Struct PlanKey 

pub struct PlanKey {
    pub query_text: Arc<str>,
    pub query_hash: u64,
    pub schema_version: u64,
    pub collection_generations: SmallVec<[u64; 4]>,
    pub analyze_generations: SmallVec<[u64; 4]>,
}

Deterministic cache key for compiled query plans.

Two keys are equal iff the canonical query text is byte-for-byte identical AND the database state (schema version + per-collection write / analyze generations) has not changed.

collection_generations must be sorted by collection name before insertion for deterministic hashing.

Correctness invariant (CACHE-01, issue #902)

query_hash is a 64-bit FxHash of the canonical query text. FxHash is a fast, non-cryptographic hash: distinct queries can be engineered to collide on the same 64-bit value. If equality were decided on query_hash alone, a colliding query would be treated as equal to an unrelated cached query and the cache could return another query’s compiled plan (wrong results).

To make this impossible, PlanKey stores the canonical query_text and the hand-written PartialEq/Eq impls compare the full text (not the hash). query_hash is retained purely as a Hash accelerator so that the DashMap/LruCache buckets stay cheap to compute; the Hash impl deliberately feeds only query_hash (plus the generation fields) into the hasher rather than re-hashing the whole string on every lookup. This mirrors the safe pattern used by the VelesQL parse cache (velesql/cache.rs), which re-checks query-text equality on every lookup.

Hash/Eq consistency: equal keys have identical query_text, and query_hash is a pure function of query_text, so equal keys always hash identically — the Hash/Eq contract holds.

Fields

query_text: Arc<str>

Canonical serialization of the query AST (see Database::build_plan_key).

This is the authoritative query-identity field: equality is decided on this string, never on query_hash alone. Stored behind Arc<str> so cloning a PlanKey (done on every cache insert / promotion) is a cheap refcount bump rather than a full string copy.

query_hash: u64

FxHash of query_text. Hash accelerator only — not an identity field. Collisions are resolved by the query_text comparison in Eq.

schema_version: u64

Monotonic counter incremented on every DDL operation.

collection_generations: SmallVec<[u64; 4]>

Per-collection write generation, sorted by collection name.

analyze_generations: SmallVec<[u64; 4]>

Per-collection analyze generation, sorted by collection name (issue #608).

Parallel to collection_generations but tracks ANALYZE invocations rather than data mutations. Including this in the cache key ensures that running ANALYZE alone — with no intermediate write to bump write_generation — still invalidates plans whose cost estimates were derived from pre-analyze heuristics.

Trait Implementations

impl Clone for PlanKey

fn clone(&self) -> PlanKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PlanKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for PlanKey

impl Hash for PlanKey

fn hash<H: Hasher>(&self, state: &mut H)

Feeds only the cheap query_hash accelerator (plus generation fields) into the hasher — never the full query_text — so lookups stay fast. Equal keys hash identically because query_hash is a pure function of query_text.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PlanKey

fn eq(&self, other: &Self) -> bool

Equality compares the canonical query text (collision-safe), never query_hash alone (issue #902). The generation fields gate cache invalidation.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.