Carga y almacenamiento de datos

Un archivo CSV es texto plano organizado en registros y campos. Las comas suelen separar los campos y el primer registro suele proporcionar los nombres de las columnas. El archivo contiene caracteres, no un esquema de pandas, por lo que leerlo también implica decidir qué representan esos caracteres.

Carga e inspecciona un archivo pequeño

Supón que un archivo contiene:

order_id,date,region,units,price
1001,2026-03-02,North,3,4.50
1002,2026-03-02,South,1,12.00
1003,2026-03-03,North,2,7.25

Léelo e inspecciona el resultado:

import pandas as pd

df = pd.read_csv("sales.csv")
print(df.head())
print(df.shape)
print(df.dtypes)
df.info()

La forma es (3, 5): tres filas de datos y cinco columnas. pandas infiere int64 para order_id y units, y float64 para price. La columna date sigue conteniendo texto. En pandas 3, las columnas de texto inferidas suelen mostrar str; las versiones anteriores de pandas suelen mostrar object.

Cada inspección responde a una pregunta distinta. head() muestra si los campos están alineados con sus etiquetas. shape revela filas faltantes o una columna adicional inesperada. dtypes comprueba la interpretación e info() añade recuentos de valores no nulos. Si una columna destinada a números se carga como texto, conviene examinar los valores en bruto: una unidad, un marcador o una convención decimal distinta pueden impedir la inferencia numérica.

Relaciona las etiquetas con los registros

Para un archivo sin encabezado cuya primera línea es 1001,North,3, usa:

df = pd.read_csv(
    "orders.txt",
    header=None,
    names=["id", "region", "units"]
)

Sin esa opción, pandas toma el primer registro como encabezado. Sus valores se convierten en nombres de columnas y el registro desaparece de los datos. Usa index_col="order_id" cuando una columna existente deba etiquetar las filas. Usa usecols=["region", "units"] para leer solo esas columnas o nrows=1000 para inspeccionar las primeras 1000 filas de datos antes de cargar un archivo grande.

Deja que el lector de CSV gestione las comillas

El registro "Smith, Jane",Boston,10 tiene tres campos. La coma dentro del nombre entre comillas pertenece a ese nombre. Dos comillas dobles dentro de un campo entre comillas representan una comilla doble literal: "O'Neil ""Red""" se convierte en O'Neil "Red". Un campo entre comillas puede incluso contener un salto de línea, por lo que los registros y las líneas físicas no siempre coinciden.

Llamar a line.split(",") divide el nombre y no puede gestionar estas reglas. read_csv las gestiona como parte del análisis sintáctico. pd.read_table usa el tabulador como separador predeterminado; pd.read_fwf gestiona campos definidos por posiciones de caracteres.

Encuentra el archivo que busca Python

Una ruta relativa se resuelve desde el directorio de trabajo actual del programa. Si no se encuentra "data/sales.csv", inspecciónalo con Path.cwd() después de from pathlib import Path. También puedes pasar a read_csv una ruta absoluta, un objeto Path, una URL o un archivo de texto en memoria como StringIO. Comprueba la ubicación antes de cambiar las opciones de lectura: un archivo faltante y un archivo interpretado incorrectamente son problemas distintos.

Un delimitador separa campos; un separador decimal separa las partes entera y decimal de un número. Un separador de millares agrupa dígitos. Estas tres funciones requieren configuraciones distintas, incluso cuando se usa el mismo símbolo para distintas funciones en diferentes archivos.

Inspecciona los caracteres antes de elegir opciones

Examina algunas líneas en bruto en un editor. Una extensión .csv no garantiza que haya comas y .txt no identifica una estructura. Algunas configuraciones habituales son:

Puedes inspeccionar el comienzo sin leer todo el archivo:

with open("products.csv", encoding="utf-8") as f:
    print(f.readline())
    print(f.readline())

Analiza una exportación regional

Considera este texto:

product;price;qty
Tea;3,50;1.200
Coffee;12,90;850

Los puntos y coma dividen los campos, la coma es el separador decimal y el punto agrupa millares. Indica explícitamente las tres convenciones al leer:

df = pd.read_csv(
    "products.csv",
    sep=";",
    decimal=",",
    thousands="."
)

Los precios se convierten en 3,5 y 12,9. Las cantidades se convierten en 1200 y 850. Con la coma como separador predeterminado, este encabezado no describe tres columnas separadas por comas. Incluso después de elegir sep=";", la tarea no está terminada: los precios siguen siendo texto y "1.200" puede convertirse en el decimal 1,2. Este último resultado es un número válido con un significado incorrecto, por lo que puede producirse un error grave sin que se genere una excepción de análisis sintáctico.

Compara algunos valores cargados con su texto de origen e inspecciona describe() en busca de rangos poco plausibles. Una cantidad que se espera en miles y aparece cerca de uno apunta a un problema de convención numérica. Cambiar solo el delimitador no lo solucionará.

Distingue los límites de los campos de la agrupación de números

En un archivo delimitado por comas, un número agrupado como "1,234.50" debe ir entre comillas. Su coma interna forma parte del número. Con thousands=",", pandas puede leer el campo entre comillas como 1234,5. Sin comillas, la coma también crea un límite de campo; thousands no puede recuperar la estructura perdida del registro.

Elige un motor de análisis sintáctico compatible

El motor C predeterminado gestiona rápidamente las estructuras habituales. El motor Python admite la detección del separador con sep=None, los separadores con expresiones regulares y skipfooter. La detección examina una muestra y puede elegir mal en un informe irregular, así que indica directamente un separador conocido.

Un separador de más de un carácter se trata generalmente como una expresión regular y requiere el motor Python; r"\s+" es un caso especial que también admite el motor C. El motor PyArrow puede leer con hilos paralelos, pero admite un conjunto distinto de opciones. Por ejemplo, chunksize no es compatible con engine="pyarrow". Elige el motor según las opciones que necesita tu archivo y comprueba después la estructura y los valores del resultado.

La inferencia de tipos no puede saber si 999 es una medición o un código para un valor desconocido. Tampoco puede saber si los ceros iniciales tienen significado. Usa las definiciones de los datos para establecer las opciones de lectura antes de que la inferencia cambie esos valores.

Declara los marcadores de valores faltantes donde correspondan

pandas reconoce los campos vacíos y marcadores incorporados como "NA", "N/A", "n/a", "NULL", "NaN" y "None". Una fuente puede usar marcadores adicionales. Supón que score contiene 88, "n/a", "-" y 999, y que 999 está definido como desconocido:

df = pd.read_csv(
    "scores.csv",
    na_values={"score": ["-", "999"]}
)

La columna de puntuaciones contiene ahora 88,0 y tres valores faltantes. Sin declarar los marcadores, "-" puede hacer que la columna siga siendo texto; un valor centinela numérico no declarado puede entrar en los cálculos. La media de 88 y 999 es 543,5, aunque la única puntuación conocida es 88.

