Share sensitive data with data clean rooms

Data clean rooms provide a security-enhanced environment in which multiple parties can share, join, and analyze their data assets without moving or revealing the underlying data.

BigQuery data clean rooms use the BigQuery sharing (formerly Analytics Hub) platform. While standard BigQuery sharing data exchanges let you share data across organizational boundaries at scale, data clean rooms address use cases for sharing sensitive and protected data. Data clean rooms provide additional security controls to protect the underlying data and enforce analysis rules defined by the data owner.

Primary use cases include the following:

• Campaign planning and audience insights. Let two parties (for example, sellers and buyers) mix first-party data and improve data enrichment in a privacy-centric way.
• Measurement and attribution. Match customer and media performance data to better understand the effectiveness of marketing efforts and make more informed business decisions.
• Activation. Combine customer data with data from other parties to enrich customer understanding, which lets you improve segmentation capabilities and media activation.

Data clean rooms also support several use cases beyond the marketing industry:

• Retail and consumer packaged goods (CPG). Optimize marketing and promotional activities by combining point-of-sale data from retailers and marketing data from CPG companies.
• Financial services. Improve fraud detection by combining sensitive data from other financial and government agencies. Build credit risk scoring by aggregating customer data across multiple banks.
• Healthcare. Share data between doctors and pharmaceutical researchers to learn how patients are reacting to treatments.
• Supply chain, logistics, and transportation. Combine data from suppliers and marketers to get a complete picture of how products perform throughout their lifecycle.

Roles

There are three main roles in BigQuery data clean rooms:

• Data clean room owner: manages permissions, visibility, and membership of one or more data clean rooms within a Google Cloud project. The data clean room owner can assign the data contributor and data clean room subscriber roles to users. This role is analogous to the Analytics Hub Admin IAM role.
• Data contributor: publishes data to a data clean room. In many cases, a data clean room owner is also a data contributor. This role is analogous to the Analytics Hub Publisher IAM role.
• Data clean room subscriber: subscribes to the data published in a data clean room and runs queries on the data. This role is analogous to a combination of the Analytics Hub Subscriber and Analytics Hub Subscription Owner IAM roles.

Architecture

BigQuery data clean rooms use a publish and subscribe model of BigQuery data. BigQuery architecture separates compute and storage, which lets data contributors share data without making multiple copies of the data. The following diagram shows the BigQuery data clean room architecture:

Data clean room

A data clean room is an environment for sharing sensitive data that helps prevent raw access and enforces query restrictions. Only users or groups added as data clean room subscribers can subscribe to the shared data. Data clean room owners can create any number of data clean rooms in BigQuery sharing.

Shared resources

A shared resource is the unit of data sharing in a data clean room. The resource must be a BigQuery table, view, or routine (table-valued function). As a data contributor, you create or use an existing BigQuery resource in your project to share with your data clean room subscribers.

Listings

A data contributor creates a listing when they add data to a data clean room. It contains a reference to the data contributor's shared resource along with descriptive information that helps subscribers use the data. As a data contributor, you can create a listing and include information such as a description, sample queries, and links to documentation for your subscribers.

Linked datasets

A linked dataset is a read-only BigQuery dataset that serves as a symbolic link to all data in a data clean room. When data clean room subscribers query resources in a linked dataset, data from the shared resources is returned, satisfying analysis rules set by the data contributor. As a subscriber, a linked dataset is created inside your project when you subscribe to a data clean room. No copy of the data is created, and subscribers can't see certain metadata, such as view definitions.

Analysis rules

As a data contributor, you configure analysis rules on the resources that you share in the data clean room. Analysis rules prevent raw access to underlying data and enforce query restrictions. For example, data clean rooms support the aggregation threshold analysis rule, which lets data clean room subscribers analyze data only through aggregation queries.

Data egress controls

Data egress controls automatically prevent data clean room subscribers from copying and exporting raw data from a data clean room. Data contributors can configure additional controls to prevent copying and exporting query results that subscribers obtain.

