Struct GrafeoDB 

pub struct GrafeoDB { /* private fields */ }

Your handle to a Grafeo database.

Start here. Create one with new_in_memory() for quick experiments, or open() for persistent storage. Then grab a session() to start querying.

Examples

use grafeo_engine::GrafeoDB;

// Quick in-memory database
let db = GrafeoDB::new_in_memory();

// Add some data
db.create_node(&["Person"]);

// Query it
let session = db.session();
let result = session.execute("MATCH (p:Person) RETURN p")?;

Implementations

impl GrafeoDB

pub fn node_count(&self) -> usize

Returns the number of nodes in the database.

pub fn edge_count(&self) -> usize

Returns the number of edges in the database.

pub fn label_count(&self) -> usize

Returns the number of distinct labels in the database.

pub fn property_key_count(&self) -> usize

Returns the number of distinct property keys in the database.

pub fn edge_type_count(&self) -> usize

Returns the number of distinct edge types in the database.

pub fn is_persistent(&self) -> bool

Returns true if this database is backed by a file (persistent).

In-memory databases return false.

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

Returns the database file path, if persistent.

In-memory databases return None.

pub fn info(&self) -> DatabaseInfo

Returns high-level database information.

Includes node/edge counts, persistence status, and mode (LPG/RDF).

pub fn detailed_stats(&self) -> DatabaseStats

Returns detailed database statistics.

Includes counts, memory usage, and index information.

pub fn schema(&self) -> SchemaInfo

Returns schema information (labels, edge types, property keys).

For LPG mode, returns label and edge type information. For RDF mode, returns predicate and named graph information.

pub fn rdf_schema(&self) -> SchemaInfo

Returns RDF schema information.

Only available when the RDF feature is enabled.

pub fn validate(&self) -> ValidationResult

Validates database integrity.

Checks for:

• Dangling edge references (edges pointing to non-existent nodes)
• Internal index consistency

Returns a list of errors and warnings. Empty errors = valid.

pub fn wal_status(&self) -> WalStatus

Returns WAL (Write-Ahead Log) status.

Returns None if WAL is not enabled.

pub fn wal_checkpoint(&self) -> Result<(), Error>

Forces a WAL checkpoint.

Flushes all pending WAL records to the main storage.

Errors

Returns an error if the checkpoint fails.

pub fn history( &self, entity_id: impl Into<EntityId>, ) -> Result<Vec<ChangeEvent>, Error>

Returns the full change history for an entity (node or edge).

Events are ordered chronologically by epoch.

Errors

Returns an error if the CDC feature is not enabled.

pub fn history_since( &self, entity_id: impl Into<EntityId>, since_epoch: EpochId, ) -> Result<Vec<ChangeEvent>, Error>

Returns change events for an entity since the given epoch.

pub fn changes_between( &self, start_epoch: EpochId, end_epoch: EpochId, ) -> Result<Vec<ChangeEvent>, Error>

Returns all change events across all entities in an epoch range.

impl GrafeoDB

pub fn create_node(&self, labels: &[&str]) -> NodeId

Creates a node with the given labels and returns its ID.

Labels categorize nodes - think of them like tags. A node can have multiple labels (e.g., ["Person", "Employee"]).

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let alice = db.create_node(&["Person"]);
let company = db.create_node(&["Company", "Startup"]);

pub fn create_node_with_props( &self, labels: &[&str], properties: impl IntoIterator<Item = (impl Into<PropertyKey>, impl Into<Value>)>, ) -> NodeId

Creates a new node with labels and properties.

If WAL is enabled, the operation is logged for durability.

pub fn get_node(&self, id: NodeId) -> Option<Node>

Gets a node by ID.

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

Deletes a node and all its edges.

If WAL is enabled, the operation is logged for durability.

pub fn set_node_property(&self, id: NodeId, key: &str, value: Value)

Sets a property on a node.

If WAL is enabled, the operation is logged for durability.

pub fn add_node_label(&self, id: NodeId, label: &str) -> bool

Adds a label to an existing node.

Returns true if the label was added, false if the node doesn’t exist or already has the label.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let alice = db.create_node(&["Person"]);

