3 JSONPath機能

概要

このセクションでは、item 値のプリプロセスステップでサポートされる JSONPath 機能の詳細について説明します。

JSONPathは、ドットで区切られたセグメントで構成されます。
セグメントは、JSON 値の名前 * のような単純な単語と、あるいは角括弧 [ ] で囲まれたより複雑な構造体です。
セグメントを区切るドットはオプションで、省略することもできます。例えば

Path	説明
`$.object.name`	Return the object.name contents.
`$.object['name']`	Return the object.name contents.
`$.object.['name']`	Return the object.name contents.
`$["object"]['name']`	Return the object.name contents.
`$.['object'].["name"]`	Return the object.name contents.
`$.object.history.length()`	Return the number of object.history array elements.
`$[?(@.name == 'Object')].price.first()`	Return the price field of the first object with name 'Object'.
`$[?(@.name == 'Object')].history.first().length()`	Return the number of history array elements of the first object with name 'Object'.
`$[?(@.price > 10)].length()`	Return the number of objects with price being greater than 10.

Escaping special characters from LLD macro values in JSONPath も参照してください。

対応セグメント

セグメント	説明
`<name>`	オブジェクトプロパティを名前で照合します
`*`	すべてのオブジェクトプロパティに一致します
`['<name>']`	オブジェクトプロパティを名前で照合します
`['<name>', '<name>', ...]`	リストされた名前のいずれかでオブジェクトプロパティを照合します
`[<index>]`	配列要素をインデックスで照合します
`[<number>, <number>, ...]`	リストされたインデックスのいずれかで配列要素を照合します
`[*]`	すべてのオブジェクトプロパティまたは配列要素に一致します
`[<start>:<end>]`	定義された範囲で配列要素を一致させます: <start> - 一致する最初のインデックス (含む)。指定しない場合は、最初からすべての配列要素に一致します。負の場合は、配列の末尾からの開始オフセットを指定します。 <end> - 一致する最後のインデックス (除外)。指定されていない場合は、すべての配列要素を最後まで一致させます。負の場合、配列の末尾からの開始オフセットを指定します。
`[?(<expression>)]`	フィルター式を適用してオブジェクト/配列要素を一致させます

前例を無視して一致するセグメント (切り離されたセグメント) を見つけるには、接頭辞 '..' を付ける必要があります。たとえば、$..name または $..['name'] はすべての 'name' プロパティの値を返します。

一致した要素名は、JSONPath に~サフィックスを追加することで抽出できます。一致したオブジェクトの名前または一致した配列項目の文字列形式のインデックスを返します。出力形式は、他の JSONPath クエリと同じ規則に従います。明確なパスの結果は'そのまま'返され、不明確なパスの結果は配列で返されます。ただし、明確なパスに一致する要素の名前を抽出する意味はあまりありません - それはすでに知られていいるからです。

フィルター式

フィルター式は、中置表記の算術式です。

サポートされているオペランド:

オペランド	説明	例
`"<text>"` `'<text>'`	テキスト定数	'value: \'1\'' "value: '1'"
`<number>`	科学表記法をサポートする数値定数	123
`<jsonpath starting with $>`	入力ドキュメントのルートノードから JSONPath によって参照される値。明確なパスのみがサポートされています。	$.object.name
`<jsonpath starting with @>`	現在のオブジェクト/要素から JSONPath によって参照される値。明確なパスのみがサポートされています。	@.name

サポートされている演算子:

演算子	タイプ	説明	結果
`-`	binary	減算	Number.
`+`	binary	加算	Number.
`/`	binary	除算	Number.
`*`	binary	乗算	Number.
`==`	binary	等しい	Boolean (1 or 0).
`!=`	binary	等しくない	Boolean (1 or 0).
`<`	binary	未満	Boolean (1 or 0).
`<=`	binary	以下	Boolean (1 or 0).
`>`	binary	超過	Boolean (1 or 0).
`>=`	binary	以下	Boolean (1 or 0).
`=~`	binary	正規表現に一致	Boolean (1 or 0).
`!`	binary	ブール値のnot	Boolean (1 or 0).
`\|\|`	binary	ブール値のor	Boolean (1 or 0).
`&&`	binary	ブール値のand	Boolean (1 or 0).

