---

source: "https://github.com/huggingface/skills/tree/main/skills/huggingface-datasets" name: hugging-face-dataset-viewer description: 通过 Dataset Viewer API 查询 Hugging Face 数据集，获取分片、行、搜索、过滤和 Parquet 链接。 risk: unknown

Hugging Face 数据集查看器

何时使用

当需要通过 Dataset Viewer API 对 Hugging Face 数据集进行只读探索时使用此技能。

使用此技能执行只读的 Dataset Viewer API 调用，用于数据集探索和数据提取。

核心工作流

1. 可选：使用 /is-valid 验证数据集可用性。
2. 使用 /splits 解析 config + split。
3. 使用 /first-rows 预览数据。
4. 使用 /rows 配合 offset 和 length（最大 100）进行分页。
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>。

数据集查看器 API

• 验证数据集：/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 中排序。
• 保持过滤和搜索为只读操作，无副作用。

查询数据集

使用 npx parquetlens 配合 Hub Parquet 别名路径进行 SQL 查询。

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
• 在仓库文件和版本页面上传 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 获取 <config>/<split>/<shard> 值，用于 @~parquet 查询。

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果所需输入、权限或上下文不明确，请停下来寻求澄清。