Create policy

POST 
/metalakes/:metalake/policies

Creates a policy of a built-in or custom type in the metalake and returns it.

Sign in with a bearer token or a local user's password; see Authentication.

Request

Path Parameters

metalake stringrequired

The name of the metalake

application/json

Body

oneOf

CustomPolicyCreateRequest

A request to create a policy with a custom content structure.

name stringrequired

The name of the policy

comment stringnullable

A comment for the policy

policyType stringrequired

Possible values: [custom]

The type of the policy

enabled boolean

Default value: true

Whether the policy is enabled

content

object

required

Content for a custom policy type.

supportedObjectTypes string[]required

Possible values: [catalog, schema, fileset, table, view, topic, model, function], >= 1

Declares the metadata object types the policy's rules are intended for, limited to the types a policy can be associated with. The field is not enforced: associating a policy does not check it, and object policy lookup does not filter by it. Consumers decide whether a policy type applies to the object they are processing. Responses return the values in lowercase; requests accept any case.

properties

object

A map of string-to-string properties for the policy content.

property name* string

customRules object

A map of custom rules where the key is the rule name and the value can be of any type.

IcebergCompactionPolicyCreateRequest

A request to create a policy with typed Iceberg compaction content.

name stringrequired

The name of the policy

comment stringnullable

A comment for the policy

policyType stringrequired

Possible values: [system_iceberg_compaction]

The type of the policy

enabled boolean

Default value: true

Whether the policy is enabled

content

object

required

Content for the built-in Iceberg data-compaction policy.

minDataFileMse int64

Minimum custom-data-file-mse metric that triggers compaction.

minDeleteFileNumber int64

Minimum custom-delete-file-number metric that triggers compaction.

dataFileMseWeight int64

Weight of the data-file MSE term in the score expression.

deleteFileNumberWeight int64

Weight of the delete-file-number term in the score expression.

maxPartitionNum int64

Maximum partitions selected for one compaction run.

rewriteOptions

object

Options expanded to job.options.* on the rewrite job.

property name* string

IcebergEncryptionPolicyCreateRequest

A request to create a policy with typed Iceberg encryption content.

name stringrequired

The name of the policy

comment stringnullable

A comment for the policy

policyType stringrequired

Possible values: [system_iceberg_encryption]

The type of the policy

enabled boolean

Default value: true

Whether the policy is enabled

content

object

required

Content for the built-in policy that governs Iceberg table encryption.

oneOf

Encryption required

required

Possible values: [true]

allowedKeys required

Possible values: >= 1

Encryption optional

required required

Possible values: [false]

schemaVersion int32required

Possible values: [1]

The version of this policy content schema.

required boolean

Default value: true

Whether matching tables must declare an encryption key.

allowedKeys

object[]

Exact {provider, keyId} identities that matching tables may declare. At least one is required when encryption is required. Protocol api is not part of the identity.

Array [

provider stringrequired

Possible values: non-empty, Value must match regular expression ^[A-Za-z0-9][A-Za-z0-9_-]*$

Named KMS config handle. Distinct from catalog plugin provider (for example lakehouse-iceberg). Protocol api is config on this handle, not part of the key identity.

keyId stringrequired

Possible values: non-empty, Value must match regular expression .*\S.*

The unmodified provider-native key identifier.

]

enforcement string

Possible values: [report, deny-create]

Default value: report

Whether a violation is reported or causes table creation to be denied.

Responses

200

The new policy, with its type, content, enabled state and audit information.

application/vnd.gravitino.v1+json

Schema

Schema

code int32

Possible values: [0]

Status code of the response

policy

object

A policy whose content is determined by its policy type.

oneOf

CustomPolicy

A policy with custom content

name stringrequired

The name of the policy

comment stringnullable

A comment about the policy

policyType stringrequired

Possible values: [custom]

The type of the policy

enabled booleanrequired

Whether the policy is enabled

audit

object

required

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

inherited booleannullable

Whether the policy is inherited from the parent metadata object

content

object

required

Content for a custom policy type.

supportedObjectTypes string[]required

Possible values: [catalog, schema, fileset, table, view, topic, model, function], >= 1

Declares the metadata object types the policy's rules are intended for, limited to the types a policy can be associated with. The field is not enforced: associating a policy does not check it, and object policy lookup does not filter by it. Consumers decide whether a policy type applies to the object they are processing. Responses return the values in lowercase; requests accept any case.

properties

object

A map of string-to-string properties for the policy content.

property name* string

customRules object

A map of custom rules where the key is the rule name and the value can be of any type.

