pub struct Connection { /* private fields */ }Expand description
A connection to a chDB database.
A Connection represents an active connection to a chDB database instance.
Connections can be created for in-memory databases or persistent databases
stored on disk.
§Thread Safety
Connection implements Send, meaning it can be safely transferred between threads.
However, the underlying chDB library may have limitations on concurrent access.
It’s recommended to use one connection per thread or implement proper synchronization.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
// Create an in-memory connection
let conn = Connection::open_in_memory()?;
// Execute a query
let result = conn.query("SELECT 1", OutputFormat::JSONEachRow)?;
println!("{}", result.data_utf8_lossy());Implementations§
Source§impl Connection
impl Connection
Sourcepub fn open(args: &[&str]) -> Result<Self>
pub fn open(args: &[&str]) -> Result<Self>
Connect to chDB with the given command-line arguments.
Use crate::session::SessionBuilder for a higher-level API that supports sessions and persistent storage.
§Arguments
args- Array of command-line arguments (e.g.,["--path=/tmp/db"])
§Examples
use chdb_rust::connection::Connection;
// Connect with custom arguments
let conn = Connection::open(&["--path=/tmp/mydb"])?;§Errors
Returns Error::ConnectionFailed if the
connection cannot be established.
Sourcepub fn open_in_memory() -> Result<Self>
pub fn open_in_memory() -> Result<Self>
Connect to an in-memory database.
Creates a connection to a temporary in-memory database. Data stored in this database will be lost when the connection is closed.
§Examples
use chdb_rust::connection::Connection;
let conn = Connection::open_in_memory()?;§Errors
Returns Error::ConnectionFailed if the
connection cannot be established.
Sourcepub fn query(&self, sql: &str, format: OutputFormat) -> Result<QueryResult>
pub fn query(&self, sql: &str, format: OutputFormat) -> Result<QueryResult>
Execute a query and return the result.
Executes a SQL query against the database and returns the result in the specified output format.
§Arguments
sql- The SQL query string to executeformat- The desired output format for the result
§Returns
Returns a QueryResult containing the query output, or an Error
if the query fails.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let conn = Connection::open_in_memory()?;
let result = conn.query("SELECT 1 + 1 AS sum", OutputFormat::JSONEachRow)?;
println!("{}", result.data_utf8_lossy());§Errors
Returns an error if:
- The query syntax is invalid
- The query references non-existent tables or columns
- The query execution fails for any other reason
Sourcepub fn query_stream<'a>(
&'a mut self,
sql: &str,
format: OutputFormat,
) -> Result<QueryStream<'a>>
pub fn query_stream<'a>( &'a mut self, sql: &str, format: OutputFormat, ) -> Result<QueryStream<'a>>
Execute a query and return a streaming result.
Unlike query, this returns a QueryStream that yields
result data in chunks. This is useful for large result sets that should not
be fully materialized in memory.
§Arguments
sql- The SQL query string to executeformat- The desired output format for each chunk
§Returns
Returns a QueryStream tied to this connection, or an Error if the query
cannot be started.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream(
"SELECT number FROM numbers(100_000)",
OutputFormat::JSONEachRow,
)?;
while let Some(chunk) = stream.next_chunk()? {
print!("{}", chunk.data_utf8_lossy());
}§Errors
Returns an error if:
- The query syntax is invalid
- The query references non-existent tables or columns
- The query execution fails for any other reason
Sourcepub fn query_stream_with_params<'a>(
&'a mut self,
sql: &str,
format: OutputFormat,
params: impl Into<QueryParams>,
) -> Result<QueryStream<'a>>
pub fn query_stream_with_params<'a>( &'a mut self, sql: &str, format: OutputFormat, params: impl Into<QueryParams>, ) -> Result<QueryStream<'a>>
Execute a query with ClickHouse {name:Type} parameter binding and stream text chunks.
Like Self::query_stream, but SQL placeholders are bound from params
before streaming begins. The connection is exclusively borrowed for the
stream’s lifetime. Syntax errors fail when the stream is created. A
missing placeholder binding is reported on the first
QueryStream::next_chunk, not at start.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_with_params(
"SELECT {x:UInt64} AS v",
OutputFormat::CSV,
[("x", 11_u64)],
)?;
while let Some(chunk) = stream.next_chunk()? {
print!("{}", chunk.data_utf8_lossy());
}§Errors
Returns an error if:
- The query syntax is invalid
- The query cannot be started
Sourcepub fn query_stream_arrow<'a>(
&'a mut self,
sql: &str,
) -> Result<ArrowQueryStream<'a>>
pub fn query_stream_arrow<'a>( &'a mut self, sql: &str, ) -> Result<ArrowQueryStream<'a>>
Execute a query and stream the result as Arrow record batches.
Each call to Iterator::next or ArrowQueryStream::next_batch on the
returned stream pulls a single arrow::record_batch::RecordBatch via the
Arrow C Data Interface.
Available when the crate is built with the arrow feature.
§Examples
use chdb_rust::connection::Connection;
let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_arrow("SELECT number FROM numbers(100_000)")?;
while let Some(batch) = stream.next_batch()? {
println!("rows: {}", batch.num_rows());
}Sourcepub fn query_arrow(&self, sql: &str) -> Result<ArrowReader>
pub fn query_arrow(&self, sql: &str) -> Result<ArrowReader>
Execute a query and take the whole result as one Arrow stream.
No Arrow IPC serialization or compression round-trip; conversion of
ClickHouse columns into Arrow buffers may still copy data. Prefer
query_stream_arrow when the result is too
large to hold at once.
The returned reader owns the Arrow stream. The C ABI transfers
out_stream->release to the caller, so the reader can be drained after
this connection is dropped.
Available when the crate is built with the arrow feature.
§Examples
use chdb_rust::connection::Connection;
let conn = Connection::open_in_memory()?;
let reader = conn.query_arrow("SELECT number FROM numbers(1000)")?;
for batch in reader {
println!("rows: {}", batch?.num_rows());
}Sourcepub fn query_arrow_with_opts(
&self,
sql: &str,
opts: &ArrowOptions,
) -> Result<ArrowReader>
pub fn query_arrow_with_opts( &self, sql: &str, opts: &ArrowOptions, ) -> Result<ArrowReader>
query_arrow with explicit type-mapping options.
Sourcepub fn query_stream_arrow_with_opts<'a>(
&'a mut self,
sql: &str,
opts: &ArrowOptions,
) -> Result<ArrowQueryStream<'a>>
pub fn query_stream_arrow_with_opts<'a>( &'a mut self, sql: &str, opts: &ArrowOptions, ) -> Result<ArrowQueryStream<'a>>
Stream a query’s result as Arrow record batches with explicit type-mapping options.
Sourcepub fn insert_stream<'a>(
&'a mut self,
sql: &str,
format: InputFormat,
) -> Result<InsertStream<'a>>
pub fn insert_stream<'a>( &'a mut self, sql: &str, format: InputFormat, ) -> Result<InsertStream<'a>>
Open a streaming INSERT.
The write-side counterpart of query_stream: send
the INSERT statement here, then push the rows in chunks. The statement
must carry no FORMAT clause and no inline data — the format is the
format argument, and the data goes through
InsertStream::append.
The connection is exclusively borrowed until the stream is finished, cancelled or dropped, because it accepts no other statement meanwhile.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::InputFormat;
let mut conn = Connection::open_in_memory()?;
let mut ins = conn.insert_stream("INSERT INTO t (a, b)", InputFormat::CSV)?;
ins.append(b"1,\"one\"\n")?;
let stats = ins.finish()?;§Errors
Returns Error::QueryError if the statement is invalid — a missing
table, say — which is reported when the stream is opened.
Sourcepub fn insert_stream_with_params<'a>(
&'a mut self,
sql: &str,
format: InputFormat,
params: impl Into<QueryParams>,
) -> Result<InsertStream<'a>>
pub fn insert_stream_with_params<'a>( &'a mut self, sql: &str, format: InputFormat, params: impl Into<QueryParams>, ) -> Result<InsertStream<'a>>
Open a streaming INSERT whose statement carries {name:Type}
placeholders.
The motivating case is INSERT INTO FUNCTION file({path:String}, ...),
where the destination itself is a bound value. See
query_with_params for binding rules.
Sourcepub fn query_with_params(
&self,
sql: &str,
format: OutputFormat,
params: impl Into<QueryParams>,
) -> Result<QueryResult>
pub fn query_with_params( &self, sql: &str, format: OutputFormat, params: impl Into<QueryParams>, ) -> Result<QueryResult>
Execute a query with ClickHouse {name:Type} parameter binding.
Parameter values are encoded here and bound in the chDB library; they
are never interpolated into the SQL text. Names in params need not match placeholder
order in the query. An empty params list is a plain query.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let conn = Connection::open_in_memory()?;
let result = conn.query_with_params(
"SELECT {x:UInt64} + {y:UInt64} AS total",
OutputFormat::CSV,
[("y", 5_u64), ("x", 7_u64)],
)?;§Errors
Returns an error if:
- The query syntax is invalid
- A
{name:Type}placeholder has no matching param - A value cannot be parsed as the type declared in the placeholder
- The query execution fails for any other reason
Sourcepub fn query_stream_arrow_with_params<'a>(
&'a mut self,
sql: &str,
params: impl Into<QueryParams>,
opts: Option<&ArrowOptions>,
) -> Result<ArrowQueryStream<'a>>
pub fn query_stream_arrow_with_params<'a>( &'a mut self, sql: &str, params: impl Into<QueryParams>, opts: Option<&ArrowOptions>, ) -> Result<ArrowQueryStream<'a>>
Execute a query with ClickHouse {name:Type} parameter binding and stream Arrow batches.
Like Self::query_stream_arrow, but SQL placeholders are bound from params
in the chDB library before streaming begins. The connection is exclusively borrowed
for the stream’s lifetime. Syntax errors fail when the stream is created.
A missing placeholder binding is reported on the first
ArrowQueryStream::next_batch, not at start.
§Examples
use chdb_rust::connection::Connection;
let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_arrow_with_params(
"SELECT {x:UInt64} AS v",
[("x", 11_u64)],
None,
)?;
while let Some(batch) = stream.next_batch()? {
println!("rows: {}", batch.num_rows());
}§Errors
Returns an error if:
- The query syntax is invalid
- The query cannot be started
Pass opts to control Arrow type mapping alongside the bindings; None
selects the engine’s default contract.
Sourcepub fn register_arrow_reader(
&mut self,
reader: Box<dyn RecordBatchReader + Send>,
) -> Result<ArrowRegistration<'_>>
pub fn register_arrow_reader( &mut self, reader: Box<dyn RecordBatchReader + Send>, ) -> Result<ArrowRegistration<'_>>
Register an owned Arrow reader for queries within a scoped lifetime.
The returned handle generates a process-unique name and unregisters on
close or drop. Use its sql_expr() in SQL and run the query through the
handle so lazy results cannot outlive the input reader.
Sourcepub fn register_arrow_stream(
&self,
table_name: &str,
arrow_stream: &ArrowStream,
) -> Result<()>
pub fn register_arrow_stream( &self, table_name: &str, arrow_stream: &ArrowStream, ) -> Result<()>
Register an Arrow C Data Interface stream for use with ArrowStream('name').
Pass a raw ArrowArrayStream* (see ArrowStream).
Registered names are not ordinary tables; query them with the
arrow_stream_table_sql helper, e.g.
SELECT * FROM ArrowStream('my_data').
The stream pointer must stay valid until unregister_arrow_table
is called or the connection is dropped.
§Examples
use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowStream};
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let conn = Connection::open_in_memory()?;
// let stream_ptr: *mut arrow::ffi::FFI_ArrowArrayStream = ...;
// let arrow_stream = unsafe { ArrowStream::from_raw(stream_ptr) };
// conn.register_arrow_stream("my_data", &arrow_stream)?;
// let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
// let _ = conn.query(&sql, OutputFormat::JSONEachRow)?;§Errors
Returns an error if:
- The table name contains invalid characters
- The Arrow stream handle is invalid
- Registration fails for any other reason
Sourcepub fn register_arrow_array(
&self,
table_name: &str,
arrow_schema: &ArrowSchema,
arrow_array: &ArrowArray,
) -> Result<()>
pub fn register_arrow_array( &self, table_name: &str, arrow_schema: &ArrowSchema, arrow_array: &ArrowArray, ) -> Result<()>
Register Arrow C Data Interface schema + array for use with ArrowStream('name').
libchdb wraps the pair in a one-shot stream. Query via
arrow_stream_table_sql.
§Arguments
table_name- The name to register for the Arrow stream table functionarrow_schema- The Arrow schema handle describing the array structurearrow_array- The Arrow array handle containing the data
§Returns
Returns Ok(()) on success, or an Error if registration fails.
§Examples
use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowArray, ArrowSchema};
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;
let conn = Connection::open_in_memory()?;
// Assuming you have Arrow C Data Interface schema and array handles
// let arrow_schema = unsafe { ArrowSchema::from_raw(schema_ptr) };
// let arrow_array = unsafe { ArrowArray::from_raw(array_ptr) };
// conn.register_arrow_array("my_data", &arrow_schema, &arrow_array)?;
// Query via the ArrowStream table function
// let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
// let result = conn.query(&sql, OutputFormat::JSONEachRow)?;§Errors
Returns an error if:
- The table name contains invalid characters
- The Arrow schema or array handles are invalid
- Registration fails for any other reason
Sourcepub fn unregister_arrow_table(&self, table_name: &str) -> Result<()>
pub fn unregister_arrow_table(&self, table_name: &str) -> Result<()>
Unregister an Arrow stream table function that was previously registered.
This function removes a previously registered Arrow stream table function, making it no longer available for queries.
§Arguments
table_name- The name of the Arrow stream table function to unregister
§Returns
Returns Ok(()) on success, or an Error if unregistration fails.
§Examples
use chdb_rust::connection::Connection;
use chdb_rust::arrow_stream::ArrowStream;
let conn = Connection::open_in_memory()?;
// Register a table
// let arrow_stream = ArrowStream::from_raw(stream_ptr);
// conn.register_arrow_stream("my_data", &arrow_stream)?;
// Use it...
// Unregister when done
// conn.unregister_arrow_table("my_data")?;§Errors
Returns an error if:
- The table name contains invalid characters
- The table was not previously registered
- Unregistration fails for any other reason