Trabalhando com JSON na linha de comando com o jq

Objetivo

Extrair, filtrar ou remodelar JSON vindo da resposta de uma API, de uma linha de log ou de um arquivo de configuração dentro de um pipeline, sem precisar escrever um programa descartável.

Pré-requisitos

jq instalado; entrada que seja JSON válido ou um fluxo de textos JSON; alguma noção da estrutura da entrada (jq 'keys', jq '.[0]' e jq 'paths' ajudam a explorá-la).

Passos

1. Confirme que a entrada é interpretada sem erros e veja a sua estrutura: jq . imprime o JSON formatado; em entradas grandes, jq -c '.[0]' ou jq 'keys' é mais fácil de ler.
2. Navegue: .foo.bar e .[0] acessam por chave ou índice, .[] itera sobre os elementos de um array ou sobre os valores de um objeto, e .foo? suprime o erro quando a entrada não é um objeto. Encadeie filtros com |.
3. Filtre e remodele: .items[] | select(.status == "open") | {id, name}; map(f) aplica um filtro a cada elemento; to_entries, from_entries e with_entries(f) convertem entre objetos e listas de pares chave-valor; a // b resulta em b quando a produz apenas null ou false.
4. Passe valores do shell com --arg name value (sempre uma string) ou --argjson name json (com tipo) e use $name no filtro. O manual observa que --arg foo 123 associa a string "123", e não um número.
5. Escolha o formato de saída conforme o próximo programa: -r (--raw-output) escreve strings sem aspas; -c imprime JSON compacto em uma única linha; @tsv, @csv e @sh formatam arrays para consumo como texto separado por tabulações, CSV ou shell POSIX; --raw-output0 separa as saídas com NUL quando os valores podem conter quebras de linha.
6. Trate várias entradas: por padrão, o filtro é executado uma vez para cada texto JSON do fluxo; -s (--slurp) reúne todos em um único array; -n (--null-input) executa o filtro uma única vez com null como entrada, o que permite construir JSON do zero: jq -n --arg a "$x" '{a: $a}'.
7. Faça a ausência de dados causar falha: -e (--exit-status) define o código de saída como 1 se a última saída for null ou false, e como 4 se nenhum resultado válido for produzido; teste esse código nos scripts em vez de verificar se há uma string vazia.

Resultado esperado

Um pipeline de uma linha que produz exatamente o campo ou a estrutura necessários, com as aspas corretas para o próximo programa, e um código de saída diferente de zero quando os dados estão ausentes.

Limites e base de verificação

A semântica segue o manual do jq citado. O jq carrega cada texto JSON por inteiro, a menos que se use --stream; por isso, documentos muito grandes exigem streaming ou outra ferramenta. O manual afirma que o tratamento de números no jq mudou ao longo do tempo e depende das opções de compilação, e que a leitura pode perder precisão em números muito grandes ou muito precisos; consulte o manual da versão instalada antes de usar o jq em operações aritméticas com esses valores. Não se afirma nenhuma medição de tempo.