Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

SQLITE3_VTAB_IN(3)         Library Functions Manual         SQLITE3_VTAB_IN(3)

NAME
     sqlite3_vtab_in - identify and handle IN constraints in xBestIndex

SYNOPSIS
     #include <sqlite3.h>

     int
     sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);

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.

     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.

     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:

     1.

          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.

     2.

          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.

     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.

     All-at-once processing of the IN operator is selected if both of the
     following conditions are met:

     1.

          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.

     2.

          The last call to sqlite3_vtab_in(P,N,F) for which F was non-negative
          had F>=1.

     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 sqlite3_vtab_in_first() and sqlite3_vtab_in_next() to find all
     values on the right-hand side of the IN constraint.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 9850.

     SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);

SEE ALSO
     sqlite3_index_info(3), sqlite3_value(3), sqlite3_vtab_in_first(3),
     SQLITE_INDEX_CONSTRAINT_EQ(3)

NetBSD 10.99                    August 24, 2023                   NetBSD 10.99