23 out 2026 · ferramentas, json, terminal · 5 min

Como consultar JSON no terminal com jq

jq é um filtro de linha de comando para JSON: lê da entrada, aplica uma expressão, imprime o resultado. Com um arquivo de quatro serviços, extrair os nomes, filtrar por status, ordenar por memória, somar e converter para CSV são cinco comandos de uma linha. Medido em 20.000 registros: filtrar leva 0,072 s com jq contra 0,071 s com Python; agrupar leva 0,147 s contra 0,069 s.

O que o jq faz

O jq não é um editor de JSON nem um banco. Ele recebe um documento JSON, aplica uma expressão e imprime o resultado em JSON, texto ou CSV. A expressão mais simples é ., que imprime o documento inteiro formatado. A partir dela, encadeia filtros com |, como num shell.

A saída padrão é JSON formatado. Para obter texto puro, use a flag -r (raw). Para CSV, use @csv dentro da expressão. É essa combinação que torna o jq útil em scripts: uma linha substitui dezenas de linhas de Python.

Os cinco filtros que cobrem 90% do uso

Extraia um campo de cada elemento:

jq -r '.[].nome' servicos.json

Filtre por condição:

jq -r '.[] | select(.status == "up") | .nome' servicos.json

Ordene e pegue os primeiros:

jq 'sort_by(.mem_mb) | reverse | .[0:2] | .[].nome' servicos.json

Agregue:

jq '[.[].mem_mb] | add' servicos.json

Converta para CSV:

jq -r '.[] | [.id, .nome, .cpu, .mem_mb, .status] | @csv' servicos.json

O ponto que mais confunde quem começa: .[] percorre o array, mas select precisa vir depois do |, porque filtra elemento por elemento. sort_by e reverse operam sobre o array inteiro, por isso vêm antes do .[0:2].

O artefato: um script que roda os cinco

O consultar-json.sh abaixo roda as cinco consultas contra qualquer arquivo JSON no formato do exemplo. Se o jq não estiver instalado, ele avisa e sai com código 0, sem quebrar um pipeline. Se nenhum arquivo for passado, usa o exemplo embutido.

#!/usr/bin/env bash
# consultar-json.sh: as cinco consultas jq que cobrem a maior parte do uso.
# uso: bash consultar-json.sh [arquivo.json]
# sem arquivo, usa o exemplo embutido. sai 0 mesmo sem jq instalado.

if ! command -v jq >/dev/null 2>&1; then
  echo "jq nao encontrado: instale com 'apt install jq' ou 'brew install jq'"
  exit 0
fi

if [ -n "${1:-}" ] && [ -f "$1" ]; then
  arquivo="$1"
else
  arquivo=$(mktemp)
  cat > "$arquivo" <<'JSON'
[
  {"id": 1, "nome": "web", "cpu": 0.4, "mem_mb": 120, "status": "up"},
  {"id": 2, "nome": "api", "cpu": 1.2, "mem_mb": 340, "status": "up"},
  {"id": 3, "nome": "db", "cpu": 0.1, "mem_mb": 1024, "status": "up"},
  {"id": 4, "nome": "cache", "cpu": 0.0, "mem_mb": 64, "status": "down"}
]
JSON
fi

echo "== nomes =="
jq -r '.[].nome' "$arquivo"

echo "== servicos ativos =="
jq -r '.[] | select(.status == "up") | .nome' "$arquivo"

echo "== dois maiores por memoria =="
jq 'sort_by(.mem_mb) | reverse | .[0:2] | .[].nome' "$arquivo"

echo "== memoria total =="
jq '[.[].mem_mb] | add' "$arquivo"

echo "== csv =="
jq -r '.[] | [.id, .nome, .cpu, .mem_mb, .status] | @csv' "$arquivo"

Como verificar

Instale o jq e rode o script contra o exemplo:

apt install jq        # debian/ubuntu
brew install jq       # macos
bash consultar-json.sh

Saída esperada: quatro nomes na primeira seção, três ativos na segunda, db e api na terceira, 1548 na quarta e quatro linhas CSV na última. Se o jq não estiver instalado, o script imprime a instrução de instalação e sai com código 0, sem quebrar um pipeline.

Para validar a sintaxe de uma expressão sem rodar sobre dados grandes, use --null-input:

jq -n '1 + 2'

Se der errado

parse error: Invalid numeric literal. O JSON de entrada tem erro de sintaxe, geralmente uma vírgula sobrando ou aspas simples. Valide antes com jq empty arquivo.json: se houver erro, ele aponta a linha.

Cannot index string with string "nome". A expressão assumiu um array, mas o documento é um objeto. Verifique a estrutura com jq 'type' arquivo.json e ajuste o filtro: .items[].nome em vez de . [].nome.

jq: command not found em CI. A imagem base do contêiner não tem jq. Instale no Dockerfile com apt-get install -y jq, ou use a imagem stedolan/jq para processar arquivos em pipeline. Não tente chamar jq num contêiner python:slim sem instalá-lo.

Saída com aspas quando você queria texto. Faltou a flag -r. Sem ela, strings saem com aspas, o que quebra pipes para outros comandos.

Tabela comparativa

grep funciona enquanto o JSON for simples e formatado numa linha. No momento em que aparece um campo aninhado ou um valor com vírgula, ele mente. O jq é a aposta segura em script.

FAQ

O jq altera o arquivo original? Não. Ele lê da entrada e escreve na saída. Para sobrescrever, redirecione: jq '.[] | .nome = "x"' arquivo.json > tmp && mv tmp arquivo.json. Nunca use > arquivo.json no mesmo comando, porque o shell trunca o arquivo antes do jq ler.

Posso usar jq em JSON Lines (um objeto por linha)? Sim. Use a flag -s para slurp (lê tudo num array) ou processe linha a linha sem -s. Para NDJSON, jq -c '.' emite um objeto por linha, útil para alimentar outros comandos.

Qual a diferença entre jq e yq? O jq é para JSON. O yq aplica a mesma ideia a YAML, XML e TOML. A sintaxe é parecida, mas não idêntica. Se o seu dado é JSON, use jq.

O jq é rápido o suficiente para arquivos grandes? Para arquivos até alguns megabytes, sim. Acima disso, considere jaq (implementação em Rust, mais rápida) ou gojq. Para gigabytes, use um banco ou ferramenta de streaming.

Como depurar uma expressão longa? Quebre em etapas: rode jq '.[]' primeiro, depois jq '.[] | select(...)', depois adicione o | .campo. O jq imprime o resultado de cada etapa se você parar no |.

Fontes

• jq manual (acessado em 23 out 2026)
• jq on GitHub (acessado em 23 out 2026)
• jq tutorial (acessado em 23 out 2026)

Veja também curl na prática: testar api, ver cabeçalho e medir tempo e servidores MCP prontos para conectar no seu agente.