eventhouse-consumption-cli

更新检查 — 每个会话仅执行一次（必需） 首次在会话中使用此技能时，请先运行 check-updates 技能，再继续。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能。
• Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程 package.json 的版本。
• 如果本会话中已执行过检查，则跳过。

重要提示

1. 要根据工作区名称查找工作区详情（包括其 ID）：先列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项目类型和项目名称查找项目详情（包括其 ID）：先列出该工作区中该类型的所有项目，然后使用 JMESPath 进行筛选

eventhouse-consumption-cli — 通过 CLI 执行只读 KQL 查询

目录

任务	参考	备注
在 Fabric 中查找工作区和项目	COMMON-CLI.md § 在 Fabric 中查找工作区和项目	必须 — 先阅读链接内容 [用于按名称查找工作区 ID，或按名称、项目类型和工作区 ID 查找项目 ID]
Fabric 拓扑和关键概念	COMMON-CORE.md § Fabric 拓扑和关键概念
环境 URL	COMMON-CORE.md § 环境 URL	KQL 群集 URI 因项目而异
身份验证和令牌获取	COMMON-CORE.md § 身份验证和令牌获取	受众错误会导致 401；遇到任何身份验证问题前请先阅读
核心控制平面 REST API	COMMON-CORE.md § 核心控制平面 REST API
分页	COMMON-CORE.md § 分页
长时间运行的操作（LRO）	COMMON-CORE.md § 长时间运行的操作（LRO）
速率限制和流量限制	COMMON-CORE.md § 速率限制和流量限制
OneLake 数据访问	COMMON-CORE.md § OneLake 数据访问	需要 storage.azure.com 令牌，而非 Fabric 令牌
作业执行	COMMON-CORE.md § 作业执行
容量管理	COMMON-CORE.md § 容量管理
常见问题和故障排除	COMMON-CORE.md § 常见问题和故障排除
最佳实践	COMMON-CORE.md § 最佳实践
工具选择依据	COMMON-CLI.md § 工具选择依据
身份验证方案	COMMON-CLI.md § 身份验证方案	az login 流程和令牌获取
通过 az rest 调用 Fabric 控制平面 API	COMMON-CLI.md § 通过 az rest 调用 Fabric 控制平面 API	始终传入 --resource https://api.fabric.microsoft.com，否则 az rest 会失败
分页模式	COMMON-CLI.md § 分页模式
长时间运行的操作（LRO）模式	COMMON-CLI.md § 长时间运行的操作（LRO）模式
通过 curl 访问 OneLake 数据	COMMON-CLI.md § 通过 curl 访问 OneLake 数据	使用 curl，而非 az rest（令牌受众不同）
作业执行（CLI）	COMMON-CLI.md § 作业执行
OneLake 快捷方式	COMMON-CLI.md § OneLake 快捷方式
容量管理（CLI）	COMMON-CLI.md § 容量管理
组合方案	COMMON-CLI.md § 组合方案
常见问题和故障排除（CLI 专属）	COMMON-CLI.md § 常见问题和故障排除（CLI 专属）	az rest 受众、Shell 转义、令牌过期
快速参考：az rest 模板	COMMON-CLI.md § 快速参考：az rest 模板
快速参考：令牌受众 / CLI 工具对照表	COMMON-CLI.md § 快速参考：令牌受众 ↔ CLI 工具对照表	各服务对应的 --resource 和工具
连接基础知识	EVENTHOUSE-CONSUMPTION-CORE.md § 连接基础知识	群集 URI 发现、az rest、REST API
架构发现和安全性	EVENTHOUSE-CONSUMPTION-CORE.md § 架构发现和安全性	架构发现、安全性 — 工作区角色和 KQL 数据库角色
监视和诊断	EVENTHOUSE-CONSUMPTION-CORE.md § 监视和诊断
性能最佳实践	EVENTHOUSE-CONSUMPTION-CORE.md § 性能最佳实践	编写 KQL 前请先阅读 — 时间筛选器、has 与 contains 的区别
常见使用模式	EVENTHOUSE-CONSUMPTION-CORE.md § 常见使用模式	时间序列、Top-N、百分位数、动态字段
常见问题、故障排除和快速参考	EVENTHOUSE-CONSUMPTION-CORE.md § 常见问题、故障排除和快速参考	常见问题和故障排除（12 个问题），快速参考：按场景划分的使用功能
表和列发现	discovery-queries.md § 表和列发现	表发现、列统计
函数和视图发现	discovery-queries.md § 函数和视图发现	函数发现、物化视图发现
策略发现	discovery-queries.md § 策略发现
外部表和引入映射	discovery-queries.md § 外部表和引入映射	外部表发现、引入映射发现
安全发现	discovery-queries.md § 安全发现
数据库概览脚本	discovery-queries.md § 数据库概览脚本
工具栈	SKILL.md § 工具栈
连接	SKILL.md § 连接	Eventhouse 专属的 az rest 连接步骤
Agent 探索（“与我的数据聊天”）	SKILL.md § Agent 探索	数据探索请从此处开始
运行查询	SKILL.md § 运行查询	az rest、输出格式化、导出
监视	SKILL.md § 监视
必须 / 建议 / 避免 / 故障排除	SKILL.md § 必须 / 建议 / 避免 / 故障排除	必须执行 / 避免 / 建议检查清单
示例	SKILL.md § 示例
Agent 集成说明	SKILL.md § Agent 集成说明

