Compartilhar via

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

  • Artigo

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.

Observação

Recomendamos o uso do método de autenticação Certificate quando possível.

O certificado do Microsoft Entra deve ser armazenado em um arquivo acessível a partir do bloco de anotações. Esse arquivo pode ser referenciado na cadeia de conexão.

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

Dica

  • Para parametrizar a cadeia de conexão, use valores sem aspas à medida que 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 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.

Opção Descrição Exemplo de sintaxe
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 da entrada na conta do Visual Studio Code Azure. -try_vscode_login
try_msi Tente obter credenciais de autenticação do ponto de extremidade local MSI. Espera um dicionário com os parâmetros MSI opcionais: resource,object_idmis_res_id//client_id , cloud_environmenttimeout, . -try_msi={"client_id":<id>}
try_token Autenticar com um token especificado. Espera um dicionário com propriedades de token do Azure AD 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 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

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

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