As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Gravar consultas de expressão **** Este tópico de documentação foi desenvolvido para espaços de trabalho do Grafana compatíveis com o **Grafana versão 9.x**. Para espaços de trabalho do Grafana compatíveis com o Grafana versão 10.x, consulte [Trabalhar no Grafana versão 10](using-grafana-v10.md). Para espaços de trabalho do Grafana compatíveis com o Grafana versão 8.x, consulte [Trabalhar no Grafana versão 8](using-grafana-v8.md). As expressões do servidor permitem que você manipule os dados retornados de consultas com operações matemáticas e outras. As expressões criam novos dados e não manipulam os dados retornados pelas fontes de dados. ## Sobre expressões As expressões do servidor permitem que você manipule dados retornados de consultas com operações matemáticas e outras. As expressões criam novos dados e não manipulam os dados retornados pelas fontes de dados, exceto por uma pequena reestruturação de dados para tornar os dados uma entrada aceitável para expressões. **Usar expressões** As expressões são usadas principalmente pelo [Grafana Alerting](v9-alerts.md). O processamento é feito no servidor para que as expressões possam operar sem uma sessão do navegador. No entanto, as expressões também podem ser usadas com fontes de dados de backend e visualização. **nota** As expressões não funcionam com alertas legados do dashboard. As expressões têm como objetivo aumentar as fontes de dados, permitindo que consultas de diferentes fontes de dados sejam combinadas ou fornecendo operações indisponíveis em uma fonte de dados. **nota** Quando possível, você deve fazer o processamento de dados dentro da fonte de dados. Copiar dados do armazenamento para o servidor Grafana para processamento é ineficiente, portanto, as expressões são direcionadas ao processamento leve de dados. As expressões funcionam com consultas de fontes de dados que retornam dados numéricos ou de séries temporais. Eles também operam com [dados multidimensionais](getting-started-grafanaui.md#time-series-dimensions). Por exemplo, uma consulta que retorna várias séries, em que cada série é identificada por rótulos ou tags. Uma expressão individual usa uma ou mais consultas ou outras expressões como entrada e adiciona dados ao resultado. Cada expressão ou consulta individual é representada por uma variável que é um identificador nomeado conhecido como RefID (por exemplo, a letra padrão `A` ou `B`). Para referenciar a saída de uma expressão individual ou de uma consulta de fonte de dados em outra expressão, esse identificador é usado como uma variável. **Tipos de expressões** As expressões funcionam com dois tipos de dados. + Uma coleção de séries temporais. + Uma coleção de números, em que cada número é um item. Cada coleção é retornada de uma única consulta ou expressão de fonte de dados e é representada pelo RefID. Cada coleção é um conjunto, em que cada item do conjunto é identificado exclusivamente por suas dimensões, que são armazenadas como [rótulos](getting-started-grafanaui.md#labels) ou pares de chave/valor. **Consultas de fonte de dados** As expressões do servidor só são compatíveis com consultas de fontes de dados para fontes de dados de backend. Geralmente, presume-se que os dados sejam rotulados como dados de séries temporais. No futuro, pretendemos adicionar uma declaração dos dados do tipo de retorno da consulta (número ou série temporal) para que as expressões possam lidar melhor com os erros. As consultas à fonte de dados, quando usadas com expressões, são executadas pelo mecanismo de expressão. Ao fazer isso, ele reestrutura os dados para serem uma série temporal ou um número por quadro de dados. Então, por exemplo, se estiver usando uma fonte de dados que retorna várias séries em um quadro na exibição de tabela, você perceberá que ela parece diferente quando executada com expressões. Atualmente, o único formato de série não temporal (número) compatível com o uso de quadros de dados é o que você tem uma resposta de tabela que retorna um quadro de dados sem hora, colunas de strings e uma coluna numérica: | Loc | Host | Avg\$1CPU | | --- | --- | --- | | MIA | A | 1 | | NYC | B | 2 | O exemplo acima produzirá um número que funciona com expressões. As colunas de strings tornam-se rótulos e a coluna numérica o valor correspondente. Por exemplo, `{"Loc": "MIA", "Host": "A"}` com um valor de 1. **Operações** Você pode usar as seguintes operações em expressões: matemática, reduzir e reamostrar. **Math** Matemática é para fórmulas matemáticas de formato livre em séries temporais ou dados numéricos. As operações matemáticas usam números e séries temporais como entrada e os alteram para outros números e séries temporais. Os dados de outras consultas ou expressões são referenciados com o RefID prefixado com um cifrão, por exemplo, `$A`. Se a variável tiver espaços no nome, você poderá usar uma sintaxe entre chaves, como `${my variable}`. As constantes numéricas podem estar em decimal (`2.24`), octal (com um zero à esquerda, como `072`) ou hexadecimal (com um 0x à esquerda, como `0x2A`). Exponenciais e sinais também são compatíveis (por exemplo, `-0.8e-2`). **Operadores** Os operadores aritméticos (`+`, binários e unários `-`, `*`, `/`, `%`, expoente `**`), relacionais (`<`, `>`, `==`, `!=`, `>=`, `<=`) e lógicos (`&&`, `||` e unários `!`) são compatíveis. A forma como a operação se comporta com os dados depende se são dados numéricos ou de séries temporais. Com operações binárias, como `$A + $B` ou `$A || $B`, o operador é aplicado das seguintes maneiras, dependendo do tipo de dados: + Se `$A` e `$B` forem um número, a operação será executada entre os dois números. + Se uma variável for um número e a outra variável for uma série temporal, a operação entre o valor de cada ponto na série temporal e o número será executada. + Se `$A` e `$B` forem dados de séries temporais, a operação entre cada valor nas duas séries será executada para cada carimbo de data e hora existente tanto em `$A` quanto em `$B`. A operação `Resample` pode ser usada para alinhar carimbos de data e hora. Resumo: + Número OP número = número + Número OP série = série + Série OP série = série Como as expressões funcionam com várias séries ou números representados por uma única variável, as operações binárias também realizam uma união (junção) entre as duas variáveis. Isso é feito com base nos rótulos de identificação associados a cada série ou número individual. Portanto, se você tiver números com rótulos como `{host=web01}` em `$A` e outro número em `$B` com os mesmos rótulos, a operação será executada entre esses dois itens em cada variável, e o resultado compartilhará os mesmos rótulos. As regras para o comportamento dessa união são as seguintes: + Um item sem rótulos se juntará a qualquer coisa. + Se `$A` e `$B` contiverem, cada um, apenas um item (uma série ou um número), eles se unirão. + Se os rótulos forem matematicamente exatos, eles se juntarão. + Se os rótulos forem um subconjunto um do outro, por exemplo, se um item em `$A` for rotulado `{host=A,dc=MIA}` e um item em `$B` for rotulado `{host=A}`, eles serão unidos. + Se dentro de uma variável, como `$A`, houver chaves de tag diferentes para cada item, o comportamento da junção será indefinido. Os operadores lógicos e relacionais retornam 0 para false 1 para true. **Funções matemáticas** Embora a maioria das funções exista nas próprias operações de expressão, a operação matemática tem algumas funções semelhantes aos operadores ou símbolos matemáticos. Quando as funções podem receber números ou séries, o mesmo tipo do argumento será retornado. Quando é uma série, a operação é executada para o valor de cada ponto na série. *abs* abs retorna o valor absoluto de seu argumento, que pode ser um número ou uma série. Por exemplo, `abs(-1)` ou `abs($A)`. *is\$1inf* is\$1inf pega um número ou uma série e retorna `1` para valores `Inf` (negativos ou positivos) e `0` para outros valores. Por exemplo, `is_inf($A)`. **nota** Se você precisar verificar especificamente o infinito negativo, por exemplo, você pode fazer uma comparação como `$A == infn()`. *is\$1nan* is\$1nan pega um número ou uma série e retorna `1` para valores `NaN` e `0` para outros valores. Por exemplo, `is_nan($A)`. Essa função existe porque `NaN` não é igual a `NaN`. *is\$1null* is\$1null pega um número ou uma série e retorna `1` para valores `null` e `0` para outros valores. Por exemplo, `is_null($A)`. *is\$1number* is\$1number pega um número ou uma série e retorna `1` para todos os valores de números reais e `0` para outros valores (que são `null`, `Inf+`, `Inf-` e `NaN`). Por exemplo, `is_number($A)`. *log* Log retorna o logaritmo natural de seu argumento, que pode ser um número ou uma série. Se o valor for menor que 0, `NaN` será retornado. Por exemplo, `log(-1)` ou `log($A)`. *inf, infn, nan e null* Todas as funções inf, infn, nan e null retornam um único valor do nome. Eles existem principalmente para testes. Exemplo: `null()`. *round* Round retorna um valor inteiro arredondado. Por exemplo, `round(3.123)` ou `round($A)`. *ceil* Ceil arredonda o número até o valor inteiro mais próximo. Por exemplo, `ceil(3.123)` exibe `4`. *floor* Floor arredonda o número para baixo até o valor inteiro mais próximo. Por exemplo, `floor(3.123`) retorna `3`. **Reduzir** Reduzir usa uma ou mais séries temporais retornadas de uma consulta ou expressão e transforma cada série em um único número. Os rótulos da série temporal são mantidos como rótulos em cada número reduzido gerado. *Campos:* + **Função**: a função de redução a ser usada + **Entrada**: a variável (refID [como `A`]) a ser reamostrada + **Modo**: permite o comportamento de controle da função de redução quando uma série contém valores não numéricos (null, NaN, \$1-Inf) **Funções de redução** *Contagem* A contagem retorna o número de pontos em cada série. *Média* A média retorna o total de todos os valores em cada série dividido pelo número de pontos nessa série. No modo `strict`, se algum valor na série for null ou nan, ou se a série estiver vazia, NaN será retornado. *Min and Max* Min and Max retornam o menor ou maior valor da série, respectivamente. No modo `strict`, se algum valor na série for null ou nan, ou se a série estiver vazia, NaN será retornado. *Soma* Sum retorna o total de todos os valores em uma série. Se a série tiver comprimento zero, a soma será 0. No modo `strict`, se houver algum valor NaN ou Null na série, NaN será retornado. *Last* Last retorna o último número da série. Se a série não tiver valores, retorna NaN. **Modos de redução** *Estrito* No modo Estrito, a série de entrada é processada como está. Se algum valor na série não for numérico (null, NaN ou \$1-Inf), NaN será retornado. *Descartar dados não numéricos* Nesse modo, todos os valores não numéricos (null, NaN ou \$1-Inf) na série de entrada são filtrados antes de executar a função de redução. *Substituir não numérico* Nesse modo, todos os valores não numéricos são substituídos por um valor predefinido. **Reamostrar** A reamostragem altera os carimbos de data e hora em cada série temporal para ter um intervalo de tempo consistente. O principal caso de uso é que você possa reamostrar séries temporais que não compartilham os mesmos carimbos de data e hora para que a matemática possa ser executada entre elas. Isso pode ser feito reamostrando cada uma das duas séries e, em seguida, em uma operação matemática referenciando as variáveis reamostradas. *Campos:* + **Input**: a variável de dados de séries temporais (refID [como `A`]) a ser reamostrada + **Reamostrar** até: a duração do tempo para reamostrar, por exemplo, `10s.`unidades pode ser `s` segundos, `m` para minutos, `h` para horas, `d` para dias, `w` para semanas e `y` para anos. + **Downsample**: a função de redução a ser usada quando há mais de um ponto de dados por amostra de janela. Consulte a operação de redução para obter detalhes sobre o comportamento. + **Upsample**: o método a ser usado para preencher uma amostra de janela que não tem pontos de dados. + **pad** é preenchido com o último valor conhecido + **backfill** com o próximo valor conhecido + **preencha para preencher as** janelas de amostra vazias com NaNs ## Escrever uma expressão Se a fonte de dados for compatível, o Grafana exibirá o botão **Expressão** e mostrará todas as expressões existentes na lista do editor de consultas. **Para escrever uma expressão** 1. Abra o painel. 1. Abaixo da consulta, escolha **Expressão**. 1. No campo **Operação**, selecione o tipo de expressão que você deseja escrever. 1. Escreva a expressão. 1. Escolha **Aplicar**. ## Casos especiais Quando qualquer fonte de dados consultada não retorna séries ou números, o mecanismo de expressão retorna `NoData`. Por exemplo, se uma solicitação contiver duas consultas de fonte de dados mescladas por uma expressão, se `NoData` for retornado por pelo menos uma das consultas de fonte de dados, o resultado retornado para toda a consulta será `NoData`. Para obter mais informações sobre como o Grafana Alerting processa os resultados `NoData`, consulte [Lidar com casos de erro e ausência de dados](v9-alerting-managerules-grafana.md#v9-alerting-rule-no-data-error).