Checkout: a whole cart in one query¶
A shop sells items from stock to accounts that pay from a balance. A checkout takes a whole cart. Every line must be in stock and the account must cover the total. Then every stock, the balance and the order lines change together, or nothing changes.
This page builds that checkout with a staged transaction. The same program
runs in Python, TypeScript, Rust and C, directly and through the proxy. It
is the shop program of the writes conformance suite, so its plans, answers
and stored state are compared across all four languages in CI.
Why one query¶
The obvious version reads first and writes later. With two buyers of the last book:
buyer A read book stock 1 check passes
buyer B read book stock 1 check passes
buyer A write book stock 0, order
buyer B write book stock 0, order the book is sold twice
``` A transaction alone does not fix this when the check
only reads (see [what conflicts](concurrency.md#what-conflicts)).
Put the check and the write in the same query instead. The query matches the
account and every item, compares the stock and the balance, computes the new
values, and writes them, all in one TypeQL pipeline on one snapshot.
Concurrent buyers write the same `stock` or `balance`, so TypeDB lets only
one of them commit; the other gets a conflict it can retry.
## The cart as one plan
Each cart line adds an item binding, a stock check and its cost to the
total. After the loop, one more check compares the balance with the total.
Then the plan writes every new stock, the new balance and one `order-line`
per item:
```python title="Python"
def checkout(authority: Any, account_id: str, order_id: str, cart: list[tuple[str, int]]) -> Plan:
"""The whole cart in one query: check every line and the total, then write."""
plan = Plan.builder()
buyer = plan.exact(Account)
balance = plan.field(buyer, Account.balance)
plan.where_(plan.field(buyer, Account.account_id).eq(account_id))
lines = []
costs = []
for sku, quantity in cart:
item = plan.exact(Item)
stock = plan.field(item, Item.stock)
plan.where_(plan.field(item, Item.sku).eq(sku)).where_(stock.ge(quantity))
costs.append(plan.field(item, Item.price) * quantity)
lines.append((item, stock, quantity))
cart_total = costs[0]
for cost in costs[1:]:
cart_total = cart_total + cost
total = plan.let_("total", cart_total)
plan.where_(balance.ge(total))
for number, (item, stock, quantity) in enumerate(lines, start=1):
plan.update(item, Item.stock, plan.let_(f"stock_{number}", stock - quantity))
plan.update(buyer, Account.balance, plan.let_("balance_after", balance - total))
for item, _, quantity in lines:
(
plan.insert(OrderLine)
.field(OrderLine.order_id, order_id)
.field(OrderLine.quantity, quantity)
.player(OrderLine.buyer, buyer)
.player(OrderLine.item, item)
)
return plan.build(authority)
/** The whole cart in one query: check every line and the total, then write. */
function checkout(
authority: QueryV2Authority,
accountId: string,
orderId: string,
cart: readonly CartLine[],
): Built {
const plan = Plan.builder();
const buyer = plan.exact(Account);
const balance = plan.field(buyer, Account.fields.balance);
plan.where(plan.field(buyer, Account.fields.accountId).eq(accountId));
const lines = cart.map(([sku, quantity]) => {
const item = plan.exact(Item);
const stock = plan.field(item, Item.fields.stock);
plan.where(plan.field(item, Item.fields.sku).eq(sku)).where(stock.ge(quantity));
const cost = plan.field(item, Item.fields.price).mul(quantity);
return { item, stock, quantity, cost };
});
// Expressions are built lazily, so summing after the loop is the same plan.
const total = plan.let(
"total",
lines.map((line) => line.cost).reduce((sum, cost) => sum.add(cost)),
);
plan.where(balance.ge(total));
lines.forEach(({ item, stock, quantity }, index) => {
plan.update(item, Item.fields.stock, plan.let(`stock_${index + 1}`, stock.sub(quantity)));
});
plan.update(buyer, Account.fields.balance, plan.let("balance_after", balance.sub(total)));
for (const { item, quantity } of lines) {
plan
.insert(OrderLine)
.field(OrderLine.fields.orderId, orderId)
.field(OrderLine.fields.quantity, quantity)
.player(OrderLine.roles.buyer, buyer)
.player(OrderLine.roles.item, item);
}
return plan.build(authority);
}
/// The whole cart in one query: check every line and the total, then write.
fn checkout(account_id: &str, order_id: &str, cart: &[(&str, i64)]) -> Result<Built> {
let mut plan = Plan::builder();
let buyer = plan.exact::<Account>();
let balance = plan.field(buyer, AccountType::balance);
let buyer_key = plan.field(buyer, AccountType::account_id);
plan.where_(buyer_key.eq(account_id.to_owned()));
let mut lines = Vec::new();
let mut total: Option<Expr> = None;
for &(sku, quantity) in cart {
let item = plan.exact::<Item>();
let stock = plan.field(item, ItemType::stock);
let item_key = plan.field(item, ItemType::sku);
plan.where_(item_key.eq(sku.to_owned()))
.where_(stock.ge(quantity));
let cost = plan.field(item, ItemType::price) * quantity;
total = Some(match total {
None => cost,
Some(total) => total + cost,
});
lines.push((item, stock, quantity));
}
let total = plan.let_("total", total.expect("a cart has at least one line"));
plan.where_(balance.ge(total));
for (number, &(item, stock, quantity)) in (1..).zip(&lines) {
let next_stock = plan.let_(&format!("stock_{number}"), stock - quantity);
plan.update(item, ItemType::stock, next_stock);
}
let balance_after = plan.let_("balance_after", balance - total);
plan.update(buyer, AccountType::balance, balance_after);
for &(item, _, quantity) in &lines {
plan.insert::<OrderLine>()
.field(OrderLineType::order_id, order_id.to_owned())
.field(OrderLineType::quantity, quantity)
.player(OrderLineType::buyer, buyer)
.player(OrderLineType::item, item);
}
plan.build(&models::SCHEMA)
}
/* The whole cart in one query: check every line and the total, then write. */
static type_bridge_status_t checkout(type_bridge_plan_builder_t *plan, const identities_t *id,
const char *account_id, const char *order_id,
const line_t *lines, size_t count) {
type_bridge_status_t status;
uint32_t buyer, balance, key, value, total_expr = 0u, total, expr, next, order;
uint32_t items[MAX_LINES], stocks[MAX_LINES];
char name[24];
size_t index;
if (count == 0u || count > MAX_LINES) return TYPE_BRIDGE_STATUS_INVALID_ARGUMENT;
CHECK(type_bridge_plan_builder_exact(plan, id->account, &buyer));
CHECK(type_bridge_plan_builder_field(plan, buyer, id->balance, &balance));
CHECK(type_bridge_plan_builder_field(plan, buyer, id->account_id, &key));
CHECK(type_bridge_plan_builder_value_string(plan, view(account_id), &value));
CHECK(against(plan, key, TYPE_BRIDGE_PLAN_COMPARE_EQUAL, value));
for (index = 0u; index < count; ++index) {
uint32_t price, cost;
CHECK(type_bridge_plan_builder_exact(plan, id->item, &items[index]));
CHECK(type_bridge_plan_builder_field(plan, items[index], id->stock, &stocks[index]));
CHECK(type_bridge_plan_builder_field(plan, items[index], id->sku, &key));
CHECK(type_bridge_plan_builder_value_string(plan, view(lines[index].sku), &value));
CHECK(against(plan, key, TYPE_BRIDGE_PLAN_COMPARE_EQUAL, value));
CHECK(type_bridge_plan_builder_value_long(plan, lines[index].quantity, &value));
CHECK(against(plan, stocks[index], TYPE_BRIDGE_PLAN_COMPARE_GREATER_OR_EQUAL, value));
/* cost = price * quantity; total = cost, or total + cost. */
CHECK(type_bridge_plan_builder_field(plan, items[index], id->price, &price));
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_MUL,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, price,
TYPE_BRIDGE_PLAN_OPERAND_VALUE, value, &cost));
if (index == 0u) {
total_expr = cost;
} else {
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_ADD,
TYPE_BRIDGE_PLAN_OPERAND_EXPR, total_expr,
TYPE_BRIDGE_PLAN_OPERAND_EXPR, cost, &total_expr));
}
}
CHECK(type_bridge_plan_builder_let(plan, view("total"), TYPE_BRIDGE_PLAN_OPERAND_EXPR,
total_expr, &total));
CHECK(type_bridge_plan_builder_compare(plan, TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance,
TYPE_BRIDGE_PLAN_COMPARE_GREATER_OR_EQUAL,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, total));
for (index = 0u; index < count; ++index) {
snprintf(name, sizeof(name), "stock_%u", (unsigned)(index + 1u));
CHECK(type_bridge_plan_builder_value_long(plan, lines[index].quantity, &value));
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, stocks[index],
TYPE_BRIDGE_PLAN_OPERAND_VALUE, value, &expr));
CHECK(type_bridge_plan_builder_let(plan, view(name), TYPE_BRIDGE_PLAN_OPERAND_EXPR, expr,
&next));
CHECK(type_bridge_plan_builder_update(plan, items[index], id->stock,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, next));
}
CHECK(type_bridge_plan_builder_expr_arith(plan, TYPE_BRIDGE_PLAN_ARITH_SUB,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, balance,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, total, &expr));
CHECK(type_bridge_plan_builder_let(plan, view("balance_after"), TYPE_BRIDGE_PLAN_OPERAND_EXPR,
expr, &next));
CHECK(type_bridge_plan_builder_update(plan, buyer, id->balance,
TYPE_BRIDGE_PLAN_OPERAND_BINDING, next));
for (index = 0u; index < count; ++index) {
CHECK(type_bridge_plan_builder_insert(plan, id->order_line, &order));
CHECK(type_bridge_plan_builder_value_string(plan, view(order_id), &value));
CHECK(set_value(plan, order, id->order_id, value));
CHECK(type_bridge_plan_builder_value_long(plan, lines[index].quantity, &value));
CHECK(set_value(plan, order, id->quantity, value));
CHECK(type_bridge_plan_builder_thing_player(plan, order, id->buyer, buyer));
CHECK(type_bridge_plan_builder_thing_player(plan, order, id->item_role, items[index]));
}
done:
return status;
}
For the cart pen x2, book x1 this plan becomes one query of this shape:
match
$buyer isa! account, has account-id "A1", has balance $balance;
$item isa! item, has sku "pen", has stock $stock, has price $price;
$stock >= 2;
$item_2 isa! item, has sku "book", has stock $stock_2, has price $price_2;
$stock_2 >= 1;
let $total = $price * 2 + $price_2 * 1;
$balance >= $total;
let $stock_1 = $stock - 2;
let $stock_2_after = $stock_2 - 1;
let $balance_after = $balance - $total;
update
$item has stock == $stock_1;
$item_2 has stock == $stock_2_after;
$buyer has balance == $balance_after;
insert
(buyer: $buyer, item: $item) isa order-line, has order-id "O1", has quantity 2;
(buyer: $buyer, item: $item_2) isa order-line, has order-id "O1", has quantity 1;
The variable names are illustrative; the plan derives its own.
Stage, then commit once¶
A staged transaction sends nothing while you stage. commit runs every
staged plan in one TypeDB transaction and commits it, and only then does each
plan's answer arrive:
def run(transaction: Any, plans: dict[str, Plan], names: tuple[str, ...]) -> dict[str, Any]:
"""Stage `names` in one transaction, commit once, and read their answers."""
with transaction as tx:
pending = {name: tx.stage(plans[name]) for name in names}
# The block committed; each answer is known only now.
return {name: answer(item.result()) for name, item in pending.items()}
Through the proxy, the whole transaction is one request.
Read the answer¶
A failed check is not an error. If any line is out of stock, or the balance
is short, the match is empty: nothing is written, the commit succeeds, and
the plan answers Matched(0). A completed checkout answers Matched(1).
Always check it.
The program runs these steps, each in its own transaction:
| Step | Cart | Answer | Why |
|---|---|---|---|
| checkout | A1: pen x2, book x1 (46 of 100) | Matched(1) |
in stock, balance covers it |
| sold out | A2: mug x1, book x1 | Matched(0) |
the book is sold out, so the mug is not taken either |
| short | A2: mug x3 (36 of 30) | Matched(0) |
the balance is short |
| two carts | A2: mug x1 (12), then pen x6 (18) | Matched(1), Matched(1) |
the second cart sees the first one's charge |
| race | eight buyers, one lamp in stock | one Matched(1), seven Matched(0) |
see when the commit fails |
One plan or several¶
Plans staged in one transaction commit together, and each one sees the writes staged before it: in the last step, the pen cart sees a balance of 18 after the mug cart's charge. But each plan's check is its own. A plan that matches nothing does not stop the others, and they still commit.
So:
- Put every check that must gate the purchase in the same plan as its writes. A cart is one plan.
- Stage several plans in one transaction when each is complete on its own and they should commit together, such as two independent carts or a cart and an audit record that does not depend on it.
When the commit fails¶
A lost race is a typed conflict at commit, and nothing from the transaction
is stored. When retry_safe is true, run the whole transaction again; it
reads a fresh snapshot, so the retried checkout sees the stock the winner
left.
The program's race step shows it. Eight buyers check out the last lamp at the same moment, each in its own transaction. Every buyer stages first, then all commit together:
def race(open_transaction: Callable[[], Any], plan: Plan) -> list[Any]:
"""BUYERS buyers commit `plan` at once; answer the sum of their matched counts.
Each buyer stages the plan in its own transaction and waits until every
buyer has staged, so the commits overlap. A buyer that loses the race gets
a retry-safe conflict and nothing it staged is stored; it runs the whole
transaction again on a fresh snapshot, where the lamp is gone.
"""
ready = threading.Barrier(BUYERS, timeout=120)
matched = [0] * BUYERS
errors: list[BaseException] = []
conflicts: list[int] = []
def buyer(index: int) -> None:
try:
for attempt in range(ATTEMPTS):
try:
with open_transaction() as tx:
bought = tx.stage(plan)
if attempt == 0:
ready.wait()
_, matched[index] = answer(bought.result())
return
except (CommitRejected, MatchRequestError) as error:
# A lost race is a typed conflict: CommitConflict on a
# direct commit, a MatchRequestError carrying the same
# failure through the proxy.
if not lost_race(error) or attempt + 1 == ATTEMPTS:
raise
conflicts.append(index)
except BaseException as error: # reported by the main thread
errors.append(error)
ready.abort()
threads = [threading.Thread(target=buyer, args=(index,)) for index in range(BUYERS)]
for thread in threads:
thread.start()
for thread in threads:
thread.join()
if errors:
raise errors[0]
# Diagnostic only: how many commits lost and were retried varies by run.
print(f"race: {len(conflicts)} conflicts retried", file=sys.stderr)
return ["matched", sum(matched)]
One commit wins. The other seven lose with a retry-safe conflict, run again,
find the lamp sold out and answer Matched(0). The sum of the answers is
exactly 1, the lamp's stock is 0, the account is charged once and there is
one order line, in every language and through the proxy. Commit, and retry a conflict
shows the loop, and Typed failures lists the
outcomes, including the unknown outcome a proxy can report.
Run it¶
The programs are examples/shop/{python,ts,rust,c}, and their schema is the
workspace in tests/contracts/sdk_conformance/writes/shop. Against a TypeDB
3.13.6 server:
uv run python scripts/ci/run_sdk_conformance.py writes \
--semantic-profile typedb-3.13.6/v1 --address localhost:1729 \
--http-port 8000 --output tmp/sdk-writes
The runner generates the four packages, runs every writes program directly and through a proxy, and compares their reports.