# 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](/pt-br/documentacao/devtools/graphql-api/recursos/#conjuntos-de-dados). :::tip[dica] Confira os [limites da API GraphQL](/pt-br/documentacao/devtools/graphql-api/limites/) 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: ```graphql query HttpQuery { workloadEvents( 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: ```json { "data": { "workloadEvents": [ { "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 `not` combinado com os operadores `Like` ou `Ilike` para filtrar entradas que correspondem a um determinado padrão. Aqui está um exemplo: ```graphql query HttpQuery { workloadEvents( limit: 10, filter: { tsRange: {begin:"2023-02-14T10:10:10", end:"2023-02-15T10:10:10"}, not: { requestUriLike: "%/verify%" } } orderBy: [ts_ASC] ) { ts remoteAddress requestUri stacktrace } } ``` :::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](/pt-br/documentacao/produtos/guias/graphql-query-top-x/). ::: ### 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: ```graphql 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: ```json { "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](/pt-br/documentacao/produtos/guias/graphql-dados-agregados/). 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: ```graphql 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: ```graphql query accountedData { accountingDetail( limit: 10, filter: { periodFrom: "2022-06-01", periodTo: "2022-06-30" } ) { accounted clientId metricSlug periodFrom periodTo } } ``` E a resposta da query: ```json { "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. ## Dados de uso Os dados de uso exibem informações contabilizadas. Aqui está um exemplo de dados de uso do Image Processor usando uma query da API GraphQL de Consumption: ```graphql query { workloadConsumptionMetrics( filter: { tsRange: { begin: "2025-02-01T00:00:00", end: "2025-03-01T00:00:00", } productId: 1441110021 metricName: "images_processed" } aggregate: { sum: accounted } limit: 10000 groupBy: [clientId, workloadId, productId, metricName] ) { clientId workloadId productId metricName total: sum } } ``` E a resposta da query: ```json { "data": { "workloadConsumptionMetrics": [ { "clientId": "0000z", "workloadId": 4829103746, "productId": 1441110021, "metricName": "images_processed", "total": 32 }, { "clientId": "0000z", "workloadId": 1938475620, "productId": 1441110021, "metricName": "images_processed", "total": 19478 }, { "clientId": "0000z", "workloadId": 7584931026, "productId": 1441110021, "metricName": "images_processed", "total": 299612 }, { "clientId": "0000z", "workloadId": 6203849175, "productId": 1441110021, "metricName": "images_processed", "total": 1432 }, { "clientId": "0000z", "workloadId": 3948571023, "productId": 1441110021, "metricName": "images_processed", "total": 268675 } ] } } ``` Para consultar os dados de uso, é obrigatório informar quais dados consultados devem ser exibidos. No exemplo apresentado, foram utilizados `accounted`, `clientId`, `workloadId`, `productId` e `metricName`. --- ## 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](/pt-br/documentacao/devtools/graphql-api/recursos/#conjuntos-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` |