カテゴリ：

半構造化データ関数と構造化データ関数 （配列/オブジェクトの作成および操作）

ARRAYS_ZIP

オブジェクト の 配列 を返します。各オブジェクトには、入力配列のn番目の要素のキーと値のペアが含まれます。例えば、返された配列の中で、最初のオブジェクトは入力配列の1番目の要素ごとのキーと値のペアを含み、2番目のオブジェクトは入力配列の2番目の要素ごとのキーと値のペアを含む、などです。

構文

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番目のオブジェクトには、すべての入力配列の2番目の要素が含まれます。

  • 3番目のオブジェクトには、すべての入力配列の3番目の要素が含まれます。

オブジェクトのキーは入力配列を識別します。

  • $1 キーと値のペアには、1番目の入力配列の値が含まれます。

  • $2 キーと値のペアには、2番目の入力配列の値が含まれます。

  • $3 キーと値のペアには、3番目の入力配列の値が含まれます。

使用上の注意

  • 返される配列は、最も長い入力配列と同じ長さです。入力配列の一部が短い場合、この関数は、短い配列で欠落している残りの要素に対して JSON null を使用します。

  • 入力配列に NULL 要素が含まれている場合、関数はその要素に対して JSON nullを返します。

例

以下の例は、この機能の仕組みを示しています。

単一の入力配列

次の例は、1つの配列に1番目、2番目、3番目の要素を含むオブジェクトの配列を返します。

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

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

複数の入力配列

次の例は、入力配列に1番目、2番目、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 NULLを使用します。

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   |
|   }             |
| ]               |
+-----------------+