json -> integer → json

jsonb -> integer → jsonb

提取 JSON 数组的第 n 个元素（数组元素从 0 开始索引，但负整数从末尾开始计数）。

'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> 2 → {"c":"baz"}

'[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> -3 → {"a":"foo"}

json -> text → json

jsonb -> text → jsonb

用给定的键提取 JSON 对象字段。

'{"a": {"b":"foo"}}'::json -> 'a' → {"b":"foo"}

json ->> integer → text

jsonb ->> integer → text

提取 JSON 数组的第 n 个元素，作为 text。

'[1,2,3]'::json ->> 2 → 3

json ->> text → text

jsonb ->> text → text

用给定的键提取 JSON 对象字段，作为 text。

'{"a":1,"b":2}'::json ->> 'b' → 2

json #> text[] → json

jsonb #> text[] → jsonb

提取指定路径下的 JSON 子对象，路径元素可以是字段键或数组索引。

'{"a": {"b": ["foo","bar"]}}'::json #> '{a,b,1}' → "bar"

json #>> text[] → text

jsonb #>> text[] → text

将指定路径上的 JSON 子对象提取为 text。

'{"a": {"b": ["foo","bar"]}}'::json #>> '{a,b,1}' → bar

jsonb @> jsonb → boolean

第一个 JSON 值是否包含第二个？（请参见第 8.14.3 节以了解包含的详细信息。）

'{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb → t

jsonb <@ jsonb → boolean

第二个 JSON 中是否包含第一个 JSON 值？

'{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb → t

jsonb ? text → boolean

文本字符串是否作为 JSON 值中的顶级键或数组元素存在？

'{"a":1, "b":2}'::jsonb ? 'b' → t

'["a", "b", "c"]'::jsonb ? 'b' → t

jsonb ?| text[] → boolean

text 数组中的字符串是否至少有一个作为顶级键或数组元素存在？

'{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'd'] → t

jsonb ?& text[] → boolean

text 数组中的所有字符串都作为顶级键或数组元素存在吗？

'["a", "b", "c"]'::jsonb ?& array['a', 'b'] → t

jsonb || jsonb → jsonb

连接两个 jsonb 值。连接两个数组将生成一个包含每个输入的所有元素的数组。连接两个对象将生成一个包含它们键的并集的对象，当存在重复的键时取第二个对象的值。所有其他情况都通过将非数组输入转换为单元素数组来处理，然后按照两个数组的方式进行处理。不递归操作：只有顶级数组或对象结构会被合并。

'["a", "b"]'::jsonb || '["a", "d"]'::jsonb → ["a", "b", "a", "d"]

'{"a": "b"}'::jsonb || '{"c": "d"}'::jsonb → {"a": "b", "c": "d"}

'[1, 2]'::jsonb || '3'::jsonb → [1, 2, 3]

'{"a": "b"}'::jsonb || '42'::jsonb → [{"a": "b"}, 42]

要将一个数组作为单个元素追加到另一个数组中，请先在它外面再包装一层数组，例如：

'[1, 2]'::jsonb || jsonb_build_array('[3, 4]'::jsonb) → [1, 2, [3, 4]]

jsonb - text → jsonb

从 JSON 对象中删除键（以及它的值），或从 JSON 数组中删除匹配的字符串值。

'{"a": "b", "c": "d"}'::jsonb - 'a' → {"c": "d"}

'["a", "b", "c", "b"]'::jsonb - 'b' → ["a", "c"]

jsonb - text[] → jsonb

从左操作数中删除所有匹配的键或数组元素。

'{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[] → {}

jsonb - integer → jsonb

删除具有指定索引的数组元素（负整数从末尾计数）。如果 JSON 值不是数组，则抛出错误。

'["a", "b"]'::jsonb - 1 → ["a"]

jsonb #- text[] → jsonb

删除指定路径上的字段或数组元素，路径元素可以是字段键或数组索引。

'["a", {"b":1}]'::jsonb #- '{1,b}' → ["a", {}]

jsonb @? jsonpath → boolean

JSON 路径是否为指定的 JSON 值返回任何项?

'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)' → t

jsonb @@ jsonpath → boolean

返回指定 JSON 值的 JSON 路径谓词检查的结果。只考虑结果的第一项。如果结果不是布尔值，则返回 NULL。

'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2' → t

to_json ( anyelement ) → json

to_jsonb ( anyelement ) → jsonb

