Struct SeleneGraph 

pub struct SeleneGraph {

    pub meta: GraphMeta,
    pub node_store: NodeStore,
    pub edge_store: EdgeStore,
    pub adjacency_out: GenericHashMap<NodeId, AdjacencyEntry, FxBuildHasher, DefaultSharedPtr>,
    pub adjacency_in: GenericHashMap<NodeId, AdjacencyEntry, FxBuildHasher, DefaultSharedPtr>,
    pub idx_label: HashMap<DbString, RoaringBitmap>,
    pub idx_edge_label: HashMap<DbString, RoaringBitmap>,
    pub property_index: FxHashMap<(DbString, DbString), PropertyIndexEntry>,
    pub edge_property_index: FxHashMap<(DbString, DbString), PropertyIndexEntry>,
    pub composite_property_index: FxHashMap<(DbString, SmallVec<[DbString; 4]>), CompositePropertyIndexEntry>,
    pub vector_index: FxHashMap<(DbString, DbString), VectorIndexEntry>,
    pub text_index: FxHashMap<(DbString, DbString), TextIndexEntry>,
    pub node_id_to_row: GenericHashMap<NodeId, RowIndex, FxBuildHasher, DefaultSharedPtr>,
    pub edge_id_to_row: GenericHashMap<EdgeId, RowIndex, FxBuildHasher, DefaultSharedPtr>,
}

Immutable graph snapshot.

Fields

meta: GraphMeta

Snapshot metadata.

node_store: NodeStore

Node storage.

edge_store: EdgeStore

Edge storage.

adjacency_out: GenericHashMap<NodeId, AdjacencyEntry, FxBuildHasher, DefaultSharedPtr>

Outgoing adjacency keyed by source node.

adjacency_in: GenericHashMap<NodeId, AdjacencyEntry, FxBuildHasher, DefaultSharedPtr>

Incoming adjacency keyed by target node.

idx_label: HashMap<DbString, RoaringBitmap>

Bitmap of node rows carrying each label.

idx_edge_label: HashMap<DbString, RoaringBitmap>

Bitmap of edge rows carrying each edge label.

property_index: FxHashMap<(DbString, DbString), PropertyIndexEntry>

Per-(label, property) node value indexes. See spec 03 section 5.2.

edge_property_index: FxHashMap<(DbString, DbString), PropertyIndexEntry>

Per-(edge label, property) edge value indexes.

composite_property_index: FxHashMap<(DbString, SmallVec<[DbString; 4]>), CompositePropertyIndexEntry>

Per-(label, properties...) node composite value indexes.

vector_index: FxHashMap<(DbString, DbString), VectorIndexEntry>

Per-(label, property) node vector indexes.

text_index: FxHashMap<(DbString, DbString), TextIndexEntry>

Per-(label, property) node BM25 text indexes.

node_id_to_row: GenericHashMap<NodeId, RowIndex, FxBuildHasher, DefaultSharedPtr>

External NodeId -> RowIndex lookup (the inverse of NodeStore::row_to_id). Replaces the id.get() - 1 arithmetic so the external id can stay stable while the row is remapped by compaction (D22 / BRIEF-Item-4a). imbl for cheap copy-on-write snapshot clones.

edge_id_to_row: GenericHashMap<EdgeId, RowIndex, FxBuildHasher, DefaultSharedPtr>

External EdgeId -> RowIndex lookup (inverse of EdgeStore::row_to_id).

Implementations

impl SeleneGraph

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

Re-derive every built-in index from the authoritative node/edge columns and assert it matches the maintained index state.

Returns Ok(()) when the snapshot is internally consistent, or Err(message) describing the first detected drift. Intended for debug assertions and tests — it allocates fresh reference indexes and is O(nodes * indexes + edges) per call.

Checked invariant families

