DuckDB

DuckDB 是一个进程内 SQL OLAP 数据库管理系统。 您可以使用 Hugging Face 路径（hf://）来访问 Hub 上的数据：

DuckDB CLI（命令行界面）是一个独立的、无依赖的可执行文件。 此外，还有其他可用于运行 DuckDB 的 API，包括 Python、C++、Go、Java、Rust 等。有关更多详细信息，请访问其 clients 页面。

有关安装详情，请访问安装页面。

如果使用 hf CLI，你可以使用 hf datasets sql 直接运行 DuckDB 查询，例如 hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3"。对于受控和私有数据集，认证会根据你已登录的令牌自动配置，并且 --format json 会返回机器可读的输出。

从 v0.10.3 版本开始，DuckDB CLI 原生支持通过 hf:// 方案的 URL 访问 Hugging Face Hub 上的数据集。以下是您可以利用此强大工具实现的一些功能：

• 查询公共数据集以及您自己的受限和私有数据集
• 分析数据集并执行 SQL 操作
• 组合数据集并将其导出为不同格式
• 在嵌入数据集上执行向量相似度搜索
• 在数据集上实现全文搜索

如需查看 DuckDB 功能的完整列表，请访问 DuckDB 文档。

要启动 CLI，请在安装文件夹中执行以下命令：

./duckdb

构建 Hugging Face URL

要访问 Hugging Face 数据集，请使用以下 URL 格式：

hf://datasets/{my-username}/{my-dataset}/{path_to_file} 

• my-username，数据集的用户或组织，例如 ibm
• my-dataset，数据集名称，例如：duorc
• path_to_parquet_file，支持 glob 模式的 parquet 文件路径，例如 **/*.parquet，用于查询所有 parquet 文件

您可以使用 @~parquet 分支查询自动转换的 Parquet 文件，该分支对应于 refs/convert/parquet 修订版本。有关更多详细信息，请参阅 https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet 处的文档。

要引用数据集的 refs/convert/parquet 修订版本，请使用以下语法：

已复制

hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 

以下是遵循上述语法的示例 URL：

已复制

hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet

查询数据集

让我们从一个快速演示开始，用于查询数据集的所有行：

FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

或者使用传统的 SQL 语法：

SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

在以下章节中，我们将介绍您可以使用 DuckDB 在 Hugging Face 数据集上执行的更复杂的操作。

查询存储桶：DuckDB 2.0 及更高版本还可以原生读取 存储桶，支持从 CLI 和所有客户端进行读取：

已复制

SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;

Bucket 不支持版本控制，因此 @revision 语法不适用于 bucket 路径。在 DuckDB 1.x 中，请改为从 Python 注册 Hugging Face 文件系统：duckdb.register_filesystem(HfFileSystem())。详情请参阅 使用 DuckDB 查询。

保存数据集

使用 COPY ... TO 语法将数据集保存到 Hugging Face。

1. 安装 DuckDB >=2.0 的 扩展：

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo
  WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

2. 使用 hf CLI 或在 DuckDB 中直接进行身份验证：

• 在 CLI 中：

  已复制

  hf auth login

• 在 DuckDB 中：

  已复制

  CREATE SECRET (TYPE HUGGINGFACE, TOKEN 'hf_...');

3. 如果数据集仓库尚不存在，请创建它：

• 在 CLI 中：

  已复制

  hf repos create username/my-dataset --repo-type dataset --private

• 在 DuckDB 中：

  已复制

  FROM hf_create_repo('hf://datasets/username/my-dataset', private := true);

4. 将您的表格导出到 Hugging Face，例如使用 Parquet 格式：

COPY tbl TO 'hf://datasets/username/my-dataset/out.parquet';

使用 PARTITION_BY 根据分区键将表拆分为多个文件：COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));。文件会根据分区键的值放置在相应的子目录中，例如 'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'。

由于数据集是 git 仓库，每个新文件都是数据集历史中的一个提交。