Installing the Snowflake Data Clean Rooms environment

Before you begin

A clean rooms environment is installed in the Snowflake account for all users in that account.

Users within an account are granted access to the clean rooms environment by a clean rooms administrator.

  • If the clean rooms environment is not installed for your account: Follow the installation instructions on this page.

  • If you have received an email invitation to join a clean room: Follow the link, provide your email and a new password, if directed. This will open the clean rooms web application where you can join and use a clean room. Note that you must provide the email address where you received the invitation. The password will be specific to your clean rooms account; we recommend not reusing your Snowflake password.

  • If the clean rooms environment is installed for your account, and you want access to it: Ask a clean rooms administrator for access to the API, the UI, or both.

Overview

Snowflake Data Clean Rooms comprises two environments:

  • The clean rooms UI: A no-code, browser-based environment that makes it easy for users to create or run analyses.

  • The clean rooms API: Access to a set of stored procedures used to create and manage clean rooms and run analyses.

These environments provide similar, but not exactly equivalent, capabilities. A clean rooms administrator installs one or both components in a Snowflake account, and can then grant users access to each environment individually.

Requirements to install Snowflake Data Clean Rooms

Account and user requirements

Here are the requirements to install Snowflake Data Clean Rooms in your Snowflake account:

  • The account must be the required Snowflake Edition:

    • To create clean rooms, you must have Enterprise Edition or higher.

    • To join and use a clean room created in another account, you must have Standard Edition or higher.

  • The account must allow key-pair authentication, which is used by the service account for authentication.

  • You must accept data sharing terms. If you have not accepted the Snowflake Customer-Controlled Data Sharing Functionality Terms, please contact Snowflake Support. Snowflake Data Clean Rooms leverage listings, which are part of the Snowflake Service and subject to your Service terms with Snowflake, including the Snowflake Customer-Controlled Data Sharing Functionality Terms and Snowflake Acceptable Use Policy.

  • You must not define an account-level default collation. You can check your collation state by running the following command: SHOW PARAMETERS LIKE 'DEFAULT_DDL_COLLATION' IN ACCOUNT;

  • (Clean rooms UI only) The Snowflake account must be a capacity account: this is an account that has an up-front capacity commitment. Snowflake On-Demand accounts cannot access the clean rooms UI.

  • (Clean rooms UI only) You must use multi-factor authentication (MFA) with a supported authenticator app.

If you do not meet all these requirements and need to upgrade, contact Snowflake Support.

Installer requirements

Here are the requirements for the person installing the clean rooms environment:

  • You must have an ACCOUNTADMIN role in a Snowflake account in order to install the clean rooms environment in that account.

  • The user with the ACCOUNTADMIN role must have a valid first name, last name, and email defined for their user object. To check, run DESCRIBE USER.

Install the clean rooms environment

Follow these steps to install a clean rooms environment in your Snowflake account.

You must always install the native app (step 1), but after that you can enable the clean rooms UI for browser usage, the clean rooms API for code usage, or both. We recommend installing both the UI and the API to support both coders and non-coders in your organization.

Note

Three sets of account credentials are involved in installing a clean rooms environment:

  • A Snowflake account: This is the Snowflake account used to install the clean rooms environment with ACCOUNTADMIN privilege.

  • A clean rooms account: This is the account used to log into the clean rooms web application. These credentials are maintained and managed by Snowflake Data Clean Room independently of your Snowflake account. Use a new password for this account. When you are signed in to the clean rooms web application, if you need to perform Snowflake administrator functions, you will sign in with your Snowflake credentials within the web app.

  • A service user: The web application uses a service user account to communicate with Snowflake. This user is granted limited permissions from your Snowflake account. You will create the service account during clean rooms installation, after which you do not need to save your service account credentials or manage the service account. You can see your service user details in the clean rooms UI in the Admin » Snowflake Admin page, under Snowflake.

1. Install the native application

Install the native application either in code or from the marketplace:

