Snowflake Data Clean Room 마이그레이션 도구

Snowflake Data Clean Room 마이그레이션 도구는 레거시 Provider 및 Consumer 클린룸과 웹앱 클린룸을 Collaboration API로 마이그레이션하도록 도와줘요.

출처: Snowflake Data Clean Room migration tool

본문

기능 — 일반 공개(Generally Available)

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

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

레거시 Provider 및 Consumer 데이터 클린룸은 지원이 중단되고 있어요. 지원 종료 타임라인의 날짜 이전에 마이그레이션 도구를 사용해 Collaboration API로 이동하세요.

Snowflake Data Clean Room 마이그레이션 도구는 레거시 Provider 및 Consumer 클린룸과 웹앱 클린룸을 Collaboration API로 마이그레이션하도록 도와줘요. 레거시 클린룸의 이름을 주면 도구가 템플릿, 데이터셋, 조인 정책, 소비자 같은 구성을 읽고, 동일한 분석 출력을 만들어내는 동등한 Collaboration API 설정을 생성해요. 이 과정에서 원래 클린룸은 절대 수정되거나 제거되지 않아요.

도구는 SQL 워크시트에서 직접 호출할 수 있는 저장 프로시저 집합으로 제공돼요. 선택적으로 Streamlit in Snowflake 앱이 클린룸 마이그레이션용 그래픽 인터페이스를 제공해요.

도구 소스 코드와 릴리스 노트는 Snowflake-Labs/dcr-migration-tool GitHub 저장소를 참고하세요.

요구 사항

마이그레이션 도구를 사용하기 전에 다음을 확인하세요:

SAMOOHA_APP_ROLE 역할 또는 동등한 권한이 있는 역할을 사용하고 있어요.
클린룸이 정상 상태예요: 링크된 데이터셋이 하나 이상, 활성 템플릿이 하나 이상, 참여한 소비자가 하나 이상 있어요.
지원 구성 표를 검토해 클린룸이 마이그레이션 대상인지 확인했어요.

참고

클린룸이 자유 형식 SQL을 사용한다면 마이그레이션 도구가 집계 정책을 만들어야 할 수 있어요. 이 작업에는 ACCOUNTADMIN 권한이 필요해요.

지원 구성

다음 표를 사용해 클린룸이 마이그레이션 대상인지 판단하세요.

참고

2024년 이전(Provider 및 Consumer 모델이 제공되기 전)에 만든 클린룸은 이 도구로 마이그레이션할 수 없어요.

기능	지원 여부	참고
측정(Measurement, Jinja SQL 템플릿)	지원
자유 형식/가로 SQL	제한적 지원	웹앱 포인트앤클릭 인터페이스는 Collaboration API에서 사용할 수 없어요. 워크시트를 사용해 자유 형식 SQL을 실행할 수 있어요.
크로스 클라우드 자동 이행(LAF) 지원	지원
머신러닝을 포함한 Python 작업	지원	사용자가 컴퓨트 풀, ML jobs, SPCS를 요청하지 않는 경우 Python 작업이 지원돼요.
Iceberg 테이블 지원	지원
Snowpark Container Services(SPCS)	미지원	SPCS 서비스 함수를 참조하는 템플릿은 사전 점검(pre-flight)에서 차단돼요.
DCR 관리 계정	지원	관리 계정으로 운영되는 클린룸은 마이그레이션할 수 있지만, 웹앱 사용자 인터페이스는 Collaboration API에서 지원되지 않아요. 자세한 내용은 Snowflake 계정 담당자에게 문의하세요.
Provider 실행 분석	지원	추가 구성 없이 Collaboration API에서 기본적으로 지원돼요.
아이덴티티 커넥터	미지원	아이덴티티 제공자는 표준 콜라보레이션 참여자(데이터 제공자)로 추가할 수 있지만, Collaboration API는 아이덴티티 제공자를 명명된 워크플로 단계로 추가하는 것을 지원하지 않아요.
웹앱 그래픽 사용자 인터페이스	제한적 지원	Data Clean Rooms는 Collaboration API용으로 웹앱과 동등한 네이티브 포인트앤클릭 인터페이스를 제공하지 않아요.
활성화(Activation)	제한적 지원	콜라보레이터의 Snowflake 계정으로의 활성화는 지원돼요. 제3자 대상(예: Google Ads 또는 Meta)으로의 활성화는 아직 지원되지 않아요.
템플릿 체인(Template chains)	미지원
요청 및 활동 로그	미지원	레거시 웹앱의 클린룸별 활동 로그를 의미해요. Collaboration API에서는 사용할 수 없어요.
차등 프라이버시(Differential privacy)	미지원

