cascades

func AddPartialMatchForCandidate ¶

func AddPartialMatchForCandidate(
	ref *expressions.Reference,
	candidate MatchCandidate,
	match PartialMatch,
) bool

AddPartialMatchForCandidate stores a PartialMatch for the given MatchCandidate on the Reference. Typed wrapper around Reference.AddPartialMatch. Mirrors Java's Reference.addPartialMatchForCandidate.

Semantic dedup: Reference.AddPartialMatch dedups only by pointer identity, but matching rules re-fire and reconstruct the SAME logical match. Endpoint-only dedup is too coarse, however: partial matching can produce several valid alias maps, child selections, and bindings for one (queryExpression, candidateRef) pair. Drop only an exact semantic re-add; retain alternatives whose downstream matching or compensation metadata differs.

func AdjustFixedBindings ¶

func AdjustFixedBindings(parts []properties.ProvidedOrderingPart, isReverse bool) []properties.ProvidedOrderingPart

AdjustFixedBindings adjusts the sort order of FIXED ordering parts to match the resolved comparison direction. If the comparison is reverse, fixed parts get descending; otherwise ascending. Mirrors Java's RecordQuerySetPlan.adjustFixedBindings.

func AdjustMatches ¶

func AdjustMatches(rootRef *expressions.Reference)

AdjustMatches walks all References reachable from rootRef and, for every existing PartialMatch, attempts to absorb candidate-side-only expressions one level up from the matched candidate ref. On success, a new PartialMatch with AdjustedMatchInfo is stored on the same query Reference but pointing to the parent candidate Reference.

This is the Go equivalent of Java's AdjustMatchRule, which fires on PartialMatches via a TransformPartialMatch task. In Go, AdjustMatches is called explicitly after MatchLeafRule and MatchIntermediateRule have run, rather than being scheduled as a rule (see also AdjustPartialMatchesForRef at the data-access consumption boundary).

Ports Java's com.apple.foundationdb.record.query.plan.cascades.rules.AdjustMatchRule.

func AdjustPartialMatchesForRef ¶

func AdjustPartialMatchesForRef(ref *expressions.Reference)

AdjustPartialMatchesForRef runs the AdjustMatchRule absorption loop on a single Reference's partial matches until stable. Each round attempts to absorb a candidate-side parent expression (SelectExpression → MatchableSortExpression) onto each existing PartialMatch, producing adjusted matches that carry e.g. matched ordering parts.

This is the per-ref unit of Java's event-driven AdjustMatchRule. It is invoked both by the bottom-up AdjustMatches walk (for REWRITING-phase matches) AND by pushDataAccessTasks just before it consumes a ref's matches — PLANNING-phase matches are seeded during exploration, after the phase-start AdjustMatches walk, so they must be adjusted at consumption time or their ordering parts (needed to satisfy a requested ordering and eliminate an in-memory sort) are never computed.

func AllAttributesExcept ¶

func AllAttributesExcept(except ...*properties.ExpressionProperty) []*properties.ExpressionProperty

AllAttributesExcept returns plan properties excluding the specified ones.

func AssertMergeSlotTypingCensus ¶

func AssertMergeSlotTypingCensus(w io.Writer, c MergeSlotTypingCounts, floor int) bool

AssertMergeSlotTypingCensus checks the census against `floor` slots, reports its reasoning to w, and returns whether it FAILED.

The polarity matches its siblings and the censusGate contract (census_gate_reporting_test.go): run returns FAILED, not OK. Getting it backwards makes a clean census report as a failure, which is how this was caught — the gate fired on a run reporting 22,362 slots with a holding partition and zero untyped. That total is one SAMPLE of a population that moves with memo exploration order (~22.4k; see positional_merge.go), which is why the floor below is an order of magnitude under it rather than an equality.

Two directions, and they are not the same alarm. The PARTITION identity going wrong means the instrument miscounts, so every share it reports is meaningless. UNTYPED going non-zero means a live slot lost its row type, which is the silent zero-rows defect. The floor guards the third case: a collapsed denominator makes `Untyped == 0` true for the wrong reason.

func AssertProjectionMergeCensus ¶

func AssertProjectionMergeCensus(w io.Writer, floors *ProjectionMergeFloors) bool

AssertProjectionMergeCensus checks the claim the name-arm deletion rests on. It reports whether anything failed.

The ZERO is the claim; the floors and the partition check are what keep the zero from being vacuous. Both are needed, and in this order: a zero over a population nothing reached, and a zero produced by a counter that stopped being wired, are indistinguishable in a printed report.

func AssertUnresolvedResultTypeCensus ¶

func AssertUnresolvedResultTypeCensus(w io.Writer, floors *UnresolvedResultTypeFloors) bool

AssertUnresolvedResultTypeCensus checks the process census against floors.

func ComputeDerivations ¶

func ComputeDerivations(expr expressions.RelationalExpression) *properties.Derivations

ComputeDerivations evaluates the derivations property for a physical plan wrapper expression. Dispatches on the concrete wrapper type, matching Java's DerivationsVisitor per-plan methods.

Exported for use by plan_properties.go and tests.

func CreateScansForMatches ¶

func CreateScansForMatches(
	accesses []Vectored[*SingleMatchedAccess],
	_ PlanContext,
) map[PartialMatch]plans.RecordQueryPlan

CreateScansForMatches converts each SingleMatchedAccess into a physical scan plan by calling MatchCandidate.ToScanPlan with the bound parameter prefix and reverse flag.

Returns a map from PartialMatch to RecordQueryPlan. The map uses the PartialMatch identity (pointer equality) as key.

Ports Java's AbstractDataAccessRule.createScansForMatches.

