This is an automated email from the ASF dual-hosted git repository.
yufei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 4f7cf97e Use upstream 1.7.1 rest-catalog-open-api.yaml instead. (#936)
4f7cf97e is described below
commit 4f7cf97e26c1c0053ac19924509a387134f20a1b
Author: Honah (Jonas) J. <[email protected]>
AuthorDate: Wed Feb 26 12:48:14 2025 -0600
Use upstream 1.7.1 rest-catalog-open-api.yaml instead. (#936)
---
LICENSE | 3 +-
regtests/README.md | 2 +-
...api.yaml => iceberg-rest-catalog-open-api.yaml} | 784 ++++++++++++++++-----
spec/polaris-catalog-apis/notifications-api.yaml | 26 +-
spec/polaris-catalog-apis/oauth-tokens-api.yaml | 282 ++++++++
spec/polaris-catalog-service.yaml | 49 +-
6 files changed, 926 insertions(+), 220 deletions(-)
diff --git a/LICENSE b/LICENSE
index 9d52f8ad..e9c023b3 100644
--- a/LICENSE
+++ b/LICENSE
@@ -215,7 +215,8 @@ License: https://www.apache.org/licenses/LICENSE-2.0
This product includes code from Apache Iceberg.
-* spec/rest-catalog-open-api.yaml
+* spec/iceberg-rest-catalog-open-api.yaml
+* spec/polaris-catalog-apis/oauth-tokens-api.yaml
*
integration-tests/src/main/java/org/apache/polaris/service/it/test/PolarisRestCatalogIntegrationTest.java
Copyright: Copyright 2017-2025 The Apache Software Foundation
diff --git a/regtests/README.md b/regtests/README.md
index 4c2d5c55..1fb1bbcd 100644
--- a/regtests/README.md
+++ b/regtests/README.md
@@ -186,7 +186,7 @@ docker run --rm \
# generate the iceberg rest client
docker run --rm \
-v ${PWD}:/local openapitools/openapi-generator-cli generate \
- -i /local/spec/rest-catalog-open-api.yaml \
+ -i /local/spec/polaris-catalog-service.yaml \
-g python \
-o /local/regtests/client/python
--additional-properties=packageName=polaris.catalog
--additional-properties=apiNameSuffix=""
--additional-properties=apiNamePrefix=Iceberg
```
diff --git a/spec/rest-catalog-open-api.yaml
b/spec/iceberg-rest-catalog-open-api.yaml
similarity index 87%
rename from spec/rest-catalog-open-api.yaml
rename to spec/iceberg-rest-catalog-open-api.yaml
index cfcd4987..b4adb6be 100644
--- a/spec/rest-catalog-open-api.yaml
+++ b/spec/iceberg-rest-catalog-open-api.yaml
@@ -17,6 +17,10 @@
# under the License.
#
+# CODE_COPIED_TO_POLARIS
+
+# Apache Iceberg Version: 1.7.1
+
---
openapi: 3.0.3
info:
@@ -221,12 +225,6 @@ paths:
Clients may also use the token exchange flow to refresh a token that
is about to expire by
sending a token exchange request (3). The request's "subject" token
should be the expiring
token. This request should use the subject token in the
"Authorization" header.
- parameters:
- - name: Authorization
- in: header
- schema:
- type: string
- required: false
requestBody:
required: true
content:
@@ -242,8 +240,6 @@ paths:
$ref: '#/components/responses/OAuthErrorResponse'
5XX:
$ref: '#/components/responses/OAuthErrorResponse'
- security:
- - BearerAuth: []
/v1/{prefix}/namespaces:
parameters:
@@ -601,6 +597,261 @@ paths:
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'
+ post:
+ tags:
+ - Catalog API
+ summary: Submit a scan for planning
+ description: >
+ Submits a scan for server-side planning.
+
+
+ Point-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.
+
+
+ Responses must include a valid status listed below. A "cancelled"
status is considered invalid for this endpoint.
+
+ - When "completed" the planning operation has produced plan tasks and
+ file scan tasks that must be returned in the response (not fetched
+ later by calling fetchPlanningResult)
+
+ - When "submitted" the response must include a plan-id used to poll
+ fetchPlanningResult to fetch the planning result when it is ready
+
+ - When "failed" the response must be a valid error response
+
+ The 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.
+
+
+ Responses that include a plan-id indicate that the service is holding
+ state or performing work for the client.
+
+
+ - Clients should use the plan-id to fetch results from
+ fetchPlanningResult when the response status is "submitted"
+
+ - Clients should inform the service if planning results are no longer
+ needed by calling cancelPlanning. Cancellation is not necessary after
+ fetchScanTasks has been used to fetch scan tasks for each plan task.
+ operationId: planTableScan
+ 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'
+
+ 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.
+
+
+ Responses must include a valid status
+
+ - When "completed" the planning operation has produced plan-tasks and
+ file-scan-tasks that must be returned in the response
+
+ - When "submitted" the planning operation has not completed; the client
+ should wait to call this endpoint again to fetch a completed response
+
+ - When "failed" the response must be a valid error response
+
+ - When "cancelled" the plan-id is invalid and should be discarded
+
+
+ The 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.
+ 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
+ description: >
+ Cancels scan planning for a plan-id.
+
+
+ This 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.
+
+
+ Cancellation is not necessary when
+
+ - Scan tasks for each plan task have been fetched using fetchScanTasks
+
+ - A plan-id has produced a "failed" or "cancelled" status from
+ planTableScan or fetchPlanningResult
+ 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, 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'
+ 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
+ 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'
@@ -694,7 +945,7 @@ paths:
required: false
schema:
type: string
- enum: [all, refs]
+ enum: [ all, refs ]
responses:
200:
$ref: '#/components/responses/LoadTableResponse'
@@ -1056,76 +1307,6 @@ paths:
5XX:
$ref: '#/components/responses/ServerErrorResponse'
- /v1/{prefix}/namespaces/{namespace}/tables/{table}/notifications:
- parameters:
- - $ref: '#/components/parameters/prefix'
- - $ref: '#/components/parameters/namespace'
- - $ref: '#/components/parameters/table'
-
- post:
- tags:
- - Catalog API
- summary: Sends a notification to the table
- operationId: sendNotification
- requestBody:
- description:
- The request containing the notification to be sent.
-
- For each table, Polaris will reject any notification where the
timestamp in the request body
- is older than or equal to the most recent time Polaris has already
processed for the table.
- The responsibility of ensuring the correct order of timestamps for a
sequence of notifications
- lies with the caller of the API. This includes managing potential
clock skew or inconsistencies
- when notifications are sent from multiple sources.
-
- A VALIDATE request behaves like a dry-run of a CREATE or UPDATE
request up to but not including
- loading the contents of a metadata file; this includes validations
of permissions, the specified
- metadata path being within ALLOWED_LOCATIONS, having an EXTERNAL
catalog, etc. The intended use
- case for a VALIDATE notification is to allow a remote catalog to
pre-validate the general
- settings of a receiving catalog against an intended new table
location before possibly creating
- a table intended for sending notifications in the remote catalog at
all. For a VALIDATE request,
- the specified metadata-location can either be a prospective full
metadata file path, or a
- relevant parent directory of the intended table to validate against
ALLOWED_LOCATIONS.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/NotificationRequest'
- required: true
- responses:
- 204:
- description: Success, no content
- 400:
- $ref: '#/components/responses/BadRequestErrorResponse'
- 401:
- $ref: '#/components/responses/UnauthorizedResponse'
- 403:
- $ref: '#/components/responses/ForbiddenResponse'
- 404:
- description:
- Not Found - NoSuchTableException, table to load does not exist
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/IcebergErrorResponse'
- examples:
- TableToLoadDoesNotExist:
- $ref: '#/components/examples/NoSuchTableError'
- 409:
- description:
- Conflict - The timestamp of the received notification is older
than or equal to the
- most recent timestamp Polaris has already processed for the
specified table.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/IcebergErrorResponse'
- example:
- $ref: '#/components/examples/OutOfOrderNotificationError'
- 419:
- $ref: '#/components/responses/AuthenticationTimeoutResponse'
- 503:
- $ref: '#/components/responses/ServiceUnavailableResponse'
- 5XX:
- $ref: '#/components/responses/ServerErrorResponse'
-
/v1/{prefix}/transactions/commit:
parameters:
- $ref: '#/components/parameters/prefix'
@@ -1634,6 +1815,14 @@ components:
type: string
example: "sales"
+ plan-id:
+ name: plan-id
+ in: path
+ description: ID used to track a planning request
+ required: true
+ schema:
+ type: string
+
view:
name: view
in: path
@@ -1762,8 +1951,8 @@ components:
properties:
type: object
description: Configured string to string map of properties for the
namespace
- example: {"owner": "Hank Bendickson"}
- default: {}
+ example: { "owner": "Hank Bendickson" }
+ default: { }
additionalProperties:
type: string
@@ -1775,10 +1964,10 @@ components:
uniqueItems: true
items:
type: string
- example: ["department", "access_group"]
+ example: [ "department", "access_group" ]
updates:
type: object
- example: {"owner": "Hank Bendickson"}
+ example: { "owner": "Hank Bendickson" }
additionalProperties:
type: string
@@ -1798,7 +1987,7 @@ components:
type: array
items:
type: string
- example: ["accounting", "tax"]
+ example: [ "accounting", "tax" ]
PageToken:
description:
@@ -2545,7 +2734,7 @@ components:
properties:
action:
type: string
- enum: ["set-default-spec"]
+ enum: [ "set-default-spec" ]
spec-id:
type: integer
description: Partition spec ID to set as the default, or -1 to set
last added spec
@@ -2559,7 +2748,7 @@ components:
properties:
action:
type: string
- enum: ["add-sort-order"]
+ enum: [ "add-sort-order" ]
sort-order:
$ref: '#/components/schemas/SortOrder'
@@ -2572,7 +2761,7 @@ components:
properties:
action:
type: string
- enum: ["set-default-sort-order"]
+ enum: [ "set-default-sort-order" ]
sort-order-id:
type: integer
description: Sort order ID to set as the default, or -1 to set last
added sort order
@@ -2586,7 +2775,7 @@ components:
properties:
action:
type: string
- enum: ["add-snapshot"]
+ enum: [ "add-snapshot" ]
snapshot:
$ref: '#/components/schemas/Snapshot'
@@ -2600,7 +2789,7 @@ components:
properties:
action:
type: string
- enum: ["set-snapshot-ref"]
+ enum: [ "set-snapshot-ref" ]
ref-name:
type: string
@@ -2613,7 +2802,7 @@ components:
properties:
action:
type: string
- enum: ["remove-snapshots"]
+ enum: [ "remove-snapshots" ]
snapshot-ids:
type: array
items:
@@ -2629,7 +2818,7 @@ components:
properties:
action:
type: string
- enum: ["remove-snapshot-ref"]
+ enum: [ "remove-snapshot-ref" ]
ref-name:
type: string
@@ -2642,7 +2831,7 @@ components:
properties:
action:
type: string
- enum: ["set-location"]
+ enum: [ "set-location" ]
location:
type: string
@@ -2655,7 +2844,7 @@ components:
properties:
action:
type: string
- enum: ["set-properties"]
+ enum: [ "set-properties" ]
updates:
type: object
additionalProperties:
@@ -2670,7 +2859,7 @@ components:
properties:
action:
type: string
- enum: ["remove-properties"]
+ enum: [ "remove-properties" ]
removals:
type: array
items:
@@ -2685,7 +2874,7 @@ components:
properties:
action:
type: string
- enum: ["add-view-version"]
+ enum: [ "add-view-version" ]
view-version:
$ref: '#/components/schemas/ViewVersion'
@@ -2698,7 +2887,7 @@ components:
properties:
action:
type: string
- enum: ["set-current-view-version"]
+ enum: [ "set-current-view-version" ]
view-version-id:
type: integer
description: The view version id to set as current, or -1 to set
last added view version id
@@ -2713,7 +2902,7 @@ components:
properties:
action:
type: string
- enum: ["set-statistics"]
+ enum: [ "set-statistics" ]
snapshot-id:
type: integer
format: int64
@@ -2729,7 +2918,7 @@ components:
properties:
action:
type: string
- enum: ["remove-statistics"]
+ enum: [ "remove-statistics" ]
snapshot-id:
type: integer
format: int64
@@ -2743,7 +2932,7 @@ components:
properties:
action:
type: string
- enum: ["set-partition-statistics"]
+ enum: [ "set-partition-statistics" ]
partition-statistics:
$ref: '#/components/schemas/PartitionStatisticsFile'
@@ -2756,7 +2945,7 @@ components:
properties:
action:
type: string
- enum: ["remove-partition-statistics"]
+ enum: [ "remove-partition-statistics" ]
snapshot-id:
type: integer
format: int64
@@ -2863,7 +3052,7 @@ components:
properties:
type:
type: string
- enum: ["assert-ref-snapshot-id"]
+ enum: [ "assert-ref-snapshot-id" ]
ref:
type: string
snapshot-id:
@@ -2879,7 +3068,7 @@ components:
properties:
type:
type: string
- enum: ["assert-last-assigned-field-id"]
+ enum: [ "assert-last-assigned-field-id" ]
last-assigned-field-id:
type: integer
@@ -2892,7 +3081,7 @@ components:
properties:
type:
type: string
- enum: ["assert-current-schema-id"]
+ enum: [ "assert-current-schema-id" ]
current-schema-id:
type: integer
@@ -2905,7 +3094,7 @@ components:
properties:
type:
type: string
- enum: ["assert-last-assigned-partition-id"]
+ enum: [ "assert-last-assigned-partition-id" ]
last-assigned-partition-id:
type: integer
@@ -2918,7 +3107,7 @@ components:
properties:
type:
type: string
- enum: ["assert-default-spec-id"]
+ enum: [ "assert-default-spec-id" ]
default-spec-id:
type: integer
@@ -2931,7 +3120,7 @@ components:
properties:
type:
type: string
- enum: ["assert-default-sort-order-id"]
+ enum: [ "assert-default-sort-order-id" ]
default-sort-order-id:
type: integer
@@ -2952,7 +3141,7 @@ components:
properties:
type:
type: string
- enum: ["assert-view-uuid"]
+ enum: [ "assert-view-uuid" ]
uuid:
type: string
@@ -3030,6 +3219,140 @@ components:
items:
$ref: '#/components/schemas/StorageCredential'
+ 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'
+
+ CompletedPlanningResult:
+ type: object
+ description: Completed server-side planning result
+ allOf:
+ - $ref: '#/components/schemas/ScanTasks'
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ $ref: '#/components/schemas/PlanStatus'
+ enum: ["completed"]
+
+ CompletedPlanningWithIDResult:
+ type: object
+ allOf:
+ - $ref: '#/components/schemas/CompletedPlanningResult'
+ - type: object
+ properties:
+ plan-id:
+ description: ID used to track a planning request
+ type: string
+
+ FailedPlanningResult:
+ type: object
+ description: Failed server-side planning result
+ allOf:
+ - $ref: '#/components/schemas/IcebergErrorResponse'
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ $ref: '#/components/schemas/PlanStatus'
+ enum: ["failed"]
+
+ AsyncPlanningResult:
+ type: object
+ required:
+ - status
+ properties:
+ status:
+ $ref: '#/components/schemas/PlanStatus'
+ enum: ["submitted"]
+ plan-id:
+ description: ID used to track a planning request
+ type: string
+
+ EmptyPlanningResult:
+ type: object
+ description: Empty server-side planning result
+ required:
+ - status
+ properties:
+ status:
+ $ref: '#/components/schemas/PlanStatus'
+ enum: ["submitted", "cancelled"]
+
+ PlanStatus:
+ description: Status of a server-side planning operation
+ type: string
+ enum: ["completed", "submitted", "cancelled", "failed"]
+
+ 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'
+
+ 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'
+
+ FetchScanTasksResult:
+ type: object
+ description: Response schema for fetchScanTasks
+ allOf:
+ - $ref: '#/components/schemas/ScanTasks'
+
CommitTableRequest:
type: object
required:
@@ -3147,7 +3470,6 @@ components:
## General Configurations
- `token`: Authorization bearer token to use for view requests if
OAuth2 security is enabled
-
type: object
required:
- metadata-location
@@ -3412,45 +3734,6 @@ components:
additionalProperties:
type: string
- NotificationRequest:
- required:
- - notification-type
- - payload
- properties:
- notification-type:
- $ref: '#/components/schemas/NotificationType'
- payload:
- $ref: '#/components/schemas/TableUpdateNotification'
-
- NotificationType:
- type: string
- enum:
- - UNKNOWN
- - CREATE
- - UPDATE
- - DROP
- - VALIDATE
-
- TableUpdateNotification:
- type: object
- required:
- - table-name
- - timestamp
- - table-uuid
- - metadata-location
- properties:
- table-name:
- type: string
- timestamp:
- type: integer
- format: int64
- table-uuid:
- type: string
- metadata-location:
- type: string
- metadata:
- $ref: '#/components/schemas/TableMetadata'
-
OAuthError:
deprecated: true
description:
@@ -3543,8 +3826,8 @@ components:
type: string
description:
Properties stored on the namespace, if supported by the server.
- example: {"owner": "Ralph", "created_at": "1452120468"}
- default: {}
+ example: { "owner": "Ralph", "created_at": "1452120468" }
+ default: { }
GetNamespaceResponse:
type: object
@@ -3561,8 +3844,8 @@ components:
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: {}
+ example: { "owner": "Ralph", 'transient_lastDdlTime': '1452120468' }
+ default: { }
nullable: true
ListTablesResponse:
@@ -3805,8 +4088,8 @@ components:
description: "List of Long values, matched to 'keys' by index"
example:
{
- "keys": [1, 2],
- "values": [100,200]
+ "keys": [ 1, 2 ],
+ "values": [ 100,200 ]
}
ValueMap:
@@ -3824,8 +4107,8 @@ components:
description: "List of primitive type values, matched to 'keys' by
index"
example:
{
- "keys": [1, 2],
- "values": [100, "test"]
+ "keys": [ 1, 2 ],
+ "values": [ 100, "test" ]
}
PrimitiveTypeValue:
@@ -3917,7 +4200,7 @@ components:
properties:
content:
type: string
- enum: ["data"]
+ enum: [ "data" ]
column-sizes:
allOf:
- $ref: '#/components/schemas/CountMap'
@@ -3961,7 +4244,7 @@ components:
properties:
content:
type: string
- enum: ["position-deletes"]
+ enum: [ "position-deletes" ]
EqualityDeleteFile:
allOf:
@@ -3971,13 +4254,113 @@ components:
properties:
content:
type: string
- enum: ["equality-deletes"]
+ enum: [ "equality-deletes" ]
equality-ids:
type: array
items:
type: integer
description: "List of equality field IDs"
+ 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'
+ 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'
+
+ 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
+
+ FetchScanTasksRequest:
+ type: object
+ required:
+ - plan-task
+ properties:
+ plan-task:
+ $ref: '#/components/schemas/PlanTask'
+
+ 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
+
+ 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'
+
#############################
# Reusable Response Objects #
#############################
@@ -4075,7 +4458,7 @@ components:
"message": "The server does not support this operation",
"type": "UnsupportedOperationException",
"code": 406
- }}
+ } }
CreateNamespaceResponse:
description:
@@ -4089,7 +4472,7 @@ components:
$ref: '#/components/schemas/CreateNamespaceResponse'
example: {
"namespace": ["accounting", "tax"],
- "properties": {"owner": "Ralph", "created_at": "1452120468"}
+ "properties": { "owner": "Ralph", "created_at": "1452120468" }
}
GetNamespaceResponse:
@@ -4182,9 +4565,9 @@ components:
schema:
$ref: '#/components/schemas/UpdateNamespacePropertiesResponse'
example: {
- "updated": ["owner"],
- "removed": ["foo"],
- "missing": ["bar"]
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
}
CreateTableResponse:
@@ -4194,6 +4577,27 @@ components:
schema:
$ref: '#/components/schemas/LoadTableResult'
+ PlanTableScanResponse:
+ description: Result of submitting a table scan to plan
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PlanTableScanResult'
+
+ FetchPlanningResultResponse:
+ description: Result of fetching a submitted scan planning operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/FetchPlanningResult'
+
+ FetchScanTasksResponse:
+ description: Result of retrieving additional plan tasks and file scan
tasks.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/FetchScanTasksResult'
+
LoadTableResponse:
description: Table metadata result when loading a table
content:
@@ -4233,13 +4637,13 @@ components:
ListTablesEmptyExample:
summary: An empty list for a namespace with no tables
value: {
- "identifiers": []
+ "identifiers": [ ]
}
ListNamespacesEmptyExample:
summary: An empty list of namespaces
value: {
- "namespaces": []
+ "namespaces": [ ]
}
ListNamespacesNonEmptyExample:
@@ -4255,8 +4659,8 @@ components:
summary: A non-empty list of table identifiers
value: {
"identifiers": [
- {"namespace": ["accounting", "tax"], "name": "paid"},
- {"namespace": ["accounting", "tax"], "name": "owed"}
+ { "namespace": ["accounting", "tax"], "name": "paid" },
+ { "namespace": ["accounting", "tax"], "name": "owed" }
]
}
@@ -4265,7 +4669,7 @@ components:
value: "accounting%1Ftax"
NamespaceAsPathVariable:
- summary: A single part namespace, as represented in a path parameter
+ summary: A single part namespace, as represented in a path paremeter
value: "accounting"
NamespaceAlreadyExistsError:
@@ -4278,6 +4682,26 @@ components:
}
}
+ NoSuchPlanIdError:
+ summary: The plan id does not exist
+ value: {
+ "error": {
+ "message": "The plan id does not exist",
+ "type": "NoSuchPlanIdException",
+ "code": 404
+ }
+ }
+
+ NoSuchPlanTaskError:
+ summary: The plan task does not exist
+ value: {
+ "error": {
+ "message": "The plan task does not exist",
+ "type": "NoSuchPlanTaskException",
+ "code": 404
+ }
+ }
+
NoSuchTableError:
summary: The requested table does not exist
value: {
@@ -4311,15 +4735,15 @@ components:
RenameTableSameNamespace:
summary: Rename a table in the same namespace
value: {
- "source": {"namespace": ["accounting", "tax"], "name": "paid"},
- "destination": {"namespace": ["accounting", "tax"], "name": "owed"}
+ "source": { "namespace": ["accounting", "tax"], "name": "paid" },
+ "destination": { "namespace": ["accounting", "tax"], "name": "owed" }
}
RenameViewSameNamespace:
summary: Rename a view in the same namespace
value: {
- "source": {"namespace": ["accounting", "tax"], "name": "paid-view"},
- "destination": {"namespace": ["accounting", "tax"], "name":
"owed-view"}
+ "source": { "namespace": [ "accounting", "tax" ], "name": "paid-view"
},
+ "destination": { "namespace": [ "accounting", "tax" ], "name":
"owed-view" }
}
TableAlreadyExistsError:
@@ -4358,20 +4782,8 @@ components:
UpdateAndRemoveNamespacePropertiesRequest:
summary: An update namespace properties request with both properties to
remove and properties to upsert.
value: {
- "removals": ["foo", "bar"],
- "updates": {"owner": "Raoul"}
- }
-
- OutOfOrderNotificationError:
- summary:
- The timestamp of the received notification is older than or equal to
the most recent timestamp
- Polaris has already processed for the specified table.
- value: {
- "error": {
- "message": "A notification with a newer timestamp has been admitted
for table",
- "type": "AlreadyExistsException",
- "code": 409
- }
+ "removals": [ "foo", "bar" ],
+ "updates": { "owner": "Raoul" }
}
securitySchemes:
diff --git a/spec/polaris-catalog-apis/notifications-api.yaml
b/spec/polaris-catalog-apis/notifications-api.yaml
index aa11ab32..ec40bfc0 100644
--- a/spec/polaris-catalog-apis/notifications-api.yaml
+++ b/spec/polaris-catalog-apis/notifications-api.yaml
@@ -21,9 +21,9 @@
paths:
/v1/{prefix}/namespaces/{namespace}/tables/{table}/notifications:
parameters:
- - $ref: '../rest-catalog-open-api.yaml#/components/parameters/prefix'
- - $ref: '../rest-catalog-open-api.yaml#/components/parameters/namespace'
- - $ref: '../rest-catalog-open-api.yaml#/components/parameters/table'
+ - $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+ - $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/parameters/namespace'
+ - $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/parameters/table'
post:
tags:
@@ -57,21 +57,21 @@ paths:
204:
description: Success, no content
400:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
401:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
403:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
404:
description:
Not Found - NoSuchTableException, table to load does not exist
content:
application/json:
schema:
- $ref:
'../rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
examples:
TableToLoadDoesNotExist:
- $ref:
'../rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
409:
description:
Conflict - The timestamp of the received notification is older
than or equal to the
@@ -79,15 +79,15 @@ paths:
content:
application/json:
schema:
- $ref:
'../rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
example:
$ref: '#/components/examples/OutOfOrderNotificationError'
419:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/AuthenticationTimeoutResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/AuthenticationTimeoutResponse'
503:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
5XX:
- $ref:
'../rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
components:
schemas:
@@ -128,7 +128,7 @@ components:
metadata-location:
type: string
metadata:
- $ref:
'../rest-catalog-open-api.yaml#/components/schemas/TableMetadata'
+ $ref:
'../iceberg-rest-catalog-open-api.yaml#/components/schemas/TableMetadata'
examples:
OutOfOrderNotificationError:
diff --git a/spec/polaris-catalog-apis/oauth-tokens-api.yaml
b/spec/polaris-catalog-apis/oauth-tokens-api.yaml
new file mode 100644
index 00000000..a57f8607
--- /dev/null
+++ b/spec/polaris-catalog-apis/oauth-tokens-api.yaml
@@ -0,0 +1,282 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# CODE_COPIED_TO_POLARIS
+
+# From Apache Iceberg Version: 1.7.1
+
+---
+paths:
+ # The /v1/oauth/tokens endpoint is copied from
iceberg-rest-catalog-open-api.yaml,
+ # ensuring that its deprecation and removal schedule is independent of the
Iceberg release cycle.
+ /v1/oauth/tokens:
+
+ post:
+ tags:
+ - OAuth2 API
+ summary: Get a token using an OAuth2 flow (DEPRECATED for REMOVAL)
+ deprecated: true
+ operationId: getToken
+ description:
+ The `oauth/tokens` endpoint is **DEPRECATED for REMOVAL**. It is _not_
recommended to
+ implement this endpoint, unless you are fully aware of the potential
security implications.
+
+ All clients are encouraged to explicitly set the configuration
property `oauth2-server-uri`
+ to the correct OAuth endpoint.
+
+ Deprecated since Iceberg (Java) 1.6.0. The endpoint and related types
will be removed from
+ this spec in Iceberg (Java) 2.0.
+
+ See [Security improvements in the Iceberg REST
specification](https://github.com/apache/iceberg/issues/10537)
+
+
+ Exchange credentials for a token using the OAuth2 client credentials
flow or token exchange.
+
+
+ This endpoint is used for three purposes -
+
+ 1. To exchange client credentials (client ID and secret) for an access
token
+ This uses the client credentials flow.
+
+ 2. To exchange a client token and an identity token for a more
specific access token
+ This uses the token exchange flow.
+
+ 3. To exchange an access token for one with the same claims and a
refreshed expiration period
+ This uses the token exchange flow.
+
+
+ For example, a catalog client may be configured with client
credentials from the OAuth2
+ Authorization flow. This client would exchange its client ID and
secret for an access token
+ using the client credentials request with this endpoint (1).
Subsequent requests would then
+ use that access token.
+
+
+ Some clients may also handle sessions that have additional user
context. These clients would
+ use the token exchange flow to exchange a user token (the "subject"
token) from the session
+ for a more specific access token for that user, using the catalog's
access token as the
+ "actor" token (2). The user ID token is the "subject" token and can be
any token type
+ allowed by the OAuth2 token exchange flow, including a unsecured JWT
token with a sub claim.
+ This request should use the catalog's bearer token in the
"Authorization" header.
+
+
+ Clients may also use the token exchange flow to refresh a token that
is about to expire by
+ sending a token exchange request (3). The request's "subject" token
should be the expiring
+ token. This request should use the subject token in the
"Authorization" header.
+ parameters:
+ - name: Authorization
+ in: header
+ schema:
+ type: string
+ required: false
+ requestBody:
+ required: true
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ $ref: '#/components/schemas/OAuthTokenRequest'
+ responses:
+ 200:
+ $ref: '#/components/responses/OAuthTokenResponse'
+ 400:
+ $ref: '#/components/responses/OAuthErrorResponse'
+ 401:
+ $ref: '#/components/responses/OAuthErrorResponse'
+ 5XX:
+ $ref: '#/components/responses/OAuthErrorResponse'
+ security:
+ - BearerAuth: []
+
+components:
+ schemas:
+
+ TokenType:
+ type: string
+ enum:
+ - urn:ietf:params:oauth:token-type:access_token
+ - urn:ietf:params:oauth:token-type:refresh_token
+ - urn:ietf:params:oauth:token-type:id_token
+ - urn:ietf:params:oauth:token-type:saml1
+ - urn:ietf:params:oauth:token-type:saml2
+ - urn:ietf:params:oauth:token-type:jwt
+ description:
+ Token type identifier, from RFC 8693 Section 3
+
+
+ See https://datatracker.ietf.org/doc/html/rfc8693#section-3
+
+ OAuthClientCredentialsRequest:
+ deprecated: true
+ description:
+ The `oauth/tokens` endpoint and related schemas are **DEPRECATED for
REMOVAL** from this
+ spec, see description of the endpoint.
+
+
+ OAuth2 client credentials request
+
+
+ See https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
+ type: object
+ required:
+ - grant_type
+ - client_id
+ - client_secret
+ properties:
+ grant_type:
+ type: string
+ enum:
+ - client_credentials
+ scope:
+ type: string
+ client_id:
+ type: string
+ description:
+ Client ID
+
+
+ This can be sent in the request body, but OAuth2 recommends
sending it in
+ a Basic Authorization header.
+ client_secret:
+ type: string
+ description:
+ Client secret
+
+
+ This can be sent in the request body, but OAuth2 recommends
sending it in
+ a Basic Authorization header.
+
+ OAuthTokenExchangeRequest:
+ deprecated: true
+ description:
+ The `oauth/tokens` endpoint and related schemas are **DEPRECATED for
REMOVAL** from this
+ spec, see description of the endpoint.
+
+
+ OAuth2 token exchange request
+
+
+ See https://datatracker.ietf.org/doc/html/rfc8693
+ type: object
+ required:
+ - grant_type
+ - subject_token
+ - subject_token_type
+ properties:
+ grant_type:
+ type: string
+ enum:
+ - urn:ietf:params:oauth:grant-type:token-exchange
+ scope:
+ type: string
+ requested_token_type:
+ $ref: '#/components/schemas/TokenType'
+ subject_token:
+ type: string
+ description: Subject token for token exchange request
+ subject_token_type:
+ $ref: '#/components/schemas/TokenType'
+ actor_token:
+ type: string
+ description: Actor token for token exchange request
+ actor_token_type:
+ $ref: '#/components/schemas/TokenType'
+
+ OAuthTokenRequest:
+ deprecated: true
+ description:
+ The `oauth/tokens` endpoint and related schemas are **DEPRECATED for
REMOVAL** from this
+ spec, see description of the endpoint.
+ anyOf:
+ - $ref: '#/components/schemas/OAuthClientCredentialsRequest'
+ - $ref: '#/components/schemas/OAuthTokenExchangeRequest'
+ OAuthError:
+ deprecated: true
+ description:
+ The `oauth/tokens` endpoint and related schemas are **DEPRECATED for
REMOVAL** from this
+ spec, see description of the endpoint.
+ type: object
+ required:
+ - error
+ properties:
+ error:
+ type: string
+ enum:
+ - invalid_request
+ - invalid_client
+ - invalid_grant
+ - unauthorized_client
+ - unsupported_grant_type
+ - invalid_scope
+ error_description:
+ type: string
+ error_uri:
+ type: string
+
+ OAuthTokenResponse:
+ deprecated: true
+ description:
+ The `oauth/tokens` endpoint and related schemas are **DEPRECATED for
REMOVAL** from this
+ spec, see description of the endpoint.
+ type: object
+ required:
+ - access_token
+ - token_type
+ properties:
+ access_token:
+ type: string
+ description:
+ The access token, for client credentials or token exchange
+ token_type:
+ type: string
+ enum:
+ - bearer
+ - mac
+ - N_A
+ description:
+ Access token type for client credentials or token exchange
+
+
+ See https://datatracker.ietf.org/doc/html/rfc6749#section-7.1
+ expires_in:
+ type: integer
+ description:
+ Lifetime of the access token in seconds for client credentials or
token exchange
+ issued_token_type:
+ $ref: '#/components/schemas/TokenType'
+ refresh_token:
+ type: string
+ description: Refresh token for client credentials or token exchange
+ scope:
+ type: string
+ description: Authorization scope for client credentials or token
exchange
+
+ responses:
+
+ OAuthTokenResponse:
+ description: OAuth2 token response for client credentials or token
exchange
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OAuthTokenResponse'
+
+ OAuthErrorResponse:
+ description: OAuth2 error response
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OAuthError'
diff --git a/spec/polaris-catalog-service.yaml
b/spec/polaris-catalog-service.yaml
index c5f7926f..cedcf0f7 100644
--- a/spec/polaris-catalog-service.yaml
+++ b/spec/polaris-catalog-service.yaml
@@ -29,7 +29,7 @@ info:
Defines the specification for the Polaris Catalog API, which encompasses
both the Iceberg REST Catalog API
and Polaris-native API.
-# The server configuration is sourced from rest-catalog-open-api.yaml
+# The server configuration is sourced from iceberg-rest-catalog-open-api.yaml
servers:
- url: "{scheme}://{host}/{basePath}"
description: Server URL when the port can be inferred from the scheme
@@ -59,7 +59,7 @@ servers:
description: Optional prefix to be appended to all routes
default: ""
-# The security configuration is sourced from rest-catalog-open-api.yaml
+# The security configuration is sourced from iceberg-rest-catalog-open-api.yaml
# All routes are currently configured using an Authorization header.
security:
- OAuth2: [catalog]
@@ -72,49 +72,60 @@ paths:
############################
/v1/config:
- $ref: './rest-catalog-open-api.yaml#/paths/~1v1~1config'
+ $ref: './iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1config'
+ # Deprecated, it should be removed or modified in the future according to
+ # https://github.com/apache/polaris/issues/12
/v1/oauth/tokens:
- $ref: './rest-catalog-open-api.yaml#/paths/~1v1~1oauth~1tokens'
+ $ref:
'./polaris-catalog-apis/oauth-tokens-api.yaml#/paths/~1v1~1oauth~1tokens'
/v1/{prefix}/namespaces:
- $ref: './rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces'
/v1/{prefix}/namespaces/{namespace}:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}'
/v1/{prefix}/namespaces/{namespace}/properties:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1properties'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1properties'
/v1/{prefix}/namespaces/{namespace}/tables:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables'
/v1/{prefix}/namespaces/{namespace}/register:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1register'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1register'
/v1/{prefix}/namespaces/{namespace}/tables/{table}:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}'
/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}~1credentials'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}~1credentials'
/v1/{prefix}/tables/rename:
- $ref: './rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1tables~1rename'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1tables~1rename'
/v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}~1metrics'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1tables~1{table}~1metrics'
/v1/{prefix}/transactions/commit:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1transactions~1commit'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1transactions~1commit'
/v1/{prefix}/namespaces/{namespace}/views:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1views'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1views'
/v1/{prefix}/namespaces/{namespace}/views/{view}:
- $ref:
'./rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1views~1{view}'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1namespaces~1{namespace}~1views~1{view}'
/v1/{prefix}/views/rename:
- $ref: './rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1views~1rename'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/paths/~1v1~1{prefix}~1views~1rename'
+
+ # /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan:
+ # Not implemented in Polaris
+
+ # /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}:
+ # Not implemented in Polaris
+
+ # /v1/{prefix}/namespaces/{namespace}/tables/{table}/tasks:
+ # Not implemented in Polaris
######################
# Polaris-native API #
@@ -127,7 +138,7 @@ paths:
components:
securitySchemes:
- # The OAuth2 scheme is sourced from rest-catalog-open-api.yaml
+ # The OAuth2 scheme is sourced from iceberg-rest-catalog-open-api.yaml
#
# If the /v1/oauth/tokens endpoint is removed or modified
# (see https://github.com/apache/polaris/issues/12),
@@ -152,4 +163,4 @@ components:
catalog: Allows interacting with the Config and Catalog APIs
BearerAuth:
- $ref:
'./rest-catalog-open-api.yaml#/components/securitySchemes/BearerAuth'
+ $ref:
'./iceberg-rest-catalog-open-api.yaml#/components/securitySchemes/BearerAuth'
