Code bundle specification¶

This specification defines a bundle of one or more code functions or procedures that can be called by a template.

A code bundle spec can contain a combined maximum of 5 functions and procedures.

For examples of different kinds of code bundles, see Example specs.

Identifiers in the code bundle spec have the following general requirements:

Names: Must be valid Snowflake identifiers that start with a letter and contain only alphanumeric characters and underscores.
Quoted identifiers: Double-quoted identifiers are supported for names with special characters.
Case sensitivity: Unquoted identifiers are case-insensitive; quoted identifiers preserve case.

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

The version of the Collaboration API used. Must be 2.0.0.

spec_type

Specification type identifier. Must be code_spec.

name: identifier

A unique name for this code bundle spec within this registry. Must be a valid Snowflake identifier with a maximum of 75 characters. This is used as the last name segment when calling the function in a template: cleanroom.code_spec_name$function_name

version: version_id

Custom version identifier. Must be alphanumeric with underscores, maximum 20 characters.

description: description_text (Optional)

A description of the code bundle spec (maximum 1,000 characters).

artifacts (Optional)

A list of staged files or packages that can be imported by your functions or procedures, and optionally exposed via handler functions. Maximum of 5 per spec.

alias: identifier: An alias for referencing this artifact in imports. When referencing this alias within this spec, use the bare alias name rather than cleanroom.spec_name$alias; that is, use the bare function name to reference another function in this spec.
stage_path: stage_path: Full stage path to the artifact file. For example, @DB.SCHEMA.STAGE/path/file.whl.

The stage must be internal. External stages aren’t supported.
The stage must have DIRECTORY enabled: The stage containing artifacts must have DIRECTORY = TRUE set.
Stage path format: Must follow @[DB.]SCHEMA.STAGE/path/to/file.ext format.
No path traversal: Stage paths can’t contain .. or \.
This artifact must exist: The file must exist at the specified stage path when the code bundle is registered.
The stage must have SNOWFLAKE_SSE server-side encryption enabled. When creating or altering the stage, set ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE').
If you push, delete, or update a staged code file, you must call ALTER STAGE stage name REFRESH to ensure that the collaboration has the latest information from the stage. Code updates are supported only before you register the code spec, as this is when the version is assigned and the hash checksum calculated.

description: description_text (Optional): A description of the artifact (maximum 500 characters).
content_hash: sha256_hash (Optional): Lowercase SHA-256 hash for integrity verification (64 hex characters).

functions (Required if no procedures are defined)

A list of UDF or UDTF definitions.

name: identifier: The function name to expose to the calling template. Must be a valid Snowflake identifier.
type: The function type. One of UDF or UDTF.
language: The function language. Currently only PYTHON is supported.
runtime_version: python_version (Optional): Python runtime version to use. Supported versions: 3.10 to 3.14.
handler: handler: The name of the handler function in the function code to call when name is called.
arguments (Optional): Function arguments as a list of name-type pairs. Types must be valid Snowflake SQL types.
returns: sql_type: The return type. For UDFs, use a SQL type such as STRING or FLOAT. For UDTFs, use TABLE(column_definitions).
packages (Optional): A list of packages used by this code. This can be any of these Anaconda Python packages or these Snowpark API packages. For example: snowflake-snowpark-python, numpy.
imports (Optional): A list of artifacts to import. These must be aliases from the artifacts list in this spec.
code_body (Optional): Inline Python code. Mutually exclusive with staged imports. Maximum size is 12 MB.
description: description_text (Optional): A description of the function (maximum 500 characters).

procedures (Required if no functions defined)

A list of stored procedure definitions. Fields are similar to functions, except there is no type field.