Usar um Jupyter Notebook e a extensão kqlmagic para analisar dados no Azure Data Explorer

Jupyter Notebook é um aplicativo web de código aberto que permite criar e compartilhar documentos contendo código dinâmico, equações, visualizações e texto narrativo. É útil para uma ampla gama de tarefas, como limpeza e transformação de dados, simulação numérica, modelagem estatística, visualização de dados e aprendizado de máquina.

O Kqlmagic estende os recursos do kernel do Python no Jupyter Notebook para que você possa executar consultas da Linguagem de Consulta Kusto (KQL) nativamente. Você pode combinar Python e KQL para consultar e visualizar dados usando a biblioteca avançada Plot.ly integrada ao operador de renderização. A extensão kqlmagic é compatível com o Jupyter Lab, a extensão Visual Studio Code Jupyter e o Azure Data Studio, e as fontes de dados com suporte incluem o Azure Data Explorer, os logs do Azure Monitor e o Application Insights.

Neste artigo, você aprenderá a usar o kqlmagic em um Bloco de Anotações Jupyter para se conectar e consultar dados armazenados no Azure Data Explorer.

Pré-requisitos

• Uma conta da Microsoft ou uma identidade de usuário do Microsoft Entra. Uma assinatura do Azure não é necessária.
• Jupyter Notebook instalado em sua máquina local. Caso contrário, use o Azure Data Studio.
• Python 3.6. Para alterar a versão do kernel do Jupyter Notebook para Python 3.6, selecione Kernel>Change Kernel>Python 3.6.

Instalar o kqlmagic

Depois de instalar e carregar a extensão kqlmagic, você pode escrever consultas KQL em seu notebook. Se o kernel parar ou os resultados não forem os esperados, recarregue a extensão kqlmagic.

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
   

Conectar a um cluster

Selecione a guia do método preferido para se conectar ao cluster.

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

%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://anonymous;cluster='<cluster-name>';database='<database-name>'

Exemplo de conexão de cluster

O comando a seguir usa o método de código Microsoft Entra para autenticar no Samples banco de dados hospedado no help cluster. Para usuários que não são do Microsoft Entra, substitua o nome Microsoft.com do locatário pelo locatário do Microsoft Entra.

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

Opções de conexão

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

Exemplo de opção de conexão

Qualquer uma das opções descritas na tabela anterior pode ser adicionada após uma cadeia de conexão. O exemplo a seguir usa a opção de entrada da CLI do Azure:

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

Exibir informações de conexão

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

%kql --conn

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

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

Consultar e visualizar

Consulte de dados usando o operador renderizar e visualize dados usando a biblioteca ploy.ly. Essa consulta e visualização fornece uma experiência integrada que usa um KQL nativo. O Kqlmagic dá suporte a maioria dos gráficos, exceto timepivot, pivotchart, e ladderchart. A renderização é compatível com todos os atributos, exceto kind, ysplit, e accumulate.

Consultar e renderizar o gráfico de pizza

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

Consultar e renderizar o gráfico de tempo

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

Personalizar a legenda de cores

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

1. Para uma lista de paletas:

   %kql --palettes -popup_window
   

2. Selecione a paleta de corescool e renderize a consulta novamente:

   %%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 o intercâmbio simples entre Kusto Query Language e Python. Para saber mais: parametrizar a consulta do kqlmagic com o Python

Usar uma variável de Python em sua consulta KQL

Use o valor de uma variável de Python em sua 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 os resultados da consulta em DataFrame do Pandas

Você pode acessar os resultados de uma consulta KQL no DataFrame Pandas. Acesse os últimos resultados da consulta executada pela variável _kql_raw_result_ e converta facilmente os resultados em DataFrame Pandas da seguinte maneira:

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

Exemplo

Em muitos cenários de análise, você talvez queira criar blocos de anotações reutilizáveis que contêm muitas consultas e alimentam os resultados de uma consulta em consultas subsequentes. O exemplo a seguir usa a variável de Python statefilter para filtrar os dados.

1. Executar uma consulta para exibir os estados de 10 principais com 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-o em uma variável de Python:

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

3. Executar uma consulta usando a instrução let e a variável de 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"
   

Notebooks de exemplo

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

Conteúdo relacionado

• Aprenda Kusto Query Language (KQL)