Struct FluentLoadQuery 

pub struct FluentLoadQuery<'a, E>
where
    E: EntityKind,
{ /* private fields */ }

FluentLoadQuery

Session-bound load query wrapper. Owns intent construction and execution routing only. All result inspection and projection is performed on Response<E>.

Implementations

impl<'a, E> FluentLoadQuery<'a, E>

where E: EntityKind,

pub const fn query(&self) -> &Query<E>

pub fn by_id(self, id: Id<E>) -> Self

Set the access path to a single typed primary-key value.

Id<E> is treated as a plain query input value here. It does not grant access.

pub fn by_ids<I>(self, ids: I) -> Self

where I: IntoIterator<Item = Id<E>>,

Set the access path to multiple typed primary-key values.

IDs are public and may come from untrusted input sources.

pub fn filter(self, predicate: Predicate) -> Self

pub fn filter_expr(self, expr: FilterExpr) -> Result<Self, QueryError>

pub fn sort_expr(self, expr: SortExpr) -> Result<Self, QueryError>

pub fn order_by(self, field: impl AsRef<str>) -> Self

pub fn order_by_desc(self, field: impl AsRef<str>) -> Self

pub fn limit(self, limit: u32) -> Self

Bound the number of returned rows.

Pagination is only valid with explicit ordering; combine limit and/or offset with order_by(...) or planning fails.

pub fn offset(self, offset: u32) -> Self

Skip a number of rows in the ordered result stream.

Pagination is only valid with explicit ordering; combine offset and/or limit with order_by(...) or planning fails.

pub fn cursor(self, token: impl Into<String>) -> Self

Attach an opaque cursor token for continuation pagination.

Cursor-mode invariants are checked before planning/execution:

• explicit order_by(...) is required
• explicit limit(...) is required

pub fn explain(&self) -> Result<ExplainPlan, QueryError>

pub fn plan(&self) -> Result<ExecutablePlan<E>, QueryError>

pub fn execute(&self) -> Result<Response<E>, QueryError>

where E: EntityValue,

Execute this query using the session’s policy settings.

pub fn page(self) -> Result<PagedLoadQuery<'a, E>, QueryError>

Enter typed cursor-pagination mode for this query.

Cursor pagination requires:

• explicit order_by(...)
• explicit limit(...)

Requests are deterministic under canonical ordering, but continuation is best-effort and forward-only over live state. No snapshot/version is pinned across requests, so concurrent writes may shift page boundaries.

pub fn execute_paged(self) -> Result<PagedLoadExecution<E>, QueryError>

where E: EntityValue,

Execute this query as cursor pagination and return items + next cursor.

The returned cursor token is opaque and must be passed back via .cursor(...).

pub fn is_empty(&self) -> Result<bool, QueryError>

where E: EntityValue,

Execute and return whether the result set is empty.

pub fn exists(&self) -> Result<bool, QueryError>

where E: EntityValue,

Execute and return whether at least one matching row exists.

pub fn count(&self) -> Result<u32, QueryError>

where E: EntityValue,

Execute and return the number of matching rows.

pub fn min(&self) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the smallest matching identifier, if any.

pub fn min_by( &self, field: impl AsRef<str>, ) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the id of the row with the smallest value for field.

Ties are deterministic: equal field values resolve by primary key ascending.

pub fn max(&self) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the largest matching identifier, if any.

pub fn max_by( &self, field: impl AsRef<str>, ) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the id of the row with the largest value for field.

Ties are deterministic: equal field values resolve by primary key ascending.

pub fn nth_by( &self, field: impl AsRef<str>, nth: usize, ) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the id at zero-based ordinal nth when rows are ordered by field ascending, with primary-key ascending tie-breaks.

pub fn sum_by( &self, field: impl AsRef<str>, ) -> Result<Option<Decimal>, QueryError>

where E: EntityValue,

Execute and return the sum of field over matching rows.

pub fn avg_by( &self, field: impl AsRef<str>, ) -> Result<Option<Decimal>, QueryError>

where E: EntityValue,

Execute and return the average of field over matching rows.

pub fn median_by( &self, field: impl AsRef<str>, ) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the median id by field using deterministic ordering (field asc, primary key asc).

Even-length windows select the lower median.

pub fn count_distinct_by( &self, field: impl AsRef<str>, ) -> Result<u32, QueryError>

