Crate scopedb_client

Expand description

§ScopeDB SDK for Rust

Query ScopeDB and write rows from async Rust applications.

Upgrading an existing application? See Upgrade from 0.3 to 0.4, including the move from Ingest to Append.

§Install

Requires Rust 1.91.0 or later and Tokio.

cargo add scopedb-client serde_json
cargo add tokio --features macros,rt-multi-thread

§Run a query

Set SCOPEDB_ENDPOINT and SCOPEDB_API_KEY using the connection guide. Save this as src/main.rs and run cargo run:

use std::error::Error;

use scopedb_client::Client;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
    let endpoint = std::env::var("SCOPEDB_ENDPOINT")?;
    let api_key = std::env::var("SCOPEDB_API_KEY")?;
    let client = Client::builder(endpoint)
        .api_key(api_key)
        .build()?;

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

query() waits for the result. into_objects() returns rows keyed by column name.

§Write rows

With an existing events table containing id int and name string columns:

let stream = client.table("events")
    .append_stream()
    .build()?;
let row = serde_json::json!({"id": 1, "name": "page_view"});
stream.send(&row).await?;

let report = stream.shutdown().await?;
println!("Written: {} rows", report.committed_rows);

send() queues a row; shutdown() waits for pending writes and closes the stream. Use flush() to wait while keeping it open. If you already have NDJSON, use Table::append.

§Find what you need

Task	API reference
Read query results	`ResultSet`
Track or cancel a query	`StatementHandle`
Read or change table schemas	`Catalog`
Tune batching and retries	`AppendStreamBuilder`
Write logs or telemetry	Continue after a batch fails
Set timeouts or HTTP options	`ClientBuilder`
Inspect a failure	`Error`

For complete programs, see the examples. For ScopeQL syntax, see the query guide.

Re-exports§

pub use reqwest;

Modules§

migration: Upgrade from 0.3 to 0.4

Structs§

AppendAdmissionResult: Rows accepted by a bulk local-admission operation.
AppendBatchFailureEvent: Diagnostic event emitted after a rejected or ambiguous append batch.
AppendCircuitBreakerOptions: Continue-mode circuit breaker settings.
AppendDeliveryReport: Aggregate settlement information since the previous delivery barrier. Counts do not identify individual input records. Use application-owned business keys to reconcile rows before replaying them.
AppendDroppedRows: Local drop counters grouped by admission failure reason.
AppendErrorDetails: Structured failure details returned by the table append API.
AppendLastFailure: The most recent remote append failure observed by the stream.
AppendRowError: A validation error for one row in an append request.
AppendRowsResult: The result of a committed table append.
AppendStream: A cloneable, bounded producer handle for asynchronous table appends. Dropping every handle drains admitted rows in the background while the Tokio runtime remains alive. Use shutdown() to observe settlement before exiting.
AppendStreamBuilder: Configures a bounded, concurrent table append stream.
AppendStreamStats: A point-in-time snapshot of append stream counters and state.
Catalog: Reads database, schema, table, and view definitions.
CatalogColumn
CatalogColumnIndex: Additional column index. Supports type “search” and analyzer “log”.
CatalogDatabase
CatalogDistinct
CatalogDocument: Complete tenant catalog. Apply replaces the entire selected subtree. Typed definitions reject unknown fields; use Catalog::raw for newer definitions.
CatalogOptions: Preview, concurrency preconditions, and explicit data-loss authorization.
CatalogResource: A selected subtree. Names are unescaped identifiers. Apply replaces the whole definition; it is not a patch. Mutations never retry automatically.
CatalogResult: Normalized states compared in one transaction; None means absent.
CatalogSchema
CatalogSnapshot
CatalogTable: A complete table definition. Omitted collections are empty and omitted optional fields are cleared. Storage is accepted only at creation.
CatalogView
Client: An async client for queries, table writes, and catalog operations.
ClientBuilder: Builds a ScopeDB client with an optional API key and custom HTTP client.
Error: A failure with a message, optional HTTP diagnostics, and operation details.
FieldSchema
ResultSet
Schema
Statement: A query with optional execution limits. Use Self::execute to wait for its result, or Self::submit to retain a handle for progress and cancellation.
StatementErrorDetails: Structured failure returned for a failed statement.
StatementEstimatedProgress
StatementHandle: Tracks one submitted query. Keep the handle to inspect progress, wait for results, or request cancellation.
StatementProgress
StatementStatusCancelled
StatementStatusFailed
StatementStatusFinished
StatementStatusPending
StatementStatusRunning
Table: A table selected for writes or catalog reads.
WriteErrorDetails: Details of an interrupted write. An unknown outcome may have committed and must not be automatically replayed.

Enums§

AppendBatchFailureAction: Action taken after a batch failure listener is invoked.
AppendCircuitState: The state of the continue-mode availability circuit breaker.
AppendDeliveryOutcome: The aggregate result of a delivery barrier.
AppendFailurePolicy: Determines what an append stream does after one HTTP batch fails.
AppendState: The commit outcome used by table append responses and client-side write interruptions.
AppendStreamState: The lifecycle state of an append stream.
AppendTrySendError: A synchronous local-admission failure from AppendStream::try_send.
DataType
ErrorKind: ErrorKind is all kinds of Error of ScopeDB client.
StatementStatus
Value: A typed result cell. Equality compares encoded array, object, any, and binary values as strings; floats use Rust’s usual equality, including NaN != NaN.
WriteErrorReason: The client-side reason an in-flight write was interrupted.

Type Aliases§

ResultObject: One typed result row keyed by its ScopeQL output column name.