stevenzwu commented on code in PR #12584:
URL: https://github.com/apache/iceberg/pull/12584#discussion_r3358407716
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -4278,6 +4416,345 @@ components:
metadata:
$ref: '#/components/schemas/TableMetadata'
+ QueryEventsResponse:
+ type: object
+ required:
+ - continuation-token
+ - 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.
+ When no more events are currently available, the server returns an
empty `events` array
+ and a `continuation-token` that the client can re-issue later to
receive events that
+ occur after this point.
+ 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.
+ type: string
+ request-event-count:
+ type: integer
+ description: >
+ Number of events produced by the originating catalog request (e.g.
updateTable
+ or commitTransaction) that generated this event. Such requests can
apply multiple
+ updates atomically, each surfaced as a separate event sharing the
same `request-id`;
+ this count reports how many events that originating request
produced in total.
+ 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.
+ Implementations may add arbitrary additional fields; the optional
`id` field is
+ recommended as a portable identifier that consumers can render and
key on.
+ properties:
+ id:
+ type: string
+ description: >
+ Recommended, optional. Stable identifier of the actor (e.g. a
user or
+ service account). Provided when the server can attribute the
operation.
+ additionalProperties: true
+ operation:
Review Comment:
Minor consistency nit: this field is missing `type: object`. OpenAPI 3.1
infers the type from `anyOf` members, but every other object-shaped field in
the events spec (`BaseOperation`, every concrete `*Operation`, and the
surrounding `Event` properties) declares `type: object` explicitly. Adding
`type: object` here would match.
```yaml
operation:
type: object
description: >
...
anyOf:
...
```
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -4278,6 +4416,345 @@ components:
metadata:
$ref: '#/components/schemas/TableMetadata'
+ QueryEventsResponse:
+ type: object
+ required:
+ - continuation-token
+ - 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.
+ When no more events are currently available, the server returns an
empty `events` array
+ and a `continuation-token` that the client can re-issue later to
receive events that
+ occur after this point.
+ 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.
+ type: string
+ request-event-count:
+ type: integer
+ description: >
+ Number of events produced by the originating catalog request (e.g.
updateTable
+ or commitTransaction) that generated this event. Such requests can
apply multiple
+ updates atomically, each surfaced as a separate event sharing the
same `request-id`;
+ this count reports how many events that originating request
produced in total.
+ 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.
+ Implementations may add arbitrary additional fields; the optional
`id` field is
+ recommended as a portable identifier that consumers can render and
key on.
+ properties:
+ id:
+ type: string
+ description: >
+ Recommended, optional. Stable identifier of the actor (e.g. a
user or
+ service account). Provided when the server can attribute the
operation.
+ additionalProperties: true
+ operation:
+ description: >
+ The operation that was performed, such as creating or updating a
table.
+ The concrete type is selected by the `operation-type`
discriminator defined on
+ `BaseOperation`. Clients should discard events with unknown
operation types.
+ Operations are emitted only when the underlying change is
committed; staged changes
+ are not surfaced.
+ anyOf:
+ - $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"
+
+ BaseOperation:
+ type: object
+ description: >
+ Base type for all catalog operations carried by an `Event`. The
`operation-type`
+ discriminator selects the concrete operation schema. Standard
operation types are
+ enumerated in `OperationType`. Implementation-specific operation types
use an `x-` prefix
+ (see `OperationType`) and are carried as a `BaseOperation` with
implementation-defined
+ additional properties; clients should discard operations with unknown
`operation-type`
+ values.
+ 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"
+ required:
+ - operation-type
+ properties:
+ operation-type:
+ $ref: "#/components/schemas/OperationType"
+
+ CreateTableOperation:
+ description: >
+ Operation to create a new table in the catalog.
+ allOf:
+ - $ref: "#/components/schemas/BaseOperation"
+ required:
+ - operation-type
+ - identifier
+ - table-uuid
+ - updates
+ properties:
+ operation-type:
+ type: string
+ const: "create-table"
+ identifier:
+ $ref: "#/components/schemas/TableIdentifier"
+ table-uuid:
+ type: string
+ format: uuid
+ updates:
+ type: array
+ items:
+ $ref: "#/components/schemas/TableUpdate"
+
+ RegisterTableOperation:
+ allOf:
+ - $ref: "#/components/schemas/BaseOperation"
+ required:
+ - operation-type
+ - identifier
+ - table-uuid
+ properties:
+ operation-type:
+ type: string
+ const: "register-table"
+ identifier:
+ $ref: "#/components/schemas/TableIdentifier"
+ table-uuid:
+ type: string
+ format: uuid
+ updates:
+ type: array
+ items:
+ $ref: "#/components/schemas/TableUpdate"
+
+ DropTableOperation:
+ allOf:
+ - $ref: "#/components/schemas/BaseOperation"
+ required:
+ - operation-type
+ - identifier
+ - table-uuid
+ properties:
+ operation-type:
+ type: string
+ const: "drop-table"
+ identifier:
+ $ref: "#/components/schemas/TableIdentifier"
+ table-uuid:
+ type: string
+ format: uuid
+ purge:
+ type: boolean
+ description: Whether purge flag was set
Review Comment:
"Whether purge flag was set" leaves the reader to infer what the flag does.
Same shape as the `request-id` rewrite — pull the why into the description so
the field is self-explanatory:
```yaml
purge:
type: boolean
description: >
Whether the originating drop request specified the purge flag,
indicating that
the table's data files should also be deleted, not just the catalog
entry.
```
--
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]
