Choose any three.
|
|
SQLite C Interface
Virtual Table Indexing Information
struct sqlite3_index_info {
/* Inputs */
int nConstraint; /* Number of entries in aConstraint */
struct sqlite3_index_constraint {
int iColumn; /* Column on left-hand side of constraint */
unsigned char op; /* Constraint operator */
unsigned char usable; /* True if this constraint is usable */
int iTermOffset; /* Used internally - xBestIndex should ignore */
} *aConstraint; /* Table of WHERE clause constraints */
int nOrderBy; /* Number of terms in the ORDER BY clause */
struct sqlite3_index_orderby {
int iColumn; /* Column number */
unsigned char desc; /* True for DESC. False for ASC. */
} *aOrderBy; /* The ORDER BY clause */
/* Outputs */
struct sqlite3_index_constraint_usage {
int argvIndex; /* if >0, constraint is part of argv to xFilter */
unsigned char omit; /* Do not code a test for this constraint */
} *aConstraintUsage;
int idxNum; /* Number used to identify the index */
char *idxStr; /* String, possibly obtained from sqlite3_malloc */
int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
int orderByConsumed; /* True if output is already ordered */
double estimatedCost; /* Estimated cost of using this index */
/* Fields below are only available in SQLite 3.8.2 and later */
sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
};
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 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.
IMPORTANT: The estimatedRows field was added to the sqlite3_index_info structure for SQLite version 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.