Parquet Format Guide

Specification

Apache Parquet es un formato de archivo de almacenamiento columnar diseñado para el almacenamiento y recuperación eficiente de datos en frameworks de procesamiento de big data. Desarrollado originalmente en Twitter y Cloudera y liberado como código abierto a través de la Apache Software Foundation en 2013, Parquet almacena datos por columna en lugar de por fila, permitiendo ratios de compresión dramáticamente mejores y consultas analíticas más rápidas comparado con formatos orientados a filas como CSV o JSONL. Se ha convertido en el formato estándar para almacenamiento de datasets a gran escala en Hugging Face Hub y en data lakes empresariales.

Los archivos Parquet se organizan en grupos de filas, cada uno conteniendo chunks de columna que almacenan datos para una sola columna. Cada chunk de columna se divide además en páginas — la unidad más pequeña de almacenamiento que puede comprimirse y codificarse individualmente. Esta estructura jerárquica permite lecturas parciales altamente eficientes: cuando una consulta necesita solo unas pocas columnas de un dataset con cientos de columnas, Parquet lee solo los chunks de columna relevantes, omitiendo todos los datos irrelevantes. Las estadísticas a nivel de columna (mín, máx, conteo de nulos) almacenadas en los metadatos permiten pushdown de predicados, donde grupos de filas completos pueden omitirse si sus estadísticas indican que no pueden contener filas coincidentes.

Parquet soporta múltiples codecs de compresión incluyendo Snappy (rápido, compresión moderada), Zstandard (excelente ratio de compresión con buena velocidad), Gzip (amplia compatibilidad), LZ4 (menor latencia) y Brotli (mayor compresión). Soporta tipos de datos complejos anidados incluyendo structs, listas y mapas, usando el esquema de codificación Dremel que maneja eficientemente campos repetidos y opcionales. El esquema autodescriptivo del formato, almacenado en el footer del archivo, asegura que los lectores puedan interpretar los datos sin definiciones de esquema externas.

When to Use Parquet

Parquet es el formato óptimo para almacenar grandes datasets de entrenamiento (cientos de megabytes a terabytes) que se benefician de la compresión y el acceso columnar eficiente. En Hugging Face Hub, Parquet es el formato predeterminado para la biblioteca datasets, habilitando funciones como streaming de datasets (carga de datos al vuelo sin descargar archivos completos) y filtrado del lado del servidor. Si estás publicando datasets para uso comunitario o trabajando con datasets que exceden la RAM disponible, Parquet debería ser tu formato de almacenamiento.

Elige Parquet sobre JSONL cuando tu dataset sea grande y necesites almacenamiento eficiente, acceso rápido a nivel de columna, o integración con herramientas de big data como Apache Spark, DuckDB, Polars o BigQuery. Un dataset JSONL que ocupa 10 GB en disco podría comprimirse a 2-3 GB en Parquet mientras también proporciona acceso de lectura más rápido para operaciones comunes. Elige Parquet sobre CSV para cualquier dataset con tipos complejos, texto Unicode, o más de unos pocos cientos de megabytes de datos.

Parquet es menos adecuado cuando necesitas streaming línea por línea hacia frameworks de entrenamiento que esperan entrada JSONL (convierte Parquet a JSONL para el paso final de entrenamiento), cuando necesitas inspeccionar o editar registros individuales manualmente (Parquet es binario y no legible por humanos), o cuando tu dataset es muy pequeño y la sobrecarga del formato Parquet excede los beneficios de la compresión.

Schema / Structure

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)       │
└──────────────────────────────────────┘

Example Data

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"])