Expresiones, funciones y operadores

Esta página explica las expresiones Cloud Spanner SQL, incluidas las funciones y los operadores.

Reglas de llamada de funciones

Las siguientes reglas se aplican a todas las funciones a menos que se indique explícitamente lo contrario en la descripción de la función:

  • Para las funciones que aceptan tipos numéricos, si un operando es un operando de coma flotante y el otro operando es otro tipo numérico, ambos operandos se convierten a FLOAT64 antes de que se evalúe la función.
  • Si un operando es NULL, el resultado es NULL, con la excepción del operador IS.

  • Para las funciones que varían según la zona horaria (como se indica en la descripción de la función), se utiliza la zona horaria predeterminada, America/Los_Angeles, si no se especifica ninguna.

Reglas de conversión

El concepto "conversión" incluye, sin limitarse a estos conceptos, la transformación y la coerción.

  • La transformación es la conversión explícita y utiliza la función CAST().
  • La coerción es la conversión implícita, que Cloud Spanner SQL realiza automáticamente en las condiciones que se describen a continuación.
  • Hay un tercer grupo de funciones de conversión que tienen sus propios nombres de funciones, como UNIX_DATE().

La siguiente tabla resume todas las alternativas de CAST y coerción posibles para los tipos de datos Cloud Spanner SQL. "Coerción a" se aplica a todas las expresiones de un tipo de datos determinado (p. ej., una columna).

De tipo TRANSFORMACIÓN a Coerción a
INT64 BOOL
FLOAT64
INT64
STRING
FLOAT64
FLOAT64 FLOAT64
INT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
BYTES
DATE
FLOAT64
INT64
STRING
TIMESTAMP
 
BYTES BYTES
STRING
 
DATE DATE
STRING
TIMESTAMP
 
TIMESTAMP DATE
STRING
TIMESTAMP
 
ARRAY ARRAY  
STRUCT STRUCT  

Transformación

Sintaxis:

CAST(expr AS typename)

La sintaxis de transformación se utiliza en una consulta para indicar que el tipo de resultado de una expresión se debe convertir a algún otro tipo.

Ejemplo:

CAST(x=1 AS STRING)

Esto genera como resultado "true" si x es 1, "false" para cualquier otro valor diferente de NULL y NULL si x es NULL.

Las transformaciones entre los tipos admitidos que no se asignan correctamente desde el valor original al dominio de destino dan lugar a errores de tiempo de ejecución. Por ejemplo, la transformación de BYTES a STRING, donde la secuencia de bytes no tiene una codificación UTF-8 válida, genera un error de tiempo de ejecución.

Al transformar una expresión x de los siguientes tipos, se aplican estas reglas:

De A Reglas al transformar x
INT64 FLOAT64 Devuelve un valor cercano pero posiblemente no exacto de FLOAT64.
INT64 BOOL Devuelve FALSE si x es 0, de lo contrario devuelve TRUE.
FLOAT64 INT64 Devuelve el valor INT64 más cercano.
Casos de valores medios como 1,5 o -0,5 se redondean a valores alejados de cero.
FLOAT64 STRING Devuelve una representación de cadena aproximada.
BOOL INT64 Devuelve 1 si x es TRUE, de lo contrario devuelve 0.
BOOL STRING Devuelve "true" si x es TRUE, de lo contrario devuelve "false".
STRING FLOAT64 Devuelve x como un valor FLOAT64 y lo interpreta como que tuviera la misma forma que un FLOAT64 literal válido.
También admite transformaciones de "inf", "+inf", "-inf" y "nan".
Las conversiones no distinguen entre mayúsculas y minúsculas.
STRING BOOL Devuelve TRUE si x es "true" y FALSE si x es "false".
Ninguno de los demás valores de x son válidos y todos generan un error en vez de la transformación a BOOL.
STRING no distingue entre mayúsculas y minúsculas al convertir a BOOL.
STRING BYTES Las STRING se transforman en BYTES con la codificación UTF-8. Por ejemplo, la STRING "©", al transformarse en BYTES, se convertiría en una secuencia de 2 bytes con los valores hexadecimales C2 y A9.
BYTES STRING Devuelve x que se interpreta como STRING UTF-8.
Por ejemplo, el b'\xc2\xa9' literal de BYTES, cuando se transforma en STRING, se interpreta como UTF-8 y se convierte en el carácter Unicode "©".
Se produce un error si x no tiene una codificación UTF-8 válida.
ARRAY ARRAY Debe ser exactamente el mismo tipo de ARRAY.
STRUCT STRUCT Permitido si se cumplen las siguientes condiciones:
  1. Los dos STRUCT tienen el mismo número de campos.
  2. Los tipos de campo STRUCT originales se pueden transformar explícitamente en los tipos de campo STRUCT objetivo correspondientes (tal como se define por orden de campo, no por nombre de campo).

Transformar cadenas hexadecimales en enteros

Si se trabaja con cadenas hexadecimales (0x123), puedes transformarlas en enteros:

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

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

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

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

Transformar tipos de fechas

Cloud Spanner SQL es compatible con la transformación de tipos de fecha a cadenas (o de cadenas) de la siguiente manera:

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

La transformación de un tipo de fecha a una cadena no depende de la zona horaria y tiene el formato YYYY-MM-DD. Al realizar la transformación de cadenas a fechas, la cadena debe ajustarse al formato literal de fecha admitido y no depende de la zona horaria. Si la expresión de cadena no es válida o representa una fecha que está fuera del intervalo mínimo o máximo admitido, se produce un error.

Tipos de marca de tiempo de transformación

Cloud Spanner SQL admite los tipos de marcas de tiempo de transformación a cadenas o de ellas, de la siguiente manera:

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

Al transformar los tipos de marcas de tiempo en cadenas, la marca de tiempo se interpreta mediante la zona horaria predeterminada, America/Los_Angeles. El número de dígitos de subsegundos producidos depende del número de ceros a la derecha en la parte del segundo: la función CAST truncará en cero, tres o seis dígitos.

Al transformar una cadena en una marca de tiempo, string_expression debe ajustarse a los formatos literales de marcas de tiempo compatibles; de lo contrario, se produce un error de tiempo de ejecución. La propia string_expression puede contener un time_zone, consulta los husos horarios. Si hay una zona horaria en string_expression, se usa esa zona horaria para la conversión; de lo contrario, se utiliza la zona horaria predeterminada, America/Los_Angeles. Si la cadena tiene menos de seis dígitos, entonces se amplía implícitamente.

Se produce un error si la string_expression no es válida, tiene más de seis dígitos de subsegundos (es decir, precisión superior a microsegundos) o representa un tiempo fuera del intervalo de marca de tiempo compatible.

Realizar transformaciones entre los tipos de fecha y marca de tiempo

Cloud Spanner SQL admite la transformación entre los tipos de fecha y marca de tiempo de la siguiente manera:

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

Transformación de una fecha a una marca de tiempo interpreta date_expression a partir de la medianoche (inicio del día) en la zona horaria predeterminada, America/Los_Angeles. La transformación de una marca de tiempo a la fecha trunca de manera eficaz la marca de tiempo a partir de la zona horaria predeterminada.

Coerción

Cloud Spanner SQL fuerza el tipo de resultado de una expresión a otro tipo si se necesita para hacer coincidir las firmas de la función. Por ejemplo, si la función func() se define para tomar un solo argumento de tipo INT64 y se usa una expresión como un argumento que tiene un tipo de resultado de FLOAT64, el resultado de la expresión se convertirá en el tipo INT64 antes de que func() se compute.

Otras funciones de conversión

Cloud Spanner SQL proporciona las siguientes funciones de conversión:

Funciones de agregación

Una función de agregación es una función que realiza un cálculo en un conjunto de valores. COUNT, MIN y MAX son ejemplos de funciones de agregación.

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

En las siguientes secciones, se describen las funciones de agregación que admite Cloud Spanner SQL.

ANY_VALUE

ANY_VALUE(expression)

Descripción

Devuelve cualquier valor de la entrada o NULL si no hay filas de entrada. Devuelve NULL si la expression se evalúa como NULL para todas las filas y, de lo contrario, como valor diferente de NULL. El valor devuelto no es determinista, lo que significa que se puede recibir un resultado diferente cada vez que se utiliza esta función.

Tipos de argumentos admitidos

Cualquiera

Tipos de datos que se devuelven

Coincide con el tipo de datos de entrada.

Ejemplos

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

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

ARRAY_AGG

ARRAY_AGG(expression)

Descripción

Devuelve un ARRAY de valores de expression.

Tipos de argumentos admitidos

Todos los tipos de datos excepto ARRAY.

Orden de los elementos en el resultado

El orden de los elementos en el resultado no es determinista, lo que significa que se puede obtener un resultado diferente cada vez que se utiliza esta función.

Tipos de datos que se devuelven

ARRAY

Si no hay filas de entrada, esta función devuelve NULL.

Ejemplos

SELECT ARRAY_AGG(x) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

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

AVG

AVG(expression)

Descripción

Devuelve el promedio de valores de entrada diferentes de NULL, o NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de entrada numérica, como INT64. Ten en cuenta que, para los tipos de entrada de coma flotante, el resultado que se devuelve no es determinista, lo que significa que se puede recibir un resultado diferente cada vez que se utilice esta función.

