コードバンドル

コラボレーターは、カスタムPythonプロシージャ、 UDFs または UDTFs をコラボレーションテンプレートでバンドルできます。テンプレートは順番にバンドルされたコードを参照して、コラボレーションで複雑なデータアクションを実行します。一般的な使用法には、クエリ内の機械学習やカスタマイズされたデータ操作が含まれます。アップロードされたコードは、 Pythonパッケージの承認済みバンドル および Snowpark API からパッケージをインポートして、使用できます。

カスタムコードはテンプレート経由でのみ呼び出すことができ、直接呼び出すことはできません。

注釈

Pythonは、コードバンドルでサポートされている唯一のコーディング言語です。

次のセクションでは、コードバンドルをアップロードして使用する方法を説明します。

カスタムコードバンドルの実装

コードバンドルをアップロードして使用する方法は次のとおりです。

コード送信者

  1. REGISTER_CODE_SPEC。

    コードは仕様内にインラインで記述するか、ステージからリンクできます。

  2. テンプレートの``code_specs``配列内でIDによって:ref:コードバンドル仕様を参照するテンプレートを作成します<label-dcr_collaboration_create_and_register_code_bundle_template>。この例に示すように、このフィールドをテンプレートおよびパラメーターフィールドと同列に追加します。

     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. テンプレートを登録してから、テンプレートをコラボレーションにリンクします。

分析実行者：

  • ``RUN``を呼び出して、標準的な方法でテンプレートを実行します。

重要

Snowflakeは、アップロードされたバンドルをクリーンルームにデプロイする前にセキュリティチェックを実行します。セキュリティチェックが失敗した場合、テンプレートとそのバンドルコードはデプロイされず、使用できません。

コードバンドルを含むテンプレートがデプロイされ、使用可能であることを確認するには、以下のステップを実行します。

  1. コードバンドルをデプロイしようとしているクリーンルームアプリケーションの名前を見つけます。

    SHOW APPLICATIONS LIKE 'SFDCR_<collaboration name>';

  2. DESCRIBE APPLICATIONの応答で``upgrade_state``の値を確認します。アップグレード状態がCOMPLETEの場合、セキュリティチェックに合格しており、新しいテンプレートとバンドルを使用できます。次の例のSQLコードのように、SQLを使用して前のステップのコマンドによって返されたアプリケーション名を渡します。

    DESCRIBE APPLICATION <application name>

コードバンドル仕様の作成と登録

カスタムコードをアップロードする最初のステップは、コードバンドル仕様を作成して登録することです。

カスタム関数は、YAMLコードバンドル仕様で定義されます。各コードバンドルは、テンプレートから呼び出すことができる1つ以上の関数を公開します。コードバンドル仕様には、仕様内にコードをインラインで含めるか、:ref:`Snowflakeステージ上にあるコードにリンクする<label-dcr_collab_code_bundles_staged_artifacts>`ことができます。

コラボレーターは、``REGISTRY.REGISTER_CODE_SPEC``を呼び出して仕様を登録します。これにより、バンドルIDが返されます。

コードバンドルを参照するテンプレートがコラボレーションにリンクされると、そのコードバンドルは、コードバンドルをリンクするテンプレートにアクセスできるコラボレーション内のすべてのユーザーに表示されます。``VIEW_CODE_SPECS``を呼び出して、コラボレーション内でアクセス可能なコードバンドルを一覧表示します。

コラボレーションでコードバンドルを表示できるユーザーは誰でも、そのコラボレーション内の自分のテンプレートでそれを表示して使用できます。インラインコードはコラボレーションのメンバーであれば誰でも表示できますが、ステージングされたアーティファクトコードはコラボレーターには表示されません。コラボレーターは、参照されたアーティファクトの content_hash がコードの整合性検証にふさわしいものか確認する必要があります。

