jackye1995 commented on code in PR #9695:
URL: https://github.com/apache/iceberg/pull/9695#discussion_r1623316927
##########
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:
+ 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/ErrorModel'
+ examples:
+ TableDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 419:
+ $ref: '#/components/responses/AuthenticationTimeoutResponse'
+ 421:
Review Comment:
looks like there are currently multiple ways to express errors:
1. create a generic error response for a specific error code, but its schema
is just the generic IcebergErrorResponse. Most of the error responses are like
that
2. have a lengthy description of the possible exceptions of an error code,
and refer to the most basic ErrorModel schema, like what 404 does
3. have a dedicated error response model, a few OAuth errors like
OAuthErrorResponse is like that.
I feel we might want to clean things up a bit later, now I just use the
simplest approach 1 for 421 and 422, and describe the expectation in the API
description section.
--
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
