Funciones definidas por el usuario de SQL estándar

BigQuery admite funciones definidas por el usuario (UDF). Una UDF te permite crear una función con otra expresión SQL o JavaScript. Estas funciones aceptan columnas de entrada y realizan acciones, para luego mostrar el resultado de esas acciones como un valor. Para obtener información sobre las funciones definidas por el usuario en el SQL heredado, consulta Funciones definidas por el usuario en el SQL heredado.

Las UDF pueden ser persistentes o temporales. Puedes reutilizar las UDF persistentes en varias consultas, mientras que solo puedes usar las UDF temporales en una sola consulta.

Sintaxis de las UDF

Para crear una UDF persistente, usa la siguiente sintaxis:

CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS]
    [`project_name`.]dataset_name.function_name
    ([named_parameter[, ...]])
  [RETURNS data_type]
  { sql_function_definition | javascript_function_definition }

Para crear una UDF temporal, usa la siguiente sintaxis:

CREATE [OR REPLACE] {TEMPORARY | TEMP} FUNCTION [IF NOT EXISTS]
    function_name
    ([named_parameter[, ...]])
  [RETURNS data_type]
  { sql_function_definition | javascript_function_definition }

named_parameter:
  param_name param_type

sql_function_definition:
  AS (sql_expression)

javascript_function_definition:
  LANGUAGE js
  [OPTIONS (library = library_array)]
  AS javascript_code

Esta sintaxis consta de los siguientes componentes:

  • CREATE { FUNCTION | OR REPLACE FUNCTION | FUNCTION IF NOT EXISTS }. Crea una función o la actualiza. Para reemplazar una función existente con el mismo nombre, usa la palabra clave OR REPLACE. Usa la cláusula IF NOT EXISTS si deseas tratar la consulta como completada y que no realice ninguna acción en el caso de que ya exista una función con el mismo nombre.
  • named_parameter. Consiste en un par de param_name and param_type separados por comas. El valor de param_type es un tipo de datos de BigQuery. Para una UDF de SQL, el valor de param_type también puede ser ANY TYPE.
  • [RETURNS data_type]. Especifica el tipo de datos que muestra la función.
    • Si la función está definida en SQL, entonces la cláusula RETURNS es opcional. Si se omite la cláusula RETURNS, BigQuery deduce el tipo de resultado de la función a partir del cuerpo de la función SQL cuando una consulta llama a la función.
    • Si la función está definida en JavaScript, entonces la cláusula RETURNS es obligatoria. Consulta los Tipos de datos de UDF de JavaScript admitidos a fin de obtener más información sobre los valores permitidos para data_type.
  • AS (sql_expression). Especifica la expresión SQL que define la función.
  • [OPTIONS (library = library_array)]. Para un UDF de JavaScript, especifica un arreglo de bibliotecas de JavaScript para incluir en la definición de función.
  • AS javascript_code. Especifica la definición de una función de JavaScript. javascript_code es un literal de string.

Para borrar una función definida por el usuario persistente, usa la siguiente sintaxis:

DROP FUNCTION [IF EXISTS] [`project_name`.]dataset_name.function_name

Las funciones temporales definidas por el usuario se vencen cuando finaliza la consulta y, por lo tanto, no son compatibles con las declaraciones DROP FUNCTION, salvo en secuencias de comandos y procedimientos.

Estructura de UDF de SQL

Crea UDF de SQL con la siguiente sintaxis:

CREATE [OR REPLACE] [TEMPORARY | TEMP] FUNCTION [IF NOT EXISTS]
    [[`project_name`.]dataset_name.]function_name
    ([named_parameter[, ...]])
  [RETURNS data_type]
  AS (sql_expression)

named_parameter:
  param_name param_type

Parámetros de UDF de SQL con plantilla

