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:
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:
In the Google Cloud console, go to the
BigQuery
page.
Go to BigQuery
In the
Explorer
pane, click
add
Add data
.
In the
Add data
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
.
To filter listings by their name or description, enter the name or
description of the listing in the
Search for listings
field.
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.
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.
To subscribe to a listing, follow these steps:
Console
To view a list of listings that you have access to, follow the steps in
View listings
.
Browse through the listings and click a listing that you want to subscribe
to. A dialog containing the details of the listing appears.
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.
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
.
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.
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:
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 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:
In the Google Cloud console, go to the
BigQuery
page.
Go to BigQuery
In the
Explorer
panel, click your project name, and then click the linked
dataset.
Expand the
more_vert
Actions
option and click
Open
.
In the
Details
panel, click
mode_edit
Edit details
and then specify the following details:
- To add labels, see
Adding a label to a dataset
.
To enable
collation
,
expand the
Advanced options
section and follow these steps:
- Select
Enable default collation
.
- From the
Default collation
list, select an option.
Click
Save
.
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 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:
In the Google Cloud console, go to the
BigQuery
page.
Go to BigQuery
In the
Explorer
panel, click your project name, and then click the linked
dataset.
Expand the
more_vert
Actions
option and click
Delete
.
In the
Delete linked dataset?
dialog, confirm deletion by typing
delete
.
Click
Delete
.
What's next