Stay organized with collections Save and categorize content based on your preferences.

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 Permissions

You must have the Analytics Hub Subscriber role (roles/analyticshub.subscriber) for the listing in order to subscribe to it. For information about the roles, see Analytics Hub user roles.

Additionally, to create a linked dataset in your project, you must also have the bigquery.datasets.create permission.

To create and query linked datasets, BigQuery offers the following predefined roles that you need on your projects:

  • BigQuery Admin (roles/bigquery.admin)
  • BigQuery User (roles/bigquery.user)

If you need a role that allows for only creating and querying datasets, you must create a custom role with the following permissions:

  • bigquery.datasets.create to create new datasets or bigquery.datasets.* to perform additional actions on datasets.
  • bigquery.jobs.create to query datasets or bigquery.jobs.* to perform additional actions on jobs.

For more information about granting roles, see Grant a single role.

View listings

To view 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 data.

  3. In the Add data dialog, click Analytics Hub. The Analytics Hub dialog appears containing listings that you can access.

    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 a listing

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

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 View 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. If you click a dataset that you can subscribe to, then click Add dataset to project 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 in a project

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

Update a linked dataset

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.

Delete a linked dataset

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