Entrada

CSV a Parquet con pandas, Polars y DuckDB

¿Qué motor usas para pasar un CSV a Parquet? Con 5 millones de filas, Polars tarda medio segundo y DuckDB deja el fichero más pequeño. Código incluido.

CSV a Parquet con pandas, Polars y DuckDB

Tengo un CSV de 5 millones de filas y 381 MB. Leerlo entero con pandas funciona, pero cada consulta vuelve a analizar texto, inferir los tipos y recorrer columnas que no necesito. En Parquet, el mismo contenido ocupa 63–75 MB, se lee por columnas y lleva estadísticas para saltarse bloques que no hacen falta.

Este post es una guía práctica para convertir CSV a Parquet con pandas, Polars y DuckDB, con código que puedes copiar, un benchmark real y las trampas que aparecen cuando el esquema importa. Está inspirado en el artículo de Mark Needham sobre el mismo problema, pero con mediciones propias y versiones actuales.

Si aún no tienes claro qué es Parquet, empieza por Formato Parquet: 369 MB de CSV en 61 MB. Aquí voy directo a la conversión.

1. Por qué cambiar de CSV a Parquet

CSV es texto:

  • Cada fila se analiza entera, aunque solo quieras una columna.
  • Los tipos se infieren en cada lectura.
  • No hay compresión ni estadísticas.
  • Los nulos y las fechas se representan como texto.
  • Un SELECT sobre 10 columnas lee las 10.

Parquet es columnar:

  • Solo lee las columnas que pides.
  • Guarda tipos y metadatos.
  • Comprime por columna con Snappy, ZSTD, Gzip o Brotli.
  • Guarda mínimos, máximos y nulos por row group.
  • Permite predicados y lectura paralela.

El cambio no es «de CSV a un formato binario raro»: es pasar de un fichero de intercambio a un formato de análisis.

2. El artículo de Mark Needham

Mark Needham convirtió un CSV de 12 millones de filas y 270 MB (rankings de tenis) a Parquet con tres herramientas y un contenedor limitado a 100 MB de RAM:

  • pandas: funcionaba con 1 GB, pero el contenedor moría por OOM con 100 MB.
  • Polars: scan_csv + sink_parquet, unos 25 MB de Parquet.
  • DuckDB: COPY con memory_limit, unos 51 MB.

Su conclusión: pandas está bien si el fichero cabe en memoria; Polars y DuckDB aguantan ficheros más grandes. Este post actualiza la idea con un dataset distinto, versiones de 2026 y una comparación más detallada de esquema, compresión y row groups. DuckDB sirve además para consultar con SQL otros datos, como el historial de git.

Mark también grabó la conversión en vídeo para su canal, Learn Data with Mark. Lo tienes al final del post, junto a otro que explica qué cambia por dentro entre CSV y Parquet.

3. Benchmark: 5 millones de filas y 381 MB de CSV

El CSV sintético tiene:

DatoValor
Filas5.000.000
Columnas10
Tamaño381 MB
Fechas1.000 días
Usuarios500.000
Países10
Dispositivos3
Nulos en notes10 %

Columnas: event_date, user_id, session_id, country, device, page, revenue, quantity, is_active y notes.

El entorno:

  • 16 vCPU, 27 GB de RAM.
  • Python 3.12.13.
  • pandas 3.1.0, PyArrow 26.0.0, Polars 2.1.0, DuckDB 2.0.0.
  • Ficheros en /tmp (tmpfs), sin cuello de botella en el disco.
  • Mediana de 3 ejecuciones por motor, con la caché caliente.
  • Mismo compression='zstd' y row_group_size=100_000 en todos.
  • pandas con motor C; además pruebo pandas con motor PyArrow.
  • DuckDB con 4 hilos y memory_limit='2GB'.
  • PyArrow directo como cuarto control.

No es un benchmark universal: es una foto de esta máquina y este dataset. Sirve para comparar órdenes de magnitud y para ver qué API te resulta más cómoda.

4. pandas: la vía directa

El código mínimo, con la documentación de to_parquet a mano:

1
2
3
4
5
6
7
8
9
10
11
12
13
import pandas as pd

