Trait NullableExpressionMethods

pub trait NullableExpressionMethods: Expression + Sized {
    // Provided methods
    fn nullable(self) -> Nullable<Self> { ... }
    fn assume_not_null(self) -> AssumeNotNull<Self> { ... }
}

Methods present on all expressions

Provided Methods

fn nullable(self) -> Nullable<Self>

Converts this potentially non-null expression into one which is treated as nullable. This method has no impact on the generated SQL, and is only used to allow certain comparisons that would otherwise fail to compile.

Example

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

fn main() {
    use self::users::dsl::*;
    use self::posts::dsl::{posts, author_name};
    let connection = &mut establish_connection();

    let data = users.inner_join(posts)
        .filter(name.nullable().eq(author_name))
        .select(name)
        .load::<String>(connection);
    println!("{:?}", data);
}

fn assume_not_null(self) -> AssumeNotNull<Self>

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);
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T: Expression> NullableExpressionMethods for T