Policies

A policy is a named set of rules that you create once in a metalake and attach to metadata objects. Attaching a policy to a catalog or schema applies it to everything beneath, so a setting that varies by table can be expressed once at the level where it holds and overridden where it does not.

Tags and policies are close cousins, and the difference is what they carry. A tag classifies, and its content is its name. A policy prescribes, and its content is a set of rules something acts on.

Policies come in two kinds. A built-in policy has a type that Gravitino defines and a consumer that acts on it. A custom policy carries rules of your own, which Gravitino stores, inherits, and serves back to whatever system you build around it.

Common uses:

• Setting table maintenance behavior for a whole catalog rather than table by table, and letting new tables pick it up without further work
• Recording a rule once against metadata that lives in several catalogs, so every engine reaching those objects through Gravitino sees the same rule
• Feeding an external enforcement or scheduling system that reads policies from Gravitino rather than keeping its own copy of what applies where

Quick start

The example creates a custom policy named retention_30d with a 30-day retention rule and attaches it to the catalog catalog1, so every schema and table beneath it inherits the policy.

UI

1. Create the policy. Open Govern → Policies and click + Policy. Enter retention_30d as the Policy name; the Policy type is Custom. Under Supported object types, choose Catalog, Schema, and Table. Under Rules, click Add rule and enter retentionDays as the Rule name and 30 as the Rule content. A Comment and Properties are optional, and Enabled is on by default. Click Create policy.

2. Attach it to the catalog. In Explore, open the metalake so its catalogs are listed, select the catalog1 row, click + Policies, choose retention_30d under Policies, and click Update policies. Only policies not already applied to the object are offered. On a single object's page, the Policies control in the header does the same.

3. See where the policy is attached. On Govern → Policies, the Attached to column for retention_30d counts the objects it is attached to directly, here one catalog.

The Policies list shows each policy's status, type, and supported object types. Policies created over REST, including built-in ones, appear alongside the rest. Clicking a policy's name opens it for editing. To switch policies on or off, select them and click Enable or Disable.

Inherited policies carry no remove control. Detaching removes the direct attachment only, so an object still shows a policy it inherits from an ancestor.

Deleting a policy removes it from every object it was attached to, with no warning about how many objects that affects and no way to recover the attachments.

REST

1. Create the policy. For a built-in policy type supportedObjectTypes cannot be changed after creation. For a custom policy, a content update can change it.

   Create a custom policy

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

2. Attach it to the catalog. The request also accepts policiesToRemove, and either list can be omitted.

   Attach and detach policies

   curl -sS -X POST "https://{gravitino_host}/api/metalakes/{metalake}/objects/catalog/catalog1/policies" \
     -H "Accept: application/vnd.gravitino.v1+json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
     "policiesToAdd": ["retention_30d"]
   }'

3. See where the policy is attached. The response lists direct attachments only, so it returns catalog1 rather than the objects beneath it.

   List objects carrying a policy

   curl -sS "https://{gravitino_host}/api/metalakes/{metalake}/policies/retention_30d/objects" \
     -H "Accept: application/vnd.gravitino.v1+json" \
     -H "Authorization: Bearer $TOKEN"

The policy model

Policy types

Type	Rules	Consumed by
system_iceberg_compaction	Compaction thresholds and scheduling	Table maintenance service
system_iceberg_encryption	Required encryption and allowed KMS keys	Iceberg table creation in Gravitino
custom	A free-form map you define	A system you provide

A built-in type has a name beginning with system_ and a content shape Gravitino defines. The compaction policy is documented in Iceberg compaction policy, and the service that acts on it in Table maintenance service.

The encryption policy is checked when an Iceberg table is created. Its rules say whether encryption is required, which KMS keys are allowed, and whether a noncompliant create is reported (report, the default) or refused (deny-create). It can be attached to catalogs, schemas, and tables, and only one enabled encryption policy may reach a table. When two do, the create fails.

A custom policy has type custom, and Gravitino makes no attempt to interpret what is inside customRules. The rules are stored, inherited down the hierarchy, and returned to any client that asks.

