Trait diesel::expression_methods::ExpressionMethods[][src]

pub trait ExpressionMethods: Expression + Sized {
Show 15 methods fn eq<T>(self, other: T) -> Eq<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn ne<T>(self, other: T) -> NotEq<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn eq_any<T>(self, values: T) -> EqAny<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsInExpression<Self::SqlType>
, { ... }
fn ne_all<T>(self, values: T) -> NeAny<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsInExpression<Self::SqlType>
, { ... }
fn is_null(self) -> IsNull<Self> { ... }
fn is_not_null(self) -> IsNotNull<Self> { ... }
fn gt<T>(self, other: T) -> Gt<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn ge<T>(self, other: T) -> GtEq<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn lt<T>(self, other: T) -> Lt<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn le<T>(self, other: T) -> LtEq<Self, T>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>
, { ... }
fn between<T, U>(self, lower: T, upper: U) -> Between<Self, T, U>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>,
        U: AsExpression<Self::SqlType>
, { ... }
fn not_between<T, U>(self, lower: T, upper: U) -> NotBetween<Self, T, U>
    where
        Self::SqlType: SqlType,
        T: AsExpression<Self::SqlType>,
        U: AsExpression<Self::SqlType>
, { ... }
fn desc(self) -> Desc<Self> { ... }
fn asc(self) -> Asc<Self> { ... }
fn assume_not_null(self) -> AssumeNotNull<Self> { ... }
}
Expand description

Methods present on all expressions, except tuples

Provided methods

Creates a SQL = expression.

Example

let data = users.select(id).filter(name.eq("Sean"));
assert_eq!(Ok(1), data.first(connection));

Creates a SQL != expression.

Example

let data = users.select(id).filter(name.ne("Sean"));
assert_eq!(Ok(2), data.first(connection));

Creates a SQL IN statement.

Queries using this method will not typically be placed in the prepared statement cache. However, in cases when a subquery is passed to the method, that query will use the cache (assuming the subquery itself is safe to cache). On PostgreSQL, you should use eq(any()) instead. This method may change in the future to automatically perform = ANY on PostgreSQL.

Example

let data = users::table.select(users::id).filter(users::name.eq_any(vec!["Sean", "Jim"]));
assert_eq!(Ok(vec![1, 3]), data.load(connection));

// Calling `eq_any` with an empty array is the same as doing `WHERE 1=0`
let data = users::table.select(users::id).filter(users::name.eq_any(Vec::<String>::new()));
assert_eq!(Ok(vec![]), data.load::<i32>(connection));

// Calling `eq_any` with a subquery is the same as using
// `WHERE {column} IN {subquery}`.

let subquery = users::table.filter(users::name.eq("Sean")).select(users::id).into_boxed();
let data = posts::table.select(posts::id).filter(posts::user_id.eq_any(subquery));
assert_eq!(Ok(vec![1, 2]), data.load::<i32>(connection));

Creates a SQL NOT IN statement.

Queries using this method will not be placed in the prepared statement cache. On PostgreSQL, you should use ne(all()) instead. This method may change in the future to automatically perform != ALL on PostgreSQL.

Example

let data = users.select(id).filter(name.ne_all(vec!["Sean", "Jim"]));
assert_eq!(Ok(vec![2]), data.load(connection));

let data = users.select(id).filter(name.ne_all(vec!["Tess"]));
assert_eq!(Ok(vec![1, 3]), data.load(connection));

// Calling `ne_any` with an empty array is the same as doing `WHERE 1=1`
let data = users.select(id).filter(name.ne_all(Vec::<String>::new()));
assert_eq!(Ok(vec![1, 2, 3]), data.load(connection));

Creates a SQL IS NULL expression.

Example

let data = animals
    .select(species)
    .filter(name.is_null())
    .first::<String>(connection)?;
assert_eq!("spider", data);

Creates a SQL IS NOT NULL expression.

Example

let data = animals
    .select(species)
    .filter(name.is_not_null())
    .first::<String>(connection)?;
