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.

O jq faz parsing rápido, mas quase toda morte diante de um arquivo de algumas centenas de MB remonta ao mesmo flag:
-scarrega 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:
selectbem no início do pipeline. O jq filtra assim que uma linha é parseada; filtrar depois das transformações desperdiça processamento.-rpara strings cruas. Sem ele, a saída é uma string JSON entre aspas, e ouniq -ccontará"ERROR"eERRORcomo 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:
-nsignifica que o jq não deve consumir a primeira entrada como valor inicial;inputsemite cada registro por si mesmo. Esquecer-ne 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.