Funciones de string

Estas funciones de string funcionan en dos valores diferentes: tipos de datos STRING y BYTES. Los valores de STRING deben ser UTF-8 y estar bien formados.

Las funciones que muestran valores de posición, como STRPOS, codifican esas posiciones como INT64. El valor 1 se refiere al primer carácter (o byte), 2 se refiere al segundo, y así sucesivamente. El valor 0 indica un índice no válido. Cuando se trabaja en los tipos de STRING, las posiciones mostradas hacen referencia a las posiciones de los caracteres.

Todas las comparaciones de string se realizan byte a byte, sin importar la equivalencia canónica Unicode.

BYTE_LENGTH

BYTE_LENGTH(value)

Descripción

Muestra la longitud del valor en bytes, sin importar si el tipo de valor es STRING o BYTES.

Tipo de datos que se muestra

INT64

Ejemplos

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)

Descripción

Muestra la longitud de la STRING en caracteres.

Tipo de datos que se muestra

INT64

Ejemplos

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)

Descripción

Sinónimo de CHAR_LENGTH.

Tipo de datos que se muestra

INT64

Ejemplos

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)

Descripción

Toma un arreglo de puntos de código ASCII extendidos (ARRAY de INT64) y muestra BYTES.

Para convertir BYTES en un arreglo de puntos de código, consulta TO_CODE_POINTS.

Tipo de datos que se muestra

BYTES

Ejemplos

El siguiente es un ejemplo básico que usa CODE_POINTS_TO_BYTES.

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

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

En el siguiente ejemplo, se usa un algoritmo de rotación por 13 lugares (ROT13) para codificar una string.

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;

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

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Descripción

Toma un arreglo de puntos de código (ARRAY de INT64) Unicode y muestra una STRING.

Para convertir una string en un arreglo de puntos de código, consulta TO_CODE_POINTS.

Tipo de datos que se muestra

STRING

Ejemplo

El siguiente es un ejemplo básico que usa CODE_POINTS_TO_STRING.

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

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

En el siguiente ejemplo, se calcula la frecuencia de las letras en un conjunto de palabras.

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[, ...])

Descripción

Concatena uno o más valores STRING o BYTE en un solo resultado.

La función muestra NULL si algún argumento de entrada es NULL.

Nota: También puedes usar el operador de concatenación || para concatenar valores en una string.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Toma dos valores. Muestra TRUE si el segundo valor es un sufijo del primero.

Tipo de datos que se muestra

BOOL

Ejemplos

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

SQL de Cloud Spanner admite una función FORMAT() para el formato de strings. Esta función es similar a la función printf de C. Produce una STRING a partir de una string de formato que contiene cero o más especificadores de formato, junto con una lista de longitud variable de argumentos adicionales que coincide con los especificadores de formato. Estos son algunos ejemplos:

Descripción	Statement	Resultado
Número entero simple	FORMAT("%d", 10)	10
Número entero con relleno en blanco a la izquierda	FORMAT("|%10d|", 11)	|           11|
Número entero con relleno de ceros a la izquierda	FORMAT("+%010d+", 12)	+0000000012+
Número entero con comas	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 función FORMAT() no proporciona un formato personalizable por completo para todos los tipos y valores, ni un formato sensible a la configuración regional.

Si el formato personalizado es necesario para un tipo, primero debes formatearlo con funciones de formato específicas del tipo, como FORMAT_DATE() o FORMAT_TIMESTAMP(). Por ejemplo:

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

Muestra

date: January 02, 2015!

Sintaxis

La sintaxis FORMAT() toma una string de formato y una lista de argumentos de longitud variable, y produce un resultado de STRING:

FORMAT(<format_string>, ...)

La expresión <format_string> puede contener cero o más especificadores de formato. Cada especificador de formato se ingresa mediante el símbolo % y debe asignarse a uno o más de los argumentos restantes. En general, esta es una asignación uno a uno, excepto cuando está presente el especificador *. Por ejemplo, %.*i se asigna a dos argumentos: uno de longitud y uno de número entero con signo. Si el número de argumentos relacionado con los especificadores de formato no es el mismo que el número de argumentos, se genera un error.

