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 already-recorded events from the server to the client.
Subscribe	SubscribeRequest	stream SubscribeResponse	Streams already-recorded and subsequently-recorded events from the server to the client.
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	[deprecated] optional bool	This field is ignored by the server.
batch_size	optional uint32	Optional batch size hint for streaming responses.

The server will return a stream of ReadResponse messages.

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.

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

Otherwise, the value of head will be the position of the last recorded event in the database during the reader transaction.

Subscribe Request

Send a SubscribeRequest to the Subscribe RPC to subscribe to events already-recorded and subsequently-recorded in the event store.

Set query to select only specific events. Set after to read only after a specific position. If after is not set, events will be read from the first recorded event.

Field	Type	Description
query	optional Query	Optional filter for selecting specific event types or tags.
after	optional uint64	Subscribe after this sequence number.
batch_size	optional uint32	Optional batch size hint for streaming responses.

The server will return a stream of SubscribeResponse messages. The stream will continue as new events are appended to the store.

Subscribe Response

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

Field	Type	Description
events	repeated SequencedEvent	A batch of events matching the SubscribeRequest.query.

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).
metadata	repeated  MetadataEntry	Key-value metadata attached to the event (e.g. provenance, correlation IDs).

Idempotent support for append operations is activated by setting 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.

Metadata Entry

Each MetadataEntry represents a single key and value pair attached to an Event.

Field	Type	Description
key	string	The metadata entry key.
value	string	The metadata entry value.

A metadata entry allows storing arbitrary string key-value pairs alongside events. This is useful for storing provenance information, correlation IDs, causation IDs, or other contextual data that should be preserved with the event. Metadata is stored with the event and returned unchanged when the event is read. Each metadata key and value may be up to 65535 bytes long; appending an event with a longer key or value fails with a validation error.

Include in:

• Event to attach metadata.

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.

Authentication

UmaDB servers can be configured to require TLS and an API key for client requests. When enabled, clients must include the API key in the Authorization metadata of each gRPC request.

Authorization: Bearer <API_KEY>

Example (Python gRPC client)

import grpc

metadata = [('authorization', f'Bearer {API_KEY}')]
stub = UmaDBStub(channel)
response = stub.SomeRpcMethod(request, metadata=metadata)

Notes:

• Header keys are case-insensitive; the server will recognize Authorization, authorization, or any variation.
• The header value (Bearer <API_KEY>) is case-sensitive, so Bearer must be capitalized exactly as shown, with a single space between Bearer and the API key.
• Requests without a valid API key will be rejected with an UNAUTHENTICATED gRPC status, with status details showing an AUTHENTICATION error.
• Replace <API_KEY> with the key provided by the server administrator.

Error Response

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

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

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

Clients should attempt to read the status details attribute and deserialize an ErrorResponse message into a suitable error or exception, and it that fails, then fall back to using standard gRPC error status with the given message string.

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.