IcebergCompactionPolicy

A policy with typed Iceberg compaction content.

name stringrequired

The name of the policy

comment stringnullable

A comment about the policy

policyType stringrequired

Possible values: [system_iceberg_compaction]

The type of the policy

enabled booleanrequired

Whether the policy is enabled

audit

object

required

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

inherited booleannullable

Whether the policy is inherited from the parent metadata object

content

object

required

Content for the built-in Iceberg data-compaction policy.

minDataFileMse int64

Minimum custom-data-file-mse metric that triggers compaction.

minDeleteFileNumber int64

Minimum custom-delete-file-number metric that triggers compaction.

dataFileMseWeight int64

Weight of the data-file MSE term in the score expression.

deleteFileNumberWeight int64

Weight of the delete-file-number term in the score expression.

maxPartitionNum int64

Maximum partitions selected for one compaction run.

rewriteOptions

object

Options expanded to job.options.* on the rewrite job.

property name* string

IcebergEncryptionPolicy

A policy with typed Iceberg encryption content.

name stringrequired

The name of the policy

comment stringnullable

A comment about the policy

policyType stringrequired

Possible values: [system_iceberg_encryption]

The type of the policy

enabled booleanrequired

Whether the policy is enabled

audit

object

required

Audit information for a Gravitino resource.

creator string

The user who created the resource

createTime date-time

The time the resource was created

lastModifier string

The user who last modified the resource

lastModifiedTime date-time

The time the resource was last modified

inherited booleannullable

Whether the policy is inherited from the parent metadata object

content

object

required

Content for the built-in policy that governs Iceberg table encryption.

oneOf

Encryption required

required

Possible values: [true]

allowedKeys required

Possible values: >= 1

Encryption optional

required required

Possible values: [false]

schemaVersion int32required

Possible values: [1]

The version of this policy content schema.

required boolean

Default value: true

Whether matching tables must declare an encryption key.

allowedKeys

object[]

Exact {provider, keyId} identities that matching tables may declare. At least one is required when encryption is required. Protocol api is not part of the identity.

Array [

provider stringrequired

Possible values: non-empty, Value must match regular expression ^[A-Za-z0-9][A-Za-z0-9_-]*$

Named KMS config handle. Distinct from catalog plugin provider (for example lakehouse-iceberg). Protocol api is config on this handle, not part of the key identity.

keyId stringrequired

Possible values: non-empty, Value must match regular expression .*\S.*

The unmodified provider-native key identifier.

]

enforcement string

Possible values: [report, deny-create]

Default value: report

Whether a violation is reported or causes table creation to be denied.

Example (from schema)

{
  "code": 0
}

PolicyResponse

{
  "code": 0,
  "policy": {
    "name": "my_policy1",
    "comment": "This is a test policy",
    "policyType": "custom",
    "enabled": false,
    "content": {
      "customRules": {
        "rule1": 123
      },
      "supportedObjectTypes": [
        "schema",
        "table",
        "model",
        "topic",
        "fileset",
        "catalog"
      ],
      "properties": {
        "key1": "value1"
      }
    },
    "inherited": null,
    "audit": {
      "creator": "anonymous",
      "createTime": "2025-08-04T10:29:23.463Z"
    }
  }
}

409

A policy with the same name already exists in the metalake.

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]deprecated

Deprecated diagnostic stack trace. Enterprise omits it by default because it can expose internal implementation details. Operators can opt in for controlled diagnostics with gravitino.server.webserver.includeErrorStackTrace=true. See OWASP REST Security: Error handling and CWE-209.

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string"
}

PolicyAlreadyExistsException

{
  "code": 1004,
  "type": "PolicyAlreadyExistsException",
  "message": "Failed to operate policy(s) [my_policy] operation [CREATE], reason [PolicyAlreadyExistsException]",
  "stack": [
    "org.apache.gravitino.exceptions.PolicyAlreadyExistsException: Gag my_policy already exists",
    "..."
  ]
}

5xx

The server hit an internal error that the client usually cannot fix by changing the request.

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]deprecated

Deprecated diagnostic stack trace. Enterprise omits it by default because it can expose internal implementation details. Operators can opt in for controlled diagnostics with gravitino.server.webserver.includeErrorStackTrace=true. See OWASP REST Security: Error handling and CWE-209.

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string"
}

Example

{
  "code": 1002,
  "type": "RuntimeException",
  "message": "Internal Server Error",
  "stack": [
    "java.lang.RuntimeException: Internal Server Error"
  ]
}

Loading...