// Promote Alice to Employee
let added = db.add_node_label(alice, "Employee");
assert!(added);

pub fn remove_node_label(&self, id: NodeId, label: &str) -> bool

Removes a label from a node.

Returns true if the label was removed, false if the node doesn’t exist or doesn’t have the label.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let alice = db.create_node(&["Person", "Employee"]);

// Remove Employee status
let removed = db.remove_node_label(alice, "Employee");
assert!(removed);

pub fn get_node_labels(&self, id: NodeId) -> Option<Vec<String>>

Gets all labels for a node.

Returns None if the node doesn’t exist.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let alice = db.create_node(&["Person", "Employee"]);

let labels = db.get_node_labels(alice).unwrap();
assert!(labels.contains(&"Person".to_string()));
assert!(labels.contains(&"Employee".to_string()));

pub fn create_edge(&self, src: NodeId, dst: NodeId, edge_type: &str) -> EdgeId

Creates an edge (relationship) between two nodes.

Edges connect nodes and have a type that describes the relationship. They’re directed - the order of src and dst matters.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let alice = db.create_node(&["Person"]);
let bob = db.create_node(&["Person"]);

// Alice knows Bob (directed: Alice -> Bob)
let edge = db.create_edge(alice, bob, "KNOWS");

pub fn create_edge_with_props( &self, src: NodeId, dst: NodeId, edge_type: &str, properties: impl IntoIterator<Item = (impl Into<PropertyKey>, impl Into<Value>)>, ) -> EdgeId

Creates a new edge with properties.

If WAL is enabled, the operation is logged for durability.

pub fn get_edge(&self, id: EdgeId) -> Option<Edge>

Gets an edge by ID.

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

Deletes an edge.

If WAL is enabled, the operation is logged for durability.

pub fn set_edge_property(&self, id: EdgeId, key: &str, value: Value)

Sets a property on an edge.

If WAL is enabled, the operation is logged for durability.

pub fn remove_node_property(&self, id: NodeId, key: &str) -> bool

Removes a property from a node.

Returns true if the property existed and was removed, false otherwise.

pub fn remove_edge_property(&self, id: EdgeId, key: &str) -> bool

Removes a property from an edge.

Returns true if the property existed and was removed, false otherwise.

pub fn batch_create_nodes( &self, label: &str, property: &str, vectors: Vec<Vec<f32>>, ) -> Vec<NodeId>

Creates multiple nodes in bulk, each with a single vector property.

Much faster than individual create_node_with_props calls because it acquires internal locks once and loops in Rust rather than crossing the FFI boundary per vector.

Arguments

• label - Label applied to all created nodes
• property - Property name for the vector data
• vectors - Vector data for each node

Returns

Vector of created NodeIds in the same order as the input vectors.

impl GrafeoDB

pub fn create_property_index(&self, property: &str)

Creates an index on a node property for O(1) lookups by value.

After creating an index, calls to Self::find_nodes_by_property will be O(1) instead of O(n) for this property. The index is automatically maintained when properties are set or removed.

Example

// Create an index on the 'email' property
db.create_property_index("email");

// Now lookups by email are O(1)
let nodes = db.find_nodes_by_property("email", &Value::from("alice@example.com"));

pub fn drop_property_index(&self, property: &str) -> bool

Drops an index on a node property.

Returns true if the index existed and was removed.

pub fn has_property_index(&self, property: &str) -> bool

Returns true if the property has an index.

pub fn find_nodes_by_property( &self, property: &str, value: &Value, ) -> Vec<NodeId>

Finds all nodes that have a specific property value.

If the property is indexed, this is O(1). Otherwise, it scans all nodes which is O(n). Use Self::create_property_index for frequently queried properties.

Example

// Create index for fast lookups (optional but recommended)
db.create_property_index("city");

// Find all nodes where city = "NYC"
let nyc_nodes = db.find_nodes_by_property("city", &Value::from("NYC"));

pub fn create_vector_index( &self, label: &str, property: &str, dimensions: Option<usize>, metric: Option<&str>, m: Option<usize>, ef_construction: Option<usize>, ) -> Result<(), Error>

