jq Cheatsheet — cheatly.dev

jq es el sed del JSON — un procesador de línea de comandos ligero y flexible que convierte respuestas de API desordenadas y archivos de configuración en exactamente los datos que necesitas. Si alguna vez entrecerraste los ojos frente a un muro de JSON minificado tratando de encontrar un campo anidado, jq es la herramienta que te hará preguntarte cómo sobrevivías sin ella.

El modelo mental es simple: jq es un pipeline. Los datos fluyen desde la izquierda, se transforman con filtros y salen por el lado derecho. El . es tu punto de partida — significa "toda la entrada." Desde ahí profundizas con .field, iteras con .[] y encadenas filtros con |. Es programación funcional disfrazada de herramienta de línea de comandos, y una vez que el pensamiento de pipeline hace clic, recurrirás a jq de la misma forma que recurres a grep.

Hemos organizado esto por el tipo de problema que estás resolviendo en lugar de por la taxonomía interna de jq. Empieza con Filtros Básicos para extraer valores de JSON, luego pasa a Operaciones de Arrays y Objetos cuando necesites reestructurar datos. La sección de One-Liners al final es donde vive la magia real — patrones probados en batalla que puedes copiar y pegar en tu terminal ahora mismo.

Algo que debes internalizar temprano: las expresiones de jq son componibles. Cada filtro toma una entrada y produce una salida, así que puedes encadenarlos infinitamente con |. ¿Ese select(...) que escribiste? Canalízalo a map(...). Canaliza eso a sort_by(...). Son filtros hasta el fondo.

Filtros Básicos

.

Identidad — devolver toda la entrada sin cambios

.field

Extraer un campo de nivel superior por nombre

.field.nested

Profundizar en objetos anidados con notación de punto

.["hyphenated-key"]

Acceder a campos con caracteres especiales en el nombre

.[]

Iterar sobre todos los elementos de un array o valores de un objeto

.[0]

Obtener el primer elemento de un array

.[-1]

Obtener el último elemento de un array

.[2:5]

Extraer un segmento del array — elementos en los índices 2, 3 y 4

.field?

Intentar acceder a un campo — suprimir errores si no existe

.[] | .name

Iterar un array y extraer un campo de cada elemento

Tipos y Valores

null

El valor null de JSON

length

Longitud de string, conteo de array o número de claves de un objeto

keys

Obtener todas las claves de un objeto como un array ordenado

keys_unsorted

Obtener todas las claves de un objeto en orden original

values

Obtener todos los valores de un objeto como un array

type

Devolver el tipo como string: "object", "array", "string", "number", "boolean" o "null"

has("field")

Verificar si un objeto tiene una clave específica (devuelve true/false)

in({"a":1})

Verificar si una clave existe en un objeto dado

empty

No producir salida — útil para supresión condicional

env.VAR

Acceder a la variable de entorno VAR

Operaciones con Strings

split(",")

Dividir un string por delimitador en un array

join(",")

Unir un array de strings con un delimitador

test("regex")

Probar si un string coincide con una regex (devuelve true/false)

match("regex")

Devolver objeto de coincidencia con offset, longitud y capturas

capture("(?<name>\\w+)")

Grupos de captura con nombre devueltos como objeto

gsub("old"; "new")

Reemplazar todas las ocurrencias de un patrón regex

sub("old"; "new")

Reemplazar la primera ocurrencia de un patrón regex

ascii_downcase

Convertir string a minúsculas

ascii_upcase

Convertir string a mayúsculas

ltrimstr("prefix")

Eliminar un prefijo de un string si está presente

rtrimstr("suffix")

Eliminar un sufijo de un string si está presente

@base64

Codificar un string como base64

@base64d

Decodificar un string base64

@uri

Codificar un string con percent-encoding para URLs

@html

Escapar caracteres especiales de HTML

tostring

Convertir cualquier valor a su representación como string

tonumber

Parsear un string como número

Operaciones con Arrays

map(f)

Aplicar el filtro f a cada elemento y recopilar resultados

map_values(f)

Aplicar el filtro f a cada valor (funciona también con objetos)

select(condition)

Mantener solo los elementos donde la condición sea true

sort

Ordenar un array de valores comparables

sort_by(.field)

Ordenar array de objetos por un campo específico

reverse

Invertir el orden de un array

group_by(.field)

Agrupar elementos del array por un campo en sub-arrays

unique

Eliminar valores duplicados de un array ordenado

unique_by(.field)

Eliminar duplicados por un campo específico

flatten

Aplanar arrays anidados en un solo nivel

flatten(1)

Aplanar un nivel de anidamiento

first

Obtener la primera salida de un generador

last

Obtener la última salida de un generador

limit(n; expr)

Tomar solo las primeras n salidas de una expresión

add

Sumar números, concatenar strings o fusionar arrays/objetos

any(condition)

True si algún elemento satisface la condición

all(condition)

True si todos los elementos satisfacen la condición

min_by(.field)

Obtener el elemento con el menor valor del campo

max_by(.field)

Obtener el elemento con el mayor valor del campo

indices(value)

Obtener todos los índices donde aparece el valor en el array

contains([values])

Verificar si el array contiene todos los valores especificados

inside([values])

Verificar si la entrada está contenida dentro del valor dado

Operaciones con Objetos

to_entries

Convertir {"a":1} a [{"key":"a","value":1}]

from_entries

Convertir [{"key":"a","value":1}] de vuelta a {"a":1}

with_entries(f)

Atajo para to_entries | map(f) | from_entries

