Manage listings

As a BigQuery sharing publisher, you can do the following inBigQuery sharing (formerly Analytics Hub):

• Create listings in a data exchange for which you have publishing access.
• Update, delete, share, and view usage metrics for listings.
• Manage different BigQuery sharing roles for your listings, such aslisting administrators, subscribers, and viewers.
• View all subscribers who subscribed to your listing.
• Monitor usage of yourlistings.
• Remove subscribers from your listing.

A listing is a reference to a shared dataset that a publisher lists inadata 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 containsthe listing:

• Public listing. It can bediscoveredandsubscribed tobyGoogle Cloud users (allAuthenticatedUsers).Listings in a public data exchange are public listings. These listings can bereferences to afree public dataset or acommercial dataset. If thelisting is of a commercial dataset, BigQuery sharing subscribers caneither request access to the listing directly from the data provider, or theycan browse and purchaseGoogle Cloud Marketplace-integrated commercial listings.

• Private listing. It is shared directly with individuals or groups. Forexample, a private listing can reference marketing metrics dataset thatyou share with other internal teams within your organization. Even though youcanallowallAuthenticatedUsers tosubscribe to your listings, the listing will remain private and won'tshow as a public listing on the BigQuery sharing page.To share such listings with users, share the listing's URL with them. To makea private listing discoverable, you mustmake your exchangepublic.

• 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 manage listings and subscriptions, you must have one of the followingBigQuery sharing Identity and Access Management (IAM) roles:

• Analytics Hub Publisher role(roles/analyticshub.publisher), which lets youcreate, update, delete, and set IAM policies on your listings.

• Analytics Hub Listing Admin role(roles/analyticshub.listingAdmin), which lets youupdate, delete, and set IAM policies on your listings.

• Analytics Hub Admin role(roles/analyticshub.admin), which lets youcreate, update, delete, and set IAM policies on all listings inyour data exchange.

For more information, seeBigQuery sharing IAM roles.To learn how to grant these roles to other users, seeCreate a listing administrator.

Additionally, to create listings, you must also have thebigquery.datasets.getandbigquery.datasets.update permissions for the datasets for which you want tocreate listings. The followingBigQuery predefined rolescontain thebigquery.datasets.update permission:

• BigQuery Data Owner(roles/bigquery.dataOwner)
• BigQuery Admin(roles/bigquery.admin)

To view all data exchanges across projects in an organization that youhave access to, you must have theresourcemanager.organizations.getpermission. There are noBigQuery predefined rolesthat contain this permission, so you would need to use anIAM custom role.

View data exchanges

To view the list of data exchanges in your organization that you have access to,seeView data exchanges.If the data exchange is in another organization, then theBigQuery sharing administrator mustshare a link to that data exchangewith you.

Create a listing

A listing is a reference to ashared datasetthat a BigQuery sharing publisher lists in a data exchange.

To create a listing, follow these steps:

POST https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings?listingId=LISTING_ID

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

   Goto BigQuery

2. Click a dataset to view its details.

3. Clickperson_addSharing>Publish as listing.

   TheCreate listing dialog opens.

4. Select a data exchange to publish this listing in. The data exchange must bein the same region as the dataset. For more information about creating adata exchange, seecreate an exchange and set permissions.

5. In theShared dataset menu, select an existing dataset, or clickCreate a dataset to create a new dataset. Select the dataset thatyou want to list in the data exchange. The dataset must be in the sameregion as the data exchange. You cannot update this field after thelisting is created.

   The source dataset name and the ID of the project that contains thedataset are returned when BigQuery sharing subscribersview the metadata of their linked dataset.

6. Optional: To let subscribersshare a SQL stored procedure within a listing,selectAllow stored procedure sharing(Preview).

7. Expand theRegion data availability menu(Preview) to make the shareddataset available in additional regions. The menu displays theregions where dataset replicas exist with theReady to uselabel. Before configuring the listing for multiple regions, verifyyou've enabledcross-region dataset replicationon the shared dataset, as you can select only regions wherecross-region dataset replication is enabled. All other regions arelabeled asUnavailable. If no additional region is selected, thelisting uses the shared dataset region by default, which is labeledasProvider primary.

8. InData Egress controls, select the appropriate dataegress option.

   • To apply data egress restrictions on your shared dataset, but not onyour query results of your shared dataset, selectDisable copy andexport of shared data.
   • To apply data egressrestrictions on your shared dataset and query results of your shareddataset, selectDisable copy and export of query results, which willautomatically setDisable copy and export of shared data as well.
   • To apply data API copy and export egress restrictions on your shareddataset, selectDisable copy and export of tables through APIs, whichwill automatically setDisable copy and export of shared data as well.

   For more information about data egress controls, includingrestrictions, seeData egress options (BigQuery shared datasets only).

