Struct diesel::query_builder::InsertStatement

source ·
#[non_exhaustive]
pub struct InsertStatement<T: QuerySource, U, Op = Insert, Ret = NoReturningClause> { pub operator: Op, pub target: T, pub records: U, pub returning: Ret, /* private fields */ }
Expand description

A fully constructed insert statement.

The parameters of this struct represent:

  • T: The table we are inserting into
  • U: The data being inserted
  • Op: The operation being performed. The specific types used to represent this are private, but correspond to SQL such as INSERT or REPLACE. You can safely rely on the default type representing INSERT
  • Ret: The RETURNING clause of the query. The specific types used to represent this are private. You can safely rely on the default type representing a query without a RETURNING clause.

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§operator: Op

The operator used by this InsertStatement

Corresponds to either Insert or Replace

§target: T

The table we are inserting into

§records: U

The data which should be inserted

§returning: Ret

An optional returning clause

Implementations§

source§

impl<T: QuerySource, U, Op, Ret> InsertStatement<T, U, Op, Ret>

source

pub fn new(target: T, records: U, operator: Op, returning: Ret) -> Self

Create a new InsertStatement instance

source§

impl<T: QuerySource, U, C, Op, Ret> InsertStatement<T, InsertFromSelect<U, C>, Op, Ret>

source

pub fn into_columns<C2>( self, columns: C2, ) -> InsertStatement<T, InsertFromSelect<U, C2>, Op, Ret>
where C2: ColumnList<Table = T> + Expression, U: Query<SqlType = C2::SqlType>,

Set the column list when inserting from a select statement

See the documentation for insert_into for usage examples.

source§

impl<T: QuerySource, U, Op> InsertStatement<T, U, Op>

source

pub fn returning<E>( self, returns: E, ) -> InsertStatement<T, U, Op, ReturningClause<E>>
where InsertStatement<T, U, Op, ReturningClause<E>>: Query,

Specify what expression is returned after execution of the insert.

§Examples
§Inserting records:
let inserted_names = diesel::insert_into(users)
    .values(&vec![name.eq("Timmy"), name.eq("Jimmy")])
    .returning(name)
    .get_results(connection);
assert_eq!(Ok(vec!["Timmy".to_string(), "Jimmy".to_string()]), inserted_names);
source§

impl<T, U, Op, Ret> InsertStatement<T, U, Op, Ret>
where T: QuerySource, U: UndecoratedInsertRecord<T> + IntoConflictValueClause,

source

pub fn on_conflict_do_nothing( self, ) -> InsertStatement<T, OnConflictValues<U::ValueClause, NoConflictTarget, DoNothing>, Op, Ret>

Adds ON CONFLICT DO NOTHING to the insert statement, without specifying any columns or constraints to restrict the conflict to.

§Examples
§Single Record
let user = User { id: 1, name: "Sean" };

let inserted_row_count = diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(conn);
assert_eq!(Ok(1), inserted_row_count);

let inserted_row_count = diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(conn);
assert_eq!(Ok(0), inserted_row_count);
§Vec of Records
let user = User { id: 1, name: "Sean" };

let inserted_row_count = diesel::insert_into(users)
    .values(&vec![user, user])
    .on_conflict_do_nothing()
    .execute(conn);
assert_eq!(Ok(1), inserted_row_count);
source

pub fn on_conflict<Target>( self, target: Target, ) -> IncompleteOnConflict<InsertStatement<T, U::ValueClause, Op, Ret>, ConflictTarget<Target>>
where ConflictTarget<Target>: OnConflictTarget<T>,

Adds an ON CONFLICT to the insert statement, if a conflict occurs for the given unique constraint.

Target can be one of:

§Examples
§Specifying a column as the target
diesel::sql_query("CREATE UNIQUE INDEX users_name ON users (name)").execute(conn).unwrap();
let user = User { id: 1, name: "Sean" };
let same_name_different_id = User { id: 2, name: "Sean" };
let same_id_different_name = User { id: 1, name: "Pascal" };

assert_eq!(Ok(1), diesel::insert_into(users).values(&user).execute(conn));

let inserted_row_count = diesel::insert_into(users)
    .values(&same_name_different_id)
    .on_conflict(name)
    .do_nothing()
    .execute(conn);
assert_eq!(Ok(0), inserted_row_count);

let pk_conflict_result = diesel::insert_into(users)
    .values(&same_id_different_name)
    .on_conflict(name)
    .do_nothing()
    .execute(conn);
assert!(pk_conflict_result.is_err());
§Specifying multiple columns as the target
use diesel::upsert::*;

diesel::sql_query("CREATE UNIQUE INDEX users_name_hair_color ON users (name, hair_color)").execute(conn).unwrap();
let user = User { id: 1, name: "Sean", hair_color: "black" };
let same_name_different_hair_color = User { id: 2, name: "Sean", hair_color: "brown" };
let same_name_same_hair_color = User { id: 3, name: "Sean", hair_color: "black" };

assert_eq!(Ok(1), diesel::insert_into(users).values(&user).execute(conn));

let inserted_row_count = diesel::insert_into(users)
    .values(&same_name_different_hair_color)
    .on_conflict((name, hair_color))
    .do_nothing()
    .execute(conn);
assert_eq!(Ok(1), inserted_row_count);

let inserted_row_count = diesel::insert_into(users)
    .values(&same_name_same_hair_color)
    .on_conflict((name, hair_color))
    .do_nothing()
    .execute(conn);
assert_eq!(Ok(0), inserted_row_count);

See the documentation for on_constraint and do_update for more examples.

Trait Implementations§

