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

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

REST

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

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

Python

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

List Tags

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

REST

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

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

Python

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

Get a Tag

REST

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

Java

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

Python

tag = client.get_tag("pii")

Alter a Tag

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

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

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

Python

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

Delete a Tag

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

REST

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

Java

client.deleteTag("pii");

Python

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

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

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

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

Python

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

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

List Tags on an Object

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

REST

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

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

Python

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

Get One Tag on an Object

REST

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

Java

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

Python

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

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

Java

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