Struct Database 

pub struct Database { /* private fields */ }

Main database handle

Implementations

impl Database

pub fn add_collection( &self, name: &str, path: &str, pattern: &str, provider_type: &str, provider_config: Option<&str>, ) -> Result<()>

Add a new collection

pub fn remove_collection(&self, name: &str) -> Result<bool>

Remove a collection and its documents

pub fn rename_collection(&self, old_name: &str, new_name: &str) -> Result<bool>

Rename a collection

pub fn list_collections(&self) -> Result<Vec<CollectionInfo>>

List all collections with document counts

pub fn get_collection(&self, name: &str) -> Result<Option<CollectionInfo>>

Get collection by name

pub fn touch_collection(&self, name: &str) -> Result<()>

Update collection’s updated_at timestamp

pub async fn reindex_collection(&self, name: &str) -> Result<usize>

Reindex a collection using the provider system

pub async fn generate_or_fetch_metadata( &self, content_hash: &str, content: &str, context: MetadataContext, generator: Option<&dyn MetadataGenerator>, ) -> Result<Option<DocumentMetadata>>

Generate or fetch metadata from cache

pub fn get_llm_cache_public(&self, key: &str) -> Result<Option<String>>

Get metadata from LLM cache (public API)

pub async fn reindex_collection_with_metadata( &self, name: &str, generator: Option<&dyn MetadataGenerator>, ) -> Result<usize>

Reindex all documents in a collection with optional metadata generation

impl Database

pub fn insert_content(&self, hash: &str, content: &str) -> Result<bool>

Insert content if not exists (content-addressable)

pub fn get_content(&self, hash: &str) -> Result<Option<String>>

Get content by hash

pub fn cleanup_orphaned_content(&self) -> Result<usize>

Delete orphaned content (not referenced by any active document)

impl Database

pub fn add_context(&self, path: &str, context: &str) -> Result<()>

Add context for a path

pub fn list_contexts(&self) -> Result<Vec<ContextInfo>>

List all contexts

pub fn check_missing_contexts(&self) -> Result<Vec<String>>

Check for collections missing context

pub fn remove_context(&self, path: &str) -> Result<bool>

Remove context for a path

pub fn resolve_context(&self, virtual_path: &str) -> Result<Option<String>>

Get context for a document path (hierarchical resolution)

impl Database

