Plotar séries temporais

Crie painéis e selecione a série temporal que deseja plotar. Use consultas personalizadas e funcionalidades avançadas, como filtragem, agregação, granularidade, operações aritméticas e funções, para trabalhar com séries temporais.

Criar um painel

Para criar um painel com dados de série temporal no Cognite Data Fusion (CDF):

1. Faça login em sua instância do Grafana e crie um painel.

2. Use as guias de consulta abaixo da área do gráfico principal para selecionar séries temporais para o seu painel:

   • Pesquisa de série temporal: busca dados de uma série temporal específica. Comece a digitar o nome ou a descrição da série temporal e selecione-a na lista suspensa.

     Especifique agregação e granularidade diretamente na consulta. Por padrão, a agregação é média e a granularidade é calculada a partir do intervalo de tempo selecionado no gráfico.

     dica

     Se preferir, defina um rótulo personalizado e use o formato {{property}} para extrair dados da série temporal. Você pode usar todas as propriedades de série temporal disponíveis para definir um rótulo (por exemplo, {{name}} - {{description}} ou {{metadata.key1}}).

   • Série temporal do ativo: busca dados da série temporal relacionada a um ativo específico. Comece a digitar o nome ou a descrição do ativo e selecione-o na lista suspensa. Como opção, você pode decidir se deseja incluir séries temporais de subativos.

   • Consulta personalizada de série temporal: busca séries temporais que correspondam a uma consulta.

3. A série temporal correspondente à sua seleção será renderizada na área do gráfico. Ajuste o período de tempo conforme necessário para exibir dados relevantes.

Usar consultas personalizadas

As consultas personalizadas oferecem controle detalhado sobre a seleção de dados de séries temporais. Você pode usar operações aritméticas, funções e uma sintaxe especial para obter séries temporais sintéticas. Esta seção também descreve as limitações relacionadas à filtragem de dados e como usar efetivamente filtros regex e do lado do servidor.

Definir uma consulta

Para solicitar séries temporais, especifique uma consulta com os parâmetros dentro dela. Por exemplo, para consultar uma série temporal em que id é igual a 123, especifique ts{id=123}.

Você pode solicitar séries temporais usando id, externalId ou filtros de séries temporais.

Para séries temporais sintéticas, você pode especificar vários tipos de propriedade:

• bool: ts{isString=true} ou ts{isStep=false}
• string ou number: ts{id=123} ou ts{externalId='external_123'}
• array: ts{assetIds=[123, 456]}
• object: ts{metadata={key1="value1", key2="value2"}}

Para criar séries temporais sintéticas complexas, você pode combinar os tipos em uma única consulta:

ts{name="test", assetSubtreeIds=[{id=123}, {externalId="external_123"}]}

Filtragem

As consultas também aceitam filtragem com base nas propriedades da série temporal que se aplicam como AND lógico. Por exemplo, a consulta abaixo encontra séries temporais:

• que pertencem a um ativo com id igual a 123
• em que name começa com "Begin"
• em que name não termina com "end"
• em que name não é igual a "Begin query"

ts{assetIds=[123], name=~"Begin.*", name!~".*end", name!="Begin query"}

A sintaxe da consulta contém diferentes tipos de operadores de igualdade:

• = — igualdade estrita: especifica parâmetros para a solicitação de série temporal ao CDF. Use com atributos de filtragem.
• =! — desigualdade estrita: filtra as séries temporais buscadas por propriedades que não são iguais à string. Aceita valores de string, numéricos e booleanos.
• =~ — igualdade de regex: filtra a série temporal buscada por propriedades que correspondem à expressão regular. Aceita valores de string.
• !~ — desigualdade de regex: filtra a série temporal buscada por propriedades que não correspondem à expressão regular. Aceita valores de string.

Você também pode filtrar por metadados:

ts{externalIdPrefix="test", metadata={key1="value1", key2=~"value2.*"}}

A consulta acima solicita séries temporais em que:

• externalIdPrefix é igual a "test"
• metadata.key1 é igual a "value1"
• metadata.key2 começa com "value2"

Limitações da consulta

Ao realizar consultas personalizadas, é importante entender as limitações subjacentes à obtenção de séries temporais:

• Filtragem do lado do cliente: O conector aplica consultas de regex (=~ para correspondências e !~ para exclusões) e filtros de desigualdade inexata (=!) no lado do cliente. Esse processo ocorre após a recuperação inicial de até 1.000 itens de série temporal do Cognite Data Fusion (CDF). Devido a essa abordagem, existe a possibilidade de que nem todas as séries temporais relevantes sejam incluídas no subconjunto obtido se o número total for superior a 1000.

• Filtragem do lado do servidor: Para minimizar essa limitação, recomendamos usar a filtragem do lado do servidor sempre que possível. Para isso, você pode aplicar filtros de igualdade estrita (=) em propriedades específicas de filtros de séries temporais. Assim, você restringe efetivamente o conjunto de séries temporais recuperadas do CDF, garantindo que os filtros subsequentes do lado do cliente sejam aplicados a um conjunto de dados mais direcionado. Isso é particularmente útil para garantir que todas as séries temporais relevantes, especialmente as de interesse, sejam incluídas no conjunto de dados inicial obtido do CDF.

