Funciones y operadores de SQL estándar

En esta página, se explican las expresiones de BigQuery, lo que incluye las funciones y los operadores.

Reglas de llamada a funciones

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

  • Para las funciones que aceptan tipos numéricos, si un operando es de punto flotante y el otro es otro tipo numérico, ambos operandos se convierten en FLOAT64 antes de evaluar la función.
  • Si un operando es NULL, el resultado es , a excepción del operador IS.
  • Para las funciones que son sensibles a la zona horaria (como se indica en la descripción de la función), la zona horaria predeterminada, UTC, se usa si no se especifica una zona horaria.

Prefijo SAFE.

Sintaxis:

SAFE.function_name()

Descripción

Si comienzas una función con el prefijo SAFE., se mostrará NULL en lugar de un error. El prefijo SAFE. solo previene errores de la función con el prefijo en sí: no evita los errores que se producen cuando se evalúan las expresiones de argumento. El prefijo SAFE. solo previene errores que se producen debido al valor de las entradas de función, como los errores “valor fuera de rango”. Aún pueden ocurrir otros errores, como errores internos o del sistema. Si la función no muestra un error, SAFE. no tiene efecto en el resultado. Si la función nunca muestra un error, como RAND, entonces SAFE. no tiene ningún efecto.

Los operadores, como + y =, no admiten el prefijo SAFE.. Para evitar errores de una operación de división, usa SAFE_DIVIDE. Algunos operadores, como IN, ARRAY y UNNEST, se parecen a funciones, pero no admiten el prefijo SAFE.. Las funciones CAST y EXTRACT tampoco admiten el prefijo SAFE.. Para evitar la transmisión de errores, usa SAFE_CAST.

Ejemplo

En el siguiente ejemplo, el primer uso de la función SUBSTR normalmente mostraría un error, porque la función no admite argumentos de longitud con valores negativos. Sin embargo, el prefijo SAFE. hace que la función muestre NULL en su lugar. El segundo uso de la función SUBSTR proporciona el resultado esperado: el prefijo SAFE. no tiene ningún efecto.

SELECT SAFE.SUBSTR('foo', 0, -2) AS safe_output UNION ALL
SELECT SAFE.SUBSTR('bar', 0, 2) AS safe_output;

+-------------+
| safe_output |
+-------------+
| NULL        |
| ba          |
+-------------+

Funciones compatibles

BigQuery admite el uso del prefijo SAFE. con la mayoría de las funciones escalares que pueden generar errores, incluidas las funciones STRING, las funciones matemáticas, las funciones DATE, las funciones DATETIME y las funciones TIMESTAMP. BigQuery no admite el uso del prefijo SAFE. con funciones agregadas, analíticas o funciones definidas por el usuario.

Llama a funciones definidas por el usuario (UDF) persistentes

Después de crear una UDF persistente, puedes llamarla como se haría con cualquier otra función, precedida por el nombre del conjunto de datos en el que se define como un prefijo.

Sintaxis

[`project_name`].dataset_name.function_name([parameter_value[, ...]])

Si se llama a una UDF en un proyecto que no sea el que se usa para ejecutar la consulta, se necesita project_name.

Ejemplos

En el siguiente ejemplo, se crea una UDF denominada multiply_by_three y se la llama desde el mismo proyecto.

CREATE FUNCTION my_dataset.multiply_by_three(x INT64) AS (x * 3);

SELECT my_dataset.multiply_by_three(5) AS result; -- returns 15

En el siguiente ejemplo, se llama a una UDF persistente desde un proyecto diferente.


CREATE `other_project`.other_dataset.other_function(x INT64, y INT64)
  AS (x * y * 2);

SELECT `other_project`.other_dataset.other_function(3, 4); --returns 24

Reglas de conversión

“Conversión” incluye, entre otros, conversión de tipos y coerción.

  • La conversión de tipos es una conversión explícita y usa la función CAST().
  • La coerción es la conversión implícita, que realiza BigQuery de forma automática según las condiciones que se detallan a continuación.
  • Existe un tercer grupo de funciones de conversión con sus propios nombres de funciones, como UNIX_DATE().

En la siguiente tabla, se resumen todas las posibilidades de coerción y CAST para los tipos de datos de BigQuery. “Coerción a” se aplica a todas las expresiones de un tipo de datos determinado (p. ej., una columna), pero los literales y los parámetros también se pueden coercionar. Consulta la sección sobre coerción de literales y coerción de parámetros para obtener más detalles.

De tipo CONVERSIÓN a Coerción a
INT64 BOOL
INT64
NUMERIC
FLOAT64
STRING
FLOAT64
NUMERIC
NUMERIC INT64
NUMERIC
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
NUMERIC
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
NUMERIC
FLOAT64
STRING
BYTES
DATE
DATETIME
TIME
TIMESTAMP
 
BYTES BYTES
STRING
 
DATE DATE
DATETIME
STRING
TIMESTAMP
 
DATETIME DATE
DATETIME
STRING
TIME
TIMESTAMP
 
TIME STRING
TIME
 
TIMESTAMP DATE
DATETIME
STRING
TIME
TIMESTAMP
 
ARRAY ARRAY  
STRUCT STRUCT  

Conversión de tipos

Sintaxis:

CAST(expr AS typename)

La sintaxis de conversión de tipos se usa en una consulta para indicar que el tipo de resultado de una expresión debe convertirse en algún otro tipo.

Ejemplo:

CAST(x=1 AS STRING)

Esto da como resultado "true" si x es 1, "false" para cualquier otro valor que no sea NULL, y NULL si x es NULL.

Las conversiones entre tipos admitidos que no se mapean con éxito del valor original al dominio de destino producen errores en el entorno de ejecución. Por ejemplo, la conversión de BYTES a STRING cuando la secuencia de bytes no es un resultado UTF-8 válido devuelve un error en el entorno de ejecución.

Cuando se convierte el tipo de una expresión x de los siguientes tipos, se aplican estas reglas:

De A Reglas para la conversión de tipos de x
INT64 FLOAT64 Muestra un valor FLOAT64 cercano, pero potencialmente no exacto.
INT64 BOOL Muestra FALSE si x es 0, y TRUE en caso contrario.
NUMERIC Floating Point NUMERIC se convertirá al número de punto flotante más cercano con una pérdida de precisión posible.
FLOAT64 INT64 Muestra el valor INT64 más cercano.
Los casos de punto medio, como 1.5 o -0.5, se redondean en dirección opuesta al cero.
FLOAT64 STRING Muestra una representación aproximada de la string.
FLOAT64 NUMERIC Si el número de punto flotante tiene más de nueve dígitos tras el punto decimal, se redondeará medio punto hacia arriba de cero. Si conviertes el tipo de un NaN, +inf o -inf, se mostrará un error. Si se convierte el tipo de un valor fuera del rango NUMERIC, se mostrará un error de desbordamiento.
BOOL INT64 Muestra 1 si x es TRUE, y 0 en caso contrario.
BOOL STRING Muestra "true" si x es TRUE, y "false" en caso contrario.
STRING FLOAT64 Muestra x como un valor FLOAT64 y lo interpreta como si tuviera el mismo formato que un literal FLOAT64 válido.
También admite conversiones de tipo desde "inf", "+inf", "-inf" y "nan".
Las conversiones no distinguen entre mayúsculas y minúsculas.
STRING NUMERIC El literal numérico incluido en STRING no debe exceder la precisión o rango máximo del tipo NUMERIC. De lo contrario, se producirá un error. Si la cantidad de dígitos tras el punto decimal es mayor que nueve, el valor NUMERIC resultante se redondeará con los valores medios en dirección opuesta al cero para que tenga nueve dígitos tras el punto decimal.
STRING BOOL Muestra TRUE si x es "true" y FALSE si x es "false"
Todos los demás valores de x no son válidos y muestran un error en lugar de convertir el tipo en BOOL.
Las STRING no distinguen entre mayúsculas y minúsculas cuando se convierten en BOOL.
STRING BYTES Las STRING se convierten en BYTES mediante la codificación UTF-8. Por ejemplo, la STRING "©", cuando se la transforma en BYTES, se convierte en una secuencia de 2 bytes con valores hexadecimales C2 y A9.
BYTES STRING Muestra x interpretado como una STRING UTF-8.
Por ejemplo, el literal de BYTES b'\xc2\xa9', cuando se convierte su tipo en STRING, se interpreta como UTF-8 y se convierte en el carácter Unicode “©”.
Se produce un error si x no es un valor de UTF-8 válido.
ARRAY ARRAY Debe ser exactamente el mismo tipo de ARRAY.
STRUCT STRUCT Se permite si se cumplen las siguientes condiciones:
  1. Los dos STRUCT tienen la misma cantidad de campos.
  2. Los tipos de campo STRUCT original se pueden transmitir a los tipos de campos STRUCT de destino correspondientes (según se define por orden y no nombre de campo).

Conversión segura

Cuando usas CAST, la consulta puede fallar si BigQuery no puede realizar la conversión de tipos. Por ejemplo, la siguiente consulta genera un error:

SELECT CAST("apple" AS INT64) AS not_a_number;

Si deseas proteger tus consultas de estos tipos de errores, puedes usar SAFE_CAST. es idéntico a CAST, pero muestra NULL en vez de generar un error.

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

Si conviertes el tipo de bytes en strings, también puedes usar la función SAFE_CONVERT_BYTES_TO_STRING. Los caracteres UTF-8 no válidos se reemplazan por el carácter de reemplazo de Unicode, U+FFFD. Consulta SAFE_CONVERT_BYTES_TO_STRING para obtener más información.

Cómo convertir strings hexadecimales en números enteros

Si trabajas con strings hexadecimales (0x123), puedes convertir sus tipos en números 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       |
+-----------+------------+

Conversión de tipos de fechas

BigQuery admite las conversiones de tipos de fechas desde y hacia strings como se muestra a continuación:

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

La conversión de un tipo de fecha a una string es independiente de la zona horaria y tiene la forma YYYY-MM-DD. Cuando se realiza una conversión de string a fecha, la string debe cumplir con el formato de fecha admitido y es independiente de la zona horaria. Se producirá un error si la expresión de la string no es válida o representa una fecha fuera del rango mínimo o máximo aceptado.

Conversión de tipos de marcas de tiempo

BigQuery admite la conversión de tipos de marcas de tiempo desde y hacia strings de la siguiente manera:

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

Cuando se realiza una conversión de tipos de marcas de tiempo a strings, la marca de tiempo se interpreta con la zona horaria predeterminada, UTC. La cantidad de dígitos de subsegundos producidos depende de la cantidad de ceros finales en la parte de subsegundos: la función CAST truncará cero, tres o seis dígitos.

Cuando se realiza una conversión de tipo de una string a una marca de tiempo, string_expression debe cumplir con los formatos de literal de marca de tiempo aceptados o, de lo contrario, ocurrirá un error en el entorno de ejecución. string_expression puede contener un time_zone; consulta zonas horarias. Si hay una zona horaria en string_expression, se usa para la conversión; de lo contrario, se usa la zona horaria predeterminada, UTC. Si la string tiene menos de seis dígitos, entonces se ensancha de forma implícita.

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

Conversión entre tipos de fecha y marca de tiempo

BigQuery admite la conversión entre tipos de fecha y marca de tiempo de la siguiente manera:

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

La conversió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, UTC. La conversión de una marca de tiempo a una fecha trunca de forma efectiva la marca de tiempo desde la zona horaria predeterminada.

Coerción

BigQuery coerciona el tipo de resultado de una expresión a otro tipo si necesita hacer coincidir las firmas de la función. Por ejemplo, si la función func() se define para que tenga un solo argumento del tipo INT64 y se usa una expresión como argumento que tiene un tipo de resultado de FLOAT64, entonces el resultado de la expresión se coercionará al tipo INT64 antes de que se calcule la función func().

Coerción literal

BigQuery es compatible con los siguientes tipos de coerción literal:

Tipo de datos de entrada Tipo de datos del resultado Notas
Literal de STRING DATE
TIMESTAMP

La coerción literal es necesaria cuando el tipo literal real es diferente al tipo que espera la función en cuestión. Por ejemplo, si la función func() toma un argumento DATE, la expresión func("2014-09-27") es válida porque el literal de STRING "2014-09-27" se coerciona a DATE.

La conversión literal se evalúa en el momento del análisis y genera un error si el literal de entrada no se puede convertir con éxito al tipo de destino.

Nota: Los literales de string no se coercionan a tipos de números.

Coerción de parámetros

BigQuery admite las siguientes coerciones de parámetros:

Tipo de datos de entrada Tipo de datos del resultado
Parámetro de la STRING

Aparecerá un error si el valor del parámetro no se puede forzar correctamente al tipo de destino.

Funciones de conversión adicionales

BigQuery proporciona las siguientes funciones de conversión adicionales:

Funciones de agregación

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

SELECT COUNT(*) as total_count, COUNT(fruit) as non_null_count,
       MIN(fruit) as min, MAX(fruit) as max
FROM (SELECT NULL as fruit UNION ALL
      SELECT "apple" as fruit UNION ALL
      SELECT "pear" as fruit UNION ALL
      SELECT "orange" as fruit)

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

En las siguientes secciones, se describen las funciones agregadas que admite BigQuery.

ANY_VALUE

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

Descripción

Muestra cualquier valor de la entrada o NULL si hay cero filas de entradas. El valor mostrado es no determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.

Tipos de argumentos admitidos

