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 new_in_memory() -> Self

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 open(path: impl AsRef<Path>) -> Result<Self>

Opens a database at the given path, creating it if it doesn’t exist.

If you’ve used this path before, Grafeo recovers your data from the write-ahead log automatically. First open on a new path creates an empty database.

Errors

Returns an error if the path isn’t writable or recovery fails.

Examples

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::open("./my_social_network")?;

pub fn with_config(config: Config) -> Result<Self>

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 execute(&self, query: &str) -> Result<QueryResult>

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>

Executes a query with parameters and returns the result.

Errors

Returns an error if the query fails.

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

Executes a query and returns a single scalar value.

Errors

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

pub fn config(&self) -> &Config

Returns the configuration.

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

Returns the underlying store.

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

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

Returns the buffer manager for memory-aware operations.

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

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).

pub fn wal(&self) -> Option<&Arc<WalManager>>

Returns the WAL manager if available.

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 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 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 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<()>

Forces a WAL checkpoint.

Flushes all pending WAL records to the main storage.

Errors

Returns an error if the checkpoint fails.

pub fn save(&self, path: impl AsRef<Path>) -> Result<()>

Saves the database to a file path.

• If in-memory: creates a new persistent database at path
• If file-backed: creates a copy at the new path

The original database remains unchanged.

Errors

Returns an error if the save operation fails.

pub fn to_memory(&self) -> Result<Self>

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 open_in_memory(path: impl AsRef<Path>) -> Result<Self>

Opens a database file and loads it entirely into memory.

The returned database has no connection to the original file. Changes will NOT be written back to the file.

Errors

Returns an error if the file can’t be opened or loaded.

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.

Trait Implementations

impl Drop for GrafeoDB

fn drop(&mut self)

Executes the destructor for this type.