Documentation Source Text

chng {2013-10-?? (3.8.1)} {
<li>Added the [unlikely()] and [likelihood()] SQL functions to be used
    as hints to the query planner.
<li>Added the [soft_heap_limit pragma].
<li>Tweaked the query planner to take into account WHERE clause terms
    that cannot be used with indices.
<li>Added support for SQLITE_ENABLE_STAT4
<li>Added the [SQLITE_MINIMUM_FILE_DESCRIPTOR] compile-time option
<li>Added the win32-longpath VFS on windows.
<li>The [Date And Time Functions] are enhanced so that the current time
    (ex: julianday('now')) is always the same for multiple function invocations
    within the same [sqlite3_step()] call.
}

chng {2013-10-?? (3.8.1)} {
<li>Added the [unlikely()] and [likelihood()] SQL functions to be used
    as hints to the query planner.
<li>Added the [soft_heap_limit pragma].
<li>Tweaked the query planner to take into account WHERE clause terms
    that cannot be used with indices.
<li>Added support for [SQLITE_ENABLE_STAT4]
<li>Added the [SQLITE_MINIMUM_FILE_DESCRIPTOR] compile-time option
<li>Added the win32-longpath VFS on windows.
<li>The [Date And Time Functions] are enhanced so that the current time
    (ex: julianday('now')) is always the same for multiple function invocations
    within the same [sqlite3_step()] call.
}

COMPILE_OPTION {SQLITE_MINIMUM_FILE_DESCRIPTOR=<i>N</i>} {
  The unix [VFS] will never use a file descriptor less than <i>N</i>.  The
  default value of <i>N</i> is 3.
  <p>
  Avoiding the use of low-numbered file descriptors is a defense against
  accidental database corruption.  If a database file was opened using
  file descriptor 2, for example, and then an assert() failed and invoked
  write(2,...), that would likely cause database corruption.  Using only

  higher-valued file descriptors avoids that problem.  The protection against

  using low-numbered file descriptiors can be disabled by setting this
  compile-time option to 0.
}

COMPILE_OPTION {SQLITE_POWERSAFE_OVERWRITE=<i>&lt;0 or 1&gt;</i>} {
  This option changes the default assumption about [powersafe overwrite]
  for the underlying filesystems for the unix and windows [VFSes].
  Setting SQLITE_POWERSAFE_OVERWRITE to 1 causes SQLite to assume that
................................................................................
  is now a no-op.
}

COMPILE_OPTION {SQLITE_ENABLE_STAT3} {
  This option adds additional logic to the [ANALYZE] command and to
  the [query planner] that can help SQLite to chose a better query plan
  under certain situations.  The [ANALYZE] command is enhanced to collect
  histogram data from each index and store that data
  in the <b>sqlite_stat3</b> table.  The query planner will then use the
  histogram data to help it make better index choices.

}

COMPILE_OPTION {SQLITE_ENABLE_STAT4} {
  This option adds additional logic to the [ANALYZE] command and to
  the [query planner] that can help SQLite to chose a better query plan
  under certain situations.  The [ANALYZE] command is enhanced to collect
  histogram data from each index and store that data
  in the <b>sqlite_stat4</b> table.  The query planner will then use the
  histogram data to help it make better index choices.
  <p>





  [SQLITE_ENABLE_STAT3] is a no-op if this compile-time option is used.
}