Especificadores de formato admitidos

El especificador de formato de función FORMAT() sigue este prototipo:

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

Los especificadores de formato admitidos se identifican en la siguiente tabla. Las desviaciones de printf() se identifican en cursiva.

Especificador	Descripción	Ejemplos	Tipos
d o i	Número entero decimal	392	INT64
o	Octal	610	INT64*
x	Número entero hexadecimal	7fa	INT64*
X	Número entero hexadecimal (mayúsculas)	7FA	INT64*
f	Notación decimal, en [-](parte de número entero).(parte fraccionaria) para valores finitos y en minúsculas para valores no finitos	392.650000 INF NAN	FLOAT64
F	Notación decimal, en [-](parte de número entero) (parte de fracciones) para valores finitos y en mayúsculas para valores no finitos	392.650000 INF NAN	FLOAT64
e	Notación científica (mantisa/exponente), minúsculas	3.926500e+02 INF NAN	FLOAT64
E	Notación científica (mantisa/exponente), mayúsculas	3.926500E+02 INF NAN	FLOAT64
g	Notación decimal o científica, según el exponente del valor de entrada y la precisión especificada. Minúscula. Consulta el comportamiento de %g y %G para obtener más detalles.	392.65 3.9265e+07 inf nan	FLOAT64
G	Notación decimal o científica, según el exponente del valor de entrada y la precisión especificada. Mayúscula. Consulta el comportamiento de %g y %G para obtener más detalles.	392.65 3.9265E+07 INF NAN	FLOAT64
s	String de caracteres	sample	STRING
t	Muestra una string imprimible que representa el valor. A menudo, se parece a convertir el tipo del argumento en STRING. Consulta el comportamiento de %t y %T.	sample 2014‑01‑01	<any>
T	Genera una string que es una constante SQL de Cloud Spanner válida con un tipo similar al tipo del valor (quizás más ancho o tal vez string). Consulta el comportamiento %t y %T.	'sample' b'bytes sample' 1234 2.3 date '2014‑01‑01'	<any>
%	“%%” genera un solo “%”	%	N/A

^* Los especificadores %o, %x y %X generan un error si se usan valores negativos.

El especificador de formato puede contener de forma opcional los subespecificadores identificados antes en el prototipo del especificador.

Estos subespecificadores deben cumplir con las siguientes especificaciones.

Marcas

Marcas	Descripción
-	Justificar a la izquierda dentro del ancho de campo dado; la justificación a la derecha es la predeterminada (ver subespecificador de ancho)
+	Obliga a anteponer un signo más o menos al resultado (+ o -) incluso para números positivos. De forma predeterminada, solo los números negativos van precedidos de un signo -
<space>	Si no se va a escribir ningún signo, se inserta un espacio en blanco antes del valor.
#	Para “%o”, “%x” y “%X”, esta marca significa que se debe anteponer 0, 0x o 0X a los valores distintos de cero, de forma respectiva. Para “%f”, “%F”, “%e” y “%E”, esta marca significa que se debe agregar el punto decimal, incluso cuando no hay una parte fraccionaria, a menos que el valor sea no finito. En el caso de “%g” y “%G”, esta marca significa que se debe agregar el punto decimal, incluso cuando no hay una parte fraccionaria, a menos que el valor sea no finito, y nunca quitar los ceros finales después del punto decimal.
0	Rellena a la izquierda del número con ceros (0) en lugar de espacios cuando se especifica el relleno (ver subespecificador de ancho).
'	Formatea números enteros con el carácter de agrupación apropiado. Por ejemplo: FORMAT("%'d", 12345678) muestra 12,345,678 FORMAT("%'x", 12345678) muestra bc:614e FORMAT("%'o", 55555) muestra 15,4403 Esta marca solo es relevante para valores decimales, hexadecimales y octales.

Las marcas se pueden especificar en cualquier orden. Las marcas duplicadas no son un error. Cuando las marcas no son relevantes para algún tipo de elemento, se ignoran.

