Consultas Customizadas

O recurso de Consultas Customizadas permite transformar um conjunto de amostras de Dados históricos em agrupamentos consolidados utilizando funções estatísticas. Isso facilita a análise e a geração de indicadores em uma determinada Tela.

As amostras podem ser agrupadas com base em diferentes períodos, como hora, dia ou semana, tornando a visualização mais intuitiva.

Além disso, é possível classificar os Dados em rótulos ou categorias específicas, como faixas de valores que indicam se um Dado é “Alto”, “Médio” ou “Baixo”.

Também podem ser aplicadas funções estatísticas, como médias, máximos e mínimos, para destacar padrões e variações ao longo do tempo.

Os resultados podem ser exibidos em Painéis Tabela ou Painéis Gráficos, proporcionando uma visualização clara e detalhada. Além disso, as amostras podem ser agrupadas em diferentes períodos (hora, dia ou dia da semana), facilitando a identificação de padrões e variações ao longo do tempo. Funções estatísticas como média, máximo e mínimo podem ser aplicadas para destacar comportamentos relevantes nos dados.

Exemplo: Monitoramento de Temperatura

Um exemplo de utilização poderia ser a necessidade de monitorar as medições de temperatura de um determinado sensor e analisar a variação média por hora.

Abaixo estão as amostras coletadas:

Timestamp	Valor do Dado
16/02/2025 10:05:11	10 °C
16/02/2025 10:10:13	15 °C
16/02/2025 10:15:15	20 °C
16/02/2025 11:00:17	30 °C
16/02/2025 11:05:19	40 °C

Ao aplicar uma Consulta Customizada configurada para agrupar por hora e calcular a temperatura média, o resultado será:

Timestamp	Média do Dado
16/02 10:00	15 °C
16/02 11:00	35 °C

Podemos utilizar o mesmo conjunto de Dados para classificar as medições em faixas de temperatura, conforme a tabela abaixo:

Rótulo ou Categoria	Faixas de Temperatura (ºC)
Baixa	até 15
Média	entre 16 e 25
Alta	acima de 25

Ao aplicar uma Consulta Customizada para classificar os Dados conforme essas faixas, o resultado será:

Classificação	Ocorrências
Baixa	2
Média	1
Alta	1

Esse tipo de agrupamento facilita a visualização da distribuição dos Dados em categorias, auxiliando na identificação de padrões e possíveis anomalias.

Criar Consulta Customizada

Para criar uma Consulta Customizada em uma Tela:

• Acesse o editor de Telas;

• Clique no menu do cabeçalho “Tela” ou “Layout”;

• Selecione a aba Scripts;

• Expanda a seção Conjunto de dados;

• Clique sobre o botão “” e defina um nome para a nova Consulta Customizada.

Importante

O nome da consulta customizada não pode conter caracteres especiais, exceto underline (_) e barra simples (/).

As consultas criadas são individuais para cada uma das Telas, ou seja, as consultas são limitadas a serem utilizadas apenas nas Telas em que as mesmas foram criadas.

Copiar nome da Consulta Customizada

Ao definir um nome para a consulta, o botão de copiar (representado pelo ícone “”), será exibido. Ao clicar sobre o botão, o nome da consulta será copiado para a área de transferência de seu dispositivo.

Agora, apresentaremos cada configuração da consulta customizada.

Expressão Agrupamento

Por padrão, é disponibilizada a seguinte expressão de agrupamento por hora nesta configuração:

moment(time).format("DD/MM HH:00")

Essa expressão ajusta os valores de tempo para o intervalo de hora cheia mais próximo, exibindo o horário no formato DD/MM HH:00” (dia, mês e hora e minuto 00).

Isso significa que os Dados serão agrupados por hora, garantindo que cada consulta exiba os resultados consolidados para cada período de 60 minutos.

Exemplo de amostra:

Timestamp
16/02/2025 10:05:11
16/02/2025 10:10:13
16/02/2025 10:15:15
16/02/2025 11:00:17
16/02/2025 11:05:19

