Struct Client 

pub struct Client { /* private fields */ }

Async ClickHouse client using the native TCP protocol.

Create a client by calling Client::connect with ClientOptions. The client holds a single TCP connection and is not Clone; for concurrent access, create multiple client instances.

Implementations

impl Client

pub async fn connect(options: ClientOptions) -> Result<Self>

Connect to ClickHouse server with retry and endpoint failover

pub async fn execute(&mut self, query: impl Into<Query>) -> Result<()>

Execute a DDL/DML query without returning data

Use this for queries that don’t return result sets:

• CREATE/DROP TABLE, DATABASE
• ALTER TABLE
• TRUNCATE
• Other DDL/DML operations

For SELECT queries, use query() instead. For query tracing, use execute_with_id().

Example

client.execute("CREATE TABLE test (id UInt32) ENGINE = Memory").await?;
client.execute("DROP TABLE test").await?;

pub async fn execute_with_id( &mut self, query: impl Into<Query>, query_id: &str, ) -> Result<()>

Execute a DDL/DML query with a specific query ID

The query ID is useful for query tracing and debugging.

Example

client.execute_with_id("CREATE TABLE test (id UInt32) ENGINE = Memory", "create-123").await?;

pub async fn query(&mut self, query: impl Into<Query>) -> Result<QueryResult>

Execute a query and return results

For INSERT operations, use insert() instead. For DDL/DML without results, use execute() instead. For query tracing, use query_with_id().

pub async fn query_with_id( &mut self, query: impl Into<Query>, query_id: &str, ) -> Result<QueryResult>

Execute a query with a specific query ID and return results

The query ID is useful for query tracing and debugging.

Example

let result = client.query_with_id("SELECT 1", "select-123").await?;

pub async fn query_with_external_data( &mut self, query: impl Into<Query>, external_tables: &[ExternalTable], ) -> Result<QueryResult>

Execute a SELECT query with external tables for JOIN operations

External tables allow passing temporary in-memory data to queries for JOINs without creating actual tables in ClickHouse.

Example

// Create a block with temporary data
let mut block = Block::new();
// ... populate block with data ...

// Create external table
let ext_table = ExternalTable::new("temp_table", block);

// Use in query with JOIN
let query = "SELECT * FROM my_table JOIN temp_table ON my_table.id = temp_table.id";
let result = client.query_with_external_data(query, &[ext_table]).await?;

pub async fn query_with_external_data_and_id( &mut self, query: impl Into<Query>, query_id: &str, external_tables: &[ExternalTable], ) -> Result<QueryResult>

Execute a SELECT query with external tables and a specific query ID

Combines external table support with query ID tracing.

Example

let ext_table = ExternalTable::new("temp_table", block);
let result = client.query_with_external_data_and_id(
    "SELECT * FROM my_table JOIN temp_table ON my_table.id = temp_table.id",
    "query-123",
    &[ext_table]
).await?;

pub async fn insert(&mut self, table_name: &str, block: Block) -> Result<()>

Insert data into a table

This method constructs an INSERT query from the block’s column names and sends the data. Example: client.insert("my_database.my_table", block).await?

For query tracing, use insert_with_id() to specify a query ID.

pub async fn insert_with_id( &mut self, table_name: &str, query_id: &str, block: Block, ) -> Result<()>

Insert data into a table with a specific query ID

The query ID is useful for:

• Query tracing and debugging
• Correlating queries with logs
• OpenTelemetry integration

Example

client.insert_with_id("my_table", "trace-id-12345", block).await?;

pub async fn ping(&mut self) -> Result<()>

Ping the server

pub async fn cancel(&mut self) -> Result<()>

Cancel the current query

Sends a cancel packet to the server to stop any currently running query. Note: This is most useful when called with a cancelable callback, or when you need to cancel a long-running query from outside the query execution flow.

pub fn server_info(&self) -> &ServerInfo

Get server info

Returns information about the connected ClickHouse server including name, version, revision, timezone, and display name.

Example

let info = client.server_info();
println!("Server: {} v{}.{}.{}",
    info.name,
    info.version_major,
    info.version_minor,
    info.version_patch
);

pub fn server_version(&self) -> (u64, u64, u64)

Get server version as a tuple (major, minor, patch)

Example

let (major, minor, patch) = client.server_version();
println!("Server version: {}.{}.{}", major, minor, patch);

pub fn server_revision(&self) -> u64

Get server revision number

The revision number is used for protocol feature negotiation.

Example

let revision = client.server_revision();
println!("Server revision: {}", revision);