Ancho

Ancho	Descripción
<number>	Número mínimo de caracteres que se deben imprimir. Si el valor que se debe imprimir es más corto que este número, el resultado se rellena con espacios en blanco. El valor no se trunca aunque el resultado sea mayor.
*	El ancho no se especifica en la string de formato, sino como un argumento de número entero adicional que precede al argumento que debe formatearse.

Precisión

Precisión	Descripción
.<number>	Para especificadores de números enteros “%d”, “%i”, “%o”, “%u”, “%x” y “%X”: la precisión especifica la cantidad mínima de dígitos que se escribirán. Si el valor que se debe escribir es más corto que este número, el resultado se rellena con ceros finales. El valor no se trunca aunque el resultado sea más largo. Una precisión de 0 significa que no se escribe ningún carácter para el valor 0. Para los especificadores “%a”, “%A”, “%e”, “%E”, “%f” y “%F”: esta es la cantidad de dígitos que se imprimirán después del punto decimal. El valor predeterminado es 6. Para los especificadores “%g” y “%G”: es la cantidad de dígitos significativos que se imprimirán antes de quitar los ceros finales después del punto decimal. El valor predeterminado es 6.
.*	La precisión no se especifica en la string de formato, sino como un argumento de número entero adicional que precede al argumento que debe formatearse.

Comportamiento de %g y %G

Los especificadores de formato %g y %G eligen la notación decimal (como los especificadores %f y %F) o la notación científica (como los especificadores %e y %E), según el exponente del valor de entrada y la precisión especificada.

Supongamos que p representa la precisión especificada (el valor predeterminado es 6; 1 si la precisión especificada es menor que 1). Primero el valor de entrada se convierte en notación científica con precisión = (p - 1). Si la parte x del exponente resultante es menor que -4 o no menor que p, se usa la notación científica con precisión = (p - 1); de lo contrario, se usa la notación decimal con precisión = (p - 1 - x).

A menos que esté presente la marca #, se quitan los ceros finales después del punto decimal y el punto decimal si no hay dígitos después de este.

Comportamiento de %t y %T

Los especificadores de formato %t y %T están definidos para todos los tipos. El ancho, la precisión y las marcas actúan como lo hacen en %s: el ancho es el ancho mínimo y la STRING se rellenará hasta alcanzar ese tamaño, mientras que la precisión es el ancho máximo de contenido para mostrar y la STRING se truncará a ese tamaño, antes del relleno para el ancho.

El especificador %t siempre debe ser una forma legible del valor.

El especificador %T siempre es un literal de SQL válido de un tipo similar, como un tipo numérico más amplio. El literal no incluirá conversiones de tipos o un nombre de tipo, excepto en el caso especial de valores de punto flotante no finitos.

La STRING está formateada de la siguiente manera:

Tipo	%t	%T
NULL de cualquier tipo	NULL	NULL
INT64	123	123
FLOAT64	123.0 (siempre con .0) 123e+10 inf -inf NaN	123.0 (siempre con .0) 123e+10 CAST("inf" AS <type>) CAST("-inf" AS <type>) CAST("nan" AS <type>)
STRING	valor de string sin comillas	literal de string entre comillas
BYTES	bytes escapados sin comillas , p. ej., abc\x01\x02	literal de bytes entre comillas , p. ej., 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	[value, value, …] ; aquí, los valores se formatean con %t	[value, value, …] ; aquí, los valores se formatean con %T

Condiciones de error

Si un especificador de formato no es válido o no es compatible con el tipo de argumento relacionado, o si se proporciona número o argumentos incorrectos, se genera un error. Por ejemplo, las siguientes expresiones <format_string> no son válidas:

FORMAT('%s', 1)

FORMAT('%')

Manejo de argumentos NULL

Una string de formato NULL da como resultado una STRING de salida NULL. Cualquier otro argumento se ignora en este caso.

Por lo general, la función produce un valor NULL si hay un argumento NULL presente. Por ejemplo, FORMAT('%i', <NULL expression>) produce una STRING NULL como resultado.