where E: EntityValue,

Execute and return the number of distinct values for field over the effective result window.

pub fn min_max_by( &self, field: impl AsRef<str>, ) -> Result<Option<(Id<E>, Id<E>)>, QueryError>

where E: EntityValue,

Execute and return both (min_by(field), max_by(field)) in one terminal.

Tie handling is deterministic for both extrema: primary key ascending.

pub fn values_by( &self, field: impl AsRef<str>, ) -> Result<Vec<Value>, QueryError>

where E: EntityValue,

Execute and return projected field values for the effective result window.

pub fn take(&self, take_count: u32) -> Result<Response<E>, QueryError>

where E: EntityValue,

Execute and return the first k rows from the effective response window.

pub fn top_k_by( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Response<E>, QueryError>

where E: EntityValue,

Execute and return the top k rows by field under deterministic ordering (field desc, primary_key asc) over the effective response window.

This terminal applies its own ordering and does not preserve query order_by(...) row order in the returned rows. For k = 1, this matches max_by(field) selection semantics.

pub fn bottom_k_by( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Response<E>, QueryError>

where E: EntityValue,

Execute and return the bottom k rows by field under deterministic ordering (field asc, primary_key asc) over the effective response window.

This terminal applies its own ordering and does not preserve query order_by(...) row order in the returned rows. For k = 1, this matches min_by(field) selection semantics.

pub fn top_k_by_values( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Vec<Value>, QueryError>

where E: EntityValue,

Execute and return projected values for the top k rows by field under deterministic ordering (field desc, primary_key asc) over the effective response window.

Ranking is applied before projection and does not preserve query order_by(...) row order in the returned values. For k = 1, this matches max_by(field) projected to one value.

pub fn bottom_k_by_values( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Vec<Value>, QueryError>

where E: EntityValue,

Execute and return projected values for the bottom k rows by field under deterministic ordering (field asc, primary_key asc) over the effective response window.

Ranking is applied before projection and does not preserve query order_by(...) row order in the returned values. For k = 1, this matches min_by(field) projected to one value.

pub fn top_k_by_with_ids( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Vec<(Id<E>, Value)>, QueryError>

where E: EntityValue,

Execute and return projected id/value pairs for the top k rows by field under deterministic ordering (field desc, primary_key asc) over the effective response window.

Ranking is applied before projection and does not preserve query order_by(...) row order in the returned values. For k = 1, this matches max_by(field) projected to one (id, value) pair.

pub fn bottom_k_by_with_ids( &self, field: impl AsRef<str>, take_count: u32, ) -> Result<Vec<(Id<E>, Value)>, QueryError>

where E: EntityValue,

Execute and return projected id/value pairs for the bottom k rows by field under deterministic ordering (field asc, primary_key asc) over the effective response window.

Ranking is applied before projection and does not preserve query order_by(...) row order in the returned values. For k = 1, this matches min_by(field) projected to one (id, value) pair.

pub fn distinct_values_by( &self, field: impl AsRef<str>, ) -> Result<Vec<Value>, QueryError>

where E: EntityValue,

Execute and return distinct projected field values for the effective result window, preserving first-observed value order.

pub fn values_by_with_ids( &self, field: impl AsRef<str>, ) -> Result<Vec<(Id<E>, Value)>, QueryError>

where E: EntityValue,

Execute and return projected field values paired with row ids for the effective result window.

pub fn first_value_by( &self, field: impl AsRef<str>, ) -> Result<Option<Value>, QueryError>

where E: EntityValue,

Execute and return the first projected field value in effective response order, if any.

pub fn last_value_by( &self, field: impl AsRef<str>, ) -> Result<Option<Value>, QueryError>

where E: EntityValue,

Execute and return the last projected field value in effective response order, if any.

pub fn first(&self) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the first matching identifier in response order, if any.

pub fn last(&self) -> Result<Option<Id<E>>, QueryError>

where E: EntityValue,

Execute and return the last matching identifier in response order, if any.

pub fn require_one(&self) -> Result<(), QueryError>

where E: EntityValue,

Execute and require exactly one matching row.

pub fn require_some(&self) -> Result<(), QueryError>

where E: EntityValue,

Execute and require at least one matching row.

impl<E> FluentLoadQuery<'_, E>

where E: EntityKind + SingletonEntity, E::Key: Default,

pub fn only(self) -> Self