使用 Python 管理标签¶

您可以使用 Python 来管理 Snowflake 中的标签。标签是一种架构级对象，可以分配给另一个 Snowflake 对象。在分配标签时，您可以将标签与任意字符串值关联，Snowflake 会将该标签及其字符串值作为键值对存储。定义标签并将其分配给 Snowflake 对象后，您可以对其进行查询，以监控对象的使用情况并支持数据治理操作，例如审计和报告。

有关标签的更多信息，请参阅 Object Tagging 简介。

Snowflake Python APIs 表示以下类型的标签：

Tag：选择使用时默认使用的角色和仓库。表示标签对象模型，其属性包括名称、存储所在的数据库和架构，以及创建时间等。
TagValue：选择使用时默认使用的角色和仓库。表示标签的值。
TagResource：选择使用时默认使用的角色和仓库。表示对标签对象的引用，可用于获取有关标签对象的信息，并对标签对象执行操作，例如重命名标签和删除标签。

先决条件¶

在本主题中的示例中，假设您已添加了用来连接 Snowflake 和创建 Root 对象以使用 Snowflake Python APIs 的代码。

例如，以下代码使用配置文件中定义的连接参数来创建与 Snowflake 的连接：

from snowflake.core import Root
from snowflake.snowpark import Session

session = Session.builder.config("connection_name", "myconnection").create()
root = Root(session)

代码可通过生成的 Session 对象创建 Root 对象，从而使用 API 的类型和方法。有关更多信息，请参阅使用 Snowflake Python APIs 连接到 Snowflake。

为表创建并管理标签¶

以下代码示例创建名为 environment_tag 和 custom_tag 的标签，将它们分配给名为 my_tagged_table 的表，并获取该表的标签分配。然后从该表中取消设置 environment_tag 标签，并再次获取标签分配。

from snowflake.core.tag import Tag, TagValue

table = root.databases["my_database"].schemas["my_schema"].tables["my_tagged_table"]
tags = root.databases["tag_database"].schemas["tag_schema"].tags

# Create tags
environment_tag = Tag(
    name="environment_tag",
    allowed_values=["prod", "dev", "staging"],
    comment="Tag to classify environment",
)
custom_tag = Tag(
    name="custom_tag",
)
environment_tag_resource = tags.create(environment_tag, mode="ifNotExists")
custom_tag_resource = tags.create(custom_tag, mode="ifNotExists")

# Set tags on a table
table.set_tags({environment_tag_resource: TagValue(value="prod"), custom_tag_resource: TagValue(value="custom value")})

# Fetch tag assignments for the table
fetched_tags = table.get_tags()
print(f"Tags on table: {fetched_tags}")
# Tags on table: {<TagResource: 'TAG_DATABASE.TAG_SCHEMA.CUSTOM_TAG'>: TagValue(value='custom value', level='TABLE'), <TagResource: 'TAG_DATABASE.TAG_SCHEMA.ENVIRONMENT_TAG'>: TagValue(value='prod', level='TABLE')}

# Unset one of the tags from the table
table.unset_tags({environment_tag_resource})

# Fetch tag assignments again
fetched_tags_after_unset = table.get_tags()
print(f"Tags after unset: {fetched_tags_after_unset}")
# Tags after unset: {<TagResource: 'TAG_DATABASE.TAG_SCHEMA.CUSTOM_TAG'>: TagValue(value='custom value', level='TABLE')}

通过继承管理架构和表的标签¶

以下代码示例将一个名为 environment_tag 的现有标签分配给名为 my_schema 的架构，并获取该架构中名为 another_tagged_table 的表的标签分配。然后获取该表在继承情况下的标签分配 (with_lineage=True)。

from snowflake.core.tag import TagValue

schema = root.databases["my_database"].schemas["my_schema"]
table = schema.tables["another_tagged_table"]
environment_tag = root.databases["tag_database"].schemas["tag_schema"].tags["environment_tag"]

# Set tag on a schema
schema.set_tags({environment_tag: TagValue(value="prod")})

# Fetch tag assignments for the table
fetched_tags = table.get_tags()
print(f"Tags on table: {fetched_tags}")
# Tags on table: {}

# Fetch tag assignments for the table with inheritance
fetched_tags_with_lineage = table.get_tags(with_lineage=True)
print(f"Tags including inheritance: {fetched_tags_with_lineage}")
# Tags including inheritance: {<TagResource: 'TAG_DATABASE.TAG_SCHEMA.ENVIRONMENT_TAG'>: TagValue(value='prod', level='SCHEMA')}