rdblue commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1733498821
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,216 @@ 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: Returns either a list of `PlanTask`, a list of `FileScanTask`.
If planning is not complete returns a `plan-id`.
+ description:
+ Prepares either a list of `PlanTask` that can be used to distribute
table scan planning, or a list of `FileScanTask`, based on a set of table scan
criteria
+ such as selected columns, filters, snapshot range, case sensitivity,
etc.
+ In the event that the plan tasks or file scan tasks are not ready to
be served, the service will return a `plan-id`,
+ which can be used as input in the `GetTasksStatus`.
+
+ Requires that the client specifies only a `snapshot-id` for a snapshot
scan, or for performing incremental scans only provide
+ a `start-snapshot-id` and an `end-snapshot-id`.
+
+ Each `PlanTask`, can be used as input in the `RetrieveTasks` API
+ to request a subset of file scan tasks in a table scan.
+ This mechanism allows clients to distribute and parallelize the entire
table scan planning process.
+ operationId: planTable
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PlanTableRequest'
+ responses:
+ 200:
+ $ref: '#/components/responses/PlanTableResponse'
+ 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/{id}:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ - $ref: '#/components/parameters/id'
+
+ get:
+ tags:
+ - Catalog API
+ summary: Uses a `plan-id` as input to get status of `planTable`. Returns
a list of `PlanTask`, a list of `FileScanTask`, or both when plan is complete.
+ operationId: GetTaskStatus
+ description:
+ Gets the status of a plan by using a `plan-id` which can be obtained
from `planTable`.
+ If the plan is not completed, returns a `plan-status` representing the
state of the plan.
+ If the plan is completed, returns a list of `PlanTask` or
`FileScanTask`.
+
+ If an invalid `plan-id` is provided, the service will return a `404
NoSuchPlanIdError` exception indicating that the requested plan does not exist.
+ responses:
+ 200:
+ $ref: '#/components/responses/GetTasksStatusResponse'
+ 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: Uses a `plan-id` as input to cancel a `planTable` operation.
+ operationId: CancelPlan
+ description:
+ Uses a `plan-id` as input to cancel a `planTable` operation.
+ If successful, should return a state that says "cancelled".
+
+ If an invalid `plan-id` is provided, the service will return a `404
NoSuchPlanIdError` exception indicating that the requested plan does not exist.
+ responses:
+ 200:
+ $ref: '#/components/responses/CancelPlanResponse'
+ 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: Retrieves additional `PlanTask`s and `FileScanTask`s from the
service.
+ operationId: RetrieveTasks
Review Comment:
I think we normally use the verb "fetch", which is also what I suggested
instead of the `GetStatus` above. How about `FetchTasks`?
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,216 @@ 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: Returns either a list of `PlanTask`, a list of `FileScanTask`.
If planning is not complete returns a `plan-id`.
+ description:
+ Prepares either a list of `PlanTask` that can be used to distribute
table scan planning, or a list of `FileScanTask`, based on a set of table scan
criteria
+ such as selected columns, filters, snapshot range, case sensitivity,
etc.
+ In the event that the plan tasks or file scan tasks are not ready to
be served, the service will return a `plan-id`,
+ which can be used as input in the `GetTasksStatus`.
+
+ Requires that the client specifies only a `snapshot-id` for a snapshot
scan, or for performing incremental scans only provide
+ a `start-snapshot-id` and an `end-snapshot-id`.
+
+ Each `PlanTask`, can be used as input in the `RetrieveTasks` API
+ to request a subset of file scan tasks in a table scan.
+ This mechanism allows clients to distribute and parallelize the entire
table scan planning process.
+ operationId: planTable
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PlanTableRequest'
+ responses:
+ 200:
+ $ref: '#/components/responses/PlanTableResponse'
+ 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/{id}:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ - $ref: '#/components/parameters/id'
+
+ get:
+ tags:
+ - Catalog API
+ summary: Uses a `plan-id` as input to get status of `planTable`. Returns
a list of `PlanTask`, a list of `FileScanTask`, or both when plan is complete.
+ operationId: GetTaskStatus
+ description:
+ Gets the status of a plan by using a `plan-id` which can be obtained
from `planTable`.
+ If the plan is not completed, returns a `plan-status` representing the
state of the plan.
+ If the plan is completed, returns a list of `PlanTask` or
`FileScanTask`.
+
+ If an invalid `plan-id` is provided, the service will return a `404
NoSuchPlanIdError` exception indicating that the requested plan does not exist.
+ responses:
+ 200:
+ $ref: '#/components/responses/GetTasksStatusResponse'
+ 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: Uses a `plan-id` as input to cancel a `planTable` operation.
+ operationId: CancelPlan
+ description:
+ Uses a `plan-id` as input to cancel a `planTable` operation.
+ If successful, should return a state that says "cancelled".
+
+ If an invalid `plan-id` is provided, the service will return a `404
NoSuchPlanIdError` exception indicating that the requested plan does not exist.
+ responses:
+ 200:
+ $ref: '#/components/responses/CancelPlanResponse'
+ 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: Retrieves additional `PlanTask`s and `FileScanTask`s from the
service.
+ operationId: RetrieveTasks
Review Comment:
I think we normally use the verb "fetch", which is also what I suggested
instead of the `GetStatus` above. How about `fetchTasks`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For additional commands, e-mail: issues-h...@iceberg.apache.org
