数据集查看器文档
列出 Parquet 文件
并获得增强的文档体验
开始使用
列出 Parquet 文件
数据集可以以任何格式(CSV、JSONL、图像目录等)发布到 Hub,并且可以使用 🤗 Datasets 库轻松访问。为了获得更高效的体验(尤其是在处理大型数据集时),数据集查看器会自动将每个数据集转换为 Parquet 格式。
什么是 Parquet?
Parquet 是一种面向列的存储格式,经过优化,可用于查询和处理大型数据集。Parquet 是大数据处理和分析的流行选择,广泛用于数据处理和机器学习。
在 Parquet 中,数据被分成称为“行组”的块,在每个行组中,数据以列而不是行的形式存储。每个行组列根据数据使用最佳压缩算法单独压缩,并包含有关其所包含数据的元数据和统计信息(最小值/最大值、NULL 值数量)。
这种结构允许高效的数据读取和查询
- 只从磁盘读取必要的列(投影下推);无需读取整个文件。这减少了处理 Parquet 数据的内存需求。
- 如果行组中存储的统计信息与感兴趣的数据不匹配,则跳过整个行组(自动过滤)
- 数据经过压缩,减少了需要存储和传输的数据量。
一个 Parquet 文件包含一个表。如果数据集有多个表(例如,多个拆分或子集),每个表都存储在单独的 Parquet 文件中。
转换为 Parquet
Parquet 文件发布到 Hub 上的特定 refs/convert/parquet
分支(例如这个 fancyzhx/amazon_polarity
分支),与 main
分支并行。
为了让数据集查看器生成数据集的 Parquet 版本,数据集必须是公开的,或者由 PRO 用户 或 Enterprise Hub 组织拥有。
使用数据集查看器 API
本指南向您展示如何使用数据集查看器的 /parquet
端点来检索转换为 Parquet 的数据集文件列表。您也可以尝试使用 Postman、RapidAPI 或 ReDoc。
/parquet
端点接受数据集名称作为其查询参数
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 文件,请查看 从数据集查看器 API 查询数据集 指南。
部分转换的数据集
在两种情况下,Parquet 版本可能不完整:
- 如果数据集已经是 Parquet 格式,但它包含的行组大于建议的大小(未压缩时 100-300MB)。此大小更适合内存使用,因为 Parquet 在大多数数据库中都是按行组流式传输的。
- 如果数据集尚未采用 Parquet 格式,或者其大小大于 5GB。
在这种情况下,Parquet 文件将生成到 5GB,并放置在以“partial”为前缀的拆分目录中,例如“partial-train”而不是“train”。
您可以使用 Parquet 元数据侧边栏直接在 Hugging Face 上检查行组大小,例如此处
Parquet 原生数据集
当数据集已经是 Parquet 格式时,数据不会被转换,`refs/convert/parquet` 中的文件是原始文件的链接。此规则有一个例外,以确保数据集查看器 API 保持快速:如果原始 Parquet 文件的行组大小过大,则会生成新的 Parquet 文件。
使用 Hugging Face Hub API
为了方便起见,您可以直接使用 Hugging Face Hub ` /api/parquet` 端点,该端点返回 Parquet URL 列表
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` 数据集有一个 Parquet 文件用于“ParaphraseRC”子集的训练拆分(有关拆分和子集的更多详细信息,请参阅列出拆分和子集指南)。
{
"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"
]
}
}
您可以选择指定要返回的子集名称以及拆分
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 上更新