将任何 SQL 值转换为 json 或 jsonb。数组和复合值递归地转换为数组和对象（多维数组在 JSON 中变成数组的数组）。否则，如果存在从 SQL 数据类型到 json 的类型转换，则类型转换函数将用于执行转换；^[a] 否则，将生成一个标量 JSON 值。对于除数字、布尔值或空值之外的任何标量，将使用文本表示，并根据需要进行转义，使其成为有效的 JSON 字符串值。

to_json('Fred said "Hi."'::text) → "Fred said \"Hi.\""

to_jsonb(row(42, 'Fred said "Hi."'::text)) → {"f1": 42, "f2": "Fred said \"Hi.\""}

array_to_json ( anyarray [, boolean ] ) → json

将 SQL 数组转换为 JSON 数组。该行为与 to_json 相同，只是如果可选布尔参数为真，换行符将在顶级数组元素之间添加。

array_to_json('{{1,5},{99,100}}'::int[]) → [[1,5],[99,100]]

json_array ( [ { value_expression [ FORMAT JSON ] } [, ...] ] [ { NULL | ABSENT } ON NULL ] [ RETURNING data_type [ FORMAT JSON [ ENCODING UTF8 ] ] ])

json_array ( [ query_expression ] [ RETURNING data_type [ FORMAT JSON [ ENCODING UTF8 ] ] ])

从一系列 value_expression 参数或 query_expression 的结果构造 JSON 数组；后者必须是返回单列的 SELECT 查询。如果指定了 ABSENT ON NULL，则忽略 NULL 值。使用 query_expression 时始终如此。

json_array(1,true,json '{"a":null}') → [1, true, {"a":null}]

json_array(SELECT * FROM (VALUES(1),(2)) t) → [1, 2]

row_to_json ( record [, boolean ] ) → json

将 SQL 复合值转换为 JSON 对象。该行为与 to_json 相同，只是如果可选布尔参数为真，换行符将在顶级元素之间添加。

row_to_json(row(1,'foo')) → {"f1":1,"f2":"foo"}

json_build_array ( VARIADIC "any" ) → json

jsonb_build_array ( VARIADIC "any" ) → jsonb

根据可变参数列表构建可能异构类型的 JSON 数组。每个参数都按照 to_json 或 to_jsonb 进行转换。

json_build_array(1, 2, 'foo', 4, 5) → [1, 2, "foo", 4, 5]

json_build_object ( VARIADIC "any" ) → json

jsonb_build_object ( VARIADIC "any" ) → jsonb

根据可变参数列表构建一个 JSON 对象。按照惯例，参数列表由交替的键和值组成。键参数会被强制转换为文本；值参数则按照 to_json 或 to_jsonb 进行转换。

json_build_object('foo', 1, 2, row(3,'bar')) → {"foo" : 1, "2" : {"f1":3,"f2":"bar"}}

json_object ( [ { key_expression { VALUE | ':' } value_expression [ FORMAT JSON [ ENCODING UTF8 ] ] }[, ...] ] [ { NULL | ABSENT } ON NULL ] [ { WITH | WITHOUT } UNIQUE [ KEYS ] ] [ RETURNING data_type [ FORMAT JSON [ ENCODING UTF8 ] ] ])

根据给定的所有键值对构造 JSON 对象；如果没有给出键值对，则构造空对象。key_expression 是定义 JSON 键的标量表达式，会被转换为 text 类型。它不能为 NULL，其类型也不能具有到 json 的类型转换。如果指定了 WITH UNIQUE KEYS，则 key_expression 不能重复。如果指定了 ABSENT ON NULL，则 value_expression 求值为 NULL 的键值对会从输出中省略；如果指定了 NULL ON NULL 或省略了该子句，则保留该键，并将其值设为 NULL。

json_object('code' VALUE 'P123', 'title': 'Jaws') → {"code" : "P123", "title" : "Jaws"}

json_object ( text[] ) → json

jsonb_object ( text[] ) → jsonb

从 text 数组构造 JSON 对象。该数组必须是一维且包含偶数个成员，此时将成员按交替的键/值对处理；或者是二维数组，且每个内部数组恰好有两个元素，将这两个元素作为一个键/值对。所有值都转换为 JSON 字符串。

