Queries API GraphQL

As queries são o ponto de partida para consultar informações. Você usa uma query para solicitar informações de um banco de dados. A API GraphQL conta com as queries para buscar valores e retornar os dados solicitados em formato semelhante a um arquivo JSON.

O uso de queries possibilita solicitar e buscar dados específicos. Assim, mesmo utilizando uma query breve, você consegue receber uma resposta para a sua solicitação apenas com os dados que deseja, sem demais dados que não sejam essenciais naquele momento. O uso de queries também proporciona respostas mais rápidas, já que a API não busca uma quantidade desnecessária de dados.

As queries também melhoram a organização das suas requisições e respostas. Devido à capacidade de adaptação da GraphQL, você pode realizar diversas chamadas para a API e ainda assim receber apenas os dados que você solicitou através de um resultado no formato JSON.

Você pode usar queries para dois tipos de dados:

  • Brutos (raw), usando a API GraphQL do Real-Time Events.
  • Agregados (aggregated), usando a API GraphQL do Real-Time Metrics.

Para cada tipo de dados, você consultará com diferentes conjuntos de dados da GraphQL.

Dados brutos

Os dados brutos (raw) exibem seus registros de eventos sem qualquer processamento adicional. Eles fornecem informações detalhadas e são úteis para realizar investigações mais aprofundadas.

Veja um exemplo de uma query de dados brutos da GraphQL do Real-Time Events:

query HttpQuery {
httpEvents(
limit: 10,
filter: {
tsRange: {begin:"2023-02-14T10:10:10", end:"2023-02-15T10:10:10"}
}
orderBy: [ts_ASC]
)
{
ts
remoteAddress
requestUri
stacktrace
}
}

E a resposta à consulta:

{
"data": {
"httpEvents": [
{
"ts": "2023-08-08T10:10:10Z",
"remoteAddress": "xx.xx.xxx.xxx",
"requestUri": "/hello.index/verify",
"stacktrace": "-"
},
{
"ts": "2023-08-08T10:10:10Z",
"remoteAddress": "yyy.y.yyy.yyyy",
"requestUri": "/hello.index/welcome",
"stacktrace": "-"
},
{
"ts": "2023-08-08T10:10:10Z",
"remoteAddress": "zzz.zzz.zz.zz",
"requestUri": "/api/verify=pPrt%20",
"stacktrace": "-"
},
{
"ts": "2023-08-08T10:10:10Z",
"remoteAddress": "xyz.xy.zxy.zxy",
"requestUri": "/helloaspx.index/search",
"stacktrace": "-"
},
{
"ts": "2023-08-08T10:10:10Z",
"remoteAddress": "zyx.z.yxz.yxz",
"requestUri": "/hello.css/analysis",
"stacktrace": "-"
}
]
}
}

Para consultar dados brutos, é obrigatório informar:

  • Um intervalo de tempo para todos os conjuntos de dados, utilizando tsRange ou tsGt + tsLt.
  • Quais dados consultados devem ser exibidos. No exemplo apresentado, os campos ts, remoteAddress, requestUri e stacktrace foram usados.

Por exemplo, para realizar uma consulta NOT LIKE, você pode usar o operador Ne combinado com os operadores Like ou Ilike para filtrar entradas que correspondem a um determinado padrão. Aqui está um exemplo:

query HttpQuery {
httpEvents(
limit: 10,
filter: {
tsRange: {begin:"2023-02-14T10:10:10", end:"2023-02-15T10:10:10"},
requestUriNe: "%/verify%"
}
orderBy: [ts_ASC]
)
{
ts
remoteAddress
requestUri
stacktrace
}
}

Dados agregados

Dados agregados são um tipo de dados estruturados que foram agrupados. Eles passam por modificações para permitir um melhor processamento analítico que busca uma análise segmentada, facilitando a visualização até de grandes quantidades de dados ao longo de períodos de tempo maiores.

Veja um exemplo de uma query de dados agregados da GraphQL do Real-Time Metrics:

query HttpQuery {
httpMetrics(
limit: 10,
filter: {
tsRange: {begin:"2022-03-21T10:10:10", end:"2023-09-08T10:10:10"}
}
aggregate: {sum: requestTime}
groupBy: [ts]
orderBy: [ts_ASC]
)
{
ts
sum
}
}

E a resposta à consulta:

{
"data": {
"httpMetrics": [
{
"ts": "2022-11-29T00:00:00Z",
"sum": 0.529
},
{
"ts": "2022-11-30T00:00:00Z",
"sum": 0.044
},
{
"ts": "2023-04-11T00:00:00Z",
"sum": 50.728
},
{
"ts": "2023-04-13T00:00:00Z",
"sum": 1.683
},
{
"ts": "2023-04-21T00:00:00Z",
"sum": 0.341
},
{
"ts": "2023-05-22T00:00:00Z",
"sum": 346.432
},
{
"ts": "2023-06-05T00:00:00Z",
"sum": 23.934
},
{
"ts": "2023-06-06T00:00:00Z",
"sum": 64.223
},
{
"ts": "2023-06-07T00:00:00Z",
"sum": 12.818
},
{
"ts": "2023-06-09T00:00:00Z",
"sum": 4.073
}
]
}
}

Para consultar dados agregados, é obrigatório informar:

  • Um intervalo de tempo para todos os conjuntos de dados, utilizando tsRange ou tsGt + tsLt.
  • Os campos em que deseja agrupar as informações, utilizando groupBy.
  • Quais os dados consultados que devem ser exibidos. No exemplo apresentado, foram utilizados os campos ts e sum, em que sum representa a resposta da agregação de requestTime.

