Fonctions SQL et opérateurs standards

Cette page présente les expressions BigQuery, y compris les fonctions et les opérateurs.libe

Règles relatives aux appels de fonctions

Les règles suivantes s'appliquent à toutes les fonctions, sauf indication contraire explicite dans la description de la fonction :

• Pour les fonctions qui acceptent les types numériques, si l'un des opérandes est à virgule flottante et que l'autre est d'un autre type numérique, les deux opérandes sont convertis en FLOAT64 avant l'évaluation de la fonction.

• Si un opérande est NULL, le résultat est NULL, sauf pour l'opérateur "IS".

• Pour les fonctions prenant en compte le fuseau horaire (indiqué dans la description de la fonction), celui par défaut (UTC) est utilisé si aucun fuseau horaire n'est spécifié.

Préfixe SAFE.

Syntaxe :

SAFE.function_name()

Description

Si vous commencez une fonction par le préfixe SAFE., elle renvoie NULL au lieu d'une erreur. Le préfixe SAFE. n'empêche que les erreurs de la fonction préfixée elle-même : il n'empêche pas celles qui se produisent lors de l'évaluation d'expressions d'argument. Le préfixe SAFE. n'empêche que les erreurs causées par la valeur des entrées de la fonction, telles que les erreurs "valeur hors plage". D'autres erreurs, telles que des erreurs internes ou système, peuvent toujours se produire. Si la fonction ne renvoie pas d'erreur, SAFE. n'a aucun effet sur le résultat. Si elle ne renvoie jamais d'erreur, comme RAND, SAFE. n'a aucun effet.

Les opérateurs, tels que + et =, ne sont pas compatibles avec le préfixe SAFE.. Pour éviter les erreurs dues à une opération de division, utilisez SAFE_DIVIDE. Certains opérateurs, tels que IN, ARRAY et UNNEST, ressemblent à des fonctions, mais ne sont pas compatibles avec le préfixe SAFE.. Les fonctions CAST et EXTRACT n'acceptent pas non plus le préfixe SAFE.. Pour éviter les erreurs dues au casting, utilisez SAFE_CAST.

Exemple

Dans l'exemple suivant, la première utilisation de la fonction SUBSTR renvoie normalement une erreur, car la fonction n'accepte pas les arguments de longueur comportant des valeurs négatives. Cependant, en raison de la présence du préfixe SAFE., la fonction renvoie NULL à la place. La seconde utilisation de la fonction SUBSTR fournit le résultat attendu : le préfixe SAFE. n'a pas d'effet.

SELECT SAFE.SUBSTR('foo', 0, -2) AS safe_output UNION ALL
SELECT SAFE.SUBSTR('bar', 0, 2) AS safe_output;

+-------------+
| safe_output |
+-------------+
| NULL        |
| ba          |
+-------------+

Fonctions compatibles

BigQuery accepte l'utilisation du préfixe SAFE. avec la plupart des fonctions scalaires pouvant générer des erreurs, y compris les fonctions STRING, les fonctions mathématiques, les fonctions DATE, les fonctions DATETIME et les fonctions TIMESTAMP. BigQuery ne permet pas l'utilisation du préfixe SAFE. avec des fonctions d'agrégation, des fonctions analytiques ou des fonctions définies par l'utilisateur.

Appeler des fonctions persistantes définies par l'utilisateur

Remarque : La compatibilité de BigQuery avec les fonctions persistantes définies par l'utilisateur est en version bêta. Pour plus d'informations, consultez les étapes de lancement des produits.

Après avoir créé une fonction persistante définie par l'utilisateur, vous pouvez l'appeler comme n'importe quelle autre fonction, précédée du nom de l'ensemble de données dans lequel elle est définie en tant que préfixe.

Syntaxe

[`project_name`].dataset_name.function_name([parameter_value[, ...]])

Pour appeler une fonction définie par l'utilisateur dans un projet autre que celui que vous utilisez pour exécuter la requête, l'élément project_name est requis.

Exemples

L'exemple suivant crée une fonction définie par l'utilisateur nommée multiply_by_three, puis l'appelle depuis le même projet.

CREATE FUNCTION my_dataset.multiply_by_three(x INT64) AS (x * 3);

SELECT my_dataset.multiply_by_three(5) AS result; -- returns 15

L'exemple suivant appelle une fonction persistante définie par l'utilisateur depuis un projet différent.

CREATE `other_project`.other_dataset.other_function(x INT64, y INT64)
  AS (x * y * 2);

SELECT `other_project`.other_dataset.other_function(3, 4); --returns 24

Règles de conversion

La "conversion" comprend, sans toutefois s'y limiter, le casting et la coercition.

• Le casting est une conversion explicite qui utilise la fonction CAST().
• La coercition est une conversion implicite, que BigQuery effectue automatiquement dans les conditions décrites dans la suite de cette section.
• Il existe un troisième groupe de fonctions de conversion qui portent un nom de fonction spécifique, par exemple UNIX_DATE().

Le tableau ci-dessous récapitule toutes les options disponibles en matière de fonction CAST et de coercition pour les types de données BigQuery. "Coercition vers" s'applique à toutes les expressions d'un type de données particulier (par exemple, une colonne), mais les littéraux et les paramètres peuvent également faire l'objet d'une coercition. Pour plus de précisions, consultez les sections Coercition de littéraux et Coercition de paramètres.

Type source	Casting vers	Coercition vers
INT64	BOOL INT64 NUMERIC FLOAT64 STRING	FLOAT64 NUMERIC
NUMERIC	INT64 NUMERIC FLOAT64 STRING	FLOAT64
FLOAT64	INT64 NUMERIC FLOAT64 STRING
BOOL	BOOL INT64 STRING
STRING	BOOL INT64 NUMERIC FLOAT64 STRING BYTES DATE DATETIME TIME TIMESTAMP
BYTES	BYTES STRING
DATE	DATE DATETIME STRING TIMESTAMP
DATETIME	DATE DATETIME STRING TIME TIMESTAMP
TIME	STRING TIME
TIMESTAMP	DATE DATETIME STRING TIME TIMESTAMP
ARRAY	ARRAY
STRUCT	STRUCT

Casting

Syntaxe :

CAST(expr AS typename)

La syntaxe "Cast" est utilisée dans une requête pour indiquer que le type de résultat d'une expression doit être converti dans un autre type.

Exemple :

CAST(x=1 AS STRING)

Cela veut dire que le résultat est "true" si la valeur de x est 1, "false" pour toutes les autres valeurs qui ne sont pas NULL et NULL si x porte la valeur NULL.

Lors des conversions (castings) entre des types compatibles, s'il est impossible d'établir une correspondance entre la valeur d'origine et le domaine cible, des erreurs d'exécution se produisent. Par exemple, si vous tentez de convertir une valeur BYTES en STRING alors que la séquence d'octets n'est pas une valeur UTF-8 valide, une erreur d'exécution se produit.

Lorsqu'une expression x de l'un des types suivants est convertie (via une opération de casting), les règles associées à ce type s'appliquent :

De	Vers	Règle(s) appliquée(s) lors du casting de x
INT64	FLOAT64	Renvoie une valeur FLOAT64 proche, mais potentiellement non exacte.
INT64	BOOL	Renvoie FALSE si x est égal à 0, ou TRUE si ce n'est pas le cas.
NUMERIC	Virgule flottante	NUMERIC convertira l'expression en nombre à virgule flottante le plus proche avec une possible perte de précision.
FLOAT64	INT64	Renvoie la valeur INT64 la plus proche. Les cas à mi-chemin tels que 1,5 ou -0,5 sont arrondis à la valeur la plus éloignée de zéro.
FLOAT64	STRING	Renvoie une représentation de chaîne approximative.
FLOAT64	NUMERIC	Si le nombre à virgule flottante comporte plus de neuf chiffres après la virgule, il sera arrondi à la valeur la plus éloignée à mi-chemin du zéro. Si vous castez une valeur NaN, +inf ou -inf, une erreur est renvoyée. Le casting d'une valeur non comprise dans la plage de NUMERIC renvoie une erreur de dépassement de capacité.
BOOL	INT64	Renvoie 1 si x est TRUE, ou 0 si ce n'est pas le cas.
BOOL	STRING	Renvoie "true" si x est TRUE, ou "false" si ce n'est pas le cas.
STRING	FLOAT64	Renvoie x sous la forme d'une valeur FLOAT64, en l'interprétant comme ayant la même forme qu'un littéral FLOAT64 valide. Accepte également le casting de "inf", "+inf", "-inf" et "nan". Les conversions ne sont pas sensibles à la casse.
STRING	NUMERIC	Le littéral numérique contenu dans la valeur STRING ne doit pas dépasser la plage ou la précision maximale du type NUMERIC sous peine de produire une erreur. Si le nombre de chiffres après la virgule est supérieur à neuf, la valeur NUMERIC résultante sera arrondie à la valeur la plus éloignée à mi-chemin du zéro de sorte qu'elle comporte neuf chiffres après la virgule.
STRING	BOOL	Renvoie TRUE si x est "true" et FALSE si x est "false". Toutes les autres valeurs de x sont considérées comme non valides. Elles génèrent une erreur au lieu d'être converties en BOOL. Les STRING ne sont pas sensibles à la casse lorsqu'elles sont converties en BOOL.
STRING	BYTES	Les STRING sont converties en BYTES par le biais de l'encodage UTF-8. Par exemple, la conversion en BYTES de la STRING "©" donne une séquence de 2 octets dont les valeurs hexadécimales sont C2 et A9.
BYTES	STRING	Renvoie x interprété en tant que STRING UTF-8. Par exemple, en cas de conversion du littéral BYTES b'\xc2\xa9' en STRING, ce littéral est interprété en tant que chaîne UTF-8 et se présente sous la forme du caractère Unicode "©". Une erreur se produit si x n'est pas une valeur UTF-8 valide.
ARRAY	ARRAY	Le type ARRAY doit être exactement le même.
STRUCT	STRUCT	Autorisé si les conditions suivantes sont remplies : Les deux STRUCT ont le même nombre de champs. Les types de champ STRUCT d'origine peuvent être explicitement convertis en types de champ STRUCT cibles correspondants (tels que définis par l'ordre des champs, et non par leur nom).

Casting sécurisé

Lors de l'utilisation de CAST, une requête peut échouer si BigQuery est incapable d'effectuer le casting. Par exemple, la requête suivante génère une erreur :

SELECT CAST("apple" AS INT64) AS not_a_number;

Si vous souhaitez protéger vos requêtes contre ce type d'erreur, vous pouvez utiliser SAFE_CAST. La fonction SAFE_CAST est identique à CAST, sauf qu'elle renvoie NULL au lieu de générer une erreur.

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

Si vous castez des octets en chaînes, vous pouvez également utiliser la fonction SAFE_CONVERT_BYTES_TO_STRING. Tous les caractères UTF-8 non valides sont remplacés par le caractère de remplacement Unicode U+FFFD. Pour en savoir plus, consultez la section SAFE_CONVERT_BYTES_TO_STRING.

Caster des chaînes hexadécimales en nombres entiers

Si vous travaillez avec des chaînes hexadécimales (0x123), vous pouvez les caster en nombres entiers :