json_object('{a, 1, b, "def", c, 3.5}') → {"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

jsonb_object ( keys text[], values text[] ) → jsonb

这种形式的 json_object 从单独的 text 数组中成对地获取键和值。除此之外，它与单参数形式相同。

json_object('{a,b}', '{1,2}') → {"a": "1", "b": "2"}

expression IS [ NOT ] JSON [ { VALUE | SCALAR | ARRAY | OBJECT } ] [ { WITH | WITHOUT } UNIQUE [ KEYS ] ]

该谓词测试 expression 是否可以解析为 JSON，也可以指定具体类型。如果指定 SCALAR、ARRAY 或 OBJECT，则测试 JSON 是否属于该特定类型。如果指定 WITH UNIQUE KEYS，则 expression 中的任意对象还会被检查是否存在重复键。

SELECT js,
  js IS JSON "json?",
  js IS JSON SCALAR "scalar?",
  js IS JSON OBJECT "object?",
  js IS JSON ARRAY "array?"
FROM (VALUES
      ('123'), ('"abc"'), ('{"a": "b"}'), ('[1,2]'),('abc')) foo(js);
     js     | json? | scalar? | object? | array?
------------+-------+---------+---------+--------
 123        | t     | t       | f       | f
 "abc"      | t     | t       | f       | f
 {"a": "b"} | t     | f       | t       | f
 [1,2]      | t     | f       | f       | t
 abc        | f     | f       | f       | f

SELECT js,
  js IS JSON OBJECT "object?",
  js IS JSON ARRAY "array?",
  js IS JSON ARRAY WITH UNIQUE KEYS "array w. UK?",
  js IS JSON ARRAY WITHOUT UNIQUE KEYS "array w/o UK?"
FROM (VALUES ('[{"a":"1"},
 {"b":"2","b":"3"}]')) foo(js);
-[ RECORD 1 ]-+--------------------
js            | [{"a":"1"},        +
              |  {"b":"2","b":"3"}]
object?       | f
array?        | t
array w. UK?  | f
array w/o UK? | t

json_array_elements ( json ) → setof json

jsonb_array_elements ( jsonb ) → setof jsonb

将顶级 JSON 数组展开为一组 JSON 值。

select * from json_array_elements('[1,true, [2,false]]') →

   value
-----------
 1
 true
 [2,false]

json_array_elements_text ( json ) → setof text

jsonb_array_elements_text ( jsonb ) → setof text

将顶级 JSON 数组展开为一组 text 值。

select * from json_array_elements_text('["foo", "bar"]') →

   value
-----------
 foo
 bar

json_array_length ( json ) → integer

jsonb_array_length ( jsonb ) → integer

返回顶层 JSON 数组中的元素数量。

json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]') → 5

jsonb_array_length('[]') → 0

json_each ( json ) → setof record ( key text, value json )

jsonb_each ( jsonb ) → setof record ( key text, value jsonb )

将顶级 JSON 对象展开为一组键/值对。

select * from json_each('{"a":"foo", "b":"bar"}') →

 key | value
-----+-------
 a   | "foo"
 b   | "bar"

json_each_text ( json ) → setof record ( key text, value text )

jsonb_each_text ( jsonb ) → setof record ( key text, value text )

将顶级 JSON 对象展开为一组键/值对。返回的 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[] ) → json

jsonb_extract_path ( from_json jsonb, VARIADIC path_elems text[] ) → jsonb

在指定路径下提取 JSON 子对象。（这在功能上相当于#> 操作符，但在某些情况下，将路径写成可变参数列表会更方便。）

json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6') → "foo"

json_extract_path_text ( from_json json, VARIADIC path_elems text[] ) → text

jsonb_extract_path_text ( from_json jsonb, VARIADIC path_elems text[] ) → text

将指定路径上的 JSON 子对象提取为 text。（这在功能上等同于#>> 操作符。）

json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6') → foo

json_object_keys ( json ) → setof text

jsonb_object_keys ( jsonb ) → setof text

返回顶级 JSON 对象中的键集合。

select * from json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}') →

 json_object_keys
------------------
 f1
 f2

json_populate_record ( base anyelement, from_json json ) → anyelement

jsonb_populate_record ( base anyelement, from_json jsonb ) → anyelement

将顶级 JSON 对象展开为一行，其复合类型与 base 参数相同。系统会扫描该 JSON 对象，查找名称与输出行类型列名匹配的字段，并将其值插入输出中的对应列。（不对应任何输出列名的字段会被忽略。）在典型用法中，base 的值就是 NULL，这意味着凡是不匹配对象字段的输出列都会被填充为空值。但是，如果 base 不是 NULL，那么其中包含的值将用于那些不匹配的列。

