apconw 架构探索技能
何时使用此技能
当您需要以下操作时使用此技能：
- 理解数据库结构
- 查找包含特定类型数据的表
- 发现列名和数据类型
- 映射表之间的关系
- 为 SQL 生成准备 M-Schema 格式的结构信息
- 回答诸如"有哪些表可用？"或"Customer 表有哪些列？"等问题
工作流程
1. 列出所有表
使用 sql_db_list_tables 工具查看数据库中所有可用的表。
这将返回您可以查询的完整表列表。
2. 智能表过滤（针对复杂查询）
当数据库表较多时，不要盲目获取所有表的 schema，而是先进行智能过滤：
- 获取表列表后，根据用户问题进行语义分析，提取关键实体和意图
- 匹配策略：
- 将关键词与表名、表注释进行语义匹配（如"销售额" → 可能涉及 orders、sales、products 等表）
- 考虑表之间的潜在关联（如用户问"客户订单"，需要同时选中 customers 和 orders）
- 忽略明显无关的系统表、日志表、临时表
- 输出：筛选后的相关表名列表（通常 3-8 张表）
内部思考模板：
用户问题：{user_question}
数据库所有表：
- {table1}, {table2}, ...
任务：从上述表中选出与用户问题直接相关的表。
考虑因素：
1. 表名是否与问题中的实体/指标匹配
2. 是否需要关联表来补充维度信息
3. 忽略明显无关的系统表、日志表
选出的相关表：[table1, table2, ...]
3. 获取特定表的架构
使用 sql_db_schema 工具配合表名来检查：
- 列名 - 有哪些字段可用
- 数据类型 - INTEGER, TEXT, DATETIME 等
- 示例数据 - 示例数据以了解内容
- 主键 - 行的唯一标识符
- 外键 - 与其他表的关系
- 列注释 - 字段含义说明
提示：可以一次传入多个表名（逗号分隔），减少工具调用次数。
4. 获取表关系
使用 sql_db_table_relationship 工具获取表之间的外键/关联关系：
- 关联字段 - 两表通过哪些字段关联
- JOIN 条件 - 返回格式如
t_orders.customer_id = t_customers.id
示例调用：
sql_db_table_relationship("t_orders, t_customers, t_products")
如果未配置表关系，可以通过以下方式推断：
- 查找以 "Id" 或 "_id" 结尾的列（例如，customer_id, product_id）
- 外键列名通常对应另一个表的主键
- 记录父子关系
5. 生成 M-Schema 格式（用于 SQL 生成）
当需要将 schema 信息传递给后续 SQL 生成步骤时，使用 M-Schema 格式组织信息：
【DB_ID】 {db_name}
【Schema】
# Table: {table_name}, {table_comment}
[
({column_name}:{column_type}, {column_comment}),
]
{foreign_key_1}
{foreign_key_2}
数据库特定规则：
- PostgreSQL/Oracle/SQL Server: 使用
schema.table_name格式 - MySQL/ClickHouse/SQLite: 使用纯
table_name
引号规则：
| 数据库类型 | 引号 |
|---|---|
| MySQL | `反引号` |
| PostgreSQL | "双引号" |
| SQLite | "双引号" |
| SQL Server | [方括号] |
| Oracle | "双引号" |
| ClickHouse | "双引号" |
6. 回答问题
提供清晰的信息：
- 可用表及其用途
- 列名及其包含的内容
- 表之间的关联方式
- 示例数据以说明内容
示例："有哪些表可用？"
步骤 1： 使用 sql_db_list_tables
响应：
数据库包含多个表：
1. Customer - 存储客户信息
2. Employee - 存储员工信息
3. Invoice - 客户购买记录
4. InvoiceLine - 发票中的单个项目
...
示例："这些表之间有什么关系？"
步骤 1： 使用 sql_db_table_relationship("Customer, Invoice, InvoiceLine")
响应：
表之间的关系如下：
• Invoice.CustomerId = Customer.Id
• InvoiceLine.InvoiceId = Invoice.Id
✅ 表关系已获取完成。
示例："准备查询销售额数据的 M-Schema"
步骤 1： sql_db_list_tables → 智能过滤出 orders, products, customers
步骤 2： sql_db_schema("orders, products, customers") → 获取完整 schema
步骤 3： sql_db_table_relationship("orders, products, customers") → 获取关系
步骤 4： 组织为 M-Schema 格式：
【DB_ID】 sales_db
【Schema】
# Table: orders, 订单表
[
(id:INTEGER, 订单ID),
(customer_id:INTEGER, 客户ID),
(product_id:INTEGER, 产品ID),
(amount:DECIMAL, 订单金额),
(order_date:DATETIME, 下单时间),
]
orders.customer_id = customers.id
orders.product_id = products.id
# Table: products, 产品表
[
(id:INTEGER, 产品ID),
(name:VARCHAR, 产品名称),
(category:VARCHAR, 产品类别),
(price:DECIMAL, 单价),
]
# Table: customers, 客户表
[
(id:INTEGER, 客户ID),
(name:VARCHAR, 客户名称),
(region:VARCHAR, 所属区域),
]
质量指南
对于"列出表"问题：
- 显示所有表名
- 添加每个表包含内容的简要描述
- 对相关表进行分组（例如，交易、人员）
对于"描述表"问题：
- 列出所有列及其数据类型
- 解释每列包含的内容
- 显示示例数据以提供上下文
- 注明主键和外键
- 解释与其他表的关系
对于"如何查询 X"问题：
- 识别所需的表
- 映射 JOIN 路径
- 解释关系链
- 建议下一步（使用查询编写技能）
对于复杂查询准备：
- 使用智能表过滤，只选相关表
- 生成 M-Schema 格式供 SQL 生成使用
- 明确标注表关系和 JOIN 条件
常见探索模式
模式 1：查找表
"哪个表包含客户信息？" → 使用 list_tables，然后描述 Customer 表
模式 2：理解结构
"Invoice 表中有什么？" → 使用 schema 工具显示列和示例数据
模式 3：映射关系
"客户如何与发票关联？"
→ 使用 sql_db_table_relationship("Customer, Invoice, InvoiceLine") 获取关系
模式 4：查询准备
"我要分析各产品销售情况" → 智能过滤 → 获取 schema → 获取关系 → 输出 M-Schema
提示
- 外键通常以 "Id" 结尾，并匹配表名
- 使用示例数据了解值的格式
- 不确定使用哪个表时，先列出所有表
- 获取 schema 时尽量一次传入多个相关表名，减少工具调用
- M-Schema 格式有助于后续 SQL 生成的准确性