SELECT '0x123' as hex_value, CAST('0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | 291        |
+-----------+------------+

SELECT '-0x123' as hex_value, CAST('-0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| -0x123    | -291       |
+-----------+------------+

Caster des types de date

BigQuery permet le casting des types de date en chaînes (ou inversement) comme suit :

CAST(date_expression AS STRING)
CAST(string_expression AS DATE)

Le casting d'un type de date en chaîne ne dépend pas du fuseau horaire et son résultat se présente sous la forme YYYY-MM-DD. Le casting d'une chaîne en date ne dépend pas du fuseau horaire et la chaîne doit être conforme au format de littéral de date accepté. Si l'expression de chaîne n'est pas valide ou représente une date en dehors de la plage de valeurs minimale-maximale acceptée, une erreur est générée.

Caster des types d'horodatage

BigQuery permet le casting des types d'horodatage en chaînes (ou inversement) comme suit :

CAST(timestamp_expression AS STRING)
CAST(string_expression AS TIMESTAMP)

Lors du casting de types d'horodatage en chaînes, l'horodatage est interprété à l'aide du fuseau horaire par défaut, à savoir UTC. Le nombre de décimales (valeurs inférieures à la seconde) générées dépend du nombre de zéros dans la partie inférieure à la seconde : la fonction CAST tronquera zéro, trois ou six chiffres.

Lors de la conversion d'une chaîne en horodatage, string_expression doit être conforme aux formats de littéraux d'horodatage acceptés. Dans le cas contraire, une erreur d'exécution se produit. L'expression string_expression peut contenir une valeur time_zone (consultez la section Fuseaux horaires). Si un fuseau horaire est spécifié dans string_expression, il est utilisé pour la conversion. Dans le cas contraire, le fuseau horaire par défaut (UTC) est utilisé. Si la chaîne comporte moins de six chiffres, elle est implicitement élargie.

Une erreur est générée si l'expression string_expression n'est pas valide, si elle comporte plus de six décimales (c.-à-d. si la précision est supérieure à la microseconde) ou si elle représente une valeur temporelle en dehors de la plage d'horodatage acceptée.

Caster des types de date en horodatages (ou inversement)

BigQuery permet le casting des types de date en horodatages (ou inversement) comme suit :

CAST(date_expression AS TIMESTAMP)
CAST(timestamp_expression AS DATE)

Le casting d'une date en horodatage interprète date_expression comme heure de début de la journée (minuit) dans le fuseau horaire par défaut (UTC). Le casting d'un horodatage en date tronque effectivement l'horodatage du fuseau horaire par défaut.

Coercition

Si nécessaire, BigQuery convertit (par coercition) le type de résultat d'une expression en un autre type pour faire correspondre les signatures de fonction. Par exemple, si la fonction "func()" est définie pour accepter un seul argument de type INT64 et qu'une expression (dont le type de résultat est FLOAT64) est utilisée en tant qu'argument, le résultat de l'expression sera "converti" dans le type INT64 avant que la valeur de "func()" soit calculée.

Coercition de littéraux

BigQuery permet les coercitions de littéraux suivantes :

Type de données d'entrée	Type de données de résultat	Notes
Littéral de type STRING	DATE TIMESTAMP

La coercition de littéraux est nécessaire lorsque le type réel des littéraux est différent du type attendu par la fonction en question. Par exemple, si la fonction func() utilise un argument DATE, l'expression func("2014-09-27") est valide, car le littéral de type STRING "2014-09-27" est converti par coercition en DATE.

La conversion de littéraux est évaluée au moment de l'analyse et génère une erreur si le littéral d'entrée ne peut pas être converti dans le type cible.

Remarque : Les littéraux de chaîne ne sont pas convertis par coercition en types numériques.

Coercition de paramètres

BigQuery permet les coercitions de paramètres suivantes :

Type de données d'entrée	Type de données de résultat
Paramètre de type STRING

Si la valeur du paramètre ne peut pas être convertie par coercition dans le type cible, une erreur est générée.

Fonctions de conversion supplémentaires

BigQuery offre les fonctions de conversion supplémentaires suivantes :

• Fonctions DATE

• Fonctions DATETIME

• Fonctions TIME

• Fonctions TIMESTAMP

Fonctions d'agrégation

Une fonction d'agrégation est une fonction qui effectue un calcul sur un ensemble de valeurs. COUNT, MIN et MAX sont des exemples de fonctions d'agrégation.

SELECT COUNT(*) as total_count, COUNT(fruit) as non_null_count,
       MIN(fruit) as min, MAX(fruit) as max
FROM UNNEST([NULL, "apple", "pear", "orange"]) as fruit;

+-------------+----------------+-------+------+
| total_count | non_null_count | min   | max  |
+-------------+----------------+-------+------+
| 4           | 3              | apple | pear |
+-------------+----------------+-------+------+

Les sections suivantes décrivent les fonctions d'agrégation acceptées par BigQuery.

ANY_VALUE

ANY_VALUE(expression)  [OVER (...)]

Description

Renvoie n'importe quelle valeur de l'entrée ou NULL s'il n'y a aucune ligne d'entrée. La valeur renvoyée est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

Types d'arguments acceptés

Tous

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Types de données renvoyés

Le type renvoyé correspond au type de données d'entrée.

Exemples

SELECT ANY_VALUE(fruit) as any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+-----------+
| any_value |
+-----------+
| apple     |
+-----------+

SELECT
  fruit,
  ANY_VALUE(fruit) OVER (ORDER BY LENGTH(fruit) ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+--------+-----------+
| fruit  | any_value |
+--------+-----------+
| pear   | pear      |
| apple  | pear      |
| banana | apple     |
+--------+-----------+

ARRAY_AGG

ARRAY_AGG([DISTINCT] expression [{IGNORE|RESPECT} NULLS]
          [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

Description

Renvoie un ARRAY (tableau) de valeurs expression.

Types d'arguments acceptés

Tout type de données, sauf ARRAY.

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de ARRAY_AGG().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

3. IGNORE NULLS ou RESPECT NULLS : si IGNORE NULLS est spécifiée, les valeurs NULL sont exclues du résultat. Si RESPECT NULLS est spécifiée ou si aucune de ces clauses n'est spécifiée, les valeurs NULL sont incluses dans le résultat (toutefois, si un tableau du résultat final de la requête contient un élément NULL, une erreur est générée).

4. ORDER BY : spécifie l'ordre des valeurs.

   • Pour chaque clé de tri, le sens de tri par défaut est ASC.
   • Valeurs NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire qu'elles apparaissent en premier dans les tris ASC et en dernier dans les tris DESC.
   • Types de données avec virgule flottante : consultez la section Sémantique à virgule flottante sur le tri et le regroupement.
   • Si DISTINCT est également spécifié, la clé de tri doit être identique à expression.
   • Si ORDER BY n'est pas spécifié, l'ordre des éléments dans le tableau de sortie est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

5. LIMIT : spécifie le nombre maximal d'entrées expression dans le résultat. La limite n doit être une valeur INT64 constante.

Types de données renvoyés

ARRAY

S'il n'y a aucune ligne d'entrée, cette fonction renvoie NULL.

Exemples

SELECT FORMAT("%T", ARRAY_AGG(x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------------+
| array_agg               |
+-------------------------+
| [2, 1, -2, 3, -2, 1, 2] |
+-------------------------+

SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+---------------+
| array_agg     |
+---------------+
| [2, 1, -2, 3] |
+---------------+

SELECT FORMAT("%T", ARRAY_AGG(x IGNORE NULLS)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [1, -2, 3, -2, 1] |
+-------------------+

SELECT FORMAT("%T", ARRAY_AGG(x ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;
+-------------------------+
| array_agg               |
+-------------------------+
| [1, 1, 2, -2, -2, 2, 3] |
+-------------------------+

SELECT FORMAT("%T", ARRAY_AGG(x LIMIT 5)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [2, 1, -2, 3, -2] |
+-------------------+

SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x IGNORE NULLS ORDER BY x LIMIT 2)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-----------+
| array_agg |
+-----------+
| [-2, 1]   |
+-----------+

SELECT
  x,
  FORMAT("%T", ARRAY_AGG(x) OVER (ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+----+-------------------------+
| x  | array_agg               |
+----+-------------------------+
| 1  | [1, 1]                  |
| 1  | [1, 1]                  |
| 2  | [1, 1, 2, -2, -2, 2]    |
| -2 | [1, 1, 2, -2, -2, 2]    |
| -2 | [1, 1, 2, -2, -2, 2]    |
| 2  | [1, 1, 2, -2, -2, 2]    |
| 3  | [1, 1, 2, -2, -2, 2, 3] |
+----+-------------------------+

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])

Description

Concatène les éléments de la valeur expression de type ARRAY et renvoie un seul élément ARRAY. Cette fonction ignore les tableaux d'entrée NULL, mais respecte les éléments NULL des tableaux d'entrée non NULL (toutefois, si un tableau du résultat final de la requête contient un élément NULL, une erreur est générée).

Types d'arguments acceptés

ARRAY

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. ORDER BY : spécifie l'ordre des valeurs.

   • Pour chaque clé de tri, le sens de tri par défaut est ASC.
   • Le tri de tableaux n'est pas accepté, et la clé de tri ne peut donc pas être identique à expression.
   • Valeurs NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire qu'elles apparaissent en premier dans les tris ASC et en dernier dans les tris DESC.
   • Types de données avec virgule flottante : consultez la section Sémantique à virgule flottante sur le tri et le regroupement.
   • Si ORDER BY n'est pas spécifié, l'ordre des éléments dans le tableau de sortie est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

2. LIMIT : spécifie le nombre maximal d'entrées expression dans le résultat. La limite s'applique au nombre de tableaux d'entrée, pas au nombre d'éléments figurant dans les tableaux. Un tableau vide compte pour une unité. Un tableau NULL n'est pas comptabilisé. La limite n doit être une valeur INT64 constante.

Types de données renvoyés

ARRAY

Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation d'expression donne NULL pour toutes les lignes.

Exemples

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
+-----------------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x ORDER BY ARRAY_LENGTH(x))) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [5, 6, 7, 8, 9, NULL, 1, 2, 3, 4] |
+-----------------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x LIMIT 2)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+--------------------------+
| array_concat_agg         |
+--------------------------+
| [NULL, 1, 2, 3, 4, 5, 6] |
+--------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x ORDER BY ARRAY_LENGTH(x) LIMIT 2)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+------------------+
| array_concat_agg |
+------------------+
| [5, 6, 7, 8, 9]  |
+------------------+

AVG

AVG([DISTINCT] expression)  [OVER (...)]

Description

Renvoie la moyenne des valeurs d'entrée différentes de NULL, ou NaN si l'entrée contient une valeur NaN.

Types d'arguments acceptés

Tout type d'entrée numérique, par exemple INT64. Notez que le résultat renvoyé est non déterministe pour les types d'entrée à virgule flottante, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de AVG().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Types de données renvoyés

• NUMERIC si le type d'entrée est NUMERIC.
• FLOAT64

Exemples

SELECT AVG(x) as avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) as x;

+-----+
| avg |
+-----+
| 3   |
+-----+

SELECT AVG(DISTINCT x) AS avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) AS x;

+------+
| avg  |
+------+
| 2.75 |
+------+

SELECT
  x,
  AVG(x) OVER (ORDER BY x ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) AS x;

+------+------+
| x    | avg  |
+------+------+
| NULL | NULL |
| 0    | 0    |
| 2    | 1    |
| 4    | 3    |
| 4    | 4    |
| 5    | 4.5  |
+------+------+

BIT_AND

BIT_AND(expression)

Description

Effectue une opération AND (ET) bit à bit sur l'expression et renvoie le résultat.

Types d'arguments acceptés

• INT64

Types de données renvoyés

INT64

Exemples

SELECT BIT_AND(x) as bit_and FROM UNNEST([0xF001, 0x00A1]) as x;

+---------+
| bit_and |
+---------+
| 1       |
+---------+

BIT_OR

BIT_OR(expression)

Description

Effectue une opération OR (OU) bit à bit sur l'expression et renvoie le résultat.

Types d'arguments acceptés

• INT64

Types de données renvoyés

INT64

Exemples

SELECT BIT_OR(x) as bit_or FROM UNNEST([0xF001, 0x00A1]) as x;

+--------+
| bit_or |
+--------+
| 61601  |
+--------+

BIT_XOR

BIT_XOR([DISTINCT] expression)

Description

Effectue une opération XOR (OU exclusif) bit à bit sur l'expression et renvoie le résultat.

Types d'arguments acceptés

• INT64

Clause facultative

DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Types de données renvoyés

INT64

Exemples

SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+

SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;
+---------+
| bit_xor |
+---------+
| 5678    |
+---------+

SELECT BIT_XOR(DISTINCT x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+

COUNT

1.

COUNT(*)  [OVER (...)]

2.

COUNT([DISTINCT] expression)  [OVER (...)]

Description

1. Renvoie le nombre de lignes dans l'entrée.
2. Renvoie le nombre de lignes où expression est évaluée avec une valeur autre que NULL.

Types d'arguments acceptés

expression peut correspondre à n'importe quel type de données.

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Types de données renvoyés

INT64

Exemples

SELECT
  COUNT(*) AS count_star,
  COUNT(x) AS count_x,
  COUNT(DISTINCT x) AS count_dist_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------------+---------+--------------+
| count_star | count_x | count_dist_x |
+------------+---------+--------------+
| 5          | 4       | 3            |
+------------+---------+--------------+

SELECT
  x,
  COUNT(*) OVER (PARTITION BY MOD(x, 3)) AS count_star,
  COUNT(x) OVER (PARTITION BY MOD(x, 3)) AS count_x,
  COUNT(DISTINCT x) OVER (PARTITION BY MOD(x, 3)) AS count_dist_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------+------------+---------+--------------+
| x    | count_star | count_x | count_dist_x |
+------+------------+---------+--------------+
| NULL | 1          | 0       | 0            |
| 1    | 3          | 3       | 2            |
| 4    | 3          | 3       | 2            |
| 4    | 3          | 3       | 2            |
| 5    | 1          | 1       | 1            |
+------+------------+---------+--------------+

COUNTIF

COUNTIF(expression)  [OVER (...)]

Description

Renvoie le nombre de valeurs TRUE pour l'expression. Renvoie 0 s'il n'y a aucune ligne d'entrée ou si l'évaluation de l'expression donne FALSE pour toutes les lignes.

Types d'arguments acceptés

BOOL

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Types de données renvoyés

INT64

Exemples

SELECT COUNTIF(x<0) AS num_negative, COUNTIF(x>0) AS num_positive
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) AS x;

+--------------+--------------+
| num_negative | num_positive |
+--------------+--------------+
| 3            | 4            |
+--------------+--------------+

SELECT
  x,
  COUNTIF(x<0) OVER (ORDER BY ABS(x) ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING) AS num_negative
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) AS x;

+------+--------------+
| x    | num_negative |
+------+--------------+
| NULL | 0            |
| 0    | 1            |
| -2   | 1            |
| 3    | 1            |
| 4    | 0            |
| 5    | 0            |
| 6    | 1            |
| -7   | 2            |
| -10  | 2            |
+------+--------------+

LOGICAL_AND

LOGICAL_AND(expression)

Description

Renvoie le AND (ET) logique de toutes les expressions non nulles (non-NULL). Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation de l'expression est NULL pour toutes les lignes.

Types d'arguments acceptés

BOOL

Types de données renvoyés

BOOL

Exemples

SELECT LOGICAL_AND(x) as logical_and FROM UNNEST([true, false, true]) as x;

+-------------+
| logical_and |
+-------------+
| false       |
+-------------+

LOGICAL_OR

LOGICAL_OR(expression)

Description

Renvoie le OR (OU) logique de toutes les expressions non nulles (non-NULL). Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation de l'expression est NULL pour toutes les lignes.

Types d'arguments acceptés

BOOL

Types de données renvoyés

BOOL

Exemples

SELECT LOGICAL_OR(x) as logical_or FROM UNNEST([true, false, true]) as x;

+------------+
| logical_or |
+------------+
| true       |
+------------+

MAX

MAX(expression)  [OVER (...)]

Description

Renvoie la valeur maximale des expressions non nulles (non-NULL). Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation de l'expression est NULL pour toutes les lignes. Renvoie NaN si l'entrée contient une valeur NaN.

Types d'arguments acceptés

Tout type de données sauf : ARRAY STRUCT

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Types de données renvoyés

Identique au type de données utilisé pour les valeurs d'entrée.

Exemples

SELECT MAX(x) AS max
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+-----+
| max |
+-----+
| 55  |
+-----+

SELECT x, MAX(x) OVER (PARTITION BY MOD(x, 2)) AS max
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | max  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 8    |
| 4    | 8    |
| 37   | 55   |
| 55   | 55   |
+------+------+

MIN

MIN(expression)  [OVER (...)]

Description

Renvoie la valeur minimale des expressions non nulles (non-NULL). Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation de l'expression est NULL pour toutes les lignes. Renvoie NaN si l'entrée contient une valeur NaN.

Types d'arguments acceptés

Tout type de données sauf : ARRAY STRUCT

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Types de données renvoyés

Identique au type de données utilisé pour les valeurs d'entrée.

Exemples

SELECT MIN(x) AS min
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+-----+
| min |
+-----+
| 4   |
+-----+

SELECT x, MIN(x) OVER (PARTITION BY MOD(x, 2)) AS min
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | min  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 4    |
| 4    | 4    |
| 37   | 37   |
| 55   | 37   |
+------+------+

STRING_AGG

STRING_AGG([DISTINCT] expression [, delimiter]  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

Description

Renvoie une valeur (STRING ou BYTES) obtenue par concaténation des valeurs non nulles.

Si un delimiter est spécifié, les valeurs concaténées sont séparées par ce délimiteur. Dans le cas contraire, une virgule est utilisée comme délimiteur.

Types d'arguments acceptés

STRING BYTES

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STRING_AGG().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

3. ORDER BY : spécifie l'ordre des valeurs.

   • Pour chaque clé de tri, le sens de tri par défaut est ASC.
   • Valeurs NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire qu'elles apparaissent en premier dans les tris ASC et en dernier dans les tris DESC.
   • Types de données avec virgule flottante : consultez la section Sémantique à virgule flottante sur le tri et le regroupement.
   • Si DISTINCT est également spécifié, la clé de tri doit être identique à expression.
   • Si ORDER BY n'est pas spécifié, l'ordre des éléments dans le tableau de sortie est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

4. LIMIT : spécifie le nombre maximal d'entrées expression dans le résultat. La limite s'applique au nombre de chaînes d'entrée, pas au nombre de caractères ou d'octets que contiennent les entrées. Une chaîne vide compte pour une unité. Une chaîne NULL n'est pas comptabilisée. La limite n doit être une valeur INT64 constante.

Types de données renvoyés

STRING BYTES

Exemples

SELECT STRING_AGG(fruit) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------+
| string_agg             |
+------------------------+
| apple,pear,banana,pear |
+------------------------+

SELECT STRING_AGG(fruit, " & ") AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------------+
| string_agg                   |
+------------------------------+
| apple & pear & banana & pear |
+------------------------------+

SELECT STRING_AGG(DISTINCT fruit, " & ") AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+-----------------------+
| string_agg            |
+-----------------------+
| apple & banana & pear |
+-----------------------+

SELECT STRING_AGG(fruit, " & " ORDER BY LENGTH(fruit)) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------------+
| string_agg                   |
+------------------------------+
| pear & pear & apple & banana |
+------------------------------+

SELECT STRING_AGG(fruit, " & " LIMIT 2) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+--------------+
| string_agg   |
+--------------+
| apple & pear |
+--------------+

SELECT STRING_AGG(DISTINCT fruit, " & " ORDER BY fruit DESC LIMIT 2) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+---------------+
| string_agg    |
+---------------+
| pear & banana |
+---------------+

SELECT
  fruit,
  STRING_AGG(fruit, " & ") OVER (ORDER BY LENGTH(fruit)) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+--------+------------------------------+
| fruit  | string_agg                   |
+--------+------------------------------+
| NULL   | NULL                         |
| pear   | pear & pear                  |
| pear   | pear & pear                  |
| apple  | pear & pear & apple          |
| banana | pear & pear & apple & banana |
+--------+------------------------------+

SUM

SUM([DISTINCT] expression)  [OVER (...)]

Description

Renvoie la somme des valeurs non nulles.

Si l'expression est une valeur à virgule flottante, la somme est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

Types d'arguments acceptés

Tout type de données numériques accepté.

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Types de données renvoyés

• Renvoie INT64 si l'entrée est un entier.

• Renvoie NUMERIC si le type d'entrée est NUMERIC.

• Renvoie FLOAT64 si l'entrée est une valeur à virgule flottante.

Renvoie NULL si l'entrée ne contient que des valeurs NULL.

Renvoie Inf si l'entrée contient Inf.

Renvoie -Inf si l'entrée contient -Inf.

Renvoie NaN si l'entrée contient une valeur NaN.

Renvoie NaN si l'entrée contient une combinaison de Inf et -Inf.

Exemples

SELECT SUM(x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 25  |
+-----+

SELECT SUM(DISTINCT x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 15  |
+-----+

SELECT
  x,
  SUM(x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 6   |
| 3 | 6   |
| 1 | 10  |
| 4 | 10  |
| 4 | 10  |
| 1 | 10  |
| 2 | 9   |
| 5 | 9   |
| 2 | 9   |
+---+-----+

SELECT
  x,
  SUM(DISTINCT x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 3   |
| 3 | 3   |
| 1 | 5   |
| 4 | 5   |
| 4 | 5   |
| 1 | 5   |
| 2 | 7   |
| 5 | 7   |
| 2 | 7   |
+---+-----+

Fonctions d'agrégation statistique

BigQuery accepte les fonctions d'agrégation statistique ci-après.

CORR

CORR(X1, X2)  [OVER (...)]

Description

Renvoie le coefficient de corrélation de Pearson d'un ensemble de paires de nombres. Pour chaque paire de nombres, le premier nombre est la variable dépendante et le second est la variable indépendante. Le résultat est compris entre -1 et 1. Un résultat égal à 0 indique une absence de corrélation.

Cette fonction ignore les paires d'entrées qui contiennent une ou plusieurs valeurs NULL. S'il y a moins de deux paires d'entrées sans valeur NULL, cette fonction renvoie NULL.

Types d'entrée acceptés

FLOAT64

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Type de données renvoyé

FLOAT64

COVAR_POP

COVAR_POP(X1, X2)  [OVER (...)]

Description

Renvoie la covariance de population d'un ensemble de paires de nombres. Le premier nombre est la variable dépendante, et le second est la variable indépendante. Le résultat renvoyé est compris entre -Inf et +Inf.

Cette fonction ignore les paires d'entrées qui contiennent une ou plusieurs valeurs NULL. S'il n'y a aucune paire d'entrées sans valeur NULL, cette fonction renvoie NULL.

Types d'entrée acceptés

FLOAT64

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Type de données renvoyé

FLOAT64

COVAR_SAMP

COVAR_SAMP(X1, X2)  [OVER (...)]

Description

Renvoie la covariance d'échantillon d'un ensemble de paires de nombres. Le premier nombre est la variable dépendante, et le second est la variable indépendante. Le résultat renvoyé est compris entre -Inf et +Inf.

Cette fonction ignore les paires d'entrées qui contiennent une ou plusieurs valeurs NULL. S'il y a moins de deux paires d'entrées sans valeur NULL, cette fonction renvoie NULL.

Types d'entrée acceptés

FLOAT64

Clause facultative

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.

Type de données renvoyé

FLOAT64

STDDEV_POP

STDDEV_POP([DISTINCT] expression)  [OVER (...)]

Description

Renvoie l'écart type (biaisé) de population des valeurs. Le résultat renvoyé est compris entre 0 et +Inf.

Cette fonction ignore toutes les entrées NULL. Si toutes les entrées sont ignorées, elle renvoie NULL.

Si cette fonction reçoit une seule entrée non-NULL, elle renvoie 0.

Types d'entrée acceptés

FLOAT64

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STDDEV_POP().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

FLOAT64

STDDEV_SAMP

STDDEV_SAMP([DISTINCT] expression)  [OVER (...)]

Description

Renvoie l'écart type (non biaisé) d'échantillon des valeurs. Le résultat renvoyé est compris entre 0 et +Inf.

Cette fonction ignore toutes les entrées NULL. S'il y a moins de deux entrées non-NULL, elle renvoie NULL.

Types d'entrée acceptés

FLOAT64

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STDDEV_SAMP().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

FLOAT64

STDDEV

STDDEV([DISTINCT] expression)  [OVER (...)]

Description

Alias de STDDEV_SAMP.

VAR_POP

VAR_POP([DISTINCT] expression)  [OVER (...)]

Description

Renvoie la variance (biaisée) de population des valeurs. Le résultat renvoyé est compris entre 0 et +Inf.

Cette fonction ignore toutes les entrées NULL. Si toutes les entrées sont ignorées, elle renvoie NULL.

Si cette fonction reçoit une seule entrée non-NULL, elle renvoie 0.

Types d'entrée acceptés

FLOAT64

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de VAR_POP().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

FLOAT64

VAR_SAMP

VAR_SAMP([DISTINCT] expression)  [OVER (...)]

Description

Renvoie la variance (non biaisée) d'échantillon des valeurs. Le résultat renvoyé est compris entre 0 et +Inf.

Cette fonction ignore toutes les entrées NULL. S'il y a moins de deux entrées non-NULL, elle renvoie NULL.

Types d'entrée acceptés

FLOAT64

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de VAR_SAMP().

2. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

FLOAT64

VARIANCE

VARIANCE([DISTINCT] expression)  [OVER (...)]

Description

Alias de VAR_SAMP.

Fonctions d'agrégation approximative

Les fonctions d'agrégation approximative sont adaptables en termes de temps et d'utilisation de la mémoire, mais elles produisent des résultats approximatifs au lieu de résultats exacts. Pour en savoir plus, consultez la page Agrégation approximative.

APPROX_COUNT_DISTINCT

APPROX_COUNT_DISTINCT(expression)

Description

Renvoie le résultat approximatif de COUNT(DISTINCT expression). La valeur renvoyée est une estimation statistique, pas nécessairement la valeur réelle.

Cette fonction est moins précise que COUNT(DISTINCT expression), mais elle fonctionne mieux en cas d'entrée volumineuse.

Types d'arguments acceptés

Tout type de données sauf : ARRAY STRUCT

Types de données renvoyés

INT64

Exemples

SELECT APPROX_COUNT_DISTINCT(x) as approx_distinct
FROM UNNEST([0, 1, 1, 2, 3, 5]) as x;

+-----------------+
| approx_distinct |
+-----------------+
| 5               |
+-----------------+

APPROX_QUANTILES

APPROX_QUANTILES([DISTINCT] expression, number [{IGNORE|RESPECT} NULLS])

Description

Renvoie les limites approximatives d'un groupe de valeurs expression, où number représente le nombre de quantiles à créer. Cette fonction renvoie un tableau de number + 1 éléments, le premier élément étant le minimum approximatif et le dernier le maximum approximatif.

Types d'arguments acceptés

expression peut correspondre à n'importe quel type de données accepté, sauf : ARRAY STRUCT

number doit être de type INT64.

Clauses facultatives

Les clauses sont appliquées dans l'ordre suivant :

1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

2. IGNORE NULLS ou RESPECT NULLS : si IGNORE NULLS est spécifiée ou si aucune de ces clauses n'est spécifiée, les valeurs NULL sont exclues du résultat. Si RESPECT NULLS est spécifiée, les valeurs NULL sont incluses dans le résultat (toutefois, si un tableau du résultat final de la requête contient un élément NULL, une erreur est générée).

Types de données renvoyés

Un tableau (ARRAY) du type spécifié par le paramètre expression.

Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation d'expression donne NULL pour toutes les lignes.

Exemples

SELECT APPROX_QUANTILES(x, 2) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 5, 10]       |
+------------------+

SELECT APPROX_QUANTILES(x, 100)[OFFSET(90)] AS percentile_90
FROM UNNEST([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) AS x;

+---------------+
| percentile_90 |
+---------------+
| 9             |
+---------------+

SELECT APPROX_QUANTILES(DISTINCT x, 2) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 6, 10]       |
+------------------+

SELECT FORMAT("%T", APPROX_QUANTILES(x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 4, 10]    |
+------------------+

SELECT FORMAT("%T", APPROX_QUANTILES(DISTINCT x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 6, 10]    |
+------------------+

APPROX_TOP_COUNT

APPROX_TOP_COUNT(expression, number)

Description

Renvoie les premiers éléments approximatifs d'expression. Le paramètre number spécifie le nombre d'éléments renvoyés.

Types d'arguments acceptés

expression peut correspondre à n'importe quel type de données accepté par la clause GROUP BY.

number doit être de type INT64.

Types de données renvoyés

Un tableau (ARRAY) de type STRUCT. L'objet STRUCT contient deux champs. Le premier champ (nommé value) contient une valeur d'entrée. Le second champ (nommé count) contient un entier de type INT64 spécifiant le nombre de fois où la valeur a été renvoyée.

Renvoie NULL s'il n'y a aucune ligne d'entrée.

Exemples

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST(["apple", "apple", "pear", "pear", "pear", "banana"]) as x;

+-------------------------+
| approx_top_count        |
+-------------------------+
| [{pear, 3}, {apple, 2}] |
+-------------------------+

Gestion des valeurs NULL

APPROX_TOP_COUNT n'ignore pas les valeurs NULL dans l'entrée. Par exemple :

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST([NULL, "pear", "pear", "pear", "apple", NULL]) as x;

+------------------------+
| approx_top_count       |
+------------------------+
| [{pear, 3}, {NULL, 2}] |
+------------------------+

APPROX_TOP_SUM

APPROX_TOP_SUM(expression, weight, number)

Description

Renvoie les premiers éléments approximatifs d'expression, en fonction de la somme d'un paramètre weight attribué. Le paramètre number spécifie le nombre d'éléments renvoyés.

Si l'entrée weight est négative ou correspond à NaN, cette fonction renvoie une erreur.

Types d'arguments acceptés

expression peut correspondre à n'importe quel type de données accepté par la clause GROUP BY.

weight doit être de l'un des types suivants :

• INT64
• FLOAT64

number doit être de type INT64.

Types de données renvoyés

Un tableau (ARRAY) de type STRUCT. L'objet STRUCT contient deux champs : value et sum. Le champ value contient la valeur de l'expression d'entrée. Le champ sum est du même type que weight, et il correspond à la somme approximative de la pondération d'entrée associée au champ value.

Renvoie NULL s'il n'y a aucune ligne d'entrée.

Exemples

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([
  STRUCT("apple" AS x, 3 AS weight),
  ("pear", 2),
  ("apple", 0),
  ("banana", 5),
  ("pear", 4)
]);

+--------------------------+
| approx_top_sum           |
+--------------------------+
| [{pear, 6}, {banana, 5}] |
+--------------------------+

Gestion des valeurs NULL

APPROX_TOP_SUM n'ignore pas les valeurs NULL pour les paramètres expression et weight.

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, NULL AS weight), ("pear", 0), ("pear", NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{pear, 0}, {apple, NULL}] |
+----------------------------+

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, 2)]);

+-------------------------+
| approx_top_sum          |
+-------------------------+
| [{NULL, 2}, {apple, 0}] |
+-------------------------+

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{apple, 0}, {NULL, NULL}] |
+----------------------------+

Fonctions HyperLogLog++

BigQuery accepte les fonctions d'agrégation approximative suivantes qui utilisent l'algorithme HyperLogLog++. Pour plus d'informations sur le fonctionnement des fonctions d'agrégation approximative, consultez la page Agrégation approximative.

HLL_COUNT.INIT

HLL_COUNT.INIT(input [, precision])

Description

Fonction d'agrégation qui prend une ou plusieurs valeurs input et les agrège dans un nouveau résumé HyperLogLog++. Chaque résumé est représenté à l'aide du type de données BYTES. Vous pouvez ensuite fusionner des résumés à l'aide de HLL_COUNT.MERGE ou de HLL_COUNT.MERGE_PARTIAL. Si aucune fusion n'est nécessaire, vous pouvez extraire le nombre final de valeurs distinctes du résumé à l'aide de HLL_COUNT.EXTRACT.

Une valeur input peut être de l'un des types suivants :

• INT64
• STRING
• BYTES

Cette fonction accepte un paramètre facultatif, precision. Ce dernier définit la précision de l'estimation au détriment de la mémoire supplémentaire requise pour traiter les résumés ou les stocker sur disque. Le tableau suivant indique les valeurs de précision autorisées, la taille maximale de résumé par groupe et l'intervalle de confiance (IC) des précisions types :

Précision	Taille maximale de résumé (Kio)	IC à 65 %	IC à 95 %	IC à 99 %
10	1	±1,63 %	±3,25 %	±6,50 %
11	2	±1,15 %	±2,30 %	±4,60 %
12	4	±0,81 %	±1,63 %	±3,25 %
13	8	±0,57 %	±1,15 %	±1,72 %
14	16	±0,41 %	±0,81 %	±1,22 %
15 (par défaut)	32	±0,29 %	±0,57 %	±0,86 %
16	64	±0,20 %	±0,41 %	±0,61 %
17	128	±0,14 %	±0,29 %	±0,43 %
18	256	±0,10 %	±0,20 %	±0,41 %
19	512	±0,07 %	±0,14 %	±0,29 %
20	1 024	±0,05 %	±0,10 %	±0,20 %
21	2 048	±0,04 %	±0,07 %	±0,14 %
22	4 096	±0,03 %	±0,05 %	±0,10 %
23	8 192	±0,02 %	±0,04 %	±0,07 %
24	16 384	±0,01 %	±0,03 %	±0,05 %

Si l'entrée est NULL, cette fonction renvoie NULL.

Pour plus d'informations, consultez l'article HyperLogLog dans la pratique : Ingénierie algorithmique d'un algorithme avancé d'estimation de la cardinalité.

Type d'entrée accepté

BYTES

Type renvoyé

BYTES

Exemple

SELECT
  HLL_COUNT.INIT(respondent) AS respondents_hll,
  flavor,
  country
FROM UNNEST([
  STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
  (1, "Chocolate", "CH"),
  (2, "Chocolate", "US"),
  (2, "Strawberry", "US")])
GROUP BY flavor, country;

HLL_COUNT.MERGE

HLL_COUNT.MERGE(sketch)

Description

Fonction d'agrégation qui renvoie la cardinalité de plusieurs résumés HyperLogLog++ en calculant leur union.

Chaque résumé (sketch) doit avoir la même précision et être initialisé sur le même type. Les tentatives de fusion de résumés ayant des précisions différentes ou pour des types différents entraînent une erreur. Par exemple, vous ne pouvez pas fusionner un résumé initialisé à partir de données INT64 avec un résumé initialisé à partir de données STRING.

Cette fonction ignore les valeurs NULL lors de la fusion de résumés. Si la fusion ne se produit sur aucune ligne ou seulement sur des valeurs NULL, la fonction renvoie 0.

Types d'entrée acceptés

BYTES

Type renvoyé

INT64

Exemple

SELECT HLL_COUNT.MERGE(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.MERGE_PARTIAL

HLL_COUNT.MERGE_PARTIAL(sketch)

Description

Fonction d'agrégation qui prend une ou plusieurs entrées sketch sketch et les agrège dans un nouveau résumé.

Cette fonction renvoie NULL s'il n'y a aucune entrée ou si toutes les entrées sont NULL.

Types d'entrée acceptés

BYTES

Type renvoyé

BYTES

Exemple

SELECT HLL_COUNT.MERGE_PARTIAL(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.EXTRACT

HLL_COUNT.EXTRACT(sketch)

Description

Fonction scalaire qui extrait une estimation de la cardinalité d'un seul résumé HyperLogLog++.

Si sketch est NULL, cette fonction renvoie une estimation de la cardinalité égale à 0.

Types d'entrée acceptés

BYTES

Type renvoyé

INT64

Exemple

SELECT
  flavor,
  country,
  HLL_COUNT.EXTRACT(respondents_hll) AS num_respondents
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country);

+------------+---------+-----------------+
| flavor     | country | num_respondents |
+------------+---------+-----------------+
| Vanilla    | CH      | 1               |
| Chocolate  | CH      | 1               |
| Chocolate  | US      | 1               |
| Strawberry | US      | 1               |
+------------+---------+-----------------+

Fonctions de numérotation

Les sections suivantes décrivent les fonctions de numérotation acceptées par BigQuery. Ces fonctions sont un sous-ensemble des fonctions analytiques. Pour plus d'informations sur le fonctionnement des fonctions analytiques, consultez la page Concepts de fonction analytique. Pour en savoir plus sur le fonctionnement des fonctions de numérotation, consultez la page Concepts de fonction de numérotation.

Exigences de la clause OVER :

• PARTITION BY : facultatif.
• ORDER BY : obligatoire, sauf pour ROW_NUMBER().
• window_frame_clause : non autorisé.

RANK

Description

Renvoie le rang ordinal (de base 1) de chaque ligne de la partition triée. Toutes les lignes homologues reçoivent la même valeur de rang. La ligne ou l'ensemble de lignes homologues suivant reçoit une valeur de rang qui est incrémentée en fonction du nombre d'homologues ayant le rang précédent, contrairement à DENSE_RANK, qui incrémente toujours la valeur d'une unité.

Types d'arguments acceptés

INT64

DENSE_RANK

Description

Renvoie le rang ordinal (de base 1) de chaque ligne de la partition de fenêtre. Toutes les lignes homologues reçoivent la même valeur de rang, et la valeur de rang suivante est incrémentée d'une unité.

Types d'arguments acceptés

INT64

PERCENT_RANK

Description

Renvoie le rang en centile d'une ligne, défini par (RK-1)/(NR-1). RK correspond au rang (RANK) de la ligne et NR correspond au nombre de lignes dans la partition. Renvoie 0 si NR=1.

Types d'arguments acceptés

FLOAT64

CUME_DIST

Description

Renvoie le rang relatif d'une ligne, défini par NP/NR. NP correspond au nombre de lignes qui précèdent la ligne actuelle ou qui en sont les homologues. NR correspond au nombre de lignes dans la partition.

Types d'arguments acceptés

FLOAT64

NTILE

NTILE(constant_integer_expression)

Description

Cette fonction divise les lignes en buckets constant_integer_expression en fonction de l'ordre des lignes et renvoie le numéro de bucket de base 1 attribué à chaque ligne. Le nombre de lignes dans les buckets peut différer d'une unité au maximum. Les valeurs restantes (le nombre de lignes restantes divisé par le nombre de buckets) sont distribuées de sorte qu'il y en ait une par bucket, en commençant par le bucket 1. Si constant_integer_expression renvoie une valeur négative, NULL ou 0, une erreur est générée.

Types d'arguments acceptés

INT64

ROW_NUMBER

Description

La clause ORDER BY n'est pas obligatoire. Renvoie le numéro ordinal séquentiel (de base 1) de chaque ligne pour chaque partition triée. Si la clause ORDER BY n'est pas spécifiée, le résultat est non déterministe.

Types d'arguments acceptés

INT64

Fonctions sur bits

BigQuery accepte les fonctions sur bits ci-après.

BIT_COUNT

BIT_COUNT(expression)

Description

L'entrée, expression, doit être un entier ou de type BYTES.

Renvoie le nombre de bits définis dans l'expression d'entrée. Pour les entiers signés, il s'agit du nombre de bits sous forme de complément à deux.

Type de données renvoyé

INT64

Exemple

SELECT a, BIT_COUNT(a) AS a_bits, FORMAT("%T", b) as b, BIT_COUNT(b) AS b_bits
FROM UNNEST([
  STRUCT(0 AS a, b'' AS b), (0, b'\x00'), (5, b'\x05'), (8, b'\x00\x08'),
  (0xFFFF, b'\xFF\xFF'), (-2, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFE'),
  (-1, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF'),
  (NULL, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF')
]) AS x;

+-------+--------+---------------------------------------------+--------+
| a     | a_bits | b                                           | b_bits |
+-------+--------+---------------------------------------------+--------+
| 0     | 0      | b""                                         | 0      |
| 0     | 0      | b"\x00"                                     | 0      |
| 5     | 2      | b"\x05"                                     | 2      |
| 8     | 1      | b"\x00\x08"                                 | 1      |
| 65535 | 16     | b"\xff\xff"                                 | 16     |
| -2    | 63     | b"\xff\xff\xff\xff\xff\xff\xff\xfe"         | 63     |
| -1    | 64     | b"\xff\xff\xff\xff\xff\xff\xff\xff"         | 64     |
| NULL  | NULL   | b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff" | 80     |
+-------+--------+---------------------------------------------+--------+

Fonctions mathématiques

Toutes les fonctions mathématiques se comportent de la façon suivante :

• Elles renvoient NULL si l'un des paramètres d'entrée est NULL.
• Elles renvoient NaN si l'un des arguments est NaN.

ABS

ABS(X)

Description

Calcule la valeur absolue. Renvoie une erreur si l'argument est un entier et que la valeur de sortie ne peut pas être représentée avec le même type. Cela ne peut se produire que pour la plus grande valeur d'entrée négative, qui n'a pas de représentation positive. Renvoie +inf pour un argument +/-inf.

SIGN

SIGN(X)

Description

Renvoie respectivement -1, 0 ou +1 pour les arguments "négatif", "zéro" et "positif". Pour les arguments à virgule flottante, cette fonction ne fait pas la distinction entre zéro positif et zéro négatif. Renvoie NaN pour un argument NaN.

IS_INF

IS_INF(X)

Description

Renvoie TRUE si la valeur correspond à l'infini positif ou négatif. Renvoie NULL pour les entrées NULL.

IS_NAN

IS_NAN(X)

Description

Renvoie TRUE si la valeur est une valeur NaN. Renvoie NULL pour les entrées NULL.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Description

Divise X par Y ; cette fonction n'échoue jamais. Renvoie une valeur FLOAT64. Contrairement à l'opérateur de division (/), cette fonction ne génère pas d'erreur en cas de division par zéro ou de débordement.

Cas particuliers :

• Si le résultat déborde, cette fonction renvoie +/-inf.
• Si Y=0 et X=0, elle renvoie NaN.
• Si Y=0 et X!=0, elle renvoie +/-inf.
• Si X = +/-inf et Y = +/-inf, elle renvoie NaN.

Le comportement de IEEE_DIVIDE est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour IEEE_DIVIDE

Le tableau suivant répertorie les cas particuliers pour IEEE_DIVIDE.

Type de données du numérateur (X)	Type de données du dénominateur (Y)	Valeur du résultat
Tout sauf 0	0	+/-inf
0	0	NaN
0	NaN	NaN
NaN	0	NaN
+/-inf	+/-inf	NaN

RAND

RAND()

Description

Génère une valeur pseudo-aléatoire de type FLOAT64 dans la plage [0, 1), 0 étant inclus et 1 étant exclu.

SQRT

SQRT(X)

Description

Calcule la racine carrée de X. Cette fonction génère une erreur si X est inférieur à 0. Renvoie +inf si X est +inf.

POW

POW(X, Y)

Description

Renvoie la valeur de X élevée à la puissance Y. Si le résultat est insuffisant et qu'il n'est pas représentable, la fonction renvoie une valeur "zéro". Elle renvoie une erreur si l'une des conditions suivantes est vraie :

• X est une valeur finie inférieure à 0 et Y n'est pas un entier.
• X est égal à 0 et Y est une valeur finie inférieure à 0.

Le comportement de POW() est illustré plus en détail dans le tableau ci-dessous.

POWER

POWER(X, Y)

Description

Synonyme de POW().

Cas particuliers pour POW(X, Y) et POWER(X, Y)

Voici des cas particuliers pour POW(X, Y) et POWER(X, Y).

X	Y	POW(X, Y) ou POWER(X, Y)
1.0	Toute valeur, y compris NaN	1.0
tout, y compris NaN	0	1.0
-1.0	+/-inf	1.0
ABS(X) < 1	-inf	+inf
ABS(X) > 1	-inf	0
ABS(X) < 1	+inf	0
ABS(X) > 1	+inf	+inf
-inf	Y < 0	0
-inf	Y > 0	-inf si Y est un entier impair, +inf dans le cas contraire
+inf	Y < 0	0
+inf	Y > 0	+inf

EXP

EXP(X)

Description

Calcule e à la puissance X. Cette fonction est également appelée "fonction exponentielle naturelle". Si le résultat est insuffisant, cette fonction renvoie un zéro. Elle génère une erreur si le résultat déborde. Si X est égal à +/-inf, cette fonction renvoie +inf ou 0.

LN

LN(X)

Description

Calcule le logarithme népérien de X. Cette fonction génère une erreur si X est inférieur ou égal à zéro. Si X est égal à +inf, cette fonction renvoie +inf.

LOG

LOG(X [, Y])

Description

Si seul X est présent, LOG est un synonyme de LN. Si Y est également présent, LOG calcule le logarithme de X en base Y. Cette fonction génère une erreur dans les cas suivants :

• X est inférieur ou égal à zéro.
• Y est égal à 1,0.
• Y est inférieur ou égal à zéro.

Le comportement de LOG(X, Y) est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour LOG(X, Y)

X	Y	LOG(X, Y)
-inf	Toute valeur	NaN
Toute valeur	+inf	NaN
+inf	0,0 Y < 1,0	-inf
+inf	Y > 1,0	+inf

LOG10

LOG10(X)

Description

Identique à LOG, mais calcule le logarithme en base 10.

GREATEST

GREATEST(X1,...,XN)

Description

Renvoie NULL si l'une des entrées est NULL. Autrement, la fonction renvoie NaN si l'une des entrées est NaN. Sinon, elle renvoie la plus grande valeur parmi "X1, ..., XN" (identifiée à l'aide de la comparaison "<").

LEAST

LEAST(X1,...,XN)

Description

Renvoie NULL si l'une des entrées est NULL. Cette fonction renvoie NaN si l'une des entrées est NaN. Sinon, elle renvoie la plus petite valeur parmi "X1, ..., XN" (identifiée à l'aide de la comparaison ">").

DIV

DIV(X, Y)

Description

Renvoie le résultat de la division d'un entier X par un entier Y. Une division par zéro renvoie une erreur. Une division par -1 peut entraîner un débordement. Reportez-vous au tableau ci-dessous pour découvrir les types de résultats possibles.

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Description

Équivaut à l'opérateur de division (/), mais renvoie NULL si une erreur se produit, par exemple une erreur de division par zéro.

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Description

Équivaut à l'opérateur de multiplication (*), mais renvoie NULL si un débordement se produit.

SAFE_NEGATE

SAFE_NEGATE(X)

Description

Équivaut à l'opérateur unaire moins (-), mais renvoie NULL en cas de débordement.

SAFE_ADD

SAFE_ADD(X, Y)

Description

Équivaut à l'opérateur d'addition (+), mais renvoie NULL en cas de débordement.

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Description

Équivaut à l'opérateur de soustraction (-), mais renvoie NULL en cas de débordement.

MOD

MOD(X, Y)

Description

Fonction modulo : renvoie le reste de la division de X par Y. La valeur renvoyée a le même signe que X. Une erreur est générée si Y est égal à 0. Reportez-vous au tableau ci-dessous pour découvrir les types de résultats possibles.

ROUND

ROUND(X [, N])

Description

Si seul X est présent, ROUND arrondit X au nombre entier le plus proche. Si N est présent, ROUND arrondit X à N décimales après la virgule. Si N est négatif, ROUND arrondit les chiffres à gauche de la virgule. Cette fonction arrondit les cas à mi-chemin à la valeur la plus éloignée de zéro. Elle génère une erreur en cas de débordement.

TRUNC

TRUNC(X [, N])

Description

Si seul X est présent, TRUNC arrondit X au nombre entier le plus proche dont la valeur absolue n'est pas supérieure à celle de X. Si N est également présent, la fonction TRUNC se comporte comme ROUND(X, N), mais elle arrondit toujours en direction de zéro et ne déborde jamais.

CEIL

CEIL(X)

Description

Renvoie la plus petite valeur intégrale (avec le type FLOAT64) parmi celles qui ne sont pas inférieures à X.

CEILING

CEILING(X)

Description

Synonyme de CEIL(X)

FLOOR

FLOOR(X)

Description

Renvoie la plus grande valeur intégrale (avec le type FLOAT64) parmi celles qui ne sont pas supérieures à X.

Exemple de comportement de la fonction d'arrondi

Exemple de comportement des fonctions d'arrondi dans BigQuery :

Entrée "X"	ROUND(X)	TRUNC(X)	CEIL(X)	FLOOR(X)
2.0	2.0	2.0	2.0	2.0
2.3	2.0	2.0	3.0	2.0
2.8	3.0	2.0	3.0	2.0
2.5	3.0	2.0	3.0	2.0
-2.3	-2.0	-2.0	-2.0	-3.0
-2.8	-3.0	-2.0	-2.0	-3.0
-2.5	-3.0	-2.0	-2.0	-3.0
0	0	0	0	0
+/-inf	+/-inf	+/-inf	+/-inf	+/-inf
NaN	NaN	NaN	NaN	NaN

COS

COS(X)

Description

Calcule le cosinus de X où X est spécifié en radians. Cette fonction n'échoue jamais.

COSH

COSH(X)

Description

Calcule le cosinus hyperbolique de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

ACOS

ACOS(X)

Description

Calcule la valeur principale du cosinus inverse de X. La valeur renvoyée est comprise dans l'intervalle [0, π]. Cette fonction génère une erreur si X se situe en dehors de la plage [-1, 1].

ACOSH

ACOSH(X)

Description

Calcule le cosinus hyperbolique inverse de X. Cette fonction génère une erreur si X est une valeur finie inférieure à 1.

SIN

SIN(X)

Description

Calcule le sinus de X où X est spécifié en radians. Cette fonction n'échoue jamais.

SINH

SINH(X)

Description

Calcule le sinus hyperbolique de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

ASIN

ASIN(X)

Description

Calcule la valeur principale de l'arc sinus de X. La valeur renvoyée est comprise dans la plage [-π/2, π/2]. Cette fonction génère une erreur si X se situe en dehors de la plage [-1, 1].

ASINH

ASINH(X)

Description

Calcule le sinus hyperbolique inverse de X. Cette fonction n'échoue pas.

TAN

TAN(X)

Description

Calcule la tangente de X où X est spécifié en radians. Cette fonction génère une erreur en cas de débordement.

TANH

TANH(X)

Description

Calcule la tangente hyperbolique de X où X est spécifié en radians. Cette fonction n'échoue pas.

ATAN

ATAN(X)

Description

Calcule la valeur principale de l'arc tangente de X. La valeur renvoyée est comprise dans l'intervalle [-π/2, π/2]. Cette fonction n'échoue pas.

ATANH

ATANH(X)

Description

Calcule la tangente hyperbolique inverse de X. Génère une erreur si X se situe en dehors de la plage [-1, 1].

ATAN2

ATAN2(Y, X)

Description

Calcule la valeur principale de la tangente inverse de Y/X en utilisant les signes des deux arguments pour déterminer le quadrant. La valeur renvoyée se situe dans la plage [-π,π]. Le comportement de cette fonction est illustré plus en détail dans le tableau ci-dessous.

Cas particuliers pour ATAN2()

Y	X	ATAN2(Y, X)
NaN	Toute valeur	NaN
Toute valeur	NaN	NaN
0	0	0, π ou -π en fonction du signe de X et Y
Valeur finie	-inf	π ou -π en fonction du signe de Y
Valeur finie	+inf	0
+/-inf	Valeur finie	π/2 ou -π/2 en fonction du signe de Y
+/-inf	-inf	¾π ou -¾π en fonction du signe de Y
+/-inf	+inf	π/4 ou -π/4 en fonction du signe de Y

Cas particuliers pour les fonctions d'arrondi trigonométriques et hyperboliques

X	COS(X)	COSH(X)	ACOS(X)	ACOSH(X)	SIN(X)	SINH(X)	ASIN(X)	ASINH(X)	TAN(X)	TANH(X)	ATAN(X)	ATANH(X)
+/-inf	NaN	=+inf	NaN	=+inf	NaN	=+inf	NaN	=+inf	NaN	=+1.0	π/2	NaN
-inf	NaN	=+inf	NaN	NaN	NaN	-inf	NaN	-inf	NaN	-1.0	-π/2	NaN
NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN

Fonctions de navigation

Les sections suivantes décrivent les fonctions de navigation acceptées par BigQuery. Ces fonctions sont un sous-ensemble des fonctions analytiques. Pour plus d'informations sur le fonctionnement des fonctions analytiques, consultez la page Concepts de fonction analytique. Pour en savoir plus sur le fonctionnement des fonctions de navigation, consultez la page Concepts de fonction de navigation.

FIRST_VALUE

FIRST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

Description

Renvoie la valeur de value_expression pour la première ligne du cadre de fenêtrage actuel.

Cette fonction inclut les valeurs NULL dans le calcul sauf si IGNORE NULLS est présent. Si IGNORE NULLS est présent, la fonction exclut les valeurs NULL du calcul.

Types d'arguments acceptés

value_expression peut correspondre à n'importe quel type de données qu'une expression peut renvoyer.

Type de données renvoyé

ANY

Exemples

L'exemple suivant calcule le meilleur temps pour chaque division.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  TIMESTAMP_DIFF(finish_time, fastest_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  FIRST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS fastest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | fastest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 0                |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 436              |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 891              |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 956              |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 1109             |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 0                |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 426              |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 691              |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 733              |
+-----------------+-------------+----------+--------------+------------------+

LAST_VALUE

LAST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

Description

Renvoie la valeur de value_expression pour la dernière ligne du cadre de fenêtrage actuel.

Cette fonction inclut les valeurs NULL dans le calcul sauf si IGNORE NULLS est présent. Si IGNORE NULLS est présent, la fonction exclut les valeurs NULL du calcul.

Types d'arguments acceptés

value_expression peut correspondre à n'importe quel type de données qu'une expression peut renvoyer.

Type de données renvoyé

ANY

Exemples

L'exemple suivant calcule le temps le moins bon pour chaque division.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', slowest_time) AS slowest_time,
  TIMESTAMP_DIFF(slowest_time, finish_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  LAST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS slowest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | slowest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 03:10:14     | 1109             |
| Nikki Leith     | 02:59:01    | F30-34   | 03:10:14     | 673              |
| Jen Edwards     | 03:06:36    | F30-34   | 03:10:14     | 218              |
| Meghan Lederer  | 03:07:41    | F30-34   | 03:10:14     | 153              |
| Lauren Reasoner | 03:10:14    | F30-34   | 03:10:14     | 0                |
| Lisa Stelzner   | 02:54:11    | F35-39   | 03:06:24     | 733              |
| Lauren Matthews | 03:01:17    | F35-39   | 03:06:24     | 307              |
| Desiree Berry   | 03:05:42    | F35-39   | 03:06:24     | 42               |
| Suzy Slane      | 03:06:24    | F35-39   | 03:06:24     | 0                |
+-----------------+-------------+----------+--------------+------------------+

NTH_VALUE

NTH_VALUE (value_expression, constant_integer_expression [{RESPECT | IGNORE} NULLS])

Description

Renvoie la valeur de value_expression à la nième ligne du cadre de fenêtrage actuel, où "nième" est défini par constant_integer_expression. Renvoie NULL s'il n'y a aucune ligne de ce type.

Cette fonction inclut les valeurs NULL dans le calcul sauf si IGNORE NULLS est présent. Si IGNORE NULLS est présent, la fonction exclut les valeurs NULL du calcul.

Types d'arguments acceptés

• value_expression peut correspondre à n'importe quel type de données pouvant être renvoyé à partir d'une expression.
• constant_integer_expression peut correspondre à n'importe quelle expression constante qui renvoie un entier.

Type de données renvoyé

ANY

Exemples

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  FORMAT_TIMESTAMP('%X', second_fastest) AS second_fastest
FROM (
  SELECT name,
  finish_time,
  division,finishers,
  FIRST_VALUE(finish_time)
    OVER w1 AS fastest_time,
  NTH_VALUE(finish_time, 2)
    OVER w1 as second_fastest
  FROM finishers
  WINDOW w1 AS (
    PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING));

+-----------------+-------------+----------+--------------+----------------+
| name            | finish_time | division | fastest_time | second_fastest |
+-----------------+-------------+----------+--------------+----------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | NULL           |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 02:59:01       |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 02:59:01       |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 02:59:01       |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 02:59:01       |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 02:59:01       |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 03:01:17       |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 03:01:17       |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 03:01:17       |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 03:01:17       |
+-----------------+-------------+----------+--------------+----------------+

LEAD

LEAD (value_expression[, offset [, default_expression]])

Description

Renvoie la valeur de value_expression sur une ligne suivante. La modification de la valeur offset change la ligne suivante qui est renvoyée. La valeur par défaut, 1, indique la ligne immédiatement suivante dans le cadre de fenêtrage. Une erreur se produit si offset est défini sur une valeur NULL ou négative.

Le paramètre default_expression facultatif est utilisé s'il n'y a pas de ligne dans le cadre de fenêtrage au décalage spécifié. Cette expression doit être constante, et son type doit pouvoir être converti implicitement (par coercition) dans le type de value_expression. Si aucune valeur n'est spécifiée, default_expression est défini par défaut sur NULL.

Types d'arguments acceptés

• value_expression peut correspondre à n'importe quel type de données pouvant être renvoyé à partir d'une expression.
• offset doit être un paramètre ou un littéral entier non négatif.
• default_expression doit être compatible avec le type de l'expression de valeur.

Type de données renvoyé

ANY

Exemples

L'exemple suivant illustre une utilisation de base de la fonction LEAD.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS followed_by
FROM finishers;

+-----------------+-------------+----------+-----------------+
| name            | finish_time | division | followed_by     |
+-----------------+-------------+----------+-----------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL            |
| Sophia Liu      | 02:51:45    | F30-34   | Nikki Leith     |
| Nikki Leith     | 02:59:01    | F30-34   | Jen Edwards     |
| Jen Edwards     | 03:06:36    | F30-34   | Meghan Lederer  |
| Meghan Lederer  | 03:07:41    | F30-34   | Lauren Reasoner |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL            |
| Lisa Stelzner   | 02:54:11    | F35-39   | Lauren Matthews |
| Lauren Matthews | 03:01:17    | F35-39   | Desiree Berry   |
| Desiree Berry   | 03:05:42    | F35-39   | Suzy Slane      |
| Suzy Slane      | 03:06:24    | F35-39   | NULL            |
+-----------------+-------------+----------+-----------------+

L'exemple suivant utilise le paramètre offset facultatif.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | NULL             |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL             |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | NULL             |
| Suzy Slane      | 03:06:24    | F35-39   | NULL             |
+-----------------+-------------+----------+------------------+

L'exemple suivant remplace les valeurs NULL par une valeur par défaut.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody           |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | Nobody           |
| Lauren Reasoner | 03:10:14    | F30-34   | Nobody           |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | Nobody           |
| Suzy Slane      | 03:06:24    | F35-39   | Nobody           |
+-----------------+-------------+----------+------------------+

LAG

LAG (value_expression[, offset [, default_expression]])

Description

Renvoie la valeur de value_expression sur une ligne précédente. La modification de la valeur offset change la ligne précédente qui est renvoyée. La valeur par défaut, 1, indique la ligne immédiatement précédente dans le cadre de fenêtrage. Une erreur se produit si offset est défini sur une valeur NULL ou négative.

Le paramètre default_expression facultatif est utilisé s'il n'y a pas de ligne dans le cadre de fenêtrage au décalage spécifié. Cette expression doit être constante, et son type doit pouvoir être converti implicitement (par coercition) dans le type de value_expression. Si aucune valeur n'est spécifiée, default_expression est défini par défaut sur NULL.

Types d'arguments acceptés

• value_expression peut correspondre à n'importe quel type de données pouvant être renvoyé à partir d'une expression.
• offset doit être un paramètre ou un littéral entier non négatif.
• default_expression doit être compatible avec le type de l'expression de valeur.

Type de données renvoyé

ANY

Exemples

L'exemple suivant illustre une utilisation de base de la fonction LAG.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS preceding_runner
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | preceding_runner |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | NULL             |
| Nikki Leith     | 02:59:01    | F30-34   | Sophia Liu       |
| Jen Edwards     | 03:06:36    | F30-34   | Nikki Leith      |
| Meghan Lederer  | 03:07:41    | F30-34   | Jen Edwards      |
| Lauren Reasoner | 03:10:14    | F30-34   | Meghan Lederer   |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL             |
| Lauren Matthews | 03:01:17    | F35-39   | Lisa Stelzner    |
| Desiree Berry   | 03:05:42    | F35-39   | Lauren Matthews  |
| Suzy Slane      | 03:06:24    | F35-39   | Desiree Berry    |
+-----------------+-------------+----------+------------------+

L'exemple suivant utilise le paramètre offset facultatif.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL              |
| Sophia Liu      | 02:51:45    | F30-34   | NULL              |
| Nikki Leith     | 02:59:01    | F30-34   | NULL              |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL              |
| Lauren Matthews | 03:01:17    | F35-39   | NULL              |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

L'exemple suivant remplace les valeurs NULL par une valeur par défaut.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody            |
| Sophia Liu      | 02:51:45    | F30-34   | Nobody            |
| Nikki Leith     | 02:59:01    | F30-34   | Nobody            |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | Nobody            |
| Lauren Matthews | 03:01:17    | F35-39   | Nobody            |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

PERCENTILE_CONT

PERCENTILE_CONT (value_expression, percentile [{RESPECT | IGNORE} NULLS])

Description

Calcule la valeur de centile spécifiée pour "value_expression", avec une interpolation linéaire.

Cette fonction ignore les valeurs NULL en cas d'absence de RESPECT NULLS. Si RESPECT NULLS est présent :

• Une interpolation entre deux valeurs NULL renvoie NULL.
• Une interpolation entre une valeur NULL et une valeur non NULL renvoie la valeur non NULL.

Types d'arguments acceptés

• value_expression est une expression numérique.
• percentile est un littéral de type DOUBLE compris dans la plage [0, 1].

Type de données renvoyé

DOUBLE

Exemples

L'exemple suivant calcule la valeur de certains centiles à partir d'une colonne de valeurs, en ignorant les valeurs NULL.

SELECT
  PERCENTILE_CONT(x, 0) OVER() AS min,
  PERCENTILE_CONT(x, 0.01) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5) OVER() AS median,
  PERCENTILE_CONT(x, 0.9) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+-----+-------------+--------+--------------+-----+
| min | percentile1 | median | percentile90 | max |
+-----+-------------+--------+--------------+-----+
| 0   | 0.03        | 1.5    | 2.7          | 3   |
+-----+-------------+--------+--------------+-----+

L'exemple suivant calcule la valeur de certains centiles à partir d'une colonne de valeurs, en respectant les valeurs NULL.

SELECT
  PERCENTILE_CONT(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_CONT(x, 0.01 RESPECT NULLS) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_CONT(x, 0.9 RESPECT NULLS) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+------+-------------+--------+--------------+-----+
| min  | percentile1 | median | percentile90 | max |
+------+-------------+--------+--------------+-----+
| NULL | 0           | 1      | 2.6          | 3   |
+------+-------------+--------+--------------+-----+

PERCENTILE_DISC

PERCENTILE_DISC (value_expression, percentile [{RESPECT | IGNORE} NULLS])

Description

Calcule la valeur de centile spécifiée pour un paramètre value_expression discret. La valeur renvoyée est la première valeur triée de value_expression avec une distribution cumulative supérieure ou égale à la valeur percentile donnée.

Cette fonction ignore les valeurs NULL, sauf si RESPECT NULLS est présent.

Types d'arguments acceptés

• value_expression peut correspondre à n'importe quel type triable.
• percentile est un littéral de type DOUBLE compris dans la plage [0, 1].

Type de données renvoyé

ANY

Exemples

L'exemple suivant calcule la valeur de certains centiles à partir d'une colonne de valeurs, en ignorant les valeurs NULL.

SELECT
  x,
  PERCENTILE_DISC(x, 0) OVER() AS min,
  PERCENTILE_DISC(x, 0.5) OVER() AS median,
  PERCENTILE_DISC(x, 1) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+-----+--------+-----+
| x    | min | median | max |
+------+-----+--------+-----+
| c    | a   | b      | c   |
| NULL | a   | b      | c   |
| b    | a   | b      | c   |
| a    | a   | b      | c   |
+------+-----+--------+-----+

L'exemple suivant calcule la valeur de certains centiles à partir d'une colonne de valeurs, en respectant les valeurs NULL.

SELECT
  x,
  PERCENTILE_DISC(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_DISC(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_DISC(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+------+--------+-----+
| x    | min  | median | max |
+------+------+--------+-----+
| c    | NULL | a      | c   |
| NULL | NULL | a      | c   |
| b    | NULL | a      | c   |
| a    | NULL | a      | c   |
+------+------+--------+-----+

Fonctions analytiques d'agrégation

Les sections suivantes décrivent les fonctions analytiques d'agrégation acceptées par BigQuery. Pour plus d'informations sur le fonctionnement des fonctions analytiques, consultez la page Concepts de fonction analytique. Pour en savoir plus sur le fonctionnement des fonctions analytiques d'agrégation, consultez la page Concepts de fonction analytique d'agrégation.

BigQuery accepte les fonctions d'agrégation suivantes comme fonctions analytiques :

• ANY_VALUE

• ARRAY_AGG

• AVG

• CORR

• COUNT

• COUNTIF

• COVAR_POP

• COVAR_SAMP

• MAX

• MIN

• STDDEV_POP

• STDDEV_SAMP

• STRING_AGG

• SUM

• VAR_POP

• VAR_SAMP

Exigences de la clause OVER :

• PARTITION BY : facultatif.
• ORDER BY : facultatif. Non autorisé si DISTINCT est présent.
• window_frame_clause : facultatif. Non autorisé si DISTINCT est présent.

Exemple :

COUNT(*) OVER (ROWS UNBOUNDED PRECEDING)

SUM(DISTINCT x) OVER ()

Fonctions de hachage

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

Description

Calcule l'empreinte de l'entrée STRING ou BYTES à l'aide de la fonction Fingerprint64 de la bibliothèque Open Source FarmHash. Le résultat renvoyé par cette fonction pour une entrée spécifique ne change jamais.

Type renvoyé

INT64

Exemples

WITH example AS (
  SELECT 1 AS x, "foo" AS y, true AS z UNION ALL
  SELECT 2 AS x, "apple" AS y, false AS z UNION ALL
  SELECT 3 AS x, "" AS y, true AS z
)
SELECT
  *,
  FARM_FINGERPRINT(CONCAT(CAST(x AS STRING), y, CAST(z AS STRING)))
    AS row_fingerprint
FROM example;
+---+-------+-------+----------------------+
| x | y     | z     | row_fingerprint      |
+---+-------+-------+----------------------+
| 1 | foo   | true  | -1541654101129638711 |
| 2 | apple | false | 2794438866806483259  |
| 3 |       | true  | -4880158226897771312 |
+---+-------+-------+----------------------+

MD5

MD5(input)

Description

Calcule le hachage de l'entrée à l'aide de l'algorithme MD5. L'entrée peut être de type STRING ou BYTES. La version "STRING" traite l'entrée comme un tableau d'octets.

Cette fonction renvoie 16 octets.

Type renvoyé

BYTES

Exemple

SELECT MD5("Hello World") as md5;

+-------------------------------------------------+
| md5                                             |
+-------------------------------------------------+
| \xb1\n\x8d\xb1d\xe0uA\x05\xb7\xa9\x9b\xe7.?\xe5 |
+-------------------------------------------------+

SHA1

SHA1(input)

Description

Calcule le hachage de l'entrée à l'aide de l'algorithme SHA-1. L'entrée peut être de type STRING ou BYTES. La version "STRING" traite l'entrée comme un tableau d'octets.

Cette fonction renvoie 20 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA1("Hello World") as sha1;

+-----------------------------------------------------------+
| sha1                                                      |
+-----------------------------------------------------------+
| \nMU\xa8\xd7x\xe5\x02/\xabp\x19w\xc5\xd8@\xbb\xc4\x86\xd0 |
+-----------------------------------------------------------+

SHA256

SHA256(input)

Description

Calcule le hachage de l'entrée à l'aide de l'algorithme SHA-256. L'entrée peut être de type STRING ou BYTES. La version "STRING" traite l'entrée comme un tableau d'octets.

Cette fonction renvoie 32 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

Description

Calcule le hachage de l'entrée à l'aide de l'algorithme SHA-512. L'entrée peut être de type STRING ou BYTES. La version "STRING" traite l'entrée comme un tableau d'octets.

Cette fonction renvoie 64 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA512("Hello World") as sha512;

Fonctions de chaîne

Ces fonctions de chaîne acceptent deux types de valeurs différents : les types de données STRING et BYTES. Les valeurs de type STRING doivent être des chaînes UTF-8 correctement formées.

Les fonctions qui renvoient des valeurs de position, par exemple STRPOS, encodent ces positions au format INT64. La valeur 1 fait référence au premier caractère (ou octet), la valeur 2 au deuxième, et ainsi de suite. La valeur 0 indique un index non valide. Lorsque le traitement concerne des valeurs de type STRING, les positions renvoyées font référence aux positions des caractères.

Toutes les comparaisons de chaînes sont effectuées octet par octet, sans prise en compte de l'équivalence canonique Unicode.

BYTE_LENGTH

BYTE_LENGTH(value)

Description

Renvoie la longueur de la valeur en octets, qu'il s'agisse d'une valeur de type STRING ou BYTES.

Type renvoyé

INT64

Exemples

WITH example AS
  (SELECT "абвгд" AS characters, b"абвгд" AS bytes)

SELECT
  characters,
  BYTE_LENGTH(characters) AS string_example,
  bytes,
  BYTE_LENGTH(bytes) AS bytes_example
FROM example;

+------------+----------------+-------+---------------+
| characters | string_example | bytes | bytes_example |
+------------+----------------+-------+---------------+
| абвгд      | 10             | абвгд | 10            |
+------------+----------------+-------+---------------+

CHAR_LENGTH

CHAR_LENGTH(value)

Description

Renvoie la longueur de la STRING en caractères.

Type renvoyé

INT64

Exemples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHAR_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

Description

Synonyme de CHAR_LENGTH.

Type renvoyé

INT64

Exemples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHARACTER_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

Description

Accepte en entrée un tableau de points de code ASCII étendu (tableau de valeurs INT64) et renvoie une valeur de type BYTES.

Pour découvrir comment convertir une valeur de type BYTES en un tableau de points de code, consultez la section TO_CODE_POINTS.

Type renvoyé

BYTES

Exemples

Voici un exemple de base utilisant CODE_POINTS_TO_BYTES.

SELECT CODE_POINTS_TO_BYTES([65, 98, 67, 100]) AS bytes;

+-------+
| bytes |
+-------+
| AbCd  |
+-------+

L'exemple suivant utilise un algorithme ROT13 (décalage de 13 caractères pour chaque lettre) pour encoder une chaîne.

SELECT CODE_POINTS_TO_BYTES(ARRAY_AGG(
  (SELECT
      CASE
        WHEN chr BETWEEN b'a' and b'z'
          THEN TO_CODE_POINTS(b'a')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'a')[offset(0)],26)
        WHEN chr BETWEEN b'A' and b'Z'
          THEN TO_CODE_POINTS(b'A')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'A')[offset(0)],26)
        ELSE code
      END
   FROM
     (SELECT code, CODE_POINTS_TO_BYTES([code]) chr)
  ) ORDER BY OFFSET)) AS encoded_string
FROM UNNEST(TO_CODE_POINTS(b'Test String!')) code WITH OFFSET;

+----------------+
| encoded_string |
+----------------+
| Grfg Fgevat!   |
+----------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Description

Accepte en entrée un tableau de points de code Unicode (tableau de valeurs INT64) et renvoie une valeur de type STRING.

Pour découvrir comment convertir une valeur de type STRING en un tableau de points de code, consultez la section TO_CODE_POINTS.

Type renvoyé

STRING

Exemple

Voici un exemple de base utilisant CODE_POINTS_TO_STRING.

SELECT CODE_POINTS_TO_STRING([65, 255, 513, 1024]) AS string;

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+

L'exemple suivant calcule la fréquence des lettres dans un ensemble de mots.

WITH Words AS (
  SELECT word
  FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word
)
SELECT
  CODE_POINTS_TO_STRING([code_point]) AS letter,
  COUNT(*) AS letter_count
FROM Words,
  UNNEST(TO_CODE_POINTS(word)) AS code_point
GROUP BY 1
ORDER BY 2 DESC;

+--------+--------------+
| letter | letter_count |
+--------+--------------+
| a      | 5            |
| f      | 3            |
| r      | 2            |
| b      | 2            |
| l      | 2            |
| o      | 2            |
| g      | 1            |
| z      | 1            |
| e      | 1            |
| m      | 1            |
| i      | 1            |
+--------+--------------+

CONCAT

CONCAT(value1[, ...])

Description

Concatène une ou plusieurs valeurs en un seul résultat.

Type renvoyé

STRING ou BYTES

Exemples

With Employees AS
  (SELECT
    "John" AS first_name,
    "Doe" AS last_name
  UNION ALL
  SELECT
    "Jane" AS first_name,
    "Smith" AS last_name
  UNION ALL
  SELECT
    "Joe" AS first_name,
    "Jackson" AS last_name)

SELECT
  CONCAT(first_name, " ", last_name)
  AS full_name
FROM Employees;

+---------------------+
| full_name           |
+---------------------+
| John Doe            |
| Jane Smith          |
| Joe Jackson         |
+---------------------+

ENDS_WITH

ENDS_WITH(value1, value2)

Description

Prend en considération deux valeurs. Renvoie TRUE si la deuxième valeur est un suffixe de la première.

Type renvoyé

BOOL

Exemples

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  ENDS_WITH(item, "e") as example
FROM items;

+---------+
| example |
+---------+
|    True |
|   False |
|    True |
+---------+

FORMAT

BigQuery accepte une fonction FORMAT() pour la mise en forme des chaînes. Cette fonction est semblable à la fonction C printf. Elle génère une STRING à partir d'une chaîne de format contenant zéro, un ou plusieurs spécificateurs de format, ainsi qu'une liste (de longueur variable) d'arguments supplémentaires correspondant aux spécificateurs de format. Voici quelques exemples :

Description	Instruction	Résultat
Entier simple	format("%d", 10)	10
Entier avec espaces de remplissage à gauche	format("|%10d|", 11)	|           11|
Entier avec zéros de remplissage à gauche	format("+%010d+", 12)	+0000000012+
Entier avec virgules	format("%'d", 123456789)	123,456,789
STRING	format("-%s-", 'abcd efg')	-abcd efg-
FLOAT64	format("%f %E", 1.1, 2.2)	1.100000 2.200000E+00
DATE	format("%t", date "2015-09-01")	2015-09-01
TIMESTAMP	format("%t", timestamp "2015-09-01 12:34:56 America/Los_Angeles")	2015‑09‑01 19:34:56+00

La fonction FORMAT() ne fournit pas une mise en forme entièrement personnalisable pour tous les types et valeurs, ni une mise en forme prenant en compte les paramètres régionaux.

Si une mise en forme personnalisée est nécessaire pour un type, vous devez d'abord formater ce dernier à l'aide de fonctions spécifiques au type, telles que FORMAT_DATE() ou FORMAT_TIMESTAMP(). Par exemple :

FORMAT("date: %s!", FORMAT_DATE("%B %d, %Y", date '2015-01-02'));

Renvoie :

date: January 02, 2015!

Syntaxe

La syntaxe FORMAT() accepte en entrée une chaîne de format et une liste d'arguments de longueur variable, puis produit un résultat STRING :

FORMAT(<format_string>, ...)

L'expression <format_string> peut contenir zéro, un ou plusieurs spécificateurs de format. Chaque spécificateur de format est introduit par le symbole % et doit être mappé sur un ou plusieurs des arguments restants. Dans la plupart des cas, il s'agit d'un mappage de type "un à un", sauf lorsque le spécificateur * est présent. Par exemple, %.*i correspond à deux arguments : un argument de longueur et un argument de nombre entier signé. Si le nombre d'arguments liés aux spécificateurs de format n'est pas identique au nombre total d'arguments, une erreur se produit.

Spécificateurs de format acceptés

Le spécificateur de format de la fonction FORMAT() suit ce prototype :

%[flags][width][.precision]specifier

Les spécificateurs de format acceptés sont identifiés dans le tableau ci-après. Les extensions de printf() sont indiquées en italique.

Spécificateur	Description	Exemples	Types
d ou i	Entier décimal	392	INT64
o	Octal	610	INT64*
x	Entier hexadécimal	7fa	INT64*
X	Entier hexadécimal (majuscule)	7FA	INT64*
f	Virgule flottante décimale, minuscule	392.65 inf NaN	NUMERIC FLOAT64
F	Virgule flottante décimale, majuscule	392.65 inf NAN	NUMERIC FLOAT64
e	Notation scientifique (mantisse/exposant), minuscule	3.9265e+2 inf NaN	NUMERIC FLOAT64
E	Notation scientifique (mantisse/exposant), majuscule	3.9265E+2 inf NAN	NUMERIC FLOAT64
g	Utilisez la représentation la plus courte : %e ou %f	392.65	FLOAT64
G	Utilisez la représentation la plus courte : %E ou %F	392.65	FLOAT64
s	Chaîne de caractères	sample	STRING
t	Renvoie une chaîne imprimable représentant la valeur. Ce résultat est souvent semblable à celui de la conversion (cast) de l'argument au format STRING. Consultez la section %t ci-dessous.	sample 2014‑01‑01	<tous>
T	Génère une chaîne qui est une constante BigQuery valide, dont le type est semblable à celui de la valeur. Il peut contenir plus de caractères ou se présenter sous forme de chaîne. Consultez la section %T ci-dessous.	'sample' b'bytes sample' 1234 2.3 date '2014‑01‑01'	<tous>
%	'%%' produit un seul '%'	%	n/a

^* Les spécificateurs o, x et X génèrent une erreur si des valeurs négatives sont utilisées.

Le spécificateur de format peut éventuellement contenir les sous-spécificateurs identifiés ci-dessus dans le prototype de spécificateur.

Ces sous-spécificateurs doivent être conformes aux spécifications suivantes.

Indicateurs

Indicateurs	Description
-	Justifie à gauche dans la largeur de champ donnée ; la justification à droite est la valeur par défaut (consultez la rubrique relative aux sous-spécificateurs de largeur).
+	Force l'ajout d'un préfixe "plus" ou "moins" (signe + ou -) avant le résultat, même pour les nombres positifs. Par défaut, seuls les nombres négatifs sont précédés d'un signe -.
<espace>	Si aucun signe ne doit être écrit par la suite, un espace est inséré avant la valeur.
#	Utilisé avec les spécificateurs o, x ou X. Ajoute, selon le cas, un préfixe 0, 0x ou 0X avant la valeur pour les valeurs différentes de zéro.
0	Ajoute des zéros (0) au lieu d'espaces à gauche du nombre lorsque l'option de remplissage est spécifiée (consultez la rubrique relative aux sous-spécificateurs de largeur).
'	Formate les entiers en utilisant le caractère de regroupement approprié. Par exemple : FORMAT("%'d", 12345678) renvoie 12,345,678 FORMAT("%'x", 12345678) renvoie bc:614e FORMAT("%'o", 55555) renvoie 15,4403 Cet indicateur ne concerne que les valeurs décimales, hexadécimales et octales.

Les indicateurs peuvent être spécifiés dans n'importe quel ordre. Les indicateurs en double ne sont pas considérés comme des erreurs. Les indicateurs n'étant pas pertinents pour un type d'élément sont ignorés.

Largeur

Largeur	Description
<nombre>	Nombre minimum de caractères à imprimer. Si la valeur à imprimer ne contient pas le nombre minimum de caractères requis, le résultat est complété par des espaces. La valeur n'est pas tronquée, même si le résultat contient plus de caractères.
*	La largeur n'est pas spécifiée dans la chaîne de format, mais en tant qu'argument de valeur entière supplémentaire précédant l'argument à formater.

Précision

Précision	Description
.<nombre>	Pour les spécificateurs d'entiers (d, i, o, u, x et X) : la "précision" indique le nombre minimal de chiffres à écrire. Si la valeur à écrire comporte moins de chiffres, des zéros sont ajoutés à la fin du résultat. La valeur n'est pas tronquée, même si le résultat contient plus de chiffres. Une précision de 0 signifie qu'aucun caractère n'est écrit pour la valeur 0. Pour les spécificateurs a, A, e, E, f et F : il s'agit du nombre de chiffres à imprimer après la virgule (valeur par défaut : 6).
.*	La précision n'est pas spécifiée dans la chaîne de format, mais en tant qu'argument de valeur entière supplémentaire précédant l'argument à formater.

Comportement de %t et %T

Les spécificateurs de format %t et %T sont définis pour tous les types. La largeur, la précision et les indicateurs se comportent comme pour %s. La width correspond à la largeur minimale et la STRING est complétée pour atteindre cette taille. La precision est la largeur maximale du contenu à afficher, la STRING est tronquée à cette taille avant que le remplissage en largeur ne soit appliqué.

%t est toujours destiné à être une forme lisible de la valeur.

%T est toujours un littéral SQL valide d'un type similaire, tel qu'un type numérique plus large. Le littéral n'inclura pas de conversions (cast) ni de nom de type, sauf dans le cas particulier des valeurs à virgule flottante non finies.

La STRING est formatée comme suit :

Type	%t	%T
NULL de n'importe quel type	NULL	NULL
INT64	123	123
NUMERIC	123.0 (toujours avec .0)	NUMERIC "123.0"
FLOAT64	123.0 (toujours avec .0) 123e+10 inf -inf NaN	123.0 (toujours avec .0) 123e+10 CAST("inf" en tant que <type>) CAST ("- inf" en tant que <type>) CAST ("nan" en tant que <type>)
STRING	valeur de chaîne sans guillemets	Littéral de chaîne entre guillemets
BYTES	octets échappés sans guillemets par exemple, abc\x01\x02	Littéral d'octets entre guillemets par exemple, b"abc\x01\x02"
DATE	2011-02-03	DATE "2011-02-03"
TIMESTAMP	2011-02-03 04:05:06+00	TIMESTAMP "2011-02-03 04:05:06+00"
ARRAY	[valeur, valeur, ...] où les valeurs sont formatées avec %t	[valeur, valeur, ...] où les valeurs sont formatées avec %T
STRUCT	(valeur, valeur, …) où les champs sont formatés avec %t	(valeur, valeur, …) où les champs sont formatés avec %T Cas particuliers : Aucun champ : STRUCT() Un champ : STRUCT(valeur)

Conditions d'erreur

Si un spécificateur de format n'est pas valide, s'il n'est pas compatible avec le type d'argument associé, ou encore si un nombre erroné ou des arguments incorrects sont fournis, une erreur est générée. Par exemple, les expressions <format_string> ci-dessous ne sont pas valides :

FORMAT('%s', 1)

FORMAT('%')

Gérer des arguments NULL

Une chaîne de format NULL donne une STRING de sortie NULL. Tous les autres arguments sont ignorés dans ce cas.

La fonction produit généralement une valeur NULL si un argument NULL est présent. Par exemple, FORMAT('%i', <NULL expression>) génère une STRING de valeur NULL en sortie.

Il existe toutefois des exceptions : si le spécificateur de format est %t ou %T (tous deux produisent des STRING qui correspondent effectivement aux sémantiques de la valeur littérale et de CAST), une valeur NULL produit un résultat "NULL" (sans les guillemets) dans la STRING résultante. Par exemple, la fonction :

FORMAT('00-%t-00', <NULL expression>);

Renvoie :

00-NULL-00

Règles sémantiques supplémentaires

Les FLOAT64 peuvent avoir pour valeur +/-inf ou NaN. Lorsqu'un argument a l'une de ces valeurs, le résultat des spécificateurs de format %f, %F, %e, %E, %g, %G et %t est inf, -inf ou nan (ou le même terme en majuscules) selon le cas. Cette règle est cohérente avec la manière dont BigQuery convertit (cast) ces valeurs au format STRING. Pour %T, BigQuery renvoie des chaînes entre guillemets pour les valeurs FLOAT64 dont les représentations littérales ne peuvent être que des chaînes.

FROM_BASE32

FROM_BASE32(string_expr)

Description

Convertit l'entrée string_expr encodée en base32 au format BYTES. Pour convertir une valeur de type BYTES en valeur de type STRING encodée en base32, utilisez TO_BASE32.

Type renvoyé

BYTES

Exemple

SELECT FROM_BASE32('MFRGGZDF74======') AS byte_data;

+-----------+
| byte_data |
+-----------+
| abcde\xff |
+-----------+

FROM_BASE64

FROM_BASE64(string_expr)

Description

Convertit l'entrée string_expr encodée en base64 au format BYTES. Pour convertir une valeur BYTES en une STRING encodée en base64, utilisez TO_BASE64.

Type renvoyé

BYTES

Exemple

SELECT FROM_BASE64('3q2+7w==') AS byte_data;

+------------------+
| byte_data        |
+------------------+
| \xde\xad\xbe\xef |
+------------------+

FROM_HEX

FROM_HEX(string)

Description

Convertit une STRING encodée en hexadécimal au format BYTES. Renvoie une erreur si la valeur d'entrée de type STRING contient des caractères non compris dans la plage (0..9, A...F, a..f). La casse des lettres (majuscule/minuscule) n'a pas d'importance. Si l'entrée STRING contient un nombre impair de caractères, la fonction agit comme si l'entrée commençait par un 0 supplémentaire. Pour convertir une valeur BYTES en STRING encodée en hexadécimal, utilisez TO_HEX.

Type renvoyé

BYTES

Exemple

WITH Input AS (
  SELECT '00010203aaeeefff' AS hex_str UNION ALL
  SELECT '0AF' UNION ALL
  SELECT '666f6f626172'
)
SELECT hex_str, FROM_HEX(hex_str) AS bytes_str
FROM Input;
+------------------+----------------------------------+
| hex_str          | bytes_str                        |
+------------------+----------------------------------+
| 0AF              | \x00\xaf                         |
| 00010203aaeeefff | \x00\x01\x02\x03\xaa\xee\xef\xff |
| 666f6f626172     | foobar                           |
+------------------+----------------------------------+

LENGTH

LENGTH(value)

Description

Renvoie la longueur de la valeur. La valeur renvoyée correspond au nombre de caractères pour les arguments STRING et au nombre d'octets pour les arguments BYTES.

Type renvoyé

INT64

Exemples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  LENGTH(characters) AS string_example,
  LENGTH(CAST(characters AS BYTES)) AS bytes_example
FROM example;

+------------+----------------+---------------+
| characters | string_example | bytes_example |
+------------+----------------+---------------+
| абвгд      |              5 |            10 |
+------------+----------------+---------------+

LPAD

LPAD(original_value, return_length[, pattern])

Description

Renvoie une valeur composée de l'élément original_value et du préfixe pattern. Le paramètre return_length est une valeur INT64 qui indique la longueur de la valeur renvoyée. Si original_value est de type BYTES, return_length correspond au nombre d'octets. Si original_value est de type STRING, return_length correspond au nombre de caractères.

La valeur par défaut de pattern est un espace.

original_value et pattern doivent correspondre au même type de données.

Si return_length est inférieur ou égal à la longueur original_value, cette fonction renvoie la valeur original_value tronquée à la valeur de return_length. Par exemple, LPAD("hello world", 7); renvoie "hello w".

Si original_value, return_length ou pattern est défini sur NULL, cette fonction renvoie NULL.

Cette fonction renvoie une erreur si :

• return_length est négatif ;
• pattern est vide.

Type renvoyé

STRING ou BYTES

Exemples

SELECT t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);

t	len	LPAD
abc	5	"  abc"
abc	2	"ab"
例子	4	"  例子"

SELECT t, len, pattern, FORMAT("%T", LPAD(t, len, pattern)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);

t	len	format	LPAD
abc	8	def	"defdeabc"
abc	5	-	"--abc"
例子	5	中文	"中文中例子"

SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

t	len	LPAD
b"abc"	5	b"  abc"
b"abc"	2	b"ab"
b"\xab\xcd\xef"	4	b" \xab\xcd\xef"

SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", LPAD(t, len, pattern)) AS LPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);

t	len	format	LPAD
b"abc"	8	b"def"	b"defdeabc"
b"abc"	5	b"-"	b"--abc"
b"\xab\xcd\xef"	5	b"\x00"	b"\x00\x00\xab\xcd\xef"

LOWER

LOWER(value)

Description

Pour les arguments STRING, cette fonction renvoie la chaîne d'origine avec tous les caractères alphabétiques en minuscules. Le mappage entre minuscules et majuscules est effectué en fonction de la base de données de caractères Unicode, sans prise en compte des mappages spécifiques à la langue.

Les arguments BYTES sont quant à eux traités comme du texte ASCII et les octets supérieurs à 127 ne sont pas modifiés.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT
    "FOO" as item
  UNION ALL
  SELECT
    "BAR" as item
  UNION ALL
  SELECT
    "BAZ" as item)

SELECT
  LOWER(item) AS example
FROM items;

+---------+
| example |
+---------+
| foo     |
| bar     |
| baz     |
+---------+

LTRIM

LTRIM(value1[, value2])

Description

Identique à TRIM, mais ne supprime que les premiers caractères.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", LTRIM(item), "#") as example
FROM items;

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  LTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  LTRIM(item, "xyz") as example
FROM items;

+-----------+
| example   |
+-----------+
| applexxx  |
| bananayyy |
| orangezzz |
| pearxyz   |
+-----------+

NORMALIZE

NORMALIZE(value[, normalization_mode])

Description

Accepte en entrée une valeur de type STRING, value, et la renvoie sous forme de chaîne normalisée.

La normalisation permet de garantir que deux chaînes sont équivalentes. Elle est souvent utilisée dans le cas où deux chaînes génèrent le même résultat à l'écran, mais ont des points de code Unicode différents.

NORMALIZE accepte quatre modes de normalisation facultatifs.

Valeur	Nom	Description
NFC	Forme de normalisation avec composition canonique	Décompose et recompose les caractères par équivalence canonique.
NFKC	Forme de normalisation avec composition de compatibilité	Décompose les caractères par compatibilité, puis les recompose par équivalence canonique.
NFD	Forme de normalisation avec décomposition canonique	Décompose les caractères par équivalence canonique, puis plusieurs caractères de combinaison sont disposés dans un ordre spécifique.
NFKD	Forme de normalisation avec décomposition de compatibilité	Décompose les caractères par compatibilité, puis plusieurs caractères de combinaison sont disposés dans un ordre spécifique.

Le mode de normalisation par défaut est NFC.

Type renvoyé

STRING

Exemples

SELECT a, b, a = b as normalized
FROM (SELECT NORMALIZE('\u00ea') as a, NORMALIZE('\u0065\u0302') as b)
AS normalize_example;

+---+---+------------+
| a | b | normalized |
+---+---+------------+
| ê | ê | true       |
+---+---+------------+

L'exemple ci-dessous permet de normaliser différents caractères d'espacement.

WITH EquivalentNames AS (
  SELECT name
  FROM UNNEST([
      'Jane\u2004Doe',
      'John\u2004Smith',
      'Jane\u2005Doe',
      'Jane\u2006Doe',
      'John Smith']) AS name
)
SELECT
  NORMALIZE(name, NFKC) AS normalized_name,
  COUNT(*) AS name_count
FROM EquivalentNames
GROUP BY 1;

+-----------------+------------+
| normalized_name | name_count |
+-----------------+------------+
| John Smith      | 2          |
| Jane Doe        | 3          |
+-----------------+------------+

NORMALIZE_AND_CASEFOLD

NORMALIZE_AND_CASEFOLD(value[, normalization_mode])

Description

Accepte en entrée une valeur de type STRING, value, et effectue les mêmes actions que NORMALIZE, ainsi que le pli de casse pour les opérations non sensibles à la casse.

NORMALIZE_AND_CASEFOLD accepte quatre modes de normalisation facultatifs.

Valeur	Nom	Description
NFC	Forme de normalisation avec composition canonique	Décompose et recompose les caractères par équivalence canonique.
NFKC	Forme de normalisation avec composition de compatibilité	Décompose les caractères par compatibilité, puis les recompose par équivalence canonique.
NFD	Forme de normalisation avec décomposition canonique	Décompose les caractères par équivalence canonique, puis plusieurs caractères de combinaison sont disposés dans un ordre spécifique.
NFKD	Forme de normalisation avec décomposition de compatibilité	Décompose les caractères par compatibilité, puis plusieurs caractères de combinaison sont disposés dans un ordre spécifique.

Le mode de normalisation par défaut est NFC.

Type renvoyé

STRING

Exemple

WITH Strings AS (
  SELECT '\u2168' AS a, 'IX' AS b UNION ALL
  SELECT '\u0041\u030A', '\u00C5'
)
SELECT a, b,
  NORMALIZE_AND_CASEFOLD(a, NFD)=NORMALIZE_AND_CASEFOLD(b, NFD) AS nfd,
  NORMALIZE_AND_CASEFOLD(a, NFC)=NORMALIZE_AND_CASEFOLD(b, NFC) AS nfc,
  NORMALIZE_AND_CASEFOLD(a, NFKD)=NORMALIZE_AND_CASEFOLD(b, NFKD) AS nkfd,
  NORMALIZE_AND_CASEFOLD(a, NFKC)=NORMALIZE_AND_CASEFOLD(b, NFKC) AS nkfc
FROM Strings;

+---+----+-------+-------+------+------+
| a | b  | nfd   | nfc   | nkfd | nkfc |
+---+----+-------+-------+------+------+
| Ⅸ | IX | false | false | true | true |
| Å | Å  | true  | true  | true | true |
+---+----+-------+-------+------+------+

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regex)

Description

Renvoie TRUE si value est une correspondance partielle de l'expression régulière (regex).

Si l'argument regex n'est pas valide, la fonction renvoie une erreur.

Vous pouvez rechercher une correspondance complète en utilisant ^ (début du texte) et $ (fin du texte). En raison de la priorité des opérateurs d'expression régulière, il est recommandé d'utiliser des parenthèses pour tout élément compris entre ^ et $.

Remarque : La bibliothèque re2 permet d'utiliser des expressions régulières dans BigQuery. Consultez la documentation de cette bibliothèque pour en savoir plus sur la syntaxe d'expression régulière à utiliser.

Type renvoyé

BOOL

Exemples

SELECT
  email,
  REGEXP_CONTAINS(email, r"@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+") AS is_valid
FROM
  (SELECT
    ["[e-mail]", "[e-mail]", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| [e-mail] | true     |
| [e-mail] | true     |
| www.example.net | false    |
+-----------------+----------+

# Performs a full match, using ^ and $. Due to regular expression operator
# precedence, it is good practice to use parentheses around everything between ^
# and $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^([\w.+-]+@foo\.com|[\w.+-]+@bar\.org)$")
    AS valid_email_address,
  REGEXP_CONTAINS(email, r"^[\w.+-]+@foo\.com|[\w.+-]+@bar\.org$")
    AS without_parentheses
FROM
  (SELECT
    ["[e-mail]", "[e-mail]", "[e-mail]", "![e-mail]", "[e-mail]"]
    AS addresses),
  UNNEST(addresses) AS email;

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| [e-mail]      | true                | true                |
| [e-mail] | false               | true                |
| [e-mail]      | true                | true                |
| ![e-mail]     | false               | true                |
| [e-mail]      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

Description

Renvoie la première sous-chaîne de value qui correspond à l'expression régulière (regex). Renvoie NULL s'il n'y a pas de correspondance.

Si l'expression régulière comporte un groupe de capture, la fonction renvoie uniquement la sous-chaîne à laquelle correspond ce groupe de capture. Si l'expression ne contient pas de groupe de capture, la fonction renvoie l'ensemble de la sous-chaîne correspondante.

Renvoie une erreur si :

• l'expression régulière n'est pas valide ;
• l'expression régulière comporte plus d'un groupe de capture.

Remarque : La bibliothèque re2 permet d'utiliser des expressions régulières dans BigQuery. Consultez la documentation de cette bibliothèque pour en savoir plus sur la syntaxe d'expression régulière à utiliser.

Type renvoyé

STRING ou BYTES

Exemples

WITH email_addresses AS
  (SELECT "[e-mail]" as email
  UNION ALL
  SELECT "[e-mail]" as email
  UNION ALL
  SELECT "[e-mail]" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+")
  AS user_name
FROM email_addresses;

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+

WITH email_addresses AS
  (SELECT "[e-mail]" as email
  UNION ALL
  SELECT "[e-mail]" as email
  UNION ALL
  SELECT "[e-mail]" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.([a-zA-Z0-9-.]+$)")
  AS top_level_domain
FROM email_addresses;

+------------------+
| top_level_domain |
+------------------+
| com              |
| org              |
| net              |
+------------------+

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regex)

Description

Renvoie un tableau contenant toutes les sous-chaînes de value qui correspondent à l'expression régulière (regex).

La fonction REGEXP_EXTRACT_ALL ne renvoie que des correspondances qui ne se chevauchent pas. Par exemple, si vous utilisez cette fonction pour extraire ana de banana, la fonction ne renvoie qu'une sous-chaîne, pas deux.

Remarque : La bibliothèque re2 permet d'utiliser des expressions régulières dans BigQuery. Consultez la documentation de cette bibliothèque pour en savoir plus sur la syntaxe d'expression régulière à utiliser.

Type renvoyé

Un tableau de valeurs STRING ou BYTES

Exemples

WITH code_markdown AS
  (SELECT "Try `function(x)` or `function(y)`" as code)

SELECT
  REGEXP_EXTRACT_ALL(code, "`(.+?)`") AS example
FROM code_markdown;

+----------------------------+
| example                    |
+----------------------------+
| [function(x), function(y)] |
+----------------------------+

REGEXP_REPLACE

REGEXP_REPLACE(value, regex, replacement)

Description

Renvoie une STRING dans laquelle toutes les sous-chaînes de value qui correspondent à l'expression régulière regex sont remplacées par l'argument replacement.

Vous pouvez utiliser des chiffres échappés par une barre oblique inverse (\1 à \9) dans l'argument replacement pour insérer du texte associé au groupe entre parenthèses correspondant dans le schéma regex. Utilisez \0 pour faire référence à l'ensemble du texte associé.

Remarque : Pour ajouter une barre oblique inverse dans votre expression régulière, vous devez d'abord l'échapper. Par exemple, SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1"); renvoie aXc.

La fonction REGEXP_REPLACE ne remplace que les correspondances qui ne se chevauchent pas. Par exemple, le fait de remplacer ana dans banana n'entraîne qu'un remplacement, pas deux.

Si l'argument regex n'est pas une expression régulière valide, cette fonction renvoie une erreur.

Remarque : La bibliothèque re2 permet d'utiliser des expressions régulières dans BigQuery. Consultez la documentation de cette bibliothèque pour en savoir plus sur la syntaxe d'expression régulière à utiliser.

Type renvoyé

STRING ou BYTES

Exemples

WITH markdown AS
  (SELECT "# Heading" as heading
  UNION ALL
  SELECT "# Another heading" as heading)

SELECT
  REGEXP_REPLACE(heading, r"^# ([a-zA-Z0-9\s]+$)", "<h1>\\1</h1>")
  AS html
FROM markdown;

+--------------------------+
| html                     |
+--------------------------+
| <h1>Heading</h1>         |
| <h1>Another heading</h1> |
+--------------------------+

REPLACE

REPLACE(original_value, from_value, to_value)

Description

Remplace toutes les occurrences de from_value par to_value dans original_value. Si from_value est vide, aucun remplacement n'est effectué.

Type renvoyé

STRING ou BYTES

Exemples

WITH desserts AS
  (SELECT "apple pie" as dessert
  UNION ALL
  SELECT "blackberry pie" as dessert
  UNION ALL
  SELECT "cherry pie" as dessert)

SELECT
  REPLACE (dessert, "pie", "cobbler") as example
FROM desserts;

+--------------------+
| example            |
+--------------------+
| apple cobbler      |
| blackberry cobbler |
| cherry cobbler     |
+--------------------+

REPEAT

REPEAT(original_value, repetitions)

Description

Renvoie une valeur constituée de l'élément original_value, ainsi que d'une ou de plusieurs répétitions de ce dernier. Le paramètre repetitions indique le nombre de répétitions de la valeur original_value. Renvoie "NULL" si l'une des valeurs (original_value ou repetitions) est "NULL".

Cette fonction renvoie une erreur si la valeur repetitions est négative.

Type renvoyé

STRING ou BYTES

Exemples

SELECT t, n, REPEAT(t, n) AS REPEAT FROM UNNEST([
  STRUCT('abc' AS t, 3 AS n),
  ('例子', 2),
  ('abc', null),
  (null, 3)
]);

t	n	REPEAT
abc	3	abcabcabc
例子	2	例子例子
abc	NULL	NULL
NULL	3	NULL

REVERSE

REVERSE(value)

Description

Renvoie l'inverse de la valeur STRING ou BYTES d'entrée.

Type renvoyé

STRING ou BYTES

Exemples

WITH example AS (
  SELECT "foo" AS sample_string, b"bar" AS sample_bytes UNION ALL
  SELECT "абвгд" AS sample_string, b"123" AS sample_bytes
)
SELECT
  sample_string,
  REVERSE(sample_string) AS reverse_string,
  sample_bytes,
  REVERSE(sample_bytes) AS reverse_bytes
FROM example;

+---------------+----------------+--------------+---------------+
| sample_string | reverse_string | sample_bytes | reverse_bytes |
+---------------+----------------+--------------+---------------+
| foo           | oof            | bar          | rab           |
| абвгд         | дгвба          | 123          | 321           |
+---------------+----------------+--------------+---------------+

RPAD

RPAD(original_value, return_length[, pattern])

Description

Renvoie une valeur composée de l'élément original_value et du suffixe pattern. Le paramètre return_length est une valeur INT64 qui indique la longueur de la valeur renvoyée. Si original_value est de type BYTES, return_length correspond au nombre d'octets. Si original_value est de type STRING, return_length correspond au nombre de caractères.

La valeur par défaut de pattern est un espace.

original_value et pattern doivent correspondre au même type de données.

Si return_length est inférieur ou égal à la longueur original_value, cette fonction renvoie la valeur original_value tronquée à la valeur de return_length. Par exemple, RPAD("hello world", 7); renvoie "hello w".

Si original_value, return_length ou pattern est défini sur NULL, cette fonction renvoie NULL.

Cette fonction renvoie une erreur si :

• return_length est négatif ;
• pattern est vide.

Type renvoyé

STRING ou BYTES

Exemples

SELECT t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);

t	len	RPAD
abc	5	"abc  "
abc	2	"ab"
例子	4	"例子  "

SELECT t, len, pattern, FORMAT("%T", RPAD(t, len, pattern)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);

t	len	format	RPAD
abc	8	def	"abcdefde"
abc	5	-	"abc--"
例子	5	中文	"例子中文中"

SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

t	len	RPAD
b"abc"	5	b"abc  "
b"abc"	2	b"ab"
b"\xab\xcd\xef"	4	b"\xab\xcd\xef "

SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", RPAD(t, len, pattern)) AS RPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);

t	len	format	RPAD
b"abc"	8	b"def"	b"abcdefde"
b"abc"	5	b"-"	b"abc--"
b"\xab\xcd\xef"	5	b"\x00"	b"\xab\xcd\xef\x00\x00"

RTRIM

RTRIM(value1[, value2])

Description

Identique à TRIM, mais ne supprime que les caractères de fin.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  RTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+

WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

SELECT
  RTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

Description

Convertit une séquence d'octets en chaîne. Tous les caractères UTF-8 non valides sont remplacés par le caractère de remplacement Unicode (U+FFFD).

Type renvoyé

STRING

Exemples

L'instruction suivante renvoie le caractère de remplacement Unicode (�).

SELECT SAFE_CONVERT_BYTES_TO_STRING(b'\xc2') as safe_convert;

SPLIT

SPLIT(value[, delimiter])

Description

Fractionne la valeur (value) à l'aide de l'argument delimiter.

Pour STRING, le délimiteur par défaut est la virgule (,).

Pour BYTES, vous devez spécifier un délimiteur.

Une requête SPLIT faisant référence à un délimiteur vide produit un tableau de caractères UTF-8 pour les valeurs STRING et un tableau de BYTES pour les valeurs BYTES.

Une requête SPLIT sur une STRING vide renvoie un tableau contenant une seule STRING vide.

Type renvoyé

Tableau de type STRING ou tableau de type BYTES

Exemples

WITH letters AS
  (SELECT "a b c d" as letter_group
  UNION ALL
  SELECT "e f g h" as letter_group
  UNION ALL
  SELECT "i j k l" as letter_group)

SELECT SPLIT(letter_group, " ") as example
FROM letters;

+----------------------+
| example              |
+----------------------+
| [a, b, c, d]         |
| [e, f, g, h]         |
| [i, j, k, l]         |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

Description

Prend en considération deux valeurs. Renvoie TRUE si la deuxième valeur est un préfixe de la première.

Type renvoyé

BOOL

Exemples

WITH items AS
  (SELECT "foo" as item
  UNION ALL
  SELECT "bar" as item
  UNION ALL
  SELECT "baz" as item)

SELECT
  STARTS_WITH(item, "b") as example
FROM items;

+---------+
| example |
+---------+
|   False |
|    True |
|    True |
+---------+

STRPOS

STRPOS(string, substring)

Description

Renvoie l'index de base 1 de la première occurrence de substring dans string. Renvoie 0 si substring est introuvable.

Type renvoyé

INT64

Exemples

WITH email_addresses AS
  (SELECT
    "[e-mail]" AS email_address
  UNION ALL
  SELECT
    "[e-mail]" AS email_address
  UNION ALL
  SELECT
    "[e-mail]" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

SELECT
  STRPOS(email_address, "@") AS example
FROM email_addresses;

+---------+
| example |
+---------+
|       4 |
|       7 |
|      10 |
|       0 |
+---------+

SUBSTR

SUBSTR(value, position[, length])

Description

Renvoie une sous-chaîne de la valeur fournie. L'argument position est un entier spécifiant la position de départ de la sous-chaîne et "position = 1" indique le premier caractère ou octet. L'argument length correspond au nombre maximal de caractères pour les arguments STRING ou au nombre maximal d'octets pour les arguments BYTES.

Si la valeur de position est négative, la fonction effectue le comptage à partir de la fin de value et "-1" indique le dernier caractère.

Si position est une position située au-delà de l'extrémité gauche de la STRING (position = 0 ou position < -LENGTH(value)), la fonction commence le comptage à partir de "position = 1". Si length dépasse la longueur de value, la fonction renvoie un nombre de caractères inférieur à length.

Si la valeur length est inférieure à 0, la fonction renvoie une erreur.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2) as example
FROM items;

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2, 2) as example
FROM items;

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, -2) as example
FROM items;

+---------+
| example |
+---------+
| le      |
| na      |
| ge      |
+---------+

TO_BASE32

TO_BASE32(bytes_expr)

Description

Convertit une séquence de valeurs de type BYTES en valeur de type STRING encodée en base32. Pour convertir une valeur de type STRING encodée en base32 en valeur de type BYTES, utilisez FROM_BASE32.

Type renvoyé

STRING

Exemple

SELECT TO_BASE32(b'abcde\xFF') AS base32_string;

+------------------+
| base32_string    |
+------------------+
| MFRGGZDF74====== |
+------------------+

TO_BASE64

TO_BASE64(bytes_expr)

Description

Convertit une séquence de BYTES en une STRING encodée en base64. Pour convertir une STRING encodée en base64 en BYTES, utilisez FROM_BASE64.

Type renvoyé

STRING

Exemple

SELECT TO_BASE64(b'\xde\xad\xbe\xef') AS base64_string;

+---------------+
| base64_string |
+---------------+
| 3q2+7w==      |
+---------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Description

Prend une valeur et renvoie un tableau de INT64.

• Si value est une STRING, chaque élément du tableau renvoyé représente un point de code. Chaque point de code est compris dans les plages [0, 0xD7FF] et [0xE000, 0x10FFFF].
• Si value est de type BYTES, chaque élément du tableau est une valeur de caractère ASCII étendu comprise dans l'intervalle [0, 255].

Pour découvrir comment convertir un tableau de points de code en STRING ou en BYTES, consultez les sections CODE_POINTS_TO_STRING ou CODE_POINTS_TO_BYTES.

Type renvoyé

Tableau de INT64

Exemples

L'exemple suivant récupère les points de code pour chaque élément dans un tableau de mots.

SELECT word, TO_CODE_POINTS(word) AS code_points
FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word;

+---------+------------------------------------+
| word    | code_points                        |
+---------+------------------------------------+
| foo     | [102, 111, 111]                    |
| bar     | [98, 97, 114]                      |
| baz     | [98, 97, 122]                      |
| giraffe | [103, 105, 114, 97, 102, 102, 101] |
| llama   | [108, 108, 97, 109, 97]            |
+---------+------------------------------------+

L'exemple suivant convertit des représentations entières de BYTES en des valeurs de caractères ASCII correspondantes.

SELECT word, TO_CODE_POINTS(word) AS bytes_value_as_integer
FROM UNNEST([b'\x00\x01\x10\xff', b'\x66\x6f\x6f']) AS word;

+------------------+------------------------+
| word             | bytes_value_as_integer |
+------------------+------------------------+
| \x00\x01\x10\xff | [0, 1, 16, 255]        |
| foo              | [102, 111, 111]        |
+------------------+------------------------+

L'exemple suivant montre la différence entre un résultat de type BYTES et un résultat de type STRING.

SELECT TO_CODE_POINTS(b'Ā') AS b_result, TO_CODE_POINTS('Ā') AS s_result;

+------------+----------+
| b_result   | s_result |
+------------+----------+
| [196, 128] | [256]    |
+------------+----------+

Notez que le caractère Ā est représenté sous la forme d'une séquence Unicode de deux octets. Par conséquent, la version BYTES de TO_CODE_POINTS renvoie un tableau avec deux éléments, tandis que la version STRING renvoie un tableau contenant un seul élément.

TO_HEX

TO_HEX(bytes)

Description

Convertit une séquence de BYTES en une STRING hexadécimale, où chaque octet est transformé en deux caractères hexadécimaux compris dans la plage (0..9, a..f). Pour convertir une STRING encodée en hexadécimal en BYTES, utilisez FROM_HEX.

Type renvoyé

STRING

Exemple

WITH Input AS (
  SELECT b'\x00\x01\x02\x03\xAA\xEE\xEF\xFF' AS byte_str UNION ALL
  SELECT b'foobar'
)
SELECT byte_str, TO_HEX(byte_str) AS hex_str
FROM Input;
+----------------------------------+------------------+
| byte_string                      | hex_string       |
+----------------------------------+------------------+
| foobar                           | 666f6f626172     |
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
+----------------------------------+------------------+

TRIM

TRIM(value1[, value2])

Description

Supprime tous les caractères de début et de fin qui correspondent à value2. Si value2 n'est pas spécifiée, tous les caractères d'espacement de début et de fin (tels que définis par la norme Unicode) sont supprimés. Si le premier argument est de type BYTES, le deuxième argument est obligatoire.

Si value2 contient plusieurs caractères ou octets, la fonction supprime tous les caractères ou octets de début et de fin contenus dans value2.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", TRIM(item), "#") as example
FROM items;

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  TRIM(item, "*") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  TRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

UPPER

UPPER(value)

Description

Pour les arguments STRING, cette fonction renvoie la chaîne d'origine avec tous les caractères alphabétiques en majuscules. Le mappage entre majuscules et minuscules est effectué en fonction de la base de données de caractères Unicode, sans prise en compte des mappages spécifiques à la langue.

Les arguments BYTES sont quant à eux traités comme du texte ASCII et les octets supérieurs à 127 ne sont pas modifiés.

Type renvoyé

STRING ou BYTES

Exemples

WITH items AS
  (SELECT
    "foo" as item
  UNION ALL
  SELECT
    "bar" as item
  UNION ALL
  SELECT
    "baz" as item)

SELECT
  UPPER(item) AS example
FROM items;

+---------+
| example |
+---------+
| FOO     |
| BAR     |
| BAZ     |
+---------+

Fonctions JSON

BigQuery accepte des fonctions permettant de récupérer des données stockées dans des chaînes au format JSON, ainsi que des fonctions permettant de transformer des données en chaînes au format JSON.

JSON_EXTRACT ou JSON_EXTRACT_SCALAR

JSON_EXTRACT(json_string_expr, json_path_string_literal) renvoie des valeurs JSON sous forme de chaîne (STRING).

JSON_EXTRACT_SCALAR(json_string_expr, json_path_string_literal) renvoie des valeurs JSON scalaires sous forme de chaîne (STRING).

Description

Le paramètre json_string_expr doit être une chaîne au format JSON. Par exemple :

{"class" : {"students" : [{"name" : "Jane"}]}}

Le paramètre json_path_string_literal identifie la ou les valeurs que vous souhaitez obtenir à partir de la chaîne au format JSON. Vous devez construire ce paramètre en utilisant le format JSONPath. Selon les règles applicables à ce format, ce paramètre doit commencer par un symbole $, qui fait référence au niveau le plus externe (le plus haut niveau) de la chaîne au format JSON. Vous pouvez identifier les valeurs enfants à l'aide de la notation par points ou de la notation entre crochets. Si l'objet JSON est un tableau, vous pouvez utiliser des crochets pour spécifier l'index de tableau.

JSONPath	Description
$	Objet ou élément racine
. ou []	Opérateur enfant
[]	Opérateur indice

Les deux fonctions renvoient NULL si le paramètre json_path_string_literal ne correspond pas à une valeur contenue dans json_string_expr. Si la valeur sélectionnée pour JSON_EXTRACT_SCALAR n'est pas scalaire, telle qu'un objet ou un tableau, la fonction renvoie NULL.

Si le format "JSONPath" n'est pas valide, ces fonctions génèrent une erreur.

Dans les cas où une clé JSON utilise des caractères JSONPath non valides, vous pouvez les échapper à l'aide de guillemets simples et de crochets, [' ']. Par exemple :

SELECT JSON_EXTRACT_SCALAR('{"a.b": {"c": "world"}}', "$['a.b'].c") as hello;

+-------+
| hello |
+-------+
| world |
+-------+

Exemples

SELECT JSON_EXTRACT(json_text, '$') AS json_text_string
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

La requête ci-dessus produit le résultat suivant :

+-----------------------------------------------------------+
| json_text_string                                          |
+-----------------------------------------------------------+
| {"class":{"students":[{"name":"Jane"}]}}                  |
| {"class":{"students":[]}}                                 |
| {"class":{"students":[{"name":"John"},{"name":"Jamie"}]}} |
+-----------------------------------------------------------+

SELECT JSON_EXTRACT(json_text, '$.class.students[0]') AS first_student
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

La requête ci-dessus produit le résultat suivant :

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+

SELECT JSON_EXTRACT(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

La requête ci-dessus produit le résultat suivant :

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| "Jamie"           |
+-------------------+

SELECT JSON_EXTRACT(json_text, "$.class['students']") AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

La requête ci-dessus produit le résultat suivant :

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+

SELECT JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

La requête ci-dessus produit le résultat suivant :

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

TO_JSON_STRING

TO_JSON_STRING(value[, pretty_print])

Description

Renvoie une représentation de value sous forme de chaîne JSON. Cette fonction accepte un paramètre pretty_print facultatif. Si pretty_print est présent, la valeur renvoyée est formatée afin d'offrir une meilleure lisibilité.

Type de données d'entrée	Valeur renvoyée
NULL de n'importe quel type	null
BOOL	true ou false.
INT64	Identique à CAST(value AS STRING) lorsque la valeur (value) est comprise dans la plage [-2^53, 2^53], qui correspond à la plage d'entiers pouvant être représentés sans perte sous forme de nombres à virgule flottante avec deux décimales IEEE 754. Les valeurs non comprises dans cette plage sont représentées sous forme de chaînes entre guillemets. Par exemple : -1 0 12345678901 9007199254740992 -9007199254740992 "9007199254740993" La valeur 9007199254740993 est supérieure à 2^53. Elle est donc représentée sous forme de chaîne entre guillemets.
NUMERIC	Identique à CAST(value AS STRING) lorsque la valeur (value) est comprise dans la plage [-2^53, 2^53] et qu'elle n'a pas de partie fractionnaire. Les valeurs non comprises dans cette plage sont représentées sous forme de chaînes entre guillemets. Par exemple : -1 0 "9007199254740993" "123.56"
FLOAT64	Les valeurs +/-inf et NaN sont représentées respectivement par Infinity, -Infinity et NaN. Sinon, ce type est identique à CAST(value AS STRING).
STRING	Valeur de chaîne entre guillemets, échappée conformément à la norme JSON. Plus précisément, ", \ et les caractères de contrôle de U+0000 à U+001F sont échappés.
BYTES	Valeur RFC 4648 entre guillemets, échappée en base64. Par exemple : "R29vZ2xl" est la représentation en base64 des octets b"Google"
DATE	Date entre guillemets. Par exemple : "2017-03-06"
TIMESTAMP	Date et heure ISO 8601 entre guillemets, où T sépare la date et l'heure, et où Zulu/UTC représente le fuseau horaire. Par exemple : "2017-03-06T12:34:56.789012Z"
DATETIME	Date et heure ISO 8601 entre guillemets, où T sépare la date et l'heure. Exemple : "2017-03-06T12:34:56.789012"
TIME	Heure ISO 8601 entre guillemets. Par exemple : "12:34:56.789012"
ARRAY	[elem1,elem2,...], où chaque valeur elem est formatée en fonction du type d'élément. Exemple avec mise en forme : [ elem1, elem2, ... ] Où chaque valeur "elem" est formatée en fonction du type d'élément. Un tableau vide est représenté par [].
STRUCT	{"field_name1":field_value1,"field_name2":field_value2,...} Où chaque valeur field_value est formatée en fonction de son type. Exemple avec mise en forme : { "field_name1": field_value1, "field_name2": field_value2, ... } Où chaque valeur field_value est formatée en fonction de son type. Si une valeur field_value est un tableau (ARRAY) ou une structure (STRUCT) non vide, les éléments sont mis en retrait au niveau approprié. Une structure vide est représentée par {}. Si les champs ont des noms en double, il est possible que JSON ne puisse pas être analysé. Les champs anonymes sont représentés par "". Si des champs UTF-8 ont des noms non valides, il est possible que JSON ne puisse pas être analysé. Les valeurs de chaîne sont échappées conformément à la norme JSON. Plus précisément, ", \ et les caractères de contrôle de U+0000 à U+001F sont échappés.

Type renvoyé

Représentation de la valeur sous forme de chaîne JSON.

Exemples

L'exemple suivant convertit les lignes d'une table au format JSON.

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  t,
  TO_JSON_STRING(t) AS json_row
FROM Input AS t;

La requête ci-dessus produit le résultat suivant :

+-----------------------------------+-------------------------------------------------------+
| t                                 | json_row                                              |
+-----------------------------------+-------------------------------------------------------+
| {[1, 2], foo, {true, 2017-04-05}} | {"x":[1,2],"y":"foo","s":{"a":true,"b":"2017-04-05"}} |
| {NULL, , {false, 0001-01-01}}     | {"x":null,"y":"","s":{"a":false,"b":"0001-01-01"}}    |
| {[3], bar, {NULL, 2016-12-05}}    | {"x":[3],"y":"bar","s":{"a":null,"b":"2016-12-05"}}   |
+-----------------------------------+-------------------------------------------------------+

L'exemple suivant convertit les lignes d'une table au format JSON et applique une mise en forme.

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  TO_JSON_STRING(t, true) AS json_row
FROM Input AS t;

La requête ci-dessus produit le résultat suivant :

+-----------------------+
| json_row              |
+-----------------------+
| {                     |
|  "x": [               |
|    1,                 |
|    2                  |
|  ],                   |
|  "y": "foo",          |
|  "s": {               |
|    "a": true,         |
|    "b": "2017-04-05"  |
|  }                    |
|}                      |
| {                     |
|  "x": null,           |
|  "y": "",             |
|  "s": {               |
|    "a": false,        |
|    "b": "0001-01-01"  |
|  }                    |
|}                      |
| {                     |
|  "x": [               |
|    3                  |
|  ],                   |
|  "y": "bar",          |
|  "s": {               |
|    "a": null,         |
|    "b": "2016-12-05"  |
|  }                    |
|}                      |
+-----------------------+

Fonctions de tableau

ARRAY

ARRAY(subquery)

Description

La fonction ARRAY renvoie un tableau (ARRAY) avec un élément pour chaque ligne dans une sous-requête.

Si la sous-requête (subquery) génère une table SQL, celle-ci doit comporter exactement une colonne. Chaque élément de l'ARRAY de sortie est la valeur de la colonne unique d'une ligne dans la table.

Si la sous-requête (subquery) génère une table de valeurs, chaque élément du tableau (ARRAY) de sortie correspond à la ligne entière de la table de valeurs.

Contraintes

• Les sous-requêtes ne sont pas ordonnées. Par conséquent, il n'existe aucune garantie que les éléments de l'ARRAY de sortie préservent l'ordre défini dans la table source pour la sous-requête. Toutefois, si la sous-requête inclut une clause ORDER BY, la fonction ARRAY renverra un tableau (ARRAY) qui respecte cette clause.
• Si la sous-requête renvoie plus d'une colonne, la fonction ARRAY renvoie une erreur.
• Si la sous-requête renvoie une colonne de type ARRAY ou des lignes de type ARRAY, la fonction ARRAY renvoie une erreur : BigQuery n'accepte pas les ARRAY avec des éléments de type ARRAY.
• Si la sous-requête ne renvoie aucune ligne, la fonction ARRAY renvoie un ARRAY vide. Elle ne renvoie jamais un ARRAY "NULL".

Type renvoyé

ARRAY

Exemples

SELECT ARRAY
  (SELECT 1 UNION ALL
   SELECT 2 UNION ALL
   SELECT 3) AS new_array;

+-----------+
| new_array |
+-----------+
| [1, 2, 3] |
+-----------+

Pour construire un tableau (ARRAY) à partir d'une sous-requête contenant plusieurs colonnes, modifiez la sous-requête pour qu'elle utilise SELECT AS STRUCT. Dorénavant, la fonction ARRAY renverra un ARRAY de STRUCT. L'ARRAY contiendra une STRUCT pour chaque ligne de la sous-requête, et chacune de ces STRUCT contiendra un champ pour chaque colonne de cette ligne.

SELECT
  ARRAY
    (SELECT AS STRUCT 1, 2, 3
     UNION ALL SELECT AS STRUCT 4, 5, 6) AS new_array;

+------------------------+
| new_array              |
+------------------------+
| [{1, 2, 3}, {4, 5, 6}] |
+------------------------+

De même, pour construire un ARRAY à partir d'une sous-requête contenant un ou plusieurs ARRAY, modifiez la sous-requête pour qu'elle utilise SELECT AS STRUCT.

SELECT ARRAY
  (SELECT AS STRUCT [1, 2, 3] UNION ALL
   SELECT AS STRUCT [4, 5, 6]) AS new_array;

+----------------------------+
| new_array                  |
+----------------------------+
| [{[1, 2, 3]}, {[4, 5, 6]}] |
+----------------------------+

ARRAY_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

Description

Concatène un ou plusieurs tableaux contenant le même type d'élément en un seul tableau.

Type renvoyé

ARRAY

Exemples

SELECT ARRAY_CONCAT([1, 2], [3, 4], [5, 6]) as count_to_six;

+--------------------------------------------------+
| count_to_six                                     |
+--------------------------------------------------+
| [1, 2, 3, 4, 5, 6]                               |
+--------------------------------------------------+

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Description

Renvoie la taille du tableau. Renvoie 0 pour un tableau vide. Renvoie NULL si array_expression a la valeur NULL.

Type renvoyé

INT64

Exemples

WITH items AS
  (SELECT ["apples", "bananas", NULL, "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

+---------------------------------+------+
| list                            | size |
+---------------------------------+------+
| [apples, bananas, NULL, grapes] | 4    |
| [coffee, tea, milk]             | 3    |
| [cake, pie]                     | 2    |
+---------------------------------+------+

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

Description

Renvoie une concaténation des éléments de array_expression sous la forme d'une STRING. La valeur de array_expression peut être un tableau contenant des types de données STRING ou BYTES.

Si le paramètre null_text est utilisé, la fonction remplace les valeurs NULL du tableau par la valeur de null_text.

Si le paramètre null_text n'est pas utilisé, la fonction omet la valeur NULL et son délimiteur précédent.

Exemples

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk              |
| cake--pie                      |
+--------------------------------+

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--', 'MISSING') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk              |
| cake--pie--MISSING             |
+--------------------------------+

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

Description

Renvoie un tableau de valeurs. Les paramètres start_expression et end_expression déterminent le début et la fin (inclus) du tableau.

La fonction GENERATE_ARRAY accepte les types de données suivants en entrée :

• INT64
• NUMERIC
• FLOAT64

Le paramètre step_expression détermine l'incrément utilisé pour générer les valeurs de tableau. La valeur par défaut pour ce paramètre est 1.

Cette fonction renvoie une erreur si step_expression est défini sur 0 ou si l'une des entrées est NaN.

Si l'un des arguments est NULL, la fonction renvoie un tableau NULL.

Type de données renvoyé

ARRAY

Exemples

La requête suivante renvoie un tableau d'entiers, avec un pas par défaut de 1.

SELECT GENERATE_ARRAY(1, 5) AS example_array;

+-----------------+
| example_array   |
+-----------------+
| [1, 2, 3, 4, 5] |
+-----------------+

La requête suivante renvoie un tableau utilisant une taille de pas spécifiée par l'utilisateur.

SELECT GENERATE_ARRAY(0, 10, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| [0, 3, 6, 9]  |
+---------------+

La requête suivante renvoie un tableau utilisant une valeur négative (-3) pour la taille de pas.

SELECT GENERATE_ARRAY(10, 0, -3) AS example_array;

+---------------+
| example_array |
+---------------+
| [10, 7, 4, 1] |
+---------------+

La requête suivante renvoie un tableau utilisant la même valeur pour start_expression et end_expression.

SELECT GENERATE_ARRAY(4, 4, 10) AS example_array;

+---------------+
| example_array |
+---------------+
| [4]           |
+---------------+

La requête suivante renvoie un tableau vide, étant donné que la valeur de start_expression est supérieure à celle de end_expression et que la valeur de step_expression est positive.

SELECT GENERATE_ARRAY(10, 0, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

La requête suivante renvoie un tableau NULL, car la valeur de end_expression est NULL.

SELECT GENERATE_ARRAY(5, NULL, 1) AS example_array;

+---------------+
| example_array |
+---------------+
| NULL          |
+---------------+

La requête suivante renvoie plusieurs tableaux.

SELECT GENERATE_ARRAY(start, 5) AS example_array
FROM UNNEST([3, 4, 5]) AS start;

+---------------+
| example_array |
+---------------+
| [3, 4, 5]     |
| [4, 5]        |
| [5]           |
+---------------+

GENERATE_DATE_ARRAY

GENERATE_DATE_ARRAY(start_date, end_date[, INTERVAL INT64_expr date_part])

Description

Renvoie un tableau de dates. Les paramètres start_date et end_date déterminent le début et la fin (inclus) du tableau.

La fonction GENERATE_DATE_ARRAY accepte les types de données suivants en entrée :

• Le paramètre start_date doit être une DATE.
• Le paramètre end_date doit être une DATE.
• Le paramètre INT64_expr doit être de type INT64.
• Le paramètre date_part doit être JOUR, SEMAINE, MOIS, TRIMESTRE ou ANNÉE.

Le paramètre INT64_expr détermine l'incrément utilisé pour générer les dates. La valeur par défaut pour ce paramètre est "1 jour".

Cette fonction renvoie une erreur si INT64_expr est défini sur 0.

Type de données renvoyé

Un tableau (ARRAY) contenant 0 ou plusieurs valeurs de type DATE.

Exemples

La requête suivante renvoie un tableau de dates, avec un pas par défaut de 1.

SELECT GENERATE_DATE_ARRAY('2016-10-05', '2016-10-08') AS example;

+--------------------------------------------------+
| example                                          |
+--------------------------------------------------+
| [2016-10-05, 2016-10-06, 2016-10-07, 2016-10-08] |
+--------------------------------------------------+

La requête suivante renvoie un tableau utilisant une taille de pas spécifiée par l'utilisateur.

SELECT GENERATE_DATE_ARRAY(
 '2016-10-05', '2016-10-09', INTERVAL 2 DAY) AS example;

+--------------------------------------+
| example                              |
+--------------------------------------+
| [2016-10-05, 2016-10-07, 2016-10-09] |
+--------------------------------------+

La requête suivante renvoie un tableau utilisant une valeur négative (-3) pour la taille de pas.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL -3 DAY) AS example;

+--------------------------+
| example                  |
+--------------------------+
| [2016-10-05, 2016-10-02] |
+--------------------------+

La requête suivante renvoie un tableau utilisant la même valeur pour start_date et end_date.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-05', INTERVAL 8 DAY) AS example;

+--------------+
| example      |
+--------------+
| [2016-10-05] |
+--------------+

La requête suivante renvoie un tableau vide, étant donné que la valeur de start_date est supérieure à celle de end_date et que la valeur de step est positive.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

La requête suivante renvoie un tableau NULL, car l'une de ses entrées est NULL.

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

La requête suivante renvoie un tableau de dates utilisant la valeur "2 MONTH" (2 mois) comme intervalle date_part :

SELECT GENERATE_DATE_ARRAY('2016-01-01',
  '2016-12-31', INTERVAL 2 MONTH) AS example;

+--------------------------------------------------------------------------+
| example                                                                  |
+--------------------------------------------------------------------------+
| [2016-01-01, 2016-03-01, 2016-05-01, 2016-07-01, 2016-09-01, 2016-11-01] |
+--------------------------------------------------------------------------+

La requête suivante utilise des dates non constantes pour générer un tableau.

WITH StartsAndEnds AS (
  SELECT DATE '2016-01-01' AS date_start, DATE '2016-01-31' AS date_end
  UNION ALL SELECT DATE "2016-04-01", DATE "2016-04-30"
  UNION ALL SELECT DATE "2016-07-01", DATE "2016-07-31"
  UNION ALL SELECT DATE "2016-10-01", DATE "2016-10-31"
)
SELECT GENERATE_DATE_ARRAY(date_start, date_end, INTERVAL 1 WEEK) AS date_range
FROM StartsAndEnds;

+--------------------------------------------------------------+
| date_range                                                   |
+--------------------------------------------------------------+
| [2016-01-01, 2016-01-08, 2016-01-15, 2016-01-22, 2016-01-29] |
| [2016-04-01, 2016-04-08, 2016-04-15, 2016-04-22, 2016-04-29] |
| [2016-07-01, 2016-07-08, 2016-07-15, 2016-07-22, 2016-07-29] |
| [2016-10-01, 2016-10-08, 2016-10-15, 2016-10-22, 2016-10-29] |
+--------------------------------------------------------------+

GENERATE_TIMESTAMP_ARRAY

GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp,
                         INTERVAL step_expression date_part)

Description

Renvoie un tableau (ARRAY) d'horodatages (TIMESTAMPS) séparés par un intervalle donné. Les paramètres start_timestamp et end_timestamp déterminent les limites inférieure et supérieure (incluses) de l'ARRAY.

La fonction GENERATE_TIMESTAMP_ARRAY accepte les types de données suivants en entrée :

• start_timestamp : TIMESTAMP
• end_timestamp : TIMESTAMP
• step_expression : INT64
• Les valeurs date_part autorisées sont :

MICROSECOND, MILLISECOND,

SECOND, MINUTE, HOUR, ou DAY.

Le paramètre step_expression détermine l'incrément utilisé pour générer des horodatages.

Type de données renvoyé

Un tableau (ARRAY) contenant zéro, une ou plusieurs valeurs TIMESTAMP.

Exemples

L'exemple suivant renvoie un tableau (ARRAY) d'horodatages (TIMESTAMP) à des intervalles d'une seconde.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:02',
                                INTERVAL 1 SECOND) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 00:00:01+00, 2016-10-05 00:00:02+00] |
+--------------------------------------------------------------------------+

L'exemple suivant renvoie un tableau (ARRAY) d'horodatages (TIMESTAMPS) avec un intervalle négatif.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-01 00:00:00',
                                INTERVAL -2 DAY) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-06 00:00:00+00, 2016-10-04 00:00:00+00, 2016-10-02 00:00:00+00] |
+--------------------------------------------------------------------------+

L'exemple suivant renvoie un tableau (ARRAY) comportant un seul élément, car start_timestamp et end_timestamp ont la même valeur.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+--------------------------+
| timestamp_array          |
+--------------------------+
| [2016-10-05 00:00:00+00] |
+--------------------------+

L'exemple suivant renvoie un tableau (ARRAY) vide, car start_timestamp est postérieur à end_timestamp.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| []              |
+-----------------+

L'exemple suivant renvoie un tableau (ARRAY) NULL, car l'une des entrées est NULL.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', NULL, INTERVAL 1 HOUR)
  AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| NULL            |
+-----------------+

L'exemple suivant génère des tableaux (ARRAY) d'horodatages (TIMESTAMP) à partir de colonnes contenant des valeurs pour start_timestamp et end_timestamp.

SELECT GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp, INTERVAL 1 HOUR)
  AS timestamp_array
FROM
  (SELECT
    TIMESTAMP '2016-10-05 00:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 02:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 12:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 14:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 23:59:00' AS start_timestamp,
    TIMESTAMP '2016-10-06 01:59:00' AS end_timestamp);

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 01:00:00+00, 2016-10-05 02:00:00+00] |
| [2016-10-05 12:00:00+00, 2016-10-05 13:00:00+00, 2016-10-05 14:00:00+00] |
| [2016-10-05 23:59:00+00, 2016-10-06 00:59:00+00, 2016-10-06 01:59:00+00] |
+--------------------------------------------------------------------------+

OFFSET et ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

Description

Accède à un élément ARRAY par position et renvoie l'élément. OFFSET signifie que la numérotation commence à zéro, ORDINAL signifie que la numérotation commence à un.

Un tableau donné peut être interprété comme étant en base 0 ou en base 1. Lorsque vous accédez à un élément de tableau, vous devez faire précéder la position du tableau par OFFSET ou ORDINAL selon le cas : aucun comportement n'est défini par défaut.

Les fonctions OFFSET et ORDINAL génèrent toutes deux une erreur si l'index est en dehors de la plage.

Type renvoyé

Varie en fonction des éléments du tableau (ARRAY).

Exemples

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM items;

+----------------------------------+-----------+-----------+
| list                             | offset_1  | ordinal_1 |
+----------------------------------+-----------+-----------+
| [apples, bananas, pears, grapes] | bananas   | apples    |
| [coffee, tea, milk]              | tea       | coffee    |
| [cake, pie]                      | pie       | cake      |
+----------------------------------+-----------+-----------+

ARRAY_REVERSE

ARRAY_REVERSE(value)

Description

Renvoie le tableau d'entrée, mais en présentant les éléments dans l'ordre inverse.

Type renvoyé

ARRAY

Exemples

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [4, 5] AS arr UNION ALL
  SELECT [] AS arr
)
SELECT
  arr,
  ARRAY_REVERSE(arr) AS reverse_arr
FROM example;

+-----------+-------------+
| arr       | reverse_arr |
+-----------+-------------+
| [1, 2, 3] | [3, 2, 1]   |
| [4, 5]    | [5, 4]      |
| []        | []          |
+-----------+-------------+

SAFE_OFFSET et SAFE_ORDINAL

array_expression[SAFE_OFFSET(zero_based_offset)]
array_expression[SAFE_ORDINAL(one_based_offset)]

Description

Identiques à OFFSET et à ORDINAL, sauf qu'elles renvoient NULL si l'index est en dehors de la plage.

Type renvoyé

Varie en fonction des éléments du tableau (ARRAY).

Exemple

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list,
  list[SAFE_OFFSET(3)] as safe_offset_3,
  list[SAFE_ORDINAL(3)] as safe_ordinal_3
FROM items;

+----------------------------------+---------------+----------------+
| list                             | safe_offset_3 | safe_ordinal_3 |
+----------------------------------+---------------+----------------+
| [apples, bananas, pears, grapes] | grapes        | pears          |
| [coffee, tea, milk]              | NULL          | milk           |
| [cake, pie]                      | NULL          | NULL           |
+----------------------------------+---------------+----------------+

Fonctions de date

BigQuery accepte les fonctions DATE ci-après.

CURRENT_DATE

CURRENT_DATE([time_zone])

Description

Renvoie la date actuelle pour le fuseau horaire spécifié ou celui par défaut.

Cette fonction accepte un paramètre time_zone facultatif. Ce paramètre est une chaîne représentant le fuseau horaire à utiliser. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (UTC) est utilisé. Pour en savoir plus sur la spécification d'un fuseau horaire, consultez la section Définition de fuseaux horaires.

Si l'évaluation du paramètre time_zone donne NULL, cette fonction renvoie NULL.

Type de données renvoyé

DATE

Exemple

SELECT CURRENT_DATE() as the_date;

+--------------+
| the_date     |
+--------------+
| 2016-12-25   |
+--------------+

EXTRACT

EXTRACT(part FROM date_expression)

Description

Renvoie la valeur correspondant à la partie de la date spécifiée. La valeur part doit être l'un des éléments suivants :

• DAYOFWEEK : renvoie des valeurs comprises dans la plage [1,7], le dimanche étant considéré comme le premier jour de la semaine.
• DAY
• DAYOFYEAR

• WEEK : renvoie le numéro de semaine de la date (compris dans la plage [0, 53]). Les semaines commencent le dimanche et les dates antérieures au premier dimanche de l'année correspondent à la semaine 0.

• WEEK(<WEEKDAY>) : renvoie le numéro de semaine de la date (compris dans la plage [0, 53]). Les semaines commencent un jour de semaine (WEEKDAY). Les dates antérieures au premier WEEKDAY de l'année correspondent à la semaine 0. Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.

• ISOWEEK : renvoie le numéro de semaine ISO 8601 de date_expression. Les ISOWEEK commencent le lundi. Les valeurs renvoyées sont comprises dans la plage [1, 53]. La première ISOWEEK de chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne.
• MONTH
• QUARTER : renvoie des valeurs comprises dans la plage [1,4].
• YEAR
• ISOYEAR : renvoie l'année à numérotation de semaine ISO 8601, qui correspond à l'année civile grégorienne contenant le jeudi de la semaine à laquelle date_expression appartient.

Type de données renvoyé

INT64

Exemples

Dans l'exemple suivant, EXTRACT renvoie une valeur correspondant à l'élément de temps DAY.

SELECT EXTRACT(DAY FROM DATE '2013-12-25') as the_day;

+---------+
| the_day |
+---------+
| 25      |
+---------+

Dans l'exemple suivant, EXTRACT renvoie des valeurs correspondant à différents éléments de temps d'une colonne de dates situées vers la fin de l'année.

SELECT
  date,
  EXTRACT(ISOYEAR FROM date) AS isoyear,
  EXTRACT(ISOWEEK FROM date) AS isoweek,
  EXTRACT(YEAR FROM date) AS year,
  EXTRACT(WEEK FROM date) AS week
FROM UNNEST(GENERATE_DATE_ARRAY('2015-12-23', '2016-01-09')) AS date
ORDER BY date;
+------------+---------+---------+------+------+
| date       | isoyear | isoweek | year | week |
+------------+---------+---------+------+------+
| 2015-12-23 | 2015    | 52      | 2015 | 51   |
| 2015-12-24 | 2015    | 52      | 2015 | 51   |
| 2015-12-25 | 2015    | 52      | 2015 | 51   |
| 2015-12-26 | 2015    | 52      | 2015 | 51   |
| 2015-12-27 | 2015    | 52      | 2015 | 52   |
| 2015-12-28 | 2015    | 53      | 2015 | 52   |
| 2015-12-29 | 2015    | 53      | 2015 | 52   |
| 2015-12-30 | 2015    | 53      | 2015 | 52   |
| 2015-12-31 | 2015    | 53      | 2015 | 52   |
| 2016-01-01 | 2015    | 53      | 2016 | 0    |
| 2016-01-02 | 2015    | 53      | 2016 | 0    |
| 2016-01-03 | 2015    | 53      | 2016 | 1    |
| 2016-01-04 | 2016    | 1       | 2016 | 1    |
| 2016-01-05 | 2016    | 1       | 2016 | 1    |
| 2016-01-06 | 2016    | 1       | 2016 | 1    |
| 2016-01-07 | 2016    | 1       | 2016 | 1    |
| 2016-01-08 | 2016    | 1       | 2016 | 1    |
| 2016-01-09 | 2016    | 1       | 2016 | 1    |
+------------+---------+---------+------+------+

Dans l'exemple suivant, date_expression tombe un dimanche. EXTRACT calcule la première colonne à l'aide de semaines commençant le dimanche, et la seconde colonne à l'aide de semaines commençant le lundi.

WITH table AS (SELECT DATE('2017-11-05') AS date)
SELECT
  date,
  EXTRACT(WEEK(SUNDAY) FROM date) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM date) AS week_monday FROM table;

+------------+-------------+-------------+
| date       | week_sunday | week_monday |
+------------+-------------+-------------+
| 2017-11-05 | 45          | 44          |
+------------+-------------+-------------+

DATE

1. DATE(year, month, day)
2. DATE(timestamp_expression[, timezone])

Description

1. Construit une DATE à partir de valeurs INT64 représentant l'année, le mois et le jour.
2. Convertit une expression timestamp_expression en un type de données DATE. Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (UTC) est utilisé.

Type de données renvoyé

DATE

Exemple

SELECT
  DATE(2016, 12, 25) as date_ymd,
  DATE(TIMESTAMP "2016-12-25 05:30:00+07", "America/Los_Angeles") as date_tstz;

+------------+------------+
| date_ymd   | date_tstz  |
+------------+------------+
| 2016-12-25 | 2016-12-24 |
+------------+------------+

DATE_ADD

DATE_ADD(date_expression, INTERVAL INT64_expr date_part)

Description

Ajoute un intervalle de temps spécifié à une DATE.

DATE_ADD accepte les valeurs date_part suivantes :

• DAY
• WEEK. Équivaut à sept jours (DAY).
• MONTH
• QUARTER
• YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de la date d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyé

DATE

Exemple

SELECT DATE_ADD(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_later;

+--------------------+
| five_days_later    |
+--------------------+
| 2008-12-30         |
+--------------------+

DATE_SUB

DATE_SUB(date_expression, INTERVAL INT64_expr date_part)

Description

Soustrait un intervalle de temps spécifié d'une DATE.

DATE_SUB accepte les valeurs date_part suivantes :

• DAY
• WEEK. Équivaut à sept jours (DAY).
• MONTH
• QUARTER
• YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de la date d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyé

DATE

Exemple

SELECT DATE_SUB(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_ago;

+---------------+
| five_days_ago |
+---------------+
| 2008-12-20    |
+---------------+

DATE_DIFF

DATE_DIFF(date_expression, date_expression, date_part)

Description

Renvoie le nombre de limites date_part entre les deux expressions date_expression. Si la première date précède la deuxième, le résultat est "non positif".

DATE_DIFF accepte les valeurs date_part suivantes :

• DAY
• WEEK (cette partie de la date commence le dimanche).
• WEEK(<WEEKDAY>) : cette partie de la date commence un jour de semaine (WEEKDAY). Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.
• ISOWEEK : utilise les limites de semaine ISO 8601. Les semaines ISO commencent le lundi.
• MONTH
• QUARTER
• YEAR
• ISOYEAR : utilise la limite de l'année à numérotation de semaine ISO 8601. La limite de l'année ISO est le lundi de la première semaine dont le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyé

INT64

Exemple

SELECT DATE_DIFF(DATE '2010-07-07', DATE '2008-12-25', DAY) as days_diff;

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+

SELECT
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', DAY) as days_diff,
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', WEEK) as weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

L'exemple ci-dessus montre le résultat de DATE_DIFF pour deux jours consécutifs. DATE_DIFF avec la partie de date WEEK renvoie 1, car DATE_DIFF compte le nombre de limites de partie de date dans cette plage de dates. Chaque WEEK commence le dimanche. Il existe donc une limite de partie de date entre le samedi (2017-10-14) et le dimanche (2017-10-15).

L'exemple suivant montre le résultat de DATE_DIFF pour deux dates avec des années différentes. La fonction DATE_DIFF avec la partie de date YEAR renvoie 3, car elle compte le nombre de limites de l'année civile grégorienne entre les deux dates. DATE_DIFF avec la partie de date ISOYEAR renvoie 2, car la seconde date appartient à l'année ISO 2015. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29.

SELECT
  DATE_DIFF('2017-12-30', '2014-12-30', YEAR) AS year_diff,
  DATE_DIFF('2017-12-30', '2014-12-30', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

L'exemple suivant montre le résultat de DATE_DIFF pour deux jours consécutifs. La première date tombe un lundi et la seconde un dimanche. DATE_DIFF avec la partie de date WEEK renvoie 0, car cette partie utilise des semaines commençant le dimanche. DATE_DIFF avec la partie de date WEEK(MONDAY) renvoie 1. DATE_DIFF avec la partie de date ISOWEEK renvoie également 1, car les semaines ISO commencent le lundi.

SELECT
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK(MONDAY)) AS week_weekday_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+-------------------+--------------+
| week_diff | week_weekday_diff | isoweek_diff |
+-----------+-------------------+--------------+
| 0         | 1                 | 1            |
+-----------+-------------------+--------------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Description

Tronque la date selon le niveau de précision spécifié.

DATE_TRUNC accepte les valeurs suivantes pour date_part :

• DAY
• WEEK
• WEEK(<WEEKDAY>) : tronque date_expression à la limite de la semaine précédente, où les semaines commencent un jour de semaine (WEEKDAY). Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.
• ISOWEEK : tronque date_expression à la limite de la semaine ISO 8601 précédente. Les ISOWEEK commencent le lundi. La première ISOWEEK de chaque année ISO englobe le premier jeudi de l'année civile grégorienne correspondante. Toute expression date_expression antérieure à celle-ci sera tronquée au lundi précédent.
• MONTH
• QUARTER
• YEAR
• ISOYEAR : tronque date_expression à la limite de l'année à numérotation de semaine ISO 8601 précédente. La limite de l'année ISO est le lundi de la première semaine dont le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyé

DATE

Exemples

SELECT DATE_TRUNC(DATE '2008-12-25', MONTH) as month;

+------------+
| month      |
+------------+
| 2008-12-01 |
+------------+

Dans l'exemple suivant, la date d'origine tombe un dimanche. Étant donné que date_part a la valeur WEEK(MONDAY), DATE_TRUNC renvoie l'objet DATE pour le lundi précédent.

SELECT date AS original, DATE_TRUNC(date, WEEK(MONDAY)) AS truncated
FROM (SELECT DATE('2017-11-05') AS date);

+------------+------------+
| original   | truncated  |
+------------+------------+
| 2017-11-05 | 2017-10-30 |
+------------+------------+

Dans l'exemple suivant, l'expression date_expression d'origine se trouve dans l'année civile grégorienne 2015. En revanche, DATE_TRUNC avec la partie de date ISOYEAR tronque date_expression au début de l'année ISO, et non de l'année civile grégorienne. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29. Par conséquent, la limite de l'année ISO précédant l'expression date_expression 2015-06-15 est le 2014-12-29.

SELECT
  DATE_TRUNC('2015-06-15', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATE '2015-06-15') AS isoyear_number;

+------------------+----------------+
| isoyear_boundary | isoyear_number |
+------------------+----------------+
| 2014-12-29       | 2015           |
+------------------+----------------+

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(INT64_expression)

Description

Interprète INT64_expression comme le nombre de jours écoulés depuis le 1er janvier 1970 (1970-01-01).

Type de données renvoyé

DATE

Exemple

SELECT DATE_FROM_UNIX_DATE(14238) as date_from_epoch;

+-----------------+
| date_from_epoch |
+-----------------+
| 2008-12-25      |
+-----------------+

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

Description

Formate date_expr en fonction de la chaîne de format (format_string) spécifiée.

Consultez la section Éléments de format acceptés pour DATE pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

STRING

Exemple

SELECT FORMAT_DATE("%x", DATE "2008-12-25") as US_format;

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

Description

Utilise une chaîne de format (format_string) et la représentation d'une date sous forme de chaîne pour renvoyer un objet DATE.

Lorsque vous utilisez PARSE_DATE, tenez compte des points suivants :

• Champs non spécifiés : tout champ non spécifié est initialisé à compter de la date par défaut 1970-01-01.
• Noms qui ne sont pas sensibles à la casse : certains noms (tels que Monday, February, etc.) ne sont pas sensibles à la casse.
• Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro ou plusieurs espaces blancs consécutifs dans la chaîne de date. En outre, les espaces blancs au début et à la fin de la chaîne de date sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
• Priorité de format : lorsqu'au moins deux éléments de format incluent des informations qui se chevauchent (par exemple, %F et %Y affectent tous deux l'année), le dernier d'entre eux remplace généralement les éléments précédents.

Consultez la section Éléments de format acceptés pour DATE pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

DATE

Exemple

SELECT PARSE_DATE("%x", "12/25/08") as parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

UNIX_DATE

UNIX_DATE(date_expression)

Description

Renvoie le nombre de jours écoulés depuis le 1er janvier 1970 (1970-01-01).

Type de données renvoyé

INT64

Exemple

SELECT UNIX_DATE(DATE "2008-12-25") as days_from_epoch;

+-----------------+
| days_from_epoch |
+-----------------+
| 14238           |
+-----------------+

Éléments de format acceptés pour DATE

Sauf indication contraire, les fonctions de date utilisant des chaînes de format acceptent les éléments suivants :

Élément de format	Description
%A	Nom complet du jour de la semaine.
%a	Nom du jour de la semaine sous forme abrégée.
%B	Nom complet du mois.
%b ou %h	Nom du mois sous forme abrégée.
%C	Siècle (une année divisée par 100 et tronquée pour obtenir un entier) sous forme de nombre décimal (00-99).
%D	Date au format %m/%d/%y.
%d	Jour du mois sous forme de nombre décimal (01-31).
%e	Jour du mois sous forme de nombre décimal (1-31) ; les valeurs à un seul chiffre (1-9) sont précédées d'une espace.
%F	Date au format %Y-%m-%d.
%G	Année ISO 8601 (avec le siècle) sous forme de nombre décimal. Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %G et %Y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%g	Année ISO 8601 (sans le siècle) sous forme de nombre décimal (00-99). Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %g et %y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%j	Jour de l'année sous forme de nombre décimal (001-366).
%m	Mois sous forme de nombre décimal (01-12).
%n	Caractère de nouvelle ligne.
%t	Caractère de tabulation.
%U	Numéro de la semaine dans l'année (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%u	Jour de la semaine (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (1-7).
%V	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (01-53). Si la semaine du 1er janvier compte quatre jours ou plus dans la nouvelle année, elle est considérée comme la semaine 1. Dans le cas contraire, elle est considérée comme semaine 53 de l'année précédente et la semaine qui suit est la semaine 1.
%W	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%w	Jour de la semaine (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (0-6).
%x	Représentation de la date au format MM/JJ/AA.
%Y	Année (avec le siècle) sous forme de nombre décimal.
%y	Année (sans le siècle) sous forme de nombre décimal (00-99), le premier zéro est facultatif. Peut être associé à %C. Si %C n'est pas spécifié, les années 00-68 sont considérées comme les années 2000 et les années 69-99 sont les années 1900.
%E4Y	Années sous forme de nombres à quatre caractères (0001 ... 9999). Notez que %Y produit autant de caractères que nécessaire pour un rendu complet de l'année.

Fonctions de date et heure

BigQuery accepte les fonctions DATETIME ci-après.

CURRENT_DATETIME

CURRENT_DATETIME([timezone])

Description

Renvoie l'heure actuelle en tant qu'objet DATETIME.

Cette fonction accepte un paramètre timezone facultatif. Pour en savoir plus sur la spécification d'un fuseau horaire, consultez la section Définition de fuseaux horaires.

Type de données renvoyé

DATETIME

Exemple

SELECT CURRENT_DATETIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 2016-05-19 10:38:47.046465 |
+----------------------------+

DATETIME

1. DATETIME(year, month, day, hour, minute, second)
2. DATETIME(date_expression, time_expression)
3. DATETIME(timestamp_expression [, timezone])

Description

1. Construit un objet DATETIME à l'aide de valeurs INT64 représentant l'année, le mois, le jour, l'heure, la minute et la seconde.
2. Construit un objet DATETIME à l'aide d'un objet DATE et d'un objet TIME.
3. Construit un objet DATETIME à l'aide d'un objet TIMESTAMP. Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (UTC) est utilisé.

Type de données renvoyé

DATETIME

Exemple

SELECT
  DATETIME(2008, 12, 25, 05, 30, 00) as datetime_ymdhms,
  DATETIME(TIMESTAMP "2008-12-25 05:30:00+00", "America/Los_Angeles") as datetime_tstz;

+---------------------+---------------------+
| datetime_ymdhms     | datetime_tstz       |
+---------------------+---------------------+
| 2008-12-25 05:30:00 | 2008-12-24 21:30:00 |
+---------------------+---------------------+

DATETIME_ADD

DATETIME_ADD(datetime_expression, INTERVAL INT64_expr part)

Description

Ajoute les unités INT64_expr de part à l'objet DATETIME.

DATETIME_ADD accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK. Équivaut à sept jours (DAY).
• MONTH
• QUARTER
• YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de l'objet DATETIME d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyé

DATETIME

Exemple

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_ADD(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_date               | later                  |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:40:00    |
+-----------------------------+------------------------+

DATETIME_SUB

DATETIME_SUB(datetime_expression, INTERVAL INT64_expr part)

Description

Soustrait les unités INT64_expr de part de l'objet DATETIME.

DATETIME_SUB accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK. Équivaut à sept jours (DAY).
• MONTH
• QUARTER
• YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de l'objet DATETIME d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyé

DATETIME

Exemple

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_SUB(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date               | earlier                |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:20:00    |
+-----------------------------+------------------------+

DATETIME_DIFF

DATETIME_DIFF(datetime_expression, datetime_expression, part)

Description

Renvoie le nombre de limites part entre les deux expressions datetime_expression. Si le premier objet DATETIME est antérieur au second objet DATETIME, le résultat est "non positif". La fonction renvoie une erreur si le calcul excède le type du résultat, par exemple si la différence en microsecondes entre les deux objets DATETIME dépasse une valeur INT64.

DATETIME_DIFF accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK : cette partie de la date commence le dimanche.
• WEEK(<WEEKDAY>) : cette partie de la date commence un jour de semaine (WEEKDAY). Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.
• ISOWEEK : utilise les limites de semaine ISO 8601. Les semaines ISO commencent le lundi.
• MONTH
• QUARTER
• YEAR
• ISOYEAR : utilise la limite de l'année à numérotation de semaine ISO 8601. La limite de l'année ISO est le lundi de la première semaine où le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyé

INT64

Exemple

SELECT
  DATETIME "2010-07-07 10:20:00" as first_datetime,
  DATETIME "2008-12-25 15:30:00" as second_datetime,
  DATETIME_DIFF(DATETIME "2010-07-07 10:20:00",
    DATETIME "2008-12-25 15:30:00", DAY) as difference;

+----------------------------+------------------------+------------------------+
| first_datetime             | second_datetime        | difference             |
+----------------------------+------------------------+------------------------+
| 2010-07-07 10:20:00        | 2008-12-25 15:30:00    | 559                    |
+----------------------------+------------------------+------------------------+

SELECT
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', DAY) as days_diff,
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', WEEK) as weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

L'exemple ci-dessus montre le résultat de DATETIME_DIFF pour deux objets DATETIME espacés de 24 heures. DATETIME_DIFF avec la partie WEEK renvoie 1, car DATETIME_DIFF compte le nombre de limites de partie dans cette plage d'objets DATETIME. Chaque WEEK commence le dimanche. Il existe donc une limite de partie entre le samedi (2017-10-14 00:00:00) et le dimanche (2017-10-15 00:00:00).

L'exemple suivant montre le résultat de DATETIME_DIFF pour deux dates avec des années différentes. La fonction DATETIME_DIFF avec la partie de date YEAR renvoie 3, car elle compte le nombre de limites de l'année civile grégorienne entre les deux objets DATETIME. DATETIME_DIFF avec la partie de date ISOYEAR renvoie 2, car le second objet DATETIME appartient à l'année ISO 2015. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29.

SELECT
  DATETIME_DIFF('2017-12-30 00:00:00',
    '2014-12-30 00:00:00', YEAR) AS year_diff,
  DATETIME_DIFF('2017-12-30 00:00:00',
    '2014-12-30 00:00:00', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

L'exemple suivant montre le résultat de DATETIME_DIFF pour deux jours consécutifs. La première date tombe un lundi et la seconde un dimanche. DATETIME_DIFF avec la partie de date WEEK renvoie 0, car cette partie utilise des semaines commençant le dimanche. DATETIME_DIFF avec la partie de date WEEK(MONDAY) renvoie 1. DATETIME_DIFF avec la partie de date ISOWEEK renvoie également 1, car les semaines ISO commencent le lundi.

SELECT
  DATETIME_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATETIME_DIFF('2017-12-18', '2017-12-17', WEEK(MONDAY)) AS week_weekday_diff,
  DATETIME_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+-------------------+--------------+
| week_diff | week_weekday_diff | isoweek_diff |
+-----------+-------------------+--------------+
| 0         | 1                 | 1            |
+-----------+-------------------+--------------+

DATETIME_TRUNC

DATETIME_TRUNC(datetime_expression, part)

Description

Tronque un objet DATETIME selon le niveau de précision de part.

DATETIME_TRUNC accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK
• WEEK(<WEEKDAY>) : tronque datetime_expression à la limite de la semaine précédente, où les semaines commencent un jour de semaine (WEEKDAY). Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.
• ISOWEEK : tronque datetime_expression à la limite de la semaine ISO 8601 précédente. Les ISOWEEK commencent le lundi. La première ISOWEEK de chaque année ISO englobe le premier jeudi de l'année civile grégorienne correspondante. Toute expression date_expression antérieure à celle-ci sera tronquée au lundi précédent.
• MONTH
• QUARTER
• YEAR
• ISOYEAR : tronque datetime_expression à la limite de l'année à numérotation de semaine ISO 8601 précédente. La limite de l'année ISO est le lundi de la première semaine dont le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyé

DATETIME

Exemples

SELECT
  DATETIME "2008-12-25 15:30:00" as original,
  DATETIME_TRUNC(DATETIME "2008-12-25 15:30:00", DAY) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 2008-12-25 15:30:00        | 2008-12-25 00:00:00    |
+----------------------------+------------------------+

Dans l'exemple suivant, l'objet DATETIME d'origine tombe un dimanche. Étant donné que part a la valeur WEEK(MONDAY), DATE_TRUNC renvoie l'objet DATETIME pour le lundi précédent.

SELECT
 datetime AS original,
 DATETIME_TRUNC(datetime, WEEK(MONDAY)) AS truncated
FROM (SELECT DATETIME(TIMESTAMP '2017-11-05 00:00:00') AS datetime);

+---------------------+---------------------+
| original            | truncated           |
+---------------------+---------------------+
| 2017-11-05 00:00:00 | 2017-10-30 00:00:00 |
+---------------------+---------------------+

Dans l'exemple suivant, l'expression datetime_expression d'origine se trouve dans l'année civile grégorienne 2015. En revanche, DATETIME_TRUNC avec la partie de date ISOYEAR tronque datetime_expression au début de l'année ISO, et non de l'année civile grégorienne. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29. Par conséquent, la limite de l'année ISO précédant l'expression datetime_expression 2015-06-15 00:00:00 est le 2014-12-29.

SELECT
  DATETIME_TRUNC('2015-06-15 00:00:00', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATETIME '2015-06-15 00:00:00') AS isoyear_number;

+---------------------+----------------+
| isoyear_boundary    | isoyear_number |
+---------------------+----------------+
| 2014-12-29 00:00:00 | 2015           |
+---------------------+----------------+

FORMAT_DATETIME

FORMAT_DATETIME(format_string, datetime_expression)

Description

Formate un objet DATETIME en fonction du paramètre format_string spécifié. Consultez la section Éléments de format acceptés pour DATETIME pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

STRING

Exemple

SELECT
  FORMAT_DATETIME("%c", DATETIME "2008-12-25 15:30:00")
  AS formatted;

PARSE_DATETIME

PARSE_DATETIME(format_string, string)

Description

Utilise un paramètre format_string et une représentation de type STRING d'un objet DATETIME pour renvoyer un objet DATETIME. Consultez la section Éléments de format acceptés pour DATETIME pour obtenir une liste des éléments de format acceptés par cette fonction.

PARSE_DATETIME analyse l'élément string selon les règles suivantes :

• Champs non spécifiés : tout champ non spécifié est initialisé à compter du 1970-01-01 00:00:00.0. Par exemple, si l'année n'est pas spécifiée, la valeur par défaut est 1970.
• Noms qui ne sont pas sensibles à la casse : certains noms, tels que Monday et February, ne sont pas sensibles à la casse.
• Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro, un ou plusieurs espaces blancs consécutifs dans la chaîne DATETIME. Les espaces blancs au début et à la fin de la chaîne DATETIME sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
• Priorité de format : lorsqu'au moins deux éléments de format incluent des informations qui se chevauchent, le dernier d'entre eux remplace généralement les éléments précédents, à quelques exceptions près. Par exemple, %F et %Y affectent tous deux l'année, donc le plus ancien des deux écrase le plus récent. Consultez les descriptions de %s, %C et %y dans la section Éléments de format acceptés pour DATETIME.

Exemples

L'exemple suivant analyse un littéral de type STRING en tant que DATETIME.

SELECT PARSE_DATETIME('%Y-%m-%d %H:%M:%S', '1998-10-18 13:45:55') AS datetime;

La requête ci-dessus renvoie le résultat suivant :

+---------------------+
| datetime            |
+---------------------+
| 1998-10-18 13:45:55 |
+---------------------+

L'exemple suivant analyse un littéral de type STRING contenant une date au format de langage naturel en tant que DATETIME.

SELECT PARSE_DATETIME('%A, %B %e, %Y','Wednesday, December 19, 2018')
  AS datetime;

La requête ci-dessus renvoie le résultat suivant :

+---------------------+
| datetime            |
+---------------------+
| 2018-12-19 00:00:00 |
+---------------------+

Type de données renvoyé

DATETIME

Éléments de format acceptés pour DATETIME

Sauf indication contraire, les fonctions DATETIME utilisant des chaînes de format acceptent les éléments suivants :

Élément de format	Description
%A	Nom complet du jour de la semaine.
%a	Nom du jour de la semaine sous forme abrégée.
%B	Nom complet du mois.
%b ou %h	Nom du mois sous forme abrégée.
%C	Siècle (une année divisée par 100 et tronquée pour obtenir un entier) sous forme de nombre décimal (00-99).
%c	Représentation de la date et de l'heure.
%D	Date au format %m/%d/%y.
%d	Jour du mois sous forme de nombre décimal (01-31).
%e	Jour du mois sous forme de nombre décimal (1-31) ; les valeurs à un seul chiffre (1-9) sont précédées d'une espace.
%F	Date au format %Y-%m-%d.
%G	Année ISO 8601 (avec le siècle) sous forme de nombre décimal. Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %G et %Y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%g	Année ISO 8601 (sans le siècle) sous forme de nombre décimal (00-99). Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %g et %y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%H	Heure (format 24 heures) sous forme de nombre décimal (00-23).
%I	Heure (format 12 heures) sous forme de nombre décimal (01-12).
%j	Jour de l'année sous forme de nombre décimal (001-366).
%k	Heure (format 24 heures) sous forme de nombre décimal (0-23) ; les valeurs à un seul chiffre sont précédées d'une espace.
%l	Heure (format 12 heures) sous forme de nombre décimal (1-12) ; les valeurs à un seul chiffre sont précédées d'une espace.
%M	Minutes sous forme de nombre décimal (00-59).
%m	Mois sous forme de nombre décimal (01-12).
%n	Caractère de nouvelle ligne.
%P	am ou pm.
%p	AM ou PM.
%R	Heure au format %H:%M.
%r	Heure au format 12 heures (avec notation AM/PM).
%S	Secondes sous forme de nombre décimal (00-60).
%s	Nombre de secondes écoulées depuis le 1970-01-01 00:00:00. Remplace systématiquement tous les autres éléments de format, indépendamment de l'endroit où %s apparaît dans la chaîne. Si plusieurs éléments %s apparaissent, le dernier est prioritaire.
%T	Heure au format %H:%M:%S.
%t	Caractère de tabulation.
%U	Numéro de la semaine dans l'année (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%u	Jour de la semaine (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (1-7).
%V	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (01-53). Si la semaine du 1er janvier compte quatre jours ou plus dans la nouvelle année, elle est considérée comme la semaine 1. Dans le cas contraire, elle est considérée comme semaine 53 de l'année précédente et la semaine qui suit est la semaine 1.
%W	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%w	Jour de la semaine (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (0-6).
%X	Représentation de l'heure au format HH:MM:SS.
%x	Représentation de la date au format MM/JJ/AA.
%Y	Année (avec le siècle) sous forme de nombre décimal.
%y	Année (sans le siècle) sous forme de nombre décimal (00-99), le premier zéro est facultatif. Peut être associé à %C. Si %C n'est pas spécifié, les années 00-68 sont considérées comme les années 2000 et les années 69-99 sont les années 1900.
%%	Caractère % unique.
%E#S	Secondes avec # chiffres de précision fractionnelle.
%E*S	Secondes avec précision fractionnelle complète (littéral '*').
%E4Y	Années sous forme de nombres à quatre caractères (0001 ... 9999). Notez que %Y produit autant de caractères que nécessaire pour un rendu complet de l'année.

Fonctions d'heure

BigQuery accepte les fonctions TIME ci-après.

CURRENT_TIME

CURRENT_TIME()

Description

Renvoie l'heure actuelle en tant qu'objet TIME.

Type de données renvoyé

TIME

Exemple

SELECT CURRENT_TIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 15:31:38.776361            |
+----------------------------+

TIME

1. TIME(hour, minute, second)
2. TIME(timestamp, [timezone])
3. TIME(datetime)

Description

1. Construit un objet TIME à partir de valeurs INT64 représentant l'heure, la minute et la seconde.
2. Construit un objet TIME à l'aide d'un objet TIMESTAMP. Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (UTC) est utilisé.
3. Construit un objet TIME à l'aide d'un objet DATETIME.

Type de données renvoyé

TIME

Exemple

SELECT
  TIME(15, 30, 00) as time_hms,
  TIME(TIMESTAMP "2008-12-25 15:30:00+08", "America/Los_Angeles") as time_tstz;
+----------+-----------+
| time_hms | time_tstz |
+----------+-----------+
| 15:30:00 | 23:30:00  |
+----------+-----------+

SELECT
  TIME(DATETIME "2008-12-25 15:30:00.000000") AS time_dt;
+----------+
| time_dt  |
+----------+
| 15:30:00 |
+----------+

TIME_ADD

TIME_ADD(time_expression, INTERVAL INT64_expr part)

Description

Ajoute les unités INT64_expr de part à l'objet TIME.

TIME_ADD accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Cette fonction s'ajuste automatiquement lorsque les valeurs ne sont pas comprises entre 00:00:00 et 24:00:00. Par exemple, si vous ajoutez une heure à 23:30:00, la valeur renvoyée est 00:30:00.

Types de données renvoyés

TIME

Exemple

SELECT
  TIME "15:30:00" as original_time,
  TIME_ADD(TIME "15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_time               | later                  |
+-----------------------------+------------------------+
| 15:30:00                    | 15:40:00               |
+-----------------------------+------------------------+

TIME_SUB

TIME_SUB(time_expression, INTERVAL INT_expr part)

Description

Soustrait les unités INT64_expr de part de l'objet TIME.

TIME_SUB accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Cette fonction s'ajuste automatiquement lorsque les valeurs ne sont pas comprises entre 00:00:00 et 24:00:00. Par exemple, si vous soustrayez une heure de 00:30:00, la valeur renvoyée est 23:30:00.

Type de données renvoyé

TIME

Exemple

SELECT
  TIME "15:30:00" as original_date,
  TIME_SUB(TIME "15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date                | earlier                |
+-----------------------------+------------------------+
| 15:30:00                    | 15:20:00               |
+-----------------------------+------------------------+

TIME_DIFF

TIME_DIFF(time_expression, time_expression, part)

Description

Renvoie le nombre d'intervalles part entiers spécifiés entre deux objets TIME. La fonction renvoie une erreur si le calcul excède le type du résultat, par exemple si la différence en microsecondes entre les deux objets TIME dépasse une valeur INT64.

TIME_DIFF accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Type de données renvoyé

INT64

Exemple

SELECT
  TIME "15:30:00" as first_time,
  TIME "14:35:00" as second_time,
  TIME_DIFF(TIME "15:30:00", TIME "14:35:00", MINUTE) as difference;

+----------------------------+------------------------+------------------------+
| first_time                 | second_time            | difference             |
+----------------------------+------------------------+------------------------+
| 15:30:00                   | 14:35:00               | 55                     |
+----------------------------+------------------------+------------------------+

TIME_TRUNC

TIME_TRUNC(time_expression, part)

Description

Tronque un objet TIME selon le niveau de précision de part.

TIME_TRUNC accepte les valeurs suivantes pour part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Type de données renvoyé

TIME

Exemple

SELECT
  TIME "15:30:00" as original,
  TIME_TRUNC(TIME "15:30:00", HOUR) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 15:30:00                   | 15:00:00               |
+----------------------------+------------------------+

FORMAT_TIME

FORMAT_TIME(format_string, time_object)

Description Formate un objet TIME en fonction du paramètre format_string spécifié. Consultez la section Éléments de format acceptés pour TIME pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

STRING

Exemple

SELECT FORMAT_TIME("%R", TIME "15:30:00") as formatted_time;

+----------------+
| formatted_time |
+----------------+
| 15:30          |
+----------------+

PARSE_TIME

PARSE_TIME(format_string, string)

Description

Utilise un paramètre format_string et une chaîne pour renvoyer un objet TIME. Consultez la section Éléments de format acceptés pour TIME pour obtenir une liste des éléments de format acceptés par cette fonction.

Lorsque vous utilisez PARSE_TIME, tenez compte des points suivants :

• Champs non spécifiés : tout champ non spécifié est initialisé à compter de 00:00:00.0. Par exemple, si aucune valeur n'est spécifiée pour seconds, la valeur par défaut est 00, etc.
• Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro, un ou plusieurs espaces blancs consécutifs dans la chaîne TIME. En outre, les espaces blancs au début et à la fin de la chaîne TIME sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
• Priorité de format : lorsqu'au moins deux éléments de format incluent des informations qui se chevauchent, le dernier d'entre eux remplace généralement les éléments précédents.

Type de données renvoyé

TIME

Exemple

SELECT PARSE_TIME("%H", "15") as parsed_time;

+-------------+
| parsed_time |
+-------------+
| 15:00:00    |
+-------------+

Éléments de format acceptés pour TIME

Sauf indication contraire, les fonctions TIME utilisant des chaînes de format acceptent les éléments suivants :

Élément de format	Description
%H	Heure (format 24 heures) sous forme de nombre décimal (00-23).
%I	Heure (format 12 heures) sous forme de nombre décimal (01-12).
%j	Jour de l'année sous forme de nombre décimal (001-366).
%k	Heure (format 24 heures) sous forme de nombre décimal (0-23) ; les valeurs à un seul chiffre sont précédées d'une espace.
%l	Heure (format 12 heures) sous forme de nombre décimal (1-12) ; les valeurs à un seul chiffre sont précédées d'une espace.
%M	Minutes sous forme de nombre décimal (00-59).
%n	Caractère de nouvelle ligne.
%P	am ou pm.
%p	AM ou PM.
%R	Heure au format %H:%M.
%r	Heure au format 12 heures (avec notation AM/PM).
%S	Secondes sous forme de nombre décimal (00-60).
%T	Heure au format %H:%M:%S.
%t	Caractère de tabulation.
%X	Représentation de l'heure au format HH:MM:SS.
%%	Caractère % unique.
%E#S	Secondes avec # chiffres de précision fractionnelle.
%E*S	Secondes avec précision fractionnelle complète (littéral '*').

Fonctions d'horodatage

BigQuery accepte les fonctions TIMESTAMP ci-après.

REMARQUE : Ces fonctions renvoient une erreur d'exécution en cas de débordement. Les valeurs de résultat sont délimitées par les valeurs min/max définies pour la date et l'horodatage.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Description

Les parenthèses sont facultatives. Cette fonction gère les sauts de secondes en les lissant sur une fenêtre de 20 heures autour de la seconde intercalaire insérée. CURRENT_TIMESTAMP() produit une valeur TIMESTAMP continue, non ambiguë, ayant exactement 60 secondes par minute et ne répétant pas les valeurs au-delà de la seconde intercalaire.

Types d'entrée acceptés

Non applicable

Type de données de résultat

TIMESTAMP

Exemple

SELECT CURRENT_TIMESTAMP() as now;

+-------------------------------+
| now                           |
+-------------------------------+
| 2016-05-16 18:12:47.145482+00 |
+-------------------------------+

EXTRACT

EXTRACT(part FROM timestamp_expression [AT TIME ZONE tz_spec])

Description

Renvoie une valeur INT64 qui correspond à la part spécifiée à partir d'une expression timestamp_expression fournie.

Les valeurs autorisées pour part sont :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAYOFWEEK
• DAY
• DAYOFYEAR

• WEEK : renvoie le numéro de semaine de la date (compris dans la plage [0, 53]). Les semaines commencent le dimanche et les dates antérieures au premier dimanche de l'année correspondent à la semaine 0.

• WEEK(<WEEKDAY>) : renvoie le numéro de semaine de timestamp_expression (compris dans la plage [0, 53]). Les semaines commencent un jour de semaine (WEEKDAY). Les éléments datetime antérieurs au premier WEEKDAY de l'année correspondent à la semaine 0. Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.

• ISOWEEK : renvoie le numéro de semaine ISO 8601 de datetime_expression. Les ISOWEEK commencent le lundi. Les valeurs renvoyées sont comprises dans la plage [1, 53]. La première ISOWEEK de chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne.

• MONTH
• QUARTER
• YEAR
• ISOYEAR : renvoie l'année à numérotation de semaine ISO 8601, qui correspond à l'année civile grégorienne contenant le jeudi de la semaine à laquelle date_expression appartient.
• DATE
• DATETIME
• TIME

Les valeurs renvoyées tronquent les périodes d'ordre inférieur. Par exemple, lors de l'extraction de secondes, EXTRACT tronque les valeurs en millisecondes et en microsecondes.

Consultez la rubrique Définition de fuseaux horaires pour plus d'informations sur la spécification d'un fuseau horaire.

Type de données renvoyé

Généralement INT64. Renvoie DATE si part a la valeur DATE.

Exemples

Dans l'exemple suivant, EXTRACT renvoie une valeur correspondant à l'élément de temps DAY.

SELECT EXTRACT(DAY
  FROM TIMESTAMP "2008-12-25 15:30:00" AT TIME ZONE "America/Los_Angeles")
  AS the_day;

+------------+
| the_day    |
+------------+
| 25         |
+------------+

Dans l'exemple suivant, EXTRACT renvoie des valeurs correspondant à différents éléments de temps d'une colonne d'horodatages.

WITH Timestamps AS (
  SELECT TIMESTAMP '2005-01-03 12:34:56' AS timestamp UNION ALL
  SELECT TIMESTAMP '2007-12-31' UNION ALL
  SELECT TIMESTAMP '2009-01-01' UNION ALL
  SELECT TIMESTAMP '2009-12-31' UNION ALL
  SELECT TIMESTAMP '2017-01-02' UNION ALL
  SELECT TIMESTAMP '2017-05-26'
)
SELECT
  timestamp,
  EXTRACT(ISOYEAR FROM timestamp) AS isoyear,
  EXTRACT(ISOWEEK FROM timestamp) AS isoweek,
  EXTRACT(YEAR FROM timestamp) AS year,
  EXTRACT(WEEK FROM timestamp) AS week
FROM Timestamps
ORDER BY timestamp;
+------------------------+---------+---------+------+------+
| timestamp              | isoyear | isoweek | year | week |
+------------------------+---------+---------+------+------+
| 2005-01-03 12:34:56+00 | 2005    | 1       | 2005 | 1    |
| 2007-12-31 00:00:00+00 | 2008    | 1       | 2007 | 52   |
| 2009-01-01 00:00:00+00 | 2009    | 1       | 2009 | 0    |
| 2009-12-31 00:00:00+00 | 2009    | 53      | 2009 | 52   |
| 2017-01-02 00:00:00+00 | 2017    | 1       | 2017 | 1    |
| 2017-05-26 00:00:00+00 | 2017    | 21      | 2017 | 21   |
+------------------------+---------+---------+------+------+

Dans l'exemple suivant, timestamp_expression tombe un dimanche. EXTRACT calcule la première colonne à l'aide de semaines commençant le dimanche, et la seconde colonne à l'aide de semaines commençant le lundi.

WITH table AS (SELECT TIMESTAMP('2017-11-05 00:00:00') AS timestamp)
SELECT
  timestamp,
  EXTRACT(WEEK(SUNDAY) FROM timestamp) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM timestamp) AS week_monday
FROM table;

+------------------------+-------------+---------------+
| timestamp              | week_sunday | week_monday |
+------------------------+-------------+---------------+
| 2017-11-05 00:00:00+00 | 45          | 44            |
+------------------------+-------------+---------------+

STRING

STRING(timestamp_expression[, timezone])

Description

Convertit une expression timestamp_expression en un type de données STRING. Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Consultez la rubrique Définition de fuseaux horaires pour plus d'informations sur la spécification d'un fuseau horaire.

Type de données renvoyé

STRING

Exemple

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles") as string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 15:30:00-08        |
+-------------------------------+

TIMESTAMP

1. TIMESTAMP(string_expression[, timezone])
2. TIMESTAMP(date_expression[, timezone])
3. TIMESTAMP(datetime_expression[, timezone])

Description

1. Convertit une expression STRING en un type de données TIMESTAMP.

2. Convertit un objet DATE en un type de données TIMESTAMP.

3. Convertit un objet DATETIME en un type de données TIMESTAMP.

Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (UTC) est utilisé.

Type de données renvoyé

TIMESTAMP

Exemple

SELECT
  CAST(TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") AS STRING) AS timestamp_str,
  CAST(TIMESTAMP(DATE "2008-12-25", "America/Los_Angeles") AS STRING) AS timestamp_date,
  CAST(TIMESTAMP(DATETIME "2008-12-25 15:30:00", "America/Los_Angeles") AS STRING) AS timestamp_datetime;

+------------------------+------------------------+------------------------+
| timestamp_str          | timestamp_date         | timestamp_datetime     |
+------------------------+------------------------+------------------------+
| 2008-12-25 23:30:00+00 | 2008-12-25 08:00:00+00 | 2008-12-25 23:30:00+00 |
+------------------------+------------------------+------------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

Description

Ajoute des unités int64_expression de date_part à l'horodatage, indépendamment de tout fuseau horaire.

TIMESTAMP_ADD accepte les valeurs suivantes pour date_part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Équivaut à 60 minutes (MINUTE).

Types de données renvoyés

TIMESTAMP

Exemple

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_ADD(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS later;

+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:40:00+00 |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL int64_expression date_part)

Description

Soustrait des unités int64_expression de date_part de l'horodatage, indépendamment de tout fuseau horaire.

TIMESTAMP_SUB accepte les valeurs suivantes pour date_part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Équivaut à 60 minutes (MINUTE).

Type de données renvoyé

TIMESTAMP

Exemple

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_SUB(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS earlier;

+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:20:00+00 |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression, timestamp_expression, date_part)

Description

Renvoie le nombre d'intervalles date_part entiers spécifiés entre deux horodatages. La première expression timestamp_expression représente la date la plus tardive ; si la première timestamp_expression est antérieure à la seconde timestamp_expression, le résultat est négatif. La fonction renvoie une erreur si le calcul excède le type du résultat, par exemple si la différence en nanosecondes entre les deux horodatages dépasse la valeur INT64 maximale possible.

TIMESTAMP_DIFF accepte les valeurs suivantes pour date_part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Équivaut à 60 minutes (MINUTE).

Type de données renvoyé

INT64

Exemple

SELECT
  TIMESTAMP "2010-07-07 10:20:00 UTC" as later_timestamp,
  TIMESTAMP "2008-12-25 15:30:00 UTC" as earlier_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00 UTC",
    TIMESTAMP "2008-12-25 15:30:00 UTC", HOUR) AS hours;

+------------------------+------------------------+-------+
| later_timestamp        | earlier_timestamp      | hours |
+------------------------+------------------------+-------+
| 2010-07-07 10:20:00+00 | 2008-12-25 15:30:00+00 | 13410 |
+------------------------+------------------------+-------+

Dans l'exemple suivant, le premier horodatage se produit avant le deuxième, ce qui entraîne un résultat négatif.

SELECT TIMESTAMP_DIFF(TIMESTAMP "2018-08-14", TIMESTAMP "2018-10-14", DAY);

+---------------+
| negative_diff |
+---------------+
| -61           |
+---------------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part[, time_zone])

Description

Tronque un horodatage selon le niveau de précision de date_part.

TIMESTAMP_TRUNC accepte les valeurs suivantes pour date_part :

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK
• WEEK(<WEEKDAY>): : tronque timestamp_expression à la limite de la semaine précédente, où les semaines commencent un jour de semaine (WEEKDAY). Les valeurs valides pour WEEKDAY sont SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY et SATURDAY.
• ISOWEEK : tronque timestamp_expression à la limite de la semaine ISO 8601 précédente. Les ISOWEEK commencent le lundi. La première ISOWEEK de chaque année ISO englobe le premier jeudi de l'année civile grégorienne correspondante. Toute expression date_expression antérieure à celle-ci sera tronquée au lundi précédent.
• MONTH
• QUARTER
• YEAR
• ISOYEAR : tronque timestamp_expression à la limite de l'année à numérotation de semaine ISO 8601 précédente. La limite de l'année ISO est le lundi de la première semaine dont le jeudi appartient à l'année civile grégorienne correspondante.

La fonction TIMESTAMP_TRUNC accepte un paramètre time_zone (facultatif). Ce paramètre s'applique aux date_parts suivants :

• MINUTE
• HOUR
• DAY
• WEEK
• WEEK(<WEEKDAY>)
• MONTH
• QUARTER
• YEAR

Utilisez ce paramètre si vous souhaitez utiliser un fuseau horaire différent de celui par défaut (UTC) dans le cadre de l'opération de troncation.

Lorsqu'une valeur TIMESTAMP est tronquée à la minute (MINUTE) ou à l'heure (HOUR), TIMESTAMP_TRUNC détermine l'heure civile de TIMESTAMP dans le fuseau horaire spécifié (ou par défaut) et soustrait les minutes et les secondes (si l'horodatage est tronqué à l'heure) ou les secondes (s'il est tronqué à la minute) de cet horodatage TIMESTAMP. Bien que cette méthode fournisse un résultat intuitif dans la plupart des cas, celui-ci peut toutefois l'être nettement moins lors du passage aux horaires d'été qui ne sont pas alignés sur l'heure.

Type de données renvoyé

TIMESTAMP

Exemples

SELECT
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'UTC') as utc,
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'America/Los_Angeles') as la;

+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25 00:00:00+00 | 2008-12-25 08:00:00+00 |
+------------------------+------------------------+

Dans l'exemple suivant, timestamp_expression présente un décalage de fuseau horaire de +12. La première colonne indique l'expression timestamp_expression dans le fuseau horaire UTC. La deuxième colonne indique le résultat de la fonction TIMESTAMP_TRUNC utilisant des semaines qui commencent le lundi. Étant donné que timestamp_expression tombe un dimanche (UTC), TIMESTAMP_TRUNC tronque cette expression au lundi précédent. La troisième colonne indique la même fonction avec l'argument facultatif de définition de fuseau horaire "Pacific/Auckland". Ici, la fonction tronque timestamp_expression en utilisant le fuseau horaire Heure avancée de la Nouvelle-Zélande, où elle tombe un lundi.

SELECT
  timestamp,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY)) AS utc_truncated,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY), 'Pacific/Auckland') AS nzdt_truncated
