Instrução LET

A instrução let é usada para definir um nome de variável igual a uma expressão ou uma função ou para criar exibições.

As instruções let são úteis para:

• Dividir uma expressão complexa em várias partes, cada uma representada por uma variável.
• Definir constantes fora do corpo da consulta para facilitar a leitura.
• Definir uma variável uma vez e usá-la várias vezes em uma consulta.

Se a variável anteriormente representasse outro valor, por exemplo, em instruções aninhadas, a instrução let mais interna se aplicará.

Para otimizar vários usos da instrução let em uma única consulta, confira Otimizar consultas que usam expressões nomeadas.

Observação

A instrução let associa o nome ao cálculo, não ao valor avaliado desse cálculo. Esse comportamento significa que várias referências ao mesmo nome podem retornar valores diferentes devido ao cálculo ser avaliado várias vezes. Se esse não for o comportamento desejado, use toscalar() ou materialize().

Sintaxe: expressões escalares ou tabulares

letNome=Expressão

Importante

As instruções LET devem ser seguidas por um ponto e vírgula. Não pode haver linhas em branco entre instruções LET ou entre instruções LET e outras instruções de consulta.

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
Nome	string	✔️	O nome da variável. Você pode escapar o nome com colchetes. Por exemplo, ["Name with spaces"].
Expression	string	✔️	Uma expressão com um resultado escalar ou tabular. Por exemplo, uma expressão com um resultado escalar seria let one=1;e uma expressão com um resultado tabular seria let RecentLog = Logs | where Timestamp > ago(1h).

Sintaxe: exibição ou função

letNome= [view] ([ Parâmetros ]){FunctionBody}

Importante

As instruções LET devem ser seguidas por um ponto e vírgula. Não pode haver linhas em branco entre instruções LET ou entre instruções LET e outras instruções de consulta.

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
FunctionBody	string	✔️	Uma expressão que produz uma função definida pelo usuário.
view	string		Relevante apenas para uma instrução let sem parâmetros. Quando usada, a instrução let é incluída em consultas com um operador union com seleção de curinga das tabelas/exibições. Para obter um exemplo, confira Criar uma exibição ou tabela virtual.
Parâmetros	string		Zero ou mais parâmetros de função escalar ou tabular separados por vírgulas. Para cada parâmetro do tipo tabular, o parâmetro deve estar no formato TableName:TableSchema, no qual TableSchema é uma lista separada por vírgulas de colunas no formato ColumnName:ColumnType ou um curinga (*). Se as colunas forem especificadas, o argumento tabular de entrada deverá conter essas colunas. Se um curinga for especificado, o argumento tabular de entrada poderá ter qualquer esquema. Para referenciar colunas no corpo da função, elas precisam ser especificadas. Para obter exemplos, confira Argumento tabular com esquema e Argumento tabular com curinga. Para cada parâmetro do tipo escalar, forneça o nome e o tipo de parâmetro no formato Nome:Tipo. O nome pode aparecer em FunctionBody e está associado a um valor específico quando a função definida pelo usuário é invocada. Os únicos tipos com suporte são bool, string, long, datetime, timespan, real, dynamic e os aliases para esses tipos.

Observação

• Os parâmetros tabulares precisam aparecer antes dos parâmetros escalares.
• Duas instruções devem ser sempre separadas por ponto e vírgula.

Exemplos

Definir valores escalares

O exemplo a seguir usa uma instrução de expressão escalar.

let n = 10;  // number
let place = "Dallas";  // string
let cutoff = ago(62d); // datetime 
Events 
| where timestamp > cutoff 
    and city == place 
| take n

O exemplo a seguir associa o nome some number usando a notação ['name'] e, em seguida, o usa em uma instrução de expressão tabular.

Executar a consulta

let ['some number'] = 20;
range y from 0 to ['some number'] step 5

Criar uma função definida pelo usuário com cálculo escalar

Esse exemplo usa a instrução let com argumentos para o cálculo escalar. A consulta define a função MultiplyByN para multiplicar dois números.

