Queries API GraphQL
Explore como utilizar a API GraphQL para consultas eficientes em tempo real, incluindo dados brutos e agregados, e descubra os operadores disponíveis.
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:
E a resposta à consulta:
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:
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:
E a resposta à consulta:
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:
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:
E a resposta da query:
Para consultar os dados financeiros, é obrigatório informar:
- Quais dados consultados devem ser exibidos. No exemplo apresentado, os campos
accounted,clientId,metricSlug,periodFromeperiodToforam 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:
E a resposta da query:
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 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 |