FROM (SELECT TIMESTAMP('2017-11-06 00:00:00+12') AS timestamp);

+------------------------+------------------------+------------------------+
| timestamp              | utc_truncated          | nzdt_truncated         |
+------------------------+------------------------+------------------------+
| 2017-11-05 12:00:00+00 | 2017-10-30 07:00:00+00 | 2017-11-05 11:00:00+00 |
+------------------------+------------------------+------------------------+

Dans l'exemple suivant, l'expression timestamp_expression d'origine se trouve dans l'année civile grégorienne 2015. En revanche, TIMESTAMP_TRUNC avec la partie de date ISOYEAR tronque timestamp_expression au début de l'année ISO, et non de l'année civile grégorienne. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29. Par conséquent, la limite de l'année ISO précédant l'expression timestamp_expression 2015-06-15 00:00:00+00 est le 2014-12-29.

SELECT
  TIMESTAMP_TRUNC('2015-06-15 00:00:00+00', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM TIMESTAMP '2015-06-15 00:00:00+00') AS isoyear_number;

+------------------------+----------------+
| isoyear_boundary       | isoyear_number |
+------------------------+----------------+
| 2014-12-29 00:00:00+00 | 2015           |
+------------------------+----------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

Description

Formate un horodatage en fonction de la chaîne de format (format_string) spécifiée.

