Collaboration Clean Rooms에서 사용자 지정 함수 업로드 및 사용¶

소개¶

모든 공동 작업자는 사용자 지정 Python UDFs 및 UDTFs를 협업에 업로드할 수 있습니다. 협업의 템플릿은 이러한 함수를 실행하여 복잡한 데이터 작업을 수행할 수 있습니다. 일반적인 사용에는 쿼리 내에서의 머신 러닝 또는 사용자 지정 데이터 조작이 포함됩니다. 업로드한 코드는 승인된 Python 패키지 번들 및 :ref:`Snowpark API 패키지 <label-dcr_snowpark_udf>`에서 패키지를 가져오고 사용할 수 있습니다.

다음 섹션에서는 사용자 지정 함수를 업로드하고 사용하는 방법을 보여줍니다.

사용자 지정 코드 번들 정의 및 사용¶

사용자 지정 함수를 업로드하고 사용하는 방법은 다음과 같습니다.

코드 제출자:

1. :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>`될 수도 있습니다.

2. 템플릿의 code_specs 배열에서 ID로 :ref:`코드 번들 사양을 참조하는 템플릿을 생성 <label-dcr_collaboration_create_and_register_code_bundle_template>`합니다. 이 예제와 같이 이 필드를 템플릿 및 매개 변수 필드의 피어로 추가합니다.

   CopyExpand

    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>
   

   Show lessSee more

   Scroll to top

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

   참고

   Snowflake는 업로드된 코드에 보안 문제가 있는지 검사합니다. 보안 문제가 발견되면 코드와 포함된 템플릿이 협업에 추가되지 않습니다.

분석 실행기:

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

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

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(metric, 0, 100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

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

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(metric, 0, 100)  -- Calls the UDF.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

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(metric, 0, 100)  -- No change needed here.
      AS normalized
        FROM {{ source_tables[0] }}
  $$
);

코드 번들 사양¶

이 사양은 템플릿에서 호출할 수 있는 하나 이상의 코드 함수 또는 프로시저의 번들을 정의합니다.

코드 번들 사양에는 최대 5개의 함수와 프로시저가 있습니다.

코드 번들 사양의 식별자에는 다음과 같은 일반적인 요구 사항이 있습니다.

• 이름: 문자로 시작하고 영숫자 문자와 밑줄만 포함하는 유효한 :doc:`Snowflake 식별자 </sql-reference/identifiers-syntax>`여야 합니다.

• 따옴표가 있는 식별자: 특수 문자가 포함된 이름에는 큰따옴표로 묶인 식별자가 지원됩니다.

• 대/소문자 구분: 따옴표가 없는 식별자는 대/소문자를 구분하지 않으며, 따옴표로 묶인 식별자는 대/소문자를 유지합니다.

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: 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

사용되는 Collaboration API의 버전입니다. 2.0.0 여야 합니다.

spec_type

사양 유형 식별자입니다. code_spec 여야 합니다.

name: identifier

이 레지스트리 내에서 이 코드 번들 사양의 고유한 이름입니다. 최대 75자의 유효한 Snowflake 식별자 </sql-reference/identifiers-syntax>`여야 합니다. 템플릿에서 함수를 호출할 때 성 세그먼트로 사용됩니다. :samp:`cleanroom.{code_spec_name}${function_name}

version: version_id

사용자 지정 버전 식별자입니다. 밑줄이 포함된 영숫자여야 하며, 최대 20자입니다.

:samp:`description: {description_text}`(선택 사항)

코드 번들 사양에 대한 설명입니다(최대 1,000자).

``artifacts``(선택 사항)

함수 또는 프로시저에서 가져올 수 있는 스테이징된 파일이나 패키지의 목록으로, :ref:`처리기 함수를 통해 선택적으로 노출 <label-dcr_collab_code_bundles_staged_artifacts>`됩니다. 사양당 최대 5개입니다.

alias: identifier

가져오기에서 이 아티팩트를 참조하기 위한 별칭입니다. 이 사양 내에서 이 별칭을 참조할 때 :samp:`cleanroom.{spec_name}${alias}`가 아닌 베어 별칭 이름을 사용합니다. 즉, 베어 함수 이름을 사용하여 이 사양의 다른 함수를 참조합니다.

stage_path: stage_path

아티팩트 파일의 전체 스테이지 경로입니다(예: @DB.SCHEMA.STAGE/path/file.whl).

• 스테이지는 내부 스테이지여야 합니다. 외부 스테이지는 지원되지 않습니다.

• 스테이지에는 DIRECTORY가 활성화되어 있어야 합니다. 아티팩트가 포함된 스테이지에는 ``DIRECTORY = TRUE``가 설정되어 있어야 합니다.

• 스테이지 경로 유형: @[DB.]SCHEMA.STAGE/path/to/file.ext 형식을 따라야 합니다.

• 경로 통과 없음: 스테이지 경로에는 .. 또는 ````를 포함할 수 없습니다.

• 이 아티팩트가 있어야 합니다. 파일은 코드 번들이 등록될 때 지정된 스테이지 경로에 있어야 합니다.

• 스테이지에는 SNOWFLAKE_SSE 서버 측 암호화가 활성화되어 있어야 합니다. 스테이지를 생성하거나 변경할 때 :code:`ENCRYPTION = (TYPE = ‘SNOWFLAKE_SSE’)`를 설정합니다.

• 스테이징된 코드 파일을 푸시, 삭제 또는 업데이트하는 경우 :samp:`ALTER STAGE {stage name} REFRESH`를 호출하여 협업에 스테이지의 최신 정보가 있는지 확인해야 합니다. 코드 업데이트는 버전이 할당되고 해시 체크섬이 계산되는 시점인 코드 사양을 등록하기 전에만 지원됩니다.

:samp:`description: {description_text}`(선택 사항)

아티팩트에 대한 설명입니다(최대 500자).

:samp:`content_hash: {sha256_hash}`(선택 사항)

무결성 확인을 위한 SHA-256 해시입니다(64개의 16진수 문자).

``functions``(프로시저가 정의되지 않은 경우 필수)

UDF 또는 UDTF 정의의 목록입니다.

name identifier

호출 템플릿에 노출할 함수 이름입니다. 유효한 :doc:`Snowflake 식별자 </sql-reference/identifiers-syntax>`여야 합니다.

type

함수 유형입니다. UDF 또는 UDTF 중 하나입니다.

language

함수 언어입니다. 현재는 PYTHON 만 지원됩니다.

:samp:`runtime_version: {python_version}`(선택 사항)

사용할 Python 런타임 버전입니다. 지원되는 버전은 ``3.10``~``3.14``입니다.

handler: handler

``name``이 호출된 경우 호출할 함수 코드의 처리기 함수 이름입니다.

``arguments``(선택 사항)

이름-유형 페어의 목록인 함수 인자입니다. 유형은 유효한 Snowflake SQL 유형이어야 합니다.

returns: sql_type

반환 유형입니다. UDFs의 경우, STRING 또는 ``FLOAT``과 같은 SQL 유형을 사용합니다. UDTFs 의 경우 TABLE(column_definitions) 를 사용합니다.

``packages``(선택 사항)

이 코드에서 사용하는 패키지 목록입니다. 해당 Anaconda Python 패키지 또는 해당 Snowpark API 패키지 <label-dcr_snowpark_udf>`일 수 있습니다. 예: ``snowflake-snowpark-python`, numpy.

``imports``(선택 사항)

가져올 아티팩트의 목록입니다. 이는 이 사양의 아티팩트 목록에 있는 별칭이어야 합니다.

``code_body``(선택 사항)

인라인 Python 코드입니다. 스테이징된 가져오기와 상호 배타적입니다. 최대 크기는 12MB입니다.

:samp:`description: {description_text}`(선택 사항)

함수에 대한 설명입니다(최대 500자).

``procedures``(함수가 정의되지 않은 경우 필수)

저장 프로시저 정의의 목록입니다. 필드는 type 필드가 없는 경우를 제외하고 ``functions``와 유사합니다.

API 참조¶

다음 프로시저는 협업에서 사용자 지정 코드 번들을 관리하는 데 사용됩니다.

REGISTER_CODE_SPEC( ['<registry_name>' ,] <code_spec> )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  description: Custom UDF for data normalization

  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      runtime_version: "3.10"
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
        - name: min_val
          type: FLOAT
        - name: max_val
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value, min_val, max_val):
            if max_val == min_val:
                return 0.0
            return (value - min_val) / (max_val - min_val)
  $$
);

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
  'my_custom_registry',
  $$
  api_version: 2.0.0
  spec_type: code_spec
  name: custom_udf
  version: v1
  description: Custom UDF for data normalization

  functions:
    - name: normalize_value
      type: UDF
      language: PYTHON
      runtime_version: "3.10"
      handler: normalize
      arguments:
        - name: value
          type: FLOAT
        - name: min_val
          type: FLOAT
        - name: max_val
          type: FLOAT
      returns: FLOAT
      code_body: |
        def normalize(value, min_val, max_val):
            if max_val == min_val:
                return 0.0
            return (value - min_val) / (max_val - min_val)
  $$
);

VIEW_REGISTERED_CODE_SPECS( [ '<registry_name>' ] )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_CODE_SPECS();

VIEW_CODE_SPECS( <collaboration_name> )

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_CODE_SPECS(
  $collaboration_id
);

사양 예제¶

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]

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)

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

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"

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

코드 번들 문제 해결하기¶

오류:

CodeSpecAlreadyExistsException

원인:

동일한 이름과 버전의 코드 번들 사양이 이미 등록되어 있습니다.

해결책:

다른 버전을 사용하거나 기존 버전을 업데이트합니다.

오류:

SpecValidationError

원인:

YAML이 스키마를 준수하지 않습니다.

해결책:

필수 필드와 형식을 확인합니다.

오류:

CodeSpecStageNotAccessibleError

원인:

아티팩트에서 참조되는 스테이지에 액세스할 수 없습니다.

해결책:

스테이지에 대한 액세스 권한을 부여하거나 스테이지가 있는지 확인합니다.

오류:

CodeSpecArtifactNotFoundAtStageError

원인:

지정된 스테이지 경로에서 파일을 찾을 수 없습니다.

해결책:

등록하기 전에 스테이지에 파일을 업로드합니다.

오류:

StageDirectoryNotEnabledError

원인:

스테이지에는 DIRECTORY가 활성화되어 있지 않습니다.

해결책:

스테이지에서 디렉터리를 활성화합니다. ALTER STAGE ... SET DIRECTORY = (ENABLE = TRUE)

오류:

CodeSpecNotFoundForOwnerException

원인:

템플릿이 등록되지 않은 코드 번들 사양을 참조합니다.

해결책:

템플릿을 등록하기 전에 코드 번들 사양을 등록합니다.