List policies

GET 
/metalakes/:metalake/policies

Returns the names of the policies in the metalake that the caller can see, or the full policies when details is true.

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

Request

Path Parameters

metalake stringrequired

The name of the metalake

Query Parameters

details boolean

Whether to return the full policy objects instead of only the policy names

Responses

200

The names of the metalake's policies, or the full policies when details is true.

application/vnd.gravitino.v1+json

Schema

Schema

oneOf

NameListResponse

code int32

Possible values: [0]

Status code of the response

names string[]

PolicyListResponse

code int32

Possible values: [0]

Status code of the response

policies

object[]

A list of policy objects

Array [

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)

{}

NameListResponse

{
  "code": 0,
  "names": [
    "my_policy1",
    "my_policy2"
  ]
}

PolicyListResponse

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

400

The request is malformed or fails validation, for example because of invalid JSON, a missing required field or an invalid parameter value. The body is normally an error model, although the server's middleware can return plain text instead.

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": 1003,
  "type": "BadRequestException",
  "message": "Malformed request"
}

404

The metalake does not exist.

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"
}

NoSuchMetalakeException

{
  "code": 1003,
  "type": "NoSuchMetalakeException",
  "message": "Failed to operate metalake(s) [test] operation [LOAD], reason [NoSuchMetalakeException]",
  "stack": [
    "org.apache.gravitino.exceptions.NoSuchMetalakeException: Metalake test does not exist",
    "..."
  ]
}

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