Sin embargo, existen algunas excepciones: si el especificador de formato es %t o %T (ambos producen STRINGs que coinciden de forma efectiva con la semántica de valores literales y CAST), un valor NULL produce “NULL” (sin comillas) en la STRING de resultado. Por ejemplo, la siguiente función:

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

Muestra

00-NULL-00

Reglas semánticas adicionales

Los valores de FLOAT64 pueden ser +/-inf o NaN. Cuando un argumento tiene uno de esos valores, el resultado de los especificadores de formato %f, %F, %e, %E, %g, %G y %t son inf, -inf o nan (o lo mismo en mayúsculas), según corresponda. Esto es coherente con la forma en que SQL de Cloud Spanner envía estos valores a STRING. En el caso de %T, SQL de Cloud Spanner SQL muestra strings entrecomilladas para los valores FLOAT64 que no tienen representaciones literales que no son de string.

FROM_BASE64

FROM_BASE64(string_expr)

Descripción

Convierte la entrada codificada en base64 string_expr en el formato BYTES. Para convertir BYTES a una STRING codificada en base64, usa TO_BASE64.

Tipo de datos que se muestra

BYTES

Ejemplo

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

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| 3q2+7w==  |
+-----------+

FROM_HEX

FROM_HEX(string)

Descripción

Convierte una STRING codificada en hexadecimal en el formato BYTES. Muestra un error si la STRING de entrada contiene caracteres fuera del rango (0..9, A..F, a..f). No importa si los caracteres están en mayúsculas o minúsculas. Si la STRING de entrada tiene un número impar de caracteres, la función actúa como si la entrada tuviera un 0 inicial adicional. Para convertir BYTES en una STRING con codificación hexadecimal, usa TO_HEX.

Tipo de datos que se muestra

BYTES

Ejemplo

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)

Descripción

Muestra la longitud del valor. El valor mostrado está en caracteres para los argumentos de STRING y en bytes para el argumento de BYTES.

Tipo de datos que se muestra

INT64

Ejemplos

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

Descripción

Muestra un valor que consta de original_value con pattern antepuesto. return_length es un INT64 que especifica la longitud del valor mostrado. Si original_value es BYTES, return_length es el número de bytes. Si original_value es STRING, return_length es el número de caracteres.

El valor predeterminado de pattern es un espacio en blanco.

original_value y pattern deben tener el mismo tipo de datos.

Si return_length es menor o igual que la longitud de original_value, esta función muestra el valor original_value, truncado al valor de return_length. Por ejemplo, LPAD("hello world", 7); muestra "hello w".

Si original_value, return_length o pattern es NULL, esta función muestra NULL.

Esta función muestra un error si se da una de estas condiciones:

• return_length es negativo.
• pattern está vacía.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Para los argumentos de STRING, muestra la string original con todos los caracteres alfabéticos en minúsculas. La asignación entre minúsculas y mayúsculas se realiza de acuerdo con la base de datos de caracteres Unicode, sin tener en cuenta las asignaciones específicas del lenguaje.

Para los argumentos de BYTES, el argumento se trata como texto ASCII, con todos los bytes mayores a 127 intactos.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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

Descripción

Es idéntico a TRIM, pero solo quita caracteres iniciales.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regexp)

Descripción

Muestra TRUE si value es una coincidencia parcial para la expresión regular, regexp.

Si el argumento regexp no es válido, la función muestra un error.

Puedes buscar una coincidencia completa con ^ (principio del texto) y $ (final del texto). Debido a la precedencia del operador de expresión regular, es una buena práctica encerrar entre paréntesis todo lo que está entre ^ y $.

Nota: SQL de Cloud Spanner proporciona compatibilidad con expresiones regulares mediante la biblioteca re2; consulta esa documentación para conocer su sintaxis de expresión regular.

Tipo de datos que se muestra

BOOL

Ejemplos

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

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

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

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

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regexp)

Descripción

Muestra la primera substring de value que coincide con la expresión regular, regexp. Muestra NULL si no hay coincidencia.

