基本フィルター

恒等フィルター：.

最も単純なフィルターは . です。このフィルターは入力を受け取り、同じ値を出力します。つまり、恒等演算子です。

jqは既定ですべての出力を整形するため、. だけからなる簡単なプログラムを使って、たとえば curl のJSON出力を整形できます。

恒等フィルター自体は入力の値を変更しませんが、jqの処理によって、変更されたように見えることがあります。たとえば、jqの現在の実装では、次の式を評価すると、

1E1234567890 | .

少なくとも1つのプラットフォームで 1.7976931348623157e+308 が生成されます。これは、数値を解析する過程で、この特定の版のjqがIEEE754の倍精度表現へ変換し、精度が失われたためです。

jqによる数値の扱いはこれまでに変化しており、今後も関連するJSON標準が定める範囲内で変化する可能性が高いと考えられます。また、ビルド設定のオプションによって、jqの数値処理の方法が変わることがあります。

したがって、以下の説明は、jqの現在の版の動作を記述することを意図したものであり、動作を規定するものと解釈すべきではない、という前提で示します。

(1) まだIEEE754の倍精度表現へ変換されていない数値に対して算術演算を行うと、IEEE754表現への変換が発生します。

(2) jqは、数値リテラルの元の十進精度を維持しようとします（ビルド設定のオプション --disable-decnum が使われなかった場合）。ただし、1E1234567890 のような式では、指数が大きすぎると精度が失われます。

(3) 数値の切り詰められていない大きな十進数表現が利用できる場合、比較はその表現を使って行われます。以下の実行例の1つで、この動作を示します。

以下の実行例では、組込み関数 have_decnum を使って、ビルド設定のオプション --disable-decnum を使った場合と使わなかった場合に期待される違いを示します。また、このオプションの使用の有無にかかわらず、実行例から作成した自動テストが成功するようにしています。

jq '.'

"Hello, world!"

"Hello, world!"

jq '.'

0.12345678901234567890123456789

0.12345678901234567890123456789

jq '[., tojson] == if have_decnum then [12345678909876543212345,"12345678909876543212345"] else [12345678909876543000000,"12345678909876543000000"] end'

12345678909876543212345

true

jq '[1234567890987654321,-1234567890987654321 | tojson] == if have_decnum then ["1234567890987654321","-1234567890987654321"] else ["1234567890987654400","-1234567890987654400"] end'

null

true

jq '. < 0.12345678901234567890123456788'

0.12345678901234567890123456789

false

jq 'map([., . == 1]) | tojson == if have_decnum then "[[1,true],[1.000,true],[1.0,true],[1.00,true]]" else "[[1,true],[1,true],[1,true],[1,true]]" end'

[1, 1.000, 1.0, 100e-2]

true

jq '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000) | . == if have_decnum then [true, false] else [false, false] end'

10000000000000000000000000000001

true

オブジェクトの識別子による索引：.foo、.foo.bar

最も単純で役に立つフィルターは .foo という形式です。JSONオブジェクト（辞書やハッシュとも呼ばれます）を入力として与えると、.foo はキー"foo"が存在する場合にその値を、存在しない場合にnullを生成します。

.foo.bar という形式のフィルターは .foo | .bar と同じです。

.foo の構文は、単純で識別子のようなキーにだけ使えます。つまり、英数字とアンダースコアだけで構成され、数字で始まらないキーです。

キーに特殊文字が含まれる場合や数字で始まる場合は、."foo$" のように二重引用符で囲むか、.["foo$"] を使う必要があります。

たとえば、.["foo::bar"] と .["foo.bar"] は使えますが、.foo::bar は使えません。

jq '.foo'

{"foo": 42, "bar": "less interesting data"}

42

jq '.foo'

{"notfoo": true, "alsonotfoo": false}

null

jq '.["foo"]'

{"foo": 42}

42

オブジェクトの識別子による索引（エラーを抑制）：.foo?

.foo と同様ですが、. がオブジェクトでなくてもエラーを出力しません。

jq '.foo?'

{"foo": 42, "bar": "less interesting data"}

42

jq '.foo?'

{"notfoo": true, "alsonotfoo": false}

null

