Struct Session 

pub struct Session { /* private fields */ }

Your handle to the database - execute queries and manage transactions.

Get one from GrafeoDB::session(). Each session tracks its own transaction state, so you can have multiple concurrent sessions without them interfering.

Implementations

impl Session

pub fn graph_model(&self) -> GraphModel

Returns the graph model this session operates on.

pub fn use_graph(&self, name: &str)

Sets the current graph for this session (USE GRAPH).

pub fn current_graph(&self) -> Option<String>

Returns the current graph name, if any.

pub fn set_time_zone(&self, tz: &str)

Sets the session time zone.

pub fn time_zone(&self) -> Option<String>

Returns the session time zone, if set.

pub fn set_parameter(&self, key: &str, value: Value)

Sets a session parameter.

pub fn get_parameter(&self, key: &str) -> Option<Value>

Gets a session parameter by cloning it.

pub fn reset_session(&self)

Resets all session state to defaults.

pub fn set_viewing_epoch(&self, epoch: EpochId)

Sets a viewing epoch override for time-travel queries.

While set, all queries on this session see the database as it existed at the given epoch. Use clear_viewing_epoch to return to normal behavior.

pub fn clear_viewing_epoch(&self)

Clears the viewing epoch override, returning to normal behavior.

pub fn viewing_epoch(&self) -> Option<EpochId>

Returns the current viewing epoch override, if any.

pub fn get_node_history( &self, id: NodeId, ) -> Vec<(EpochId, Option<EpochId>, Node)>

Returns all versions of a node with their creation/deletion epochs.

Properties and labels reflect the current state (not versioned per-epoch).

pub fn get_edge_history( &self, id: EdgeId, ) -> Vec<(EpochId, Option<EpochId>, Edge)>

Returns all versions of an edge with their creation/deletion epochs.

Properties reflect the current state (not versioned per-epoch).

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

Executes a GQL query.

Errors

Returns an error if the query fails to parse or execute.

Examples

use grafeo_engine::GrafeoDB;

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

// Create a node
session.execute("INSERT (:Person {name: 'Alice', age: 30})")?;

// Query nodes
let result = session.execute("MATCH (n:Person) RETURN n.name, n.age")?;
for row in &result.rows {
    println!("{:?}", row);
}

pub fn execute_at_epoch( &self, query: &str, epoch: EpochId, ) -> Result<QueryResult>

Executes a GQL query with visibility at the specified epoch.

This enables time-travel queries: the query sees the database as it existed at the given epoch.

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 GQL query with parameters.

Errors

Returns an error if the query fails to parse or execute.

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

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 the query fails.

pub fn begin_tx(&mut self) -> Result<()>

Begins a new transaction.

Errors

Returns an error if a transaction is already active.

Examples

use grafeo_engine::GrafeoDB;

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

session.begin_tx()?;
session.execute("INSERT (:Person {name: 'Alice'})")?;
session.execute("INSERT (:Person {name: 'Bob'})")?;
session.commit()?; // Both inserts committed atomically

pub fn begin_tx_with_isolation( &mut self, isolation_level: IsolationLevel, ) -> Result<()>

Begins a transaction with a specific isolation level.

See begin_tx for the default (SnapshotIsolation).

Errors

Returns an error if a transaction is already active.

pub fn commit(&mut self) -> Result<()>

Commits the current transaction.

Makes all changes since begin_tx permanent.

Errors

Returns an error if no transaction is active.

pub fn rollback(&mut self) -> Result<()>

Aborts the current transaction.

Discards all changes since begin_tx.

Errors

Returns an error if no transaction is active.

Examples

use grafeo_engine::GrafeoDB;

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

session.begin_tx()?;
session.execute("INSERT (:Person {name: 'Alice'})")?;
session.rollback()?; // Insert is discarded

pub fn in_transaction(&self) -> bool

Returns whether a transaction is active.

pub fn prepare_commit(&mut self) -> Result<PreparedCommit<'_>>

Prepares the current transaction for a two-phase commit.

Returns a PreparedCommit that lets you inspect pending changes and attach metadata before finalizing. The mutable borrow prevents concurrent operations while the commit is pending.

If the PreparedCommit is dropped without calling commit() or abort(), the transaction is automatically rolled back.

