カテゴリ：

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

ARRAY_EXCEPT

別の入力 ARRAY にはない、ある入力 ARRAY の要素を含む新しい ARRAY を返します。

この関数は NULL-safeです。つまり、 NULLs を等値比較の既知の値として扱います。

こちらもご参照ください。

ARRAY_INTERSECTION

構文

ARRAY_EXCEPT( <source_array> , <array_of_elements_to_exclude> )

引数

source_array

新しい ARRAY に含める要素を含む配列。

array_of_elements_to_exclude

新しい ARRAY から除外する要素を含む配列。

戻り値

この関数は、 array_of_elements_to_exclude にない source_array の要素を含む ARRAY を返します。

source_array から array_of_elements_to_exclude の要素を除外した後に要素が残っていない場合、関数は空の ARRAY を返します。

1つまたは両方の引数が NULLの場合、関数は NULLを返します。

返される配列内の値の順序は指定されていません。

使用上の注意

  • 型 OBJECT のデータを比較する場合、一致していると見なされるには、オブジェクトが同一である必要があります。詳細については、 例 （このトピック内）をご参照ください。

  • Snowflakeでは、配列はセットではなくマルチセットです。つまり、配列には同じ値の複数のコピーを含めることができます。

    ARRAY_EXCEPT は、マルチセットセマンティクス（別称「バッグセマンティクス」）を使用して配列を比較します。 source_array に値の複数のコピーが含まれている場合、関数は array_of_elements_to_exclude で指定された数の値のコピーのみを削除します。

    つまり、 source_array に値のN個のコピーがあり、 array_of_elements_to_exclude に同じ値のM個のコピーがある場合、関数は返される配列から値のM個のコピーを除外します。返される配列内にある値のコピーの数はN - Mであり、MがNより大きい場合は0です。

    たとえば、 source_array に値 'A' を持つ5個の要素が含まれ、 array_of_elements_to_exclude に値 'A' を持つ2個の要素が含まれる場合、返される配列には、値 'A' を持つ3個の要素が含まれます。

  • 構造化 ARRAY を渡す場合:

    • 第2引数の ARRAY は、第1引数の ARRAY と 比較可能 である必要があります。

    • この関数は、第1引数の ARRAY と同じ型の構造化 ARRAY を返します。

例

このセクションの例では、 ARRAY 定数 と OBJECT 定数 を使用して ARRAYs と OBJECTs を指定しています。

次の例では、関数の使用方法を示しています。

SELECT ARRAY_EXCEPT(['A', 'B'], ['B', 'C']);

+--------------------------------------+
| ARRAY_EXCEPT(['A', 'B'], ['B', 'C']) |
|--------------------------------------|
| [                                    |
|   "A"                                |
| ]                                    |
+--------------------------------------+

次の例では、要素 'C' を source_array に追加します。 'C' は array_of_elements_to_exclude にも指定されているため、返された ARRAY には 'C' が含まれていません。

SELECT ARRAY_EXCEPT(['A', 'B', 'C'], ['B', 'C']);

+-------------------------------------------+
| ARRAY_EXCEPT(['A', 'B', 'C'], ['B', 'C']) |
|-------------------------------------------|
| [                                         |
|   "A"                                     |
| ]                                         |
+-------------------------------------------+

次の例では、 source_array に値 'B' を持つ3個の要素が含まれています。 array_of_elements_to_exclude には1個の 'B' 要素しか含まれていないため、関数は1個の 'B' 要素のみを除外し、他の2個の 'B' 要素を含む ARRAY を返します。

SELECT ARRAY_EXCEPT(['A', 'B', 'B', 'B', 'C'], ['B']);

+------------------------------------------------+
| ARRAY_EXCEPT(['A', 'B', 'B', 'B', 'C'], ['B']) |
|------------------------------------------------|
| [                                              |
|   "A",                                         |
|   "B",                                         |
|   "B",                                         |
|   "C"                                          |
| ]                                              |
+------------------------------------------------+

次の例では、 source_array から array_of_elements_to_exclude 内の要素を除外すると、要素が残りません。結果として、関数は空の ARRAY を返します。

SELECT ARRAY_EXCEPT(['A', 'B'], ['A', 'B']);

+--------------------------------------+
| ARRAY_EXCEPT(['A', 'B'], ['A', 'B']) |
|--------------------------------------|
| []                                   |
+--------------------------------------+

次の例は、関数が NULL 要素を既知の値として扱う方法を示しています。前述のように、 source_array には array_of_elements_to_exclude よりも NULL 要素が1個多いため、返された ARRAY では NULL 要素が1個だけ除外され、他は含まれます（これは undefined として出力されます）。

SELECT ARRAY_EXCEPT(['A', NULL, NULL], ['B', NULL]);

+----------------------------------------------+
| ARRAY_EXCEPT(['A', NULL, NULL], ['B', NULL]) |
|----------------------------------------------|
| [                                            |
|   "A",                                       |
|   undefined                                  |
| ]                                            |
+----------------------------------------------+

次の例では、 source_array と array_of_elements_to_exclude に同じ数の NULL 要素が含まれているため、返される ARRAY から NULL 要素が除外されます。

SELECT ARRAY_EXCEPT(['A', NULL, NULL], [NULL, 'B', NULL]);

+----------------------------------------------------+
| ARRAY_EXCEPT(['A', NULL, NULL], [NULL, 'B', NULL]) |
|----------------------------------------------------|
| [                                                  |
|   "A"                                              |
| ]                                                  |
+----------------------------------------------------+

次の例は、 source_array と array_of_elements_to_exclude で同じオブジェクトを指定すると、返される ARRAY からそのオブジェクトが除外されることを示しています。

SELECT ARRAY_EXCEPT([{'a': 1, 'b': 2}, 1], [{'a': 1, 'b': 2}, 3]);

+------------------------------------------------------------+
| ARRAY_EXCEPT([{'A': 1, 'B': 2}, 1], [{'A': 1, 'B': 2}, 3]) |
|------------------------------------------------------------|
| [                                                          |
|   1                                                        |
| ]                                                          |
+------------------------------------------------------------+

次の例は、 NULL を渡すと関数が NULL を返すことを示しています。

SELECT ARRAY_EXCEPT(['A', 'B'], NULL);

+--------------------------------+
| ARRAY_EXCEPT(['A', 'B'], NULL) |
|--------------------------------|
| NULL                           |
+--------------------------------+