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

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_with_params( &self, query: &str, params: HashMap<String, Value>, ) -> Result<QueryResult, Error>

Executes a GQL query with parameters.

Errors

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

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

Executes a Cypher query.

Errors

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

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

Executes a Gremlin 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 some nodes first
session.create_node(&["Person"]);

// Query using Gremlin
let result = session.execute_gremlin("g.V().hasLabel('Person')")?;

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

Executes a Gremlin query with parameters.

Errors

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

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

Executes a GraphQL query against the LPG store.

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 some nodes first
session.create_node(&["User"]);

// Query using GraphQL
let result = session.execute_graphql("query { user { id name } }")?;

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

Executes a GraphQL query with parameters.

Errors

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

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

Executes a SQL/PGQ query (SQL:2023 GRAPH_TABLE).

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

let result = session.execute_sql(
    "SELECT * FROM GRAPH_TABLE (
        MATCH (n:Person)
        COLUMNS (n.name AS name)
    )"
)?;

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

Executes a SQL/PGQ query with parameters.

Errors

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

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

Executes a SPARQL query.

Errors

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

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

Executes a SPARQL 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, 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 the query fails.

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

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

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

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

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

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

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

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.