Agregação e Downsampling

Por padrão, um widget recebe linhas brutas: cada registro que corresponde aos seus filtros, do mais novo para o mais antigo, até o limite de linhas. Isso é exatamente o certo para uma tabela com as últimas leituras e exatamente o errado para um gráfico dos últimos seis meses — um sensor que amostra a cada segundo produz 15 milhões de linhas nessa janela, das quais um gráfico de 600 pixels de largura consegue desenhar talvez 600.

A agregação resolve os dois problemas de uma vez. O banco de dados do projeto agrupa os registros correspondentes em intervalos de tempo, calcula um valor por intervalo e envia apenas esses valores ao widget. Um ano de dados vira algumas centenas de pontos, e perguntas que os dados brutos não conseguem responder — temperatura média por hora, registros por máquina, energia total hoje — viram configuração comum de widget.

Tudo acontece no banco de dados, antes de os dados chegarem ao navegador. Nada é calculado no widget, então widgets agregados continuam ao vivo e continuam rápidos, por mais histórico que exista por trás deles.

Como Ativar

A agregação fica na mesma caixa de diálogo dos filtros — aquela que abre pelo ícone de filtro ao lado de uma vinculação de dados. Veja Vinculação de Dados para a caixa de diálogo como um todo.

Nela, a seção Agregação oferece duas opções:

• Linhas brutas — o padrão: os registros são retornados como estão armazenados.
• Agregado ao longo do tempo — os registros são agrupados e reduzidos a um valor por grupo.

Mudar para Agregado ao longo do tempo revela um seletor de Método e, quando aplicável, os controles de tamanho de intervalo descritos abaixo. Como todo agregado precisa de um intervalo de tempo sobre o qual trabalhar, ativar a agregação também preenche uma janela deslizante padrão das últimas 24 horas, caso o widget ainda não tivesse uma janela de tempo — ajuste-a na seção Janela de tempo móvel, logo acima.

Métodos

Um método se aplica a todas as colunas de valor de uma mesma série de dados. Para mostrar várias estatísticas da mesma medição — uma faixa de mínimo/máximo com uma linha de média, por exemplo — adicione uma série de dados por estatística. Elas compartilham uma única consulta ao banco de dados, então as séries extras não custam requisições adicionais.

Média, Soma, Mínimo e Máximo exigem uma coluna que contenha números. Apontá-los para uma coluna de texto ou booleana é rejeitado com uma mensagem explicativa. Contagem funciona com qualquer coisa, o que a torna o método para perguntas do tipo “quantos registros”.

O Que É Agregado

Você nunca lista explicitamente as colunas da agregação — a plataforma as deriva do mapeamento de campos que você já configurou para o widget:

Isso significa que o mesmo mapeamento usado para linhas brutas continua funcionando: mapeie x para o timestamp e y para temperature, ative a agregação, e o gráfico passa a plotar a temperatura média por intervalo em vez de cada leitura individual.

As Três Formas de um Widget Agregado

1. Série temporal com resolução automática

O caso mais comum: x está mapeado para tsp e o modo de intervalo permanece em Automático — ajustado à resolução do widget. A plataforma então escolhe o tamanho do intervalo a partir da largura renderizada do widget — um gráfico de 600 pixels de largura nunca recebe mais do que cerca de 600 pontos, seja qual for a janela de tempo. Amplie a janela de um dia para um ano e os intervalos simplesmente ficam mais largos; o volume de dados que trafega pela rede permanece constante.

Escolha esta opção quando o tamanho do intervalo em si não carrega significado e você quer apenas um gráfico de tendência legível e rápido: “temperatura no último mês”.

Redimensionar um widget refaz a consulta na nova resolução, mas somente quando a largura cruza um degrau — pequenos arrastes não disparam requisições.

2. Série temporal com tamanho de intervalo fixo

Selecione Tamanho de intervalo fixo e informe uma duração e uma unidade — a cada 1 hora, a cada 15 minutos, a cada 6 horas. Use isso sempre que o intervalo faz parte da pergunta, e não é apenas um detalhe de exibição: “unidades produzidas por hora”, “energia consumida por dia”.

