Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

CREATE EXTERNAL FUNCTION

Crea una funzione scalare definita dall'utente (UDF) basata su Amazon AWS Lambda Redshift. Per ulteriori informazioni sulle funzioni Lambda definite dall'utente, consultare Lambda scalare UDFs.

Privilegi richiesti

Di seguito sono riportati i privilegi necessari per CREATE EXTERNAL FUNCTION:

Sintassi

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::<Account AWS-id>:role/<role-name>’
RETRY_TIMEOUT milliseconds
MAX_BATCH_ROWS count
MAX_BATCH_SIZE size [ KB | MB ];

Parametri

Note per l'utilizzo

Considera quanto segue quando crei UDFs Lambda:

Esempi

Di seguito sono riportati alcuni esempi di utilizzo delle funzioni scalari definite dall'utente Lambda (). UDFs

Esempio di funzione Lambda definita dall'utente scalare che utilizza una funzione Lambda Node.js

L'esempio seguente crea una funzione esterna denominata exfunc_sum che utilizza due numeri interi come argomenti di input. Questa funzione restituisce la somma come output intero. Il nome della funzione Lambda da chiamare è lambda_sum. La lingua utilizzata per questa funzione Lambda è Node.js 12.x. Assicurarsi di specificare il ruolo IAM. L'esempio utilizza 'arn:aws:iam::123456789012:user/johndoe' come ruolo 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 funzione Lambda accetta il payload della richiesta ed esegue l'iterazione su ogni riga. Tutti i valori di una singola riga vengono aggiunti per calcolare la somma per quella riga, che viene salvata nell'array di risposte. Il numero di righe nell'array dei risultati è simile al numero di righe ricevute nel payload della richiesta.

Perché sia riconosciuto dalla funzione esterna, il payload della risposta JSON deve avere i dati di risultato nel campo 'results'. Il campo argomenti nella richiesta inviata alla funzione Lambda contiene il payload dei dati. In caso di richiesta batch, è possibile avere più righe nel payload dei dati. La seguente funzione Lambda itera su tutte le righe nel payload dei dati della richiesta. Inoltre, itera individualmente su tutti i valori all'interno di una singola riga.

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);
};

Nell'esempio seguente viene chiamata la funzione esterna con valori letterali.

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

Nell'esempio seguente viene creata una tabella denominata t_sum con due colonne, c1 e c2, del tipo di dati intero e vengono inserite due righe di dati. Quindi la funzione esterna viene chiamata passando i nomi delle colonne di questa tabella. Le due righe della tabella vengono inviate in una richiesta batch nel payload della richiesta come un singolo richiamo 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)

Esempio di funzione Lambda definita dall'utente scalare che utilizza l'attributo RETRY_TIMEOUT

Nella sezione seguente, puoi trovare un esempio di come utilizzare l'attributo RETRY_TIMEOUT in Lambda. UDFs

AWS Lambda le funzioni hanno limiti di concorrenza che è possibile impostare per ciascuna funzione. Per ulteriori informazioni sui limiti di concorrenza, consulta Gestire la concorrenza per una funzione Lambda nella Guida per gli AWS Lambda sviluppatori e il post Managing AWS Lambda Function Concurrency sul blog di Compute. AWS

Quando il numero di richieste servite da una funzione Lambda definita dall'utente supera i limiti di simultaneità, le nuove richieste ricevono l'errore TooManyRequestsException. La funzione Lambda definita dall'utente riprova su questo errore fino a quando la somma di tutti i ritardi tra le richieste inviate alla funzione Lambda è uguale o superiore al valore RETRY_TIMEOUT impostato. Il valore di default di RETRY_TIMEOUT è 20.000 millisecondi.

L'esempio seguente crea una funzione Lambda denominata exfunc_sleep_3. Questa funzione prende in carico il payload della richiesta, itera su ogni riga e converte l'input in maiuscolo. Quindi si interrompe per 3 secondi e restituisce il risultato. Il linguaggio utilizzato per questa funzione Lambda è Python 3.8.

Il numero di righe nell'array dei risultati è simile al numero di righe ricevute nel payload della richiesta. Perché sia riconosciuto dalla funzione esterna, il payload della risposta JSON deve avere i dati di risultato nel campo results. Il campo arguments nella richiesta inviata alla funzione Lambda contiene il payload dei dati. In caso di richiesta batch, è possibile avere più righe nel payload dei dati.

Il limite di simultaneità per questa funzione è impostato specificatamente su 1 nella simultaneità riservata per dimostrare l'utilizzo dell'attributo RETRY_TIMEOUT. Quando l'attributo è impostato su 1, la funzione Lambda può servire solo una richiesta alla volta.

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

