Registering data¶
This topic describes how to register data so that it can be linked into a Snowflake Data Clean Room.
Supported objects¶
The following object types can be linked into clean rooms:
Tables
Dynamic tables
Views
Materialized views
Secure views. The owner of a secure view must be the SAMOOHA_APP_ROLE role.
Note
†External and Iceberg tables must be enabled before they can be used in a clean room.
Registering data objects¶
Before users can link data into a Snowflake Data Clean Room, the data must first be registered. Registering data grants USAGE and SELECT privileges on the object to SAMOOHA_APP_ROLE, which is used by the clean room environment to access data. If you register a database or schema, all of the child objects are registered as well. You must have MANAGE GRANTS privilege on an object to be able to link it.
You can register databases, schemas, and objects using the clean room UI or the clean room API. Using the clean room UI is simpler, but requires that you have the ACCOUNTADMIN role. Using the developer APIs, you can register any object on which you have OWNERSHIP privilege without using the ACCOUNTADMIN role.
Important
Registering a database or schema does not register objects added after the registration. You must either register the new object individually or use the clean room UI to navigate to Admin > Snowflake Admin > Database Registration and select Resync.
You can link only data registered by your account. That is, a provider can’t link data registered by the consumer and a consumer can’t link data registered by the provider. Once data is linked into a clean room, it can be accessed by anyone with access to the clean room, subject to the linking party’s settings (such as join and column policies).
Follow the steps below to register a database, schema, or object using the clean room UI:
Sign in to the clean room UI as an account administrator and then take one of the following steps:
If using a managed account, select Admin > My Account.
If using a Snowflake account, select Admin > Snowflake Admin and sign in to Snowflake as a user with the ACCOUNTADMIN role.
Select Admin > Snowflake Admin.
Select Log in to Snowflake, and authenticate as a user with the ACCOUNTADMIN role.
To enable external or Iceberg tables in the account, enable the External & Iceberg Tables toggle.
In the Access management for Snowflake objects section, select Edit, and then select the database, schema, or object to make its data linkable by users in this account.
Select Save.
Use the clean room API to register databases, schemas, and objects programmatically. Note that you need MANAGE GRANTS privilege on an object to register it.
External and Iceberg tables are registered differently than other object types.
The following procedures are available to register or unregister objects:
Object type |
Register |
Unregister |
|---|---|---|
Database |
|
|
Schema |
|
|
Managed access schema |
|
|
Any other supported object type |
|
|
Example:
USE ROLE <ROLE-WITH-MANAGE-GRANTS-PRIVILEGE>
CALL samooha_by_snowflake_local_db.library.register_schema(['MY_DB.MY_SCHEMA']);
Unregistering data objects¶
Once a table is linked into a clean room, it cannot be removed. However, you can unregister the object in the account, which will remove access by any clean rooms in that account.
If you want to remove data from a clean room or account, don’t simply delete the underlying object; this will cause the clean room to fail. Instead, use one of the following techniques to unregister the object.
When you unregister an object from an account, you should also update any clean rooms you created that used this data.
Queries by any collaborators that depend on deleted data will fail the next time they are run.
To unregister an object in an account:
Sign in to the clean room UI as an account administrator and then take one of the following steps:
If using a managed account, select Admin > My Account.
If using a Snowflake account, select Admin > Snowflake Admin and sign in to Snowflake as a user with the ACCOUNTADMIN role.
Select Admin > Snowflake Admin.
Select Log in to Snowflake, and authenticate as a user with the ACCOUNTADMIN role.
To enable external or Iceberg tables in the account, enable the External & Iceberg Tables toggle.
In the Access management for Snowflake objects section, select Edit, and then deselect the database, schema, or object to make its data unavailable to users in this account.
Select Save.
Update any clean rooms you created that depend on this data.
In the API, call the appropriate procedure to unregister an object from an account:
library.unregister_dblibrary.unregister_schemalibrary.unregister_managed_access_schemalibrary.unregister_objects
Enabling external and Apache Iceberg™ tables¶
To allow external tables and Iceberg tables to be linked into a clean room, the account must first be configured to enable use of external and Iceberg tables. After external and Iceberg tables are enabled, they can be registered, linked, and used the same as any other tables.
The process for enabling external and Iceberg tables varies, depending on whether you are managing the clean room using the clean room UI or the clean room API.
External and Iceberg table requirements¶
Both the provider and consumer accounts must enable external and Iceberg tables to allow full usage of a clean room that links in external or Iceberg tables.
Providers must always enable external tables and Iceberg tables when sharing a clean room with a managed account. This is because managed accounts always use external tables.
If the provider and consumer are in different regions, only the consumer can link external or Iceberg tables into a clean room.
The clean room UI controls external and Iceberg tables at the account level.
Warning
If the consumer account has not enabled this feature, consumers will be blocked from joining any clean rooms that link in external or Iceberg tables, or will be prevented from editing (but can still run) any already joined clean rooms that link in either type of table.
A DCR administrator in both the provider and consumer accounts must take the following steps:
Sign in to the clean room UI as an account administrator and then take one of the following steps:
If using a managed account, select Admin > My Account.
If using a Snowflake account, select Admin > Snowflake Admin and sign in to Snowflake as a user with the ACCOUNTADMIN role.
Enable the External & Iceberg Tables toggle. This enables the feature in both UI-created and API-created clean rooms.
External and Iceberg tables are now selectable in the administrator’s Access management for Snowflake objects panel, where they can be selected to make them available to clean rooms, the same as any other objects.
In code, you must enable external and Iceberg tables at both the account level and also for each clean room that links in external or Iceberg tables. If you have enabled external and Iceberg tables in the clean room UI, you do not need to enable them in code (you don’t need to take the steps listed here).
Warning
If only one account has enabled this feature for their account or clean room and linked in an external or Iceberg table, the other account will be able to run existing templates, but won’t be able to modify the clean room in any way until external and Iceberg tables are allowed in both that account and clean room.
To enable and use external or Iceberg tables for new clean rooms in code:
A user with the ACCOUNTADMIN role first enables external and Iceberg tables for the entire clean room environment in both the provider and consumer accounts:
USE ROLE ACCOUNTADMIN; CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();
Note
Existing clean rooms created with the clean room UI are not affected by this method. To update existing clean rooms created using the clean room UI you must either enable them in code individually, as shown in the next steps, or else enable clean rooms using the clean room UI, which enables the feature for all existing clean rooms.
A provider enables external and Iceberg tables for their clean room. Note that this triggers a security scan which, if successful, will generate a new clean room version, so you will need to update the default release directive.
USE ROLE SAMOOHA_APP_ROLE; CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom( $cleanroom_name); -- Call until scan is complete. call samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name); -- When scan is successful, update with patch version mentioned in return value from enable_external_tables_for_cleanroom. call samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '<PATCH_VERSION>');
A consumer must also enable use of external and Iceberg tables in the same clean room:
USE ROLE SAMOOHA_APP_ROLE; CALL samooha_by_snowflake_local_db.consumer.enable_external_tables_for_cleanroom( $cleanroom_name);
After external and Iceberg tables have been enabled for a clean room, collaborators can register and link these tables the same way as any other table.