JSON Toolkit

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

Resumo: 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 leituraPublicado em 2026-11-12Atualizado em 2026-11-12
Comparação de memória entre streaming jq e -s em JSON grandes

O jq faz parsing rápido, mas quase toda morte diante de um arquivo de algumas centenas de MB remonta ao mesmo flag: -s carrega toda a entrada em um único array gigante, e o RSS de pico alcança facilmente vários múltiplos do tamanho do arquivo.

Um arquivo, duas consultas: 580 vezes menos memória

Comecemos por uma medição. A amostra é um log JSONL de 220 MB e 2.000.000 de linhas (um registro de requisição por linha: timestamp, level, path, status, duration_ms, uid). Ambiente: jq 1.7 em Linux x86_64, RSS de pico capturado via /usr/bin/time -v:

Consulta Tarefa Duração RSS de pico
jq -s 'group_by(.level) | ...' contagem por level 10,1s 2,08 GB (~9,5x o tamanho do arquivo)
jq -n 'reduce inputs ...' a mesma contagem 4,7s 3,5 MB
jq -r 'select(...) | .path' filtro linha a linha 2,6s 3,6 MB

A mesma estatística, 580 vezes menos memória, e ainda mais rápido. Não é um bug do jq — -s significa, por definição, «ler tudo em um array»; a maioria das pessoas simplesmente não dimensiona esse custo padrão. Fontes de terceiros convergem: a experiência com 2,3 GB de JSONL da comunidade Huawei Cloud conta exatamente a mesma história — OOM com slurp, depois o redutor em streaming que termina em 47 segundos com pouco mais de 30 MB de RSS. A Dratini.tech mediu sobre 2,5 GB de entrada um jq -s morto pelo OOM killer até mesmo em uma máquina com mais de 16 GB, enquanto o pipeline ordinário completava em 48,2s com 84 MB.

A conclusão primeiro: se o arquivo ultrapassa metade da sua memória disponível, -s nem sequer é candidato. Meça três coisas antes de escrever qualquer coisa: ls -lh para o tamanho, free -m para a margem de memória, wc -l para o número de linhas.

Para onde vai realmente a memória

jq -s (slurp) é documentado como «ler todas as entradas em um array». O custo real excede largamente o texto: após o parsing, o jq mantém uma árvore de estruturas C, e cada objeto, array, string e número carrega seu próprio nó com metadados. Nossos 220 MB de texto viraram pouco mais de 2 GB de estruturas — um inchaço de cerca de 9,5x. O group_by ainda ordena e agrupa em memória, amplificando o pico.

Um único documento JSON grande se comporta da mesma forma. Empacotando o mesmo log em um array raiz de 300 MB e extraindo com um filtro comum:

Consulta Duração RSS de pico
jq '.[] | select(.level=="ERROR") | .uid' (documento inteiro) 4,7s 1,85 GB
jq --stream 'select(...)' (eventos de caminho) 13,4s 3,4 MB

O parsing integral culmina ainda em torno de 1,8 GB — o jq constrói toda a árvore antes de o filtro executar. O --stream troca aproximadamente 3 vezes o tempo de execução por uma memória 540 vezes menor. O modelo detalhado desse inchaço é desenvolvido em De onde vem a memória.

Logs JSONL: a leitura linha a linha já é streaming

Se o seu «arquivo grande» na verdade é JSONL — um objeto por linha —, o comportamento padrão do jq já é um fluxo: cada linha é parseada e emitida independentemente, e -s não é apenas desnecessário, é prejudicial:

# contagem por level: linha a linha, agregação no shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# filtro + extração: select primeiro, as linhas que não casam são descartadas na hora
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Dois hábitos a forçar:

  • select bem no início do pipeline. O jq filtra assim que uma linha é parseada; filtrar depois das transformações desperdiça processamento.
  • -r para strings cruas. Sem ele, a saída é uma string JSON entre aspas, e o uniq -c contará "ERROR" e ERROR como dois valores distintos.

Para as linhas corrompidas use fromjson?: jq -r 'fromjson? | .level' pula silenciosamente as linhas não parseáveis, e um fragmento truncado não mata o pipeline inteiro. O formato em si é tratado em O manual prático de JSONL; este artigo trata dos comandos que o processam.

Agregação global: reduce inputs mantém o estado limitado

A filtragem linha a linha pertence ao shell, mas quando a agregação precisa acontecer dentro do jq — contadores por level, duração média por path —, a chave é reduce com inputs, para um estado limitado:

# contagem por level: a memória segue o tamanho do resultado, não o do arquivo
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# duração média por path: o estado é um par fixo {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Dois detalhes:

  • -n significa que o jq não deve consumir a primeira entrada como valor inicial; inputs emite cada registro por si mesmo. Esquecer -n e o primeiro registro é engolido como estado inicial.
  • O estado do redutor deve ter forma fixa — apenas contadores e acumuladores. Assim que você empurra as linhas correspondentes para um array dentro do redutor, a memória volta a crescer com o volume de dados e o streaming deixa de valer alguma coisa.

