Por Jerry Fan

JSONL en Rust: serde_json, BufReader y abstracciones de coste cero

Una guía completa para trabajar con archivos JSONL (JSON Lines) en Rust. Aprende a leer, escribir, parsear y procesar datos JSONL en streaming con serde_json, BufReader, rayon para el procesamiento paralelo y tokio para la E/S asíncrona.

¿Por qué usar Rust para trabajar con JSONL?

Rust es una excelente opción para procesar JSONL cuando importan el rendimiento, la seguridad de memoria y la corrección del código. Su modelo de propiedad evita las carreras de datos en tiempo de compilación, sus abstracciones de coste cero permiten encadenar iteradores de alto nivel que se compilan en bucles eficientes, y serde_json es uno de los parsers de JSON más rápidos, independientemente del lenguaje. Si estás creando un pipeline de datos que necesita procesar millones de registros JSONL por segundo, Rust te da el control necesario para conseguirlo sin sacrificar la seguridad.

JSONL (JSON Lines) almacena un objeto JSON por línea, por lo que resulta ideal para el procesamiento en streaming, los logs en los que solo se añaden entradas y el procesamiento de grandes conjuntos de datos. BufReader de Rust lee los archivos línea a línea sin cargarlos enteros en memoria, y su modelo de iteradores encaja perfectamente con la estructura de JSONL, basada en líneas. En esta guía aprenderás a leer y escribir JSONL con BufReader, deserializar registros en structs con tipado fuerte mediante serde, procesar registros en paralelo con rayon, trabajar con E/S asíncrona con tokio e implementar un manejo de errores robusto con Result y el operador ?.

Lectura de archivos JSONL con BufReader

La biblioteca estándar de Rust incluye BufReader para leer archivos de forma eficiente mediante un búfer. En combinación con el iterador lines(), permite leer archivos JSONL línea a línea con un consumo adicional de memoria mínimo. Cada línea se parsea de forma independiente, por lo que este enfoque sirve para archivos de cualquier tamaño.

La forma más sencilla consiste en envolver un File en un BufReader, recorrer lines() y parsear cada línea con serde_json. Así solo se mantiene una línea en memoria en cada momento, sea cual sea el tamaño del archivo.

Lectura básica de JSONL con BufReader
use std::fs::File;
use std::io::{BufRead, BufReader};
use serde_json::Value;


fn read_jsonl(path: &str) -> std::io::Result<Vec<Value>> {
    let file = File::open(path)?;
    let reader = BufReader::new(file);
    let mut records = Vec::new();


    for (line_num, line) in reader.lines().enumerate() {
        let line = line?;
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue; // Skip empty lines
        }
        match serde_json::from_str::<Value>(trimmed) {
            Ok(value) => records.push(value),
            Err(e) => {
                eprintln!("Skipping invalid JSON at line {}: {}", line_num + 1, e);
            }
        }
    }


    Ok(records)
}


fn main() -> std::io::Result<()> {
    let records = read_jsonl("data.jsonl")?;
    println!("Loaded {} records", records.len());
    if let Some(first) = records.first() {
        println!("First record: {}", first);
    }
    Ok(())
}

Añade serde y serde_json a tu Cargo.toml. La feature derive habilita las macros Serialize y Deserialize para definir structs tipados.

Dependencias en Cargo.toml
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"


# Optional: for parallel processing
rayon = "1.10"


# Optional: for async I/O
tokio = { version = "1", features = ["full"] }

Parseo con seguridad de tipos mediante serde_json

Una de las grandes ventajas de Rust para procesar JSONL son las macros derive de serde, que permiten deserializar cada línea JSON directamente en un struct con tipado fuerte. El compilador comprueba que tu código maneje los datos correctamente y detecta incompatibilidades de tipos, campos ausentes y errores de estructura en tiempo de compilación, en lugar de hacerlo durante la ejecución.

Define un struct con Deserialize y usa serde_json::from_str para convertir cada línea JSONL en una instancia de ese struct. Si falta algún campo o tiene un formato incorrecto, obtendrás un mensaje de error claro durante el parseo, en lugar de que se produzcan panics más adelante en el programa.

Deserialización en structs tipados
use serde::Deserialize;
use std::fs::File;
use std::io::{BufRead, BufReader};


