Parquet Format Guide

用於大規模訓練資料集的欄式儲存格式

Training Data

Specification

Apache Parquet 是一種欄式儲存檔案格式，專為大資料處理框架中的高效資料儲存和檢索而設計。最初由 Twitter 和 Cloudera 開發，並於 2013 年透過 Apache Software Foundation 開源，Parquet 按欄而非按行儲存資料，與 CSV 或 JSONL 等行導向格式相比，實現了顯著更好的壓縮比和更快的分析查詢。它已成為 Hugging Face Hub 和企業資料湖中大規模資料集儲存的標準格式。

Parquet 檔案組織為行群組（row groups），每個行群組包含儲存單一欄位資料的欄區塊（column chunks）。每個欄區塊進一步劃分為頁面（pages）——可以單獨壓縮和編碼的最小儲存單位。這種層次結構實現了高效的部分讀取：當查詢僅需要具有數百欄位資料集中的幾個欄位時，Parquet 僅讀取相關的欄區塊，跳過所有不相關的資料。儲存在中繼資料中的欄級統計資訊（最小值、最大值、空值計數）支援謂詞下推，當統計資訊表明行群組不可能包含匹配的行時，可以跳過整個行群組。

Parquet 支援多種壓縮編碼器，包括 Snappy（快速、中等壓縮）、Zstandard（優秀的壓縮比和良好的速度）、Gzip（廣泛相容）、LZ4（最低延遲）和 Brotli（最高壓縮）。它支援複雜的巢狀資料型別，包括結構體、列表和映射，使用 Dremel 編碼方案高效處理重複和可選欄位。該格式的自描述架構儲存在檔案頁腳中，確保讀取器可以在沒有外部架構定義的情況下解讀資料。

When to Use Parquet

Parquet 是儲存受益於壓縮和高效欄式存取的大型訓練資料集（數百 MB 到 TB）的最佳格式。在 Hugging Face Hub 上，Parquet 是 datasets 程式庫的預設格式，支援資料集串流（在不下載整個檔案的情況下即時載入資料）和伺服器端篩選等功能。如果您正在發布資料集供社群使用或處理超出可用 RAM 的資料集，Parquet 應該是您的儲存格式。

當您的資料集很大且需要高效儲存、快速欄級存取，或與 Apache Spark、DuckDB、Polars 或 BigQuery 等大資料工具整合時，選擇 Parquet 而非 JSONL。佔用 10 GB 磁碟空間的 JSONL 資料集可能在 Parquet 中壓縮到 2-3 GB，同時還提供更快的常見操作讀取存取。對於具有複雜型別、Unicode 文字或超過幾百 MB 資料的任何資料集，選擇 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 →