Documentation Source Text

Check-in [bd399e9806]
Login

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

Overview
Comment:Update the virtual table documentation with information about the new operators passed into xBestIndex.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: bd399e9806f3e1060ad8b72aed5d4d897f5c4eb972b289ae9a67201220b704fd
User & Date: drh 2017-09-12 00:44:05
Context
2017-09-13
04:08
Add a line to the change log for the recent pragma integrity_check enhancement. check-in: 12d0f93647 user: drh tags: trunk
2017-09-12
00:44
Update the virtual table documentation with information about the new operators passed into xBestIndex. check-in: bd399e9806 user: drh tags: trunk
2017-09-11
23:48
Add the b899b6042f97f5 ticket fix to the change log. check-in: 5257ab389b user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/vtab.in.

421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
...
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675





676
677
678
679
680
681
682
683
been reported up to the application.

<p>
If the xCreate method is omitted (left as a NULL pointer) then the
virtual table is an [eponymous-only virtual table].  New instances of
the virtual table cannot be created using [CREATE VIRTUAL TABLE] and the
virtual table can only be used via its module name.
Note that SQLite versions prior to 3.9.0 do not understand
eponymous-only virtual tables and will segfault if an attempt is made
to [CREATE VIRTUAL TABLE] on an eponymous-only virtual table because
the xCreate method was not checked for null.

<p>
If the xCreate method is the exact same pointer as the [xConnect] method,
that indicates that the virtual table does not need to initialize backing
................................................................................
against constants 3008002, 3009000, and/or 3010000. The result of attempting 
to access these fields in an sqlite3_index_info structure created by an 
older version of SQLite are undefined.

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

<codeblock>
  #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
  #define SQLITE_INDEX_CONSTRAINT_LIKE   65     /* 3.10.0 and later only */
  #define SQLITE_INDEX_CONSTRAINT_GLOB   66     /* 3.10.0 and later only */
  #define SQLITE_INDEX_CONSTRAINT_REGEXP 67     /* 3.10.0 and later only */





  #define SQLITE_INDEX_SCAN_UNIQUE        1     /* Scan visits at most 1 row */
</codeblock>

<p>The SQLite core calls the xBestIndex method when it is compiling a query
that involves a virtual table. In other words, SQLite calls this method 
when it is running [sqlite3_prepare()] or the equivalent. 
By calling this method, the 
SQLite core is saying to the virtual table that it needs to access 







|







 







|
|
|
|
|
|
|
|
|
>
>
>
>
>
|







421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
...
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
been reported up to the application.

<p>
If the xCreate method is omitted (left as a NULL pointer) then the
virtual table is an [eponymous-only virtual table].  New instances of
the virtual table cannot be created using [CREATE VIRTUAL TABLE] and the
virtual table can only be used via its module name.
Note that SQLite versions prior to 3.9.0 ([dateof:3.9.0]) do not understand
eponymous-only virtual tables and will segfault if an attempt is made
to [CREATE VIRTUAL TABLE] on an eponymous-only virtual table because
the xCreate method was not checked for null.

<p>
If the xCreate method is the exact same pointer as the [xConnect] method,
that indicates that the virtual table does not need to initialize backing
................................................................................
against constants 3008002, 3009000, and/or 3010000. The result of attempting 
to access these fields in an sqlite3_index_info structure created by an 
older version of SQLite are undefined.

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

<codeblock>
  #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
  #define SQLITE_INDEX_CONSTRAINT_LIKE      65  /* 3.10.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_GLOB      66  /* 3.10.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_REGEXP    67  /* 3.10.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_NE        68  /* 3.21.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_ISNOT     69  /* 3.21.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70  /* 3.21.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_ISNULL    71  /* 3.21.0 and later */
  #define SQLITE_INDEX_CONSTRAINT_IS        72  /* 3.21.0 and later */
  #define SQLITE_INDEX_SCAN_UNIQUE           1  /* Scan visits at most 1 row */
</codeblock>

<p>The SQLite core calls the xBestIndex method when it is compiling a query
that involves a virtual table. In other words, SQLite calls this method 
when it is running [sqlite3_prepare()] or the equivalent. 
By calling this method, the 
SQLite core is saying to the virtual table that it needs to access