Trait diesel::prelude::RunQueryDsl

source · [−]
pub trait RunQueryDsl<Conn>: Sized {
    fn execute(self, conn: &mut Conn) -> QueryResult<usize>
    where
        Conn: Connection,
        Self: ExecuteDsl<Conn>,
    { ... }
    fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>
    where
        Self: LoadQuery<'query, Conn, U>,
    { ... }
    fn load_iter<'conn, 'query: 'conn, U, B>(
        self,
        conn: &'conn mut Conn
    ) -> QueryResult<LoadIter<'conn, 'query, Self, Conn, U, B>>
    where
        U: 'conn,
        Self: LoadQuery<'query, Conn, U, B> + 'conn,
    { ... }
    fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
    where
        Self: LoadQuery<'query, Conn, U>,
    { ... }
    fn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>
    where
        Self: LoadQuery<'query, Conn, U>,
    { ... }
    fn first<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
    where
        Self: LimitDsl,
        Limit<Self>: LoadQuery<'query, Conn, U>,
    { ... }
}
Expand description

Methods used to execute queries.

Provided Methods

Executes the given command, returning the number of rows affected.

execute is usually used in conjunction with insert_into, update and delete where the number of affected rows is often enough information.

When asking the database to return data from a query, load should probably be used instead.

Example
let inserted_rows = insert_into(users)
    .values(name.eq("Ruby"))
    .execute(connection)?;
assert_eq!(1, inserted_rows);

let inserted_rows = insert_into(users)
    .values(&vec![name.eq("Jim"), name.eq("James")])
    .execute(connection)?;
assert_eq!(2, inserted_rows);

Executes the given query, returning a Vec with the returned rows.

When using the query builder, the return type can be a tuple of the values, or a struct which implements Queryable.

When this method is called on sql_query, the return type can only be a struct which implements QueryableByName

For insert, update, and delete operations where only a count of affected is needed, execute should be used instead.

Examples
Returning a single field
let data = users.select(name)
    .load::<String>(connection)?;
assert_eq!(vec!["Sean", "Tess"], data);
Returning a tuple
let data = users
    .load::<(i32, String)>(connection)?;
let expected_data = vec![
    (1, String::from("Sean")),
    (2, String::from("Tess")),
];
assert_eq!(expected_data, data);
Returning a struct
#[derive(Queryable, PartialEq, Debug)]
struct User {
    id: i32,
    name: String,
}

let data = users
    .load::<User>(connection)?;
let expected_data = vec![
    User { id: 1, name: String::from("Sean") },
    User { id: 2, name: String::from("Tess") },
];
assert_eq!(expected_data, data);

Executes the given query, returning an Iterator with the returned rows.

The iterator’s item is QueryResult<U>.

You should normally prefer to use RunQueryDsl::load instead. This method is provided for situations where the result needs to be collected into a different container than a Vec

When using the query builder, the return type can be a tuple of the values, or a struct which implements Queryable. This type is specified by the first generic type of this function.

The second generic type paramater specifies the so called loading mode, which describes how the connection implementation loads data from the database. All connections should provide a implementaiton for DefaultLoadingMode.

They may provide additional modes. Checkout the documentation of the concrete connection types for details. For connection implementations that provide more than one loading mode it is required to specify this generic paramater. This is currently true for PgConnection.

When this method is called on sql_query, the return type can only be a struct which implements QueryableByName

For insert, update, and delete operations where only a count of affected is needed, execute should be used instead.

Examples
Returning a single field
use diesel::connection::DefaultLoadingMode;

let data = users.select(name)
    .load_iter::<String, DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
assert_eq!(vec!["Sean", "Tess"], data);
Returning a tuple
use diesel::connection::DefaultLoadingMode;

let data = users
    .load_iter::<(i32, String), DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
let expected_data = vec![
    (1, String::from("Sean")),
    (2, String::from("Tess")),
];
assert_eq!(expected_data, data);
Returning a struct
#[derive(Queryable, PartialEq, Debug)]
struct User {
    id: i32,
    name: String,
}

use diesel::connection::DefaultLoadingMode;

let data = users
    .load_iter::<User, DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
let expected_data = vec![
    User { id: 1, name: String::from("Sean") },
    User { id: 2, name: String::from("Tess") },
];
assert_eq!(expected_data, data);

Runs the command, and returns the affected row.

Err(NotFound) will be returned if the query affected 0 rows. You can call .optional() on the result of this if the command was optional to get back a Result<Option<U>>

When this method is called on an insert, update, or delete statement, it will implicitly add a RETURNING * to the query, unless a returning clause was already specified.

This method only returns the first row that was affected, even if more rows are affected.

Example
let inserted_row = insert_into(users)
    .values(name.eq("Ruby"))
    .get_result(connection)?;
assert_eq!((3, String::from("Ruby")), inserted_row);

// This will return `NotFound`, as there is no user with ID 4
let update_result = update(users.find(4))
    .set(name.eq("Jim"))
    .get_result::<(i32, String)>(connection);
assert_eq!(Err(diesel::NotFound), update_result);

Runs the command, returning an Vec with the affected rows.

This method is an alias for load, but with a name that makes more sense for insert, update, and delete statements.

Attempts to load a single record.

This method is equivalent to .limit(1).get_result()

Returns Ok(record) if found, and Err(NotFound) if no results are returned. If the query truly is optional, you can call .optional() on the result of this to get a Result<Option<U>>.

Example:
diesel::insert_into(users)
    .values(&vec![name.eq("Sean"), name.eq("Pascal")])
    .execute(connection)?;

let first_name = users.order(id).select(name).first(connection);
assert_eq!(Ok(String::from("Sean")), first_name);

let not_found = users
    .filter(name.eq("Foo"))
    .first::<(i32, String)>(connection);
assert_eq!(Err(diesel::NotFound), not_found);

Implementors