Exemplos de retorno dessa expressão para a amostra acima:

Timestamp
16/02 10:00
16/02 11:00

Caso seja necessário ajustar a exibição do gráfico para incluir uma quebra de linha entre a data e a hora, é possível utilizar a seguinte variação:

moment(time).format("DD/MM [\n] HH:00 A")

Essa opção melhora a legibilidade ao separar visualmente as informações, tornando a interpretação dos Dados mais intuitiva.

Pode ser modificada pela seguinte expressão de agrupamento por dia:

moment(time).format("DD/MM")

Essa expressão ajusta os valores de tempo para o intervalo de dia cheia mais próximo, exibindo o dia no formato DD/MM” (dia e mês).

Isso significa que os Dados serão agrupados por dia, garantindo que cada consulta exiba os resultados consolidados para cada período de 24 horas.

Exemplo de amostra:

Timestamp
16/02/2025 10:05:11
16/02/2025 10:10:13
16/02/2025 10:15:15
17/02/2025 11:00:17
17/02/2025 11:05:19

Exemplos de retorno dessa expressão para a amostra acima:

Timestamp
16/02
17/02

Pode ser modificada pela seguinte expressão de agrupamento por dia da semana (podendo utilizar Lista de Texto):

moment(time).format("d")

Essa expressão ajusta os valores de tempo para o intervalo de 0 à 6 cheia mais próximo, exibindo o dia da semana no formato “d” (dia da semana).

Isso significa que os Dados serão agrupados por dia da semana, garantindo que cada consulta exiba os resultados consolidados para cada período de 24 horas.

Exemplo de amostra:

Timestamp
16/02/2025 10:05:11
16/02/2025 10:10:13
17/02/2025 10:15:15
17/02/2025 11:00:17
18/02/2025 11:05:19
18/02/2025 10:05:11
19/02/2025 10:10:13
19/02/2025 10:15:15
20/02/2025 11:00:17
20/02/2025 11:05:19
21/02/2025 10:05:11
21/02/2025 10:10:13
22/02/2025 10:15:15
22/02/2025 11:00:17

Exemplos de retorno dessa expressão para a amostra acima:

Timestamp
0 (Domingo)
1 (Segunda)
2 (Terça)
3 (Quarta)
4 (Quinta)
5 (Sexta)
6 (Sábado)

Além disso, é possível classificar os Dados em rótulos ou categorias específicas, como faixas de valores que indicam se um Dado é “Alto”, “Médio” ou “Baixo”.

Esta expressão é utilizada para definir um status para o Dado de acordo com o intervalo do valor que ele possui, permitindo que no painel, seja exibido este mesmo status no local onde o Dado possui os valores definidos na condição.

Para maiores detalhes sobre o uso da condição de intervalo, acesse Operador Ternário.

Neste exemplo, seria válido a definição do status de acordo com as seguintes condições:

• O status “Alto” assim que o valor do Dado for maior que 70;

• O status “Médio” assim que o valor do Dado for maior que 30;

• O status “Baixo” para o restante dos valores menores que 30.

Para definir os exemplos citados acima, devemos criar a expressão de acordo com a escrita abaixo:

value > 70 ? 'Alto' : value >= 30 ? 'Médio' : 'Baixo'

Exemplo de amostra:

Timestamp	Valor do Dado
16/02/2025 10:05:11	10 °C
16/02/2025 10:10:13	30 °C
16/02/2025 10:15:15	50 °C
16/02/2025 11:00:17	70 °C
16/02/2025 11:05:19	90 °C

Exemplos de retorno dessa expressão, contando cada item, usando a estatística count:

Classificação	Ocorrências
Baixa	1
Média	3
Alta	1

Outra forma de aplicar este exemplo seria utilizar valores críticos (adicionando também o filtro: value > 70 || value < 30):

value > 70 ? 'Alta (> 70)' : 'Baixa (< 30)'

Exemplo de amostra:

Timestamp	Valor do Dado
16/02/2025 10:05:11	10 °C
16/02/2025 10:10:13	30 °C
16/02/2025 10:15:15	50 °C
16/02/2025 11:00:17	70 °C
16/02/2025 11:05:19	90 °C

Exemplos de retorno dessa expressão, contando cada item, usando a estatística count:

Classificação	Ocorrências
Baixa (< 30)	1
Alta (> 70)	1

Atenção

O formato que será utilizado para a consulta não pode ser alterado nas propriedades dos painéis em que a consulta será realizada.

Esta função aplica-se ao Dado associado e no intervalo selecionado sobre o filtro das amostras precisa ser maior que o período definido na função para que o cálculo seja realizado da maneira correta.

Ordenar Agrupamento

O ícone de ordenação da expressão de agrupamento é utilizado para ordenar o resultado da agregação:

• Ascendente;

• Descendente.

Filtro

Filtro: utilizado para filtrar os valores das amostras antes do agregação ser aplicada.

Para mais informações sobre os filtros, acesse Filtros de valores para apresentação de séries de Dados.

Colunas

Define o Dado para ser calculado uma estatística do agrupamento.

Atenção

A ordem de apresentação no Painel Gráfico segue a mesma definida durante a criação das colunas. Entretanto, no Painel Tabela, é possível alterar esta ordem.

Em ambos os Paineis, é possível ocultar determinados campos.

Para criar uma coluna de agregação, siga o passo a passo:

• Expanda a seção de Colunas;

• Clique em “Adicionar”;

• Adicione um Dado de origem;

• Defina o nome da coluna para identificação;

• Selecione uma função de agregação (estatística);

• Informe um formato de apresentação (por padrão, será utilizado o formato cadastrado no Dado);

• Clique em “ Salvar” para confirmar as alterações da tela selecionada.

Atenção

Sempre que houver alguma alteração nas configurações de uma consulta customizada, será necessário atualizá-la, no ícone “ Aplicar” nas configurações dos Painéis Gráfico e Tabela para que as mudanças sejam refletidas corretamente.

É importante destacar que todas as alterações realizadas (como criação, edição ou remoção) são salvas automaticamente, mas apenas de forma local, ou seja, no navegador em uso durante a configuração.

Para que as modificações sejam efetivamente registradas e disponibilizadas para outros usuários, é indispensável utilizar a função Publicar da Tela.

Atenção

Este recurso deve ser utilizado com moderação, pois todos os cálculos de agrupamento e estatísticas são processados diretamente no navegador do usuário, considerando o conjunto completo de amostras retornado para o período selecionado.

Dependendo da quantidade de colunas configuradas na consulta personalizada, da taxa de amostragem do histórico de cada Dado e da extensão do período selecionado, o navegador pode apresentar lentidão ou até mesmo travamentos na aba em uso.

Para evitar impactos no desempenho, recomenda-se ajustar esses parâmetros conforme necessário.

Exemplo de utilização

A primeira premissa para funcionamento de uma Consulta Customizada é definir como as amostras registradas no histórico para os Dados serão agrupadas, por exemplo, por tempo ou por categoria.

Para isso, deve ser utilizada uma expressão(em linguagem “JavaScript”) que permite agrupar as amostras registradas no intervalo selecionado através do Painel Barra de Ferramentas.

Expressão Agrupamento por Tempo

Para exemplificar o uso deste recurso, iremos construir uma nova tela contendo 1 Painel de Barra de Ferramentas, 3 Painel Tabela e 2 Painel Gráfico:

Após, iremos configurar os Paineis Tabela com as informações, como mostra abaixo:

Agora, iremos configurar a exibição do histórico das amostras gerais do filtro:

Nesta Tela, iremos criar uma consulta customizada que será responsável por realizar uma pesquisa de todas as amostras de um Dado entre o período inicial e final, realizar a média destes valores por dia e exibi-las em sequência no gráfico.