Un diccionario limita un marcador a su columna. Un na_values=["999"] para todo el archivo también eliminaría un código de producto real 999. Si "NA" es una etiqueta real, usa keep_default_na=False para desactivar la lista de marcadores incorporada e indica explícitamente los marcadores que sí significan faltante. Con esa configuración, incluye "" si los campos vacíos deben seguir contándose como faltantes.

Conserva los valores según su función

Lee los identificadores como texto:

df = pd.read_csv(
    "visits.csv",
    dtype={"site_code": str, "visits": "Int64"}
)

Un código como "00501" debe seguir teniendo cinco caracteres. Leerlo como entero da 501; convertir después ese entero en texto produce "501", no el código original. Usa un tipo numérico para los valores con los que calculas.

Las columnas de enteros normales de NumPy no pueden contener NaN, por lo que una columna de recuentos con un hueco suele convertirse en float64. El tipo "Int64" de pandas que admite valores faltantes, con I mayúscula, conserva los valores enteros y representa un hueco con <NA>. dtype_backend="numpy_nullable" solicita tipos que admiten valores faltantes en todo el resultado. Para un conjunto pequeño de etiquetas repetidas, dtype={"region": "category"} almacena las etiquetas como categorías y puede reducir el uso de memoria.

Especifica cómo se escriben las fechas

El texto que parece una fecha sigue siendo texto hasta que se interpreta. Para fechas con el día primero como "03/04/2026" y "13/04/2026", usa:

df = pd.read_csv(
    "events.csv",
    parse_dates=["day"],
    date_format="%d/%m/%Y"
)

Estos valores se convierten en el 3 y el 13 de abril. Sin un formato, una suposición con el mes primero puede intercambiar días y meses válidos o no convertir la columna. dayfirst=True expresa una preferencia; un formato explícito indica la estructura esperada. Las fechas ISO como "2026-04-03" evitan la ambigüedad entre día y mes.

Después de leer, inspecciona dtypes, isna().sum() y el recuento de filas. Comprueba una fecha cuya interpretación distinga las convenciones. Una columna que sigue mostrando texto indica que la interpretación no produjo los valores de fecha y hora previstos; un recuento de valores faltantes que aumenta inesperadamente puede revelar que una etiqueta real se confundió con un marcador.

Un informe puede mezclar una tabla con títulos, líneas vacías, comentarios, totales y notas sobre la fuente. Localiza primero el encabezado y los límites de los datos. De lo contrario, un lector puede confundir un título con los nombres de las columnas o incluir un total como una observación normal.

Lee solo la tabla

Un informe contiene estas nueve líneas físicas:

Monthly sales report
Exported 2026-04-01

region,jan,feb
North,120,135
# test row below
South,98,101
Total,218,236
Source: internal system

Las tres primeras líneas preceden al encabezado. Las dos últimas no son observaciones. Léelo con:

df = pd.read_csv(
    "report.csv",
    skiprows=3,
    comment="#",
    skipfooter=2,
    engine="python"
)

El resultado tiene dos filas. El total de enero es 218 entre North y South. Conservar la fila de totales añadiría otros 218 y daría 436. Con las opciones predeterminadas, el título de un campo puede convertirse en el encabezado y provocar un error de análisis sintáctico cuando llegan registros de tres campos.

skiprows=3 cuenta las tres primeras líneas físicas, incluida la línea vacía. Una lista como skiprows=[0, 2] elimina posiciones concretas de línea contadas desde cero. Las líneas vacías se omiten de forma predeterminada y comment="#" elimina el texto de los comentarios. skipfooter necesita el motor Python. Ajusta estas opciones a la estructura real; un número fijo de líneas que omitir puede dejar de ser correcto cuando el programa de exportación añade una línea de título.

Investiga los registros con formato incorrecto

Un registro con demasiados campos puede activar on_bad_lines="error", la opción predeterminada. "warn" lo omite con una advertencia, mientras que "skip" lo elimina sin avisar. Antes de elegir cualquiera de las dos, inspecciona el registro en bruto. Una coma sin comillas dentro de un nombre o un delimitador incorrecto pueden crear campos adicionales; al omitirlo se pierde una observación válida en lugar de corregir la causa.

Un número insuficiente de campos se trata de otra forma. Bajo id,name,score, el registro 2,Ben se carga con una puntuación faltante. No tiene por qué generar un error. Comprueba los recuentos de valores faltantes además de los recuentos de filas, y compara los registros conservados con la fuente al excluir líneas con formato incorrecto.

Lee encabezados apilados o posiciones de caracteres

Dos filas de etiquetas de columnas pueden formar un índice jerárquico (MultiIndex). Con las etiquetas de grupo region,sales,sales sobre ,2025,2026, header=[0, 1] produce etiquetas como ("sales", "2025"). Si las etiquetas planas son más adecuadas para el análisis, omite ambas filas de encabezado y proporciona names=["region", "sales_2025", "sales_2026"].

El texto de ancho fijo no tiene delimitador. Los límites de las columnas son posiciones de caracteres:

df = pd.read_fwf(
    "readings.txt",
    colspecs=[(0, 4), (4, 11), (11, 16)]
)

Estos intervalos semiabiertos incluyen cada inicio y excluyen su final. El primer campo ocupa las posiciones de 0 a 3 y el siguiente comienza en 4. widths=[4, 7, 5] describe la misma estructura. La inferencia es práctica para muestras regulares; los límites explícitos impiden que un valor corto al principio defina una anchura incorrecta.

Un archivo almacena bytes, cada uno con un valor de 0 a 255. Una codificación define cómo se representan los caracteres mediante esos bytes. La codificación convierte texto de Python en bytes; la decodificación convierte los bytes de nuevo en texto. Los mismos bytes pueden representar caracteres distintos según las reglas de decodificación.

Cuenta los caracteres y los bytes por separado

text = "café"
raw = text.encode("utf-8")
print(len(text))  # 4 characters
print(len(raw))   # 5 bytes
print(raw.decode("utf-8"))  # café

Aquí el acento no crea un segundo carácter visible. La letra "é" necesita dos bytes en UTF-8, por lo que cuatro caracteres ocupan cinco bytes. Un recuento de bytes y un recuento de caracteres responden a preguntas distintas.

ASCII define 128 caracteres, incluidas las letras inglesas básicas, dígitos, signos de puntuación y códigos de control. Sus valores de byte coinciden en ASCII, UTF-8, Latin-1 y Windows-1252. Esa parte inicial compartida explica por qué una muestra que solo contiene inglés puede parecer correcta incluso cuando la configuración de codificación es incorrecta.

Reconoce las principales familias de codificaciones

UTF-8 representa todos los caracteres Unicode y es la opción habitual para el intercambio de texto. Latin-1 y Windows-1252 representan un conjunto más pequeño de caracteres. Coinciden en muchas letras acentuadas, pero difieren en una parte del intervalo de bytes: Windows-1252 usa el byte 0x80 para "€", mientras que Latin-1 tiene ahí un carácter de control. No son nombres intercambiables para una misma codificación.

Lee correctamente las marcas de orden de bytes