Intervalos fixos são alinhados a fronteiras naturais no fuso horário do seu navegador: intervalos de 6 horas começam às 00:00, 06:00, 12:00 e 18:00 no horário local; intervalos diários quebram à meia-noite local; intervalos semanais começam na segunda-feira.

Se o tamanho escolhido produzisse mais intervalos do que um gráfico consegue exibir de forma sensata (o teto é 2000), a plataforma automaticamente amplia os intervalos para um múltiplo do que você pediu — intervalos de um minuto ao longo de uma semana inteira viram intervalos de cinco minutos — em vez de recusar a consulta. A caixa de diálogo avisa quando isso acontece e qual tamanho está realmente em uso.

3. Um valor por categoria

Mapeie x para uma coluna em vez do timestamp — um nome de máquina, um tipo de produto, uma unidade — e o widget vira um resumo por categoria: a janela de tempo inteira é tratada como um único intervalo, e cada valor distinto dessa coluna gera exatamente uma linha agregada.

Esta é a forma para “registros por máquina hoje” ou “tempo médio de ciclo por linha de produção nesta semana”. Não há tamanho de intervalo a escolher — a caixa de diálogo informa isso em vez de exibir os controles de intervalo.

Contando registros: a contagem de linhas de um grupo é Contagem aplicada à coluna de timestamp tsp, já que todo registro tem uma. Mapeie y para tsp e a plataforma seleciona Contagem automaticamente — é o único agregado que uma coluna de timestamp permite.

x     → machine_name        (agrupa os registros)
y     → tsp                 (contado → número de registros)
Método: Contagem
Janela: último dia

O resultado é uma barra por máquina mostrando quantos registros aquela máquina produziu no último dia.

Valores Únicos Agregados

Vinculações escalares — o valor de um card de KPI, de um medidor, de um campo de texto — oferecem a mesma escolha em uma seção Valor:

• Último valor — o valor do registro mais recente, como antes.
• Agregado em uma janela de tempo — um valor calculado sobre toda a janela.

Use isso para números de destaque ao vivo: “unidades produzidas hoje” (Contagem sobre tsp com uma janela de 1 dia), “temperatura média neste turno”, “pico de potência neste mês”. Aqui também não há tamanho de intervalo — a janela é o intervalo. O valor se atualiza conforme novos registros chegam, então, diferentemente de um número colado no widget, ele nunca fica desatualizado.

Filtros, Janelas e Agregação em Conjunto

As seções da caixa de diálogo se aplicam na ordem em que aparecem, que é também a ordem em que o banco de dados as aplica:

1. Janela de tempo móvel / janela temporal personalizada — seleciona o período.
2. Filtros — selecionam quais registros dentro desse período participam.
3. Agregação — reduz os registros selecionados a um valor por intervalo.
4. Limite de Linhas — uma salvaguarda, veja abaixo.

Como os filtros rodam antes da agregação, eles restringem o que entra em cada intervalo. machine = 'A' combinado com médias horárias dá a média horária da máquina A. Filtros ligados a widgets de filtro ou a segmentos de roteamento funcionam exatamente como funcionam para linhas brutas, então um gráfico agregado acompanha um menu suspenso ou a URL de uma página como qualquer outro widget.

Widgets de calendário também se combinam: quando o usuário escolhe um intervalo de datas, esse intervalo substitui a janela deslizante e a agregação o acompanha.

Alinhamento da janela

Enquanto a agregação está ativa, o início da janela é alinhado à grade de intervalos para que os próprios intervalos fiquem parados conforme o tempo passa — sem isso, cada atualização deslocaria levemente todas as fronteiras de intervalo e o gráfico inteiro tremeria. A caixa de diálogo indica isso com “A janela desloca em passos de …”, e a prévia do início/fim resolvidos sempre mostra o intervalo realmente consultado.

O fim da janela nunca é estendido: uma janela que termina agora continua terminando agora, e uma janela que termina há uma hora nunca alcança essa última hora.

