Provider-run analyses

概要

The default clean room configuration enables only the consumer to run an analysis in the clean room. However, the provider can request permission from the consumer to run a specific template in a specific clean room using consumer data. Provider-run analysis can be enabled and run using either the clean rooms UI or code.

The following diagram shows the data flow and main components in a basic provider-run analysis:

Basic data flow direction in a provider-run analysis

  1. 基本的なプロバイダーデータ分析では、コンシューマーとプロバイダーは両方とも、データをクリーンルームにリンクします。ソースデータは、データが存在するアカウントのプライベートビューとしてクリーンルームにリンクされます。

  2. プロバイダーが分析を実行すると、プロバイダーのデータがコンシューマーのアカウントのクリーンルームアプリと共有されます。分析はコンシューマーのアカウントで実行されます。

  3. 暗号化された結果は、コンシューマーアカウントのコンシューマー DB に一時的に書き込まれます。

  4. 次に、暗号化された結果は、プロバイダーのアカウントの分析結果バック共有（別称: ガバナンスバック共有）にコピーされ、復号化されます。分析はコンシューマーのアカウントで実行されるため、コンシューマーは分析の料金を請求されます。

詳細については、 Snowflake Data Clean Rooms: インストールされたオブジェクト をご参照ください。

Templates that support provider-run analyses

The following templates support provider-run analyses:

  • Audience Overlap & Segmentation

  • SQL Query (UI only)

  • カスタムテンプレート (API のみ)

Billing and cost details

Provider-run analyses run in the consumer's account, and consumers are billed for a provider-run analysis. To stop incurring costs from provider-run analyses, the consumer must uninstall the clean room.

A consumer can estimate the number of credits consumed by the provider within the last N days by executing the following query. Specify the number of previous days as a negative number.

-- Estimate the number of credits consumed in the past 5 days.
SELECT * FROM TABLE(SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.PRA_CONSUMPTION_UDTF(-5));
Copy

When a provider runs an analysis in the clean rooms UI, the clean room uses auto-scaling logic based on dataset sizes to choose a warehouse for the provider's analysis.

プロバイダーが API を使用してクリーンルームを作成し、実行する場合、プロバイダーは、コンシューマーが指定した許容値のセットからウェアハウスのサイズと型を明示的に選択できます。

一般的なメモ

  • プロバイダーは、 UI または API を使用して自分のアカウントに結果をアクティブ化したり、 UI を使用している場合はサードパーティのプロバイダーに結果をアクティブ化できます。アクティベーションを有効にして結果を表示する方法については、 Activating query results をご参照ください。

  • If the consumer and provider are in different cloud regions, Cross-cloud auto-fulfillment must be enabled in both accounts and for both clean rooms.

    プロバイダーが実行するクロスクラウドクエリの実行には、プロバイダーのソースデータをプロバイダーからコンシューマーに複製する必要があり、クエリ結果をコンシューマーからプロバイダーに複製する必要があるため、実行に時間がかかる場合があることに注意してください。

  • Any templates run by the provider require column names or aliases for all columns generated in the results. If a column is aggregated (for example, SUM(col1)) or calls a custom function (for example, cleanroom.my_function(p.hashed_email)), the template must explicitly specify a column name alias as shown here:

    SELECT SUM(col1) AS TOTAL FROM my_db.my_sch.T; -- Correct
SELECT SUM(col1)          FROM my_db.my_sch.T; -- Error: aggregated column needs an explicit alias.
    Copy

Provider-run analyses in the UI

