他のバージョンの文書9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

9.15. JSON関数と演算子

表9-40は2つのJSONデータ型(項8.14を参照)で使用可能な演算子を示しています。

表 9-40. jsonjsonb演算子

演算子右オペランド型説明例の結果
->intJSON配列要素取得(添字はゼロから)'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json->2{"c":"baz"}
->textキーに依るJSONオブジェクトフィールド取得'{"a": {"b":"foo"}}'::json->'a'{"b":"foo"}
->>intJSON 配列要素をtextとして取得'[1,2,3]'::json->>23
->>textJSON オブジェクトフィールドを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

注意: jsonjsonb型の両方に対して、以上の演算子の対応するものがあります。 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_jsonrow_to_jsonは表示を整えるオプションを提供する以外はto_jsonと同様の振舞いをします。 同様にto_jsonに書かれた振舞いはJSON作成関数により変換された個々の値に適用されます。

注意: hstore拡張はhstoreからjsonへのキャストを含みます。従って、JSON作成関数で変換されたhstore値は元の文字列値ではなくJSONオブジェクトとして示されます。

表9-43jsonjsonb値を処理するのに使える関数を示します。

表 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の組み合わせに拡張する。返り値は型textselect * 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)

anyelementfrom_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 anyelementfrom_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値の型をテキスト文字列として返す。取りうる型はobjectarraystringnumberbooleannullである。 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_recordjson_to_recordset、JSONからの型強制は"最善努力"であり、ある型では望んだ結果にならないかもしれません。 JSONキーは対象の行の型の中の同一の列の名前と一致します。 対象の行の型に現れないJSONフィールドは出力から省略され、JSONフィールドに一致しない対象の列は単にNULLになります。

注意: json_typeofnull戻り値をSQLのNULLと混同してはいけません。 json_typeof('null'::json)を呼び出すとnullが返りますが、json_typeof(NULL::json)を呼び出すとSQLのNULLが返ります。

レコードの値をJSONに集約するjson_agg集約関数や、値の対をJSONオブジェクトに集約するjson_object_agg集約関数については項9.20も参照してください。