创建标量 Lambda UDF

Amazon Redshift 可以将 Amazon Lambda 中定义的自定义函数作为 SQL 查询的一部分。您可以使用 Lambda 支持的任何编程语言编写标量 Lambda UDF，如 Java、Go、PowerShell、Node.js、C#、Python 和 Ruby。或者您可以使用自定义运行时。

Lambda UDF 在 Lambda 中定义和管理，您可以控制在 Amazon Redshift 中调用这些 UDF 的访问权限。您可以在同一查询中调用多个 Lambda 函数，也可以多次调用相同的函数。

在支持标量函数的 SQL 语句的任何子句中使用 Lambda UDF。您还可以在任何 SQL 语句（如 SELECT、UPDATE、INSERT 或 DELETE）中使用 Lambda UDF。

注意

使用 Lambda UDF 可能会产生来自 Lambda 服务的额外费用。是否这样做取决于 Lambda 请求的数量（UDF 调用）和 Lambda 程序执行的总持续时间等因素。但是，在 Amazon Redshift 中使用 Lambda UDF 不需要支付额外费用。有关 Amazon Lambda 定价的信息，请参阅 Amazon Lambda 定价。

Lambda 请求的数量取决于使用 Lambda UDF 的特定 SQL 语句子句。例如，假设此函数用于 WHERE 子句，如下所示。

SELECT a, b FROM t1 WHERE lambda_multiply(a, b) = 64; SELECT a, b FROM t1 WHERE a*b = lambda_multiply(2, 32)

在这种情况下，Amazon Redshift 为每个语句调用第一个 SELECT 语句，并仅调用第二个 SELECT 语句一次。

但是，在查询的投影部分中使用 UDF 可能只会为结果集中的每个限定行或聚合行调用一次 Lambda 函数。

注册 Lambda UDF

CREATE EXTERNAL FUNCTION 命令创建以下参数：

（可选）具有数据类型的参数列表。
一个返回数据类型。
由 Amazon Redshift 调用的外部函数的一个函数名称。
Amazon Redshift 集群有权代入并调用 Lambda 的一个 IAM 角色。
Lambda UDF 调用的一个 Lambda 函数名称。

有关 CREATE EXTERNAL FUNCTION 的更多信息，请参阅CREATE EXTERNAL FUNCTION。

此函数的输入和返回数据类型可以是任何标准 Amazon Redshift 数据类型。

Amazon Redshift 确保外部函数可以发送和接收批量参数和结果。

管理 Lambda UDF 安全性和权限

要创建 Lambda UDF，请确保您具有在 LANGUAGE EXFUNC 上使用的权限。您必须将 USAGE ON LANGUAGE EXFUNC 明确授予给特定用户、组或公众，或撤销其 USAGE ON LANGUAGE EXFUNC。

以下示例将 EXFUNC 的使用权限授予 PUBLIC。


grant usage on language exfunc to PUBLIC;

以下示例将从 PUBLIC 撤销对 exfunc 的使用权限，然后向用户组 lambda_udf_devs 授予使用权限。


revoke usage on language exfunc from PUBLIC;
grant usage on language exfunc to group lambda_udf_devs;

要运行 Lambda UDF，请确保您对每个调用的函数都拥有权限。预设情况下，向 PUBLIC 授予运行新 Lambda UDF 的权限。要限制使用，请从 PUBLIC 撤销该函数的此权限。然后向特定用户或组授予权限。

以下示例从 PUBLIC 撤销对函数 exfunc_sum 的执行权限。然后它会向用户组 lambda_udf_devs 授予使用权限。


revoke execute on function exfunc_sum(int, int) from PUBLIC;
grant execute on function exfunc_sum(int, int) to group lambda_udf_devs;

默认情况下，超级用户拥有全部权限。

有关授予和撤消权限的更多信息，请参阅GRANT和REVOKE。

配置 Lambda UDF 的授权参数

CREATE EXTERNAL FUNCTION 命令需要授权才能在 Amazon Lambda 中调用 Lambda 函数。要启动授权，请在您运行 CREATE EXTERNAL FUNCTION 命令时指定 Amazon Identity and Access Management (IAM) 角色。有关 IAM 角色的更多信息，请参阅《IAM 用户指南》中的 IAM 角色。

如果现有 IAM 角色具有调用附加到集群的 Lambda 函数的权限，则您可以在命令的 IAM_ROLE 参数中替代您的角色 Amazon Resource Name (ARN)。以下部分介绍了在 CREATE EXTERNAL FUNCTION 命令中使用 IAM 角色的步骤。

为 Lambda 创建 IAM 角色

IAM 角色需要调用 Lambda 函数的权限。创建 IAM 角色时，请通过以下方式之一提供权限：