Un parámetro con plantilla con param_type = ANY TYPE puede coincidir con más de un tipo de argumento cuando se llama a la función.

  • Si hay más de un parámetro con el tipo ANY TYPE, BigQuery no impone ninguna relación entre estos argumentos.
  • La función tipo de datos que se muestra no puede ser ANY TYPE. Debe omitirse, lo que significa que se determina de forma automática en función de sql_expression, o debe ser un tipo explícito.
  • Si pasas los argumentos de funciones de tipos que son incompatibles con la definición de la función, se producirá un error durante la llamada.

Ejemplos de UDF de SQL

En el siguiente ejemplo se muestra una UDF que emplea una función de SQL.

CREATE TEMP FUNCTION addFourAndDivide(x INT64, y INT64) AS ((x + 4) / y);
WITH numbers AS
  (SELECT 1 as val
  UNION ALL
  SELECT 3 as val
  UNION ALL
  SELECT 4 as val
  UNION ALL
  SELECT 5 as val)
SELECT val, addFourAndDivide(val, 2) AS result
FROM numbers;

+-----+--------+
| val | result |
+-----+--------+
| 1   | 2.5    |
| 3   | 3.5    |
| 4   | 4      |
| 5   | 4.5    |
+-----+--------+

En el siguiente ejemplo se muestra una UDF de SQL que usa un parámetro con plantilla. La función resultante acepta argumentos de varios tipos.

CREATE TEMP FUNCTION addFourAndDivideAny(x ANY TYPE, y ANY TYPE) AS (
  (x + 4) / y
);
SELECT addFourAndDivideAny(3, 4) AS integer_output,
       addFourAndDivideAny(1.59, 3.14) AS floating_point_output;

+----------------+-----------------------+
| integer_output | floating_point_output |
+----------------+-----------------------+
| 1.75           | 1.7802547770700636    |
+----------------+-----------------------+

En el siguiente ejemplo, se muestra una UDF de SQL que usa un parámetro con plantilla para mostrar el último elemento de un arreglo de cualquier tipo.

CREATE TEMP FUNCTION lastArrayElement(arr ANY TYPE) AS (
  arr[ORDINAL(ARRAY_LENGTH(arr))]
);
SELECT
  names[OFFSET(0)] AS first_name,
  lastArrayElement(names) AS last_name
FROM (
  SELECT ['Fred', 'McFeely', 'Rogers'] AS names UNION ALL
  SELECT ['Marie', 'Skłodowska', 'Curie']
);

+------------+-----------+
| first_name | last_name |
+------------+-----------+
| Fred       | Rogers    |
| Marie      | Curie     |
+------------+-----------+

Estructura de una UDF de JavaScript

Crea una UDF de JavaScript mediante la siguiente estructura.

