JSON Toolkit

Ler JSON grande em Node.js: parsing em streaming com stream-json e contrapressão na prática

Resumo: Ler um array JSON de 186MB com readFileSync e JSON.parse leva a memória ao pico de 612MB; trocar pelo streamArray do stream-json mantém a curva plana em 104MB. Este artigo compara quatro estratégias de leitura com medições, explica por que for await produz contrapressão naturalmente, como o evento data a perde e como ajustar highWaterMark e drain no lado da escrita.

Intermédio~5 min de leituraPublicado em 2026-11-17Atualizado em 2026-11-17
Streaming de um ficheiro JSON grande em Node.js: comparação entre streamArray e contrapressão

Quando importar um ficheiro JSON de 186MB empurra o processo para 600MB de memória, o culpado não é o tamanho do ficheiro — o JSON.parse trocou o texto inteiro por todo o grafo de objetos de uma só vez. Mude a estratégia de leitura e a curva de memória fica plana.

Um sintoma: ficheiro de 186MB com pico de 612MB

As tarefas de importação do lado do servidor são o terreno onde este problema mais aparece: sincronizações agendadas de encomendas, limpeza de logs, carregamento de histórico em massa. A implementação típica tem este aspeto:

const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);

Medimos este padrão no Node 22.13. A amostra: um array de objetos com 480 000 registos de encomendas, ficheiro de 186MB com strings, objetos aninhados e arrays nos campos, imitando estruturas reais. Pico do Maximum resident set size medido com /usr/bin/time -v: a leitura leva 1.3 segundos, mas o RSS atinge 612MB — 3.3 vezes o ficheiro. Com o limite predefinido do espaço antigo da V8 em 1.4–2GB, algumas tarefas destas em paralelo bastam para o contêiner morrer por OOM Kill.

A aritmética não é exótica: o texto bruto ocupa uma cópia na memória (cerca de 186MB), o grafo de objetos resultante do parse ocupa outra (cada chave string, cada cabeçalho de objeto aninhado e cada array tem custo), e o próprio processo de parsing aloca transitoriamente por cima. Chegar a 600MB de pico é normal.

Segunda causa: o JSON.parse troca texto inteiro por grafo inteiro

O contrato do JSON.parse é «dá-me o texto completo, devolvo-te o grafo completo». Exige que todo o texto esteja no lugar antes de começar e só entrega o resultado no fim. Não existe mecanismo para «aqui vão primeiro os primeiros 1 000 registos».

O custo do grafo de objetos foi medido item por item em A conta de memória do JSON: cada string ocupa espaço real, cada chave de objeto toma um slot, e a largura de um array depende dos tipos dos elementos. Uma dezena de MB de JSON torna-se rotineiramente três a cinco vezes maior depois do parsing, com o pico por cima.

Mas a maioria das importações nunca precisa do grafo inteiro: inserir linha por linha, filtrar linha por linha, transformar linha por linha — cada registo pode ser libertado assim que tratado. O que a tarefa precisa é de «parse de um registo, entrega de um registo». É precisamente a definição de parsing em streaming.

A solução: streamArray consome registo a registo, e o for await oferece contrapressão

O stream-json implementa o parser como um Transform stream que consome tokens e nunca espera pelo ficheiro inteiro. Quando o nível de topo é um array, o streamArray() emite {key, value} no instante em que cada elemento termina de ser parseado:

const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');

async function importOrders(filePath) {
  const pipeline = chain([
    fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
    parser(),
    streamArray(),
  ]);
  for await (const { key, value } of pipeline) {
    await saveToDb(value);
  }
}

No mesmo ficheiro de 186MB com os mesmos 480 000 registos, esta versão atinge um pico de RSS de 104MB, plano durante toda a execução. Existem em memória apenas «o elemento atual + o estado do parser»; os registos terminados são recuperados imediatamente.

