Documentation Source Text

Check-in [906016ee92]
Login

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

Overview
Comment:Add initial automatic indexing documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 906016ee923faf6a96dd8b6f0e205368e761dbae
User & Date: drh 2010-04-12 13:57:01
Context
2010-05-06
23:48
Minor edits on the way toward 3.7.0 documentation. The wal.html document is created but is still mostly just a stub. check-in: 019b60379f user: drh tags: trunk
2010-04-12
13:57
Add initial automatic indexing documentation. check-in: 906016ee92 user: drh tags: trunk
2010-03-29
19:57
Updates prior to the release of 3.6.23.1 check-in: 8327c0b926 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/compile.in.

537
538
539
540
541
542
543





544
545
546
547
548
549
550
  [AUTOINCREMENT] functionality. When this 
  is macro is defined, columns declared as 
  "[INTEGER PRIMARY KEY] AUTOINCREMENT"
  behave in the same way as columns declared as "[INTEGER PRIMARY KEY]" when a 
  NULL is inserted. The sqlite_sequence system table is neither created, nor
  respected if it already exists.
}






COMPILE_OPTION {SQLITE_OMIT_AUTOINIT} {
  For backwards compatibility with older versions of SQLite that lack
  the [sqlite3_initialize()] interface, the [sqlite3_initialize()] interface
  is called automatically upon entry to certain key interfaces such as
  [sqlite3_open()], [sqlite3_vfs_register()], and [sqlite3_mprintf()].
  The overhead of invoking [sqlite3_initialize()] automatically in this







>
>
>
>
>







537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
  [AUTOINCREMENT] functionality. When this 
  is macro is defined, columns declared as 
  "[INTEGER PRIMARY KEY] AUTOINCREMENT"
  behave in the same way as columns declared as "[INTEGER PRIMARY KEY]" when a 
  NULL is inserted. The sqlite_sequence system table is neither created, nor
  respected if it already exists.
}

COMPILE_OPTION {SQLITE_OMIT_AUTOMATIC_INDEX} {
  This option is used to omit the 
  [automatic indexing] functionality.
}

