cypher

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) Explain ¶

func (e *Engine) Explain(query string, params map[string]expr.Value) (string, 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

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

For the current in-memory implementation there is no external transaction manager (lpg.Graph does not support rollback). "Commit on success, rollback on error" means: the pipeline runs to completion with mutations applied eagerly; if any operator returns an error the pipeline is drained no further (standard Volcano error propagation) and the partial mutations remain in the graph. This matches the single-writer, in-memory contract documented in CLAUDE.md.

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 (*Result) Close ¶

func (r *Result) Close() error

Close releases all resources held by the result set. When the result was created by Engine.RunInTx, Close also:

1. Commits or rolls back buffered index changes (always).
2. When the engine is WAL-backed (NewEngineWithStore), WAL-syncs the buffered ops via txn.Tx.CommitWALOnly on success, or calls txn.Tx.Rollback on error. Mutations have already been applied to the in-memory graph eagerly; CommitWALOnly only persists them to the WAL.

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.

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