Struct duckdb::Statement [−][src]
pub struct Statement<'conn> { /* fields omitted */ }
Expand description
A prepared statement.
Implementations
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.
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.
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.
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
.
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.
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.
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.
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.
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>,
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.
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.
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.
Get next batch records
Return the number of parameters that can be bound to this statement.
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(())
}
Low level API to execute a statement given that all parameters were
bound explicitly with the Statement::raw_bind_parameter
API.
Caveats
Any unbound parameters will have NULL
as their value.
This should not generally be used outside of special cases, and
functions in the Statement::execute
family should be preferred.
Failure
Will return Err
if the executed statement returns rows (in which case
query
should be used instead), or the underlying DuckDB call fails.
Low level API to get Rows
for this query given that all parameters
were bound explicitly with the Statement::raw_bind_parameter
API.
Caveats
Any unbound parameters will have NULL
as their value.
This should not generally be used outside of special cases, and
functions in the Statement::query
family should be preferred.
Note that if the SQL does not return results, Statement::raw_execute
should be used instead.