Expand description
What a read asks for, stated once (§16, F-34).
Three qualifiers appear on every read surface in this crate — the lineage,
the valid-time instant, the transaction-time instant — and until 0.15.9
each surface spelled them itself. TraversalBuilder carries three
fields, query_as_of_edges_on takes two positional arguments and cannot
express the third at all, and the Python binding repeats the set as
keywords on five entry points. Nothing was wrong with any one of them; what
was wrong is that “read exp as it stood on Tuesday, under what we believed
in March” was a sentence the crate could not hold as a value, so it could
not be passed, stored, compared, or given a default.
ReadPlan is that value. It is caller-facing and deliberately dumb: it
holds four Options and knows no SQL. The lowering that turns a read into
CTEs lives in graph::plan and stays crate-private, which is why there are
two modules called plan and only one of them is a public path. The
division is the useful one — this module is what was asked, that one is
how it is answered, and a caller who never reads SQL should never meet
the second.
§The fourth qualifier, and the promise 0.15.9 made about it
limit was in the 0.16.0 plan’s sketch of this struct and was left out of
0.15.9 on the grounds that a public knob that silently does nothing is the
one failure mode a plan value has that three loose arguments do not — a
caller can see an argument go unused at a call site and cannot see a field
go unread. #[non_exhaustive] made it additive on the day it meant
something, and 0.15.10 (D-252) is that day: it bounds the walk from
inside the recursive CTE, and every surface that takes a plan reads it.
It is not a fourth temporal qualifier and it does not compose like one.
The other three narrow which rows are true; this one says how much of the
answer to pay for, so two reads under the same plan can differ. That is
stated on ReadPlan::limit() rather than smoothed over, and it is why
the walk reports whether the ceiling bit
(WalkOutcome) where it never had to report
on an instant.
Structs§
- Read
Plan - The lineage, the two instants, and the ceiling a read is taken under.