Visão Geral

jq é uma ferramenta de linha de comando leve, projetada para manipular dados JSON. Ela permite analisar, filtrar, transformar e formatar JSON diretamente no termnial, facilitando o trabalho com dados estruturados em scripts e workflows de desenvolvimento.

Instalação

Para sistemas baseados em Debian, como Ubuntu, a instalação pode ser feita via gerenciador de pacotes:

apt install jq

Sintaxe e Uso Básico

A estrutura de comando do jq segue o padrão:

jq [opções] <filtro> [arquivo...]</filtro>

Opções essenciais incluem:

• -r: exibe a saída como string crua, removendo aspas do JSON.
• -c: gera saída compacta em uma única linha.
• -s: agrupa múltiplas entradas em um array para processamento.
• --arg: injeta variáveis externas no filtro.

O jq aceita dados de arquivos locais ou via redirecionamento padrão, como a saída de comandos curl.

Formatação de JSON

Para embelezar a saída JSON de uma string simples:

echo '{"cidade":"São Paulo","populacao":12300000}' | jq .

Extração de Campos

É possível extrair valores específicos de objetos JSON:

# Obter um único campo
echo '{"cidade":"São Paulo","populacao":12300000}' | jq '.cidade'

# Acessar campos aninhados
echo '{"local":{"cidade":"São Paulo"}}' | jq '.local.cidade'

# Extrair múltiplos campos simultaneamente
echo '{"cidade":"São Paulo","populacao":12300000}' | jq '.cidade, .populacao'

Trabalhando com Arrays

O jq oferece operações robustas para manipulação de arrays:

# Iterar sobre todos os elementos
echo '[5,10,15]' | jq '.[]'

# Acessar elemento por índice
echo '[5,10,15]' | jq '.[0]'

# Realizar fatiamento
echo '[5,10,15,20,25]' | jq '.[1:3]'  # Resultado: [10,15]

Filtros Essenciais

Encadeamento com Pipe

Use o operador de pipe para encadear múltiplas operações:

echo '[{"nome":"Lucas"},{"nome":"Maria"}]' | jq '.[] | .nome'

Operações Aritméticas

O jq suporta cálculos matemáticos diretamente:

echo '{"valor1":8,"valor2":12}' | jq '.valor1 + .valor2'

Manipulação de Strings

Funções integradas permitem transformar strings:

echo '{"texto":"exemplo"}' | jq '.texto | ascii_upcase'  # Converte para maiúsculas
echo '{"texto":"EXEMPLO"}' | jq '.texto | ascii_downcase'  # Converte para minúsculas
echo '{"texto":"exemplo"}' | jq '.texto | length'   # Calcula o comprimento

Recursos Avançados

Condições e Lógica

Incorpore estruturas condicionais nos filtros:

echo '{"idade":30}' | jq 'if .idade >= 18 then "maior" else "menor" end'

Mapeamento de Arrays

Transforme cada elemento de um array usando map:

echo '[2,4,6]' | jq 'map(. * 5)'

Filtragem com Select

Selecione elementos com base em critérios específicos:

echo '[{"pontos":85},{"pontos":72}]' | jq '.[] | select(.pontos >= 80)'

Uso de Variáveis

Passe parâmetros externos para os filtros:

jq --arg usuario "Carlos" '.nome = $usuario' config.json

Exemplos Práticos

Formatando Saída de API

Execute uma requisição HTTP e formate o JSON retornado:

curl -s https://api.example.com/dados | jq

Extração Compelxa de Dados

Dado o arquivo registros.json com conteúdo:

{

  "equipes": [

    {"membro": "Ana", "experiencia": 5},

    {"membro": "Pedro", "experiencia": 2}

  ]

}

Para listar membros com mais de 3 anos de experiência:

jq '.equipes[] | select(.experiencia > 3) | .membro' registros.json

Geração de JSON com Cálculos

Crie um novo objeto JSON a partir de operações matemáticas:

echo '{"a":7,"b":3}' | jq '{produto: (.a * .b)}'

# Saída: {"produto": 21}