rdblue commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1687097927
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -541,6 +541,130 @@ 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
+ parameters:
+ - $ref: '#/components/parameters/page-token'
+ - $ref: '#/components/parameters/page-size'
+ 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/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:
+ 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
+ parameters:
+ - $ref: '#/components/parameters/page-token'
+ - $ref: '#/components/parameters/page-size'
+ 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:
+ 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'
+ 419:
+ $ref: '#/components/responses/AuthenticationTimeoutResponse'
+ 421:
+ $ref: '#/components/responses/MisdirectedRequestResponse'
+ 422:
+ $ref: '#/components/responses/UnprocessableContentResponse'
Review Comment:
I don't see the value of having both 421 and 422 here, when both would have
the same behavior for the client. If there is more context that the service
wants to share for why the preplan endpoint must be used, it can already do
that in an error message.
I think that 422 should probably be removed unless there is some additional
value to it.
--
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
