Crate fsqlite_planner 

Query planner: name resolution, WHERE analysis, cost model, join ordering.

Implements:

• Compound SELECT ORDER BY resolution (§19 quirk: first SELECT wins)
• Cost model for access paths in page reads (§10.5)
• Index usability analysis for WHERE terms (§10.5)
• Bounded beam search join ordering — NGQP-style (§10.5)

Note: AST-to-VDBE compilation is an integration concern and lives above the planner layer per the workspace layering rules (bd-1wwc).

Modules

codegen

AST-to-VDBE bytecode compilation (§10.6).

decision_contract

Decision Contract for the query planner (bd-1lsfu.6).

differential

Planner-side fail-closed compiler for Bloodstream-compatible view shapes.

stats

Statistics for cost-based query planning.

Structs

AccessPath

A concrete access path chosen by the planner.

CostMetricsSnapshot

Point-in-time snapshot of planner cost metrics.

CrackingHintStore

Minimal adaptive hint cache keyed by table name.

IndexInfo

Metadata about an index, used for cost estimation and usability checks.

JoinPlanSegment

One join-operator decision segment.

MorselEligibility

Morsel-parallel SELECT eligibility decision produced by the planner.

PlannerFeatureFlags

Planner feature toggles.

PushedPredicate

A pushed-down predicate: WHERE term assigned to a specific table.

QueryPlan

The final output of the query planner: an ordered access plan.

QueryPlanner

Stateful planner wrapper that memoizes query plans by SQL template and schema cookie.

ResolvedCompoundOrderBy

A resolved ORDER BY term for a compound SELECT.

RowidAliasHint

Schema hint that a visible table column is an alias for SQLite’s hidden rowid, as with INTEGER PRIMARY KEY.

TableRefWithStats

A table reference paired with cost-model inputs for join ordering.

TableStats

Statistics about a table, used for cost estimation.

WhereColumn

The column side of a WHERE comparison.

WhereTerm

A decomposed WHERE term with the column it references (if any).

Enums

AccessPathKind

The kind of access path the planner can choose for a table scan.

AccessPathProbe

Probe expressions extracted from the WHERE clause during access-path selection. Carried forward so downstream consumers (connection seam, VDBE codegen) do not re-extract from the AST.

CompoundOrderByError

Errors during compound ORDER BY resolution.

FoldResult

Result of attempting to fold a constant expression.

IndexUsability

Result of analyzing a WHERE term against an index.

JoinOperator

Join operator chosen for a segment of the join plan.

MorselIneligibleReason

Why a query was deemed ineligible for morsel-parallel execution.

MultiColumnTrailingConstraint

SingleTableProjectionError

Errors during single-table result-column resolution.

StatsSource

How table/index statistics were obtained.

WhereTermKind

Classification of a WHERE term for index usability.

Constants

DEFAULT_PLAN_CACHE_CAPACITY

Default number of cached query plans retained by QueryPlanner.

Functions

analyze_index_usability

Determine the usability of an index for a set of WHERE terms.

asymmetric_estimation_loss

Compute asymmetric loss between estimated and actual costs.

best_access_path

Build the cheapest AccessPath for a table given available indexes and WHERE terms. Returns the lowest-cost option.

best_access_path_with_hints

Build the cheapest AccessPath while applying explicit index hints and optional adaptive cracking hint reuse.

best_access_path_with_rowid_alias_hints

Build the cheapest AccessPath while recognizing schema-provided rowid alias columns such as id INTEGER PRIMARY KEY.

choose_join_segments

Select join operator segments for a query plan.

classify_where_term

Classify a single WHERE expression into a WhereTerm.

collect_table_index_hints

Extract per-table index hints from a FROM clause.

compound_op_name

Get the compound operator type names for a compound SELECT (for logging).

compute_mx_choice

Compute the mxChoice beam width from the number of tables in the join.

cost_metrics_snapshot

Take a point-in-time snapshot of cost estimation metrics.

count_output_columns

Count the number of output columns in a SelectCore.

decompose_where

Decompose a WHERE clause into individual conjuncts (AND-separated terms).

detect_star_query

Detect a star-query pattern: one table joins to all other tables.

estimate_cost

Estimate the cost (in page reads) for a given access path.

estimate_cost_ext

Estimate the cost (in page reads) for a given access path, optionally incorporating the table row count (PLANNER-2).

extract_output_aliases

Extract output column alias names from a single SelectCore.

is_compound

Check whether a SelectBody is a compound query (has UNION/INTERSECT/EXCEPT).

order_join_inputs_with_hints

Decide a join evaluation order for tables using per-table cost hints.

order_joins

Order tables using bounded beam search (NGQP-style, §10.5).

order_joins_with_hints

Order tables using bounded beam search while honoring table-level INDEXED BY/NOT INDEXED hints and optional adaptive cracking hints.

order_joins_with_hints_and_features

Order tables using bounded beam search and select join operators (hash vs Leapfrog Triejoin) based on feature flags and cost model.

plans_enumerated_total

Take a snapshot of plans-enumerated counter.

pushdown_predicates

Push WHERE predicates down to the lowest possible table in the join tree.

record_estimation_error

Record an estimation error observation (actual_cost / estimated_cost).

reset_cost_metrics

Reset cost estimation metrics.

reset_plans_enumerated

Reset plans-enumerated counter.

resolve_compound_order_by

Resolve all ORDER BY terms for a compound SELECT statement.

resolve_single_table_result_columns

Resolve result columns for a single-table SELECT by:

resolve_single_table_result_columns_with_options

Resolve result columns for a single-table SELECT with explicit control over whether hidden rowid aliases (rowid, _rowid_, oid) are available.

snapshot_index_selection_totals

try_constant_fold

Attempt to constant-fold an expression.