Um detalhe fácil de perder: o for await não puxa o próximo registo do parser até saveToDb terminar, por isso o parser deixa de ler o ficheiro. Base de dados mais lenta, leitura mais lenta — isso é contrapressão, formada naturalmente, sem uma linha de código extra. Um artigo do dev.to sobre a ingestão de um feed municipal de 4GB usa a mesma cadeia com pick({filter:'data'}) e relata uma curva de memória igualmente plana.

Quando o lado da escrita falha: um evento data sem pausa empurra a memória de volta

O parsing em streaming só disciplina a leitura. Se a escrita não aceitar a contrapressão, a memória sobe de novo. A falha clássica: escritas assíncronas num handler de data sem olhar para o buffer do writable:

// Errado: evento data + escrita assíncrona, contrapressão totalmente perdida
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // o stream não espera; o buffer continua a crescer
});

No modo data o stream continua a fluir, por mais lento que seja o slowWrite, e tudo se acumula no buffer interno do writable. Na mesma amostra de 186MB, dirigimos os registos a um Writable lento que atrasa 1ms em cada centésimo bloco. Ignorando a contrapressão, o RSS chegou ao pico de 407MB; suspendendo com await once(sink, 'drain') quando write() devolve false, 161MB. A diferença de 246MB são literalmente dados sentados no buffer de escrita.

// Correto: pausar quando write() devolve false, retomar no drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Duas notas de campo: ao montar cadeias de streams à mão, defina highWaterMark explicitamente em cada stream — o valor predefinido de 16 em objectMode é demasiado generoso para objetos grandes; e prefira pipeline() de stream/promises em vez de pipe(), que trata da propagação de erros e da limpeza.

As medições: pico de memória de quatro estratégias

Estratégia Amostra Pico RSS Duração Uso
readFileSync + JSON.parse 186MB / 480k 612MB 1.3s ficheiros pequenos, acesso aleatório
streamArray + for await + escritas lentas na BD (0.5ms cada) a mesma 104MB (plana) ao ritmo da BD ingestão registo a registo, transformações
streamArray + escritas via data, sem contrapressão a mesma 407MB ~10s o exemplo a não seguir
streamArray + write()/drain a mesma 161MB ~10s gravar em disco ou reencaminhar

Ambiente: Node 22.13, Maximum resident set size via /usr/bin/time -v, amostra sintética com campos de forma real, execuções únicas sem média, escritas lentas simuladas com setTimeout. Estes números são conclusões de ordem de grandeza para esta amostra, não constantes universais — meça com os seus próprios dados.

Duas leituras merecem atenção. A primeira e a segunda estratégia diferem num fator de seis em memória, ao preço de trocar «1.3 segundos» por «a velocidade da BD». A terceira e a quarta diferem num fator de 2.5: ler em streaming sem contrapressão na escrita resolve só metade do problema.

Diagnóstico: confirmar que a contrapressão funciona mesmo

Problemas de memória em produção não se diagnostical por intuição. Um artigo da Tencent Cloud sobre resolução de contrapressão dá um método prático:

  1. Faça log temporário de 'pause' e 'resume' nos streams críticos. Se uma pipeline de grande débito nunca pausa, algures há dados a acumular-se em memória;
  2. Observe writable.writableLength — crescimento contínuo significa que o buffer nunca esvazia;
  3. Amostre o RSS com process.memoryUsage() a intervalos e trace a curva, distinguindo «crescimento em rampa» (acumulação) de «planalto em dente de serra» (libertação saudável).

Sob a semântica do for await, os eventos pause e resume têm de alternar; se nunca dispararem, procure um listener data a mais ou um await esquecido.

Quando o streaming não é a resposta

O streaming não é a solução predefinida. Para ficheiros de algumas dezenas de MB com acesso aleatório por chave, uma chamada simples de JSON.parse é mais simples e barata. Abrir um ficheiro grande no navegador é outro domínio de problema — como abrir um ficheiro JSON grande cobre a escada de visualizadores. As fronteiras do parsing em streaming são claras:

  • o nível de topo é um array (ou os dados dividem-se como JSONL), o consumo é sequencial, sem olhar para trás;
  • o tamanho do ficheiro é incontrolável ou excede largamente a margem do heap, e uma importação não pode duplicar a pegada do processo;
  • o consumidor tem um desfasamento de velocidade natural (escritas na BD, chamadas a APIs a jusante), por isso precisa de contrapressão em vez de uma mangueira a pleno débito.