Errors

Returns an error if no transaction is active.

Examples

use grafeo_engine::GrafeoDB;

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

session.begin_tx()?;
session.execute("INSERT (:Person {name: 'Alice'})")?;

let mut prepared = session.prepare_commit()?;
println!("Nodes written: {}", prepared.info().nodes_written);
prepared.set_metadata("audit_user", "admin");
prepared.commit()?;

pub fn set_auto_commit(&mut self, auto_commit: bool)

Sets auto-commit mode.

pub fn auto_commit(&self) -> bool

Returns whether auto-commit is enabled.

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

Creates a node directly (bypassing query execution).

This is a low-level API for testing and direct manipulation. If a transaction is active, the node will be versioned with the transaction ID.

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

Creates a node with properties.

If a transaction is active, the node will be versioned with the transaction ID.

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

Creates an edge between two nodes.

This is a low-level API for testing and direct manipulation. If a transaction is active, the edge will be versioned with the transaction ID.

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

Gets a node by ID directly, bypassing query planning.

This is the fastest way to retrieve a single node when you know its ID. Skips parsing, binding, optimization, and physical planning entirely.

Performance

• Time complexity: O(1) average case
• No lock contention (uses DashMap internally)
• ~20-30x faster than equivalent MATCH query

Example

let session = db.session();
let node_id = session.create_node(&["Person"]);

// Direct lookup - O(1), no query planning
let node = session.get_node(node_id);
assert!(node.is_some());

pub fn get_node_property(&self, id: NodeId, key: &str) -> Option<Value>

Gets a single property from a node by ID, bypassing query planning.

More efficient than get_node() when you only need one property, as it avoids loading the full node with all properties.

Performance

• Time complexity: O(1) average case
• No query planning overhead

Example

let session = db.session();
let id = session.create_node_with_props(&["Person"], [("name", "Alice".into())]);

// Direct property access - O(1)
let name = session.get_node_property(id, "name");
assert_eq!(name, Some(Value::String("Alice".into())));

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

Gets an edge by ID directly, bypassing query planning.

Performance

• Time complexity: O(1) average case
• No lock contention

pub fn get_neighbors_outgoing(&self, node: NodeId) -> Vec<(NodeId, EdgeId)>

Gets outgoing neighbors of a node directly, bypassing query planning.

Returns (neighbor_id, edge_id) pairs for all outgoing edges.

Performance

• Time complexity: O(degree) where degree is the number of outgoing edges
• Uses adjacency index for direct access
• ~10-20x faster than equivalent MATCH query

Example

let session = db.session();
let alice = session.create_node(&["Person"]);
let bob = session.create_node(&["Person"]);
session.create_edge(alice, bob, "KNOWS");

// Direct neighbor lookup - O(degree)
let neighbors = session.get_neighbors_outgoing(alice);
assert_eq!(neighbors.len(), 1);
assert_eq!(neighbors[0].0, bob);

pub fn get_neighbors_incoming(&self, node: NodeId) -> Vec<(NodeId, EdgeId)>

Gets incoming neighbors of a node directly, bypassing query planning.

Returns (neighbor_id, edge_id) pairs for all incoming edges.

Performance

• Time complexity: O(degree) where degree is the number of incoming edges
• Uses backward adjacency index for direct access

pub fn get_neighbors_outgoing_by_type( &self, node: NodeId, edge_type: &str, ) -> Vec<(NodeId, EdgeId)>

Gets outgoing neighbors filtered by edge type, bypassing query planning.

Example

let neighbors = session.get_neighbors_outgoing_by_type(alice, "KNOWS");

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

Checks if a node exists, bypassing query planning.

Performance

• Time complexity: O(1)
• Fastest existence check available

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

Checks if an edge exists, bypassing query planning.

pub fn get_degree(&self, node: NodeId) -> (usize, usize)

Gets the degree (number of edges) of a node.

Returns (outgoing_degree, incoming_degree).

pub fn get_nodes_batch(&self, ids: &[NodeId]) -> Vec<Option<Node>>

Batch lookup of multiple nodes by ID.

More efficient than calling get_node() in a loop because it amortizes overhead.

Performance

• Time complexity: O(n) where n is the number of IDs
• Better cache utilization than individual lookups