csv = "events.csv"
out = "events.parquet"

df = pd.read_csv(csv, parse_dates=["event_date"])
df.to_parquet(
    out,
    engine="pyarrow",
    compression="zstd",
    row_group_size=100_000,
    index=False,
)

Resultado en mi prueba:

  • 2,42 s de mediana.
  • 74,3 MB de Parquet.
  • 969 MB de RSS máximo.
  • event_date acaba como TIMESTAMP, no como DATE.

Ventajas: una línea, APIs conocidas, ecosistema enorme. Desventajas: carga todo en memoria y el esquema lo decide pandas.

5. Motor PyArrow en pandas: 1,61 s y más memoria

Si el CSV es grande pero cabe en RAM, pandas puede usar el motor PyArrow y tipos Arrow:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import pandas as pd

df = pd.read_csv(
    "events.csv",
    engine="pyarrow",
    dtype_backend="pyarrow",
    parse_dates=["event_date"],
)

df.to_parquet(
    "events.parquet",
    engine="pyarrow",
    compression="zstd",
    row_group_size=100_000,
    index=False,
)

Resultado:

  • 1,61 s de mediana.
  • 75,0 MB.
  • 1.142 MB de RSS.

Es más rápido que el motor C en esta prueba, pero consume más memoria. Y sigue escribiendo la fecha como timestamp. Úsalo si ya estás en pandas y quieres acelerar la lectura, no si vas justo de RAM.

6. Polars en streaming: scan_csv y sink_parquet

Polars separa «leer» de «materializar», como explica su guía de sources y sinks:

1
2
3
4
5
6
7
8
9
10
import polars as pl

(
    pl.scan_csv("events.csv", try_parse_dates=True)
      .sink_parquet(
          "events.parquet",
          compression="zstd",
          row_group_size=100_000,
      )
)

Resultado:

  • 0,49 s de mediana.
  • 65,6 MB.
  • 969 MB de RSS máximo.
  • event_date como DATE.

scan_csv no carga todo: construye un plan. sink_parquet ejecuta ese plan en streaming y escribe por lotes. La documentación de Polars lo describe como la forma de volcar resultados más grandes que la RAM.

En este dataset fue el más rápido. No siempre será así: con muchas columnas de texto, agregaciones o joins, el resultado cambia.

7. DuckDB: SQL + COPY

DuckDB convierte el CSV en una consulta SQL, con la sintaxis de COPY:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import duckdb

con = duckdb.connect()
con.execute("SET threads=4")
con.execute("SET memory_limit='2GB'")
con.execute("SET temp_directory='/tmp/duckdb-spill'")

con.execute("""
COPY (
    SELECT *
    FROM read_csv_auto('events.csv', HEADER=TRUE)
)
TO 'events.parquet'
(FORMAT PARQUET, CODEC 'ZSTD', ROW_GROUP_SIZE 100000);
""")

Resultado:

  • 1,09 s de mediana.
  • 63,4 MB: el más pequeño.
  • 921 MB de RSS.
  • event_date como DATE.

La sintaxis COPY permite leer el CSV en streaming, aplicar filtros o columnas calculadas y escribir el Parquet sin pasar por un DataFrame. Si ya piensas en SQL, es la opción más natural.

El memory_limit y el temp_directory importan: sin ellos, DuckDB puede intentar usar más memoria de la que le das y dejar ficheros incompletos en casos extremos.

8. PyArrow directo: control total del esquema

PyArrow es la capa que hay debajo de pandas y Parquet; su documentación de Parquet cubre compresión y encoding:

1
2
3
4
5
6
7
8
9
10
import pyarrow.csv as pv
import pyarrow.parquet as pq

table = pv.read_csv("events.csv")
pq.write_table(
    table,
    "events.parquet",
    compression="zstd",
    row_group_size=100_000,
)

Resultado:

  • 2,07 s.
  • 74,2 MB.
  • 1.133 MB de RSS.

No es la opción más rápida, pero da control total sobre el esquema, las opciones de lectura y los metadatos. Es la que usaría si necesito un tipo exacto o escribir un dataset con un schema fijo.

