- カテゴリ：
半構造化データ関数と構造化データ関数 （配列/オブジェクトの作成および操作）
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 |
| } |
| ] |
+-----------------+