Filtrar JSON en la línea de comandos con jq

Extrae un valor de JSON con jq '.users[0].name' api.json — el punto es la sintaxis de ruta de jq, y todo lo demás (select, @csv, -r) es la misma idea aplicada a filtrar, convertir o limpiar la salida. jq trata el JSON como awk trata el texto: parsea una vez y luego encadena filtros. Los seis patrones de abajo cubren lo que realmente aparece cuando miras la respuesta de una API y necesitas un campo, una lista filtrada o un CSV.

1. Obtener un campo

$ clai saca el nombre del primer usuario de api.json→ jq '.users[0].name' api.json"alice"

El punto es el filtro de jq para «tomar el valor actual», y después le sigue una ruta. Las comillas en la salida significan que jq devolvió una cadena JSON, no texto plano para la shell.

2. Quitar las comillas para un script

$ clai imprime los nombres de todos los usuarios sin comillas→ jq -r '.users[].name' api.jsonalicebob

-r (raw output) te da cadenas sin comillas, que es lo que quieres cuando el resultado va a una variable de shell o a un bucle. Si omites -r obtienes cadenas entre comillas que fallan en la primera comparación sin razón aparente.

3. Filtrar por una condición

$ clai muestra los nombres de los usuarios mayores de 30→ jq -r '.users[] | select(.age > 30) | .name' api.jsonalice

.users[] despliega el array en un flujo de valores, y select() solo deja pasar los que cumplen. La tubería dentro de jq funciona igual que una tubería de shell.

4. Convertirlo en CSV

$ clai convierte esto en csv con nombre y edad→ jq -r '.users[] | [.name, .age] | @csv' api.json"alice",34"bob",28

Reúne los campos que quieres en un array y pásalo a @csv. También existen @tsv, @base64 y @uri. Eso es una línea en lugar de un script en Python.

5. Entender una respuesta de API desconocida

$ clai muestra qué claves hay en el nivel superior→ jq -r 'keys[]' api.jsonusers

Es lo primero que vale la pena correr contra el JSON de otra persona. Sigue con jq -r '.users[0] | keys[]' para ver los campos dentro de un elemento.

6. Parsear una respuesta de API directamente desde curl

$ clai obtén el json de la api y muestra solo el campo version→ curl -s https://example.com/api/status | jq -r '.version'

Esta combinación es la razón de ser de jq. -s apaga el indicador de progreso de curl — sin él, ese indicador cae en el flujo y jq se atraganta con él.

Trampas habituales

• -r cambia la salida, no el filtro. Un -r olvidado está detrás de la mayoría de las rarezas del tipo "1.2.3" en comparaciones de cadenas en bash.
• Una clave con guion o punto necesita comillas: jq '."content-type"'. Sin ellas jq intenta interpretarla como una expresión y falla.
• jq se atraganta con un flujo de varios objetos JSON. Para JSON delimitado por líneas (JSON Lines), añade -s (slurp) o procesa línea por línea.

Preguntas relacionadas

¿Cómo obtengo el último elemento de un array? jq '.users[-1]'. Los índices negativos cuentan desde el final.

¿Cómo compruebo si existe un campo? jq 'has("age")' para un objeto, o jq '.users[] | select(has("email"))' para filtrar una lista.

¿jq o python -m json.tool? json.tool solo formatea. jq selecciona, filtra y transforma — tareas distintas dentro de una tubería.

Ver también

• Imprimir una columna de un CSV con awk (y cuándo no)
• Triaje de red en lenguaje sencillo
• De one-liner a script versionado: cuándo dar el salto

Describe el campo que necesitas y CliAI escribe el filtro de jq, comillas incluidas. Instálalo en una línea.