Explorar guías rápidas · Python
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
- Problema
- Respuesta rápida
- Código / comandos
- 1. Leer un CSV con tipos y fechas explícitos
- 2. Leer solo las columnas necesarias de un CSV
- 3. Controlar el manejo de nulos en un CSV
- 4. Conservar las cadenas vacías cuando sea necesario
- 5. Leer un CSV con una codificación explícita
- 6. Leer un CSV grande por bloques
- 7. Escribir un CSV sin el índice del DataFrame
- 8. Escribir un CSV con codificación UTF-8
- 9. Escribir columnas seleccionadas de un CSV en un orden controlado
- 10. Dar formato a las marcas de tiempo al escribir un CSV
- 11. Leer un archivo Parquet
- 12. Leer columnas seleccionadas de un Parquet
- 13. Leer un Parquet particionado con filtros cuando se admita
- 14. Escribir un archivo Parquet
- 15. Escribir un Parquet comprimido
- 16. Escribir un conjunto de datos Parquet particionado
- 17. Leer una estructura JSON estándar (array u objeto)
- 18. Leer JSON Lines
- 19. Escribir registros JSON
- 20. Escribir JSON Lines
- 21. Controlar el formato de las marcas de tiempo en JSON
- 22. Leer JSON de una estructura anidada tipo API
- 23. Normalizar arrays anidados con metadatos
- 24. Inspeccionar el esquema justo después de la lectura
- 25. Validar las columnas clave después de la ingesta
- 26. Validar el número de filas después de una escritura de ida y vuelta
- 27. Escribir en una ruta temporal antes de reemplazar un archivo de producción
- 28. Evitar anexar a un CSV a ciegas
- 29. Agregar el encabezado solo al crear un CSV
- 30. Comparar la elección del formato de archivo según la carga de trabajo
- Qué significa el resultado
- Qué revisar
- Los ID pierden los ceros a la izquierda
- La columna de fecha sigue siendo texto
- Una ida y vuelta por CSV cambia los dtypes
- El archivo Parquet es mucho más pequeño que el CSV
- La lectura de Parquet sigue siendo lenta
- El JSON produce columnas o un número de filas inesperados
- El número de nulos cambia después de leer un CSV
- Notas de producción
- CSV no tiene un esquema real
- Parquet suele ser mejor para la analítica repetida
- Las dependencias de Parquet importan
- JSON no es tabular por naturaleza
- Las escrituras de archivos no son transacciones
- El almacenamiento de objetos se comporta distinto que un disco local
- Evita muchos archivos Parquet diminutos
- La compresión intercambia CPU por almacenamiento y E/S
- Errores comunes
- 1. Dejar que pandas infiera el tipo de los identificadores
- 2. Escribir el índice del DataFrame por accidente
- 3. Tratar CSV como si conservara el esquema
- 4. Pensar al estilo errors="ignore" ante archivos defectuosos
- 5. Suponer que en JSON cada objeto es una fila
- 6. Anexar a un CSV desde varios procesos
- 7. Particionar Parquet por columnas de alta cardinalidad
- 8. Escribir directamente sobre un archivo de producción
- 9. Suponer que el filtrado de predicados en origen de Parquet siempre se aplica
- Siguiente paso
- 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:
snappygzipbrotlizstd
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_valueskeep_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:
pyarrowfastparquet
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.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.