Skip to main content

QueryResult

Struct QueryResult 

Source
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

Source

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

Source

pub fn column_count(&self) -> usize

Number of columns in the result.

Source

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.

Source

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.

Source

pub fn rows_changed(&self) -> u64

Rows changed by an INSERT / UPDATE / DELETE. Zero for other statements.

Source

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.

Source

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.

Source

pub fn result_kind(&self) -> ResultKind

What kind of outcome the statement produced.

Source

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.

Source

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.

Source

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.

Source

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);
}
Source

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.

Trait Implementations§

Source§

impl Debug for QueryResult

Source§

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

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

impl Drop for QueryResult

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

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> 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> 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, U> TryFrom<U> for T
where U: Into<T>,

Source§

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>,

Source§

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.