■サンプルファイルのダウンロードについて
本書掲載のサンプルファイルは、下記 URL からダウンロードできます。

https://-----------------------------------------（出版社 Web サイト）

https://github.com/----------------------------------- （著者の GitHub）

・本書の内容についてのご意見、ご質問は、お名前、ご連絡先を明記のうえ、小社出版部宛文書（郵送または E-mail）でお送りください。
・電話によるお問い合わせはお受けできません。
・本書の解説範囲を越える内容のご質問や、本書の内容と無関係なご質問にはお答えできません。
・匿名のフリーメールアドレスからのお問い合わせには返信しかねます。
本書で取り上げられているシステム名／製品名は、一般に開発各社の登録商標／商品名です。本書では、™ および ® マークは明記していません。本書に掲載されている団体／商品に対して、その商標権を侵害する意図は一切ありません。本書で紹介している URL や各サイトの内容は変更される場合があります。

はじめに

jq は JSON テキストを解析、抽出、変換するコマンドライン指向のツールです。
JSON（JavaScript Object Notation）は構造的なデータを表現する一般的な形式で、ウェブサービスで広く利用されています。とくにウェブ技術を基盤にした REST（REpresentational State
Transfer）では、リソースはたいてい JSON で記述されます。REST はリモートシステムの管理運用でよく用いられ、JSON テキストを送信することでシステムを設定したり、GET リクエストから JSON で書かれたシステム情報を取得します。たとえば、協調ソフトウェア開発でよく用いられる GitHub、AWS などのクラウド環境、あるいは F5 BIG-IP のようなネットワーク機器の REST イ
ンタフェースは JSON ベースです。次の例は、GitHub からリポジトリ情報を取得したときのものです。
$ curl -sku :$TOKEN https://api.github.com/user/repos | jq '.'[{"id": 1234567879,"node_id": "MDEabcdefghijkRvcnkzNDc3NzQyMzM=","name": "Sample","full_name": "Sample codes","private": false,"owner": {"login": "foobar","id": 1234567,
...

# 以下略

JSON テキストは可読文字で記述されるので、テキストエディタで読み書きできます。しかし、データの階層構造が深いと、経験を積んだ目でもかなり読みづらいです。数百個の構成情報が改行なしで 1 行にまとめられることもあり、そんなときは Unix でおなじみの行指向ツールである
grep や sed では簡単には解析できません。そこで、やや込み入った処理ではプログラミングのお世話になります。幸いなことに、Python や JavaScript といったポピュラーな言語には JSON 処理
ライブラリが用意されているので、スクリプティングはそれほど難しくありません。
しかし、ちょっとした操作のためにわざわざプログラムを書くのは面倒です。Unix ツールのよ
うに、必要なときに必要なものだけをいろいろ組みあわせてさくっと利用できたほうが便利です。

iii

jq はそんな用法を念頭に設計されています。つまり、JSON 専用の sed あるいは awk のようなコマンドです。jq は部分データの抽出、不要な要素の削除、値の変更や演算、簡単な集計などを（たいていは）1 行でできます。なれてくれば、より複雑な操作もできます。

jq が略語だとしたら、もとの単語がなにかは気になるところです。JSON Query という説もありますが、設計者の Stephen Dolan によれば、短くて打ちやすいから選んだだけで、もともと意味はないそうです（Stack Overflow より）。

jq のオフィシャルマニュアルは A4 換算で 50 ページほどなので、使いたい機能を見つけるのはそう大変ではありません。ただ、そっけない記述も多く、ときには試行錯誤も必要です。チュート
リアルもありますが、あまり拡充されていません。そこで、シンプルなサンプルとその実行例から各種の機能を説明したのが本書です。オフィシャルマニュアルのほとんどをカバーしていますが、
一部、利用頻度の少なそうな機能は省いています。
REST を日常的に利用する NetOps や DevOps 諸氏のお役に立てれば幸いです。
2021 年６月
豊沢 聡

iv

注意事項
以下、本書の表記や使用するサンプルファイルなどで注意すべき点を説明します。

表記
コマンドとその出力を示す実行例は、すべて Unix でのものです。$ で始まる行がコマンド、それに続くのが出力です。例によっては、# からコメントを加えたものもあります。

JSON の仕様にコメントはありません。あくまで、本書を読むための補助にすぎません。

$ jq -c '.' startMeUp01.json["烧餐包","烧卖皇","虾饺","韭菜饺"]# コマンド# 出力

