Struct Client 

pub struct Client { /* private fields */ }

An async client for queries, table writes, and catalog operations.

Start with Self::builder to configure your endpoint and API key. Clones share the underlying HTTP connection pool.

Implementations

impl Client

pub fn builder(endpoint: impl ToString) -> ClientBuilder

Starts a client builder for the common API-key authentication path.

Examples found in repository

examples/common/mod.rs (line 43)

pub fn client() -> Result<Client, Box<dyn std::error::Error>> {
    let api_key = std::env::var("SCOPEDB_API_KEY")
        .ok()
        .filter(|value| !value.is_empty())
        .or_else(|| {
            std::env::var("SCOPEDB_TOKEN")
                .ok()
                .filter(|value| !value.is_empty())
        });
    let mut builder = Client::builder(endpoint());
    if let Some(api_key) = api_key {
        builder = builder.api_key(api_key);
    }
    Ok(builder.build()?)
}

pub fn new<E: IntoUrl>(endpoint: E, client: Client) -> Result<Self, Error>

Creates a ScopeDB client from an endpoint and a compatible HTTP client.

Use the HTTP types re-exported from crate::reqwest to avoid a dependency-version mismatch in applications using another reqwest major. Configure the HTTP client as described in ClientBuilder::http_client to prevent automatic write replay. The write timeout defaults to 30 seconds.

pub fn statement(&self, statement: impl Into<String>) -> Statement

Examples found in repository

examples/statement.rs (line 27)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub fn statement_handle(&self, statement_id: Uuid) -> StatementHandle

pub fn table(&self, table: impl Into<String>) -> Table

Examples found in repository

examples/common/mod.rs (line 62)

pub fn write_table(client: &Client) -> Result<Table, io::Error> {
    let table = std::env::var("SCOPEDB_TABLE")
        .ok()
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "set SCOPEDB_TABLE to a disposable table before running this write example",
            )
        })?;

    Ok(client
        .table(table)
        .with_database(database())
        .with_schema(schema()))
}

examples/table.rs (line 22)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;
    let table_name = std::env::var("SCOPEDB_TABLE").unwrap_or_else(|_| "events".to_string());
    let table = client
        .table(table_name)
        .with_database(common::database())
        .with_schema(common::schema());

    println!("identifier: {}", table.identifier());

    let description = table.catalog().get().await?.definition;
    for column in description.columns {
        println!("{}: {:?}", column.name, column.data_type);
    }

    Ok(())
}

pub async fn query( &self, statement: impl Into<String>, ) -> Result<ResultSet, Error>

Executes a ScopeQL statement and waits for all result rows. Errors after submission retain Error::statement_id for resuming the existing execution with Self::statement_handle, not resubmitting it.

Examples found in repository

examples/statement.rs (line 21)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub fn catalog(&self) -> Catalog

Selects the complete declarative catalog or an individual resource.

Examples found in repository

examples/catalog.rs (line 23)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;
    let database = common::database();
    let schema = common::schema();

    let catalog = client.catalog().get().await?;
    for item in catalog.definition.databases {
        println!(
            "database {}: {}",
            item.name,
            item.comment.unwrap_or_default()
        );
    }
    let snapshot = client.catalog().schema(&database, &schema).get().await?;
    println!("schema ETag: {}", snapshot.etag);
    for table in snapshot.definition.tables {
        println!("table {}: {:?}", table.name, table.columns);
    }
    Ok(())
}

pub async fn append_rows( &self, database: &str, schema: &str, table: &str, ndjson: impl Into<String>, ) -> Result<AppendRowsResult, Error>

Appends at most 8 MiB of uncompressed newline-delimited JSON to a table.

Sends one request without automatic retries. An unknown outcome remains non-retryable through Error::is_retryable because replay may duplicate rows.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.