Struct UnifiedStore 

pub struct UnifiedStore { /* private fields */ }

Unified storage for tables, graphs, and vectors

UnifiedStore provides a single coherent interface for all data types:

• Tables: Row-based data with columns
• Graphs: Nodes and edges with labels
• Vectors: Embeddings for similarity search

Features

• Multi-collection management
• Cross-collection queries
• Cross-reference tracking between entities
• Automatic ID generation
• Segment-based storage with growing/sealed lifecycle

Example

use reddb::storage::{Entity, Store};

let store = Store::new();

// Create a collection
store.create_collection("hosts")?;

// Insert an entity
let entity = Entity::table_row(1, "hosts", 1, vec![]);
let id = store.insert("hosts", entity)?;

// Query
let found = store.get("hosts", id);

Implementations

impl UnifiedStore

pub fn lookup_graph_nodes_by_label(&self, label: &str) -> Vec<EntityId>

Look up entity IDs for a graph node label across all collections.

pub fn create_collection( &self, name: impl Into<String>, ) -> Result<(), StoreError>

pub fn get_or_create_collection( &self, name: impl Into<String>, ) -> Arc<SegmentManager>

Get or create a collection

pub fn get_collection(&self, name: &str) -> Option<Arc<SegmentManager>>

Get a collection

pub fn context_index(&self) -> &ContextIndex

Get the context index for cross-structure search.

pub fn set_config_tree(&self, prefix: &str, json: &Value) -> usize

Set multiple config KV pairs at once from a JSON tree. Keys are flattened with dot-notation: {"a":{"b":1}} → a.b = 1.

pub fn get_config(&self, key: &str) -> Option<Value>

Read a single config value from red_config by dot-notation key.

pub fn list_collections(&self) -> Vec<String>

List all collections

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

Drop a collection

pub fn insert( &self, collection: &str, entity: UnifiedEntity, ) -> Result<EntityId, StoreError>

Insert an entity into a collection

pub fn bulk_insert( &self, collection: &str, entities: Vec<UnifiedEntity>, ) -> Result<Vec<EntityId>, StoreError>

Turbo bulk insert — optimized fast path.

Single lock for the entire batch. Skips bloom filter, memtable, context index, and cross-ref indexing. B-tree writes are batched.

pub fn insert_auto( &self, collection: &str, entity: UnifiedEntity, ) -> Result<EntityId, StoreError>

Insert an entity, creating collection if needed

pub fn get(&self, collection: &str, id: EntityId) -> Option<UnifiedEntity>

Get an entity from a collection

Prefers the live SegmentManager view so reads after update/delete observe the current in-memory state even when the paged B-tree image has not been refreshed yet. Falls back to the B-tree image for recovery-oriented reads.

pub fn get_batch( &self, collection: &str, ids: &[EntityId], ) -> Vec<Option<UnifiedEntity>>

Batch-fetch multiple entities from the same collection in minimal lock acquisitions.

Preferred over N individual get() calls in indexed-scan loops (sorted index, bitmap, hash). Reduces lock acquisitions from N×3 to 2-3 total. Preserves input order: result[i] corresponds to ids[i].

pub fn get_any(&self, id: EntityId) -> Option<(String, UnifiedEntity)>

Get an entity from any collection

pub fn entity_cache_hit_rate(&self) -> Option<f64>

Hit rate of the store’s entity cache (get_any lookups).

Returns None until the cache has served at least one lookup. Exposed for observability — e.g. dashboards distinguishing graph workloads (high hit rate) from OLTP DML (≈ 0 % hit rate).

pub fn entity_cache_stats(&self) -> EntityCacheStats

Snapshot of cache hit / miss / eviction counters and current size.

pub fn delete(&self, collection: &str, id: EntityId) -> Result<bool, StoreError>

Delete an entity

pub fn delete_batch( &self, collection: &str, ids: &[EntityId], ) -> Result<Vec<EntityId>, StoreError>

pub fn set_metadata( &self, collection: &str, id: EntityId, metadata: Metadata, ) -> Result<(), StoreError>

Set metadata for an entity

pub fn get_metadata(&self, collection: &str, id: EntityId) -> Option<Metadata>

Get metadata for an entity

pub fn add_cross_ref( &self, source_collection: &str, source_id: EntityId, target_collection: &str, target_id: EntityId, ref_type: RefType, weight: f32, ) -> Result<(), StoreError>

Add a cross-reference between entities

pub fn get_refs_from(&self, id: EntityId) -> Vec<(EntityId, RefType, String)>

Get cross-references from an entity

pub fn get_refs_to(&self, id: EntityId) -> Vec<(EntityId, RefType, String)>

Get cross-references to an entity

pub fn expand_refs( &self, id: EntityId, depth: u32, ref_types: Option<&[RefType]>, ) -> Vec<(UnifiedEntity, u32, RefType)>

Expand cross-references to get related entities

pub fn unindex_cross_refs_fast_path_hits(&self) -> u64

Test/observability hook: number of times unindex_cross_refs_batch took the read-only fast path. Used to pin the early-exit in tests and as a cheap signal in delete-heavy benchmarks.

pub fn query_all<F>(&self, filter: F) -> Vec<(String, UnifiedEntity)>

where F: Fn(&UnifiedEntity) -> bool + Clone + Send + Sync,

Query across all collections with a filter

pub fn filter_metadata_all( &self, filters: &[(String, MetadataFilter)], ) -> Vec<(String, EntityId)>

Filter by metadata across all collections

pub fn stats(&self) -> StoreStats

Get statistics

pub fn run_maintenance(&self) -> Result<(), StoreError>