웹앱 클린룸 마이그레이션

레거시 Snowflake Data Clean Room 웹 애플리케이션("웹앱")은 Provider 및 Consumer 아키텍처로 실행됐지만, 웹앱 사용자 인터페이스는 Collaboration API에서 지원되지 않아요.

일부 웹앱 클린룸은 prod_sql_with_platform_privacy라는 이름의 템플릿을 사용해요. 마이그레이션 도구는 이 템플릿을 감지해 자유 형식 SQL 데이터 오퍼링으로 수동 재구성이 필요하다고 표시해요. 자동으로 변환되지는 않아요.

기존 웹 애플리케이션을 Collaboration API로 마이그레이션하고 싶다면 Streamlit 앱을 사용해 사용자용 포인트앤클릭 인터페이스를 만들 수 있어요. 자세한 내용은 비즈니스 사용자 지원을 참고하세요.

도구 배포

마이그레이션 도구는 Snowflake 계정마다 한 번 배포해요. 항상 Provider 계정에 먼저 배포한 다음 각 Consumer 계정에 배포해요.

백엔드 배포(필수)

Snowflake-Labs/dcr-migration-tool GitHub 저장소에서 migration-backend.sql을 내려받아요.
Snowsight에서 새 SQL 워크시트를 열고 migration-backend.sql의 내용을 실행해요.

참고

나중에 같은 계정에서 또 마이그레이션을 실행한다면 도구를 다시 배포할 필요가 없어요. 배포는 재사용 가능해요.

Streamlit 인터페이스 배포(선택)

Streamlit 앱은 동일한 저장 프로시저에 그래픽 인터페이스를 제공해요. 모든 마이그레이션 작업은 SQL로 직접 수행할 수도 있어요. Streamlit 인터페이스는 Provider와 Consumer 클린룸 마이그레이션을 지원하며, 웹앱 클린룸 마이그레이션은 SQL 워크시트로 실행해야 해요.

Streamlit 앱을 배포하려면:

GitHub 저장소에서 streamlit_app.py를 내려받아요.
Snowsight에서 Streamlit으로 이동해 + Streamlit App을 클릭해요.
앱 이름을 DCR Migration Tool로 지정하고, 데이터베이스를 DCR_SNOWVA, 스키마를 MIGRATION으로 설정한 뒤 streamlit_app.py의 내용을 편집기에 붙여넣고 Create를 클릭해요.

참고

기본적으로 앱 생성자만 앱을 볼 수 있어요. Snowsight의 Share this app을 사용해 다른 사용자에게 접근 권한을 부여하세요.

클린룸 마이그레이션

마이그레이션은 Plan, Execute, Finalize, Validate 네 단계로 진행돼요. 아래 1단계와 5단계가 시작 전 검토 단계와 끝의 선택적 검증 단계로 그 핵심 단계들을 감싸요. 각 단계는 Streamlit 앱에서 탭으로, 저장 프로시저 호출로도 사용할 수 있어요.

1단계: 마이그레이션 대상 클린룸 검토

계정의 클린룸과 마이그레이션 대상 여부를 보려면 다음 명령을 실행하거나 Streamlit 앱을 열어요:

USE ROLE SAMOOHA_APP_ROLE;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PROVIDER.view_cleanrooms();

각 클린룸은 다음 중 하나로 분류돼요:

Eligible: 마이그레이션할 준비가 됨.
Ineligible: 지원되지 않는 구성으로 차단됨. 사유가 표시돼요.
Internal(UUID): 고아 또는 테스트 클린룸. 자동으로 건너뜀.

목록을 검토하고 어떤 클린룸을 마이그레이션할지 결정해요.

2단계: 마이그레이션 계획

Plan 단계는 읽기 전용이에요. 클린룸의 구성을 발견하고, 그것을 Collaboration API YAML 스펙으로 변환하며, 계정을 변경하지 않고 검토용 생성 SQL 스크립트를 반환해요.

도구는 현재 계정이 Provider인지 Consumer인지 자동으로 감지하고 각각에 적절한 스크립트를 생성해요.

Streamlit 앱에서: 클린룸을 선택한 뒤 View Script 탭을 클릭해요.

SQL로:

USE ROLE SAMOOHA_APP_ROLE;

CALL DCR_SNOWVA.MIGRATION.AGENT_MIGRATE_ORCHESTRATOR(
    '<cleanroom_name>',
    'PLAN'
);

출력에는 다음이 포함돼요:

