Pacotes de código

Qualquer colaborador pode agrupar procedimentos Python personalizados, UDFs ou UDTFs com modelos de colaboração. Os modelos, por sua vez, fazem referência ao código agrupado para executar ações de dados complexas na colaboração. O uso comum inclui machine learning ou manipulação de dados personalizados em uma consulta. O código carregado pode importar e usar pacotes de um conjunto aprovado de pacotes Python e da Snowpark API.

O código personalizado só pode ser chamado por meio de modelos e não diretamente.

Nota

Python é a única linguagem de programação compatível com pacotes de código.

As seções a seguir mostram como carregar e usar pacotes de código.

Implementando pacotes de código personalizados

Veja como carregar e usar um pacote de código:

Quem envia o código:

  1. Cria e registra o código chamando REGISTER_CODE_SPEC.

    O código pode estar em linha na especificação ou vinculado de uma área de preparação.

  2. Cria um modelo que faz referência à especificação do pacote de código pelo ID na matriz code_specs do modelo. Adicione esse campo como um par de campos de modelo e de parâmetros, conforme mostrado neste exemplo:

     parameters:
   - name: <parameter_name>
     description: <parameter_description>
     required: <true_or_false>
     default: <default_value>
     type: <data_type>

 code_specs:             # Optional: List of code bundles used by this template
 - <code_spec_id>        # One or more code spec IDs.

 template: |
   <template_content>

  3. Registra e vincula o modelo à colaboração.

Quem executa a análise:

  • Executa o modelo da maneira padrão, chamando RUN.

Importante

O Snowflake executa verificações de segurança em todos os pacotes carregados antes de implantá-los em uma sala limpa. Se uma verificação de segurança falhar, o modelo e seu código em pacote não serão implantados nem estarão disponíveis para uso.

Para confirmar se um modelo com um pacote de código está implantado e pronto para uso, siga as etapas a seguir:

  1. Encontre o nome do aplicativo de sala limpa em que você está tentando implantar o pacote de código:

    SHOW APPLICATIONS LIKE 'SFDCR_<collaboration name>';

  2. Verifique o valor upgrade_state na resposta de DESCRIBE APPLICATION. Quando o estado da atualização é COMPLETE, as verificações de segurança foram aprovadas, e o modelo e o pacote novos estão disponíveis para uso. Passe o nome do aplicativo retornado pelo comando na etapa anterior usando SQL, como no exemplo a seguir: código SQL:

    DESCRIBE APPLICATION <application name>

Criar e registrar a especificação do pacote de código

A primeira etapa para carregar o código personalizado é criar e registrar a especificação do pacote de código.

As funções personalizadas são definidas em uma especificação de pacote de código YAML. Cada pacote de código expõe uma ou mais funções que podem ser chamadas por um modelo. A especificação do pacote de código pode incluir o código na especificação em linha ou vincular para o código que reside em uma área de preparação do Snowflake.

Um colaborador registra uma especificação chamando REGISTRY.REGISTER_CODE_SPEC, que retorna o ID do pacote.

Depois que o modelo que referencia o pacote de código for vinculado à colaboração, esse pacote de código ficará visível para qualquer pessoa na colaboração que possa acessar um modelo que o vincule. Chame VIEW_CODE_SPECS para listar pacotes de código acessíveis em uma colaboração.

Qualquer pessoa que possa ver um pacote de código em uma colaboração poderá vê-lo e usá-lo em seus próprios modelos nessa colaboração. Qualquer código em linha pode ser visualizado por qualquer membro da colaboração, mas o código do artefato preparado não pode ser visualizado pelos colaboradores. Os colaboradores precisam garantir que o content_hash dos artefatos referenciados corresponda para a verificação de integridade do código.

A especificação do pacote de código a seguir expõe uma única UDF Python chamada normalize_value, que chama a função normalize definida nessa especificação:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value):
            return value / 100.0
  $$
);

Criar e registrar o modelo de chamada

Após o registro da especificação de código, o colaborador registra um modelo que usa esse pacote de código. Para usar um pacote de código, adicione o ID da especificação do pacote ao campo code_specs do modelo. Adicionar este modelo à colaboração também fará com que o código empacotado fique disponível na colaboração.

Um modelo chama uma função personalizada usando a sintaxe cleanroom.spec_name$function_name. Observe as marcas de escopo de nomes . e $.

Nota

Use o nome, e não o ID, da especificação para fazer referência a uma função em seu modelo. Isso permite que você atualize rapidamente a versão do seu pacote de código sem precisar alterar todas as referências a ele no seu modelo.

No exemplo a seguir, um modelo usa a função normalize_value do pacote de código custom_udf:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v1
  type: sql_analysis
  code_specs:
    - custom_udf_v1  -- Imports the code bundle.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

Adicionar o modelo a uma colaboração

Adicione o modelo que chama sua função à colaboração da maneira padrão. Para obter mais informações, consulte Modelos.

O Snowflake o valida e carrega na colaboração quando o modelo de chamada é adicionado a uma colaboração. O exemplo a seguir mostra uma solicitação para adicionar um modelo a uma colaboração existente:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ADD_TEMPLATE_REQUEST(
  'my_collaboration',
  'normalization_template_v1',
  ['consumer']
);

Nota

A instalação de um modelo com um pacote de código aciona uma verificação de segurança do Snowflake e emite um novo patch da sala limpa subjacente. O modelo não estará disponível ou utilizável até que o processo seja concluído e o patch seja instalado.

Para verificar o progresso da instalação do patch:

  1. Encontre o nome do aplicativo de sala limpa. Normalmente, será SFDCR_<clean room name>, mas você pode pesquisar para ter certeza:

    -- Find the exact name of the clean room application.