Tipos de datos que se devuelven

FLOAT64

Ejemplos

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

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

BIT_AND

BIT_AND(expression)

Descripción

Realiza una operación AND bit a bit en la expression y devuelve el resultado.

Tipos de argumentos admitidos

INT64

Tipos de datos que se devuelven

INT64

Ejemplos

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

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

BIT_OR

BIT_OR(expression)

Descripción

Realiza una operación OR bit a bit en la expression y devuelve el resultado.

Tipos de argumentos admitidos

INT64

Tipos de datos que se devuelven

INT64

Ejemplos

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

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

BIT_XOR

BIT_XOR(expression)

Descripción

Realiza una operación XOR bit a bit en la expression y devuelve el resultado.

Tipos de argumentos admitidos

INT64

Tipos de datos que se devuelven

INT64

Ejemplos

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

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

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

COUNT

1.

COUNT(*)

2.

COUNT(expression)

Descripción

  1. Devuelve el número de filas en la entrada.
  2. Devuelve el número de filas con la expression evaluada como cualquier valor diferente de NULL.

Tipos de argumentos admitidos

La expression puede ser de cualquier tipo de datos.

Tipos de datos que se devuelven

INT64

Ejemplos

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

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

LOGICAL_AND

LOGICAL_AND(expression)

Descripción

Devuelve el AND lógico de todas las expresiones diferentes de NULL. Devuelve NULL si no hay filas de entrada o la expression evalúa como NULL para todas las filas.

Tipos de argumentos admitidos

BOOL

Tipos de datos que se devuelven

BOOL

Ejemplos

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

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

LOGICAL_OR

LOGICAL_OR(expression)

Descripción

Devuelve el OR lógico de todas las expresiones diferentes de NULL. Devuelve NULL si no hay filas de entrada o la expression evalúa como NULL para todas las filas.

Tipos de argumentos admitidos

BOOL

Tipos de datos que se devuelven

BOOL

Ejemplos

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

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

MAX

MAX(expression)

Descripción

Devuelve el valor máximo de expresiones diferentes de NULL. Devuelve NULL si no hay filas de entrada o la expression evalúa como NULL para todas las filas. Devuelve NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de datos excepto: STRUCT ARRAY

Tipos de datos que se devuelven

Igual que el tipo de datos utilizado como valores de entrada.

Ejemplos

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

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

MIN

MIN(expression)

Descripción

Devuelve el valor mínimo de las expresiones diferentes de NULL. Devuelve NULL si no hay filas de entrada o la expression evalúa como NULL para todas las filas. Devuelve NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de datos excepto: STRUCT ARRAY

Tipos de datos que se devuelven

Igual que el tipo de datos utilizado como valores de entrada.

Ejemplos

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

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

STRING_AGG

STRING_AGG(expression [, delimiter])

Descripción

Devuelve un valor (STRING o BYTES) que se obtiene mediante la concatenación de valores diferentes de cero.

Si se especifica un delimiter, dicho delimitador separa los valores concatenados, de lo contrario, se usa una coma como delimitador.

Tipos de argumentos admitidos

STRING BYTES

Orden de los elementos en el resultado

El orden de los elementos en el resultado no es determinista, lo que significa que se puede obtener un resultado diferente cada vez que se utiliza esta función.

Tipos de datos que se devuelven

STRING BYTES

Ejemplos

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

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

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

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

SUM

SUM(expression)

Descripción

Devuelve la suma de valores no nulos.

Si la expresión es un valor de coma flotante, la suma no es determinista, lo que significa que se puede recibir un resultado diferente cada vez que se utilice esta función.

Tipos de argumentos admitidos

Cualquier tipo de datos numéricos compatible.

Tipos de datos que se devuelven

Devuelve INT64 si la entrada es un entero.

Devuelve FLOAT64 si la entrada es un valor de coma flotante.

Devuelve NULL si la entrada contiene solo valores NULL.

Devuelve Inf si la entrada contiene Inf.

Devuelve -Inf si la entrada contiene -Inf.

Devuelve NaN si la entrada contiene un NaN.

Devuelve NaN si la entrada contiene una combinación de Inf e -Inf.

Ejemplos

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

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

Funciones matemáticas

Funciones matemáticas:

  • Devuelve NULL si alguno de los parámetros de entrada es NULL.
  • Devuelve NaN si alguno de los argumentos es NaN.
Función Descripción
ABS(X) Calcula el valor absoluto. Con un argumento entero, genera un error si el valor no se puede representar como el mismo tipo (lo que ocurre solo para el valor de entrada negativo más grande, que no tiene representación positiva). Devuelve +inf para el argumento +/-inf.
SIGN(X) Devuelve -1, 0 o +1 para un argumento negativo, cero y positivo, respectivamente. Con el argumento de coma flotante no se distingue el cero positivo y negativo. Devuelve NaN para el argumento NaN.
IS_INF(X) Devuelve TRUE si el valor es infinito positivo o negativo. Devuelve NULL para entradas NULL.
IS_NAN(X) Devuelve TRUE si el valor es un valor NaN. Devuelve NULL para entradas NULL.
IEEE_DIVIDE(X, Y)

Divide X por Y. Nunca falla. Devuelve FLOAT64. A diferencia del operador de división (/), no genera errores para la división entre cero o desbordamiento.

Casos especiales:

  • Si el resultado se desborda, devuelve +/-inf.
  • Si Y = 0 y X = 0, devuelve NaN.
  • Si Y=0 y X!=0, devuelve +/-inf.
  • Si X =+/-inf e Y =+/-inf, devuelve NaN.
El comportamiento de IEEE_DIVIDE se ilustra con más detalle en la tabla a continuación.
SQRT(X) Calcula la raíz cuadrada de X. Genera un error si X es menor que 0. Devuelve +inf si X es +inf.
POW(X, Y) Función de potencia: devuelve el valor de X elevado a la potencia de Y. Si el resultado se subdesborda y no se puede representar, se devuelve el valor cero. Se puede generar un error si uno de los siguientes puntos es verdadero: X es un valor finito menor que 0 e Y no es entero, si X es 0 e Y es un valor finito menor que 0, el resultado se desborda. El comportamiento de POW() se ilustra con más detalle en la tabla siguiente.
POWER(X, Y) Sinónimo de POW(). El comportamiento de POWER() se ilustra con más detalle en la tabla siguiente.
EXP(X) Calcula la función exponencial natural ex. Si el resultado se subdesborda, se devuelve un cero. Genera un error si el resultado se desborda. Si X es +/-inf, entonces se devuelve +inf (o 0).
LN(X) Calcula el logaritmo natural de X. Genera un error si X es menor o igual a cero. Si X es +inf, entonces se devuelve +inf.
LOG(X) Sinónimo de LN(X).
LOG(X, Y) Calcula el logaritmo de X a la base Y. Genera un error si: X es menor o igual a cero, Y es 1,0, Y es menor o igual a cero.El comportamiento de LOG(X, Y) se ilustra con más detalle en la tabla a continuación.
LOG10(X) Similar a LOG(X) pero calcula el logaritmo con base 10.
GREATEST(X1,...,XN) Devuelve NULL si alguna de las entradas es NULL. De lo contrario, devuelve NaN si alguna de las entradas es NaN. De lo contrario, devuelve el valor más grande entre X1,...,XN según la comparación <.
LEAST(X1,...,XN) Devuelve NULL si alguna de las entradas es NULL. De lo contrario, devuelve NaN si alguna de las entradas es NaN. De lo contrario, devuelve el valor más pequeño entre X1,...,XN según la comparación >.
DIV(X, Y) Devuelve el resultado de la división de enteros de X entre Y. La división entre cero devuelve un error. La división entre -1 puede desbordarse. Para obtener posibles tipos de resultados, consulta la tabla a continuación.
MOD(X, Y) Función de módulo: devuelve el resto de la división de X entre Y. El valor devuelto tiene el mismo signo que X. Si Y es igual a 0 se genera un error. Para obtener posibles tipos de resultados, consulta la tabla a continuación.

Casos especiales de IEEE_DIVIDE(X, Y)

La siguiente tabla muestra casos especiales de IEEE_DIVIDE(X,Y).

Tipo de datos del numerador (X) Tipo de datos del denominador (Y) Valor del resultado
Todo menos 0 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

Casos especiales de POW(X, Y) y POWER(X, Y)

Los siguientes son casos especiales de POW(X, Y) y POWER(X, Y).

X Y POW(X, Y) o POWER(X, Y)
1,0 Cualquier valor incluido NaN 1,0
Cualquier valor incluido NaN 0 1,0
-1,0 +/-inf 1,0
ABS(X) < 1 -inf +inf
ABS(X) > 1 -inf 0
ABS(X) < 1 +inf 0
ABS(X) > 1 +inf +inf
-inf Y < 0 0
-inf Y > 0 -inf si Y es un entero impar, de lo contrario +inf
+inf Y < 0 0
+inf Y > 0 +inf

Casos especiales de LOG(X, Y)

X Y LOG(X, Y)
-inf Cualquier valor NaN
Cualquier valor +inf NaN
+inf 0,0 Y < 1,0 -inf
+inf Y > 1,0 +inf

Funciones de redondeo

