*** DRAFT ***
int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
This interface may only be used from within an xBestIndex() method of a virtual table implementation. The result of invoking this interface from any other context is undefined and probably harmful.
R-40842-63945:[A constraint on a virtual table of the form "column IN (...)" is communicated to the xBestIndex method as a SQLITE_INDEX_CONSTRAINT_EQ constraint. ] If xBestIndex wants to use this constraint, it must set the corresponding aConstraintUsage[].argvIndex to a postive integer. R-05285-60272:[Then, under the usual mode of handling IN operators, SQLite generates bytecode that invokes the xFilter() method once for each value on the right-hand side of the IN operator. ] Thus the virtual table only sees a single value from the right-hand side of the IN operator at a time.
In some cases, however, it would be advantageous for the virtual table to see all values on the right-hand of the IN operator all at once. The sqlite3_vtab_in() interfaces facilitates this in two ways:
R-48752-58459:[A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) if and only if the P->aConstraint[N] constraint is an IN operator that can be processed all at once. ] R-19441-39473:[In other words, sqlite3_vtab_in() with -1 in the third argument is a mechanism by which the virtual table can ask SQLite if all-at-once processing of the IN operator is even possible. ]
R-61787-30047:[A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates to SQLite that the virtual table does or does not want to process the IN operator all-at-once, respectively. ] R-19651-13392:[Thus when the third parameter (F) is non-negative, this interface is the mechanism by which the virtual table tells SQLite how it wants to process the IN operator. ]
R-61030-07741:[The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times within the same xBestIndex method call. ] R-47993-15116:[For any given P,N pair, the return value from sqlite3_vtab_in(P,N,F) will always be the same within the same xBestIndex call. ] R-63112-34944:[If the interface returns true (non-zero), that means that the constraint is an IN operator that can be processed all-at-once. ] R-01440-04765:[If the constraint is not an IN operator or cannot be processed all-at-once, then the interface returns false. ]
R-36885-25505:[All-at-once processing of the IN operator is selected if both of the following conditions are met:
The P->aConstraintUsage[N].argvIndex value is set to a positive integer. This is how the virtual table tells SQLite that it wants to use the N-th constraint.
The last call to sqlite3_vtab_in(P,N,F) for which F was non-negative had F>=1.
R-47011-48090:[If either or both of the conditions above are false, then SQLite uses the traditional one-at-a-time processing strategy for the IN constraint. ] R-60379-28396:[If both conditions are true, then the argvIndex-th parameter to the xFilter method will be an sqlite3_value that appears to be NULL, but which can be passed to sqlite3_vtab_in_first() and sqlite3_vtab_in_next() to find all values on the right-hand side of the IN constraint. ]
See also lists of Objects, Constants, and Functions.
*** DRAFT ***