1.Dd January 24, 2024 2.Dt SQLITE3_VTAB_IN 3 3.Os 4.Sh NAME 5.Nm sqlite3_vtab_in 6.Nd identify and handle IN constraints in xBestIndex 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_vtab_in 11.Fa "sqlite3_index_info*" 12.Fa "int iCons" 13.Fa "int bHandle" 14.Fc 15.Sh DESCRIPTION 16This interface may only be used from within an xBestIndex() method 17of a virtual table implementation. 18The result of invoking this interface from any other context is undefined 19and probably harmful. 20.Pp 21A constraint on a virtual table of the form "column IN (...)" 22is communicated to the xBestIndex method as a SQLITE_INDEX_CONSTRAINT_EQ 23constraint. 24If xBestIndex wants to use this constraint, it must set the corresponding 25aConstraintUsage[].argvIndex to a positive integer. 26Then, under the usual mode of handling IN operators, SQLite generates 27bytecode that invokes the xFilter() method 28once for each value on the right-hand side of the IN operator. 29Thus the virtual table only sees a single value from the right-hand 30side of the IN operator at a time. 31.Pp 32In some cases, however, it would be advantageous for the virtual table 33to see all values on the right-hand of the IN operator all at once. 34The sqlite3_vtab_in() interfaces facilitates this in two ways: 35.Bl -enum 36.It 37.Pp 38A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) if and 39only if the P->aConstraintN constraint is an IN operator 40that can be processed all at once. 41In other words, sqlite3_vtab_in() with -1 in the third argument is 42a mechanism by which the virtual table can ask SQLite if all-at-once 43processing of the IN operator is even possible. 44.It 45.Pp 46A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates to SQLite 47that the virtual table does or does not want to process the IN operator 48all-at-once, respectively. 49Thus when the third parameter (F) is non-negative, this interface is 50the mechanism by which the virtual table tells SQLite how it wants 51to process the IN operator. 52.El 53.Pp 54The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times 55within the same xBestIndex method call. 56For any given P,N pair, the return value from sqlite3_vtab_in(P,N,F) 57will always be the same within the same xBestIndex call. 58If the interface returns true (non-zero), that means that the constraint 59is an IN operator that can be processed all-at-once. 60If the constraint is not an IN operator or cannot be processed all-at-once, 61then the interface returns false. 62.Pp 63All-at-once processing of the IN operator is selected if both of the 64following conditions are met: 65.Bl -enum 66.It 67.Pp 68The P->aConstraintUsageN.argvIndex value is set to a positive integer. 69This is how the virtual table tells SQLite that it wants to use the 70N-th constraint. 71.It 72.Pp 73The last call to sqlite3_vtab_in(P,N,F) for which F was non-negative 74had F>=1. 75.El 76.Pp 77If either or both of the conditions above are false, then SQLite uses 78the traditional one-at-a-time processing strategy for the IN constraint. 79If both conditions are true, then the argvIndex-th parameter to the 80xFilter method will be an sqlite3_value that appears to 81be NULL, but which can be passed to 82.Fn sqlite3_vtab_in_first 83and 84.Fn sqlite3_vtab_in_next 85to find all values on the right-hand side of the IN constraint. 86.Sh IMPLEMENTATION NOTES 87These declarations were extracted from the 88interface documentation at line 9962. 89.Bd -literal 90SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle); 91.Ed 92.Sh SEE ALSO 93.Xr sqlite3_index_info 3 , 94.Xr sqlite3_value 3 , 95.Xr sqlite3_vtab_in_first 3 , 96.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 97