Documentation Source Text

Check-in [1d0df412df]
Login

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

Overview
Comment:Fix typos and enhance the text of documentation for 3.8.1 changes.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 1d0df412df08a01c3b672bfaf84251f6128a141b
User & Date: drh 2013-09-19 14:14:56.671
Context
2013-09-19
14:24
Leave unspecified what it means for the sqlite_stat3 and sqlite_stat4 tables to have idx columns equal to their tbl column. (check-in: c538b41b91 user: drh tags: trunk)
14:14
Fix typos and enhance the text of documentation for 3.8.1 changes. (check-in: 1d0df412df user: drh tags: trunk)
13:22
Updates to the TH3 description. (check-in: ecd17d4f41 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/changes.in.
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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.
}








|







20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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.
}

Changes to pages/compile.in.
199
200
201
202
203
204
205
206

207

208
209
210
211
212
213
214
215
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







|
>
|
>
|







199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
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
599
600
601
602
603
604
605
606
607
608

609
610
611
612
613
614
615
616
617
618





619
620
621
622
623
624
625
626
  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







|
|

>






|
|


>
>
>
>
>
|







601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
  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
Changes to pages/fileformat2.in.
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266

<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







|







1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266

<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
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
<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 







|
|
|

|







1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
<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 
Changes to pages/lang.in.
2147
2148
2149
2150
2151
2152
2153
2154

2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165


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







|
>



|







2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166


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
2348
2349
2350
2351
2352
2353
2354
2355

2356
2357
2358
2359
2360
2361
2362
  ^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)} {} {







|
>







2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
  ^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)} {} {