9. ¿Quién gana? Polars en tiempo y DuckDB en tamaño

Gráfico de barras con el tiempo de conversión: pandas 2,42 s, pandas con PyArrow 1,61 s, Polars 0,49 s, DuckDB 1,09 s y PyArrow 2,07 s

Mediana de 3 ejecuciones; mismo CSV, ZSTD y row group de 100.000.

Gráfico de barras con el tamaño del Parquet: pandas 74,3 MB, pandas con PyArrow 75,0 MB, Polars 65,6 MB, DuckDB 63,4 MB y PyArrow 74,2 MB

El CSV original pesa 381 MB; el Parquet, entre 63 y 75 MB.

Resumen:

MotorTiempoTamañoRSS máximoFecha
pandas (C)2,42 s74,3 MB969 MBTIMESTAMP
pandas + PyArrow1,61 s75,0 MB1.142 MBTIMESTAMP
Polars0,49 s65,6 MB969 MBDATE
DuckDB1,09 s63,4 MB921 MBDATE
PyArrow2,07 s74,2 MB1.133 MBDATE

Tres conclusiones:

  1. Polars es el más rápido en esta prueba, con diferencia.
  2. DuckDB genera el fichero más pequeño y el que mejor schema tiene por defecto.
  3. pandas no es lento, pero paga el coste de cargar todo y de un esquema menos preciso.

El RSS máximo incluye imports, páginas mapeadas y buffers del proceso; no es una medida pura de heap. Para comparar memoria real, usa cgroups o memory.max en un contenedor.

9.1 Lo que no mide este benchmark

Este benchmark mide una conversión completa en una máquina concreta. No mide:

  • Consultas posteriores: ahí Parquet es mucho más rápido que CSV, pero depende de filtros y row groups.
  • Ficheros con muchas columnas de texto o JSON anidado.
  • Lectura desde S3, NFS o un disco lento.
  • Concurrencia de varios procesos.
  • Compresión distinta de ZSTD.

La caché del sistema está caliente: el CSV se generó y se leyó varias veces antes. En frío, la primera ejecución sería más lenta para todos. La conclusión útil no es «Polars es 5 veces más rápido siempre», sino «Polars y DuckDB tienen una API de streaming que evita cargar todo y, en este caso, además son más rápidos».

Si quieres repetirlo, el benchmark de liiink-it y el de henrikalbihn usan métodos parecidos con datasets distintos.

10. Compresión: ZSTD frente a Snappy y Gzip

El CSV son 381 MB. Los Parquet con ZSTD quedan entre 63 y 75 MB: 5–6 veces menos.

Compresiones habituales:

CódecVelocidadTamañoCuándo
SnappyMuy rápidaMayorCompatibilidad y velocidad de escritura
ZSTDEquilibradaMenorRecomendado por defecto
GzipLentaSimilar o menorLegado, no lo elegiría hoy
BrotliLentaMuy competitivoCuando el tamaño importa más que la CPU

En pandas:

1
df.to_parquet(out, compression="zstd", compression_level=3)

En Polars:

1
sink_parquet(out, compression="zstd", compression_level=3)

En DuckDB:

1
COPY (...) TO 'out.parquet' (FORMAT PARQUET, CODEC 'ZSTD');

ZSTD es un buen equilibrio: comprime más que Snappy y descomprime rápido. Si necesitas que un lector antiguo abra el fichero, Snappy es la apuesta segura.

10.1 Prueba de códecs con DuckDB

Mismo CSV y mismo row_group_size, cambiando solo el códec:

CódecTiempoTamaño
Snappy0,83 s120,2 MB
ZSTD0,88 s63,3 MB
GZIP2,59 s69,7 MB

En este caso ZSTD comprime casi el doble que Snappy con un coste de tiempo mínimo. GZIP tarda tres veces más y ni siquiera gana en tamaño. Por eso ZSTD es mi opción por defecto.

11. TIMESTAMP no es DATE

Este es el detalle que más me sorprendió:

  • pandas con parse_dates escribe event_date como TIMESTAMP.
  • Polars, DuckDB y PyArrow la escriben como DATE.

