Bounded queries and bulk loads
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:
| Field | Bounds | Error |
|---|---|---|
timeout | The whole call: waiting, SQL and path search | DeadlineExceeded |
cancel | A token (Rust) or a key (bindings) you can trigger from elsewhere | Cancelled |
reader_timeout | The wait for a free read connection | PoolTimeout |
max_rows, max_bytes | Everything the call decodes, across all the statements it runs | ResultLimitExceeded |
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:
- Over a limit is an error, never a prefix. If the answer has 10 001 rows and the limit is 10 000, you get
ResultLimitExceeded, not the first 10 000. A silently cut answer looks like a complete one, and an agent would trust it. If you want a prefix, say so withLIMIT. - A stopped write leaves no trace.
transacttakes a budget too. If it is cancelled or runs out of time, the transaction rolls back and nothing is committed. - A stopped read gives back its connection. The reader pool does not leak, and the next call is not slowed down by the last one.
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).
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
- Each chunk is an ordinary transaction, with its own number in history. It commits or rolls back on its own.
- Chunks skip the statistics refresh.
finishruns one full analysis at the end, and the readers reload the new statistics. - The session holds the write lease. Other writes fail with
ImportInProgressuntil it ends. Reads go on, and see the last committed chunk. - Progress is counted.
progress()reports chunks, rejected chunks, asserted, existing and retracted rows, the transaction of every chunk, and the time spent.
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().
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:
| Note | Why it stayed in SQL |
|---|---|
cyclicLftjDisabled | The pattern is cyclic, but LFTJ is off |
lftjUnavailable | The operator is not installed on this connection |
lftjUnsupportedShape | The pattern is not a pure cyclic join the operator handles |
lftjBelowEstimate | The 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:
| Graph | Edges | Triangles | SQL | LFTJ | SQL / LFTJ |
|---|---|---|---|---|---|
| Uniform, out-degree 5 | 25 000 | 126 | 30.2 ms | 23.4 ms | 1.3× |
| 30 hubs × 150 spokes, both ways, plus noise | 13 960 | 620 | 143.3 ms | 11.8 ms | 12.1× |
| 3 layers of 40, 3 closing edges each | 3 317 | 14 040 | 12.5 ms | 5.7 ms | 2.2× |
| 3 layers of 80, 3 closing edges each | 13 034 | 56 160 | 88.2 ms | 23.3 ms | 3.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.
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
- Give agent-facing calls a budget. Errors are typed, results are never cut silently, and stopped writes leave no trace.
- Load large data in a bulk import session: chunked commits, one analysis at the end, and a write lease so nothing else interleaves.
- If your questions are cyclic and your graph is skewed, try
lftj=True, look atexplain, and measure on your own data.