Documentation Source Text

Check-in [77f80a4186]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for sqlite3_index_info.estimatedRows, part of the virtual table interface.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 77f80a4186dbd7b811a7af044d54039b11d55752
User & Date: dan 2014-07-24 14:39:19
Context
2014-07-24
15:36
Add a change log for version 3.8.6. Update the home page for version 3.8.6. check-in: 0d81c00b9a user: drh tags: trunk
14:39
Add documentation for sqlite3_index_info.estimatedRows, part of the virtual table interface. check-in: 77f80a4186 user: dan tags: trunk
14:27
Add documentation on the hexadecimal integer notation. check-in: 4656303de6 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/vtab.in.

473
474
475
476
477
478
479


480
481







482
483
484
485
486
487
488
...
626
627
628
629
630
631
632





633
634
635
636
637
638
639
      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 */


  };
</pre></blockquote>








<p>In addition, there are some defined constants:

<blockquote><pre>
  #define SQLITE_INDEX_CONSTRAINT_EQ    2
  #define SQLITE_INDEX_CONSTRAINT_GT    4
  #define SQLITE_INDEX_CONSTRAINT_LE    8
................................................................................
separate sorting pass over the data after it comes out of the virtual table.

<p>The estimatedCost field should be set to the estimated number
of disk access operations required to execute this query against 
the virtual table. The SQLite core will often call xBestIndex 
multiple times with different constraints, obtain multiple cost
estimates, then choose the query plan that gives the lowest estimate.






<p>The aConstraintUsage[] array contains one element for each of 
the nConstraint constraints in the inputs section of the 
[sqlite3_index_info] structure. 
The aConstraintUsage[] array is used by xBestIndex to tell the 
core how it is using the constraints.








>
>


>
>
>
>
>
>
>







 







>
>
>
>
>







473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
...
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
      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 */
    <b>/* Fields below are only available in SQLite 3.8.2 and later */</b>
    sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */
  };
</pre></blockquote>

<p>Please note the warning above the "estimatedRows" field. This field was
added to the structure beginning with SQLite version 3.8.2. This means that any
extension that reads or writes this field must first check that the version of
the SQLite library in use is greater than or equal to 3.8.2 - perhaps using
a call to [sqlite3_version()]. The results of attempting to access this field
within a structure created by an older version of SQLite are undefined.

<p>In addition, there are some defined constants:

<blockquote><pre>
  #define SQLITE_INDEX_CONSTRAINT_EQ    2
  #define SQLITE_INDEX_CONSTRAINT_GT    4
  #define SQLITE_INDEX_CONSTRAINT_LE    8
................................................................................
separate sorting pass over the data after it comes out of the virtual table.

<p>The estimatedCost field should be set to the estimated number
of disk access operations required to execute this query against 
the virtual table. The SQLite core will often call xBestIndex 
multiple times with different constraints, obtain multiple cost
estimates, then choose the query plan that gives the lowest estimate.

<p>If the current version of SQLite is 3.8.2 or greater, the estimatedRows
field may be set to an estimate of the number of rows returned by the
proposed query plan. If this value is not explicitly set, the default 
estimate of 25 rows is used.

<p>The aConstraintUsage[] array contains one element for each of 
the nConstraint constraints in the inputs section of the 
[sqlite3_index_info] structure. 
The aConstraintUsage[] array is used by xBestIndex to tell the 
core how it is using the constraints.