Cette page a été traduite par l'API Cloud Translation.

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:

Flags
Largeur
Précision

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

Comportement de%g et de %G
Comportement de%t et %T
Conditions d'erreur
Gestion des arguments NULL
Règles sémantiques supplémentaires

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.

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 |
| Å | Å  | 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 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.

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