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 to 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.

Enable the Analytics Hub API

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.

Caution: We recommend that you don't add your shared datasets in a project with a VPC Service Controls perimeter. If you do so, then you must add the appropriate ingress and egress rules.

To create a listing, follow these steps:

Console

1. Go to the Analytics Hub page.

   Go to Analytics Hub

   A page appears that lists all data exchanges that you can access.

2. Click the data exchange name in which you want to create the listing.

3. Click Create listing.

4. On the Create listing page, in Display name, enter the name of the listing.

5. 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.

6. 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.

7. 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.

   Important: The source dataset name and the ID of the project that contains the dataset are returned when subscribers view the metadata of their linked dataset.

8. 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.

9. 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) to allUsers or allAuthenticatedUsers. 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.

10. 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.

11. 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:

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

   Go to BigQuery

2. Click a dataset to view its details.

3. Click Sharing > Publish as listing.

   The Create listing dialog opens.

4. 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.

5. 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.

6. Enter the listing details.

   Display name is the name of this listing and is required; other fields are optional.

7. Optional: Click the Public discoverability toggle to enable public discoverability. You must grant the Analytics Hub Viewer role (roles/analyticshub.viewer) to allUsers or allAuthenticatedUsers. 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.

8. 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.

9. 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

1. Go to the Analytics Hub page.

   Go to Analytics Hub

2. Click the data exchange name that contains the listing.

3. Click the listing for which you want to add subscribers.

4. Click Set permissions.

5. To add principals, click Add principal.

6. 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.

7. 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.

8. Click Save.

API

1. Read the existing policy with the listing getIamPolicy method by using the projects.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.

2. To add or remove members and their associated roles, edit the policy with a text editor. Use the following format to add members:

   • user:[e-mail]
   • group:[e-mail]
   • serviceAccount:[e-mail]
   • domain:example.domain.com

   For example, to grant the roles/analyticshub.subscriber role to group:[e-mail], add the following binding to the policy:

   {
    "members": [
      "group:[e-mail]"
    ],
    "role":"roles/analyticshub.subscriber"
   }
   

3. 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.

Note: After you grant licenses to users to access your commercial listing, you can either create a private listing for those users or grant those users the Analytics Hub Subscriber role for your commercial listing.

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:

1. Go to the Analytics Hub page.

   Go to Analytics Hub

   A page appears that lists all data exchanges that you can access.

2. Click the data exchange name that contains the listing.

3. Click the display name to view the listing details. The listing must have public discoverability enabled.

4. 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

1. Go to the Analytics Hub page.

   Go to Analytics Hub

2. Click the data exchange name that contains the listing for which you want to manage the subscriptions.

3. Click the listing for which you want to list all subscribers.

4. To view all subscribers of your listing, click Manage subscriptions.

   

5. 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:

1. Go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and select the shared dataset.

3. 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:

1. To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.

2. To remove a subscriber from a listing, click Delete. If you want to remove all subscriptions, click Remove all subscriptions.

3. In the Remove subscription? dialog, enter remove to confirm.

4. Click Remove.

To remove subscriptions created after July 25, 2023, follow these steps:

Console

1. To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.

2. Click the Subscriptions tab.

3. To remove a subscriber from a listing, select the Subscription(s) you would like to remove and click Remove Subscriptions.

4. In the Remove subscription? dialog, enter remove to confirm.

5. 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

1. Go to the Analytics Hub page.

   Go to Analytics Hub

2. Click the data exchange name that contains the listing.

3. Click the listing that you want to update.

4. Click Edit listing.

5. Modify values in the fields. You can modify all values except the source dataset of the listing.

6. Optional:

   • If you enable public discoverability, grant allUsers or allAuthenticatedUsers 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 and allAuthenticatedUsers. Public exchanges can't have private listings, but private exchanges can have public listings.

7. To preview changes, click Preview.

8. 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.

Note: If a dataset remains linked, remove the dataset manually by clicking Sharing > Manage Subscription. The Subscriptions page opens, where you can remove a specific subscriber dataset or all subscriber datasets at once.

If you delete a listing, you cannot undo it. To delete a listing, follow these steps:

Console

1. Go to the Analytics Hub page.

   Go to Analytics Hub

2. Click the data exchange name that contains the listing.

3. Click the listing that you want to delete.

4. Click Delete.

5. In the Delete listing? dialog, confirm deletion by typing delete.

6. 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.