Listing manifest reference¶
Creating Snowflake listings programmatically requires a manifest, written in YAML (https://yaml.org/spec/). Use the information provided here to learn about the manifest format and its individual sections.
- See also:
CREATE LISTING, ALTER LISTING, DESCRIBE LISTING, SHOW LISTINGS, DROP LISTING
Note
Fields can be any of:
Optional - Optional for either marketplace listings or private listings.
Required - Required for either marketplace listings or private listings.
Qualified - requirements differ for marketplace listings or private listings and optional vs required is qualified by listing type. For example optional for private listings, but required for marketplace listings.
The general format of a listing manifest is:
#
# Listing prefix
#
title: <listing title>
subtitle: <Optional listing subtitle>
description: <listing description>
profile : <Optional name of the provider profile>
listing_terms:
- # Required listing terms that the consumer must sign
auto_fulfillment:
- # Required when the target accounts are outside the provider's region, otherwise optional.
data_dictionary:
- # Optional data dictionary
business_needs:
- # Optional <List>BusinessNeed elements, maximum 6.
usage_examples:
- # Optional <List>UsageExample elements, maximum 10.
targets:
- # Required <List> Consumer accounts to target with this private listing
The following sections detail each listing manifest field, child fields, and provide associated examples.
Listing prefix¶
Each listing manifest starts with the following fields:
title
(String, required, maximum length 110): Listing title.subtitle
(String, optional for private, required for marketplace listings, maximum length 110): Listing subtitle.description
(String, required, maximum length 7500): Listing description.custom_contact
(String, optional): Email. Must be a valid, well formed email address.profile
(String, optional for private listings, required for marketplace listings): Name of an approved provider profile.
For more information, refer to: Provider basic information.
Note
Values for profile
can be found by executing show profiles in data exchange SNOWFLAKE_DATA_MARKETPLACE;
.
Listing prefix example¶
title: Weather information
subtitle: Historical weather by postcode.
description: This listing includes historical weather data by post code.
profile: My provider profile
listing_terms
¶
The required listing_terms
(required) field contains the following name value pairs:
listing_terms.type
(enum, required): must be one of:STANDARD
- Refers to the Standard Agreement for Marketplace Products.OFFLINE
- Indicates that terms are negotiated offline by the parties.CUSTOM
- When specified, must specify a value forlisting_terms.link
.
listing_terms.link
(required when type is CUSTOM): A fully qualified link to the provider’s listing terms, must start withhttp
orhttps
.
For more information, refer to Terms of Service in the table in Basic information.
Note
Consumers can accept listing terms programmatically. For more information contact Snowflake Support.
listing_terms
example¶
. . .
listing_terms:
type: "CUSTOM"
link: "http://example.com/my/listing/terms"
. . .
targets
¶
The targets
field is required for marketplace and private listings.
Contains a list, maximum of 100 elements:
targets.accounts
(Required iftargets.region
not present): List of accounts with which to share the listing.Each target account must be in
<OrgName>.<AccountName>
format, where:OrgName
can be obtained using SELECT CURRENT_ORGANIZATION_NAME();.AccountName
can be obtained from account_name usingSHOW ACCOUNTS or using Snowsight.
or
targets.regions
(Required iftargets.accounts
not present):List of regions with which to share the listing.
Each target region must be of the form “region_groups_type.snowflake_region”. In addition, “ALL” is supported for including all regions.
For example “PUBLIC.AWS_US_EAST_1”.
For a complete list of region group types and Snowflake regions execute:
SHOW REGIONS IN DATA EXCHANGE SNOWFLAKE_DATA_MARKETPLACE;
For more information, see Consumer accounts (private listings only).
targets
examples¶
Define a set of target accounts for this listing.
. . .
targets:
accounts: ["Org1.Account1", "Org2.Account2"]
. . .
Define a set of target regions for this listing.
. . .
targets:
regions: ["PUBLIC.AWS_US_EAST_1", "PUBLIC.AZURE_WESTUS2"]
. . .
auto_fulfillment
¶
Cross-Cloud Auto-fulfillment allows the data product associated with a listing
to be automatically fulfilled to other Snowflake regions.
The auto_fulfillment
field defines how that auto-fulfillment takes place.
For more information on Cross-Cloud Auto-fulfillment, see Configure Cross-Cloud Auto-Fulfillment.
Optional only if you’re sharing to accounts in the same region, otherwise required.
The auto_fulfillment
field is:
Required if your data product is an application package.
Required for private listings if the target accounts are outside the provider’s region.
Optional but recommended for marketplace listings if your data product is a share.
Contains the following name value pairs:
auto_fulfillment.refresh_schedule
<num> MINUTE
- Number of minutes. Minimum 10 minutes, maximum 8 days, or 11520 minutes.If
refresh_type
is specified asSUB_DATABASE_WITH_REFERENCE_USAGE
, do not include this setting. The refresh schedule for application packages must be defined at the account level and cannot specified at the listing level.For more information see Set account-level refresh frequency.
USING CRON <expression>
- Defines the data product auto-fulfillment refresh schedule.The syntax for
USING CRON
andREPLICATION SCHEDULE
are the same. See CREATE REPLICATION GROUP parameters .
auto_fulfillment.refresh_type
(required when usingauto_fulfillment
): Must be one of -SUB_DATABASE
- database replication (object level) - recommended.SUB_DATABASE_WITH_REFERENCE_USAGE
- application package.FULL_DATABASE
- database replication (for the entire database)
auto_fulfillment.refresh_schedule_override
(optional): Overrides the defined update refresh frequency for all listings that use the same database. When this value isFALSE
, listing updates fail when multiple listings sharing the same database have different refresh frequencies.TRUE
- enables the refresh frequency override.FALSE
- (default) disables the refresh frequency override.
See also Configure Cross-Cloud Auto-Fulfillment.
auto_fulfillment.refresh_schedule
examples¶
The following example refreshes the data product associated with a listing every 10 minutes:
. . .
listing_terms: . . .
. . .
auto_fulfillment:
refresh_schedule: 10 MINUTE
refresh_type: SUB_DATABASE
. . .
The following example refreshes the data product associated with a listing on specific days and times in specific regions:
. . .
listing_terms: . . .
. . .
auto_fulfillment:
refresh_schedule: USING CRON 0 17 * * MON-FRI Europe/London
refresh_type: SUB_DATABASE
. . .
The following example enables the refresh frequency override for listings that share the same database but have different refresh frequencies:
. . .
listing_terms: . . .
. . .
auto_fulfillment:
refresh_schedule: 10 MINUTE
refresh_type: SUB_DATABASE
refresh_schedule_override: TRUE
. . .
Snowflake Native App auto_fulfillment
example¶
SUB_DATABASE_WITH_REFERENCE_USAGE
can only be used with application packages
and cannot be combined with auto_fulfillment.refresh_schedule
.
. . .
listing_terms: . . .
. . .
auto_fulfillment:
refresh_type: SUB_DATABASE_WITH_REFERENCE_USAGE
. . .
Object level auto_fulfillment
example¶
. . .
listing_terms: . . .
. . .
auto_fulfillment:
refresh_type: SUB_DATABASE
. . .
business_needs
¶
Listings are grouped by business needs for easy discovery. Business need is a describes how a specific listing meets a given business need. For more information see Business needs.
STANDARD business needs¶
business_needs.name
(required when usingbusiness_needs
):Valid values include:
“360-Degree Customer View”
“Supply Chain”
“Personalize Customer Experiences”
“Inventory Management”
“Accelerating Advertising Revenue”
“Attribution Analysis”
“Contact Data Enrichment”
“Foot Traffic Analytics”
“Audience Segmentation”
“Sentiment Analysis”
“ESG Investment Analysis”
“Fundamental Analysis”
“Quantitative Analysis”
“Risk Analysis”
“Fraud Remediation”
“Customer Onboarding”
“Identity Resolution”
“Asset Valuation”
“Economic Impact Analysis”
“Demand Forecasting”
“Population Health Management”
“Real World Data (RWD)”
“Location Planning”
“Regulatory Reporting”
“Subscriber Acquisition and Retention”
“Life Sciences Commercialization”
“Patient 360”
“Blockchain Analysis”
“Customer Acquisition”
“Data Quality and Cleansing”
“Location Data Enrichment”
“Location Geocoding”
“Machine Learning”
“Market Analysis”
“Pricing Analysis”
“Audience Activation”
business_needs[].description
(required when using business_needs
): Description of associated business_needs.name, maximum length 1000.
business_needs[].type
: STANDARD (optional).
CUSTOM business needs¶
Custom business needs include a user defined name
, description
, and required type
field with value CUSTOM.
business_needs.name
(required when using business_needs
): User defined name.
business_needs[].description
(required when using business_needs
): Description of associated business_needs.name, maximum length 1000.
business_needs[].type
: CUSTOM (required when defining custom business needs).
business_needs
examples¶
Standard without optional type
. . .
business_needs:
- name: "Real World Data (RWD)"
description: "Global weather data"
. . .
Standard with optional type
. . .
business_needs:
- name: "Real World Data (RWD)"
description: "Global weather data"
type: STANDARD
. . .
Custom with required type
. . .
business_needs:
- name: "Machinery Maintenance"
description: "Repair and maintenance data for machinery"
type: CUSTOM
. . .
categories
¶
The categories
field specifies the category or area the listing belongs to.
Categories are optional for private listings but required for marketplace listings.
Categories are used in Snowflake Marketplace to browse listings by area and help consumers find your data.
The categories
field is a list, but can only contain a single entry, from the set below:
BUSINESS
CONNECTORS
DEMOGRAPHICS
ECONOMY
ENERGY
ENVIRONMENT
FINANCIAL
GOVERNMENT
HEALTH
IDENTITY
LEGAL
LOCAL
LOOKUP_TABLES
MARKETING
MEDIA
SECURITY
SPORTS
TRANSPORTATION
TRAVEL
WEATHER
categories
example¶
. . .
categories:
- ECONOMY
. . .
data_attributes
¶
Data attributes provide consumers insight into information about the listing such as refresh rate and other characteristics.
The data_attributes
field is optional for private listings but required for marketplace listings.
For additional information on data product attributes see Data product - attributes.
Contains the following name value pairs:
data_attributes.refresh_rate
(required)Specifies how often your data product is updated in Snowflake.
One of:
CONTINUOUSLY
HOURLY
DAILY
WEEKLY
MONTHLY
QUARTERLY
ANNUALLY
STATIC
data_attributes.geography
(required), containing:Specifies the geographic regions for which your data product has coverage.
granularity
(string, required)Geographic coverage of your dataset.
One of:
LATITUDE_LONGITUDE
ADDRESS
POSTAL_CODE
CITY
COUNTY
STATE
COUNTRY
REGION_CONTINENT
geo_option
(string, required)One of:
NOT_APPLICABLE
GLOBAL
COUNTRIES
coverage
(required based on selection ofgeo_option
), containing either :states
(list of strings) containing any list of valid U.S. state name.
Or
continents
(list of strings):Any of:
ASIA
EUROPE
AFRICA
NORTH AMERICA
SOUTH AMERICA
OCEANIA
ANTARCTICA
time
(required) containing:Specifies the time period that your data product covers.
granularity
(required)
One of:
EVENT_BASED
HOURLY
DAILY
WEEKLY
MONTHLY
YEARLY
time_range
(required) containing the following name/value pairs:time_frame
(required)One of:
NEXT
LAST
BETWEEN
unit
(required)One of:
DAYS
WEEKS
MONTHS
YEARS
value
(required whentime_frame
is NEXT/LAST, integer), range 1-100.start_time
(required whentime_frame
is BETWEEN, String date), format MM-DD-YYYY.end_time
(required whentime_frame
is BETWEEN, String date), format MM-DD-YYYY.
data_attributes
example¶
. . .
data_attributes:
refresh_rate: DAILY
geography:
granularity:
- REGION_CONTINENT
geo_option: COUNTRIES
coverage:
continents:
ASIA:
- INDIA
- CHINA
NORTH AMERICA:
- UNITED STATES
- CANADA
EUROPE:
- UNITED KINGDOM
time:
granularity: MONTHLY
time_range:
time_frame: LAST
unit: MONTHS
value: 6
data_dictionary
¶
The data_dictionary
field provides consumers insight into the contents and structure of a listing before they install it into their account.
It’s optional for private listings but required for marketplace listings.
The data_dictionary
field contains a list of up to five data dictionary entries:
data_dictionary.featured
(required when usingdata_dictionary
): must be ‘featured’.data_dictionary.featured.database
(required when usingdata_dictionary
): database name.data_dictionary.featured.objects
(required when usingdata_dictionary
): list of name value pairs -name
(string, required): object nameschema
(string, required): schemadomain
(required):One of:
DATABASE
SCHEMA
TABLE
VIEW
EXTERNAL_TABLE
MATERIALIZED_VIEW
DIRECTORY_TABLE
FUNCTION
COLUMN
See also Data product - data dictionary.
data_dictionary
example¶
. . .
data_dictionary:
featured:
database: "WEATHERDATA"
objects:
- name: "GLOBAL_WEATHER"
schema: "PUBLIC"
domain: "TABLE"
- name: "GLOBAL_WEATHER_REPORT"
schema: "PUBLIC"
domain: "TABLE"
. . .
usage_examples
¶
The usage_examples
field is optional for private listings but required for marketplace listings.
Contains a list the following name value pairs:
usage.title
(String, required ): Usage example title, maximum length 110 characters.usage.description
(String, optional): Associated description, maximum length 300 characters.usage.query
(String, required) : Query associated with the usage example, maximum length 30000 characters.
For more information, see Sample SQL queries.
usage_examples
example¶
. . .
usage_examples:
- title: "Return all weather for the US"
description: "Example of how to select weather information for the United States"
query: "select * from weather where country_code='USA'";
. . .
resources
¶
Resources contain information about the listing, including links to documentation and a video.
The resources
field is optional for private listing but required for marketplace listings.
Contains the following name value pairs:
resources.documentation
(String, required ): A fully qualified link to a page on your website with more detailed documentation for the listing. Must start withhttp
orhttps
.resources.media
(String, optional) A fully qualified link to an unlisted or public YouTube video for the listing.
For more information see Listing details.
resources
example¶
. . .
resources:
documentation: https://www.example.com/documentation/
media: https://www.youtube.com/watch?v=MEFlT3dc3uc
. . .