xref: /netbsd-src/external/public-domain/sqlite/man/sqlite3_vtab_in.3 (revision b9988867a8ad969c45a52aa7628bc932ec98d46b)

.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