Tutorial de jq: filtre e transforme JSON

jq é a ferramenta padrão de linha de comando para fatiar, filtrar e transformar JSON. Transforma one-liners em uma linguagem de consulta poderosa para respostas de API, arquivos de log e configuração. Este tutorial cobre instalação, os filtros principais que você vai usar todo dia, e um conjunto de receitas para copiar e colar para as tarefas mais comuns do mundo real.

O que é jq?

jq lê JSON de um arquivo ou da entrada padrão, aplica um filter, e escreve JSON (ou texto cru) na saída padrão. Faz pretty-print por padrão e nunca envia seus dados para lugar nenhum —— é um binário local, ideal para payloads sensíveis.

Instalando o jq

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

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

# Verifica
jq --version

O filtro identity: pretty-print qualquer coisa

O filtro mais simples, ., retorna a entrada sem alterações —— o que faz do jq um formatador instantâneo:

# Pretty-print de um arquivo
jq . data.json

# Pretty-print de uma resposta curl
curl -s https://api.example.com/users | jq .

# Ao contrário: minify (saída compacta)
jq -c . data.json

Selecionando campos

Entre em objetos com .key, e em arrays com []:

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

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

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

# Tira as aspas de JSON com -r (raw output)
jq -r '.[].name' users.json

Filtrando com select

# Mantenha só os objetos que casam com uma condição
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# Comparação numérica
jq '.[] | select(.age > 30)' users.json

Transformando com map e construção de objetos

# Refaça cada elemento como um novo objeto
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

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

# Encadeie filtros com |
jq '.items | map(.price) | add' order.json   # soma de todos os preços

Receitas comuns

Remodelando objetos: to_entries / from_entries

Os dois transformadores de forma de objeto mais úteis em jq:

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

# Descarta keys cujo valor seja 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", ...}

Interpolação e formatos de saída: \(.x), @csv, @json, @base64

jq tem interpolação de strings e format strings embutidas para transformar JSON em outros formatos:

# Interpolação de string dentro de uma string entre aspas
jq -r '"\(.user) bought \(.items|length) items"' order.json

# Uma linha 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 um valor em Base64 (útil para tokens / data URIs)
jq -r '.payload | @base64' message.json
# Lado de decodificação: jq aceita @base64d em versões mais novas

Validando JSON com jq

Como jq sai com código não-zero em entrada inválida, jq empty file.json é uma checagem limpa de validade para scripts e CI —— veja Como validar JSON para mais abordagens de validação.

Quando uma ferramenta no navegador é mais rápida

jq brilha em scripts e pipelines, mas para algo pontual —— formatar uma resposta colada, inspecionar uma estrutura desconhecida, ou reparar JSON quebrado —— uma ferramenta no navegador não precisa de instalação nem de escape de shell:

• JSON Fix —— formata e repara JSON em um passo
• JSON Viewer —— explore respostas grandes como uma árvore que dá para recolher
• Como formatar JSON —— formatação em código e linha de comando

Perguntas frequentes

Como faço pretty-print de JSON com jq?

Execute jq . file.json —— o filtro identity . retorna a entrada e jq a formata por padrão. Use -c para saída compacta.

Como extraio um único campo com jq?

Use um filtro de caminho como jq '.data.token', e adicione -r para saída crua se quiser o valor sem as aspas.

Como filtro um array JSON com jq?

Itere com .[] e aplique select(), por exemplo jq '.[] | select(.active == true)'.

Dá para validar JSON com jq?

Sim —— jq empty file.json parseia a entrada e sai com código não-zero se for inválida, o que o torna útil em CI. Para detalhes veja Como validar JSON.

Continue lendo

• Como formatar JSON —— jq, JavaScript, Python e formatação no navegador
• Como minificar JSON —— saída compacta com jq -c e além
• Como validar JSON —— incluindo jq empty em CI
• JSON Viewer —— uma alternativa no navegador para explorar JSON