If you do not want to agree to the Marketplace provider and consumer terms:

Run the following code in your Snowflake account:

USE ROLE ACCOUNTADMIN
CREATE APPLICATION SAMOOHA_BY_SNOWFLAKE FROM LISTING 'GZSTZTP0KKO';
Copy
If you agree to the Marketplace provider and consumer terms:
  1. Set your current role to ACCOUNTADMIN

  2. Install the Snowflake Data Clean Rooms application from the Snowflake Marketplace

  3. Select Get and accept the default options.

Installation takes several minutes.

2. Install the clean rooms API

The clean rooms API is used for programmatic creation and usage of clean rooms.

Here are the steps to install the clean rooms API in your Snowflake account:

  1. After installing the native application, launch it in Snowflake: Data products » Apps » Snowflake Data Clean Rooms » Launch app. This opens a worksheet with SQL commands.

  2. Run the SQL commands to install clean rooms API, with the following notes:

    • If you renamed the native application during installation you will need to modify the script as indicated in the script comments.

    • If you want to review the full installation script before running it, uncomment the DRY_RUN=TRUE script line and run all commands up to and including that line to see the script contents. Note that you should not run the installation script exposed by that command manually, as it might result in an incomplete installation.

    • Note that installation takes several minutes.

  3. Confirm that you can access the API:

    USE ROLE samooha_app_role;
    USE WAREHOUSE app_wh;
    CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.CHECK_MOUNT_STATUS();
    
    Copy

    If this returns FALSE, see the troubleshooting section below.

  4. Grant API access to other users in your Snowflake account:

    • To add users with full abilities to create and manage clean rooms, run GRANT ROLE SAMOOHA_APP_ROLE to USER USER

    • To add users with consumer-run permissions only, create one or more Snowflake roles and grant users access to this role. Then grant run access to specific clean rooms by calling consumer.grant_run_on_cleanrooms_to_role.

  5. (Optional) Install the clean rooms UI to enable no-code access to your clean rooms or other features such as scheduled queries.

3. Enable the clean rooms UI

The clean rooms UI provides an easy no-code environment to manage your clean rooms account and create clean rooms and run analyses. It also provides some additional functionality not available in the clean rooms API, such as scheduled queries, third-party activation, and useful predefined templates.

Important

Clean rooms manages its own user credentials, separately from Snowflake. We recommend using a different password for your clean rooms account and your Snowflake account.