COMPILE_OPTION {SQLITE_ENABLE_TREE_EXPLAIN} {
  This option adds support for the [SQLITE_TESTCTRL_EXPLAIN_STMT] test-control
  in the SQLite core.  When the [command-line shell] is also compiled with
  this option, the ".explain" dot-command enables a mode that uses the
  [SQLITE_TESTCTRL_EXPLAIN_STMT] interface to display an ASCII-art diagram

COMPILE_OPTION {SQLITE_MINIMUM_FILE_DESCRIPTOR=<i>N</i>} {
  The unix [VFS] will never use a file descriptor less than <i>N</i>.  The
  default value of <i>N</i> is 3.
  <p>
  Avoiding the use of low-numbered file descriptors is a defense against
  accidental database corruption.  If a database file was opened using
  file descriptor 2, for example, and then an assert() failed and invoked
  write(2,...), that would likely cause database corruption by overwritting
  part of the database file with the assertion error message.  Using only
  higher-valued file descriptors avoids this potential problem.  The 
  protection against
  using low-numbered file descriptors can be disabled by setting this
  compile-time option to 0.
}

COMPILE_OPTION {SQLITE_POWERSAFE_OVERWRITE=<i>&lt;0 or 1&gt;</i>} {
  This option changes the default assumption about [powersafe overwrite]
  for the underlying filesystems for the unix and windows [VFSes].
  Setting SQLITE_POWERSAFE_OVERWRITE to 1 causes SQLite to assume that
................................................................................
  is now a no-op.
}

COMPILE_OPTION {SQLITE_ENABLE_STAT3} {
  This option adds additional logic to the [ANALYZE] command and to
  the [query planner] that can help SQLite to chose a better query plan
  under certain situations.  The [ANALYZE] command is enhanced to collect
  histogram data from the left-most column of each index and store that data
  in the [sqlite_stat3] table.  The query planner will then use the
  histogram data to help it make better index choices.
  <p>
}

COMPILE_OPTION {SQLITE_ENABLE_STAT4} {
  This option adds additional logic to the [ANALYZE] command and to
  the [query planner] that can help SQLite to chose a better query plan
  under certain situations.  The [ANALYZE] command is enhanced to collect
  histogram data from all columns of every index and store that data
  in the [sqlite_stat4] table.  The query planner will then use the
  histogram data to help it make better index choices.
  <p>
  SQLITE_ENABLE_STAT4 is an enhancement of [SQLITE_ENABLE_STAT3].  STAT3
  only recorded histogram data for the left-most column of each index
  whereas the STAT4 enhancement records histograph data from all columns
  of each index.
  The [SQLITE_ENABLE_STAT3] compile-time option is a no-op and is ignored
  if the SQLITE_ENABLE_STAT4 compile-time option is used.
}

COMPILE_OPTION {SQLITE_ENABLE_TREE_EXPLAIN} {
  This option adds support for the [SQLITE_TESTCTRL_EXPLAIN_STMT] test-control
  in the SQLite core.  When the [command-line shell] is also compiled with
  this option, the ".explain" dot-command enables a mode that uses the
  [SQLITE_TESTCTRL_EXPLAIN_STMT] interface to display an ASCII-art diagram

<blockquote><pre>
CREATE TABLE sqlite_stat3(tbl,idx,nEq,nLt,nDLt,sample);
</pre></blockquote>

<p>There are usually multiple entries in the sqlite_stat3 table for each index.
The sqlite_stat3.sample column holds the value of the left-most field of an
index identified by the sqlite_stat3.idx and the sqlite_stat3.tbl columns.
If the sqlite_stat3.idx and sqlite_stat3.tbl
columns hold the same value, then that row contains a sample from
the [INTEGER PRIMARY KEY] of the table.
The sqlite_stat3.nEq column holds the approximate
number of entries in the index whose left-most column exactly matches
the sample.  
The sqlite_stat3.nLt holds the approximate number of entries in the
................................................................................
<blockquote><pre>
CREATE TABLE sqlite_stat4(tbl,idx,nEq,nLt,nDLt,sample);
</pre></blockquote>

<p>There are usually multiple entries in the sqlite_stat4 table for each index.
The sqlite_stat4.sample column holds the content of an index entry in
the [record format].  The index entry stored is taken from the
index identified by the sqlite_stat4.idx and the sqlite_stat4.tbl columns.
If the sqlite_stat4.idx and sqlite_stat4.tbl
columns hold the same value, then that row contains a sample from
the [INTEGER PRIMARY KEY] of the table.
The sqlite_stat4.nEq column holds a list of integer where the K-th integer
is the approximate number of entries in the index whose left-most K columns
exactly match the K left-most columns of the sample.
The sqlite_stat4.nLt holds a list of integers where the K-th integer is
the approximate number of entries in the
index whose K left-most columns are collectively less than the 
K left-most columns of the sample.
The sqlite_stat4.nDLt column holds a list of intgers where the K-th 

<blockquote><pre>
CREATE TABLE sqlite_stat3(tbl,idx,nEq,nLt,nDLt,sample);
</pre></blockquote>

<p>There are usually multiple entries in the sqlite_stat3 table for each index.
The sqlite_stat3.sample column holds the value of the left-most field of an
index identified by sqlite_stat3.idx and sqlite_stat3.tbl.
If the sqlite_stat3.idx and sqlite_stat3.tbl
columns hold the same value, then that row contains a sample from
the [INTEGER PRIMARY KEY] of the table.
The sqlite_stat3.nEq column holds the approximate
number of entries in the index whose left-most column exactly matches
the sample.  
The sqlite_stat3.nLt holds the approximate number of entries in the
................................................................................
<blockquote><pre>
CREATE TABLE sqlite_stat4(tbl,idx,nEq,nLt,nDLt,sample);
</pre></blockquote>

<p>There are usually multiple entries in the sqlite_stat4 table for each index.
The sqlite_stat4.sample column holds the content of an index entry in
the [record format].  The index entry stored is taken from the
index identified by sqlite_stat4.idx and sqlite_stat4.tbl.
If sqlite_stat4.idx and sqlite_stat4.tbl
hold the same value, then that row contains a sample from
the [INTEGER PRIMARY KEY] of the table.
The sqlite_stat4.nEq column holds a list of integers where the K-th integer
is the approximate number of entries in the index whose left-most K columns
exactly match the K left-most columns of the sample.
The sqlite_stat4.nLt holds a list of integers where the K-th integer is
the approximate number of entries in the
index whose K left-most columns are collectively less than the 
K left-most columns of the sample.
The sqlite_stat4.nDLt column holds a list of intgers where the K-th 

funcdef {likelihood(X,Y)} {} {
  ^The likelihood(X,Y) function returns argument X unchanged.
  ^The value Y in likelihood(X,Y) must be a floating point constant
  between 0.0 and 1.0, inclusive.
  ^The likelihood(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles at run-time.

  ^The purpose of the likelihood(X,Y) function is to provide a hint
  to the query planner that the argument X is a boolean that is
  true with a probability of approximately Y.
  ^The likelihood(X, 0.0625) function is equivalent to [unlikely](X).
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point name is used.
  ^The load_extension() function raises an exception if the extension fails to
................................................................................
  ^The typeof(X) function returns a string that indicates the [datatype] of
  the expression X: "null", "integer", "real", "text", or "blob".
}

funcdef {unlikely(X)} {} {
  ^The unlikely(X) function returns the argument X unchanged.
  ^The unlikely(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles at run-time.

  ^The purpose of the unlikely(X) function is to provide a hint
  to the query planner that the argument X is a boolean value
  that is usually not true. ^The unlikely(X) function is equivalent
  to [likelihood](X, 0.0625).
}

funcdef {unicode(X)} {} {

funcdef {likelihood(X,Y)} {} {
  ^The likelihood(X,Y) function returns argument X unchanged.
  ^The value Y in likelihood(X,Y) must be a floating point constant
  between 0.0 and 1.0, inclusive.
  ^The likelihood(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles during run-time
  (that is, during calls to [sqlite3_step()]).
  ^The purpose of the likelihood(X,Y) function is to provide a hint
  to the query planner that the argument X is a boolean that is
  true with a probability of approximately Y.
  ^The [unlikely(X)] fucntion is short-hand for likelihood(X,0.0625).
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point name is used.
  ^The load_extension() function raises an exception if the extension fails to
................................................................................
  ^The typeof(X) function returns a string that indicates the [datatype] of
  the expression X: "null", "integer", "real", "text", or "blob".
}

funcdef {unlikely(X)} {} {
  ^The unlikely(X) function returns the argument X unchanged.
  ^The unlikely(X) function is a no-op that the code generator
  optimizes away so that it consumes no CPU cycles at
  run-time (that is, during calls to [sqlite3_step()]).
  ^The purpose of the unlikely(X) function is to provide a hint
  to the query planner that the argument X is a boolean value
  that is usually not true. ^The unlikely(X) function is equivalent
  to [likelihood](X, 0.0625).
}

funcdef {unicode(X)} {} {