Struct Select

Source

pub struct Select<M: Model> { /* private fields */ }

Expand description

A SELECT query builder.

Provides a fluent API for building SELECT queries with type-safe column references and conditions.

Implementations§

Source §

impl<M: Model> Select<M>

Source

pub fn new() -> Self

Create a new SELECT query for the model’s table.

Source

pub fn columns(self, cols: &[&str]) -> Self

Select specific columns.

Source

pub fn filter(self, expr: Expr) -> Self

Add a WHERE condition.

Source

pub fn or_filter(self, expr: Expr) -> Self

Add an OR WHERE condition.

Source

pub fn order_by(self, order: OrderBy) -> Self

Add ORDER BY clause.

Source

pub fn join(self, join: Join) -> Self

Add a JOIN clause.

Source

pub fn limit(self, n: u64) -> Self

Set LIMIT.

Source

pub fn offset(self, n: u64) -> Self

Set OFFSET.

Source

pub fn group_by(self, cols: &[&str]) -> Self

Add GROUP BY columns.

Source

pub fn having(self, expr: Expr) -> Self

Add HAVING condition.

Source

pub fn distinct(self) -> Self

Make this a DISTINCT query.

Source

pub fn for_update(self) -> Self

Add FOR UPDATE lock.

Source

pub fn eager(self, loader: EagerLoader<M>) -> Self

Configure eager loading for relationships.

§Example

let heroes = select!(Hero)
    .eager(EagerLoader::new().include("team"))
    .all_eager(cx, &conn)
    .await?;

Source

pub fn polymorphic_joined<Child: Model>( self, ) -> PolymorphicJoinedSelect<M, Child>

Convert this Select<M> into a joined-table inheritance polymorphic query.

For joined-table inheritance, polymorphic queries need an explicit LEFT JOIN and explicit table__col projections for both base and child tables so that row hydration can be deterministic and collision-free.

This returns a query that hydrates either M (base) or Child depending on whether the child-side columns are all NULL.

Notes:

Requires M to be a joined-inheritance base model (inheritance="joined").
Requires Child to be a joined-inheritance child with inherits="M".
This always projects full base + child columns (ignores custom columns(...)), since hydration depends on a complete prefixed projection.

Source

pub fn polymorphic_joined2<C1: Model, C2: Model>( self, ) -> PolymorphicJoinedSelect2<M, C1, C2>

Convert this Select<M> into a joined-table inheritance polymorphic query with two child types.

This LEFT JOINs both child tables and returns PolymorphicJoined2<M, C1, C2>.

Source

pub fn polymorphic_joined3<C1: Model, C2: Model, C3: Model>( self, ) -> PolymorphicJoinedSelect3<M, C1, C2, C3>

Convert this Select<M> into a joined-table inheritance polymorphic query with three child types.

This LEFT JOINs three child tables and returns PolymorphicJoined3<M, C1, C2, C3>.

Source

pub async fn all_eager<C: Connection>( self, cx: &Cx, conn: &C, ) -> Outcome<Vec<M>, Error>

Execute the query with eager loading and return hydrated models.

This method fetches the parent models along with their eagerly loaded relationships in a single query using JOINs. Results are deduplicated by primary key to handle one-to-many JOINs.

§Note

Currently, this method parses parent models from aliased columns and deduplicates by primary key. Full hydration of Related<T> and RelatedMany<T> fields requires macro support and is tracked separately. The JOIN query is still valuable as it:

Fetches all data in a single query (avoiding N+1)
Returns related data that can be accessed via row.subset_by_prefix()

§Example

let heroes = select!(Hero)
    .eager(EagerLoader::new().include("team"))
    .all_eager(cx, &conn)
    .await?;

Source

pub fn build(&self) -> (String, Vec<Value>)

Build the SQL query and parameters.

Source

pub fn build_with_dialect(&self, dialect: Dialect) -> (String, Vec<Value>)

Build the SQL query and parameters with a specific dialect.

Source

pub fn into_exists(self) -> Expr

Convert this SELECT query to an EXISTS expression.

Creates an Expr::Exists that can be used in WHERE clauses of other queries. For performance, the SELECT is automatically optimized to SELECT 1 when generating the EXISTS subquery.

§Example

// Find customers who have at least one order
let has_orders = Select::<Order>::new()
    .filter(Expr::raw("orders.customer_id = customers.id"))
    .into_exists();

let customers = Select::<Customer>::new()
    .filter(has_orders)
    .all(cx, &conn)
    .await?;

// Generates: SELECT * FROM customers WHERE EXISTS (SELECT 1 FROM orders WHERE orders.customer_id = customers.id)

Source

pub fn into_exists_with_dialect(self, dialect: Dialect) -> Expr

Convert this SELECT query to an EXISTS expression using a specific dialect.

Use this when embedding the EXISTS in a query for a non-default dialect.

Source

pub fn into_not_exists(self) -> Expr

Convert this SELECT query to a NOT EXISTS expression.

Creates an Expr::Exists (negated) that can be used in WHERE clauses. For performance, the SELECT is automatically optimized to SELECT 1.

§Example

// Find customers with no orders
let has_no_orders = Select::<Order>::new()
    .filter(Expr::raw("orders.customer_id = customers.id"))
    .into_not_exists();

let customers = Select::<Customer>::new()
    .filter(has_no_orders)
    .all(cx, &conn)
    .await?;

// Generates: SELECT * FROM customers WHERE NOT EXISTS (SELECT 1 FROM orders WHERE orders.customer_id = customers.id)

Source

pub fn into_not_exists_with_dialect(self, dialect: Dialect) -> Expr

Convert this SELECT query to a NOT EXISTS expression using a specific dialect.

Source

pub fn into_lateral_join( self, alias: impl Into<String>, join_type: JoinType, on: Expr, ) -> Join

Convert this SELECT into a LATERAL JOIN.

Creates a Join with lateral: true that can be added to another query. The subquery can reference columns from the outer query.

Supported by PostgreSQL (9.3+) and MySQL (8.0.14+). Not supported by SQLite.

§Arguments

alias - Required alias for the lateral subquery
join_type - The join type (typically Left or Inner)
on - ON condition (use Expr::raw("TRUE") for implicit TRUE)

§Example

// Get top 3 recent orders per customer
let recent_orders = Select::<Order>::new()
    .filter(Expr::raw("orders.customer_id = customers.id"))
    .order_by(OrderBy::desc("date"))
    .limit(3)
    .into_lateral_join("recent_orders", JoinType::Left, Expr::raw("TRUE"));

let query = Select::<Customer>::new().join(recent_orders);

Source