쿼리 결과 활성화

쿼리 결과 활성화

제공자나 소비자는 활성화(activation)라는 과정을 통해 템플릿 결과를 클린룸 밖으로 보낼 수 있어요.

출처: Activating query results

본문

지원 종료(EOL) 공지

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

활성화 개요

제공자 또는 소비자는 활성화(activation)라는 과정을 통해 템플릿 결과를 클린룸 밖으로 보낼 수 있어요. Snowflake는 세 가지 유형의 활성화를 지원해요:

  • Provider 활성화: 결과가 제공자 Snowflake 계정의 테이블로 푸시되는 방식이에요.
  • Consumer 활성화: 결과가 소비자 Snowflake 계정의 테이블로 푸시되는 방식이에요.
  • 제3자 활성화: 제공자 또는 소비자가 활성화 커넥터를 통해 Google Ads 또는 Meta Ads Manager 같은 Snowflake 승인 제3자에게 결과를 푸시하는 방식이에요.

모든 경우에 템플릿이 활성화를 지원해야 하고, 당사자들은 활성화될 자신의 데이터 컬럼에 대해 활성화를 승인해야 해요. 데이터 제공자는 활성화 정책을 설정해 어떤 컬럼이 활성화되는지 지정해요. 클린룸 정책에 대한 자세한 내용은 Snowflake Data Clean Room 정책 이해를 참고하세요.

활성화는 활성화된 경우 차등 프라이버시를 지원하며, 차등 프라이버시 규칙과 예산을 존중해요.

중요

소비자와 제공자가 다른 클라우드 리전에 있다면 두 계정과 두 클린룸 모두에서 크로스 클라우드 자동 이행을 활성화해야 해요.

Provider 및 Consumer 활성화

클린룸이 템플릿 결과를 제공자 또는 소비자의 Snowflake 계정에 저장하도록 구성할 수 있어요. 제공자와 소비자 모두 클린룸 밖으로 나가는 데이터의 활성화를 승인해야 해요.

활성화는 전용 활성화 템플릿을 사용해 구현돼요. 클린룸 UI에서 활성화 템플릿을 분석 템플릿과 연결할 수 있고, 사용자는 분석 템플릿을 실행하고 결과를 본 다음 연결된 활성화 템플릿을 실행할 수 있어요. Snowflake 제공 Audience Overlap & Segmentation 흐름이 이렇게 동작해요.

활성화 템플릿은 연결된 분석 템플릿과 동일할 필요가 없어요. 활성화 템플릿은 종종 분석 템플릿의 하위 집합이에요.

지원되는 템플릿

다음 템플릿은 provider 및 consumer 활성화를 지원해요:

지원되는 조합

활성화는 제공자 또는 소비자가 실행할 수 있어요. (provider 실행 분석에 대해 더 알아보세요.)

다음 조합이 지원돼요:

Provider 활성화 Consumer 활성화 제3자 활성화
Provider 실행 ✅ ❌ UI 전용
Consumer 실행 ✅ ✅ UI 전용

결과

Provider 활성화 결과는 제공자 계정의 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY 테이블에 저장돼요.

Consumer 활성화 결과는 소비자 계정의 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY 테이블에 저장돼요.

데이터를 읽는 방법은 결과 보기를 참고하세요.

Provider 또는 Consumer 활성화 구현

클린룸 UI

설정

  1. 클린룸 생성 또는 참여: 클린룸을 만들거나 참여할 때 Configure Analysis & Query 단계의 Activation Settings에서 자신의 계정으로 활성화된 결과에 추가할 컬럼을 지정해요.
  2. 템플릿 실행 및 결과 활성화: 자신의 분석과 연결된 활성화를 실행하려면 다음 단계를 완료해요:
    1. 분석을 실행해요.
    2. 분석을 실행한 뒤 Results » Activate를 선택해요.
    3. Activation Hub 아래에서 활성화할 provider 또는 consumer 계정의 이름을 선택해요.
    4. 설명용 세그먼트 이름이나 활성화 컬럼처럼 활성화 템플릿에 특정한 정보를 제공해요.
    5. 세그먼트 이름을 제공해요. 이는 주어진 실행의 결과 집합을 식별하는 임의의 문자열이에요. 각 실행의 결과를 따로 그룹화하려면 활성화마다 다른 문자열을 제공하거나, 결과를 결합하고 싶다면 여러 실행에 걸쳐 같은 세그먼트 이름을 사용할 수 있어요.
    6. Push Data를 선택해요.
    7. 활성화된 결과를 보는 방법은 Provider 및 Consumer 활성화 결과 보기를 참고하세요.