Creates a vector similarity index on a node property.

This enables efficient approximate nearest-neighbor search on vector properties. Currently validates the index parameters and scans existing nodes to verify the property contains vectors of the expected dimensions.

Arguments

• label - Node label to index (e.g., "Doc")
• property - Property containing vector embeddings (e.g., "embedding")
• dimensions - Expected vector dimensions (inferred from data if None)
• metric - Distance metric: "cosine" (default), "euclidean", "dot_product", "manhattan"
• m - HNSW links per node (default: 16). Higher = better recall, more memory.
• ef_construction - Construction beam width (default: 128). Higher = better index quality, slower build.

Errors

Returns an error if the metric is invalid, no vectors are found, or dimensions don’t match.

pub fn drop_vector_index(&self, label: &str, property: &str) -> bool

Drops a vector index for the given label and property.

Returns true if the index existed and was removed, false if no index was found.

After dropping, vector_search for this label+property pair will return an error.

pub fn rebuild_vector_index( &self, label: &str, property: &str, ) -> Result<(), Error>

Drops and recreates a vector index, rescanning all matching nodes.

This is useful after bulk inserts or when the index may be out of sync. When the index still exists, the previous configuration (dimensions, metric, M, ef_construction) is preserved. When it has already been dropped, dimensions are inferred from existing data and default parameters are used.

Errors

Returns an error if the rebuild fails (e.g., no matching vectors found and no dimensions can be inferred).

pub fn create_text_index( &self, label: &str, property: &str, ) -> Result<(), Error>

Creates a BM25 text index on a node property for full-text search.

Indexes all existing nodes with the given label and property. The index stays in sync automatically as nodes are created, updated, or deleted. Use rebuild_text_index only if the index was created before existing data was loaded.

Errors

Returns an error if the label has no nodes or the property contains no text values.

pub fn drop_text_index(&self, label: &str, property: &str) -> bool

Drops a text index on a label+property pair.

Returns true if the index existed and was removed.

pub fn rebuild_text_index( &self, label: &str, property: &str, ) -> Result<(), Error>

Rebuilds a text index by re-scanning all matching nodes.

Use after bulk property updates to keep the index current.

Errors

Returns an error if no text index exists for this label+property.

impl GrafeoDB

pub fn to_memory(&self) -> Result<GrafeoDB, Error>

Creates an in-memory copy of this database.

Returns a new database that is completely independent. Useful for:

• Testing modifications without affecting the original
• Faster operations when persistence isn’t needed

Errors

Returns an error if the copy operation fails.

pub fn export_snapshot(&self) -> Result<Vec<u8>, Error>

Exports the entire database to a binary snapshot.

The returned bytes can be stored (e.g. in IndexedDB) and later restored with import_snapshot().

Errors

Returns an error if serialization fails.

pub fn import_snapshot(data: &[u8]) -> Result<GrafeoDB, Error>

Creates a new in-memory database from a binary snapshot.

The data must have been produced by export_snapshot().

All edge references are validated before any data is inserted: every edge’s source and destination must reference a node present in the snapshot, and duplicate node/edge IDs are rejected. If validation fails, no database is created.

Errors

Returns an error if the snapshot is invalid, contains dangling edge references, has duplicate IDs, or deserialization fails.

pub fn iter_nodes(&self) -> impl Iterator<Item = Node>

Returns an iterator over all nodes in the database.

Useful for dump/export operations.

pub fn iter_edges(&self) -> impl Iterator<Item = Edge>

Returns an iterator over all edges in the database.

Useful for dump/export operations.

impl GrafeoDB

pub fn execute(&self, query: &str) -> Result<QueryResult, Error>

Runs a query directly on the database.

A convenience method that creates a temporary session behind the scenes. If you’re running multiple queries, grab a session() instead to avoid the overhead.

Errors

Returns an error if parsing or execution fails.

pub fn execute_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a query with parameters and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_cypher(&self, query: &str) -> Result<QueryResult, Error>

Executes a Cypher query and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_cypher_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a Cypher query with parameters and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_gremlin(&self, query: &str) -> Result<QueryResult, Error>

