flyrain commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1750675084
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,264 @@ 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
+
+ - 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
+
+ - Status "cancelled" is not a valid status from this endpoint
+
+
+ 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
Review Comment:
I'm also not sure if this is the right place to do that, but I feel like it
makes sense to give a warning message here, that if a server does delete a plan
aggressively, the clients may get confused error message.
--
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
