DuckDB 免下載直接查 Hugging Face 資料集
DuckDB Blog · 2026-09-25
DuckDB 現在可以用一句 SELECT 直接查詢 Hugging Face Hub 上的資料集，不必先把檔案下載到本機，也不必透過 Hugging Face 的 datasets 函式庫轉換格式。只要把查詢對象換成 hf:// 開頭的路徑，DuckDB 就會直接連到遠端資料集，只抓查詢實際用到的那部分資料。
背景：下載再轉檔的舊流程
在這個功能出現以前，要分析 Hugging Face 上的資料集，得先用 huggingface-cli download 或 Hugging Face 的 datasets 函式庫把檔案整包抓到本機，再讀進 pandas 或 DuckDB 裡查詢。這種先下載再轉檔的流程對於只想看幾個欄位、或先確認資料格式對不對的探索性分析來說，往往是不必要的等待與硬碟占用。DuckDB 官方部落格直接點出這個痛點：使用者其實可以「不下載就查詢」資料集本身所在的位置。
核心改動：hf:// 協定與 Secrets 管理
這個能力其實從 DuckDB v0.10.3（2024 年 5 月 22 日發布）就已經存在，靠的是建構在 httpfs extension 之上的 hf:// 路徑格式，語法是 hf://datasets/使用者名稱/資料集名稱/檔案路徑。DuckDB 可以直接讀取 CSV、JSONL 與 Parquet 三種格式，其中 Parquet 是欄式格式，DuckDB 只會抓取查詢實際用到的欄位，不必把整個檔案都下載下來。查詢多個檔案時可以用萬用字元，例如 hf://datasets/cais/mmlu/astronomy/*.parquet 就能一次涵蓋整個子資料夾，甚至能把來自不同資料夾的多個 Parquet 檔案丟進 read_parquet([...]) 一起 GROUP BY。
如果要鎖定特定版本，可以在資料集名稱後面加上 @，指向分支名稱或 commit hash，例如 hf://datasets/cais/mmlu@c30699e8356da336a370243923dbaf21066bb9fe/astronomy/*.parquet；Hugging Face 也會把資料集自動轉成 Parquet 放在 ~parquet 分支，讓查詢效率更好。私有或 gated 資料集則要先用 DuckDB 的 Secrets Manager 建立憑證，例如 CREATE SECRET hf_token (TYPE huggingface, TOKEN '你的token')，或改用 CREATE SECRET hf_token (TYPE huggingface, PROVIDER credential_chain)讓 DuckDB 自動抓取本機已存的登入憑證。
影響範圍：誰該檢查什麼
這個改動主要影響資料工程師、做探索分析的資料科學家，以及需要串接公開資料集的 pipeline。實際導入前建議先確認以下幾件事：
- 資料集是否為私有或 gated：需要先設定
CREATE SECRET，用固定 token 或credential_chain自動抓取登入憑證。 - 資料格式是否落在支援範圍內：目前只涵蓋 CSV、JSONL、Parquet，其他格式仍得走原本的下載流程。
- 效能特性和本地檔案不同：查詢是透過網路讀取遠端檔案，處理整個資料集前可以先用
count(*)這類輕量查詢確認資料量，再用COPY ... TO把結果落地成本機檔案。
舊流程與新流程的差異，最直接反映在下面兩段對照：下載轉檔要分兩三個步驟，新方法只是把資料表換成一個網址。
# 舊流程：先下載整個資料集，再用 Python 載入查詢
huggingface-cli download cais/mmlu \
--repo-type dataset --local-dir ./mmlu
python3 -c "
import pandas as pd
df = pd.read_parquet('./mmlu/astronomy/test-00000-of-00001.parquet')
print(df[df.question.str.contains('planet')])
"-- 新流程：一句 SQL 直接查詢遠端資料集
SELECT count(*) AS count
FROM 'hf://datasets/cais/mmlu/astronomy/*.parquet'
WHERE question LIKE '%planet%';原始來源：DuckDB Blog - DuckDB and Hugging Face: Querying Datasets Directly