assert_eq!("dog", data);

Creates a SQL > expression.

Example

let data = users
    .select(name)
    .filter(id.gt(1))
    .first::<String>(connection)?;
assert_eq!("Tess", data);

Creates a SQL >= expression.

Example

let data = users
    .select(name)
    .filter(id.ge(2))
    .first::<String>(connection)?;
assert_eq!("Tess", data);

Creates a SQL < expression.

Example

let data = users
    .select(name)
    .filter(id.lt(2))
    .first::<String>(connection)?;
assert_eq!("Sean", data);

Creates a SQL <= expression.

Example

let data = users
    .select(name)
    .filter(id.le(2))
    .first::<String>(connection)?;
assert_eq!("Sean", data);

Creates a SQL BETWEEN expression using the given lower and upper bounds.

Example

let data = animals
    .select(species)
    .filter(legs.between(2, 6))
    .first(connection);
assert_eq!(Ok("dog".to_string()), data);

Creates a SQL NOT BETWEEN expression using the given lower and upper bounds.

Example

let data = animals
    .select(species)
    .filter(legs.not_between(2, 6))
    .first::<String>(connection)?;
assert_eq!("spider", data);

Creates a SQL DESC expression, representing this expression in descending order.

Example

let names = users
    .select(name)
    .order(name.desc())
    .load::<String>(connection)?;
assert_eq!(vec!["Tess", "Sean"], names);

Creates a SQL ASC expression, representing this expression in ascending order.

This is the same as leaving the direction unspecified. It is useful if you need to provide an unknown ordering, and need to box the return value of a function.

Example

let ordering: Box<dyn BoxableExpression<users, DB, SqlType = NotSelectable>> =
    if order == "name" {
        Box::new(name.desc())
    } else {
        Box::new(id.asc())
    };

Converts this potentially nullable expression into one which will be assumed to be not-null. This method has no impact on the generated SQL, however it will enable you to attempt deserialization of the returned value in a non-Option.

This is meant to cover for cases where you know that given the WHERE clause the field returned by the database will never be NULL.

This will cause runtime errors on load() if the “assume” turns out to be incorrect.

Examples

Normal usage

table! {
    animals {
        id -> Integer,
        species -> VarChar,
        legs -> Integer,
        name -> Nullable<VarChar>,
    }
}

fn main() {
    use self::animals::dsl::*;
    let connection = &mut establish_connection();

    let result = animals
        .filter(name.is_not_null())
        .select(name.assume_not_null())
        .load::<String>(connection);
    assert!(result.is_ok());
}

Incorrect usage

table! {
    animals {
        id -> Integer,
        species -> VarChar,
        legs -> Integer,
        name -> Nullable<VarChar>,
    }
}

fn main() {
    use diesel::result::{Error, UnexpectedNullError};
    use self::animals::dsl::*;
    let connection = &mut establish_connection();

    let result = animals
        .select(name.assume_not_null())
        .load::<String>(connection);
    assert!(matches!(
        result,
        Err(Error::DeserializationError(err)) if err.is::<UnexpectedNullError>()
    ));
}

Advanced usage - use only if you’re sure you know what you’re doing!

This will cause the Option to be None where the left_join succeeded but the author_name turned out to be NULL, due to how Option deserialization works. (see Queryable documentation)

table! {
    posts {
        id -> Integer,
        user_id -> Integer,
        author_name -> Nullable<Text>,
    }
}

fn main() {
    use self::posts;
    use self::users;
    let connection = &mut establish_connection();


    let result = posts::table.left_join(users::table)
        .select((posts::id, (users::id, posts::author_name.assume_not_null()).nullable()))
        .order_by(posts::id)
        .load::<(i32, Option<(i32, String)>)>(connection);
    let expected = Ok(vec![
        (1, Some((1, "Sean".to_owned()))),
        (2, Some((1, "Sean".to_owned()))),
        (3, None),
    ]);
    assert_eq!(expected, result);
}

Implementors