활성화는 누가 실행하는지와 consumer 또는 provider 활성화인지에 따라 다르게 수행돼요.

Consumer 활성화(Consumer 실행) / Provider 활성화(Consumer 실행) / Provider 활성화(Provider 실행)

중요

클린룸에서 소비자가 제공자 계정에 데이터를 처음 활성화할 때, 제공자는 해당 계정의 클린룸 UI에 로그인해 최대 30분 동안 로그인 상태를 유지해 데이터 파이프라인을 구축해야 해요. 이 작업은 클린룸당 소비자당 한 번만 하면 돼요. 그 전에는 활성화가 성공해도 데이터가 제공자 계정에 나타나지 않아요.

Consumer가 자신의 Snowflake 계정으로 결과를 푸시하는 방법:

제공자:

  1. 표준 클린룸처럼 클린룸을 만들고, 데이터셋을 링크하고, 조인 정책을 설정해요.
  2. 지원되는 Snowflake 표준 템플릿을 선택하거나 클린룸에 커스텀 활성화 템플릿을 추가해요. 이 클린룸을 UI에서 사용한다면 템플릿 문서에 설명된 대로 올바른 활성화 필드가 있는 웹 폼을 제공해야 해요.
  3. provider.enable_template_for_consumer_activation을 호출해 템플릿을 consumer 활성화용으로 활성화해요.
  4. 활성화할 수 있는 제공자 컬럼을 지정하려면 provider.set_activation_policy를 호출해 활성화된 템플릿의 클린룸에 활성화 정책을 설정해요.
  5. 평소처럼 소비자 콜라보레이터를 추가하고, 기본 릴리스 지시문을 설정하고, 클린룸을 게시해요.

소비자:

  1. 표준 클린룸처럼 클린룸을 설치하고, 데이터셋을 링크하고, 조인 정책을 설정해요.
  2. 활성화할 수 있는 소비자 컬럼을 지정하려면 consumer.set_activation_policy를 호출해 그 템플릿의 클린룸에 활성화 정책을 설정해요.
  3. 마지막 파라미터를 TRUE로 설정해 consumer 활성화임을 나타내고 consumer.run_activation을 호출해 활성화를 실행해요.
  4. 아래 설명대로 결과를 확인해요.

예시:

다음 예시를 내려받아 Snowflake 계정에 워크시트 파일로 업로드해요. provider와 consumer에 클린룸 API가 설치된 별도의 계정이 필요해요. 샘플 파일에 표시된 대로 정보를 대체해요. Snowflake 계정에 SQL 워크시트를 업로드하는 방법 보기.

Consumer가 제공자의 Snowflake 계정으로 결과를 푸시하는 방법:

중요

소비자와 제공자 양쪽에 클린룸 UI가 설치되어 있지 않고 소비자가 제공자에게 활성화한다면:

  • 소비자는 다음 SQL 명령을 실행해야 해요:
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2
  ADD ACCOUNTS = $provider_account_data_sharing_id;

여기서 $provider_account_data_sharing_id는 제공자의 Data Sharing 계정 식별자예요.

  • 제공자는 다음 프로시저를 실행해야 해요:
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);