Si la expresión regular contiene un grupo de captura, la función muestra la substring que coincide con él. Si la expresión no contiene un grupo de captura, la función muestra toda la substring coincidente.

Muestra un error si se da una de estas condiciones:

• La expresión regular no es válida.
• La expresión regular tiene más de un grupo de captura.

Nota: SQL de Cloud Spanner proporciona compatibilidad con expresiones regulares mediante la biblioteca re2; consulta esa documentación para conocer su sintaxis de expresión regular.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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

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

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

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

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

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

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regexp)

Descripción

Muestra un arreglo de todas las substrings de value que coinciden con la expresión regular, regexp.

La función REGEXP_EXTRACT_ALL solo muestra coincidencias no superpuestas. Por ejemplo, usar esta función para extraer ana de banana muestra solo una substring, no dos.

Nota: SQL de Cloud Spanner proporciona compatibilidad con expresiones regulares mediante la biblioteca re2; consulta esa documentación para conocer su sintaxis de expresión regular.

Tipo de datos que se muestra

Un ARRAY de STRING o BYTES

Ejemplos

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)

Descripción

Muestra una STRING en la que todas las substrings de value que coinciden con la expresión regular regexp se reemplazan por replacement.

Puedes usar dígitos con escape de barras invertidas (de \1 a \9) dentro del argumento replacement para insertar texto que coincida con el grupo entre paréntesis correspondiente en el patrón regexp. Usa \0 para hacer referencia a todo el texto coincidente.

Nota: Para agregar una barra invertida a tu expresión regular, primero debes escaparla. Por ejemplo, SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1"); muestra aXc.

La función REGEXP_REPLACE solo reemplaza las coincidencias no superpuestas. Por ejemplo, si se reemplaza ana dentro de banana, ocurre un solo reemplazo, no dos.

Si el argumento regexp no es una expresión regular válida, esta función muestra un error.

Nota: SQL de Cloud Spanner proporciona compatibilidad con expresiones regulares mediante la biblioteca re2; consulta esa documentación para conocer su sintaxis de expresión regular.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Reemplaza todos los casos de from_value por to_value en original_value. Si from_value está vacío, no se realiza ningún reemplazo.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Muestra un valor que consta de original_value, repetido. El parámetro repetitions especifica la cantidad de veces que se debe repetir original_value. Muestra NULL si original_value o repetitions son NULL.

Esta función muestra un error si el valor de repetitions es negativo.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Muestra la inversa de la STRING o BYTES de entrada.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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

Descripción

Muestra un valor que consta de original_value con pattern agregado. return_length es un INT64 que especifica la longitud del valor mostrado. Si original_value es BYTES, return_length es el número de bytes. Si original_value es STRING, return_length es el número de caracteres.

El valor predeterminado de pattern es un espacio en blanco.

original_value y pattern deben tener el mismo tipo de datos.

Si return_length es menor o igual que la longitud de original_value, esta función muestra el valor original_value, truncado al valor de return_length. Por ejemplo, RPAD("hello world", 7); muestra "hello w".

Si original_value, return_length o pattern es NULL, esta función muestra NULL.

Esta función muestra un error si se da una de estas condiciones:

• return_length es negativo.
• pattern está vacía.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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

Descripción

Es idéntico a TRIM, pero solo quita caracteres finales.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Convierte una secuencia de bytes en una string. Los caracteres UTF-8 no válidos se reemplazan por el carácter de reemplazo de Unicode, U+FFFD.

Tipo de datos que se muestra

STRING

Ejemplos

La siguiente instrucción muestra el carácter de reemplazo de Unicode, �.

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

DIVIDIR

SPLIT(value[, delimiter])

Descripción

Divide value mediante el argumento delimiter.

Para STRING, el delimitador predeterminado es la coma ,.

Para BYTES, debes especificar un delimitador.

La división en un delimitador vacío produce un arreglo de caracteres UTF-8 para los valores de STRING y un arreglo de BYTES para los valores de BYTES.

Dividir una STRING vacía muestra un ARRAY con una sola STRING vacía.