Cualquiera

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipos de datos mostrados

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     |
+-----------+
SELECT
  fruit,
  ANY_VALUE(fruit) OVER (ORDER BY LENGTH(fruit) ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+--------+-----------+
| fruit  | any_value |
+--------+-----------+
| pear   | pear      |
| apple  | pear      |
| banana | apple     |
+--------+-----------+

ARRAY_AGG

ARRAY_AGG([DISTINCT] expression [{IGNORE|RESPECT} NULLS]
          [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

Descripción

Muestra un ARRAY de valores expression.

Tipos de argumentos admitidos

Todos los tipos de datos excepto ARRAY.

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de ARRAY_AGG().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.
  3. IGNORE NULLS o RESPECT NULLS: si se especifica , los valores NULL se excluyen del resultado. Si se especifica RESPECT NULLS o si no se especifica ninguno de los dos, los valores NULL se incluyen en el resultado (sin embargo, se genera un error si un arreglo en el resultado final de la consulta contiene un elemento NULL).
  4. ORDER BY: Especifica el orden de los valores.
    • Para cada clave de orden, la dirección de orden predeterminada es ASC.
    • NULL: En el contexto de la cláusula ORDER BY, NULL es el valor mínimo posible; es decir, los valores NULL aparecen primeros en ASC y últimos en DESC.
    • Tipos de datos de punto flotante: consulta Semántica de punto flotante sobre cómo ordenar y agrupar.
    • Si también se especifica DISTINCT, la clave de clasificación debe ser igual que expression.
    • Si no se especifica ORDER BY, el orden de los elementos en el arreglo de resultado no es determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.
  5. LIMIT: especifica la cantidad máxima de entradas expression en el resultado. El límite n debe ser una constante INT64.

Tipos de datos mostrados

ARRAY

Si hay cero filas de entrada, esta función muestra NULL.

Ejemplos

SELECT FORMAT("%T", ARRAY_AGG(x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------------+
| array_agg               |
+-------------------------+
| [2, 1, -2, 3, -2, 1, 2] |
+-------------------------+
SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+---------------+
| array_agg     |
+---------------+
| [2, 1, -2, 3] |
+---------------+
SELECT FORMAT("%T", ARRAY_AGG(x IGNORE NULLS)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [1, -2, 3, -2, 1] |
+-------------------+
SELECT FORMAT("%T", ARRAY_AGG(x ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------------+
| array_agg               |
+-------------------------+
| [1, 1, 2, -2, -2, 2, 3] |
+-------------------------+
SELECT FORMAT("%T", ARRAY_AGG(x LIMIT 5)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [2, 1, -2, 3, -2] |
+-------------------+
SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x IGNORE NULLS ORDER BY x LIMIT 2)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-----------+
| array_agg |
+-----------+
| [-2, 1]   |
+-----------+
SELECT
  x,
  FORMAT("%T", ARRAY_AGG(x) OVER (ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

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

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])

Descripción

Concatena elementos de expression de tipo ARRAY y muestra un solo ARRAY como resultado. Esta función ignora los arreglos de entrada NULL, pero respeta los elementos NULL en arreglos de entrada que no son NULL (no obstante, se genera un error si un arreglo en el resultado final de la consulta contiene un elemento NULL).

Tipos de argumentos admitidos

ARRAY

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. ORDER BY: Especifica el orden de los valores.
    • Para cada clave de orden, la dirección de orden predeterminada es ASC.
    • No se admite el ordenamiento de arreglos y, por lo tanto, la clave de orden no puede ser la misma que en expression.
    • NULL: En el contexto de la cláusula ORDER BY, NULL es el valor mínimo posible; es decir, los valores NULL aparecen primeros en ASC y últimos en DESC.
    • Tipos de datos de punto flotante: consulta Semántica de punto flotante sobre cómo ordenar y agrupar.
    • Si no se especifica ORDER BY, el orden de los elementos en el arreglo de resultado no es determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.
  2. LIMIT: especifica la cantidad máxima de entradas expression en el resultado. El límite se aplica al número de arreglos de entrada, no al número de elementos en el arreglo. Un arreglo vacío cuenta como 1. Un arreglo NULL no se cuenta. El límite n debe ser una constante INT64.

Tipos de datos mostrados

ARRAY

Muestra NULL si no hay filas de entrada o si expression se evalúa como NULL en todas las filas.

Ejemplos

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

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
+-----------------------------------+
SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x ORDER BY ARRAY_LENGTH(x))) AS array_concat_agg FROM (
  SELECT [1, 2, 3, 4] AS x
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

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

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

+------------------+
| array_concat_agg |
+------------------+
| [5, 6, 7, 8, 9]  |
+------------------+

AVG

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

Descripción

Muestra el promedio de valores de entrada que no son NULL, o muestra NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de entrada numérico, como INT64. Ten en cuenta que para los tipos de entrada de punto flotante, el resultado mostrado es no determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de AVG().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipos de datos mostrados

  • NUMERIC si el tipo de entrada es NUMERIC.
  • FLOAT64

Ejemplos

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

+-----+
| avg |
+-----+
| 3   |
+-----+
SELECT AVG(DISTINCT x) AS avg
FROM UNNEST([0, 2, 4, 4, 5]) AS x;

+------+
| avg  |
+------+
| 2.75 |
+------+
SELECT
  x,
  AVG(x) OVER (ORDER BY x ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) AS x;

+------+------+
| x    | avg  |
+------+------+
| NULL | NULL |
| 0    | 0    |
| 2    | 1    |
| 4    | 3    |
| 4    | 4    |
| 5    | 4.5  |
+------+------+

BIT_AND

BIT_AND(expression)

Descripción

Realiza una operación AND a nivel de bits en expression y muestra el resultado.

Tipos de argumentos admitidos

  • INT64

Tipos de datos mostrados

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 a nivel de bits en expression y muestra el resultado.

Tipos de argumentos admitidos

  • INT64

Tipos de datos mostrados

INT64

Ejemplos

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

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

BIT_XOR

BIT_XOR([DISTINCT] expression)

Descripción

Realiza una operación XOR a nivel de bits en expression y muestra el resultado.

Tipos de argumentos admitidos

  • INT64

Cláusula opcional

DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipos de datos mostrados

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    |
+---------+
SELECT BIT_XOR(DISTINCT x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;

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

COUNT

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

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

Descripción

  1. Muestra el número de filas en la entrada.
  2. Muestra el número de filas con expression evaluado como cualquier valor distinto de NULL.

Tipos de argumentos admitidos

expression puede ser cualquier tipo de datos.

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas.
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipos de datos mostrados

INT64

Ejemplos

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

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

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

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

COUNTIF

COUNTIF(expression)  [OVER (...)]

Descripción

Muestra el recuento de valores TRUE para expression. Muestra 0 si hay cero filas de entrada o si expression se evalúa como FALSE para todas las filas.

Tipos de argumentos admitidos

BOOL

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipos de datos mostrados

INT64

Ejemplos

SELECT COUNTIF(x<0) AS num_negative, COUNTIF(x>0) AS num_positive
FROM UNNEST([5, -2, 3, 6, -10, -7, 4, 0]) AS x;

+--------------+--------------+
| num_negative | num_positive |
+--------------+--------------+
| 3            | 4            |
+--------------+--------------+
SELECT
  x,
  COUNTIF(x<0) OVER (ORDER BY ABS(x) ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING) AS num_negative
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) AS x;

+------+--------------+
| x    | num_negative |
+------+--------------+
| NULL | 0            |
| 0    | 1            |
| -2   | 1            |
| 3    | 1            |
| 4    | 0            |
| 5    | 0            |
| 6    | 1            |
| -7   | 2            |
| -10  | 2            |
+------+--------------+

LOGICAL_AND

LOGICAL_AND(expression)

Descripción

Muestra el AND lógico para todas las expresiones que no son NULL. Muestra NULL si hay cero filas de entrada o si expression se evalúa como NULL para todas las filas.

Tipos de argumentos admitidos

BOOL

Tipos de datos mostrados

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

Muestra el OR lógico para todas las expresiones que no son NULL. Muestra NULL si hay cero filas de entrada o si expression se evalúa como NULL para todas las filas.

Tipos de argumentos admitidos

BOOL

Tipos de datos mostrados

BOOL

Ejemplos

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

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

MAX

MAX(expression)  [OVER (...)]

Descripción

Muestra el valor máximo de las expresiones que no son NULL. Muestra NULL si hay cero filas de entrada o si expression se evalúa como NULL para todas las filas. Muestra NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de datos excepto: ARRAY STRUCT

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipos de datos mostrados

Igual al tipo de datos usado como valores de entrada.

Ejemplos

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

+-----+
| max |
+-----+
| 55  |
+-----+
SELECT x, MAX(x) OVER (PARTITION BY MOD(x, 2)) AS max
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | max  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 8    |
| 4    | 8    |
| 37   | 55   |
| 55   | 55   |
+------+------+

MIN

MIN(expression)  [OVER (...)]

Descripción

Muestra el valor mínimo de las expresiones que no son NULL. Muestra NULL si hay cero filas de entrada o si expression se evalúa como NULL para todas las filas. Muestra NaN si la entrada contiene un NaN.

Tipos de argumentos admitidos

Cualquier tipo de datos excepto: ARRAY STRUCT

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipos de datos mostrados

Igual al tipo de datos usado como valores de entrada.

Ejemplos

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

+-----+
| min |
+-----+
| 4   |
+-----+
SELECT x, MIN(x) OVER (PARTITION BY MOD(x, 2)) AS min
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | min  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 4    |
| 4    | 4    |
| 37   | 37   |
| 55   | 37   |
+------+------+

STRING_AGG

STRING_AGG([DISTINCT] expression [, delimiter]  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

Descripción

Muestra un valor (ya sea STRING o BYTES) obtenido mediante la concatenación de valores no nulos.

Si especificas un delimiter, los valores concatenados se separan con ese delimitador; de lo contrario, se usa una coma.

Tipos de argumentos admitidos

STRING BYTES

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de STRING_AGG().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.
  3. ORDER BY: Especifica el orden de los valores.
    • Para cada clave de orden, la dirección de orden predeterminada es ASC.
    • NULL: En el contexto de la cláusula ORDER BY, NULL es el valor mínimo posible; es decir, los valores NULL aparecen primeros en ASC y últimos en DESC.
    • Tipos de datos de punto flotante: consulta Semántica de punto flotante sobre cómo ordenar y agrupar.
    • Si también se especifica DISTINCT, la clave de clasificación debe ser igual que expression.
    • Si no se especifica ORDER BY, el orden de los elementos en el arreglo de resultado no es determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.
  4. LIMIT: especifica la cantidad máxima de entradas expression en el resultado. El límite se aplica al número de strings de entrada, no al número de caracteres o bytes en las entradas. Una string vacía cuenta como 1. Una string NULL no se cuenta. El límite n debe ser una constante INT64.

Tipos de datos mostrados

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

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

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

+------------------------------+
| string_agg                   |
+------------------------------+
| pear & pear & apple & banana |
+------------------------------+
SELECT STRING_AGG(fruit, " & " LIMIT 2) AS string_agg
FROM UNNEST(["apple", "pear", "banana", "pear"]) AS fruit;

+--------------+
| string_agg   |
+--------------+
| apple & pear |
+--------------+
SELECT STRING_AGG(DISTINCT fruit, " & " ORDER BY fruit DESC LIMIT 2) AS string_agg
FROM UNNEST(["apple", "pear", "banana", "pear"]) AS fruit;

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

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

SUM

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

Descripción

Muestra la suma de valores no nulos.

Si la expresión es un valor de punto flotante, la suma es no determinista, lo que significa que podrías recibir un resultado diferente cada vez que uses esta función.

Tipos de argumentos admitidos

Cualquier tipo de datos numéricos admitido.

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas.
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipos de datos mostrados

  • Muestra INT64 si la entrada es un número entero.
  • Muestra NUMERIC si el tipo de entrada es NUMERIC.
  • Muestra FLOAT64 si la entrada es un valor de punto flotante.

Muestra NULL si la entrada solo contiene .

Muestra Inf si la entrada contiene .

Muestra -Inf si la entrada contiene .

Muestra NaN si la entrada contiene un .

Muestra NaN si la entrada contiene una combinación de Inf y -Inf.

Ejemplos

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

+-----+
| sum |
+-----+
| 25  |
+-----+
SELECT SUM(DISTINCT x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 15  |
+-----+
SELECT
  x,
  SUM(x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 6   |
| 3 | 6   |
| 1 | 10  |
| 4 | 10  |
| 4 | 10  |
| 1 | 10  |
| 2 | 9   |
| 5 | 9   |
| 2 | 9   |
+---+-----+
SELECT
  x,
  SUM(DISTINCT x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 3   |
| 3 | 3   |
| 1 | 5   |
| 4 | 5   |
| 4 | 5   |
| 1 | 5   |
| 2 | 7   |
| 5 | 7   |
| 2 | 7   |
+---+-----+

Funciones de agregación estadística

BigQuery admite las siguientes funciones de agregación estadística.

CORR

CORR(X1, X2)  [OVER (...)]

Descripción

Muestra el coeficiente de correlación de Pearson de un conjunto de pares de números. Para cada par de números, el primero es la variable dependiente y el segundo es la variable independiente. El resultado que se muestra está entre -1 y 1. Un resultado de 0 indica que no hay correlación.

Esta función ignora los pares de entrada que contengan uno o más valores NULL. Si hay menos de dos pares de entrada sin valores NULL, la función muestra NULL.

Tipos de entrada admitidos

FLOAT64

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipo de datos mostrados

FLOAT64

COVAR_POP

COVAR_POP(X1, X2)  [OVER (...)]

Descripción

Muestra la covarianza poblacional de un conjunto de pares de números. El primer número es la variable dependiente; el segundo es la variable independiente. El resultado que se muestra está entre -Inf y +Inf.

Esta función ignora los pares de entrada que contengan uno o más valores NULL. Si no hay ningún par de entrada sin valores NULL, esta función muestra NULL. Si hay un par de entrada sin valores NULL, esta función muestra 0.

Tipos de entrada admitidos

FLOAT64

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipo de datos mostrados

FLOAT64

COVAR_SAMP

COVAR_SAMP(X1, X2)  [OVER (...)]

Descripción

Muestra la covarianza de ejemplo de un conjunto de pares de números. El primer número es la variable dependiente; el segundo es la variable independiente. El resultado que se muestra está entre -Inf y +Inf.

Esta función ignora los pares de entrada que contengan uno o más valores NULL. Si hay menos de dos pares de entrada sin valores NULL, la función muestra NULL.

Tipos de entrada admitidos

FLOAT64

Cláusula opcional

OVER: Especifica una ventana. Consulta la sección sobre Funciones analíticas.

Tipo de datos mostrados

FLOAT64

STDDEV_POP

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

Descripción

Muestra la desviación estándar poblacional (sesgada) de los valores. El resultado que se muestra está entre 0 y +Inf.

Esta función ignora cualquier entrada NULL. Si se ignoran todas las entradas, esta función muestra NULL.

Si esta función recibe una entrada única que no es NULL, muestra 0.

Tipos de entrada admitidos

FLOAT64

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de STDDEV_POP().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipo de datos mostrados

FLOAT64

STDDEV_SAMP

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

Descripción

Muestra la desviación estándar muestral (imparcial) de los valores. El resultado que se muestra está entre 0 y +Inf.

Esta función ignora cualquier entrada NULL. Si hay menos de dos entradas que no sean NULL, esta función muestra NULL.

Tipos de entrada admitidos

FLOAT64

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de STDDEV_SAMP().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipo de datos mostrados

FLOAT64

STDDEV

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

Descripción

Un alias de STDDEV_SAMP.

VAR_POP

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

Descripción

Muestra la varianza poblacional (sesgada) de los valores. El resultado que se muestra está entre 0 y +Inf.

Esta función ignora cualquier entrada NULL. Si se ignoran todas las entradas, esta función muestra NULL.

Si esta función recibe una entrada única que no es NULL, muestra 0.

Tipos de entrada admitidos

FLOAT64

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de VAR_POP().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipo de datos mostrados

FLOAT64

VAR_SAMP

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

Descripción

Muestra la varianza muestral (imparcial) de los valores. El resultado que se muestra está entre 0 y +Inf.

Esta función ignora cualquier entrada NULL. Si hay menos de dos entradas que no sean NULL, esta función muestra NULL.

Tipos de entrada admitidos

FLOAT64

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. OVER: Especifica una ventana. Consulta Conceptos de funciones analíticas. En este momento, esta cláusula no es compatible con todas las otras cláusulas dentro de VAR_SAMP().
  2. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.

Tipo de datos mostrados

FLOAT64

VARIANCE

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

Descripción

Un alias de VAR_SAMP.

Funciones de agregación aproximada

Las funciones de agregación aproximada son escalables en términos de tiempo y uso de la memoria, pero generan resultados aproximados en lugar de resultados exactos. Para obtener más información, consulta la página sobre la agregación aproximada.

APPROX_COUNT_DISTINCT

APPROX_COUNT_DISTINCT(expression)

Descripción

Muestra el resultado aproximado para COUNT(DISTINCT expression). El valor que se mostró es una estimación estadística, no es necesariamente el valor real.

Esta función es menos precisa que COUNT(DISTINCT expression), pero funciona mejor en entradas grandes.

Tipos de argumentos admitidos

Cualquier tipo de datos excepto: ARRAY STRUCT

Tipos de datos mostrados

INT64

Ejemplos

SELECT APPROX_COUNT_DISTINCT(x) as approx_distinct
FROM UNNEST([0, 1, 1, 2, 3, 5]) as x;

+-----------------+
| approx_distinct |
+-----------------+
| 5               |
+-----------------+

APPROX_QUANTILES

APPROX_QUANTILES([DISTINCT] expression, number [{IGNORE|RESPECT} NULLS])

Descripción

Muestra los límites aproximados para un grupo de valores expression, en los que number representa la cantidad de cuantiles que se crearán. Esta función muestra un arreglo de number + 1 elementos, en el que el primer elemento es el mínimo aproximado y el último es el máximo aproximado.

Tipos de argumentos admitidos

expression puede ser cualquier tipo de datos admitido, excepto: ARRAY STRUCT

number debe ser INT64.

Cláusulas opcionales

Las cláusulas se aplican en el siguiente orden:

  1. DISTINCT: Cada valor distinto de expression se agrega solo una vez en el resultado.
  2. IGNORE NULLS o RESPECT NULLS: si se especifica o si no se especifica ninguno, los valores NULL se excluyen del resultado. Si se especifica RESPECT NULLS, los valores NULL se incluyen en el resultado (sin embargo, se genera un error si un arreglo en el resultado de la consulta final contiene un elemento NULL).

Tipos de datos mostrados

Un ARRAY del tipo especificado por el parámetro expression.

Muestra NULL si no hay filas de entrada o si expression se evalúa como NULL en todas las filas.

Ejemplos

SELECT APPROX_QUANTILES(x, 2) AS approx_quantiles
FROM UNNEST([1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 5, 10]       |
+------------------+
SELECT APPROX_QUANTILES(x, 100)[OFFSET(90)] AS percentile_90
FROM UNNEST([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) AS x;

+---------------+
| percentile_90 |
+---------------+
| 9             |
+---------------+
SELECT APPROX_QUANTILES(DISTINCT x, 2) AS approx_quantiles
FROM UNNEST([1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 6, 10]       |
+------------------+
SELECT FORMAT("%T", APPROX_QUANTILES(x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 4, 10]    |
+------------------+
SELECT FORMAT("%T", APPROX_QUANTILES(DISTINCT x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 6, 10]    |
+------------------+

APPROX_TOP_COUNT

APPROX_TOP_COUNT(expression, number)

Descripción

Muestra los elementos principales aproximados de expression. El parámetro number especifica la cantidad de elementos que se muestran.

Tipos de argumentos admitidos

expression puede ser de cualquier tipo de datos que admita la cláusula GROUP BY.

number debe ser INT64.

Tipos de datos mostrados

Un ARRAY del tipo STRUCT. El STRUCT contiene dos campos. El primer campo (llamado value) contiene un valor de entrada. El segundo campo (llamado count) contiene un INT64 que especifica la cantidad de veces que se mostró el valor.

Muestra NULL si no hay filas de entrada.

Ejemplos

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST(["apple", "apple", "pear", "pear", "pear", "banana"]) as x;

+-------------------------+
| approx_top_count        |
+-------------------------+
| [{pear, 3}, {apple, 2}] |
+-------------------------+

Manejo de NULL

APPROX_TOP_COUNT no ignora los NULL de la entrada. Por ejemplo:

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST([NULL, "pear", "pear", "pear", "apple", NULL]) as x;

+------------------------+
| approx_top_count       |
+------------------------+
| [{pear, 3}, {NULL, 2}] |
+------------------------+

APPROX_TOP_SUM

APPROX_TOP_SUM(expression, weight, number)

Descripción

Muestra los elementos principales aproximados de expression, en función de la suma de un weight asignado. El parámetro number especifica la cantidad de elementos que se muestran.

Si la entrada weight es negativa o si es NaN, esta función muestra un error.

Tipos de argumentos admitidos

expression puede ser de cualquier tipo de datos que admita la cláusula GROUP BY.

weight debe ser una de las siguientes opciones:

  • INT64
  • FLOAT64

number debe ser INT64.

Tipos de datos mostrados

Un ARRAY del tipo STRUCT. El STRUCT contiene dos campos: value y sum. El campo value contiene el valor de la expresión de entrada. El campo sum es del mismo tipo que weight y es la suma aproximada del peso de entrada asociado con el campo value.

Muestra NULL si no hay filas de entrada.

Ejemplos

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([
  STRUCT("apple" AS x, 3 AS weight),
  ("pear", 2),
  ("apple", 0),
  ("banana", 5),
  ("pear", 4)
]);

+--------------------------+
| approx_top_sum           |
+--------------------------+
| [{pear, 6}, {banana, 5}] |
+--------------------------+

Manejo de NULL

APPROX_TOP_SUM no ignora los valores NULL de los parámetros expression y weight.

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, NULL AS weight), ("pear", 0), ("pear", NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{pear, 0}, {apple, NULL}] |
+----------------------------+
SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, 2)]);

+-------------------------+
| approx_top_sum          |
+-------------------------+
| [{NULL, 2}, {apple, 0}] |
+-------------------------+
SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{apple, 0}, {NULL, NULL}] |
+----------------------------+

Funciones HyperLogLog++

BigQuery admite las siguientes funciones agregadas aproximadas mediante el uso del algoritmo HyperLogLog++. Para obtener una explicación de cómo operan las funciones agregadas aproximadas, consulta Agregación aproximada.

HLL_COUNT.INIT

HLL_COUNT.INIT(input [, precision])

Descripción

Una función agregada que toma uno o más valores input y los agrega en un boceto HyperLogLog++ . Cada boceto se representa con el tipo de datos BYTES. Luego, puedes combinar los bocetos con HLL_COUNT.MERGE o HLL_COUNT.MERGE_PARTIAL. Si no es necesaria la combinación, puedes extraer el recuento final de los valores distintos del boceto con HLL_COUNT.EXTRACT.

Esta función admite un parámetro opcional, precision. Este parámetro define la precisión de la estimación a costo de memoria adicional necesaria para procesar los bocetos o almacenarlos en el disco. La siguiente tabla muestra los valores de precisión permitidos, el tamaño máximo del boceto por grupo y el intervalo de confianza (IC) de las precisiones típicas:

Precisión Tamaño máx. del boceto (KiB) IC 65% IC 95% IC 99%
10 1 ±1.63% ±3.25% ±6.50%
11 2 ±1.15% ±2.30% ±4.60%
12 4 ±0.81% ±1.63% ±3.25%
13 8 ±0.57% ±1.15% ±1.72%
14 16 ±0.41% ±0.81% ±1.22%
15 (predeterminada) 32 ±0.29% ±0.57% ±0.86%
16 64 ±0.20% ±0.41% ±0.61%
17 128 ±0.14% ±0.29% ±0.43%
18 256 ±0.10% ±0.20% ±0.41%
19 512 ±0.07% ±0.14% ±0.29%
20 1,024 ±0.05% ±0.10% ±0.20%
21 2,048 ±0.04% ±0.07% ±0.14%
22 4,096 ±0.03% ±0.05% ±0.10%
23 8192 ±0.02% ±0.04% ±0.07%
24 16384 ±0.01% ±0.03% ±0.05%

Si la entrada es NULL, esta función muestra NULL.

Para obtener más información, consulta HyperLogLog en la práctica: Ingeniería algorítmica de un algoritmo de estimación de cardinalidad de última generación.

Tipos de entrada admitidos

INT64, NUMERIC, STRING, BYTES

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT
  HLL_COUNT.INIT(respondent) AS respondents_hll,
  flavor,
  country
FROM UNNEST([
  STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
  (1, "Chocolate", "CH"),
  (2, "Chocolate", "US"),
  (2, "Strawberry", "US")])
GROUP BY flavor, country;

HLL_COUNT.MERGE

HLL_COUNT.MERGE(sketch)

Descripción

Una función agregada que muestra la cardinalidad de varios bocetos de conjuntos HyperLogLog++ mediante el cálculo de su unión.

Cada sketch debe tener la misma precisión y debe inicializarse en el mismo tipo. Los intentos de combinar bocetos con diferentes precisiones o para diferentes tipos dan como resultado un error. Por ejemplo, no puedes combinar un boceto inicializado a partir de datos INT64 con uno inicializado a partir de datos STRING.

Esta función ignora los valores NULL durante la combinación de bocetos. Si la combinación se realiza en cero filas o solo en valores NULL, la función muestra 0.

Tipos de entrada admitidos

BYTES

Tipo de datos que se muestra

INT64

Ejemplo

SELECT HLL_COUNT.MERGE(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.MERGE_PARTIAL

HLL_COUNT.MERGE_PARTIAL(sketch)

Descripción

Una función agregada que toma uno o más datos de entrada de sketch HyperLogLog++ y las combina en un boceto nuevo.

Esta función muestra NULL si no hay entrada o si todas las entradas son NULL.

Tipos de entrada admitidos

BYTES

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT HLL_COUNT.MERGE_PARTIAL(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.EXTRACT

HLL_COUNT.EXTRACT(sketch)

Descripción

Una función escalar que extrae una estimación de cardinalidad de un solo boceto HyperLogLog++.

Si sketch es NULL, esta función muestra una estimación de cardinalidad de 0.

Tipos de entrada admitidos

BYTES

Tipo de datos que se muestra

INT64

Ejemplo

SELECT
  flavor,
  country,
  HLL_COUNT.EXTRACT(respondents_hll) AS num_respondents
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country);

+------------+---------+-----------------+
| flavor     | country | num_respondents |
+------------+---------+-----------------+
| Vanilla    | CH      | 1               |
| Chocolate  | CH      | 1               |
| Chocolate  | US      | 1               |
| Strawberry | US      | 1               |
+------------+---------+-----------------+

Funciones de numeración

En las secciones siguientes, se describen las funciones de numeración que admite BigQuery. Las funciones de numeración son un subconjunto de funciones analíticas. Para obtener una explicación de cómo operan las funciones analíticas, consulta Conceptos de funciones analíticas. Para obtener una descripción de cómo operan las funciones de numeración, consulta Conceptos de funciones de numeración.

A continuación, se detallan los requisitos de la cláusula OVER:

  • PARTITION BY: Es opcional.
  • ORDER BY: Obligatorio, excepto para ROW_NUMBER()
  • window_frame_clause: No permitido

RANK

Descripción

Muestra el rango ordinal (que se basa en 1) de cada fila dentro de la partición ordenada. Todas las filas del mismo nivel reciben el mismo valor de rango. La siguiente fila o conjunto de filas del mismo nivel recibe un valor de rango que aumenta según el número de filas del mismo nivel con el valor de rango anterior, en lugar de DENSE_RANK, que siempre aumenta en 1.

Tipos de argumentos admitidos

INT64

DENSE_RANK

Descripción

Muestra el rango ordinal (que se basa en 1) de cada fila dentro de la partición de la ventana. Todas las filas del mismo nivel reciben el mismo valor de rango y el valor de rango posterior se incrementa en uno.

Tipos de argumentos admitidos

INT64

PERCENT_RANK

Descripción

Muestra el rango percentil de una fila definida como (RK-1) o (NR-1), en el que RK es el RANK de la fila y NR es el número de filas en la partición. Muestra 0 si NR=1.

Tipos de argumentos admitidos

FLOAT64

CUME_DIST

Descripción

Muestra el rango relativo de una fila definida como NP o NR. NP se define como el número de filas que se encuentran antes o en el mismo nivel que la fila actual. NR es el número de filas en la partición.

Tipos de argumentos admitidos

FLOAT64

NTILE

NTILE(constant_integer_expression)

Descripción

Esta función divide las filas en depósitos constant_integer_expression según su orden y muestra el número de depósito que se basa en 1 asignado a cada fila. El número de filas en los depósitos puede variar como máximo en 1. Los valores de resto (el resto del número de filas dividido por los depósitos) se distribuyen uno por cada depósito, el primero es el depósito 1. Si constant_integer_expression se evalúa como NULL, 0 o negativo, se muestra un error.

Tipos de argumentos admitidos

INT64

ROW_NUMBER

Descripción

No requiere la cláusula ORDER BY. Muestra la fila secuencial ordinal (que se basa en 1) de cada fila para cada partición ordenada. Si no se especifica la cláusula ORDER BY, el resultado no es determinista.

Tipos de argumentos admitidos

INT64

Funciones de bits

BigQuery admite las funciones de bits siguientes.

BIT_COUNT

BIT_COUNT(expression)

Descripción

La entrada, expression, debe ser un número entero o BYTES.

Muestra el número de bits establecidos en la entrada expression. Para números enteros con signo, esta es la cantidad de bits en forma de complemento de a dos.

Tipo de datos mostrados

INT64

Ejemplo

SELECT a, BIT_COUNT(a) AS a_bits, FORMAT("%T", b) as b, BIT_COUNT(b) AS b_bits
FROM UNNEST([
  STRUCT(0 AS a, b'' AS b), (0, b'\x00'), (5, b'\x05'), (8, b'\x00\x08'),
  (0xFFFF, b'\xFF\xFF'), (-2, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFE'),
  (-1, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF'),
  (NULL, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF')
]) AS x;

+-------+--------+---------------------------------------------+--------+
| a     | a_bits | b                                           | b_bits |
+-------+--------+---------------------------------------------+--------+
| 0     | 0      | b""                                         | 0      |
| 0     | 0      | b"\x00"                                     | 0      |
| 5     | 2      | b"\x05"                                     | 2      |
| 8     | 1      | b"\x00\x08"                                 | 1      |
| 65535 | 16     | b"\xff\xff"                                 | 16     |
| -2    | 63     | b"\xff\xff\xff\xff\xff\xff\xff\xfe"         | 63     |
| -1    | 64     | b"\xff\xff\xff\xff\xff\xff\xff\xff"         | 64     |
| NULL  | NULL   | b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff" | 80     |
+-------+--------+---------------------------------------------+--------+

Funciones matemáticas

Todas las funciones matemáticas tienen los siguientes comportamientos:

  • Muestran NULL si alguno de los parámetros de entrada es .
  • Muestran NaN si alguno de los argumentos es .

ABS

ABS(X)

Descripción

Calcula el valor absoluto. Muestra un error si el argumento es un número entero y el valor de resultado no se puede representar como el mismo tipo; esto sucede solo para el valor de entrada negativo más grande, que no tiene una representación positiva. Muestra +inf para un argumento +/-inf.

SIGN

SIGN(X)

Descripción

Muestra -1, 0 o +1 para los argumentos negativos, de cero y positivos, respectivamente. Para argumentos de punto flotante, esta función no distingue entre cero positivo y negativo. Muestra NaN para un argumento NaN.

IS_INF

IS_INF(X)

Descripción

Muestra TRUE si el valor es infinito positivo o negativo. Muestra NULL para las entradas NULL.

IS_NAN

IS_NAN(X)

Descripción

Muestra TRUE si el valor es NaN. Muestra NULL para las entradas NULL.

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

Descripción

Divide X por Y; esta función nunca presenta errores. Muestra FLOAT64. A diferencia del operador de división (/), esta función no genera errores de divisiones por cero ni se desborda.

Casos especiales:

  • Si el resultado se desborda, muestra +/-inf.
  • Si Y=0 y X=0, muestra NaN.
  • Si Y=0 y X!=0, muestra +/-inf.
  • Si X = +/-inf y Y = , muestra NaN.

El comportamiento de IEEE_DIVIDE se ilustra con más detalle en la tabla a continuación.

Casos especiales de IEEE_DIVIDE

En la siguiente tabla, se enumeran los casos especiales de IEEE_DIVIDE.

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

RAND

RAND()

Descripción

Genera un valor seudoaleatorio de tipo FLOAT64 en el rango de [0, 1), el cual incluye 0 pero no 1.

SQRT

SQRT(X)

Descripción

Calcula la raíz cuadrada de X. Genera un error si X es menor que 0. Muestra +inf si X es +inf.

POW

POW(X, Y)

Descripción

Muestra el valor de X elevado a la potencia de Y. Si el resultado se subdesborda y no es representable, entonces la función muestra un valor de cero. Muestra un error si uno de los siguientes es verdadero:

  • X es un valor finito menor que 0 y, además, Y es un número no entero.
  • X es 0 y, también, Y es un valor finito menor que 0.

El comportamiento de POW() se ilustra con más detalle en la tabla a continuación.

POWER

POWER(X, Y)

Descripción

Sinónimo de POW().

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
Cualquiera, 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 número entero impar, +inf si es lo contrario
+inf Y < 0 0
+inf Y > 0 +inf

EXP

EXP(X)

Descripción

Calcula e elevado a X, también llamada función exponencial natural. Si el resultado se subdesborda, esta función muestra un cero. Genera un error si el resultado se desborda. Si X es +/-inf, entonces esta función muestra +inf o 0.

LN

LN(X)

Descripción

Calcula el logaritmo natural de X. Genera un error si X es menor o igual que cero. Si X es +inf, entonces esta función muestra +inf.

LOG

LOG(X [, Y])

Descripción

Si solo X está presente, LOG es un sinónimo de LN. Si Y también está presente, LOG calcula el logaritmo de X en base Y. Genera un error en los siguientes casos:

  • X es menor o igual que cero.
  • Y es 1.0.
  • Y es menor o igual que cero.

El comportamiento de LOG(X, Y) se ilustra con más detalle en la tabla a continuación.

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

LOG10

LOG10(X)

Descripción

Similar a LOG, pero calcula el logaritmo en base 10.

GREATEST

GREATEST(X1,...,XN)

Descripción

Muestra NULL si alguna de las entradas es . De lo contrario, muestra NaN si alguna de las entradas es NaN. Si no, muestra el valor más grande entre X1,…,XN según la comparación <.

LEAST

LEAST(X1,...,XN)

Descripción

Muestra NULL si alguna de las entradas es . Muestra NaN si alguna de las entradas es NaN. Si no, muestra el valor más pequeño entre X1,…,XN según la > comparación.

DIV

DIV(X, Y)

Descripción

Muestra el resultado de la división del número entero de X por Y. La división por cero muestra un error. La división por -1 se puede desbordar. Consulta la tabla a continuación para obtener tipos de resultados posibles.

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

Descripción

Equivale al operador de división (/), pero muestra NULL si se produce un error, como un error de división por cero.

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

Descripción

Equivalente al operador de multiplicación (*), pero muestra NULL si se produce un desbordamiento.

SAFE_NEGATE

SAFE_NEGATE(X)

Descripción

Equivalente al operador menos unario (-), pero muestra NULL si se produce un desbordamiento.

SAFE_ADD

SAFE_ADD(X, Y)

Descripción

Equivale al operador de suma (+), pero muestra NULL si se produce un desbordamiento.

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

Descripción

Equivalente al operador de resta (-), pero muestra NULL si se produce un desbordamiento.

MOD

MOD(X, Y)

Descripción

Función de módulo: muestra el resto de la división de X por Y. El valor que se muestra tiene el mismo signo que X. Se generará un error si Y es 0. Consulta la tabla a continuación para obtener tipos de resultados posibles.

ROUND

ROUND(X [, N])

Descripción

Si solo está presente X, ROUND redondea X al número entero más cercano. Si N está presente, ROUND redondea X a N decimales después del punto decimal. Si N es negativo, ROUND redondeará los dígitos a la izquierda del punto decimal. Se redondean casos de punto medio en dirección opuesta al cero. Genera un error si se produce un desbordamiento.

TRUNC

TRUNC(X [, N])

Descripción

Si solo está presente X, TRUNC redondea X al número entero más cercano cuyo valor absoluto no es mayor que el valor absoluto de X. Si N también está presente, TRUNC se comporta como ROUND(X, N), pero siempre se redondea hacia cero y nunca se desborda.

CEIL

CEIL(X)

Descripción

Muestra el valor integral más pequeño (con el tipo FLOAT64) que no es menor que X.

CEILING

CEILING(X)

Descripción

Sinónimo de CEIL(X)

FLOOR

FLOOR(X)

Descripción

Muestra el valor integral más grande (con el tipo FLOAT64) que no es mayor que X.

Ejemplo del comportamiento de la función de redondeo

Ejemplo del comportamiento de las funciones de redondeo de BigQuery:

Entrada “X” 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

COS

COS(X)

Descripción

Calcula el coseno de X, en el que X se especifica en radianes. Nunca falla.

COSH

COSH(X)

Descripción

Calcula el coseno hiperbólico de X, en el que X se especifica en radianes. Genera un error si se produce un desbordamiento.

ACOS

ACOS(X)

Descripción

Calcula el valor principal del coseno inverso de X. El valor de muestra está en el rango [0,π]. Genera un error si X es un valor fuera del rango [-1, 1].

ACOSH

ACOSH(X)

Descripción

Calcula el coseno hiperbólico inverso de X. Genera un error si X es un valor inferior a 1.

SIN

SIN(X)

Descripción

Calcula el seno de X, en el que X se especifica en radianes. Nunca falla.

SINH

SINH(X)

Descripción

Calcula el seno hiperbólico de X, en el que X se especifica en radianes. Genera un error si se produce un desbordamiento.

ASIN

ASIN(X)

Descripción

Calcula el valor principal del seno inverso de X. El valor que se muestra está en el rango [-π/2,π/2]. Genera un error si X está fuera del rango [-1, 1].

ASINH

ASINH(X)

Descripción

Calcula el seno hiperbólico inverso de X. No falla.

TAN

TAN(X)

Descripción

Calcula la tangente de X, en la que X se especifica en radianes. Genera un error si se produce un desbordamiento.

TANH

TANH(X)

Descripción

Calcula la tangente hiperbólica de X, en el que X se especifica en radianes. No falla.

ATAN

ATAN(X)

Descripción

Calcula el valor principal de la tangente inversa de X. El valor que se muestra está en el rango [-π/2,π/2]. No falla.

ATANH

ATANH(X)

Descripción

Calcula la tangente hiperbólica inversa de X. Genera un error si X está fuera del rango [-1, 1].

ATAN2

ATAN2(Y, X)

Descripción

Calcula el valor principal de la tangente inversa de Y/X con los signos de los dos argumentos para determinar el cuadrante. El valor que se muestra está en el rango [-π,π]. El comportamiento de esta función se ilustra con más detalle en la siguiente tabla.

Casos especiales de ATAN2()

Y X ATAN2(Y, X)
NaN Cualquier valor NaN
Cualquier valor NaN NaN
0 0 0, π o -π según el signo de X y de Y
Valor finito -inf π o -π según el signo de Y
Valor finito +inf 0
+/-inf Valor finito π/2 o π/2 según el signo de Y
+/-inf -inf ¾π o -¾π según el signo de Y
+/-inf +inf π/4 o -π/4 según el signo de Y

Casos especiales de funciones de redondeo hiperbólicas y trigonométricas

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

RANGE_BUCKET

RANGE_BUCKET(point, boundaries_array)

Descripción

RANGE_BUCKET examina un arreglo ordenado y muestra la posición basada en 0 del límite superior del punto. Esto puede ser útil si necesitas agrupar tus datos para compilar particiones, histogramas, reglas definidas por el negocio y mucho más.

RANGE_BUCKET sigue estas reglas:

  • Si el punto existe en el arreglo, muestra el índice del siguiente valor más grande.

    RANGE_BUCKET(20, [0, 10, 20, 30, 40]) -- 3 is return value
    RANGE_BUCKET(20, [0, 10, 20, 20, 40, 40]) -- 4 is return value
    
  • Si el punto no existe en el arreglo, pero oscila entre dos valores, muestra el índice del valor más grande.

    RANGE_BUCKET(25, [0, 10, 20, 30, 40]) -- 3 is return value
    
  • Si el punto es más pequeño que el primer valor del arreglo, muestra 0.

    RANGE_BUCKET(-10, [5, 10, 20, 30, 40]) -- 0 is return value
    
  • Si el punto es mayor o igual que el último valor del arreglo, muestra la longitud de este.

    RANGE_BUCKET(80, [0, 10, 20, 30, 40]) -- 5 is return value
    
  • Si el arreglo está vacío, muestra 0.

    RANGE_BUCKET(80, []) -- 0 is return value
    
  • Si el punto es NULL o NaN, muestra .

    RANGE_BUCKET(NULL, [0, 10, 20, 30, 40]) -- NULL is return value
    
  • El tipo de datos del punto y el arreglo debe ser compatible.

    RANGE_BUCKET('a', ['a', 'b', 'c', 'd']) -- 1 is return value
    RANGE_BUCKET(1.2, [1, 1.2, 1.4, 1.6]) -- 2 is return value
    RANGE_BUCKET(1.2, [1, 2, 4, 6]) -- execution failure
    

La falla de ejecución se produce en los siguientes casos:

  • El arreglo tiene un valor NaN o NULL.

    RANGE_BUCKET(80, [NULL, 10, 20, 30, 40]) -- execution failure
    
  • El arreglo no se ordenó de forma ascendente.

    RANGE_BUCKET(30, [10, 30, 20, 40, 50]) -- execution failure
    

Parámetros

  • point: Un valor genérico.
  • boundaries_array: Un arreglo genérico de valores.

Valor que se muestra

INT64

Ejemplos

En una tabla denominada students, verifica cuántos registros existirían en cada depósito de age_group, según la edad del alumno:

  • age_group 0 (age < 10)
  • age_group 1 (age >= 10, age < 20)
  • age_group 2 (age >= 20, age < 30)
  • age_group 3 (age >= 30)
WITH students AS
(
  SELECT 9 AS age UNION ALL
  SELECT 20 AS age UNION ALL
  SELECT 25 AS age UNION ALL
  SELECT 31 AS age UNION ALL
  SELECT 32 AS age UNION ALL
  SELECT 33 AS age
)
SELECT RANGE_BUCKET(age, [10, 20, 30]) AS age_group, COUNT(*) AS count
FROM students
GROUP BY 1

+--------------+-------+
| age_group    | count |
+--------------+-------+
| 0            | 1     |
| 2            | 2     |
| 3            | 3     |
+--------------+-------+

En las siguientes secciones, se describen las funciones de navegación que admite BigQuery. Las funciones de navegación son un subconjunto de funciones analíticas. Para obtener una explicación de cómo funcionan las funciones analíticas, consulta conceptos de funciones analíticas. Para obtener una explicación de cómo funcionan las funciones de navegación, consulta los conceptos de funciones de navegación.

FIRST_VALUE

FIRST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

Descripción

Muestra el valor de value_expression para la primera fila en el marco de ventana actual.

Esta función incluye valores NULL en el cálculo, a menos que IGNORE NULLS esté presente. Si IGNORE NULLS está presente, la función excluye los valores NULL del cálculo.

Tipos de argumentos admitidos

value_expression puede ser cualquier tipo de datos que pueda mostrar una expresión.

Tipo de datos mostrados

CUALQUIERA

Ejemplos

El siguiente ejemplo procesa el tiempo más rápido para cada división.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  TIMESTAMP_DIFF(finish_time, fastest_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  FIRST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS fastest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | fastest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 0                |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 436              |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 891              |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 956              |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 1109             |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 0                |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 426              |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 691              |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 733              |
+-----------------+-------------+----------+--------------+------------------+

LAST_VALUE

LAST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

Descripción

Muestra el valor de value_expression para la última fila en el marco de la ventana actual.

Esta función incluye valores NULL en el cálculo, a menos que IGNORE NULLS esté presente. Si IGNORE NULLS está presente, la función excluye los valores NULL del cálculo.

Tipos de argumentos admitidos

value_expression puede ser cualquier tipo de datos que pueda mostrar una expresión.

Tipo de datos mostrados

CUALQUIERA

Ejemplos

El siguiente ejemplo procesa el tiempo más lento para cada división.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', slowest_time) AS slowest_time,
  TIMESTAMP_DIFF(slowest_time, finish_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  LAST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS slowest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | slowest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 03:10:14     | 1109             |
| Nikki Leith     | 02:59:01    | F30-34   | 03:10:14     | 673              |
| Jen Edwards     | 03:06:36    | F30-34   | 03:10:14     | 218              |
| Meghan Lederer  | 03:07:41    | F30-34   | 03:10:14     | 153              |
| Lauren Reasoner | 03:10:14    | F30-34   | 03:10:14     | 0                |
| Lisa Stelzner   | 02:54:11    | F35-39   | 03:06:24     | 733              |
| Lauren Matthews | 03:01:17    | F35-39   | 03:06:24     | 307              |
| Desiree Berry   | 03:05:42    | F35-39   | 03:06:24     | 42               |
| Suzy Slane      | 03:06:24    | F35-39   | 03:06:24     | 0                |
+-----------------+-------------+----------+--------------+------------------+

NTH_VALUE

NTH_VALUE (value_expression, constant_integer_expression [{RESPECT | IGNORE} NULLS])

Descripción

Muestra el valor de value_expression en la enésima fila del marco de ventana actual, en el que N está definido por constant_integer_expression. Muestra NULL si no hay tal fila.

Esta función incluye valores NULL en el cálculo, a menos que IGNORE NULLS esté presente. Si IGNORE NULLS está presente, la función excluye los valores NULL del cálculo.

Tipos de argumentos admitidos

  • value_expression puede ser cualquier tipo de datos que se pueda mostrar a partir de una expresión.
  • constant_integer_expression puede ser cualquier expresión constante que muestre un número entero.

Tipo de datos mostrados

CUALQUIERA

Ejemplos

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  FORMAT_TIMESTAMP('%X', second_fastest) AS second_fastest
FROM (
  SELECT name,
  finish_time,
  division,finishers,
  FIRST_VALUE(finish_time)
    OVER w1 AS fastest_time,
  NTH_VALUE(finish_time, 2)
    OVER w1 as second_fastest
  FROM finishers
  WINDOW w1 AS (
    PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING));

+-----------------+-------------+----------+--------------+----------------+
| name            | finish_time | division | fastest_time | second_fastest |
+-----------------+-------------+----------+--------------+----------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | NULL           |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 02:59:01       |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 02:59:01       |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 02:59:01       |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 02:59:01       |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 02:59:01       |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 03:01:17       |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 03:01:17       |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 03:01:17       |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 03:01:17       |
+-----------------+-------------+----------+--------------+----------------+

LEAD

LEAD (value_expression[, offset [, default_expression]])

Descripción

Muestra el valor de value_expression en una fila posterior. Cambiar el valor de offset cambia qué fila posterior se muestra; el valor predeterminado es 1, que indica la siguiente fila en el marco de ventana. Si offset es NULL o un valor negativo, se produce un error.

Se usa la default_expression opcional si no hay una fila en el marco de la ventana del desplazamiento especificado. Esta expresión debe ser constante y su tipo debe ser coercible de forma implícita al tipo de value_expression. Si no se especifica, default_expression tiene el valor predeterminado NULL.

Tipos de argumentos admitidos

  • value_expression puede ser cualquier tipo de datos que se pueda mostrar a partir de una expresión.
  • offset debe ser un literal o parámetro de número entero no negativo.
  • default_expression debe ser compatible con el tipo de expresión de valor.

Tipo de datos mostrados

CUALQUIERA

Ejemplos

En el siguiente ejemplo, se ilustra un uso básico de la función LEAD.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS followed_by
FROM finishers;

+-----------------+-------------+----------+-----------------+
| name            | finish_time | division | followed_by     |
+-----------------+-------------+----------+-----------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL            |
| Sophia Liu      | 02:51:45    | F30-34   | Nikki Leith     |
| Nikki Leith     | 02:59:01    | F30-34   | Jen Edwards     |
| Jen Edwards     | 03:06:36    | F30-34   | Meghan Lederer  |
| Meghan Lederer  | 03:07:41    | F30-34   | Lauren Reasoner |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL            |
| Lisa Stelzner   | 02:54:11    | F35-39   | Lauren Matthews |
| Lauren Matthews | 03:01:17    | F35-39   | Desiree Berry   |
| Desiree Berry   | 03:05:42    | F35-39   | Suzy Slane      |
| Suzy Slane      | 03:06:24    | F35-39   | NULL            |
+-----------------+-------------+----------+-----------------+

En el siguiente ejemplo, se usa el parámetro opcional offset.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | NULL             |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL             |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | NULL             |
| Suzy Slane      | 03:06:24    | F35-39   | NULL             |
+-----------------+-------------+----------+------------------+

En el siguiente ejemplo, se reemplazan los valores NULL por un valor predeterminado.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody           |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | Nobody           |
| Lauren Reasoner | 03:10:14    | F30-34   | Nobody           |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | Nobody           |
| Suzy Slane      | 03:06:24    | F35-39   | Nobody           |
+-----------------+-------------+----------+------------------+

LAG

LAG (value_expression[, offset [, default_expression]])

Descripción

Muestra el valor de value_expression en una fila anterior. Cuando se cambia el valor de offset, cambia la fila anterior que se muestra; el valor predeterminado es 1, que indica la fila anterior en el marco de la ventana. Si offset es NULL o un valor negativo, se produce un error.

Se usa la default_expression opcional si no hay una fila en el marco de la ventana del desplazamiento especificado. Esta expresión debe ser constante y su tipo debe ser coercible de forma implícita al tipo de value_expression. Si no se especifica, default_expression tiene el valor predeterminado NULL.

Tipos de argumentos admitidos

  • value_expression puede ser cualquier tipo de datos que se pueda mostrar a partir de una expresión.
  • offset debe ser un literal o parámetro de número entero no negativo.
  • default_expression debe ser compatible con el tipo de expresión de valor.

Tipo de datos mostrados

CUALQUIERA

Ejemplos

En el siguiente ejemplo, se ilustra un uso básico de la función LAG.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS preceding_runner
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | preceding_runner |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | NULL             |
| Nikki Leith     | 02:59:01    | F30-34   | Sophia Liu       |
| Jen Edwards     | 03:06:36    | F30-34   | Nikki Leith      |
| Meghan Lederer  | 03:07:41    | F30-34   | Jen Edwards      |
| Lauren Reasoner | 03:10:14    | F30-34   | Meghan Lederer   |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL             |
| Lauren Matthews | 03:01:17    | F35-39   | Lisa Stelzner    |
| Desiree Berry   | 03:05:42    | F35-39   | Lauren Matthews  |
| Suzy Slane      | 03:06:24    | F35-39   | Desiree Berry    |
+-----------------+-------------+----------+------------------+

En el siguiente ejemplo, se usa el parámetro opcional offset.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL              |
| Sophia Liu      | 02:51:45    | F30-34   | NULL              |
| Nikki Leith     | 02:59:01    | F30-34   | NULL              |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL              |
| Lauren Matthews | 03:01:17    | F35-39   | NULL              |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

En el siguiente ejemplo, se reemplazan los valores NULL por un valor predeterminado.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody            |
| Sophia Liu      | 02:51:45    | F30-34   | Nobody            |
| Nikki Leith     | 02:59:01    | F30-34   | Nobody            |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | Nobody            |
| Lauren Matthews | 03:01:17    | F35-39   | Nobody            |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

PERCENTILE_CONT

PERCENTILE_CONT (value_expression, percentile [{RESPECT | IGNORE} NULLS])

Descripción

Calcula el valor de percentil especificado para value_expression con interpolación lineal.

Esta función ignora los valores NULL si RESPECT NULLS no está presente. Si RESPECT NULLS está presente:

  • La interpolación entre dos valores NULL muestra .
  • La interpolación entre un valor NULL y un valor no muestra el valor no .

Tipos de argumentos admitidos

  • value_expression es una expresión numérica.
  • percentile es un literal DOUBLE en el rango [0, 1].

Tipo de datos mostrados

DOUBLE

Ejemplos

El siguiente ejemplo procesa el valor para algunos percentiles de una columna de valores a la vez que ignora los valores nulos.

SELECT
  PERCENTILE_CONT(x, 0) OVER() AS min,
  PERCENTILE_CONT(x, 0.01) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5) OVER() AS median,
  PERCENTILE_CONT(x, 0.9) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+-----+-------------+--------+--------------+-----+
| min | percentile1 | median | percentile90 | max |
+-----+-------------+--------+--------------+-----+
| 0   | 0.03        | 1.5    | 2.7          | 3   |
+-----+-------------+--------+--------------+-----+

El siguiente ejemplo procesa el valor de algunos percentiles a partir de una columna de valores y respeta los valores nulos.

SELECT
  PERCENTILE_CONT(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_CONT(x, 0.01 RESPECT NULLS) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_CONT(x, 0.9 RESPECT NULLS) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+------+-------------+--------+--------------+-----+
| min  | percentile1 | median | percentile90 | max |
+------+-------------+--------+--------------+-----+
| NULL | 0           | 1      | 2.6          | 3   |
+------+-------------+--------+--------------+-----+

PERCENTILE_DISC

PERCENTILE_DISC (value_expression, percentile [{RESPECT | IGNORE} NULLS])

Descripción

Calcula el valor de percentil especificado para una value_expression discreta. El valor mostrado es el primer valor ordenado de value_expression con una distribución acumulada mayor o igual al valor de percentile dado.

Esta función ignora los valores NULL, a menos que RESPECT NULLS esté presente.

Tipos de argumentos admitidos

  • value_expression puede ser cualquier tipo que se pueda ordenar.
  • percentile es un literal DOUBLE en el rango [0, 1].

Tipo de datos mostrados

ANY

Ejemplos

El siguiente ejemplo procesa el valor para algunos percentiles de una columna de valores a la vez que ignora los valores nulos.

SELECT
  x,
  PERCENTILE_DISC(x, 0) OVER() AS min,
  PERCENTILE_DISC(x, 0.5) OVER() AS median,
  PERCENTILE_DISC(x, 1) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+-----+--------+-----+
| x    | min | median | max |
+------+-----+--------+-----+
| c    | a   | b      | c   |
| NULL | a   | b      | c   |
| b    | a   | b      | c   |
| a    | a   | b      | c   |
+------+-----+--------+-----+

El siguiente ejemplo procesa el valor de algunos percentiles a partir de una columna de valores y respeta los valores nulos.

SELECT
  x,
  PERCENTILE_DISC(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_DISC(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_DISC(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+------+--------+-----+
| x    | min  | median | max |
+------+------+--------+-----+
| c    | NULL | a      | c   |
| NULL | NULL | a      | c   |
| b    | NULL | a      | c   |
| a    | NULL | a      | c   |
+------+------+--------+-----+

Funciones analíticas de agregación

En las siguientes secciones, se describen las funciones analíticas agregadas que admite BigQuery. Para obtener una explicación de cómo operan las funciones analíticas, consulta Conceptos de funciones analíticas. Para obtener una explicación de cómo operan las funciones analíticas agregadas, consulta Conceptos de funciones analíticas agregadas.

BigQuery admite las siguientes funciones agregadas como funciones analíticas:

A continuación, se detallan los requisitos de la cláusula OVER:

  • PARTITION BY: Es opcional.
  • ORDER BY: Es opcional. No se permite si DISTINCT está presente.
  • window_frame_clause: Es opcional. No se permite si DISTINCT está presente.

Ejemplo:

COUNT(*) OVER (ROWS UNBOUNDED PRECEDING)
SUM(DISTINCT x) OVER ()

Funciones de generación de hash

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

Descripción

Calcula la huella digital de la entrada de STRING o BYTES con la función Fingerprint64 de la biblioteca de FarmHash de código abierto. El resultado de esta función para una entrada particular nunca cambiará.

Tipo de datos que se muestra

INT64

Ejemplos

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

MD5

MD5(input)

Descripción

Calcula el hash de la entrada mediante el uso del algoritmo MD5. La entrada puede ser STRING o BYTES. La versión de string trata a la entrada como un arreglo de bytes.

Esta función muestra 16 bytes.

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT MD5("Hello World") as md5;

+-------------------------------------------------+
| md5                                             |
+-------------------------------------------------+
| \xb1\n\x8d\xb1d\xe0uA\x05\xb7\xa9\x9b\xe7.?\xe5 |
+-------------------------------------------------+

SHA1

SHA1(input)

Descripción

Calcula el hash de la entrada mediante el uso del algoritmo SHA-1. La entrada puede ser STRING o BYTES. La versión de string trata a la entrada como un arreglo de bytes.

Esta función muestra 20 bytes.

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT SHA1("Hello World") as sha1;

+-----------------------------------------------------------+
| sha1                                                      |
+-----------------------------------------------------------+
| \nMU\xa8\xd7x\xe5\x02/\xabp\x19w\xc5\xd8@\xbb\xc4\x86\xd0 |
+-----------------------------------------------------------+

SHA256

SHA256(input)

Descripción

Calcula el hash de la entrada mediante el uso del algoritmo SHA-256. La entrada puede ser STRING o BYTES. La versión de string trata a la entrada como un arreglo de bytes.

Esta función muestra 32 bytes.

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

Descripción

Calcula el hash de la entrada mediante el uso del algoritmo SHA-512. La entrada puede ser STRING o BYTES. La versión de string trata a la entrada como un arreglo de bytes.

Esta función muestra 64 bytes.

Tipo de datos que se muestra

BYTES

Ejemplo

SELECT SHA512("Hello World") as sha512;

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_AGG(
  (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([code]) chr)
  ) ORDER BY OFFSET)) AS encoded_string
FROM UNNEST(TO_CODE_POINTS(b'Test String!')) code WITH OFFSET;

+----------------+
| 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 en un solo resultado.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos


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

BigQuery admite una función FORMAT() para formatear 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:

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 extensiones 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 Punto flotante decimal, minúsculas 392.65
infNaN
NUMERIC
FLOAT64
F Punto flotante decimal, mayúsculas 392.65
infNAN
NUMERIC
FLOAT64
e Notación científica (mantisa/exponente), minúsculas 3.9265e+2
infNaN
NUMERIC
FLOAT64
E Notación científica (mantisa/exponente), mayúsculas 3.9265E+2
infNAN
NUMERIC
FLOAT64
g Usa la representación más corta, %e o %f 392.65
FLOAT64
G Usa la representación más corta, %E o %F 392.65
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 la sección de %t a continuación. sample
2014‑01‑01
<any>
T Genera una string que es una constante válida de BigQuery con un tipo similar al del valor (puede ser más amplio o ser una string). Consulta la sección de %T a continuación. 'sample'
b'bytes sample'
1234
2.3
date '2014‑01‑01'
<any>
% “%%” genera un solo “%” % No corresponde

*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
# Se usa con especificadores o, x o X. Antepone 0, 0x o 0X a los valores distintos de cero, de forma respectiva
0 Rellena a la Izquierda el 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, 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: este es el número de dígitos que se imprimirá 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 %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: width es el ancho mínimo y la STRING se rellenará hasta alcanzar ese tamaño, mientras que precision es el ancho máximo del contenido que se debe mostrar y la STRING se truncará a ese tamaño, antes del relleno para el ancho.

%t siempre está destinado a ser una forma legible del valor.

%T es siempre 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
NUMERIC 123.0 (siempre con .0)NUMERIC "123.0"
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
STRUCT [value, value, …]
; aquí, los campos se formatean con %t
[value, value, …]
; aquí, los campos se formatean con %TCasos especiales: cero campos: STRUCT() Un campo: STRUCT(value)

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 . Cualquier otro argumento se ignora en este caso.

Por lo general, la función produce un valor NULL si hay un argumento 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 BigQuery convierte el tipo de estos valores en STRING. En %T, BigQuery muestra strings entre comillas para los valores FLOAT64 que no tienen representaciones literales que no sean de string.

FROM_BASE32

FROM_BASE32(string_expr)

Descripción

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

Tipo de datos que se muestra

BYTES

Ejemplo

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

+-----------+
| byte_data |
+-----------+
| abcde\xff |
+-----------+

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;

+------------------+
| byte_data        |
+------------------+
| \xde\xad\xbe\xef |
+------------------+

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;
+------------------+----------------------------------+
| hex_str          | bytes_str                        |
+------------------+----------------------------------+
| 0AF              | \x00\xaf                         |
| 00010203aaeeefff | \x00\x01\x02\x03\xaa\xee\xef\xff |
| 666f6f626172     | foobar                           |
+------------------+----------------------------------+

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

NORMALIZE

NORMALIZE(value[, normalization_mode])

Descripción

Toma una STRING, value, y la muestra como una string normalizada.

La normalización se usa para garantizar que dos strings sean equivalentes. La normalización suele usarse en situaciones en las que dos strings se renderizan de la misma forma en la pantalla, pero tienen puntos de código Unicode diferentes.

NORMALIZE admite cuatro modos de normalización opcionales:

Valor Nombre Descripción
NFC Composición canónica de la forma normalizada Descompone y recompone los caracteres por equivalencia canónica.
NFKC Composición de compatibilidad de la forma normalizada Descompone los caracteres por compatibilidad y los recompone por equivalencia canónica.
NFD Descomposición canónica de la forma normalizada Descompone los caracteres por equivalencia canónica, y múltiples caracteres de combinación se organizan en un orden específico.
NFKD Descomposición de compatibilidad de la forma normalizada Descompone los caracteres por compatibilidad, y múltiples caracteres de combinación se organizan en un orden específico.

El modo de normalización predeterminado es NFC.

Tipo de datos que se muestra

STRING

Ejemplos

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

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

En el siguiente ejemplo, se normalizan diferentes caracteres de espacio.

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

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

NORMALIZE_AND_CASEFOLD

NORMALIZE_AND_CASEFOLD(value[, normalization_mode])

Descripción

Toma una STRING, value, y realiza las mismas acciones que NORMALIZE, además de la combinación de mayúsculas y minúsculas para operaciones que no distinguen entre mayúsculas y minúsculas.

NORMALIZE_AND_CASEFOLD admite cuatro modos de normalización opcionales:

Valor Nombre Descripción
NFC Composición canónica de la forma normalizada Descompone y recompone los caracteres por equivalencia canónica.
NFKC Composición de compatibilidad de la forma normalizada Descompone los caracteres por compatibilidad y los recompone por equivalencia canónica.
NFD Descomposición canónica de la forma normalizada Descompone los caracteres por equivalencia canónica, y múltiples caracteres de combinación se organizan en un orden específico.
NFKD Descomposición de compatibilidad de la forma normalizada Descompone los caracteres por compatibilidad, y múltiples caracteres de combinación se organizan en un orden específico.

El modo de normalización predeterminado es NFC.

Tipo de datos que se muestra

STRING

Ejemplo

WITH Strings AS (
  SELECT '\u2168' AS a, 'IX' AS b UNION ALL
  SELECT '\u0041\u030A', '\u00C5'
)
SELECT a, b,
  NORMALIZE_AND_CASEFOLD(a, NFD)=NORMALIZE_AND_CASEFOLD(b, NFD) AS nfd,
  NORMALIZE_AND_CASEFOLD(a, NFC)=NORMALIZE_AND_CASEFOLD(b, NFC) AS nfc,
  NORMALIZE_AND_CASEFOLD(a, NFKD)=NORMALIZE_AND_CASEFOLD(b, NFKD) AS nkfd,
  NORMALIZE_AND_CASEFOLD(a, NFKC)=NORMALIZE_AND_CASEFOLD(b, NFKC) AS nkfc
FROM Strings;

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

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regex)

Descripción

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

Si el argumento regex 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 $.

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
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

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

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

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

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

Descripción

Muestra la primera substring de value que coincide con la expresión regular, regex. 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.

Tipo de datos que se muestra

STRING o BYTES

Ejemplos


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

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

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

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

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

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

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regex)

Descripción

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

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.

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, regex, replacement)

Descripción

Muestra una STRING en la que todas las substrings de value que coinciden con la expresión regular regex 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 regex. Usa \0 para hacer referencia a todo el texto coincidente.

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 regex no es una expresión regular válida, esta función muestra un error.

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 . 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 "a b c d" as letter_group
  UNION ALL
  SELECT "e f g h" as letter_group
  UNION ALL
  SELECT "i j k l" as letter_group)

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

+----------------------+
| example              |
+----------------------+
| [a, b, c, d]         |
| [e, f, g, h]         |
| [i, j, k, l]         |
+----------------------+

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
    "foo@example.com" AS email_address
  UNION ALL
  SELECT
    "foobar@example.com" AS email_address
  UNION ALL
  SELECT
    "foobarbaz@example.com" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

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

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

SUBSTR

SUBSTR(value, position[, length])

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 ( = 0 o  < -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_BASE32

TO_BASE32(bytes_expr)

Descripción

Convierte una secuencia de BYTES en una STRING codificada en base32. Para convertir una STRING codificada en base32 en BYTES, usa FROM_BASE32.

Tipo de datos que se muestra

STRING

Ejemplo

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

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

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       |
+----------------------------------+------------------+
| foobar                           | 666f6f626172     |
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
+----------------------------------+------------------+

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 .

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

Funciones JSON

BigQuery admite funciones que te ayudan a recuperar datos almacenados en strings con formato JSON y funciones que te ayudan a transformar datos en strings con formato JSON.

JSON_EXTRACT o JSON_EXTRACT_SCALAR

JSON_EXTRACT(json_string_expr, json_path_string_literal), que muestra valores JSON como STRING.

JSON_EXTRACT_SCALAR(json_string_expr, json_path_string_literal), que muestra valores JSON escalares como STRING.

Descripción

El parámetro json_string_expr debe ser una string con formato JSON. Por ejemplo:

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

El parámetro json_path_string_literal identifica los valores que deseas obtener de la string con formato JSON. Debes construir este parámetro mediante el uso del formato JSONPath. Como parte de este formato, este parámetro debe comenzar con un símbolo $, que hace referencia al nivel más externo de la string con formato JSON. Puedes identificar valores secundarios mediante la notación de puntos o corchetes. Si el objeto JSON es un arreglo, puedes usar corchetes para especificar el índice del arreglo.

JSONPath Descripción
$ Objeto o elemento raíz
. o [] Operador secundario
[] Operador subíndice

Ambas funciones muestran NULL si el parámetro json_path_string_literal no coincide con un valor en json_string_expr. Si el valor seleccionado para JSON_EXTRACT_SCALAR no es escalar, como un objeto o un arreglo, la función muestra NULL.

Si JSONPath no es válido, estas funciones generan un error.

En los casos en los que una clave JSON usa caracteres JSONPath no válidos, puedes escapar esos caracteres mediante el uso de comillas simples y corchetes, [' ']. Por ejemplo:

SELECT JSON_EXTRACT_SCALAR('{"a.b": {"c": "world"}}', "$['a.b'].c") as hello;

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

Ejemplos

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

La consulta anterior arroja el siguiente resultado:

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

La consulta anterior arroja el siguiente resultado:

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

La consulta anterior arroja el siguiente resultado:

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

La consulta anterior arroja el siguiente resultado:

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+
SELECT JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

La consulta anterior arroja el siguiente resultado:

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

TO_JSON_STRING

TO_JSON_STRING(value[, pretty_print])

Descripción

Muestra una representación de una string con formato JSON de value. Esta función admite un parámetro pretty_print opcional. Si pretty_print está presente, el valor que se muestra tiene un formato para una lectura fácil.

Tipo de datos de entrada Valor mostrado
NULL de cualquier tipo null
BOOL true o false.
INT64

Lo mismo que CAST(value AS STRING) cuando value está en el rango de [-253, 253], que es el rango de números enteros que se pueden representar sin pérdidas como números de puntos flotante de precisión doble IEEE 754. Los valores fuera de este rango se representan como strings entre comillas. Por ejemplo:

-1
0
12345678901
9007199254740992
-9007199254740992
"9007199254740993"

9007199254740993 es mayor que 253, por lo que se representa como una string entre comillas.

NUMERIC

Igual que CAST(value AS STRING) cuando value está en el rango de [-253, 253] y no tiene parte fraccionaria. Los valores fuera de este rango se representan como strings entre comillas. Por ejemplo:

-1
0
"9007199254740993"
"123.56"
FLOAT64 +/-inf y NaN se representan como Infinity, -Infinity y NaN, respectivamente.

De lo contrario, es lo mismo que CAST(value AS STRING).

STRING Valor de string entre comillas, evitado según el estándar JSON. En específico, se escapan ", \ y los caracteres de control de U+0000 a U+001F.
BYTES

Valor evitado RFC 4648 de base64. Por ejemplo:

"R29vZ2xl" es la representación en base64 de los bytes b"Google"

DATE

Fecha entre comillas. Por ejemplo:

"2017-03-06"
TIMESTAMP

Fecha y hora ISO 8601 entre comillas, donde T separa la fecha y hora y Zulu/UTC representa la zona horaria. Por ejemplo:

"2017-03-06T12:34:56.789012Z"
DATETIME

Fecha y hora ISO 8601 entre comillas, donde T separa la fecha y hora. Por ejemplo:

"2017-03-06T12:34:56.789012"
TIME

Hora ISO 8601 entre comillas. Por ejemplo:

"12:34:56.789012"
ARRAY

[elem1,elem2,...], en el que cada elem se formatea según el tipo de elemento.

Ejemplo con formato:

[
  elem1,
  elem2,
  ...
]

Donde cada elem está formateado según el tipo de elemento. El arreglo vacío se representa como [].

STRUCT {"field_name1":field_value1,"field_name2":field_value2,...}

Donde cada field_value se formatea según su tipo.

Ejemplo con formato:

{
  "field_name1": field_value1,
  "field_name2": field_value2,
  ...
}

Donde cada field_value se formatea según su tipo. Si un field_value es un ARRAY o STRUCT que no está vacío, los elementos se sangran al nivel adecuado. El struct vacío se representa como {}.

Los campos con nombres duplicados pueden dar como resultado JSON no analizable. Los campos anónimos se representan con "".

Los nombres de campo UTF-8 no válidos pueden dar como resultado JSON no analizable. Los valores de string se escapan según el estándar JSON. En específico, se escapan ", \ y los caracteres de control de U+0000 a U+001F.

Tipo de datos que se muestra

Representación de la string JSON del valor.

Ejemplos

Convertir las filas en una tabla a JSON.

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  t,
  TO_JSON_STRING(t) AS json_row
FROM Input AS t;

La consulta anterior arroja el siguiente resultado:

+-----------------------------------+-------------------------------------------------------+
| t                                 | json_row                                              |
+-----------------------------------+-------------------------------------------------------+
| {[1, 2], foo, {true, 2017-04-05}} | {"x":[1,2],"y":"foo","s":{"a":true,"b":"2017-04-05"}} |
| {NULL, , {false, 0001-01-01}}     | {"x":null,"y":"","s":{"a":false,"b":"0001-01-01"}}    |
| {[3], bar, {NULL, 2016-12-05}}    | {"x":[3],"y":"bar","s":{"a":null,"b":"2016-12-05"}}   |
+-----------------------------------+-------------------------------------------------------+

Convertir filas en una tabla a JSON con formato.

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  TO_JSON_STRING(t, true) AS json_row
FROM Input AS t;

La consulta anterior arroja el siguiente resultado:

+-----------------------+
| json_row              |
+-----------------------+
| {                     |
|  "x": [               |
|    1,                 |
|    2                  |
|  ],                   |
|  "y": "foo",          |
|  "s": {               |
|    "a": true,         |
|    "b": "2017-04-05"  |
|  }                    |
|}                      |
| {                     |
|  "x": null,           |
|  "y": "",             |
|  "s": {               |
|    "a": false,        |
|    "b": "0001-01-01"  |
|  }                    |
|}                      |
| {                     |
|  "x": [               |
|    3                  |
|  ],                   |
|  "y": "bar",          |
|  "s": {               |
|    "a": null,         |
|    "b": "2016-12-05"  |
|  }                    |
|}                      |
+-----------------------+

Funciones de arreglo

ARRAY

ARRAY(subquery)

Descripción

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

Si la subquery genera una tabla de SQL, la tabla debe tener una sola columna. Cada elemento en el ARRAY de salida es el valor de la única columna de una fila en la tabla.

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

Limitaciones

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

Tipo de datos que se muestra

ARRAY

Ejemplos

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

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

Si deseas construir un ARRAY a partir de una subconsulta que contiene varias columnas, debes modificar la subconsulta para usar SELECT AS STRUCT. Ahora, la función ARRAY mostrará un ARRAY de STRUCT. El ARRAY contendrá un valor STRUCT por cada fila de la subconsulta y cada uno de estos valores STRUCT contendrá un campo por cada columna de 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 la misma forma, para construir un ARRAY a partir de una subconsulta que contiene uno o más , 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_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

Descripción

Concatena uno o más arreglos con el mismo tipo de elemento en un solo arreglo.

Tipo de datos que se muestra

ARRAY

Ejemplos

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

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

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Descripción

Muestra el tamaño del arreglo. Muestra 0 para un arreglo vacío. Muestra NULL si la array_expression es NULL.

Tipo de datos que se muestra

INT64

Ejemplos

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

SELECT list, ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

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

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

Descripción

Muestra una concatenación de los elementos en la array_expression como una STRING. El valor de la array_expression puede ser un arreglo de tipos de datos STRING o BYTES.

Si se usa el parámetro null_text, la función reemplaza cualquier valor NULL en el arreglo por el valor de .

Si no se usa el parámetro null_text, la función omite el valor NULL y su delimitador anterior.

Ejemplos

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

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

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

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

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

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

Descripción

Muestra un arreglo de valores. Los parámetros start_expression y end_expression determinan el inicio y el final inclusivos del arreglo.

La función GENERATE_ARRAY acepta los siguientes tipos de datos como entradas:

  • INT64
  • NUMERIC
  • FLOAT64

El parámetro step_expression determina el incremento que se usa para generar valores de arreglo. El valor predeterminado para este parámetro es 1.

Esta función muestra un error si step_expression se establece en 0 o si alguna entrada es NaN.

Si algún argumento es NULL, la función mostrará un arreglo .

Tipo de datos mostrados

ARRAY

Ejemplos

En el siguiente ejemplo, se muestra un arreglo de números enteros, con un paso predeterminado de 1.

SELECT GENERATE_ARRAY(1, 5) AS example_array;

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

A continuación, se muestra un arreglo con un tamaño del paso especificado por el usuario.

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

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

A continuación, se muestra un arreglo con un valor negativo, -3, como su tamaño del paso.

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

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

A continuación, se muestra un arreglo con el mismo valor para start_expression y end_expression.

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

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

En el siguiente ejemplo, se muestra un arreglo vacío porque start_expression es mayor que end_expression, y el valor step_expression es positivo.

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

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

En el siguiente ejemplo, se muestra un arreglo NULL porque la end_expression es .

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

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

En el siguiente ejemplo, se muestran múltiples arreglos.

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

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

GENERATE_DATE_ARRAY

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

Descripción

Muestra un arreglo de fechas. Los parámetros start_date y end_date determinan el inicio y el final inclusivos del arreglo.

La función GENERATE_DATE_ARRAY acepta los siguientes tipos de datos como entradas:

  • start_date debe ser DATE.
  • end_date debe ser DATE.
  • INT64_expr debe ser INT64.
  • date_part debe ser DAY, WEEK, MONTH, QUARTER o YEAR.

El parámetro INT64_expr determina el incremento que se usa para generar fechas. El valor predeterminado para este parámetro es de 1 día.

Esta función muestra un error si INT64_expr se establece en 0.

Tipo de datos mostrados

Un ARRAY que contiene 0 o más valores DATE.

Ejemplos

A continuación, se muestra un arreglo de fechas con un paso predeterminado de 1.

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

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

A continuación, se muestra un arreglo con un tamaño del paso especificado por el usuario.

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

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

A continuación, se muestra un arreglo con un valor negativo, -3, como su tamaño del paso.

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

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

En el siguiente ejemplo, se muestra un arreglo con el mismo valor para start_date y end_date.

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

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

En el siguiente ejemplo, se muestra un arreglo vacío porque start_date es mayor que end_date, y el valor step es positivo.

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

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

En el siguiente ejemplo, se muestra un arreglo NULL porque una de sus entradas es .

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

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

En el siguiente ejemplo, se muestra un arreglo de fechas con MONTH como el intervalo date_part:

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

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

En el siguiente ejemplo, se usan fechas no constantes para generar un arreglo.

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

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

GENERATE_TIMESTAMP_ARRAY

GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp,
                         INTERVAL step_expression date_part)

Descripción

Muestra un ARRAY de TIMESTAMPS separados por un intervalo determinado. Los parámetros start_timestamp y end_timestamp determinan los límites inferiores y superiores inclusivos del ARRAY.

La función GENERATE_TIMESTAMP_ARRAY acepta los siguientes tipos de datos como entradas:

  • start_timestamp: TIMESTAMP
  • end_timestamp: TIMESTAMP
  • step_expression: INT64
  • Los valores de date_part permitidos son los siguientes:

    MICROSECOND, MILLISECOND,

    SECOND, MINUTE, HOUR o DAY.

El parámetro step_expression determina el incremento que se usa para generar marcas de tiempo.

Tipo de datos mostrados

Un ARRAY que contiene 0 o más valores de TIMESTAMP.

Ejemplos

En el siguiente ejemplo, se muestra un ARRAY de TIMESTAMP en intervalos de 1 día.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-07 00:00:00',
                                INTERVAL 1 DAY) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-06 00:00:00+00, 2016-10-07 00:00:00+00] |
+--------------------------------------------------------------------------+

En el siguiente ejemplo, se muestra un ARRAY de TIMESTAMP en intervalos de 1 segundo.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:02',
                                INTERVAL 1 SECOND) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 00:00:01+00, 2016-10-05 00:00:02+00] |
+--------------------------------------------------------------------------+

En el siguiente ejemplo, se muestra un ARRAY de TIMESTAMPS con un intervalo negativo.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-01 00:00:00',
                                INTERVAL -2 DAY) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-06 00:00:00+00, 2016-10-04 00:00:00+00, 2016-10-02 00:00:00+00] |
+--------------------------------------------------------------------------+

En el siguiente ejemplo, se muestra un ARRAY con un solo elemento, porque start_timestamp y end_timestamp tienen el mismo valor.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+--------------------------+
| timestamp_array          |
+--------------------------+
| [2016-10-05 00:00:00+00] |
+--------------------------+

En el siguiente ejemplo, se muestra un ARRAY vacío, porque start_timestamp es posterior a end_timestamp.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| []              |
+-----------------+

En el siguiente ejemplo, se muestra un ARRAY nulo porque una de las entradas es NULL.

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', NULL, INTERVAL 1 HOUR)
  AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| NULL            |
+-----------------+

En el siguiente ejemplo, se generan ARRAY de TIMESTAMP a partir de columnas que contienen valores de start_timestamp y end_timestamp.

SELECT GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp, INTERVAL 1 HOUR)
  AS timestamp_array
FROM
  (SELECT
    TIMESTAMP '2016-10-05 00:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 02:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 12:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 14:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 23:59:00' AS start_timestamp,
    TIMESTAMP '2016-10-06 01:59:00' AS end_timestamp);

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 01:00:00+00, 2016-10-05 02:00:00+00] |
| [2016-10-05 12:00:00+00, 2016-10-05 13:00:00+00, 2016-10-05 14:00:00+00] |
| [2016-10-05 23:59:00+00, 2016-10-06 00:59:00+00, 2016-10-06 01:59:00+00] |
+--------------------------------------------------------------------------+

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 lo muestra. OFFSET significa que la numeración comienza en cero, ORDINAL significa que comienza en uno.

Un arreglo dado puede interpretarse como basado en 0 o en 1. Cuando accedes a un elemento de arreglo, debes anteponer la posición del arreglo con OFFSET o con ORDINAL, de forma respectiva; no hay comportamiento predeterminado.

OFFSET y ORDINAL generan un error si el índice está fuera de rango.

Tipo de datos que se muestra

Varía según los elementos en el ARRAY.

Ejemplos

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

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

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

ARRAY_REVERSE

ARRAY_REVERSE(value)

Descripción

Muestra el ARRAY de entrada con los elementos en orden inverso.

Tipo de datos que se muestra

ARRAY

Ejemplos

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

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

SAFE_OFFSET y SAFE_ORDINAL

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

Descripción

Idéntico a OFFSET y ORDINAL, excepto que muestra NULL si el índice está fuera de rango.

Tipo de datos que se muestra

Varía según los elementos en el ARRAY.

Ejemplo

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

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

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

Funciones de fecha

BigQuery admite las siguientes funciones DATE.

CURRENT_DATE

CURRENT_DATE([time_zone])

Descripción

Muestra la fecha actual de la zona horaria especificada o predeterminada.

Esta función admite un parámetro time_zone opcional. Este parámetro es una string que representa la zona horaria que se debe usar. Si no se especifica una zona horaria, se usa la predeterminada, UTC. Consulta las Definiciones de la zona horaria para obtener información sobre cómo especificar una zona horaria.

Si el parámetro time_zone se evalúa como NULL, esta función muestra NULL.

Tipo de datos mostrados

DATE

Ejemplo

SELECT CURRENT_DATE() as the_date;

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

EXTRACT

EXTRACT(part FROM date_expression)

Descripción

Muestra el valor correspondiente a la parte de fecha especificada. El valor part debe ser uno de los siguientes:

  • DAYOFWEEK: muestra valores en el rango [1,7] con el domingo como primer día de la semana.
  • DAY
  • DAYOFYEAR
  • WEEK: muestra el número de semana de la fecha en el rango [0, 53]. Las semanas comienzan con el domingo y las fechas anteriores al primer domingo del año están en la semana 0.
  • WEEK(<WEEKDAY>): muestra el número de semana de la fecha en el rango [0, 53]. Las semanas comienzan el WEEKDAY. Las fechas anteriores al primer WEEKDAY del año están en la semana 0. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: Muestra el número de semana ISO 8601 de date_expression. Los valores ISOWEEK comienzan el lunes. Los valores de muestra están en el rango [1, 53]. El primer valor ISOWEEK de cada año ISO comienza el lunes anterior al primer jueves del año del calendario gregoriano.
  • MONTH
  • QUARTER: muestra valores en el rango [1,4].
  • YEAR
  • ISOYEAR: muestra el año de numeración de la semana ISO 8601, que es el año calendario gregoriano que contiene el jueves de la semana a la que pertenece date_expression.

Tipo de datos mostrados

INT64

Ejemplos

En el siguiente ejemplo, EXTRACT muestra un valor que corresponde a la parte de tiempo DAY.

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

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

En el siguiente ejemplo, EXTRACT muestra valores correspondientes a diferentes partes de tiempo de una columna de fechas cerca del final del año.

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

En el siguiente ejemplo, date_expression es un domingo. EXTRACT calcula la primera columna mediante las semanas que comienzan los días domingo y calcula la segunda columna con las semanas que comienzan los días lunes.

WITH table AS (SELECT DATE('2017-11-05') AS date)
SELECT
  date,
  EXTRACT(WEEK(SUNDAY) FROM date) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM date) AS week_monday FROM table;

+------------+-------------+-------------+
| date       | week_sunday | week_monday |
+------------+-------------+-------------+
| 2017-11-05 | 45          | 44          |
+------------+-------------+-------------+

DATE

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

Descripción

  1. Construye un valor DATE a partir de los valores INT64 que representan el año, mes y día.
  2. Extrae la DATE de una expresión de TIMESTAMP. Admite un parámetro opcional para especificar una zona horaria. Si no se especifica una zona horaria, se usa la predeterminada, UTC.
  3. Extrae la DATE de una expresión de DATETIME.

Tipo de datos mostrados

DATE

Ejemplo

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

+------------+------------+------------+
| date_ymd   | date_dt    | date_tstz  |
+------------+------------+------------+
| 2016-12-25 | 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 un valor DATE.

DATE_ADD admite los siguientes valores date_part:

  • DAY
  • WEEK, que equivale a 7 DAY
  • MONTH
  • QUARTER
  • YEAR

Se requiere un manejo especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes o está cerca de este. Si el mes del resultado tiene menos días que el de la fecha original, el día del resultado será el último día del nuevo mes.

Tipo de datos mostrados

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 un valor DATE.

DATE_SUB admite los siguientes valores date_part:

  • DAY
  • WEEK, que equivale a 7 DAY
  • MONTH
  • QUARTER
  • YEAR

Se requiere un manejo especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes o está cerca de este. Si el mes del resultado tiene menos días que el de la fecha original, el día del resultado será el último día del nuevo mes.

Tipo de datos mostrados

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

Muestra el número de límites de date_part entre las dos date_expression. Si la primera fecha se encuentra antes de la segunda, el resultado no será positivo.

DATE_DIFF admite los siguientes valores date_part:

  • DAY
  • WEEK: esta parte de fecha comienza el domingo.
  • WEEK(<WEEKDAY>): Esta parte de fecha comienza el WEEKDAY. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: Usa los límites de la semana ISO 8601. Las semanas ISO comienzan el lunes.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: Usa el límite del año de numeración de semana ISO 8601. El límite del año ISO es el lunes de la primera semana cuyo jueves pertenece al año calendario gregoriano correspondiente.

Tipo de datos mostrados

INT64

Ejemplo

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

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

SELECT
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', DAY) as days_diff,
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', WEEK) as weeks_diff;

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

En el ejemplo anterior, se muestra el resultado de DATE_DIFF durante dos días seguidos. DATE_DIFF con la parte de fecha WEEK muestra 1 porque DATE_DIFF cuenta el número de límites de parte de fecha en este rango de fechas. Cada WEEK comienza el domingo, por lo que hay un límite de parte de fecha entre el sábado, 2017-10-14, y el domingo, 2017-10-15.

En el siguiente ejemplo, se muestra el resultado de DATE_DIFF para dos fechas en años diferentes. DATE_DIFF con la parte de fecha YEAR muestra 3 porque cuenta el número de límites del año calendario gregoriano entre las dos fechas. DATE_DIFF con la parte de fecha ISOYEAR muestra 2 porque la segunda fecha pertenece al año ISO 2015. El primer jueves del año calendario 2015 fue 2015-01-01, por lo que el año ISO 2015 comienza el lunes anterior, 2014-12-29.

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

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

En el siguiente ejemplo, se muestra el resultado de DATE_DIFF para dos días seguidos. La primera fecha es un lunes y la segunda es un domingo. DATE_DIFF con la parte de fecha WEEK muestra 0 porque esta parte de tiempo usa semanas que comienzan el domingo. DATE_DIFF con la parte de fecha WEEK(MONDAY) muestra 1. DATE_DIFF con la parte de fecha ISOWEEK también muestra 1 porque las semanas ISO comienzan el lunes.

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

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

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Descripción

Trunca la fecha al nivel de detalle especificado.

DATE_TRUNC admite los siguientes valores para date_part:

  • DAY
  • WEEK
  • WEEK(<WEEKDAY>): trunca date_expression al límite de la semana anterior, en el que las semanas comienzan en WEEKDAY. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: trunca date_expression al límite de la semana ISO 8601 anterior. Los valores comienzan el lunes. El primer ISOWEEK de cada año ISO contiene el primer jueves del año calendario gregoriano correspondiente. Cualquier valor date_expression anterior a esto se truncará al lunes anterior.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: trunca date_expression al límite de año de numeración de la semana ISO 8601. El límite del año ISO es el lunes de la primera semana cuyo jueves pertenece al año calendario gregoriano correspondiente.

Tipo de datos mostrados

DATE

Ejemplos

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

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

En el siguiente ejemplo, la fecha original es un domingo. Debido a que date_part es WEEK(MONDAY), DATE_TRUNC muestra DATE para el lunes anterior.

SELECT date AS original, DATE_TRUNC(date, WEEK(MONDAY)) AS truncated
FROM (SELECT DATE('2017-11-05') AS date);

+------------+------------+
| original   | truncated  |
+------------+------------+
| 2017-11-05 | 2017-10-30 |
+------------+------------+

En el siguiente ejemplo, el valor date_expression original está en el año calendario gregoriano 2015. Sin embargo, DATE_TRUNC con la parte de fecha ISOYEAR trunca el valor date_expression al comienzo del año ISO, no el año calendario gregoriano. El primer jueves del año calendario 2015 fue 2015-01-01, por lo que el año ISO 2015 comienza el lunes anterior, 2014-12-29. Por lo tanto, el límite del año ISO que precede al valor date_expression 2015-06-15 es 2014-12-29.

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

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

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(INT64_expression)

Descripción

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

Tipo de datos mostrados

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

Da formato a date_expr de acuerdo con el format_string especificado.

Consulta la sección sobre elementos de formato admitidos para DATE a fin de obtener una lista de los elementos de formato que admite esta función.

Tipo de datos mostrados

STRING

Ejemplos

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

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

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

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

PARSE_DATE

PARSE_DATE(format_string, date_string)

Descripción

Usa format_string y una representación de string de una fecha para mostrar un objeto DATE.

Cuando uses PARSE_DATE, ten en cuenta lo siguiente:

  • Campos sin especificar. Todo campo sin especificar se inicializa desde 1970-01-01.
  • Nombres sin distinción 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 string que coinciden con cero o más espacios en blanco consecutivos en la string de fecha. Además, los espacios en blanco iniciales y finales en la string de fecha siempre están permitidos, incluso si no están en la string de formato.
  • Precedencia del formato. Cuando dos (o más) elementos de formato tienen información superpuesta (por ejemplo, si %F y %Y afectan el año), por lo general, el último anula los anteriores.

Tipo de datos mostrados

DATE

Ejemplo

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

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

UNIX_DATE

UNIX_DATE(date_expression)

Descripción

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

Tipo de datos mostrados

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 strings 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 del mes abreviado
%C El siglo (un año dividido por 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 número decimal (01-31)
%e El día del mes como número decimal (1-31); los dígitos individuales están precedidos por un espacio
%F La fecha en el formato %Y-%m-%d
%G El año ISO 8601 con siglo como número decimal. Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %G y %Y pueden producir resultados diferentes cerca de los límites del año gregoriano, en donde el año gregoriano y el año ISO pueden divergir.
%g El año ISO 8601 sin el siglo como número decimal (00-99). Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %y y %g pueden producir resultados diferentes cerca de los límites del año gregoriano, en los que el año gregoriano y el año ISO pueden divergir.
%j El día del año como número decimal (001-366)
%m El mes como número decimal (01-12)
%n Un carácter de salto de línea
%Q El trimestre como número decimal (1-4).
%t Un tabulador
%U El número de la semana del año (con el domingo como primer día de la semana) como número decimal (00-53)
%u El día de la semana (lunes como primer día de la semana) como número decimal (1-7)
%V El número de semana ISO 8601 del año (con el lunes como el primer día de la semana) como número decimal (01-53). Si la semana que contiene el 1 de enero tiene cuatro o más días en el Año Nuevo, entonces es la semana 1; de lo contrario, es la semana 53 del año anterior, y la próxima semana es la semana 1.
%W El número de la semana del año (con el lunes como primer día de la semana) como número decimal (00-53)
%w El día de la semana (domingo como primer día de la semana) como número decimal (0-6)
%x La representación de la fecha en formato MM/DD/YY
%Y El año con siglo como número decimal
%y El año sin siglo como número decimal (00-99), con un cero inicial opcional. Se puede combinar con %C. Si no se especifica %C, los años 00-68 son los años 2000, mientras que los años 69-99 son los 1900.
%E4Y Los años de cuatro caracteres (0001 … 9999). Ten en cuenta que %Y genera tantos caracteres como sean necesarios para procesar el año completo.

Funciones de fecha y hora

BigQuery admite las siguientes funciones DATETIME.

CURRENT_DATETIME

CURRENT_DATETIME([timezone])

Descripción

Muestra la hora actual como un objeto DATETIME.

Esta función admite un parámetro timezone opcional. Consulta las Definiciones de la zona horaria para obtener información sobre cómo especificar una zona horaria.

Tipo de datos mostrados

DATETIME

Ejemplo

SELECT CURRENT_DATETIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 2016-05-19 10:38:47.046465 |
+----------------------------+

DATETIME

1. DATETIME(year, month, day, hour, minute, second)
2. DATETIME(date_expression, time_expression)
3. DATETIME(timestamp_expression [, timezone])

Descripción

  1. Construye un objeto DATETIME con valores INT64 que representan el año, mes, día, hora, minuto y segundo.
  2. Construye un objeto DATETIME con un objeto DATE y uno TIME.
  3. Construye un objeto DATETIME con un objeto TIMESTAMP. Admite un parámetro opcional para especificar una zona horaria. Si no se especifica una zona horaria, se usa la predeterminada, UTC.

Tipo de datos mostrados

DATETIME

Ejemplo

SELECT
  DATETIME(2008, 12, 25, 05, 30, 00) as datetime_ymdhms,
  DATETIME(TIMESTAMP "2008-12-25 05:30:00+00", "America/Los_Angeles") as datetime_tstz;

+---------------------+---------------------+
| datetime_ymdhms     | datetime_tstz       |
+---------------------+---------------------+
| 2008-12-25 05:30:00 | 2008-12-24 21:30:00 |
+---------------------+---------------------+

DATETIME_ADD

DATETIME_ADD(datetime_expression, INTERVAL INT64_expr part)

Descripción

Agrega INT64_expr unidades de part al objeto DATETIME.

DATETIME_ADD admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK, que equivale a 7 DAY
  • MONTH
  • QUARTER
  • YEAR

Se requiere un manejo especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes o está cerca de este. Si el mes del resultado tiene menos días que el día de DATETIME original, entonces el día del resultado será el último día del nuevo mes.

Tipo de datos mostrados

DATETIME

Ejemplo

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_ADD(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as later;

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

DATETIME_SUB

DATETIME_SUB(datetime_expression, INTERVAL INT64_expr part)

Descripción

Resta INT64_expr unidades de part al DATETIME.

DATETIME_SUB admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK, que equivale a 7 DAY
  • MONTH
  • QUARTER
  • YEAR

Se requiere un manejo especial para las partes MONTH, QUARTER y YEAR cuando la fecha es el último día del mes o está cerca de este. Si el mes del resultado tiene menos días que el día de DATETIME original, entonces el día del resultado será el último día del nuevo mes.

Tipo de datos mostrados

DATETIME

Ejemplo

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_SUB(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as earlier;

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

DATETIME_DIFF

DATETIME_DIFF(datetime_expression, datetime_expression, part)

Descripción

Muestra el número de límites de part entre las dos datetime_expression. Si el primer DATETIME ocurre antes del segundo DATETIME, el resultado no es positivo. Genera un error si el cálculo desborda el tipo de resultado, por ejemplo, si la diferencia en microsegundos entre los dos objetos DATETIME desbordaría un valor INT64.

DATETIME_DIFF admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK: esta parte de la fecha comienza el día domingo.
  • WEEK(<WEEKDAY>): Esta parte de fecha comienza el WEEKDAY. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: Usa los límites de la semana ISO 8601. Las semanas ISO comienzan el lunes.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: Usa el límite del año de numeración de semana ISO 8601. El límite del año ISO es el lunes de la primera semana cuyo jueves pertenece al año calendario gregoriano correspondiente.

Tipo de datos mostrados

INT64

Ejemplo

SELECT
  DATETIME "2010-07-07 10:20:00" as first_datetime,
  DATETIME "2008-12-25 15:30:00" as second_datetime,
  DATETIME_DIFF(DATETIME "2010-07-07 10:20:00",
    DATETIME "2008-12-25 15:30:00", DAY) as difference;

+----------------------------+------------------------+------------------------+
| first_datetime             | second_datetime        | difference             |
+----------------------------+------------------------+------------------------+
| 2010-07-07 10:20:00        | 2008-12-25 15:30:00    | 559                    |
+----------------------------+------------------------+------------------------+

SELECT
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', DAY) as days_diff,
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', WEEK) as weeks_diff;

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

En el ejemplo anterior, se muestra el resultado de DATETIME_DIFF para dos DATETIME con 24 horas de diferencia. DATETIME_DIFF con la parte WEEK muestra 1 porque DATETIME_DIFF cuenta el número de límites de parte en este rango de DATETIME. Cada WEEK comienza el domingo, por lo que hay un límite de parte entre el sábado, 2017-10-14 00:00:00, y el domingo, 2017-10-15 00:00:00.

En el siguiente ejemplo, se muestra el resultado de DATETIME_DIFF para dos fechas en años diferentes. DATETIME_DIFF con la parte de fecha YEAR muestra 3 porque cuenta el número de límites de año del calendario gregoriano entre los dos DATETIME. DATETIME_DIFF con la parte de fecha ISOYEAR muestra 2 porque el segundo DATETIME pertenece al año 2015 según la ISO. El primer jueves del año calendario 2015 fue 2015-01-01, por lo que el año ISO 2015 comienza el lunes anterior, 2014-12-29.

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

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

En el siguiente ejemplo, se muestra el resultado de DATETIME_DIFF para dos días seguidos. La primera fecha es un lunes y la segunda es un domingo. DATETIME_DIFF con la parte de fecha WEEK muestra 0 porque esta parte de tiempo usa semanas que comienzan el domingo. DATETIME_DIFF con la parte de fecha WEEK(MONDAY) muestra 1. DATETIME_DIFF con la parte de fecha ISOWEEK también muestra 1 porque las semanas ISO comienzan el lunes.

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

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

DATETIME_TRUNC

DATETIME_TRUNC(datetime_expression, part)

Descripción

Trunca un objeto DATETIME al nivel de detalle de part.

DATETIME_TRUNC admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>): trunca datetime_expression al límite de la semana anterior, en el que las semanas comienzan en WEEKDAY. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: trunca datetime_expression al límite de la semana ISO 8601 anterior. Los valores comienzan el lunes. El primer ISOWEEK de cada año ISO contiene el primer jueves del año calendario gregoriano correspondiente. Cualquier valor date_expression anterior a esto se truncará al lunes anterior.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: trunca datetime_expression al límite de año de numeración de la semana ISO 8601. El límite del año ISO es el lunes de la primera semana cuyo jueves pertenece al año calendario gregoriano correspondiente.

Tipo de datos mostrados

DATETIME

Ejemplos

SELECT
  DATETIME "2008-12-25 15:30:00" as original,
  DATETIME_TRUNC(DATETIME "2008-12-25 15:30:00", DAY) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 2008-12-25 15:30:00        | 2008-12-25 00:00:00    |
+----------------------------+------------------------+

En el siguiente ejemplo, el DATETIME original es un domingo. Debido a que part es WEEK(MONDAY), DATE_TRUNC muestra DATETIME para el lunes anterior.

SELECT
 datetime AS original,
 DATETIME_TRUNC(datetime, WEEK(MONDAY)) AS truncated
FROM (SELECT DATETIME(TIMESTAMP '2017-11-05 00:00:00') AS datetime);

+---------------------+---------------------+
| original            | truncated           |
+---------------------+---------------------+
| 2017-11-05 00:00:00 | 2017-10-30 00:00:00 |
+---------------------+---------------------+

En el siguiente ejemplo, el valor datetime_expression original está en el año calendario gregoriano 2015. Sin embargo, DATETIME_TRUNC con la parte de fecha ISOYEAR trunca el valor datetime_expression al comienzo del año ISO, no el año calendario gregoriano. El primer jueves del año calendario 2015 fue 2015-01-01, por lo que el año ISO 2015 comienza el lunes anterior, 2014-12-29. Por lo tanto, el límite del año ISO que precede al valor datetime_expression 2015-06-15 00:00:00 es 2014-12-29.

SELECT
  DATETIME_TRUNC('2015-06-15 00:00:00', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATETIME '2015-06-15 00:00:00') AS isoyear_number;

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

FORMAT_DATETIME

FORMAT_DATETIME(format_string, datetime_expression)

Descripción

Formatea un objeto DATETIME según el valor format_string especificado. Consulta los elementos de formato admitidos para DATETIME a fin de obtener una lista de los elementos de formato que admite esta función.

Tipo de datos mostrados

STRING

Ejemplos

SELECT
  FORMAT_DATETIME("%c", DATETIME "2008-12-25 15:30:00")
  AS formatted;

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

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

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

PARSE_DATETIME

PARSE_DATETIME(format_string, string)

Descripción

Usa format_string y una representación de STRING de DATETIME para mostrar DATETIME. Consulta los elementos de formato admitidos para DATETIME a fin de obtener una lista de los elementos de formato que admite esta función.

PARSE_DATETIME analiza la string según las siguientes reglas:

  • Campos sin especificar. Todo campo sin especificar se inicializa desde 1970-01-01 00:00:00.0. Por ejemplo, si el año no se especifica, su valor predeterminado es 1970.
  • Nombres sin distinción entre mayúsculas y minúsculas. Los nombres, como Monday y February, no distinguen entre mayúsculas y minúsculas.
  • Espacio en blanco. Uno o más espacios en blanco consecutivos en la string de formato coinciden con cero o más espacios en blanco consecutivos en la string DATETIME. Los espacios en blanco iniciales y finales siempre se permiten en la string DATETIME, incluso si no están en la string de formato.
  • Precedencia del formato. Cuando dos o más elementos de formato tienen información superpuesta, por lo general, el último anula los anteriores, con algunas excepciones. Por ejemplo, %F y %Y afectan el año, por lo que el elemento anterior anula al posterior. Consulta las descripciones de %s, %C y %y en los elementos de formato admitidos para DATETIME.

Ejemplos

En el siguiente ejemplo, se analiza un literal de STRING como DATETIME.

SELECT PARSE_DATETIME('%Y-%m-%d %H:%M:%S', '1998-10-18 13:45:55') AS datetime;

La consulta anterior muestra el siguiente resultado:

+---------------------+
| datetime            |
+---------------------+
| 1998-10-18 13:45:55 |
+---------------------+

En el siguiente ejemplo, se analiza un literal de STRING que contiene una fecha en un formato de lenguaje natural como DATETIME.

SELECT PARSE_DATETIME('%A, %B %e, %Y','Wednesday, December 19, 2018')
  AS datetime;

La consulta anterior muestra el siguiente resultado:

+---------------------+
| datetime            |
+---------------------+
| 2018-12-19 00:00:00 |
+---------------------+

Tipo de datos mostrados

DATETIME

Elementos de formato admitidos para DATETIME

A menos que se indique lo contrario, las funciones DATETIME que usan strings 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 del mes abreviado
%C El siglo (un año dividido por 100 y truncado a un número entero) como un número decimal (00-99).
%c La representación de la fecha y la hora.
%D La fecha en el formato %m/%d/%y
%d El día del mes como número decimal (01-31)
%e El día del mes como número decimal (1-31); los dígitos individuales están precedidos por un espacio
%F La fecha en el formato %Y-%m-%d
%G El año ISO 8601 con siglo como número decimal. Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %G y %Y pueden producir resultados diferentes cerca de los límites del año gregoriano, en donde el año gregoriano y el año ISO pueden divergir.
%g El año ISO 8601 sin el siglo como número decimal (00-99). Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %g y %y pueden producir resultados diferentes cerca de los límites del año gregoriano, en donde el año gregoriano y el año ISO pueden divergir.
%H La hora (formato de 24 horas) como número decimal (00-23).
%I La hora (formato de 12 horas) como número decimal (01-12).
%j El día del año como número decimal (001-366).
%k La hora (formato de 24 horas) como número decimal (0-23); los dígitos individuales están precedidos por un espacio.
%l La hora (formato de 12 horas) como número decimal (1-12); los dígitos individuales están precedidos por un espacio.
%M El minuto como número decimal (00-59).
%m El mes como número decimal (01-12)
%n Un carácter de salto de línea.
%P Ya sea a.m. o p.m.
%p Puede ser A.M. o P.M.
%Q El trimestre como número decimal (1-4).
%R La hora en el formato %H:%M.
%r La hora en el formato de 12 horas con la notación A.M./P.M.
%S El segundo como número decimal (00-60).
%s El número de segundos desde 1970-01-01 00:00:00. Siempre anula todos los demás elementos de formato, sin importar dónde aparezca %s en la string. Si aparecen varios elementos %s, el último tiene prioridad.
%T La hora en el formato %H:%M:%S.
%t Un tabulador
%U El número de la semana del año (con el domingo como primer día de la semana) como número decimal (00-53)
%u El día de la semana (lunes como primer día de la semana) como número decimal (1-7)
%V El número de semana ISO 8601 del año (con el lunes como el primer día de la semana) como número decimal (01-53). Si la semana que contiene el 1 de enero tiene cuatro o más días en el Año Nuevo, entonces es la semana 1; de lo contrario, es la semana 53 del año anterior, y la próxima semana es la semana 1.
%W El número de la semana del año (con el lunes como primer día de la semana) como número decimal (00-53)
%w El día de la semana (domingo como primer día de la semana) como número decimal (0-6).
%X La representación de la hora en formato HH:MM:SS.
%x La representación de la fecha en formato MM/DD/YY
%Y El año con siglo como número decimal
%y El año sin siglo como número decimal (00-99), con un cero inicial opcional. Se puede combinar con %C. Si no se especifica %C, los años 00-68 son los años 2000, mientras que los años 69-99 son los 1900.
%% Un solo carácter %
%E#S Segundos con # dígitos de precisión fraccional.
%E*S Segundos con precisión fraccional completa (un literal '*').
%E4Y Los años de cuatro caracteres (0001 … 9999). Ten en cuenta que %Y produce tantos caracteres como sea necesario para procesar el año por completo.

Funciones de tiempo

BigQuery admite las siguientes funciones TIME.

CURRENT_TIME

CURRENT_TIME()

Descripción

Muestra la hora actual como un objeto TIME.

Tipo de datos mostrados

TIME

Ejemplo

SELECT CURRENT_TIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 15:31:38.776361            |
+----------------------------+

TIME

1. TIME(hour, minute, second)
2. TIME(timestamp, [timezone])
3. TIME(datetime)

Descripción

  1. Construye un objeto TIME mediante valores INT64 que representan la hora, los minutos y los segundos.
  2. Construye un objeto TIME mediante un objeto TIMESTAMP. Admite un parámetro opcional para especificar una zona horaria. Si no se especifica una zona horaria, se usa la predeterminada, UTC.
  3. Construye un objeto TIME mediante un objeto DATETIME.

Tipo de datos mostrados

TIME

Ejemplo

SELECT
  TIME(15, 30, 00) as time_hms,
  TIME(TIMESTAMP "2008-12-25 15:30:00+08", "America/Los_Angeles") as time_tstz;
+----------+-----------+
| time_hms | time_tstz |
+----------+-----------+
| 15:30:00 | 23:30:00  |
+----------+-----------+
SELECT
  TIME(DATETIME "2008-12-25 15:30:00.000000") AS time_dt;
+----------+
| time_dt  |
+----------+
| 15:30:00 |
+----------+

TIME_ADD

TIME_ADD(time_expression, INTERVAL INT64_expr part)

Descripción

Agrega INT64_expr unidades de part al objeto TIME.

TIME_ADD admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

Esta función se ajusta automáticamente cuando los valores caen fuera del límite de 00:00:00 a 24:00:00. Por ejemplo, si agregas una hora a la 23:30:00, el valor que se muestra es 00:30:00.

Tipos de datos mostrados

TIME

Ejemplo

SELECT
  TIME "15:30:00" as original_time,
  TIME_ADD(TIME "15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_time               | later                  |
+-----------------------------+------------------------+
| 15:30:00                    | 15:40:00               |
+-----------------------------+------------------------+

TIME_SUB

TIME_SUB(time_expression, INTERVAL INT_expr part)

Descripción

Resta INT64_expr unidades de part al objeto TIME.

TIME_SUB admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

Esta función se ajusta automáticamente cuando los valores caen fuera del límite de 00:00:00 a 24:00:00. Por ejemplo, si restas una hora de 00:30:00, el valor que se muestra es 23:30:00.

Tipo de datos mostrados

TIME

Ejemplo

SELECT
  TIME "15:30:00" as original_date,
  TIME_SUB(TIME "15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date                | earlier                |
+-----------------------------+------------------------+
| 15:30:00                    | 15:20:00               |
+-----------------------------+------------------------+

TIME_DIFF

TIME_DIFF(time_expression, time_expression, part)

Descripción

Muestra el número de intervalos part completos especificados entre dos objetos TIME. Genera un error si el cálculo desborda el tipo de resultado, por ejemplo, si la diferencia en microsegundos entre los dos objetos de tiempo desbordaría un valor INT64.

TIME_DIFF admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

Tipo de datos mostrados

INT64

Ejemplo

SELECT
  TIME "15:30:00" as first_time,
  TIME "14:35:00" as second_time,
  TIME_DIFF(TIME "15:30:00", TIME "14:35:00", MINUTE) as difference;

+----------------------------+------------------------+------------------------+
| first_time                 | second_time            | difference             |
+----------------------------+------------------------+------------------------+
| 15:30:00                   | 14:35:00               | 55                     |
+----------------------------+------------------------+------------------------+

TIME_TRUNC

TIME_TRUNC(time_expression, part)

Descripción

Trunca un objeto TIME al nivel de detalle de part.

TIME_TRUNC admite los siguientes valores para part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

Tipo de datos mostrados

TIME

Ejemplo

SELECT
  TIME "15:30:00" as original,
  TIME_TRUNC(TIME "15:30:00", HOUR) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 15:30:00                   | 15:00:00               |
+----------------------------+------------------------+

FORMAT_TIME

FORMAT_TIME(format_string, time_object)

Descripción Formatea un objeto TIME según el format_string especificado. Consulta Elementos de formato admitidos para TIME a fin de obtener una lista de los elementos de formato que admite esta función.

Tipo de datos mostrados

STRING

Ejemplo

SELECT FORMAT_TIME("%R", TIME "15:30:00") as formatted_time;

+----------------+
| formatted_time |
+----------------+
| 15:30          |
+----------------+

PARSE_TIME

PARSE_TIME(format_string, string)

Descripción

Usa un format_string y una string para mostrar un objeto TIME. Consulta Elementos de formato admitidos para TIME a fin de obtener una lista de los elementos de formato que admite esta función.

Cuando uses PARSE_TIME, ten en cuenta lo siguiente:

  • Campos sin especificar. Todo campo sin especificar se inicializa desde 00:00:00.0. Por ejemplo, si seconds no está especificado, el valor predeterminado es 00, y así sucesivamente.
  • Espacio en blanco. Uno o más espacios en blanco consecutivos en la string de formato no coinciden con ningún espacio en blanco consecutivo o coinciden con más espacios en blanco consecutivos en la string TIME. Además, los espacios en blanco iniciales y finales en la string TIME siempre están permitidos, incluso si no están en la string de formato.
  • Precedencia del formato. Cuando dos (o más) elementos de formato tienen información superpuesta, el último generalmente anula los anteriores.

Tipo de datos mostrados

TIME

Ejemplo

SELECT PARSE_TIME("%H", "15") as parsed_time;

+-------------+
| parsed_time |
+-------------+
| 15:00:00    |
+-------------+

Elementos de formato admitidos para TIME

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

Elemento de formato Descripción
%H La hora (formato de 24 horas) como número decimal (00-23).
%I La hora (formato de 12 horas) como número decimal (01-12).
%j El día del año como número decimal (001-366).
%k La hora (formato de 24 horas) como número decimal (0-23); los dígitos individuales están precedidos por un espacio.
%l La hora (formato de 12 horas) como número decimal (1-12); los dígitos individuales están precedidos por un espacio.
%M El minuto como número decimal (00-59)
%n Un carácter de salto de línea.
%P Ya sea a.m. o p.m.
%p Ya sea A.M. o P.M.
%R La hora en el formato %H:%M.
%r La hora en el formato de 12 horas con la notación A.M./P.M.
%S El segundo como número decimal (00-60)
%T La hora en el formato %H:%M:%S.
%t Un tabulador
%X La representación de la hora en formato HH:MM:SS
%% Un solo carácter %
%E#S Segundos con # dígitos de precisión fraccional.
%E*S Segundos con precisión fraccional completa (un literal “*”).

Funciones de marca de tiempo

BigQuery admite las siguientes funciones TIMESTAMP.

NOTA: Estas funciones muestran un error de entorno de ejecución si se produce un desbordamiento; los valores de los resultados están delimitados por la fecha definida y los valores mínimo/máximo de la marca de tiempo.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Descripción

Los paréntesis son opcionales. Esta función maneja los segundos bisiestos; para ello, los coloca en una ventana de 20 horas alrededor del segundo bisiesto insertado. CURRENT_TIMESTAMP() produce un valor TIMESTAMP que es continuo, no es ambiguo, tiene 60 segundos por minuto exactos y no repite los valores durante el segundo bisiesto.

Tipos de entrada admitidos

No aplicable

Tipo de datos del resultado

TIMESTAMP

Ejemplo

SELECT CURRENT_TIMESTAMP() as now;

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

EXTRACT

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

Descripción

Muestra un valor INT64 que corresponde al part especificado de un timestamp_expression suministrado.

Los valores part permitidos son los siguientes:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAYOFWEEK
  • DAY
  • DAYOFYEAR
  • WEEK: muestra el número de semana de la fecha en el rango [0, 53]. Las semanas comienzan con el domingo y las fechas anteriores al primer domingo del año están en la semana 0.
  • WEEK(<WEEKDAY>): Muestra el número de la semana de timestamp_expression en el rango [0, 53]. Las semanas comienzan el WEEKDAY. Los valores datetime anteriores al primer WEEKDAY del año están en la semana 0. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: muestra el número de semana ISO 8601 de datetime_expression. Los valores ISOWEEK comienzan el lunes. Los valores de muestra están en el rango [1, 53]. El primer valor ISOWEEK de cada año ISO comienza el lunes anterior al primer jueves del año del calendario gregoriano.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: muestra el año de numeración de la semana ISO 8601, que es el año calendario gregoriano que contiene el jueves de la semana a la que pertenece date_expression.
  • DATE
  • DATETIME
  • TIME

Los valores mostrados truncan los períodos de tiempo de orden inferior. Por ejemplo, cuando se extraen segundos, EXTRACT trunca los valores de milisegundos y microsegundos.

Consulta las Definiciones de la zona horaria para obtener información sobre cómo especificar una zona horaria.

Tipo de datos mostrados

Por lo general, INT64. Muestra DATE si part es DATE.

Ejemplos

En el siguiente ejemplo, EXTRACT muestra un valor que corresponde a la parte de tiempo DAY.

SELECT EXTRACT(DAY
  FROM TIMESTAMP "2008-12-25 15:30:00" AT TIME ZONE "America/Los_Angeles")
  AS the_day;

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

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

WITH Timestamps AS (
  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'
)
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 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   |
+------------------------+---------+---------+------+------+

En el siguiente ejemplo, timestamp_expression es un domingo. EXTRACT calcula la primera columna mediante las semanas que comienzan los días domingo y calcula la segunda columna con las semanas que comienzan los días lunes.

WITH table AS (SELECT TIMESTAMP('2017-11-05 00:00:00') AS timestamp)
SELECT
  timestamp,
  EXTRACT(WEEK(SUNDAY) FROM timestamp) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM timestamp) AS week_monday
FROM table;

+------------------------+-------------+---------------+
| timestamp              | week_sunday | week_monday   |
+------------------------+-------------+---------------+
| 2017-11-05 00:00:00+00 | 45          | 44            |
+------------------------+-------------+---------------+

STRING

STRING(timestamp_expression[, timezone])

Descripción

Convierte un valor timestamp_expression en un tipo de datos STRING. Admite un parámetro opcional para especificar una zona horaria. Consulta las Definiciones de la zona horaria para obtener información sobre cómo especificar una zona horaria.

Tipo de datos mostrados

STRING

Ejemplo

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles") as string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 07:30:00-08        |
+-------------------------------+

TIMESTAMP

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

Descripción

  • string_expression[, timezone]: Convierte una expresión STRING en un tipo de datos TIMESTAMP. string_expression debe incluir un literal de marca de tiempo. Si string_expression incluye una zona horaria en literal de marca de tiempo, no incluyas un argumento explícito timezone.
  • date_expression[, timezone]: convierte un objeto DATE en un tipo de datos TIMESTAMP.
  • datetime_expression[, timezone]: convierte un objeto DATETIME en un tipo de datos TIMESTAMP.

Esta función admite un parámetro opcional para especificar una zona horaria. Si no se especifica una zona horaria, se usa la predeterminada, UTC.

Tipo de datos mostrados

TIMESTAMP

Ejemplos

En estos ejemplos, se especifica la zona horaria.

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

+------------------------+
| timestamp_str          |
+------------------------+
| 2008-12-25 23:30:00+00 |
+------------------------+
SELECT CAST(
  TIMESTAMP("2008-12-25 15:30:00 America/Los_Angeles") AS STRING
) AS timestamp_str_timezone;

+------------------------+
| timestamp_str_timezone |
+------------------------+
| 2008-12-25 23:30:00+00 |
+------------------------+
SELECT CAST(
  TIMESTAMP(DATETIME "2008-12-25 15:30:00", "America/Los_Angeles") AS STRING
) AS timestamp_datetime;

+------------------------+
| timestamp_datetime     |
+------------------------+
| 2008-12-25 23:30:00+00 |
+------------------------+
SELECT CAST(
  TIMESTAMP(DATE "2008-12-25", "America/Los_Angeles") AS STRING
) AS timestamp_date;

+------------------------+
| timestamp_date         |
+------------------------+
| 2008-12-25 08:00:00+00 |
+------------------------+

Para estos ejemplos, supongamos que la zona horaria predeterminada es UTC.

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

+------------------------+
| timestamp_str          |
+------------------------+
| 2008-12-25 15:30:00+00 |
+------------------------+
SELECT CAST(
  TIMESTAMP(DATE "2008-12-25") AS STRING
) AS timestamp_date;

+------------------------+
| timestamp_date         |
+------------------------+
| 2008-12-25 00:00:00+00 |
+------------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

Descripción

Agrega int64_expression unidades de date_part a la marca de tiempo, sin importar la zona horaria.

TIMESTAMP_ADD admite los siguientes valores para date_part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 MINUTE.
  • DAY. Equivalente a 24 HOUR.

Tipos de datos mostrados

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 int64_expression unidades de date_part de la marca de tiempo, sin importar la zona horaria.

TIMESTAMP_SUB admite los siguientes valores para date_part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 MINUTE.
  • DAY. Equivalente a 24 HOUR.

Tipo de datos mostrados

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

Muestra el número de intervalos date_part completos especificados entre dos marcas de tiempo. El primer valor timestamp_expression representa la fecha posterior; si el primer valor timestamp_expression es anterior al segundo timestamp_expression, el resultado es negativo. Genera un error si el cálculo sobrepasa el tipo de resultado, por ejemplo, si la diferencia en nanosegundos entre las dos marcas de tiempo excede un valor INT64.

TIMESTAMP_DIFF admite los siguientes valores para date_part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR. Equivalente a 60 MINUTE.
  • DAY. Equivalente a 24 HOUR.

Tipo de datos mostrados

INT64

Ejemplo

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

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

En el siguiente ejemplo, la primera marca de tiempo se produce antes de la segunda marca de tiempo, lo que se traduce en un resultado negativo.

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

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

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part[, time_zone])

Descripción

Trunca una marca de tiempo con el nivel de detalle de date_part.

TIMESTAMP_TRUNC admite los siguientes valores para date_part:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>): trunca timestamp_expression al límite de la semana anterior, donde las semanas comienzan en WEEKDAY. Los valores válidos para WEEKDAY son SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY y SATURDAY.
  • ISOWEEK: trunca timestamp_expression al límite de la semana ISO 8601 anterior. Los valores comienzan el lunes. El primer ISOWEEK de cada año ISO contiene el primer jueves del año calendario gregoriano correspondiente. Cualquier valor date_expression anterior a esto se truncará al lunes anterior.
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR: trunca timestamp_expression al límite de año de numeración de la semana ISO 8601. El límite del año ISO es el lunes de la primera semana cuyo jueves pertenece al año calendario gregoriano correspondiente.

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

  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>)
  • MONTH
  • QUARTER
  • YEAR

Usa este parámetro si deseas usar una zona horaria distinta de la predeterminada, UTC, como parte de la operación para truncar.

Cuando se trunca un valor TIMESTAMP a MINUTE o HOUR, TIMESTAMP_TRUNC determina la hora civil de en la zona horaria especificada (o predeterminada) y resta los minutos y los segundos (cuando se trunca a HOUR) o los segundos (cuando se trunca a MINUTE) de . Si bien esto proporciona resultados intuitivos en la mayoría de los casos, el resultado es una transición no intuitiva cerca del horario de verano que no está alineada con la hora.

Tipo de datos mostrados

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

En el siguiente ejemplo, timestamp_expression tiene un desplazamiento de zona horaria de + 12. La primera columna muestra el valor timestamp_expression en la hora UTC. La segunda columna muestra el resultado de TIMESTAMP_TRUNC con las semanas que comienzan el lunes. Debido a que timestamp_expression es un domingo en UTC, TIMESTAMP_TRUNC lo trunca al lunes anterior. La tercera columna muestra la misma función con el argumento de definiciones de zona horaria opcional “Pacific/Auckland”. Aquí, la función trunca el valor timestamp_expression ya que usa el horario de verano de Nueva Zelanda, que cae un lunes.

SELECT
  timestamp,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY)) AS utc_truncated,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY), 'Pacific/Auckland') AS nzdt_truncated
FROM (SELECT TIMESTAMP('2017-11-06 00:00:00+12') AS timestamp);

+------------------------+------------------------+------------------------+
| timestamp              | utc_truncated          | nzdt_truncated         |
+------------------------+------------------------+------------------------+
| 2017-11-05 12:00:00+00 | 2017-10-30 00:00:00+00 | 2017-11-05 11:00:00+00 |
+------------------------+------------------------+------------------------+

En el siguiente ejemplo, el valor timestamp_expression original está en el año calendario gregoriano 2015. Sin embargo, TIMESTAMP_TRUNC con la parte de fecha ISOYEAR trunca el valor timestamp_expression al comienzo del año ISO, no el año calendario gregoriano. El primer jueves del año calendario 2015 fue 2015-01-01, por lo que el año ISO 2015 comienza el lunes anterior, 2014-12-29. Por lo tanto, el límite del año ISO que precede al valor timestamp_expression 2015-06-15 00:00:00 + 00 es 2014-12-29.

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

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

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

Descripción

Formatea una marca de tiempo de acuerdo con el valor format_string especificado.

Consulta Elementos de formato admitidos para TIMESTAMP a fin de obtener una lista de los elementos de formato que admite esta función.

Tipo de datos mostrados

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 |
+--------------------------+
SELECT FORMAT_TIMESTAMP("%b-%d-%Y", TIMESTAMP "2008-12-25 15:30:00")
  AS formatted;

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

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

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, string[, time_zone])

