---
name: warehouse-table-sql
description: 根据提示词从目标数据库查找表并生成数据仓库建表SQL代码
license: MIT
compatibility: opencode
metadata:
  audience: data engineers
  workflow: data warehouse development
---

## 功能概述

本技能帮助用户根据自然语言提示词，从业务数据库中查找对应的数据表，并生成数据仓库的建表SQL代码。技能会分析业务数据推断字段含义，为每个字段和表生成详细的中文注释。

## 使用前准备

在使用本技能前，请确保以下信息已明确：

1. **业务数据库类型**：如 Oracle、MySQL、PostgreSQL 等
2. **数据仓库类型**：如 Doris、ClickHouse、Snowflake 等
3. **目标项目路径**：生成的技能文件保存的项目目录（例如 `svc-code`）

## 工作流程

### 1. 理解用户意图
- 分析用户的提示词，提取关键实体、表名、字段描述等信息
- 明确用户想要从哪个业务数据库导出哪些表到数据仓库
- 使用数据库工具分页查询表名称和描述，分析大概是不是，然后再次查询列来确定，最后查询数据来确定

### 2. 收集必要信息
- 使用提问工具向用户确认：
  - 业务数据库的具体类型（Oracle/MySQL/PostgreSQL等）
  - 目标数据仓库的类型（Doris/ClickHouse等）
  - 技能文件保存的项目路径
- 如果用户未提供上述信息，必须询问清楚后才能继续

### 3. 查找数据表
- 使用字段匹配工具（`my-remote-mcp_field_matcher`）根据中文表名或字段描述查找对应的数据库表
- 如果工具返回匹配结果，获取表的英文名、字段结构、数据类型等信息
- 如果未找到匹配的表，向用户说明情况，并询问是否需要调整搜索条件或手动提供表结构

### 4. 生成建表SQL
- 根据找到的表结构，结合目标数据仓库的语法特点，生成对应的建表SQL语句
- 考虑数据类型映射、主键、索引、分区等数据仓库特有配置
- 提供完整的SQL代码，包括表名、字段定义等
- **字段筛选规则**：
  1. **基础排除规则**：排除TEXT类型、JSON格式字段以及长度大于200的字符字段（VARCHAR(>200)）
  2. **BI分析价值评估**：数据仓库主要用于分析，需要评估每个字段在BI报表分析中的使用价值：
     - **高价值字段（必须包含）**：
       - 主键、外键等标识字段（用于关联和去重）
       - 时间戳字段（用于时间序列分析、趋势分析）
       - 数值型字段（金额、数量、评分等，用于聚合计算）
       - 状态、类型等分类字段（用于分组、筛选）
       - 业务关键描述字段（如名称、标题等，用于展示和标识）
     - **低价值字段（可排除）**：
       - 详细描述、备注、长文本说明（分析中很少使用）
       - 技术性字段（如内部ID、系统标识等，业务分析无关）
       - 临时性、过程性字段（如操作标记、中间状态等）
       - 冗余字段（已包含在其他字段中的信息）
     - **判断标准**：如果字段在BI报表分析中使用频率低于5%，则不需要创建
       - 基于字段名称、数据类型、示例数据推断分析价值
       - 考虑业务场景：分析报告通常关注聚合、趋势、分类，而非详细文本
       - 当不确定时，优先包含可能用于筛选、分组、计算的字段
- **Doris Unique Key模型**：当目标数据仓库是Doris时，如果表需要主键去重功能，应使用Unique Key模型。将需要作为逻辑主键的字段指定为UNIQUE KEY，重复数据会自动覆盖。示例：
  ```sql
  CREATE TABLE IF NOT EXISTS your_table_name (
      id BIGINT NOT NULL COMMENT '主键ID',
      name VARCHAR(50) COMMENT '名称',
      value INT COMMENT '数值',
      update_time DATETIME COMMENT '更新时间'
  )
  UNIQUE KEY(id)
  DISTRIBUTED BY HASH(id) BUCKETS 10
  PROPERTIES (
      "replication_num" = "1",
      "enable_unique_key_merge_on_write" = "true"
  );
  ```
  核心原理：UNIQUE KEY字段会被视为逻辑主键，相同数据自动覆盖。覆盖逻辑是新数据完全覆盖具有相同UNIQUE KEY的整行旧数据。

### 5. 生成中文注释
- 使用工具分析业务数据库字段数据，推断每个字段保存的业务含义
- 为每个字段编写清晰的中文注释，说明字段的业务用途和数据含义
- 为表名添加中文描述，说明表的业务用途和数据范围
- 将中文注释集成到建表SQL代码中，确保每个字段和表都有对应的中文说明

### 6. 保存结果
- 将生成的SQL代码保存到用户指定的项目目录中
- 建议保存路径：`{项目路径}/sql/warehouse_tables/`
- 提供文件路径供用户查看和使用

## 输出示例

```sql
-- 数据仓库建表语句 (Doris)
-- 表中文描述：用户基本信息表，存储系统注册用户的身份信息和联系方式
-- 源表：用户信息表 (user_info)
CREATE TABLE IF NOT EXISTS dw_user_info (
    user_id BIGINT COMMENT '用户唯一标识符，系统自动生成的主键ID',
    user_name VARCHAR(100) COMMENT '用户真实姓名，用于身份识别和显示',
    email VARCHAR(200) COMMENT '用户电子邮箱地址，用于登录和接收通知',
    phone VARCHAR(20) COMMENT '用户手机号码，用于登录验证和联系',
    status TINYINT COMMENT '用户状态：0-禁用，1-正常，2-锁定',
    created_at DATETIME COMMENT '用户注册时间，记录账户创建时间戳',
    updated_at DATETIME COMMENT '最后更新时间，记录用户信息修改时间'
) ENGINE=OLAP
-- 使用UNIQUE KEY模型实现主键去重，相同user_id的数据会自动覆盖
UNIQUE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10
PROPERTIES (
    "replication_num" = "1",
    -- 启用写时合并模式以获得最佳查询性能
    "enable_unique_key_merge_on_write" = "true"
);

-- 表注释：此表用于存储用户核心信息，支持用户管理和身份验证功能
COMMENT ON TABLE dw_user_info IS '用户基本信息表，包含用户身份、联系方式和状态信息';
```

## 注意事项

1. **数据安全**：不处理敏感数据，不生成包含实际业务数据的SQL
2. **语法差异**：不同数据仓库的SQL语法有差异，需要根据目标类型调整
3. **字段映射**：业务数据库与数据仓库的数据类型可能不同，需要合理映射
4. **性能考虑**：生成的SQL应包含适当的分区、分桶、索引等性能优化建议
5. **中文注释**：确保每个字段都有清晰的中文注释，说明业务含义和数据用途，表名也需添加中文描述

## 错误处理

- 如果无法理解用户意图，请求用户提供更详细的描述
- 如果工具查找失败，提供手动输入表结构的选项
- 如果生成SQL时遇到语法问题，标记出不确定的部分并询问用户

## 相关工具

- `my-remote-mcp_field_matcher`：用于根据中文字段名匹配数据库表信息，获取字段元数据
- 提问工具：用于收集用户输入和确认信息
- 数据分析工具：用于分析业务数据库字段数据，推断字段业务含义（通过字段名、数据类型、示例数据等综合分析）