Object Tagging¶

Tag quotas for objects and columns¶

The string value for each tag can be up to 256 characters, with the option to specify allowed values for a tag.

The following description applies to all objects that are not tables and views:

Snowflake allows a maximum number of 50 unique tags that can be set on a single object. In a CREATE <object> or ALTER <object> statement, 100 is the maximum number of tags that can be specified in a single statement.

The maximum number of unique tags is slightly different for tables and views, including the columns in those tables and views.

Specify tag values¶

The ALLOWED_VALUES tag property enables specifying the possible string values that can be assigned to the tag when the tag is set on an object. The maximum number of possible string values for a single tag is 300.

You can specify these values when creating or replacing a tag with a CREATE TAG statement, or while modifying an existing tag key with an ALTER TAG statement. Note that the ALTER TAG statement supports adding allowed values for a tag and dropping existing values for a tag.

To determine the list of allowed values for a tag, call the GET_DDL function or the SYSTEM$GET_TAG_ALLOWED_VALUES function.

For example:

Create a tag named cost_center with 'finance' and 'engineering' as the only two allowed string values:

create tag cost_center
    allowed_values 'finance', 'engineering';

Copy

Verify the allowed values:

select get_ddl('tag', 'cost_center')

+------------------------------------------------------------------------------+
| GET_DDL('tag', 'cost_center')                                                |
|------------------------------------------------------------------------------|
| create or replace tag cost_center allowed_values = 'finance', 'engineering'; |
+------------------------------------------------------------------------------+

Copy

Modify the tag named cost_center to add 'marketing' as an allowed string value:

alter tag cost_center
    add allowed_values 'marketing';

Copy

Modify the tag named cost_center to drop 'engineering' as an allowed string value:

alter tag cost_center
    drop allowed_values 'engineering';

Copy

To obtain the list of allowed string values for a given tag, call either the GET_DDL function or the SYSTEM$GET_TAG_ALLOWED_VALUES function. For example, assuming that the tag cost_center is stored in a database named governance and a schema named tags:

select system$get_tag_allowed_values('governance.tags.cost_center');

+--------------------------------------------------------------+
| SYSTEM$GET_TAG_ALLOWED_VALUES('GOVERNANCE.TAGS.COST_CENTER') |
|--------------------------------------------------------------|
| ["finance","marketing"]                                      |
+--------------------------------------------------------------+

Copy

Tag lineage¶

A tag is inherited based on the Snowflake securable object hierarchy. Snowflake recommends defining the tag keys as closely as possible to the securable object hierarchy in your Snowflake environment.

Tag inheritance means that if a tag is applied to a table, the tag also applies to the columns in that table. This behavior is referred to as tag lineage.

It is possible to override an inherited tag on a given object. For example, if a table column inherits the tag named cost_center with a string value called sales, the tag can be updated with a more specific tag string value such as sales_na, to specify the North America sales cost center. Additionally, a new tag can be applied to the table column. Use an ALTER TABLE … ALTER COLUMN statement to update the tag string value on the column and to set one or more additional tags on a column.

After defining the tag keys and assigning tags to Snowflake objects, monitor the tags, tag references, and tag lineage using the specified table functions or query the views as shown in Monitor tags with SQL (in this topic).

Benefits¶

Ease of Use:

Define a tag once and apply it to as many different objects as desirable.

Tag Lineage:

Since tags are inherited, applying the tag to objects higher in the securable objects hierarchy results in the tag being applied to all child objects. For example, if a tag is set on a table, the tag will be inherited by all columns in that table.

Consistent Assignment with Replication:

Supported regions for feature

This feature is not available in the People’s Republic of China.

Snowflake replicates tags and their assignments within the primary database to the secondary database.

For more information, see Replication (in this topic).

Sensitive Data Tracking and Resource Usage:

Tags simplify identifying sensitive data (e.g. PII, Secret) and bring visibility to Snowflake resource usage. With data and metadata in the same system, analysts can quickly determine which resources consume the most Snowflake credits based on the tag definition (e.g. cost_center, department).

Centralized or Decentralized Management:

Tags supports different management approaches to facilitate compliance with internal and external regulatory requirements.

In a centralized approach, the tag_admin custom role creates and applies tags to Snowflake objects.

In a decentralized approach, individual teams apply tags to Snowflake objects and the tag_admin custom role creates tags to ensure consistent tag naming.

Considerations¶

Future grants:

Future grants of privileges on tags are not supported.

As a workaround, grant the APPLY TAG privilege to a custom role to allow that role to apply tags to another object.

Snowflake Native App:

Use caution when creating the setup script when tags exist in a versioned schema. For details, see version schema considerations.

Supported objects¶

The following table lists the supported objects for tags, including columns, based on the Snowflake securable object hierarchy.

A tag can be set on an object with a CREATE <object> statement or an ALTER <object> statement unless specified otherwise in the table below.

