Snowflake Data Clean Rooms 개발자 안내

Snowflake Data Clean Rooms를 프로그래밍 방식으로 만들거나 관리하려는 사용자를 위한 지침을 제공해요.

출처: Snowflake Data Clean Rooms developer's guide

본문

지원 종료(EOL) 공지

레거시 Provider 및 Consumer 데이터 클린룸은 지원이 중단되고 있어요. 날짜와 마이그레이션 지침은 지원 종료 타임라인을 참고하세요.

이 항목은 Snowflake Data Clean Rooms를 프로그래밍 방식으로 만들거나 관리하려는 사용자에게 지침을 제공해요.

Snowflake는 클린룸을 만들고 제어하기 위한 저장 프로시저 API를 노출해요. 이 저장 프로시저는 클린룸 환경과 연결된 Snowflake 계정에 접근할 수 있는 모든 인터페이스(Snowsight 노트북·워크시트, Snowflake CLI 포함)에서 실행할 수 있어요. 이 프로시저는 SQL 또는 Snowflake 환경이 지원하는 모든 언어로 호출할 수 있어요.

환경 설정

클린룸 API를 효과적으로 사용하기 위한 코딩 환경 설정 팁이에요.

개발 도구
코딩 설정
계정, 사용자, 역할 설정
클린룸 환경으로 설치된 것 확인
샘플 데이터

개발 도구

클린룸의 주요 개발자 도구는 다음과 같아요:

코딩 환경: Snowflake 계정에서 저장 프로시저를 실행할 수 있는 모든 코딩 환경이 작동해요. 대부분의 개발자는 Snowsight(브라우저 기반 도구)의 워크시트나 Snowflake CLI를 사용해요.
클린룸 UI: 클린룸을 구성·관리·생성하려면 클린룸 UI를 사용해요. 대부분의 클린룸 분석가는 코드보다 UI를 사용하므로, 클린룸의 경험을 UI에서 보고 테스트하는 것이 중요해요. 또한 클린룸 UI에서만 사용할 수 있는 몇 가지 기능이 있어요.
Snowsight: 데이터베이스와 다른 객체를 탐색하고 객체를 검색하는 데 유용해요.
클린룸 API: API 문서는 provider와 consumer 항목 페이지로 나뉘어 있어요.

코딩 설정

클린룸용 코딩 환경을 설정하는 방법은 다음과 같아요:

필수 역할과 웨어하우스
클린룸 API에 대해
API 프로시저의 클린룸 이름에 대해

필수 역할과 웨어하우스

클린룸 API는 전체 API 접근을 위해 SAMOOHA_APP_ROLE 역할이 필요해요. 클린룸 관리자에게 전체 API 접근을 부여해 달라고 요청하세요. 클린룸은 또한 API 프로시저의 하위 집합에 접근할 수 있는 역할 생성을 지원해요.

SAMOOHA_APP_ROLE이 사용할 수 있는 웨어하우스에서 클린룸 API를 사용해야 해요. app_wh는 API에 접근할 수 있는 여러 웨어하우스 중 하나예요. 필요에 맞는 적절한 웨어하우스를 선택하세요.

일반적인 클린룸 편집·생성·삭제 명령에는 XS 웨어하우스를 사용하는 것을 권장해요. 머신러닝 워크로드 같은 대형 분석을 실행할 때는 더 큰 웨어하우스나 Snowpark 최적화 웨어하우스를 사용하는 것을 고려하세요.

-- Set up environment.
USE ROLE SAMOOHA_APP_ROLE;
USE WAREHOUSE app_wh;

-- Call your clean rooms API functions.
...

다른 웨어하우스를 사용한다면 SAMOOHA_APP_ROLE에 그 웨어하우스 usage를 부여해야 해요:

GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;

클린룸 API에 대해

Snowflake Data Clean Rooms는 제공자가 클린룸을 만들고, 구성하고, 공유할 수 있게 해주는 저장 프로시저 집합을 노출해요. 이 프로시저는 노트북, 워크시트, Snowflake CLI를 포함해 Snowflake 프로시저를 지원하는 모든 명령줄 환경에서 호출할 수 있어요. 여기 문서는 SQL 사용을 보여주지만, Python이나 다른 지원되는 Snowflake 언어도 사용할 수 있어요.

프로시저는 다음 스키마 안에 존재해요:

samooha_by_snowflake_local_db.provider — Provider 특정 프로시저. 이 프로시저는 현재 계정에서 만들어진 클린룸에서만 호출할 수 있어요.
samooha_by_snowflake_local_db.consumer — Consumer 특정 프로시저. 이 프로시저는 현재 계정이 소비자로 초대된 클린룸에서만 호출할 수 있어요.
samooha_by_snowflake_local_db.library — 클린룸 생성자(제공자) 또는 클린룸 콜라보레이터(소비자)가 호출하는 일반 프로시저. 이 프로시저는 provider 및 consumer 참조 페이지 양쪽에 문서화돼 있어요.

일부 프로시저는 provider와 consumer 버전이 모두 있어요. 결과는 스키마에 적합해요. 예를 들어 provider.view_cleanrooms는 현재 계정에서 자신이 제공자인 모든 클린룸을 나열하고, consumer.view_cleanrooms는 현재 계정에서 자신이 소비자인 모든 클린룸을 나열해요. 필요한 네임스페이스에서 프로시저를 호출하는지 확인하세요.

API 프로시저의 클린룸 이름에 대해

많은 클린룸 API 프로시저는 cleanroom_name 인자를 받아요.

API로 만든 클린룸이라면 클린룸 이름을 사용해요. 패키지 이름의 일부로 사용되는 경우 공백을 밑줄로 바꿔요:

-- Spaces work here:
CALL samooha_by_snowflake_local_db.provider.describe_cleanroom('my code created clean room');

-- Underscores required here:
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_my_code_created_clean_room;

클린룸 UI로 만든 클린룸이라면 클린룸 ID를 사용해요.

describe_cleanroom 또는 view_cleanrooms를 호출하면 클린룸 이름과 ID를 볼 수 있어요.

API로 만든 클린룸은 클린룸 UI에서 Supported with Developer APIs로 표시돼요.

계정, 사용자, 역할 설정

클린룸을 개발하는 데 클린룸 UI를 사용할 필요는 없어요. 대부분의 클린룸 기능은 API를 호출해 사용할 수 있어요. 하지만 UI에서만 사용할 수 있는 몇 가지 기능이 있고, 일부는 UI에서 더 빠르게 수행돼요. 그리고 많은 사용자가 UI만 사용하므로 클린룸이 UI에서 어떻게 동작하는지 보는 것이 중요해요. 따라서 클린룸 관리자에게 적절한 클린룸 계정에서 클린룸 매니저 이상으로 추가해 달라고 요청해야 해요.

사용 사례에 따라 다른 웹 호스팅 리전에 추가 Snowflake 계정을 설정해 크로스 클라우드 동작을 테스트하고 싶을 수도 있어요.

테스트 Snowflake 계정 이름을 일반적인 용도를 나타내도록 의미 있게 지으세요. 예: "Consumer account", "Provider account", "Cross-cloud account". 테스트 계정이 여러 개 있고 클린룸 로그인 페이지에서 계정을 선택해야 할 때 도움이 돼요.

내부 테스트 클린룸

개발 중에 클린룸을 자신과 공유해 테스트할 수 있어요. 이러한 클린룸을 내부 테스트 클린룸(internal testing clean room)이라고 해요. 제공자와 소비자 모두에 단일 계정을 사용하는 것은 빠른 기능 테스트에 편리해요.

내부 테스트 클린룸을 만들려면 provider.add_consumers에 유일한 소비자로 제공자 계정 정보를 전달하기만 하면 돼요.

내부 테스트 클린룸에는 다음 제한이 있어요:

내부 테스트 클린룸은 나중에 다른 계정과 공유할 수 없어요. 내부 테스트 클린룸은 항상 내부 테스트 클린룸이에요.
내부 테스트 클린룸에서 지원되지 않는 기능은 다음과 같아요:
- Provider 활성화
- Provider 실행 분석
- 요청 로그 마운트 또는 보기(provider.mount_request_logs_for_all_consumers 또는 provider.view_request_logs)
- Consumer 정의 템플릿
- 다중 제공자 분석
- 차등 프라이버시

내부 테스트 룸에서 지원되지 않는 기능을 테스트하려면 클린룸 양쪽을 테스트하기 위해 별도의 provider 및 consumer Snowflake 계정을 설정해야 해요.