COMPILE_OPTION {SQLITE_OMIT_AUTOINIT} {
  For backwards compatibility with older versions of SQLite that lack
  the [sqlite3_initialize()] interface, the [sqlite3_initialize()] interface
  is called automatically upon entry to certain key interfaces such as
  [sqlite3_open()], [sqlite3_vfs_register()], and [sqlite3_mprintf()].
  The overhead of invoking [sqlite3_initialize()] automatically in this

Changes to pages/optoverview.in.

17
18
19
20
21
22
23
24

25

26
27
28
29
30
31
32
...
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
...
940
941
942
943
944
945
946

















































947
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  hd_resolve "<p>$t3</p>\n"
}
set level(0) 0
set level(1) 0
proc HEADING {n name {tag {}}} {

  hd_fragment $tag

  global level
  incr level($n)
  for {set i [expr {$n+1}]} {$i<10} {incr i} {
    set level($i) 0
  }
  if {$n==0} {
    set num {}
................................................................................
}

HEADING 1 {Choosing between multiple indices} multi_index

PARAGRAPH {
  Each table in the FROM clause of a query can use at most one index
  (except when the <a href="#or_opt">OR-clause optimization</a> comes into
  paly)
  and SQLite strives to use at least one index on each table.  Sometimes,
  two or more indices might be candidates for use on a single table.
  For example:
}
CODE {
  CREATE TABLE ex2(x,y,z);
  CREATE INDEX ex2i1 ON ex2(x);
................................................................................
PARAGRAPH {)^
  ^In order for these optimizations to occur, they must appear in exactly
  the form shown above - changing only the name of the table and column.
  ^It is not permissible to add a WHERE clause or do any arithmetic on the
  result.  ^The result set must contain a single column.
  ^The column in the MIN or MAX function must be an indexed column.
}

















































</tcl>







|
>
|
>







 







|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
...
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
...
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
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
987
988
989
990
991
992
993
994
995
996
997
998
proc PARAGRAPH {text} {
  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
  regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
  hd_resolve "<p>$t3</p>\n"
}
set level(0) 0
set level(1) 0
proc HEADING {n name args} {
  if {[llength $args]>0} {
    eval hd_fragment $args
  }
  global level
  incr level($n)
  for {set i [expr {$n+1}]} {$i<10} {incr i} {
    set level($i) 0
  }
  if {$n==0} {
    set num {}
................................................................................
}

HEADING 1 {Choosing between multiple indices} multi_index

PARAGRAPH {
  Each table in the FROM clause of a query can use at most one index
  (except when the <a href="#or_opt">OR-clause optimization</a> comes into
  play)
  and SQLite strives to use at least one index on each table.  Sometimes,
  two or more indices might be candidates for use on a single table.
  For example:
}
CODE {
  CREATE TABLE ex2(x,y,z);
  CREATE INDEX ex2i1 ON ex2(x);
................................................................................
PARAGRAPH {)^
  ^In order for these optimizations to occur, they must appear in exactly
  the form shown above - changing only the name of the table and column.
  ^It is not permissible to add a WHERE clause or do any arithmetic on the
  result.  ^The result set must contain a single column.
  ^The column in the MIN or MAX function must be an indexed column.
}

HEADING 1 {Automatic Indices} autoindex {automatic indexing} {Automatic indexing}

PARAGRAPH {
  ^(When no indices are available to aid the evaulation of a query, SQLite
  will consider creating a automatic index that lasts only for the duration
  of a single SQL statement and use that index to help boost the query
  performance.)^  Since the cost of constructing the automatic index is
  O(NlogN) (where N is the number of entries in the table) and the cost of
  doing a full table scan is only O(N), an automatic index will
  only be created if SQLite expects that the lookup will be run more than
  logN times during the course of the SQL statement. Consider an example:
}
CODE {
  CREATE TABLE t1(a,b);
  CREATE TABLE t2(c,d);
  -- Insert many rows into both t1 and t2
  SELECT * FROM t1, t2 WHERE a=c;
}
PARAGRAPH {
  In the query above, if both t1 and t2 have approximately N rows, then
  without any indices the query will require O(N*N) time.  On the other
  hand, creating an index on table t2 requires O(NlogN) time and then using 
  that index to evaluate the query requires an additional O(NlogN) time.
  In the absence of [ANALYZE] information, SQLite guesses that N is one
  million and hence it believes that constructing the automatic index will
  be the cheaper approach.
}
PARAGRAPH {
  An automatic index might also be used for a subquery:
}
CODE {
  CREATE TABLE t1(a,b);
  CREATE TABLE t2(c,d);
  -- Insert many rows into both t1 and t2
  SELECT a, (SELECT d FROM t2 WHERE c=b) FROM t1;
}
PARAGRAPH {
  In this example, the t2 table is used in a subquery to translate values
  of the t1.b column.  If each table contains N rows, SQLite expects that
  the subquery will run N times, and hence it will believe it is faster
  to construct an automatic, transient index on t2 first and then using
  that index to satisfy the N instances of the subquery.
}
PARAGRAPH {
  The automatic indexing capability can be disabled at run-time using
  the [automatic_index pragma] and can be omitted from the build at
  compile-time using the [SQLITE_OMIT_AUTOMATIC_INDEX] compile-time option.
}
</tcl>

Changes to pages/pragma.in.

92
93
94
95
96
97
98












99
100
101
102
103
104
105
database name is omitted, "main" is assumed.  ^In some pragmas, the database
name is meaningless and is simply ignored.</p>

<tcl>Section {Pragmas to modify library operation} modify</tcl>
</tcl>

<ul>












<tcl>Subsection auto_vacuum</tcl>
<li><p><b>PRAGMA auto_vacuum;<br>
          PRAGMA auto_vacuum = </b>
           <i>0 | NONE | 1 | FULL | 2 | INCREMENTAL</i><b>;</b></p>

    <p>Query or set the auto-vacuum status in the database.</p>








>
>
>
>
>
>
>
>
>
>
>
>







92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
database name is omitted, "main" is assumed.  ^In some pragmas, the database
name is meaningless and is simply ignored.</p>

<tcl>Section {Pragmas to modify library operation} modify</tcl>
</tcl>

<ul>
<tcl>Subsection automatic_index</tcl>
<li><p>^(<b>PRAGMA automatic_index;
       <br>PRAGMA automatic_index = </b><i>boolean</i><b>;</b></p>
    <p>Query, set, or clear the [automatic indexing] capability.)^

    <p>^[Automatic indexing] is enabled by default.
     ^This pragma only influences the query plan as statements are
     prepared or reprepared.  Existing prepared statements must be
     reprepared for a change in the automatic_index setting to affect
     their operation.
</li>

<tcl>Subsection auto_vacuum</tcl>
<li><p><b>PRAGMA auto_vacuum;<br>
          PRAGMA auto_vacuum = </b>
           <i>0 | NONE | 1 | FULL | 2 | INCREMENTAL</i><b>;</b></p>

    <p>Query or set the auto-vacuum status in the database.</p>