Usar um Bloco de Anotações e kqlmagic para analisar dados no Azure Data Explorer

Jupyter Notebook é uma aplicação web de código aberto que permite criar e compartilhar documentos contendo código ao vivo, 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 Python no Jupyter Notebook para que você possa executar consultas Kusto Query Language (KQL) nativamente. Você pode combinar Python e KQL para consultar e visualizar dados usando a biblioteca de Plot.ly avançada integrada com o 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 suportadas incluem o Azure Data Explorer, logs do Azure Monitor e Application Insights.

Neste artigo, saiba como usar a extensão Kqlmagic em um Bloco de Anotações para se conectar e consultar dados armazenados no Azure Data Explorer.

Pré-requisitos

• Uma conta Microsoft ou uma identidade de utilizador do Microsoft Entra. Uma assinatura do Azure não é necessária.
• Um Notebook instalado na 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 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
   

Ligar a um cluster

Selecione a guia do seu 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 uma conexão de cluster

O comando a seguir usa o método de código Microsoft Entra para autenticar no banco de dados Samples hospedado no cluster help. 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 ligaçã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 uma conexão usando a CLI do Azure

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 como o método de autenticação:

%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 dados usando o operador de renderização e visualize dados usando a biblioteca de ploy.ly. Essa consulta e visualização fornecem uma experiência integrada que usa KQL nativo.

Kqlmagic suporta a maioria dos gráficos, exceto timepivot, pivotcharte ladderchart. A renderização é suportada com todos os atributos, exceto kind, ysplite accumulate.

Consultar e renderizar piechart

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

Consultar e renderizar gráfico temporal

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

Personalizar as cores do gráfico

Se você 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 consulta kqlmagic

1. Para obter uma lista de paletas:

   %kql --palettes -popup_window
   

2. Selecione a paleta de cool cores e renderize a consulta novamente:

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

Parametrizar uma consulta com Python

O Kqlmagic permite um intercâmbio simples entre Kusto Query Language e Python. Para saber mais: Parametrize sua consulta kqlmagic com Python

Use uma variável Python em sua consulta KQL

Você pode usar o valor de uma variável 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 resultados de consulta em Pandas DataFrame

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

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

Exemplo

Em muitos cenários de análise, convém criar blocos de anotações reutilizáveis que contenham muitas consultas e alimentem os resultados de uma consulta em consultas subsequentes. O exemplo abaixo usa a variável statefilter Python para filtrar os dados.

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

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

2. Execute uma consulta para extrair o estado superior e defini-lo em uma variável Python:

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

3. Execute uma consulta usando 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 help:

   %kql --help "help"
   

Blocos de notas de exemplo

• Introdução ao kqlmagic para Azure Data Explorer
• Introdução ao kqlmagic for Application Insights
• Comece a usar o kqlmagic para logs do Azure Monitor
• Parametrize sua consulta kqlmagic com Python
• Escolha a paleta de cores para o resultado do gráfico de consulta kqlmagic

Conteúdo relacionado

• Aprenda Kusto Query Language (KQL)