Combine a filtragem do lado do servidor com atributos ou metadados específicos para refinar o escopo da sua consulta antes de aplicar um regex ou outros filtros do lado do cliente. Essa abordagem aumenta significativamente as chances de selecionar todas as séries temporais de interesse em seu painel do Grafana.

Agregação, granularidade e alinhamento

Você pode especificar agregação e granularidade para cada série temporal usando os menus suspensos na interface do usuário.

Se, por exemplo, a agregação for definida como average e a granularidade for igual a 1h, todas as consultas solicitarão pontos de dados com a agregação e a granularidade selecionadas. Por padrão, a agregação com série temporal sintética é alinhada para quinta-feira 00:00:00 UTC, 1º de janeiro de 1970.

Com a sintaxe de consulta de série temporal sintética, você pode definir agregação, granularidade e alinhamento de cada série temporal separadamente:

ts{externalId='houston.ro.REMOTE_AI[34]', alignment=1599609600000, aggregate='average', granularity='24h'}

A consulta acima substitui os valores de agregação e granularidade definidos na interface do usuário. Consulte a documentação da API para obter uma lista de agregados compatíveis.

Operações aritméticas

Você pode aplicar operações aritméticas para combinar séries temporais. Por exemplo:

ts{id=123} + ts{externalId="test"}

O resultado da consulta acima é um único gráfico em que os pontos de dados são valores somados de cada série temporal.

Neste exemplo, a consulta ts{name~="test1.*"} pode retornar mais de uma série temporal. Mas vamos supor que ela retorne três séries temporais com as IDs 111, 222 e 333:

ts{name~="test1.*"} + ts{id=123}

O resultado da consulta são três gráficos, uma combinação de valores somados de séries temporais retornados pela primeira e segunda expressões na consulta. Os gráficos resultantes representam estas consultas:

• ts{id=111} + ts{id=123}
• ts{id=222} + ts{id=123}
• ts{id=333} + ts{id=123}

Você pode conferir um exemplo desse comportamento (cada expressão ts{} retorna duas séries temporais) na imagem abaixo (observe os rótulos abaixo do gráfico).

Funções

É aceita uma ampla variedade de funções que você pode aplicar a séries temporais sintéticas:

• Trigonométrica: sin(ts{}), cos(ts{}) e pi().
• Funções de comprimento variável: max(ts{}, ...), min(ts{}, ...) e avg(ts{}, ...).
• Algébrica: ln(ts{}), pow(ts{}, exponent), sqrt(ts{}), exp(ts{}) e abs(ts{}).
• Tratamento de erros: on_error(ts{}, default_value). Consulte Tratamento de erros de cálculos.
• Série temporal de strings: map(expression, [list of strings to map from], [list of values to map to], default_value). Consulte Série temporal de strings.

Tratamento de erros de cálculos

A função on_error(ts{...}) permite a renderização do gráfico mesmo que alguma exceção apareça. Ela lida com erros como:

• BAD_DOMAIN: se forem fornecidos intervalos de entrada inválidos. Por exemplo, divisão por zero ou a raiz quadrada de um número negativo.
• OVERFLOW: se o resultado for maior que 10^100 em valor absoluto.

Se algum deles for encontrado, em vez de retornar um valor para o carimbo de data/hora, o CDF retornará um campo de erro com uma mensagem de erro. Para evitar isso, você pode agrupar a (sub)expressão na função on_error():

on_error(1/ts{externalId='canBeZero'}, 0)

Série temporal de strings

A função map() pode lidar com séries temporais com valores de strings para converter strings em duplas. Se, por exemplo, uma série temporal de uma válvula pode ter os valores "OPEN" ou "CLOSED", você pode convertê-la em um número com:

map(TS{externalId='stringstate'}, ['OPEN', 'CLOSED'], [1, 0], -1)

"OPEN" mapeado para 1, "CLOSED" para 0 e os demais para -1.

No momento, não há suporte para séries temporais de strings no momento. Todas as séries temporais de strings são consideradas séries temporais escalonadas.

Conversão de unidades

Se uma série temporal tiver um unitExternalId definido, você poderá converter os valores para uma unidade diferente dentro da mesma quantidade ao consultar dados usando consultas personalizadas.

Exemplo:

{ts{externalId='temperature_f_houston', targetUnit='temperature:deg_c'} + ts{id='123', targetUnitSystem='SI'}}

Você pode escolher targetUnit ou targetUnitSystem para cada série temporal ou agregado. A unidade de destino que você escolher deve ser compatível com a unidade original.

Ao consultar pontos de dados usando séries temporais sintéticas, as unidades dos valores não serão mantidas. Isso significa que é possível adicionar valores de uma série temporal temperatura a uma série temporal distância, mesmo que não seja fisicamente preciso.

Observação: se você tentar acessar as propriedades unit ou unitExternalId de cada série temporal no campo de rótulo, o Grafana retornará a unidade original da série temporal, não a unidade dos pontos de dados.

Exibir dados de série temporal das instâncias de modelo de dados

Você pode exibir dados de séries temporais das instâncias de modelos de dados do CDF:

1. Na guia Modelos de dados, selecione o modelo de dados e a versão.

2. Especifique a consulta.

   importante

   Adicione __typename e externalId abaixo dos campos que contêm a série temporal. Neste exemplo, abaixo de temperature e pressure:

   {
     listPump {
       items {
         temperature {
           __typename
           externalId
         }
         pressure {
           __typename
           externalId
         }
       }
     }
   }