Struct SQLExpr 

pub struct SQLExpr<'a, V: SQLParam, T: DataType, N: Nullability = NonNull, A: AggregateKind = Scalar, S = ()> { /* private fields */ }

A SQL fragment together with its type information.

Every function in crate::expr returns an SQLExpr. The type parameters record what the fragment produces:

• 'a: lifetime of borrowed values inside it;
• V: the dialect’s value type (SQLiteValue, PostgresValue, …);
• T: the SQL data type marker;
• N: NonNull or Null;
• A: Scalar or Agg;
• S: the tables it reads (see crate::scope).

SQLExpr dereferences to SQL, so methods such as SQL::sql work on it directly. The Rust operators + - * / % and unary - do arithmetic on numeric expressions, and & | ! combine boolean ones.

Examples

let total = users.age.clone() * 2 + 1;
assert_eq!(total.sql(), r#""users"."age" * ? + ?"#);

Implementations

impl<'a, V: SQLParam, T: DataType, N: Nullability, A: AggregateKind, S> SQLExpr<'a, V, T, N, A, S>

pub const fn new(sql: SQL<'a, V>) -> Self

Wraps a SQL fragment, declaring its type.

The type parameters are trusted, not checked against the SQL.

pub fn into_sql(self) -> SQL<'a, V>

Returns the SQL fragment, dropping the type information.

pub fn nullable(self) -> SQLExpr<'a, V, T, Null, A, S>

Marks this expression as nullable, keeping its SQL type and aggregate kind.

pub fn unscoped(self) -> SQLExpr<'a, V, T, N, A>

Forgets which tables this expression reads.

The result passes every scope check. Use it only for SQL that is valid in a scope the type system cannot see, such as a correlated subquery built separately from its outer query.

impl<'a, V, T, N, S> SQLExpr<'a, V, T, N, Agg, S>

where V: SQLParam + 'a, T: DataType, N: Nullability,

pub fn over<W>( self, spec: WindowSpec<'a, V, W>, ) -> SQLExpr<'a, V, T, N, Scalar, (S, W)>

Turns this aggregate into a window function (agg OVER (...)).

The result keeps the SQL type and nullability but is scalar, so it can be selected next to plain columns.

Examples

let per_name = sum(users.score).over(window().partition_by([users.name]));
assert_eq!(
    per_name.sql(),
    r#"SUM ("users"."score") OVER (PARTITION BY "users"."name")"#
);

pub fn filter<C>( self, condition: C, ) -> SQLExpr<'a, V, T, N, Agg, (S, ScopeOnly<C::Sources>)>

where C: Expr<'a, V>, C::SQLType: BooleanLike, V::DialectMarker: DialectSupports<AggregateFilter>,

Limits the rows an aggregate sees (agg FILTER (WHERE condition)), on SQLite and PostgreSQL.

The condition must be boolean. The result is still an aggregate.

Examples

let adults = count(users.id).filter(gt(users.age, 18));
assert_eq!(
    adults.sql(),
    r#"COUNT ("users"."id") FILTER (WHERE "users"."age" > ?)"#
);

Methods from Deref<Target = SQL<'a, V>>

pub fn is_subquery(&self) -> bool

Returns true if the fragment starts with a SELECT or WITH token.

pub fn sql(&self) -> String

Renders the SQL text.

Placeholders follow the dialect of V: $1, $2, ... for PostgreSQL, :name (named) or ? for SQLite, and ? for MySQL. Use SQL::build to get the parameters in the same pass.

pub fn has_returning(&self) -> bool

Whether this statement has a RETURNING clause (outside any parentheses), so it returns rows although it changes data.

pub fn inline_sql(&self) -> Option<String>

Renders the SQL text with every bound value written as a literal instead of a placeholder.

For statements that cannot take parameters, such as the body of a CREATE VIEW. Returns None when a placeholder has no bound value, or a value has no literal form in this dialect (see SQLParam::write_literal).

pub fn build(&self) -> (String, SmallVec<[&V; 8]>)

Renders the SQL text and collects the bound values in one pass.

Drivers use this to execute a statement. Placeholders without a bound value are rendered but not collected. For SQLite, a named placeholder that appears more than once is collected once, since SQLite gives each distinct :name a single slot.

Examples

use drizzle_core::SQL;

let sql = SQL::raw("SELECT").append(SQL::param(Value(1)));
let (text, params) = sql.build();
assert_eq!(text, "SELECT ?");
assert_eq!(params.as_slice(), [&Value(1)]);

pub fn build_with(&self, style: ParamStyle) -> (String, SmallVec<[&V; 8]>)

Like build, but with a caller-chosen placeholder style.

For drivers that speak the dialect but bind parameters differently, such as the AWS Data API on PostgreSQL, which needs :1, :2, ... instead of $1, $2, ....

pub fn write_to(&self, buf: &mut impl Write)

Writes the SQL text to buf, like SQL::sql without allocating a new string.

pub fn write_to_with(&self, buf: &mut impl Write, style: ParamStyle)

Like write_to, but with a caller-chosen placeholder style.

pub fn write_chunk_to( &self, buf: &mut impl Write, chunk: &SQLChunk<'a, V>, index: usize, )

Writes the chunk at index to buf, expanding an empty SELECT projection that ends at this chunk.

Does not write the space that may follow the chunk.

pub fn params(&self) -> impl Iterator<Item = &V> + use<'_, V>

Returns the bound values, in order. Placeholders without a value are skipped.

Trait Implementations

impl<'a, V, T, N, A, S, Rhs> Add<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: ArithmeticOutput<Rhs::SQLType, AddOp>, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: Numeric, Rhs::Nullable: Nullability, <T as ArithmeticOutput<Rhs::SQLType, AddOp>>::Nullability: ResolveArithmeticNullability<N, Rhs::Nullable>,

type Output = SQLExpr<'a, V, <T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, AddOp>>::Output, <<T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, AddOp>>::Nullability as ResolveArithmeticNullability<N, <Rhs as Expr<'a, V>>::Nullable>>::Output, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the + operator.

fn add(self, rhs: Rhs) -> Self::Output

Performs the + operation.

impl<'a, V, T, N, A, S> AsRef<SQL<'a, V>> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam, T: DataType, N: Nullability, A: AggregateKind,

Borrows the inner SQL.

fn as_ref(&self) -> &SQL<'a, V>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a, V, T, N, A, S, Rhs> BitAnd<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: BooleanLike, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: BooleanLike, Rhs::Nullable: Nullability,

left & right renders (left AND right); see and.

type Output = SQLExpr<'a, V, <<V as SQLParam>::DialectMarker as DialectTypes>::Bool, <N as Nullability>::Or<<Rhs as Expr<'a, V>>::Nullable>, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the & operator.

fn bitand(self, rhs: Rhs) -> Self::Output

Performs the & operation.

impl<'a, V, T, N, A, S, Rhs> BitOr<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: BooleanLike, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: BooleanLike, Rhs::Nullable: Nullability,

left | right renders (left OR right); see or.

type Output = SQLExpr<'a, V, <<V as SQLParam>::DialectMarker as DialectTypes>::Bool, <N as Nullability>::Or<<Rhs as Expr<'a, V>>::Nullable>, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the | operator.

fn bitor(self, rhs: Rhs) -> Self::Output

Performs the | operation.

impl<'a, V: Clone + SQLParam, T: Clone + DataType, N: Clone + Nullability, A: Clone + AggregateKind, S: Clone> Clone for SQLExpr<'a, V, T, N, A, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, V: Debug + SQLParam, T: Debug + DataType, N: Debug + Nullability, A: Debug + AggregateKind, S: Debug> Debug for SQLExpr<'a, V, T, N, A, S>

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

Formats the value using the given formatter.

impl<'a, V, T, N, A, S> Deref for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam, T: DataType, N: Nullability, A: AggregateKind,

Gives direct access to the inner SQL and its methods, such as SQL::sql.

type Target = SQL<'a, V>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<V, T, N, A, S> Display for SQLExpr<'_, V, T, N, A, S>

where V: SQLParam + Display, T: DataType, N: Nullability, A: AggregateKind,

Formats the expression like its inner SQL.

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

Formats the value using the given formatter.

impl<'a, V, T, N, A, S, Rhs> Div<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: ArithmeticOutput<Rhs::SQLType, DivOp>, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: Numeric, Rhs::Nullable: Nullability, <T as ArithmeticOutput<Rhs::SQLType, DivOp>>::Nullability: ResolveArithmeticNullability<N, Rhs::Nullable>,

type Output = SQLExpr<'a, V, <T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, DivOp>>::Output, <<T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, DivOp>>::Nullability as ResolveArithmeticNullability<N, <Rhs as Expr<'a, V>>::Nullable>>::Output, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the / operator.

fn div(self, rhs: Rhs) -> Self::Output

Performs the / operation.

impl<'a, V: SQLParam, T: DataType, N: Nullability, A: AggregateKind, S> Expr<'a, V> for SQLExpr<'a, V, T, N, A, S>

type SQLType = T

The SQL data type this expression evaluates to.

type Nullable = N

Whether this expression can be NULL.

type Aggregate = A

Whether this is an aggregate (COUNT, SUM) or scalar expression.

fn to_expr_sql(&self) -> SQL<'a, V>

Renders this value as a scalar expression, borrowing it.

fn into_expr_sql(self) -> SQL<'a, V>

where Self: Sized,

Renders this value as a scalar expression, consuming it.

fn to_condition_sql(&self) -> Option<SQL<'a, V>>

Renders this value as one element of a ConditionList.

fn into_condition_sql(self) -> Option<SQL<'a, V>>

where Self: Sized,

Consuming counterpart of Expr::to_condition_sql.

impl<V: SQLParam, T: DataType, N: Nullability, A: AggregateKind, S> ExprSources for SQLExpr<'_, V, T, N, A, S>

type Sources = S

Type-level tree with one Src leaf per column read.

impl<V: SQLParam, T, N, A, S> ExprValueType for SQLExpr<'_, V, T, N, A, S>

where T: DataType + SQLTypeToRust<V::DialectMarker>, N: Nullability + WrapNullable<<T as SQLTypeToRust<V::DialectMarker>>::RustType>, A: AggregateKind,

type ValueType = <N as WrapNullable<<T as SQLTypeToRust<<V as SQLParam>::DialectMarker>>::RustType>>::Output

The decoded Rust type.

impl<'a, V: SQLParam, T: DataType, N: Nullability, A: AggregateKind, S> From<SQLExpr<'a, V, T, N, A, S>> for SQL<'a, V>

fn from(expr: SQLExpr<'a, V, T, N, A, S>) -> Self

Converts to this type from the input type.

impl<V: SQLParam, T, N, A, S> GroupByIdentity for SQLExpr<'_, V, T, N, A, S>

where T: DataType, N: Nullability, A: AggregateKind,

type Identity = SQLExpr<'_, V, T, N, A, S>

The type looked up in the grouped column list.

impl<V, T, N, A, S> HasAggStatus for SQLExpr<'_, V, T, N, A, S>

where V: SQLParam, T: DataType, N: Nullability, A: AggregateKind,

type Status = <A as AggregateKind>::Status

AllScalar, AllAgg or MixedAgg.

impl<V: SQLParam, T, N, A, S> IntoSelectTarget for SQLExpr<'_, V, T, N, A, S>

where T: DataType, N: Nullability, A: AggregateKind,

select(typed_expr) → SelectCols<(Expr,)> — single typed expression.

type Marker = SelectCols<(SQLExpr<'_, V, T, N, A, S>,)>

The select marker.

impl<'a, V, T, N, A, S, Rhs> Mul<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: ArithmeticOutput<Rhs::SQLType, MulOp>, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: Numeric, Rhs::Nullable: Nullability, <T as ArithmeticOutput<Rhs::SQLType, MulOp>>::Nullability: ResolveArithmeticNullability<N, Rhs::Nullable>,

type Output = SQLExpr<'a, V, <T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, MulOp>>::Output, <<T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, MulOp>>::Nullability as ResolveArithmeticNullability<N, <Rhs as Expr<'a, V>>::Nullable>>::Output, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the * operator.

fn mul(self, rhs: Rhs) -> Self::Output

Performs the * operation.

impl<'a, V, T, N, A, S> Neg for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: Numeric + NegOutput, N: Nullability, A: AggregateKind,

type Output = SQLExpr<'a, V, <T as NegOutput>::Output, N, A, S>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<'a, V, T, N, A, S> Not for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: BooleanLike, N: Nullability, A: AggregateKind,

!expr renders NOT (expr); see not.

type Output = SQLExpr<'a, V, <<V as SQLParam>::DialectMarker as DialectTypes>::Bool, N, A, S>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<'a, V, T, N, A, S, Rhs> Rem<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: ArithmeticOutput<Rhs::SQLType, RemOp>, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: Numeric, Rhs::Nullable: Nullability, <T as ArithmeticOutput<Rhs::SQLType, RemOp>>::Nullability: ResolveArithmeticNullability<N, Rhs::Nullable>,

type Output = SQLExpr<'a, V, <T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, RemOp>>::Output, <<T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, RemOp>>::Nullability as ResolveArithmeticNullability<N, <Rhs as Expr<'a, V>>::Nullable>>::Output, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the % operator.

fn rem(self, rhs: Rhs) -> Self::Output

Performs the % operation.

impl<'a, V, T, N, A, S, Rhs> Sub<Rhs> for SQLExpr<'a, V, T, N, A, S>

where V: SQLParam + 'a, T: ArithmeticOutput<Rhs::SQLType, SubOp>, N: Nullability, A: AggregateKind, Rhs: Expr<'a, V>, Rhs::SQLType: Numeric, Rhs::Nullable: Nullability, <T as ArithmeticOutput<Rhs::SQLType, SubOp>>::Nullability: ResolveArithmeticNullability<N, Rhs::Nullable>,

type Output = SQLExpr<'a, V, <T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, SubOp>>::Output, <<T as ArithmeticOutput<<Rhs as Expr<'a, V>>::SQLType, SubOp>>::Nullability as ResolveArithmeticNullability<N, <Rhs as Expr<'a, V>>::Nullable>>::Output, <A as AggregateKind>::Or<<Rhs as Expr<'a, V>>::Aggregate>, (S, <Rhs as ExprSources>::Sources)>

The resulting type after applying the - operator.

fn sub(self, rhs: Rhs) -> Self::Output

Performs the - operation.

impl<'a, V: SQLParam, T: DataType, N: Nullability, A: AggregateKind, S> ToSQL<'a, V> for SQLExpr<'a, V, T, N, A, S>

fn to_sql(&self) -> SQL<'a, V>

Renders self as a SQL fragment.

fn into_sql(self) -> SQL<'a, V>

Renders self as a SQL fragment, consuming it.