その仕様で定義されている``normalize``関数を呼び出す、``normalize_value``という名前の単一のPythonUDFを公開するコードバンドル仕様は次のとおりです。

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
  $$
);

呼び出しテンプレートの作成と登録

コード仕様が登録された後、コラボレーターはこのコードバンドルを使用するテンプレートを登録します。コードバンドルを使用するには、テンプレートの``code_specs``フィールドにバンドル仕様IDを追加します。このテンプレートをコラボレーションに追加すると、バンドルされたコードもコラボレーションで利用できるようになります。

テンプレートは、構文:samp:cleanroom.{spec_name}${function_name}`を使用してカスタム関数を呼び出します。リテラルの`.``および``$``の名前スコープマークに注意してください。

注釈

テンプレート内の関数を参照するには、仕様IDではなく仕様名を使用します。これは、テンプレート内のすべての参照を変更することなく、コードバンドルのバージョンをすばやく更新できるようにするためです。

以下の例では、テンプレートはコードバンドル``custom_udf``の関数``normalize_value``を使用します。

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] }}
  $$
);

コラボレーションへのテンプレートの追加

標準的な方法で、関数を呼び出すテンプレートをコラボレーションに追加します。詳細については、 テンプレート をご参照ください。

呼び出しテンプレートがコラボレーションに追加されると、Snowflakeは検証を行い、コラボレーションにアップロードします。次の例は、既存のコラボレーションにテンプレートを追加するリクエストを示しています。

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

注釈

コードバンドルを含むテンプレートをインストールすると、Snowflakeセキュリティチェックがトリガーされ、基礎となるクリーンルームの新しいパッチが発行されます。プロセスが完了し、パッチがインストールされるまで、テンプレートは使用できません。

パッチインストールの進行状況を確認するには、以下を手順を実行します。

  1. クリーンルームアプリケーションの名前を検索します。通常、これは SFDCR_<clean room name> ですが、検索して以下であることを確認できます。

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

  2. パッチインストールのステータスを確認します。以下のクエリで upgrade_state が COMPLETE になるまで待機します。

    DESCRIBE APPLICATION SFDCR_<application name>;

コードのバージョン管理

すべての登録済みコード仕様は、アカウント内のすべてのレジストリにおいて一意の「名前＋バージョン」を持つ必要があります。テンプレートは、コード仕様の特定の名前とバージョンをロードします。コードの新しいバージョンを作成または使用する場合は、code_specsフィールドで新しいコードバージョンを参照するテンプレートの新しいバージョンを送信する必要があります。テンプレート本文を変更する必要はありません。例:

**ステップ1：**コードバンドルのバージョン1を使用します。

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] }}
  $$
);

**ステップ2：**コードバンドルの新しいバージョンを更新および登録し、新しいバージョンを使用するようにテンプレートを更新します。

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] }}
  $$
);

関数名にはバージョンが含まれないため、関数の新しいバージョンをアップロードするときにテンプレート本文の呼び出しコードを変更する必要はありません。

仕様の例

コード本文付きのインラインUDF

インラインPythonコードを使用した単純なUDF

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（ユーザー定義テーブル関数）

この例のYAMLは、複数行を返すUDTFを定義します。

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)

Wheelパッケージを使用したステージングされたアーティファクト

コード仕様内のステージングされたコードにリンクするための、:ref:`stage_pathドキュメント要件<label-dcr_collab_code_bundle_spec_yaml>`を必ずお読みください。

この例のYAMLは、ステージングされたPython Wheelパッケージを使用します。

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

ストアドプロシージャ

この例のYAMLは、データ処理用のストアドプロシージャを定義します。

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"

ステージングされたアーティファクトとしての複数のPythonファイル

コード仕様内のステージングされたコードにリンクするための、:ref:`stage_pathドキュメント要件<label-dcr_collab_code_bundle_spec_yaml>`を必ずお読みください。

この例のYAMLは、ステージングされた複数のPythonソースファイルを使用します。

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