类别：

:doc:`/sql-reference/functions-semistructured`（数组/对象）

OBJECT_INSERT

返回一个对象，它由输入对象组成，并插入了一个新的键值对（或者用新值更新了现有的键）。

语法

OBJECT_INSERT( <object> , <key> , <value> [ , <updateFlag> ] )
Copy

实参

必填：

object

插入新键值对的源对象。

key

要插入到对象中的新键。必须与对象中的所有现有键不同，除非 updateFlag 设置为 TRUE。

value

与键关联的值。

可选：

updateFlag

布尔标志，当设置为 TRUE 时，指定输入值用于更新/覆盖对象中的现有键，而不是插入新的键值对。

默认为 FALSE。

使用说明

  • 该函数支持 JSON NULL 值，但不支持 SQL NULL 值或键：

    • 如果 key 是 NULL 以外的任何字符串，并且 value 是 JSON NULL（例如 PARSE_JSON('NULL')），则将键值对插入到返回的对象中。

    • 如果 key 或 value 为 SQL NULL，则返回的对象中将省略键值对。

  • 如果可选 updateFlag 实参设置为 TRUE，则现有输入 key 将更新为输入 value。如果 updateFlag 省略或设置为 FALSE，则使用对象中已存在的输入键调用此函数会导致错误。

  • 如果 update 标志设置为 true，但对象中尚不存在相应的键，则会添加键/值对。

  • 对于 结构化 OBJECTs：

    • 对于作为键的实参，您必须指定常量。

    • 当 updateFlag 实参为 FALSE（插入新的键值对时）：

      • 如果指定 OBJECT 中已存在的键，则会发生错误。

        SELECT OBJECT_INSERT(
  {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
  'city',
  'San Jose',
  false
);
        Copy
        093202 (23001): Function OBJECT_INSERT:
  expected structured object to not contain field city but it did.

      • 该函数返回一个结构化的 OBJECT。OBJECT 的类型包括新插入的键。例如，假设您添加具有 DOUBLE 值 94402 的 zipcode 键：

        SELECT
  OBJECT_INSERT(
    {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR,state VARCHAR),
    'zip_code',
    94402::DOUBLE,
    false
  ) AS new_object,
  SYSTEM$TYPEOF(new_object);
        Copy

        该函数返回类型 OBJECT（城市 VARCHAR、州 VARCHAR、邮政编码 DOUBLE）的 OBJECT：

        +-------------------------------------+---------------------------------------------------------------------------------------+
| NEW_OBJECT                          | SYSTEM$TYPEOF(NEW_OBJECT)                                                             |
|-------------------------------------+---------------------------------------------------------------------------------------|
| {                                   | OBJECT(city VARCHAR(16777216), state VARCHAR(16777216), zip_code FLOAT NOT NULL)[LOB] |
|   "city": "San Mateo",              |                                                                                       |
|   "state": "CA",                    |                                                                                       |
|   "zip_code": 9.440200000000000e+04 |                                                                                       |
| }                                   |                                                                                       |
+-------------------------------------+---------------------------------------------------------------------------------------+

        插入值的类型决定了添加到 OBJECT 类型定义中的类型。在本例中，zipcode 的值是转换为 DOUBLE 的值，因此 zipcode 的类型为 DOUBLE。

    • 当 updateFlag 实参为 TRUE（当您替换现有键值对时）：

      • 如果指定的键在 OBJECT 中不存在，则会发生错误。

      • 该函数返回相同类型的结构化 OBJECT。

      • 插入值的类型 强制转换 为现有键的类型。

示例

将第三个键值对插入到包含两个键值对的对象中：

SELECT OBJECT_INSERT(OBJECT_CONSTRUCT('a',1,'b',2),'c',3);

----------------------------------------------------+
 OBJECT_INSERT(OBJECT_CONSTRUCT('A',1,'B',2),'C',3) |
----------------------------------------------------+
 {                                                  |
   "a": 1,                                          |
   "b": 2,                                          |
   "c": 3                                           |
 }                                                  |
----------------------------------------------------+
Copy

将两个新的键值对插入到空对象中，同时省略一个键值对：

  • Key_One 由一个 JSON NULL 值组成。

  • Key_Two 由一个 SQL NULL 值组成，因此被省略。

  • Key_Three 由包含“null”的字符串组成。

SELECT
  OBJECT_INSERT(OBJECT_INSERT(OBJECT_INSERT(OBJECT_CONSTRUCT(), 'Key_One', PARSE_JSON('NULL')), 'Key_Two', NULL), 'Key_Three', 'null')
  AS obj;

-----------------------+
          OBJ          |
-----------------------+
 {                     |
   "Key_One": null,    |
   "Key_Three": "null" |
 }                     |
-----------------------+
Copy

使用新值 ("string-value") 更新现有键值对 ("k1": 100)：

SELECT OBJECT_INSERT(OBJECT_INSERT(OBJECT_CONSTRUCT(),'k1', 100),'k1','string-value', TRUE) AS obj;

------------------------+
          OBJ           |
------------------------+
 {                      |
   "k1": "string-value" |
 }                      |
------------------------+
Copy
语言: 中文