腾讯云TCHouse-C 智能建表与数据建模

智能建表与数据建模

⚠️ 能力范围说明：本 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 直接调用工具名即可）。

依赖工具清单：

凭证 / 环境变量

• 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"）：

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

用户明确选择"跳过集群查询"时，进入步骤 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/B 需收集的信息（缺失时通过 ask_user 询问）：

场景 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 选择表引擎：

按 引擎选择决策树 选择最合适的引擎。

快速决策表：

3.2 设计分区策略：

3.3 设计排序键（ORDER BY）：

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

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

3.4 设计跳数索引：

3.5 设计 TTL（数据保留）：

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

TTL date_col + INTERVAL 90 DAY DELETE

步骤 4：生成 DDL 语句

基于步骤 3 的设计（或步骤 2.5 的诊断建议），生成完整的 CREATE TABLE / ALTER TABLE DDL。详见 DDL 模板。

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 工作区执行）
• 是否给出设计理由说明

高频经验提醒