pub struct QueryResult { /* private fields */ }Expand description
A duckdb_result — materialised, or streaming when it came from
PreparedStatement::execute_streaming (feature duckdb-1-5) — destroyed
on drop.
Iterate the rows with next_chunk until it returns
Ok(None); an Err means the rows stopped early.
Implementations§
Source§impl QueryResult
impl QueryResult
Sourcepub fn statement_type(&self) -> StatementType
pub fn statement_type(&self) -> StatementType
What kind of statement produced this result: for a string of several
statements, the one whose result this is (see
query).
Works on every supported DuckDB (stable C API slot 17).
Source§impl QueryResult
impl QueryResult
Sourcepub fn column_count(&self) -> usize
pub fn column_count(&self) -> usize
Number of columns in the result.
Sourcepub fn column_name(&self, index: usize) -> Option<String>
pub fn column_name(&self, index: usize) -> Option<String>
Name of column index, or None if the index is out of range or the
name is not UTF-8.
Sourcepub fn column_type(&self, index: usize) -> Option<TypeId>
pub fn column_type(&self, index: usize) -> Option<TypeId>
TypeId of column index, or None if the index is out of range or
the type is one this build does not recognise.
Sourcepub fn rows_changed(&self) -> u64
pub fn rows_changed(&self) -> u64
Rows changed by an INSERT / UPDATE / DELETE. Zero for other
statements.
Sourcepub fn next_chunk(&mut self) -> Result<Option<OwnedDataChunk>, ExtensionError>
pub fn next_chunk(&mut self) -> Result<Option<OwnedDataChunk>, ExtensionError>
Fetches the next chunk of rows: Ok(None) once every row has been
read, Err if the rows stopped early.
Chunks hold at most duckdb_vector_size() rows; call this repeatedly:
while let Some(chunk) = result.next_chunk()? {
// ... read chunk.size() rows ...
}§Errors
duckdb_fetch_chunk returns null both at the end of the rows and when
fetching fails, recording the failure on the result. On a streaming
result that happens when execution fails part-way (a runtime error in
the query, an interrupt) or, up to DuckDB 1.5.x, when another
statement has run on the same connection, which invalidates the stream
(2.0.0 refuses that statement instead; see
PreparedStatement::execute_streaming).
This returns that error — with
DuckDB’s message — instead of reporting a clean end after a partial
result. Once it has returned Ok(None) or an error it keeps returning
the same thing without calling DuckDB again.
Sourcepub fn column_logical_type(&self, index: usize) -> Option<LogicalType>
pub fn column_logical_type(&self, index: usize) -> Option<LogicalType>
Returns the full LogicalType of column
index.
column_type collapses a column to its top-level
TypeId, which is all you need for a scalar but
loses everything about a STRUCT’s fields, a LIST’s element type, a
DECIMAL’s width and scale, or an ENUM’s dictionary. This keeps them.
Returns None when index is out of range.
Sourcepub fn result_kind(&self) -> ResultKind
pub fn result_kind(&self) -> ResultKind
What kind of outcome the statement produced.
Sourcepub fn is_streaming(&self) -> bool
pub fn is_streaming(&self) -> bool
Whether this result is streaming rather than fully materialised.
Only PreparedStatement::execute_streaming can produce a streaming
result, and even then DuckDB may decide to materialise — which is why
this is a question rather than a guarantee.
Requires duckdb-1-5: duckdb_result_is_streaming sits in the unstable
region of the C API struct.
Sourcepub unsafe fn arrow_options<'conn>(
&self,
) -> Result<ArrowOptions<'conn>, ExtensionError>
pub unsafe fn arrow_options<'conn>( &self, ) -> Result<ArrowOptions<'conn>, ExtensionError>
The Arrow production settings this result was created with
(duckdb_result_get_arrow_options).
Hand these to
arrow::to_arrow_schema and
arrow::data_chunk_to_arrow when
exporting this result’s chunks: they carry the client properties captured
when the query ran, which is what the chunks were built against.
§Errors
Returns an ExtensionError when DuckDB returns null, which it does
for a result with no internal data.
§Safety
The connection that ran this query must stay open for all of 'conn:
the options point at its ClientContext, and a QueryResult does not
borrow its connection. See
ArrowOptions::from_result.
ArrowOptions::from_connection
is the safe alternative.
Sourcepub const fn as_raw(&self) -> &duckdb_result
pub const fn as_raw(&self) -> &duckdb_result
Returns the raw duckdb_result.
Use this for C API calls this crate does not wrap. Do not destroy it — this value still owns it.
Sourcepub const unsafe fn from_raw(result: duckdb_result) -> Self
pub const unsafe fn from_raw(result: duckdb_result) -> Self
Takes ownership of a raw duckdb_result, which is then destroyed
(duckdb_destroy_result) on drop: the way back into this crate’s
RAII for a result a raw call filled in (duckdb_execute_pending, for
one).
§Safety
result must have been filled in by a successful DuckDB call
(duckdb_query, duckdb_execute_prepared, duckdb_execute_pending,
…) and must not be destroyed by anyone else. Its connection must stay
open while it is read. Chunks already fetched from it are not seen
again: next_chunk continues where the raw
fetching stopped.
§Example
use quack_rs::query::QueryResult;
// SAFETY: zeroed is a valid `duckdb_result`; DuckDB fills it in.
let mut raw: libduckdb_sys::duckdb_result = unsafe { std::mem::zeroed() };
// SAFETY: `con` is open.
let state = unsafe { libduckdb_sys::duckdb_query(con, c"SELECT 1".as_ptr(), &raw mut raw) };
if state == libduckdb_sys::DuckDBSuccess {
// SAFETY: filled in by a successful `duckdb_query`, owned by nothing else.
let result = unsafe { QueryResult::from_raw(raw) };
assert_eq!(result.column_count(), 1);
}Sourcepub const fn into_raw(self) -> duckdb_result
pub const fn into_raw(self) -> duckdb_result
Gives up ownership and returns the raw result, which the caller must
destroy (duckdb_destroy_result) or hand back to
from_raw. Whether next_chunk
had reached the end is not carried over.