01 BIRD-SQL 数据集解析与领域模型映射

起凡2026/3/30大约 4 分钟

在构建我们的 Text2SQL Agent 之前，我们需要先喂给它足够的“养料”。业界著名的 BIRD-SQL (A Big Bench for Large-Scale Database Grounded Text-to-SQLs) 数据集就是绝佳的训练和测试素材。

本文将带大家拆解 BIRD 数据集的核心文件结构，并展示如何将这些庞杂的 JSON 文件和 SQLite 数据库，优雅地映射到我们系统后端的领域模型（Domain Model）中。

1. 认识 BIRD 数据集结构

下载并解压 BIRD 的 dev.zip 后，你会看到一个非常庞大的文件树。对于 Text2SQL 任务，我们最需要关注以下三个核心部分：

1.1 `dev_databases/` 目录：物理数据库

这里面存放了多个 SQLite 格式的物理数据库文件（例如 california_schools.sqlite, card_games.sqlite 等）。它们包含了真实的表结构和数据行，用来验证最终生成的 SQL 是否能跑通。

关键概念：db_id

每个数据库文件夹的名字（如 california_schools），就是我们后续系统用来隔离多租户/多数据库的唯一标识 db_id（在我们的代码中称为 databaseId）。

1.2 `dev_tables.json`：表结构元数据

这个文件非常关键，它用 JSON 数组的形式，详细记录了每个数据库下的所有表名、列名、字段类型以及主外键关系。

{
  "db_id": "california_schools",
  "table_names_original": ["schools", "satscores", "frpm"],
  "table_names": ["Schools Info", "SAT Scores", "Free Meal"],
  "column_names_original": [[-1, "*"], [0, "CDSCode"], [0, "Street"], [1, "cds"]],
  "column_types": ["text", "text", "text", "text"],
  "foreign_keys": [[3, 1]], 
  "primary_keys": [1, 3]
}

结构解析难点

你会发现 BIRD 的列信息和主外键信息大量使用了异构数组和索引指针（例如 [0, "CDSCode"] 代表第 0 张表的 CDSCode 列，外键 [3, 1] 代表第 3 列指向第 1 列）。在将这些结构导入数据库时，我们需要进行复杂的索引计算和映射。

1.3 `dev.json`：问答与外部知识 (Evidence)

这里存放了 Text2SQL 任务的核心资产：自然语言问题（Question）、大模型生成 SQL 所需的外部推理知识（Evidence），以及作为标准答案的 SQL 语句。

{
  "question_id": 37,
  "db_id": "california_schools",
  "question": "What is the complete address of the school with the lowest excellence rate?",
  "evidence": "Execellence Rate = NumGE1500 / NumTstTakr; complete address has Street, City, Zip, State",
  "SQL": "SELECT T2.Street, T2.City FROM schools ...",
  "difficulty": "moderate"
}

2. 领域模型（Entity）映射设计

了解了原始数据，我们如何把它们装进自己的系统里？结合基于 Jimmer 编写的实体类，我们的映射架构如下：

2.1 结构映射 (Schema Mapping)

我们要将 dev_tables.json 中的数组，转换为面向对象的关系型实体。所有的实体都通过 databaseId 进行逻辑隔离。

DbTable (数据表)
- databaseId 绑定到 JSON 中的 db_id。
- name 绑定到 table_names_original 中的真实表名。
- description 绑定到 table_names 中的直观描述。
DbColumn (数据列)
- name 和 type 分别对应 column_names_original 和 column_types。
- dbTable 级联关联到所属的 DbTable。
DbForeignKey (外键关联)
- 将 foreign_keys 数组中指示的索引对，转换为指向实际 DbColumn 的 sourceColumn 和 targetColumn 关联关系。

2.2 知识映射 (Knowledge Mapping)

仅仅知道表结构是不够的。BIRD 数据集的精髓在于其丰富的业务语境（Evidence），这对于 Agent 命中正确的 SQL 至关重要。

QuestionKnowledge (问答语料库)
- 提取 JSON 的 question 和 SQL 组成问答对，作为大模型的高质量 Few-Shot（少样本提示）素材。
GlossaryKnowledge (业务词典)
- 提取 dev.json 中的 evidence 字段。例如，把 "Execellence Rate = NumGE1500 / NumTstTakr" 提取为具体的业务公式词条，供 Agent 在生成 SQL 时检索参考。

3. 迈向向量检索 (Vector Retrieval)

值得一提的是，在我们的领域模型中，我们为这些实体都设计了 toDocument() 方法。

向量化铺垫

无论是表结构（Table/Column）还是知识（Knowledge），最终都会被转化为带有 Metadata（如 VECTOR_TYPE, DATABASE_ID）的 Document 对象。这为我们后续利用 Spring AI 将它们写入向量数据库做好了完美的铺垫。

4. 总结与预告

通过上述映射，我们成功地把 BIRD 扁平、松散的 JSON 结构，转化为了高度结构化的领域驱动模型（Domain Driven Model）。

但纸上得来终觉浅，如何在代码中解析那些复杂的索引，并优雅地保存进关系型数据库？

在下一篇文章《Text2SQL 核心实战：如何优雅地将 BIRD 数据集解析并导入数据库》中，我们将正式动手写代码，解决**“剥离级联保存”以及“通过内存映射快速匹配外键”**等核心痛点。敬请期待！