9. In theListing details section, inDisplay name, enter the name of the listing.

10. Enter the following optional details:

    • Category: select up to two categories that best represent yourlisting. BigQuery sharing subscribers canfilter listingsbased on these categories.

    • Data affinity: region(s) used by the BigQuery sharing publisherfor publishing the data. This information is useful for BigQuery sharingsubscribers tominimize or avoid Pub/Sub network egress costs by reading the datafrom the same region. For more information about egress costs, seeData transfer costs.

    • Icon: an icon for your listing. PNG and JPEG file formats aresupported. Icons must have a file size of less than 512 KiB anddimensions of no more than 512 x 512 pixels.

    • Description: a brief description about your listing.BigQuery sharing subscribers cansearch for listingsbased on the description.

    • Public Discoverability: enable public discoverability of your listingin the BigQuery sharing catalog. If you enable this option, grantallUsers orallAuthenticatedUsers theAnalytics Hub Viewer role(roles/analyticshub.viewer). For more information, seeGrant the role for a listing.If the exchange is alreadypublic,listing permissions are already inherited and no further action isrequired.

      Publicly discoverable exchanges can't have private listings due topermission inheritance, but private exchanges can have public listings. Forpublic listings to be created, the project the data listing is in must havean associated organization and billing account. If you're creating aCloud Marketplace-integrated commercial listing,we recommend making your listing publicly discoverable.

    • Subscriber Email Logging: turn on logging of theprincipal identifiers of subscribersrunning jobs and queries on this listing's linked dataset for all futuresubscriptions. When you enable this option, only newly createdsubscriptions log the principal identifiers. The logged data is availablein thejob_principal_subject field of theINFORMATION_SCHEMA.SHARED_DATASET_USAGE view.

      Note: Once you enable and save email logging, this setting cannot beedited. To disable email logging, delete the listing and recreateit without clicking theSubscriber Email Logging toggle.

    • Documentation> Markdown: additional information such aslinks to any relevant documentation and any additional information that canhelp subscribers to use your topic.

11. On theListing contact information section, enter the following optionaldetails:

    • Primary contact: enter an email ID or a URL of the primary contact forthe listing.

    • Request access contact: enter an email ID or URL of the intake formfor subscribers to contact you.

    • Provider: expand theProvider section and specify details in thefollowing fields:

      • Provider name: the name of the topic provider.
      • Provider primary contact: an email ID or a URL of the topicprovider's primary contact.

      Subscribers can filter listings based on the data providers.

    • Publisher: expand thePublisher section and specify details inthe following fields:

      • Publisher name: the name of the BigQuery sharing publisherwho's creating the listing.
      • Publisher primary contact: an email ID or a URL of the topicpublisher's primary contact.

12. Review theListing preview section.

13. ClickPublish.

Share a SQL stored procedure within a listing

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

You can shareSQL stored procedureswhen creating listings with BigQuery datasets. Since storedprocedures can create, drop, and manipulate tables, as well as invokeother stored procedures, additional authorization is needed.

Subscriber authorization

After subscribing to a listing, the linked stored procedures might not beexecuted directly. To ensure that the linked stored procedures can be accessed,the subscriber must communicate to the provider with the linked dataset name so thatthe provider authorizes the linked stored procedure on the provider resources.In addition, the subscriber mustauthorize the linked shared stored procedure and attach an IAM roleto the resources that they own in order to read from and write to thoseresources.

Provider authorization

When a provider creates a listing with a stored procedure, they need to let thesubscriber read from and write to their tables through the linked storedprocedure. To ensure this, do the following:

• For non-read operations, the provider mustauthorize the linked shared stored procedure andattach an IAM roleto any of the provider's resources that are accessed by the linked storedprocedure.

• For read operations, the provider canauthorize either the linked shared stored procedure (in the subscriber's linked dataset) or their original shared stored procedure (in the provider's dataset) andattach an IAM roleto any of the provider's resources that are accessed by the linked storedprocedure.

Give users access to a listing

