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
impl Client
Sourcepub fn new() -> Result<Client>
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();
Sourcepub fn extensions(&self) -> Result<Vec<Extension>>
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();
Sourcepub fn collections(&self, href: &str) -> Result<Vec<Collection>>
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();
Sourcepub fn search(&self, href: &str, search: Search) -> Result<ItemCollection>
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();
Sourcepub fn search_to_arrow(
&self,
href: &str,
search: Search,
) -> Result<Vec<RecordBatch>>
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>§
Sourcepub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement<'_>, Error>
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.
Sourcepub fn set_prepared_statement_cache_capacity(&self, capacity: usize)
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.
Sourcepub fn flush_prepared_statement_cache(&self)
pub fn flush_prepared_statement_cache(&self)
Remove/finalize all prepared statements currently in the cache.
Sourcepub fn pragma_query_value<T, F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F,
) -> Result<T, Error>
pub fn pragma_query_value<T, F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> 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;
Sourcepub fn pragma_query<F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
f: F,
) -> Result<(), Error>
pub fn pragma_query<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, f: F, ) -> Result<(), Error>
Query the current rows/values of pragma_name
.
Prefer PRAGMA function introduced in DuckDB 3.20:
SELECT * FROM pragma_collation_list;
Sourcepub fn pragma<F>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: &dyn ToSql,
f: F,
) -> Result<(), Error>
pub fn pragma<F>( &self, schema_name: Option<DatabaseName<'_>>, pragma_name: &str, pragma_value: &dyn ToSql, f: F, ) -> 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(?);
Sourcepub fn pragma_update(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: &dyn ToSql,
) -> Result<(), Error>
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.
Sourcepub fn pragma_update_and_check<F, T>(
&self,
schema_name: Option<DatabaseName<'_>>,
pragma_name: &str,
pragma_value: &dyn ToSql,
f: F,
) -> Result<T, Error>
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>
Set a new value to pragma_name
and return the updated value.
Only few pragmas automatically return the updated value.
Sourcepub fn transaction(&mut self) -> Result<Transaction<'_>, Error>
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.
Sourcepub fn unchecked_transaction(&self) -> Result<Transaction<'_>, Error>
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.
Sourcepub fn savepoint(&mut self) -> Result<Savepoint<'_>, Error>
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.
Sourcepub fn savepoint_with_name<T>(
&mut self,
name: T,
) -> Result<Savepoint<'_>, Error>
pub fn savepoint_with_name<T>( &mut self, name: T, ) -> Result<Savepoint<'_>, Error>
Sourcepub fn execute_batch(&self, sql: &str) -> Result<(), Error>
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.
Sourcepub fn execute<P>(&self, sql: &str, params: P) -> Result<usize, Error>where
P: Params,
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.
Sourcepub fn path(&self) -> Option<&Path>
pub fn path(&self) -> Option<&Path>
Returns the path to the database file, if one exists and is known.
Sourcepub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> Result<T, Error>
pub fn query_row<T, P, F>(&self, sql: &str, params: P, f: F) -> 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.
Sourcepub fn query_row_and_then<T, E, P, F>(
&self,
sql: &str,
params: P,
f: F,
) -> Result<T, E>
pub fn query_row_and_then<T, E, P, F>( &self, sql: &str, params: P, f: F, ) -> Result<T, E>
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.
Sourcepub fn prepare(&self, sql: &str) -> Result<Statement<'_>, Error>
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.
Sourcepub fn interrupt_handle(&self) -> Arc<InterruptHandle>
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(())
}
Sourcepub fn is_autocommit(&self) -> bool
pub fn is_autocommit(&self) -> bool
Test for auto-commit mode. Autocommit mode is on by default.
Sourcepub fn try_clone(&self) -> Result<Connection, Error>
pub fn try_clone(&self) -> Result<Connection, Error>
Creates a new connection to the already-opened database.
Trait Implementations§
Source§impl From<Connection> for Client
impl From<Connection> for Client
Source§fn from(connection: Connection) -> Self
fn from(connection: Connection) -> Self
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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