PostgreSQL JSON 函数和操作符

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

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

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

jsonb ?& text[] → boolean

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

"["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"}

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相同，只是如果可选boolean参数为真，换行符将在顶级数组元素之间添加。

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

row_to_json ( record [, boolean ] ) → json

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

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 ( text[] ) → json

jsonb_object ( text[] ) → jsonb

从文本数组构建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从单独的文本数组中成对地获取键和值。否则，它与单参数形式相同。

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

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数组展开为一组文本值。

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

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对象扩展为一组键/值对。返回的值的类型为文本。

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子对象提取为文本。(这在功能上等同于#>>操作符。)

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对象扩展为具有基本参数的复合类型的行。JSON对象将被扫描，查找名称与输出行类型的列名匹配的字段，并将它们的值插入到输出的这些列中。 (不对应任何输出列名的字段将被忽略。)在典型的使用中，基本的值仅为NULL，这意味着任何不匹配任何对象字段的输出列都将被填充为空。 但是，如果 base 不为NULL，那么它包含的值将用于不匹配的列。

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

虽然下面的示例使用一个常量JSON值，典型的用法是在查询的FROM子句中从另一个表侧面地引用json或jsonb列。 在FROM子句中编写json_populate_record是一种很好的实践，因为提取的所有列都可以使用，而不需要重复的函数调用。

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数组展开为一组具有基本参数的复合类型的行。 对于json[b]_populate_record，将如上所述处理JSON数组的每个元素。

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[b]_populate_record，将如上所述处理JSON数组的每个元素。

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。 与面向路径操作符一样，负整数出现在JSON数组末尾的path计数中。 如果最后一个路径步骤是超出范围的数组索引，并且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。 与面向路径操作符一样，负整数出现在JSON数组末尾的 path计数中。 如果最后一个路径步骤是超出范围的数组下标，则如果下标为负，则将新值添加到数组的开头;如果下标为正，则将新值添加到数组的结尾。

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值中删除所有具有空值的对象字段，递归地。非对象字段的空值是未受影响的。

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