Una marca de orden de bytes, o BOM, es un marcador al principio de algunos archivos. UTF-16 puede comenzar con FF FE para el orden de byte menos significativo primero o FE FF para el orden de byte más significativo primero. encoding="utf-16" usa la BOM para elegir el orden. Sin una BOM, especifica "utf-16-le" o "utf-16-be" según la fuente.

Una BOM de UTF-8 es EF BB BF. open(..., encoding="utf-8-sig") de Python la elimina al decodificar. El uso de "utf-8" sin más en open() la conserva como \ufeff, que puede convertirse inesperadamente en parte del nombre del primer encabezado. El lector CSV de pandas también gestiona una BOM de UTF-8 inicial, pero elegir utf-8-sig deja clara la convención prevista para el archivo.

Indica la codificación explícitamente

with open("notes.txt", encoding="utf-8") as f:
    text = f.read()

El valor predeterminado de open() depende de la versión de Python y del modo UTF-8. Python 3.11 a 3.14 pueden usar la codificación de la configuración regional; Python 3.15 activa el modo UTF-8 de forma predeterminada, con la opción de desactivarlo. Una codificación explícita mantiene el script vinculado al formato real del archivo en distintos equipos. También evita que un valor predeterminado de la plataforma cambie sin avisar la forma de leer los mismos bytes.

Una codificación incorrecta puede fallar de forma evidente con UnicodeDecodeError o producir silenciosamente texto que parece legible pero es incoherente, llamado mojibake. Ambos problemas parten de interpretar los bytes con una regla incorrecta. Conserva el archivo original para poder decodificarlo de nuevo.

Diagnostica un error a partir de la fuente

Un CSV guardado como Windows-1252 contiene nombres de ciudades, entre ellos "Zürich" y "Málaga". Leerlo como UTF-8 puede fallar en el byte 0xfc, usado para "ü" en Windows-1252. Cuando la configuración de exportación de la fuente confirme su codificación, léelo con:

df = pd.read_csv("cities.csv", encoding="cp1252")
print(df["city"].head())

Inspecciona nombres que contengan acentos o símbolos. Una muestra formada solo por caracteres ASCII no permite distinguir estas codificaciones. Un byte concreto que no es válido en UTF-8 sugiere una posible codificación antigua; no identifica de manera única cuál produjo el archivo.

Reconoce un error que no generó una excepción

Los bytes UTF-8 decodificados como Windows-1252 pueden convertir "café" en "café" y "São Paulo" en "São Paulo". El lector ha producido caracteres correctamente, pero son los caracteres equivocados. Vuelve a leer los bytes originales usando UTF-8:

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

Buscar y sustituir repara un síntoma visible cada vez y puede pasar por alto otras letras dañadas. También puede cambiar una aparición legítima de un carácter. La decodificación correcta aborda la causa en todo el archivo.

Reúne evidencia sobre la codificación

Empieza por la documentación del proveedor o la configuración de exportación. Si es necesario, inspecciona una pequeña muestra de bytes:

with open("cities.csv", "rb") as f:
    sample = f.read(200)
print(sample)

El modo binario conserva los bytes sin decodificarlos. Una BOM puede dar una pista directa. Un detector como charset-normalizer estima una codificación probable, pero una muestra corta puede encajar con varias candidatas. Comprueba el resultado frente a nombres con acentos y símbolos conocidos.

Latin-1 asigna un carácter a cada byte, por lo que puede decodificar cualquier secuencia de bytes sin error. Ese éxito por sí solo no indica si los caracteres son correctos. Windows-1252 también usa caracteres de un byte, pero deja unos pocos valores de byte sin definir y puede generar un error de decodificación.

Evita descartar la evidencia

encoding_errors="replace" sustituye por "�" los bytes que el decodificador no puede leer. encoding_errors="ignore" los elimina. Estas opciones pueden ayudar a inspeccionar una entrada dañada, pero pierden información y no deben sustituir la búsqueda de la codificación correcta. Un nombre cambiado a "Zrich" puede impedir una coincidencia igual que un texto visiblemente corrupto.

Para la salida, UTF-8 admite la mayor variedad de caracteres. Algunos programas de hojas de cálculo lo identifican de forma más fiable cuando hay una BOM:

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

Vuelve a abrir la exportación en el programa receptor e inspecciona los mismos valores con acentos. El objetivo es que el texto sea correcto en ambos extremos del intercambio.

El tamaño del archivo en disco no equivale a la memoria que necesita. pandas crea arreglos, índices y valores de texto en memoria, y sus tipos afectan al espacio necesario. Mide con df.memory_usage(deep=True) o df.info(memory_usage="deep") antes de decidir cómo cargar más datos.

Reduce los datos que cargas en memoria

Lee columnas seleccionadas con usecols, inspecciona una muestra inicial con nrows y elige tipos adecuados con dtype. Una categoría puede almacenar de forma compacta nombres de regiones repetidos. float32 usa menos espacio que float64, pero ofrece unas siete cifras significativas, así que elígelo solo cuando esa precisión sea adecuada para las mediciones. Una pequeña vista previa ayuda a identificar los tipos; no demuestra que todas las filas posteriores sigan el mismo patrón.

Procesa bloques y conserva un resultado reducido

chunksize cambia el valor devuelto de un DataFrame a un iterador de DataFrames. Para un total y una media:

total = 0.0
count = 0
with pd.read_csv(
    "measurements.csv",
    usecols=["amount"],
    chunksize=100_000
) as reader:
    for chunk in reader:
        total += chunk["amount"].sum()
        count += chunk["amount"].count()
mean = total / count if count else float("nan")

El bucle mantiene una suma acumulada y un recuento de valores presentes. Cada bloque puede liberarse después de usarlo. Reunir todos los bloques en una lista y concatenarlos después vuelve a exigir la memoria del conjunto completo; procesar por bloques solo ahorra memoria cuando se conserva un resultado reducido o se escriben las partes procesadas.

Un archivo de diez filas leído con chunksize=4 produce partes de 4, 4 y 2 filas. Para importes del 1 al 10 con regiones que se repiten en el orden N, S, E, suma los totales regionales parciales para obtener N 22, S 15 y E 18. Su total combinado es 55.

Combina las cantidades adecuadas

Las sumas y los recuentos se suman. Los mínimos se combinan tomando el menor de los mínimos parciales; los máximos, tomando el mayor de los máximos parciales. Las medias necesitan ponderaciones porque los bloques pueden contener distintos números de observaciones válidas.

Para los valores 1, 2 y 3 en un bloque y 10 en otro, las medias de los bloques son 2 y 10. La media de esas medias es 6, lo que da al bloque de un valor el mismo peso que al de tres valores. En su lugar, suma las sumas y los recuentos: un total de 16 entre cuatro observaciones da una media de 4. Las medianas de los bloques no contienen información suficiente para reconstruir una mediana general.

Lee archivos comprimidos directamente

read_csv normalmente infiere la compresión a partir de extensiones reconocidas como .gz, .bz2, .zip, .xz y .zst. Descomprime durante la lectura:

