Creating, joining, removing, and uninstalling clean rooms¶

This page shows how to create a basic clean room, join a clean room to which you have been invited, delete a clean room that you created, or remove a clean room that you have joined as a consumer.

Create a new clean room¶

You must have the proper permission in a Snowflake account to be able to create a clean room. The clean room creator is called the provider.

The Clean Rooms page in the web app lets you, as a provider, manage the lifecycle of a clean room, including creating and sharing. If you don’t have access to the clean rooms web app, speak to a clean rooms administrator for your Snowflake account.

To create and share a clean room, do the following:

Sign in to your clean room environment in the web app.
In the left navigation, select Clean Rooms.
Select + Clean Room. The creation process has the following steps:
1. Use the Add Data step to name the clean room and select the tables that are being shared with the consumer. The name can be 80 characters maximum, case-insensitive a-z, 0-9, spaces, and underscores.
2. Use the Specify Join Policies step to enable identity providers enabled by your clean rooms account administrator and select which columns the consumer can join on.
3. Use the Configure Analysis & Query step to define which templates are available in the clean room, template-specific configuration settings, and addtional features such as activation and privacy settings.
4. Use the Share Clean Room step to invite consumers to use the clean room to collaborate. You can also use the Enable Run Analysis & Query option to specify which collaborators can run analyses in the clean room.

For a full walkthrough of creating a new clean room in the clean room UI, try the clean rooms web app tutorial

To create a new clean room in code, you must be granted the SAMOOHA_APP_ROLE role in your account.

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;
SET cleanroom_name = 'Developer Tutorial';
CALL samooha_by_snowflake_local_db.provider.cleanroom_init(
  $cleanroom_name,
  'INTERNAL');      -- Use EXTERNAL to share outside your Snowflake org

Copy

After creating your clean room, you must, at minimum, perform the following steps to configure a basic clean room:

Import data into the clean room.
Set join policies on your data.
Specify one or more templates in the clean room.
Set column policies on your data for each template.
Set a default release directive.
Specify consumers to share the clean room with.
Publish the clean room.

For a full walkthrough of creating a new clean room in code, try the clean rooms code tutorial

Note

There is a limit to the number of (clean rooms + collaborators) that you can create in a single account. If you create too many test clean rooms, you might need to delete a few in order to create new clean rooms. If you need more clean rooms than your account can hold, contact Snowflake Support.

Install (join) a clean room¶

If you have been invited to join a clean room, you will receive an email message with a link to install, configure, and run the clean room in the clean room UI. You can follow the link and use the clean room UI, or install and run the clean room using code.

The Clean Rooms page in the web app lets you, as a consumer, install clean rooms that have been shared with you by a provider. To install a clean room, do the following:

Sign in to your clean room environment in the web app.
In the left navigation, select Clean Rooms.
On the Invited tab, find the clean room and select Join. You should get a direct link to this page in an invitation email when you are added as a collaborator in the clean room UI.
Select the tables that you want to use to collaborate with the provider’s data, then select Next.
Select any identity providers available in your Clean Room environment that you need to use in this clean room.
Specify which columns in your table can be joined, and the corresponding columns from the provider’s data.
Select Next.
Provide template-specific settings for any templates assigned to the clean room.
Click Finish, and optionally run a template immediately, or schedule a repeating run of that template.

If you have been invited to join a clean room as a consumer, you can install, configure, and run the clean room in code.

To join a clean room in code, open up the account that was invited to add the clean room, and run the following code:

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;
SET cleanroom_name = 'Developer Tutorial'; -- Get the actual clean room name and provider's account locator from the provider.
CALL samooha_by_snowflake_local_db.consumer.
  install_cleanroom($cleanroom_name, <PROVIDER_LOCATOR>);

Copy

After the clean room is installed, you must take the following steps, at minimum, to be able to run templates in that clean room:

Link your data.
Set join and column policies on your tables and for the templates that you want to run.
Run the template.

For a full walkthrough of joining a clean room in code, try the clean rooms code tutorial

Note

Some clean rooms throw the following error when you try to join it:

Application role `SAMOOHA_BY_SNOWFLAKE.DCR_DELEGATED_CLEANROOM_ROLE` does not exist
or not authorized.

If you encounter this error, run the following code and try joining the clean room again:

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE.APP_SCHEMA.PREPARE_MOUNT_SCRIPT();
EXECUTE IMMEDIATE FROM @SAMOOHA_BY_SNOWFLAKE.APP_SCHEMA.MOUNT_CODE_STAGE/dcr_loader.sql;

Copy

Delete a clean room that you created¶

After deletion, a clean room will no longer be visible to shared users the next time they open the clean room web app. If an analysis is in progress when a clean room is deleted, it might not complete before the clean room is deleted.

To use the clean room UI to delete a clean room that you created, do the following:

Sign in to your clean room environment in the web app.

In the left navigation, select Clean Rooms.

In the clean room to delete, select More () > Delete.

To delete a single clean room using the API, call provider.drop_cleanroom.

To list your created clean rooms, call provider.view_cleanrooms:

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

-- List created and published clean rooms
CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();
SELECT CLEANROOM_ID AS "cleanroom_name"
  FROM TABLE(RESULT_SCAN(last_query_id()))
  WHERE STATE = 'CREATED' AND IS_PUBLISHED = TRUE;

-- Specify a clean room name from the list and drop it
CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Copy

For a full walkthrough of creating, configuring, using, and deleting a clean room in code, try the clean rooms code tutorial

Uninstall (unjoin) a clean room¶

You can uninstall a clean room that you installed (joined) as a consumer. This will uninstall the clean room for all users in the account.

Sign in to your clean room environment in the web app.
In the left navigation, select Clean Rooms.
Navigate to Clean Rooms » Joined
In the clean room to uninstall, select More () > Leave.

To list your installed (joined) clean rooms

Call samooha_by_snowflake_local_db.consumer.view_cleanrooms and filter rows to IS_ALREADY_INSTALLED = TRUE. This shows clean rooms that are installed rather than simply invitations to join.

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();
SELECT CLEANROOM_ID AS "cleanroom_name"
  FROM TABLE(RESULT_SCAN(last_query_id()))
  WHERE IS_ALREADY_INSTALLED = TRUE;

CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);

Copy

To uninstall (unjoin) a single clean room:

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;
CALL samooha_by_snowflake_local_db.consumer.
  uninstall_cleanroom($cleanroom_name).

Copy

For a full walkthrough of creating, configuring, using, and deleting a clean room in code, try the clean rooms code tutorial

Adding or removing tables from a clean room¶

Here is how to add or remove (link or unlink) tables from a clean room:

When using the UI, only tables or views registered by an administrator can be linked into a clean room. If you don’t see a table or view as available for use in your clean room, ask your administrator to register the object in your account.

As a provider, you choose which tables to link into the clean room in the Add Data step when you create or edit a clean room.
As a consumer, you choose which tables to link the clean room in the Add Data step when you join or edit a clean room.

Once a table is added to a clean room, it cannot be removed from that clean room. You can, however, remove the data from the entire account. If you need to remove a table or view from a clean room, speak to your clean room administrator.