カテゴリ:

半構造化データ関数と構造化データ関数 (配列/オブジェクト)

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 に設定されている場合、オブジェクトに既に存在する入力キーを使用してこの関数を呼び出すと、エラーが発生します。

  • 更新フラグが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(city VARCHAR, state VARCHAR, zipcode 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 を返します。

      • 挿入された値の型は、既存のキーの型に 強制 されます。

3つのキーと値のペアを、2つのキーと値のペアを含むオブジェクトに挿入します。

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

1つのキーと値のペアを省略しながら、2つの新しいキーと値のペアを空のオブジェクトに挿入します。

  • 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

既存のキーと値のペア("k1": 100)を新しい値("string-value")で更新します。

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

------------------------+
          OBJ           |
------------------------+
 {                      |
   "k1": "string-value" |
 }                      |
------------------------+
Copy