本文介绍如何使用 ClickHouse Rust (HTTP) 驱动连接并访问 ByteHouse 云数仓。

获取ClickHouse驱动后，可以通过cargo进行安装：

# Install ClickHouse with native-tls feature
cargo add clickhouse@0.13.1 --features native-tls
# Install tokio with full features (required for async operations)
cargo add tokio@1.0.1 --features full
# Install anyhow for error handling (optional but recommended)
cargo add anyhow
# Install serde with derive features (required for Row trait)
cargo add serde --features derive

或者将以下内容添加到Cargo. toml：

[dependencies]
anyhow = "1.0.95"
clickhouse = { version = "0.13.1", features = ["native-tls"] }
serde = { version = "1.0.217", features = ["derive"] }
tokio = { version = "1.0.1", features = ["full"] }

可参考下面代码样例，通过Rust驱动连接ByteHouse。

use clickhouse::Client;
use anyhow::Result;

pub async fn create_client() -> Result<()> {
    // Create a client
    let client = Client::default()
        .with_url("https://tenant-{TENANT_ID}-{REGION}-public.bytehouse.volces.com:8123")
        .with_database("your_database")
        .with_user("bytehouse")
        .with_password("your_api_key");
        .with_option("virtual_warehouse", "your_vw_id");

    // Test connection with a simple query
    let result: u8 = client
        .query("SELECT 1")
        .fetch_one()
        .await?;

    println!("Query result: {}", result);

    Ok(())
}

连接ByteHouse后，您可以通过ClickHouse Rust (HTTP) Driver进行建表、数据读写等操作，以下为简单的操作示例。

示例1：建表、数据读写

use clickhouse::Row;
use serde::{Deserialize, Serialize};
use anyhow::Result;
use crate::utils::create_client;

#[derive(Debug, Row, Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    age: u8,
    active: bool,
}

pub async fn quickstart_example() -> Result<()> {
    let client = create_client();

    // Drop table if exists and create a new one
    client
        .query("DROP TABLE IF EXISTS users")
        .execute()
        .await?;

    client
        .query(
            "
            CREATE TABLE users (
                id       UInt32,
                name     String,
                age      UInt8,
                active   Bool
            ) ENGINE = CnchMergeTree()
            ORDER BY id
            "
        )
        .execute()
        .await?;

    println!("Table created successfully");

    // Insert some sample data
    let mut insert = client.insert("users")?;

    let users = vec![
        User {
            id: 1,
            name: "Alice".to_string(),
            age: 25,
            active: true,
        },
        User {
            id: 2,
            name: "Bob".to_string(),
            age: 30,
            active: true,
        },
        User {
            id: 3,
            name: "Charlie".to_string(),
            age: 35,
            active: false,
        },
    ];

    for user in users {
        insert.write(&user).await?;
    }

    insert.end().await?;
    println!("Data inserted successfully");

    // Select all users
    let all_users = client
        .query("SELECT ?fields FROM users")
        .fetch_all::<User>()
        .await?;

    println!("\nAll users:");
    for user in all_users {
        println!("{:?}", user);
    }

    Ok(())
}

示例2：传递Query ID

您也可以在连接ByteHouse时设置将Query ID传递给客户端。

use anyhow::Result;
use crate::utils::create_client;

pub async fn query_id_example() -> Result<()> {
    let client = create_client();

    // Use a simple string as query ID
    let query_id = "test_query_id_1";

    // Execute a simple query with the query ID
    let result = client
        .query("SELECT 1")
        .with_option("query_id", query_id)
        .fetch_one::<u8>()
        .await?;

    println!("Query ID: {}", query_id);
    println!("Result: {}", result);

    Ok(())
}