MoteDB

AI-native embedded multimodal database for embodied intelligence. Columnar storage engine with ACID transactions, vector search, full-text search, and spatial indexing — in a single embedded library.

Status: pre-1.0. The Rust embedding API and storage engine are stable and heavily tested; the SQL surface and multi-language FFI are still evolving. See Supported SQL for the current feature set.

Quick Start

cargo add motedb

A minimal, runnable example (examples/hello_world.rs):

use motedb::{Database, QueryResult};

fn main() -> motedb::Result<()> {
    // Create or open an embedded database (single file + WAL sidecars).
    let db = Database::create("hello.mote")?;

    // Standard SQL: CREATE / INSERT / SELECT
    db.execute("CREATE TABLE users (id INT PRIMARY KEY, name TEXT, age INT)")?;
    db.execute("INSERT INTO users VALUES (1, 'Ada', 36)")?;
    db.execute("INSERT INTO users VALUES (2, 'Linus', 54)")?;

    // Query — materialize results
    let result = db.execute("SELECT name, age FROM users WHERE age > 40")?;
    if let QueryResult::Select { rows, .. } = result.materialize()? {
        for row in &rows {
            println!("{:?}", row);
        }
    }

    Ok(())
}

Run it with:

cargo run --example hello_world

For the multimodal features (vector / full-text / spatial search), see examples/crud.rs and the indexes overview.

Performance

Benchmark: 300K rows × 4 columns on Apple Silicon M-series vs SQLite 3.x WAL mode.

Memory: 257 B/row (vs SQLite 369 B/row — 30% less)

Architecture

┌─────────────────────────────────────────────────────┐
│                     MoteDB                           │
├──────────┬──────────┬──────────┬───────────────────┤
│  SQL     │  Vector  │  Text    │  Spatial          │
│  Parser  │  DiskANN │  FTS     │  i-Octree         │
├──────────┴──────────┴──────────┴───────────────────┤
│              Columnar Storage Engine                 │
│  ┌─────────┐  ┌──────────┐  ┌────────────────────┐ │
│  │ WAL     │→ │ Columnar │→ │ Columnar SSTable    │ │
│  │ (fsync) │  │ Buffer   │  │ (mmap + Snappy)     │ │
│  └─────────┘  └──────────┘  └────────────────────┘ │
├─────────────────────────────────────────────────────┤
│  MVCC Transaction │ Snapshot Isolation │ Conflict  │
└─────────────────────────────────────────────────────┘

• Storage: Columnar SSTable with Snappy compression, mmap zero-copy access
• Write Path: WAL (durability) → columnar buffer → auto-finalize → SSTable
• Read Path: SelectColumnar (zero-materialization), typed array access, predicate pushdown
• Transactions: VersionStore MVCC with snapshot isolation and conflict detection

Logging

MoteDB emits lifecycle and durability events (WAL flush, checkpoint, background thread errors) through the standard log facade. The library installs no logger itself — your application chooses one (e.g. env_logger, tracing, slog) and controls verbosity:

fn main() {
    // Install a logger (env_logger reads RUST_LOG).
    let _ = env_logger::Builder::from_env(
        env_logger::Env::default().default_filter_or("off")
    ).try_init();

    let db = motedb::Database::create("my_data").unwrap();
    // ...
}

RUST_LOG=motedb=info  ./your_app   # lifecycle events (open/close/checkpoint)
RUST_LOG=motedb=warn  ./your_app   # degraded conditions only
RUST_LOG=motedb=debug ./your_app   # verbose hot-path detail

With no logger installed, all logging compiles to a no-op (zero runtime cost). See examples/logging.rs for a runnable demo.

Features

Multimodal

Embedded Optimized

• Low memory: 257 B/row (30% less than SQLite)
• Zero-copy reads: mmap with on-demand page loading
• Fast writes: Zero-encode columnar INSERT (2.4M rows/s)
• Small disk: Snappy compression (~1.8x, 68 B/row)
• No daemon: Single library, embedded directly

ACID

• Atomic: WAL-based crash recovery
• Consistent: PK uniqueness, NOT NULL, type coercion
• Isolated: MVCC snapshot isolation
• Durable: WAL fsync + auto-finalize

Installation

cargo add motedb

Or in Cargo.toml:

[dependencies]
motedb = "0.5"

For minimal edge builds (no tokenizer, no parallelism), disable default features:

[dependencies]
motedb = { version = "0.5", default-features = false, features = ["jemalloc"] }

Configuration

Pick a preset that matches your device, or start from one and override fields:

use motedb::{Database, DBConfig};

// Edge device (low memory, periodic fsync, single write partition)
let config = DBConfig::for_edge();

// Robotics (fast sensor ingestion, vector support)
let config = DBConfig::for_robotics();

// Embodied AI (vision-language models, real-time control loops)
let config = DBConfig::for_embodied();

let db = Database::create_with_config("my_data", config)?;

See docs/ for the full configuration reference and per-field docs.

SQL Support

Supported: CREATE TABLE / CREATE INDEX (column, vector, text, spatial, timestamp) / CREATE TEXT|VECTOR|SPATIAL|TIMESTAMP INDEX, DROP TABLE [IF EXISTS] / DROP INDEX, ALTER TABLE (ADD COLUMN, AUTO_INCREMENT = N), INSERT, UPDATE, DELETE, SELECT with:

• WHERE, JOIN (INNER / LEFT / RIGHT / FULL), subqueries in WHERE
• GROUP BY (single- and multi-column), HAVING, ORDER BY, LIMIT/OFFSET
• DISTINCT (rows) and COUNT(DISTINCT col) aggregates
• Aggregates: COUNT, SUM, AVG, MIN, MAX, STDDEV, VARIANCE
• UNION / UNION ALL
• CASE WHEN ... THEN ... ELSE ... END
• WITH / Common Table Expressions (non-recursive; WITH name [(cols)] AS (SELECT ...), ... <main query>)
• Multimodal predicates: MATCH(col) AGAINST('q') (BM25 ranked FTS), vector <->/<~> ordering (DiskANN ANN), ST_WITHIN, ST_DISTANCE, ST_KNN
• Transactions: BEGIN / COMMIT / ROLLBACK, savepoints, read-your-writes visibility inside a transaction

Not yet supported: WITH RECURSIVE (the keyword is accepted but self-referencing CTEs error out), DECIMAL/DATE/BLOB types, window functions, and cross-statement server-side cursors.

Documentation

Full guides live in docs/:

• Quick start · Installation & config · SQL operations
• Batch operations · Transactions
• Indexes: overview · column · vector · text · spatial · timestamp
• Performance tuning · Data types · API reference · Best practices · FAQ

API docs: https://docs.rs/motedb

License

MIT — see LICENSE.