结构化数据类型¶

指定结构化 ARRAY 类型¶

若要指定结构化 ARRAY 类型，请使用以下语法：

ARRAY( <element_type> [ NOT NULL ] )

其中：

• element_type 是此 ARRAY 中元素的 Snowflake 数据类型。

  您还可以指定结构的 ARRAY、结构化 OBJECT 或 MAP 作为元素的类型。

  备注

  在 Iceberg 表列的定义中，不能指定 VARIANT、半结构化 ARRAY 或半结构化 OBJECT 作为 ARRAY 元素类型。

• NOT NULL 指定 ARRAY 中不能包含任何的 NULL 元素。

例如，在以下语句中比较 SYSTEM$TYPEOF 函数返回的类型：

• 第一列的表达式将半结构化 ARRAY 值转换为结构化 ARRAY 值（NUMBER 元素的 ARRAY）。

• 第二列表达式指定半结构化 ARRAY 值。

SELECT
  SYSTEM$TYPEOF(
    [1, 2, 3]::ARRAY(NUMBER)
  ) AS structured_array,
  SYSTEM$TYPEOF(
    [1, 2, 3]
  ) AS semi_structured_array;

+-------------------------------+-----------------------+
| STRUCTURED_ARRAY              | SEMI_STRUCTURED_ARRAY |
|-------------------------------+-----------------------|
| ARRAY(NUMBER(38,0))[LOB]      | ARRAY[LOB]            |
+-------------------------------+-----------------------+

指定结构化 OBJECT 类型¶

若要指定结构化 OBJECT 类型，请使用以下语法：

OBJECT(
  [
    <key> <value_type> [ NOT NULL ]
    [ , <key> <value_type> [ NOT NULL ] ]
    [ , ... ]
  ]
)

其中：

• key 指定 OBJECT 类型的键。

  • OBJECT 定义中的每个 key 都必须是唯一的。

  • 键的顺序是 OBJECT 定义的一部分。不允许以不同顺序比较具有相同键的两个 OBJECT 值。（发生编译时错误。）

  • 如果不指定任何键，但指定括号（即，如果使用 OBJECT()），生成的类型则是不包含键的结构化 OBJECT。没有键的结构化 OBJECT 与半结构化 OBJECT 不同。

• value_type 是键所对应值的 Snowflake 数据类型。

  您还可以指定结构化 ARRAY、结构化 OBJECT 或 MAP 作为值的类型。

  备注

  在 Iceberg 表列的定义中，不能指定 VARIANT、半结构化 ARRAY 或半结构化 OBJECT 作为与 OBJECT 键对应的值的类型。

• NOT NULL 指定与键对应的值不能为 NULL。

例如，在以下语句中比较 SYSTEM$TYPEOF 函数返回的类型：

• 第一列表达式将半结构化 OBJECT 值转换为包含以下键和值的结构化 OBJECT 值：

  • 名为 str 的键，且附带非 NULL 的 VARCHAR 值。

  • 名为 num 的键，且附带 NUMBER 值。

• 第二列表达式指定半结构化 OBJECT 值。

SELECT
  SYSTEM$TYPEOF(
    {
      'str': 'test',
      'num': 1
    }::OBJECT(
      str VARCHAR NOT NULL,
      num NUMBER
    )
  ) AS structured_object,
  SYSTEM$TYPEOF(
    {
      'str': 'test',
      'num': 1
    }
  ) AS semi_structured_object;

+---------------------------------------------------------------+------------------------+
| STRUCTURED_OBJECT                                             | SEMI_STRUCTURED_OBJECT |
|---------------------------------------------------------------+------------------------|
| OBJECT(str VARCHAR(16777216) NOT NULL, num NUMBER(38,0))[LOB] | OBJECT[LOB]            |
+---------------------------------------------------------------+------------------------+

指定 MAP 类型¶

若要指定 MAP 类型，请使用以下语法：

MAP( <key_type> , <value_type> [ NOT NULL ] )

其中：

• key_type 是用于映射的键的 Snowflake 数据类型。您必须为键使用以下类型之一：

  • VARCHAR

  • （NUMBER 标度为 0）

  不能使用浮点数据类型作为键的类型。

  映射键不能是 NULL。

