Struct proton_client::ProtonClient

pub struct ProtonClient { /* private fields */ }

Implementations

impl ProtonClient

pub async fn fetch<T: Row>(&self, query: &str) -> Result<RowCursor<T>>

Executes the query, returning a RowCursor to obtain results.

Example

 use proton_client::ProtonClient;
 use proton_client::prelude::Result;

 async fn example() -> Result<()> {

#[derive(Debug, clickhouse::Row, serde::Deserialize)]
struct MyRow<'a> {
    no: u32,
    name: &'a str,
}

let client = ProtonClient::new("http://localhost:8123");

 let mut cursor = client
    .fetch::<MyRow<'_>>("SELECT ?fields from table(test_stream) WHERE no BETWEEN 500 AND 504")
    .await
    .expect("[main/fetch]: Failed to fetch data");

while let Some(MyRow { name, no }) = cursor.next().await.expect("[main/fetch]: Failed to fetch data") {
    println!("{name}: {no}");
}

pub async fn fetch_all<T>(&self, query: &str) -> Result<Vec<T>>

where T: Row + for<'b> Deserialize<'b>,

Executes the query and returns all the generated results, collected into a Vec.

Note that T must be owned.

Errors

This function will return an error if:

• The API call fails

Example

use proton_client::prelude::{ProtonClient, Result};

#[derive(clickhouse::Row, serde::Deserialize)]
struct MyRow{
    no: u32,
    name: String,
}

async fn example() -> Result<()> {

let client = ProtonClient::new("http://localhost:8123");

let query = "SELECT ?fields FROM test_stream WHERE no BETWEEN 0 AND 1";
let data = client.fetch_all::<MyRow>(query).await.unwrap();

println!("Received {} records", data.len());

  Ok(())
}

pub async fn fetch_one<T>(self, query: &str) -> Result<T>

where T: Row + for<'b> Deserialize<'b>,

Executes the query and returns just a single row.

Note that T must be owned.

Errors

This function will return an error if:

• The API call fails

Example

use proton_client::prelude::{ProtonClient, Result};

async fn example() -> Result<()> {

let client = ProtonClient::new("http://localhost:8123");
let query = "select count() from table(test_stream)";
let item = client.fetch_one::<u64>(query).await.unwrap();

println!("Single result: {:#?}", item);

  Ok(())
}

pub async fn fetch_optional<T>(self, query: &str) -> Result<Option<T>>

where T: Row + for<'b> Deserialize<'b>,

Executes the query and returns at most one row.

Note that T must be owned.

Errors

This function will return an error if:

• The API call fails

Example

use proton_client::prelude::{ProtonClient, Result};

#[derive(clickhouse::Row, serde::Deserialize, Debug)]
struct MyRow{
    no: u32,
    name: String,
}

async fn example() -> Result<()> {

let client = ProtonClient::new("http://localhost:8123");
let item_id = 42;
let query = "SELECT ?fields FROM test_stream WHERE no = 42";
let item = client.fetch_optional::<MyRow>(query).await.unwrap();

match item {
    Some(item) => println!("Fetched: {:#?}", item),
    None => println!("No item with id {}", item_id),
}

  Ok(())
}

impl ProtonClient

pub async fn client(&self) -> &Client

Returns a reference to the internal clickhouse client.

This can be used for making lower-level requests.

For details on how to use the client, see the clickhouse client crate.

Example

use proton_client::prelude::{ProtonClient, Result};

async fn example() -> Result<()> {

let client = ProtonClient::new("http://localhost:8123");

let url = client.client().await;

Ok(())
}

pub async fn url(&self) -> &str

Returns the base URL of the Proton API endpoint.

This is the root URL passed to the client during construction.

Example

use proton_client::prelude::{ProtonClient, Result};

async fn example() -> Result<()> {

let client = ProtonClient::new("http://localhost:8123");

let url = client.url().await;

assert_eq!(url, "http://localhost:8123");

Ok(())
}

impl ProtonClient

pub async fn insert<T: Row>(&self, table: &str) -> Result<Insert<T>>

Inserts a new data item into Proton.

Pass in the data to insert to add it to Proton.

Arguments

• table - The table name to insert into

Errors

This method will return an error if:

• The API call fails

Example

 use proton_client::ProtonClient;
 use proton_client::prelude::{Result, Row};
 use serde::{Deserialize, Serialize};

#[derive(Debug, Row, Serialize, Deserialize)]
pub struct MyRow<'a> {
    no: u32,
    name: &'a str,
}