Existem também algumas opções que você deve informar através do campo aggregate na query:

IdentificadorDescrição
CountDetermina o valor total de registros que atende a uma condição específica.
SumRetorna a soma dos valores de entrada da coluna ou expressão.
MaxRetorna o valor máximo de um determinado campo de uma tabela de acordo com o critério de seleção estabelecido.
MinRetorna o valor mínimo de um determinado campo de uma tabela de acordo com o critério de seleção estabelecido.
AvgCalcula a média aritmética de um conjunto de valores contidos em um campo especificado em uma consulta.
RateUtilizado com o conjunto de dados imagesProcessed. Obtém a taxa de imagens processadas por segundo ao utilizar o Image Processor.

Veja mais informações e exemplos no guia Como realizar consultas agregando dados com a API GraphQL.

Você pode realizar uma consulta com cada uma das opções disponíveis: count, sum, max, min, avg e rate, contanto que cada opção seja utilizada apenas uma vez e cada operador faça a agregação de apenas um campo do conjunto de dados por vez. Veja o exemplo a seguir:

aggregate: {
count: rows,
sum: bytesSent,
avg: requestTime,
max: requestLength,
min: missedData,
rate: requestTime
}

Com o modelo de dados agregados, você recebe dados de acordo com um intervalo de tempo definido através de um adaptive resolver. Existem três intervalos possíveis para buscar seus dados: minuto, hora e dia.

IntervaloDescrição
MinutoUtilizado para queries com intervalo de até 3 dias.
HoraUtilizado para queries com intervalo entre 3 e 60 dias.
DiaUtilizado para queries com intervalo acima de 60 dias.

Dados financeiros

Os dados financeiros exibem informações de dois tipos: dados contabilizados e dados faturados.

Aqui está um exemplo de uma query GraphQL de dados contabilizados:

query accountedData {
accountingDetail(
limit: 10,
filter: {
periodFrom: "2022-06-01",
periodTo: "2022-06-30"
}
)
{
accounted
clientId
metricSlug
periodFrom
periodTo
}
}

E a resposta da query:

{
"data": {
"accountingDetail": [
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "load_balancer_data_transferred",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "compute_time",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 139.63,
"clientId": "8437r",
"metricSlug": "compute_time",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "compute_time",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
},
{
"accounted": 0,
"clientId": "8437r",
"metricSlug": "compute_time",
"periodFrom": "2022-06-01",
"periodTo": "2022-06-30"
}
]
}
}

Para consultar os dados financeiros, é obrigatório informar:

  • Quais dados consultados devem ser exibidos. No exemplo apresentado, os campos accounted, clientId, metricSlug, periodFrom e periodTo foram utilizados.

Diferente de uma query bruta e uma agregada, você utilizará os campos periodFrom e periodTo para filtrar um intervalo de tempo.


Operadores

Operadores são chaves especiais que permitem que você personalize sua query para realizar desde comparações lógicas básicas até mais complexas. Você pode usar eles tanto para a API GraphQL do Real-Time Metrics quanto para a API GraphQL do Real-Time Events.

Dependendo do operador que você usar, você muda a condição que está consultando e recebe resultados diferentes. Os seguintes operadores podem ser utilizados com a GraphQL:

ChaveDescriçãoOperador da GraphQL
eqConsulta dados que são uma combinação exata do valor especificado.Eq
neConsulta dados que são diferentes do valor especificado.Ne
likeConsulta dados que são semelhantes ao valor especificado, considerando maiúsculas e minúsculas.Like
ilikeConsulta dados que são semelhantes ao valor especificado, sem considerar maiúsculas e minúsculas.Ilike
is_nullConsulta dados que são nulos ou não são nulos em relação ao valor especificado, usando true ou false.IsNull
inConsulta dados que são parte de uma determinada lista de acordo com o valor especificado.In
not_inConsulta dados que não estão contidos em uma dada lista de acordo com o valor especificado.NotIn
ltConsulta dados com valores menores do que o valor especificado.Lt
lteConsulta dados com valores menores ou iguais ao valor especificado.Lte
gtConsulta dados com valores maiores do que o valor especificado.Gt
gteConsulta dados com valores maiores ou iguais ao valor especificado.Gte
rangeConsulta dados que são parte de uma determinada faixa de valores de acordo com os valores especificados.Range

Se você usar os operadores Like e Ilike, você também deve passar o identificador % dentro do campo na posição que desejar:

Posição do identificadorDescriçãoExemplo
FimQualquer string que começa com os caracteres.”Braz%“
InícioQualquer string que termina com os caracteres.”%ao Paulo”
Fim e inícioQualquer string que contém os caracteres.”%ttp%“

Veja exemplos de alguns campos com operadores:

OperadorExemploDescrição
EqupstreamCacheStatusEq: “HIT”Busca todos os dados que têm uma combinação exata com o valor HIT no campo upstreamCacheStatus.
NegeolocCountryNameNe: “Brazil”Busca todos os dados que não contêm Brazil no campo geolocCountryName.
LikehostLike: “%mysite.com%“Busca todos os dados de hosts com o padrão mysite.com, considerando maiúsculas e minúsculas
IlikehostIlike: “%mysite.com%“Busca todos os dados de hosts com o padrão mysite.com, sem considerar maiúsculas e minúsculas

Dependendo do tipo de campo de um conjunto de dados que você está consultando, você poderá usar operadores diferentes:

Tipo de campoPossíveis operadores
StringEq, Ne, Like, Ilike, In, NotIn, IsNull
Integer, Float, DateTimeEq, Lt, Lte, Gt, Gte, Ne, In, NotIn, IsNull, Range

Contribuidores