1. Label / edge-label bitmaps match a re-derivation from alive node label sets and alive edge labels; no bucket is present-but-empty.
2. Typed property indexes match a fresh lenient re-build (build_property_index_lenient). The lenient policy is reused so open-graph kind drift and NaN — which the commit path legitimately skips — do not false-positive.
3. Composite typed indexes match a fresh lenient re-build, same skip-aware policy.
4. Vector row-set indexes match a fresh lenient re-build, same skip-aware policy.
5. Text BM25 indexes match a fresh re-build from string properties.
6. Store integrity / alive-set parity: per-store columns share one length and every alive row index is in range. Dead rows are permitted holes (D11) and are only asserted absent from derived state, never from the columns. The snapshot’s meta.next_*_id allocator high-water marks are intentionally not checked here: the published snapshot’s meta is allowed to carry stale allocator fields after a from_graph / recovery load (the real allocator floor is enforced separately by IdAllocator::from_meta_with_floors), so they are not a derived-index invariant.
7. Adjacency matches a re-derivation from alive edges in both directions, with no present-but-empty entry.

Errors

Returns the first mismatch as a human-readable String.

impl SeleneGraph

pub fn new(graph_id: GraphId) -> Self

Construct an empty graph snapshot.

pub const fn graph_id(&self) -> GraphId

Return this graph snapshot’s stable graph ID.

pub fn node_count(&self) -> usize

Number of alive nodes.

pub fn live_nodes(&self) -> &RoaringBitmap

Bitmap of alive node row indices.

Returned bitmap is row-indexed (matching nodes_with_label), not NodeId-indexed; consumers convert a row to its external NodeId via Self::node_id_for_row (never by row + 1 arithmetic — the external id is stable while compaction renumbers the row). Used by selene-algorithms to seed the “all alive nodes” baseline of a GraphProjection.

pub fn edge_count(&self) -> usize

Number of alive edges.

pub fn compaction_stats(&self) -> CompactionStats

Return current row-space pressure for compaction planning.

This is a cheap read over store lengths and liveness bitmaps; it does not rebuild indexes or allocate a dense graph.

pub fn live_edges(&self) -> &RoaringBitmap

Bitmap of alive edge row indices.

The edge-side sibling of Self::live_nodes. The returned bitmap is row-indexed (matching edges_with_label), not EdgeId-indexed; consumers convert a row to its external EdgeId via Self::edge_id_for_row (never by row + 1 arithmetic). Covers every alive edge regardless of label — used by the DROP GRAPH factory-reset (BRIEF-152) to enumerate every live edge, including untyped/arbitrary-label ones that a per-type truncate would miss.

pub fn row_for_node_id(&self, id: NodeId) -> Option<RowIndex>

Map an external NodeId to its internal RowIndex.

Returns None for a never-committed (aborted-tx hole) id. A deleted id still resolves — to its now-dead row — so liveness, not existence, distinguishes it (the row’s alive bit is clear). This is the map-backed replacement for the old id - 1 arithmetic; the external id stays stable while BRIEF-Item-4b compaction renumbers the row.

pub fn row_for_edge_id(&self, id: EdgeId) -> Option<RowIndex>

Map an external EdgeId to its internal RowIndex; see Self::row_for_node_id.

pub fn node_id_for_row(&self, row: RowIndex) -> Option<NodeId>

Recover the external NodeId bound to a materialized RowIndex.

Reads the row_to_id column (the persistence-stable per-row id), never synthesizing row + 1. Returns None past the column end or for a never-committed hole row (which holds NodeId::TOMBSTONE).

pub fn edge_id_for_row(&self, row: RowIndex) -> Option<EdgeId>

Recover the external EdgeId bound to a materialized RowIndex; see Self::node_id_for_row.

pub fn is_node_alive(&self, id: NodeId) -> bool

Return true when id names an alive node.

pub fn is_edge_alive(&self, id: EdgeId) -> bool

Return true when id names an alive edge.

pub fn node_labels(&self, id: NodeId) -> Option<&LabelSet>

Return node labels for an alive node.

pub fn node_properties(&self, id: NodeId) -> Option<&PropertyMap>

Return node properties for an alive node.

pub fn edge_label(&self, id: EdgeId) -> Option<&DbString>

Return edge label for an alive edge.

