ログ解析やAPIレスポンス加工を快適に。現場で本当に使う「jq」の厳選フィルタ術
目次
開閉
マイクロサービスのAPIを叩いた時や、クラウドのアクセスログを調査している時、ターミナルに数千行・数万行のJSONが怒涛のように流れてきて途方に暮れた経験は誰しもあるはずです。
手っ取り早く必要な値を取り出そうとして grep や awk、sed などのテキスト処理コマンドを組み合わせてみたものの、JSONの改行位置やネストの深さが変わった途端にスクリプトが壊れてしまう。そんな泥臭い試行錯誤を経験してきたエンジニアも多いのではないでしょうか。
JSONの操作には、JSON専用のクエリ言語を持つ jq （GitHub: jqlang/jq）を使うのが最も確実で堅牢です。
多機能すぎるあまり敬遠されがちな jq ですが、実務で日常的に叩くフィルタパターンは実は片手で数えられるほどに限られています。今回は現場で本当に役立つ厳選パターンをまとめました。
最短で身につける基本パイプライン
まずは構文の基本です。jq は標準入力から受け取ったJSONに対して「フィルタ式」を適用し、結果を標準出力に流します。
もっとも基本的な「整形（Pretty Print）」と「キー抽出」から確認しましょう。
# JSONを見やすく色分け・インデント整形する
curl -s https://api.example.com/users | jq '.'
# 特定のプロパティを取り出す
curl -s https://api.example.com/users | jq '.data.profile.name'
# クォート（""）を外して純粋な文字列値だけを取り出す（-r オプション）
curl -s https://api.example.com/users | jq -r '.data.profile.name'シェルスクリプトで別のコマンドの引数に値を渡す際は、必ず -r（--raw-output）を付与して前後のダブルクォートを取り除くのが基本です。
配列の展開と条件抽出（select）
現場で最も頻出するのが、「ユーザー一覧の配列から、特定条件に一致するレコードだけを絞り込む」という操作です。
ここでは以下のサンプルJSONを例に考えます。
[
{ "id": 1, "name": "Alice", "role": "admin", "active": true },
{ "id": 2, "name": "Bob", "role": "editor", "active": false },
{ "id": 3, "name": "Charlie", "role": "admin", "active": true }
]1. 配列を展開して全要素を走査する（[]）
配列の後ろに [] を付けると、配列全体ではなく「個別の要素ごとのストリーム」に分解されます。
# 配列内の全ユーザーのnameプロパティを一覧表示する
jq -r '.[].name' users.json
# 出力:
# Alice
# Bob
# Charlie2. 特定条件でフィルタリングする（select(...)）
select() 関数をパイプ（|）で繋ぐことで、指定した真偽条件に合致する要素だけを通過させます。
# activeがtrueかつroleがadminのユーザーを抽出
jq '.[] | select(.active == true and .role == "admin")' users.json正規表現による部分一致検索を行いたい場合は、test() 関数を組み合わせます。
# メールアドレスが "@example.com" で終わるユーザーを抽出
jq '.[] | select(.email | test("@example\\.com$"))' users.jsonオブジェクトの再構成（必要なフィールドだけの新しいJSONを作る）
APIレスポンスのフィールドが多すぎて視認性が悪い時、必要な項目だけを抜き出して自分好みのコンパクトなオブジェクトやTSV（タブ区切りテキスト）に変換するテクニックです。
1. 新しいオブジェクトに詰め直す
中括弧 {} の中に、出力したいキー名とマッピングしたい元のプロパティを指定します。
# idと名前だけのスリムなオブジェクト配列を作る
jq '[.[] | { userId: .id, userName: .name }]' users.json出力結果：
[
{ "userId": 1, "userName": "Alice" },
{ "userId": 2, "userName": "Bob" },
{ "userId": 3, "userName": "Charlie" }
]2. スプレッドシートや別コマンドに渡すためのTSV変換
@tsv フォーマットフィルタを活用すると、配列データを一瞬でタブ区切りテキストへ変換できます。
jq -r '.[] | [.id, .name, .role] | @tsv' users.json
# 出力:
# 1 Alice admin
# 2 Bob editor
# 3 Charlie adminこれをクリップボード（macOSなら pbcopy、Windowsなら clip.exe）に流し込めば、そのままExcelやGoogleスプレッドシートに綺麗にペーストできます。
編集長
実務で役立つ小ワザ集
存在しないキーでもエラーにしない（オプショナルチェーン）
ネストの深いJSONで、途中のオブジェクトが存在しない（nullである）可能性がある場合は、ドットの前に ? を付与します。
# metadataが存在しなくてもエラーにならずnullを返す
jq '.data.metadata?.tags' response.jsonトップレベルのキー一覧を確認する（keys）
巨大なJSONの構造を素早く把握したいときは、keys 関数で第1階層のプロパティ名だけを一覧化します。
jq 'keys' huge_response.jsonまとめ
jq は決して「黒魔術的な難解コマンド」ではありません。「. で潜る」「[] で展開する」「select() で絞る」「{} で再構成する」という4つの基本文法さえ押さえておけば、日常業務のJSON処理の9割以上は即座に解決できます。
ターミナルでのテキスト置換や正規表現の扱いに慣れておくと、CLIでのデータ処理速度がさらに上がります。テキスト処理の効率化については、以下の記事もぜひ参考にしてみてください。
都内IT企業に勤める業界20年のWebエンジニア。業務効率化・自動化スクリプトや快適な開発環境の構築、厳選したツール・ガジェットの活用法など、手元で実際に検証したリアルな一次情報をお届けします。
運営者プロフィール詳細を見る
