Manage subscriptions

This document describes how to manage your BigQuery sharing subscriptions, covering tasks for both subscribers and publishers.

As a BigQuery sharing subscriber, you can do the following:

• Subscribe to a listing.
• List your current subscriptions in a given Google Cloud project.
• Delete a subscription.

As a BigQuery sharing publisher, you can do the following:

• View all subscriptions to your listing.
• Revoke access to a specific subscription.

A BigQuery sharing subscription is a regionalized resource that resides in the subscriber's project. Subscriptions store relevant information about the subscriber and represent the contract between publisher and subscriber.

Before you begin

To get started with BigQuery sharing (formerly Analytics Hub), you need to enable the Analytics Hub API inside your Google Cloud project.

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:

• Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

To enable the Analytics Hub API, select one of the following options:

gcloud services enable analyticshub.googleapis.com

Required roles

To get the permissions that you need to manage subscriptions, ask your administrator to grant you the Analytics Hub Subscription Owner (roles/analyticshub.subscriptionOwner) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Subscriber workflows for managing subscriptions

The following sections describe what BigQuery sharing subscribers can do with subscriptions.

Subscribe to listings

To subscribe to listings, follow the steps in View and subscribe to listings and data exchanges.

List subscriptions

To list your current subscriptions in a given project, use the projects.locations.subscriptions.list method:

GET https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/subscriptions

Replace the following:

• PROJECT_ID: the Google Cloud project ID for the subscriptions that you want to list.
• LOCATION: the location for the subscriptions that you want to list.

Delete a subscription

To delete a subscription, use the projects.locations.subscriptions.delete method:

DELETE https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/subscriptions/SUBSCRIPTION_ID

Replace the following:

• PROJECT_ID: the project ID for the subscription to delete.
• LOCATION: the location of the subscription to delete. For more information about locations that support sharing, see Supported regions.
• SUBSCRIPTION_ID: the ID of the subscription to delete.

The request body must be empty. If successful, the response body contains an operation instance.

When a subscriber deletes a subscription, it also deletes the linked dataset from the subscriber's project.

When you delete a subscription from a multi-region listing (Preview), all the primary and secondary linked dataset replicas are also deleted from the subscriber's project.

For more information about the tasks you can do with subscriptions using the API, see the projects.locations.subscriptions methods.

Publisher workflows for managing subscriptions

The following sections describe what BigQuery sharing publishers can do with subscriptions. For more information about managing subscriptions to listings, see Manage listings.

List subscriptions

To list all subscriptions, select one of the following options.

GET https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID:listSubscriptions

Revoke a subscription

When a publisher revokes a subscription, the subscriber can no longer query the linked dataset. Because this action is initiated by the publisher on a subscriber-owned resource, the linked dataset remains in the subscriber's project. The subscriber can remove the dataset by deleting it.

If a publisher revokes a subscription from a multi-region listing (Preview), subscribers can no longer query any primary or secondary linked dataset replicas.

To revoke a subscription, select one of the following options:

POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/subscriptions/SUBSCRIPTION_ID:revoke

Limitations

Subscriptions have the following limitations:

• You can only use the API to manage subscriptions created after July 25, 2023. Linked datasets created before this date are unsupported because they lack the required subscription resource.

What's next

• Read about BigQuery sharing architecture.
• Learn how to view and subscribe to listings and data exchanges.
• Learn about BigQuery sharing user roles.
• Learn how to create datasets.
• Learn about BigQuery sharing audit logging.