Snowflake Data Clean Rooms 개발자 가이드예요

Snowflake Data Clean Rooms 개발자 가이드예요

지원 종료 공지

레거시 Provider 및 Consumer Data Clean Rooms는 지원이 중단될 예정이에요. 날짜와 마이그레이션 지침은 end-of-life timeline에서 확인할 수 있어요.

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

Snowflake는 clean rooms을 생성하고 제어하기 위한 저장 프로시저 API를 제공해요. 이러한 저장 프로시저는 clean room 환경과 연결된 Snowflake 계정에 액세스할 수 있는 모든 인터페이스에서 실행할 수 있어요. 여기에는 Snowsight 노트북과 워크시트, 그리고 Snowflake CLI가 포함돼요. 이 프로시저는 SQL 또는 Snowflake 환경에서 지원하는 모든 언어로 호출할 수 있어요.

출처: 문서

본문

환경 설정하기

clean rooms API를 효과적으로 사용하기 위해 코딩 환경을 설정하는 몇 가지 팁을 소개할게요.

개발 도구

clean rooms를 위한 주요 개발자 도구는 다음과 같아요.

  • 코딩 환경: Snowflake 계정에서 저장 프로시저를 실행할 수 있는 모든 코딩 환경이 작동해요. 대부분의 개발자는 Snowsight(브라우저 기반 도구)의 워크시트나 Snowflake CLI를 사용해요.

  • clean rooms UI: clean rooms UI를 사용하여 clean rooms를 구성, 관리 또는 생성할 수 있어요. 대부분의 clean room 분석가는 코드보다 UI를 사용하므로, UI에서 clean rooms의 경험을 확인하고 테스트하는 것이 중요해요. 또한 clean rooms UI에서만 사용할 수 있는 몇 가지 기능이 있어요.

  • Snowsight는 데이터베이스 및 기타 객체를 탐색하고 객체를 검색하는 데 유용해요.

  • Clean rooms API: API 문서는 provider 및 consumer 주제 페이지로 나뉘어 있어요.

코딩 설정

clean rooms를 위해 코딩 환경을 설정하는 방법은 다음과 같아요.

필수 역할 및 웨어하우스

clean rooms API는 전체 API 액세스를 위해 SAMOOHA_APP_ROLE 역할이 필요해요. clean rooms 관리자에게 전체 API 액세스 권한을 부여해 달라고 요청하세요. clean rooms는 또한 API 프로시저의 일부에만 액세스할 수 있는 역할 생성을 지원해요.

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

일반적인 clean room 편집, 생성 또는 삭제 명령에는 XS 웨어하우스를 사용하는 것이 좋아요. 머신러닝 워크로드와 같은 대규모 분석을 실행할 때는 더 큰 웨어하우스나 Snowpark 최적화 웨어하우스 사용을 고려해 보세요.

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

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

다른 웨어하우스를 사용하는 경우 해당 웨어하우스에 SAMOOHA_APP_ROLE 사용 권한을 부여해야 해요:

GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;`

clean rooms API 정보

Snowflake Data Clean Rooms는 공급자(provider)가 clean room을 생성, 구성 및 공유할 수 있게 해주는 일련의 저장 프로시저를 제공해요. 이러한 프로시저는 노트북, 워크시트, Snowflake CLI를 포함하여 Snowflake 프로시저를 지원하는 모든 명령줄 환경에서 호출할 수 있어요. 여기의 문서는 SQL 사용법을 보여주지만, Python이나 기타 지원되는 Snowflake 언어를 사용할 수도 있어요.

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

  • samooha_by_snowflake_local_db.provider - Provider 전용 프로시저. 이 프로시저는 현재 계정에서 생성된 clean rooms에서만 호출할 수 있어요.

  • samooha_by_snowflake_local_db.consumer - Consumer 전용 프로시저. 이 프로시저는 현재 계정이 consumer로 초대된 clean rooms에서만 호출할 수 있어요.

  • samooha_by_snowflake_local_db.library - clean room 생성자(provider) 또는 clean room 협업자(consumer)가 호출하는 일반 프로시저예요. 이 프로시저는 provider 및 consumer 참조 페이지에 모두 문서화되어 있어요.

일부 프로시저는 provider 버전과 consumer 버전이 모두 있어요. 결과는 스키마에 맞게 제공되죠. 예를 들어 provider.view_cleanrooms는 현재 계정에서 자신이 provider인 모든 clean rooms를 나열하고, consumer.view_cleanrooms는 현재 계정에서 자신이 consumer인 모든 clean rooms를 나열해요. 필요한 네임스페이스에서 프로시저를 호출해야 해요.

API 프로시저에서의 clean room 이름

많은 clean room API 프로시저는 cleanroom_name 인자를 사용해요.

clean room이 API를 사용하여 생성된 경우 clean room 이름을 사용하세요. 패키지 이름의 일부로 사용하는 경우 공백을 밑줄로 바꾸세요:

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

clean room이 clean rooms UI를 사용하여 생성된 경우 clean room ID를 사용하세요.

describe_cleanroom 또는 view_cleanrooms를 호출하면 clean room 이름과 ID를 확인할 수 있어요.

API를 사용하여 생성된 clean rooms는 clean rooms UI에서 Supported with Developer APIs로 표시돼요.

계정, 사용자 및 역할 설정

clean room을 개발할 때 clean rooms UI를 꼭 사용할 필요는 없어요. 대부분의 clean room 기능은 API를 호출해서 사용할 수 있거든요. 하지만 몇 가지 기능은 UI에서만 사용할 수 있고, 어떤 기능은 UI에서 더 빠르게 수행할 수 있어요. 그리고 많은 사용자가 UI만 사용하기 때문에, 여러분의 clean room이 UI에서 어떻게 동작하는지 확인하는 것이 중요해요. 따라서 clean room 관리자에게 요청해서 해당 clean room 계정에서 clean room manager 이상의 권한을 받아 두는 것이 좋아요.

사용 사례에 따라, cross-cloud 동작을 테스트하기 위해 다른 웹 호스팅 리전에 추가 Snowflake 계정을 설정하고 싶을 수도 있어요.

테스트용 Snowflake 계정 이름은 일반적인 용도를 알 수 있게 의미 있게 지어 보세요. 예를 들어 “Consumer account”, “Provider account”, “Cross-cloud account”처럼요. 테스트 계정이 여러 개 있고 clean rooms 로그인 페이지에서 계정을 선택해야 할 때 도움이 돼요.

내부 테스트 clean room

개발 중에 clean room을 자신과 공유해서 테스트할 수 있어요. 이런 clean room을 내부 테스트 clean room이라고 해요. provider와 consumer를 하나의 계정으로 사용하면 빠른 기능 테스트에 편리해요.

내부 테스트 clean room을 만들려면 provider.add_consumers에 provider 계정 정보를 유일한 consumer로 전달하기만 하면 돼요.

내부 테스트 clean room에는 다음과 같은 제한 사항이 있어요:

내부 테스트 clean room은 나중에 다른 계정과 공유할 수 없어요. 내부 테스트 clean room은 항상 내부 테스트 clean room으로 유지돼요.

내부 테스트 clean room에서는 다음 기능이 지원되지 않아요:

  • Provider 활성화

  • Provider 실행 분석

  • 요청 로그 마운트 또는 보기 (provider.mount_request_logs_for_all_consumers 또는 provider.view_request_logs)

  • Consumer 정의 템플릿

  • 다중 provider 분석

  • 차등 프라이버시

내부 테스트 clean room에서 지원되지 않는 기능을 테스트하려면, clean room의 양쪽을 테스트할 수 있도록 별도의 provider 및 consumer Snowflake 계정을 설정해야 해요.

하나의 계정에서 provider와 consumer로 clean room을 사용하는 방법을 보여 주는 샘플 워크시트를 다운로드하세요.

clean rooms 환경에 설치된 항목 확인하기

Snowflake Data Clean Rooms는 설치 시 많은 로컬 데이터베이스를 만들어요. clean room 패키지와 함께 실행되거나 설치되는 task와 객체에 대한 자세한 내용은 Snowflake Data Clean Rooms: 설치된 객체에서 확인할 수 있어요.

샘플 데이터

clean rooms 환경에는 사용할 수 있는 샘플 데이터 세트 몇 가지가 설치돼요.

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

지침 및 권장 사항

clean room 작업 시 문제를 피하기 위한 몇 가지 지침은 다음과 같아요:

clean rooms UI와 코드에서 동일한 계정을 사용하고 있는지 확인

예를 들어 코드로 clean room을 만든 다음 clean rooms UI에서 어떻게 보이는지 확인할 때처럼, 같은 Snowflake 계정으로 코딩 환경과 clean rooms UI를 열어야 하는 경우가 자주 있어요. 각 환경에서 동일한 Snowflake 계정을 사용하고 있는지 확인하는 것이 중요해요.

Snowsight에는 같은 계정으로 clean rooms UI를 열 수 있는 단축키가 없고, 그 반대도 마찬가지예요. 따라서 각 환경에서 같은 계정으로 로그인해야 해요.

clean room 이름과 clean room ID

API를 사용할 때 clean room 이름 인수를 받는 프로시저의 경우, clean room 이름을 사용할지 clean room ID를 사용할지 다음과 같이 결정하세요:

  • clean room이 API를 사용하여 생성된 경우, clean room 이름을 사용하세요.

  • clean room이 clean rooms UI에서 생성된 경우, clean room ID를 사용하세요. clean room 이름과 ID는 provider.view_cleanrooms 또는 provider.describe_cleanroom을 호출하여 확인할 수 있어요.

UI를 변경할 때마다 clean room 업데이트

UI에 영향을 주는 clean room 속성을 변경할 때는 변경 사항을 반영하기 위해 provider.create_or_update_cleanroom_listing을 호출하세요.

코드 또는 UI에서 생성된 clean room 간의 상호 운용성

API를 사용하여 clean room을 만들면 일부 기능은 clean rooms UI에서 수정할 수 없어요. 예를 들어 UI에서 생성된 clean room에는 코드로 추가 템플릿을 추가할 수 없어요. 기본 제공되는 Snowflake 템플릿도 마찬가지예요. 또한 차등 프라이버시 설정도 변경할 수 없어요.

문제 해결

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

Consumer가 참여한 clean room에서 join policies를 설정하거나 다른 기본 작업을 수행할 수 없는 경우

clean room을 올바른 역할(SAMOOHA_APP_ROLE)로 설치했는지 확인하세요. clean room을 설치할 때 SAMOOHA_APP_ROLE을 사용하지 않았다면 일반적으로 권한 오류와 같은 많은 문제가 발생합니다. 이 경우 consumer.uninstall_cleanroom조차 실패하므로, 추가 단계를 거쳐 clean room을 제거한 다음 올바른 역할로 다시 설치해야 합니다.

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

생성한 clean room을 찾을 수 없는 경우

한 계정에서 clean room을 생성했지만 협력자의 계정에서 보이지 않는 경우, 가능한 이유는 다음과 같습니다.

  • clean room이 다른 클라우드 호스팅 리전에서 생성되었고 cross-cloud auto-fulfillment를 활성화하지 않았습니다.

  • provider.create_or_update_cleanroom_listing을 호출하여 clean room을 게시하지 않았습니다.

  • consumer.view_cleanrooms() 대신 provider.view_cleanrooms()를 호출하고 있습니다(또는 그 반대).

  • clean room을 공유하지 않았거나, 잘못된 계정과 clean room을 공유했거나, Snowsight/Clean rooms UI/CLI에서 잘못된 협력자 계정을 열었습니다. clean room이 보일 것으로 예상하는 계정이 clean room을 공유한 계정인지, 그리고 해당 공유 계정으로 로그인되어 있는지 확인하세요.

  • clean room을 게시한 후 협력자에게 표시되기까지 약간의 지연이 있습니다.

알 수 없는 함수

프로시저를 호출했는데 다음과 유사한 오류가 발생하는 경우:

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

가능한 원인은 다음과 같습니다.

잘못된 네임스페이스를 입력했습니다.

프로시저의 올바른 consumer 또는 provider 버전을 호출해야 합니다. 많은 프로시저에는 provider 버전과 consumer 버전이 모두 있습니다.

함수 이름을 잘못 입력했습니다.

올바른 이름은 참조 가이드를 확인하세요.

제한된 액세스 run-role이 부여되었고, 호출한 함수가 해당 역할에서 허용되지 않습니다.

다음 SQL 코드를 실행하여 테스트하세요:

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

코드 스니펫이 TRUE를 반환하면 clean room API에 대한 제한된 액세스 run-role 권한이 있는 것입니다. 더 많은 액세스가 필요하면 clean room 관리자에게 전체 액세스를 요청하세요. 허용된 run-role 프로시저 목록은 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';

결과가 없으면 관리자에게 clean room에 대한 API 액세스를 요청하세요.

사용자가 clean room을 설치했는지 확인

다음 SQL 코드를 실행하여 특정 사용자가 특정 clean room을 설치했는지 확인할 수 있습니다. $consumer_locator와 $cleanroom_name을 consumer locator와 clean room 이름으로 바꾸세요.

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

쿼리 또는 분석 기록 확인

UI 또는 코드에서 실행한 분석에 대한 쿼리 기록을 볼 수 있습니다. 이 기록은 별도로 저장되고 확인됩니다.

UI 분석 기록

clean rooms UI는 Analyses & Queries 페이지에 이 계정의 모든 이전 분석 목록을 표시합니다. 이 결과는 UI에서 실행된 쿼리에만 해당합니다.

clean room을 수정하거나 삭제하면 해당 clean room에 대한 UI의 분석 보고서는 다음 템플릿 중 하나를 사용하지 않는 한 삭제됩니다.

  • Audience Overlap & Segmentation

  • SQL Query

  • 사용자 지정 템플릿.

위에 나열된 템플릿에 대한 쿼리 기록은 clean room이 수정되거나 삭제되어도 유지됩니다.

API 쿼리 기록

템플릿 분석을 포함하여 API를 사용해 실행된 모든 호출의 계정 기록을 보려면 다음을 수행하세요.

  1. Snowsight에 로그인합니다.

  2. 탐색 메뉴에서 Monitoring » Query History를 선택합니다.

  3. 필터를 사용하여 분석과 연결된 쿼리를 찾은 다음 쿼리 또는 분석을 선택합니다.

확장 예제

Developer APIs의 다양한 기능을 이해하는 데 도움이 되도록 clean rooms 문서의 Use cases 및 Features 섹션에 있는 예제를 참조할 수 있습니다.

더 알아보기 (Learn more)