stevenzwu commented on code in PR #12584:
URL: https://github.com/apache/iceberg/pull/12584#discussion_r3299360603
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -4278,6 +4427,340 @@ components:
metadata:
$ref: '#/components/schemas/TableMetadata'
+ QueryEventsResponse:
+ type: object
+ required:
+ - continuation-token
+ - highest-processed-timestamp-ms
+ - events
+ properties:
+ continuation-token:
+ type: string
+ description: >
+ An opaque continuation token to fetch the next page of events.
+ This token encodes the server's cursor position and filter state.
+ Clients should treat this as an opaque value and pass it
unmodified in subsequent requests.
+ highest-processed-timestamp-ms:
+ description: >
+ The highest event timestamp processed when generating this
response.
+ This may not necessarily appear in the returned changes if it was
filtered out.
+ type: integer
+ format: int64
+ events:
+ type: array
+ items:
+ $ref: "#/components/schemas/Event"
+
+ Event:
+ type: object
+ required:
+ - event-id
+ - request-id
+ - request-event-count
+ - timestamp-ms
+ - operation
+ properties:
+ event-id:
+ type: string
+ description: Unique ID of this event. Clients should perform
deduplication based on this ID.
+ request-id:
+ description: >
+ Opaque ID of the request this change belongs to.
+ This ID can be used to identify events that were part of the same
request.
+ Servers generate this ID randomly.
+ type: string
+ request-event-count:
+ type: integer
+ description: >
+ Total number of events in this batch or request.
+ Some endpoints, such as "updateTable" and "commitTransaction", can
perform multiple updates in a single atomic request.
+ Each update is modeled as a separate event. All events generated
by the same request share the same `request-id`.
+ The `request-event-count` field indicates the total number of
events generated by that request.
+ timestamp-ms:
+ type: integer
+ format: int64
+ description: >
+ Timestamp when this event occurred (epoch milliseconds).
+ Timestamps are not guaranteed to be unique. Typically all events in
+ a transaction will have the same timestamp.
+ actor:
+ type: object
+ description: >
+ The actor who performed the operation, such as a user or service
account.
+ The content of this field is implementation specific.
+ additionalProperties: true
Review Comment:
With `actor` as a free-form `additionalProperties: true` map and no
recommended fields, federation/audit consumers have no portable contract —
every catalog will pick a different shape and clients can't write code that
works across them. Even one well-known optional field (e.g. `id: string` or
`principal: string`) with everything else free-form would give consumers
something to render and key on, without restricting the extensibility you
wanted to preserve.
`Snapshot.summary` is the existing precedent in the spec for this shape — a
required `operation` field plus `additionalProperties` for engine-specific
extras:
```yaml
summary:
type: object
required:
- operation
properties:
operation:
type: string
enum: ["append", "replace", "overwrite", "delete"]
additionalProperties:
type: string
```
Same structure here, just `additionalProperties: true` instead of typed
strings since actor values may be richer than strings. Following this pattern
keeps the spec internally consistent.
--
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]
