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 lpg.Graph.View snapshot. 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 and acquires the engine's writer serialisation: the store's single-writer mutex on a WAL-backed engine, or the engine writer mutex on a store-less engine. The caller MUST finish the returned handle with exactly one ExplicitTx.Commit or ExplicitTx.Rollback; until then the writer serialisation is held and concurrent writers block (write-write Isolation).

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 and guarantees the writer serialisation cannot be held forever.

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

See exectx.go for the full transaction and concurrency contract, including the read-committed isolation scope: concurrent readers block while this transaction is open and observe only the committed state once it ends (task #1412).

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) 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 physical plan that would be chosen to execute query with the given params. The plan reflects current index availability: a hash index on the relevant (label, property) pair causes the relevant Selection+LabelScan subtree to appear as NodeByIndexSeek. No rows are produced; the graph is not modified.

The format mirrors ir.Explain but annotates Selection→LabelScan pairs that would be rewritten to index seeks at execution time.

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:
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) 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) 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 runs under lpg.Graph.View, so it observes one consistent snapshot and does not block concurrent writers (which serialise elsewhere). 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) 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) (res *Result, err error)

Run parses, analyses, plans, and executes query, returning a materialised Result. The query is built and drained inside the read visibility barrier (Graph.View) so it observes a consistent, partial-transaction-free snapshot. 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 lpg.Graph.View 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 single-writer 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) 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 materialised row. It must only be called after a successful [Next] on a materialised result 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.