Explorar guías rápidas · Python

Tecnología: PythonCategoría: Lectura y escritura de datosNivel: IntermedioActualizado

Leer y escribir archivos CSV, Parquet y JSON

Lee y escribe archivos CSV, Parquet y JSON con pandas controlando el esquema, las fechas, los nulos, la compresión, la codificación y un comportamiento de archivos seguro en producción.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Leer un CSV con tipos y fechas explícitos
  5. 2. Leer solo las columnas necesarias de un CSV
  6. 3. Controlar el manejo de nulos en un CSV
  7. 4. Conservar las cadenas vacías cuando sea necesario
  8. 5. Leer un CSV con una codificación explícita
  9. 6. Leer un CSV grande por bloques
  10. 7. Escribir un CSV sin el índice del DataFrame
  11. 8. Escribir un CSV con codificación UTF-8
  12. 9. Escribir columnas seleccionadas de un CSV en un orden controlado
  13. 10. Dar formato a las marcas de tiempo al escribir un CSV
  14. 11. Leer un archivo Parquet
  15. 12. Leer columnas seleccionadas de un Parquet
  16. 13. Leer un Parquet particionado con filtros cuando se admita
  17. 14. Escribir un archivo Parquet
  18. 15. Escribir un Parquet comprimido
  19. 16. Escribir un conjunto de datos Parquet particionado
  20. 17. Leer una estructura JSON estándar (array u objeto)
  21. 18. Leer JSON Lines
  22. 19. Escribir registros JSON
  23. 20. Escribir JSON Lines
  24. 21. Controlar el formato de las marcas de tiempo en JSON
  25. 22. Leer JSON de una estructura anidada tipo API
  26. 23. Normalizar arrays anidados con metadatos
  27. 24. Inspeccionar el esquema justo después de la lectura
  28. 25. Validar las columnas clave después de la ingesta
  29. 26. Validar el número de filas después de una escritura de ida y vuelta
  30. 27. Escribir en una ruta temporal antes de reemplazar un archivo de producción
  31. 28. Evitar anexar a un CSV a ciegas
  32. 29. Agregar el encabezado solo al crear un CSV
  33. 30. Comparar la elección del formato de archivo según la carga de trabajo
  34. Qué significa el resultado
  35. Qué revisar
  36. Los ID pierden los ceros a la izquierda
  37. La columna de fecha sigue siendo texto
  38. Una ida y vuelta por CSV cambia los dtypes
  39. El archivo Parquet es mucho más pequeño que el CSV
  40. La lectura de Parquet sigue siendo lenta
  41. El JSON produce columnas o un número de filas inesperados
  42. El número de nulos cambia después de leer un CSV
  43. Notas de producción
  44. CSV no tiene un esquema real
  45. Parquet suele ser mejor para la analítica repetida
  46. Las dependencias de Parquet importan
  47. JSON no es tabular por naturaleza
  48. Las escrituras de archivos no son transacciones
  49. El almacenamiento de objetos se comporta distinto que un disco local
  50. Evita muchos archivos Parquet diminutos
  51. La compresión intercambia CPU por almacenamiento y E/S
  52. Errores comunes
  53. 1. Dejar que pandas infiera el tipo de los identificadores
  54. 2. Escribir el índice del DataFrame por accidente
  55. 3. Tratar CSV como si conservara el esquema
  56. 4. Pensar al estilo errors="ignore" ante archivos defectuosos
  57. 5. Suponer que en JSON cada objeto es una fila
  58. 6. Anexar a un CSV desde varios procesos
  59. 7. Particionar Parquet por columnas de alta cardinalidad
  60. 8. Escribir directamente sobre un archivo de producción
  61. 9. Suponer que el filtrado de predicados en origen de Parquet siempre se aplica
  62. Siguiente paso
  63. Para profundizar

Problema

Necesitas cargar o exportar datos con pandas y quieres un comportamiento predecible con CSV, Parquet y JSON.

Lo difícil no es llamar a read_csv() o to_parquet().

