Expressions, fonctions et opérateurs en SQL standard

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

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.

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

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 inclut, sans s'y limiter, le casting, la coercition et le supertype.

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.
Un supertype est un type commun auquel deux ou plusieurs expressions peuvent être converties (coercition).

Certaines conversions ont également leurs propres noms de fonction, tels que PARSE_DATE(). Pour en savoir plus sur ces fonctions, consultez la section Fonctions de conversion.

Comparaison entre les fonctions de casting et de coercition

Le tableau suivant récapitule toutes les options disponibles associées aux fonctions de casting et de coercition pour les types de données BigQuery. La colonne Coercition 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 en savoir plus, consultez les sections Coercition de littéraux et Coercition de paramètres.

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

Casting

La plupart des types de données peuvent être convertis d'un type à un autre à l'aide de la fonction CAST. En cas d'utilisation de CAST, une requête peut échouer si BigQuery est incapable d'effectuer le casting. Si vous souhaitez protéger vos requêtes contre ce type d'erreur, vous pouvez utiliser SAFE_CAST. Pour en savoir plus sur les règles CAST et SAFE_CAST, ainsi que sur les autres fonctions de casting, consultez la section Fonctions de conversion.

Coercition

Si nécessaire, BigQuery convertit (par coercition) le type de résultat d'une expression d'argument 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 FLOAT64 et qu'une expression (dont le type de résultat est INT64) est utilisée en tant qu'argument, le résultat de l'expression sera "converti" dans le type FLOAT64 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	Remarques
Littéral de type STRING	DATE DATETIME TIME 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 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.

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	DATE DATETIME TIME TIMESTAMP

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

Supertypes

Un supertype est un type commun auquel deux ou plusieurs expressions peuvent être converties (coercition). Les supertypes sont utilisés avec des opérations d'ensemble telles que UNION ALL et des expressions telles que CASE attendent plusieurs arguments avec des types correspondants. Chaque type comporte un ou plusieurs supertypes, y compris lui-même, qui définit son ensemble de supertypes.

Type d'entrée	Supertypes
BOOL	BOOL
INT64	INT64 FLOAT64 NUMERIC BIGNUMERIC
FLOAT64	FLOAT64
NUMERIC	NUMERIC BIGNUMERIC FLOAT64
DÉCIMAL	DECIMAL BIGDECIMAL FLOAT64
BIGNUMERIC	BIGNUMERIC FLOAT64
BIGDECIMAL	BIGDECIMAL FLOAT64
CHAÎNE	CHAÎNE
DATE	DATE
TIME	TIME
DATETIME	DATETIME
TIMESTAMP	TIMESTAMP
BYTES	BYTES
STRUCT	STRUCT avec les mêmes types de position de champ.
ARRAY	ARRAY avec les mêmes types d'éléments.
GEOGRAPHY	GEOGRAPHY

Si vous souhaitez rechercher le supertype pour un ensemble de types d'entrée, commencez par déterminer l'intersection de l'ensemble de supertypes pour chaque type d'entrée. Si cet ensemble est vide, les types d'entrée n'ont pas de supertype commun. Si cet ensemble n'est pas vide, le supertype commun est généralement le type le plus spécifique dans cet ensemble. Généralement, le type le plus spécifique est le type dont le domaine est le plus restrictif.

Exemples

Types d'entrée	Supertype commun	Renvoie	Remarques
INT64 FLOAT64	FLOAT64	FLOAT64	Si vous appliquez le supertype à INT64 et à FLOAT64, celui-ci réussit, car ils partagent le supertype FLOAT64.
INT64 BOOL	Aucun	Erreur	Si vous appliquez le supertype à INT64 et BOOL, il échoue, car ils n'ont pas de supertype commun.

Types exacts et inexacts

Les types numériques peuvent être exacts ou inexacts. Pour le supertype, si tous les types d'entrée sont des types exacts, le supertype obtenu ne peut être qu'un type exact.

Le tableau suivant répertorie les types de données numériques exacts et inexacts.

Types exacts	Types inexacts
INT64 NUMERIC BIGNUMERIC	FLOAT64

Exemples

Types d'entrée	Supertype commun	Renvoie	Remarques
INT64 FLOAT64	FLOAT64	FLOAT64	Si le supertype est appliqué à INT64 et DOUBLE, il réussit, car il existe des types numériques exacts et inexacts qui font l'objet d'un supertype.

Spécificité des types

Chaque type est associé à un domaine de valeurs qu'il accepte. Un type avec un domaine restreint est plus spécifique qu'un type doté d'un domaine plus étendu. Les types exacts sont plus spécifiques que les types inexacts, car ceux-ci ont une plage de valeurs de domaine plus étendue que les types exacts. Par exemple, INT64 est plus spécifique que FLOAT64.

Supertypes et littéraux

Les règles de supertype pour les littéraux sont plus permissives que pour les expressions normales et sont cohérentes avec les règles de coercition implicites. L'algorithme suivant est utilisé lorsque l'ensemble d'entrée des types inclut des types liés aux littéraux :

S'il existe des types "non littéral" dans l'ensemble, recherchez l'ensemble de supertypes communs de ces types.
S'il existe au moins un supertype possible, recherchez le type le plus spécifique pour lequel les types littéraux restants peuvent être implicitement convertis et renvoient ce supertype. Sinon, il n'y a pas de supertype.
Si l'ensemble ne contient que des types liés aux littéraux, calculez le supertype des types littéraux.
Si tous les types d'entrée sont liés à des littéraux NULL, le supertype obtenu est INT64.
Si aucun supertype commun n'est trouvé, une erreur est générée.

Exemples

Types d'entrée	Supertype commun	Renvoie
Littéral INT64 Expression UINT64	UINT64	UINT64
Expression TIMESTAMP Littéral STRING	TIMESTAMP	TIMESTAMP
Littéral NULL Littéral NULL	INT64	INT64
Littéral BOOL Littéral TIMESTAMP	Aucun	Erreur

Fonctions d'agrégation

Une fonction d'agrégation est une fonction qui récapitule les lignes d'un groupe en une valeur unique. 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 (SELECT NULL as fruit UNION ALL
      SELECT "apple" as fruit UNION ALL
      SELECT "pear" as fruit UNION ALL
      SELECT "orange" as fruit)

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

Lorsqu'ils sont utilisés conjointement avec une clause GROUP BY, les groupes récapitulés disposent généralement d'au moins une ligne. Lorsque la clause SELECT associée n'a pas de clause GROUP BY ou que certains modificateurs de fonction d'agrégation filtrent les lignes du groupe à récapituler, il est possible que la fonction d'agrégation doive récapituler un groupe vide. Dans ce cas, les fonctions COUNT et COUNTIF renvoient 0, alors que toutes les autres fonctions d'agrégation renvoient NULL.

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

ANY_VALUE

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

Description

Renvoie expression pour une ligne sélectionnée dans le groupe. La ligne sélectionnée est non déterministe et non aléatoire. Renvoie NULL lorsque l'entrée ne produit aucune ligne. Renvoie NULL lorsque expression est NULL pour toutes les lignes du groupe.

ANY_VALUE se comporte comme si RESPECT NULLS était spécifié. Les lignes pour lesquelles la valeur de expression est définie sur NULL sont prises en compte et peuvent être sélectionnées.

Types d'arguments acceptés

Tous

Clause facultative

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

Types de données renvoyées

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 tableau (ARRAY) 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 :

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de ARRAY_AGG().
DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
IGNORE NULLS ou RESPECT NULLS : si IGNORE NULLS est spécifié, les valeurs NULL sont exclues du résultat. Si RESPECT NULLS est spécifié, les valeurs NULL sont incluses dans le résultat. Si aucune de ces clauses n'est spécifiée, les valeurs NULL sont incluses dans le résultat. Si un tableau du résultat final de la requête contient un élément NULL, une erreur est générée.
ORDER BY : spécifie l'ordre des valeurs.
- Pour chaque clé de tri, le sens de tri par défaut est ASC.
- NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire que les valeurs NULL 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 portant 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.
LIMIT : spécifie le nombre maximal d'entrées expression dans le résultat. La limite n doit être une constante de type INT64.

Type de données renvoyé

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 :

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.
- NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire que les valeurs NULL 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 portant 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.
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 entrée. Un tableau NULL n'est pas comptabilisé. La limite n doit être une constante de type INT64.

Type de données renvoyé

ARRAY

Renvoie NULL s'il n'y a aucune ligne d'entrée ou si l'évaluation de la valeur 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 [1, 2, 3, 4] AS x
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

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

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

