jq ハンドブック

REST API の応答、クラウドや Git ホスティングサービスの API が返す構成情報、ネットワーク機器の状態データと、運用の現場で目にするデータは JSON の形で届くことが多く、それをシェル上で抽出し、変換し、集計できるかどうかで作業の速さが変わります。『jq ハンドブック』 (豊沢聡 著、カットシステム、2021 年 7 月刊) は、JSON テキストを解析、抽出、変換するコマンドライン指向のツール jq を、シンプルなサンプルとその実行例から機能ごとに説明する B5 変型判の解説書で、副題は「NetOps/DevOps 必携の JSON パーザ」です。版元によれば jq のオフィシャルマニュアルのほとんどをカバーし、利用頻度の少なそうな機能だけを一部省いていて、学習に使えるサンプルファイルのダウンロードサービスが付きます。同じ著者が 2023 年に出した応用篇『jq クックブック』の版元紹介文では、ベーシックな用法は導入篇の本書を参照するよう案内されており、二冊は導入篇と応用篇の関係にあります。

全 10 章と付録 4 本、jq の実行からフィルタの記号、制御構造まで

構成は全 10 章と付録 4 本で、第 1 章「はじめよう」で jq の実行、フィルタ、コマンドオプションを押さえ、第 2 章「入出力」で入力、フィルタファイル、終了コード、出力文字の変換を扱います。第 3 章「フィルタの基本」は角カッコ、カンマ、パイプ、疑問符、中カッコ、ダブルドットと、節題が記号そのものになっているのが特徴で、jq の式を構成する記号を一つずつ意味づけていきます。第 4 章「基本演算とデータ型」で演算子と関数、データ型、加算と減算、型依存の関数、代入を学んだ後は、第 5 章「数値演算」 (乗除算、丸め処理、数値の分解、数列の生成、日時関数、数値定数、数値の精度)、第 6 章「文字列操作」 (基本操作と正規表現)、第 7 章「配列操作」 (要素の抽出、配列の変形、シーケンス処理)、第 8 章「オブジェクト操作」 (キーと値の同時処理、パス配列) と、データ型別の操作へ進みます。第 9 章は比較演算子、論理演算子、述語関数、第 10 章「制御構造」は条件分岐、エラー処理、変数、関数定義、ループで、各章末に「まとめ」の節が置かれています。付録はインストール、JSON、コマンド一覧、参考文献の 4 本です。

grep や sed では JSON を扱えない理由と jq の設計

Unix の行指向ツールは、改行で区切られた 1 行を 1 レコードとみなして処理します。ところが JSON は入れ子の階層構造を持ち、レコードの境界が改行と一致しません。版元の紹介文が指摘するとおり、数百個の構成情報が改行なしで 1 行にまとめられていることもあり、そうなると grep や sed では簡単に解析できず、Python や JavaScript の JSON ライブラリでスクリプトを書くことになりますが、ちょっとした操作のためにプログラムを書くのは面倒です。jq はこの隙間を埋める、JSON 専用の sed あるいは awk のようなコマンドで、部分データの抽出、不要な要素の削除、値の変更や演算、簡単な集計を、たいていは 1 行で済ませられます。仕組みとしては、入力の JSON 値がフィルタを通過するたびに別の値へ置き換わり、パイプで次のフィルタへ流れていく処理モデルで、角カッコで配列の要素を展開し、カンマで複数の出力を並べ、疑問符でエラーを抑制するといった記号の意味を知っているかどうかが、式を読み書きできるかの分水嶺になります。本書が第 3 章を記号単位の節に割り、第 6 章で 正規表現 を独立した節に立てているのは、この分水嶺を越えさせる構成です。

NetOps / DevOps が対象、前提知識と jq のバージョン

版元が対象に挙げるのは、REST を日常的に利用する NetOps や DevOps の担当者です。REST API ではリソースがたいてい JSON で記述され、システムの設定を JSON で送り、GET リクエストで JSON のシステム情報を取得するという運用が前提になっているため、コマンドラインとパイプの基本的な感覚があれば読み始められます。JSON そのものの知識は付録 B が補い、インストール手順は付録 A にあるので、jq を初めて入れる段階の人でも入口でつまずきにくい作りです。注意点は 2 つあります。1 つは版元登録に対応 jq バージョンの記載が無いことで、刊行の 2021 年時点で配布されていた jq は 2018 年公開の 1.6 系、2023 年 9 月に 1.7 が公開されて以降は追加された関数や挙動の差分があるため、手元の環境の版と読み合わせる必要があります。もう 1 つは本書が導入篇である点で、すでに jq を使い込んでいて統計や SQL 風の表操作を関数として組む実例を求める人には、応用篇『jq クックブック』のほうが目的に合います。特定言語のライブラリで JSON を処理したい人にも、本書の射程は向きません。

元が取れるのは、API の応答やクラウド CLI の出力を毎日のように読み、必要な値だけを抜き出す作業をシェルの 1 行で終わらせたい人です。オフィシャルマニュアルはそっけない記述が多く試行錯誤が要る、と版元自身が述べる部分を、サンプルと実行例の対で埋めてくれるのが本書の実利で、記号の意味を体系的に押さえておけば、その後に検索で見つけた jq のワンライナーも読み解けるようになります。jq を「たまに使うが式の組み立てに自信が無い」段階から、自分で書ける段階へ移るための導入篇として、手元に置く価値のある一冊です。