Como agrupar dados por tempo em KQL: passo a passo

Agrupar dados por intervalos de tempo é a base de qualquer análise em tempo real: transforma milhares de eventos soltos numa linha temporal legível, pronta para gráficos e alertas. Em KQL (Kusto Query Language) — a linguagem do Real-Time Analytics no Microsoft Fabric e do Azure Data Explorer — esta tarefa resume-se a duas funções simples: summarize e bin(). Este guia mostra como agrupar leituras de sensores por janelas de tempo, do exemplo mais básico ao gráfico final.

Pré-requisitos

• Acesso a uma base de dados KQL no Microsoft Fabric (Real-Time Analytics) ou a um cluster do Azure Data Explorer.
• Uma tabela com, pelo menos, uma coluna de data/hora do tipo datetime. Neste exemplo usamos a tabela Leituras, com as colunas Timestamp, Sensor e Valor.
• Noções básicas de consultas: saber que em KQL os passos se ligam com o operador pipe (|).

Passo 1: Filtrar a janela de tempo

Antes de agrupar, convém limitar a consulta ao período que interessa. Assim a consulta é mais rápida e o gráfico não fica poluído com dados antigos. A função ago() devolve um momento no passado a partir de agora; aqui pedimos apenas as últimas 24 horas.

Leituras
| where Timestamp > ago(24h)

O resultado ainda são as linhas em bruto, uma por leitura. É o ponto de partida para o agrupamento.

Passo 2: Agrupar com summarize e bin()

A função bin() arredonda cada data/hora para o início da janela a que pertence. Por exemplo, bin(Timestamp, 15m) transforma 10:07 e 10:14 ambos em 10:00, e 10:22 em 10:15. O operador summarize usa esse valor para juntar todas as leituras da mesma janela e calcular uma métrica — neste caso, a média.

Leituras
| where Timestamp > ago(24h)
| summarize MediaValor = avg(Valor) by bin(Timestamp, 15m)

Agora cada linha representa uma janela de 15 minutos com a respetiva média. Passámos de milhares de leituras para dezenas de pontos.

Dica: o segundo argumento de bin() aceita qualquer duração — 1m, 5m, 1h, 1d. Comece largo (1h) e reduza só quando precisar de mais detalhe.

Passo 3: Agrupar por sensor e por tempo

Muitas vezes queremos a evolução por cada sensor, e não a média global. Basta acrescentar a coluna Sensor à cláusula by. O KQL cria então uma janela por cada combinação de sensor e intervalo.

Leituras
| where Timestamp > ago(24h)
| summarize MediaValor = avg(Valor) by Sensor, bin(Timestamp, 15m)

A ordem na cláusula by não altera o resultado do cálculo, mas ajuda a ler a tabela.

Passo 4: Calcular várias métricas e ordenar

Numa só consulta é possível calcular vários valores por janela. Aqui juntamos a média, o máximo e o número de leituras, e alargamos a janela para 1 hora. No fim, ordenamos por tempo para a linha temporal ficar correta.

Leituras
| where Timestamp > ago(24h)
| summarize
    MediaValor = avg(Valor),
    MaxValor   = max(Valor),
    NLeituras  = count()
    by bin(Timestamp, 1h)
| order by Timestamp asc

Repare que count() não precisa de argumentos: conta as linhas de cada janela.

Passo 5: Transformar em gráfico

Para ver a tendência de imediato, adicione o operador render. O tipo timechart assume que a primeira coluna é temporal e desenha uma linha por métrica.

Leituras
| where Timestamp > ago(24h)
| summarize MediaValor = avg(Valor) by bin(Timestamp, 1h)
| render timechart

No Real-Time Analytics, este gráfico pode ir diretamente para um painel (dashboard) e atualizar-se sozinho.

Verificar o resultado

Para confirmar que o agrupamento está correto, verifique três coisas: (1) os valores da coluna de tempo estão sempre no início da janela (por exemplo, minutos 00, 15, 30, 45 para janelas de 15m); (2) não existe nenhum Timestamp no futuro; e (3) o número de janelas faz sentido — 24 horas em janelas de 1 hora dão, no máximo, 24 linhas por sensor. Se aparecerem intervalos em falta, é porque não houve leituras nesse período — normal em dados reais.

Conclusão

Com summarize e bin() já consegue transformar dados em bruto numa série temporal pronta a analisar. O passo seguinte natural é usar make-series para preencher automaticamente as janelas sem dados (útil para gráficos contínuos) e, mais tarde, criar alertas quando a média ultrapassar um limite. Qual seria a janela de tempo ideal para os seus dados: 5 minutos, 1 hora ou 1 dia?