rdblue commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1736605830
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,263 @@ 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
+
+ - 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
+ - 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
Review Comment:
I don't understand the distinction you're suggesting. What do you think the
wording should be?
--
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
