jq は JSON を入力として受け取り、フィルタで抽出や整形・変換・集計を行う CLI ツールです。sed/awk/grep の JSON 版のように扱え、スクリプトやパイプラインでの自動処理に最適です。(JqLang)
フィールド抽出、配列の加工、ログの整形、API レスポンスの整形・要約などで日常的に使われます。(JqLang)
構文（Syntax）
# 基本形
jq [OPTIONS] 'FILTER' [FILE...]
# 代表例
curl ... | jq '.' # 整形表示（pretty print）
jq -r '.items[] | .name' data.json # 生文字列で出力
jq -f script.jq input.json # フィルタをファイルから読み込み
jq -n --arg k v '{(env.k):$v}' # 入力なしで JSON を構築
- フィルタ（
FILTER）は jq 言語で記述します。.は恒等（入力をそのまま出力）。(JqLang)
主なオプション一覧
| オプション | 説明 | 使用例 |
|---|---|---|
-r, --raw-output | 文字列を JSON 文字列でなく生の文字列で出力 | jq -r '.version' package.json (JqLang) |
-j, --join-output | -r の派生。改行を付けないで連結出力 | jq -j '.[]' (JqLang) |
-c, --compact-output | 1 行に圧縮して出力（機械処理向き） | jq -c '.items' (JqLang) |
-S, --sort-keys | オブジェクトの キーをソートして出力 | jq -S '.' (JqLang) |
-C / -M | 強制カラー / モノクロ出力 | `jq -C ‘.’ |
--tab / --indent N | インデントをタブ / スペース数 N に変更 | jq --indent 4 '.' (JqLang) |
-s, --slurp | 入力全体を 配列1件として読み込む | jq -s 'add' files*.json (JqLang) |
-R, --raw-input | 入力を JSON として 解釈せず生テキストで受け取る | jq -R 'split(\":\")' (JqLang) |
-n, --null-input | 入力を読まず null を 1 度だけ流す（JSON の生成に） | jq -n '{now:now}' (JqLang) |
--stream | 巨大 JSON を ストリーミングで処理（path,leaf のペア） | jq --stream '...reduce...' (JqLang) |
--seq | application/json-seq 形式で入出力 | jq --seq '.' (JqLang) |
-f, --from-file FILE | フィルタをファイルから読み込む | jq -f filter.jq data.json (JqLang) |
-L DIR | モジュール検索パスを追加（import 用） | jq -L lib -f main.jq (JqLang) |
--arg name val | 文字列変数を $name に注入 | jq --arg q "tokyo" '.city==$q' (JqLang) |
--argjson name json | JSON 値を変数として注入 | jq --argjson ids '[1,2]' 'map(select(.id IN($ids[])))' (JqLang) |
--argfile name file / --slurpfile name file | ファイル内容を変数へ（JSON/行スループ） | jq --slurpfile cfg cfg.json '. + $cfg[0]' (JqLang) |
-e, --exit-status | 最終結果で 終了コード を設定（監視/判定に便利） | jq -e 'length>0' (JqLang) |
実行例
整形表示とキー抽出
説明: API レスポンスを整形し、配列要素の名前だけ取り出します。
コマンド:
curl -s https://api.github.com/repos/jqlang/jq/commits?per_page=3 \
| jq '.[] | {sha, author: .commit.author.name}'
jq -r '.[].commit.message' commits.json
(JqLang)
条件抽出と並び替え
説明: .items の中から active==true だけに絞り、名前でソート。
コマンド:
jq '.items | map(select(.active)) | sort_by(.name) | .[].name' data.json
（select/ sort_by は定番フィルタです） (JqLang)
生テキストから JSON を組み立てる（ログ処理）
説明: key:value 形式の行を -R で読み、オブジェクトへ変換。
コマンド:
cat kv.txt | jq -R 'split(":") | { (.[0]): .[1] }' | jq -s 'add'
(JqLang)
巨大 JSON をストリーミングで集計（メモリ節約）
説明: ルート配列が非常に大きい場合でも --stream で段階処理。
コマンド:
jq --stream 'foreach ( .[] as $p (0; if ($p|length==2 and ($p[0]|last)=="price") then . + $p[1] else . end ))' big.json
（--stream は path と値のペアを逐次出力します） (JqLang)
エラー例：入力が JSON でない
説明: 入力が JSON でないのに -R を付けないとパースエラーになります。
コマンド:
echo 'not json' | jq '.'
出力例（例）:
parse error: Invalid numeric literal at line 1, column 5
対処: テキストなら -R を使う、あるいは JSON に整形してから渡します。(JqLang)
関連コマンド
yq: YAML 用のフィルタ（内部でjq互換表現を使える版もあり）。jo: シェルから JSON を構築するユーティリティ。jqplay: ブラウザで jq を試せるプレイグラウンド。(jqプレイグラウンド)curl/httpie: API レスポンスを取得してjqに渡す相棒。
備考
- 引用とエスケープ: シェルのメタ文字と jq の構文が衝突しやすいので、Unix シェルでは 単一引用符
'...'を推奨（PowerShell/Windows では規則が異なる）。(JqLang) - 整形と配信: 人間向けは既定（カラー/整形）、機械向けは
-cと-r/-jを併用。(JqLang) - 大規模データ: 全体を配列化する
-sは簡単ですがメモリ消費が増えます。巨大データは--streamとreduce/foreachで段階処理を。(JqLang) - モジュール:
-Lで検索パスを追加しimportで関数を再利用できます。(JqLang) - 終了コード:
-eで 0/1/4 などに分岐でき、シェルの if/CI 判定に便利です。(JqLang)
参考
- 公式サイト（トップ）: https://jqlang.org/
- マニュアル（最新 / v1.8）: https://jqlang.org/manual/
- チュートリアル: https://jqlang.org/tutorial/
- GitHub（リポジトリ）: https://github.com/jqlang/jq
- jq Playground: https://play.jqlang.org/
- Arch Linux man ページ: https://man.archlinux.org/man/jq.1.en
コメント