Skip to main content

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

Create a custom policy
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

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

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

List​

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

List policies
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"

Get​

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

Alter​

Changes are applied as a list in one request.

ChangeJSONJava
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)
Update policy content
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

Enable or disable​

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.

Enable or disable a policy
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

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

Delete​

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

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

Object operations​

Attach and detach policies​

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

Attach and detach policies
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

List policies​

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

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

Get one policy​

Get a policy on an object
curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/objects/catalog/catalog1/policies/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.

List objects carrying a policy
curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
  http://localhost:8090/api/metalakes/test/policies/retention_30d/objects
Last updated on