数据产品规范

定义提供商愿意与分析运行者共享的一组表，以及共享规则（例如策略、列格式以及表是否必须配合模板使用）。

数据提供商通过调用 REGISTER_DATA_OFFERING 提交此规范，这将返回一个可在协作规范中使用的产品 ID。

在注册数据产品的账户加入协作之前，该数据产品在协作中不可用。

您必须拥有 REGISTER DATA OFFERING 账户权限才能加入任何可以激活数据的协作；即，您是分析运行者且协作规范包含 activation_destinations 字段。有关更多信息，请参阅 访问管理 API 参考指南。

架构：

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: data_offering        # Required: Must be "data_offering"
name: <data_offering_name>      # Required: Unique name (max 75 chars)
version: <version_string>       # Required: Version identifier (max 20 chars)
description: <data_offering_description>  # Optional: Description (max 1,000 chars)

datasets:                       # Required: Tables to share
  - alias: <dataset_name>       # One or more dataset items...
    data_object_fqn: <database.schema.table_name>  # Required: Fully-qualified table name
    allowed_analyses: <allowed_analysis_type>      # Required: template_only or template_and_freeform_sql
    object_class: <object_class>    # Optional: ads_log or custom
    schema_and_template_policies:   # Required: Column definitions
      <column_name>:                # One or more column definitions...
        category: <category_type>   # Required: join_standard, join_custom, timestamp, passthrough, or event_type
        column_type: <format_type>  # Required for join_standard category, omitted for other categories.
        activation_allowed: <true_or_false>  # Optional: Whether column can be used for activation
    freeform_sql_policies:      # Optional: Policies for freeform SQL queries
      aggregation_policy:       # Optional: Single aggregation policy
        name: <fully_qualified_policy_name>
        entity_keys:            # Optional: Entity key columns
          - <column_name>       # One or more POSSIBLY RENAMED column names...
      join_policy:              # Optional: Single join policy
        name: <fully_qualified_policy_name>
        columns:                # Optional: Columns this policy applies to
          - <column_name>       # One or more POSSIBLY RENAMED column names...
      masking_policies:         # Optional: Masking policies
        - name: <fully_qualified_policy_name>  # One or more masking policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more POSSIBLY RENAMED column names...
      projection_policies:      # Optional: Projection policies
        - name: <fully_qualified_policy_name>  # One or more projection policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more POSSIBLY RENAMED column names...
      row_access_policy:        # Optional: Row access policy
        name: <fully_qualified_policy_name>
        columns:              # Optional: Columns this policy applies to
          - <column_name>     # One or more POSSIBLY RENAMED column names...
    require_freeform_sql_policy: <true_or_false>  # Optional: Require a policy for freeform SQL
api_version

所使用的 Collaboration API 的版本。必须是 2.0.0

spec_type

规范类型标识符。必须是 data_offering

name: data_offering_name

要向协作者公开的一组表和列的名称。此名称用作协作规范中的数据产品参考值。您可以针对不同的用例，创建包含重叠表和列的多个数据产品。必须遵循 Snowflake 标识符规则，长度最多 75 个字符，并且在您的 Snowflake Data Clean Room 账户中是唯一的。name_version 对在此账户的所有数据产品中必须是唯一的。

version

此数据产品规范的自定义版本标识符（最多 20 个字符）。必须遵循 Snowflake 标识符规则。版本字符串在对 VIEW_DATA_OFFERINGS 和 VIEW_REGISTERED_DATA_OFFERINGS 的响应中拥有自己的列，因此请使用可按递增值排序的值。示例：V0

:samp:`description: {data_offering_description}`（可选）

数据产品的描述（最多 1,000 个字符）。

datasets

可供协作使用的一个或多个数据集的列表。

alias: dataset_name

此数据对象的名称，用于 collaboration.run。必须遵循 Snowflake 标识符规则 并在此产品中保持唯一。最多 75 个字符。

data_object_fqn: fully_qualified_table_name

描述可供协作者使用的单个表。提供账户中源对象的完全限定名称 (database.schema.table_name)。最大长度为 773 个字符。

allowed_analyses: allowed_analysis_type

协作者可以针对此表运行的分析类型。必填字段，具有以下值：

  • template_only：选择使用 时默认使用的角色和仓库。分析运行者只能使用协作规范中列出的模板来查询此表。

  • template_and_freeform_sql：选择使用 时默认使用的角色和仓库。分析运行者可以使用协作规范中列出的模板查询此表，或者在代码环境中使用 自由格式 SQL 查询。

``object_class``（可选）

对象类型。以下值之一：

  • ads_log：选择使用 时默认使用的角色和仓库。此处列出的表和列必须符合广告日志要求。

  • custom：选择使用 时默认使用的角色和仓库。一组没有特殊要求的自定义表和列。

schema_and_template_policies

提供由 data_object_fqn 列出的表中的列名列表，并定义每列的策略和格式。只有此处列出的列可供协作者使用。每列具有以下描述符：

category: category_type

