Organization listing manifest reference

As a provider, you can use organizational listings to share data products securely within your organization. A manifest, written in YAML (https://yaml.org/spec/) is required to create organization listings programmatically. Use the information provided here to learn about the manifest format and its individual fields.

Organization listing fields are part of the larger Listing manifest reference. To add or modify organizational listing fields programatically locate and modify the listing manifest using DESCRIBE LISTING and ALTER LISTING commands.

Organization listing manifest

Note

Organizational listing fields can be one of the following:

  • Optional - Optional for organizational listings.

  • Required - Required for organizational listings.

The general format of a organization listing manifest is:

#
# Organization listing manifest
#
title: <Required listing title>
description: <listing description>
resources: <optional listing resources>
listing_terms: <optional listing terms>
data_dictionary: <optional data dictionary>
usage_examples: <optional usage examples>
data_attributes: <optional data attributes>
organization_profile: <Optional custom organization profile. Default "INTERNAL">
organization_targets:
  - # Required
support_contact: "<support email address>"
  - # Required
approver_contact: "<approver email address"
  - # Required when the organization_targets includes the organization_targets.discover field
locations:
  - # Optional list of regions to share into.
auto_fulfillment:
  - # Required when the target accounts are outside the provider's region, otherwise optional.
Copy

Organization listing fields

Organization listing manifests include a prefix, followed by a set of required and optional fields.

Organization listing prefix

Each organization listing manifest starts with the following fields:

  • title (String, required, maximum length 110): Listing title.

  • description (String, optional, maximum length 7500): Listing description. Markdown syntax is supported.

  • resources (String, optional): Resources for the listing.

  • listing_terms (parent with child fields, optional): Terms for the listing.

  • organization_profile (String, optional): Optional custom organization profile. Defaults to INTERNAL if not specified.

resources

Resources for the listing.

The optional resources field 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 about the type of information you can include with this field, see Details.

resources example

. . .
resources:
  documentation: https://www.example.com/documentation/
  media: https://www.youtube.com/watch?v=MEFlT3dc3uc
. . .
Copy

listing_terms

Defines the terms of service for the listing.

The optional listing_terms field contains the following name value pairs:

  • listing_terms.type

    • CUSTOM - Only CUSTOM is supported. If listing_terms.type is specified, then you must also specify a value for listing_terms.link.

  • listing_terms.link: A fully qualified link to the provider’s listing terms, which 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

data_dictionary

The optional data_dictionary field provides information on data preview and column types for the objects within the listing.

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): The database name.

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

    • name (string, required): The object name.

    • schema (string, required): The schema associated with the data dictionary.

    • domain (required):

      One of the following:

      • DATABASE

      • SCHEMA

      • TABLE

      • VIEW

      • EXTERNAL_TABLE

      • MATERIALIZED_VIEW

      • DIRECTORY_TABLE

      • FUNCTION

      • COLUMN

For more information see 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 optional usage_examples field contains a list of the following name value pairs:

  • usage.title (String, required): The usage example title. The maximum length is 110 characters.

  • usage.description (String, optional): A description of the usage example. The maximum length is 300 characters.

  • usage.query (String, required): The query associated with the usage example. The maximum length is 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

data_attributes

Data attributes provide consumers with listing information.

The optional data_attributes field contains the following name value pairs:

  • data_attributes.refresh_rate (required)

    One of the following: Specifies how often your data product is updated in Snowflake.

    • CONTINUOUSLY

    • HOURLY

    • DAILY

    • WEEKLY

    • MONTHLY

    • QUARTERLY

    • ANNUALLY

    • STATIC

  • data_attributes.geography (required):

    Specifies geographic information for the data product.

    • granularity (string, required)

      Geographic coverage of the dataset.

      One of the following:

      • LATITUDE_LONGITUDE

      • ADDRESS

      • POSTAL_CODE

      • CITY

      • COUNTY

      • STATE

      • COUNTRY

      • REGION_CONTINENT

    • geo_option (string, required)

      One of the following:

      • NOT_APPLICABLE

      • GLOBAL

      • COUNTRIES

    • coverage (required based on selection of geo_option):

      • states (list of states) containing any list of valid U.S. state names.

      Or

      • continents (list of continents):

        Any of the following:

        • ASIA

        • EUROPE

        • AFRICA

        • NORTH AMERICA

        • SOUTH AMERICA

        • OCEANIA

        • ANTARCTICA

    • time (required):

      Specifies the time period for the data product.

      • granularity (required)

      One of the following:

      • EVENT_BASED

      • HOURLY

      • DAILY

      • WEEKLY

      • MONTHLY

      • YEARLY

      • time_range (required) containing the following name/value pairs:

        • time_frame (required)

          One of the following:

          • NEXT

          • LAST

          • BETWEEN

        • unit (required)

          One of the following:

          • DAYS

          • WEEKS

          • MONTHS

          • YEARS

        • value (required when time_frame is NEXT/LAST, integer). The range is 1 to 100.

        • start_time (required when time_frame is BETWEEN, String date). The start time for the data product. The format is MM-DD-YYYY.

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

For additional information on data product attributes, see Data product - attributes.

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

organization_targets

The required organization_targets field defines who can discover and access the listing.

Contains the discovery and access fields, one of which must be specified.

discovery

Required when access isn’t specified, but otherwise optional. Defines who can discover the listing. When not present no accounts can discover the listing.

access

Required when discovery isn’t specified, but otherwise optional. Defines who can access the listing.

Both discovery and access, contain the same child fields.

Either:

all_internal_accounts : {true | false}

When true, all internal accounts can find or access the listing. When false no accounts can find or access the listing.

Or an array of accounts, followed by the optional roles array within the specified accounts.

- account: "<account_name>"

When roles is present, it specifies a list of roles within the account that can access or discover the listing. For example:

… roles: [ 'role1','role2'] …

organization_target examples

The following examples show various combinations of the discovery and access fields.

All internal accounts in the organization can discover and access the listing

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - all_internal_accounts : true
. . .
Copy

Discoverable but only accessible by limited accounts

All internal accounts within the organization can discover the listing, but only finance accounts can access the listing.

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - account: 'finance'
. . .
Copy

Discoverable but accessible by only select accounts

All internal accounts within the organization can discover the listing, but only accounts in the finance or credit account can access the listing.

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - account: 'finance'
   - account: 'credit'
. . .
Copy

Discoverable but only accessible by limited accounts and specific roles

All internal accounts within the organization can discover the listing, but only accounts in the finance account which have the accounting or debit role can access the listing.

. . .
organization_targets:
    discovery:
    - all_internal_accounts : true
    access:
    - account: 'finance'

      roles: [ 'accounting','debit']
. . .
Copy

support_contact

The email address for support information associated with the listing.

Required when the discovery field is specified.

. . .
support_contact: "support@exampledomain.com"
. . .
Copy

approver_contact

The email address for the listing approver.

Required when the discovery field is specified.

. . .
  approver_contact: "approver@exampledomain.com"
. . .
Copy

locations

Specifies the optional locations which can discover or access the listing.

The access_regions field is required when locations is specified and it must include one of the following sub-fields:

  • ALL - All regions can discover or access the listing.

  • An array of regions names prefixed with PUBLIC which can discover or access the listing. For example access_regions: - name: PUBLIC.AWS_US_WEST_2.

    . . .
locations:
  access_regions:
  - name: "<names | ALL>"
. . .
    Copy

For a complete list of regions, see SHOW REGIONS.

Language: English