jq を使ってコマンドラインで JSON を加工する

今回はjq コマンドの簡単な使い方についてご説明します。
jq コマンドを使うと、 JSON データを sed や awk 等のコマンドと連携するのが容易になります。

jq の使用例

jq 公式サイトの Tutorial に、 GitHub の JSON API を操作する例が記載されています。

なお、筆者の方でもいくつか例を書いてみました。良かったら参考にしてみてください。

例1: コミット履歴から最新5件のメッセージを表示する。

curl -s https://api.github.com/repos/jqlang/jq/commits?per_page=5 \
    | jq -r '.[].commit.message | split("\n")[0]'

# 出力結果は以下の通り。
#
#     jq.test: drop non-portable %F test (#3365)
#     Update jq documentation for jq 1.8.1 release
#     Update signatures of 1.8.1 (#3364)
#     Update NEWS.md and AUTHORS for 1.8.1 (#3353)
#     build(deps): bump pyyaml from 6.0.1 to 6.0.2 in /docs (#3363)

ポイント

• パイプ : |
  • 左側の出力を右側の入力として扱います。（Unix のパイプと同様です。）
  • コミットメッセージを split() で処理するため、パイプで繋いでいます。
• 文字列を配列に分割する : split()
  • コミットコメントを改行で分割し、先頭行だけを取り出しています。

例2 コミット履歴を CSV に変換する。

curl -s https://api.github.com/repos/jqlang/jq/commits?per_page=5 \
    | jq -r '.[].commit | [.author.date, .tree.sha[0:8], (.message | split("\n")[0])] | @csv'

# 出力結果は以下の通り。
#
#     "2025-07-04T16:25:28Z","c84b2cc8","jq.test: drop non-portable %F test (#3365)"
#     "2025-07-01T11:54:28Z","255fef92","Update jq documentation for jq 1.8.1 release"
#     "2025-07-01T11:50:42Z","547d8784","Update signatures of 1.8.1 (#3364)"
#     "2025-07-01T10:36:14Z","d1a25f4b","Update NEWS.md and AUTHORS for 1.8.1 (#3353)"
#     "2025-07-01T10:29:37Z","a6da73f6","build(deps): bump pyyaml from 6.0.1 to 6.0.2 in /docs (#3363)"

ポイント

• 文字列や配列から一部を切り取る（substring, slice） : [<number>:<number>]
  • 例えば [0:8] は、先頭から8文字（または8つ目までの要素）を切り取ります。
  • ハッシュの先頭8文字を取得するのに使っています。
• 値を配列に変換する : [] で囲む
  • [] で囲むと、囲まれた値が配列になります。
  • 「コミット日時、ハッシュ、メッセージ」を配列に変換しています。
• 配列をCSVに変換する : @csv
  • 配列を CSV に形式に変換します。

おまけ: jq と似たライブラリ

JSON を変換するライブラリは jq だけではなく、いくつか存在します。

AWS CLI を使っている方は JMESPath のお世話になっている方も多いのではないでしょうか。これは AWS CLI の --query オプションで使えるもので、 AWS コマンドから取得した JSON を加工するのに便利なものです。（※なお JMESPath の文法は jq とは異なりますのでご注意ください。）

• 参考: AWS Command Line Interface バージョン 2 用ユーザーガイド > Filtering output in the AWS CLI

これ以外にも JSON Query, JSONiq といったライブラリも存在しています。

まとめ

JSON を加工するのに便利な jq コマンドについてご説明しました。

jq で JSON を加工すると、sed, awk を始めとする他のコマンドと連携するのが容易になります。

jq 以外にも類似したライブラリが存在しますが、それらの文法は違うものになっています。
AWS CLI を使う方は JMESPath の文法を覚えておくと便利です。