feat(planner): seek col = (non-correlated scalar subquery) (B9e)

MagicalTux · claude · MagicalTux · commit 94426fb56c83 · 2026-07-04T05:27:28.000+09:00
`WHERE b = (SELECT max(x) FROM u)` (and `&lt;`/`&gt;`/etc.) against a non-correlated
scalar subquery now seeks the index instead of scanning, matching SQLite:
`SEARCH t USING INDEX tb (b=?)`. Secondary index and INTEGER PRIMARY KEY,
equality and range.

Two sides, kept consistent without evaluating during EXPLAIN:
- Executor: scan_source's single-table fast path folds the WHERE via the
  existing fold_subquery_expr (foldable = non-correlated computed) into a
  shadowed seek clause passed to the try_* seeks; run_core re-applies the
  original WHERE, so it stays a superset.
- EQP: eqp_access rewrites a structurally-foldable scalar-subquery comparison
  operand to a placeholder literal (placeholder_fold_seek_where) so the
  constraint collectors recognize the seek WITHOUT running the subquery — SQLite
  plans the seek without evaluating it (e.g. `b=(SELECT 1/0)` still plans a
  SEARCH; the query errors only at execution, as in SQLite). Gated to SELECT.

Residuals (executor and EQP agree — they only differ from SQLite): a bare-column
subquery does not fold (dropping its affinity would be unsound) and stays a SCAN;
a DELETE/UPDATE subquery WHERE stays a SCAN (SQLite's two-pass COVERING plan is
not reproducible from the sel-less eqp_access). Correlated / EXISTS / IN (SELECT)
correctly do not seek.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1196,10 +1196,19 @@ tie/representative order), so they are perf/EQP-fidelity work, not correctness:
   grouping b-tree only over a bare `SCAN`; under a `WHERE` seek it omits the node.
   Entangled with B9h (SQLite often picks a *different* index whose walk serves the
   grouping), so it should land together with the index-choice work.
-- **B9e — `col = (scalar subquery)` seek.** `WHERE b = (SELECT …)` seeks the once-
-  computed value in SQLite (`SEARCH … (b=?)`); graphite `SCAN`s because the eq-
-  collector requires a constant RHS. Needs the executor to evaluate the
-  non-correlated subquery once, then seek (superset-safe; `eqp_access` mirrors it).
+- **B9e — `col = (scalar subquery)` seek. ✅ Done (SELECT).** `WHERE b = (SELECT …)`
+  (and `>`/`<`/etc.) against a non-correlated scalar subquery now seeks — the executor
+  folds the subquery to its value before the seek (`scan_source` single-table fast path),
+  and `eqp_access` recognizes the shape *structurally* (a placeholder-literal rewrite,
+  `placeholder_fold_seek_where`) so `EXPLAIN` renders the `SEARCH` without running the
+  subquery — matching SQLite, which plans the seek without evaluating it (so even
+  `b=(SELECT 1/0)` plans a `SEARCH`; the query still errors at execution as in SQLite).
+  Secondary index + INTEGER PRIMARY KEY, equality + range. Superset-safe. *Residuals:*
+  a **bare-column** subquery (`(SELECT x FROM u)`) does not fold (dropping its affinity
+  would be unsound), so it stays a SCAN (rows correct); and a **DELETE/UPDATE** with a
+  subquery `WHERE` stays a SCAN (SQLite renders a two-pass `USING COVERING INDEX` the
+  `sel`-less `eqp_access` can't reproduce). A **correlated** body / `EXISTS` /
+  `IN (SELECT)` correctly do not seek.
 - **B9f — `GLOB 'prefix*'` prefix-range seek. ✅ Done.** A fixed-prefix `GLOB`
   (always case-sensitive / byte-based) now seeks `col >= 'prefix' AND col < 'prefix⁺'`
   on a BINARY index and reads `SEARCH … (b>? AND b<?)`. Implemented as a `BinaryOp::Glob`
diff --git a/src/exec/mod.rs b/src/exec/mod.rs
@@ -776,24 +776,21 @@ impl Connection {
     /// reference — so the resulting literal has the same NONE affinity / BINARY
     /// collation the subquery operand would have had, making the substitution
     /// exact for the enclosing comparison.
+    /// The *structural* half of [`Self::eval_foldable_scalar`]: whether a scalar
+    /// subquery would fold to a literal — self-contained (non-correlated), a single
+    /// *computed* result column, and (for a compound) every arm computed — WITHOUT
+    /// running it. Used to recognize `col = (subquery)` as a seekable equality for
+    /// EXPLAIN QUERY PLAN, which SQLite plans without evaluating the subquery.
+    fn scalar_subquery_folds_structurally(&self, sel2: &Select) -> bool {
+        self.vdbe_subquery_foldable(sel2)
+            && sel2.columns.len() == 1
+            && matches!(&sel2.columns[0],
+                sql::ast::ResultColumn::Expr { expr, .. } if !is_bare_column_expr(expr))
+            && self.compound_arms_computed(sel2)
+    }
+
     fn eval_foldable_scalar(&self, sel2: &Select) -> Option<Value> {
-        if !self.vdbe_subquery_foldable(sel2) {
-            return None;
-        }
-        if sel2.columns.len() != 1 {
-            return None;
-        }
-        let sql::ast::ResultColumn::Expr { expr, .. } = &sel2.columns[0] else {
-            return None;
-        };
-        if is_bare_column_expr(expr) {
-            return None;
-        }
-        // A compound body's value is folded to a literal, so every additional arm
-        // must also project a COMPUTED column (NONE affinity / BINARY collation);
-        // a bare-column arm would carry that column's affinity, which the literal
-        // would drop — see `is_bare_column_expr` above for the base arm.
-        if !self.compound_arms_computed(sel2) {
+        if !self.scalar_subquery_folds_structurally(sel2) {
             return None;
         }
         let r = self.run_select(sel2, &Params::default()).ok()?;
@@ -806,6 +803,61 @@ impl Connection {
         )
     }
 
+    /// Rewrite a `WHERE` clause so that a *structurally-foldable* non-correlated
+    /// scalar subquery used as a comparison operand (`col = (SELECT …)`, `col > (…)`)
+    /// is replaced by a non-NULL placeholder literal — WITHOUT running it. The seek
+    /// constraint collectors then recognize the comparison as seekable, so
+    /// `eqp_access` renders the `SEARCH` SQLite plans (SQLite plans the seek without
+    /// evaluating the subquery; the executor evaluates it via `fold_subquery_expr`).
+    /// Descends only the `AND`/`(…)` spine and the seekable comparison operators, so a
+    /// subquery elsewhere (an `OR`, a projection) never spuriously enables a seek.
+    /// Returns `None` when nothing changed. The placeholder value is irrelevant — the
+    /// plan renders `col=?`/`col>?` and only the constrained *column* is used.
+    fn placeholder_fold_seek_where(&self, e: &Expr) -> Option<Expr> {
+        let mut changed = false;
+        let out = self.placeholder_fold_where_inner(e, &mut changed);
+        changed.then_some(out)
+    }
+
+    fn placeholder_fold_where_inner(&self, e: &Expr, changed: &mut bool) -> Expr {
+        let subq_placeholder = |s: &Expr, changed: &mut bool| -> Expr {
+            match s {
+                Expr::Subquery(sel2) if self.scalar_subquery_folds_structurally(sel2) => {
+                    *changed = true;
+                    Expr::Literal(Literal::Integer(0))
+                }
+                other => other.clone(),
+            }
+        };
+        match e {
+            Expr::Binary {
+                op: BinaryOp::And,
+                left,
+                right,
+            } => Expr::Binary {
+                op: BinaryOp::And,
+                left: Box::new(self.placeholder_fold_where_inner(left, changed)),
+                right: Box::new(self.placeholder_fold_where_inner(right, changed)),
+            },
+            Expr::Paren(inner) => {
+                Expr::Paren(Box::new(self.placeholder_fold_where_inner(inner, changed)))
+            }
+            Expr::Binary { op, left, right }
+                if matches!(
+                    op,
+                    BinaryOp::Eq | BinaryOp::Lt | BinaryOp::LtEq | BinaryOp::Gt | BinaryOp::GtEq
+                ) =>
+            {
+                Expr::Binary {
+                    op: *op,
+                    left: Box::new(subq_placeholder(left, changed)),
+                    right: Box::new(subq_placeholder(right, changed)),
+                }
+            }
+            other => other.clone(),
+        }
+    }
+
     /// True when every *compound arm* of `sel2` (the `UNION`/… operands after the
     /// base) projects a single computed (non-bare-column) expression — so the
     /// whole compound's result column carries NONE affinity, exactly like an
@@ -14640,6 +14692,17 @@ impl Connection {
         let Some(where_expr) = where_clause else {
             return Ok(alloc::format!("SCAN {label}"));
         };
+        // A non-correlated scalar subquery used as a comparison operand
+        // (`col = (SELECT …)`) seeks the same as a constant would: SQLite evaluates it
+        // once and plans a `SEARCH`. Replace it with a placeholder literal (structurally,
+        // without running it — matching SQLite, which plans the seek without evaluating
+        // the subquery) so the constraint collectors below recognize the seek. The
+        // executor mirrors this by folding the subquery to its value before its seek.
+        // Restricted to a `SELECT` (`sel` present): a DELETE/UPDATE with a subquery
+        // `WHERE` is a two-pass plan SQLite renders `USING COVERING INDEX`, which the
+        // `sel`-less `eqp_access` can't reproduce, so it is left to its prior SCAN.
+        let folded = sel.and_then(|_| self.placeholder_fold_seek_where(where_expr));
+        let where_expr = folded.as_ref().unwrap_or(where_expr);
         // `INDEX` vs `COVERING INDEX` for a seek through `idx_cols`: the same
         // decision the executor's seek paths make via `seek_index_covers`.
         let index_kw = |idx_cols: &[usize]| -> &'static str {
@@ -20988,6 +21051,28 @@ impl Connection {
         // full WHERE is still applied by run_core, so the index only needs to
         // return a superset of matching rows.
         if from.joins.is_empty() {
+            // Fold a non-correlated scalar subquery used as a seek operand
+            // (`col = (SELECT …)`) to its value so the seek can use it — the same
+            // seek `eqp_access` renders. Only the seek *decision* uses the folded
+            // WHERE; `run_core` re-applies the original (superset-safe). A subquery
+            // that fails to fold (correlated / bare-column / erroring) is left in
+            // place and the query scans, exactly as before.
+            let seek_where;
+            let sel = match &sel.where_clause {
+                Some(w) => {
+                    let mut changed = false;
+                    let fw = self.fold_subquery_expr(w, &mut changed);
+                    if changed {
+                        let mut s = sel.clone();
+                        s.where_clause = Some(fw);
+                        seek_where = s;
+                        &seek_where
+                    } else {
+                        sel
+                    }
+                }
+                None => sel,
+            };
             let mut first_meta = self
                 .table_meta(&from.first.name, from.first.alias.as_deref())
                 .map_err(|e| {
diff --git a/tests/seek_scalar_subquery.rs b/tests/seek_scalar_subquery.rs
@@ -0,0 +1,118 @@
+//! B9e — a comparison against a *non-correlated scalar subquery* seeks the index,
+//! exactly as a constant would. `WHERE b = (SELECT max(x) FROM u)` reads
+//! `SEARCH t USING INDEX tb (b=?)` (plus the existing `SCALAR SUBQUERY N` child) in
+//! SQLite, which evaluates the subquery once and plans a seek; graphite used to SCAN
+//! because the eq-collector required a constant RHS. The executor folds the
+//! subquery to its value before the seek; `eqp_access` recognizes the shape
+//! *structurally* (without running the subquery, matching SQLite — `EXPLAIN` never
+//! evaluates it, so even `b = (SELECT 1/0)` plans a `SEARCH`). Equality and range,
+//! secondary index and INTEGER PRIMARY KEY.
+//!
+//! A *correlated* body, `EXISTS`, `IN (SELECT)`, and a bare-column subquery
+//! (`(SELECT x FROM u)` — folding it would drop the column's affinity) do NOT seek —
+//! the outer table stays a `SCAN`, and the full `WHERE` is re-applied so rows are
+//! exact regardless. Verified vs the sqlite3 3.50.4 CLI.
+
+#![cfg(feature = "std")]
+
+use std::process::Command;
+
+fn sqlite3_available() -> bool {
+    Command::new("sqlite3").arg("--version").output().is_ok()
+}
+
+fn plan(bin: &str, base: &str, sql: &str) -> String {
+    let full = format!("{base} EXPLAIN QUERY PLAN {sql}");
+    let out = Command::new(bin)
+        .arg(":memory:")
+        .arg(&full)
+        .output()
+        .unwrap();
+    String::from_utf8_lossy(&out.stdout)
+        .lines()
+        .filter(|l| !l.trim().is_empty() && !l.starts_with("QUERY PLAN"))
+        .map(|l| l.trim_start_matches(|c: char| " |`*+_-".contains(c)))
+        .collect::<Vec<_>>()
+        .join("#")
+}
+
+fn rows(bin: &str, base: &str, sql: &str) -> String {
+    let full = format!("{base} {sql}");
+    let out = Command::new(bin)
+        .arg(":memory:")
+        .arg(&full)
+        .output()
+        .unwrap();
+    String::from_utf8_lossy(&out.stdout).trim_end().to_string()
+}
+
+const SCHEMA: &str = "CREATE TABLE t(a INTEGER PRIMARY KEY, b, c); CREATE INDEX tb ON t(b); \
+                      CREATE TABLE u(x,y); CREATE INDEX ux ON u(x);";
+
+#[test]
+fn scalar_subquery_operand_seeks_like_sqlite() {
+    if !sqlite3_available() {
+        eprintln!("sqlite3 CLI not found; skipping");
+        return;
+    }
+    let g = env!("CARGO_BIN_EXE_graphitesql");
+    for q in [
+        "SELECT * FROM t WHERE b=(SELECT max(x) FROM u)", // secondary index equality
+        "SELECT * FROM t WHERE a=(SELECT max(x) FROM u)", // INTEGER PRIMARY KEY
+        "SELECT * FROM t WHERE b>(SELECT max(x) FROM u)", // range
+        "SELECT * FROM t WHERE b=(SELECT max(x) FROM u) AND c=1",
+        "SELECT * FROM t WHERE b=(SELECT 5)", // constant subquery
+        "SELECT c FROM t WHERE b=(SELECT max(x) FROM u)", // covering
+        "SELECT * FROM t WHERE b=(SELECT 1/0)", // EXPLAIN never runs the subquery
+    ] {
+        assert_eq!(
+            plan("sqlite3", SCHEMA, q),
+            plan(g, SCHEMA, q),
+            "plan for {q}"
+        );
+    }
+}
+
+#[test]
+fn non_seekable_subquery_shapes_stay_scan() {
+    // A correlated / EXISTS / IN (SELECT) / bare-column subquery must not seek the
+    // outer table — graphite keeps the SCAN (results still correct via the WHERE
+    // re-apply). (SQLite renders extra CORRELATED / LIST SUBQUERY nodes graphite does
+    // not model, so we assert only that the outer access is not a SEARCH.)
+    let g = env!("CARGO_BIN_EXE_graphitesql");
+    for q in [
+        "SELECT * FROM t WHERE b=(SELECT y FROM u WHERE x=t.a)", // correlated
+        "SELECT * FROM t WHERE b IN (SELECT x FROM u)",          // IN (SELECT)
+        "SELECT * FROM t WHERE EXISTS(SELECT 1 FROM u WHERE x=b)", // correlated EXISTS
+        "SELECT * FROM t WHERE b=(SELECT x FROM u)",             // bare-column projection
+    ] {
+        let got = plan(g, SCHEMA, q);
+        assert!(
+            !got.contains("SEARCH t "),
+            "{q} should not seek the outer table t, got {got:?}"
+        );
+    }
+}
+
+#[test]
+fn scalar_subquery_seek_rows_match() {
+    if !sqlite3_available() {
+        eprintln!("sqlite3 CLI not found; skipping");
+        return;
+    }
+    let g = env!("CARGO_BIN_EXE_graphitesql");
+    let base = format!(
+        "{SCHEMA} INSERT INTO t VALUES(1,10,1),(2,20,2),(3,30,3),(4,20,4); \
+         INSERT INTO u VALUES(20,1),(10,2),(5,3);"
+    );
+    for q in [
+        "SELECT a FROM t WHERE b=(SELECT max(x) FROM u) ORDER BY a",
+        "SELECT a FROM t WHERE a=(SELECT max(x) FROM u) ORDER BY a",
+        "SELECT a FROM t WHERE b>(SELECT min(x) FROM u) ORDER BY a",
+        "SELECT count(*) FROM t WHERE b=(SELECT max(x) FROM u)",
+        "SELECT a FROM t WHERE b=(SELECT max(x) FROM u WHERE x>999) ORDER BY a", // NULL → no rows
+        "SELECT a FROM t WHERE b=(SELECT x FROM u ORDER BY x DESC LIMIT 1) ORDER BY a",
+    ] {
+        assert_eq!(rows("sqlite3", &base, q), rows(g, &base, q), "rows for {q}");
+    }
+}