템플릿 YAML 스펙. 템플릿 이름은 자동으로 버전 관리돼요(예: migrated_my_template_2026_04_07_V1).
데이터 오퍼링 YAML 스펙. 점 표기법의 테이블 이름은 밑줄을 사용하도록 변환돼요.
클린룸 토폴로지와 일치하도록 analysis_runners 블록이 구성된 콜라보레이션 스펙.
마이그레이션을 실행하기 전에 해결해야 하는 경고들.

일반적인 경고와 해결 방법:

경고	해결 방법
`ReferenceUsageGrantMissingException`	실행 전에 `ACCOUNTADMIN`으로 다음을 실행하세요: `GRANT REFERENCE_USAGE ON DATABASE <db> TO SHARE <share>;`
소비자 데이터 오퍼링이 비어 있음	소비자가 데이터셋을 링크하고 올바른 조인 정책을 구성했는지 확인하세요.
Provider 실행 분석 감지	소비자도 마이그레이션을 실행하고 자신의 데이터 오퍼링을 링크해야 해요.

3단계: 마이그레이션 실행(Provider 계정)

Execute 단계는 계정에 기록해요. 템플릿과 데이터 오퍼링을 등록한 다음 새 클린룸을 초기화해요. 이 작업은 멱등적이에요. 중단돼도 다시 실행하는 것이 안전해요.

Streamlit 앱에서: Execute Migration 탭을 클릭하고 확인해요.

SQL로:

USE ROLE SAMOOHA_APP_ROLE;

CALL DCR_SNOWVA.MIGRATION.AGENT_MIGRATE_ORCHESTRATOR(
    '<cleanroom_name>',
    'EXECUTE'
);

실행 중에 도구는:

각 템플릿에 대해 REGISTRY.REGISTER_TEMPLATE을 호출해요.
각 데이터셋에 대해 REGISTRY.REGISTER_DATA_OFFERING을 호출해요.
REGISTRY.VIEW_REGISTERED_TEMPLATES에서 시스템 생성 리소스 ID를 가져와요.
권위 있는 ID로 콜라보레이션 스펙을 재생성해요.
COLLABORATION.INITIALIZE를 호출해 새 클린룸을 만들어요.
상태를 폴링하고 CREATED가 될 때까지 기다린 뒤 COLLABORATION.JOIN을 호출해요.

4단계: 완료 — 소비자가 콜라보레이션에 참여

Provider가 마이그레이션을 실행한 뒤에는 각 Consumer 계정도 도구를 배포하고 마이그레이션 단계를 실행해야 해요. Consumer는 자신의 계정에서 같은 클린룸 이름으로 동일한 Plan → Execute 흐름을 실행해요.

중요

JOIN 명령에는 SYSTEM$ACCEPT_LEGAL_TERMS가 필요하며, Streamlit 앱 안에서는 실행할 수 없어요. Streamlit 인터페이스를 사용하든 SQL을 직접 실행하든, 생성된 JOIN 스크립트를 복사해 Snowflake SQL 워크시트에서 실행해야 해요. Streamlit 앱은 Finalize 탭에 붙여 넣을 준비가 된 스니펫을 제공해요.

Consumer 마이그레이션:

Consumer 계정 컨텍스트에서 사전 요구 사항을 확인해요.
Consumer 측 메타데이터(데이터 오퍼링, 조인 정책, 컬럼 정책)를 읽어요.
Consumer 측 콜라보레이션 스펙을 생성해요.
COLLABORATION.JOIN을 호출해 새 클린룸에 참여해요.
link_data_offering으로 소비자 데이터 오퍼링을 Provider 계정에 링크해요.

5단계: 검증

Validate 단계는 마이그레이션된 콜라보레이션이 원래 클린룸과 동등한지 확인해요.

Streamlit 앱에서: Validate 탭을 클릭해요.

SQL로:

USE ROLE SAMOOHA_APP_ROLE;

CALL DCR_SNOWVA.MIGRATION.AGENT_MIGRATE_ORCHESTRATOR(
    '<cleanroom_name>',
    'VALIDATE'
);

검증 확인 항목:

콜라보레이션 상태가 CREATED(Provider) 또는 JOINED(Consumer).
템플릿 수가 레거시 클린룸과 일치.
데이터 오퍼링 수가 일치.
소비자 수가 일치.

검증이 통과해도 원래 클린룸은 그대로 있어요. 새 콜라보레이션에 대해 파이프라인이 올바르게 실행되고 있는지 확인하기 전까지는 원래 클린룸을 삭제하지 마세요.

마이그레이션 롤백

