stevenzwu commented on code in PR #15830:
URL: https://github.com/apache/iceberg/pull/15830#discussion_r3120543018
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -1931,6 +1903,143 @@ paths:
5XX:
$ref: '#/components/responses/ServerErrorResponse'
+ /v1/{prefix}/relations/batch-load:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Batch load relations (tables and views) from the catalog
+ operationId: batchLoadRelations
+ description:
+ "
+ Load metadata for multiple relations in one request. Identifiers may
span different namespaces.
+ Each item includes a `TableIdentifier` and optional per-item
parameters (`etag` and `snapshots`).
+ The server resolves each identifier as a table or view.
+
+
+ The per-item `status` in the response indicates the outcome:
+
+ - `200` - Relation exists and metadata is returned. The `result` field
contains a
+ `LoadRelationResult` with `object-type` and the type-specific
payload.
+
+ - `304` - The relation is a table and the provided ETag matches the
current metadata version.
+ No payload is returned. The current `etag` value is included.
+
+ - `404` - No table or view exists for the identifier.
+
+
+ Servers MAY cap the amount of computation or response payload size per
request and return
+ `unprocessed-identifiers` for items they did not process. Clients
SHOULD retry unprocessed
+ identifiers in a subsequent request.
Review Comment:
Good catch, thanks. Updated the spec.
`unprocessed-identifiers` was only meant as a cooperative soft cap — the
server accepted the request, then stopped partway due to its own cost budget.
It doesn't cover the "please reject this upfront" case you described.
Added a typed hard cap to `CatalogConfig`:
```yaml
relations-batch-load-max-items:
type: integer
minimum: 1
```
Advertising the limit lets well-behaved clients chunk proactively, and
servers that receive an oversized request still have a spec-supported way to
reject with `400`.
The `batchLoadRelations` description and `unprocessed-identifiers` field now
spell out the two mechanisms as distinct:
- `relations-batch-load-max-items` — governs whether the request is accepted
at all (`400` if exceeded).
- `unprocessed-identifiers` — reports partial progress within an accepted
request.
Went with `400` rather than `413` since the limit is on identifier count (a
request property), not body size — happy to switch if you disagree.
--
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]
