Exercício – Introduzir variáveis usando a instrução let

Concluído

Usamos um conjunto de dados meteorológicos para agregar e visualizar dados. Aqui, você aprenderá a usar instruções let para introduzir variáveis e organizar consultas complexas.

As instruções let são úteis para dividir uma expressão complexa em várias partes, definir constantes fora do corpo da consulta para legibilidade ou definir uma variável uma vez e usá-la várias vezes dentro de uma consulta. Use instruções let para criar consultas complexas bem organizadas. É possível usar várias instruções let, e cada uma precisa ser seguida por ponto e vírgula (;).

É possível usar instruções let em diferentes tipos de situações. No nível mais simples, você pode definir valores escalares que serão referenciados posteriormente em uma consulta, como um valor int, de cadeia de caracteres, de data/hora ou qualquer outro valor. Você pode criar uma exibição filtrada tabular de uma tabela que será usada como a entrada tabular para a consulta. Você também pode criar uma função usando uma instrução let.

Definir um escalar com uma instrução let

Lembre-se de que as consultas anteriores filtravam com base em locais ou danos mínimos. Vamos definir esses valores de limite usando uma instrução let no início da consulta.

A consulta a seguir usa duas instruções let para definir valores escalares que serão usados posteriormente como parâmetros de entrada na consulta. O primeiro valor definido é um número e o segundo é uma cadeia de caracteres. As instruções let terminam com ponto e vírgula.