Sintaxis Descripción
ROUND(X) Redondea X al entero más cercano. Los casos de valores medios se redondean a valores alejados de cero.
ROUND(X, N) Redondea X a N lugares decimales después de la coma decimal. N puede ser negativo, por lo que los dígitos se redondearán a la izquierda de la coma decimal. Los casos de valores medios se redondean a valores alejados de cero. Genera un error si se produce un desbordamiento.
TRUNC(X) Redondea X al entero más cercano cuyo valor absoluto no es mayor que X.
TRUNC(X, N) Similar a ROUND(X, N) pero siempre redondea hacia cero. A diferencia de ROUND(X, N) nunca se desborda.
CEIL(X) Devuelve el valor integral más pequeño (con el tipo FLOAT64) que no es inferior a X.
CEILING(X) Sinónimo de CEIL(X).
FLOOR(X) Devuelve el valor integral más grande (con el tipo FLOAT64) que no es mayor que X.

Comportamiento de ejemplo de las funciones de redondeo Cloud Spanner SQL:

"X" de entrada ROUND(X) TRUNC(X) CEIL(X) FLOOR(X)
2,0 2,0 2,0 2,0 2,0
2,3 2,0 2,0 3,0 2,0
2,8 3,0 2,0 3,0 2,0
2,5 3,0 2,0 3,0 2,0
-2,3 -2,0 -2,0 -2,0 -3,0
-2,8 -3,0 -2,0 -2,0 -3,0
-2,5 -3,0 -2,0 -2,0 -3,0
0 0 0 0 0
+/-inf +/-inf +/-inf +/-inf +/-inf
NaN NaN NaN NaN NaN

Funciones trigonométricas e hiperbólicas

Sintaxis Descripción
COS(X) Calcula el coseno de X. Nunca falla.
COSH(X) Calcula el coseno hiperbólico de X. Se produce un error si ocurre un desbordamiento.
ACOS(X) Calcula el valor principal del arcocoseno de X. El valor que se devuelve está en el intervalo [0,]. Se produce un error si X es un valor finito fuera del intervalo [-1, 1].
ACOSH(X) Calcula el coseno hiperbólico inverso de X. Se produce un error si X es un valor finito menor que 1.
SIN(X) Calcula el seno de X. Nunca falla.
SINH(X) Calcula el seno hiperbólico de X. Se produce un error si ocurre un desbordamiento.
ASIN(X) Calcula el valor principal del arcoseno de X. El valor que se devuelve está en el intervalo [-π/2, π/2]. Se produce un error si X es un valor finito fuera del intervalo [-1, 1].
ASINH(X) Calcula el seno hiperbólico inverso de X. No falla.
TAN(X) Calcula la tangente de X. Se produce un error si ocurre un desbordamiento.
TANH(X) Calcula la tangente hiperbólica de X. No falla.
ATAN(X) Calcula el valor principal de la arcotangente de X. El valor que se devuelve está en el intervalo [-π/2, π/2]. No falla.
ATANH(X) Calcula la tangente hiperbólica inversa de X. Se produce un error si el valor absoluto de X es mayor o igual a 1.
ATAN2(Y, X) Calcula el valor principal de la arcotangente de Y/X y usa los signos de los dos argumentos para determinar el cuadrante. El valor que se devuelve está en el intervalo [-π, π]. El comportamiento de esta función se ilustra con más detalle en la tabla a continuación.

Casos especiales de ATAN2()

Y X ATAN2(Y, X)
NaN Cualquier valor NaN
Cualquier valor NaN NaN
0 0 0, π o -π dependiendo del signo de X e Y
Valor finito -inf π o -π dependiendo del signo de Y
Valor finito +inf 0
+/-inf Valor finito π/2 o -π/2 dependiendo del signo de Y
+/-inf -inf ¾π o -¾π dependiendo del signo de Y
+/-inf +inf π/4 o -π/4 dependiendo del signo de Y

Casos especiales para funciones de redondeo trigonométricas e hiperbólicas

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

Funciones de cadena

Estas funciones de cadena se ejecutan en dos valores diferentes: STRING y BYTES. Los valores STRING deben tener codificación UTF-8 correcta.

Las funciones que devuelven 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. Al trabajar en tipos STRING, las posiciones que se devuelven se refieren a las posiciones de los caracteres.

Todas las comparaciones de cadenas se realizan byte por byte, independientemente de la equivalencia canónica Unicode.

BYTE_LENGTH

BYTE_LENGTH(value)

Descripción

Devuelve la longitud del valor en bytes, independientemente de si el tipo del valor es STRING o BYTES.

Tipo de devolución

INT64

Ejemplos

Table example:

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

Devuelve la longitud de STRING en caracteres.

Tipo de devolución

INT64

Ejemplos

Table example:

+----------------+
| 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 devolución

INT64

Ejemplos

Table example:

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

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

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

CONCAT

CONCAT(value1[, ...])

Descripción

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

Tipo de devolución

STRING o BYTES

Ejemplos

Table Employees:

+-------------+-----------+
| first_name  | last_name |
+-------------+-----------+
| John        | Doe       |
| Jane        | Smith     |
| Joe         | Jackson   |
+-------------+-----------+

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. Devuelve TRUE si el segundo valor es un sufijo del primero.

Tipo de devolución

BOOL

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
| apple          |
| banana         |
| orange         |
+----------------+

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

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

LENGTH

LENGTH(value)

Descripción

Devuelve la longitud del valor. El valor que se devuelve está en caracteres para los argumentos STRING y en bytes para el argumento BYTES.

Tipo de devolución

INT64

Ejemplos

Table example:

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

LOWER

LOWER(value)

Descripción

Para los argumentos STRING, devuelve la cadena 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 idioma.

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

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
| FOO            |
| BAR            |
| BAZ            |
+----------------+

SELECT
  LOWER(item) AS example
FROM items;

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

LTRIM

LTRIM(value1[, value2])

Descripción

Idéntico a TRIM, pero solo elimina los caracteres principales.

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
|    apple       |
|    banana      |
|    orange      |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| ***apple***    |
| ***banana***   |
| ***orange***   |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| xxxapplexxx    |
| yyybananayyy   |
| zzzorangezzz   |
| xyzpearzyz     |
+----------------+

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

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

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regex)

Descripción

Devuelve TRUE si value es una coincidencia parcial para la expresión regular, regex. Utiliza ^ (al principio del texto) y $ (al final del texto) para buscar una coincidencia completa.

Si el argumento de regex no es válido, la función devuelve un error.

Nota: Cloud Spanner SQL usa la biblioteca re2 para proporcionar asistencia de expresiones regulares. Si quieres obtener información sobre la sintaxis de las expresiones regulares, consulta la documentación correspondiente.

Tipo de devolución

BOOL

Ejemplos

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 $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")
    AS valid_email_address
FROM
  (SELECT
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

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

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

Descripción

Devuelve la primera subcadena en value que coincide con la expresión regular, regex. Devuelve NULL si no hay coincidencia.

Si la expresión regular contiene un grupo de captura, la función devuelve la subcadena que coincide con ese grupo de captura. Si la expresión no contiene un grupo de captura, la función devuelve toda la subcadena que coincida.

Devuelve un error si:

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

Nota: Cloud Spanner SQL usa la biblioteca re2 para proporcionar asistencia de expresiones regulares. Si quieres obtener información sobre la sintaxis de las expresiones regulares, consulta la documentación correspondiente.

Tipo de devolución

STRING o BYTES

Ejemplos

Table email_addresses:

+-------------------------+
| email                   |
+-------------------------+
| foo@example.com         |
| bar@example.com         |
| baz@example.com         |
+-------------------------+

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

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

Table email_addresses:

+-------------------------+
| email                   |
+-------------------------+
| foo@example.com         |
| bar@example.com         |
| baz@example.com         |
+-------------------------+

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

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

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regex)

Descripción

Devuelve una matriz de todas las subcadenas de value que coinciden con la expresión regular, regex.

La función REGEXP_EXTRACT_ALL solo devuelve coincidencias que no se superponen. Por ejemplo, si se usa esta función para extraer ana de banana, se devolverá solo una subcadena, no dos.

Nota: Cloud Spanner SQL usa la biblioteca re2 para proporcionar asistencia de expresiones regulares. Si quieres obtener información sobre la sintaxis de las expresiones regulares, consulta la documentación correspondiente.

Tipo de devolución

Un ARRAY de STRING o BYTES

Ejemplos

Table code_markdown:

+------------------------------------+
| code                               |
+------------------------------------+
| Try `function(x)` or `function(y)` |
+------------------------------------+

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

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

REGEXP_REPLACE

REGEXP_REPLACE(value, regex, replacement)

Descripción

Devuelve un STRING donde todas las subcadenas de value que coinciden con la expresión regular regex se sustituyen por replacement.

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

Nota: Para agregar una barra invertida en la expresión regular, primero debe aplicársele un carácter de escape. Por ejemplo, SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1"); devuelve aXc.

La función REGEXP_REPLACE solo sustituye las coincidencias que no se superponen. Por ejemplo, la sustitución de ana en banana genera como resultado una sola sustitución, no dos.

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

Nota: Cloud Spanner SQL usa la biblioteca re2 para proporcionar asistencia de expresiones regulares. Si quieres obtener información sobre la sintaxis de las expresiones regulares, consulta la documentación correspondiente.

Tipo de devolución

