VelesDB Mobile

Last updated: 2026-06-14.

Native bindings for iOS (Swift) and Android (Kotlin) via UniFFI.

VelesDB Mobile brings microsecond vector search to edge devices - perfect for on-device AI, semantic search, and RAG applications.

Features

• Native Performance: Direct Rust bindings, minimal FFI overhead
• Multi-Query Fusion: Native MQG with RRF/Weighted strategies
• Binary Quantization: 32x memory reduction for constrained devices
• ARM NEON SIMD: Optimized for mobile processors (Apple A-series, Snapdragon)
• Offline-First: Full functionality without network connectivity
• Thread-Safe: Safe to use from multiple threads/queues

Quick Start

Swift (iOS)

import VelesDB

// Open database (UniFFI named constructor — Rust `#[uniffi::constructor] open` becomes a Swift static method, not a default init)
let db = try VelesDatabase.open(path: documentsPath + "/velesdb")

// Create collection (768D for MiniLM, 384D for all-MiniLM-L6-v2)
try db.createCollection(name: "documents", dimension: 384, metric: .cosine)

// Get collection
guard let collection = try db.getCollection(name: "documents") else {
    fatalError("Collection not found")
}

// Insert vectors
let point = VelesPoint(
    id: 1,
    vector: embedding,  // [Float] from your embedding model
    payload: "{\"title\": \"Hello World\"}"
)
try collection.upsert(point: point)

// Search
let results = try collection.search(vector: queryEmbedding, limit: 10)
for result in results {
    print("ID: \(result.id), Score: \(result.score)")
}

Kotlin (Android)

import com.velesdb.mobile.*

// Open database (UniFFI named constructor — Rust `#[uniffi::constructor] open` becomes a Kotlin companion-object factory, not a default constructor)
val db = VelesDatabase.open("${context.filesDir}/velesdb")

// Create collection
db.createCollection("documents", 384u, DistanceMetric.COSINE)

// Get collection
val collection = db.getCollection("documents")
    ?: throw Exception("Collection not found")

// Insert vectors
val point = VelesPoint(
    id = 1uL,
    vector = embedding,  // List<Float> from your embedding model
    payload = """{"title": "Hello World"}"""
)
collection.upsert(point)

// Search (use Dispatchers.IO for async)
val results = withContext(Dispatchers.IO) {
    collection.search(queryEmbedding, 10u)
}
results.forEach { result ->
    println("ID: ${result.id}, Score: ${result.score}")
}

Build Instructions

Prerequisites

# Install Rust targets
rustup target add aarch64-apple-ios        # iOS device
rustup target add aarch64-apple-ios-sim    # iOS simulator (ARM)
rustup target add x86_64-apple-ios         # iOS simulator (Intel)

rustup target add aarch64-linux-android    # Android ARM64
rustup target add armv7-linux-androideabi  # Android ARMv7
rustup target add x86_64-linux-android     # Android x86_64

# For Android: Install cargo-ndk
cargo install cargo-ndk

iOS Build

# Build for device
cargo build --release --target aarch64-apple-ios -p velesdb-mobile

# Build for simulator
cargo build --release --target aarch64-apple-ios-sim -p velesdb-mobile

# Generate Swift bindings
cargo run -p velesdb-mobile --bin uniffi-bindgen -- generate \
    --library target/aarch64-apple-ios/release/libvelesdb_mobile.a \
    --language swift \
    --out-dir bindings/swift

# Create XCFramework (requires macOS)
xcodebuild -create-xcframework \
    -library target/aarch64-apple-ios/release/libvelesdb_mobile.a \
    -headers bindings/swift \
    -library target/aarch64-apple-ios-sim/release/libvelesdb_mobile.a \
    -headers bindings/swift \
    -output VelesDB.xcframework

Android Build

# Build for all Android ABIs
cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 \
    build --release -p velesdb-mobile

# Generate Kotlin bindings
cargo run -p velesdb-mobile --bin uniffi-bindgen -- generate \
    --library target/aarch64-linux-android/release/libvelesdb_mobile.so \
    --language kotlin \
    --out-dir bindings/kotlin

# Libraries are in:
# - target/aarch64-linux-android/release/libvelesdb_mobile.so
# - target/armv7-linux-androideabi/release/libvelesdb_mobile.so
# - target/x86_64-linux-android/release/libvelesdb_mobile.so

API Reference

VelesDatabase

VelesCollection

The filterJson shape

The filterJson argument on searchWithFilter, textSearchWithFilter, hybridSearchWithFilter, and multiQuerySearchWithFilter is a JSON string using the same canonical filter shape as the core engine and REST API: {"condition": {"type": <op>, "field": ..., "value"/"values"/"pattern"/"conditions": ...}}. Operators: eq, neq, gt, gte, lt, lte, in, contains, like, ilike, is_null, is_not_null, array_contains, array_contains_any, array_contains_all, geo_distance, geo_bbox, and and/or/not for composition.

Swift:

let results = try collection.searchWithFilter(
    vector: queryVector,
    limit: 5,
    filterJson: #"{"condition": {"type": "eq", "field": "category", "value": "tech"}}"#
)

Kotlin:

val results = collection.searchWithFilter(
    queryVector,
    5,
    """{"condition": {"type": "eq", "field": "category", "value": "tech"}}"""
)

VelesSemanticMemory

Agent memory for on-device AI. Stores knowledge facts as vectors with similarity search.

MobileGraphStore

In-memory graph store for mobile knowledge graphs.

Distance Metrics

Storage Modes (IoT/Edge)

// iOS - Create collection with SQ8 compression (4x memory reduction)
try db.createCollectionWithStorage(
    name: "embeddings",
    dimension: 384,
    metric: .cosine,
    storageMode: .sq8  // 4x less memory, ~1% recall loss
)

// Android - Binary quantization for IoT devices (32x compression)
db.createCollectionWithStorage(
    "embeddings", 384u, DistanceMetric.COSINE, StorageMode.BINARY
)

Fusion Strategies

Used with multiQuerySearch() for combining results from multiple query vectors.

Data Types

Performance Tips

1. Use SQ8 or Binary Quantization for memory-constrained devices
2. Batch inserts with upsertBatch() for 10x faster bulk loading
3. Use search() on background thread to avoid blocking UI
4. Pre-allocate embedding arrays to reduce allocations

Memory Footprint

License

Licensed under the VelesDB Core License 1.0 (source-available). The compiled mobile bindings embed the VelesDB engine and are governed by the Core License.