Utilizar uma extensão Jupyter Notebook e kqlmagic para analisar dados no Azure Data Explorer

Jupyter Notebook é uma aplicação Web open source que lhe permite criar e partilhar documentos que contenham código dinâmico, equações, visualizações e texto narrativo. É útil para uma vasta gama de tarefas, como limpeza e transformação de dados, simulação numérica, modelação estatística, visualização de dados e machine learning.

O Kqlmagic expande as capacidades do kernel do Python no Jupyter Notebook para que possa executar consultas Linguagem de Pesquisa Kusto (KQL) nativamente. Pode combinar Python e KQL para consultar e visualizar dados com a biblioteca de Plot.ly avançada integrada com o operador de composição . A extensão kqlmagic é compatível com o Jupyter Lab, a extensão Jupyter do Visual Studio Code e o Azure Data Studio e as origens de dados suportadas incluem o Azure Data Explorer, os registos do Azure Monitor e o Application Insights.

Neste artigo, irá aprender a utilizar kqlmagic numa Jupyter Notebook para ligar e consultar dados armazenados no Azure Data Explorer.

Pré-requisitos

• Uma conta Microsoft ou uma identidade de utilizador Microsoft Entra. Não é necessária uma subscrição do Azure.
• Jupyter Notebook instalado no seu computador local. Caso contrário, utilize o Azure Data Studio.
• Python 3.6. Para alterar a versão Jupyter Notebook kernel para Python 3.6, selecione KernelAlterar Kernel>>Python 3.6.

Instalar kqlmagic

Depois de instalar e carregar a extensão kqlmagic, pode escrever consultas KQL no seu bloco de notas. Se o kernel parar ou os resultados não forem os esperados, recarregue a extensão kqlmagica.

1. Para instalar o kqlmagic, execute o seguinte comando:

   !pip install Kqlmagic --no-cache-dir  --upgrade
   

2. Para carregar a extensão kqlmagic, execute o seguinte comando:

   %reload_ext Kqlmagic
   

Ligar a um cluster

Selecione o separador do seu método preferencial para ligar ao cluster.

%kql AzureDataExplorer://code;cluster='<cluster-name>';database='<database-name>'

%kql AzureDataExplorer://tenant='<tenant-id>';clientid='<aad-appid>';clientsecret='<aad-appkey>';cluster='<cluster-name>';database='<database-name>'

%kql AzureDataExplorer://username='<username>';password='<password>';cluster='<cluster-name>';database='<database-name>'

%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'

%kql azureDataExplorer://anonymous;cluster='<cluster-name>';database='<database-name>'

Exemplo de ligação de cluster

O comando seguinte utiliza o método de código Microsoft Entra para autenticar na Samples base de dados alojada no help cluster. Para utilizadores que não Microsoft Entra, substitua o nome Microsoft.com do inquilino pelo seu inquilino Microsoft Entra.

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

Opções de ligação

Para simplificar o processo de obtenção de credenciais, pode adicionar um dos seguintes sinalizadores de opção após o cadeia de ligação.

Exemplo de opção de ligação

Qualquer uma das opções descritas na tabela anterior pode ser adicionada após uma cadeia de ligação. O exemplo seguinte utiliza a opção de início de sessão da CLI do Azure:

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

Apresentar informações de ligação

Para ver todas as ligações existentes, execute o seguinte comando:

%kql --conn

Para verificar os detalhes de uma ligação específica, execute o seguinte comando:

%kql --conn <database-name>@<cluster-name>

Consultar e visualizar

Consultar dados com o operador de composição e visualizar dados com a biblioteca de ploy.ly. Esta consulta e visualização fornecem uma experiência integrada que utiliza KQL nativo. O Kqlmagic suporta a maioria dos gráficos, exceto timepivot, pivotcharte ladderchart. A composição é suportada com todos os atributos, exceto kind, ysplite accumulate.

Consultar e compor gráfico circular

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take10
| render piechart title="My Pie Chart by State"

Consultar e compor o tempograma

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

Personalizar as cores do gráfico

Se não gostar da paleta de cores predefinida, personalize os gráficos com as opções de paleta. As paletas disponíveis podem ser encontradas aqui: selecione a paleta de cores para o resultado do gráfico de consultas kqlmagico

1. Para obter uma lista de paletas:

   %kql --palettes -popup_window
   

2. Selecione a cool paleta de cores e volte a compor a consulta:

   %%kql -palette_name "cool"
   StormEvents
   | summarize statecount=count() by State
   | sort by statecount
   | take10
   | render piechart title="My Pie Chart by State"
   

Parametrizar uma consulta com Python

O Kqlmagic permite um intercâmbio simples entre Linguagem de Pesquisa Kusto e Python. Para saber mais: Parametrizar a consulta kqlmagica com Python

Utilizar uma variável Python na consulta KQL

Pode utilizar o valor de uma variável Python na consulta para filtrar os dados:

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

Converter resultados de consulta em DataFrame do Pandas

Pode aceder aos resultados de uma consulta KQL no Pandas DataFrame. Aceda aos resultados da última consulta executada por variável _kql_raw_result_ e converta facilmente os resultados em DataFrame do Pandas da seguinte forma:

df = _kql_raw_result_.to_dataframe()
df.head(10)

Exemplo

Em muitos cenários de análise, poderá querer criar blocos de notas reutilizáveis que contenham muitas consultas e alimentar os resultados de uma consulta em consultas subsequentes. O exemplo abaixo utiliza a variável statefilter Python para filtrar os dados.

1. Execute uma consulta para ver os 10 principais estados com o máximo DamageProperty:

   %%kql
   StormEvents
   | summarize max(DamageProperty) by State
   | order by max_DamageProperty desc
   | take10
   

2. Execute uma consulta para extrair o estado superior e defina-a numa variável python:

   df = _kql_raw_result_.to_dataframe()
   statefilter =df.loc[0].State
   statefilter
   

3. Execute uma consulta com a let instrução e a variável Python:

   %%kql
   let _state = statefilter;
   StormEvents 
   | where State in (_state)
   | summarize statecount=count() by bin(StartTime,1d), State
   | render timechart title = "Trend"
   

4. Execute o comando de ajuda:

   %kql --help "help"
   

Blocos de notas de exemplo

• Introdução ao kqlmagic para o Azure Data Explorer
• Introdução ao kqlmagic para o Application Insights
• Introdução ao kqlmagic para registos do Azure Monitor
• Parametrizar a consulta kqlmagica com Python
• Escolher paleta de cores para o resultado do gráfico de consultas kqlmagic

Conteúdo relacionado

• Learn Linguagem de Pesquisa Kusto (KQL)