STRING o BYTES

Ejemplos

Table markdown:

+-------------------------+
| heading                 |
+-------------------------+
| # Heading               |
| # Another 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

Sustituye todas las repeticiones de from_value con to_value en original_value. Si from_value está vacío, no se realiza ninguna sustitución.

Tipo de devolución

STRING o BYTES

Ejemplos

+--------------------+
| dessert            |
+--------------------+
| apple pie          |
| blackberry pie     |
| cherry pie         |
+--------------------+

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

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

RTRIM

RTRIM(value1[, value2])

Descripción

Idéntico a TRIM, pero solo elimina los caracteres finales.

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
| ***apple***    |
| ***banana***   |
| ***orange***   |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| applexxx       |
| bananayyy      |
| orangezzz      |
| pearxyz        |
+----------------+

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

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

STARTS_WITH

STARTS_WITH(value1, value2)

Descripción

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

Tipo de devolución

BOOL

Ejemplos

SELECT
  STARTS_WITH(item, "b") as example
FROM (
  SELECT "foo" as item
  UNION ALL SELECT "bar" as item
  UNION ALL SELECT "baz" as item) AS items;

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

STRPOS

STRPOS(string, substring)

Descripción

Devuelve el índice con base 1 de la primera repetición de substring dentro de la string. Devuelve 0 si no se encuentra la substring.

Tipo de devolución

INT64

Ejemplos

Table email_addresses:

+-------------------------+
| email_address           |
+-------------------------+
| foo@example.com         |
| foobar@example.com      |
| foobarbaz@example.com   |
| quxexample.com          |
+-------------------------+

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

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

SUBSTR

SUBSTR(value, position[, length])

Descripción

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

Si la position es negativa, la función cuenta desde el final del value, donde -1 indica el último carácter.

Si la position es una posición fuera del extremo izquierdo de STRING (position = 0 o position < -LENGTH(value)), la función comienza desde la posición = 1. Si la length supera la longitud del value, devuelve menos caracteres de length.

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

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
| apple          |
| banana         |
| orange         |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| apple          |
| banana         |
| orange         |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| apple          |
| banana         |
| orange         |
+----------------+

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

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

TRIM

TRIM(value1[, value2])

Descripción

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

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

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
|    apple       |
|    banana      |
|    orange      |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| ***apple***    |
| ***banana***   |
| ***orange***   |
+----------------+

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

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

Table items:

+----------------+
| item           |
+----------------+
| xxxapplexxx    |
| yyybananayyy   |
| zzzorangezzz   |
| xyzpearxyz     |
+----------------+

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

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

UPPER

UPPER(value)

Descripción

Para los argumentos STRING, devuelve la cadena original con todos los caracteres alfabéticos en mayú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 idioma.

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

Tipo de devolución

STRING o BYTES

Ejemplos

Table items:

+----------------+
| item           |
+----------------+
| foo            |
| bar            |
| baz            |
+----------------+

SELECT
  UPPER(item) AS example
FROM items;

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

Funciones de matriz

ARRAY

ARRAY(subquery)

Descripción

La función ARRAY devuelve un ARRAY con un elemento para cada fila en una subconsulta.

Si la subquery genera una tabla SQL estándar, la tabla debe tener exactamente una columna. Cada elemento en el ARRAY de salida es el valor de la columna individual de una fila en la tabla.

Si la subquery genera una tabla de valores, entonces cada elemento en el ARRAY de salida es la fila correspondiente completa de la tabla de valores.

Restricciones

  • Las subconsultas no están ordenadas, por lo que no se garantiza que los elementos del ARRAY de salida conserven ningún orden en la tabla de origen para la subconsulta. Sin embargo, si la subconsulta incluye una cláusula ORDER BY, la función ARRAY devolverá un ARRAY que respete esa cláusula.
  • Si la subconsulta devuelve más de una columna, la función ARRAY devuelve un error.
  • Si la subconsulta devuelve una columna de tipo ARRAY o filas de tipo ARRAY, la función ARRAY devuelve un error: Cloud Spanner SQL no admite ARRAY con elementos de tipo ARRAY.
  • Si la subconsulta no devuelve ninguna fila, la función ARRAY devuelve un ARRAY vacío. Nunca devuelve un ARRAY NULL.

Tipo de devolución

ARRAY

Ejemplos

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

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

Para construir un ARRAY a partir de una subconsulta que contiene varias columnas, cambia la subconsulta para usar SELECT AS STRUCT. Ahora la función ARRAY devolverá un ARRAY de STRUCT. El ARRAY contendrá un STRUCT para cada fila en la subconsulta, y cada uno de estos STRUCT contendrá un campo para cada columna en esa fila.

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

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

De forma similar, para construir un ARRAY a partir de una subconsulta que contenga uno o más ARRAY, cambia la subconsulta para usar SELECT AS STRUCT.

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

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

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Descripción

Devuelve el tamaño de la matriz. Devuelve 0 para una matriz vacía. Devuelve NULL si el array_expression es NULL.

Tipo de devolución

INT64

Ejemplos

SELECT list, ARRAY_LENGTH(list) AS size
FROM (
  SELECT ["apples", "bananas", NULL, "grapes"] as list
  UNION ALL SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL SELECT ["cake", "pie"] as list) AS items
ORDER BY size DESC;

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

OFFSET y ORDINAL

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

Descripción

Accede a un elemento ARRAY por posición y devuelve el elemento. OFFSET significa que la numeración comienza en cero, ORDINAL significa que la numeración comienza en uno.

Una matriz determinada se puede interpretar como basada en 0 o en 1. Al acceder a un elemento de matriz, se debe establecer previamente la posición de la matriz con OFFSET u ORDINAL, respectivamente. No existe un comportamiento predeterminado.

Tanto OFFSET como ORDINAL generan un error si el índice está fuera del intervalo.

Tipo de devolución

Varía en función de los elementos en el ARRAY.

Ejemplos

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM (
  SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL SELECT ["cake", "pie"] as list) AS items;

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

Funciones de fecha

Cloud Spanner SQL admite las siguientes funciones de DATE.

EXTRACT

EXTRACT(part FROM date_expression)

Descripción

Devuelve el valor correspondiente a la parte de la fecha especificada. La part debe ser una de las siguientes:

  • DAYOFWEEK: devuelve valores en el intervalo [1,7], donde el domingo es el primer día de la semana.
  • DAY
  • DAYOFYEAR
  • WEEK: devuelve el número de semana de la fecha en el intervalo [0, 53]. Las semanas comienzan el domingo y las fechas anteriores al primer domingo del año corresponden a la semana 0.

  • ISOWEEK: devuelve el número de semana ISO 8601 de la date_expression. ISOWEEK comienza el lunes. Los valores que se devuelven están en el intervalo [1, 53]. La primera ISOWEEK de cada año ISO comienza el lunes anterior al primer jueves del año del calendario gregoriano.

  • MONTH
  • QUARTER: devuelve valores en el intervalo [1,4].
  • YEAR
  • ISOYEAR: devuelve el año con numeración semanal ISO 8601, que representa el año del calendario gregoriano que contiene el jueves de la semana al que pertenece la date_expression.

Tipo de datos que se devuelven

INT64

Ejemplos

En el siguiente ejemplo, EXTRACT devuelve un valor correspondiente a la parte de tiempo DAY.

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

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

DATE

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

Descripción

  1. Construye una fecha (DATE) a partir de valores INT64 que representan el año, el mes y el día.
  2. Convierte una timestamp_expression en un tipo de datos de DATE. Es compatible con un parámetro opcional para especificar una zona horaria. Si no se especifica la zona horaria, se utiliza la zona horaria predeterminada, America/Los_Angeles.

Tipo de datos que se devuelven

DATE

Ejemplo

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

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

DATE_ADD

DATE_ADD(date_expression, INTERVAL INT64_expr date_part)

Descripción

Agrega un intervalo de tiempo especificado a una DATE.

DATE_ADD admite los siguientes valores de date_part:

  • DAY
  • WEEK. Equivalente a 7 días de DAY.
  • MONTH
  • QUARTER
  • YEAR

Se requiere un tratamiento especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes (o está cercana a él). Si el mes resultante tiene menos días que el día de la fecha original, entonces el día del resultado es el último día del nuevo mes.

Tipo de datos que se devuelven

DATE

Ejemplo

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

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

DATE_SUB

DATE_SUB(date_expression, INTERVAL INT64_expr date_part)

Descripción

Resta un intervalo de tiempo especificado a partir de una DATE.

DATE_SUB admite los siguientes valores de date_part:

  • DAY
  • WEEK. Equivalente a 7 días de DAY.
  • MONTH
  • QUARTER
  • YEAR

Se requiere un tratamiento especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes (o está cercana a él). Si el mes resultante tiene menos días que el día de la fecha original, entonces el día del resultado es el último día del nuevo mes.

Tipo de datos que se devuelven

DATE

Ejemplo

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

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

DATE_DIFF

DATE_DIFF(date_expression, date_expression, date_part)

Descripción

Devuelve el número de límites de date_part entre las dos date_expression. Si la primera fecha ocurre antes de la segunda fecha, entonces el resultado no es positivo.

DATE_DIFF admite los siguientes valores de date_part:

  • DAY
  • MONTH
  • QUARTER
  • YEAR