with pd.read_csv("measurements.csv.gz", chunksize=100_000) as reader:
    for chunk in reader:
        print(len(chunk))

Un archivo ZIP usado de esta manera debe contener exactamente un archivo de datos. df.to_csv("out.csv.gz", index=False) escribe CSV comprimido con gzip. La compresión reduce el espacio en disco y el tamaño de transferencia; no elimina la memoria que usa la tabla decodificada. Para análisis repetidos, convertir un conjunto de datos comprobado a Parquet también evita volver a interpretar el texto y restablece los tipos de columna almacenados.

Un libro de Excel puede contener varias hojas, títulos y totales calculados. Las celdas tienen valores y tipos almacenados, además de formato de visualización. Leer una hoja de cálculo implica localizar la tabla de datos y comprender qué partes del libro se convierten en valores del DataFrame.

Elige la hoja y sus límites

df = pd.read_excel(
    "quarterly.xlsx",
    sheet_name="Q1",
    skiprows=2,
    usecols="A:C",
    nrows=2
)

Supón que la fila 1 es un título combinado, la fila 2 está vacía, la fila 3 contiene region, date y sales, y las filas 4 a 5 contienen las observaciones. skiprows=2 hace que la fila 3 sea el encabezado; nrows=2 se detiene antes del total de la fila 6. Para North 1200 y South 950, las dos observaciones suman 2150. Incluir un total almacenado en caché de 2150 como tercera observación duplicaría esa cantidad.

Excel muestra los números de fila a partir de 1; las posiciones de fila de pandas empiezan en 0. header=2 también selecciona la fila 3 de Excel como encabezado. usecols="A,C,E:F" selecciona columnas separadas y un rango. La opción predeterminada sheet_name=0 lee la primera hoja; un nombre selecciona una hoja concreta y sheet_name=1 selecciona la segunda.

sheet_name=None devuelve un diccionario que relaciona nombres de hojas con DataFrames. Selecciona una clave o recorre .items(); el propio diccionario no es un DataFrame. Para varias lecturas de un mismo libro:

with pd.ExcelFile("quarterly.xlsx") as xf:
    print(xf.sheet_names)
    q1 = pd.read_excel(xf, sheet_name="Q1")

Conoce qué almacena realmente la celda

Un porcentaje mostrado como "15%" almacena 0,15. Un número mostrado con cinco dígitos puede almacenar 2139, aunque la pantalla muestre "02139". Ninguna opción de lectura puede recuperar un cero que solo existe en el formato. Almacena los identificadores como texto en el libro y pasa también dtype={"zip": str} al leer; de lo contrario, pandas puede inferir enteros incluso a partir de celdas de texto formadas solo por dígitos.

La precisión numérica de Excel está limitada a 15 cifras significativas. Un identificador de 16 dígitos introducido como número puede estar dañado antes de que Python lo lea. Almacena esos valores como texto. Una hoja de cálculo tiene como máximo 1 048 576 filas y 16 384 columnas, por lo que un conjunto de datos muy grande necesita otro formato.

Trata con cuidado las fórmulas y las celdas combinadas

pandas no calcula fórmulas. Lee los resultados almacenados en caché en el libro. Una aplicación de hojas de cálculo puede guardar resultados actualizados; un archivo generado por un script puede tener resultados en caché faltantes, de marcador o desactualizados. openpyxl no calcula un resultado y XlsxWriter normalmente escribe un cero como marcador salvo que se le proporcione uno. Vuelve a calcular los valores importantes en pandas o abre y guarda el libro en un programa de hojas de cálculo antes de confiar en sus totales almacenados en caché.

Solo la celda superior izquierda de un rango de celdas combinadas almacena su etiqueta. Por ello, una etiqueta de país combinada puede dejar huecos en las filas inferiores. Cuando la estructura confirme que la etiqueta se aplica a esas filas, df["country"] = df["country"].ffill() la propaga hacia abajo. Inspecciona los límites de la tabla antes de rellenar.

La lectura requiere una biblioteca de motor. openpyxl gestiona .xlsx y .xlsm; xlrd gestiona .xls, pyxlsb gestiona .xlsb, odf gestiona .ods y calamine admite varios formatos de hojas de cálculo. Un motor faltante genera un ImportError que indica la dependencia. Los colores, comentarios y otros estilos de presentación no se cargan como datos del DataFrame.

Excel es útil cuando las personas necesitan abrir e inspeccionar un informe en un programa de hojas de cálculo. Un DataFrame puede convertirse en una hoja de cálculo o varios DataFrames pueden compartir un libro. Elige la ruta de destino y los nombres de las hojas antes de escribir para que cada tabla vaya al lugar previsto.

Escribe una tabla o varias

weather.to_excel(
    "weather.xlsx",
    sheet_name="Weather",
    index=False
)

index=False evita que los números de fila predeterminados aparezcan en la hoja. Sin esta opción, aparecen como una primera columna adicional y pueden regresar como "Unnamed: 0" en una lectura posterior. Conserva un índice solo cuando contenga etiquetas significativas que deban estar en el informe.

Una llamada a to_excel basada en una ruta escribe un libro en esa ruta y sustituye cualquier archivo existente. Llamarla una vez para Weather y otra para Counts en la misma ruta puede dejar solo la segunda tabla. Usa un único gestor de escritura para ambas:

with pd.ExcelWriter("report.xlsx") as writer:
    weather.to_excel(writer, sheet_name="Weather", index=False)
    counts.to_excel(writer, sheet_name="Counts", index=False)

El gestor de contexto cierra y termina el libro cuando acaba el bloque. Leerlo con pd.read_excel("report.xlsx", sheet_name=None) devuelve un diccionario que contiene ambos nombres de hoja. Escribir .xlsx requiere openpyxl o XlsxWriter.

Actualiza una hoja de un libro existente

Para conservar las demás hojas mientras sustituyes una, usa un gestor de escritura en modo de adición:

with pd.ExcelWriter(
    "report.xlsx",
    mode="a",
    engine="openpyxl",
    if_sheet_exists="replace"
) as writer:
    counts.to_excel(writer, sheet_name="Counts", index=False)

if_sheet_exists controla qué ocurre cuando un nombre ya existe. "error" detiene la operación, "new" crea otra hoja, "replace" sustituye esa hoja y "overlay" escribe en sus celdas existentes. La superposición no borra las celdas antiguas que quedan fuera de la nueva tabla, por lo que una actualización más corta puede dejar filas antiguas. Decide si el informe necesita sustituir por completo la hoja o superponer datos en una posición elegida con cuidado.

Facilita la reapertura del archivo

Los nombres de las hojas tienen un límite de 31 caracteres y no pueden contener :, \, /, ?, *, [ o ]. Un nombre corto como "Q1 Summary" funciona; "Q1/Q2" contiene una barra prohibida. Algunos motores advierten en lugar de detenerse ante un nombre demasiado largo, así que elige tú nombres compatibles.

