diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_vtab_in.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_vtab_in.3 | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_vtab_in.3 b/static/netbsd/man3/sqlite3_vtab_in.3 new file mode 100644 index 00000000..28cd5cb8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_in.3 @@ -0,0 +1,96 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_IN 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_in +.Nd identify and handle IN constraints in xBestIndex +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_in +.Fa "sqlite3_index_info*" +.Fa "int iCons" +.Fa "int bHandle" +.Fc +.Sh DESCRIPTION +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. +.Pp +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 positive integer. +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. +.Pp +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: +.Bl -enum +.It +.Pp +A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) if and +only if the P->aConstraintN constraint is an IN operator +that can be processed all at once. +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. +.It +.Pp +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. +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. +.El +.Pp +The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times +within the same xBestIndex method call. +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. +If the interface returns true (non-zero), that means that the constraint +is an IN operator that can be processed all-at-once. +If the constraint is not an IN operator or cannot be processed all-at-once, +then the interface returns false. +.Pp +All-at-once processing of the IN operator is selected if both of the +following conditions are met: +.Bl -enum +.It +.Pp +The P->aConstraintUsageN.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. +.It +.Pp +The last call to sqlite3_vtab_in(P,N,F) for which F was non-negative +had F>=1. +.El +.Pp +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. +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 +.Fn sqlite3_vtab_in_first +and +.Fn sqlite3_vtab_in_next +to find all values on the right-hand side of the IN constraint. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9962. +.Bd -literal +SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle); +.Ed +.Sh SEE ALSO +.Xr sqlite3_index_info 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_vtab_in_first 3 , +.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 |