Provider-run analysis¶

Here are the steps to enable provider-run analysis in a new clean room:

1. The provider creates and configures a clean room, using one of the supported templates.

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

   • This setting cannot be changed after a clean room is created; if you want to change permission for a specific account to run queries in a published clean room, you must delete the clean room and create a new one.

3. The consumer joins and configures the clean room as normal 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.

   • When the consumer joins the clean room, they are warned before joining that provider-run analysis is enabled for that clean room.

   • 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 is only for 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. The clean room is now available for both provider run (after the initial setup delay) and consumer run (no delay) analyses.

   • The consumer is billed for all analyses in this clean room, whether run by the provider or consumer.

The provider can enable and disable both provider- and consumer-run analysis in a clean room by making the appropriate API calls.

However, any time the provider changes the provider-run analysis setting, 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, then create a new clean room with the desired permissions.

Here is the general flow for creating a new clean room that allows provider-run analyses:

1. Provider

   1. Create and configure your clean room and data and policies in the standard way.

   2. Add consumers in the standard way.

   3. Enable provider-run analysis for specific consumer accounts in the clean room by calling provider.enable_provider_run_analysis. Call this procedure only after adding consumers to a clean room, but before any consumer installs the clean room. Each consumer account must approve this request separately, or their data will not be accessible for provider-run analyses in this clean room.

   4. Publish the clean room.

   5. Let your consumers 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. Consumer

   1. Install the clean room and link in your data in the standard way.

   2. Set join and column policies on your data. If you do not set both policies in a clean room, the provider cannot run a template using your data. This is unlike consumer-run analyses, where total absence of a policy means that all columns are approved for that policy type.

   3. Allow provider analysis for specific templates in the clean room by calling consumer.enable_templates_for_provider_run.

   4. (Optional) Provider-run analyses happen in the consumer’s account, and are billed to the consumer. If you want to limit the warehouse type or sizes available to a provider when running a template, call consumer.set_provider_run_configuration.

   5. Tell the provider that you have installed the clean room and approved provider-run analyses.

3. Provider

   1. After the consumer has installed the clean room, you must enable your 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. If a new consumer account installs the clean room later and you want to use their data in this template, you 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.

   2. Run the analysis by calling provider.submit_analysis_request with the template name, the table names, and the template arguments. You can optionally specify a warehouse size and type, as shown later in this topic.

      • Save the response ID, which is required to check the status and results of the analysis.

   3. Check 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.

Tip

If you change the provider-run analysis setting for your clean room, you must uninstall and then re-install the clean room for the change to take effect.

Specifying warehouse limits and choosing a warehouse type

Here is how a consumer sets a warehouse size and type limitation, and how a provider chooses a warehouse when running an analysis:

1. The consumer calls consumer.set_provider_run_configuration and specifies which warehouse sizes and types a provider can use for a specified template.

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

   Copy

2. The provider calls provider.view_warehouse_sizes_for_template to see which warehouse sizes and types are permitted for provider-run analyses on that template.

   CALL samooha_by_snowflake_local_db.provider.view_warehouse_sizes_for_template(
     $cleanroom_name,
     $template_name,
     $consumer_account_loc
   );
   

   Copy

3. The provider specifies which size and type warehouse to use in their analysis run request. A provider can specify only warehouse sizes and types that the consumer permits for that template.

   CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
     $cleanroom_name,
     $consumer_locator_id,
     $template1,
     ['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

Install and run the code example

You can download and install a complete running example of a clean room that enables and runs a provider-run analysis. To run this example, you need two Snowflake accounts in the same organization and cloud hosting region with the Clean Room environment installed.

1. Download the example notebook.

2. Install the notebook in both your provider and consumer accounts.

   To upload a notebook, do the following:

   1. In the navigation menu, select Projects » Notebooks.

   2. Select + Notebook » Import .ipynb file.

   3. Select the .ipynb file you downloaded.

   4. Name the file as desired, and choose a database and schema.

   5. Keep the default warehouse APP_WH.

   6. Select Create.

   7. Open the notebook in the provider account and complete the provider portion to create the clean room.

   8. Open the notebook in the consumer account and complete the consumer portion to install and configure the clean room and run the template.