Los problemas en producción suelen venir de:

  • una inferencia de tipos incorrecta
  • diferencias en el análisis de fechas
  • ceros a la izquierda perdidos
  • problemas de codificación
  • inconsistencias en los valores nulos
  • archivos inesperadamente grandes
  • confusión entre JSON orientado a filas y JSON Lines
  • cambios de esquema
  • un comportamiento de sobrescritura inseguro
  • archivos CSV que parecen correctos pero cambian de significado al volver a abrirlos

El objetivo es elegir el formato adecuado y hacer explícito el comportamiento de ingesta y de escritura.

Respuesta rápida

Usa CSV cuando lo más importante sea la interoperabilidad:

import pandas as pd

df = pd.read_csv(
    "orders.csv",
    dtype={"customer_id": "string"},
    parse_dates=["order_time"],
)

Usa Parquet cuando quieras un almacenamiento analítico tipado y columnar:

df = pd.read_parquet(
    "orders.parquet",
    columns=["order_id", "customer_id", "amount", "order_time"],
)

Escribe en Parquet para una reutilización analítica eficiente:

df.to_parquet(
    "orders.parquet",
    index=False,
    compression="snappy",
)

Usa JSON Lines para registros de tipo streaming o eventos:

df.to_json(
    "events.jsonl",
    orient="records",
    lines=True,
    date_format="iso",
)

Elige el formato según el próximo consumidor, no por costumbre.

Código / comandos

1. Leer un CSV con tipos y fechas explícitos

import pandas as pd

df = pd.read_csv(
    "orders.csv",
    dtype={
        "order_id": "string",
        "customer_id": "string",
        "country": "string",
    },
    parse_dates=["order_time"],
)

Usa un dtype= explícito para los identificadores que no deben interpretarse como números.

Así evitas que valores como:

000123

se conviertan en:

123

2. Leer solo las columnas necesarias de un CSV

df = pd.read_csv(
    "orders.csv",
    usecols=[
        "order_id",
        "customer_id",
        "amount",
        "order_time",
    ],
    parse_dates=["order_time"],
)

Esto reduce:

  • el uso de memoria
  • el trabajo de análisis
  • la dependencia accidental de columnas irrelevantes

Usa usecols= cuando el origen tenga más columnas de las que necesita la carga de trabajo.


3. Controlar el manejo de nulos en un CSV

De forma predeterminada, pandas reconoce varios valores habituales equivalentes a nulos.

Puedes agregar valores propios del origen:

df = pd.read_csv(
    "orders.csv",
    na_values=[
        "",
        "NULL",
        "N/A",
        "-9999",
    ],
)

Clasifica valores del origen como faltantes solo cuando conozcas su significado.

Si un "NULL" literal es un valor de negocio válido, no lo conviertas automáticamente.


4. Conservar las cadenas vacías cuando sea necesario

Si las cadenas vacías deben seguir siendo distintas de los valores faltantes:

df = pd.read_csv(
    "orders.csv",
    keep_default_na=False,
)

Esto cambia el comportamiento predeterminado de detección de nulos.

Úsalo solo cuando la semántica del origen exija esa distinción.


5. Leer un CSV con una codificación explícita

df = pd.read_csv(
    "customers.csv",
    encoding="utf-8",
)

Si el origen usa otra codificación conocida:

df = pd.read_csv(
    "legacy_customers.csv",
    encoding="cp1252",
)

No adivines codificaciones en silencio en un pipeline de producción.


6. Leer un CSV grande por bloques

for chunk in pd.read_csv(
    "large_orders.csv",
    chunksize=100_000,
):
    process(chunk)

Usa la lectura por bloques cuando el CSV completo no quepa cómodamente en memoria.

Recuerda que el procesamiento bloque a bloque puede cambiar el diseño del algoritmo.

Por ejemplo, una deduplicación global o una clasificación global necesitan mantener estado entre bloques.


7. Escribir un CSV sin el índice del DataFrame

df.to_csv(
    "orders.csv",
    index=False,
)

Así evitas crear sin querer una columna como:

Unnamed: 0

cuando el archivo se vuelva a leer más adelante.


8. Escribir un CSV con codificación UTF-8

df.to_csv(
    "orders.csv",
    index=False,
    encoding="utf-8",
)

Para flujos de trabajo orientados a Excel que necesitan un BOM UTF-8:

df.to_csv(
    "orders.csv",
    index=False,
    encoding="utf-8-sig",
)

Usa utf-8-sig solo cuando la herramienta posterior se beneficie de ello.


9. Escribir columnas seleccionadas de un CSV en un orden controlado

df.to_csv(
    "orders.csv",
    columns=[
        "order_id",
        "customer_id",
        "amount",
        "order_time",
    ],
    index=False,
)

Así el esquema de exportación es deliberado.


10. Dar formato a las marcas de tiempo al escribir un CSV

df.to_csv(
    "orders.csv",
    index=False,
    date_format="%Y-%m-%dT%H:%M:%S",
)

Ten cuidado con las marcas de tiempo con zona horaria.

Una cadena formateada puede perder la información de zona horaria si el formato no la incluye.

Si el consumidor necesita los desplazamientos de zona horaria, prefiere una representación ISO que los conserve.


11. Leer un archivo Parquet

df = pd.read_parquet(
    "orders.parquet",
)

Parquet conserva la información del esquema mejor que CSV.

Entre los tipos que suelen conservarse están:

  • enteros
  • valores de punto flotante
  • booleanos
  • cadenas
  • marcas de tiempo

El comportamiento exacto depende del motor de Parquet y del esquema subyacente.


12. Leer columnas seleccionadas de un Parquet

df = pd.read_parquet(
    "orders.parquet",
    columns=[
        "order_id",
        "customer_id",
        "amount",
        "order_time",
    ],
)

Es una de las principales ventajas de Parquet.

La poda de columnas puede reducir mucho la E/S cuando solo necesitas una parte de un conjunto de datos con muchas columnas.


13. Leer un Parquet particionado con filtros cuando se admita

df = pd.read_parquet(
    "orders_dataset/",
    filters=[
        ("country", "==", "US"),
        ("year", "==", 2026),
    ],
)

El filtrado en origen (filter pushdown) depende de:

  • la organización del almacenamiento
  • los metadatos de Parquet
  • la compatibilidad del motor
  • la expresión de filtro

No supongas que todos los filtros evitan leer todos los archivos.


14. Escribir un archivo Parquet

df.to_parquet(
    "orders.parquet",
    index=False,
)

Para datos analíticos que se van a reutilizar, Parquet suele ser una mejor opción predeterminada que CSV.


15. Escribir un Parquet comprimido

df.to_parquet(
    "orders.parquet",
    index=False,
    compression="snappy",
)

Las demás opciones de compresión admitidas dependen del motor de Parquet instalado.

Entre las opciones habituales están:

  • snappy
  • gzip
  • brotli
  • zstd

Elige según la compatibilidad, la tasa de compresión y el costo de CPU.

No supongas que la compresión más fuerte es la mejor para todas las cargas de trabajo.


16. Escribir un conjunto de datos Parquet particionado

df.to_parquet(
    "orders_dataset/",
    index=False,
    partition_cols=[
        "year",
        "month",
    ],
)

Usa el particionamiento cuando los lectores posteriores filtren con frecuencia por esas columnas.

Evita columnas de partición con una cardinalidad extremadamente alta.

Entre los malos ejemplos de partición suelen estar:

  • el ID de cliente
  • el ID de transacción
  • la marca de tiempo exacta

Pueden crear demasiados archivos o directorios pequeños.


17. Leer una estructura JSON estándar (array u objeto)

df = pd.read_json(
    "records.json",
)

Úsalo solo cuando la estructura JSON coincida con lo que espera read_json().

Inspecciona un JSON que no conozcas antes de suponer que se traduce directamente en filas.


18. Leer JSON Lines

JSON Lines contiene un objeto JSON por línea.

df = pd.read_json(
    "events.jsonl",
    lines=True,
)

Este formato es habitual en:

  • registros de eventos
  • exportaciones en streaming
  • API
  • pipelines de datos de tipo anexado

19. Escribir registros JSON

df.to_json(
    "records.json",
    orient="records",
    date_format="iso",
)

Conceptualmente:

[
  {"order_id":"A1","amount":10.5},
  {"order_id":"A2","amount":20.0}
]

