Imported from ahang1598/doubao-workbuddy-qwenwork-skills (
workbuddy/connectors/marketplace/connectors/tencent-tchouse-c/skills/tchousec-smart-table-design/SKILL.md). Install upstream withnpx skills add ahang1598/doubao-workbuddy-qwenwork-skills --skill tchousec-smart-table-design. Copyright stays with the author.
智能建表与数据建模
⚠️ 能力范围说明：本 Skill 当前仅负责表结构设计与 DDL 生成，不直接连接集群执行建表。生成的 DDL 语句需由用户自行复制到 TCHouse-C 控制台 SQL 工作区（DMS）或其他 ClickHouse 客户端执行。
概述
本 Skill 提供 TCHouse-C（ClickHouse）集群的智能建表与数据建模能力，包含四个子能力：
- 表引擎推荐：根据业务场景（是否需要去重、更新、聚合）推荐最合适的 MergeTree 系列引擎
- 分区策略与排序键设计：根据日增数据量、查询模式、数据保留周期设计最优分区和排序方案
- 完整 DDL 生成：生成可直接复制到 DMS 或客户端执行的 CREATE TABLE 语句
- 现有表结构优化诊断：分析已有表的 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）。任何工具调用前都必须先按 地域映射表 将上下文中的地域信息（无论是中文名、英文串还是RegionId数字）统一转为Region字符串后再传入，禁止凭记忆填写。详见 工具传参形式速查。
💡 多平台兼容说明：本文档中所有提到的
ask_user工具，在 WorkBuddy 平台中对应为AskUserQuestion。后文不再重复标注。
核心工作流
步骤 0：参数确认
必需参数：
instance_id（集群 ID）region_id（地域）
可选参数（从用户问题中提取，缺失时主动询问，不自行假设）：
- 数据库名：用户指定或后续步骤中选择
- 业务场景描述：日增数据量、查询模式、保留周期等
判断逻辑：
- ✅ 参数齐全 → 强制按 地域映射表 将地域信息统一转为
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 分析表结构问题：
按 引擎选择指南 逐项检查：
- 引擎选择是否合理
- 分区粒度是否合适
- 排序键设计是否匹配查询模式
- 是否缺少跳数索引
- 是否缺少 TTL 配置
2.5.3 生成优化建议：
输出诊断报告 + ALTER TABLE 优化语句，进入步骤 5。
步骤 3：设计表结构
基于收集到的业务信息，按以下顺序设计：
3.1 选择表引擎：
按 引擎选择决策树 选择最合适的引擎。
快速决策表：
| 业务特征 | 推荐引擎 |
|---|---|
| 纯追加写入，无更新无去重 | 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）：
排序键设计原则（按优先级）：
- 将高频 WHERE 过滤字段放入排序键
- 字段顺序：基数低 → 基数高（如 date → city → user_id）
- 排序键字段数量控制在 3-5 个
- 分区键字段应作为排序键的第一个字段
3.4 设计跳数索引：
| 字段特征 | 推荐索引类型 |
|---|---|
| 低基数字段（状态、类型） | set(N) |
| 高基数字段（ID、手机号） | bloom_filter(0.01) |
| 数值/日期范围查询 | minmax |
| 字符串模糊查询 | tokenbf_v1 / ngrambf_v1 |
3.5 设计 TTL（数据保留）：
用户指定保留周期时，添加 TTL 表达式：
TTL date_col + INTERVAL 90 DAY DELETE步骤 4：生成 DDL 语句
基于步骤 3 的设计（或步骤 2.5 的诊断建议），生成完整的 CREATE TABLE / ALTER TABLE DDL。详见 DDL 模板。
DDL 必须包含：
- 完整的列定义（含数据类型、注释）
- 表引擎声明
- PARTITION BY 表达式
- ORDER BY 排序键
- 跳数索引（如有）
- TTL 配置（如有）
- SETTINGS（如
index_granularity）
DDL 输出规范：
向用户交付 DDL 时必须包含以下内容：
- 完整 DDL 语句：使用 Markdown 代码块（
sql ...）包裹，方便用户复制 - 多语句拆分：如需先建库再建表，分别用独立代码块给出，并说明执行顺序
- 占位符标注：如有需用户按实际情况调整的部分（如集群名
default_cluster、副本节点数），使用-- TODO: ...注释明确标出 - 执行方式提示：在 DDL 下方附一句执行指引：
请将上述 DDL 按顺序复制到 TCHouse-C 控制台「SQL 工作区（DMS）」执行。执行前建议先备份或在测试库验证，确认无误后再在生产库执行。
- 设计说明：简述引擎选择、分区策略、排序键、TTL 等关键设计点的依据
步骤 5：输出结果
向用户输出：
- DDL 完整文本（原始 SQL，Markdown 代码块，便于用户复制执行）
- 设计理由说明（引擎选择、分区策略、排序键、TTL 等的依据）
- 执行注意事项（用户在 SQL 工作区执行时可能遇到的问题及规避方法，如"表已存在"→ 可加
IF NOT EXISTS、"权限不足"→ 联系管理员等） - 场景 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 后粘贴，同样可诊断 |