From ae9c69d3ccbf5392d17c952ddd0f5325975b9666 Mon Sep 17 00:00:00 2001 From: Taylor Bantle Date: Wed, 8 Jul 2026 15:33:02 -0700 Subject: [PATCH] docs: document DOLT_DIFF() secondary-index optimization dolthub/dolt@c96100db07 and c77dec5ce9 (since v2.1.10, unreleased) let DOLT_DIFF() use a covering secondary index instead of always scanning the primary index, when one index covers every non-generated column of the table at both revisions. Add a Performance note explaining the eligibility requirement. Reviewed dolt's commit log since v2.1.10 for other SQL-surface changes; everything else in that range is internal (nbs/gitblobstore, gRPC load balancing, an adaptive-encoding bug fix) with no user-visible SQL behavior to document. Co-Authored-By: Claude Sonnet 5 --- .../reference/sql/version-control/dolt-sql-functions.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/site/dolt/src/content/reference/sql/version-control/dolt-sql-functions.md b/site/dolt/src/content/reference/sql/version-control/dolt-sql-functions.md index 7a53b89..b9fb426 100644 --- a/site/dolt/src/content/reference/sql/version-control/dolt-sql-functions.md +++ b/site/dolt/src/content/reference/sql/version-control/dolt-sql-functions.md @@ -253,6 +253,15 @@ Note that the `DOLT_DIFF()` table function currently requires that argument valu `DOLT_DIFF()` table function requires `SELECT` privilege on the specified table. +#### Performance + +`DOLT_DIFF()` normally scans the table's primary index at both revisions, which means it always pays for a +full table scan even if you only care about a few rows. If a secondary index exists that covers every +non-generated column of the table — at both the `from_revision` and `to_revision` schemas — Dolt will use +that index instead, which can be significantly faster for large tables. An index that only covers part of +the table's columns (including one that only covers the primary key) is not eligible, since it can't be used +to detect every kind of change; add the missing columns to the index if you want `DOLT_DIFF()` to pick it up. + #### Options ```sql