motherduckdb/duckdb-text2sql-25k

---
license: cc-by-sa-4.0
task_categories:
- text2text-generation
language:
- en
tags:
- text-2-sql
pretty_name: duckdb-text2sql-25k
size_categories:
- 10K<n<100K
---

# Dataset Summary

The duckdb-text2sql-25k dataset contains 25,000 DuckDB text-2-sql pairs covering diverse aspects of DuckDB's SQL syntax.

We synthesized this dataset using [Mixtral 8x7B](https://huggingface.co/mistralai/Mixtral-8x7B-v0.1), based on [DuckDB's v0.9.2 documentation](https://duckdb.org/docs/archive/0.9/) and [Spider](https://huggingface.co/datasets/spider) schemas that were translated to DuckDB syntax and enriched with nested type columns.

Each training sample consists of a natural language prompt, a corresponding (optional) schema, and a resulting query. Each pair furthermore has a category property that indicates which part of the documentation was used generate the sample.

We applied various techniques to validate the syntactical and semantic correctness of the synthesized statements.

# How to use it

```python
from datasets import load_dataset

dataset = load_dataset("motherduckdb/duckdb-text2sql-25k")
```

We recommend using a prompt template similar to the one used for [DuckDB-NSQL-7B](https://huggingface.co/motherduckdb/DuckDB-NSQL-7B-v0.1#how-to-use) training.

# Dataset Structure

## Data Fields

- `prompt` (string): the instruction to generate SQL.
- `query` (string): the SQL statement.
- `schema` (string): the associated schema as CREATE TABLE statements.
- `category` (string): the category of the query.

# Languages

The language of the data is primarily English.

# Source Data and Licensing Information

Schemas in this dataset are derived from [Spider](https://huggingface.co/datasets/spider), with CC-BY-SA-4.0 License. We publish our dataset under the same license.

许可证：知识共享署名-相同方式共享4.0（CC-BY-SA-4.0）
任务类别：
- 文本到文本生成（text2text-generation）
语言：
- 英语（en）
标签：
- 文本到SQL（text-2-sql）
展示名称：duckdb-text2sql-25k
样本量区间：10000 < 样本量 < 100000

# 数据集概览

本数据集`duckdb-text2sql-25k`包含25000条DuckDB文本到SQL（text-2-sql）样本对，涵盖DuckDB SQL语法的各类应用场景。
我们借助Mixtral 8x7B完成了本数据集的合成工作，数据集基于[DuckDB v0.9.2官方文档](https://duckdb.org/docs/archive/0.9/)与已转换为DuckDB语法并补充了嵌套类型列的[Spider](https://huggingface.co/datasets/spider)数据集的架构（schema）生成。
每条训练样本包含一条自然语言提示词（prompt）、对应的可选架构（schema）以及生成的SQL查询语句。此外，每对样本还带有类别属性，用于标识生成该样本时所参考的文档章节。
我们采用多种技术手段，对合成生成的SQL语句的语法正确性与语义合理性进行了校验。

# 使用方式

python
from datasets import load_dataset

dataset = load_dataset("motherduckdb/duckdb-text2sql-25k")

我们建议使用与[DuckDB-NSQL-7B](https://huggingface.co/motherduckdb/DuckDB-NSQL-7B-v0.1#how-to-use)模型训练时一致的提示词（prompt）模板。

# 数据集结构

## 数据字段

- `prompt`（字符串类型）：用于生成SQL的自然语言提示词（prompt）
- `query`（字符串类型）：生成的SQL查询语句
- `schema`（字符串类型）：以CREATE TABLE语句形式呈现的关联数据库架构（schema）
- `category`（字符串类型）：该查询的所属类别

# 语言说明

本数据集的数据语言以英语为主。

# 源数据与授权信息

本数据集的架构（schema）源自[Spider](https://huggingface.co/datasets/spider)数据集，其原授权协议为知识共享署名-相同方式共享4.0（CC-BY-SA-4.0）。本数据集沿用相同的授权协议发布。

原始信息汇总

数据集概述

数据集名称

• pretty_name: duckdb-text2sql-25k

数据集内容

• 描述: 包含25,000个DuckDB文本到SQL的配对，覆盖DuckDB SQL语法的多个方面。
• 生成方式: 使用Mixtral 8x7B模型合成，基于DuckDB v0.9.2文档和Spider数据集的架构，经过转换和增强处理。
• 样本组成: 每个样本包括自然语言提示、相应的（可选）架构和生成的查询，以及指示生成样本所用文档部分的类别属性。

数据集结构

• 数据字段:
  • prompt (字符串): 生成SQL的指令。
  • query (字符串): SQL语句。
  • schema (字符串): 相关的架构，以CREATE TABLE语句表示。
  • category (字符串): 查询的类别。

语言

• 主要语言: 英语

许可信息

• 许可证: CC-BY-SA-4.0
• 源数据许可: 架构来源于Spider数据集，同样使用CC-BY-SA-4.0许可证。

搜集汇总

数据集介绍

构建方式

在自然语言处理与数据库交叉领域中，Text-to-SQL任务旨在将人类自然语言查询自动转化为可执行的结构化查询语言。该数据集名为duckdb-text2sql-25k，由MotherDuck团队精心构建，专注于DuckDB这一高性能分析数据库的SQL语法。构建过程中，研究团队基于DuckDB v0.9.2的官方文档以及Spider数据集中的数据库模式，借助Mixtral 8x7B大语言模型进行合成。Spider模式被转换为DuckDB兼容的语法，并额外丰富了嵌套类型列。最终生成了25,000条包含自然语言提示、可选模式与对应查询语句的配对样本，每对样本还附有类别属性以标识生成来源。为确保质量，团队采用多种验证手段，对合成语句进行了语法与语义正确性的严格校验。

特点

该数据集的核心特点在于其高度针对性与多样性。它全面覆盖DuckDB SQL语法的各个维度，从基础查询到复杂嵌套类型操作均有涉及，为特定数据库引擎的Text-to-SQL模型训练提供了稀缺资源。每个样本由提示、查询、模式及类别四个字段构成，结构清晰且信息丰富。类别属性不仅反映了样本源自文档的不同章节，还便于研究者分析模型在不同SQL主题上的表现。此外，数据规模适中（25,000条），既保证了统计有效性，又避免了过大数据集带来的训练负担。基于CC-BY-SA-4.0许可协议发布，确保了学术与商业使用的合规性。

使用方法

使用该数据集极为便捷，开发者可通过HuggingFace的datasets库直接加载，仅需一行代码即可获取完整数据。推荐在训练时采用与DuckDB-NSQL-7B模型类似的提示模板，以充分发挥数据集的效能。数据集的四个字段——prompt（自然语言指令）、query（生成的SQL语句）、schema（以CREATE TABLE语句呈现的关联模式）以及category（查询类别），为模型微调或评估提供了标准化输入输出格式。研究者可基于类别属性对模型进行分领域性能分析，或利用schema字段增强模型对数据库结构的理解。该数据集尤其适合用于训练面向DuckDB的专用Text-to-SQL模型，或作为通用模型在特定数据库引擎上的迁移学习基准。

背景与挑战

背景概述

在自然语言处理与数据库交叉领域，将人类自然语言查询自动转化为结构化查询语言（Text-to-SQL）一直是人工智能研究的热点问题。2023年，由MotherDuck团队主导创建的duckdb-text2sql-25k数据集应运而生，旨在推动面向新兴分析型数据库DuckDB的Text-to-SQL能力发展。该数据集由Mixtral 8x7B模型基于DuckDB v0.9.2官方文档和经语法转换及嵌套类型列增强的Spider数据集模式自动合成，包含25,000条覆盖DuckDB多样化SQL语法特性的自然语言与查询对。作为首个大规模专门针对DuckDB的Text-to-SQL资源，它不仅填补了该领域的数据空白，还为后续如DuckDB-NSQL-7B等专用模型的训练提供了关键基础，对推动轻量级、高性能分析数据库的智能交互界面研究具有重要影响。

当前挑战

该数据集面临的核心挑战首先来自于其自动合成数据的本质：尽管采用了多种语法和语义验证技术，但由大语言模型生成的查询对在复杂嵌套查询、边界情况处理及多表关联逻辑上的准确性与一致性仍难以完全保证，可能引入模型偏见或错误模式。其次，数据集构建过程中面临的技术挑战在于如何将通用的Spider模式精准转换为DuckDB特有的语法结构，并有效融入其支持嵌套类型列的独特特性，这要求对两种系统有深刻理解且转换过程需高度自动化。此外，现有数据集仅覆盖DuckDB v0.9.2文档范围，随着DuckDB快速迭代，数据集的时效性和对新语法特性的覆盖度将成为长期挑战，制约其在持续演进的真实应用场景中的泛化能力。

常用场景

经典使用场景

在自然语言处理与数据库交叉研究领域，duckdb-text2sql-25k数据集为Text-to-SQL任务提供了高质量的微调与评估基准。该数据集包含25,000条精心构建的自然语言查询与DuckDB SQL语句配对样本，覆盖DuckDB v0.9.2文档中多样化的SQL语法特性。研究者可基于该数据集训练模型将自由文本问题精准转化为可执行的SQL查询，尤其适用于处理嵌套类型列等DuckDB特有语法结构，为分析型数据库的自然语言交互研究奠定了坚实基础。

实际应用

在实际应用中，该数据集赋能数据分析师与业务人员通过自然语言直接交互DuckDB数据库，降低SQL学习门槛。基于此数据集训练的模型可嵌入商业智能工具，实现即席查询的自动生成，例如用户输入“各品类上月销售额及环比增长率”即可输出对应的DuckDB聚合查询。此外，该数据集支持数据管道自动化场景，帮助开发者快速将自然语言描述的数据转换逻辑转化为可维护的SQL脚本，大幅提升数据工程效率。

衍生相关工作

该数据集衍生出多个经典工作，包括DuckDB-NSQL-7B模型——一个基于该数据微调的开源Text-to-SQL大语言模型，展示了在分析型查询上的卓越性能。研究者还将其用于跨数据库方言迁移学习，验证了从通用SQL到DuckDB特有语法的知识迁移可行性。此外，基于该数据集的语法验证方法催生了新的SQL生成质量评估框架，推动了对模型输出句法与语义一致性的深入研究，为构建更可靠的数据库自然语言接口提供了方法论支撑。