Query templates

Query templates let data clean room owners and BigQuery sharing publishers share predefined queries without sharing the underlying resources of tables and views.

Predefined queries use table-valued functions (TVFs) in BigQuery that allow an entire table or specific fields to pass as input parameters and return a table as the output.

Limitations

BigQuery data clean rooms have the following limitations:

• You can set analysis rules only on views, not on tables or materialized views. Because of this limitation, if a data contributor directly shares tables or materialized views, or views without analysis rules, into a data clean room, then data clean room subscribers have raw access to the data in those resources.
• While analysis rules provide privacy controls, they aren't guaranteed to block every unauthorized query designed to extract raw data. To secure your information, use query templates in data clean rooms to review and approve queries, effectively blocking unauthorized attempts up front.
• Because data clean rooms use the BigQuery sharing platform, all BigQuery sharing limitations apply.
• Data clean rooms are only available in BigQuery sharing regions.
• As a data clean room subscriber, you can't search for shared resources in Knowledge Catalog or Data Catalog.
• As a data clean room subscriber, you can't query INFORMATION_SCHEMA views on linked datasets.
• As a data contributor, you can't publish an entire dataset directly to a data clean room.
• As a data contributor, you can't publish models or routines (outside of query templates) to a data clean room.
• You can add a maximum of 100 shared resources to a data clean room. If you need to increase this limit, contact bq-dcr-feedback@google.com.
• Listings for multiple regions aren't supported in data clean rooms.

Before you begin

Grant Identity and Access Management (IAM) roles to give users the necessary permissions to perform each task in this document, enable the Analytics Hub API, and assign the Analytics Hub Admin role to your data clean room owner.

Required permissions

To get the permissions that you need to use data clean rooms, ask your administrator to grant you the BigQuery Data Editor (roles/bigquery.dataEditor) IAM role. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to use data clean rooms. To see the exact permissions that are required, expand the Required permissions section:

You might also be able to get these permissions with custom roles or other predefined roles.

For more information about IAM roles and permissions in BigQuery, see Introduction to IAM.

Enable the Analytics Hub API

To enable the Analytics Hub API, select one of the following options:

gcloud services enable analyticshub.googleapis.com

After you enable the Analytics Hub API, you can access the Sharing (Analytics Hub) page.

Assign the Analytics Hub Admin role

Your data clean room owner, the user who creates the data clean room, must have the Analytics Hub Admin role (roles/analyticshub.admin). To learn how to grant this role to other users, see Create BigQuery sharing administrators.

Data clean room owner workflows

As a data clean room owner, you can do the following:

• Create a data clean room.
• Update data clean room properties.
• Delete a data clean room.
• Manage data contributors.
• Manage data clean room subscribers.
• Share a data clean room.

Additional data clean room owner permissions

You must have the Analytics Hub Admin role (roles/analyticshub.admin) on your project to perform data clean room owner tasks. You can also assign this role at the folder or organization level, if applicable.

Create a data clean room

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges?data_exchange_id=CLEAN_ROOM_ID -d
  '{
    display_name: "CLEAN_ROOM_NAME",
    sharing_environment_config: {dcr_exchange_config: {}}
  }'

Update a data clean room

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X PATCH https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID?updateMask=UPDATEMASK -d
'{
  display_name: "CLEAN_ROOM_NAME",
  sharing_environment_config: {dcr_exchange_config: {}}
}'

Delete a data clean room

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X DELETE https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges?data_exchange_id=CLEAN_ROOM_ID

When you delete a data clean room, all the listings within it are deleted. However, the shared resources and linked datasets are not deleted. The linked datasets are unlinked from the source datasets, so querying resources in the data clean room starts to fail for data clean room subscribers.

Manage data contributors

As a data clean room owner, you manage which users can add data to your data clean rooms (your data contributors). To let a user add data to a data clean room, grant them the Analytics Hub Publisher role (roles/analyticshub.publisher) on a specific data clean room: