Tchousec Smart Table Design

---
name: 腾讯云TCHouse-C 智能建表与数据建模
description: >
  TCHouse-C（ClickHouse）智能建表与数据建模 Skill。AI 根据用户描述的业务场景（日增数据量、查询模式、数据保留周期等），推荐合适的表引擎，设计分区策略与排序键，生成完整的 DDL 语句及设计理由说明。支持新建表设计、MySQL 迁移方案、现有表结构优化诊断。
  ⚠️ 当前版本仅生成 DDL 与设计方案，不直接执行建表；用户需自行将生成的 DDL 复制到 TCHouse-C 控制台的 SQL 工作区（DMS）或其他客户端执行。
  触发词：建表、DDL、CREATE TABLE、表设计、表结构、数据建模、分区策略、排序键、ORDER BY、PARTITION BY、表引擎、MergeTree、ReplacingMergeTree、AggregatingMergeTree、CollapsingMergeTree、SummingMergeTree、VersionedCollapsingMergeTree、数据模型、schema设计、索引设计、跳数索引、主键设计、分区键、TTL、数据保留、数据过期、宽表、维度表、事实表、日志表、订单表、用户表、MySQL迁移、迁移方案、表结构优化、ClickHouse建表、TCHouse-C建表、cdwch。
  本 Skill 包含 4 个子能力：①表引擎推荐 ②分区策略与排序键设计 ③完整 DDL 生成 ④现有表结构优化诊断。
  何时不触发：慢 SQL 诊断与自动调优（已有 SQL 的性能分析）、NL2SQL 数据分析查询、集群健康诊断与故障排查、集群选型与架构推荐、集群扩缩容操作、权限管理、数据导入导出等非建表/数据建模相关问题不走本 Skill。
allowed-tools:
  - TCHouseCDescribeInstance
  - TCHouseCDescribeInstanceNodes
  - TCHouseCDescribeTableSchema
  - TCHouseCDescribeClusterConfigs
  - ask_user # WorkBuddy 中为 AskUserQuestion
---

# 智能建表与数据建模

> ⚠️ **能力范围说明**：本 Skill 当前**仅负责表结构设计与 DDL 生成**，不直接连接集群执行建表。生成的 DDL 语句需由用户自行复制到 TCHouse-C 控制台 SQL 工作区（DMS）或其他 ClickHouse 客户端执行。

## 概述

本 Skill 提供 TCHouse-C（ClickHouse）集群的智能建表与数据建模能力，包含四个子能力：

1. **表引擎推荐**：根据业务场景（是否需要去重、更新、聚合）推荐最合适的 MergeTree 系列引擎
2. **分区策略与排序键设计**：根据日增数据量、查询模式、数据保留周期设计最优分区和排序方案
3. **完整 DDL 生成**：生成可直接复制到 DMS 或客户端执行的 CREATE TABLE 语句
4. **现有表结构优化诊断**：分析已有表的 DDL，发现设计问题并给出 ALTER TABLE 优化建议

## 依赖与运行环境

本 Skill 的所有调用通过 MCP Tool 完成（云 API 类工具由平台封装为 MCP Tool，Agent 直接调用工具名即可）。

**依赖工具清单**：

| #   | Tool 名称                      | 能力定位                                             |
| --- | ------------------------------ | ---------------------------------------------------- |
| 1   | TCHouseCDescribeInstance       | 集群基本信息获取（版本、节点规格、分布式集群判断）   |
| 2   | TCHouseCDescribeTableSchema    | 根据表名和节点 IP 获取建表 DDL（场景 C 现有表诊断）  |
| 3   | TCHouseCDescribeClusterConfigs | 集群配置参数（辅助引擎/参数选择）                    |
| 4   | ask_user                       | 向用户询问确认信息（WorkBuddy 中为 AskUserQuestion） |

## 凭证 / 环境变量

- `instance_id`：从会话 context 的 X-Context header 自动注入
- `region_id`：从会话 context 的 X-Context header 自动注入（可能是 `RegionId` 数字、`Region` 字符串或中文地域名）
- 若以上参数缺失，通过 `ask_user`（WorkBuddy 中为 `AskUserQuestion`）询问用户

