chdb_rust/
lib.rs

1//! # chdb-rust
2//!
3//! Rust FFI bindings for [chDB](https://github.com/chdb-io/chdb), an embedded ClickHouse database.
4//!
5//! ## Overview
6//!
7//! This crate provides a safe Rust interface to chDB, allowing you to execute ClickHouse SQL queries
8//! either statelessly (in-memory) or with persistent storage using sessions.
9//!
10//! ## Quick Start
11//!
12//! ```no_run
13//! use chdb_rust::execute;
14//! use chdb_rust::arg::Arg;
15//! use chdb_rust::format::OutputFormat;
16//!
17//! // Execute a simple query
18//! let result = execute("SELECT 1 + 1 AS sum", None)?;
19//! println!("Result: {}", result.data_utf8_lossy());
20//! # Ok::<(), chdb_rust::error::Error>(())
21//! ```
22//!
23//! ## Features
24//!
25//! - **Stateless queries**: Execute one-off queries without persistent storage
26//! - **Stateful sessions**: Create databases and tables with persistent storage
27//! - **Multiple output formats**: JSON, CSV, TabSeparated, and more
28//! - **Thread-safe**: Connections and results can be safely sent between threads
29//!
30//! ## Examples
31//!
32//! See the [`examples`](https://github.com/chdb-io/chdb-rust/tree/main/examples) directory for more detailed examples.
33//!
34//! ## Safety
35//!
36//! This crate uses `unsafe` code to interface with the C library, but provides a safe Rust API.
37//! All public functions are safe to call, and the crate ensures proper resource cleanup.
38
39pub mod arg;
40pub mod arrow_stream;
41#[allow(
42    dead_code,
43    unused,
44    non_snake_case,
45    non_camel_case_types,
46    non_upper_case_globals
47)]
48mod bindings;
49pub mod connection;
50pub mod error;
51pub mod format;
52pub mod log_level;
53pub mod query_result;
54pub mod session;
55
56use crate::arg::{extract_output_format, Arg};
57use crate::connection::Connection;
58use crate::error::Result;
59use crate::query_result::QueryResult;
60
61/// Execute a one-off query using an in-memory connection.
62///
63/// This function creates a temporary in-memory database connection, executes the query,
64/// and returns the result. It's suitable for queries that don't require persistent storage.
65///
66/// # Arguments
67///
68/// * `query` - The SQL query string to execute
69/// * `query_args` - Optional array of query arguments (e.g., output format)
70///
71/// # Returns
72///
73/// Returns a [`QueryResult`] containing the query output, or an [`Error`](error::Error) if
74/// the query fails.
75///
76/// # Examples
77///
78/// ```no_run
79/// use chdb_rust::execute;
80/// use chdb_rust::arg::Arg;
81/// use chdb_rust::format::OutputFormat;
82///
83/// // Simple query with default format
84/// let result = execute("SELECT 1 + 1 AS sum", None)?;
85/// println!("{}", result.data_utf8_lossy());
86///
87/// // Query with JSON output format
88/// let result = execute(
89///     "SELECT 'Hello' AS greeting, 42 AS answer",
90///     Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
91/// )?;
92/// println!("{}", result.data_utf8_lossy());
93/// # Ok::<(), chdb_rust::error::Error>(())
94/// ```
95///
96/// # Errors
97///
98/// This function will return an error if:
99/// - The query syntax is invalid
100/// - The connection cannot be established
101/// - The query execution fails
102pub fn execute(query: &str, query_args: Option<&[Arg]>) -> Result<QueryResult> {
103    let conn = Connection::open_in_memory()?;
104    let fmt = extract_output_format(query_args);
105    conn.query(query, fmt)
106}
chdb_rust/lib.rs

chdb_rust/
lib.rs