---

工具栈

工具	用途	安装
az cli	通过 Kusto REST API 执行 KQL 查询和管理命令；发现 Fabric 控制平面	winget install Microsoft.AzureCLI
jq	JSON 处理和输出格式化	winget install jqlang.jq

连接

第 1 步 — 发现 KQL 数据库查询 URI

# Get workspace ID (if not known)
WS_ID=$(az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --resource "https://api.fabric.microsoft.com" \
  | jq -r '.value[] | select(.displayName=="MyWorkspace") | .id')

# List KQL Databases and get connection properties
az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/kqlDatabases" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {name: .displayName, id: .id, queryUri: .properties.queryServiceUri, dbName: .properties.databaseName}'

第 2 步 — 设置连接变量

CLUSTER_URI="https://<cluster>.kusto.fabric.microsoft.com"
DB_NAME="MyKqlDatabase"

第 3 步 — 验证连接

重要 — 请求正文文件模式：KQL 查询包含 |（管道）字符，会破坏 bash 和 PowerShell 中的 shell 转义。务必将 JSON 请求正文写入临时文件，并通过 --body @<file> 引用。这是所有 az rest KQL 调用的推荐方式。 在 PowerShell 中，使用 @{db="X";csl="..."} | ConvertTo-Json -Compress | Out-File $env:TEMP\kql_body.json -Encoding utf8NoBOM，然后使用 --body "@$env:TEMP\kql_body.json"。

# Write body to temp file (avoids pipe escaping issues)
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyKqlDatabase","csl":"print Message = 'Connected successfully', Cluster = current_cluster_endpoint(), Timestamp = now()"}
EOF

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

---

Agent 式探索

“与我的数据聊天” — 发现序列

当用户要求探索或查询 Eventhouse，但未指定表时：

Step 1 → .show tables                                    // discover tables
Step 2 → .show table <TABLE> schema as json              // understand columns + types
Step 3 → <TABLE> | take 10                               // see sample data
Step 4 → <TABLE> | summarize count() by bin(Timestamp, 1h) | render timechart  // shape of data
Step 5 → Formulate targeted query based on user's question

感知架构的查询生成

发现架构后，使用实际的列名和类型生成查询：

// Example: user asks "show me errors in the last hour"
// After discovering table "AppEvents" with columns: Timestamp, Level, Message, Source
AppEvents
| where Timestamp > ago(1h)
| where Level == "Error"
| summarize ErrorCount = count() by Source, bin(Timestamp, 5m)
| order by ErrorCount desc

---

运行查询

通过 az rest

--body 务必使用临时文件模式 — KQL 管道（|）会破坏内联 shell 转义。

# Run a KQL query
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1h) | count"}
EOF

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

输出格式化

# Pretty-print results as a table with jq
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".show tables"}
EOF

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0] | [.Columns[].ColumnName] as $cols | .Rows[] | [$cols, .] | transpose | map({(.[0]): .[1]}) | add'

