本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CREATE EXTERNAL FUNCTION

建立以 Amazon Redshift AWS Lambda 為基礎的純量使用者定義函數 (UDF)。如需 Lambda 使用者定義函數的相關資訊，請參閱 創建一個標量 Lambda UDF。

所需權限

以下是所需的權限 CREATE EXTERNALFUNCTION：

語法

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

參數

使用須知

建立 Lambda 時，請考量下列事項UDFs：

範例

以下是使用標量 Lambda 用戶定義函數的例子（UDFs）。

使用 Node.js Lambda 函數的標量 Lambda UDF 示例

下列範例會建立名為 exfunc_sum 的外部函數，該函數會接受兩個整數做為輸入引數。該函數會傳回作為整數輸出的總和。要呼叫的 Lambda 函數名稱為 lambda_sum。用於此 Lambda 函數的語言是 Node.js 12.x。請務必指定IAM角色。此範例使用'arn:aws:iam::123456789012:user/johndoe'作為IAM角色。

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

Lambda 函數會接受請求承載並逐一查看每一列。單列中的所有值都會加入以計算該列的總和，而這會保存在回應陣列中。結果陣列中的資料列數會與請求承載中接收的資料列數相似。

JSON響應有效負載必須在「結果」字段中具有結果數據，以便由外部函數識別。在傳送至 Lambda 函數的請求中，引數欄位會包含資料承載。在批次處理請求的情況下，資料承載中可以有多個資料列。下列 Lambda 函數會逐一查看請求資料承載中的所有資料列。也會單獨逐一查看單一資料列中的所有值。

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

下列範例會呼叫具有常值的外部函數。

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

下列範例會建立名為 t_sum 的資料表，其中包含整數資料類型的兩個資料欄 c1 和 c2，並插入兩列資料。然後透過傳遞此資料表的資料欄名稱來呼叫外部函數。這兩個資料表資料列會在請求承載中以批次請求的形式傳送，以做為單一 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)

使用 RETRY _ TIMEOUT 屬性的標量 Lambda UDF 示例

在下一節中，您可以找到如何在 Lambda 中使用 RETRY _ TIMEOUT 屬性的範例UDFs。

AWS Lambda 函數具有您可以為每個函數設置的並發限制。如需並行限制的詳細資訊，請參閱AWS Lambda 開發人員指南中的管理 Lambda 函數的並行性，以及運算部落格上的管理 AWS Lambda 函數並行文章。 AWS

當 Lambda 提供的要求數目UDF超過並行限制時，新要求會收到TooManyRequestsException錯誤訊息。Lambda UDF 會重試此錯誤，直到傳送至 Lambda 函數的要求之間的所有延遲總和等於或超過您設定的 RETRY _ TIMEOUT 值為止。預設 RETRY _ TIMEOUT 值為 20,000 毫秒。

下列範例會使用名為 exfunc_sleep_3 的 Lambda 函數。該函數會接受請求承載、逐一查看每一個資料列，並將輸入轉換為大寫。然後休眠 3 秒鐘後傳回結果。用於此 Lambda 函數的語言是 Python 3.8。

結果陣列中的資料列數會與請求承載中接收的資料列數相似。JSON回應裝載必須在results欄位中包含結果資料，才能由外部函數辨識。在傳送至 Lambda 函數的請求中，arguments 欄位會包含資料承載。在批次處理請求的情況下，資料承載中可以有多個資料列。

此函數的並發限制專門設置為 1 在保留並發，以示範使用 RETRY _ TIMEOUT 屬性。當屬性設定為 1 時，Lambda 函數一次只能處理一個請求。

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

下面，另外兩個例子說明了 RETRY _ TIMEOUT 屬性。他們每個人都叫用一個 Lambda UDF。呼叫 Lambda 時UDF，每個範例都會執行相同的SQL查詢，同時UDF從兩個並行資料庫工作階段叫用 Lambda。當第一個叫用 Lambda 的查詢UDF由提供時UDF，第二個查詢會收到TooManyRequestsException錯誤。之所以發生此結果，是因為您特別將中的保留並行設定UDF為 1。如需如何為 Lambda 函數設定保留並行的相關資訊，請參閱設定保留並行。

接下來的第一個範例會UDF將 Lambda 的 RETRY _ TIMEOUT 屬性設定為 0 毫秒。如果 Lambda 請求從 Lambda 函數收到任何例外狀況，Amazon Redshift 不會進行任何重試。發生這個結果是因為 RETRY _ TIMEOUT 屬性設定為 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;

將 RETRY _ TIMEOUT 設定為 0 時，您可以從不同的資料庫工作階段執行下列兩個查詢，以查看不同的結果。

第一個使用 Lambda 的SQL查詢成功UDF執行。

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

同時從不同資料庫工作階段執行的第二個查詢會收到 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]
-----------------------------------------------

接下來的第二個範例會UDF將 Lambda 的 RETRY _ TIMEOUT 屬性設定為 3,000 毫秒。即使第二個查詢同時執行，Lambda 仍UDF會重試，直到總延遲為 3,000 毫秒為止。因此，兩個查詢都會成功執行。

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;

將 RETRY _ TIMEOUT 設定為 3,000 毫秒時，您可以從不同的資料庫工作階段執行下列兩個查詢，以查看相同的結果。

第一個執行 Lambda 的SQL查詢UDF會成功執行。

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

第二個查詢會同時執行，Lambda UDF 會重試，直到總延遲為 3,000 毫秒為止。

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

使用 Python Lambda 函數的標量 Lambda UDF 示例

下列範例會建立名為 exfunc_multiplication 且會乘以數字並傳回整數的外部函數。此範例包含 Lambda 回應中的成功和 error_msg 欄位。當乘法結果中有整數溢位，且 error_msg 訊息設定為 Integer multiplication overflow 時，成功欄位會設定為 false。exfunc_multiplication 函數採用三個整數作為輸入參數，並傳回總和作為整數輸出。

要呼叫的 Lambda 函數名稱為 lambda_multiplication。用於此 Lambda 函數的語言是 Python 3.8。請務必指定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'; 

Lambda 函數會接受請求承載並逐一查看每一列。單列中的所有值都會相乘以計算該列的結果，而這會保存在回應清單中。此範例使用預設為 true 的布林成功值。如果資料列的乘法結果有整數溢位，則成功值會設定為 false。然後迭代循環會中斷。

建立回應承載時，如果成功值為 false，則下列 Lambda 函數會在承載中新增 error_msg 欄位。也會將錯誤訊息設定為 Integer multiplication overflow。如果成功值為 true，則結果資料會新增到結果欄位中。結果陣列中的資料列數 (如果有的話) 會與請求承載中接收的資料列數相似。

在傳送至 Lambda 函數的請求中，引數欄位會包含資料承載。在批次處理請求的情況下，資料承載中可以有多個資料列。下列 Lambda 函數會逐一查看請求資料承載中的所有資料列，並個別逐一查看單一資料列中的所有值。

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

下列範例會呼叫具有常值的外部函數。

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

下列範例會建立名為 t_multi 的資料表，其中包含整數資料類型的三個資料欄 c1、c2 和 c3。外部函數會透過傳遞此資料表的資料欄名稱來呼叫。資料會以這種方式插入，進而導致整數溢位，以顯示錯誤的傳播方式。

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