Por Jerry Fan

Como trabalhar com arquivos JSONL grandes (1GB+)

Estratégias e boas práticas para processar dados JSONL na escala de gigabytes com eficiência

Por que arquivos JSONL grandes exigem cuidados específicos

Fazer o parsing de um arquivo JSONL inteiro para dicionários Python ou objetos JavaScript pode exigir muito mais memória do que seu tamanho em disco. O consumo adicional depende da quantidade de registros, dos nomes dos campos, dos valores e do ambiente de execução. Meça com um arquivo representativo em vez de presumir um multiplicador fixo de memória.

A principal vantagem do JSONL em relação ao JSON convencional é permitir o processamento linha por linha. Cada linha é um documento JSON independente, então você nunca precisa carregar o arquivo inteiro. Essa capacidade de processamento em streaming faz do JSONL o formato preferido para grandes conjuntos de dados em aprendizado de máquina, análise de logs e engenharia de dados.

Estratégias de leitura em streaming

A base para trabalhar com arquivos JSONL grandes é ler o arquivo linha por linha e processar cada registro separadamente. Veja como fazer isso com linguagens e ferramentas populares.

A iteração sobre arquivos em Python lê uma linha por vez. O uso de memória depende da maior linha e dos dados que seu código de processamento mantém; um único registro muito grande ainda pode esgotar a memória.

Python
import json


