ruvector/docs/guide/BASIC_TUTORIAL.md

Basic Tutorial

This tutorial walks through the core features of Ruvector with practical examples.

Prerequisites

• Completed Installation
• Basic understanding of vectors/embeddings
• Familiarity with Rust or Node.js

Tutorial Overview

1. Create a Vector Database
2. Insert Vectors
3. Search for Similar Vectors
4. Add Metadata
5. Batch Operations
6. Configure HNSW
7. Enable Quantization
8. Persistence

1. Create a Vector Database

Rust

use ruvector_core::{VectorDB, DbOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut options = DbOptions::default();
    options.dimensions = 128;  // Vector dimensionality
    options.storage_path = "./my_vectors.db".to_string();

    let db = VectorDB::new(options)?;
    println!("Created database with 128 dimensions");

    Ok(())
}

Node.js

const { VectorDB } = require('ruvector');

const db = new VectorDB({
    dimensions: 128,
    storagePath: './my_vectors.db'
});

console.log('Created database with 128 dimensions');

2. Insert Vectors

Rust

use ruvector_core::{VectorDB, VectorEntry};

fn insert_examples(db: &VectorDB) -> Result<(), Box<dyn std::error::Error>> {
    // Insert a single vector
    let entry = VectorEntry {
        id: None,  // Auto-generate ID
        vector: vec![0.1; 128],
        metadata: None,
    };

    let id = db.insert(entry)?;
    println!("Inserted vector with ID: {}", id);

    // Insert with custom ID
    let entry = VectorEntry {
        id: Some("doc_001".to_string()),
        vector: vec![0.2; 128],
        metadata: None,
    };

    db.insert(entry)?;
    println!("Inserted vector with custom ID: doc_001");

    Ok(())
}

Node.js

// Insert a single vector
const id = await db.insert({
    vector: new Float32Array(128).fill(0.1)
});
console.log('Inserted vector with ID:', id);

// Insert with custom ID
await db.insert({
    id: 'doc_001',
    vector: new Float32Array(128).fill(0.2)
});
console.log('Inserted vector with custom ID: doc_001');

3. Search for Similar Vectors

Rust

use ruvector_core::SearchQuery;

fn search_examples(db: &VectorDB) -> Result<(), Box<dyn std::error::Error>> {
    let query = SearchQuery {
        vector: vec![0.15; 128],
        k: 10,  // Return top 10 results
        filter: None,
        include_vectors: false,
    };

    let results = db.search(&query)?;

    for (i, result) in results.iter().enumerate() {
        println!(
            "{}. ID: {}, Distance: {:.4}",
            i + 1,
            result.id,
            result.distance
        );
    }

    Ok(())
}

Node.js

const results = await db.search({
    vector: new Float32Array(128).fill(0.15),
    k: 10
});

results.forEach((result, i) => {
    console.log(`${i + 1}. ID: ${result.id}, Distance: ${result.distance.toFixed(4)}`);
});

4. Add Metadata

Metadata allows you to store additional information with each vector.

Rust

use serde_json::json;
use std::collections::HashMap;

fn insert_with_metadata(db: &VectorDB) -> Result<(), Box<dyn std::error::Error>> {
    let mut metadata = HashMap::new();
    metadata.insert("title".to_string(), json!("Example Document"));
    metadata.insert("author".to_string(), json!("Alice"));
    metadata.insert("tags".to_string(), json!(["ml", "ai", "embeddings"]));
    metadata.insert("timestamp".to_string(), json!(1234567890));

    let entry = VectorEntry {
        id: Some("doc_002".to_string()),
        vector: vec![0.3; 128],
        metadata: Some(metadata),
    };

    db.insert(entry)?;
    println!("Inserted vector with metadata");

    Ok(())
}

Node.js

await db.insert({
    id: 'doc_002',
    vector: new Float32Array(128).fill(0.3),
    metadata: {
        title: 'Example Document',
        author: 'Alice',
        tags: ['ml', 'ai', 'embeddings'],
        timestamp: 1234567890
    }
});

console.log('Inserted vector with metadata');

Retrieve metadata in search

const results = await db.search({
    vector: new Float32Array(128).fill(0.3),
    k: 5,
    includeMetadata: true
});

results.forEach(result => {
    console.log(`ID: ${result.id}`);
    console.log(`Title: ${result.metadata.title}`);
    console.log(`Tags: ${result.metadata.tags.join(', ')}`);
    console.log('---');
});

5. Batch Operations

Batch operations are significantly faster than individual operations.

Rust

fn batch_insert(db: &VectorDB) -> Result<(), Box<dyn std::error::Error>> {
    use rand::Rng;
    let mut rng = rand::thread_rng();

    // Create 1000 random vectors
    let entries: Vec<VectorEntry> = (0..1000)
        .map(|i| {
            let vector: Vec<f32> = (0..128)
                .map(|_| rng.gen::<f32>())
                .collect();

            VectorEntry {
                id: Some(format!("vec_{:04}", i)),
                vector,
                metadata: None,
            }
        })
        .collect();

    // Batch insert
    let start = std::time::Instant::now();
    let ids = db.insert_batch(entries)?;
    let duration = start.elapsed();

    println!("Inserted {} vectors in {:?}", ids.len(), duration);
    println!("Throughput: {:.0} vectors/sec", ids.len() as f64 / duration.as_secs_f64());

    Ok(())
}

Node.js

// Create 1000 random vectors
const entries = Array.from({ length: 1000 }, (_, i) => ({
    id: `vec_${i.toString().padStart(4, '0')}`,
    vector: new Float32Array(128).map(() => Math.random())
}));

// Batch insert
const start = Date.now();
const ids = await db.insertBatch(entries);
const duration = Date.now() - start;

console.log(`Inserted ${ids.length} vectors in ${duration}ms`);
console.log(`Throughput: ${Math.floor(ids.length / (duration / 1000))} vectors/sec`);

6. Configure HNSW

Tune HNSW parameters for your use case.

Rust

use ruvector_core::{HnswConfig, DistanceMetric};

fn create_tuned_db() -> Result<VectorDB, Box<dyn std::error::Error>> {
    let mut options = DbOptions::default();
    options.dimensions = 128;
    options.storage_path = "./tuned_db.db".to_string();

    // HNSW configuration
    options.hnsw = HnswConfig {
        m: 32,                    // Connections per node (16-64)
        ef_construction: 200,     // Build quality (100-400)
        ef_search: 100,           // Search quality (50-500)
        max_elements: 10_000_000, // Maximum vectors
    };

    // Distance metric
    options.distance_metric = DistanceMetric::Cosine;

    let db = VectorDB::new(options)?;
    println!("Created database with tuned HNSW parameters");

    Ok(db)
}

Node.js

const db = new VectorDB({
    dimensions: 128,
    storagePath: './tuned_db.db',
    hnsw: {
        m: 32,              // Connections per node
        efConstruction: 200, // Build quality
        efSearch: 100,      // Search quality
        maxElements: 10_000_000
    },
    distanceMetric: 'cosine'
});

console.log('Created database with tuned HNSW parameters');

Parameter trade-offs

Parameter	Low	Medium	High
m	16 (low memory)	32 (balanced)	64 (high recall)
ef_construction	100 (fast build)	200 (balanced)	400 (high quality)
ef_search	50 (fast search)	100 (balanced)	500 (high recall)

7. Enable Quantization

Reduce memory usage with quantization.

Rust

use ruvector_core::QuantizationConfig;

fn create_quantized_db() -> Result<VectorDB, Box<dyn std::error::Error>> {
    let mut options = DbOptions::default();
    options.dimensions = 128;
    options.storage_path = "./quantized_db.db".to_string();

    // Scalar quantization (4x compression)
    options.quantization = QuantizationConfig::Scalar;

    // Product quantization (8-16x compression)
    // options.quantization = QuantizationConfig::Product {
    //     subspaces: 16,
    //     k: 256,
    // };

    let db = VectorDB::new(options)?;
    println!("Created database with scalar quantization");

    Ok(db)
}

Node.js

const db = new VectorDB({
    dimensions: 128,
    storagePath: './quantized_db.db',
    quantization: {
        type: 'scalar'  // or 'product', 'binary'
    }
});

console.log('Created database with scalar quantization');

Quantization comparison

Type	Compression	Recall	Use Case
None	1x	100%	Small datasets, high accuracy
Scalar	4x	97-99%	General purpose
Product	8-16x	90-95%	Large datasets
Binary	32x	80-90%	Filtering stage

8. Persistence

Ruvector automatically persists data to disk.

Load existing database

// Rust
let db = VectorDB::open("./my_vectors.db")?;

// Node.js
const db = new VectorDB({ storagePath: './my_vectors.db' });

Export/Import

// Export to JSON
db.export_json("./export.json")?;

// Import from JSON
db.import_json("./export.json")?;

Backup

# Simple file copy (database is in a consistent state)
cp -r ./my_vectors.db ./backup/

# Or use ruvector CLI
ruvector export --db ./my_vectors.db --output ./backup.json
ruvector import --db ./new_db.db --input ./backup.json

Complete Example

Here's a complete program combining everything:

use ruvector_core::{
    VectorDB, VectorEntry, SearchQuery, DbOptions, HnswConfig,
    DistanceMetric, QuantizationConfig,
};
use rand::Rng;
use serde_json::json;
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create database with tuned settings
    let mut options = DbOptions::default();
    options.dimensions = 128;
    options.storage_path = "./tutorial_db.db".to_string();
    options.hnsw = HnswConfig {
        m: 32,
        ef_construction: 200,
        ef_search: 100,
        max_elements: 1_000_000,
    };
    options.distance_metric = DistanceMetric::Cosine;
    options.quantization = QuantizationConfig::Scalar;

    let db = VectorDB::new(options)?;
    println!("✓ Created database");

    // 2. Insert vectors with metadata
    let mut rng = rand::thread_rng();
    let entries: Vec<VectorEntry> = (0..10000)
        .map(|i| {
            let vector: Vec<f32> = (0..128)
                .map(|_| rng.gen::<f32>())
                .collect();

            let mut metadata = HashMap::new();
            metadata.insert("id".to_string(), json!(i));
            metadata.insert("category".to_string(), json!(i % 10));

            VectorEntry {
                id: Some(format!("doc_{:05}", i)),
                vector,
                metadata: Some(metadata),
            }
        })
        .collect();

    let start = std::time::Instant::now();
    db.insert_batch(entries)?;
    println!("✓ Inserted 10,000 vectors in {:?}", start.elapsed());

    // 3. Search
    let query_vector: Vec<f32> = (0..128).map(|_| rng.gen::<f32>()).collect();
    let query = SearchQuery {
        vector: query_vector,
        k: 10,
        filter: None,
        include_vectors: false,
    };

    let start = std::time::Instant::now();
    let results = db.search(&query)?;
    let search_time = start.elapsed();

    println!("✓ Search completed in {:?}", search_time);
    println!("\nTop 10 Results:");
    for (i, result) in results.iter().enumerate() {
        println!("  {}. ID: {}, Distance: {:.4}", i + 1, result.id, result.distance);
    }

    Ok(())
}

Next Steps

• Advanced Features Guide - Hybrid search, filtering, MMR
• AgenticDB Tutorial - Reflexion memory, skills, causal memory
• Performance Tuning - Optimization guide
• API Reference - Complete API documentation

Common Patterns

Pattern 1: Document Embedding Storage

// Store document embeddings with full metadata
let doc = VectorEntry {
    id: Some(format!("doc_{}", uuid::Uuid::new_v4())),
    vector: embedding,  // From your embedding model
    metadata: Some(HashMap::from([
        ("title".into(), json!(title)),
        ("content".into(), json!(content_preview)),
        ("url".into(), json!(url)),
        ("timestamp".into(), json!(chrono::Utc::now().timestamp())),
    ])),
};
db.insert(doc)?;

Pattern 2: Semantic Search

// Embed user query
let query_embedding = embed_text(&user_query);

// Search with filters
let results = db.search(&SearchQuery {
    vector: query_embedding,
    k: 20,
    filter: Some(json!({
        "timestamp": { "$gte": one_week_ago }
    })),
    include_vectors: false,
})?;

// Return relevant documents
for result in results {
    println!("{}: {}", result.id, result.metadata["title"]);
}

Pattern 3: Recommendation System

// Get user's liked items
let user_vectors = get_user_liked_vectors(&db, user_id)?;

// Average embeddings
let avg_vector = average_vectors(&user_vectors);

// Find similar items
let recommendations = db.search(&SearchQuery {
    vector: avg_vector,
    k: 10,
    filter: Some(json!({
        "id": { "$nin": user_already_seen }
    })),
    include_vectors: false,
})?;

Troubleshooting

Low Performance

• Enable SIMD: RUSTFLAGS="-C target-cpu=native" cargo build --release
• Use batch operations instead of individual inserts
• Tune HNSW parameters (lower ef_search for speed)

High Memory Usage

• Enable quantization
• Use memory-mapped vectors for large datasets
• Reduce max_elements or HNSW m parameter

Low Recall

• Increase ef_construction and ef_search
• Disable or reduce quantization
• Use Cosine distance for normalized vectors