단일 계정을 provider와 consumer 모두에 사용해 클린룸을 사용하는 방법을 보여주는 샘플 워크시트를 내려받아 보세요.

클린룸 환경으로 설치된 것 확인

Snowflake Data Clean Rooms는 설치 시 많은 로컬 데이터베이스를 만들어요. 클린룸 패키지로 실행되거나 설치되는 태스크와 객체에 대한 세부 사항은 Snowflake Data Clean Rooms: 설치된 객체에서 찾을 수 있어요.

샘플 데이터

클린룸 환경은 사용할 수 있는 몇 가지 샘플 데이터셋을 설치해요.

Snowflake를 사용해 합성 테스트 데이터를 생성할 수도 있어요.

지침 및 권장 사항

클린룸으로 작업할 때 문제를 피하기 위한 몇 가지 지침이에요:

클린룸 UI와 코드에서 같은 계정을 사용하고 있는지 확인
클린룸 이름 vs 클린룸 ID
UI를 변경할 때마다 클린룸 업데이트
코드 또는 UI로 만든 클린룸 간 상호 운용성

클린룸 UI와 코드에서 같은 계정을 사용하고 있는지 확인

같은 Snowflake 계정에 대해 코딩 환경과 클린룸 UI를 모두 열어야 하는 경우가 자주 있어요. 예를 들어 코드로 클린룸을 만든 다음 클린룸 UI에서 그 모양을 확인하는 경우가 그렇죠. 각각에서 같은 Snowflake 계정을 사용하고 있는지 확인하는 것이 중요해요.

Snowsight에는 같은 계정의 클린룸 UI를 여는 단축키가 없으므로(반대도 마찬가지), 각 환경에서 같은 계정에 로그인했는지 확인해야 해요.

클린룸 이름 vs 클린룸 ID

API를 사용할 때 클린룸 이름 인자를 받는 프로시저에 대해 클린룸 이름 또는 클린룸 ID를 다음과 같이 결정해요:

API로 만든 클린룸이라면 클린룸 이름을 사용해요.
클린룸 UI에서 만든 클린룸이라면 클린룸 ID를 사용해요. provider.view_cleanrooms 또는 provider.describe_cleanroom을 호출하면 클린룸 이름과 ID를 모두 볼 수 있어요.

UI를 변경할 때마다 클린룸 업데이트

UI에 영향을 주는 클린룸 속성을 변경할 때마다 provider.create_or_update_cleanroom_listing을 호출해 변경 사항을 전파하세요.

코드 또는 UI로 만든 클린룸 간 상호 운용성

API로 클린룸을 만들면 일부 기능은 클린룸 UI에서 수정할 수 없어요. 예를 들어 UI로 만든 클린룸에 코드로 추가 템플릿(심지어 기본 Snowflake 템플릿조차)을 추가할 수 없어요. 차등 프라이버시 설정도 변경할 수 없어요.

문제 해결

일반적인 문제 해결 팁은 다음과 같아요:

소비자가 참여한 클린룸에서 조인 정책이나 다른 기본 작업을 설정할 수 없음
만든 클린룸을 찾을 수 없음
알 수 없는 함수
사용자가 클린룸을 설치했는지 확인
쿼리 또는 분석 기록 확인

소비자가 참여한 클린룸에서 조인 정책이나 다른 기본 작업을 설정할 수 없음

적절한 역할(SAMOOHA_APP_ROLE)로 클린룸을 설치했는지 확인하세요. 클린룸을 설치할 때 SAMOOHA_APP_ROLE을 사용하지 않았다면 일반적으로 권한 오류인 많은 문제가 발생할 거예요. 이런 경우 consumer.uninstall_cleanroom도 실패하고, 클린룸을 제거한 뒤 올바른 역할로 다시 설치하는 추가 단계를 거쳐야 해요.

-- Who owns the clean room?
SHOW SHARES LIKE 'SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>';

-- If the owner role is not SAMOOHA_APP_ROLE, you must drop the share, then
-- uninstall the clean room.
DROP SHARE SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
USE ROLE SAMOOHA_APP_ROLE;
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<provider_locator>');

만든 클린룸을 찾을 수 없음

한 계정에서 클린룸을 만들었는데 콜라보레이터 계정에서 볼 수 없다면 가능한 이유는 다음과 같아요:

클린룸이 다른 클라우드 호스팅 리전에서 만들어졌고 크로스 클라우드 자동 이행을 활성화하지 않았어요.
provider.create_or_update_cleanroom_listing을 호출해 클린룸을 게시하지 않았어요.
consumer.view_cleanrooms()을 호출 중인데 provider.view_cleanrooms()여야 하거나(또는 반대), 그 반대예요.
클린룸을 공유하지 않았거나, 잘못된 계정과 공유했거나, Snowsight/클린룸 UI/CLI에서 잘못된 콜라보레이터 계정을 열었어요. 클린룸이 보이길 기대하는 계정이 클린룸을 공유한 계정인지, 그 공유된 계정에 로그인했는지 확인하세요.
클린룸을 게시하고 콜라보레이터에게 보이기까지 약간의 지연이 있어요.

알 수 없는 함수

프로시저를 호출했는데 다음 스니펫과 같은 오류가 나오면:

Unknown user-defined function SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.<procedure name>

가능한 원인이 몇 가지 있어요:

잘못된 네임스페이스를 입력했어요. 프로시저의 올바른 consumer 또는 provider 버전을 호출해야 해요. 많은 프로시저는 provider와 consumer 버전이 모두 있어요.
함수 이름을 잘못 입력했어요. 올바른 이름은 참조 안내를 확인하세요.
제한된 접근 실행 역할이 부여되었고, 호출한 함수가 역할에 허용되지 않아요. 다음 SQL 코드를 실행해 테스트하세요:

USE DATABASE samooha_by_snowflake_local_db;
CALL IS_DATABASE_ROLE_IN_SESSION('samooha_run_role');

코드 스니펫이 TRUE를 반환하면 클린룸 API에 제한된 접근 실행 역할 권한이 있는 거예요. 더 큰 접근이 필요하면 클린룸 관리자에게 전체 접근을 요청하세요. 허용된 실행 역할 프로시저 목록은 consumer.grant_run_on_cleanrooms_to_role 문서에서 확인하세요.

SAMOOHA_APP_ROLE이 없어요. SAMOOHA_APP_ROLE을 사용할 수 있는지 보려면 다음 명령을 실행해요:

-- Get current user name.
SELECT current_user();

-- Add current user name in place as indicated.
SHOW GRANTS TO USER <current_user_name> ->> select * from $1 where "role" = 'SAMOOHA_APP_ROLE';

결과가 없으면 관리자에게 클린룸 API 접근을 요청하세요.

사용자가 클린룸을 설치했는지 확인

주어진 사용자가 주어진 클린룸을 설치했는지 다음 SQL 코드로 확인할 수 있어요. $consumer_locator와 $cleanroom_name을 소비자 로케이터와 클린룸 이름으로 바꾸세요.

SELECT * FROM snowflake.data_sharing_usage.application_state
  WHERE consumer_account_locator = $consumer_locator
    AND CONTAINS(package_name, UPPER(REPLACE($cleanroom_name, ' ', '_')));

쿼리 또는 분석 기록 확인

UI 또는 코드에서 실행한 분석의 쿼리 기록을 볼 수 있어요. 이 기록들은 별도로 저장되고 확인돼요.

UI 분석 기록

클린룸 UI는 Analyses & Queries 페이지에 이 계정의 모든 이전 분석 목록을 보여줘요. 이 결과는 UI에서 실행한 쿼리만 해당돼요.

클린룸을 수정하거나 삭제하면, 다음 템플릿 중 하나를 사용하지 않는 한 UI의 그 클린룸 분석 보고서가 삭제돼요:

Audience Overlap & Segmentation
SQL Query
커스텀 템플릿

위에 나열된 템플릿의 쿼리 기록은 클린룸이 수정되거나 삭제되어도 유지돼요.

API 쿼리 기록

템플릿 분석을 포함해 API로 실행된 모든 호출의 계정 기록을 보려면:

Snowsight에 로그인해요.
탐색 메뉴에서 Monitoring » Query History를 선택해요.
필터를 사용해 분석과 연결된 쿼리를 찾고 쿼리 또는 분석을 선택해요.

확장 예시

Developer API의 다양한 기능 사용을 이해하려면 클린룸 문서의 Use cases 및 Features 섹션의 예시를 참조할 수 있어요.

Snowflake Data Clean Rooms 개발자 안내