Skip to main content
Last updated on

CREATE GOVERNED TAG

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 18.1 and above check marked yes Unity Catalog only

Creates a governed tag, which is an account-level resource.

To execute this statement, you must have the CREATE privilege at the account level. Account admins and workspace admins have this privilege by default.

Syntax​

CREATE GOVERNED TAG tag_key [ DESCRIPTION description ] [ VALUES ( value_name [, ...] ) ]

Parameters​

  • tag_key

    The tag key to mark as governed. The tag key must be unique within the account and is case sensitive. If a governed tag with this tag key already exists, Databricks returns an ALREADY_EXISTS error.

  • DESCRIPTION description

    An optional STRING literal. The description for the governed tag.

  • VALUES ( value_name [, ...] )

    Sets the allowed values for the governed tag. Governed tags support key-only assignments or a predefined list of values. When specified with an empty list or omitted entirely, the governed tag allows key-only tag assignments only.

    • value_name

      A STRING literal. The name for an allowed value. Case sensitive.

Requirements​

Tag keys and tag values:

  • Can be up to 256 characters.
  • Support UTF-8 encoding, including Unicode characters such as international letters, symbols, and emoji.
  • Are case-sensitive. For example, Department and department are two distinct tags.
  • Cannot contain the following characters: * . / < > % & ? \ = or control characters (ASCII 0–31)
  • Cannot begin or end with white space.

Examples​

SQL
-- Create a key-only governed tag.
> CREATE GOVERNED TAG isPii;

-- Create a governed tag with an empty values list.
> CREATE GOVERNED TAG sensitivity_level VALUES ();

-- Create a governed tag with allowed values.
> CREATE GOVERNED TAG sensitivity_level VALUES ('low', 'medium', 'high');

-- Create a governed tag with a description and allowed values.
> CREATE GOVERNED TAG pii
  DESCRIPTION 'Indicates what kind of personal identifiable information the asset contains'
  VALUES ('ssn', 'ccn', 'dob');