#[derive(Debug, Deserialize)]
struct LogEntry {
    timestamp: String,
    level: String,
    message: String,
    #[serde(default)]
    metadata: Option<serde_json::Value>,
}


fn read_typed_jsonl(path: &str) -> anyhow::Result<Vec<LogEntry>> {
    let file = File::open(path)?;
    let reader = BufReader::new(file);
    let mut entries = Vec::new();


    for line in reader.lines() {
        let line = line?;
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        let entry: LogEntry = serde_json::from_str(trimmed)?;
        entries.push(entry);
    }


    Ok(entries)
}


fn main() -> anyhow::Result<()> {
    let entries = read_typed_jsonl("logs.jsonl")?;
    for entry in &entries {
        println!("[{}] {}: {}", entry.level, entry.timestamp, entry.message);
    }
    Ok(())
}

Cuando los registros JSONL tienen esquemas distintos, usa serde_json::Value para acceder a los datos con flexibilidad. Puedes acceder a los valores mediante índices entre corchetes o usar los métodos as_str(), as_i64() para convertir los tipos de forma segura.

Parseo dinámico con serde_json::Value
use serde_json::Value;
use std::fs::File;
use std::io::{BufRead, BufReader};


fn process_dynamic_jsonl(path: &str) -> anyhow::Result<()> {
    let file = File::open(path)?;
    let reader = BufReader::new(file);


    for line in reader.lines() {
        let line = line?;
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }


        let value: Value = serde_json::from_str(trimmed)?;


        // Access fields dynamically
        if let Some(name) = value.get("name").and_then(Value::as_str) {
            println!("Name: {}", name);
        }
        if let Some(age) = value.get("age").and_then(Value::as_i64) {
            println!("Age: {}", age);
        }


        // Check if a field exists
        if value.get("email").is_some() {
            println!("Has email field");
        }
    }


    Ok(())
}

Escritura de archivos JSONL en Rust

Escribir JSONL es el proceso inverso a leerlo: serializa cada registro como una cadena JSON, añade un salto de línea y escríbelo en un archivo. BufWriter y serde_json::to_string permiten hacerlo correctamente y con buen rendimiento.

Serializa cada struct con serde_json::to_string() y escríbelo seguido de un salto de línea. La macro de derivación Serialize convierte automáticamente tus tipos de Rust a JSON.

Escritura básica de JSONL
use serde::Serialize;
use std::fs::File;
use std::io::Write;


#[derive(Serialize)]
struct Record {
    id: u64,
    name: String,
    score: f64,
}


fn write_jsonl(path: &str, records: &[Record]) -> std::io::Result<()> {
    let mut file = File::create(path)?;


    for record in records {
        let json = serde_json::to_string(record)
            .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
        writeln!(file, "{}", json)?;
    }


    Ok(())
}


fn main() -> std::io::Result<()> {
    let records = vec![
        Record { id: 1, name: "Alice".into(), score: 95.5 },
        Record { id: 2, name: "Bob".into(), score: 87.3 },
        Record { id: 3, name: "Charlie".into(), score: 92.1 },
    ];


    write_jsonl("output.jsonl", &records)?;
    println!("Wrote {} records", records.len());
    Ok(())
}

Para escribir archivos JSONL grandes, envuelve el File en un BufWriter y reduce así el número de llamadas al sistema. De este modo, las escrituras pequeñas se agrupan en bloques mayores que se escriben al vaciar el búfer, lo que mejora considerablemente la tasa de escritura.

Escritura con búfer para archivos de salida grandes
use serde::Serialize;
use std::fs::File;
use std::io::{BufWriter, Write};


#[derive(Serialize)]
struct Event {
    timestamp: u64,
    event_type: String,
    payload: serde_json::Value,
}


fn write_buffered_jsonl(path: &str, events: &[Event]) -> std::io::Result<()> {
    let file = File::create(path)?;
    let mut writer = BufWriter::new(file);


    for event in events {
        serde_json::to_writer(&mut writer, event)
            .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
        writer.write_all(b"\n")?;
    }


    writer.flush()?;
    Ok(())
}

Procesamiento en paralelo con rayon

El crate rayon de Rust permite procesar datos en paralelo con cambios mínimos en el código. Si llamas a par_iter() en lugar de iter(), rayon distribuye automáticamente el trabajo entre todos los núcleos de la CPU mediante un pool de hilos con work-stealing. Esto resulta especialmente eficaz en transformaciones JSONL limitadas por la CPU, en las que el parseo y el procesamiento consumen más tiempo que la E/S.

