Documentation Source Text: Check-in [bd399e9806]

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.

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








|







 







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

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