Struct Client

Source
pub struct Client {
    pub use_hive_partitioning: bool,
    pub convert_wkb: bool,
    pub union_by_name: bool,
    /* private fields */
}
Expand description

A client for making DuckDB requests for STAC objects.

Fields§

§use_hive_partitioning: bool

Whether to use hive partitioning

§convert_wkb: bool

Whether to convert WKB to native geometries.

If False, WKB metadata will be added.

§union_by_name: bool

Whether to use union_by_name when querying.

Defaults to true.

Implementations§

Source§

impl Client

Source

pub fn new() -> Result<Client>

Creates a new client with an in-memory DuckDB connection.

This function will install the spatial extension. If you’d like to manage your own extensions (e.g. if your extensions are stored in a different location), set things up then use connection.into() to get a new Client.

§Examples
use stac_duckdb::Client;

let client = Client::new().unwrap();
Source

pub fn extensions(&self) -> Result<Vec<Extension>>

Returns a vector of all extensions.

§Examples
use stac_duckdb::Client;

let client = Client::new().unwrap();
let extensions = client.extensions().unwrap();
Source

pub fn collections(&self, href: &str) -> Result<Vec<Collection>>

Returns one or more stac::Collection from the items in the stac-geoparquet file.

§Examples
use stac_duckdb::Client;

let client = Client::new().unwrap();
let collections = client.collections("data/100-sentinel-2-items.parquet").unwrap();
Source

pub fn search(&self, href: &str, search: Search) -> Result<ItemCollection>

Searches a single stac-geoparquet file.

§Examples
use stac_duckdb::Client;

let client = Client::new().unwrap();
let item_collection = client.search("data/100-sentinel-2-items.parquet", Default::default()).unwrap();
Source

pub fn search_to_arrow( &self, href: &str, search: Search, ) -> Result<Vec<RecordBatch>>

Searches to an iterator of record batches.

§Examples
use stac_duckdb::Client;

let client = Client::new().unwrap();
let record_batches = client.search_to_arrow("data/100-sentinel-2-items.parquet", Default::default()).unwrap();

Methods from Deref<Target = Connection>§

Source

pub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>, Error>

Prepare a SQL statement for execution, returning a previously prepared (but not currently in-use) statement if one is available. The returned statement will be cached for reuse by future calls to prepare_cached once it is dropped.

fn insert_new_people(conn: &Connection) -> Result<()> {
    {
        let mut stmt = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
        stmt.execute(["Joe Smith"])?;
    }
    {
        // This will return the same underlying DuckDB statement handle without
        // having to prepare it again.
        let mut stmt = conn.prepare_cached("INSERT INTO People (name) VALUES (?)")?;
        stmt.execute(["Bob Jones"])?;
    }
    Ok(())
}
§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn set_prepared_statement_cache_capacity(&self, capacity: usize)

Set the maximum number of cached prepared statements this connection will hold. By default, a connection will hold a relatively small number of cached statements. If you need more, or know that you will not use cached statements, you can set the capacity manually using this method.

Source

pub fn flush_prepared_statement_cache(&self)

Remove/finalize all prepared statements currently in the cache.

Source

