aegis-document

Document store engine for the Aegis Database Platform.

Overview

aegis-document provides a flexible document storage system with schema-optional JSON storage, full-text search, JSONPath queries, and schema validation. It's designed for semi-structured data that doesn't fit traditional relational models.

Features

• Schema-Optional - Store any JSON document
• Collections - Logical grouping of documents
• Full-Text Search - Tokenized text search with ranking
• JSONPath Queries - Query nested document fields
• Schema Validation - Optional JSON Schema enforcement
• Secondary Indexes - Index any field for fast lookups

Architecture

┌─────────────────────────────────────────────────┐
│              Document Engine                     │
├─────────────────────────────────────────────────┤
│               Query Processor                    │
│  ┌──────────┬──────────────┬─────────────────┐  │
│  │ JSONPath │  Full-Text   │  Aggregation    │  │
│  │  Parser  │   Search     │    Engine       │  │
│  └──────────┴──────────────┴─────────────────┘  │
├─────────────────────────────────────────────────┤
│                Index Manager                     │
│  ┌──────────┬──────────────┬─────────────────┐  │
│  │  B-Tree  │   Inverted   │   Composite     │  │
│  │  Index   │    Index     │    Index        │  │
│  └──────────┴──────────────┴─────────────────┘  │
├─────────────────────────────────────────────────┤
│             Collection Manager                   │
│          (Schema Validation Layer)               │
└─────────────────────────────────────────────────┘

Modules

Usage

[dependencies]
aegis-document = { path = "../aegis-document" }

Collections

use aegis_document::{DocumentEngine, Collection, CollectionOptions};

let engine = DocumentEngine::new(storage)?;

// Create a collection
engine.create_collection("users", CollectionOptions {
    schema: None,  // Schema-optional
    indexes: vec![
        Index::new("email").unique(true),
        Index::new("name"),
    ],
})?;

// Create with schema validation
let schema = json!({
    "type": "object",
    "required": ["name", "email"],
    "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" },
        "age": { "type": "integer", "minimum": 0 }
    }
});

engine.create_collection("validated_users", CollectionOptions {
    schema: Some(schema),
    indexes: vec![],
})?;

CRUD Operations

// Insert
let doc_id = engine.insert("users", json!({
    "name": "Alice",
    "email": "alice@example.com",
    "tags": ["admin", "developer"],
    "profile": {
        "bio": "Software engineer",
        "location": "San Francisco"
    }
}))?;

// Find by ID
let doc = engine.find_by_id("users", &doc_id)?;

// Update
engine.update("users", &doc_id, json!({
    "$set": { "profile.location": "New York" },
    "$push": { "tags": "speaker" }
}))?;

// Delete
engine.delete("users", &doc_id)?;

Querying

use aegis_document::query::{Query, Filter, Sort};

// Simple filter
let results = engine.find("users", Query {
    filter: Filter::eq("email", "alice@example.com"),
    ..Default::default()
})?;

// Complex query
let results = engine.find("users", Query {
    filter: Filter::and(vec![
        Filter::gt("age", 21),
        Filter::in_array("tags", vec!["developer", "admin"]),
        Filter::regex("email", r".*@company\.com$"),
    ]),
    sort: Sort::desc("created_at"),
    skip: 0,
    limit: 100,
    projection: vec!["name", "email"],
})?;

// Nested field query (JSONPath)
let results = engine.find("users", Query {
    filter: Filter::eq("profile.location", "San Francisco"),
    ..Default::default()
})?;

Full-Text Search

use aegis_document::search::{TextSearch, SearchOptions};

// Create text index
engine.create_index("articles", Index::text(vec!["title", "content"]))?;

// Search
let results = engine.search("articles", TextSearch {
    query: "rust database performance",
    options: SearchOptions {
        fuzzy: true,
        highlight: true,
        ..Default::default()
    },
})?;

for result in results {
    println!("Score: {}, Title: {}", result.score, result.doc["title"]);
    println!("Highlights: {:?}", result.highlights);
}

Aggregation

use aegis_document::aggregation::{Pipeline, Stage};

let results = engine.aggregate("orders", Pipeline::new()
    .match_stage(Filter::gte("created_at", "2024-01-01"))
    .group(json!({
        "_id": "$customer_id",
        "total": { "$sum": "$amount" },
        "count": { "$count": {} }
    }))
    .sort(Sort::desc("total"))
    .limit(10)
)?;

Update Operators

Configuration

[document]
default_collection_options = { max_documents = 1000000 }
text_search_language = "english"

[document.indexes]
auto_create = true
background_build = true

Tests

cargo test -p aegis-document

Test count: 634 tests (workspace total)

License

Apache-2.0