Consultez la section Éléments de format acceptés pour TIMESTAMP pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

STRING

Exemple

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles")
  AS formatted;

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 07:30:00 2008 |
+--------------------------+

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, string[, time_zone])

Description

Utilise une chaîne de format (format_string) et la représentation d'un horodatage sous forme de chaîne pour renvoyer un objet TIMESTAMP.

Lorsque vous utilisez PARSE_TIMESTAMP, tenez compte des points suivants :

• Champs non spécifiés : tout champ non spécifié est initialisé à compter de 1970-01-01 00:00:00.0. Cette valeur d'initialisation utilise le fuseau horaire spécifié par l'argument "time zone" de la fonction, si ce dernier est présent. Dans le cas contraire, la valeur d'initialisation utilise le fuseau horaire par défaut (UTC). Par exemple, si l'année n'est pas spécifiée, la valeur par défaut 1970 est utilisée, et ainsi de suite.
• Noms qui ne sont pas sensibles à la casse : certains noms (tels que Monday, February, etc.) ne sont pas sensibles à la casse.
• Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro ou plusieurs espaces blancs consécutifs dans la chaîne d'horodatage. En outre, les espaces blancs au début et à la fin de la chaîne d'horodatage sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
• Priorité de format : lorsque deux (ou plus de deux) éléments de format incluent des informations qui se chevauchent (par exemple, %F et %Y affectent tous deux l'année), le dernier d'entre eux remplace généralement les éléments précédents, à quelques exceptions près (reportez-vous aux descriptions de %s, %C et %y).

Consultez la section Éléments de format acceptés pour TIMESTAMP pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyé

TIMESTAMP

Exemple

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008", "America/Los_Angeles") as parsed;

+-------------------------+
| parsed                  |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_SECONDS

TIMESTAMP_SECONDS(int64_expression)

Description

Interprète int64_expression comme le nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC).