SHOW APPLICATIONS LIKE 'SFDCR_%';

  2. Verifique o status da instalação do patch. Aguarde até que upgrade_state esteja COMPLETE na seguinte consulta:

    DESCRIBE APPLICATION SFDCR_<application name>;

Controlando as versões do seu código

Cada especificação de código registrada deve ter um nome + versão exclusivos em todos os registros em sua conta. Um modelo carrega um nome e uma versão específicos de uma especificação de código. Se quiser criar ou consumir uma nova versão do seu código, você deverá enviar uma nova versão do modelo que faça referência à nova versão do código no campo code_specs. Você não precisa alterar o corpo do modelo. Por exemplo:

Etapa 1: Consumir a versão 1 do pacote de código:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v1
  type: sql_analysis
  code_specs:
    - custom_udf_v1  -- Bundle ID includes the version number.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

Etapa 2: Atualizar e registrar a nova versão do seu pacote de código e, em seguida, atualizar seu modelo para usar a nova versão:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: normalization_template
  version: v2        -- Update the template version.
  type: sql_analysis
  code_specs:
    - custom_udf_v2  -- Use the new code bundle.
  template: |
    SELECT cleanroom.custom_udf$normalize_value(100)  -- No change needed here.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

Observe que os nomes das funções não incluem a versão; portanto, você não precisa alterar o código de chamada no corpo do modelo ao carregar uma nova versão de uma função.

Exemplos de especificações

UDF em linha com corpo de código

Uma UDF simples com código Python em linha:

api_version: 2.0.0
spec_type: code_spec
name: string_utils
version: v1
description: String utility functions

functions:
  - name: clean_string
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: clean
    arguments:
      - name: input_str
        type: STRING
    returns: STRING
    description: Removes leading/trailing whitespace and converts to lowercase
    code_body: |
      def clean(input_str):
          if input_str is None:
              return None
          return input_str.strip().lower()

  - name: extract_domain
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: extract
    arguments:
      - name: email
        type: STRING
    returns: STRING
    description: Extracts domain from email address
    code_body: |
      def extract(email):
          if email is None or '@' not in email:
              return None
          return email.split('@')[1]

UDTF (função de tabela definida pelo usuário)

Este exemplo de YAML define uma UDTF que retorna várias linhas:

api_version: 2.0.0
spec_type: code_spec
name: tokenizer
version: v1
description: Text tokenization UDTF

functions:
  - name: tokenize_text
    type: UDTF
    language: PYTHON
    runtime_version: "3.10"
    handler: Tokenizer
    arguments:
      - name: text
        type: STRING
      - name: delimiter
        type: STRING
    returns: TABLE(token STRING, position INTEGER)
    description: Splits text into tokens and returns each with its position
    code_body: |
      class Tokenizer:
          def process(self, text, delimiter):
              if text is None:
                  return
              tokens = text.split(delimiter if delimiter else ' ')
              for i, token in enumerate(tokens):
                  yield (token.strip(), i)

Artefato preparado com pacote wheel

Leia os requisitos na documentação do stage_path para vincular ao código preparado na sua especificação de código.

Este exemplo de YAML utiliza um pacote wheel Python preparado:

api_version: 2.0.0
spec_type: code_spec
name: ml_scoring
version: v2
description: ML scoring functions using custom library

artifacts:
  - alias: ml_lib
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/libs/ml_scoring_lib-1.0.0-py3-none-any.whl"
    description: Custom ML scoring library
    content_hash: "a1b2c3d4e5f6..."

functions:
  - name: predict_score
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: ml_scoring_lib.predictor.predict
    arguments:
      - name: features
        type: ARRAY
    returns: FLOAT
    packages:
      - numpy
      - scikit-learn
    imports:
      - ml_lib
    description: Predicts score using trained ML model

Procedimento armazenado

Este exemplo de YAML define um procedimento armazenado para processamento de dados:

api_version: 2.0.0
spec_type: code_spec
name: data_processor
version: v1
description: Data processing procedures

procedures:
  - name: aggregate_metrics
    language: PYTHON
    runtime_version: "3.10"
    handler: process
    arguments:
      - name: table_name
        type: STRING
      - name: group_column
        type: STRING
    returns: STRING
    packages:
      - snowflake-snowpark-python
    description: Aggregates metrics by specified column
    code_body: |
      def process(session, table_name, group_column):
          df = session.table(table_name)
          result = df.group_by(group_column).count()
          result.write.mode("overwrite").save_as_table("aggregated_results")
          return f"Aggregated {df.count()} rows into aggregated_results"

Vários arquivos Python como artefatos preparados

Leia os requisitos na documentação do stage_path para vincular ao código preparado na sua especificação de código.

Este exemplo de YAML utiliza vários arquivos de origem Python preparados:

api_version: 2.0.0
spec_type: code_spec
name: analytics_suite
version: v3
description: Analytics suite with multiple modules

artifacts:
  - alias: utils
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/utils.py"
    description: Utility functions
  - alias: transformers
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/transformers.py"
    description: Data transformation functions
  - alias: validators
    stage_path: "@MY_DB.PUBLIC.CODE_STAGE/analytics/validators.py"
    description: Validation functions

functions:
  - name: transform_and_validate
    type: UDF
    language: PYTHON
    runtime_version: "3.10"
    handler: transformers.transform_validate
    arguments:
      - name: data
        type: OBJECT
    returns: OBJECT
    imports:
      - utils
      - transformers
      - validators
    description: Transforms and validates input data