Invert MERGE's target × source scan into a per-source-row target seek when the ON carries a seekable target equality.

Author: RyanLamansky

CLAUDE.md

@@ -107,7 +107,7 @@ The `*.Tests` and `*.Tests.EFCore` suites are the authoritative behavior contrac
 
 ### Constraints
 - `CHECK`: inline single-column and table-level forms; Msg 547 per row on definitely-false predicate. Inline column-level CHECK predicates may only reference their owning column — peer references raise **Msg 8141** at CREATE TABLE (probe-confirmed verbatim wording). The walker is structural via `Expression.VisitColumnReferences` + `BooleanExpression.VisitOperandExpressions`; coverage is currently limited to common container subclasses (`Reference`, `Parenthesized`, `TwoSidedExpression`, `Cast`, `Length`) — peer refs buried in less-common containers (`DATEPART`, `SUBSTRING`, nested `CASE`, etc.) silently escape the CREATE-TABLE check and surface at INSERT instead. Table-level CHECK has no peer restriction.
-- `PRIMARY KEY` / `UNIQUE` / secondary `CREATE INDEX`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up), identical across keys and non-clustered indexes (built from heap-row bytes keyed by the index's ordinals): equality / IN on the longest leading prefix, range (`>`/`<`/`BETWEEN`) on a leading key column, ORDER BY elimination — single or multi-column leading-prefix sort (all NOT NULL, all one direction), including an equality-prefix continued by the order columns (`WHERE a = @x ORDER BY b`) — and keyset (seek-method) pagination (`WHERE a > @x OR (a = @x AND b > @y) ORDER BY a, b` seeks past the cursor). The same equality / range narrowing accelerates **single-table `UPDATE` / `DELETE` target scans** (`Selection.SeekMutationTarget`; the mutation loop's full-predicate re-check is the residual filter, and it X-locks only the rows it commits so the lock footprint is unchanged) — `MERGE` still full-scans (its `ON` correlates target to source, so it needs loop inversion). See [`indexes.md`](docs/claude/indexes.md) for the journal mechanics, decline rules, and the residual-WHERE correctness invariant.
+- `PRIMARY KEY` / `UNIQUE` / secondary `CREATE INDEX`: linear scan (O(N) per insert); no B-tree. Reads get **incrementally-maintained** per-`Heap` seek acceleration (no per-mutation warm-up), identical across keys and non-clustered indexes: equality / IN on the longest leading prefix, range on a leading key column, ORDER BY elimination, and keyset pagination. The same narrowing accelerates `UPDATE` / `DELETE` target scans and `MERGE` (via loop inversion). See [`indexes.md`](docs/claude/indexes.md) for the seek shapes, mutation/MERGE seeking, journal mechanics, decline rules, and the residual-WHERE correctness invariant.
 - `FOREIGN KEY`: inline / table-level / named forms; all four referential actions on `ON DELETE` / `ON UPDATE`; enforced at INSERT / UPDATE / DELETE / MERGE; full `sys.foreign_keys` / `sys.foreign_key_columns`. Enforcement **seeks the shared `HeapSeekCache`** (the same per-`Heap` index the query path uses): child-insert parent-existence probes the parent's PK/UNIQUE; parent-delete/update cascades seek the child's FK columns — both verifying candidates against live bytes (no residual WHERE), with a full-scan fallback only for non-stored key columns. Referential-action, cascade-cycle, PK/UNIQUE-target, and NULL-skip rules + Msg numbers in [`foreign-keys.md`](docs/claude/foreign-keys.md).
 
 ### Transactions

SqlServerSimulator.Tests.Internal/IndexSeekTests.cs

@@ -1714,4 +1714,93 @@ public void DeleteSeek_NoMatch_LeavesTableIntact()
         Exec(c, "delete from t where id = 99");
         AreEqual("1,2,3", Seq(ReadRows(c, "select id from t order by id")));
     }
+
+    // ---- MERGE inverts its target × source scan into a per-source-row target
+    // seek (Selection.TryPrepareMergeTargetSeek) when the ON carries a seekable
+    // target equality, no NOT MATCHED BY SOURCE clause forces every target to be
+    // visited, and the target isn't a view. A MERGE does no query-path seek of
+    // its own, so a CacheBuild during one is the inverted target seek; the
+    // declined cases (NMBS clause, non-seekable ON) keep the full scan and never
+    // touch the cache. ----
+
+    private static SimulatedDbConnection FreshTarget()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table tgt (id int not null primary key, v int not null);
+            insert tgt values (1, 10), (2, 20), (3, 30)
+            """);
+        return c;
+    }
+
+    [TestMethod]
+    public void MergeOnPrimaryKey_SeeksTarget()
+    {
+        var c = FreshTarget();
+        var trace = ExecTraced(c, """
+            merge tgt as t
+            using (values (2, 200), (4, 400)) as s(id, v) on t.id = s.id
+            when matched then update set v = s.v
+            when not matched then insert (id, v) values (s.id, s.v);
+            """);
+        Contains("CacheBuild", trace);
+        AreEqual(4, Convert.ToInt32(ReadVal(c, "select count(*) from tgt")));
+        AreEqual(200, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 2"))); // matched → updated
+        AreEqual(400, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 4"))); // not matched → inserted
+        AreEqual(10, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 1")));  // untouched
+    }
+
+    [TestMethod]
+    public void MergeNotMatchedBySource_FullScans()
+    {
+        var c = FreshTarget();
+        // A NOT MATCHED BY SOURCE clause has to visit every target row, so the
+        // inversion declines and the target × source scan stands — no CacheBuild.
+        var trace = ExecTraced(c, """
+            merge tgt as t
+            using (values (2, 200)) as s(id, v) on t.id = s.id
+            when matched then update set v = s.v
+            when not matched by source then delete;
+            """);
+        DoesNotContain("CacheBuild", trace);
+        AreEqual("2", Seq(ReadRows(c, "select id from tgt order by id"))); // 1 and 3 deleted
+        AreEqual(200, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 2")));
+    }
+
+    [TestMethod]
+    public void MergeSeek_ResidualOnTerm_Filters()
+    {
+        var c = new Simulation().CreateDbConnection();
+        c.Open();
+        Exec(c, """
+            create table tgt (id int not null primary key, active int not null, v int not null);
+            insert tgt values (1, 1, 10), (2, 0, 20)
+            """);
+        // ON seeks id; the residual t.active = 1 (re-checked per candidate)
+        // excludes id = 2, so its source row matches nothing and v stays 20.
+        var trace = ExecTraced(c, """
+            merge tgt as t
+            using (values (1, 100), (2, 200)) as s(id, v) on t.id = s.id and t.active = 1
+            when matched then update set v = s.v;
+            """);
+        Contains("CacheBuild", trace);
+        AreEqual(100, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 1")));
+        AreEqual(20, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 2")));
+    }
+
+    [TestMethod]
+    public void MergeNonSeekableOn_FullScans()
+    {
+        var c = FreshTarget();
+        // ON on an unindexed expression (v, no key) — nothing seekable, so the
+        // inversion declines and the scan stands.
+        var trace = ExecTraced(c, """
+            merge tgt as t
+            using (values (20, 999)) as s(v, nv) on t.v = s.v
+            when matched then update set v = s.nv;
+            """);
+        DoesNotContain("CacheBuild", trace);
+        AreEqual(999, Convert.ToInt32(ReadVal(c, "select v from tgt where id = 2")));
+    }
 }

SqlServerSimulator/Parser/Selection.Execution.IndexSeek.cs

@@ -1329,7 +1329,7 @@ private static IEnumerable<byte[]> MaterializeWithLockChecks(
     internal static IEnumerable<(int Page, int Slot, byte[] Bytes)>? SeekMutationTarget(
         HeapTable table, BooleanExpression where, BatchContext batch)
     {
-        var source = BuildBaseTableSeekSource(table);
+        var source = BuildBaseTableSeekSource(table, table.Name);
 
         var conjuncts = new List<BooleanExpression>();
         where.CollectConjuncts(conjuncts);
@@ -1360,18 +1360,82 @@ private static IEnumerable<byte[]> MaterializeWithLockChecks(
         return null;
     }
 
-    // Minimal single-source view of a base table for the mutation seek: real
-    // column names + storage metadata so TryIdentifyIndexableColumn resolves the
-    // WHERE's column references, qualified by the table's own name (the only
-    // qualifier a single-table UPDATE / DELETE WHERE can use). The Rows stream is
-    // unused — the seek reads addresses straight from the heap's cache.
-    private static FromSource BuildBaseTableSeekSource(HeapTable table)
+    /// <summary>
+    /// A per-source-row target seeker for a MERGE whose <c>ON</c> carries a
+    /// seekable equality on the target's leading key / index prefix — returns
+    /// <c>null</c> when no such equality exists (caller keeps its
+    /// <c>target × source</c> scan). The <c>ON</c> conjunct <c>t.k = s.k</c> is
+    /// the correlated-seek shape: <c>t.k</c> resolves to the (single-source)
+    /// target so it's the column side, <c>s.k</c> doesn't so it's a stable outer
+    /// value — exactly what the SELECT path's correlated subquery seek already
+    /// recognizes (<c>allowCorrelatedColumnValue: true</c>). The returned delegate
+    /// takes one source row's resolver and yields the matching target rows; a NULL
+    /// or non-matching probe yields nothing (a valid empty match for that source).
+    /// The structural test (does some key's lead column carry an equality?) is run
+    /// once here, so per-source the delegate only evaluates probes and seeks. The
+    /// caller still re-runs the full <c>ON</c> predicate per candidate — the seek
+    /// keys on the equality prefix only, so a residual <c>ON</c> term
+    /// (<c>… AND t.active = 1</c>) and a stale cache entry are both filtered there.
+    /// </summary>
+    internal static Func<Func<MultiPartName, SqlValue>, IEnumerable<(int Page, int Slot, byte[] Bytes)>>? TryPrepareMergeTargetSeek(
+        HeapTable table, string? targetQualifier, BooleanExpression on, BatchContext batch)
+    {
+        var source = BuildBaseTableSeekSource(table, targetQualifier);
+
+        var conjuncts = new List<BooleanExpression>();
+        on.CollectConjuncts(conjuncts);
+
+        var equalities = new Dictionary<int, Expression[]>();
+        foreach (var conjunct in conjuncts)
+        {
+            if (conjunct.TryGetEqualityOperands(out var left, out var right))
+            {
+                _ = TryRecordColumnEquality(source, left, right, equalities, allowCorrelatedColumnValue: true)
+                    || TryRecordColumnEquality(source, right, left, equalities, allowCorrelatedColumnValue: true);
+                continue;
+            }
+            if (conjunct.TryGetEqualityFamily(out var family))
+                _ = TryRecordEqualityFamily(source, family, equalities, allowCorrelatedColumnValue: true);
+        }
+
+        return HasSeekableLeadingPrefix(table, equalities) ? Seek : null;
+
+        IEnumerable<(int Page, int Slot, byte[] Bytes)> Seek(Func<MultiPartName, SqlValue> outerResolver) =>
+            TryComputeEqualityCandidates(source, table, batch, outerResolver, equalities, out var candidates, out _)
+                ? MaterializeMutationCandidates(table, candidates)
+                : [];
+    }
+
+    // True when some key / index's leading column carries a recorded equality —
+    // the structural precondition for a seek (independent of probe values, so a
+    // per-source NULL probe later reads as an empty match, not "unseekable").
+    private static bool HasSeekableLeadingPrefix(HeapTable table, Dictionary<int, Expression[]> equalities)
+    {
+        foreach (var key in table.KeyConstraints)
+        {
+            if (key.StorageOrdinals.Length > 0 && equalities.ContainsKey(key.StorageOrdinals[0]))
+                return true;
+        }
+        foreach (var index in table.Indexes)
+        {
+            if (index.KeyColumns.Length > 0 && equalities.ContainsKey(index.KeyColumns[0].StorageOrdinal))
+                return true;
+        }
+        return false;
+    }
+
+    // Minimal single-source view of a base table for a seek: real column names +
+    // storage metadata so TryIdentifyIndexableColumn resolves the predicate's
+    // column references, under the given qualifier (the table's own name for a
+    // single-table UPDATE / DELETE, the target alias for a MERGE). The Rows stream
+    // is unused — the seek reads addresses straight from the heap's cache.
+    private static FromSource BuildBaseTableSeekSource(HeapTable table, string? qualifier)
     {
         var columnNames = new string[table.Columns.Length];
         for (var i = 0; i < columnNames.Length; i++)
             columnNames[i] = table.Columns[i].Name;
         return new FromSource(
-            qualifier: table.Name,
+            qualifier: qualifier,
             columnNames: columnNames,
             columns: table.Columns,
             storedSchema: table.StoredColumns,