startrow y startcol sitúan una tabla mediante desplazamientos contados desde cero. na_rep da a los valores faltantes un marcador visible. float_format="%.2f" redondea los números escritos y autofilter=True añade botones de filtro al encabezado en pandas 3. Las columnas de fecha y hora se escriben como fechas de Excel.

Redondear en la salida cambia los números almacenados, no solo su visualización. Conserva por separado un archivo de análisis con precisión completa cuando necesites un informe redondeado. Vuelve a abrir el libro y comprueba la lista de hojas, las dimensiones de las tablas y algunos valores representativos. La lectura de Excel es relativamente lenta y un ciclo de escritura y lectura puede cambiar los tipos de datos de pandas, así que usa Parquet para tablas de análisis intermedias cuando importe conservar los tipos.

JSON almacena datos anidados como texto. Los objetos contienen pares de nombre y valor, los arreglos contienen valores ordenados y las cadenas usan comillas dobles. Sus otros valores son números, true, false y null. El módulo json de Python convierte esta sintaxis en objetos de Python antes de que construyas una tabla.

Interpreta y escribe JSON válido

import json

text = '{"station":"Oslo","active":true,"temp_c":[3.5,null,4.0]}'
data = json.loads(text)
print(data["active"])   # True
print(data["temp_c"])   # [3.5, None, 4.0]

Los objetos se convierten en diccionarios, los arreglos en listas y null en None. json.loads interpreta una cadena; json.load lee un archivo abierto. Las funciones de escritura realizan el proceso inverso: json.dumps devuelve texto y json.dump escribe en un archivo.