Usa orient="records" cuando los sistemas posteriores esperen una lista de objetos con forma de fila.


20. Escribir JSON Lines

df.to_json(
    "events.jsonl",
    orient="records",
    lines=True,
    date_format="iso",
)

Esto produce un registro por línea.

Suele ser más fácil de transmitir en streaming y de procesar por anexado que un único array JSON grande.


21. Controlar el formato de las marcas de tiempo en JSON

Prefiere marcas de tiempo ISO para intercambios legibles por personas:

df.to_json(
    "events.json",
    orient="records",
    date_format="iso",
)

Sin un control explícito, las decisiones de serialización JSON pueden diferir de lo que esperan los consumidores posteriores.

Verifica:

  • la representación de la zona horaria
  • la precisión
  • la semántica de solo fecha frente a marca de tiempo

22. Leer JSON de una estructura anidada tipo API

El JSON anidado a menudo necesita normalización.

Ejemplo:

payload = {
    "results": [
        {
            "id": 1,
            "customer": {
                "name": "Ana",
                "country": "US",
            },
        }
    ]
}

Normaliza:

df = pd.json_normalize(
    payload["results"]
)

Las columnas resultantes pueden incluir:

id
customer.name
customer.country

Usa json_normalize() cuando los objetos anidados formen parte de la estructura del registro.


23. Normalizar arrays anidados con metadatos

payload = {
    "orders": [
        {
            "order_id": "A1",
            "items": [
                {"sku": "X", "qty": 2},
                {"sku": "Y", "qty": 1},
            ],
        }
    ]
}

Normaliza las filas de artículos:

items = pd.json_normalize(
    payload["orders"],
    record_path="items",
    meta=["order_id"],
)

Entiende la granularidad resultante:

una fila por artículo

no:

una fila por pedido

La expansión de estructuras anidadas puede cambiar mucho el número de filas.


24. Inspeccionar el esquema justo después de la lectura

print(df.shape)
print(df.dtypes)
df.info()

Después, comprueba:

print(df.head())
print(df.isna().sum().sort_values(ascending=False).head(20))

Que un archivo se cargue sin errores no significa que se haya cargado correctamente.


25. Validar las columnas clave después de la ingesta

required = [
    "order_id",
    "customer_id",
]

missing_required = df[required].isna().sum()

print(missing_required)

Comprueba la unicidad cuando corresponda:

assert not df["order_id"].duplicated().any()

Exige unicidad solo cuando la granularidad de negocio indique que la clave debe ser única.


26. Validar el número de filas después de una escritura de ida y vuelta

Ejemplo:

df.to_parquet(
    "orders.parquet",
    index=False,
)

check = pd.read_parquet(
    "orders.parquet",
)

assert len(check) == len(df)

En pipelines críticos, valida también:

  • el número de claves
  • el número de nulos
  • los dtypes
  • los agregados importantes

El número de filas por sí solo no basta.


27. Escribir en una ruta temporal antes de reemplazar un archivo de producción

Evita en lo posible archivos finales escritos a medias.

Ejemplo de patrón local:

from pathlib import Path

target = Path("orders.parquet")
temp = Path("orders.parquet.tmp")

df.to_parquet(
    temp,
    index=False,
)

temp.replace(target)

En sistemas de archivos locales, reemplazar el archivo después de una escritura correcta es más seguro que escribir directamente sobre el archivo final.

La atomicidad y el comportamiento de sobrescritura son distintos en sistemas remotos y de almacenamiento de objetos.


28. Evitar anexar a un CSV a ciegas

Anexar datos:

df.to_csv(
    "orders.csv",
    mode="a",
    header=False,
    index=False,
)

puede ser válido, pero solo si:

  • el esquema es idéntico
  • el orden de las columnas es idéntico
  • la codificación coincide
  • no hay otro proceso escribiendo al mismo tiempo
  • las escrituras parciales son aceptables

Anexar a un CSV no aplica ningún control de esquema.

Úsalo con cuidado.


29. Agregar el encabezado solo al crear un CSV

from pathlib import Path

path = Path("orders.csv")

df.to_csv(
    path,
    mode="a",
    header=not path.exists(),
    index=False,
)