関数

関数は JSONPath の最後で使用できます。前の関数が次の関数によって受け入れられる値を返す場合、複数の関数をチェーンできます。

サポートされている関数:

関数	説明	入力	出力
`avg`	入力配列の数値の平均値	数値の配列	数値
`min`	入力配列の数値の最小値	数値の配列	数値
`max`	入力配列の数値の最大値	数値の配列	数値
`sum`	入力配列の数値の合計	数値の配列	数値
`length`	入力配列の要素数	配列	数値
`first`	最初の配列要素	配列	入力配列の内容に応じた JSON コンストラクト (オブジェクト、配列、値)

引用符で囲まれた数値は、JSONPath 集計関数によって受け入れられます。これは、集計が必要な場合、値が文字列型から数値に変換されることを意味します。

入力に互換性がない場合、関数はエラーを生成します。

出力値

JSONPathsは、定型パスと不定型パスに分けることができます。
定型パスは、NULLまたは単一のマッチのみを返すことができます。
不定型パスは、複数の名前/インデックスリスト、配列スライス、式セグメントを含む JSONPath を返します。
しかし関数が使用されると、JSONPath は定型的なものになります。関数は常に単一の値を出力するからです。

定型パスは、参照するオブジェクト/配列/値を返します。
不定形のパスは、マッチしたオブジェクト/配列/値の配列を返します。

内部の最適化方法により、JSONPath クエリ結果のプロパティ順序は、元の JSON プロパティ順序と一致しない場合があります。たとえば、JSONPath $.books[1]["author", "title"] は ["title", "author"] を返す場合があります。元のプロパティ順序を維持することが不可欠な場合は、クエリ後の代替処理方法を検討する必要があります。

空白文字

空白文字（スペース、タブ文字）は、ブラケット記法のセグメントで自由に使用することができます。
例: $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( ).

文字列

