Hugging Face 的标志

Dataset viewer 文档

列出 Parquet 文件

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

列出 Parquet 文件

数据集可以以任何格式（CSV、JSONL、图像目录等）发布到 Hub，并且可以使用 🤗 Datasets 库轻松访问它们。为了获得更高效的体验（尤其是在处理大型数据集时），dataset viewer 会自动将每个数据集转换为 Parquet 格式。

什么是 Parquet？

Parquet 是一种列式存储格式，针对查询和处理大型数据集进行了优化。Parquet 是大数据处理和分析的热门选择，并广泛用于数据处理和机器学习。

在 Parquet 中，数据被分成称为“行组”的块，并且在每个行组中，数据以列而不是行的形式存储。每个行组列都使用最佳压缩算法根据数据单独压缩，并包含有关其包含数据的元数据和统计信息（最小值/最大值、NULL 值的数量）。

这种结构允许高效的数据读取和查询

  • 仅从磁盘读取必要的列（投影下推）；无需读取整个文件。这减少了使用 Parquet 数据的内存需求。
  • 如果其元数据中存储的统计信息与感兴趣的数据不匹配，则跳过整个行组（自动过滤）
  • 数据被压缩，这减少了需要存储和传输的数据量。

一个 Parquet 文件包含一个表。如果一个数据集有多个表（例如，多个拆分或子集），则每个表都存储在一个单独的 Parquet 文件中。

转换为 Parquet

Parquet 文件发布到 Hub 上的特定 refs/convert/parquet 分支（例如，像 fancyzhx/amazon_polarity branch 分支这样），该分支与 main 分支并行。

为了使 dataset viewer 生成数据集的 Parquet 版本，数据集必须是公开的，或者由 PRO 用户 或 Enterprise Hub 组织拥有。

使用 dataset viewer API

本指南向您展示如何使用 dataset viewer 的 /parquet 端点来检索数据集的已转换为 Parquet 的文件列表。您也可以随意使用 Postman、RapidAPI 或 ReDoc 尝试一下。

/parquet 端点接受数据集名称作为其查询参数

Python
JavaScript
cURL
import requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
API_URL = "https://datasets-server.huggingface.co/parquet?dataset=ibm/duorc"
def query():
    response = requests.get(API_URL, headers=headers)
    return response.json()
data = query()

端点响应是一个 JSON，其中包含 Parquet 格式的数据集文件列表。例如，ibm/duorc 数据集有六个 Parquet 文件，这对应于其两个子集 ParaphraseRC 和 SelfRC 的 test、train 和 validation 拆分（有关拆分和子集的更多详细信息，请参阅列出拆分和子集指南）。

端点还提供了每个文件的文件名和大小

{
   "parquet_files":[
      {
         "dataset":"ibm/duorc",
         "config":"ParaphraseRC",
         "split":"test",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/ParaphraseRC/test/0000.parquet",
         "filename":"0000.parquet",
         "size":6136591
      },
      {
         "dataset":"ibm/duorc",
         "config":"ParaphraseRC",
         "split":"train",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/ParaphraseRC/train/0000.parquet",
         "filename":"0000.parquet",
         "size":26005668
      },
      {
         "dataset":"ibm/duorc",
         "config":"ParaphraseRC",
         "split":"validation",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/ParaphraseRC/validation/0000.parquet",
         "filename":"0000.parquet",
         "size":5566868
      },
      {
         "dataset":"ibm/duorc",
         "config":"SelfRC",
         "split":"test",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/SelfRC/test/0000.parquet",
         "filename":"0000.parquet",
         "size":3035736
      },
      {
         "dataset":"ibm/duorc",
         "config":"SelfRC",
         "split":"train",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/SelfRC/train/0000.parquet",
         "filename":"0000.parquet",
         "size":14851720
      },
      {
         "dataset":"ibm/duorc",
         "config":"SelfRC",
         "split":"validation",
         "url":"https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/SelfRC/validation/0000.parquet",
         "filename":"0000.parquet",
         "size":3114390
      }
   ],
   "pending":[
      
   ],
   "failed":[
      
   ],
   "partial":false
}

分片 Parquet 文件

大型数据集被分区为约 500MB 大小的 Parquet 文件（分片）。文件名包含数据集的名称、拆分、分片索引和分片总数 (dataset-name-train-0000-of-0004.parquet)。对于给定的拆分，列表中的元素按其分片索引升序排序。例如，fancyzhx/amazon_polarity 数据集的 train 拆分被分区为 4 个分片