创建 IAM 角色时将 AWSLambdaRole 策略附加到 Attach permissions policy（附加权限策略）页面上。AWSLambdaRole 策略授予调用 Lambda 函数的权限，这是最低要求。有关更多信息和其他策略，请参阅 Amazon Lambda 开发人员指南中的Amazon Lambda 的基于身份的 IAM 策略。
创建您自己的自定义策略以附加到您的 IAM 角色，该角色具有对所有资源或具有该函数 ARN 的特定 Lambda 函数的 lambda:InvokeFunction 权限。有关如何创建策略的更多信息，请参阅 IAM 用户指南中的创建 IAM 策略。

以下示例策略允许在特定 Lambda 函数上调用 Lambda。
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Invoke",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction"
            ],
            "Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function"
        }
    ]
}
```
有关 Lambda 函数的资源的更多信息，请参阅 IAM API 参考中的 Lambda 操作的资源和条件。

创建具有所需权限的自定义策略后，您可以在创建 IAM 角色的同时在 Attach permissions policy（附加权限策略）页面上将策略附加到该 IAM 角色。

有关创建 IAM 角色的步骤，请参阅《Amazon Redshift 管理指南》中的授权 Amazon Redshift 代表您访问其他 Amazon 服务。

如果您不想创建新的 IAM 角色，您可以将之前提到的权限添加到现有 IAM 角色。

将 IAM 角色与集群关联

将 IAM 角色附加到您的集群。通过使用 Amazon Redshift 管理控制台、CLI 或 API，您可将角色添加到集群或查看与集群关联的角色。有关更多信息，请参阅《Amazon Redshift 管理指南》中的将 IAM 角色与集群关联。

在命令中包含 IAM 角色

在 CREATE EXTERNAL FUNCTION 命令中包含 IAM 角色 ARN。当您创建 IAM 角色时，IAM 将返回该角色的 Amazon Resource Name (ARN)。要指定 IAM 角色，请利用 IAM_ROLE 参数提供角色 ARN。以下显示 IAM_ROLE 参数的语法。


IAM_ROLE 'arn:aws:iam::aws-account-id:role/role-name'

要调用位于同一区域内的其他账户中的 Lambda 函数，请参阅在 Amazon Redshift 中串联 IAM 角色。

在 Amazon Redshift 和 Amazon Lambda 之间使用 JSON 界面

Amazon Redshift 对于 Amazon Redshift 通信的所有 Lambda 函数使用通用界面。

下表显示了预计将用于 JSON 负载的指定 Lambda 函数的输入字段列表。

字段名称	描述	值范围
request_id	通用唯一标识符 (UUID)，用于唯一标识每个调用请求。	有效的 UUID。
集群	集群的完整 Amazon Resource Name (ARN)。	有效的集群 ARN。
user	进行调用的用户的名称。	有效用户名。
数据库	正在运行查询的数据库的名称。	有效的数据库名称。
external_function	进行调用的外部函数的完全限定名称。	有效的完全限定函数名称。
query_id	正在进行调用的查询的查询 ID。	有效的查询 ID。
num_records	负载中的参数数量。	值为 1 - 2^64。
arguments	指定格式的数据负载。	数组格式的数据必须是 JSON 数组。如果参数的数量大于 1，则每个元素都是一个数组的记录。通过使用数组，Amazon Redshift 可以保留记录在负载中的顺序。

JSON 数组的顺序决定了批处理的顺序。Lambda 函数必须以迭代方式处理参数并生成确切的记录数量。以下是负载的示例。


{
  "request_id" : "23FF1F97-F28A-44AA-AB67-266ED976BF40",
  "cluster" : "arn:aws:redshift:xxxx",
  "user" : "adminuser",
  "database" : "db1",
  "external_function": "public.foo",
  "query_id" : 5678234,
  "num_records" : 4,
  "arguments" : [
     [ 1, 2 ],
     [ 3, null],
     null,
     [ 4, 6]
   ]
 }

Lambda 函数的返回输出包含以下字段。

字段名称	描述	值范围
success	函数成功或失败的指示。	值为 `"true"` 或者 `"false"`。
error_msg	如果成功值为 `"false"`（如果函数失败），则出现错误消息；否则，此字段将被忽略。	一个有效的消息。
num_records	负载中的记录数。	值为 1 - 2^64。
results	指定格式的调用结果。	不适用

以下是 Lambda 函数输出的示例。


{
  "success": true,   // true indicates the call succeeded
  "error_msg" : "my function isn't working",  // shall only exist when success != true
  "num_records": 4,      // number of records in this payload
  "results" : [
     1,
     4,
     null,
     7
   ]
}

当您通过 SQL 查询调用 Lambda 函数时，Amazon Redshift 会根据以下注意事项确保连接的安全性：

GRANT 和 REVOKE 权限。有关 UDF 安全性和权限的更多信息，请参阅UDF 安全性和权限。
Amazon Redshift 仅向指定的 Lambda 函数提交最小数据集。
Amazon Redshift 只调用具有指定 IAM 角色的指定 Lambda 函数。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

记录错误和警告

UDF 的示例使用案例