Package: github.com/freeeve/gochickpeas/gql

package gql Import Path github.com/freeeve/gochickpeas/gql (on go.dev) Dependency Relation imports 20 packages, and imported by one package

Involved Source Files d cache.go PlanCache: a size-bounded LRU cache of auto-parameterized query plans. Two layers share one lock. An exact-string fast path (L1) skips parse + plan on a verbatim repeat; a template index (L2) lets queries differing only in lifted constants share one compiled plan. L1 entries own the plans; a template entry dies when its last L1 variant is evicted (the Go refcount standing in for the Rust engine's Arc/Weak split). Both layers hold the TEMPLATE plan -- planned after auto- parameterization, where every cost probe abstains on parameter slots -- so a cached plan is value-independent by construction. It may differ in SHAPE (never in results) from the literal-probed plan an uncached Run builds for the same text; this mirrors the Rust engine's query_cached composition, trading the best-effort literal plan for zero double planning and cross-literal sharing. Eviction is least-recently-used past a configurable byte budget. The byte estimate counts each L1 entry's key, parameters, and a per-plan estimate; a plan shared by several literal variants is charged once per variant -- a deliberate over-count, so the true footprint stays under the bound. d defaultcache.go The implicit per-snapshot plan cache behind Run/RunWithParams: library callers get template caching (skip parse + plan on repeats) with no setup, per the census verdict -- every measured flip is timing-neutral and the flip-aware bypass routes structurally flipped templates through sighted planning, so the cached path does no harm. The registry keys caches by WEAK snapshot pointers with a GC cleanup, so dropping a snapshot drops its cache; a cache never outlives (or pins) its snapshot. Callers wanting the literal-planned path explicitly -- benchmarks separating cold from warm, plan-shape experiments that mutate planner thresholds between runs -- use RunUncached. d errors.go Package gql is a read-only GQL query engine over an immutable chickpeas.Snapshot -- the Go port of the rustychickpeas-cypher engine with an ISO GQL (read subset) surface. Pipeline: parse -> desugar -> bind -> plan -> execute, returning Rows. d gql.go The public entry points: Run/RunWithParams execute a GQL query over an engine snapshot; Explain renders the plan. Pipeline: parse -> desugar -> plan (cost-based) -> execute, mapping each stage's typed error onto the package sentinels. d planflip.go Plan-flip detection for the cache: a template planned blind (constants lifted to parameters) can choose a structurally different operator tree than value-sighted planning would -- exact scan cardinalities, resolved anchor degrees, and rewrite gates priced from those exacts all go blind under auto-parameterization, and a flipped plan can be arbitrarily worse (the census measured one 17.5x allocation regression). The cache detects the flip once, when a template is first planned, by also planning the literal text and comparing the trees value-blind; a flipped template is marked so execution routes through sighted planning instead of the cached tree. Non-flipped templates -- the overwhelming majority -- keep the full cache win. d prepared.go Prepared: a parsed, auto-parameterized, and planned query, ready to execute repeatedly without re-incurring parse/plan cost -- the unit the plan cache holds, exposed directly for callers managing their own reuse. d rows.go The result surface: Rows, an iterator of named-column Row values. The executor materializes the result set and Rows streams it from the buffer (same contract as the Rust engine's lazy Rows).

Package-Level Functions (total 9)

func DefaultCacheFor(g *chickpeas.Snapshot) *PlanCache DefaultCacheFor returns the snapshot's implicit plan cache, creating it on first use (DefaultCacheBytes budget). Run and RunWithParams route through it; sharing the same cache with explicit PlanCache calls is fine but unnecessary.

func Explain(g *chickpeas.Snapshot, query string) (string, error) Explain renders the query's plan (with cardinality estimates and anchor notes) without executing it.

func ExplainCanonical(g *chickpeas.Snapshot, query string) (string, error) ExplainCanonical renders the query's plan as a stable, canonical shape string for golden plan-regression snapshots: operator order, scan sources, hop patterns, the recognizers that fired, and the chosen anchor -- with the volatile parts (wall-clock planning time, the numeric estimates, the anchor note's magnitudes) excluded. Unlike Explain the output is deterministic across plannings, so a diff between two commits is a review prompt that a planner change moved the plan, invisible to a row-level differential.

func NewPlanCache(maxBytes int) *PlanCache NewPlanCache is an empty cache bounded to maxBytes of approximate resident memory (LRU eviction past the bound); maxBytes <= 0 means DefaultCacheBytes.

func Prepare(g *chickpeas.Snapshot, query string) (*Prepared, error) Prepare parses, desugars, auto-parameterizes, and plans query once against g's statistics.

func Run(g *chickpeas.Snapshot, query string) (*Rows, error) Run executes a GQL query over the snapshot, through the snapshot's implicit plan cache (see DefaultCacheFor): repeats skip parse + plan, results are identical to the uncached path by the -cached-parity contract, and structurally flipped templates route through sighted planning. Use RunUncached for the always-literal-planned path.

func RunUncached(g *chickpeas.Snapshot, query string) (*Rows, error) RunUncached executes a GQL query with literal-sighted planning on every call, bypassing the implicit plan cache -- the cold path, for benchmarks separating cold from warm and for callers that mutate planner behavior between runs.

func RunUncachedWithParams(g *chickpeas.Snapshot, query string, params map[string]value.Value) (*Rows, error) RunUncachedWithParams is RunUncached with explicit $name parameter values.

func RunWithParams(g *chickpeas.Snapshot, query string, params map[string]value.Value) (*Rows, error) RunWithParams is Run with explicit $name parameter values. An unsupplied parameter reads as null.

Package-Level Variables (total 4)

var ErrBind error ErrBind marks a semantic error (unknown variable, bad reference).

var ErrEval error ErrEval marks a runtime evaluation error.

var ErrParse error ErrParse marks a syntax error from the parser.

var ErrPlan error ErrPlan marks a planning error (unsupported construct, bad plan input).

Package-Level Constants (only one)

const DefaultCacheBytes = 134217728 DefaultCacheBytes is the default budget: 128 MiB of approximate resident plan + key + parameter bytes.