Filtrar JSON na linha de comando com jq

Extraia um valor do JSON com jq '.users[0].name' api.json — o ponto é a sintaxe de caminho do jq, e tudo depois disso (select, @csv, -r) é a mesma ideia aplicada a filtrar, converter ou limpar a saída. O jq trata JSON como o awk trata texto: faz o parse uma vez e depois encadeia filtros. Os seis padrões abaixo cobrem o que realmente aparece quando você está diante de uma resposta de API e precisa de um campo, uma lista filtrada ou um CSV.

1. Pegar um campo

$ clai pega o nome do primeiro usuário de api.json→ jq '.users[0].name' api.json"alice"

O ponto é o filtro do jq para «pegar o valor atual», e depois vem um caminho. As aspas na saída significam que o jq devolveu uma string JSON, não texto puro para a shell.

2. Remover as aspas para um script

$ clai imprime os nomes de todos os usuários sem aspas→ jq -r '.users[].name' api.jsonalicebob

-r (raw output) devolve strings sem aspas, o que você quer quando o resultado vai para uma variável de shell ou um loop. Sem -r você recebe uma string entre aspas que falha na primeira comparação sem motivo aparente.

3. Filtrar por uma condição

$ clai mostra os nomes dos usuários com mais de 30 anos→ jq -r '.users[] | select(.age > 30) | .name' api.jsonalice

.users[] desenrola o array em um fluxo de valores, e select() só deixa passar os que combinam. O pipe dentro do jq funciona exatamente como um pipe de shell.

4. Transformar em CSV

$ clai transforma isso em csv com nome e idade→ jq -r '.users[] | [.name, .age] | @csv' api.json"alice",34"bob",28

Reúna os campos que quer em um array e passe para @csv. Também existem @tsv, @base64 e @uri. Isso é uma linha em vez de um script em Python.

5. Entender uma resposta de API desconhecida

$ clai mostra quais chaves existem no nível superior→ jq -r 'keys[]' api.jsonusers

É a primeira coisa que vale a pena rodar contra o JSON de outra pessoa. Depois, jq -r '.users[0] | keys[]' mostra os campos dentro de um elemento.

6. Analisar uma resposta de API direto do curl

$ clai pega o json da api e imprime só o campo version→ curl -s https://example.com/api/status | jq -r '.version'

Essa combinação é a razão de existir do jq. -s desliga o indicador de progresso do curl — sem isso, ele cai no stream e o jq engasga.

Pegadinhas

• -r muda a saída, não o filtro. Um -r esquecido está por trás da maioria das esquisitices tipo "1.2.3" em comparação de strings no bash.
• Uma chave com hífen ou ponto precisa de aspas: jq '."content-type"'. Sem elas o jq tenta interpretar como expressão e falha.
• O jq engasga com um fluxo de vários objetos JSON. Para JSON delimitado por linhas (JSON Lines), adicione -s (slurp) ou processe linha a linha.

Perguntas relacionadas

Como pego o último elemento de um array? jq '.users[-1]'. Índices negativos contam a partir do fim.

Como verifico se um campo existe? jq 'has("age")' para um objeto, ou jq '.users[] | select(has("email"))' para filtrar uma lista.

jq ou python -m json.tool? json.tool só formata. O jq seleciona, filtra e transforma — tarefas diferentes num pipeline.

Veja também

• Imprimir uma coluna de um CSV com awk (e quando não usar)
• Triagem de rede em linguagem simples
• De one-liner a script versionado: quando vale a pena

Descreva o campo que você precisa e o CliAI escreve o filtro jq, aspas incluídas. Instale em uma linha.