使用用户定义的标签自动传播标签¶

如果将对象标签应用于源对象，则标签传播会自动为目标对象分配对象标签。例如，您可以在源对象（例如表及其列）上定义标签，这些标签会自动传播到目标对象，例如从该源对象创建的视图或其他表。

自动标签传播的优势包括：

简化跨对象标签管理，特别是在将标签应用于源对象或列以便于发现和保护数据时。
确保与标签关联的任何策略都自动应用于目标对象。

只有具有账户级别 APPLY TAG 权限的标签所有者才能实现自动标签传播。

传播的类型¶

当存在对象依赖关系和/或数据移动时，您可以选择传播标签。

对象依赖关系的标签传播¶

当为对象依赖关系配置标签传播时，标签将从源对象传播到基于它的所有目标对象。例如，如果您为表 t1 上的标签 data_sensitivity 设置传播，然后基于 t1 创建两个视图，则该 data_sensitivity 标签将传播到两个视图。

从源对象创建视图、安全视图、物化视图或动态表被视为对象依赖关系。

对象依赖关系的持续传播¶

为对象依赖关系配置标签后，Snowflake 会在出现以下任何情况时持续更新目标对象：

该标签被添加到源对象或列中。
标签的值已更新。
标签已从源对象或列中移除。在这种情况下，Snowflake 会将标签从目标对象或列中移除。

例如，假设标签 data_sensitivity 在执行 CREATE VIEW 语句后从表 t1 传播到视图 v2。当您更改 t1 上的 data_sensitivity 值时，v2 上标签的值也会随之更新。

自动标签传播依赖于源对象的存在。如果删除带有标签的源对象，则标签不会传播到目标对象。由于视图依赖于其源，例如基表或其他视图，因此标签仅在源对象存在时才会传播。

用于数据移动的标签传播¶

如果为数据移动配置了标签传播，则当您通过执行以下任一操作将数据从源对象移动到另一个对象时，就会传播标签：

执行 CREATE TABLE ... AS SELECT (CTAS) 语句来创建表。
执行 CREATE DYNAMIC TABLE 语句。
执行数据操作语言 (DML) 命令。以下 DML 命令会触发标签传播：
- INSERT
- MERGE
- UPDATE
- COPY INTO

CREATE TABLE ... CLONE 和 CREATE TABLE ... LIKE 不依赖 PROPAGATE 标签属性进行标签传播。当您执行这些语句时，源中的标签始终会分配给目标对象。

备注

与针对对象依赖关系的标签传播不同，数据移动时应用于目标对象的标签不会随着源对象上标签的变化而持续更新。

设置标签传播¶

要启用自动标签传播，请使用 CREATE TAG 或 ALTER TAG 命令来设置 PROPAGATE 属性。您可以配置该属性，以便针对对象依赖关系和/或数据移动传播标签。

有关设置标签传播的说明，请参阅定义一个将自动传播的标签。

标签传播冲突¶

当标签从不同的源对象传播到同一个目标对象时，可能会发生冲突。如果标签在每个源对象中具有不同的值，则当该标签从源对象传播到目标对象时会发生冲突。

备注

如果目标对象的标签为手动应用，则现有标签值优先于传播的值，这样就不会发生冲突。

如果目标对象继承了 Snowflake 对象层次结构中级别较高的对象的值，则传播值优先，不存在冲突。

标签的 ON_CONFLICT 属性决定了发生冲突时会发生什么。您可以使用三种方法来处理标签传播冲突：

选项 1： 用字符串 CONFLICT 替换标签的值。如果您未设置标签的 ON_CONFLICT 参数，则这是默认设置。
选项 2： 用用户定义的字符串替换标签的值。您可以将 ON_CONFLICT 参数设置为该字符串。

例如，如果您希望标签的值在值冲突时为 HIGHLY CONFIDENTIAL，请使用下面的 SQL 创建标签：
```
CREATE TAG data_sensitivity
  PROPAGATE = ON_DEPENDENCY_AND_DATA_MOVEMENT
  ON_CONFLICT = 'HIGHLY CONFIDENTIAL';
```
选项 3： 使用标签 ALLOWED_VALUES 参数中值的顺序来确定要使用哪个值。设置 ON_CONFLICT = ALLOWED_VALUES_SEQUENCE 以实现此策略。

例如，假设您使用以下 SQL 语句创建了标签：
```
CREATE TAG data_sensitivity
  ALLOWED_VALUES 'confidential', 'internal', 'public'
  PROPAGATE = ON_DEPENDENCY
  ON_CONFLICT = ALLOWED_VALUES_SEQUENCE;
```
如果此标签的值 internal 和 public 之间存在冲突，则 data_sensitivity 标签的值将是 internal，因为它在允许值列表中排在 public 前面。

请注意，如果您选择使用 ON_CONFLICT = ALLOWED_VALUES_SEQUENCE，更改 ALLOWED_VALUES 参数会影响冲突的解决方式。例如，如果您更改允许列表中值的顺序，则将来的冲突可能会导致为标签分配不同的值。

