表9.42「json
とjsonb
演算子」に2つのJSONデータ型(8.14. JSONデータ型を参照)で使用可能な演算子を示します。
表9.42 json
とjsonb
演算子
演算子 | 右オペランド型 | 説明 | 例 | 例の結果 |
---|---|---|---|---|
-> | int | JSON配列要素を取得(添字はゼロから、負数なら後ろから数える) | '[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json->2 | {"c":"baz"} |
-> | text | キーに依るJSONオブジェクトフィールド取得 | '{"a": {"b":"foo"}}'::json->'a' | {"b":"foo"} |
->> | int | JSON 配列要素をtext として取得 | '[1,2,3]'::json->>2 | 3 |
->> | text | JSON オブジェクトフィールドをtext として取得 | '{"a":1,"b":2}'::json->>'b' | 2 |
#> | text[] | 指定されたパスにあるJSONオブジェクトを取得 | '{"a": {"b":{"c": "foo"}}}'::json#>'{a,b}' | {"c": "foo"} |
#>> | text[] | 指定されたパスにあるJSONオブジェクトをtext として取得 | '{"a":[1,2,3],"b":[4,5,6]}'::json#>>'{a,2}' | 3 |
json
とjsonb
型の両方に対して、以上の演算子の対応するものがあります。
フィールド/要素/パス抽出演算子は左辺の入力と同じ型(json
またはjsonb
)を返します。
ただし、text
を返すと明示してあるものは、値をテキストに変換して返します。
JSON入力が要求と一致する正しい構造をしていなければ、フィールド/要素/パス抽出演算子は失敗するのではなくNULLを返します。例えばそのような要素が存在しない場合です。
JSON配列の添字を整数で受け取り、フィールド、要素、パスを返す演算子はすべて、配列の終わりから数える負の添字をサポートします。
表9.1「比較演算子」に示されている標準の比較演算子がjsonb
で利用可能ですが、json
ではそうではありません。
それらは8.14.4. jsonb
インデックスで概略を述べたB-tree演算子の順序規則に従います。
ほかにjsonb
だけで利用可能な演算子もいくつか存在します。
それらを表9.43「追加jsonb
演算子」に示します。
これらのうち多くの演算子はjsonb
演算子クラスでインデックス付けすることが可能です。
jsonb
の包含と存在の意味に関する完全な記述は8.14.3. jsonb
型用包含演算子と存在演算子を参照してください。
8.14.4. jsonb
インデックスには、jsonb
データを効率的にインデックス付けするためにこれらの演算子をどのように利用できるかについて書いてあります。
表9.43 追加jsonb
演算子
演算子 | 右オペランド型 | 説明 | 例 |
---|---|---|---|
@> | jsonb | 左のJSON値はトップレベルにおいて右のJSONパスまたは値を包含するか | '{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb |
<@ | jsonb | 左のJSONパスまたは値は右のJSON値にトップレベルで包含されるか | '{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb |
? | text | 文字列はJSON値のトップレベルのキーとして存在するか | '{"a":1, "b":2}'::jsonb ? 'b' |
?| | text[] | 配列の文字列のいずれかがトップレベルのキーとして存在するか。 | '{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'c'] |
?& | text[] | 配列の文字列のすべてがトップレベルのキーとして存在するか。 | '["a", "b"]'::jsonb ?& array['a', 'b'] |
|| | jsonb | 2つのjsonb 値を結合して、新しいjsonb 値を作る | '["a", "b"]'::jsonb || '["c", "d"]'::jsonb |
- | text | 左のオペランドからキー/値のペア、あるいは文字列要素を削除する。 キー/値のペアはキーの値に基づいてマッチされる。 | '{"a": "b"}'::jsonb - 'a' |
- | integer | 指定した添字の配列要素を削除する(負数の場合は後ろから数えます)。 トップレベルのコンテナが配列でないときはエラーが発生する。 | '["a", "b"]'::jsonb - 1 |
#- | text[] | 指定したパスのフィールドまたは要素を削除する(JSON配列では、負数は後ろから数えます) | '["a", {"b":1}]'::jsonb #- '{1,b}' |
||
演算子は、両オペランドのトップレベルで要素を結合します。
再帰的には作用しません。
例えば、両方のオペランドが同じキーフィールド名のオブジェクトの場合、そのフィールドの値は、単に右側のオペランドの値になります。
表9.44「JSON作成関数」に、JSON値およびjsonb
値を作成するために利用可能な関数を示します。
(row_to_json
関数およびarray_to_json
関数と同等なjsonb
の関数はありません。
しかし、to_jsonb
を使えば、これらの関数と同じ機能を提供できるでしょう。)
表9.44 JSON作成関数
関数 | 説明 | 例 | 例の結果 |
---|---|---|---|
| json あるいはjsonb として値を返す。
配列と複合型は(再帰的に)配列とオブジェクトに変換される。
あるいは、その型からjson にキャストがあれば、キャスト関数が変換のために用いられる。
そうでなければ、スカラ値が生成される。
数値、論理値、またはNULL値以外のスカラ型に対しては、有効なjson 値あるいはjsonb 値となる形式の文字列表現が使用される。
| to_json('Fred said "Hi."'::text) | "Fred said \"Hi.\"" |
array_to_json(anyarray [, pretty_bool])
| 配列をJSON配列として返す。
PostgreSQLの多次元配列はJSON配列の配列となる。
pretty_bool が真の場合、次元数-1の要素の間に改行が加えられる。
| array_to_json('{{1,5},{99,100}}'::int[]) | [[1,5],[99,100]] |
row_to_json(record [, pretty_bool])
| 行をJSONオブジェクトとして返す。
pretty_bool が真の場合、レベル-1の要素の間に改行が加えられる。
| row_to_json(row(1,'foo')) | {"f1":1,"f2":"foo"} |
| 異なる型から構成される可能性のあるJSON配列をvariadic引数リストから作成。 | json_build_array(1,2,'3',4,5) | [1, 2, "3", 4, 5] |
| variadic引数リストからJSONオブジェクトを作成。 慣例により引数リストはキーと値が交互に並んだもの。 | json_build_object('foo',1,'bar',2) | {"foo": 1, "bar": 2} |
| テキスト配列からJSONオブジェクトを作成。 配列は、偶数個の要素からなる1次元(キー/値の対が交互に並んでいるものと扱われる))あるいは内側の配列が2つの要素を持つ2次元(2つの要素がキー/値の対として扱われる)のいずれかでなければならない。 |
| {"a": "1", "b": "def", "c": "3.5"} |
| この形のjson_object は2つの別々の配列からキーと値の対を取る。
他の点ではすべて、引数1つの形と同じ。
| json_object('{a, b}', '{1,2}') | {"a": "1", "b": "2"} |
array_to_json
とrow_to_json
は表示を整えるオプションを提供する以外はto_json
と同様の振舞いをします。
同様にto_json
に書かれた振舞いはJSON作成関数により変換された個々の値に適用されます。
hstore拡張はhstore
からjson
へのキャストを含みます。従って、JSON作成関数で変換されたhstore
値は元の文字列値ではなくJSONオブジェクトとして示されます。
表9.45「JSON処理関数」にjson
とjsonb
値を処理するのに使える関数を示します。
表9.45 JSON処理関数
関数 | 戻り値型 | 説明 | 例 | 例の結果 |
---|---|---|---|---|
| int | JSON配列の最も外側の要素の数を返す。 | json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]') | 5 |
|
| JSONオブジェクトの最も外側をkey/valueの組み合わせに拡張する。 | select * from json_each('{"a":"foo", "b":"bar"}') | key | value -----+------- a | "foo" b | "bar" |
| setof key text, value text | JSONオブジェクトの最も外側をkey/valueの組み合わせに拡張する。返り値は型text 。
| select * from json_each_text('{"a":"foo", "b":"bar"}') | key | value -----+------- a | foo b | bar |
|
| path_elems で示されたJSONオブジェクトを返す(#> と同じ)。
| json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4') | {"f5":99,"f6":"foo"} |
| text | path_elems で示されたJSONオブジェクトをtext として返す(#>> 演算子と同じ)。
| json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4', 'f6') | foo |
| setof text | 最も外側のJSONオブジェクトの中のキーの集合を返す。 | json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}') | json_object_keys ------------------ f1 f2 |
| anyelement | from_json 内のオブジェクトを行をbase で定義されたレコード型に一致する列に拡張する(以下の注意書きを参照)。
| select * from json_populate_record(null::myrowtype, '{"a":1,"b":2}') | a | b ---+--- 1 | 2 |
| setof anyelement | from_json におけるオブジェクトの最も外側の配列をbase で定義されたレコード型に一致する列を持つ行の集合に展開する(以下の注意書き参照)。
| select * from json_populate_recordset(null::myrowtype, '[{"a":1,"b":2},{"a":3,"b":4}]') | a | b ---+--- 1 | 2 3 | 4 |
|
| JSON配列をJSON値の集合に展開する。 | select * from json_array_elements('[1,true, [2,false]]') | value ----------- 1 true [2,false] |
| setof text | JSON配列をtext 値の集合に展開する。
| select * from json_array_elements_text('["foo", "bar"]') | value ----------- foo bar |
| text | 最も外側のJSON値の型をテキスト文字列として返す。
取りうる型はobject 、 array 、 string 、 number 、boolean 、null である。
| json_typeof('-123.4') | number |
| record | JSONオブジェクトから任意のレコードを作成する(下記の注釈を参照)。
record を返す関数すべてと同様、呼び出し側がAS 句でレコードの構造を明示的に決める必要がある。
| select * from json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}') as x(a int, b text, d text) | a | b | d ---+---------+--- 1 | [1,2,3] | |
| setof record | オブジェクトの配列のJSONから任意のレコードの集合を作成する(下記の注釈を参照)。
record を返す関数すべてと同様、呼び出し側がAS 句でレコードの構造を明示的に決める必要がある。
| select * from json_to_recordset('[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]') as x(a int, b text); | a | b ---+----- 1 | foo 2 | |
|
| NULL値を持つオブジェクトフィールドを削除したfrom_json を返す。
他のNULL値はそのまま残る。
| json_strip_nulls('[{"f1":1,"f2":null},2,null,3]') | [{"f1":1},2,null,3] |
|
| path で指定した部分をnew_value で置換、
あるいはcreate_missing が真(デフォルトはtrue )でpath で指定した項目が存在しないならnew_value を追加して、
target を返す。
パスの位置についての演算子について、path の中にある負の整数はJSON配列の終わりから数える。
|
|
|
|
| new_value を挿入してtarget を返す。
path で指定したtarget の部分がJSONB配列内にある場合は、new_value はtargetの前に挿入されるか、あるいは、insert_after が真であれば(デフォルトはfalse )、後に挿入される。
path で指定したtarget の部分がJSONBオブジェクト内にある場合は、new_value はtarget が存在しない場合にのみ挿入される。
pathについての演算子について言うと、new_value 内の負の整数はJSON配列の終わりから数える。
|
|
|
|
| from_json をインデントしたJSON文字列にして返す。
| jsonb_pretty('[{"f1":1,"f2":null},2,null,3]') | [ { "f1": 1, "f2": null }, 2, null, 3 ] |
これらの多くの関数や演算子は、JSON文字列のUnicodeのエスケープを適切な一文字に変換します。
これは入力がjsonb
型であれば、変換は既に行なわれていますので、重要な問題ではありません。しかし、json
の入力に対しては、8.14. JSONデータ型で言及したようにこれはエラーを発生させる結果になるかもしれません.
json_populate_record
、json_populate_recordset
、json_to_record
およびjson_to_recordset
におけるJSONからの型強制は「最善努力」であり、ある型では望んだ結果にならないかもしれません。
JSONキーは対象の行の型の中の同一の列の名前と一致します。
対象の行の型に現れないJSONフィールドは出力から省略され、JSONフィールドに一致しない対象の列は単にNULLになります。
jsonb_set
およびjsonb_insert
のpath
パラメータは、最後の項目を除き、すべての項目がtarget
内に存在しなければなりません。
create_missing
が偽ならなら、jsonb_set
のpath
パラメータのすべての項目が存在しなければなりません。
これらの条件が満たされなければ、target
が変更されずに返されます。
パスの最後の要素がオブジェクトのキーの場合、それが存在しなければ作成されて、新しい値が与えられます。
パスの最後の項目が配列の添字の場合、それが正ならセットすべき項目は左から数えられ、負なら右から数えられます(-1
は最も右側の要素を指す、という具合です)。
項目が[-array_length .. array_length -1]の範囲外にあり、かつcreate_missingが真なら、新しい値が配列の先頭(項目が負数のとき)あるいは配列の終わり(項目が正数のとき)に追加されます。
json_typeof
のnull
戻り値をSQLのNULLと混同してはいけません。
json_typeof('null'::json)
を呼び出すとnull
が返りますが、json_typeof(NULL::json)
を呼び出すとSQLのNULLが返ります。
json_strip_nulls
の引数で、オブジェクト内にフィールド名が重複しているものがある場合、それが発生している順序によって、結果は意味的にやや異なるものになることがあります。
jsonb
値はオブジェクトのフィールド名が重複することがないので、jsonb_strip_nulls
にはこのような問題はありません。
レコードの値をJSONに集約するjson_agg
集約関数、値の対をJSONオブジェクトに集約するjson_object_agg
集約関数、およびそれらのjsonb
版のjsonb_agg
とjsonb_object_agg
については9.20. 集約関数を参照して下さい。