CREATE FUNCTION (Snowpark Container Services)¶

该命令支持以下变体：

CREATE OR ALTER FUNCTION (Snowpark Container Services)：如果服务函数不存在，则创建一个，或者更改现有服务函数。

另请参阅：: 服务函数、CREATE EXTERNAL FUNCTION、DESC FUNCTION、DROP FUNCTION、ALTER FUNCTION、CREATE OR ALTER <对象>

语法¶

CREATE [ OR REPLACE ] FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ MAX_BATCH_RETRIES = <integer> ]
  [ ON_BATCH_FAILURE = { ABORT | RETURN_NULL } ]
  [ BATCH_TIMEOUT_SECS = <integer> ]
  AS '<http_path_to_request_handler>'

Copy

变体语法¶

CREATE OR ALTER FUNCTION (Snowpark Container Services)¶

如果不存在服务函数，则新建一个，或者将现有服务函数转换为语句中定义的服务函数。CREATE OR ALTER FUNCTION (Snowpark Container Services) 语句遵循 CREATE FUNCTION (Snowpark Container Services) 语句的语法规则，并且具有与 ALTER FUNCTION (Snowpark Container Services) 语句相同的限制。

支持的功能更改包括对以下内容的更改：

CONTEXT_HEADERS
SERVICE
ENDPOINT
MAX_BATCH_ROWS
MAX_BATCH_RETRIES
ON_BATCH_FAILURE
BATCH_TIMEOUT_SECS

有关更多信息，请参阅 CREATE OR ALTER FUNCTION (Snowpark Container Services) 使用说明。

CREATE [ OR ALTER ] FUNCTION ...

Copy

必填参数¶

name

指定该函数的标识符 (name) 和任何输入实参。

对于创建函数的架构，标识符不必唯一，因为函数是通过名称和实参类型的组合来标识和解析的。
标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。请参阅标识符要求。

( [ arg_name arg_data_type ] [ , ... ] )

指定服务函数的实参/输入。这些实参应该与服务所期望的实参相对应。

如果没有实参，则包括不带任何实参名称和数据类型的括号。

RETURNS result_data_type

指定函数返回的结果的数据类型。

SERVICE = service_name

指定 Snowpark Container Services 服务的名称。

ENDPOINT = endpoint_name

指定服务规范中定义的端点的名称。

AS http_path_to_request_handler: 指定调用函数时执行的服务代码的 HTTP 路径。

可选参数¶

[ [ NOT ] NULL ]: 指定函数是可以返回 NULL 值，还是只能返回 NON-NULL 值。默认值为 NULL（即，函数可以返回 NULL）。

CALLED ON NULL INPUT 或 . { RETURNS NULL ON NULL INPUT | STRICT }

指定在使用 Null 输入调用时函数的行为。与系统定义的函数（当任何输入为 null 时总是返回 null）相反，函数可以处理 null 输入，即使输入为 null 也返回非 null 值：

CALLED ON NULL INPUT 将始终使用 Null 输入调用函数。这取决于函数是否适当地处理这些值。
如果任何输入为 Null，则 RETURNS NULL ON NULL INPUT （或其同义词 STRICT）将不会调用函数。相反，将始终为该行返回 null 值。请注意，对于非 Null 输入，该函数仍可能返回 Null。

默认：CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

指定在返回结果时函数的行为：

VOLATILE：该函数可能为不同的行返回不同的值，即使是相同的输入也如此（例如，由于非确定性和有状态性）。

IMMUTABLE：该函数假定当使用相同的输入调用该函数时，该函数将始终返回相同的结果。此保证未经检查。为相同输入返回不同值的函数指定 IMMUTABLE，这样会导致未定义的行为。

默认：VOLATILE

MAX_BATCH_ROWS = integer

指定向服务发送数据的批次大小以提高并发性

MAX_BATCH_RETRIES = integer

指定您希望 Snowflake 重试失败批次的次数。

默认值：3

ON_BATCH_FAILURE = { ABORT | RETURN_NULL }

指定 Snowflake 达到处理批次的最大重试次数后函数的行为。

ABORT：服务函数中止执行。任何剩余的行批次都不会被处理。
RETURN_NULL：服务函数为失败批次中的每一行返回 NULL，并继续处理剩余批次。如果您选择此选项，请注意以下注意事项：
- 如果这些批次相互依赖并且一个批次失败，则可能会导致意想不到的结果。
- 如果您的服务可以将 NULL 作为有效响应返回，则无法区分 Snowflake 因批次失败而返回的 NULL 与您的服务返回的 NULL。

默认值：ABORT

BATCH_TIMEOUT_SECS = integer