Após adicionar os painéis na Tela, iremos acessar a aba Scripts e expandir a seção Conjunto de Dados para criar uma nova consulta customizada:

Clicando sobre o botão “Criar” (representado pelo ícone “”) e definindo um nome para a consulta customizada, confirme a opção através do botão “” para criar uma nova consulta:

Para este exemplo, iremos definir uma expressão:

moment(time).format("DD/MM/YYYY")

Neste caso, definimos no parâmetro “DD” que as amostras coletadas serão agrupadas a cada 1 dia. Ou seja, a cada dia da consulta, o Portal irá coletar todas as amostras e separá-las dia por dia.

Para a opção Filtro, iremos definir para que sejam exibidos apenas as amostras que possuírem o valor maior que 20, antes da agregação, através da seguinte expressão:

value > 20

Já no tópico Colunas, iremos adicionar o Dado que será monitorado nesta consulta e configurar 3 opções de personalização:

• Nome da coluna: Nome que será exibido na coluna do painel do Dado. Caso este campo não seja preenchido, o Portal automaticamente irá definir o nome da coluna utilizando o mesmo nome do Dado monitorado.

• Função de agregação: Seleção de uma função estatística que calculará o valor final das amostras agregadas. Neste caso, iremos selecionar a opção “average” que é responsável por realizar a média das amostras;

• Formato: Formato customizado que será exibido nas amostras do painel. Neste caso, iremos definir a opção “%.1f%” para que os valores sejam exibidos contendo 1 casa decimal.

Salve as configurações feitas para a consulta customizada através do botão “Salvar “

Após a configuração de todos os campos da Consulta customizada, teremos uma consulta semelhante ao exemplo abaixo:

Após realizar as configurações, iremos definir para que o Painel gráfico assuma a nova consulta customizada como padrão para as pesquisas, para isso acesse a aba de propriedades do Painel gráfico, em seguida expanda as opções de “Propriedades específicas” e em “Série de dados” altere no campo “Origem” de “Lista de dados” para a opção “Consulta customizada”.

Ao selecionar “Consulta customizada”, será disponibilizada logo abaixo uma nova opção “Nome” que possibilitará visualizar todas as consultas customizadas que foram criadas para esta tela. Selecione a consulta customizada criada nos passos anteriores:

Após terminar essa configuração, fazer o mesmo no Painel Gráfico do lado direito, porém com o tipo de gráfico de Barra e com Rótulo, além de modificar o Eixo X e Y conforme desejado.

Agora temos que configurar a exibição das tabelas de agregação que estão divididas em duas partes, primeira tabela com 7 registros, segunda tabela começa depois do 7º registro.

Na tabela 1, será configurado no limite 7:

Já na tabela 2, será configurado no offset 7, começando da 8ª linha da amostra:

Para finalizar, após publicar e definir esta tela como Dashboard de um Conector. Iremos acessá-la e realizar uma consulta definindo um Período inicial e um Período final pelo painel de Barra de Ferramentas:

Após visualizar os resultados, podemos concluir que os mesmos foram exibidos separados por dia. Ou seja, de acordo com a Função de agregação “average”, o Portal analisou todas as amostras que foram coletadas entre os períodos selecionados e nos casos em que o Dado possuia mais de uma amostra por dia, foram realizadas e exibidas apenas as médias dos valores.

Para concluir, na imagem abaixo podemos visualizar o histórico de amostras do Dado “Umidade” e podemos visualizar que em algumas situações, o Dado sofreu mais de uma alteração, validando o procedimento da Função de agregação definida anteriormente:

Expressão Agrupamento por Condição de Intervalo (Categoria)

Uma alternativa eficiente para organizar e categorizar dados é utilizar condições de intervalo. Esse método permite agrupar valores em categorias predefinidas, facilitando a análise e a visualização dos dados nos painéis.

Neste exemplo, aplicaremos essa abordagem ao Dado de Umidade, classificando as amostras coletadas em três categorias distintas:

• Baixa: amostras cujo valor seja inferior a 30;

