Journeys that respect time
Ana tells Ben a secret on the 2nd of March. Ben meets Cara on the 5th. Cara met Dan on the 1st. Who could know the secret?
Ben and Cara, but not Dan: Cara met Dan before she could have heard it. Any person gets this right. A plain graph path gets it wrong, because met+ follows edges without looking at when they happened. It says Dan, too. This article is about asking that question correctly in SPARQL and Cypher, and about knowing whether a path answer is complete.
The data
Each meeting is a statement with a valid time: the day it happened, as a half-open interval. Ben also met Eve, in February, long before Ana spoke to him.
with db.transact() as tx:
tx.assert_(ana, met, ben, valid_from="2026-03-02", valid_to="2026-03-03")
tx.assert_(ben, met, cara, valid_from="2026-03-05", valid_to="2026-03-06")
tx.assert_(cara, met, dan, valid_from="2026-03-01", valid_to="2026-03-02")
tx.assert_(ben, met, eve, valid_from="2026-02-20", valid_to="2026-02-21")
A plain path from Ana finds everyone:
db.now().sparql("SELECT ?who WHERE { v:ana v:met+ ?who }")
# ben, cara, dan, eve
The hop rule
A time-respecting path, or journey, carries a clock τ. It starts at a time you give, or at minus infinity. A hop over a statement valid during [from, to) is allowed only if the statement is still valid after τ (to > τ, or no end). Taking the hop moves the clock to max(τ, from): you cannot use a meeting before it happens, so you wait for it. The clock never goes back.
Start at the 1st of March. Ana meets Ben on the 2nd: allowed, the clock moves to the 2nd. Ben meets Cara on the 5th: allowed, clock at the 5th. Cara met Dan on the 1st, and that interval ended on the 2nd: not allowed. Ben met Eve in February: not allowed. The answer is Ben and Cara.
The time when the walk reaches a node is its arrival. A longer walk can arrive earlier than a shorter one, so the engine keeps the earliest arrival for each node and goes on while some node improves.
In SPARQL
A SERVICE scope turns every property path inside it into a journey. tm:arrival binds the earliest arrival at the end of a path.
SELECT ?who ?t WHERE {
SERVICE <urn:tiramemsu:tm:timeRespecting/2026-03-01> {
v:ana v:met+ ?who .
?who tm:arrival ?t
}
} ORDER BY ?t
# who t
# ben 1772409600000 (2026-03-02)
# cara 1772668800000 (2026-03-05)
- The start goes after the slash: epoch milliseconds, an
xsd:datesuch as2026-03-01(midnight UTC), anxsd:dateTime, or$namefor a parameter. Leave it out to start at minus infinity. - Parameters come from the call:
params={"since": "2026-03-01"}in Python,{ params: { since: "2026-03-01" } }in Node.js,SparqlOptions::paramsin Rust, withtimeRespecting/$sincein the query. - Arrivals are integers of epoch milliseconds. With no start and no valid time on any hop, the arrival is minus infinity and
?tstays unbound. - Which paths count. Anything with
*,+,?,^or|. A plain sequencev:a/v:bis split into triple patterns by the parser and is not a journey. Write(v:a/v:b)+if you mean one. - Other scopes still apply. Nest it in
SERVICE <urn:tiramemsu:tm:asOf/150>to ask what the journeys looked like by what we knew at transaction 150.GRAPHandFROMstill restrict every hop.
In Cypher
Cypher gets a modifier on MATCH. AFTER sets the start and ARRIVAL AS names the arrival.
MATCH TIME RESPECTING AFTER date('2026-03-01') ARRIVAL AS t
(a {`@id`: 'v:ana'})-[:met*]->(who)
RETURN who, min(t) AS arrived ORDER BY arrived
AFTER takes an integer, a $parameter, datetime('…') or date('…'). A Cypher variable-length pattern walks trails, so each row has the arrival of its own trail; min(t) gives the earliest per person. The result is the same two people.
From code
The query languages and the API run on the same engine, so they agree. In the bindings, path takes a time_respecting start (Python) or timeRespecting (Node.js), and in Rust PathArgs::time_respecting:
rep = db.now().path_report(ana, "met+", time_respecting="2026-03-01")
[row.end for row in rep.rows] # [ben, cara]
Was the answer complete?
Path searches have limits, and a cut answer looks just like a full one. So every path search now reports a verdict, and queries return it when asked (path_completeness=True, pathCompleteness: true, or Solutions::path_completeness in Rust):
| Kind | Means | Complete? |
|---|---|---|
exhaustive | Nothing was left to explore | Yes |
bound | A hop bound you asked for stopped it, with more left to explore | Yes, within the bound you asked for |
cap | The database’s path_max_hops cut an unbounded pattern | No: longer paths may exist |
The difference between bound and cap is who set the limit. If you asked for at most one hop, a one-hop answer is what you wanted:
db.now().path_report(ana, "met+", max_hops=1).completeness
# PathCompleteness(kind='bound', max_hops=1, complete=True)
A Cypher * has no upper bound in the query, but it walks trails, so the engine cuts it at path_max_hops (15 by default). If the cut leaves anything unexplored, the verdict is cap. Here is a chain Ana → Ben → Cara on a database opened with path_max_hops=1:
db.now().cypher("MATCH (a {`@id`: 'v:ana'})-[:met*]->(who) RETURN who", path_completeness=True)
# rows: ben only
# PathCompleteness(kind='cap', max_hops=1, complete=False)
Two cases that may surprise:
- A SPARQL
+or*asks for reachability, which is finite, so it is not capped and reportsexhaustive. - A bounded pattern such as Cypher
*1..2carries its bound in the pattern itself. When the pattern has no move left, the search isexhaustivefor what the pattern asked, even if longer chains exist in the data.
Running out of the search-state budget (path_max_states) is never a verdict. It is the error PathLimitExceeded, so a huge search never comes back as a partial answer.
Limits
- A journey runs forward, so its start must be bound. A path bound only at its end is refused as unsupported.
- The clock is valid time. A statement with no valid time is valid forever: it never blocks a hop and never moves the clock.
- These are opt-in extensions of SPARQL and Cypher. Other stores will not understand them.
Why an agent wants this
Agents reason about causes. Could this email have influenced that decision? Could this person have known about the change when they signed? Which tasks were unblocked in time? Each one is a chain of events that must happen in order. A plain path answers a different, easier question, and an agent that does not know the difference will be confidently wrong. A journey answers the real question, says when each step became possible, and says whether it looked far enough.