CREATE FUNCTION (Snowpark Container Services)

创建 服务函数。

另请参阅：

服务函数、CREATE EXTERNAL FUNCTION、DESC FUNCTION、DROP FUNCTION、ALTER FUNCTION，

语法

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> ]
  AS '<http_path_to_request_handler>'
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 ]

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

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 上下文标头。

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

访问控制要求

用于执行此 SQL 命令的 角色 必须至少具有以下 权限：

权限

对象

备注

CREATE FUNCTION

架构

USAGE

服务端点

服务规范中定义的服务角色将获得服务端点的使用权限。然后，您为服务角色授予创建服务函数的角色。

请注意，对架构中的对象进行操作还需要对父数据库和架构具有 USAGE 权限。

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

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

使用说明

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

  • 关于元数据：

    注意

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

示例

在 教程 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 函数相关联。

语言: 中文