pub fn pragma_query_value<T, F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> Result<T, Error>
where F: FnOnce(&Row<'_>) -> Result<T, Error>,

Query the current value of pragma_name.

Some pragmas will return multiple rows/values which cannot be retrieved with this method.

Prefer PRAGMA function introduced in DuckDB 3.20: SELECT user_version FROM pragma_user_version;

Source

pub fn pragma_query<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> Result<(), Error>
where F: FnMut(&Row<'_>) -> Result<(), Error>,

Query the current rows/values of pragma_name.

Prefer PRAGMA function introduced in DuckDB 3.20: SELECT * FROM pragma_collation_list;

Source

pub fn pragma<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, f: F, ) -> Result<(), Error>
where F: FnMut(&Row<'_>) -> Result<(), Error>,

Query the current value(s) of pragma_name associated to pragma_value.

This method can be used with query-only pragmas which need an argument (e.g. table_info('one_tbl')) or pragmas which returns value(s) (e.g. integrity_check).

Prefer PRAGMA function introduced in DuckDB 3.20: SELECT * FROM pragma_table_info(?);

Source

pub fn pragma_update( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, ) -> Result<(), Error>

Set a new value to pragma_name.

Some pragmas will return the updated value which cannot be retrieved with this method.

Source

pub fn pragma_update_and_check<F, T>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, f: F, ) -> Result<T, Error>
where F: FnOnce(&Row<'_>) -> Result<T, Error>,

Set a new value to pragma_name and return the updated value.

Only few pragmas automatically return the updated value.

Source

pub fn transaction(&mut self) -> Result<Transaction<'_>, Error>

Begin a new transaction with the default behavior (DEFERRED).

The transaction defaults to rolling back when it is dropped. If you want the transaction to commit, you must call commit or set_drop_behavior(DropBehavior: :Commit).

§Example
fn perform_queries(conn: &mut Connection) -> Result<()> {
    let tx = conn.transaction()?;

    do_queries_part_1(&tx)?; // tx causes rollback if this fails
    do_queries_part_2(&tx)?; // tx causes rollback if this fails

    tx.commit()
}
§Failure

Will return Err if the underlying DuckDB call fails.

Source

pub fn unchecked_transaction(&self) -> Result<Transaction<'_>, Error>

Begin a new transaction with the default behavior (DEFERRED).

Attempt to open a nested transaction will result in a DuckDB error. Connection::transaction prevents this at compile time by taking &mut self, but Connection::unchecked_transaction() may be used to defer the checking until runtime.

See Connection::transaction and Transaction::new_unchecked (which can be used if the default transaction behavior is undesirable).

§Example
fn perform_queries(conn: Rc<Connection>) -> Result<()> {
    let tx = conn.unchecked_transaction()?;

    do_queries_part_1(&tx)?; // tx causes rollback if this fails
    do_queries_part_2(&tx)?; // tx causes rollback if this fails

    tx.commit()
}
§Failure

Will return Err if the underlying DuckDB call fails. The specific error returned if transactions are nested is currently unspecified.

Source

pub fn savepoint(&mut self) -> Result<Savepoint<'_>, Error>

Begin a new savepoint with the default behavior (DEFERRED).

The savepoint defaults to rolling back when it is dropped. If you want the savepoint to commit, you must call commit or [set_drop_behavior(DropBehavior::Commit)](Savepoint:: set_drop_behavior).

§Example
fn perform_queries(conn: &mut Connection) -> Result<()> {
    let sp = conn.savepoint()?;

    do_queries_part_1(&sp)?; // sp causes rollback if this fails
    do_queries_part_2(&sp)?; // sp causes rollback if this fails

    sp.commit()
}
§Failure

Will return Err if the underlying DuckDB call fails.

Source

pub fn savepoint_with_name<T>( &mut self, name: T, ) -> Result<Savepoint<'_>, Error>
where T: Into<String>,

Begin a new savepoint with a specified name.

See savepoint.

§Failure

Will return Err if the underlying DuckDB call fails.

Source

pub fn execute_batch(&self, sql: &str) -> Result<(), Error>

Convenience method to run multiple SQL statements (that cannot take any parameters).

§Example
fn create_tables(conn: &Connection) -> Result<()> {
    conn.execute_batch("BEGIN;
                        CREATE TABLE foo(x INTEGER);
                        CREATE TABLE bar(y TEXT);
                        COMMIT;",
    )
}
§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn execute<P>(&self, sql: &str, params: P) -> Result<usize, Error>
where P: Params,

Convenience method to prepare and execute a single SQL statement.

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

§Example
§With params
fn update_rows(conn: &Connection) {
    match conn.execute("UPDATE foo SET bar = 'baz' WHERE qux = ?", [1i32]) {
        Ok(updated) => println!("{} rows were updated", updated),
        Err(err) => println!("update failed: {}", err),
    }
}
§With params of varying types
fn update_rows(conn: &Connection) {
    match conn.execute("UPDATE foo SET bar = ? WHERE qux = ?", params![&"baz", 1i32]) {
        Ok(updated) => println!("{} rows were updated", updated),
        Err(err) => println!("update failed: {}", err),
    }
}
§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn path(&self) -> Option<&Path>

Returns the path to the database file, if one exists and is known.

Source

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

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

§Example
fn preferred_locale(conn: &Connection) -> Result<String> {
    conn.query_row(
        "SELECT value FROM preferences WHERE name='locale'",
        [],
        |row| row.get(0),
    )
}

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

§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn query_row_and_then<T, E, P, F>( &self, sql: &str, params: P, f: F, ) -> Result<T, E>
where P: Params, F: FnOnce(&Row<'_>) -> Result<T, E>, E: From<Error>,

Convenience method to execute a query that is expected to return a single row, and execute a mapping via f on that returned row with the possibility of failure. The Result type of f must implement std::convert::From<Error>.

§Example
fn preferred_locale(conn: &Connection) -> Result<String> {
    conn.query_row_and_then(
        "SELECT value FROM preferences WHERE name='locale'",
        [],
        |row| row.get(0),
    )
}

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

§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn prepare(&self, sql: &str) -> Result<Statement<'_>, Error>

Prepare a SQL statement for execution.

§Example
fn insert_new_people(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("INSERT INTO People (name) VALUES (?)")?;
    stmt.execute(["Joe Smith"])?;
    stmt.execute(["Bob Jones"])?;
    Ok(())
}
§Failure

Will return Err if sql cannot be converted to a C-compatible string or if the underlying DuckDB call fails.

Source

pub fn appender(&self, table: &str) -> Result<Appender<'_>, Error>

Create an Appender for fast import data default to use DatabaseName::Main

§Example
fn insert_rows(conn: &Connection) -> Result<()> {
    let mut app = conn.appender("foo")?;
    app.append_rows([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])?;
    Ok(())
}
§Failure

Will return Err if table not exists

Source

pub fn appender_to_db( &self, table: &str, schema: &str, ) -> Result<Appender<'_>, Error>

Create an Appender for fast import data

§Example
fn insert_rows(conn: &Connection) -> Result<()> {
    let mut app = conn.appender_to_db("foo", &DatabaseName::Main.to_string())?;
    app.append_rows([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])?;
    Ok(())
}
§Failure

Will return Err if table not exists

Source

pub fn interrupt_handle(&self) -> Arc<InterruptHandle>

Get a handle to interrupt long-running queries.

§Example
fn run_query(conn: Connection) -> Result<()> {
  let interrupt_handle = conn.interrupt_handle();
  let join_handle = std::thread::spawn(move || { conn.execute("expensive query", []) });

  // Arbitrary wait for query to start
  std::thread::sleep(std::time::Duration::from_millis(100));

  interrupt_handle.interrupt();

  let query_result = join_handle.join().unwrap();
  assert!(query_result.is_err());

  Ok(())
}
Source

pub fn is_autocommit(&self) -> bool

Test for auto-commit mode. Autocommit mode is on by default.

Source

pub fn try_clone(&self) -> Result<Connection, Error>

Creates a new connection to the already-opened database.

Source

pub fn version(&self) -> Result<String, Error>

Returns the version of the DuckDB library

Trait Implementations§

Source§

impl Debug for Client

Source§

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

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

impl Deref for Client

Source§

type Target = Connection

The resulting type after dereferencing.
Source§

fn deref(&self) -> &Self::Target

Dereferences the value.
Source§

impl DerefMut for Client

Source§

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.
Source§

impl From<Connection> for Client

Source§

fn from(connection: Connection) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

§

impl !Freeze for Client

§

impl !RefUnwindSafe for Client

§

impl Send for Client

§

impl !Sync for Client

§

impl Unpin for Client

§

impl UnwindSafe for Client

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> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
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.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<G1, G2> Within<G2> for G1
where G2: Contains<G1>,

Source§

fn is_within(&self, b: &G2) -> bool

Source§

impl<T> ErasedDestructor for T
where T: 'static,