Expressions, fonctions et opérateurs

Cette page présente en détail les expressions SQL de Cloud Spanner, 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 (America/Los_Angeles) 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          |
+-------------+

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 Cloud Spanner SQL exécute 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 ci-dessous récapitule toutes les options disponibles de conversion et de coercition pour les types de données SQL de Cloud Spanner. La colonne Coerce to s'applique à toutes les expressions d'un type de données particulier (par exemple, une colonne).

Type source Casting vers Coercition vers
INT64 BOOL
INT64
NUMERIC
FLOAT64
CHA STRINGNE
NUMERIC
FLOAT64
NUMERIC INT64
NUMERIC
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
NUMERIC
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
NUMERIC
FLOAT64
CHA STRINGNE
BYTES
DATE
TIMESTAMP
 
BYTES STRING
BYTES
 
DATE STRING
DATE
TIMESTAMP
TIMESTAMP STRING
DATE
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 Cloud Spanner SQL 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, Cloud Spanner SQL 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.

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
FLOAT64 FLOAT64
NUMERIC NUMERIC
FLOAT64
CHAÎNE CHAÎNE
DATE DATE
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.

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
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 Cloud Spanner SQL.

ANY_VALUE

ANY_VALUE(expression [HAVING {MAX | MIN} expression2])

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 IGNORE NULLS était spécifié. Les lignes pour lesquelles la valeur de expression est définie sur NULL ne sont pas prises en compte et ne seront pas sélectionnées.

Types d'arguments acceptés

Tous

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

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

ARRAY_AGG

ARRAY_AGG([DISTINCT] expression [{IGNORE|RESPECT} NULLS] [HAVING {MAX | MIN} expression2])

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 :

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. IGNORE NULLS ou RESPECT NULLS : si IGNORE NULLS est spécifié, 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.
  3. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Ordre des éléments de sortie

L'ordre des éléments dans le résultat est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

Type de données renvoyé

ARRAY

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

Exemples

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

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression [HAVING {MAX | MIN} expression2])

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.

Types d'arguments acceptés

ARRAY

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Ordre des éléments de sortie

L'ordre des éléments dans le résultat est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

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

AVG

