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.
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.
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.
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 timeComo 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.
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.
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)
NativoO 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ápidaorjson é 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ápidaujson (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.
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.
Experimente nossas ferramentas gratuitas para JSONL
Não quer escrever código? Use nossas ferramentas online gratuitas para visualizar, validar e converter arquivos JSONL diretamente no navegador.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Domine as boas práticas de JSONL para formatação, consistência de schema, tratamento de erros, otimização de desempenho e organização de arquivos. Evite problemas comuns com exemplos práticos.
Converta arquivos JSONL em um array JSON padrão. Ideal para APIs e pipelines de processamento de dados.
Aprenda a usar o formato JSONL em JavaScript e Node.js.