Por Jerry Fan

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.

Importar JSONL a una columna jsonb
-- 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.

Exportar filas de PostgreSQL como JSONL
-- 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.

Script de Python para importar datos a columnas tipadas en PostgreSQL
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.

Importar JSONL con mongoimport
# 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=4

mongoexport 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.

Exportar datos de MongoDB a JSONL con mongoexport
# 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.jsonl

MySQL: 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.

Importar JSONL con una tabla de staging y JSON_TABLE
-- 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.

Script de Python para importar JSONL a MySQL
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.

Script de Python para importar JSONL a SQLite
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

Rendimiento

Nunca 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

Fiabilidad

Parsea 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

Observabilidad

En 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.

Patrón de importación por lotes listo para producció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 stats

Trabaja con archivos JSONL en línea

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin necesidad de subir archivos, 100% privado.

Preguntas frecuentes

Referencias