queryplan

Documentation

Overview

Package queryplan provides the plan-cache primitives for #142: a stable query-shape fingerprint, a composite cache key, and a concurrency-safe cache for compiled planning artifacts. Values, cursor positions, and dirty IDs never participate in a shape hash — they are bound per request.

Index

• func HashFederatedQueryShape(q *model.FederatedAttributeQuery) (string, error)
• func HashScopeParts(parts ...string) string
• type Cache
  • func NewCache(capacity int) *Cache
  • func (c *Cache) GetOrBuild(key Key, build func() (any, error)) (any, bool, error)
  • func (c *Cache) Reset()
  • func (c *Cache) Stats() (hits, misses int64)
• type Key

Functions

func HashFederatedQueryShape

func HashFederatedQueryShape(q *model.FederatedAttributeQuery) (string, error)

HashFederatedQueryShape fingerprints everything about a federated query that determines the compiled plan: the condition-tree structure (attribute names, canonical operators, and/or logic, original child order), sort keys, anchor choice, and pagination mode including keyset columns and direction. Filter operands, keyset cursor values, limit, and offset are excluded.

func HashScopeParts

func HashScopeParts(parts ...string) string

HashScopeParts fingerprints ordered scope components (table names, connection strings, template identity, inline pagination values) that must isolate cache entries but are not part of the query shape.

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a concurrency-safe store for compiled planning artifacts, shared across engines/repositories so its lifetime spans repeated requests (the benchmark and production reuse lifecycle — #142 design review finding 1). Concurrent misses on one key are single-flighted: exactly one goroutine builds, the rest wait and share the result, so `misses` equals builds and the benchmark artifact counters stay trustworthy.

func NewCache

func NewCache(capacity int) *Cache

NewCache creates a cache bounded to capacity entries; at the bound the cache clears wholesale (shape/scope combinations are bounded in practice).

func (*Cache) GetOrBuild

func (c *Cache) GetOrBuild(key Key, build func() (any, error)) (any, bool, error)

GetOrBuild returns the cached artifact for key or builds, stores, and returns it. Build errors are returned without caching. Concurrent callers on the same missing key build exactly once (waiters share the result and count as hits). A nil *Cache degrades to always building (zero-value construction in tests).

func (*Cache) Reset

func (c *Cache) Reset()

Reset drops all entries; the schema-generation invalidation hook for future metadata reload scenarios.

func (*Cache) Stats

func (c *Cache) Stats() (hits, misses int64)

Stats returns cumulative hit and miss counts (benchmark evidence hook).

type Key

type Key struct {
	// Kind names the artifact family, e.g. "duckdb_federated",
	// "postgres_optimized_template", "dual_clause_plan".
	Kind string
	// SchemaVersion is the deterministic schema-metadata fingerprint (or
	// load-generation token) — the invalidation lever: content changes
	// produce a different fingerprint, orphaning old entries.
	SchemaVersion string
	SchemaID      int16
	ShapeHash     string
	ScopeHash     string
}

Key isolates cached planning artifacts. Every field participates in equality: a plan is only reused when kind, schema content (fingerprint), schema identity, query shape, and rendering scope all match.