O limite de linhas sob agregação

O Limite de Linhas continua visível, mas muda de papel: o número de intervalos é derivado do tamanho do widget ou do seu intervalo fixo, não desse campo. Ele só se aplica se um widget precisar recorrer a linhas brutas — por exemplo, em uma instância auto-hospedada cuja versão da plataforma é anterior à agregação. Mantê-lo em um valor sensato mantém esse widget utilizável.

Lacunas nos Dados

Um intervalo em que nenhum registro correspondeu é omitido do resultado, e não retornado como zero. Para uma média essa é a resposta honesta — não existe média de nada —, mas para um gráfico de Contagem de um evento intermitente isso significa que um gráfico de linhas traça uma reta atravessando o período de silêncio em vez de cair para zero. Gráficos de barras mostram a lacuna naturalmente; em gráficos de linhas, esteja ciente da diferença entre “sem dados” e “zero”.

Atualizações ao Vivo

Widgets agregados continuam ao vivo. Conforme os registros chegam, os intervalos afetados são recalculados e o widget se atualiza — no máximo uma vez a cada poucos segundos, para que um dispositivo publicando em alta frequência não inunde o board. Como o intervalo mais recente normalmente ainda está sendo preenchido, seu valor continua mudando até que o intervalo se feche; isso é esperado, e é por isso que o último ponto de um gráfico ao vivo costuma ser mais baixo que os vizinhos em Contagem e Soma.

Desempenho e Históricos Longos

A agregação sobre uma janela longa ainda precisa ler os registros por trás dela. Para tabelas que costumam alimentar gráficos de janela longa, um app pode declarar downsampling contínuo no seu esquema de dados — veja downsample na referência do Backend de Dados. A plataforma passa então a manter uma cópia pré-agregada da tabela e responde às consultas de janela longa a partir dela, tipicamente ordens de magnitude mais rápido, e pode reter esse histórico reduzido por mais tempo que os próprios dados brutos — de modo que um gráfico ainda consegue mostrar dois anos de médias horárias depois que os registros brutos já foram descartados.

Isso é totalmente transparente para o board: a configuração do widget não muda, e as consultas que a cópia pré-agregada não consegue atender (intervalos muito finos, filtros em colunas pelas quais ela não agrupa) recorrem automaticamente à tabela bruta.

Limitações

• A agregação se aplica a tabelas, não a tabelas de transformação. Agregue a tabela subjacente ou pré-agregue no próprio SQL da transformação.
• Um método por série de dados. Use várias séries de dados para várias estatísticas de uma mesma coluna.
• Timestamps só são agregados por Contagem. A Média de um timestamp não faz sentido e é rejeitada.
• Um eixo de categorias e um eixo de tempo são mutuamente exclusivos para uma mesma série de dados — um gráfico é “ao longo do tempo” ou “por categoria”. Para ter os dois (médias horárias por máquina), mantenha x em tsp e coloque a coluna da máquina em pivot.
• Campos JSON podem ser agregados como colunas comuns, mas apenas os campos que o app declarou para downsampling se beneficiam da cópia pré-agregada; os demais são calculados a partir da tabela bruta.

Receitas

Resumo

• Mude uma vinculação de Linhas brutas para Agregado ao longo do tempo na caixa de diálogo de filtro para que o banco de dados calcule os valores em vez de enviar registros.
• Com x no timestamp você obtém uma série temporal — resolução automática para tendências, um intervalo fixo quando o intervalo é a pergunta.
• Com x em outra coluna você obtém um valor por categoria; com uma vinculação escalar, um único número ao vivo.
• Contagem sobre a coluna tsp é como se contam registros.
• Os filtros se aplicam antes da agregação; intervalos vazios são omitidos; o limite de linhas vira uma salvaguarda de reserva.
• Para históricos longos, os apps podem declarar downsample para que a plataforma sirva os gráficos a partir de uma cópia pré-agregada e possa manter esse histórico além da janela de retenção dos dados brutos.