• value_type 是映射中值的 Snowflake 数据类型。

  您还可以指定结构化 ARRAY、结构化 OBJECT 或 MAP 作为值的类型。

  备注

  在 Iceberg 表列的定义中，不能指定 VARIANT、半结构化 ARRAY 或半结构化 OBJECT 作为 MAP 中值的类型。

• NOT NULL 指定与键对应的值不能为 NULL。

下面的示例将半结构化 OBJECT 值转换为 MAP 值，并使用 SYSTEM$TYPEOF 函数打印值的结果类型。MAP 将 VARCHAR 键与 VARCHAR 值关联起来。

SELECT
  SYSTEM$TYPEOF(
    {
      'a_key': 'a_val',
      'b_key': 'b_val'
    }::MAP(VARCHAR, VARCHAR)
  ) AS map_example;

+------------------------------------------------+
| MAP_EXAMPLE                                    |
|------------------------------------------------|
| MAP(VARCHAR(16777216), VARCHAR(16777216))[LOB] |
+------------------------------------------------+

将半结构化类型显式转换为结构化类型¶

要将半结构化类型的值显式转换为结构化类型的值，您可以 调用 CAST 函数或使用 :: 运算符。

您只能将以下半结构化类型的值转换为相应的结构化类型的值；否则，将发生运行时错误。

接下来的部分将更详细地说明如何转换类型：

• 将半结构化 ARRAY 和 VARIANT 值转换为结构化 ARRAY 值

• 将半结构化 OBJECT 和 VARIANT 值转换为结构化 OBJECT 值

• 将半结构化 OBJECT 和 VARIANT 值转换为 MAP 值

SELECT
  SYSTEM$TYPEOF(
    CAST ([1,2,3] AS ARRAY(NUMBER))
  ) AS array_cast_type,
  SYSTEM$TYPEOF(
    CAST ([1,2,3]::VARIANT AS ARRAY(NUMBER))
  ) AS variant_cast_type;

SELECT
  SYSTEM$TYPEOF(
    [1,2,3]::ARRAY(NUMBER)
  ) AS array_cast_type,
  SYSTEM$TYPEOF(
    [1,2,3]::VARIANT::ARRAY(NUMBER)
  ) AS variant_cast_type;

+--------------------------+--------------------------+
| ARRAY_CAST_TYPE          | VARIANT_CAST_TYPE        |
|--------------------------+--------------------------|
| ARRAY(NUMBER(38,0))[LOB] | ARRAY(NUMBER(38,0))[LOB] |
+--------------------------+--------------------------+

SELECT
  SYSTEM$TYPEOF(
    CAST ({'city':'San Mateo','state':'CA'} AS OBJECT(city VARCHAR, state VARCHAR))
  ) AS object_cast_type,
  SYSTEM$TYPEOF(
    CAST ({'city':'San Mateo','state':'CA'}::VARIANT AS OBJECT(city VARCHAR, state VARCHAR))
  ) AS variant_cast_type;