The UI creates custom policies only. A built-in policy is created over REST with its own content shape.

What can carry a policy

A metadata object is identified by a type and a name, with each level below the catalog separated by a dot. Eight object types can carry a policy.

Object type	Name form
CATALOG	{catalog_name}
SCHEMA	{catalog_name}.{schema_name}
TABLE	{catalog_name}.{schema_name}.{table_name}
VIEW	{catalog_name}.{schema_name}.{view_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}

Columns cannot carry a policy, which is narrower than tags. A metalake cannot carry one either, so to reach every object in a catalog, attach the policy to the catalog.

Content

Policy content has three parts: the supportedObjectTypes list, the rules, and properties.

supportedObjectTypes is a declaration and is not enforced. Associating a policy does not check it, and object policy lookup does not filter by it, so a policy whose content lists only TABLE can be attached to a catalog or a schema and is returned by lookups on those objects. Each consumer decides whether a policy type applies to the object it is processing.

For a built-in policy type the field cannot be changed after creation. A custom policy content update replaces the whole content and can change it.

The rules are what a consumer evaluates. For a custom policy they live under customRules as a map you define, where the name is yours and the value is any JSON value.

customRules for a custom policy

"customRules": {
  "retentionDays": 30,
  "maxTableSizeGb": 500,
  "requiresApproval": true
}

Gravitino does not interpret those names or values. Whatever consumes the policy decides what retentionDays means and what to do about it.

A built-in policy has a rule set Gravitino defines, and the service that consumes it documents how those rules are applied. The compaction policy's content carries minDataFileMse, minDeleteFileNumber, dataFileMseWeight, deleteFileNumberWeight, maxPartitionNum, and rewriteOptions, from which Gravitino derives the trigger and score expressions. Those names and their meanings are covered in Compaction policy.

Properties describe the policy itself rather than the behavior it asks for. Rules change as you adjust thresholds, and properties stay stable. The compaction policy uses properties for its strategy type and job template name, which tell the table maintenance service what to run, and those are set by Gravitino rather than by you. For a custom policy, properties are yours, and suit facts such as which team owns the policy, which system consumes it, or which version of a rule set it represents. Anything evaluated against an object belongs in rules instead.

Properties sit on the policy rather than on an attachment, so every object carrying the policy sees the same values.

The enabled flag

The enabled flag marks a policy as active or inactive for readers. Gravitino does not act on it for custom and compaction policies, so disabling one does not detach it or change what a consumer receives. Treat it as a signal to whoever reads the policy, useful for holding a policy through review without deleting it. The encryption policy is the exception: a disabled one is ignored at table creation.

Inheritance

An object shows the policies attached to it plus the policies attached to each of its ancestors, so a policy on a catalog applies to every schema, table, view, fileset, topic, model, and function beneath it. For catalogs that support multi-level schemas, the intermediate schemas are ancestors too.

Each policy appears once, whether it reaches the object through one ancestor or several. A policy attached directly to the object counts as direct even when an ancestor carries it too.

Direct and inherited attachments are distinguishable. In the UI an inherited policy is marked with a lock icon. Over REST, a policy listing requested with details=true carries an inherited field on each policy, which a plain listing of names does not.

A policy 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 policy to a catalog takes effect immediately for tables created afterward.

Listing the objects that carry a policy returns direct attachments only. A policy attached to a catalog returns the catalog, not the schemas and tables beneath it.

Permissions

Policy permissions are held on the policy, and apply in addition to permissions on the objects being governed.

Creating a policy requires CREATE_POLICY on the metalake. Reading a policy and attaching or detaching it requires APPLY_POLICY, granted on the metalake or on that one policy.

Altering and deleting a policy are reserved for the metalake owner and the policy owner. Attaching a policy also requires access to the object being governed. Policy listings show only the policies that user is allowed to read.

See Privileges for a comprehensive list of privilege grants.

Use the API

Policies can be created, attached, and read over REST and through the Java client. The REST reference documents each call, with the client code under the Java tab.