Type de données renvoyé

TIMESTAMP

Exemple

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

Description

Interprète int64_expression comme le nombre de millisecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC).

Type de données renvoyé

TIMESTAMP

Exemple

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

Description

Interprète int64_expression comme le nombre de microsecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC).

Type de données renvoyé

TIMESTAMP

Exemple

SELECT TIMESTAMP_MICROS(1230219000000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Description

Renvoie le nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Tronque les niveaux de précision les plus élevés.

Type de données renvoyé

INT64

Exemple

SELECT UNIX_SECONDS(TIMESTAMP "2008-12-25 15:30:00") as seconds;

+------------+
| seconds    |
+------------+
| 1230219000 |
+------------+

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Description

Renvoie le nombre de millisecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Tronque les niveaux de précision les plus élevés.

Type de données renvoyé

INT64

Exemple

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00 UTC") as millis;

+---------------+
| millis        |
+---------------+
| 1230219000000 |
+---------------+

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

Description

Renvoie le nombre de microsecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Tronque les niveaux de précision les plus élevés.

Type de données renvoyé

INT64

Exemple

SELECT UNIX_MICROS(TIMESTAMP "2008-12-25 15:30:00") as micros;

+------------------+
| micros           |
+------------------+
| 1230219000000000 |
+------------------+

Éléments de format acceptés pour TIMESTAMP

Sauf indication contraire, les fonctions d'horodatage utilisant des chaînes de format acceptent les éléments suivants :

Élément de format	Description
%A	Nom complet du jour de la semaine.
%a	Nom du jour de la semaine sous forme abrégée.
%B	Nom complet du mois.
%b ou %h	Nom du mois sous forme abrégée.
%C	Siècle (une année divisée par 100 et tronquée pour obtenir un entier) sous forme de nombre décimal (00-99).
%c	Représentation de la date et de l'heure.
%D	Date au format %m/%d/%y.
%d	Jour du mois sous forme de nombre décimal (01-31).
%e	Jour du mois sous forme de nombre décimal (1-31) ; les valeurs à un seul chiffre (1-9) sont précédées d'une espace.
%F	Date au format %Y-%m-%d.
%G	Année ISO 8601 (avec le siècle) sous forme de nombre décimal. Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %G et %Y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%g	Année ISO 8601 (sans le siècle) sous forme de nombre décimal (00-99). Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %g et %y peuvent produire des résultats différents près des limites de l'année grégorienne, où celle-ci et l'année ISO peuvent diverger.
%H	Heure (format 24 heures) sous forme de nombre décimal (00-23).
%I	Heure (format 12 heures) sous forme de nombre décimal (01-12).
%j	Jour de l'année sous forme de nombre décimal (001-366).
%k	Heure (format 24 heures) sous forme de nombre décimal (0-23) ; les valeurs à un seul chiffre sont précédées d'une espace.
%l	Heure (format 12 heures) sous forme de nombre décimal (1-12) ; les valeurs à un seul chiffre sont précédées d'une espace.
%M	Minutes sous forme de nombre décimal (00-59).
%m	Mois sous forme de nombre décimal (01-12).
%n	Caractère de nouvelle ligne.
%P	am ou pm.
%p	AM ou PM.
%R	Heure au format %H:%M.
%r	Heure au format 12 heures (avec notation AM/PM).
%S	Secondes sous forme de nombre décimal (00-60).
%s	Nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Remplace systématiquement tous les autres éléments de format, indépendamment de l'endroit où %s apparaît dans la chaîne. Si plusieurs éléments %s apparaissent, le dernier est prioritaire.
%T	Heure au format %H:%M:%S.
%t	Caractère de tabulation.
%U	Numéro de la semaine dans l'année (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%u	Jour de la semaine (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (1-7).
%V	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (01-53). Si la semaine du 1er janvier compte quatre jours ou plus dans la nouvelle année, elle est considérée comme la semaine 1. Dans le cas contraire, elle est considérée comme semaine 53 de l'année précédente et la semaine qui suit est la semaine 1.
%W	Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53).
%w	Jour de la semaine (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (0-6).
%X	Représentation de l'heure au format HH:MM:SS.
%x	Représentation de la date au format MM/JJ/AA.
%Y	Année (avec le siècle) sous forme de nombre décimal.
%y	Année (sans le siècle) sous forme de nombre décimal (00-99), le premier zéro est facultatif. Peut être associé à %C. Si %C n'est pas spécifié, les années 00-68 sont considérées comme les années 2000 et les années 69-99 sont les années 1900.
%Z	Nom du fuseau horaire.
%z	Décalage par rapport au méridien d'origine, au format +HHMM ou -HHMM selon le cas. Les emplacements situés à l'est du méridien de Greenwich sont représentés par des valeurs positives.
%%	Caractère % unique.
%Ez	Fuseau horaire numérique compatible RFC 3339 (+HH:MM ou -HH:MM).
%E#S	Secondes avec # chiffres de précision fractionnelle.
%E*S	Secondes avec précision fractionnelle complète (littéral '*').
%E4Y	Années sous forme de nombres à quatre caractères (0001 ... 9999). Notez que %Y produit autant de caractères que nécessaire pour un rendu complet de l'année.

Définition de fuseaux horaires

Certaines fonctions de date et d'horodatage vous permettent d'ignorer le fuseau horaire par défaut et d'en spécifier un autre. Vous pouvez spécifier un fuseau horaire en indiquant son décalage UTC au format suivant :

(+|-)H[H][:M[M]]

Par exemple :

-08:00

Fonctions de géographie

Les fonctions de géographie effectuent des opérations sur des valeurs GEOGRAPHY BigQuery ou en génèrent. La signature de toute fonction de géographie commence par ST_. BigQuery accepte les fonctions ci-après, qui peuvent être utilisées pour analyser des données géographiques, déterminer les relations spatiales entre des éléments géographiques, et construire ou manipuler des valeurs GEOGRAPHY.

Les fonctions de géographie sont regroupées dans les catégories suivantes en fonction de leur comportement :

• Constructeurs : fonctions qui créent des valeurs GEOGRAPHY à partir de coordonnées ou de valeurs GEOGRAPHY existantes, telles que ST_GEOGPOINT.
• Analyseurs : fonctions qui créent des valeurs GEOGRAPHY à partir d'un format externe tel que WKT et GeoJSON. Par exemple, ST_GEOGFROMTEXT crée une valeur GEOGRAPHY à partir de WKT.
• Formateurs : fonctions qui exportent des valeurs GEOGRAPHY vers un format externe tel que WKT et GeoJSON. Par exemple, ST_ASTEXT formate une valeur GEOGRAPHY en WKT.
• Transformations : fonctions qui génèrent une nouvelle valeur GEOGRAPHY à partir d'autres valeurs qui respecte une certaine propriété. Les exemples incluent ST_INTERSECTION et ST_BOUNDARY.
• Prédicats : fonctions qui renvoient TRUE ou FALSE pour une relation spatiale entre deux valeurs GEOGRAPHY, ou pour une propriété d'une zone géographique. Ces fonctions sont couramment utilisées dans les clauses de filtre. Par exemple, ST_DWITHIN est un prédicat.
• Accesseurs : fonctions permettant d'accéder aux propriétés d'une valeur GEOGRAPHY sans effets secondaires, par exemple ST_NUMPOINTS.
• Mesures : fonctions qui calculent les mesures d'une ou de plusieurs valeurs GEOGRAPHY, par exemple ST_DISTANCE.
• Fonctions d'agrégation : fonctions d'agrégation propres à une zone géographique, par exemple ST_UNION_AGG.

Toutes les fonctions de géographie de BigQuery renvoient NULL si l'un des arguments d'entrée est NULL.

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

Description

Crée une valeur GEOGRAPHY avec un seul point. ST_GEOGPOINT crée un point à partir des paramètres de longitude et de latitude FLOAT64 spécifiés, et le renvoie dans une valeur GEOGRAPHY.

Contraintes

• Les latitudes doivent être comprises dans la plage [-90, 90]. Si elles sont situées en dehors de cette plage, elles entraînent une erreur.
• Les longitudes non comprises de la plage [-180, 180] sont autorisées. ST_GEOGPOINT utilise le modulo 360 de longitudes d'entrées pour obtenir une longitude comprise dans cette plage.

Type renvoyé

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)

