Apply tags to Unity Catalog securable objects

This article shows how to apply tags to Unity Catalog securable objects.

Tags are attributes that include keys and optional values that you can use to organize and categorize securable objects in Unity Catalog. Using tags also simplifies search and discovery of tables and views using the workspace search functionality.

Supported securable objects

Securable object tagging is currently supported on catalogs, schemas, tables, table columns, volumes, views, registered models, and model versions. For more information about securable objects, see Securable objects in Unity Catalog.

Requirements

To add tags to Unity Catalog securable objects, you must own the object or have all of the following privileges:

  • APPLY TAG on the object

  • USE SCHEMA on the object’s parent schema

  • USE CATALOG on the object’s parent catalog

Constraints

The following is a list of tag constraints:

  • You can assign a maximum of 20 tags to a single securable object.

  • The maximum length of a tag key is 255 characters.

  • The maximum length of a tag value is 1000 characters.

  • Special characters cannot be used in tag names.

  • Tag search using the workspace search UI is supported only for tables, views, and table columns.

  • Tag search requires exact term matching.

Add and update tags using Catalog Explorer

To add and update securable object tags using Catalog Explorer:

  1. Click Catalog icon Catalog in the sidebar.

  2. Select a securable object.

  3. On the object Overview page, add or update a tag:

    • If there are no tags, click the Add tags button.

    • If there are tags, click the Edit icon Add/Edit tags icon.

    You can use the Add/Edit tags dialog to add and delete multiple tags.

    Tag keys are required. Tag values are optional.

    To add or delete table column tags, click the Icon to add a column tag or comment Add tag icon.

Add and update tags using SQL commands

Note

This feature is available in Databricks Runtime versions 13.3 and above.

You can use the ALTER <object> SQL command to tag catalogs, schemas, tables (including views, materialized views, streaming tables), volumes, and table columns. For example, you can use the SET TAGS and UNSET TAGS clauses with ALTER TABLE to manage tags on a table. See DDL statements for a list of available Data Definition Language (DDL) commands and their syntax.

For registered models, you must use Catalog Explorer or the MLflow ClientAPI. See Use tags on models.

Use tags to search for tables

You can use the Databricks workspace search bar to search for tables, views, and table columns using tag keys and tag values. You can use both table tags and table column tags. You cannot use tags to search for other tagged objects, like catalogs, schemas, or volumes.

Only tables and views that you have permission to see appear in search results. This means that you must have at least the BROWSE privilege on the object (or on the object’s parent catalog and schema) to return the object in search results.

For details, see Use tags to search for tables.

Retrieve tag information from information schema tables

Each catalog created in Unity Catalog includes an INFORMATION_SCHEMA. This schema includes tables that describe the objects known to the schema’s catalog. You must have the appropriate privileges to view the schema information.

You can query the following to retrieve tag information:

For more information, see Information schema.