Skip to content
ParticleDB

Rust SDK

The ParticleDB Rust SDK provides a typed client with vector search, KV, RAG, and AI helpers. It uses a trait-based design (SqlExecutor) so you can plug in any wire transport (PG, gRPC, HTTP) or use the built-in MockExecutor for testing.

Installation

Section titled “Installation”

Add to your Cargo.toml:

[dependencies]
particledb-sdk = "0.1"

Quick Start

Section titled “Quick Start”
use particledb_sdk::{ParticleDB, Config, Value};


// Create a client (with mock executor for testing)
let db = ParticleDB::mock(Config::default());


// Raw SQL queries
let result = db.query("SELECT * FROM users WHERE id = $1", &[Value::Int64(1)])?;
for row in &result.rows {
    let name: String = row.get_by_name("name")?;
    println!("User: {}", name);
}


// Vector similarity search
let results = db.vector().search("documents", "embedding", &[0.1, 0.2, 0.3], 5, None)?;


// Key-value store
db.kv().set("session:abc", "active")?;
let val = db.kv().get("session:abc")?;


// AI functions
let embedding = db.ai().embed("hello world", None)?;
let summary = db.ai().generate("Summarize this text...")?;


// RAG
let answer = db.rag().query("What is ParticleDB?", "docs_pipeline")?;

Custom Executor

Section titled “Custom Executor”

Implement SqlExecutor to connect to a real ParticleDB instance (e.g., via tokio-postgres):

use particledb_sdk::{SqlExecutor, QueryResult, Value, Config, ParticleDB};


struct MyExecutor { /* connection pool */ }


impl SqlExecutor for MyExecutor {
    fn execute_query(&self, sql: &str, params: &[Value]) -> particledb_sdk::Result<QueryResult> {
        todo!("send query over wire protocol")
    }
    fn execute_statement(&self, sql: &str, params: &[Value]) -> particledb_sdk::Result<u64> {
        todo!("send statement over wire protocol")
    }
}


let db = ParticleDB::with_executor(Config::default(), MyExecutor { /* ... */ });

Modules

Section titled “Modules”
ModuleDescription
clientConnection config, ParticleDB client, SqlExecutor trait, MockExecutor
vectorVector similarity search and index creation
kvKey-value get/set/delete/mset/incr
ragRetrieval-Augmented Generation pipelines
aiAI functions (embed, generate, classify, summarize)
typesValue, Row, QueryResult, FromValue trait
errorError enum and Result type alias
Section titled “Vector Search”
let vec_ops = db.vector();


// Search for nearest neighbors
let results = vec_ops.search("documents", "embedding", &[0.1, 0.2, 0.3], 5, None)?;
for r in &results {
    println!("distance: {:.4}", r.distance);
}


// Search with filter
let results = vec_ops.search(
    "documents", "embedding", &[0.1, 0.2, 0.3], 10,
    Some("category = 'science'"),
)?;


// Create a vector index
vec_ops.create_index("documents", "embedding", "hnsw", None)?;

Key-Value Operations

Section titled “Key-Value Operations”
let kv = db.kv();


// Set / Get
kv.set("user:1", "alice")?;
let val = kv.get("user:1")?;


// Set with TTL
kv.set_with_ttl("session:abc", "data", 3600)?;


// Batch operations
kv.mset(&[("k1", "v1"), ("k2", "v2")])?;
let vals = kv.mget(&["k1", "k2"])?;


// Atomic increment
let new_val = kv.incr("counter", 1)?;


// Delete
kv.delete("user:1")?;

RAG (Retrieval-Augmented Generation)

Section titled “RAG (Retrieval-Augmented Generation)”
let rag = db.rag();


// Query using a named pipeline
let answer = rag.query("What is ParticleDB?", "docs_pipeline")?;
println!("{}", answer);


// Create a pipeline
rag.create_pipeline("docs_pipeline", "documents", "embedding", "content", 5, "hybrid")?;

AI Functions

Section titled “AI Functions”
let ai = db.ai();


// Generate embeddings
let embedding = ai.embed("Hello world", None)?;


// Text generation
let text = ai.generate("Explain vector databases")?;


// Classification
let label = ai.classify("Great product!", &["positive", "negative", "neutral"])?;


// Summarization
let summary = ai.summarize("Long article text...")?;

Next Steps

Section titled “Next Steps”