코드 스펙(Code specification)

템플릿이 호출할 수 있는 하나 이상의 코드 함수, 프로시저, 또는 ML Jobs를 정의하는 스펙이에요.

출처: 문서

본문

기능 — 일반 공개(Generally Available)

현재 지원 리전: 이 리전들에서 사용할 수 있어요.

정부 및 VPS 배포에서는 사용할 수 없어요.

이 코드 스펙은 템플릿이 호출할 수 있는 하나 이상의 코드 함수, 프로시저, 또는 ML Jobs를 정의해요.

코드 스펙은 최대 5개의 ML job과, 함수와 프로시저를 합쳐 최대 5개까지 포함할 수 있어요. ml_jobs, functions, procedures 중 최소 하나는 정의되어야 해요.

다양한 종류의 코드 스펙 예시는 예시 스펙을 참고하세요.

코드 스펙의 식별자에는 다음과 같은 일반 요구 사항이 있어요:

이름: 문자로 시작하고 영숫자 문자와 밑줄만 포함하는 유효한 Snowflake 식별자여야 해요.
따옴표로 묶인 식별자: 특수 문자가 있는 이름은 큰따옴표로 묶인 식별자가 지원돼요.
대소문자 구분: 따옴표 없는 식별자는 대소문자를 구분하지 않고, 따옴표로 묶인 식별자는 대소문자를 보존해요.

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 spec.
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 or ML jobs 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 or ML jobs defined
  - name: <identifier>          # One or more procedure items...
    language: PYTHON            # Required: Currently only PYTHON supported
    runtime_version: <python_version>  # Optional: Python runtime version (3.10 - 3.14)
    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.

ml_jobs:                        # Required if no functions or procedures defined
  - name: <identifier>          # One or more ML job items...
    entrypoint: <script.py>     # Required: Python script (.py) to run
    stage_code_dir: <stage_path> # Required: Stage directory containing the code
    pip_requirements:           # Optional: pip packages to install
      - <package_spec>          # One or more package items...
    description: <description_text> # Optional: Description (max 1,000 chars)
    allow_monitoring: <boolean> # Optional: Allow log monitoring (default: false)
    image_tag: <tag>            # Optional: Container image version (max 64 chars)

api_version — 사용된 Collaboration API 버전이에요. 2.0.0이어야 해요.
spec_type — 스펙 유형 식별자예요. code_spec이어야 해요.
name: identifier — 이 레지스트리 안에서 이 코드 스펙의 고유한 이름이에요. 최대 75자의 유효한 Snowflake 식별자여야 해요. 템플릿에서 함수를 호출할 때 마지막 이름 세그먼트로 사용돼요: cleanroom.code_spec_name$function_name.
version: version_id — 커스텀 버전 식별자예요. 밑줄을 포함한 영숫자여야 하고 최대 20자예요.
description: description_text(선택) — 코드 스펙 설명이에요(최대 1,000자).
artifacts(선택) — 함수나 프로시저가 가져올 수 있는 스테이징된 파일 또는 패키지 목록이에요. 핸들러 함수를 통해 선택적으로 노출될 수 있어요. 스펙당 최대 5개.
- alias: identifier — imports에서 이 아티팩트를 참조하기 위한 별칭이에요. 이 스펙 안에서 이 별칭을 참조할 때는 cleanroom.spec_name$alias가 아니라 별칭 이름을 그대로 사용해요.
- stage_path: stage_path — 아티팩트 파일의 전체 스테이지 경로예요. 예: @DB.SCHEMA.STAGE/path/file.whl.
  - 스테이지는 내부여야 해요. 외부 스테이지는 지원되지 않아요.
  - 스테이지에 DIRECTORY가 활성화되어 있어야 해요: 아티팩트를 포함하는 스테이지는 DIRECTORY = (ENABLE = TRUE)가 설정되어 있어야 해요.
  - 스테이지 경로 형식: @[DB.]SCHEMA.STAGE/path/to/file.ext 형식을 따라야 해요.
  - 경로 순회 금지: 스테이지 경로는 .. 또는 \를 포함할 수 없어요.
  - 이 아티팩트는 존재해야 해요: 코드 스펙이 등록될 때 지정된 스테이지 경로에 파일이 존재해야 해요.
  - 스테이지는 SNOWFLAKE_SSE 서버 측 암호화가 활성화되어 있어야 해요. 스테이지를 만들거나 변경할 때 ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')를 설정해요.
  - 스테이징된 코드 파일을 push·삭제·업데이트했다면 ALTER STAGE {stage name} REFRESH를 호출해 콜라보레이션이 스테이지의 최신 정보를 갖도록 해야 해요. 코드 업데이트는 코드 스펙을 등록하기 전에만 지원돼요. 등록 시 버전이 배정되고 해시 체크섬이 계산되기 때문이에요.
