c-thiel commented on code in PR #12584:
URL: https://github.com/apache/iceberg/pull/12584#discussion_r2602236824
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -3964,6 +4132,332 @@ components:
metadata:
$ref: '#/components/schemas/TableMetadata'
+ EventsResponse:
+ type: object
+ required:
+ - highest-processed-timestamp-ms
+ - events
+ properties:
+ next-page-token:
+ $ref: "#/components/schemas/PageToken"
+ 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
+ - 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
+ 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 `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: string
+ description: >
+ The actor who performed the operation, such as a user or service
account.
+ The content of this field is implementation specific.
+ operation:
+ type: object
+ description: >
+ The operation that was performed, such as creating or updating a
table.
+ Clients should discard events with unknown operation types.
+ discriminator:
+ propertyName: operation-type
+ mapping:
+ create-table: "#/components/schemas/CreateTableOperation"
+ register-table: "#/components/schemas/RegisterTableOperation"
+ drop-table: "#/components/schemas/DropTableOperation"
+ update-table: "#/components/schemas/UpdateTableOperation"
+ rename-table: "#/components/schemas/RenameTableOperation"
+ create-view: "#/components/schemas/CreateViewOperation"
+ drop-view: "#/components/schemas/DropViewOperation"
+ update-view: "#/components/schemas/UpdateViewOperation"
+ rename-view: "#/components/schemas/RenameViewOperation"
+ create-namespace: "#/components/schemas/CreateNamespaceOperation"
+ update-namespace-properties:
"#/components/schemas/UpdateNamespacePropertiesOperation"
+ drop-namespace: "#/components/schemas/DropNamespaceOperation"
+ custom: "#/components/schemas/CustomOperation"
+ oneOf:
+ - $ref: "#/components/schemas/CreateTableOperation"
+ - $ref: "#/components/schemas/RegisterTableOperation"
+ - $ref: "#/components/schemas/DropTableOperation"
+ - $ref: "#/components/schemas/UpdateTableOperation"
+ - $ref: "#/components/schemas/RenameTableOperation"
+ - $ref: "#/components/schemas/CreateViewOperation"
+ - $ref: "#/components/schemas/DropViewOperation"
+ - $ref: "#/components/schemas/UpdateViewOperation"
+ - $ref: "#/components/schemas/RenameViewOperation"
+ - $ref: "#/components/schemas/CreateNamespaceOperation"
+ - $ref: "#/components/schemas/UpdateNamespacePropertiesOperation"
+ - $ref: "#/components/schemas/DropNamespaceOperation"
+ - $ref: "#/components/schemas/CustomOperation"
+
+ CreateTableOperation:
+ description: >
+ Operation to create a new table in the catalog.
+ Events for this Operation must be issued when the create is finalized
and committed, not when the create is staged.
+ required:
+ - operation-type
+ - identifier
+ - table-uuid
+ - updates
+ properties:
+ operation-type:
+ $ref: "#/components/schemas/OperationType"
+ const: "create-table"
+ identifier:
+ $ref: "#/components/schemas/TableIdentifier"
+ table-uuid:
+ type: string
+ format: uuid
+ updates:
+ type: array
+ items:
+ $ref: "#/components/schemas/TableUpdate"
Review Comment:
In its current design the `events` table in a server implementation does not
need to store full `TableMetadata`, instead, it just needs to store Updates. So
yes, its part of the rest spec, but not part of the return type. So returning
`TableMetadata` now would increase the complexity of the server implementation.
If you look at the first version of this PR, I actually returned
`TableMetadata` just like you suggested (i.e. here
https://github.com/apache/iceberg/blob/5fa2b5a3c52aaaac95be666447ec1c79c53d2afa/open-api/rest-catalog-open-api.yaml#L4151-L4163),
but after discussion this in a Catalog sync we decided to change it.
This was changed as part of the following changes (copied from the google
doc):
Changelog 2025-07-01:
* Remove `TableMetadata` from CreateTable, RegisterTable & CreateView
* Rename “replace-view” to “update-view”
* Improve some docstrings
Diff:
[c54125d](https://github.com/apache/iceberg/pull/12584/commits/c54125dd518afef5a0a1d6153747f716ce0ee739)
I believe there should be able to find more information in the Recording:
https://youtu.be/g7z9i127UjY?si=6XNViPgmuWsiYnI5
Happy to jump in a call if something is unclear after this :)
--
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]