ST_MAKELINE(array_of_geography)

Description

Crée une valeur GEOGRAPHY avec une seule polyligne en concaténant les sommets des points ou des lignes de chacune des valeurs GEOGRAPHY d'entrée, dans l'ordre dans lequel elles sont données.

ST_MAKELINE comporte deux variantes. Pour la première variante, deux valeurs GEOGRAPHY doivent être saisies. Pour la deuxième, l'entrée doit être une valeur ARRAY de type GEOGRAPHY. Dans l'une ou l'autre variante, chaque entrée GEOGRAPHY doit comporter l'une des valeurs suivantes :

• Exactement un point
• Exactement une polyligne

Pour la première variante de ST_MAKELINE, si l'une des entrées GEOGRAPHY est NULL, ST_MAKELINE renvoie NULL. Pour la deuxième variante, si l'entrée ARRAY ou un élément de l'entrée ARRAY est NULL, ST_MAKELINE renvoie NULL.

Contraintes

Chaque arête doit couvrir strictement moins de 180 degrés.

REMARQUE : Le processus d'ancrage de BigQuery peut supprimer les arêtes suffisamment courtes et ancrer les deux extrémités ensemble. Par exemple, si deux valeurs GEOGRAPHY d'entrée contiennent chacune un point et que la distance séparant les deux points est inférieure au rayon d'ancrage, les points sont ancrés ensemble. Dans ce cas, le résultat obtenu est une valeur GEOGRAPHY avec exactement un point.

