Parquet Format Guide

用于大规模训练数据集的列式存储格式

Training Data

Specification

Apache Parquet 是一种列式存储文件格式，专为大数据处理框架中高效的数据存储和检索而设计。该格式最初由 Twitter 和 Cloudera 开发，于 2013 年通过 Apache 软件基金会开源。Parquet 按列而非按行存储数据，与 CSV 或 JSONL 等行式格式相比，可实现显著更高的压缩率和更快的分析查询速度。它已成为 Hugging Face Hub 和企业数据湖中大规模数据集存储的标准格式。

Parquet 文件组织为行组（row group），每个行组包含列块（column chunk），每个列块存储单列的数据。每个列块进一步划分为页（page）——可单独压缩和编码的最小存储单元。这种层次结构实现了高效的部分读取：当查询只需要数百列数据集中的几列时，Parquet 只读取相关的列块，跳过所有无关数据。存储在元数据中的列级统计信息（最小值、最大值、空值计数）支持谓词下推，即当统计信息表明某个行组不可能包含匹配行时，可以直接跳过整个行组。

Parquet 支持多种压缩编解码器，包括 Snappy（快速、中等压缩率）、Zstandard（出色的压缩率和良好的速度）、Gzip（广泛兼容）、LZ4（最低延迟）和 Brotli（最高压缩率）。它支持复杂的嵌套数据类型，包括结构体、列表和映射，使用 Dremel 编码方案高效处理重复和可选字段。格式的自描述模式存储在文件尾部，确保读取器无需外部模式定义即可解释数据。

When to Use Parquet

Parquet 是存储大型训练数据集（数百兆字节到数 TB）的最佳格式，这些数据集可以从压缩和高效的列式访问中受益。在 Hugging Face Hub 上，Parquet 是 datasets 库的默认格式，支持数据集流式加载（无需下载完整文件即可即时加载数据）和服务端过滤等功能。如果你要发布数据集供社区使用，或处理超出可用内存的数据集，Parquet 应该是你的存储格式。

当你的数据集较大且需要高效存储、快速列级访问或与 Apache Spark、DuckDB、Polars、BigQuery 等大数据工具集成时，应选择 Parquet 而非 JSONL。一个占用 10 GB 磁盘空间的 JSONL 数据集在转为 Parquet 后可能压缩至 2-3 GB，同时常见操作的读取速度也更快。对于包含复杂类型、Unicode 文本或超过几百兆字节的数据集，应选择 Parquet 而非 CSV。

当你需要将数据逐行流式传入期望 JSONL 输入的训练框架时（可在最终训练步骤将 Parquet 转换为 JSONL），当你需要手动检查或编辑单条记录时（Parquet 是二进制格式，不具有人类可读性），或当数据集非常小以至于 Parquet 格式的开销超过压缩带来的收益时，Parquet 不太适用。

Schema / Structure

text

Parquet File Structure:
┌──────────────────────────────────────┐
│ Row Group 0                          │
│  ├── Column Chunk: "text"            │
│  │    ├── Page 0 (data + encoding)   │
│  │    └── Page 1 (data + encoding)   │
│  ├── Column Chunk: "label"           │
│  │    └── Page 0 (data + encoding)   │
│  └── Column Chunk: "metadata"        │
│       └── Page 0 (data + encoding)   │
├──────────────────────────────────────┤
│ Row Group 1                          │
│  ├── Column Chunk: "text"            │
│  ├── Column Chunk: "label"           │
│  └── Column Chunk: "metadata"        │
├──────────────────────────────────────┤
│ Footer                               │
│  ├── File Metadata                   │
│  │    ├── Schema (column names/types)│
│  │    ├── Row group metadata         │
│  │    └── Column statistics          │
│  └── Footer length (4 bytes)         │
│ Magic number: "PAR1" (4 bytes)       │
└──────────────────────────────────────┘

Apache Parquet 文件结构，展示行组、列块、页和尾部元数据

Example Data

python

import pyarrow as pa
import pyarrow.parquet as pq
import pandas as pd

# Create a training dataset and save as Parquet
data = {
    "text": [
        "The product quality exceeded my expectations",
        "Terrible customer service, waited 3 hours",
        "Average experience, nothing special",
    ],
    "label": ["positive", "negative", "neutral"],
    "confidence": [0.95, 0.88, 0.72],
}
table = pa.Table.from_pydict(data)
pq.write_table(table, "training_data.parquet", compression="zstd")

# Read specific columns (efficient columnar access)
df = pq.read_table("training_data.parquet", columns=["text", "label"]).to_pandas()
print(df.head())

# Stream large Parquet files with Hugging Face datasets
from datasets import load_dataset
ds = load_dataset("parquet", data_files="training_data.parquet", streaming=True)
for example in ds["train"]:
    print(example["text"], example["label"])

使用 PyArrow 和 Hugging Face 创建、读取和流式处理 Parquet 训练数据集

Ertas Support

Ertas Data Suite 支持 Parquet 的导入和导出，可高效处理大规模训练数据集。你可以从数据湖和数据仓库导入 Parquet 文件，进行 PII 脱敏和数据转换，并将处理后的数据集以 Parquet（节省存储空间）或 JSONL（兼容训练框架）格式导出。数据血缘系统在行组级别追踪转换操作，即使跨格式转换也能维护数据溯源。

Ship AI that runs on your users' devices.

Early bird pricing starts at $14.50/mo — locked in for life. Plans for builders and agencies.

View early bird pricing or join the waitlist →