gRPC API

You can interact with an UmaDB server using its gRPC API.

• grpc.health.v1.Health — for checking server health.
• umadb.v1.DCB — for reading and appending DCB events.

The sections below detail the umadb.v1.DCB service defined in umadb.proto.

DCB Service

UmaDB's gRPC service for reading and appending events exposes four RPC methods:

Name	Request	Response	Description
Append	AppendRequest	AppendResponse	Appends new events atomically, with optional append condition, and optional tracking information.
Read	ReadRequest	stream ReadResponse	Streams stored events from the server to the client, optionally as a subscription.
Head	HeadRequest	HeadResponse	Returns the position of the last event in the database; used to measure the volume of stored events.
GetTrackingInfo	TrackingRequest	TrackingResponse	Returns the last recorded position in an upstream sequence of events; used when starting or resuming event processing components.

Append Request

Send an AppendRequest to the Append RPC to store new events. All the Event messages in the events field will be appended atomically in order, unless the AppendCondition given in the condition field fails.

Field	Type	Description
events	repeated Event	Events to append, in order.
condition	optional AppendCondition	Optional condition to enforce optimistic concurrency and detect conflicts.
tracking_info	optional TrackingInfo	Optional tracking information; used by event processing components to checkpoint their progress.

The server will return an AppendResponse message if the condition does not fail.

If the append condition fails, or if the tracking information conflicts, the server will return a gRPC error response with gRPC status FAILED_PRECONDITION and a human-readable message string. In addition, the gRPC status details attribute will have a serialised ErrorResponse message, that has the same human-readable message string and INTEGRITY as the error_type.

Conditional appending of events with UUIDs is idempotent. The server does not enforce uniqueness of event IDs.

Append Response

The server returns an AppendResponse message for each successful AppendRequest.

Field	Type	Description
position	uint64	Sequence number of the last appended event.

Clients can use the returned position to wait until downstream event processing components have become up-to-date, avoiding out-of-date views being presented to users.

Read Request

Send a ReadRequest to the Read RPC to read events from the event store.

Set query to select only specific events. Set start to read only from a specific position. If start is not set, events will be read from the first recorded event, or the last if backwards is true.

Field	Type	Description
query	optional Query	Optional filter for selecting specific event types or tags.
start	optional uint64	Read from this sequence number.
backwards	optional bool	Start reading backwards (default false).
limit	optional uint32	Maximum number of events to return (default unlimited).
subscribe	optional bool	If true, the stream remains open and continues delivering new events.
batch_size	optional uint32	Optional batch size hint for streaming responses.

The server will return a stream of ReadResponse messages. The default value of subscribe is false, meaning the stream will end when all selected events have been received. When subscribe is true, the stream will continue as new events are appended to the store.

Read Response

A stream of ReadResponse messages are sent in response to each ReadRequest. A collection of SequencedEvent messages can be obtained from the events field.

Field	Type	Description
events	repeated SequencedEvent	A batch of events matching the ReadRequest.query.
head	optional uint64	The position of the last recorded event.

When ReadRequest.subscribe was false and ReadRequest.limit was None, the value of head will be the position of the last recorded event in the database during the reader transaction.

Otherwise, if ReadRequest.subscribe was true, the value of head will be empty.

Otherwise, if ReadRequest.limit was a uint64, the value of head will be the position of the last event in the message's events field.

Head Request

Send a HeadRequest to the Head RPC to get the position of the last recorded event in the event store.

This message has no fields.

Head Response

The server returns a HeadResponse message in response to each HeadRequest message sent by clients to the Head RPC.

Field	Type	Description
position	optional uint64	The latest known event position, or None if the store is empty.

The position field contains the sequence position of the last recorded event in the store, or None if the store is empty.

Tracking Request

Send a TrackingRequest to the GetTrackingInfo RPC to get the last recorded position in an upstream sequence of events.

Field	Type	Description
source	string	Upstream sequence name.

Tracking Response