여기서 $consumer_account_data_sharing_id는 소비자의 Data Sharing 계정 식별자예요.

  1. 제공자:

    1. 표준 방식으로 클린룸을 만들어요.
    2. 데이터셋을 링크해요. 제공자는 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.TEMP_PUBLIC_KEY 테이블도 클린룸에 링크해야 해요.
    3. 표준 방식으로 조인 정책을 설정해요.
    4. 지원되는 Snowflake 표준 템플릿을 선택하거나 클린룸에 커스텀 활성화 템플릿을 추가해요. 이 클린룸을 클린룸 UI에서 사용한다면 올바른 활성화 필드가 있는 웹 폼을 제공해야 해요.
    5. 활성화할 수 있는 제공자 컬럼을 지정하려면 provider.set_activation_policy를 호출해 그 템플릿의 클린룸에 활성화 정책을 설정해요.
    6. 평소처럼 소비자 콜라보레이터를 추가하고, 기본 릴리스 지시문을 설정하고, 클린룸을 게시해요. (클린룸 UI가 설치되어 있지 않다면 소비자를 추가한 뒤 provider.setup_provider_activation_share_mount_task를 호출해요.)

  2. 소비자:

    1. 표준 클린룸처럼 클린룸을 설치하고, 데이터셋을 링크하고, 조인 정책을 설정해요.
    2. 활성화할 수 있는 소비자 컬럼을 지정하려면 consumer.set_activation_policy를 호출해 그 템플릿의 클린룸에 활성화 정책을 설정해요.
    3. 마지막 인자를 FALSE로 설정해 provider 활성화임을 나타내고 consumer.run_activation을 호출해 활성화를 실행해요.

    참고

    활성화된 데이터의 암호화된 버전은 SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY 테이블에 28일 동안 소비자 계정에 저장돼요. 28일보다 오래된 데이터는 소비자 계정에서 제거돼요.

  3. 제공자:

    1. 소비자가 귀하의 계정에 데이터를 처음 활성화할 때는 소비자가 데이터를 활성화한 후 약 30분 동안 이 계정의 클린룸 UI에 로그인해야 해요. 그러면 데이터가 계정에 나타나요. 이 작업은 클린룸당 소비자 계정당 한 번만 합니다. 같은 소비자가 같은 클린룸에서 나중에 활성화할 때는 이 단계가 필요하지 않아요. 결과는 계정에 저장되기 전에 복호화되어야 하므로 시간이 걸릴 수 있어요. 복호화 태스크는 60분 후 타임아웃됩니다. 이 경우 provider.update_activation_warehouse를 호출해 복호화에 사용되는 웨어하우스 크기를 늘리세요.
    2. 아래 설명대로 결과를 확인해요.

예시:

다음 예시를 내려받아 Snowflake 계정에 워크시트 파일로 업로드해요. provider와 consumer에 클린룸 API가 설치된 별도의 계정이 필요해요. 샘플 파일에 표시된 대로 정보를 대체해요. Snowflake 계정에 SQL 워크시트를 업로드하는 방법 보기.

Provider가 자신의 Snowflake 계정으로 결과를 푸시하는 방법:

이 방식은 커스텀 템플릿, provider 실행 분석, provider 활성화를 포함한 여러 기법을 결합하므로, 제공자와 소비자 사이에 여러 라운드의 요청과 승인이 수반돼요.

  1. 제공자:

    1. 표준 클린룸처럼 클린룸을 만들고 데이터셋을 링크하고 조인 정책을 설정해요. 단 한 가지 예외: samooha_by_snowflake_local_db.library.temp_public_key 테이블을 링크해야 해요. Provider 실행 데이터는 암호화되며, 이 테이블이 결과의 암호화와 복호화를 가능하게 해요.
    2. 지원되는 Snowflake 표준 템플릿을 선택하거나 클린룸에 커스텀 활성화 템플릿을 추가해요. 이 클린룸을 UI에서 사용한다면 템플릿 문서에 설명된 대로 활성화를 지원하는 올바른 필드가 있는 웹 폼을 제공해야 해요.
    3. 활성화할 수 있는 제공자 컬럼을 지정하려면 provider.set_activation_policy를 호출해 그 템플릿의 클린룸에 활성화 정책을 설정해요.
    4. 표준 방식으로 소비자 콜라보레이터를 추가해요. 클린룸 UI가 설치되어 있지 않다면 사용자를 추가한 뒤 provider.setup_provider_activation_share_mount_task를 호출해야 해요.
    5. provider.enable_provider_run_analysis를 호출해 클린룸에서 provider 실행 분석을 활성화해요. 이 작업은 콜라보레이터를 추가한 뒤, 콜라보레이터가 클린룸을 설치하기 전에 해야 해요. 소비자가 클린룸을 설치한 후 이 설정을 변경한다면 소비자가 클린룸을 다시 설치해야 변경 사항이 적용돼요.
    6. 평소처럼 기본 릴리스 지시문을 설정하고 클린룸을 게시해요.

  2. 소비자:

    1. 표준 클린룸처럼 클린룸을 설치하고, 데이터셋을 링크하고, 조인 정책을 설정해요.
    2. 활성화할 수 있는 소비자 컬럼을 지정하려면 consumer.set_activation_policy를 호출해 그 템플릿의 클린룸에 활성화 정책을 설정해요.

  3. 제공자:

    • provider.request_provider_activation_consent를 호출해 소비자에게 활성화 템플릿 실행 권한을 요청해요.

  4. 소비자:

    1. consumer.enable_templates_for_provider_run을 호출해 제공자에게 이 클린룸에서 주어진 템플릿을 실행할 권한을 부여해요.
    2. consumer.approve_provider_activation_consent를 호출해 제공자에게 이 클린룸에서 주어진 템플릿의 결과를 활성화할 권한을 부여해요.

  5. 제공자:

    1. provider.mount_request_logs_for_all_consumers를 호출해 provider 활성화에서 소비자 데이터가 공유되도록 해요.
    2. provider.submit_analysis_request를 호출해 활성화 템플릿을 실행해요. 요청이 로그에 나타나기까지 몇 분이 걸려요. 상태는 provider.check_analysis_status로 확인해요. 상태가 SUCCESS로 보고된 뒤에도 결과가 복호화되어 제공자 Snowflake 테이블에 기록되는 데 추가 시간이 필요하다는 점에 주의하세요. 모든 복호화된 데이터는 한 번에 결과 테이블에 추가돼요. 세그먼트 또는 활성화 ID에 대해 결과 테이블을 주기적으로 계속 확인해요. 복호화 태스크는 60분 후 타임아웃됩니다. 이 경우 provider.update_activation_warehouse를 호출해 복호화에 사용되는 웨어하우스 크기를 늘리세요.

    참고

    소비자가 템플릿을 승인한 뒤 템플릿을 수정하려면 다음 단계를 수행해야 해요. 그렇지 않으면 provider.submit_analysis_request가 마지막으로 승인된 템플릿 버전을 계속 실행해요.

    1. 제공자가 provider.add_custom_sql_template을 호출해 템플릿을 업데이트해요. create_or_update_cleanroom_listing을 다시 호출할 필요는 없어요.
    2. 소비자가 consumer.enable_templates_for_provider_run을 호출해요.
    3. 소비자가 consumer.approve_provider_activation_consent를 호출해요.
    4. 업데이트된 템플릿이 이제 provider 활성화에 사용할 준비가 됐어요.

