Skip to main content

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​

The example creates a tag named pii, attaches it to the customers table in catalog1.schema1, and checks that the table's columns inherit it.

  1. Create the tag. Open Govern → Tags, click + Tag, enter pii as the Tag name, and click Create tag. The name must be unique in the metalake. A Description of up to 256 characters, a Color, and Properties are optional.

  2. Attach it to the table. In Explore, open schema1 so its tables are listed, select the customers row, and click + Tags. Choose pii under Additional tags and click Update tags. Only tags that already exist in the metalake and are not already applied are offered. The same flow tags catalogs from the metalake level and schemas from a catalog.

  3. Check the columns. Open the customers table. Each row of its column list shows the column's own tags plus everything it inherits from the table, schema, and catalog, so pii appears on every column, marked with a lock icon. A tag for one column alone is added from the tag control on that column's row.

  4. See where the tag is attached. On Govern → Tags, select pii to list the objects it is attached to directly.

The Tags list holds every tag in the metalake with its description and owner, and can be searched. To remove a tag from an object, 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.

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.

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 typeName 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.

A listing of the objects carrying a tag shows direct attachments only, 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. The REST reference documents each call, with the client code under the Java and Python tabs.

Last updated on