CREATE TAG¶

Creates a new tag or replaces an existing tag in the system.

This command supports the following variants:

CREATE OR ALTER TAG: Creates a tag if it doesn’t exist or alters an existing tag.

See also:: ALTER TAG , SHOW TAGS , DROP TAG , UNDROP TAG

Syntax¶

CREATE [ OR REPLACE ] TAG [ IF NOT EXISTS ] <name>
    [ ALLOWED_VALUES '<val_1>' [ , '<val_2>' [ , ... ] ] ]
    [ PROPAGATE = { ON_DEPENDENCY_AND_DATA_MOVEMENT | ON_DEPENDENCY | ON_DATA_MOVEMENT }
      [ ON_CONFLICT = { '<string>' | ALLOWED_VALUES_SEQUENCE } ] ]
    [ COMMENT = '<string_literal>' ]

Copy

Important

The parameter ALLOWED_VALUES must always be set before all other parameters, such as COMMENT, for ALLOWED_VALUES to work.

Variant syntax¶

CREATE OR ALTER TAG¶

Creates a new tag if it doesn’t already exist, or transforms an existing tag into the tag defined in the statement. A CREATE OR ALTER TAG statement follows the syntax rules of a CREATE TAG statement and has the same limitations as an ALTER TAG statement.

Supported alterations include changes to the ALLOWED_VALUES and COMMENT properties.

For more information, see CREATE OR ALTER TAG usage notes.

CREATE OR ALTER TAG <name>
  [ ALLOWED_VALUES '<val_1>' [ , '<val_2>' [ , ... ] ] ]
  [ COMMENT = '<string_literal>' ]

Copy

Required parameters¶

name

Identifier for the tag. Assign the tag string value on an object using either a CREATE <object> statement or an ALTER <object> statement.

The identifier value must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (e.g. “My object”). Identifiers enclosed in double quotes are also case-sensitive.

For more details, see Identifier requirements.

Optional parameters¶

ALLOWED_VALUES 'val_1' [ , 'val_2' [ , ... ] ]

Specifies a comma-separated list of the possible string values that can be assigned to the tag when the tag is set on an object using the corresponding CREATE <object> or ALTER <object> command.

Must come before all other parameters to work.

The maximum number of tag values in this list is 300.

If a tag is configured to automatically propagate to target objects, the order of values in the allowed list can affect how conflicts are resolved. For more information, see Tag propagation conflicts.

Default: NULL (all string values are allowed, including an empty string value (that is, ' ')).

PROPAGATE = { ON_DEPENDENCY_AND_DATA_MOVEMENT | ON_DEPENDENCY | ON_DATA_MOVEMENT }

Specifies that the tag will be automatically propagated from source objects to target objects. You can configure the tag to propagate when there is an object dependency, data movement, or both.

ON_DEPENDENCY_AND_DATA_MOVEMENT: Propagates the tag when there is an object dependency or data movement.
ON_DEPENDENCY: Propagates the tag for object dependencies, but not for data movement.
ON_DATA_MOVEMENT: Propagates the tag when there is data movement, but not for object dependencies.

ON_CONFLICT = { 'string' | ALLOWED_VALUES_SEQUENCE }

Specifies what happens when there is a conflict between the values of propagated tags.

If you don’t set this parameter and there is a conflict, the value of the tag is set to the string CONFLICT.

Possible values are:

'string'

When there is a conflict, the value of the tag is set to the specified string.

ALLOWED_VALUES_SEQUENCE

The order of the values in the ALLOWED_VALUES property of the tag determines which value is used when there is a conflict. For example, suppose you created a tag with the following statement:

CREATE TAG my_tag ALLOWED_VALUES 'blue', 'red'
  PROPAGATE = ON_DEPENDENCY
  ON_CONFLICT = ALLOWED_VALUES_SEQUENCE;

Copy

If there is a conflict, then the value of my_tag will be blue because it comes before red in the allowed values list.

Default: Set the value of the tag to CONFLICT.

COMMENT = 'string_literal'

Specifies a comment for the tag.

Default: No value

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:

Privilege	Object	Notes
CREATE TAG	Schema
OWNERSHIP	Tag	A role must be granted or inherit the OWNERSHIP privilege on the object to create a temporary object that has the same name as the object that already exists in the schema. Required to execute a CREATE OR ALTER TAG statement for an existing tag.

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

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

For additional details on tag DDL and privileges, see Access control privileges.

CREATE OR ALTER TAG usage notes¶

All limitations of the ALTER TAG command apply.
Setting or unsetting a masking policy is not supported.
The parameter ALLOWED_VALUES must always be set before all other parameters, such as COMMENT, for ALLOWED_VALUES to work.

Usage notes¶

Snowflake limits the number of tags in an account to 10,000.
For more information about how tags can be associated with Snowflake objects, see Introduction to object tagging.
For more information about tag DDL authorization, see required privileges.
Regarding metadata:

Attention

Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.
CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

Examples¶

Create a tag with the key cost_center.

CREATE TAG cost_center COMMENT = 'cost_center tag';

Copy

Update cost_center to include new allowed values and unset the comment:

CREATE OR ALTER TAG cost_center ALLOWED_VALUES 'finance', 'engineering', 'sales';

Copy