kql

KQL 技能

在 Azure 数据平台上编写、调试、优化、转换和自动化 KQL 查询。

工作流路由

工作流	触发条件	文件
WriteQuery	“编写查询”“创建 KQL”“查询……”“查找符合条件的事件”“显示……”	workflows/WriteQuery.md
DebugOptimize	“优化”“查询很慢”“修复这段 KQL”“提升性能”“调试查询”	workflows/DebugOptimize.md
Translate	“SQL 转 KQL”“Splunk 转 KQL”“SPL 转 KQL”“转换这段查询”	workflows/Translate.md
Tooling	“验证 KQL”“通过 CLI 运行查询”“自动化查询”“安排警报”“REST API”	workflows/Tooling.md

如果没有匹配的特定工作流，则默认使用 WriteQuery。

参考文件

按需阅读，无需一开始就全部加载：

参考资料	阅读时机	文件
运算符和函数	编写或检查任何查询时	references/operators.md
服务表	需要了解特定服务提供哪些表时	references/service-tables.md
模式和反模式	优化查询或检查最佳实践时	references/patterns.md
SQL 到 KQL 对照表	将 SQL 转换为 KQL 时	references/sql-to-kql.md

示例查询

samples/ 目录包含按服务整理的、可用于生产环境的 .kql 文件。编写类似查询时可参考这些文件，它们展示了预期的文件格式和惯例。

输出格式

生成的每个查询都必须使用此 .kql 文件格式：

// ============================================================
// Title: <descriptive title>
// Service: <Log Analytics | Sentinel | ADX | App Insights>
// Tables: <comma-separated list of tables used>
// Description: <what this query does and when to use it>
// Parameters: <any variables the user should customize>
// Complexity: <Beginner | Intermediate | Advanced>
// ============================================================

// <the query, with inline comments for non-obvious logic>

文件命名

使用 kebab-case：failed-sign-ins-by-location.kql、high-cpu-vms-last-24h.kql

核心原则

1. 始终指定目标服务——不同 Azure 服务中的 KQL 各不相同。适用于 Sentinel 的查询不一定能在 ADX 中运行。
2. 默认限定时间范围——加入 TimeGenerated 筛选条件（或等效条件），以避免扫描整张表。除非用户另有指定，否则默认查询最近 24 小时的数据。
3. 性能优先——尽早筛选（在 join/summarize 前使用 where），字符串匹配优先使用 has 而非 contains，避免对宽表使用 * 投影。
4. 使用参数——使用 let 语句定义用户可能会自定义的值（时间范围、阈值、资源名称）。
5. 解释查询——对非简单逻辑添加行内注释，尤其是 mv-expand、parse、正则表达式和复杂的 summarize 表达式。

服务专属说明

• Log Analytics：不支持管理命令（.create、.alter）。表包括 Heartbeat、Perf、Event、Syslog、AzureActivity。
• Sentinel：在 Log Analytics 的基础上扩展了 SecurityEvent、SecurityAlert、SigninLogs、ThreatIntelligenceIndicator，以及自定义分析规则函数。
• ADX：完整的 KQL 引擎，支持管理命令、具体化视图、连续导出和外部表。功能最强，但查询可能无法移植。
• Application Insights：使用 Log Analytics 引擎。主要表包括：requests、dependencies、exceptions、traces、customEvents、performanceCounters。

示例

示例 1 — 编写查询：

“编写一个 KQL 查询，查找最近 7 天内来自美国境外的登录失败记录” 路由至：workflows/WriteQuery.md → 目标服务为 Sentinel/Log Analytics，使用 SigninLogs

示例 2 — 优化：

“这个查询运行起来特别慢，能帮我加快速度吗？”（粘贴 KQL） 路由至：workflows/DebugOptimize.md

示例 3 — 转换：

“将这段 SQL 查询转换为 KQL：SELECT * FROM events WHERE severity > 3 GROUP BY source” 路由至：workflows/Translate.md

示例 4 — 工具：

“如何通过 Azure CLI 运行此查询并导出为 CSV？” 路由至：workflows/Tooling.md

---

注意事项

• ago() 在查询解析时而非行时间进行求值 — where TimeGenerated > ago(1h) 和 | extend Age = now() - TimeGenerated 使用的 now() 快照相差几毫秒。如果比较结果很重要，请使用 let now_ = now(); 缓存该值。
• contains 不区分大小写且不使用索引；has 使用索引，但仅匹配词元边界： where Message has "error" 不会匹配 errors（词元不同）。如需匹配子字符串，请使用 contains_cs / contains，但要知道它们会全表扫描。
• 不带 by 的 summarize 会返回一行，掩盖所有分组错误 — 如果你忘了 by 子句并且只得到一行，原因就在这里。开发时始终至少投影一个维度。
• 跨群集 join 没问题；跨工作区 join 会静默截断数据 — 如果表名冲突，只会使用第一个工作区的数据集。请在两侧使用 workspace("foo").Table 别名。
• extend 会延迟求值 — 它之后的 where 会在计算 extend 之前进行筛选，这样速度更快，但意味着 where 引用的列必须已存在。请调整顺序：先 where，再 extend。
• Sentinel 中的 SigninLogs 和 AADSignInEventsBeta 是具有不同架构的不同表 — 为其中一张表编写的查询用于另一张表时，会因“找不到列”而报错，且错误信息晦涩。请将 print Tables = "<expected>" 与 getschema 的结果进行核对。
• Sentinel 分析规则每次运行最多返回 10,000 条结果，且不会提示 — 交互式运行时返回 50K 行的狩猎查询，实际只会对 10K 行触发警报。请显式使用 | take 10000，以便在测试期间暴露此限制。