CREATE TAG

Creates a tag definition in the catalog for data governance and classification.

Syntax

CREATE TAG [IF NOT EXISTS] <name> [DESCRIPTION '<desc>'] [CATEGORY <cat>]
  [ALLOWED VALUES ('<v1>', '<v2>', ...)] [PROPAGATE]

Description

## Overview Creates a tag definition in the control plane catalog. Tags are governance primitives that classify tables, views, and columns with key-value metadata. They support data discovery, policy enforcement, and compliance reporting across the data lake. A tag definition specifies the tag's name, optional category, optional value constraints, and propagation behavior. Once created, the tag can be assigned to objects using SET TAG. ## Behavior - Tag names must be unique across the catalog. - If IF NOT EXISTS is specified and the tag already exists, the statement completes successfully without modification. - If IF NOT EXISTS is omitted and the tag already exists, the command returns an error. - ALLOWED VALUES constrains assignable values at SET TAG time. If no allowed values are specified, any string value is accepted. - PROPAGATE causes SET TAG on a table to automatically cascade the assignment to all of the table's columns. This is useful for broad classification (e.g., marking an entire table as containing PII). - The command routes through the control plane catalog API. A valid catalog router connection is required. ## Compatibility CREATE TAG is a DeltaForge extension. It provides governance metadata similar to object tagging in enterprise data catalog systems.

Examples

-- Create a PII classification tag with restricted values
CREATE TAG pii_type DESCRIPTION 'PII classification' CATEGORY classification
    ALLOWED VALUES ('email', 'phone', 'ssn', 'name', 'address');

-- Create an environment tag, skip if it already exists
CREATE TAG IF NOT EXISTS environment CATEGORY environment
    ALLOWED VALUES ('production', 'staging', 'development');

-- Create a freeform ownership tag (any value allowed)
CREATE TAG data_owner DESCRIPTION 'Team or person responsible for the data' CATEGORY ownership;

-- Create a tag that propagates to child columns
CREATE TAG sensitivity DESCRIPTION 'Data sensitivity level' CATEGORY compliance
    ALLOWED VALUES ('public', 'internal', 'confidential', 'restricted') PROPAGATE;

-- Create a simple domain tag
CREATE TAG IF NOT EXISTS domain CATEGORY domain
    ALLOWED VALUES ('finance', 'marketing', 'engineering', 'hr');

Pitfalls

• Tag names are case-sensitive. Use consistent casing (e.g., lowercase with underscores) across all tag operations to avoid duplicates.
• ALLOWED VALUES are enforced at assignment time. If you need to add a new value later, use ALTER TAG to replace the full allowed-values list.
• PROPAGATE only affects future SET TAG operations. Existing column-level assignments are not created retroactively when propagation is enabled.

See Also

• ALTER_TAG
• DROP_TAG
• DESCRIBE_TAG
• SET_TAG
• UNSET_TAG
• SHOW_TAGS