def process_large_jsonl(filepath: str) -> int:
    """Process a large JSONL file line by line."""
    count = 0
    errors = 0
    
    with open(filepath, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                record = json.loads(line)
                # Process your record here
                count += 1
            except json.JSONDecodeError as e:
                errors += 1
                print(f'Line {line_num}: {e}')
    
    print(f'Processed {count} records, {errors} errors')
    return count

A interface readline do Node.js permite processar arquivos linha por linha de forma eficiente usando streams, com consumo mínimo de memória mesmo em arquivos de vários gigabytes.

Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


async function processLargeJsonl(filepath) {
  const rl = createInterface({
    input: createReadStream(filepath, 'utf-8'),
    crlfDelay: Infinity,
  });


  let count = 0;
  for await (const line of rl) {
    const trimmed = line.trim();
    if (!trimmed) continue;
    try {
      const record = JSON.parse(trimmed);
      // Process your record here
      count++;
    } catch (err) {
      console.error(`Parse error: ${err.message}`);
    }
  }
  console.log(`Processed ${count} records`);
}

As ferramentas de linha de comando do Unix são ideais para inspecionar e processar arquivos JSONL grandes rapidamente, sem precisar escrever código.

Ferramentas de linha de comando
# Count lines in a JSONL file
wc -l data.jsonl


# View first 10 records
head -n 10 data.jsonl


# View last 5 records
tail -n 5 data.jsonl


# Pretty-print first record
head -n 1 data.jsonl | jq .


# Filter records with jq
jq -c 'select(.age > 30)' data.jsonl


# Extract specific fields
jq -c '{name, email}' data.jsonl

Técnicas de gerenciamento de memória

Além da leitura linha por linha, estas técnicas ajudam você a processar arquivos JSONL grandes com mais eficiência.

Processe os registros em lotes de 1.000 a 10.000 para equilibrar o consumo de memória e a eficiência do processamento. Isso é especialmente útil ao gravar dados em bancos de dados ou fazer chamadas de API.

Processamento em lotes
import json
from typing import Iterator


def read_jsonl_batches(
    filepath: str,
    batch_size: int = 5000
) -> Iterator[list]:
    batch = []
    with open(filepath, 'r') as f:
        for line in f:
            record = json.loads(line.strip())
            batch.append(record)
            if len(batch) >= batch_size:
                yield batch
                batch = []
    if batch:
        yield batch


# Usage
for batch in read_jsonl_batches('large.jsonl'):
    # Insert batch into database
    db.insert_many(batch)

Monitore o consumo de memória durante o processamento para identificar problemas logo no início e ajustar o tamanho dos lotes.

Monitoramento do uso de memória
import json
import psutil
import os


def process_with_monitoring(filepath: str):
    process = psutil.Process(os.getpid())
    
    with open(filepath, 'r') as f:
        for i, line in enumerate(f):
            record = json.loads(line)
            # Process record
            
            if i % 100000 == 0:
                mem = process.memory_info().rss / 1024 / 1024
                print(f'Line {i:,}: {mem:.1f} MB')

Como dividir arquivos JSONL grandes

Às vezes, você precisa dividir um arquivo JSONL grande em partes menores para processá-las em paralelo, enviá-las a serviços com limites de tamanho ou distribuir o trabalho entre várias máquinas.

Use split -l para preservar linhas completas. Não use split -b para criar partes JSONL que possam ser usadas de forma independente: um corte por bytes pode dividir um registro JSON ou um caractere UTF-8 ao meio. Os comandos abaixo criam um novo diretório e param se ele já existir.

Usando o comando split
# Split into parts of 100,000 complete lines in a NEW directory
mkdir jsonl-parts &&
split -l 100000 data.jsonl jsonl-parts/chunk_ &&
for f in jsonl-parts/chunk_*; do
    [ -f "$f" ] || continue
    mv "$f" "$f.jsonl"
done

Esta alternativa em Python divide pelo número de linhas e preserva os bytes de entrada, incluindo caracteres UTF-8 e finais de linha. Ela cria um novo diretório de saída e se recusa a sobrescrever um existente. Valide a entrada primeiro: dividir o arquivo não corrige registros inválidos.

Script em Python
from pathlib import Path


def split_jsonl(input_path, output_dir="jsonl-parts", lines_per_file=100000):
    if lines_per_file < 1:
        raise ValueError("lines_per_file must be positive")
    directory = Path(output_dir)
    file_num = 0
    output = None
    with open(input_path, "rb") as source:
        directory.mkdir()  # Refuse to overwrite an existing directory
        try:
            for line_number, line in enumerate(source):
                if line_number % lines_per_file == 0:
                    if output is not None:
                        output.close()
                    file_num += 1
                    output = (directory / f"part_{file_num:04d}.jsonl").open("xb")
                output.write(line)
        finally:
            if output is not None:
                output.close()
    print(f"Split into {file_num} files")


split_jsonl("data.jsonl")

Estratégias de compressão

JSONL costuma ter boa compressão quando os registros repetem nomes de campos e valores. A economia depende do conjunto de dados, do nível de compressão e do codec; meça o tamanho compactado e o tempo de processamento com uma amostra representativa.

O módulo gzip do Python permite trabalhar com arquivos JSONL compactados de forma transparente. A extensão .gz é uma convenção reconhecida automaticamente pelas ferramentas.

Leitura e gravação de JSONL compactado com gzip
import gzip
import json


# Reading gzipped JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        # Process record


# Writing gzipped JSONL
with gzip.open('output.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record) + '\n')

Comparação de métodos de compressão

Escolha um codec pela compatibilidade e pelo desempenho medido com seus próprios dados. Os pontos abaixo apresentam vantagens e limitações, não resultados de benchmark:

gzip: amplamente compatível; uma escolha prática para trocar arquivos JSONL compactados.

zstd: oferece níveis de compressão ajustáveis; compare o tamanho e a taxa de processamento com gzip na sua carga de trabalho.

lz4: desenvolvido para compressão e descompressão rápidas; meça o impacto dessa escolha no tamanho com seus dados.

Sem compressão: dispensa o trabalho de descompressão, mas usa mais armazenamento; útil quando você precisa de acesso direto aos bytes.

Como processar arquivos grandes no navegador

O jsonl.co lê arquivos JSONL localmente no seu navegador. O visualizador percorre os arquivos em blocos e usa rolagem virtual para não renderizar todos os registros de uma vez. O conteúdo dos seus arquivos não é enviado para servidores.

O tamanho de arquivo que pode ser processado depende da memória do navegador, dos recursos do dispositivo, do tamanho dos registros e da operação. Ler a entrada em streaming não garante um uso de memória limitado para a saída: a conversão para Excel, por exemplo, acumula linhas e monta a pasta de trabalho na memória. Teste primeiro com uma amostra menor e divida os arquivos quando necessário.

Trabalhe com arquivos JSONL grandes online

Inspecione JSONL localmente com o visualizador do navegador. Para cargas de trabalho maiores, divida o arquivo ou use os scripts acima que processam uma linha por vez.

Perguntas frequentes

Referências