Struct Session 

pub struct Session<'g> { /* private fields */ }

Caller-owned executor session bound to one shared graph.

Implementations

impl<'g> Session<'g>

pub const fn new(graph: &'g SharedGraph) -> Self

Create a session without commit-principal bytes.

pub fn with_principal(graph: &'g SharedGraph, principal: Arc<[u8]>) -> Self

Create a session that forwards opaque principal bytes to commits.

pub fn with_cancellation_token(self, token: CancellationToken) -> Self

Attach a cooperative cancellation token to subsequent statements.

Cancellation is cooperative: statements observe the token at executor, built-in-procedure, and algorithm checkpoints. If a statement inside an explicit transaction returns Cancelled, the transaction enters the failed state until ROLLBACK.

pub fn with_deadline(self, deadline: Instant) -> Self

Attach an absolute per-statement deadline to subsequent statements.

The deadline is compared with Instant::now() at the same cooperative checkpoints as cancellation. Expiry returns Timeout; inside an explicit transaction that also marks the transaction failed until ROLLBACK.

pub fn with_max_nodes_scanned(self, max_nodes: usize) -> Self

Attach a deterministic per-statement node-scan budget.

Scan-heavy graph and procedure loops debit this budget at batch boundaries. Exceeding it returns GQLSTATUS 5GQL1 (program-limit-exceeded); inside an explicit transaction that also marks the transaction failed until ROLLBACK.

pub fn with_impl_defined_caps(self, caps: ImplDefinedCaps) -> Self

Set the implementation-defined planning/runtime caps for subsequent statements (ISO IL013/IL015/IL018 limit surfaces — e.g. max_quantifier, set-op / GROUP BY key caps, optimizer-iteration, string/byte-string concat length, path-length, and list-cardinality bounds).

The caps are baked into every plan lowered for this session, so they are honored by both the plan-time variable-length quantifier gate and the runtime/optimizer cap checks. Defaults to ImplDefinedCaps::DEFAULT.

pub fn with_row_cap(self, max_rows: usize) -> Self

Attach an outermost result-row cap to subsequent statements.

The cap is enforced only at the statement output boundary. Intermediate rows produced by scans, joins, FOR, or other pipeline operators do not count against it. Exceeding the cap returns RowCapExceeded; inside an explicit transaction that marks the transaction failed until ROLLBACK.

pub fn with_warning_sink(self, sink: impl WarningSink + 'static) -> Self

Attach an opt-in runtime warning sink to subsequent statements.

Sessions without a sink silently discard warnings. The sink currently receives ISO warning records such as 01G11 for aggregate NULL elimination and 01N01 for relaxed validation-mode writes; see docs/embedding-guide.md for an embedder-side collection example.

pub fn bind_parameter(&mut self, name: DbString, value: Value) -> Option<Value>

Bind or replace a session-local query parameter.

Parameters are named without the leading $ and are resolved by $name references during statement execution. Binding is an upsert: rebinding a name replaces the prior value and affects subsequent statements only. Parameters are session-level metadata, so transaction boundaries and Self::abort preserve the map. Parameters not referenced by a statement are ignored. Session plan-cache keys remain source-only; parameter values and runtime types are checked during each execution.

Runtime positions that require a specific type validate strictly; for example, LIMIT $n accepts only non-negative integer values and returns ExecutorError::InvalidParameterType for mismatches.

If name previously held a table binding, the table is replaced and None is returned. Use Self::bind_table_parameter when callers need table-aware replacement information.

pub fn bind_table_parameter( &mut self, name: DbString, table: BindingTable, ) -> Option<SessionParameterValue>

Bind or replace a session-local query parameter with a binding table.

The table is stored at session scope and materialized into a fresh request-scoped table reference for each statement execution.

pub fn clear_parameter(&mut self, name: &DbString) -> Option<Value>

Remove one session-local query parameter and return its prior scalar value.

If name held a table binding, the table is removed and None is returned.

pub fn clear_parameters(&mut self)

Remove all session-local query parameters.

pub const fn is_closed(&self) -> bool

True when SESSION CLOSE has terminated this session.

pub const fn without_index_selection(self) -> Self

Disable optimizer index selection; all scans fall back to ScanAccess::Linear.

With index selection off, execute_source skips the optimizer entirely and lowers the byte-identical Linear plan (and EXPLAIN output) of pre-optimizer-wiring HEAD. This is the escape hatch for committed perf-baseline reproduction and access-path debugging.

pub const fn with_index_selection(self) -> Self

(Re-)enable optimizer index selection (the default).

When enabled, execute_source builds a snapshot-pinned LiveIndexCatalog per cache-miss statement and runs the optimizer so label / typed / composite index access paths are selected. Linear remains the always-correct fallback inside every rule, so results are byte-identical to the disabled path.

pub fn with_plan_cache(self, capacity: NonZeroUsize) -> Self

Enable this session’s source-string plan cache with the given capacity.

The cache is Session-local and invalidates entries when the backing graph’s schema-version epoch changes.

pub fn with_shared_plan_cache(self, cache: Arc<SharedPlanCache>) -> Self

Enable this session’s shared non-CALL source-string plan cache.

Embedders should pass one shared cache per graph so short-lived sessions can reuse read and write plans across requests. The cache key includes graph ID, schema-version epoch, procedure-registry version, source text, implementation-defined caps, and optimizer index-selection mode.

pub fn with_call_plan_cache(self, cache: Arc<CallPlanCache>) -> Self

Enable this session’s shared procedure-CALL plan cache.

Embedders should pass one shared cache per graph so short-lived sessions can reuse procedure-call plans across requests. The cache key includes the graph ID, schema-version epoch, and procedure-registry version.

pub fn plan_cache_stats(&self) -> Option<PlanCacheStats>

Return this session’s plan-cache counters, if caching is enabled.

pub fn clear_plan_cache(&mut self)

Clear this session’s cached plans without resetting counters.

pub const fn has_active_txn(&self) -> bool

Return true when the session owns an explicit write transaction.

pub const fn is_aborted(&self) -> bool

Return true when the active explicit transaction is aborted.

pub fn start_transaction(&mut self) -> Result<(), ExecutorError>

Open an explicit write transaction.

Subsequent non-control statements executed through this session run inside the transaction until Self::commit_transaction or Self::rollback_transaction closes it.

Errors

Returns ExecutorError::TransactionAlreadyActive when this session already owns an explicit transaction.

pub fn commit_transaction( &mut self, ) -> Result<TransactionOutcome, ExecutorError>

Commit the open explicit transaction.

Errors

Returns ExecutorError::NoActiveTransaction when no explicit transaction is open, ExecutorError::InFailedTransaction when the transaction has been aborted by a failed statement, or ExecutorError::GraphMutation when the graph commit is rejected.

pub fn rollback_transaction(&mut self) -> Result<RollbackOutcome, ExecutorError>

Roll back the open explicit transaction.

Errors

Returns ExecutorError::NoActiveTransaction when no explicit transaction is open.

pub fn flush(&self) -> Result<Option<u64>, ExecutorError>

Flush every commit-critical durable provider registered on this graph.

Returns the highest durable sequence reported by providers, or None when the graph has no durable providers.

Errors

Returns ExecutorError::Flush when any provider-owned flush fails.

pub fn abort(&mut self)

Roll back and clear the explicit transaction, when one is active.

impl Session<'_>

pub fn execute_source( &mut self, source: &str, registry: &dyn ProcedureRegistry, ) -> Result<StatementOutput, ExecutorError>

Parse, plan, and execute one source-string statement through this session.

When the session has a plan cache, source strings whose cached plan was prepared against the current graph schema version skip parse, analyze, and plan. Short-lived sessions can additionally use the opt-in shared non-CALL source-plan cache, keyed by graph ID, schema version, registry version, source text, caps, and optimizer mode. Procedure-call-rooted statements use the separate opt-in shared CALL plan cache, keyed by graph ID, schema version, registry version, and formatter-canonical source. Embedded in-pipeline CALL remains uncached. If an active explicit transaction has uncommitted schema changes, both caches bypass lookup and insert so analysis sees transaction-local schema.