Skip to main content

Query

Struct Query 

Source
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: String

The resource being read.

§params: Record

The 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: bool

Whether 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

Source

pub fn new(resource: impl Into<String>) -> Self

Start a query against resource with an empty param bag.

Source

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.

Source

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));
Source

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);
Source

pub fn sort_desc(self, attribute: impl Into<String>) -> Self

Sort the read by attribute, descending. See sort_asc.

Source

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.

Source

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));
Source

pub fn load<I, S>(self, relationships: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Request relationships be loaded alongside each row.

Source

pub fn aggregates<I, S>(self, names: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Request declared aggregates be computed for each row.

Source

pub fn computed<I, S>(self, names: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Request declared computed fields be computed for each row.

Source

pub fn key_set( resource: impl Into<String>, attr: impl Into<String>, keys: Vec<Value>, ) -> Self

Build the reserved IN key-set query: rows of resource whose attr is one of keys. The executor uses this for relationship loads; a layer reads it back with key_set.

Source

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.

Source

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.

Source

pub fn relates_filter(&self) -> Option<(&str, Record)>

Read this query’s unresolved RELATES filter, if it carries one: (relationship, predicate). The domain uses this to decide whether relationship-filter resolution is needed before a read.

Trait Implementations§

Source§

impl Clone for Query

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Query

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Query

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl From<Filter> for Query

A Filter is a Query with no resource name; the executor stamps the resource of the action it runs against (it does so for every read).

Source§

fn from(filter: Filter) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

§

impl !Freeze for Query

§

impl Forget for Query

§

impl Move for Query

§

impl RefUnwindSafe for Query

§

impl Send for Query

§

impl Sync for Query

§

impl Unpin for Query

§

impl UnsafeUnpin for Query

§

impl UnwindSafe for Query

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<B> FromRef<B> for B
where B: Clone,

Source§

fn from_ref(backend: &B) -> B

Extract a Self from a reference to the composite backend B.
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.