Struct EntityGraph 

pub struct EntityGraph { /* private fields */ }

Core entity graph with bitmap tag indexing and bidirectional ref adjacency.

Implementations

impl EntityGraph

pub fn new() -> Self

Create an empty entity graph with standard Haystack fields auto-indexed and default changelog capacity (50,000).

pub fn with_changelog_capacity(capacity: usize) -> Self

Create an empty entity graph with a custom changelog capacity.

pub fn with_namespace(ns: DefNamespace) -> Self

Create an entity graph with an ontology namespace.

pub fn index_field(&mut self, field: &str)

Register a field for B-Tree value indexing. Enables O(log N) range queries (e.g. temp > 72) for this field. Must be called before entities are added, or followed by rebuild_value_index for existing data.

pub fn rebuild_value_index(&mut self)

Rebuild the value index for all indexed fields from the current entities.

pub fn value_index(&self) -> &ValueIndex

Returns a reference to the value index (for use by the query planner).

pub fn track_column(&mut self, tag: &str)

Register a tag for columnar storage. Enables cache-friendly sequential scans for this tag. Must be called before entities are added, or followed by rebuild_columnar for existing data.

pub fn rebuild_columnar(&mut self)

Rebuild all tracked columnar data from current entities.

pub fn columnar(&self) -> &ColumnarStore

Returns a reference to the columnar store for direct column scans.

pub fn add(&mut self, entity: HDict) -> Result<String, GraphError>

Add an entity to the graph.

The entity must have an id tag that is a Ref. Returns the ref value string on success.

pub fn get(&self, ref_val: &str) -> Option<&HDict>

Get a reference to an entity by ref value.

pub fn update( &mut self, ref_val: &str, changes: HDict, ) -> Result<(), GraphError>

Update an existing entity by merging changes into it.

Tags in changes overwrite existing tags; Kind::Remove tags are deleted. The id tag cannot be changed.

pub fn remove(&mut self, ref_val: &str) -> Result<HDict, GraphError>

Remove an entity from the graph. Returns the removed entity.

pub fn read(&self, filter_expr: &str, limit: usize) -> Result<HGrid, GraphError>

Run a filter expression and return matching entities as a grid.

pub fn read_all( &self, filter_expr: &str, limit: usize, ) -> Result<Vec<&HDict>, GraphError>

Run a filter expression and return matching entities as references.

pub fn refs_from(&self, ref_val: &str, ref_type: Option<&str>) -> Vec<String>

Get ref values that the given entity points to.

pub fn refs_to(&self, ref_val: &str, ref_type: Option<&str>) -> Vec<String>

Get ref values of entities that point to the given entity.

pub fn rebuild_csr(&mut self)

Rebuild the CSR snapshot from the current adjacency. Should be called after a batch of mutations (e.g., import, sync).

pub fn csr_is_stale(&self) -> bool

Returns true if the CSR snapshot is stale (version mismatch).

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

Return all edges in the graph as (source_ref, ref_tag, target_ref) tuples.

pub fn neighbors( &self, ref_val: &str, hops: usize, ref_types: Option<&[&str]>, ) -> (Vec<&HDict>, Vec<(String, String, String)>)

BFS neighborhood: return entities and edges within hops of ref_val.

ref_types optionally restricts which ref tags are traversed. Returns (entities, edges) where edges are (source, ref_tag, target).

pub fn shortest_path(&self, from: &str, to: &str) -> Vec<String>

BFS shortest path from from to to. Returns ordered ref_vals, or empty vec if no path exists.

pub fn subtree(&self, root: &str, max_depth: usize) -> Vec<(&HDict, usize)>

Return the subtree rooted at root up to max_depth levels.

Walks reverse refs (children referencing parent). Returns entities paired with their depth from root. Root is depth 0.

pub fn ref_chain(&self, ref_val: &str, ref_tags: &[&str]) -> Vec<&HDict>

Walk a chain of ref tags starting from an entity.

For example, ref_chain("point-1", &["equipRef", "siteRef"]) follows point-1 → its equipRef → that entity’s siteRef, returning the ordered path of resolved entities (excluding the starting entity).

pub fn site_for(&self, ref_val: &str) -> Option<&HDict>

Resolve the site for any entity by walking equipRef → siteRef.

If the entity itself has a site marker, returns it directly. Otherwise walks the standard Haystack ref chain.

pub fn children(&self, ref_val: &str) -> Vec<&HDict>

All direct children: entities with any ref tag pointing to this entity.

pub fn equip_points(&self, equip_ref: &str, filter: Option<&str>) -> Vec<&HDict>

All points for an equip — children with the point marker.

Optionally filter further with a filter expression.

pub fn entities_fitting(&self, spec_name: &str) -> Vec<&HDict>

Find all entities that structurally fit a spec/type name.

Requires a namespace to be set. Returns empty if no namespace.

pub fn validate(&self) -> Vec<ValidationIssue>

Validate all entities against the namespace and check for dangling refs.

Returns empty if no namespace is set and no dangling refs exist.

pub fn to_grid(&self, filter_expr: &str) -> Result<HGrid, GraphError>

Convert matching entities to a grid.

If filter_expr is empty, exports all entities. Otherwise, delegates to read.

pub fn from_grid( grid: &HGrid, namespace: Option<DefNamespace>, ) -> Result<Self, GraphError>

Build an EntityGraph from a grid.

Rows without a valid id Ref tag are silently skipped.

pub fn changes_since( &self, version: u64, ) -> Result<Vec<&GraphDiff>, ChangelogGap>

Get changelog entries since a given version.

Returns Err(ChangelogGap) if the requested version has been evicted from the changelog, signalling the subscriber must do a full resync.

pub fn floor_version(&self) -> u64

The lowest version still retained in the changelog.

Returns 0 if no entries have been evicted.

pub fn changelog_capacity(&self) -> usize

The configured changelog capacity.

pub fn version(&self) -> u64

Current graph version (monotonically increasing).

pub fn len(&self) -> usize

Number of entities in the graph.

pub fn is_empty(&self) -> bool

Returns true if the graph has no entities.

pub fn contains(&self, ref_val: &str) -> bool

Returns true if an entity with the given ref value exists.

pub fn all(&self) -> Vec<&HDict>

Returns references to all entities in the graph.

pub fn hierarchy_tree( &self, root: &str, max_depth: usize, ) -> Option<HierarchyNode>

Build a full hierarchy subtree as a structured tree. root is the entity ref, max_depth limits recursion (0 = root only).

pub fn classify(&self, ref_val: &str) -> Option<String>

Determine the most specific entity type from its markers.

Returns the most specific marker tag that identifies the entity type. E.g., an entity with equip + ahu markers returns "ahu" (most specific).

Trait Implementations

impl Default for EntityGraph

fn default() -> Self

Returns the “default value” for a type.