SELECT
  SYSTEM$TYPEOF(
     {'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  ) AS object_cast_type,
  SYSTEM$TYPEOF(
     {'city':'San Mateo','state':'CA'}::VARIANT::OBJECT(city VARCHAR, state VARCHAR)
  ) AS variant_cast_type;

+--------------------------------------------------------------+--------------------------------------------------------------+
| OBJECT_CAST_TYPE                                             | VARIANT_CAST_TYPE                                            |
|--------------------------------------------------------------+--------------------------------------------------------------|
| OBJECT(city VARCHAR(16777216), state VARCHAR(16777216))[LOB] | OBJECT(city VARCHAR(16777216), state VARCHAR(16777216))[LOB] |
+--------------------------------------------------------------+--------------------------------------------------------------+

SELECT
  SYSTEM$TYPEOF(
    CAST ({'my_key':'my_value'} AS MAP(VARCHAR, VARCHAR))
  ) AS map_cast_type,
  SYSTEM$TYPEOF(
    CAST ({'my_key':'my_value'} AS MAP(VARCHAR, VARCHAR))
  ) AS variant_cast_type;

SELECT
  SYSTEM$TYPEOF(
    {'my_key':'my_value'}::MAP(VARCHAR, VARCHAR)
  ) AS map_cast_type,
  SYSTEM$TYPEOF(
    {'my_key':'my_value'}::VARIANT::MAP(VARCHAR, VARCHAR)
  ) AS variant_cast_type;

+------------------------------------------------+------------------------------------------------+
| MAP_CAST_TYPE                                  | VARIANT_CAST_TYPE                              |
|------------------------------------------------+------------------------------------------------|
| MAP(VARCHAR(16777216), VARCHAR(16777216))[LOB] | MAP(VARCHAR(16777216), VARCHAR(16777216))[LOB] |
+------------------------------------------------+------------------------------------------------+

将结构化类型显式转换为半结构化类型¶

若要将结构化类型的值显式转换为半结构化类型的值，可以 调用 CAST 函数，使用 :: 运算符，或调用其中一个转换函数（例如 TO_ARRAY、TO_OBJECT 或 TO_VARIANT）。

例如：

• 如果 col_structured_array 为 ARRAY(VARCHAR) 类型：

  • CAST(col_structured_array AS ARRAY) 会返回半结构化 ARRAY 值。

  • CAST(col_structured_array AS VARIANT) 会返回包含半结构化 ARRAY 值的 VARIANT 值。

• 如果 col_structured_object 为 OBJECT(name VARCHAR, state VARCHAR) 类型：

  • CAST(col_structured_object AS OBJECT) 会返回半结构化 OBJECT 值。

  • CAST(col_structured_object AS VARIANT) 会返回包含半结构化 OBJECT 值的 VARIANT 值。

• 如果 col_map 为 MAP(VARCHAR, VARCHAR) 类型：

  • CAST(col_map AS OBJECT) 会返回半结构化 OBJECT 值。

  • CAST(col_map AS VARIANT) 会返回包含半结构化 OBJECT 值的 VARIANT 值。

请注意以下事项：

• 转换为半结构化 OBJECT 值时，不会保留结构化 OBJECT 值中的键顺序。

• 将结构化 OBJECT 或 MAP 值转换为半结构化 OBJECT 或 VARIANT 值时，任何 NULL 值都将转换为 JSON 空值。

  如果将结构化 ARRAY 值转换为 VARIANT 值，则 NULL 值将按原样保留。

  SELECT [1,2,NULL,3]::ARRAY(INTEGER)::VARIANT;
  

  Copy

  +---------------------------------------+
  | [1,2,NULL,3]::ARRAY(INTEGER)::VARIANT |
  |---------------------------------------|
  | [                                     |
  |   1,                                  |
  |   2,                                  |
  |   undefined,                          |
  |   3                                   |
  | ]                                     |
  +---------------------------------------+
  

• 如果您要转换使用 NUMBER 键类型的 MAP 值，则 MAP 键将转换为返回的 OBJECT 值中的字符串。

隐式转换值（强制）¶

以下规则适用于从一种结构化类型的值 隐式转换（强制） 为另一种结构化类型的值：

• 如果两个基本对象类型相同，则可以将一个结构化类型值强制转换为另一个结构化类型值：

  • 一种类型的 ARRAY 值可以强制转换为另一种类型的 ARRAY 值，前提是第一种元素类型可强制转换为第二种元素类型。

    在以下任一情况下，一种元素类型可以强制转换为另一种元素类型：

    • 两种类型都是数值。支持以下情况：

      • 两者都使用相同的数值类型，但在精度和/或标度上可能有所不同。

      • 将 NUMBER 强制转换为 FLOAT （反之亦然）。

    • 两种类型都是时间戳。支持以下情况：

      • 两者都使用相同的类型，但精度可能不同。

      • 将 TIMESTAMP_LTZ 强制转换为 TIMESTAMP_TZ （反之亦然）。

    例如：

    • ARRAY(NUMBER) 值可以强制转换为 ARRAY(DOUBLE) 值。

    • ARRAY(DATE) 值不能强制转换为 ARRAY(NUMBER) 值。

  • 仅当满足以下所有条件时，具有一种类型定义的 OBJECT 值才能强制转换为具有另一种类型定义的 OBJECT 值：

    • 两种 OBJECT 类型具有相同数量的键。

    • 两种 OBJECT 类型为键使用相同的名称。

    • 两种 OBJECT 类型中的键的顺序相同。

    • 一种 OBJECT 类型中每个值的类型可以强制转换为另一种 OBJECT 类型中相应值的类型。

      与结构化 ARRAY 值中的元素类型一样，只有在以下情况下，才能将一个值的类型强制转换为另一种类型：

      • 两种类型都是数值。支持以下情况：

        • 两者都使用相同的数值类型，但在精度和/或标度上可能有所不同。

        • 将 NUMBER 强制转换为 FLOAT （反之亦然）。

      • 两种类型都是时间戳。支持以下情况：

        • 两者都使用相同的类型，但精度可能不同。

        • 将 TIMESTAMP_LTZ 强制转换为 TIMESTAMP_TZ （反之亦然）。

    例如：

    • OBJECT(city VARCHAR, zipcode NUMBER) 值可以强制转换为 OBJECT(city VARCHAR, zipcode DOUBLE) 值。

    • OBJECT(city VARCHAR, zipcode NUMBER) 值不能强制转换为 OBJECT(city VARCHAR, zipcode DATE) 值。

  • 在以下情况下，具有一种值类型的 MAP 值可以强制转换为具有不同值类型的 MAP 值：

    • 两种值类型都是数值。支持以下情况：

      • 两者都使用相同的数值类型，但在精度和/或标度上可能有所不同。

      • 将 NUMBER 强制转换为 FLOAT （反之亦然）。

    • 两种值类型都是时间戳。支持以下情况：

      • 两者都使用相同的类型，但精度可能不同。

      • 将 TIMESTAMP_LTZ 强制转换为 TIMESTAMP_TZ （反之亦然）。

    例如，MAP（VARCHAR，NUMBER）值可以强制转换为 MAP（VARCHAR，DOUBLE）值。

  • 如果两种键类型都使用只有精度不同的相同整数 NUMERIC 类型，则可以将具有一种键类型的 MAP 值强制转换为不同键类型的 MAP 值。

    例如，MAP(VARCHAR, NUMBER) 值不能强制转换为 MAP(NUMBER, NUMBER) 值。

• 结构化类型值不能强制转换为半结构化值（反之亦然）。

• VARCHAR 值不能强制转换为结构化类型值。

从一种结构化类型转换为另一种结构化类型¶

您可以 调用 CAST 函数或使用 :: 运算符 从一个结构化类型的值转换为另一个结构化类型的值。您可以在以下结构化类型之间转换值：

• 对于结构化 ARRAYs：

  您可以将一个类型的 ARRAY 值转换为另一个类型的 ARRAY 值。

• 对于结构化 OBJECTs：

  • 您可以在 OBJECT 值中使用转换来 更改键值对顺序。

  • 您可以在 OBJECT 值中使用转换来 更改键名称。

  • 您可以使用转换向 OBJECT 值 添加键。

  • 您可以将结构化 OBJECT 值转换为 MAP 值。

• 对于 MAP 值：

  • 您可以将具有特定类型键和值的 MAP 值转换为具有不同类型键和值的 MAP 值。

  • 您可以将 MAP 值转换为结构化 OBJECT 值。

如果无法将值从一种类型转换为另一种类型，则转换失败。例如，尝试将 ARRAY(BOOLEAN) 值转换为 ARRAY(DATE) 值失败。

SELECT CAST(
  CAST([1,2,3] AS ARRAY(NUMBER))
  AS ARRAY(VARCHAR)) AS cast_array;

+------------+
| CAST_ARRAY |
|------------|
| [          |
|   "1",     |
|   "2",     |
|   "3"      |
| ]          |
+------------+

SELECT CAST(
  {'city': 'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(state VARCHAR, city VARCHAR)) AS object_value_order;

+-----------------------+
| OBJECT_VALUE_ORDER    |
|-----------------------|
| {                     |
|   "state": "CA",      |
|   "city": "San Mateo" |
| }                     |
+-----------------------+

SELECT CAST({'city':'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(city_name VARCHAR, state_name VARCHAR) RENAME FIELDS) AS object_value_key_names;

+-----------------------------+
| OBJECT_VALUE_KEY_NAMES      |
|-----------------------------|
| {                           |
|   "city_name": "San Mateo", |
|   "state_name": "CA"        |
| }                           |
+-----------------------------+

SELECT CAST({'city':'San Mateo','state': 'CA'}::OBJECT(city VARCHAR, state VARCHAR)
  AS OBJECT(city VARCHAR, state VARCHAR, zipcode NUMBER) ADD FIELDS) AS add_fields;

+------------------------+
| ADD_FIELDS             |
|------------------------|
| {                      |
|   "city": "San Mateo", |
|   "state": "CA",       |
|   "zipcode": null      |
| }                      |
+------------------------+

使用 SQL 函数构造结构化 ARRAY 和 OBJECT 值¶

以下函数构造半结构化 ARRAY 值：

• ARRAY_CONSTRUCT

• ARRAY_CONSTRUCT_COMPACT

• ARRAY_AGG

• TO_ARRAY

以下函数构造半结构化 OBJECT 值：

• OBJECT_CONSTRUCT

• OBJECT_CONSTRUCT_KEEP_NULL

• OBJECT_AGG

• TO_OBJECT

若要构造结构化 ARRAY 或 OBJECT 值，请使用这些函数并显式转换函数的返回值。例如：

SELECT ARRAY_CONSTRUCT(10, 20, 30)::ARRAY(NUMBER);

SELECT OBJECT_CONSTRUCT(
  'oname', 'abc',
  'created_date', '2020-01-18'::DATE
)::OBJECT(
  oname VARCHAR,
  created_date DATE
);

有关详细信息，请参阅 将半结构化类型显式转换为结构化类型。

使用 ARRAY 和 OBJECT 常量构造结构化 ARRAY 和 OBJECT 值¶

当您指定 ARRAY 常量 或 OBJECT 常量 时，您指定的是半结构化 ARRAY 或 OBJECT 值。

要构造结构化 ARRAY 或 OBJECT 值，必须显式转换表达式。例如：

SELECT [10, 20, 30]::ARRAY(NUMBER);

SELECT {
  'oname': 'abc',
  'created_date': '2020-01-18'::DATE
}::OBJECT(
  oname VARCHAR,
  created_date DATE
);

有关详细信息，请参阅 将半结构化类型显式转换为结构化类型。

构造 MAP 值¶

要构造 MAP 值，请构造半结构化 OBJECT 值，并将 OBJECT 值转换为 MAP 值。

例如，以下语句均生成 MAP 值 {'city'->'San Mateo','state'->'CA'}：

SELECT OBJECT_CONSTRUCT(
  'city', 'San Mateo',
  'state', 'CA'
)::MAP(
  VARCHAR,
  VARCHAR
);

SELECT {
  'city': 'San Mateo',
  'state': 'CA'
}::MAP(
  VARCHAR,
  VARCHAR
);

以下语句生成 MAP 值 {-10->'CA',-20->'OR'}：

SELECT {
  '-10': 'CA',
  '-20': 'OR'
}::MAP(
  NUMBER,
  VARCHAR
);

有关详细信息，请参阅 将半结构化 OBJECT 和 VARIANT 值转换为 MAP 值。

从结构化 OBJECT 值中获取键列表¶

要获取结构化 OBJECT 值中的键列表，请调用 OBJECT_KEYS 函数：

SELECT OBJECT_KEYS({'city':'San Mateo','state':'CA'}::OBJECT(city VARCHAR, state VARCHAR));

如果输入是结构化 OBJECT 值，则函数返回包含键的 ARRAY(VARCHAR) 值。如果输入是半结构化 OBJECT 值，则函数返回 ARRAY 值。

获取 MAP 值中的键列表¶

要获取 MAP 值中的键列表，请调用 MAP_KEYS 函数：

SELECT MAP_KEYS({'my_key':'my_value'}::MAP(VARCHAR,VARCHAR));

访问结构化类型值中的值和元素¶

您可以使用以下方法访问结构化 ARRAY、结构化 OBJECT 和 MAP 值中的值和元素：

• GET 函数

• GET_IGNORE_CASE 函数

• GET_PATH 函数

• 点表示法

• 括号表示法

返回的值和元素具有为结构化值指定的类型，而不是 VARIANT。

下面的示例将半结构化 ARRAY 值的第一个元素和 ARRAY(VARCHAR) 值传递给 SYSTEM$TYPEOF 函数，以返回该元素的数据类型：

SELECT
  SYSTEM$TYPEOF(
    ARRAY_CONSTRUCT('San Mateo')[0]
  ) AS semi_structured_array_element,
  SYSTEM$TYPEOF(
    CAST(
      ARRAY_CONSTRUCT('San Mateo') AS ARRAY(VARCHAR)
    )[0]
  ) AS structured_array_element;

+-------------------------------+-----------------------------+
| SEMI_STRUCTURED_ARRAY_ELEMENT | STRUCTURED_ARRAY_ELEMENT    |
|-------------------------------+-----------------------------|
| VARIANT[LOB]                  | VARCHAR(16777216)[LOB]      |
+-------------------------------+-----------------------------+

请注意以下事项：

• 将结构化 OBJECT 值传递给 GET 或 GET_IGNORE_CASE 函数时，必须为键指定常量。

  如果要将 MAP 或结构化 ARRAY 值传递给 GET 函数，则无需指定常量。

  如果要将 MAP 值传递给 GET_IGNORE_CASE 函数，也不需要指定常量。

• 将结构化 OBJECT、结构化 ARRAY 或 MAP 值传递给 GET_PATH 函数时，必须为路径名指定一个常量。

• 对于结构化 OBJECT 值，如果使用不存在的 OBJECT 键或路径，则会发生编译时错误。

  相反，当您在半结构化 OBJECT 值中使用不存在的索引、键或路径时，该函数将返回 NULL。

确定结构化 ARRAY 值的大小¶

要确定结构化 ARRAY 值的大小，请将 ARRAY 值传递给 ARRAY_SIZE 函数：

SELECT ARRAY_SIZE([1,2,3]::ARRAY(NUMBER));

确定 MAP 值的大小¶

要确定 MAP 值的大小，请将 MAP 值传递给 MAP_SIZE 函数：

SELECT MAP_SIZE({'my_key':'my_value'}::MAP(VARCHAR,VARCHAR));

在结构化 ARRAY 值中查找元素¶

要确定结构化 ARRAY 值中是否存在元素，请调用 ARRAY_CONTAINS 函数。例如：

SELECT ARRAY_CONTAINS(10, [1, 10, 100]::ARRAY(NUMBER));

要确定元素在结构化 ARRAY 值中的位置，请调用 ARRAY_POSITION 函数。例如：

SELECT ARRAY_POSITION(10, [1, 10, 100]::ARRAY(NUMBER));

确定 MAP 值是否包含键¶

若要确定 MAP 值是否包含键，请调用 MAP_CONTAINS_KEY 函数：

例如：

SELECT MAP_CONTAINS_KEY('key_to_find', my_map);

SELECT MAP_CONTAINS_KEY(10, my_map);

将结构化值与半结构化值进行比较¶

不能将结构化 ARRAY、结构化 OBJECT 或 MAP 值与半结构化 ARRAY、OBJECT 或 VARIANT 值进行比较。

将结构化值与其他结构化值进行比较¶

可以比较两个相同类型的值（例如，两个结构化 ARRAY 值、两个结构化 OBJECT 值或两个 MAP 值）。

目前，支持使用以下比较运算符来比较结构化类型值：

• =

• !=

• <

• <=

• >=

• >

比较两个结构化值是否相等时，请注意以下事项：

• 如果一种类型不能 强制转换 为另一种类型，则比较失败。

• 当您比较具有数字键的 MAP 值时，这些键将作为数字（而不是 VARCHAR 值）进行比较。

使用 <, <=, >=, or > 比较两个结构化值时，将按字母顺序比较结构化值字段。例如，以下值：

{'a':2,'b':1}::OBJECT(b INTEGER,a INTEGER)

大于：

{'a':1,'b':2}::OBJECT(b INTEGER,a INTEGER)

确定两个 ARRAY 值是否重叠¶

如果需要确定两个结构化的 ARRAY 值元素是否重叠，请调用 ARRAYS_OVERLAP 函数。例如：

SELECT ARRAYS_OVERLAP(numeric_array, other_numeric_array);

ARRAY 值必须属于 同类的类型。

不能将半结构化 ARRAY 值和结构化 ARRAY 值传递给此函数。两个 ARRAY 值必须同时是结构化的或半结构化的。

转换结构化 ARRAY 值¶

当将结构化 ARRAY 值传递给这些函数时，这些函数将返回相同类型的结构化 ARRAY 值：

• ARRAY_APPEND

• ARRAY_CAT

• ARRAY_COMPACT

• ARRAY_EXCEPT

• ARRAY_INSERT

• ARRAY_INTERSECTION

• ARRAY_PREPEND

• ARRAY_SLICE

• ARRAY_UNION_AGG

接下来的部分将介绍这些函数如何处理结构化 ARRAY 值。

• 将元素添加到 ARRAY 值的函数

• 可接受多个 ARRAY 值作为输入的函数

SELECT ARRAY_APPEND( [1,2]::ARRAY(DOUBLE), 3::NUMBER );

SELECT ARRAY_APPEND( [1,2]::ARRAY(DOUBLE), '3' );

SELECT ARRAY_APPEND( [1,2]::ARRAY(NUMBER), '2022-02-02'::DATE );

SELECT ARRAY_CAT( [1,2]::ARRAY(NUMBER), ['3','4'] );

SELECT ARRAY_CAT( [1,2], ['3','4']::ARRAY(VARCHAR) );

SELECT
  ARRAY_CAT(
    [1, 2, 3]::ARRAY(NUMBER NOT NULL),
    [5.5, NULL]::ARRAY(NUMBER(2, 1))
  ) AS concatenated_array,
  SYSTEM$TYPEOF(concatenated_array);

+--------------------+-----------------------------------+
| CONCATENATED_ARRAY | SYSTEM$TYPEOF(CONCATENATED_ARRAY) |
|--------------------+-----------------------------------|
| [                  | ARRAY(NUMBER(38,1))[LOB]          |
|   1,               |                                   |
|   2,               |                                   |
|   3,               |                                   |
|   5.5,             |                                   |
|   undefined        |                                   |
| ]                  |                                   |
+--------------------+-----------------------------------+

SELECT ARRAY_EXCEPT( [1,2]::ARRAY(NUMBER), [2,3]::ARRAY(DOUBLE) );

SELECT ARRAY_EXCEPT( [1,2]::ARRAY(NUMBER), ['2','3']::ARRAY(VARCHAR) );

转换结构化 OBJECT 值¶

以下部分说明如何返回已从另一个结构化 OBJECT 值转换而来的结构化 OBJECT 值：

• 移除键值对

• 插入键值对并更新值

• 从现有 OBJECT 中选择键值对

若要更改键值对的顺序、重命名键或在不指定值的情况下添加键，请使用 CAST 函数或 :: 运算符。有关详细信息，请参阅 从一种结构化类型转换为另一种结构化类型。

转换 MAP 值¶

要转换 MAP 值，请使用以下函数：

• MAP_CAT

• MAP_DELETE

• MAP_INSERT

• MAP_PICK

将 FLATTEN 函数用于结构化类型的值¶

您可以将结构化 ARRAY、结构化 OBJECT 和 MAP 值传递给 FLATTEN 函数。与半结构化数据类型一样，您可以使用 PATH 实参来指定要展平的值。

• 如果要展平的值是结构化 ARRAY 值，并且 RECURSIVE 实参为 FALSE，则 value 列包含与 ARRAY 值相同的类型值。

  例如：

  SELECT value, SYSTEM$TYPEOF(value)
    FROM TABLE(FLATTEN(INPUT => [1.08, 2.13, 3.14]::ARRAY(DOUBLE)));
  

  Copy

  +-------+----------------------+
  | VALUE | SYSTEM$TYPEOF(VALUE) |
  |-------+----------------------|
  |  1.08 | FLOAT[DOUBLE]        |
  |  2.13 | FLOAT[DOUBLE]        |
  |  3.14 | FLOAT[DOUBLE]        |
  +-------+----------------------+
  

• 如果要展平的值为 MAP 值，RECURSIVE 实参为 FALSE，则 key 列包含与 MAP 键类型相同的键，并且 value 列包含与 MAP 值类型相同的值。

  例如：

  SELECT key, SYSTEM$TYPEOF(key), value, SYSTEM$TYPEOF(value)
    FROM TABLE(FLATTEN(INPUT => {'my_key': 'my_value'}::MAP(VARCHAR, VARCHAR)));
  

  Copy

  +--------+------------------------+----------+------------------------+
  | KEY    | SYSTEM$TYPEOF(KEY)     | VALUE    | SYSTEM$TYPEOF(VALUE)   |
  |--------+------------------------+----------+------------------------|
  | my_key | VARCHAR(16777216)[LOB] | my_value | VARCHAR(16777216)[LOB] |
  +--------+------------------------+----------+------------------------+
  

• 否则，key 和 value 列的类型为 VARIANT。

对于 MAP 值，返回的键和值的顺序是不确定的。

使用 PARSE_JSON 函数¶

PARSE_JSON 函数不返回结构化类型。

将结构化类型与集合运算符和 CASE 表达式一起使用¶

您可以在以下表达式中使用结构化 ARRAY、结构化 OBJECT 和 MAP 值：

• 由集合运算符组合而成的查询表达式（例如 UNION ALL）。

• CASE 表达式。

对于集运算符，如果在不同的表达式中使用不同的类型（例如，如果一种类型是 ARRAY(NUMBER)，另一种类型是 ARRAY(DOUBLE)），则一种类型将 强制转换 为另一种类型。

处理其他半结构化函数¶

以下函数不接受结构化 ARRAY、结构化 OBJECT 或 MAP 值作为输入实参：

• AS_ARRAY

• AS_OBJECT

• IS_ARRAY

• IS_OBJECT

• TYPEOF

将结构化类型值作为输入传递会导致错误。

使用 SHOW COLUMNS 命令查看结构化类型信息¶

在 SHOW COLUMNS 命令的输出中，data_type 列包含有关元素、键和值类型的信息。

使用 DESCRIBE 和其他 SHOW 命令查看结构化类型信息¶

以下命令的输出包括有关结构化类型的信息：

• DESCRIBE TABLE

• DESCRIBE RESULT

• DESCRIBE FUNCTION

• DESCRIBE PROCEDURE

• SHOW FUNCTIONS

• SHOW PROCEDURES

例如，在 DESCRIBE RESULT 输出中，MAP （VARCHAR、VARCHAR）列的行包含 type 列中的以下值：

map(VARCHAR(16777216), VARCHAR(16777216))

ARRAY(NUMBER) 列的行包含 type 列中的以下值：

ARRAY(NUMBER(38,0))

查看有关数据库中使用的结构化类型的信息¶

对于结构化类型的列，INFORMATION_SCHEMA COLUMNS 视图 仅提供与列的基本数据类型（ARRAY、OBJECT 或 MAP）有关的信息。

例如，data_type 列仅包含 ARRAY、OBJECT 或 MAP。该列不包括元素、键或值的类型。

要查看有关元素、键和值类型的信息，请使用以下视图：

• 有关结构化 ARRAY 类型中的元素类型的信息，请查询 INFORMATION_SCHEMA 中的 ELEMENT_TYPES 视图 或 ACCOUNT_USAGE 中的 ELEMENT_TYPES 视图。

• 有关结构化 OBJECT 和 MAP 类型中的键和值的信息，请查询 INFORMATION_SCHEMA 中的 FIELDS 视图 或 ACCOUNT_USAGE 中的 FIELDS 视图。