From: drh <>
Date: Mon, 20 May 2024 16:00:27 +0000 (+0000)
Subject: Improvements to the sqlite3_vtab_distinct() documentation.
X-Git-Tag: version-3.46.0~7^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fheads%2Fvtab-distinct-fix;p=thirdparty%2Fsqlite.git
Improvements to the sqlite3_vtab_distinct() documentation.
FossilOrigin-Name: 6ee041d34f292b94701919f51bbb9e12bcb9e0c4f45e4c0b83f30ff328070637
---
diff --git a/manifest b/manifest
index 401fc0177e..ce10a0198d 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Fix\sthe\sdefinition\sof\ssqlite3_vtab_distinct()\ssuch\sthat\sreturn\scodes\s2\sand\n3\smean\sthat\sall\srows\smust\sbe\sdistinct\sover\s"colUsed"\swhich\sis\sa\ssuperset\sof\n"aOrderBy".\s\sAlso,\sdisallow\sreturn\scodes\s2\sand\s3\sif\sthe\srowid\sof\sthe\svirtual\ntable\sis\saccessed.
-D 2024-05-18T20:00:08.988
+C Improvements\sto\sthe\ssqlite3_vtab_distinct()\sdocumentation.
+D 2024-05-20T16:00:27.117
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -756,7 +756,7 @@ F src/resolve.c 22f1fa3423b377c02ae78d451cfeb1c2d96dcf0389c0642cbdcd19d3bfd7ae01
F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97
F src/select.c 1a841c38974d45cf15a7611398479182b61ad4c187423c380741d8b1688fe607
F src/shell.c.in 8f2406e4e8d726452e48058d117f52e86b789f47435157b0418fb06c631349b6
-F src/sqlite.h.in 6d645f9c2da3b64ea44944024df0c733bba186ee200d849a72a25bf8ae9beac4
+F src/sqlite.h.in c71d9ef76a6d32dc7ff2d373f2e57ce09056af26c1457bcadae5358b7628c7c3
F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
F src/sqlite3ext.h 3f046c04ea3595d6bfda99b781926b17e672fd6d27da2ba6d8d8fc39981dcb54
F src/sqliteInt.h 6a9fa3902c9faca2b57060e822f2afadfbf96d64c4ede81e201f0e0c42d7e4aa
@@ -2191,11 +2191,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 1a073f9acfb691eebf4a8cc78a72ff47ebbb6aba4acede6755fa3faefae48f2b
-R be7ef6a3dcb331720f0112bf3c3e9c8c
-T *branch * vtab-distinct-fix
-T *sym-vtab-distinct-fix *
-T -sym-trunk *
+P 922731ce98c0ce7837784ff7966049e59fa73da2aa04abf3506503b6fc4aa048
+R 65c04e4dfc1793594341c544753e5e70
U drh
-Z 3a71e5f761d3443220a5a5a181b974f3
+Z 4b4899e535e10a58b98edaa878f294f3
# Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index 6968f2e6b3..1200d1128c 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-922731ce98c0ce7837784ff7966049e59fa73da2aa04abf3506503b6fc4aa048
\ No newline at end of file
+6ee041d34f292b94701919f51bbb9e12bcb9e0c4f45e4c0b83f30ff328070637
\ No newline at end of file
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 459af929b1..549b52a153 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -9942,26 +9942,45 @@ const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
**
** ^(If the sqlite3_vtab_distinct() interface returns 2, that means
** that the query planner does not need the rows returned in any particular
-** order, as long as rows with the same values in all "colUsed" columns
-** are adjacent.)^ ^(Furthermore, only a single row for each particular
-** combination of values in the columns identified by the "colUsed" field
-** needs to be returned.)^ ^It is always ok for two or more rows with the same
-** values in all "colUsed" columns to be returned, as long as all such rows
-** are adjacent. ^The virtual table may, if it chooses, omit extra rows
-** that have the same value for all columns identified by "colUsed".
-** ^However omitting the extra rows is optional.
+** order, as long as rows with the same values in all columns identified
+** by "aOrderBy" are adjacent.)^ ^(Furthermore, when two or more rows
+** contain the same values for all columns identified by "colUsed", all but
+** one such row may optionally be omitted from the result.)^
+** The virtual table is not required to omit rows that are duplicates
+** over the "colUsed" columns, but if the virtual table can do that without
+** too much extra effort, it could potentially help the query to run faster.
** This mode is used for a DISTINCT query.
**
-** ^(If the sqlite3_vtab_distinct() interface returns 3, that means
-** that the query planner needs only rows that are distinct over the
-** set of columns defined by "colUsed" but it does need the
-** rows to be sorted according to the order defined by "aOrderBy".)^
-** ^The virtual table implementation is free to omit
-** rows that are identical in all "colUsed" columns, if it wants to, but
-** it is not required to omit any rows. This mode is used for queries
+** ^(If the sqlite3_vtab_distinct() interface returns 3, that means the
+** virtual table must return rows in the order defined by "aOrderBy" as
+** if the sqlite3_vtab_distinct() interface had returned 0. However if
+** two or more rows in the result have the same values for all columns
+** identified by "colUsed", then all but one such row may optionally be
+** omitted.)^ Like when the return value is 2, the virtual table
+** is not required to omit rows that are duplicates over the "colUsed"
+** columns, but if the virtual table can do that without
+** too much extra effort, it could potentially help the query to run faster.
+** This mode is used for queries
** that have both DISTINCT and ORDER BY clauses.
**
**
+**
The following table summarizes the conditions under which the
+** virtual table is allowed to set the "orderByConsumed" flag based on
+** the value returned by sqlite3_vtab_distinct(). This table is a
+** restatement of the previous four paragraphs:
+**
+**
+**
+** | sqlite3_vtab_distinct() return value
+** | Rows are returned in aOrderBy order
+** | Rows with the same value in all aOrderBy columns are adjacent
+** | Duplicates over all colUsed columns may be omitted
+** |
| 0 | yes | yes | no
+** |
| 1 | no | yes | no
+** |
| 2 | no | yes | yes
+** |
| 3 | yes | yes | yes
+** |
+**
** ^For the purposes of comparing virtual table output values to see if the
** values are same value for sorting purposes, two NULL values are considered
** to be the same. In other words, the comparison operator is "IS"