列表清单引用¶

以编程方式创建 Snowflake 列表需要使用以 YAML (https://yaml.org/spec/ (https://yaml.org/spec/)) 编写的清单。下面介绍清单的整体格式以及清单的每个部分，包括细节和示例。

另请参阅：: CREATE LISTING、ALTER LISTING、DESCRIBE LISTING、SHOW LISTINGS、DROP LISTING

备注

字段可以是以下任意一种：

可选 – 对于 Marketplace 列表或私密列表为可选。
必填 – 对于 Marketplace 列表或私密列表为必填。
限定 – Marketplace 列表或私密列表的要求不同，并且由列表类型来限定是可选还是必填。例如，对于私密列表为可选，但对于 Marketplace 列表为必填。

列表清单的一般格式是：

#
# 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:
  - # Required for public listings, and optional for all other listing types.
data_preview:
  - # Required for public listings, and optional for all other listing types.
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

以下各部分将详细介绍每个列表清单字段、子字段，并提供关联的示例。

列表前缀¶

每个列表清单都以下列字段开头：

title （字符串，必填，最大长度 110）：列表标题。
subtitle （字符串，对于私密列表为可选，对于 Marketplace 列表为必填，最大长度 110）：列表子标题。
description （字符串，必填，最大长度 7500）：列表描述。
custom_contact （字符串，可选）：电子邮件地址。必须是有效、格式正确的电子邮件地址。
profile （字符串，对于私密列表为可选，对于 Marketplace 列表为必填）：已批准的提供商简介的名称。

有关更多信息，请参阅：提供商基本信息。

备注

要查找 profile 的值，请执行 show profiles in data exchange SNOWFLAKE_DATA_MARKETPLACE;。

列表前缀示例¶

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`¶

必填的 listing_terms （必填）字段包含以下名称值对：

listing_terms.type （枚举，必填）：必须是以下之一：
- STANDARD – 指“标准 Marketplace 产品协议”。
- OFFLINE – 表示条款由双方在线下协商。
- CUSTOM – 指定时，必须指定 listing_terms.link 的值。
listing_terms.link （类型为 CUSTOM 时为必填）：指向提供商列表条款的完全限定链接，必须以 http 或 https 开头。

有关更多信息，请参阅基本信息中表格内的 服务条款。

备注

使用者可以以编程方式接受列表条款。如需更多信息，请联系 Snowflake 支持部门。

`listing_terms` 示例¶

. . .
listing_terms:
  type: "CUSTOM"
  link: "http://example.com/my/listing/terms"
. . .

Copy

`targets`¶

targets 字段对于 Marketplace 列表和私密列表均为必填。

包含一个列表，最多 100 个元素：

targets.accounts （如果 targets.region 不存在，则为必填）：与之共享列表的账户的列表。

每个目标账户都必须采用 <OrgName>.<AccountName> 格式，其中：
- 可使用 SELECT CURRENT_ORGANIZATION_NAME(); 获取 OrgName 。
- 要获取 AccountName，可以使用
  `SHOW ACCOUNTS <https://docs.snowflake.cn/en/sql-reference/sql/show-accounts> `_ 从 account_name 中获取，或使用 Snowsight 来获取。

或

targets.regions （如果 targets.accounts 不存在，则为必填）：

与之共享列表的区域的列表。

每个目标区域的形式都必须是“region_groups_type.snowflake_region”。此外，还支持“ALL”以包括所有区域。

例如“PUBLIC.AWS_US_EAST_1”。

有关区域组类型和 Snowflake 区域的完整列表，请执行：
```
SHOW REGIONS IN DATA EXCHANGE SNOWFLAKE_DATA_MARKETPLACE;
```
Copy

有关更多信息，请参阅使用者账户（仅限私密列表）。

`targets` 示例¶

为该列表定义一组目标账户。

. . .
targets:
   accounts: ["Org1.Account1", "Org2.Account2"]
. . .

Copy

为该列表定义一组目标区域。

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

Copy

`auto_fulfillment`¶

Cross-Cloud Auto-Fulfillment 允许与列表相关联的数据产品自动履行到其他 Snowflake 区域。auto_fulfillment 字段定义了自动履行的发生方式。

有关 Cross-Cloud Auto-Fulfillment 的更多信息，请参阅配置 Cross-Cloud Auto-Fulfillment

如果您要将数据共享到多个区域，则仅需要自动履行。如果您与同一区域的账户共享，请不要启用它。

如果您在多个区域共享数据，则 auto_fulfillment：

在数据产品是应用程序包时为必填。
在数据产品通过专用列表共享时为必填。
在数据产品通过公共列表共享时为必填。

包含以下名称值对：

auto_fulfillment.refresh_schedule
- <num> MINUTE – 分钟数。最短 10 分钟，最长 8 天（11520 分钟）。
  
  如果将 refresh_type 指定为 SUB_DATABASE_WITH_REFERENCE_USAGE，不要包括此设置。应用程序包的刷新计划必须在账户级别定义，不能在列表级别指定。
  
  有关更多信息，请参阅设置账户级别刷新频率。
- USING CRON <expression> – 定义数据产品自动履行刷新计划。
  
  USING CRON 和 REPLICATION SCHEDULE 的语法是相同的。查看 CREATE REPLICATION GROUP 参数。
auto_fulfillment.refresh_type （使用 auto_fulfillment 时为必填）：必须是以下类型之一 –
- SUB_DATABASE – 数据库复制（对象级别）– 推荐。
- SUB_DATABASE_WITH_REFERENCE_USAGE – 应用程序包。
- FULL_DATABASE – 完整数据库复制。
auto_fulfillment.refresh_schedule_override`（可选）：覆盖所有使用相同数据库的列表的定义更新刷新频率。当这个值为 :code:`FALSE 时，当多个共享同一数据库的列表具有不同的刷新频率时，列表更新失败。
- TRUE – 启用刷新频率覆盖。
- FALSE –（默认）禁用刷新频率覆盖。

另请参阅配置 Cross-Cloud Auto-Fulfillment。

`auto_fulfillment.refresh_schedule` 示例¶

以下示例每 10 分钟刷新与列表相关的数据产品：

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: 10 MINUTE
  refresh_type: SUB_DATABASE
. . .

Copy

以下示例在特定地区的特定日期和时间刷新与列表相关的数据产品：

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: USING CRON  0 17 * * MON-FRI Europe/London
  refresh_type: SUB_DATABASE
. . .

Copy

以下示例启用共享同一数据库但具有不同刷新频率的列表的刷新频率覆盖。

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: 10 MINUTE
  refresh_type: SUB_DATABASE
  refresh_schedule_override: TRUE
. . .

Copy

Snowflake Native App `auto_fulfillment` 示例¶

SUB_DATABASE_WITH_REFERENCE_USAGE 只能与应用程序包一起使用，不能与 auto_fulfillment.refresh_schedule 结合使用。

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_type: SUB_DATABASE_WITH_REFERENCE_USAGE
. . .

Copy

`auto_fulfillment` 示例¶

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

Copy

`business_needs`¶

列表按业务需求分组，以便发现。业务需求描述特定列表如何满足给定的业务需求。有关更多信息，请参阅业务需求。

STANDARD 业务需求¶

business_needs.name （使用 business_needs 时为必填）：

有效值包括：
- “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 （使用 business_needs 时为必填）：关联的 business_needs.name 的描述，最大长度 1000。

business_needs[].type：STANDARD（可选）。

CUSTOM 业务需求¶

自定义业务需求包括用户定义的 name、description 和必填的 type 字段（值为 CUSTOM）。

business_needs.name （使用 business_needs 时为必填）：用户定义的名称。

business_needs[].description （使用 business_needs 时为必填）：关联的 business_needs.name 的描述，最大长度 1000。

business_needs[].type：CUSTOM（定义自定义业务需求时为必填）。

`business_needs` 示例¶

标准，无可选的 type

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

Copy

标准，有可选的 type

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

Copy

自定义，有必填的 type

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

Copy

`categories`¶

categories 字段指定列表所属的类别或区域。类别对于私密列表为可选，但对于 Marketplace 列表为必填。

在 Snowflake Marketplace 中，使用类别按区域浏览列表，并帮助使用者找到您的数据。

categories 字段是一个列表，但只能包含下面集合中的一个条目：

BUSINESS
CONNECTORS
DEMOGRAPHICS
ECONOMY
ENERGY
ENVIRONMENT
FINANCIAL
GOVERNMENT
HEALTH
IDENTITY
LEGAL
LOCAL
LOOKUP_TABLES
MARKETING
MEDIA
SECURITY
SPORTS
TRANSPORTATION
TRAVEL
WEATHER

`categories` 示例¶

. . .
categories:
 - ECONOMY
. . .

Copy

`data_attributes`¶

数据属性可让使用者深入了解有关列表的信息，如刷新率和其他特征。

data_attributes 字段对于私密列表为可选，但对于 Marketplace 列表为必填。

有关数据产品属性的更多信息，请参阅数据产品 – 属性。

包含以下名称值对：

:code:`data_attributes.refresh_rate`（必填）

指定数据产品在 Snowflake 中的更新频率。

其中之一：
- CONTINUOUSLY
- HOURLY
- DAILY
- WEEKLY
- MONTHLY
- QUARTERLY
- ANNUALLY
- STATIC
:code:`data_attributes.geography`（必填），包含：

指定数据产品覆盖的地理区域。
- :code:`granularity`（字符串，必填）
  
  数据集的地理覆盖范围。
  
  其中之一：
  - LATITUDE_LONGITUDE
  - ADDRESS
  - POSTAL_CODE
  - CITY
  - COUNTY
  - STATE
  - COUNTRY
  - REGION_CONTINENT
- :code:`geo_option`（字符串，必填）
  
  其中之一：
  - NOT_APPLICABLE
  - GLOBAL
  - COUNTRIES
- coverage`（根据所选的 :code:`geo_option 来确定是否必填），包含：
  - :code:`states`（字符串列表），包含有效美国州名的任意列表。
  或
  - :code:`continents`（字符串列表）：
    
    以下任意一项：
    
    ASIA
    
    EUROPE
    
    AFRICA
    
    NORTH AMERICA
    
    SOUTH AMERICA
    
    OCEANIA
    
    ANTARCTICA
- :code:`time`（必填），包含：
  
  指定数据产品覆盖的时间段。
  - :code:`granularity`（必填）
  其中之一：
  - EVENT_BASED
  - HOURLY
  - DAILY
  - WEEKLY
  - MONTHLY
  - YEARLY
  - :code:`time_range`（必填），包含以下名称/值对：
    
    :code:`time_frame`（必填）
    
    其中之一：
    
    NEXT
    
    LAST
    
    BETWEEN
    
    :code:`unit`（必填）
    
    其中之一：
    
    DAYS
    
    WEEKS
    
    MONTHS
    
    YEARS
    
    value`（当 :code:`time_frame 为 NEXT/LAST 时为必填，整型），范围 1-100。
    
    start_time`（当 :code:`time_frame 为 BETWEEN 时为必填，字符串日期），格式为 MM-DD-YYYY。
    
    end_time`（当 :code:`time_frame 为 BETWEEN 时为必填，字符串日期），格式为 MM-DD-YYYY。

`data_attributes` 示例¶

. . .
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`¶

data_dictionary 字段可让使用者在将列表安装到自己的账户之前，深入了解列表的内容和结构。对于公开列表，为必填，对于所有其他列表类型，为选填。

data_dictionary 字段包含由最多五个数据字典条目组成的列表：

data_dictionary.featured`（使用 :code:`data_dictionary 时为必填）：必须为“featured”。
data_dictionary.featured.database`（使用 :code:`data_dictionary 时为必填）：数据库名称。
data_dictionary.featured.objects`（使用 :code:`data_dictionary 时为必填）：名称值对的列表 –
- :code:`name`（字符串，必填）：对象名称
- :code:`schema`（字符串，必填）：架构
- :code:`domain`（必填）：
  
  其中之一：
  - DATABASE
  - SCHEMA
  - TABLE
  - VIEW
  - EXTERNAL_TABLE
  - MATERIALIZED_VIEW
  - DIRECTORY_TABLE
  - FUNCTION
  - COLUMN

另请参阅数据产品 – 数据字典。

`data_dictionary` 示例¶

. . .
data_dictionary:
 featured:
    database: "WEATHERDATA"
    objects:
       - name: "GLOBAL_WEATHER"
         schema: "PUBLIC"
         domain: "TABLE"
       - name: "GLOBAL_WEATHER_REPORT"
         schema: "PUBLIC"
         domain: "TABLE"
. . .

Copy

`data_preview`¶

data_preview 字段允许提供商在从列表数据生成的数据预览样本中识别和隐藏个人身份信息 (PII)。PII 数据是可能直接或间接泄露个人身份的数据。对于公开列表，为必填，对于所有其他列表类型，为选填。

data_preview 字段包括以下条目：

data_preview.has_pii`（在使用 :code:`data_preview 时需要）：表示 PII 是否包含在列表数据中。
- TRUE - PII 包含在列表数据中。
- FALSE - PII 不包括在列表数据中。
data_preview.metadata_overrides`（当 :code:`data_preview.has_pii 是 TRUE 时建议使用）：确定 PII 列表数据的位置，以及该数据集内包含要隐藏或公开的 PII 的对象。
- :code:`database`（字符串，必填）：数据库名称。
- :code:`objects`（列表，必填）：在数据预览示例中隐藏或显示列的对象：
  - :code:`schema`（字符串，必填）：架构名称。
  - :code:`domain`（字符串，必填）：域名。
  - :code:`name`（字符串，必填）：对象名称
  - :code:`pii_columns`（列表，可选）：包含 PII 的列。
  - :code:`overridden_pii_columns`（列表，可选）：Snowflake 分类标识为包含 PII 的列，但应在与消费者共享的数据预览样本中可用。
    
    Snowflake 会定期对生成的数据预览运行分类。运行 SHOW 命令时，任何包含 PII 的列都会在:code:classified_pii_columns 中定义。
    
    被 Snowflake 识别为包含 PII 的列仅在数据预览样本中对列表使用者隐藏。如果列表提供商确定列被错误地标识为包含 PII，他们可以使用 overridden_pii_columns 指定希望包含在数据预览样本中的特定列。

`data_preview` 示例¶

. . .
data_preview:
 has_pii: TRUE
 metadata_overrides:
    database: WEATHERDATA
    objects:
       - schema: PUBLIC
         domain: TABLE
         name: GLOBAL_WEATHER
         pii_columns: [ADDRESS, PHONE]
         overridden_pii_columns: [FIRST_NAME, LAST_NAME]
. . .

Copy

`usage_examples`¶

usage_examples 字段对于私密列表为可选，但对于 Marketplace 列表为必填。

包含以下名称值对的列表：

usage.title （字符串，必填）：使用情况示例标题，最长 110 个字符。
:code:`usage.description`（字符串，可选）：关联的描述，最长 300 个字符。
:code:`usage.query`（字符串，必填）：与使用情况示例关联的查询，最长 30000 个字符。

有关更多信息，请参阅示例 SQL 查询。

`usage_examples` 示例¶

. . .
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 字段对于私密列表为可选，但对于 Marketplace 列表为必填。

包含以下名称值对：

resources.documentation`（字符串，必填）：指向您网站上的页面的完全限定链接，其中包含有关列表的更详细文档。必须以 :code:`http 或 https 开头。
:code:`resources.media`（字符串，可选）指向列表的不公开或公开 YouTube 视频的完全限定链接。

有关更多信息，请参阅列表详细信息。

`resources` 示例¶

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

Copy

列表清单引用¶

列表前缀¶

列表前缀示例¶

listing_terms¶

listing_terms 示例¶

targets¶

targets 示例¶

auto_fulfillment¶

auto_fulfillment.refresh_schedule 示例¶

Snowflake Native App auto_fulfillment 示例¶

auto_fulfillment 示例¶

business_needs¶

STANDARD 业务需求¶

CUSTOM 业务需求¶

business_needs 示例¶

categories¶

categories 示例¶

data_attributes¶

data_attributes 示例¶

data_dictionary¶

data_dictionary 示例¶

data_preview¶

data_preview 示例¶

usage_examples¶

usage_examples 示例¶

resources¶

resources 示例¶

完整的 YAML 示例，用于数据共享列表¶

`listing_terms`¶

`listing_terms` 示例¶

`targets`¶

`targets` 示例¶

`auto_fulfillment`¶

`auto_fulfillment.refresh_schedule` 示例¶

Snowflake Native App `auto_fulfillment` 示例¶

`auto_fulfillment` 示例¶

`business_needs`¶

`business_needs` 示例¶

`categories`¶

`categories` 示例¶

`data_attributes`¶

`data_attributes` 示例¶

`data_dictionary`¶

`data_dictionary` 示例¶

`data_preview`¶

`data_preview` 示例¶

`usage_examples`¶

`usage_examples` 示例¶

`resources`¶

`resources` 示例¶