코드 번들¶

모든 공동 작업자는 사용자 지정 Python 프로시저, UDFs, UDTFs를 공동 작업 템플릿과 함께 번들로 묶을 수 있습니다. 그러면 템플릿은 번들로 제공되는 코드를 참조하여 공동 작업 시 복잡한 데이터 작업을 수행합니다. 일반적인 사용에는 쿼리 내에서의 머신 러닝 또는 사용자 지정 데이터 조작이 포함됩니다. 업로드한 코드는 `승인된 Python 패키지 번들<https://repo.anaconda.com/pkgs/snowflake/>`_ 및 :ref:`Snowpark API<label-dcr_snowpark_udf>`에서 패키지를 가져오고 사용할 수 있습니다.

사용자 지정 코드는 템플릿을 통해서만 호출할 수 있으며 직접 호출할 수는 없습니다.

참고

Python은 코드 번들에 대해 지원되는 유일한 코딩 언어입니다.

다음 섹션에서는 코드 번들을 업로드하고 사용하는 방법을 보여줍니다.

사용자 지정 코드 번들 구현하기¶

코드 번들을 업로드하고 사용하는 방법은 다음과 같습니다.

코드 제출자:

:ref:`REGISTER_CODE_SPEC <label-dcr_collab_register_code_spec>`을 호출하여 :ref:`코드를 생성하고 등록 <label-dcr_collaboration_create_and_register_code_bundle>`합니다.

코드는 사양에서 인라인이거나 :ref:`스테이지에서 연결 <label-dcr_collab_code_bundles_staged_artifacts>`될 수도 있습니다.

템플릿의 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>

템플릿을 등록한 다음 :ref:`템플릿을 협업에 연결 <label-dcr_collaboration_code_bundle_link_template>`합니다.

분석 실행기:

``RUN``을 호출하여 표준 방식으로 템플릿을 실행합니다.

중요

Snowflake는 업로드된 번들에 대한 보안 검사를 실행한 후 클린룸에 배포합니다. 보안 검사에 실패하면 템플릿과 번들 코드가 배포되지 않고 사용할 수 없게 됩니다.

코드 번들이 포함된 템플릿이 배포되어 사용할 준비가 되었는지 확인하려면 다음 단계를 따릅니다.

코드 번들을 배포하려는 클린룸 애플리케이션의 이름을 찾습니다.
SHOW APPLICATIONS LIKE 'SFDCR_<collaboration name>';
DESCRIBE APPLICATION 응답에서 upgrade_state 값을 확인합니다. 업그레이드 상태가 COMPLETE인 경우, 보안 검사를 통과하여 새 템플릿과 번들을 사용할 수 있습니다. 다음 예제와 같이 SQL을 사용하여 이전 단계의 명령에서 반환된 애플리케이션 이름을 전달합니다. SQL 코드:
DESCRIBE APPLICATION <application name>

코드 번들 사양 생성 및 등록¶

사용자 지정 코드를 업로드하는 첫 번째 단계는 코드 번들 사양을 생성하고 등록하는 것입니다.

사용자 지정 함수는 YAML 코드 번들 사양에 정의됩니다. 각 코드 번들은 템플릿에서 호출할 수 있는 하나 이상의 함수를 노출합니다. 코드 번들 사양은 사양에 코드를 인라인으로 포함하거나 :ref:`Snowflake 스테이지에 있는 코드에 연결 <label-dcr_collab_code_bundles_staged_artifacts>`할 수 있습니다.

공동 작업자는 번들 ID를 반환하는 ``REGISTRY.REGISTER_CODE_SPEC``을 호출하여 사양을 등록합니다.

코드 번들을 참조하는 템플릿이 공동 작업에 연결되면 해당 코드 번들은 코드 번들을 연결하는 템플릿에 액세스할 수 있는 공동 작업의 모든 사용자에게 표시됩니다. ``VIEW_CODE_SPECS``를 호출하여 협업에서 액세스 가능한 코드 번들을 나열합니다.

협업에서 코드 번들을 볼 수 있는 사용자는 해당 협업의 자체 템플릿에서 코드 번들을 보고 사용할 수 있습니다. 모든 인라인 코드는 공동 작업의 모든 구성원이 볼 수 있지만, 스테이징된 아티팩트 코드는 공동 작업자가 볼 수 없습니다. 공동 작업자는 코드 무결성 확인을 위해 참조된 아티팩트의 content_hash 가 일치하는지 확인해야 합니다.

다음 코드 번들 사양은 normalize_value``라는 단일 Python UDF를 노출하며, 해당 사양에 정의된 ``normalize 함수를 호출합니다.

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

호출 템플릿 생성 및 등록¶

코드 사양이 등록된 후 공동 작업자는 이 코드 번들을 사용하는 템플릿을 등록합니다. 코드 번들을 사용하려면 번들 사양 ID를 템플릿의 code_specs 필드에 추가합니다. 이 템플릿을 공동 작업에 추가하면 번들로 제공되는 코드도 공동 작업에서 사용할 수 있습니다.

템플릿은 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 보안 검사가 트리거되고 기본 클린룸의 새 패치가 발급됩니다. 프로세스가 완료되고 패치가 설치될 때까지 템플릿을 사용할 수 없습니다.

패치 설치 진행 상황을 확인하려면 다음을 수행합니다.

클린룸 애플리케이션의 이름을 찾습니다. 일반적으로 이는 SFDCR_<clean room name> 이지만, 다음을 검색하여 확인할 수 있습니다.
```
-- Find the exact name of the clean room application.
SHOW APPLICATIONS LIKE 'SFDCR_%';
```
패치 설치 상태를 확인합니다. 다음 쿼리에서 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)

휠 패키지가 있는 스테이징된 아티팩트¶

코드 사양의 스테이징된 코드에 연결하려면 :ref:`stage_path 설명서 요구 사항 <label-dcr_collab_code_bundle_spec_yaml>`을 확인하세요.

이 YAML 예제는 스테이징된 Python 휠 패키지를 사용합니다.

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