hugging-face-dataset-viewer

Hugging Face Dataset Viewer

データセットの探索や抽出のために、読み取り専用の Dataset Viewer API 呼び出しを実行する際に使用します。

基本的なワークフロー

1. 必要に応じて、/is-valid でデータセットの利用可否を確認します。
2. /splits で config と split を特定します。
3. /first-rows でプレビューします。
4. offset と length（最大 100）を指定して /rows で内容をページ分割して取得します。
5. テキストの照合には /search、行の条件指定には /filter を使用します。
6. /parquet で Parquet のリンクを取得し、/size と /statistics で合計値やメタデータを取得します。

デフォルト設定

• ベース URL：https://datasets-server.huggingface.co
• デフォルトの API メソッド：GET
• クエリパラメーターは URL エンコードしてください。
• offset は 0 起点です。
• 行を扱うエンドポイントの length の最大値は、通常 100 です。
• ゲート付き／非公開データセットには、Authorization: Bearer <HF_TOKEN> が必要です。

Dataset Viewer

• データセットを検証：/is-valid?dataset=<namespace/repo>
• サブセットと分割を一覧表示：/splits?dataset=<namespace/repo>
• 先頭の行をプレビュー：/first-rows?dataset=<namespace/repo>&config=<config>&split=<split>
• 行をページ分割して取得：/rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int>
• テキストを検索：/search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int>
• 条件でフィルタリング：/filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int>
• Parquet シャードを一覧表示：/parquet?dataset=<namespace/repo>
• サイズの合計値を取得：/size?dataset=<namespace/repo>
• 列の統計情報を取得：/statistics?dataset=<namespace/repo>&config=<config>&split=<split>
• Croissant メタデータを取得（利用可能な場合）：/croissant?dataset=<namespace/repo>

ページネーションのパターン：

curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=0&length=100"
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=100&length=100"

ページネーションが一部のみの場合は、num_rows_total、num_rows_per_page、partial などのレスポンスフィールドを使用して、継続処理を制御します。

検索とフィルタリングに関する注意事項：

• /search は文字列型の列を照合します（全文検索のような動作は API 内部で処理されます）。
• /filter では where に条件式の構文が必要です。また、orderby で並べ替えを指定できます。
• フィルタリングと検索は読み取り専用で、副作用のない操作にしてください。

データセットのクエリ

SQL クエリには、Hub の Parquet エイリアスパスと npx parquetlens を使用します。

Parquet エイリアスの形式：

hf://datasets/<namespace>/<repo>@~parquet/<config>/<split>/<shard>.parquet

Dataset Viewer の /parquet から <config>、<split>、<shard> を特定します。

curl -s "https://datasets-server.huggingface.co/parquet?dataset=cfahlgren1/hub-stats" \
  | jq -r '.parquet_files[] | "hf://datasets/\(.dataset)@~parquet/\(.config)/\(.split)/\(.filename)"'

SQL クエリを実行します。

npx -y -p parquetlens -p @parquetlens/sql parquetlens \
  "hf://datasets/<namespace>/<repo>@~parquet/<config>/<split>/<shard>.parquet" \
  --sql "SELECT * FROM data LIMIT 20"

SQL エクスポート

• CSV：--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.csv' (FORMAT CSV, HEADER, DELIMITER ',')"
• JSON：--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.json' (FORMAT JSON)"
• Parquet：--sql "COPY (SELECT * FROM data LIMIT 1000) TO 'export.parquet' (FORMAT PARQUET)"

データセットの作成とアップロード

依存関係の制約に応じて、以下のいずれかの手順を使用します。

ローカル依存関係なし（Hub UI）：

• ブラウザーでデータセットリポジトリを作成します：https://huggingface.co/new-dataset
• リポジトリの「Files and versions」ページで Parquet ファイルをアップロードします。
• Dataset Viewer にシャードが表示されることを確認します。

curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"

依存関係を抑えた CLI の手順（npx @huggingface/hub / hfjs）：

• 認証トークンを設定します。

export HF_TOKEN=<your_hf_token>

• Parquet フォルダーをデータセットリポジトリにアップロードします（存在しない場合は自動的に作成されます）。

npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data

• 作成時に非公開リポジトリとしてアップロードします。

npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data --private

アップロード後、/parquet を呼び出して、@~parquet でクエリするための <config>/<split>/<shard> の値を確認します。