← 記事一覧
更新日: May 29, 20267 min read

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

コマンドラインで jq を学ぶ：インストール、整形、選択、フィルタ、map、JSON 編集——コピペできるレシピ付き。

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

jq とは？

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

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

タスク コマンド
整形 jq . file.json
Minify jq -c . file.json
1 つのフィールドを取得 jq '.data.token' resp.json
Raw 文字列（引用符なし） jq -r '.token' resp.json
配列の要素数 `jq '.
オブジェクトの key 一覧 jq 'keys' obj.json
行をフィルタ `jq '.[]
フィールドでソート jq 'sort_by(.age)'
フィールドの合計 `jq '[.[].amount]
key をソート jq --sort-keys . file.json
検証（exit code 経由） jq empty file.json

オブジェクトの再構成：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 エスケープ不要のブラウザツールが向いています：

よくある質問

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 を検証する方法。

jq で JSON の値を更新するには？

= で代入（例：jq '.status = "done"'）するか、|= で現在の値を変換（例：jq '.count |= . + 1'）します。jq は標準出力に書き出すので、一時ファイル経由で変更を保存してください —— in-place のフラグはありません。

jq にシェル変数を渡すには？

文字列には --arg name "$value"（数値や真偽値には --argjson）を使い、フィルタ内で $name として参照します。この方法は、フィルタ文字列に値を直接埋め込むより安全です。埋め込むと、引用符ひとつでフィルタが壊れることがあります。

続けて読む

出典

最終確認: 2026年6月。