Tags

Overview

A tag is a named label that you create once in a metalake and attach to any number of metadata objects. A tag carries an optional comment and a set of properties, so it can hold a small amount of structured detail beyond its name. The same tag can be attached to a catalog, a table, and a single column at the same time.

Tags travel with the metadata rather than with the data, so a tag applied to a table is visible to every engine and every client that reaches that table through Gravitino, no matter which system actually stores it. That makes a tag the practical way to say something once about metadata that lives in several catalogs at once.

Gravitino stores tags, resolves them down the metadata hierarchy, and shows them wherever the object appears. Common uses:

• Recording a classification once, on the catalog or schema, and having every table and column beneath it carry that classification without further work
• Answering coverage questions across catalogs you do not own, such as which objects anywhere in the metalake are marked as personal data
• Carrying a classification that arrived from another catalog through to the engines and clients that read metadata from Gravitino
• Marking objects for a downstream consumer to act on, such as a job that reads the tags on an object before deciding what to do with it

Quick start

1. Create the tag. Tags are created in the UI from Govern → Tags → + Tag. A tag needs a name, and can also carry a comment and any properties you want to keep with it.

2. Attach it to an object. In Explore, select the catalog, schema, or table rows to label and click + Tags. Only tags that already exist in the metalake are offered, so create the tag first and attach it second.

3. Label a single column. A table's column list carries its own tag control on each row, so a tag can sit on one column without applying to the rest of the table.

4. See where the tag is attached. Selecting a tag name in the tag list shows the objects it is attached to directly.

The tag model

What can carry a tag

A metadata object is identified by a type and a name, with each level below the catalog separated by a dot. Nine object types can carry a tag.

Object type	Name form
CATALOG	{catalog_name}
SCHEMA	{catalog_name}.{schema_name}
TABLE	{catalog_name}.{schema_name}.{table_name}
VIEW	{catalog_name}.{schema_name}.{view_name}
COLUMN	{catalog_name}.{schema_name}.{table_name}.{column_name}
FILESET	{catalog_name}.{schema_name}.{fileset_name}
TOPIC	{catalog_name}.{schema_name}.{topic_name}
MODEL	{catalog_name}.{schema_name}.{model_name}
FUNCTION	{catalog_name}.{schema_name}.{function_name}

A metalake cannot carry a tag, so there is no single attachment point that covers everything at once. To reach every object in a catalog, attach the tag to the catalog.

The UI attaches tags on catalogs, schemas, tables, and columns. For the other types, use the REST API described at the end of this page.

Names and properties

A tag name is unique within its metalake and is the identifier used everywhere else, so renaming a tag changes what every stored request has to ask for.

A name is up to 64 characters of letters, digits, underscores, slashes, equals signs, and hyphens. A separator convention such as pii/email keeps a growing set readable.

Properties are free-form key and value pairs on the tag itself rather than on the attachment, so every object carrying the tag sees the same values. Properties suit facts about the tag, such as which team owns it or which external system it came from. Properties do not suit facts about one tagged object.

Inheritance

An object shows the tags attached to it plus the tags attached to each of its ancestors, so a tag on a catalog appears on every schema, table, and column beneath it. For catalogs that support multi-level schemas, the intermediate schemas are ancestors too, so a schema two levels down inherits from both of the schemas above it.

Each tag appears once, whether it reaches the object through one ancestor or several. A tag attached directly to the object counts as direct even when an ancestor carries it too.

The two are distinguishable. In the UI an inherited tag is marked with a lock icon. Over REST, a tag listing requested with details=true carries an inherited field on each tag, which a plain listing of names does not.

A tag that reaches an object only by inheritance cannot be removed there. Detach it from the ancestor that carries it, which affects every other object beneath that ancestor as well.

Inheritance is resolved when the object is read rather than stored on the object, so attaching a tag to a catalog takes effect immediately for tables created afterward.

Working with tags in the UI

Creating a tag

1. Open Govern → Tags and click + Tag.
2. Enter a Tag name, which must be unique in the metalake. A Description of up to 256 characters, a Color, and Properties are optional.
3. Click Create tag.

The Tags list holds every tag in the metalake with its description and owner, and can be searched. Deleting a tag removes it from every object it was attached to. There is no warning about how many objects that affects and no way to recover the attachments, so check where a tag is used before deleting one.

Attaching tags

1. In Explore, open the level that lists the objects to tag: the metalake for catalogs, a catalog for its schemas, a schema for its tables.
2. Select the rows and click + Tags.
3. Choose the tags under Additional tags and click Update tags.

Only tags not already applied are offered. To remove a tag, open the object on its own and remove it there. Inherited tags carry no remove control, so an object still shows a tag it inherits from an ancestor after its own attachment is removed.

Column tags are edited from the column list on the table page. A column shows its own tags plus everything it inherits from the table, schema, and catalog above it.

Finding where a tag is used

Selecting a tag name opens a view listing the objects the tag is attached to directly. Inherited reach is not included, so a tag attached to one catalog lists that catalog rather than the tables under it. Coverage questions that span a subtree are answered by walking the objects and reading the tags on each one.

Permissions

Tag permissions are held on the tag, and apply in addition to permissions on the objects being tagged.

Creating a tag requires CREATE_TAG on the metalake. Reading a tag and attaching or detaching it requires APPLY_TAG, granted on the metalake or on that one tag.

Altering and deleting a tag are reserved for the metalake owner and the tag owner. Attaching a tag also requires access to the object being tagged, so a user who can apply a tag cannot use it to reach an object they could not otherwise see. Tag listings show only the tags that user is allowed to read.

See Privileges for a comprehensive list of privilege grants.

Using the API

Tags can be created, attached, and read over REST and through the Java and Python clients, which is also the only way to tag views, filesets, topics, models, and functions today. Endpoints, payload shapes, and worked examples are in Manage Tags.