Listing manifest reference

Creating Snowflake listings programmatically requires a manifest, written in YAML (https://yaml.org/spec/ (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
Copy

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
Copy

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 for listing_terms.link.

  • listing_terms.link (required when type is CUSTOM): A fully qualified link to the provider’s listing terms, must start with http or https.

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

targets

The targets field is required for marketplace and private listings.

Contains a list, maximum of 100 elements:

  • targets.accounts (Required if targets.region not present): List of accounts with which to share the listing.

    Each target account must be in <OrgName>.<AccountName> format, where:

or

  • targets.regions (Required if targets.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;
    Copy

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"]
. . .
Copy

Define a set of target regions for this listing.

. . .
targets:
   regions: ["PUBLIC.AWS_US_EAST_1", "PUBLIC.AZURE_WESTUS2"]
. . .
Copy

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.

Auto-fulfillment is only required if you’re sharing data to multiple regions. Do not enable it if you are sharing to accounts in the same region.

If you share data across multiple regions, the auto_fulfillment is:

  • Required if your data product is an application package.

  • Required if your data product is shared through a private listing.

  • Recommended if your data product is shared through a public listing.

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 as SUB_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 and REPLICATION SCHEDULE are the same. See CREATE REPLICATION GROUP parameters .

  • auto_fulfillment.refresh_type (required when using auto_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 is FALSE, 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
. . .
Copy

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

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

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

Object level auto_fulfillment example

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_type: SUB_DATABASE
. . .
Copy

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 using business_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"
. . .
Copy

Standard with optional type

. . .
business_needs:
 - name: "Real World Data (RWD)"
   description: "Global weather data"
   type: STANDARD
. . .
Copy

Custom with required type

. . .
business_needs:
 - name: "Machinery Maintenance"
   description: "Repair and maintenance data for machinery"
   type: CUSTOM
. . .
Copy

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

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 of geo_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 when time_frame is NEXT/LAST, integer), range 1-100.

        • start_time (required when time_frame is BETWEEN, String date), format MM-DD-YYYY.

        • end_time (required when time_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
Copy

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 using data_dictionary): must be ‘featured’.

  • data_dictionary.featured.database (required when using data_dictionary): database name.

  • data_dictionary.featured.objects (required when using data_dictionary): list of name value pairs -

    • name (string, required): object name

    • schema (string, required): schema

    • domain (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"
. . .
Copy

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'";
. . .
Copy

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 with http or https.

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

Complete YAML example for a data share listing

title: "Covid data listing"
subtitle: "Listing about covid"
description: "Example covid manifest"
profile: "MyProfile"
listing_terms:
  type: "STANDARD"
targets:
  accounts: ["Org1.Account1", "Org2.Account2"]
auto_fulfillment:
  refresh_schedule: "120 MINUTE"
  refresh_type: "SUB_DATABASE"
business_needs:
  - name: "Life Sciences Commercialization"
    description: "COVID-19 Epidemiological Data"
usage_examples:
  - title: "Get total case count by country"
    description: "Calculates the total number of cases by country, aggregated over time."
    query: "SELECT  COUNTRY_REGION, SUM(CASES) AS Cases FROM ECDC_GLOBAL GROUP BY COUNTRY_REGION;"
data_attributes:
  refresh_rate: HOURLY
  geography:
    granularity:
      - ADDRESS
    geo_option: COUNTRIES
    coverage:
      continents:
        ASIA:
          - INDIA
          - CHINA
        NORTH AMERICA:
          - UNITED STATES
          - CANADA
        EUROPE:
          - UNITED KINGDOM
  time:
    granularity: MONTHLY
    time_range:
      time_frame: BETWEEN
      start_date: 12-24-2020
      end_date: 12-25-2021
  resources:
    documentation: https://www.example.com/documentation/
    media: https://www.youtube.com/watch?v=MEFlT3dc3uc
categories:
 - HEALTH
Copy
Language: English