JSONL en Rust : serde_json, BufReader et abstractions à coût nul
Un guide complet pour manipuler des fichiers JSONL (JSON Lines) en Rust. Apprenez à lire, écrire, parser et traiter en streaming des données JSONL avec serde_json, BufReader, rayon pour le parallélisme et tokio pour les E/S asynchrones.
Pourquoi choisir Rust pour le JSONL ?
Rust est un excellent choix pour traiter du JSONL lorsque les performances, la sûreté mémoire et la fiabilité du code sont essentielles. Son modèle de propriété élimine les accès concurrents non synchronisés aux données dès la compilation. Ses abstractions à coût nul permettent d’écrire des chaînes d’itérateurs de haut niveau qui, une fois compilées, deviennent des boucles optimisées. Quant à serde_json, c’est l’un des parseurs JSON les plus rapides, tous langages confondus. Si vous développez un pipeline de données qui doit traiter des millions d’enregistrements JSONL par seconde, Rust vous donne la maîtrise nécessaire pour y parvenir sans sacrifier la sûreté.
Le format JSONL (JSON Lines) stocke un objet JSON par ligne, ce qui le rend idéal pour le streaming, les journaux en ajout uniquement et le traitement de grands jeux de données. BufReader lit les fichiers ligne par ligne sans les charger entièrement en mémoire, et le modèle d’itérateurs de Rust se prête parfaitement à cette organisation du JSONL. Ce guide vous explique comment lire et écrire du JSONL avec BufReader, désérialiser les enregistrements en structures fortement typées avec serde, les traiter en parallèle avec rayon, gérer les E/S asynchrones avec tokio et mettre en place une gestion robuste des erreurs avec Result et l’opérateur ?.
Lire des fichiers JSONL avec BufReader
La bibliothèque standard de Rust propose BufReader pour lire efficacement les fichiers grâce à une mise en tampon. Associé à l’itérateur lines(), il permet de lire les fichiers JSONL ligne par ligne avec une très faible surcharge mémoire. Chaque ligne est parsée indépendamment, ce qui rend cette approche adaptée aux fichiers de toute taille.
L’approche la plus simple consiste à envelopper un File dans un BufReader, à parcourir les lignes avec lines() et à parser chacune d’elles avec serde_json. Une seule ligne est ainsi conservée en mémoire à la fois, quelle que soit la taille du fichier.
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; // Ignorer les lignes vides
}
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(())
}Ajoutez serde et serde_json à votre Cargo.toml. La fonctionnalité derive active les macros de dérivation Serialize et Deserialize pour définir des structures typées.
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
# Optionnel : pour le traitement parallele
rayon = "1.10"
# Optionnel : pour les E/S asynchrones
tokio = { version = "1", features = ["full"] }Parser avec la sûreté du typage grâce à serde_json
Les macros de dérivation de serde sont l’un des grands atouts de Rust pour le traitement du JSONL : elles permettent de désérialiser chaque ligne JSON directement en une structure fortement typée. Le compilateur vérifie que votre code manipule correctement les données et détecte les incompatibilités de types, les champs manquants et les erreurs de structure dès la compilation, plutôt qu’à l’exécution.
Définissez une structure avec Deserialize, puis utilisez serde_json::from_str pour désérialiser chaque ligne JSONL en une instance de cette structure. Les champs manquants ou mal formés produisent des messages d’erreur clairs lors du parsing, au lieu de provoquer des panics plus tard dans le programme.
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(())
}Lorsque les enregistrements JSONL suivent des schémas différents, serde_json::Value permet d’accéder aux données avec souplesse. Vous pouvez accéder aux valeurs par indexation entre crochets ou utiliser les méthodes as_str(), as_i64() pour effectuer des conversions de types sûres.
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)?;
// Acces dynamique aux champs
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);
}
// Verifier si un champ existe
if value.get("email").is_some() {
println!("Has email field");
}
}
Ok(())
}Écrire des fichiers JSONL en Rust
L’écriture de JSONL suit le chemin inverse de la lecture : sérialisez chaque enregistrement en une chaîne JSON, ajoutez un retour à la ligne et écrivez le tout dans un fichier. BufWriter et serde_json::to_string permettent de concilier exactitude du résultat et performances.
Sérialisez chaque structure avec serde_json::to_string(), puis écrivez le résultat suivi d’un retour à la ligne. La macro de dérivation Serialize se charge automatiquement de convertir vos types Rust en JSON.
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(())
}Pour écrire de gros fichiers JSONL, enveloppez le File dans un BufWriter afin de réduire le nombre d’appels système. Les petites écritures sont ainsi regroupées dans un tampon, puis envoyées par blocs plus volumineux, ce qui améliore considérablement le débit.
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(())
}Traitement parallèle avec rayon
La crate rayon permet de paralléliser le traitement des données en Rust avec très peu de modifications du code. En appelant par_iter() à la place de iter(), vous laissez rayon répartir automatiquement le travail sur tous les cœurs du processeur grâce à un pool de threads utilisant le vol de travail. Cette approche est particulièrement efficace pour les transformations JSONL limitées par le processeur, où le parsing et le traitement prennent plus de temps que les E/S.
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> {
// Etape 1 : Lire toutes les lignes en memoire
let file = File::open(input_path)?;
let reader = BufReader::new(file);
let lines: Vec<String> = reader.lines().collect::<Result<_, _>>()?;
// Etape 2 : Analyser et transformer en parallele
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();
// Etape 3 : Ecrire les resultats
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(())
}Cette approche consiste à lire toutes les lignes, à les traiter en parallèle avec par_iter() de rayon, puis à écrire les résultats de manière séquentielle. Le parsing et les transformations sont répartis sur tous les cœurs disponibles du processeur. Pour les fichiers qui tiennent en mémoire, le gain de vitesse peut être presque proportionnel au nombre de cœurs. Pour les fichiers très volumineux, envisagez de découper les données d’entrée en blocs afin de trouver un équilibre entre consommation mémoire et parallélisme.
E/S asynchrones avec tokio
Lorsque votre traitement JSONL fait intervenir des E/S réseau, par exemple pour lire des données depuis des endpoints HTTP ou écrire vers un stockage distant, le runtime asynchrone de tokio permet d’effectuer des calculs pendant les temps d’attente des E/S. Le trait tokio::io::AsyncBufReadExt fournit une méthode lines() asynchrone qui reprend le fonctionnement de l’API synchrone de BufReader.
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(())
}L’approche asynchrone est surtout intéressante lorsqu’elle s’accompagne d’opérations réseau. Pour de simples E/S sur des fichiers stockés sur un disque local, le BufReader synchrone est souvent plus rapide, car l’asynchrone ajoute un surcoût lié à l’ordonnancement des tâches. Utilisez tokio pour lire du JSONL depuis des flux HTTP, des buckets S3 ou d’autres sources réseau lorsque la latence des E/S est prépondérante.
Gestion des erreurs : Result et l’opérateur ?
Le type Result de Rust et l’opérateur ? permettent de gérer les erreurs de traitement JSONL de manière claire et composable. Au lieu d’utiliser des blocs try-catch, chaque opération susceptible d’échouer renvoie un Result, que vous pouvez propager avec ? ou traiter localement avec match. Les cas d’erreur sont ainsi explicites et ne peuvent pas être ignorés par inadvertance.
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)?; // Erreur E/S auto-convertie 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?; // Propager les erreurs d'E/S
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);
}
}
}Cette approche définit avec thiserror une énumération d’erreurs personnalisée qui couvre tous les cas d’échec : erreurs d’E/S, erreurs de parsing JSON accompagnées des numéros de ligne et erreurs de validation propres au domaine métier. L’attribut #[from] permet la conversion automatique depuis std::io::Error, et l’opérateur ? propage les erreurs en remontant la pile d’appels. Chaque variante d’erreur contient suffisamment de contexte pour produire un diagnostic clair et identifier précisément la ligne à l’origine du problème.
Crates Rust pour le traitement du JSON
L’écosystème Rust propose plusieurs crates de parsing JSON aux profils de performances différents. serde_json est le choix de référence, tandis que simd-json et sonic-rs vont encore plus loin en exploitant les instructions SIMD.
serde_json
StandardLe standard de fait pour le JSON en Rust. Son intégration aux macros de dérivation de serde permet de sérialiser les données sans code répétitif. C’est un excellent choix pour la plupart des traitements JSONL, grâce à la sûreté du typage, à des messages d’erreur détaillés et à une large prise en charge dans l’écosystème.
simd-json
Le plus rapideUn portage en Rust de simdjson qui utilise les instructions SIMD pour parser du JSON à plusieurs gigaoctets par seconde. Il nécessite des tampons d’entrée mutables et propose une API différente de celle de serde_json, mais peut être 2 à 4 fois plus rapide lorsque le parsing représente l’essentiel du traitement. Il convient particulièrement aux pipelines à haut débit.
sonic-rs
SIMD + serdeUne bibliothèque JSON accélérée par SIMD, dotée d’une API compatible avec serde. Elle vise à associer la vitesse de simd-json à l’ergonomie de serde_json. Elle propose un parsing à la demande ou immédiat, ce qui en fait un bon choix pour gagner en performances sans réécrire votre code.
Essayez nos outils JSONL gratuits
Pas envie d’écrire du code ? Utilisez nos outils en ligne gratuits pour visualiser, valider et convertir des fichiers JSONL directement dans votre navigateur.
Les stratégies pour traiter des gigaoctets de données JSONL : lecture en streaming, gestion de la mémoire, découpage des fichiers, compression et outils en ligne.
Apprenez à utiliser JSONL comme format d’échange dans vos pipelines ETL : streaming avec Apache Kafka, DAG Airflow, chargement dans Snowflake et BigQuery, et conception de pipelines tolérants aux pannes.
Maîtrisez les bonnes pratiques JSONL : mise en forme, cohérence des schémas, gestion des erreurs, optimisation des performances et organisation des fichiers. Des exemples concrets vous aident à éviter les pièges courants.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Un guide complet pour manipuler des fichiers JSONL en Go. Découvrez bufio.Scanner, json.Decoder, les modèles de programmation concurrente avec les goroutines, la gestion des erreurs et la création de pipelines de données performants.