Skip to content

Latest commit

 

History

History
383 lines (326 loc) · 14.2 KB

queries-gql.mdx

File metadata and controls

383 lines (326 loc) · 14.2 KB
Raw
title description meta_tags namespace permalink menu_namespace
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.
graphql, api, azion, query
documentation_graphql_queries
/documentacao/devtools/graphql-api/queries/
graphqlMenu

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.

:::tip[dica] Confira os limites da API GraphQL para garantir que sua query é válida. :::

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.

:::tip[dica] Você também pode utilizar o recurso Top X query com a API GraphQL do Real-Time Events. Ela tem a finalidade de visualizar o uso de recursos e ferramentas e ter uma visão detalhada sobre determinadas condições que são mais ou menos usadas. Por exemplo, você pode consultar os “Top 10 Hosts” ou os “Top 10 Status Codes”.

Veja mais sobre Como selecionar Top X queries com a GraphQL API. :::

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

import ContributorList from '~/components/ContributorList.astro'

Contribuidores Contributor