Struct QueryBuilder 

pub struct QueryBuilder<'a, T, 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>) -> Self

Creates a new QueryBuilder using the provided Executor.

pub fn filter(self, condition: impl Into<String>) -> Self

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>) -> Self

Adds a raw SQL filter condition to the query.

pub fn filter_eq( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

Adds an equality filter (column = value).

pub fn filter_ne( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

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

pub fn filter_lt( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

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

pub fn filter_lte( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

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

pub fn filter_gt( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

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

pub fn filter_gte( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

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

pub fn filter_like( self, column: impl Into<ColumnRef>, value: impl Into<BindValue>, ) -> Self

Adds a LIKE filter (column LIKE value).

pub fn filter_is_null(self, column: impl Into<ColumnRef>) -> Self

Filters rows where the column IS NULL.

pub fn filter_is_not_null(self, column: impl Into<ColumnRef>) -> Self

Filters rows where the column IS NOT NULL.

pub fn filter_in<I, V>(self, column: impl Into<ColumnRef>, values: I) -> Self

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

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

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

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

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

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

pub fn include(self, relation: impl Into<String>) -> Self

Eager loads a related model.

pub fn with_deleted(self) -> Self

Includes soft-deleted records in the results.

pub fn allow_unsafe(self) -> Self

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

pub fn fast(self) -> Self

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

pub fn unsafe_fast(self) -> Self

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

pub fn ultra_fast(self) -> Self

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

pub fn prepared(self) -> Self

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

pub fn unprepared(self) -> Self

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, for<'q> <DB as Database>::Arguments<'q>: IntoArguments<'q, DB>, for<'c> &'c mut <DB as Database>::Connection: Executor<'c, Database = DB>, for<'c> &'c str: ColumnIndex<DB::Row>, DB::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>, NaiveDateTime: for<'q> Encode<'q, DB> + Type<DB>, NaiveDate: for<'q> Encode<'q, DB> + Type<DB>, Json<Value>: 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<BoxStream<'a, Result<T, Error>>, 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>, NaiveDateTime: for<'q> Encode<'q, DB> + Type<DB>, NaiveDate: for<'q> Encode<'q, DB> + Type<DB>, Json<Value>: 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>, Uuid: for<'q> Encode<'q, DB> + Type<DB>, DateTime<Utc>: for<'q> Encode<'q, DB> + Type<DB>, NaiveDateTime: for<'q> Encode<'q, DB> + Type<DB>, NaiveDate: for<'q> Encode<'q, DB> + Type<DB>, Json<Value>: 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: Database> Debug for QueryBuilder<'a, T, DB>

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

Formats the value using the given formatter.