外部函数简介¶

外部函数是什么？¶

外部函数 调用在 Snowflake 外部执行的代码。

远程执行的代码称为 远程服务。

发送到远程服务的信息通常通过 代理服务 进行中继。

Snowflake 在 API 集成 中存储与安全性相关的外部函数信息。

下图展示了从客户端程序通过 Snowflake 到远程服务的基本信息流：

下面更详细地介绍了每个关键组件。

外部函数：

外部函数是一种 UDF。与其他 UDFs 不同，外部函数不包含自己的代码；相反，外部函数调用在 Snowflake 外部存储和执行的代码。

在 Snowflake 内部，外部函数存储为数据库对象，其中包含 Snowflake 用于调用远程服务的信息。此类存储信息包含 代理服务 的 URL。代理服务将信息中继到远程服务，以及从远程服务中继信息。此类信息通过 CREATE EXTERNAL FUNCTION 命令指定。

表示外部函数的数据库对象在特定的数据库和架构中创建。您可以使用点表示法来表示完全限定名称，从而调用外部函数。例如：

select my_database.my_schema.my_external_function(col1) from table1;

Copy

远程服务：

远程执行的代码称为远程服务。

远程服务必须像函数一样运行。例如，它必须返回值。

Snowflake 支持 标量 外部函数；远程服务必须正好为收到的每一行返回一行。

要通过 Snowflake External Function 功能调用，远程服务必须执行以下操作：

• 接受 JSON (https://www.json.org) 输入并返回 JSON 输出。（有关 Snowflake 兼容的 HTTP 标头和 JSON 格式化数据的更多信息，请参阅 远程服务输入和输出数据格式。）

• 公开 HTTPS 端点。

例如，远程服务可以通过以下方式实施：

• AWS Lambda 函数。

• Microsoft Azure 函数。

• EC2 实例上运行的 HTTPS 服务器（例如 Node.js）。

代理服务：

Snowflake 不直接调用 远程服务。相反，Snowflake 调用代理服务，将数据中继到远程服务。

代理服务可以对面向远程服务的请求进行身份验证，从而提高安全性。

对于远程服务，代理服务可以支持基于订阅的计费。例如，代理服务可以验证远程服务的调用方是否是付费订阅者。

代理服务还将来自远程服务的响应中继回 Snowflake。

代理服务的示例包括：

• Amazon API Gateway。

• Microsoft Azure API Management 服务。

API 集成：

集成 是一个 Snowflake 对象，在 Snowflake 和第三方服务之间提供接口。API 集成存储在使用代理服务或远程服务时所需的信息，例如安全信息。

API 集成是使用 CREATE API INTEGRATION 命令创建的。

用户可以编写并调用自己的远程服务，也可以调用第三方编写的远程服务。这些远程服务可以使用任何 HTTP 服务器堆栈编写，包括云无服务器计算服务（例如 AWS Lambda）。

从运行 SQL 语句的用户的角度来看，外部函数的行为与任何其他 UDF 类似。外部函数遵循以下规则：

• 外部函数返回一个值。

• 外部函数可以接受参数。

• 外部函数可以在 SQL 语句的任何子句中显示，在其中可以显示其他类型的 UDF。例如：

  select my_external_function_2(column_1, column_2)
      from table_1;
  
  select col1
      from table_1
      where my_external_function_3(col2) < 0;
  
  create view view1 (col1) as
      select my_external_function_5(col1)
          from table9;
  

  Copy

• 外部函数可以属于更复杂的表达式：

  select upper(zipcode_to_city_external_function(zipcode))
    from address_table;
  

  Copy

• 返回值可以是复合值，例如包含 JSON 的 VARIANT。

• 外部函数可以重载；两个不同的函数可以具有相同的名称但不同的签名（输入参数的数量或数据类型不同）。

外部函数的工作原理¶

Snowflake 不直接调用远程服务。相反，Snowflake 通过云提供商的本地 HTTPS 代理服务（例如 AWS 上的 API Gateway）调用远程服务。

外部函数的主要调用步骤如下：

1. 用户的客户端程序向 Snowflake 传递用于调用外部函数的 SQL 语句。

2. 在执行查询期间评估外部函数时，Snowflake 会读取外部函数定义和相应的 API 集成信息。

   • 来自外部函数定义的信息包括：

     • 代理服务的 URL。

     • 相应 API 集成的名称。

   • 来自 API 集成的信息包括：

     • 要使用的代理服务资源。资源包含有关远程服务的信息，例如相应服务的位置。

     • 相应代理服务资源的身份验证信息。

   然后，Snowflake 编写 HTTP POST 命令，包括：

   • 要处理的数据。此数据采用 JSON 格式。

   • HTTP 标头信息。（有关详细信息，请参阅 CREATE EXTERNAL FUNCTION。）

   • 来自 API 集成的身份验证信息。

   然后，Snowflake 向代理服务发送 POST 请求。

3. 代理服务接收 POST 请求，然后处理请求并将其转发给实际的远程服务。您可以大致将代理服务和资源视为用于调用远程服务的“中继函数”。

4. 远程服务处理数据并返回结果，结果通过链传回原始 SQL 语句。

5. 如果远程服务使用 HTTP 代码响应信号 异步 处理，则 Snowflake 会发送一个或多个 HTTP GET 请求，从远程服务中检索结果。只要 Snowflake 收到响应代码以继续请求，Snowflake 就会继续发送 GET 请求，直到外部函数超时或返回错误。

通常，当查询有大量行要发送到远程服务时，这些行会分成多个批次。批处理通常可以提高并行度并加快查询。在某些情况下，批处理可以减少远程服务的重载。

远程服务为收到的每个批次返回 1 批行。对于标量外部函数，返回批次中的行数等于接收批次中的行数。

每个批次都有唯一的批次 ID，包含在从 Snowflake 发送到远程服务的每个请求中。

重试操作（例如因超时而重试）通常在批处理级别完成。

外部函数的优势¶

相较于其他 UDFs，外部函数具有以下优势：

• 远程服务的代码可以用其他 UDFs 无法使用的语言编写，包括：

  • Go

  • C#

• 远程服务可以使用内部 UDFs 无法访问的函数和库。例如，远程服务可以与商用第三方库（例如机器学习评分库）进行交互。

• 开发者可以编写远程服务，这些服务既可以从 Snowflake 调用，也可以从使用相同接口编写的其他软件调用。

外部函数的限制¶

外部函数具有以下限制，这些限制可以大致分为创建时间限制和执行时间限制。

外部函数使用计费¶

使用外部函数会产生与以下内容相关的正常成本：

• Snowflake 仓库使用。

• 数据传输。

此外，您可能需要支付间接或第三方费用，包括远程服务提供商收取的费用。费用可能因供应商而异。

支持的平台¶