Struct Insert 

pub struct Insert<T> { /* private fields */ }

Performs one INSERT.

The Insert::end must be called to finalize the INSERT. Otherwise, the whole INSERT will be aborted.

Rows are sent progressively to spread network load.

Note: Metadata is Cached

If validation is enabled, this helper will query the metadata for the target table to learn the column names and types.

To avoid querying this metadata every time, it is cached within the Client.

Any concurrent changes to the table schema may cause insert failures if the metadata is no longer correct. For correct functioning, call Client::clear_cached_metadata() after any changes to the current database schema.

Implementations

impl<T> Insert<T>

pub fn into_any(self) -> Insert<()>

Converts this typed insert into a type-erased Insert<()>, preserving any row metadata (and thus schema validation) that was fetched for T.

This lets you to store Insert<()> in a container, for example HashMap<std::any::TypeId, Insert<()>>.

let mut insert = client.insert::<MyRow>("table").await?.into_any();
insert.write_any(&MyRow { ... }).await?;
insert.end().await?;

pub fn with_timeouts( self, send_timeout: Option<Duration>, end_timeout: Option<Duration>, ) -> Self

Sets timeouts for different operations.

send_timeout restricts time on sending a data chunk to a socket. None disables the timeout, it’s a default. It’s roughly equivalent to tokio::time::timeout(insert.write(...)).

end_timeout restricts time on waiting for a response from the CH server. Thus, it includes all work needed to handle INSERT by the CH server, e.g. handling all materialized views and so on. None disables the timeout, it’s a default. It’s roughly equivalent to tokio::time::timeout(insert.end(...)).

These timeouts are much more performant (~x10) than wrapping write() and end() calls into tokio::time::timeout().

pub fn with_roles( self, roles: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Configure the roles to use when executing INSERT statements.

Overrides any roles previously set by this method, Insert::with_option, Client::with_roles or Client::with_option.

An empty iterator may be passed to clear the set roles.

Panics

If called after the request is started, e.g., after Insert::write.

pub fn with_default_roles(self) -> Self

Clear any explicit roles previously set on this Insert or inherited from Client.

Overrides any roles previously set by Insert::with_roles, Insert::with_option, Client::with_roles or Client::with_option.

Panics

If called after the request is started, e.g., after Insert::write.

pub fn with_option( self, name: impl Into<String>, value: impl Into<String>, ) -> Self

Similar to Client::with_option, but for this particular INSERT statement only.

Panics

If called after the request is started, e.g., after Insert::write.

pub fn write<'a>( &'a mut self, row: &T::Value<'_>, ) -> impl Future<Output = Result<()>> + 'a + Send

where T: RowWrite,

Serializes the provided row into an internal buffer. Once the buffer is full, it’s sent to a background task writing to the socket.

Close to:

async fn write<T>(&self, row: &T) -> Result<usize>;

A returned future doesn’t depend on the row’s lifetime.

Returns an error if the row cannot be serialized or the background task failed. Once failed, the whole INSERT is aborted and cannot be used anymore.

Panics

If called after the previous call that returned an error.

pub fn write_any<'a, R>( &'a mut self, row: &R, ) -> impl Future<Output = Result<()>> + 'a + Send

where R: Row + Serialize,

Writes a row of any type R into this insert.

Unlike Insert::write, the row type R is inferred directly from the argument, no turbofish needed:

insert.write_any(&MyRow { ... }).await?;

This is the primary write method for type-erased Insert<()> obtained from Client::insert_any.

pub async fn end(self) -> Result<()>

Ends INSERT, the server starts processing the data.

Succeeds if the server returns 200, that means the INSERT was handled successfully, including all materialized views and quorum writes.

NOTE: If it isn’t called, the whole INSERT is aborted.