Descripción

Usa un valor format_string y una representación de string de una marca de tiempo para mostrar un objeto TIMESTAMP.

Cuando uses PARSE_TIMESTAMP, ten en cuenta lo siguiente:

  • Campos sin especificar. Todo campo sin especificar se inicializa desde 1970-01-01 00:00:00.0. Este valor de inicialización usa la zona horaria que especifica el argumento de la zona horaria de la función, si está presente. De lo contrario, el valor de inicialización usa la zona horaria predeterminada, UTC. Por ejemplo, si no se especifica el año, el valor predeterminado es 1970, y así sucesivamente.
  • Nombres sin distinción 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 string de formato no coinciden con ningún espacio en blanco consecutivo o coinciden con más espacios en blanco consecutivos en la string de marca de tiempo. Además, los espacios en blanco iniciales y finales en la string de marca de tiempo siempre están permitidos, incluso si no están en la string de formato.
  • Precedencia del formato. Cuando dos (o más) elementos de formato tienen información superpuesta (por ejemplo, tanto %F como %Y afectan el año), el último suele anular los anteriores, con algunas excepciones (consulta las descripciones de %s, %C y %y).

Tipo de datos mostrados

TIMESTAMP

Ejemplo

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008", "America/Los_Angeles") as parsed;

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

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 mostrados

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

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

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 mostrados

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

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

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