pub fn insert_doc(&self, doc: &DocumentInsert<'_>) -> Result<i64>

Insert new document using struct parameters

pub fn insert_document( &self, collection: &str, path: &str, title: &str, hash: &str, created_at: &str, modified_at: &str, source_type: &str, source_uri: Option<&str>, ) -> Result<i64>

Insert new document (legacy method)

pub fn update_document( &self, id: i64, title: &str, hash: &str, modified_at: &str, ) -> Result<()>

Update existing document (new content hash)

pub fn update_document_title( &self, id: i64, title: &str, modified_at: &str, ) -> Result<()>

Update document title only

pub fn deactivate_document(&self, collection: &str, path: &str) -> Result<bool>

Soft-delete document (set active = 0)

pub fn find_active_document( &self, collection: &str, path: &str, ) -> Result<Option<Document>>

Find active document by collection and path

pub fn get_active_document_paths(&self, collection: &str) -> Result<Vec<String>>

Get all active document paths in collection

pub fn find_by_docid(&self, docid: &str) -> Result<Option<DocumentResult>>

Find document by docid (hash prefix)

pub fn delete_inactive_documents(&self) -> Result<usize>

Hard delete inactive documents

pub fn lookup_document( &self, query: &str, collections: &HashMap<String, PathBuf>, ) -> Result<Option<DocumentResult>>

Multi-lookup with fallback chain

pub fn fuzzy_find_documents( &self, query: &str, limit: usize, ) -> Result<Vec<DocumentResult>>

Fuzzy matching using simple contains + length

pub fn get_document(&self, query: &str) -> Result<String>

Get document content by query (docid, virtual path, etc)

pub fn list_documents_by_prefix( &self, prefix: &str, ) -> Result<Vec<DocumentListItem>>

List documents by prefix

pub fn get_documents_by_pattern( &self, pattern: &str, ) -> Result<Vec<DocumentContent>>

Get multiple documents by pattern

impl Database

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Open database at path, creating if necessary

pub fn open_in_memory() -> Result<Self>

Open in-memory database (for testing)

pub fn initialize(&self) -> Result<()>

Initialize database schema

pub fn schema_version(&self) -> Result<Option<i32>>

Get current schema version

pub fn migrate(&self) -> Result<()>

Run migrations to upgrade schema to current version

impl Database

pub fn get_stats(&self) -> Result<DatabaseStats>

Get database statistics

pub fn vacuum(&self) -> Result<()>

Vacuum the database

pub fn cleanup_orphaned_vectors(&self) -> Result<usize>

Cleanup orphaned vectors

impl Database

pub fn add_metadata(&self, docid: &str, metadata: &UserMetadata) -> Result<()>

Add or update user metadata for a document

Arguments

• docid - Document ID (short hash like “abc123” or full “#abc123”)
• metadata - User metadata to add/update

Example

use agentroot_core::{Database, MetadataBuilder};

let db = Database::open("index.sqlite")?;
let metadata = MetadataBuilder::new()
    .text("author", "John Doe")
    .tags("labels", vec!["rust", "tutorial"])
    .build();

db.add_metadata("#abc123", &metadata)?;

pub fn get_metadata(&self, docid: &str) -> Result<Option<UserMetadata>>

Get user metadata for a document

pub fn remove_metadata_fields( &self, docid: &str, fields: &[String], ) -> Result<()>

Remove specific metadata fields from a document

pub fn clear_metadata(&self, docid: &str) -> Result<()>

Clear all user metadata from a document

pub fn find_by_metadata( &self, filter: &MetadataFilter, limit: usize, ) -> Result<Vec<String>>

Find documents matching metadata filter

pub fn list_with_metadata( &self, limit: usize, ) -> Result<Vec<(String, UserMetadata)>>

List all documents with user metadata

impl Database

pub fn ensure_vec_table(&self, _dimensions: usize) -> Result<()>

Ensure vector storage table exists

pub fn insert_embedding( &self, hash: &str, seq: u32, pos: usize, model: &str, embedding: &[f32], ) -> Result<()>

Insert embedding for a document chunk

pub fn has_vector_index(&self) -> bool

Check if vector index exists and has data

pub fn get_all_embeddings(&self) -> Result<Vec<(String, Vec<f32>)>>

Get all embeddings for similarity search

pub fn get_embeddings_for_collection( &self, collection: &str, ) -> Result<Vec<(String, Vec<f32>)>>

Get embeddings for specific hashes (for filtered search)

pub fn get_hashes_needing_embedding(&self) -> Result<Vec<(String, String)>>

Get hashes that need embedding

pub fn count_hashes_needing_embedding(&self) -> Result<usize>

Count hashes needing embedding

pub fn delete_embeddings(&self, hash: &str) -> Result<usize>

Delete embeddings for a hash

pub fn get_all_hashes_for_embedding(&self) -> Result<Vec<(String, String)>>

Get all hashes for embedding (for force re-embedding)

pub fn check_model_compatibility( &self, model: &str, expected_dims: usize, ) -> Result<bool>

Check if model dimensions are compatible with expected dimensions

pub fn get_cached_embedding( &self, chunk_hash: &str, model: &str, expected_dims: usize, ) -> Result<CacheLookupResult>

Look up a cached embedding by chunk hash (performs dimension check)

pub fn get_cached_embedding_fast( &self, chunk_hash: &str, model: &str, ) -> Result<CacheLookupResult>

Look up a cached embedding by chunk hash (skips dimension check - caller must verify compatibility)

pub fn insert_chunk_embedding( &self, doc_hash: &str, seq: u32, pos: usize, chunk_hash: &str, model: &str, embedding: &[f32], ) -> Result<()>

Insert a chunk embedding with cache support

pub fn get_chunk_hashes_for_doc( &self, doc_hash: &str, ) -> Result<Vec<(u32, String)>>

Get chunk hashes for a document

pub fn cleanup_orphaned_chunk_embeddings(&self) -> Result<usize>

Clean up orphaned chunk embeddings (not referenced by any document)

pub fn register_model(&self, model: &str, dimensions: usize) -> Result<()>

Register model with its dimensions

pub fn get_model_dimensions(&self, model: &str) -> Result<Option<usize>>

Get stored model dimensions

pub fn count_cached_embeddings(&self, model: &str) -> Result<usize>

Count cached chunk embeddings

impl Database

pub fn default_path() -> PathBuf

Get the default database path

impl Database

pub fn get_all_content(&self) -> Result<Vec<(String, String)>>

Get all content hashes and content

pub fn get_all_content_with_paths( &self, ) -> Result<Vec<(String, String, Option<String>)>>

Get all content with file paths

pub fn get_content_needing_embedding_with_paths( &self, ) -> Result<Vec<(String, String, Option<String>)>>

Get content needing embedding with file paths

pub fn get_document_title_by_hash(&self, hash: &str) -> Result<Option<String>>

Get document title by hash

impl Database

pub fn search_fts( &self, query: &str, options: &SearchOptions, ) -> Result<Vec<SearchResult>>

Perform BM25 full-text search

impl Database

pub fn search_vec_sync( &self, _query: &str, options: &SearchOptions, ) -> Result<Vec<SearchResult>>

Synchronous vector search (placeholder for CLI - needs runtime)

pub fn search_hybrid_sync( &self, query: &str, options: &SearchOptions, ) -> Result<Vec<SearchResult>>

Synchronous hybrid search (placeholder for CLI - needs runtime)

impl Database

pub async fn search_vec( &self, query: &str, embedder: &dyn Embedder, options: &SearchOptions, ) -> Result<Vec<SearchResult>>

Perform vector similarity search