jq — Consulta e Transformação de JSON
Visão Geral
jq é a ferramenta CLI padrão para consultar e remodelar JSON. Esta skill cobre o uso prático em nível especializado: filtrar dados profundamente aninhados, transformar estruturas, agregar valores e compor jq em pipelines de shell. Todos os exemplos estão prontos para copiar e colar em fluxos de trabalho reais.
Quando Usar Esta Skill
- Use ao analisar saída JSON de APIs, ferramentas CLI (AWS, GitHub, kubectl, docker) ou arquivos de log
- Use ao transformar estrutura JSON (renomear chaves, achatar arrays, agrupar registros)
- Use quando o usuário precisar de
jqdentro de um script bash ou one-liner - Use ao explicar o que uma expressão
jqcomplexa faz
Como Funciona
jq recebe uma expressão de filtro e a aplica à entrada JSON. Filtros se compõem com pipes (|), e o jq lida nativamente com arrays, objetos, strings, números, booleanos e null.
Seleção Básica
# Extrair um campo
echo '{"nome":"alice","idade":30}' | jq '.nome'
# "alice"
# Acesso aninhado
echo '{"usuario":{"email":"[email protected]"}}' | jq '.usuario.email'
# Índice de array
echo '[10, 20, 30]' | jq '.[1]'
# 20
# Fatia de array
echo '[1,2,3,4,5]' | jq '.[2:4]'
# [3, 4]
# Todos os elementos do array
echo '[{"id":1},{"id":2}]' | jq '.[]'
Filtragem com select
# Manter apenas elementos correspondentes
echo '[{"funcao":"admin"},{"funcao":"usuario"},{"funcao":"admin"}]' \
| jq '[.[] | select(.funcao == "admin")]'
# Comparação numérica
curl -s https://api.github.com/repos/dono/repo/issues \
| jq '[.[] | select(.comments > 5)]'
# Testar se um campo existe e não é nulo
jq '[.[] | select(.email != null)]'
# Combinar condições
jq '[.[] | select(.ativo == true and .pontuacao >= 80)]'
Mapeamento e Transformação
# Extrair um campo de cada elemento do array
echo '[{"nome":"alice","idade":30},{"nome":"bob","idade":25}]' \
| jq '[.[] | .nome]'
# ["alice", "bob"]
# Abreviação: map()
jq 'map(.nome)'
# Construir um novo objeto por elemento
jq '[.[] | {usuario: .nome, anos: .idade}]'
# Adicionar um campo calculado
jq '[.[] | . + {senior: (.idade > 28)}]'
# Renomear chaves
jq '[.[] | {nome_usuario: .nome, endereco_email: .email}]'
Agregação e Reduce
# Somar todos os valores
echo '[1, 2, 3, 4, 5]' | jq 'add'
# 15
# Somar um campo entre objetos
jq '[.[].preco] | add'
# Contar elementos
jq 'length'
# Máximo / mínimo
jq 'max_by(.pontuacao)'
jq 'min_by(.criado_em)'
# reduce: acumulador personalizado
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15
# Agrupar por campo
jq 'group_by(.departamento)'
# Contar por grupo
jq 'group_by(.status) | map({status: .[0].status, contagem: length})'
Interpolação de Strings e Formatação
# Interpolação de strings
jq -r '.[] | "\(.nome) tem \(.idade) anos de idade"'
# Formatar como CSV (sem cabeçalho)
jq -r '.[] | [.nome, .idade, .email] | @csv'
# Formatar como TSV
jq -r '.[] | [.nome, .pontuacao] | @tsv'
# Codificar valor para URL
jq -r '.consulta | @uri'
# Codificar em Base64
jq -r '.dados | @base64'
Trabalhando com Chaves e Caminhos
# Listar todas as chaves de nível superior
jq 'keys'
# Verificar se uma chave existe
jq 'has("email")'
# Excluir uma chave
jq 'del(.senha)'
# Excluir chaves aninhadas de cada elemento
jq '[.[] | del(.id_interno, .dados_crus)]'
# Descida recursiva: encontrar todos os valores de uma chave em qualquer lugar da árvore
jq '.. | .id? // empty'
# Obter todos os caminhos até folhas
jq '[paths(scalars)]'
Condicionais e Tratamento de Erros
# if-then-else
jq 'if .pontuacao >= 90 then "A" elif .pontuacao >= 80 then "B" else "C" end'
# Operador alternativo: usar fallback se nulo ou falso
jq '.apelido // .nome'
# try-catch: pular erros em vez de parar
jq '[.[] | try .aninhado.valor catch null]'
# Suprimir saída nula com // empty
jq '.[] | .campo_opcional // empty'
Integração Prática com Shell
# Ler de arquivo
jq '.usuarios' dados.json
# Saída compacta (sem espaços) para pipe
jq -c '.[]' registros.json | while IFS= read -r registro; do
echo "Processando: $registro"
done
# Passar variável do shell para o jq
STATUS="ativo"
jq --arg s "$STATUS" '[.[] | select(.status == $s)]'
# Passar um número
jq --argjson limite 42 '[.[] | select(.valor > $limite)]'
# Juntar várias linhas JSON em um array
jq -s '.' registros.ndjson
# Vários arquivos: juntar todos em um array
jq -s 'add' arquivo1.json arquivo2.json
# Pipeline à prova de nulo a partir de um comando
kubectl get pods -o json | jq '.items[] | {nome: .metadata.name, status: .status.phase}'
# GitHub CLI: extrair números de PR
gh pr list --json number,title | jq -r '.[] | "\(.number)\t\(.title)"'
# AWS CLI: listar IDs de instâncias em execução
aws ec2 describe-instances \
| jq -r '.Reservations[].Instances[] | select(.State.Name=="running") | .InstanceId'
# Docker: mostrar nomes e imagens dos contêineres
docker inspect $(docker ps -q) | jq -r '.[] | "\(.Name)\t\(.Config.Image)"'
Padrões Avançados
# Transpor um objeto de arrays para um array de objetos
# Entrada: {"nomes":["a","b"],"pontuacoes":[10,20]}
jq '[.nomes, .pontuacoes] | transpose | map({nome: .[0], pontuacao: .[1]})'
# Achatar um nível
jq 'flatten(1)'
# Único por campo
jq 'unique_by(.email)'
# Ordenar, deduplicar e reindexar
jq '[.[] | .nome] | unique | sort'
# Walk: aplicar transformação a cada nó recursivamente
jq 'walk(if type == "string" then ascii_downcase else . end)'
# env: ler variáveis de ambiente dentro do jq
export API_KEY=segredo
jq -n 'env.API_KEY'
Melhores Práticas
- Sempre use
-r(saída raw) ao passar resultados dojqpara variáveis do shell ou outros comandos para remover as aspas do JSON - Use
--arg/--argjsonpara injetar variáveis do shell com segurança — nunca interpole variáveis do shell diretamente em strings de filtro - Prefira
map(f)a[.[] | f]para legibilidade - Use
-c(compacto) para pipelines JSON delimitados por nova linha; omita para depuração legível por humanos - Teste filtros interativamente com
jq -ne entrada literal antes de incorporar em scripts - Use
emptypara descartar elementos indesejados em vez de filtrar paranull
Notas de Segurança
jqé somente leitura por design — não pode escrever arquivos nem executar comandos- Evite incorporar valores de campos JSON não confiáveis diretamente em comandos do shell; sempre cite ou use
--arg
Armadilhas Comuns
-
Problema:
jqproduznullem vez do valor esperado Solução: Verifique erros de digitação nos nomes das chaves; usekeyspara inspecionar os nomes reais dos campos. Lembre-se que JSON diferencia maiúsculas de minúsculas. -
Problema: Números aparecem entre aspas na saída Solução: Use
--argjsonem vez de--argao injetar valores numéricos. -
Problema: O filtro funciona no terminal, mas falha em um script Solução: Garanta que a string do filtro use aspas simples no shell para evitar expansão de variáveis. Exemplo:
jq '.campo'e nãojq ".campo". -
Problema:
addretornanullem um array vazio Solução: Useadd // 0ouadd // ""para fornecer um valor padrão alternativo. -
Problema: Processar arquivos grandes é lento Solução: Use
jq --streamou mude parajstream/gronpara arquivos muito grandes.
Skills Relacionadas
@bash-pro— Encapsulando chamadas jq em scripts shell robustos@bash-linux— Padrões gerais de pipeline shell@github-automation— Usando jq com saída JSON do GitHub CLI
Limitações
- Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação, teste ou revisão especializada específica do ambiente.
- Pare e peça esclarecimentos se os requisitos de entrada, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.