httpfs 扩展引入了对 hf:// 协议的支持，用于访问托管在 Hugging Face 仓库中的数据集。详情请参阅发布博客文章。

用法

可以使用以下 URL 模式查询 Hugging Face 仓库

hf://datasets/⟨my_username⟩/⟨my_dataset⟩/⟨path_to_file⟩

例如，要读取 CSV 文件，可以使用以下查询

SELECT *
FROM 'hf://datasets/datasets-examples/doc-formats-csv-1/data.csv';

其中

• datasets-examples 是用户/组织名称
• doc-formats-csv-1 是数据集仓库名称
• data.csv 是仓库中的文件路径

查询结果为

要读取 JSONL 文件，可以运行

SELECT *
FROM 'hf://datasets/datasets-examples/doc-formats-jsonl-1/data.jsonl';

最后，若要读取 Parquet 文件，请使用以下查询

SELECT *
FROM 'hf://datasets/datasets-examples/doc-formats-parquet-1/data/train-00000-of-00001.parquet';

这些命令中的每一个都会从指定的文件格式中读取数据，并以结构化的表格格式显示。请根据您所处理的文件格式选择相应的命令。

创建本地表

为了避免每次查询都访问远程端点，您可以运行 CREATE TABLE ... AS 命令将数据保存到 DuckDB 表中。例如

CREATE TABLE data AS
    SELECT *
    FROM 'hf://datasets/datasets-examples/doc-formats-csv-1/data.csv';

然后，只需按如下方式查询 data 表即可

SELECT *
FROM data;

多个文件

要查询特定目录下的所有文件，可以使用 glob 模式。例如

SELECT count(*) AS count
FROM 'hf://datasets/cais/mmlu/astronomy/*.parquet';

通过使用 glob 模式，您可以高效地处理大型数据集，并在多个文件上执行综合查询，从而简化数据检查和处理任务。在这里，您可以查看如何搜索天文学中包含单词“planet”（行星）的问题

SELECT count(*) AS count
FROM 'hf://datasets/cais/mmlu/astronomy/*.parquet'
WHERE question LIKE '%planet%';

版本控制与修订（Revisions）

在 Hugging Face 仓库中，数据集版本或修订版代表不同的数据集更新。每个版本都是特定时间点的快照，使您能够跟踪更改和改进。在 Git 术语中，它可以理解为一个分支或特定的提交。

您可以使用以下 URL 查询不同的数据集版本/修订版

hf://datasets/my_username/my_dataset@my_branch/path_to_file

例如

SELECT *
FROM 'hf://datasets/datasets-examples/doc-formats-csv-1@~parquet/**/*.parquet';

上述查询将读取 ~parquet 修订版下的所有 Parquet 文件。这是一个特殊的分支，Hugging Face 会自动在此生成每个数据集的 Parquet 文件，以实现高效扫描。

身份验证

在 DuckDB Secrets Manager（密钥管理器）中配置您的 Hugging Face 令牌，以访问私有或受限数据集。首先，访问 Hugging Face 设置 – 令牌 (Tokens) 以获取您的访问令牌。其次，使用 DuckDB 的 Secrets Manager 在您的 DuckDB 会话中进行设置。DuckDB 支持两种用于管理密钥的提供程序：

CONFIG

用户必须将所有配置信息传入 CREATE SECRET 语句中。要使用 CONFIG 提供程序创建密钥，请使用以下命令

CREATE SECRET hf_token (
    TYPE huggingface,
    TOKEN 'your_hf_token'
);

credential_chain

自动尝试获取凭据。对于 Hugging Face 令牌，它会尝试从 ~/.cache/huggingface/token 获取。要使用 credential_chain 提供程序创建密钥，请使用以下命令

CREATE SECRET hf_token (
    TYPE huggingface,
    PROVIDER credential_chain
);