Instrução LET
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel
Uma let instrução é usada para definir um nome de variável igual a uma expressão ou 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 let instrução associa um nome a um 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 | Digitar | Obrigatória | Descrição |
|---|---|---|---|
| Nome | string |
✔️ | O nome da variável. Você pode escapar o nome com colchetes. Por exemplo, ["Name with spaces"]. |
| Expressão | 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 | Digitar | Obrigatória | 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.
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.
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.
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).
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.
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.
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á.
let CountRecordsInTable=(T: (*)) { T | count };
StormEvents | invoke CountRecordsInTable()
Saída
| Contagem |
|---|
| 59.066 |