Como usar variáveis com let em KQL: passo a passo

Em KQL, o operador let permite dar um nome a um valor ou ao resultado de uma consulta e voltar a usá-lo quantas vezes forem precisas. Trabalhar com variáveis com let em KQL torna as consultas mais legíveis, evita repetir os mesmos números e filtros, e facilita a manutenção quando um limite ou um período muda. É uma das primeiras técnicas que compensa dominar quando se começa a escrever consultas maiores, e vais encontrá-la no início de quase todas as consultas KQL bem escritas.

Pré-requisitos

• Acesso a um ambiente que corra KQL: Azure Data Explorer, um KQL Queryset no Microsoft Fabric (Real-Time Analytics) ou Azure Monitor / Log Analytics.
• Uma tabela com alguns dados. Nos exemplos usamos uma tabela fictícia chamada Sales, com as colunas Amount, Region e Timestamp.
• Noções básicas de KQL, como os operadores where e summarize.

Passo 1: Criar a tua primeira variável com let

Uma declaração começa com a palavra let, seguida do nome, de um sinal de igual e do valor. Cada declaração let termina com ponto e vírgula, e a seguir vem a consulta que a utiliza. No exemplo, guardamos um limite numa variável e usamo-lo no filtro. O nome pode ter letras, números e underscores, e distingue maiúsculas de minúsculas.

let amountThreshold = 1000;
Sales
| where Amount > amountThreshold

Se amanhã quiseres analisar vendas acima de 5000, mudas só o número na primeira linha, em vez de o procurar no meio da consulta.

Passo 2: Guardar texto, datas e períodos

O let não serve apenas para números. Também podes guardar texto, datas e intervalos de tempo. Isto é prático para definir um período de análise uma única vez e reutilizá-lo em vários filtros.

let region = "North";
let startDate = ago(30d);
Sales
| where Region == region
| where Timestamp >= startDate

A função ago(30d) devolve o momento de há 30 dias. Ao guardá-la numa variável, garantes que todos os filtros partem exatamente do mesmo ponto no tempo.

Passo 3: Guardar o resultado de uma consulta

Uma variável com let em KQL também pode guardar uma tabela inteira, ou seja, o resultado de outra consulta. Depois usas esse nome como se fosse uma tabela normal. Assim divides uma consulta complexa em partes mais fáceis de ler, e podes encadear várias variáveis tabulares, cada uma a preparar um pedaço dos dados.

let RecentSales =
    Sales
    | where Timestamp >= ago(7d);
RecentSales
| summarize TotalByRegion = sum(Amount) by Region
| order by TotalByRegion desc

Primeiro definimos RecentSales com os dados dos últimos 7 dias. A seguir, agregamos esse resultado por região. Repara que a declaração termina com ponto e vírgula, mas a consulta final não.

Passo 4: Reutilizar e criar pequenas funções

A maior vantagem aparece quando o mesmo valor é usado mais do que uma vez. Com let, defines uma vez e referes o nome onde precisares. Podes até criar pequenas funções para cálculos repetidos.

let vatRate = 1.23;
let addVat = (value:real) { value * vatRate };
Sales
| extend AmountWithVat = addVat(Amount)
| project Region, Amount, AmountWithVat

Aqui addVat é uma função criada com let que recebe um valor e devolve-o com IVA incluído. Se a taxa mudar, alteras apenas a variável vatRate e todo o cálculo acompanha.

Dica: dá nomes descritivos às variáveis, como amountThreshold em vez de x. As consultas KQL leem-se de cima para baixo, e bons nomes poupam comentários.

Verificar o resultado

Executa cada consulta e confirma que devolve linhas sem erros. Para testar que as variáveis funcionam, muda o valor numa declaração let (por exemplo, o amountThreshold de 1000 para 5000) e corre outra vez: o número de linhas deve mudar conforme o novo filtro. Se aparecer um erro de sintaxe, confirma que cada declaração let termina com ponto e vírgula e que a consulta final não tem um ponto e vírgula a mais. Vale a pena guardar as consultas que funcionam para as reutilizares mais tarde.

Conclusão

Com o let já consegues nomear valores, guardar períodos e resultados de consultas, e criar pequenas funções para não repetir lógica. O passo seguinte é combinar variáveis tabulares com join ou union para análises mais ricas, mantendo cada parte legível. Qual é o valor que mais repetes nas tuas consultas e que podias transformar já numa variável let?