Struct duckdb::CachedStatement

source ·

pub struct CachedStatement<'conn> { /* private fields */ }

Expand description

Cacheable statement.

Statement will return automatically to the cache by default. If you want the statement to be discarded, call discard() on it.

Implementations§

source §

impl CachedStatement<'_>

source

pub fn discard(self)

Discard the statement, preventing it from being returned to its Connection’s collection of cached statements.

Methods from Deref<Target = Statement<'conn>>§

source

pub fn column_names(&self) -> Vec<String>

Get all the column names in the result set of the prepared statement.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

source

pub fn column_count(&self) -> usize

Return the number of columns in the result set returned by the prepared statement.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

source

pub fn column_name(&self, col: usize) -> Result<&String>

Returns the name assigned to a particular column in the result set returned by the prepared statement.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

§Failure

Returns an Error::InvalidColumnIndex if idx is outside the valid column range for this row.

Panics when column name is not valid UTF-8.

source

pub fn column_index(&self, name: &str) -> Result<usize>

Returns the column index in the result set for a given column name.

If there is no AS clause then the name of the column is unspecified and may change from one release of DuckDB to the next.

If associated DB schema can be altered concurrently, you should make sure that current statement has already been stepped once before calling this method.

§Failure

Will return an Error::InvalidColumnName when there is no column with the specified name.

source

pub fn execute<P: Params>(&mut self, params: P) -> Result<usize>

Execute the prepared statement.

On success, returns the number of rows that were changed or inserted or deleted.

§Example

§Use with positional parameters

fn update_rows(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("UPDATE foo SET bar = 'baz' WHERE qux = ?")?;
    // The `duckdb::params!` macro is mostly useful when the parameters do not
    // all have the same type, or if there are more than 32 parameters
    // at once.
    stmt.execute(params![1i32])?;
    // However, it's not required, many cases are fine as:
    stmt.execute(&[&2i32])?;
    // Or even:
    stmt.execute([2i32])?;
    Ok(())
}

§Use without parameters

fn delete_all(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("DELETE FROM users")?;
    stmt.execute([])?;
    Ok(())
}

§Failure

Will return Err if binding parameters fails, the executed statement returns rows (in which case query should be used instead), or the underlying DuckDB call fails.

source

pub fn insert<P: Params>(&mut self, params: P) -> Result<()>

Execute an INSERT.

§Note

This function is a convenience wrapper around execute() intended for queries that insert a single item. It is possible to misuse this function in a way that it cannot detect, such as by calling it on a statement which updates a single item rather than inserting one. Please don’t do that.

§Failure

Will return Err if no row is inserted or many rows are inserted.

source

pub fn query_arrow<P: Params>(&mut self, params: P) -> Result<Arrow<'_>>

Execute the prepared statement, returning a handle to the resulting vector of arrow RecordBatch

§Example

fn get_arrow_data(conn: &Connection) -> Result<Vec<RecordBatch>> {
    Ok(conn.prepare("SELECT * FROM test")?.query_arrow([])?.collect())
}

§Failure

Will return Err if binding parameters fails.

source

pub fn query<P: Params>(&mut self, params: P) -> Result<Rows<'_>>

Execute the prepared statement, returning a handle to the resulting rows.

Due to lifetime restricts, the rows handle returned by query does not implement the Iterator trait. Consider using query_map or query_and_then instead, which do.

§Example

§Use without parameters

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people")?;
    let mut rows = stmt.query([])?;

    let mut names = Vec::new();
    while let Some(row) = rows.next()? {
        names.push(row.get(0)?);
    }

    Ok(names)
}

§Use with positional parameters

fn query(conn: &Connection, name: &str) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test where name = ?")?;
    let mut rows = stmt.query(duckdb::params![name])?;
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}

Or, equivalently (but without the [params!] macro).

fn query(conn: &Connection, name: &str) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test where name = ?")?;
    let mut rows = stmt.query([name])?;
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}

§Failure

Will return Err if binding parameters fails.

source

pub fn query_map<T, P, F>( &mut self, params: P, f: F ) -> Result<MappedRows<'_, F>>
where P: Params, F: FnMut(&Row<'_>) -> Result<T>,

Executes the prepared statement and maps a function over the resulting rows, returning an iterator over the mapped function results.

f is used to transform the streaming iterator into a standard iterator.

This is equivalent to stmt.query(params)?.mapped(f).

§Example

§Use with positional params

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people")?;
    let rows = stmt.query_map([], |row| row.get(0))?;

    let mut names = Vec::new();
    for name_result in rows {
        names.push(name_result?);
    }

    Ok(names)
}

§Failure

Will return Err if binding parameters fails.

source

pub fn query_and_then<T, E, P, F>( &mut self, params: P, f: F ) -> Result<AndThenRows<'_, F>>
where P: Params, E: From<Error>, F: FnMut(&Row<'_>) -> Result<T, E>,

Executes the prepared statement and maps a function over the resulting rows, where the function returns a Result with Error type implementing std::convert::From<Error> (so errors can be unified).

This is equivalent to stmt.query(params)?.and_then(f).

§Example

§Use with positional params

fn get_names(conn: &Connection) -> Result<Vec<String>> {
    let mut stmt = conn.prepare("SELECT name FROM people WHERE id = ?")?;
    let rows = stmt.query_and_then(["one"], |row| row.get::<_, String>(0))?;

    let mut persons = Vec::new();
    for person_result in rows {
        persons.push(person_result?);
    }

    Ok(persons)
}

§Failure

Will return Err if binding parameters fails.

source

pub fn exists<P: Params>(&mut self, params: P) -> Result<bool>

Return true if a query in the SQL statement it executes returns one or more rows and false if the SQL returns an empty set.

source

pub fn query_row<T, P, F>(&mut self, params: P, f: F) -> Result<T>
where P: Params, F: FnOnce(&Row<'_>) -> Result<T>,

Convenience method to execute a query that is expected to return a single row.

If the query returns more than one row, all rows except the first are ignored.

Returns Err(QueryReturnedNoRows) 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<T>> (requires that the trait duckdb::OptionalExt is imported).

§Failure

Will return Err if the underlying DuckDB call fails.

source

pub fn row_count(&self) -> usize

Return the row count

source

pub fn step(&self) -> Option<StructArray>

Get next batch records in arrow-rs

source

pub fn parameter_count(&self) -> usize

Return the number of parameters that can be bound to this statement.

source

pub fn raw_bind_parameter<T: ToSql>( &mut self, one_based_col_index: usize, param: T ) -> Result<()>

Low level API to directly bind a parameter to a given index.

Note that the index is one-based, that is, the first parameter index is 1 and not 0. This is consistent with the DuckDB API and the values given to parameters bound as ?NNN.

The valid values for one_based_col_index begin at 1, and end at Statement::parameter_count, inclusive.

§Caveats

This should not generally be used, but is available for special cases such as:

binding parameters where a gap exists.
binding named and positional parameters in the same query.
separating parameter binding from query execution.

Statements that have had their parameters bound this way should be queried or executed by Statement::raw_query or Statement::raw_execute. Other functions are not guaranteed to work.

§Example

fn query(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("SELECT * FROM test WHERE name = ? AND value > ?2")?;
    stmt.raw_bind_parameter(1, "foo")?;
    stmt.raw_bind_parameter(2, 100)?;
    let mut rows = stmt.raw_query();
    while let Some(row) = rows.next()? {
        // ...
    }
    Ok(())
}