Daí os 3,5 MB da tabela: dois gigabytes passaram, resta apenas uma tabela hash.

Um único documento grande: os eventos de caminho do --stream

Quando a entrada é um único documento raiz enorme (um export de algumas centenas de MB sem fronteiras de linha), use --stream. Em vez de valores completos, ele emite uma sequência de eventos «caminho + valor folha»:

# um evento se parece com: array de caminho + escalar
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Extrair do fluxo de eventos exige casar a forma completa do caminho — profundidade, nomes de membros, posições de índice —, porque verificar apenas o último componente pegará também chaves homônimas em objetos aninhados:

# apenas rows[i].id, ignorando meta.id e os homônimos mais profundos
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

A agregação continua sendo o reduce inputs de forma fixa (com -n --stream, os eventos devem ser consumidos via inputs — veja as armadilhas). Para a reconstrução — transformar um fluxo de eventos de volta em objetos inteiros — combine truncate_stream e fromstream. A visão geral da escolha de ferramentas por tamanho está em Arquivo JSON grande demais?.

Três armadilhas reais

Armadilha um: -n --stream sem inputs não produz saída alguma, em silêncio. Constatação nesta máquina: jq -n --stream 'select(...)' file.json termina com código 0, sem saída nem erro — no modo -n, o jq não lê a entrada, e o select do filtro não recebe evento algum. Correto: remova -n e use --stream puro, ou acople -n --stream com reduce inputs. Essa classe de falhas «sucesso mas vazio» é a mais difícil de depurar; valide em uma amostra pequena antes de montar um pipeline.

Armadilha dois: --stream só emite folhas escalares; objetos e arrays vazios não têm evento de valor. {"a":{}} produz apenas um evento de fechamento de caminho (do tipo length == 1), e um filtro sobre length == 2 engolirá silenciosamente os contêineres vazios — decida explicitamente se eles contam nas suas estatísticas.

Armadilha três: resultado parcial após um erro de parsing no meio do arquivo. Um pipeline em streaming pode ter emitido metade da sua saída antes de tropeçar em JSON quebrado perto do fim. O jq 1.7 falha ruidosamente por padrão — [1,] produziu parse error: Expected another array element at line 1, column 4 com código 5 em nosso teste —, mas se o seu shell redireciona o stdout para o arquivo de destino, o resultado truncado já está no disco. A salvaguarda de engenharia: staging mais rename — escrever em um arquivo temporário e mover sobre o destino apenas após o sucesso do jq. Para um controle mais fino, --stream-errors transforma os erros de parsing em eventos que você pode tratar e interromper explicitamente via error.

Quando não usar jq: Miller e pipelines híbridas

O jq é uma linguagem funcional de transformação de árvores, forte em reestruturação profunda. Mas assim que a tarefa degenera em «filtrar e contar gigabytes de logs planos», existem ferramentas mais bem cortadas. O benchmark da dratini.tech sobre 2,5 GB de JSONL (filtro + seleção de colunas):

Ferramenta Duração RSS de pico
pipeline jq comum 48,2s 84 MB
jq -s OOM (morto mesmo com 16 GB+) —
Miller (mlr --json) 11,4s 18 MB
ripgrep + jq híbrido 8,1s 32 MB

A regra: aninhamento profundo, reestruturação, onipresença em CI — jq. Estatísticas planas de vários gigabytes, percentis p95, JSONL para TSV — um único mlr --json stats1 substitui um script jq com memória constante. E se o ripgrep puder eliminar 90 % das linhas inúteis antes do jq, o híbrido é o mais rápido.

FAQ

A partir de que tamanho o jq -s se torna perigoso?

Limite prático: assim que o arquivo ultrapassa metade da memória disponível, desconfie. A memória após o parsing costuma valer de 3 a 10 vezes o texto (9,5x nos nossos 220 MB; relatos de terceiros mostram um arquivo de 4 GB matando uma máquina de 16 GB). Compare primeiro ls -lh com free -m e substitua -s por reduce inputs se estiver perto do limite.

Por que -n antes de reduce inputs?

-n diz ao jq para não consumir a primeira entrada como valor inicial do programa, para que inputs emita ele mesmo cada registro. Sem -n, o primeiro registro se torna o estado inicial do reduce e desaparece silenciosamente do resultado — uma perda de dados sem nenhum erro.

Como escolher entre --stream e o modo comum?

Olhe primeiro a forma do arquivo. O JSONL já é um fluxo linha a linha; --stream não serve para nada. Para um único documento grande do qual você quer apenas alguns valores folha, o --stream troca cerca de 3 vezes o tempo por centenas de vezes menos memória. Se o arquivo cabe na memória, o jq comum é simplesmente mais rápido.

O que fazer com as linhas corrompidas em streaming?

No JSONL, fromjson? pula as linhas não parseáveis para que uma única linha suja não mate o pipeline. Em um único documento grande, um erro de parsing no meio do arquivo faz a execução falhar — publique atomicamente por meio de arquivo de staging e rename, ou use --stream-errors para um controle explícito.