Run maintenance on all collections

impl UnifiedStore

pub fn new() -> UnifiedStore

pub fn format_version(&self) -> u32

Get the current storage format version

pub fn next_entity_id(&self) -> EntityId

Allocate a global entity ID

pub fn reserve_entity_ids(&self, n: u64) -> Range<u64>

Reserve n contiguous global entity IDs with one fetch_add. Caller assigns id = EntityId::new(start + i) per entity.

pub fn load_from_file(path: &Path) -> Result<UnifiedStore, Box<dyn Error>>

Load store from binary file

Binary format:

[magic: 4 bytes "RDST"]
[version: u32]
[collection_count: varu32]
[collections...]
[cross_ref_count: varu32]
[cross_refs...]

pub fn save_to_file(&self, path: &Path) -> Result<(), Box<dyn Error>>

Save store to binary file

Uses compact binary encoding with varint for efficient storage. No JSON - pure binary with pages and indices.

impl UnifiedStore

pub fn update_physical_file_header( &self, physical: PhysicalFileHeader, ) -> Result<(), StoreError>

pub fn physical_file_header(&self) -> Option<PhysicalFileHeader>

Read the minimal physical header mirrored into page 0 for paged databases.

pub fn write_native_collection_roots( &self, roots: &BTreeMap<String, u64>, existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist native collection roots into a dedicated page in the paged file.

pub fn read_native_collection_roots( &self, page_id: u32, ) -> Result<BTreeMap<String, u64>, StoreError>

Read native collection roots from a dedicated page in the paged file.

pub fn write_native_manifest_summary( &self, sequence: u64, events: &[ManifestEvent], existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist a compact native manifest summary into a dedicated page in the paged file.

pub fn read_native_manifest_summary( &self, page_id: u32, ) -> Result<NativeManifestSummary, StoreError>

Read a compact native manifest summary from a dedicated page in the paged file.

pub fn write_native_registry_summary( &self, summary: &NativeRegistrySummary, existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist a compact native operational registry summary into a dedicated page.

impl UnifiedStore

pub fn read_native_registry_summary( &self, page_id: u32, ) -> Result<NativeRegistrySummary, StoreError>

pub fn write_native_recovery_summary( &self, summary: &NativeRecoverySummary, existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist a compact native snapshot/export summary into a dedicated page.

pub fn read_native_recovery_summary( &self, page_id: u32, ) -> Result<NativeRecoverySummary, StoreError>

Read a compact native snapshot/export summary from a dedicated page.

pub fn write_native_catalog_summary( &self, summary: &NativeCatalogSummary, existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist a compact native catalog summary into a dedicated page.

pub fn read_native_catalog_summary( &self, page_id: u32, ) -> Result<NativeCatalogSummary, StoreError>

Read a compact native catalog summary from a dedicated page.

pub fn write_native_metadata_state_summary( &self, summary: &NativeMetadataStateSummary, existing_page: Option<u32>, ) -> Result<(u32, u64), StoreError>

Persist a compact native metadata state summary into a dedicated page.

pub fn read_native_metadata_state_summary( &self, page_id: u32, ) -> Result<NativeMetadataStateSummary, StoreError>

Read a compact native metadata state summary from a dedicated page.

impl UnifiedStore

pub fn read_native_physical_state( &self, ) -> Result<NativePhysicalState, StoreError>

pub fn read_native_blob_chain( &self, root_page: u32, ) -> Result<Vec<u8>, StoreError>

pub fn write_native_vector_artifact_store( &self, artifacts: &[(String, String, Vec<u8>)], existing_page: Option<u32>, ) -> Result<(u32, u64, Vec<NativeVectorArtifactPageSummary>), StoreError>

pub fn read_native_vector_artifact_store( &self, page_id: u32, ) -> Result<Vec<NativeVectorArtifactPageSummary>, StoreError>

pub fn read_native_vector_artifact_blob( &self, page_id: u32, collection: &str, artifact_kind: Option<&str>, ) -> Result<Option<(NativeVectorArtifactPageSummary, Vec<u8>)>, StoreError>

impl UnifiedStore

pub fn pager(&self) -> Option<&Arc<Pager>>

Get a reference to the underlying pager (if in paged mode).

pub fn config(&self) -> &UnifiedStoreConfig

Borrow the immutable store configuration. Runtime hooks (e.g. the auto_index_id first-insert hook in MutationEngine) read knobs off this struct without going through the legacy global config tree.

pub fn with_config(config: UnifiedStoreConfig) -> UnifiedStore

pub fn open(path: impl AsRef<Path>) -> Result<UnifiedStore, StoreError>

Open or create a page-based database

This uses the page engine for ACID durability with B-tree indices. The database file uses 4KB pages with checksums and efficient caching.

Arguments

• path - Path to the database file (e.g., “data.rdb”)

Example

let store = UnifiedStore::open("security.rdb")?;
store.create_collection("hosts")?;
// ... operations ...
store.persist()?; // Flush to disk

pub fn open_with_config( path: impl AsRef<Path>, config: UnifiedStoreConfig, ) -> Result<UnifiedStore, StoreError>

pub fn persist(&self) -> Result<(), StoreError>

Persist all data to page-based storage

Writes all entities to B-tree pages and flushes to disk. This provides ACID durability guarantees.

pub fn is_paged(&self) -> bool

Check if the store is using page-based persistence

pub fn db_path(&self) -> Option<&Path>

Get the database file path (if using paged mode)

Trait Implementations

impl Default for UnifiedStore

fn default() -> UnifiedStore

Returns the “default value” for a type.