CREATE [OR REPLACE] [TEMPORARY | TEMP] FUNCTION [IF NOT EXISTS]
    [[`project_name`.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  LANGUAGE js
  [OPTIONS (library = library_array)]
  AS javascript_code

Ejemplos de UDF de JavaScript

CREATE TEMP FUNCTION multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE js AS """
  return x*y;
""";
WITH numbers AS
  (SELECT 1 AS x, 5 as y
  UNION ALL
  SELECT 2 AS x, 10 as y
  UNION ALL
  SELECT 3 as x, 15 as y)
SELECT x, y, multiplyInputs(x, y) as product
FROM numbers;

+-----+-----+--------------+
| x   | y   | product      |
+-----+-----+--------------+
| 1   | 5   | 5            |
| 2   | 10  | 20           |
| 3   | 15  | 45           |
+-----+-----+--------------+

Puedes pasar el resultado de una UDF como entrada para otra UDF. Por ejemplo:

CREATE TEMP FUNCTION multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE js AS """
  return x*y;
""";
CREATE TEMP FUNCTION divideByTwo(x FLOAT64)
RETURNS FLOAT64
LANGUAGE js AS """
  return x/2;
""";
WITH numbers AS
  (SELECT 1 AS x, 5 as y
  UNION ALL
  SELECT 2 AS x, 10 as y
  UNION ALL
  SELECT 3 as x, 15 as y)
SELECT x,
  y,
  multiplyInputs(divideByTwo(x), divideByTwo(y)) as half_product
FROM numbers;

+-----+-----+--------------+
| x   | y   | half_product |
+-----+-----+--------------+
| 1   | 5   | 1.25         |
| 2   | 10  | 5            |
| 3   | 15  | 11.25        |
+-----+-----+--------------+

El siguiente ejemplo suma los valores de todos los campos llamados “foo” en la string de JSON dada.

CREATE TEMP FUNCTION SumFieldsNamedFoo(json_row STRING)
  RETURNS FLOAT64
  LANGUAGE js AS """
function SumFoo(obj) {
  var sum = 0;
  for (var field in obj) {
    if (obj.hasOwnProperty(field) && obj[field] != null) {
      if (typeof obj[field] == "object") {
        sum += SumFoo(obj[field]);
      } else if (field == "foo") {
        sum += obj[field];
      }
    }
  }
  return sum;
}
var row = JSON.parse(json_row);
return SumFoo(row);
""";

WITH Input AS (
  SELECT STRUCT(1 AS foo, 2 AS bar, STRUCT('foo' AS x, 3.14 AS foo) AS baz) AS s, 10 AS foo UNION ALL
  SELECT NULL, 4 AS foo UNION ALL
  SELECT STRUCT(NULL, 2 AS bar, STRUCT('fizz' AS x, 1.59 AS foo) AS baz) AS s, NULL AS foo
)
SELECT
  TO_JSON_STRING(t) AS json_row,
  SumFieldsNamedFoo(TO_JSON_STRING(t)) AS foo_sum
FROM Input AS t;
+---------------------------------------------------------------------+---------+
| json_row                                                            | foo_sum |
+---------------------------------------------------------------------+---------+
| {"s":{"foo":1,"bar":2,"baz":{"x":"foo","foo":3.14}},"foo":10}       | 14.14   |
| {"s":null,"foo":4}                                                  | 4       |
| {"s":{"foo":null,"bar":2,"baz":{"x":"fizz","foo":1.59}},"foo":null} | 1.59    |
+---------------------------------------------------------------------+---------+

Consulta la página sobre tipos de datos UDF de JavaScript admitidos para obtener información sobre cómo los tipos de datos de BigQuery se asignan a los tipos de JavaScript.

Tipos de datos de UDF de JavaScript admitidos

Algunos tipos de SQL se corresponden de forma directa con tipos de JavaScript, pero otros no. BigQuery representa los tipos de la siguiente manera:

Tipos de datos de BigQuery Tipo de datos de JavaScript
ARRAY ARRAY
BOOL BOOLEAN
BYTES STRING codificada en base64
FLOAT64 NUMBER
NUMERIC Si un valor NUMERIC se puede representar de forma exacta como un valor de punto flotante IEEE 754 y no tiene una parte fraccionaria, se codifica como un Número. Estos valores están en el rango [-253, 253]. De lo contrario, se codifica como una String.
STRING STRING
STRUCT OBJECT en el que cada campo de STRUCT tiene nombre
MARCA DE TIEMPO DATE con un campo de microsegundos que contiene la fracción de microsecond de la marca de tiempo
DATE DATE

Debido a que JavaScript no admite un tipo de número entero de 64 bits, INT64 no es compatible como tipo de entrada para UDF de JavaScript. En su lugar, usa FLOAT64 a fin de representar valores como un número entero, o STRING para representarlos como una string.

BigQuery admite INT64 como un tipo de datos que se muestra en las UDF de JavaScript. En este caso, el cuerpo de la función de JavaScript puede mostrar una String o un Número de JavaScript. BigQuery luego convierte cualquiera de estos tipos en INT64.

Si el valor de retorno del UDF de JavaScript es una Promise, BigQuery espera hasta que se establezca la Promise. Si Promise se establece en un estado entregado, BigQuery muestra su resultado. Si Promise se establece en un estado rechazado, BigQuery muestra un error.

Reglas de citación

Debes encerrar el código de JavaScript entre comillas. Para fragmentos de código simples de una línea, puedes usar una string entre comillas estándar, como la siguiente:

CREATE TEMP FUNCTION plusOne(x FLOAT64)
RETURNS FLOAT64
LANGUAGE js
AS "return x+1;";
SELECT val, plusOne(val) AS result
FROM UNNEST([1, 2, 3, 4, 5]) AS val;

+-----------+-----------+
| val       | result    |
+-----------+-----------+
| 1         | 2         |
| 2         | 3         |
| 3         | 4         |
| 4         | 5         |
| 5         | 6         |
+-----------+-----------+

En los casos en que el fragmento de código contiene comillas o consta de varias líneas, usa bloques con comillas triples:

CREATE TEMP FUNCTION customGreeting(a STRING)
RETURNS STRING
LANGUAGE js AS """
  var d = new Date();
  if (d.getHours() < 12) {
    return 'Good Morning, ' + a + '!';
  } else {
    return 'Good Evening, ' + a + '!';
  }
  """;
SELECT customGreeting(names) as everyone
FROM UNNEST(["Hannah", "Max", "Jakob"]) AS names;
+-----------------------+
| everyone              |
+-----------------------+
| Good Morning, Hannah! |
| Good Morning, Max!    |
| Good Morning, Jakob!  |
+-----------------------+

Incluye bibliotecas de JavaScript

Puedes extender tus UDF de JavaScript mediante la sección OPTIONS. Esta sección te permite especificar bibliotecas de código externas para la UDF.

CREATE TEMP FUNCTION myFunc(a FLOAT64, b STRING)
  RETURNS STRING
  LANGUAGE js
  OPTIONS (
    library=["gs://my-bucket/path/to/lib1.js", "gs://my-bucket/path/to/lib2.js"]
  )
  AS
"""
    // Assumes 'doInterestingStuff' is defined in one of the library files.
    return doInterestingStuff(a, b);
""";

SELECT myFunc(3.14, 'foo');

En el ejemplo anterior, el código en lib1.js y lib2.js está disponible para cualquier código en la sección [external_code] de la UDF.

Las UDF y la IU web

Puedes usar la IU web de BigQuery para ejecutar consultas con una o más UDF.

Ejecuta una consulta con una UDF

  1. Haz clic en el botón REDACTAR CONSULTA.
  2. Haz clic en la pestaña Editor de consultas.
  3. Haz clic en el botón Mostrar opciones.
  4. Desmarca la casilla de verificación Usar SQL heredado.
  5. Escribe la declaración de UDF en el área de texto del Editor de consultas. Por ejemplo:

    CREATE TEMPORARY FUNCTION timesTwo(x FLOAT64)
    RETURNS FLOAT64
      LANGUAGE js AS """
      return x*2;
    """;
  6. Escribe tu consulta debajo de la declaración de UDF. Por ejemplo:

    SELECT timesTwo(numbers) AS doubles
    FROM UNNEST([1, 2, 3, 4, 5]) AS numbers;
  7. Haz clic en el botón EJECUTAR CONSULTA. Los resultados de la consulta se muestran debajo de los botones.

Las UDF y la herramienta de línea de comandos de bq

Puedes usar la herramienta de línea de comandos bq del SDK de Google Cloud para ejecutar una consulta que contenga una o más UDF.

Usa la siguiente sintaxis para ejecutar una consulta con una UDF:

bq query <statement_with_udf_and_query>

Recomendaciones para las UDF de JavaScript

Realiza un filtro previo a tu entrada

Si tu entrada se puede filtrar con facilidad antes de pasarla a una UDF de JavaScript, es probable que tu consulta sea más rápida y económica.

Evita el estado mutable persistente

No almacenes ni accedas a un estado mutable en llamadas a la UDF de JavaScript.

Usa la memoria de manera eficaz

El entorno de procesamiento de JavaScript tiene memoria limitada disponible por consulta. Las consultas de las UDF de JavaScript que acumulan demasiado estado local pueden fallar debido al agotamiento de la memoria.

Límites

  • Cantidad de datos que tu UDF de JavaScript genera cuando procesa una única fila: aproximadamente 5 MB o menos
  • Límite de frecuencia de simultaneidad para consultas de SQL heredadas que contengan funciones definidas por el usuario (UDF): 6 consultas simultáneas
  • El límite de frecuencia de simultaneidad para consultas de SQL heredado que contienen UDF incluye las consultas interactivas y por lotes. Las consultas interactivas que contienen UDF también se toman en cuenta en el límite de frecuencia de simultaneidad de las consultas interactivas. Este límite no se aplica a consultas de SQL estándar.

  • Cantidad máxima de recursos de UDF de JavaScript, como archivos externos o BLOB de código intercalados, en un trabajo de consulta: 50
  • Tamaño máximo de cada BLOB de código intercalado: 32 KB
  • Tamaño máximo de cada recurso de código externo: 1 MB

Se aplican los siguientes límites a las funciones persistentes definidas por el usuario.
  • Largo máximo de un nombre de función: 256 caracteres
  • Cantidad máxima de argumentos: 256
  • Largo máximo de un nombre de argumento: 128 caracteres
  • Profundidad máxima de una cadena de referencia de función definida por el usuario: 16
  • Profundidad máxima del argumento o resultado de tipo STRUCT: 15
  • Cantidad máxima de campos en un argumento o resultado de tipo STRUCT por UDF: 1,024
  • Cantidad máxima de UDF únicas más las referencias de tablas por consulta: 1,000 Después de una expansión completa, cada UDF puede hacer referencia hasta a 1,000 tablas y UDF únicas combinadas.
  • Cantidad máxima de bibliotecas JavaScript en la declaración CREATE FUNCTION: 50
  • Largo máximo de rutas de acceso a bibliotecas JavaScript incluidas: 5,000 caracteres
  • Frecuencia de actualización máxima por UDF: 5 veces cada 10 segundos Después de crear la función, puedes actualizar cada función hasta 5 veces cada 10 segundos.
  • Cada BLOB de código intercalado tiene un límite de tamaño de 32 KB
  • Cada recurso de código de JavaScript tiene un límite de tamaño máximo de 1 MB

Limitaciones

Las siguientes limitaciones se aplican a funciones temporales y a funciones persistentes definidas por el usuario:

  • No se admiten los objetos DOM Window, Document y Node, ni las funciones que los requieren.
  • Las funciones de JavaScript que se basan en el código nativo no son compatibles.
  • Una UDF de JavaScript puede agotar el tiempo de espera y evitar que se complete tu consulta. Los tiempos de espera pueden ser tan solo de 5 minutos, pero pueden variar según distintos factores, incluidos el tiempo de CPU del usuario que consume tu función y el tamaño de tus entradas y salidas en la función de JS.
  • Debido a su naturaleza no determinista, las consultas que invocan funciones de JavaScript definidas por el usuario no pueden usar resultados almacenados en caché.
  • Las operaciones a nivel de bits en JavaScript manejan solo los 32 bits más significativos.
  • No puedes hacer referencia a una tabla en una UDF.

Las siguientes limitaciones se aplican a las funciones persistentes definidas por el usuario:

  • Cada conjunto de datos solo puede contener una UDF persistente con el mismo nombre. Sin embargo, puedes crear una UDF cuyo nombre sea igual al de una tabla en el mismo conjunto de datos.
  • Cuando se hace referencia a una UDF persistente desde otra UDF persistente, debes calificar el nombre con el conjunto de datos. Por ejemplo:
    CREATE FUNCTION mydataset.referringFunction() AS (mydataset.referencedFunction());
  • Cuando se hace referencia a una UDF persistente desde una vista lógica, debes calificar el nombre completo con el proyecto y conjunto de datos. Por ejemplo:
    CREATE VIEW mydataset.sample_view AS SELECT `my-project`.mydataset.referencedFunction();

Las limitaciones siguientes se aplican a las funciones temporales definidas por el usuario.

  • Cuando creas una UDF temporal, el function_name no puede contener puntos.
  • Las vistas lógicas y las UDF persistentes no pueden hacer referencia a las UDF temporales.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.