CREATE EXTERNAL FUNCTION

Crea una función definida por el usuario (UDF) escalar basada en AWS Lambda para Amazon Redshift. Para obtener más información acerca de las funciones de Lambda definidas por el usuario, consulte UDF de Lambda escalares.

Privilegios necesarios

Los siguientes privilegios son necesarios para CREATE EXTERNAL FUNCTION:

Sintaxis

CREATE [ OR REPLACE ] EXTERNAL FUNCTION external_fn_name ( [data_type] [, ...] )
RETURNS data_type
{ VOLATILE | STABLE }
LAMBDA 'lambda_fn_name'
IAM_ROLE { default | ‘arn:aws:iam::<Cuenta de AWS-id>:role/<role-name>’
RETRY_TIMEOUT milliseconds
MAX_BATCH_ROWS count
MAX_BATCH_SIZE size [ KB | MB ];

Parámetros

Notas de uso

Tenga en cuenta lo siguiente al crear UDF de Lambda:

Ejemplos

A continuación, se proporcionan ejemplos de uso de funciones escalares de Lambda definidas por el usuario (UDF).

Ejemplo de UDF escalar de Lambda con una función Node.js de Lambda

En el siguiente ejemplo, se crea una función externa denominada exfunc_sum que toma dos valores enteros como argumentos de entrada. Esta función devuelve la suma como una salida expresada con un número entero. El nombre de la función de Lambda a la que se llamará es lambda_sum. El lenguaje utilizado para esta función de Lambda es Node.js 12.x. Asegúrese de especificar el rol de IAM. El ejemplo utiliza 'arn:aws:iam::123456789012:user/johndoe' como rol de IAM.

CREATE EXTERNAL FUNCTION exfunc_sum(INT,INT)
RETURNS INT
VOLATILE
LAMBDA 'lambda_sum'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test';

La función de Lambda toma la carga de solicitudes e itera sobre cada fila. Se suman todos los valores de una sola fila para calcular la suma de esa fila, que se guarda en la matriz de respuesta. La cantidad de filas en la matriz de resultados es similar a la cantidad de filas recibidas en la carga de la solicitud.

La carga de respuesta JSON debe tener los datos de resultado en el campo “results” para que la función externa la reconozca. El campo de argumentos de la solicitud enviada a la función de Lambda contiene la carga de datos. En el caso de una solicitud por lote, es posible que existan varias filas en la carga de datos. La siguiente función de Lambda itera sobre todas las filas de la carga de datos de la solicitud. También itera de forma individual sobre todos los valores dentro de una sola fila.

exports.handler = async (event) => {
    // The 'arguments' field in the request sent to the Lambda function contains the data payload.
    var t1 = event['arguments'];

    // 'len(t1)' represents the number of rows in the request payload.
    // The number of results in the response payload should be the same as the number of rows received.
    const resp = new Array(t1.length);

    // Iterating over all the rows in the request payload.
    for (const [i, x] of t1.entries())
    {
        var sum = 0;
        // Iterating over all the values in a single row.
        for (const y of x) {
            sum = sum + y;
        }
        resp[i] = sum;
    }
    // The 'results' field should contain the results of the lambda call.
    const response = {
        results: resp
    };
    return JSON.stringify(response);
};

En el siguiente ejemplo, se llama a la función externa con valores literales.

select exfunc_sum(1,2);
exfunc_sum
------------
 3
(1 row)

En el siguiente ejemplo, se crea una tabla denominada t_sum con dos columnas, c1 y c2, del tipo de datos entero y se insertan dos filas de datos. Luego, se llama a la función externa transmitiendo los nombres de las columnas de esta tabla. Las dos filas de la tabla se envían en una solicitud por lote en la carga de la solicitud como una sola invocación de Lambda.

CREATE TABLE t_sum(c1 int, c2 int);
INSERT INTO t_sum VALUES (4,5), (6,7);
SELECT exfunc_sum(c1,c2) FROM t_sum;
 exfunc_sum
---------------
 9
 13
(2 rows)

Ejemplo de UDF escalar de Lambda con el atributo RETRY_TIMEOUT

En la siguiente sección, encontrará un ejemplo de cómo utilizar el atributo RETRY_TIMEOUT en las UDF de Lambda.

Las funciones de AWS Lambda tienen límites de simultaneidad que se pueden establecer para cada función. Para obtener más información acerca de los límites de simultaneidad, consulte Administración de la simultaneidad para una función de Lambda en la Guía para desarrolladores de AWS Lambda y la publicación Administración de la simultaneidad de la función AWS Lambda en el blog de informática de AWS.

Cuando la cantidad de solicitudes que atiende una UDF de Lambda supera los límites de simultaneidad, las solicitudes nuevas reciben el error TooManyRequestsException. La UDF de Lambda intenta solucionar este error de nuevo hasta que la suma de todos los retrasos entre las solicitudes enviadas a la función de Lambda sea igual o superior al valor RETRY_TIMEOUT que estableció. El valor predeterminado de RETRY_TIMEOUT es 20 000 milisegundos.

En el siguiente ejemplo, se utiliza una función de Lambda denominada exfunc_sleep_3. Esta función toma la carga de la solicitud, itera sobre cada fila y convierte la entrada a mayúsculas. Luego, está inactiva durante 3 segundos y devuelve el resultado. El lenguaje utilizado para esta función de Lambda es Python 3.8.

La cantidad de filas en la matriz de resultados es similar a la cantidad de filas recibidas en la carga de la solicitud. La carga de respuesta JSON debe tener los datos de resultado en el campo results para que la función externa la reconozca. El campo de arguments de la solicitud enviada a la función de Lambda contiene la carga de datos. En el caso de una solicitud por lote, es posible que aparezcan varias filas en la carga de datos.

El límite de simultaneidad para esta función se configura específicamente en 1 en simultaneidad reservada para demostrar el uso del atributo RETRY_TIMEOUT. Cuando el atributo se configura en 1, la función de Lambda solo puede atender una solicitud a la vez.

import json
import time
def lambda_handler(event, context):
    t1 = event['arguments']
    # 'len(t1)' represents the number of rows in the request payload.
    # The number of results in the response payload should be the same as the number of rows received.
    resp = [None]*len(t1)

    # Iterating over all rows in the request payload.
    for i, x in enumerate(t1):
        # Iterating over all the values in a single row.
        for j, y in enumerate(x):
            resp[i] = y.upper()

    time.sleep(3)
    ret = dict()
    ret['results'] = resp
    ret_json = json.dumps(ret)
    return ret_json

A continuación, se incluyen dos ejemplos adicionales que ilustran el atributo RETRY_TIMEOUT. Cada ejemplo invoca una sola UDF de Lambda. Cuando invocan la UDF de Lambda, cada ejemplo ejecuta la misma consulta SQL para invocar la UDF de Lambda desde dos sesiones de base de datos simultáneas. Cuando la primera consulta que invoca la UDF de Lambda es atendida por la UDF, la segunda consulta recibe el error TooManyRequestsException. Este resultado se produce porque se configura de forma específica la simultaneidad reservada en 1 en la UDF. Para obtener información sobre cómo establecer la simultaneidad reservada para las funciones de Lambda, consulte Configuración de la simultaneidad reservada.

A continuación, el primer ejemplo configura el atributo RETRY_TIMEOUT para la UDF de Lambda en 0 milisegundos. Si la solicitud de Lambda recibe alguna excepción de la función de Lambda, Amazon Redshift no realiza ningún reintento. Este resultado se produce porque el atributo RETRY_TIMEOUT se configura en 0.

CREATE OR REPLACE EXTERNAL FUNCTION exfunc_upper(varchar)
RETURNS varchar
VOLATILE
LAMBDA 'exfunc_sleep_3'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test'
RETRY_TIMEOUT 0;

Con RETRY_TIMEOUT configurado en 0, puede ejecutar las siguientes dos consultas desde sesiones de base de datos independientes para ver resultados diferentes.

La primera consulta SQL que utiliza la UDF de Lambda se ejecuta correctamente.

select exfunc_upper('Varchar');
 exfunc_upper
 --------------
 VARCHAR
(1 row)

La segunda consulta, que se ejecuta desde una sesión de base de datos independiente al mismo tiempo, recibe el error TooManyRequestsException.

select exfunc_upper('Varchar');
ERROR:  Rate Exceeded.; Exception: TooManyRequestsException; ShouldRetry: 1
DETAIL:
-----------------------------------------------
error:  Rate Exceeded.; Exception: TooManyRequestsException; ShouldRetry: 1
code:      32103
context:query:     0
location:  exfunc_client.cpp:102
process:   padbmaster [pid=26384]
-----------------------------------------------

A continuación, el segundo ejemplo configura el atributo RETRY_TIMEOUT para la UDF de Lambda en 3000 milisegundos. Incluso si la segunda consulta se ejecuta de forma simultánea, la UDF de Lambda reintenta la ejecución hasta que el retraso total sea de 3000 milisegundos. Por lo tanto, ambas consultas se ejecutan correctamente.

CREATE OR REPLACE EXTERNAL FUNCTION exfunc_upper(varchar)
RETURNS varchar
VOLATILE
LAMBDA 'exfunc_sleep_3'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test'
RETRY_TIMEOUT 3000;

Con RETRY_TIMEOUT configurado en 3000, puede ejecutar las siguientes dos consultas desde sesiones de base de datos independientes para ver los mismos resultados.

La primera consulta SQL que ejecuta la UDF de Lambda se ejecuta correctamente.

select exfunc_upper('Varchar');
 exfunc_upper
 --------------
 VARCHAR
(1 row)

La segunda consulta se ejecuta de forma simultánea, y la UDF de Lambda reintenta la ejecución hasta que el retraso total sea de 3000 milisegundos.

select exfunc_upper('Varchar');
 exfunc_upper
--------------
 VARCHAR
(1 row)

Ejemplo de UDF escalar de Lambda con una función Python de Lambda

En el siguiente ejemplo, se crea una función externa denominada exfunc_multiplication que multiplica números y devuelve un número entero. Este ejemplo incorpora los campos de éxito y error_msg en la respuesta de Lambda. El campo de éxito se establece como false cuando hay un desbordamiento de valores enteros en el resultado de la multiplicación y el mensaje error_msg se establece como Integer multiplication overflow. La función exfunc_multiplication toma tres valores enteros como argumentos de entrada y devuelve la suma como un valor de salida entero.

El nombre de la función de Lambda que se llama es lambda_multiplication. El lenguaje utilizado para esta función de Lambda es Python 3.8. Asegúrese de especificar el rol de IAM.

CREATE EXTERNAL FUNCTION exfunc_multiplication(int, int, int)
RETURNS INT
VOLATILE
LAMBDA 'lambda_multiplication'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test'; 

La función de Lambda toma la carga de solicitudes e itera sobre cada fila. Todos los valores de una sola fila se multiplican para calcular el resultado de esa fila, que se guarda en la lista de respuestas. En este ejemplo, se utiliza un valor booleano de éxito establecido como true de manera predeterminada. Si el resultado de la multiplicación de una fila tiene un desbordamiento de valores enteros, el valor de éxito se establece como false. Por lo tanto, se interrumpe el ciclo de iteraciones.

Durante la creación de la carga de respuesta, si el valor de éxito es false, la siguiente función de Lambda agrega el campo error_msg a la carga. También establece el mensaje de error en Integer multiplication overflow. Si el valor de éxito es true, los datos de resultado se agregan en el campo de resultados. La cantidad de filas en la matriz de resultados, si hay, es similar a la cantidad de filas recibidas en la carga de la solicitud.

El campo de argumentos de la solicitud enviada a la función de Lambda contiene la carga de datos. En el caso de una solicitud por lote, es posible que existan varias filas en la carga de datos. La siguiente función de Lambda itera sobre todas las filas de la carga de datos de la solicitud e itera de manera individual sobre todos los valores dentro de una sola fila.

import json
def lambda_handler(event, context):
    t1 = event['arguments']
    # 'len(t1)' represents the number of rows in the request payload.
    # The number of results in the response payload should be the same as the number of rows received.
    resp = [None]*len(t1)

    # By default success is set to 'True'.
    success = True
    # Iterating over all rows in the request payload.
    for i, x in enumerate(t1):
        mul = 1
        # Iterating over all the values in a single row.
        for j, y in enumerate(x):
            mul = mul*y

        # Check integer overflow.
        if (mul >= 9223372036854775807 or mul <= -9223372036854775808):
            success = False
            break
        else:
            resp[i] = mul
    ret = dict()
    ret['success'] = success
    if not success:
        ret['error_msg'] = "Integer multiplication overflow"
    else:
        ret['results'] = resp
    ret_json = json.dumps(ret)

    return ret_json

En el siguiente ejemplo, se llama a la función externa con valores literales.

SELECT exfunc_multiplication(8, 9, 2);
  exfunc_multiplication
---------------------------
          144
(1 row)

En el siguiente ejemplo, se crea una tabla denominada t_multi con tres columnas, c1, c2 y c3, del tipo de datos entero. Se llama a la función externa transmitiendo los nombres de las columnas de esta tabla. Los datos se insertan de tal manera que provocan un desbordamiento de valores enteros para mostrar cómo se propaga el error.

CREATE TABLE t_multi (c1 int, c2 int, c3 int);
INSERT INTO t_multi VALUES (2147483647, 2147483647, 4);
SELECT exfunc_multiplication(c1, c2, c3) FROM t_multi;
DETAIL:
  -----------------------------------------------
  error:  Integer multiplication overflow
  code:      32004context:
  context:
  query:     38
  location:  exfunc_data.cpp:276
  process:   query2_16_38 [pid=30494]
  -----------------------------------------------