embedded

func BuildSchemaTemplateFromDDL ¶

func BuildSchemaTemplateFromDDL(schemaDDL string) (*metadata.RecordLayerSchemaTemplate, error)

BuildSchemaTemplateFromDDL parses schemaDDL as a single CREATE SCHEMA TEMPLATE statement (auto-wrapping bare CREATE TABLE/INDEX clauses) and builds the RecordLayerSchemaTemplate without any catalog write. It is the programmatic entry to the exact metadata the DDL path produces — used by wire-level index tests that need the DDL-generated metadata against a real record store.

func BuildSchemaTemplateFromDDLNamed ¶

func BuildSchemaTemplateFromDDLNamed(schemaDDL, name string) (*metadata.RecordLayerSchemaTemplate, error)

BuildSchemaTemplateFromDDLNamed is BuildSchemaTemplateFromDDL with an explicit template name for bare clause bodies. The name matters at the wire level: it is the descriptor FILE name inside the persisted RecordMetaData, so a cross-engine byte comparison must build under the same name Java persisted. Quoted to preserve case (Java's harness sets the name programmatically, case intact).

func NewExplainOnlyGenerator ¶

func NewExplainOnlyGenerator() query.Generator

NewExplainOnlyGenerator constructs a Generator suitable for capturing Plan.Explain() output without executing. The returned Generator is backed by a zero-value EmbeddedConnection — Plan.Execute on the returned plans is unsupported (no FDB, no catalog, no session state). Used by the plan-equivalence harness (RFC-022 section 4.-1) to produce plan trees for diffing against Java's planner output.

Catalog-aware predicate trees (buildLogicalPlanFor*WithCatalog paths) require non-nil RecordMetaData; this constructor always produces text-only logical plans. Use NewExplainOnlyGeneratorWithSchema to unlock the catalog-aware branch.

func NewExplainOnlyGeneratorWithSchema ¶

func NewExplainOnlyGeneratorWithSchema(schemaDDL string) (query.Generator, error)

NewExplainOnlyGeneratorWithSchema is the catalog-aware companion to NewExplainOnlyGenerator. It parses the supplied CREATE SCHEMA TEMPLATE DDL into an in-memory RecordLayerSchemaTemplate (no FDB write), wraps it in an api.Schema bound to a synthetic database + schema, and seeds the connection's SchemaCache. Subsequent statements planned through the returned Generator route through the buildLogicalPlanFor*WithCatalog paths so WHERE clauses appear as real cascades.predicates.QueryPredicate trees in the Explain output.

schemaDDL must contain exactly one CREATE SCHEMA TEMPLATE statement. Multiple-statement DDL or any non-CREATE-SCHEMA-TEMPLATE shape returns an error — callers should isolate the schema DDL from the SELECT/DML they intend to plan.

func PlanPhysicalDMLForTest ¶

func PlanPhysicalDMLForTest(sql, schemaDDL string, stats properties.StatisticsProvider) (plans.RecordQueryPlan, error)

PlanPhysicalDMLForTest is PlanPhysicalForTest for a DELETE or UPDATE statement: it routes the DML through the SAME logical-build → translate → Cascades-plan → extract → ValidatePlanInvariants pipeline the production DML generator (cascadesGenerator.planDML) runs, but metadata-only — no live store, planner-default statistics when stats is nil — exactly as PlanPhysicalForTest does for SELECT.

It exists so the explain-differ corpus dump can pin DML plan SHAPES. A planner change that reads differ-clean on every SELECT while corrupting the DELETE-WHERE-EXISTS path (RFC-184 W2) is invisible to a SELECT-only dump; planning DELETE/UPDATE too catches that class at the plan level.

Only DELETE and UPDATE are handled. INSERT carries no interesting winning plan: INSERT … VALUES is literal rows (no scanned tree), and INSERT … SELECT is planned as its SELECT body, already covered by PlanPhysicalForTest. The sql passed here MUST be a single DELETE or UPDATE statement; anything else is a caller error (ErrCodeUnsupportedQuery).

func PlanPhysicalDMLForTestWithReachability ¶

func PlanPhysicalDMLForTestWithReachability(
	sql, schemaDDL string,
	stats properties.StatisticsProvider,
	reach *cascades.ReachabilityCollector,
) (plans.RecordQueryPlan, error)

PlanPhysicalDMLForTestWithReachability is PlanPhysicalDMLForTest with RFC-183's yield-time plan-reachability accounting routed into the caller's collector. nil = collect nothing (identical to PlanPhysicalDMLForTest).

func PlanPhysicalForTest ¶

func PlanPhysicalForTest(sql, schemaDDL string, stats properties.StatisticsProvider) (plans.RecordQueryPlan, error)

PlanPhysicalForTest is PlanQueryForTest returning the TYPED physical plan instead of its Explain rendering. The rowdiff harness (RFC-182) buckets plan families over this tree — per the RFC, plan-family classification must come from a plan-type switch, never from string-matching EXPLAIN text.

func PlanPhysicalForTestWithReachability ¶

func PlanPhysicalForTestWithReachability(
	sql, schemaDDL string,
	stats properties.StatisticsProvider,
	reach *cascades.ReachabilityCollector,
) (plans.RecordQueryPlan, error)

PlanPhysicalForTestWithReachability is PlanPhysicalForTest with RFC-183's yield-time plan-reachability accounting routed into the caller's collector.

Exists because that tally must belong to ONE measurement. It used to live in package variables inside cascades, and the corpus ratchet consequently summed three concurrent tests' planning into a single number (edges=53748 against a true 17916). A collector the caller owns cannot be added to, or reset by, anyone it was not handed to.

nil collector is legal and means "collect nothing" — identical to PlanPhysicalForTest.

func PlanQueryForTest ¶

func PlanQueryForTest(sql, schemaDDL string, stats properties.StatisticsProvider) (string, error)

PlanQueryForTest runs the full Cascades pipeline on a SQL query against a schema defined by DDL, with optional table statistics. Returns the physical plan's Explain string. No FDB connection needed.

schemaDDL is a CREATE SCHEMA TEMPLATE statement (or just the table/index definitions — "CREATE SCHEMA TEMPLATE auto_template" is prepended if missing).

stats may be nil to use default statistics (LeafScanCardinality for all record types).

func PlanQueryForTestWithDisabledRules ¶

func PlanQueryForTestWithDisabledRules(
	sql, schemaDDL string, stats properties.StatisticsProvider, disabled []string,
) (string, error)

PlanQueryForTestWithDisabledRules is PlanQueryForTest with a set of planner rules excluded from selection, by the SIMPLE type name Planner.DisabledRules is keyed by ("MergeProjectionAndFetchRule").

It exists so a causal claim about WHICH rule produces an observed plan shape can be asserted rather than asserted-in-prose: the observable ("the plan has COVERING") is one measurement, and "this rule is what put it there" is a different one that only a disabling experiment can make. The names go through the same api.Options funnel a connection's DISABLED_PLANNER_RULES uses, so a test cannot reach a disabled-rule configuration production cannot.

An unrecognized name is INERT, not an error — Java's setDisabledTransformationRuleNames never resolves its strings either. A test relying on a name must therefore also show the name has an effect; a typo otherwise reads as "disabling it changed nothing".

func PlanQueryWithMetadata ¶

func PlanQueryWithMetadata(sql string, md *recordlayer.RecordMetaData, stats properties.StatisticsProvider) (string, error)

PlanQueryWithMetadata is like PlanQueryForTest but accepts pre-built RecordMetaData instead of DDL. Used for testing features that require index types not expressible in DDL (aggregate indexes).

func PlanRecordQueryAssertingAllIndexesReadable ¶

func PlanRecordQueryAssertingAllIndexesReadable(
	sql string, md *recordlayer.RecordMetaData, stats properties.StatisticsProvider,
) (plans.RecordQueryPlan, error)

PlanRecordQueryAssertingAllIndexesReadable is PlanRecordQueryWithMetadata under the AFFIRMATIVE all-indexes-readable view instead of the UNKNOWN one.

The plain harness deliberately leaves index state UNKNOWN — it has no store to ask — and RFC-210 §5.1.1 makes that demotion load-bearing: a planning run that never consulted a store may still plan an index scan, but it may not prove anything from an index's declared UNIQUENESS. That is why the harness never yields R2 or R3, and it is a property worth keeping.

It also means a metadata-only test cannot obtain a NARROWED plan from the planner. Before this entry existed, the tests that needed one built it by hand — `distinct.WithNarrowedDedup("BY_EMAIL", []int{0})` — which asserts nothing about the mapping from the index's key columns onto dedup-key slot positions (rule_implement_distinct_final.go's exemptSlotsFor). That mapping is the part that can be wrong: aim it at the wrong slot and the operator tests a column the index does not key, retaining rows on a passenger column's NULLs and missing the key column's. A hand-written [0] agrees with a broken exemptSlotsFor on every fixture where the key column happens to be first.

The CALLER states the assertion, which is the whole point: this is the same affirmative claim cascadesGenerator mints after fetching a snapshot and finding every index strictly READABLE (readableIndexesFrom), so a caller using it is asserting the store condition rather than being handed it. Use it only where that condition is established independently — a freshly built store whose indexes were never transitioned. Everything the plain harness documents about executing its result applies here unchanged and with more force: this one CAN produce a plan whose correctness rests on an index's state.

func PlanRecordQueryWithMetadata ¶

func PlanRecordQueryWithMetadata(sql string, md *recordlayer.RecordMetaData, stats properties.StatisticsProvider) (plans.RecordQueryPlan, error)

PlanRecordQueryWithMetadata is like PlanQueryWithMetadata but returns the physical RecordQueryPlan, not just its Explain string. This is a metadata-only TEST/HARNESS API: it has no record store from which to load mutable index state. A caller that executes the result against a real store must independently establish that EVERY secondary index in md is strictly READABLE and remains so through execution. Otherwise a metadata-only UNIQUE proof can survive even when the final plan contains no index leaf for the executor to reject. Live SQL must use cascadesGenerator, which snapshots, cache-keys, and revalidates authoritative store state. The session schema defaults to the embedded planner's "s".

The query's scalar subqueries are planned but NOT returned — fine for plan-only callers (Explain/shape assertions); a caller that EXECUTES a subquery-bearing plan without pre-binding results fails loudly with values.UnboundScalarSubqueryError. Executing callers use PlanRecordQueryWithSubqueries.

func PlanRecordQueryWithMetadataSchema ¶

func PlanRecordQueryWithMetadataSchema(sql string, md *recordlayer.RecordMetaData, schemaName string, stats properties.StatisticsProvider) (plans.RecordQueryPlan, error)

PlanRecordQueryWithMetadataSchema is PlanRecordQueryWithMetadata bound to a specific session schema (the real CONNECT schema on the session path — cascades_generator.go uses g.c.sess.Schema for the same threading). A non-default schema flows through NewPlanVisitorWithSchema AND the schema-qualified-table demotion/resolution, so a schema-qualified source — including INSIDE a subquery (`… EXISTS (SELECT 1 FROM PA AS main, main.PB AS B)` with session schema `main`) — is resolved against the ACTIVE schema, not the hardcoded default. RFC-142 (P2b). It remains a metadata-only harness and inherits the strictly-READABLE execution precondition above.

func ResultColumnDefsForPlan ¶

func ResultColumnDefsForPlan(plan plans.RecordQueryPlan, md *recordlayer.RecordMetaData) []executor.ColumnDef

ResultColumnDefsForPlan returns the FULL production ColumnDef set for a plan — the same deriveColumnsFromPlan output the live Execute() path hands to NewRecordLayerResultSet — so an FDB test can drive the REAL result-set read path (including the positional-aligned column read) for shapes not seeded through the SQL driver.

func ResultColumnLabelsForPlan ¶

func ResultColumnLabelsForPlan(plan plans.RecordQueryPlan, md *recordlayer.RecordMetaData) []string

ResultColumnLabelsForPlan returns the user-visible result-set column labels a plan would advertise — the metadata-only (no-FDB) analog of the driver's paginatingRows.Columns(): it runs the SAME production column derivation (deriveColumnsFromPlan, the function the live Execute() path calls) and maps each ColumnDef to its label exactly as Columns() does (Label, or Name when the label is empty), upper-cased. This lets the planner harness assert the result COLUMN SET — distinct from the per-row datum map (which carries extra resolution-convenience keys) — for shapes that cannot be seeded through the SQL driver (historically non-empty array columns, before SQL INSERT gained array literals). RFC-142.

func ResultColumnNullabilityForPlan ¶

func ResultColumnNullabilityForPlan(plan plans.RecordQueryPlan, md *recordlayer.RecordMetaData) []int

ResultColumnNullabilityForPlan returns the JDBC NULLABILITY flag advertised for each result-set column, in order — the metadata-only (no-FDB) analog of the driver's ResultSetMetaData.isNullable. It runs the SAME production column derivation (deriveColumnsFromPlan → ColumnDef.Nullable) the live Execute() path uses, so the harness can assert column nullability for shapes that cannot be seeded through the SQL driver (historically a lateral unnest over a non-empty array column, before SQL INSERT gained array literals). The WITH-ORDINALITY ordinal column must report api.ColumnNoNulls here (Java's INT NOT NULL ordinal), even though it has no backing proto descriptor field. RFC-142.

func ResultColumnTypesForPlan ¶

func ResultColumnTypesForPlan(plan plans.RecordQueryPlan, md *recordlayer.RecordMetaData) []string

ResultColumnTypesForPlan returns the SQL TYPE NAME advertised for each result-set column, in order — the metadata-only (no-FDB) analog of the driver's column-type metadata. It runs the SAME production column derivation (deriveColumnsFromPlan → ColumnDef.TypeName) the live Execute() path uses, so the harness can assert column types for shapes that cannot be seeded through the SQL driver (historically a lateral unnest over a non-empty array column, before SQL INSERT gained array literals). The element column of a non-ordinal unnest over a STRING array must report STRING here, not the UnknownType→BIGINT fallback. RFC-142.