stevenzwu commented on code in PR #12584:
URL: https://github.com/apache/iceberg/pull/12584#discussion_r3301121007
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -3545,6 +3652,69 @@ components:
allOf:
- $ref: '#/components/schemas/ScanTasks'
+ QueryEventsRequest:
+ type: object
+ properties:
+ continuation-token:
+ type: string
+ description: >
+ A continuation token to resume fetching events from a previous
request.
+ If not provided, events are fetched from the beginning of the
event log
+ subject to other filters.
+ page-size:
+ type: integer
+ format: int32
+ description: >
+ The maximum number of events to return in a single response.
+ If not provided, the server may choose a default page size.
+ Servers may return less results than requested for various
reasons, such as
+ server side limits, payload size or processing time.
+ after-timestamp-ms:
Review Comment:
I see. this is an optional starting timestamp for the initial request. it is
similar to the Kafka seek-to-timestamp for the starting point of message
consumption.
Separate point on naming: `since-timestamp-ms` reads more naturally than
`after-timestamp-ms` for an inclusive starting cursor. It's a common REST
convention for time-keyed listings ([GitHub uses
`since`](https://docs.github.com/en/rest/issues/issues#list-repository-issues)
for issues and commits; [Kubernetes uses
`sinceTime`/`sinceSeconds`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#read-log-pod-v1-core)
for pod log streams), and `after-` reads slightly exclusive in plain English —
the opposite of the documented '(inclusive)' semantics, so every reader has to
resolve that mismatch.
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -1825,6 +1825,59 @@ paths:
5XX:
$ref: '#/components/responses/ServerErrorResponse'
+ /v1/{prefix}/events:
+ parameters:
+ - $ref: '#/components/parameters/prefix'
+ post:
+ tags:
+ - Catalog API
+ summary: Get events for changes to catalog objects
+ description: >
+ Returns a sequence of changes to catalog objects (tables, namespaces,
views)
+ that allows clients to efficiently track metadata modifications
without polling individual
+ resources. Consumers track their progress through a
continuation-token, enabling resumable
+ synchronization after downtime or errors.
+
+ This endpoint primarily supports use cases like catalog federation,
workflow triggering,
+ and basic audit capabilities.
+
+ The server encodes all necessary state in the token to ensure
+ consistent filtering across pages. Clients should use the returned
`continuation-token` for
+ subsequent requests.
+
+ Consumers should be prepared to handle 410 Gone responses when
requested sequences are
+ outside the server's retention window. Consumers should also
de-duplicate received events based
+ on the event's `event-id`. Consistency guarantees vary between server
implementations.
Review Comment:
I saw `event's` is changed to `events`. I was saying maybe drop the word
completely.
--
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]
