httpfs 扩展引入了对 hf:// 协议的支持，以访问托管在 Hugging Face 仓库中的数据集。有关详细信息，请参阅公告博客文章。

用法

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

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%';

版本控制和修订

在 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 设置 – 令牌 以获取您的访问令牌。其次，使用 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
);