Tipo de datos que se devuelven

INT64

Ejemplo

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

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Descripción

Trunca la fecha a la granularidad especificada.

DATE_TRUNC admite los siguientes valores para date_part:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

Tipo de datos que se devuelven

DATE

Ejemplos

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

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

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(INT64_expression)

Descripción

Interpreta INT64_expression como el número de días desde 1970-01-01.

Tipo de datos que se devuelven

DATE

Ejemplo

SELECT DATE_FROM_UNIX_DATE(14238) as date_from_epoch;

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

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

Descripción

Define el formato de la date_expr según el format_string especificado.

Si quieres obtener una lista de elementos de formato compatibles con esta función, consulta elementos de formato admitidos para DATE.

Tipo de datos que se devuelven

STRING

Ejemplo

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

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

Descripción

Utiliza una format_string y una representación de cadena de una fecha para devolver un objeto de DATE.

Si utilizas PARSE_DATE, ten en cuenta lo siguiente:

  • Campos no especificados. Cualquier campo no especificado se inicializa desde 1970-01-01.
  • Nombres que no distinguen entre mayúsculas y minúsculas. Los nombres, como Monday, February, etc., no distinguen entre mayúsculas y minúsculas.
  • Espacio en blanco. Uno o más espacios en blanco consecutivos en la cadena de formato coinciden con cero o más espacios en blanco consecutivos en la cadena de fecha. Además, siempre se permiten espacios en blanco iniciales y finales en la cadena de fecha, incluso si no están en la cadena de formato.
  • Prioridad de formato. Cuando dos (o más) elementos de formato tienen información superpuesta (por ejemplo, tanto %F como %Y afectan al año), el último generalmente anula los anteriores.

Si quieres obtener una lista de elementos de formato compatibles con esta función, consulta Elementos de formato admitidos para DATE.

Tipo de datos que se devuelven

DATE

Ejemplo

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

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

UNIX_DATE

UNIX_DATE(date_expression)

Descripción

Devuelve el número de días desde 1970-01-01.

Tipo de datos que se devuelven

INT64

Ejemplo

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

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

Elementos de formato admitidos para DATE

A menos que se indique lo contrario, las funciones de DATE que usan cadenas de formato admiten los siguientes elementos:

Elemento de formato Descripción
%A El nombre completo del día de la semana.
%a El nombre abreviado del día de la semana.
%B El nombre completo del mes.
%b o %h El nombre abreviado del mes.
%C El siglo (un año dividido entre 100 y truncado a un número entero) como un número decimal (00-99).
%D La fecha en el formato %m/%d/%y.
%d El día del mes como un número decimal (01-31).
%e El día del mes como un número decimal (1-31). Los dígitos de una sola cifra están precedidos por un espacio.
%F La fecha en el formato %Y-%m-%d.
%G El año ISO 8601 donde el siglo es un número decimal.
%g El año ISO 8601 donde el siglo no es un número decimal (00-99).
%j El día del año como un número decimal (001-366).
%m El mes como un número decimal (01-12).
%n Un carácter de línea nueva.
%t Un carácter de tabulación.
%U El número de semana del año (donde el domingo es el primer día de la semana) como un número decimal (00-53).
%u El día de la semana (donde el lunes es el primer día de la semana) como un número decimal (1-7).
%V El número de semana del año (donde el lunes es el primer día de la semana) como un número decimal (01-53). Si la semana que contiene el 1 de enero tiene cuatro o más días en el nuevo año, entonces es la semana 1, de lo contrario, es la semana 53 del año anterior, y la semana siguiente es la semana 1.
%W El número de semana del año (donde el lunes es el primer día de la semana) como un número decimal (00-53).
%w El día de la semana (donde el domingo es el primer día de la semana) como un número decimal (0-6).
%x La representación de la fecha en formato MM/DD/AA.
%Y El año donde el siglo es un número decimal.
%y El año donde el siglo no es un número decimal (00-99), con un cero inicial opcional. Se puede mezclar con %C. Si no se especifica %C, los años 00-68 son a partir del 2000, mientras que los años 69-99 son con base en 1900.
%E4Y Años de cuatro caracteres (0001 ... 9999). Ten en cuenta que %Y genera tantos caracteres como sea necesario para representar el año por completo.

Funciones de marcas de tiempo

Cloud Spanner SQL admite las siguientes funciones de TIMESTAMP.

NOTA: Estas funciones devuelven un error de tiempo de ejecución si ocurre un desbordamiento. Los valores min./máx. de fecha y marca de tiempo definidos limitan los valores que se generan.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Descripción

Los paréntesis son opcionales. Esta función maneja segundos intercalares al unirlos en una franja de 20 horas alrededor del segundo intercalado insertado. CURRENT_TIMESTAMP() produce un valor TIMESTAMP que es continuo, no ambiguo, tiene exactamente 60 segundos por minuto y no repite valores en el segundo intercalar.

Tipos de entrada admitidos

No aplicable

Tipo de datos de resultado

TIMESTAMP

Ejemplo

SELECT CURRENT_TIMESTAMP() as now;

+----------------------------------+
| now                              |
+----------------------------------+
| 2016-05-16 18:12:47.145482639+00 |
+----------------------------------+

EXTRACT

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

Descripción

Devuelve un valor INT64 que corresponde a part especificada a partir de una timestamp_expression proporcionada.

Los valores de part permitidos son:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAYOFWEEK
  • DAY
  • DAYOFYEAR
  • WEEK: devuelve el número de semana de la fecha en el intervalo [0, 53]. Las semanas comienzan el domingo y las fechas anteriores al primer domingo del año corresponden a la semana 0.

  • ISOWEEK : devuelve el número de semana ISO 8601 de la datetime_expression. ISOWEEK comienza el lunes. Los valores que se devuelven están en el intervalo [1, 53]. La primera ISOWEEK de cada año ISO comienza el lunes anterior al primer jueves del año del calendario gregoriano.

  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: devuelve el año con numeración semanal ISO 8601, que representa el año del calendario gregoriano que contiene el jueves de la semana al que pertenece la date_expression.
  • DATE

Los valores que se devuelven truncan los períodos de tiempo de orden inferior. Por ejemplo, al extraer segundos, EXTRACT trunca los valores de milisegundos y microsegundos.

Para obtener información sobre cómo especificar una zona horaria, consulta Definiciones de zona horaria.

Tipo de datos que se devuelven

Normalmente INT64. Devuelve DATE si part es DATE.

En el siguiente ejemplo, EXTRACT devuelve valores que corresponden a diferentes partes de tiempo de una columna de marcas de tiempo.

SELECT
  timestamp,
  EXTRACT(ISOYEAR FROM timestamp) AS isoyear,
  EXTRACT(ISOWEEK FROM timestamp) AS isoweek,
  EXTRACT(YEAR FROM timestamp) AS year,
  EXTRACT(WEEK FROM timestamp) AS week
FROM (
    SELECT TIMESTAMP '2005-01-03 12:34:56' AS timestamp UNION ALL
    SELECT TIMESTAMP '2007-12-31' UNION ALL
    SELECT TIMESTAMP '2009-01-01' UNION ALL
    SELECT TIMESTAMP '2009-12-31' UNION ALL
    SELECT TIMESTAMP '2017-01-02' UNION ALL
    SELECT TIMESTAMP '2017-05-26'
  ) AS Timestamps
ORDER BY timestamp;
+------------------------+---------+---------+------+------+
| timestamp              | isoyear | isoweek | year | week |
+------------------------+---------+---------+------+------+
| 2005-01-03 12:34:56+00 | 2005    | 1       | 2005 | 1    |
| 2007-12-31 00:00:00+00 | 2008    | 1       | 2007 | 52   |
| 2009-01-01 00:00:00+00 | 2009    | 1       | 2009 | 0    |
| 2009-12-31 00:00:00+00 | 2009    | 53      | 2009 | 52   |
| 2017-01-02 00:00:00+00 | 2017    | 1       | 2017 | 1    |
| 2017-05-26 00:00:00+00 | 2017    | 21      | 2017 | 21   |
+------------------------+---------+---------+------+------+

STRING

STRING(timestamp_expression[, timezone])

Descripción

Convierte una timestamp_expression en un tipo de datos STRING. Admite un parámetro opcional para especificar una zona horaria. Para obtener información sobre cómo especificar una zona horaria, consulta Definiciones de zona horaria.

Tipo de datos que se devuelven

STRING

TIMESTAMP

1. TIMESTAMP(string_expression[, timezone])
2. TIMESTAMP(date_expression[, timezone])

Descripción

  1. Convierte una expresión STRING en un tipo de datos TIMESTAMP.

  2. Convierte un objeto DATE a un tipo de datos TIMESTAMP.

Esta función admite un parámetro opcional para especificar una zona horaria. Si no se especifica la zona horaria, se utiliza la zona horaria predeterminada, America/Los_Angeles.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplo

SELECT
  CAST(TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") AS STRING) AS timestamp_str,
  CAST(TIMESTAMP(DATE "2008-12-25", "America/Los_Angeles") AS STRING) AS timestamp_date;

+------------------------+------------------------+
| timestamp_str          | timestamp_date         |
+------------------------+------------------------+
| 2008-12-25 15:30:00-08 | 2008-12-25 00:00:00-08 |
+------------------------+------------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

Descripción

Agrega unidades int64_expression de date_part a la marca de tiempo, independientemente de cualquier zona horaria.

TIMESTAMP_ADD admite los siguientes valores para date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 minutos en el campo MINUTE.

Tipos de datos que se devuelven

TIMESTAMP

Ejemplo

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

+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:40:00+00 |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL int64_expression date_part)

