ARRAY_CONTAINS¶

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 dans array, 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 dans array, y compris lorsque l’argument value_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 valeur value_expr en une valeur VARIANT est exigée pour les valeurs des types de données suivants :

  • Chaîne et binaire

  • Date et heure

  L’exemple suivant convertit explicitement une valeur de chaîne en une valeur VARIANT :

  SELECT ARRAY_CONTAINS('mystring2'::VARIANT, ARRAY_CONSTRUCT('mystring1', 'mystring2'));
  

  Copy

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