Manage Policies

Introduction

This page covers the Gravitino API for policies. For what a policy is, which object types can carry one, what goes in policy content, how inheritance resolves, and how to work with policies in the UI, see Policies.

The Python client does not cover policies, so the examples below are REST and Java only.

Policy Operations

Create a Policy

A policy needs a name and a type. Content carries the rules, the object types the policy supports, and optional properties. supportedObjectTypes cannot be changed after creation.

REST

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "name": "retention_30d",
  "comment": "Thirty day retention",
  "policyType": "custom",
  "enabled": true,
  "content": {
    "customRules": {"retentionDays": 30},
    "supportedObjectTypes": ["CATALOG", "SCHEMA", "TABLE"],
    "properties": {"owner": "platform"}
  }
}' http://localhost:8090/api/metalakes/test/policies

Java

PolicyContent content = PolicyContents.custom(
    ImmutableMap.of("retentionDays", 30),
    ImmutableSet.of(
        MetadataObject.Type.CATALOG,
        MetadataObject.Type.SCHEMA,
        MetadataObject.Type.TABLE),
    ImmutableMap.of("owner", "platform"));

Policy policy = client.createPolicy(
    "retention_30d", "custom", "Thirty day retention", true, content);

The built-in compaction policy has a fixed content shape, documented in Iceberg compaction policy, and a helper that builds it with defaults.

Policy policy = client.createPolicy(
    "nightly_compaction",
    "system_iceberg_compaction",
    "Compaction defaults",
    true,
    PolicyContents.icebergDataCompaction());

List Policies

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

REST

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

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

Java

String[] policyNames = client.listPolicies();
Policy[] policies = client.listPolicyInfos();

Get a Policy

REST

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

Java

Policy policy = client.getPolicy("retention_30d");

Alter a Policy

Changes are applied as a list in one request.

Change	JSON	Java
Rename	{"@type":"rename","newName":"policy_renamed"}	PolicyChange.rename("policy_renamed")
Update the comment	{"@type":"updateComment","newComment":"new_comment"}	PolicyChange.updateComment("new_comment")
Update the content	{"@type":"updateContent","policyType":"custom","newContent":{...}}	PolicyChange.updateContent("custom", newContent)

REST

curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "updates": [
    {
      "@type": "updateContent",
      "policyType": "custom",
      "newContent": {
        "customRules": {"retentionDays": 90},
        "supportedObjectTypes": ["CATALOG", "SCHEMA", "TABLE"],
        "properties": {"owner": "platform"}
      }
    }
  ]
}' http://localhost:8090/api/metalakes/test/policies/retention_30d

Java

PolicyContent newContent = PolicyContents.custom(
    ImmutableMap.of("retentionDays", 90),
    ImmutableSet.of(
        MetadataObject.Type.CATALOG,
        MetadataObject.Type.SCHEMA,
        MetadataObject.Type.TABLE),
    ImmutableMap.of("owner", "platform"));

Policy policy = client.alterPolicy(
    "retention_30d", PolicyChange.updateContent("custom", newContent));

Enable or Disable a Policy

The flag is a marker for readers. Gravitino does not act on it, and disabling a policy neither detaches it nor changes what a consumer receives.

REST

curl -X PATCH -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{"enable": false}' \
  http://localhost:8090/api/metalakes/test/policies/retention_30d

Java

client.disablePolicy("retention_30d");
client.enablePolicy("retention_30d");

Delete a Policy

Deleting a policy 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/policies/retention_30d

Java

client.deletePolicy("retention_30d");

Object Operations

Attach and Detach Policies

Both happen in one request, and either list can be omitted. Catalogs, schemas, tables, filesets, topics, models, views, and functions can carry a policy.

REST

curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
  -H "Content-Type: application/json" -d '{
  "policiesToAdd": ["retention_30d"],
  "policiesToRemove": ["retention_7d"]
}' http://localhost:8090/api/metalakes/test/objects/catalog/catalog1/policies

Java

Catalog catalog = client.loadCatalog("catalog1");
catalog.supportsPolicies().associatePolicies(
    new String[] {"retention_30d"},
    new String[] {"retention_7d"});

Schema schema = catalog.asSchemas().loadSchema("schema1");
schema.supportsPolicies().associatePolicies(new String[] {"retention_30d"}, null);

List Policies on an Object

The response includes policies inherited from ancestors. With details=true each policy 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/catalog/catalog1/policies?details=true"

Java

Catalog catalog = client.loadCatalog("catalog1");
String[] policyNames = catalog.supportsPolicies().listPolicies();
Policy[] policies = catalog.supportsPolicies().listPolicyInfos();

Get One Policy on an Object

REST

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

Java

Policy policy = catalog.supportsPolicies().getPolicy("retention_30d");

List Objects Carrying a Policy

The response lists direct attachments only, so a policy 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/policies/retention_30d/objects

Java

Policy policy = client.getPolicy("retention_30d");
MetadataObject[] objects = policy.associatedObjects().objects();
int count = policy.associatedObjects().count();