Google Git
Sign in
apache / iceberg / c9795fda7105789edc0d1f8a624ceb251dfd4a69 / . / open-api / rest-catalog-open-api.yaml
blob: 77aabc834adb28e208cb22ce317c2bc9da7b89d7 [file] [log] [blame]
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
#
---
openapi: 3.0.3
info:
title: 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 first version of the REST Catalog API.
Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
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: ""
# All routes are currently configured using an Authorization header.
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:
"
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
"
responses:
200:
description: Server specified configuration values.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogConfig'
example: {
"overrides": {
"warehouse": "s3://bucket/warehouse/"
},
"defaults": {
"clients": "4"
}
}
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
operationId: getToken
description:
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.
requestBody:
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'
/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'
- 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:
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:
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'
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'
419:
$ref: '#/components/responses/AuthenticationTimeoutResponse'
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/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/data-access'
requestBody:
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:
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/data-access'
- 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'
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.
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:
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
}
}
503:
$ref: '#/components/responses/ServiceUnavailableResponse'
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
}
}
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}/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:
$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}/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.
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
}
}
503:
$ref: '#/components/responses/ServiceUnavailableResponse'
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
}
}
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/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:
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:
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
}
}
503:
$ref: '#/components/responses/ServiceUnavailableResponse'
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
}
}
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:
200:
description: OK
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:
$ref: '#/components/examples/ViewAlreadyExistsError'
419:
$ref: '#/components/responses/AuthenticationTimeoutResponse'
503:
$ref: '#/components/responses/ServiceUnavailableResponse'
5XX:
$ref: '#/components/responses/ServerErrorResponse'
components:
#######################################################
# Common Parameter Definitions Used In Several Routes #
#######################################################
parameters:
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"
prefix:
name: prefix
in: path
schema:
type: string
required: true
description: An optional prefix in the path
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"
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"
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
##############################
# Application Schema Objects #
##############################
schemas:
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
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.
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
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
RenameTableRequest:
type: object
required:
- source
- destination
properties:
source:
$ref: '#/components/schemas/TableIdentifier'
destination:
$ref: '#/components/schemas/TableIdentifier'
Namespace:
description: Reference to one or more levels of a namespace
type: array
items:
type: string
example: [ "accounting", "tax" ]
PageToken:
description:
An opaque token which allows clients to make use of pagination for a list API (e.g. ListTables).
Clients will initiate the first paginated request by sending an empty `pageToken` e.g. `GET /tables?pageToken` or `GET /tables?pageToken=`
signaling to the service that the response should be paginated.
Servers that support pagination will recognize `pageToken` and return a `next-page-token` in response if there are more results available.
After the initial request, it is expected that the value of `next-page-token` from the last response is used in the subsequent request.
Servers that do not support pagination will ignore `next-page-token` and return all results.
type: string
TableIdentifier:
type: object
required:
- namespace
- name
properties:
namespace:
$ref: '#/components/schemas/Namespace'
name:
type: string
nullable: false
PrimitiveType:
type: string
example:
- "long"
- "string"
- "fixed[16]"
- "decimal(10,2)"
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
StructType:
type: object
required:
- type
- fields
properties:
type:
type: string
enum: ["struct"]
fields:
type: array
items:
$ref: '#/components/schemas/StructField'
ListType:
type: object
required:
- type
- element-id
- element
- element-required
properties:
type:
type: string
enum: ["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
enum: ["map"]
key-id:
type: integer
key:
$ref: '#/components/schemas/Type'
value-id:
type: integer
value:
$ref: '#/components/schemas/Type'
value-required:
type: boolean
Type:
oneOf:
- $ref: '#/components/schemas/PrimitiveType'
- $ref: '#/components/schemas/StructType'
- $ref: '#/components/schemas/ListType'
- $ref: '#/components/schemas/MapType'
Schema:
allOf:
- $ref: '#/components/schemas/StructType'
- type: object
properties:
schema-id:
type: integer
readOnly: true
identifier-field-ids:
type: array
items:
type: integer
Expression:
oneOf:
- $ref: '#/components/schemas/AndOrExpression'
- $ref: '#/components/schemas/NotExpression'
- $ref: '#/components/schemas/SetExpression'
- $ref: '#/components/schemas/LiteralExpression'
- $ref: '#/components/schemas/UnaryExpression'
ExpressionType:
type: string
example:
- "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"
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'
enum: ["not"]
child:
$ref: '#/components/schemas/Expression'
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
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
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
Term:
oneOf:
- $ref: '#/components/schemas/Reference'
- $ref: '#/components/schemas/TransformTerm'
Reference:
type: string
example:
- "column-name"
TransformTerm:
type: object
required:
- type
- transform
- term
properties:
type:
type: string
enum: ["transform"]
transform:
$ref: '#/components/schemas/Transform'
term:
$ref: '#/components/schemas/Reference'
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'
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
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
# schema tracking
schemas:
type: array
items:
$ref: '#/components/schemas/Schema'
current-schema-id:
type: integer
last-column-id:
type: integer
# partition spec tracking
partition-specs:
type: array
items:
$ref: '#/components/schemas/PartitionSpec'
default-spec-id:
type: integer
last-partition-id:
type: integer
# sort order tracking
sort-orders:
type: array
items:
$ref: '#/components/schemas/SortOrder'
default-sort-order-id:
type: integer
# snapshot tracking
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
# logs
snapshot-log:
$ref: '#/components/schemas/SnapshotLog'
metadata-log:
$ref: '#/components/schemas/MetadataLog'
# statistics
statistics-files:
type: array
items:
$ref: '#/components/schemas/StatisticsFile'
partition-statistics-files:
type: array
items:
$ref: '#/components/schemas/PartitionStatisticsFile'
SQLViewRepresentation:
type: object
required:
- type
- sql
- dialect
properties:
type:
type: string
sql:
type: string
dialect:
type: string
ViewRepresentation:
oneOf:
- $ref: '#/components/schemas/SQLViewRepresentation'
ViewHistoryEntry:
type: object
required:
- version-id
- timestamp-ms
properties:
version-id:
type: integer
timestamp-ms:
type: integer
format: int64
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'
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
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'
type: object
required:
- action
properties:
action:
type: string
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:
- action
- uuid
properties:
action:
type: string
enum: ["assign-uuid"]
uuid:
type: string
UpgradeFormatVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- format-version
properties:
action:
type: string
enum: ["upgrade-format-version"]
format-version:
type: integer
AddSchemaUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- schema
properties:
action:
type: string
enum: ["add-schema"]
schema:
$ref: '#/components/schemas/Schema'
last-column-id:
type: integer
description: 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:
- action
- schema-id
properties:
action:
type: string
enum: ["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:
- action
- spec
properties:
action:
type: string
enum: ["add-spec"]
spec:
$ref: '#/components/schemas/PartitionSpec'
SetDefaultSpecUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- spec-id
properties:
action:
type: string
enum: [ "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:
- action
- sort-order
properties:
action:
type: string
enum: [ "add-sort-order" ]
sort-order:
$ref: '#/components/schemas/SortOrder'
SetDefaultSortOrderUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- sort-order-id
properties:
action:
type: string
enum: [ "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:
- action
- snapshot
properties:
action:
type: string
enum: [ "add-snapshot" ]
snapshot:
$ref: '#/components/schemas/Snapshot'
SetSnapshotRefUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
- $ref: '#/components/schemas/SnapshotReference'
required:
- action
- ref-name
properties:
action:
type: string
enum: [ "set-snapshot-ref" ]
ref-name:
type: string
RemoveSnapshotsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- snapshot-ids
properties:
action:
type: string
enum: [ "remove-snapshots" ]
snapshot-ids:
type: array
items:
type: integer
format: int64
RemoveSnapshotRefUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- ref-name
properties:
action:
type: string
enum: [ "remove-snapshot-ref" ]
ref-name:
type: string
SetLocationUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- location
properties:
action:
type: string
enum: [ "set-location" ]
location:
type: string
SetPropertiesUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- updates
properties:
action:
type: string
enum: [ "set-properties" ]
updates:
type: object
additionalProperties:
type: string
RemovePropertiesUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- removals
properties:
action:
type: string
enum: [ "remove-properties" ]
removals:
type: array
items:
type: string
AddViewVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- view-version
properties:
action:
type: string
enum: [ "add-view-version" ]
view-version:
$ref: '#/components/schemas/ViewVersion'
SetCurrentViewVersionUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- view-version-id
properties:
action:
type: string
enum: [ "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:
- action
- snapshot-id
- statistics
properties:
action:
type: string
enum: [ "set-statistics" ]
snapshot-id:
type: integer
format: int64
statistics:
$ref: '#/components/schemas/StatisticsFile'
RemoveStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- snapshot-id
properties:
action:
type: string
enum: [ "remove-statistics" ]
snapshot-id:
type: integer
format: int64
SetPartitionStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- partition-statistics
properties:
action:
type: string
enum: [ "set-partition-statistics" ]
partition-statistics:
$ref: '#/components/schemas/PartitionStatisticsFile'
RemovePartitionStatisticsUpdate:
allOf:
- $ref: '#/components/schemas/BaseUpdate'
required:
- action
- snapshot-id
properties:
action:
type: string
enum: [ "remove-partition-statistics" ]
snapshot-id:
type: integer
format: int64
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'
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'
TableRequirement:
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'
type: object
required:
- type
properties:
type:
type: "string"
AssertCreate:
allOf:
- $ref: "#/components/schemas/TableRequirement"
type: object
description: The table must not already exist; used for create transactions
required:
- type
properties:
type:
type: string
enum: ["assert-create"]
AssertTableUUID:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description: The table UUID must match the requirement's `uuid`
required:
- type
- uuid
properties:
type:
type: string
enum: ["assert-table-uuid"]
uuid:
type: string
AssertRefSnapshotId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
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
required:
- type
- ref
- snapshot-id
properties:
type:
type: string
enum: [ "assert-ref-snapshot-id" ]
ref:
type: string
snapshot-id:
type: integer
format: int64
AssertLastAssignedFieldId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description:
The table's last assigned column id must match the requirement's `last-assigned-field-id`
required:
- type
- last-assigned-field-id
properties:
type:
type: string
enum: [ "assert-last-assigned-field-id" ]
last-assigned-field-id:
type: integer
AssertCurrentSchemaId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description:
The table's current schema id must match the requirement's `current-schema-id`
required:
- type
- current-schema-id
properties:
type:
type: string
enum: [ "assert-current-schema-id" ]
current-schema-id:
type: integer
AssertLastAssignedPartitionId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description:
The table's last assigned partition id must match the requirement's `last-assigned-partition-id`
required:
- type
- last-assigned-partition-id
properties:
type:
type: string
enum: [ "assert-last-assigned-partition-id" ]
last-assigned-partition-id:
type: integer
AssertDefaultSpecId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description:
The table's default spec id must match the requirement's `default-spec-id`
required:
- type
- default-spec-id
properties:
type:
type: string
enum: [ "assert-default-spec-id" ]
default-spec-id:
type: integer
AssertDefaultSortOrderId:
allOf:
- $ref: "#/components/schemas/TableRequirement"
description:
The table's default sort order id must match the requirement's `default-sort-order-id`
required:
- type
- default-sort-order-id
properties:
type:
type: string
enum: [ "assert-default-sort-order-id" ]
default-sort-order-id:
type: integer
ViewRequirement:
discriminator:
propertyName: type
mapping:
assert-view-uuid: '#/components/schemas/AssertViewUUID'
type: object
required:
- type
properties:
type:
type: "string"
AssertViewUUID:
allOf:
- $ref: "#/components/schemas/ViewRequirement"
description: The view UUID must match the requirement's `uuid`
required:
- type
- uuid
properties:
type:
type: string
enum: [ "assert-view-uuid" ]
uuid:
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 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
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
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'
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'
CommitTransactionRequest:
type: object
required:
- table-changes
properties:
table-changes:
type: array
items:
description: Table commit request; must provide an `identifier`
$ref: '#/components/schemas/CommitTableRequest'
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
RegisterTableRequest:
type: object
required:
- name
- metadata-location
properties:
name:
type: string
metadata-location:
type: string
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
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
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
OAuthClientCredentialsRequest:
description:
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.
OAuthTokenExchangeRequest:
description:
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:
anyOf:
- $ref: '#/components/schemas/OAuthClientCredentialsRequest'
- $ref: '#/components/schemas/OAuthTokenExchangeRequest'
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,
}
}
ReportMetricsRequest:
anyOf:
- $ref: '#/components/schemas/ScanReport'
- $ref: '#/components/schemas/CommitReport'
required:
- report-type
properties:
report-type:
type: string
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
OAuthError:
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
OAuthTokenResponse:
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
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
}
}
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
ListTablesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
identifiers:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/TableIdentifier'
ListNamespacesResponse:
type: object
properties:
next-page-token:
$ref: '#/components/schemas/PageToken'
namespaces:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/Namespace'
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
CommitTableResponse:
type: object
required:
- metadata-location
- metadata
properties:
metadata-location:
type: string
metadata:
$ref: '#/components/schemas/TableMetadata'
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'
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
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
BooleanTypeValue:
type: boolean
example: true
IntegerTypeValue:
type: integer
example: 42
LongTypeValue:
type: integer
format: int64
example: 9223372036854775807
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"
CountMap:
type: object
properties:
keys:
type: array
items:
$ref: '#/components/schemas/IntegerTypeValue'
description: "List of integer column ids for each corresponding value"
values:
type: array
items:
$ref: '#/components/schemas/LongTypeValue'
description: "List of Long values, matched to 'keys' by index"
example:
{
"keys": [ 1, 2 ],
"values": [ 100,200 ]
}
ValueMap:
type: object
properties:
keys:
type: array
items:
$ref: '#/components/schemas/IntegerTypeValue'
description: "List of integer column ids for each corresponding value"
values:
type: array
items:
$ref: '#/components/schemas/PrimitiveTypeValue'
description: "List of primitive type values, matched to 'keys' by index"
example:
{
"keys": [ 1, 2 ],
"values": [ 100, "test" ]
}
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'
FileFormat:
type: string
enum:
- avro
- orc
- parquet
ContentFile:
discriminator:
propertyName: content
mapping:
data: '#/components/schemas/DataFile'
position-deletes: '#/components/schemas/PositionDeleteFile'
equality-deletes: '#/components/schemas/EqualityDeleteFile'
type: object
required:
- spec-id
- content
- file-path
- file-format
- file-size-in-bytes
- record-count
properties:
content:
type: string
file-path:
type: string
file-format:
$ref: '#/components/schemas/FileFormat'
spec-id:
type: integer
partition:
type: array
items:
$ref: '#/components/schemas/PrimitiveTypeValue'
description:
"A list of partition field values ordered based on the fields of the partition spec specified by the
`spec-id`"
example: [1, "bar"]
file-size-in-bytes:
type: integer
format: int64
description: "Total file size in bytes"
record-count:
type: integer
format: int64
description: "Number of records in the file"
key-metadata:
allOf:
- $ref: '#/components/schemas/BinaryTypeValue'
description: "Encryption key metadata blob"
split-offsets:
type: array
items:
type: integer
format: int64
description: "List of splittable offsets"
sort-order-id:
type: integer
DataFile:
allOf:
- $ref: '#/components/schemas/ContentFile'
type: object
required:
- content
properties:
content:
type: string
enum: [ "data" ]
column-sizes:
allOf:
- $ref: '#/components/schemas/CountMap'
description: "Map of column id to total count, including null and NaN"
value-counts:
allOf:
- $ref: '#/components/schemas/CountMap'
description: "Map of column id to null value count"
null-value-counts:
allOf:
- $ref: '#/components/schemas/CountMap'
description: "Map of column id to null value count"
nan-value-counts:
allOf:
- $ref: '#/components/schemas/CountMap'
description: "Map of column id to number of NaN values in the column"
lower-bounds:
allOf:
- $ref: '#/components/schemas/ValueMap'
description: "Map of column id to lower bound primitive type values"
upper-bounds:
allOf:
- $ref: '#/components/schemas/ValueMap'
description: "Map of column id to upper bound primitive type values"
PositionDeleteFile:
allOf:
- $ref: '#/components/schemas/ContentFile'
required:
- content
properties:
content:
type: string
enum: [ "position-deletes" ]
EqualityDeleteFile:
allOf:
- $ref: '#/components/schemas/ContentFile'
required:
- content
properties:
content:
type: string
enum: [ "equality-deletes" ]
equality-ids:
type: array
items:
type: integer
description: "List of equality field IDs"
#############################
# Reusable Response Objects #
#############################
responses:
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'
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
}
}
# Note that this is a representative example response for use as a shorthand in the spec.
# The fields `message` and `type` as indicated here are not presently prescriptive.
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
}
}
# Note that this is a representative example response for use as a shorthand in the spec.
# The fields `message` and `type` as indicated here are not presently prescriptive.
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
}
}
# Note that this is a representative example response for use as a shorthand in the spec.
# The fields `message` and `type` as indicated here are not presently prescriptive.
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
}
}
IcebergErrorResponse:
description: JSON wrapper for all error responses (non-2xx)
content:
application/json:
schema:
$ref: '#/components/schemas/IcebergErrorResponse'
example: {
"error": {
"message": "The server does not support this operation",
"type": "UnsupportedOperationException",
"code": 406
} }
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" }
}
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'
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'
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'
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
}
}
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" ]
}
CreateTableResponse:
description: Table metadata result after creating a table
content:
application/json:
schema:
$ref: '#/components/schemas/LoadTableResult'
LoadTableResponse:
description: Table metadata result when loading a table
content:
application/json:
schema:
$ref: '#/components/schemas/LoadTableResult'
LoadViewResponse:
description: View metadata result when loading a view
content:
application/json:
schema:
$ref: '#/components/schemas/LoadViewResult'
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'
#######################################
# Common examples of different values #
#######################################
examples:
ListTablesEmptyExample:
summary: An empty list for a namespace with no tables
value: {
"identifiers": [ ]
}
ListNamespacesEmptyExample:
summary: An empty list of namespaces
value: {
"namespaces": [ ]
}
ListNamespacesNonEmptyExample:
summary: A non-empty list of namespaces
value: {
"namespaces": [
["accounting", "tax"],
["accounting", "credits"]
]
}
ListTablesNonEmptyExample:
summary: A non-empty list of table identifiers
value: {
"identifiers": [
{ "namespace": ["accounting", "tax"], "name": "paid" },
{ "namespace": ["accounting", "tax"], "name": "owed" }
]
}
MultipartNamespaceAsPathVariable:
summary: A multi-part namespace, as represented in a path parameter
value: "accounting%1Ftax"
NamespaceAsPathVariable:
summary: A single part namespace, as represented in a path paremeter
value: "accounting"
NamespaceAlreadyExistsError:
summary: The requested namespace already exists
value: {
"error": {
"message": "The given namespace 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
}
}
NoSuchViewError:
summary: The requested view does not exist
value: {
"error": {
"message": "The given view does not exist",
"type": "NoSuchViewException",
"code": 404
}
}
NoSuchNamespaceError:
summary: The requested namespace does not exist
value: {
"error": {
"message": "The given namespace does not exist",
"type": "NoSuchNamespaceException",
"code": 404
}
}
RenameTableSameNamespace:
summary: Rename a table in the same namespace
value: {
"source": { "namespace": ["accounting", "tax"], "name": "paid" },
"destination": { "namespace": ["accounting", "tax"], "name": "owed" }
}
RenameViewSameNamespace:
summary: Rename a view in the same namespace
value: {
"source": { "namespace": [ "accounting", "tax" ], "name": "paid-view" },
"destination": { "namespace": [ "accounting", "tax" ], "name": "owed-view" }
}
TableAlreadyExistsError:
summary: The requested table identifier already exists
value: {
"error": {
"message": "The given table already exists",
"type": "AlreadyExistsException",
"code": 409
}
}
ViewAlreadyExistsError:
summary: The requested view identifier already exists
value: {
"error": {
"message": "The given view already exists",
"type": "AlreadyExistsException",
"code": 409
}
}
# This is an example response and is not meant to be prescriptive regarding the message or type.
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
}
}
UpdateAndRemoveNamespacePropertiesRequest:
summary: An update namespace properties request with both properties to remove and properties to upsert.
value: {
"removals": [ "foo", "bar" ],
"updates": { "owner": "Raoul" }
}
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