pub fn edge_endpoints(&self, id: EdgeId) -> Option<(NodeId, NodeId)>

Return edge endpoints for an alive edge.

pub fn edge_properties(&self, id: EdgeId) -> Option<&PropertyMap>

Return edge properties for an alive edge.

pub fn outgoing_edges(&self, source: NodeId) -> Option<&AdjacencyEntry>

Return outgoing adjacency for source.

pub fn incoming_edges(&self, target: NodeId) -> Option<&AdjacencyEntry>

Return incoming adjacency for target.

pub fn node_has_incident_edges(&self, id: NodeId) -> bool

Return true when an alive node has at least one incident edge.

pub fn nodes_with_label(&self, label: &DbString) -> Option<&RoaringBitmap>

Return the bitmap of node rows carrying label.

pub fn edges_with_label(&self, label: &DbString) -> Option<&RoaringBitmap>

Return the bitmap of edge rows carrying label.

pub fn label_count(&self) -> usize

Number of distinct node labels currently indexed.

pub fn edge_label_count(&self) -> usize

Number of distinct edge labels currently indexed.

pub fn property_index_for( &self, label: &DbString, property: &DbString, ) -> Option<Arc<TypedIndex>>

Return a clone of the registered (label, property) index.

pub fn edge_property_index_for( &self, label: &DbString, property: &DbString, ) -> Option<Arc<TypedIndex>>

Return a clone of the registered edge (label, property) index.

pub fn composite_property_index_for( &self, label: &DbString, properties: &[DbString], ) -> Option<Arc<CompositeTypedIndex>>

Return a clone of the registered composite index.

pub fn composite_property_index_entry_for( &self, label: &DbString, properties: &[DbString], ) -> Option<&CompositePropertyIndexEntry>

Return composite index metadata for a property set.

pub fn vector_index_for( &self, label: &DbString, property: &DbString, ) -> Option<Arc<VectorIndex>>

Return a clone of the registered vector index.

pub fn text_index_for( &self, label: &DbString, property: &DbString, ) -> Option<Arc<TextIndex>>

Return a clone of the registered text index.

pub fn property_index_count(&self) -> usize

Number of distinct (label, property) indexes currently registered.

pub fn edge_property_index_count(&self) -> usize

Number of registered edge property indexes.

pub fn composite_property_index_count(&self) -> usize

Number of distinct (label, properties...) indexes currently registered.

pub fn vector_index_count(&self) -> usize

Number of distinct (label, property) vector indexes currently registered.

pub fn text_index_count(&self) -> usize

Number of distinct (label, property) text indexes currently registered.

pub fn iter_property_indexes( &self, ) -> impl Iterator<Item = (DbString, DbString, TypedIndexKind)> + '_

Iterate built-in property indexes as owned (label, property, kind) tuples.

This covers only SeleneGraph’s built-in property indexes. Extension-provider index state is surfaced through that provider’s own procedures.

pub fn iter_property_index_entries( &self, ) -> impl Iterator<Item = (DbString, DbString, TypedIndexKind, Option<DbString>)> + '_

Iterate built-in property indexes with optional explicit catalog names.

pub fn iter_composite_property_index_entries( &self, ) -> impl Iterator<Item = CompositePropertyIndexEntryRow> + '_

Iterate built-in composite property indexes with optional explicit catalog names.

pub fn iter_vector_index_entries( &self, ) -> impl Iterator<Item = VectorIndexEntryRow> + '_

Iterate built-in vector indexes with optional explicit catalog names.

pub fn iter_text_index_entries( &self, ) -> impl Iterator<Item = TextIndexEntryRow> + '_

Iterate built-in text indexes with optional explicit catalog names.

pub fn nodes_with_property_eq( &self, label: &DbString, property: &DbString, value: &Value, ) -> Option<Cow<'_, RoaringBitmap>>

Return rows matching value under a registered property index.

None means no index is registered for (label, property) or the supplied value cannot be used with that index kind. Some(empty) means the index exists but no row matches. A kind-mismatched probe returns None so the caller drops to a linear scan; open-graph kind drift remains discoverable via cross-variant value_compare.

pub fn nodes_with_property_any( &self, label: &DbString, property: &DbString, values: &[Value], ) -> Option<RoaringBitmap>

Return the union of node rows matching any indexed scalar value.

None means no node property index is registered for (label, property) or at least one supplied value cannot be used with that index kind. Some(empty) means the index exists but no row matches the value set.

pub fn edges_with_property_eq( &self, label: &DbString, property: &DbString, value: &Value, ) -> Option<Cow<'_, RoaringBitmap>>

Return edge rows matching value under a registered edge property index.

None means no edge index is registered for (label, property) or the supplied value cannot be used with that index kind. Some(empty) means the index exists but no edge row matches.

pub fn edges_with_property_any( &self, label: &DbString, property: &DbString, values: &[Value], ) -> Option<RoaringBitmap>

Return the union of edge rows matching any indexed scalar value.

None means no edge property index is registered for (label, property) or at least one supplied value cannot be used with that index kind. Some(empty) means the index exists but no row matches the value set.

pub fn nodes_with_property_range<R>( &self, label: &DbString, property: &DbString, range: R, ) -> Option<RoaringBitmap>

where R: RangeBounds<Value>,

Return rows matching range under a registered property index.

None means no index is registered or the supplied bounds do not match the index kind. Some(empty) means the index exists but the range matches no rows.

pub fn edges_with_property_range<R>( &self, label: &DbString, property: &DbString, range: R, ) -> Option<RoaringBitmap>

where R: RangeBounds<Value>,

Return edge rows matching range under a registered edge property index.

None means no edge index is registered or the supplied bounds do not match the index kind. Some(empty) means the index exists but no edge row matches.

pub fn nodes_with_property_prefix( &self, label: &DbString, property: &DbString, prefix: &str, ) -> Option<RoaringBitmap>

Return rows whose string property key starts with prefix.

None means no index is registered or the registered index is not a string index.

impl SeleneGraph

pub fn exact_json_contains_nodes( &self, label: &DbString, property: &DbString, candidate: &JsonValue, k: usize, ) -> GraphResult<Vec<JsonContainmentHit>>

Exhaustively find JSON-valued node properties containing candidate.

pub fn exact_json_contains_nodes_checked( &self, label: &DbString, property: &DbString, candidate: &JsonValue, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonContainmentHit>, JsonSearchError>

Exhaustively find JSON-valued node properties with cancellation checks.

pub fn exact_json_path_exists_nodes( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], k: usize, ) -> GraphResult<Vec<JsonPathHit>>

Exhaustively find JSON-valued node properties where path exists.