- description: description_text(선택) — 아티팩트 설명이에요(최대 500자).
- content_hash: sha256_hash(선택) — 무결성 검증을 위한 소문자 SHA-256 해시예요(64자 16진수).
functions(프로시저나 ML job이 없으면 필수) — UDF 또는 UDTF 정의 목록이에요.
- name: identifier — 호출 템플릿에 노출할 함수 이름이에요. 유효한 Snowflake 식별자여야 해요.
- type — 함수 유형이에요. UDF 또는 UDTF 중 하나예요.
- language — 함수 언어예요. 현재 PYTHON만 지원돼요.
- runtime_version: python_version(선택) — 사용할 Python 런타임 버전이에요. 지원 버전: 3.10~3.14.
- handler: handler — name이 호출될 때 호출할 함수 코드의 핸들러 함수 이름이에요.
- arguments(선택) — 이름-유형 쌍 목록의 함수 인자예요. 유형은 유효한 Snowflake SQL 유형이어야 해요.
- returns: sql_type — 반환 유형이에요. UDF는 STRING이나 FLOAT 같은 SQL 유형을 사용하고, UDTF는 TABLE(column_definitions)를 사용해요.
- packages(선택) — 이 코드가 사용하는 패키지 목록이에요. 이 Anaconda Python 패키지들 또는 이 Snowpark API 패키지들 중 무엇이든 될 수 있어요. 예: snowflake-snowpark-python, numpy.
- imports(선택) — 가져올 아티팩트 목록이에요. 이 스펙의 artifacts 목록에 있는 별칭이어야 해요.
- code_body(선택) — 인라인 Python 코드예요. 스테이징된 imports와 상호 배타적이에요. 최대 크기는 12MB예요.
- description: description_text(선택) — 함수 설명이에요(최대 500자).
procedures(함수나 ML job이 없으면 필수) — 저장 프로시저 정의 목록이에요. 필드는 functions와 비슷하지만 type 필드가 없어요.
ml_jobs(함수나 프로시저가 없으면 필수) — ML job 정의 목록이에요. 코드 스펙당 최대 5개의 ML job. 이 제한은 함수·프로시저 제한(역시 5)과 독립적이에요. 함수와 프로시저와 달리 ML job은 컴퓨트 풀의 격리된 컨테이너에서 실행돼서 GPU 가속, 분산 학습, 임의 pip 패키지, 장시간 비동기 실행이 가능해요.