要将 JSON 值转换为输出列的 SQL 类型，需要依次应用以下规则：

虽然下面的示例使用的是常量 JSON 值，但典型用法是在查询的 FROM 子句中，以横向方式引用另一个表中的 json 或 jsonb 列。把 json_populate_record 写在 FROM 子句中是一种良好实践，因为这样抽取出的所有列都可以直接使用，而不需要重复调用函数。

create type subrowtype as (d int, e text); create type myrowtype as (a int, b text[], c subrowtype);

select * from json_populate_record(null::myrowtype, '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}, "x": "foo"}') →

 a |   b       |      c
---+-----------+-------------
 1 | {2,"a b"} | (4,"a b c")

json_populate_recordset ( base anyelement, from_json json ) → setof anyelement

jsonb_populate_recordset ( base anyelement, from_json jsonb ) → setof anyelement

将由对象组成的顶级 JSON 数组展开为一组行，其复合类型与 base 参数相同。JSON 数组中的每个元素都按照上文对 json[b]_populate_record 的说明进行处理。

create type twoints as (a int, b int);

select * from json_populate_recordset(null::twoints, '[{"a":1,"b":2}, {"a":3,"b":4}]') →

 a | b
---+---
 1 | 2
 3 | 4

json_to_record ( json ) → record

jsonb_to_record ( jsonb ) → record

将顶级 JSON 对象展开为具有由 AS 子句定义的复合类型的行。（与所有返回 record 的函数一样，调用查询必须使用 AS 子句显式定义记录的结构。）输出记录由 JSON 对象的字段填充，与上面描述的 json[b]_populate_record 的方式相同。由于没有输入记录值，不匹配的列总是用空值填充。

create type myrowtype as (a int, b text);

select * from json_to_record('{"a":1,"b":[1,2,3],"c":[1,2,3],"e":"bar","r": {"a": 123, "b": "a b c"}}') as x(a int, b text, c int[], d text, r myrowtype) →

 a |    b    |    c    | d |       r
---+---------+---------+---+---------------
 1 | [1,2,3] | {1,2,3} |   | (123,"a b c")

json_to_recordset ( json ) → setof record

jsonb_to_recordset ( jsonb ) → setof record

将顶级 JSON 对象数组展开为一组由 AS 子句定义的复合类型的行。（与所有返回 record 的函数一样，调用查询必须使用 AS 子句显式定义记录的结构。）JSON 数组中的每个元素都按照上文对 json[b]_populate_record 的说明进行处理。

select * from json_to_recordset('[{"a":1,"b":"foo"}, {"a":"2","c":"bar"}]') as x(a int, b text) →

 a |  b
---+-----
 1 | foo
 2 |

jsonb_set ( target jsonb, path text[], new_value jsonb [, create_if_missing boolean ] ) → jsonb

返回 target，将 path 指定的项替换为 new_value，如果 create_if_missing 为真（此为默认值）并且 path 指定的项不存在，则添加 new_value。路径中的所有前面步骤都必须存在，否则将不加改变地返回 target。与面向路径的操作符一样，path 中的负整数从 JSON 数组末尾计数。如果最后一个路径步骤是超出范围的数组索引，并且 create_if_missing 为真，那么如果索引为负，新值将添加到数组的开头，如果索引为正，则添加到数组的结尾。

jsonb_set('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', '[2,3,4]', false) → [{"f1": [2, 3, 4], "f2": null}, 2, null, 3]

jsonb_set('[{"f1":1,"f2":null},2]', '{0,f3}', '[2,3,4]') → [{"f1": 1, "f2": null, "f3": [2, 3, 4]}, 2]

jsonb_set_lax ( target jsonb, path text[], new_value jsonb [, create_if_missing boolean [, null_value_treatment text ]] ) → jsonb

如果 new_value 不是 NULL，则行为与 jsonb_set 完全相同。否则，根据 null_value_treatment 的值进行处理，其值必须是'raise_exception'、'use_json_null'、'delete_key' 或'return_target' 之一。默认值为'use_json_null'。

jsonb_set_lax('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', null) → [{"f1": null, "f2": null}, 2, null, 3]

jsonb_set_lax('[{"f1":99,"f2":null},2]', '{0,f3}', null, true, 'return_target') → [{"f1": 99, "f2": null}, 2]

jsonb_insert ( target jsonb, path text[], new_value jsonb [, insert_after boolean ] ) → jsonb