func CrossProduct ¶

func CrossProduct[T any](lists [][]T) [][]T

CrossProduct computes the Cartesian product of N lists. Each list provides alternatives for one "dimension"; the result is every combination of picking one element from each list.

For input [[a, b], [x, y]], returns [[a, x], [a, y], [b, x], [b, y]]. Empty input returns nil. Any empty inner list makes the product empty.

Mirrors Java's CrossProduct.crossProduct utility.

func DataAccessForMatchPartition ¶

func DataAccessForMatchPartition(
	requestedOrderings []*properties.RequestedOrdering,
	partialMatches []PartialMatch,
	ctx PlanContext,
	intersector IntersectorFunc,
) []expressions.RelationalExpression

DataAccessForMatchPartition orchestrates data access planning from a collection of PartialMatches. This is the main entry point that concrete rules call.

Steps:

1. Compute maximum-coverage matches (with Pareto filtering)
2. Create scan plans for each viable match
3. For single match: wrap as expression with compensation
4. For multiple matches: try intersections via the provided intersector callback

The intersector is a function parameter so concrete rules can provide their own intersection logic (replaces Java's abstract createIntersectionAndCompensation method).

Ports Java's AbstractDataAccessRule.dataAccessForMatchPartition.

func ExplainPhysicalPlan ¶

func ExplainPhysicalPlan(expr expressions.RelationalExpression) string

ExplainPhysicalPlan returns the Explain() string for a physical-plan expression, or empty string if the expression is not a physical plan.

func ExtractBestPlan ¶

func ExtractBestPlan(ref *expressions.Reference) (expressions.RelationalExpression, error)

ExtractBestPlan walks the Reference DAG rooted at `ref` and returns a fresh RelationalExpression tree where every reachable Reference is a singleton holding the cost-cheapest member chosen under DefaultStatistics. Children are extracted recursively.

Use case: callers holding an explored Reference (rule-generated alternatives attached) who want to materialise a single best plan for execution / display / serialisation. Without this, the extracted "plan" is the Reference DAG with multiple alternative members still attached; downstream consumers have no easy way to lock in one shape.

Behaviour:

• Returns nil if `ref` is nil or empty.
• The returned expression is structurally fresh — its Quantifiers range over freshly-allocated single-member Reference objects. Pointer identity with the input tree's References is NOT preserved.
• Cycle-safe: a visited set guards against infinite recursion through cyclic Reference DAGs (e.g. recursive CTE expression trees where the RecursiveUnion's quantifiers could form back-edges through the Memo).
• Switch-on-concrete-type for constructor dispatch — each concrete RelationalExpression type has an arm. Adding a new type requires extending this switch.

Returns an error if any reachable expression is of a type unknown to this extractor — surfacing the missing arm rather than silently dropping or panicking.

See ExtractBestPlanWith for the stats-bound variant.

func ExtractBestPlanFromSelector ¶

func ExtractBestPlanFromSelector(ref *expressions.Reference, sel BestMemberSelector, stats properties.StatisticsProvider) (expressions.RelationalExpression, error)

ExtractBestPlanFromSelector returns a fresh executable tree where every Reference's physical member comes from `sel` if available; otherwise it cost-selects from physical members only. A selector-named LogicalSort is the one exception: it is accepted only when sort elision immediately resolves it to a physical ordered child.

Use this when the caller has a pre-populated selector (e.g. the cascades.Planner after PlanWithContext). It avoids repeating the OPTIMIZE work that already happened during planning.

Pass nil sel to use the physical-only cost fallback. Use ExtractBestPlanWith when intentionally extracting a still-logical DAG.

func ExtractBestPlanFromSelectorContext ¶

func ExtractBestPlanFromSelectorContext(
	ctx context.Context,
	ref *expressions.Reference,
	sel BestMemberSelector,
	stats properties.StatisticsProvider,
) (expressions.RelationalExpression, error)

ExtractBestPlanFromSelectorContext is the cancelable form of ExtractBestPlanFromSelector. It polls ctx throughout recursive extraction so a canceled planning run does not continue rebuilding a large plan DAG.

func ExtractBestPlanWith ¶

func ExtractBestPlanWith(ref *expressions.Reference, stats properties.StatisticsProvider) (expressions.RelationalExpression, error)

ExtractBestPlanWith is ExtractBestPlan driven by a specific StatisticsProvider. Stats flow into per-Reference best-member selection so different table cardinalities can flip which alternative wins.

Pass nil for stats to use DefaultStatistics (equivalent to ExtractBestPlan).

func FinalOf ¶

func FinalOf(expression expressions.RelationalExpression) (*expressions.Reference, error)

func FinalOfAtStage ¶

func FinalOfAtStage(expression expressions.RelationalExpression, stage expressions.PlannerStage) (*expressions.Reference, error)

func FinalizePlan ¶

func FinalizePlan(plan plans.RecordQueryPlan)

FinalizePlan performs the plan-time bake: it builds ONE type repository for the whole plan and stamps every reachable *values.RecordConstructorValue with the message descriptor for its result type.

This is Java's QueryPlan.java:639-643, which builds one TypeRepository per plan from usedTypes().evaluate(relationalExpression) and hands it to the evaluation context for RecordConstructorValue.eval to read back (RecordConstructorValue.java:113-114). Go stamps the descriptor onto the value instead of carrying it on a context, because Go has no uniform evaluation context to carry it on — RFC-204 §4.5.1 records the decision and the reasoning, and TestFrontierContextIsNotAUniformCarrier pins the premise it rests on.

One repository per plan is what makes the COMMON case free; it is not a correctness requirement. Descriptor identity is per-repository, so two constructors of the same record type stamped from different repositories produce messages that are wire-compatible but not identity-equal. Within one plan that never happens, which is why a nested constructor's message can be set straight into its parent's field — Java's deepCopyIfNeeded (RecordConstructorValue.java:165-216) has nothing to reconcile there.

ACROSS plans it does happen, by design: a scalar subquery is planned and baked as its own plan (embedded/scalar_subquery_planning.go calls FinalizePlan on it separately, because it hangs off the cascadesPlan rather than off any child edge of the outer plan), so it carries its own repository. A message built from that repository and set into an outer constructor's field takes the by-number copy in values.rowMessageToProtoValue — the port of deepCopyIfNeeded — and lands correctly. So the guarantee this walk provides is "one repository per plan", and the copy is what covers the rest.

Call it exactly once per plan, on the plan-cache MISS path before PlanCache.Put. The cache returns the SAME plan pointer to every subsequent execution and each page rebuilds its cursor hierarchy from it concurrently, so stamping at execution time would be a data race on values.

A type with no message form (a bare scalar record field, an erased array) yields a *values.ProtoTypeError from MessageDescriptorFor. That is NOT a query failure: the constructor simply stays unstamped and evaluates to its name-keyed map, exactly as it did before the bake existed.

func FireExpressionRule ¶

func FireExpressionRule(rule ExpressionRule, ref *expressions.Reference) ([]expressions.RelationalExpression, error)

FireExpressionRule is a standalone driver for testing ExpressionRules. Matches the rule's pattern against every member of `ref` and invokes OnMatch for each successful match. Yields are inserted into `ref` via the ExpressionRuleCall's Reference; the returned slice is the rule's intent (Yielded()).

Production rule driving lives in the planner's task stack (unified_tasks.go); this helper is the testable entry point — same pattern as FireRule for predicate/value rules.

func FireExpressionRuleWithMemo ¶

func FireExpressionRuleWithMemo(rule ExpressionRule, ref *expressions.Reference, ctx PlanContext, memo *Memo) ([]expressions.RelationalExpression, error)

FireExpressionRuleWithMemo is like FireExpressionRule but passes a PlanContext and Memo to the rule call, enabling cross-Reference memoization when running inside the Planner.

func FireImplementationRule ¶

func FireImplementationRule(rule ImplementationRule, ref *expressions.Reference, constraints ...*ConstraintMap) ([]expressions.RelationalExpression, error)

FireImplementationRule runs an ImplementationRule against a Reference, matching each member and collecting yielded expressions. Returns the yielded expressions (also inserted into ref.Members).

func FireImplementationRuleWithContext ¶

func FireImplementationRuleWithContext(rule ImplementationRule, ref *expressions.Reference, ctx PlanContext, memo *Memo, constraints ...*ConstraintMap) ([]expressions.RelationalExpression, error)

FireImplementationRuleWithContext is like FireImplementationRule but threads a PlanContext through to the rule call. The planner uses this to provide PK / match-candidate info to rules that need it.

func FireRule ¶

func FireRule(rule CascadesRule, in any) ([]any, error)

FireRule drives a predicate/value rule once against `in`: run `rule.Matcher()`, and for every successful match invoke `rule.OnMatch`. Returns the aggregate list of yielded replacements across all matches. Used by rule unit tests; production predicate simplification runs through Simplify's fixpoint loop (simplifier.go), and planner rules through the task stack (unified_tasks.go).

func FormatMergeSlotTypingCensus ¶

func FormatMergeSlotTypingCensus() string

FormatMergeSlotTypingCensus renders the tally for a harness report.

func FormatProjectionMergeCensus ¶

func FormatProjectionMergeCensus() string

FormatProjectionMergeCensus renders the counts for a corpus report.

func FormatUnresolvedResultTypeCensus ¶

func FormatUnresolvedResultTypeCensus() string

FormatUnresolvedResultTypeCensus renders the process census for a harness to log.

func Get ¶

func Get[T any](cm *ConstraintMap, ref *expressions.Reference, key *PlannerConstraint[T]) (T, bool)

Get retrieves the constraint value for a Reference + key combination. The Reference is canonicalized: a constraint pushed on a since-merged alias must stay visible to a reader holding the survivor (and vice versa) — the map's identity is the GROUP, not the pointer.

func GetPhysicalMultiIntersectionPlan ¶

func GetPhysicalMultiIntersectionPlan(expr expressions.RelationalExpression) *plans.RecordQueryMultiIntersectionOnValuesPlan

GetPhysicalMultiIntersectionPlan returns the plan if expr is a multi-intersection, nil otherwise. Since RFC-184 W2 the memo holds the bare plan, so this is a bare type assertion.

func IndexPredicateProtoIsTautology ¶

func IndexPredicateProtoIsTautology(p *gen.Predicate) bool

IndexPredicateProtoIsTautology reports whether a stored index predicate provably rejects no record — i.e. whether the index it guards holds an entry for every record. Normalize the way Java's constructors do, then apply Java's narrow tautology test to the result.

func InitialOf ¶

func InitialOf(expression expressions.RelationalExpression) (*expressions.Reference, error)

InitialOf, FinalOf, and FinalOfAtStage are the checked root factories. They return no Reference until exact admission and the complete singleton commit succeed.

func IsPhysicalAggregateIndex ¶

func IsPhysicalAggregateIndex(expr expressions.RelationalExpression) bool

IsPhysicalAggregateIndex reports whether the expression is an aggregate index scan. Since RFC-184 W2 the memo holds *plans.RecordQueryAggregateIndexPlan directly (no physicalAggregateIndexWrapper), so this is a bare type check.

func IsPhysicalDelete ¶

func IsPhysicalDelete(expr expressions.RelationalExpression) bool

IsPhysicalDelete reports whether the given RelationalExpression is a DELETE plan. Since RFC-184 W2 the memo holds *plans.RecordQueryDeletePlan directly (no physicalDeleteWrapper), so this is a bare type check.

func IsPhysicalFetchFromPartialRecord ¶

func IsPhysicalFetchFromPartialRecord(expr expressions.RelationalExpression) bool

IsPhysicalFetchFromPartialRecord reports whether the given RelationalExpression is a physical fetch. Since RFC-184 W2 the memo holds *plans.RecordQueryFetchFromPartialRecordPlan directly (no physicalFetchFromPartialRecordWrapper), so this is a bare type check on the plan.

func IsPhysicalFilter ¶

func IsPhysicalFilter(expr expressions.RelationalExpression) bool

IsPhysicalFilter reports whether the given RelationalExpression is a physical predicates filter. Since RFC-184 W2 the memo holds *plans.RecordQueryPredicatesFilterPlan directly (no physicalPredicatesFilterWrapper), so this is a bare type check.

func IsPhysicalFlatMap ¶

func IsPhysicalFlatMap(expr expressions.RelationalExpression) bool

IsPhysicalFlatMap reports whether the given RelationalExpression is a physical correlated FlatMap. Since RFC-184 W2 the memo holds *plans.RecordQueryFlatMapPlan directly (no physicalFlatMapWrapper), so this is a bare type check.

func IsPhysicalInJoin ¶

func IsPhysicalInJoin(expr expressions.RelationalExpression) bool

IsPhysicalInJoin reports whether the given expression is an InJoin. Since RFC-184 W2 the memo holds *plans.RecordQueryInJoinPlan directly (no physicalInJoinWrapper), so this is a bare type check.

func IsPhysicalIndexScan ¶

func IsPhysicalIndexScan(expr expressions.RelationalExpression) bool

IsPhysicalIndexScan reports whether the given RelationalExpression is an index scan. Since RFC-184 W2 the memo holds the plan directly (no physicalIndexScanWrapper), so this is a type check on the plan.

A COVERING index scan answers TRUE. It is an index scan — it reads the same physical index range and differs only in the row it reconstructs — and since RFC-220 it is the shape the memo actually holds for an index-backed access. A predicate named "is an index scan" that answered FALSE for the only index scan in the memo would be a trap for every caller.

func IsPhysicalInsert ¶

func IsPhysicalInsert(expr expressions.RelationalExpression) bool

IsPhysicalInsert reports whether the given RelationalExpression is an INSERT plan. Since RFC-184 W2 the memo holds *plans.RecordQueryInsertPlan directly (no physicalInsertWrapper), so this is a bare type check.

func IsPhysicalIntersection ¶

func IsPhysicalIntersection(expr expressions.RelationalExpression) bool

IsPhysicalIntersection reports whether the given RelationalExpression is an intersection. Since RFC-184 W2 the memo holds *plans.RecordQueryIntersectionPlan directly (no physicalIntersectionWrapper), so this is a bare type check.

func IsPhysicalLimit ¶

func IsPhysicalLimit(expr expressions.RelationalExpression) bool

IsPhysicalLimit reports whether the given RelationalExpression is a physical LIMIT. Since RFC-184 W2 the memo holds *plans.RecordQueryLimitPlan directly (no physicalLimitWrapper), so this is a bare type check on the plan.

func IsPhysicalMap ¶

func IsPhysicalMap(expr expressions.RelationalExpression) bool

IsPhysicalMap reports whether the given expression is a physical map. Since RFC-184 W2 the memo holds *plans.RecordQueryMapPlan directly (no physicalMapWrapper), so this is a bare type check on the plan.

func IsPhysicalMultiIntersection ¶

func IsPhysicalMultiIntersection(expr expressions.RelationalExpression) bool

IsPhysicalMultiIntersection reports whether the given RelationalExpression is a multi-intersection. Since RFC-184 W2 the memo holds *plans.RecordQueryMultiIntersectionOnValuesPlan directly (no physicalMultiIntersectionWrapper), so this is a bare type check.

func IsPhysicalNestedLoopJoin ¶

func IsPhysicalNestedLoopJoin(expr expressions.RelationalExpression) bool

IsPhysicalNestedLoopJoin reports whether the given RelationalExpression is a physical nested-loop join. Since RFC-184 W2 the memo holds *plans.RecordQueryNestedLoopJoinPlan directly (no physicalNestedLoopJoinWrapper), so this is a bare type check.

func IsPhysicalPredicatesFilter ¶

func IsPhysicalPredicatesFilter(expr expressions.RelationalExpression) bool

IsPhysicalPredicatesFilter reports whether the given expression is a physical predicates filter. Since RFC-184 W2 the memo holds *plans.RecordQueryPredicatesFilterPlan directly (no physicalPredicatesFilterWrapper), so this is a bare type check.

func IsPhysicalRecursiveDfsJoin ¶

func IsPhysicalRecursiveDfsJoin(expr expressions.RelationalExpression) bool

IsPhysicalRecursiveDfsJoin reports whether the given RelationalExpression is a recursive DFS join. Since RFC-184 W2 the memo holds *plans.RecordQueryRecursiveDfsJoinPlan directly (no physicalRecursiveDfsJoinWrapper), so this is a bare type check.

func IsPhysicalRecursiveLevelUnion ¶

func IsPhysicalRecursiveLevelUnion(expr expressions.RelationalExpression) bool

IsPhysicalRecursiveLevelUnion reports whether the given RelationalExpression is a recursive level union. Since RFC-184 W2 the memo holds *plans.RecordQueryRecursiveLevelUnionPlan directly (no physicalRecursiveLevelUnionWrapper), so this is a bare type check.

func IsPhysicalStreamingAgg ¶

func IsPhysicalStreamingAgg(expr expressions.RelationalExpression) bool

IsPhysicalStreamingAgg reports whether the given RelationalExpression is a physical streaming aggregation. Since RFC-184 W2 the memo holds *plans.RecordQueryStreamingAggregationPlan directly (no physicalStreamingAggWrapper), so this is a bare type check.

func IsPhysicalUpdate ¶

func IsPhysicalUpdate(expr expressions.RelationalExpression) bool

IsPhysicalUpdate reports whether the given RelationalExpression is an UPDATE plan. Since RFC-184 W2 the memo holds *plans.RecordQueryUpdatePlan directly (no physicalUpdateWrapper), so this is a bare type check.

func MergeSlotTypeDisagreements ¶

func MergeSlotTypeDisagreements() (int64, []string)

MergeSlotTypeDisagreements returns how many positional merges declined because a leg quantifier's reference members disagreed on their row type, plus the distinct witnesses retained (capped). A nonzero count over any corpus is a memo defect: either a rule inserted an expression flowing a different row into an existing equivalence class, or a leg's row type is being derived two ways.

func NestPullUp ¶

func NestPullUp(
	pm PartialMatch,
	pullUp *PullUp,
	candidateAlias values.CorrelationIdentifier,
) (rootOfMatchPullUp *PullUp, currentPullUp *PullUp)

NestPullUp walks through the candidate reference chain to build a nested PullUp chain. For each level, it visits the candidate expression to determine the pull-through value. If the match info is adjusted (wrapping another), it descends through the adjustment chain.

Returns (rootOfMatchPullUp, currentPullUp). currentPullUp is the innermost level, used to translate predicates and to nest child matches. rootOfMatchPullUp is the level this nesting introduced on top of the incoming chain — the one result compensation pulls the query result value through. It is nil when the incoming pull-up is itself a match level (this nesting continues someone else's match rather than rooting a new one), which is Java's signal that no result compensation is owed here.

currentPullUp is nil when the chain cannot be built faithfully: a missing candidate reference, a reference that does not hold exactly one non-nil member, or an adjusted level whose candidate does not have exactly one quantifier. Java asserts those (Reference.get, which throws unless the reference holds exactly one member, and Verify.verify on the quantifier count) and crashes; Go fails closed instead so the caller degrades the match to an impossible compensation. Both refuse to compensate off a guessed chain — silently taking members[0] of a multi-member reference builds a pull-up for an expression the match was never proved against, and every value pulled through it is then wrong.

Ports Java's PartialMatch.nestPullUp.

func NewPlanningCostModelLess ¶

func NewPlanningCostModelLess(stats properties.StatisticsProvider) func(a, b expressions.RelationalExpression) bool

NewPlanningCostModelLess returns a stats-aware cost model comparator with no PlanContext (index metadata for cardinality/unmatched-field criteria is resolved conservatively). Prefer NewPlanningCostModelLessWithContext.

func NewPlanningCostModelLessWithContext ¶

func NewPlanningCostModelLessWithContext(stats properties.StatisticsProvider, ctx PlanContext) func(a, b expressions.RelationalExpression) bool

NewPlanningCostModelLessWithContext returns a stats-aware cost model comparator. The returned function uses real record counts (via stats) for cardinality estimation and resolves index/primary-key metadata via ctx so the criterion-#2 (provable max cardinality) and criterion-#12 (unmatched primary-scan/index key fields) properties are computed faithfully from the CONCRETE plan tree (RFC-069). Pass nil stats for default (LeafScanCardinality); pass nil ctx to resolve index metadata conservatively (treat indexes as non-unique).

func NormalizeDNF ¶

func NormalizeDNF(pred predicates.QueryPredicate, sizeLimit int) (predicates.QueryPredicate, bool)

NormalizeDNF converts a predicate to disjunctive normal form (DNF). Returns (result, true) if a transformation was applied, or (original, false) if the predicate is already in DNF or the normalised form would exceed sizeLimit.

DNF: the outer connective is OR, each child is either a leaf or an AND of leaves. The transformation distributes AND over OR:

A AND (B OR C) -> (A AND B) OR (A AND C)

Mirrors Java's BooleanPredicateNormalizer with Mode.DNF.

func NormalizeDNFWithoutSimplification ¶

func NormalizeDNFWithoutSimplification(pred predicates.QueryPredicate, sizeLimit int) (predicates.QueryPredicate, bool)

NormalizeDNFWithoutSimplification is the Go port of BooleanPredicateNormalizer.getDefaultInstanceForDnf().normalize(pred, false) (BooleanPredicateNormalizer.java:227-230): pure distribution into disjunctive normal form with NOT pushed down over AND/OR via De Morgan (toNormalized's negate flag, :370-384), but — unlike NormalizeDNF above, which matches normalizeAndSimplify (:209-215) — WITHOUT absorption and WITHOUT dedup. The distinction is wire-visible for the index-predicate producer (MaterializedViewIndexGenerator.java:675 calls normalize, not normalizeAndSimplify): an absorbed clause would change the stored RecordMetaDataProto.Predicate bytes relative to Java.

Returns (pred, false) when the predicate is already in normal form (isInNormalForm, :255-293) or the normalized size would exceed sizeLimit (shouldNormalize with failIfTooLarge=false, :295-303) — Java's Optional.empty(), which the caller resolves with orElse(conjunction).

func NormalizeIndexPredicateProto ¶

func NormalizeIndexPredicateProto(p *gen.Predicate) *gen.Predicate

THE INVARIANT, for this function and every caller of it: normalization may only ERASE a predicate it can PROVE accepts every record. Anything it cannot prove — an arm it does not understand, a malformed message, a child it cannot compile — must stay VISIBLE to the sparseness gates, because those gates read absence as "this index holds everything". Erasing on doubt turns a partial index into a full one and a scan of it into wrong rows; keeping a predicate that was in fact harmless costs at worst a declined candidate.

NormalizeIndexPredicateProto applies Java's predicate CONSTRUCTION rules to a stored index predicate, returning the equivalent predicate Java would have built. It is the single authority on that question: the planner (deciding whether a candidate carries a predicate to account for) and the executor (deciding whether an index is complete enough to scan) both classify through it, so they cannot answer differently about the same stored bytes.

Java never classifies a conjunction of tautologies, because it never constructs one. IndexPredicate.AndPredicate.toPredicate delegates to AndPredicate.and (IndexPredicate.java:344-345), and that constructor drops every tautological conjunct, returns ConstantPredicate.TRUE when none remain, and unwraps a lone survivor (AndPredicate.java:188-206). `TRUE AND TRUE` has therefore already become the constant before anything asks whether it filters.

OR IS NOT THE DUAL, and deliberately so. OrPredicate.or delegates to OrPredicate.of (OrPredicate.java:417-445), which only collapses a single-element disjunction — it does no tautology folding — and OrPredicate never overrides QueryPredicate.isTautology (default false, QueryPredicate.java:311). So `TRUE OR x` is NOT a tautology to Java, and folding it here would make Go's completeness proof WIDER than Java's: Go would scan an index Java treats as filtering. The asymmetry is Java's, not an oversight to be tidied up.

A ROW-NUMBER WINDOW arm is likewise never folded, and that is a DIVERGENCE from Java's conversion, taken deliberately. Java's RowNumberWindowPredicate.toPredicate returns ConstantPredicate.TRUE (IndexPredicate.java:770-772) — but that states only that the constraint is not expressible as a QueryPredicate over a record, NOT that it filters nothing. It filters maximally: `QualifyRowNumber(score, DESC) <= 100` "keeps the 100 records with the highest score values in the index" (IndexPredicate.java:608-619). Folding it to the constant here would classify a top-N index as COMPLETE and let a scan serve it as the whole table.

Leaving it unfolded keeps it VISIBLE to the sparseness gates, and that alone turned out not to be enough: the flat expansion converts the predicate and omits a tautological result, so a row-window arm that reached indexPredicateToQueryPredicate was mapped to TRUE and dropped, and the candidate matched as full whether the arm arrived bare or wrapped in an AND. The conversion therefore REFUSES the arm outright, which excludes the candidate.

That refusal is LOAD-BEARING rather than belt-and-braces: a store can carry such an index, because the record layer maintains one — a vector index whose stored predicate declares the window is decorated by slidingWindowIndexMaintainer, which keeps only the qualifying records in the wrapped HNSW graph. The arm's compiled per-record evaluator answers `true` for every record (Java's shouldIndexThisRecord), and it is exactly that answer which must never reach the completeness question here.

The result is always a deep clone; the input is never mutated and the two trees share no nodes.

func OptionalRewritingRuleNames ¶

func OptionalRewritingRuleNames() []string

OptionalRewritingRuleNames returns the names of the rules Java's `RecordQueryPlannerConfiguration.Builder.disableRewritingRules()` turns off — `RewritingRuleSet.OPTIONAL_RULES`, i.e. every rule of the REWRITING rule set EXCEPT `FinalizeExpressionsRule`, which stays on because it is what stamps an expression FINAL and planning cannot proceed without it.

Java's set is {QueryPredicateSimplificationRule, PredicatePushDownRule, DecorrelateValuesRule, RewriteOuterJoinRule, SelectMergeRule}; all five exist in Go under the same names, so the disabled set is name-identical. SelectMergeRule is in Go's DefaultExpressionRules rather than RewritingRules (Go's REWRITING phase runs the default expression rules), so it is named explicitly instead of being derived from RewritingRules().

The names are the Java simple-class-name spelling, which is exactly what Planner.DisabledRules is keyed by.

func OrderFunctionDirection ¶

func OrderFunctionDirection(name string) (values.OrderedBytesDirection, bool)

OrderFunctionDirection maps an order-function name to its TupleOrdering direction; ok=false for any other function name.

EXACT match, not case-folded. Java never classifies by name at all — it holds the direction as a field on OrderFunctionKeyExpression and dispatches on the type — and it registers the four builders under names already lowercased (OrderFunctionKeyExpressionFactory: `FUNCTION_NAME_PREFIX + direction.name().toLowerCase(Locale.ROOT)`), so no upper-case spelling can name a built-in order function in either engine.

Folding case here was not a harmless convenience. RegisterFunction is public API over a CASE-SENSITIVE map (key_expression.go), so an application may register its own evaluator under `ORDER_ASC_NULLS_FIRST`; the record layer would then encode that column with the application's function while the planner classified it as the built-in tuple-order encoding, deriving ordered ranges — or eliminating a sort — from bytes nothing ever wrote in that order. Exact match keeps this consistent with isOrderFunctionName (order_function_key_expression.go), which never folded.

func OrderingAliases ¶

func OrderingAliases(
	groupingAliases []values.CorrelationIdentifier,
	scoreAlias values.CorrelationIdentifier,
	primaryKeyAliases []values.CorrelationIdentifier,
) []values.CorrelationIdentifier

OrderingAliases is a package-level helper that computes the ordering alias list for a windowed index: grouping + [score] + primaryKey. Ports Java's WindowedIndexScanMatchCandidate.orderingAliases().

func PlanningCostModelLess ¶

func PlanningCostModelLess(a, b expressions.RelationalExpression) bool

PlanningCostModelLess is the Java-aligned multi-criteria plan comparator, with the documented Go-specific criteria called out below.

Returns true if a is strictly preferred over b. The comparison uses these ordered tie-breaking criteria. Parenthetical numbers are the stable Java-aligned labels used by focused tests and design docs; Go extensions do not renumber those labels:

• Physical plan beats non-physical (#1)
• Max cardinality of all data accesses, lower wins (#2)
• Fewer normalized residual predicates (#3)
• Fewer data access operators: scan + index + covering (#4)
• Recursive CTE tie-breaker: DFS beats level-based (#5)
• Join-order cost (#15, broadened and hoisted in Go)
• IN-plan penalty when IN-values are not SARGs (#6)
• Primary scan vs index-scan-with-fetch preference (#7)
• In-memory sort count, fewer wins (Go sort-elimination analogue)
• Type filter count, fewer wins (#8)
• Type filter depth, deeper wins (#9)
• Index fetch metrics, fewer non-covering scans/fetches win (#10)
• Distinct depth, deeper wins (#11)
• Unmatched primary-scan/index key field count, fewer wins (#12)
• IN-join source count, more wins (#13)
• MAP + PredicatesFilter count, fewer wins (#14)
• Nested-loop-join predicate count, more wins (Go extension)
• ON EMPTY NULL operation count, fewer wins (#16)
• Scalar cost fallback (Go statistics extension)
• Plan hash deterministic tie-break (#17)

func PredicatePushesBelowGroupBy ¶

func PredicatePushesBelowGroupBy(p predicates.QueryPredicate, groupingKeys []values.Value) bool

PredicatePushesBelowGroupBy reports whether one predicate over a GroupBy's output can be evaluated BEFORE the aggregation — the decision this rule makes per predicate, exported because the SQL translator has to make the SAME call upstream: a HAVING reference that will be pushed below must keep its pre-aggregate binding, and one that will not must be rebased onto the aggregate's output row. Two answers to one question is a wrong-row read on whichever side loses.

It was TWO implementations, and they had already drifted in three ways that a shared decider removes: the translator's copy matched a group key by BARE LEAF NAME (so a nested `addr.city` key answered to a top-level `city`), it never checked the COMPARAND (so `key > SUM(v)` — which this rule refuses to push — was told it would be pushed), and it did not require every grouping key to have an establishable identity.

func RegisteredRuleNames ¶

func RegisteredRuleNames() []string

RegisteredRuleNames returns a sorted list of registered rule names. Useful for tests that want to iterate the registry deterministically.

func ResetMergeSlotTypingCensus ¶

func ResetMergeSlotTypingCensus()

ResetMergeSlotTypingCensus zeroes the tally.

func ResetOrderingComparisonCensus ¶

func ResetOrderingComparisonCensus()

ResetOrderingComparisonCensus zeroes every site's counts.

It exists because these counters are PACKAGE-scoped, and this package has learned what that costs: ReachabilityCollector's header records a corpus tally that read 3x its true value because sibling tests planned the same corpus in parallel. The same hazard applies here, with one difference that makes the package scope tolerable — the assertion built on these counts is a ZERO, and a zero over a sum of non-negative terms is exact no matter how many extra corpus passes contribute to it. A concurrent pass can only make the assertion FAIL, never falsely pass.

The absolute TOTALS have no such protection: they are a lower bound unless the census ran alone. Reset before a pass and run that pass with -run isolation if the totals themselves are the artifact you need.

func ResetProjectionMergeCensus ¶

func ResetProjectionMergeCensus()

ResetProjectionMergeCensus zeroes the counts.

The counters are PACKAGE-scoped, so a sibling test planning in parallel adds to them. The assertion built on them is a ZERO, and a zero over a sum of non-negative terms is exact however many extra passes contribute — a concurrent pass can only make it FAIL, never falsely pass. The absolute totals have no such protection and are a lower bound unless the pass ran alone.

func ResetUnresolvedResultTypeCensus ¶

func ResetUnresolvedResultTypeCensus()

ResetUnresolvedResultTypeCensus clears the process counters. Present so a test can drive the REAL recorder — recordResultTypeRead, by name — rather than a local copy of its body, which is the mutation a copy would survive.

func ResolveComparisonDirection ¶

func ResolveComparisonDirection(parts []properties.ProvidedOrderingPart) bool

ResolveComparisonDirection examines the comparison ordering parts and determines if the comparison is reverse (all descending). Returns true if all directional parts are descending. Mirrors Java's RecordQuerySetPlan.resolveComparisonDirection.

func RewritingCostModelLess ¶

func RewritingCostModelLess(a, b expressions.RelationalExpression) bool

RewritingCostModelLess is the cost model for the REWRITING phase. It ports the tail of Java's RewritingCostModel.compare():

1. Fewer SelectExpressions
2. Fewer TableFunctionExpressions
3. Fewer normalized residual predicate conjuncts (CNF full-size)
4. More predicates at deeper levels (push predicates down)
5. Semantic hash tiebreak

DELIBERATE OMISSION — Java's FIRST criterion, outerJoinCount (penalize any surviving OuterJoinExpression), is NOT ported, and must not be. In Java it is a CORRECTNESS GUARD, not a heuristic: Java's OuterJoinExpression is a logical-only node with NO physical operator and exactly one consumer (RewriteOuterJoinRule), so it MUST be rewritten before planning. Java's single-final-expression prune keeps one survivor per group; without outerJoinCount the un-rewritten OuterJoinExpression (0 selects) would beat the rewritten form (2 selects) on the selectCount tie-break, survive the prune, and leave the planning phase with an UNIMPLEMENTABLE node — the query would fail to plan. outerJoinCount forces the implementable rewritten form to survive.

Go has no such correctness problem, because Go's outer join IS directly implementable: an outer-join SelectExpression is planned by ImplementNestedLoopJoinRule as a MATERIALIZED RecordQueryNestedLoopJoinPlan (RFC-152) — a read-side extension Java lacks (Java has only the correlated FlatMap re-scan). Go deliberately keeps the un-rewritten outer-join select as the REWRITING prune survivor (it wins on selectCount, 1<2) precisely so PLANNING can derive BOTH the materialized NLJ (scan the inner once) AND the correlated FlatMap (re-scan) and cost-choose. Porting outerJoinCount would force the rewritten form to win the prune, discard the outer-join select, and thereby SUPPRESS the materialized-NLJ alternative — a regression, not a fix (pinned by TestFDB_ArrayUnnestOrdinality, which asserts the materialized NLJ box, and by TestRewritingCostModel_KeepsUnrewrittenOuterJoin). RFC-186: every tier derives through DESIGNATED child finals (the virtual prune, designated_final.go) — a function of a deterministically-chosen candidate tree, never of memo-population history. The pre-RFC-186 tiers summed over ALL memo members (exploratory included), so two equivalent candidates scored differently by how many rewrites their child groups happened to accumulate — and tier 3's physical-only descent counted nothing at all on the all-logical REWRITING memo. This package-level function mints a fresh designation scope per call (identical semantics to the planner-owned scope, merely uncached); the planner's REWRITING cost model uses its own scope so OptimizeGroup winners and designations come from the SAME comparator (coherence, RFC-186 instrument).

func Set ¶

func Set[T any](cm *ConstraintMap, ref *expressions.Reference, key *PlannerConstraint[T], value T) bool

Set stores a constraint value for a Reference + key combination (the Reference canonicalized — see Get). Set pushes a constraint with Java pushProperty semantics (RFC-181 WS-P stage (b) first commit): the per-key LATTICE COMBINE decides — an absent key stores the push; a present key stores the combined value when the lattice grew and SUBSUMES the push otherwise (no store, no tick — Java's empty Optional). Both stores see the same combined value: the planner-global map (read-authoritative) and the per-Reference epoch mirror (which ticks only on real change, so an unchanged re-Set per rule re-fire can never hold a group unconverged once epochs drive convergence). The former plain overwrite ALSO silently clobbered a shared child's accumulated referenced fields when two parents pushed different sets — the union combine is the Java-faithful repair. The returned verdict reports whether the lattice GREW — Java's pushProperty Optional presence. Callers gate re-exploration scheduling on it (a subsumed push schedules nothing).

func SetOrderingComparisonCensusEnabled ¶

func SetOrderingComparisonCensusEnabled(on bool)

SetOrderingComparisonCensusEnabled turns the census on or off. It is OFF in every production path and in every test but the corpus census, which needs the counts and is the only reader; when off, each comparison pays one relaxed atomic load.

func Simplify ¶

func Simplify(pred predicates.QueryPredicate, rules []CascadesRule) (predicates.QueryPredicate, error)

Simplify iterates the rules on `pred` until no rule produces a rewrite, then returns the final form. Each iteration applies every rule in order; if ANY rule yields, the result replaces `pred` and the loop restarts from the top (fixpoint convergence). Descends into child predicates after the top-level stabilises.

Termination invariants for the rule sets this driver runs:

• DefaultSimplifyRules — each rule strictly reduces the tree (folds a constant or drops an identity / absorbed child), and there's a finite number of constants / identities to collapse.
• NormalizationRules — adds DeMorganRule, which strictly INCREASES the node count (NOT distributed across N children adds N-1 NOTs). DeMorganRule terminates via NOT-depth monotone decrease: each application moves every NOT one level closer to leaves, leaves are finitely deep, leaves eventually hit NotComparisonRewriteRule and disappear (or stop matching).

Not safe against cyclic-rewrite rule sets — real Cascades uses a memo to detect cycles. The rule sets this driver runs are termination-proven per above so no cycle is possible.

func UnresolvedResultTypeCensus ¶

func UnresolvedResultTypeCensus() (map[string]int, map[string]int)

UnresolvedResultTypeCensus reports a SNAPSHOT of the counters as two maps, resolved and unresolved, keyed by deciding site.

func ValidatePlanInvariants ¶

func ValidatePlanInvariants(plan plans.RecordQueryPlan) error

ValidatePlanInvariants checks RFC-164 WS-2 structural invariants on a fully extracted physical plan tree. It is a cheap, always-on backstop — run in the no-FDB plan harness, the production generator, and a fuzz target — that makes a whole class of malformed plans un-shippable rather than hunting them one PR at a time.

It has TWO detectors for a relink that dropped a child:

• Empty-children: a non-leaf plan with zero children. A unary operator whose inner was left nil (the IN-LIMIT bug) has its nil masked by GetChildren (which returns empty for a nil inner), so it masquerades as a leaf. Comparing against the fixed set of genuinely-childless plan types unmasks it.
• Nil-in-slice: a fixed-arity operator (NLJ, FlatMap, recursive joins/unions) returns a length-N slice whose dropped child is a nil ELEMENT rather than a shorter slice; the per-child nil check below catches that.

It walks the PLAN tree, not the expression tree: the malformation lives in the eagerly-materialized plan SNAPSHOT, while the live expression member (the wrapper's quantifier) still points at a healthy reference — so an expression-tree walk traverses the healthy edge and never reaches the break.