Procesamiento en paralelo con rayon
use rayon::prelude::*;
use serde::{Deserialize, Serialize};
use std::fs::File;
use std::io::{BufRead, BufReader, BufWriter, Write};


#[derive(Debug, Deserialize, Serialize)]
struct Record {
    id: u64,
    text: String,
    #[serde(default)]
    word_count: Option<usize>,
}


fn parallel_process_jsonl(
    input_path: &str,
    output_path: &str,
) -> anyhow::Result<usize> {
    // Step 1: Read all lines into memory
    let file = File::open(input_path)?;
    let reader = BufReader::new(file);
    let lines: Vec<String> = reader.lines().collect::<Result<_, _>>()?;


    // Step 2: Parse and transform in parallel
    let processed: Vec<Record> = lines
        .par_iter()
        .filter(|line| !line.trim().is_empty())
        .filter_map(|line| {
            serde_json::from_str::<Record>(line.trim()).ok()
        })
        .map(|mut record| {
            record.word_count = Some(record.text.split_whitespace().count());
            record
        })
        .collect();


    // Step 3: Write results
    let file = File::create(output_path)?;
    let mut writer = BufWriter::new(file);
    let count = processed.len();


    for record in &processed {
        serde_json::to_writer(&mut writer, record)?;
        writer.write_all(b"\n")?;
    }
    writer.flush()?;


    Ok(count)
}


fn main() -> anyhow::Result<()> {
    let count = parallel_process_jsonl("input.jsonl", "output.jsonl")?;
    println!("Processed {} records in parallel", count);
    Ok(())
}

Este patrón lee todas las líneas, las procesa en paralelo con par_iter() de rayon y escribe los resultados de forma secuencial. En la fase paralela, el parseo y la transformación se reparten entre todos los núcleos de CPU disponibles. Si el archivo cabe en memoria, la mejora de velocidad puede ser casi proporcional al número de núcleos. Para archivos muy grandes, considera dividir la entrada en bloques para equilibrar el consumo de memoria y el paralelismo.

E/S asíncrona con tokio

Cuando el procesamiento de JSONL incluye E/S de red, como leer desde endpoints HTTP o escribir en almacenamiento remoto, el runtime asíncrono de tokio te permite realizar cálculos mientras esperas a que terminen las operaciones de E/S. El trait tokio::io::AsyncBufReadExt ofrece un método lines() asíncrono equivalente al de la API síncrona de BufReader.

E/S asíncrona con tokio
use tokio::fs::File;
use tokio::io::{AsyncBufReadExt, BufReader};
use serde::Deserialize;


#[derive(Debug, Deserialize)]
struct ApiRecord {
    id: u64,
    url: String,
    status: String,
}


async fn read_jsonl_async(path: &str) -> anyhow::Result<Vec<ApiRecord>> {
    let file = File::open(path).await?;
    let reader = BufReader::new(file);
    let mut lines = reader.lines();
    let mut records = Vec::new();


    while let Some(line) = lines.next_line().await? {
        let trimmed = line.trim().to_string();
        if trimmed.is_empty() {
            continue;
        }
        let record: ApiRecord = serde_json::from_str(&trimmed)?;
        records.push(record);
    }


    Ok(records)
}


async fn write_jsonl_async(
    path: &str,
    records: &[ApiRecord],
) -> anyhow::Result<()> {
    use tokio::io::AsyncWriteExt;


    let mut file = File::create(path).await?;
    for record in records {
        let json = serde_json::to_string(record)?;
        file.write_all(json.as_bytes()).await?;
        file.write_all(b"\n").await?;
    }
    file.flush().await?;
    Ok(())
}


#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let records = read_jsonl_async("api_logs.jsonl").await?;
    println!("Read {} async records", records.len());
    write_jsonl_async("output.jsonl", &records).await?;
    Ok(())
}

El enfoque asíncrono aporta más ventajas cuando se combina con operaciones de red. Si solo lees y escribes archivos en discos locales, BufReader síncrono suele ser más rápido, ya que la ejecución asíncrona añade sobrecarga al planificar las tareas. Usa tokio cuando necesites leer JSONL desde streams HTTP, buckets de S3 u otras fuentes de red en las que la latencia de E/S sea el factor dominante.

Manejo de errores: Result y el operador ?

