Documentation Source Text

Hex Artifact Content
Login

Artifact 68e3a0784f77d53894b3ebca2d2addfbd14de7f051d2574fd8e20529344db961:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 44 42 53 54 41  <title>The DBSTA
0010: 54 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 3c  T Virtual Table<
0020: 2f 74 69 74 6c 65 3e 0a 3c 74 63 6c 3e 68 64 5f  /title>.<tcl>hd_
0030: 6b 65 79 77 6f 72 64 73 20 64 62 73 74 61 74 20  keywords dbstat 
0040: 7b 64 62 73 74 61 74 20 76 69 72 74 75 61 6c 20  {dbstat virtual 
0050: 74 61 62 6c 65 7d 3c 2f 74 63 6c 3e 0a 3c 66 61  table}</tcl>.<fa
0060: 6e 63 79 5f 66 6f 72 6d 61 74 3e 0a 0a 0a 3c 68  ncy_format>...<h
0070: 31 3e 4f 76 65 72 76 69 65 77 3c 2f 68 31 3e 0a  1>Overview</h1>.
0080: 0a 3c 70 3e 0a 54 68 65 20 44 42 53 54 41 54 20  .<p>.The DBSTAT 
0090: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 69  virtual tables i
00a0: 73 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 5b 65  s a read-only [e
00b0: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
00c0: 20 74 61 62 6c 65 5d 20 74 68 61 74 20 72 65 74   table] that ret
00d0: 75 72 6e 73 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e  urns.information
00e0: 20 61 62 6f 75 74 20 77 68 69 63 68 20 70 61 67   about which pag
00f0: 65 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  es of the databa
0100: 73 65 20 66 69 6c 65 73 20 61 72 65 20 75 73 65  se files are use
0110: 64 20 62 79 20 77 68 69 63 68 0a 74 61 62 6c 65  d by which.table
0120: 73 20 61 6e 64 20 69 6e 64 65 78 65 73 20 69 6e  s and indexes in
0130: 20 74 68 65 20 73 63 68 65 6d 61 2e 0a 54 68 65   the schema..The
0140: 20 74 68 65 20 44 42 53 54 41 54 20 76 69 72 74   the DBSTAT virt
0150: 75 61 6c 20 74 61 62 6c 65 20 69 73 20 75 73 65  ual table is use
0160: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
0170: 73 71 6c 69 74 65 33 5f 61 6e 61 6c 79 7a 65 72  sqlite3_analyzer
0180: 2e 65 78 65 5d 0a 75 74 69 6c 69 74 79 20 70 72  .exe].utility pr
0190: 6f 67 72 61 6d 2c 20 61 6e 64 20 74 6f 20 68 65  ogram, and to he
01a0: 6c 70 20 63 6f 6d 70 75 74 65 20 74 68 65 20 0a  lp compute the .
01b0: 5b 68 74 74 70 73 3a 2f 2f 77 77 77 2e 73 71 6c  [https://www.sql
01c0: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 72 65 70 6f  ite.org/src/repo
01d0: 2d 74 61 62 73 69 7a 65 7c 74 61 62 6c 65 20 73  -tabsize|table s
01e0: 69 7a 65 20 70 69 65 2d 63 68 61 72 74 5d 20 69  ize pie-chart] i
01f0: 6e 0a 74 68 65 20 5b 68 74 74 70 73 3a 2f 2f 77  n.the [https://w
0200: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72  ww.fossil-scm.or
0210: 67 2f 7c 46 6f 73 73 69 6c 2d 69 6d 70 6c 65 6d  g/|Fossil-implem
0220: 65 6e 74 65 64 5d 20 76 65 72 73 69 6f 6e 20 63  ented] version c
0230: 6f 6e 74 72 6f 6c 20 73 79 73 74 65 6d 0a 66 6f  ontrol system.fo
0240: 72 20 53 51 4c 69 74 65 2e 0a 3c 2f 70 3e 0a 0a  r SQLite..</p>..
0250: 3c 70 3e 0a 5e 54 68 65 20 3c 62 3e 64 62 73 74  <p>.^The <b>dbst
0260: 61 74 3c 2f 62 3e 20 76 69 72 74 75 61 6c 20 74  at</b> virtual t
0270: 61 62 6c 65 20 69 73 20 61 76 61 69 6c 61 62 6c  able is availabl
0280: 65 20 6f 6e 20 61 6c 6c 20 0a 5b 64 61 74 61 62  e on all .[datab
0290: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
02a0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
02b0: 62 75 69 6c 74 20 75 73 69 6e 67 20 74 68 65 0a  built using the.
02c0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 44  [SQLITE_ENABLE_D
02d0: 42 53 54 41 54 5f 56 54 41 42 5d 20 63 6f 6d 70  BSTAT_VTAB] comp
02e0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
02f0: 0a 5e 54 68 65 20 64 62 73 74 61 74 20 76 69 72  .^The dbstat vir
0300: 74 75 61 6c 20 74 61 62 6c 65 20 70 72 6f 76 69  tual table provi
0310: 64 65 73 20 6c 6f 77 2d 6c 65 76 65 6c 20 69 6e  des low-level in
0320: 66 6f 72 6d 61 74 69 6f 6e 20 0a 61 62 6f 75 74  formation .about
0330: 20 62 74 72 65 65 20 61 6e 64 20 6f 76 65 72 66   btree and overf
0340: 6c 6f 77 20 70 61 67 65 73 20 69 6e 20 61 20 64  low pages in a d
0350: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 0a 3c  atabase file...<
0360: 70 3e 0a 5e 54 68 65 20 64 62 73 74 61 74 20 76  p>.^The dbstat v
0370: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
0380: 61 6e 20 5b 65 70 6f 6e 79 6d 6f 75 73 20 76 69  an [eponymous vi
0390: 72 74 75 61 6c 20 74 61 62 6c 65 5d 2c 20 6d 65  rtual table], me
03a0: 61 6e 69 6e 67 0a 74 68 61 74 20 69 73 20 6e 6f  aning.that is no
03b0: 74 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 72  t necessary to r
03c0: 75 6e 20 5b 43 52 45 41 54 45 20 56 49 52 54 55  un [CREATE VIRTU
03d0: 41 4c 20 54 41 42 4c 45 5d 20 74 6f 20 63 72 65  AL TABLE] to cre
03e0: 61 74 65 20 61 6e 0a 69 6e 73 74 61 6e 63 65 20  ate an.instance 
03f0: 6f 66 20 74 68 65 20 64 62 73 74 61 74 20 76 69  of the dbstat vi
0400: 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 66 6f  rtual table befo
0410: 72 65 20 75 73 69 6e 67 20 69 74 2e 20 20 54 68  re using it.  Th
0420: 65 20 22 64 62 73 74 61 74 22 0a 6d 6f 64 75 6c  e "dbstat".modul
0430: 65 20 6e 61 6d 65 20 63 61 6e 20 62 65 20 75 73  e name can be us
0440: 65 64 20 61 73 20 69 66 20 69 74 20 77 65 72 65  ed as if it were
0450: 20 61 20 74 61 62 6c 65 20 6e 61 6d 65 20 74 6f   a table name to
0460: 20 71 75 65 72 79 20 74 68 65 0a 64 62 73 74 61   query the.dbsta
0470: 74 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  t virtual table 
0480: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
0490: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
04a0: 6f 63 6b 3e 0a 53 45 4c 45 43 54 20 2a 20 46 52  ock>.SELECT * FR
04b0: 4f 4d 20 64 62 73 74 61 74 3b 0a 3c 2f 63 6f 64  OM dbstat;.</cod
04c0: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 49 66 20  eblock>..<p>.If 
04d0: 61 20 6e 61 6d 65 64 20 76 69 72 74 75 61 6c 20  a named virtual 
04e0: 74 61 62 6c 65 20 74 68 61 74 20 75 73 65 73 20  table that uses 
04f0: 74 68 65 20 64 62 73 74 61 74 20 6d 6f 64 75 6c  the dbstat modul
0500: 65 20 69 73 20 64 65 73 69 72 65 64 2c 0a 74 68  e is desired,.th
0510: 65 6e 20 74 68 65 20 72 65 63 6f 6d 6d 65 6e 64  en the recommend
0520: 65 64 20 77 61 79 20 74 6f 20 63 72 65 61 74 65  ed way to create
0530: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
0540: 74 68 65 20 64 62 73 74 61 74 0a 76 69 72 74 75  the dbstat.virtu
0550: 61 6c 20 74 61 62 6c 65 20 69 73 20 61 73 20 66  al table is as f
0560: 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c  ollows:..<codebl
0570: 6f 63 6b 3e 0a 43 52 45 41 54 45 20 56 49 52 54  ock>.CREATE VIRT
0580: 55 41 4c 20 54 41 42 4c 45 20 74 65 6d 70 2e 73  UAL TABLE temp.s
0590: 74 61 74 20 55 53 49 4e 47 20 64 62 73 74 61 74  tat USING dbstat
05a0: 28 6d 61 69 6e 29 3b 0a 3c 2f 63 6f 64 65 62 6c  (main);.</codebl
05b0: 6f 63 6b 3e 0a 0a 3c 70 3e 0a 4e 6f 74 65 20 74  ock>..<p>.Note t
05c0: 68 65 20 22 74 65 6d 70 2e 22 20 71 75 61 6c 69  he "temp." quali
05d0: 66 69 65 72 20 62 65 66 6f 72 65 20 74 68 65 20  fier before the 
05e0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6e 61  virtual table na
05f0: 6d 65 20 28 22 73 74 61 74 22 29 2e 20 20 54 68  me ("stat").  Th
0600: 69 73 0a 71 75 61 6c 69 66 69 65 72 20 63 61 75  is.qualifier cau
0610: 73 65 73 20 74 68 65 20 76 69 72 74 75 61 6c 20  ses the virtual 
0620: 74 61 62 6c 65 20 74 6f 20 62 65 20 74 65 6d 70  table to be temp
0630: 6f 72 61 72 79 20 2d 20 74 6f 20 6f 6e 6c 79 20  orary - to only 
0640: 65 78 69 73 74 20 66 6f 72 0a 74 68 65 20 64 75  exist for.the du
0650: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  ration of the cu
0660: 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 63  rrent database c
0670: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
0680: 20 69 73 20 74 68 65 0a 72 65 63 6f 6d 6d 65 6e   is the.recommen
0690: 64 65 64 20 61 70 70 72 6f 61 63 68 2e 0a 0a 3c  ded approach...<
06a0: 70 3e 0a 54 68 65 20 22 6d 61 69 6e 22 20 61 72  p>.The "main" ar
06b0: 67 75 6d 65 6e 74 20 74 6f 20 64 62 73 74 61 74  gument to dbstat
06c0: 20 69 73 20 64 65 66 61 75 6c 74 20 73 63 68 65   is default sche
06d0: 6d 61 0a 66 6f 72 20 77 68 69 63 68 20 69 6e 66  ma.for which inf
06e0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  ormation is to b
06f0: 65 20 70 72 6f 76 69 64 65 64 2e 20 20 54 68 65  e provided.  The
0700: 20 64 65 66 61 75 6c 74 20 69 73 20 22 6d 61 69   default is "mai
0710: 6e 22 2c 20 61 6e 64 0a 73 6f 20 74 68 65 20 75  n", and.so the u
0720: 73 65 20 6f 66 20 22 6d 61 69 6e 22 20 69 6e 20  se of "main" in 
0730: 74 68 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76  the example abov
0740: 65 20 69 73 20 72 65 64 75 6e 64 61 6e 74 2e 20  e is redundant. 
0750: 20 46 6f 72 20 61 6e 79 0a 70 61 72 74 69 63 75   For any.particu
0760: 6c 61 72 20 71 75 65 72 79 2c 20 74 68 65 20 73  lar query, the s
0770: 63 68 65 6d 61 20 63 61 6e 20 62 65 20 63 68 61  chema can be cha
0780: 6e 67 65 64 20 62 79 20 73 70 65 63 69 66 79 69  nged by specifyi
0790: 6e 67 20 74 68 65 0a 61 6c 74 65 72 6e 61 74 69  ng the.alternati
07a0: 76 65 20 73 63 68 65 6d 61 20 61 73 20 61 20 66  ve schema as a f
07b0: 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
07c0: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
07d0: 74 61 62 6c 65 0a 6e 61 6d 65 20 69 6e 20 74 68  table.name in th
07e0: 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f 66  e FROM clause of
07f0: 20 74 68 65 20 71 75 65 72 79 2e 20 20 28 53 65   the query.  (Se
0800: 65 20 66 75 72 74 68 65 72 20 64 69 73 63 75 73  e further discus
0810: 73 69 6f 6e 20 6f 66 0a 5b 74 61 62 6c 65 2d 76  sion of.[table-v
0820: 61 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  alued functions 
0830: 69 6e 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75  in the FROM clau
0840: 73 65 5d 20 66 6f 72 20 6d 6f 72 65 20 64 65 74  se] for more det
0850: 61 69 6c 73 2e 29 0a 0a 3c 70 3e 0a 54 68 65 20  ails.)..<p>.The 
0860: 73 63 68 65 6d 61 20 66 6f 72 20 74 68 65 20 64  schema for the d
0870: 62 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61  bstat virtual ta
0880: 62 6c 65 20 69 73 20 74 68 69 73 3a 0a 3c 63 6f  ble is this:.<co
0890: 64 65 62 6c 6f 63 6b 3e 0a 43 52 45 41 54 45 20  deblock>.CREATE 
08a0: 54 41 42 4c 45 20 64 62 73 74 61 74 28 0a 20 20  TABLE dbstat(.  
08b0: 6e 61 6d 65 20 20 20 20 20 20 20 54 45 58 54 2c  name       TEXT,
08c0: 20 20 20 20 20 20 20 20 2d 2d 20 4e 61 6d 65 20          -- Name 
08d0: 6f 66 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65  of table or inde
08e0: 78 0a 20 20 70 61 74 68 20 20 20 20 20 20 20 54  x.  path       T
08f0: 45 58 54 2c 20 20 20 20 20 20 20 20 2d 2d 20 50  EXT,        -- P
0900: 61 74 68 20 74 6f 20 70 61 67 65 20 66 72 6f 6d  ath to page from
0910: 20 72 6f 6f 74 0a 20 20 70 61 67 65 6e 6f 20 20   root.  pageno  
0920: 20 20 20 49 4e 54 45 47 45 52 2c 20 20 20 20 20     INTEGER,     
0930: 2d 2d 20 50 61 67 65 20 6e 75 6d 62 65 72 0a 20  -- Page number. 
0940: 20 70 61 67 65 74 79 70 65 20 20 20 54 45 58 54   pagetype   TEXT
0950: 2c 20 20 20 20 20 20 20 20 2d 2d 20 27 69 6e 74  ,        -- 'int
0960: 65 72 6e 61 6c 27 2c 20 27 6c 65 61 66 27 20 6f  ernal', 'leaf' o
0970: 72 20 27 6f 76 65 72 66 6c 6f 77 27 0a 20 20 6e  r 'overflow'.  n
0980: 63 65 6c 6c 20 20 20 20 20 20 49 4e 54 45 47 45  cell      INTEGE
0990: 52 2c 20 20 20 20 20 2d 2d 20 43 65 6c 6c 73 20  R,     -- Cells 
09a0: 6f 6e 20 70 61 67 65 20 28 30 20 66 6f 72 20 6f  on page (0 for o
09b0: 76 65 72 66 6c 6f 77 29 0a 20 20 70 61 79 6c 6f  verflow).  paylo
09c0: 61 64 20 20 20 20 49 4e 54 45 47 45 52 2c 20 20  ad    INTEGER,  
09d0: 20 20 20 2d 2d 20 42 79 74 65 73 20 6f 66 20 70     -- Bytes of p
09e0: 61 79 6c 6f 61 64 20 6f 6e 20 74 68 69 73 20 70  ayload on this p
09f0: 61 67 65 0a 20 20 75 6e 75 73 65 64 20 20 20 20  age.  unused    
0a00: 20 49 4e 54 45 47 45 52 2c 20 20 20 20 20 2d 2d   INTEGER,     --
0a10: 20 42 79 74 65 73 20 6f 66 20 75 6e 75 73 65 64   Bytes of unused
0a20: 20 73 70 61 63 65 20 6f 6e 20 74 68 69 73 20 70   space on this p
0a30: 61 67 65 0a 20 20 6d 78 5f 70 61 79 6c 6f 61 64  age.  mx_payload
0a40: 20 49 4e 54 45 47 45 52 2c 20 20 20 20 20 2d 2d   INTEGER,     --
0a50: 20 4c 61 72 67 65 73 74 20 70 61 79 6c 6f 61 64   Largest payload
0a60: 20 73 69 7a 65 20 6f 66 20 61 6c 6c 20 63 65 6c   size of all cel
0a70: 6c 73 20 6f 6e 20 74 68 69 73 20 70 61 67 65 0a  ls on this page.
0a80: 20 20 70 67 6f 66 66 73 65 74 20 20 20 49 4e 54    pgoffset   INT
0a90: 45 47 45 52 2c 20 20 20 20 20 2d 2d 20 4f 66 66  EGER,     -- Off
0aa0: 73 65 74 20 6f 66 20 70 61 67 65 20 69 6e 20 66  set of page in f
0ab0: 69 6c 65 0a 20 20 70 67 73 69 7a 65 20 20 20 20  ile.  pgsize    
0ac0: 20 49 4e 54 45 47 45 52 2c 20 20 20 20 20 2d 2d   INTEGER,     --
0ad0: 20 53 69 7a 65 20 6f 66 20 74 68 65 20 70 61 67   Size of the pag
0ae0: 65 0a 20 20 73 63 68 65 6d 61 20 20 20 20 20 54  e.  schema     T
0af0: 45 58 54 20 48 49 44 44 45 4e 20 20 2d 2d 20 44  EXT HIDDEN  -- D
0b00: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 62  atabase schema b
0b10: 65 69 6e 67 20 61 6e 61 6c 79 7a 65 64 0a 29 3b  eing analyzed.);
0b20: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
0b30: 70 3e 0a 54 68 65 72 65 20 69 73 20 61 20 73 69  p>.There is a si
0b40: 6e 67 6c 65 20 72 6f 77 20 6f 66 20 74 68 65 20  ngle row of the 
0b50: 64 62 73 74 61 74 20 74 61 62 6c 65 20 66 6f 72  dbstat table for
0b60: 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 74 68   each page in th
0b70: 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e.database file.
0b80: 20 20 46 72 65 65 6c 69 73 74 20 70 61 67 65 73    Freelist pages
0b90: 2c 20 74 68 65 20 6c 6f 63 6b 20 70 61 67 65 2c  , the lock page,
0ba0: 20 61 6e 64 0a 70 6f 69 6e 74 65 72 2d 6d 61 70   and.pointer-map
0bb0: 20 70 61 67 65 73 20 6f 66 20 74 68 65 20 64 61   pages of the da
0bc0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 6f 20 6e  tabase file do n
0bd0: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 65  ot appear in the
0be0: 0a 64 62 73 74 61 74 20 76 69 72 74 75 61 6c 20  .dbstat virtual 
0bf0: 74 61 62 6c 65 2e 0a 0a 3c 68 31 3e 54 68 65 20  table...<h1>The 
0c00: 22 70 61 74 68 22 20 63 6f 6c 75 6d 6e 20 6f 66  "path" column of
0c10: 20 74 68 65 20 64 62 73 74 61 74 20 76 69 72 74   the dbstat virt
0c20: 75 61 6c 20 74 61 62 6c 65 3c 2f 68 31 3e 0a 0a  ual table</h1>..
0c30: 3c 70 3e 0a 54 68 65 20 22 70 61 74 68 22 20 63  <p>.The "path" c
0c40: 6f 6c 75 6d 6e 20 64 65 73 63 72 69 62 65 73 20  olumn describes 
0c50: 74 68 65 20 70 61 74 68 20 74 61 6b 65 6e 20 66  the path taken f
0c60: 72 6f 6d 20 74 68 65 20 0a 72 6f 6f 74 20 6e 6f  rom the .root no
0c70: 64 65 20 6f 66 20 74 68 65 20 62 74 72 65 65 20  de of the btree 
0c80: 73 74 72 75 63 74 75 72 65 20 74 6f 20 65 61 63  structure to eac
0c90: 68 20 70 61 67 65 2e 20 20 54 68 65 0a 22 70 61  h page.  The."pa
0ca0: 74 68 22 20 6f 66 20 74 68 65 20 72 6f 6f 74 20  th" of the root 
0cb0: 6e 6f 64 65 20 69 74 73 65 6c 66 20 69 73 20 27  node itself is '
0cc0: 2f 27 2e 0a 0a 54 68 65 20 22 70 61 74 68 22 20  /'...The "path" 
0cd0: 66 6f 72 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73  for the left-mos
0ce0: 74 20 63 68 69 6c 64 20 70 61 67 65 20 6f 66 20  t child page of 
0cf0: 74 68 65 20 72 6f 6f 74 20 6f 66 0a 61 20 62 74  the root of.a bt
0d00: 72 65 65 20 70 61 67 65 20 69 73 20 27 2f 30 30  ree page is '/00
0d10: 30 2f 27 2e 20 28 42 74 72 65 65 73 20 73 74 6f  0/'. (Btrees sto
0d20: 72 65 20 63 6f 6e 74 65 6e 74 20 6f 72 64 65 72  re content order
0d30: 65 64 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20  ed from left to 
0d40: 72 69 67 68 74 0a 73 6f 20 74 68 65 20 70 61 67  right.so the pag
0d50: 65 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 68  es to the left h
0d60: 61 76 65 20 73 6d 61 6c 6c 65 72 20 6b 65 79 73  ave smaller keys
0d70: 20 74 68 61 6e 20 74 68 65 20 70 61 67 65 73 20   than the pages 
0d80: 74 6f 20 74 68 65 20 72 69 67 68 74 2e 29 0a 54  to the right.).T
0d90: 68 65 20 6e 65 78 74 20 74 6f 20 6c 65 66 74 2d  he next to left-
0da0: 6d 6f 73 74 20 63 68 69 6c 64 20 6f 66 20 74 68  most child of th
0db0: 65 20 72 6f 6f 74 20 70 61 67 65 20 69 73 20 27  e root page is '
0dc0: 2f 30 30 31 27 2c 20 61 6e 64 20 73 6f 20 6f 6e  /001', and so on
0dd0: 2c 0a 65 61 63 68 20 73 69 62 6c 69 6e 67 20 70  ,.each sibling p
0de0: 61 67 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  age identified b
0df0: 79 20 61 20 33 2d 64 69 67 69 74 20 68 65 78 20  y a 3-digit hex 
0e00: 20 76 61 6c 75 65 2e 0a 54 68 65 20 63 68 69 6c   value..The chil
0e10: 64 72 65 6e 20 6f 66 20 74 68 65 20 34 35 31 73  dren of the 451s
0e20: 74 20 6c 65 66 74 2d 6d 6f 73 74 20 73 69 62 6c  t left-most sibl
0e30: 69 6e 67 20 68 61 76 65 20 70 61 74 68 73 20 73  ing have paths s
0e40: 75 63 68 0a 61 73 20 27 2f 31 63 32 2f 30 30 30  uch.as '/1c2/000
0e50: 2f 2c 20 27 2f 31 63 32 2f 30 30 31 2f 27 20 65  /, '/1c2/001/' e
0e60: 74 63 2e 0a 0a 4f 76 65 72 66 6c 6f 77 20 70 61  tc...Overflow pa
0e70: 67 65 73 20 61 72 65 20 73 70 65 63 69 66 69 65  ges are specifie
0e80: 64 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  d by appending a
0e90: 20 27 2b 27 20 63 68 61 72 61 63 74 65 72 20 61   '+' character a
0ea0: 6e 64 20 61 20 0a 73 69 78 2d 64 69 67 69 74 20  nd a .six-digit 
0eb0: 68 65 78 61 64 65 63 69 6d 61 6c 20 76 61 6c 75  hexadecimal valu
0ec0: 65 20 74 6f 20 74 68 65 20 70 61 74 68 20 74 6f  e to the path to
0ed0: 20 74 68 65 20 63 65 6c 6c 20 74 68 65 79 20 61   the cell they a
0ee0: 72 65 20 6c 69 6e 6b 65 64 0a 66 72 6f 6d 2e 20  re linked.from. 
0ef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65  For example, the
0f00: 20 74 68 72 65 65 20 6f 76 65 72 66 6c 6f 77 20   three overflow 
0f10: 70 61 67 65 73 20 69 6e 20 61 20 63 68 61 69 6e  pages in a chain
0f20: 20 6c 69 6e 6b 65 64 20 66 72 6f 6d 20 0a 74 68   linked from .th
0f30: 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 65 6c 6c  e left-most cell
0f40: 20 6f 66 20 74 68 65 20 34 35 30 74 68 20 63 68   of the 450th ch
0f50: 69 6c 64 20 6f 66 20 74 68 65 20 72 6f 6f 74 20  ild of the root 
0f60: 70 61 67 65 20 61 72 65 20 69 64 65 6e 74 69 66  page are identif
0f70: 69 65 64 0a 62 79 20 74 68 65 20 70 61 74 68 73  ied.by the paths
0f80: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 27  :..<codeblock>.'
0f90: 2f 31 63 32 2f 30 30 30 2b 30 30 30 30 30 30 27  /1c2/000+000000'
0fa0: 20 20 20 20 20 20 20 20 20 2f 2f 20 46 69 72 73           // Firs
0fb0: 74 20 70 61 67 65 20 69 6e 20 6f 76 65 72 66 6c  t page in overfl
0fc0: 6f 77 20 63 68 61 69 6e 0a 27 2f 31 63 32 2f 30  ow chain.'/1c2/0
0fd0: 30 30 2b 30 30 30 30 30 31 27 20 20 20 20 20 20  00+000001'      
0fe0: 20 20 20 2f 2f 20 53 65 63 6f 6e 64 20 70 61 67     // Second pag
0ff0: 65 20 69 6e 20 6f 76 65 72 66 6c 6f 77 20 63 68  e in overflow ch
1000: 61 69 6e 0a 27 2f 31 63 32 2f 30 30 30 2b 30 30  ain.'/1c2/000+00
1010: 30 30 30 32 27 20 20 20 20 20 20 20 20 20 2f 2f  0002'         //
1020: 20 54 68 69 72 64 20 70 61 67 65 20 69 6e 20 6f   Third page in o
1030: 76 65 72 66 6c 6f 77 20 63 68 61 69 6e 0a 3c 2f  verflow chain.</
1040: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
1050: 49 66 20 74 68 65 20 70 61 74 68 73 20 61 72 65  If the paths are
1060: 20 73 6f 72 74 65 64 20 75 73 69 6e 67 20 74 68   sorted using th
1070: 65 20 42 49 4e 41 52 59 20 63 6f 6c 6c 61 74 69  e BINARY collati
1080: 6f 6e 20 73 65 71 75 65 6e 63 65 2c 20 74 68 65  on sequence, the
1090: 6e 0a 74 68 65 20 6f 76 65 72 66 6c 6f 77 20 70  n.the overflow p
10a0: 61 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 20  ages associated 
10b0: 77 69 74 68 20 61 20 63 65 6c 6c 20 77 69 6c 6c  with a cell will
10c0: 20 61 70 70 65 61 72 20 65 61 72 6c 69 65 72 20   appear earlier 
10d0: 69 6e 20 74 68 65 0a 73 6f 72 74 2d 6f 72 64 65  in the.sort-orde
10e0: 72 20 74 68 61 6e 20 69 74 73 20 63 68 69 6c 64  r than its child
10f0: 20 70 61 67 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f   page:..<codeblo
1100: 63 6b 3e 0a 27 2f 31 63 32 2f 30 30 30 2f 27 20  ck>.'/1c2/000/' 
1110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2f                //
1120: 20 4c 65 66 74 2d 6d 6f 73 74 20 63 68 69 6c 64   Left-most child
1130: 20 6f 66 20 34 35 31 73 74 20 63 68 69 6c 64 20   of 451st child 
1140: 6f 66 20 72 6f 6f 74 0a 3c 2f 63 6f 64 65 62 6c  of root.</codebl
1150: 6f 63 6b 3e 0a 0a 3c 68 31 3e 45 78 61 6d 70 6c  ock>..<h1>Exampl
1160: 65 20 75 73 65 73 20 6f 66 20 74 68 65 20 64 62  e uses of the db
1170: 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61 62  stat virtual tab
1180: 6c 65 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 54 6f 20  le</h1>..<p>.To 
1190: 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
11a0: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 75  umber of pages u
11b0: 73 65 64 20 74 6f 20 73 74 6f 72 65 20 74 61 62  sed to store tab
11c0: 6c 65 20 22 78 79 7a 22 20 69 6e 20 73 63 68 65  le "xyz" in sche
11d0: 6d 61 20 22 61 75 78 31 22 2c 0a 75 73 65 3a 0a  ma "aux1",.use:.
11e0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 53 45 4c  .<codeblock>.SEL
11f0: 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
1200: 4d 20 64 62 73 74 61 74 28 27 61 75 78 31 27 29  M dbstat('aux1')
1210: 20 57 48 45 52 45 20 6e 61 6d 65 3d 27 78 79 7a   WHERE name='xyz
1220: 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ';.</codeblock>.
1230: 0a 3c 70 3e 0a 54 6f 20 73 65 65 20 68 6f 77 20  .<p>.To see how 
1240: 65 66 66 69 63 69 65 6e 74 6c 79 20 74 68 65 20  efficiently the 
1250: 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 74 61 62  content of a tab
1260: 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 20  le is stored on 
1270: 64 69 73 6b 2c 0a 63 6f 6d 70 75 74 65 20 74 68  disk,.compute th
1280: 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
1290: 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 61  e used to hold a
12a0: 63 74 75 61 6c 20 63 6f 6e 74 65 6e 74 20 64 69  ctual content di
12b0: 76 69 64 65 64 0a 62 79 20 74 68 65 20 74 6f 74  vided.by the tot
12c0: 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 64 69 73  al amount of dis
12d0: 6b 20 73 70 61 63 65 20 75 73 65 64 2e 20 20 54  k space used.  T
12e0: 68 65 20 63 6c 6f 73 65 72 20 74 68 69 73 20 6e  he closer this n
12f0: 75 6d 62 65 72 0a 69 73 20 74 6f 20 31 30 30 25  umber.is to 100%
1300: 2c 20 74 68 65 20 6d 6f 72 65 20 65 66 66 69 63  , the more effic
1310: 69 65 6e 74 20 74 68 65 20 70 61 63 6b 69 6e 67  ient the packing
1320: 2e 20 20 28 49 6e 20 74 68 69 73 20 65 78 61 6d  .  (In this exam
1330: 70 6c 65 2c 20 74 68 65 0a 27 78 79 7a 27 20 74  ple, the.'xyz' t
1340: 61 62 6c 65 20 69 73 20 61 73 73 75 6d 65 64 20  able is assumed 
1350: 74 6f 20 62 65 20 69 6e 20 74 68 65 20 27 6d 61  to be in the 'ma
1360: 69 6e 27 20 73 63 68 65 6d 61 2e 29 0a 0a 3c 63  in' schema.)..<c
1370: 6f 64 65 62 6c 6f 63 6b 3e 0a 53 45 4c 45 43 54  odeblock>.SELECT
1380: 20 73 75 6d 28 70 67 73 69 7a 65 2d 75 6e 75 73   sum(pgsize-unus
1390: 65 64 29 2f 73 75 6d 28 70 67 73 69 7a 65 29 20  ed)/sum(pgsize) 
13a0: 46 52 4f 4d 20 64 62 73 74 61 74 20 57 48 45 52  FROM dbstat WHER
13b0: 45 20 6e 61 6d 65 3d 27 78 79 7a 27 3b 0a 3c 2f  E name='xyz';.</
13c0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
13d0: 54 6f 20 66 69 6e 64 20 74 68 65 20 61 76 65 72  To find the aver
13e0: 61 67 65 20 66 61 6e 2d 6f 75 74 20 66 6f 72 20  age fan-out for 
13f0: 61 20 74 61 62 6c 65 2c 20 72 75 6e 3a 0a 0a 3c  a table, run:..<
1400: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 53 45 4c 45 43  codeblock>.SELEC
1410: 54 20 61 76 67 28 6e 63 65 6c 6c 29 20 46 52 4f  T avg(ncell) FRO
1420: 4d 20 64 62 73 74 61 74 20 57 48 45 52 45 20 6e  M dbstat WHERE n
1430: 61 6d 65 3d 27 78 79 7a 27 20 41 4e 44 20 70 61  ame='xyz' AND pa
1440: 67 65 74 79 70 65 3d 27 69 6e 74 65 72 6e 61 6c  getype='internal
1450: 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ';.</codeblock>.
1460: 0a 0a 3c 70 3e 0a 4d 6f 64 65 72 6e 20 66 69 6c  ..<p>.Modern fil
1470: 65 73 79 73 74 65 6d 73 20 6f 70 65 72 61 74 65  esystems operate
1480: 20 66 61 73 74 65 72 20 77 68 65 6e 20 64 69 73   faster when dis
1490: 6b 20 61 63 63 65 73 73 65 73 20 61 72 65 20 73  k accesses are s
14a0: 65 71 75 65 6e 74 69 61 6c 2e 0a 48 65 6e 63 65  equential..Hence
14b0: 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75  , SQLite will ru
14c0: 6e 20 66 61 73 74 65 72 20 69 66 20 74 68 65 20  n faster if the 
14d0: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
14e0: 61 74 61 62 61 73 65 20 66 69 6c 65 0a 69 73 20  atabase file.is 
14f0: 6f 6e 20 73 65 71 75 65 6e 74 69 61 6c 20 70 61  on sequential pa
1500: 67 65 73 2e 20 20 54 6f 20 66 69 6e 64 20 6f 75  ges.  To find ou
1510: 74 20 77 68 61 74 20 66 72 61 63 74 69 6f 6e 20  t what fraction 
1520: 6f 66 20 74 68 65 20 70 61 67 65 73 20 69 6e 0a  of the pages in.
1530: 61 20 64 61 74 61 62 61 73 65 20 61 72 65 20 73  a database are s
1540: 65 71 75 65 6e 74 69 61 6c 20 28 61 6e 64 20 74  equential (and t
1550: 68 75 73 20 6f 62 74 61 69 6e 20 61 20 6d 65 61  hus obtain a mea
1560: 73 75 72 65 6d 65 6e 74 20 74 68 61 74 20 6d 69  surement that mi
1570: 67 68 74 0a 62 65 20 75 73 65 66 75 6c 20 69 6e  ght.be useful in
1580: 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 77 68 65   determining whe
1590: 6e 20 74 6f 20 5b 56 41 43 55 55 4d 5d 29 2c 20  n to [VACUUM]), 
15a0: 72 75 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65  run a query like
15b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
15c0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 43 52 45  .<codeblock>.CRE
15d0: 41 54 45 20 54 45 4d 50 20 54 41 42 4c 45 20 73  ATE TEMP TABLE s
15e0: 28 72 6f 77 69 64 20 49 4e 54 45 47 45 52 20 50  (rowid INTEGER P
15f0: 52 49 4d 41 52 59 20 4b 45 59 2c 20 70 61 67 65  RIMARY KEY, page
1600: 6e 6f 20 49 4e 54 29 3b 0a 49 4e 53 45 52 54 20  no INT);.INSERT 
1610: 49 4e 54 4f 20 73 28 70 61 67 65 6e 6f 29 20 53  INTO s(pageno) S
1620: 45 4c 45 43 54 20 70 61 67 65 6e 6f 20 46 52 4f  ELECT pageno FRO
1630: 4d 20 64 62 73 74 61 74 20 4f 52 44 45 52 20 42  M dbstat ORDER B
1640: 59 20 70 61 74 68 3b 0a 53 45 4c 45 43 54 20 73  Y path;.SELECT s
1650: 75 6d 28 73 31 2e 70 61 67 65 6e 6f 2b 31 3d 3d  um(s1.pageno+1==
1660: 73 32 2e 70 61 67 65 6e 6f 29 2a 31 2e 30 2f 63  s2.pageno)*1.0/c
1670: 6f 75 6e 74 28 2a 29 0a 20 20 46 52 4f 4d 20 73  ount(*).  FROM s
1680: 20 41 53 20 73 31 2c 20 73 20 41 53 20 73 32 0a   AS s1, s AS s2.
1690: 20 57 48 45 52 45 20 73 31 2e 72 6f 77 69 64 2b   WHERE s1.rowid+
16a0: 31 3d 73 32 2e 72 6f 77 69 64 3b 0a 44 52 4f 50  1=s2.rowid;.DROP
16b0: 20 54 41 42 4c 45 20 73 3b 0a 3c 2f 63 6f 64 65   TABLE s;.</code
16c0: 62 6c 6f 63 6b 3e 0a                             block>.