> ⚠️ **地域参数强制规则**：本 Skill 依赖的全部工具（`TCHouseCXxx` 系）都只接受 **`Region` 字符串**（如 `ap-guangzhou`）。**任何工具调用前**都必须先按 [地域映射表](references/region-mapping.md) 将上下文中的地域信息（无论是中文名、英文串还是 `RegionId` 数字）统一转为 `Region` 字符串后再传入，禁止凭记忆填写。详见 [工具传参形式速查](references/region-mapping.md#工具传参形式速查)。

> 💡 **多平台兼容说明**：本文档中所有提到的 `ask_user` 工具，在 WorkBuddy 平台中对应为 `AskUserQuestion`。后文不再重复标注。

## 核心工作流

### 步骤 0：参数确认

**必需参数**：

- `instance_id`（集群 ID）
- `region_id`（地域）

**可选参数**（从用户问题中提取，缺失时主动询问，不自行假设）：

- 数据库名：用户指定或后续步骤中选择
- 业务场景描述：日增数据量、查询模式、保留周期等

**判断逻辑**：

- ✅ 参数齐全 → **强制**按 [地域映射表](references/region-mapping.md) 将地域信息统一转为 `Region` 字符串（任何输入形式都要过这一步：中文名、英文串、数字 ID 都不例外），转换后进入步骤 1
- ❌ `instance_id` 或 `region_id` 缺失 → 调用 `ask_user` 询问
- ❌ 地域信息在映射表中匹配不到（或大区模糊，如"华南地区"）→ 调用 `ask_user` 确认后再转换

### 步骤 1：确认集群信息

调用 `TCHouseCDescribeInstance` 获取集群基本信息。

**判断逻辑**（按失败类型区分处理，**不要笼统地"继续生成 DDL"**）：

| 结果                                                                                                       | 处理策略                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ 集群状态为 `Serving`                                                                                    | 进入步骤 2                                                                                                                                                                                                                                    |
| ⚠️ 集群状态非 `Serving`（如 `Modifying`、`Isolated`、`Deleted` 等临时或不可用状态）                        | 告知用户集群当前状态，**通过 `ask_user` 明确询问**："是否继续基于业务信息生成 DDL 设计方案？（生成的 DDL 需待集群恢复 `Serving` 后自行到 SQL 工作区执行）"；用户确认后进入步骤 2，走"跳过集群信息的降级路径"（见下方）                        |
| ❌ 调用失败：`appId and instanceId not match` / `instanceId not belong to this account` 等 ID 与账号不匹配 | **优先让用户确认 ID**，不要直接跳过。调用 `ask_user` 提供 3 个选项让用户选：①"重新确认/修正 instance_id"（默认推荐） ②"切换账号后重试" ③"跳过集群查询，直接基于我提供的业务信息生成通用 DDL 方案"。仅当用户明确选 ③ 才进入步骤 2 并走降级路径 |
| ❌ 调用失败：`ResourceNotFound` / instance_id 格式错误                                                     | 先自动检查 instance_id 格式（应为 `cdwch-` 前缀）。格式错 → 直接修正后重试一次；格式对 → 调用 `ask_user` 让用户重新确认 ID（同样给出与上一行相同的 3 个选项）                                                                                 |
| ❌ 调用失败：`AuthFailure` / 权限不足                                                                      | 调用 `ask_user` 提供 3 个选项：①"我去补充/申请该集群的读权限后重试"（默认推荐） ②"切换有权限的账号重试" ③"跳过集群查询，直接生成通用 DDL 方案"。仅当用户明确选 ③ 才进入步骤 2 并走降级路径                                                    |

**降级路径（跳过集群信息后的约束）**：

用户明确选择"跳过集群查询"时，进入步骤 2 继续设计，但必须在最终 DDL 中做如下降级：

- 无法确认 ClickHouse 版本 → 默认按主流稳定版本（21.x/22.x/23.x 兼容语法）生成 DDL，并在设计说明中注明"未获取到集群版本，如为更老版本需人工核对语法兼容性"
- 无法确认是否为分布式集群 → **同时给出**「单机版 DDL」和「分布式版 DDL（本地表 `ReplicatedXxxMergeTree ON CLUSTER` + `Distributed` 表）」两套，让用户按实际集群形态择一执行
- 分布式 DDL 中的 `ON CLUSTER {cluster_name}`、`Distributed(cluster, db, local_table, sharding_key)` 等参数用 `-- TODO: 替换为实际集群名` 占位符标注
- 在最终交付时明确提示：本次 DDL 未经过集群信息核对，**执行前务必到控制台 SQL 工作区先在测试库验证**

**正常路径记录信息**：ClickHouse 版本号（影响可用引擎和功能）、节点规格和数量、是否为分布式集群。

### 步骤 2：场景分类与需求收集

根据用户描述判断属于哪种场景：

| 场景          | 判定条件                         | 后续路径                     |
| ------------- | -------------------------------- | ---------------------------- |
| A. 新建表设计 | 用户描述业务需求，要求设计表结构 | → 步骤 3                     |
| B. MySQL 迁移 | 用户提到从 MySQL/其他数据库迁移  | → 步骤 3（额外收集源表 DDL） |
| C. 现有表优化 | 用户提到"查询慢"/"表结构有问题"  | → 步骤 2.5                   |

**场景 A/B 需收集的信息**（缺失时通过 `ask_user` 询问）：

| 信息项                         | 重要性 | 默认值（用户未提供时）            |
| ------------------------------ | ------ | --------------------------------- |
| 日增数据量                     | 必需   | 无默认，必须询问                  |
| 主要查询模式（按什么维度过滤） | 必需   | 无默认，必须询问                  |
| 是否需要去重/更新              | 重要   | 默认不需要（追加写入）            |
| 聚合粒度（是否需要预聚合）     | 重要   | 默认不需要                        |
| 数据保留周期                   | 重要   | 默认永久保留                      |
| 字段列表及类型                 | 必需   | 无默认，必须询问或从源表 DDL 提取 |

**场景 B 额外收集**：源表 DDL（MySQL CREATE TABLE 语句）。

**判断逻辑**：

- ✅ 关键信息齐全 → 进入步骤 3
- ❌ 缺少必需信息 → 调用 `ask_user` 一次性询问所有缺失项（避免多轮追问）

### 步骤 2.5：现有表结构诊断（场景 C）

**2.5.1 获取现有表结构**：

调用 `TCHouseCDescribeTableSchema` 获取目标表的建表 DDL。

**判断逻辑**：

- ✅ 成功 → 进入 2.5.2
- ❌ 表不存在 → 调用 `ask_user` 确认表名和数据库名
- ❌ 权限不足 → 告知用户无权限查看该表结构，可请用户直接粘贴现有 DDL 后继续分析

**备选方案**：如果 `TCHouseCDescribeTableSchema` 因权限或网络不可用，可通过 `ask_user` 让用户在 TCHouse-C 控制台 SQL 工作区执行 `SHOW CREATE TABLE {db}.{table}` 并把结果粘贴过来，同样可完成诊断。

**2.5.2 分析表结构问题**：

按 [引擎选择指南](references/engine-selection-guide.md#诊断检查清单) 逐项检查：

- 引擎选择是否合理
- 分区粒度是否合适
- 排序键设计是否匹配查询模式
- 是否缺少跳数索引
- 是否缺少 TTL 配置

**2.5.3 生成优化建议**：

输出诊断报告 + ALTER TABLE 优化语句，进入步骤 5。

### 步骤 3：设计表结构

基于收集到的业务信息，按以下顺序设计：

**3.1 选择表引擎**：

按 [引擎选择决策树](references/engine-selection-guide.md#引擎选择决策树) 选择最合适的引擎。

**快速决策表**：

| 业务特征                    | 推荐引擎                                           |
| --------------------------- | -------------------------------------------------- |
| 纯追加写入，无更新无去重    | MergeTree / ReplicatedMergeTree                    |
| 需要按主键去重（保留最新）  | ReplacingMergeTree                                 |
| 需要按主键更新字段          | CollapsingMergeTree / VersionedCollapsingMergeTree |
| 需要预聚合（sum/count/avg） | SummingMergeTree / AggregatingMergeTree            |
| 分布式集群                  | 对应引擎的 Replicated 版本 + Distributed 表        |

**3.2 设计分区策略**：

| 日增数据量      | 推荐分区粒度    | 分区表达式                             |
| --------------- | --------------- | -------------------------------------- |
| < 100 万行      | 按月            | `toYYYYMM(date_col)`                   |
| 100 万 ~ 1 亿行 | 按天            | `toYYYYMMDD(date_col)`                 |
| > 1 亿行        | 按天 + 业务维度 | `(toYYYYMMDD(date_col), business_key)` |

**3.3 设计排序键（ORDER BY）**：

排序键设计原则（按优先级）：

1. 将高频 WHERE 过滤字段放入排序键
2. 字段顺序：基数低 → 基数高（如 date → city → user_id）
3. 排序键字段数量控制在 3-5 个
4. 分区键字段应作为排序键的第一个字段

**3.4 设计跳数索引**：

| 字段特征                 | 推荐索引类型                |
| ------------------------ | --------------------------- |
| 低基数字段（状态、类型） | `set(N)`                    |
| 高基数字段（ID、手机号） | `bloom_filter(0.01)`        |
| 数值/日期范围查询        | `minmax`                    |
| 字符串模糊查询           | `tokenbf_v1` / `ngrambf_v1` |

**3.5 设计 TTL（数据保留）**：

用户指定保留周期时，添加 TTL 表达式：

```sql
TTL date_col + INTERVAL 90 DAY DELETE
```

### 步骤 4：生成 DDL 语句

基于步骤 3 的设计（或步骤 2.5 的诊断建议），生成完整的 CREATE TABLE / ALTER TABLE DDL。详见 [DDL 模板](references/ddl-templates.md)。

**DDL 必须包含**：

1. 完整的列定义（含数据类型、注释）
2. 表引擎声明
3. PARTITION BY 表达式
4. ORDER BY 排序键
5. 跳数索引（如有）
6. TTL 配置（如有）
7. SETTINGS（如 `index_granularity`）

**DDL 输出规范**：

向用户交付 DDL 时必须包含以下内容：

1. **完整 DDL 语句**：使用 Markdown 代码块（`sql ... `）包裹，方便用户复制
2. **多语句拆分**：如需先建库再建表，分别用独立代码块给出，并说明执行顺序
3. **占位符标注**：如有需用户按实际情况调整的部分（如集群名 `default_cluster`、副本节点数），使用 `-- TODO: ...` 注释明确标出
4. **执行方式提示**：在 DDL 下方附一句执行指引：
   > 请将上述 DDL 按顺序复制到 TCHouse-C 控制台「SQL 工作区（DMS）」执行。执行前建议先备份或在测试库验证，确认无误后再在生产库执行。
5. **设计说明**：简述引擎选择、分区策略、排序键、TTL 等关键设计点的依据

### 步骤 5：输出结果

向用户输出：

1. **DDL 完整文本**（原始 SQL，Markdown 代码块，便于用户复制执行）
2. **设计理由说明**（引擎选择、分区策略、排序键、TTL 等的依据）
3. **执行注意事项**（用户在 SQL 工作区执行时可能遇到的问题及规避方法，如"表已存在"→ 可加 `IF NOT EXISTS`、"权限不足"→ 联系管理员等）
4. **场景 C 诊断报告**（如适用）：以结构化列表列出发现的问题、影响、优化优先级

## 输出前检查清单

- [ ] 是否已根据集群版本（步骤 1）选择兼容的引擎与语法
- [ ] 分区策略是否与日增数据量匹配（参考 3.2 表格）
- [ ] 排序键设计是否覆盖高频 WHERE 过滤字段
- [ ] 是否根据字段特征添加合理的跳数索引
- [ ] 如用户指定了保留周期，是否添加 TTL 表达式
- [ ] DDL 是否用 Markdown 代码块包裹便于用户复制
- [ ] 多条 DDL 是否明确说明执行顺序
- [ ] 是否附上执行方式提示（引导用户到控制台 SQL 工作区执行）
- [ ] 是否给出设计理由说明

## 高频经验提醒

| 经验                          | 触发时机         | 说明                                                                                                              |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| 本 Skill 不直接执行 DDL       | 每次交付 DDL 时  | 必须提醒用户到 TCHouse-C 控制台 SQL 工作区（DMS）自行执行；生产库执行前建议先测试库验证                           |
| 分区粒度按日增数据量选择      | 步骤 3.2         | < 100 万行按月、100 万 ~ 1 亿行按天、> 1 亿行按天 + 业务维度                                                      |
| 排序键覆盖高频过滤字段        | 步骤 3.3         | 按"基数低 → 基数高"顺序排列，字段数量控制在 3-5 个，分区键字段应作为排序键第一个字段                              |
| 分布式集群需本地表 + 分布式表 | 步骤 3.1         | 分布式集群下需生成 `ReplicatedXxxMergeTree` 本地表（`ON CLUSTER`）+ `Distributed` 表                              |
| MySQL 迁移需类型映射          | 场景 B           | BIGINT → UInt64/Int64、VARCHAR → String、TINYINT → UInt8/Int8、DATETIME → DateTime；低基数字段可用 LowCardinality |
| 场景 C 现有表可让用户粘贴 DDL | 2.5.1 权限不足时 | 无权限调用 `TCHouseCDescribeTableSchema` 时，让用户在控制台执行 `SHOW CREATE TABLE` 后粘贴，同样可诊断            |