Quando a forma de topo é irregular, inspecione primeiro a estrutura na ferramenta parser e formatador JSON; o equivalente na linha de comandos está coberto em jq para JSON grande — jq --stream e streamArray são a mesma ideia em dois runtimes.

FAQ

Quanto mais lento é o stream-json comparado com o JSON.parse?

No parsing puro, o JSON.parse ganha: 1.3 segundos para a amostra de 186MB, contra cerca de 7 segundos para o streamArray sem latência de escrita (parsing por tokens mais construção de objetos registo a registo). O benefício do streaming vive inteiramente no lado da memória: o pico cai de 612MB para 104MB. Uma importação é de qualquer forma limitada pela BD, pelo que pagar alguns segundos de parsing por uma margem de memória seis vezes maior é normalmente um bom negócio; dentro de respostas API ao milissegundo, não.

A contrapressão do for await é a mesma que pause/resume manuais?

Semanticamente sim: o for await suspende o stream legível enquanto o corpo do ciclo está pendente, o que equivale a chamar pause() quando write() devolve false e resume() no drain. A diferença: a mecânica da linguagem assume a contabilidade e nada se esquece; o cabeamento manual perde a contrapressão de toda a cadeia assim que um ponto falha.

E se o nível de topo for um único objeto imenso?

O stream-json fornece streamObject() (emite por chave) e o filtro Pick (analisa só a subárvore escolhida). Se bastam alguns campos, o Pick com um JSONPath reduz o grafo inteiro ao subgrafo necessário. Entrada multi-documento (JSON Lines, sequências JSON) vale melhor dividida linha a linha e tratada como documentos independentes.

Como escrever o resultado como JSONL ou reencaminhar a jusante?

O lado da escrita é a mesma questão de contrapressão: fs.createWriteStream e http.request exigem verificar o valor de retorno de write() e aguardar once(stream, 'drain') em caso de false — ou ligar o writable ao pipeline(). A verificação é simples: a curva de RSS após uma passagem tem de ser estável e o writableLength não pode crescer persistentemente.

Qual é o monitor de memória mais rápido para uma tarefa de importação?

Versão mínima: um temporizador que amostra process.memoryUsage().rss a cada 100ms para um array e imprime o máximo no fim. Mais preciso: /usr/bin/time -v node task.js dá diretamente o Maximum resident set size. Em contêineres, coloque a linha de alerta em 70% do limite de memória para deixar margem ao GC.

Referências

Ferramentas relacionadas

Artigos relacionados

jq e arquivos JSON grandes: por que -s explode a memória e como processar em streaming

Agregar centenas de MB de logs JSON com jq -s termina em OOM, enquanto reduce inputs produz a mesma estatística com poucos MB de RAM. Medido em uma amostra de 220 MB e 2 milhões de linhas: slurp culmina em 2,08 GB contra 3,5 MB do redutor em streaming. Este artigo explica o mecanismo de consumo de memória, o processamento linha a linha do JSONL, os eventos de caminho do --stream e três armadilhas reais, incluindo a saída vazia silenciosa do -n --stream.

Avançado~6 min de leituraAtualizado em 2026-11-12

Arquivo JSON grande não abre? Escolha a ferramenta certa pelo tamanho

Exportações JSON de dezenas de MB frequentemente travam editores de texto e ferramentas online, embora o parsing leve apenas algumas centenas de milissegundos. Medimos tempo e memória em cada etapa com uma amostra de 45 MB e 500.000 registros, mostramos que o custo real está na contagem de linhas e nós e apresentamos uma tabela de decisão de ferramentas por tamanho: visualização online, extração via linha de comando, streaming e aplicativo de desktop.

Intermediário~6 min de leituraAtualizado em 2026-11-07