Documentation Source Text

Check-in [1bbfd06810]
Login

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

Overview
Comment:Improved documentation for automatic analyze using PRAGMA optimize.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 1bbfd068107ecdc90ea05ff2b1da78ecb80e4ff8782a1c130f0b1825d14e3aed
User & Date: drh 2017-03-20 14:42:52
Context
2017-03-20
15:36
Report the fix of the sqlite3_trace_v2() output for nested SQL. check-in: a432575098 user: drh tags: trunk
14:42
Improved documentation for automatic analyze using PRAGMA optimize. check-in: 1bbfd06810 user: drh tags: trunk
13:05
Add the changes to SQLITE_SOURCE_ID to the change log. check-in: 717afb7f73 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

383
384
385
386
387
388
389
390












































391
392
393
394
395
396
397
<p> The query planner loads the content of the statistics tables
into memory when the schema is read.  ^Hence, when an application
changes the statistics tables directly, SQLite will not immediately
notice the changes. ^An application
can force the query planner to reread the statistics tables by running
<b>ANALYZE sqlite_master</b>. </p>

<p> 













































<tcl>
##############################################################################
Section {ATTACH DATABASE} attach {attached *ATTACH}

RecursiveBubbleDiagram attach-stmt
</tcl>







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







383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
<p> The query planner loads the content of the statistics tables
into memory when the schema is read.  ^Hence, when an application
changes the statistics tables directly, SQLite will not immediately
notice the changes. ^An application
can force the query planner to reread the statistics tables by running
<b>ANALYZE sqlite_master</b>. </p>

<tcl>hd_fragment autoanalyze {automatically running ANALYZE}</tcl>
<h2>Automatically Running ANALYZE</h2>

<p>The [PRAGMA optimize] command will automatically run ANALYZE on individual
tables on an as-needed basis.  The recommended practice is for applications
to invoke the [PRAGMA optimize] statement just before closing each database
connection.</p>

<p>Each SQLite [database connection] records cases when the query planner would
benefit from having accurate results of ANALYZE at hand.  These records
are held in memory and accumulate over the life of a database connection.
The [PRAGMA optimize] command looks at those records and runs ANALYZE on only
those tables for which new or updated ANALYZE data seems likely to be useful.
In most cases [PRAGMA optimize] will not run ANALYZE, but it will occasionally
do so either for tables that have never before been analyzed, or for tables
that have grown significantly since they were last analyzed.</p>

<p>Since the actions of [PRAGMA optimize] are determined to some extent by
prior queries that have been evaluated on the same database connection, it
is recommended that [PRAGMA optimize] be deferred until the database connection
is closing and has thus had an opportunity to accumulate as must usage information
as possible.  It is also reasonable to set a timer to run [PRAGMA optimize]
every few hours, or every few days, for database connections that stay open
for a long time.</p>

<p>Applications that desire more control can run [PRAGMA optimize(0x03)] to 
obtain a list of ANALYZE commands that SQLite thinks are appropriate to run,
but without actually running those commands.  If the returned set is 
non-empty, the application can then make a decision about whether or not
to run the suggested ANALYZE commands, perhaps after prompting the user
for guidance.</p>

<p>The [PRAGMA optimize] command was first introduced with 
SQLite 3.18.0 ([dateof:3.18.0]) and is a no-op for all prior releases
of SQLite.</p>

<h2>Anticipated Future Enhancements</h2>

<p>All existing versions of SQLite do a full table scan for ANALYZE.  This can be
slow for multi-gigabyte and larger databases.  Future versions of SQLite might
use random sampling rather than a full table scan to obtain estimates for the
database shape, especially on larger tables.  The results would approximate, but 
will be close enough for query planning purposes.  As of 2017-03-20, this
concept has been tested in experimental branches and appears to work well, but
has not been folded into an official release.</p>

<tcl>
##############################################################################
Section {ATTACH DATABASE} attach {attached *ATTACH}

RecursiveBubbleDiagram attach-stmt
</tcl>

Changes to pages/pragma.in.

961
962
963
964
965
966
967
968
969
970
971
972
973
974

975
976
977
978
979
980
981
982
983
984
985
         information from the current session in the
         database file so that it will be available to "optimize"
         pragmas run by future database connections.
  <li value='8'><p>
         <em>(Not yet implemented)</em>
         Create indexes that might have been helpful to recent queries.
  </ol>
  <p>The default MASK is and alway shall be 0xfffe.  The 0xfffe mask means
  perform all of the optimizations listed above except Debug Mode.  If new
  optimizations are added in the future that should be off by default, those
  new optimizations will be given a mask of 0x10000 or larger.</p>

  <p>To see all optimizations that would have been done without actually
  doing them, run "PRAGMA optimize(-1)".</p>

  
  <p><b>Determination Of When To Run Analyze</b></p>
  <p> In the current implementation, a table is analyzed if only if all of
      the following are true:
  <ul>
  <li><p>
    MASK bit 0x02 is set.
  <li><p>
    The query planner used [sqlite_stat1]-style statistics for one or
    more indexes of the table at some point during the lifetime of
    the current connection.







|





|
>


|
|







961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
         information from the current session in the
         database file so that it will be available to "optimize"
         pragmas run by future database connections.
  <li value='8'><p>
         <em>(Not yet implemented)</em>
         Create indexes that might have been helpful to recent queries.
  </ol>
  <p>The default MASK is and always shall be 0xfffe.  The 0xfffe mask means
  perform all of the optimizations listed above except Debug Mode.  If new
  optimizations are added in the future that should be off by default, those
  new optimizations will be given a mask of 0x10000 or larger.</p>

  <p>To see all optimizations that would have been done without actually
  doing them, run "PRAGMA optimize(-1)".  To use only the ANALYZE
  optimization, run "PRAGMA optimize(0x02)".</p>
  
  <p><b>Determination Of When To Run Analyze</b></p>
  <p> In the current implementation, a table is analyzed if and only if 
      all of the following are true:
  <ul>
  <li><p>
    MASK bit 0x02 is set.
  <li><p>
    The query planner used [sqlite_stat1]-style statistics for one or
    more indexes of the table at some point during the lifetime of
    the current connection.