jq チュートリアル: JSON のフィルタと変換

jq は、JSON のスライス、フィルタリング、変換を行うための標準的なコマンドラインツールです。ワンライナーを、API レスポンス、ログファイル、設定ファイルを扱うための強力なクエリ言語に変えてくれます。本チュートリアルでは、インストール、毎日使う中核 filter、そして実際によくあるタスク向けのコピペできる recipe 集を扱います。

jq とは？

jq はファイルまたは標準入力から JSON を読み、filter を適用して、JSON（または raw テキスト）を標準出力に書き出します。デフォルトで整形され、データはどこにも送信されません —— ローカルバイナリなので、機微な payload にも適しています。

jq のインストール

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget or choco)
winget install jqlang.jq

# 確認
jq --version

Identity Filter：何でも整形

最もシンプルな filter . は入力をそのまま返します —— つまり jq は即席の整形ツールになります：

# ファイルを整形
jq . data.json

# curl レスポンスを整形
curl -s https://api.example.com/users | jq .

# 逆に minify（コンパクト出力）
jq -c . data.json

フィールドの選択

オブジェクトには .key、配列には [] で潜ります：

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# 配列の全要素
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# 各配列要素から 1 つのフィールド
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# -r で JSON の引用符を外す（raw output）
jq -r '.[].name' users.json

select でフィルタリング

# 条件に合うオブジェクトだけ残す
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# 数値比較
jq '.[] | select(.age > 30)' users.json

map とオブジェクト構築で変形する

# 各要素を新しいオブジェクトに作り直す
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# フラットな値リストを取り出す
jq '[.[].email]' users.json     # ["a@x.com", ...]

# filter を | で繋ぐ
jq '.items | map(.price) | add' order.json   # 全 price の合計

よく使う Recipe

オブジェクトの再構成：to_entries / from_entries

jq の中でもっとも有用なオブジェクト形状の変換器が 2 つ：

# 全 key を改名（ここでは小文字化）
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# 値が null の key を落とす
jq 'with_entries(select(.value != null))' file.json

# オブジェクト ⇄ ペアの配列
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

補間と出力フォーマット：\(.x)、@csv、@json、@base64

jq には文字列補間と、JSON を別の形式に変換するための format 文字列 が組み込まれています：

# 引用符付き文字列内での文字列補間
jq -r '"\(.user) bought \(.items|length) items"' order.json

# オブジェクトごとに 1 行の CSV
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# Shell 用のインライン JSON（エスケープ済み文字列リテラル）
jq -r '.user | @json' record.json

# 値を Base64 エンコード（token / data URI で便利）
jq -r '.payload | @base64' message.json
# デコード側: 新しい版の jq は @base64d をサポート

jq で JSON を検証する

jq は不正な入力に対して非ゼロ exit code を返すので、jq empty file.json はスクリプトや CI でのきれいな妥当性チェックになります —— その他の検証手段は JSON を検証する方法 を参照。

ブラウザツールの方が速いとき

jq はスクリプトやパイプラインで真価を発揮しますが、その場限りの作業 —— 貼り付けたレスポンスを整形する、見慣れない構造を覗く、壊れた JSON を修復する —— には、インストール不要・shell エスケープ不要のブラウザツールが向いています：

• JSON Fix —— 整形と修復をワンステップで
• JSON Viewer —— 大きなレスポンスを折りたたみツリーとして探索
• JSON のフォーマット方法 —— コードとコマンドラインでのフォーマット

よくある質問

jq で JSON を整形するには？

jq . file.json を実行します —— identity filter . は入力を返し、jq はデフォルトで整形します。コンパクト出力にしたければ -c を使います。

jq で 1 つのフィールドを取り出すには？

jq '.data.token' のようなパス filter を使い、引用符なしの raw 値が欲しければ -r を追加します。

jq で JSON 配列をフィルタするには？

.[] でイテレートし、select() を適用します。例：jq '.[] | select(.active == true)'。

jq は JSON を検証できますか？

はい —— jq empty file.json は入力をパースし、不正なら非ゼロで終了するので、CI で重宝します。詳細は JSON を検証する方法。

続けて読む

• JSON のフォーマット方法 —— jq、JavaScript、Python、ブラウザでのフォーマット
• JSON を minify する方法 —— jq -c 等でのコンパクト出力
• JSON を検証する方法 —— CI での jq empty など
• JSON Viewer —— JSON 探索のためのブラウザ代替手段