+--------------------------+
| array_concat_agg         |
+--------------------------+
| [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 [1, 2, 3, 4] AS x
  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 :

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de AVG().
DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

Exemples

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

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

SELECT AVG(DISTINCT x) AS avg
FROM UNNEST([0, 2, 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

Type de données renvoyé

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

Type de données renvoyé

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ées

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

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

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

Description

Renvoie le nombre de lignes dans l'entrée.
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. Si DISTINCT est présent, expression ne peut être qu'un type de données groupable.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.
DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Types de données renvoyées

INT64

Exemples

Vous pouvez utiliser la fonction COUNT pour renvoyer le nombre de lignes d'une table ou le nombre de valeurs distinctes d'une expression. Exemple :

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

+------------+--------------+
| count_star | count_dist_x |
+------------+--------------+
| 4          | 3            |
+------------+--------------+

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

+------+------------+--------------+
| x    | count_star | count_dist_x |
+------+------------+--------------+
| 1    | 3          | 2            |
| 4    | 3          | 2            |
| 4    | 3          | 2            |
| 5    | 1          | 1            |
+------+------------+--------------+

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

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

Si vous souhaitez compter le nombre de valeurs distinctes d'une expression pour laquelle une certaine condition est remplie, vous pouvez utiliser cette recette :

COUNT(DISTINCT IF(condition, expression, NULL))

Ici, IF renvoie la valeur de expression si condition est TRUE, ou NULL dans le cas contraire. L'élément COUNT(DISTINCT ...) environnant ignore les valeurs NULL. Il ne comptabilise donc que les valeurs distinctes de expression pour lesquelles condition est TRUE.

Par exemple, pour compter le nombre de valeurs positives distinctes de x :

SELECT COUNT(DISTINCT IF(x > 0, x, NULL)) AS distinct_positive
FROM UNNEST([1, -2, 4, 1, -5, 4, 1, 3, -6, 1]) AS x;

+-------------------+
| distinct_positive |
+-------------------+
| 3                 |
+-------------------+

Ou pour compter le nombre de dates distinctes auxquelles un certain type d'événement s'est produit :

WITH Events AS (
  SELECT DATE '2021-01-01' AS event_date, 'SUCCESS' AS event_type
  UNION ALL
  SELECT DATE '2021-01-02' AS event_date, 'SUCCESS' AS event_type
  UNION ALL
  SELECT DATE '2021-01-02' AS event_date, 'FAILURE' AS event_type
  UNION ALL
  SELECT DATE '2021-01-03' AS event_date, 'SUCCESS' AS event_type
  UNION ALL
  SELECT DATE '2021-01-04' AS event_date, 'FAILURE' AS event_type
  UNION ALL
  SELECT DATE '2021-01-04' AS event_date, 'FAILURE' AS event_type
)
SELECT
  COUNT(DISTINCT IF(event_type = 'FAILURE', event_date, NULL))
    AS distinct_dates_with_failures
FROM Events;

+------------------------------+
| distinct_dates_with_failures |
+------------------------------+
| 2                            |
+------------------------------+

NB.SI

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 la valeur expression donne FALSE ou NULL pour toutes les lignes.

Étant donné que expression doit être un BOOL, le formulaire COUNTIF(DISTINCT ...) n'est pas accepté. Cela ne serait pas utile : il n'y a qu'une seule valeur distincte de TRUE. Généralement, lorsqu'une personne souhaite combiner COUNTIF et DISTINCT, elle souhaite compter le nombre de valeurs distinctes d'une expression pour laquelle une certaine condition est remplie. Pour ce faire, vous pouvez utiliser la recette suivante :

COUNT(DISTINCT IF(condition, expression, NULL))

Notez que cela utilise COUNT, et non COUNTIF. la partie IF a été déplacée à l'intérieur. Pour en savoir plus, consultez les exemples pour COUNT.

Types d'arguments acceptés

BOOL

Clause facultative

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

Types de données renvoyées

INT64

Exemples

SELECT COUNTIF(x<0) AS num_negative, COUNTIF(x>0) AS num_positive
FROM UNNEST([5, -2, 3, 6, -10, -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

Type de données renvoyées

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

Type de données renvoyées

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 pouvant être triées.

Clause facultative

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

Types de données renvoyées

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

Exemples

SELECT MAX(x) AS max
FROM UNNEST([8, 37, 4, 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 pouvant être triées.

Clause facultative

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

Types de données renvoyées

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

Exemples

SELECT MIN(x) AS min
FROM UNNEST([8, 37, 4, 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. 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.

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 :

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STRING_AGG().
DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
ORDER BY : spécifie l'ordre des valeurs.
- Pour chaque clé de tri, le sens de tri par défaut est ASC.
- NULL : dans le contexte de la clause ORDER BY, les valeurs NULL sont la plus petite valeur possible, c'est-à-dire que les valeurs NULL 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 portant 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.
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 entrée. Une chaîne NULL n'est pas comptabilisée. La limite n doit être une constante de type INT64.

Types de données renvoyées

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", "pear", "banana", "pear"]) AS fruit;

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

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

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

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

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

SELECT STRING_AGG(fruit, " & " LIMIT 2) AS string_agg
FROM UNNEST(["apple", "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", "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é et INTERVAL.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page Fonctions analytiques.
DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64	INTERVAL
RÉSULTAT	INT64	NUMERIC	BIGNUMERIC	FLOAT64	INTERVAL

Cas particuliers :

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

Renvoie NULL si l'entrée ne contient aucune ligne.

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

SELECT SUM(x) AS sum
FROM UNNEST([]) AS x;

+------+
| sum  |
+------+
| NULL |
+------+

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.

Tous les types numériques sont acceptés. Si l'entrée est NUMERIC ou BIGNUMERIC, l'agrégation interne est stable avec la sortie finale convertie en FLOAT64. Sinon, l'entrée est convertie en une valeur FLOAT64 avant l'agrégation, ce qui génère un résultat potentiellement instable.

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

Clause facultative

OVER : spécifie une fenêtre. Consultez la page sur les 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 est compris entre -Inf et +Inf.

Cette fonction ignore les paires d'entrées qui contiennent au moins une valeur NULL. En l'absence de paires d'entrées sans valeur NULL, cette fonction renvoie NULL. S'il y a une seule paire d'entrées sans valeur NULL, cette fonction renvoie 0.

Clause facultative

OVER : spécifie une fenêtre. Consultez la page sur les 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 est compris entre -Inf et +Inf.

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

Clause facultative

OVER : spécifie une fenêtre. Consultez la page sur les 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.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STDDEV_POP().
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.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de STDDEV_SAMP().
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

Un 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.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de VAR_POP().
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.

Clauses facultatives

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

OVER : spécifie une fenêtre. Consultez la page sur les fonctions analytiques. Cette clause est actuellement incompatible avec toutes les autres clauses de VAR_SAMP().
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

Un 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. Ces fonctions requièrent généralement moins de mémoire que les fonctions d'agrégation exacte telles que COUNT(DISTINCT ...), mais elles engendrent également une incertitude statistique. Cela rend l'agrégation approximative appropriée pour les flux de données volumineux pour lesquels l'utilisation linéaire de la mémoire est difficile, ainsi que pour les données qui sont déjà approximatives.

Les fonctions d'agrégation approximative de cette section fonctionnent directement sur les données d'entrée, plutôt que sur une estimation intermédiaire des données. Ces fonctions ne permettent pas aux utilisateurs de spécifier la précision de l'estimation avec des résumés. Si vous souhaitez spécifier la précision avec des résumés, consultez les sections suivantes :

Fonctions HyperLogLog++ pour estimer la cardinalité.

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ées

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 :

DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
IGNORE NULLS ou RESPECT NULLS : si IGNORE NULLS est spécifié, les valeurs NULL sont exclues du résultat. Si RESPECT NULLS est spécifié, les valeurs NULL sont incluses dans le résultat. Si aucune valeur n'est spécifiée, les valeurs NULL sont exclues du résultat. Si un tableau du résultat final de la requête contient un élément NULL, une erreur est générée.

Type de données renvoyé

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 de la valeur expression donne NULL pour toutes les lignes.

Exemples

SELECT APPROX_QUANTILES(x, 2) AS approx_quantiles
FROM UNNEST([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([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.

Type de données renvoyé

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 count contient une valeur 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 l'un des éléments suivants :

INT64
NUMERIC
BIGNUMERIC
FLOAT64

number doit être de type INT64.

Type de données renvoyé

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

L'algorithme HyperLogLog++ (HLL++) estime la cardinalité à partir des résumés. Si vous ne souhaitez pas utiliser les résumés et que vous n'avez pas besoin d'une précision personnalisée, envisagez d'utiliser des fonctions d'agrégation approximative avec une précision définie par le système.

Les fonctions HLL++ sont des fonctions d'agrégation approximative. Elles requièrent généralement moins de mémoire que les fonctions d'agrégation exacte, telles que COUNT(DISTINCT), mais elles engendrent également une incertitude statistique. Ainsi, les fonctions HLL++ sont adaptées aux flux de données volumineux pour lesquels l'utilisation linéaire de la mémoire est difficile, ainsi que pour les données qui sont déjà approximatives.

BigQuery accepte les fonctions HLL++ suivantes :

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é HLL++. 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.

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	±3,25 %	±6,50 %	±9,75 %
11	2	±2,30 %	±4,60 %	±6,89 %
12	4	±1,63 %	±3,25 %	±4,88 %
13	8	±1,15 %	±2,30 %	±3,45 %
14	16	±0,81 %	±1,63 %	±2,44 %
15 (par défaut)	32	±0,57 %	±1,15 %	±1,72 %
16	64	±0,41 %	±0,81 %	±1,22 %
17	128	±0,29 %	±0,57 %	±0,86 %
18	256	±0,20 %	±0,41 %	±0,61 %
19	512	±0,14 %	±0,29 %	±0,43 %
20	1 024	±0,10 %	±0,20 %	±0,30 %
21	2 048	±0,07 %	±0,14 %	±0,22 %
22	4 096	±0,05 %	±0,10 %	±0,15 %
23	8 192	±0,04 %	±0,07 %	±0,11 %
24	16 384	±0,03 %	±0,05 %	±0,08 %

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é.

Types d'entrée acceptés

INT64
NUMERIC
BIGNUMERIC
STRING
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 HLL++ en calculant leur union.

Chaque sketch doit être initialisé sur le même type. Les tentatives de fusion de résumés pour différents types génèrent 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.

Si les résumés fusionnés ont été initialisés avec des précisions différentes, la précision sera réduite à la précision la plus basse impliquée dans la fusion.

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 HLL++ et les fusionne dans un nouveau résumé.

Si les résumés fusionnés ont été initialisés avec des précisions différentes, la précision sera réduite à la précision la plus basse impliquée dans la fusion. Par exemple, si MERGE_PARTIAL rencontre des esquisses de précision 14 et 15, la nouvelle esquisse renvoyée aura la précision 14.

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é HLL++.

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

À propos de l'algorithme HLL++

L'algorithme HLL++ améliore l'algorithme HLL en évaluant plus précisément les cardinalités de toutes tailles. L'algorithme HLL++ inclut une fonction de hachage 64 bits, une représentation creuse pour réduire les besoins en mémoire, ainsi que la correction de biais empirique pour les faibles estimations de cardinalité.

À propos des résumés

Un résumé est une synthèse d'un flux de données volumineux. Vous pouvez extraire des statistiques d'un résumé pour estimer des statistiques particulières des données d'origine ou fusionner des résumés pour synthétiser plusieurs flux de données. Un résumé présente les caractéristiques suivantes :

Il compresse les données brutes en une représentation en mémoire fixe.
Il est asymptotiquement plus petit que l'entrée.
Il s'agit de la forme sérialisée d'une structure de données sous-linéaire en mémoire.
Il nécessite généralement moins de mémoire que l'entrée utilisée pour la création.

Les résumés permettent l'intégration à d'autres systèmes. Par exemple, il est possible de créer des résumés dans des applications externes, telles que Cloud Dataflow, ou Apache Spark, et de les utiliser dans BigQuery et inversement. Les résumés permettent également de créer des agrégations intermédiaires pour les fonctions non additives telles que COUNT(DISTINCT).

Fonctions de numérotation

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 l'utilisation des fonctions de numérotation, consultez la page Concepts des fonctions de numérotation.

Exigences de la clause OVER :

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

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 ensembles constant_integer_expression en fonction de l'ordre des lignes et renvoie le numéro d'ensemble en base 1 attribué à chaque ligne. Le nombre de lignes dans les ensembles peut différer d'une unité au maximum. Les valeurs restantes (le nombre de lignes restantes divisé par le nombre d'ensembles) sont distribuées de sorte qu'il y en ait une par ensemble, en commençant par l'ensemble 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

Ne nécessite pas la clause ORDER BY. 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'entrée expression. 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 de conversion

BigQuery accepte les fonctions de conversion suivantes. Ces conversions de type de données sont explicites, mais certaines conversions peuvent se produire de manière implicite. Vous pouvez en savoir plus sur la conversion implicite et explicite avec ce lien.

Présentation de CAST

CAST(expression AS typename [format_clause])

Description

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.

En cas d'utilisation de CAST, une requête peut échouer si BigQuery est incapable d'effectuer le casting. Si vous souhaitez protéger vos requêtes contre ce type d'erreur, vous pouvez utiliser SAFE_CAST.

Lors des 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 caster 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.

Certains castings peuvent inclure une clause de format, qui fournit des instructions sur la façon de procéder au casting. Par exemple, vous pouvez demander à un casting de convertir une séquence d'octets en chaîne encodée en BASE64 au lieu d'une chaîne encodée en UTF-8.

La structure de la clause de format est unique à chaque type de casting et des informations supplémentaires sont disponibles dans la section correspondant à ce casting.

Exemples

La requête suivante renvoie "true" si la valeur de x est 1, "false" pour toutes les autres valeurs qui ne sont pas NULL et NULL si x a la valeur NULL.

CAST(x=1 AS STRING)

CAST AS ARRAY

CAST(expression AS ARRAY<element_type>)

Description

BigQuery accepte le casting vers le type ARRAY. Le paramètre expression peut représenter une expression pour les types de données suivants :

ARRAY

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
ARRAY	ARRAY	Le type ARRAY doit être exactement le même.

CAST AS BIGNUMERIC

CAST(expression AS BIGNUMERIC)

Description

BigQuery accepte le casting vers le type BIGNUMERIC. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
FLOAT64	BIGNUMERIC	Le nombre à virgule flottante 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 `BIGNUMERIC` renvoie une erreur de dépassement de capacité.
CHAÎNE	BIGNUMERIC	Le littéral numérique contenu dans la valeur `STRING` ne doit pas dépasser la plage ou la précision maximale du type `BIGNUMERIC` sous peine de produire une erreur. Si le nombre de chiffres après la virgule est supérieur à 38, la valeur `BIGNUMERIC` résultante sera arrondie à la valeur la plus éloignée à mi-chemin du zéro de sorte qu'elle comporte 38 chiffres après la virgule.

CAST AS BOOL

CAST(expression AS BOOL)

Description

BigQuery accepte le casting vers le type BOOL. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
BOOL
STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
INT64	BOOL	Renvoie `FALSE` si la valeur de `x` est `0`, ou `TRUE` si ce n'est pas le cas.
CHAÎNE	BOOL	Renvoie `TRUE` si la valeur de `x` est `"true"` et `FALSE` si la valeur de `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 castées en BOOL. Les valeurs STRING ne sont pas sensibles à la casse lorsqu'elles sont converties en BOOL.

CAST AS BYTES

CAST(expression AS BYTES [format_clause])

Description

BigQuery accepte le casting vers le type BYTES. Le paramètre expression peut représenter une expression pour les types de données suivants :

BYTES
STRING

Clause de format

Lorsqu'une expression d'un type est castée dans un autre type, vous pouvez utiliser la clause de format pour fournir des instructions sur le casting de ce type. Vous pouvez utiliser la clause de format de cette section si expression est de type STRING.

Formater la chaîne en octets

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	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.

CAST AS DATE

CAST(expression AS DATE [format_clause])

Description

BigQuery accepte le casting vers le type DATE. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRING
TIME
DATETIME
TIMESTAMP

Clause de format

Formater la chaîne comme date et heure

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	DATE	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.
TIMESTAMP	DATE	Le casting d'un horodatage en date tronque effectivement l'horodatage du fuseau horaire par défaut.

CAST AS DATETIME

CAST(expression AS DATETIME [format_clause])

Description

BigQuery accepte le casting vers le type DATETIME. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRING
TIME
DATETIME
TIMESTAMP

Clause de format

Formater la chaîne comme date et heure

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	DATETIME	Le casting d'une chaîne en date/heure ne dépend pas du fuseau horaire et la chaîne doit être conforme au format de la valeur littérale de date/heure acceptée. Si l'expression de chaîne n'est pas valide ou représente une date/heure en dehors de la plage de valeurs minimale-maximale acceptée, une erreur est générée.
TIMESTAMP	DATETIME	Le casting d'un horodatage en date/heure tronque effectivement l'horodatage du fuseau horaire par défaut.

CAST AS FLOAT64

CAST(expression AS FLOAT64)

Description

BigQuery accepte le casting vers les types à virgule flottante. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
INT64	FLOAT64	Renvoie une valeur à virgule flottante proche, mais potentiellement non exacte.
NUMERIC	FLOAT64	NUMERIC convertira l'expression en nombre à virgule flottante le plus proche avec une possible perte de précision.
BIGNUMERIC	FLOAT64	BIGNUMERIC convertira l'expression en nombre à virgule flottante le plus proche avec une possible perte de précision.
CHAÎNE	FLOAT64	Renvoie `x` sous la forme d'une valeur à virgule flottante, en l'interprétant comme ayant le même format qu'une valeur littérale à virgule flottante valide. Accepte également le casting de `"[+,-]inf"` à `[,-]Infinity`, `"[+,-]infinity"` à `[,-]Infinity` et `"[+,-]nan"` à `NaN`. Les conversions ne sont pas sensibles à la casse.

CAST AS INT64

CAST(expression AS INT64)

Description

BigQuery accepte le casting vers les types entiers. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
BOOL
STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
FLOAT64	INT64	Renvoie la valeur entière 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.
BOOL	INT64	Renvoie `1` si la valeur de `x` est `TRUE`, ou `0` si ce n'est pas le cas.
CHAÎNE	INT64	Une chaîne hexadécimale peut être castée en nombre entier. Par exemple, la valeur `0x123` en `291` ou la valeur `-0x123` en `-291`.

Exemples

Si vous utilisez 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       |
+-----------+------------+

CAST AS INTERVAL

CAST(expression AS INTERVAL)

Description

BigQuery est compatible avec la diffusion vers la valeur INTERVAL. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	INTERVAL	Lors du casting d'une chaîne en intervalle, la chaîne doit être conforme à la durée ISO 8601 ou au format littéral d'intervalle "YM DH:M:SF". Les formats de littéral d'intervalle partiel sont également acceptés s'ils ne sont pas ambigus, par exemple "H:M:S". Si l'expression de chaîne n'est pas valide ou représente un intervalle en dehors de la plage de valeurs minimale-maximale acceptée, une erreur est générée.

Exemples

SELECT input, CAST(input AS INTERVAL) AS output
FROM UNNEST([
  '1-2 3 10:20:30.456',
  '1-2',
  '10:20:30',
  'P1Y2M3D',
  'PT10H20M30,456S'
]) input

+--------------------+--------------------+
| input              | output             |
+--------------------+--------------------+
| 1-2 3 10:20:30.456 | 1-2 3 10:20:30.456 |
| 1-2                | 1-2 0 0:0:0        |
| 10:20:30           | 0-0 0 10:20:30     |
| P1Y2M3D            | 1-2 3 0:0:0        |
| PT10H20M30,456S    | 0-0 0 10:20:30.456 |
+--------------------+--------------------+

CAST AS NUMERIC

CAST(expression AS NUMERIC)

Description

BigQuery accepte le casting vers le type NUMERIC. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
STRING

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
FLOAT64	NUMERIC	Le nombre à virgule flottante 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é.
CHAÎNE	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.

CAST AS STRING

CAST(expression AS STRING [format_clause [AT TIME ZONE timezone_expr]])

Description

BigQuery accepte le casting vers le type STRING. Le paramètre expression peut représenter une expression pour les types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
BOOL
BYTES
TIME
DATE
DATETIME
TIMESTAMP
STRING

Clause de format

Lorsqu'une expression d'un type est castée vers un autre type, vous pouvez utiliser la clause de format pour fournir des instructions sur la façon de procéder au casting. Vous pouvez utiliser la clause de format de cette section si expression correspond à l'un des types de données suivants :

INT64
FLOAT64
NUMERIC
BIGNUMERIC
BYTES
TIME
DATE
DATETIME
TIMESTAMP

La clause de format pour STRING comporte une clause supplémentaire facultative appelée AT TIME ZONE timezone_expr, que vous pouvez utiliser pour spécifier un fuseau horaire spécifique à utiliser lors du formatage d'un TIMESTAMP. Si cette clause facultative n'est pas incluse lors de la mise en forme d'un TIMESTAMP, votre fuseau horaire actuel est utilisé.

Pour plus d'informations, consultez les articles suivants :

Formater des octets en tant que chaîne
Formater date et heure en tant que chaîne
Formater le type numérique en tant que chaîne

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
FLOAT64	STRING	Renvoie une représentation de chaîne approximative.
BOOL	CHAÎNE	Renvoie `"true"` si la valeur de `x` est `TRUE`, ou `"false"` si ce n'est pas le cas.
BYTES	STRING	Renvoie `x` interprété en tant que STRING UTF-8. Par exemple, en cas de casting du littéral BYTES `b'\xc2\xa9'` en STRING, ce littéral est interprété en tant que valeur 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.
TIME	CHAÎNE	Le casting d'un type d'heure en chaîne ne dépend pas du fuseau horaire et son résultat se présente au format `HH:MM:SS`.
DATE	CHAÎNE	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`.
DATETIME	CHAÎNE	Le casting d'un type de date/heure en chaîne ne dépend pas du fuseau horaire et son résultat se présente au format `YYYY-MM-DD HH:MM:SS`.
TIMESTAMP	CHAÎNE	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.
INTERVAL	CHAÎNE	Le casting d'un intervalle en chaîne se présente sous la forme `Y-M D H:M:S`.

Exemples

SELECT CAST(CURRENT_DATE() AS STRING) AS current_date

+---------------+
| current_date  |
+---------------+
| 2021-03-09    |
+---------------+

SELECT CAST(CURRENT_DATE() AS STRING FORMAT 'DAY') AS current_day

+-------------+
| current_day |
+-------------+
| MONDAY      |
+-------------+

SELECT CAST(
  TIMESTAMP '2008-12-25 00:00:00+00:00'
  AS STRING FORMAT 'YYYY-MM-DD HH24:MI:SS TZH:TZM') AS date_time_to_string

-- Results depend upon where this query was executed.
+------------------------------+
| date_time_to_string          |
+------------------------------+
| 2008-12-24 16:00:00 -08:00   |
+------------------------------+

SELECT CAST(
  TIMESTAMP '2008-12-25 00:00:00+00:00'
  AS STRING FORMAT 'YYYY-MM-DD HH24:MI:SS TZH:TZM'
  AT TIME ZONE 'Asia/Kolkata') AS date_time_to_string

-- Because the time zone is specified, the result is always the same.
+------------------------------+
| date_time_to_string          |
+------------------------------+
| 2008-12-25 05:30:00 +05:30   |
+------------------------------+

CAST AS STRUCT

CAST(expression AS STRUCT)

Description

BigQuery accepte le casting vers le type STRUCT. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRUCT

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
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).

CAST AS TIME

CAST(expression AS TIME [format_clause])

Description

BigQuery accepte le casting vers le type TIME. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRING
TIME
DATETIME
TIMESTAMP

Clause de format

Formater la chaîne comme date et heure

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	TIME	Le casting d'une chaîne en heure ne dépend pas du fuseau horaire et la chaîne doit être conforme au format de la valeur littérale d'heure acceptée. Si l'expression de chaîne n'est pas valide ou représente une heure en dehors de la plage de valeurs minimale-maximale acceptée, une erreur est générée.

CAST AS TIMESTAMP

CAST(expression AS TIMESTAMP [format_clause [AT TIME ZONE timezone_expr]])

Description

BigQuery accepte le casting vers le type TIMESTAMP. Le paramètre expression peut représenter une expression pour les types de données suivants :

STRING
TIME
DATETIME
TIMESTAMP

Clause de format

Formater la chaîne comme date et heure

La clause de format pour TIMESTAMP comporte une clause facultative supplémentaire appelée AT TIME ZONE timezone_expr, que vous pouvez utiliser pour spécifier un fuseau horaire spécifique à utiliser lors de la mise en forme. Si cette clause facultative n'est pas incluse, votre fuseau horaire actuel est utilisé.

Règles de conversion

De	Jusqu'au	Règle(s) appliquée(s) lors du casting de `x`
CHAÎNE	TIMESTAMP	Lors du casting d'une chaîne en horodatage, `string_expression` doit être conforme aux formats de littéral d'horodatage acceptés. Dans le cas contraire, une erreur d'exécution se produit. L'expression `string_expression` peut contenir un fuseau horaire. 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.
DATE	TIMESTAMP	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).
DATETIME	TIMESTAMP	Le casting d'une date/heure en horodatage interprète `datetime_expression` comme heure de début de la journée (minuit) dans le fuseau horaire par défaut (UTC).

Exemples

L'exemple suivant convertit un horodatage au format de chaîne sous forme d'horodatage :

SELECT CAST("2020-06-02 17:00:53.110+00:00" AS TIMESTAMP) AS as_timestamp

-- Results depend upon where this query was executed.
+-----------------------------+
| as_timestamp                |
+-----------------------------+
| 2020-06-03 00:00:53.110 UTC |
+-----------------------------+

Les exemples suivants castent une date et une heure au format chaîne en tant qu'horodatage. Ces exemples renvoient le même résultat que l'exemple précédent.

SELECT CAST("06/02/2020 17:00:53.110" AS TIMESTAMP FORMAT 'MM/DD/YYYY HH:MI:SS' AT TIME ZONE 'America/Los_Angeles') AS as_timestamp

SELECT CAST("06/02/2020 17:00:53.110" AS TIMESTAMP FORMAT 'MM/DD/YYYY HH:MI:SS' AT TIME ZONE '00') AS as_timestamp

SELECT CAST('06/02/2020 17:00:53.110 +00' AS TIMESTAMP FORMAT 'YYYY-MM-DD HH:MI:SS TZH') AS as_timestamp

PARSE_BIGNUMERIC

PARSE_BIGNUMERIC(string_expression)

Description

Convertit une chaîne en une valeur BIGNUMERIC.

La valeur littérale numérique contenue dans la chaîne ne doit pas dépasser la plage ou la précision maximale du type BIGNUMERIC, sinon une erreur se produit. Si le nombre de chiffres après le séparateur décimal est supérieur à 38, la valeur BIGNUMERIC résultante sera arrondie à la valeur la plus éloignée à mi-chemin du zéro de sorte qu'elle comporte 38 chiffres après le séparateur décimal.


-- This example shows how a string with a decimal point is parsed.
SELECT PARSE_BIGNUMERIC("123.45") AS parsed

+--------+
| parsed |
+--------+
| 123.45 |
+--------+

-- This example shows how a string with an exponent is parsed.
SELECT PARSE_BIGNUMERIC("123.456E37") AS parsed

+-----------------------------------------+
| parsed                                  |
+-----------------------------------------+
| 123400000000000000000000000000000000000 |
+-----------------------------------------+

-- This example shows the rounding when digits after the decimal point exceeds 38.
SELECT PARSE_BIGNUMERIC("1.123456789012345678901234567890123456789") as parsed

+------------------------------------------+
| parsed                                   |
+------------------------------------------+
| 1.12345678901234567890123456789012345679 |
+------------------------------------------+

Cette fonction est semblable à l'utilisation de la fonction CAST AS BIGNUMERIC, à la différence que la fonction PARSE_BIGNUMERIC n'accepte que les entrées de chaîne et autorise les éléments suivants dans la chaîne :

Espaces entre le signe (+/-) et le nombre
Signes (+/-) après le nombre

Règles pour les chaînes d'entrée valides :

Règle	Exemple d'entrée	Résultat
La chaîne ne peut contenir que des chiffres, des virgules, des séparateurs décimaux et des signes.	"- 12,34567,89.0"	-123456789
Les espaces blancs sont autorisés n'importe où, sauf entre les chiffres.	" - 12.345 "	-12.345
Seuls les chiffres et les virgules sont autorisés avant le séparateur décimal.	" 12,345,678"	12345678
Seuls les chiffres sont autorisés après le séparateur décimal.	"1.234 "	1.234
Utilisez `E` ou `e` pour les exposants. Après la valeur `e`, les chiffres et un indicateur de signe initial sont autorisés.	" 123.45e-1"	12.345
Si la partie entière n'est pas vide, elle doit contenir au moins un chiffre.	" 0,.12 -"	-0.12
Si la chaîne contient un séparateur décimal, elle doit contenir au moins un chiffre.	" .1"	0,1
La chaîne ne peut pas contenir plus d'un signe.	" 0.5 +"	0,5

Type de données renvoyé

BIGNUMERIC

Exemples

Cet exemple montre une entrée avec des espaces avant, après et entre le signe et le nombre :

SELECT PARSE_BIGNUMERIC("  -  12.34 ") as parsed;

+--------+
| parsed |
+--------+
| -12.34 |
+--------+

Cet exemple montre une entrée avec un exposant ainsi que le signe après le nombre :

SELECT PARSE_BIGNUMERIC("12.34e-1-") as parsed;

+--------+
| parsed |
+--------+
| -1.234 |
+--------+

Cet exemple présente une entrée avec plusieurs virgules dans la partie entière du nombre :

SELECT PARSE_BIGNUMERIC("  1,2,,3,.45 + ") as parsed;

+--------+
| parsed |
+--------+
| 123.45 |
+--------+

Cet exemple montre une entrée avec un séparateur décimal et aucun chiffre dans la partie entière du nombre :

SELECT PARSE_BIGNUMERIC(".1234  ") as parsed;

+--------+
| parsed |
+--------+
| 0.1234 |
+--------+

Exemples d'entrées non valides

Cet exemple n'est pas valide, car la partie entière du nombre ne contient pas de chiffres :

SELECT PARSE_BIGNUMERIC(",,,.1234  ") as parsed;

Cet exemple n'est pas valide, car il y a des espaces entre les chiffres :

SELECT PARSE_BIGNUMERIC("1  23.4 5  ") as parsed;

Cet exemple n'est pas valide, car le nombre est vide, à l'exception d'un exposant :

SELECT PARSE_BIGNUMERIC("  e1 ") as parsed;

Cet exemple n'est pas valide, car la chaîne contient plusieurs signes :

SELECT PARSE_BIGNUMERIC("  - 12.3 - ") as parsed;

Cet exemple n'est pas valide, car la valeur du nombre se situe en dehors de la plage de BIGNUMERIC :

SELECT PARSE_BIGNUMERIC("12.34E100 ") as parsed;

Cet exemple n'est pas valide, car la chaîne contient des caractères non valides :

SELECT PARSE_BIGNUMERIC("$12.34") as parsed;

PARSE_NUMERIC

PARSE_NUMERIC(string_expression)

Description

Convertit une chaîne en une valeur NUMERIC.

La valeur littérale numérique contenue dans la chaîne ne doit pas dépasser la plage ou la précision maximale du type NUMERIC, sinon une erreur se produit. Si le nombre de chiffres après la virgule est supérieur à neuf, la valeur NUMERIC résultante est arrondie à la valeur la plus éloignée à mi-chemin du zéro de sorte qu'elle comporte neuf chiffres après la virgule.


-- This example shows how a string with a decimal point is parsed.
SELECT PARSE_NUMERIC("123.45") AS parsed

+--------+
| parsed |
+--------+
| 123.45 |
+--------+

-- This example shows how a string with an exponent is parsed.
SELECT PARSE_NUMERIC("12.34E27") as parsed

+-------------------------------+
| parsed                        |
+-------------------------------+
| 12340000000000000000000000000 |
+-------------------------------+

-- This example shows the rounding when digits after the decimal point exceeds 9.
SELECT PARSE_NUMERIC("1.0123456789") as parsed

+-------------+
| parsed      |
+-------------+
| 1.012345679 |
+-------------+

Cette fonction est semblable à l'utilisation de la fonction CAST AS NUMERIC, à la différence que la fonction PARSE_NUMERIC n'accepte que les entrées de chaîne et autorise ce qui suit :

Espaces entre le signe (+/-) et le nombre
Signes (+/-) après le nombre

Règles pour les chaînes d'entrée valides :

Règle	Exemple d'entrée	Résultat
La chaîne ne peut contenir que des chiffres, des virgules, des séparateurs décimaux et des signes.	"- 12,34567,89.0"	-123456789
Les espaces blancs sont autorisés n'importe où, sauf entre les chiffres.	" - 12.345 "	-12.345
Seuls les chiffres et les virgules sont autorisés avant le séparateur décimal.	" 12,345,678"	12345678
Seuls les chiffres sont autorisés après le séparateur décimal.	"1.234 "	1.234
Utilisez `E` ou `e` pour les exposants. Après la valeur `e`, les chiffres et un indicateur de signe initial sont autorisés.	" 123.45e-1"	12.345
Si la partie entière n'est pas vide, elle doit contenir au moins un chiffre.	" 0,.12 -"	-0.12
Si la chaîne contient un séparateur décimal, elle doit contenir au moins un chiffre.	" .1"	0,1
La chaîne ne peut pas contenir plus d'un signe.	" 0.5 +"	0,5

Type de données renvoyé

NUMERIC

Exemples

Cet exemple montre une entrée avec des espaces avant, après et entre le signe et le nombre :

SELECT PARSE_NUMERIC("  -  12.34 ") as parsed;

+--------+
| parsed |
+--------+
| -12.34 |
+--------+

Cet exemple montre une entrée avec un exposant ainsi que le signe après le nombre :

SELECT PARSE_NUMERIC("12.34e-1-") as parsed;

+--------+
| parsed |
+--------+
| -1.234 |
+--------+

Cet exemple présente une entrée avec plusieurs virgules dans la partie entière du nombre :

SELECT PARSE_NUMERIC("  1,2,,3,.45 + ") as parsed;

+--------+
| parsed |
+--------+
| 123.45 |
+--------+

Cet exemple montre une entrée avec un séparateur décimal et aucun chiffre dans la partie entière du nombre :

SELECT PARSE_NUMERIC(".1234  ") as parsed;

+--------+
| parsed |
+--------+
| 0.1234 |
+--------+

Exemples d'entrées non valides

Cet exemple n'est pas valide, car la partie entière du nombre ne contient pas de chiffres :

SELECT PARSE_NUMERIC(",,,.1234  ") as parsed;

Cet exemple n'est pas valide, car il y a des espaces entre les chiffres :

SELECT PARSE_NUMERIC("1  23.4 5  ") as parsed;

Cet exemple n'est pas valide, car le nombre est vide, à l'exception d'un exposant :

SELECT PARSE_NUMERIC("  e1 ") as parsed;

Cet exemple n'est pas valide, car la chaîne contient plusieurs signes :

SELECT PARSE_NUMERIC("  - 12.3 - ") as parsed;

Cet exemple n'est pas valide, car la valeur du nombre se situe en dehors de la plage de BIGNUMERIC :

SELECT PARSE_NUMERIC("12.34E100 ") as parsed;

Cet exemple n'est pas valide, car la chaîne contient des caractères non valides :

SELECT PARSE_NUMERIC("$12.34") as parsed;

SAFE_CAST

SAFE_CAST(expression AS typename [format_clause])

Description

En cas d'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 sur la fonction SAFE_CONVERT_BYTES_TO_STRING.

Autres fonctions de conversion

Pour en savoir plus sur ces fonctions de conversion, consultez les autres pages de documentation suivantes :

Fonction de conversion	De	To
ARRAY_TO_STRING	ARRAY	CHAÎNE
DATE	Différents types de données	DATE
DATETIME	Différents types de données	DATETIME
FROM_BASE32	CHAÎNE	BYTES
FROM_BASE64	CHAÎNE	BYTES
FROM_HEX	CHAÎNE	BYTES
PARSE_DATE	CHAÎNE	DATE
PARSE_DATETIME	CHAÎNE	DATETIME
PARSE_TIME	CHAÎNE	TIME
PARSE_TIMESTAMP	CHAÎNE	TIMESTAMP
SAFE_CONVERT_BYTES_TO_STRING	BYTES	CHAÎNE
STRING	TIMESTAMP	CHAÎNE
TIME	Différents types de données	TIME
TIMESTAMP	Différents types de données	TIMESTAMP
TO_BASE32	BYTES	CHAÎNE
TO_BASE64	BYTES	CHAÎNE
TO_HEX	BYTES	CHAÎNE
TO_JSON_STRING	Tous les types de données	CHAÎNE

Clause de format pour CAST

format_clause:
  FORMAT format_model

format_model:
  format_string_expression

La clause de format peut être utilisée dans certaines fonctions CAST. Vous utilisez une clause de format pour fournir des instructions sur la façon de procéder à un casting. Par exemple, vous pouvez demander à un casting de convertir une séquence d'octets en chaîne encodée en BASE64 au lieu d'une chaîne encodée en UTF-8.

La clause de format inclut un modèle de format. Le modèle de format peut contenir des éléments de format combinés en tant que chaîne de format.

Formater des octets sous forme de chaîne

CAST(bytes_expression AS STRING FORMAT format_string_expression)

Vous pouvez caster une séquence d'octets vers une chaîne en ajoutant un élément de format à la chaîne. Si les octets ne peuvent pas être mis en forme avec un élément de format, une erreur est renvoyée. Si la séquence d'octets est NULL, le résultat est NULL. Les éléments de format ne sont pas sensibles à la casse.

Élément de format	Renvoie	Exemple
HEX	Convertit une séquence de valeurs de type BYTES en une valeur de type STRING hexadécimale.	Entrée : b'\x00\x01\xEF\xFF' Sortie : 0001efff
BASEX	Convertit une séquence de valeurs de type BYTES en une chaîne encodée BASEX. X représente l'un des nombres suivants : 2, 8, 16, 32, 64.	Entrée en tant que BASE8 : b'\x02\x11\x3B' Sortie : 00410473
BASE64M	Convertit une séquence d'octets en une chaîne encodée en BASE64 basée sur la norme rfc 2045 pour MIME. Génère un caractère de nouvelle ligne ("\n") tous les 76 caractères.	Entrée : b'\xde\xad\xbe\xef' Résultat : 3q2+7w==
ASCII	Convertit une séquence d'octets de valeur ASCII en chaîne. Si l'entrée contient des octets qui ne sont pas un encodage ASCII valide, une erreur est renvoyée.	Entrée : b'\x48\x65\x6c\x6c\x6f' Résultat : Hello
UTF-8	Convertit une séquence d'octets qui sont des valeurs UTF-8 en une chaîne. Si l'entrée contient des octets qui ne sont pas un encodage UTF-8 valide, une erreur est renvoyée.	Entrée : b'\x24' Résultat : $
UTF8	Comportement identique à la norme UTF-8.

Type renvoyé

STRING

Exemple

SELECT CAST(b'\x48\x65\x6c\x6c\x6f' AS STRING FORMAT 'ASCII') AS bytes_to_string;

+-----------------+
| bytes_to_string |
+-----------------+
| Hello           |
+-----------------+

Mettre en forme la chaîne en octets

CAST(string_expression AS BYTES FORMAT format_string_expression)

Vous pouvez convertir une chaîne en octets à l'aide d'un élément de format dans la chaîne de format. Si la chaîne ne peut pas être mise en forme avec l'élément de format, une erreur est renvoyée. Les éléments de format ne sont pas sensibles à la casse.

Dans l'expression de chaîne, les caractères d'espacement, tels que \n, sont ignorés si l'élément de format BASE64 ou BASE64M est utilisé.

Élément de format	Renvoie	Exemple
HEX	Convertit une chaîne encodée en hexadécimal en octets. Si l'entrée contient des caractères qui ne font pas partie de l'alphabet d'encodage HEX (0~9, non sensible à la casse a~f), une erreur est renvoyée.	Entrée : "0001efff" Résultat : b'\x00\x01\xEF\xFF'
BASEX	Convertit une chaîne encodée en BASEX en octets. X représente l'un des nombres suivants : 2, 8, 16, 32, 64. Une erreur est renvoyée si l'entrée contient des caractères qui ne font pas partie de l'alphabet d'encodage BASEX, à l'exception des caractères d'espacement si l'élément de format est BASE64.	Entrée en BASE8 : '00410473' Sortie : b'\x02\x11\x3B'
BASE64M	Convertit une chaîne encodée en BASE64 en octets. Si l'entrée contient des caractères qui ne sont pas des espaces blancs et qui ne font pas partie de l'alphabet d'encodage BASE64 défini dans la RFC 2045, une erreur est renvoyée. Le décodage BASE64M et BASE64 ont le même comportement.	Entrée : '3q2+7w==' Sortie : b'\xde\xad\xbe\xef'
ASCII	Convertit une chaîne ne contenant que des caractères ASCII en octets. Si l'entrée contient des caractères autres que des caractères ASCII, une erreur est renvoyée.	Entrée : 'Hello' Sortie : b'\x48\x65\x6c\x6c\x6f'
UTF-8	Convertit une chaîne en une séquence d'octets UTF-8.	Entrée : '$' Résultat : b'\x24'
UTF8	Comportement identique à la norme UTF-8.

Type renvoyé

BYTES

Exemple

SELECT CAST('Hello' AS BYTES FORMAT 'ASCII') AS string_to_bytes

+-------------------------+
| string_to_bytes         |
+-------------------------+
| b'\x48\x65\x6c\x6c\x6f' |
+-------------------------+

Mettre en forme la date et l'heure sous forme de chaîne

Vous pouvez mettre en forme ces parties de date et heure sous forme de chaîne :

Formater la partie de l'année sous forme de chaîne
Formater la partie du mois en tant que chaîne
Mettre en forme la partie jour sous forme de chaîne
Formater la partie "heure" sous forme de chaîne
Formater la partie minute en chaîne
Formater la partie seconde en tant que chaîne
Formater l'indicateur méridien sous forme de chaîne
Formater le fuseau horaire en tant que chaîne
Formater le littéral en tant que chaîne

La correspondance de casse est prise en charge lorsque vous formatez des parties de date ou d'heure sous forme de chaîne et que la sortie contient des lettres. Pour en savoir plus, consultez la section Correspondance de casse.

Correspondance des casses

Lorsque la sortie d'un élément de format contient des lettres, la casse des lettres de la sortie sont mises en correspondance avec celles de l'élément de format, ce qui signifie que les mots du résultat comportent des majuscules en fonction des majuscules comprises dans l'élément de format. C'est ce qu'on appelle la correspondance de casse. Les règles sont les suivantes :

Si les deux premières lettres de l'élément sont en majuscules, les mots du résultat sont en majuscules. Exemple : DAY = THURSDAY.
Si la première lettre de l'élément est en majuscules et la deuxième en minuscules, la première lettre de chaque mot du résultat est en majuscule et les autres lettres sont en minuscules. Exemple : Day = Thursday.
Si la première lettre de l'élément est en minuscule, toutes les lettres de la sortie sont en minuscules. Exemple : day = thursday.

Mettre en forme la partie de l'année sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caste un type de données contenant la partie année en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec l'année que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format d'année.

Ces types de données incluent une partie année :

DATE
DATETIME
TIMESTAMP

Si expression ou format_string_expression est NULL, la valeur renvoyée est NULL. Si format_string_expression est une chaîne vide, le résultat est une chaîne vide. Une erreur est générée si une valeur qui n'est pas un élément de format compatible apparaît dans format_string_expression ou expression ne contient pas une valeur spécifiée par un élément de format.

Élément de format	Renvoie	Exemple
AAAA	Année, quatre chiffres ou plus.	Entrée : DATE '2018-01-30' Sortie : 2018 Entrée : DATE '76-01-30' Sortie : 0076 Entrée : DATE '10000-01-30' Sortie : 10000
YYY	Année, trois derniers chiffres uniquement.	Entrée : DATE '2018-01-30' Sortie : 018 Entrée : DATE '98-01-30' Sortie : 098
YY	Année, les deux derniers chiffres uniquement.	Entrée : DATE '2018-01-30' Sortie : 18 Entrée : DATE '8-01-30' Sortie : 08
O	Année, dernier chiffre uniquement.	Entrée : DATE '2018-01-30' Sortie : 8
RRRR	Comportement identique à AAAA.
RR	Même comportement que AA.

Type renvoyé

STRING

Exemple

SELECT CAST(DATE '2018-01-30' AS STRING FORMAT 'YYYY') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 2018                |
+---------------------+

Formater la partie du mois en tant que chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caste un type de données contenant la partie mois en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec le mois que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de mois.

Les types de données suivants incluent une partie mois :

DATE
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
MM	mois/2 chiffres	Entrée : DATE '2018-01-30' Résultat : 01
LUN	Nom abrégé du mois, composé de trois caractères. Les noms de mois abrégés pour les paramètres régionaux en-US sont les suivants : JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC. La correspondance de casse est compatible.	Entrée : DATE '2018-01-30' Sortie : JAN
MOIS	Nom du mois. La mise en correspondance de la casse est compatible.	Entrée : DATE '2018-01-30' Résultat : JANUARY

Type renvoyé

STRING

Exemple

SELECT CAST(DATE '2018-01-30' AS STRING FORMAT 'MONTH') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| JANUARY             |
+---------------------+

Mettre en forme la partie jour sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caste un type de données contenant la partie journée en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec le jour que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format de jour.

Ces types de données incluent une partie jour :

DATE
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
JOUR	Nom du jour de la semaine, localisé. Les espaces sont complétés du côté droit pour que la taille de sortie soit exactement 9. La mise en correspondance de la casse est compatible.	Entrée : DATE '2020-12-31' Sortie : THURSDAY
DY	Nom abrégé, composé de trois caractères du jour de la semaine, localisé. Les noms abrégés des jours de la semaine pour les paramètres régionaux en-US sont : MON, TUE, WED, THU, FRI, SAT et SUN. La mise en correspondance de la casse est compatible.	Entrée : DATE '2020-12-31' Sortie : THU
D	Jour de la semaine (1 à 7), avec le dimanche comme 1.	Entrée : DATE '2020-12-31' Résultat : 4
DD	Jour du mois sur deux chiffres.	Entrée : DATE '2018-12-02' Résultat : 02
DDD	Jour à trois chiffres de l'année.	Entrée : DATE '2018-02-03' Résultat : 034

Type renvoyé

STRING

Exemple

SELECT CAST(DATE '2018-02-15' AS STRING FORMAT 'DD') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 15                  |
+---------------------+

Formater la partie heure sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Convertit un type de données contenant la partie heure en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec l'heure que vous devez formater.
format_string_expression : chaîne contenant les éléments de format, y compris l'élément de format horaire.

Ces types de données incluent une partie d'heure :

TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
HH	Heure du jour, format 12 heures, 2 chiffres.	Entrée : TIME '21:30:00' Sortie : 09
HH12	Heure du jour, format 12 heures	Entrée : TIME '21:30:00' Sortie : 09
HH24	Heure du jour, horloge au format 24 heures, 2 chiffres.	Entrée : TIME '21:30:00' Sortie : 21

Type renvoyé

STRING

Exemples

SELECT CAST(TIME '21:30:00' AS STRING FORMAT 'HH24') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 21                  |
+---------------------+

SELECT CAST(TIME '21:30:00' AS STRING FORMAT 'HH12') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 09                  |
+---------------------+

Mettre en forme l'élément de la minute sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caste un type de données contenant la partie minute en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec la minute que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format minute.

Ces types de données incluent une partie minute :

TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
MI	minute/2 chiffres	Entrée : TIME '01:02:03' Sortie : 02

Type renvoyé

STRING

Exemple

SELECT CAST(TIME '21:30:00' AS STRING FORMAT 'MI') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 30                  |
+---------------------+

Mettre en forme la partie seconde sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caste un type de données contenant la partie seconde en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec la partie seconde que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format seconde.

Ces types de données incluent une partie "seconde" :

TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
SS	Secondes de la minute, deux chiffres.	Entrée : TIME '01:02:03' Sortie : 03
SSSSS	Secondes du jour, cinq chiffres.	Entrée : TIME '01:02:03' Sortie : 03723
FFn	Partie fractionnaire de la seconde, `n` chiffres. Remplacez `n` par une valeur comprise entre 1 et 9. Par exemple, "FF5". La partie fractionnaire de la seconde est arrondie pour s'adapter à la taille de la sortie.	Entrée pour FF1 : TIME '01:05:07.16' Sortie : 1 Entrée pour FF2 : TIME '01:05:07.16' Sortie : 16 Entrée pour FF3 : TIME '01:05:07.16' Sortie : 016

Type renvoyé

STRING

Exemples

SELECT CAST(TIME '21:30:25.16' AS STRING FORMAT 'SS') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 25                  |
+---------------------+

SELECT CAST(TIME '21:30:25.16' AS STRING FORMAT 'FF2') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| 16                  |
+---------------------+

Mettre en forme la partie de l'indicateur méridien sous forme de chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Convertit un type de données qui contient l'indicateur méridien en chaîne. Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec l'indicateur méridien que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format indicateur méridien.

Ces types de données incluent une partie indicateur méridien :

TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
A.M.	AM si le temps est inférieur à 12, dans le cas contraire P.M., la casse de la sortie est déterminée par la première lettre de l'élément de format.	Entrée pour AM : TIME '01:02:03' Sortie : AM Entrée A.M. : TIME '16:02:03' Sortie : P.M. Entrée pour a.m. : TIME '01:02:03' Sortie : a.m. Entrée pour a.M. : TIME '01:02:03' Sortie : a.m.
a.m.	AM si l'heure est inférieure à 12, dans le cas contraire, P.M. La casse des lettres de la sortie est déterminée par la première lettre de l'élément de format.	Entrée pour AM : TIME '01:02:03' Sortie : AM Entrée pour AM : TIME '16:02:03' Sortie : PM Entrée pour am : TIME '01:02:03' Sortie : am Entrée pour aM : TIME '01:02:03' Sortie : am
PM	Le résultat est identique à l'élément de format AM.
p.m.	Le résultat est identique à l'élément de format AM.

Type renvoyé

STRING

Exemples

SELECT CAST(TIME '21:30:00' AS STRING FORMAT 'AM') AS date_time_to_string;
SELECT CAST(TIME '21:30:00' AS STRING FORMAT 'PM') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| PM                  |
+---------------------+

SELECT CAST(TIME '01:30:00' AS STRING FORMAT 'AM') AS date_time_to_string;
SELECT CAST(TIME '01:30:00' AS STRING FORMAT 'PM') AS date_time_to_string;

+---------------------+
| date_time_to_string |
+---------------------+
| AM                  |
+---------------------+

Mettre en forme la partie du fuseau horaire en tant que chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Caster un type de données contenant la partie "Fuseau horaire" en chaîne Inclut des éléments de format, qui fournissent des instructions pour mener le casting.

expression : cette expression contient le type de données avec le fuseau horaire que vous devez formater.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format de fuseau horaire.

Ces types de données incluent une partie de fuseau horaire :

DATE
TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
TZH	Décalage horaire (heure) pour un fuseau horaire. Cela inclut le signe `+/-` et l'heure à deux chiffres.	Inputstamp : TIMESTAMP '2008-12-25 05:30:00+00' Résultat : −08
TZM	Décalage horaire (minute) pour un fuseau horaire. Cela n'inclut que la minute à deux chiffres.	Inputstamp : TIMESTAMP '2008-12-25 05:30:00+00' Résultat : 00

Type renvoyé

STRING

Exemples

SELECT CAST(TIMESTAMP '2008-12-25 00:00:00+00:00' AS STRING FORMAT 'TZH') AS date_time_to_string;

-- Results depend upon where this query was executed.
+---------------------+
| date_time_to_string |
+---------------------+
| -08                 |
+---------------------+

SELECT CAST(TIMESTAMP '2008-12-25 00:00:00+00:00' AS STRING FORMAT 'TZH' AT TIME ZONE 'Asia/Kolkata')
AS date_time_to_string;

-- Because the time zone is specified, the result is always the same.
+---------------------+
| date_time_to_string |
+---------------------+
| +05                 |
+---------------------+

SELECT CAST(TIMESTAMP '2008-12-25 00:00:00+00:00' AS STRING FORMAT 'TZM') AS date_time_to_string;

-- Results depend upon where this query was executed.
+---------------------+
| date_time_to_string |
+---------------------+
| 00                  |
+---------------------+

SELECT CAST(TIMESTAMP '2008-12-25 00:00:00+00:00' AS STRING FORMAT 'TZM' AT TIME ZONE 'Asia/Kolkata')
AS date_time_to_string;

-- Because the time zone is specified, the result is always the same.
+---------------------+
| date_time_to_string |
+---------------------+
| 30                  |
+---------------------+

Mettre en forme le littéral en tant que chaîne

CAST(expression AS STRING FORMAT format_string_expression)

Élément de format	Renvoie	Exemple
-	Le résultat est identique à l'entrée.	-
.	Le résultat est identique à l'entrée.	.
/	Le résultat est identique à l'entrée.	/
,	Le résultat est identique à l'entrée.	,
'	Le résultat est identique à l'entrée.	'
;	Le résultat est identique à l'entrée.	;
:	Le résultat est identique à l'entrée.	:
Espace blanc	Le résultat est identique à l'entrée. Les espaces blancs correspondent au caractère d'espacement, ASCII 32. Il ne s'agit pas d'autres types d'espaces, tels que des tabulations ou des nouvelles lignes. Tout caractère d'espace blanc autre que le caractère ASCII 32 dans le modèle de format génère une erreur.
"texte"	La sortie correspond à la valeur entre guillemets doubles. Pour conserver un caractère de guillemet double ou de barre oblique inverse, utilisez la séquence d'échappement `\"` ou `\\`. Les autres séquences d'échappement ne sont pas acceptées.	Entrée : "abc" Sortie : abc Entrée : "a\"b\\c" Sortie : a"b\c

Mettre en forme la chaîne en tant que date et heure

Vous pouvez mettre en forme une chaîne avec les parties de date et heure suivantes :

Mettre en forme la chaîne en tant que partie d'année
Mettre en forme la chaîne en tant que partie de mois
Formater la chaîne comme partie jour
Mettre en forme la chaîne en tant que partie heure
Mettre en forme la chaîne en tant que partie minute
Formater la chaîne comme partie "seconde"
Formater la chaîne comme partie d'indicateur méridien
Mettre en forme la chaîne en tant que partie du fuseau horaire
Formater une chaîne en tant que partie de littéral

Lorsque vous mettez en forme une chaîne avec des parties de date et heure, vous devez suivre les règles de modèle de mise en forme.

Règles de format de modèle

Lorsque vous castez une chaîne en parties de date et d'heure, vous devez vous assurer que le modèle de format est valide. Le modèle de format représente les éléments transmis à CAST(string_expression AS type FORMAT format_string_expression) en tant que format_string_expression et est validé conformément aux règles suivantes :

Il contient au maximum l'un des éléments suivants : indicateur méridien, année, mois, jour, heure.
Un élément de format non littéral et non blanc ne peut pas apparaître plus d'une fois.
Si il contient l'élément de format de jour de l'année, DDD, il ne peut pas contenir de mois.
S'il contient l'élément de format 24 heures, HH24, il ne peut pas contenir l'élément de format 12 heures ni un indicateur méridien.
S'il contient l'élément de format 12 heures, HH12 ou HH, il doit également contenir un indicateur méridien.
S'il contient un indicateur méridien, il doit également contenir un élément de format 12 heures.
S'il contient l'élément de format de seconde de jour, SSSSS, il ne peut contenir aucun des éléments suivants : heure, minute, seconde ou indicateur méridien.
Il ne peut pas contenir d'élément de format tel que la valeur qu'il définit n'existe pas dans le type cible. Par exemple, un élément de format horaire tel que HH24 ne peut pas apparaître dans une chaîne que vous castez en tant que DATE.

Mettre en forme la chaîne en tant que partie d'année

CAST(string_expression AS type FORMAT format_string_expression)

Caste une année au format de chaîne en un type de données contenant la partie année. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne avec l'année que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie année.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format d'année. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie année :

DATE
DATETIME
TIMESTAMP

Si la partie YEAR est manquante dans string_expression et que le type renvoyé inclut cette partie, YEAR est défini sur l'année en cours.

Une erreur est générée si une valeur qui n'est pas un élément de format compatible apparaît dans format_string_expression ou string_expression ne contient pas une valeur spécifiée par un élément de format.

Élément de format	Renvoie	Exemple
AAAA	Si le code est délimité, il correspond à 1 à 5 chiffres. S'il n'est pas délimité, correspond à 4 chiffres. Définit la partie année sur le nombre correspondant.	Entrée pour MM-DD-YYYY : '03-12-2018' Sortie en tant que DATE : 2018-12-03 Entrée pour YYYY-MMDD : '10000-1203' Sortie en tant que DATE : 10000-12-03 Entrée pour YYYY : '18' Sortie en tant que DATE : 2018-03-01 (supposons que la date actuelle est le 23 mars 2021)
YYY	Correspond à 3 chiffres. Définit les trois derniers chiffres de la partie de l'année sur le nombre correspondant.	Entrée pour YYY-MM-DD : '018-12-03' Sortie en tant que DATE : 2018-12-03 Entrée pour YYY-MM-DD : '038-12-03' Sortie en tant que DATE : 2038-12-03
YY	Correspond à 2 chiffres. Définit les deux derniers chiffres de la partie de l'année sur le nombre correspondant.	Entrée pour YY-MM-DD : '18-12-03' Sortie en tant que DATE : 2018-12-03 Entrée pour YY-MM-DD : '38-12-03' Sortie en tant que DATE : 2038-12-03
O	Correspond à 1 chiffre. Définit le dernier chiffre de la partie de l'année sur le nombre correspondant.	Entrée pour Y-MM-DD : '8-12-03' Sortie en tant que DATE : 2008-12-03
Y,YYY	Correspond au modèle de 1 à 2 chiffres, à la virgule, puis exactement à 3 chiffres. Définit la partie année sur le nombre correspondant.	Entrée pour Y,YYY-MM-DD : '2,018-12-03' Sortie en tant que : 2008-12-03
RRRR	Comportement identique à AAAA.
RR	Correspond à 2 chiffres. Si les deux chiffres saisis sont compris entre 00 et 49 et que les deux derniers chiffres de l'année en cours sont compris entre 00 et 49, l'année renvoyée comporte les deux premiers chiffres de l'année en cours. Si les deux derniers chiffres de l'année en cours sont compris entre 50 et 99, les 2 premiers chiffres de l'année renvoyée sont supérieurs aux 2 premiers chiffres de l'année en cours d'une valeur de un. Si les deux chiffres saisis sont compris entre 50 et 99, et que les deux derniers chiffres de l'année en cours sont compris entre 00 et 49, les deux premiers chiffres de l'année renvoyée sont inférieurs aux deux premiers chiffres de l'année en cours d'une valeur de un. Si les deux derniers chiffres de l'année en cours sont compris entre 50 et 99, l'année renvoyée comporte les mêmes deux premiers chiffres que l'année en cours.	Entrée pour RR-MM-DD : '18-12-03' Sortie en tant que DATE : 2018-12-03 (exécuté en 2021) Sortie en tant que DATE : 2118-12-03 (exécuté en 2050) Entrée pour RR-MM-DD : '50-12-03' Sortie en tant que DATE : 2050-12-03 (exécuté en 2021) Sortie en tant que DATE : 2050-12-03 (exécuté en 2050)

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

DATE
DATETIME
TIMESTAMP

Exemples

SELECT CAST('18-12-03' AS DATE FORMAT 'YY-MM-DD') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 2018-02-03          |
+---------------------+

Mettre en forme la chaîne en tant que partie de mois

CAST(string_expression AS type FORMAT format_string_expression)

Caste un mois au format de chaîne en un type de données contenant la partie mois. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne contenant le mois que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Elle doit inclure la partie mois.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de mois. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Les types de données suivants incluent une partie mois :

DATE
DATETIME
TIMESTAMP

Si la partie MONTH est manquante dans string_expression et que le type renvoyé inclut cette partie, MONTH est défini sur le mois en cours.

Élément de format	Renvoie	Exemple
MM	Correspond à 2 chiffres. Définit la partie "mois" sur le nombre correspondant.	Entrée pour MM-JJ-AAAA : '03-12-2018' Sortie en tant que DATE : 2018-12-03
LUN	Correspond à trois lettres. Définit la partie du mois sur la chaîne correspondante interprétée comme le nom abrégé du mois.	Entrée pour MON JJ, AAAA : 'DEC 03 2018' Sortie en tant que DATE : 2018-12-03
MOIS	Correspond à 9 lettres. Définit la partie du mois sur la chaîne correspondante interprétée comme le nom du mois.	Entrée pour MONTH DD, AAAA : 'DECEMBER 03, 2018' Sortie en tant que DATE : 2018-12-03

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

DATE
DATETIME
TIMESTAMP

Exemples

SELECT CAST('DEC 03, 2018' AS DATE FORMAT 'MON DD, YYYY') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 2018-12-03          |
+---------------------+

Mettre en forme la chaîne comme partie jour

CAST(string_expression AS type FORMAT format_string_expression)

Caste un jour au format de chaîne en un type de données contenant la partie jour. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne contenant le jour que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie jour.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format de jour. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie jour :

DATE
DATETIME
TIMESTAMP

Si la partie DAY est manquante dans string_expression et que le type renvoyé inclut cette partie, DAY est défini sur 1.

Élément de format	Renvoie	Exemple
DD	Correspond à 2 chiffres. Définit la partie "jour" du nombre correspondant.	Entrée pour MONTH DD, AAAA : 'DECEMBER 03, 2018' Sortie en tant que DATE : 2018-12-03

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

DATE
DATETIME
TIMESTAMP

Exemples

SELECT CAST('DECEMBER 03, 2018' AS DATE FORMAT 'MONTH DD, YYYY') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 2018-12-03          |
+---------------------+

Mettre en forme la chaîne en tant que partie heure

CAST(string_expression AS type FORMAT format_string_expression)

Caste une heure au format de chaîne en un type de données contenant la partie heure. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne contenant l'heure que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie heure.
format_string_expression : chaîne contenant les éléments de format, y compris l'élément de format horaire. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie d'heure :

TIME
DATETIME
TIMESTAMP

Si la partie HOUR est manquante dans string_expression et que le type renvoyé inclut cette partie, HOUR est défini sur 0.

Élément de format	Renvoie	Exemple
HH	Correspond à 2 chiffres. Si le nombre correspondant `n` est `12`, définit `temp = 0`. Sinon, définit `temp = n`. Si la valeur correspondante de l'élément de format AM/PM est PM, définit `temp = n + 12`. Définit la partie heure sur `temp`. Un indicateur méridien doit être présent dans le modèle de format, en présence de la valeur HH.	Entrée pour HH:MI PM : '03:30 P.M.' Sortie au format TIME : 15:30:00
HH12	Même comportement que HH.
HH24	Correspond à 2 chiffres. Définit la partie heure sur le nombre correspondant.	Entrée pour HH24:MI : '15:30' Sortie au format TIME : 15:30:00

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

TIME
DATETIME
TIMESTAMP

Exemples

SELECT CAST('15:30' AS TIME FORMAT 'HH24:MI') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 15:30:00            |
+---------------------+

Mettre en forme la chaîne en partie minute

CAST(string_expression AS type FORMAT format_string_expression)

Caste une minute au format de chaîne dans un type de données contenant la partie minute. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne avec la minute que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie minute.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format minute. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie minute :

TIME
DATETIME
TIMESTAMP

Si la partie MINUTE est manquante dans string_expression et que le type renvoyé inclut cette partie, MINUTE est défini sur 0.

Élément de format	Renvoie	Exemple
MI	Correspond à 2 chiffres. Définit la partie de minutes sur le nombre correspondant.	Entrée pour HH:MI PM : '03:30 P.M.' Sortie au format TIME : 15:30:00

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

TIME
DATETIME
TIMESTAMP

Exemples

SELECT CAST('03:30 P.M.' AS TIME FORMAT 'HH:MI P.M.') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 15:30:00            |
+---------------------+

Mettre en forme la chaîne en partie seconde

CAST(string_expression AS type FORMAT format_string_expression)

Caste une seconde au format de chaîne en un type de données contenant la partie seconde. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne avec la seconde que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie seconde.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format seconde. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie "seconde" :

TIME
DATETIME
TIMESTAMP

Si la partie SECOND est manquante dans string_expression et que le type renvoyé inclut cette partie, SECOND est défini sur 0.

Élément de format	Renvoie	Exemple
SS	Correspond à 2 chiffres. Définit la partie "seconde" sur le nombre correspondant.	Entrée pour HH:MI:SS PM : '03:30:02 P.M.' Sortie au format TIME : 15:30:02
SSSSS	Correspond à 5 chiffres. Définit les parties heure, minute et seconde en interprétant le nombre correspondant comme le nombre de secondes écoulées après minuit.	Entrée pour SSSSS : "03723" Sortie en tant que TIME : 01:02:03
FFn	Correspond à `n` chiffres, où `n` est le nombre qui suit FF dans l'élément de format. Définit la partie fractionnaire de la partie "seconde" sur le nombre correspondant.	Entrée pour HH24:MI:SS.FF1 : '01:05:07.16' Sortie en tant que TIME : 01:05:07.2 Entrée pour HH24:MI:SS.FF2 : '01:05:07.16' Sortie en tant que TIME : 01:05:07.16 Entrée pour HH24:MI:SS.FF3 : 'FF3: 01:05:07.16' Sortie en tant que TIME : 01:05:07.160

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

TIME
DATETIME
TIMESTAMP

Exemples

SELECT CAST('01:05:07.16' AS TIME FORMAT 'HH24:MI:SS.FF1') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 01:05:07.2          |
+---------------------+

Mettre en forme la chaîne en partie indicateur méridien

CAST(string_expression AS type FORMAT format_string_expression)

Caste un indicateur méridien au format de chaîne en un type de données contenant la partie indicateur méridien. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne avec l'indicateur méridien que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Elle doit inclure la partie indicateur méridien.
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format indicateur méridien. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie indicateur méridien :

TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
AM ou PM	Correspond à l'expression régulière `'(A\|P)\.M\.'`.	Entrée pour HH:MI AM : '03:30 A.M.' Sortie au format TIME : 03:30:00 Entrée pour HH:MI PM : '03:30 P.M.' Sortie en tant que TIME : 15:30:00 Entrée pour HH:MI P.M. : '03:30 A.M.' Sortie en tant que TIME : 03:30:00 Entrée pour HH:MI A.M. : '03:30 P.M.' Sortie en tant que TIME : 15:30:00 Entrée pour HH:MI a.m. : '03:30 a.m.' Sortie en tant que TIME : 03:30:00

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

TIME
DATETIME
TIMESTAMP

Exemples

SELECT CAST('03:30 P.M.' AS TIME FORMAT 'HH:MI A.M.') AS string_to_date_time

+---------------------+
| string_to_date_time |
+---------------------+
| 15:30:00            |
+---------------------+

Mettre en forme la chaîne en tant que partie du fuseau horaire

CAST(string_expression AS type FORMAT format_string_expression)

Caste un fuseau horaire au format de chaîne en un type de données contenant la partie de fuseau horaire. Inclut des éléments de format, qui fournissent des instructions sur la façon de procéder au casting.

string_expression : cette expression contient la chaîne contenant le fuseau horaire que vous devez formater.
type : type de données vers lequel vous effectuez un casting. Doit inclure la partie "fuseau horaire".
format_string_expression : chaîne contenant des éléments de format, y compris l'élément de format de fuseau horaire. Les éléments de format de cette chaîne sont définis collectivement comme le modèle de format, qui doit respecter ces règles.

Ces types de données incluent une partie de fuseau horaire :

DATE
TIME
DATETIME
TIMESTAMP

Élément de format	Renvoie	Exemple
TZH	Correspond à l'expression régulière `'(\+\|\-\| )[0-9]{2}'`. Définit le fuseau horaire et les parties d'heure sur le signe et le numéro correspondants. Définit le signe de fuseau horaire comme étant la première lettre de la chaîne correspondante. Le nombre 2 correspond à deux chiffres au maximum pour la correspondance non exacte et deux chiffres exactement pour la correspondance exacte.	Entrée pour AAAA-MM-JJ HH:MI:SSTZH : '2008-12-25 05:30:00-08' Sortie au format TIMESTAMP : 2008-12-25 05:30:00-08
TZM	Correspond à 2 chiffres. Attribuez la valeur `n` au numéro correspondant. Si le signe de fuseau horaire est le signe moins, définit la partie de fuseau horaire sur `-n`. Sinon, définit la partie minute du fuseau horaire sur `n`.	Entrée pour AAAA-MM-JJ HH:MI:SSTZH : '2008-12-25 05:30:00+05.30' Sortie au format TIMESTAMP : 2008-12-25 05:30:00+05.30

Type renvoyé

Type de données sur lequel la chaîne a été castée. Il peut s'agir de :

DATE
TIME
DATETIME
TIMESTAMP

Exemples

SELECT CAST('2020.06.03 00:00:53+00' AS TIMESTAMP FORMAT 'YYYY.MM.DD HH:MI:SSTZH') AS string_to_date_time

+-----------------------------+
| as_timestamp                |
+-----------------------------+
| 2020-06-03 00:00:53.110 UTC |
+-----------------------------+

Mettre en forme une chaîne en littéral

CAST(string_expression AS data_type FORMAT format_string_expression)

Élément de format	Renvoie	Exemple
-	Le résultat est identique à l'entrée.
.	Le résultat est identique à l'entrée.	.
/	Le résultat est identique à l'entrée.	/
,	Le résultat est identique à l'entrée.	,
'	Le résultat est identique à l'entrée.	'
;	Le résultat est identique à l'entrée.	;
:	Le résultat est identique à l'entrée.	:
Espace blanc	Une séquence consécutive d'un ou de plusieurs espaces du modèle de format est mise en correspondance avec un ou plusieurs caractères d'espacement Unicode consécutifs dans l'entrée. L'espace signifie le caractère d'espace ASCII 32. Cela ne signifie pas les espaces généraux, tels qu'une tabulation ou une nouvelle ligne. Tout caractère d'espacement qui n'est pas le caractère ASCII 32 dans le modèle de format génère une erreur.
"texte"	Résultat généré par l'élément de mise en forme en utilisant cette expression régulière et `s`, représentant l'entrée de chaîne : `regex.escape(s)`.	Entrée : "abc" Sortie : abc Entrée : "a\"b\\c" Sortie : a"b\c

Mettre en forme le type numérique en tant que chaîne

CAST(numeric_expression AS STRING FORMAT format_string_expression)

Vous pouvez caster un type numérique vers une chaîne en combinant les éléments de format suivants :

Chiffres
Séparateur décimal
Signe
Symbole de devise
Séparateur de groupes
Autres éléments de format

À l'exception de l'élément de format d'exposant (EEEE), tous les éléments de format génèrent un nombre fixe de caractères dans la sortie, et celle-ci est alignée par le point décimal. Pour supprimer des caractères vides et des zéros de fin, utilisez l'option FM.

Type renvoyé

STRING

Exemple

SELECT input, CAST(input AS STRING FORMAT '$999,999.999') AS output
FROM UNNEST([1.2, 12.3, 123.456, 1234.56, -12345.678, 1234567.89]) AS input

+------------+---------------+
|   input    |    output     |
+------------+---------------+
|        1.2 |        $1.200 |
|       12.3 |       $12.300 |
|    123.456 |      $123.456 |
|    1234.56 |    $1,234.560 |
| -12345.678 |  -$12,345.678 |
| 1234567.89 |  $###,###.### |
+------------+---------------+

Mettre en forme les chiffres sous forme de chaîne

Les éléments de format suivants produisent des chiffres. Si les éléments au format numérique ne sont pas suffisants pour représenter l'entrée, tous les éléments de format numérique sont remplacés par # dans la sortie.

Élément de format Renvoie Exemple

Un chiffre décimal. Les zéros de début et de fin sont inclus.

Élément de format	Renvoie	Exemple
0	Un chiffre décimal. Les zéros de début et de fin sont inclus.	Entrée : `12` Format : `'000'` Sortie : `' 012'` Entrée : `12` Format : `'000.000'` Sortie : `' 012.000'` Entrée : `-12` Format : `'000.000'` Sortie : `'-012.000'`
9	Un chiffre décimal. Les zéros de début sont remplacés par des espaces. Les zéros de fin sont inclus.	Entrée : `12` Format : `'999'` Sortie : `' 12'` Entrée : `12` Format : `'999.999'` Sortie : `' 12.000'`
X ou x	Un chiffre hexadécimal. Ne peut pas apparaître avec d'autres éléments de format, à l'exception de 0, FM et de l'élément de format de signe. Le nombre maximal de chiffres hexadécimaux compris dans la chaîne de format est de 16. X génère des lettres majuscules et x génère des lettres minuscules. Lorsque 0 est combiné à l'élément de format hexadécimal, la lettre générée par 0 correspond à la casse de l'élément X ou x suivant. S'il n'y a pas de X ou de X ultérieur, 0 génère une lettre majuscule.	Entrée : `43981` Format : `'XXXX'` Sortie : `' ABCD'` Entrée : `43981` Format : `'xxxx'` Sortie : `' abcd'` Entrée : `43981` Format : `'0X0x'` Sortie : `' ABcd'` Entrée : `43981` Format : `'0000000X'` Sortie : `' 0000ABCD'`

Entrée : 12
Format : '000'
Sortie : ' 012'

Entrée : 12
Format : '000.000'
Sortie : ' 012.000'

Entrée : -12
Format : '000.000'
Sortie : '-012.000'

Un chiffre décimal. Les zéros de début sont remplacés par des espaces. Les zéros de fin sont inclus.

Entrée : 12
Format : '999'
Sortie : ' 12'

Entrée : 12
Format : '999.999'
Sortie : ' 12.000'

X ou x

Un chiffre hexadécimal. Ne peut pas apparaître avec d'autres éléments de format, à l'exception de 0, FM et de l'élément de format de signe. Le nombre maximal de chiffres hexadécimaux compris dans la chaîne de format est de 16.

X génère des lettres majuscules et x génère des lettres minuscules.

Lorsque 0 est combiné à l'élément de format hexadécimal, la lettre générée par 0 correspond à la casse de l'élément X ou x suivant. S'il n'y a pas de X ou de X ultérieur, 0 génère une lettre majuscule.

Entrée : 43981
Format : 'XXXX'
Sortie : ' ABCD'

Entrée : 43981
Format : 'xxxx'
Sortie : ' abcd'

Entrée : 43981
Format : '0X0x'
Sortie : ' ABcd'

Entrée : 43981
Format : '0000000X'
Sortie : ' 0000ABCD'

Type renvoyé

STRING

Exemple

SELECT
  CAST(12 AS STRING FORMAT '999') as a,
  CAST(-12 AS STRING FORMAT '999') as b;

+------+------+
|  a   |  b   |
+------+------+
|   12 |  -12 |
+------+------+

Mettre en forme le nombre décimal sous forme de chaîne

Les éléments de format suivants génèrent un séparateur décimal. Ces éléments de format s'excluent mutuellement. Au maximum, un seul peut apparaître dans la chaîne de format.

Élément de format	Renvoie	Exemple
. (point)	Séparateur décimal.	Entrée : `123.58` Format : `'999.999'` Sortie : `' 123.580'`
D	Séparateur décimal des paramètres régionaux actuels.	Entrée : `123.58` Format : `'999D999'` Sortie : `' 123.580'`

Type renvoyé

STRING

Exemple

SELECT CAST(12.5 AS STRING FORMAT '99.99') as a;

+--------+
|   a    |
+--------+
|  12.50 |
+--------+

Mettre en forme le signe sous forme de chaîne

Les éléments de format suivants génèrent le signe (+/-). Ces éléments de format sont mutuellement exclusifs. Au maximum, un seul peut apparaître dans la chaîne de format.

S'il n'y a pas d'éléments de format de signe, un espace supplémentaire est réservé pour le signe. Par exemple, si l'entrée est 12 et que la chaîne de format est '99', le résultat est ' 12', avec une longueur de trois caractères.

Le signe apparaît avant le numéro. Si le modèle de format inclut un élément de symbole de devise, le signe s'affiche avant le symbole de devise.

Élément de format	Renvoie	Exemple
S	Signe explicite. Renvoie `+` pour les nombres positifs et `-` pour les nombres négatifs. La position dans la sortie est ancrée au nombre.	Entrée : `-12` Format : `'S9999'` Sortie : `' -12'` Entrée : `-12` Format : `'9999S'` Sortie : `' 12-'`
MI	Signe explicite. Renvoie un espace pour les nombres positifs et `-` pour les nombres négatifs. Cet élément ne peut apparaître qu'en dernière position.	Entrée : `12` Format : `'9999MI'` Sortie : `' 12 '` Entrée : `-12` Format : `'9999MI'` Sortie : `' 12-'`
PR	Pour les nombres négatifs, la valeur est placée entre crochets. Pour les nombres positifs, la valeur est renvoyée avec un espace de début et de fin. Cet élément ne peut apparaître qu'en dernière position.	Entrée : `12` Format : `'9999PR'` Sortie : `' 12 '` Entrée : `-12` Format : `'9999PR'` Sortie : `' <12>'`

Type renvoyé

STRING

Exemple

SELECT
  CAST(12 AS STRING FORMAT 'S99') as a,
  CAST(-12 AS STRING FORMAT 'S99') as b;

+-----+-----+
|  a  |  b  |
+-----+-----+
| +12 | -12 |
+-----+-----+

Mettre en forme le symbole de devise sous forme de chaîne

Les éléments de format suivants génèrent un symbole de devise. Ces éléments de format s'excluent mutuellement. Au maximum, un seul peut apparaître dans la chaîne de format. Dans le résultat, le symbole de devise apparaît avant le premier chiffre ou le séparateur décimal.

Élément de format	Renvoie	Exemple
$	signe dollar ($)	Entrée : `-12` Format : `'$999'` Sortie : `' -$12'`
C ou c	Code ISO-4217 de la devise des paramètres régionaux actuels.	Entrée : `-12` Format : `'C999'` Sortie : `' -USD12'` Entrée : `-12` Format : `'c999'` Sortie : `' -usd12'`
L	Symbole de la devise des paramètres régionaux actuels.	Entrée : `-12` Format : `'L999'` Sortie : `' -$12'`

Type renvoyé

STRING

Exemple

SELECT
  CAST(12 AS STRING FORMAT '$99') as a,
  CAST(-12 AS STRING FORMAT '$99') as b;

+------+------+
|  a   |  b   |
+------+------+
|  $12 | -$12 |
+------+------+

Formater le séparateur de groupes sous forme de chaîne

Les éléments de format suivants génèrent un séparateur de groupe.

Élément de format	Renvoie	Exemple
, (Virgule)	Séparateur de groupes.	Entrée : `12345` Format : `'999,999'` Sortie : `' 12,345'`
G	Point de séparation du groupe des paramètres régionaux actuels.	Entrée : `12345` Format : `'999G999'` Sortie : `' 12,345'`

Type renvoyé

STRING

Exemple

SELECT CAST(1234 AS STRING FORMAT '999,999') as a;

+----------+
|    a     |
+----------+
|    1,234 |
+----------+

Autres éléments de format numérique

Élément de format	Renvoie	Exemple
B	Affiche les espaces lorsque la partie entière est égale à zéro. Si la partie entière du nombre est 0, les éléments de format suivants génèrent des espaces dans la sortie : chiffres (9, X, 0), séparateur décimal, séparateur de groupe, devise, signe et exposant.	Entrée : `0.23` Format : `'B99.999S'` Sortie : `' '` Entrée : `1.23` Format : `'B99.999S'` Sortie : `' 1.230+'`
EEEE	Affiche la partie exponentielle de la valeur en notation scientifique. Si la valeur de l'exposant est comprise entre -99 et 99, la sortie est de quatre caractères. Sinon, le nombre minimal de chiffres est utilisé dans la sortie.	Entrée : `20` Format : `'9.99EEEE'` Sortie : `' 2.0E+01'` Entrée : `299792458` Format : `'S9.999EEEE'` Sortie : `'+2.998E+08'`
FM	Supprime tous les espaces et les zéros de fin de la sortie. Vous pouvez utiliser cet élément pour supprimer les espaces et les zéros de fin générés par d'autres éléments de format.	Entrée : `12.5` Format : `'999999.000FM'` Sortie : `'12.5'`
RN	Renvoie la valeur sous la forme de chiffres romains, arrondis à l'entier le plus proche. La valeur doit être comprise entre 1 et 3 999. Le résultat est complété par des espaces à gauche jusqu'à une longueur de 15. Cet élément ne peut pas être utilisé avec d'autres éléments de format sauf `FM`.	Entrée : `2021` Format : `'RN'` Sortie : `' MMXXI'`
V	La valeur d'entrée est multipliée par 10^n, où n est le nombre de 9 après le `V`. Cet élément ne peut pas être utilisé avec l'élément de format du séparateur décimal ou de l'exposant.	Entrée : `23.5` Format : `'S000V00'` Sortie : `'+02350'`

Type renvoyé

STRING

Exemple

SELECT CAST(-123456 AS STRING FORMAT '9.999EEEE') as a;"

+------------+
|     a      |
+------------+
| -1.235E+05 |
+------------+

À propos de l'encodage BASE

L'encodage BASE traduit les données binaires au format chaîne en une représentation radix-X.

Si X est égal à 2, 8 ou 16, les chiffres arabes 0 à 9 et les lettres latines a à z sont utilisés dans la chaîne codée. Ainsi, par exemple, les résultats de l'encodage hexadécimal BASE16/hexadécimal contiennent 0~9 et a~f).

Si X est égal à 32 ou 64, les tables de caractères par défaut sont définies en RFC 4648. Lorsque vous décodez une chaîne BASE où X correspond à 2, 8 ou 16, les lettres latines de la chaîne d'entrée ne sont pas sensibles à la casse. Par exemple, "3a" et "3A" sont des chaînes d'entrée valides pour le décodage BASE16/Hexadécimal, et produiront le même résultat.

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.

X	ABS(X)
25	25
-25	25
`+inf`	`+inf`
`-inf`	`+inf`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	INT64	NUMERIC	BIGNUMERIC	FLOAT64

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.

X	SIGN(X)
25	+1
0	0
-25	-1
NaN	NaN

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	INT64	NUMERIC	BIGNUMERIC	FLOAT64

IS_INF

IS_INF(X)

Description

Renvoie TRUE si la valeur correspond à l'infini positif ou négatif.

X	IS_INF(X)
`+inf`	`TRUE`
`-inf`	`TRUE`
25	`FALSE`

IS_NAN

IS_NAN(X)

Description

Renvoie TRUE si la valeur est une valeur NaN.

X	IS_NAN(X)
`NaN`	`TRUE`
25	`FALSE`

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.

X	O	IEEE_DIVIDE(X, Y)
20.0	4.0	5,0
0,0	25,0	0,0
25,0	0,0	`+inf`
-25,0	0,0	`-inf`
0,0	0,0	`NaN`
0,0	`NaN`	`NaN`
`NaN`	0,0	`NaN`
`+inf`	`+inf`	`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. Génère une erreur si X est inférieur à 0.

X	SQRT(X)
`25.0`	`5.0`
`+inf`	`+inf`
`X < 0`	Erreur

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

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".

X	O	POW(X, Y)
2.0	3,0	8.0
1.0	Toute valeur, y compris `NaN`	1.0
Toute valeur, y compris `NaN`	0	1,0
-1,0	`+inf`	1.0
-1,0	`-inf`	1,0
ABS(X) < 1	`-inf`	`+inf`
ABS(X) > 1	`-inf`	0,0
ABS(X) < 1	`+inf`	0,0
ABS(X) > 1	`+inf`	`+inf`
`-inf`	Y < 0	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`
Valeur finie < 0	Non entier	Erreur
0	Valeur finie < 0	Erreur

Type de données renvoyé

Le type de données renvoyé est déterminé par les types des arguments à l'aide du tableau suivant.

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

POWER

POWER(X, Y)

Description

Synonyme de POW(X, Y).

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.

X	EXP(X)
0,0	1.0
`+inf`	`+inf`
`-inf`	0,0

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

LN

LN(X)

Description

Calcule le logarithme népérien de X. Génère une erreur si X est inférieur ou égal à zéro.

X	LN(X)
1.0	0,0
`+inf`	`+inf`
`X < 0`	Erreur

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

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.

X	Y	LOG(X, Y)
100,0	10,0	2.0
`-inf`	Toute valeur	`NaN`
Toute valeur	`+inf`	`NaN`
`+inf`	0,0 < Y < 1,0	`-inf`
`+inf`	Y > 1,0	`+inf`
X <= 0	Toute valeur	Erreur
Toute valeur	Y <= 0	Erreur
Toute valeur	1.0	Erreur

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

LOG10

LOG10(X)

Description

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

X	LOG10(X)
100,0	2.0
`-inf`	`NaN`
`+inf`	`NaN`
X <= 0	Erreur

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

GREATEST

GREATEST(X1,...,XN)

Description

Renvoie la plus grande valeur parmi "X1,...,XN" (identifiée à l'aide de la comparaison "<"). Si une partie de X1,...,XN est NULL, la valeur renvoyée est NULL.

X1,...,XN	GREATEST(X1,...,XN)
3,5,1	5

Type de données renvoyé

Type de données des valeurs d'entrée

LEAST

LEAST(X1,...,XN)

Description

Renvoie la plus petite valeur parmi "X1,...,XN" (identifiée à l'aide de la comparaison ">"). Si une partie de X1,...,XN est NULL, la valeur renvoyée est NULL.

X1,...,XN	LEAST(X1,...,XN)
3,5,1	1

Type de données renvoyé

Type de données des valeurs d'entrée

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.

X	O	DIV(X, Y)
20	4	5
0	20	0
20	0	Erreur

Type de données renvoyé

Le type de données renvoyé est déterminé par les types des arguments à l'aide du tableau suivant.

ENTRÉE	INT64	NUMERIC	BIGNUMERIC
INT64	INT64	NUMERIC	BIGNUMERIC
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Description

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

X	O	SAFE_DIVIDE(X, Y)
20	4	5
0	20	`0`
20	0	`NULL`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Description

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

X	O	SAFE_MULTIPLY(X, Y)
20	4	80

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_NEGATE

SAFE_NEGATE(X)

Description

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

X	SAFE_NEGATE(X)
+1	-1
-1	+1
0	0

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	INT64	NUMERIC	BIGNUMERIC	FLOAT64

SAFE_ADD

SAFE_ADD(X, Y)

Description

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

X	O	SAFE_ADD(X, Y)
5	4	9

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Description

Renvoie le résultat de Y soustrait de X. Équivaut à l'opérateur de soustraction (-), mais renvoie NULL en cas de débordement.

X	O	SAFE_SUBTRACT(X, Y)
5	4	1

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
INT64	INT64	NUMERIC	BIGNUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC	FLOAT64
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64	FLOAT64

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.

X	O	MOD(X, Y)
25	12	1
25	0	Erreur

Type de données renvoyé

Le type de données renvoyé est déterminé par les types des arguments à l'aide du tableau suivant.

ENTRÉE	INT64	NUMERIC	BIGNUMERIC
INT64	INT64	NUMERIC	BIGNUMERIC
NUMERIC	NUMERIC	NUMERIC	BIGNUMERIC
BIGNUMERIC	BIGNUMERIC	BIGNUMERIC	BIGNUMERIC

ARRONDI

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. Cette fonction génère une erreur en cas de débordement.

X	ROUND(X)
2.0	2,0
2,3	2.0
2,8	3,0
2.5	3,0
-2,3	-2,0
-2,8	-3,0
-2,5	-3,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

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.

X	TRUNC(X)
2.0	2,0
2,3	2.0
2.8	2.0
2.5	2.0
-2,3	-2,0
-2,8	-2,0
-2,5	-2,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

CEIL

CEIL(X)

Description

Renvoie la plus petite valeur intégrale parmi celles qui ne sont pas inférieures à X.

X	CEIL(X)
2.0	2,0
2,3	3,0
2.8	3,0
2.5	3,0
-2,3	-2,0
-2,8	-2,0
-2,5	-2,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

CEILING

CEILING(X)

Description

Synonyme de CEIL(X)

FLOOR

FLOOR(X)

Description

Renvoie la plus grande valeur intégrale parmi celles qui ne sont pas supérieures à X.

X	FLOOR(X)
2,0	2,0
2,3	2.0
2.8	2.0
2.5	2.0
-2,3	-3,0
-2,8	-3,0
-2,5	-3,0
0	0
`+inf`	`+inf`
`-inf`	`-inf`
`NaN`	`NaN`

Type de données renvoyé

ENTRÉE	INT64	NUMERIC	BIGNUMERIC	FLOAT64
RÉSULTAT	FLOAT64	NUMERIC	BIGNUMERIC	FLOAT64

COS

COS(X)

Description

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

X	COS(X)
`+inf`	`NaN`