コマンドが 1 行に収まらないときは、シェルに解釈される部分では行末にバックスラッシュ（\）を加えて改行しています。jq に解釈されるフィルタ（シングルクォートで囲まれた jq の第 1引数）の部分ではそのまま（記号なしで）改行しています。どちらの記法でも、（$ やコメントを除けば）そのままコピー & ペーストで実行できます。
$ cat filter01.json | \# シェルでの折り返し$ cat control01.json | jq -r '.aLaCarte[] |# フィルタでの折り返し

jq -c '.'

if endswith("焼き") then.

else

. + "は焼きものではない"

end'

v

日本語環境の Windows コマンドプロンプトでは、Windows Subsystem for Linux（WSL）も含めてバックスラッシュ（\）は ¥ で表示されます。

縦に長い出力は、全体を示す必要がなければ省略しています。
["烧餐包","烧卖皇",...

# 省略部分

横に長い出力は書籍の幅にもとづいて、そのまま折り返しています。つまり、書籍の幅のコンソールに出力されたのとおなじ見栄えです。
{"赤皿":{"品目":["こはだ","とびっこ軍艦","とろたく軍艦","納豆巻"],"価格":130},"青皿":{"品目":["びんちょう","〆さば","あじ","いわし"],"価格":210},"金皿":{"品目":["うなぎ","あわび","中トロ","いくら軍艦"],"価格":430}}

ただし、エラー出力は可読性を考慮して、手で改行を入れています。実際の出力と異なる点、ご了承ください。
# 本書での表示

jq: error: syntax error, unexpected INVALID_CHARACTER,

expecting FORMAT or QQSTRING_START (Unix shell quoting issues?)
at <top-level>, line 1:# もとの表示（自然な折り返し）

jq: error: syntax error, unexpected INVALID_CHARACTER, expecting FORMAT or QQSTRING_STAR
T (Unix shell quoting issues?) at <top-level>, line 1:

エラーメッセージは jq のバージョンで異なることもあります。

vi配列要素番号
配列要素の番号は、0 からカウントしています。たとえば、配列 [1, 2, 3] の要素 1 は 0 番目の要素です。

サンプルファイル
本書のほとんどの実行例は、サンプルの JSON テキストから示します。いずれもたかだか 20 行程度の短いものなので各章の冒頭に提示してありますが、出版社のダウンロードサービスあるいは
次に示す筆者の GitHub からダウンロードもできます。文字エンコーディングは UTF-8 です。
https://github.com/stoyosawa/jqDoc-Public

もっとも、ファイルの中身そのものに意味があるわけではないので、似たような構造なら好みのファイルでテストしても問題はありません。

jq のバージョン
本書で使用し、動作を確認した jq はバージョン 1.6（2018 年 11 月 1 日リリース）です。OS
にバンドルされているもの、あるいは apt-get や yum などのパッケージ管理ツールからインストールしたものは、これよりも古いバージョンのことがあります。エラーが頻繁に発生するようなら、付録 A.1 から実行形式をインストールしてください。
（jq のオフィシャルサイトのバイナリではない）バンドル版やパッケージ版にはまた、正規表記
ライブラリ抜きでコンパイルされたものも散見されます（たとえば F5 社の BIG-IP にバンドルされたもの）。そのタイプのバイナリでは、6.2 節で取り上げる正規表現関数は利用できません。オフ
ィシャル版のインストールをお勧めします。

Windows での利用
jq には Windows 用バイナリもありますが、Windows コマンドプロンプトからの直接利用は勧められません。特殊文字や非 ASCII 文字の扱いに癖があるため、込み入った jq フィルタの記述が難しいからです。Windows ユーザには Windows Subsystem for Linux（WSL）を有効化し、そのコンソールから Linux 版バイナリを使用することを勧めます。WSL の導入と簡単な利用方法は付録 A.2 に示しました。

vii

あえて Windows コマンドプロンプトから利用するにあたっては、引用符にはとくに注意してください。本書の用例では、jq フィルタの特殊記号をシェルに解釈させないようにシングルクォー

ト（'）でくくっていますが、コマンドプロンプトではシングルクォートは使いません。Windows
で本書の用例をそのまま用いるとエラーになります。
$ jq '.contact.phone' startMeUp02.json# Unix。フィルタを''でくくる

C:\temp>jq '.contact.phone' startMeUp02.json# Windows。''でくくるとエラー"09-123-4567"

jq: error: syntax error, unexpected INVALID_CHARACTER,

expecting $end (Windows cmd shell quoting issues?) at <top-level>, line 1:'.contact.phone'

jq: 1 compile error
C:\temp>jq .contact.phone startMeUp02.json"09-123-4567"# Windows。''がなければ動作

Windows コマンドプロンプトのデフォルト文字エンコーディングは Shift JIS（SJIS）です。
UTF-8 で記述されたファイルは、次の例に示すように文字化けします。
C:\temp>chcp# デフォルトはSJIS

C:\temp>type predicate01.json# UTF-8は文字化け

現在のコード ページ: 932{"null": null,"boolean": true,"number": 810,

"string": "縺輔・縺ｮ蜻ｳ蝎檎・螳夐｣・,"array" : ["縺秘｣ｯ", "蜻ｳ蝎梧ｱ・, "蜑ｲ繧雁ｹｲ縺怜､ｧ譬ｹ"],}"object": {"drink": "譯懆干蜷滄・驟・}しかし、ファイルを SJIS にすると、コマンドプロンプトで表示はできても UTF-8 マシンの jq では次に示すように処理できません。

viii

C:\temp>type predicate01-sjis.json{# SJIS版は表示できる"null": null,"boolean": true,"number": 810,

"string": "さばの味噌煮定食","array" : ["ご飯", "味噌汁", "割り干し大根"],}"object": {"drink": "桜花吟醸酒"}

C:\temp>jq '.' predicate01-sjis.json

jq: error: syntax error, unexpected INVALID_CHARACTER,# 処理失敗expecting $end (Windows cmd shell quoting issues?) at <top-level>, line 1:'.'

jq: 1 compile error

ix

目

次

目次

はじめに........................................................................................................................ iii

第1章
1.1

はじめよう ...........................................................1
jq の実行............................................................................................................ 2
1.1.1
1.1.2
1.1.3

1.2

フィルタ............................................................................................................. 5
1.2.1
1.2.2
1.2.3
1.2.4
1.2.5

1.3

第2章
2.1

アイデンティティ.........................................................................................................5
オブジェクトへのパス................................................................................................6
特殊なプロパティ名....................................................................................................7
配列要素へのパス.........................................................................................................8
イテレータ......................................................................................................................9

コマンドオプション........................................................................................11
1.3.1
1.3.2
1.3.3
1.3.4
1.3.5
1.3.6
1.3.7
1.3.8
1.3.9

1.4

コマンドの書式.............................................................................................................3フィルタの保護.............................................................................................................3
不正な JSON テキスト................................................................................................4

バージョン...................................................................................................................11
インデント幅の変更.................................................................................................11
ダブルクォートを外す.............................................................................................12コンパクト出力..........................................................................................................13
連結.................................................................................................................................14
Unicode の表示...........................................................................................................15
配色の変更...................................................................................................................16
プロパティ名のソート.............................................................................................17
複数のオプション......................................................................................................17

まとめ..............................................................................................................18

入出力 ...............................................................19
入力..................................................................................................................20
2.1.1 複数のファイル..........................................................................................................20
2.1.2 複数の JSON テキスト.............................................................................................21
2.1.3 複数の JSON をまとめる.........................................................................................222.1.4 slurp の挙動.................................................................................................................24
2.1.5 標準入力........................................................................................................................25

x

目 次

2.1.6
2.1.7
2.1.8
2.1.9

2.2
2.3

プログラムの出力を処理........................................................................................26
無入力.............................................................................................................................27
入力を文字列として扱う........................................................................................28
JSON テキストシーケンス.....................................................................................29

フィルタファイル............................................................................................30
終了コード.......................................................................................................31
2.3.1
2.3.2

終了コードの変更......................................................................................................32
その他の終了コード.................................................................................................32

2.4

出力文字の変換................................................................................................33

2.5

まとめ..............................................................................................................36

第3章
3.1

フィルタの基本 ..................................................39
角カッコ...........................................................................................................40
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5

3.2

負の配列要素番号......................................................................................................40
配列のスライス..........................................................................................................41
文字列のスライス......................................................................................................42
配列の生成...................................................................................................................42配列の配列...................................................................................................................45

カンマ..............................................................................................................46
3.2.1 複数の配列要素の抽出.............................................................................................46
3.2.2 複数のオブジェクトの抽出....................................................................................47
3.2.3 直値の指定...................................................................................................................48

3.3

パイプ..............................................................................................................49

3.4

疑問符..............................................................................................................50

3.5

中カッコ...........................................................................................................51

3.6

ダブルドット...................................................................................................53

3.7

まとめ..............................................................................................................55

第4章
4.1

基本演算とデータ型 ............................................57
演算子と関数...................................................................................................58
4.1.1
4.1.2
4.1.3

4.2

演算子の引数...............................................................................................................58
関数の引数...................................................................................................................59
処理順序........................................................................................................................61

データ型...........................................................................................................62
4.2.1

データ型の確認..........................................................................................................62xi

4.2.2
4.2.3
4.2.4
4.2.5

4.3

加算と減算.......................................................................................................67
4.3.1
4.3.2
4.3.3
4.3.4

4.4

第5章
5.1

数値演算 ............................................................87
乗除算..............................................................................................................88

絶対値.............................................................................................................................92整数部分と小数点部分への分解...........................................................................93
符号の転写...................................................................................................................94

その他の数学関数............................................................................................94
5.4.1
5.4.2
5.4.3
5.4.4

xii

切り上げ........................................................................................................................91
切り捨て........................................................................................................................91
最接近丸め...................................................................................................................92
0 への丸め....................................................................................................................92

数値の分解.......................................................................................................92
5.3.1
5.3.2
5.3.3

5.4

浮動小数点版モジュロ.............................................................................................89

丸め処理...........................................................................................................90
5.2.1
5.2.2
5.2.3
5.2.4

5.3

演算結果の代入..........................................................................................................80
存在しない要素への代入........................................................................................80
更新代入........................................................................................................................81
算術更新代入...............................................................................................................84

まとめ..............................................................................................................84

5.1.1

5.2

length.............................................................................................................................71
add...................................................................................................................................73
sort..................................................................................................................................74
sort_by...........................................................................................................................77
max と min...................................................................................................................78

代入..................................................................................................................79
4.5.1
4.5.2
4.5.3
4.5.4

4.6

加算.................................................................................................................................67
加算の制約...................................................................................................................69
null の加算...................................................................................................................69
減算.................................................................................................................................70

型依存の関数...................................................................................................71
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5

4.5

特定のデータ型だけ抽出........................................................................................62
文字列から数値への変換........................................................................................64
文字列への変換..........................................................................................................65
文字列表記のオブジェクトと配列......................................................................65

最大値と最小値..........................................................................................................94
指数関数........................................................................................................................95
対数関数........................................................................................................................96三角関数........................................................................................................................96

目 次

5.5
5.6

数列の生成.......................................................................................................98
日時関数........................................................................................................ 100
5.6.1 現在の日時................................................................................................................ 101
5.6.2 Unix エポックと文字列表記の相互変換........................................................ 101
5.6.3 日時の分解................................................................................................................ 102
5.6.4 カスタム日時文字列.............................................................................................. 1035.7

数値定数........................................................................................................ 104
5.7.1

無限大.......................................................................................................................... 105

5.8

数値の精度.................................................................................................... 106

5.9

まとめ........................................................................................................... 107

第6章
6.1

文字列操作 .......................................................109
基本操作........................................................................................................ 110
6.1.1
6.1.2
6.1.3
6.1.4
6.1.5
6.1.6
6.1.7

6.2

乗算.............................................................................................................................. 110
部分文字列................................................................................................................ 110
バイト長..................................................................................................................... 111
Unicode コード........................................................................................................ 112
大文字小文字化....................................................................................................... 113
文字列の分割と連結.............................................................................................. 114
文字位置の検索....................................................................................................... 116

正規表現........................................................................................................ 119
6.2.1 使用上の注意............................................................................................................ 119
6.2.2 パターンマッチ文字列.......................................................................................... 120
6.2.3 正規表現関数の引数.............................................................................................. 120
6.2.4 test................................................................................................................................ 122
6.2.5 match.......................................................................................................................... 123
6.2.6 match とキャプチャ.............................................................................................. 124
6.2.7 match と名前つきキャプチャ............................................................................ 126
6.2.8 capture....................................................................................................................... 128
6.2.9 scan.............................................................................................................................. 128
6.2.10 splits......................................................................................................................... 130
6.2.11 sub と gsub............................................................................................................ 131

6.3

まとめ........................................................................................................... 132

xiii

第7章
7.1

配列操作 ..........................................................133
要素の抽出.................................................................................................... 134
7.1.1
7.1.2
7.1.3
7.1.4

7.2

配列の変形.................................................................................................... 138
7.2.1
7.2.2
7.2.3
7.2.4
7.2.5
7.2.6

7.3

第8章
8.1

オブジェクト操作 .............................................151
オブジェクト操作......................................................................................... 152

xiv

to_entries................................................................................................................... 157
to_entries と配列.................................................................................................... 159
from_entries............................................................................................................. 160
with_entries.............................................................................................................. 161

パス配列........................................................................................................ 162
8.3.1
8.3.2
8.3.3
8.2.4

8.4

キー抽出..................................................................................................................... 152
削除.............................................................................................................................. 153
重複の除外................................................................................................................ 154
シーケンス処理....................................................................................................... 155

キーと値の同時処理..................................................................................... 156
8.2.1
8.2.2
8.2.3
8.2.4

8.3

map.............................................................................................................................. 146
reduce......................................................................................................................... 147

まとめ........................................................................................................... 149

8.1.1
8.1.2
8.1.3
8.1.4

8.2

平板化.......................................................................................................................... 138
重複の除外................................................................................................................ 138
逆順.............................................................................................................................. 139
削除.............................................................................................................................. 139
組みあわせ................................................................................................................ 139
転置.............................................................................................................................. 141

シーケンス処理............................................................................................. 146
7.3.1
7.3.2

7.4

位置から抽出............................................................................................................ 134
個数から抽出............................................................................................................ 135
値から番号を抽出................................................................................................... 136
バイナリサーチ....................................................................................................... 136

生成.............................................................................................................................. 163
値の取得..................................................................................................................... 165
値のセット................................................................................................................ 166
削除.............................................................................................................................. 167

まとめ........................................................................................................... 168

目 次

第9章
9.1

比較演算子、論理演算子、述語関数 ....................169
比較演算子.................................................................................................... 170
9.1.1
9.1.2

9.2

論理演算子.................................................................................................... 172
9.2.1
9.2.2
9.2.3

9.3

論理和と論理積....................................................................................................... 172
否定演算子................................................................................................................ 174
排他的論理和............................................................................................................ 175

述語関数........................................................................................................ 175
9.3.1
9.3.2
9.3.3
9.3.4

9.4

等値.............................................................................................................................. 170
大小関係..................................................................................................................... 171

文字列用..................................................................................................................... 176
数値用.......................................................................................................................... 177
配列用.......................................................................................................................... 178
汎用.............................................................................................................................. 180

まとめ........................................................................................................... 183

第 10 章制御構造 ........................................................18510.1 条件分岐........................................................................................................ 186
10.1.110.1.210.1.3

if 文............................................................................................................................ 186
select......................................................................................................................... 188
代替演算子.............................................................................................................. 189

10.2 エラー処理.................................................................................................... 191
10.2.110.2.210.2.310.2.4try-catch.................................................................................................................. 191
エラー抑制演算子................................................................................................ 192
強制終了.................................................................................................................. 192
強制エラー.............................................................................................................. 194

10.3 変数............................................................................................................... 194
10.3.1 変数定義.................................................................................................................. 195
10.3.2 コマンドラインからの変数設定..................................................................... 196
10.3.3 ファイルを変数に代入....................................................................................... 197
10.3.4 変数を用いた in と inside................................................................................. 200
10.3.5 環境変数.................................................................................................................. 200

10.4 関数定義........................................................................................................ 202
10.5 ループ........................................................................................................... 204
10.5.1
10.5.210.5.3

while......................................................................................................................... 204
until........................................................................................................................... 206
foreach..................................................................................................................... 207

10.6 まとめ........................................................................................................... 209

xv

付録 .............................................................................211
付録 A

インストール............................................................................................. 211
A.1
A.2

付録 B

実行形式のインストール.................................................................................. 212
Windows Subsystem for Linux の導入....................................................... 214

JSON........................................................................................................ 217
B.1 JSON とは............................................................................................................... 217
B.2 JSON テキスト...................................................................................................... 218
B.3 JSON ファイル...................................................................................................... 228

付録 C

コマンド一覧............................................................................................. 229
C.1
C.2
C.3
C.4
C.5
C.6

付録 D

コマンドオプション........................................................................................... 229
特殊記号.................................................................................................................. 230
演算子....................................................................................................................... 231
一般関数.................................................................................................................. 232
数学関数.................................................................................................................. 236
定数、特殊変数..................................................................................................... 237

参考文献.................................................................................................... 238

索  引........................................................................................................................ 240

xvi

第1章
はじめよう

第1章

はじめよう

まずは使ってみましょう。
jq が未導入なら、付録 A からインストールしてください。また、JSON テキストの構造や記述方

法に不明な点があれば、付録 B に示した JSON の仕様概略を参照してください。
本章のテスト用 JSON ファイルは、次に示す startMeUp01.json と startMeUp02.json です。
$ cat startMeUp01.json["烧餐包", "烧卖皇", "虾饺", "韭菜饺"]4 つの文字列要素を収容した配列ひとつからなるシンプルなものです。
$ cat startMeUp02.json{"name":"別不同","isOpen":false,"評価":4.5,"hours":["11:00","15:00"],"contact":{"phone":"09-123-4567","メール": "booking@starcafe.com"}

5 つのプロパティからなるオブジェクトです。プロパティの値は順に文字列、真偽値、数値、配列、オブジェクトです。すべての要素が改行やインデントなしで 1 行に収められているので、かなり読みにくいです（紙面ではコンソール出力時のように自然に折り返されています）。このようにレスポンスボディを整形せずに返す REST サーバも多くあり、このサンプルはそのような状態をシミュレートしています。

1

1

はじめよう

1.1 jq の実行
jq は JSON テキストを整形して表示します。テストファイルからためします。
$ jq . startMeUp01.json["烧餐包","烧卖皇",
"虾饺",

]

"韭菜饺"

$ jq . startMeUp02.json{"name": "別不同","isOpen": false,"評価": 4.5,

"hours": ["11:00","15:00"],"contact": {"phone": "09-123-4567",}}"メール": "booking@starcafe.com"

出力は、JSON テキストの構造が把握しやすくなるよう整形されます。配列は要素単位で、オ
ブジェクトはプロパティ単位で改行されます。加えて、値が配列など入れ子で構造化されている
startMeUp02.json の hours や contact プロパティでは、それらがさらにインデントされます。

2

1.1 jq の実行

1.1.1

コマンドの書式

1

jq コマンドの書式は次のとおりです。

2$ jq [options] filter file.json

3● options: 任意指定（optional）なコマンドオプション。jq のデフォルトの挙動を変更するとき4に用いるもので、前記の実行例では用いていません。1.3 節で説明します。
● filter: フィルタ。入力された JSON テキストをどのように処理するかの指示。前記の実行例

5

す。コマンドオプションを介して、ファイルに記述したフィルタを読み込むこともできます6

ではドット（.）ひとつです。本書はこのフィルタの書き方を 1 冊かけて説明していきま（2.2 節）。
● file.json: 入力 JSON テキストファイル。JSON の仕様にのっとったテキストファイルでなけれ7

ばなりません。仕様は付録 B を参照してください。ファイルからだけでなく、標準入力ある
いはフィルタ内に記述した直値からでも入力できます。入力方法は 2.1 節で説明します。

8

1.1.2

9

フィルタの保護上記のフィルタは . だけで構成されていますが、複雑なものになるとスペースや特殊記号も含ま10れます。フィルタの特殊記号がシェルに先行して解釈（展開）されないようにするため、フィルタ
はシングルクォート（'）でくくります。

特殊記号が含まれたフィルタをシングルクォートなしで記述すると、エラーが発生したり、思わぬ挙動を示すことがあります。次の例で、フィルタ ., .（ドット、カンマ、スペース、ドット）を用いたときの動作を示します（カンマの用法は 3.2 節）。jq の文法上適正なフィルタなのでシン
グルクォートでくくれば正常に動作しますが、くくられないとエラーが発生します。
$ jq '., .' startMeUp01.json[# シングルクォートされている"烧餐包","烧卖皇",...

$ jq ., . startMeUp01.json# 以下略# ないとエラー付 録

jq: error: syntax error, unexpected $end (Unix shell quoting issues?)
at <top-level>, line 1:

3

1

はじめよう

.,

jq: 1 compile error

シェルはコマンド行をスペースで分解するので、指定のフィルタは .,（ドットカンマ）、.（ドット）、startmeUp01.json の 3 つの文字列として jq に引き渡されます。jq は最初の ., をフィルタと解釈しますが、これは文法上不正です（中途半端に終わっている）。そのため、「1 行目の ., に文法上のエラーがあります」（意訳）というエラーを発して異常終了します。また、「Unix
シェルのクォートはちゃんとしてる ?」とのヒントも示されています。

単一の . のように特殊記号を含まない 1 単語のフィルタならシングルクォートは必要ありませんが、いつもくくるように習慣づけるとよいでしょう。

Windows ではフィルタをシングルクォートでくくると逆にエラーになります。

1.1.3

不正な JSON テキスト

JSON の仕様に反したテキストはエラーになります。たとえば、startMeUp01.json ファイル末尾の閉じ角括弧（]）を削除するとエラーが報告されます。
$ cat startMeUp01.json# 末尾の]がない$ jq '.' startMeUp01.json# エラー["烧餐包", "烧卖皇", "虾饺", "韭菜饺"parse error: Unfinished JSON term at EOF at line 2, column 04

1.2 フィルタ

1.2 フィルタ

1

入力 JSON テキストの処理方法を記述したフィルタはどこまでも複雑になりえますが、本節で2は、入力から所定の要素を取りだすベーシックな記法を紹介します。

1.2.1

3

アイデンティティ

4

もっともシンプルなフィルタは、. だけで構成されたものです。ドットは「その JSON テキス

5ト」のトップレベルを指す記号で、マニュアルはこれをアイデンティティ（identity）と呼んでいます。

配列がひとつだけ収容された startMeUp01.json なら、前後をくくる [] も含めてドット直下の6レベルにある 4 つの要素すべてを指します。

7

図 1.1 ● startMeUp01.json の構造

89[ " 烧餐包 "" 烧卖皇 "" 虾饺 "" 韭菜饺 " ]10startMeUp02.json なら、ドットを起点とした階層構造で示される JSON テキスト全体です。これには全体をくくる {} も含まれます。また、hours や contact のように値がさらに構造化されているときはその中身も再帰的に表示されます。
図 1.2 ● startMeUp02.json の構造

{

name

isOpen

評価" 別不同 "

false

4.5

hours

contact["11:00" '15:00"]

phone

メール

付 録

"09-123-4567" "booking@starcafe.com" }

5

1

はじめよう

1.2.2

オブジェクトへのパス

JSON テキストにある . 配下の要素は、. を起点としたパス構造で参照できます。たとえば、startMeUp02.json のトップレベルにある name プロパティには .name から、isOpen プロパティには .isOpen からアクセスできます。このように、ドットを起点にした要素の参照をパス（path）といいます。ファイルシステム内のカレントディレクトリ（.）からその配下のディレクトリのファイルを指定するのとおなじ要領です。
$ jq '.name' startMeUp02.json# nameの値だけを抽出$ jq '.isOpen' startMeUp02.json# isOpenの値だけを抽出

"別不同"
false

出力はそのプロパティの値です。プロパティ名（キー）は出力されません（キーとともに出力する方法は 8.2 節）。name プロパティの値は文字列なので、出力もダブルクォートでくくられています。isOpen プロパティの値は真偽値なのでくくられません。
プ ロ パ テ ィ hours お よ び contact の 値 は、 そ れ ぞ れ 配 列 と オ ブ ジ ェ ク ト で す。 そ の た め、.contact をパスに指定すると、. 同様、その位置から下の要素をすべて示します。
$ jq '.contact' startMeUp02.json{}"phone": "09-123-4567",# contactの値を抽出# 結果はオブジェクト"メール": "booking@starcafe.com"

contact プロパティの値であるオブジェクトの内部の phone プロパティを参照するときは、.contact.phone のようにプロパティ名をドットでチェーンします。ファイルシステムのアナロジー

でいえば、カレントディレクトリ配下の contact ディレクトリにあるファイル name を参照しているイメージです。
$ jq '.contact.phone' startMeUp02.json"09-123-4567"

6# contactのphoneの値

1.2 フィルタ

1.2.3

特殊なプロパティ名

1startMeUp02.json には、日本語（Unicode 文字）で記述したプロパティ名があります。トップ2

レベルの " 評価 " と contact プロパティの " メール " です。英数文字以外は特殊文字なため、プロ
パティ名をダブルクォート（"）でくくらなければなりません。つまり、." 評価 "、.contact." メ

3ール " です。クォートなしで参照するとエラーになります。

4
JSON のプロパティ名に使ってはならない文字はありません。ただし、疑問符（?）、5

バックスラッシュ（\）、制御文字（ASCII コードで 0x00 から 0x1f）はバックスラ

ッシュでエスケープしなければなりません。

$ jq '.評価' startMeUp02.json

67# くくられていないのでエラー

jq: error: syntax error, unexpected INVALID_CHARACTER (Unix shell quoting issues?)

8

at <top-level>, line 1:.評価

jq: error: try .["field"] instead of .field for unusually named fields

9

.評価

10

at <top-level>, line 1:

jq: 2 compile errors$ jq '."評価"' startMeUp02.json# ."評価"はOK$ jq '.contact.メール' startMeUp02.json# 裸のメールなのでエラー

4.5

jq: error: syntax error, unexpected INVALID_CHARACTER,

expecting FORMAT or QQSTRING_START (Unix shell quoting issues?)
at <top-level>, line 1:.contact.メール

jq: 1 compile error$ jq '.contact."メール"' startMeUp02.json"booking@starcafe.com"# "メール"をくくればOK
付 録

7

1

はじめよう

エラーの 2 行目は「普通ではないプロパティ名なら .["field"] を使え」と、"" でくくったプロパティ名をさらに [] でくくるように勧めています。たとえば、.[" 評価 "] です。これも適正な用法ですが、本書では使いません。

ダブルクォートでくくるときは、プロパティ名だけくくるよう注意します。アイデンティティ. とプロパティ名の組みあわせだからです。". 評価 " や ."contact. メール " のように全体を一気にくくると、思わぬ結果が得られます。

たとえば、ドットはクォートの外にでているものの、."contact. メール " はプロパティが存在しないという意味で null を出力します。contact の配下の " メール " ではなく、トップレベルのcontact. メールという 1 単語のプロパティ名を参照しているからです。
$ jq '."contact.メール"' startMeUp02.json
null

1.2.4

# そのようなプロパティはない

配列要素へのパス

配 列 要 素 を 要 素 番 号 か ら 参 照 す る と き の パ ス は、[n] で す。n は 0 か ら カ ウ ン ト し ま す。

startMeUp01.json には 4 つの要素が収容されているので、n の値は 0 から 3 の範囲です。参照するには、トップレベルからスタートしてその配下の配列を参照するという意味で . を先頭に加えなければなりません。たとえば、（0 からカウントして）1 番目の要素である " 烧卖皇 " は .[1] から参照します。

$ jq '.[1]' startMeUp01.json"烧卖皇"# 1番目の要素

配列範囲外の要素を指定すると、一般的なプログラミング言語ではエラー（Out of Range など）が発生しますが、jq は存在しないプロパティ名同様、null を出力します。
$ jq '.[100]' startMeUp01.json
null

8

# 範囲外

1.2 フィルタ

startMeUp02.json の hours プロパティの値は配列です。その要素へのアクセスも、上記とお1

なじ要領で [n] を用います。ただし、トップレベルからみて hours プロパティの配列要素なので.hours を先頭に加えます。

2$ cat startMeUp01.json | jq '.hours[0]'# hours配列の0番目の要素$ cat startMeUp01.json | jq '.hours[1]'# hours配列の1番目の要素"11:00""15:00"

1.2.5

3
4
5
6

イテレータ

角カッコ [] はなかに数値（配列）あるいは文字列（オブジェクト）が記述されないときはイテ

7

理するメカニズムで、端的には要素数分のループです。イテレータを作用させると、その要素が順

8

素を順に取りだしています。

9

レータと解釈されます。イテレータ（iterator）は配列やオブジェクトの要素を順に取りだして処に出力されます。次の例では、トップレベルの . にイテレータ [] を作用させることで、4 つの要$ jq '.[]' startMeUp01.json"烧餐包"# 4つの要素ぜんぶ

10

"烧卖皇"
"虾饺"

"韭菜饺"

出力結果は単体の . と似ていますが、やや異なります。

. は「トップレベルからみたその JSON テキスト全体」なので、出力は配列です。そのことは、出力の前後に置かれた [] から示されています。つまり、フィルタ . はひとつの JSON テキスト（中身は 4 要素の配列）を受け取り、そのままひとつの JSON テキストとして（整形しつつ）出力します。

これに対し、.[] は「トップレベルからみたその JSON テキスト（の配列）を要素単位で抽出

し、ループしながらすべて書きだす」という意味なので、4 つの要素をくくる [] はありません。

このとき、4 つの要素はそれぞれ独立した JSON テキストです（{} や [] でくくられていない生の付 録

文字列ひとつ、数値ひとつだけでも立派な JSON テキストです）。言い換えれば、もとの（配列という）構造はなくなります。

9

1

はじめよう

イテレータ [] はオブジェクトにも利用できます。その場合、要素番号ではなくプロパティ名（キー）でループし、その値を順に取りだします。次の例では、startMeUp02.json の contact プロ
パティの値であるオブジェクトの値を順次抽出しています。
$ jq '.contact[]' startMeUp02.json"09-123-4567"# contactの値を抽出"booking@starcafe.com"

startMeUp02.json 全体に適用すれば、トップレベルのプロパティの値をすべて取得できます。
$ jq '.[]' startMeUp02.json"別不同"# nameの値

4.5# "評価"の値

false
[
]
{
}

"11:00",# isOpenの値# hoursの値"15:00""phone": "09-123-4567",# contactの値"メール": "booking@starcafe.com"

hours や contact のように値がさらに配列やオブジェクトのときは、構造を保ったまま表示されるところに注意してください。

構造をすべて解消して値だけ取り出すには、再帰のダブルドット（..）と基本型だけを選択的に抽出する関数 scalars をパイプ（|）で組みあわせます。これらは 3.6 節、4.2 節、3.3 節でそれぞれ説明します。

$ jq '.. | scalars' startMeUp02.json"別不同"# nameの値

4.5# "評価"の値

false"11:00""15:00""09-123-4567""booking@starcafe.com"

10# isOpenの値# hoursの0番目の値# hoursの1番目の値# contactのphoneの値# contactの"メール"の値