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.

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:

Identificador	Descrição
Count	Determina o valor total de registros que atende a uma condição específica.
Sum	Retorna a soma dos valores de entrada da coluna ou expressão.
Max	Retorna o valor máximo de um determinado campo de uma tabela de acordo com o critério de seleção estabelecido.
Min	Retorna o valor mínimo de um determinado campo de uma tabela de acordo com o critério de seleção estabelecido.
Avg	Calcula a média aritmética de um conjunto de valores contidos em um campo especificado em uma consulta.
Rate	Utilizado 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.

Intervalo	Descrição
Minuto	Utilizado para queries com intervalo de até 3 dias.
Hora	Utilizado para queries com intervalo entre 3 e 60 dias.
Dia	Utilizado 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:

Chave	Descrição	Operador da GraphQL
eq	Consulta dados que são uma combinação exata do valor especificado.	`Eq`
ne	Consulta dados que são diferentes do valor especificado.	`Ne`
like	Consulta dados que são semelhantes ao valor especificado, considerando maiúsculas e minúsculas.	`Like`
ilike	Consulta dados que são semelhantes ao valor especificado, sem considerar maiúsculas e minúsculas.	`Ilike`
is_null	Consulta dados que são nulos ou não são nulos em relação ao valor especificado, usando `true` ou `false`.	`IsNull`
in	Consulta dados que são parte de uma determinada lista de acordo com o valor especificado.	`In`
not_in	Consulta dados que não estão contidos em uma dada lista de acordo com o valor especificado.	`NotIn`
lt	Consulta dados com valores menores do que o valor especificado.	`Lt`
lte	Consulta dados com valores menores ou iguais ao valor especificado.	`Lte`
gt	Consulta dados com valores maiores do que o valor especificado.	`Gt`
gte	Consulta dados com valores maiores ou iguais ao valor especificado.	`Gte`
range	Consulta 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 identificador	Descrição	Exemplo
Fim	Qualquer string que começa com os caracteres.	”Braz%“
Início	Qualquer string que termina com os caracteres.	”%ao Paulo”
Fim e início	Qualquer string que contém os caracteres.	”%ttp%“

Veja exemplos de alguns campos com operadores:

Operador	Exemplo	Descrição
Eq	upstreamCacheStatusEq: “HIT”	Busca todos os dados que têm uma combinação exata com o valor `HIT` no campo upstreamCacheStatus.
Ne	geolocCountryNameNe: “Brazil”	Busca todos os dados que não contêm `Brazil` no campo geolocCountryName.
Like	hostLike: “%mysite.com%“	Busca todos os dados de hosts com o padrão `mysite.com`, considerando maiúsculas e minúsculas
Ilike	hostIlike: “%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 campo	Possíveis operadores
String	`Eq`, `Ne`, `Like`, `Ilike`, `In`, `NotIn`, `IsNull`
Integer, Float, DateTime	`Eq`, `Lt`, `Lte`, `Gt`, `Gte`, `Ne`, `In`, `NotIn`, `IsNull`, `Range`

Contribuidores