Descripción

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

Tipo de datos mostrados

TIMESTAMP

Ejemplo

SELECT TIMESTAMP_MICROS(1230219000000000) as timestamp;

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

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Descripción

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

Tipo de datos mostrados

INT64

Ejemplo

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

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

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Descripción

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

Tipo de datos mostrados

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

Muestra 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 mostrados

INT64

Ejemplo

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

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

Elementos de formato admitidos para TIMESTAMP

A menos que se indique lo contrario, las funciones de TIMESTAMP que usan strings 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 del mes abreviado
%C El siglo (un año dividido por 100 y truncado a un número entero) como un número decimal (00-99).
%c La representación de la fecha y la hora en el formato %a %b %e %T %Y.
%D La fecha en el formato %m/%d/%y
%d El día del mes como número decimal (01-31)
%e El día del mes como número decimal (1-31); los dígitos individuales están precedidos por un espacio
%F La fecha en el formato %Y-%m-%d
%G El año ISO 8601 con siglo como número decimal. Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %G y %Y pueden producir resultados diferentes cerca de los límites del año gregoriano, en donde el año gregoriano y el año ISO pueden divergir.
%g El año ISO 8601 con siglo como número decimal (00-99). Cada año ISO comienza el lunes anterior al primer jueves del año calendario gregoriano. Ten en cuenta que %g y %y pueden producir resultados diferentes cerca de los límites del año gregoriano, en donde el año gregoriano y el año ISO pueden divergir.
%H La hora (formato de 24 horas) como número decimal (00-23).
%I La hora (formato de 12 horas) como número decimal (01-12).
%j El día del año como número decimal (001-366).
%k La hora (formato de 24 horas) como número decimal (0-23); los dígitos individuales están precedidos por un espacio.
%l La hora (formato de 12 horas) como número decimal (1-12); los dígitos individuales están precedidos por un espacio.
%M El minuto como número decimal (00-59).
%m El mes como número decimal (01-12)
%n Un carácter de salto de línea.
%P Ya sea a.m. o p.m.
%p Puede ser A.M. o P.M.
%Q El trimestre como número decimal (1-4).
%R La hora en el formato %H:%M.
%r La hora en el formato de 12 horas con la notación A.M./P.M.
%S El segundo como número decimal (00-60).
%s El número de segundos desde 1970-01-01 00:00:00 UTC. Siempre anula todos los demás elementos de formato, sin importar dónde aparezca %s en la string. Si aparecen varios elementos %s, el último tiene prioridad.
%T La hora en el formato %H:%M:%S.
%t Un tabulador
%U El número de la semana del año (con el domingo como primer día de la semana) como número decimal (00-53)
%u El día de la semana (lunes como primer día de la semana) como número decimal (1-7)
%V El número de semana ISO 8601 del año (con el lunes como el primer día de la semana) como número decimal (01-53). Si la semana que contiene el 1 de enero tiene cuatro o más días en el Año Nuevo, entonces es la semana 1; de lo contrario, es la semana 53 del año anterior, y la próxima semana es la semana 1.
%W El número de la semana del año (con el lunes como primer día de la semana) como número decimal (00-53)
%w El día de la semana (domingo como primer día de la semana) como número decimal (0-6).
%X La representación de la hora en formato HH:MM:SS.
%x La representación de la fecha en formato MM/DD/YY
%Y El año con siglo como número decimal
%y El año sin siglo como número decimal (00-99), con un cero inicial opcional. Se puede combinar con %C. Si no se especifica %C, los años 00-68 son los años 2000, mientras que los años 69-99 son los 1900.
%Z El nombre de la zona horaria.
%z La compensación desde el primer meridiano 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 RFC 3339 (+HH:MM o -HH:MM).
%E#S Segundos con # dígitos de precisión fraccional.
%E*S Segundos con precisión fraccional completa (un literal '*').
%E4Y Los años de cuatro caracteres (0001 … 9999). Ten en cuenta que %Y produce tantos caracteres como sea necesario para procesar el año por completo.