source§

impl<T, U, Op> AsQuery for InsertStatement<T, U, Op, NoReturningClause>

§

type SqlType = <<InsertStatement<T, U, Op> as AsQuery>::Query as Query>::SqlType

The SQL type of Self::Query
§

type Query = InsertStatement<T, U, Op, ReturningClause<<T as Table>::AllColumns>>

What kind of query does this type represent?
source§

fn as_query(self) -> Self::Query

Converts a type which semantically represents a SQL query into the actual query being executed. See the trait level docs for more.
source§

impl<T: Clone + QuerySource, U: Clone, Op: Clone, Ret: Clone> Clone for InsertStatement<T, U, Op, Ret>
where T::FromClause: Clone,

source§

fn clone(&self) -> InsertStatement<T, U, Op, Ret>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<T: Debug + QuerySource, U: Debug, Op: Debug, Ret: Debug> Debug for InsertStatement<T, U, Op, Ret>
where T::FromClause: Debug,

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<T, U, Op, Ret> Query for InsertStatement<T, U, Op, ReturningClause<Ret>>

§

type SqlType = <Ret as Expression>::SqlType

The SQL type that this query represents. Read more
source§

impl<T, U, Op, Ret, DB> QueryFragment<DB> for InsertStatement<T, U, Op, Ret>
where DB: Backend + DieselReserveSpecialization, T: Table, T::FromClause: QueryFragment<DB>, U: QueryFragment<DB> + CanInsertInSingleQuery<DB>, Op: QueryFragment<DB>, Ret: QueryFragment<DB>,

source§

fn walk_ast<'b>(&'b self, out: AstPass<'_, 'b, DB>) -> QueryResult<()>

Walk over this QueryFragment for all passes. Read more
source§

fn to_sql(&self, out: &mut DB::QueryBuilder, backend: &DB) -> QueryResult<()>

Converts this QueryFragment to its SQL representation. Read more
source§

fn collect_binds<'b>( &'b self, out: &mut <DB as HasBindCollector<'b>>::BindCollector, metadata_lookup: &mut DB::MetadataLookup, backend: &'b DB, ) -> QueryResult<()>

Serializes all bind parameters in this query. Read more
source§

fn is_safe_to_cache_prepared(&self, backend: &DB) -> QueryResult<bool>

Is this query safe to store in the prepared statement cache? Read more
source§

fn is_noop(&self, backend: &DB) -> QueryResult<bool>

Does walking this AST have any effect?
source§

impl<T, U, Op, Ret> QueryId for InsertStatement<T, U, Op, Ret>
where T: QuerySource + QueryId + 'static, U: QueryId, Op: QueryId, Ret: QueryId,

§

type QueryId = InsertStatement<T, <U as QueryId>::QueryId, <Op as QueryId>::QueryId, <Ret as QueryId>::QueryId>

A type which uniquely represents Self in a SQL query. Read more
source§

const HAS_STATIC_QUERY_ID: bool = _

Can the SQL generated by Self be uniquely identified by its type? Read more
source§

fn query_id() -> Option<TypeId>

Returns the type id of Self::QueryId if Self::HAS_STATIC_QUERY_ID. Returns None otherwise. Read more
source§

impl<T: QuerySource, U, Op, Ret, Conn> RunQueryDsl<Conn> for InsertStatement<T, U, Op, Ret>

source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

impl<T: Copy + QuerySource, U: Copy, Op: Copy, Ret: Copy> Copy for InsertStatement<T, U, Op, Ret>
where T::FromClause: Copy,

Auto Trait Implementations§

§

impl<T, U, Op, Ret> Freeze for InsertStatement<T, U, Op, Ret>
where Op: Freeze, T: Freeze, U: Freeze, Ret: Freeze, <T as QuerySource>::FromClause: Freeze,

§

impl<T, U, Op, Ret> RefUnwindSafe for InsertStatement<T, U, Op, Ret>

§

impl<T, U, Op, Ret> Send for InsertStatement<T, U, Op, Ret>
where Op: Send, T: Send, U: Send, Ret: Send, <T as QuerySource>::FromClause: Send,

§

impl<T, U, Op, Ret> Sync for InsertStatement<T, U, Op, Ret>
where Op: Sync, T: Sync, U: Sync, Ret: Sync, <T as QuerySource>::FromClause: Sync,

§

impl<T, U, Op, Ret> Unpin for InsertStatement<T, U, Op, Ret>
where Op: Unpin, T: Unpin, U: Unpin, Ret: Unpin, <T as QuerySource>::FromClause: Unpin,

§

impl<T, U, Op, Ret> UnwindSafe for InsertStatement<T, U, Op, Ret>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> AsQuery for T
where T: Query,

§

type SqlType = <T as Query>::SqlType

The SQL type of Self::Query
§

type Query = T

What kind of query does this type represent?
source§

fn as_query(self) -> <T as AsQuery>::Query

Converts a type which semantically represents a SQL query into the actual query being executed. See the trait level docs for more.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Copy,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<Conn, DB, T> ExecuteDsl<Conn, DB> for T
where Conn: Connection<Backend = DB>, DB: Backend, T: QueryFragment<DB> + QueryId,

source§

fn execute(query: T, conn: &mut Conn) -> Result<usize, Error>

Execute this command
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoSql for T

source§

fn into_sql<T>(self) -> AsExprOf<Self, T>

Convert self to an expression for Diesel’s query builder. Read more
source§

fn as_sql<'a, T>(&'a self) -> AsExprOf<&'a Self, T>

Convert &self to an expression for Diesel’s query builder. Read more
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.