Struct proton_client::ProtonClient
source · pub struct ProtonClient { /* private fields */ }
Implementations§
source§impl ProtonClient
impl ProtonClient
sourcepub async fn fetch<T: Row>(&self, query: &str) -> Result<RowCursor<T>>
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}");
}
sourcepub async fn fetch_all<T>(&self, query: &str) -> Result<Vec<T>>where
T: Row + for<'b> Deserialize<'b>,
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(())
}
sourcepub async fn fetch_one<T>(self, query: &str) -> Result<T>where
T: Row + for<'b> Deserialize<'b>,
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(())
}
sourcepub async fn fetch_optional<T>(self, query: &str) -> Result<Option<T>>where
T: Row + for<'b> Deserialize<'b>,
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(())
}
source§impl ProtonClient
impl ProtonClient
sourcepub async fn client(&self) -> &Client
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(())
}
sourcepub async fn url(&self) -> &str
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(())
}
source§impl ProtonClient
impl ProtonClient
sourcepub async fn insert<T: Row>(&self, table: &str) -> Result<Insert<T>>
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(())
}
source§impl ProtonClient
impl ProtonClient
sourcepub async fn inserter<T: Row>(&self, table: &str) -> Result<Inserter<T>>
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(())
}
source§impl ProtonClient
impl ProtonClient
sourcepub async fn execute_query(&self, query: &str) -> Result<()>
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(())
}
source§impl ProtonClient
impl ProtonClient
sourcepub async fn fetch_stream<T>(&self, query: &str) -> Result<RowCursor<T>>where
T: Row + for<'b> Deserialize<'b>,
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}");
}
Trait Implementations§
source§impl Clone for ProtonClient
impl Clone for ProtonClient
source§fn clone(&self) -> ProtonClient
fn clone(&self) -> ProtonClient
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Display for ProtonClient
impl Display for ProtonClient
source§fn fmt(&self, f: &mut Formatter<'_>) -> Result
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