Especificação do pacote de código¶

Esta especificação define um pacote de uma ou mais funções ou procedimentos de código que podem ser chamados por um modelo.

Uma especificação de pacote de código pode conter um máximo combinado de 5 funções e procedimentos.

Para obter exemplos de diferentes tipos de pacotes de código, consulte Exemplos de especificações.

Os identificadores na especificação do pacote de código têm os seguintes requisitos gerais:

Nomes: devem ser identificadores válidos do Snowflake, que começam com uma letra e contêm apenas caracteres alfanuméricos e sublinhados.
Identificadores entre aspas: identificadores entre aspas duplas são permitidos para nomes com caracteres especiais.
Diferenciação entre maiúsculas e minúsculas: identificadores sem aspas não diferenciam maiúsculas de minúsculas. Identificadores entre aspas preservam o uso de maiúsculas e minúsculas.

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

A versão da API do Collaboration utilizada. Deve ser 2.0.0.

spec_type

Identificador do tipo de especificação. Deve ser code_spec.

name: identifier

Um nome exclusivo para esta especificação de pacote de código neste registro. Deve ser um identificador válido do Snowflake com no máximo 75 caracteres. Ele é usado como o segmento do sobrenome ao chamar a função em um modelo: cleanroom.code_spec_name$function_name

version: version_id

Identificador de versão personalizado. Deve ser alfanumérico com sublinhados e, no máximo, 20 caracteres.

description: description_text (opcional)

Uma descrição da especificação do pacote de código (máximo de 1.000 caracteres).

artifacts (opcional)

Uma lista de arquivos ou pacotes preparados que podem ser importados por suas funções ou procedimentos e opcionalmente expostos por meio de funções do manipulador. Máximo de 5 por especificação.

alias: identifier: Um alias para referenciar este artefato nas importações. Ao referenciar este alias nesta especificação, use o nome do alias simples em vez de cleanroom.spec_name$alias; ou seja, use o nome da função simples para fazer referência a outra função nesta especificação.
stage_path: stage_path: Caminho completo da área de preparação para o arquivo de artefato. Por exemplo, @DB.SCHEMA.STAGE/path/file.whl.

A área de preparação deve ser interna. Áreas de preparação externas não são compatíveis.
A área de preparação deve ter o DIRECTORY habilitado: a área de preparação que contém artefatos deve ter DIRECTORY = TRUE definido.
Formato do caminho da área de preparação: deve seguir o formato @[DB.]SCHEMA.STAGE/path/to/file.ext.
Sem travessia de caminho: os caminhos de área de preparação não podem conter .. ou \.
Este artefato deve existir: o arquivo deve existir no caminho da área de preparação especificado quando o pacote de código for registrado.
A área de preparação deve ter a criptografia do lado do servidor SNOWFLAKE_SSE habilitada. Ao criar ou alterar a área de preparação, defina ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE').
Se você enviar, excluir ou atualizar um arquivo de código preparado, deverá chamar ALTER STAGE stage name REFRESH para garantir que a colaboração tenha as informações mais recentes da área de preparação. As atualizações de código são permitidas apenas antes de você registrar a especificação do código, pois é quando a versão é atribuída e a soma de verificação do hash é calculada.

description: description_text (opcional): Uma descrição do artefato (máximo de 500 caracteres).
content_hash: sha256_hash (opcional): Hash SHA-256 em minúsculas para verificação de integridade (64 caracteres hexadecimais).

functions (obrigatório se nenhum procedimento for definido)

Uma lista de definições de UDF ou UDTF.

name: identifier: O nome da função a ser exposta ao modelo de chamada. Deve ser um identificador válido do Snowflake.
type: O tipo de função. UDF ou UDTF.
language: A linguagem da função. Atualmente, somente PYTHON é compatível.
runtime_version: python_version (opcional): Versão de tempo de execução do Python a ser usada. Versões compatíveis: 3.10 a 3.14.
handler: handler: O nome da função do manipulador no código da função a ser chamada quando name é chamado.
arguments (opcional): Argumentos de função como uma lista de pares nome-tipo. Devem ser tipos SQL válidos do Snowflake.
returns: sql_type: O tipo de retorno. Para UDFs, use um tipo SQL, como STRING ou FLOAT. Para UDTFs, use TABLE(column_definitions):
packages (opcional): Uma lista de pacotes usados por este código. Pode ser qualquer um destes pacotes Anaconda Python ou destes pacotes da API Snowpark. Por exemplo: snowflake-snowpark-python, numpy.
imports (opcional): Uma lista de artefatos a serem importados. Eles devem ser aliases da lista de artefatos nesta especificação.
code_body (opcional): Código Python em linha. Mutualmente exclusivo com importações preparadas. O tamanho máximo é 12 MB.
description: description_text (opcional): Uma descrição da função (máximo de 500 caracteres).

procedures (obrigatório se nenhuma função for definida)

Uma lista de definições de procedimentos armazenados. Os campos são semelhantes a functions, exceto que não há um campo type.