SQLite CVSTrac

Page History

This document describes the xBestIndex method of a virtual table implementation. If you have not already read about VirtualTables you should do so before reading this page. You might also want to read about the other virtual table methods prior to perusing the following text.

The xBestIndex method has a prototype like this:

  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);

Most of the input and output to and from the xBestIndex method occurs inside the sqlite3_index_info structure. The sqlite3_index_info structure looks like this:

  struct sqlite3_index_info {
    /* Inputs */
    const int nConstraint;     /* Number of entries in aConstraint */
    const 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 */
    } *const aConstraint;      /* Table of WHERE clause constraints */
    const int nOrderBy;        /* Number of terms in the ORDER BY clause */
    const struct sqlite3_index_orderby {
       int iColumn;              /* Column number */
       unsigned char desc;       /* True for DESC.  False for ASC. */
    } *const 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 */
    } *const 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 */
  };

In addition, there are some defined constants:

  #define SQLITE_INDEX_CONSTRAINT_EQ    2
  #define SQLITE_INDEX_CONSTRAINT_GT    4
  #define SQLITE_INDEX_CONSTRAINT_LE    8
  #define SQLITE_INDEX_CONSTRAINT_LT    16
  #define SQLITE_INDEX_CONSTRAINT_GE    32
  #define SQLITE_INDEX_CONSTRAINT_MATCH 64

The sqlite3_index_info and the constants shown above are all defined in the sqlite3.h header file.

sqlite - Virtual Table Best Index Method

Page History