Executar a consulta

let MultiplyByN = (val:long, n:long) { val * n };
range x from 1 to 5 step 1 
| extend result = MultiplyByN(x, 5)

Saída

x	result
1	5
2	10
3	15
4	20
5	25

Criar uma função definida pelo usuário que corta a entrada

O exemplo a seguir remove os itens à esquerda e à direita da entrada.

Executar a consulta

let TrimOnes = (s:string) { trim("1", s) };
range x from 10 to 15 step 1 
| extend result = TrimOnes(tostring(x))

Saída

x	result
10	0
11
12	2
13	3
14	4
15	5

Usar múltiplas instruções let

Este exemplo define duas instruções let nas quais uma instrução (foo2) usa outra (foo1).

Executar a consulta

let foo1 = (_start:long, _end:long, _step:long) { range x from _start to _end step _step};
let foo2 = (_step:long) { foo1(1, 100, _step)};
foo2(2) | count

Saída

result
50

Criar uma exibição ou tabela virtual

Este exemplo mostra como usar uma instrução let para criar uma viewou tabela virtual.

Executar a consulta

let Range10 = view () { range MyColumn from 1 to 10 step 1 };
let Range20 = view () { range MyColumn from 1 to 20 step 1 };
search MyColumn == 5

Saída

$table	MyColumn
Range10	5
Range20	5

Usar uma função materialize

A função materialize() permite que você armazene em cache os resultados da subconsulta durante o tempo da execução da consulta. Quando você usa a função materialize(), os dados são armazenados em cache e qualquer invocação subsequente do resultado usa dados armazenados em cache.

let totalPagesPerDay = PageViews
| summarize by Page, Day = startofday(Timestamp)
| summarize count() by Day;
let materializedScope = PageViews
| summarize by Page, Day = startofday(Timestamp);
let cachedResult = materialize(materializedScope);
cachedResult
| project Page, Day1 = Day
| join kind = inner
(
    cachedResult
    | project Page, Day2 = Day
)
on Page
| where Day2 > Day1
| summarize count() by Day1, Day2
| join kind = inner
    totalPagesPerDay
on $left.Day1 == $right.Day
| project Day1, Day2, Percentage = count_*100.0/count_1

Saída

Dia1	Dia2	Porcentagem
2016-05-01 00:00:00.0000000	2016-05-02 00:00:00.0000000	34.0645725975255
2016-05-01 00:00:00.0000000	2016-05-03 00:00:00.0000000	16.618368960101
2016-05-02 00:00:00.0000000	2016-05-03 00:00:00.0000000	14.6291376489636

Usar instruções let aninhadas

Instruções let aninhadas são permitidas, inclusive dentro de uma expressão de função definida pelo usuário. Os argumentos e as instruções let se aplicam ao escopo atual e interno do corpo da função.

let start_time = ago(5h); 
let end_time = start_time + 2h; 
T | where Time > start_time and Time < end_time | ...

Argumento tabular com esquema

O exemplo a seguir especifica que o parâmetro tabela T precisa ter uma coluna State do tipo string. A tabela T talvez pode incluir outras colunas, mas elas não podem ser referenciadas na função StateState porque não são declaradas.

Executar a consulta

let StateState=(T: (State: string)) { T | extend s_s=strcat(State, State) };
StormEvents
| invoke StateState()
| project State, s_s

Saída

Estado	s_s
ATLÂNTICO SUL	ATLANTIC SOUTHATLANTIC SOUTH
FLÓRIDA	FLORIDAFLORIDA
FLÓRIDA	FLORIDAFLORIDA
GEÓRGIA	GEORGIAGEORGIA
MISSISSIPI	MISSISSIPPIMISSISSIPPI
...	...

Argumento tabular com curinga

O parâmetro de tabela T pode ter qualquer esquema, e a função CountRecordsInTable funcionará.

Executar a consulta

let CountRecordsInTable=(T: (*)) { T | count };
StormEvents | invoke CountRecordsInTable()

Saída

Contagem
59.066