Descripción

Resta unidades int64_expression de date_part de la marca de tiempo, independientemente de cualquier zona horaria.

TIMESTAMP_SUB admite los siguientes valores para date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 minutos en el campo MINUTE.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplo

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

+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:20:00+00 |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression, timestamp_expression, date_part)

Descripción

Devuelve el número de intervalos de date_part especificados entre dos marcas de tiempo. Genera un error si el cálculo desborda el tipo de resultado, por ejemplo, si la diferencia en nanosegundos entre las dos marcas de tiempo desborda un valor INT64.

TIMESTAMP_DIFF admite los siguientes valores para date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 minutos en el campo MINUTE.

Tipo de datos que se devuelven

INT64

Ejemplo

SELECT
  TIMESTAMP "2010-07-07 10:20:00 UTC" as first_timestamp,
  TIMESTAMP "2008-12-25 15:30:00 UTC" as second_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00 UTC",
    TIMESTAMP "2008-12-25 15:30:00 UTC", HOUR) AS hours;

+------------------------+------------------------+-------+
| first_timestamp        | second_timestamp       | hours |
+------------------------+------------------------+-------+
| 2010-07-07 10:20:00+00 | 2008-12-25 15:30:00+00 | 13410 |
+------------------------+------------------------+-------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part, [, time_zone])

Descripción

Trunca una marca de tiempo a la granularidad de date_part.

TIMESTAMP_TRUNC admite los siguientes valores para date_part:

  • NANOSECOND
  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

La función TIMESTAMP_TRUNC admite un parámetro de time_zone opcional. Este parámetro se aplica a las siguientes date_parts:

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

Usa este parámetro si quieres usar una zona horaria que no sea la predeterminada, America/Los_Angeles, como parte de la operación de truncado.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplos

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

+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25 00:00:00+00 | 2008-12-25 08:00:00+00 |
+------------------------+------------------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

Descripción

Formatea una marca de tiempo de acuerdo con la format_string especificada.

Para obtener una lista de elementos de formato que esta función admite, consulta Elementos de formato admitidos para TIMESTAMP.

Tipo de datos que se devuelven

STRING

Ejemplo

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

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 07:30:00 2008 |
+--------------------------+

TIMESTAMP_SECONDS

TIMESTAMP_SECONDS(int64_expression)

Descripción

Interpreta int64_expression como la cantidad de segundos desde 1970-01-01 00:00:00 UTC.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

Descripción

Interpreta int64_expression como el número de milisegundos desde 1970-01-01 00:00:00 UTC.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

Descripción

Interpreta int64_expression como el número de microsegundos desde 1970-01-01 00:00:00 UTC.

