PostgreSQL jsonb_set_lax() 函数使用指南

PostgreSQL jsonb_set_lax() 函数替换指定的路径上的值或者在指定的路径上插入值。此函数与 jsonb_set() 的不同之处是对 NULL 值的处理方式不同。

jsonb_set_lax() 语法

这是 PostgreSQL jsonb_set_lax() 函数的语法:

jsonb_set_lax(
    target JSONB
  , path TEXT[]
  , new_value JSONB
  [, create_if_missing BOOLEAN
  [, null_value_treatment TEXT]]
) -> JSONB

参数

target
必需的。 要插入新值的 JSONB 值。
path
必需的。 一个文本数组,指示了新值插入的位置。数组中靠前的路径,应该包含数组中靠后的路径。
new_value
必需的。 要插入的新值。
create_if_missing
可选的。 它指示如果指定的路径不存在时是否添加指定的新值。默认值为 true
null_value_treatment
可选的。 它指示了当 new_value 为 NULL 时的不同的处理方式。它是一个字符串,可以接收以下 4 个值:
  • 'raise_exception': 当 new_value 为 NULL 时,给出一个错误。
  • 'use_json_null': 当 new_value 为 NULL 时,使用 JSON null 值。
  • 'delete_key': 当 new_value 为 NULL 时,删掉对应的键。
  • 'return_target': 当 new_value 为 NULL 时,返回原来的 JSON 值。

返回值

PostgreSQL jsonb_set_lax() 函数返回给定的 JSONB 值,其中指定的路径被新值替换,或者 create_if_missing 为 true (默认值) 时添加新的值。

当参数 new_value 不为 NULL 时,此函数的行为与 jsonb_set() 完全相同。

当参数 new_value 为 NULL 时,您可以通过参数 null_value_treatment 来对 NULL 值采取不同的动作:

  • 'raise_exception': 给出一个错误
  • 'use_json_null': 使用 JSON null 值
  • 'delete_key': 删掉对应的键
  • 'return_target': 不采取任何操作,返回原来的 JSON 值

如果参数 targetpath 为 NULL,jsonb_set_lax() 函数将返回 NULL。

jsonb_set_lax() 示例

数组

下面的示例展示了如何使用 PostgreSQL jsonb_set_lax() 函数更新一个 JSON 数组中的元素。

SELECT jsonb_set_lax('[0, 1, 2]', '{1}', '"x"');
  jsonb_set_lax
-------------
 [0, "x", 2]

这里,路径数组 {1} 指向 [0, 1, 2] 数组中的索引为 1 的元素。

下面的示例展示了如何使用 PostgreSQL jsonb_set_lax() 函数更新一个内嵌的 JSON 数组中的元素。

SELECT jsonb_set_lax('[0, [1, 2], 2]', '{1, 1}', '"x"');
    jsonb_set_lax
------------------
 [0, [1, "x"], 2]

这里,路径数组 {1, 1} 指向数组 [0, [1, 2], 2] 中的索引为 1 的内嵌数组中的索引为 1 的元素。

对象

下面的示例展示了如何使用 PostgreSQL jsonb_set_lax() 函数更新一个 JSON 对象中的字段。

SELECT jsonb_set_lax('{"x": 1}', '{x}', '"x"');
 jsonb_set_lax
------------
 {"x": "x"}

下面的示例展示了如何使用 PostgreSQL jsonb_set_lax() 函数在一个 JSON 对象中插入一个新的字段。

SELECT jsonb_set_lax('{"x": 1}', '{y}', '2');
    jsonb_set_lax
------------------
 {"x": 1, "y": 2}

这里,由于 JSON 对象 {"x": 1} 中不存在路径 y,因此 jsonb_set_lax() 在 JSON 对象 {"x": 1} 中插入一个值为 2 的字段 y。当然,您也可以通过将 create_if_missing 设置为 false 来禁止这种默认插入的行为,比如:

SELECT jsonb_set_lax('{"x": 1}', '{y}', '2', false);
 jsonb_set_lax
-----------
 {"x": 1}

这里,因为禁止了默认插入的行为,因此返回了原来的 JSON 文档。

NULL 值

下面的示例展示了如何使用 PostgreSQL jsonb_set_lax() 函数在一个 JSON 对象中插入一个新的字段。

SELECT jsonb_set_lax('{"x": 1, "y": 2}', '{y}', NULL);
    jsonb_set_lax
---------------------
 {"x": 1, "y": null}

这里,我们为键 y 使用了一个 NULL 值, jsonb_set_lax() 函数使用了 JSON null 值,这是默认的行为。我们也可以通过参数 null_value_treatment 改变这种行为,比如:

  • delete_key

    SELECT jsonb_set_lax('{"x": 1, "y": 2}', '{y}', NULL, true, 'delete_key');
    
    jsonb_set_lax
    ---------------
    {"x": 1}

    这个例子中,我们为参数 null_value_treatment 使用了 'delete_key',那么键 y 被删除了。

  • return_target

    SELECT jsonb_set_lax('{"x": 1, "y": 2}', '{y}', NULL, true, 'return_target');
    
    jsonb_set_lax
    ------------------
    {"x": 1, "y": 2}

    这个例子中,我们为参数 null_value_treatment 使用了 'return_target',因此 jsonb_set_lax() 函数返回了原来的 JSON 对象。

  • raise_exception

    SELECT jsonb_set_lax('{"x": 1, "y": 2}', '{y}', NULL, true, 'raise_exception');
    
    错误:  JSON value must not be null
    描述:  Exception was raised because null_value_treatment is "raise_exception".
    提示:  To avoid, either change the null_value_treatment argument or ensure that an SQL NULL is not passed.

    这个例子中,我们为参数 null_value_treatment 使用了 'raise_exception',因此 jsonb_set_lax() 函数给出了一个错误。