← Todos los artículos
Actualizado el May 29, 20267 min read

Tutorial de jq: filtra y transforma JSON

Aprende jq en la línea de comandos: instalar, formatear, seleccionar, filtrar, mapear y editar JSON — con recetas listas para copiar.

jq es la herramienta estándar de línea de comandos para cortar, filtrar y transformar JSON. Convierte one-liners en un potente lenguaje de consulta para respuestas de API, archivos de log y configuración. Este tutorial cubre la instalación, los filtros principales que usarás cada día, y un conjunto de recetas para copiar y pegar para las tareas más comunes del mundo real.

¿Qué es jq?

jq lee JSON de un archivo o de la entrada estándar, aplica un filter, y escribe JSON (o texto raw) en la salida estándar. Lo formatea por defecto y nunca envía tus datos a ningún sitio —— es un binario local, ideal para payloads sensibles. El lenguaje de filtros completo está documentado en el manual de jq.

Instalar jq

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget o choco)
winget install jqlang.jq

# Verifica
jq --version

El filtro identity: formatear cualquier cosa

El filtro más simple, ., devuelve la entrada sin cambios —— lo que hace de jq un formateador instantáneo:

# Formatear un archivo
jq . data.json

# Formatear una respuesta curl
curl -s https://api.example.com/users | jq .

# Al revés: minify (salida compacta)
jq -c . data.json

Seleccionar campos

Entra en objetos con .key, y en arrays con []:

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# Todos los elementos de un array
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# Un campo de cada elemento del array
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# Quita las comillas de JSON con -r (raw output)
jq -r '.[].name' users.json

Filtrar con select

# Mantén solo los objetos que cumplen una condición
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# Comparación numérica
jq '.[] | select(.age > 30)' users.json

Transformar con map y construcción de objetos

# Reformula cada elemento en un objeto nuevo
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# Saca una lista plana de valores
jq '[.[].email]' users.json     # ["a@x.com", ...]

# Encadena filtros con |
jq '.items | map(.price) | add' order.json   # suma de todos los precios

Recetas comunes

Tarea Comando
Formatear jq . file.json
Minify jq -c . file.json
Obtener un campo jq '.data.token' resp.json
String raw (sin comillas) jq -r '.token' resp.json
Contar elementos del array `jq '.
Keys de un objeto jq 'keys' obj.json
Filtrar filas `jq '.[]
Ordenar por un campo jq 'sort_by(.age)'
Sumar un campo `jq '[.[].amount]
Ordenar keys del objeto jq --sort-keys . file.json
Validar (vía exit code) jq empty file.json

Remodelar objetos: to_entries / from_entries

Los dos transformadores de forma de objeto más útiles de jq:

# Renombra cada key (aquí a minúsculas)
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# Elimina keys cuyo valor sea null
jq 'with_entries(select(.value != null))' file.json

# Objeto ⇄ array de pares
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

Interpolación y formatos de salida: \(.x), @csv, @json, @base64

jq tiene interpolación de strings y format strings incorporados para convertir JSON en otros formatos:

# Interpolación de strings dentro de un string entre comillas
jq -r '"\(.user) bought \(.items|length) items"' order.json

# Una fila CSV por objeto
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# JSON inline para shells (literal de string escapado)
jq -r '.user | @json' record.json

# Codifica un valor en Base64 (útil para tokens / data URIs)
jq -r '.payload | @base64' message.json
# Lado de decodificación: jq acepta @base64d en versiones más nuevas

Validar JSON con jq

Como jq sale con código distinto de cero con entrada inválida, jq empty file.json es un chequeo de validez limpio para scripts y CI —— ve Cómo validar JSON para más enfoques de validación.

Cuándo una herramienta del navegador es más rápida

jq brilla en scripts y pipelines, pero para algo puntual —— formatear una respuesta pegada, inspeccionar una estructura desconocida o reparar JSON roto —— una herramienta del navegador no necesita instalación ni escapado de shell:

Preguntas frecuentes

¿Cómo formateo JSON con jq?

Ejecuta jq . file.json —— el filtro identity . devuelve la entrada y jq la formatea por defecto. Usa -c para salida compacta.

¿Cómo extraigo un solo campo con jq?

Usa un filtro de ruta como jq '.data.token', y añade -r para salida raw si quieres el valor sin las comillas.

¿Cómo filtro un array JSON con jq?

Itera con .[] y aplica select(), p. ej. jq '.[] | select(.active == true)'.

¿Puede jq validar JSON?

Sí —— jq empty file.json parsea la entrada y sale con código distinto de cero si es inválida, lo que lo hace útil en CI. Para más detalles ve Cómo validar JSON.

¿Cómo actualizo un valor en JSON con jq?

Asigna con = (por ejemplo jq '.status = "done"') o transforma el valor actual con |= (por ejemplo jq '.count |= . + 1'). jq escribe en la salida estándar, así que guarda los cambios mediante un archivo temporal —— no existe un flag para editar in situ.

¿Cómo paso una variable de shell a jq?

Usa --arg name "$value" para cadenas (o --argjson para números y booleanos) y refiérete a ella como $name en el filtro. Pasar los valores así es más seguro que insertarlos en la cadena del filtro, donde una comilla suelta podría romperlo.

Sigue leyendo

Fuentes

Última revisión: junio de 2026.