使用 Notebook 和 kqlmagic 分析Azure Data Explorer中的数据

Jupyter Notebook是一个开源 Web 应用程序，可用于创建和共享包含实时代码、公式、可视化效果和叙述文本的文档。它适用于各种任务，例如数据清理和转换、数值模拟、统计建模、数据可视化和machine learning。

Kqlmagic在 Jupyter Notebook 中扩展 Python 内核的功能，用于本地运行 Kusto 查询语言（KQL）查询。你可以结合使用 Python 和 KQL，并利用与 render 运算符集成的丰富的 Plot.ly 库来查询和可视化数据。 Kqlmagic 扩展与 Jupyter Lab 兼容，Visual Studio Code Jupyter 扩展，支持的数据源包括Azure Data Explorer、Azure Monitor 日志和 Application Insights。

在本文中，了解如何使用 Notebook 中的 Kqlmagic 扩展连接到 Azure Data Explorer 中存储的数据并对其进行查询。

Prerequisites

Microsoft 帐户或 Microsoft Entra 用户标识。不需要Azure订阅。
已在本地计算机上安装 Notebook。
Python 3.6。若要将Jupyter Notebook内核版本更改为 Python 3.6，请选择 Kernel>Change Kernel>Python 3.6。

安装 kqlmagic

安装并加载 kqlmagic 扩展后，可以在笔记本中编写 KQL 查询。如果内核停止或结果不符合预期，请重新加载 kqlmagic 扩展。

若要安装 kqlmagic，请运行以下命令：

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

若要加载 kqlmagic 扩展，请运行以下命令：
```
%reload_ext Kqlmagic
```

连接到群集

选择用于连接群集的首选方法的选项卡。

Note

建议尽可能使用证书身份验证方法。

Microsoft Entra 证书应存储在可从笔记本访问的文件中。可以在connection string中引用此文件。

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

Microsoft Entra 代码方法会提示Microsoft身份验证库（MSAL）交互式登录。你会收到用于身份验证输入的代码。

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

Microsoft Entra 应用程序方法允许使用 Microsoft Entra 应用程序 ID 和密钥进行非交互式登录。

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

Microsoft Entra 用户名和密码方法仅适用于企业网络。如果提供了用户名但未提供密码，则系统会提示用户提供密码。

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

匿名身份验证相当于无身份验证，仅支持用于本地群集。

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

Tip

若要参数化connection string，请使用无引号的值，因为它们被解释为 Python 表达式。
若要简化获取凭据的过程，请参阅连接选项。

群集连接示例

以下命令使用 Microsoft Entra 代码方法对 Samples 群集上托管的 help 数据库进行身份验证。对于非 Microsoft Entra 用户，请将租户名称 Microsoft.com 替换为 Microsoft Entra 租户。

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

连接选项

为了简化获取凭据的过程，可以在connection string后添加以下选项标志之一。

Option	Description	示例语法
try_azcli_login	尝试从Azure CLI获取身份验证凭据。期望您已使用 Azure CLI 登录。请参阅使用 Azure CLI 的连接示例。	`-try_azcli_login`
try_azcli_login_subscription	尝试根据指定的订阅从Azure CLI获取身份验证凭据。	`-try_azcli_login_subscription=<subscription_id>`
try_vscode_login	尝试从 Visual Studio Code Azure 帐户登录获取身份验证凭据。	`-try_vscode_login`
try_msi	尝试从 MSI 本地终结点获取身份验证凭据。需要一个包含可选 MSI 参数的字典：`resource`、`client_id`/`object_id`/`mis_res_id`、`cloud_environment`、`timeout`。	`-try_msi={"client_id":<id>}`
try_token	使用指定的令牌进行身份验证。需要具有 Azure AD v1 或 v2 令牌属性的字典。	`-try_token={"tokenType":"bearer","accessToken":"<token>"}`

使用 Azure CLI 的连接示例

可以将上表中所述的任何选项添加到连接字符串后。以下示例使用 Azure CLI 登录选项作为身份验证方法：

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

Note

此选项假定已使用Azure CLI登录到Azure。如果未登录，弹出窗口会提示你登录到Azure。

显示连接信息

若要查看所有现有连接，请运行以下命令：

%kql --conn

若要检查特定连接的详细信息，请运行以下命令：

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

查询和可视化

使用 render 运算符查询数据并使用 ploy.ly 库可视化数据。此查询和可视化操作提供了使用本机 KQL 的集成体验。

Kqlmagic 支持大多数图表，但是 timepivot、pivotchart 和 ladderchart 除外。除 kind、ysplit 和 accumulate 之外的所有属性都支持 Render。

查询和渲染饼图

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

查询和呈现时间表

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

Note

这些图表是交互式的。选择时间范围可放大到特定时间。

自定义图表颜色

如果不喜欢默认调色板，可使用调色板选项自定义图表。在此处可找到可用的调色板：针对 kqlmagic 查询图表结果选择调色板

调色板列表如下：
```
%kql --palettes -popup_window
```

选择 cool 调色板并重新呈现查询：

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

使用 Python 将查询参数化

Kqlmagic 可用于在 Kusto 查询语言与 Python 之间进行简单的交换。若要了解详细信息，请访问以下链接：使用 Python 将 kqlmagic 查询参数化

在 KQL 查询中使用 Python 变量

可在查询中使用 Python 变量的值来筛选数据：

statefilter = ["TEXAS", "KANSAS"]

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

将查询结果转换到 Pandas DataFrame

可以在 Pandas 数据帧中访问 KQL 查询的结果。访问变量 _kql_raw_result_ 上次执行的查询结果，并可轻松将结果转换为 Pandas 数据框，如下所示：

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

Example

在很多分析方案中，可能需要创建包含多个查询的可复用笔记本，并将结果从一个查询馈送到后续查询中。以下示例使用 Python 变量 statefilter 来筛选数据。

运行查询以查看最大值为 DamageProperty 的前 10 个状态：

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

运行查询以提取第一个状态并将其设置到 Python 变量中：

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

使用 let 语句和 Python 变量运行查询：

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

运行 help 命令：
```
%kql --help "help"
```

Tip

若要接收有关所有可用配置的信息，请使用 %config Kqlmagic。
若要排查和捕获 Kusto 错误（例如连接问题和不正确的查询），请使用 %config Kqlmagic.short_errors=False

示例笔记本

了解 Kusto 查询语言（KQL）

Last updated on 2026-03-10

通过

使用 Notebook 和 kqlmagic 分析Azure Data Explorer中的数据

Prerequisites

安装 kqlmagic

连接到群集

群集连接示例

连接选项

使用 Azure CLI 的连接示例

显示连接信息

查询和可视化

查询和渲染饼图

查询和呈现时间表

自定义图表颜色

使用 Python 将查询参数化

在 KQL 查询中使用 Python 变量

将查询结果转换到 Pandas DataFrame

Example

示例笔记本

相关内容

其他资源