About managing listings using SQL¶
With a listing, you can share data products to accounts in any Snowflake region. For more about listings, see About sharing with listings.
You can use SQL commands to create and manage listings that you offer to specific consumers. For other limitations, see Limitations of working with listings using SQL.
Prerequisites for working with listings using SQL¶
Before you can create listings using SQL, you must do the following:
Review and accept the Snowflake Provider and Consumer Terms of Service.
Prepare the data for your listing. See Preparing data for a listing.
Review the Provider Policies.
Configure account privileges.
Limitations of working with listings using SQL¶
This preview has the following limitations:
You cannot offer paid, personalized listings, or listings on private data exchanges.
Define a listing manifest¶
To create a listing you must first create a listing manifest.
Manifests are written in YAML (https://yaml.org/spec/), and include a prefix and required and optional fields.
For example, to create a simple titled listing with listing terms, define a manifest similar to:
title: A title for the listing.
subtitle: An optional subtitle.
description: A general description.
profile: Provider profile reference.
listing_terms: ...
targets: ...
Each manifest then includes additional sections, such as:
auto_fulfillment: ...
And a number of optional fields, such as data_dictionary
, business_needs
, and more.
A simple manifest would include:
title: "MyFirstListing"
subtitle: "Example listing"
description: "This is my first listing!"
listing_terms:
type: "OFFLINE"
targets:
accounts: ["Org1.Account1"]
For more information, see Listing manifest reference.
Create a listing using SQL¶
To create a listing, use the CREATE LISTING command, specifying a name and a YAML manifest that describes the listing. Listings created using CREATE LISTING … are automatically published. After a listing is created, you can alter it using ALTER LISTING, which includes unpublish and publish support.
Note that unlike Snowsight, when you create a listing using SQL the associated share must already exist.
Additionally, listings can be described, shown, published and unpublished, and dropped.
Note
Creating a listing using SQL is conceptually similar to Share data or apps with specific consumers using a private listing. You should be familiar and comfortable with creating, viewing, and publishing listings using Snowsight and Provider Studio before creating listings using SQL. For more information, see Share data or apps with specific consumers using a private listing.
Before you create your listing, ensure you have completed all prerequisites.
For example, if you want to create a DRAFT listing my1stlisting
from share myshare
with title “My first SQL listing”, execute the following command:
CREATE EXTERNAL LISTING my1stlisting
SHARE myshare AS
$$
title: "My first SQL listing"
description: "This is my first listing"
listing_terms:
type: "OFFLINE"
targets:
accounts: ["Org1.Account1"]
$$ PUBLISH=FALSE REVIEW=FALSE;
Note
Listings are identified using the listing’s NAME. A listing NAME is the identifier used when initially creating the listing. In the example above, the listing name is MY1STLISTING. While title, subtitle and other listing characteristics can be altered, NAME cannot be altered by specifying a new name in yaml. Use ALTER LISTING … RENAME TO to rename a listing. Commands such as ALTER LISTING, SHOW LISTINGS, DESCRIBE LISTING, and DROP LISTING all use NAME to identify a listing. Listing NAME is not shown in Snowsight, which identifies listings by title.
Publish a listing using SQL¶
You can publish and un-publish listings using ALTER LISTING … PUBLISH and ALTER LISTING … UNPUBLISH.
For more information about publishing listings using Snowsight, see Publishing a listing.
Note that listings can be automatically published when created using CREATE LISTING.
For example, to publish the previously unpublished listing, execute the following command:
ALTER LISTING MY1STLISTING PUBLISH;
Additionally, before a listing can be dropped, it must be un-published. To un-publish a previously published listing, execute a command similar to:
ALTER LISTING MY1STLISTING UNPUBLISH;
Expand the definition of a listing using SQL¶
The previous example did not include targets or usage examples. You can use the ALTER LISTING to alter a listing’s characteristics. In this example, we update an existing listing to add targets and example SQL. Note that the original YAML manifest is extended to include new content.
To alter a listing to include additional fields execute a command similar to:
ALTER LISTING MY1STLISTING AS
$$
title: "My First SQL Listing"
description: "This is my first listing"
listing_terms:
type: "OFFLINE"
targets:
accounts: ["Org1.Account1"]
usage_examples:
- title: "this is a test sql"
description: "Simple example"
query: "select *"
$$;
Examine listings using SQL¶
Much like tables and other SQL elements, listings can be described and shown. DESCRIBE LISTING takes a single listing name
as a parameter and provides details about that listing. SHOW LISTINGS can provide information about a group of listings, using a
LIKE
filter, or all listings created by a given account if no filter is provided.
To show the details of the MY1STLISTING listing, execute a command similar to:
SHOW LISTINGS LIKE 'MY1STLISTING';
To show all listings that your role has access to, execute a command similar to:
SHOW LISTINGS;
To describe the listing MY1STLISTING, execute a command similar to:
DESC LISTING MY1STLISTING;
Drop listings using SQL¶
To remove a listing, you must first un-publish the listing. You should be familiar with removing listings using Snowsight before dropping listings using SQL. For more information about removing listings using Snowsight, see Removing listings as a provider.
To un-publish a listing, execute a command similar to:
ALTER LISTING MY1STLISTING UNPUBLISH;
To drop a listing, execute a command similar to:
DROP LISTING IF EXISTS MY1STLISTING