{
   "parquet_files":[
      {
         "dataset":"fancyzhx/amazon_polarity",
         "config":"amazon_polarity",
         "split":"test",
         "url":"https://huggingface.co/datasets/fancyzhx/amazon_polarity/resolve/refs%2Fconvert%2Fparquet/amazon_polarity/test/0000.parquet",
         "filename":"0000.parquet",
         "size":117422360
      },
      {
         "dataset":"fancyzhx/amazon_polarity",
         "config":"amazon_polarity",
         "split":"train",
         "url":"https://huggingface.co/datasets/fancyzhx/amazon_polarity/resolve/refs%2Fconvert%2Fparquet/amazon_polarity/train/0000.parquet",
         "filename":"0000.parquet",
         "size":259761770
      },
      {
         "dataset":"fancyzhx/amazon_polarity",
         "config":"amazon_polarity",
         "split":"train",
         "url":"https://huggingface.co/datasets/fancyzhx/amazon_polarity/resolve/refs%2Fconvert%2Fparquet/amazon_polarity/train/0001.parquet",
         "filename":"0001.parquet",
         "size":258363554
      },
      {
         "dataset":"fancyzhx/amazon_polarity",
         "config":"amazon_polarity",
         "split":"train",
         "url":"https://huggingface.co/datasets/fancyzhx/amazon_polarity/resolve/refs%2Fconvert%2Fparquet/amazon_polarity/train/0002.parquet",
         "filename":"0002.parquet",
         "size":255471883
      },
      {
         "dataset":"fancyzhx/amazon_polarity",
         "config":"amazon_polarity",
         "split":"train",
         "url":"https://huggingface.co/datasets/fancyzhx/amazon_polarity/resolve/refs%2Fconvert%2Fparquet/amazon_polarity/train/0003.parquet",
         "filename":"0003.parquet",
         "size":254410930
      }
   ],
   "pending":[
      
   ],
   "failed":[
      
   ],
   "partial":false
}

要读取和查询 Parquet 文件，请查看从 dataset viewer API 查询数据集指南。

部分转换的数据集

在两种情况下，Parquet 版本可能是部分的

  • 如果数据集已经是 Parquet 格式，但它包含的行组大于建议的大小（100-300MB 未压缩）。此大小更适合内存使用，因为在大多数数据库中，Parquet 是按行组流式传输的。
  • 如果数据集还不是 Parquet 格式，或者如果它大于 5GB。

在这种情况下，Parquet 文件将生成最大 5GB，并放置在以“partial”为前缀的拆分目录中，例如“partial-train”而不是“train”。

您可以直接在 Hugging Face 上使用 Parquet 元数据侧边栏检查行组大小，例如这里

clic-parquet-metadata-sidebar

parquet-metadata-sidebar-total-byte-size

Parquet 原生数据集

当数据集已经是 Parquet 格式时，数据不会被转换，并且 refs/convert/parquet 中的文件是指向原始文件的链接。此规则有一个例外，以确保 dataset viewer API 保持快速：如果原始 Parquet 文件的行组大小太大，则会生成新的 Parquet 文件。

使用 Hugging Face Hub API

为了方便起见，您可以直接使用 Hugging Face Hub /api/parquet 端点，该端点返回 Parquet URL 列表

Python
JavaScript
cURL
import requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
API_URL = "https://huggingface.co/api/datasets/ibm/duorc/parquet"
def query():
    response = requests.get(API_URL, headers=headers)
    return response.json()
urls = query()

端点响应是一个 JSON，其中包含每个拆分和子集的 Parquet 格式的数据集文件 URL 列表。例如，ibm/duorc 数据集为 “ParaphraseRC” 子集的 train 拆分提供了一个 Parquet 文件（有关拆分和子集的更多详细信息，请参阅列出拆分和子集指南）。

{
   "ParaphraseRC":{
      "test":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/test/0.parquet"
      ],
      "train":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/train/0.parquet"
      ],
      "validation":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/validation/0.parquet"
      ]
   },
   "SelfRC":{
      "test":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/SelfRC/test/0.parquet"
      ],
      "train":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/SelfRC/train/0.parquet"
      ],
      "validation":[
         "https://huggingface.co/api/datasets/ibm/duorc/parquet/SelfRC/validation/0.parquet"
      ]
   }
}

可选地，您可以指定要返回的子集名称以及拆分

Python
JavaScript
cURL
import requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
API_URL = "https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/train"
def query():
    response = requests.get(API_URL, headers=headers)
    return response.json()
urls = query()
[
  "https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/train/0.parquet"
]

还可以使用其分片索引访问每个 parquet 文件：例如，https://huggingface.co/api/datasets/ibm/duorc/parquet/ParaphraseRC/train/0.parquet 重定向到 https://huggingface.co/datasets/ibm/duorc/resolve/refs%2Fconvert%2Fparquet/ParaphraseRC/train/0000.parquet。

< > 在 GitHub 上更新

←过滤数据集中的行 获取行数和字节大小→