ログ解析やAPIレスポンス加工を快適に。現場で本当に使う「jq」の厳選フィルタ術
目次
開閉
マイクロサービスのAPIを叩いた時や、クラウドのアクセスログを調査している時、ターミナルに数千行・数万行のJSONが怒涛のように流れてきて途方に暮れた経験は誰しもあるはずです。
手っ取り早く必要な値を取り出そうとして grep や awk、sed などのテキスト処理コマンドを組み合わせてみたものの、JSONの改行位置やネストの深さが変わった途端にスクリプトが壊れてしまう。そんな泥臭い試行錯誤を経験してきたエンジニアも多いのではないでしょうか。
JSONの操作には、JSON専用のクエリ言語を持つ jq (GitHub: jqlang/jq、公式マニュアル v1.7)を使うのが最も確実で堅牢です。
多機能すぎるあまり敬遠されがちな jq ですが、実務で日常的に叩くフィルタパターンは実は片手で数えられるほどに限られています。今回は手元の検証環境(macOS Sequoia / zsh および Windows 11 / PowerShell 7.4、jq-1.7.1)での実測ログを交えながら、現場で役立つ厳選パターンとOS別の落とし穴をまとめました。
最短で身につける基本パイプライン
まずは構文の基本です。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(users.json)を例に考えます。実務のAPIレスポンスと同様、一部のレコードで部署名(department)が null になっているケースを含めています。
[
{ "id": 101, "name": "山田 太郎", "email": "yamada.taro@example.com", "role": "admin", "active": true, "department": "Platform" },
{ "id": 102, "name": "見本 花子", "email": "mihon.hanako@example.jp", "role": "editor", "active": false, "department": "Marketing" },
{ "id": 103, "name": "仮名 次郎", "email": "kamei.jiro@example.com", "role": "admin", "active": true, "department": null }
]1. 配列を展開して全要素を走査する([])
配列の後ろに [] を付けると、配列全体ではなく「個別の要素ごとのストリーム」に分解されます。
# 配列内の全ユーザーのnameプロパティを一覧表示する
$ jq -r '.[].name' users.json
山田 太郎
見本 花子
仮名 次郎2. 特定条件でフィルタリングする(select(...))
select() 関数をパイプ(|)で繋ぐことで、指定した真偽条件に合致する要素だけを通過させます。
# activeがtrueかつroleがadminのユーザーを抽出(-c で1行1オブジェクトに圧縮出力)
$ jq -c '.[] | select(.active == true and .role == "admin")' users.json
{"id":101,"name":"山田 太郎","email":"yamada.taro@example.com","role":"admin","active":true,"department":"Platform"}
{"id":103,"name":"仮名 次郎","email":"kamei.jiro@example.com","role":"admin","active":true,"department":null}
正規表現による部分一致検索を行いたい場合は、test() 関数を組み合わせます。
# メールアドレスが "@example.com" で終わるユーザーを抽出
$ jq -r '.[] | select(.email | test("@example\\.com$")) | .email' users.json
yamada.taro@example.com
kamei.jiro@example.comオブジェクトの再構成(必要なフィールドだけの新しいJSONを作る)
APIレスポンスのフィールドが多すぎて視認性が悪い時、必要な項目だけを抜き出して自分好みのコンパクトなオブジェクトやTSV(タブ区切りテキスト)に変換するテクニックです。
1. 新しいオブジェクトに詰め直す
中括弧 {} の中に、出力したいキー名とマッピングしたい元のプロパティを指定します。
# idと名前だけのスリムなオブジェクト配列を作る
$ jq '[.[] | { userId: .id, userName: .name }]' users.json
出力結果:
[
{ "userId": 101, "userName": "山田 太郎" },
{ "userId": 102, "userName": "見本 花子" },
{ "userId": 103, "userName": "仮名 次郎" }
]2. スプレッドシートや別コマンドに渡すためのTSV変換
@tsv フォーマットフィルタを活用すると、配列データをタブ区切りテキストへ変換できます。
$ jq -r '.[] | [.id, .name, .role, (.department // "未所属")] | @tsv' users.json
101 山田 太郎 admin Platform
102 見本 花子 editor Marketing
103 仮名 次郎 admin 未所属
これをクリップボード(macOSなら pbcopy、Windowsなら clip.exe)に流し込めば、そのままExcelやGoogleスプレッドシートに綺麗にペーストできます。
実務でハマりやすい2つの罠と回避策
1. null 値の文字列連結による異常終了(Exit Code 5)
本番のAPIレスポンスでは、任意項目のフィールドに null が入ってくることが日常茶飯事です。これに気づかず文字列結合(+)を行うと、途中で jq がエラー終了します。
実際に上記の users.json(3件目の department が null)に対して単純な文字列連結を実行すると、以下のエラーが発生します。
$ jq -r '.[] | "User: " + .name + " (" + .department + ")"' users.json
User: 山田 太郎 (Platform)
User: 見本 花子 (Marketing)
jq: error (at users.json:5): string ("User: 仮名 次...) and null (null) cannot be added
この現象を防ぐには、代替演算子 //(Alternative operator)を使って null や false の場合のフォールバック値を指定するか、文字列補間構文 \(.property) を使います。
# 解決策A: 代替演算子 // でデフォルト文字列を補う
$ jq -r '.[] | "User: " + .name + " (" + (.department // "未設定") + ")"' users.json
User: 山田 太郎 (Platform)
User: 見本 花子 (Marketing)
User: 仮名 次郎 (未設定)2. Windows(PowerShell)とmacOS(zsh/bash)のクォート解釈の違い
MacとWindowsを行き来する開発環境で最も多いトラブルが、引数のクォート(' と ")の解釈差です。
macOSやLinux(bash / zsh)では、シングルクォート '...' の中に書いたダブルクォート " はそのまま jq バイナリへ渡されます。しかし、Windows PowerShell 5.1 では外部コマンドへ引数を渡す際にダブルクォートが剥がされる仕様があり、以下のようなエラーになります。
# Windows PowerShell 5.1 でそのまま実行した場合の失敗例
PS C:\work> jq '.[] | select(.role == "admin")' users.json
jq: error: admin/0 is not defined at <top-level>, line 1:
.[] | select(.role == admin)
jq: 1 compile error
Windows環境でこの問題を回避するには、以下のいずれかの方法をとります。
- PowerShell 7.3以降(
pwsh)を利用する: デフォルトでPSNativeCommandArgumentPassingがStandardに改善されており、macOS/Linuxと同じクォート構文がそのまま通ります。 - フィルタ式を別ファイル(
.jq)に切り出して-f(--from-file)で読み込む: OSやシェルのエスケープ仕様に一切影響されないため、チーム共有スクリプトでは最も確実です。
その他の便利な実務オプション
存在しないキーでもエラーにしない(オプショナル演算子 ?)
ネストの深いJSONで、途中のオブジェクトが存在しない(あるいは配列ではなくスカラー値になっている)可能性がある場合は、ドットの前に ? を付与します。
# metadataが存在しなくてもエラーにならずnullを返す
jq '.data.metadata?.tags' response.jsonトップレベルのキー一覧と件数を素早く確認する(keys, length)
巨大なJSONファイルの全体構造を把握したいときは、ファイル全体を画面に表示するのではなく、keys や length で骨格だけを確認します。
# 配列の要素件数を確認する
$ jq 'length' users.json
3
# 1件目のオブジェクトが持つプロパティ名一覧をソートして取得する
$ jq '.[0] | keys' users.json
[
"active",
"department",
"email",
"id",
"name",
"role"
]まとめ
jq は決して「黒魔術的な難解コマンド」ではありません。「. で潜る」「[] で展開する」「select() で絞る」「{} で再構成する」という4つの基本文法さえ押さえておけば、日常業務のJSON処理の9割以上は即座に解決できます。
ターミナルでのテキスト置換や正規表現の扱いに慣れておくと、CLIでのデータ処理速度がさらに上がります。VS Codeのマルチカーソルと正規表現置換による編集効率化や、curlの実践オプション活用については、以下の記事も参考にしてみてください。
関連記事(ツール・効率化)
「ツール・効率化」の記事をもっと見るGemini 4 Hydrogenの動画生成を4本試してみた感想とちょっとしたコツ
2026/11/18
MCPサーバーの肥大化を防ぎトークン消費と誤爆を抑える実務運用レシピ
2026/10/23