Tipo de datos que se devuelven

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_MICROS(1230219000000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Descripción

Devuelve la cantidad de segundos desde 1970-01-01 00:00:00 UTC. Trunca los niveles más altos de precisión.

Tipo de datos que se devuelven

INT64

Ejemplo

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

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

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Descripción

Devuelve la cantidad de milisegundos desde 1970-01-01 00:00:00 UTC. Trunca los niveles más altos de precisión.

Tipo de datos que se devuelven

INT64

Ejemplo

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

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

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

Descripción

Devuelve el número de microsegundos desde 1970-01-01 00:00:00 UTC. Trunca los niveles más altos de precisión.

Tipo de datos que se devuelven

INT64

Ejemplo

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

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

Elementos de formato admitidos para TIMESTAMP

A menos que se indique lo contrario, las funciones TIMESTAMP que usan cadenas de formato admiten los siguientes elementos:

Elemento de formato Descripción
%A El nombre completo del día de la semana.
%a El nombre abreviado del día de la semana.
%B El nombre completo del mes.
%b o %h El nombre abreviado del mes.
%C El siglo (un año dividido entre 100 y truncado a un número entero) como un número decimal (00-99).
%c La representación de fecha y hora.
%D La fecha en el formato %m/%d/%y.
%d El día del mes como un número decimal (01-31).
%e El día del mes como un número decimal (1-31). Los dígitos de una sola cifra están precedidos por un espacio.
%F La fecha en el formato %Y-%m-%d.
%G El año ISO 8601 donde el siglo es un número decimal.
%g El año ISO 8601 donde el siglo no es un número decimal (00-99).
%H La hora (reloj de 24 horas) como un número decimal (00-23).
%I La hora (reloj de 12 horas) como un número decimal (01-12).
%j El día del año como un número decimal (001-366).
%k La hora (reloj de 24 horas) como un número decimal (0-23). Los dígitos individuales están precedidos por un espacio.
%l La hora (reloj de 12 horas) como un número decimal (1-12). Los dígitos individuales están precedidos por un espacio.
%M El minuto como un número decimal (00-59).
%m El mes como un número decimal (01-12).
%n Un carácter de línea nueva.
%P Puede ser am o pm.
%p Puede ser AM o PM.
%R La hora en el formato %H:%M.
%r La hora del reloj de 12 horas con la notación AM o PM.
%S El segundo como un número decimal (00-60).
%s La cantidad de segundos desde 1970-01-01 00:00:00 UTC. Siempre anula todos los demás elementos de formato, independientemente de dónde aparezcan los %s en la cadena. Si aparecen varios elementos %s, entonces el último tiene prioridad.
%T La hora en el formato %H:%M:%S.
%t Un carácter de tabulación.
%U El número de semana del año (donde el domingo es el primer día de la semana) como un número decimal (00-53).
%u El día de la semana (donde el lunes es el primer día de la semana) como un número decimal (1-7).
%V El número de semana del año (donde el lunes es el primer día de la semana) como un número decimal (01-53). Si la semana que contiene el 1 de enero tiene cuatro o más días en el nuevo año, entonces es la semana 1, de lo contrario, es la semana 53 del año anterior, y la semana siguiente es la semana 1.
%W El número de semana del año (donde el lunes es el primer día de la semana) como un número decimal (00-53).
%w El día de la semana (donde el domingo es el primer día de la semana) como un número decimal (0-6).
%X La representación de tiempo en formato HH:MM:SS.
%x La representación de la fecha en formato MM/DD/AA.
%Y El año donde el siglo es un número decimal.
%y El año donde el siglo no es un número decimal (00-99), con un cero inicial opcional. Se puede mezclar con %C. Si no se especifica %C, los años 00-68 son a partir del 2000, mientras que los años 69-99 son con base en 1900.
%Z El nombre de la zona horaria.
%z El desplazamiento desde el meridiano de Greenwich en el formato + HHMM o -HHMM, según corresponda, con valores positivos que representan ubicaciones al este de Greenwich.
%% Un solo carácter %.
%Ez Zona horaria numérica compatible con RFC3339 (+HH:MM o -HH:MM).
%E#S Segundos con # dígitos de precisión fraccionaria.
%E*S Segundos con precisión fraccionaria completa (un * literal).
%E4Y Años de cuatro caracteres (0001 ... 9999). Ten en cuenta que %Y produce tantos caracteres como sea necesario para representar el año por completo.

Definiciones de zona horaria

Algunas funciones de fecha y marca de tiempo te permiten anular la zona horaria predeterminada y especificar una diferente. Se puede especificar una zona horaria suministrando el desplazamiento UTC con el siguiente formato:

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

Por ejemplo:

-08:00

Operadores

Los operadores están representados por caracteres especiales o palabras clave. No usan la sintaxis de llamada de función. Un operador manipula cualquier cantidad de entradas de datos, también llamados operandos, y devuelve un resultado.

Convenciones comunes:

  • A menos que se especifique lo contrario, todos los operadores devuelven NULL cuando uno de los operandos es NULL.
  • Todos los operadores generarán un error si el resultado del cálculo se desborda.
  • Para todas las operaciones de coma flotante, solo se pueden devolver +/-inf y NaN si uno de los operandos es +/-inf o NaN. En otros casos, se devuelve un error.

En la siguiente tabla, se muestran todos los operadores de Cloud Spanner SQL desde la precedencia más alta hasta la más baja, es decir, el orden en que se evaluarán dentro de una instrucción.

Orden de precedencia Operador Tipos de datos de entrada Nombre Ardida del operador
1 . STRUCT.
Operador de acceso de campo miembro. Binario
  [ ] ARRAY. Posición de la matriz. Debe usarse con OFFSET u ORDINAL. Consulta las funciones ARRAY. Binario
2 - Numérico. Resta unaria. Unario
  ~ Entero. NOT bit a bit. Unario
3 * Numérico. Multiplicación. Binario
  / Numérico. División. Binario
4 + Numérico. Suma. Binario
  - Numérico. Resta. Binario
5 << Entero. Desplazamiento a la izquierda bit a bit. Binario
  >> Entero. Desplazamiento a la derecha bit a bit. Binario
6 & Entero. AND bit a bit. Binario
7 ^ Entero. XOR bit a bit. Binario
8 | Entero. OR bit a bit. Binario
9 (operadores de comparación) = Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. Igual. Binario
  < Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. Inferior a. Binario
  > Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. Superior a. Binario
  <= Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. Inferior o igual a. Binario
  >= Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. Superior o igual a. Binario
  !=, <> Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista completa. No igual. Binario
  [NOT] LIKE STRING y byte. El valor [no] coincide con el patrón especificado. Binario
  [NOT] BETWEEN Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista. El valor [no] está dentro del intervalo especificado. Binario
  [NOT] IN Cualquier tipo comparable. Consulta los tipos de datos para obtener una lista. El valor [no] está en el conjunto de valores especificado. Binario
  IS [NOT] NULL Todo. El valor [no] es NULL. Unario
  IS [NOT] TRUE BOOL. El valor [no] es TRUE. Unario
  IS [NOT] FALSE BOOL. El valor [no] es FALSE. Unario
10 NOT BOOL. NOT lógico. Unario
11 AND BOOL. AND lógico. Binario
12 OR BOOL. OR lógico. Binario

Los operadores con la misma precedencia se asocian a la izquierda. Esto significa que esos operadores se agrupan empezando por la izquierda y moviéndose a la derecha. Por ejemplo, la expresión:

x AND y AND z

se interpreta como

( ( x AND y ) AND z )

La expresión:

x * y / z

se interpreta como:

( ( x * y ) / z )

Todos los operadores de comparación tienen la misma prioridad y se agrupan utilizando asociatividad izquierda. Sin embargo, los operadores de comparación no son asociativos. Como resultado, se recomienda utilizar paréntesis para mejorar la legibilidad y garantizar que las expresiones se resuelvan como se desee. Por ejemplo, se recomienda:

(x < y) IS FALSE

en vez de:

x < y IS FALSE

Operadores de acceso a elementos

Operador Sintaxis Tipos de datos de entrada Tipo de datos de resultado Descripción
. expression.fieldname1... STRUCT
Tipo T almacenado en fieldname1 Operador punto. Se puede usar para acceder a los campos anidados, p. ej., expression.fieldname1.fieldname2...
[ ] array_expression [position_keyword (int_expression ) ] Ver las funciones ARRAY Tipo T almacenado en ARRAY position_keyword es OFFSET u ORDINAL. Consulta las funciones ARRAY para conocer las dos funciones que usan este operador.

Operadores aritméticos

Todos los operadores aritméticos aceptan entradas de tipo numérico T, y el tipo de resultado tiene el tipo T a menos que se indique lo contrario en la siguiente descripción:

Nombre Sintaxis
Suma X + Y
Resta X - Y
Multiplicación X * Y
División X / Y
Resta unaria - X

NOTA: Las operaciones de división entre cero devuelven un error. Para devolver un resultado diferente, considera las funciones IEEE_DIVIDE o SAFE_DIVIDE.

Tipos de resultados para suma y multiplicación:

 FLOAT64INT64
FLOAT64FLOAT64FLOAT64
INT64FLOAT64INT64

Tipos de resultados para la resta:

 FLOAT64INT64
FLOAT64FLOAT64FLOAT64
INT64FLOAT64INT64

Tipos de resultados para la división:

 FLOAT64INT64
FLOAT64FLOAT64FLOAT64
INT64FLOAT64FLOAT64

Tipos de resultados para resta unitaria:

Tipo de datos de entrada Tipo de datos de resultado
INT64 INT64
FLOAT64 FLOAT64

Operadores bit a bit

Todos los operadores bit a bit devuelven el mismo tipo que el primer operando.

Nombre Sintaxis Tipo de datos de entrada Descripción
NOT bit a bit ~ X Entero Realiza la negación lógica en cada bit y forma el complemento de uno de los valores binarios dados.
OR bit a bit X | Y X: entero
Y: mismo tipo que X
Toma patrones de dos bits de igual longitud y realiza la operación OR inclusiva lógica en cada par de los bits correspondientes.
XOR bit a bit X ^ Y X: entero
Y: mismo tipo que X
Toma patrones de dos bits de igual longitud y realiza la operación OR exclusiva lógica en cada par de los bits correspondientes.
AND bit a bit X & Y X: entero
Y: mismo tipo que X
Toma patrones de dos bits de igual longitud y realiza la operación AND lógica en cada par de los bits correspondientes.
Desplazamiento a la izquierda X << Y X: entero
Y: INT64
Traslada el primer operando X a la izquierda. Este operador devuelve 0 si el segundo operando Y es mayor o igual que 64. Este operador genera un error si Y es negativo.
Desplazamiento a la derecha X >> Y X: entero
Y: INT64
Traslada el primer operando X a la derecha. Este operador no hace la extensión de signo en bit con un tipo con signo (es decir, llena los bits libres de la izquierda con 0). Este operador devuelve 0 si el segundo operando Y es mayor o igual que 64. Este operador genera un error si Y es negativo.

Operadores lógicos

Todos los operadores lógicos permiten solo la entrada BOOL.

Nombre Sintaxis Descripción
NOT lógico NOT X Devuelve FALSE si la entrada es TRUE. Devuelve TRUE si la entrada es FALSE. De lo contrario, devuelve NULL.
AND lógico X AND Y Devuelve FALSE si al menos una entrada es FALSE. Devuelve TRUE si tanto X como Y son TRUE. De lo contrario, devuelve NULL.
OR lógico X OR Y Devuelve FALSE si tanto X como Y son FALSE. Devuelve TRUE si al menos una entrada es TRUE. De lo contrario, devuelve NULL.

Operadores de comparación

Las comparaciones siempre devuelven BOOL. Las comparaciones requieren que ambos operandos sean del mismo tipo. Si son diferentes, se los coacciona a un tipo común para la comparación. Los tipos de datos comparables se definen en los tipos de datos.

Los tipos de datos STRUCT solo admiten 4 operadores de comparación: igual (=), no igual (!= y <>) e IN.

Las siguientes reglas se aplican al comparar estos tipos de datos:

  • FLOAT64: todas las comparaciones con NaN devuelven FALSE, excepto para != y<>, que devuelven TRUE.
  • BOOL: FALSE es menos que TRUE.
  • STRING: las cadenas se comparan punto de código por punto de código, lo que significa que solo se garantiza que las cadenas canónicamente equivalentes se igualen si primero se han normalizado.
  • NULL: la convención aparece aquí (cualquier operación con una entrada NULL devuelve NULL).
Nombre Sintaxis Descripción
Inferior a X < Y Devuelve TRUE si X es menor que Y.
Inferior o igual a X <= Y Devuelve TRUE si X es menor o igual a Y.
Superior a X > Y Devuelve TRUE si X es mayor que Y.
Superior o igual a X >= Y Devuelve TRUE si X es mayor o igual a Y.
Igual X = Y Devuelve TRUE si X es igual a Y.
No igual X != Y
X <> Y
Devuelve TRUE si X no es igual a Y.
BETWEEN X [NOT] BETWEEN Y AND Z Devuelve TRUE si X [no] está dentro del intervalo especificado. El resultado de "X BETWEEN Y AND Z" es equivalente a "Y <= X AND X <= Z", pero X se evalúa solo una vez en el primero.
LIKE X [NOT] LIKE Y Comprueba si la STRING en el primer operando X coincide con un patrón especificado por el segundo operando Y. Las expresiones pueden contener los siguientes caracteres:
  • Un signo de porcentaje "%" coincide con cualquier número de caracteres o bytes.
  • Un guion bajo "_" coincide con un solo carácter o byte.
  • Se puede escapar "\", "_", o "%" con dos barras invertidas. Por ejemplo, "\\%". Si se usan cadenas sin formato, solo se requiere una barra invertida. Por ejemplo, r"\%".
IN Varios: ver abajo Devuelve FALSE si el operando derecho está vacío. Devuelve NULL si el operando izquierdo es NULL. Devuelve TRUE o NULL, nunca FALSE, si el operando derecho contiene NULL. Los argumentos a cada lado de IN son expresiones generales. Ninguno de los dos operandos debe ser un literal, aunque el uso de un literal a la derecha es lo más común. X se evalúa solo una vez.

Al probar valores que tienen un tipo de datos STRUCT para la igualdad, es posible que uno o más campos sean NULL. En esos casos:

  • Si todos los valores de campo no NULL son iguales, la comparación devuelve NULL.
  • Si los valores de campo no NULL no son iguales, la comparación devuelve FALSE.

La siguiente tabla muestra cómo se comparan los tipos de datos STRUCT cuando tienen campos que tienen valores NULL.

Struct1 Struct2 Struct1 = Struct2
STRUCT(1, NULL) STRUCT(1, NULL) NULL
STRUCT(1, NULL) STRUCT(2, NULL) FALSE
STRUCT(1,2) STRUCT(1, NULL) NULL

Operadores IN

El operador IN admite las siguientes sintaxis:

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

Los argumentos a cada lado del operador IN son expresiones generales. Es habitual usar literales en la expresión de la derecha, aunque no resulta necesario.

La semántica de:

x IN (y, z, ...)

se define como equivalente a:

(x = y) OR (x = z) OR ...

y las formas de subconsulta y matriz se definen de manera similar.

x NOT IN ...

equivale a:

NOT(x IN ...)

La forma UNNEST trata una exploración de matriz como UNNEST en la cláusula FROM:

x [NOT] IN UNNEST(<array expression>)

Esta forma se usa a menudo con los parámetros ARRAY. Por ejemplo:

x IN UNNEST(@array_parameter)

Nota: Un ARRAY NULL se tratará de manera equivalente a un ARRAY vacío.

Para obtener más información sobre cómo usar esta sintaxis, consulta el tema relativo a las matrices.

Cuando se usa el operador IN, se aplica la siguiente semántica:

  • IN con una expresión vacía en el lado derecho es siempre FALSE.
  • IN con una expresión NULL en el lado izquierdo y una expresión no vacía en el lado derecho es siempre NULL.
  • IN con un NULL en la lista IN solo puede devolver TRUE o NULL, nunca FALSE.
  • NULL IN (NULL) devuelve NULL.
  • IN UNNEST(<NULL array>) devuelve FALSE (no NULL).

IN se puede usar con claves de varias partes mediante el uso de la sintaxis del constructor struct. Por ejemplo:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

Para obtener más información sobre esta sintaxis, consulta la sección sobre el tipo de estructura del tema relativo a los tipos de datos.

Operadores IS

Los operadores IS devuelven TRUE o FALSE para la condición que prueban. Nunca devuelven NULL, ni siquiera para entradas NULL, a diferencia de las funciones IS_INF e IS_NAN definidas en Funciones matemáticas. Si NOT está presente, el valor BOOL de salida se invierte.

Sintaxis de la función Tipo de datos de entrada Tipo de datos de resultado Descripción

X IS [NOT] NULL
Cualquier tipo de valor BOOL Devuelve TRUE si el operando X se evalúa como NULL, de lo contrario, devuelve FALSE.

X IS [NOT] TRUE
BOOL BOOL Devuelve TRUE si el operando BOOL se evalúa como TRUE. De lo contrario, devuelve FALSE.

X IS [NOT] FALSE
BOOL BOOL Devuelve TRUE si el operando BOOL se evalúa como FALSE. De lo contrario, devuelve FALSO.

Expresiones condicionales

Las expresiones condicionales imponen restricciones al orden de evaluación de sus entradas. En esencia, se evalúan de izquierda a derecha, con cortocircuito, y solo evalúa el valor de salida que se eligió. Por el contrario, todas las entradas a las funciones normales se evalúan antes de llamar a la función. El cortocircuito en expresiones condicionales se puede explotar para el tratamiento de errores o la optimización del rendimiento.

Sintaxis Tipos de datos de entrada Tipo de datos de resultado Descripción

CASE expr
  WHEN value THEN result
  [WHEN ...]
  [ELSE else_result]
  END
expr y value: cualquier tipo result y else_result: supertipo de tipos de entrada Compara expr con el valor de cada cláusula WHEN sucesiva y devuelve el primer resultado donde esta comparación devuelve true. Las cláusulas WHEN y else_result restantes no se evalúan. Si la comparación expr = value devuelve false o NULL para todas las cláusulas WHEN, devuelve else_result. Las expresiones expr y value se deben coaccionar implícitamente a un supertipo común. Las comparaciones de igualdad se realizan en valores coercitivos. Las expresiones result y else_result se deben coaccionar a un supertipo común.

CASE
  WHEN cond1 THEN result
  [WHEN cond2...]
  [ELSE else_result]
  END
cond: BOOL result y else_result: supertipo de tipos de entrada Evalúa la condición cond de cada cláusula WHEN sucesiva y devuelve el primer resultado donde la condición es true. Las cláusulas WHEN y else_result restantes no se evalúan. Si todas las condiciones son false o NULL, devuelve else_result. Las expresiones result y else_result se deben coaccionar implícitamente a un supertipo común.
COALESCE(expr1, ..., exprN) Cualquier tipo Supertipo de tipos de entrada Devuelve el valor de la primera expresión no nula. Las expresiones restantes no se evalúan. Todas las expresiones de entrada se deben coaccionar implícitamente a un supertipo común.
IF(cond, true_result, else_result) cond: BOOL true_result y else_result: cualquier tipo Si cond es true, devuelve true_result, de lo contrario devuelve else_result. else_result no se evalúa si cond es true. true_result no se evalúa si cond es false o NULL. true_result y else_result se deben coaccionar a un supertipo común.
IFNULL(expr, null_result) Cualquier tipo Cualquier tipo o supertipo de tipos de entrada Si expr es NULL, devuelve null_result. De lo contrario, devuelve expr. Si expr no es NULL, null_result no se evalúa. expr y null_result se deben coaccionar implícitamente a un supertipo común. Sinónimo de COALESCE(expr, null_result).
NULLIF(expression, expression_to_match) Cualquier tipo T o subtipo de T Cualquier tipo T o subtipo de T Devuelve NULL si expression = expression_to_match es verdadero, de lo contrario, devuelve expression. expression y expression_to_match se deben coaccionar implícitamente a un supertipo común. La comparación de igualdad se realiza en valores coercitivos.

NULLIF no es compatible con los tipos STRUCT.

Subconsultas de expresiones

Hay cuatro tipos de subconsultas de expresiones, es decir, subconsultas que se utilizan como expresiones. Las subconsultas de expresiones devuelven NULL o un solo valor, a diferencia de una columna o tabla, y deben estar entre paréntesis. Para profundizar en el tema de las subconsultas, dirígete al apartado correspondiente a las subconsultas.

Tipo de subconsulta Tipo de datos de resultado Descripción
Escalar Cualquier tipo T Una subconsulta entre paréntesis dentro de una expresión (p. ej., en la lista SELECT o en la cláusula WHERE) se interpreta como una subconsulta escalar. La lista SELECT en una subconsulta escalar debe tener exactamente un campo. Si la subconsulta devuelve exactamente una fila, ese único valor es el resultado de la subconsulta escalar. Si la subconsulta devuelve cero filas, el valor de la subconsulta escalar es NULL. Si la subconsulta devuelve más de una fila, la consulta falla con un error de tiempo de ejecución. Cuando la subconsulta se escribe con SELECT AS STRUCT, puede incluir varias columnas, y el valor que se devuelve es el STRUCT construido. La selección de varias columnas sin usar SELECT AS es un error.
ARRAY ARRAY Se puede usar SELECT AS STRUCT para construir matrices de structs y, por el contrario, la selección de varias columnas sin utilizar SELECT AS es un error. Devuelve un ARRAY vacío si la subconsulta devuelve cero filas. Nunca devuelve un ARRAY NULL.
IN BOOL Ocurre en una expresión que sigue al operador IN. La subconsulta debe producir una sola columna cuyo tipo sea compatible con la igualdad con la expresión del lado izquierdo del operador IN. Devuelve FALSE si la subconsulta devuelve cero filas. x IN () es equivalente a x IN (value, value, ...). Para obtener una semántica completa consulta el operador IN en Operadores de comparación.
EXISTS BOOL Devuelve TRUE si la subconsulta produjo una o más filas. Devuelve FALSE si la subconsulta produce cero filas. Nunca devuelve NULL. A diferencia de todas las otras subconsultas de expresión, no hay reglas sobre la lista de columnas. Se puede seleccionar cualquier cantidad de columnas y no afectará el resultado de la consulta.

Ejemplos

Los siguientes ejemplos de subconsultas de expresiones suponen que t.int_array es del tipo ARRAY<INT64>.

Tipo Subconsulta Tipo de datos de resultado Notas
Escalar (SELECT COUNT(*) FROM t.int_array) INT64  
(SELECT DISTINCT i FROM t.int_array i) INT64, posiblemente error de tiempo de ejecución  
(SELECT i FROM t.int_array i WHERE i=5) INT64, posiblemente error de tiempo de ejecución  
(SELECT ARRAY_AGG(i) FROM t.int_array i) ARRAY Utiliza la función de agregación ARRAY_AGG para devolver un ARRAY.
(SELECT 'xxx' a) STRING  
(SELECT 'xxx' a, 123 b) Error Devuelve un error porque hay más de una columna.
(SELECT AS STRUCT 'xxx' a, 123 b) STRUCT  
(SELECT AS STRUCT 'xxx' a) STRUCT  
ARRAY ARRAY(SELECT COUNT(*) FROM t.int_array) ARRAY de tamaño 1  
ARRAY(SELECT x FROM t) ARRAY  
ARRAY(SELECT 5 a, COUNT(*) b FROM t.int_array) Error Devuelve un error porque hay más de una columna.
ARRAY(SELECT AS STRUCT 5 a, COUNT(*) b FROM t.int_array) ARRAY  
ARRAY(SELECT AS STRUCT i FROM t.int_array i) ARRAY Forma un ARRAY de STRUCTs de un campo.
ARRAY(SELECT AS STRUCT 1 x, 2, 3 x) ARRAY Devuelve un ARRAY de STRUCTs con campos anónimos o duplicados.
ARRAY(SELECT AS TypeName SUM(x) a, SUM(y) b, SUM(z) c from t) array<TypeName> Selección en un tipo con nombre. Supone que TypeName es un tipo de STRUCT con los campos a, b y c.
STRUCT (SELECT AS STRUCT 1 x, 2, 3 x) STRUCT Construye un STRUCT con campos anónimos o duplicados.
EXISTS EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
NOT EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
IN x IN (SELECT y FROM table WHERE z) BOOL  
x NOT IN (SELECT y FROM table WHERE z) BOOL