pub struct RowRange { /* private fields */ }Expand description
One entry of a path’s ranges attribute: which rows to read.
Built three ways, one per selector the rich YPath reference defines:
RowRange::rows— by row index; plain Rust ranges convert viaInto, sopath.range(0..100)reads as it would on a slice;RowRange::keys— by key, on a sorted table;RowRange::exact_key— exactly the rows whose key starts with a tuple.
A range never mixes exact with a lower or upper limit, because no
constructor can express that — the reference defines them as alternatives.
Implementations§
Source§impl RowRange
impl RowRange
Sourcepub fn rows(rows: impl RangeBounds<i64>) -> Self
pub fn rows(rows: impl RangeBounds<i64>) -> Self
Rows by index: rows(0..100), rows(100..), rows(..).
Rust range semantics and the cluster’s are the same — lower_limit is
inclusive and upper_limit exclusive for a row_index (the reference:
“All limit types except for key_bound are inclusive in the
lower_limit attribute and exclusive in the upper_limit
attribute”) — so 0..2 means rows 0 and 1 on both sides of the wire,
and ..=2 rows 0 through 2.
Sourcepub fn keys(keys: impl RangeBounds<Key>) -> Self
pub fn keys(keys: impl RangeBounds<Key>) -> Self
Rows by key, on a sorted table.
Takes a Rust range of Keys, and the inclusivity travels with it:
keys(a..b)— fromainclusive tobexclusive. These are the spellings thekeyselector has natively (inclusive inlower_limit, exclusive inupper_limit), so they are sent as{key=[…]}, exactly what the Go SDK’sypath.Keysends.keys(a..=b)— inclusive upper bound. Thekeyselector cannot say that, so it is sent as the cluster’skey_boundform,{key_bound=["<="; […]]}; an exclusive lower bound ((Bound::Excluded(a), …)) likewise becomes{key_bound=[">"; […]]}. The reference defineskey_boundas[relation; prefix]with>>=allowed only inlower_limitand<<=only inupper_limit, and this constructor is what makes the wrong pairing unwritable.
A key shorter than the table’s key columns is a prefix bound — and the two selectors compare a prefix by opposite rules.
key compares the row’s whole key against the bound component-wise,
the shorter tuple being smaller when equal so far. key_bound does
not: the reference says the row’s key is first truncated to the
bound’s length — “we need to extract a prefix of length K from that
key and perform a lexicographic comparison” — after which every row
sharing the prefix compares equal to the bound. So <= takes that
whole group and > drops that whole group, and the practical
consequence is that a..b and a..=b differ by a group of rows
rather than by one row.
Measured on a local cluster, on a table keyed (host, path) holding
(a,/x) (a,/y) (b,/x) (b,/y) (c,/x):
| asked for | sent | rows back |
|---|---|---|
keys(a..b) | {key=[a]} … {key=[b]} | (a,/x) (a,/y) |
keys(a..=b) | {key=[a]} … {key_bound=["<=";[b]]} | (a,/x) (a,/y) (b,/x) (b,/y) |
keys((Excluded(a), Unbounded)) | {key_bound=[">";[a]]} | (b,/x) (b,/y) (c,/x) |
keys(a..=a) | {key=[a]} … {key_bound=["<=";[a]]} | (a,/x) (a,/y) |
The third row is the one to remember: an exclusive lower bound on a
prefix excludes every row of that prefix, not the one row equal to
it — there is no “the row just after a” for the cluster to start
from. Give a full key if you want a single row skipped.
The second row settles the other question a mixed range raises: an
entry carrying key on one side and key_bound on the other is
accepted — the same local cluster answered it 200 with the rows
above — so the most natural inclusive spelling needs no workaround.
Sourcepub fn exact_key(key: impl Into<Key>) -> Self
pub fn exact_key(key: impl Into<Key>) -> Self
Exactly the rows whose full key starts with key.
The exact selector of the reference: “only returns those rows where
the full key contains the key tuple as its prefix”. On a table keyed
by (host, path), exact_key(Key::from("example.com")) is every row
of that host — the same rows keys(k..=k) selects, measured on a
local cluster against the table in RowRange::keys, said in the
cluster’s own word for it.