Executes a Gremlin query and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_gremlin_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a Gremlin query with parameters and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_graphql(&self, query: &str) -> Result<QueryResult, Error>

Executes a GraphQL query and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_graphql_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a GraphQL query with parameters and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_sql(&self, query: &str) -> Result<QueryResult, Error>

Executes a SQL/PGQ query (SQL:2023 GRAPH_TABLE) and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_sql_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a SQL/PGQ query with parameters and returns the result.

Errors

Returns an error if the query fails.

pub fn execute_sparql(&self, query: &str) -> Result<QueryResult, Error>

Executes a SPARQL query and returns the result.

SPARQL queries operate on the RDF triple store.

Errors

Returns an error if the query fails.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let result = db.execute_sparql("SELECT ?s ?p ?o WHERE { ?s ?p ?o }")?;

pub fn execute_language( &self, query: &str, language: &str, params: Option<HashMap<String, Value>>, ) -> Result<QueryResult, Error>

Executes a query in the specified language by name.

Supported language names: "gql", "cypher", "gremlin", "graphql", "sparql", "sql". Each requires the corresponding feature flag.

Errors

Returns an error if the language is unknown/disabled, or if the query fails.

pub fn rdf_store(&self) -> &Arc<RdfStore>

Returns the RDF store.

This provides direct access to the RDF store for triple operations.

pub fn query_scalar<T>(&self, query: &str) -> Result<T, Error>

where T: FromValue,

Executes a query and returns a single scalar value.

Errors

Returns an error if the query fails or doesn’t return exactly one row.

impl GrafeoDB

pub fn vector_search( &self, label: &str, property: &str, query: &[f32], k: usize, ef: Option<usize>, filters: Option<&HashMap<String, Value>>, ) -> Result<Vec<(NodeId, f32)>, Error>

Searches for the k nearest neighbors of a query vector.

Uses the HNSW index created by create_vector_index.

Arguments

• label - Node label that was indexed
• property - Property that was indexed
• query - Query vector (slice of floats)
• k - Number of nearest neighbors to return
• ef - Search beam width (higher = better recall, slower). Uses index default if None.
• filters - Optional property equality filters. Only nodes matching all (key, value) pairs will appear in results.

Returns

Vector of (NodeId, distance) pairs sorted by distance ascending.

pub fn batch_vector_search( &self, label: &str, property: &str, queries: &[Vec<f32>], k: usize, ef: Option<usize>, filters: Option<&HashMap<String, Value>>, ) -> Result<Vec<Vec<(NodeId, f32)>>, Error>

Searches for nearest neighbors for multiple query vectors in parallel.

Uses rayon parallel iteration under the hood for multi-core throughput.

Arguments

• label - Node label that was indexed
• property - Property that was indexed
• queries - Batch of query vectors
• k - Number of nearest neighbors per query
• ef - Search beam width (uses index default if None)
• filters - Optional property equality filters

pub fn mmr_search( &self, label: &str, property: &str, query: &[f32], k: usize, fetch_k: Option<usize>, lambda: Option<f32>, ef: Option<usize>, filters: Option<&HashMap<String, Value>>, ) -> Result<Vec<(NodeId, f32)>, Error>

Searches for diverse nearest neighbors using Maximal Marginal Relevance (MMR).

MMR balances relevance (similarity to query) with diversity (dissimilarity among selected results). This is the algorithm used by LangChain’s mmr_traversal_search() for RAG applications.

Arguments

• label - Node label that was indexed
• property - Property that was indexed
• query - Query vector
• k - Number of diverse results to return
• fetch_k - Number of initial candidates from HNSW (default: 4 * k)
• lambda - Relevance vs. diversity in [0, 1] (default: 0.5). 1.0 = pure relevance, 0.0 = pure diversity.
• ef - HNSW search beam width (uses index default if None)
• filters - Optional property equality filters

Returns

(NodeId, distance) pairs in MMR selection order. The f32 is the original distance from the query, matching vector_search.

pub fn text_search( &self, label: &str, property: &str, query: &str, k: usize, ) -> Result<Vec<(NodeId, f64)>, Error>

