Por Jerry Fan

JSONL em Python: leitura, escrita e parsing

Um guia completo para trabalhar com arquivos JSONL (JSON Lines) em Python. Aprenda a ler, escrever, fazer o parsing e processar dados JSONL em streaming com módulos nativos, pandas e bibliotecas de alto desempenho.

Por que usar Python para trabalhar com JSONL?

Python é a linguagem mais popular para trabalhar com arquivos JSONL, e há bons motivos para isso. O módulo json da biblioteca padrão já oferece tudo o que você precisa para fazer o parsing de JSON, a iteração sobre arquivos usa a memória de forma eficiente por padrão e o ecossistema conta com bibliotecas poderosas, como pandas e orjson, para necessidades específicas. Seja para processar conjuntos de dados de aprendizado de máquina, logs de aplicações ou respostas de APIs, Python facilita o trabalho com JSONL.

JSONL (JSON Lines) armazena um objeto JSON por linha, o que torna o formato ideal para streaming, gravação de logs apenas por acréscimo e processamento de grandes conjuntos de dados sem carregar tudo na memória. A leitura de arquivos linha a linha do Python se encaixa perfeitamente nesse formato. Neste guia, você aprenderá três formas de ler JSONL, duas formas de escrever nesse formato e como lidar com arquivos que não cabem na memória.

Como ler arquivos JSONL em Python

Há várias formas de ler arquivos JSONL em Python, cada uma indicada para um caso de uso. O módulo json da biblioteca padrão atende à maioria dos cenários, pandas facilita a análise de dados tabulares e geradores são a melhor opção para arquivos grandes.

A forma mais simples é usar o módulo json da biblioteca padrão do Python. Abra o arquivo, percorra as linhas e faça o parsing de cada uma com json.loads(). Essa abordagem carrega todos os registros em uma lista na memória.

Leitura básica com o módulo json
import json


records = []
with open('data.jsonl', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.strip()
        if line:  # Skip empty lines
            records.append(json.loads(line))


print(f'Loaded {len(records)} records')
print(records[0])

Se os seus dados JSONL forem tabulares (com as mesmas chaves em todos os registros), pandas pode carregá-los diretamente em um DataFrame com uma única chamada de função. Essa é a forma mais rápida de começar a analisar dados JSONL estruturados.

Leitura com pandas
import pandas as pd


# Read entire file into a DataFrame
df = pd.read_json('data.jsonl', lines=True)
print(df.head())
print(f'Shape: {df.shape}')


# For large files, read in chunks
chunks = pd.read_json('large.jsonl', lines=True, chunksize=10000)
for chunk in chunks:
    # Process each chunk (DataFrame)
    print(f'Chunk shape: {chunk.shape}')

Para arquivos que não cabem na memória, use uma função geradora. Ela fornece um registro por vez, mantendo o uso de memória constante, independentemente do tamanho do arquivo. Esse é o padrão recomendado para pipelines de dados em produção.

Uso de geradores para arquivos grandes
import json
from typing import Iterator, Any


def read_jsonl(path: str) -> Iterator[dict[str, Any]]:
    """Read a JSONL file lazily, yielding one record at a time."""
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                yield json.loads(line)
            except json.JSONDecodeError as e:
                print(f'Skipping invalid JSON at line {line_num}: {e}')


# Process records one at a time
for record in read_jsonl('large_data.jsonl'):
    process(record)  # Only one record in memory at a time

Como escrever arquivos JSONL em Python

Escrever arquivos JSONL é simples: serialize cada registro como uma string JSON e acrescente um caractere de nova linha. A regra principal é manter um objeto JSON por linha, sem vírgulas no final e sem colocar os objetos dentro de um array.

Use json.dumps() para serializar cada registro e grave o resultado seguido de uma nova linha. Defina ensure_ascii=False para preservar na saída os caracteres Unicode, como caracteres chineses, japoneses e emojis.

Escrita básica com o módulo json
import json


records = [
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
]


with open('output.jsonl', 'w', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


print(f'Wrote {len(records)} records to output.jsonl')

Se os seus dados já estiverem em um DataFrame do pandas, use to_json() com orient='records' e lines=True para exportá-los diretamente como JSONL. Essa é a operação inversa de pd.read_json() com lines=True.

Escrita com pandas
import pandas as pd


df = pd.DataFrame([
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
])


# Write DataFrame to JSONL
df.to_json('output.jsonl', orient='records', lines=True, force_ascii=False)


print(f'Wrote {len(df)} records to output.jsonl')

Bibliotecas Python para trabalhar com JSONL

Python oferece várias bibliotecas para fazer o parsing de JSON, com diferentes níveis de desempenho. A escolha depende do tamanho do arquivo e dos seus requisitos de desempenho.

json (stdlib)

Nativo

O módulo json faz parte da biblioteca padrão do Python, dispensa instalação e funciona em qualquer ambiente. Ele atende à maioria das necessidades de processamento de JSONL e oferece suporte a todos os tipos padrão de JSON. O desempenho é adequado para arquivos de até algumas centenas de MB.

orjson

Mais rápida

orjson é a biblioteca JSON mais rápida para Python e é escrita em Rust. O parsing e a serialização são 2-10x mais rápidos do que no módulo json da biblioteca padrão. Ela retorna bytes em vez de strings e oferece suporte nativo a dataclasses, datetime, numpy e tipos UUID.

ujson

Rápida

ujson (UltraJSON) é uma biblioteca JSON escrita em C, 2-5x mais rápida que o módulo json da biblioteca padrão. Sua API é quase idêntica à desse módulo, o que permite usá-la como substituta direta. É um bom equilíbrio entre compatibilidade e velocidade.

Processamento de arquivos JSONL grandes em streaming

Para processar arquivos JSONL de vários gigabytes, você precisa de uma abordagem de streaming que leia, transforme e grave os dados em lotes. Isso mantém o uso de memória constante e permite acompanhar o progresso.

Processamento de arquivos JSONL grandes em streaming
import json
import sys


def process_large_jsonl(
    input_path: str,
    output_path: str,
    batch_size: int = 1000
) -> int:
    """Stream-process a large JSONL file in batches."""
    processed = 0
    batch: list[dict] = []


    with open(input_path, 'r') as fin, \
         open(output_path, 'w') as fout:
        for line in fin:
            line = line.strip()
            if not line:
                continue
            record = json.loads(line)
            # Transform the record
            record['processed'] = True
            batch.append(record)


            if len(batch) >= batch_size:
                for r in batch:
                    fout.write(json.dumps(r) + '\n')
                processed += len(batch)
                batch.clear()
                print(f'\rProcessed {processed} records...', end='')


        # Write remaining records
        for r in batch:
            fout.write(json.dumps(r) + '\n')
        processed += len(batch)


    print(f'\nDone. Processed {processed} records total.')
    return processed


# Usage
process_large_jsonl('input.jsonl', 'output.jsonl', batch_size=5000)

Essa abordagem mantém o uso de memória constante ao processar os registros em lotes de tamanho fixo. O parâmetro batch_size controla o equilíbrio entre o uso de memória e a eficiência de I/O. Na maioria dos sistemas, lotes de 1.000 a 10.000 registros funcionam bem. O indicador de progresso ajuda a acompanhar tarefas demoradas.

Trabalhe com arquivos JSONL online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no navegador. Sem precisar enviar arquivos, com 100% de privacidade.

Perguntas frequentes

Referências