impl<'a> MyRow<'a> {
    pub fn new(no: u32, name: &'a str) -> Self {
        Self { no, name }
    }
}

 async fn example() -> Result<()> {

    let client = ProtonClient::new("http://localhost:8123");
    let mut insert = client.insert("table_name").await?;

   insert
    .write(&MyRow::new(42, "foo"))
    .await
    .expect(" Failed to insert row into table some");

    insert.end().await.expect("Failed to end insert");

    Ok(())
 }

impl ProtonClient

pub async fn inserter<T: Row>(&self, table: &str) -> Result<Inserter<T>>

Inserts bulk data into Proton.

Arguments

• table - The table name to insert into

Errors

This method will return an error if:

• The API call fails

Example

 use proton_client::prelude::{ProtonClient,Result, Row};
 use serde::{Deserialize, Serialize};

#[derive(Debug, Row, Serialize, Deserialize)]
pub struct MyRow<'a> {
    no: u32,
    name: &'a str,
}

 async fn example() -> Result<()> {

    let client = ProtonClient::new("http://localhost:8123");
     let mut inserter = client
        .inserter("table_name")
        .await
        .expect("Failed to create inserter")
        .with_max_entries(100_000); //  The maximum number of rows in one INSERT statement.

    for i in 0..1000 {
        inserter.write(&MyRow { no: i, name: "foo" }).await.expect("Failed to insert row");
        inserter.commit().await.expect("Failed to commit"); // Checks limits and ends a current INSERT if they are reached.
    }

    inserter.end().await.expect("Failed to end inserter"); // Ends a current INSERT and whole Inserter unconditionally.

    Ok(())
 }

impl ProtonClient

pub async fn execute_query(&self, query: &str) -> Result<()>

Executes a query against Proton.

Pass a query string to run against the Proton data. Returns the result.

Arguments

• query - The query string to execute

Errors

This method will return an error if:

• The API call fails
• Query syntax is invalid

Example

 use proton_client::ProtonClient;
 use proton_client::prelude::Result;

 async fn example() -> Result<()> {

 let client = ProtonClient::new("http://localhost:8123");

     client
        .execute_query("CREATE STREAM IF NOT EXISTS test_stream(no uint32, name string) ORDER BY no")
        .await
        .expect("Failed to execute query");

  Ok(())
}

impl ProtonClient

pub async fn fetch_stream<T>(&self, query: &str) -> Result<RowCursor<T>>

where T: Row + for<'b> Deserialize<'b>,

Executes a streaming query, returning a RowCursor to obtain results as they become available from the stream. The key difference compared to fetch is that, for streaming query, the returned result is a unbounded stream. Also, a fetch_stream query will keep running continuously returning fresh data until the application terminates..

Example

 use proton_client::ProtonClient;
 use proton_client::prelude::Result;

 async fn example() -> Result<()> {

#[derive(Debug, clickhouse::Row, serde::Deserialize)]
struct MyRow {
    no: u32,
    name: String,
}

let client = ProtonClient::new("http://localhost:3218");

 let mut cursor = client
    .fetch_stream::<MyRow>("SELECT ?fields from (test_stream) WHERE no BETWEEN 500 AND 504")
    .await
    .expect("[main/fetch]: Failed to fetch stream data");

while let Some(MyRow { name, no }) = cursor.next().await.expect("[main/fetch]: Failed to fetch data") {
    println!("{name}: {no}");
}

impl ProtonClient

pub fn new(url: &str) -> Self

Creates a new Proton client instance. `

Arguments

• url - The base URL of the Proton API endpoint.

Returns

Returns a new Proton client instance with the provided base URL.

Example

use proton_client::ProtonClient;

let client = ProtonClient::new("http://localhost:8123");

Trait Implementations

impl Clone for ProtonClient

fn clone(&self) -> ProtonClient

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ProtonClient

fn default() -> Self

Returns a default configured Proton client instance.

The default configuration includes:

• Default URL is set to http://localhost:8123

Returns

A Proton client instance with default configuration.

Example

use proton_client::ProtonClient;

let proton = ProtonClient::default();

impl Display for ProtonClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the ProtonClient for display.

This converts the ProtonClient into a string containing the base URL.

Example

use proton_client::ProtonClient;

let client = ProtonClient::new("http://localhost:8123");

println!("Client connected to: {}", client);

Output:

Client connected to: http://localhost:8123