# Save results to file
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1h) | summarize count() by EventType"}
EOF

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  --output-file results.json

---

监控

// Active queries
.show queries

// Recent commands (last hour)
.show commands
| where StartedOn > ago(1h)
| project StartedOn, CommandType, Text = substring(Text, 0, 80), Duration, State
| order by StartedOn desc

// Ingestion failures (for context when data seems stale)
.show ingestion failures
| where FailedOn > ago(24h)
| summarize count() by ErrorCode
| top 5 by count_

---

必须 / 优先 / 避免 / 故障排除

必须

• 务必包含时间筛选条件 — 时间序列表中必须包含 where Timestamp > ago(...)。
• 查询前先发现架构 — 先运行 .show tables 和 .show table T schema as json。
• 使用 has 搜索词项 — 已建立索引且速度快；仅在需要子字符串匹配时使用 contains。
• 验证群集 URI — KQL 数据库 URI 按项目区分；务必通过 Fabric REST API 解析。

优先

• CLI 查询会话使用 az rest；与 Agent 集成的工作流使用 Fabric KQL MCP 服务。
• 尽早使用 project，在聚合前删除不需要的列。
• 当一个子表达式被多次使用时，使用 materialize()。
• 初步探索使用 take 100；避免扫描整张表。
• 时间序列使用 render timechart；分布使用 render piechart。

避免

• 在大型表上使用 contains — 会进行全表扫描，且未建立索引。请使用 has 或 has_cs。
• 未先筛选两侧数据就使用 join — 会导致内存激增。
• 在宽表上使用相当于 SELECT * 的写法（project 所有列）。
• 在时间序列 summarize 中遗漏 bin() — 会为每个唯一时间戳生成一行。
• 硬编码群集 URI — 务必从 Fabric REST API 或环境变量中解析。

故障排除

症状	修复方法
az rest 身份验证失败	先运行 az login；确保已设置 --resource "https://kusto.kusto.windows.net"
有效表返回空结果	检查数据库上下文；可能需要使用 database("name").table
查询超时	使用更严格的时间筛选条件；检查 .show queries，查看是否有冲突的查询
Forbidden (403)	为 KQL 数据库申请 viewer 角色
结果被截断	默认上限为 500K 行；在查询前添加 set truncationmaxrecords = N;
KQL 管道 | 导致 PowerShell 或 bash 出错	切勿在 --body 中内联 KQL。将 JSON 写入临时文件，并使用 --body @file.json（参见运行查询）

---

示例

示例 1：发现并查询

# 1. Set connection variables (after discovering URI via Step 1)
CLUSTER_URI="https://<your-cluster>.kusto.fabric.microsoft.com"
DB_NAME="SalesDB"

# 2. Discover tables
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":".show tables"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

# 3. Explore schema
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":".show table Orders schema as json"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

# 4. Sample data
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":"Orders | take 10"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

// 5. Analytical query (via az rest --body @file)
Orders
| where OrderDate > ago(30d)
| summarize
    TotalOrders = count(),
    TotalRevenue = sum(Amount)
    by bin(OrderDate, 1d)
| render timechart

示例 2：跨数据库查询

// Query across KQL databases in the same Eventhouse
let orders = database("SalesDB").Orders | where OrderDate > ago(7d);
let products = database("CatalogDB").Products;
orders
| join kind=inner (products) on ProductId
| summarize Revenue = sum(Amount) by ProductName
| top 10 by Revenue desc

示例 3：将结果导出到文件

# Run query and save results to JSON
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1d) | summarize count() by EventType"}
EOF

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  --output-file results.json

# Convert to CSV with jq
cat results.json \
  | jq -r '.Tables[0] | (.Columns | map(.ColumnName)), (.Rows[]) | @csv' > results.csv

---

Agent 集成说明

• 此技能为只读——不会创建、修改或删除数据库对象。
• 对于创作操作（表管理、数据引入、策略），请委托给 eventhouse-authoring-cli。
• 对于跨工作负载编排（Spark + SQL + KQL），请委托给 FabricDataEngineer Agent。
• Fabric KQL MCP server（mcp-setup/mcp-config-template.json 中的 fabric-kql）可用作 az rest 的替代方案，以执行集成到 Agent 中的查询。