A tag can be set on a column using a either a CREATE TABLE, CREATE VIEW, ALTER TABLE … MODIFY COLUMN, or ALTER VIEW statement.

Object Tagging and masking policies¶

For details, see Tag-based masking policies.

Note that a masking policy that is directly assigned to a column takes precedence over a tag-based masking policy.

CREATE TABLE statements¶

With CREATE TABLE … LIKE, tags assigned to the source table are assigned to the target table.

Dynamic tables¶

You can create a dynamic table with a row access policy, masking policy, and tag. For more information, see:

• CREATE DYNAMIC TABLE

• Additional limitations with incremental refresh

Replication¶

Tags and their assignments can be replicated from a source account to a target account.

Tag assignments cannot be modified in the target account after the initial replication from the source account. For example, setting a tag on a secondary (i.e. replicated) database is not allowed. To modify tag assignments in the target account, modify them in the source account and replicate them to the target account.

For database replication, the replication operation fails if either of the following conditions is true:

• The primary database is in an Enterprise (or higher) account and contains a tag but one or more of the accounts approved for replication are on lower editions.

• An object contained in the primary database has a dangling reference to a tag in a different database.

To avoid a dangling reference error, replicate the database and account-level objects using a replication or failover group. Ensure that the replication group includes:

• The database containing the tags in the ALLOWED_DATABASES property.

• Other account-level objects that have a tag in the OBJECT_TYPES property (e.g. ROLES, WAREHOUSES).

  For details, refer to CREATE REPLICATION GROUP and CREATE FAILOVER GROUP.

Cloning¶

• Tag associations in the source object (e.g. table) are maintained in the cloned objects.

• For a database or a schema:

  The tags stored in that database or schema are also cloned.

  When a database or schema is cloned, tags that reside in that schema or database are also cloned.

  If a table or view exists in the source schema/database and has references to tags in the same schema or database, the cloned table or view is mapped to the corresponding cloned tag (in the target schema/database) instead of the tag in the source schema or database.

Data Sharing¶

• When the shared view and tag exist in different databases, grant the REFERENCE_USAGE privilege on the database containing the tag to the share. For details, see Share data from multiple databases.

• In the data sharing consumer account:

  • Executing the SHOW TAGS returns the shared tag, provided that the role executing the SHOW TAGS command has the USAGE privilege on the schema containing the shared tag.

    If the provider grants the READ privilege on the tag to the share or to a shared database role, the consumer can view the tag assignments for the shared tag. For details, see shared tag references.

  • If a tag from the data sharing provider account is assigned to a shared table, the data sharing consumer cannot call the SYSTEM$GET_TAG function or the TAG_REFERENCES Information Schema table function to view the tag assignment.

Discover tags¶

Snowflake supports the following options to list tags and to identify the tag string value for a given tag key.

• Identify tags in your account:

  Use the TAGS view in the Account Usage schema of the shared SNOWFLAKE database. This view can be thought of as a catalog for all tags in your Snowflake account that provides information on current and deleted tags. For example:

  SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.TAGS
  ORDER BY TAG_NAME;
  

  Copy

• Identify a value for a given tag:

  Use the SYSTEM$GET_TAG system function to return the tag value assigned to the specified tag, and the Snowflake object or column.

  SELECT SYSTEM$GET_TAG('cost_center', 'my_table', 'table');
  

  Copy

Identify assignments¶

Snowflake supports different options to identify tag assignments, depending on whether the query needs to target the account or a specific database, and whether tag lineage is necessary.

• Account-level query with lineage:

  Use the Account Usage table function TAG_REFERENCES_WITH_LINEAGE to determine all of the objects that have a given tag key and tag value that also includes the tag lineage:

  SELECT *
  FROM TABLE(
    snowflake.account_usage.tag_references_with_lineage(
      'my_db.my_schema.cost_center'
    )
  );
  

  Copy

• Account-level query without lineage:

  Use the Account Usage TAG_REFERENCES view to determine all of the objects that have a given tag key and tag value, but does not include the tag lineage:

  SELECT * FROM snowflake.account_usage.tag_references
  ORDER BY TAG_NAME, DOMAIN, OBJECT_ID;
  

  Copy

• Database-level query, with lineage:

  Every Snowflake database includes an Snowflake Information Schema. Use the Information Schema table function TAG_REFERENCES to determine all of the objects that have a given tag that also includes the tag lineage in a given database:

  SELECT *
  FROM TABLE(
    my_db.INFORMATION_SCHEMA.TAG_REFERENCES(
      'my_table',
      'table'
    )
  );
  

  Copy

• Database-level query for all of the tags on every column in a table or view, with lineage:

  Use the Information Schema table function TAG_REFERENCES_ALL_COLUMNS to obtain all of the tags that are set on every column in a given table or view.

  Note that the domain TABLE must be used for all objects that contain columns, even if the object name is a view (i.e. view, materialized view).

  SELECT *
  FROM TABLE(
    INFORMATION_SCHEMA.TAG_REFERENCES_ALL_COLUMNS(
      'my_table',
      'table'
    )
  );
  

  Copy