类别决定了是否应用列重命名，以及应应用哪些数据格式强制执行。category 和 column_type 决定了向分析运行者公开的列名。支持以下值：

  • join_standard：选择使用 时默认使用的角色和仓库。这是一个可联接列，其数据采用 column_type 字段中指定的格式。此列在共享数据产品中被重命名为 column_type 值。此列已添加到 Clean Room 联接策略。

  • join_custom：选择使用 时默认使用的角色和仓库。这是任何格式的可联接列。当联接列没有合适的 column_type 时，请使用此项。在共享数据产品中使用原始列名。此列已添加到 Clean Room 联接策略。

  • timestamp：选择使用 时默认使用的角色和仓库。这是一个可投影列，用于指定任何事件的时间戳。该列在共享数据产品中重命名为 timestamp。

  • passthrough：选择使用 时默认使用的角色和仓库。这是任何其他类型的可投影列。在共享数据产品中使用原始列名。

  • event_type：选择使用 时默认使用的角色和仓库。这是一个可投影列，用于记录此行的事件类型分类，例如：“purchase”、“sign-up”、“impression”、“click”等。

``column_type: <format_type>``（当 category=join_standard 时必填，其他类别类型则忽略）

数据的格式。如果数据不符合此格式，则您对 REGISTER_DATA_OFFERING 的调用将失败。为符合 category = join_standard 的列提供此字段。category 和 column_type 决定了向分析运行者公开的列名。您不能为同一个表中的多个列分配相同的 column_type 值。支持以下格式类型：

  • email：选择使用 时默认使用的角色和仓库。原始电子邮件地址。

  • hashed_email_sha256：选择使用 时默认使用的角色和仓库。经 SHA256 哈希处理的电子邮件。

  • hashed_email_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希电子邮件。

  • phone：选择使用 时默认使用的角色和仓库。不带标点符号的电话号码。例如：2015551212。

  • hashed_phone_sha256：选择使用 时默认使用的角色和仓库。经 SHA256 哈希处理的电话号码。原始号码应采用 phone 格式。

  • hashed_phone_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希电话号码。

  • device_id：选择使用 时默认使用的角色和仓库。原始设备 ID，例如移动广告 ID 或 CTV 设备 ID。

  • hashed_device_id_sha256：经 SHA256 哈希处理的设备 ID。原文应采用 device_id 格式。

  • hashed_device_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希设备 ID。

  • ip_address：选择使用 时默认使用的角色和仓库。采用 IPv4 格式的原始 IP 地址。

  • hashed_ip_address_sha256：经 SHA256 哈希处理的 IPv4 地址。原文应采用 ip_address 格式。

  • hashed_ip_address_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码的哈希 IP 地址。

  • first_name：选择使用 时默认使用的角色和仓库。原始名字。

  • hashed_first_name_sha256：选择使用 时默认使用的角色和仓库。SHA256 哈希化后的名字。原文应采用 first_name 格式。

  • hashed_first_name_b64_encoded：选择使用 时默认使用的角色和仓库。Base64 编码后的哈希化名字。

  • last_name：选择使用 时默认使用的角色和仓库。原始姓氏。

  • hashed_last_name_sha256：选择使用 时默认使用的角色和仓库。SHA256 哈希化后的姓氏。原文应采用 last_name 格式。

  • hashed_last_name_b64_encoded：选择使用 时默认使用的角色和仓库。base64 编码的哈希化后姓氏。

``activation_allowed``（可选）

此列是否可用于激活目的。默认值为 false。

``freeform_sql_policies``（可选）

如果 allowed_analyses 为 template_and_freeform_sql，则此可选字段列出了在此数据产品上运行的 SQL 自由格式查询中应应用的任何 Snowflake 策略。有关更多信息，请参阅 将 Snowflake 策略应用到数据产品（仅限自由格式查询使用）。

支持以下类型：

``aggregation_policy``（可选）

单个 聚合策略 配置。

  • name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。

  • ``entity_keys``（可选）：用作聚合策略的实体键的列名列表。NOTE：如果这些列已 重命名，则必须使用生成的列名。

``join_policy``（可选）

单个 联接策略 配置。

  • name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。NOTE：如果此列已 重命名，则必须使用生成的列名。

  • ``columns``（可选）：此策略适用的列名列表。

``masking_policies``（可选）

掩码策略 配置数组。

  • name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。NOTE：如果此列已 重命名，则必须使用生成的列名。

  • ``columns``（可选）：此策略适用的列名列表。

``projection_policies``（可选）

投影策略 配置数组。

  • name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。NOTE：如果此列已 重命名，则必须使用生成的列名。

  • ``columns``（可选）：此策略适用的列名列表。

``row_access_policy``（可选）

一个对象，用于描述 行访问策略 配置。

  • name：选择使用 时默认使用的角色和仓库。完全限定的策略名称。NOTE：如果此列已 重命名，则必须使用生成的列名。

  • ``columns``（可选）：此策略适用的列名列表。

``require_freeform_sql_policy``（可选）

此数据源是否必须定义 freeform_sql_policies。这用作故障保护，以防止在未分配策略的情况下关联至支持自由格式 SQL 查询的数据源。