-C Omit\sthe\sWhereLoopBuilder.pOrderBy\sfield,\swhich\sis\sno\slonger\sneeded.
-D 2022-01-22T02:52:22.316
+C Iimproved\sdocumentation\sfor\ssqlite3_vtab_distinct().\s\sNo\schanges\sto\scode.
+D 2022-01-22T19:19:35.721
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92
F src/select.c ab5717255420972e69b9b9ce4d1c4730fe82cfbdc14b7743e389a8bdb79ca027
F src/shell.c.in 4690f216dc4da0c104a8fd9f9e12bec0483242e630324aa7a3ccd155922e346e
-F src/sqlite.h.in 1335c91f118ed8490ab8661becf8ad7d29fe531149464d72ccc095290c872e86
+F src/sqlite.h.in 31c2c8d737814369bd3b71f3849c4a97ef7ede0aa3ce976ecb11632fa5f1f863
F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
F src/sqlite3ext.h 5d54cf13d3406d8eb65d921a0d3c349de6126b732e695e79ecd4830ce86b4f8a
F src/sqliteInt.h 21a31abf60222f50c1d654cdc27ad9d4040249f0341129dd8286b8b5b32bcd30
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P d571262d2345bb11e71bef395cf078e5d7303b974b38b4e319adda6194ccc1c5
-R c8f2432bbe6ecf01b6e5ac0aa57d1f94
+P a13afc909c8bb643aa154b39ba8c023bae7352d3cd7cfb96be3891fa0e4bc045
+R ee7e69afa00103e3a528aaa0afa4a945
U drh
-Z 0649a152fd9646f6591062a2384e3001
+Z f9808520490668283a6ca50de433adb3
# Remove this line to create a well-formed Fossil manifest.
/*
** CAPI3REF: Determine The Collation For a Virtual Table Constraint
+** METHOD: sqlite3_index_info
**
** This function may only be called from within a call to the [xBestIndex]
** method of a [virtual table]. This function returns a pointer to a string
** that is the name of the appropriate collation sequence to use for text
** comparisons on the constraint identified by its arguments.
**
-** The first argument must be the pointer to the sqlite3_index_info object
+** The first argument must be the pointer to the [sqlite3_index_info] object
** that is the first parameter to the xBestIndex() method. The second argument
** must be an index into the aConstraint[] array belonging to the
** sqlite3_index_info structure passed to xBestIndex.
** Important:
** The first parameter must be the same pointer that is passed into the
** xBestMethod() method. The first parameter may not be a pointer to a
-** different sqlite3_index_info object, even an exact copy.
+** different [sqlite3_index_info] object, even an exact copy.
**
** The return value is computed as follows:
**
SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
/*
-** CAPI3REF: Determine if virtual table query is DISTINCT
+** CAPI3REF: Determine if a virtual table query is DISTINCT
** METHOD: sqlite3_index_info
**
** This API may only be used from within an xBestIndex() callback. The
** undefined and probably harmful.
**
** ^The sqlite3_vtab_distinct() returns an integer that is either 0, 1, or
-** 2. ^The sqlite3_vtab_distinct() interface returns 0 if SQLite needs the
-** output rows sorted as defined by the nOrderBy and aOrderBy fields of the
-** [sqlite3_index_info] object P. ^The sqlite3_vtab_distinct() interface
-** returns 1 if SQLite needs all rows to be returned and for equivalent rows
-** to be adjacent to one another, but if it does not require that the rows
-** be sorted. ^The sqlite3_vtab_distinct() interface returns 2 if SQLite only
-** needs the virtual table to return rows that are distinct for the columns
-** identified by the nOrderBy and aOrderBy fields of the [sqlite3_index_info]
-** object. If rows are returned that differ in any of the columns identified
-** by the nOrderBy and aOrderBy fields, then all such rows should be adjacent.
+** 2. The integer returned by sqlite3_vtab_distinct() gives the virtual table
+** additional information about how the query planner wants the output to be
+** ordered. As long as the virtual table can meet the ordering requirements
+** of the query planner, it may set the "orderByConsumed" flag.
+**
+** <ol><li value="0"><p>
+** ^If the sqlite3_vtab_distinct() interface returns 0, that means
+** that the query planner needs the virtual table to return all rows in the
+** sort order defined by the "nOrderBy" and "aOrderBy" fields of the
+** [sqlite3_index_info] object. This is the default expectation. If the
+** virtual table outputs all rows in sorted order, then it is always safe for
+** the xBestIndex method to set the "orderByConsumed" flag, regardless of
+** what the return value from sqlite3_vtab_distinct().
+** <li value="1"><p>
+** ^(If the sqlite3_vtab_distinct() interface returns 1, that means
+** that the query planner does not need the rows to be returned in sorted order
+** as long as all rows with the same values in all columns identified by the
+** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
+** is doing a GROUP BY.
+** <li value="2"><p>
+** ^(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 "aOrderBy" columns
+** are adjacent.)^ ^(Furthermore, only a single row for each particular
+** combination of values in the columns identified by the "aOrderBy" field
+** needs to be returned.)^ ^It is ok always for two or more rows with the same
+** values in all "aOrderBy" 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 "aOrderBy".
+** ^However omitting the extra rows is optional.
+** This mode is used for a DISTINCT query.
+** </ol>
+**
+** ^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"
+** (or "IS NOT DISTINCT FROM") and not "==".
+**
+** If a virtual table implementation is unable to meet the requirements
+** specified above, then it must not set the "orderByConsumed" flag in the
+** [sqlite3_index_info] object or an incorrect answer may result.
+**
+** ^A virtual table implementation is always free to return rows in any order
+** it wants, as long as the "orderByConsumed" flag is not set. ^When the
+** the "orderByConsumed" flag is unset, the query planner will add extra
+** [bytecode] to ensure that the final results returned by the SQL query are
+** ordered correctly. The use of the "orderByConsumed" flag and the
+** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
+** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
+** flag might help queries against a virtual table to run faster. Being
+** overly aggressive and setting the "orderByConsumed" flag when it is not
+** valid to do so, on the other hand, might cause SQLite to return incorrect
+** results.
*/
int sqlite3_vtab_distinct(sqlite3_index_info*);
**
** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
** the [xBestIndex] method of a [virtual table] implementation, with P being
-** a copy of the sqlite3_index_info object pointer passed into xBestIndex and
+** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and
** J being a 0-based index into P->aConstraint[], then this routine
** attempts to set *V to be the value on the right-hand side of
** that constraint if the right-hand side is a known constant. ^If the
projects / thirdparty / sqlite.git / commitdiff