Esto evita filas de encabezado repetidas en flujos sencillos de anexado local.

Aun así, evita este patrón con procesos de escritura concurrentes en producción.


30. Comparar la elección del formato de archivo según la carga de trabajo

Usa este modelo mental:

Interoperabilidad entre personas y herramientas -> CSV
Almacenamiento analítico tipado                 -> Parquet
Intercambio de API/eventos/documentos           -> JSON / JSON Lines

No es absoluto, pero es un buen punto de partida.

Qué significa el resultado

Formato Fortaleza Riesgo principal
CSV Universal y legible por personas Sin esquema incorporado; la inferencia de tipos puede cambiar el significado
Parquet Tipado, columnar, comprimido y eficiente para analítica Menos legible por personas; importa la compatibilidad de motores y herramientas
JSON Intercambio jerárquico flexible Verboso; la estructura anidada puede complicar la carga tabular
JSON Lines Un registro por línea, apto para streaming Sigue siendo verboso; el esquema puede variar entre registros

Opciones importantes de pandas:

Opción Por qué importa
dtype= Evita una inferencia de tipos no deseada
parse_dates= Analiza las columnas de fecha conocidas durante la lectura
usecols= Lee solo las columnas necesarias
na_values= Agrega marcadores de valores faltantes propios del origen
keep_default_na= Controla el reconocimiento de nulos integrado en pandas
columns= Restringe las columnas que se leen o escriben en Parquet
filters= Puede habilitar el filtrado de predicados en origen (predicate pushdown) en Parquet
compression= Controla la compresión de la salida
orient= Define la forma del JSON
lines=True Lee o escribe JSON Lines

Qué revisar

Los ID pierden los ceros a la izquierda

Probablemente el origen se infirió como numérico.

Usa:

dtype={"customer_id": "string"}

La columna de fecha sigue siendo texto

Puede ser que:

  • no se haya analizado
  • los valores del origen sean inconsistentes
  • el formato sea inesperado

Inspecciona los fallos de análisis antes de reemplazar los datos originales.

Una ida y vuelta por CSV cambia los dtypes

Es normal, salvo que restaures el esquema de forma explícita.

CSV no almacena un esquema de pandas.

El archivo Parquet es mucho más pequeño que el CSV

Suele ser lo esperado, porque Parquet es comprimido y columnar.

No juzgues la corrección solo por el tamaño del archivo.

La lectura de Parquet sigue siendo lenta

Revisa:

  • el número de archivos
  • el problema de los archivos pequeños
  • las columnas seleccionadas
  • el filtrado en origen
  • la latencia del almacenamiento
  • el códec de compresión
  • la organización de las particiones

El JSON produce columnas o un número de filas inesperados

Es posible que el origen esté anidado.

Inspecciona la jerarquía del JSON y define la granularidad de salida deseada antes de normalizar.

El número de nulos cambia después de leer un CSV

Revisa:

  • na_values
  • keep_default_na
  • las cadenas vacías
  • valores literales como "NA"

La interpretación de los nulos en CSV es configurable y puede cambiar el significado de negocio.

Notas de producción

CSV no tiene un esquema real

Un archivo CSV no distingue por sí mismo:

00123

de:

123

ni:

2026-10-04

de una simple cadena.

Guarda el esquema por separado o especifícalo en el momento de la lectura.

Parquet suele ser mejor para la analítica repetida

Parquet admite:

  • columnas tipadas
  • compresión
  • poda de columnas
  • filtrado de predicados en origen en los lectores compatibles
  • lecturas completas eficientes

Suele ser un formato analítico interno más sólido que CSV.

Las dependencias de Parquet importan

pandas depende de un motor de Parquet como:

  • pyarrow
  • fastparquet

Las funciones disponibles y la compatibilidad pueden variar.

En las cargas de trabajo modernas de pandas, pyarrow es de uso habitual.

JSON no es tabular por naturaleza

Los objetos y arrays anidados requieren una estrategia de aplanamiento explícita.

Antes de normalizar, define:

¿Qué debe representar una fila de salida?

Las escrituras de archivos no son transacciones

Escribir un archivo local o remoto no proporciona automáticamente la atomicidad de una base de datos.

