openapi: 3.2.0 info: title: Apache Iceberg REST Catalog 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 all Iceberg table spec versions. servers: - url: '{scheme}://{host}/{basePath}' description: Server URL when the port can be inferred from the scheme variables: scheme: description: The scheme of the URI, either http or https. default: https host: description: The host address for the specified server default: localhost basePath: description: Optional prefix to be appended to all routes default: '' - url: '{scheme}://{host}:{port}/{basePath}' description: Generic base server URL, with all parts configurable variables: scheme: description: The scheme of the URI, either http or https. default: https host: description: The host address for the specified server default: localhost port: description: The port used when addressing the host default: '443' basePath: description: Optional prefix to be appended to all routes default: '' security: - OAuth2: - catalog - BearerAuth: [] tags: - name: Catalog API paths: /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, all top-level namespaces should be listed. For backward compatibility, empty string is treated as absent for now. If parent is a multipart namespace, the parts must be separated by the namespace separator as indicated via the /config override `namespace-separator`, which defaults to the unit separator `0x1F` byte (url encoded `%1F`). To be compatible with older clients, servers must use both the advertised separator and `0x1F` as valid separators when decoding namespaces. The `namespace-separator` should be provided in a url encoded form. required: false schema: type: string example: accounting%1Ftax - name: returnUuids in: query description: If true, include the `namespace-uuids` field in the response required: false schema: type: boolean default: false - name: returnProtectionStatus in: query description: If true, include the `protection-status` field in the response required: false schema: type: boolean default: false 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 parameters: - $ref: '#/components/parameters/idempotency-key' description: Create a namespace, with an optional set of properties. The server might also add properties, such as `last_modified_time` etc. operationId: createNamespace requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateNamespaceRequest' responses: 200: $ref: '#/components/responses/CreateNamespaceResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 406: $ref: '#/components/responses/UnsupportedOperationResponse' 409: description: Conflict - The namespace already exists content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NamespaceAlreadyExists: $ref: '#/components/examples/NamespaceAlreadyExistsError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /v1/{prefix}/namespaces/{namespace}: parameters: - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/namespace' get: tags: - Catalog API summary: Load the metadata properties for a namespace operationId: loadNamespaceMetadata description: Return all stored metadata properties for a given namespace responses: 200: $ref: '#/components/responses/GetNamespaceResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - Namespace not found content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NoSuchNamespaceExample: $ref: '#/components/examples/NoSuchNamespaceError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' parameters: - name: returnUuid in: query description: If true, include the `namespace-uuid` field in the response required: false schema: type: boolean default: false 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. operationId: dropNamespace parameters: - $ref: '#/components/parameters/idempotency-key' - name: force in: query description: If force and recursive are set to true, immediately delete all contents of the namespace without considering soft-delete policies. Force has no effect without recursive=true. required: false schema: type: boolean default: false - name: recursive in: query description: Delete a namespace and its contents. This means all tables, views, and namespaces under this namespace will be deleted. The namespace itself will also be deleted. If the warehouse containing the namespace is configured with a soft-deletion profile, the `force` flag has to be provided. The deletion will not be a soft-deletion. Every table, view and namespace will be gone as soon as this call returns. Depending on whether the `purge` flag was set to true, the data will be queued for deletion too. Any pending `tabular_expiration` will be cancelled. If there is a running `tabular_expiration`, this call will fail with a `409 Conflict` error. required: false schema: type: boolean default: false - name: purge in: query description: If recursive is true, also deletes table and view data. If false, only metadata is dropped from the catalog, table location remains untouched. Defaults to true for all tables managed by Lakekeeper. required: false schema: type: boolean default: 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 - Namespace to delete does not exist. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NoSuchNamespaceExample: $ref: '#/components/examples/NoSuchNamespaceError' 409: description: Not Empty - Namespace to delete is not empty. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NamespaceNotEmptyExample: $ref: '#/components/examples/NamespaceNotEmptyError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' description: Drop a namespace from the catalog. By default, the namespace needs to be empty. You can however set `recursive=true` which will delete all tables, views and namespaces under this namespace. The namespace itself will also be deleted. If the warehouse containing the namespace is configured with a soft-deletion profile, the `force` flag has to be provided. The deletion will not be a soft-deletion. Every table, view and namespace will be gone as soon as this call returns. Depending on whether the `purge` flag was set to true, the data will be queued for deletion too. Any pending `tabular_expiration` will be cancelled. If there is a running `tabular_expiration`, this call will fail with a `409 Conflict` error. /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 parameters: - $ref: '#/components/parameters/idempotency-key' description: 'Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update. Properties that are not in the request are not modified or removed by this call. Server implementations are not required to support namespace properties.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateNamespacePropertiesRequest' examples: UpdateAndRemoveProperties: $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest' responses: 200: $ref: '#/components/responses/UpdateNamespacePropertiesResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - Namespace not found content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NamespaceNotFound: $ref: '#/components/examples/NoSuchNamespaceError' 406: $ref: '#/components/responses/UnsupportedOperationResponse' 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' - name: returnUuids in: query description: If true, include the `table-uuids` field in the response required: false schema: type: boolean default: false - name: returnProtectionStatus in: query description: If true, include the `protection-status` field in the response required: false schema: type: boolean default: false 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' - $ref: '#/components/parameters/idempotency-key' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTableRequest' responses: 200: $ref: '#/components/responses/CreateTableResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - The namespace specified does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NamespaceNotFound: $ref: '#/components/examples/NoSuchNamespaceError' 409: description: Conflict - The table already exists content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableAlreadyExists: $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}/plan: parameters: - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/namespace' - $ref: '#/components/parameters/table' - $ref: '#/components/parameters/data-access' post: tags: - Catalog API summary: Submit a scan for planning description: "Submits a scan for server-side planning.\nPoint-in-time scans are planned by passing snapshot-id to identify the table snapshot to scan. Incremental scans are planned by passing both start-snapshot-id and end-snapshot-id. Requests that include both point in time config properties and incremental config properties are invalid. If the request does not include either incremental or point-in-time config properties, scan planning should produce a point-in-time scan of the latest snapshot in the table's main branch.\nResponses must include a valid status listed below. A \"cancelled\" status is considered invalid for this endpoint.\n- When \"completed\" the planning operation has produced plan tasks and\n\n file scan tasks that must be returned in the response (not fetched\n later by calling fetchPlanningResult)\n\n- When \"submitted\" the response must include a plan-id used to poll\n\n fetchPlanningResult to fetch the planning result when it is ready\n\n- When \"failed\" the response must be a valid error response\nThe response for a \"completed\" planning operation includes two types of tasks (file scan tasks and plan tasks) and both may be included in the response. Tasks must not be included for any other response status.\nResponses that include a plan-id indicate that the service is holding state or performing work for the client.\n- Clients should use the plan-id to fetch results from\n\n fetchPlanningResult when the response status is \"submitted\"\n\n- Clients should inform the service if planning results are no longer\n\n needed by calling cancelPlanning. Cancellation is not necessary after\n fetchScanTasks has been used to fetch scan tasks for each plan task.\n" operationId: planTableScan parameters: - $ref: '#/components/parameters/idempotency-key' requestBody: content: application/json: schema: $ref: '#/components/schemas/PlanTableScanRequest' responses: 200: $ref: '#/components/responses/PlanTableScanResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableDoesNotExist: $ref: '#/components/examples/NoSuchTableError' NamespaceDoesNotExist: $ref: '#/components/examples/NoSuchNamespaceError' 406: $ref: '#/components/responses/UnsupportedOperationResponse' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}: parameters: - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/namespace' - $ref: '#/components/parameters/table' - $ref: '#/components/parameters/plan-id' - $ref: '#/components/parameters/data-access' get: tags: - Catalog API summary: Fetches the result of scan planning for a plan-id operationId: fetchPlanningResult description: "Fetches the result of scan planning for a plan-id.\nResponses must include a valid status\n- When \"completed\" the planning operation has produced plan-tasks and\n\n file-scan-tasks that must be returned in the response\n\n- When \"submitted\" the planning operation has not completed; the client\n\n should wait to call this endpoint again to fetch a completed response\n\n- When \"failed\" the response must be a valid error response\n- When \"cancelled\" the plan-id is invalid and should be discarded\nThe response for a \"completed\" planning operation includes two types of tasks (file scan tasks and plan tasks) and both may be included in the response. Tasks must not be included for any other response status.\n" responses: 200: $ref: '#/components/responses/FetchPlanningResultResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: PlanIdDoesNotExist: $ref: '#/components/examples/NoSuchPlanIdError' TableDoesNotExist: $ref: '#/components/examples/NoSuchTableError' NamespaceDoesNotExist: $ref: '#/components/examples/NoSuchNamespaceError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' delete: tags: - Catalog API summary: Cancels scan planning for a plan-id operationId: cancelPlanning parameters: - $ref: '#/components/parameters/idempotency-key' description: "Cancels scan planning for a plan-id.\nThis notifies the service that it can release resources held for the scan. Clients should cancel scans that are no longer needed, either while the plan-id returns a \"submitted\" status or while there are remaining plan tasks that have not been fetched.\nCancellation is not necessary when\n- Scan tasks for each plan task have been fetched using fetchScanTasks\n- A plan-id has produced a \"failed\" or \"cancelled\" status from\n\n planTableScan or fetchPlanningResult\n" 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 - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: PlanIdDoesNotExist: $ref: '#/components/examples/NoSuchPlanIdError' TableDoesNotExist: $ref: '#/components/examples/NoSuchTableError' NamespaceDoesNotExist: $ref: '#/components/examples/NoSuchNamespaceError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /v1/{prefix}/namespaces/{namespace}/tables/{table}/tasks: parameters: - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/namespace' - $ref: '#/components/parameters/table' post: tags: - Catalog API summary: Fetches result tasks for a plan task operationId: fetchScanTasks parameters: - $ref: '#/components/parameters/idempotency-key' description: Fetches result tasks for a plan task. requestBody: content: application/json: schema: $ref: '#/components/schemas/FetchScanTasksRequest' responses: 200: $ref: '#/components/responses/FetchScanTasksResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchPlanTaskException, the plan-task does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: PlanTaskDoesNotExist: $ref: '#/components/examples/NoSuchPlanTaskError' TableDoesNotExist: $ref: '#/components/examples/NoSuchTableError' NamespaceDoesNotExist: $ref: '#/components/examples/NoSuchNamespaceError' 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 parameters: - $ref: '#/components/parameters/data-access' - $ref: '#/components/parameters/idempotency-key' description: Register a table using given metadata file location. operationId: registerTable requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterTableRequest' responses: 200: $ref: '#/components/responses/LoadTableResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - The namespace specified does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: NamespaceNotFound: $ref: '#/components/examples/NoSuchNamespaceError' 409: description: Conflict - The table already exists content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableAlreadyExists: $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=".' parameters: - $ref: '#/components/parameters/data-access' - name: If-None-Match in: header description: An optional header that allows the server to return 304 (Not Modified) if the metadata is current. The content is the value of the ETag received in a CreateTableResponse, LoadTableResponse or CommitTableResponse. required: false schema: type: string - in: query name: snapshots description: 'The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags. Default if no param is provided is `all`.' required: false schema: type: string enum: - all - refs - $ref: '#/components/parameters/referenced-by' responses: 200: $ref: '#/components/responses/LoadTableResponse' 304: description: Not Modified - Based on the content of the 'If-None-Match' header the table metadata has not changed since. 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, table to load does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToLoadDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' post: tags: - Catalog API summary: Commit updates to a table operationId: updateTable parameters: - $ref: '#/components/parameters/idempotency-key' description: 'Commit updates to a table. Commits have two parts, requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, `assert-ref-snapshot-id` will check that a named ref''s snapshot ID has a certain value. Server implementations are required to fail with a 400 status code if any unknown updates or requirements are received. Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id. Create table transactions that are started by createTable with `stage-create` set to true are committed using this route. Transactions should include all changes to the table, including table initialization, like AddSchemaUpdate and SetCurrentSchemaUpdate. The `assert-create` requirement is used to ensure that the table was not created concurrently.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CommitTableRequest' responses: 200: $ref: '#/components/responses/CommitTableResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, table to load does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToUpdateDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 409: description: Conflict - CommitFailedException, one or more requirements failed. The client may retry. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 500: description: An unknown server-side problem occurred; the commit state is unknown. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' example: error: message: Internal Server Error type: CommitStateUnknownException code: 500 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: - $ref: '#/components/parameters/idempotency-key' - name: purgeRequested in: query required: false description: 'Whether the user requested to purge the underlying table data and metadata. Note: when omitted, Lakekeeper treats the drop as a purge for tables it manages, so the data is removed. This differs from the Iceberg REST default of false. See the Dropping Tables section of the Lakekeeper documentation.' schema: type: boolean default: false - name: force in: query description: If true, ignore `protection-status` when dropping. required: false schema: type: boolean default: false responses: 204: description: Success, no content 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, Table to drop does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToDeleteDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' head: tags: - Catalog API summary: Check if a table exists operationId: tableExists description: Check if a table exists within a given namespace. The response does not contain a body. responses: 204: description: Success, no content 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, Table not found content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToLoadDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials: parameters: - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/namespace' - $ref: '#/components/parameters/table' get: tags: - Catalog API summary: Load vended credentials for a table from the catalog operationId: loadCredentials parameters: - name: planId in: query required: false schema: type: string description: The plan ID that has been used for server-side scan planning - $ref: '#/components/parameters/referenced-by' description: Load vended credentials for a table from the catalog. responses: 200: $ref: '#/components/responses/LoadCredentialsResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, table to load credentials for does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToLoadDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /v1/{prefix}/tables/rename: parameters: - $ref: '#/components/parameters/prefix' post: tags: - Catalog API summary: Rename a table from its current name to a new name parameters: - $ref: '#/components/parameters/idempotency-key' 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 parameters: - $ref: '#/components/parameters/idempotency-key' requestBody: description: 'Commit updates to multiple tables in an atomic operation A commit for a single table consists of a table identifier with requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, `assert-ref-snapshot-id` will check that a named ref''s snapshot ID has a certain value. Server implementations are required to fail with a 400 status code if any unknown updates or requirements are received. Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.' content: application/json: schema: $ref: '#/components/schemas/CommitTransactionRequest' required: true responses: 204: description: Success, no content 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchTableException, table to load does not exist content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' examples: TableToUpdateDoesNotExist: $ref: '#/components/examples/NoSuchTableError' 409: description: Conflict - CommitFailedException, one or more requirements failed. The client may retry. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 500: description: An unknown server-side problem occurred; the commit state is unknown. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' example: error: message: Internal Server Error type: CommitStateUnknownException code: 500 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' - name: returnUuids in: query description: If true, include the `table-uuids` field in the response required: false schema: type: boolean default: false - name: returnProtectionStatus in: query description: If true, include the `protection-status` field in the response required: false schema: type: boolean default: false responses: 200: $ref: '#/components/responses/ListTablesResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - The namespace specified does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorModel' examples: NamespaceNotFound: $ref: '#/components/examples/NoSuchNamespaceError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' post: tags: - Catalog API summary: Create a view in the given namespace description: Create a view in the given namespace. operationId: createView requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateViewRequest' responses: 200: $ref: '#/components/responses/LoadViewResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - The namespace specified does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorModel' examples: NamespaceNotFound: $ref: '#/components/examples/NoSuchNamespaceError' 409: description: Conflict - The view already exists content: application/json: schema: $ref: '#/components/schemas/ErrorModel' examples: ViewAlreadyExists: $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=".' parameters: - $ref: '#/components/parameters/referenced-by' 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 parameters: - $ref: '#/components/parameters/idempotency-key' description: Commit updates to a view. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CommitViewRequest' responses: 200: $ref: '#/components/responses/LoadViewResponse' 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchViewException, view to load does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorModel' examples: ViewToUpdateDoesNotExist: $ref: '#/components/examples/NoSuchViewError' 409: description: Conflict - CommitFailedException. The client may retry. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 500: description: An unknown server-side problem occurred; the commit state is unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' example: error: message: Internal Server Error type: CommitStateUnknownException code: 500 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 parameters: - $ref: '#/components/parameters/idempotency-key' - name: force in: query description: If true, ignore `protection-status` when dropping. required: false 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 - 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 parameters: - $ref: '#/components/parameters/idempotency-key' requestBody: description: Current view identifier to rename and new view identifier to rename to content: application/json: schema: $ref: '#/components/schemas/RenameTableRequest' examples: RenameViewSameNamespace: $ref: '#/components/examples/RenameViewSameNamespace' required: true responses: 204: description: Success, no content 400: $ref: '#/components/responses/BadRequestErrorResponse' 401: $ref: '#/components/responses/UnauthorizedResponse' 403: $ref: '#/components/responses/ForbiddenResponse' 404: description: Not Found - NoSuchViewException, view to rename does not exist - NoSuchNamespaceException, The target namespace of the new identifier does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorModel' examples: ViewToRenameDoesNotExist: $ref: '#/components/examples/NoSuchViewError' NamespaceToRenameToDoesNotExist: $ref: '#/components/examples/NoSuchNamespaceError' 406: $ref: '#/components/responses/UnsupportedOperationResponse' 409: description: Conflict - The target identifier to rename to already exists as a table or view content: application/json: schema: $ref: '#/components/schemas/ErrorModel' example: $ref: '#/components/examples/ViewAlreadyExistsError' 419: $ref: '#/components/responses/AuthenticationTimeoutResponse' 503: $ref: '#/components/responses/ServiceUnavailableResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' components: parameters: etag: name: ETag in: header description: 'Identifies a unique version of the table metadata. Implementations that support ETags should produce unique tags for responses that return different metadata content but represent the same version of table metadata. For example, the `snapshots` query parameter may result in different metadata representations depending on whether `refs` or `all` is provided, therefore should have distinct ETags.' required: false schema: type: string plan-id: name: plan-id in: path description: ID used to track a planning request required: true schema: type: string namespace: name: namespace in: path required: true description: A namespace identifier as a single string. Multipart namespace parts must be separated by the namespace separator as indicated via the /config override `namespace-separator`, which defaults to the unit separator `0x1F` byte (url encoded `%1F`). To be compatible with older clients, servers must use both the advertised separator and `0x1F` as valid separators when decoding namespaces. The `namespace-separator` should be provided in a url encoded form. schema: type: string examples: singlepart_namespace: value: accounting multipart_namespace: value: accounting%1Ftax referenced-by: name: referenced-by in: query description: 'A comma-separated list of fully qualified view names (namespace and view name) representing the view reference chain when an entity (table or view) is loaded via a view. The list should be ordered with the outermost view first, followed by any intermediate views it references, down to the view that directly references the entity. For a simple case where a view directly references the entity, the list contains a single view identifier. For nested views (a view referencing another view which references the entity), the list contains multiple view identifiers representing the complete dependency chain. The view identifier is a composite string of the format {namespace}{separator}{viewName}. The namespace-separator (defined in /config) acts as the delimiter. When parsing, the last occurrence of this separator identifies the boundary between the namespace and the view name. Multipart namespaces must follow the encoding rules of the parent parameter in the list namespaces endpoint. Multiple view identifiers are separated by commas. Servers should split the parameter value on comma characters to parse individual view identifiers. If view names contain commas, they must be url-encoded as %2C. Example with multiple views (where prod%1Fanalytics is a nested namespace which has a quarterly_view which references to monthly_view which then references the entity being loaded) - prod%1Fanalytics%1Fquarterly_view,prod%1Fanalytics%1Fmonthly_view' required: false schema: type: string 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 page-token: name: pageToken in: query required: false schema: $ref: '#/components/schemas/PageToken' 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 prefix: name: prefix in: path schema: type: string required: true description: An optional prefix in the path idempotency-key: name: Idempotency-Key in: header required: false schema: type: string format: uuid minLength: 36 maxLength: 36 example: 017F22E2-79B0-7CC3-98C4-DC0C0C07398F description: "Optional client-provided idempotency key for safe request retries.\n\nWhen present, the server ensures no additional effects for requests that carry the same\nIdempotency-Key. If a prior request with this key has been finalized, the server returns\nan equivalent final response without re-running the operation. The response body may\nreflect a newer state of the catalog than existed at the time of the commit.\n\nFinalization rules:\n- Finalize & replay: 200, 201, 204, and deterministic terminal 4xx (including 409\n such as AlreadyExists, NamespaceNotEmpty, etc.)\n- Do not finalize (not stored/replayed): 5xx\n\nKey Requirements:\n- Key format: UUIDv7 in string form (RFC 9562).\n- The idempotency key must be globally unique (no reuse across different operations).\n- Catalogs SHOULD NOT expire keys before the end of the advertised token lifetime.\n- If Idempotency-Key is used, clients MUST reuse the same key when retrying the same\n logical operation and MUST generate a new key for a different operation.\n" table: name: table in: path description: A table name required: true schema: type: string example: sales schemas: 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 Expression: oneOf: - $ref: '#/components/schemas/TrueExpression' - $ref: '#/components/schemas/FalseExpression' - $ref: '#/components/schemas/AndOrExpression' - $ref: '#/components/schemas/NotExpression' - $ref: '#/components/schemas/SetExpression' - $ref: '#/components/schemas/LiteralExpression' - $ref: '#/components/schemas/UnaryExpression' 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' TransformTerm: type: object required: - type - transform - term properties: type: type: string const: transform transform: $ref: '#/components/schemas/Transform' term: $ref: '#/components/schemas/Reference' CompletedPlanningWithIDResult: type: object allOf: - $ref: '#/components/schemas/CompletedPlanningResult' - type: object required: - plan-id properties: plan-id: description: ID used to track a planning request type: string SetCurrentSchemaUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - schema-id properties: action: type: string const: set-current-schema schema-id: type: integer description: Schema ID to set as current, or -1 to set last added schema FixedTypeValue: type: string description: Fixed length type values are stored and serialized as an uppercase hexadecimal string preserving the fixed length example: 78797A SetDefaultSortOrderUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - sort-order-id properties: action: type: string const: set-default-sort-order sort-order-id: type: integer description: Sort order ID to set as the default, or -1 to set last added sort order MapType: type: object required: - type - key-id - key - value-id - value - value-required properties: type: type: string const: map key-id: type: integer key: $ref: '#/components/schemas/Type' value-id: type: integer value: $ref: '#/components/schemas/Type' value-required: type: boolean 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 SetSnapshotRefUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' - $ref: '#/components/schemas/SnapshotReference' required: - ref-name properties: action: type: string const: set-snapshot-ref ref-name: type: string AssertViewUUID: description: The view UUID must match the requirement's `uuid` required: - type - uuid properties: type: type: string const: assert-view-uuid uuid: type: string BaseUpdate: discriminator: propertyName: action mapping: assign-uuid: '#/components/schemas/AssignUUIDUpdate' upgrade-format-version: '#/components/schemas/UpgradeFormatVersionUpdate' add-schema: '#/components/schemas/AddSchemaUpdate' set-current-schema: '#/components/schemas/SetCurrentSchemaUpdate' add-spec: '#/components/schemas/AddPartitionSpecUpdate' set-default-spec: '#/components/schemas/SetDefaultSpecUpdate' add-sort-order: '#/components/schemas/AddSortOrderUpdate' set-default-sort-order: '#/components/schemas/SetDefaultSortOrderUpdate' add-snapshot: '#/components/schemas/AddSnapshotUpdate' set-snapshot-ref: '#/components/schemas/SetSnapshotRefUpdate' remove-snapshots: '#/components/schemas/RemoveSnapshotsUpdate' remove-snapshot-ref: '#/components/schemas/RemoveSnapshotRefUpdate' set-location: '#/components/schemas/SetLocationUpdate' set-properties: '#/components/schemas/SetPropertiesUpdate' remove-properties: '#/components/schemas/RemovePropertiesUpdate' add-view-version: '#/components/schemas/AddViewVersionUpdate' set-current-view-version: '#/components/schemas/SetCurrentViewVersionUpdate' set-statistics: '#/components/schemas/SetStatisticsUpdate' remove-statistics: '#/components/schemas/RemoveStatisticsUpdate' set-partition-statistics: '#/components/schemas/SetPartitionStatisticsUpdate' remove-partition-statistics: '#/components/schemas/RemovePartitionStatisticsUpdate' remove-partition-specs: '#/components/schemas/RemovePartitionSpecsUpdate' remove-schemas: '#/components/schemas/RemoveSchemasUpdate' add-encryption-key: '#/components/schemas/AddEncryptionKeyUpdate' remove-encryption-key: '#/components/schemas/RemoveEncryptionKeyUpdate' type: object required: - action properties: action: type: string EqualityDeleteFile: allOf: - $ref: '#/components/schemas/ContentFile' required: - content properties: content: type: string const: equality-deletes equality-ids: type: array items: type: integer description: List of equality field IDs RemoveStatisticsUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - snapshot-id properties: action: type: string const: remove-statistics snapshot-id: type: integer format: int64 Term: oneOf: - $ref: '#/components/schemas/Reference' - $ref: '#/components/schemas/TransformTerm' StructField: type: object required: - id - name - type - required properties: id: type: integer name: type: string type: $ref: '#/components/schemas/Type' required: type: boolean doc: type: string initial-default: $ref: '#/components/schemas/PrimitiveTypeValue' write-default: $ref: '#/components/schemas/PrimitiveTypeValue' EmptyPlanningResult: type: object description: Empty server-side planning result required: - status properties: status: $ref: '#/components/schemas/PlanStatus' enum: - submitted - cancelled LongTypeValue: type: integer format: int64 example: 9223372036854775807 NotExpression: type: object required: - type - child properties: type: $ref: '#/components/schemas/ExpressionType' const: not child: $ref: '#/components/schemas/Expression' 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 FieldName: description: 'A full field name (including parent field names), such as those passed in APIs like Java `Schema#findField(String name)`. The nested field name follows these rules - Nested struct fields are named by concatenating field names at each struct level using dot (`.`) delimiter, e.g. employer.contact_info.address.zip_code - Nested fields in a map key are named using the keyword `key`, e.g. employee_address_map.key.first_name - Nested fields in a map value are named using the keyword `value`, e.g. employee_address_map.value.zip_code - Nested fields in a list are named using the keyword `element`, e.g. employees.element.first_name' type: string SnapshotLog: type: array items: type: object required: - snapshot-id - timestamp-ms properties: snapshot-id: type: integer format: int64 timestamp-ms: type: integer format: int64 TableIdentifier: type: object required: - namespace - name properties: namespace: $ref: '#/components/schemas/Namespace' name: type: string nullable: false 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' 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: {} FileFormat: type: string enum: - avro - orc - parquet - puffin 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 first-row-id: type: integer format: int64 description: The first _row_id assigned to the first row in the first data file in the first manifest added-rows: type: integer format: int64 description: The upper bound of the number of rows with assigned row IDs summary: type: object required: - operation properties: operation: type: string enum: - append - replace - overwrite - delete additionalProperties: type: string schema-id: type: integer PrimitiveType: type: string example: - long - string - fixed[16] - decimal(10,2) DataFile: allOf: - $ref: '#/components/schemas/ContentFile' type: object required: - content properties: content: type: string const: data first-row-id: type: integer format: int64 description: The first row ID assigned to the first row in the data file 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 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 RemoveEncryptionKeyUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - key-id properties: action: type: string const: remove-encryption-key key-id: type: string PositionDeleteFile: allOf: - $ref: '#/components/schemas/ContentFile' required: - content properties: content: type: string const: position-deletes content-offset: type: integer format: int64 description: Offset within the delete file of delete content content-size-in-bytes: type: integer format: int64 description: Length, in bytes, of the delete content; required if content-offset is present SetPropertiesUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - updates properties: action: type: string const: set-properties updates: type: object additionalProperties: type: string NullOrder: type: string enum: - nulls-first - nulls-last SnapshotReferences: type: object additionalProperties: $ref: '#/components/schemas/SnapshotReference' 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 TrueExpression: type: object required: - type properties: type: $ref: '#/components/schemas/ExpressionType' const: 'true' TableMetadata: type: object required: - format-version - table-uuid properties: format-version: type: integer minimum: 1 maximum: 3 table-uuid: type: string location: type: string last-updated-ms: type: integer format: int64 next-row-id: type: integer format: int64 description: A long higher than all assigned row IDs; the next snapshot's first-row-id. properties: type: object additionalProperties: type: string schemas: type: array items: $ref: '#/components/schemas/Schema' current-schema-id: type: integer last-column-id: type: integer partition-specs: type: array items: $ref: '#/components/schemas/PartitionSpec' default-spec-id: type: integer last-partition-id: type: integer sort-orders: type: array items: $ref: '#/components/schemas/SortOrder' default-sort-order-id: type: integer encryption-keys: type: array items: $ref: '#/components/schemas/EncryptedKey' snapshots: type: array items: $ref: '#/components/schemas/Snapshot' refs: $ref: '#/components/schemas/SnapshotReferences' current-snapshot-id: type: integer format: int64 last-sequence-number: type: integer format: int64 snapshot-log: $ref: '#/components/schemas/SnapshotLog' metadata-log: $ref: '#/components/schemas/MetadataLog' statistics: type: array items: $ref: '#/components/schemas/StatisticsFile' partition-statistics: type: array items: $ref: '#/components/schemas/PartitionStatisticsFile' ScanTasks: type: object description: 'Scan and planning tasks for server-side scan planning - `plan-tasks` contains opaque units of planning work - `file-scan-tasks` contains a partial or complete list of table scan tasks - `delete-files` contains delete files referenced by file scan tasks Each plan task must be passed to the fetchScanTasks endpoint to fetch the file scan tasks for the plan task. The list of delete files must contain all delete files referenced by the file scan tasks. ' properties: delete-files: description: Delete files referenced by file scan tasks type: array items: $ref: '#/components/schemas/DeleteFile' file-scan-tasks: type: array items: $ref: '#/components/schemas/FileScanTask' plan-tasks: type: array items: $ref: '#/components/schemas/PlanTask' PlanTableScanRequest: type: object properties: snapshot-id: description: Identifier for the snapshot to scan in a point-in-time scan type: integer format: int64 select: description: List of selected schema fields type: array items: $ref: '#/components/schemas/FieldName' filter: description: Expression used to filter the table data $ref: '#/components/schemas/Expression' min-rows-requested: description: The minimum number of rows requested for the scan. This is used as a hint to the server to not have to return more rows than necessary. It is not required for the server to return that many rows since the scan may not produce that many rows. The server can also return more rows than requested. type: integer format: int64 case-sensitive: description: Enables case sensitive field matching for filter and select type: boolean default: true use-snapshot-schema: description: 'Whether to use the schema at the time the snapshot was written. When time travelling, the snapshot schema should be used (true). When scanning a branch, the table schema should be used (false).' type: boolean default: false start-snapshot-id: description: Starting snapshot ID for an incremental scan (exclusive) type: integer format: int64 end-snapshot-id: description: 'Ending snapshot ID for an incremental scan (inclusive). Required when start-snapshot-id is specified.' type: integer format: int64 stats-fields: description: List of fields for which the service should send column stats. type: array items: $ref: '#/components/schemas/FieldName' CounterResult: type: object required: - unit - value properties: unit: type: string value: type: integer format: int64 RemoveSnapshotRefUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - ref-name properties: action: type: string const: remove-snapshot-ref ref-name: type: string AssignUUIDUpdate: description: Assigning a UUID to a table/view should only be done when creating the table/view. It is not safe to re-assign the UUID if a table/view already has a UUID assigned allOf: - $ref: '#/components/schemas/BaseUpdate' required: - uuid properties: action: type: string const: assign-uuid uuid: type: string CommitTransactionRequest: type: object required: - table-changes properties: table-changes: type: array items: description: Table commit request; must provide an `identifier` $ref: '#/components/schemas/CommitTableRequest' 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: $ref: '#/components/schemas/PrimitiveTypeValue' 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 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 SortDirection: type: string enum: - asc - desc ExpressionType: type: string example: - 'true' - 'false' - eq - and - or - not - in - not-in - lt - lt-eq - gt - gt-eq - not-eq - starts-with - not-starts-with - is-null - not-null - is-nan - not-nan FetchPlanningResult: type: object description: Result of server-side scan planning for fetchPlanningResult discriminator: propertyName: status mapping: completed: '#/components/schemas/CompletedPlanningResult' submitted: '#/components/schemas/EmptyPlanningResult' cancelled: '#/components/schemas/EmptyPlanningResult' failed: '#/components/schemas/FailedPlanningResult' oneOf: - $ref: '#/components/schemas/CompletedPlanningResult' - $ref: '#/components/schemas/FailedPlanningResult' - $ref: '#/components/schemas/EmptyPlanningResult' 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' LoadTableResult: description: "Result used when a table is successfully loaded.\n\nThe 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.\nClients can check whether metadata has changed by comparing metadata locations after the table has been created.\n\nThe `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.\n\nThe following configurations should be respected by clients:\n\n## General Configurations\n\n- `token`: Authorization bearer token to use for table requests if OAuth2 security is enabled\n- `scan-planning-mode`: Communicates to clients the supported planning mode. Clients should use this value to fail fast if the supported scanning mode is not available on the client. Valid values:\n - `client`: Clients MUST use client-side scan planning\n - `server`: Clients MUST use server-side scan planning via the `planTableScan` endpoint\n\n## AWS Configurations\n\nThe following configurations should be respected when working with tables stored in AWS S3\n - `client.region`: region to configure client for making requests to AWS\n - `s3.access-key-id`: id for credentials that provide access to the data in S3\n - `s3.secret-access-key`: secret for credentials that provide access to data in S3\n - `s3.session-token`: if present, this value should be used for as the session token\n - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification\n - `s3.cross-region-access-enabled`: if `true`, S3 Cross-Region bucket access is enabled\n\n## Storage Credentials\n\nCredentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field.\nClients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.\n" type: object required: - metadata properties: metadata-location: type: string description: May be null if the table is staged as part of a transaction nullable: true metadata: $ref: '#/components/schemas/TableMetadata' config: type: object additionalProperties: type: string storage-credentials: type: array items: $ref: '#/components/schemas/StorageCredential' SetDefaultSpecUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - spec-id properties: action: type: string const: set-default-spec spec-id: type: integer description: Partition spec ID to set as the default, or -1 to set last added spec AddPartitionSpecUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - spec properties: action: type: string const: add-spec spec: $ref: '#/components/schemas/PartitionSpec' StringTypeValue: type: string example: hello TimeTypeValue: type: string description: Time type values follow the 'HH:MM:SS.ssssss' ISO-8601 format with microsecond precision example: '22:31:08.123456' 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' 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 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' 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 ListNamespacesResponse: type: object properties: next-page-token: $ref: '#/components/schemas/PageToken' namespaces: type: array uniqueItems: true items: $ref: '#/components/schemas/Namespace' namespace-uuids: type: array uniqueItems: true nullable: true items: type: string protection-status: type: array nullable: true items: type: boolean AddEncryptionKeyUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - encryption-key properties: action: type: string const: add-encryption-key encryption-key: $ref: '#/components/schemas/EncryptedKey' SQLViewRepresentation: type: object required: - type - sql - dialect properties: type: type: string sql: type: string dialect: type: string 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 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' IntegerTypeValue: type: integer example: 42 BooleanTypeValue: type: boolean example: true SetStatisticsUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - statistics properties: action: type: string const: set-statistics snapshot-id: type: integer format: int64 deprecated: true description: This optional field is **DEPRECATED for REMOVAL** since it contains redundant information. Clients should use the `statistics.snapshot-id` field instead. statistics: $ref: '#/components/schemas/StatisticsFile' StorageCredential: type: object required: - prefix - config properties: prefix: type: string description: Indicates a storage location prefix where the credential is relevant. Clients should choose the most specific prefix (by selecting the longest prefix) if several credentials of the same type are available. config: type: object additionalProperties: type: string 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 AddSortOrderUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - sort-order properties: action: type: string const: add-sort-order sort-order: $ref: '#/components/schemas/SortOrder' FloatTypeValue: type: number format: float example: 3.14 PageToken: description: 'An opaque token that allows clients to make use of pagination for list APIs (e.g. ListTables). Clients may initiate the first paginated request by sending an empty query parameter `pageToken` to the server. Servers that support pagination should identify the `pageToken` parameter and return a `next-page-token` in the response if there are more results available. After the initial request, the value of `next-page-token` from each response must be used as the `pageToken` parameter value for the next request. The server must return `null` value for the `next-page-token` in the last response. Servers that support pagination must return all results in a single response with the value of `next-page-token` set to `null` if the query parameter `pageToken` is not set in the request. Servers that do not support pagination should ignore the `pageToken` parameter and return all results in a single response. The `next-page-token` must be omitted from the response. Clients must interpret either `null` or missing response value of `next-page-token` as the end of the listing results.' type: string nullable: true PlanTask: description: An opaque string provided by the REST server that represents a unit of work to produce file scan tasks for scan planning. This allows clients to fetch tasks across multiple requests to accommodate large result sets. 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 ViewRepresentation: oneOf: - $ref: '#/components/schemas/SQLViewRepresentation' 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 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 UpgradeFormatVersionUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - format-version properties: action: type: string const: upgrade-format-version format-version: type: integer EncryptedKey: type: object required: - key-id - encrypted-key-metadata properties: key-id: type: string encrypted-key-metadata: type: string format: byte contentEncoding: base64 encrypted-by-id: type: string properties: type: object additionalProperties: type: string FetchScanTasksRequest: type: object required: - plan-task properties: plan-task: $ref: '#/components/schemas/PlanTask' PartitionSpec: type: object required: - fields properties: spec-id: type: integer readOnly: true fields: type: array items: $ref: '#/components/schemas/PartitionField' Schema: allOf: - $ref: '#/components/schemas/StructType' - type: object properties: schema-id: type: integer readOnly: true identifier-field-ids: type: array items: type: integer BinaryTypeValue: type: string description: Binary type values are stored and serialized as an uppercase hexadecimal string example: 78797A 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' MetadataLog: type: array items: type: object required: - metadata-file - timestamp-ms properties: metadata-file: type: string timestamp-ms: type: integer format: int64 FileScanTask: type: object required: - data-file properties: data-file: $ref: '#/components/schemas/DataFile' delete-file-references: description: A list of indices in the delete files array (0-based) type: array items: type: integer residual-filter: description: 'An optional filter to be applied to rows in this file scan task. If the residual is not present, the client must produce the residual or use the original filter.' allOf: - $ref: '#/components/schemas/Expression' DeleteFile: discriminator: propertyName: content mapping: position-deletes: '#/components/schemas/PositionDeleteFile' equality-deletes: '#/components/schemas/EqualityDeleteFile' oneOf: - $ref: '#/components/schemas/PositionDeleteFile' - $ref: '#/components/schemas/EqualityDeleteFile' Namespace: description: Reference to one or more levels of a namespace type: array items: type: string example: - accounting - tax 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' TableUpdate: anyOf: - $ref: '#/components/schemas/AssignUUIDUpdate' - $ref: '#/components/schemas/UpgradeFormatVersionUpdate' - $ref: '#/components/schemas/AddSchemaUpdate' - $ref: '#/components/schemas/SetCurrentSchemaUpdate' - $ref: '#/components/schemas/AddPartitionSpecUpdate' - $ref: '#/components/schemas/SetDefaultSpecUpdate' - $ref: '#/components/schemas/AddSortOrderUpdate' - $ref: '#/components/schemas/SetDefaultSortOrderUpdate' - $ref: '#/components/schemas/AddSnapshotUpdate' - $ref: '#/components/schemas/SetSnapshotRefUpdate' - $ref: '#/components/schemas/RemoveSnapshotsUpdate' - $ref: '#/components/schemas/RemoveSnapshotRefUpdate' - $ref: '#/components/schemas/SetLocationUpdate' - $ref: '#/components/schemas/SetPropertiesUpdate' - $ref: '#/components/schemas/RemovePropertiesUpdate' - $ref: '#/components/schemas/SetStatisticsUpdate' - $ref: '#/components/schemas/RemoveStatisticsUpdate' - $ref: '#/components/schemas/RemovePartitionSpecsUpdate' - $ref: '#/components/schemas/RemoveSchemasUpdate' - $ref: '#/components/schemas/AddEncryptionKeyUpdate' - $ref: '#/components/schemas/RemoveEncryptionKeyUpdate' 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' RenameTableRequest: type: object required: - source - destination properties: source: $ref: '#/components/schemas/TableIdentifier' destination: $ref: '#/components/schemas/TableIdentifier' LoadCredentialsResponse: type: object required: - storage-credentials properties: storage-credentials: type: array items: $ref: '#/components/schemas/StorageCredential' SetCurrentViewVersionUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - view-version-id properties: action: type: string const: set-current-view-version view-version-id: type: integer description: The view version id to set as current, or -1 to set last added view version id Type: oneOf: - $ref: '#/components/schemas/PrimitiveType' - $ref: '#/components/schemas/StructType' - $ref: '#/components/schemas/ListType' - $ref: '#/components/schemas/MapType' AsyncPlanningResult: type: object required: - status - plan-id properties: status: $ref: '#/components/schemas/PlanStatus' const: submitted plan-id: description: ID used to track a planning request type: string ViewRequirement: type: object discriminator: propertyName: type mapping: assert-view-uuid: '#/components/schemas/AssertViewUUID' oneOf: - $ref: '#/components/schemas/AssertViewUUID' Transform: type: string example: - identity - year - month - day - hour - bucket[256] - truncate[16] ViewHistoryEntry: type: object required: - version-id - timestamp-ms properties: version-id: type: integer timestamp-ms: type: integer format: int64 ListTablesResponse: type: object properties: next-page-token: $ref: '#/components/schemas/PageToken' identifiers: type: array uniqueItems: true items: $ref: '#/components/schemas/TableIdentifier' table-uuids: type: array uniqueItems: true nullable: true items: type: string protection-status: type: array nullable: true items: type: boolean Reference: type: string example: - column-name ContentFile: discriminator: propertyName: content mapping: data: '#/components/schemas/DataFile' position-deletes: '#/components/schemas/PositionDeleteFile' equality-deletes: '#/components/schemas/EqualityDeleteFile' type: object required: - spec-id - partition - 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 UnaryExpression: type: object required: - type - term properties: type: $ref: '#/components/schemas/ExpressionType' enum: - is-null - not-null - is-nan - not-nan term: $ref: '#/components/schemas/Term' AddSchemaUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - schema properties: action: type: string const: add-schema schema: $ref: '#/components/schemas/Schema' last-column-id: type: integer deprecated: true description: 'This optional field is **DEPRECATED for REMOVAL** since it more safe to handle this internally, and shouldn''t be exposed to the clients. The highest assigned column ID for the table. This is used to ensure columns are always assigned an unused ID when evolving schemas. When omitted, it will be computed on the server side.' RemovePartitionSpecsUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - spec-ids properties: action: type: string const: remove-partition-specs spec-ids: type: array items: type: integer 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' 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' BlobMetadata: type: object required: - type - snapshot-id - sequence-number - fields properties: type: type: string snapshot-id: type: integer format: int64 sequence-number: type: integer format: int64 fields: type: array items: type: integer properties: type: object additionalProperties: type: string StructType: type: object required: - type - fields properties: type: type: string const: struct fields: type: array items: $ref: '#/components/schemas/StructField' ReportMetricsRequest: anyOf: - $ref: '#/components/schemas/ScanReport' - $ref: '#/components/schemas/CommitReport' required: - report-type properties: report-type: type: string TableRequirement: type: object discriminator: propertyName: type mapping: assert-create: '#/components/schemas/AssertCreate' assert-table-uuid: '#/components/schemas/AssertTableUUID' assert-ref-snapshot-id: '#/components/schemas/AssertRefSnapshotId' assert-last-assigned-field-id: '#/components/schemas/AssertLastAssignedFieldId' assert-current-schema-id: '#/components/schemas/AssertCurrentSchemaId' assert-last-assigned-partition-id: '#/components/schemas/AssertLastAssignedPartitionId' assert-default-spec-id: '#/components/schemas/AssertDefaultSpecId' assert-default-sort-order-id: '#/components/schemas/AssertDefaultSortOrderId' properties: type: type: string required: - type FailedPlanningResult: type: object description: Failed server-side planning result allOf: - $ref: '#/components/schemas/IcebergErrorResponse' - type: object required: - status properties: status: $ref: '#/components/schemas/PlanStatus' const: failed MetricResult: anyOf: - $ref: '#/components/schemas/CounterResult' - $ref: '#/components/schemas/TimerResult' 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 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 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 SortOrder: type: object required: - order-id - fields properties: order-id: type: integer readOnly: true fields: type: array items: $ref: '#/components/schemas/SortField' DateTypeValue: type: string format: date description: Date type values follow the 'YYYY-MM-DD' ISO-8601 standard date format example: '2007-12-03' PlanStatus: description: Status of a server-side planning operation type: string enum: - completed - submitted - cancelled - failed AddSnapshotUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - snapshot properties: action: type: string const: add-snapshot snapshot: $ref: '#/components/schemas/Snapshot' RemoveSchemasUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - schema-ids properties: action: type: string const: remove-schemas schema-ids: type: array items: type: integer ListType: type: object required: - type - element-id - element - element-required properties: type: type: string const: list element-id: type: integer element: $ref: '#/components/schemas/Type' element-required: type: boolean FetchScanTasksResult: type: object description: Response schema for fetchScanTasks allOf: - $ref: '#/components/schemas/ScanTasks' RemovePropertiesUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - removals properties: action: type: string const: remove-properties removals: type: array items: type: string PlanTableScanResult: type: object description: Result of server-side scan planning for planTableScan discriminator: propertyName: status mapping: completed: '#/components/schemas/CompletedPlanningWithIDResult' submitted: '#/components/schemas/AsyncPlanningResult' cancelled: '#/components/schemas/EmptyPlanningResult' failed: '#/components/schemas/FailedPlanningResult' oneOf: - $ref: '#/components/schemas/CompletedPlanningWithIDResult' - $ref: '#/components/schemas/FailedPlanningResult' - $ref: '#/components/schemas/AsyncPlanningResult' - $ref: '#/components/schemas/EmptyPlanningResult' SetLocationUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - location properties: action: type: string const: set-location location: type: string RemoveSnapshotsUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - snapshot-ids properties: action: type: string const: remove-snapshots snapshot-ids: type: array items: type: integer format: int64 ViewVersion: type: object required: - version-id - timestamp-ms - schema-id - summary - representations - default-namespace properties: version-id: type: integer timestamp-ms: type: integer format: int64 schema-id: type: integer description: Schema ID to set as current, or -1 to set last added schema summary: type: object additionalProperties: type: string representations: type: array items: $ref: '#/components/schemas/ViewRepresentation' default-catalog: type: string default-namespace: $ref: '#/components/schemas/Namespace' AddViewVersionUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' required: - view-version properties: action: type: string const: add-view-version view-version: $ref: '#/components/schemas/ViewVersion' 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: $ref: '#/components/schemas/PrimitiveTypeValue' 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' FalseExpression: type: object required: - type properties: type: $ref: '#/components/schemas/ExpressionType' const: 'false' CompletedPlanningResult: type: object description: Completed server-side planning result allOf: - $ref: '#/components/schemas/ScanTasks' - type: object required: - status properties: status: $ref: '#/components/schemas/PlanStatus' const: completed storage-credentials: type: array description: 'Storage credentials for accessing the files returned in the scan result. If the server returns storage credentials as part of the completed scan planning response, the expectation is for the client to use these credentials to read the files returned in the FileScanTasks as part of the scan result.' items: $ref: '#/components/schemas/StorageCredential' CommitTableResponse: type: object required: - metadata-location - metadata properties: metadata-location: type: string metadata: $ref: '#/components/schemas/TableMetadata' 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' 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 namespace-uuid: type: string nullable: true RegisterTableRequest: type: object required: - name - metadata-location properties: name: type: string metadata-location: type: string overwrite: description: Whether to overwrite table metadata if the table already exists type: boolean default: false 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 responses: 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 UnauthorizedResponse: description: Unauthorized. The REST Catalog SHOULD respond with the 401 UnauthorizedResponse when the access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the request. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' example: error: message: Not authorized to make this request type: NotAuthorizedException code: 401 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' headers: etag: $ref: '#/components/parameters/etag' LoadTableResponse: description: Table metadata result when loading a table content: application/json: schema: $ref: '#/components/schemas/LoadTableResult' headers: etag: $ref: '#/components/parameters/etag' FetchScanTasksResponse: description: Result of retrieving additional plan tasks and file scan tasks. content: application/json: schema: $ref: '#/components/schemas/FetchScanTasksResult' 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 PlanTableScanResponse: description: Result of submitting a table scan to plan content: application/json: schema: $ref: '#/components/schemas/PlanTableScanResult' 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' LoadViewResponse: description: View metadata result when loading a view content: application/json: schema: $ref: '#/components/schemas/LoadViewResult' 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 CreateTableResponse: description: Table metadata result after creating a table content: application/json: schema: $ref: '#/components/schemas/LoadTableResult' headers: etag: $ref: '#/components/parameters/etag' 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' 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' FetchPlanningResultResponse: description: Result of fetching a submitted scan planning operation content: application/json: schema: $ref: '#/components/schemas/FetchPlanningResult' AuthenticationTimeoutResponse: description: This is an optional status response type that the REST Catalog can issue when the token has expired. The client MAY request a new access token and retry the request. 401 UnauthorizedResponse SHOULD be preferred over this response type on token expiry. content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' example: error: message: Credentials have timed out type: AuthenticationTimeoutException code: 419 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' 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 LoadCredentialsResponse: description: Table credentials result when loading credentials for a table content: application/json: schema: $ref: '#/components/schemas/LoadCredentialsResponse' 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 ServiceUnavailableResponse: description: 'The service is not ready to handle the request, request could have been partially processed. The service may additionally send a Retry-After header to indicate when to retry, a non idempotent request should only be retried by the client when the Retry-After header is present.' content: application/json: schema: $ref: '#/components/schemas/IcebergErrorResponse' example: error: message: Slow down type: SlowDownException code: 503 examples: 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 NoSuchNamespaceError: summary: The requested namespace does not exist value: error: message: The given namespace does not exist type: NoSuchNamespaceException code: 404 NamespaceAlreadyExistsError: summary: The requested namespace already exists value: error: message: The given namespace already exists type: AlreadyExistsException code: 409 ListNamespacesNonEmptyExample: summary: A non-empty list of namespaces value: namespaces: - - accounting - tax - - accounting - credits ViewAlreadyExistsError: summary: The requested view identifier already exists value: error: message: The given view already exists type: AlreadyExistsException code: 409 ListNamespacesEmptyExample: summary: An empty list of namespaces value: namespaces: [] ListTablesEmptyExample: summary: An empty list for a namespace with no tables value: identifiers: [] RenameTableSameNamespace: summary: Rename a table in the same namespace value: source: namespace: - accounting - tax name: paid destination: namespace: - accounting - tax name: owed ListTablesNonEmptyExample: summary: A non-empty list of table identifiers value: identifiers: - namespace: - accounting - tax name: paid - namespace: - accounting - tax name: owed NoSuchViewError: summary: The requested view does not exist value: error: message: The given view does not exist type: NoSuchViewException code: 404 NoSuchPlanIdError: summary: The plan id does not exist value: error: message: The plan id does not exist type: NoSuchPlanIdException code: 404 RenameViewSameNamespace: summary: Rename a view in the same namespace value: source: namespace: - accounting - tax name: paid-view destination: namespace: - accounting - tax name: owed-view NoSuchPlanTaskError: summary: The plan task does not exist value: error: message: The plan task does not exist type: NoSuchPlanTaskException code: 404 NamespaceNotEmptyError: summary: The requested namespace is not empty value: error: message: The given namespace is not empty type: NamespaceNotEmptyException code: 409 NoSuchTableError: summary: The requested table does not exist value: error: message: The given table does not exist type: NoSuchTableException code: 404 TableAlreadyExistsError: summary: The requested table identifier already exists value: error: message: The given table already exists type: AlreadyExistsException code: 409 UpdateAndRemoveNamespacePropertiesRequest: summary: An update namespace properties request with both properties to remove and properties to upsert. value: removals: - foo - bar updates: owner: Raoul 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