Skip to main content

Tags

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 goes with it 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. Which users see a tag is set by tag permissions; see Permissions.

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 to every type. Select the objects' rows in Explore and click + Tags, or use the tag control on a column's row.

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.

The UI accepts names of up to 64 characters made of letters, digits, underscores, slashes, equals signs, and hyphens, starting with a letter, digit, or underscore. The API applies no character rule and stores names of up to 128 characters, so a tag created over REST may carry a name the UI form would refuse. 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.

Who can see a tag​

Being able to see an object does not show its tags. A user sees a tag, both in the metalake's tag list and on the objects it is attached to, only when they hold APPLY_TAG on that tag or on the metalake, or own the tag.

For example, an administrator attaches the tags pii and finance to the table sales.raw.orders. A user who holds SELECT_TABLE on the table can load it and read its data, but the list of tags on the table comes back empty. Granting APPLY_TAG on pii to that user's role makes pii appear on the table and in the tag list, while finance stays hidden.

When some of an object's tags are hidden from the caller, the response to listing that object's tags sets hasInaccessibleTags to true, so a client can tell that more tags exist without seeing which ones.

APPLY_TAG also lets the holder attach and detach the tag. In this release there is no way to let a user see a tag without also letting them apply it.

What each operation needs​

Creating a tag requires CREATE_TAG on the metalake. Attaching or detaching a tag requires APPLY_TAG on that tag or on the metalake, and also 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. Altering and deleting a tag are reserved for the metalake owner and the tag owner.

See Privileges for a comprehensive list of privilege grants.

Use the API​

Tags can be created, attached, and read over REST and through the Java and Python clients. The REST reference documents each call, with the client code under the Java and Python tabs.

Last updated on