Di seguito, due esempi aggiuntivi illustrano l'attributo RETRY_TIMEOUT. Ognuno di essi richiama una singola funzione Lambda definita dall'utente. Durante il richiamo della funzione Lambda, ogni esempio esegue la stessa query SQL per richiamare la funzione Lambda da due sessioni di database simultanee contemporaneamente. Quando la prima query che richiama la funzione Lambda definita dall'utente viene servita dalla funzione, la seconda query riceve l'errore TooManyRequestsException. Questo risultato si verifica perché si imposta in modo specifico la simultaneità riservata nella funzione definita dall'utente su 1. Per informazioni su come configurare la simultaneità riservata per le funzioni Lambda, consultare Configurazione della simultaneità riservata.

Nel primo esempio che segue, l'attributo RETRY_TIMEOUT per la funzione Lambda definita dall'utente viene impostato su 0 millisecondi. Se la richiesta Lambda riceve una qualsiasi eccezione dalla funzione Lambda, Amazon Redshift non esegue alcun nuovo tentativo. Questo risultato si verifica perché l'attributo RETRY_TIMEOUT è impostato su 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 impostato su 0, è possibile eseguire le seguenti due query da sessioni di database separate e visualizzare risultati diversi.

La prima query SQL che utilizza la funzione Lambda definita dall'utente viene eseguita correttamente.

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

La seconda query, eseguita contemporaneamente da una sessione di database separata, riceve l'errore 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]
-----------------------------------------------

Nel primo esempio che segue, l'attributo RETRY_TIMEOUT per la funzione Lambda definita dall'utente viene impostato su 3.000 millisecondi. Anche se la seconda query viene eseguita contemporaneamente, la funzione Lambda definita dall'utente tenta di nuovo fino a quando il ritardo totale è di 3.000 millisecondi. Pertanto, entrambe le query vengono eseguite correttamente.

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 impostato su 3.000 millisecondi, è possibile eseguire le seguenti due query da sessioni di database separate e visualizzare gli stessi risultati.

La prima query SQL che esegue la funzione Lambda definita dall'utente viene eseguita correttamente.

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

La seconda query viene eseguita contemporaneamente e la funzione Lambda definita dall'utente prova di nuovo fino a quando il ritardo totale è di 3.000 millisecondi.

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

Esempio di funzione Lambda definita dall'utente scalare che utilizza una funzione Lambda Python

L'esempio seguente crea una funzione esterna denominata exfunc_multiplication e che moltiplica i numeri e restituisce un numero intero. Questo esempio incorpora il successo e i campi error_msg nella risposta Lambda. Il campo di successo è impostato su false quando c'è un overflow di numeri interi nel risultato della moltiplicazione e il messaggio error_msg è impostato su Integer multiplication overflow. La funzione exfunc_multiplication accetta tre numeri interi come argomenti di input e restituisce la somma come output intero.

Il nome della funzione Lambda richiamata è lambda_multiplication. Il linguaggio utilizzato per questa funzione Lambda è Python 3.8. Assicurarsi di specificare il ruolo 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 funzione Lambda accetta il payload della richiesta ed esegue l'iterazione su ogni riga. Tutti i valori di una singola riga vengono moltiplicati per calcolare il risultato di tale riga, che viene salvato nell'elenco delle risposte. In questo esempio viene utilizzato un valore di successo booleano impostato su true per impostazione predefinita. Se il risultato della moltiplicazione per una riga ha un overflow intero, il valore di successo è impostato su false. Quindi il ciclo di iterazione si interrompe.

Durante la creazione del payload di risposta, se il valore di successo è false, la seguente funzione Lambda aggiunge il campo error_msg nel payload. Imposta anche il messaggio di errore su Integer multiplication overflow. Se il valore di successo è true, i dati dei risultati vengono aggiunti nel campo dei risultati. Il numero di righe nell'array dei risultati, se presente, è simile al numero di righe ricevute nel payload della richiesta.

Il campo argomenti nella richiesta inviata alla funzione Lambda contiene il payload dei dati. In caso di richiesta batch, è possibile avere più righe nel payload dei dati. La seguente funzione Lambda itera su tutte le righe nel payload dei dati richiesta e itera individualmente su tutti i valori all'interno di una singola riga.

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

Nell'esempio seguente viene chiamata la funzione esterna con valori letterali.

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

Nell'esempio seguente viene creata una tabella denominata t_multi con tre colonne, c1, c2 e c3, del tipo di dati intero. La funzione esterna viene chiamata passando i nomi delle colonne di questa tabella. I dati vengono inseriti in modo tale da causare l'overflow di interi per mostrare come l'errore viene propagato.

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