Manage listings
As an Analytics Hub publisher, you can perform the following tasks:
- Create listings in a data exchange for which you have publishing access.
- Update, delete, share, and view usage metrics for listings.
- Manage different roles for your Analytics Hub listings, such as listing administrators, subscribers, and viewers.
- View all subscribers who subscribed to your listing.
- Monitor usage of your listings.
- Remove subscribers from your listing.
A listing is a reference to a shared dataset that a publisher lists in a data exchange. A listing can be of the following two types based on the Identity and Access Management (IAM) policy that is set for the listing and the type of data exchange that contains the listing:
Public listing. It can be discovered and subscribed by Google Cloud users (
allAuthenticatedUsers
). Listings in a public data exchange are public listings. These listings can be references to a free public dataset or a commercial dataset. If the listing is of a commercial dataset, subscribers can request access to the listing and the data provider contacts those subscribers.Private listing. It is shared directly with individuals or groups. For example, a private listing can reference marketing metrics dataset that you share with other internal teams within your organization. Even though you can allow
allAuthenticatedUsers
to subscribe to your listings, the listing will remain private and won't show as a public listing on the Analytics Hub page. To share such listings with users, share the listing's URL with them. To make a private listing discoverable, you must make your exchange public.
Before you begin
To get started with Analytics Hub, you need to enable the Analytics Hub API inside your Google Cloud project.
Required permissions
To enable the Analytics Hub API, you need the following Identity and Access Management (IAM) permissions:
serviceUsage.services.get
serviceUsage.services.list
serviceUsage.services.enable
The following predefined IAM role includes the permissions that you need to enable the Analytics Hub API:
roles/serviceusage.serviceUsageAdmin
For more information about IAM roles in BigQuery, see Predefined roles and permissions.
Enable the Analytics Hub API
To enable the Analytics Hub API, do the following:
Console
Go to the Analytics Hub API for your Google Cloud project and enable it.
gcloud
Run the gcloud services enable command:
gcloud services enable analyticshub.googleapis.com
Required permissions
To manage listings and subscriptions, you must have one of the following Analytics Hub roles:
Analytics Hub Publisher role (
roles/analyticshub.publisher
), which lets you create, update, delete, and set IAM policies on your listings.Analytics Hub Listing Admin role (
roles/analyticshub.listingAdmin
), which lets you update, delete, and set IAM policies on your listings.Analytics Hub Admin role (
roles/analyticshub.Admin
), which lets you create, update, delete, and set IAM policies on all listings in your data exchange.
For more information, see Analytics Hub user roles. To learn how to grant these roles to other users, see Create a listing administrator.
Additionally, to create listings, you must also have bigquery.datasets.get
and
bigquery.datasets.update
permissions for the datasets for which you want to
create listings. The following BigQuery predefined
roles contain the
bigquery.datasets.update
permission:
- BigQuery Data Owner role (
roles/bigquery.dataOwner
) - BigQuery Admin role (
roles/bigquery.admin
)
To view all data exchanges across projects in an organization that you
have access to, you must have the resourcemanager.organizations.get
permission. There are no BigQuery predefined
roles that contain this
permission so you would need to use an IAM custom role.
View data exchanges
To view the list of data exchanges in your organization that you have access to, see View data exchanges. If the data exchange is in another organization, then the Analytics Hub administrator must share a link to that data exchange with you.
Create a listing
A listing is a reference to a shared dataset that a publisher lists in a data exchange.
To create a listing, follow these steps:
Console
Go to the Analytics Hub page.
A page appears that lists all data exchanges that you can access.
Click the data exchange name in which you want to create the listing.
Click
Create listing.On the Create listing page, in Display name, enter the name of the listing.
If you are creating a commercial listing, then you must fill in the Request access contact field. You must enter an email or URL of the intake form for subscribers to contact you.
Optional: Enter the following details:
Primary contact: enter an email or a URL of the primary contact for the listing.
Category: select up to two categories that best represent your listing. Subscribers can filter listings based on these categories.
Provider: expand the Provider section and specify details in the following fields:
- Provider name: the name of the dataset provider.
- Provider primary contact: an email or a URL of the dataset provider's primary contact.
Subscribers can filter listings based on the data providers.
Publisher: expand the Publisher section and specify details in the following fields:
- Publisher name: the name of the publisher who's creating the listing.
- Publisher primary contact: an email or a URL of the dataset publisher's primary contact.
Icon: an icon for your listing. PNG and JPEG file formats are supported. Icons must have a file size of less than 512 KiB and dimensions of no more than 512 x 512 pixels.
Description: a brief description about your listing. Subscribers can search for listings based on the description.
In Source dataset, select the dataset that you want to list in the data exchange. The source dataset must be in the same region as the data exchange. You cannot update this field after the listing is created.
In Data Egress, select the appropriate data egress option. Only subscribers with non-edition offerings or the Enterprise Plus edition can query data with data egress restrictions.
- To apply data egress restrictions on your shared dataset, but not on your query results of your shared dataset, select Disable copy and export of shared data.
- To apply data egress restrictions on your shared dataset and query results of your shared dataset, select Disable copy and export of query results, which will automatically set Disable copy and export of shared data as well.
- To apply data API copy and export egress restrictions on your shared dataset, select Disable copy and export of tables through APIs, which will automatically set Disable copy and export of shared data as well.
Optional: In the Listing details section, click the Public discoverability toggle to enable public discoverability. You must grant the Analytics Hub Viewer role (
roles/analyticshub.viewer
) toallUsers
orallAuthenticatedUsers
. For more information, see Grant the role for a listing. If the exchange is already public, listing permissions are already inherited and no further action is required.Publicly discoverable exchanges can't have private listings due to permission inheritance, but private exchanges can have public listings. For public listings to be created, the project the data listing is in must have an associated organization and billing account.
Optional: In the Documentation > Markdown section, you can enter additional information such as sample queries that you can run on the dataset, links to any relevant documentation, and any additional information that can help subscribers to use your dataset.
Click Save.
API
Use the projects.locations.dataExchanges.listings.create
method.
POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings?listingId=LISTING_ID
Replace the following:
PROJECT_ID
: the project ID that contains the data exchange in which you want to create the listing.LOCATION
: the location for your data exchange. For more information about locations that support Analytics Hub, see Supported regions.DATAEXCHANGE_ID
: the data exchange ID.LISTING_ID
: the listing ID.
In the body of the request, provide the listing details. If the request is successful, then the response body contains details of the listing.
For more information about the tasks that you can perform on listings using
APIs, see projects.locations.dataExchanges.listings
methods.
Create a listing from a dataset
You can also create a listing from a dataset by doing the following:
In the Google Cloud console, go to the BigQuery page.
Click a dataset to view its details.
Click > Publish as listing.
SharingThe Create listing dialog opens.
Select a data exchange to publish this listing in. The data exchange must be in the same region as the dataset. For more information about creating a data exchange, see create an exchange and set permissions.
In Data Egress controls, select the appropriate data egress option. Only subscribers with non-edition offerings or the Enterprise Plus edition can query data with data egress restrictions.
- To apply data egress restrictions on your shared dataset, but not on your query results of your shared dataset, select Disable copy and export of shared data.
- To apply data egress restrictions on your shared dataset and query results of your shared dataset, select Disable copy and export of query results, which will automatically set Disable copy and export of shared data as well.
- To apply data API copy and export egress restrictions on your shared dataset, select Disable copy and export of tables through APIs, which will automatically set Disable copy and export of shared data as well.
Enter the listing details.
Display name is the name of this listing and is required; other fields are optional.
Optional: Click the Public discoverability toggle to enable public discoverability. You must grant the Analytics Hub Viewer role (
roles/analyticshub.viewer
) toallUsers
orallAuthenticatedUsers
. For more information, see Grant the role for a listing. If the exchange is already public, listing permissions are already inherited and no further action is required.Publicly discoverable exchanges can't have private listings due to permission inheritance, but private exchanges can have public listings. For public listings to be created, the project the data listing is in must have an associated organization and billing account.
Optional: In the Documentation > Markdown section, you can enter additional information such as sample queries that you can run on the dataset, links to any relevant documentation, and any additional information that can help subscribers to use your dataset.
Click Publish.
Give users access to a listing
If you want to give users access to a private listing, you must set
IAM policy for an individual or a group for that listing. For a
commercial listing, your data exchange must be public.
Listings in a public data exchange appears in Analytics Hub for
all Google Cloud users (allAuthenticatedUsers
).
To enable users to request access for commercial listings, you must grant users
the Analytics Hub Viewer role.
If you want to make your listing accessible to everyone, including people who
don't use Google Cloud, you must grant allUsers
the Analytics Hub Viewer Role
(roles/analyticshub.viewer
).
To give users access to view or subscribe to your listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing for which you want to add subscribers.
Click
Set permissions.To add principals, click
Add principal.In the New principals field, add the following details based on the type of listing:
For a private listing, enter emails of the identity to whom you want to grant access.
For a public listing, add
allAuthenticatedUsers
.For a public listing discoverable to everyone, including non-Google Cloud users, add
allUsers
.
For Select a role, hold the pointer over Analytics Hub, and then based on the type of listing, select one of the following roles:
For a commercial listing, select the Analytics Hub Viewer role. This role lets users view the listing and request access.
For a private or non-commercial public listing, select the Analytics Hub Subscriber role. This role lets users subscribe to your listing.
For more information, see the Analytics Hub Subscriber and Viewer roles.
Click Save.
API
Read the existing policy with the listing
getIamPolicy
method by using theprojects.locations.dataExchanges.listings.getIamPolicy
method.POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID:getIamPolicy
Replace the following:
PROJECT_ID
: the project ID—for example,my-project-1
.LOCATION
: the location of the data exchange that contains the listing.DATAEXCHANGE_ID
: the data exchange ID.LISTING_ID
: the listing ID.
Analytics Hub returns the current policy in the response.
To add or remove members and their associated roles, edit the policy with a text editor. Use the following format to add members:
user:[email protected]
group:[email protected]
serviceAccount:[email protected]
domain:example.domain.com
For example, to grant the
roles/analyticshub.subscriber
role togroup:[email protected]
, add the following binding to the policy:{ "members": [ "group:[email protected]" ], "role":"roles/analyticshub.subscriber" }
Write the updated policy by using the
projects.locations.dataExchanges.listings.setIamPolicy
method. In the body of the request, provide the updated IAM policy from the previous step.POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID:setIamPolicy
In the body of the request, provide the listing details. If the request is successful, then the response body contains details of the listing.
For more information about the tasks that you can perform on listings using
APIs, see projects.locations.dataExchanges.listings
methods.
Create a non-authenticated URL for public listing
To create a non-authenticated Analytics Hub listing URL that is viewable to even non-Google Cloud users, do the following:
Go to the Analytics Hub page.
A page appears that lists all data exchanges that you can access.
Click the data exchange name that contains the listing.
Click the display name to view the listing details. The listing must have public discoverability enabled.
Click Copy public link to generate an unauthenticated listing URL. Make sure this listing grants
allUsers
the Analytics Hub Viewer role (roles/analyticshub.viewer
).
Create a listing administrator
To let users manage listings, you must create Analytics Hub listing administrators. To create listing administrators, you need to grant users the Analytics Hub Publisher or the Analytics Hub Listing Admin role at the listing level. For more information about how to grant these roles for a listing, see Grant the role for a listing.
View all subscriptions
To view all current subscriptions to your listing, select one of the following options:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing for which you want to manage the subscriptions.
Click the listing for which you want to list all subscribers.
To view all subscribers of your listing, click Manage subscriptions.
Optional: You can filter results by subscriber details.
Alternatively, if you have access to the shared dataset, you can follow these steps to list subscribers:
Go to the BigQuery page.
In the Explorer pane, expand your project and select the shared dataset.
In the
Sharing list, select Manage subscriptions.
SQL
The following example uses the
INFORMATION_SCHEMA.SCHEMATA_LINKS
view
to list all linked datasets to a shared dataset in myproject
that are in the
us
region:
SELECT * FROM `myproject`.`region-us`.INFORMATION_SCHEMA.SCHEMATA_LINKS;
The output is similar to the following. Some columns are omitted to simplify the output.
+----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+ | catalog_name | schema_name | linked_schema_catalog_name | linked_schema_catalog_number | linked_schema_name | linked_schema_org_display_name | +----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+ | myproject | myschema1 | subscriptionproject1 | 974999999291 | subscriptionld1 | subscriptionorg | | myproject | myschema2 | subscriptionproject2 | 974999999292 | subscriptionld2 | subscriptionorg | | myproject | myschema3 | subscriptionproject3 | 974999999293 | subscriptionld3 | subscriptionorg | +----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+
API
Use the projects.locations.dataExchanges.listings.listSubscriptions method.
GET https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID:listSubscriptions
Replace the following:
PROJECT_ID
: the project ID of the listing that you want to subscribe to.LOCATION
: the location for the listing that you want to subscribe to.DATAEXCHANGE_ID
: the data exchange ID that contains the listing that you want to subscribe to.LISTING_ID
: the ID of the listing that you want to subscribe to.
Remove a subscription
When you remove a subscription created before July 25, 2023 from your listings, the linked dataset gets unlinked from the shared dataset. Subscribers can still see the datasets in their projects but they are no longer linked with the shared dataset.
To remove a subscription created before July 25, 2023 from your listings, follow these steps:
To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.
To remove a subscriber from a listing, click
Delete. If you want to remove all subscriptions, click Remove all subscriptions.In the Remove subscription? dialog, enter
remove
to confirm.Click Remove.
To remove subscriptions created after July 25, 2023, follow these steps:
Console
To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.
Click the Subscriptions tab.
To remove a subscriber from a listing, select the Subscription(s) you would like to remove and click
Remove Subscriptions.In the Remove subscription? dialog, enter
remove
to confirm.Click Remove.
API
Use the projects.locations.subscriptions.revoke method.
POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/subscriptions/SUBSCRIPTION_ID:revoke
Replace the following:
PROJECT_ID
: the project ID of the subscription that you want to remove.LOCATION
: the location of the subscription that you want to remove.SUBSCRIPTION
: the ID of the subscription that you want to remove.
Update a listing
To update a listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing that you want to update.
Click
Edit listing.Modify values in the fields. You can modify all values except the source dataset of the listing.
Optional:
- If you enable public discoverability, grant
allUsers
orallAuthenticatedUsers
the Analytics Hub Viewer role (roles/analyticshub.viewer
). For more information, see Grant the role for a listing - If you disable public discoverability,
remove the Analytics Hub Viewer role from
allUsers
andallAuthenticatedUsers
. Public exchanges can't have private listings, but private exchanges can have public listings.
- If you enable public discoverability, grant
To preview changes, click Preview.
To save changes, click Save.
API
Use the projects.locations.dataExchanges.listings.patch
method.
PATCH https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID?updateMask=UPDATEMASK
Replace UPDATEMASK
with the list of fields
that you want to update. For updating multiple values, use a comma-separated
list. In the body of the request, specify the updated values.
For more information about the tasks that you can perform on listings using
APIs, see projects.locations.dataExchanges.listings
methods.
Delete a listing
When you delete a listing, subscribers can no longer view the listing. Deleting a listing also deletes all linked datasets (removes all subscriptions) from your subscribers' projects.
If you delete a listing, you cannot undo it. To delete a listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing that you want to delete.
Click
Delete.In the Delete listing? dialog, confirm deletion by typing delete.
Click Delete.
API
Use the projects.locations.dataExchanges.listings.delete
method.
DELETE https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID
For more information about the tasks that you can perform on listings using
APIs, see projects.locations.dataExchanges.listings
methods.
Display a listing in the featured section
To increase visibility and awareness of your listing in the Analytics Hub catalog, listings can be displayed in the Featured section. Featured listings are governed by the Google Cloud Partner Advantage Agreement.
Partners that are interested in their listings being in the Featured section of the Analytics Hub catalog must meet the following criteria:
Shared data must reside in BigQuery.
They must be enrolled in the Partner Advantage Program with the Build designation.
The listing must be created and have public discoverability enabled.
To request your listing to be in the Featured section, complete and submit the intake form. To request your listing is removed from the section, submit the same intake form.
What's next
- Read about Analytics Hub architecture
- Learn how to view and subscribe to listings.
- Learn about Analytics Hub user roles.
- Learn about creating datasets.
- Learn about Analytics Hub audit logging.
- Learn how to monitor listings.