Requests

A request queries or updates the database state.

A request consists of one or more events of the same type sent to the cluster in a single message. For example, a single request can create multiple transfers but it cannot create both accounts and transfers.

The cluster commits an entire request at once. Events are applied in series, such that successive events observe the effects of previous ones and event timestamps are totally ordered.

Each request receives one reply message from the cluster. The reply contains one result for each event in the request.

Request Types

create_accounts: create Accounts
create_transfers: create Transfers
lookup_accounts: fetch Accounts by id
lookup_transfers: fetch Transfers by id
get_account_transfers: fetch Transfers by debit_account_id or credit_account_id
get_account_balances: fetch the historical account balance by the Account’s id.
query_accounts: query Accounts
query_transfers: query Transfers

More request types, including more powerful queries, are coming soon!

Events and Results

Each request has a corresponding event and result type:

Request Type	Event	Result
`create_accounts`	`Account`	`CreateAccountResult`
`create_transfers`	`Transfer`	`CreateTransferResult`
`lookup_accounts`	`Account.id`	`Account` or nothing
`lookup_transfers`	`Transfer.id`	`Transfer` or nothing
`get_account_transfers`	`AccountFilter`	`Transfer` or nothing
`get_account_balances`	`AccountFilter`	`AccountBalance` or nothing
`query_accounts`	`QueryFilter`	`Account` or nothing
`query_transfers`	`QueryFilter`	`Transfer` or nothing

Idempotency

Events that create objects are idempotent. The first event to create an object with a given id will receive the ok result. Subsequent events that attempt to create the same object will receive the exists result.

Batching Events

To achieve high throughput, TigerBeetle amortizes the overhead of consensus and I/O by batching many events in each request.

In the default configuration, the maximum batch sizes for each request type are:

Request Type	Request Batch Size (Events)	Reply Batch Size (Results)
`lookup_accounts`	8190	8190
`lookup_transfers`	8190	8190
`create_accounts`	8190	8190
`create_transfers`	8190	8190
`get_account_transfers`	1	8190
`get_account_balances`	1	8190
`query_accounts`	1	8190
`query_transfers`	1	8190

TigerBeetle clients automatically batch events. Therefore, it is recommended to share the client instances between multiple threads or tasks to have events batched transparently.

Guarantees

A request executes within the cluster at most once.
Requests do not time out. Clients will continuously retry requests until they receive a reply from the cluster. This is because in the case of a network partition, a lack of response from the cluster could either indicate that the request was dropped before it was processed or that the reply was dropped after the request was processed. Note that individual pending transfers within a request may have timeouts.
Requests retried by their original client session receive identical replies.
Requests retried by a different client (same request body, different session) may receive different replies.
Events within a request are executed in sequence. The effects of a given event are observable when the next event within that request is applied.
Events within a request do not interleave with events from other requests.
All events within a request batch are committed, or none are. Note that this does not mean that all of the events in a batch will succeed, or that all will fail. Events succeed or fail independently unless they are explicitly linked
Once committed, an event will always be committed — the cluster’s state never backtracks.
Within a cluster, object timestamps are unique and strictly increasing. No two objects within the same cluster will have the same timestamp. Furthermore, the order of the timestamps indicates the order in which the objects were committed.

Edit this page