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

  • Artigo

Jupyter Notebook é um aplicativo Web de software livre que permite criar e compartilhar documentos que contêm código dinâmico, equações, visualizações e texto narrativo. É útil para uma ampla variedade 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 jupyter Visual Studio Code 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 kqlmagic em um Jupyter Notebook para se conectar e consultar dados armazenados no Azure Data Explorer.

Pré-requisitos

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

Instalar kqlmagic

Depois de instalar e carregar a extensão kqlmagic, você poderá escrever consultas KQL em seu notebook. Se o kernel for interrompido 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.

O método de código Microsoft Entra solicita a entrada interativa da MSAL. Você receberá um código a ser inserido para autenticação.

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

Dica

  • Para parametrizar o cadeia de conexão, use valores não citados, pois eles são interpretados como expressões python.
  • Para simplificar o processo de obtenção de credenciais, consulte Opções de conexão.

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 não Microsoft Entra, substitua o nome Microsoft.com do locatário pelo locatário 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 sinalizadores de opção a seguir após o cadeia de conexão.

Opção Descrição Sintaxe de exemplo
try_azcli_login Tente obter credenciais de autenticação da CLI do Azure. -try_azcli_login
try_azcli_login_subscription Tente obter credenciais de autenticação da CLI do Azure com base na assinatura especificada. -try_azcli_login_subscription=<subscription_id>
try_vscode_login Tente obter credenciais de autenticação de Visual Studio Code entrada da conta do Azure. -try_vscode_login
try_msi Tente obter credenciais de autenticação do ponto de extremidade local da MSI. Espera um dicionário com os parâmetros msi opcionais: resource, client_id/object_idmis_res_id/, , . timeoutcloud_environment -try_msi={"client_id":<id>}
try_token Autenticar com um token especificado. Espera um dicionário com Azure AD propriedades de token v1 ou v2. -try_token={"tokenType":"bearer","accessToken":"<token>"}

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 marcar 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

Observação

Os gráficos são interativos. Selecione um intervalo de tempo para ampliar um horário específico.

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 um intercâmbio simples entre Linguagem de Consulta Kusto 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"

Dica

Para receber informações sobre todas as configurações disponíveis, use %config Kqlmagic. Para solucionar problemas e capturar erros do Kusto, como problemas de conexão e consultas incorretas, use %config Kqlmagic.short_errors=False

Notebooks de exemplo

Conteúdo relacionado