*** DRAFT ***

SQLite Requirement Matrix Details
vtab_in.html

Index Summary Markup Original


R-40842-63945-47552-49146-54322-06556-53449-29032 tcl slt th3 src

A constraint on a virtual table of the form "column IN (...)" is communicated to the xBestIndex method as a SQLITE_INDEX_CONSTRAINT_EQ constraint.

/* IMP: R-40842-63945 */
# EVIDENCE-OF: 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.

R-05285-60272-09922-62033-18210-31943-35280-46624 tcl slt th3 src

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.

/* IMP: R-05285-60272 */
# EVIDENCE-OF: 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.

R-48752-58459-43335-39214-58584-56522-10495-27152 tcl slt th3 src

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.

/* IMP: R-48752-58459 */
# EVIDENCE-OF: 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-56265-40787-18174-36980-59541-17858 tcl slt th3 src

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.

/* IMP: R-19441-39473 */
# EVIDENCE-OF: 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-57212-17703-61133-61221-34356-50389 tcl slt th3 src

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.

/* IMP: R-61787-30047 */
# EVIDENCE-OF: 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-21479-00254-25512-03039-17979-35123 tcl slt th3 src

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.

/* IMP: R-19651-13392 */
# EVIDENCE-OF: 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-23809-31922-35879-55755-23580-02409 tcl slt th3 src

The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times within the same xBestIndex method call.

/* IMP: R-61030-07741 */
# EVIDENCE-OF: 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-21733-48888-04976-39029-50790-47089 tcl slt th3 src

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.

/* IMP: R-47993-15116 */
# EVIDENCE-OF: 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-34179-41157-25567-47419-36770-60612 tcl slt th3 src

If the interface returns true (non-zero), that means that the constraint is an IN operator that can be processed all-at-once.

/* IMP: R-63112-34944 */
# EVIDENCE-OF: 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-48174-15543-37673-24749-20235-52074 tcl slt th3 src

If the constraint is not an IN operator or cannot be processed all-at-once, then the interface returns false.

/* IMP: R-01440-04765 */
# EVIDENCE-OF: 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-12420-31937-05570-33633-11902-61321 tcl slt th3 src

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

  1. 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.

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

/* IMP: R-36885-25505 */
# EVIDENCE-OF: 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-41554-54348-35857-62405-59159-33091 tcl slt th3 src

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.

/* IMP: R-47011-48090 */
# EVIDENCE-OF: 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-59672-52502-37778-52591-48911-05246 tcl slt th3 src

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.

/* IMP: R-60379-28396 */
# EVIDENCE-OF: 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.