마이그레이션을 취소하려면 TEARDOWN 모드를 사용해요. 이것은 마이그레이션된 콜라보레이션만 제거해요. 원래 클린룸은 영향을 받지 않아요.

Streamlit 앱에서: Undo 탭을 클릭해요.

SQL로:

USE ROLE SAMOOHA_APP_ROLE;

CALL DCR_SNOWVA.MIGRATION.AGENT_MIGRATE_ORCHESTRATOR(
    '<cleanroom_name>',
    'TEARDOWN'
);

참고

Teardown은 2단계 비동기 프로세스예요. 프로시저는 상태가 LOCAL_DROP_PENDING이 될 때까지 GET_STATUS를 폴링한 다음, 작업을 완료하기 위해 TEARDOWN을 두 번째 호출해요.

마이그레이션 기록 보기

도구가 수행하는 모든 작업은 DCR_SNOWVA.MIGRATION.MIGRATION_JOBS 테이블에 기록돼요. 이 테이블을 언제든지 쿼리해 마이그레이션 활동을 감사할 수 있어요.

컬럼	설명
`JOB_ID`	이 작업의 고유 식별자.
`CLEANROOM_NAME`	소스 클린룸 이름.
`ACTION`	실행된 모드: `PLAN`, `EXECUTE`, `VALIDATE`, `TEARDOWN`.
`ROLE`	실행 중 사용된 역할.
`STARTED_AT` / `FINISHED_AT`	실행 타임스탬프.
`STATUS`	`SUCCESS` 또는 `FAILED`.
`DETAILS`	결과 JSON의 처음 4,000자.

Streamlit 앱에서 Migrated DCRs를 클릭하면 이 계정에서 실행된 모든 마이그레이션의 접을 수 있는 요약과 각 클린룸의 실시간 상태·전체 기록을 볼 수 있어요.

문제 해결

CleanroomNotInstalled 오류

클린룸 이름이 틀렸거나 잘못된 계정을 사용하고 있어요. 사용 가능한 클린룸을 나열해 정확한 이름을 확인하세요:

USE ROLE SAMOOHA_APP_ROLE;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PROVIDER.view_cleanrooms();

사전 점검 실패: 다중 제공자 구성 감지

다중 제공자 클린룸은 이 릴리스에서 지원되지 않아요. 솔루션 엔지니어에게 문의해 옵션을 논의하거나, 대상이 되는 단일 제공자 클린룸으로 진행하세요.

마이그레이션 후 분석 출력이 일치하지 않음

클린룸이 Provider 실행 분석을 사용했을 때 발생할 수 있어요. Provider 및 Consumer 아키텍처에서 source_table은 항상 Provider의 테이블을 참조했지만, Collaboration API에서는 이 매핑이 뒤집힐 수 있어요. Plan 모드에서 생성된 템플릿 YAML을 검토하고 source_table과 my_table을 바꿔야 하는지 확인하세요.

REFERENCE_USAGE 부여 누락

콜라보레이션에 참여할 때 missing reference usage grant 오류가 보이면 ACCOUNTADMIN으로 다음을 실행하세요:

GRANT REFERENCE_USAGE ON DATABASE <provider_database> TO SHARE <collab_share>;

자세한 내용은 Collaboration Data Clean Rooms 문제 해결을 참고하세요.

비즈니스 사용자 지원

레거시 웹앱은 사용자가 SQL을 작성하지 않고도 분석을 실행할 수 있게 해주는 포인트앤클릭 인터페이스를 제공했어요. Collaboration API는 현재 Snowflake 인터페이스에서 레거시 웹앱과 완전한 기능 동등성을 갖고 있지 않아요.

오늘 Collaboration API를 사용해야 하면서 포인트앤클릭 인터페이스를 지원해야 한다면, 사용자 워크플로에 맞게 설계된 목적별 UI에서 Collaboration API 호출을 감싸는 Streamlit in Snowflake 앱을 만들 수 있어요. Streamlit 앱은 비즈니스 사용자에게 필요한 분석(예: 오디언스 중복, 도달 및 빈도)을 정확히 노출할 수 있고 SQL을 작성하지 않아도 돼요.

Snowflake SE 팀이 워크플로에 맞는 Streamlit 앱 설계·구축을 도와줄 수 있어요. 자세한 내용은 Snowflake 계정 담당자에게 문의하세요.

Streamlit 앱 구축을 시작하려면:

Streamlit in Snowflake 소개: 아키텍처, 지원 라이브러리, 보안 모델.
Streamlit 앱 만들기: Snowsight에서 Streamlit 앱을 만들고, 편집하고, 공유하는 방법.

Snowflake Data Clean Room 마이그레이션 도구