Definiciones de la zona horaria

Ciertas funciones de fecha y marca de tiempo te permiten anular la zona horaria predeterminada y especificar una diferente. Puedes proporcionar el nombre de zona horaria para especificar una (por ejemplo, America/Los_Angeles) o el desplazamiento de zona horaria desde UTC (por ejemplo, -08).

Si decides usar un desplazamiento de zona horaria, aplica el siguiente formato:

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

Las siguientes marcas de tiempo son equivalentes porque el desplazamiento de la zona horaria de America/Los_Angeles es -08 en la fecha y hora especificadas.

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

Funciones de geografía

Las funciones de geografía operan en valores GEOGRAPHY de BigQuery o los generan. La firma de cualquier función de geografía comienza con ST_. BigQuery admite las siguientes funciones que se pueden usar para analizar datos geográficos, determinar relaciones espaciales entre accidentes geográficos y construir o manipular objetos GEOGRAPHY.

Las funciones de geografía se agrupan en las siguientes categorías, según su comportamiento:

  • Constructores: funciones que crean nuevos valores GEOGRAPHY a partir de coordenadas o de objetos GEOGRAPHY existentes, como ST_GEOGPOINT.
  • Analizadores: funciones que crean objetos GEOGRAPHY a partir de un formato externo como WKT y GeoJSON. Por ejemplo, con ST_GEOGFROMTEXT, se crea un GEOGRAPHY a partir de WKT.
  • Formateadores: funciones que exportan GEOGRAPHY a un formato externo como WKT y GeoJSON. Por ejemplo, ST_ASTEXT convierte el formato de GEOGRAPHY en WKT.
  • Transformaciones: funciones que generan un objeto GEOGRAPHY nuevo a partir de otros que se adhieren a alguna propiedad. Los ejemplos incluyen ST_INTERSECTION y ST_BOUNDARY.
  • Predicados: funciones que muestran TRUE o FALSE para alguna relación espacial entre dos objetos GEOGRAPHY o alguna propiedad de una geografía. Por lo general, estas funciones se usan en cláusulas de filtro. Por ejemplo, ST_DWITHIN es un predicado.
  • Descriptores de acceso: funciones que proporcionan acceso a las propiedades de un objeto GEOGRAPHY sin efectos secundarios, como ST_NUMPOINTS.
  • Medidas: funciones que calculan medidas de uno o más objetos GEOGRAPHY, por ejemplo, ST_DISTANCE.
  • Funciones agregadas: funciones agregadas específicas de la geografía, como ST_UNION_AGG.

