Filtrado y selección de JSON con pipelines de jq

jq es una herramienta ligera y potente de línea de comandos para analizar, filtrar y transformar datos JSON. Es el sed de JSON: se introduce JSON mediante una tubería y se obtiene de vuelta una salida estructurada.

• Está preinstalado en la mayoría de las distribuciones de Linux o se puede instalar mediante apt install jq / brew install jq
• Funciona perfectamente en canalizaciones del shell con curl, cat y otras herramientas
• Admite filtrado, mapeo, reducción y conversión de formatos

La invocación básica es: jq '<filter>' file.json o mediante una tubería, como cat file.json | jq '<filter>'. El filtro . (punto) es la identidad: muestra todo el documento con formato legible.

Para acceder a un campo de un objeto JSON, use la notación de punto: .fieldName. Puede encadenar selectores para recorrer objetos anidados.

• .name — campo de nivel superior
• .address.city — campo anidado
• ."field-with-dash" — los campos con caracteres especiales necesitan comillas

Si el campo no existe, jq devuelve null en lugar de producir un error. Esto permite utilizarlo de forma segura en scripts sin comprobaciones adicionales de valores nulos para campos opcionales.

Se accede a los arrays JSON mediante la notación de corchetes. jq utiliza índices basados en cero.

• .items[0] — primer elemento
• .items[-1] — último elemento
• .items[1:3] — segmento (desde el índice 1 hasta antes del 3)
• .items[] — descompone el array: muestra cada elemento como un valor independiente (este es el iterador)

El iterador [] es fundamental en las canalizaciones de jq: permite aplicar los filtros posteriores a cada elemento de forma independiente.

Al igual que la tubería del shell |, jq tiene su propio operador de tubería interno. Este pasa la salida de un filtro como entrada del siguiente.

• jq '.users[] | .name' — itera sobre los usuarios y después extrae el nombre de cada uno
• jq '.data | .items[] | .id' — navega hasta data, descompone items y extrae id

Las tuberías dentro de una expresión jq permiten construir transformaciones complejas paso a paso. Cada etapa recibe todo lo que produjo la etapa anterior, incluidos los múltiples valores generados por un iterador.

Idea clave: cuando un iterador produce N valores, cada filtro posterior se ejecuta N veces, una vez por valor.

El filtro select(condition) deja pasar un valor únicamente si la condición es verdadera; de lo contrario, no produce ninguna salida. Es el equivalente en jq de grep o WHERE en SQL.

• select(.age > 18) — conserva los objetos cuya edad es mayor que 18
• select(.status == "active") — comprobación de igualdad
• select(.name | startswith("A")) — prueba de cadena anidada

Combine select con el iterador para filtrar arrays: .items[] | select(.active) muestra únicamente los elementos cuyo .active sea verdadero.

jq permite remodelar los datos mediante la construcción de objetos nuevos con {} y arrays nuevos con [].

• {name: .name, city: .address.city} — selecciona y renombra campos en un objeto nuevo
• [.items[] | .id] — vuelve a recopilar los valores iterados en un array
• Forma abreviada: {name, age} equivale a {name: .name, age: .age}

Rodear una canalización con [...] se denomina construcción de arrays y es esencial cuando desea obtener un array JSON como salida en lugar de un flujo de valores.

El JSON del mundo real suele estar profundamente anidado. jq proporciona dos herramientas para la navegación profunda:

• .a.b.c — ruta explícita cuando se conoce la estructura
• .. | .fieldName? — descenso recursivo: recorre todos los nodos del árbol y muestra los valores donde existe la clave

El operador ? (try) suprime los errores cuando un campo no existe en un nodo determinado, algo fundamental al utilizar el descenso recursivo en árboles heterogéneos.

Utilice el descenso recursivo con moderación en documentos grandes: visita todos los nodos y puede ser lento. Prefiera rutas explícitas cuando la estructura sea predecible.

Uno de los casos de uso más habituales de jq es analizar respuestas de API REST obtenidas con curl. Combinar curl -s (silencioso) con una canalización de jq permite extraer datos de forma limpia y apta para scripts.

• Extraer un valor único: curl -s URL | jq '.field'
• Construir una tabla de resumen: iterar sobre un array y reconstruir objetos únicamente con los campos necesarios
• Usar -r (salida sin formato) para eliminar las comillas que rodean los valores de texto, algo esencial al asignarlos a variables del shell

Consejo: añada siempre -r cuando la salida de jq se vaya a utilizar como variable del shell o se vaya a enviar a otro comando.

jq proporciona dos funciones de orden superior prácticas para transformar colecciones:

• map(f) — aplica el filtro f a cada elemento de un array y devuelve un array nuevo. Equivale a [.[] | f].
• map_values(f) — aplica f a cada valor de un objeto o array, conservando las claves o los índices.

Estas funciones son más legibles que envolver manualmente las canalizaciones en [] y constituyen el estilo idiomático de jq para las transformaciones que deben conservarse como arrays.

Los datos JSON de fuentes externas suelen ser inconsistentes: puede que falten campos o que tengan el valor null. jq proporciona el operador alternativo // (doble barra) para proporcionar un valor predeterminado.

• .nickname // "anonymous" — usa .nickname si no es null ni false; de lo contrario, usa "anonymous"
• .count // 0 — valor predeterminado numérico
• Combínelo con select: select((.status // "inactive") == "active")

Esto es mucho más conciso que el equivalente del shell, ${VAR:-default}, y se combina fácilmente dentro de canalizaciones más largas.

El registro estructurado en JSON es habitual en los sistemas modernos. A continuación se muestra un script realista que lee un archivo de registro JSON delimitado por saltos de línea, filtra las entradas de error y da formato a un resumen legible.

Patrones principales utilizados:

• -c (salida compacta): un objeto JSON por línea, útil para enviarlo a bucles del shell mediante una tubería
• --arg name value — inyecta una variable del shell como argumento de texto de jq
• select para filtrar por nivel del registro
• -r para obtener una salida de texto sin formato adecuada para echo

Compruebe su comprensión de cómo funciona select() dentro de una canalización de jq.

Dado el siguiente comando:

¿Cuál será la salida?

Ha estudiado las herramientas fundamentales de jq para recorrer y filtrar JSON desde la línea de comandos:

• Notación de punto (.field, .a.b.c) selecciona campos de objetos
• Acceso a arrays (.[0], .[]) permite indexar y recorrer arrays
• Operador de tubería (|) encadena filtros; cada etapa procesa todos los valores de la anterior
• select(cond) filtra valores y solo deja pasar aquellos cuya condición sea verdadera
• Construcción de objetos y arrays ({}, [], map()) remodela los datos en nuevas estructuras
• Operador alternativo (//) proporciona valores predeterminados para campos nulos o inexistentes
• Indicador -r elimina las comillas al asignar variables del shell; --arg inserta variables del shell de forma segura
• Descenso recursivo (.. | .field?) busca en árboles profundamente anidados cuando se desconoce la ruta

Con estos elementos puede transformar cualquier respuesta de una API JSON, archivo de registro o configuración en exactamente los datos que necesitan sus scripts, sin salir del terminal.