Manage tags

Introduction

This page covers the Gravitino API for tags. For what a tag is, which object types can carry one, how inheritance resolves, and how to work with tags in the UI, see Tags.

Tag operations

Create

A tag needs a name, and can carry a comment and properties.

REST

Create a tag

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "name": "pii",
  "comment": "Personally identifiable information",
  "properties": {"owner": "data-governance"}
}' http://localhost:8090/api/metalakes/test/tags

Java

Create a tag

GravitinoClient client = ...
Tag tag = client.createTag(
    "pii",
    "Personally identifiable information",
    ImmutableMap.of("owner", "data-governance"));

Python

Create a tag

tag = client.create_tag(
    tag_name="pii",
    comment="Personally identifiable information",
    properties={"owner": "data-governance"})

List

Listing returns names, or full tag objects when details=true is set.

REST

List tags in a metalake

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/tags

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/test/tags?details=true"

Java

List tags in a metalake

String[] tagNames = client.listTags();
Tag[] tags = client.listTagsInfo();

Python

List tags in a metalake

tag_names = client.list_tags()
tags = client.list_tags_info()

Get

REST

Get a tag

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/tags/pii

Java

Get a tag

Tag tag = client.getTag("pii");

Python

Get a tag

tag = client.get_tag("pii")

Alter

Changes are applied as a list in one request.

Change	JSON	Java	Python
Rename	{"@type":"rename","newName":"tag_renamed"}	TagChange.rename("tag_renamed")	TagChange.rename("tag_renamed")
Update the comment	{"@type":"updateComment","newComment":"new_comment"}	TagChange.updateComment("new_comment")	TagChange.update_comment("new_comment")
Set a property	{"@type":"setProperty","property":"key1","value":"value1"}	TagChange.setProperty("key1", "value1")	TagChange.set_property("key1", "value1")
Remove a property	{"@type":"removeProperty","property":"key1"}	TagChange.removeProperty("key1")	TagChange.remove_property("key1")

REST

Update a tag comment and property

curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "updates": [
    {"@type": "updateComment", "newComment": "Reviewed quarterly"},
    {"@type": "setProperty", "property": "owner", "value": "privacy-office"}
  ]
}' http://localhost:8090/api/metalakes/test/tags/pii

Java

Update a tag comment and property

Tag tag = client.alterTag(
    "pii",
    TagChange.updateComment("Reviewed quarterly"),
    TagChange.setProperty("owner", "privacy-office"));

Python

Update a tag comment and property

tag = client.alter_tag(
    "pii",
    TagChange.update_comment("Reviewed quarterly"),
    TagChange.set_property("owner", "privacy-office"))

Delete

Deleting a tag also removes it from every object it was attached to.

REST

Delete a tag

curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/tags/pii

Java

Delete a tag

client.deleteTag("pii");

Python

Delete a tag

client.delete_tag("pii")

Object operations

Attach and detach tags

Both happen in one request, and either list can be omitted. The object type and full name go in the path, so the same call covers catalogs, schemas, tables, views, columns, filesets, topics, models, and functions.

REST

Attach and detach tags

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "tagsToAdd": ["pii"],
  "tagsToRemove": ["unreviewed"]
}' http://localhost:8090/api/metalakes/test/objects/table/catalog1.schema1.customers/tags

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "tagsToAdd": ["pii"]
}' http://localhost:8090/api/metalakes/test/objects/fileset/catalog1.schema1.raw_events/tags

Java

Attach and detach tags

Table customers = ...
customers.supportsTags().associateTags(
    new String[] {"pii"},
    new String[] {"unreviewed"});

Fileset rawEvents = ...
rawEvents.supportsTags().associateTags(new String[] {"pii"}, null);

Python

Attach and detach tags

customers = ...
customers.supports_tags().associate_tags(["pii"], ["unreviewed"])

raw_events = ...
raw_events.supports_tags().associate_tags(["pii"], None)

List tags

The response includes tags inherited from ancestors. With details=true each tag carries an inherited field, which a plain name listing does not.

REST

List tags on a table

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  "http://localhost:8090/api/metalakes/test/objects/table/catalog1.schema1.customers/tags?details=true"

Java

List tags on a table

Table customers = ...
String[] tagNames = customers.supportsTags().listTags();
Tag[] tags = customers.supportsTags().listTagsInfo();

Python

List tags on a table

customers = ...
tag_names = customers.supports_tags().list_tags()
tags = customers.supports_tags().list_tags_info()

Get one tag

REST

Get one tag on a table

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/objects/table/catalog1.schema1.customers/tags/pii

Java

Get one tag on a table

Tag tag = customers.supportsTags().getTag("pii");

Python

Get one tag on a table

tag = customers.supports_tags().get_tag("pii")

List objects carrying a tag

The response lists direct attachments only, so a tag attached to a catalog returns that catalog rather than the objects beneath it.

REST

List objects carrying a tag

curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/tags/pii/objects

Java

List objects carrying a tag

Tag tag = client.getTag("pii");
MetadataObject[] objects = tag.associatedObjects().objects();
int count = tag.associatedObjects().count();