Filtragem e seleção de JSON com pipelines do jq

jq é uma ferramenta de linha de comando leve e poderosa para analisar, filtrar e transformar dados JSON. Ele é o sed do JSON — você envia JSON para ele por um fluxo e recebe uma saída estruturada.

• Já vem instalado na maioria das distribuições Linux ou está disponível por meio de apt install jq / brew install jq
• Funciona perfeitamente em fluxos do shell com curl, cat e outras ferramentas
• Oferece suporte a filtragem, mapeamento, redução e conversão de formato

A chamada básica é: jq '<filter>' file.json ou por fluxo, como em cat file.json | jq '<filter>'. O filtro . (ponto) é a identidade — ele formata de maneira legível todo o documento.

Para acessar um campo em um objeto JSON, use a notação de ponto: .fieldName. Você pode encadear seletores para navegar por objetos aninhados.

• .name — campo de nível superior
• .address.city — campo aninhado
• ."field-with-dash" — campos com caracteres especiais precisam de aspas

Se o campo não existir, jq retornará null em vez de produzir um erro. Isso torna seu uso seguro em scripts, sem verificações adicionais de nulo para campos opcionais.

As matrizes JSON são acessadas com a notação de colchetes. jq usa índices começando em zero.

• .items[0] — primeiro elemento
• .items[-1] — último elemento
• .items[1:3] — fatia (do índice 1 até, mas sem incluir, o 3)
• .items[] — desmembrar a matriz: gera cada elemento como um valor separado (este é o iterador)

O iterador [] é fundamental para os fluxos do jq — ele permite aplicar filtros posteriores a cada elemento de maneira independente.

Assim como o canal do shell |, jq tem seu próprio operador interno de canalização. Ele passa a saída de um filtro como entrada para o próximo.

• jq '.users[] | .name' — itera pelos usuários e depois extrai o nome de cada um
• jq '.data | .items[] | .id' — navega até os dados, desmembra os itens e extrai o identificador

Os canais dentro de uma expressão jq permitem criar transformações complexas passo a passo. Cada estágio recebe o que o estágio anterior produziu — inclusive vários valores vindos de um iterador.

Ideia principal: quando um iterador produz N valores, cada filtro posterior é executado N vezes, uma vez para cada valor.

O filtro select(condition) deixa um valor passar somente se a condição for verdadeira; caso contrário, não produz saída. Ele é o equivalente, no jq, a grep ou WHERE em SQL.

• select(.age > 18) — mantém os objetos em que a idade é maior que 18
• select(.status == "active") — verifica a igualdade
• select(.name | startswith("A")) — teste de texto aninhado

Combine select com o iterador para filtrar matrizes: .items[] | select(.active) gera somente os elementos em que .active é verdadeiro.

jq permite remodelar dados construindo novos objetos com {} e novas matrizes com [].

• {name: .name, city: .address.city} — seleciona e renomeia campos em um novo objeto
• [.items[] | .id] — reúne os valores iterados novamente em uma matriz
• Forma abreviada: {name, age} equivale a {name: .name, age: .age}

Envolver um fluxo em [...] é chamado de construção de matriz e é essencial quando você quer uma matriz JSON como saída, em vez de um fluxo de valores.

JSON do mundo real geralmente é profundamente aninhado. jq oferece duas ferramentas para navegação profunda:

• .a.b.c — caminho explícito quando a estrutura é conhecida
• .. | .fieldName? — descida recursiva: percorre cada nó da árvore e gera os valores nos locais em que a chave existe

O operador ? (tentativa) suprime erros quando um campo não existe em determinado nó, o que é essencial ao usar descida recursiva em árvores heterogêneas.

Use a descida recursiva com moderação em documentos grandes — ela visita cada nó e pode ser lenta. Prefira caminhos explícitos quando a estrutura for previsível.

Um dos casos de uso mais comuns do jq é analisar respostas de APIs REST obtidas com curl. Combinar curl -s (silencioso) com um fluxo jq fornece uma extração de dados limpa e adequada para scripts.

• Extrair um único valor: curl -s URL | jq '.field'
• Criar uma tabela-resumo: iterar por uma matriz e reconstruir objetos apenas com os campos necessários
• Usar -r (saída bruta) para remover as aspas ao redor dos valores de texto — essencial ao atribuí-los a variáveis do shell

Dica: sempre adicione -r quando a saída do jq for usada como variável do shell ou canalizada para outro comando.

jq oferece duas funções convenientes de ordem superior para transformar coleções:

• map(f) — aplica o filtro f a cada elemento de uma matriz, retornando uma nova matriz. Equivale a [.[] | f].
• map_values(f) — aplica f a cada valor de um objeto ou matriz, preservando as chaves/índices.

Essas funções são mais legíveis do que envolver manualmente os fluxos em [] e representam o estilo idiomático do jq para transformações que devem continuar sendo matrizes.

Dados JSON de fontes externas geralmente são inconsistentes — campos podem estar ausentes ou nulos. jq oferece o operador alternativo // (barra dupla) para fornecer um valor padrão.

• .nickname // "anonymous" — usa .nickname se ele não for nulo/falso; caso contrário, usa "anonymous"
• .count // 0 — valor padrão numérico
• Combine com select: select((.status // "inactive") == "active")

Isso é muito mais conciso do que o equivalente no shell, ${VAR:-default}, e pode ser combinado facilmente dentro de fluxos mais longos.

O registro estruturado em JSON é padrão nos sistemas modernos. Veja um script realista que lê um arquivo de registro JSON delimitado por quebras de linha, filtra as entradas de erro e formata um resumo legível.

Principais padrões utilizados:

• -c (saída compacta) — um objeto JSON por linha, útil para canalizar para laços do shell
• --arg name value — injeta uma variável do shell como argumento de texto do jq
• select para filtragem por nível de registro
• -r para saída de texto bruto adequada para echo

Teste sua compreensão de como select() funciona dentro de um fluxo do jq.

Considere o seguinte comando:

Qual será o resultado?

Você aprendeu os principais recursos do jq para navegar e filtrar JSON na linha de comando:

• Notação de ponto (.field, .a.b.c) seleciona campos de objetos
• Acesso a matrizes (.[0], .[]) indexa e percorre matrizes
• Operador de pipe (|) encadeia filtros; cada etapa processa todos os valores da etapa anterior
• select(cond) filtra valores, mantendo apenas aqueles em que a condição é verdadeira
• Construção de objetos/matrizes ({}, [], map()) reorganiza os dados em novas estruturas
• Operador alternativo (//) fornece valores padrão para campos nulos ou ausentes
• Opção -r remove as aspas para atribuição a variáveis do shell; --arg injeta variáveis do shell com segurança
• Descida recursiva (.. | .field?) pesquisa árvores profundamente aninhadas quando o caminho é desconhecido

Com esses blocos básicos, você pode transformar qualquer resposta de uma API JSON, arquivo de registro ou configuração exatamente nos dados de que seus scripts precisam — tudo sem sair do terminal.