No es un fallo: pandas representa fechas como datetime64[ns] y Parquet lo guarda como timestamp. Si tu consumidor espera DATE, el esquema no coincide.

Cómo evitarlo:

  • Convertir a fecha antes de escribir: df["event_date"] = df["event_date"].dt.date.
  • Usar un esquema PyArrow explícito con pa.date32().
  • O dejar que DuckDB lea el CSV y haga event_date::DATE en el SELECT.

En un pipeline de producción, define el esquema una vez y verifícalo con DESCRIBE o parquet_metadata. No dejes que cada motor invente el suyo.

12. Verificar el Parquet: filas, columnas y metadatos

No basta con que el fichero exista. Comprueba filas, columnas y una agregación:

1
2
3
4
5
6
7
8
9
10
import duckdb

con = duckdb.connect()
print(con.sql("SELECT count(*) FROM 'events.parquet'").fetchone())
print(con.sql("""
    SELECT country, count(*) AS n, round(avg(revenue), 2) AS avg_revenue
    FROM 'events.parquet'
    GROUP BY country
    ORDER BY n DESC
""").fetchdf())

También puedes mirar los metadatos:

1
2
3
4
5
6
import pyarrow.parquet as pq

pf = pq.ParquetFile("events.parquet")
print(pf.metadata.num_rows)
print(pf.metadata.num_row_groups)
print(pf.schema_arrow)

En mi caso: 5.000.000 filas, 50 row groups y 10 columnas. Si el número de filas no cuadra, el problema casi siempre es el CSV (comillas, saltos de línea, encoding) o una inferencia de tipos que ha partido una columna.

13. Row groups y particiones

Un row group es un bloque de filas que Parquet lee por separado. Afecta a memoria, paralelismo y poda de predicados.

  • 100.000 filas es un buen punto de partida para analítica.
  • DuckDB usa 122.880 por defecto.
  • La guía de Parquet recomienda grupos grandes (512 MB–1 GB) para escaneos secuenciales; para consultas selectivas, grupos más pequeños permiten saltar mejor.
  • Como regla: al menos tantos row groups como hilos de consulta.

Particionar es otra cosa: crear carpetas por country, year o event_date. Útil si casi siempre filtras por esa columna; peligroso si generas miles de ficheros pequeños.

En pandas:

1
df.to_parquet("events/", partition_cols=["country"])

En DuckDB:

1
2
3
COPY (SELECT * FROM 'events.parquet')
TO 'events/'
(FORMAT PARQUET, PARTITION_BY (country));

En Polars, sink_parquet acepta PartitionBy. No partitions por defecto: mide primero.

13.1 Un ejemplo de partición

Si casi todas tus consultas filtran por country, particionar por país puede tener sentido:

1
2
3
COPY (SELECT * FROM 'events.parquet')
TO 'events_by_country/'
(FORMAT PARQUET, PARTITION_BY (country), CODEC 'ZSTD');

Genera una carpeta por país (country=ES/, country=US/…) y ficheros dentro. DuckDB, Polars y Spark leen ese directorio como un dataset y pueden saltarse particiones enteras.

Pero no lo hagas por user_id con 500.000 valores: acabarías con 500.000 carpetas y sus metadatos que gestionar. Para alta cardinalidad, mejor ordenar por esa columna y usar row groups con estadísticas, o un bucket hash. La guía de tips de DuckDB explica el equilibrio entre row groups, estadísticas y pruning.

14. Memoria y ficheros más grandes que la RAM

Pandas necesita el CSV entero en memoria. Si no cabe:

  • Polars: scan_csv + sink_parquet.
  • DuckDB: COPY con memory_limit y temp_directory.
  • pandas por chunks: escribe varios Parquet y luego únelos o consulta el directorio como dataset.

Ejemplo de pandas por chunks:

1
2
3
4
import pandas as pd

for i, chunk in enumerate(pd.read_csv("events.csv", chunksize=1_000_000)):
    chunk.to_parquet(f"events/part-{i:03d}.parquet", compression="zstd", index=False)

