JSON Toolkit

jq y archivos JSON grandes: por qué -s revienta la memoria y cómo procesar en streaming

En resumen: Agregar cientos de MB de logs JSON con jq -s termina en OOM, mientras que reduce inputs produce la misma estadística con unos pocos MB de RAM. Medido sobre una muestra de 220 MB y 2 millones de líneas: slurp culmina en 2,08 GB frente a 3,5 MB del reductor en streaming. Este artículo explica el mecanismo de consumo de memoria, el procesamiento línea a línea del JSONL, los eventos de ruta de --stream y tres trampas reales, incluida la salida vacía silenciosa de -n --stream.

Avanzado~6 min de lecturaPublicado el 2026-11-12Actualizado el 2026-11-12
Comparación de memoria entre streaming jq y -s con JSON grandes

jq parsea rápido, pero casi cada muerte ante un archivo de unos cientos de MB se remonta al mismo flag: -s carga toda la entrada en un solo array gigante, y el RSS máximo alcanza fácilmente varios múltiplos del tamaño del archivo.

Un archivo, dos consultas: 580 veces menos memoria

Empecemos por una medición. La muestra es un log JSONL de 220 MB y 2.000.000 de líneas (un registro de petición por línea: timestamp, level, path, status, duration_ms, uid). Entorno: jq 1.7 sobre Linux x86_64, RSS máximo capturado con /usr/bin/time -v:

Consulta Tarea Duración RSS máximo
jq -s 'group_by(.level) | ...' conteo por level 10,1s 2,08 GB (~9,5x el tamaño del archivo)
jq -n 'reduce inputs ...' el mismo conteo 4,7s 3,5 MB
jq -r 'select(...) | .path' filtro línea a línea 2,6s 3,6 MB

La misma estadística, 580 veces menos memoria, y además más rápido. No es un bug de jq — -s significa por definición «leer todo en un array»; la mayoría simplemente no dimensiona ese coste por defecto. Las fuentes de terceros coinciden: la experiencia con 2,3 GB de JSONL de la comunidad de Huawei Cloud cuenta exactamente la misma historia — OOM con slurp, y luego el reductor en streaming que termina en 47 segundos con un poco más de 30 MB de RSS. Dratini.tech midió sobre 2,5 GB de entrada un jq -s ejecutado por el OOM killer incluso en una máquina de más de 16 GB, mientras el pipeline ordinario completaba en 48,2s con 84 MB.

La conclusión primero: si el archivo supera la mitad de tu memoria disponible, -s ni siquiera es candidato. Mide tres cosas antes de escribir nada: ls -lh para el tamaño, free -m para el margen de memoria, wc -l para el número de líneas.

A dónde va realmente la memoria

jq -s (slurp) está documentado como «leer todas las entradas en un array». El coste real supera con creces el texto: tras el parseo, jq mantiene un árbol de estructuras C, y cada objeto, array, cadena y número lleva su propio nodo con metadatos. Nuestros 220 MB de texto se convirtieron en algo más de 2 GB de estructuras — una inflación de unas 9,5x. group_by además ordena y agrupa en memoria, amplificando el pico.

Un único documento JSON grande se comporta igual. Empaquetando el mismo log en un array raíz de 300 MB y extrayendo con un filtro ordinario:

Consulta Duración RSS máximo
jq '.[] | select(.level=="ERROR") | .uid' (documento entero) 4,7s 1,85 GB
jq --stream 'select(...)' (eventos de ruta) 13,4s 3,4 MB

El parseo completo sigue culminando en torno a 1,8 GB — jq construye todo el árbol antes de que el filtro se ejecute. --stream intercambia aproximadamente 3 veces el tiempo de ejecución por una memoria 540 veces menor. El modelo detallado de esta inflación se desarrolla en De dónde sale la memoria.

Logs JSONL: la lectura línea a línea ya es streaming

Si tu «archivo grande» en realidad es JSONL — un objeto por línea —, el comportamiento por defecto de jq ya es un flujo: cada línea se parsea y emite de forma independiente, y -s no es solo innecesario, es perjudicial:

# conteo por level: línea a línea, agregación en la shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# filtro + extracción: select primero, las líneas que no coinciden se descartan al instante
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Dos hábitos que conviene forzar:

  • select al principio de la pipeline. jq filtra en cuanto una línea se parsea; filtrar después de las transformaciones desperdicia cálculo.
  • -r para cadenas crudas. Sin él, la salida es una cadena JSON entrecomillada, y uniq -c contará "ERROR" y ERROR como dos valores distintos.

Para las líneas corruptas usa fromjson?: jq -r 'fromjson? | .level' salta silenciosamente las líneas no parseables, y un fragmento truncado no mata toda la pipeline. El formato en sí se trata en El manual práctico de JSONL; este artículo trata los comandos que lo procesan.

Agregación global: reduce inputs mantiene el estado acotado

El filtrado línea a línea pertenece a la shell, pero cuando la agregación debe hacerse dentro de jq — contadores por level, duración media por path —, la clave es reduce con inputs, para un estado acotado:

# conteo por level: la memoria sigue el tamaño del resultado, no el del archivo
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# duración media por path: el estado es un par fijo {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Dos detalles:

  • -n significa que jq no debe consumir la primera entrada como valor inicial; inputs emite cada registro por sí mismo. Olvidar -n y el primer registro queda tragado como estado inicial.
  • El estado del reducer debe tener forma fija — solo contadores y acumuladores. En cuanto empujas las líneas coincidentes a un array dentro del reducer, la memoria vuelve a crecer con el volumen de datos y el streaming deja de servir de nada.