指定处理单批次行的最大持续时间，包括重试（和轮询异步函数请求），在此之后 Snowflake 应终止批次请求。

可接受的值：大于 0 且小于或等于 604800 秒（7 天）。

默认值：604800 秒（7 天）

COMMENT = 'string_literal'

指定函数的注释，该注释在 SHOW FUNCTIONS 和 SHOW USER FUNCTIONS 输出的 DESCRIPTION 列中显示。

默认：user-defined function

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )

这会将 Snowflake 上下文函数结果绑定到 HTTP 标头。（有关 Snowflake 上下文函数的更多信息，请参阅：上下文函数。）

上下文标头并非支持所有上下文函数。支持以下内容：

CURRENT_ACCOUNT()
CURRENT_CLIENT()
CURRENT_DATABASE()
CURRENT_DATE()
CURRENT_IP_ADDRESS()
CURRENT_REGION()
CURRENT_ROLE()
CURRENT_SCHEMA()
CURRENT_SCHEMAS()
CURRENT_SESSION()
CURRENT_STATEMENT()
CURRENT_TIME()
CURRENT_TIMESTAMP()
CURRENT_TRANSACTION()
CURRENT_USER()
CURRENT_VERSION()
CURRENT_WAREHOUSE()
LAST_QUERY_ID()
LAST_TRANSACTION()
LOCALTIME()
LOCALTIMESTAMP()

当函数名在 CONTEXT_HEADERS 子句中列出时，函数名不应加引号。

Snowflake 在写入 HTTP 请求之前会将 sf-context 追加到标头。

示例：

CONTEXT_HEADERS = (current_timestamp)

Copy

在此示例中，Snowflake 将标头 sf-context-current-timestamp 写入 HTTP 请求。

上下文函数可以生成 HTTP 标头值中非法的字符，包括（但不限于）以下字符：

换行符
Ä
Î
ß
ë
¬
±
©
®

Snowflake 将每个包含一个或多个非法字符的序列替换为一个空格字符。（替换是按序列，而不是按字符。）

例如，假设上下文函数 CURRENT_STATEMENT() 返回以下内容：

select
  /*ÄÎßë¬±©®*/
  my_service_function(1);

Copy

sf-context-current-statement 中发送的值如下所示：

select /* */ my_service_function(1);

Copy

为确保您的服务代码可以通过上下文函数访问原始结果（包含非法字符），即使非法字符已替换，Snowflake 也会发送一个二进制上下文标头，其中包含使用 base64 编码的上下文函数结果。

在上面的示例中，在 base64 编码的标头中发送的值是以下调用的结果：

base64_encode('select\n/ÄÎßë¬±©®/\nmy_service_function(1)')

Copy

如果需要，远程服务负责解码 base64 值。

每个此类 base64 标头都根据以下惯例命名：

sf-context-<context-function>-base64

Copy

在上面的示例中，标头的名称如下：

sf-context-current-statement-base64

Copy

如果没有发送上下文标头，则不会发送 base64 上下文标头。

如果发送到服务函数的行拆分为多个批次，则所有批次都包含相同的上下文标头和相同的二进制上下文标头。

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：

权限	对象	备注
CREATE FUNCTION	架构
USAGE	服务端点	服务规范中定义的服务角色将获得服务端点的使用权限。然后，您为服务角色授予创建服务函数的角色。

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

一般使用说明¶

CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

CREATE OR ALTER FUNCTION (Snowpark Container Services) 使用说明¶

不支持以下更改：

RETURNS
波动性 (VOLATILE/IMMUTABLE)
Null 处理 (CALLED ON NULL INPUT/RETURNS NULL ON NULL)

示例¶

创建简单的服务函数¶

在教程 1 中，您可以创建以下服务函数：

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

Copy

此函数连接指定 SERVICE 的特定 ENDPOINT。当您调用此函数时，Snowflake 会向服务容器内的 /echo 路径发送请求。

请注意以下事项：

my_echo_udf 函数将字符串作为输入并返回字符串。
SERVICE 属性标识服务 (echo_service)，ENDPOINT 属性标识用户友好的端点名称 (echoendpoint)。
AS '/echo' 指定服务的路径。在 echo_service.py`（请参阅服务代码）中，则 :code:`@app.post 装饰器将此路径与 echo 函数相关联。

使用 CREATE OR ALTER FUNCTION (Snowpark Container Services) 命令更改服务函数¶

更改函数 my_echo_udf，将批处理行的最大数量设置为 100，并添加上下文标题和端点：

CREATE OR ALTER FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE = echo_service
  ENDPOINT = reverse_echoendpoint
  CONTEXT_HEADERS = (current_account)
  MAX_BATCH_ROWS = 100
  AS '/echo';

Copy