Struct ConcurrentTemporalHnsw

pub struct ConcurrentTemporalHnsw<D: DistanceMetric> {
    inner: RwLock<TemporalHnsw<D>>,
    insert_queue: Mutex<Vec<PendingInsert>>,
}

Thread-safe spatiotemporal HNSW index with insert queue (RFC-002-04).

Uses a two-tier approach to reduce write lock contention:

• Inserts are queued into a Mutex<Vec<...>> (sub-microsecond)
• flush_inserts() drains the queue under a single write lock
• Searches always acquire a read lock (concurrent, unblocked during queue drain)

For immediate visibility, use insert() which still takes the write lock directly. For high-throughput ingestion, use queue_insert() + flush_inserts().

Fields

inner: RwLock<TemporalHnsw<D>>

insert_queue: Mutex<Vec<PendingInsert>>

Insert queue for batched commits (RFC-002-04, Option A).

Implementations

impl<D: DistanceMetric> ConcurrentTemporalHnsw<D>

pub fn new(config: HnswConfig, metric: D) -> Self

Create a new empty concurrent index.

pub fn len(&self) -> usize

Number of points in the index.

pub fn is_empty(&self) -> bool

Whether the index is empty.

pub fn insert(&self, entity_id: u64, timestamp: i64, vector: &[f32]) -> u32

Insert a temporal point (exclusive write lock).

pub fn search( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, ) -> Vec<(u32, f32)>

Search with temporal filtering (shared read lock).

pub fn trajectory( &self, entity_id: u64, filter: TemporalFilter, ) -> Vec<(i64, u32)>

Retrieve trajectory for an entity (shared read lock).

pub fn timestamp(&self, node_id: u32) -> i64

Get timestamp for a node (shared read lock).

pub fn entity_id(&self, node_id: u32) -> u64

Get entity_id for a node (shared read lock).

pub fn vector(&self, node_id: u32) -> Vec<f32>

Get vector for a node (shared read lock).

pub fn compute_centroid(&self) -> Option<Vec<f32>>

Compute the centroid (mean vector) of all indexed vectors.

pub fn set_centroid(&self, centroid: Vec<f32>)

Set the centroid for anisotropy correction (write lock).

pub fn clear_centroid(&self)

Clear the centroid (write lock).

pub fn centroid(&self) -> Option<Vec<f32>>

Get the current centroid, if set.

pub fn centered_vector(&self, vec: &[f32]) -> Vec<f32>

Return a centered copy of the given vector (vec - centroid).

pub fn queue_insert(&self, entity_id: u64, timestamp: i64, vector: Vec<f32>)

Queue an insert for batched processing (RFC-002-04).

This only takes a Mutex (sub-microsecond), NOT the write lock. The insert becomes visible after flush_inserts() is called.

pub fn pending_inserts(&self) -> usize

Number of pending inserts in the queue.

pub fn flush_inserts(&self) -> usize

Flush all queued inserts, applying them under a single write lock.

Returns the number of inserts applied.

Trait Implementations

impl<D: DistanceMetric> IndexBackend for ConcurrentTemporalHnsw<D>

fn insert( &self, entity_id: u64, vector: &[f32], timestamp: i64, ) -> Result<u32, IndexError>

Insert a point into the index.

fn search( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, ) -> Result<Vec<ScoredResult>, QueryError>

Search for the k nearest neighbors with temporal filtering.

fn remove(&self, _point_id: u64) -> Result<(), IndexError>

Remove a point from the index.

fn len(&self) -> usize

Number of points in the index.

fn is_empty(&self) -> bool

Whether the index is empty.

impl<D: DistanceMetric> TemporalIndexAccess for ConcurrentTemporalHnsw<D>

fn search_raw( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, ) -> Vec<(u32, f32)>

Search with temporal filtering, returning (node_id, score) pairs.

fn trajectory(&self, entity_id: u64, filter: TemporalFilter) -> Vec<(i64, u32)>

Retrieve trajectory for an entity: (timestamp, node_id) pairs.

fn vector(&self, node_id: u32) -> Vec<f32>

Get the vector for a node. Returns owned vec for thread safety.

fn entity_id(&self, node_id: u32) -> u64

Get the entity_id for a node.

fn timestamp(&self, node_id: u32) -> i64

Get the timestamp for a node.

fn len(&self) -> usize

Number of points in the index.

fn regions(&self, level: usize) -> Vec<(u32, Vec<f32>, usize)>

Get semantic regions at a given HNSW level (RFC-004). Returns (hub_node_id, hub_vector, n_assigned) per region.

fn region_members( &self, region_hub: u32, level: usize, filter: TemporalFilter, ) -> Vec<(u32, u64, i64)>

Get points belonging to a specific region, optionally time-filtered (RFC-005). Returns (node_id, entity_id, timestamp) per member.

fn region_assignments( &self, level: usize, filter: TemporalFilter, ) -> HashMap<u32, Vec<(u64, i64)>>

Assign all nodes to regions in a single O(N) pass, optionally time-filtered. Returns HashMap<hub_id, Vec<(entity_id, timestamp)>>.

fn region_trajectory( &self, entity_id: u64, level: usize, window_days: i64, alpha: f32, ) -> Vec<(i64, Vec<f32>)>

Smoothed region-distribution trajectory for an entity (RFC-004).

fn is_empty(&self) -> bool

Whether the index is empty.

fn metadata(&self, _node_id: u32) -> HashMap<String, String>

Get metadata for a node. Returns empty map if not available.

fn search_with_metadata( &self, query: &[f32], k: usize, filter: TemporalFilter, alpha: f32, query_timestamp: i64, metadata_filter: &MetadataFilter, ) -> Vec<(u32, f32)>

Search with metadata filtering (post-filter on search results). Default: ignores metadata filter and delegates to search_raw.