要跟踪与标签传播相关的冲突，请参阅使用事件表监控标签传播。

使用事件表监控标签传播¶

您可以使用事件表收集与标签传播相关的遥测数据。在 Snowflake 开始收集事件表中的数据后，您可以查询该表、创建流以跟踪更改，或者设置警报以在某些事件发生时发送通知。

如果您希望收集标签传播的遥测数据，必须启用 ENABLE_TAG_PROPAGATION_EVENT_LOGGING 账户参数。要开始收集数据，请运行以下命令：

ALTER ACCOUNT SET ENABLE_TAG_PROPAGATION_EVENT_LOGGING = TRUE;

如果您为该标签所在的数据库设置了事件表，则事件会记录到该表中。否则，事件会记录到默认事件表中。

了解事件¶

下表描述了事件表中与标签传播对应的值，便于您关注相关事件。有关事件表结构的详细信息，请参阅事件表列。


事件表列	列字段	字段值	描述
`scope`	`name`	`snow.automatic_tag_propagation`	表示该记录与自动标签传播相关。
`record_attributes`	`tag_name`	`tag_name`	在传播过程中发生事件的标签名称。
`record_attributes`	`event_type`	`CONFLICT`	表示在传播标签时发生了冲突。
`record_attributes`	`event_type`	`TAG_PROPAGATION_LIMIT_EXCEEDED`	表示由于目标对象超过 10,000 个，Snowflake 未传播该标签。
`value`	`conflict_values`	[`tag_value`, `tag_value`]	发生冲突的标签值数组。
`value`	`resolution_type`	`DEFAULT`、`STRING_OVERRIDE` 或 `ALLOWED_VALUES_OVERRIDE`	指示在发生冲突时 Snowflake 所采取的操作。要了解冲突为何以特定方式解决，请参阅标签传播冲突。
`value`	`resolved_values`	`tag_value`	Snowflake 解决冲突后标签的最终值。

使用以下示例可以更好地理解如何在事件表中识别标签传播事件。

查询：查找与标签 TAG1 传播相关的所有事件

SELECT
  TIMESTAMP as time,
  RECORD_ATTRIBUTES['event_type'] as event_type,
  VALUE as event_details
FROM tagging_db.tagging_schema.my_event_table
WHERE
  SCOPE['name'] = 'snow.automatic_tag_propagation'
  AND RECORD_ATTRIBUTES['tag_name'] = 'TAGGING_DB.TAGGING_SCHEMA.TAG1';

查询：查找在传播过程中发生冲突的所有标签

SELECT
  DISTINCT RECORD_ATTRIBUTES['tag_name'] as tags,
  VALUE['conflict_values'] as conflicting_tag_values,
  VALUE['resolution_type'] as resolution_type,
  VALUE['resolved_value'] as resolved_value,
FROM tagging_db.tagging_schema.my_event_table
WHERE
  SCOPE['name'] = 'snow.automatic_tag_propagation'
  AND RECORD_ATTRIBUTES['event_type'] = 'CONFLICT';

查询：查找在标签 TAG1 传播过程中发生冲突的实体

SELECT
  TIMESTAMP as time,
  RECORD_ATTRIBUTES['entity_name'] as entity_name,
  RECORD_ATTRIBUTES['entity_domain'] as entity_domain,
FROM tagging_db.tagging_schema.my_event_table
WHERE
  SCOPE['name'] = 'snow.automatic_tag_propagation'
  AND RECORD_ATTRIBUTES['tag_name'] = 'TAGGING_DB.TAGGING_SCHEMA.TAG1'
  AND RECORD_ATTRIBUTES['event_type'] = 'CONFLICT';

事件的严重性¶

Tag propagation events are logged only if the LOG_EVENT_LEVEL parameter governing the table is configured to show events of that severity level. Use the following table to determine the severity level of tag propagation events.


事件类型	解决类型	严重性
`CONFLICT`	`default`	WARN
	`string_override`	INFO
	`allowed_values_override`	INFO
`TAG_PROPAGATION_LIMIT_EXCEEDED`	不适用	ERROR

受支持对象¶

以下对象类型支持从源到目标的标签传播：

列
以下类型的表：
- 表
- 动态表 – 出于标签传播的目的，创建动态表既被视为对象依赖关系，也被视为数据移动。
- 外部表
- Iceberg 表
- 临时/瞬态表
以下类型的视图：
- 视图
- 安全视图
- 物化视图

限制和注意事项¶

系统标签不会传播。
继承的标签不会传播。
标签不会从共享传播到本地对象。
对象上的标签数量不能超过标准限制。
In a single transaction that triggers tag propagation, a tag can only be propagated to up to 10,000 downstream objects. If there are more than 10,000 objects in the dependency chain, for instance, a table with more than 10,000 views referencing it, then propagation fails. You can use the event table to find out if propagation failed for this reason.
通过对对象依赖关系进行标签传播，可以将标签应用于源表和目标视图。如果标签与掩码策略关联，则重复执行该策略可能会产生相关后果。