JSONB_INSERT

功能描述

JSONB_INSERT函数用于将一个新值插入到JSONB值中的指定路径位置。

函数返回在给定路径上插入了指定新值后的JSONB值。

注意事项

• 路径中的所有前值都必须存在，否则将原封不动地返回target（原JSONB值）。
• 如果最后一个路径值是超出范围的数组索引，则新值将添加到数组的开头（如果索引为负）或数组的末尾（如果索引为正）。

语法格式

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

参数说明

• target

  将要插入新值的JSONB值。

• path

  一个文本数组，指示了新值插入的位置。

  • {y, 0} 表示先找到对象中的 y 字段，再找到 y 字段中的索引为 0 的位置。

  • { y, key }表示先找到对象中的 y 字段，再找到 y 字段中对象键为 key 的字段。

  

  • 如果path指向的是一个数组元素：

    • 如果insert_after为假（默认值），则new_value将被插入到该项之前。

    • 如果insert_after为真，则new_value将被插入到该项之后。

  • 如果由path指代的项是一个对象字段，则只在对象不包含该字段时才插入new_value。

  • 出现在路径中的负整数代表从JSON数组的末尾开始计数。

• new_value

  要插入的新值。

• insert_after

  可选参数。 指定new_value是否插入到指定的位置之后：

  • false：新值插入到指定的索引位置。（默认值。）
  • true：新值插入到指定的位置之后。

示例

示例1： 路径指向的是一个范围内的数组元素。

• insert_after为缺省值false：

  select jsonb_insert('{"a": ["This","is","mine"]}', '{a,1}', '"not"');
  

  新值插入到指定的位置，返回结果如下：

              jsonb_insert
  --------------------------------------
  {"a": ["This", "not", "is", "mine"]}
  (1 row)
  

• insert_after设置为true：

  select jsonb_insert('{"a": ["This","is","mine"]}', '{a,1}', '"not"', true);
  

  新值插入到给定位置之后，返回结果如下：

              jsonb_insert
  --------------------------------------
  {"a": ["This", "is", "not", "mine"]}
  (1 row)
  

• insert_after为true，且索引位为负数：

  select jsonb_insert('{"a": ["This","is","mine"]}', '{a,-2}', '"not"', true);
  

  插入位置从最右开始计数，返回结果如下：

              jsonb_insert
  --------------------------------------
  {"a": ["This", "is", "not", "mine"]}
  (1 row)
  

示例2： 路径指向的是一个超出范围的数组元素。

• 路径的后值是超出范围的正数：

  select jsonb_insert('{"a": [1,2,3,4]}', '{a,6}', '"new"');
  

  新值插入到原数组的末尾，返回结果如下：

          jsonb_insert
  ----------------------------
  {"a": [1, 2, 3, 4, "new"]}
  (1 row)
  

• 路径的后值是超出范围的负数：

  select jsonb_insert('{"a": [1,2,3,4]}', '{a,-6}', '"new"');
  

  新值插入到原数组的开头，返回结果如下：

          jsonb_insert
  ----------------------------
  {"a": ["new", 1, 2, 3, 4]}
  (1 row)
  

示例3： path指代的是一个对象字段。

• 对象键“gender”不包含原字段中，插入新值。

  select jsonb_insert('{"CHINESE": {"Id":"abcd","fullName": "李四"}}','{CHINESE,gender}','"男"');
  

  返回结果如下：

                          jsonb_insert
  -----------------------------------------------------------------
  {"CHINESE": {"Id": "abcd", "gender": "男", "fullName": "李四"}}
  (1 row)
  

• 对象键“Id”在原数组中已存在：

  select jsonb_insert('{"CHINESE": {"Id":"abcd","fullName": "李四"}}','{CHINESE,Id}','"1001"');
  

  “Id”已存在，无法插入或替换，报错信息如下：

  ERROR:  cannot replace existing key