AVG([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

Types d'arguments acceptés

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

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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

BIT_AND

BIT_AND([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

Types d'arguments acceptés

  • INT64

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

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([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

Types d'arguments acceptés

  • INT64

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

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 [HAVING {MAX | MIN} expression2])

Description

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

Types d'arguments acceptés

  • INT64

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

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

NB

1. COUNT(*)

2. COUNT([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

Types d'arguments acceptés

expression peut correspondre à n'importe quel type de données. 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 :

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

INT64

Exemples

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 COUNT(*) AS count_star, COUNT(x) AS count_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------------+---------+
| count_star | count_x |
+------------+---------+
| 5          | 4       |
+------------+---------+

COUNTIF

COUNTIF([DISTINCT] expression [HAVING {MAX | MIN} expression2])

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.

Types d'arguments acceptés

BOOL

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

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

LOGICAL_AND

LOGICAL_AND(expression [HAVING {MAX | MIN} expression2])

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

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

BOOL

Exemples

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

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

LOGICAL_OR

LOGICAL_OR(expression [HAVING {MAX | MIN} expression2])

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

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

BOOL

Exemples

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

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

MAX

MAX(expression [HAVING {MAX | MIN} expression2])

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

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

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

MIN

MIN(expression [HAVING {MAX | MIN} expression2])

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

Clause facultative

HAVING MAX ou HAVING MIN : limite l'ensemble des lignes que la fonction agrège selon une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

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

STRING_AGG

STRING_AGG([DISTINCT] expression [, delimiter] [HAVING {MAX | MIN} expression2])

Description

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

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

Types d'arguments acceptés

STRING BYTES

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Ordre des éléments de sortie

L'ordre des éléments dans le résultat est non déterministe, ce qui implique que vous pouvez recevoir un résultat différent chaque fois que vous utilisez cette fonction.

Type de données renvoyé

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

SUM

SUM([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

Renvoie la somme des valeurs non nulles.

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

Types d'arguments acceptés

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

Clauses facultatives

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

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
RÉSULTATINT64NUMERICFLOAT64

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 SUM(x) AS sum
FROM UNNEST([]) AS x;

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

Clauses courantes

Clauses HAVING MAX et HAVING MIN

La plupart des fonctions d'agrégation acceptent deux clauses facultatives appelées HAVING MAX et HAVING MIN, qui limitent l'ensemble de lignes agrégées par une fonction aux lignes ayant une valeur maximale ou minimale dans une colonne particulière. La syntaxe se présente généralement comme suit :

aggregate_function(expression1 [HAVING {MAX | MIN} expression2])
  • HAVING MAX: limite l'ensemble de lignes que la fonction agrège à celles dont la valeur pour expression2 est égale à la valeur maximale de expression2 dans le groupe. La valeur maximale est égale au résultat de MAX(expression2).
  • HAVING MIN limite l'ensemble de lignes regroupées par la fonction avec celles dont la valeur pour expression2 est égale à la valeur minimale de expression2 dans le groupe. La valeur minimale est égale au résultat de MIN(expression2).

Ces clauses ignorent les valeurs NULL lors du calcul de la valeur maximale ou minimale, sauf si expression2 a la valeur NULL pour toutes les lignes.

Ces clauses ne sont compatibles qu'avec les types de données pouvant être triées.

Exemple

Dans cet exemple, les précipitations moyennes sont renvoyée pour l'année la plus récente, soit 2001.

WITH Precipitation AS
 (SELECT 2001 as year, 'spring' as season, 9 as inches UNION ALL
  SELECT 2001, 'winter', 1 UNION ALL
  SELECT 2000, 'fall', 3 UNION ALL
  SELECT 2000, 'summer', 5 UNION ALL
  SELECT 2000, 'spring', 7 UNION ALL
  SELECT 2000, 'winter', 2)
SELECT AVG(inches HAVING MAX year) as average FROM Precipitation

+---------+
| average |
+---------+
| 5       |
+---------+

En premier lieu, la requête obtient les lignes présentant la valeur maximale de la colonne year. Celles-ci sont au nombre de deux :

+------+--------+--------+
| year | season | inches |
+------+--------+--------+
| 2001 | spring | 9      |
| 2001 | winter | 1      |
+------+--------+--------+

Enfin, la requête calcule la moyenne des valeurs de la colonne inches (9 et 1) avec le résultat suivant :

+---------+
| average |
+---------+
| 5       |
+---------+

Fonctions d'agrégation statistique

Cloud Spanner SQL accepte les fonctions d'agrégation statistique ci-après.

STDDEV_SAMP

STDDEV_SAMP([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

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

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 :

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

FLOAT64

STDDEV

STDDEV([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

Un alias de STDDEV_SAMP.

VAR_SAMP

VAR_SAMP([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

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

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

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 :

  1. DISTINCT : chaque valeur distincte d'expression n'est agrégée qu'une seule fois dans le résultat.
  2. HAVING MAX ou HAVING MIN : limite l'ensemble de lignes que la fonction agrège en fonction d'une valeur maximale ou minimale. Consultez les clauses HAVING MAX et HAVING MIN pour plus de détails.

Type de données renvoyé

FLOAT64

VARIANCE

VARIANCE([DISTINCT] expression [HAVING {MAX | MIN} expression2])

Description

Un alias de VAR_SAMP.

Fonctions de conversion

Cloud Spanner SQL 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)

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 Cloud Spanner SQL 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.

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

Cloud Spanner SQL accepte le casting en 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 BOOL

CAST(expression AS BOOL)

Description

Cloud Spanner SQL accepte le casting en 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)

Description

Cloud Spanner SQL accepte le casting en BYTES. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • BYTES
  • STRING

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)

Description

Cloud Spanner SQL accepte le casting en DATE. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • STRING
  • TIMESTAMP

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 FLOAT64

CAST(expression AS FLOAT64)

Description

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

  • INT64
  • FLOAT64
  • NUMERIC
  • 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.
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

Cloud Spanner SQL accepte le casting en types entiers. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • INT64
  • FLOAT64
  • NUMERIC
  • 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 NUMERIC

CAST(expression AS NUMERIC)

Description

Cloud Spanner SQL accepte le casting en NUMERIC. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • INT64
  • FLOAT64
  • NUMERIC
  • 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 le séparateur décimal 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 le séparateur décimal.

CAST AS STRING

CAST(expression AS STRING)

Description

Cloud Spanner SQL accepte le casting en STRING. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • INT64
  • FLOAT64
  • NUMERIC
  • BOOL
  • BYTES
  • DATE
  • TIMESTAMP
  • STRING

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.
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.
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 (America/Los_Angeles). 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.

Exemples

SELECT CAST(CURRENT_DATE() AS STRING) AS current_date

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

CAST AS STRUCT

CAST(expression AS STRUCT)

Description

Cloud Spanner SQL accepte le casting en 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 :
  1. Les deux STRUCT ont le même nombre de champs.
  2. 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 TIMESTAMP

CAST(expression AS TIMESTAMP)

Description

Cloud Spanner SQL accepte le casting en TIMESTAMP. Le paramètre expression peut représenter une expression pour les types de données suivants :

  • STRING
  • TIMESTAMP

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 America/Los_Angeles 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 (America/Los_Angeles).

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-03T00:00:53.11Z |
+-------------------------+

SAFE_CAST

SAFE_CAST(expression AS typename)

Description

En cas d'utilisation de CAST, une requête peut échouer si Cloud Spanner SQL 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
FROM_BASE32 CHAÎNE BYTES
FROM_BASE64 CHAÎNE BYTES
FROM_HEX CHAÎNE BYTES
PARSE_DATE CHAÎNE DATE
PARSE_TIMESTAMP CHAÎNE TIMESTAMP
SAFE_CONVERT_BYTES_TO_STRING BYTES CHAÎNE
STRING TIMESTAMP CHAÎNE
TIMESTAMP Différents types de données TIMESTAMP
TO_BASE32 BYTES CHAÎNE
TO_BASE64 BYTES CHAÎNE
TO_HEX BYTES CHAÎNE

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ÉEINT64NUMERICFLOAT64
RÉSULTATINT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATINT64NUMERICFLOAT64

IS_INF

IS_INF(X)

Description

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

Renvoie FALSE pour les entrées NUMERIC, car NUMERIC ne peut pas être INF.

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.

Renvoie FALSE pour les entrées NUMERIC, car NUMERIC ne peut pas être 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

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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. Si les deux entrées sont NUMERIC et que le résultat déborde, la fonction renvoie une erreur numeric overflow.

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ÉEINT64NUMERIC
INT64INT64NUMERIC
NUMERICNUMERICNUMERIC

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.

XOSAFE_DIVIDE(X, Y)
2045
0200
200NULL

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Description

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

XOSAFE_MULTIPLY(X, Y)
20480

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

SAFE_NEGATE

SAFE_NEGATE(X)

Description

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

XSAFE_NEGATE(X)
+1-1
-1+1
00

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
RÉSULTATINT64NUMERICFLOAT64

SAFE_ADD

SAFE_ADD(X, Y)

Description

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

XOSAFE_ADD(X, Y)
549

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

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.

XOSAFE_SUBTRACT(X, Y)
541

Type de données renvoyé

ENTRÉEINT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

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ÉEINT64NUMERIC
INT64INT64NUMERIC
NUMERICNUMERICNUMERIC

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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ÉEINT64NUMERICFLOAT64
RÉSULTATFLOAT64NUMERICFLOAT64

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
-inf NaN
NaN NaN

COSH

COSH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X COSH(X)
+inf +inf
-inf +inf
NaN NaN

ACOS

ACOS(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X ACOS(X)
+inf NaN
-inf NaN
NaN NaN
X < -1 Erreur
X > 1 Erreur

ACOSH

ACOSH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X ACOSH(X)
+inf +inf
-inf NaN
NaN NaN
X < 1 Erreur

SIN

SIN(X)

Description

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

X SIN(X)
+inf NaN
-inf NaN
NaN NaN

SINH

SINH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X SINH(X)
+inf +inf
-inf -inf
NaN NaN

ASIN

ASIN(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X ASIN(X)
+inf NaN
-inf NaN
NaN NaN
X < -1 Erreur
X > 1 Erreur

ASINH

ASINH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X ASINH(X)
+inf +inf
-inf -inf
NaN NaN

TAN

TAN(X)

Description

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

X TAN(X)
+inf NaN
-inf NaN
NaN NaN

TANH

TANH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X TANH(X)
+inf 1.0
-inf -1,0
NaN NaN

ATAN

ATAN(X)

Description

Calcule la valeur principale de la tangente inverse de X. La valeur renvoyée se situe dans la plage [-π/2, π/2]. Cette fonction n'échoue pas.

Si X est de type NUMERIC, le résultat est FLOAT64.

X ATAN(X)
+inf π/2
-inf -π/2
NaN NaN

ATANH

ATANH(X)

Description

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

Si X est de type NUMERIC, le résultat est FLOAT64.

X ATANH(X)
+inf NaN
-inf NaN
NaN NaN
X < -1 Erreur
X > 1 Erreur

ATAN2

ATAN2(X, Y)

Description

Calcule la valeur principale de la tangente inverse de Y/X en utilisant les signes des deux arguments pour déterminer le quadrant. La valeur renvoyée se situe dans la plage [-π,π].

Si X est de type NUMERIC, le résultat est FLOAT64.

X O ATAN2(X, Y)
NaN Toute valeur NaN
Toute valeur NaN NaN
0,0 0,0 0,0
Valeur finie positive -inf π
Valeur finie négative -inf
Valeur finie +inf 0,0
+inf Valeur finie π/2
-inf Valeur finie -π/2
+inf -inf ¾π
-inf -inf -¾π
+inf +inf π/4
-inf +inf -π/4

Fonctions de hachage

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

Description

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

Type renvoyé

INT64

Exemples

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

SHA1

SHA1(input)

Description

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

Cette fonction renvoie 20 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA1("Hello World") as sha1;

-- Note that the result of SHA1 is of type BYTES, displayed as a base64-encoded string.
+------------------------------+
| sha1                         |
+------------------------------+
| Ck1VqNd45QIvq3AZd8XYQLvEhtA= |
+------------------------------+

SHA256

SHA256(input)

Description

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

Cette fonction renvoie 32 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

Description

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

Cette fonction renvoie 64 octets.

Type renvoyé

BYTES

Exemple

SELECT SHA512("Hello World") as sha512;

Fonctions de chaîne

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

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

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

BYTE_LENGTH

BYTE_LENGTH(value)

Description

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

Type renvoyé

INT64

Exemples

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

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

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

CHAR_LENGTH

CHAR_LENGTH(value)

Description

Renvoie la longueur de la valeur STRING en caractères.

Type renvoyé

INT64

Exemples

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

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

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

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

Description

Synonyme de CHAR_LENGTH.

Type renvoyé

INT64

Exemples

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

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

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

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

Description

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

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

Type renvoyé

BYTES

Exemples

Voici un exemple de base utilisant CODE_POINTS_TO_BYTES.

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

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'AbCd' is the result.
+----------+
| bytes    |
+----------+
| QWJDZA== |
+----------+

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

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

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'Grfg Fgevat!' is the result.
+------------------+
| encoded_string   |
+------------------+
| R3JmZyBGZ2V2YXQh |
+------------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Description

Accepte en entrée un tableau de points de code Unicode (ARRAY de INT64) et renvoie une valeur STRING. Si la valeur d'un point de code est 0, il ne renvoie pas de caractère pour celui-ci dans STRING.

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

Type renvoyé

STRING

Exemples

Voici des exemples de base qui utilisent CODE_POINTS_TO_STRING.

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

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+
SELECT CODE_POINTS_TO_STRING([97, 0, 0xF9B5]) AS string;

+--------+
| string |
+--------+
| a例    |
+--------+
SELECT CODE_POINTS_TO_STRING([65, 255, NULL, 1024]) AS string;

+--------+
| string |
+--------+
| NULL   |
+--------+

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

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

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

CONCAT

CONCAT(value1[, ...])

Description

Concatène une ou plusieurs valeurs STRING ou BYTE dans un seul résultat.

La fonction renvoie NULL si l'un des arguments d'entrée est NULL.

Type renvoyé

STRING ou BYTES

Exemples

SELECT CONCAT("T.P.", " ", "Bar") as author;

+---------------------+
| author              |
+---------------------+
| T.P. Bar            |
+---------------------+

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

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

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

ENDS_WITH

ENDS_WITH(value1, value2)

Description

Prend deux valeurs STRING ou BYTES. Renvoie TRUE si la deuxième valeur est un suffixe de la première.

Type renvoyé

BOOL

Exemples

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

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

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

FORMAT

FORMAT(format_string_expression, data_type_expression[, ...])

Description

FORMAT formate une expression de type de données sous forme de chaîne.

  • format_string_expression: peut contenir zéro, un ou plusieurs spécificateurs de format. Chaque spécificateur de format est introduit par le symbole % et doit être mappé sur un ou plusieurs des arguments restants. En général, il s'agit d'un mappage de type "un à un", sauf lorsque le spécificateur * est présent. Par exemple, %.*i correspond à deux arguments : un argument de longueur et un argument de nombre entier signé. Si le nombre d'arguments liés aux spécificateurs de format n'est pas identique au nombre total d'arguments, une erreur se produit.
  • data_type_expression: valeur à mettre en forme en tant que chaîne. Il peut s'agir de n'importe quel type de données SQL Cloud Spanner.

Type renvoyé

STRING

Exemples

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

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

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

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

Renvoie

date: January 02, 2015!

Spécificateurs de format acceptés

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

Un indicateur de format ajoute une mise en forme lors de la conversion d'une valeur vers une chaîne. Il peut éventuellement contenir les sous-spécificateurs suivants:

Informations supplémentaires sur les spécificateurs de format:

Spécificateurs de format
Spécificateur Description Exemples Types
d ou i Entier décimal 392 INT64
o Octal 610
INT64*
x Entier hexadécimal 7fa
INT64*
X Entier hexadécimal (majuscule) 7FA
INT64*
f Notation décimale [-](partie entière).(partie fractionnaire) pour les valeurs finies. Minuscule pour les valeurs non finies. 392.650000
inf
nan
NUMERIC
FLOAT64
F Notation décimale [-](partie entière).(partie fractionnaire) pour les valeurs finies. Majuscule pour les valeurs non finies. 392.650000
INF
NAN
NUMERIC
FLOAT64
e Notation scientifique (mantisse/exposant), minuscule 3.926500e+02
inf
nan
NUMERIC
FLOAT64
E Notation scientifique (mantisse/exposant), majuscule 3.926500E+02
INF
NAN
NUMERIC
FLOAT64
g Notation décimale ou scientifique, en fonction de l'exposant de la valeur d'entrée et de la précision spécifiée. Minuscule. Consultez la section Comportement de %g et %G pour plus de détails. 392.65
3.9265e+07
inf
nan
NUMERIC
FLOAT64
G Notation décimale ou scientifique, en fonction de l'exposant de la valeur d'entrée et de la précision spécifiée. Majuscule. Consultez la section Comportement de %g et %G pour plus de détails. 392,65
3,9265E+07
INF
NAN
NUMERIC
FLOAT64
s Chaîne de caractères exemple STRING
t Renvoie une chaîne imprimable représentant la valeur. Ce résultat est souvent semblable à celui du casting de l'argument au format STRING. Consultez la section Comportement%t et %T. exemple
2014‐01‐01
<tous>
T Génère une chaîne qui est une constante Cloud Spanner SQL valide, dont le type est semblable à celui de la valeur. Il peut contenir plus de caractères ou se présenter sous forme de chaîne. Consultez la section Comportement%t et %T. 'sample'
b'bytes sample'
1234
2.3
date "2014‐01‐01"
<tous>
% '%%' produit un seul '%' % n/a

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

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

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

Options
Options Description
- Justifie à gauche dans la largeur de champ donnée ; la justification à droite est la valeur par défaut (consultez la rubrique relative aux sous-spécificateurs de largeur).
+ Force l'ajout d'un préfixe "plus" ou "moins" (signe + ou -) avant le résultat, même pour les nombres positifs. Par défaut, seuls les nombres négatifs sont précédés d'un signe -.
<espace> Si aucun signe ne doit être écrit par la suite, un espace est inséré avant la valeur
#
  • Pour "%o", "%x" et "%X", cette option ajoute respectivement le préfixe 0, 0x ou 0X avant la valeur lorsqu'elle est différente de zéro.
  • Pour "%f", "%F", "%e" et "%E", cette option ajoute le point décimal même s'il n'y a pas de partie fractionnaire (sauf dans le cas d'une valeur non finie).
  • Pour "%g" et "%G", cette option ajoute le point décimal même s'il n'y a pas de partie fractionnaire (sauf dans le cas d'une valeur non finie), et ne supprime jamais les zéros de fin après le point décimal.
0 Ajoute des zéros (0) au lieu d'espaces à gauche du nombre lorsque l'option de remplissage est spécifiée (consultez la rubrique relative aux sous-spécificateurs de largeur).
'

Formate les entiers en utilisant le caractère de regroupement approprié. Par exemple :

  • FORMAT("%'d", 12345678) renvoie 12,345,678
  • FORMAT("%'x", 12345678) renvoie bc:614e
  • FORMAT("%'o", 55555) renvoie 15,4403
  • Cet indicateur ne concerne que les valeurs décimales, hexadécimales et octales.

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

Largeur
Largeur Description
<nombre> Nombre minimum de caractères à imprimer. Si la valeur à imprimer ne contient pas le nombre minimum de caractères requis, le résultat est complété par des espaces. La valeur n'est pas tronquée, même si le résultat contient plus de caractères.
* La largeur n'est pas spécifiée dans la chaîne de format, mais en tant qu'argument de valeur entière supplémentaire précédant l'argument à formater.
Précision
Précision Description
.<nombre>
  • Pour les spécificateurs d'entiers "%d", "%i", "%o", "%u", "%x" et "%X", la précision indique le nombre minimal de chiffres à écrire. Si la valeur à écrire comporte moins de chiffres, des zéros sont ajoutés à la fin du résultat. La valeur n'est pas tronquée, même si le résultat contient plus de chiffres. Avec une précision de 0, aucun caractère n'est écrit pour la valeur 0.
  • Pour les spécificateurs "%a", "%A", "%e", "%E", "%f" et "%F", la précision indique le nombre de chiffres à écrire après le point décimal. La valeur par défaut est 6.
  • Pour les spécificateurs "%g" et "%G", la précision indique le nombre de chiffres significatifs à écrire, avant que les zéros de fin après le point décimal ne soient supprimés. La valeur par défaut est 6.
.* La précision n'est pas spécifiée dans la chaîne de format, mais en tant qu'argument de valeur entière supplémentaire précédant l'argument à formater.
Comportement de %g et %G

Les spécificateurs de format %g et %G adoptent la notation décimale (comme les spécificateurs %f et %F) ou la notation scientifique (comme les spécificateurs %e et %E), en fonction de l'exposant de la valeur d'entrée et de la précision spécifiée.

Soit p la précision spécifiée (6 par défaut ; 1 si la précision spécifiée est inférieure à 1). La valeur d'entrée est d'abord convertie en notation scientifique avec la précision (p - 1). Si l'exposant x obtenu est inférieur à -4 ou supérieur ou égal à p, c'est la notation scientifique avec la précision (p - 1) qui est retenue. Dans les autres cas, c'est la notation décimale avec la précision (p - 1 - x) qui est utilisée.

À moins que l'option # ne soit spécifiée, les zéros de fin après le point décimal sont supprimés, et le point décimal est également supprimé si aucun chiffre ne figure après.

Comportement de %t et %T

Les spécificateurs de format %t et %T sont définis pour tous les types. La largeur, la précision et les options se comportent comme pour le spécificateur %s : la largeur correspond à la taille minimale, et la chaîne STRING est complétée pour atteindre cette taille ; la précision est la taille maximale du contenu à afficher, et la chaîne STRING est tronquée pour lui donner cette taille avant l'application du remplissage nécessaire pour atteindre la largeur spécifiée.

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

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

La STRING est formatée comme suit :

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

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

FORMAT('%s', 1)
FORMAT('%')
Gérer des arguments NULL

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

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

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

FORMAT('00-%t-00', NULL_expression);

Renvoie

00-NULL-00
Règles sémantiques supplémentaires

Les valeurs FLOAT64 peuvent être +/-inf ou NaN. Lorsqu'un argument comporte l'une de ces valeurs, le résultat des spécificateurs de format %f, %F, %e, %E, %g, %G et %t est inf, -inf ou nan (ou le même terme en majuscules) selon le cas. Ceci est cohérent avec la manière dont Cloud Spanner SQL convertit (par casting) ces valeurs en STRING. Pour %T, Cloud Spanner SQL renvoie des chaînes entre guillemets pour les valeurs FLOAT64 n'ayant pas de représentations littérales de chaîne.

FROM_BASE32

FROM_BASE32(string_expr)

Description

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

Type renvoyé

BYTES

Exemple

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

-- Note that the result of FROM_BASE32 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| YWJjZGX/  |
+-----------+

FROM_BASE64

FROM_BASE64(string_expr)

Description

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

Il existe plusieurs encodages en base64 d'usage courant qui varient selon l'alphabet de 65 caractères ASCII utilisé pour encoder les 64 chiffres et le remplissage. Pour en savoir plus, consultez la norme RFC 4648. Cette fonction attend l'alphabet [A-Za-z0-9+/=].

Type renvoyé

BYTES

Exemple

SELECT FROM_BASE64('/+A=') AS byte_data;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| /+A=      |
+-----------+

Pour travailler avec un encodage utilisant un autre alphabet en base64, vous devrez peut-être composer FROM_BASE64 avec la fonction REPLACE. Par exemple, l'encodage base64url sécurisé pour les URL et le nom de fichier couramment utilisé dans la programmation Web utilise -_= comme derniers caractères plutôt que +/=. Pour décoder une chaîne encodée en base64url, remplacez + et / par - et _, respectivement.

SELECT FROM_BASE64(REPLACE(REPLACE("_-A=", "-", "+"), "_", "/")) AS binary;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+--------+
| binary |
+--------+
| /+A=   |
+--------+

FROM_HEX

FROM_HEX(string)

Description

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

Type renvoyé

BYTES

Exemple

WITH Input AS (
  SELECT '00010203aaeeefff' AS hex_str UNION ALL
  SELECT '0AF' UNION ALL
  SELECT '666f6f626172'
)
SELECT hex_str, FROM_HEX(hex_str) AS bytes_str
FROM Input;

-- Note that the result of FROM_HEX is of type BYTES, displayed as a base64-encoded string.
+------------------+--------------+
| hex_str          | bytes_str    |
+------------------+--------------+
| 0AF              | AAECA6ru7/8= |
| 00010203aaeeefff | AK8=         |
| 666f6f626172     | Zm9vYmFy     |
+------------------+--------------+

LENGTH

LENGTH(value)

Description

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

Type renvoyé

INT64

Exemples


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

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

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

LPAD

LPAD(original_value, return_length[, pattern])

Description

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

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

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

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

Si original_value, return_length ou pattern est NULL, cette fonction renvoie NULL.

Cette fonction renvoie une erreur si :

  • return_length est une valeur négative ;
  • pattern est vide.

Type renvoyé

STRING ou BYTES

Exemples

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

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

+------+-----+---------+--------------+
| t    | len | pattern | LPAD         |
|------|-----|---------|--------------|
| abc  | 8   | def     | "defdeabc"   |
| abc  | 5   | -       | "--abc"      |
| 例子  | 5   | 中文    | "中文中例子"   |
+------+-----+---------+--------------+
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

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

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

LOWER

LOWER(value)

Description

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

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

Type renvoyé

STRING ou BYTES

Exemples


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

SELECT
  LOWER(item) AS example
FROM items;

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

LTRIM

LTRIM(value1[, value2])

Description

Identique à TRIM, mais ne supprime que les caractères de début.

Type renvoyé

STRING ou BYTES

Exemples

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

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

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+
WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

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

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+
WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)
SELECT
  LTRIM(item, "xyz") as example
FROM items;

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

NORMALIZE

NORMALIZE(value[, normalization_mode])

Description

Accepte en entrée une valeur de type valeur de chaîne et la renvoie sous forme de chaîne normalisée. Si vous ne fournissez pas de mode de normalisation, NFC est utilisé.

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

NORMALIZE accepte quatre modes de normalisation facultatifs.

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

Type renvoyé

STRING

Exemples

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

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

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

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

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

NORMALIZE_AND_CASEFOLD

NORMALIZE_AND_CASEFOLD(value[, normalization_mode])

Description

Accepte en entrée une valeur de type valeur de chaîne et la renvoie sous forme de chaîne normalisée avec normalisation.

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

Le pliage de casse permet de comparer des chaînes sans casse. Si vous devez comparer des chaînes et que la casse ne doit pas être prise en compte, utilisez NORMALIZE_AND_CASEFOLD. Sinon, utilisez NORMALIZE.

NORMALIZE_AND_CASEFOLD accepte quatre modes de normalisation facultatifs.

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

Type renvoyé

STRING

Exemples

SELECT
  a, b,
  NORMALIZE(a) = NORMALIZE(b) as normalized,
  NORMALIZE_AND_CASEFOLD(a) = NORMALIZE_AND_CASEFOLD(b) as normalized_with_case_folding
FROM (SELECT 'The red barn' AS a, 'The Red Barn' AS b);

+--------------+--------------+------------+------------------------------+
| a            | b            | normalized | normalized_with_case_folding |
+--------------+--------------+------------+------------------------------+
| The red barn | The Red Barn | false      | true                         |
+--------------+--------------+------------+------------------------------+
WITH Strings AS (
  SELECT '\u2168' AS a, 'IX' AS b UNION ALL
  SELECT '\u0041\u030A', '\u00C5'
)
SELECT a, b,
  NORMALIZE_AND_CASEFOLD(a, NFD)=NORMALIZE_AND_CASEFOLD(b, NFD) AS nfd,
  NORMALIZE_AND_CASEFOLD(a, NFC)=NORMALIZE_AND_CASEFOLD(b, NFC) AS nfc,
  NORMALIZE_AND_CASEFOLD(a, NFKD)=NORMALIZE_AND_CASEFOLD(b, NFKD) AS nkfd,
  NORMALIZE_AND_CASEFOLD(a, NFKC)=NORMALIZE_AND_CASEFOLD(b, NFKC) AS nkfc
FROM Strings;

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

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regexp)

Description

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

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

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

Type renvoyé

BOOL

Exemples

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

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| foo@example.com | true     |
| bar@example.org | true     |
| www.example.net | false    |
+-----------------+----------+

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

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| a@foo.com      | true                | true                |
| a@foo.computer | false               | true                |
| b@bar.org      | true                | true                |
| !b@bar.org     | false               | true                |
| c@buz.net      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regexp)

Description

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

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

Renvoie une erreur si :

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

Type renvoyé

STRING ou BYTES

Exemples

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

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

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+
WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

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

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

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regexp)

Description

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

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

Type renvoyé

ARRAY de type STRING ou BYTES

Exemples

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

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

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

REGEXP_REPLACE

REGEXP_REPLACE(value, regexp, replacement)

Description

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

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

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

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

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

REPLACE

REPLACE(original_value, from_value, to_value)

Description

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

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

REPEAT

REPEAT(original_value, repetitions)

Description

Renvoie une valeur STRING ou BYTES constituée de l'élément original_value, ainsi que d'une ou de plusieurs répétitions de celui-ci. Le paramètre repetitions indique le nombre de répétitions de la valeur original_value. Renvoie NULL si original_value ou repetitions est NULL.

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

Type renvoyé

STRING ou BYTES

Exemples

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

+------+------+-----------+
| t    | n    | REPEAT    |
|------|------|-----------|
| abc  | 3    | abcabcabc |
| 例子 | 2    | 例子例子  |
| abc  | NULL | NULL      |
| NULL | 3    | NULL      |
+------+------+-----------+

REVERSE

REVERSE(value)

Description

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

RPAD

RPAD(original_value, return_length[, pattern])

Description

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

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

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

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

Si original_value, return_length ou pattern est NULL, cette fonction renvoie NULL.

Cette fonction renvoie une erreur si :

  • return_length est une valeur négative ;
  • pattern est vide.

Type renvoyé

STRING ou BYTES

Exemples

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

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

+------+-----+---------+--------------+
| t    | len | pattern | RPAD         |
|------|-----|---------|--------------|
| abc  | 8   | def     | "abcdefde"   |
| abc  | 5   | -       | "abc--"      |
| 例子  | 5   | 中文     | "例子中文中"  |
+------+-----+---------+--------------+
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

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

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

RTRIM

RTRIM(value1[, value2])

Description

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+
WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

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

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

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

Description

Convertit une séquence de BYTES en STRING. Tous les caractères UTF-8 non valides sont remplacés par le caractère de remplacement Unicode U+FFFD.

Type renvoyé

STRING

Exemples

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

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

SPLIT

SPLIT(value[, delimiter])

Description

Répartit value à l'aide de l'argument delimiter.

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

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

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

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

Type renvoyé

ARRAY de type STRING ou ARRAY de type BYTES

Exemples

WITH letters AS
  (SELECT "" as letter_group
  UNION ALL
  SELECT "a" as letter_group
  UNION ALL
  SELECT "b c d" as letter_group)

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

+----------------------+
| example              |
+----------------------+
| []                   |
| [a]                  |
| [b, c, d]            |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

Description

Prend deux valeurs STRING ou BYTES. Renvoie TRUE si la deuxième valeur est un préfixe de la première.

Type renvoyé

BOOL

Exemples

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

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

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

STRPOS

STRPOS(value1, value2)

Description

Prend deux valeurs STRING ou BYTES. Renvoie l'index en base 1 de la première occurrence de value2 dans value1. Renvoie 0 si value2 est introuvable.

Type renvoyé

INT64

Exemples

WITH email_addresses AS
  (SELECT
    "foo@example.com" AS email_address
  UNION ALL
  SELECT
    "foobar@example.com" AS email_address
  UNION ALL
  SELECT
    "foobarbaz@example.com" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

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

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

SUBSTR

SUBSTR(value, position[, length])

Description

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

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

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

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+
WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

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

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+
WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

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

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

TO_BASE32

TO_BASE32(bytes_expr)

Description

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

Type renvoyé

STRING

Exemple

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

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

TO_BASE64

TO_BASE64(bytes_expr)

Description

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

Il existe plusieurs encodages en base64 d'usage courant qui varient selon l'alphabet de 65 caractères ASCII utilisé pour encoder les 64 chiffres et le remplissage. Pour en savoir plus, consultez la norme RFC 4648. Cette fonction ajoute un remplissage et utilise l'alphabet [A-Za-z0-9+/=].

Type renvoyé

STRING

Exemple

SELECT TO_BASE64(b'\377\340') AS base64_string;

+---------------+
| base64_string |
+---------------+
| /+A=          |
+---------------+

Pour travailler avec un encodage utilisant un autre alphabet en base64, vous devrez peut-être composer TO_BASE64 avec la fonction REPLACE. Par exemple, l'encodage base64url sécurisé pour les URL et le nom de fichier couramment utilisé dans la programmation Web utilise -_= comme derniers caractères plutôt que +/=. Pour encoder une chaîne encodée en base64url, remplacez - et _ par + et /, respectivement.

SELECT REPLACE(REPLACE(TO_BASE64(b"\377\340"), "+", "-"), "/", "_") as websafe_base64;

+----------------+
| websafe_base64 |
+----------------+
| _-A=           |
+----------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Description

Prend une valeur et renvoie un tableau de INT64.

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

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

Type renvoyé

ARRAY sur INT64

Exemples

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

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

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

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

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

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

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

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

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

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

TO_HEX

TO_HEX(bytes)

Description

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

Type renvoyé

STRING

Exemple

WITH Input AS (
  SELECT b'\x00\x01\x02\x03\xAA\xEE\xEF\xFF' AS byte_str UNION ALL
  SELECT b'foobar'
)
SELECT byte_str, TO_HEX(byte_str) AS hex_str
FROM Input;

+----------------------------------+------------------+
| byte_string                      | hex_string       |
+----------------------------------+------------------+
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
| foobar                           | 666f6f626172     |
+----------------------------------+------------------+

TRIM

TRIM(value1[, value2])

Description

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

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

Type renvoyé

STRING ou BYTES

Exemples

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

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

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+
WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

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

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+
WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

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

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

UPPER

UPPER(value)

Description

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

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

Type renvoyé

STRING ou BYTES

Exemples

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

SELECT
  UPPER(item) AS example
FROM items;

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

Fonctions JSON

Le langage SQL de Cloud Spanner accepte les fonctions suivantes, qui peuvent récupérer et transformer des données JSON.

Présentation de la fonction

Les fonctions suivantes utilisent des guillemets doubles pour échapper les caractères JSONPath non valides : "a.b".

Ce comportement est conforme à la norme ANSI.

Fonction JSON Description Type renvoyé
JSON_QUERY Extrait une valeur JSON, telle qu'un tableau ou un objet, ou une valeur scalaire JSON, telle qu'une chaîne, un entier ou un booléen. STRING au format JSON
JSON_VALUE Extrait une valeur scalaire. Une valeur scalaire peut représenter une chaîne, un entier ou une valeur booléenne. Supprime les guillemets les plus externes et l'échappement des valeurs. Renvoie un résultat SQL NULL si une valeur non scalaire est sélectionnée. STRING

JSON_QUERY

JSON_QUERY(json_string_expr, json_path)

Description

Extrait une valeur JSON, telle qu'un tableau ou un objet, ou une valeur scalaire JSON, telle qu'une chaîne, un entier ou un booléen. Si une clé JSON utilise des caractères JSONPath non valides, vous pouvez les échapper à l'aide de guillemets doubles.

  • json_string_expr : chaîne au format JSON. Exemple :

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

    Extrait une valeur NULL SQL lorsqu'une chaîne "null" est trouvée au format JSON. Exemple :

    SELECT JSON_QUERY("null", "$") -- Returns a SQL NULL
    
  • json_path : format JSONPath. Identifie la ou les valeurs que vous souhaitez obtenir à partir de la chaîne au format JSON.

    SELECT JSON_QUERY('{"a":null}', "$.a"); -- Returns a SQL NULL
    SELECT JSON_QUERY('{"a":null}', "$.b"); -- Returns a SQL NULL
    

Si vous souhaitez inclure des valeurs non scalaires telles que des tableaux dans l'extraction, utilisez JSON_QUERY. Si vous ne souhaitez extraire que des valeurs scalaires telles que des chaînes, des entiers et des valeurs booléennes, utilisez JSON_VALUE.

Type renvoyé

STRING au format JSON

Exemples

Dans les exemples suivants, les données JSON sont extraites et renvoyées sous forme de chaînes au format JSON.

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

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

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+
SELECT JSON_QUERY(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name" : null}]}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| NULL              |
| "Jamie"           |
+-------------------+
SELECT JSON_QUERY(json_text, '$.class."students"') AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

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

JSON_VALUE

JSON_VALUE(json_string_expr[, json_path])

Description

Extrait une valeur scalaire, puis la renvoie sous forme de chaîne. Une valeur scalaire peut représenter une chaîne, un entier ou une valeur booléenne. Supprime les guillemets les plus externes et l'échappement des valeurs renvoyées. Si une clé JSON utilise des caractères JSONPath non valides, vous pouvez les échapper à l'aide de guillemets doubles.

  • json_string_expr : chaîne au format JSON. Exemple :

    '{"class" : {"students" : [{"name" : "Jane"}]}}'
    
  • json_path : format JSONPath. Identifie la ou les valeurs que vous souhaitez obtenir à partir de la chaîne au format JSON. Si json_path renvoie un résultat JSON null ou une valeur non scalaire (en d'autres termes, si json_path fait référence à un objet ou à un tableau), un résultat SQL NULL est renvoyé. Si ce paramètre facultatif n'est pas renseigné, le symbole JSONPath $ est appliqué, ce qui signifie que l'intégralité de la chaîne au format JSON est analysée.

Si vous ne souhaitez extraire que des valeurs scalaires telles que des chaînes, des entiers et des valeurs booléennes, utilisez JSON_VALUE. Si vous souhaitez inclure des valeurs non scalaires telles que des tableaux dans l'extraction, utilisez JSON_QUERY.

Type renvoyé

STRING

Exemples

L'exemple suivant compare le mode d'envoi des résultats des fonctions JSON_QUERY et JSON_VALUE.

SELECT JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.name') AS json_name,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.name') AS scalar_name,
  JSON_QUERY('{ "name" : "Jakob", "age" : "6" }', '$.age') AS json_age,
  JSON_VALUE('{ "name" : "Jakob", "age" : "6" }', '$.age') AS scalar_age;

+-----------+-------------+----------+------------+
| json_name | scalar_name | json_age | scalar_age |
+-----------+-------------+----------+------------+
| "Jakob"   | Jakob       | "6"      | 6          |
+-----------+-------------+----------+------------+
SELECT JSON_QUERY('{"fruits": ["apple", "banana"]}', '$.fruits') AS json_query,
  JSON_VALUE('{"fruits": ["apple", "banana"]}', '$.fruits') AS json_value;

+--------------------+------------+
| json_query         | json_value |
+--------------------+------------+
| ["apple","banana"] | NULL       |
+--------------------+------------+

Dans les cas où une clé JSON utilise des caractères JSONPath non valides, vous pouvez les échapper à l'aide de guillemets doubles. Exemple :

SELECT JSON_VALUE('{"a.b": {"c": "world"}}', '$."a.b".c') AS hello;

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

JSONPath

La plupart des fonctions JSON sont transmises dans un paramètre json_string_expr et un paramètre json_path. Le paramètre json_string_expr transmet une chaîne au format JSON, et le paramètre json_path identifie la ou les valeurs que vous souhaitez obtenir de la chaîne au format JSON.

Le paramètre json_string_expr doit être une chaîne JSON dont le format est le suivant :

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

Vous construisez le paramètre json_path en utilisant le format JSONPath. Selon les règles applicables à ce format, ce paramètre doit commencer par un symbole $, qui fait référence au niveau le plus externe (le plus haut niveau) de la chaîne au format JSON. Vous pouvez identifier les valeurs enfants à l'aide de points. Si l'objet JSON est un tableau, vous pouvez utiliser des crochets pour spécifier l'index de tableau. Si les clés contiennent $, des points ou des crochets, reportez-vous à chaque fonction JSON pour savoir comment les échapper.

JSONPath Description Exemple Résultat utilisant le code json_string_expr ci-dessus
$ Objet ou élément racine "$" {"class":{"students":[{"name":"Jane"}]}}
. Opérateur enfant "$.class.students" [{"name":"Jane"}]
[] Opérateur indice "$.class.students[0]" {"name":"Jane"}

Une fonction JSON renvoie NULL si le paramètre json_path ne correspond pas à une valeur dans json_string_expr. Si la valeur sélectionnée pour une fonction scalaire n'est pas scalaire, telle qu'un objet ou un tableau, la fonction renvoie NULL.

Si le format JSONPath n'est pas valide, la fonction génère une erreur.

Fonctions de tableau

ARRAY

ARRAY(subquery)

Description

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

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

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

Contraintes

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

Type renvoyé

ARRAY

Exemples

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

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

Pour construire un ARRAY à partir d'une sous-requête contenant plusieurs colonnes, modifiez la sous-requête pour qu'elle utilise SELECT AS STRUCT. La fonction ARRAY renvoie alors un ARRAY d'objets STRUCT. L'ARRAY contiendra une STRUCT pour chaque ligne de la sous-requête, et chacune de ces STRUCT contiendra un champ pour chaque colonne de cette ligne.

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

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

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

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

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

ARRAY_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

Description

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

Type renvoyé

ARRAY

Exemples

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

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

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Description

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

Type renvoyé

INT64

Exemples

WITH items AS
  (SELECT ["coffee", NULL, "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)
SELECT ARRAY_TO_STRING(list, ', ', 'NULL'), ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

+---------------------------------+------+
| list                            | size |
+---------------------------------+------+
| [coffee, NULL, milk]            | 3    |
| [cake, pie]                     | 2    |
+---------------------------------+------+

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

Description

Renvoie une concaténation des éléments de array_expression sous forme de chaîne (STRING). La valeur de array_expression peut être un tableau contenant des types de données STRING ou BYTES.

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

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

Exemples

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

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

+--------------------------------+
| text                           |
+--------------------------------+
| coffee--tea--milk              |
| cake--pie                      |
+--------------------------------+
WITH items AS
  (SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

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

+--------------------------------+
| text                           |
+--------------------------------+
| coffee--tea--milk              |
| cake--pie--MISSING             |
+--------------------------------+

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

Description

Renvoie un tableau de valeurs. Les paramètres start_expression et end_expression déterminent les valeurs de début et de fin inclusives du tableau.

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

  • INT64
  • NUMERIC
  • FLOAT64

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

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

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

Type de données renvoyé

ARRAY

Exemples

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

SELECT GENERATE_ARRAY(1, 5) AS example_array;

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

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

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

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

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

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

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

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

SELECT GENERATE_ARRAY(4, 4, 10) AS example_array;

+---------------+
| example_array |
+---------------+
| [4]           |
+---------------+

La requête suivante renvoie un tableau vide, étant donné que la valeur de start_expression est supérieure à celle de end_expression et que la valeur de step_expression est positive.

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

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

La requête suivante renvoie un tableau NULL, car la valeur de end_expression est NULL.

SELECT GENERATE_ARRAY(5, NULL, 1) AS example_array;

+---------------+
| example_array |
+---------------+
| NULL          |
+---------------+

La requête suivante renvoie plusieurs tableaux.

SELECT GENERATE_ARRAY(start, 5) AS example_array
FROM UNNEST([3, 4, 5]) AS start;

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

GENERATE_DATE_ARRAY

GENERATE_DATE_ARRAY(start_date, end_date[, INTERVAL INT64_expr date_part])

Description

Renvoie un tableau de dates. Les paramètres start_date et end_date déterminent les valeurs de début et de fin inclusives du tableau.

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

  • Le paramètre start_date doit être une DATE.
  • Le paramètre end_date doit être une DATE.
  • Le paramètre INT64_expr doit être de type INT64.
  • Le paramètre date_part doit être DAY (jour), WEEK (semaine), MONTH (mois), QUARTER (trimestre) ou YEAR (année).

Le paramètre INT64_expr détermine l'incrément utilisé pour générer les dates. La valeur par défaut pour ce paramètre est "1 jour".

Cette fonction renvoie une erreur si INT64_expr est défini sur 0.

Type de données renvoyé

Un tableau (ARRAY) contenant 0 ou plusieurs valeurs de type DATE.

Exemples

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

SELECT GENERATE_DATE_ARRAY('2016-10-05', '2016-10-08') AS example;

+--------------------------------------------------+
| example                                          |
+--------------------------------------------------+
| [2016-10-05, 2016-10-06, 2016-10-07, 2016-10-08] |
+--------------------------------------------------+

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

SELECT GENERATE_DATE_ARRAY(
 '2016-10-05', '2016-10-09', INTERVAL 2 DAY) AS example;

+--------------------------------------+
| example                              |
+--------------------------------------+
| [2016-10-05, 2016-10-07, 2016-10-09] |
+--------------------------------------+

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

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL -3 DAY) AS example;

+--------------------------+
| example                  |
+--------------------------+
| [2016-10-05, 2016-10-02] |
+--------------------------+

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

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-05', INTERVAL 8 DAY) AS example;

+--------------+
| example      |
+--------------+
| [2016-10-05] |
+--------------+

La requête suivante renvoie un tableau vide, étant donné que la valeur de start_date est supérieure à celle de end_date et que la valeur de step est positive.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

La requête suivante renvoie un tableau NULL, car l'une de ses entrées est NULL.

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

La requête suivante renvoie un tableau de dates utilisant la valeur MONTH (mois) comme intervalle date_part :

SELECT GENERATE_DATE_ARRAY('2016-01-01',
  '2016-12-31', INTERVAL 2 MONTH) AS example;

+--------------------------------------------------------------------------+
| example                                                                  |
+--------------------------------------------------------------------------+
| [2016-01-01, 2016-03-01, 2016-05-01, 2016-07-01, 2016-09-01, 2016-11-01] |
+--------------------------------------------------------------------------+

La requête suivante utilise des dates non constantes pour générer un tableau.

SELECT GENERATE_DATE_ARRAY(date_start, date_end, INTERVAL 1 WEEK) AS date_range
FROM (
  SELECT DATE '2016-01-01' AS date_start, DATE '2016-01-31' AS date_end
  UNION ALL SELECT DATE "2016-04-01", DATE "2016-04-30"
  UNION ALL SELECT DATE "2016-07-01", DATE "2016-07-31"
  UNION ALL SELECT DATE "2016-10-01", DATE "2016-10-31"
) AS items;

+--------------------------------------------------------------+
| date_range                                                   |
+--------------------------------------------------------------+
| [2016-01-01, 2016-01-08, 2016-01-15, 2016-01-22, 2016-01-29] |
| [2016-04-01, 2016-04-08, 2016-04-15, 2016-04-22, 2016-04-29] |
| [2016-07-01, 2016-07-08, 2016-07-15, 2016-07-22, 2016-07-29] |
| [2016-10-01, 2016-10-08, 2016-10-15, 2016-10-22, 2016-10-29] |
+--------------------------------------------------------------+

OFFSET et ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

Description

Accède à un élément ARRAY par position et renvoie l'élément. OFFSET signifie que la numérotation commence à zéro, ORDINAL signifie que la numérotation commence à un.

Un tableau donné peut être interprété comme étant en base 0 ou en base 1. Lorsque vous accédez à un élément de tableau, vous devez faire précéder la position du tableau par OFFSET ou ORDINAL selon le cas : aucun comportement n'est défini par défaut.

Les fonctions OFFSET et ORDINAL génèrent toutes deux une erreur si l'index est en dehors de la plage.

Type renvoyé

Varie en fonction des éléments du tableau (ARRAY).

Exemples

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

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM items;

+----------------------------------+-----------+-----------+
| list                             | offset_1  | ordinal_1 |
+----------------------------------+-----------+-----------+
| [apples, bananas, pears, grapes] | bananas   | apples    |
| [coffee, tea, milk]              | tea       | coffee    |
| [cake, pie]                      | pie       | cake      |
+----------------------------------+-----------+-----------+

ARRAY_REVERSE

ARRAY_REVERSE(value)

Description

Renvoie le tableau d'entrée, mais en présentant les éléments dans l'ordre inverse.

Type renvoyé

ARRAY

Exemples

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [4, 5] AS arr UNION ALL
  SELECT [] AS arr
)
SELECT
  arr,
  ARRAY_REVERSE(arr) AS reverse_arr
FROM example;

+-----------+-------------+
| arr       | reverse_arr |
+-----------+-------------+
| [1, 2, 3] | [3, 2, 1]   |
| [4, 5]    | [5, 4]      |
| []        | []          |
+-----------+-------------+

ARRAY_IS_DISTINCT

ARRAY_IS_DISTINCT(value)

Description

Renvoie la valeur "true" si le tableau ne contient aucun élément répété, en utilisant la même logique de comparaison d'égalité que SELECT DISTINCT.

Type renvoyé

BOOL

Exemples

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [1, 1, 1] AS arr UNION ALL
  SELECT [1, 2, NULL] AS arr UNION ALL
  SELECT [1, 1, NULL] AS arr UNION ALL
  SELECT [1, NULL, NULL] AS arr UNION ALL
  SELECT [] AS arr UNION ALL
  SELECT CAST(NULL AS ARRAY<INT64>) AS arr
)
SELECT
  arr,
  ARRAY_IS_DISTINCT(arr) as is_distinct
FROM example;

+-----------------+-------------+
| arr             | is_distinct |
+-----------------+-------------+
| [1, 2, 3]       | true        |
| [1, 1, 1]       | false       |
| [1, 2, NULL]    | true        |
| [1, 1, NULL]    | false       |
| [1, NULL, NULL] | false       |
| []              | true        |
| NULL            | NULL        |
+-----------------+-------------+

SAFE_OFFSET et SAFE_ORDINAL

array_expression[SAFE_OFFSET(zero_based_offset)]
array_expression[SAFE_ORDINAL(one_based_offset)]

Description

Identiques à OFFSET et à ORDINAL, sauf qu'elles renvoient NULL si l'index est en dehors de la plage.

Type renvoyé

Varient en fonction des éléments du tableau (ARRAY).

Exemple

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

SELECT list,
  list[SAFE_OFFSET(3)] as safe_offset_3,
  list[SAFE_ORDINAL(3)] as safe_ordinal_3
FROM items;

+----------------------------------+---------------+----------------+
| list                             | safe_offset_3 | safe_ordinal_3 |
+----------------------------------+---------------+----------------+
| [apples, bananas, pears, grapes] | grapes        | pears          |
| [coffee, tea, milk]              | NULL          | milk           |
| [cake, pie]                      | NULL          | NULL           |
+----------------------------------+---------------+----------------+

Fonctions de date

Cloud Spanner SQL accepte les fonctions DATE suivantes :

CURRENT_DATE

CURRENT_DATE([time_zone])

Description

Renvoie la date actuelle pour le fuseau horaire spécifié ou celui par défaut. Les parenthèses sont facultatives lorsqu'elles sont appelées sans argument.

Cette fonction accepte un paramètre time_zone facultatif. Ce paramètre est une chaîne représentant le fuseau horaire à utiliser. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (America/Los_Angeles) est utilisé. Consultez la rubrique Définition de fuseaux horaires pour plus d'informations sur la spécification d'un fuseau horaire.

Si l'évaluation du paramètre time_zone est NULL, cette fonction renvoie NULL.

Type de données renvoyé

DATE

Exemple

SELECT CURRENT_DATE() AS the_date;

+--------------+
| the_date     |
+--------------+
| 2016-12-25   |
+--------------+

Lorsqu'une colonne nommée current_date est présente, le nom de la colonne et l'appel de fonction sans parenthèses sont ambigus. Pour garantir l'appel de fonction, ajoutez des parenthèses. Pour garantir le nom de la colonne, qualifiez-la avec sa variable de plage. Par exemple, la requête suivante sélectionne la fonction dans la colonne the_date et la colonne de table dans la colonne current_date.

WITH t AS (SELECT 'column value' AS `current_date`)
SELECT current_date() AS the_date, t.current_date FROM t;

+------------+--------------+
| the_date   | current_date |
+------------+--------------+
| 2016-12-25 | column value |
+------------+--------------+

EXTRACT

EXTRACT(part FROM date_expression)

Description

Renvoie la valeur correspondant à la partie de la date spécifiée. Le paramètre part doit correspondre à l'une des valeurs suivantes :

  • DAYOFWEEK : renvoie des valeurs comprises dans la plage [1,7], le dimanche étant considéré comme le premier jour de la semaine.
  • DAY
  • DAYOFYEAR
  • WEEK : renvoie le numéro de semaine de la date (compris dans la plage [0, 53]). Les semaines commencent le dimanche et les dates antérieures au premier dimanche de l'année correspondent à la semaine 0.
  • ISOWEEK : renvoie le numéro de semaine ISO 8601 de date_expression. Les ISOWEEK commencent le lundi. Les valeurs renvoyées sont comprises dans la plage [1, 53]. La première ISOWEEK de chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne.
  • MONTH
  • QUARTER : renvoie des valeurs comprises dans la plage [1,4].
  • YEAR
  • ISOYEAR : renvoie l'année à numérotation de semaine conforme à l'ISO 8601, qui correspond à l'année grégorienne contenant le jeudi de la semaine à laquelle date_expression appartient.

Type de données renvoyées

INT64

Exemples

Dans l'exemple suivant, EXTRACT renvoie une valeur correspondant à la partie de date DAY.

SELECT EXTRACT(DAY FROM DATE '2013-12-25') AS the_day;

+---------+
| the_day |
+---------+
| 25      |
+---------+

Dans l'exemple suivant, EXTRACT renvoie des valeurs correspondant à différents éléments de date d'une colonne de dates situées vers la fin de l'année.

SELECT
  date,
  EXTRACT(ISOYEAR FROM date) AS isoyear,
  EXTRACT(ISOWEEK FROM date) AS isoweek,
  EXTRACT(YEAR FROM date) AS year,
  EXTRACT(WEEK FROM date) AS week
FROM UNNEST(GENERATE_DATE_ARRAY('2015-12-23', '2016-01-09')) AS date
ORDER BY date;
+------------+---------+---------+------+------+
| date       | isoyear | isoweek | year | week |
+------------+---------+---------+------+------+
| 2015-12-23 | 2015    | 52      | 2015 | 51   |
| 2015-12-24 | 2015    | 52      | 2015 | 51   |
| 2015-12-25 | 2015    | 52      | 2015 | 51   |
| 2015-12-26 | 2015    | 52      | 2015 | 51   |
| 2015-12-27 | 2015    | 52      | 2015 | 52   |
| 2015-12-28 | 2015    | 53      | 2015 | 52   |
| 2015-12-29 | 2015    | 53      | 2015 | 52   |
| 2015-12-30 | 2015    | 53      | 2015 | 52   |
| 2015-12-31 | 2015    | 53      | 2015 | 52   |
| 2016-01-01 | 2015    | 53      | 2016 | 0    |
| 2016-01-02 | 2015    | 53      | 2016 | 0    |
| 2016-01-03 | 2015    | 53      | 2016 | 1    |
| 2016-01-04 | 2016    | 1       | 2016 | 1    |
| 2016-01-05 | 2016    | 1       | 2016 | 1    |
| 2016-01-06 | 2016    | 1       | 2016 | 1    |
| 2016-01-07 | 2016    | 1       | 2016 | 1    |
| 2016-01-08 | 2016    | 1       | 2016 | 1    |
| 2016-01-09 | 2016    | 1       | 2016 | 1    |
+------------+---------+---------+------+------+

DATE

1. DATE(year, month, day)
2. DATE(timestamp_expression[, timezone])

Description

  1. Construit une DATE à partir de valeurs INT64 représentant l'année, le mois et le jour.
  2. Extrait la DATE d'une expression TIMESTAMP. Cette étape accepte un paramètre facultatif permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (America/Los_Angeles) est utilisé.

Type de données renvoyé

DATE

Exemple

SELECT
  DATE(2016, 12, 25) AS date_ymd,
  DATE(TIMESTAMP "2016-12-25 05:30:00+07", "America/Los_Angeles") AS date_tstz;

+------------+------------+
| date_ymd   | date_tstz  |
+------------+------------+
| 2016-12-25 | 2016-12-24 |
+------------+------------+

DATE_ADD

DATE_ADD(date_expression, INTERVAL int64_expression date_part)

Description

Ajoute un intervalle de temps spécifié à une DATE.

La fonction DATE_ADD est compatible avec les valeurs date_part suivantes :

  • DAY
  • WEEK. Équivaut à sept jours (DAY).
  • MONTH
  • QUARTER
  • YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de la date d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyées

DATE

Exemple

SELECT DATE_ADD(DATE "2008-12-25", INTERVAL 5 DAY) AS five_days_later;

+--------------------+
| five_days_later    |
+--------------------+
| 2008-12-30         |
+--------------------+

DATE_SUB

DATE_SUB(date_expression, INTERVAL int64_expression date_part)

Description

Soustrait un intervalle de temps spécifié d'une DATE.

La fonction DATE_SUB est compatible avec les valeurs date_part suivantes :

  • DAY
  • WEEK. Équivaut à sept jours (DAY).
  • MONTH
  • QUARTER
  • YEAR

Une manipulation particulière est requise pour les parties MONTH (mois), QUARTER (trimestre) et YEAR (année) lorsque la date correspond au dernier jour du mois (ou à un jour très proche). Si le mois résultant ne comporte pas suffisamment de jours pour inclure le jour de la date d'origine, le jour renvoyé en résultat est le dernier jour du nouveau mois.

Type de données renvoyées

DATE

Exemple

SELECT DATE_SUB(DATE "2008-12-25", INTERVAL 5 DAY) AS five_days_ago;

+---------------+
| five_days_ago |
+---------------+
| 2008-12-20    |
+---------------+

DATE_DIFF

DATE_DIFF(date_expression_a, date_expression_b, date_part)

Description

Renvoie le nombre d'intervalles date_part entiers spécifiés entre deux objets DATE (date_expression_a – date_expression_b). Si la première DATE est antérieure à la seconde, la sortie est négative.

La fonction DATE_DIFF est compatible avec les valeurs date_part suivantes :

  • DAY
  • WEEK (cette partie de la date commence le dimanche).
  • ISOWEEK : utilise les limites de semaine ISO 8601. Les semaines ISO commencent le lundi.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR : utilise la limite d'année à numérotation de semaines ISO 8601. La limite d'année ISO est le lundi de la première semaine où le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyées

INT64

Exemple

SELECT DATE_DIFF(DATE '2010-07-07', DATE '2008-12-25', DAY) AS days_diff;

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+
SELECT
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', DAY) AS days_diff,
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', WEEK) AS weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

L'exemple ci-dessus montre le résultat de DATE_DIFF pour deux jours consécutifs. DATE_DIFF avec la partie de date WEEK renvoie 1, car DATE_DIFF compte le nombre de limites de partie de date dans cette plage de dates. Chaque WEEK commence le dimanche. Il existe donc une limite de partie de date entre le samedi (2017-10-14) et le dimanche (2017-10-15).

L'exemple suivant montre le résultat de DATE_DIFF pour deux dates avec des années différentes. La fonction DATE_DIFF avec la partie de date YEAR renvoie 3, car elle compte le nombre de limites de l'année civile grégorienne entre les deux dates. DATE_DIFF avec la partie de date ISOYEAR renvoie 2, car la seconde date appartient à l'année ISO 2015. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29.

SELECT
  DATE_DIFF('2017-12-30', '2014-12-30', YEAR) AS year_diff,
  DATE_DIFF('2017-12-30', '2014-12-30', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

L'exemple suivant montre le résultat de DATE_DIFF pour deux jours consécutifs. La première date tombe un lundi et la seconde un dimanche. DATE_DIFF avec la partie de date WEEK renvoie 0, car cette partie utilise des semaines commençant le dimanche. DATE_DIFF avec la partie de date ISOWEEK renvoie 1, car les semaines ISO commencent le lundi.

SELECT
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+--------------+
| week_diff | isoweek_diff |
+-----------+--------------+
| 0         | 1            |
+-----------+--------------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Description

Tronque la date selon le niveau de précision spécifié.

DATE_TRUNC est compatible avec les valeurs suivantes pour date_part :

  • DAY
  • WEEK
  • ISOWEEK : tronque date_expression à la limite de la semaine ISO 8601 précédente. Les semaines ISOWEEK commencent le lundi. La première ISOWEEK de chaque année ISO englobe le premier jeudi de l'année civile grégorienne correspondante. Toute date_expression précédente sera tronquée au lundi précédent.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR : tronque date_expression à la limite de l'année à numérotation de semaine ISO 8601 précédente. La limite d'année ISO est le lundi de la première semaine où le jeudi appartient à l'année civile grégorienne correspondante.

Type de données renvoyées

DATE

Exemples

SELECT DATE_TRUNC(DATE '2008-12-25', MONTH) AS month;

+------------+
| month      |
+------------+
| 2008-12-01 |
+------------+

Dans l'exemple suivant, le code d'origine date_expression date de l'année civile grégorienne 2015. En revanche, DATE_TRUNC avec la partie de date ISOYEAR tronque date_expression au début de l'année ISO, et non de l'année civile grégorienne. Le premier jeudi de l'année civile 2015 était le 1er janvier 2015 (2015-01-01), donc l'année ISO 2015 commence le lundi précédent, soit le 29 décembre 2014 (2014-12-29). Par conséquent, la limite de l'année ISO précédant l'expression date_expression 2015-06-15 est le 29 décembre 2014 (2014-12-29).

SELECT
  DATE_TRUNC('2015-06-15', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATE '2015-06-15') AS isoyear_number;

+------------------+----------------+
| isoyear_boundary | isoyear_number |
+------------------+----------------+
| 2014-12-29       | 2015           |
+------------------+----------------+

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(int64_expression)

Description

Interprète int64_expression comme le nombre de jours écoulés depuis le 1970-01-01.

Type de données renvoyé

DATE

Exemple

SELECT DATE_FROM_UNIX_DATE(14238) AS date_from_epoch;

+-----------------+
| date_from_epoch |
+-----------------+
| 2008-12-25      |
+-----------------+

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

Description

Formate un objet date_expr en fonction du paramètre format_string spécifié.

Consultez la section Éléments de format acceptés pour DATE pour obtenir la liste des éléments de format acceptés par cette fonction.

Type de données renvoyées

STRING

Exemples

SELECT FORMAT_DATE("%x", DATE "2008-12-25") AS US_format;

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+
SELECT FORMAT_DATE("%b-%d-%Y", DATE "2008-12-25") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec-25-2008 |
+-------------+
SELECT FORMAT_DATE("%b %Y", DATE "2008-12-25") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec 2008    |
+-------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

Description

Convertit une représentation de la date sous forme de chaîne en objet DATE.

format_string contient les éléments de format qui définissent le format de date_string. Chaque élément de date_string doit avoir un élément correspondant dans format_string. L'emplacement de chaque élément dans format_string doit correspondre à celui de chaque élément dans date_string.

-- This works because elements on both sides match.
SELECT PARSE_DATE("%A %b %e %Y", "Thursday Dec 25 2008")

-- This doesn't work because the year element is in different locations.
SELECT PARSE_DATE("%Y %A %b %e", "Thursday Dec 25 2008")

-- This doesn't work because one of the year elements is missing.
SELECT PARSE_DATE("%A %b %e", "Thursday Dec 25 2008")

-- This works because %F can find all matching elements in date_string.
SELECT PARSE_DATE("%F", "2000-12-30")

La chaîne de format est entièrement compatible avec la plupart des éléments de format, à l'exception de %a, %A, %g, %G, %j, %u, %U. , %V, %w et %W.

Lorsque vous utilisez PARSE_DATE, tenez compte des points suivants :

  • Champs non spécifiés : tout champ non spécifié est initialisé à compter de la date 1970-01-01.
  • Noms qui ne sont pas sensibles à la casse : les noms, tels que Monday, February, etc., ne sont pas sensibles à la casse.
  • Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro ou plusieurs espaces blancs consécutifs dans la chaîne de date. En outre, les espaces blancs au début et à la fin de la chaîne de date sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
  • Priorité de format : lorsqu'au moins deux éléments de format incluent des informations qui se chevauchent (par exemple, %F et %Y affectent tous deux l'année), le dernier d'entre eux remplace généralement les éléments précédents.

Type de données renvoyé

DATE

Exemples

Cet exemple convertit une chaîne au format MM/DD/YY en objet DATE :

SELECT PARSE_DATE("%x", "12/25/08") AS parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

Cet exemple convertit une chaîne au format YYYYMMDD en objet DATE :

SELECT PARSE_DATE("%Y%m%d", "20081225") AS parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

UNIX_DATE

UNIX_DATE(date_expression)

Description

Renvoie le nombre de jours écoulés depuis le 1er janvier 1970 (1970-01-01).

Type de données renvoyé

INT64

Exemple

SELECT UNIX_DATE(DATE "2008-12-25") AS days_from_epoch;

+-----------------+
| days_from_epoch |
+-----------------+
| 14238           |
+-----------------+

Éléments de format acceptés pour DATE

Sauf indication contraire, les fonctions de date utilisant des chaînes de format acceptent les éléments suivants :

Élément de format Description Exemple
%A Nom complet du jour de la semaine. Mercredi
%a Nom du jour de la semaine sous forme abrégée. Mer
%B Nom complet du mois. Janvier
%b ou %h Nom du mois sous forme abrégée. Jan
%C Siècle (une année divisée par 100 et tronquée pour obtenir un entier) sous forme de nombre décimal (00-99). 20
%D Date au format %m/%d/%y. 01/20/21
%d Jour du mois sous forme de nombre décimal (01-31). 20
%e Jour du mois sous forme de nombre décimal (1-31) ; les valeurs à un seul chiffre (1-9) sont précédées d'une espace. 20
%F Date au format %Y-%m-%d. 2021-01-20
%G Année ISO 8601 avec le siècle sous forme de nombre décimal. Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne Notez que %G et %Y peuvent produire des résultats différents près des limites de l'année grégorienne. Dans ce cas, l'année grégorienne et l'année ISO peuvent diverger. 2021
%g Année ISO 8601 sans le siècle sous forme de nombre décimal (00-99). Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %g et %y peuvent produire des résultats différents près des limites de l'année grégorienne. Dans ce cas, l'année grégorienne et l'année ISO peuvent diverger. 21
%j Jour de l'année sous forme de nombre décimal (001-366). 020
%m Mois sous forme de nombre décimal (01-12). 01
%n Caractère de nouvelle ligne.
%t Caractère de tabulation.
%U Numéro de la semaine dans l'année (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53). 03
%u Jour de la semaine (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (1-7). 3
%V Numéro de la semaine ISO 8601 dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (01-53). Si la semaine du 1er janvier compte quatre jours ou plus dans la nouvelle année, elle est considérée comme la semaine 1. Dans le cas contraire, elle est considérée comme semaine 53 de l'année précédente et la semaine qui suit est la semaine 1. 03
%W Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53). 03
%w Jour de la semaine (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (0-6). 3
%x Représentation de la date au format MM/JJ/AA. 01/20/21
%Y Année (avec le siècle) sous forme de nombre décimal. 2021
%y Année (sans le siècle) sous forme de nombre décimal (00-99), le premier zéro est facultatif. Peut être associé à %C. Si %C n'est pas spécifié, les années 00-68 correspondent aux années 2000, tandis que les années 69-99 correspondent aux années 1900. 21
%E4Y Années sous forme de nombres à quatre caractères (0001 ... 9999). Notez que %Y produit autant de caractères que nécessaire pour un rendu complet de l'année. 2021

Fonctions d'horodatage

Cloud Spanner SQL accepte les fonctions TIMESTAMP suivantes.

REMARQUE : Ces fonctions renvoient une erreur d'exécution en cas de débordement. Les valeurs de résultat sont délimitées par les valeurs min/max définies pour la date et l'horodatage.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Description

CURRENT_TIMESTAMP() produit une valeur TIMESTAMP continue, non ambiguë, qui comprend exactement 60 secondes par minute et ne répète pas les valeurs au-delà de la seconde intercalaire. Les parenthèses sont facultatives.

Cette fonction gère les sauts de secondes en les lissant sur une fenêtre de 20 heures autour de la seconde intercalaire insérée.

Types d'entrée acceptés

Non applicable

Type de données de résultat

TIMESTAMP

Exemples

SELECT CURRENT_TIMESTAMP() as now;

+--------------------------------+
| now                            |
+--------------------------------+
| 2020-06-02T23:58:40.347847393Z |
+--------------------------------+

Lorsqu'une colonne nommée current_timestamp est présente, le nom de la colonne et l'appel de fonction sans parenthèses sont ambigus. Pour garantir l'appel de fonction, ajoutez des parenthèses. Pour garantir le nom de la colonne, qualifiez-la avec sa variable de plage. Par exemple, la requête suivante sélectionne la fonction dans la colonne now et la colonne de table dans la colonne current_timestamp.

WITH t AS (SELECT 'column value' AS `current_timestamp`)
SELECT current_timestamp() AS now, t.current_timestamp FROM t;

+--------------------------------+-------------------+
| now                            | current_timestamp |
+--------------------------------+-------------------+
| 2020-06-02T23:58:40.347847393Z | column value      |
+--------------------------------+-------------------+

EXTRACT

EXTRACT(part FROM timestamp_expression [AT TIME ZONE timezone])

Description

Renvoie une valeur qui correspond à la valeur part spécifiée à partir d'une expression timestamp_expression fournie. Cette fonction accepte un paramètre facultatif, timezone. Consultez la rubrique Définition de fuseaux horaires pour plus d'informations sur la spécification d'un fuseau horaire.

Les valeurs part autorisées correspondent aux valeurs suivantes :

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAYOFWEEK
  • DAY
  • DAYOFYEAR
  • WEEK : renvoie le numéro de semaine de la date (compris dans la plage [0, 53]). Les semaines commencent le dimanche et les dates antérieures au premier dimanche de l'année correspondent à la semaine 0.
  • ISOWEEK : renvoie le numéro de semaine ISO 8601 de datetime_expression. Les ISOWEEK commencent le lundi. Les valeurs renvoyées sont comprises dans la plage [1, 53]. La première ISOWEEK de chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR : renvoie l'année à numérotation de semaine conforme à l'ISO 8601, qui correspond à l'année grégorienne contenant le jeudi de la semaine à laquelle date_expression appartient.
  • DATE

Les valeurs renvoyées tronquent les périodes d'ordre inférieur. Par exemple, lors de l'extraction de secondes, EXTRACT tronque les valeurs en millisecondes et en microsecondes.

Type de données renvoyées

INT64, sauf dans les cas suivants :

  • part correspond à DATE, renvoie un objet DATE.

Exemples

Dans l'exemple suivant, EXTRACT renvoie une valeur correspondant à l'élément de temps DAY.

WITH Input AS (SELECT TIMESTAMP("2008-12-25 05:30:00+00") AS timestamp_value)
SELECT
  EXTRACT(DAY FROM timestamp_value AT TIME ZONE "UTC") AS the_day_utc,
  EXTRACT(DAY FROM timestamp_value AT TIME ZONE "America/Los_Angeles") AS the_day_california
FROM Input

+-------------+--------------------+
| the_day_utc | the_day_california |
+-------------+--------------------+
| 25          | 24                 |
+-------------+--------------------+

Dans l'exemple suivant, EXTRACT renvoie des valeurs correspondant à différentes parties de date d'une colonne d'horodatages.

WITH Timestamps AS (
  SELECT TIMESTAMP("2005-01-03 12:34:56+00") AS timestamp_value UNION ALL
  SELECT TIMESTAMP("2007-12-31 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2009-01-01 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2009-12-31 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2017-01-02 12:00:00+00") UNION ALL
  SELECT TIMESTAMP("2017-05-26 12:00:00+00")
)
SELECT
  timestamp_value,
  EXTRACT(ISOYEAR FROM timestamp_value) AS isoyear,
  EXTRACT(ISOWEEK FROM timestamp_value) AS isoweek,
  EXTRACT(YEAR FROM timestamp_value) AS year,
  EXTRACT(WEEK FROM timestamp_value) AS week
FROM Timestamps
ORDER BY timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+---------+---------+------+------+
| timestamp_value        | isoyear | isoweek | year | week |
+------------------------+---------+---------+------+------+
| 2005-01-03T12:34:56Z   | 2005    | 1       | 2005 | 1    |
| 2007-12-31T12:00:00Z   | 2008    | 1       | 2007 | 52   |
| 2009-01-01T12:00:00Z   | 2009    | 1       | 2009 | 0    |
| 2009-12-31T12:00:00Z   | 2009    | 53      | 2009 | 52   |
| 2017-01-02T12:00:00Z   | 2017    | 1       | 2017 | 1    |
| 2017-05-26T12:00:00Z   | 2017    | 21      | 2017 | 21   |
+------------------------+---------+---------+------+------+

STRING

STRING(timestamp_expression[, timezone])

Description

Convertit une expression timestamp_expression en un type de données STRING. Cette fonction accepte un paramètre (facultatif) permettant de spécifier un fuseau horaire. Consultez la rubrique Définition de fuseaux horaires pour plus d'informations sur la spécification d'un fuseau horaire.

Type de données renvoyées

STRING

Exemple

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00+00", "UTC") AS string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 15:30:00+00        |
+-------------------------------+

TIMESTAMP

TIMESTAMP(string_expression[, timezone])
TIMESTAMP(date_expression[, timezone])

Description

  • string_expression[, timezone] : convertit une expression STRING en un type de données TIMESTAMP. string_expression doit inclure un littéral d'horodatage. Si string_expression inclut un fuseau horaire dans le littéral d'horodatage, n'incluez pas d'argument timezone explicite.
  • date_expression[, timezone] : convertit un objet DATE en un type de données TIMESTAMP.

Cette fonction accepte un paramètre facultatif permettant de spécifier un fuseau horaire. Si aucun fuseau horaire n'est spécifié, le fuseau horaire par défaut (America/Los_Angeles) est utilisé.

Type de données renvoyé

TIMESTAMP

Exemples

SELECT TIMESTAMP("2008-12-25 15:30:00+00") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T15:30:00Z |
+----------------------+
SELECT TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T23:30:00Z |
+----------------------+
SELECT TIMESTAMP("2008-12-25 15:30:00 UTC") AS timestamp_str;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_str        |
+----------------------+
| 2008-12-25T15:30:00Z |
+----------------------+
SELECT TIMESTAMP(DATE "2008-12-25") AS timestamp_date;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+----------------------+
| timestamp_date       |
+----------------------+
| 2008-12-25T08:00:00Z |
+----------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

Description

Ajoute des unités int64_expression de date_part à l'horodatage, quel que soit le fuseau horaire.

TIMESTAMP_ADD est compatible avec les valeurs suivantes pour date_part :

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Équivaut à 60 minutes (MINUTE).
  • DAY. Équivaut à 24 heures (HOUR).

Type de données renvoyées

TIMESTAMP

Exemple

SELECT
  TIMESTAMP("2008-12-25 15:30:00+00") AS original,
  TIMESTAMP_ADD(TIMESTAMP "2008-12-25 15:30:00+00", INTERVAL 10 MINUTE) AS later;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25T15:30:00Z   | 2008-12-25T15:40:00Z   |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL int64_expression date_part)

Description

Soustrait des unités int64_expression de date_part de l'horodatage, quel que soit le fuseau horaire.

TIMESTAMP_SUB est compatible avec les valeurs suivantes pour date_part :

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Équivaut à 60 minutes (MINUTE).
  • DAY. Équivaut à 24 heures (HOUR).

Type de données renvoyé

TIMESTAMP

Exemple

SELECT
  TIMESTAMP("2008-12-25 15:30:00+00") AS original,
  TIMESTAMP_SUB(TIMESTAMP "2008-12-25 15:30:00+00", INTERVAL 10 MINUTE) AS earlier;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25T15:30:00Z   | 2008-12-25T15:20:00Z   |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression_a, timestamp_expression_b, date_part)

Description

Renvoie le nombre d'intervalles date_part entiers spécifiés entre deux objets TIMESTAMP (timestamp_expression_atimestamp_expression_b). Si la première expression TIMESTAMP est antérieur à la seconde, le résultat est négatif. La fonction renvoie une erreur si le calcul excède le type du résultat, par exemple si la différence en nanosecondes entre les deux objets TIMESTAMP dépasse une valeur INT64.

TIMESTAMP_DIFF est compatible avec les valeurs suivantes pour date_part :

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Équivaut à 60 minutes (MINUTE).
  • DAY. Équivaut à 24 heures (HOUR).

Type de données renvoyé

INT64

Exemple

SELECT
  TIMESTAMP("2010-07-07 10:20:00+00") AS later_timestamp,
  TIMESTAMP("2008-12-25 15:30:00+00") AS earlier_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00+00", TIMESTAMP "2008-12-25 15:30:00+00", HOUR) AS hours;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+-------+
| later_timestamp        | earlier_timestamp      | hours |
+------------------------+------------------------+-------+
| 2010-07-07T10:20:00Z   | 2008-12-25T15:30:00Z   | 13410 |
+------------------------+------------------------+-------+

Dans l'exemple suivant, le premier horodatage se produit avant le deuxième, ce qui entraîne un résultat négatif.

SELECT TIMESTAMP_DIFF(TIMESTAMP "2018-08-14", TIMESTAMP "2018-10-14", DAY);

+---------------+
| negative_diff |
+---------------+
| -61           |
+---------------+

Dans cet exemple, le résultat est de 0, car seul le nombre d'intervalles HOUR entiers spécifiés est inclus.

SELECT TIMESTAMP_DIFF("2001-02-01 01:00:00", "2001-02-01 00:00:01", HOUR)

+---------------+
| negative_diff |
+---------------+
| 0             |
+---------------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part[, timezone])

Description

Tronque un horodatage selon le niveau de précision de date_part.

TIMESTAMP_TRUNC est compatible avec les valeurs suivantes pour date_part :

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • ISOWEEK : tronque timestamp_expression à la limite de la semaine ISO 8601 précédente. Les semaines ISOWEEK commencent le lundi. La première ISOWEEK de chaque année ISO englobe le premier jeudi de l'année civile grégorienne correspondante. Toute date_expression précédente sera tronquée au lundi précédent.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR : tronque timestamp_expression à la limite de l'année à numérotation de semaine ISO 8601 précédente. La limite d'année ISO est le lundi de la première semaine où le jeudi appartient à l'année civile grégorienne correspondante.

La fonction TIMESTAMP_TRUNC est compatible avec un paramètre facultatif timezone. Ce paramètre s'applique aux date_parts suivants :

  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • ISOWEEK
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR

Utilisez ce paramètre si vous souhaitez utiliser un fuseau horaire différent de celui par défaut (America/Los_Angeles) dans le cadre de l'opération de troncation.

Lorsqu'une valeur TIMESTAMP est tronquée à la minute (MINUTE) ou à l'heure (HOUR), TIMESTAMP_TRUNC détermine l'heure civile de TIMESTAMP dans le fuseau horaire spécifié (ou par défaut), et soustrait les minutes et les secondes (si l'horodatage est tronqué à l'heure) ou les secondes (s'il est tronqué à la minute) de cet horodatage TIMESTAMP. Bien que cette méthode fournisse un résultat intuitif dans la plupart des cas, ce ne sera pas le cas lors du passage aux horaires d'été qui ne sont pas alignés sur l'heure.

Type de données renvoyées

TIMESTAMP

Exemples

SELECT
  TIMESTAMP_TRUNC(TIMESTAMP "2008-12-25 15:30:00+00", DAY, "UTC") AS utc,
  TIMESTAMP_TRUNC(TIMESTAMP "2008-12-25 15:30:00+00", DAY, "America/Los_Angeles") AS la;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25T00:00:00Z   | 2008-12-25T08:00:00Z   |
+------------------------+------------------------+

Dans l'exemple suivant, le code d'origine timestamp_expression date de l'année civile grégorienne 2015. Cependant, TIMESTAMP_TRUNC avec la partie de date ISOYEAR tronque timestamp_expression au début de l'année ISO, et non de l'année civile grégorienne. Le premier jeudi de l'année civile 2015 était le 2015-01-01, donc l'année ISO 2015 commence le lundi précédent, soit le 2014-12-29. Par conséquent, la limite de l'année ISO précédant l'expression timestamp_expression 2015-06-15 00:00:00 + 00 correspond à 2014-12-29.

SELECT
  TIMESTAMP_TRUNC("2015-06-15 00:00:00+00", ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM TIMESTAMP "2015-06-15 00:00:00+00") AS isoyear_number;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+----------------+
| parsed                 | isoyear_number |
+------------------------+----------------+
| 2014-12-29T08:00:00Z   | 2015           |
+------------------------+----------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, timezone])

Description

Formate un horodatage en fonction de la chaîne de format format_string spécifiée.

Consultez la section Éléments de format acceptés pour TIMESTAMP pour obtenir une liste des éléments de format acceptés par cette fonction.

Type de données renvoyées

STRING

Exemple

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2008-12-25 15:30:00+00", "UTC") AS formatted;

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 15:30:00 2008 |
+--------------------------+
SELECT FORMAT_TIMESTAMP("%b-%d-%Y", TIMESTAMP "2008-12-25 15:30:00+00") AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec-25-2008 |
+-------------+
SELECT FORMAT_TIMESTAMP("%b %Y", TIMESTAMP "2008-12-25 15:30:00+00")
  AS formatted;

+-------------+
| formatted   |
+-------------+
| Dec 2008    |
+-------------+

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, timestamp_string[, timezone])

Description

Convertit une représentation d'un horodatage sous forme de chaîne en objet TIMESTAMP.

format_string contient les éléments de format qui définissent le format de timestamp_string. Chaque élément de timestamp_string doit avoir un élément correspondant dans format_string. L'emplacement de chaque élément dans format_string doit correspondre à celui de chaque élément dans timestamp_string.

-- This works because elements on both sides match.
SELECT PARSE_TIMESTAMP("%a %b %e %I:%M:%S %Y", "Thu Dec 25 07:30:00 2008")

-- This doesn't work because the year element is in different locations.
SELECT PARSE_TIMESTAMP("%a %b %e %Y %I:%M:%S", "Thu Dec 25 07:30:00 2008")

-- This doesn't work because one of the year elements is missing.
SELECT PARSE_TIMESTAMP("%a %b %e %I:%M:%S", "Thu Dec 25 07:30:00 2008")

-- This works because %c can find all matching elements in timestamp_string.
SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008")

La chaîne de format est entièrement compatible avec la plupart des éléments de format, à l'exception de %a, %A, %g, %G, %j, %P, %u, %U, %V, %w et %W.

Lorsque vous utilisez PARSE_TIMESTAMP, tenez compte des points suivants :

  • Champs non spécifiés : tout champ non spécifié est initialisé à compter de 1970-01-01 00:00:00.0. Cette valeur d'initialisation utilise le fuseau horaire spécifié par l'argument "time zone" de la fonction, si ce dernier est présent. Dans le cas contraire, la valeur d'initialisation utilise le fuseau horaire par défaut (America/Los_Angeles). Par exemple, si l'année n'est pas spécifiée, la valeur par défaut 1970 est utilisée, et ainsi de suite.
  • Noms qui ne sont pas sensibles à la casse : les noms, tels que Monday, February, etc., ne sont pas sensibles à la casse.
  • Espace blanc : un ou plusieurs espaces blancs consécutifs dans la chaîne de format correspondent à zéro ou plusieurs espaces blancs consécutifs dans la chaîne d'horodatage. En outre, les espaces blancs au début et à la fin de la chaîne d'horodatage sont toujours autorisés, même s'ils ne figurent pas dans la chaîne de format.
  • Priorité de format : lorsque deux éléments de format (ou plus) se chevauchent (par exemple %F et %Y affectent l'année), le dernier d'entre eux remplace généralement les précédents, à quelques exceptions près (consulter les descriptions de %s, %C et %y).

Type de données renvoyées

TIMESTAMP

Exemple

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008") AS parsed;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| parsed                 |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_SECONDS

TIMESTAMP_SECONDS(int64_expression)

Description

Interprète int64_expression comme le nombre de secondes écoulées depuis 1970-01-01 00:00:00 UTC.

Type de données renvoyées

TIMESTAMP

Exemple

SELECT TIMESTAMP_SECONDS(1230219000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

Description

Interprète int64_expression comme le nombre de millisecondes écoulées depuis 1970-01-01 00:00:00 UTC.

Type de données renvoyées

TIMESTAMP

Exemple

SELECT TIMESTAMP_MILLIS(1230219000000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

Description

Interprète int64_expression comme le nombre de microsecondes écoulées depuis 1970-01-01 00:00:00 UTC.

Type de données renvoyées

TIMESTAMP

Exemple

SELECT TIMESTAMP_MICROS(1230219000000000) AS timestamp_value;

-- Results may differ, depending upon the environment and time zone where this query was executed.
+------------------------+
| timestamp_value        |
+------------------------+
| 2008-12-25T15:30:00Z   |
+------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Description

Renvoie le nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Tronque les niveaux de précision plus élevés.

Type de données renvoyées

INT64

Exemple

SELECT UNIX_SECONDS(TIMESTAMP "2008-12-25 15:30:00+00") AS seconds;

+------------+
| seconds    |
+------------+
| 1230219000 |
+------------+

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Description

Renvoie le nombre de millisecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC). Tronque les niveaux de précision plus élevés.

Type de données renvoyées

INT64

Exemple

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00+00") AS millis;

+---------------+
| millis        |
+---------------+
| 1230219000000 |
+---------------+

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

Description

Renvoie le nombre de microsecondes écoulées depuis 1970-01-01 00:00:00  UTC. Tronque les niveaux de précision plus élevés.

Type de données renvoyées

INT64

Exemple

SELECT UNIX_MICROS(TIMESTAMP "2008-12-25 15:30:00+00") AS micros;

+------------------+
| micros           |
+------------------+
| 1230219000000000 |
+------------------+

PENDING_COMMIT_TIMESTAMP

PENDING_COMMIT_TIMESTAMP()

Description

Utilisez la fonction PENDING_COMMIT_TIMESTAMP() dans une instruction LMD INSERT ou UPDATE pour écrire l'horodatage de commit en attente, c'est-à-dire l'horodatage de commit de l'écriture lors de la validation, dans une colonne de type TIMESTAMP.

Cloud Spanner SQL sélectionne l'horodatage de commit lorsque la transaction est enregistrée. La fonction PENDING_COMMIT_TIMESTAMP peut être utilisée comme valeur pour INSERT ou UPDATE uniquement dans une colonne possédant le type approprié. Elle ne peut pas être utilisée avec SELECT ou comme entrée dans une autre expression scalaire.

Type de données renvoyé

TIMESTAMP

Exemple

L'instruction LMD suivante met à jour la colonne LastUpdated de la table Singers avec l'horodatage de commit.

UPDATE Performances SET LastUpdated = PENDING_COMMIT_TIMESTAMP()
   WHERE SingerId=1 AND VenueId=2 AND EventDate="2015-10-21"

Éléments de format acceptés pour TIMESTAMP

Sauf indication contraire, les fonctions d'horodatage utilisant des chaînes de format acceptent les éléments suivants :

Élément de format Description Exemple
%A Nom complet du jour de la semaine. Mercredi
%a Nom du jour de la semaine sous forme abrégée. Mer
%B Nom complet du mois. Janvier
%b ou %h Nom du mois sous forme abrégée. Jan
%C Siècle (une année divisée par 100 et tronquée pour obtenir un entier) sous forme de nombre décimal (00-99). 20
%c Représentation de la date et de l'heure au format %a %b %e %T %Y. Mer Jan 20 16:47:00 2021
%D Date au format %m/%d/%y. 01/20/21
%d Jour du mois sous forme de nombre décimal (01-31). 20
%e Jour du mois sous forme de nombre décimal (1-31) ; les valeurs à un seul chiffre (1-9) sont précédées d'une espace. 20
%F Date au format %Y-%m-%d. 2021-01-20
%G Année ISO 8601 avec le siècle sous forme de nombre décimal. Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne Notez que %G et %Y peuvent produire des résultats différents près des limites de l'année grégorienne. Dans ce cas, l'année grégorienne et l'année ISO peuvent diverger. 2021
%g Année ISO 8601 sans le siècle sous forme de nombre décimal (00-99). Chaque année ISO commence le lundi précédant le premier jeudi de l'année civile grégorienne. Notez que %g et %y peuvent produire des résultats différents près des limites de l'année grégorienne. Dans ce cas, l'année grégorienne et l'année ISO peuvent diverger. 21
%H Heure (format 24 heures) sous forme de nombre décimal (00-23). 16
%I Heure (format 12 heures) sous forme de nombre décimal (01-12). 04
%j Jour de l'année sous forme de nombre décimal (001-366). 020
%k Heure (format 24 heures) sous forme de nombre décimal (0-23) ; les valeurs à un seul chiffre sont précédées d'une espace. 16
%l Heure (format 12 heures) sous forme de nombre décimal (1-12) ; les valeurs à un seul chiffre sont précédées d'une espace. 11
%M Minutes sous forme de nombre décimal (00-59). 47
%m Mois sous forme de nombre décimal (01-12). 01
%n Caractère de nouvelle ligne.
%P am ou pm. am
%p AM ou PM. AM
%Q Trimestre sous forme de nombre décimal (1-4). 1
%R Heure au format %H:%M. 16:47
%r Heure au format 12 heures (avec notation AM/PM). 04:47:00 PM
%S Secondes sous forme de nombre décimal (00-60). 00
%s Nombre de secondes écoulées depuis le 1970-01-01 00:00:00 UTC. Remplace systématiquement tous les autres éléments de format, indépendamment de l'endroit où %s apparaît dans la chaîne. Si plusieurs éléments %s apparaissent, le dernier est prioritaire. 1611179220
%T Heure au format %H:%M:%S. 16:47:00
%t Caractère de tabulation.
%U Numéro de la semaine dans l'année (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53). 03
%u Jour de la semaine (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (1-7). 3
%V Numéro de la semaine ISO 8601 dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (01-53). Si la semaine du 1er janvier compte quatre jours ou plus dans la nouvelle année, elle est considérée comme la semaine 1. Dans le cas contraire, elle est considérée comme semaine 53 de l'année précédente et la semaine qui suit est la semaine 1. 03
%W Numéro de la semaine dans l'année (lundi considéré comme premier jour de la semaine) sous forme de nombre décimal (00-53). 03
%w Jour de la semaine (dimanche considéré comme premier jour de la semaine) sous forme de nombre décimal (0-6). 3
%X Représentation de l'heure au format HH:MM:SS. 16:47:00
%x Représentation de la date au format MM/JJ/AA. 01/20/21
%Y Année (avec le siècle) sous forme de nombre décimal. 2021
%y Année (sans le siècle) sous forme de nombre décimal (00-99), le premier zéro est facultatif. Peut être associé à %C. Si %C n'est pas spécifié, les années 00-68 correspondent aux années 2000, tandis que les années 69-99 correspondent aux années 1900. 21
%Z Nom du fuseau horaire. UTC-5
%z Décalage par rapport au méridien d'origine, au format +HHMM ou -HHMM selon le cas. Les emplacements situés à l'est du méridien de Greenwich sont représentés par des valeurs positives. -0500
%% Caractère % unique. %
%Ez Fuseau horaire numérique compatible RFC 3339 (+HH:MM ou -HH:MM). -05:00
%E#S Secondes avec # chiffres de précision fractionnelle. 00.000
%E*S Secondes avec précision fractionnelle complète (littéral '*'). 00
%E4Y Année sous forme de nombre à quatre caractères (0001 … 9999). Notez que %Y produit autant de caractères que nécessaire pour un rendu complet de l'année. 2021

Définition de fuseaux horaires

Certaines fonctions de date et d'horodatage vous permettent d'ignorer le fuseau horaire par défaut et d'en spécifier un autre. Vous pouvez indiquer un fuseau horaire en indiquant son nom (par exemple, America/Los_Angeles) ou le décalage de fuseau horaire par rapport à l'heure UTC (par exemple, -08).

Si vous choisissez d'utiliser un décalage de fuseau horaire, utilisez le format suivant :

(+|-)H[H][:M[M]]

Les horodatages suivants sont équivalents, car le décalage de fuseau horaire pour America/Los_Angeles est de -08 pour la date et l'heure spécifiées.

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00 America/Los_Angeles") as millis;
SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00-08:00") as millis;

Fonctions Net

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Description

Convertit une adresse IPv4 ou IPv6 du format texte (STRING) au format binaire (BYTES) dans l'ordre des octets sur le réseau.

Cette fonction accepte les formats suivants pour addr_str :

  • IPv4 : quatre nombres séparés par des points, Par exemple, 10.1.2.3.
  • IPv6 : éléments séparés par deux points, par exemple, 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Pour plus d'exemples, consultez la page IP Version 6 Addressing Architecture.

Cette fonction n'accepte pas le format CIDR, tel que 10.1.2.3/32.

Si cette fonction reçoit une entrée NULL, elle renvoie NULL. Si l'entrée est considérée comme non valide, une erreur OUT_OF_RANGE se produit.

Type de données renvoyées

BYTES

Exemple

SELECT
  addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128'
]) AS addr_str;
addr_str ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

Description

Semblable à NET.IP_FROM_STRING, mais renvoie NULL au lieu de générer une erreur si l'entrée n'est pas valide.

Type de données renvoyées

BYTES

Exemple

SELECT
  addr_str,
  FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128',
  '48.49.50.51/32',
  '48.49.50',
  '::wxyz'
]) AS addr_str;
addr_str safe_ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
48.49.50.51/32 NULL
48.49.50 NULL
::wxyz NULL

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

Description Convertit une adresse IPv4 ou IPv6 du format binaire (BYTES) au format texte (STRING) dans l'ordre des octets sur le réseau.

Si l'entrée correspond à 4 octets, cette fonction renvoie une adresse IPv4 au format STRING. Si l'entrée correspond à 16 octets, une adresse IPv6 est renvoyée au format STRING.

Si cette fonction reçoit une entrée NULL, elle renvoie NULL. Si la longueur de l'entrée est différente de 4 ou 16, une erreur OUT_OF_RANGE se produit.

Type de données renvoyées

STRING

Exemple

SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
  b"0123",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
  b"0123456789@ABCDE",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;
addr_bin ip_to_string
b"0123" 48.49.50.51
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" ::1
b"0123456789@ABCDE" 3031:3233:3435:3637:3839:4041:4243:4445
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" ::ffff:192.0.2.128

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

Description

Renvoie un masque de réseau, c'est-à-dire une séquence d'octets d'une longueur égale à num_output_bytes, où les prefix_length premiers bits sont définis sur 1, et les autres bits sur 0. num_output_bytes et prefix_length sont de type INT64. Cette fonction génère une erreur si la valeur de num_output_bytes est différente de 4 (pour IPv4) ou de 16 (pour IPv6). Elle génère également une erreur si la valeur de prefix_length est négative ou supérieure à 8 * num_output_bytes.

Type de données renvoyées

BYTES

Exemple

SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
  STRUCT(4 as x, 0 as y),
  (4, 20),
  (4, 32),
  (16, 0),
  (16, 1),
  (16, 128)
]);
x y ip_net_mask
4 0 b"\x00\x00\x00\x00"
4 20 b"\xff\xff\xf0\x00"
4 32 b"\xff\xff\xff\xff"
16 0 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 1 b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 128 b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

Description Prend addr_bin, une adresse IPv4 ou IPv6 au format binaire (BYTES) dans l'ordre des octets du réseau, et renvoie une adresse de sous-réseau au même format. Le résultat présente la même longueur que addr_bin. Les prefix_length premiers bits correspondent à ceux de addr_bin, et les bits restants sont définis sur 0.

Cette fonction génère une erreur si la valeur de LENGTH(addr_bin) est différente de 4 ou de 16, ou si la valeur de prefix_len est négative ou supérieure à LENGTH(addr_bin) * 8.

Type de données renvoyées

BYTES

Exemple

SELECT
  FORMAT("%T", x) as addr_bin, prefix_length,
  FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
  STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
  (b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
  (b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
  (b'0123456789@ABCDE', 80)
]);
addr_bin prefix_length ip_trunc
b"\xaa\xbb\xcc\xdd" 0 b"\x00\x00\x00\x00"
b"\xaa\xbb\xcc\xdd" 11 b"\xaa\xa0\x00\x00"
b"\xaa\xbb\xcc\xdd" 12 b"\xaa\xb0\x00\x00"
b"\xaa\xbb\xcc\xdd" 24 b"\xaa\xbb\xcc\x00"
b"\xaa\xbb\xcc\xdd" 32 b"\xaa\xbb\xcc\xdd"
b"0123456789@ABCDE" 80 b"0123456789\x00\x00\x00\x00\x00\x00"

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

Description

Convertit une adresse IPv4 du format entier au format binaire (BYTES) dans l'ordre des octets sur le réseau. Dans l'entrée entière, le bit de poids faible de l'adresse IP est stocké dans le bit de poids faible de l'entier, quelle que soit l'architecture de l'hôte ou du client. Par exemple, 1 signifie 0.0.0.1 et 0x1FF signifie 0.0.1.255.

Cette fonction vérifie que les 32 bits de poids fort sont tous définis sur 0, ou que les 33 bits de poids fort sont tous définis sur 1 (le signe est étendu à partir d'un entier de 32 bits). En d'autres termes, l'entrée doit être comprise dans la plage [-0x80000000, 0xFFFFFFFF]. Dans le cas contraire, cette fonction génère une erreur.

Cette fonction n'est pas compatible avec IPv6.

Type de données renvoyé

BYTES

Exemple

SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
  SELECT CAST(x_hex AS INT64) x, x_hex
  FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);
x x_hex ipv4_from_int64
0 0x0 b"\x00\x00\x00\x00"
11259375 0xABCDEF b"\x00\xab\xcd\xef"
4294967295 0xFFFFFFFF b"\xff\xff\xff\xff"
-1 -0x1 b"\xff\xff\xff\xff"
-2 -0x2 b"\xff\xff\xff\xfe"

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

Description

Convertit une adresse IPv4 du format binaire (BYTES) au format entier dans l'ordre des octets sur le réseau. Dans la sortie entière, le bit de poids faible de l'adresse IP est stocké dans le bit de poids faible de l'entier, quelle que soit l'architecture de l'hôte ou du client. Par exemple, 1 signifie 0.0.0.1, et 0x1FF signifie 0.0.1.255. La sortie est comprise dans la plage [0, 0xFFFFFFFF].

Si la longueur de l'entrée est différente de 4, cette fonction génère une erreur.

Cette fonction n'est pas compatible avec IPv6.

Type de données renvoyé

INT64

Exemple

SELECT
  FORMAT("%T", x) AS addr_bin,
  FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;
addr_bin ipv4_to_int64
b"\x00\x00\x00\x00" 0x0
b"\x00\xab\xcd\xef" 0xABCDEF
b"\xff\xff\xff\xff" 0xFFFFFFFF

NET.HOST

NET.HOST(url)

Description

Prend une URL au format STRING et renvoie l'hôte dans ce même format. Pour des résultats optimaux, les valeurs d'URL doivent être conformes au format défini par la norme RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent. Si elle ne peut pas analyser l'entrée, elle renvoie NULL.

Remarque : La fonction n'effectue aucune normalisation.

Type de données renvoyé

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
Entrée Description Hôte Suffixe Domaine
"" entrée non valide NULL NULL NULL
"http://abc.xyz" URL standard "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public "a.b" NULL NULL
"https://[::1]:80" URL standard avec hôte IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL standard avec nom de domaine internationalisé "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL non standard avec espaces et lettres majuscules, et sans schéma "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI au lieu d'URL – incompatible "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Description

Prend une URL au format STRING et renvoie le suffixe public (tel que com, org ou net) dans ce même format. Un suffixe public est un domaine de l'ICANN enregistré sur publicsuffix.org. Pour des résultats optimaux, les valeurs d'URL doivent être conformes au format défini par la norme RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent.

Cette fonction renvoie NULL si l'une des conditions suivantes est remplie :

  • La fonction ne peut pas analyser l'hôte à partir de l'entrée.
  • L'hôte analysé contient des points adjacents au milieu (pas au début ni à la fin).
  • L'hôte analysé ne contient aucun suffixe public.

Avant de rechercher le suffixe public, cette fonction normalise temporairement l'hôte en convertissant les majuscules latines en minuscules et en encodant tous les caractères non-ASCII avec Punycode. La fonction renvoie ensuite le suffixe public en tant que partie de l'hôte d'origine plutôt que de l'hôte normalisé.

Remarque : La fonction n'effectue pas de normalisation Unicode.

Remarque : Les données relatives aux suffixes publics du site publicsuffix.org contiennent également des domaines privés. Cette fonction ignore les domaines privés.

Remarque : Les données relatives aux suffixes publics peuvent évoluer avec le temps. Par conséquent, une entrée qui produit un résultat NULL maintenant pourra renvoyer une valeur non NULL dans l'avenir.

Type de données renvoyées

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
Entrée Description Hôte Suffixe Domaine
"" entrée non valide NULL NULL NULL
"http://abc.xyz" URL standard "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public "a.b" NULL NULL
"https://[::1]:80" URL standard avec hôte IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL standard avec nom de domaine internationalisé "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL non standard avec espaces et lettres majuscules, et sans schéma "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" URI au lieu d'URL – incompatible "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Description

Prend une URL au format STRING et renvoie le domaine enregistré ou pouvant être enregistré (le suffixe public précédé d'une étiquette) au format STRING. Pour des résultats optimaux, les valeurs d'URL doivent être conformes au format défini par la norme RFC 3986. Dans le cas contraire, cette fonction s'efforce d'analyser l'entrée et de renvoyer un résultat pertinent.

Cette fonction renvoie NULL si l'une des conditions suivantes est remplie :

  • La fonction ne peut pas analyser l'hôte à partir de l'entrée.
  • L'hôte analysé contient des points adjacents au milieu (pas au début ni à la fin).
  • L'hôte analysé ne contient aucun suffixe public.
  • L'hôte analysé ne contient qu'un suffixe public, qui n'est pas précédé d'une étiquette.

Avant de rechercher le suffixe public, cette fonction normalise temporairement l'hôte en convertissant les majuscules latines en minuscules et en encodant tous les caractères non-ASCII avec Punycode. Elle renvoie ensuite le domaine enregistré ou pouvant être enregistré en tant que partie de l'hôte d'origine plutôt que de l'hôte normalisé.

Remarque : La fonction n'effectue pas de normalisation Unicode.

Remarque : Les données relatives aux suffixes publics du site publicsuffix.org contiennent également des domaines privés. Cette fonction ne traite pas un domaine privé comme un suffixe public. Par exemple, si "us.com" est un domaine privé compris dans les données relatives aux suffixes publics, NET.REG_DOMAIN("foo.us.com") renvoie "us.com" (le suffixe public "com", précédé de l'étiquette "us") plutôt que "foo.us.com" (le domaine privé "us.com", précédé de l'étiquette "foo").

Remarque : Les données relatives aux suffixes publics peuvent évoluer avec le temps. Par conséquent, une entrée qui produit un résultat NULL maintenant pourra renvoyer une valeur non NULL dans l'avenir.

Type de données renvoyées

STRING

Exemple

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
Entrée Description Hôte Suffixe Domaine
"" entrée non valide NULL NULL NULL
"http://abc.xyz" URL standard "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL standard avec requête, chemin, port et schéma relatifs, mais sans suffixe public "a.b" NULL NULL
"https://[::1]:80" URL standard avec hôte IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL standard avec nom de domaine internationalisé "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL non standard avec espaces et lettres majuscules, et sans schéma "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI au lieu d'URL – incompatible "mailto" NULL NULL

Opérateurs

Les opérateurs sont représentés par des caractères spéciaux ou des mots-clés ; ils n'utilisent pas la syntaxe d'appel de fonction. Un opérateur manipule un certain nombre d'entrées de données (ces entrées de données sont également appelées opérandes), puis renvoie un résultat.

Conventions communes :

  • Sauf indication contraire, tous les opérateurs renvoient NULL lorsque l'un des opérandes est NULL.
  • Tous les opérateurs génèrent une erreur lorsque le résultat du calcul entraîne un débordement.
  • Pour toutes les opérations en virgule flottante, +/-inf et NaN ne peuvent être renvoyés que si l'un des opérandes est +/-inf ou NaN. Dans les autres cas, une erreur est renvoyée.

Priorité de l'opérateur

Le tableau ci-dessous répertorie tous les opérateurs SQL de Cloud Spanner, classés de la priorité la plus élevée à la plus faible, c'est-à-dire en fonction de l'ordre selon lequel ils seront évalués dans une instruction.

Ordre de priorité Opérateur Types de données d'entrée Nom Arité de l'opérateur
1 . STRUCT
Opérateur d'accès au champ Binaire
  Opérateur de sous-scriptif de tableau ARRAY Position du tableau. Doit être utilisé avec OFFSET ou ORDINAL (consultez la section Fonctions de tableau). Binary
2 + Tous les types numériques Plus unaire. Unaire
  - Tous les types numériques Moins unaire Unaire
  ~ Entier ou BYTES Opérateur NOT (PAS) au niveau du bit Unaire
3 * Tous les types numériques Multiplication Binaire
  / Tous les types numériques Division Binaire
  || STRING, BYTES ou ARRAY<T> Opérateur de concaténation Binaire
4 + Tous les types numériques Addition Binaire
  - Tous les types numériques Soustraction Binaire
5 << Entier ou BYTES Décalage à gauche bit à bit Binaire
  >> Entier ou BYTES Décalage à droite bit à bit Binaire
6 & Entier ou BYTES Opérateur AND (ET) au niveau du bit Binaire
7 ^ Entier ou BYTES Opérateur XOR (OU exclusif) au niveau du bit Binaire
8 | Entier ou BYTES Opérateur OR (OU) au niveau du bit Binaire
9 (Opérateurs de comparaison) = Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Equal (Égal à) Binaire
  < Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Moins de Binaire
  > Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Supérieur à Binaire
  <= Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Inférieur ou égal à Binaire
  >= Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Supérieur ou égal à Binaire
  !=, <> Tout type comparable. Pour obtenir la liste complète, consultez la page Types de données. Not Equal (Non égal à) Binaire
  [NOT] LIKE STRING et octet La valeur correspond [ne correspond pas] au modèle spécifié Binaire
  [NOT] BETWEEN Tous types comparables. Pour obtenir la liste complète, consultez la page Types de données. La valeur est [n'est pas] comprise dans la plage spécifiée Binaire
  [NOT] IN Tous types comparables. Pour obtenir la liste complète, consultez la page Types de données. La valeur est [n'est pas] comprise dans l'ensemble de valeurs spécifié Binaire
  IS [NOT] NULL Tous La valeur est [n'est pas] NULL Unaire
  IS [NOT] TRUE BOOL La valeur est [n'est pas] TRUE. Unaire
  IS [NOT] FALSE BOOL La valeur est [n'est pas] FALSE. Unaire
10 NOT BOOL Logical NOT (Opérateur logique PAS) Unaire
11 AND BOOL Logical AND (Opérateur logique ET) Binaire
12 OR BOOL Logical OR (Opérateur logique OU) Binaire

Les opérateurs ayant le même niveau de priorité sont considérés selon un schéma "associatif gauche". Cela signifie que le regroupement de ces opérateurs commence par la gauche, puis se poursuit vers la droite. Par exemple, l'expression :

x AND y AND z

est interprétée comme :

( ( x AND y ) AND z )

L'expression :

x * y / z

est interprétée comme :

( ( x * y ) / z )

Tous les opérateurs de comparaison ont la même priorité, mais les opérateurs de comparaison ne sont pas associatifs. Par conséquent, des parenthèses sont nécessaires afin de résoudre les ambiguïtés. Exemple :

(x < y) IS FALSE

Opérateur d'accès au champ

expression.fieldname[. ...]

Description

Récupère la valeur d'un champ. Cette méthode est également appelée "point". Peut être utilisé pour accéder à des champs imbriqués. Par exemple, expression.fieldname1.fieldname2.

Types d'entrée

  • STRUCT

Type renvoyé

  • Pour STRUCT: type de données SQL de fieldname. Si un champ est introuvable dans la structure, une erreur est renvoyée.

Opérateur de sous-scriptif de tableau

array_expression [position_keyword (array_element_id)]

Description

Obtenez une valeur dans un tableau correspondant à un emplacement spécifique. Compatible avec certaines fonctions de tableau.

Types d'entrée

  • position_keyword : OFFSET ou ORDINAL. Pour en savoir plus, consultez les sections OFFSET et ORDINAL
  • array_element_id: entier représentant un index dans le tableau.

Type renvoyé

Saisissez T stocké au niveau de l'index dans un tableau.

Opérateurs arithmétiques

Tous les opérateurs arithmétiques acceptent les entrées de type numérique T, et les résultats sont