Esto no convierte el CSV «en un solo fichero», pero deja un dataset particionado que DuckDB, Polars o Spark pueden leer. Es la vía cuando la memoria es el límite y no quieres cambiar de herramienta.

15. Cuándo usar cada motor

Diagrama de CSV a Parquet con pandas, Polars y DuckDB: el CSV se lee una vez y el Parquet se lee muchas

La misma conversión con tres motores. Cambia la API y el consumo, no los datos.

SituaciónElección
CSV pequeño o mediano, ya usas pandaspandas
Quieres la conversión más rápidaPolars
Quieres SQL, filtros o columnas calculadasDuckDB
Necesitas control exacto del esquemaPyArrow
Fichero más grande que la RAMPolars o DuckDB
Vas a leer con SparkParquet + clúster de Spark

Mi elección por defecto: DuckDB si hay SQL de por medio, Polars si solo quiero convertir rápido, pandas si estoy explorando y el fichero cabe.

15.1 Cómo lo haría en producción

Para un pipeline repetible:

  1. Deja el CSV en una carpeta raw/ con fecha o versión.
  2. Valida el esquema con una muestra y un contrato (event_date DATE, revenue DOUBLE, etc.).
  3. Convierte con DuckDB o Polars a un fichero temporal.
  4. Comprueba filas, columnas y una agregación contra el CSV.
  5. Renombra el temporal al nombre final solo si todo cuadra.
  6. Publica el Parquet con una tabla de metadatos: origen, fecha, versión de la biblioteca y row groups.
  7. Lee el resultado con otro motor para detectar incompatibilidades de esquema.

Ese «renombrar al final» evita que un fallo a mitad de escritura deje un Parquet corrupto con nombre definitivo. Y la comprobación con otro motor evita sorpresas como la fecha TIMESTAMP de pandas.

16. Lo que se rompe al convertir

Inferencia de tipos distinta en cada motor. Revisa DESCRIBE y fija el esquema si vas a compartir el fichero.

Fechas como timestamp. Si necesitas DATE, conviértelo explícitamente.

CSV con comillas o saltos de línea. Prueba quotechar, escapechar y lineterminator; si el fichero está mal, ningún motor lo arregla.

Encoding. UTF-8 por defecto; si ves caracteres raros, prueba encoding="latin-1" y revisa los datos.

Nulos. NA, NULL, cadena vacía y NaN no son lo mismo. Define na_values y comprueba el resultado.

Decimales. Para dinero, float64 puede perder precisión. Usa Decimal/decimal128 si el consumidor lo necesita.

Índice de pandas. index=False evita una columna extra; si no, el índice se escribe como columna.

Muchos ficheros pequeños. Particionar por una columna con 10.000 valores genera demasiados ficheros y metadatos. Piensa en el patrón de consulta.

Benchmarks sin método. Una sola ejecución, caché fría, disco lento o distinto número de hilos cambia el resultado. Mide tu caso.

17. Doce comprobaciones antes de migrar a Parquet

  • Define el esquema antes de convertir.
  • Comprueba filas y columnas al terminar.
  • Usa ZSTD salvo que necesites compatibilidad con Snappy.
  • Fija row_group_size según tus consultas.
  • No particiones sin medir el número de ficheros.
  • Comprueba fechas, nulos y decimales.
  • Lee el Parquet con otro motor para validar.
  • Mide tiempo, tamaño y memoria en tu hardware.
  • Guarda el script y la versión de las bibliotecas.
  • Si el CSV no cabe, usa streaming o chunks.
  • Documenta el esquema y el códec.
  • Prueba una consulta real, no solo count(*).

18. Enlaces y vídeos de interés

18.1 Artículos

18.2 Vídeos

Vídeo en inglés: Mark Needham hace la conversión del CSV de rankings de tenis con pandas, Polars y DuckDB, contenedor de 100 MB incluido. Es el vídeo del artículo que inspira este post.

Vídeo en inglés: qué cambia por dentro al pasar de CSV a Parquet — ventajas, inconvenientes y en qué casos cada formato sigue teniendo sentido.

Esta entrada está licenciada bajo CC BY 4.0 por el autor.