---
name: warehouse-table-sql-doris
description: 根据现有业务表生成Doris数据仓库建表SQL代码，遵循严格的字段处理和注释规范
license: MIT
compatibility: opencode
metadata:
  audience: data engineers
  workflow: data warehouse development
  target_db: Apache Doris
---

## 功能概述

本技能根据现有的业务数据库表结构，生成Apache Doris数据仓库的建表SQL代码。技能严格遵循以下原则：
1. 不增加新字段（除非用户明确要求）
2. 为每个表和字段添加详细中文说明
3. 对含义不明确的字段，通过查询业务数据或询问用户来明确含义
4. 排除与分析无关的字段
5. 优化表和字段命名，使其更能反映业务意图
6. 为常用字段创建索引
7. 输出JSON格式的建表定义，包含表名、描述、字段集合和完整SQL代码
8. 生成的SQL文件保存到项目`create8-sql`目录下
9. 生成的SQL代码包含`IF NOT EXISTS`控制
10. 调用工具测试SQL语法有效性

## 使用前准备

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

1. **业务表来源**：业务表定义的位置（Go结构体文件、数据库连接、SQL文件等）
2. **目标数据仓库**：Apache Doris（本技能专用）
3. **项目路径**：生成的SQL文件保存的项目目录（默认为当前项目的`create8-sql`目录）

## 工作流程

### 1. 确定业务表来源
- 询问用户业务表定义的来源（如Go结构体文件、现有数据库、SQL脚本等）
- 根据来源采取相应的读取策略：
  - **Go结构体文件**：读取`tables`目录下的`.go`文件，解析`sqldef`定义或GORM标签
  - **数据库连接**：需要用户提供连接信息，使用相应工具查询表结构
  - **SQL文件**：读取现有SQL建表语句

### 2. 提取表结构
- 使用`glob`和`read`工具查找并读取业务表定义文件
- 解析表名、字段名、数据类型、长度、是否可为空、默认值、注释等信息
- 如果字段缺少注释或含义不明确，执行以下步骤：
  - 优先查询业务数据库的示例数据（如果可访问）
  - 使用数据分析工具推断字段含义
  - 如果仍不明确，使用提问工具向用户询问字段含义

### 3. 筛选相关字段
- 根据数据分析需求，排除与分析无关的字段（如内部ID、审计字段等）
- 保留业务分析相关的字段（如金额、数量、状态、时间等）
- 如果用户有特定要求，按用户指示筛选

### 4. 优化命名
- 检查表和字段命名是否符合规范
- 对命名不规范的字段进行重命名，使其更能反映业务意图：
  - 使用中文拼音或缩写字段名转换为英文描述性名称
  - 统一命名风格（蛇形命名法`snake_case`）
  - 确保名称简洁且含义明确

### 5. 生成Doris表结构
- 将业务数据类型映射到Doris兼容类型：
  - `VARCHAR` → `VARCHAR`
  - `INT` → `INT`
  - `BIGINT` → `BIGINT`
  - `DATETIME` → `DATETIME`
  - `DECIMAL` → `DECIMAL`
  - `TEXT` → `STRING`
  - 注意Doris特有类型：`ARRAY`、`MAP`、`BITMAP`等
- 添加Doris表属性：
  - `ENGINE=OLAP`
  - `DUPLICATE KEY`或`UNIQUE KEY`或`AGGREGATE KEY`
  - `DISTRIBUTED BY HASH`分桶
  - `PROPERTIES`配置（如`replication_num`）

### 6. 添加中文注释
- 为每个字段生成详细的中文注释，说明：
  - 字段的业务含义
  - 数据格式和取值范围
  - 与其他字段的关系
- 为表生成中文描述，说明：
  - 表的业务用途
  - 数据来源和更新频率
  - 主要分析维度

### 7. 创建索引
- 为常用查询字段创建索引：
  - 时间字段（`created_at`、`updated_at`）
  - 状态字段（`status`）
  - 外键字段（`user_id`、`order_id`）
  - 高频过滤字段
- 使用Doris的`INDEX`语法或`BITMAP`索引

