pub trait Cursor: ResultSetMetadata {
// Required method
fn bind_buffer<B>(
self,
row_set_buffer: B
) -> Result<BlockCursor<Self, B>, Error>
where Self: Sized,
B: RowSetBuffer;
// Provided method
fn next_row(&mut self) -> Result<Option<CursorRow<'_>>, Error> { ... }
}
Expand description
Cursors are used to process and iterate the result sets returned by executing queries.
Example: Fetching result in batches
use odbc_api::{Cursor, buffers::{BufferDesc, ColumnarAnyBuffer}, Error};
/// Fetches all values from the first column of the cursor as i32 in batches of 100 and stores
/// them in a vector.
fn fetch_all_ints(cursor: impl Cursor) -> Result<Vec<i32>, Error> {
let mut all_ints = Vec::new();
// Batch size determines how many values we fetch at once.
let batch_size = 100;
// We expect the first column to hold INTEGERs (or a type convertible to INTEGER). Use
// the metadata on the result set, if you want to investige the types of the columns at
// runtime.
let description = BufferDesc::I32 { nullable: false };
// This is the buffer we bind to the driver, and repeatedly use to fetch each batch
let buffer = ColumnarAnyBuffer::from_descs(batch_size, [description]);
// Bind buffer to cursor
let mut row_set_buffer = cursor.bind_buffer(buffer)?;
// Fetch data batch by batch
while let Some(batch) = row_set_buffer.fetch()? {
all_ints.extend_from_slice(batch.column(0).as_slice().unwrap())
}
Ok(all_ints)
}
Required Methods§
sourcefn bind_buffer<B>(
self,
row_set_buffer: B
) -> Result<BlockCursor<Self, B>, Error>where
Self: Sized,
B: RowSetBuffer,
fn bind_buffer<B>( self, row_set_buffer: B ) -> Result<BlockCursor<Self, B>, Error>where Self: Sized, B: RowSetBuffer,
Binds this cursor to a buffer holding a row set.
Provided Methods§
sourcefn next_row(&mut self) -> Result<Option<CursorRow<'_>>, Error>
fn next_row(&mut self) -> Result<Option<CursorRow<'_>>, Error>
Advances the cursor to the next row in the result set. This is Slow. Bind buffers instead, for good performance.
While this method is very convenient due to the fact that the application does not have to
declare and bind specific buffers it is also in many situations extremely slow. Concrete
performance depends on the ODBC driver in question, but it is likely it performs a roundtrip
to the datasource for each individual row. It is also likely an extra conversion is
performed then requesting individual fields, since the C buffer type is not known to the
driver in advance. Consider binding a buffer to the cursor first using
Self::bind_buffer
.