From: drh <> Date: Sat, 22 Jan 2022 19:19:35 +0000 (+0000) Subject: Iimproved documentation for sqlite3_vtab_distinct(). No changes to code. X-Git-Tag: version-3.38.0~96^2~1 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9b9fc74f2eafeb8a280198ee7209c8ccefe6a108;p=thirdparty%2Fsqlite.git Iimproved documentation for sqlite3_vtab_distinct(). No changes to code. FossilOrigin-Name: 7af03f02940b5380ee7375672ca8d0ff68c5f741d0ea206911631f3eb5a78555 --- diff --git a/manifest b/manifest index b4574239e7..00218ad384 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -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 @@ -554,7 +554,7 @@ F src/resolve.c 359bc0e445d427583d2ab6110433a5dc777f64a0ecdf8d24826d8b475233ead9 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 @@ -1941,8 +1941,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 d571262d2345bb11e71bef395cf078e5d7303b974b38b4e319adda6194ccc1c5 -R c8f2432bbe6ecf01b6e5ac0aa57d1f94 +P a13afc909c8bb643aa154b39ba8c023bae7352d3cd7cfb96be3891fa0e4bc045 +R ee7e69afa00103e3a528aaa0afa4a945 U drh -Z 0649a152fd9646f6591062a2384e3001 +Z f9808520490668283a6ca50de433adb3 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index c378259f5f..fb902954b0 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -a13afc909c8bb643aa154b39ba8c023bae7352d3cd7cfb96be3891fa0e4bc045 \ No newline at end of file +7af03f02940b5380ee7375672ca8d0ff68c5f741d0ea206911631f3eb5a78555 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 1e78911129..4b36233b37 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -9471,13 +9471,14 @@ int sqlite3_vtab_nochange(sqlite3_context*); /* ** 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. @@ -9485,7 +9486,7 @@ int sqlite3_vtab_nochange(sqlite3_context*); ** 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: ** @@ -9504,7 +9505,7 @@ int sqlite3_vtab_nochange(sqlite3_context*); 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 @@ -9512,16 +9513,59 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int); ** 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. +** +**

  1. +** ^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(). +**

  2. +** ^(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. +**

  3. +** ^(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. +**

+** +** ^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*); @@ -9535,7 +9579,7 @@ 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