Importación y exportación de JSONL en bases de datos: PostgreSQL, MongoDB y más
Una guía completa para importar archivos JSONL a bases de datos y exportar sus registros en formato JSONL. Incluye comandos COPY de PostgreSQL, herramientas de línea de comandos de MongoDB, JSON_TABLE de MySQL, scripts para SQLite y patrones de importación masiva listos para producción.
¿Por qué usar JSONL para importar y exportar datos en bases de datos?
JSONL (JSON Lines) se ha convertido en uno de los formatos preferidos para transferir datos entre bases de datos y sistemas externos. Cada línea es un objeto JSON independiente y completo, por lo que puedes procesar los registros en streaming, uno a uno, sin cargar todo el conjunto de datos en memoria. Esto resulta fundamental al migrar millones de filas entre instancias de PostgreSQL, sincronizar colecciones de MongoDB con un data warehouse o usar las exportaciones de una base de datos como entrada de pipelines de aprendizaje automático.
Frente a CSV, JSONL conserva los tipos de datos, admite objetos y arrays anidados y evita las ambigüedades al escapar delimitadores. Un archivo JSONL puede contener una columna jsonb de PostgreSQL tal cual, mientras que con CSV tendrías que aplanar la estructura anidada o escaparla. A diferencia de un array JSON completo, JSONL permite trabajar en streaming: puedes procesar, validar o transformar cada registro en cuanto se lee, sin esperar a que se termine de parsear todo el archivo.
Los principales sistemas de bases de datos ya cuentan con herramientas para JSONL. PostgreSQL permite cargar filas con COPY mediante la conversión a jsonb; MongoDB incluye mongoimport y mongoexport, que usan JSONL por defecto; MySQL 8.0 incorporó JSON_TABLE para extraer datos estructurados, y SQLite dispone de la extensión JSON1. En las siguientes secciones encontrarás los comandos, scripts y buenas prácticas concretos para cada base de datos.
PostgreSQL: importar y exportar JSONL
PostgreSQL ofrece varias formas de trabajar con JSONL. El comando COPY es la opción más rápida para la importación masiva, mientras que el tipo de datos jsonb permite almacenar y consultar datos semiestructurados de forma nativa. Si trabajas con tablas estructuradas, puedes extraer los campos de JSONL y cargarlos en columnas tipadas durante la importación.
La forma más rápida de importar JSONL a PostgreSQL es cargar cada línea como un valor jsonb con el comando COPY. Crea una tabla con una sola columna jsonb y, después, usa COPY FROM para cargar el archivo directamente en la base de datos en streaming.
-- Create a staging table with a single jsonb column
CREATE TABLE staging_import (data jsonb);
-- Import the JSONL file (each line becomes one row)
\COPY staging_import (data) FROM 'users.jsonl';
-- Verify the import
SELECT count(*) FROM staging_import;
SELECT data->>'name' AS name, data->>'email' AS email
FROM staging_import
LIMIT 5;
-- Move data into a structured table
INSERT INTO users (name, email, age)
SELECT
data->>'name',
data->>'email',
(data->>'age')::int
FROM staging_import;Para exportar datos en formato JSONL, usa row_to_json() o to_jsonb() para convertir cada fila en un objeto JSON y, después, guarda el resultado en un archivo con COPY. Cada fila ocupará una línea en el archivo de salida.
-- Export entire table as JSONL
\COPY (
SELECT row_to_json(t)
FROM (SELECT id, name, email, created_at FROM users) t
) TO 'users_export.jsonl';
-- Export with filtering and transformation
\COPY (
SELECT row_to_json(t)
FROM (
SELECT id, name, email,
created_at::text AS created_at
FROM users
WHERE active = true
ORDER BY id
) t
) TO 'active_users.jsonl';
-- Verify: each line is valid JSON
-- {"id":1,"name":"Alice","email":"[email protected]",...}Para cargas de trabajo en producción, usa un script de Python con psycopg2 que lea un archivo JSONL e inserte los registros en columnas tipadas. Así tendrás pleno control sobre la validación, la gestión de errores y el tamaño de los lotes.
import json
import psycopg2
from psycopg2.extras import execute_values
def import_jsonl_to_postgres(file_path, conn_string):
conn = psycopg2.connect(conn_string)
cur = conn.cursor()
batch = []
batch_size = 1000
total = 0
with open(file_path, 'r') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
batch.append((
record['name'],
record['email'],
record.get('age'),
))
except (json.JSONDecodeError, KeyError) as e:
print(f"Skipping line {line_num}: {e}")
continue
if len(batch) >= batch_size:
execute_values(
cur,
"INSERT INTO users (name, email, age) "
"VALUES %s ON CONFLICT (email) DO NOTHING",
batch
)
total += len(batch)
batch = []
print(f"Imported {total} records...")
if batch:
execute_values(
cur,
"INSERT INTO users (name, email, age) "
"VALUES %s ON CONFLICT (email) DO NOTHING",
batch
)
total += len(batch)
conn.commit()
cur.close()
conn.close()
print(f"Done. Imported {total} records.")
# Usage
import_jsonl_to_postgres('users.jsonl', 'postgresql://localhost/mydb')MongoDB: compatibilidad nativa con JSONL
MongoDB ofrece compatibilidad completa con JSONL mediante sus herramientas de línea de comandos Database Tools. Las utilidades mongoimport y mongoexport usan JSONL por defecto, lo que convierte a MongoDB en una de las bases de datos más sencillas para intercambiar datos en este formato. Cada línea de un archivo JSONL se corresponde directamente con un documento de MongoDB.
mongoimport lee un archivo JSONL e inserta cada línea como un documento en la colección indicada. Admite el modo upsert, la conversión de tipos de los campos y la inserción en paralelo para lograr un alto rendimiento.
# Basic import: each line becomes a document
mongoimport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--file=users.jsonl
# Upsert mode: update existing documents by _id
mongoimport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--file=users.jsonl \
--mode=upsert \
--upsertFields=email
# Drop collection before import (clean slate)
mongoimport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--file=users.jsonl \
--drop
# Import with parallel workers for large files
mongoimport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--file=large_users.jsonl \
--numInsertionWorkers=4mongoexport escribe cada documento de una colección en una sola línea JSON. Puedes filtrar los documentos, seleccionar los campos y ordenar la salida. El resultado es un archivo JSONL válido, listo para que lo procese cualquier sistema en las siguientes etapas del flujo de datos.
# Export entire collection as JSONL (default format)
mongoexport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--out=users_export.jsonl
# Export with query filter
mongoexport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--query='{"active": true}' \
--out=active_users.jsonl
# Export specific fields only
mongoexport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--fields=name,email,created_at \
--out=users_partial.jsonl
# Export with sorting
mongoexport \
--uri="mongodb://localhost:27017/mydb" \
--collection=users \
--sort='{"created_at": -1}' \
--out=users_sorted.jsonlMySQL: JSONL con JSON_TABLE y scripts
MySQL no incluye un comando de importación de JSONL como el de MongoDB, pero MySQL 8.0 incorporó JSON_TABLE, que permite extraer datos estructurados de cadenas JSON. Para importar JSONL de forma masiva, las opciones más fiables son combinar LOAD DATA INFILE para la carga inicial de los datos sin procesar con JSON_TABLE para la extracción, o usar un lenguaje de scripting como Python.
Carga el archivo JSONL como texto sin procesar en una tabla de staging y, después, usa JSON_TABLE para extraer los campos e insertarlos en una tabla estructurada. Este proceso de dos pasos se ejecuta íntegramente en MySQL.
-- Step 1: Create a staging table for raw lines
CREATE TABLE jsonl_staging (
id INT AUTO_INCREMENT PRIMARY KEY,
raw_line TEXT NOT NULL
);
-- Step 2: Load the JSONL file as raw text
LOAD DATA INFILE '/var/lib/mysql-files/users.jsonl'
INTO TABLE jsonl_staging
LINES TERMINATED BY '\n'
(raw_line);
-- Step 3: Extract structured data with JSON_TABLE
INSERT INTO users (name, email, age)
SELECT jt.name, jt.email, jt.age
FROM jsonl_staging,
JSON_TABLE(
raw_line, '$'
COLUMNS (
name VARCHAR(255) PATH '$.name',
email VARCHAR(255) PATH '$.email',
age INT PATH '$.age'
)
) AS jt;
-- Step 4: Clean up staging table
DROP TABLE jsonl_staging;
-- Verify the import
SELECT * FROM users LIMIT 5;Si necesitas más flexibilidad, usa un script de Python con mysql-connector-python para leer un archivo JSONL e insertar los registros por lotes. Este método procesa archivos grandes de forma eficiente y ofrece información detallada sobre los errores.
import json
import mysql.connector
def import_jsonl_to_mysql(file_path, config):
conn = mysql.connector.connect(**config)
cursor = conn.cursor()
batch = []
batch_size = 1000
total = 0
insert_sql = (
"INSERT INTO users (name, email, age) "
"VALUES (%s, %s, %s) "
"ON DUPLICATE KEY UPDATE name=VALUES(name)"
)
with open(file_path, 'r') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
batch.append((
record['name'],
record['email'],
record.get('age'),
))
except (json.JSONDecodeError, KeyError) as e:
print(f"Skipping line {line_num}: {e}")
continue
if len(batch) >= batch_size:
cursor.executemany(insert_sql, batch)
conn.commit()
total += len(batch)
batch = []
print(f"Imported {total} records...")
if batch:
cursor.executemany(insert_sql, batch)
conn.commit()
total += len(batch)
cursor.close()
conn.close()
print(f"Done. Imported {total} records.")
# Usage
import_jsonl_to_mysql('users.jsonl', {
'host': 'localhost',
'user': 'root',
'password': 'secret',
'database': 'mydb'
})SQLite: importación ligera de JSONL
SQLite es una excelente opción para el desarrollo local y los conjuntos de datos más pequeños. Aunque no incluye un comando nativo para importar JSONL, su extensión JSON1 ofrece json_extract() para trabajar con datos JSON. Además, un sencillo script de Python permite importar archivos JSONL de forma eficiente gracias al soporte de transacciones integrado en SQLite.
Usa el módulo sqlite3 incluido en Python para leer un archivo JSONL e insertar los registros en una base de datos SQLite. Agrupar todas las inserciones en una sola transacción mejora considerablemente el rendimiento con archivos grandes.
import json
import sqlite3
def import_jsonl_to_sqlite(jsonl_path, db_path):
conn = sqlite3.connect(db_path)
cursor = conn.cursor()
# Create table if it doesn't exist
cursor.execute("""
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE,
age INTEGER,
raw_json TEXT
)
""")
total = 0
errors = 0
with open(jsonl_path, 'r') as f:
# Use a transaction for bulk insert performance
conn.execute('BEGIN TRANSACTION')
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
cursor.execute(
"INSERT OR IGNORE INTO users "
"(name, email, age, raw_json) "
"VALUES (?, ?, ?, ?)",
(
record['name'],
record.get('email'),
record.get('age'),
line, # Store original JSON
)
)
total += 1
except (json.JSONDecodeError, KeyError) as e:
errors += 1
print(f"Line {line_num}: {e}")
conn.commit()
conn.close()
print(f"Imported {total} records, {errors} errors")
# Usage
import_jsonl_to_sqlite('users.jsonl', 'app.db')
# Query with json_extract (SQLite JSON1 extension)
# SELECT json_extract(raw_json, '$.name') FROM users;Buenas prácticas para la importación masiva
Al importar archivos JSONL grandes a una base de datos, debes prestar especial atención a las transacciones, la gestión de errores y el uso de recursos. Estas buenas prácticas se aplican a todos los sistemas de bases de datos y te ayudarán a crear pipelines de importación fiables y listos para producción.
Transacciones por lotes
RendimientoNunca insertes una sola fila por transacción. Agrupa las inserciones en lotes de 500-5000 filas por transacción. Así reducirás las operaciones de entrada/salida en disco y la sobrecarga de los bloqueos entre 10 y 100 veces. En la mayoría de las bases de datos, las mayores mejoras se consiguen con lotes de 1000 filas. Aumentar ese tamaño aporta cada vez menos beneficios y encarece el rollback si algo falla.
Gestión de errores por línea
FiabilidadParsea y valida cada línea JSONL por separado. Si una línea falla al validarse o insertarse, registra su número y el mensaje de error. Usa ON CONFLICT / ON DUPLICATE KEY para gestionar las infracciones de las restricciones de unicidad sin abortar toda la importación. Guarda las líneas que hayan fallado en un archivo de errores aparte para revisarlas más adelante.
Seguimiento del progreso
ObservabilidadEn archivos con millones de líneas, registra el progreso cada N registros (por ejemplo, cada 10,000). Lleva la cuenta del total de líneas leídas, las inserciones correctas, los duplicados omitidos y los errores. Calcula y muestra la velocidad de importación (registros/segundo) para detectar cuellos de botella de rendimiento. Esta información es esencial para supervisar las importaciones de larga duración.
Este patrón genérico combina el procesamiento por lotes, la gestión de errores y el seguimiento del progreso. Puedes adaptarlo a cualquier base de datos sustituyendo la función de inserción.
import json
import time
def batch_import_jsonl(file_path, insert_fn, batch_size=1000):
"""Generic JSONL batch importer with error handling."""
batch = []
stats = {
'total_lines': 0,
'imported': 0,
'skipped': 0,
'errors': 0
}
start_time = time.time()
error_file = open(file_path + '.errors', 'w')
with open(file_path, 'r') as f:
for line_num, line in enumerate(f, 1):
stats['total_lines'] = line_num
line = line.strip()
if not line:
stats['skipped'] += 1
continue
try:
record = json.loads(line)
batch.append(record)
except json.JSONDecodeError as e:
stats['errors'] += 1
error_file.write(f"{line_num}\t{e}\t{line}\n")
continue
if len(batch) >= batch_size:
inserted = insert_fn(batch)
stats['imported'] += inserted
batch = []
if line_num % 10000 == 0:
elapsed = time.time() - start_time
rate = stats['imported'] / elapsed
print(
f"Progress: {line_num:,} lines | "
f"{stats['imported']:,} imported | "
f"{rate:,.0f} records/sec"
)
# Flush remaining batch
if batch:
inserted = insert_fn(batch)
stats['imported'] += inserted
error_file.close()
elapsed = time.time() - start_time
print(f"\nComplete in {elapsed:.1f}s")
print(f" Lines: {stats['total_lines']:,}")
print(f" Imported: {stats['imported']:,}")
print(f" Errors: {stats['errors']:,}")
return statsPrepara tus datos con herramientas gratuitas para JSONL
Antes de importar JSONL a tu base de datos, valida el formato del archivo y realiza las conversiones entre formatos que necesites. Nuestras herramientas gratuitas en línea lo procesan todo localmente en tu navegador, de modo que tus datos nunca salen de tu equipo.
Exporta datos JSONL a hojas de cálculo CSV para analizarlos en Excel o Google Sheets.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Aprende a validar archivos JSONL usando JSON Schema. Cubre Python, Node.js, herramientas CLI y automatizacion CI/CD.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Aprende a usar JSONL como formato de intercambio en pipelines ETL. Incluye streaming con Apache Kafka, DAGs de Airflow, carga de datos en Snowflake y BigQuery y diseño de pipelines tolerantes a fallos.