The server returns a TrackingResponse message in response to each TrackingRequest message sent by clients to the GetTrackingInfo RPC.

Field	Type	Description
position	optional uint64	The last recorded position.

The position field contains the last recorded position in an upstream sequence of events, or None if the sequence name is not found.

Event

An Event represents a single event either to be appended or already stored in the event log.

Field	Type	Description
event_type	string	The event’s logical type (e.g. "UserRegistered").
tags	repeated string	Tags assigned to the event (used for filtering and indexing).
data	bytes	Binary payload associated with the event.
uuid	string	Unique event ID (e.g. serialized version 4 UUIDv4).

Idempotent support for append operations is activated by setting a UUID on appended events. The server does not enforce uniqueness of event IDs.

Include in:

• AppendRequest when writing new events to the store.

Included in:

• SequencedEvent when the server responds to read requests.

Matched by:

• QueryItem during Read and Append operations.

Append Condition

An AppendCondition causes an append request to fail if events match its Query, optionally after a sequence number.

Field	Type	Description
fail_if_events_match	optional Query	Query for conflicting events.
after	optional uint64	Sequence number.

Include in:

• AppendRequest to define optimistic concurrent control.

To implement a consistency boundary, command handlers can use the same Query used in ReadRequest as the value of fail_if_events_match, and the "head" received in the ReadResponse as the value of after, when appending new events generated by a decision model.

Tracking Info

A TrackingInfo message represents the source and position of an upstream event.

Field	Type	Description
source	string	Upstream sequence name.
position	uint64	Upstream sequence number.

Include in:

• AppendRequest when recording the results of processing an upstream event.

Query

A Query defines criteria for selecting events in the event store.

Field	Type	Description
items	repeated QueryItem	A list of selection criteria (logical OR).

An Event is selected if any QueryItem matches or the items field is empty.

Include in:

• ReadRequest to select events returned by the server.
• AppendCondition to select conflicting events.

Query Item

A QueryItem defines a criterion for matching events.

Field	Type	Description
types	repeated string	List of event types (logical OR).
tags	repeated string	List of tags (logical AND).

A QueryItem will match an Event if:

• one of its types matches the Event.event_type or its types field is empty; AND
• all of its tags match one of the Event.tags or its tags field is empty.

Include in:

• Query to define which events to select.

Sequenced Event

A SequencedEvent represents a recorded Event along with its assigned sequence number.

Field	Type	Description
position	uint64	The sequence number.
event	Event	The recorded event.

Included in:

• ReadResponse when the server responds to read requests.

Error Response

An ErrorResponse is used to return errors from the gRPC API.

Field	Type	Description
message	string	Human-readable description of the error.
error_type	ErrorType	Classification of the error.

If an operation fails, the server will return a gRPC error response with a suitable gRPC status code and a human-readable message string. In addition, the gRPC status details attribute will have a serialised ErrorResponse message that has the same human-readable message string, and an error_type set to a appropriate ErrorType.

Error Type

The ErrorType enum indicates UmaDB error types returned within an ErrorResponse .

Value	Name	Description
0	IO	Input/output error (e.g. storage or filesystem).
1	SERIALIZATION	Serialization or deserialization failure.
2	INTEGRITY	Logical integrity violation (e.g. condition failed).
3	CORRUPTION	Corrupted or invalid data detected.
4	INTERNAL	Internal server or database error.
5	AUTHENTICATION	Client-server authentication error.
6	INVALID_ARGUMENT	Request contains an invalid argument.

Summary

Category	Message	Description
Event Model	Event, SequencedEvent	Core event representation.
Queries	Query, QueryItem	Define filters for event selection.
Conditions	AppendCondition	Control write preconditions.
Read/Write	ReadRequest, ReadResponse, AppendRequest, AppendResponse	Reading and appending APIs.
Meta	HeadRequest, HeadResponse	Retrieve current head position.
Tracking	TrackingRequest, TrackingResponse	Retrieve current head position.
Errors	ErrorResponse	Consistent error representation.