Categories:

System functions (System Control)

SYSTEM$GET_LISTING_URL_FOR_EXTERNAL_CONSUMER

Returns the catalog URL and catalog URI for an external listing, enabling an external consumer to connect using an Iceberg REST Catalog client.

See also:

Open Data Sharing (Preview)

Syntax

SYSTEM$GET_LISTING_URL_FOR_EXTERNAL_CONSUMER( '<listing_name>' )

Arguments

Required:

'listing_name'

Name of the external listing. The name must be enclosed in single quotes.

Returns

Returns a JSON object containing the following fields:

FieldDescription
catalogThe catalog name the external consumer uses to identify the shared data.
catalog_uriThe Iceberg REST Catalog endpoint URL the external consumer uses to connect.

Access control requirements

A role used to execute this operation must have the following privileges at a minimum:

PrivilegeObjectNotes
OWNERSHIP or USAGEListingRequired to retrieve the catalog URL for the listing.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Usage notes

  • The external consumer must authenticate using the Programmatic Access Token (PAT) generated for their external consumer identity.
  • During Private Preview, the catalog URI returns data only from the region where the provider account is located.
  • Provide both the catalog_uri value and the PAT to the external consumer so they can connect with an Iceberg REST Catalog client.

Examples

Retrieve the catalog URL for an external listing named TEST_LISTING:

CALL SYSTEM$GET_LISTING_URL_FOR_EXTERNAL_CONSUMER('TEST_LISTING');

Example output:

{
  "catalog": "TEST_LISTING",
  "catalog_uri": "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog"
}