Here is how to enable provider-run analysis in a new clean room when using the clean rooms UI:

  1. The provider creates and configures a clean room, using one of the supported templates. Configure the clean room up to the Share Clean Room step.

  2. In the Share Clean Room step of clean room configuration, the provider selects Enable run analysis & query next to their own account to enable them to run all templates in this clean room that support provider-run analysis.

    • この設定をクリーンルームの作成後に変更することはできません。公開されたクリーンルームでクエリを実行するために特定のアカウントの権限を変更したい場合は、クリーンルームを削除して新しいクリーンルームを作成する必要があります。

  3. The consumer joins and configures the clean room as usual for all templates in the clean room, including any templates that support provider analysis. If the consumer does not want to enable a provider to run a specific template, they can omit required details for that template.

    • コンシューマーがクリーンルームに参加すると、参加する前にそのクリーンルームでプロバイダー実行分析が有効であることが警告されます。

    • The consumer can run queries as soon as the clean room is joined, but there is a delay of up to 30 minutes before the provider can run the template. This setup delay occurs only during the initial join step; if the provider later adds other provider-run templates, the provider can run them as soon as the consumer configures their clean room for that template.

  4. After the join step completes, the clean room is available for both provider run analyses and consumer run analyses.

    重要:

    • プロバイダーは、コンシューマーがクリーンルームをインストールしてから分析を実行するまで、約10分待っていなければなりません。遅延は、プロバイダー実行の分析に必要な追加のバックグラウンド構成のためです。

    • コンシューマーは、プロバイダーまたはコンシューマーが実行するかどうかに関係なく、このクリーンルームですべての分析に対して請求されます。

Provider-run analyses in the API

Here is how to enable provider-run analysis in a new clean room using the clean rooms API:

  1. プロバイダー

    1. Creates and configures the clean room and data and policies in the standard way.

    2. Adds consumers in the standard way.

    3. provider.enable_provider_run_analysis を呼び出すことで、クリーンルーム内の特定のコンシューマーアカウントに対してプロバイダーデータ分析を可能にします。

      重要:

      • The provider must call provider.enable_provider_run_analysis after adding consumers to a clean room, but before any consumer installs the clean room. Each consumer account must approve this request for their data to be accessible for provider-run analyses in this clean room.

      • Any time the provider changes the provider-run analysis setting for a clean room, the clean room must be re-installed by all consumers for the change to take effect. Because it can be difficult to force all collaborators to re-install a clean room, it is more reliable for the provider to delete a published, shared clean room when changing the analysis permissions, and then create a new clean room with the desired permissions.

    4. Publishes the clean room.

    5. Lets the consumer know that the clean room is available, the name of the clean room, and what templates you want to run in the clean room.

  2. コンシューマー

    1. Installs the clean room and links in data in the standard way.

    2. データに必要な 結合および列のポリシー を設定します。

    3. Allows provider-run analysis for specific templates in the clean room by calling either consumer.enable_templates_for_provider_run (for multiple templates) or consumer.approve_template (for one template).

      注釈

      コンシューマーがテンプレートを承認した後にプロバイダーがテンプレートを変更した場合、コンシューマーはテンプレートを再度承認する必要があります。テンプレートが再承認されるまで、承認されたテンプレートの古いキャッシュバージョンはプロバイダーによって実行されます。

    4. （オプション）コンシューマーは、プロバイダー実行の分析に使用できるウェアハウスのタイプやサイズを制限することができます。Restricting warehouse size and type limits をご参照ください。

    5. Tells the provider that they have installed the clean room and approved provider-run analyses.

  3. プロバイダー

    1. After the consumer has installed the clean room, the provider enables analyses to access consumer data by enabling data sharing from the consumer to the provider account. The process for this depends on whether the provider and consumer are in the same cloud region or different cloud regions:

      • If the provider and consumer are in the same cloud region, the provider calls provider.mount_request_logs_for_all_consumers once. If a new consumer account installs the clean room later and the provider wants to use consumer data in this template, the provider must re-run this procedure to be able to access that data.

      • If the provider and consumer are in different cloud regions, the provider and consumer must enable cross-cloud auto-fulfillment. When a provider runs an analysis across regions, the query can take some time to complete, because query data is sent from the provider's region to the consumer's region and back.

    2. provider.view_warehouse_sizes_for_template を呼び出してコンシューマーが分析に使用するウェアハウスのタイプとサイズを制限しているかどうかを確認します。コンシューマーがプロバイダーの実行分析のためのウェアハウスサイズに制限がある場合、プロバイダーは次のステップの分析リクエストで許可された warehouse_type 値および warehouse_size 値を指定する必要があります。コンシューマーがウェアハウスの制限を指定していない場合、それらのフィールドは分析リクエストでオプションです。詳細については、 Restricting warehouse size and type limits をご参照ください。

    3. Runs the analysis by calling provider.submit_analysis_request with the template name, the table names, and the template arguments. If the consumer has specified limits on warehouse sizes or types, the provider must also specify the warehouse size and type in the analysis request.

      • Save the request ID returned by provider.submit_analysis_request; the ID is needed to check the status and results of the analysis.

    4. Checks the status of the analysis by calling provider.check_analysis_status. When status is reported as COMPLETED, call provider.get_analysis_result to get the analysis results.

