View and subscribe to listings

As an Analytics Hub subscriber, you can view and subscribe to listings for which you have access. Subscribing to a listing creates a linked dataset in your project.

Required roles

To get the permissions that you need to use listings, ask your administrator to grant you the following Identity and Access Management (IAM) roles on the subscriber project:

• Discover listings: Analytics Hub Viewer (roles/analyticshub.viewer)

• Subscribe to listings: BigQuery User (roles/bigquery.user)

  • To subscribe to listings, you must also ask the listing publisher to grant you the Analytics Hub Subscriber role (roles/analyticshub.subscriber) on their listing, exchange, or project, whichever scope is most appropriate for your use case.

• 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, see Manage access.

These predefined roles contain the permissions required to perform the tasks in this document. To see the exact permissions that are required to create and query datasets, expand the Required permissions section:

Required permissions

• Create new datasets: bigquery.datasets.create or bigquery.datasets.* to perform additional actions on datasets.
• Query datasets: bigquery.jobs.create or bigquery.jobs.* to perform additional actions on jobs.

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

Discover listings

To discover public and private listings, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, click Add.

3. In the Add dialog, click Analytics Hub. The Analytics Hub dialog appears containing listings that you can access. For Salesforce Data Cloud listings, there is a button in the Explorer pane that automatically filters related listings.
   

   Alternatively, to open the Analytics Hub dialog you can also go to Analytics Hub and click Search listings.

4. To filter listings by their name or description, enter the name or description of the listing in the Search for listings field.

5. In the Filter section, you can filter listings based on the following fields:

   • Listings: select whether you want to view private listings, public listings, or listings within your org.

   • Categories: select the desired categories.

   • Location: select the desired location. For more information, see Supported regions.

   • Provider: select the data provider. Some data providers require you to request access to their commercial datasets. After requesting access, the data provider contacts you to share their datasets.

6. Browse through the filtered listings.

Subscribe to listings

Subscribing to a listing gives you read-only access to the data in the listing by creating a linked dataset in your project.

Caution: We recommend that you don't put data into a project that is within a VPC Service Controls perimeter. If you do so, then you must add the appropriate ingress 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 in Discover listings.

2. Browse through the listings and click a listing that you want to subscribe to. A dialog containing the details of the listing appears.

3. If you don't have access to subscribe to a listing, such as a listing referencing a commercial dataset, then click Request access or Purchase via Marketplace. If you click a dataset that you can subscribe to, then click Subscribe to open the Create 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. Click Enable Analytics Hub API.

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

   • Project: specify the name of the project in which you want to add the dataset.
   • Linked dataset name: specify the name of the linked dataset.

6. To save your changes, click Save. The linked dataset is listed in your project.

API

Use the projects.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 you want to subscribe to.
• LOCATION: the location for your listing that you want to subscribe to.
• DATAEXCHANGE_ID: the data exchange ID of the listing that you want to subscribe to.
• LISTING_ID: the listing ID that you want to subscribe to.

In the body of the request, specify the dataset where you want to create the linked dataset. If successful, the response body is empty.

View linked datasets

Linked datasets are displayed together with other datasets in the Google Cloud console.

To view linked datasets in your project, follow these steps:

Console

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

   Go to BigQuery

2. In the Explorer panel, click your project name that contains the linked dataset.

Alternatively, you can also use Data Catalog to search and view linked datasets. To matches all Analytics Hub linked datasets, use the type=dataset.linked predicate. For more information, see Data 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

Note: If a publisher removes the subscription, then the linked dataset details page shows that the dataset has been unlinked. You can delete an unlinked dataset because you can't query an unlinked dataset.

Query linked datasets

You can query tables and views in your linked datasets in the same way you would query any other BigQuery table.

Update linked datasets

Resources in a linked dataset are read-only. You can't edit the data or metadata for resources in linked datasets, or specify permissions for individual resources.

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 the BigQuery page.

   Go to BigQuery

2. In the Explorer panel, click your project name, and then click the linked dataset.

3. Expand the Actions option and click Open.

4. In the Details panel, click Edit details and then specify the following details:

   1. To add labels, see Adding a label to a dataset.

   2. To enable collation, expand the Advanced options section and follow these steps:

      1. Select Enable default collation.
      2. From the Default collation list, select an option.

5. Click Save.

View table metadata

To view the underlying table metadata, query the INFORMATION_SCHEMA.TABLES view:

SELECT * FROM `LINKED-DATASET.INFORMATION_SCHEMA.TABLES`

Replace LINKED-DATASET with the name of your linked dataset.

Note: Region-based INFORMATION_SCHEMA queries don't return metadata of linked tables. To learn about INFORMATION_SCHEMA views that don't support dataset qualifiers for linked datasets, see Limitations.

Delete linked datasets

If your subscription is removed by an Analytics Hub publisher, then your linked dataset gets unlinked from the shared dataset. You can delete an unlinked dataset because you can't query an unlinked dataset.

Deleting a linked dataset does not delete the source dataset. You cannot retrieve a linked dataset that you deleted. However, you can recreate it by subscribing to the listing again and adding the dataset to your project.

To delete a linked dataset, do the following:

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

   Go to BigQuery

2. In the Explorer panel, click your project name, and then click the linked dataset.

3. Expand the Actions option and click Delete.

4. In the Delete linked dataset? dialog, confirm deletion by typing delete.

5. Click Delete.

What's next

• Learn about Analytics Hub.
• Learn about managing listings.
• Learn about managing data exchanges.
• Learn about Analytics Hub audit logging.