일반적인 오류

  • Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized - 임시 결과 테이블이 어떤 이유로 생성되지 못했어요. 템플릿의 SQL 오류이거나, 템플릿이 명시적으로 테이블을 생성하지 않았을 수 있어요. 오류 세부 내용을 확인하세요.
  • Query validation checks failed - 활성화 정책에 없는 템플릿에 사용된 일부 컬럼이 있어요.

예시:

다음 예시를 내려받아 Snowflake 계정에 워크시트 파일로 업로드해요. provider와 consumer에 클린룸 API가 설치된 별도의 계정이 필요해요. 샘플 파일에 표시된 대로 정보를 대체해요. Snowflake 계정에 SQL 워크시트를 업로드하는 방법 보기.

Provider 및 Consumer 활성화 결과 보기

활성화 결과 위치와 형식

모든 활성화 결과는 제공자 또는 소비자 계정의 지정된 클린룸 테이블에 추가돼요. 테이블의 각 행은 쿼리 결과의 행에 대응해요. 각 실행의 결과는 테이블에 추가돼요(각 실행 전에 테이블이 지워지지 않음). 서로 다른 실행은 활성화마다 고유한 ACTIVATION_ID 컬럼이나, 호출자가 각 활성화 실행마다 지정할 수 있는 SEGMENT 컬럼으로 구분할 수 있어요.

참고

Provider 활성화 결과는 암호화된 형식으로 소비자의 localDB 임시 테이블에 기록돼요. 그런 다음 결과가 제공자 계정으로 복사되어 저장되기 전에 복호화돼요. 이 추가 이동 및 복호화 단계는 큰 결과 집합에서 지연을 일으킬 수 있어요.

  • Provider 활성화 결과는 제공자 계정의 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY에 저장돼요.
  • Consumer 활성화 결과는 소비자 계정의 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY에 저장돼요.