Here is how to install the clean rooms UI for your Snowflake account:

  1. Configure your network policies to allow the clean rooms UI to access your Snowflake account. (Required only if your Snowflake account uses a network policy to control network traffic.)

  2. Create a service user. This service user is used by the clean rooms UI to communicate with Snowflake.

    1. Sign in to Snowsight with your Snowflake administrator credentials and create a service user as shown below. Provide a password and an email address that you can access. We recommend using a distribution list rather than a personal email.

      USE ROLE USERADMIN;
      CREATE USER <SERVICE-USER-USERNAME> PASSWORD='<SERVICE-USER-PASSWORD>'
      FIRST_NAME='DCR' LAST_NAME='Service User'
      EMAIL='<SERVICE-USER-EMAIL-ADDRESS>';
      
      Copy
    2. Save the service user name and password outside of Snowsight, because you’ll use during the installation process.

    3. Sign out of the current user in Snowsight, then sign back in to the same account but with the service user’s credentials.

    4. Open your profile and select Resend verification email.

    5. Open the verification email and follow the link to verify the service user email address. No need to sign in to Snowsight again with the service user’s credentials.

  3. Create your clean rooms UI account. You will create a clean rooms account in this step. Clean rooms account credentials are email and password, and are independent of your Snowflake credentials. You will use these credentials to sign in to the clean rooms UI.

    1. Visit the clean rooms account registration page. You’ll need to provide the following information:

      • Your Snowflake account identifier. In your Snowsight account admin account, open the profile menu » Account » View account details » Account Identifier » For assistive technology, the copy button. (Copy).

      • An email address that you can access. The email you provide here will be your clean rooms user name (and cannot be changed later). This doesn’t need to be related to your Snowflake account email. If you are using an email service that supports decorators, you can use decorators to help you organize your clean room UI accounts. For example: myldap+cleanroom_admin@example.com.

    2. Verify your account’s email address by following the link emailed to your account to set up your clean rooms UI account. You will provide the following information:

      • Email: This is the email address where you got the verification email. This is the username in your clean room credentials.

      • Company name: A read-only name for this clean rooms account. The name you provide is shown in the clean rooms UI account chooser and also in your account profile in the clean rooms UI. Choose something that is unique for all your clean rooms accounts, and is meaningful in the account chooser when your clean rooms credentials can access multiple clean rooms accounts. This name is visible only to providers in your account, not to consumers, and can be changed only by contacting Snowflake support. Example useful names might be “Test consumer” and “Test provider”, if you use one clean rooms account as a consumer account an another as a provider account.

      • Password for this clean rooms account.

  4. Complete UI setup. This step applies your network policy to the service user, migrates the service user from password authentication to key-pair authentication, and grants SAMOOHA_APP_ROLE to the service user. Follow these steps to complete the basic UI setup:

    1. Sign in to the clean rooms UI with your clean room user credentials: name (email) and password.

    2. Open Admin » Snowflake Admin » Connect to Snowflake account and sign in with your Snowflake account credentials.

    3. Enter your service account user name and select Save.

    4. You can now use the clean rooms UI.

  5. Configure the clean rooms UI environment:

    • Register data in your environment. In order to use Snowflake data in a clean room, it must first be registered by an account administrator. Only registered data can be linked into a clean room by a clean room creator.

    • Add DCR administrators. DCR administrators manage the web application on a day-to-day basis, add other administrators and clean room managers, can enable and configure connectors available to clean rooms, and do other tasks.

    • Add clean room managers. Clean room managers are able to use the web application to create clean rooms, or act as consumers when a clean room is shared with them.

    • Add developers. Grant API access to developers in your Snowflake account so they can create or consume clean rooms in your account.

    • Enable SSO for your account. If your account uses SSO to manage authentication, learn how to enable SSO for your clean rooms environment.

    • Enable Cross-Cloud Auto-Fulfillment. By default, clean rooms can be shared only with consumers in the same underlying cloud region as the clean room creator. If you want to enable a clean room to be shared with consumers in a different cloud region, you must enable Cross-Cloud Auto-Fulfillment for your account.

Troubleshooting installation

Use this section to troubleshoot problems you might have after completing the steps in this topic.

Symptom: Insufficient privileges

Solution: Ensure that the IP addresses associated with the web app are allowed by your network policies. For a list of these IP addresses, see Configure network policies.

Symptom: Installation is successful, but the web app is not functioning properly.

Solution #1: Use the DESCRIBE USER command to double-check that the Snowflake user that you used to configure Snowflake has a valid first name, last name, and email. If the user is missing any of these, execute the ALTER USER command to specify them.

Solution #2: Try uninstalling the Snowflake Native App for Snowflake Data Clean Rooms, and then re-installing it.

  • To uninstall the app, see Uninstall a Snowflake Native App. If you installed the application with its default name, it is called SAMOOHA_BY_SNOWFLAKE.

  • To re-install the app:

    1. Sign in to the web app.

    2. In the left navigation pane, select Snowflake Admin.

    3. Select Login to Snowflake, and authenticate as a Snowflake user with the ACCOUNTADMIN role.

    4. Use the DESCRIBE USER command to confirm that the Snowflake user with the ACCOUNTADMIN role that you just used to authenticate has a valid first name, last name, and email. If the user is missing any of these, execute the ALTER USER command to specify them.

    5. To install the Snowflake Native App, select Install.

    6. Accept the default name of the application during the installation process.