Type renvoyé

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)

ST_MAKEPOLYGON(geography_expression, array_of_geography)

Description

Crée une valeur GEOGRAPHY contenant un seul polygone à partir d'entrées de polyligne, chacune étant utilisée pour construire un anneau de polygone.

ST_MAKEPOLYOGN comporte deux variantes. Pour la première variante, la polyligne d'entrée est fournie par une seule valeur GEOGRAPHY contenant exactement une polyligne. Pour la deuxième variante, l'entrée est composée d'une seule valeur GEOGRAPHY et d'un tableau de GEOGRAPHY, chacun contenant exactement une polyligne. La première valeur GEOGRAPHY de l'une ou l'autre variante est utilisée pour construire l'enveloppe du polygone. Les valeurs GEOGRAPHY supplémentaires fournies dans l'entrée ARRAY spécifient un trou du polygone. Pour chaque valeur GEOGRAPHY d'entrée contenant exactement une polyligne, les conditions suivantes doivent être remplies :

• La polyligne doit comporter au moins trois sommets distincts.
• La polyligne doit être fermée, c'est-à-dire que les premier et dernier sommets doivent être identiques. S'ils sont différents, la fonction construit une arête finale allant du premier au dernier sommet.

Pour la première variante de ST_MAKEPOLYGON, si l'une des entrées GEOGRAPHY est NULL, ST_MAKEPOLYOGN renvoie NULL. Pour la deuxième variante, si l'entrée ARRAY ou un élément de l'entrée ARRAY est NULL, ST_MAKEPOLYGON renvoie NULL.

REMARQUE : ST_MAKEPOLYGON accepte une valeur GEOGRAPHY vide comme entrée. ST_MAKEPOLYGON interprète une valeur GEOGRAPHY vide comme ayant une polyligne vide, ce qui crée une boucle complète, autrement dit un polygone couvrant toute la Terre.

Contraintes

Ensemble, les anneaux d'entrée doivent former un polygone valide :

• L'enveloppe du polygone doit couvrir chacun des trous de ce dernier.
• Il ne peut y avoir qu'une seule enveloppe de polygone (qui doit être le premier anneau d'entrée). Cela implique que les trous de polygone ne peuvent pas être imbriqués.
• Les anneaux de polygone ne peuvent se croiser que dans un sommet situé sur la limite des deux anneaux.

Chaque arête doit couvrir strictement moins de 180 degrés.

Chaque anneau de polygone divise la sphère en deux régions. La première polyligne d'entrée pour ST_MAKEPOLYGON forme l'enveloppe du polygone, et l'intérieur est choisi pour être la plus petite des deux régions. Chaque polyligne d'entrée suivante spécifie un trou de polygone, de sorte que l'intérieur du polygone est déjà bien défini. Pour définir une enveloppe du polygone de façon à ce que l'intérieur de ce dernier soit la plus grande des deux régions, consultez la section relative à la fonction ST_MAKEPOLYGONORIENTED.

REMARQUE : Le processus d'ancrage de BigQuery peut supprimer les arêtes suffisamment courtes et ancrer les deux extrémités ensemble. Par conséquent, lorsque les sommets sont ancrés ensemble, il est possible qu'un trou de polygone suffisamment petit disparaisse, ou que la valeur GEOGRAPHY de sortie ne contienne qu'un point ou une ligne.

Type renvoyé

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

Description

Cette fonction est identique à ST_MAKEPOLYGON, mais l'ordre des sommets de chaque polyligne d'entrée détermine l'orientation de chaque anneau de polygone. L'orientation d'un anneau de polygone définit l'intérieur du polygone de la manière suivante : si quelqu'un marche le long de la limite du polygone dans l'ordre des sommets d'entrée, l'intérieur du polygone se trouve sur la gauche. Ceci s'applique à chaque anneau de polygone fourni.

Cette variante du constructeur de polygone est plus flexible, car ST_MAKEPOLYGONORIENTED peut construire un polygone de sorte que l'intérieur se trouve de chaque côté de l'anneau de polygone. Cependant, il est primordial que les anneaux de polygone soient orientés correctement pour construire le polygone souhaité.

Si l'entrée ARRAY ou tout autre élément de l'entrée ARRAY est NULL, ST_MAKEPOLYGONORIENTED renvoie NULL.

REMARQUE : l'argument d'entrée pour ST_MAKEPOLYGONORIENTED peut contenir une valeur GEOGRAPHY vide. ST_MAKEPOLYGONORIENTED interprète une valeur GEOGRAPHY vide comme ayant une polyligne vide, ce qui crée une boucle complète, autrement dit un polygone couvrant toute la Terre.

Contraintes

Ensemble, les anneaux d'entrée doivent former un polygone valide :

• L'enveloppe du polygone doit couvrir chacun des trous de ce dernier.
• Il ne doit y avoir qu'une seule enveloppe de polygone, qui doit être le premier anneau d'entrée. Cela implique que les trous de polygone ne peuvent pas être imbriqués.
• Les anneaux de polygone ne peuvent se croiser que dans un sommet situé sur la limite des deux anneaux.

Chaque arête doit couvrir strictement moins de 180 degrés.

ST_MAKEPOLYGONORIENTED s'appuie sur l'ordre des sommets d'entrée de chaque polyligne pour déterminer l’orientation du polygone. Ceci s'applique à l'enveloppe du polygone et à tous les trous de ce dernier. ST_MAKEPOLYGONORIENTED s'attend à ce que tous les trous du polygone aient l'orientation opposée à celle de l'enveloppe. Consultez la section relative à la fonction ST_MAKEPOLYGON pour découvrir un autre constructeur de polygone, ainsi que d'autres contraintes associées à la construction d'un polygone valide.

REMARQUE : En raison du processus d'ancrage de BigQuery, les arêtes suffisamment courtes sont supprimées et les deux extrémités sont ancrées à un seul point. Par conséquent, il est possible que les sommets d'une polyligne soient ancrés ensemble de façon qu'une ou plusieurs arêtes disparaissent. Ainsi, un trou de polygone suffisamment petit peut disparaître, ou la valeur GEOGRAPHY résultante peut ne contenir qu'un point ou une ligne.

Type renvoyé

GEOGRAPHY

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

Description

Renvoie une valeur GEOGRAPHY correspondant à la représentation GeoJSON d'entrée.

ST_GEOGFROMGEOJSON accepte une entrée conforme à la norme RFC 7946.

Une valeur GEOGRAPHY BigQuery a des arêtes géodésiques sphériques, tandis qu'un objet Geometry GeoJSON a explicitement des arêtes planes. Pour effectuer la conversion entre ces deux types d'arêtes, BigQuery ajoute des points supplémentaires à la ligne si nécessaire, de sorte que la séquence d'arêtes résultante reste à moins de 10 mètres de l'arête d'origine.

Pour formater une valeur GEOGRAPHY en GeoJSON, consultez la section sur la fonction ST_ASGEOJSON.

Contraintes

L'entrée est soumise aux contraintes suivantes :

• La fonction ST_GEOGFROMGEOJSON n'accepte que des fragments de géométrie JSON et elle ne peut pas être utilisée pour ingérer un document JSON complet.
• Le fragment JSON d'entrée doit être d'un type de géométrie GeoJSON, soit Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon ou GeometryCollection. Tout autre type GeoJSON, tel que Feature ou FeatureCollection, entraînera une erreur.
• Une position dans le membre coordinates d'un type de géométrie GeoJSON doit comporter exactement deux éléments. Le premier est la longitude, et le second est la latitude. Par conséquent, ST_GEOGFROMGEOJSON n'accepte pas le troisième élément facultatif pour une position dans le membre coordinates.

Type renvoyé

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)

ST_GEOGFROMTEXT(wkt_string, oriented)

Description

Renvoie une valeur GEOGRAPHY correspondant à la représentation WKT d'entrée.

Cette fonction accepte un paramètre facultatif de type BOOL, oriented. Si ce paramètre est défini sur TRUE, tous les polygones de l'entrée sont supposés être orientés comme suit : si quelqu'un marche le long de la limite du polygone dans l'ordre des sommets d'entrée, l'intérieur du polygone se trouve sur la gauche. WKT peut ainsi représenter des polygones plus grands qu'un hémisphère. Si oriented a la valeur FALSE ou est omis, cette fonction renvoie le polygone ayant la plus petite aire. Consultez également la section relative à la fonction ST_MAKEPOLYGONORIENTED, qui est semblable à la fonction ST_GEOGFROMTEXT avec le paramètre oriented=TRUE.

Pour formater une valeur GEOGRAPHY en WKT, utilisez la fonction ST_ASTEXT.

Contraintes

Toutes les arêtes d'entrée sont supposées être des géodésiques sphériques, et non des lignes droites planes. Pour lire des données dans une projection planaire, envisagez d'utiliser ST_GEOGFROMGEOJSON. Pour plus d'informations sur les différences entre les géodésiques sphériques et les lignes planes, consultez la section Systèmes de coordonnées et arêtes.

Type renvoyé

GEOGRAPHY

Exemple

La requête suivante lit la chaîne WKT POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) à la fois comme un polygone non orienté et comme un polygone orienté, et vérifie si chaque résultat contient le point (1, 1).

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

Description

Renvoie une valeur GEOGRAPHY correspondant à la représentation WKB d'entrée.

Pour formater une valeur GEOGRAPHY en WKB, utilisez la fonction ST_ASBINARY.

Contraintes

Toutes les arêtes d'entrée sont supposées être des géodésiques sphériques, et non des lignes droites planes. Pour lire des données dans une projection planaire, envisagez d'utiliser ST_GEOGFROMGEOJSON.

Type renvoyé

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

Description

Renvoie une valeur GEOGRAPHY correspondant à un point au milieu d'un cadre de délimitation défini dans le GeoHash.

Type renvoyé

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

Description

Renvoie la représentation GeoJSON conforme à la norme RFC 7946 pour la valeur GEOGRAPHY d'entrée.

Une valeur GEOGRAPHY BigQuery a des arêtes géodésiques sphériques, tandis qu'un objet Geometry GeoJSON a explicitement des arêtes planes. Pour effectuer la conversion entre ces deux types d'arêtes, BigQuery ajoute des points supplémentaires à la ligne si nécessaire, de sorte que la séquence d'arêtes résultante reste à moins de 10 mètres de l'arête d'origine.

Consultez la section sur la fonction ST_GEOGFROMGEOJSON pour construire une valeur GEOGRAPHY à partir de GeoJSON.

Type renvoyé

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

Description

Renvoie la représentation WKT d'une valeur GEOGRAPHY d'entrée.

Consultez la section sur la fonction ST_GEOGFROMTEXT pour construire une valeur GEOGRAPHY à partir de WKT.

Type renvoyé

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Description

Renvoie une représentation GeoHash de geography_expression. Le GeoHash résultant contiendra au maximum maxchars caractères. Un nombre moins important de caractères correspond à une précision inférieure (ou, autrement dit, à un cadre de délimitation plus grand).

L'exécution de ST_GeoHash sur un objet GEOGRAPHY vide renvoie NULL.

Contraintes

• Seuls les objets GEOGRAPHY représentant des points uniques sont acceptés.
• La valeur maximale de maxchars est 20.

Exemple

Renvoie un GeoHash du Seattle Center avec une précision de 10 caractères.

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

Type renvoyé

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

Description

Renvoie la représentation WKB d'une valeur GEOGRAPHY d'entrée.

Consultez la section relative à la fonction ST_GEOGFROMWKB pour construire une valeur GEOGRAPHY à partir de WKB.

Type renvoyé

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

Description

Renvoie une seule valeur GEOGRAPHY contenant l'union des limites de chaque composant dans la valeur GEOGRAPHY d'entrée donnée.

La limite de chaque composant d'une valeur GEOGRAPHY est définie comme suit :

• La limite d'un point est vide.
• La limite d'une polyligne est constituée des extrémités de cette dernière.
• La limite d'un polygone est constituée des polylignes qui forment l'enveloppe du polygone et de chacun des trous de ce dernier.

Type renvoyé

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

Description

Renvoie le centroïde de la valeur GEOGRAPHY d'entrée sous la forme d'une valeur GEOGRAPHY à un seul point.

Le centroïde d'une valeur GEOGRAPHY est la moyenne pondérée des centroïdes des composants ayant la dimension la plus élevée dans la valeur GEOGRAPHY. Le centroïde des composants dans chaque dimension est défini comme suit :

• Le centroïde des points correspond à la moyenne arithmétique des coordonnées en entrée.
• Le centroïde des polylignes correspond au centroïde de toutes les arêtes pondérées par la longueur. Le centroïde de chaque arête est le milieu géodésique de l'arête.
• Le centroïde d'un polygone est son centre de masse.

Si la valeur GEOGRAPHY d'entrée est vide, une valeur GEOGRAPHY vide est renvoyée.

Contraintes

Dans le cas peu probable où le centroïde d'une valeur GEOGRAPHY ne peut pas être défini par un seul point situé sur la surface de la Terre, un point déterministe mais arbitraire est renvoyé. Cela ne peut se produire que si le centroïde est exactement au centre de la Terre, par exemple dans le cas du centroïde d'une paire de points antipodaux, et la probabilité que cela se produise est extrêmement faible.

Type renvoyé

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)

ST_CLOSESTPOINT(geography_1, geography_2, use_spheroid)

Description

Renvoie une valeur GEOGRAPHY contenant un point sur geography_1 situé à la distance la plus faible possible de geography_2. Cela implique que la distance entre le point renvoyé par ST_CLOSESTPOINT et geography_2 est inférieure ou égale à la distance entre tout autre point sur geography_1 et geography_2.

Si l'une des valeurs GEOGRAPHY d'entrée est vide, ST_CLOSESTPOINT renvoie NULL.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

Description

Renvoie une valeur GEOGRAPHY qui représente la différence d'ensemble de points entre geography_1 et geography_2.

Si geometry_1 est entièrement contenu dans geometry_2, ST_DIFFERENCE renvoie une valeur GEOGRAPHY vide.

Contraintes

Les objets géométriques sous-jacents représentés par une valeur GEOGRAPHY BigQuery correspondent à un ensemble de points fermé. Par conséquent, ST_DIFFERENCE est la fermeture de la différence d'ensemble de points entre geography_1 et geography_2. Cela implique qu'en cas d'intersection de geography_1 et geography_2, une partie de la limite de geography_2 pourrait se trouver dans la différence.

Type renvoyé

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

Description

Renvoie une valeur GEOGRAPHY représentant l'intersection des ensembles de points des deux valeurs GEOGRAPHY d'entrée. Ainsi, chaque point de l'intersection apparaît à la fois dans geography_1 et dans geography_2.

Si les deux valeurs GEOGRAPHY d'entrée sont disjointes, c'est-à-dire si aucun point n'apparaît à la fois dans geometry_1 et dans geometry_2, une valeur GEOGRAPHY vide est renvoyée.

Pour en savoir plus sur les fonctions de prédicat associées, consultez les sections sur les fonctions ST_INTERSECTS et ST_DISJOINT.

Type renvoyé

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

Description

Renvoie la valeur GEOGRAPHY d'entrée, où chaque sommet a été ancré à une grille de longitude/latitude. La taille de la grille est déterminée par le paramètre grid_size, qui est exprimé en degrés.

Contraintes

Les tailles de grille arbitraires ne sont pas acceptées. Le paramètre grid_size est arrondi de sorte qu'il se présente sous la forme $$10^n$$, où $$-10 < n < 0$$.

Type renvoyé

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

Description

Renvoie une valeur GEOGRAPHY représentant l'union des ensembles de points de toutes les valeurs GEOGRAPHY d'entrée.

ST_UNION comporte deux variantes. Pour la première variante, deux valeurs GEOGRAPHY doivent être saisies. Pour la deuxième, l'entrée est un ARRAY de type GEOGRAPHY.

Pour la première variante de ST_UNION, si une entrée GEOGRAPHY est NULL, ST_UNION renvoie NULL. Pour la deuxième variante, si la valeur d'entrée ARRAY est NULL, ST_UNION renvoie NULL. Pour une entrée ARRAY non NULL, l'union est calculée et les éléments NULL sont ignorés afin qu'ils n'affectent pas la sortie.

Pour en savoir plus sur la version agrégée de ST_UNION_AGG, consultez la section sur la fonction ST_UNION.

Type renvoyé

GEOGRAPHY

ST_X

ST_X(geography_expression)

Description

Renvoie la longitude en degrés de la valeur GEOGRAPHY d'entrée à un seul point.

Pour toute valeur GEOGRAPHY d'entrée qui n'est pas constituée d'un seul point, y compris une valeur GEOGRAPHY vide, ST_X renvoie une erreur. Utilisez le préfixe SAFE. pour obtenir NULL.

Type renvoyé

FLOAT64

Exemple

L'exemple suivant utilise ST_X et ST_Y pour extraire les coordonnées de zones géographiques à un seul point.

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

Description

Renvoie la latitude en degrés de la valeur GEOGRAPHY d'entrée à un seul point.

Pour toute valeur GEOGRAPHY d'entrée qui n'est pas constituée d'un seul point, y compris une valeur GEOGRAPHY vide, ST_Y renvoie une erreur. Utilisez le préfixe SAFE. pour renvoyer NULL à la place.

Type renvoyé

FLOAT64

Exemple

Pour voir un exemple d'utilisation, consultez la section sur la fonction ST_X.

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

Description

Renvoie TRUE si aucun point de geography_2 n'est en dehors de geography_1 et que les intérieurs s'entrecroisent. Sinon, renvoie FALSE.

REMARQUE : Une valeur GEOGRAPHY ne contient pas sa propre limite. Comparez cette fonction avec ST_COVERS.

Type renvoyé

BOOL

Exemple

La requête suivante vérifie si le polygone POLYGON((1 1, 20 1, 10 20, 1 1)) contient chacun des trois points (0, 0), (1, 1) et (10, 10), qui se trouvent à l'extérieur, sur la limite et à l'intérieur du polygone, respectivement.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | false    |
| POINT(1 1)   | false    |
| POINT(10 10) | true     |
+--------------+----------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

Description

Renvoie FALSE si geography_1 ou geography_2 est vide. Renvoie TRUE si aucun point de geography_1 ne se trouve à l'extérieur de geography_2.

Pour deux valeurs GEOGRAPHY nommées a et b, ST_COVEREDBY(a, b) renvoie le même résultat que ST_COVERS(b, a). Notez l'ordre inverse des arguments.

Type renvoyé

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

Description

Renvoie FALSE si geography_1 ou geography_2 est vide. Renvoie TRUE si aucun point de geography_2 ne se trouve à l'extérieur de geography_1.

Type renvoyé

BOOL

Exemple

La requête suivante vérifie si le polygone POLYGON((1 1, 20 1, 10 20, 1 1)) couvre chacun des trois points (0, 0), (1, 1) et (10, 10), qui se trouvent à l'extérieur, sur la limite et à l'intérieur du polygone, respectivement.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | false  |
| POINT(1 1)   | true   |
| POINT(10 10) | true   |
+--------------+--------+

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

Description

Renvoie TRUE si l'intersection de geography_1 et geography_2 est vide, c'est-à-dire qu'aucun point de geography_1 ne figure également dans geography_2.

ST_DISJOINT est la négation logique de ST_INTERSECTS.

Type renvoyé

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2), distance)

ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

Description

Renvoie TRUE si la distance entre au moins un point de geography_1 et un point de geography_2 est inférieure ou égale à la distance donnée par l'argument distance. Sinon, renvoie FALSE. Si l'une des valeurs GEOGRAPHY d'entrée est vide, ST_DWithin renvoie FALSE. La distance donnée est exprimée en mètres sur la surface de la Terre.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

Description

Renvoie TRUE si geography_1 et geography_2 représentent la même valeur GEOGRAPHY. Plus précisément, cela signifie que l'une des conditions suivantes s'applique :

• ST_COVERS(geography_1, geography_2) = TRUE et ST_COVERS(geography_2, geography_1) = TRUE
• Les paramètres geography_1 et geography_2 sont tous deux vides.

Par conséquent, deux valeurs GEOGRAPHY peuvent être égales même si l’ordre des points ou des sommets diffère, dans la mesure où ils représentent toujours la même structure géométrique.

Contraintes

Il n'est pas garanti que ST_EQUALS soit une fonction transitive.

Type renvoyé

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Description

Renvoie TRUE si l'intersection des ensembles de points de geography_1 et geography_2 n'est pas vide. Ainsi, cette fonction renvoie TRUE si au moins un point apparaît dans les deux valeurs GEOGRAPHY d'entrée.

Si ST_INTERSECTS renvoie TRUE, cela signifie que ST_DISJOINT renvoie FALSE.

Type renvoyé

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

Description

Renvoie TRUE en cas d'intersection de geography et du rectangle entre [lng1, lng2] et [lat1, lat2]. Les arêtes du rectangle suivent des lignes constantes de longitude et de latitude. lng1 et lng2 spécifient les lignes de longitude minimale et maximale qui délimitent le rectangle. lat1 et lat2 spécifient les lignes de latitude constante minimale et maximale qui délimitent le rectangle.

Spécifiez tous les arguments de longitude et de latitude en degrés.

Contraintes

Les arguments d'entrée sont soumis aux contraintes suivantes :

• Les latitudes doivent être comprises dans la plage de degrés [-90, 90].
• Les longitudes doivent être comprises dans la plage de degrés [-180, 180].

Type renvoyé

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

Description

Renvoie TRUE pour autant que les deux conditions suivantes soient remplies :

1. geography_1 et geography_2 s'entrecroisent.
2. L'intérieur de geography_1 et l'intérieur de geography_2 sont disjoints.

Type renvoyé

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Description

Renvoie TRUE si aucun point de geography_1 n'est en dehors de geography_2, et que les intérieurs de geography_1 et geography_2 s'entrecroisent.

Pour deux zones géographiques nommées a et b, ST_WITHIN(a, b) renvoie le même résultat que ST_CONTAINS(b, a). Notez l'ordre inverse des arguments.

Type renvoyé

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

Description

Renvoie TRUE si la valeur GEOGRAPHY donnée est vide, c'est-à-dire que la valeur GEOGRAPHY ne contient ni point, ni ligne, ni polygone.

REMARQUE : Une valeur GEOGRAPHY BigQuery vide n'est pas associée à une forme géométrique particulière. Par exemple, les résultats des expressions ST_GEOGFROMTEXT('POINT EMPTY') et ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') sont identiques.

Type renvoyé

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

Description

Renvoie TRUE si le nombre total de points, de polylignes et de polygones est supérieur à un.

Une valeur GEOGRAPHY vide n'est pas une collection.

Type renvoyé

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

Description

Renvoie la dimension de l'élément ayant la dimension la plus élevée dans la valeur GEOGRAPHY d'entrée.

La dimension de chaque élément possible est la suivante :

• La dimension d'un point est 0.
• La dimension d'une polyligne est 1.
• La dimension d'un polygone est 2.

Si la valeur GEOGRAPHY d'entrée est vide, ST_DIMENSION renvoie -1.

Type renvoyé

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

Description

Renvoie le nombre de sommets dans la valeur GEOGRAPHY d'entrée. Cela inclut le nombre de points, de sommets de polylignes et de sommets de polygones.

REMARQUE : le premier et le dernier sommet d'un anneau de polygone sont comptés comme des sommets distincts.

Type renvoyé

INT64

ST_AREA

ST_AREA(geography_expression)

ST_AREA(geography_expression, use_spheroid)

Description

Renvoie l'aire, exprimée en mètres carrés, couverte par les polygones dans la valeur GEOGRAPHY d'entrée.

Si geography_expression est un point ou une ligne, renvoie zéro. Si geography_expression est une collection, renvoie l'aire des polygones que celle-ci contient. Si la collection ne contient pas de polygones, renvoie zéro.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)

ST_DISTANCE(geography_1, geography_2, use_spheroid)

Description

Renvoie la distance la plus courte, exprimée en mètres, entre deux valeurs GEOGRAPHY non vides.

Si l'une des valeurs GEOGRAPHY d'entrée est vide, ST_DISTANCE renvoie NULL.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)

ST_LENGTH(geography_expression, use_spheroid)

Description

Renvoie la longueur totale, exprimée en mètres, des lignes de la valeur GEOGRAPHY d'entrée.

Si geography_expression est un point ou un polygone, renvoie zéro. Si geography_expression est une collection, renvoie la longueur des lignes que celle-ci contient. Si la collection ne contient pas de lignes, renvoie zéro.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)

ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

Renvoie la distance la plus longue, exprimée en mètres, entre deux valeurs GEOGRAPHY non vides. Autrement dit, il s'agit de la distance entre deux sommets, où le premier sommet se trouve dans la première valeur GEOGRAPHY, et où le second sommet se trouve dans la seconde valeur GEOGRAPHY. Si geography_1 et geography_2 sont la même valeur GEOGRAPHY, la fonction renvoie la distance entre les deux sommets les plus éloignés dans cette valeur GEOGRAPHY.

Si l'une des valeurs GEOGRAPHY d'entrée est vide, ST_MAXDISTANCE renvoie NULL.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)

ST_PERIMETER(geography_expression, use_spheroid)

Description

Renvoie la longueur, exprimée en mètres, de la limite des polygones dans la valeur GEOGRAPHY d'entrée.

Si geography_expression est un point ou une ligne, renvoie zéro. Si geography_expression est une collection, renvoie le périmètre des polygones que celle-ci contient. Si la collection ne contient pas de polygones, renvoie zéro.

Le paramètre use_spheroid facultatif détermine la manière dont cette fonction mesure la distance. Si use_spheroid a la valeur FALSE, la fonction mesure la distance sur la surface d'une sphère parfaite.

Le paramètre use_spheroid n'accepte actuellement que la valeur FALSE. La valeur par défaut de use_spheroid est FALSE.

Type renvoyé

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

Description

Renvoie une valeur GEOGRAPHY représentant l'union des ensembles de points de toutes les valeurs GEOGRAPHY d'entrée.

ST_UNION_AGG ignore l'entrée NULL des valeurs GEOGRAPHY.

Pour en savoir plus sur la version non agrégée de ST_UNION, consultez la section sur la fonction ST_UNION_AGG.

Type renvoyé

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

Description

Calcule le centroïde de l'ensemble de valeurs GEOGRAPHY d'entrée sous la forme d'une valeur GEOGRAPHY à un seul point.

Le centroïde de l'ensemble de valeurs GEOGRAPHY d'entrée est la moyenne pondérée du centroïde de chaque valeur GEOGRAPHY individuelle. Seules les valeurs GEOGRAPHY ayant la dimension la plus élevée présentes dans l'entrée contribuent au centroïde de l'ensemble entier. Par exemple, si l'entrée contient à la fois des valeurs GEOGRAPHY avec des lignes et des valeurs GEOGRAPHY ne contenant que des points, ST_CENTROID_AGG renvoie la moyenne pondérée des valeurs GEOGRAPHY avec des lignes, car celles-ci ont la dimension maximale. Dans cet exemple, ST_CENTROID_AGG ignore les valeurs GEOGRAPHY ne contenant que des points lors du calcul du centroïde agrégé.

ST_CENTROID_AGG ignore l'entrée NULL des valeurs GEOGRAPHY.

Pour en savoir plus sur la version non agrégée de ST_CENTROID_AGG et sur la définition du centroïde d'une valeur GEOGRAPHY individuelle, consultez la section concernant la fonction ST_CENTROID.

Type renvoyé

GEOGRAPHY

Exemple

Les requêtes suivantes calculent le centroïde agrégé sur un ensemble de valeurs GEOGRAPHY. L'entrée de la première requête ne contient que des points. Par conséquent, chaque valeur contribue au centroïde agrégé. Notez également que ST_CENTROID_AGG n'équivaut pas à appeler ST_CENTROID sur le résultat de ST_CENTROID_AGG. Les doubles sont supprimés par l'opération d'union, ce qui n'est pas le cas avec la fonction ST_UNION_AGG. L'entrée de la seconde requête a des dimensions mixtes, et seules les valeurs ayant la dimension la plus élevée de l'ensemble, c'est-à-dire les lignes, affectent le centroïde agrégé.

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)')
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+

https://en.wikipedia.org/wiki/Geohash "GeoHash"

Fonctions de sécurité

BigQuery accepte les fonctions de sécurité ci-après.

SESSION_USER

SESSION_USER()

Description

Renvoie l'adresse e-mail de l'utilisateur qui exécute la requête.

Type de données renvoyé

STRING

Exemple

SELECT SESSION_USER() as user;

+----------------------+
| user                 |
+----------------------+
| [e-mail]     |
+----------------------+

Fonctions UUID

BigQuery accepte les fonctions d'identifiant unique universel (UUID, Universally Unique Identifier) ci-après.

GENERATE_UUID

GENERATE_UUID()

Description

Renvoie un UUID aléatoire sous forme de chaîne (STRING). La chaîne (STRING) renvoyée se compose de 32 chiffres hexadécimaux répartis dans cinq groupes séparés par des traits d'union, au format 8-4-4-4-12. Les chiffres hexadécimaux représentent 122 bits aléatoires et 6 bits fixes, conformément à la section 4.4 de la norme RFC 4122. La chaîne (STRING) renvoyée est en minuscules.

Type de données renvoyé

STRING

Exemple

La requête ci-après génère un UUID aléatoire.

SELECT GENERATE_UUID() AS uuid;

La requête ci-dessus génère un résultat de ce type :

+--------------------------------------+
| uuid                                 |
+--------------------------------------+
| 4192bff0-e1e0-43ce-a4db-912808c32493 |
+--------------------------------------+

Fonctions Net

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Description

Convertit une adresse IPv4 ou IPv6 du format texte (STRING) au format binaire (BYTES) dans l'ordre des octets sur le réseau.

Cette fonction accepte les formats suivants pour addr_str :

• IPv4 : quatre nombres séparés par des points, par exemple 10.1.2.3.
• IPv6 : éléments séparés par des signes deux-points, par exemple 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Pour plus d'exemples, consultez la page IP Version 6 Addressing Architecture.

Cette fonction n'accepte pas le format CIDR, tel que 10.1.2.3/32.

Si cette fonction reçoit une entrée NULL, elle renvoie NULL. Si l'entrée est considérée comme non valide, une erreur OUT_OF_RANGE se produit.

Type de données renvoyé

BYTES

Exemple

SELECT
  addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128'
]) AS addr_str;

addr_str	ip_from_string
48.49.50.51	b"0123"
::1	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445	b"0123456789@ABCDE"
::ffff:192.0.2.128	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

Description

Semblable à NET.IP_FROM_STRING, mais renvoie NULL au lieu de générer une erreur si l'entrée n'est pas valide.

Type de données renvoyé

BYTES

Exemple

SELECT
  addr_str,
  FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128',
  '48.49.50.51/32',
  '48.49.50',
  '::wxyz'
]) AS addr_str;

addr_str	safe_ip_from_string
48.49.50.51	b"0123"
::1	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445	b"0123456789@ABCDE"
::ffff:192.0.2.128	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
48.49.50.51/32	NULL
48.49.50	NULL
::wxyz	NULL

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

Description Convertit une adresse IPv4 ou IPv6 du format binaire (BYTES) au format texte (STRING) dans l'ordre des octets sur le réseau.

Si l'entrée correspond à 4 octets, cette fonction renvoie une adresse IPv4 au format STRING. Si l'entrée correspond à 16 octets, une adresse IPv6 est renvoyée au format STRING.

Si cette fonction reçoit une entrée NULL, elle renvoie NULL. Si la longueur de l'entrée est différente de 4 ou 16, une erreur OUT_OF_RANGE se produit.

Type de données renvoyé

STRING

Exemple

SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
  b"0123",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
  b"0123456789@ABCDE",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;

addr_bin	ip_to_string
b"0123"	48.49.50.51
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"	::1
b"0123456789@ABCDE"	3031:3233:3435:3637:3839:4041:4243:4445
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"	::ffff:192.0.2.128

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

Description

Renvoie un masque de réseau, c'est-à-dire une séquence d'octets d'une longueur égale à num_output_bytes, où les prefix_length premiers bits sont définis sur 1, et les autres bits sur 0. num_output_bytes et prefix_length sont de type INT64. Cette fonction génère une erreur si la valeur de num_output_bytes est différente de 4 (pour IPv4) ou de 16 (pour IPv6). Elle génère également une erreur si la valeur de prefix_length est négative ou supérieure à 8 * num_output_bytes.

Type de données renvoyé

BYTES

Exemple

SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
  STRUCT(4 as x, 0 as y),
  (4, 20),
  (4, 32),
  (16, 0),
  (16, 1),
  (16, 128)
]);

