Catégories :

Fonctions de données semi-structurées et structurées (tableau/objet)

ARRAY_EXCEPT

Renvoie un nouveau ARRAY qui contient les éléments d’un ARRAY d’entrée qui ne sont pas dans un autre ARRAY d’entrée.

La fonction est NULL-safe, ce qui signifie qu’elle considère les NULLs comme des valeurs connues permettant de comparer l’égalité.

Voir aussi :

ARRAY_INTERSECTION

Syntaxe

ARRAY_EXCEPT( <source_array> , <array_of_elements_to_exclude> )
Copy

Arguments

source_array

Tableau qui contient des éléments à inclure dans le nouveau ARRAY.

array_of_elements_to_exclude

Tableau qui contient des éléments à exclure du nouveau ARRAY.

Renvoie

Cette fonction renvoie un ARRAY qui contient les éléments de source_array qui ne sont pas dans array_of_elements_to_exclude.

Si aucun élément ne subsiste après avoir exclu les éléments de array_of_elements_to_exclude de source_array, la fonction renvoie un ARRAY vide.

Si l’un des arguments ou les deux sont NULL, la fonction renvoie NULL.

L’ordre des valeurs dans le tableau renvoyé n’est pas spécifié.

Notes sur l’utilisation

  • Lorsque vous comparez des données du type OBJECT, les objets doivent être identiques pour être considérés comme des correspondances. Pour plus de détails, voir Exemples (dans ce chapitre).

  • Dans Snowflake, les tableaux sont des ensembles multiples et non des ensembles simples. En d’autres termes, les tableaux peuvent contenir plusieurs copies de la même valeur.

    ARRAY_EXCEPT compare les tableaux en utilisant la sémantique à plusieurs ensembles (parfois appelée « sémantique de sac »). Si source_array comprend plusieurs copies d’une valeur, la fonction ne supprime que le nombre de copies de cette valeur qui sont spécifiées dans array_of_elements_to_exclude.

    En d’autres termes, si source_array a N copies d’une valeur et array_of_elements_to_exclude a M copies de la même valeur, la fonction exclut M copies de la valeur du tableau renvoyé. Le nombre de copies de la valeur dans le tableau renvoyé est N - M ou, si M est plus grand que N, 0.

    Par exemple, si source_array contient cinq éléments avec la valeur 'A' et array_of_elements_to_exclude contient deux éléments avec la valeur 'A', le tableau renvoyé contient trois éléments avec la valeur 'A'.

  • Si vous transmettez un ARRAY structuré :

    • Le ARRAY du deuxième argument doit être comparable au ARRAY du premier argument.

    • La fonction renvoie un ARRAY structuré du même type que le ARRAY du premier argument.

Exemples

Les exemples de cette section utilisent les constantes ARRAY et les constantes OBJECT pour spécifier ARRAYs et OBJECTs.

Les exemples suivants montrent comment utiliser la fonction :

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

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

L’exemple suivant ajoute l’élément 'C' à source_array. L’ARRAY renvoyé exclut 'C' car 'C' est également spécifié dans array_of_elements_to_exclude.

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

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

Dans l’exemple suivant, source_array contient trois éléments avec la valeur 'B'. Comme array_of_elements_to_exclude ne contient qu’un élément 'B' , la fonction exclut seulement un élément 'B' et renvoie un ARRAY contenant les deux autres éléments 'B'.

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

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

Dans l’exemple suivant, il ne reste aucun élément après avoir exclu les éléments de array_of_elements_to_exclude de source_array. En conséquence, la fonction renvoie un ARRAY vide.

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

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

L’exemple suivant montre comment la fonction traite les éléments NULL comme des valeurs connues. Comme expliqué précédemment, puisque source_array contient un élément NULL de plus que array_of_elements_to_exclude, l’ARRAY renvoyé exclut un seul élément NULL et inclut l’autre (qui est affiché comme undefined).

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

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

Dans l’exemple suivant, source_array et array_of_elements_to_exclude contiennent le même nombre d’éléments NULL, donc l’ARRAY renvoyé exclut les éléments NULL.

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

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

L’exemple suivant montre comment le fait de spécifier le même objet dans source_array et array_of_elements_to_exclude exclut cet objet de l’ARRAY renvoyé :

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

L’exemple suivant montre qu’en transmettant des valeurs NULL, la fonction renvoie un résultat NULL.

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

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