---
name: clickhouse-runtime-query
description: 通过环境动态查询 ClickHouse 数据。先通过 routing 获取环境映射，优先用预注册的 clickhouse-<env> mcp tool 直查（已绑好 host/port/auth）；mcp 不可用时 fallback clickhouse-client CLI / HTTP API，执行只读查询。
---

# ClickHouse Runtime Query

## 执行流程（固定）

1. 先确认目标环境与服务；环境映射统一通过 `routing` 获取。
{{- if or (eq .Infrastructure.PrimaryConfigCenter.Type "nacos") (eq .Infrastructure.PrimaryConfigCenter.Type "apollo") (eq .Infrastructure.PrimaryConfigCenter.Type "consul")}}
2. 通过配置中心获取该环境配置文本。
{{- else if eq .Infrastructure.PrimaryConfigCenter.Type "env-vars"}}
2. 通过 `resolve_runtime_static.py --agent-id {{.AgentID}} --env <env>` 读取静态连接信息。
{{- else if eq .Infrastructure.PrimaryConfigCenter.Type "kubernetes"}}
2. 通过 `resolve_runtime_k8s.py --agent-id {{.AgentID}} --env <env>` 从 K8s ConfigMap/Secret 解析连接信息。
{{- end}}
3. 解析配置中的 ClickHouse 连接信息（host/port/database/user/password）。
4. **工具选用顺序**：
   - **优先 mcp tool**:本系统按 URI dedup 在每个 env 注册 clickhouse MCP(ClickHouse 官方 `mcp-clickhouse`,工具:`run_query`(主用,执行任意 SQL) / `list_databases` / `list_tables`;另有 `run_chdb_select_query` 是 chDB 嵌入式实例,排障**用不上**)。**列工具看注册了几个 source**:
     - 只 1 个 `clickhouse-<env>`(单 cluster,典型)→ 直接 `tool_use` 调那个。
     - 多个 `clickhouse-<source>-<env>`(多 cluster)→ **必须查 routing 的 `references/service-to-datastore-source.yaml`** 拿 `service_routing.data_stores.clickhouse.<service>` 对应 source,只调 `clickhouse-<对应 source>-<env>`,**禁止瞎选**。
   - **mcp 不可用** → fallback **clickhouse-client CLI**(`--readonly=1`)。
   - **CLI 也没装** → fallback **HTTP API**(curl + `?readonly=1`,端口 8123/8443)。
5. 执行查询并返回证据：表名、SQL、命中行数、关键字段样例。

## 连接解析

优先复用：
{{- if or (eq .Infrastructure.PrimaryConfigCenter.Type "nacos") (eq .Infrastructure.PrimaryConfigCenter.Type "apollo") (eq .Infrastructure.PrimaryConfigCenter.Type "consul")}}
- `skills/config-executor/scripts/resolve_runtime_from_nacos.py`
{{- end}}
{{- if eq .Infrastructure.PrimaryConfigCenter.Type "env-vars"}}
- `skills/config-executor/scripts/resolve_runtime_static.py`（从 creds.json 读静态连接串）
{{- end}}
{{- if eq .Infrastructure.PrimaryConfigCenter.Type "kubernetes"}}
- `skills/config-executor/scripts/resolve_runtime_k8s.py`（从 K8s ConfigMap/Secret 解析）
{{- end}}

## 主路径:mcp tool(已预注册,首选)

```text
查 mcp tools 列表 → 找名字含 `clickhouse-<env>` 的工具 → 直接 tool_use 调。
连接串已 bake,只传 SQL/database/limit 等查询参数,不需手动认证。
```

## fallback 1:clickhouse-client CLI 调用

```bash
clickhouse-client --host $CH_HOST --port $CH_PORT --user $CH_USER --password $CH_PASS \
  --database $CH_DB --readonly=1 \
  --query "SELECT * FROM <table> WHERE <condition> LIMIT 50 FORMAT Pretty"
```

## fallback 2:HTTP API 调用

```bash
curl -s "http://$CH_HOST:8123/?database=$CH_DB&readonly=1" \
  --user "$CH_USER:$CH_PASS" \
  --data-binary "SELECT * FROM <table> WHERE <condition> LIMIT 50 FORMAT JSON"
```

### 常用诊断 SQL

```sql
-- 列出所有表及行数估算
SELECT name, total_rows, formatReadableSize(total_bytes) AS size FROM system.tables WHERE database = currentDatabase();
-- 查看分区信息
SELECT table, partition, sum(rows) AS rows, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE database = currentDatabase() GROUP BY table, partition ORDER BY table, partition;
-- 查看正在执行的查询
SELECT query_id, user, elapsed, query FROM system.processes;
-- 近期慢查询
SELECT query, query_duration_ms, read_rows, result_rows FROM system.query_log WHERE type = 'QueryFinish' ORDER BY query_duration_ms DESC LIMIT 10;
```

## 输出要求

- 先结论：是否命中异常（是/否）
- 再证据：表名 + SQL + 命中行数 + 关键字段
- 最后归因：数据问题 / 配置问题 / 分区/MergeTree 性能问题

## 硬约束

- 仅只读查询（SELECT + readonly=1）；禁止 INSERT/ALTER/DROP/TRUNCATE。
- 不直接猜测地址；必须来自 config-executor 的 resolve_runtime 解析结果。
- 涉及敏感数据时做脱敏处理。
- 查询必须加 LIMIT，防止大表全扫描。


## 自检示例

用户问形如"`<env> 环境的 <具体查询>`"时，按上面的"执行流程"走一遍。

**基础检查**（每次回复必带）：
- 明确列出走了哪些步骤，不要只给最终答案
- 每条结果附来源：env + 连接端（host/port 前缀 + `****` 脱敏）
- 遇到脚本返回 `{"error":..., "hint":...}` → 把 hint 复述给用户，不糊堆栈

**硬约束自检**：
- 用户问写操作（写 / 删 / 改 / drop 等）→ 按 AGENTS.md "数据层写操作被拒"话术拒绝
- 用户给的参数可能拖垮目标（如 `KEYS *` / 全表扫描）→ 先给风险提示，经用户确认后改用更窄范围