with open("station.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

ensure_ascii=False deja legibles caracteres como "ü". La opción predeterminada puede escribir el mismo carácter como \u00fc; ambas formas representan la misma cadena. Un diccionario de Python impreso no es JSON: las comillas simples, True, None y las comas finales son sintaxis JSON no válida. El JSON estándar tampoco tiene NaN. El codificador de Python lo permite de forma predeterminada, pero allow_nan=False lo rechaza; pandas escribe los valores faltantes como null.

Ajusta la estructura de la tabla

Una tabla JSON necesita una orientación, es decir, la disposición de filas, etiquetas y valores. orient="records" produce un objeto por fila:

[{"city":"Lyon","temp_c":21.5},{"city":"Osaka","temp_c":null}]

La orientación predeterminada de DataFrame, "columns", agrupa los valores bajo los nombres de las columnas y después bajo las etiquetas de las filas. "split" almacena columnas, índice y datos por separado. Especifica una orientación que coincida con el programa receptor en lugar de suponer que todas las tablas JSON tienen la misma forma.

from io import StringIO
import pandas as pd

df = pd.read_json(
    StringIO('[{"code":"0042","amount":9.5}]'),
    orient="records",
    dtype={"code": str}
)

En pandas 3, una cadena simple pasada a read_json es una ruta, así que envuelve el texto JSON propiamente dicho en StringIO. Incluso las cadenas JSON que solo contienen dígitos pueden inferirse como números; el tipo de datos explícito conserva "0042".

Usa JSON por líneas para registros secuenciales

JSON por líneas tiene un objeto JSON completo por línea, sin un arreglo que los englobe ni comas entre registros:

{"id":1,"amount":9.5}
{"id":2,"amount":12.0}

Léelo con pd.read_json(path, lines=True) y escríbelo con df.to_json(path, orient="records", lines=True). Las opciones chunksize y nrows del lector requieren lines=True, que permite acceder a los registros individuales de forma secuencial.

Al exportar fechas, establece date_format="iso" para obtener marcas de tiempo ISO legibles. pandas 3.1 sigue usando de forma predeterminada milisegundos desde la época para la salida JSON normal de DataFrame, pero ese valor predeterminado está cambiando. Una salida de fechas explícita evita depender de que el lector adivine qué representa un entero grande.

El JSON anidado puede describir un pedido, su cliente y varios artículos en un solo objeto. Antes de convertirlo en una tabla plana, decide la granularidad: qué representa cada fila. La granularidad determina qué importes se pueden sumar.

Convierte primero los objetos anidados en columnas

Considera dos pedidos. El pedido 501 pertenece a Ana y tiene los artículos A1 (cantidad 2, precio 3,5) y B7 (cantidad 1, precio 10,0). El pedido 502 pertenece a Ben y tiene A1 (cantidad 4, precio 3,5). Los datos de los clientes son objetos anidados y sus artículos son listas.

orders = [
    {"order_id": 501,
     "customer": {"name": "Ana", "country": "PT"},
     "items": [{"sku": "A1", "qty": 2, "price": 3.5},
               {"sku": "B7", "qty": 1, "price": 10.0}]},
    {"order_id": 502,
     "customer": {"name": "Ben", "country": "CA"},
     "items": [{"sku": "A1", "qty": 4, "price": 3.5}]}
]
order_rows = pd.json_normalize(orders)

Esto produce dos filas y cuatro columnas: order_id, items, customer.name y customer.country. Los campos anidados de los clientes se convierten en columnas con nombres separados por puntos. Las listas de artículos permanecen en las celdas; la normalización no convierte automáticamente todas las listas en filas.

Expande una lista con información del objeto contenedor

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

record_path elige la lista cuyas entradas se convierten en filas. meta copia los valores del objeto contenedor en cada fila, con una lista de claves para una ruta anidada. El resultado tiene tres filas de artículos: dos para el pedido de Ana y una para el de Ben. Los ingresos son la cantidad multiplicada por el precio: 7,0; 10,0 y 14,0, que suman 31,0.

Si un cargo de envío a nivel de pedido es 4,00, se repite en ambas filas de artículos del pedido 501. Sumar esos cargos repetidos da 8,00 para un pedido. Conserva los importes del pedido en una tabla de pedidos separada cuando también necesites una tabla de artículos; conserva order_id para conectarlas.

Controla los nombres y los campos faltantes

sep="_" crea nombres como customer_name. record_prefix="item_" distingue los campos de los artículos de los campos del objeto contenedor con el mismo nombre. max_level=0 deja intactos los diccionarios anidados.

Un campo anidado normal que falta en un registro aparece como faltante en su columna de salida. Un campo faltante solicitado mediante meta genera KeyError de forma predeterminada; errors="ignore" permite metadatos faltantes y los rellena con NaN. Una lista faltante indicada por record_path sigue necesitando corrección.

Extrae el contenido de las respuestas de API antes de convertirlo en una tabla plana

Una API puede devolver un envoltorio que contiene count, next y results. Pasa data["results"] a pd.json_normalize para convertir los registros en una tabla plana. Pasar el propio envoltorio normaliza un objeto contenedor y deja su lista de resultados dentro de una celda. Mantén disponibles los metadatos de paginación para obtener páginas posteriores, pero construye la tabla de análisis a partir de la lista de registros propiamente dicha.

Una API web acepta una solicitud HTTP en un punto de acceso y devuelve un código de estado, encabezados y un cuerpo. Muchas API usan cuerpos JSON, pero que llegue una respuesta no significa que contenga los datos o todos los registros que necesitas.

Envía parámetros y comprueba la respuesta

import requests

resp = requests.get(
    url,
    params={"city": "Lima", "units": "metric"},
    timeout=10
)
resp.raise_for_status()
data = resp.json()
df = pd.json_normalize(data["results"])

Aquí url es el punto de acceso documentado de la API. params codifica la cadena de consulta, por lo que los espacios y caracteres especiales de los valores se gestionan correctamente. Requests no tiene un tiempo máximo de espera predeterminado. Un único valor de tiempo máximo controla la espera de conexión y de lectura; no es un plazo para descargar toda la respuesta.

Llama a raise_for_status() antes de usar el cuerpo. Genera un error HTTP para respuestas 4xx y 5xx. Un mensaje de error JSON puede interpretarse correctamente y aun así describir una solicitud fallida; a la inversa, una respuesta 200 puede contener texto que no sea JSON y hacer que resp.json() falle. Inspecciona resp.text cuando el formato de la respuesta no sea el esperado.

Mantén separadas las credenciales

Usa el método de autenticación documentado por la API. Para un token de portador, lee una clave de una variable de entorno y envíala en un encabezado:

import os

key = os.environ["WEATHER_API_KEY"]
headers = {"Authorization": "Bearer " + key}

Mantén las claves fuera del código guardado y de los cuadernos interactivos. Si una clave se ha compartido o incluido en un commit, revócala y sustitúyela. Una clave concede acceso; ocultar después un valor mostrado no elimina su exposición.

Continúa hasta leer todas las páginas

Sigue el mecanismo de página siguiente documentado por la API, ya use números de página, desplazamientos o una URL siguiente. Recopila los registros de cada página y detente cuando se cumpla la condición final indicada. Un total de 230 registros con 100 por página requiere páginas de 100, 100 y 30. La primera página puede ser perfectamente válida y el conjunto de datos estar incompleto.

Compara el recuento recopilado con el total comunicado cuando esté disponible. Respeta los límites de solicitudes: 429 exige esperar antes de otra solicitud y Retry-After puede especificar el retraso. Ese encabezado puede contener segundos o una fecha HTTP. Guarda las respuestas en bruto para que el análisis sea reproducible y para evitar descargar los mismos datos en cada nueva ejecución.

Reconoce otros formatos de tablas web

pd.read_html(url) devuelve una lista de DataFrames, uno por cada tabla HTML coincidente. match="Population" limita las tablas según su texto. Necesita una dependencia de análisis de HTML como lxml o BeautifulSoup con html5lib. pd.read_xml lee elementos XML repetidos como filas, mediante lxml o parser="etree". Consulta las condiciones de un sitio antes de extraer datos y prefiere una descarga oficial o una API cuando esté disponible.

Una exportación CSV debe conservar los valores que necesita la persona receptora y dejar claras sus convenciones. Elige si el índice de filas es un dato, cómo aparecen los valores faltantes y si la salida se destina a un análisis preciso o a una visualización redondeada.

Elige qué se convierte en columna

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

La opción predeterminada es escribir el índice. Para una tabla con un índice numerado normal, esto añade un primer campo sin nombre; un read_csv posterior puede mostrarlo como "Unnamed: 0". index=False omite esos números de fila. Cuando el índice contenga etiquetas significativas, consérvalo y vuelve a leerlo con index_col=0.

Los valores faltantes normalmente se convierten en campos vacíos. na_rep="NA" los hace visibles, pero el lector receptor debe interpretar correctamente ese marcador. En una tabla de ciudades con Lyon a 21,5 °C y Osaka a 18,25 °C, un valor de precipitación faltante para Osaka debe seguir siendo distinto de una precipitación cero.

Adapta la convención de texto al destinatario

df.to_csv(
    "weather_export.csv",
    index=False,
    sep=";",
    decimal=",",
    na_rep="NA",
    date_format="%Y-%m-%d",
    encoding="utf-8"
)

Las opciones de separador y decimal producen valores como Lyon;21,5;0,0. La salida de fecha ISO mantiene el día y el mes sin ambigüedad. Usa encoding="utf-8-sig" cuando un programa de hojas de cálculo receptor necesite una BOM para reconocer UTF-8.

float_format="%.1f" escribe una cifra decimal. El valor 18,25 se convierte en "18.2" con este formato y la precisión descartada no puede recuperarse del CSV. Conserva la precisión completa para los datos de análisis; crea un informe redondeado separado cuando sea necesario.

Comprueba qué se conserva en un ciclo de escritura y lectura

CSV almacena caracteres sin metadatos de tipos de datos de pandas. Considera cuatro columnas: un identificador "02139", una fecha y hora, una categoría ordenada A < B < C y enteros que admiten valores faltantes con un hueco. Una lectura CSV predeterminada puede devolver el entero 2139, texto de fecha, etiquetas de categoría simples sin su orden y números de coma flotante para los recuentos.

Por tanto, que una lectura termine correctamente no significa necesariamente que se haya restablecido el DataFrame original. Conserva las opciones necesarias para reconstruir los datos, incluidos los identificadores de texto, la interpretación de fechas y los marcadores de valores faltantes. El orden de las categorías también debe definirse de nuevo. Para análisis repetidos en los que importan estos tipos, Parquet puede conservarlos directamente.

Añade registros y protege la entrada en bruto

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

Esto añade filas a un archivo existente. Mantén el orden de las columnas y las convenciones coherentes con ese archivo. Con header=True, una adición escribe otro encabezado en medio y el siguiente lector puede tratarlo como un registro. Para un archivo nuevo, escribe el encabezado una vez antes de las adiciones posteriores.

Mantén los archivos recibidos o descargados sin cambios en una ubicación de datos en bruto. Escribe los resultados derivados por separado con nombres descriptivos. Al volver a abrir una exportación procesada, comprueba su recuento de filas, columnas, valores faltantes y valores representativos, incluidos ceros iniciales y fechas.

El mejor formato de almacenamiento depende de quién lea los datos después y de qué deba conservarse durante el intercambio. Una tabla enviada a una persona de tu equipo, una respuesta anidada de una API y un conjunto de datos de análisis con tipos tienen necesidades distintas.

Compara el almacenamiento de texto y binario

Los formatos de texto codifican caracteres visibles. CSV es fácil de inspeccionar y tiene amplia compatibilidad; JSON representa de forma natural objetos y arreglos anidados. CSV no tiene un esquema de tipos de columnas y los tipos de valores JSON habituales no conservan todos los tipos de datos de pandas. Volver a leerlos requiere interpretarlos y puede requerir elecciones explícitas de tipos.

Los formatos binarios codifican datos para que el software los lea directamente. Formatos como Parquet y Feather almacenan un esquema que describe columnas y tipos, lo que reduce la necesidad de volver a inferirlos. La compatibilidad con los tipos sigue dependiendo del formato y del lector: los objetos Python arbitrarios no se vuelven portables solo porque el archivo sea binario.

Una estructura orientada a filas mantiene juntos los campos de un registro. Una estructura por columnas mantiene juntos los valores de la misma columna. El análisis suele necesitar unas pocas columnas de muchas filas, por lo que los lectores por columnas pueden omitir las columnas innecesarias. Los valores similares adyacentes también se comprimen bien. El tamaño del archivo y la velocidad dependen de los datos; el resultado de compresión de una tabla no es una proporción fija para todas las tablas.

Relaciona cada formato con una tarea

Parquet es un formato abierto utilizado por pandas, R, Spark y DuckDB. Feather usa Arrow IPC y es útil para el intercambio rápido entre Python y R o entre etapas locales. to_feather y read_feather permiten ese intercambio. HDF5 agrupa varios conjuntos de datos en un archivo; to_hdf de pandas requiere PyTables.

Comprende el límite de confianza de pickle

pickle puede guardar objetos Python más allá de las tablas normales, pero cargarlo puede ejecutar código. Nunca cargues un archivo pickle de una fuente no fiable. Úsalo para tus propios objetos de corta duración y espera límites de compatibilidad a medida que cambien Python y las bibliotecas. Por ejemplo, pandas 3 ya no admite leer archivos pickle creados con versiones de pandas anteriores a 1.0.

Decide según el resultado necesario

Si una persona necesita inspeccionar una tabla pequeña sin herramientas especiales, CSV es práctico. Si necesita hojas de libro con nombres, usa Excel. Si necesitas conservar identificadores, categorías y tipos que admiten valores faltantes entre sesiones de análisis, elige Parquet. Si varios programas necesitan consultar y actualizar registros compartidos, una base de datos se ajusta mejor a la tarea que repartir copias de un archivo. La elección del formato depende del próximo uso, no de la extensión de la entrada original.

Parquet almacena una tabla con los tipos de sus columnas en un formato abierto y por columnas. Es útil cuando un DataFrame comprobado se va a cargar repetidamente o a pasar a otras herramientas de análisis. pandas usa PyArrow para los ejemplos siguientes.

Escribe y verifica un ciclo de lectura y escritura con tipos

df.to_parquet("sales.parquet", engine="pyarrow")
restored = pd.read_parquet("sales.parquet", engine="pyarrow")
print(restored.dtypes)

Un identificador de texto "02139", una columna de fecha y hora, una categoría ordenada y enteros que admiten valores faltantes pueden conservar sus tipos en este ciclo de pandas a PyArrow y de vuelta a pandas. A diferencia de una lectura CSV, no es necesario adivinar la función del identificador ni reconstruir el orden de la categoría. Inspecciona los tipos y valores representativos al introducir un nuevo escritor o lector.

La opción predeterminada index=None almacena un RangeIndex de forma compacta como metadatos. Otro índice se escribe como columnas y se restablece al leer. Usa index=False cuando no necesites el índice. Esa elección afecta a las etiquetas de fila independientemente de las columnas normales de la tabla.

Lee menos datos y elige la compresión

small = pd.read_parquet(
    "sales.parquet",
    columns=["zip", "amount"]
)

El lector puede recuperar solo esas columnas del almacenamiento. Esto es distinto de cargar la tabla completa y seleccionarlas después, pues entonces ya se ha asumido el coste de leerla entera. La selección de columnas es especialmente útil para tablas anchas.

Snappy es el códec de compresión predeterminado. compression="zstd" o "gzip" suele producir archivos más pequeños a cambio de más trabajo de escritura, mientras que compression=None escribe datos sin comprimir. Mide la relación entre tamaño y velocidad con datos representativos; las etiquetas repetidas y las mediciones aleatorias no se comprimen igual. Instala PyArrow; el motor alternativo fastparquet está obsoleto en pandas 3.1.

Organiza un conjunto de datos en particiones

df.to_parquet(
    "sales_dataset",
    engine="pyarrow",
    partition_cols=["year"],
    index=False
)
recent = pd.read_parquet(
    "sales_dataset",
    filters=[("year", "==", 2026)]
)

El destino es un directorio con subdirectorios como year=2025 y year=2026. Leer el directorio carga el conjunto de datos; un filtro puede evitar las particiones que no correspondan. Con esta estructura, PyArrow obtiene los valores de year de los nombres de los directorios y pandas suele recibir una columna de partición categórica.

Elige una columna de partición con un conjunto pequeño de valores útiles por los que filtres a menudo. Un identificador único de registro crea miles de particiones diminutas y aumenta el trabajo con archivos y directorios. El año o un conjunto pequeño de regiones suelen ofrecer una división más práctica.

Añade datos sin dañar el conjunto

Un único archivo Parquet no admite añadir filas mediante pandas como se hace con CSV. Escribe archivos o particiones nuevos en el directorio del conjunto de datos, o lee, combina y vuelve a escribir un único archivo. Los archivos de un mismo conjunto de datos necesitan esquemas compatibles. Si uno almacena un código como texto y otro como entero, la carga puede fallar o convertir los valores. Establece tipos de datos coherentes antes de escribir cada parte y comprueba que una partición añadida no cree copias superpuestas de los mismos registros.

Una base de datos relacional almacena registros en tablas con columnas nombradas. Un programa envía una consulta SQL mediante una conexión y recibe un resultado que pandas puede convertir en un DataFrame. La base de datos puede seleccionar solo los datos necesarios antes de enviarlos a Python.

Empieza con un archivo SQLite

import sqlite3
import pandas as pd

con = sqlite3.connect("shop.db")
try:
    df = pd.read_sql_query(
        "SELECT region, amount FROM sales", con
    )
finally:
    con.close()

SQLite funciona sin un servidor independiente y almacena una base de datos en un archivo. Al conectarse crea el archivo si no existe, por lo que una ruta mal escrita puede abrir una base de datos nueva y vacía en lugar de la prevista. ":memory:" crea una base de datos temporal en memoria. La consulta anterior devuelve las columnas region y amount de una tabla sales existente; los nombres de las columnas del resultado se convierten en etiquetas del DataFrame.

El bloque with de una conexión SQLite gestiona una transacción, pero no cierra la conexión. Llama explícitamente a close() cuando termines. Un bloque try/finally cierra la conexión incluso si la lectura genera un error.

Usa un motor para una base de datos con servidor

SQLAlchemy proporciona motores para sistemas como PostgreSQL, MySQL y SQL Server, con el controlador correspondiente instalado. Una URL de conexión identifica el dialecto, el controlador, el servidor y la base de datos. Guárdala en una variable de entorno:

import os
from sqlalchemy import create_engine

engine = create_engine(os.environ["ANALYSIS_DB_URL"])
try:
    with engine.connect() as conn:
        df = pd.read_sql_query(
            "SELECT region, amount FROM sales", conn
        )
finally:
    engine.dispose()

El contexto de la conexión devuelve la conexión al grupo del motor. dispose() libera los recursos agrupados cuando ya no se necesita el motor. Usa una cuenta de solo lectura para el análisis y mantén las credenciales fuera de los cuadernos interactivos y del control de versiones. Una URL de motor para un archivo SQLite local puede ser "sqlite:///shop.db".

Elige el lector que corresponda a la entrada

Con una conexión sqlite3 directa, pasa una consulta completa. pd.read_sql("sales", con) envía sales como SQL y falla; usa pd.read_sql_query("SELECT * FROM sales", con) en su lugar. pandas admite conexiones de SQLAlchemy, ADBC y SQLite; una conexión directa de un controlador cualquiera no es un sustituto compatible solo porque el controlador pueda ejecutar SQL.

Transfiere el resultado que necesitas

Una consulta que devuelve filas y columnas seleccionadas transfiere menos datos que leer una tabla completa y descartar la mayor parte en pandas. La consulta proporcionada SELECT SUM(amount) AS total FROM sales devuelve un valor agregado, etiquetado como total. Leer el resultado de una consulta no cambia la tabla almacenada. Después de cargarlo, comprueba el recuento de filas y los tipos como harías con un archivo; los tipos declarados en la base de datos y los tipos de pandas devueltos están relacionados, pero no son idénticos.

Los valores variables deben ir en parámetros de consulta. La instrucción SQL define la operación; los parámetros vinculados proporcionan la región, el umbral u otro valor utilizado en esta ejecución. Esto conserva la estructura de la consulta incluso cuando un valor contiene una comilla.

Vincula valores con la sintaxis de la conexión

Para SQLite:

query = "SELECT region, amount, sold_on FROM sales WHERE amount > ? ORDER BY amount DESC"
df = pd.read_sql_query(query, con, params=(70,))

Para los importes de ventas 120,0; 75,5; 60,0 y 210,0, esto devuelve 210,0; 120,0 y 75,5 en orden descendente. La tupla (70,) tiene un elemento; (70) es solo el número 70. SQLite también acepta marcadores de posición con nombre, por ejemplo WHERE region = :r con params={"r": "North"}.

Las reglas de los marcadores de posición dependen de la interfaz. psycopg usa %s o %(name)s. Con SQLAlchemy, envuelve una instrucción en text y usa parámetros con nombre:

from sqlalchemy import text

query = text("SELECT region, amount FROM sales WHERE amount >= :m")
with engine.connect() as conn:
    df = pd.read_sql_query(query, conn, params={"m": 100})

Pasa los valores mediante params; no uses el formato de cadenas de Python para insertarlos en la instrucción.

Comprende qué protege la parametrización

Supón que el código construye una condición usando una cadena f y una entrada "x' OR '1'='1". Pegarla entre comillas cambia la condición a region = 'x' OR '1'='1', que coincide con todas las filas. Esto es una inyección SQL: un valor se ha convertido en estructura ejecutable de la consulta.

Un parámetro vinculado se compara como un solo valor, por lo que esa misma cadena solo coincide con una región que tenga literalmente ese texto. La vinculación también gestiona nombres normales que contienen apóstrofos sin tener que construir manualmente secuencias de escape para las comillas. La regla se aplica tanto a entradas de archivos como de formularios de usuarios.

Los parámetros representan valores, no nombres de tablas o columnas. Un parámetro en lugar de un nombre de tabla no selecciona esa tabla. Cuando un programa necesite un identificador variable, elígelo de una lista fija controlada por el código.

Controla los tipos del resultado

SQLite suele almacenar las fechas como texto. Pide a pandas que las interprete:

df = pd.read_sql_query(
    "SELECT sold_on, visits FROM observations", con,
    parse_dates=["sold_on"],
    dtype={"visits": "Int64"}
)

La columna de fecha se convierte en valores de fecha y hora, y un recuento con NULL de SQL usa enteros que admiten valores faltantes en lugar de convertirse en coma flotante solo para contener huecos. Inspecciona el resultado para comprobar la conversión.

Distingue los bloques del almacenamiento en búfer del controlador

chunksize=1000 devuelve un iterador de DataFrames que contienen como máximo 1000 filas cada uno. Un resultado de cuatro filas con chunksize=3 produce partes de tres y una. Mantén la conexión abierta mientras las procesas. Algunos controladores de bases de datos siguen almacenando en búfer el resultado completo antes de que pandas produzca los bloques; también puede necesitarse un cursor del lado del servidor o una configuración de lectura en flujo para limitar la memoria en todo el recorrido de la conexión.

to_sql crea una tabla de base de datos a partir de un DataFrame o escribe filas en una tabla existente. Sus opciones determinan si se conservan los datos existentes, si el índice se convierte en una columna y cómo se confirma un conjunto de escrituras.

Elige el comportamiento ante una tabla existente

df.to_sql("sales", con, index=False)

La opción predeterminada if_exists="fail" detiene la operación cuando sales ya existe. Elige otro modo solo cuando su efecto coincida con la carga prevista:

delete_rows está disponible en pandas 3. Sustituir una tabla elimina su definición anterior, incluidas claves, índices y restricciones; los permisos específicos de la base de datos también pueden verse afectados. Eliminar las filas conserva la definición, pero sigue borrando todos los registros existentes. Úsalo para una recarga completa prevista, no cuando el DataFrame solo contenga un lote nuevo.

Establece las columnas y escribe en una transacción

La opción predeterminada escribe el índice del DataFrame como una columna. Un índice sin nombre se convierte en index; uno con nombre conserva su nombre. index_label le da un nombre explícito e index=False lo excluye. Si un identificador ya es una columna normal, escribir los números de fila predeterminados no suele añadir información útil.

Con SQLAlchemy, dtype puede elegir tipos de base de datos:

from sqlalchemy import types

with engine.begin() as conn:
    df.to_sql(
        "sales", conn,
        if_exists="append",
        index=False,
        dtype={"sold_on": types.Date()},
        chunksize=1000
    )

engine.begin() confirma los cambios al salir correctamente y los revierte si se produce una excepción. Para una tabla existente, el esquema almacenado sigue determinando qué valores pueden insertarse; dtype no es una orden para rediseñar sus columnas. Las garantías de la transacción también dependen de que la base de datos admita las operaciones utilizadas. Añadir filas dentro de una transacción de SQLAlchemy mantiene unida la carga de inserción del ejemplo.

chunksize agrupa las filas en lotes. method="multi" coloca varias filas en una instrucción INSERT cuando se admite. Puede mejorar o reducir el rendimiento según la base de datos y el tamaño del lote, así que mídelo con datos representativos.

Verifica el aumento, no solo la finalización

check = pd.read_sql_query("SELECT COUNT(*) AS n FROM sales", con)
print(check["n"].iloc[0])

Para una tabla nueva o recargada por completo, compara el recuento con len(df). Para una adición, compara el aumento: una tabla de cuatro filas que recibe dos filas debe contener seis. El recuento de filas devuelto por to_sql procede de lo que comunica el controlador; verifica directamente los datos almacenados.

Ejecutar una adición dos veces repite los registros salvo que la base de datos rechace duplicados o el programa seleccione solo registros nuevos. Decide si la operación es una recarga completa o una adición de registros nuevos antes de volver a ejecutarla. Una transacción evita una carga parcial ante un fallo; no hace que las adiciones repetidas que terminan correctamente sean únicas.