Struct QueryBuilder 

pub struct QueryBuilder<T: IEntityType> { /* private fields */ }

A chainable query builder for entity type T.

Corresponds to EFCore’s IQueryable<T>.

Clone is derived so that builders can be forked for compositional reuse (e.g. applying additional filters on a base query without losing the original). Note that single/single_or_default still use the take(2) approach rather than clone().count() to avoid a double round-trip.

Implementations

impl<T: IEntityType> QueryBuilder<T>

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

Creates a new QueryBuilder for a given table (without provider — SQL-only).

pub fn with_provider( table_name: impl Into<String>, provider: Arc<dyn IDatabaseProvider>, ) -> Self

Creates a new QueryBuilder for a given table with a provider for execution.

pub fn state(&self) -> &QueryState

Returns a reference to the accumulated query state.

pub fn filter(self, f: impl FnOnce(Self) -> Self) -> Self

Applies a compile-time LINQ expression tree from linq!(?).

impl<T: IEntityType> QueryBuilder<T>

pub fn distinct(self) -> Self

Marks this query as SELECT DISTINCT.

pub fn where_exists_internal( self, nav_field: &'static str, related_type: &'static str, predicate: Option<BoolExpr>, negated: bool, ) -> Self

G5: Adds an EXISTS (or NOT EXISTS) correlated subquery condition.

#[doc(hidden)] — called by linq! expansion of b.posts.any(|p| p.published) / b.posts.none(...) / b.posts.all(...).

The nav_field and related_type arguments are the &'static str constants emitted by #[derive(EntityType)] (FIELD_<NAME> and NAV_RELATED_<NAME>). The table/column fields of the SubquerySpec are resolved later at SQL generation time via resolve_subqueries.

pub fn where_in_subquery_internal( self, outer_column: &'static str, source_table: &'static str, projection_column: &'static str, predicate: Option<BoolExpr>, negated: bool, ) -> Self

v1.1: Adds an IN (SELECT ...) (or NOT IN (SELECT ...)) subquery condition.

#[doc(hidden)] — called by linq! expansion of b.field.in_subquery(|p: Post| p.blog_id).

Unlike where_exists_internal, the InSubquerySpec is fully specified at construction time (no navigation resolution needed). The source_table and projection_column are &'static str constants emitted by #[derive(EntityType)] (TABLE and COLUMN_<NAME>).

pub fn skip(self, count: usize) -> Self

Skips the specified number of rows.

pub fn take(self, count: usize) -> Self

Takes the specified number of rows.

impl<T: IEntityType> QueryBuilder<T>

pub async fn find(self, id: impl Into<DbValue>) -> EFResult<Option<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Finds an entity by its single primary key. Uses the entity’s PK metadata — no longer hardcodes "id".

pub async fn find_by_key(self, keys: &[(&str, DbValue)]) -> EFResult<Option<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Finds an entity by composite primary key. Keys are column-name constants paired with values, e.g. &[(BlogTag::COLUMN_BLOG_ID, DbValue::I32(1))].

pub async fn exists_by_id(self, id: impl Into<DbValue>) -> EFResult<bool>

Checks if an entity with the given single primary key exists.

Uses SELECT 1 ... LIMIT 1 — cheaper than find(id).await?.is_some() which materializes the full row. Reads the PK column from entity metadata, mirroring find.

pub async fn exists_by_key(self, keys: &[(&str, DbValue)]) -> EFResult<bool>

Checks if an entity with the given composite key exists.

Uses SELECT 1 ... LIMIT 1 — cheaper than find_by_key(keys).is_some().

pub fn to_sql(&self) -> String

Builds the SQL string for this query.

pub fn compile_sql(&self) -> (String, Vec<DbValue>)

pub async fn to_list(self) -> EFResult<Vec<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns all matching entities.

pub async fn to_list_with_includes(self) -> EFResult<Vec<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and eagerly loads included navigations.

pub async fn first(self) -> EFResult<T>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the first matching entity.

pub async fn first_or_default(self) -> EFResult<Option<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the first matching entity or None.

pub async fn count(self) -> EFResult<i64>

Executes a COUNT query.

pub async fn any(self) -> EFResult<bool>

Checks if any entities match the query.

pub async fn last(self) -> EFResult<T>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the last matching entity (reverses ordering, then takes 1). Errors if no rows match.

pub async fn last_or_default(self) -> EFResult<Option<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the last matching entity or None.

When the caller has set explicit order_by clauses, their directions are reversed and take(1) returns the last row under that ordering. When no ordering is set, a default ORDER BY <pk> DESC is injected so that “last” has deterministic semantics (matches the original design in the v0.4 plan §4 阶段 4). Errors if the entity has no primary key and no explicit ordering was provided.

pub async fn single(self) -> EFResult<T>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the only matching entity. Errors if there are 0 or 2+ results.

pub async fn single_or_default(self) -> EFResult<Option<T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Executes the query and returns the only matching entity, or None if empty. Errors if there are 2+ results.

pub async fn long_count(self) -> EFResult<i64>

Executes a COUNT query and returns the result as i64. Alias for count() — in .NET LINQ, LongCount returns long while Count returns int; in Rust both are i64.

pub async fn all<F>(self, predicate: F) -> EFResult<bool>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit, F: Fn(&T) -> bool,

Determines whether all elements in the sequence satisfy a predicate. The predicate is applied in Rust after loading the entities.

pub async fn contains(self, id: impl Into<DbValue>) -> EFResult<bool>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit,

Determines whether the sequence contains an entity with the given primary key value.

pub async fn to_dictionary<K, F>( self, key_selector: F, ) -> EFResult<HashMap<K, T>>

where T: IFromRow + INavigationSetter + IGetKeyValues + IEntitySnapshot + ILazyInit, K: Hash + Eq, F: Fn(&T) -> K,

Projects each entity into a key-value pair and collects into a HashMap<K, T>. The key selector closure extracts the key from each entity.

pub fn execute_update(self) -> ExecuteUpdateBuilder<T>

Prepares a bulk update operation.

pub async fn execute_delete(self) -> EFResult<u64>

Executes a bulk delete operation.

Trait Implementations

impl<T: Clone + IEntityType> Clone for QueryBuilder<T>

fn clone(&self) -> QueryBuilder<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: IEntityType> LinqSource for QueryBuilder<T>