Searches a text index using BM25 scoring.

Returns up to k results as (NodeId, score) pairs sorted by descending relevance score.

Errors

Returns an error if no text index exists for this label+property.

pub fn hybrid_search( &self, label: &str, text_property: &str, vector_property: &str, query_text: &str, query_vector: Option<&[f32]>, k: usize, fusion: Option<FusionMethod>, ) -> Result<Vec<(NodeId, f64)>, Error>

Performs hybrid search combining text (BM25) and vector similarity.

Runs both text search and vector search, then fuses results using the specified method (default: Reciprocal Rank Fusion).

Arguments

• label - Node label to search within
• text_property - Property indexed for text search
• vector_property - Property indexed for vector search
• query_text - Text query for BM25 search
• query_vector - Vector query for similarity search (optional)
• k - Number of results to return
• fusion - Score fusion method (default: RRF with k=60)

Errors

Returns an error if the required indexes don’t exist.

impl GrafeoDB

pub fn new_in_memory() -> GrafeoDB

Creates an in-memory database - fast to create, gone when dropped.

Use this for tests, experiments, or when you don’t need persistence. For data that survives restarts, use open() instead.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let session = db.session();
session.execute("INSERT (:Person {name: 'Alice'})")?;

pub fn with_config(config: Config) -> Result<GrafeoDB, Error>

Creates a database with custom configuration.

Use this when you need fine-grained control over memory limits, thread counts, or persistence settings. For most cases, new_in_memory() or open() are simpler.

Errors

Returns an error if the database can’t be created or recovery fails.

Examples

use grafeo_engine::{GrafeoDB, Config};

// In-memory with a 512MB limit
let config = Config::in_memory()
    .with_memory_limit(512 * 1024 * 1024);

let db = GrafeoDB::with_config(config)?;

pub fn session(&self) -> Session

Opens a new session for running queries.

Sessions are cheap to create - spin up as many as you need. Each gets its own transaction context, so concurrent sessions won’t block each other on reads.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();
let session = db.session();

// Run queries through the session
let result = session.execute("MATCH (n) RETURN count(n)")?;

pub fn adaptive_config(&self) -> &AdaptiveConfig

Returns the adaptive execution configuration.

pub fn config(&self) -> &Config

Returns the configuration.

pub fn graph_model(&self) -> GraphModel

Returns the graph data model of this database.

pub fn memory_limit(&self) -> Option<usize>

Returns the configured memory limit in bytes, if any.

pub fn store(&self) -> &Arc<LpgStore>

Returns the underlying store.

This provides direct access to the LPG store for algorithm implementations.

pub fn gc(&self)

Garbage collects old MVCC versions that are no longer visible.

Determines the minimum epoch required by active transactions and prunes version chains older than that threshold. Also cleans up completed transaction metadata in the transaction manager.

pub fn buffer_manager(&self) -> &Arc<BufferManager>

Returns the buffer manager for memory-aware operations.

pub fn query_cache(&self) -> &Arc<QueryCache>

Returns the query cache.

pub fn close(&self) -> Result<(), Error>

Closes the database, flushing all pending writes.

For persistent databases, this ensures everything is safely on disk. Called automatically when the database is dropped, but you can call it explicitly if you need to guarantee durability at a specific point.

Errors

Returns an error if the WAL can’t be flushed (check disk space/permissions).

Trait Implementations

impl AdminService for GrafeoDB

fn info(&self) -> DatabaseInfo

Returns high-level database information (counts, mode, persistence).

fn detailed_stats(&self) -> DatabaseStats

Returns detailed database statistics (memory, disk, indexes).

fn schema(&self) -> SchemaInfo

Returns schema information (labels, edge types, property keys).

fn validate(&self) -> ValidationResult

Validates database integrity, returning errors and warnings.

fn wal_status(&self) -> WalStatus

Returns WAL (Write-Ahead Log) status.

fn wal_checkpoint(&self) -> Result<(), Error>

Forces a WAL checkpoint, flushing pending records to storage.

impl Drop for GrafeoDB

fn drop(&mut self)

Executes the destructor for this type.