JSON函数和操作符

操作符

右操作数类型

返回类型

描述

用法示例

示例结果

->

int

json/jsonb

获取json数组中元素（索引从0开始，负整数表示从末尾开始数）。

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

{"c":"baz"}

->

text

json/jsonb

通过键获取json对象。

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

{"b":"foo"}

->>

int

text

以text类型获取json数组中元素。

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

3

->>

text

text

以text类型通过键获取json对象。

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

2

#>

text[]

json/jsonb

获取指定路径的json对象。

'{"a": {"b":{"c": "foo"}}}'::json#>'{a,b}'

{"c": "foo"}

#>>

text[]

text

以text类型获取指定路径的json对象。

'{"a":[1,2,3],"b":[4,5,6]}'::json#>>'{a,2}'

3

操作符

右操作数类型

描述

用法示例

@>

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

将两个jsonb值连接为一个新的jsonb值。

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

-

text

删除左边的键值对或字符串元素。键值对是基于右边的键来匹配。

'{"a": "b"}'::jsonb - 'a'

-

text[]

删除左边的多个键值对或字符串元素。键值对是基于右边的键来匹配。

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

-

integer

删除左边指定索引（负整数表示从末尾开始数）的数组元素。如果顶层不是数组则抛出异常。

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

#-

text[]

删除左边json数组中具有指定路径的域或元素（负整数表示从末尾开始数）。

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

@?

jsonpath

json路径是否返回左边指定的json值的任意项。

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

@@

jsonpath

返回右边指定的json路径检查结果。只考虑结果的首项。 如果结果非布尔值，返回null 。

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

函数

描述

用法示例

示例结果

to_json(any element)

to_jsonb(any element)

将括号中的值返回为json或者jsonb。

• 数组和集合会被转换成数组和对象。

• 对于不是数组和集合的值，如果存在从该类型到json的转换函数，将用该函数来执行转换；否则将产生一个标量值。

• 对于任何不是数字、布尔值、空值的标量类型，将使用文本表示，在这种情况下它是一个合法的json或者jsonb值。

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

"Fred said \"Hi.\""

array_to_json(any array, [pretty_bool])

将数组返回为一个json数组。 PostgreSQL中一个多维数组会返回为一个json格式的数组。若pretty_bool为真，将在第一维度的元素之间增加换行。

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

[[1,5],[99,100]]

row_to_json(record, [pretty_bool])

将行返回为一个json对象。若pretty_bool为真，将在第一层元素之间增加换行。

row_to_json(row(1,'foo'))

{"f1":1,"f2":"foo"}

json_build_array(VARIADIC "any")

jsonb_build_array(VARIADIC "any")

由一个可变参数列表构造一个可能包含异质类型的json数组。

json_build_array(1,2,'3',4,5)

[1, 2, "3", 4, 5]

json_build_object(VARIADIC "any")

jsonb_build_object(VARIADIC "any")

由一个可变参数列表构造一个json对象。通过转换，该参数列表由交替出现的键和值组成。

json_build_object('foo',1,'bar',2)

{"foo": 1, "bar": 2}

json_object(text[])

jsonb_object(text[])

由一个文本数组构造一个json对象。该数组必须是具有偶数个成员的一维数组（成员被看作交替出现的键值对），或是一个二维数组（每个内部数组恰好有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[])

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

json_object是从两个独立的数组得到键值对。在其他方面和一个参数的形式相同。

json_object('{a, b}', '{1,2}')

{"a": "1", "b": "2"}

函数

返回值

描述

用法示例

示例结果

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)

set of key text, value json

set of key text, value jsonb

将最外层json对象展开为一组键值对。

SELECT * FROM json_each('{"a":"foo", "b":"bar"}')

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

json_each_text(json)

jsonb_each_text(jsonb)

set of key text, value text

将最外层json对象展开为一组键值对。返回值是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

以text类型返回由path_elems指向的JSON值（效果同#>>操作符）。

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

foo

json_object_keys(json)

jsonb_object_keys(jsonb)

set of text

返回最外层json对象中的键集合。

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

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

json_populate_record(base any element, from_json json)

jsonb_populate_record(base any element, from_json jsonb)

any element

将from_json中的对象展开为一行，它的列匹配是由base定义的记录类型。

SELECT * FROM json_populate_record(null::myrowtype, '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}}')

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

json_populate_recordset(base any element, from_json json)

jsonb_populate_recordset(base any element, from_json jsonb)

set of any element

将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)

set of json

set of 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)

set of 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, c text)

 a |    b    | c   |
---+---------+-----+
 1 | [1,2,3] | bar |

json_to_recordset(json)

jsonb_to_recordset(jsonb)

set of 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 |

json_strip_nulls(from_json json)

jsonb_strip_nulls(from_json jsonb)

json

jsonb

返回from_json，其中所有存在空值的对象域都被省略，其他空值除外。

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

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

jsonb_set(jsonb, path text[], new_value jsonb[,create_missing boolean])

jsonb

返回jsonb，其中由path指定的项用new_value替换。若path指定的项不存在并且create_missing为true（默认为true）则加上new_value。正如面向路径的操作符一样，出现在path中的负整数表示从json数组的末尾开始数。

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

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

[{"f1":[2,3,4],"f2":null},2,null,3]

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

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

jsonb

返回被插入了new_value的jsonb。如果path指定的jsonb在一个jsonb数组中，new_value将被插入到目标之前（当insert_after默认为false）或之后（当insert_after为true）。如果path指定的target在一个jsonb对象内，则只有target不存在时才插入new_value。对于面向路径的操作符来说，出现在path中的负整数表示从JSON数组的末尾开始数。

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

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

{"a": [0, "new_value", 1, 2]}

{"a": [0, 1, "new_value", 2]}

jsonb_pretty(from_json jsonb)

text

将from_json返回为一段缩进后的json文本。

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

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

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

boolean

检查json路径是否为指定的json值返回任意项。

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

true

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

boolean

返回指定的json路径检查结果。 只考虑结果的首项。 如果结果非布尔值，则返回null。

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

true

jsonb_path_query(target jsonb, path jsonpath [, vars jsonb [, silent bool]])

set of jsonb

获取指定的json值的json路径返回的全部json项。

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 bool]])

jsonb

获取指定json路径返回的全部json项，并将结果封装为数组。

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 bool]])

jsonb

获取指定的json值的第一个json路径返回的json项。 如果无结果，则返回NULL。

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

2