# Datasets e argumentos de query Um dataset é o conjunto de registros que uma query da GraphQL API lê, nomeado como o campo de nível superior da query. Cada um dos cinco endpoints atende os seus próprios datasets. Todo dataset aceita os mesmos argumentos para filtrar, agregar, agrupar, ordenar e paginar os seus registros, e a maioria dos datasets de `metrics` também aceita `resample`. --- ## Datasets A tabela lista os datasets de cada endpoint. A coluna Endpoint indica o segmento da URL: um dataset de `metrics` vai para `https://api.azion.com/v4/metrics/graphql`, e o mesmo padrão vale para `events`, `billing`, `accounting` e `consumption`. Envie cada query em uma requisição `POST` com o header `Authorization: Token [TOKEN VALUE]`: | Dataset | Endpoint | Dados | | ---------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workloadMetrics` | `metrics` | Requisições que [Applications](/pt-br/documentacao/plataforma/applications/) e [Firewall](/pt-br/documentacao/plataforma/firewall/) processaram, agregadas em buckets de tempo | | `workloadBreakdownMetrics` | `metrics` | Requisições por endereço do cliente, path, user agent, referer e país, agregadas por hora, com contagens de [requisições bloqueadas e de ameaças](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-dados-httpbreakdownmetrics-com-graphql/) | | `functionsMetrics` | `metrics` | Invocações e tempo de computação de [Functions](/pt-br/documentacao/plataforma/functions/) | | `dnsQueriesMetrics` | `metrics` | Consultas que o [Edge DNS](/pt-br/documentacao/plataforma/edge-dns/) respondeu, por zona e tipo de registro | | `idnsQueriesMetrics` | `metrics` | As mesmas linhas de `dnsQueriesMetrics` | | `imagesProcessedMetrics` | `metrics` | Imagens que o [Image Processor](/pt-br/documentacao/plataforma/applications/image-processor/configuracoes/) processou | | `tieredCacheMetrics` | `metrics` | Requisições que o [Tiered Cache](/pt-br/documentacao/plataforma/applications/cache/tiered-cache/) processou | | `l2CacheMetrics` | `metrics` | Os mesmos campos de `tieredCacheMetrics` | | `dataStreamedMetrics` | `metrics` | Dados que o [Data Stream](/pt-br/documentacao/plataforma/data-stream/) enviou para os seus endpoints | | `connectedUsersMetrics` | `metrics` | [Usuários conectados às suas aplicações](/pt-br/documentacao/guias/plataforma/observabilidade/query-dados-connected-users-com-graphql/) por meio do Live Ingest, por minuto | | `botManagerMetrics` | `metrics` | [Requisições que o Bot Manager avaliou](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-dados-bot-manager-com-graphql/) e as ações que ele executou; exige uma assinatura do Bot Manager | | `botManagerBreakdownMetrics` | `metrics` | [As URLs que bots maliciosos mais requisitam](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-dados-bot-manager-breakdown-com-graphql/), a partir dos dados do Bot Manager; exige uma assinatura do Bot Manager | | `workloadEvents` | `events` | Um registro por requisição que Applications e Firewall processaram | | `functionEvents` | `events` | Um registro por execução de Functions | | `functionConsoleEvents` | `events` | Linhas que as functions executadas no [Azion Runtime](/pt-br/documentacao/devtools/runtime/) escrevem no console, com o seu nível | | `dnsQueriesEvents` | `events` | Um registro por consulta que o Edge DNS respondeu, com o seu código de resposta | | `idnsQueriesEvents` | `events` | Os mesmos campos de `dnsQueriesEvents` | | `imagesProcessedEvents` | `events` | Um registro por imagem que o Image Processor processou | | `tieredCacheEvents` | `events` | Um registro por requisição que o Tiered Cache processou | | `l2CacheEvents` | `events` | Os mesmos campos de `tieredCacheEvents` | | `dataStreamedEvents` | `events` | Entregas que o Data Stream enviou para os seus endpoints, com a URL do endpoint e o código de status | | `activityHistoryEvents` | `events` | Atividade da conta no Azion Console, conforme o [Activity History](/pt-br/documentacao/fundamentos/activity-history/) a registra; mantida por 2 anos | | `telemetryDeviceInfoEvents` | `events` | Detalhes de hardware e software dos dispositivos que o Azion Mobile SDK registra | | `telemetrySensorsEvents` | `events` | Leituras dos sensores dos dispositivos que o Azion Mobile SDK registra, como dados de touchscreen e giroscópio | | `balanceFinancialEntry` | `billing` | Lançamentos financeiros por tipo, com os seus valores | | `paymentsClientDebt` | `billing` | Débitos e pagamentos da conta, com os seus valores | | `billDetail` | `billing` | Valores faturados por produto, métrica e região em cada período de cobrança | | `accountingDetail` | `accounting` | Valores contabilizados por produto, métrica e região | | `workloadConsumptionMetrics` | `consumption` | Uso contabilizado por workload, produto e métrica | Os datasets do endpoint `events` retornam registros brutos, um por evento, como mostra [Dados brutos](/pt-br/documentacao/devtools/graphql/queries/#dados-brutos). Os datasets do endpoint `metrics` retornam dados agrupados em buckets de tempo, como mostra [Dados agregados](/pt-br/documentacao/devtools/graphql/queries/#dados-agregados). Os campos de cada dataset estão em [Campos do Real-Time Metrics](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-metrics/), [Campos do Real-Time Events](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-events/), [Campos de Billing](/pt-br/documentacao/devtools/graphql/campos-gql-billing/), [Campos de Accounting](/pt-br/documentacao/devtools/graphql/campos-gql-accounting/) e [Campos de Consumption](/pt-br/documentacao/devtools/graphql/campos-gql-consumption/). Uma query de introspecção retorna as mesmas informações a partir do próprio endpoint: todo dataset e todo campo que ele atende, com as suas descrições e tipos. Para mais informações, consulte [Consulte os metadados do schema GraphQL](/pt-br/documentacao/guias/plataforma/observabilidade/graphql-metadados/). ### Datasets descontinuados O schema marca como descontinuados os nomes de dataset abaixo. Um dataset descontinuado aceita os mesmos campos do seu substituto e retorna as mesmas linhas, então mover uma query para o substituto muda apenas o nome do dataset: | Dataset descontinuado | Use no lugar | | ----------------------- | -------------------------- | | `httpMetrics` | `workloadMetrics` | | `httpBreakdownMetrics` | `workloadBreakdownMetrics` | | `edgeFunctionsMetrics` | `functionsMetrics` | | `edgeDnsQueriesMetrics` | `dnsQueriesMetrics` | | `httpEvents` | `workloadEvents` | | `edgeFunctionsEvents` | `functionEvents` | | `cellsConsoleEvents` | `functionConsoleEvents` | | `edgeDnsQueriesEvents` | `dnsQueriesEvents` | --- ## Argumentos de query Todo dataset da GraphQL API, em todo endpoint, aceita os seis primeiros argumentos abaixo, e `resample` se aplica apenas a datasets de `metrics`. Todos são opcionais, mas uma query em um dataset de `metrics`, `events` ou `consumption` precisa de uma janela de tempo dentro de `filter`: | Argumento | Tipo | Padrão | O que faz | | ----------- | ---------------------------- | ------ | ----------------------------------------------------------------------------------------- | | `filter` | Input object | — | Seleciona os registros a ler: a janela de tempo e quaisquer condições de campo. | | `aggregate` | Input object | — | Aplica funções, como `count` ou `sum`, a um campo. | | `groupBy` | Lista de campos | — | Retorna uma linha por combinação dos campos listados. | | `orderBy` | Lista de chaves de ordenação | — | Ordena as linhas por campos ou por saídas de funções. | | `offset` | `Int` | `0` | Define quantas linhas a API pula antes da primeira linha que retorna. | | `limit` | `Int` | `10` | Define quantas linhas a API retorna, de 0 a 10.000. | | `resample` | Input object | — | Combina as linhas em um número definido de pontos no tempo. Apenas datasets de `metrics`. | As funções de `aggregate`, e o que `groupBy` faz com elas, estão em [Queries](/pt-br/documentacao/devtools/graphql/queries/#funcoes-de-agregacao). --- ## Filtragem O argumento `filter` seleciona os registros que uma query da GraphQL API lê e aceita qualquer campo do dataset. Cada chave nomeia um campo e, por meio de um sufixo, um operador: `statusGte: 400` mantém os registros cujo `status` é 400 ou maior. Uma chave sem sufixo compara por igualdade, então `host: "www.example.com"` e `hostEq: "www.example.com"` retornam os mesmos registros. Esta query retorna os buckets de tempo de uma janela de sete dias que contêm requisições do Brasil: ```graphql query HttpQuery { workloadMetrics( limit: 10 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} geolocCountryName: "Brazil" } ) { ts geolocCountryName } } ``` A resposta contém 10 linhas, cortada aqui após a terceira: ```json { "data": { "workloadMetrics": [ { "ts": "2026-09-28T22:00:00Z", "geolocCountryName": "Brazil" }, { "ts": "2026-09-28T22:00:00Z", "geolocCountryName": "Brazil" }, { "ts": "2026-09-28T23:00:00Z", "geolocCountryName": "Brazil" }, … ] } } ``` ### Operadores Os operadores que um campo aceita dependem do seu tipo. Um campo de string contém texto, como `host`. Um campo numérico contém um valor bruto, como `status` ou `requestTime`. Um campo calculado contém um valor que a API calcula, como `requestsTotal` ou `dataTransferredTotal`: | Operador | Corresponde a | Aplica-se a | Exemplo | | -------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------- | | `Eq` | Valores iguais ao valor informado | Campos de string, numéricos, calculados e `ts` | `hostEq: "www.example.com"` | | `Ne` | Valores diferentes do valor informado | Campos de string, numéricos, calculados e `ts` | `hostNe: "www.example.com"` | | `Like` | Valores que correspondem a um padrão, diferenciando maiúsculas e minúsculas | Campos de string | `hostLike: "%example%"` | | `Ilike` | Valores que correspondem a um padrão, sem diferenciar maiúsculas e minúsculas | Campos de string | `hostIlike: "%EXAMPLE%"` | | `In` | Valores em uma lista | Campos de string, numéricos e `ts`, e alguns campos calculados | `statusIn: [403, 404]` | | `NotIn` | Valores fora de uma lista | Campos de string, numéricos e `ts` | `statusNotIn: [200, 304]` | | `IsNull` | Valores vazios com `true`, valores presentes com `false` | Campos de string e numéricos | `hostIsNull: false` | | `Lt` | Valores menores que o valor informado | Campos numéricos, calculados e `ts` | `statusLt: 300` | | `Lte` | Valores menores ou iguais ao valor informado | Campos numéricos e `ts` | `statusLte: 300` | | `Gt` | Valores maiores que o valor informado | Campos numéricos, calculados e `ts` | `statusGt: 399` | | `Gte` | Valores maiores ou iguais ao valor informado | Campos numéricos e `ts` | `statusGte: 400` | | `Range` | Valores entre `begin` e `end` | Campos numéricos, calculados e `ts` | `statusRange: {begin: 400, end: 499}` | Um operador que o campo não aceita retorna `400`. Por exemplo, `requestsTotalLte` em `workloadMetrics` retorna `Unknown field.`, porque campos calculados não aceitam `Lte` nem `Gte`. Um padrão de `Like` ou `Ilike` usa `%` para qualquer sequência de caracteres. `"Braz%"` corresponde a valores que começam com `Braz`, `"%ao Paulo"` corresponde a valores que terminam com `ao Paulo` e `"%ttp%"` corresponde a valores que contêm `ttp`. Maiúsculas e minúsculas no padrão importam apenas com `Like`: `hostLike: "%EXAMPLE%"` não corresponde a `www.example.com`, e `hostIlike: "%EXAMPLE%"` corresponde. Os datasets dos endpoints `billing` e `accounting` não têm campo `ts`. Os seus filtros aceitam o campo sem sufixo, `Eq`, `In` e `Range`, em campos como `periodFrom`, `periodTo` e `created`. ### Condições combinadas As chaves dentro de um mesmo objeto `filter` se aplicam todas juntas. Para combinar condições de forma explícita, `and` e `or` recebem uma lista de filtros, e `not` recebe um filtro: - `and` mantém os registros que correspondem a todos os filtros da lista, como `and: [{ hostEq: "www.example.com" }, { statusGte: 400 }]`. - `or` mantém os registros que correspondem a pelo menos um filtro da lista. - `not` exclui os registros que correspondem ao seu filtro, como `not: { requestUriLike: "%/_astro/%" }`. Esta query conta, por status, as requisições de uma janela de sete dias cujo status é `304` ou fica entre `200` e `299`: ```graphql query { workloadEvents( limit: 10 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} or: [{ status: 304 }, { statusRange: {begin: 200, end: 299} }] } aggregate: { count: rows } groupBy: [status] orderBy: [count_DESC] ) { status count } } ``` A resposta aparece cortada após a terceira linha: ```json { "data": { "workloadEvents": [ { "status": 200, "count": 2931 }, { "status": 304, "count": 1093 }, { "status": 204, "count": 129 }, … ] } } ``` O schema tipa `or` como uma lista. A API também aceita `or` como um único objeto, por exemplo `or: { status: 304, statusRange: {begin: 200, end: 299} }`, e trata as suas chaves como alternativas. ### Janela de tempo Uma query em um dataset de `metrics`, `events` ou `consumption` define a sua janela de tempo dentro de `filter`. `tsRange` recebe um `begin` e um `end`. `tsGt` e `tsLt` definem um limite cada, e `tsGt` sozinho é aceito. Sem nenhum deles, a API retorna `400` com `To execute queries it is mandatory to provide the desired time interval.` Os dois limites de uma janela usam o mesmo fuso horário. Um limite com `Z` ao lado de um limite sem ele retorna `400` com `The start and end dates must have the same timezone.` Limites com o mesmo offset, como `-03:00`, são aceitos, e a API os converte para UTC. Uma janela cujo `begin` vem depois do seu `end` retorna uma lista vazia. Esta query soma as requisições de uma janela de uma hora por bucket de tempo, com `tsGt` e `tsLt`: ```graphql query { workloadMetrics( limit: 3 filter: { tsGt: "2026-10-03T13:00:00", tsLt: "2026-10-03T14:00:00" } aggregate: { sum: requests } groupBy: [ts] orderBy: [ts_ASC] ) { ts sum } } ``` A resposta contém apenas os buckets da janela que contêm requisições: ```json { "data": { "workloadMetrics": [ { "ts": "2026-10-03T13:16:00Z", "sum": 1 }, { "ts": "2026-10-03T13:34:00Z", "sum": 1 } ] } } ``` Os datasets de `billing` e `accounting` filtram por período, como mostra [Queries](/pt-br/documentacao/devtools/graphql/queries/#dados-financeiros). --- ## Ordenação O argumento `orderBy` ordena as linhas que uma query da GraphQL API retorna. Ele recebe uma lista de chaves, e cada chave é um campo ou uma saída de função seguida de `_ASC`, do menor para o maior, ou `_DESC`, do maior para o menor. Por exemplo, `orderBy: [avg_ASC]` coloca a menor média primeiro. Uma query pode listar várias chaves, como `orderBy: [ts_ASC, requestId_ASC]`. Uma chave sem direção retorna `400`. Para `orderBy: [host]` em `workloadMetrics`, a mensagem termina com `Expected type "WorkloadMetricsOrderByFields", found host.` Esta query soma os bytes enviados por host em uma janela de sete dias, do maior para o menor: ```graphql query SumBytesSentByHost { workloadMetrics( limit: 1000 filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } aggregate: {sum: bytesSent} groupBy: [host] orderBy: [sum_DESC] ) { host sum } } ``` A resposta aparece cortada após a terceira linha: ```json { "data": { "workloadMetrics": [ { "host": "www.example.com", "sum": 77554923 }, { "host": "shop.example.com", "sum": 47900834 }, { "host": "api.example.com", "sum": 19165846 }, … ] } } ``` --- ## Paginação Os argumentos `offset` e `limit` paginam as linhas de uma query da GraphQL API. `offset` define quantas linhas a API pula, `0` por padrão. `limit` define quantas linhas ela retorna, `10` por padrão e no máximo 10.000. Por exemplo, `offset: 15` com `limit: 30` retorna as linhas 16 a 45. Um `limit` fora do intervalo de 0 a 10.000 retorna `400`, como descreve [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites/). Esta query retorna as linhas 6 a 10 das requisições de uma janela de 24 horas, ordenadas por tempo e depois por ID da requisição: ```graphql query { workloadEvents(offset: 5, limit: 5, filter: { tsRange: {begin: "2026-10-02T14:00:00", end: "2026-10-03T14:00:00"} }, orderBy: [ts_ASC, requestId_ASC]) { ts requestId } } ``` A resposta contém cinco linhas, cortada aqui após a terceira: ```json { "data": { "workloadEvents": [ { "ts": "2026-10-02T16:19:56Z", "requestId": "0123456789abcdef0123456789abcd01" }, { "ts": "2026-10-02T16:19:56Z", "requestId": "0123456789abcdef0123456789abcd02" }, { "ts": "2026-10-02T16:19:56Z", "requestId": "0123456789abcdef0123456789abcd03" }, … ] } } ``` A mesma query com `limit: 10` e sem `offset` retorna as linhas 1 a 10, e as suas últimas cinco linhas são as cinco linhas acima. Um `offset` além da última linha retorna uma lista vazia. Cada página é uma query separada. Quando os dados mudam entre duas queries, linhas podem passar de uma página para a seguinte, então uma página pode deixar de trazer uma linha ou repetir uma. A query acima ordena por `ts` e depois por `requestId`, então linhas com o mesmo timestamp voltam na mesma ordem em todas as páginas. --- ## Reamostragem O argumento `resample` combina as linhas de um dataset de `metrics` em menos pontos no tempo, para caber em um gráfico. Ele complementa `limit`: `limit` limita as linhas, e `resample` define em quantos pontos a janela de tempo é dividida. Ele recebe duas chaves: - `function`, obrigatória, define como os pontos dentro de cada intervalo se combinam. - `points`, um `Int`, define o número de intervalos a buscar. `function` aceita um de quatro valores: - `sum` retorna o total dos pontos no intervalo. - `mean` retorna a média deles. - `max` retorna o maior ponto. - `min` retorna o menor ponto. Todo dataset de `metrics` aceita `resample`, exceto `connectedUsersMetrics` e `objectStorageMetrics`. Em um dataset de `events`, o argumento retorna `400` com `Unknown argument "resample" on field "workloadEvents" of type "Query".` Uma query com resample também precisa de `ts` em `groupBy`, com todos os campos de `groupBy` selecionados. Sem eles, a API retorna `400` com uma mensagem que começa com `Query syntax error. In resample queries, you must provide the timestamp (ts) field in the group_by parameter`. A API divide a janela de tempo por `points` e arredonda o intervalo para baixo, até um número inteiro de buckets de tempo, então a resposta pode conter mais pontos que `points`. Por exemplo, uma janela de sete dias com `points: 10` retorna 11 pontos, com 16 horas de distância entre eles, porque 168 horas divididas por 10 dão 16,8 horas. Um intervalo sem dados ainda retorna um ponto, com valor zero. Com `points: 100`, a mesma janela retorna um ponto por hora, incluindo as horas vazias, enquanto a mesma query sem `resample` retorna apenas as horas que contêm dados. Esta query calcula a média das contagens de requisições por hora de uma janela de sete dias em cerca de dez pontos: ```graphql query { workloadMetrics( limit: 10000 resample: { function: mean, points: 10 } filter: { tsRange: {begin: "2026-09-26T14:00:00", end: "2026-10-03T14:00:00"} } aggregate: { sum: requests } groupBy: [ts] orderBy: [ts_ASC] ) { ts sum } } ``` A resposta contém 11 linhas, com 16 horas de distância entre elas, cortada aqui após a terceira: ```json { "data": { "workloadMetrics": [ { "ts": "2026-09-26T16:00:00Z", "sum": 2.0 }, { "ts": "2026-09-27T08:00:00Z", "sum": 2.125 }, { "ts": "2026-09-28T00:00:00Z", "sum": 3.6875 }, … ] } } ``` --- ## Recursos relacionados - [Queries](/pt-br/documentacao/devtools/graphql/queries.md): O formato de query para dados brutos, agregados, financeiros e de uso, com as funções de agregação. - [Campos do Real-Time Metrics](/pt-br/documentacao/devtools/graphql/campos-gql-real-time-metrics.md): Os campos de todo dataset de metrics, pelos quais você filtra, agrupa e ordena. - [Limites da GraphQL API](/pt-br/documentacao/devtools/graphql/limites.md): Os limites de linhas, campos e janela de tempo dentro dos quais uma query é executada. - [Respostas de erro](/pt-br/documentacao/devtools/graphql/mensagens-erro.md): Os códigos de status e as mensagens que uma query recusada retorna, e o que causa cada um.