cypher

func (*Engine) BeginReadTx ¶ added in v0.4.0

func (e *Engine) BeginReadTx(ctx context.Context) (*ExplicitTx, error)

BeginReadTx opens a read-only explicit transaction bound to ctx. Unlike Engine.BeginTx, it acquires NO writer serialisation, opens NO WAL transaction, and does NOT hold the visibility barrier: a read-only transaction has no durability obligation and never serialises behind, or blocks, a concurrent writer. The caller MUST still finish the returned handle with exactly one ExplicitTx.Commit or ExplicitTx.Rollback; on a read-only handle both are teardown-only no-ops (they release nothing, since nothing was acquired).

Every statement run through ExplicitTx.Exec on the handle:

• is rejected with ErrWriteInReadOnlyTx BEFORE execution if it contains a writing clause (QueryHasWritingClause) or is DDL (ir.IsDDL) — the rejection is what keeps the lock-free read path safe, since a write would otherwise run with no writer lock, no barrier, and no WAL; and
• otherwise runs through the engine's concurrent read path (Engine.Run), taking its OWN per-statement snapshot (lpg.Graph.BeginRead). Reads therefore observe READ-COMMITTED isolation across the statements of the transaction (each RUN sees the latest committed state, matching Neo4j's default), and run fully in parallel with other readers and writers.

If ctx is already cancelled or its deadline has elapsed, BeginReadTx returns promptly with an error wrapping the context error (matchable via errors.Is against context.Canceled / context.DeadlineExceeded).

func (*Engine) BeginTx ¶ added in v0.2.0

func (e *Engine) BeginTx(ctx context.Context) (*ExplicitTx, error)

BeginTx opens an explicit, multi-statement transaction bound to ctx. It acquires NOTHING: no writer serialisation, no visibility barrier, no lock of any kind. Concurrency control is MVCC alone. The caller MUST finish the returned handle with exactly one ExplicitTx.Commit or ExplicitTx.Rollback.

This doc used to read "but it does take the graph's visibility barrier exclusively, which until rmp #2305 retires it still blocks concurrent writers for the transaction's lifetime". THAT IS FALSE and has been since rmp #2305 did retire it — the sentence outlived the change it was describing, and it contradicted both this file's own header ("What serialises an explicit transaction: NOTHING") and the [ExplicitTx.view] field doc. What keeps this handle's reads stable is the transaction id it stamps its versions with, not exclusion (rmp #2345).

ctx bounds every statement executed through the handle. Pass the connection context (optionally narrowed with a transaction timeout) so that a cancelled connection, a server shutdown, or an elapsed timeout interrupts an in-flight statement. It no longer guards against a serialisation being held forever — there is none to hold — but it still bounds a statement queued behind a DDL.

ctx also bounds the ACQUISITION, not only the statements that follow. BeginTx takes three things in order — the writer serialisation, the WAL transaction, and the visibility barrier — and every one of them honours ctx, so a caller whose deadline elapses while queued behind another writer or behind an in-flight reader gets the context error rather than a transaction it is no longer entitled to. When that happens NOTHING is left held and no handle is returned. Before rmp #2174 two of the three acquisitions ignored ctx entirely: the round-3 audit measured a 50 ms deadline returning after 601 ms, and after 11.60 s under load, both times with err=nil and a live transaction, which also made the Bolt tx_timeout inert at BEGIN.

If ctx is already cancelled or its deadline has elapsed, BeginTx returns promptly without acquiring any lock, with an error wrapping the context error (matchable via errors.Is against context.Canceled / context.DeadlineExceeded).

The error is returned within the deadline plus a small, bounded margin: the margin is one scheduling hop, not the holder's remaining tenure. See mvcc.Gate.StrongLockCtx and the acquireCtx helper beside it for why a queued lock acquisition cannot simply be abandoned and what is done instead.

