| PostgreSQL 9.4.5文書 | |||
|---|---|---|---|
| 前のページ | 上に戻る | 第 9章関数と演算子 | 次のページ |
表9-40は2つのJSONデータ型(項8.14を参照)で使用可能な演算子を示しています。
表 9-40. 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入力が要求と一致する正しい構造をしていなければ、フィールド/要素/パス抽出演算子は失敗するのではなくNULLを返します。例えばそのような要素が存在しない場合です。
表9-1に示されている標準の比較演算子がjsonbで利用可能ですが、jsonではそうではありません。 それらは項8.14.4で概略を述べたB-tree演算子の順序規則に従います。
表9-41に示されているようにjsonbだけにはそれ以上の演算子も存在します。 そのうちの多くの演算子はjsonb演算子クラスでインデックス付けすることが可能です。 jsonbの包含と存在の意味に関する完全な記述は項8.14.3を参照してください。 項8.14.4には、jsonbデータを効率的にインデックス付けするためにこれらの演算子をどのように利用できるかについて書いてあります。
表 9-41. 追加jsonb演算子
| 演算子 | 右オペランド型 | 説明 | 例 |
|---|---|---|---|
| @> | jsonb | 左のJSON値はその中に右の値を包含するか。 | '{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb |
| <@ | jsonb | 左の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'] |
表9-42に、JSON値を作成するために利用可能な関数を示します。 (今のところ、jsonbのための同様な関数はありませんが、以下の関数の結果をjsonbにキャストできます。)
表 9-42. JSON作成関数
| 関数 | 説明 | 例 | 例の結果 |
|---|---|---|---|
| to_json(anyelement) | JSONとして値を返す。 配列と複合型は(それぞれ)配列とオブジェクトに変換される。そうでなければ、その型からjsonにキャストがあれば、キャスト関数が変換のために用いられる。そうでなければ、JSONスカラ値が生成される。 数値、論理値、またはNULL値以外のスカラ型に対しては、有効なJSONと認められるようエスケープおよび引用符で囲まれた文字列表現が使用される。 | 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_build_array(VARIADIC "any") | 異なる型から構成される可能性のあるJSON配列をvariadic引数一覧から作成。 | json_build_array(1,2,'3',4,5) | [1, 2, "3", 4, 5] |
| json_build_object(VARIADIC "any") | variadic引数一覧からJSONオブジェクトを作成。慣例により引数一覧はキーと値が交互に並んだもの。 | json_build_object('foo',1,'bar',2) | {"foo": 1, "bar": 2} |
| json_object(text[]) | テキスト配列からJSONオブジェクトを作成。配列は、以下のどちらかでなければならない。偶数個の要素からなる1次元、この場合にはキー/値の対が交互に並んでいるものと扱われる。内側の配列が2つの要素を持つ2次元、2つの要素がキー/値の対として扱われる。 | json_object('{a, 1, b, "def", c, 3.5}') json_object('{{a, 1},{b, "def"},{c, 3.5}}') | {"a": "1", "b": "def", "c": "3.5"} |
| json_object(keys text[], values text[]) | この形の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-43にjsonとjsonb値を処理するのに使える関数を示します。
表 9-43. JSON処理関数
| 関数 | 戻り値型 | 説明 | 例 | 例の結果 |
|---|---|---|---|---|
json_array_length(json) jsonb_array_length(jsonb) | int | JSON配列の最も外側の要素の数を返す。 | json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]') | 5 |
json_each(json) jsonb_each(jsonb) | setof key text, value json setof key text, value jsonb | JSONオブジェクトの最も外側をkey/valueの組み合わせに拡張する。 | select * from json_each('{"a":"foo", "b":"bar"}') | key | value -----+------- a | "foo" b | "bar" |
json_each_text(json) jsonb_each_text(jsonb) | setof key text, value text | JSONオブジェクトの最も外側をkey/valueの組み合わせに拡張する。返り値は型text。 | select * from json_each_text('{"a":"foo", "b":"bar"}') | key | value -----+------- a | foo b | bar |
json_extract_path(from_json json, VARIADIC path_elems text[]) jsonb_extract_path(from_json jsonb, VARIADIC path_elems text[]) | json jsonb | path_elemsで示されたJSONオブジェクトを返す(#>と同じ)。 | json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4') | {"f5":99,"f6":"foo"} |
json_extract_path_text(from_json json, VARIADIC path_elems text[]) jsonb_extract_path_text(from_json jsonb, VARIADIC path_elems text[]) | text | path_elemsで示されたJSONオブジェクトをtextとして返す(#>>演算子と同じ)。 | json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4', 'f6') | foo |
json_object_keys(json) jsonb_object_keys(jsonb) | setof text | 最も外側のJSONオブジェクトの中のキー一式を返す。 | json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}') | json_object_keys ------------------ f1 f2 |
json_populate_record(base anyelement, from_json json) jsonb_populate_record(base anyelement, from_json jsonb) | anyelement | from_json内のオブジェクトを行をbaseで定義されたレコード型に一致する列に拡張する(以下の注意書きを参照)。 | select * from json_populate_record(null::myrowtype, '{"a":1,"b":2}') | a | b ---+--- 1 | 2 |
json_populate_recordset(base anyelement, from_json json) jsonb_populate_recordset(base anyelement, from_json jsonb) | 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_array_elements(json) jsonb_array_elements(jsonb) | setof json setof jsonb | JSON配列をJSON値の集合に展開する。 | select * from json_array_elements('[1,true, [2,false]]') | value ----------- 1 true [2,false] |
json_array_elements_text(json) jsonb_array_elements_text(jsonb) | setof text | JSON配列をtext値の集合に展開する。 | select * from json_array_elements_text('["foo", "bar"]') | value ----------- foo bar |
json_typeof(json) jsonb_typeof(jsonb) | text | 最も外側のJSON値の型をテキスト文字列として返す。取りうる型はobject、 array、 string、 number、boolean、nullである。 | json_typeof('-123.4') | number |
json_to_record(json) jsonb_to_record(jsonb) | 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] | |
json_to_recordset(json) jsonb_to_recordset(jsonb) | 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 | |
注意: これらの多くの関数や演算子はデータベースエンコードがUTF8の時は、JSON文字列のUnicodeのエスケープを適切な一文字に変換します。 これは入力がjsonb型であれば、変換は既に行なわれていますので、重要な問題ではありません。しかし、jsonの入力に対しては、項8.14で言及したようにこれはエラーを発生させる結果になるかもしれません．
注意:
json_to_recordとjson_to_recordset、JSONからの型強制は"最善努力"であり、ある型では望んだ結果にならないかもしれません。 JSONキーは対象の行の型の中の同一の列の名前と一致します。 対象の行の型に現れないJSONフィールドは出力から省略され、JSONフィールドに一致しない対象の列は単にNULLになります。
注意: json_typeofのnull戻り値をSQLのNULLと混同してはいけません。 json_typeof('null'::json)を呼び出すとnullが返りますが、json_typeof(NULL::json)を呼び出すとSQLのNULLが返ります。
レコードの値をJSONに集約するjson_agg集約関数や、値の対をJSONオブジェクトに集約するjson_object_agg集約関数については項9.20も参照してください。