• Média: amostras cujo valor seja maior do que 30 e menor que 70;

• Alta: amostras cujo valor seja superior a 70;

Para facilitar a criação dos painéis, utilizaremos consultas customizadas que agregam as amostras conforme essas classificações.

Configuração das Consultas Customizadas

Criaremos duas consultas customizadas para estruturar os dados:

• status_completo: contabiliza todas as amostras e as classifica em Baixa, Média e Alta.

• status_critico: considera apenas as amostras em situações críticas, ou seja, classificadas como Baixa e Alta.

Consulta Customizada: “status_completo”

A expressão utilizada para definir essa classificação é

value > 70 ? 'Alta' : value >= 30 ? 'Média' : 'Baixa'

A função de agregação será count, para contar a quantidade de amostras coletadas, e o formato será %d.

Após configurar os campos, teremos a seguinte visualização:

Consulta Customizada: “status_critico”

Nesta consulta, queremos destacar apenas as amostras com valores críticos (menores que 30 ou maiores que 70).

A expressão utilizada será:

value > 70 ? 'Alta (> 70)' : 'Baixa (< 30)'

Além disso, aplicaremos um filtro para incluir apenas valores menores que 30 ou maiores que 70:

value > 70 || value < 30

Após configurar os campos, teremos a consulta customizada “status_critico” semelhante ao exemplo abaixo:

Configuração dos Painéis

Para exibir os resultados de maneira intuitiva, organizamos a visualização em diferentes tipos de painéis:

• 1 Painel de Barra de Ferramentas;

• 3 Painéis Tabela;

• 2 Painéis Gráficos.

Painéis Tabela

Neste caso, o primeiro painel tabela (“Histórico”) será responsável por exibir as amostras coletadas do Dado Umidade, exibindo a data/hora do registro e seus respectivos valores. Para isso, iremos configurar o painel como mostra o exemplo abaixo:

O segundo painel tabela (“Status Completo”) será responsável por exibir a quantidade de amostras coletadas para cada um dos termos, ou seja, a quantidade de registros considerados altos, médios e baixos.

Após realizar as personalizações visuais da tabela e configurar o “Conjunto de Dados” selecionando a consulta customizada “status_completo”, teremos um painel semelhante ao exemplo abaixo:

O terceiro painel tabela (“Status Crítico”) será responsável por exibir a quantidade de amostras coletadas apenas para os termos considerados altos e baixos.

Após realizar as personalizações visuais da tabela e configurar o “Conjunto de Dados” selecionando a consulta customizada “status_critico”, teremos um painel semelhante ao exemplo abaixo:

Painéis Gráficos

Para o primeiro painel gráfico, iremos utilizar a consulta customizada “status_competo” e selecionar a opção de gráfico “Torta”. Desta forma, será exiba a distribuição das amostras entre as três categorias (Baixa, Média e Alta) com base na consulta “status_completo”.

Após configurar o primeiro painel gráfico, teremos um exemplo semelhante a imagem abaixo:

Para o segundo painel gráfico, iremos utilizar a consulta customizada “status_critico” e selecionar a opção de gráfico “Torta”. Desta forma, será exiba a distribuição das amostras apenas entre as categorias Baixa e Alta.

Após configurar o segundo painel gráfico, teremos um exemplo semelhante a imagem abaixo:

Análise dos Resultados

Após publicar a tela, defini-la como Dashboard de um Conector e selecionar períodos válidos para a consulta, podemos analisar os resultados obtidos pelas consultas customizadas:

O painel “Status Completo” e o gráfico de torta mostram que as amostras foram corretamente agrupadas nas categorias Alta, Média e Baixa.

Já o painel “Status Crítico” e o gráfico de barras apresentam apenas as amostras em situações extremas (Alta e Baixa), como definido na consulta “status_critico”.

O painel “Histórico” permite uma inspeção detalhada dos valores coletados ao longo do tempo, facilitando a validação das contagens e agrupamentos.