jqチートシート - JSON処理コマンドラインリファレンス

概要

jq は JSON データを変換・抽出するためのコマンドラインツールです。sed や awk が行指向のテキストに対して行う処理を、jq は構造化された JSON に対して行います。HTTP API のレスポンス整形、設定ファイルの加工、ログ解析、CI スクリプトでの値抽出など幅広く使われています。本チートシートは現行版 jq 1.7 系を対象に、よく使う構文と実用レシピを整理します。

基本コマンド

主要オプション

基本フィルタ

値の生成

1, 2, 3              # 3 つの値
"hello"              # 文字列
true, false, null    # 真偽値・null
[1, 2, 3]            # 配列リテラル
{a: 1, b: 2}         # オブジェクトリテラル
{user, id: .uid}     # ショートハンド（user: .user）

配列操作

オブジェクト操作

文字列操作

"User: \(.name) (\(.age))"

数値・型

制御構文

if .age >= 20 then "adult" else "minor" end

# elif
if .x == 0 then "zero"
elif .x > 0 then "positive"
else "negative"
end

# try / catch
try .a.b.c catch "missing"

# 代入
.user.name = "Alice"          # 上書き
.user.name |= ascii_upcase    # 既存値に関数適用
.tags += ["new"]              # 配列追加
.count += 1                   # 数値加算
.user |= . + {active:true}    # オブジェクト更新

# 削除
del(.user.password)

変数と束縛

. as $root | .users[] | {name, root_id: $root.id}

# 複数値の分解
.coord as [$x, $y] | $x + $y
{a, b} as {a: $a, b: $b} | $a * $b

reduce / foreach

# 配列の合計
reduce .[] as $x (0; . + $x)

# 累積配列
[foreach .[] as $x (0; . + $x; .)]

関数定義

def double: . * 2;
def addn(n): . + n;
def stats: {min: min, max: max, count: length};

[1,2,3] | map(double) | stats

実用レシピ

1. 配列から特定フィールドだけ抽出

jq '[.users[] | {id, name}]' data.json

2. 条件で絞り込み

jq '.users[] | select(.age >= 20 and .active)' data.json

3. CSV 風出力

jq -r '.users[] | [.id, .name, .email] | @csv' data.json
jq -r '.users[] | [.id, .name] | @tsv' data.json

4. キーをソートして出力

jq -S '.' config.json

5. ネストの深いキーのデフォルト

jq '.user.profile.bio // "no bio"' user.json

6. 環境変数との連携

NAME="Alice" jq --arg name "$NAME" '.users[] | select(.name == $name)' data.json

7. JSON Lines を読む

# 既定で JSON Lines もそのまま読める
cat events.jsonl | jq 'select(.level == "error")'

# 1 配列にまとめる
jq -s '.' events.jsonl > events.json

8. オブジェクトを配列に展開

jq 'to_entries | map({k: .key, v: .value})' map.json

9. 値で集計

jq '[.events[] | .type] | group_by(.) | map({type: .[0], count: length})' data.json

10. ネストしたフィールドを更新

jq '.user.profile.bio = "updated"' user.json
jq '(.users[] | select(.id == 1)).active = false' data.json

11. 複数 JSON をマージ

jq -s '.[0] * .[1]' a.json b.json

12. 配列差分

jq -n --slurpfile a a.json --slurpfile b b.json '$a[0] - $b[0]'

13. キー名の一括変換

jq 'with_entries(.key |= ascii_downcase)' data.json

14. null や空文字を除外

jq '.users | map(select(.email != null and .email != ""))' data.json

15. JSON を Bash 変数に取り込む

NAME=$(jq -r '.user.name' data.json)
mapfile -t IDS < <(jq -r '.users[].id' data.json)

16. curl の API レスポンスから値抜き出し

curl -s https://api.github.com/repos/jqlang/jq | jq -r '.stargazers_count'

17. 配列要素の追加・削除

jq '.tags += ["new-tag"]' data.json
jq '.tags -= ["old-tag"]' data.json
jq 'del(.tags[1])' data.json

18. パスを取得

jq 'paths(scalars)' data.json
jq 'paths(. == "target")' data.json

19. 再帰的に値を探す

jq '.. | objects | select(has("email")) | .email' data.json

20. テンプレ的な文字列生成

jq -r '.users[] | "\(.id),\(.name),\(.email)"' data.json

よく使うフォーマット出力

トラブルシューティング

Tips & ベストプラクティス

• フィルタは必ずシングルクォートで囲んでシェル展開を防ぐ。
• 値だけ欲しいときは -r を忘れない（特に変数代入時）。
• 複数行の複雑なフィルタは def で関数化して読みやすくする。
• パイプライン | は左から右へ値を流す。, は同じ入力に対して複数の値を出力する。両者を混同しないこと。
• 安全アクセスは ? を活用する（.a.b?.c?）。
• スクリプトに埋め込むときは --arg / --argjson で値を渡し、文字列連結による注入を避ける。
• 集計は group_by → map パターンで簡潔に書ける。
• フォーマット出力は @csv / @tsv を使えば、エスケープを自分で書く必要がない。
• 1.7 系では SQL 風の ltrimstr / rtrimstr、改善された I/O オプションが入っている。最新版を使うのが安全。
• フィルタを試すときは jqplay.org の利用が便利。

さらに進んだ機能

入力ストリーム関数

# 複数 JSON を順に処理
jq -n 'inputs | select(.level == "error")' a.json b.json c.json

# パイプの中間値をデバッグ
jq '.users | map(. | debug("user")) | length' data.json

パスと割り当て

# 値を持つすべてのパスを列挙
[paths]

# スカラー値のパスのみ
[paths(scalars)]

# 特定値を持つパス
[paths(. == "target")]

# パスを使った代入
getpath(["a", "b"])
setpath(["a", "b"]; 42)
delpaths([["a", "b"], ["c"]])

walk 関数

walk(f) でツリー全体を再帰的に変換できます。

# 文字列値を全て大文字に
jq 'walk(if type == "string" then ascii_upcase else . end)' data.json

# null を空文字に置換
jq 'walk(if . == null then "" else . end)' data.json

env と $ENV

HOME_PATH=/srv jq -n '{home: env.HOME_PATH, all: $ENV}'

SQL 風スタイル関数

jq '[.users[]] | INDEX(.id)' data.json
# => { "1": {...}, "2": {...} }

モジュール / インポート

jq はライブラリパスからモジュールを読み込めます。~/.jq または -L <path> で指定したディレクトリ配下に .jq ファイルを配置します。

# ~/.jq/lib.jq
def percent(total): . / total * 100;

jq 'import "lib" as lib; .count | lib::percent(100)' data.json

組み込み定義は include で取り込めます。

参考リソース

• jq マニュアル（公式）
• jq ダウンロード / インストール
• jq GitHub リポジトリ
• jq クックブック（GitHub Wiki）