이 테이블들은 다음 컬럼을 포함해요:

  • USER_ID: JSON 형식의 결과 한 행. 키는 컬럼 이름이고 값은 해당 행의 그 컬럼 값이에요. 객체는 템플릿에 전달된 각 인자의 컬럼도 포함해요.
  • ACTIVATION_ID: 각 요청의 고유 ID. ID는 성공적인 활성화 요청에서 반환돼요. 이 컬럼으로 필터링해 같은 활성화 실행의 모든 결과를 얻거나, 여러 실행에 걸쳐 같은 세그먼트 이름을 재사용한다면 SEGMENT로 필터링할 수 있어요. 이는 submit_analysis_request 또는 run_activation이 반환한 쿼리 요청 ID와 같아요.
  • CLEANROOM_NAME: 쿼리가 실행된 클린룸의 이름.
  • CONSUMER: (Provider 활성화 전용) 이 활성화를 승인한 소비자.
  • PROVIDER: (Consumer 활성화 전용) 이 활성화를 승인한 제공자.
  • SEGMENT: 활성화를 실행할 때 배정하는 임의의 문자열 값. 이 컬럼을 사용해 여러 쿼리 실행의 결과를 조인할 수 있어요.
  • TIMESTAMP: 활성화가 실행된 시각.

Provider 활성화 예시:

SELECT * FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY WHERE segment = 'my_segment';

                             USER_ID                          |   CLEANROOM_NAME |   SEGMENT  | CONSUMER |          TIMESTAMP      |  ACTIVATION_ID
"{\""AGE_BAND\"":55,\""ITEM_COUNT\"":2328,\""STATUS\"":\""MEMBER\""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{\""AGE_BAND\"":20,\""ITEM_COUNT\"":88,\""STATUS\"":\""PLATINUM\""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{\""AGE_BAND\"":80,\""ITEM_COUNT\"":18,\""STATUS\"":\""GOLD\""}"     |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
...

Provider 또는 Consumer 활성화 결과 읽기

Snowflake 계정으로 활성화된 결과를 보려면 적절한 SQL 명령을 실행해요:

Provider 활성화 결과 보기:

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Consumer 활성화 결과 보기:

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

각 데이터 행은 USER_ID 컬럼의 객체로 결합돼요. 다음 같은 쿼리로 결과를 펼칠 수 있어요:

-- Assuming columns AGE_BAND, STATUS, and ITEM_COUNT
SELECT
  item:"AGE_BAND",
  item:"STATUS",
  item:"ITEM_COUNT"
FROM (SELECT parse_json(user_id)
      AS item
      FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
      WHERE segment = $segment_name)
ORDER BY item:"AGE_BAND", item:"STATUS" ASC
LIMIT 20 ;

Snowsight에서 최신 결과 행 10개를 보려면:

  1. Snowsight에 로그인해요.
  2. 탐색 메뉴에서 Catalog » Explorer를 선택해요.
    • Provider 활성화의 경우 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY로 이동해요.
    • Consumer 활성화의 경우 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY로 이동해요.
  3. Data Preview를 선택해요.

제3자 활성화

제3자 활성화는 제3자 활성화 커넥터를 사용해 쿼리 결과를 Snowflake 승인 제3자의 계정에 저장해요.

제3자 활성화는 클린룸 UI에서만 지원되며 커스텀 템플릿으로는 지원되지 않아요.

클린룸 UI를 사용한 활성화는 클린룸 계정이 활성화를 허용하는 경우에만 지원돼요.

클린룸 관리자는 제3자 활성화 커넥터를 지원하도록 환경을 구성하고, 허용된 커넥터를 선택하고 구성해야 그 커넥터를 어떤 클린룸에서 사용할 수 있어요.

제3자 활성화는 consumer 실행 및 provider 실행 분석을 모두 지원해요.

지원되는 템플릿

다음 템플릿은 제3자 활성화를 지원해요:

  • Audience Overlap & Segmentation

제3자 활성화 구현

  1. 클린룸 생성 또는 참여: 클린룸을 만들거나 참여할 때 Configure Analysis & Query 단계의 Activation Settings에서 자신의 계정으로 활성화된 결과에 추가할 컬럼을 지정해요.
  2. 결과 활성화:
    1. 분석을 실행해요.
    2. 분석을 실행한 뒤 Results » Activate를 선택해요.
    3. Activation Hub 아래에서 활성화할 제3자 제공자의 이름을 선택해요.
    4. 제공자에 특정한 정보를 제공해요. 설명용 이름을 제공하거나 활성화할 컬럼을 선택하는 것일 수 있어요. 페이지의 툴팁이 그 제공자에 대한 추가 정보를 제공해야 해요.
    5. Push Data를 선택해요.

더 알아보기