Accessing the Governance area in Snowsight¶

To access the Governance area, your Snowflake account must be Enterprise Edition or higher. Additionally, you must do either of the following:

• Use the ACCOUNTADMIN role.

• Use an account role that is directly granted the GOVERNANCE_VIEWER and OBJECT_VIEWER database roles.

  You must use an account role with these database role grants. Currently, Snowsight does not evaluate role hierarchies and user-defined database roles that have access to tables, views, data access policies, and tags.

  To determine if your account role is granted these two database roles, use a SHOW GRANTS command:

  SHOW GRANTS LIKE '%VIEWER%' TO ROLE data_engineer;
  

  Copy

  |-------------------------------+-----------+---------------+-----------------------------+------------+-----------------+--------------+------------|
  | created_on                    | privilege | granted_on    | name                        | granted_to | grantee_name    | grant_option | granted_by |
  |-------------------------------+-----------+---------------+-----------------------------+------------+-----------------+--------------+------------|
  | 2024-01-24 17:12:26.984 +0000 | USAGE     | DATABASE_ROLE | SNOWFLAKE.GOVERNANCE_VIEWER | ROLE       | DATA_ENGINEER   | false        |            |
  | 2024-01-24 17:12:47.967 +0000 | USAGE     | DATABASE_ROLE | SNOWFLAKE.OBJECT_VIEWER     | ROLE       | DATA_ENGINEER   | false        |            |
  |-------------------------------+-----------+---------------+-----------------------------+------------+-----------------+--------------+------------|
  

  
  

  If your account role is not granted either or both of these database roles, use the GRANT DATABASE ROLE command and run the SHOW GRANTS command again to confirm the grants:

  USE ROLE ACCOUNTADMIN;
  GRANT DATABASE ROLE SNOWFLAKE.GOVERNANCE_VIEWER TO ROLE data_engineer;
  GRANT DATABASE ROLE SNOWFLAKE.OBJECT_VIEWER TO ROLE data_engineer;
  SHOW GRANTS LIKE '%VIEWER%' TO ROLE data_engineer;
  

  Copy

  For details about these database roles, see SNOWFLAKE database roles.

Dashboard¶

As a data administrator, you can use the Dashboard interface to monitor tag and policy usage in the following ways.

• Coverage: specifies the count and percentage based on whether a table, view, or column has a policy or tag.

• Prevalence: lists and counts the most frequently used policies and tags.

The coverage and prevalence provide a snapshot as to how well the data is protected and tagged.

When you select a count number, percentage, policy name, or tag name, the Tagged Objects interface opens. The Tagged Objects interface updates the filters automatically based on your selection in the Dashboard.

The monitoring information is an alternative or complement to running complex and query-intensive operations on multiple Account Usage views.

These views might include, but are not limited to, the COLUMNS, POLICY_REFERENCES, TABLES, TAG_REFERENCES, and VIEWS views.

Tagged Objects¶

As a data administrator, you can use this table to associate the coverage and prevalence in the Dashboard to a list of specific tables, view, or columns quickly. You can also filter the table results manually as follows.

• Choose Tables or Columns.

• For tags, you can filter with tags, without tags, or by a specific tag.

• For policies, you can filter with policies, without policies, or by a specific policy.

When you select a row in the table, the Table Details or Columns tab in Data » Databases opens. You can edit the tag and policy assignments as needed.

Tag privileges¶

Snowflake supports the following privileges to determine whether users can create, set, and own tags.

The USAGE privilege on the parent database and schema are required to perform operations on any object in a schema.

Tag DDL reference¶

Snowflake supports the following DDL to create and manage tags:

• CREATE TAG

• ALTER TAG

• ALTER <object> (to set a tag on a Snowflake object)

• SHOW TAGS

• DROP TAG

• UNDROP TAG

Note that Snowflake does not support the describe operation for the tag object.

Summary of DDL commands, operations, and privileges¶

The following table summarizes the relationship between tag privileges and DDL operations.

Snowflake supports different permissions to create and set a tag on an object.

1. For a centralized tag management approach in which the tag_admin custom role creates and sets tags on all objects/columns, the following permissions are necessary:

   use role securityadmin;
   grant create tag on schema <db_name.schema_name> to role tag_admin;
   grant apply tag on account to role tag_admin;
   

   Copy

2. In a hybrid management approach, a single role has the CREATE TAG privilege to ensure tags are named consistently and individual teams or roles have the APPLY privilege for a specific tag.

   For example, the custom role finance_role role can be granted the permission to set the tag cost_center on tables and views the role owns (i.e. the role has the OWNERSHIP privilege on the table or view):

   use role securityadmin;
   grant create tag on schema <db_name.schema_name> to role tag_admin;
   grant apply on tag cost_center to role finance_role;
   

   Copy