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;

次のセクションでは、Hugging Faceのデータセットに対してDuckDBで実行できるより複雑な操作について説明します。

Storage Buckets のクエリ: DuckDB 2.0 以降では、Storage Buckets を CLI およびすべてのクライアントからネイティブに読み取れます:

コピーしました

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

バケットにはバージョン管理がないため、@revision 構文はバケットパスには適用されません。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 リポジトリであるため、新しいファイルの各々はデータセットの履歴におけるコミットです。