Tiramemsu

Bounded queries and bulk loads

Tiramemsu articles · 3 October 2026

This article is about the plumbing: what happens when a query takes too long, when a result is too big, when you need to load a million facts, and when a pattern is shaped like a triangle. None of it is exciting until it goes wrong. Then it decides whether your agent answers in a second or hangs until someone kills it.

Query budgets

By default every call is unbounded, as before. A QueryBudget puts limits on one call:

FieldBoundsError
timeoutThe whole call: waiting, SQL and path searchDeadlineExceeded
cancelA token (Rust) or a key (bindings) you can trigger from elsewhereCancelled
reader_timeoutThe wait for a free read connectionPoolTimeout
max_rows, max_bytesEverything the call decodes, across all the statements it runsResultLimitExceeded
from tiramemsu import QueryBudget, TiramemsuError

view = db.now().with_budget(QueryBudget(timeout_ms=500, max_rows=10_000))
try:
    rows = view.sparql("SELECT ?s ?o WHERE { ?s v:worksAt ?o }")
except TiramemsuError as e:
    if e.code == "ResultLimitExceeded":
        ...   # ask a narrower question, or add LIMIT

Three rules make budgets safe to use:

In Rust, a CancelToken can be cloned into another thread and cancelled there. QueryBudget::run(|| …) bounds a sequence of calls as one operation, so three queries share one deadline:

let budget = QueryBudget { timeout: Some(Duration::from_secs(1)), ..Default::default() };
let (rows, known) = budget.run(|| {
    let a = db.now().sparql("SELECT * WHERE { ?s ?p ?o }")?;
    let b = db.now().sparql("ASK { v:alice v:worksAt v:acme }")?;
    Ok::<_, Error>((a, b))
})?;

reader_timeout is separate from SQLite’s busy_timeout on purpose. One is “all readers are busy”, the other is “the file is locked”, and they need different fixes. Set a default for every read with OpenOptions::reader_timeout (reader_timeout_ms, readerTimeoutMs in the bindings).

Cancelling from Node.js and Python. The bindings are synchronous. Give the call a cancel_key (cancelKey), and db.cancel(key) stops it. In Python, call it from another thread; the GIL is released while a call runs. In Node.js, the same thread cannot run code during a call, so cancel only stops a call that starts later. Use a deadline there, and a fresh key per call.

The MCP server uses all of this: its --timeout-ms, --max-rows and --max-bytes flags become one budget per tool call.

Bulk import

Loading a lot of data used to leave two bad choices. One huge transaction holds the writer for the whole load, and a failure at the end throws everything away. Many small transactions are each fine, but every big commit triggers a full ANALYZE of the file, so a large load spends much of its time refreshing planner statistics it will throw away a moment later.

A bulk import session sits in between:

with db.bulk_import() as imp:              # finishes on a clean exit, cancels if the block raises
    for batch in batches:
        with imp.chunk() as tx:              # one atomic transaction
            for s, p, o in batch:
                tx.assert_(s, p, o)
        print(imp.progress().chunks, imp.progress().asserted)

s = imp.summary
print(s.progress.chunks, s.analyzed, s.maintenance_error)   # 4 True None

In Rust, chunk_with(opts, Some(&budget), f) bounds one chunk with a budget, and Db::bulk_import_shared takes an Arc<Db> and returns a session you can move to another thread. In Node.js, end the session in a finally block with finish() or cancel().

It is not one atomic import. A failing chunk rolls back alone; earlier chunks stay committed. Cancelling (or dropping the session in Rust) keeps the committed chunks, skips the analysis, and leaves statistics_due true until the next ordinary commit or optimize(). If the final analysis fails, that is reported in maintenance_error, and nothing is rolled back. Never-forget still holds: an import adds statements, like any other write.

Cyclic patterns and the leapfrog triejoin

Most graph questions are trees: start somewhere and branch out. Some are cycles. “Which of my contacts know each other?” is a triangle:

SELECT * WHERE { ?a v:knows ?b . ?b v:knows ?c . ?c v:knows ?a }