pub fn exact_json_path_exists_nodes_checked( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathHit>, JsonSearchError>

Exhaustively find JSON-valued node properties with path-existence checks.

pub fn exact_json_path_contains_nodes( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidate: &JsonValue, k: usize, ) -> GraphResult<Vec<JsonPathContainmentHit>>

Exhaustively find JSON-valued node properties whose selected path contains candidate.

pub fn exact_json_path_contains_nodes_checked( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidate: &JsonValue, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathContainmentHit>, JsonSearchError>

Exhaustively find JSON path containment matches with cancellation checks.

pub fn exact_json_path_value_nodes( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], k: usize, ) -> GraphResult<Vec<JsonPathValueHit>>

Exhaustively find JSON-valued node properties where path selects a value.

pub fn exact_json_path_value_nodes_checked( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathValueHit>, JsonSearchError>

Exhaustively find JSON path values with cancellation checks.

impl SeleneGraph

pub fn exact_json_contains_candidate_nodes( &self, label: &DbString, property: &DbString, candidate: &JsonValue, candidates: &[NodeId], k: usize, ) -> GraphResult<Vec<JsonContainmentHit>>

Find candidate nodes whose JSON property contains candidate.

pub fn exact_json_contains_candidate_nodes_checked( &self, label: &DbString, property: &DbString, candidate: &JsonValue, candidates: &[NodeId], k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonContainmentHit>, JsonSearchError>

Find candidate JSON containment matches with cancellation checks.

pub fn exact_json_path_exists_candidate_nodes( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidates: &[NodeId], k: usize, ) -> GraphResult<Vec<JsonPathHit>>

Find candidate nodes whose JSON property has path.

pub fn exact_json_path_exists_candidate_nodes_checked( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidates: &[NodeId], k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathHit>, JsonSearchError>

Find candidate JSON path-existence matches with cancellation checks.

pub fn exact_json_path_contains_candidate_nodes( &self, label: &DbString, property: &DbString, options: JsonPathContainmentCandidateOptions<'_>, ) -> GraphResult<Vec<JsonPathContainmentHit>>

Find candidate nodes whose selected JSON path contains candidate.

pub fn exact_json_path_contains_candidate_nodes_checked( &self, label: &DbString, property: &DbString, options: JsonPathContainmentCandidateOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathContainmentHit>, JsonSearchError>

Find candidate JSON path-containment matches with cancellation checks.

pub fn exact_json_path_value_candidate_nodes( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidates: &[NodeId], k: usize, ) -> GraphResult<Vec<JsonPathValueHit>>

Return selected JSON values for matching candidate nodes.

pub fn exact_json_path_value_candidate_nodes_checked( &self, label: &DbString, property: &DbString, path: &[JsonPathSelector], candidates: &[NodeId], k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<JsonPathValueHit>, JsonSearchError>

Return selected candidate JSON path values with cancellation checks.

impl SeleneGraph

pub fn build_text_index( &self, label: &DbString, property: &DbString, ) -> GraphResult<TextIndex>

Build a reusable BM25 postings index for label.property.

The returned index is tied to this graph snapshot. Mutations committed after the snapshot is read require rebuilding or durable registration in a later maintained-index layer.

Errors

Returns GraphError::Inconsistent if graph label/property columns are internally inconsistent while the snapshot is scanned.

pub fn indexed_text_search_nodes( &self, label: &DbString, property: &DbString, query: &str, k: usize, ) -> GraphResult<Vec<TextSearchHit>>

Rank string-valued node properties through a transient postings index.

This is primarily useful for tests and benchmark comparisons. Repeated production queries should build a TextIndex once and call TextIndex::search directly.

Errors

Returns GraphError::Inconsistent if index construction observes corrupt graph columns.

impl SeleneGraph

pub fn exact_text_search_nodes( &self, label: &DbString, property: &DbString, query: &str, k: usize, ) -> GraphResult<Vec<TextSearchHit>>

Exhaustively rank string-valued node properties using BM25.

This is the full-text correctness oracle and small-corpus path. It scans the row bitmap for label, skips nodes where property is absent or not a string, tokenizes documents with the built-in Unicode-aware tokenizer, and ranks matches with Okapi BM25 (k1 = 1.2, b = 0.75). Query tokens are deduplicated so repeated query terms do not overweight a document.

pub fn exact_text_search_nodes_checked( &self, label: &DbString, property: &DbString, query: &str, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<TextSearchHit>, TextSearchError>

Exhaustively rank string-valued node properties with cancellation checks.

pub fn exact_text_search_nodes_in_rows_checked( &self, label: &DbString, property: &DbString, query: &str, k: usize, allowed_rows: &RoaringBitmap, checker: CancellationChecker<'_>, ) -> Result<Vec<TextSearchHit>, TextSearchError>

Exhaustively rank text documents while admitting only allowed_rows.

BM25 corpus statistics are still computed over every string document for (label, property), so scores and ordering match an unfiltered search whose full ranking is filtered by this row set before k truncation.

impl SeleneGraph

pub fn approximate_vector_search_nodes_in_rows_checked( &self, label: &DbString, property: &DbString, query: &VectorValue, allowed_rows: &RoaringBitmap, options: ApproximateVectorSearchOptions, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Approximately rank vector-valued node properties while admitting only rows in allowed_rows.

impl SeleneGraph

pub fn approximate_vector_search_candidate_set_checked( &self, label: &DbString, property: &DbString, query: &VectorValue, candidates: &VectorCandidateSet, options: ApproximateVectorSearchOptions, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Approximately rank a canonical node candidate set through a TurboQuant index.

This is the approximate counterpart to Self::score_vector_candidate_set_checked: callers supply the candidate set explicitly, TurboQuant preselects up to ef_search candidates within that set, and the graph layer exact-reranks the returned rows against primary VECTOR values. Missing nodes, nodes outside the registered (label, property) vector index, and nodes without a vector value are skipped under the normal snapshot visibility rules. When the search width covers every surviving indexed candidate row, the compressed preselection pass is skipped and those rows are exact-scored directly.

pub fn approximate_vector_search_candidate_sets_batch_checked( &self, label: &DbString, property: &DbString, queries: &[VectorValue], candidate_sets: &[VectorCandidateSet], options: ApproximateVectorSearchOptions, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Approximately rank one canonical node candidate set per query.

Each queries[i] is searched only within candidate_sets[i] through a matching TurboQuant index, then exact-reranked against primary vector values. Output positions correspond to input query positions.

impl SeleneGraph

pub fn exact_vector_search_nodes_batch_checked( &self, label: &DbString, property: &DbString, queries: &[VectorValue], metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Exhaustively rank vector-valued node properties for a batch of queries.

The output position corresponds to the input query position. This keeps the exact single-query semantics but resolves the row set once and scans candidates once, which is useful for agent-memory workloads that probe several embeddings over the same (label, property) surface.

impl SeleneGraph

pub fn score_vector_nodes( &self, property: &DbString, query: &VectorValue, candidates: &[NodeId], metric: VectorMetric, k: usize, ) -> GraphResult<Vec<VectorNodeSearchHit>>

Score an explicit node candidate set against one query vector.

This is the graph-retrieval rerank primitive: callers can produce candidates from graph pattern matches, graph algorithms, or ANN indexes, then rank only those nodes by a vector-valued property. Candidate ids are deduplicated before scoring. Missing, deleted, and non-vector candidates are skipped to match normal live-snapshot visibility.

pub fn score_vector_nodes_checked( &self, property: &DbString, query: &VectorValue, candidates: &[NodeId], metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Score explicit node candidates with cancellation checks.

This preserves Self::score_vector_nodes ordering and visibility while checking checker before work begins and every 1024 unique candidates.

pub fn score_vector_candidate_set( &self, property: &DbString, query: &VectorValue, candidates: &VectorCandidateSet, metric: VectorMetric, k: usize, ) -> GraphResult<Vec<VectorNodeSearchHit>>

Score one canonical node candidate set against one query vector.

This is the zero-renormalization companion to Self::score_vector_nodes. Callers that already hold a VectorCandidateSet can avoid the extra sort/dedup pass while keeping the same live-snapshot visibility, metric, and hit ordering semantics.

pub fn score_vector_candidate_set_checked( &self, property: &DbString, query: &VectorValue, candidates: &VectorCandidateSet, metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Score one canonical node candidate set with cancellation checks.

pub fn score_vector_nodes_batch<C>( &self, property: &DbString, queries: &[VectorValue], candidate_sets: &[C], metric: VectorMetric, k: usize, ) -> GraphResult<Vec<Vec<VectorNodeSearchHit>>>

where C: AsRef<[NodeId]>,

Score one explicit candidate set for each query vector.

The result position corresponds to the input query position. Candidate sets are independent and follow Self::score_vector_nodes semantics: each set is deduplicated, non-live or non-vector nodes are skipped, and hits are ordered by distance then node id. The method rejects mismatched query/candidate-set counts and mixed query dimensions before scoring.

pub fn score_vector_nodes_batch_checked<C>( &self, property: &DbString, queries: &[VectorValue], candidate_sets: &[C], metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

where C: AsRef<[NodeId]>,

Score batched explicit node candidates with cancellation checks.

This preserves Self::score_vector_nodes_batch ordering and visibility while checking checker before batch validation and before each query’s candidate set is scored.

pub fn score_vector_candidate_sets_batch( &self, property: &DbString, queries: &[VectorValue], candidate_sets: &[VectorCandidateSet], metric: VectorMetric, k: usize, ) -> GraphResult<Vec<Vec<VectorNodeSearchHit>>>

Score one canonical candidate set for each query vector.

This is the batch companion to Self::score_vector_candidate_set. It preserves the generic batch scoring contract while avoiding a second normalization pass for callers that already hold canonical candidate sets.

pub fn score_vector_candidate_sets_batch_checked( &self, property: &DbString, queries: &[VectorValue], candidate_sets: &[VectorCandidateSet], metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Score batched canonical candidate sets with cancellation checks.

pub fn score_vector_neighbors( &self, property: &DbString, query: &VectorValue, anchor: NodeId, options: VectorNeighborSearchOptions<'_>, ) -> GraphResult<Vec<VectorNodeSearchHit>>

Score vector-valued neighbors reached from one anchor through edge_label.

This is the one-hop graph candidate-set companion to Self::score_vector_nodes. It derives candidates from the snapshot’s directed adjacency, then applies the same dedupe, visibility, metric, and ordering rules as explicit candidate scoring.

pub fn score_vector_neighbors_checked( &self, property: &DbString, query: &VectorValue, anchor: NodeId, options: VectorNeighborSearchOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Score vector-valued neighbors with cancellation checks.

pub fn score_vector_neighbors_batch( &self, property: &DbString, queries: &[VectorValue], anchors: &[NodeId], options: VectorNeighborSearchOptions<'_>, ) -> GraphResult<Vec<Vec<VectorNodeSearchHit>>>

Score one anchor’s vector-valued neighbors for each query vector.

queries[i] is scored against neighbors derived from anchors[i]. Mismatched query/anchor counts and mixed query dimensions are rejected before scoring.

pub fn score_vector_neighbors_batch_checked( &self, property: &DbString, queries: &[VectorValue], anchors: &[NodeId], options: VectorNeighborSearchOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Score batched one-hop graph neighbors with cancellation checks.

pub fn score_vector_expanded_candidate_sets_batch( &self, property: &DbString, queries: &[VectorValue], root_sets: &[VectorCandidateSet], options: VectorNeighborSearchOptions<'_>, ) -> GraphResult<Vec<Vec<VectorNodeSearchHit>>>

Expand one canonical root set per query through one graph hop, then score it.

queries[i] is scored against root_sets[i] plus nodes reached from those roots through options.edge_label in options.direction. This is the batch graph-retrieval primitive for ANN-then-graph-expansion and graph-query-then-vector-rerank workloads.

pub fn score_vector_expanded_candidate_sets_batch_checked( &self, property: &DbString, queries: &[VectorValue], root_sets: &[VectorCandidateSet], options: VectorNeighborSearchOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Expand and score batched canonical root sets with cancellation checks.

pub fn expand_vector_candidate_sets_batch_checked( &self, root_sets: &[VectorCandidateSet], edge_label: &DbString, direction: VectorNeighborDirection, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorCandidateSet>, VectorSearchError>

Expand one canonical root set per query through one graph hop.

This is the reusable batch expansion primitive used by graph-expanded vector scorers. It preserves input order, reuses duplicate root-set expansion work within bounded batches, and checks cancellation while deriving candidates.

pub fn vector_neighbor_candidates( &self, anchor: NodeId, edge_label: &DbString, direction: VectorNeighborDirection, ) -> VectorCandidateSet

Return canonical vector-score candidates reached from one graph anchor.

Candidates are filtered by edge label and direction, sorted by NodeId, and deduplicated. The returned set intentionally does not check vector property presence or node liveness; scoring APIs apply normal snapshot visibility when the set is consumed.

pub fn expand_vector_candidate_set( &self, roots: &VectorCandidateSet, edge_label: &DbString, direction: VectorNeighborDirection, ) -> VectorCandidateSet

Expand canonical candidates through one labeled graph hop.

The returned set contains every root candidate plus neighbors reached from those roots through edge_label in direction. This is the production primitive behind graph-authored support/provenance expansion: callers can build a small root set from graph queries or ANN hits, expand through graph topology, then pass the canonical result to vector scoring.

pub fn expand_vector_candidate_set_checked( &self, roots: &VectorCandidateSet, edge_label: &DbString, direction: VectorNeighborDirection, checker: CancellationChecker<'_>, ) -> Result<VectorCandidateSet, VectorSearchError>

Expand canonical candidates through one labeled graph hop with cancellation checks.

impl SeleneGraph

pub fn exact_vector_search_nodes( &self, label: &DbString, property: &DbString, query: &VectorValue, metric: VectorMetric, k: usize, ) -> GraphResult<Vec<VectorNodeSearchHit>>

Exhaustively rank vector-valued node properties for one label.

This is the correctness oracle and small-corpus path for future ANN indexes: it scans the row bitmap for label, skips nodes where property is absent or not a vector, and returns the exact best k matches. Graph structural inconsistencies are reported as GraphError::Inconsistent; vector metric errors such as dimension mismatch propagate through GraphError::Core.

pub fn exact_vector_search_nodes_checked( &self, label: &DbString, property: &DbString, query: &VectorValue, metric: VectorMetric, k: usize, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Exhaustively rank vector-valued node properties with cancellation checks.

This preserves the exact ordering and filtering contract of Self::exact_vector_search_nodes while checking checker before the scan and every 1024 candidate rows thereafter. It is the preferred path for GQL procedure execution because a large exact scan should remain cooperatively cancellable until ANN indexes take over this surface.

pub fn approximate_vector_search_nodes_checked( &self, label: &DbString, property: &DbString, query: &VectorValue, options: ApproximateVectorSearchOptions, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Approximately rank vector-valued node properties through an ANN index.

This is intentionally separate from Self::exact_vector_search_nodes: it requires a registered ANN vector index whose dimension and metric match the query, then returns the approximate result set produced by that derived index. Distances are exact for the candidates the ANN index returns, but recall is governed by ef_search. TurboQuant skips compressed preselection when ef_search.max(k) already covers every indexed row, because that path would exact-rerank the full row set.

pub fn approximate_vector_search_nodes_batch_checked( &self, label: &DbString, property: &DbString, queries: &[VectorValue], options: ApproximateVectorSearchOptions, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Run approximate ANN vector search for a batch of queries.

The result at each output position corresponds to the query at the same input position and follows the same ordering, visibility, and error contract as Self::approximate_vector_search_nodes_checked. The batch path resolves the ANN index once and reuses scratch buffers where the algorithm supports them, making it the preferred native API when a caller has several independent embedding lookups over the same (label, property) index.

pub fn approximate_vector_search_expanded_candidates_checked( &self, label: &DbString, property: &DbString, query: &VectorValue, options: ApproximateVectorExpansionOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<VectorNodeSearchHit>, VectorSearchError>

Use ANN hits as graph roots, expand them, then exact-rerank candidates.

This composes the HNSW/IVF root-finding path with graph topology: approximate search chooses up to options.root_k seed nodes from the registered ANN index, one-hop graph expansion adds related candidates, then the expanded set is exact-reranked by the same vector property and metric. The ANN path remains explicit, so missing or metric-mismatched indexes return the same errors as Self::approximate_vector_search_nodes_checked.

pub fn approximate_vector_search_expanded_candidates_batch_checked( &self, label: &DbString, property: &DbString, queries: &[VectorValue], options: ApproximateVectorExpansionOptions<'_>, checker: CancellationChecker<'_>, ) -> Result<Vec<Vec<VectorNodeSearchHit>>, VectorSearchError>

Batch ANN-root graph expansion followed by exact candidate reranking.

The result at each output position corresponds to the query at the same input position. ANN roots are produced through one shared (label, property) index, converted to canonical root sets, expanded through options.edge_label, then scored by Self::score_vector_expanded_candidate_sets_batch_checked.

Trait Implementations

impl Clone for SeleneGraph

fn clone(&self) -> SeleneGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SeleneGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.