Todas las funciones de geografía de BigQuery muestran NULL si algún argumento de entrada es .

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

Descripción

Crea un objeto GEOGRAPHY de un solo punto. ST_GEOGPOINT crea un punto a partir de los parámetros de longitud y latitud FLOAT64 especificados y muestra ese punto en un valor GEOGRAPHY.

Limitaciones

  • Las latitudes deben encontrarse en el rango [-90, 90]. Las latitudes fuera de este rango generarán un error.
  • Se permiten longitudes fuera del rango [-180, 180]; ST_GEOGPOINT utiliza el módulo de longitud de entrada 360 para obtener una longitud dentro de [-180, 180].

Tipo de datos que se muestra

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)

Descripción

Crea un objeto GEOGRAPHY con una sola LineString mediante la concatenación de los vértices de punto o línea de cada uno de los objetos de entrada en el orden en que se presentan.

ST_MAKELINE tiene dos variantes. Para la primera variante, la entrada debe ser de dos objetos GEOGRAPHY. Para la segunda, la entrada es un ARRAY de tipo GEOGRAPHY. En ambas variantes, cada GEOGRAPHY de entrada debe ser uno de los siguientes valores:

  • Exactamente un punto
  • Exactamente una LineString

Para la primera variante de ST_MAKELINE, si alguna de las entradas GEOGRAPHY es NULL, muestra NULL. Para la segunda variante, si el ARRAY de entrada o cualquier elemento de este ARRAY es NULL, ST_MAKELINE muestra NULL.

Limitaciones

Cada borde debe abarcar estrictamente menos de 180 grados.

NOTA: El proceso de ajuste de BigQuery puede descartar bordes lo bastante cortos y juntar los dos extremos. Por ejemplo, si dos objetos GEOGRAPHY de entrada contienen cada uno un punto, y los dos puntos están separados por una distancia menor que el radio de ajuste, los puntos se unirán. En tal caso, el resultado será un objeto GEOGRAPHY con exactamente un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)
ST_MAKEPOLYGON(geography_expression, array_of_geography)

Descripción

Crea un objeto GEOGRAPHY que contiene un único polígono a partir de entradas de LineString, en el que cada LineString de entrada se usa para construir un anillo de polígono.

ST_MAKEPOLYGON tiene dos variantes. Para la primera variante, un único objeto GEOGRAPHY que contiene exactamente una LineString proporciona la LineString de entrada. Para la segunda variante, la entrada consiste en un único objeto GEOGRAPHY y un arreglo de objetos GEOGRAPHY, cada uno de los cuales contiene exactamente una LineString. El primer objeto GEOGRAPHY en cualquiera de las variantes se usa para construir el perímetro del polígono. Los objetos GEOGRAPHY adicionales proporcionados en el ARRAY de entrada especifican un agujero del polígono. Para cada objeto GEOGRAPHY de entrada que contenga exactamente una LineString, los siguientes enunciados deben ser ciertos:

  • La LineString debe constar de al menos tres vértices distintos.
  • La LineString debe estar cerrada; es decir, el primer y último vértice deben ser iguales. Si el primer y último vértice difieren, la función construye una arista final desde el primer vértice hasta el último.

Para la primera variante de ST_MAKEPOLYGON, si alguna de las entradas GEOGRAPHY es NULL, muestra NULL. Para la segunda variante, si el ARRAY de entrada o cualquier elemento de este ARRAY es NULL, ST_MAKEPOLYGON muestra NULL.

NOTA: ST_MAKEPOLYGON acepta un objeto GEOGRAPHY vacío como entrada. ST_MAKEPOLYGON interpreta que un objeto GEOGRAPHY vacío tiene una LineString vacía, lo que creará un bucle completo; es decir, un polígono que cubre toda la Tierra.

Limitaciones

Juntos, los anillos de entrada deben formar un polígono válido:

  • El perímetro del polígono debe cubrir cada uno de los agujeros del polígono.
  • Solo puede haber un perímetro del polígono (que debe ser el primer anillo de entrada). Esto implica que los agujeros del polígono no se pueden anidar.
  • Los anillos del polígono solo pueden cruzarse en un vértice en el límite de ambos anillos.

Cada borde debe abarcar estrictamente menos de 180 grados.

Cada anillo del polígono divide la esfera en dos regiones. La primera LineString de entrada a ST_MAKEPOLYGON forma el perímetro del polígono, y el interior se elige como la más pequeña de las dos regiones. Cada LineString de entrada posterior especifica un agujero del polígono, por lo que el interior del polígono ya está bien definido. Para definir un perímetro del polígono de modo que el interior del polígono sea la mayor de las dos regiones, consulta ST_MAKEPOLYGONORIENTED.

NOTA: El proceso de ajuste de BigQuery puede descartar bordes lo bastante cortos y juntar los dos extremos. Por lo tanto, cuando los vértices se juntan, es posible que un agujero del polígono que sea lo suficientemente pequeño pueda desaparecer, o que el objeto GEOGRAPHY de salida pueda contener solo una línea o un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

Descripción