文字列は、シングルクォート( ' )またはダブルクォート( " )で囲みます。
文字列の内部では、シングルクォートまたはダブルクォート(どちらで囲むかによって異なる) と
バックスラッシュ \ は、バックスラッシュ \文字でエスケープされます。

例

入力データ

{
         "books": [
           {
             "category": "reference",
             "author": "Nigel Rees",
             "title": "Sayings of the Century",
             "price": 8.95,
             "id": 1
           },
           {
             "category": "fiction",
             "author": "Evelyn Waugh",
             "title": "Sword of Honour",
             "price": 12.99,
             "id": 2
           },
           {
             "category": "fiction",
             "author": "Herman Melville",
             "title": "Moby Dick",
             "isbn": "0-553-21311-3",
             "price": 8.99,
             "id": 3
           },
           {
             "category": "fiction",
             "author": "J. R. R. Tolkien",
             "title": "The Lord of the Rings",
             "isbn": "0-395-19395-8",
             "price": 22.99,
             "id": 4
           }
         ],
         "services": {
           "delivery": {
             "servicegroup": 1000,
             "description": "Next day delivery in local town",
             "active": true,
             "price": 5
           },
           "bookbinding": {
             "servicegroup": 1001,
             "description": "Printing and assembling book in A5 format",
             "active": true,
             "price": 154.99
           },
           "restoration": {
             "servicegroup": 1002,
             "description": "Various restoration methods",
             "active": false,
             "methods": [
               {
                 "description": "Chemical cleaning",
                 "price": 46
               },
               {
                 "description": "Pressing pages damaged by moisture",
                 "price": 24.5
               },
               {
                 "description": "Rebinding torn book",
                 "price": 99.49
               }
             ]
           }
         },
         "filters": {
           "price": 10,
           "category": "fiction",
           "no filters": "no \"filters\""
         },
         "closed message": "Store is closed",
         "tags": [
           "a",
           "b",
           "c",
           "d",
           "e"
         ]
       }

JSONPath	Type	Result	Comments
`$.filters.price`	definite	10
`$.filters.category`	definite	fiction
`$.filters['no filters']`	definite	no "filters"
`$.filters`	definite	{ "price": 10, "category": "fiction", "no filters": "no \"filters\"" }
`$.books[1].title`	definite	Sword of Honour
`$.books[-1].author`	definite	J. R. R. Tolkien
`$.books.length()`	definite	4
`$.tags[:]`	indefinite	["a", "b", "c", "d", "e" ]
`$.tags[2:]`	indefinite	["c", "d", "e" ]
`$.tags[:3]`	indefinite	["a", "b", "c"]
`$.tags[1:4]`	indefinite	["b", "c", "d"]
`$.tags[-2:]`	indefinite	["d", "e"]
`$.tags[:-3]`	indefinite	["a", "b"]
`$.tags[:-3].length()`	definite	2
`$.books[0, 2].title`	indefinite	["Moby Dick", "Sayings of the Century"]
`$.books[1]['author', "title"]`	indefinite	["Sword of Honour", "Evelyn Waugh"]
`$..id`	indefinite	[1, 2, 3, 4]
`$.services..price`	indefinite	[154.99, 5, 46, 24.5, 99.49]
`$.books[?(@.id == 4 - 0.4 * 5)].title`	indefinite	["Sword of Honour"]	このクエリは、算術演算をクエリで使用できることを示しています。もちろん、このクエリは `$.books[?(@.id == 2)].title` に簡略化できます。
`$.books[?(@.id == 2 \\|\\| @.id == 4)].title`	indefinite	["Sword of Honour", "The Lord of the Rings"]
`$.books[?(!(@.id == 2))].title`	indefinite	["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
`$.books[?(@.id != 2)].title`	indefinite	["Sayings of the Century", "Moby Dick", "The Lord of the Rings"]
`$.books[?(@.title =~ " of ")].title`	indefinite	["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"]
`$.books[?(@.price > 12.99)].title`	indefinite	["The Lord of the Rings"]
`$.books[?(@.author > "Herman Melville")].title`	indefinite	["Sayings of the Century", "The Lord of the Rings"]
`$.books[?(@.price > $.filters.price)].title`	indefinite	["Sword of Honour", "The Lord of the Rings"]
`$.books[?(@.category == $.filters.category)].title`	indefinite	["Sword of Honour","Moby Dick","The Lord of the Rings"]
`$.books[?(@.category == "fiction" && @.price < 10)].title`	indefinite	["Moby Dick"]
`$..[?(@.id)]`	indefinite	[ { "price": 8.95, "id": 1, "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century" }, { "price": 12.99, "id": 2, "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour" }, { "price": 8.99, "id": 3, "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3" }, { "price": 22.99, "id": 4, "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8" } ]
`$.services..[?(@.price > 50)].description`	indefinite	'["Printing and assembling book in A5 format", "Rebinding torn book"]
`$..id.length()`	definite	4
`$.books[?(@.id == 2)].title.first()`	definite	Sword of Honour
`$..tags.first().length()`	definite	5	$..tags は不定パスなので、一致した要素の配列 - [["a", "b", "c", "d", "e" ]] を返します。first() は最初の要素 - ["a", "b", "c", "d", "e" ] を返し、最後に length() はその長さ - 5 を計算します。
`$.books[*].price.min()`	definite	8.95
`$..price.max()`	definite	154.99
`$.books[?(@.category == "fiction")].price.avg()`	definite	14.99
`$.books[?(@.category == $.filters.xyz)].title`	indefinite		一致のないクエリは、明確なパスと不明確なパスに対して NULL を返します。
`$.services[?(@.active=="true")].servicegroup`	indefinite	[1001,1000]	ブール値の比較ではテキスト定数を使用する必要があります。
`$.services[?(@.active=="false")].servicegroup`	indefinite	[1002]	ブール値の比較ではテキスト定数を使用する必要があります。
`$.services[?(@.servicegroup=="1002")]~.first()`	definite	restoration

Documentation

3 JSONPath機能

概要

対応セグメント

フィルター式

関数

出力値

空白文字

文字列

例

入力データ