See exectx.go for the full transaction and concurrency contract, including the isolation scope: concurrent readers do NOT block while this transaction is open, and observe the state before it began until it commits (task #1412, strengthened by rmp #2290).

func (*Engine) ClearPlanCache ¶

func (e *Engine) ClearPlanCache()

ClearPlanCache drops every cached plan and increments the cypher.plan_cache.invalidations counter exactly once. It is the operator-facing invalidation hook installed on every DDL operator (CREATE/DROP INDEX, CREATE/DROP CONSTRAINT) — successful schema mutations call it so that subsequent queries re-plan against the new index / constraint topology rather than reusing stale plans built before the schema changed.

ClearPlanCache is also safe to invoke directly as a user-facing manual reset (e.g. from operational tooling after an out-of-band index swap on the underlying graph).

ClearPlanCache is idempotent and safe for concurrent use; each call emits exactly one invalidations counter increment regardless of the cache's prior size.

func (*Engine) Close ¶ added in v0.11.0

func (e *Engine) Close() error

Close releases the background resources the engine's graph owns — currently the MVCC vacuum goroutine — and waits for them to terminate. It is the io.Closer the engine's owner calls at shutdown.

Why the engine has this at all (rmp #2308) ¶

The graph owns a goroutine now: reclamation moved off the commit path onto a demand-started background vacuum. That vacuum exits on its own once there is nothing left to reclaim, so an owner that never closes leaks nothing — but an owner that wants the goroutine gone at a KNOWN instant had no way to say so, because the engine holds the only reference to its graph. `internal/sim`'s metrics oracle found the gap immediately: it certifies that a workload returns to its exact goroutine baseline with zero slack, and it had no teardown to call.

It closes the GRAPH and nothing else. The engine's own state — the plan cache, the registries, the statistics collector — spawns no goroutine and needs no teardown, and the durable store's pieces belong to [store.DB.Close], which the embedder owns separately.

Idempotent and safe to call concurrently with any other operation. The engine stays usable afterwards; what stops is reclamation, so an owner that closes and then keeps writing accumulates versions with nothing to release them.

func (*Engine) CloseCtx ¶ added in v0.11.0

func (e *Engine) CloseCtx(ctx context.Context) error

CloseCtx is Engine.Close with a deadline on the join; see lpg.Graph.CloseCtx for what the context does and does not bound.

func (*Engine) ConstraintSpecsForSnapshot ¶ added in v0.2.0

func (e *Engine) ConstraintSpecsForSnapshot() []snapshot.ConstraintSpec

ConstraintSpecsForSnapshot converts the engine's current constraint set into the store/snapshot.ConstraintSpec slice that store/snapshot.WriteSnapshotFullWithConstraints (and its mapper-codec variant) persists into a snapshot's constraints.bin component. A checkpointer calls e.ConstraintSpecsForSnapshot() and hands the result to the writer so a checkpoint + WAL truncate does not lose constraints.

func (*Engine) Constraints ¶ added in v0.2.0

func (e *Engine) Constraints() []ConstraintDef

Constraints returns a structured snapshot of every schema constraint currently registered on the engine, in deterministic order (UNIQUE before NOT NULL, then by label, property, name). It is the source a checkpointer passes to store/snapshot.WriteSnapshotFullWithConstraints (via [ConstraintSpecsForSnapshot]) so the constraint set survives a checkpoint that truncates the WAL prefix which first declared a constraint (audit gap H1, the checkpoint-survival half).

Constraints is safe for concurrent use.

func (*Engine) CountStoreCells ¶ added in v0.10.0

func (e *Engine) CountStoreCells() int

CountStoreCells reports the number of distinct live relationship count-store cells the engine currently holds (design §2.3): the count-store's footprint, bounded by observed schema cardinality rather than by |V| or |E|. It is an observability accessor for the size indicator the metrics [Backend] cannot express as a gauge (task #2087); it returns 0 for an engine without a count store. Safe for concurrent use — it reads the store under its own shard read locks.

func (*Engine) Explain ¶

func (e *Engine) Explain(query string, params map[string]expr.Value) (s string, err error)

Explain returns a textual representation of the plan that executes query with the given params. No rows are produced and the graph is not modified.

For a READING statement the rendering is the PHYSICAL plan: the operator tree the builder actually produced, walked node by node, with each node named after its concrete operator type. Hash-join substitution, columnar and parallel tier engagement and the chosen access path are therefore visible, and cannot disagree with what runs — a HashJoin is named HashJoin because it IS one.

Before rmp #2222 this rendered the logical IR instead, and was wrong in BOTH directions: it reported NodeByIndexSeek where a label scan ran, and printed CartesianProduct for

MATCH (a:P), (b:P) WHERE a.age = b.age RETURN count(*)

which the runtime counter proves executes as a HashJoin — showing a reader O(n·m) where O(n+m) runs.

For a WRITING statement it renders the logical plan and says so on the first line. A write's physical tree cannot be built without a live mutator (the operators bind to an open transaction), so there is nothing faithful to walk outside one; the honest label is preferable to silently returning a different kind of plan. Use Engine.Profile on a read to inspect a physical tree with measurements.

package main

import (
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher"
	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
)

func main() {
	g := lpg.New[string, float64](adjlist.Config{})
	eng := cypher.NewEngine(g)

	plan, err := eng.Explain("MATCH (n:Person) RETURN n", nil)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Print(plan)
}

Output:
Project
└─ NodeByLabelScan [Person]

func (*Engine) ExplainLogical ¶ added in v0.11.0

func (e *Engine) ExplainLogical(query string, params map[string]expr.Value) (s string, err error)

ExplainLogical returns the LOGICAL plan for query, annotated with the index seeks and the count-store-gated reorderings the read path would apply, and with each operator's estimated row count.

It is the companion to Engine.Explain, not a lesser version of it, and the two answer different questions:

• Explain answers "what runs?" — the physical operator tree, named after the operators themselves, so it cannot misreport the access path, the join, or the tier.
• ExplainLogical answers "what did the planner think?" — the logical shape plus the CARDINALITY ESTIMATES that drove the physical choices. Those estimates belong to the logical nodes and have no counterpart on a built operator, so they are only visible here.

Reach for this one when an estimate looks wrong (a plan chosen on a bad guess); reach for Explain when you need to know what actually executes.

package main

import (
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher"
	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
)

func main() {
	g := lpg.New[string, float64](adjlist.Config{})
	eng := cypher.NewEngine(g)

	plan, err := eng.ExplainLogical("MATCH (n:Person) RETURN n", nil)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Print(plan)
}

Output:
ProduceResults
└─ Projection
   └─ NodeByLabelScan [n:Person] (est. rows=0, exact)

func (*Engine) IndexSpecsForSnapshot ¶ added in v0.6.0

func (e *Engine) IndexSpecsForSnapshot() []snapshot.IndexDefSpec

IndexSpecsForSnapshot converts the engine's current USER secondary-index definitions into the store/snapshot.IndexDefSpec slice that store/snapshot.WriteSnapshotFullWithConstraintsAndIndexDefs (and its mapper-codec variant) persists into a snapshot's indexdefs.bin component. A checkpointer calls e.IndexSpecsForSnapshot() and hands the result to the writer so a checkpoint + WAL truncate does not lose index definitions (#1755).

The set is sourced from the engine's own index-def registry (indexDefReg), not reconstructed from the index.Manager: the registry holds every user index def — including one whose backing subscriber is unbound after a recovery empty-graph fallback, which a Manager BoundNode() probe would miss — and never holds the internal numeric companion or a UNIQUE constraint backing index, so only the definitions recovery is expected to surface in res.Indexes are persisted.

func (*Engine) ListIndexes ¶ added in v0.3.0

func (e *Engine) ListIndexes() []string

ListIndexes returns the names of every secondary index currently registered on the engine, in unspecified order. The list reflects the live in-memory state: it includes every index created via CREATE INDEX and excludes any dropped via DROP INDEX. It is safe for concurrent use.

This is a thin wrapper over index.Manager.ListIndexes: the test suite and embedders that need to inspect the engine's schema without importing the graph/index package can use this method directly.

func (*Engine) NewSession ¶ added in v0.11.0

func (e *Engine) NewSession() *Session

NewSession returns a Session over this engine.

It is cheap — no locks, no registration, no resources to release — so a server may mint one per connection and discard it when the connection ends.

Safe for concurrent use.

func (*Engine) Procs ¶

func (e *Engine) Procs() *procs.Registry

Procs returns the engine's procedure registry so callers can register custom procedures alongside the built-in db.* set. The returned *procs.Registry is the live, owning registry — mutations are observed immediately by every subsequent CALL <ns>.<name>() in any query parsed by this engine.

Returned registry is non-nil. Safe for concurrent use; see procs.Registry for the concurrency contract.

func (*Engine) Profile ¶ added in v0.11.0

func (e *Engine) Profile(ctx context.Context, query string, params map[string]expr.Value) (s string, err error)

Profile executes query with the given params and returns the PHYSICAL plan annotated with each operator's emitted row count and the wall-clock time attributed to it — GoGraph's equivalent of the PROFILE both incumbents expose (Neo4j adds db-hits, Memgraph relative time).

The query really runs: rows are produced and discarded, so Profile is for a reading statement only and returns an error for a writing one rather than performing its writes as a side effect of a diagnostic.

Times are INCLUSIVE of an operator's children, because a pipelined operator's Next pulls from them. Subtract a node's children to obtain its exclusive cost — the same arithmetic a reader of Neo4j's PROFILE performs.

Profiling is off unless this method is called: the instrumentation is a wrapper installed by the builder, so an ordinary Engine.Run executes code identical to a build in which profiling does not exist (rmp #2222 AC 3).

func (*Engine) RefreshStatistics ¶ added in v0.10.0

func (e *Engine) RefreshStatistics(ctx context.Context) error

RefreshStatistics rebuilds the planner statistics for every (label, property) pair currently present on a live node, publishing a fresh snapshot atomically. It is the explicit maintenance entry point: statistics are best-effort and never maintained by a background goroutine, so a caller (a maintenance task, a scheduled job, or a test) drives the rebuild.

The scan resolves against one pinned snapshot, so it observes a consistent instant and does not block concurrent writers (which serialise elsewhere). It takes no barrier — see the note on the internal builder below for why wrapping it in the old lpg.Graph.View would not have given the property it claimed.

Statistics built here ship INERT: no query-path consumer reads them yet (#2099 is the intended consumer), so a rebuild changes no plan. It honours context cancellation, returning ctx.Err() without publishing a partial snapshot.

func (*Engine) RefreshStatisticsLocked ¶ added in v0.11.0

func (e *Engine) RefreshStatisticsLocked(ctx context.Context) error

RefreshStatisticsLocked is Engine.RefreshStatistics for a caller that ALREADY holds the visibility barrier — specifically db.stats.refresh(), which runs inside query execution (#2196).

It exists because visMu is a non-re-entrant sync.RWMutex: taking it again from a goroutine already inside Graph.View would DEADLOCK the engine. The re-entrancy guard turns that into a panic, but only in a debug or race build — a production binary would hang. So the barrier-taking and barrier-free entry points must be distinct, and the caller has to pick correctly.

Correctness is unchanged: the scan only reads, and the caller's read barrier already pins the consistent snapshot it needs.

func (*Engine) ResultRowCap ¶ added in v0.2.0

func (e *Engine) ResultRowCap() int64

ResultRowCap reports the effective per-query result-row cap this Engine enforces, after EngineOptions.MaxResultRows has been resolved by the constructor:

• A positive value is the active cap. A single Engine.Run or Engine.RunInTx call materialising more than this many rows trips ErrResultRowsExceeded during the in-barrier drain, before the surplus rows are ever handed to the caller.
• Zero means the cap is disabled (the engine was built with MaxResultRowsUnlimited). Such an engine offers no upper bound on the rows a single query materialises, so an embedder exposing it to untrusted callers — for example behind the Bolt server — should bound memory by another means.

The accessor lets an embedder that receives a pre-built Engine observe its memory-safety posture without reaching into unexported state; the Bolt server uses it to warn when handed an uncapped engine.

func (*Engine) Run ¶

func (e *Engine) Run(ctx context.Context, query string, params map[string]expr.Value) (*Result, error)

Run parses, analyses, plans, and executes query, returning a materialised Result. The query is built and drained at ONE read instant — a snapshot opened here and released when the statement finishes — so it observes a consistent, partial-transaction-free view. DDL statements take a dedicated fast path. Parameters are bound from params and type-checked against the plan before execution.

If ctx is already cancelled or its deadline has elapsed when Run is called, it returns promptly — before any parse, plan, or execution work — with an error wrapping the context error (matchable via errors.Is against context.Canceled / context.DeadlineExceeded).

A recoverable panic raised while planning or executing the query is intercepted and returned as an error wrapping ErrInternalPanic; it never unwinds past this method to crash the embedding process.

package main

import (
	"context"
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher"
	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
)

func main() {
	g := lpg.New[string, float64](adjlist.Config{})
	for _, key := range []string{"a", "b", "c"} {
		if err := g.AddNode(key); err != nil {
			fmt.Println("error:", err)
			return
		}
		if err := g.SetNodeLabel(key, "Person"); err != nil {
			fmt.Println("error:", err)
			return
		}
	}

	eng := cypher.NewEngine(g)
	res, err := eng.Run(context.Background(), "MATCH (n:Person) RETURN count(n) AS people", nil)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	defer res.Close()

	for res.Next() {
		rec := res.Record()
		fmt.Println("people:", rec["people"])
	}
}

Output:
people: 3

func (*Engine) RunAny ¶

func (e *Engine) RunAny(ctx context.Context, query string, params map[string]any) (*Result, error)

RunAny executes query with params expressed as map[string]any, automatically converting Go native types to expr.Value. See BindParams for the supported conversions.

RunAny auto-detects whether the query contains writing clauses (CREATE, MERGE, SET, REMOVE, DELETE, DETACH DELETE) and routes through Engine.RunInTx when so, or Engine.Run otherwise. Callers that need an explicit choice should invoke Engine.Run / Engine.RunInTx directly.

package main

import (
	"context"
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher"
	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
)

func main() {
	g := lpg.New[string, float64](adjlist.Config{})
	eng := cypher.NewEngine(g)

	if _, err := drainTxAny(eng,
		`CREATE (:Account {owner: "alice"}), (:Account {owner: "bob"})`); err != nil {
		fmt.Println("seed error:", err)
		return
	}

	// $owner is supplied as a Go string in the params map.
	res, err := eng.RunAny(context.Background(),
		`MATCH (a:Account) WHERE a.owner = $owner RETURN a.owner AS owner`,
		map[string]any{"owner": "bob"},
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	defer res.Close()
	for res.Next() {
		fmt.Println("owner:", res.Record()["owner"])
	}
}

// drainTxAny runs a write query in a transaction, draining and closing the
// result. It is a tiny helper shared by the parameter example above.
func drainTxAny(eng *cypher.Engine, query string) (int, error) {
	res, err := eng.RunInTxAny(context.Background(), query, nil)
	if err != nil {
		return 0, err
	}
	defer res.Close()
	var rows int
	for res.Next() {
		rows++
	}
	return rows, res.Err()
}

Output:
owner: "bob"

func (*Engine) RunInTx ¶

func (e *Engine) RunInTx(ctx context.Context, query string, params map[string]expr.Value) (res *Result, err error)

RunInTx executes a write query against the engine's graph and returns a streaming Result. Unlike [Run], RunInTx inspects the IR plan for write operators; when any write operator is present it builds a mutator adapter so that write operators can modify the graph.

RunInTx is atomic: mutations apply eagerly to the live graph as the pipeline runs, with the inverse of each recorded into an in-memory undo log (see exectx.go's "Atomicity and the undo log" section for the shared mechanism). If the pipeline drain returns an error, a commit-time NOT NULL constraint is violated, the WAL fsync fails, or the pipeline panics, the whole statement rolls back: the undo log replays in reverse inside the write visibility barrier, restoring the graph to its pre-statement state, before the barrier is ever released — so a concurrent snapshot reader can never observe a partially-applied write. Only once every check passes does the WAL fsync (durability before visibility), after which the undo log is discarded.

RunInTx is safe for concurrent use (each call creates an independent operator tree), subject to the per-operator-tree single-goroutine constraint on write queries.

If ctx is already cancelled or its deadline has elapsed when RunInTx is called, it returns promptly — before any parse, plan, or txn.Store.Begin work — with an error wrapping the context error (matchable via errors.Is against context.Canceled / context.DeadlineExceeded).

package main

import (
	"context"
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher"
	"github.com/FlavioCFOliveira/GoGraph/graph/adjlist"
	"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
)

func main() {
	g := lpg.New[string, float64](adjlist.Config{})
	eng := cypher.NewEngine(g)

	// Write: CREATE two labelled nodes atomically.
	write, err := eng.RunInTx(context.Background(),
		`CREATE (:Account {owner: "alice"}), (:Account {owner: "bob"})`, nil)
	if err != nil {
		fmt.Println("write error:", err)
		return
	}
	for write.Next() { //nolint:revive // a write query streams no result rows; drain then close
	}
	if err := write.Err(); err != nil {
		fmt.Println("write error:", err)
		return
	}
	write.Close()

	// Read-back: the committed nodes are visible to a subsequent query.
	read, err := eng.Run(context.Background(), "MATCH (a:Account) RETURN count(a) AS accounts", nil)
	if err != nil {
		fmt.Println("read error:", err)
		return
	}
	defer read.Close()
	for read.Next() {
		fmt.Println("accounts:", read.Record()["accounts"])
	}
}

Output:
accounts: 2

func (*Engine) RunInTxAny ¶

func (e *Engine) RunInTxAny(ctx context.Context, query string, params map[string]any) (*Result, error)

RunInTxAny executes a write query with params expressed as map[string]any, automatically converting Go native types to expr.Value. See BindParams.

func (*Engine) StatsTrackedPairs ¶ added in v0.10.0

func (e *Engine) StatsTrackedPairs() int

StatsTrackedPairs reports the number of distinct (label, property) pairs the engine currently holds planner statistics for (task #2102): the statistics footprint, bounded by observed schema cardinality rather than by |V|. It is an observability accessor for the size indicator the metrics [Backend] cannot express as a gauge (mirroring Engine.CountStoreCells); it returns 0 for an engine that never refreshed statistics (the lazy collector is unallocated). Safe for concurrent use — it reads the collector's atomic-pointer snapshot.

func (*ErrStatementPipeline) Error ¶ added in v0.3.0

func (e *ErrStatementPipeline) Error() string

Error implements the error interface.

func (*ErrStatementPipeline) Unwrap ¶ added in v0.3.0

func (e *ErrStatementPipeline) Unwrap() error

Unwrap returns the underlying pipeline error so errors.Is and errors.As traversal works correctly.

func (*ExplicitTx) Commit ¶ added in v0.2.0

func (tx *ExplicitTx) Commit() (err error)

Commit makes the whole transaction durable and visible, then releases the writer serialisation. On a WAL-backed engine the WAL is fsynced exactly ONCE for every statement's accumulated writes (durable-then-visible, #1281) and the secondary-index buffer is committed; on a store-less engine the writes are already visible and Commit simply finalises the index buffer. The accumulated undo log is discarded. After Commit the handle is finished.

Commit runs the finalisation inside the visibility barrier so that, on a WAL-backed engine, the fsync happens-before the index commit and no concurrent reader can observe a committed-but-not-durable state. If the WAL fsync fails, the transaction is rolled back instead (in-memory undo replayed, index and WAL rolled back) and the fsync error is returned wrapping it: a transaction whose durability could not be guaranteed is reported as failed, never acknowledged.

Commit returns ErrTxFinished if the transaction was already committed or rolled back, and ErrTxPoisoned if a prior ExplicitTx.Exec call returned an ErrStatementPipeline error (call ExplicitTx.Rollback instead).

func (*ExplicitTx) Exec ¶ added in v0.2.0

func (tx *ExplicitTx) Exec(query string, params map[string]expr.Value) (res *Result, err error)

Exec runs one statement inside the open transaction and returns a materialised Result. The statement's writes are applied eagerly and accumulate in the transaction; they are NOT made durable or finalised here — that happens once, at ExplicitTx.Commit. Closing the returned Result releases only its own iterator state; it never commits or rolls the transaction back.

A DDL statement (CREATE/DROP INDEX or CONSTRAINT) is rejected: schema changes are not transactional in this engine and must be issued outside an explicit transaction (autocommit). A read-only statement is permitted and simply observes the transaction's current state.

A statement that raises a runtime error is returned directly as the error return of Exec. The per-statement writes remain in the accumulated undo log, so the caller (the Bolt session) can roll the whole transaction back via ExplicitTx.Rollback after inspecting the error. A statement that panics is converted to an error wrapping ErrInternalPanic; the in-memory writes of the whole transaction are rolled back inside the visibility barrier, the writer serialisation is released, and the handle is marked finished (a subsequent Rollback is then a no-op).

Exec returns ErrTxFinished if the transaction has already been committed or rolled back, or if ctx (the BeginTx context) is already done.

func (*ExplicitTx) ExecAny ¶ added in v0.2.0

func (tx *ExplicitTx) ExecAny(query string, params map[string]any) (*Result, error)

ExecAny is the ExplicitTx.Exec variant taking params as map[string]any, converting Go native values to expr.Value via BindParams.

func (*ExplicitTx) Rollback ¶ added in v0.2.0

func (tx *ExplicitTx) Rollback() (err error)

Rollback unwinds the whole transaction: it replays the accumulated in-memory undo log in reverse inside the visibility barrier (restoring the graph to its pre-transaction state), rolls back the secondary-index buffer, rolls back the WAL transaction (WAL-backed only, so a fresh recovery observes none of the writes), and releases the writer serialisation. After Rollback the handle is finished.

Rollback is best-effort and total: it always releases the writer serialisation and finishes the handle, even if an inverse operation fails. It returns ErrUndoFailed (wrapped) when the in-memory undo replay itself failed — the graph may then be inconsistent until reopen, which a WAL-backed engine reconciles to the durable state and a store-less engine cannot. It returns ErrTxFinished if the transaction was already committed or rolled back.

func (*Result) Close ¶

func (r *Result) Close() error

Close releases all resources held by the result set.

For a write Result created by Engine.RunInTx, the buffered index changes and the WAL transaction were already committed (durably, fsync first) or rolled back inside the write query's lpg.Graph.ApplyAtomically window (commitUnderBarrier, #1281). Close therefore only releases the underlying ResultSet for such a result — the durability and visibility decision is made and finalised before RunInTx returns, never deferred to Close. The commit/rollback branches below survive only as a fallback for a Result that reached Close without that in-barrier finalisation (e.g. one that was never materialised), preserving the historical contract for that path.

Close is idempotent: a second invocation returns nil without re-entering the underlying ResultSet. The finalizer safety net also relies on this idempotence — see the type-level documentation.

func (*Result) Columns ¶

func (r *Result) Columns() []string

Columns returns the ordered list of output column names.

func (*Result) Counters ¶ added in v0.11.0

func (r *Result) Counters() *exec.QueryCounters

Counters returns the write effects this statement actually applied — nodes and relationships created and deleted, properties set and removed, labels added and removed, and index and constraint DDL (#2212).

It returns nil for a read-only statement. That is a meaningful distinction, not an absence: nil means the statement had no write surface at all, whereas a non-nil all-zero result means writes were attempted and changed nothing — the difference between a MATCH and a MERGE that matched.

The counts reflect what was APPLIED, so a re-intern of an existing node is not a creation, removing an absent property counts nothing, and a statement that failed or rolled back never produces a Result to report from. The nodes and relationships counters are incremented at the same call sites as the graph-scoped side-effect counters the openCypher TCK comparator verifies, so the two cannot drift.

The returned pointer is owned by the Result; treat it as read-only.

func (*Result) Err ¶

func (r *Result) Err() error

Err returns the first error encountered during iteration, or nil.

When a bounded-resource guard truncated the result during materialisation, Err returns the guard's sentinel: ErrResultRowsExceeded when the row cap (EngineOptions.MaxResultRows) was hit, or ErrResultBytesExceeded when the aggregate-byte budget (EngineOptions.MaxResultBytes) was hit. Either is matchable with errors.Is. For an autocommit write statement a tripped guard is a failed statement: its eager mutations were rolled back atomically inside the barrier and nothing was made durable (#1338).

When the query was a write that failed and the subsequent in-memory undo replay ALSO failed (an inverse panicked, ErrUndoFailed), Err returns the pipeline error wrapped together with ErrUndoFailed so the caller learns both that the statement failed and that the rollback could not fully restore the graph; either is matchable with errors.Is.

When the in-barrier WAL fsync failed (#1281), Err returns that error. RunInTx already surfaces it directly and does not hand such a Result back, so this is a defensive backstop for any caller that nonetheless holds the Result: it reports that the write did not become durable (and was therefore rolled back).

func (*Result) IsClosed ¶

func (r *Result) IsClosed() bool

IsClosed reports whether Close has been called on this Result.

func (*Result) Next ¶

func (r *Result) Next() bool

Next advances to the next result row. Returns true when a row is available. If EngineOptions.MaxResultRows is set and the limit is reached, Next sets the result's error to ErrResultRowsExceeded and returns false.

func (*Result) Notifications ¶ added in v0.3.1

func (r *Result) Notifications() []Notification

Notifications returns the out-of-band advisories attached to this result by the planner — for example a Cartesian-product warning when the query builds a cross product between disconnected patterns (#1483). Notifications are NOT result rows and never affect iteration; a caller (or a Bolt driver via the SUCCESS "notifications" metadata) may surface them to warn the user. The returned slice is nil when the query produced no notifications.

func (*Result) Record ¶

func (r *Result) Record() exec.Record

Record returns the current row as a map from column name to value. Must only be called after a successful [Next].

For a materialised result the map is built lazily from the column-oriented backing store into a single reused scratch map (#1499): the returned map is owned by the Result and is overwritten on the next Record call, mirroring the streaming exec.ResultSet.Record contract. Callers that need to retain a row must copy it. Use Result.RowAt/Result.ValueAt to read values positionally without materialising the map.

func (*Result) RowAt ¶ added in v0.3.1

func (r *Result) RowAt(i int) []expr.Value

RowAt returns the materialised row at index i as a positional slice of values whose indices correspond to Result.Columns. The returned slice aliases the Result's backing store and must not be mutated or retained beyond the Result's lifetime. It is only valid for a materialised result (every read query and every RunInTx result is materialised under the visibility barrier); it panics if i is out of range. This is the allocation-free row accessor: it never builds the per-row map that Result.Record returns.

func (*Result) ValueAt ¶ added in v0.3.1

func (r *Result) ValueAt(col int) expr.Value

ValueAt returns the value at column index col of the current row. It must only be called after a successful [Next], and is the allocation-free positional accessor used by hot consumers (the Bolt PULL path) that read every column by index and discard the row. Out-of-range indices return nil.

It serves BOTH a materialised result and a streaming one. That distinction used to matter and silently produced wrong answers (#2215): SHOW INDEXES and SHOW CONSTRAINTS build a streaming result over static rows ([Engine.newShowResult]), while this accessor read only the materialised backing store — whose matRowLen is zero for a streaming result, so every column came back as a bare nil. bolt/server reads each column with ValueAt on the premise that an engine result is always materialised, so `SHOW INDEXES` over Bolt answered with a well-formed row of nulls and no error: fail-silent, which the failure-handling rule forbids outright. Record() was unaffected, which is why the in-tree tests missed it.

The streaming branch is served from the ResultSet's positional row, so it costs no allocation and no map lookup, and it fixes the whole class rather than the one instance — any future non-materialised plan is now safe here.

func (*Session) BeginReadTx ¶ added in v0.11.0

func (s *Session) BeginReadTx(ctx context.Context) (*ExplicitTx, error)

BeginReadTx opens a read-only transaction bound to this session, pinned to an instant at or after this session's last commit.

func (*Session) BeginTx ¶ added in v0.11.0

func (s *Session) BeginTx(ctx context.Context) (*ExplicitTx, error)

BeginTx opens a multi-statement write transaction bound to this session: it observes every commit the session has made, and its own commit instant is recorded on the session when it closes.

The recording happens on Commit AND on Rollback, for the reason lpg.Session documents: a rolled-back statement still publishes at the lpg layer, so its instant is a real published instant and a session that skipped it could start its next operation below a commit it made.

func (*Session) Floor ¶ added in v0.11.0

func (s *Session) Floor() uint64

Floor reports the instant of the latest commit this session has made, or 0 when it has made none. It is the timestamp every subsequent operation waits for.

Exported for observability and for tests that need to bracket an observation between two known instants; ordinary callers never need it.

func (*Session) Run ¶ added in v0.11.0

func (s *Session) Run(ctx context.Context, query string, params map[string]expr.Value) (*Result, error)

Run executes a read-only statement, observing every commit this session has made.

It waits for the visible frontier to reach this session's floor and then runs exactly as Engine.Run does. On a session that has committed nothing the wait is a single atomic load and the statement is indistinguishable from Engine.Run.

func (*Session) RunAny ¶ added in v0.11.0

func (s *Session) RunAny(ctx context.Context, query string, params map[string]any) (*Result, error)

RunAny is Engine.RunAny bound to this session: it binds `any`-typed parameters and routes to Session.RunInTx or Session.Run by whether the query writes.

It is the autocommit entry point a server uses, because a wire protocol hands it untyped parameters and does not tell it whether the statement writes.

func (*Session) RunInTx ¶ added in v0.11.0

func (s *Session) RunInTx(ctx context.Context, query string, params map[string]expr.Value) (*Result, error)

RunInTx executes a writing statement as one autocommit transaction, observing every commit this session has made and recording its own.

Recording its own is the half that makes the NEXT operation correct: without it a session's guarantee would cover only the writes it made before the last one.