Rust SDK

The Rust SDK lets your application read and write Spiral Tables directly. You open a Table by name, such as frames in Project demo, scan an exact version as a stream of Arrow record batches, and publish new rows in a commit. The bytes move straight between your process and object storage, so Spiral's services never sit in the data path.

The same client manages Organizations, Projects, Workloads, Applications, installations and access grants. These operations use the HTTP API and need no native library.

Use Client for authenticated resource operations and workflows that select a state, read data or publish changes. It shares your connection pool and resolves current credentials before every request. Collections fetch pages lazily and retain their filters and continuation tokens.

let page = client.projects().list().page_size(20).send().await?;
for project in page.items {
    println!(
        "{}: {}",
        project.id,
        project.description.unwrap_or_default()
    );
}
let snapshot = client.project("demo")?.branch("main").await?;
let table = snapshot.table("frames").await?;
println!("Table version: {}", table.identity().version_id);

For direct service calls, construct a raw generated client from spiral::api and supply an authorization header to each operation. Raw clients work independently of Client and its credential discovery.

use spiral::api::project::{ProjectApi, ProjectClient};

let projects = ProjectClient::new("https://api.spiraldb.dev")?;
let project = projects.read_project(authorization, "demo".into()).await?;
println!("Project: {}", project.id);

The Rust API reference lists request and response types, raw service clients and declared errors.

Choose where Table work runs. The embedded backend reads and writes storage inside your process through libspiral. The remote backend streams Arrow through Connect, served by ScanDAL, including Spiral's hosted endpoint. Select the backend explicitly with the client builder; see Choose a backend.

The SDK has no SQL engine. For SQL, add the DataFusion integration.

InstallCopy Anchor Link

Install spiral-sdk from crates.io. The API reference is at docs.rs/spiral-sdk.

The package is spiral-sdk, and its library name is spiral, so your code imports from spiral:

use spiral::{Client, ScanOptions};

Import Arrow types through spiral::arrow_array and spiral::arrow_schema rather than depending on Arrow yourself. The re-exports keep your Arrow version identical to the SDK's, so batches pass between them without conversion.

Choose a backendCopy Anchor Link

Both backends return the same Scan and batch-stream types, so the rest of your code does not change when you switch.

The embedded backend runs libspiral, a native library that Cargo links into your application from a prepared archive (see Use the embedded backend). Use the archive from the same SDK release as your crate, because the interface between them can change in any release. The SDK resolves Table names and supplies the host resolver once. The native library asks it for scoped storage access for both Table files and blob references, and reuses each binding until renewal. Writes request separate access for one attempt or publication. Your application supplies identity and resource IDs; storage credentials stay internal to the host. Explicit local roots and compatibility transports remain available. See Architecture for how this split keeps your data out of Spiral's services.

A Cargo feature never selects a backend on its own; the client builder does.

Cargo featuresCopy Anchor Link

Each cloud or platform feature groups its integrations under one name. Today these bundles provide workload identity and shared refresh.

With default-features = false, you get the clients for the Catalog and the other resource services, without the Table API or private-key sign-in. The SDK uses rustls and never links OpenSSL. TLS and key signing both go through rustls's process-wide crypto provider: the SDK installs the provider its features select, unless your application installed one first. To bring your own provider, disable aws-lc and ring and call CryptoProvider::install_default before you create a client.

LicensingCopy Anchor Link

The SDK source and wrappers use the MIT license. The embedded libspiral runtime has a separate native binary license, included as LICENSE-libspiral in the SDK crate and each native archive. It permits commercial use, linking and redistribution with your applications; restrictions on reverse engineering apply to its proprietary code, subject to applicable law and third-party licenses. Your application code keeps its own license.

GuidesCopy Anchor Link

The task guides live with each service: create a Table, write rows, read rows, and select an exact state. The pages in this section cover the Rust API itself:

• Client: endpoints, credentials, and the embedded backend.
• Sessions: Snapshot, BranchHead and TableSession, branch pins, and resolved addresses.
• Commits: publish, a moved branch, and recovery.
• Reading: ScanOptions, computed outputs, and parallel streams.
• Writing: write methods, Arrow input, and recovering a write.
• Functions: SPQL functions on your own Arrow batches.
• Errors: error variants and what to do about each.