Trait diesel::prelude::NullableExpressionMethods

source · 
pub trait NullableExpressionMethods: Expression + Sized {
    fn nullable(self) -> Nullable<Self> { ... }
    fn assume_not_null(self) -> AssumeNotNull<Self> { ... }
}
Expand description

Methods present on all expressions

Provided Methods§

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

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§