Es igual que ST_MAKEPOLYGON, pero el orden de vértices de cada LineString de entrada determina la orientación de cada anillo del polígono. La orientación de un anillo del polígono define el interior del polígono de la siguiente manera: si alguien camina a lo largo del límite del polígono en el orden de los vértices de entrada, el interior del polígono está a la izquierda. Esto se aplica a cada anillo del polígono proporcionado.

Esta variante del constructor de polígonos es más flexible, ya que ST_MAKEPOLYGONORIENTED puede construir un polígono de modo que el interior esté a cualquiera de los lados del anillo del polígono. Sin embargo, la orientación adecuada de los anillos del polígono es crítica para construir el polígono deseado.

Si el ARRAY de entrada o cualquier elemento en el es NULL, ST_MAKEPOLYGONORIENTED muestra NULL.

NOTA: El argumento de entrada para ST_MAKEPOLYGONORIENTED puede contener un objeto GEOGRAPHY vacío. interpreta que un objeto GEOGRAPHY vacío tiene una LineString vacía, lo que creará un bucle completo; es decir, un polígono que cubre toda la Tierra.

Limitaciones

Juntos, los anillos de entrada deben formar un polígono válido:

  • El perímetro del polígono debe cubrir cada uno de los agujeros del polígono.
  • Debe haber solo un perímetro del polígono, que debe ser el primer anillo de entrada. Esto implica que los agujeros del polígono no se pueden anidar.
  • Los anillos del polígono solo pueden cruzarse en un vértice en el límite de ambos anillos.

Cada borde debe abarcar estrictamente menos de 180 grados.

ST_MAKEPOLYGONORIENTED se basa en el orden de los vértices de entrada de cada LineString para determinar la orientación del polígono. Esto se aplica al perímetro del polígono y a los agujeros del polígono. ST_MAKEPOLYGONORIENTED espera que todos los agujeros del polígono tengan la orientación opuesta al perímetro. Consulta ST_MAKEPOLYGON con el fin de obtener más información sobre un constructor de polígonos alternativo y otras restricciones para compilar un polígono válido.

NOTA: Debido al proceso de ajuste de BigQuery, los bordes con una longitud lo bastante corta se descartarán y los dos extremos se unirán en un solo punto. Por lo tanto, es posible que los vértices en una LineString se junten de manera tal que una o más aristas desaparezcan. Entonces, es posible que un agujero del polígono que sea lo bastante pequeño pueda desaparecer, o que el objeto GEOGRAPHY resultante pueda contener solo una línea o un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

Descripción

Muestra un valor GEOGRAPHY que corresponde a la representación GeoJSON de entrada.

ST_GEOGFROMGEOJSON acepta entradas que cumplan con RFC 7946.

Un objeto GEOGRAPHY de BigQuery tiene bordes geodésicos esféricos, mientras que un objeto Geometry de GeoJSON tiene de forma explícita bordes planos. Para generar una conversión entre estos dos tipos de bordes, BigQuery agrega puntos adicionales a la línea cuando sea necesario para que la secuencia resultante de bordes permanezca dentro de los 10 metros del borde original.

Consulta ST_ASGEOJSON para formatear un objeto GEOGRAPHY como GeoJSON.

Limitaciones

La entrada está sujeta a las siguientes restricciones:

  • ST_GEOGFROMGEOJSON solo acepta fragmentos de geometría JSON y no se puede usar para transferir un documento JSON completo.
  • El fragmento JSON de entrada debe constar de un tipo de geometría GeoJSON, que incluye Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon y GeometryCollection. Cualquier otro tipo de GeoJSON, como Feature o FeatureCollection, generará un error.
  • Una posición en el miembro de coordinates de un tipo de geometría GeoJSON debe constar de exactamente dos elementos. El primero es la longitud y el segundo es la latitud. Por lo tanto, ST_GEOGFROMGEOJSON no admite el tercer elemento opcional para una posición en el miembro de coordinates.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)
ST_GEOGFROMTEXT(wkt_string, oriented)

Descripción

Muestra un valor GEOGRAPHY que corresponde a la representación WKT de entrada.

Esta función admite un parámetro opcional de tipo BOOL, oriented. Si este parámetro se establece en TRUE, se supone que cualquier polígono en la entrada está orientado de la siguiente manera: si alguien camina por el límite del polígono en el orden de los vértices de entrada, el interior del polígono está a la izquierda. Esto permite que WKT represente polígonos más grandes que un hemisferio. Si oriented es FALSE o se omite, esta función muestra el polígono con el área más pequeña. Consulta también ST_MAKEPOLYGONORIENTED, que es similar a ST_GEOGFROMTEXT con oriented=TRUE.

Para formatear GEOGRAPHY como WKT, usa ST_ASTEXT.

Limitaciones

Se supone que todos los bordes de entrada son geodésicos esféricos y no líneas rectas planas. Para leer datos en una proyección plana, considera usar ST_GEOGFROMGEOJSON. Para obtener más información sobre las diferencias entre las geodésicas esféricas y las líneas planas, consulta los bordes y sistemas de coordenadas.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

La siguiente consulta lee la string WKT POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) como un polígono no orientado y como un polígono orientado, y comprueba si cada resultado contiene el punto (1, 1).

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

Descripción

Muestra un valor GEOGRAPHY que corresponde a la representación WKB de entrada.

Para formatear GEOGRAPHY como WKB, usa ST_ASBINARY.

Limitaciones

Se supone que todos los bordes de entrada son geodésicos esféricos y no líneas rectas planas. Para leer datos en una proyección plana, considera usar ST_GEOGFROMGEOJSON.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

Descripción

Muestra un valor GEOGRAPHY que corresponde a un punto en el medio de un cuadro de límite definido en GeoHash.

Tipo de datos que se muestra

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

Descripción

Muestra la representación GeoJSON que cumple con RFC 7946 del objeto GEOGRAPHY de entrada.

Un objeto GEOGRAPHY de BigQuery tiene bordes geodésicos esféricos, mientras que un objeto Geometry de GeoJSON tiene de forma explícita bordes planos. Para generar una conversión entre estos dos tipos de bordes, BigQuery agrega puntos adicionales a la línea cuando sea necesario para que la secuencia resultante de bordes permanezca dentro de los 10 metros del borde original.

Consulta ST_GEOGFROMGEOJSON para construir un objeto GEOGRAPHY a partir de GeoJSON.

Tipo de datos que se muestra

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

Descripción

Muestra la representación WKT de un GEOGRAPHY de entrada.

Consulta ST_GEOGFROMTEXT para construir un objeto GEOGRAPHY a partir de WKT.

Tipo de datos que se muestra

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Descripción

Muestra una representación de GeoHash de geography_expression. El GeoHash resultante contendrá como máximo maxchars caracteres. Menos caracteres corresponden a una precisión menor (o, descrito de manera diferente, a un cuadro de límite más grande).

ST_GeoHash sobre un objeto GEOGRAPHY vacío muestra NULL.

Limitaciones

  • Solo se admiten objetos GEOGRAPHY que representan puntos únicos.
  • El valor máximo de maxchars es 20.

Ejemplo

Muestra un GeoHash del Seattle Center con 10 caracteres de precisión.

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

Tipo de datos que se muestra

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

Descripción

Muestra la representación WKB de un GEOGRAPHY de entrada.

Consulta ST_GEOGFROMWKB para construir un objeto GEOGRAPHY a partir de WKB.

Tipo de datos que se muestra

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

Descripción

Muestra un único objeto GEOGRAPHY que contiene la unión de los límites de cada componente en el objeto de entrada proporcionado.

El límite de cada componente de un objeto GEOGRAPHY se define de la siguiente manera:

  • El límite de un punto está vacío.
  • El límite de una LineString consiste en los extremos de la LineString.
  • El límite de un polígono consiste en las LineString que forman el perímetro del polígono y cada uno de los agujeros del polígono.

Tipo de datos que se muestra

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

Descripción

Muestra el centroide del objeto GEOGRAPHY de entrada como un GEOGRAPHY de un solo punto.

El centroide de un objeto GEOGRAPHY es el promedio ponderado de los centroides de los componentes de mayor dimensión en el GEOGRAPHY. El centroide para componentes en cada dimensión se define de la siguiente manera:

  • El centroide de puntos es la media aritmética de las coordenadas de entrada.
  • El centroide de las LineString es el centroide de todos los bordes ponderados por la longitud. El centroide de cada borde es el punto medio geodésico del borde.
  • El centroide de un polígono es su centro de masa.

Si el GEOGRAPHY de entrada está vacío, se muestra un objeto vacío.

Limitaciones

En el improbable caso de que el centroide de un GEOGRAPHY no pueda definirse por un solo punto en la superficie de la Tierra, se muestra un punto determinista, pero arbitrario. Esto solo puede suceder si el centroide está exactamente en el centro de la Tierra, como el centroide de un par de puntos antipodales, y la probabilidad de que esto ocurra es muy pequeña.

Tipo de datos que se muestra

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)
ST_CLOSESTPOINT(geography_1, geography_2, use_spheroid)

Descripción

Muestra un GEOGRAPHY que contiene un punto en geography_1 con la menor distancia posible a geography_2. Esto implica que la distancia entre el punto que muestra ST_CLOSESTPOINT y geography_2 es menor o igual que la distancia entre cualquier otro punto en geography_1 y geography_2.

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_CLOSESTPOINT muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

Descripción

Muestra un GEOGRAPHY que representa la diferencia de conjunto de puntos de geography_1 y geography_2.

Si geometry_1 está contenido por completo en geometry_2, ST_DIFFERENCE muestra un GEOGRAPHY vacío.

Limitaciones

Los objetos geométricos subyacentes que representan un objeto GEOGRAPHY de BigQuery corresponden a un conjunto de puntos cerrado. Por lo tanto, ST_DIFFERENCE es el cierre de la diferencia de conjunto de puntos entre geography_1 y geography_2. Esto implica que, si geography_1 y geography_2 se intersecan, una parte del límite de geography_2 podría aparecer en la diferencia.

Tipo de datos que se muestra

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

Descripción

Muestra un objeto GEOGRAPHY que representa la intersección del conjunto de puntos de los dos objetos de entrada. Por lo tanto, cada punto en la intersección aparece en geography_1 y en geography_2.

Si los dos objetos GEOGRAPHY de entrada son inconexos, es decir, no hay puntos que aparezcan en geometry_1 y en geometry_2, se muestra un objeto vacío.

Consulta ST_INTERSECTS, ST_DISJOINT para ver funciones de predicado relacionadas.

Tipo de datos que se muestra

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

Descripción

Muestra el objeto GEOGRAPHY de entrada, en el que cada vértice se ajustó a una cuadrícula de longitud/latitud. El tamaño de la cuadrícula está determinado por el parámetro grid_size, que se presenta en grados.

Limitaciones

No se admiten los tamaños de cuadrícula arbitrarios. El parámetro grid_size se redondea para que tenga la forma \(10^n\), donde \(-10 < n < 0\).

Tipo de datos que se muestra

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)

Descripción

Muestra un objeto GEOGRAPHY que representa la unión del conjunto de puntos de todos los objetos de entrada.

ST_UNION tiene dos variantes. Para la primera variante, la entrada debe ser de dos objetos GEOGRAPHY. Para la segunda, la entrada es un ARRAY de tipo GEOGRAPHY.

Para la primera variante de ST_UNION, si un objeto GEOGRAPHY de entrada es NULL, muestra NULL. Para la segunda variante, si el valor de ARRAY de entrada es NULL, muestra NULL. Para un ARRAY de entrada no NULL, se calcula la unión y los elementos NULL se ignoran, de manera que no afecten el resultado.

Consulta ST_UNION_AGG para ver la versión agregada de ST_UNION.

Tipo de datos que se muestra

GEOGRAPHY

ST_X

ST_X(geography_expression)

Descripción

Muestra la longitud en grados del objeto GEOGRAPHY de entrada de un solo punto.

Para cualquier objeto GEOGRAPHY de entrada que no sea un punto único, incluido un vacío, ST_X muestra un error. Usa el prefijo SAFE. para obtener NULL.

Tipo de datos que se muestra

FLOAT64

Ejemplo

En el siguiente ejemplo, se usan ST_X y ST_Y para extraer coordenadas de geografías de un solo punto.

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

Descripción

Muestra la latitud en grados del objeto GEOGRAPHY de entrada de un solo punto.

Para cualquier objeto GEOGRAPHY de entrada que no sea un punto único, incluido un vacío, ST_Y muestra un error. Usa el prefijo SAFE. para mostrar NULL en su lugar.

Tipo de datos que se muestra

FLOAT64

Ejemplo

Consulta ST_X para ver un ejemplo de uso.

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

Descripción

Muestra TRUE si ningún punto de geography_2 está fuera de geography_1 y los interiores se cruzan; de lo contrario, muestra FALSE.

NOTA: Un objeto GEOGRAPHY no contiene su propio límite. Compara esto con ST_COVERS.

Tipo de datos que se muestra

BOOL

Ejemplo

En la siguiente consulta, se prueba si el polígono POLYGON((1 1, 20 1, 10 20, 1 1)) contiene cada uno de los tres puntos (0, 0), (1, 1) y (10, 10), que se encuentran en el exterior, el límite y el interior del polígono, respectivamente.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | false    |
| POINT(1 1)   | false    |
| POINT(10 10) | true     |
+--------------+----------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

Descripción

Muestra FALSE si geography_1 o geography_2 están vacíos. Muestra TRUE si ningún punto de geography_1 está en el exterior de geography_2.

Dados dos GEOGRAPHY, a y b, ST_COVEREDBY(a, b) muestra el mismo resultado que ST_COVERS(b, a). Ten en cuenta el orden opuesto de los argumentos.

Tipo de datos que se muestra

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

Descripción

Muestra FALSE si geography_1 o geography_2 están vacíos. Muestra TRUE si ningún punto de geography_2 está en el exterior de geography_1.

Tipo de datos que se muestra

BOOL

Ejemplo

En la siguiente consulta, se prueba si el polígono POLYGON((1 1, 20 1, 10 20, 1 1)) abarca cada uno de los tres puntos (0, 0), (1, 1) y (10, 10), que se encuentran en el exterior, el límite y el interior del polígono, respectivamente.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | false  |
| POINT(1 1)   | true   |
| POINT(10 10) | true   |
+--------------+--------+

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

Descripción

Muestra TRUE si la intersección de geography_1 y geography_2 está vacía, es decir, ningún punto en geography_1 aparece en geography_2.

ST_DISJOINT es la negación lógica de ST_INTERSECTS.

Tipo de datos que se muestra

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2, distance)
ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

Descripción

Muestra TRUE si la distancia entre al menos un punto en geography_1 y un punto en geography_2 es menor o igual que la distancia dada por el argumento distance; de lo contrario, muestra FALSE. Si alguna de las entradas GEOGRAPHY está vacía, ST_DWithin muestra FALSE. El distance dado está en metros sobre la superficie de la Tierra.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

Descripción

Muestra TRUE si geography_1 y geography_2 representan el mismo valor GEOGRAPHY. Más precisamente, esto significa que se cumple una de las siguientes condiciones:

  • ST_COVERS(geography_1, geography_2) = TRUE y ST_COVERS(geography_2, geography_1) = TRUE
  • geography_1 y geography_2 están vacíos.

Por lo tanto, dos objetos GEOGRAPHY pueden ser iguales, incluso si el orden de los puntos o vértices difiere, siempre que todavía representen la misma estructura geométrica.

Limitaciones

No se asegura que ST_EQUALS sea una función transitiva.

Tipo de datos que se muestra

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Descripción

Muestra TRUE si la intersección de conjunto de puntos de geography_1 y geography_2 no está vacía. Por lo tanto, esta función muestra TRUE si hay al menos un punto que aparece en ambos objetos GEOGRAPHY de entrada.

Si ST_INTERSECTS muestra TRUE, implica que ST_DISJOINT muestra FALSE.

Tipo de datos que se muestra

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

Descripción

Muestra TRUE si geography interseca el rectángulo entre [lng1, lng2] y [lat1, lat2]. Los bordes del rectángulo siguen líneas constantes de longitud y latitud. lng1 y lng2 especifican las líneas de longitud mínima y máxima que delimitan al rectángulo, y lat1 y lat2 especifican las líneas de latitud constante mínima y máxima que delimitan el rectángulo.

Especifica todos los argumentos de longitud y latitud en grados.

Limitaciones

Los argumentos de entrada están sujetos a las siguientes restricciones:

  • Las latitudes deben estar en el rango de grados [-90, 90].
  • Las longitudes deben estar en el rango de grados [-180, 180].

Tipo de datos que se muestra

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

Descripción

Muestra TRUE siempre que se cumplan las dos condiciones siguientes:

  1. geography_1 y geography_2 se intersecan.
  2. El interior de geography_1 y el interior de geography_2 son inconexos.

Tipo de datos que se muestra

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Descripción

Muestra TRUE si ningún punto de geography_1 está fuera de geography_2 y los interiores de geography_1 y geography_2 se intersecan.

Dadas dos geografías a y b, ST_WITHIN(a, b) muestra el mismo resultado que ST_CONTAINS(b, a). Ten en cuenta el orden opuesto de los argumentos.

Tipo de datos que se muestra

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

Descripción

Muestra TRUE si el objeto GEOGRAPHY proporcionado está vacío; es decir, GEOGRAPHY no contiene puntos, líneas ni polígonos.

NOTA: Un objeto GEOGRAPHY vacío de BigQuery no está asociado con una forma geométrica particular. Por ejemplo, los resultados de las expresiones ST_GEOGFROMTEXT('POINT EMPTY') y ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') son idénticos.

Tipo de datos que se muestra

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

Descripción

Muestra TRUE si la cantidad total de puntos, LineString y polígonos es mayor que uno.

Un objeto GEOGRAPHY vacío no es una colección.

Tipo de datos que se muestra

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

Descripción

Muestra la dimensión del elemento de mayor dimensión en el objeto GEOGRAPHY de entrada.

La dimensión de cada elemento posible es la siguiente:

  • La dimensión de un punto es 0.
  • La dimensión de una LineString es 1.
  • La dimensión de un polígono es 2.

Si el objeto GEOGRAPHY de entrada está vacío, ST_DIMENSION muestra -1.

Tipo de datos que se muestra

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

Descripción

Muestra la cantidad de vértices en el objeto GEOGRAPHY de entrada. Esto incluye la cantidad de puntos, vértices de LineString y vértices de polígono.

NOTA: El primer y último vértice de un anillo del polígono se cuentan como vértices distintos.

Tipo de datos que se muestra

INT64

ST_AREA

ST_AREA(geography_expression)
ST_AREA(geography_expression, use_spheroid)

Descripción

Muestra el área en metros cuadrados que cubren los polígonos en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o una línea, muestra cero. Si geography_expression es una colección, muestra el área de los polígonos en la colección; si la colección no contiene polígonos, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)
ST_DISTANCE(geography_1, geography_2, use_spheroid)

Descripción

Muestra la distancia más corta en metros entre dos objetos GEOGRAPHY no vacíos.

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_DISTANCE muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)
ST_LENGTH(geography_expression, use_spheroid)

Descripción

Muestra la longitud total en metros de las líneas en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o un polígono, muestra cero. Si geography_expression es una colección, muestra la longitud de las líneas en la colección; si la colección no contiene líneas, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)
ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

Muestra la distancia más larga en metros entre dos objetos GEOGRAPHY no vacíos; es decir, la distancia entre dos vértices donde el primer vértice está en el primer y el segundo vértice está en el segundo . Si geography_1 y geography_2 son el mismo objeto , la función muestra la distancia entre los dos vértices más distantes en ese .

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_MAXDISTANCE muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)
ST_PERIMETER(geography_expression, use_spheroid)

Descripción

Muestra la longitud en metros del límite de los polígonos en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o una línea, muestra cero. Si geography_expression es una colección, muestra el perímetro de los polígonos en la colección; si la colección no contiene polígonos, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

Descripción

Muestra un objeto GEOGRAPHY que representa la unión del conjunto de puntos de todos los objetos de entrada.

ST_UNION_AGG ignora los valores GEOGRAPHY de entrada NULL.

Consulta ST_UNION para ver la versión no agregada de ST_UNION_AGG.

Tipo de datos que se muestra

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

Descripción

Calcula el centroide del conjunto de objetos GEOGRAPHY de entrada como un de un solo punto.

El centroide sobre el conjunto de objetos GEOGRAPHY de entrada es el promedio ponderado del centroide de cada objeto GEOGRAPHY individual. Solo los objetos GEOGRAPHY con la dimensión más alta presentes en la entrada contribuyen al centroide de todo el conjunto. Por ejemplo, si la entrada contiene objetos GEOGRAPHY con líneas y objetos GEOGRAPHY con solo puntos, ST_CENTROID_AGG muestra el promedio ponderado de los objetos GEOGRAPHY con líneas, ya que esos tienen una dimensión máxima. En este ejemplo, ST_CENTROID_AGG ignora los objetos GEOGRAPHY con solo puntos cuando se calcula el centroide agregado.

ST_CENTROID_AGG ignora los valores GEOGRAPHY de entrada NULL.

Consulta ST_CENTROID a fin de ver la versión no agregada de ST_CENTROID_AGG y la definición de centroide para un valor GEOGRAPHY individual.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

Las siguientes consultas calculan el centroide agregado sobre un conjunto de valores de GEOGRAPHY. La entrada a la primera consulta contiene solo puntos y, por lo tanto, cada valor contribuye al centroide agregado. Observa también que ST_CENTROID_AGG no es equivalente a llamar a ST_CENTROID en el resultado de ST_UNION_AGG; la unión quita los duplicados, a diferencia de ST_CENTROID_AGG. La entrada a la segunda consulta tiene dimensiones mixtas, y solo los valores con la dimensión más alta del conjunto, las líneas, afectan al centroide agregado.

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)')
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+

Funciones de seguridad

BigQuery es compatible con las siguientes funciones de seguridad.

SESSION_USER

SESSION_USER()

Descripción

Muestra la dirección de correo electrónico del usuario que ejecuta la consulta.

Tipo de datos mostrados

STRING

Ejemplo

SELECT SESSION_USER() as user;

+----------------------+
| user                 |
+----------------------+
| jdoe@example.com     |
+----------------------+

Funciones de UUID

BigQuery admite las siguientes funciones de identificador único universal (UUID).

GENERATE_UUID

GENERATE_UUID()

Descripción

Muestra un identificador único universal aleatorio (UUID) como una STRING. La STRING que se muestra consta de 32 dígitos hexadecimales en cinco grupos separados por guiones en formato 8-4-4-4-12. Los dígitos hexadecimales representan 122 bits aleatorios y 6 bits fijos, en conformidad con RFC 4122 sección 4.4. La STRING que se muestra está en minúscula.

Tipo de datos mostrados

STRING

Ejemplo

La siguiente consulta genera un UUID aleatorio.

SELECT GENERATE_UUID() AS uuid;

La consulta anterior genera un resultado como el que se muestra a continuación:

+--------------------------------------+
| uuid                                 |
+--------------------------------------+
| 4192bff0-e1e0-43ce-a4db-912808c32493 |
+--------------------------------------+

Funciones de red

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

Descripción

Convierte una dirección IPv4 o IPv6 de formato de texto (STRING) a formato binario (BYTES) en orden de bytes de red.

Esta función admite los siguientes formatos para addr_str:

  • IPv4: notación en cuatro segmentos separados por puntos. Por ejemplo, 10.1.2.3.
  • IPv6: formato separado por dos puntos. Por ejemplo, 1234:5678:90ab:cdef:1234:5678:90ab:cdef. Para obtener más ejemplos, consulta la arquitectura de direccionamiento de IP versión 6.

Esta función no admite la notación CIDR, como 10.1.2.3/32.

Si esta función recibe una entrada NULL, muestra . Si la entrada se considera no válida, se produce un error OUT_OF_RANGE.

Tipo de datos mostrados

BYTES

Ejemplo

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

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

Descripción

Similar a NET.IP_FROM_STRING, pero muestra NULL en lugar de arrojar un error si la entrada no es válida.

Tipo de datos mostrados

BYTES

Ejemplo

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

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

Descripción Convierte una dirección IPv4 o IPv6 de formato binario (BYTES) en formato de orden de bytes de red a texto (STRING).

Si la entrada es de 4 bytes, esta función muestra una dirección IPv4 como una STRING. Si la entrada es de 16 bytes, muestra una dirección IPv6 como STRING.

Si esta función recibe una entrada NULL, muestra . Si la entrada tiene una longitud diferente de 4 o 16, se produce un error OUT_OF_RANGE.

Tipo de datos mostrados

STRING

Ejemplo

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

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

Descripción

Muestra una máscara de red: una secuencia de bytes con una longitud igual a num_output_bytes, en la que los primeros bits de prefix_length se establecen en 1 y los otros bits se establecen en 0. num_output_bytes y prefix_length son INT64. Esta función muestra un error si num_output_bytes no es 4 (para IPv4) o 16 (para IPv6). También muestra un error si prefix_length es negativo o mayor que 8 * num_output_bytes.