Restricting warehouse size and type limits

コンシューマーにはプロバイダーが実行した分析に対して請求されるため、コンシューマーはプロバイダーが自分のアカウントで分析を実行するために使用できるウェアハウスサイズと型を指示できます。コンシューマーがウェアハウスサイズとタイプの制限を設定する方法、およびプロバイダーが分析を実行する際にウェアハウスサイズとタイプを選択する方法は次のとおりです。

  1. The consumer calls consumer.set_provider_run_configuration and specifies which warehouse sizes and types a provider can use for a specific template. In the following snippet, the consumer limits providers to using STANDARD warehouses of size MEDIUM or LARGE when running template_1:

    CALL samooha_by_snowflake_local_db.consumer.set_provider_run_configuration(
  $cleanroom_name,
  {
    'template_1': {
      'warehouse_type': 'STANDARD',
      'warehouse_size': ['MEDIUM', 'LARGE']}
  });
    Copy

  2. プロバイダーは``provider.view_warehouse_sizes_for_template``を呼び出し、そのテンプレートに対するプロバイダー実行分析について許可されるウェアハウスのサイズとタイプを確認します。

    CALL samooha_by_snowflake_local_db.provider.view_warehouse_sizes_for_template(
  $cleanroom_name,
  'template_1',
  $consumer_account_loc
);
    Copy

  3. プロバイダーは、分析実行リクエストで使用するウェアハウスのサイズとタイプを指定します。

    CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
  $cleanroom_name,
  $consumer_locator_id,
  'template_1',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  object_construct(
    'dimensions', ['c.REGION_CODE'],
    'measure_type', ['AVG'],
    'measure_column', ['c.DAYS_ACTIVE'],
    'warehouse_type', 'STANDARD',      -- Any other value would cause the request to fail.
    'warehouse_size', 'LARGE'          -- Only MEDIUM and LARGE supported.
  )
);
    Copy

Tip

以下のプロシージャは、clean room内でどちらの側から分析を実行するかを管理します：

**コンシューマー実行分析**（デフォルトで許可）：変更はすぐに適用されます。

  • provider.enable_consumer_run_analysis

  • provider.disable_consumer_run_analysis

**プロバイダー実行分析**（デフォルトで無効）：変更にはコンシューマーによる再インストールが必要です。

  • provider.enable_provider_run_analysis (requires the consumer to approve by calling consumer.enable_templates_for_provider_run)

  • provider.disable_provider_run_analysis

Install and run the code example

You can download and install a complete running example to create and run a provider-run analysis. To run this example, you need two Snowflake accounts in the same organization and cloud hosting region with the Snowflake Data Clean Room environment installed.

  1. サンプルノートブックをダウンロードします。

  2. プロバイダーとコンシューマーアカウントの両方にノートブックをインストールします。

    ノートブックをアップロードするには、次を実行します。

    1. Sign in to Snowsight。

    2. In the navigation menu, select Projects » Notebooks。

    3. + Notebook » Import .ipynb file を選択します。

    4. ダウンロードした.ipynbファイルを選択します。

    5. ファイルに好きな名前を付けて、データベースとスキーマを選択します。

    6. デフォルトのウェアハウス APP_WH をそのまま使用します。

    7. Create を選択します。

    8. To create the clean room, open the notebook in the provider account and complete the provider portion.

    9. コンシューマーアカウントでノートブックを開き、コンシューマーの部分を入力してclean roomをインストールおよび構成し、テンプレートを実行します。

  3. ノートブックに表示されている順序で、示されているとおりにプロバイダーとコンシューマーのアクションを実行します。

言語: 日本語