자세한 내용은 Data Clean Rooms의 ML Jobs를 참고하세요.
- name: identifier — ML job 이름이에요. 최대 255자의 유효한 Snowflake 식별자여야 해요. 대소문자를 구분하지 않고 코드 스펙 안에서 고유해야 해요. 이 이름은 템플릿 호출 패턴에 사용돼요: cleanroom.code_spec_name$ml_job_name(compute_pool, num_instances, warehouse, args_json).
- entrypoint: script.py — 엔트리 포인트로 실행할 Python 파일이에요. .py 파일(대소문자 구분)이어야 해요. 예: train.py 또는 run_pipeline.py. module.function 같은 모듈 경로 표기는 지원되지 않아요. 엔트리 포인트는 항상 Python 파일이어야 해요.
- stage_code_dir: stage_path — 실행할 Python 코드가 들어 있는 스테이지 디렉토리예요. @DB.SCHEMA.STAGE/path 형식을 따르고 파일이 아니라 디렉토리를 가리켜야 해요.
  - 스테이지는 내부여야 해요. 외부 스테이지는 지원되지 않아요.
  - 스테이지에 DIRECTORY가 활성화되어 있어야 해요: 스테이지를 만들 때 DIRECTORY = (ENABLE = TRUE)를 설정해요.
  - 스테이지에 SNOWFLAKE_SSE 암호화가 활성화되어 있어야 해요: 스테이지를 만들 때 ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')를 설정해요.
  - 경로 순회 금지: 스테이지 경로는 .. 또는 백슬래시를 포함할 수 없어요.
  - 압축 없이 파일 업로드: PUT으로 파일을 업로드할 때 AUTO_COMPRESS = FALSE를 설정해 파일이 그대로 저장되게 해요. 압축 업로드는 파일 이름과 내용을 바꿔서 엔트리 포인트와 무결성 검증을 깨뜨려요.
  - 파일 업로드 후 디렉토리 새로 고침: 파일을 업로드하거나 업데이트한 뒤 ALTER STAGE stage_name REFRESH를 호출해요. 콜라보레이션은 디렉토리 뷰를 사용해 스테이징된 코드에 접근해요. 새로 고침 없이는 새로 업로드된 파일이 콜라보레이션에 보이지 않고 생성이 중단될 수 있어요.
  - 지원 콘텐츠: 디렉토리는 Python 스크립트(.py), wheel 패키지(.whl), JAR 파일(.jar), 공유 라이브러리(.so), 아카이브 파일(.zip, .tar.gz), 구성 파일(.json, .yaml), 직렬화된 모델 아티팩트(.pkl, .joblib)를 포함한 모든 파일 유형을 포함할 수 있어요. 중첩 하위 디렉토리가 지원돼요. entrypoint 파일만 .py 스크립트여야 해요.
  - 디렉토리당 최대 500개 파일: stage_code_dir은 최대 500개 파일(하위 디렉토리의 모든 파일 포함)을 포함할 수 있어요. 이 제한을 초과하면 등록이 실패해요.
  - 총 디렉토리 크기: stage_code_dir의 결합 크기를 약 2GB 미만으로 유지해요.
  - 무결성 검증: 등록 시 시스템이 디렉토리의 모든 파일에 SHA-256 해시를 계산해요. 콜라보레이션이 코드를 로드할 때 모든 해시를 재검증해요. 등록 이후 어떤 파일이 수정·추가·제거되었다면 템플릿 요청이 실패해요. 스테이징된 파일을 수정한 뒤에는 코드 스펙을 재등록하세요.
참고

2026년 6월 18일 릴리스(Clean Rooms API 버전 16.3) 이전에 등록된 ML Jobs 코드 스펙은 콘텐츠 해시가 없어 콜라보레이션에 추가할 수 없어요. 해결 단계는 ML Jobs 문제 해결을 참고하세요.
- pip_requirements(선택) — 런타임에 컨테이너에 설치할 pip 패키지 요구 사항 목록이에요. 예: scikit-learn>=1.0, xgboost, pandas. 함수·프로시저 코드 스펙과 달리 ML job은 Anaconda 승인 번들이 아니라 pip으로 설치 가능한 모든 패키지를 사용할 수 있어요.
- description: description_text(선택) — ML job 설명이에요(최대 1,000자).
- allow_monitoring: boolean(선택) — 분석 실행자가 이 ML job의 컨테이너 로그를 볼 수 있는지 여부예요. 기본값: false.
- image_tag: tag(선택) — 사용할 ML 런타임 이미지 버전이에요. 최대 64자. 생략하면 콜라보레이션은 코드 스펙이 콜라보레이션에 추가될 때 해석되는 최신 사용 가능한 런타임 이미지를 사용해요. 새 런타임 버전이 릴리스되면 기본 이미지가 업데이트돼요. 코드 스펙이 알려진 사전 설치 라이브러리 집합과 런타임 동작으로 실행되도록 image_tag를 특정 버전으로 고정하는 것을 권장해요. 고정된 모든 버전은 패치 전체에서 변경 없이 보존돼요.

다음 예시는 두 개의 ML job이 있는 코드 스펙을 등록해요:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_CODE_SPEC(
$$
api_version: 2.0.0
spec_type: code_spec
name: my_ml_model
version: V0
ml_jobs:
  - name: my_train_job
    entrypoint: train.py
    stage_code_dir: '@MY_DB.PUBLIC.MY_STAGE/ml_project'
    image_tag: "2.9.0"
    pip_requirements:
      - pandas
      - xgboost
      - scikit-learn
  - name: my_score_job
    entrypoint: score.py
    stage_code_dir: '@MY_DB.PUBLIC.MY_STAGE/ml_project'
    image_tag: "2.9.0"
    pip_requirements:
      - pandas
      - xgboost
      - scikit-learn
$$);

ML Jobs 코드 스펙을 참조하는 템플릿은 cleanroom.<code_spec_name>$<ml_job_name>(compute_pool, num_instances, warehouse, args_json) 패턴을 사용해 생성된 프로시저를 호출해요.

코드 스펙(Code specification)

코드 스펙(Code specification)

본문

더 알아보기