x	y	ip_net_mask
4	0	b"\x00\x00\x00\x00"
4	20	b"\xff\xff\xf0\x00"
4	32	b"\xff\xff\xff\xff"
16	0	b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16	1	b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16	128	b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

Description Prend addr_bin, une adresse IPv4 ou IPv6 au format binaire (BYTES) dans l'ordre des octets du réseau, et renvoie une adresse de sous-réseau au même format. Le résultat présente la même longueur que addr_bin. Les prefix_length premiers bits correspondent à ceux de addr_bin, et les bits restants sont définis sur 0.

Cette fonction génère une erreur si la valeur de LENGTH(addr_bin) est différente de 4 ou de 16, ou si la valeur de prefix_len est négative ou supérieure à LENGTH(addr_bin) * 8.

Type de données renvoyé

BYTES

Exemple

SELECT
  FORMAT("%T", x) as addr_bin, prefix_length,
  FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
  STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
  (b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
  (b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
  (b'0123456789@ABCDE', 80)
]);

addr_bin	prefix_length	ip_trunc
b"\xaa\xbb\xcc\xdd"	0	b"\x00\x00\x00\x00"
b"\xaa\xbb\xcc\xdd"	11	b"\xaa\xa0\x00\x00"
b"\xaa\xbb\xcc\xdd"	12	b"\xaa\xb0\x00\x00"
b"\xaa\xbb\xcc\xdd"	24	b"\xaa\xbb\xcc\x00"
b"\xaa\xbb\xcc\xdd"	32	b"\xaa\xbb\xcc\xdd"
b"0123456789@ABCDE"	80	b"0123456789\x00\x00\x00\x00\x00\x00"

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

Description

Convertit une adresse IPv4 du format entier au format binaire (BYTES) dans l'ordre des octets sur le réseau. Dans l'entrée entière, le bit le moins significatif de l'adresse IP est stocké dans le bit le moins significatif de l'entier, quelle que soit l'architecture de l'hôte ou du client. Par exemple, 1 signifie 0.0.0.1, et 0x1FF signifie 0.0.1.255.

Cette fonction vérifie que les 32 bits les plus significatifs sont tous définis sur 0, ou que les 33 bits les plus significatifs sont tous définis sur 1 (le signe est étendu à partir d'un entier de 32 bits). En d'autres termes, l'entrée doit être comprise dans la plage [-0x80000000, 0xFFFFFFFF]. Dans le cas contraire, cette fonction génère une erreur.

Cette fonction n'est pas compatible avec IPv6.

Type de données renvoyé

BYTES

Exemple

SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
  SELECT CAST(x_hex AS INT64) x, x_hex
  FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);

x	x_hex	ipv4_from_int64
0	0x0	b"\x00\x00\x00\x00"
11259375	0xABCDEF	b"\x00\xab\xcd\xef"
4294967295	0xFFFFFFFF	b"\xff\xff\xff\xff"
-1	-0x1	b"\xff\xff\xff\xff"
-2	-0x2	b"\xff\xff\xff\xfe"

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

Description

Convertit une adresse IPv4 du format binaire (BYTES) au format entier dans l'ordre des octets sur le réseau. Dans la sortie entière, le bit le moins significatif de l'adresse IP est stocké dans le bit le moins significatif de l'entier, quelle que soit l'architecture de l'hôte ou du client. Par exemple, 1 signifie 0.0.0.1, et 0x1FF signifie 0.0.1.255. La sortie est comprise dans la plage [0, 0xFFFFFFFF].

Si la longueur de l'entrée est différente de 4, cette fonction génère une erreur.

Cette fonction n'est pas compatible avec IPv6.

Type de données renvoyé

INT64

Exemple

SELECT
  FORMAT("%T", x) AS addr_bin,
  FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;

addr_bin	ipv4_to_int64
b"\x00\x00\x00\x00"	0x0
b"\x00\xab\xcd\xef"	0xABCDEF
b"\xff\xff\xff\xff"	0xFFFFFFFF

NET.HOST

NET.HOST(url)

Description

Prend une URL au format STRING et renvoie l'hôte dans ce même format. Pour des résultats optimaux, les valeurs d'URL doivent être conformes au format défini par la norme RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent. Si elle ne peut pas analyser l'entrée, elle renvoie NULL.

Remarque : La fonction n'effectue aucune normalisation.

Type de données renvoyé

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Entrée	Description	Hôte	Suffixe	Domaine
""	entrée non valide	NULL	NULL	NULL
"http://abc.xyz"	URL standard	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public	"a.b"	NULL	NULL
"https://[::1]:80"	URL standard avec hôte IPv6	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	URL standard avec nom de domaine internationalisé	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
"    www.Example.Co.UK    "	URL non standard avec espaces et lettres majuscules, et sans schéma	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK"
"mailto:?to=&subject=&body="	URI au lieu d'URL – incompatible	"mailto"	NULL	NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Description

Prend une URL au format STRING et renvoie le suffixe public (tel que com, org ou net) dans ce même format. Un suffixe public est un domaine de l'ICANN enregistré sur publicsuffix.org. Pour des résultats optimaux, les valeurs d'URL doivent être conformes au format défini par la norme RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent.

Cette fonction renvoie NULL si l'une des conditions suivantes est remplie :

• La fonction ne peut pas analyser l'hôte à partir de l'entrée.
• L'hôte analysé contient des points adjacents au milieu (pas au début ni à la fin).
• L'hôte analysé ne contient aucun suffixe public.

Avant de rechercher le suffixe public, cette fonction normalise temporairement l'hôte en convertissant les majuscules latines en minuscules et en encodant tous les caractères non-ASCII avec Punycode. La fonction renvoie ensuite le suffixe public en tant que partie de l'hôte d'origine plutôt que de l'hôte normalisé.

Remarque : La fonction n'effectue pas de normalisation Unicode.

Remarque : Les données relatives aux suffixes publics du site publicsuffix.org contiennent également des domaines privés. Cette fonction ignore les domaines privés.

Remarque : Les données relatives aux suffixes publics peuvent évoluer avec le temps. Par conséquent, une entrée qui produit un résultat NULL maintenant pourra renvoyer une valeur non NULL dans l'avenir.

Type de données renvoyé

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Entrée	Description	Hôte	Suffixe	Domaine
""	entrée non valide	NULL	NULL	NULL
"http://abc.xyz"	URL standard	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public	"a.b"	NULL	NULL
"https://[::1]:80"	URL standard avec hôte IPv6	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	URL standard avec nom de domaine internationalisé	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
"    www.Example.Co.UK    "	URL non standard avec espaces et lettres majuscules, et sans schéma	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK
"mailto:?to=&subject=&body="	URI au lieu d'URL – incompatible	"mailto"	NULL	NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Description

Prend une URL au format STRING et renvoie le domaine enregistré ou pouvant être enregistré (le suffixe public précédé d'une étiquette) au format STRING. Pour de meilleurs résultats, les valeurs d'URL doivent être conformes au format défini par la RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent.

Cette fonction renvoie NULL si l'une des conditions suivantes est remplie :

• La fonction ne peut pas analyser l'hôte à partir de l'entrée.
• L'hôte analysé contient des points adjacents au milieu (pas au début ni à la fin).
• L'hôte analysé ne contient aucun suffixe public.
• L'hôte analysé ne contient qu'un suffixe public, qui n'est pas précédé d'une étiquette.

Avant de rechercher le suffixe public, cette fonction normalise temporairement l'hôte en convertissant les majuscules latines en minuscules et en encodant tous les caractères non-ASCII avec Punycode. Elle renvoie ensuite le domaine enregistré ou pouvant être enregistré en tant que partie de l'hôte d'origine plutôt que de l'hôte normalisé.

Remarque : La fonction n'effectue pas de normalisation Unicode.

Remarque : Les données relatives aux suffixes publics du site publicsuffix.org contiennent également des domaines privés. Cette fonction ne traite pas un domaine privé comme un suffixe public. Par exemple, si "us.com" est un domaine privé compris dans les données relatives aux suffixes publics, NET.REG_DOMAIN("foo.us.com") renvoie "us.com" (le suffixe public "com", précédé de l'étiquette "us") plutôt que "foo.us.com" (le domaine privé "us.com", précédé de l'étiquette "foo").

Remarque : Les données relatives aux suffixes publics peuvent évoluer avec le temps. Par conséquent, une entrée qui produit un résultat NULL maintenant pourra renvoyer une valeur non NULL dans l'avenir.

Type de données renvoyé

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);

Entrée	Description	Hôte	Suffixe	Domaine
""	entrée non valide	NULL	NULL	NULL
"http://abc.xyz"	URL standard	"abc.xyz"	"xyz"	"abc.xyz"
"//user:password@a.b:80/path?query"	URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public	"a.b"	NULL	NULL
"https://[::1]:80"	URL standard avec hôte IPv6	"[::1]"	NULL	NULL
"http://例子.卷筒纸.中国"	URL standard avec nom de domaine internationalisé	"例子.卷筒纸.中国"	"中国"	"卷筒纸.中国"
"    www.Example.Co.UK    "	URL non standard avec espaces et lettres majuscules, et sans schéma	"www.Example.Co.UK"	"Co.UK"	"Example.Co.UK"
"mailto:?to=&subject=&body="	URI au lieu d'URL – incompatible	"mailto"	NULL	NULL

Opérateurs

Les opérateurs sont représentés par des caractères spéciaux ou des mots-clés ; ils n'utilisent pas la syntaxe d'appel de fonction. Un opérateur manipule un certain nombre d'entrées de données (ces entrées de données sont également appelées opérandes), puis renvoie un résultat.

Conventions communes :

• Sauf indication contraire, tous les opérateurs renvoient NULL lorsque l'un des opérandes est NULL.
• Tous les opérateurs génèrent une erreur lorsque le résultat du calcul déborde.
• Pour toutes les opérations en virgule flottante, +/-inf et NaN ne peuvent être renvoyés que si l'un des opérandes est +/-inf ou NaN. Dans les autres cas, une erreur est renvoyée.

Le tableau ci-dessous répertorie tous les opérateurs de BigQuery, classés de la priorité la plus élevée à la plus faible, c'est-à-dire en fonction de l'ordre selon lequel ils seront évalués dans une instruction.

Ordre de priorité	Opérateur	Types de données d'entrée	Nom	Arité de l'opérateur
1	.	STRUCT	Opérateur d'accès au champ Membre	Binaire
	[ ]	ARRAY	Position du tableau. Doit être utilisé avec OFFSET ou ORDINAL (consultez la section Fonctions de tableau).	Binaire
2	-	Tous les types numériques	Moins unaire	Unaire
	~	Entier ou BYTES	Opérateur NOT (PAS) au niveau du bit	Unaire
3	*	Tous les types numériques	Multiplication	Binaire
	/	Tous les types numériques	Division	Binaire
4	+	Tous les types numériques	Addition	Binaire
	-	Tous les types numériques	Soustraction	Binaire
5	<<	Entier ou BYTES	Décalage à gauche bit à bit	Binaire
	>>	Entier ou BYTES	Décalage à droite bit à bit	Binaire
6	&	Entier ou BYTES	Opérateur AND (ET) au niveau du bit	Binaire
7	^	Entier ou BYTES	Opérateur XOR (OU exclusif) au niveau du bit	Binaire
8	|	Entier ou BYTES	Opérateur OR (OU) au niveau du bit	Binaire
9 (Opérateurs de comparaison)	=	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Equal (Égal à)	Binaire
	<	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Less than (Inférieur à)	Binaire
	>	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Greater than (Supérieur à)	Binaire
	<=	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Less than or equal to (Inférieur ou égal à)	Binaire
	>=	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Greater than or equal to (Supérieur ou égal à)	Binaire
	!=, <>	Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données.	Not Equal (Non égal à)	Binaire
	[NOT] LIKE	STRING et octet	La valeur correspond [ne correspond pas] au modèle spécifié	Binaire
	[NOT] BETWEEN	Tous types comparables. Consultez la section "Types de données" pour obtenir la liste.	La valeur est [n'est pas] comprise dans la plage spécifiée	Binaire
	[NOT] IN	Tous types comparables. Consultez la section "Types de données" pour obtenir la liste.	La valeur est [n'est pas] comprise dans l'ensemble de valeurs spécifié	Binaire
	IS [NOT] NULL	Tous	La valeur est [n'est pas] NULL	Unaire
	IS [NOT] TRUE	BOOL	La valeur est [n'est pas] TRUE.	Unaire
	IS [NOT] FALSE	BOOL	La valeur est [n'est pas] FALSE.	Unaire
10	NOT	BOOL	Logical NOT (Opérateur logique PAS)	Unaire
11	AND	BOOL	Logical AND (Opérateur logique ET)	Binaire
12	OR	BOOL	Logical OR (Opérateur logique OU)	Binaire

Les opérateurs ayant le même niveau de priorité sont considérés selon un schéma "associatif gauche". Cela signifie que le regroupement de ces opérateurs commence par la gauche, puis se poursuit vers la droite. Par exemple, l'expression :

x AND y AND z

est interprétée comme :

( ( x AND y ) AND z )

L'expression :

x * y / z

est interprétée comme :

( ( x * y ) / z )

Tous les opérateurs de comparaison ont la même priorité, mais les opérateurs de comparaison ne sont pas associatifs. Par conséquent, des parenthèses sont nécessaires afin de résoudre les ambiguïtés. Exemple :

(x < y) IS FALSE

Opérateurs d'accès aux éléments

Opérateur	Syntaxe	Types de données d'entrée	Type de données de résultat	Description
.	expression.nom_de_champ_1...	STRUCT	Type T stocké dans nom_de_champ_1	Opérateur point. Peut être utilisé pour accéder à des champs imbriqués, par exemple : expression.nom_de_champ_1.nom_de_champ_2...
[ ]	array_expression [position_keyword (int_expression)]	Consultez la section "Fonctions de tableau".	Type T stocké dans un tableau	position_keyword est soit OFFSET, soit ORDINAL. Reportez-vous à la section Fonctions de tableau pour en savoir plus sur les deux fonctions qui utilisent cet opérateur.

Opérateurs arithmétiques

Tous les opérateurs arithmétiques acceptent les entrées de type numérique T, et les résultats sont de type T sauf indication contraire dans la description ci-dessous :

Nom	Syntaxe
Addition	X + Y
Soustraction	X - Y
Multiplication	X * Y
Division	X / Y
Moins unaire	- X

REMARQUE : Les opérations de division par zéro renvoient une erreur. Pour qu'un résultat différent soit renvoyé, utilisez la fonction IEEE_DIVIDE ou la fonction SAFE_DIVIDE.

Types de résultat pour l'addition et la multiplication :

	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Types de résultat pour la soustraction :

	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Types de résultats pour la division :

	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Types de résultat pour Moins unaire :

Type de données d'entrée	Type de données de résultat
INT64	INT64
NUMERIC	NUMERIC
FLOAT64	FLOAT64

Opérateurs bit à bit

Tous les opérateurs fonctionnant au niveau du bit renvoient le même type et la même longueur que le premier opérande.

Nom	Syntaxe	Type de données d'entrée	Description
Opérateur NOT (PAS) au niveau du bit	~ X	Entier ou BYTES	Effectue une négation logique sur chaque bit, en formant le complément de la valeur binaire donnée pour chaque bit.
Opérateur OR (OU) au niveau du bit	X | Y	X : entier ou BYTES Y : même type que X	Prend deux combinaisons binaires de longueur égale et effectue l'opération logique "OU inclusif" sur chaque paire de bits correspondants. Cet opérateur génère une erreur si X et Y sont des séquences BYTES de longueurs différentes.
Opérateur XOR (OU exclusif) au niveau du bit	X ^ Y	X : entier ou BYTES Y : même type que X	Prend deux combinaisons binaires de longueur égale et effectue l'opération logique "OU exclusif" sur chaque paire de bits correspondants. Cet opérateur génère une erreur si X et Y sont des séquences BYTES de longueurs différentes.
Opérateur AND (ET) au niveau du bit	X & Y	X : entier ou BYTES Y : même type que X	Prend deux combinaisons binaires de longueur égale et effectue l'opération logique "ET" sur chaque paire de bits correspondants. Cet opérateur génère une erreur si X et Y sont des séquences BYTES de longueurs différentes.
Décalage à gauche	X << Y	X : entier ou BYTES Y : INT64	Décale le premier opérande X vers la gauche. Cet opérateur renvoie 0 ou une séquence d'octets de b'\x00' si le deuxième opérande Y est supérieur ou égal à la longueur en bits du premier opérande X (par exemple, 64 si X est de type INT64). Cet opérateur génère une erreur si Y est négatif.
Décalage à droite	X >> Y	X : entier ou BYTES Y : INT64	Décale le premier opérande X vers la droite. Cet opérateur ne signe pas d'extension de bit avec un type signé (c'est-à-dire qu'il remplit les bits vacants à gauche avec des 0). Cet opérateur renvoie 0 ou une séquence d'octets de b'\x00' si le deuxième opérande Y est supérieur ou égal à la longueur en bits du premier opérande X (par exemple, 64 si X est de type INT64). Cet opérateur génère une erreur si Y est négatif.

Opérateurs logiques

Tous les opérateurs logiques n'autorisent que l'entrée BOOL.

Nom	Syntaxe	Description
Logical NOT (Opérateur logique PAS)	NOT X	Renvoie FALSE si l'entrée est TRUE. Renvoie TRUE si l'entrée est FALSE. Renvoie NULL dans les autres cas.
Logical AND (Opérateur logique ET)	X AND Y	Renvoie FALSE si au moins une entrée est FALSE. Renvoie TRUE si X et Y sont TRUE. Renvoie NULL dans les autres cas.
Logical OR (Opérateur logique OU)	X OR Y	Renvoie FALSE si X et Y sont tous deux FALSE. Renvoie TRUE si au moins une entrée est TRUE. Renvoie NULL dans les autres cas.

Opérateurs de comparaison

Les comparaisons renvoient toujours une valeur de type BOOL. Les comparaisons nécessitent généralement que les deux opérandes soient du même type. Si les opérandes sont de types différents et que BigQuery peut convertir les valeurs de ces types en un type commun sans perte de précision, BigQuery les convertit généralement (par coercition) dans ce type commun pour la comparaison. En pareil cas, BigQuery va généralement convertir (par coercition) des types littéraux en type "non littéral" si un tel type est présent. Les types de données comparables sont définis dans la section Types de données.

Les STRUCT n'acceptent que 4 opérateurs de comparaison : Equal (=), Not Equal (!= et <>) et IN.

Les règles suivantes s'appliquent lors de la comparaison de ces types de données :

• FLOAT64 : toutes les comparaisons avec NaN renvoient FALSE, sauf pour != et <>, qui renvoient TRUE.
• BOOL : FALSE est inférieur à TRUE.
• STRING : les chaînes sont comparées point de code par point de code. Par conséquent, pour garantir que des chaînes canoniquement équivalentes seront bien considérées comme égales, il est nécessaire de les normaliser en premier lieu.
• NULL : la convention tient ici. Toute opération avec une entrée NULL renvoie NULL.

Nom	Syntaxe	Description
Less Than (Inférieur à)	X < Y	Renvoie TRUE (vrai) si X est inférieur à Y.
Less Than or Equal To (Inférieur ou égal à)	X <= Y	Renvoie TRUE (vrai) si X est inférieur ou égal à Y.
Greater Than (Supérieur à)	X > Y	Renvoie TRUE (vrai) si X est supérieur à Y.
Greater Than or Equal To (Supérieur ou égal à)	X >= Y	Renvoie TRUE (vrai) si X est supérieur ou égal à Y.
Equal (Égal à)	X = Y	Renvoie TRUE (vrai) si X est égal à Y.
Not Equal (Non égal à)	X != Y X <> Y	Renvoie TRUE (vrai) si X n'est pas égal à Y.
BETWEEN (entre)	X [NOT] BETWEEN Y AND Z	Renvoie TRUE (vrai) si X est [n'est pas] compris dans la plage spécifiée. Le résultat de "X BETWEEN Y AND Z" équivaut à "Y <= X AND X <= Z", mais X n'est évalué qu'une fois dans le premier cas.
LIKE (comme)	X [NOT] LIKE Y	Vérifie si la STRING dans le premier opérande X correspond à un schéma spécifié par le deuxième opérande Y. Les expressions peuvent contenir les caractères suivants : Un signe de pourcentage "%" correspond à un nombre quelconque de caractères ou d'octets. Un trait de soulignement "_" correspond à un caractère ou un octet unique. Vous pouvez échapper les caractères "\", "_" ou "%" à l'aide de deux barres obliques inverses. Par exemple, "\\%". Si vous utilisez des chaînes brutes, une seule barre oblique inverse est nécessaire. Par exemple, r"\%".
IN	Multiple (voir ci-dessous)	Renvoie FALSE si l'opérande de droite est vide. Renvoie NULL si l'opérande de gauche est NULL. Renvoie TRUE ou NULL (mais jamais FALSE) si l'opérande de droite contient NULL. Les arguments situés de part et d'autre de l'opérateur "IN" sont des expressions génériques. Il n'est pas absolument nécessaire que l'un des deux opérandes soit un littéral, bien que l'utilisation d'un littéral à droite soit l'approche la plus courante. X n'est évalué qu'une fois.

Lorsque vous effectuez un test d'égalité pour des valeurs ayant un type de données STRUCT, il est possible qu'un ou plusieurs champs aient la valeur NULL. Dans ces cas :

• Si toutes les valeurs de champ non nulles sont égales, la comparaison renvoie "NULL".
• Si certaines valeurs de champ non nulles ne sont pas égales, la comparaison renvoie "FALSE".

Le tableau suivant montre comment les types de données STRUCT sont comparés lorsqu'ils contiennent des champs dont la valeur est NULL.

Struct1	Struct2	Struct1 = Struct2
STRUCT(1, NULL)	STRUCT(1, NULL)	NULL
STRUCT(1, NULL)	STRUCT(2, NULL)	FALSE
STRUCT(1,2)	STRUCT(1, NULL)

NULL

Opérateurs IN

L'opérateur IN accepte les syntaxes suivantes :

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

Les arguments situés de part et d'autre de l'opérateur IN sont des expressions génériques. Il est courant d'utiliser des littéraux sur l'expression située du côté droit, mais cela n'est pas obligatoire.

La sémantique de :

x IN (y, z, ...)

est définie comme équivalente à :

(x = y) OR (x = z) OR ...

et les formulaires de sous-requête et de tableau sont définis de la même manière.

x NOT IN ...

équivaut à :

NOT(x IN ...)

Le formulaire "UNNEST" traite une analyse de tableau comme UNNEST dans la clause FROM :

x [NOT] IN UNNEST(<array expression>)

Ce formulaire est souvent utilisé avec les paramètres de tableau (array_parameter). Par exemple :

x IN UNNEST(@array_parameter)

Remarque : Un tableau (ARRAY) NULL est traité de la même manière qu'un tableau (ARRAY) vide.

Consultez la rubrique Tableaux pour plus d'informations sur l'utilisation de cette syntaxe.

Lorsque l'opérateur IN est utilisé, la sémantique suivante s'applique :

• IN avec une expression vide du côté droit est toujours FALSE
• IN avec une expression NULL du côté gauche et une expression non vide du côté droit est toujours NULL
• IN avec un NULL dans la liste IN ne peut renvoyer que TRUE ou NULL, mais jamais FALSE
• NULL IN (NULL) renvoie NULL
• IN UNNEST(<NULL array>) renvoie FALSE (pas NULL)
• NOT IN avec un NULL dans la liste IN ne peut renvoyer que FALSE ou NULL, mais jamais TRUE

IN peut être utilisé avec des clés composées de plusieurs parties à l'aide de la syntaxe du constructeur de structure. Par exemple :

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

Consultez la section Type de structure de la rubrique "Types de données" pour plus d'informations sur cette syntaxe.

Opérateurs IS

Les opérateurs IS renvoient TRUE ou FALSE pour la condition testée. Ils ne renvoient jamais NULL, même pour les entrées NULL, contrairement aux fonctions IS_INF et IS_NAN définies dans la section Fonctions mathématiques. Si NOT est présent, la valeur BOOL de sortie est inversée.

Syntaxe de la fonction	Type de données d'entrée	Type de données de résultat	Description
X IS [NOT] NULL	N'importe quel type de valeur	BOOL	Renvoie TRUE si l'évaluation de l'opérande X donne NULL, renvoie FALSE dans le cas contraire.
X IS [NOT] TRUE	BOOL	BOOL	Renvoie TRUE si l'évaluation de l'opérande BOOL donne TRUE, renvoie FALSE dans le cas contraire.
X IS [NOT] FALSE	BOOL	BOOL	Renvoie TRUE si l'évaluation de l'opérande BOOL donne FALSE, renvoie FALSE dans le cas contraire.

Expressions conditionnelles

Les expressions conditionnelles imposent des contraintes sur l'ordre d'évaluation de leurs entrées. En substance, elles sont évaluées de gauche à droite (avec possibilité de court-circuitage) et l'évaluation ne porte que sur la valeur de sortie qui a été choisie. Par opposition, les entrées des fonctions standards sont quant à elles toutes évaluées avant l'appel de la fonction. L'option de court-circuitage disponible avec les expressions conditionnelles peut être exploitée pour la gestion des erreurs ou l'optimisation des performances.

Syntaxe	Types de données d'entrée	Type de données de résultat	Description
CASE expr WHEN value THEN result [WHEN ...] [ELSE else_result] END	expr et value : tous les types	result et else_result : supertype de types d'entrée.	Compare successivement expr à la valeur de chaque clause WHEN et retourne le premier résultat où cette comparaison renvoie "true". Les clauses WHEN restantes et else_result ne sont pas évalués. Si la comparaison expr = value renvoie "false" ou NULL pour toutes les clauses WHEN, la fonction renvoie else_result si celui-ci est présent et NULL s'il ne l'est pas. Les expressions expr et value doivent pouvoir être converties implicitement (coercition) en un supertype commun ; les comparaisons d'égalité sont effectuées sur des valeurs "contraintes". Les expressions result et else_result doivent pouvoir être converties (coercition) en un supertype commun.
CASE WHEN cond1 THEN result [WHEN cond2...] [ELSE else_result] END	cond : BOOL	result et else_result : supertype de types d'entrée.	Évalue successivement la condition cond de chaque clause WHEN et renvoie le premier résultat où la condition est "true" ; les clauses WHEN restantes et else_result ne sont pas évalués. Si toutes les conditions sont "false" ou NULL, la fonction renvoie else_result si celui-ci est présent et NULL s'il ne l'est pas. Les expressions result et else_result doivent pouvoir être converties implicitement (coercition) en un supertype commun.
COALESCE(expr1, ..., exprN)	Tous les types	Supertype de types d'entrée.	Renvoie la valeur de la première expression non nulle. Les expressions restantes ne sont pas évaluées. Toutes les expressions en entrée doivent pouvoir être converties implicitement (coercition) en un supertype commun.
IF(cond, true_result, else_result)	cond : BOOL	true_result et else_result : tous les types.	Si cond est "true", la fonction renvoie true_result, sinon elle renvoie else_result. else_result n'est pas évalué si cond est "true". true_result n'est pas évalué si cond est "false" ou NULL. true_result et else_result doivent pouvoir être convertis implicitement (coercition) en un supertype commun.
IFNULL(expr, null_result)	Tous les types	Tous les types ou supertype de types d'entrée.	Si expr est NULL, la fonction renvoie null_result. Sinon, elle renvoie expr. Si expr n'est pas NULL, null_result n'est pas évalué. expr et null_result doivent pouvoir être convertis implicitement (coercition) en un supertype commun. Synonyme de COALESCE(expr, null_result).
NULLIF(expression, expression_to_match)	Tout type T ou sous-type de T	Tout type T ou sous-type de T	Renvoie NULL si expression = expression_to_match est "true", renvoie expression dans le cas contraire. expression et expression_to_match doivent pouvoir être convertis implicitement (coercition) en un supertype commun ; la comparaison d'égalité est effectuée sur des valeurs "contraintes".

Sous-requêtes d'expression

Il existe quatre types de sous-requêtes d'expression (des sous-requêtes utilisées en tant qu'expressions). Les sous-requêtes d'expression renvoient NULL ou une valeur unique, par opposition à une colonne ou une table. En outre, elles doivent être entourées de parenthèses. Pour en savoir plus sur les sous-requêtes, reportez-vous à la rubrique Sous-requêtes.

Type de sous-requête	Type de données de résultat	Description
Scalaire	Tout type T	Une sous-requête entre parenthèses à l'intérieur d'une expression (par exemple, dans la liste SELECT ou la clause WHERE) est interprétée comme une sous-requête scalaire. La liste SELECT d'une sous-requête scalaire doit comporter exactement un champ. Si la sous-requête renvoie exactement une ligne, cette valeur unique correspond au résultat de la sous-requête scalaire. Si la sous-requête ne renvoie aucune ligne, la valeur de la sous-requête scalaire est NULL. Si la sous-requête renvoie plusieurs lignes, une erreur d'exécution se produit et la requête échoue. Lorsque la sous-requête est écrite avec SELECT AS STRUCT, elle peut inclure plusieurs colonnes et la valeur renvoyée est le STRUCT construit. Le fait de sélectionner plusieurs colonnes sans utiliser SELECT AS est considéré comme une erreur.
ARRAY	ARRAY	Permet d'utiliser SELECT AS STRUCT pour construire des tableaux de structures. En revanche, le fait de sélectionner plusieurs colonnes sans utiliser SELECT AS est considéré comme une erreur. Renvoie un tableau vide si la sous-requête ne renvoie aucune ligne. Ne renvoie jamais un tableau NULL.
IN	BOOL	Se présente dans une expression suivant l'opérateur IN. La sous-requête doit générer une seule colonne, dont le type est compatible (pour les comparaisons d'égalité) avec l'expression située à gauche de l'opérateur IN. Renvoie FALSE si la sous-requête ne renvoie aucune ligne. x IN () équivaut à x IN (value, value, ...). Pour obtenir une présentation complète de la sémantique utilisée, consultez la section consacrée à l'opérateur IN dans la rubrique Opérateurs de comparaison.
EXISTS	BOOL	Renvoie TRUE si la sous-requête a généré une ou plusieurs lignes. Renvoie FALSE si la sous-requête ne génère aucune ligne. Ne renvoie jamais NULL. Contrairement à toutes les autres sous-requêtes d'expression, il n'existe ici aucune règle relative à la liste de colonnes. Il est possible de sélectionner n'importe quel nombre de colonnes sans que cela ait une incidence sur le résultat de la requête.

Exemples

Dans les exemples suivants de sous-requêtes d'expression, nous supposons que t.int_array est de type ARRAY<INT64>.

Type	Sous-requête	Type de données de résultat	Notes
Scalaire	(SELECT COUNT(*) FROM t.int_array)	INT64
	(SELECT DISTINCT i FROM t.int_array i)	INT64, éventuellement erreur d'exécution
	(SELECT i FROM t.int_array i WHERE i=5)	INT64, éventuellement erreur d'exécution
	(SELECT ARRAY_AGG(i) FROM t.int_array i)	ARRAY	Utilise la fonction d'agrégation "ARRAY_AGG" pour renvoyer un tableau.
	(SELECT 'xxx' a)	STRING
	(SELECT 'xxx' a, 123 b)	Erreur	Renvoie une erreur, car il y a plus d'une colonne.
	(SELECT AS STRUCT 'xxx' a, 123 b)	STRUCT
	(SELECT AS STRUCT 'xxx' a)	STRUCT
ARRAY	ARRAY(SELECT COUNT(*) FROM t.int_array)	ARRAY (de taille 1)
	ARRAY(SELECT x FROM t)	ARRAY
	ARRAY(SELECT 5 a, COUNT(*) b FROM t.int_array)	Erreur	Renvoie une erreur, car il y a plus d'une colonne.
	ARRAY(SELECT AS STRUCT 5 a, COUNT(*) b FROM t.int_array)	ARRAY
	ARRAY(SELECT AS STRUCT i FROM t.int_array i)	ARRAY	Génère un tableau de STRUCT à un champ
	ARRAY(SELECT AS STRUCT 1 x, 2, 3 x)	ARRAY	Renvoie un tableau de STRUCT avec des champs anonymes ou en double.
	ARRAY(SELECT AS TypeName SUM(x) a, SUM(y) b, SUM(z) c from t)	array<TypeName>	Sélection dans un type nommé. Il est supposé que TypeName est un type STRUCT avec des champs a, b et c.
STRUCT	(SELECT AS STRUCT 1 x, 2, 3 x)	STRUCT	Construit une STRUCT avec des champs anonymes ou en double.
EXISTS	EXISTS(SELECT x,y,z FROM table WHERE y=z)	BOOL
	NOT EXISTS(SELECT x,y,z FROM table WHERE y=z)	BOOL
IN	x IN (SELECT y FROM table WHERE z)	BOOL
	x NOT IN (SELECT y FROM table WHERE z)	BOOL

Fonctions de débogage

BigQuery accepte les fonctions de débogage ci-après.

ERROR

ERROR(error_message)

Description

Renvoie une erreur. L'argument error_message est de type STRING.

BigQuery traite la fonction ERROR de la même manière que toute expression pouvant entraîner une erreur : aucune garantie particulière n'est donnée quant à l'ordre d'évaluation suivi.

Type de données renvoyé

BigQuery infère le type renvoyé en contexte.

Exemples

Dans l'exemple suivant, la requête renvoie un message d'erreur si la valeur de la ligne ne correspond pas à l'une des deux valeurs définies.

SELECT
  CASE
    WHEN value = 'foo' THEN 'Value is foo.'
    WHEN value = 'bar' THEN 'Value is bar.'
    ELSE ERROR(concat('Found unexpected value: ', value))
  END AS new_value
FROM (
  SELECT 'foo' AS value UNION ALL
  SELECT 'bar' AS value UNION ALL
  SELECT 'baz' AS value);

Found unexpected value: baz

Dans l'exemple suivant, BigQuery est susceptible d'évaluer la fonction ERROR avant ou après la condition x > 0, car il ne fournit généralement aucune garantie de tri pour les conditions de clause WHERE. En outre, il n'existe aucune garantie particulière pour la fonction ERROR.

SELECT *
FROM (SELECT -1 AS x)
WHERE x > 0 AND ERROR('Example error');

Dans l'exemple qui suit, la clause WHERE évalue une condition IF, ce qui garantit que BigQuery n'évaluera la fonction ERROR que si la condition échoue.

SELECT *
FROM (SELECT -1 AS x)
WHERE IF(x > 0, true, ERROR(FORMAT('Error: x must be positive but is %t', x)));'

Error: x must be positive but is -1