View and subscribe to listings and data exchanges

This document describes how to view and subscribe to listings and data exchangesin BigQuery sharing (formerly Analytics Hub). As a BigQuery sharingsubscriber, you can view and subscribe to listings and data exchanges for whichyou have access. Subscribing to a listing or a data exchange inBigQuery sharing creates a linked dataset in your Google Cloud project.

Required roles

To get the permissions that you need to use listings, ask yourBigQuery sharing administrator to grant you the followingIdentity and Access Management (IAM) roles on the BigQuery sharing subscriberproject:

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.create orbigquery.datasets.* to perform additional actions on datasets.
  • Query datasets:bigquery.jobs.create orbigquery.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:

  1. In the Google Cloud console, go to theSharing (Analytics Hub) page.

    Go to Sharing (Analytics Hub)

  2. ClickSearch listings. A dialog appears containing listings that you canaccess.

  3. To filter listings by their name or description, enter the name ordescription of the listing in theSearch for listings field.

  4. In theFilters section, you can filter listings based on the followingfields:

    • Listings: select whether you want to view private listings, publiclistings, orlistingswithin your organization.

    • 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 their commercial datasets. After requesting access,the data provider contacts you to share their datasets.

  5. Browse through the filtered listings.

Discover data exchanges

To discover data exchanges, follow these steps:

  1. In the Google Cloud console, go to theSharing (Analytics Hub) page.

    Go to Sharing (Analytics Hub)

  2. ClickSearch listings. A dialog appears containing listings and dataexchanges that you can subscribe to.

  3. To filter data exchanges by their name or description, enter the name ordescription of the data clean room exchange in theSearch for listingsfield.

  4. In theFilters section, you can filter data clean room exchanges based onthe following fields:

    • Listings: select theClean rooms checkbox to view the data cleanrooms 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.

  5. 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 avoid placing data in 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

  1. To view a list of listings that you have access to, follow the steps inDiscover listings.

  2. Browse through the listings and click a listing that you want to subscribeto. A dialog with the listing details appears. The dialog shows if theprovider enabled subscriber email logging. In theAdditional detailssection, you can see the regions where the provider made the listingavailable.

  3. 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.

  4. If you don't have the Analytics Hub API enabled in your project,an error message appears with a link to enable the API. ClickEnable Analytics Hub API.

  5. In theCreate linked dataset dialog, specify the following details:

    Note: Linked dataset replicas are created on a best-effort basis.If permissions are missing, replicas aren't created.

  6. 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 selected secondary replica regions. Ensurethat the specified regions in thelocation property and in thedestinationDataset.replica_locations field are regions where the associatedlisting is available.

Note: Linked dataset replicas are created on a best-effort basis. Ifthebigquery.datasets.update permission is missing on the linked dataset,replicas aren't created.

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 is available inthejob_principal_subject field of theINFORMATION_SCHEMA.SHARED_DATASET_USAGE view.

If you enable stored procedure sharing(Preview), the listing responsecontainsstored_procedure_config: true.

Note: BigQuery sharing subscribers mustauthorize shared stored proceduresin a linked dataset to read from and write to certain resources owned bythe subscriber.

Subscribe to data exchanges

Subscribing to adata exchangegives you read-only access to the data in the data clean room exchange bycreating alinked datasetin your project.

To subscribe to a data clean room exchange, follow these steps:

Console

  1. To view a list of data clean room exchanges that you have access to, followthe steps inDiscover data exchanges.

  2. Browse through the data clean room exchanges and click a data clean roomexchange that you want to subscribe to. A dialog with the data clean roomexchange details appears.

  3. If you click a data clean room exchange that you can subscribeto, then clickSubscribe to open theAdd data clean room to project dialog.

  4. If you don't have the Analytics Hub API enabled in your project,an error message appears with a link to enable the API. ClickEnable Analytics Hub API.

  5. In theAdd data clean room to project dialog, specify the followingdetails:

    • Destination: specify the name of the project in which you want to addthe dataset.

  6. 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 exchangethat you want to subscribe to.
  • LOCATION: the location for your data exchange thatyou want 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

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In theClassic Explorer pane, clickcategoryClassic Explorer:

    Highlighted button for the Classic Explorer pane.

    If theClassic Explorer pane is not visible, clickExpand left pane to open the pane.

  3. In theClassic Explorer pane, click the project name that contains theAnalytics Hub linked dataset iconlinked 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=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

ReplacePROJECT_ID with your Google Cloud project ID.

Note: If a BigQuery sharing publisherremoves the subscription,then the linked dataset details page shows that the dataset is unlinked.You can delete anunlinked dataset because you can'tquery an unlinked dataset.

Query linked datasets

You can query tables and views in your linked datasetsin the same way youquery 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:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In theExplorer pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project name, clickDatasets, andthen click the name of the linked dataset to open it.

  4. In the details pane, clickEdit details and then specify the following details:

    1. To add labels, seeAdding a label to a dataset.

    2. To enablecollation,expand theAdvanced options section and follow these steps:

      1. SelectEnable default collation.
      2. From theDefault collation list, select an option.

  5. 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 datasetis unlinked from theshared dataset.Since this is a publisher-initiated action on a subscriber-owned resource, thelinked dataset remains in the BigQuery sharing subscriber's project in anunlinked state. You can remove the unlinked dataset by deleting it.

To delete a linked dataset, do the following:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In theExplorer pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project name, clickDatasets, andthen click the name of the linked dataset to open it.

  4. ClickDelete.

  5. In theDelete linked dataset? dialog, confirm deletion by typingdelete.

  6. ClickDelete.

What's next

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 2026-02-18 UTC.