+ (objects)

Fusionar dos objetos — el lado derecho gana en conflictos de claves

* (objects)

Fusionar dos objetos recursivamente

{name, age}

Seleccionar campos específicos de un objeto

{newname: .oldname}

Renombrar un campo al extraer

del(.field)

Eliminar un campo de un objeto

paths

Listar todas las rutas a valores hoja como arrays

getpath(["a","b"])

Obtener valor en una ruta específica — como .a.b

setpath(["a","b"]; val)

Establecer valor en una ruta específica

delpaths([path])

Eliminar valores en las rutas especificadas

Condicionales y Comparaciones

if . then A else B end

Expresión condicional — la cláusula else es opcional

// (alternative)

Usar el valor derecho si el izquierdo es null o false

a == b

Comparación de igualdad (igualdad profunda para objetos/arrays)

a != b

Comparación de desigualdad

and, or, not

Operadores booleanos

try f

Ejecutar filtro f, suprimir errores silenciosamente

try f catch msg

Ejecutar filtro f, usar expresión msg en caso de error

f as $var | expr

Vincular un valor a una variable para usar en el pipeline

reduce .[] as $x (init; update)

Reducir un array a un solo valor

label $out | foreach ...

Bucle de streaming con soporte de break

Formato de Salida

-r (--raw-output)

Salida de strings sin comillas JSON

-c (--compact-output)

Minificar — imprimir JSON en una sola línea

-S (--sort-keys)

Ordenar claves de objetos alfabéticamente en la salida

-e (--exit-status)

Establecer código de salida basado en la salida: 0 para true/no-null, 1 para false/null

-n (--null-input)

No leer entrada — útil con --argjson o --slurpfile

-s (--slurp)

Leer todas las entradas en un solo array

--arg name val

Pasar un valor string como variable $name

--argjson name val

Pasar un valor JSON como variable $name

--slurpfile name file

Cargar un archivo JSON como variable $name (array)

@csv

Formatear un array de arrays como CSV

@tsv

Formatear un array de arrays como TSV

@json

Serializar un valor como string JSON (para incrustar)

@text

Convertir a salida de texto

One-Liners

Patrones del mundo real que realmente usarás. Copia, pega, adapta.

One-Liners

jq . file.json

Imprimir un archivo JSON con formato legible

jq -r ".[] | .name" file.json

Extraer un campo de cada objeto en un array

jq "[.[] | select(.active == true)]"

Filtrar un array para dejar solo elementos que coincidan

jq -r ".[] | [.name, .email] | @csv"

Convertir array JSON a CSV

jq -s "." file1.json file2.json

Fusionar múltiples archivos JSON en un array

jq -r "keys[]" file.json

Listar todas las claves de nivel superior

jq ".[] | select(.price > 100) | .name"

Encontrar nombres donde el precio excede un umbral

jq "group_by(.status) | map({(.[0].status): length}) | add"

Contar elementos por grupo

jq --arg q "$QUERY" '.[] | select(.name | test($q; "i"))'

Búsqueda insensible a mayúsculas usando una variable de shell

jq -r "to_entries[] | \"\(.key)=\(.value)\""

Convertir objeto JSON a líneas clave=valor

jq "[.[] | {id, name}]"

Reestructurar objetos — mantener solo campos específicos

jq -r ".results | sort_by(.date) | reverse | .[0]"

Obtener la entrada más reciente de un array ordenado

curl -s api.example.com | jq .

Imprimir respuesta de API con formato legible en línea

jq -s "map(.items) | flatten | unique_by(.id)"

Fusionar y deduplicar respuestas paginadas de API

jq 'walk(if type == "string" then gsub("\\n"; " ") else . end)'

Limpiar recursivamente saltos de línea en todos los valores string

Usa -r (salida cruda) siempre que canalices jq a otro comando. Sin ella, los strings vienen envueltos en comillas, y esas comillas atormentarán tus scripts de shell. jq -r '.name' te da Alice, no "Alice".

El operador // es el operador de coalescencia nula de jq — devuelve el lado derecho cuando el izquierdo es null o false. Perfecto para valores predeterminados: .config.timeout // 30. Es una de esas combinaciones de dos caracteres que te ahorra escribir un if-then-else completo el noventa por ciento de las veces.

Cuando necesites combinar datos de múltiples archivos o respuestas de API, recurre a --slurp (-s). Lee todas las entradas en un solo array, así puedes usar add para unir objetos, aplanar arrays o combinar datos entre archivos.

Usa --arg y --argjson para pasar variables de shell a jq de forma segura. Nunca interpoles variables de shell directamente en expresiones jq — se rompe con caracteres especiales y te abre a inyecciones. jq --arg name "$USER" '.[] | select(.name == $name)' es la forma correcta.

El filtro @base64d es un salvavidas cuando trabajas con secrets de Kubernetes o JWTs. Canaliza un valor codificado en base64 a través de jq -r '.data.password | @base64d' y obtén el texto plano sin salir de tu pipeline.

Encadena to_entries, map y from_entries (o usa el atajo with_entries) para transformar claves y valores de objetos en una sola pasada. ¿Quieres prefijar cada clave? with_entries(.key = "prefix_" + .key). Es el equivalente de map para objetos en lo que respecta a arrays.

Si los mensajes de error de jq son crípticos, agrega debug en cualquier punto de tu pipeline para ver qué está fluyendo en ese punto. Imprime a stderr sin interrumpir tu salida. Piénsalo como console.log para jq: .[] | debug | select(.active).

Related Tools

docker git fzf