jackye1995 commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1623317017
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -537,6 +537,124 @@ paths:
5XX:
$ref: '#/components/responses/ServerErrorResponse'
+ /v1/{prefix}/namespaces/{namespace}/tables/{table}/preplan:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ post:
+ tags:
+ - Catalog API
+ summary: Prepare a list of tasks that can be used to distribute table
scan planning
+ description:
+ Prepare a list of tasks that can be used to distribute table scan
planning based on a set of table scan criteria
+ such as selected columns, filters, snapshot range, case sensitivity,
etc.
+
+ This API returns a list of `plan-task`s, and each of them can be used
in the `PlanTable` API
+ to request a subset of all file scan tasks in a table scan.
+ This mechanism allows clients to distribute and parallelize the entire
table scan planning process.
+ operationId: PreplanTable
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PreplanTableRequest'
+ responses:
+ 200:
+ $ref: '#/components/responses/PreplanTableResponse'
+ 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/ErrorModel'
+ 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:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ post:
+ tags:
+ - Catalog API
+ summary: Perform scan planning against a table
+ operationId: PlanTable
+ description:
+ Perform scan planning against a table based on a set of table scan
criteria such as selected columns, filters,
+ snapshot range, case sensitivity, etc.
+
+ An optional `plan-task` can be provided to request only a subset of
file scan tasks.
+ The `plan-task` can be retrieved by invoking the `PreplanTable`
endpoint.
+
+ If preplanning using the `PreplanTable` endpoint is required before
hitting this endpoint but the client fails
+ to supply a `plan-task` in the request, then a `421 Misdirected
Request` response should be returned to
+ indicate this requirement.
+
+ If planning a table scan produces too many file scan tasks and the
server is unable to return them within its
+ response size limit, then a `422 Unprocessable Content` response
should be returned to indicate that the client
+ should first attempt to preplan the specific table scan to distribute
the planning process and make the content
+ processable by the server.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PlanTableRequest'
+ responses:
Review Comment:
Technically there are also some missing ones like 429 throttling, 408 time
out, but I think those are needed for basically every API. If we agree with
that, I will add them in separated PRs.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
