- Catégories :
Fonctions de données semi-structurées et structurées (tableau/objet)
ARRAY_CONTAINS¶
Renvoie TRUE si la valeur spécifiée se trouve dans le tableau spécifié.
Syntaxe¶
ARRAY_CONTAINS( <value_expr> , <array> )
Arguments¶
value_expr
Valeur à trouver dans
array
.Si
array
est un tableau semi-structuré,value_expr
doit être évalué sur une VARIANT.Si
array
est un tableau structuré,value_expr
doit être évalué sur un type qui est comparable au type du tableau.
array
Le tableau à rechercher.
Renvoie¶
Cette fonction renvoie une valeur de type BOOLEAN ou NULL :
La fonction renvoie TRUE si
value_expr
est présent dansarray
, y compris dans les cas suivants :Lorsque l’argument
value_expr
est NULL et qu’il existe une valeur SQL NULL dans le tableau (undefined
).Lorsque l’argument
value_expr
est JSON null et qu’il existe une valeur JSON null dans le tableau (null
).
La fonction renvoie FALSE si
value_expr
n’est pas présent dansarray
, y compris lorsque l’argumentvalue_expr
est JSON null et qu’il n’y a pas de valeurs JSON null dans le tableau.La fonction renvoie NULL si l’argument
value_expr
est NULL et qu’il n’y a pas de valeurs SQLNULL dans le tableau.
Pour plus d’informations sur les valeurs NULL dans les tableaux, voir Valeurs NULL.
Notes sur l’utilisation¶
La fonction ne prend pas en charge les caractères génériques dans
value_expr
. Toutefois, vous pouvez utiliser la fonction ARRAY_TO_STRING pour convertir un tableau en chaîne, puis effectuer une recherche dans la chaîne à l’aide de caractères génériques. Par exemple, vous pouvez spécifier des caractères génériques pour effectuer une recherche dans la chaîne renvoyée à l’aide des fonctions [ NOT ] LIKE et REGEXP_LIKE.Si
array
est un tableau semi-structuré, la conversion explicite de la valeurvalue_expr
en une valeur VARIANT est exigée pour les valeurs des types de données suivants :L’exemple suivant convertit explicitement une valeur de chaîne en une valeur VARIANT :
SELECT ARRAY_CONTAINS('mystring2'::VARIANT, ARRAY_CONSTRUCT('mystring1', 'mystring2'));
La conversion explicite n’est pas exigée pour les valeurs d’autres types de données.
Exemples¶
Les requêtes suivantes utilisent la fonction ARRAY_CONTAINS dans une liste SELECT.
Dans cet exemple, la fonction renvoie TRUE parce que l’argument value_expr
est 'hello'
et que le tableau contient une valeur VARIANT qui stocke la chaîne 'hello'
:
SELECT ARRAY_CONTAINS('hello'::VARIANT, ARRAY_CONSTRUCT('hello', 'hi'));
+------------------------------------------------------------------+
| ARRAY_CONTAINS('HELLO'::VARIANT, ARRAY_CONSTRUCT('HELLO', 'HI')) |
|------------------------------------------------------------------|
| True |
+------------------------------------------------------------------+
Dans cet exemple, la fonction renvoie FALSE parce que l’argument value_expr
est 'hello'
mais que le tableau ne contient pas de valeur VARIANT qui stocke la chaîne 'hello'
:
SELECT ARRAY_CONTAINS('hello'::VARIANT, ARRAY_CONSTRUCT('hola', 'bonjour'));
+----------------------------------------------------------------------+
| ARRAY_CONTAINS('HELLO'::VARIANT, ARRAY_CONSTRUCT('HOLA', 'BONJOUR')) |
|----------------------------------------------------------------------|
| False |
+----------------------------------------------------------------------+
Dans cet exemple, la fonction renvoie NULL parce que l’argument value_expr
est NULL mais que le tableau ne contient pas de valeur SQL NULL :
SELECT ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('hola', 'bonjour'));
+----------------------------------------------------------+
| ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('HOLA', 'BONJOUR')) |
|----------------------------------------------------------|
| NULL |
+----------------------------------------------------------+
Dans cet exemple, la fonction renvoie TRUE parce que l’argument value_expr
est NULL et que le tableau contient une valeur SQL NULL :
SELECT ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('hola', NULL));
+-----------------------------------------------------+
| ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('HOLA', NULL)) |
|-----------------------------------------------------|
| True |
+-----------------------------------------------------+
Dans cet exemple, la fonction renvoie TRUE parce que l’argument value_expr
est une valeur JSON null et que le tableau contient une valeur JSON null :
SELECT ARRAY_CONTAINS(PARSE_JSON('null'), ARRAY_CONSTRUCT('hola', PARSE_JSON('null')));
+---------------------------------------------------------------------------------+
| ARRAY_CONTAINS(PARSE_JSON('NULL'), ARRAY_CONSTRUCT('HOLA', PARSE_JSON('NULL'))) |
|---------------------------------------------------------------------------------|
| True |
+---------------------------------------------------------------------------------+
Dans cet exemple, la fonction renvoie NULL parce que l’argument value_expr
est NULL mais que le tableau ne contient pas de valeur SQL NULL (bien qu’il contienne une valeur JSON null) :
SELECT ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('hola', PARSE_JSON('null')));
+-------------------------------------------------------------------+
| ARRAY_CONTAINS(NULL, ARRAY_CONSTRUCT('HOLA', PARSE_JSON('NULL'))) |
|-------------------------------------------------------------------|
| NULL |
+-------------------------------------------------------------------+
La requête suivante utilise la fonction ARRAY_CONTAINS dans une clause WHERE. Tout d’abord, créez une table avec une colonne ARRAY et insérez des données :
CREATE OR REPLACE TABLE array_example (id INT, array_column ARRAY);
INSERT INTO array_example (id, array_column)
SELECT 1, ARRAY_CONSTRUCT(1, 2, 3);
INSERT INTO array_example (id, array_column)
SELECT 2, ARRAY_CONSTRUCT(4, 5, 6);
SELECT * FROM array_example;
+----+--------------+
| ID | ARRAY_COLUMN |
|----+--------------|
| 1 | [ |
| | 1, |
| | 2, |
| | 3 |
| | ] |
| 2 | [ |
| | 4, |
| | 5, |
| | 6 |
| | ] |
+----+--------------+
Exécutez une requête qui spécifie la valeur à rechercher pour value_expr
et la colonne ARRAY pour array
:
SELECT * FROM array_example WHERE ARRAY_CONTAINS(5, array_column);
+----+--------------+
| ID | ARRAY_COLUMN |
|----+--------------|
| 2 | [ |
| | 4, |
| | 5, |
| | 6 |
| | ] |
+----+--------------+