Tipo de datos mostrados

BYTES

Ejemplo

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

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

Descripción Toma addr_bin, una dirección IPv4 o IPv6 en formato binario (BYTES) en orden de bytes de red, y muestra una dirección de subred con el mismo formato. El resultado tiene la misma longitud que addr_bin, en el que los primeros bits de prefix_length son iguales a los de addr_bin y los bits restantes son 0.

Esta función arroja un error si LENGTH(addr_bin) no es 4 o 16, o si prefix_len es negativo o mayor que LENGTH(addr_bin) * 8.

Tipo de datos mostrados

BYTES

Ejemplo

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

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

Descripción

Convierte una dirección IPv4 de formato de número entero en formato binario (BYTES) en orden de bytes de red. En la entrada de número entero, el bit de menos importancia de la dirección IP se almacena en el bit menos importante del número entero, sin importar la arquitectura del host o del cliente. Por ejemplo, 1 significa 0.0.0.1 y 0x1FF significa 0.0.1.255.

Esta función comprueba que todos los 32 bits más importantes sean 0 o que todos los 33 bits más importantes sean 1 (signo extendido desde un número entero de 32 bits). En otras palabras, la entrada debe estar en el rango [-0x80000000, 0xFFFFFFFF]; de lo contrario, esta función muestra un error.

Esta función no es compatible con IPv6.

Tipo de datos mostrados

BYTES

Ejemplo

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

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

Descripción

Convierte una dirección IPv4 de formato binario (BYTES) en orden de bytes de red al formato de número entero. En la salida del número entero, el bit menos importante de la dirección IP se almacena en el bit menos importante del entero, sin importar la arquitectura del host o del cliente. Por ejemplo, 1 significa 0.0.0.1 y 0x1FF significa 0.0.1.255. El resultado está en el rango [0, 0xFFFFFFFF].

Si la longitud de entrada no es 4, esta función produce un error.

Esta función no es compatible con IPv6.

Tipo de datos mostrados

INT64

Ejemplo

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

NET.HOST

NET.HOST(url)

Descripción

Toma una URL como STRING y muestra el host como una STRING. Para obtener los mejores resultados, los valores de URL deben cumplir con el formato que define RFC 3986. Si el valor de la URL no cumple con el formato RFC 3986, esta función hace el mejor esfuerzo para analizar la entrada y mostrar un resultado relevante. Si la función no puede analizar la entrada, muestra NULL.

Nota: La función no realiza ninguna normalización.

Tipo de datos mostrados

STRING

Ejemplo

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
entrada descripción host sufijo dominio
"" entrada no válida NULL NULL NULL
"http://abc.xyz" URL estándar "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL estándar con esquema relativo, puerto, ruta y consulta, pero sin sufijo público "a.b" NULL NULL
"https://[::1]:80" URL estándar con host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL estándar con nombre de dominio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL no estándar con espacios, letras mayúsculas y sin esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI en lugar de URL: no compatible "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Descripción

Toma una URL como STRING y muestra el sufijo público (por ejemplo, com, org o net) como una STRING. Un sufijo público es un dominio de ICANN registrado en publicsuffix.org. Para obtener los mejores resultados, los valores de URL deben cumplir con el formato que define RFC 3986. Si el valor de la URL no cumple con el formato RFC 3986, esta función hace el mejor esfuerzo para analizar la entrada y mostrar un resultado relevante.

Esta función muestra NULL si se cumple alguna de las siguientes condiciones:

  • No puede analizar el host a partir de la entrada ingresada;
  • El host analizado contiene puntos adyacentes en el medio (no al principio ni al final); o bien
  • El host analizado no contiene ningún sufijo público.

Antes de buscar el sufijo público, esta función normaliza de forma temporal el host por medio de la conversión de las letras en inglés en mayúsculas a minúsculas y la codificación de todos los caracteres que no son ASCII con Punycode. La función luego muestra el sufijo público como parte del host original en lugar del host normalizado.

Nota: La función no realiza la normalización de Unicode.

Nota: Los datos del sufijo público en publicsuffix.org también contienen dominios privados. Esta función ignora los dominios privados.

Nota: Los datos del sufijo público pueden cambiar con el tiempo. En consecuencia, la entrada que produce un resultado NULL ahora puede producir un valor distinto de NULL en el futuro.

Tipo de datos mostrados

STRING

Ejemplo

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
entrada descripción host sufijo dominio
"" entrada no válida NULL NULL NULL
"http://abc.xyz" URL estándar "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL estándar con esquema relativo, puerto, ruta y consulta, pero sin sufijo público "a.b" NULL NULL
"https://[::1]:80" URL estándar con host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL estándar con nombre de dominio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL no estándar con espacios, letras mayúsculas y sin esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" URI en lugar de URL: no compatible "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Descripción

Toma una URL como una STRING y muestra el dominio registrado o registrable (el sufijo público más una etiqueta anterior), como una STRING. Para obtener los mejores resultados, los valores de URL deben cumplir con el formato que define RFC 3986. Si el valor de la URL no cumple con el formato RFC 3986, esta función hace el mejor esfuerzo para analizar la entrada y mostrar un resultado relevante.

Esta función muestra NULL si se cumple alguna de las siguientes condiciones:

  • No puede analizar el host a partir de la entrada ingresada;
  • El host analizado contiene puntos adyacentes en el medio (no al principio ni al final);
  • El host analizado no contiene ningún sufijo público; o bien
  • El host analizado contiene solo un sufijo público sin ninguna etiqueta anterior.

Antes de buscar el sufijo público, esta función normaliza de forma temporal el host por medio de la conversión de las letras mayúsculas en inglés a minúsculas y la codificación de todos los caracteres no ASCII con Punycode. Luego, la función muestra el dominio registrado o registrable como parte del host original en lugar del host normalizado.

Nota: La función no realiza la normalización de Unicode.

Nota: Los datos del sufijo público en publicsuffix.org también contienen dominios privados. Esta función no trata un dominio privado como un sufijo público. Por ejemplo, si "us.com" es un dominio privado en los datos del sufijo público, NET.REG_DOMAIN ("foo.us.com") muestra "us.com" (el sufijo público "com" más la etiqueta anterior "us") en lugar de "foo.us.com" (el dominio privado "us.com" más la etiqueta anterior "foo").

Nota: Los datos del sufijo público pueden cambiar con el tiempo. En consecuencia, la entrada que produce un resultado NULL ahora puede producir un valor distinto de NULL en el futuro.

Tipo de datos mostrados

STRING

Ejemplo

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
entrada descripción host sufijo dominio
"" entrada no válida NULL NULL NULL
"http://abc.xyz" URL estándar "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" URL estándar con esquema relativo, puerto, ruta y consulta, pero sin sufijo público "a.b" NULL NULL
"https://[::1]:80" URL estándar con host IPv6 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" URL estándar con nombre de dominio internacionalizado "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " URL no estándar con espacios, letras mayúsculas y sin esquema "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" URI en lugar de URL: no compatible "mailto" NULL NULL

Operadores

Los operadores se representan mediante caracteres especiales o palabras clave; no se usa la sintaxis de llamada a funciones. Un operador manipula cualquier cantidad de entradas de datos, también llamados operandos, y muestra un resultado.

Convenciones comunes:

  • A menos que se especifique lo contrario, todos los operadores muestran NULL cuando uno de los operandos es .
  • Todos los operadores mostrarán un error si el cálculo arroja demasiados resultados.
  • Para todas las operaciones de punto flotante, +/-inf y NaN solo se pueden mostrar si uno de los operandos es o NaN. En otros casos, se muestra un error.

En la siguiente tabla, se enumeran todos los operadores de BigQuery desde la prioridad más alta a la más baja, es decir, en el orden en que se evaluarán dentro de una declaración.

Orden de prioridad Operador Tipos de datos de entrada Nombre Aridad del operador
1 . STRUCT
Operador de acceso de campo del miembro Binario
  [ ] ARRAY Posición del arreglo. Se debe usar con OFFSET o con ORDINAL; consulta Funciones de ARRAY. Binario
2 - Todos los tipos numéricos Menos unario Unario
  ~ Número entero o BYTES NOT a nivel de bits Unario
3 * Todos los tipos numéricos Multiplicación Binario
  / Todos los tipos numéricos División Binario
4 + Todos los tipos numéricos Suma Binario
  - Todos los tipos numéricos Resta Binario
5 << Número entero o BYTES Desplazamiento de bits a la izquierda Binario
  >> Número entero o BYTES Desplazamiento de bits a la derecha Binario
6 & Número entero o BYTES AND a nivel de bits Binario
7 ^ Número entero o BYTES XOR a nivel de bits Binario
8 | Número entero o BYTES OR a nivel de bits Binario
9 (Operadores de comparación) = Cualquier tipo comparable. Consulta Tipos de datos para ver una lista completa. Igual Binario
  < Cualquier tipo comparable. Consulta Tipos de datos para ver una lista completa. Menor que Binario
  > Cualquier tipo comparable. Consulta Tipos de datos para ver una lista completa. Mayor que Binario
  <= Cualquier tipo comparable. Consulta Tipos de datos para ver una lista completa. Menor o igual que Binario
  >= Cualquier tipo comparable. Consulta Tipos de datos para ver una lista completa. Mayor o igual que Binario
  !=, <> Cualquier tipo comparable. Consulta Tipos de datos para ver 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 ver la lista. El valor [no] está dentro del rango especificado Binario
  [NOT] IN Cualquier tipo comparable. Consulta los tipos de datos para ver la lista. El valor [no] está en el conjunto de valores especificado Binario
  IS [NOT] NULL Todos El valor [no] es NULL Unario
  IS [NOT] TRUE BOOL El valor [no] es VERDADERO Unario
  IS [NOT] FALSE BOOL El valor [no] es FALSO Unario
10 NOT BOOL Lógica NOT Unario
11 AND BOOL Lógica AND Binario
12 OR BOOL Lógica OR Binario

Los operadores con la misma prioridad son asociativos a la izquierda. Esto significa que esos operadores se agrupan juntos de izquierda a 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, pero no son asociativos. Por lo tanto, se requieren paréntesis para resolver la ambigüedad. Por ejemplo:

(x < y) IS FALSE

Operadores de acceso a elementos

Operador Sintaxis Tipos de datos de entrada Tipo de datos del resultado Descripción
. expression.fieldname1… STRUCT
Tipo T almacenado en fieldname1 Operador de punto. Puede usarse para acceder a campos anidados, por ejemplo, expression.fieldname1.fieldname2...
[ ] array_expression [position_keyword (int_expression ) ] Consulta Funciones de ARRAY Tipo T almacenado en ARRAY position_keyword es OFFSET o bien ORDINAL. Consulta Funciones de ARRAY para ver las dos funciones que usan este operador.

Operadores aritméticos

Todos los operadores aritméticos aceptan la entrada del 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
Menos unario - X

NOTA: Las operaciones de dividir por cero muestran un error. Para que se muestre un resultado diferente considera usar la funciones IEEE_DIVIDE o SAFE_DIVIDE.

Tipos de resultados para Suma y Multiplicación:

 INT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

Tipos de resultados para Resta:

 INT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

Tipos de resultados para División:

 INT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

Tipos de resultados para Menos unario:

Tipo de datos de entrada Tipo de datos del resultado
INT64 INT64
NUMERIC NUMERIC
FLOAT64 FLOAT64

Operadores a nivel de bits

Todos los operadores a nivel de bits muestran el mismo tipo y la misma longitud que el primer operando.

Nombre Sintaxis Tipo de datos de entrada Descripción
NOT a nivel de bits ~ X Número entero o BYTES Realiza una negación lógica en cada bit y forma el complemento a uno del valor binario dado.
OR a nivel de bits X | Y X: Número entero o BYTES
Y: mismo tipo que X
Toma dos patrones de bits de igual longitud y realiza la operación OR inclusiva lógica en cada par de los bits correspondientes. Este operador muestra un error si Y y X son BYTES de diferentes longitudes.
XOR a nivel de bits X ^ Y X: Número entero o BYTES
Y: mismo tipo que X
Toma dos patrones de bits de igual longitud y realiza la operación OR exclusiva lógica en cada par de los bits correspondientes. Este operador muestra un error si Y y X son BYTES de diferentes longitudes.
AND a nivel de bits X & Y X: Número entero o BYTES
Y: mismo tipo que X
Toma dos patrones de bits de igual longitud y realiza la operación lógica AND en cada par de los bits correspondientes. Este operador muestra un error si Y y X son BYTES de diferentes longitudes.
Desplazamiento a la izquierda X << Y X: Número entero o BYTES
Y: INT64
Desplaza el primer operando X a la izquierda. Este operador muestra 0 o una secuencia de bytes de b'\x00' si el segundo operando Y es igual o mayor que el largo de bits del primer operando X (por ejemplo, 64 si X tiene el tipo INT64). Este operador muestra un error si Y es negativo.
Desplazamiento a la derecha X >> Y X: Número entero o BYTES
Y: INT64
Desplaza el primer operando X a la derecha. Este operador no realiza la extensión de signo con un tipo de signo (es decir, llena los bits vacantes de la izquierda con 0). Este operador muestra 0 o una secuencia de bytes de b'\x00' si el segundo operando Y es igual o mayor que el largo de bits del primer operando X (por ejemplo, 64 si X tiene el tipo INT64). Este operador muestra un error si Y es negativo.

Operadores lógicos

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

Nombre Sintaxis Descripción
Lógica NOT NOT X Muestra FALSE si la entrada es TRUE. Muestra TRUE si la entrada es FALSE. De lo contrario, muestra NULL.
Lógica AND X AND Y Muestra FALSE si al menos una entrada es FALSE. Muestra TRUE si tanto X como Y son TRUE. De lo contrario, muestra NULL.
Lógica OR X OR Y Muestra FALSE si tanto X como Y son FALSE. Muestra TRUE si al menos una entrada es TRUE. De lo contrario, muestra NULL.

Operadores de comparación

Las comparaciones siempre muestran BOOL. Por lo general, las comparaciones requieren que ambos operandos sean del mismo tipo. Si los operandos son de tipos diferentes y si BigQuery puede convertir los valores de esos tipos en un tipo común sin que se pierda la precisión, BigQuery, en general, los coerciona a ese tipo común para la comparación. Con frecuencia, BigQuery coerciona los literales al tipo de los no literales, cuando están presentes. Los tipos de datos comparables se definen en Tipos de datos.

Los STRUCT solo admiten 4 operadores de comparación: igual (=), no igual (!= Y <>) y también IN.

Las siguientes reglas se aplican cuando se comparan estos tipos de datos:

  • FLOAT64: todas las comparaciones con NaN muestran FALSE, excepto != y <>, que muestran TRUE.
  • BOOL: FALSE es menor que TRUE.
  • STRING: Las strings se comparan punto de código por punto de código, lo que significa que solo se garantiza que las strings canónicamente equivalentes se comparen como iguales si se normalizaron primero.
  • NULL: Aquí se mantiene la convención: cualquier operación con una entrada mostrará el valor .
Nombre Sintaxis Descripción
Menor que X < Y Muestra TRUE si X es menor que Y.
Menor o igual que X <= Y Muestra TRUE si X es menor o igual que Y.
Mayor que X > Y Muestra TRUE si X es mayor que Y.
Mayor o igual que X >= Y Muestra TRUE si X es mayor o igual que Y.
Igual X = Y Muestra TRUE si X es igual que Y.
No igual X != Y
X <> Y
Muestra TRUE si X no es igual que Y.
BETWEEN X [NOT] BETWEEN Y AND Z Muestra TRUE si X [no] está dentro del rango 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 primer caso.
LIKE X [NOT] LIKE Y Comprueba si la STRING del primer operando X coincide con un patrón especificado por el segundo operando Y. Las expresiones pueden contener estos 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
  • Puedes marcar "\", "_" o "%" con dos barras invertidas. Por ejemplo, "\\%". Si usas strings sin procesar, se requiere una sola barra invertida. Por ejemplo, r"\%".
IN Múltiple: ver a continuación Muestra FALSE si el operando derecho está vacío. Muestra NULL si el operando izquierdo es NULL. Muestra TRUE o NULL, nunca FALSE, si el operando derecho contiene NULL. Los argumentos a ambos lados de IN son expresiones generales. No se requiere que ninguno de los operandos sea literal, aunque lo más común es usar un literal del lado derecho. X se evalúa una sola vez.

Cuando se evalúan valores que tienen un tipo de datos STRUCT para determinar la igualdad, es posible que uno o más campos sea NULL. En esos casos:

  • Si todos los valores que no son NULL son iguales, la comparación muestra NULL.
  • Si el valor de algún campo no NULL no es igual, la comparación muestra FALSE.

En la siguiente tabla, se muestra cómo los tipos de datos STRUCT se comparan cuando tienen campos con 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 es compatible con 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 ambos lados del operador IN son expresiones generales. Es habitual el uso de literales en la expresión de la derecha; sin embargo, esto no es obligatorio.

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 arreglo se definen de forma similar.

x NOT IN ...

es equivalente a lo siguiente:

NOT(x IN ...)

El formulario UNNEST trata un análisis de arreglo como UNNEST en la cláusula FROM:

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

Este formulario se suele usar con parámetros ARRAY. Por ejemplo:

x IN UNNEST(@array_parameter)

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

Consulta el tema Arreglos para obtener información sobre cómo usar esta sintaxis.

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

  • IN con una expresión vacía del lado derecho siempre es FALSE
  • IN con una expresión NULL del lado izquierdo y una expresión no vacía del lado derecho siempre es NULL
  • IN con NULL en la lista de solo puede mostrar TRUE o NULL, nunca FALSE
  • NULL IN (NULL) muestra NULL
  • IN UNNEST(<NULL array>) muestra FALSE (no NULL)
  • NOT IN con un NULL en la lista IN solo puede mostrar FALSE o NULL, nunca TRUE

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

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

Consulta la sección Tipo Struct del tema Tipos de datos para obtener más información sobre la sintaxis.

Operadores IS

Los operadores IS muestran TRUE o FALSE para la condición que prueban. Nunca muestran NULL, ni siquiera para entradas NULL, a diferencia de la función IS_INF y la función IS_NAN que se definen 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 del resultado Descripción

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

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

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

Expresiones condicionales

Las expresiones condicionales imponen restricciones en el orden de evaluación de sus entradas. En síntesis, se evalúan de izquierda a derecha, con cortocircuito, y solo evalúan el valor de resultado elegido. 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 puede explotarse para el manejo de errores o el ajuste del rendimiento.

Sintaxis Tipos de datos de entrada Tipo de datos del 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 muestra el primer resultado en el que esta comparación sea verdadera. Las cláusulas WHEN restantes y else_result no se evalúan. Si la comparación expr = value da como resultado “falso” o NULL en todas las cláusulas WHEN, muestra else_result si está presente; si no lo está, muestra NULL. Las expresiones expr y value deben ser coercibles de manera implícita a un supertipo común; las comparaciones de igualdad se llevan a cabo con valores forzados. Las expresiones result y else_result deben ser coercibles 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 muestra el primer resultado en el que la condición sea verdadera; las cláusulas WHEN restantes y else_result no se evalúan. Si todas las condiciones son falsas o NULL, muestra else_result si está presente; si no lo está, muestra NULL. Las expresiones result y else_result deben ser coercibles de manera implícita un supertipo común.
COALESCE(expr1, …, exprN) Cualquier tipo Supertipo de tipos de entrada Muestra el valor de la primera expresión no nula. Las expresiones restantes no se evalúan. Todas las expresiones de entrada deben ser implícitamente coercibles a un supertipo común.
IF(cond, true_result, else_result) cond: BOOL true_result y else_result: cualquier tipo. Si cond es verdadero, muestra true_result; de lo contrario, muestra else_result. else_result no se evalúa si cond es verdadero. true_result no se evalúa si cond es falso o NULL. true_result y else_result deben ser coercibles a un supertipo común.
IFNULL(expr, null_result) Cualquier tipo Cualquier tipo o supertipo de tipos de entrada Si expr es NULL, muestra null_result. De lo contrario, muestra expr. Si expr no es NULL, null_result no se evalúa. expr y null_result deben ser coercibles de manera implícita 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 Muestra NULL si expression = expression_to_match es verdadero; de lo contrario, muestra expression. expression y expression_to_match deben ser coercibles de manera implícita a un supertipo común; la comparación de igualdad se realiza en valores coercionados.

Subconsultas de expresión

Hay cuatro tipos de subconsultas de expresión (es decir, subconsultas que se usan como expresiones). Las subconsultas de expresión muestran NULL o un solo valor (no una columna o tabla) y deben estar entre paréntesis. Para ver un análisis más completo de las subconsultas, ve a Subconsultas.

Tipo de subconsulta Tipo de datos del resultado Descripción
Escalar Cualquier tipo T Una subconsulta entre paréntesis dentro de una expresión (p. ej., en la lista SELECT o la cláusula WHERE) se interpreta como una subconsulta escalar. La lista SELECT de una subconsulta escalar debe tener solo un campo. Si la subconsulta muestra exactamente una fila, ese único valor es el resultado de la subconsulta escalar. Si la subconsulta muestra cero filas, el valor de la subconsulta escalar es NULL. Si la subconsulta muestra más de una fila, la consulta genera un error de tiempo de ejecución. Cuando la subconsulta se escribe con SELECT AS STRUCT, puede incluir varias columnas y el valor mostrado será el STRUCT construido. Seleccionar varias columnas sin usar SELECT AS es un error.
ARRAY ARRAY Se puede usar SELECT AS STRUCT para crear arreglos de structs; a su vez, seleccionar varias columnas sin usar SELECT AS es un error. Muestra un ARRAY vacío si el resultado de la subconsulta son cero filas. Nunca muestra un ARRAY NULL.
IN BOOL Ocurre en una expresión que sigue al operador IN. La subconsulta debe producir una sola columna cuyo tipo admita la comparación de igualdad con la expresión que está en el lado izquierdo del operador IN. El resultado es FALSE si la subconsulta muestra cero filas. x IN () es equivalente a x IN (value, value, ...). Consulta el operador IN en los operadores de comparación para obtener una semántica completa.
EXISTS BOOL Muestra TRUE si la subconsulta produce una o más filas. Muestra FALSE si la subconsulta produce cero filas. Nunca muestra NULL. A diferencia de todas las demás subconsultas de expresión, no hay reglas que se apliquen a la lista de columnas. Se puede seleccionar cualquier número de columnas sin que esto afecte el resultado de la consulta.

Ejemplos

En los siguientes ejemplos de subconsultas de expresión, se supone que t.int_array tiene el tipo ARRAY<INT64>.

Tipo Subconsulta Tipo de datos del resultado Notas
Escalar (SELECT COUNT(*) FROM t.int_array) INT64  
(SELECT DISTINCT i FROM t.int_array i) INT64, posible error de entorno de ejecución  
(SELECT i FROM t.int_array i WHERE i=5) INT64, posible error de entorno de ejecución  
(SELECT ARRAY_AGG(i) FROM t.int_array i) ARRAY Utiliza la función de agregación ARRAY_AGG para mostrar un ARRAY.
(SELECT 'xxx' a) STRING  
(SELECT 'xxx' a, 123 b) Error Muestra 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 Muestra 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 Genera un ARRAY de STRUCT de un campo.
ARRAY(SELECT AS STRUCT 1 x, 2, 3 x) ARRAY Muestra un ARRAY de STRUCT 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 de 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  

Funciones de depuración

BigQuery admite las siguientes funciones de depuración.

ERROR

ERROR(error_message)

Descripción

Muestra un error. El argumento error_message es un STRING.

BigQuery trata a ERROR de la misma manera que a cualquier expresión que pueda dar como resultado un error: no hay una garantía especial de orden de evaluación.

Tipo de datos mostrados

BigQuery infiere el tipo de retorno en contexto.

Ejemplos

En el siguiente ejemplo, la consulta muestra un mensaje de error si el valor de la fila no coincide con uno de los dos valores definidos.

SELECT
  CASE
    WHEN value = 'foo' THEN 'Value is foo.'
    WHEN value = 'bar' THEN 'Value is bar.'
    ELSE ERROR(concat('Found unexpected value: ', value))
  END AS new_value
FROM (
  SELECT 'foo' AS value UNION ALL
  SELECT 'bar' AS value UNION ALL
  SELECT 'baz' AS value);

Found unexpected value: baz

En el siguiente ejemplo, BigQuery puede evaluar la función ERROR antes o después de la condición x > 0, porque BigQuery, por lo general, no ofrece garantías de ordenamiento entre las condiciones de la cláusula WHERE y no hay garantías especiales para la función .

SELECT *
FROM (SELECT -1 AS x)
WHERE x > 0 AND ERROR('Example error');

En el siguiente ejemplo, la cláusula WHERE evalúa una condición IF, lo que garantiza que BigQuery solo evalúe la función ERROR si la condición falla.

SELECT *
FROM (SELECT -1 AS x)
WHERE IF(x > 0, true, ERROR(FORMAT('Error: x must be positive but is %t', x)));'

Error: x must be positive but is -1