返回插入 new_value 的 target。如果 path 指派的项是一个数组元素，则当 insert_after 为假（此为默认值）时，new_value 将被插入到该项之前；当 insert_after 为真时，则插入到该项之后。如果由 path 指派的项是一个对象字段，则只在对象不包含该键时才插入 new_value。路径中的所有前面步骤都必须存在，否则将不加改变地返回 target。与面向路径的操作符一样，path 中的负整数从 JSON 数组末尾计数。如果最后一个路径步骤是超出范围的数组下标，那么当下标为负时，新值会被添加到数组开头；当下标为正时，新值会被添加到数组末尾。

jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"') → {"a": [0, "new_value", 1, 2]}

jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"', true) → {"a": [0, 1, "new_value", 2]}

json_strip_nulls ( json ) → json

jsonb_strip_nulls ( jsonb ) → jsonb

递归删除给定 JSON 值中所有值为 null 的对象字段。不是对象字段的 null 值保持不变。

json_strip_nulls('[{"f1":1, "f2":null}, 2, null, 3]') → [{"f1":1},2,null,3]

jsonb_path_exists ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → boolean

检查 JSON 路径是否返回指定 JSON 值的任何项。如果指定了 vars 参数，则它必须是一个 JSON 对象，并且它的字段提供要替换到 jsonpath 表达式中的具名值。如果指定了 silent 参数并为 true，函数会抑制与@? 和 @@操作符相同的错误。

jsonb_path_exists('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}') → t

jsonb_path_match ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → boolean

返回指定 JSON 值的 JSON 路径谓词检查的结果。只有结果的第一项被考虑在内。如果结果不是布尔值，则返回 NULL。可选的 vars 和 silent 参数的作用与 jsonb_path_exists 相同。

jsonb_path_match('{"a":[1,2,3,4,5]}', 'exists($.a[*] ? (@ >= $min && @ <= $max))', '{"min":2, "max":4}') → t

jsonb_path_query ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → setof jsonb

为指定的 JSON 值返回由 JSON 路径返回的所有 JSON 项。可选的 vars 和 silent 参数的作用与 jsonb_path_exists 相同。

select * from jsonb_path_query('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}') →

 jsonb_path_query
------------------
 2
 3
 4

jsonb_path_query_array ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → jsonb

以 JSON 数组的形式返回由 JSON 路径为指定的 JSON 值返回的所有 JSON 项。可选的 vars 和 silent 参数的作用与 jsonb_path_exists 相同。

jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}') → [2, 3, 4]

jsonb_path_query_first ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → jsonb

为指定的 JSON 值返回由 JSON 路径返回的第一个 JSON 项。如果没有结果则返回 NULL。可选的 vars 和 silent 参数的作用与 jsonb_path_exists 相同。

jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}') → 2

jsonb_path_exists_tz ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → boolean

jsonb_path_match_tz ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → boolean

jsonb_path_query_tz ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → setof jsonb

jsonb_path_query_array_tz ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → jsonb

jsonb_path_query_first_tz ( target jsonb, path jsonpath [, vars jsonb [, silent boolean ]] ) → jsonb

这些函数的作用类似于上面描述的没有_tz 后缀的对应函数，不同之处在于这些函数支持需要时区感知转换的日期/时间值的比较。下面的示例需要将仅日期值 2015-08-02 解释为带有时区的时间戳，因此结果取决于当前的 TimeZone 设置。由于这种依赖性，这些函数被标记为稳定的，这意味着这些函数不能用于索引。它们的对应函数是不可变的，因此可以用于索引；但如果要求进行这样的比较，它们将抛出错误。

jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]', '$[*] ? (@.datetime() < "2015-08-02".datetime())') → t

jsonb_pretty ( jsonb ) → text

将给定的 JSON 值转换为经过美化并带有缩进的文本。

jsonb_pretty('[{"f1":1,"f2":null}, 2]') →

[
    {
        "f1": 1,
        "f2": null
    },
    2
]

json_typeof ( json ) → text

jsonb_typeof ( jsonb ) → text

以文本字符串形式返回顶级 JSON 值的类型。可能的类型有 object、array、string、number、boolean 和 null。（null 的结果不应与 SQL NULL 混淆；参见示例。）

json_typeof('-123.4') → number

json_typeof('null'::json) → null

json_typeof(NULL::json) IS NULL → t