If you want to give users access to a private listing, you must setIAM policy for an individual or a group for that listing. For acommercial listing, yourdata exchange must be public.Listings in a public data exchange appear in BigQuery sharing forallGoogle Cloud users (allAuthenticatedUsers).To enable users to browse and request access to commercial listings, you mustgrant users theAnalytics Hub Viewer role(roles/analyticshub.viewer). To enable users to subscribe to commerciallistings, you must explicitly grant users theAnalytics Hub Subscriber role(roles/analyticshub.subscriber). ForCloud Marketplace-integrated commercial listings,the Analytics Hub Subscriber role is automatically provisionedbased on the Cloud Marketplace orders.

If you want to make your listing accessible to everyone, including people whodon't use Google Cloud, you must grantallUsers the Analytics Hub Viewer role(roles/analyticshub.viewer).

To give users access to view or subscribe to your listing, follow these steps:

Create a non-authenticated URL for public listing

To create a non-authenticated BigQuery sharing listing URL that isviewable to even non-Google Cloud users, do the following:

1. Go to theSharing (Analytics Hub) page.

   Go to Sharing (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 havepublic discoverabilityenabled.

4. ClickCopy public link to generate an unauthenticated listing URL. Ensurethat this listing grantsallUsers theAnalytics Hub Viewer role (roles/analyticshub.viewer).

Create a listing administrator

To let users manage listings, you must create listing administrators. Tocreate listing administrators, you need to grant users theAnalytics Hub Publisher or the Analytics Hub Listing Admin IAM roleat the listing level. For more information about how to grant these roles for alisting, seeGrant the role for a listing.

View all subscriptions

To view all the current subscriptions to your listing, select one of thefollowing options:

SELECT * FROM `myproject`.`region-us`.INFORMATION_SCHEMA.SCHEMATA_LINKS;

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

SELECT * FROM `myproject`.`region-eu`.INFORMATION_SCHEMA.SCHEMATA_LINKS;

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

Remove a subscription

When you remove a subscription created before July 25, 2023 from your listings,thelinked dataset getsunlinked from theshareddataset. Subscriberscan still see the datasets in their projects but they are no longer linked withthe shared dataset.

To remove a subscription created before July 25, 2023 from your listings, followthese steps:

1. To list all subscribers of a listing, follow the Google Cloud consoleinstructions inView all subscriptions.

2. To remove a subscriber from a listing, clickdeleteDelete. If you want to removeall subscriptions, clickRemove all subscriptions.

3. In theRemove subscription? dialog, enterremove to confirm.

4. ClickRemove.

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

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

Update a listing

To update a listing, follow these steps:

PATCH https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID?updateMask=UPDATEMASK

Delete a listing

When you delete a listing, subscribers can no longerview the listing.Deleting a listing alsodeletes all the linked datasetsand removes all the subscriptions from your subscribers' projects. If a datasetremains linked, remove the dataset manually by clickingperson_addSharing> Manage Subscription.TheSubscriptions page opens, where you can remove a specific subscriberdataset or all subscriber datasets at once.

You can't deleteCloud Marketplace-integrated listingswith active commercial subscriptions.Revoke all commercial subscriptionsbefore you delete the listing.

Deleting a listing for multiple regions(Preview)doesn't delete the shared dataset replicas. After deleting the listing formultiple regions, subscribers can no longer view the listing or query the linkeddatasets. If the shared dataset replicas aren't referenced in other listings,you canchoose to delete them.

Before deleting a listing for multiple regions(Preview), ensure there are no activesubscriptions associated with it. If active subscriptions exist, you must firstrevoke them using theprojects.locations.subscriptions.revoke method.After all the active subscriptions are removed, you can proceed with deleting thelisting for multiple regions.

DELETE https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/dataExchanges/DATAEXCHANGE_ID/listings/LISTING_ID

Display a listing in the featured section

To increase visibility and awareness of your listing in theBigQuery sharing catalog, listings can be displayed in theFeatured section. Featured listings are governed by the Google Cloud PartnerAdvantage Agreement.

Partners that are interested in their listings being in theFeatured sectionof the BigQuery sharing catalog must meet the following criteria:

• Shared data must reside in BigQuery.

• They must be enrolled in thePartner Advantage Program with the Build designation.

• The listing must be created and havepublic discoverability enabled.

To request your listing to be in theFeatured section, complete and submit theintake form.To request that your listing be removed from the section, submit the sameintake form.

What's next

• Read aboutBigQuery sharing architecture
• Learn how toview and subscribe to listings.
• Learn aboutBigQuery sharing IAM roles.
• Learn aboutcreating datasets.
• Learn aboutBigQuery sharing audit logging.
• Learn how tomonitor listings.