Para salidas críticas:

  • escribe en una ubicación temporal
  • valida
  • promueve o renombra cuando se admita
  • evita procesos de escritura concurrentes
  • usa un formato de almacenamiento o una capa de tablas con semántica transaccional cuando sea necesario

El almacenamiento de objetos se comporta distinto que un disco local

Rutas como:

s3://...
abfss://...
gs://...

pueden admitirse mediante integraciones de sistemas de archivos, pero:

  • la semántica del renombrado es distinta
  • las credenciales importan
  • los reintentos importan
  • el comportamiento de consistencia depende del servicio
  • las escrituras concurrentes requieren un diseño deliberado

No supongas el comportamiento de un sistema de archivos local.

Evita muchos archivos Parquet diminutos

Los archivos pequeños generan sobrecarga de metadatos y de planificación en los sistemas analíticos.

Agrupa los datos en archivos de tamaño adecuado para el motor posterior en lugar de escribir un archivo por fila o por evento.

La compresión intercambia CPU por almacenamiento y E/S

El mejor códec depende de:

  • la frecuencia de lectura
  • la frecuencia de escritura
  • el costo de almacenamiento
  • el presupuesto de CPU
  • la compatibilidad posterior

Mide con tu carga de trabajo.

Errores comunes

1. Dejar que pandas infiera el tipo de los identificadores

Los ID suelen ser cadenas aunque solo contengan dígitos.

Usa dtypes explícitos.

2. Escribir el índice del DataFrame por accidente

Esto suele producir columnas no deseadas cuando el archivo se vuelve a cargar.

Usa:

index=False

salvo que el índice forme parte intencionalmente del contrato de datos.

3. Tratar CSV como si conservara el esquema

No lo hace.

Define los tipos al leer.

4. Pensar al estilo errors="ignore" ante archivos defectuosos

Una conversión silenciosa o un análisis permisivo pueden ocultar problemas de calidad de datos.

Inspecciona de forma deliberada los registros rechazados o mal formados.

5. Suponer que en JSON cada objeto es una fila

Los arrays anidados pueden multiplicar los registros.

Define la granularidad de destino antes de normalizar.

6. Anexar a un CSV desde varios procesos

Los anexados concurrentes pueden corromper o intercalar la salida.

Usa un proceso de escritura coordinado o un sistema de almacenamiento diseñado para la concurrencia.

7. Particionar Parquet por columnas de alta cardinalidad

Esto crea demasiadas particiones o archivos pequeños.

Particiona por campos que favorezcan los patrones de poda habituales y tengan una cardinalidad manejable.

8. Escribir directamente sobre un archivo de producción

Una escritura fallida puede dejar una salida incompleta.

Usa un patrón de escritura preparada y posterior promoción cuando el sistema de archivos o el modelo de almacenamiento lo admitan.

9. Suponer que el filtrado de predicados en origen de Parquet siempre se aplica

La compatibilidad del filtrado depende de la organización, los metadatos, el motor y la expresión.

Verifica el comportamiento en las cargas de trabajo importantes.

Siguiente paso

Usa el comportamiento de los archivos para elegir la siguiente acción.

  • Los ID cambiaron de tipo o perdieron el formato → define dtype= de forma explícita.
  • Las fechas se analizaron mal → analízalas con reglas explícitas e inspecciona los fallos.
  • El CSV es demasiado grande o lento para la analítica repetida → pasa a Parquet.
  • La lectura de Parquet lee demasiados datos → selecciona columnas, revisa los filtros e inspecciona el particionamiento.
  • El JSON está anidado → define la granularidad de filas de destino y usa json_normalize().
  • El número de nulos cambió de forma inesperada → revisa las opciones de análisis de nulos del CSV.
  • La salida la consume otro equipo u otro sistema → define explícitamente el contrato de esquema y formato.
  • Las escrituras deben ser atómicas o concurrentes → usa escrituras preparadas o una capa de almacenamiento transaccional en lugar de sobrescribir un archivo sin más.
  • El conjunto de datos ya no cabe cómodamente en memoria → lleva la lectura, el filtrado y la transformación a un motor de ejecución más potente.

← Todas las guías rápidas