stevenzwu commented on code in PR #15830:
URL: https://github.com/apache/iceberg/pull/15830#discussion_r3120610527
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -1897,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:
Review Comment:
Agreed. Will switch the per-item shape to a discriminated union using the
same `object-type`-style pattern already in `LoadRelationResult`:
```yaml
BatchLoadRelationResultItem:
oneOf:
- $ref: '#/components/schemas/BatchLoadRelationLoaded'
- $ref: '#/components/schemas/BatchLoadRelationNotModified'
- $ref: '#/components/schemas/BatchLoadRelationNotFound'
discriminator:
propertyName: result-type
mapping:
loaded: '#/components/schemas/BatchLoadRelationLoaded'
not-modified: '#/components/schemas/BatchLoadRelationNotModified'
not-found: '#/components/schemas/BatchLoadRelationNotFound'
```
Each variant declares exactly its own required fields:
- **`loaded`** → `result` (required) + `etag` (optional, tables only)
- **`not-modified`** → `etag` (required)
- **`not-found`** → `identifier` (required), optionally `error: ErrorModel`
Why domain-native names over HTTP status integers:
- **Wire stays honest.** HTTP codes describe transport; per-item outcomes
describe domain state. Keeping them separate means caches, retries, tracing,
and monitoring don't have to peek inside the body to know what actually
happened.
- **Presence rules become schema-enforced.** `oneOf` lets each variant
require its own fields instead of relying on prose in the description.
- **Stronger generated clients.** `result-type` generates into sealed
interfaces / discriminated unions / sum types, so the compiler catches missed
cases. An integer `status` generates into a plain `int` that callers switch on
by hand.
- **Extensible without fake codes.** Adding outcomes like `skipped` or
`stale-etag-mismatch` later is a new variant — no need to overload `429` or
invent a meaning for an HTTP code that doesn't fit.
- **Internally consistent with this PR.** `LoadRelationResult` already uses
`object-type` as a string discriminator; reusing the same style for per-item
outcomes keeps the reader's mental model uniform.
--
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]
