类别：

:doc:`/sql-reference/functions-semistructured`（数组/对象的创建和操作）

ARRAYS_ZIP

返回 对象 的一个 数组，每个对象都包含输入数组中第 n 个元素的键值对。例如，在返回的数组中，第一个对象包含输入数组中每个第一个元素的键值对，第二个对象包含输入数组中每个第二个元素的键值对，依此类推。

语法

ARRAYS_ZIP( <array> [ , <array> ... ] )

实参

array

输入数组。

输入数组的长度可以不同。

如果任何输入数组为 结构化数组，则所有输入数组都必须是结构化数组。

返回

返回以下类型之一的值：

  • 如果输入数组是半结构化数组，则该函数返回由结构化对象组成的半结构化数组。

  • 如果输入数组是结构化数组，则该函数返回由结构化对象组成的结构化数组。结构化对象的定义取决于输入数组的数量和数组中值的类型。

  • 如果任何输入数组为 NULL，则该函数返回 NULL。

每个对象都包含输入数组中第 n 个元素值的键值对。键（$1、$2 等）代表输入数组的位置。

例如，假设你传入了以下数组：

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  ['first', 'second', 'third'],
  ['i', 'ii', 'iii']
) AS zipped_arrays;

该函数返回以下对象数组：

+---------------------+
| ZIPPED_ARRAYS       |
|---------------------|
| [                   |
|   {                 |
|     "$1": 1,        |
|     "$2": "first",  |
|     "$3": "i"       |
|   },                |
|   {                 |
|     "$1": 2,        |
|     "$2": "second", |
|     "$3": "ii"      |
|   },                |
|   {                 |
|     "$1": 3,        |
|     "$2": "third",  |
|     "$3": "iii"     |
|   }                 |
| ]                   |
+---------------------+

在返回的数组中：

  • 第一个对象包含所有输入数组的第一个元素。

  • 第二个对象包含所有输入数组的第二个元素。

  • 第三个对象包含所有输入数组的第三个元素。

对象中的键标识输入数组：

  • $1 键值对包含来自第一个输入数组的值。

  • $2 键值对包含来自第二个输入数组的值。

  • $3 键值对包含来自第三个输入数组的值。

使用说明

  • 返回的数组与最长的输入数组一样长。如果某些输入数组较短，则该函数使用 JSON 空值 来表示较短数组中缺少的其余元素。

  • 如果输入数组包含一个 NULL 元素，则该函数为该元素返回一个 JSON 空值。

示例

以下示例演示了该函数的工作原理：

一个输入数组

以下示例返回一个对象数组，该数组包含单个数组中的第一、第二和第三个元素：

SELECT ARRAYS_ZIP(
  [1, 2, 3]
) AS zipped_array;

+--------------+
| ZIPPED_ARRAY |
|--------------|
| [            |
|   {          |
|     "$1": 1  |
|   },         |
|   {          |
|     "$1": 2  |
|   },         |
|   {          |
|     "$1": 3  |
|   }          |
| ]            |
+--------------+

多个输入数组

以下示例返回一个对象数组，该数组包含输入数组中的第一、第二和第三个元素：

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  [10, 20, 30],
  [100, 200, 300]
) AS zipped_array;

+---------------+
| ZIPPED_ARRAY  |
|---------------|
| [             |
|   {           |
|     "$1": 1,  |
|     "$2": 10, |
|     "$3": 100 |
|   },          |
|   {           |
|     "$1": 2,  |
|     "$2": 20, |
|     "$3": 200 |
|   },          |
|   {           |
|     "$1": 3,  |
|     "$2": 30, |
|     "$3": 300 |
|   }           |
| ]             |
+---------------+

不同长度的输入数组

以下示例传入了不同长度的输入数组。对于较短数组中不存在的值，该函数在对象中使用 JSON 空值。

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  ['one'],
  ['I', 'II']
) AS zipped_array;

+------------------+
| ZIPPED_ARRAY     |
|------------------|
| [                |
|   {              |
|     "$1": 1,     |
|     "$2": "one", |
|     "$3": "I"    |
|   },             |
|   {              |
|     "$1": 2,     |
|     "$2": null,  |
|     "$3": "II"   |
|   },             |
|   {              |
|     "$1": 3,     |
|     "$2": null,  |
|     "$3": null   |
|   }              |
| ]                |
+------------------+

NULL 和空数组处理

如下例所示，为任何输入数组传入一个 NULL 都将导致该函数返回一个 SQL NULL：

SELECT ARRAYS_ZIP(
  [1, 2, 3],
  NULL,
  [100, 200, 300]
) AS zipped_array;

+--------------+
| ZIPPED_ARRAY |
|--------------|
| NULL         |
+--------------+

在以下示例中，所有输入数组均为空，这导致该函数返回一个空对象：

SELECT ARRAYS_ZIP(
  [], [], []
) AS zipped_array;

+--------------+
| ZIPPED_ARRAY |
|--------------|
| [            |
|   {}         |
| ]            |
+--------------+

在以下示例中，输入数组中的一些元素为 NULL。在返回的对象中，这些元素的值为 JSON null：

SELECT ARRAYS_ZIP(
  [1, NULL, 3],
  [NULL, 20, NULL],
  [100, NULL, 300]
) AS zipped_array;

+-----------------+
| ZIPPED_ARRAY    |
|-----------------|
| [               |
|   {             |
|     "$1": 1,    |
|     "$2": null, |
|     "$3": 100   |
|   },            |
|   {             |
|     "$1": null, |
|     "$2": 20,   |
|     "$3": null  |
|   },            |
|   {             |
|     "$1": 3,    |
|     "$2": null, |
|     "$3": 300   |
|   }             |
| ]               |
+-----------------+