代码包规范¶

此规范定义了一个或多个可由模板调用的代码函数或过程的捆绑包。

一个代码包规范最多可以包含 5 个函数和过程。

有关不同类型代码包的示例，请参阅示例规范。

代码包规范中的标识符具有以下一般要求：

名称：必须是以字母开头、仅包含字母数字字符和下划线的有效 Snowflake 标识符。
带引号的标识符：包含特殊字符的名称支持使用双引号标识符。
区分大小写：不带引号的标识符不区分大小写；带引号的标识符保留大小写。

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: code_spec            # Required: Must be "code_spec"
name: <identifier>              # Required: Unique name of this code bundle.
version: <version_id>           # Required: Alphanumeric with underscores (max 20 chars)
description: <description_text> # Optional: Description (max 1,000 chars)

artifacts:                      # Optional: Staged files for import
  - alias: <identifier>         # One or more artifact items...
    stage_path: <stage_path>    # Required: Full stage path. See below for additional requirements.
    description: <description_text>  # Optional: Description (max 500 chars)
    content_hash: <sha256_hash>      # Optional: Lowercase SHA-256 hash for integrity verification

functions:                      # Required if no procedures defined
  - name: <identifier>          # One or more functions...
    type: UDF | UDTF            # Required: Function type
    language: PYTHON            # Required: Currently only PYTHON supported
    runtime_version: <python_version>  # Optional: Python runtime (3.10 - 3.14)
    handler: <handler>          # Required: Handler function
    arguments:                  # Optional: One or more function arguments
      - name: <arg_name>        # Argument name
        type: <sql_type>        # Snowflake SQL type of this argument
    returns: <sql_type>         # Required: Snowflake return type
    packages:                   # Optional: Package dependencies
      - <package_name>          # One or more package items...
    imports:                    # Optional: Artifact aliases to import
      - <artifact_alias>        # One or more import items...
    code_body: |                # Optional: Inline Python code (max 12 MB)
      <inline_python_code>
    description: <description_text>  # Optional: Description of this function.

procedures:                     # Required if no functions defined
  - name: <identifier>          # One or more procedure items...
    language: PYTHON            # Required: Currently only PYTHON supported
    runtime_version: <python_version>  # Optional: Python runtime version
    handler: <handler>          # Required: Handler function
    arguments:                  # Optional: One or more procedure arguments
      - name: <arg_name>        # Argument name
        type: <sql_type>        # Snowflake SQL type of this argument
    returns: <sql_type>         # Optional: Return type
    packages:                   # Optional: Package dependencies
      - <package_name>          # One or more package items...
    imports:                    # Optional: Artifact aliases to import
      - <artifact_alias>        # One or more import items...
    code_body: |                # Optional: Inline Python code
      # inline python_code ...
    description: <description_text>  # Optional: Description of this procedure.

api_version

所使用的 Collaboration API 的版本。必须是 2.0.0

spec_type

规范类型标识符。必须是 code_spec

name: identifier

此注册表中该代码包规范的唯一名称。必须是有效的 Snowflake 标识符，且最多 75 个字符。在模板中调用函数时，这将用作名称的最后一段：cleanroom.code_spec_name$function_name

version: version_id

自定义版本标识符。必须是带下划线的字母数字，最多 20 个字符。

:samp:`description: {description_text}`（可选）

代码包规范的描述（最多 1,000 个字符）。

``artifacts``（可选）

可由您的函数或过程导入的暂存文件或包列表，并可以选择通过处理程序函数公开。每个规范最多 5 个。

alias: identifier: 用于在导入中引用此工件的别名。在本规范中引用此别名时，请使用裸别名而不是 cleanroom.spec_name$alias；也就是说，使用裸函数名称来引用本规范中的另一个函数。
stage_path: stage_path: 工件文件的完整暂存区路径。例如 @DB.SCHEMA.STAGE/path/file.whl。

暂存区必须是内部暂存区。 不支持外部暂存区。
暂存区必须启用 DIRECTORY：包含工件的暂存区必须设置 DIRECTORY = TRUE。
暂存区路径格式：必须遵循 @[DB.]SCHEMA.STAGE/path/to/file.ext 格式。
无路径遍历：暂存区路径不能包含 .. 或 \。
此工件必须存在：注册代码包时，该文件必须存在于指定的暂存区路径中。
暂存区必须启用 SNOWFLAKE_SSE 服务端加密。 创建或更改暂存区时，请设置 ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')。
如果您推送、删除或更新暂存的代码文件， 则必须调用 ALTER STAGE stage name REFRESH 以确保协作拥有来自暂存区的最新信息。仅在注册代码规范之前支持代码更新，因为此时会分配版本并计算哈希校验和。

:samp:`description: {description_text}`（可选）: 工件的描述（最多 500 个字符）。
:samp:`content_hash: {sha256_hash}`（可选）: 用于完整性验证的小写 SHA-256 哈希值（64 个十六进制字符）。

functions （如果未定义过程，则为必填项）

UDF 或 UDTF 定义的列表。

name: identifier: 要向调用模板公开的函数名称。必须是有效的 Snowflake 标识符。
type: 函数类型。UDF 或 UDTF 之一。
language: 函数语言。目前仅支持 PYTHON。
:samp:`runtime_version: {python_version}`（可选）: 要使用的 Python 运行时版本。支持的版本：3.10 到 3.14。
handler: handler: 调用 name 时要在函数代码中调用的处理程序函数名称。
``arguments``（可选）: 以名称-类型对列表形式表示的函数实参。类型必须是有效的 Snowflake SQL 类型。
returns: sql_type: 返回类型。对于 UDFs，请使用 SQL 类型，例如 STRING 或 FLOAT。对于 UDTFs，请使用 TABLE(column_definitions)。
``packages``（可选）: 此代码使用的包列表。这可以是这些 Anaconda Python 包 (https://repo.anaconda.com/pkgs/snowflake/) 或这些 Snowpark API 包中的任何一个。例如：snowflake-snowpark-python，numpy。
``imports``（可选）: 要导入的工件列表。这些必须是本规范中工件列表中的别名。
``code_body``（可选）: 内联 Python 代码。与暂存导入互斥。最大大小为 12 MB。
:samp:`description: {description_text}`（可选）: 函数的描述（最多 500 个字符）。

procedures （如果未定义函数，则为必填项）

存储过程定义列表。字段与 functions 类似，但没有 type 字段。