jq — Consultando e Transformando JSON

Visão Geral

jq é a ferramenta padrão de linha de comando para consultar e remodelar JSON. Esta habilidade abrange uso prático em nível de especialista: filtrando dados profundamente aninhados, transformando estruturas, agregando valores e compondo jq em pipelines de shell. Cada exemplo está pronto para copiar e colar em fluxos de trabalho reais.

Quando Usar Esta Habilidade

• Use ao analisar a saída JSON de APIs, ferramentas de linha de comando (AWS, GitHub, kubectl, docker) ou arquivos de log
• Use ao transformar a estrutura JSON (renomear chaves, achatar arrays, agrupar registros)
• Use quando o usuário precisar de jq dentro de um script bash ou de uma linha única
• Use ao explicar o que uma expressão jq complexa faz

Como Funciona

jq recebe uma expressão de filtro e a aplica à entrada JSON. Os filtros se compõem com pipes (|), e jq lida nativamente com arrays, objetos, strings, números, booleanos e null.

Seleção Básica

# Extract a field
echo '{"name":"alice","age":30}' | jq '.name'
# "alice"

# Nested access
echo '{"user":{"email":"a@b.com"}}' | jq '.user.email'

# Array index
echo '[10, 20, 30]' | jq '.[1]'
# 20

# Array slice
echo '[1,2,3,4,5]' | jq '.[2:4]'
# [3, 4]

# All array elements
echo '[{"id":1},{"id":2}]' | jq '.[]'

Filtragem com select

# Keep only matching elements
echo '[{"role":"admin"},{"role":"user"},{"role":"admin"}]' \
  | jq '[.[] | select(.role == "admin")]'

# Numeric comparison
curl -s https://api.github.com/repos/owner/repo/issues \
  | jq '[.[] | select(.comments > 5)]'

# Test a field exists and is non-null
jq '[.[] | select(.email != null)]'

# Combine conditions
jq '[.[] | select(.active == true and .score >= 80)]'

Mapeamento e Transformação

# Extract a field from every array element
echo '[{"name":"alice","age":30},{"name":"bob","age":25}]' \
  | jq '[.[] | .name]'
# ["alice", "bob"]

# Shorthand: map()
jq 'map(.name)'

# Build a new object per element
jq '[.[] | {user: .name, years: .age}]'

# Add a computed field
jq '[.[] | . + {senior: (.age > 28)}]'

# Rename keys
jq '[.[] | {username: .name, email_address: .email}]'

Agregação e Redução

# Sum all values
echo '[1, 2, 3, 4, 5]' | jq 'add'
# 15

# Sum a field across objects
jq '[.[].price] | add'

# Count elements
jq 'length'

# Max / min
jq 'max_by(.score)'
jq 'min_by(.created_at)'

# reduce: custom accumulator
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15

# Group by field
jq 'group_by(.department)'

# Count per group
jq 'group_by(.status) | map({status: .[0].status, count: length})'

Interpolação e Formatação de Strings

# String interpolation
jq -r '.[] | "\(.name) is \(.age) years old"'

# Format as CSV (no header)
jq -r '.[] | [.name, .age, .email] | @csv'

# Format as TSV
jq -r '.[] | [.name, .score] | @tsv'

# URL-encode a value
jq -r '.query | @uri'

# Base64 encode
jq -r '.data | @base64'

Trabalhando com Chaves e Caminhos

# List all top-level keys
jq 'keys'

# Check if key exists
jq 'has("email")'

# Delete a key
jq 'del(.password)'

# Delete nested keys from every element
jq '[.[] | del(.internal_id, .raw_payload)]'

# Recursive descent: find all values for a key anywhere in tree
jq '.. | .id? // empty'

# Get all leaf paths
jq '[paths(scalars)]'

Condicionais e Tratamento de Erros

# if-then-else
jq 'if .score >= 90 then "A" elif .score >= 80 then "B" else "C" end'

# Alternative operator: use fallback if null or false
jq '.nickname // .name'

# try-catch: skip errors instead of halting
jq '[.[] | try .nested.value catch null]'

# Suppress null output with // empty
jq '.[] | .optional_field // empty'

Integração Prática com Shell

# Ler de um arquivo
jq '.users' data.json

# Saída compacta (sem espaços em branco) para posterior piping
jq -c '.[]' records.json | while IFS= read -r record; do
  echo "Processando: $record"
done

# Passar uma variável de shell para o jq
STATUS="active"
jq --arg s "$STATUS" '[.[] | select(.status == $s)]'

# Passar um número
jq --argjson threshold 42 '[.[] | select(.value > $threshold)]'

# Juntar várias linhas JSON em um array
jq -s '.' records.ndjson

# Múltiplos arquivos: juntar todos em um único array
jq -s 'add' file1.json file2.json

# Pipeline seguro contra nulos a partir de um comando
kubectl get pods -o json | jq '.items[] | {name: .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 \

…