### 8. 生成JSON输出
- 按照以下JSON格式组织输出：
```json
{
  "table_name": "表英文名",
  "description": "表中文描述",
  "fields": [
    {
      "name": "字段名",
      "length": "字段长度",
      "type": "字段类型",
      "description": "字段中文描述"
    }
  ],
  "create_sql": "完整的建表SQL语句"
}
```

### 9. 保存文件
- 在项目根目录下创建`create8-sql`目录（如果不存在）
- 生成文件名格式：`{表名}_doris_create.json`
- 使用`write`工具将JSON内容写入文件
- 同时生成一个纯SQL文件（可选）：`{表名}_doris_create.sql`

### 10. 测试SQL语法
- 调用Bash工具测试生成的SQL语法：
  - 如果有Doris测试环境，使用`echo "SQL" | doris-cli`进行验证
  - 如果没有，使用`mysql --parse`进行基本语法检查（注意Doris与MySQL的差异）
  - 报告任何语法错误并修正

## 输出示例

### JSON格式输出
```json
{
  "table_name": "dw_user_info",
  "description": "用户基本信息表，包含用户身份、联系方式和状态信息",
  "fields": [
    {
      "name": "user_id",
      "length": "",
      "type": "BIGINT",
      "description": "用户唯一标识符，系统自动生成的主键ID"
    },
    {
      "name": "user_name",
      "length": "100",
      "type": "VARCHAR",
      "description": "用户真实姓名，用于身份识别和显示"
    },
    {
      "name": "email",
      "length": "200",
      "type": "VARCHAR",
      "description": "用户电子邮箱地址，用于登录和接收通知"
    }
  ],
  "create_sql": "CREATE TABLE IF NOT EXISTS dw_user_info (\n    user_id BIGINT COMMENT '用户唯一标识符，系统自动生成的主键ID',\n    user_name VARCHAR(100) COMMENT '用户真实姓名，用于身份识别和显示',\n    email VARCHAR(200) COMMENT '用户电子邮箱地址，用于登录和接收通知',\n    phone VARCHAR(20) COMMENT '用户手机号码，用于登录验证和联系',\n    status TINYINT COMMENT '用户状态：0-禁用，1-正常，2-锁定',\n    created_at DATETIME COMMENT '用户注册时间，记录账户创建时间戳',\n    updated_at DATETIME COMMENT '最后更新时间，记录用户信息修改时间'\n) ENGINE=OLAP\nDUPLICATE KEY(user_id)\nDISTRIBUTED BY HASH(user_id) BUCKETS 10\nPROPERTIES (\n    \"replication_num\" = \"3\"\n);\nCOMMENT ON TABLE dw_user_info IS '用户基本信息表，包含用户身份、联系方式和状态信息';"
}
```

### 纯SQL输出
```sql
-- 数据仓库建表语句 (Apache 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
DUPLICATE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10
PROPERTIES (
    "replication_num" = "3"
);

COMMENT ON TABLE dw_user_info IS '用户基本信息表，包含用户身份、联系方式和状态信息';
```

## 注意事项

1. **字段控制**：绝不增加新字段，除非用户明确说明要增加什么字段
2. **注释完整性**：确保每个字段和表都有详细的中文注释
3. **数据安全**：不查询真实业务数据（除非用户明确授权），使用示例数据或元数据分析
4. **Doris语法**：注意Doris与MySQL的语法差异，特别是：
   - 表属性配置（`PROPERTIES`）
   - 索引类型（`BITMAP`、`INVERTED`）
   - 分区和分桶语法
   - 数据模型（Duplicate、Unique、Aggregate）
5. **命名规范**：优化命名时保持与业务系统的一致性，避免混淆
6. **文件保存**：确保`create8-sql`目录存在，文件命名清晰

## 错误处理

- 如果无法解析业务表结构，请求用户提供更详细的信息或手动输入
- 如果字段含义不明确且无法查询数据，必须询问用户
- 如果Doris语法检查失败，查找文档修正语法错误
- 如果文件保存失败，检查目录权限和磁盘空间

## 相关工具

- `glob`：查找业务表定义文件
- `read`：读取文件内容
- `grep`：搜索特定模式
- `write`：保存生成的JSON和SQL文件
- `bash`：测试SQL语法
- `question`：询问用户字段含义和确认信息