Trait diesel::query_dsl::RunQueryDsl
source · pub trait RunQueryDsl<Conn>: Sized {
// Provided methods
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§
sourcefn execute(self, conn: &mut Conn) -> QueryResult<usize>where
Conn: Connection,
Self: ExecuteDsl<Conn>,
fn execute(self, conn: &mut Conn) -> QueryResult<usize>where
Conn: Connection,
Self: ExecuteDsl<Conn>,
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);
sourcefn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
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);
sourcefn 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 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,
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);
sourcefn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>where
Self: LoadQuery<'query, Conn, U>,
fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>where
Self: LoadQuery<'query, Conn, U>,
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);
sourcefn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<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>,
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.
sourcefn first<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
fn first<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
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);