Observe as partes comentadas da consulta que começam com barras duplas (//). Barras duplas indicam o início de um comentário até o final da linha. Esses comentários são ignorados ao executar consultas.

1. Execute a seguinte consulta:

   Executar a consulta

   let MinDamage = 1; // int
   let EventLocation = "ARIZONA"; // string
   StormEvents
   | where State == EventLocation
   | where DamageCrops + DamageProperty >= MinDamage
   | summarize Damage=round(avg(DamageProperty + DamageCrops)) by EventType
   | sort by Damage
   

   Você deve obter resultados parecidos com a seguinte imagem:

   

2. Tente alterar o nome do estado ou os números mínimos de danos e executar novamente a consulta. Como os resultados mudam?

Converter um resultado tabular em valor escalar usando toscalar dentro de uma instrução let

Em seguida, vamos examinar uma contagem do tipo de evento mais frequente como uma função do tempo. Primeiro, você precisa descobrir qual é o tipo de evento mais frequente. Em seguida, você usará esse valor em uma consulta. Use a tabela StormEvents para localizar o principal EventType contando o número de eventos dentro de cada tipo. Use o operador project para retornar apenas a coluna EventType.

Antes de começar a construir a instrução let, execute a consulta para descobrir o que esse evento de fato é. Isso permite verificar se sua consulta está produzindo os resultados esperados.

Executar a consulta

StormEvents
| summarize count() by EventType
| top 1 by count_
| project EventType

Você deve obter resultados parecidos com a seguinte imagem:

Você observará que a consulta produziu um resultado tabular com uma coluna e uma linha. No entanto, é necessário convertê-lo em um valor escalar a ser usado como valor de filtro em sua consulta principal. Primeiro, defina o nome da variável que queremos introduzir como MostFrequentEventType. Em seguida, converta o resultado tabular em um valor escalar colocando toda a consulta dentro da função toscalar().

As etapas anteriores estão resumidas na seguinte instrução let:

let MostFrequentEventType = toscalar(
    StormEvents
    | summarize count() by EventType
    | top 1 by count_
    | project EventType);

Observe que essa instrução por si só não é uma consulta válida, pois uma consulta válida deve conter pelo menos uma instrução que não seja uma instrução let. No entanto, você pode usar esse valor escalar armazenado em uma consulta. Lembre-se de que você quer examinar uma contagem do tipo de evento mais frequente como uma função do tempo. Você filtrará em MostFrequentEventType e, em seguida, resumirá a contagem por um determinado compartimento de tempo.

Nesse caso, vamos ver os resultados por mês. Você usará a função startofmonth(), que retorna um datetime que representa o início do mês para o valor de data fornecido. Nesta consulta, você usará a coluna StartTime como entrada para a função startofmonth().

Por fim, renderize os resultados como um gráfico de colunas para obter um histograma da contagem do tipo de evento mais frequente compartimentado por mês.

1. Execute a seguinte consulta:

   Executar a consulta

   let MostFrequentEventType = toscalar(
       StormEvents
       | summarize count() by EventType
       | top 1 by count_
       | project EventType);
   StormEvents
   | where EventType == MostFrequentEventType
   | summarize count() by startofmonth(StartTime)
   | render columnchart
   

   Você deve obter resultados parecidos com a seguinte imagem:

   

2. Tente alterar a consulta para mostrar um histograma do tipo de evento menos frequente compartimentado por mês e executando a consulta novamente.

Construir uma instrução let com saída tabular

Os exemplos anteriores criaram um valor escalar armazenado a ser usado como um parâmetro de entrada em uma consulta. No entanto, também é possível usar uma instrução let para criar dados tabulares que são usados como a entrada para uma consulta.

1. Filtre a tabela StormEvents segundo eventos que causaram mortes indireta ou diretamente. Em seguida, retorne um subconjunto das colunas usando o operador project. Esta instrução fornece uma saída tabular chamada KillerStorms. Use esta instrução let como a entrada inicial para a consulta.

   let KillerStorms =
       StormEvents
       | where DeathsDirect + DeathsIndirect > 0
       | project State, EventType, Deaths=DeathsDirect + DeathsIndirect;
   

2. Em seguida, você pode usar algumas das funções de agregação que aprendeu em unidades anteriores. Execute a seguinte consulta:

   Executar a consulta

   let KillerStorms =
       StormEvents
       | where DeathsDirect + DeathsIndirect > 0
       | project State, EventType, Deaths=DeathsDirect + DeathsIndirect;
   KillerStorms
   | summarize DistinctKillerEventTypes=dcount(EventType), TotalDeaths=sum(Deaths) by State
   | sort by TotalDeaths
   

   Você deve obter resultados parecidos com a seguinte imagem:

   

3. Observe os resultados. Todos os eventos resumidos na coluna DistinctKillerEventTypes são realmente denominados "tempestades assassinas"?

Criar uma função definida pelo usuário com a instrução let

Você também pode usar instruções let para definir funções definidas pelo usuário, que são subconsultas reutilizáveis. Suponha que você queira descobrir qual porcentagem de cada tipo de evento causou danos. Você criará uma função definida pelo usuário que calcula porcentagens e, mais tarde, chamará essa função e especificará quais colunas devem ser usadas para calcular a porcentagem.

Em uma instrução let, você declarará o nome da função, os argumentos e o corpo usando a seguinte sintaxe geral:

let function=(argument1:datatype, argument2:datatype) {functionbody};

Especificamente, você usará uma função definida pelo usuário para calcular percentuais. Primeiro, defina o tipo de dados e os argumentos de entrada. Para este exemplo, você usará os seguintes argumentos:

Nome do argumento	Tipo de dados	Descrição
portion	real	A parte do total de eventos dos quais você deseja calcular o percentual.
total	real	O número total de eventos.

Você arredondará a resposta para duas casas decimais usando a função round().

Ao todo, a função definida pelo usuário descrita pela instrução let é:

let Pcent = (portion:real, total:real){round(100 * portion / total, 2)};

1. Use esta instrução let na seguinte consulta:

   Executar a consulta

   let Pcent = (portion: real, total: real) { round(100 * portion / total, 2) };
   StormEvents
   | extend Damage = DamageCrops + DamageProperty
   | summarize TotalEvents = count(), TotalDamagingEvents = countif(Damage > 0) by EventType
   | project EventType, TotalDamagingEvents, TotalEvents, Percentage = Pcent(TotalDamagingEvents, TotalEvents)
   | sort by EventType asc
   

   Você deve obter resultados parecidos com a seguinte imagem:

   

2. Dedique algum tempo a entender os resultados. Tente modificar a consulta para mostrar um detalhamento da porcentagem por tipo de danos e executar a consulta novamente.

Confira os resultados. O que a porcentagem significa? Observe que a consulta chama a função Pcent, que definimos na instrução let. As entradas usadas nessa função são TotalDamagingEvents e TotalEvents, o que significa que você está procurando a porcentagem de eventos que causaram danos.