Tipo de datos que se muestra

ARRAY de tipo STRING o ARRAY de tipo BYTES

Ejemplos

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)

Descripción

Toma dos valores. Muestra TRUE si el segundo valor es un prefijo del primero.

Tipo de datos que se muestra

BOOL

Ejemplos

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

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

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

STRPOS

STRPOS(string, substring)

Descripción

Muestra el índice basado en 1 del primer caso de substring dentro de string. Muestra 0 si no se encuentra substring.

Tipo de datos que se muestra

INT64

Ejemplos

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

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

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

SUBSTR

SUBSTR(value, position[, length])

Descripción

Muestra una substring del valor proporcionado. El argumento position es un número entero que especifica la posición inicial de la substring, en la que position = 1 indica el primer carácter o byte. El argumento length es la cantidad máxima de caracteres para los argumentos de STRING, o de bytes para los argumentos de BYTES.

Si position es negativo, la función cuenta desde el final de value, y -1 indica el último carácter.

Si position es una posición más allá del extremo izquierdo de la STRING (position = 0 o position < -LENGTH(value)), la función comienza desde position = 1. Si length excede la longitud de value, muestra menos de length caracteres.

Si length es menor que 0, la función muestra un error.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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_BASE64

TO_BASE64(bytes_expr)

Descripción

Convierte una secuencia de BYTES en una STRING codificada en base64. Para convertir una STRING codificada en base64 en BYTES, usa FROM_BASE64.

Tipo de datos que se muestra

STRING

Ejemplo

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

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

TO_CODE_POINTS

TO_CODE_POINTS(value)

Descripción

Toma un valor y muestra un arreglo de INT64.

• Si value es una STRING, cada elemento del arreglo que se muestra representa un punto de código. Cada punto de código está dentro del rango de [0, 0xD7FF] y [0xE000, 0x10FFFF].
• Si value es BYTES, cada elemento del arreglo es un valor de caracteres ASCII extendido en el rango de [0, 255].

Para convertir un arreglo de puntos de código en STRING o BYTES, consulta CODE_POINTS_TO_STRING o CODE_POINTS_TO_BYTES.

Tipo de datos que se muestra

ARRAY de INT64

Ejemplos

En el siguiente ejemplo, se obtienen los puntos de código para cada elemento de un arreglo de palabras.

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

En el siguiente ejemplo, se convierten representaciones de números enteros de BYTES en sus valores de caracteres ASCII correspondientes.

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

En el siguiente ejemplo, se muestra la diferencia entre un resultado de BYTES y un resultado de STRING.

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

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

Observa que el carácter, Ā, se representa como una secuencia Unicode de dos bytes. Como resultado, la versión BYTES de TO_CODE_POINTS muestra un arreglo con dos elementos, mientras que la versión STRING muestra un arreglo con un solo elemento.

TO_HEX

TO_HEX(bytes)

Descripción

Convierte una secuencia de BYTES en una STRING hexadecimal. Convierte cada byte de la STRING en dos caracteres hexadecimales dentro del rango (0..9, a..f). Para convertir una STRING con codificación hexadecimal en BYTES, usa FROM_HEX.

Tipo de datos que se muestra

STRING

Ejemplo

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

Descripción

Quita todos los caracteres iniciales y finales que coinciden con value2. Si no se especifica value2, se quitan todos los caracteres de espacio en blanco iniciales y finales (como se define en el estándar Unicode). Si el primer argumento es de tipo BYTES, el segundo argumento es obligatorio.

Si value2 contiene más de un carácter o byte, la función quita todos los caracteres o bytes iniciales o finales contenidos en value2.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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)

Descripción

Para los argumentos de STRING, muestra la string original con todos los caracteres alfabéticos en mayúsculas. La asignación entre mayúsculas y minúsculas se realiza de acuerdo con la base de datos de caracteres Unicode, sin tener en cuenta las asignaciones específicas del lenguaje.

Para los argumentos de BYTES, el argumento se trata como texto ASCII, con todos los bytes mayores a 127 intactos.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos

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