El tipo Result de Rust y el operador ? ofrecen un patrón claro para manejar errores al procesar JSONL, fácil de combinar con otras operaciones. En lugar de usar bloques try-catch, cada operación que puede fallar devuelve un Result que puedes propagar con ? o manejar localmente con match. Así, los posibles errores quedan explícitos y no se pueden ignorar por accidente.

Manejo de errores: Result y el operador ?
use serde::Deserialize;
use std::fs::File;
use std::io::{BufRead, BufReader};
use thiserror::Error;


#[derive(Error, Debug)]
enum JsonlError {
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
    #[error("JSON parse error at line {line}: {source}")]
    Parse {
        line: usize,
        source: serde_json::Error,
    },
    #[error("Validation error at line {line}: {message}")]
    Validation {
        line: usize,
        message: String,
    },
}


#[derive(Debug, Deserialize)]
struct Record {
    id: u64,
    name: String,
    value: f64,
}


fn validate_record(record: &Record, line: usize) -> Result<(), JsonlError> {
    if record.name.is_empty() {
        return Err(JsonlError::Validation {
            line,
            message: "name cannot be empty".into(),
        });
    }
    if record.value < 0.0 {
        return Err(JsonlError::Validation {
            line,
            message: format!("value must be non-negative, got {}", record.value),
        });
    }
    Ok(())
}


fn process_jsonl_with_errors(
    path: &str,
) -> Result<Vec<Record>, JsonlError> {
    let file = File::open(path)?; // Io error auto-converted via #[from]
    let reader = BufReader::new(file);
    let mut records = Vec::new();


    for (idx, line) in reader.lines().enumerate() {
        let line_num = idx + 1;
        let line = line?; // Propagate I/O errors
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }


        let record: Record = serde_json::from_str(trimmed)
            .map_err(|e| JsonlError::Parse { line: line_num, source: e })?;


        validate_record(&record, line_num)?;
        records.push(record);
    }


    Ok(records)
}


fn main() {
    match process_jsonl_with_errors("data.jsonl") {
        Ok(records) => println!("Successfully processed {} records", records.len()),
        Err(JsonlError::Io(e)) => eprintln!("File error: {}", e),
        Err(JsonlError::Parse { line, source }) => {
            eprintln!("JSON error at line {}: {}", line, source);
        }
        Err(JsonlError::Validation { line, message }) => {
            eprintln!("Validation error at line {}: {}", line, message);
        }
    }
}

Este patrón define con thiserror un enum de errores personalizado que contempla todos los posibles fallos: errores de E/S, errores de parseo de JSON con números de línea y errores de validación propios del dominio. El atributo #[from] permite convertir automáticamente los errores de std::io::Error, y el operador ? los propaga por la pila de llamadas. Cada variante de error incluye contexto suficiente para generar un mensaje de diagnóstico claro y localizar exactamente la línea que causó el problema.

Crates de Rust para procesar JSON

El ecosistema de Rust ofrece varios crates para parsear JSON con distintas características de rendimiento. serde_json es la opción habitual, mientras que simd-json y sonic-rs llevan el rendimiento más allá mediante instrucciones SIMD.

serde_json

Estándar

El estándar de facto para trabajar con JSON en Rust. Se integra directamente con las macros derive de serde para serializar sin escribir código repetitivo. Es una excelente opción para la mayoría de las cargas de trabajo con JSONL: ofrece sólidas garantías de seguridad de tipos, mensajes de error detallados y un amplio soporte en el ecosistema.

simd-json

El más rápido

Una adaptación de simdjson a Rust que usa instrucciones SIMD para parsear JSON a varios gigabytes por segundo. Requiere búferes de entrada mutables y su API es distinta de la de serde_json, pero puede ser 2-4x más rápido en cargas de trabajo donde predomina el parseo. Es especialmente adecuado para pipelines que procesan grandes volúmenes de datos por segundo.

sonic-rs

SIMD + serde

Una biblioteca de JSON acelerada mediante SIMD con una API compatible con serde. Su objetivo es combinar la velocidad de simd-json con la facilidad de uso de serde_json. Admite tanto el parseo diferido como el inmediato, por lo que es una buena opción si necesitas rendimiento sin reescribir tu código.

Trabaja con archivos JSONL online

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. No necesitas subir archivos: es 100% privado.

Preguntas frecuentes

Referencias