NAME
sqlite3_index_info —
Virtual Table
Indexing Information
SYNOPSIS
struct sqlite3_index_info;
DESCRIPTION
The sqlite3_index_info structure and its substructures is used as part of the
virtual table interface to pass information into and receive the reply from
the xBestIndex method of a virtual table module. The fields under **Inputs**
are the inputs to xBestIndex and are read-only. xBestIndex inserts its results
into the **Outputs** fields.
The aConstraint[] array records WHERE clause constraints of the form:
column OP expr
where OP is =, <, <=, >, or >=. The particular operator is stored in
aConstraint[].op using one of the SQLITE_INDEX_CONSTRAINT_ values. The index
of the column is stored in aConstraint[].iColumn. aConstraint[].usable is TRUE
if the expr on the right-hand side can be evaluated (and thus the constraint
is usable) and false if it cannot.
The optimizer automatically inverts terms of the form "expr OP column"
and makes other simplifications to the WHERE clause in an attempt to get as
many WHERE clause terms into the form shown above as possible. The
aConstraint[] array only reports WHERE clause terms that are relevant to the
particular virtual table being queried.
Information about the ORDER BY clause is stored in aOrderBy[]. Each term of
aOrderBy records a column of the ORDER BY clause.
The colUsed field indicates which columns of the virtual table may be required
by the current scan. Virtual table columns are numbered from zero in the order
in which they appear within the CREATE TABLE statement passed to
sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), the
corresponding bit is set within the colUsed mask if the column may be required
by SQLite. If the table has at least 64 columns and any column to the right of
the first 63 is required, then bit 63 of colUsed is also set. In other words,
column iCol may be required if the expression (colUsed &
((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to non-zero.
The xBestIndex method must fill aConstraintUsage[] with information about what
parameters to pass to xFilter. If argvIndex>0 then the right-hand side of
the corresponding aConstraint[] is evaluated and becomes the argvIndex-th
entry in argv. If aConstraintUsage[].omit is true, then the constraint is
assumed to be fully handled by the virtual table and is not checked again by
SQLite.
The idxNum and idxPtr values are recorded and passed into the xFilter method.
sqlite3_free() is used to free idxPtr if and only if needToFreeIdxPtr is true.
The orderByConsumed means that output from xFilter/xNext will occur in the
correct order to satisfy the ORDER BY clause so that no separate sorting step
is required.
The estimatedCost value is an estimate of the cost of a particular strategy. A
cost of N indicates that the cost of the strategy is similar to a linear scan
of an SQLite table with N rows. A cost of log(N) indicates that the expense of
the operation is similar to that of a binary search on a unique indexed field
of an SQLite table with N rows.
The estimatedRows value is an estimate of the number of rows that will be
returned by the strategy.
The xBestIndex method may optionally populate the idxFlags field with a mask of
SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
assumes that the strategy may visit at most one row.
Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then SQLite
also assumes that if a call to the xUpdate() method is made as part of the
same statement to delete or update a virtual table row and the implementation
returns SQLITE_CONSTRAINT, then there is no need to rollback any database
changes. In other words, if the xUpdate() returns SQLITE_CONSTRAINT, the
database contents must be exactly as they were before xUpdate was called. By
contrast, if SQLITE_INDEX_SCAN_UNIQUE is not set and xUpdate returns
SQLITE_CONSTRAINT, any database changes made by the xUpdate method are
automatically rolled back by SQLite.
IMPORTANT: The estimatedRows field was added to the sqlite3_index_info structure
for SQLite version 3.8.2 (dateof:3.8.2). If a virtual table extension is used
with an SQLite version earlier than 3.8.2, the results of attempting to read
or write the estimatedRows field are undefined (but are likely to included
crashing the application). The estimatedRows field should therefore only be
used if sqlite3_libversion_number() returns a value greater than or equal to
3008002. Similarly, the idxFlags field was added for version 3.9.0
(dateof:3.9.0). It may therefore only be used if sqlite3_libversion_number()
returns a value greater than or equal to 3009000.
SEE ALSO
sqlite3_malloc(3),
sqlite3_version(3),
SQLITE_INDEX_CONSTRAINT_EQ(3),
sqlite3_module(3)