jq

jq

フィルター構文はドキュメントに記載されているとおりに動作します。このファイルでは、ツールの選択方法と、よくある失敗を防ぐイディオムについて説明します。

jq を使わないほうがよい場合

• CSV／TSV には xsv、YAML には yq、JSON に対する分析 SQL には duckdb（read_json_auto）を使用します。
• インプレース編集には対応していません。一時ファイルに書き込んでから移動してください。jq '...' f.json > f.json とすると、jq が読み込む前に入力ファイルが切り詰められます。

重要なイディオム

jq -r '.name'                     # raw string output — no surrounding quotes
jq -c '.'                         # compact; required when piping NDJSON onward
jq '.field // "default"'          # alternative operator — survives null/missing
jq '.maybe?'                      # suppress "cannot index" instead of erroring out
jq --arg env prod '.[$env]'       # inject shell values; never interpolate into the filter string
jq -n --argjson d "$JSON" '$d.x'  # no input, build from arguments
jq -r '.[] | [.a, .b] | @csv'     # @csv / @tsv / @sh handle quoting correctly
jq 'to_entries | map(...) | from_entries'   # operate on keys
jq 'walk(if type == "object" then del(.secret) else . end)'   # recursive edit

一括読み込みとストリーム処理

-s は入力全体を 1 つの配列として読み込みます。便利ですが、すべてをメモリーに読み込みます。大きな入力や NDJSON の場合は、代わりにレコードごとに処理してください。

jq -c 'select(.important)' stream.ndjson    # one object per line, streaming
jq --stream 'select(length == 2)' huge.json # leaf-level streaming for a single huge document

group_by／sort_by を使う前にフィルターを適用してください。これらの関数は、セット全体をメモリー上に展開する必要があります。

エラーの診断

メッセージ	原因
parse error: Invalid numeric literal	JSON の形式が正しくありません。jq empty file.json で検証してください
Cannot index string with string	オブジェクト以外にフィールドアクセスしています。jq 'type' で確認してください
Cannot iterate over null	フィールドがありません。.field // [] を使用してください

jq empty file.json は素早く有効性を確認する方法です。何も出力されなければ有効です。debug は出力ストリームに影響を与えず、中間値を stderr に出力します。