pub struct Query {
pub resource: String,
pub params: Record,
pub load: Vec<String>,
pub tenant: Option<Value>,
pub limit: Option<u32>,
pub across_tenants: bool,
pub aggregate_names: Vec<String>,
pub computed: Vec<String>,
pub sort: Vec<SortKey>,
pub after: Option<Cursor>,
pub offset: Option<u32>,
}Expand description
A declarative read over a resource: its resource name plus an opaque bag of parameters the data layer interprets.
Build one with Query::new and add params; the fields are public, so refine
with struct-update syntax:
use ash_domain::query::Query;
let q = Query::new("note")
.param("done", false)
.param("limit", 10);What done and limit mean is up to the resource’s read
Preparations and the
DataLayer; the core attaches no semantics to
them.
Fields§
§resource: StringThe resource being read.
params: RecordThe opaque parameter bag the data layer interprets. May also carry the
executor’s reserved keys.
load: Vec<String>Relationships to load alongside each record. Resolved by the
Domain against the abstract data layer after the read;
a layer may also honour them natively.
tenant: Option<Value>The tenant this read is scoped to, if any. The domain sets it from the
Context for a tenant-scoped resource; a partitioning
layer can read it directly. It is a discriminator, not a filter param.
limit: Option<u32>A hard upper bound on the number of rows the layer may return, or None
for “the caller set no bound” — in which case the domain sets one from
DomainConfig::max_rows before the layer
ever sees the query.
This is not an ordinary param a layer may ignore: it is a contract
point like reserved::IN. A layer must return at most this many rows
(a SQL LIMIT, a scan cut short, a page size on an API call); the domain
verifies the count on the way back and fails the read with
Error::DataLayer if the layer overran it,
rather than truncating and hiding the breach.
Some(0) is a legitimate request for an empty result, not “unbounded” —
that is why this is a plain u32 and not a NonZeroU32.
across_tenants: boolWhether this is a sanctioned cross-tenant read — the domain dropped the
tenant predicate because the caller opted in via
Context::allow_cross_tenant. A
partitioning (Layer) data layer must read
across partitions when this is set; audit can see the read for what it is.
Never set on a global (non-tenant) resource — there is nothing to cross.
aggregate_names: Vec<String>Names of declared Aggregates to compute
alongside each row. Resolved by the domain; an unknown name is an error.
computed: Vec<String>Names of declared Computed fields to
compute for each row. Resolved by the domain; an unknown name is an error.
sort: Vec<SortKey>The sort order, outermost key first, or empty for “the layer’s natural order”.
Like limit this is a contract point, not an ordinary
param: a layer that cannot sort by these keys must say so
(Error::Unsupported) rather than return
rows in some other order, because a bounded read of unordered rows is an
arbitrary subset rather than a page. The domain validates every key names
a declared attribute before the layer sees it.
after: Option<Cursor>Resume a previous page: return only rows that fall after this cursor
in the query’s sort order.
Produced by Page::cursor from a previous read and passed back
verbatim. The layer decodes it with Cursor::keys and turns it into a
keyset predicate. Meaningless without a sort, which is why the domain
rejects the combination.
offset: Option<u32>Skip this many rows of the sorted result set before returning any — the offset of offset/limit pagination.
Like limit and sort this is a contract
point, not an ordinary param: a layer must skip exactly this many rows of
the order it was asked for (a SQL OFFSET, a scan advanced before
collecting), or decline with
Error::Unsupported.
Offset paging is the weaker of the two models the core offers, and
deliberately so: rows inserted or removed before the offset between two
pages shift every later row, so a caller walking pages can see a row
twice or miss it entirely. It is here because it buys what a cursor
cannot — random access to page n — which is what a numbered pager
needs. Prefer after whenever the caller only ever walks
forward. The two are mutually exclusive: a query carrying both describes
two different positions, and the domain rejects it.
Meaningless without a sort for the same reason limit
is — skipping rows of an arbitrary order yields an arbitrary subset — so
the domain rejects that combination too.
Implementations§
Source§impl Query
impl Query
Sourcepub fn new(resource: impl Into<String>) -> Self
pub fn new(resource: impl Into<String>) -> Self
Start a query against resource with an empty param bag.
Sourcepub fn param(self, key: impl Into<String>, value: impl Into<Value>) -> Self
pub fn param(self, key: impl Into<String>, value: impl Into<Value>) -> Self
Set a param in the bag, consuming and returning self for chaining.
Sourcepub fn limit(self, limit: u32) -> Self
pub fn limit(self, limit: u32) -> Self
Bound the read to at most limit rows.
The layer must honour it (see Query::limit); the domain checks that it
did. A caller-set bound is taken as deliberate and passed through
untouched — the domain’s own
max_rows ceiling only fills in for a
read that carries no bound of its own.
use ash_domain::Query;
let q = Query::new("note").limit(50);
assert_eq!(q.limit, Some(50));Sourcepub fn sort_asc(self, attribute: impl Into<String>) -> Self
pub fn sort_asc(self, attribute: impl Into<String>) -> Self
Sort the read by attribute, ascending — appending to any sort keys
already set, so repeated calls build a compound order.
use ash_domain::Query;
let q = Query::new("note").sort_asc("created_at").sort_desc("id");
assert_eq!(q.sort.len(), 2);Sourcepub fn sort_desc(self, attribute: impl Into<String>) -> Self
pub fn sort_desc(self, attribute: impl Into<String>) -> Self
Sort the read by attribute, descending. See
sort_asc.
Sourcepub fn after(self, cursor: Cursor) -> Self
pub fn after(self, cursor: Cursor) -> Self
Resume after cursor — the next page of the read that produced it.
The sort order must match the one the cursor came from; the domain refuses a cursor on an unsorted read, since there is no order to resume.
Sourcepub fn offset(self, offset: u32) -> Self
pub fn offset(self, offset: u32) -> Self
Skip the first offset rows of the sorted result set.
The offset-paging counterpart of after, and mutually
exclusive with it: page n of a numbered pager is
.offset(n * page_size).limit(page_size). Requires a
sort — the domain rejects an offset without one, since
skipping rows of an unordered read skips arbitrary rows. See
Query::offset for why a cursor is the better default.
use ash_domain::Query;
let q = Query::new("note").sort_asc("id").offset(50).limit(25);
assert_eq!(q.offset, Some(50));Sourcepub fn load<I, S>(self, relationships: I) -> Self
pub fn load<I, S>(self, relationships: I) -> Self
Request relationships be loaded alongside each row.
Sourcepub fn aggregates<I, S>(self, names: I) -> Self
pub fn aggregates<I, S>(self, names: I) -> Self
Request declared aggregates be computed for each row.
Sourcepub fn computed<I, S>(self, names: I) -> Self
pub fn computed<I, S>(self, names: I) -> Self
Request declared computed fields be computed for each row.
Sourcepub fn key_set(
resource: impl Into<String>,
attr: impl Into<String>,
keys: Vec<Value>,
) -> Self
pub fn key_set( resource: impl Into<String>, attr: impl Into<String>, keys: Vec<Value>, ) -> Self
Sourcepub fn as_key_set(&self) -> Option<(&str, &[Value])>
pub fn as_key_set(&self) -> Option<(&str, &[Value])>
Read this query’s IN key-set, if it carries one:
(attr, keys). A data layer calls this to honour an executor-issued
relationship load.
Sourcepub fn relates(
resource: impl Into<String>,
relationship: impl Into<String>,
predicate: Record,
) -> Self
pub fn relates( resource: impl Into<String>, relationship: impl Into<String>, predicate: Record, ) -> Self
Build an unresolved RELATES filter: rows related
through relationship to a row matching the predicate bag. The
Domain resolves this into a key-set before the layer
runs; see relates_filter.