View and subscribe to listings and data exchanges
As a BigQuery sharing subscriber, you can view and subscribe tolistings and data exchanges for which you have access. Subscribing to a listing or a data exchange creates alinked dataset in your project.
Required roles
To get the permissions that you need to use listings, ask yourBigQuery sharing administrator to grant you the following Identity and Access Management (IAM) roles on the BigQuery sharing subscriberproject:
- Discover listings:Analytics Hub Viewer (
roles/analyticshub.viewer) - Discover data exchanges:Analytics Hub Viewer (
roles/analyticshub.viewer) Subscribe to listings:BigQuery User (
roles/bigquery.user)- To subscribe to listings, you must also ask the BigQuery sharinglisting publisher to grant you theAnalytics Hub Subscriber role(
roles/analyticshub.subscriber) on their listing, exchange, or project,depending on the scope that's most appropriate for your use case.
- To subscribe to listings, you must also ask the BigQuery sharinglisting publisher to grant you theAnalytics Hub Subscriber role(
Subscribe to data exchanges:BigQuery User (
roles/bigquery.user)- To subscribe to data exchanges in the context of data clean room exchanges,you must also ask the BigQuery sharing exchange publisher to grantyou the Analytics Hub Subscriber role (
roles/analyticshub.subscriber) onthe specific data clean room. Additionally, you must ask the destinationproject owners in the BigQuery sharing subscriber organization togrant you theAnalytics Hub Subscription Owner role(roles/analyticshub.subscriptionOwner) on the destination project.
- To subscribe to data exchanges in the context of data clean room exchanges,you must also ask the BigQuery sharing exchange publisher to grantyou the Analytics Hub Subscriber role (
View linked datasets:BigQuery Data Viewer (
roles/bigquery.dataViewer)Query linked datasets:BigQuery Data Viewer (
roles/bigquery.dataViewer)Update linked datasets:BigQuery Data Owner (
roles/bigquery.dataOwner)View table metadata:BigQuery Data Viewer (
roles/bigquery.dataViewer)Delete linked datasets:BigQuery Admin (
roles/bigquery.admin)
For more information about granting roles, seeManage access to projects, folders, and organizations.
These predefined roles contain the permissions required to perform the tasks inthis document. To see the exact permissions that are required to create andquery datasets, expand theRequired permissions section:
Required permissions
- Create new datasets:
bigquery.datasets.createorbigquery.datasets.*to perform additional actions on datasets. - Query datasets:
bigquery.jobs.createorbigquery.jobs.*to perform additional actions on jobs.
You might also be able to get these permissions withcustom rolesor otherpredefined roles.
Discover listings
To discover public and private listings, follow these steps:
In the Google Cloud console, go to theSharing (Analytics Hub) page.
ClickSearch listings. A dialog appears containing listings that you canaccess.
To filter listings by their name or description, enter the name ordescription of the listing in theSearch for listings field.
In theFilters section, you can filter listings based on the followingfields:
Listings: select whether you want to view private listings, publiclistings, orlistingswithin your org.
Categories: select one or more categories.
Location: select a location. You can only search by dataexchange location. For more information, seeSupported regions.
Provider: select the data provider. Some data providers require you torequest access to theircommercial datasets. After requesting access,the data provider contacts you to share their datasets.
Browse through the filtered listings.
Discover data exchanges
To discover data exchanges, follow these steps:
In the Google Cloud console, go to theSharing (Analytics Hub) page.
ClickSearch listings. A dialog appears containing listings and data exchanges that you cansubscribe to.
To filter data exchanges by their name or description, enter the name ordescription of the data clean room exchange in theSearch for listings field.
In theFilters section, you can filter data clean room exchanges based on the followingfields:
Listings: select theClean rooms checkbox if you want to view the data clean rooms shared with you.
Categories: select one or more categories.
Location: select a location. You can only search by the dataexchange location. For more information, seeSupported regions.
Browse through the filtered data clean rooms.
Subscribe to listings
Subscribing to alistinggives youread-only access to the data in the listing by creating alinked datasetin your project.
Caution: We recommend that you don't put data into a project that is within aVPC Service Controls perimeter. If you do so, then you must add the appropriateingress and egress rules.To subscribe to a listing, follow these steps:
Console
To view a list of listings that you have access to, follow the steps inDiscover listings.
Browse through the listings and click a listing that you want to subscribeto. A dialog containing the details of the listing appears. In this dialog,you can see if the provider enabled subscriber email logging. In theAdditional details section, you can see what regions the provider hasmade the listing available in.
If you don't have access to subscribe to a listing, such as a listingreferencing acommercial dataset, then clickRequest access orPurchase via Marketplace. If you click a dataset that you can subscribeto, then clickSubscribe to open theCreate linked dataset dialog.
If you don't have the Analytics Hub API enabled in your project,an error message appears with a link to enable the API. ClickEnableAnalytics Hub API.
In theCreate linked dataset dialog, specify the following details:
- Project: specify the name of the project in which you want to add thedataset.
- Linked dataset name: specify the name of the linked dataset.
Primary region: select the region where you want to create thelinked dataset.
Note: The selected primary region doesn't need to be the same as theprovider's primary region. You might choose to colocate your linkeddataset in the same region as the provider to minimize data replicationlatency.Optional:Replica regions(Preview): select the region orregions where you want to create additional linked dataset secondaryreplicas. You might choose to colocate your linked dataset in the sameregion as your other data to minimize egress and facilitate cross-datasetjoins. To create linked dataset replicas, you must have the
bigquery.datasets.updatepermission.
To save your changes, clickSave. The linked dataset is listed in yourproject.
API
Use theprojects.locations.dataExchanges.listings.subscribe method.
POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID:subscribe
Replace the following:
PROJECT_ID: the project ID of the listing that youwant to subscribe to.LOCATION: the location for your listing that youwant to subscribe to.DATAEXCHANGE_ID: the data exchange ID of thelisting that you want to subscribe to.LISTING_ID: the listing ID that you want tosubscribe to.
In the body of the request, specify the dataset where you want to create thelinked dataset.
To create a subscription with linked dataset replicas available in multipleregions (Preview), specify the primaryregion of the linked dataset using thelocation field in the request body.For the secondary regions where you want to create linked dataset replicas,you can optionally use thedestinationDataset.replica_locations field inthe request body and list all the desired secondary replica regions. Ensurethat the specified regions in thelocation property and in thedestinationDataset.replica_locations field are regions where the associatedlisting is available.
If the request is successful, the response body contains thesubscription object.
If you enable subscriber email logging for the data exchange or listing withthelogLinkedDatasetQueryUserEmail field, the subscription response containslog_linked_dataset_query_user_email: true. The logged data isavailable in thejob_principal_subject field of theINFORMATION_SCHEMA.SHARED_DATASET_USAGE view.
If you enable stored procedure sharing(Preview), the listing responsecontainsstored_procedure_config: true.
Subscribe to data exchanges
Subscribing to adata exchangegives you read-only access to the data in the data clean room exchange by creating alinkeddataset in yourproject.
To subscribe to a data clean room exchange, follow these steps:
Console
To view a list of data clean room exchanges that you have access to, follow the steps inDiscover data exchanges.
Browse through the data clean room exchanges and click a data clean room exchange that you want to subscribeto. A dialog containing the details of the data clean room exchange appears.
If you click a data clean room exchange that you can subscribeto, then clickSubscribe to open theAdd data clean room to project dialog.
If you don't have the Analytics Hub API enabled in your project,an error message appears with a link to enable the API. ClickEnableAnalytics Hub API.
In theAdd data clean room to project dialog, specify the following details:
- Destination: specify the name of the project in which you want to add thedataset.
To save your changes, clickSave. The linked dataset is listed in yourproject.
API
Use theprojects.locations.dataExchanges.subscribe method.
POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID:subscribe
Replace the following:
PROJECT_ID: the project ID of the data exchange that youwant to subscribe to.LOCATION: the location for your data exchange that youwant to subscribe to.DATAEXCHANGE_ID: the data exchange ID that you wantto subscribe to.
In the body of the request, specify the dataset where you want to create thelinked dataset.
If the request is successful, the response body contains thesubscription object.If you have enabled subscriber email logging(Preview) for the data exchange,the subscription response containslog_linked_dataset_query_user_email: true.
View linked datasets
Linked datasets are displayed together with other datasets in theGoogle Cloud console.
To view linked datasets in your project, follow these steps:
Console
In the Google Cloud console, go to theBigQuery page.
In the left pane, clickcategoryClassic Explorer:
If you don't see the left pane, clickExpand left pane to open the pane.
In theClassic Explorer pane, click the project name that contains the
linked dataset.
Alternatively, you can also useData Catalog (deprecated) orDataplex Universal Catalogto search and view linked datasets. To match all BigQuery sharinglinked datasets, use thetype=dataset.linked predicate. For moreinformation, seeData Catalog search syntaxorDataplex Universal Catalog search syntax.
Cloud Shell
Run the following command:
PROJECT=<your project ID> \for dataset in $(bq ls --project_id $PROJECT | tail +3); do [ "$(bq show -d --project_id $PROJECT $dataset | egrep LINKED)" ] && echo $dataset; done
Query linked datasets
You can query tables and views in your linked datasetsin the same way you wouldquery any other BigQuery table.
Update linked datasets
Resources in a linked dataset areread-only. You can't edit the data ormetadata for resources in linked datasets, or specify permissions for individualresources.
You can only update the description and labels of your linked datasets.Changes to a linked dataset don't affect the source or shared datasets.
To update the description and labels of a linked dataset, follow these steps:
In the Google Cloud console, go to theBigQuery page.
In the left pane, click
Explorer:
In theExplorer pane, expand your project name, clickDatasets, andthen click the name of the linked dataset to open it.
In the details pane, clickEdit details and then specify the following details:
- To add labels, seeAdding a label to a dataset.
To enablecollation,expand theAdvanced options section and follow these steps:
- SelectEnable default collation.
- From theDefault collation list, select an option.
ClickSave.
View table metadata
To view the underlying table metadata, query theINFORMATION_SCHEMA.TABLESview:
SELECT * FROM `LINKED-DATASET.INFORMATION_SCHEMA.TABLES`ReplaceLINKED-DATASET with the name of your linked dataset.
Note:Region-basedINFORMATION_SCHEMA queriesdon't return metadata of linked tables. To learn aboutINFORMATION_SCHEMAviews that don't support dataset qualifiers for linked datasets, seeLimitations.Unsubscribe from or delete linked datasets
To unsubscribe from a dataset, you must delete the linked dataset. Deleting alinked dataset doesn't delete the source dataset.
You cannot retrieve a linked dataset after you delete it. However, you canrecreate the deleted linked dataset bysubscribing to the listing again and adding thedataset and the linked datasets created from Google Cloud Marketplace-integratedlistings to your project.
If yoursubscription is removedby a BigQuery sharing publisher, then yourlinked datasetgets unlinked from theshared dataset.Since this is a publisher-initiated action on a subscriber-owned resource, thelinked dataset remains dangling in the BigQuery sharing subscriber'sproject. The subscriber can remove the dangling dataset by deleting it.
To delete a linked dataset, do the following:
In the Google Cloud console, go to theBigQuery page.
In the left pane, click
Explorer:In theExplorer pane, expand your project name, clickDatasets, andthen click the name of the linked dataset to open it.
ClickDelete.
In theDelete linked dataset? dialog, confirm deletion by typingdelete.
ClickDelete.
What's next
- Learn aboutBigQuery sharing.
- Learn aboutmanaging listings.
- Learn aboutmanaging data exchanges.
- Learn aboutBigQuery sharing audit logging.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.