Add comments to sqlite.h.in describing the change on this branch.

FossilOrigin-Name: 19038620cd8326a4f4e7ef9dcceef3f93bfb47323df3c9cb7e881fdfc6b09c49

diff --git a/manifest b/manifest
index 60bd88585ada3e74a790f8da4f29577e719da432..b2d4b2ae21e5be90997f1ef4d94260571bb49597 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Merge\slatest\strunk\schanges\sinto\sthis\sbranch.
-D 2025-07-14T18:03:23.184
+C Add\scomments\sto\ssqlite.h.in\sdescribing\sthe\schange\son\sthis\sbranch.
+D 2025-07-14T18:59:45.531
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -788,7 +788,7 @@ F src/resolve.c d3ee7ed308d46f4ee6d3bb6316d8d6f87158f93a7fd616732138cc953cf364f0
 F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97
 F src/select.c fc003cad96a105765261f7b6c5f4596e505894262bb5593cb29e10b682800d12
 F src/shell.c.in 73c0eeb7c265d59b99219d5aa055f412f07842088d8036b6d259927d85dd1bbf
-F src/sqlite.h.in 1164b84f4cd0e9bcc78beafb7057e671bf88e91f1ec69b90dd915e3dbe1ee7ca
+F src/sqlite.h.in 65939c73f3a0fa9cd2da409a1cc27b3abbf758621736c5ce8030dc072bf8affa
 F src/sqlite3.rc 015537e6ac1eec6c7050e17b616c2ffe6f70fca241835a84a4f0d5937383c479
 F src/sqlite3ext.h 0bfd049bb2088cc44c2ad54f2079d1c6e43091a4e1ce8868779b75f6c1484f1e
 F src/sqliteInt.h 984e80f6cfdb1cd65ab465d14d82b6b56af4f7dc308c4bc1da85074a5b4ca755
@@ -2214,8 +2214,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 1ad0169b022b280bcaaf94a7fa231591be96b514230ab5c98fbf15cd7df842dd
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P b67babf1ab44ff13aea5c644e03da7cbcd16b9f6b840375e41fe483261681b7c 63ddc215eb6106985c53d3c8d99f5445a92acf4359a6bb2681882c49583df871
-R 213e35af82c50282a7078971b7210637
+P 8f9d6acaf7e15ca593da466ee83e88da9b718f17579ae8626040f28f071aeb18
+R 672dc7971b629909624541e24505c083
 U dan
-Z 561cee1843624b72af8850fd14292987
+Z 50975b6812ff50105ef5988478dc3210
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index f0b5c9d4bdc63ff49af1fea5e9713684766611b2..44f396803697173f4d9324d2b1ada03c85ec26b4 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-8f9d6acaf7e15ca593da466ee83e88da9b718f17579ae8626040f28f071aeb18
+19038620cd8326a4f4e7ef9dcceef3f93bfb47323df3c9cb7e881fdfc6b09c49

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index cb109c4353bff34c6a9e59fd9db5047813435048..b642a9ee9a09639f45369fd5f9a2ee785fdd35a6 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -7633,6 +7633,31 @@ struct sqlite3_module {
 ** ^The estimatedRows value is an estimate of the number of rows that
 ** will be returned by the strategy.
 **
+** The estimatedSetup field is used to specify the estimated one-time setup
+** cost of a query strategy, which is typically incurred during the first 
+** call to xFilter. In most cases, this value should be zero. However, if 
+** the strategy requires initialization of an internal index or data 
+** structure - similar to SQLite's native [automatic indexes] - a non-zero 
+** value may be used to reflect that overhead.
+**
+** A negative value for estimatedSetup is treated by SQLite as zero.
+**
+** When the xBestIndex method is invoked, estimatedSetup may be initialized
+** to either 0.0 or to a negative value. If it is set to a negative value,
+** then SQLite is requesting a strategy with no (or minimal) setup cost. The
+** virtual table implementation does not have to honor the request, but
+** it may be more efficient to do so.
+**
+** In practice, xBestIndex is usually invoked with estimatedSetup initialized
+** to 0.0. If the implementation then returns a strategy with estimatedSetup
+** set to a value greater than 0.0, then SQLite invokes the xBestIndex method 
+** a second time with the same parameters, except this time with estimatedSetup
+** initialized to a negative value. This allows the virtual table to present 
+** two different strategies - one with a higher setup cost and potentially
+** lower per-row cost, and another with minimal setup cost - enabling the 
+** query planner to make an informed decision based on query-specific 
+** tradeoffs.
+**
 ** The xBestIndex method may optionally populate the idxFlags field with a
 ** mask of SQLITE_INDEX_SCAN_* flags. One such flag is
 ** [SQLITE_INDEX_SCAN_HEX], which if set causes the [EXPLAIN QUERY PLAN]