SQLite answers this with nested loops: for each a→b, for each b→c, check c→a. On a graph with hubs, the middle loop explodes, because a hub has thousands of neighbours and almost none of them close a triangle. A worst-case optimal join, such as the leapfrog triejoin (LFTJ), binds one variable at a time and intersects sorted lists of candidates, so it never builds the large intermediate result.

Tiramemsu 0.3 has an LFTJ operator. It runs inside SQLite as the table function tm_lftj, reading the same covering indexes, and it is off by default.

db = Database("memory.db", lftj=True)           # default threshold: 100 000 statements
db = Database("memory.db", lftj=True, lftj_min_rows=0)   # route every cyclic pattern

plan = db.now().explain_sparql("SELECT * WHERE { ?a v:knows ?b . ?b v:knows ?c . ?c v:knows ?a }")
[(r["kind"], r["note"]) for r in plan["regions"]]
# [('sql', 'none'), ('nativeLftj', 'lftjNative')]

In Rust it is OpenOptions { planner: PlannerOptions { lftj: LftjConfig { enabled: true, min_rows_estimate: 0 } }, ..OpenOptions::default() }, and in Node.js { lftj: true, lftjMinRows: 0 }.

The planner is careful about what it routes. A region goes to the operator only when LFTJ is enabled, the operator is installed, the pattern is a pure cyclic basic graph pattern of at most 32 variables, and at least one of its patterns matches min_rows_estimate statements or more. Otherwise it stays in SQL, and explain says why:

NoteWhy it stayed in SQL
cyclicLftjDisabledThe pattern is cyclic, but LFTJ is off
lftjUnavailableThe operator is not installed on this connection
lftjUnsupportedShapeThe pattern is not a pure cyclic join the operator handles
lftjBelowEstimateThe pattern is too small to be worth it

The answers are the same on both routes, including duplicate rows where SPARQL and Cypher expect them. Budgets still apply inside the operator.

The triangle benchmark

The repository has a harness, crates/tiramemsu/examples/triangles.rs. It loads a graph, opens the file twice (default options, and LFTJ on with a threshold of 0), checks that the second really routes to tm_lftj, and counts triangles on both routes. If the counts differ, it stops with an error. Only then does it time a COUNT(*) of the triangle pattern on each route, best of three.

cargo run --release -p tiramemsu --example triangles            # small: seconds
cargo run --release -p tiramemsu --example triangles -- full    # larger graphs

Results at the small scale, on an Apple M2 Max with bundled SQLite, 3 October 2026:

GraphEdgesTrianglesSQLLFTJSQL / LFTJ
Uniform, out-degree 525 00012630.2 ms23.4 ms1.3×
30 hubs × 150 spokes, both ways, plus noise13 960620143.3 ms11.8 ms12.1×
3 layers of 40, 3 closing edges each3 31714 04012.5 ms5.7 ms2.2×
3 layers of 80, 3 closing edges each13 03456 16088.2 ms23.3 ms3.8×

The counts were identical on both routes for every graph. The pattern matches each directed triangle once per rotation, so the counts are three times the distinct triangles. The pattern is the one you would expect: on a uniform graph the two routes are close, and on the hub-and-spoke graph, where nested loops waste most of their work, the intersection join is twelve times faster.

Read these numbers with care. They are small graphs on one machine, generated by hand, not a real data set. The LFTJ times include each pattern’s ordered scan. The full scale has not been measured for the operator yet, for a known reason: the operator materialises its output rows before SQLite reads them, so layered graphs with 0.8 and 3.2 million output rows would hold hundreds of megabytes during the count. Streaming the output is still to do. That is also why LFTJ stays off by default, and why its threshold is high.

An earlier, pure-Python version of the same idea (bench/triangles/bench.py) measured larger graphs against SQLite’s plan: on the 1.1-million-edge hub graph, 79.6 s for nested loops against 1.9 s for an intersection join written in plain Python. That is the evidence that led to the operator, not a measurement of it.

Summary

Back to what’s new in 0.3 →