jq '.["foo"]?'

{"foo": 42}

42

jq '[.foo?]'

[1,2]

[]

オブジェクトの索引：.[<string>]

.["foo"] のような構文を使って、オブジェクトのフィールドを検索することもできます（前述の .foo はこの省略形ですが、識別子のような文字列にだけ使えます）。

配列の索引：.[<number>]

索引の値が整数の場合、.[<number>] で配列を参照できます。配列の索引は0から始まるため、.[2] は3番目の要素を返します。

負の索引も使えます。-1は最後の要素、-2は最後から2番目の要素を指し、以下も同様です。

jq '.[0]'

[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]

{"name":"JSON", "good":true}

jq '.[2]'

[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]

null

jq '.[-2]'

[1,2,3]

2

配列・文字列のスライス：.[<number>:<number>]

.[<number>:<number>] という構文を使うと、配列の部分配列や文字列の部分文字列を返せます。.[10:15] が返す配列の長さは5で、索引10（含む）から索引15（含まない）までの要素を含みます。どちらの索引も負の値にできます。その場合、配列の末尾から逆向きに数えます。また、どちらも省略でき、その場合は配列の先頭または末尾を指します。索引は0から始まります。

jq '.[2:4]'

["a","b","c","d","e"]

["c", "d"]

jq '.[2:4]'

"abcdefghi"

"cd"

jq '.[:3]'

["a","b","c","d","e"]

["a", "b", "c"]

jq '.[-2:]'

["a","b","c","d","e"]

["d", "e"]

配列・オブジェクトの値のイテレーター：.[]

.[index] の構文で索引を完全に省略すると、配列のすべての要素を返します。.[] を入力 [1,2,3] に対して実行すると、1つの配列ではなく、3つの別々の結果として数値を生成します。.foo[] という形式のフィルターは .foo | .[] と同じです。

オブジェクトに対して使うこともでき、その場合はオブジェクトのすべての値を返します。

このイテレーター演算子は、値のジェネレーターであることに注意してください。

jq '.[]'

[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]

{"name":"JSON", "good":true}

{"name":"XML", "good":false}

jq '.[]'

[]

jq '.foo[]'

{"foo":[1,2,3]}

1

2

3

jq '.[]'

{"a": 1, "b": 1}

1

1

.[]?

.[] と同様ですが、.が配列でもオブジェクトでもない場合も、エラーを出力しません。.foo[]? という形式のフィルターは .foo | .[]? と同じです。

カンマ：,

2つのフィルターをカンマで区切ると、両方に同じ入力が渡され、2つのフィルターが出力する値のストリームが順番に連結されます。最初に左側の式が生成するすべての出力が続き、その後に右側の式が生成するすべての出力が続きます。たとえば、フィルター .foo, .bar は"foo"フィールドと"bar"フィールドの両方を、別々の出力として生成します。

, 演算子は、ジェネレーターを構築する方法の1つです。

jq '.foo, .bar'

{"foo": 42, "bar": "something else", "baz": true}

42

"something else"

jq '.user, .projects[]'

{"user":"stedolan", "projects": ["jq", "wikiflow"]}

"stedolan"

"jq"

"wikiflow"

jq '.[4,2]'

["a","b","c","d","e"]

"e"

"c"

パイプ：|

|演算子は、左側のフィルターの出力を右側のフィルターの入力へ渡すことで、2つのフィルターを組み合わせます。Unixシェルのパイプに慣れていれば、それと似たものと考えられます。

左側が複数の結果を生成すると、右側はそれぞれの結果に対して実行されます。したがって、式 .[] | .foo は入力配列の各要素から"foo"フィールドを取り出します。これは直積であり、意外に感じることがあります。

.a.b.c は .a | .b | .c と同じであることに注意してください。

また、. は「パイプライン」の特定の段階、具体的には . という式が現れる位置での入力値です。したがって、.a | . | .b は .a.b と同じです。中央の . は、.a が生成した値を指すためです。

jq '.[] | .name'

[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]

"JSON"

"XML"

丸括弧

丸括弧は、一般的なプログラミング言語と同様に、式をまとめる演算子として働きます。

jq '(. + 2) * 5'

1

15