Skip to content

Instantly share code, notes, and snippets.

@onderkalaci

onderkalaci/polaris.txt

Created August 8, 2025 14:03
Show Gist options
  • Save onderkalaci/cf081cad8ffc3d263cfc2ce76bfa2338 to your computer and use it in GitHub Desktop.
Save onderkalaci/cf081cad8ffc3d263cfc2ce76bfa2338 to your computer and use it in GitHub Desktop.
Download ZIP
polaris
Raw
polaris.txt
openapi: 3.0.3
info:
title: Apache Polaris and Apache Iceberg REST Catalog API
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 0.0.1
description: Defines the specification for the Polaris Catalog API, which encompasses both the Iceberg REST Catalog API and Polaris-native API.
servers:
- url: '{scheme}://{host}/{basePath}'
description: Server URL when the port can be inferred from the scheme
variables:
scheme:
description: The scheme of the URI, either http or https.
default: https
host:
description: The host address for the specified server
default: localhost
basePath:
description: Optional prefix to be appended to all routes
default: ''
- url: '{scheme}://{host}:{port}/{basePath}'
description: Generic base server URL, with all parts configurable
variables:
scheme:
description: The scheme of the URI, either http or https.
default: https
host:
description: The host address for the specified server
default: localhost
port:
description: The port used when addressing the host
default: '443'
basePath:
description: Optional prefix to be appended to all routes
default: ''
security:
- OAuth2:
- catalog
- BearerAuth: []
paths:
/v1/config:
get:
tags:
- Configuration API
summary: List all catalog configuration settings
operationId: getConfig
parameters:
- name: warehouse
in: query
required: false
schema:
type: string
description: Warehouse location or identifier to request from the service
description: |2-
All REST clients should first call this route to get catalog configuration properties from the server to configure the catalog and its HTTP client. Configuration from the server consists of two sets of key/value pairs.
- defaults - properties that should be used as default configuration; applied before client configuration
- overrides - properties that should be used to override client configuration; applied after defaults and client configuration
Catalog configuration is constructed by setting the defaults, then client- provided configuration, and finally overrides. The final property set is then used to configure the catalog.
For example, a default configuration property might set the size of the client pool, which can be replaced with a client-specific setting. An override might be used to set the warehouse location, which is stored on the server rather than in client configuration.
Common catalog configuration settings are documented at https://iceberg.apache.org/docs/latest/configuration/#catalog-properties
The catalog configuration also holds an optional `endpoints` field that contains information about the endpoints supported by the server. If a server does not send the `endpoints` field, a default set of endpoints is assumed:
- GET /v1/{prefix}/namespaces
- POST /v1/{prefix}/namespaces
- GET /v1/{prefix}/namespaces/{namespace}
- DELETE /v1/{prefix}/namespaces/{namespace}
- POST /v1/{prefix}/namespaces/{namespace}/properties
- GET /v1/{prefix}/namespaces/{namespace}/tables
- POST /v1/{prefix}/namespaces/{namespace}/tables
- GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
- POST /v1/{prefix}/namespaces/{namespace}/tables/{table}
- DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}
- POST /v1/{prefix}/namespaces/{namespace}/register
- POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics
- POST /v1/{prefix}/tables/rename
- POST /v1/{prefix}/transactions/commit
responses:
'200':
description: Server specified configuration values.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogConfig'
example:
overrides:
warehouse: s3://bucket/warehouse/
defaults:
clients: '4'
endpoints:
- GET /v1/{prefix}/namespaces/{namespace}
- GET /v1/{prefix}/namespaces
- POST /v1/{prefix}/namespaces
- GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
- GET /v1/{prefix}/namespaces/{namespace}/views/{view}
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/oauth/tokens:
post:
tags:
- OAuth2 API
summary: Get a token using an OAuth2 flow (DEPRECATED for REMOVAL)
deprecated: true
operationId: getToken
description: |-
The `oauth/tokens` endpoint is **DEPRECATED for REMOVAL**. It is _not_ recommended to implement this endpoint, unless you are fully aware of the potential security implications.
All clients are encouraged to explicitly set the configuration property `oauth2-server-uri` to the correct OAuth endpoint.
Deprecated since Iceberg (Java) 1.6.0. The endpoint and related types will be removed from this spec in Iceberg (Java) 2.0.
See [Security improvements in the Iceberg REST specification](https://github.com/apache/iceberg/issues/10537)
Exchange credentials for a token using the OAuth2 client credentials flow or token exchange.
This endpoint is used for three purposes -
1. To exchange client credentials (client ID and secret) for an access token This uses the client credentials flow.
2. To exchange a client token and an identity token for a more specific access token This uses the token exchange flow.
3. To exchange an access token for one with the same claims and a refreshed expiration period This uses the token exchange flow.
For example, a catalog client may be configured with client credentials from the OAuth2 Authorization flow. This client would exchange its client ID and secret for an access token using the client credentials request with this endpoint (1). Subsequent requests would then use that access token.
Some clients may also handle sessions that have additional user context. These clients would use the token exchange flow to exchange a user token (the "subject" token) from the session for a more specific access token for that user, using the catalog's access token as the "actor" token (2). The user ID token is the "subject" token and can be any token type allowed by the OAuth2 token exchange flow, including a unsecured JWT token with a sub claim. This request should use the catalog's bearer token in the "Authorization" header.
Clients may also use the token exchange flow to refresh a token that is about to expire by sending a token exchange request (3). The request's "subject" token should be the expiring token. This request should use the subject token in the "Authorization" header.
parameters:
- name: Authorization
in: header
schema:
type: string
required: false
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/OAuthTokenRequest'
responses:
'200':
$ref: '#/components/responses/OAuthTokenResponse'
'400':
$ref: '#/components/responses/OAuthErrorResponse'
'401':
$ref: '#/components/responses/OAuthErrorResponse'
5XX:
$ref: '#/components/responses/OAuthErrorResponse'
security:
- BearerAuth: []
/v1/{prefix}/namespaces:
parameters:
- $ref: '#/components/parameters/prefix'
get:
tags:
- Catalog API
summary: List namespaces, optionally providing a parent namespace to list underneath
description: List all namespaces at a certain level, optionally starting from a given parent namespace. If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would translate into `GET /namespaces?parent=accounting` and must return a namespace, ["accounting", "tax"] only. Using 'SELECT NAMESPACE IN accounting.tax' would translate into `GET /namespaces?parent=accounting%1Ftax` and must return a namespace, ["accounting", "tax", "paid"]. If `parent` is not provided, all top-level namespaces should be listed.
operationId: listNamespaces
parameters:
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
- $ref: '#/components/parameters/prefix'
- name: parent
in: query
description: An optional namespace, underneath which to list namespaces. If not provided or empty, all top-level namespaces should be listed. If parent is a multipart namespace, the parts must be separated by the unit separator (`0x1F`) byte.
required: false
allowEmptyValue: true
schema:
type: string
example: accounting%1Ftax
responses:
'200':
$ref: '#/components/responses/ListNamespacesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - Namespace provided in the `parent` query parameter is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NoSuchNamespaceExample:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Catalog API
summary: Create a namespace
description: Create a namespace, with an optional set of properties. The server might also add properties, such as `last_modified_time` etc.
operationId: createNamespace
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNamespaceRequest'
responses:
'200':
$ref: '#/components/responses/CreateNamespaceResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'406':
$ref: '#/components/responses/UnsupportedOperationResponse'
'409':
description: Conflict - The namespace already exists
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceAlreadyExists:
$ref: '#/components/examples/NamespaceAlreadyExistsError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
get:
tags:
- Catalog API
summary: Load the metadata properties for a namespace
operationId: loadNamespaceMetadata
description: Return all stored metadata properties for a given namespace
responses:
'200':
$ref: '#/components/responses/GetNamespaceResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - Namespace not found
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NoSuchNamespaceExample:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
head:
tags:
- Catalog API
summary: Check if a namespace exists
operationId: namespaceExists
description: Check if a namespace exists. The response does not contain a body.
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - Namespace not found
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NoSuchNamespaceExample:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
delete:
tags:
- Catalog API
summary: Drop a namespace from the catalog. Namespace must be empty.
operationId: dropNamespace
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - Namespace to delete does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NoSuchNamespaceExample:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/properties:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
post:
tags:
- Catalog API
summary: Set or remove properties on a namespace
operationId: updateProperties
description: |-
Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update.
Properties that are not in the request are not modified or removed by this call.
Server implementations are not required to support namespace properties.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
examples:
UpdateAndRemoveProperties:
$ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
responses:
'200':
$ref: '#/components/responses/UpdateNamespacePropertiesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - Namespace not found
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'406':
$ref: '#/components/responses/UnsupportedOperationResponse'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'422':
description: Unprocessable Entity - A property key was included in both `removals` and `updates`
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
UnprocessableEntityDuplicateKey:
$ref: '#/components/examples/UnprocessableEntityDuplicateKey'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/tables:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
get:
tags:
- Catalog API
summary: List all table identifiers underneath a given namespace
description: Return all table identifiers under this namespace
operationId: listTables
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
responses:
'200':
$ref: '#/components/responses/ListTablesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Catalog API
summary: Create a table in the given namespace
description: |-
Create a table or start a create transaction, like atomic CTAS.
If `stage-create` is false, the table is created immediately.
If `stage-create` is true, the table is not created, but table metadata is initialized and returned. The service should prepare as needed for a commit to the table commit endpoint to complete the create transaction. The client uses the returned metadata to begin a transaction. To commit the transaction, the client sends all create and subsequent changes to the table commit route. Changes from the table create operation include changes like AddSchemaUpdate and SetCurrentSchemaUpdate that set the initial table state.
operationId: createTable
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/data-access'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableRequest'
responses:
'200':
$ref: '#/components/responses/CreateTableResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'409':
description: Conflict - The table already exists
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceAlreadyExists:
$ref: '#/components/examples/TableAlreadyExistsError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/register:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
post:
tags:
- Catalog API
summary: Register a table in the given namespace using given metadata file location
description: Register a table using given metadata file location.
operationId: registerTable
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterTableRequest'
responses:
'200':
$ref: '#/components/responses/LoadTableResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'409':
description: Conflict - The table already exists
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceAlreadyExists:
$ref: '#/components/examples/TableAlreadyExistsError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/tables/{table}:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/table'
get:
tags:
- Catalog API
summary: Load a table from the catalog
operationId: loadTable
description: |-
Load a table from the catalog.
The response contains both configuration and table metadata. The configuration, if non-empty is used as additional configuration for the table that overrides catalog configuration. For example, this configuration may change the FileIO implementation to be used for the table.
The response also contains the table's full metadata, matching the table metadata JSON file.
The catalog configuration may contain credentials that should be used for subsequent requests for the table. The configuration key "token" is used to pass an access token to be used as a bearer token for table requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=<JWT-token>".
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/table'
- $ref: '#/components/parameters/data-access'
- name: If-None-Match
in: header
description: An optional header that allows the server to return 304 (Not Modified) if the metadata is current. The content is the value of the ETag received in a CreateTableResponse or LoadTableResponse.
required: false
schema:
type: string
- in: query
name: snapshots
description: |-
The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags.
Default if no param is provided is `all`.
required: false
schema:
type: string
enum:
- all
- refs
responses:
'200':
$ref: '#/components/responses/LoadTableResponse'
'304':
description: Not Modified - Based on the content of the 'If-None-Match' header the table metadata has not changed since.
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Catalog API
summary: Commit updates to a table
operationId: updateTable
description: |-
Commit updates to a table.
Commits have two parts, requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, `assert-ref-snapshot-id` will check that a named ref's snapshot ID has a certain value. Server implementations are required to fail with a 400 status code if any unknown updates or requirements are received.
Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.
Create table transactions that are started by createTable with `stage-create` set to true are committed using this route. Transactions should include all changes to the table, including table initialization, like AddSchemaUpdate and SetCurrentSchemaUpdate. The `assert-create` requirement is used to ensure that the table was not created concurrently.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CommitTableRequest'
responses:
'200':
$ref: '#/components/responses/CommitTableResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToUpdateDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'409':
description: Conflict - CommitFailedException, one or more requirements failed. The client may retry.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'500':
description: An unknown server-side problem occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Internal Server Error
type: CommitStateUnknownException
code: 500
'502':
description: A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Invalid response from the upstream server
type: CommitStateUnknownException
code: 502
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
'504':
description: A server-side gateway timeout occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Gateway timed out during commit
type: CommitStateUnknownException
code: 504
5XX:
description: A server-side problem that might not be addressable on the client.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Bad Gateway
type: InternalServerError
code: 502
delete:
tags:
- Catalog API
summary: Drop a table from the catalog
operationId: dropTable
description: Remove a table from the catalog
parameters:
- name: purgeRequested
in: query
required: false
description: Whether the user requested to purge the underlying table's data and metadata
schema:
type: boolean
default: false
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, Table to drop does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToDeleteDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
head:
tags:
- Catalog API
summary: Check if a table exists
operationId: tableExists
description: Check if a table exists within a given namespace. The response does not contain a body.
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, Table not found
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/table'
get:
tags:
- Catalog API
summary: Load vended credentials for a table from the catalog
operationId: loadCredentials
description: Load vended credentials for a table from the catalog.
responses:
'200':
$ref: '#/components/responses/LoadCredentialsResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load credentials for does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/tables/rename:
parameters:
- $ref: '#/components/parameters/prefix'
post:
tags:
- Catalog API
summary: Rename a table from its current name to a new name
description: Rename a table from one identifier to another. It's valid to move a table across namespaces, but the server implementation is not required to support it.
operationId: renameTable
requestBody:
description: Current table identifier to rename and new table identifier to rename to
content:
application/json:
schema:
$ref: '#/components/schemas/RenameTableRequest'
examples:
RenameTableSameNamespace:
$ref: '#/components/examples/RenameTableSameNamespace'
required: true
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, Table to rename does not exist - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToRenameDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
NamespaceToRenameToDoesNotExist:
$ref: '#/components/examples/NoSuchNamespaceError'
'406':
$ref: '#/components/responses/UnsupportedOperationResponse'
'409':
description: Conflict - The target identifier to rename to already exists as a table or view
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
summary: The requested table identifier already exists
value:
error:
message: The given table already exists
type: AlreadyExistsException
code: 409
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/table'
post:
tags:
- Catalog API
summary: Send a metrics report to this endpoint to be processed by the backend
operationId: reportMetrics
requestBody:
description: The request containing the metrics report to be sent
content:
application/json:
schema:
$ref: '#/components/schemas/ReportMetricsRequest'
required: true
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/transactions/commit:
parameters:
- $ref: '#/components/parameters/prefix'
post:
tags:
- Catalog API
summary: Commit updates to multiple tables in an atomic operation
operationId: commitTransaction
requestBody:
description: |-
Commit updates to multiple tables in an atomic operation
A commit for a single table consists of a table identifier with requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, `assert-ref-snapshot-id` will check that a named ref's snapshot ID has a certain value. Server implementations are required to fail with a 400 status code if any unknown updates or requirements are received.
Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.
content:
application/json:
schema:
$ref: '#/components/schemas/CommitTransactionRequest'
required: true
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToUpdateDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'409':
description: Conflict - CommitFailedException, one or more requirements failed. The client may retry.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'500':
description: An unknown server-side problem occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Internal Server Error
type: CommitStateUnknownException
code: 500
'502':
description: A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Invalid response from the upstream server
type: CommitStateUnknownException
code: 502
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
'504':
description: A server-side gateway timeout occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Gateway timed out during commit
type: CommitStateUnknownException
code: 504
5XX:
description: A server-side problem that might not be addressable on the client.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Bad Gateway
type: InternalServerError
code: 502
/v1/{prefix}/namespaces/{namespace}/views:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
get:
tags:
- Catalog API
summary: List all view identifiers underneath a given namespace
description: Return all view identifiers under this namespace
operationId: listViews
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
responses:
'200':
$ref: '#/components/responses/ListTablesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Catalog API
summary: Create a view in the given namespace
description: Create a view in the given namespace.
operationId: createView
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateViewRequest'
responses:
'200':
$ref: '#/components/responses/LoadViewResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'409':
description: Conflict - The view already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
NamespaceAlreadyExists:
$ref: '#/components/examples/ViewAlreadyExistsError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/views/{view}:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/view'
get:
tags:
- Catalog API
summary: Load a view from the catalog
operationId: loadView
description: |-
Load a view from the catalog.
The response contains both configuration and view metadata. The configuration, if non-empty is used as additional configuration for the view that overrides catalog configuration.
The response also contains the view's full metadata, matching the view metadata JSON file.
The catalog configuration may contain credentials that should be used for subsequent requests for the view. The configuration key "token" is used to pass an access token to be used as a bearer token for view requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=<JWT-token>".
responses:
'200':
$ref: '#/components/responses/LoadViewResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchViewException, view to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
ViewToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchViewError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Catalog API
summary: Replace a view
operationId: replaceView
description: Commit updates to a view.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CommitViewRequest'
responses:
'200':
$ref: '#/components/responses/LoadViewResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchViewException, view to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
ViewToUpdateDoesNotExist:
$ref: '#/components/examples/NoSuchViewError'
'409':
description: Conflict - CommitFailedException. The client may retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'500':
description: An unknown server-side problem occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
error:
message: Internal Server Error
type: CommitStateUnknownException
code: 500
'502':
description: A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
error:
message: Invalid response from the upstream server
type: CommitStateUnknownException
code: 502
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
'504':
description: A server-side gateway timeout occurred; the commit state is unknown.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
error:
message: Gateway timed out during commit
type: CommitStateUnknownException
code: 504
5XX:
description: A server-side problem that might not be addressable on the client.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
error:
message: Bad Gateway
type: InternalServerError
code: 502
delete:
tags:
- Catalog API
summary: Drop a view from the catalog
operationId: dropView
description: Remove a view from the catalog
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchViewException, view to drop does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
ViewToDeleteDoesNotExist:
$ref: '#/components/examples/NoSuchViewError'
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
head:
tags:
- Catalog API
summary: Check if a view exists
operationId: viewExists
description: Check if a view exists within a given namespace. This request does not return a response body.
responses:
'204':
description: Success, no content
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/views/rename:
parameters:
- $ref: '#/components/parameters/prefix'
post:
tags:
- Catalog API
summary: Rename a view from its current name to a new name
description: Rename a view from one identifier to another. It's valid to move a view across namespaces, but the server implementation is not required to support it.
operationId: renameView
requestBody:
description: Current view identifier to rename and new view identifier to rename to
content:
application/json:
schema:
$ref: '#/components/schemas/RenameTableRequest'
examples:
RenameViewSameNamespace:
$ref: '#/components/examples/RenameViewSameNamespace'
required: true
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchViewException, view to rename does not exist - NoSuchNamespaceException, The target namespace of the new identifier does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
examples:
ViewToRenameDoesNotExist:
$ref: '#/components/examples/NoSuchViewError'
NamespaceToRenameToDoesNotExist:
$ref: '#/components/examples/NoSuchNamespaceError'
'406':
$ref: '#/components/responses/UnsupportedOperationResponse'
'409':
description: Conflict - The target identifier to rename to already exists as a table or view
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
summary: The requested view identifier already exists
value:
error:
message: The given view already exists
type: AlreadyExistsException
code: 409
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/v1/{prefix}/namespaces/{namespace}/tables/{table}/notifications:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/table'
post:
tags:
- Catalog API
summary: Sends a notification to the table
operationId: sendNotification
requestBody:
description: |-
The request containing the notification to be sent.
For each table, Polaris will reject any notification where the timestamp in the request body is older than or equal to the most recent time Polaris has already processed for the table. The responsibility of ensuring the correct order of timestamps for a sequence of notifications lies with the caller of the API. This includes managing potential clock skew or inconsistencies when notifications are sent from multiple sources.
A VALIDATE request behaves like a dry-run of a CREATE or UPDATE request up to but not including loading the contents of a metadata file; this includes validations of permissions, the specified metadata path being within ALLOWED_LOCATIONS, having an EXTERNAL catalog, etc. The intended use case for a VALIDATE notification is to allow a remote catalog to pre-validate the general settings of a receiving catalog against an intended new table location before possibly creating a table intended for sending notifications in the remote catalog at all. For a VALIDATE request, the specified metadata-location can either be a prospective full metadata file path, or a relevant parent directory of the intended table to validate against ALLOWED_LOCATIONS.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationRequest'
required: true
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'409':
description: Conflict - The timestamp of the received notification is older than or equal to the most recent timestamp Polaris has already processed for the specified table.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
summary: The timestamp of the received notification is older than or equal to the most recent timestamp Polaris has already processed for the specified table.
value:
error:
message: A notification with a newer timestamp has been admitted for table
type: AlreadyExistsException
code: 409
'419':
$ref: '#/components/responses/AuthenticationTimeoutResponse'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/namespaces/{namespace}/generic-tables:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
get:
tags:
- Generic Table API
summary: List all generic tables identifiers underneath a given namespace
description: Return all generic table identifiers under this namespace
operationId: listGenericTables
parameters:
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
responses:
'200':
$ref: '#/components/responses/ListGenericTablesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Generic Table API
summary: Create a generic table under the given namespace
description: Create a generic table under the given namespace, and return the created table information as a response.
operationId: createGenericTable
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGenericTableRequest'
responses:
'200':
$ref: '#/components/responses/CreateGenericTableResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'409':
description: Conflict - The table already exists under the given namespace
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableAlreadyExists:
$ref: '#/components/examples/TableAlreadyExistsError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/{generic-table}:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/generic-table'
get:
tags:
- Generic Table API
summary: Load a generic table under the given namespace from the catalog
operationId: loadGenericTable
description: |-
Load a generic table from the catalog under the given namespace.
The response contains all table information passed during create.
responses:
'200':
$ref: '#/components/responses/LoadGenericTableResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableError, generic table to load does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
delete:
tags:
- Generic Table API
summary: Drop a generic table under the given namespace from the catalog
operationId: dropGenericTable
description: Remove a table under the given namespace from the catalog
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableError, Generic table to drop does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TableToDeleteDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/namespaces/{namespace}/policies:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
post:
tags:
- Policy API
summary: Create a policy in the given namespace
operationId: createPolicy
description: |
Creates a policy within the specified namespace.
A policy defines a set of rules governing actions on specified resources under predefined conditions.
In Apache Polaris, policies are created, stored, and later referenced by external engines to enforce access controls on associated resources.
User provides the following inputs when creating a policy
- `name` (REQUIRED): The name of the policy.
- `type` (REQUIRED): The type of the policy.
- **Predefined Policies:** policies have a `system.*` prefix in their type, such as `system.data_compaction`
- `description` (OPTIONAL): Provides details about the policy's purpose and functionality
- `content` (OPTIONAL): Defines the rules that control actions and access conditions on resources. The format can be JSON, SQL, or any other format.
The content field in the request body is validated using the policy's corresponding validator. The policy is created only if the content passes validation.
Upon successful creation, the new policy's version will be 0.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePolicyRequest'
responses:
'200':
$ref: '#/components/responses/CreatePolicyResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'409':
description: Conflict - The policy already exists under the given namespace
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyAlreadyExists:
$ref: '#/components/examples/PolicyAlreadyExistsError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
get:
tags:
- Policy API
summary: List all policy identifiers underneath a given namespace
description: Return all policy identifiers under this namespace. Users can optionally filter the result by policy type
operationId: listPolicies
parameters:
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
- $ref: '#/components/parameters/policy-type'
responses:
'200':
$ref: '#/components/responses/ListPoliciesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - The namespace specified does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
NamespaceNotFound:
$ref: '#/components/examples/NoSuchNamespaceError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/namespaces/{namespace}/policies/{policy-name}:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/policy-name'
get:
tags:
- Policy API
summary: Load a policy
operationId: loadPolicy
description: |
Load a policy from the catalog
The response contains the policy's metadata and content. For more details, refer to the definition of the `Policy` model.
responses:
'200':
$ref: '#/components/responses/LoadPolicyResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchPolicyException, policy to get does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyToGetDoesNotExist:
$ref: '#/components/examples/NoSuchPolicyError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
put:
tags:
- Policy API
summary: Update a policy
operationId: updatePolicy
description: |
Update a policy
A policy's description and content can be updated. The new content is validated against the policy's corresponding validator.
Upon a successful update, the policy's version is incremented by 1.
The update will only succeed if the current version matches the one in the catalog.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePolicyRequest'
responses:
'200':
$ref: '#/components/responses/UpdatePolicyResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchPolicyException, policy to get does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyToUpdateDoesNotExist:
$ref: '#/components/examples/NoSuchPolicyError'
'409':
description: The policy version doesn't match the current-policy-version; retry after fetching latest version
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyVersionMismatch:
$ref: '#/components/examples/PolicyVersionMismatchError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
delete:
tags:
- Policy API
summary: Drop a policy from the catalog
operationId: dropPolicy
description: |
Remove a policy from the catalog.
A policy can only be dropped if it is not attached to any resource entity. To remove the policy along with all its attachments, set detach-all to true.
parameters:
- name: detach-all
in: query
required: false
description: |
When set to true, the dropPolicy operation will also delete all mappings between the policy and its attached target entities.
schema:
type: boolean
example: false
responses:
'204':
description: Success, no content
'400':
description: Bad Request - the policy to be dropped is attached to one or more targets and detach-all is not set to true
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyInUse:
$ref: '#/components/examples/PolicyInUseError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchPolicyException, policy to get does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyToDeleteDoesNotExist:
$ref: '#/components/examples/NoSuchPolicyError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/namespaces/{namespace}/policies/{policy-name}/mappings:
parameters:
- $ref: '#/components/parameters/prefix'
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/policy-name'
put:
tags:
- Policy API
summary: Create a mapping between a policy and a resource entity
operationId: attachPolicy
description: |
Create a mapping between a policy and a resource entity
Policy can be attached to different levels:
1. **Table-like level:** Policies specific to individual tables or views.
2. **Namespace level:** Policies applies to a namespace.
3. **Catalog level:** Policies that applies to a catalog
The ability to attach a policy to a specific entity type is governed by the PolicyValidator. A policy can only be attached if the resource entity is a valid target for the specified policy type.
In addition to the validation rules enforced by the PolicyValidator, there are additional constraints on policy attachment:
1. For inheritable policies, only one policy of the same type can be attached to a given resource entity.
2. For non-inheritable policies, multiple policies of the same type can be attached to the same resource entity without restriction.
For inheritable policies, the inheritance override rule is:
1. Table-like level policies override namespace and catalog policies.
2. Namespace-level policies override upper level namespace or catalog policies.
Additional parameters can be provided in `parameters` when creating a mapping to define specific behavior or constraints.
If the policy is already attached to the target entity, the existing mapping record will be updated with the new set of parameters, replacing the previous ones.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachPolicyRequest'
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchPolicyException, NoSuchTargetException
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyToSetDoesNotExist:
$ref: '#/components/examples/NoSuchPolicyError'
TargetToSetDoesNotExist:
$ref: '#/components/examples/NoSuchTargetError'
'409':
description: Conflict - The policy type is inheritable and there is already a policy of the same type attached to the target entity
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
AnotherPolicyOfSameInheritableAttached:
$ref: '#/components/examples/ConflictPolicyAttachmentError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
post:
tags:
- Policy API
summary: Remove a mapping between a policy and a target entity
operationId: detachPolicy
description: |
Remove a mapping between a policy and a target entity
A target entity can be a catalog, namespace, table or view.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DetachPolicyRequest'
responses:
'204':
description: Success, no content
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchPolicyException, NoSuchTargetException, NoSuchMappingException
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
PolicyToUnsetDoesNotExist:
$ref: '#/components/examples/NoSuchPolicyError'
TargetToUnsetDoesNotExist:
$ref: '#/components/examples/NoSuchTargetError'
MappingToUnsetDoesNotExist:
$ref: '#/components/examples/NoSuchMappingError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
/polaris/v1/{prefix}/applicable-policies:
parameters:
- $ref: '#/components/parameters/prefix'
get:
tags:
- Policy API
summary: Get Applicable policies for catalog, namespace, table, or views
operationId: getApplicablePolicies
description: |
Retrieves all applicable policies for a specified entity, including inherited policies from parent entities. An entity can be a table/view, namespace, or catalog. The required parameters depend on the entity type:
- Table/View:
- The `namespace` parameter is required to specify the entity's namespace.
- The `target-name` parameter is required to specify the entity name.
- Namespace:
- The `namespace` parameter is required to specify the identifier.
- The `target-name` parameter should not be set.
- Catalog:
- Neither `namespace` nor `target-name` should be set.
An optional policyType parameter filters results to return only policies of the specified type.
This API evaluates the entity's hierarchy and applies inheritable policies from parent entities. The inheritance follows the following override rule:
1. Table-like level policies override namespace and catalog policies.
2. Namespace-level policies override upper level namespace or catalog policies.
parameters:
- $ref: '#/components/parameters/page-token'
- $ref: '#/components/parameters/page-size'
- name: namespace
in: query
required: false
description: A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
schema:
type: string
examples:
singlepart_namespace:
value: accounting
multipart_namespace:
value: accounting%1Ftax
- name: target-name
in: query
required: false
description: Name of the target table/view
schema:
type: string
example: test_table
- $ref: '#/components/parameters/policy-type'
responses:
'200':
$ref: '#/components/responses/GetApplicablePoliciesResponse'
'400':
$ref: '#/components/responses/BadRequestErrorResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
examples:
TargetTableDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
TargetViewDoesNotExist:
$ref: '#/components/examples/NoSuchViewError'
TargetNamespaceDoesNotExist:
$ref: '#/components/examples/NoSuchNamespaceError'
'503':
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
components:
securitySchemes:
OAuth2:
type: oauth2
description: |-
This scheme is used for OAuth2 authorization.
For unauthorized requests, services should return an appropriate 401 or 403 response. Implementations must not return altered success (200) responses when a request is unauthenticated or unauthorized.
If a separate authorization server is used, substitute the tokenUrl with the full token path of the external authorization server, and use the resulting token to access the resources defined in the spec.
flows:
clientCredentials:
tokenUrl: /v1/oauth/tokens
scopes:
catalog: Allows interacting with the Config and Catalog APIs
BearerAuth:
type: http
scheme: bearer
schemas:
CatalogConfig:
type: object
description: Server-provided configuration for the catalog.
required:
- defaults
- overrides
properties:
overrides:
type: object
additionalProperties:
type: string
description: Properties that should be used to override client configuration; applied after defaults and client configuration.
defaults:
type: object
additionalProperties:
type: string
description: Properties that should be used as default configuration; applied before client configuration.
endpoints:
type: array
items:
type: string
description: A list of endpoints that the server supports. The format of each endpoint must be "<HTTP verb> <resource path from OpenAPI REST spec>". The HTTP verb and the resource path must be separated by a space character.
example:
- GET /v1/{prefix}/namespaces/{namespace}
- GET /v1/{prefix}/namespaces
- POST /v1/{prefix}/namespaces
- GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
- GET /v1/{prefix}/namespaces/{namespace}/views/{view}
ErrorModel:
type: object
description: JSON error payload returned in a response with further details on the error
required:
- message
- type
- code
properties:
message:
type: string
description: Human-readable error message
type:
type: string
description: Internal type definition of the error
example: NoSuchNamespaceException
code:
type: integer
minimum: 400
maximum: 600
description: HTTP response code
example: 404
stack:
type: array
items:
type: string
IcebergErrorResponse:
description: JSON wrapper for all error responses (non-2xx)
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorModel'
additionalProperties: false
example:
error:
message: The server does not support this operation
type: UnsupportedOperationException
code: 406
OAuthClientCredentialsRequest:
deprecated: true
description: |-
The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this spec, see description of the endpoint.
OAuth2 client credentials request
See https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
type: object
required:
- grant_type
- client_id
- client_secret
properties:
grant_type:
type: string
enum:
- client_credentials
scope:
type: string
client_id:
type: string
description: |-
Client ID
This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.
client_secret:
type: string
description: |-
Client secret
This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.
TokenType:
type: string
enum:
- urn:ietf:params:oauth:token-type:access_token
- urn:ietf:params:oauth:token-type:refresh_token
- urn:ietf:params:oauth:token-type:id_token
- urn:ietf:params:oauth:token-type:saml1
- urn:ietf:params:oauth:token-type:saml2
- urn:ietf:params:oauth:token-type:jwt
description: |-
Token type identifier, from RFC 8693 Section 3
See https://datatracker.ietf.org/doc/html/rfc8693#section-3
OAuthTokenExchangeRequest:
deprecated: true
description: |-
The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this spec, see description of the endpoint.
OAuth2 token exchange request
See https://datatracker.ietf.org/doc/html/rfc8693
type: object
required:
- grant_type
- subject_token
- subject_token_type
properties:
grant_type:
type: string
enum:
- urn:ietf:params:oauth:grant-type:token-exchange
scope:
type: string
requested_token_type:
$ref: '#/components/schemas/TokenType'
subject_token:
type: string
description: Subject token for token exchange request
subject_token_type:
$ref: '#/components/schemas/TokenType'
actor_token:
type: string
description: Actor token for token exchange request
actor_token_type:
$ref: '#/components/schemas/TokenType'
OAuthTokenRequest:
deprecated: true
description: The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this spec, see description of the endpoint.
anyOf:
- $ref: '#/components/schemas/OAuthClientCredentialsRequest'
- $ref: '#/components/schemas/OAuthTokenExchangeRequest'
OAuthTokenResponse:
deprecated: true
description: The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this spec, see description of the endpoint.
type: object
required:
- access_token
- token_type
properties:
access_token:
type: string
description: The access token, for client credentials or token exchange
token_type:
type: string
enum:
- bearer
- mac
- N_A
description: |-
Access token type for client credentials or token exchange
See https://datatracker.ietf.org/doc/html/rfc6749#section-7.1
expires_in:
type: integer
description: Lifetime of the access token in seconds for client credentials or token exchange
issued_token_type:
$ref: '#/components/schemas/TokenType'
refresh_token:
type: string
description: Refresh token for client credentials or token exchange
scope:
type: string
description: Authorization scope for client credentials or token exchange
OAuthError:
deprecated: true
description: The `oauth/tokens` endpoint and related schemas are **DEPRECATED for REMOVAL** from this spec, see description of the endpoint.
type: object
required:
- error
properties:
error:
type: string
enum:
- invalid_request
- invalid_client
- invalid_grant
- unauthorized_client
- unsupported_grant_type
- invalid_scope
error_description:
type: string
error_uri:
type: string
PageToken:
description: |-
An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server.
Servers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response.
Servers that support pagination must return all results in a single response with the value of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the request.
Servers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted from the response.
Clients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.
type: string
nullable: true
Namespace:
description: Reference to one or more levels of a namespace
type: array
items:
type: string
example:
- accounting
- tax
ListNamespacesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
namespaces:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/Namespace'
CreateNamespaceRequest:
type: object
required:
- namespace
properties:
namespace:
$ref: '#/components/schemas/Namespace'
properties:
type: object
description: Configured string to string map of properties for the namespace
example:
owner: Hank Bendickson
default: {}
additionalProperties:
type: string
CreateNamespaceResponse:
type: object
required:
- namespace
properties:
namespace:
$ref: '#/components/schemas/Namespace'
properties:
type: object
additionalProperties:
type: string
description: Properties stored on the namespace, if supported by the server.
example:
owner: Ralph
created_at: '1452120468'
default: {}
GetNamespaceResponse:
type: object
required:
- namespace
properties:
namespace:
$ref: '#/components/schemas/Namespace'
properties:
type: object
description: Properties stored on the namespace, if supported by the server. If the server does not support namespace properties, it should return null for this field. If namespace properties are supported, but none are set, it should return an empty object.
additionalProperties:
type: string
example:
owner: Ralph
transient_lastDdlTime: '1452120468'
default: {}
nullable: true
UpdateNamespacePropertiesRequest:
type: object
properties:
removals:
type: array
uniqueItems: true
items:
type: string
example:
- department
- access_group
updates:
type: object
example:
owner: Hank Bendickson
additionalProperties:
type: string
UpdateNamespacePropertiesResponse:
type: object
required:
- updated
- removed
properties:
updated:
description: List of property keys that were added or updated
type: array
uniqueItems: true
items:
type: string
removed:
description: List of properties that were removed
type: array
items:
type: string
missing:
type: array
items:
type: string
description: List of properties requested for removal that were not found in the namespace's properties. Represents a partial success response. Server's do not need to implement this.
nullable: true
TableIdentifier:
type: object
required:
- namespace
- name
properties:
namespace:
$ref: '#/components/schemas/Namespace'
name:
type: string
nullable: false
ListTablesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
identifiers:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/TableIdentifier'
PrimitiveType:
type: string
example:
- long
- string
- fixed[16]
- decimal(10,2)
StructType:
type: object
required:
- type
- fields
properties:
type:
type: string
const: struct
fields:
type: array
items:
$ref: '#/components/schemas/StructField'
Type:
oneOf:
- $ref: '#/components/schemas/PrimitiveType'
- $ref: '#/components/schemas/StructType'
- $ref: '#/components/schemas/ListType'
- $ref: '#/components/schemas/MapType'
ListType:
type: object
required:
- type
- element-id
- element
- element-required
properties:
type:
type: string
const: list
element-id:
type: integer
element:
$ref: '#/components/schemas/Type'
element-required:
type: boolean
MapType:
type: object
required:
- type
- key-id
- key
- value-id
- value
- value-required
properties:
type:
type: string
const: map
key-id:
type: integer
key:
$ref: '#/components/schemas/Type'
value-id:
type: integer
value:
$ref: '#/components/schemas/Type'
value-required:
type: boolean
BooleanTypeValue:
type: boolean
example: true
IntegerTypeValue:
type: integer
example: 42
LongTypeValue:
type: integer
format: int64
example: 9223372036854776000
FloatTypeValue:
type: number
format: float
example: 3.14
DoubleTypeValue:
type: number
format: double
example: 123.456
DecimalTypeValue:
type: string
description: Decimal type values are serialized as strings. Decimals with a positive scale serialize as numeric plain text, while decimals with a negative scale use scientific notation and the exponent will be equal to the negated scale. For instance, a decimal with a positive scale is '123.4500', with zero scale is '2', and with a negative scale is '2E+20'
example: '123.4500'
StringTypeValue:
type: string
example: hello
UUIDTypeValue:
type: string
format: uuid
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
maxLength: 36
minLength: 36
description: UUID type values are serialized as a 36-character lowercase string in standard UUID format as specified by RFC-4122
example: eb26bdb1-a1d8-4aa6-990e-da940875492c
DateTypeValue:
type: string
format: date
description: Date type values follow the 'YYYY-MM-DD' ISO-8601 standard date format
example: '2007-12-03'
TimeTypeValue:
type: string
description: Time type values follow the 'HH:MM:SS.ssssss' ISO-8601 format with microsecond precision
example: '22:31:08.123456'
TimestampTypeValue:
type: string
description: Timestamp type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss' ISO-8601 format with microsecond precision
example: '2007-12-03T10:15:30.123456'
TimestampTzTypeValue:
type: string
description: TimestampTz type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss+00:00' ISO-8601 format with microsecond precision, and a timezone offset (+00:00 for UTC)
example: '2007-12-03T10:15:30.123456+00:00'
TimestampNanoTypeValue:
type: string
description: Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss' ISO-8601 format with nanosecond precision
example: '2007-12-03T10:15:30.123456789'
TimestampTzNanoTypeValue:
type: string
description: Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss+00:00' ISO-8601 format with nanosecond precision, and a timezone offset (+00:00 for UTC)
example: '2007-12-03T10:15:30.123456789+00:00'
FixedTypeValue:
type: string
description: Fixed length type values are stored and serialized as an uppercase hexadecimal string preserving the fixed length
example: 78797A
BinaryTypeValue:
type: string
description: Binary type values are stored and serialized as an uppercase hexadecimal string
example: 78797A
PrimitiveTypeValue:
oneOf:
- $ref: '#/components/schemas/BooleanTypeValue'
- $ref: '#/components/schemas/IntegerTypeValue'
- $ref: '#/components/schemas/LongTypeValue'
- $ref: '#/components/schemas/FloatTypeValue'
- $ref: '#/components/schemas/DoubleTypeValue'
- $ref: '#/components/schemas/DecimalTypeValue'
- $ref: '#/components/schemas/StringTypeValue'
- $ref: '#/components/schemas/UUIDTypeValue'
- $ref: '#/components/schemas/DateTypeValue'
- $ref: '#/components/schemas/TimeTypeValue'
- $ref: '#/components/schemas/TimestampTypeValue'
- $ref: '#/components/schemas/TimestampTzTypeValue'
- $ref: '#/components/schemas/TimestampNanoTypeValue'
- $ref: '#/components/schemas/TimestampTzNanoTypeValue'
- $ref: '#/components/schemas/FixedTypeValue'
- $ref: '#/components/schemas/BinaryTypeValue'
StructField:
type: object
required:
- id
- name
- type
- required
properties:
id:
type: integer
name:
type: string
type:
$ref: '#/components/schemas/Type'
required:
type: boolean
doc:
type: string
initial-default:
$ref: '#/components/schemas/PrimitiveTypeValue'
write-default:
$ref: '#/components/schemas/PrimitiveTypeValue'
Schema:
allOf:
- $ref: '#/components/schemas/StructType'
- type: object
properties:
schema-id:
type: integer
readOnly: true
identifier-field-ids:
type: array
items:
type: integer
Transform:
type: string
example:
- identity
- year
- month
- day
- hour
- bucket[256]
- truncate[16]
PartitionField:
type: object
required:
- source-id
- transform
- name
properties:
field-id:
type: integer
source-id:
type: integer
name:
type: string
transform:
$ref: '#/components/schemas/Transform'
PartitionSpec:
type: object
required:
- fields
properties:
spec-id:
type: integer
readOnly: true
fields:
type: array
items:
$ref: '#/components/schemas/PartitionField'
SortDirection:
type: string
enum:
- asc
- desc
NullOrder:
type: string
enum:
- nulls-first
- nulls-last
SortField:
type: object
required:
- source-id
- transform
- direction
- null-order
properties:
source-id:
type: integer
transform:
$ref: '#/components/schemas/Transform'
direction:
$ref: '#/components/schemas/SortDirection'
null-order:
$ref: '#/components/schemas/NullOrder'
SortOrder:
type: object
required:
- order-id
- fields
properties:
order-id:
type: integer
readOnly: true
fields:
type: array
items:
$ref: '#/components/schemas/SortField'
CreateTableRequest:
type: object
required:
- name
- schema
properties:
name:
type: string
location:
type: string
schema:
$ref: '#/components/schemas/Schema'
partition-spec:
$ref: '#/components/schemas/PartitionSpec'
write-order:
$ref: '#/components/schemas/SortOrder'
stage-create:
type: boolean
properties:
type: object
additionalProperties:
type: string
Snapshot:
type: object
required:
- snapshot-id
- timestamp-ms
- manifest-list
- summary
properties:
snapshot-id:
type: integer
format: int64
parent-snapshot-id:
type: integer
format: int64
sequence-number:
type: integer
format: int64
timestamp-ms:
type: integer
format: int64
manifest-list:
type: string
description: Location of the snapshot's manifest list file
summary:
type: object
required:
- operation
properties:
operation:
type: string
enum:
- append
- replace
- overwrite
- delete
additionalProperties:
type: string
schema-id:
type: integer
SnapshotReference:
type: object
required:
- type
- snapshot-id
properties:
type:
type: string
enum:
- tag
- branch
snapshot-id:
type: integer
format: int64
max-ref-age-ms:
type: integer
format: int64
max-snapshot-age-ms:
type: integer
format: int64
min-snapshots-to-keep:
type: integer
SnapshotReferences:
type: object
additionalProperties:
$ref: '#/components/schemas/SnapshotReference'
SnapshotLog:
type: array
items:
type: object
required:
- snapshot-id
- timestamp-ms
properties:
snapshot-id:
type: integer
format: int64
timestamp-ms:
type: integer
format: int64
MetadataLog:
type: array
items:
type: object
required:
- metadata-file
- timestamp-ms
properties:
metadata-file:
type: string
timestamp-ms:
type: integer
format: int64
BlobMetadata:
type: object
required:
- type
- snapshot-id
- sequence-number
- fields
properties:
type:
type: string
snapshot-id:
type: integer
format: int64
sequence-number:
type: integer
format: int64
fields:
type: array
items:
type: integer
properties:
type: object
additionalProperties:
type: string
StatisticsFile:
type: object
required:
- snapshot-id
- statistics-path
- file-size-in-bytes
- file-footer-size-in-bytes
- blob-metadata
properties:
snapshot-id:
type: integer
format: int64
statistics-path:
type: string
file-size-in-bytes:
type: integer
format: int64
file-footer-size-in-bytes:
type: integer
format: int64
blob-metadata:
type: array
items:
$ref: '#/components/schemas/BlobMetadata'
PartitionStatisticsFile:
type: object
required:
- snapshot-id
- statistics-path
- file-size-in-bytes
properties:
snapshot-id:
type: integer
format: int64
statistics-path:
type: string
file-size-in-bytes:
type: integer
format: int64
TableMetadata:
type: object
required:
- format-version
- table-uuid
properties:
format-version:
type: integer
minimum: 1
maximum: 2
table-uuid:
type: string
location:
type: string
last-updated-ms:
type: integer
format: int64
properties:
type: object
additionalProperties:
type: string
schemas:
type: array
items:
$ref: '#/components/schemas/Schema'
current-schema-id:
type: integer
last-column-id:
type: integer
partition-specs:
type: array
items:
$ref: '#/components/schemas/PartitionSpec'
default-spec-id:
type: integer
last-partition-id:
type: integer
sort-orders:
type: array
items:
$ref: '#/components/schemas/SortOrder'
default-sort-order-id:
type: integer
snapshots:
type: array
items:
$ref: '#/components/schemas/Snapshot'
refs:
$ref: '#/components/schemas/SnapshotReferences'
current-snapshot-id:
type: integer
format: int64
last-sequence-number:
type: integer
format: int64
snapshot-log:
$ref: '#/components/schemas/SnapshotLog'
metadata-log:
$ref: '#/components/schemas/MetadataLog'
statistics:
type: array
items:
$ref: '#/components/schemas/StatisticsFile'
partition-statistics:
type: array
items:
$ref: '#/components/schemas/PartitionStatisticsFile'
StorageCredential:
type: object
required:
- prefix
- config
properties:
prefix:
type: string
description: Indicates a storage location prefix where the credential is relevant. Clients should choose the most specific prefix (by selecting the longest prefix) if several credentials of the same type are available.
config:
type: object
additionalProperties:
type: string
LoadTableResult:
description: |
Result used when a table is successfully loaded.
The table metadata JSON is returned in the `metadata` field. The corresponding file location of table metadata should be returned in the `metadata-location` field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed.
Clients can check whether metadata has changed by comparing metadata locations after the table has been created.
The `config` map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage.
The following configurations should be respected by clients:
## General Configurations
- `token`: Authorization bearer token to use for table requests if OAuth2 security is enabled
## AWS Configurations
The following configurations should be respected when working with tables stored in AWS S3
- `client.region`: region to configure client for making requests to AWS
- `s3.access-key-id`: id for credentials that provide access to the data in S3
- `s3.secret-access-key`: secret for credentials that provide access to data in S3
- `s3.session-token`: if present, this value should be used for as the session token
- `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification
- `s3.cross-region-access-enabled`: if `true`, S3 Cross-Region bucket access is enabled
## Storage Credentials
Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.
Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
type: object
required:
- metadata
properties:
metadata-location:
type: string
description: May be null if the table is staged as part of a transaction
metadata:
$ref: '#/components/schemas/TableMetadata'
config:
type: object
additionalProperties:
type: string
storage-credentials:
type: array
items:
$ref: '#/components/schemas/StorageCredential'
RegisterTableRequest:
type: object
required:
- name
- metadata-location
properties:
name:
type: string
metadata-location:
type: string
TableRequirement:
type: object
discriminator:
propertyName: type
mapping:
assert-create: '#/components/schemas/AssertCreate'
assert-table-uuid: '#/components/schemas/AssertTableUUID'
assert-ref-snapshot-id: '#/components/schemas/AssertRefSnapshotId'
assert-last-assigned-field-id: '#/components/schemas/AssertLastAssignedFieldId'
assert-current-schema-id: '#/components/schemas/AssertCurrentSchemaId'
assert-last-assigned-partition-id: '#/components/schemas/AssertLastAssignedPartitionId'
assert-default-spec-id: '#/components/schemas/AssertDefaultSpecId'
assert-default-sort-order-id: '#/components/schemas/AssertDefaultSortOrderId'
properties:
type:
type: string
required:
- type
AssertCreate:
type: object
description: The table must not already exist; used for create transactions
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- type
properties:
type:
type: string
const: assert-create
AssertTableUUID:
description: The table UUID must match the requirement's `uuid`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- type
- uuid
properties:
type:
type: string
const: assert-table-uuid
uuid:
type: string
AssertRefSnapshotId:
description: The table branch or tag identified by the requirement's `ref` must reference the requirement's `snapshot-id`; if `snapshot-id` is `null` or missing, the ref must not already exist
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- ref
- snapshot-id
properties:
type:
type: string
const: assert-ref-snapshot-id
ref:
type: string
snapshot-id:
type: integer
format: int64
AssertLastAssignedFieldId:
description: The table's last assigned column id must match the requirement's `last-assigned-field-id`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- last-assigned-field-id
properties:
type:
type: string
const: assert-last-assigned-field-id
last-assigned-field-id:
type: integer
AssertCurrentSchemaId:
description: The table's current schema id must match the requirement's `current-schema-id`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- current-schema-id
properties:
type:
type: string
const: assert-current-schema-id
current-schema-id:
type: integer
AssertLastAssignedPartitionId:
description: The table's last assigned partition id must match the requirement's `last-assigned-partition-id`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- last-assigned-partition-id
properties:
type:
type: string
const: assert-last-assigned-partition-id
last-assigned-partition-id:
type: integer
AssertDefaultSpecId:
description: The table's default spec id must match the requirement's `default-spec-id`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- default-spec-id
properties:
type:
type: string
const: assert-default-spec-id
default-spec-id:
type: integer
AssertDefaultSortOrderId:
description: The table's default sort order id must match the requirement's `default-sort-order-id`
allOf:
- $ref: '#/components/schemas/TableRequirement'
required:
- default-sort-order-id
properties:
type:
type: string
const: assert-default-sort-order-id
default-sort-order-id:
type: integer
AssignUUIDUpdate:
description: Assigning a UUID to a table/view should only be done when creating the table/view. It is not safe to re-assign the UUID if a table/view already has a UUID assigned
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- uuid
properties:
action:
type: string
const: assign-uuid
uuid:
type: string
BaseUpdate:
discriminator:
propertyName: action
mapping:
assign-uuid: '#/components/schemas/AssignUUIDUpdate'
upgrade-format-version: '#/components/schemas/UpgradeFormatVersionUpdate'
add-schema: '#/components/schemas/AddSchemaUpdate'
set-current-schema: '#/components/schemas/SetCurrentSchemaUpdate'
add-spec: '#/components/schemas/AddPartitionSpecUpdate'
set-default-spec: '#/components/schemas/SetDefaultSpecUpdate'
add-sort-order: '#/components/schemas/AddSortOrderUpdate'
set-default-sort-order: '#/components/schemas/SetDefaultSortOrderUpdate'
add-snapshot: '#/components/schemas/AddSnapshotUpdate'
set-snapshot-ref: '#/components/schemas/SetSnapshotRefUpdate'
remove-snapshots: '#/components/schemas/RemoveSnapshotsUpdate'
remove-snapshot-ref: '#/components/schemas/RemoveSnapshotRefUpdate'
set-location: '#/components/schemas/SetLocationUpdate'
set-properties: '#/components/schemas/SetPropertiesUpdate'
remove-properties: '#/components/schemas/RemovePropertiesUpdate'
add-view-version: '#/components/schemas/AddViewVersionUpdate'
set-current-view-version: '#/components/schemas/SetCurrentViewVersionUpdate'
set-statistics: '#/components/schemas/SetStatisticsUpdate'
remove-statistics: '#/components/schemas/RemoveStatisticsUpdate'
set-partition-statistics: '#/components/schemas/SetPartitionStatisticsUpdate'
remove-partition-statistics: '#/components/schemas/RemovePartitionStatisticsUpdate'
remove-partition-specs: '#/components/schemas/RemovePartitionSpecsUpdate'
enable-row-lineage: '#/components/schemas/EnableRowLineageUpdate'
type: object
required:
- action
properties:
action:
type: string
UpgradeFormatVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- format-version
properties:
action:
type: string
const: upgrade-format-version
format-version:
type: integer
AddSchemaUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- schema
properties:
action:
type: string
const: add-schema
schema:
$ref: '#/components/schemas/Schema'
last-column-id:
type: integer
deprecated: true
description: |-
This optional field is **DEPRECATED for REMOVAL** since it more safe to handle this internally, and shouldn't be exposed to the clients.
The highest assigned column ID for the table. This is used to ensure columns are always assigned an unused ID when evolving schemas. When omitted, it will be computed on the server side.
SetCurrentSchemaUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- schema-id
properties:
action:
type: string
const: set-current-schema
schema-id:
type: integer
description: Schema ID to set as current, or -1 to set last added schema
AddPartitionSpecUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- spec
properties:
action:
type: string
const: add-spec
spec:
$ref: '#/components/schemas/PartitionSpec'
SetDefaultSpecUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- spec-id
properties:
action:
type: string
const: set-default-spec
spec-id:
type: integer
description: Partition spec ID to set as the default, or -1 to set last added spec
AddSortOrderUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- sort-order
properties:
action:
type: string
const: add-sort-order
sort-order:
$ref: '#/components/schemas/SortOrder'
SetDefaultSortOrderUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- sort-order-id
properties:
action:
type: string
const: set-default-sort-order
sort-order-id:
type: integer
description: Sort order ID to set as the default, or -1 to set last added sort order
AddSnapshotUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- snapshot
properties:
action:
type: string
const: add-snapshot
snapshot:
$ref: '#/components/schemas/Snapshot'
SetSnapshotRefUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
- $ref: '#/components/schemas/SnapshotReference'
required:
- ref-name
properties:
action:
type: string
const: set-snapshot-ref
ref-name:
type: string
RemoveSnapshotsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- snapshot-ids
properties:
action:
type: string
const: remove-snapshots
snapshot-ids:
type: array
items:
type: integer
format: int64
RemoveSnapshotRefUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- ref-name
properties:
action:
type: string
const: remove-snapshot-ref
ref-name:
type: string
SetLocationUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- location
properties:
action:
type: string
const: set-location
location:
type: string
SetPropertiesUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- updates
properties:
action:
type: string
const: set-properties
updates:
type: object
additionalProperties:
type: string
RemovePropertiesUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- removals
properties:
action:
type: string
const: remove-properties
removals:
type: array
items:
type: string
SQLViewRepresentation:
type: object
required:
- type
- sql
- dialect
properties:
type:
type: string
sql:
type: string
dialect:
type: string
ViewRepresentation:
oneOf:
- $ref: '#/components/schemas/SQLViewRepresentation'
ViewVersion:
type: object
required:
- version-id
- timestamp-ms
- schema-id
- summary
- representations
- default-namespace
properties:
version-id:
type: integer
timestamp-ms:
type: integer
format: int64
schema-id:
type: integer
description: Schema ID to set as current, or -1 to set last added schema
summary:
type: object
additionalProperties:
type: string
representations:
type: array
items:
$ref: '#/components/schemas/ViewRepresentation'
default-catalog:
type: string
default-namespace:
$ref: '#/components/schemas/Namespace'
AddViewVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- view-version
properties:
action:
type: string
const: add-view-version
view-version:
$ref: '#/components/schemas/ViewVersion'
SetCurrentViewVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- view-version-id
properties:
action:
type: string
const: set-current-view-version
view-version-id:
type: integer
description: The view version id to set as current, or -1 to set last added view version id
SetStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- statistics
properties:
action:
type: string
const: set-statistics
snapshot-id:
type: integer
format: int64
deprecated: true
description: This optional field is **DEPRECATED for REMOVAL** since it contains redundant information. Clients should use the `statistics.snapshot-id` field instead.
statistics:
$ref: '#/components/schemas/StatisticsFile'
RemoveStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- snapshot-id
properties:
action:
type: string
const: remove-statistics
snapshot-id:
type: integer
format: int64
SetPartitionStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- partition-statistics
properties:
action:
type: string
const: set-partition-statistics
partition-statistics:
$ref: '#/components/schemas/PartitionStatisticsFile'
RemovePartitionStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- snapshot-id
properties:
action:
type: string
const: remove-partition-statistics
snapshot-id:
type: integer
format: int64
RemovePartitionSpecsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- spec-ids
properties:
action:
type: string
const: remove-partition-specs
spec-ids:
type: array
items:
type: integer
EnableRowLineageUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
properties:
action:
type: string
const: enable-row-lineage
TableUpdate:
anyOf:
- $ref: '#/components/schemas/AssignUUIDUpdate'
- $ref: '#/components/schemas/UpgradeFormatVersionUpdate'
- $ref: '#/components/schemas/AddSchemaUpdate'
- $ref: '#/components/schemas/SetCurrentSchemaUpdate'
- $ref: '#/components/schemas/AddPartitionSpecUpdate'
- $ref: '#/components/schemas/SetDefaultSpecUpdate'
- $ref: '#/components/schemas/AddSortOrderUpdate'
- $ref: '#/components/schemas/SetDefaultSortOrderUpdate'
- $ref: '#/components/schemas/AddSnapshotUpdate'
- $ref: '#/components/schemas/SetSnapshotRefUpdate'
- $ref: '#/components/schemas/RemoveSnapshotsUpdate'
- $ref: '#/components/schemas/RemoveSnapshotRefUpdate'
- $ref: '#/components/schemas/SetLocationUpdate'
- $ref: '#/components/schemas/SetPropertiesUpdate'
- $ref: '#/components/schemas/RemovePropertiesUpdate'
- $ref: '#/components/schemas/SetStatisticsUpdate'
- $ref: '#/components/schemas/RemoveStatisticsUpdate'
- $ref: '#/components/schemas/RemovePartitionSpecsUpdate'
- $ref: '#/components/schemas/EnableRowLineageUpdate'
CommitTableRequest:
type: object
required:
- requirements
- updates
properties:
identifier:
description: Table identifier to update; must be present for CommitTransactionRequest
$ref: '#/components/schemas/TableIdentifier'
requirements:
type: array
items:
$ref: '#/components/schemas/TableRequirement'
updates:
type: array
items:
$ref: '#/components/schemas/TableUpdate'
CommitTableResponse:
type: object
required:
- metadata-location
- metadata
properties:
metadata-location:
type: string
metadata:
$ref: '#/components/schemas/TableMetadata'
LoadCredentialsResponse:
type: object
required:
- storage-credentials
properties:
storage-credentials:
type: array
items:
$ref: '#/components/schemas/StorageCredential'
RenameTableRequest:
type: object
required:
- source
- destination
properties:
source:
$ref: '#/components/schemas/TableIdentifier'
destination:
$ref: '#/components/schemas/TableIdentifier'
ExpressionType:
type: string
example:
- 'true'
- 'false'
- eq
- and
- or
- not
- in
- not-in
- lt
- lt-eq
- gt
- gt-eq
- not-eq
- starts-with
- not-starts-with
- is-null
- not-null
- is-nan
- not-nan
TrueExpression:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/ExpressionType'
const: 'true'
FalseExpression:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/ExpressionType'
const: 'false'
Expression:
oneOf:
- $ref: '#/components/schemas/TrueExpression'
- $ref: '#/components/schemas/FalseExpression'
- $ref: '#/components/schemas/AndOrExpression'
- $ref: '#/components/schemas/NotExpression'
- $ref: '#/components/schemas/SetExpression'
- $ref: '#/components/schemas/LiteralExpression'
- $ref: '#/components/schemas/UnaryExpression'
AndOrExpression:
type: object
required:
- type
- left
- right
properties:
type:
$ref: '#/components/schemas/ExpressionType'
enum:
- and
- or
left:
$ref: '#/components/schemas/Expression'
right:
$ref: '#/components/schemas/Expression'
NotExpression:
type: object
required:
- type
- child
properties:
type:
$ref: '#/components/schemas/ExpressionType'
const: not
child:
$ref: '#/components/schemas/Expression'
Reference:
type: string
example:
- column-name
TransformTerm:
type: object
required:
- type
- transform
- term
properties:
type:
type: string
const: transform
transform:
$ref: '#/components/schemas/Transform'
term:
$ref: '#/components/schemas/Reference'
Term:
oneOf:
- $ref: '#/components/schemas/Reference'
- $ref: '#/components/schemas/TransformTerm'
SetExpression:
type: object
required:
- type
- term
- values
properties:
type:
$ref: '#/components/schemas/ExpressionType'
enum:
- in
- not-in
term:
$ref: '#/components/schemas/Term'
values:
type: array
items:
type: object
LiteralExpression:
type: object
required:
- type
- term
- value
properties:
type:
$ref: '#/components/schemas/ExpressionType'
enum:
- lt
- lt-eq
- gt
- gt-eq
- eq
- not-eq
- starts-with
- not-starts-with
term:
$ref: '#/components/schemas/Term'
value:
type: object
UnaryExpression:
type: object
required:
- type
- term
- value
properties:
type:
$ref: '#/components/schemas/ExpressionType'
enum:
- is-null
- not-null
- is-nan
- not-nan
term:
$ref: '#/components/schemas/Term'
value:
type: object
CounterResult:
type: object
required:
- unit
- value
properties:
unit:
type: string
value:
type: integer
format: int64
TimerResult:
type: object
required:
- time-unit
- count
- total-duration
properties:
time-unit:
type: string
count:
type: integer
format: int64
total-duration:
type: integer
format: int64
MetricResult:
anyOf:
- $ref: '#/components/schemas/CounterResult'
- $ref: '#/components/schemas/TimerResult'
Metrics:
type: object
additionalProperties:
$ref: '#/components/schemas/MetricResult'
example:
metrics:
total-planning-duration:
count: 1
time-unit: nanoseconds
total-duration: 2644235116
result-data-files:
unit: count
value: 1
result-delete-files:
unit: count
value: 0
total-data-manifests:
unit: count
value: 1
total-delete-manifests:
unit: count
value: 0
scanned-data-manifests:
unit: count
value: 1
skipped-data-manifests:
unit: count
value: 0
total-file-size-bytes:
unit: bytes
value: 10
total-delete-file-size-bytes:
unit: bytes
value: 0
ScanReport:
type: object
required:
- table-name
- snapshot-id
- filter
- schema-id
- projected-field-ids
- projected-field-names
- metrics
properties:
table-name:
type: string
snapshot-id:
type: integer
format: int64
filter:
$ref: '#/components/schemas/Expression'
schema-id:
type: integer
projected-field-ids:
type: array
items:
type: integer
projected-field-names:
type: array
items:
type: string
metrics:
$ref: '#/components/schemas/Metrics'
metadata:
type: object
additionalProperties:
type: string
CommitReport:
type: object
required:
- table-name
- snapshot-id
- sequence-number
- operation
- metrics
properties:
table-name:
type: string
snapshot-id:
type: integer
format: int64
sequence-number:
type: integer
format: int64
operation:
type: string
metrics:
$ref: '#/components/schemas/Metrics'
metadata:
type: object
additionalProperties:
type: string
ReportMetricsRequest:
anyOf:
- $ref: '#/components/schemas/ScanReport'
- $ref: '#/components/schemas/CommitReport'
required:
- report-type
properties:
report-type:
type: string
CommitTransactionRequest:
type: object
required:
- table-changes
properties:
table-changes:
type: array
items:
description: Table commit request; must provide an `identifier`
$ref: '#/components/schemas/CommitTableRequest'
CreateViewRequest:
type: object
required:
- name
- schema
- view-version
- properties
properties:
name:
type: string
location:
type: string
schema:
$ref: '#/components/schemas/Schema'
view-version:
$ref: '#/components/schemas/ViewVersion'
description: The view version to create, will replace the schema-id sent within the view-version with the id assigned to the provided schema
properties:
type: object
additionalProperties:
type: string
ViewHistoryEntry:
type: object
required:
- version-id
- timestamp-ms
properties:
version-id:
type: integer
timestamp-ms:
type: integer
format: int64
ViewMetadata:
type: object
required:
- view-uuid
- format-version
- location
- current-version-id
- versions
- version-log
- schemas
properties:
view-uuid:
type: string
format-version:
type: integer
minimum: 1
maximum: 1
location:
type: string
current-version-id:
type: integer
versions:
type: array
items:
$ref: '#/components/schemas/ViewVersion'
version-log:
type: array
items:
$ref: '#/components/schemas/ViewHistoryEntry'
schemas:
type: array
items:
$ref: '#/components/schemas/Schema'
properties:
type: object
additionalProperties:
type: string
LoadViewResult:
description: |
Result used when a view is successfully loaded.
The view metadata JSON is returned in the `metadata` field. The corresponding file location of view metadata is returned in the `metadata-location` field.
Clients can check whether metadata has changed by comparing metadata locations after the view has been created.
The `config` map returns view-specific configuration for the view's resources.
The following configurations should be respected by clients:
## General Configurations
- `token`: Authorization bearer token to use for view requests if OAuth2 security is enabled
type: object
required:
- metadata-location
- metadata
properties:
metadata-location:
type: string
metadata:
$ref: '#/components/schemas/ViewMetadata'
config:
type: object
additionalProperties:
type: string
AssertViewUUID:
description: The view UUID must match the requirement's `uuid`
required:
- type
- uuid
properties:
type:
type: string
const: assert-view-uuid
uuid:
type: string
ViewRequirement:
type: object
discriminator:
propertyName: type
mapping:
assert-view-uuid: '#/components/schemas/AssertViewUUID'
oneOf:
- $ref: '#/components/schemas/AssertViewUUID'
ViewUpdate:
anyOf:
- $ref: '#/components/schemas/AssignUUIDUpdate'
- $ref: '#/components/schemas/UpgradeFormatVersionUpdate'
- $ref: '#/components/schemas/AddSchemaUpdate'
- $ref: '#/components/schemas/SetLocationUpdate'
- $ref: '#/components/schemas/SetPropertiesUpdate'
- $ref: '#/components/schemas/RemovePropertiesUpdate'
- $ref: '#/components/schemas/AddViewVersionUpdate'
- $ref: '#/components/schemas/SetCurrentViewVersionUpdate'
CommitViewRequest:
type: object
required:
- updates
properties:
identifier:
description: View identifier to update
$ref: '#/components/schemas/TableIdentifier'
requirements:
type: array
items:
$ref: '#/components/schemas/ViewRequirement'
updates:
type: array
items:
$ref: '#/components/schemas/ViewUpdate'
NotificationType:
type: string
enum:
- UNKNOWN
- CREATE
- UPDATE
- DROP
- VALIDATE
TableUpdateNotification:
type: object
required:
- table-name
- timestamp
- table-uuid
- metadata-location
properties:
table-name:
type: string
timestamp:
type: integer
format: int64
table-uuid:
type: string
metadata-location:
type: string
metadata:
$ref: '#/components/schemas/TableMetadata'
NotificationRequest:
required:
- notification-type
- payload
properties:
notification-type:
$ref: '#/components/schemas/NotificationType'
payload:
$ref: '#/components/schemas/TableUpdateNotification'
ListGenericTablesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
identifiers:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/TableIdentifier'
CreateGenericTableRequest:
type: object
required:
- name
- format
properties:
name:
type: string
format:
type: string
base-location:
type: string
doc:
type: string
properties:
type: object
additionalProperties:
type: string
GenericTable:
type: object
description: |
Generic Table information.
- `name` (REQUIRED): name for the generic table
- `format` (REQUIRED): format for the generic table, i.e. "delta", "csv"
- `base-location` (OPTIONAL): table base location in URI format. For example: s3://<my-bucket>/path/to/table.
- The table base location is a location that includes all files for the table.
- A table with multiple disjoint locations (i.e. containing files that are outside the configured base location) is not compliant with the current generic table support in Polaris.
- If no location is provided, clients or users are responsible for managing the location.
- `properties` (OPTIONAL): properties for the generic table passed on creation
- `doc` (OPTIONAL): comment or description for the generic table
required:
- name
- format
properties:
name:
type: string
format:
type: string
base-location:
type: string
doc:
type: string
properties:
type: object
additionalProperties:
type: string
LoadGenericTableResponse:
description: Result used when a table is successfully loaded.
type: object
required:
- table
properties:
table:
$ref: '#/components/schemas/GenericTable'
PolicyType:
description: The type of a policy
type: string
nullable: true
example: system.data-compaction
PolicyIdentifier:
type: object
required:
- namespace
- name
properties:
namespace:
$ref: '#/components/schemas/Namespace'
name:
type: string
nullable: false
ListPoliciesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
identifiers:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/PolicyIdentifier'
PolicyName:
type: string
description: A policy name. A valid policy name should only consist of uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
pattern: ^[A-Za-z0-9\-_]+$
example: compaction
CreatePolicyRequest:
type: object
required:
- name
- type
properties:
name:
$ref: '#/components/schemas/PolicyName'
type:
type: string
description:
type: string
content:
type: string
Policy:
type: object
description: |
A policy in Apache Polaris defines a set of rules for governing access, data usage, and operational consistency across various catalog resources.
Policies are stored within Polaris and can be attached to catalogs, namespaces, tables, or views.
For example, they can be used for fine-grained control over who can perform specific actions on certain resources.
The policy object includes
- **policy-type:** The type of the policy, which determines the expected format and semantics of the policy content.
- **inheritable:** A boolean flag indicating whether the policy is inheritable.
- **name:** A human-readable name for the policy, which must be unique within a given namespace.
- **description:** Detailed description of the purpose and functionalities of the policy.
- **content:** Policy content, which can be validated against predefined schemas of a policy type.
- **version:** Indicates the current version of the policy. Versions increased monotonically, the default value is 0
Policies stored in Polaris serve as the persistent definition for access control and governance rules.
required:
- policy-type
- name
- version
- inheritable
properties:
policy-type:
type: string
inheritable:
type: boolean
name:
$ref: '#/components/schemas/PolicyName'
description:
type: string
content:
type: string
version:
type: integer
LoadPolicyResponse:
type: object
properties:
policy:
$ref: '#/components/schemas/Policy'
UpdatePolicyRequest:
type: object
properties:
description:
type: string
content:
type: string
current-policy-version:
type: integer
PolicyAttachmentTarget:
type: object
required:
- type
properties:
type:
type: string
description: |
Policy can be attached to different levels:
1. table-like: Policies specific to individual tables or views.
2. namespace: Policies applies to a namespace.
3. catalog: Policies that applies to a catalog
enum:
- catalog
- namespace
- table-like
example: table-like
path:
type: array
items:
type: string
description: |
A list representing the hierarchical path to the target, ordered from the namespace level down to the entity.
If the target is catalog, the path should be either empty or not set.
example:
- NS1
- NS2
- test_table_1
AttachPolicyRequest:
type: object
required:
- target
properties:
target:
$ref: '#/components/schemas/PolicyAttachmentTarget'
parameters:
type: object
additionalProperties:
type: string
DetachPolicyRequest:
type: object
required:
- target
properties:
target:
$ref: '#/components/schemas/PolicyAttachmentTarget'
ApplicablePolicy:
allOf:
- type: object
description: |
For policies returned by GetApplicablePolicies, there are 2 additional fields
- **inherited:** A boolean flag indicating whether the policy is inherited from target's parents. For non-inheritable policy, it should always be `false`.
- **namespace:** A list representing the hierarchical parent path to the policy, ordered from higher level namespace to lower.
required:
- inherited
- namespace
properties:
inherited:
type: boolean
default: false
namespace:
$ref: '#/components/schemas/Namespace'
- $ref: '#/components/schemas/Policy'
GetApplicablePoliciesResponse:
type: object
required:
- applicable-policies
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
applicable-policies:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ApplicablePolicy'
responses:
BadRequestErrorResponse:
description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Malformed request
type: BadRequestException
code: 400
UnauthorizedResponse:
description: Unauthorized. Authentication is required and has failed or has not yet been provided.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Not authorized to make this request
type: NotAuthorizedException
code: 401
ForbiddenResponse:
description: Forbidden. Authenticated user does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Not authorized to make this request
type: NotAuthorizedException
code: 403
AuthenticationTimeoutResponse:
description: Credentials have timed out. If possible, the client should refresh credentials and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Credentials have timed out
type: AuthenticationTimeoutException
code: 419
ServiceUnavailableResponse:
description: |-
The service is not ready to handle the request. The client should wait and retry.
The service may additionally send a Retry-After header to indicate when to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Slow down
type: SlowDownException
code: 503
ServerErrorResponse:
description: A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example:
error:
message: Internal Server Error
type: InternalServerError
code: 500
OAuthTokenResponse:
description: OAuth2 token response for client credentials or token exchange
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokenResponse'
OAuthErrorResponse:
description: OAuth2 error response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
ListNamespacesResponse:
description: A list of namespaces
content:
application/json:
schema:
$ref: '#/components/schemas/ListNamespacesResponse'
examples:
NonEmptyResponse:
$ref: '#/components/examples/ListNamespacesNonEmptyExample'
EmptyResponse:
$ref: '#/components/examples/ListNamespacesEmptyExample'
CreateNamespaceResponse:
description: Represents a successful call to create a namespace. Returns the namespace created, as well as any properties that were stored for the namespace, including those the server might have added. Implementations are not required to support namespace properties.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNamespaceResponse'
example:
namespace:
- accounting
- tax
properties:
owner: Ralph
created_at: '1452120468'
UnsupportedOperationResponse:
description: Not Acceptable / Unsupported Operation. The server does not support this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
example:
error:
message: The server does not support this operation
type: UnsupportedOperationException
code: 406
GetNamespaceResponse:
description: Returns a namespace, as well as any properties stored on the namespace if namespace properties are supported by the server.
content:
application/json:
schema:
$ref: '#/components/schemas/GetNamespaceResponse'
UpdateNamespacePropertiesResponse:
description: JSON data response for a synchronous update properties request.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateNamespacePropertiesResponse'
example:
updated:
- owner
removed:
- foo
missing:
- bar
ListTablesResponse:
description: A list of table identifiers
content:
application/json:
schema:
$ref: '#/components/schemas/ListTablesResponse'
examples:
ListTablesResponseNonEmpty:
$ref: '#/components/examples/ListTablesNonEmptyExample'
ListTablesResponseEmpty:
$ref: '#/components/examples/ListTablesEmptyExample'
CreateTableResponse:
description: Table metadata result after creating a table
content:
application/json:
schema:
$ref: '#/components/schemas/LoadTableResult'
headers:
etag:
$ref: '#/components/headers/etag'
LoadTableResponse:
description: Table metadata result when loading a table
content:
application/json:
schema:
$ref: '#/components/schemas/LoadTableResult'
headers:
etag:
$ref: '#/components/headers/etag'
CommitTableResponse:
description: |-
Response used when a table is successfully updated.
The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata must be returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations.
content:
application/json:
schema:
$ref: '#/components/schemas/CommitTableResponse'
LoadCredentialsResponse:
description: Table credentials result when loading credentials for a table
content:
application/json:
schema:
$ref: '#/components/schemas/LoadCredentialsResponse'
LoadViewResponse:
description: View metadata result when loading a view
content:
application/json:
schema:
$ref: '#/components/schemas/LoadViewResult'
ListGenericTablesResponse:
description: List of generic table identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/ListGenericTablesResponse'
CreateGenericTableResponse:
description: Table result if successfully created a generic table.
content:
application/json:
schema:
$ref: '#/components/schemas/LoadGenericTableResponse'
LoadGenericTableResponse:
description: Table result if successfully load a generic table.
content:
application/json:
schema:
$ref: '#/components/schemas/LoadGenericTableResponse'
ListPoliciesResponse:
description: a list of policy identifiers
content:
application/json:
schema:
$ref: '#/components/schemas/ListPoliciesResponse'
examples:
ListPoliciesResponseNonEmpty:
$ref: '#/components/examples/ListPoliciesNonEmptyExample'
ListPoliciesResponseEmpty:
$ref: '#/components/examples/ListPoliciesEmptyExample'
CreatePolicyResponse:
description: Policy object result after creating a policy
content:
application/json:
schema:
$ref: '#/components/schemas/LoadPolicyResponse'
LoadPolicyResponse:
description: Policy object result when getting a policy
content:
application/json:
schema:
$ref: '#/components/schemas/LoadPolicyResponse'
UpdatePolicyResponse:
description: |-
Response used when a policy is successfully updated
The updated policy JSON is returned in the policy field
content:
application/json:
schema:
$ref: '#/components/schemas/LoadPolicyResponse'
GetApplicablePoliciesResponse:
description: A list of policies applicable to the table
content:
application/json:
schema:
$ref: '#/components/schemas/GetApplicablePoliciesResponse'
parameters:
prefix:
name: prefix
in: path
schema:
type: string
required: true
description: An optional prefix in the path
page-token:
name: pageToken
in: query
required: false
allowEmptyValue: true
schema:
$ref: '#/components/schemas/PageToken'
page-size:
name: pageSize
in: query
description: For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated `pageSize`.
required: false
schema:
type: integer
minimum: 1
namespace:
name: namespace
in: path
required: true
description: A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
schema:
type: string
examples:
singlepart_namespace:
value: accounting
multipart_namespace:
value: accounting%1Ftax
data-access:
name: X-Iceberg-Access-Delegation
in: header
description: |
Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.
Specific properties and handling for `vended-credentials` is documented in the `LoadTableResult` schema section of this spec document.
The protocol and specification for `remote-signing` is documented in the `s3-signer-open-api.yaml` OpenApi spec in the `aws` module.
required: false
schema:
type: string
enum:
- vended-credentials
- remote-signing
style: simple
explode: false
example: vended-credentials,remote-signing
table:
name: table
in: path
description: A table name
required: true
schema:
type: string
example: sales
view:
name: view
in: path
description: A view name
required: true
schema:
type: string
example: sales
generic-table:
name: generic-table
in: path
description: A generic table name
required: true
schema:
type: string
example: sales
policy-type:
name: policyType
in: query
required: false
allowEmptyValue: true
schema:
$ref: '#/components/schemas/PolicyType'
policy-name:
name: policy-name
in: path
required: true
schema:
$ref: '#/components/schemas/PolicyName'
examples:
ListNamespacesNonEmptyExample:
summary: A non-empty list of namespaces
value:
namespaces:
- - accounting
- tax
- - accounting
- credits
ListNamespacesEmptyExample:
summary: An empty list of namespaces
value:
namespaces: []
NoSuchNamespaceError:
summary: The requested namespace does not exist
value:
error:
message: The given namespace does not exist
type: NoSuchNamespaceException
code: 404
NamespaceAlreadyExistsError:
summary: The requested namespace already exists
value:
error:
message: The given namespace already exists
type: AlreadyExistsException
code: 409
UpdateAndRemoveNamespacePropertiesRequest:
summary: An update namespace properties request with both properties to remove and properties to upsert.
value:
removals:
- foo
- bar
updates:
owner: Raoul
UnprocessableEntityDuplicateKey:
summary: The request body either has the same key multiple times in what should be a map with unique keys or the request body has keys in two or more fields which should be disjoint sets.
value:
error:
message: The request cannot be processed as there is a key present multiple times
type: UnprocessableEntityException
code: 422
ListTablesNonEmptyExample:
summary: A non-empty list of table identifiers
value:
identifiers:
- namespace:
- accounting
- tax
name: paid
- namespace:
- accounting
- tax
name: owed
ListTablesEmptyExample:
summary: An empty list for a namespace with no tables
value:
identifiers: []
TableAlreadyExistsError:
summary: The requested table identifier already exists
value:
error:
message: The given table already exists
type: AlreadyExistsException
code: 409
NoSuchTableError:
summary: The requested table does not exist
value:
error:
message: The given table does not exist
type: NoSuchTableException
code: 404
RenameTableSameNamespace:
summary: Rename a table in the same namespace
value:
source:
namespace:
- accounting
- tax
name: paid
destination:
namespace:
- accounting
- tax
name: owed
ViewAlreadyExistsError:
summary: The requested view identifier already exists
value:
error:
message: The given view already exists
type: AlreadyExistsException
code: 409
NoSuchViewError:
summary: The requested view does not exist
value:
error:
message: The given view does not exist
type: NoSuchViewException
code: 404
RenameViewSameNamespace:
summary: Rename a view in the same namespace
value:
source:
namespace:
- accounting
- tax
name: paid-view
destination:
namespace:
- accounting
- tax
name: owed-view
ListPoliciesNonEmptyExample:
summary: A non-empty list of policy identifiers
value:
identifiers:
- namespace:
- accounting
- tax
name: policy1
- namespace:
- accounting
- tax
name: policy2
ListPoliciesEmptyExample:
summary: An empty list for a namespace with no policies
value:
identifiers: []
PolicyAlreadyExistsError:
summary: The requested policy identifier already exists
value:
error:
message: The given policy already exists
type: AlreadyExistsException
code: 409
NoSuchPolicyError:
summary: The requested policy does not exist
value:
error:
message: The given policy does not exist
type: NoSuchPolicyException
code: 404
PolicyVersionMismatchError:
summary: The policy version doesn't match the current-policy-version
value:
error:
message: The policy version doesn't match the current-policy-version
type: PolicyVersionMismatchException
code: 409
PolicyInUseError:
summary: The policy is attached to one or more targets
value:
error:
message: The policy is attached to one or more targets
type: PolicyInUseException
code: 400
NoSuchTargetError:
summary: The requested target does not exist
value:
error:
message: The given target does not exist
type: NoSuchTargetException
code: 404
ConflictPolicyAttachmentError:
summary: The policy type is inheritable and there is already a policy of the same type attached to the target entity
value:
error:
message: The policy type is inheritable and there is already a policy of the same type attached to the target entity
type: ConflictPolicyAttachmentException
code: 409
NoSuchMappingError:
summary: The requested mapping between policy and target does not exist
value:
error:
message: The given mapping between policy and target does not exist
type: NoSuchMappingException
code: 404
headers:
etag:
name: ETag
in: header
description: Identifies a unique version of the table metadata.
required: false
schema:
type: string
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment