Struct Store 

pub struct Store { /* 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 refresh_collection( &self, name: &str, entities: Vec<UnifiedEntity>, ) -> Result<Vec<Vec<u8>>, StoreError>

Atomic full-collection replace — issue #595 slice 9c.

Builds a fresh SegmentManager populated with entities, atomically swaps it into the collections map, rebuilds the paged B-tree from the same records, and emits a single RefreshCollection WAL action.

Concurrent readers that resolved an Arc<SegmentManager> for this collection before the swap continue reading the prior contents; readers after the swap see the new contents. The transition is single-pointer so partial state is unobservable.

A crash between in-memory mutation and WAL fsync leaves the previous WAL stream intact — on recovery the prior RefreshCollection (or whatever last bulk-applied to the collection) is replayed, so the prior contents are observed.

pub fn refresh_collection_from_records( &self, name: &str, records: Vec<Vec<u8>>, ) -> Result<(), StoreError>

Replica-side analogue of Self::refresh_collection — issue #596 slice 9d. Takes pre-serialized record bytes from the primary’s CDC stream (the same bytes the primary wrote into the RefreshCollection WAL action), applies the atomic swap, and emits the same RefreshCollection WAL action against the replica’s local store WAL so the post-swap state survives a replica restart through the normal recovery path.

Idempotency: re-applying the same records bytes is a full rebuild from the same payload, so the resulting backing- collection contents are equal to the prior call’s result. The primary-side LogicalChangeApplier short-circuits exact duplicate LSN+payload combinations before reaching here.

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 lookup_graph_nodes_by_label_in( &self, collection: &str, label: &str, ) -> Vec<EntityId>

Look up entity IDs for a graph node label scoped to a single collection.

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 take_replayed_turbo_inserts( &self, collection: &str, ) -> Option<Vec<(u64, Vec<f32>)>>

Drain WAL-replayed VectorInsert records for collection (issue #694). Returns None when nothing was captured at open time (in-memory mode, fresh database, or non-turbo collection). One-shot: the caller owns the records after this call, the store’s internal buffer is cleared for that collection.

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_table_row_by_logical_id( &self, collection: &str, logical_id: EntityId, ) -> Option<UnifiedEntity>

Resolve a table row by stable logical identity.

Legacy rows use logical_id == id, so the physical-id lookup remains the fast path. Versioned rows may have a different physical id and fall back to a scan until the history-store/index slices add a dedicated map.

pub fn table_row_versions_by_logical_id( &self, collection: &str, logical_id: EntityId, ) -> Vec<UnifiedEntity>

pub fn vacuum_mvcc_history( &self, collection: &str, cutoff_xid: u64, ) -> Result<MvccVacuumStats, StoreError>

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.