Struct QueryBuilder 

pub struct QueryBuilder<'a, T, DB>
where
    DB: Database,
{ /* private fields */ }

A type-safe SQL query builder.

QueryBuilder provides a fluent interface for building SELECT, UPDATE, and DELETE queries with support for filtering, pagination, eager loading, and soft deletes.

Implementations

impl<'a, T, DB> QueryBuilder<'a, T, DB>

where DB: SqlDialect + HasStatementCache, T: Model<DB>,

pub fn new(executor: Executor<'a, DB>) -> QueryBuilder<'a, T, DB>

Creates a new QueryBuilder using the provided Executor.

pub fn filter(self, condition: impl Into<String>) -> QueryBuilder<'a, T, DB>

Adds a raw SQL filter condition to the query.

Safety

This method is potentially unsafe and requires calling [allow_unsafe] for the query to execute.

pub fn filter_raw(self, condition: impl Into<String>) -> QueryBuilder<'a, T, DB>

Adds a raw SQL filter condition to the query.

pub fn filter_eq( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds an equality filter (column = value).

pub fn filter_ne( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a not-equal filter (column != value).

pub fn filter_lt( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a less-than filter (column < value).

pub fn filter_lte( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a less-than-or-equal filter (column <= value).

pub fn filter_gt( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a greater-than filter (column > value).

pub fn filter_gte( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a greater-than-or-equal filter (column >= value).

pub fn filter_like( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> QueryBuilder<'a, T, DB>

Adds a LIKE filter (column LIKE value).

pub fn filter_is_null( self, column: impl Into<ColumnRef>, ) -> QueryBuilder<'a, T, DB>

Filters rows where the column IS NULL.

pub fn filter_is_not_null( self, column: impl Into<ColumnRef>, ) -> QueryBuilder<'a, T, DB>

Filters rows where the column IS NOT NULL.

pub fn filter_in<I, V>( self, column: impl Into<ColumnRef>, values: I, ) -> QueryBuilder<'a, T, DB>

where I: IntoIterator<Item = V>, V: Into<BindValue>,

Adds an IN filter (column IN (values...)).

pub fn limit(self, limit: i32) -> QueryBuilder<'a, T, DB>

Limits the number of rows returned by the query. Sets the maximum number of rows to return.

pub fn offset(self, offset: i32) -> QueryBuilder<'a, T, DB>

Skips the specified number of rows. Sets the number of rows to skip.

pub fn include(self, relation: impl Into<String>) -> QueryBuilder<'a, T, DB>

Eager loads a related model.

pub fn with_deleted(self) -> QueryBuilder<'a, T, DB>

Includes soft-deleted records in the results.

pub fn allow_unsafe(self) -> QueryBuilder<'a, T, DB>

Explicitly allows potentially unsafe raw filters. Enables execution of queries with raw SQL filters.

pub fn fast(self) -> QueryBuilder<'a, T, DB>

Enables a fast path that skips logging and metrics for hot queries.

pub fn unsafe_fast(self) -> QueryBuilder<'a, T, DB>

Enables an unsafe fast path that skips logging, metrics, and safety guards.

pub fn ultra_fast(self) -> QueryBuilder<'a, T, DB>

Enables the ultra-fast path: skips logging, metrics, safety guards, and eager loading. Note: Any configured includes will be ignored.

pub fn prepared(self) -> QueryBuilder<'a, T, DB>

Enable prepared statement caching for this query (default: enabled).

pub fn unprepared(self) -> QueryBuilder<'a, T, DB>

Disable prepared statement caching for this query.

pub fn to_sql(&self) -> String

Returns the SELECT SQL that would be executed for this query.

pub fn to_update_sql(&self, values: &Value) -> Result<String, Error>

Returns the UPDATE SQL that would be executed for this query.

pub fn to_delete_sql(&self) -> String

Returns the DELETE (or soft delete) SQL that would be executed for this query.

impl<'a, T, DB> QueryBuilder<'a, T, DB>

where DB: SqlDialect, T: Model<DB> + Send, <DB as Database>::Arguments<'q>: for<'q> IntoArguments<'q, DB>, &'c mut <DB as Database>::Connection: for<'c> Executor<'c, Database = DB>, &'c str: for<'c> ColumnIndex<<DB as Database>::Row>, <DB as Database>::Connection: Send, String: for<'q> Encode<'q, DB> + Type<DB>, i64: for<'q> Encode<'q, DB> + Type<DB>, f64: for<'q> Encode<'q, DB> + Type<DB>, bool: for<'q> Encode<'q, DB> + Type<DB>, Option<String>: for<'q> Encode<'q, DB> + Type<DB>, Uuid: for<'q> Encode<'q, DB> + Type<DB>, DateTime<Utc>: for<'q> Encode<'q, DB> + Type<DB>,

pub async fn all(self) -> Result<Vec<T>, Error>

Executes the query and returns a vector of results.

This method will fetch all rows matching the criteria and then perform eager loading for any included relations.

pub fn stream( self, ) -> Result<Pin<Box<dyn Stream<Item = Result<T, Error>> + Send + 'a>>, Error>

where T: 'a,

Executes the query and returns a stream of results.

This is useful for processing large result sets without loading them all into memory.

pub async fn update(self, values: Value) -> Result<u64, Error>

where String: for<'q> Encode<'q, DB> + Type<DB>, i64: for<'q> Encode<'q, DB> + Type<DB>, f64: for<'q> Encode<'q, DB> + Type<DB>, bool: for<'q> Encode<'q, DB> + Type<DB>, Option<String>: for<'q> Encode<'q, DB> + Type<DB>, Uuid: for<'q> Encode<'q, DB> + Type<DB>, DateTime<Utc>: for<'q> Encode<'q, DB> + Type<DB>,

Executes a bulk update based on the current filters.

Errors

Returns an error if no filters are provided (unless allow_unsafe is used), or if the values cannot be mapped to the database.

pub async fn update_all(self, values: Value) -> Result<u64, Error>

where String: for<'q> Encode<'q, DB> + Type<DB>, i64: for<'q> Encode<'q, DB> + Type<DB>, f64: for<'q> Encode<'q, DB> + Type<DB>, bool: for<'q> Encode<'q, DB> + Type<DB>, Option<String>: for<'q> Encode<'q, DB> + Type<DB>,

Executes a bulk update based on the current filters. Alias for [update].

pub async fn delete(self) -> Result<u64, Error>

Executes a bulk delete based on the current filters.

pub async fn delete_all(self) -> Result<u64, Error>

Executes a bulk delete based on the current filters. Alias for [delete].

Trait Implementations

impl<'a, T, DB> Debug for QueryBuilder<'a, T, DB>

where DB: Database,

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

Formats the value using the given formatter.