De ahí los 3,5 MB de la tabla: han pasado dos gigabytes, y solo queda una tabla hash.

Un solo documento grande: los eventos de ruta de --stream

Cuando la entrada es un único documento raíz enorme (un export de unos cientos de MB sin fronteras de líneas), usa --stream. En lugar de valores completos, emite una secuencia de eventos «ruta + valor hoja»:

# un evento se ve así: array de ruta + escalar
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Extraer del flujo de eventos exige emparejar la forma completa de la ruta — profundidad, nombres de miembros, posiciones de índice —, porque comprobar solo el último componente atrapará también claves homónimas en objetos anidados:

# solo rows[i].id, ignorando meta.id y los homónimos más profundos
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

La agregación sigue siendo el reduce inputs de forma fija (con -n --stream, los eventos deben consumirse vía inputs — ver las trampas). Para la reconstrucción — convertir un flujo de eventos de nuevo en objetos enteros — combina truncate_stream y fromstream. La visión general de la elección de herramientas por tamaño está en ¿Archivo JSON demasiado grande?.

Tres trampas reales

Trampa uno: -n --stream sin inputs no produce salida en absoluto, en silencio. Comprobado en esta máquina: jq -n --stream 'select(...)' file.json termina con código 0, sin salida ni error — en modo -n, jq no lee la entrada, y el select del filtro no recibe ni un evento. Correcto: quita -n y usa --stream a secas, o acopla -n --stream con reduce inputs. Esta clase de fallos «éxito pero vacío» es la más difícil de depurar; valida con una muestra pequeña antes de cablear una pipeline.

Trampa dos: --stream solo emite hojas escalares; los objetos y arrays vacíos no tienen evento de valor. {"a":{}} produce solo un evento de cierre de ruta (del tipo length == 1), y un filtro sobre length == 2 se tragará los contenedores vacíos en silencio — decide explícitamente si cuentan en tus estadísticas.

Trampa tres: resultado parcial tras un error de parseo a mitad del archivo. Una pipeline en streaming puede haber emitido la mitad de su salida antes de toparse con JSON roto hacia el final. jq 1.7 falla ruidosamente por defecto — [1,] produjo parse error: Expected another array element at line 1, column 4 con código 5 en nuestra prueba —, pero si tu shell redirige stdout al archivo de destino, el resultado truncado ya está en disco. La salvaguarda de ingeniería: staging más rename — escribir en un archivo temporal y mover sobre el destino solo tras el éxito de jq. Para un control más fino, --stream-errors convierte los errores de parseo en eventos que puedes tratar e interrumpir explícitamente vía error.

Cuándo no usar jq: Miller y las pipelines híbridas

jq es un lenguaje funcional de transformación de árboles, fuerte en reestructuración profunda. Pero tan pronto la tarea degenera en «filtrar y contar gigabytes de logs planos», existen herramientas mejor cortadas. El benchmark de dratini.tech sobre 2,5 GB de JSONL (filtro + selección de columnas):

Herramienta Duración RSS máximo
pipeline jq ordinaria 48,2s 84 MB
jq -s OOM (ejecutado incluso con 16 GB+) —
Miller (mlr --json) 11,4s 18 MB
ripgrep + jq híbrido 8,1s 32 MB

La regla: anidación profunda, reestructuración, omnipresencia en CI — jq. Estadísticas planas de varios gigabytes, percentiles p95, JSONL a TSV — un solo mlr --json stats1 reemplaza un script jq con memoria constante. Y si ripgrep puede eliminar el 90 % de las líneas innecesarias antes de jq, el híbrido es el más rápido.

FAQ

¿A partir de qué tamaño jq -s se vuelve peligroso?

Umbral práctico: en cuanto el archivo supera la mitad de la memoria disponible, desconfía. La memoria tras el parseo suele valer de 3 a 10 veces el texto (9,5x en nuestros 220 MB; reportes de terceros muestran un archivo de 4 GB matando una máquina de 16 GB). Compara primero ls -lh con free -m y sustituye -s por reduce inputs si estás cerca del límite.

¿Por qué -n delante de reduce inputs?

-n le dice a jq que no consuma la primera entrada como valor inicial del programa, para que inputs emita él mismo cada registro. Sin -n, el primer registro se convierte en el estado inicial del reduce y desaparece silenciosamente del resultado — una pérdida de datos sin ningún error.

¿Cómo elegir entre --stream y el modo ordinario?

Mira primero la forma del archivo. El JSONL ya es un flujo línea a línea; --stream no aporta nada. Para un único documento grande del que solo quieres unos valores hoja, --stream intercambia unas 3 veces el tiempo por cientos de veces menos memoria. Si el archivo cabe en memoria, el jq ordinario es simplemente más rápido.

¿Qué hacer con las líneas corruptas en streaming?

En JSONL, fromjson? salta las líneas imposibles de parsear para que una sola línea sucia no mate la pipeline. En un documento grande único, un error de parseo a mitad del archivo hace fallar la ejecución — publica de forma atómica mediante archivo de staging y rename, o usa --stream-errors para un control explícito.