Documentation Source Text

Hex Artifact Content
Login

Artifact 9842e4dfbc43842f74b639b47384a2ee40780b45b0072d3cc77f3c4ad0a44887:


0000: 3c 74 69 74 6c 65 3e 51 75 65 72 79 20 4c 61 6e  <title>Query Lan
0010: 67 75 61 67 65 20 55 6e 64 65 72 73 74 6f 6f 64  guage Understood
0020: 20 62 79 20 53 51 4c 69 74 65 3c 2f 74 69 74 6c   by SQLite</titl
0030: 65 3e 0a 0a 3c 68 31 20 61 6c 69 67 6e 3d 63 65  e>..<h1 align=ce
0040: 6e 74 65 72 3e 53 51 4c 20 41 73 20 55 6e 64 65  nter>SQL As Unde
0050: 72 73 74 6f 6f 64 20 42 79 20 53 51 4c 69 74 65  rstood By SQLite
0060: 3c 2f 68 31 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65  </h1>..<p>SQLite
0070: 20 75 6e 64 65 72 73 74 61 6e 64 73 20 6d 6f 73   understands mos
0080: 74 20 6f 66 20 74 68 65 20 73 74 61 6e 64 61 72  t of the standar
0090: 64 20 53 51 4c 0a 6c 61 6e 67 75 61 67 65 2e 20  d SQL.language. 
00a0: 20 42 75 74 20 69 74 20 64 6f 65 73 20 3c 61 20   But it does <a 
00b0: 68 72 65 66 3d 22 6f 6d 69 74 74 65 64 2e 68 74  href="omitted.ht
00c0: 6d 6c 22 3e 6f 6d 69 74 20 73 6f 6d 65 20 66 65  ml">omit some fe
00d0: 61 74 75 72 65 73 3c 2f 61 3e 0a 77 68 69 6c 65  atures</a>.while
00e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
00f0: 65 0a 61 64 64 69 6e 67 20 61 20 66 65 77 20 66  e.adding a few f
0100: 65 61 74 75 72 65 73 20 6f 66 20 69 74 73 20 6f  eatures of its o
0110: 77 6e 2e 20 20 54 68 69 73 20 64 6f 63 75 6d 65  wn.  This docume
0120: 6e 74 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 64  nt attempts to.d
0130: 65 73 63 72 69 62 65 20 70 72 65 63 69 73 65 6c  escribe precisel
0140: 79 20 77 68 61 74 20 70 61 72 74 73 20 6f 66 20  y what parts of 
0150: 74 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67 65  the SQL language
0160: 20 53 51 4c 69 74 65 20 64 6f 65 73 0a 61 6e 64   SQLite does.and
0170: 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
0180: 74 2e 20 20 41 20 6c 69 73 74 20 6f 66 20 5b 53  t.  A list of [S
0190: 51 4c 20 6b 65 79 77 6f 72 64 73 5d 20 69 73 20  QL keywords] is 
01a0: 0a 61 6c 73 6f 20 70 72 6f 76 69 64 65 64 2e 20  .also provided. 
01b0: 20 54 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67   The SQL languag
01c0: 65 20 73 79 6e 74 61 78 20 69 73 20 64 65 73 63  e syntax is desc
01d0: 72 69 62 65 64 20 62 79 0a 5b 73 79 6e 74 61 78  ribed by.[syntax
01e0: 20 64 69 61 67 72 61 6d 73 5d 2e 0a 0a 3c 70 3e   diagrams]...<p>
01f0: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 79  The following sy
0200: 6e 74 61 78 20 64 6f 63 75 6d 65 6e 74 61 74 69  ntax documentati
0210: 6f 6e 20 74 6f 70 69 63 73 20 61 72 65 20 61 76  on topics are av
0220: 61 69 6c 61 62 6c 65 3a 3c 2f 70 3e 0a 0a 3c 74  ailable:</p>..<t
0230: 61 62 6c 65 20 77 69 64 74 68 3d 22 31 30 30 25  able width="100%
0240: 22 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 22 35  " cellpadding="5
0250: 22 20 62 6f 72 64 65 72 3d 22 30 22 3e 0a 3c 74  " border="0">.<t
0260: 72 3e 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  r><td valign="to
0270: 70 22 3e 3c 75 6c 3e 0a 0a 3c 74 63 6c 3e 0a 20  p"><ul>..<tcl>. 
0280: 20 73 65 74 20 69 20 30 0a 20 20 73 65 74 20 6c   set i 0.  set l
0290: 61 6e 67 5f 73 65 63 74 69 6f 6e 5f 6c 69 73 74  ang_section_list
02a0: 20 7b 0a 20 20 20 20 7b 7b 43 52 45 41 54 45 20   {.    {{CREATE 
02b0: 54 41 42 4c 45 7d 20 63 72 65 61 74 65 74 61 62  TABLE} createtab
02c0: 6c 65 7d 0a 20 20 20 20 7b 7b 43 52 45 41 54 45  le}.    {{CREATE
02d0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 7d 20   VIRTUAL TABLE} 
02e0: 63 72 65 61 74 65 76 74 61 62 7d 0a 20 20 20 20  createvtab}.    
02f0: 7b 7b 43 52 45 41 54 45 20 49 4e 44 45 58 7d 20  {{CREATE INDEX} 
0300: 63 72 65 61 74 65 69 6e 64 65 78 7d 0a 20 20 20  createindex}.   
0310: 20 7b 56 41 43 55 55 4d 20 76 61 63 75 75 6d 7d   {VACUUM vacuum}
0320: 0a 20 20 20 20 7b 7b 44 52 4f 50 20 54 41 42 4c  .    {{DROP TABL
0330: 45 7d 20 64 72 6f 70 74 61 62 6c 65 7d 0a 20 20  E} droptable}.  
0340: 20 20 7b 7b 44 52 4f 50 20 49 4e 44 45 58 7d 20    {{DROP INDEX} 
0350: 64 72 6f 70 69 6e 64 65 78 7d 0a 20 20 20 20 7b  dropindex}.    {
0360: 49 4e 53 45 52 54 20 69 6e 73 65 72 74 7d 0a 20  INSERT insert}. 
0370: 20 20 20 7b 52 45 50 4c 41 43 45 20 72 65 70 6c     {REPLACE repl
0380: 61 63 65 7d 0a 20 20 20 20 7b 44 45 4c 45 54 45  ace}.    {DELETE
0390: 20 64 65 6c 65 74 65 7d 0a 20 20 20 20 7b 55 50   delete}.    {UP
03a0: 44 41 54 45 20 75 70 64 61 74 65 7d 0a 20 20 20  DATE update}.   
03b0: 20 7b 53 45 4c 45 43 54 20 73 65 6c 65 63 74 7d   {SELECT select}
03c0: 0a 20 20 20 20 7b 7b 57 49 54 48 20 63 6c 61 75  .    {{WITH clau
03d0: 73 65 7d 20 77 69 74 68 63 6c 61 75 73 65 7d 0a  se} withclause}.
03e0: 20 20 20 20 7b 63 6f 6d 6d 65 6e 74 20 63 6f 6d      {comment com
03f0: 6d 65 6e 74 7d 0a 20 20 20 20 7b 45 58 50 4c 41  ment}.    {EXPLA
0400: 49 4e 20 65 78 70 6c 61 69 6e 7d 0a 20 20 20 20  IN explain}.    
0410: 7b 65 78 70 72 65 73 73 69 6f 6e 20 65 78 70 72  {expression expr
0420: 7d 0a 20 20 20 20 7b 7b 42 45 47 49 4e 20 54 52  }.    {{BEGIN TR
0430: 41 4e 53 41 43 54 49 4f 4e 7d 20 74 72 61 6e 73  ANSACTION} trans
0440: 61 63 74 69 6f 6e 7d 0a 20 20 20 20 7b 7b 43 4f  action}.    {{CO
0450: 4d 4d 49 54 20 54 52 41 4e 53 41 43 54 49 4f 4e  MMIT TRANSACTION
0460: 7d 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 43 4f  } transaction CO
0470: 4d 4d 49 54 7d 0a 20 20 20 20 7b 7b 45 4e 44 20  MMIT}.    {{END 
0480: 54 52 41 4e 53 41 43 54 49 4f 4e 7d 20 74 72 61  TRANSACTION} tra
0490: 6e 73 61 63 74 69 6f 6e 20 43 4f 4d 4d 49 54 7d  nsaction COMMIT}
04a0: 0a 20 20 20 20 7b 7b 52 4f 4c 4c 42 41 43 4b 20  .    {{ROLLBACK 
04b0: 54 52 41 4e 53 41 43 54 49 4f 4e 7d 20 74 72 61  TRANSACTION} tra
04c0: 6e 73 61 63 74 69 6f 6e 20 52 4f 4c 4c 42 41 43  nsaction ROLLBAC
04d0: 4b 7d 0a 20 20 20 20 7b 53 41 56 45 50 4f 49 4e  K}.    {SAVEPOIN
04e0: 54 20 73 61 76 65 70 6f 69 6e 74 7d 0a 20 20 20  T savepoint}.   
04f0: 20 7b 7b 52 45 4c 45 41 53 45 20 53 41 56 45 50   {{RELEASE SAVEP
0500: 4f 49 4e 54 7d 20 73 61 76 65 70 6f 69 6e 74 20  OINT} savepoint 
0510: 53 41 56 45 50 4f 49 4e 54 7d 0a 20 20 20 20 7b  SAVEPOINT}.    {
0520: 50 52 41 47 4d 41 20 70 72 61 67 6d 61 2e 68 74  PRAGMA pragma.ht
0530: 6d 6c 7d 0a 20 20 20 20 7b 7b 4f 4e 20 43 4f 4e  ml}.    {{ON CON
0540: 46 4c 49 43 54 20 63 6c 61 75 73 65 7d 20 63 6f  FLICT clause} co
0550: 6e 66 6c 69 63 74 7d 0a 20 20 20 20 7b 7b 43 52  nflict}.    {{CR
0560: 45 41 54 45 20 56 49 45 57 7d 20 63 72 65 61 74  EATE VIEW} creat
0570: 65 76 69 65 77 7d 0a 20 20 20 20 7b 7b 44 52 4f  eview}.    {{DRO
0580: 50 20 56 49 45 57 7d 20 64 72 6f 70 76 69 65 77  P VIEW} dropview
0590: 7d 0a 20 20 20 20 7b 7b 43 52 45 41 54 45 20 54  }.    {{CREATE T
05a0: 52 49 47 47 45 52 7d 20 63 72 65 61 74 65 74 72  RIGGER} createtr
05b0: 69 67 67 65 72 7d 0a 20 20 20 20 7b 7b 44 52 4f  igger}.    {{DRO
05c0: 50 20 54 52 49 47 47 45 52 7d 20 64 72 6f 70 74  P TRIGGER} dropt
05d0: 72 69 67 67 65 72 7d 0a 20 20 20 20 7b 7b 41 54  rigger}.    {{AT
05e0: 54 41 43 48 20 44 41 54 41 42 41 53 45 7d 20 61  TACH DATABASE} a
05f0: 74 74 61 63 68 7d 0a 20 20 20 20 7b 7b 44 45 54  ttach}.    {{DET
0600: 41 43 48 20 44 41 54 41 42 41 53 45 7d 20 64 65  ACH DATABASE} de
0610: 74 61 63 68 7d 0a 20 20 20 20 20 20 7b 52 45 49  tach}.      {REI
0620: 4e 44 45 58 20 72 65 69 6e 64 65 78 7d 0a 20 20  NDEX reindex}.  
0630: 20 20 7b 7b 41 4c 54 45 52 20 54 41 42 4c 45 7d    {{ALTER TABLE}
0640: 20 61 6c 74 65 72 74 61 62 6c 65 7d 0a 20 20 20   altertable}.   
0650: 20 7b 7b 41 4e 41 4c 59 5a 45 7d 20 61 6e 61 6c   {{ANALYZE} anal
0660: 79 7a 65 7d 0a 20 20 20 20 7b 7b 49 4e 44 45 58  yze}.    {{INDEX
0670: 45 44 20 42 59 7d 20 69 6e 64 65 78 65 64 62 79  ED BY} indexedby
0680: 7d 0a 20 20 20 20 7b 7b 61 67 67 72 65 67 61 74  }.    {{aggregat
0690: 65 20 66 75 6e 63 74 69 6f 6e 73 7d 20 61 67 67  e functions} agg
06a0: 66 75 6e 63 20 61 67 67 66 75 6e 63 7d 0a 20 20  func aggfunc}.  
06b0: 20 20 7b 7b 63 6f 72 65 20 66 75 6e 63 74 69 6f    {{core functio
06c0: 6e 73 7d 20 63 6f 72 65 66 75 6e 63 20 63 6f 72  ns} corefunc cor
06d0: 65 66 75 6e 63 7d 0a 20 20 20 20 7b 7b 64 61 74  efunc}.    {{dat
06e0: 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63 74  e and time funct
06f0: 69 6f 6e 73 7d 20 64 61 74 65 66 75 6e 63 20 64  ions} datefunc d
0700: 61 74 65 66 75 6e 63 7d 0a 20 20 20 20 7b 6b 65  atefunc}.    {ke
0710: 79 77 6f 72 64 73 20 6b 65 79 77 6f 72 64 73 20  ywords keywords 
0720: 7b 53 51 4c 20 6b 65 79 77 6f 72 64 73 7d 7d 0a  {SQL keywords}}.
0730: 20 20 7d 0a 20 20 73 65 74 20 6c 78 20 7b 7d 0a    }.  set lx {}.
0740: 20 20 66 6f 72 65 61 63 68 20 7b 73 65 63 74 69    foreach {secti
0750: 6f 6e 7d 20 5b 6c 73 6f 72 74 20 2d 69 6e 64 65  on} [lsort -inde
0760: 78 20 30 20 2d 64 69 63 74 69 6f 6e 61 72 79 20  x 0 -dictionary 
0770: 24 6c 61 6e 67 5f 73 65 63 74 69 6f 6e 5f 6c 69  $lang_section_li
0780: 73 74 5d 20 7b 0a 20 20 20 20 66 6f 72 65 61 63  st] {.    foreac
0790: 68 20 7b 73 5f 74 69 74 6c 65 20 73 5f 74 61 67  h {s_title s_tag
07a0: 20 73 5f 6b 77 7d 20 24 73 65 63 74 69 6f 6e 20   s_kw} $section 
07b0: 7b 7d 0a 20 20 20 20 69 66 20 7b 24 73 5f 6b 77  {}.    if {$s_kw
07c0: 20 3d 3d 20 22 22 7d 20 7b 0a 20 20 20 20 20 20   == ""} {.      
07d0: 73 65 74 20 73 5f 6b 77 20 24 73 5f 74 69 74 6c  set s_kw $s_titl
07e0: 65 0a 20 20 20 20 7d 0a 20 20 20 20 6c 61 70 70  e.    }.    lapp
07f0: 65 6e 64 20 6c 78 20 5b 6c 69 73 74 20 24 73 5f  end lx [list $s_
0800: 6b 77 20 24 73 5f 74 69 74 6c 65 20 30 5d 0a 20  kw $s_title 0]. 
0810: 20 7d 0a 20 20 68 64 5f 6c 69 73 74 5f 6f 66 5f   }.  hd_list_of_
0820: 6c 69 6e 6b 73 20 7b 7d 20 33 34 30 20 24 6c 78  links {} 340 $lx
0830: 0a 3c 2f 74 63 6c 3e 0a 3c 2f 75 6c 3e 3c 2f 74  .</tcl>.</ul></t
0840: 64 3e 3c 2f 74 72 3e 3c 2f 74 61 62 6c 65 3e 0a  d></tr></table>.
0850: 0a 3c 70 3e 5e 54 68 65 20 72 6f 75 74 69 6e 65  .<p>^The routine
0860: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
0870: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
0880: 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c 0a 5b  e3_prepare()],.[
0890: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
08a0: 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  6()], [sqlite3_p
08b0: 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
08c0: 0a 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  .[sqlite3_exec()
08d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
08e0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 61 63 63  get_table()] acc
08f0: 65 70 74 0a 61 6e 20 53 51 4c 20 73 74 61 74 65  ept.an SQL state
0900: 6d 65 6e 74 20 6c 69 73 74 20 28 73 71 6c 2d 73  ment list (sql-s
0910: 74 6d 74 2d 6c 69 73 74 29 20 77 68 69 63 68 20  tmt-list) which 
0920: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  is a semicolon-s
0930: 65 70 61 72 61 74 65 64 0a 6c 69 73 74 20 6f 66  eparated.list of
0940: 20 73 74 61 74 65 6d 65 6e 74 73 2e 3c 2f 70 3e   statements.</p>
0950: 0a 0a 3c 74 63 6c 3e 42 75 62 62 6c 65 44 69 61  ..<tcl>BubbleDia
0960: 67 72 61 6d 20 73 71 6c 2d 73 74 6d 74 2d 6c 69  gram sql-stmt-li
0970: 73 74 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 45 61 63  st</tcl>..<p>Eac
0980: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
0990: 69 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  in the statement
09a0: 20 6c 69 73 74 20 69 73 20 61 6e 20 69 6e 73 74   list is an inst
09b0: 61 6e 63 65 20 6f 66 20 74 68 65 0a 66 6f 6c 6c  ance of the.foll
09c0: 6f 77 69 6e 67 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c  owing:</p>..<tcl
09d0: 3e 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 73  >BubbleDiagram s
09e0: 71 6c 2d 73 74 6d 74 3c 2f 74 63 6c 3e 0a 0a 3c  ql-stmt</tcl>..<
09f0: 74 63 6c 3e 0a 70 72 6f 63 20 4f 70 65 72 61 74  tcl>.proc Operat
0a00: 6f 72 20 7b 6e 61 6d 65 7d 20 7b 0a 20 20 72 65  or {name} {.  re
0a10: 74 75 72 6e 20 22 3c 66 6f 6e 74 20 63 6f 6c 6f  turn "<font colo
0a20: 72 3d 5c 22 23 32 63 32 63 66 30 5c 22 3e 3c 62  r=\"#2c2cf0\"><b
0a30: 69 67 3e 24 6e 61 6d 65 3c 2f 62 69 67 3e 3c 2f  ig>$name</big></
0a40: 66 6f 6e 74 3e 22 0a 7d 0a 70 72 6f 63 20 4e 6f  font>".}.proc No
0a50: 6e 74 65 72 6d 69 6e 61 6c 20 7b 6e 61 6d 65 7d  nterminal {name}
0a60: 20 7b 0a 20 20 72 65 74 75 72 6e 20 22 3c 69 3e   {.  return "<i>
0a70: 3c 66 6f 6e 74 20 63 6f 6c 6f 72 3d 5c 22 23 66  <font color=\"#f
0a80: 66 33 34 33 34 5c 22 3e 24 6e 61 6d 65 3c 2f 66  f3434\">$name</f
0a90: 6f 6e 74 3e 3c 2f 69 3e 22 0a 7d 0a 70 72 6f 63  ont></i>".}.proc
0aa0: 20 4b 65 79 77 6f 72 64 20 7b 6e 61 6d 65 7d 20   Keyword {name} 
0ab0: 7b 0a 20 20 72 65 74 75 72 6e 20 22 3c 66 6f 6e  {.  return "<fon
0ac0: 74 20 63 6f 6c 6f 72 3d 5c 22 23 32 63 32 63 66  t color=\"#2c2cf
0ad0: 30 5c 22 3e 24 6e 61 6d 65 3c 2f 66 6f 6e 74 3e  0\">$name</font>
0ae0: 22 0a 7d 0a 70 72 6f 63 20 45 78 61 6d 70 6c 65  ".}.proc Example
0af0: 20 7b 74 65 78 74 7d 20 7b 0a 20 20 68 64 5f 70   {text} {.  hd_p
0b00: 75 74 73 20 22 3c 62 6c 6f 63 6b 71 75 6f 74 65  uts "<blockquote
0b10: 3e 3c 70 72 65 3e 24 74 65 78 74 3c 2f 70 72 65  ><pre>$text</pre
0b20: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 22 0a  ></blockquote>".
0b30: 7d 0a 0a 70 72 6f 63 20 53 65 63 74 69 6f 6e 20  }..proc Section 
0b40: 7b 6e 61 6d 65 20 6c 61 62 65 6c 20 6b 65 79 77  {name label keyw
0b50: 6f 72 64 73 7d 20 7b 0a 20 20 67 6c 6f 62 61 6c  ords} {.  global
0b60: 20 44 4f 43 0a 20 20 68 64 5f 63 6c 6f 73 65 5f   DOC.  hd_close_
0b70: 6d 61 69 6e 0a 20 20 68 64 5f 6f 70 65 6e 5f 6d  main.  hd_open_m
0b80: 61 69 6e 20 6c 61 6e 67 5f 24 6c 61 62 65 6c 2e  ain lang_$label.
0b90: 68 74 6d 6c 0a 20 20 68 64 5f 68 65 61 64 65 72  html.  hd_header
0ba0: 20 22 53 51 4c 69 74 65 20 51 75 65 72 79 20 4c   "SQLite Query L
0bb0: 61 6e 67 75 61 67 65 3a 20 24 6e 61 6d 65 22 20  anguage: $name" 
0bc0: 24 44 4f 43 2f 70 61 67 65 73 2f 6c 61 6e 67 2e  $DOC/pages/lang.
0bd0: 69 6e 0a 20 20 65 76 61 6c 20 68 64 5f 6b 65 79  in.  eval hd_key
0be0: 77 6f 72 64 73 20 24 6b 65 79 77 6f 72 64 73 0a  words $keywords.
0bf0: 20 20 69 66 20 7b 5b 6c 73 65 61 72 63 68 20 24    if {[lsearch $
0c00: 6b 65 79 77 6f 72 64 73 20 24 6e 61 6d 65 5d 20  keywords $name] 
0c10: 3d 3d 20 2d 31 20 26 26 20 5b 6c 73 65 61 72 63  == -1 && [lsearc
0c20: 68 20 24 6b 65 79 77 6f 72 64 73 20 2a 24 6e 61  h $keywords *$na
0c30: 6d 65 5d 20 3d 3d 20 2d 31 7d 20 7b 0a 20 20 20  me] == -1} {.   
0c40: 20 65 76 61 6c 20 68 64 5f 6b 65 79 77 6f 72 64   eval hd_keyword
0c50: 73 20 7b 20 24 6e 61 6d 65 20 7d 0a 20 20 7d 0a  s { $name }.  }.
0c60: 20 20 68 64 5f 70 75 74 73 20 7b 3c 64 69 76 20    hd_puts {<div 
0c70: 63 6c 61 73 73 3d 6e 6f 73 65 61 72 63 68 3e 7d  class=nosearch>}
0c80: 0a 20 20 68 64 5f 70 75 74 73 20 7b 3c 68 31 20  .  hd_puts {<h1 
0c90: 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 53  align="center">S
0ca0: 51 4c 20 41 73 20 55 6e 64 65 72 73 74 6f 6f 64  QL As Understood
0cb0: 20 42 79 20 53 51 4c 69 74 65 3c 2f 68 31 3e 7d   By SQLite</h1>}
0cc0: 0a 20 20 68 64 5f 70 75 74 73 20 7b 3c 70 3e 3c  .  hd_puts {<p><
0cd0: 61 20 68 72 65 66 3d 22 6c 61 6e 67 2e 68 74 6d  a href="lang.htm
0ce0: 6c 22 3e 5b 54 6f 70 5d 3c 2f 61 3e 3c 2f 70 3e  l">[Top]</a></p>
0cf0: 7d 0a 20 20 68 64 5f 70 75 74 73 20 22 3c 68 32  }.  hd_puts "<h2
0d00: 3e 24 6e 61 6d 65 3c 2f 68 32 3e 22 0a 20 20 68  >$name</h2>".  h
0d10: 64 5f 70 75 74 73 20 7b 3c 2f 64 69 76 3e 7d 0a  d_puts {</div>}.
0d20: 7d 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  }..#############
0d30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0d40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0d50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0d60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0d70: 23 23 0a 53 65 63 74 69 6f 6e 20 7b 41 4c 54 45  ##.Section {ALTE
0d80: 52 20 54 41 42 4c 45 7d 20 61 6c 74 65 72 74 61  R TABLE} alterta
0d90: 62 6c 65 20 7b 7b 41 4c 54 45 52 20 54 41 42 4c  ble {{ALTER TABL
0da0: 45 7d 20 7b 2a 41 4c 54 45 52 7d 7d 0a 0a 52 65  E} {*ALTER}}..Re
0db0: 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
0dc0: 67 72 61 6d 20 61 6c 74 65 72 2d 74 61 62 6c 65  gram alter-table
0dd0: 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70  -stmt.</tcl>..<p
0de0: 3e 53 51 4c 69 74 65 20 73 75 70 70 6f 72 74 73  >SQLite supports
0df0: 20 61 20 6c 69 6d 69 74 65 64 20 73 75 62 73 65   a limited subse
0e00: 74 20 6f 66 20 41 4c 54 45 52 20 54 41 42 4c 45  t of ALTER TABLE
0e10: 2e 0a 54 68 65 20 41 4c 54 45 52 20 54 41 42 4c  ..The ALTER TABL
0e20: 45 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 53 51 4c  E command in SQL
0e30: 69 74 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 75  ite allows the u
0e40: 73 65 72 20 74 6f 20 72 65 6e 61 6d 65 20 61 20  ser to rename a 
0e50: 74 61 62 6c 65 0a 6f 72 20 74 6f 20 61 64 64 20  table.or to add 
0e60: 61 20 6e 65 77 20 63 6f 6c 75 6d 6e 20 74 6f 20  a new column to 
0e70: 61 6e 20 65 78 69 73 74 69 6e 67 20 74 61 62 6c  an existing tabl
0e80: 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28 54  e..</p>..<p> ^(T
0e90: 68 65 20 52 45 4e 41 4d 45 20 54 4f 20 73 79 6e  he RENAME TO syn
0ea0: 74 61 78 20 63 68 61 6e 67 65 73 20 74 68 65 20  tax changes the 
0eb0: 6e 61 6d 65 20 6f 66 20 3c 79 79 74 65 72 6d 3e  name of <yyterm>
0ec0: 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65  table-name</yyte
0ed0: 72 6d 3e 0a 74 6f 20 3c 79 79 74 65 72 6d 3e 6e  rm>.to <yyterm>n
0ee0: 65 77 2d 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79  ew-table-name</y
0ef0: 79 74 65 72 6d 3e 2e 29 5e 0a 54 68 69 73 20 63  yterm>.)^.This c
0f00: 6f 6d 6d 61 6e 64 20 0a 63 61 6e 6e 6f 74 20 62  ommand .cannot b
0f10: 65 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 61  e used to move a
0f20: 20 74 61 62 6c 65 20 62 65 74 77 65 65 6e 20 61   table between a
0f30: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
0f40: 73 2c 20 6f 6e 6c 79 20 74 6f 20 72 65 6e 61 6d  s, only to renam
0f50: 65 20 0a 61 20 74 61 62 6c 65 20 77 69 74 68 69  e .a table withi
0f60: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
0f70: 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 49  ase.</p>..<p> ^I
0f80: 66 20 74 68 65 20 74 61 62 6c 65 20 62 65 69 6e  f the table bein
0f90: 67 20 72 65 6e 61 6d 65 64 20 68 61 73 20 74 72  g renamed has tr
0fa0: 69 67 67 65 72 73 20 6f 72 20 69 6e 64 69 63 65  iggers or indice
0fb0: 73 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 65  s, then these re
0fc0: 6d 61 69 6e 0a 61 74 74 61 63 68 65 64 20 74 6f  main.attached to
0fd0: 20 74 68 65 20 74 61 62 6c 65 20 61 66 74 65 72   the table after
0fe0: 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6e   it has been ren
0ff0: 61 6d 65 64 2e 20 20 5e 48 6f 77 65 76 65 72 2c  amed.  ^However,
1000: 20 69 66 20 74 68 65 72 65 20 61 72 65 0a 61 6e   if there are.an
1010: 79 20 76 69 65 77 20 64 65 66 69 6e 69 74 69 6f  y view definitio
1020: 6e 73 2c 20 6f 72 20 73 74 61 74 65 6d 65 6e 74  ns, or statement
1030: 73 20 65 78 65 63 75 74 65 64 20 62 79 20 74 72  s executed by tr
1040: 69 67 67 65 72 73 20 74 68 61 74 20 72 65 66 65  iggers that refe
1050: 72 20 74 6f 0a 74 68 65 20 74 61 62 6c 65 20 62  r to.the table b
1060: 65 69 6e 67 20 72 65 6e 61 6d 65 64 2c 20 74 68  eing renamed, th
1070: 65 73 65 20 61 72 65 20 6e 6f 74 20 61 75 74 6f  ese are not auto
1080: 6d 61 74 69 63 61 6c 6c 79 20 6d 6f 64 69 66 69  matically modifi
1090: 65 64 20 74 6f 20 75 73 65 20 74 68 65 20 6e 65  ed to use the ne
10a0: 77 0a 74 61 62 6c 65 20 6e 61 6d 65 2e 20 49 66  w.table name. If
10b0: 20 74 68 69 73 20 69 73 20 72 65 71 75 69 72 65   this is require
10c0: 64 2c 20 74 68 65 20 74 72 69 67 67 65 72 73 20  d, the triggers 
10d0: 6f 72 20 76 69 65 77 20 64 65 66 69 6e 69 74 69  or view definiti
10e0: 6f 6e 73 20 6d 75 73 74 20 62 65 0a 64 72 6f 70  ons must be.drop
10f0: 70 65 64 20 61 6e 64 20 72 65 63 72 65 61 74 65  ped and recreate
1100: 64 20 74 6f 20 75 73 65 20 74 68 65 20 6e 65 77  d to use the new
1110: 20 74 61 62 6c 65 20 6e 61 6d 65 20 62 79 20 68   table name by h
1120: 61 6e 64 2e 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  and..</p>..<bloc
1130: 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f  kquote><table bo
1140: 72 64 65 72 3d 22 31 22 20 63 65 6c 6c 70 61 64  rder="1" cellpad
1150: 64 69 6e 67 3d 22 31 30 22 3e 0a 3c 74 72 3e 3c  ding="10">.<tr><
1160: 74 64 3e 0a 3c 65 6d 3e 49 6d 70 6f 72 74 61 6e  td>.<em>Importan
1170: 74 20 4e 6f 74 65 3a 3c 2f 65 6d 3e 0a 54 68 65  t Note:</em>.The
1180: 20 27 41 4c 54 45 52 20 54 41 42 4c 45 20 2e 2e   'ALTER TABLE ..
1190: 2e 20 52 45 4e 41 4d 45 20 54 4f 20 2e 2e 2e 27  . RENAME TO ...'
11a0: 20 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 20 6e 6f   command does no
11b0: 74 20 75 70 64 61 74 65 20 61 63 74 69 6f 6e 0a  t update action.
11c0: 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69  statements withi
11d0: 6e 20 74 72 69 67 67 65 72 73 20 6f 72 20 53 45  n triggers or SE
11e0: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 20  LECT statements 
11f0: 77 69 74 68 69 6e 20 76 69 65 77 73 2e 0a 49 66  within views..If
1200: 20 74 68 65 20 74 61 62 6c 65 20 62 65 69 6e 67   the table being
1210: 20 72 65 6e 61 6d 65 64 20 69 73 20 72 65 66 65   renamed is refe
1220: 72 65 6e 63 65 64 20 66 72 6f 6d 20 77 69 74 68  renced from with
1230: 69 6e 20 74 72 69 67 67 65 72 73 20 6f 72 20 76  in triggers or v
1240: 69 65 77 73 2c 0a 74 68 65 6e 20 74 68 6f 73 65  iews,.then those
1250: 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 76 69   triggers and vi
1260: 65 77 73 20 6d 75 73 74 20 62 65 20 64 72 6f 70  ews must be drop
1270: 70 65 64 20 61 6e 64 20 72 65 63 72 65 61 74 65  ped and recreate
1280: 64 20 73 65 70 61 72 61 74 65 6c 79 0a 62 79 20  d separately.by 
1290: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
12a0: 0a 3c 2f 74 64 3e 3c 2f 74 72 3e 3c 2f 74 61 62  .</td></tr></tab
12b0: 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  le>.</blockquote
12c0: 3e 0a 0a 3c 70 3e 5e 49 66 20 5b 66 6f 72 65 69  >..<p>^If [forei
12d0: 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
12e0: 74 73 5d 20 61 72 65 20 0a 5b 66 6f 72 65 69 67  ts] are .[foreig
12f0: 6e 5f 6b 65 79 73 20 70 72 61 67 6d 61 20 7c 20  n_keys pragma | 
1300: 65 6e 61 62 6c 65 64 5d 20 77 68 65 6e 20 61 20  enabled] when a 
1310: 74 61 62 6c 65 20 69 73 20 72 65 6e 61 6d 65 64  table is renamed
1320: 2c 20 74 68 65 6e 20 61 6e 79 0a 5b 66 6f 72 65  , then any.[fore
1330: 69 67 6e 2d 6b 65 79 2d 63 6c 61 75 73 65 20 7c  ign-key-clause |
1340: 20 52 45 46 45 52 45 4e 43 45 53 20 63 6c 61 75   REFERENCES clau
1350: 73 65 73 5d 20 69 6e 20 61 6e 79 20 74 61 62 6c  ses] in any tabl
1360: 65 20 28 65 69 74 68 65 72 20 74 68 65 0a 74 61  e (either the.ta
1370: 62 6c 65 20 62 65 69 6e 67 20 72 65 6e 61 6d 65  ble being rename
1380: 64 20 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72 20  d or some other 
1390: 74 61 62 6c 65 29 0a 74 68 61 74 20 72 65 66 65  table).that refe
13a0: 72 20 74 6f 20 74 68 65 20 74 61 62 6c 65 20 62  r to the table b
13b0: 65 69 6e 67 20 72 65 6e 61 6d 65 64 20 61 72 65  eing renamed are
13c0: 20 6d 6f 64 69 66 69 65 64 20 74 6f 20 72 65 66   modified to ref
13d0: 65 72 20 0a 74 6f 20 74 68 65 20 72 65 6e 61 6d  er .to the renam
13e0: 65 64 20 74 61 62 6c 65 20 62 79 20 69 74 73 20  ed table by its 
13f0: 6e 65 77 20 6e 61 6d 65 2e 0a 0a 3c 70 3e 20 5e  new name...<p> ^
1400: 54 68 65 20 41 44 44 20 43 4f 4c 55 4d 4e 20 73  The ADD COLUMN s
1410: 79 6e 74 61 78 0a 69 73 20 75 73 65 64 20 74 6f  yntax.is used to
1420: 20 61 64 64 20 61 20 6e 65 77 20 63 6f 6c 75 6d   add a new colum
1430: 6e 20 74 6f 20 61 6e 20 65 78 69 73 74 69 6e 67  n to an existing
1440: 20 74 61 62 6c 65 2e 0a 5e 54 68 65 20 6e 65 77   table..^The new
1450: 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6c 77 61 79   column is alway
1460: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  s appended to th
1470: 65 20 65 6e 64 20 6f 66 20 74 68 65 20 6c 69 73  e end of the lis
1480: 74 20 6f 66 20 65 78 69 73 74 69 6e 67 20 63 6f  t of existing co
1490: 6c 75 6d 6e 73 2e 0a 54 68 65 20 5b 63 6f 6c 75  lumns..The [colu
14a0: 6d 6e 2d 64 65 66 5d 20 72 75 6c 65 20 64 65 66  mn-def] rule def
14b0: 69 6e 65 73 20 74 68 65 20 63 68 61 72 61 63 74  ines the charact
14c0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
14d0: 6e 65 77 20 63 6f 6c 75 6d 6e 2e 0a 5e 28 54 68  new column..^(Th
14e0: 65 20 6e 65 77 20 63 6f 6c 75 6d 6e 20 6d 61 79  e new column may
14f0: 20 74 61 6b 65 20 61 6e 79 20 6f 66 20 74 68 65   take any of the
1500: 20 66 6f 72 6d 73 20 70 65 72 6d 69 73 73 69 62   forms permissib
1510: 6c 65 20 69 6e 20 61 20 5b 43 52 45 41 54 45 20  le in a [CREATE 
1520: 54 41 42 4c 45 5d 0a 73 74 61 74 65 6d 65 6e 74  TABLE].statement
1530: 2c 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  , with the follo
1540: 77 69 6e 67 20 72 65 73 74 72 69 63 74 69 6f 6e  wing restriction
1550: 73 3a 29 5e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 5e 54  s:)^.<ul>.<li>^T
1560: 68 65 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 6e 6f  he column may no
1570: 74 20 68 61 76 65 20 61 20 50 52 49 4d 41 52 59  t have a PRIMARY
1580: 20 4b 45 59 20 6f 72 20 55 4e 49 51 55 45 20 63   KEY or UNIQUE c
1590: 6f 6e 73 74 72 61 69 6e 74 2e 3c 2f 6c 69 3e 0a  onstraint.</li>.
15a0: 3c 6c 69 3e 5e 54 68 65 20 63 6f 6c 75 6d 6e 20  <li>^The column 
15b0: 6d 61 79 20 6e 6f 74 20 68 61 76 65 20 61 20 64  may not have a d
15c0: 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20  efault value of 
15d0: 43 55 52 52 45 4e 54 5f 54 49 4d 45 2c 20 43 55  CURRENT_TIME, CU
15e0: 52 52 45 4e 54 5f 44 41 54 45 2c 20 0a 20 20 20  RRENT_DATE, .   
15f0: 20 43 55 52 52 45 4e 54 5f 54 49 4d 45 53 54 41   CURRENT_TIMESTA
1600: 4d 50 2c 20 6f 72 20 61 6e 20 65 78 70 72 65 73  MP, or an expres
1610: 73 69 6f 6e 20 69 6e 20 70 61 72 65 6e 74 68 65  sion in parenthe
1620: 73 65 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 5e 49  ses.</li>.<li>^I
1630: 66 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  f a NOT NULL con
1640: 73 74 72 61 69 6e 74 20 69 73 20 73 70 65 63 69  straint is speci
1650: 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 63  fied, then the c
1660: 6f 6c 75 6d 6e 20 6d 75 73 74 20 68 61 76 65 20  olumn must have 
1670: 61 0a 20 20 20 20 64 65 66 61 75 6c 74 20 76 61  a.    default va
1680: 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 4e  lue other than N
1690: 55 4c 4c 2e 0a 3c 6c 69 3e 5e 49 66 20 5b 66 6f  ULL..<li>^If [fo
16a0: 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
16b0: 61 69 6e 74 73 5d 20 61 72 65 20 5b 66 6f 72 65  aints] are [fore
16c0: 69 67 6e 5f 6b 65 79 73 20 70 72 61 67 6d 61 20  ign_keys pragma 
16d0: 7c 20 65 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 20  | enabled] and. 
16e0: 20 20 20 61 20 63 6f 6c 75 6d 6e 20 77 69 74 68     a column with
16f0: 20 61 20 5b 66 6f 72 65 69 67 6e 2d 6b 65 79 2d   a [foreign-key-
1700: 63 6c 61 75 73 65 20 7c 20 52 45 46 45 52 45 4e  clause | REFEREN
1710: 43 45 53 20 63 6c 61 75 73 65 5d 0a 20 20 20 20  CES clause].    
1720: 69 73 20 61 64 64 65 64 2c 20 74 68 65 20 63 6f  is added, the co
1730: 6c 75 6d 6e 20 6d 75 73 74 20 68 61 76 65 20 61  lumn must have a
1740: 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f   default value o
1750: 66 20 4e 55 4c 4c 2e 0a 3c 2f 75 6c 3e 0a 0a 3c  f NULL..</ul>..<
1760: 70 3e 5e 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  p>^Note also tha
1770: 74 20 77 68 65 6e 20 61 64 64 69 6e 67 20 61 20  t when adding a 
1780: 5b 43 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e  [CHECK constrain
1790: 74 5d 2c 20 74 68 65 20 43 48 45 43 4b 20 63 6f  t], the CHECK co
17a0: 6e 73 74 72 61 69 6e 74 0a 69 73 20 6e 6f 74 20  nstraint.is not 
17b0: 74 65 73 74 65 64 20 61 67 61 69 6e 73 74 20 70  tested against p
17c0: 72 65 65 78 69 73 74 69 6e 67 20 72 6f 77 73 20  reexisting rows 
17d0: 6f 66 20 74 68 65 20 74 61 62 6c 65 2e 0a 5e 54  of the table..^T
17e0: 68 69 73 20 63 61 6e 20 72 65 73 75 6c 74 20 69  his can result i
17f0: 6e 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 63  n a table that c
1800: 6f 6e 74 61 69 6e 73 20 64 61 74 61 20 74 68 61  ontains data tha
1810: 74 0a 69 73 20 69 6e 20 76 69 6f 6c 61 74 69 6f  t.is in violatio
1820: 6e 20 6f 66 20 74 68 65 20 43 48 45 43 4b 20 63  n of the CHECK c
1830: 6f 6e 73 74 72 61 69 6e 74 2e 20 20 46 75 74 75  onstraint.  Futu
1840: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1850: 51 4c 69 74 65 20 6d 69 67 68 74 0a 63 68 61 6e  QLite might.chan
1860: 67 65 20 74 6f 20 76 61 6c 69 64 61 74 65 20 43  ge to validate C
1870: 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 73  HECK constraints
1880: 20 61 73 20 74 68 65 79 20 61 72 65 20 61 64 64   as they are add
1890: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20 54 68 65  ed.</p>..<p> The
18a0: 20 65 78 65 63 75 74 69 6f 6e 20 74 69 6d 65 20   execution time 
18b0: 6f 66 20 74 68 65 20 41 4c 54 45 52 20 54 41 42  of the ALTER TAB
18c0: 4c 45 20 63 6f 6d 6d 61 6e 64 20 69 73 20 69 6e  LE command is in
18d0: 64 65 70 65 6e 64 65 6e 74 20 6f 66 0a 74 68 65  dependent of.the
18e0: 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
18f0: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54  in the table.  T
1900: 68 65 20 41 4c 54 45 52 20 54 41 42 4c 45 20 63  he ALTER TABLE c
1910: 6f 6d 6d 61 6e 64 20 72 75 6e 73 20 61 73 20 71  ommand runs as q
1920: 75 69 63 6b 6c 79 0a 6f 6e 20 61 20 74 61 62 6c  uickly.on a tabl
1930: 65 20 77 69 74 68 20 31 30 20 6d 69 6c 6c 69 6f  e with 10 millio
1940: 6e 20 72 6f 77 73 20 61 73 20 69 74 20 64 6f 65  n rows as it doe
1950: 73 20 6f 6e 20 61 20 74 61 62 6c 65 20 77 69 74  s on a table wit
1960: 68 20 31 20 72 6f 77 2e 0a 3c 2f 70 3e 0a 0a 3c  h 1 row..</p>..<
1970: 70 3e 41 66 74 65 72 20 41 44 44 20 43 4f 4c 55  p>After ADD COLU
1980: 4d 4e 20 68 61 73 20 62 65 65 6e 20 72 75 6e 20  MN has been run 
1990: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 2c 20 74  on a database, t
19a0: 68 61 74 20 64 61 74 61 62 61 73 65 20 77 69 6c  hat database wil
19b0: 6c 20 6e 6f 74 0a 62 65 20 72 65 61 64 61 62 6c  l not.be readabl
19c0: 65 20 62 79 20 53 51 4c 69 74 65 20 76 65 72 73  e by SQLite vers
19d0: 69 6f 6e 20 33 2e 31 2e 33 20 28 5b 64 61 74 65  ion 3.1.3 ([date
19e0: 6f 66 3a 33 2e 31 2e 33 5d 29 20 61 6e 64 20 65  of:3.1.3]) and e
19f0: 61 72 6c 69 65 72 2e 3c 2f 70 3e 0a 0a 3c 74 63  arlier.</p>..<tc
1a00: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6f 74  l>hd_fragment ot
1a10: 68 65 72 61 6c 74 65 72 3c 2f 74 63 6c 3e 0a 3c  heralter</tcl>.<
1a20: 68 33 3e 4d 61 6b 69 6e 67 20 4f 74 68 65 72 20  h3>Making Other 
1a30: 4b 69 6e 64 73 20 4f 66 20 54 61 62 6c 65 20 53  Kinds Of Table S
1a40: 63 68 65 6d 61 20 43 68 61 6e 67 65 73 3c 2f 68  chema Changes</h
1a50: 33 3e 0a 0a 3c 70 3e 20 54 68 65 20 6f 6e 6c 79  3>..<p> The only
1a60: 20 73 63 68 65 6d 61 20 61 6c 74 65 72 69 6e 67   schema altering
1a70: 20 63 6f 6d 6d 61 6e 64 73 20 64 69 72 65 63 74   commands direct
1a80: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
1a90: 53 51 4c 69 74 65 20 61 72 65 20 74 68 65 0a 22  SQLite are the."
1aa0: 72 65 6e 61 6d 65 20 74 61 62 6c 65 22 20 61 6e  rename table" an
1ab0: 64 20 22 61 64 64 20 63 6f 6c 75 6d 6e 22 20 63  d "add column" c
1ac0: 6f 6d 6d 61 6e 64 73 20 73 68 6f 77 6e 20 61 62  ommands shown ab
1ad0: 6f 76 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 61  ove.  However, a
1ae0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 63 61 6e 20  pplications.can 
1af0: 6d 61 6b 65 20 6f 74 68 65 72 20 61 72 62 69 74  make other arbit
1b00: 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1b10: 74 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 61 20  the format of a 
1b20: 74 61 62 6c 65 20 75 73 69 6e 67 20 61 20 73 69  table using a si
1b30: 6d 70 6c 65 0a 73 65 71 75 65 6e 63 65 20 6f 66  mple.sequence of
1b40: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 54 68 65   operations..The
1b50: 20 73 74 65 70 73 20 74 6f 20 6d 61 6b 65 20 61   steps to make a
1b60: 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1b70: 20 74 6f 20 74 68 65 20 73 63 68 65 6d 61 20 64   to the schema d
1b80: 65 73 69 67 6e 20 6f 66 20 73 6f 6d 65 20 74 61  esign of some ta
1b90: 62 6c 65 20 58 0a 61 72 65 20 61 73 20 66 6f 6c  ble X.are as fol
1ba0: 6c 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e  lows:..<ol>.<li>
1bb0: 3c 70 3e 0a 49 66 20 66 6f 72 65 69 67 6e 20 6b  <p>.If foreign k
1bc0: 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ey constraints a
1bd0: 72 65 20 65 6e 61 62 6c 65 64 2c 0a 64 69 73 61  re enabled,.disa
1be0: 62 6c 65 20 74 68 65 6d 20 75 73 69 6e 67 20 5b  ble them using [
1bf0: 50 52 41 47 4d 41 20 66 6f 72 65 69 67 6e 5f 6b  PRAGMA foreign_k
1c00: 65 79 73 20 7c 20 50 52 41 47 4d 41 20 66 6f 72  eys | PRAGMA for
1c10: 65 69 67 6e 5f 6b 65 79 73 3d 4f 46 46 5d 2e 0a  eign_keys=OFF]..
1c20: 0a 3c 6c 69 3e 3c 70 3e 0a 53 74 61 72 74 20 61  .<li><p>.Start a
1c30: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 0a 3c   transaction...<
1c40: 6c 69 3e 3c 70 3e 0a 52 65 6d 65 6d 62 65 72 20  li><p>.Remember 
1c50: 74 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 61 6c  the format of al
1c60: 6c 20 69 6e 64 65 78 65 73 20 61 6e 64 20 74 72  l indexes and tr
1c70: 69 67 67 65 72 73 20 61 73 73 6f 63 69 61 74 65  iggers associate
1c80: 64 20 77 69 74 68 20 74 61 62 6c 65 20 58 2e 0a  d with table X..
1c90: 54 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  This information
1ca0: 20 77 69 6c 6c 20 62 65 20 6e 65 65 64 65 64 20   will be needed 
1cb0: 69 6e 20 73 74 65 70 20 38 20 62 65 6c 6f 77 2e  in step 8 below.
1cc0: 20 20 4f 6e 65 20 77 61 79 20 74 6f 20 64 6f 20    One way to do 
1cd0: 74 68 69 73 20 69 73 0a 74 6f 20 72 75 6e 20 61  this is.to run a
1ce0: 20 71 75 65 72 79 20 6c 69 6b 65 20 74 68 65 20   query like the 
1cf0: 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 53 45 4c 45 43  following:.SELEC
1d00: 54 20 74 79 70 65 2c 20 73 71 6c 20 46 52 4f 4d  T type, sql FROM
1d10: 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 57   sqlite_master W
1d20: 48 45 52 45 20 74 62 6c 5f 6e 61 6d 65 3d 27 58  HERE tbl_name='X
1d30: 27 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20  '...<li><p>.Use 
1d40: 5b 43 52 45 41 54 45 20 54 41 42 4c 45 5d 20 74  [CREATE TABLE] t
1d50: 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
1d60: 77 20 74 61 62 6c 65 20 22 6e 65 77 5f 58 22 20  w table "new_X" 
1d70: 74 68 61 74 20 69 73 20 69 6e 20 74 68 65 20 64  that is in the d
1d80: 65 73 69 72 65 64 0a 72 65 76 69 73 65 64 20 66  esired.revised f
1d90: 6f 72 6d 61 74 20 6f 66 20 74 61 62 6c 65 20 58  ormat of table X
1da0: 2e 20 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61  .  Make sure tha
1db0: 74 20 74 68 65 20 6e 61 6d 65 20 22 6e 65 77 5f  t the name "new_
1dc0: 58 22 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6c 6c  X" does not coll
1dd0: 69 64 65 0a 77 69 74 68 20 61 6e 79 20 65 78 69  ide.with any exi
1de0: 73 74 69 6e 67 20 74 61 62 6c 65 20 6e 61 6d 65  sting table name
1df0: 2c 20 6f 66 20 63 6f 75 72 73 65 2e 0a 0a 3c 6c  , of course...<l
1e00: 69 3e 3c 70 3e 0a 54 72 61 6e 73 66 65 72 20 63  i><p>.Transfer c
1e10: 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 58 20 69 6e  ontent from X in
1e20: 74 6f 20 6e 65 77 5f 58 20 75 73 69 6e 67 20 61  to new_X using a
1e30: 20 73 74 61 74 65 6d 65 6e 74 0a 6c 69 6b 65 3a   statement.like:
1e40: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 6e 65 77   INSERT INTO new
1e50: 5f 58 20 53 45 4c 45 43 54 20 2e 2e 2e 20 46 52  _X SELECT ... FR
1e60: 4f 4d 20 58 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 44  OM X...<li><p>.D
1e70: 72 6f 70 20 74 68 65 20 6f 6c 64 20 74 61 62 6c  rop the old tabl
1e80: 65 20 58 3a 20 20 5b 44 52 4f 50 20 54 41 42 4c  e X:  [DROP TABL
1e90: 45 20 7c 20 44 52 4f 50 20 54 41 42 4c 45 20 58  E | DROP TABLE X
1ea0: 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 68 61 6e  ]...<li><p>.Chan
1eb0: 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 6e  ge the name of n
1ec0: 65 77 5f 58 20 74 6f 20 58 20 75 73 69 6e 67 3a  ew_X to X using:
1ed0: 20 41 4c 54 45 52 20 54 41 42 4c 45 20 6e 65 77   ALTER TABLE new
1ee0: 5f 58 20 52 45 4e 41 4d 45 20 54 4f 20 58 2e 0a  _X RENAME TO X..
1ef0: 0a 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20 5b 43 52  .<li><p>.Use [CR
1f00: 45 41 54 45 20 49 4e 44 45 58 5d 20 61 6e 64 20  EATE INDEX] and 
1f10: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 5d  [CREATE TRIGGER]
1f20: 20 74 6f 20 72 65 63 6f 6e 73 74 72 75 63 74 20   to reconstruct 
1f30: 69 6e 64 65 78 65 73 20 61 6e 64 20 74 72 69 67  indexes and trig
1f40: 67 65 72 73 0a 61 73 73 6f 63 69 61 74 65 64 20  gers.associated 
1f50: 77 69 74 68 20 74 61 62 6c 65 20 58 2e 20 20 50  with table X.  P
1f60: 65 72 68 61 70 73 20 75 73 65 20 74 68 65 20 6f  erhaps use the o
1f70: 6c 64 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65  ld format of the
1f80: 20 74 72 69 67 67 65 72 73 20 61 6e 64 0a 69 6e   triggers and.in
1f90: 64 65 78 65 73 20 73 61 76 65 64 20 66 72 6f 6d  dexes saved from
1fa0: 20 73 74 65 70 20 33 20 61 62 6f 76 65 20 61 73   step 3 above as
1fb0: 20 61 20 67 75 69 64 65 2c 20 6d 61 6b 69 6e 67   a guide, making
1fc0: 20 63 68 61 6e 67 65 73 20 61 73 20 61 70 70 72   changes as appr
1fd0: 6f 70 72 69 61 74 65 0a 66 6f 72 20 74 68 65 20  opriate.for the 
1fe0: 61 6c 74 65 72 61 74 69 6f 6e 2e 0a 0a 3c 6c 69  alteration...<li
1ff0: 3e 3c 70 3e 49 66 20 61 6e 79 20 76 69 65 77 73  ><p>If any views
2000: 20 72 65 66 65 72 20 74 6f 20 74 61 62 6c 65 20   refer to table 
2010: 58 20 69 6e 20 61 20 77 61 79 20 74 68 61 74 20  X in a way that 
2020: 69 73 20 61 66 66 65 63 74 65 64 20 62 79 20 74  is affected by t
2030: 68 65 0a 73 63 68 65 6d 61 20 63 68 61 6e 67 65  he.schema change
2040: 2c 20 74 68 65 6e 20 64 72 6f 70 20 74 68 6f 73  , then drop thos
2050: 65 20 76 69 65 77 73 20 75 73 69 6e 67 20 5b 44  e views using [D
2060: 52 4f 50 20 56 49 45 57 5d 20 61 6e 64 20 72 65  ROP VIEW] and re
2070: 63 72 65 61 74 65 20 74 68 65 6d 0a 77 69 74 68  create them.with
2080: 20 77 68 61 74 65 76 65 72 20 63 68 61 6e 67 65   whatever change
2090: 73 20 61 72 65 20 6e 65 63 65 73 73 61 72 79 20  s are necessary 
20a0: 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 74  to accommodate t
20b0: 68 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  he schema change
20c0: 0a 75 73 69 6e 67 20 5b 43 52 45 41 54 45 20 56  .using [CREATE V
20d0: 49 45 57 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49  IEW]...<li><p>.I
20e0: 66 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f  f foreign key co
20f0: 6e 73 74 72 61 69 6e 74 73 20 77 65 72 65 20 6f  nstraints were o
2100: 72 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c 65  riginally enable
2110: 64 0a 74 68 65 6e 20 72 75 6e 20 5b 50 52 41 47  d.then run [PRAG
2120: 4d 41 20 66 6f 72 65 69 67 6e 5f 6b 65 79 5f 63  MA foreign_key_c
2130: 68 65 63 6b 5d 20 74 6f 20 76 65 72 69 66 79 20  heck] to verify 
2140: 74 68 61 74 20 74 68 65 20 73 63 68 65 6d 61 0a  that the schema.
2150: 63 68 61 6e 67 65 20 64 69 64 20 6e 6f 74 20 62  change did not b
2160: 72 65 61 6b 20 61 6e 79 20 66 6f 72 65 69 67 6e  reak any foreign
2170: 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
2180: 2e 0a 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 6f 6d 6d  ....<li><p>.Comm
2190: 69 74 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  it the transacti
21a0: 6f 6e 20 73 74 61 72 74 65 64 20 69 6e 20 73 74  on started in st
21b0: 65 70 20 32 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49  ep 2...<li><p>.I
21c0: 66 20 66 6f 72 65 69 67 6e 20 6b 65 79 73 20 63  f foreign keys c
21d0: 6f 6e 73 74 72 61 69 6e 74 73 20 77 65 72 65 20  onstraints were 
21e0: 6f 72 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c  originally enabl
21f0: 65 64 2c 20 72 65 65 6e 61 62 6c 65 20 74 68 65  ed, reenable the
2200: 6d 20 6e 6f 77 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70  m now..</ol>..<p
2210: 3e 54 68 65 20 70 72 6f 63 65 64 75 72 65 20 61  >The procedure a
2220: 62 6f 76 65 20 69 73 20 63 6f 6d 70 6c 65 74 65  bove is complete
2230: 6c 79 20 67 65 6e 65 72 61 6c 20 61 6e 64 20 77  ly general and w
2240: 69 6c 6c 20 77 6f 72 6b 20 65 76 65 6e 20 69 66  ill work even if
2250: 20 74 68 65 0a 73 63 68 65 6d 61 20 63 68 61 6e   the.schema chan
2260: 67 65 20 63 61 75 73 65 73 20 74 68 65 20 69 6e  ge causes the in
2270: 66 6f 72 6d 61 74 69 6f 6e 20 73 74 6f 72 65 64  formation stored
2280: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 74 6f   in the table to
2290: 20 63 68 61 6e 67 65 2e 0a 53 6f 20 74 68 65 20   change..So the 
22a0: 66 75 6c 6c 20 70 72 6f 63 65 64 75 72 65 20 61  full procedure a
22b0: 62 6f 76 65 20 69 73 20 61 70 70 72 6f 70 72 69  bove is appropri
22c0: 61 74 65 20 66 6f 72 20 64 72 6f 70 70 69 6e 67  ate for dropping
22d0: 20 61 20 63 6f 6c 75 6d 6e 2c 0a 63 68 61 6e 67   a column,.chang
22e0: 69 6e 67 20 74 68 65 20 6f 72 64 65 72 20 6f 66  ing the order of
22f0: 20 63 6f 6c 75 6d 6e 73 2c 20 61 64 64 69 6e 67   columns, adding
2300: 20 6f 72 20 72 65 6d 6f 76 69 6e 67 20 61 20 55   or removing a U
2310: 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74  NIQUE constraint
2320: 0a 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  .or PRIMARY KEY,
2330: 20 61 64 64 69 6e 67 20 43 48 45 43 4b 20 6f 72   adding CHECK or
2340: 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72 20   FOREIGN KEY or 
2350: 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2360: 69 6e 74 73 2c 0a 6f 72 20 63 68 61 6e 67 69 6e  ints,.or changin
2370: 67 20 74 68 65 20 64 61 74 61 74 79 70 65 20 66  g the datatype f
2380: 6f 72 20 61 20 63 6f 6c 75 6d 6e 2c 20 66 6f 72  or a column, for
2390: 20 65 78 61 6d 70 6c 65 2e 20 20 48 6f 77 65 76   example.  Howev
23a0: 65 72 2c 20 61 20 73 69 6d 70 6c 65 72 0a 61 6e  er, a simpler.an
23b0: 64 20 66 61 73 74 65 72 20 70 72 6f 63 65 64 75  d faster procedu
23c0: 72 65 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  re can optionall
23d0: 79 20 62 65 20 75 73 65 64 20 66 6f 72 0a 73 6f  y be used for.so
23e0: 6d 65 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  me changes that 
23f0: 64 6f 20 6e 6f 20 61 66 66 65 63 74 20 74 68 65  do no affect the
2400: 20 6f 6e 2d 64 69 73 6b 20 63 6f 6e 74 65 6e 74   on-disk content
2410: 20 69 6e 20 61 6e 79 20 77 61 79 2e 0a 54 68 65   in any way..The
2420: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 69 6d 70 6c   following simpl
2430: 65 72 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  er procedure is 
2440: 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
2450: 72 65 6d 6f 76 69 6e 67 0a 43 48 45 43 4b 20 6f  removing.CHECK o
2460: 72 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72  r FOREIGN KEY or
2470: 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2480: 61 69 6e 74 73 2c 0a 72 65 6e 61 6d 69 6e 67 20  aints,.renaming 
2490: 63 6f 6c 75 6d 6e 73 2c 20 6f 72 20 61 64 64 69  columns, or addi
24a0: 6e 67 20 6f 72 20 72 65 6d 6f 76 69 6e 67 20 6f  ng or removing o
24b0: 72 20 63 68 61 6e 67 69 6e 67 20 64 65 66 61 75  r changing defau
24c0: 6c 74 20 76 61 6c 75 65 73 20 6f 6e 0a 61 20 63  lt values on.a c
24d0: 6f 6c 75 6d 6e 2e 0a 0a 3c 6f 6c 3e 0a 3c 6c 49  olumn...<ol>.<lI
24e0: 3e 3c 70 3e 20 53 74 61 72 74 20 61 20 74 72 61  ><p> Start a tra
24f0: 6e 73 61 63 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c  nsaction...<li><
2500: 70 3e 20 52 75 6e 20 5b 50 52 41 47 4d 41 20 73  p> Run [PRAGMA s
2510: 63 68 65 6d 61 5f 76 65 72 73 69 6f 6e 5d 20 74  chema_version] t
2520: 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2530: 63 75 72 72 65 6e 74 20 73 63 68 65 6d 61 0a 76  current schema.v
2540: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2e 20 20  ersion number.  
2550: 54 68 69 73 20 6e 75 6d 62 65 72 20 77 69 6c 6c  This number will
2560: 20 62 65 20 6e 65 65 64 65 64 20 66 6f 72 20 73   be needed for s
2570: 74 65 70 20 36 20 62 65 6c 6f 77 2e 0a 0a 3c 6c  tep 6 below...<l
2580: 69 3e 3c 70 3e 20 41 63 74 69 76 61 74 65 20 73  i><p> Activate s
2590: 63 68 65 6d 61 20 65 64 69 74 69 6e 67 20 75 73  chema editing us
25a0: 69 6e 67 20 0a 5b 50 52 41 47 4d 41 20 77 72 69  ing .[PRAGMA wri
25b0: 74 61 62 6c 65 5f 73 63 68 65 6d 61 20 7c 20 50  table_schema | P
25c0: 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73  RAGMA writable_s
25d0: 63 68 65 6d 61 3d 4f 4e 5d 2e 0a 0a 3c 6c 69 3e  chema=ON]...<li>
25e0: 3c 70 3e 20 52 75 6e 20 61 6e 20 5b 55 50 44 41  <p> Run an [UPDA
25f0: 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  TE] statement to
2600: 20 63 68 61 6e 67 65 20 74 68 65 20 64 65 66 69   change the defi
2610: 6e 69 74 69 6f 6e 20 6f 66 20 74 61 62 6c 65 20  nition of table 
2620: 58 0a 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  X.in the [sqlite
2630: 5f 6d 61 73 74 65 72 20 74 61 62 6c 65 5d 3a 20  _master table]: 
2640: 0a 55 50 44 41 54 45 20 73 71 6c 69 74 65 5f 6d  .UPDATE sqlite_m
2650: 61 73 74 65 72 20 53 45 54 20 73 71 6c 3d 2e 2e  aster SET sql=..
2660: 2e 20 57 48 45 52 45 20 74 79 70 65 3d 27 74 61  . WHERE type='ta
2670: 62 6c 65 27 20 41 4e 44 20 6e 61 6d 65 3d 27 58  ble' AND name='X
2680: 27 3b 0a 3c 70 3e 3c 65 6d 3e 43 61 75 74 69 6f  ';.<p><em>Cautio
2690: 6e 3a 3c 2f 65 6d 3e 20 20 4d 61 6b 69 6e 67 20  n:</em>  Making 
26a0: 61 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20  a change to the 
26b0: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 74 61  sqlite_master ta
26c0: 62 6c 65 20 6c 69 6b 65 20 74 68 69 73 20 77 69  ble like this wi
26d0: 6c 6c 0a 72 65 6e 64 65 72 20 74 68 65 20 64 61  ll.render the da
26e0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 20 61  tabase corrupt a
26f0: 6e 64 20 75 6e 72 65 61 64 61 62 6c 65 20 69 66  nd unreadable if
2700: 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 6e 74   the change cont
2710: 61 69 6e 73 0a 61 20 73 79 6e 74 61 78 20 65 72  ains.a syntax er
2720: 72 6f 72 2e 20 20 49 74 20 69 73 20 73 75 67 67  ror.  It is sugg
2730: 65 73 74 65 64 20 74 68 61 74 20 63 61 72 65 66  ested that caref
2740: 75 6c 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  ul testing of th
2750: 65 20 55 50 44 41 54 45 0a 73 74 61 74 65 6d 65  e UPDATE.stateme
2760: 6e 74 20 62 65 20 64 6f 6e 65 20 6f 6e 20 61 20  nt be done on a 
2770: 73 65 70 61 72 61 74 65 20 62 6c 61 6e 6b 20 64  separate blank d
2780: 61 74 61 62 61 73 65 20 70 72 69 6f 72 20 74 6f  atabase prior to
2790: 20 75 73 69 6e 67 20 69 74 20 6f 6e 0a 61 20 64   using it on.a d
27a0: 61 74 61 62 61 73 65 20 63 6f 6e 74 61 69 6e 69  atabase containi
27b0: 6e 67 20 69 6d 70 6f 72 74 61 6e 74 20 64 61 74  ng important dat
27c0: 61 2e 0a 0a 3c 6c 69 3e 3c 70 3e 20 49 66 20 74  a...<li><p> If t
27d0: 68 65 20 63 68 61 6e 67 65 20 74 6f 20 74 61 62  he change to tab
27e0: 6c 65 20 58 20 61 6c 73 6f 20 61 66 66 65 63 74  le X also affect
27f0: 73 20 6f 74 68 65 72 20 74 61 62 6c 65 73 20 6f  s other tables o
2800: 72 20 69 6e 64 65 78 65 73 20 6f 72 0a 74 72 69  r indexes or.tri
2810: 67 67 65 72 73 20 61 72 65 20 76 69 65 77 73 20  ggers are views 
2820: 77 69 74 68 69 6e 20 73 63 68 65 6d 61 2c 20 74  within schema, t
2830: 68 65 6e 20 72 75 6e 20 5b 55 50 44 41 54 45 5d  hen run [UPDATE]
2840: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 20 6d   statements to m
2850: 6f 64 69 66 79 0a 74 68 6f 73 65 20 6f 74 68 65  odify.those othe
2860: 72 20 74 61 62 6c 65 73 20 69 6e 64 65 78 65 73  r tables indexes
2870: 20 61 6e 64 20 76 69 65 77 73 20 74 6f 6f 2e 20   and views too. 
2880: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66   For example, if
2890: 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 61 20 63   the name of.a c
28a0: 6f 6c 75 6d 6e 20 63 68 61 6e 67 65 73 2c 20 61  olumn changes, a
28b0: 6c 6c 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 63  ll FOREIGN KEY c
28c0: 6f 6e 73 74 72 61 69 6e 74 73 2c 20 74 72 69 67  onstraints, trig
28d0: 67 65 72 73 2c 20 69 6e 64 65 78 65 73 2c 20 61  gers, indexes, a
28e0: 6e 64 0a 76 69 65 77 73 20 74 68 61 74 20 72 65  nd.views that re
28f0: 66 65 72 20 74 6f 20 74 68 61 74 20 63 6f 6c 75  fer to that colu
2900: 6d 6e 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66  mn must be modif
2910: 69 65 64 2e 0a 3c 70 3e 3c 65 6d 3e 43 61 75 74  ied..<p><em>Caut
2920: 69 6f 6e 3a 3c 2f 65 6d 3e 20 20 4f 6e 63 65 20  ion:</em>  Once 
2930: 61 67 61 69 6e 2c 20 6d 61 6b 69 6e 67 20 63 68  again, making ch
2940: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 73 71 6c  anges to the sql
2950: 69 74 65 5f 6d 61 73 74 65 72 20 0a 74 61 62 6c  ite_master .tabl
2960: 65 20 6c 69 6b 65 20 74 68 69 73 20 77 69 6c 6c  e like this will
2970: 20 72 65 6e 64 65 72 20 74 68 65 20 64 61 74 61   render the data
2980: 62 61 73 65 20 63 6f 72 72 75 70 74 20 61 6e 64  base corrupt and
2990: 20 75 6e 72 65 61 64 61 62 6c 65 20 69 66 20 74   unreadable if t
29a0: 68 65 20 0a 63 68 61 6e 67 65 20 63 6f 6e 74 61  he .change conta
29b0: 69 6e 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 43  ins an error.  C
29c0: 61 72 65 66 75 6c 6c 79 20 74 65 73 74 20 6f 66  arefully test of
29d0: 20 74 68 69 73 20 65 6e 74 69 72 65 20 70 72 6f   this entire pro
29e0: 63 65 64 75 72 65 0a 6f 6e 20 61 20 73 65 70 61  cedure.on a sepa
29f0: 72 61 74 65 20 74 65 73 74 20 64 61 74 61 62 61  rate test databa
2a00: 73 65 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  se prior to usin
2a10: 67 20 69 74 20 6f 6e 0a 61 20 64 61 74 61 62 61  g it on.a databa
2a20: 73 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6d  se containing im
2a30: 70 6f 72 74 61 6e 74 20 64 61 74 61 20 61 6e 64  portant data and
2a40: 2f 6f 72 20 6d 61 6b 65 20 62 61 63 6b 75 70 20  /or make backup 
2a50: 63 6f 70 69 65 73 20 6f 66 0a 69 6d 70 6f 72 74  copies of.import
2a60: 61 6e 74 20 64 61 74 61 62 61 73 65 73 20 70 72  ant databases pr
2a70: 69 6f 72 20 74 6f 20 72 75 6e 6e 69 6e 67 20 74  ior to running t
2a80: 68 69 73 20 70 72 6f 63 65 64 75 72 65 2e 0a 0a  his procedure...
2a90: 3c 6c 69 3e 3c 70 3e 20 49 6e 63 72 65 6d 65 6e  <li><p> Incremen
2aa0: 74 20 74 68 65 20 73 63 68 65 6d 61 20 76 65 72  t the schema ver
2ab0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 75 73 69 6e  sion number usin
2ac0: 67 0a 5b 50 52 41 47 4d 41 20 73 63 68 65 6d 61  g.[PRAGMA schema
2ad0: 5f 76 65 72 73 69 6f 6e 20 7c 20 50 52 41 47 4d  _version | PRAGM
2ae0: 41 20 73 63 68 65 6d 61 5f 76 65 72 73 69 6f 6e  A schema_version
2af0: 3d 58 5d 20 77 68 65 72 65 20 58 20 69 73 20 6f  =X] where X is o
2b00: 6e 65 0a 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne.more than the
2b10: 20 6f 6c 64 20 73 63 68 65 6d 61 20 76 65 72 73   old schema vers
2b20: 69 6f 6e 20 6e 75 6d 62 65 72 20 66 6f 75 6e 64  ion number found
2b30: 20 69 6e 20 73 74 65 70 20 32 20 61 62 6f 76 65   in step 2 above
2b40: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 20 44 69 73 61 62  ...<li><p> Disab
2b50: 6c 65 20 73 63 68 65 6d 61 20 65 64 69 74 69 6e  le schema editin
2b60: 67 20 75 73 69 6e 67 20 0a 5b 50 52 41 47 4d 41  g using .[PRAGMA
2b70: 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
2b80: 20 7c 20 50 52 41 47 4d 41 20 77 72 69 74 61 62   | PRAGMA writab
2b90: 6c 65 5f 73 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a  le_schema=OFF]..
2ba0: 0a 3c 6c 69 3e 3c 70 3e 20 28 4f 70 74 69 6f 6e  .<li><p> (Option
2bb0: 61 6c 29 20 52 75 6e 20 5b 50 52 41 47 4d 41 20  al) Run [PRAGMA 
2bc0: 69 6e 74 65 67 72 69 74 79 5f 63 68 65 63 6b 5d  integrity_check]
2bd0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
2be0: 74 68 65 0a 73 63 68 65 6d 61 20 63 68 61 6e 67  the.schema chang
2bf0: 65 73 20 64 69 64 20 6e 6f 74 20 64 61 6d 61 67  es did not damag
2c00: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
2c10: 0a 3c 6c 69 3e 3c 70 3e 20 43 6f 6d 6d 69 74 20  .<li><p> Commit 
2c20: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2c30: 73 74 61 72 74 65 64 20 6f 6e 20 73 74 65 70 20  started on step 
2c40: 31 20 61 62 6f 76 65 2e 0a 3c 2f 6f 6c 3e 0a 0a  1 above..</ol>..
2c50: 3c 70 3e 49 66 20 73 6f 6d 65 20 66 75 74 75 72  <p>If some futur
2c60: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  e version of SQL
2c70: 69 74 65 20 61 64 64 73 20 6e 65 77 20 41 4c 54  ite adds new ALT
2c80: 45 52 20 54 41 42 4c 45 20 63 61 70 61 62 69 6c  ER TABLE capabil
2c90: 69 74 69 65 73 2c 20 0a 74 68 6f 73 65 20 63 61  ities, .those ca
2ca0: 70 61 62 69 6c 69 74 69 65 73 20 77 69 6c 6c 20  pabilities will 
2cb0: 76 65 72 79 20 6c 69 6b 65 6c 79 20 75 73 65 20  very likely use 
2cc0: 6f 6e 65 20 6f 66 20 74 68 65 20 74 77 6f 20 70  one of the two p
2cd0: 72 6f 63 65 64 75 72 65 73 0a 6f 75 74 6c 69 6e  rocedures.outlin
2ce0: 65 64 20 61 62 6f 76 65 2e 0a 0a 3c 74 63 6c 3e  ed above...<tcl>
2cf0: 0a 23 20 20 4f 6e 65 20 6f 66 20 74 68 65 20 72  .#  One of the r
2d00: 65 61 73 6f 6e 73 20 74 68 61 74 0a 23 20 53 51  easons that.# SQ
2d10: 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63 75  Lite does not cu
2d20: 72 72 65 6e 74 6c 79 20 73 75 70 70 6f 72 74 20  rrently support 
2d30: 6d 6f 72 65 20 41 4c 54 45 52 20 54 41 42 4c 45  more ALTER TABLE
2d40: 20 63 61 70 61 62 69 6c 69 74 69 65 73 20 69 73   capabilities is
2d50: 20 74 68 61 74 0a 23 20 74 68 65 20 70 72 6f 63   that.# the proc
2d60: 65 64 75 72 65 20 73 68 6f 77 6e 20 61 62 6f 76  edure shown abov
2d70: 65 20 69 73 20 64 69 66 66 69 63 75 6c 74 20 74  e is difficult t
2d80: 6f 20 61 75 74 6f 6d 61 74 65 20 66 6f 72 20 61  o automate for a
2d90: 6e 20 61 72 62 69 74 72 61 72 79 20 73 63 68 65  n arbitrary sche
2da0: 6d 61 2e 0a 23 20 50 61 72 74 69 63 75 6c 61 72  ma..# Particular
2db0: 6c 79 20 74 72 6f 75 62 6c 65 73 6f 6d 65 20 61  ly troublesome a
2dc0: 72 65 61 73 20 61 72 65 20 69 64 65 6e 74 69 66  reas are identif
2dd0: 79 69 6e 67 20 61 6c 6c 20 76 69 65 77 73 20 61  ying all views a
2de0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 23  ssociated with.#
2df0: 20 74 61 62 6c 65 20 58 20 69 6e 20 73 74 65 70   table X in step
2e00: 20 31 20 61 6e 64 20 63 72 65 61 74 69 6e 67 20   1 and creating 
2e10: 6e 65 77 20 76 69 65 77 73 20 61 6e 64 20 74 72  new views and tr
2e20: 69 67 67 65 72 73 20 74 68 61 74 20 61 72 65 20  iggers that are 
2e30: 63 6f 6d 70 61 74 69 62 6c 65 0a 23 20 77 69 74  compatible.# wit
2e40: 68 20 74 68 65 20 61 6c 74 65 72 65 64 20 73 63  h the altered sc
2e50: 68 65 6d 61 20 66 6f 72 20 74 61 62 6c 65 20 58  hema for table X
2e60: 20 69 6e 20 73 74 65 70 20 36 2e 20 20 49 74 20   in step 6.  It 
2e70: 69 73 20 61 20 74 72 69 63 6b 79 20 62 75 74 20  is a tricky but 
2e80: 73 6f 6c 76 61 62 6c 65 0a 23 20 70 72 6f 62 6c  solvable.# probl
2e90: 65 6d 20 74 6f 20 63 72 65 61 74 65 20 63 6f 64  em to create cod
2ea0: 65 20 74 68 61 74 20 77 69 6c 6c 20 70 65 72 66  e that will perf
2eb0: 6f 72 6d 20 74 68 65 20 73 74 65 70 73 20 61 62  orm the steps ab
2ec0: 6f 76 65 20 0a 23 20 66 6f 72 20 22 72 65 61 73  ove .# for "reas
2ed0: 6f 6e 61 62 6c 65 22 20 73 63 68 65 6d 61 73 20  onable" schemas 
2ee0: 63 6f 6d 6d 6f 6e 6c 79 20 66 6f 75 6e 64 20 69  commonly found i
2ef0: 6e 20 70 72 61 63 74 69 63 65 2e 20 20 0a 23 20  n practice.  .# 
2f00: 42 75 74 20 74 68 65 72 65 20 65 78 69 73 74 20  But there exist 
2f10: 6d 61 6c 65 76 6f 6c 65 6e 74 20 73 63 68 65 6d  malevolent schem
2f20: 61 73 20 66 6f 72 20 77 68 69 63 68 0a 23 20 74  as for which.# t
2f30: 68 65 73 65 20 73 74 65 70 73 20 61 72 65 20 6d  hese steps are m
2f40: 61 64 64 65 6e 69 6e 67 6c 79 20 64 69 66 66 69  addeningly diffi
2f50: 63 75 6c 74 20 74 6f 20 64 6f 20 63 6f 72 72 65  cult to do corre
2f60: 63 74 6c 79 2e 20 20 52 61 74 68 65 72 20 74 68  ctly.  Rather th
2f70: 61 6e 20 63 72 65 61 74 65 0a 23 20 41 4c 54 45  an create.# ALTE
2f80: 52 20 54 41 42 4c 45 20 66 65 61 74 75 72 65 73  R TABLE features
2f90: 20 74 68 61 74 20 77 6f 72 6b 20 63 6f 72 72 65   that work corre
2fa0: 63 74 6c 79 20 39 39 2e 39 25 20 6f 66 20 74 68  ctly 99.9% of th
2fb0: 65 20 74 69 6d 65 20 62 75 74 20 70 6f 73 73 69  e time but possi
2fc0: 62 6c 79 0a 23 20 63 6f 72 72 75 70 74 20 74 68  bly.# corrupt th
2fd0: 65 20 73 63 68 65 6d 61 20 6f 6e 20 74 68 65 20  e schema on the 
2fe0: 6f 74 68 65 72 20 30 2e 31 25 2c 20 74 68 65 20  other 0.1%, the 
2ff0: 53 51 4c 69 74 65 20 64 65 76 65 6c 6f 70 65 72  SQLite developer
3000: 73 20 68 61 76 65 20 64 65 63 69 64 65 64 0a 23  s have decided.#
3010: 20 74 6f 20 70 75 73 68 20 74 68 65 20 70 72 6f   to push the pro
3020: 62 6c 65 6d 20 69 6e 74 6f 20 74 68 65 20 61 70  blem into the ap
3030: 70 6c 69 63 61 74 69 6f 6e 20 64 6f 6d 61 69 6e  plication domain
3040: 2c 20 77 68 65 72 65 20 69 74 20 69 73 20 6d 75  , where it is mu
3050: 63 68 20 65 61 73 69 65 72 0a 23 20 74 6f 20 73  ch easier.# to s
3060: 6f 6c 76 65 2e 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c  olve..</tcl>...<
3070: 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
3080: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
3090: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30c0: 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 41 4e 41  ###.Section {ANA
30d0: 4c 59 5a 45 7d 20 61 6e 61 6c 79 7a 65 20 41 4e  LYZE} analyze AN
30e0: 41 4c 59 5a 45 0a 0a 52 65 63 75 72 73 69 76 65  ALYZE..Recursive
30f0: 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 61 6e  BubbleDiagram an
3100: 61 6c 79 7a 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c  alyze-stmt.</tcl
3110: 3e 0a 0a 3c 70 3e 20 5e 54 68 65 20 41 4e 41 4c  >..<p> ^The ANAL
3120: 59 5a 45 20 63 6f 6d 6d 61 6e 64 20 67 61 74 68  YZE command gath
3130: 65 72 73 20 73 74 61 74 69 73 74 69 63 73 20 61  ers statistics a
3140: 62 6f 75 74 20 74 61 62 6c 65 73 20 61 6e 64 0a  bout tables and.
3150: 69 6e 64 69 63 65 73 20 61 6e 64 20 73 74 6f 72  indices and stor
3160: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 65 64  es the collected
3170: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 69 6e 20   information.in 
3180: 5b 69 6e 74 65 72 6e 61 6c 20 74 61 62 6c 65 73  [internal tables
3190: 5d 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  ] of the databas
31a0: 65 20 77 68 65 72 65 20 74 68 65 20 71 75 65 72  e where the quer
31b0: 79 20 6f 70 74 69 6d 69 7a 65 72 20 63 61 6e 0a  y optimizer can.
31c0: 61 63 63 65 73 73 20 74 68 65 20 69 6e 66 6f 72  access the infor
31d0: 6d 61 74 69 6f 6e 20 61 6e 64 20 75 73 65 20 69  mation and use i
31e0: 74 20 74 6f 20 68 65 6c 70 20 6d 61 6b 65 20 62  t to help make b
31f0: 65 74 74 65 72 20 71 75 65 72 79 20 70 6c 61 6e  etter query plan
3200: 6e 69 6e 67 20 63 68 6f 69 63 65 73 2e 0a 5e 49  ning choices..^I
3210: 66 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61  f no arguments a
3220: 72 65 20 67 69 76 65 6e 2c 20 61 6c 6c 20 61 74  re given, all at
3230: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
3240: 20 61 72 65 0a 61 6e 61 6c 79 7a 65 64 2e 20 20   are.analyzed.  
3250: 5e 49 66 20 61 20 73 63 68 65 6d 61 20 6e 61 6d  ^If a schema nam
3260: 65 20 69 73 20 67 69 76 65 6e 20 61 73 20 74 68  e is given as th
3270: 65 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65 6e  e argument, then
3280: 20 61 6c 6c 20 74 61 62 6c 65 73 0a 61 6e 64 20   all tables.and 
3290: 69 6e 64 69 63 65 73 20 69 6e 20 74 68 61 74 20  indices in that 
32a0: 6f 6e 65 20 64 61 74 61 62 61 73 65 20 61 72 65  one database are
32b0: 20 61 6e 61 6c 79 7a 65 64 2e 20 20 0a 5e 49 66   analyzed.  .^If
32c0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
32d0: 20 61 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 74   a table name, t
32e0: 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74 20 74 61  hen only that ta
32f0: 62 6c 65 20 61 6e 64 20 74 68 65 0a 69 6e 64 69  ble and the.indi
3300: 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ces associated w
3310: 69 74 68 20 74 68 61 74 20 74 61 62 6c 65 20 61  ith that table a
3320: 72 65 20 61 6e 61 6c 79 7a 65 64 2e 20 20 5e 49  re analyzed.  ^I
3330: 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 69  f the argument.i
3340: 73 20 61 6e 20 69 6e 64 65 78 20 6e 61 6d 65 2c  s an index name,
3350: 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74 20   then only that 
3360: 6f 6e 65 20 69 6e 64 65 78 20 69 73 20 61 6e 61  one index is ana
3370: 6c 79 7a 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20  lyzed.</p>..<p> 
3380: 5e 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70  ^The default imp
3390: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 74 6f 72  lementation stor
33a0: 65 73 20 61 6c 6c 20 73 74 61 74 69 73 74 69 63  es all statistic
33b0: 73 20 69 6e 20 61 20 73 69 6e 67 6c 65 0a 74 61  s in a single.ta
33c0: 62 6c 65 20 6e 61 6d 65 64 20 22 5b 73 71 6c 69  ble named "[sqli
33d0: 74 65 5f 73 74 61 74 31 5d 22 2e 20 20 5e 49 66  te_stat1]".  ^If
33e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
33f0: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 5b 53 51  led with the.[SQ
3400: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
3410: 33 5d 20 6f 70 74 69 6f 6e 20 61 6e 64 20 77 69  3] option and wi
3420: 74 68 6f 75 74 20 74 68 65 20 5b 53 51 4c 49 54  thout the [SQLIT
3430: 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 34 5d 0a  E_ENABLE_STAT4].
3440: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 61 64 64  option, then add
3450: 69 74 69 6f 6e 61 6c 20 68 69 73 74 6f 67 72 61  itional histogra
3460: 6d 20 64 61 74 61 20 69 73 0a 63 6f 6c 6c 65 63  m data is.collec
3470: 74 65 64 20 61 6e 64 20 73 74 6f 72 65 64 20 69  ted and stored i
3480: 6e 20 5b 73 71 6c 69 74 65 5f 73 74 61 74 33 5d  n [sqlite_stat3]
3490: 2e 0a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .. ^If SQLite is
34a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
34b0: 68 65 0a 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he.[SQLITE_ENABL
34c0: 45 5f 53 54 41 54 34 5d 20 6f 70 74 69 6f 6e 2c  E_STAT4] option,
34d0: 20 74 68 65 6e 20 61 64 64 69 74 69 6f 6e 61 6c   then additional
34e0: 20 68 69 73 74 6f 67 72 61 6d 20 64 61 74 61 20   histogram data 
34f0: 69 73 0a 63 6f 6c 6c 65 63 74 65 64 20 61 6e 64  is.collected and
3500: 20 73 74 6f 72 65 64 20 69 6e 20 5b 73 71 6c 69   stored in [sqli
3510: 74 65 5f 73 74 61 74 34 5d 2e 0a 4f 6c 64 65 72  te_stat4]..Older
3520: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3530: 69 74 65 20 77 6f 75 6c 64 20 6d 61 6b 65 20 75  ite would make u
3540: 73 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  se of the [sqlit
3550: 65 5f 73 74 61 74 32 5d 20 74 61 62 6c 65 0a 77  e_stat2] table.w
3560: 68 65 6e 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  hen compiled wit
3570: 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
3580: 5f 53 54 41 54 32 5d 20 62 75 74 20 61 6c 6c 20  _STAT2] but all 
3590: 72 65 63 65 6e 74 20 76 65 72 73 69 6f 6e 73 20  recent versions 
35a0: 6f 66 0a 53 51 4c 69 74 65 20 69 67 6e 6f 72 65  of.SQLite ignore
35b0: 20 74 68 65 20 73 71 6c 69 74 65 5f 73 74 61 74   the sqlite_stat
35c0: 32 20 74 61 62 6c 65 2e 0a 46 75 74 75 72 65 20  2 table..Future 
35d0: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 6d 61 79  enhancements may
35e0: 20 63 72 65 61 74 65 0a 61 64 64 69 74 69 6f 6e   create.addition
35f0: 61 6c 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61 62  al [internal tab
3600: 6c 65 73 5d 20 77 69 74 68 20 74 68 65 20 73 61  les] with the sa
3610: 6d 65 20 6e 61 6d 65 20 70 61 74 74 65 72 6e 20  me name pattern 
3620: 65 78 63 65 70 74 20 77 69 74 68 0a 66 69 6e 61  except with.fina
3630: 6c 20 64 69 67 69 74 20 6c 61 72 67 65 72 20 74  l digit larger t
3640: 68 61 6e 20 22 34 22 2e 0a 41 6c 6c 20 6f 66 20  han "4"..All of 
3650: 74 68 65 73 65 20 74 61 62 6c 65 73 20 61 72 65  these tables are
3660: 20 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 72 65   collectively re
3670: 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 73 74  ferred to as "st
3680: 61 74 69 73 74 69 63 73 20 74 61 62 6c 65 73 22  atistics tables"
3690: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 54 68 65  ..</p>..<p> ^The
36a0: 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36b0: 73 74 61 74 69 73 74 69 63 73 20 74 61 62 6c 65  statistics table
36c0: 73 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  s can be queried
36d0: 20 75 73 69 6e 67 20 5b 53 45 4c 45 43 54 5d 0a   using [SELECT].
36e0: 61 6e 64 20 63 61 6e 20 62 65 20 63 68 61 6e 67  and can be chang
36f0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 44 45  ed using the [DE
3700: 4c 45 54 45 5d 2c 20 5b 49 4e 53 45 52 54 5d 2c  LETE], [INSERT],
3710: 20 61 6e 64 20 5b 55 50 44 41 54 45 5d 20 63 6f   and [UPDATE] co
3720: 6d 6d 61 6e 64 73 2e 0a 5e 28 54 68 65 20 5b 44  mmands..^(The [D
3730: 52 4f 50 20 54 41 42 4c 45 5d 20 63 6f 6d 6d 61  ROP TABLE] comma
3740: 6e 64 20 77 6f 72 6b 73 20 6f 6e 20 73 74 61 74  nd works on stat
3750: 69 73 74 69 63 73 20 74 61 62 6c 65 73 0a 61 73  istics tables.as
3760: 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
3770: 6f 6e 20 33 2e 37 2e 39 2e 29 5e 20 28 5b 64 61  on 3.7.9.)^ ([da
3780: 74 65 6f 66 3a 33 2e 37 2e 39 5d 29 0a 5e 54 68  teof:3.7.9]).^Th
3790: 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45 5d 20  e [ALTER TABLE] 
37a0: 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 20 6e 6f 74  command does not
37b0: 20 77 6f 72 6b 20 6f 6e 20 73 74 61 74 69 73 74   work on statist
37c0: 69 63 73 20 74 61 62 6c 65 73 2e 0a 41 70 70 72  ics tables..Appr
37d0: 6f 70 72 69 61 74 65 20 63 61 72 65 20 73 68 6f  opriate care sho
37e0: 75 6c 64 20 62 65 20 75 73 65 64 20 77 68 65 6e  uld be used when
37f0: 20 63 68 61 6e 67 69 6e 67 20 74 68 65 20 63 6f   changing the co
3800: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 73 74 61  ntent of the sta
3810: 74 69 73 74 69 63 73 0a 74 61 62 6c 65 73 20 61  tistics.tables a
3820: 73 20 69 6e 76 61 6c 69 64 20 63 6f 6e 74 65 6e  s invalid conten
3830: 74 20 63 61 6e 20 63 61 75 73 65 20 53 51 4c 69  t can cause SQLi
3840: 74 65 20 74 6f 20 73 65 6c 65 63 74 20 69 6e 65  te to select ine
3850: 66 66 69 63 69 65 6e 74 0a 71 75 65 72 79 20 70  fficient.query p
3860: 6c 61 6e 73 2e 20 20 47 65 6e 65 72 61 6c 6c 79  lans.  Generally
3870: 20 73 70 65 61 6b 69 6e 67 2c 20 6f 6e 65 20 73   speaking, one s
3880: 68 6f 75 6c 64 20 6e 6f 74 20 6d 6f 64 69 66 79  hould not modify
3890: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 0a   the content of.
38a0: 74 68 65 20 73 74 61 74 69 73 74 69 63 73 20 74  the statistics t
38b0: 61 62 6c 65 73 20 62 79 20 61 6e 79 20 6d 65 63  ables by any mec
38c0: 68 61 6e 69 73 6d 20 6f 74 68 65 72 20 74 68 61  hanism other tha
38d0: 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 41  n invoking the.A
38e0: 4e 41 4c 59 5a 45 20 63 6f 6d 6d 61 6e 64 2e 20  NALYZE command. 
38f0: 20 0a 53 65 65 20 22 5b 4d 61 6e 75 61 6c 20 43   .See "[Manual C
3900: 6f 6e 74 72 6f 6c 20 4f 66 20 51 75 65 72 79 20  ontrol Of Query 
3910: 50 6c 61 6e 73 20 55 73 69 6e 67 20 53 51 4c 49  Plans Using SQLI
3920: 54 45 5f 53 54 41 54 20 54 61 62 6c 65 73 5d 22  TE_STAT Tables]"
3930: 20 66 6f 72 0a 66 75 72 74 68 65 72 20 69 6e 66   for.further inf
3940: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c  ormation.</p>..<
3950: 70 3e 20 5e 53 74 61 74 69 73 74 69 63 73 20 67  p> ^Statistics g
3960: 61 74 68 65 72 65 64 20 62 79 20 41 4e 41 4c 59  athered by ANALY
3970: 5a 45 20 61 72 65 20 6e 6f 74 20 61 75 74 6f 6d  ZE are not autom
3980: 61 74 69 63 61 6c 6c 79 20 75 70 64 61 74 65 64  atically updated
3990: 20 61 73 0a 74 68 65 20 63 6f 6e 74 65 6e 74 20   as.the content 
39a0: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
39b0: 63 68 61 6e 67 65 73 2e 20 20 49 66 20 74 68 65  changes.  If the
39c0: 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
39d0: 64 61 74 61 62 61 73 65 0a 63 68 61 6e 67 65 73  database.changes
39e0: 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79 2c 20   significantly, 
39f0: 6f 72 20 69 66 20 74 68 65 20 64 61 74 61 62 61  or if the databa
3a00: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
3a10: 73 2c 20 74 68 65 6e 20 6f 6e 65 20 73 68 6f 75  s, then one shou
3a20: 6c 64 0a 63 6f 6e 73 69 64 65 72 20 72 65 72 75  ld.consider reru
3a30: 6e 6e 69 6e 67 20 74 68 65 20 41 4e 41 4c 59 5a  nning the ANALYZ
3a40: 45 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 6f 72 64  E command in ord
3a50: 65 72 20 74 6f 20 75 70 64 61 74 65 20 74 68 65  er to update the
3a60: 20 73 74 61 74 69 73 74 69 63 73 2e 3c 2f 70 3e   statistics.</p>
3a70: 0a 0a 3c 70 3e 20 54 68 65 20 71 75 65 72 79 20  ..<p> The query 
3a80: 70 6c 61 6e 6e 65 72 20 6c 6f 61 64 73 20 74 68  planner loads th
3a90: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
3aa0: 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62 6c   statistics tabl
3ab0: 65 73 0a 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 77  es.into memory w
3ac0: 68 65 6e 20 74 68 65 20 73 63 68 65 6d 61 20 69  hen the schema i
3ad0: 73 20 72 65 61 64 2e 20 20 5e 48 65 6e 63 65 2c  s read.  ^Hence,
3ae0: 20 77 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61   when an applica
3af0: 74 69 6f 6e 0a 63 68 61 6e 67 65 73 20 74 68 65  tion.changes the
3b00: 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62 6c   statistics tabl
3b10: 65 73 20 64 69 72 65 63 74 6c 79 2c 20 53 51 4c  es directly, SQL
3b20: 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6d 6d  ite will not imm
3b30: 65 64 69 61 74 65 6c 79 0a 6e 6f 74 69 63 65 20  ediately.notice 
3b40: 74 68 65 20 63 68 61 6e 67 65 73 2e 20 5e 41 6e  the changes. ^An
3b50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 63 61 6e   application.can
3b60: 20 66 6f 72 63 65 20 74 68 65 20 71 75 65 72 79   force the query
3b70: 20 70 6c 61 6e 6e 65 72 20 74 6f 20 72 65 72 65   planner to rere
3b80: 61 64 20 74 68 65 20 73 74 61 74 69 73 74 69 63  ad the statistic
3b90: 73 20 74 61 62 6c 65 73 20 62 79 20 72 75 6e 6e  s tables by runn
3ba0: 69 6e 67 0a 3c 62 3e 41 4e 41 4c 59 5a 45 20 73  ing.<b>ANALYZE s
3bb0: 71 6c 69 74 65 5f 6d 61 73 74 65 72 3c 2f 62 3e  qlite_master</b>
3bc0: 2e 20 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  . </p>..<tcl>hd_
3bd0: 66 72 61 67 6d 65 6e 74 20 61 75 74 6f 61 6e 61  fragment autoana
3be0: 6c 79 7a 65 20 7b 61 75 74 6f 6d 61 74 69 63 61  lyze {automatica
3bf0: 6c 6c 79 20 72 75 6e 6e 69 6e 67 20 41 4e 41 4c  lly running ANAL
3c00: 59 5a 45 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 41  YZE}</tcl>.<h2>A
3c10: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 52 75 6e  utomatically Run
3c20: 6e 69 6e 67 20 41 4e 41 4c 59 5a 45 3c 2f 68 32  ning ANALYZE</h2
3c30: 3e 0a 0a 3c 70 3e 54 68 65 20 5b 50 52 41 47 4d  >..<p>The [PRAGM
3c40: 41 20 6f 70 74 69 6d 69 7a 65 5d 20 63 6f 6d 6d  A optimize] comm
3c50: 61 6e 64 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  and will automat
3c60: 69 63 61 6c 6c 79 20 72 75 6e 20 41 4e 41 4c 59  ically run ANALY
3c70: 5a 45 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  ZE on individual
3c80: 0a 74 61 62 6c 65 73 20 6f 6e 20 61 6e 20 61 73  .tables on an as
3c90: 2d 6e 65 65 64 65 64 20 62 61 73 69 73 2e 20 20  -needed basis.  
3ca0: 54 68 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  The recommended 
3cb0: 70 72 61 63 74 69 63 65 20 69 73 20 66 6f 72 20  practice is for 
3cc0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 74 6f 20  applications.to 
3cd0: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 50 52 41 47  invoke the [PRAG
3ce0: 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 73 74 61  MA optimize] sta
3cf0: 74 65 6d 65 6e 74 20 6a 75 73 74 20 62 65 66 6f  tement just befo
3d00: 72 65 20 63 6c 6f 73 69 6e 67 20 65 61 63 68 20  re closing each 
3d10: 64 61 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63 74  database.connect
3d20: 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 45 61 63  ion.</p>..<p>Eac
3d30: 68 20 53 51 4c 69 74 65 20 5b 64 61 74 61 62 61  h SQLite [databa
3d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 72  se connection] r
3d50: 65 63 6f 72 64 73 20 63 61 73 65 73 20 77 68 65  ecords cases whe
3d60: 6e 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  n the query plan
3d70: 6e 65 72 20 77 6f 75 6c 64 0a 62 65 6e 65 66 69  ner would.benefi
3d80: 74 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 61 63  t from having ac
3d90: 63 75 72 61 74 65 20 72 65 73 75 6c 74 73 20 6f  curate results o
3da0: 66 20 41 4e 41 4c 59 5a 45 20 61 74 20 68 61 6e  f ANALYZE at han
3db0: 64 2e 20 20 54 68 65 73 65 20 72 65 63 6f 72 64  d.  These record
3dc0: 73 0a 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65  s.are held in me
3dd0: 6d 6f 72 79 20 61 6e 64 20 61 63 63 75 6d 75 6c  mory and accumul
3de0: 61 74 65 20 6f 76 65 72 20 74 68 65 20 6c 69 66  ate over the lif
3df0: 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  e of a database 
3e00: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 54 68 65 20  connection..The 
3e10: 5b 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65  [PRAGMA optimize
3e20: 5d 20 63 6f 6d 6d 61 6e 64 20 6c 6f 6f 6b 73 20  ] command looks 
3e30: 61 74 20 74 68 6f 73 65 20 72 65 63 6f 72 64 73  at those records
3e40: 20 61 6e 64 20 72 75 6e 73 20 41 4e 41 4c 59 5a   and runs ANALYZ
3e50: 45 20 6f 6e 20 6f 6e 6c 79 0a 74 68 6f 73 65 20  E on only.those 
3e60: 74 61 62 6c 65 73 20 66 6f 72 20 77 68 69 63 68  tables for which
3e70: 20 6e 65 77 20 6f 72 20 75 70 64 61 74 65 64 20   new or updated 
3e80: 41 4e 41 4c 59 5a 45 20 64 61 74 61 20 73 65 65  ANALYZE data see
3e90: 6d 73 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  ms likely to be 
3ea0: 75 73 65 66 75 6c 2e 0a 49 6e 20 6d 6f 73 74 20  useful..In most 
3eb0: 63 61 73 65 73 20 5b 50 52 41 47 4d 41 20 6f 70  cases [PRAGMA op
3ec0: 74 69 6d 69 7a 65 5d 20 77 69 6c 6c 20 6e 6f 74  timize] will not
3ed0: 20 72 75 6e 20 41 4e 41 4c 59 5a 45 2c 20 62 75   run ANALYZE, bu
3ee0: 74 20 69 74 20 77 69 6c 6c 20 6f 63 63 61 73 69  t it will occasi
3ef0: 6f 6e 61 6c 6c 79 0a 64 6f 20 73 6f 20 65 69 74  onally.do so eit
3f00: 68 65 72 20 66 6f 72 20 74 61 62 6c 65 73 20 74  her for tables t
3f10: 68 61 74 20 68 61 76 65 20 6e 65 76 65 72 20 62  hat have never b
3f20: 65 66 6f 72 65 20 62 65 65 6e 20 61 6e 61 6c 79  efore been analy
3f30: 7a 65 64 2c 20 6f 72 20 66 6f 72 20 74 61 62 6c  zed, or for tabl
3f40: 65 73 0a 74 68 61 74 20 68 61 76 65 20 67 72 6f  es.that have gro
3f50: 77 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79  wn significantly
3f60: 20 73 69 6e 63 65 20 74 68 65 79 20 77 65 72 65   since they were
3f70: 20 6c 61 73 74 20 61 6e 61 6c 79 7a 65 64 2e 3c   last analyzed.<
3f80: 2f 70 3e 0a 0a 3c 70 3e 53 69 6e 63 65 20 74 68  /p>..<p>Since th
3f90: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 5b 50 52  e actions of [PR
3fa0: 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 61  AGMA optimize] a
3fb0: 72 65 20 64 65 74 65 72 6d 69 6e 65 64 20 74 6f  re determined to
3fc0: 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79 0a   some extent by.
3fd0: 70 72 69 6f 72 20 71 75 65 72 69 65 73 20 74 68  prior queries th
3fe0: 61 74 20 68 61 76 65 20 62 65 65 6e 20 65 76 61  at have been eva
3ff0: 6c 75 61 74 65 64 20 6f 6e 20 74 68 65 20 73 61  luated on the sa
4000: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
4010: 65 63 74 69 6f 6e 2c 20 69 74 0a 69 73 20 72 65  ection, it.is re
4020: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 5b  commended that [
4030: 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d  PRAGMA optimize]
4040: 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
4050: 69 6c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  il the database 
4060: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 69 73 20 63 6c  connection.is cl
4070: 6f 73 69 6e 67 20 61 6e 64 20 68 61 73 20 74 68  osing and has th
4080: 75 73 20 68 61 64 20 61 6e 20 6f 70 70 6f 72 74  us had an opport
4090: 75 6e 69 74 79 20 74 6f 20 61 63 63 75 6d 75 6c  unity to accumul
40a0: 61 74 65 20 61 73 20 6d 75 73 74 20 75 73 61 67  ate as must usag
40b0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61 73  e information.as
40c0: 20 70 6f 73 73 69 62 6c 65 2e 20 20 49 74 20 69   possible.  It i
40d0: 73 20 61 6c 73 6f 20 72 65 61 73 6f 6e 61 62 6c  s also reasonabl
40e0: 65 20 74 6f 20 73 65 74 20 61 20 74 69 6d 65 72  e to set a timer
40f0: 20 74 6f 20 72 75 6e 20 5b 50 52 41 47 4d 41 20   to run [PRAGMA 
4100: 6f 70 74 69 6d 69 7a 65 5d 0a 65 76 65 72 79 20  optimize].every 
4110: 66 65 77 20 68 6f 75 72 73 2c 20 6f 72 20 65 76  few hours, or ev
4120: 65 72 79 20 66 65 77 20 64 61 79 73 2c 20 66 6f  ery few days, fo
4130: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4140: 63 74 69 6f 6e 73 20 74 68 61 74 20 73 74 61 79  ctions that stay
4150: 20 6f 70 65 6e 0a 66 6f 72 20 61 20 6c 6f 6e 67   open.for a long
4160: 20 74 69 6d 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41   time.</p>..<p>A
4170: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
4180: 20 64 65 73 69 72 65 20 6d 6f 72 65 20 63 6f 6e   desire more con
4190: 74 72 6f 6c 20 63 61 6e 20 72 75 6e 20 5b 50 52  trol can run [PR
41a0: 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 28 30 78  AGMA optimize(0x
41b0: 30 33 29 5d 20 74 6f 20 0a 6f 62 74 61 69 6e 20  03)] to .obtain 
41c0: 61 20 6c 69 73 74 20 6f 66 20 41 4e 41 4c 59 5a  a list of ANALYZ
41d0: 45 20 63 6f 6d 6d 61 6e 64 73 20 74 68 61 74 20  E commands that 
41e0: 53 51 4c 69 74 65 20 74 68 69 6e 6b 73 20 61 72  SQLite thinks ar
41f0: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 6f  e appropriate to
4200: 20 72 75 6e 2c 0a 62 75 74 20 77 69 74 68 6f 75   run,.but withou
4210: 74 20 61 63 74 75 61 6c 6c 79 20 72 75 6e 6e 69  t actually runni
4220: 6e 67 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64  ng those command
4230: 73 2e 20 20 49 66 20 74 68 65 20 72 65 74 75 72  s.  If the retur
4240: 6e 65 64 20 73 65 74 20 69 73 20 0a 6e 6f 6e 2d  ned set is .non-
4250: 65 6d 70 74 79 2c 20 74 68 65 20 61 70 70 6c 69  empty, the appli
4260: 63 61 74 69 6f 6e 20 63 61 6e 20 74 68 65 6e 20  cation can then 
4270: 6d 61 6b 65 20 61 20 64 65 63 69 73 69 6f 6e 20  make a decision 
4280: 61 62 6f 75 74 20 77 68 65 74 68 65 72 20 6f 72  about whether or
4290: 20 6e 6f 74 0a 74 6f 20 72 75 6e 20 74 68 65 20   not.to run the 
42a0: 73 75 67 67 65 73 74 65 64 20 41 4e 41 4c 59 5a  suggested ANALYZ
42b0: 45 20 63 6f 6d 6d 61 6e 64 73 2c 20 70 65 72 68  E commands, perh
42c0: 61 70 73 20 61 66 74 65 72 20 70 72 6f 6d 70 74  aps after prompt
42d0: 69 6e 67 20 74 68 65 20 75 73 65 72 0a 66 6f 72  ing the user.for
42e0: 20 67 75 69 64 61 6e 63 65 2e 3c 2f 70 3e 0a 0a   guidance.</p>..
42f0: 3c 70 3e 54 68 65 20 5b 50 52 41 47 4d 41 20 6f  <p>The [PRAGMA o
4300: 70 74 69 6d 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ptimize] command
4310: 20 77 61 73 20 66 69 72 73 74 20 69 6e 74 72 6f   was first intro
4320: 64 75 63 65 64 20 77 69 74 68 20 0a 53 51 4c 69  duced with .SQLi
4330: 74 65 20 33 2e 31 38 2e 30 20 28 5b 64 61 74 65  te 3.18.0 ([date
4340: 6f 66 3a 33 2e 31 38 2e 30 5d 29 20 61 6e 64 20  of:3.18.0]) and 
4350: 69 73 20 61 20 6e 6f 2d 6f 70 20 66 6f 72 20 61  is a no-op for a
4360: 6c 6c 20 70 72 69 6f 72 20 72 65 6c 65 61 73 65  ll prior release
4370: 73 0a 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e  s.of SQLite.</p>
4380: 0a 0a 3c 68 32 3e 41 6e 74 69 63 69 70 61 74 65  ..<h2>Anticipate
4390: 64 20 46 75 74 75 72 65 20 45 6e 68 61 6e 63 65  d Future Enhance
43a0: 6d 65 6e 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 41  ments</h2>..<p>A
43b0: 6c 6c 20 65 78 69 73 74 69 6e 67 20 76 65 72 73  ll existing vers
43c0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 64  ions of SQLite d
43d0: 6f 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  o a full table s
43e0: 63 61 6e 20 66 6f 72 20 41 4e 41 4c 59 5a 45 2e  can for ANALYZE.
43f0: 20 20 54 68 69 73 20 63 61 6e 20 62 65 0a 73 6c    This can be.sl
4400: 6f 77 20 66 6f 72 20 6d 75 6c 74 69 2d 67 69 67  ow for multi-gig
4410: 61 62 79 74 65 20 61 6e 64 20 6c 61 72 67 65 72  abyte and larger
4420: 20 64 61 74 61 62 61 73 65 73 2e 20 20 46 75 74   databases.  Fut
4430: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
4440: 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 75 73 65  SQLite might.use
4450: 20 72 61 6e 64 6f 6d 20 73 61 6d 70 6c 69 6e 67   random sampling
4460: 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 20 66   rather than a f
4470: 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20 74  ull table scan t
4480: 6f 20 6f 62 74 61 69 6e 20 65 73 74 69 6d 61 74  o obtain estimat
4490: 65 73 20 66 6f 72 20 74 68 65 0a 64 61 74 61 62  es for the.datab
44a0: 61 73 65 20 73 68 61 70 65 2c 20 65 73 70 65 63  ase shape, espec
44b0: 69 61 6c 6c 79 20 6f 6e 20 6c 61 72 67 65 72 20  ially on larger 
44c0: 74 61 62 6c 65 73 2e 20 20 54 68 65 20 72 65 73  tables.  The res
44d0: 75 6c 74 73 20 77 6f 75 6c 64 20 61 70 70 72 6f  ults would appro
44e0: 78 69 6d 61 74 65 2c 20 62 75 74 20 0a 77 69 6c  ximate, but .wil
44f0: 6c 20 62 65 20 63 6c 6f 73 65 20 65 6e 6f 75 67  l be close enoug
4500: 68 20 66 6f 72 20 71 75 65 72 79 20 70 6c 61 6e  h for query plan
4510: 6e 69 6e 67 20 70 75 72 70 6f 73 65 73 2e 20 20  ning purposes.  
4520: 41 73 20 6f 66 20 32 30 31 37 2d 30 33 2d 32 30  As of 2017-03-20
4530: 2c 20 74 68 69 73 0a 63 6f 6e 63 65 70 74 20 68  , this.concept h
4540: 61 73 20 62 65 65 6e 20 74 65 73 74 65 64 20 69  as been tested i
4550: 6e 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 62  n experimental b
4560: 72 61 6e 63 68 65 73 20 61 6e 64 20 61 70 70 65  ranches and appe
4570: 61 72 73 20 74 6f 20 77 6f 72 6b 20 77 65 6c 6c  ars to work well
4580: 2c 20 62 75 74 0a 68 61 73 20 6e 6f 74 20 62 65  , but.has not be
4590: 65 6e 20 66 6f 6c 64 65 64 20 69 6e 74 6f 20 61  en folded into a
45a0: 6e 20 6f 66 66 69 63 69 61 6c 20 72 65 6c 65 61  n official relea
45b0: 73 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23  se.</p>..<tcl>.#
45c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
45d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
45e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
45f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4600: 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
4610: 63 74 69 6f 6e 20 7b 41 54 54 41 43 48 20 44 41  ction {ATTACH DA
4620: 54 41 42 41 53 45 7d 20 61 74 74 61 63 68 20 7b  TABASE} attach {
4630: 61 74 74 61 63 68 65 64 20 2a 41 54 54 41 43 48  attached *ATTACH
4640: 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
4650: 6c 65 44 69 61 67 72 61 6d 20 61 74 74 61 63 68  leDiagram attach
4660: 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70  -stmt.</tcl>..<p
4670: 3e 20 5e 54 68 65 20 41 54 54 41 43 48 20 44 41  > ^The ATTACH DA
4680: 54 41 42 41 53 45 20 73 74 61 74 65 6d 65 6e 74  TABASE statement
4690: 20 61 64 64 73 20 61 6e 6f 74 68 65 72 20 64 61   adds another da
46a0: 74 61 62 61 73 65 20 0a 66 69 6c 65 20 74 6f 20  tabase .file to 
46b0: 74 68 65 20 63 75 72 72 65 6e 74 20 5b 64 61 74  the current [dat
46c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
46d0: 5d 2e 20 0a 44 61 74 61 62 61 73 65 20 66 69 6c  ]. .Database fil
46e0: 65 73 20 74 68 61 74 20 77 65 72 65 20 70 72 65  es that were pre
46f0: 76 69 6f 75 73 6c 79 20 61 74 74 61 63 68 65 64  viously attached
4700: 20 63 61 6e 20 62 65 20 72 65 6d 6f 76 65 64 20   can be removed 
4710: 75 73 69 6e 67 0a 74 68 65 20 5b 44 45 54 41 43  using.the [DETAC
4720: 48 20 44 41 54 41 42 41 53 45 5d 20 63 6f 6d 6d  H DATABASE] comm
4730: 61 6e 64 2e 0a 0a 3c 70 3e 5e 54 68 65 20 66 69  and...<p>^The fi
4740: 6c 65 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 64  lename for the d
4750: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 61 74  atabase to be at
4760: 74 61 63 68 65 64 20 69 73 20 74 68 65 20 76 61  tached is the va
4770: 6c 75 65 20 6f 66 0a 74 68 65 20 65 78 70 72 65  lue of.the expre
4780: 73 73 69 6f 6e 20 74 68 61 74 20 6f 63 63 75 72  ssion that occur
4790: 73 20 62 65 66 6f 72 65 20 74 68 65 20 41 53 20  s before the AS 
47a0: 6b 65 79 77 6f 72 64 2e 0a 5e 54 68 65 20 66 69  keyword..^The fi
47b0: 6c 65 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  lename of the da
47c0: 74 61 62 61 73 65 20 66 6f 6c 6c 6f 77 73 20 74  tabase follows t
47d0: 68 65 20 73 61 6d 65 20 73 65 6d 61 6e 74 69 63  he same semantic
47e0: 73 20 61 73 20 74 68 65 0a 66 69 6c 65 6e 61 6d  s as the.filenam
47f0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
4800: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
4810: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
4820: 5f 76 32 28 29 5d 3b 20 74 68 65 0a 73 70 65 63  _v2()]; the.spec
4830: 69 61 6c 20 6e 61 6d 65 20 22 5b 3a 6d 65 6d 6f  ial name "[:memo
4840: 72 79 3a 5d 22 20 72 65 73 75 6c 74 73 20 69 6e  ry:]" results in
4850: 20 61 6e 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64   an [in-memory d
4860: 61 74 61 62 61 73 65 5d 20 61 6e 64 20 61 6e 0a  atabase] and an.
4870: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 72 65 73  empty string res
4880: 75 6c 74 73 20 69 6e 20 61 20 6e 65 77 20 74 65  ults in a new te
4890: 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65  mporary database
48a0: 2e 0a 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  ..^The filename 
48b0: 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20  argument can be 
48c0: 61 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  a [URI filename]
48d0: 20 69 66 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   if URI filename
48e0: 20 70 72 6f 63 65 73 73 69 6e 67 0a 69 73 20 65   processing.is e
48f0: 6e 61 62 6c 65 20 6f 6e 20 74 68 65 20 64 61 74  nable on the dat
4900: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4910: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  .  The default b
4920: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 0a 55  ehavior is for.U
4930: 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 74 6f 20  RI filenames to 
4940: 62 65 20 64 69 73 61 62 6c 65 64 2c 20 68 6f 77  be disabled, how
4950: 65 76 65 72 20 74 68 61 74 20 6d 69 67 68 74 20  ever that might 
4960: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
4970: 72 65 20 72 65 6c 65 61 73 65 0a 6f 66 20 53 51  re release.of SQ
4980: 4c 69 74 65 2c 20 73 6f 20 61 70 70 6c 69 63 61  Lite, so applica
4990: 74 69 6f 6e 20 64 65 76 65 6c 6f 70 65 72 73 20  tion developers 
49a0: 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 70  are advised to p
49b0: 6c 61 6e 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  lan accordingly.
49c0: 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 20 74 68  ..<p>The name th
49d0: 61 74 20 6f 63 63 75 72 73 20 61 66 74 65 72 20  at occurs after 
49e0: 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 69  the AS keyword i
49f0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
4a00: 65 20 64 61 74 61 62 61 73 65 0a 75 73 65 64 20  e database.used 
4a10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
4a20: 4c 69 74 65 2e 0a 5e 54 68 65 20 73 63 68 65 6d  Lite..^The schem
4a30: 61 2d 6e 61 6d 65 73 20 27 6d 61 69 6e 27 20 61  a-names 'main' a
4a40: 6e 64 20 0a 27 74 65 6d 70 27 20 72 65 66 65 72  nd .'temp' refer
4a50: 20 74 6f 20 74 68 65 20 6d 61 69 6e 20 64 61 74   to the main dat
4a60: 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64 61  abase and the da
4a70: 74 61 62 61 73 65 20 75 73 65 64 20 66 6f 72 20  tabase used for 
4a80: 0a 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65  .temporary table
4a90: 73 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 61 6e  s.  ^The main an
4aa0: 64 20 74 65 6d 70 20 64 61 74 61 62 61 73 65 73  d temp databases
4ab0: 20 63 61 6e 6e 6f 74 20 62 65 20 61 74 74 61 63   cannot be attac
4ac0: 68 65 64 20 6f 72 0a 64 65 74 61 63 68 65 64 2e  hed or.detached.
4ad0: 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28 54 61 62 6c  </p>..<p> ^(Tabl
4ae0: 65 73 20 69 6e 20 61 6e 20 61 74 74 61 63 68 65  es in an attache
4af0: 64 20 64 61 74 61 62 61 73 65 20 63 61 6e 20 62  d database can b
4b00: 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 75 73  e referred to us
4b10: 69 6e 67 20 74 68 65 20 73 79 6e 74 61 78 20 0a  ing the syntax .
4b20: 3c 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 2e 74  <i>schema-name.t
4b30: 61 62 6c 65 2d 6e 61 6d 65 3c 2f 69 3e 2e 29 5e  able-name</i>.)^
4b40: 20 20 5e 49 66 20 74 68 65 20 6e 61 6d 65 20 6f    ^If the name o
4b50: 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 75  f the table is u
4b60: 6e 69 71 75 65 0a 61 63 72 6f 73 73 20 61 6c 6c  nique.across all
4b70: 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
4b80: 73 65 73 20 61 6e 64 20 74 68 65 20 6d 61 69 6e  ses and the main
4b90: 20 61 6e 64 20 74 65 6d 70 20 64 61 74 61 62 61   and temp databa
4ba0: 73 65 73 2c 20 74 68 65 6e 20 74 68 65 0a 3c 69  ses, then the.<i
4bb0: 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69 3e  >schema-name</i>
4bc0: 20 70 72 65 66 69 78 20 69 73 20 6e 6f 74 20 72   prefix is not r
4bd0: 65 71 75 69 72 65 64 2e 20 20 5e 49 66 20 74 77  equired.  ^If tw
4be0: 6f 20 6f 72 20 6d 6f 72 65 20 74 61 62 6c 65 73  o or more tables
4bf0: 20 69 6e 0a 64 69 66 66 65 72 65 6e 74 20 64 61   in.different da
4c00: 74 61 62 61 73 65 73 20 68 61 76 65 20 74 68 65  tabases have the
4c10: 20 73 61 6d 65 20 6e 61 6d 65 20 61 6e 64 20 74   same name and t
4c20: 68 65 20 0a 3c 69 3e 73 63 68 65 6d 61 2d 6e 61  he .<i>schema-na
4c30: 6d 65 3c 2f 69 3e 20 70 72 65 66 69 78 20 69 73  me</i> prefix is
4c40: 20 6e 6f 74 20 75 73 65 64 20 6f 6e 20 61 20 74   not used on a t
4c50: 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 2c 20  able reference, 
4c60: 74 68 65 6e 20 74 68 65 0a 74 61 62 6c 65 20 63  then the.table c
4c70: 68 6f 73 65 6e 20 69 73 20 74 68 65 20 6f 6e 65  hosen is the one
4c80: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4c90: 20 74 68 61 74 20 77 61 73 20 6c 65 61 73 74 20   that was least 
4ca0: 72 65 63 65 6e 74 6c 79 20 61 74 74 61 63 68 65  recently attache
4cb0: 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 72 61  d.</p>..<p>.^Tra
4cc0: 6e 73 61 63 74 69 6f 6e 73 20 69 6e 76 6f 6c 76  nsactions involv
4cd0: 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 61 74 74  ing multiple att
4ce0: 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
4cf0: 61 72 65 20 61 74 6f 6d 69 63 2c 0a 61 73 73 75  are atomic,.assu
4d00: 6d 69 6e 67 20 74 68 61 74 20 74 68 65 20 6d 61  ming that the ma
4d10: 69 6e 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  in database is n
4d20: 6f 74 20 22 5b 3a 6d 65 6d 6f 72 79 3a 5d 22 20  ot "[:memory:]" 
4d30: 61 6e 64 20 74 68 65 20 0a 5b 6a 6f 75 72 6e 61  and the .[journa
4d40: 6c 5f 6d 6f 64 65 5d 20 69 73 20 6e 6f 74 20 5b  l_mode] is not [
4d50: 57 41 4c 5d 2e 20 20 5e 28 49 66 20 74 68 65 20  WAL].  ^(If the 
4d60: 6d 61 69 6e 0a 64 61 74 61 62 61 73 65 20 69 73  main.database is
4d70: 20 22 3a 6d 65 6d 6f 72 79 3a 22 20 6f 72 20 69   ":memory:" or i
4d80: 66 20 74 68 65 20 6a 6f 75 72 6e 61 6c 5f 6d 6f  f the journal_mo
4d90: 64 65 20 69 73 20 57 41 4c 2c 20 74 68 65 6e 20  de is WAL, then 
4da0: 0a 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f  .transactions co
4db0: 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 61 74 6f  ntinue to be ato
4dc0: 6d 69 63 20 77 69 74 68 69 6e 20 65 61 63 68 20  mic within each 
4dd0: 69 6e 64 69 76 69 64 75 61 6c 0a 64 61 74 61 62  individual.datab
4de0: 61 73 65 20 66 69 6c 65 2e 20 42 75 74 20 69 66  ase file. But if
4df0: 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
4e00: 65 72 20 63 72 61 73 68 65 73 20 69 6e 20 74 68  er crashes in th
4e10: 65 20 6d 69 64 64 6c 65 0a 6f 66 20 61 20 5b 43  e middle.of a [C
4e20: 4f 4d 4d 49 54 5d 20 77 68 65 72 65 20 74 77 6f  OMMIT] where two
4e30: 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73   or more databas
4e40: 65 20 66 69 6c 65 73 20 61 72 65 20 75 70 64 61  e files are upda
4e50: 74 65 64 2c 0a 73 6f 6d 65 20 6f 66 20 74 68 6f  ted,.some of tho
4e60: 73 65 20 66 69 6c 65 73 20 6d 69 67 68 74 20 67  se files might g
4e70: 65 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 77  et the changes w
4e80: 68 65 72 65 20 6f 74 68 65 72 73 0a 6d 69 67 68  here others.migh
4e90: 74 20 6e 6f 74 2e 29 5e 0a 3c 2f 70 3e 0a 0a 3c  t not.)^.</p>..<
4ea0: 70 3e 20 5e 54 68 65 72 65 20 69 73 20 61 20 6c  p> ^There is a l
4eb0: 69 6d 69 74 2c 20 73 65 74 20 75 73 69 6e 67 20  imit, set using 
4ec0: 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
4ed0: 5d 20 61 6e 64 20 0a 5b 53 51 4c 49 54 45 5f 4c  ] and .[SQLITE_L
4ee0: 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 2c 20  IMIT_ATTACHED], 
4ef0: 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
4f00: 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
4f10: 63 61 6e 20 62 65 0a 73 69 6d 75 6c 74 61 6e 65  can be.simultane
4f20: 6f 75 73 6c 79 20 61 74 74 61 63 68 65 64 20 74  ously attached t
4f30: 6f 20 61 20 73 69 6e 67 6c 65 20 64 61 74 61 62  o a single datab
4f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c  ase connection.<
4f50: 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  /p>..<tcl>.#####
4f60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4f70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4f80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4f90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4fa0: 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
4fb0: 6f 6e 20 7b 42 45 47 49 4e 20 54 52 41 4e 53 41  on {BEGIN TRANSA
4fc0: 43 54 49 4f 4e 7d 20 74 72 61 6e 73 61 63 74 69  CTION} transacti
4fd0: 6f 6e 20 7b 2a 42 45 47 49 4e 20 43 4f 4d 4d 49  on {*BEGIN COMMI
4fe0: 54 20 52 4f 4c 4c 42 41 43 4b 7d 0a 0a 52 65 63  T ROLLBACK}..Rec
4ff0: 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
5000: 72 61 6d 20 62 65 67 69 6e 2d 73 74 6d 74 0a 52  ram begin-stmt.R
5010: 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
5020: 61 67 72 61 6d 20 63 6f 6d 6d 69 74 2d 73 74 6d  agram commit-stm
5030: 74 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  t.RecursiveBubbl
5040: 65 44 69 61 67 72 61 6d 20 72 6f 6c 6c 62 61 63  eDiagram rollbac
5050: 6b 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  k-stmt.</tcl>..<
5060: 70 3e 0a 5e 4e 6f 20 63 68 61 6e 67 65 73 20 63  p>.^No changes c
5070: 61 6e 20 62 65 20 6d 61 64 65 20 74 6f 20 74 68  an be made to th
5080: 65 20 64 61 74 61 62 61 73 65 20 65 78 63 65 70  e database excep
5090: 74 20 77 69 74 68 69 6e 20 61 20 74 72 61 6e 73  t within a trans
50a0: 61 63 74 69 6f 6e 2e 0a 5e 41 6e 79 20 63 6f 6d  action..^Any com
50b0: 6d 61 6e 64 20 74 68 61 74 20 63 68 61 6e 67 65  mand that change
50c0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  s the database (
50d0: 62 61 73 69 63 61 6c 6c 79 2c 20 61 6e 79 20 53  basically, any S
50e0: 51 4c 20 63 6f 6d 6d 61 6e 64 0a 6f 74 68 65 72  QL command.other
50f0: 20 74 68 61 6e 20 5b 53 45 4c 45 43 54 5d 29 20   than [SELECT]) 
5100: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
5110: 6c 79 20 73 74 61 72 74 20 61 20 74 72 61 6e 73  ly start a trans
5120: 61 63 74 69 6f 6e 20 69 66 0a 6f 6e 65 20 69 73  action if.one is
5130: 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20   not already in 
5140: 65 66 66 65 63 74 2e 20 20 5e 41 75 74 6f 6d 61  effect.  ^Automa
5150: 74 69 63 61 6c 6c 79 20 73 74 61 72 74 65 64 20  tically started 
5160: 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 61 72 65  transactions.are
5170: 20 63 6f 6d 6d 69 74 74 65 64 20 77 68 65 6e 20   committed when 
5180: 74 68 65 20 6c 61 73 74 20 71 75 65 72 79 20 66  the last query f
5190: 69 6e 69 73 68 65 73 2e 0a 3c 2f 70 3e 0a 0a 3c  inishes..</p>..<
51a0: 70 3e 0a 5e 54 72 61 6e 73 61 63 74 69 6f 6e 73  p>.^Transactions
51b0: 20 63 61 6e 20 62 65 20 73 74 61 72 74 65 64 20   can be started 
51c0: 6d 61 6e 75 61 6c 6c 79 20 75 73 69 6e 67 20 74  manually using t
51d0: 68 65 20 42 45 47 49 4e 0a 63 6f 6d 6d 61 6e 64  he BEGIN.command
51e0: 2e 20 20 5e 28 53 75 63 68 20 74 72 61 6e 73 61  .  ^(Such transa
51f0: 63 74 69 6f 6e 73 20 75 73 75 61 6c 6c 79 20 70  ctions usually p
5200: 65 72 73 69 73 74 20 75 6e 74 69 6c 20 74 68 65  ersist until the
5210: 20 6e 65 78 74 0a 43 4f 4d 4d 49 54 20 6f 72 20   next.COMMIT or 
5220: 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64  ROLLBACK command
5230: 2e 20 20 42 75 74 20 61 20 74 72 61 6e 73 61 63  .  But a transac
5240: 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 0a  tion will also .
5250: 52 4f 4c 4c 42 41 43 4b 20 69 66 20 74 68 65 20  ROLLBACK if the 
5260: 64 61 74 61 62 61 73 65 20 69 73 20 63 6c 6f 73  database is clos
5270: 65 64 20 6f 72 20 69 66 20 61 6e 20 65 72 72 6f  ed or if an erro
5280: 72 20 6f 63 63 75 72 73 0a 61 6e 64 20 74 68 65  r occurs.and the
5290: 20 52 4f 4c 4c 42 41 43 4b 20 63 6f 6e 66 6c 69   ROLLBACK confli
52a0: 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c  ct resolution al
52b0: 67 6f 72 69 74 68 6d 20 69 73 20 73 70 65 63 69  gorithm is speci
52c0: 66 69 65 64 2e 29 5e 0a 53 65 65 20 74 68 65 20  fied.)^.See the 
52d0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
52e0: 20 74 68 65 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43   the [ON CONFLIC
52f0: 54 5d 0a 63 6c 61 75 73 65 20 66 6f 72 20 61 64  T].clause for ad
5300: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
5310: 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 52  tion about the R
5320: 4f 4c 4c 42 41 43 4b 0a 63 6f 6e 66 6c 69 63 74  OLLBACK.conflict
5330: 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f   resolution algo
5340: 72 69 74 68 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  rithm..</p>..<p>
5350: 0a 5e 45 4e 44 20 54 52 41 4e 53 41 43 54 49 4f  .^END TRANSACTIO
5360: 4e 20 69 73 20 61 6e 20 61 6c 69 61 73 20 66 6f  N is an alias fo
5370: 72 20 43 4f 4d 4d 49 54 2e 0a 3c 2f 70 3e 0a 0a  r COMMIT..</p>..
5380: 3c 70 3e 20 5e 28 54 72 61 6e 73 61 63 74 69 6f  <p> ^(Transactio
5390: 6e 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ns created using
53a0: 20 42 45 47 49 4e 2e 2e 2e 43 4f 4d 4d 49 54 20   BEGIN...COMMIT 
53b0: 64 6f 20 6e 6f 74 20 6e 65 73 74 2e 29 5e 0a 5e  do not nest.)^.^
53c0: 46 6f 72 20 6e 65 73 74 65 64 20 74 72 61 6e 73  For nested trans
53d0: 61 63 74 69 6f 6e 73 2c 20 75 73 65 20 74 68 65  actions, use the
53e0: 20 5b 53 41 56 45 50 4f 49 4e 54 5d 20 61 6e 64   [SAVEPOINT] and
53f0: 20 5b 52 45 4c 45 41 53 45 5d 20 63 6f 6d 6d 61   [RELEASE] comma
5400: 6e 64 73 2e 0a 54 68 65 20 22 54 4f 20 53 41 56  nds..The "TO SAV
5410: 45 50 4f 49 4e 54 20 3c 79 79 74 65 72 6d 3e 6e  EPOINT <yyterm>n
5420: 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 22 20 63 6c  ame</yyterm>" cl
5430: 61 75 73 65 20 6f 66 20 74 68 65 20 52 4f 4c 4c  ause of the ROLL
5440: 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 73 68 6f  BACK command sho
5450: 77 6e 0a 69 6e 20 74 68 65 20 73 79 6e 74 61 78  wn.in the syntax
5460: 20 64 69 61 67 72 61 6d 20 61 62 6f 76 65 20 69   diagram above i
5470: 73 20 6f 6e 6c 79 20 61 70 70 6c 69 63 61 62 6c  s only applicabl
5480: 65 20 74 6f 20 5b 53 41 56 45 50 4f 49 4e 54 5d  e to [SAVEPOINT]
5490: 0a 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20  .transactions.  
54a0: 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 69  ^An attempt to i
54b0: 6e 76 6f 6b 65 20 74 68 65 20 42 45 47 49 4e 20  nvoke the BEGIN 
54c0: 63 6f 6d 6d 61 6e 64 20 77 69 74 68 69 6e 0a 61  command within.a
54d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c   transaction wil
54e0: 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
54f0: 72 72 6f 72 2c 20 72 65 67 61 72 64 6c 65 73 73  rror, regardless
5500: 20 6f 66 20 77 68 65 74 68 65 72 0a 74 68 65 20   of whether.the 
5510: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 61 73 20  transaction was 
5520: 73 74 61 72 74 65 64 20 62 79 20 5b 53 41 56 45  started by [SAVE
5530: 50 4f 49 4e 54 5d 20 6f 72 20 61 20 70 72 69 6f  POINT] or a prio
5540: 72 20 42 45 47 49 4e 2e 0a 5e 54 68 65 20 43 4f  r BEGIN..^The CO
5550: 4d 4d 49 54 20 63 6f 6d 6d 61 6e 64 20 61 6e 64  MMIT command and
5560: 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63 6f   the ROLLBACK co
5570: 6d 6d 61 6e 64 20 77 69 74 68 6f 75 74 20 74 68  mmand without th
5580: 65 20 54 4f 20 63 6c 61 75 73 65 0a 77 6f 72 6b  e TO clause.work
5590: 20 74 68 65 20 73 61 6d 65 20 6f 6e 20 5b 53 41   the same on [SA
55a0: 56 45 50 4f 49 4e 54 5d 20 74 72 61 6e 73 61 63  VEPOINT] transac
55b0: 74 69 6f 6e 73 20 61 73 20 74 68 65 79 20 64 6f  tions as they do
55c0: 20 77 69 74 68 20 74 72 61 6e 73 61 63 74 69 6f   with transactio
55d0: 6e 73 0a 73 74 61 72 74 65 64 20 62 79 20 42 45  ns.started by BE
55e0: 47 49 4e 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  GIN.</p>..<tcl>h
55f0: 64 5f 66 72 61 67 6d 65 6e 74 20 69 6d 6d 65 64  d_fragment immed
5600: 69 61 74 65 20 7b 42 45 47 49 4e 20 49 4d 4d 45  iate {BEGIN IMME
5610: 44 49 41 54 45 7d 20 7b 42 45 47 49 4e 20 45 58  DIATE} {BEGIN EX
5620: 43 4c 55 53 49 56 45 7d 3c 2f 74 63 6c 3e 0a 3c  CLUSIVE}</tcl>.<
5630: 70 3e 0a 5e 54 72 61 6e 73 61 63 74 69 6f 6e 73  p>.^Transactions
5640: 20 63 61 6e 20 62 65 20 64 65 66 65 72 72 65 64   can be deferred
5650: 2c 20 69 6d 6d 65 64 69 61 74 65 2c 20 6f 72 20  , immediate, or 
5660: 65 78 63 6c 75 73 69 76 65 2e 20 20 0a 5e 54 68  exclusive.  .^Th
5670: 65 20 64 65 66 61 75 6c 74 20 74 72 61 6e 73 61  e default transa
5680: 63 74 69 6f 6e 20 62 65 68 61 76 69 6f 72 20 69  ction behavior i
5690: 73 20 64 65 66 65 72 72 65 64 2e 0a 5e 44 65 66  s deferred..^Def
56a0: 65 72 72 65 64 20 6d 65 61 6e 73 20 74 68 61 74  erred means that
56b0: 20 6e 6f 20 6c 6f 63 6b 73 20 61 72 65 20 61 63   no locks are ac
56c0: 71 75 69 72 65 64 0a 6f 6e 20 74 68 65 20 64 61  quired.on the da
56d0: 74 61 62 61 73 65 20 75 6e 74 69 6c 20 74 68 65  tabase until the
56e0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 69 72   database is fir
56f0: 73 74 20 61 63 63 65 73 73 65 64 2e 20 20 5e 54  st accessed.  ^T
5700: 68 75 73 20 77 69 74 68 20 61 0a 64 65 66 65 72  hus with a.defer
5710: 72 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  red transaction,
5720: 20 74 68 65 20 42 45 47 49 4e 20 73 74 61 74 65   the BEGIN state
5730: 6d 65 6e 74 20 69 74 73 65 6c 66 20 64 6f 65 73  ment itself does
5740: 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 0a   nothing to the.
5750: 66 69 6c 65 73 79 73 74 65 6d 2e 20 20 5e 4c 6f  filesystem.  ^Lo
5760: 63 6b 73 0a 61 72 65 20 6e 6f 74 20 61 63 71 75  cks.are not acqu
5770: 69 72 65 64 20 75 6e 74 69 6c 20 74 68 65 20 66  ired until the f
5780: 69 72 73 74 20 72 65 61 64 20 6f 72 20 77 72 69  irst read or wri
5790: 74 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 5e  te operation.  ^
57a0: 54 68 65 20 66 69 72 73 74 20 72 65 61 64 0a 6f  The first read.o
57b0: 70 65 72 61 74 69 6f 6e 20 61 67 61 69 6e 73 74  peration against
57c0: 20 61 20 64 61 74 61 62 61 73 65 20 63 72 65 61   a database crea
57d0: 74 65 73 20 61 20 5b 53 48 41 52 45 44 5d 20 6c  tes a [SHARED] l
57e0: 6f 63 6b 20 61 6e 64 20 74 68 65 20 66 69 72 73  ock and the firs
57f0: 74 0a 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t.write operatio
5800: 6e 20 63 72 65 61 74 65 73 20 61 20 5b 52 45 53  n creates a [RES
5810: 45 52 56 45 44 5d 20 6c 6f 63 6b 2e 20 20 20 5e  ERVED] lock.   ^
5820: 42 65 63 61 75 73 65 20 74 68 65 20 61 63 71 75  Because the acqu
5830: 69 73 69 74 69 6f 6e 20 6f 66 0a 6c 6f 63 6b 73  isition of.locks
5840: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
5850: 69 6c 20 74 68 65 79 20 61 72 65 20 6e 65 65 64  il they are need
5860: 65 64 2c 20 69 74 20 69 73 20 70 6f 73 73 69 62  ed, it is possib
5870: 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 0a  le that another.
5880: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
5890: 73 20 63 6f 75 6c 64 20 63 72 65 61 74 65 20 61  s could create a
58a0: 20 73 65 70 61 72 61 74 65 20 74 72 61 6e 73 61   separate transa
58b0: 63 74 69 6f 6e 20 61 6e 64 20 77 72 69 74 65 20  ction and write 
58c0: 74 6f 0a 74 68 65 20 64 61 74 61 62 61 73 65 20  to.the database 
58d0: 61 66 74 65 72 20 74 68 65 20 42 45 47 49 4e 20  after the BEGIN 
58e0: 6f 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  on the current t
58f0: 68 72 65 61 64 20 68 61 73 20 65 78 65 63 75 74  hread has execut
5900: 65 64 2e 0a 5e 49 66 20 74 68 65 20 74 72 61 6e  ed..^If the tran
5910: 73 61 63 74 69 6f 6e 20 69 73 20 69 6d 6d 65 64  saction is immed
5920: 69 61 74 65 2c 20 74 68 65 6e 20 5b 52 45 53 45  iate, then [RESE
5930: 52 56 45 44 5d 20 6c 6f 63 6b 73 0a 61 72 65 20  RVED] locks.are 
5940: 61 63 71 75 69 72 65 64 20 6f 6e 20 61 6c 6c 20  acquired on all 
5950: 64 61 74 61 62 61 73 65 73 20 61 73 20 73 6f 6f  databases as soo
5960: 6e 20 61 73 20 74 68 65 20 42 45 47 49 4e 20 63  n as the BEGIN c
5970: 6f 6d 6d 61 6e 64 20 69 73 0a 65 78 65 63 75 74  ommand is.execut
5980: 65 64 2c 20 77 69 74 68 6f 75 74 20 77 61 69 74  ed, without wait
5990: 69 6e 67 20 66 6f 72 20 74 68 65 0a 64 61 74 61  ing for the.data
59a0: 62 61 73 65 20 74 6f 20 62 65 20 75 73 65 64 2e  base to be used.
59b0: 20 20 5e 41 66 74 65 72 20 61 20 42 45 47 49 4e    ^After a BEGIN
59c0: 20 49 4d 4d 45 44 49 41 54 45 2c 20 0a 6e 6f 20   IMMEDIATE, .no 
59d0: 6f 74 68 65 72 20 5b 64 61 74 61 62 61 73 65 20  other [database 
59e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 6c 6c  connection] will
59f0: 20 62 65 20 61 62 6c 65 20 74 6f 20 77 72 69 74   be able to writ
5a00: 65 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  e to the databas
5a10: 65 20 6f 72 0a 64 6f 20 61 20 42 45 47 49 4e 20  e or.do a BEGIN 
5a20: 49 4d 4d 45 44 49 41 54 45 20 6f 72 20 42 45 47  IMMEDIATE or BEG
5a30: 49 4e 20 45 58 43 4c 55 53 49 56 45 2e 20 20 5e  IN EXCLUSIVE.  ^
5a40: 4f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  Other processes 
5a50: 63 61 6e 20 63 6f 6e 74 69 6e 75 65 0a 74 6f 20  can continue.to 
5a60: 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 64 61  read from the da
5a70: 74 61 62 61 73 65 2c 20 68 6f 77 65 76 65 72 2e  tabase, however.
5a80: 20 20 5e 41 6e 20 65 78 63 6c 75 73 69 76 65 20    ^An exclusive 
5a90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 61 75 73  transaction caus
5aa0: 65 73 0a 5b 45 58 43 4c 55 53 49 56 45 5d 20 6c  es.[EXCLUSIVE] l
5ab0: 6f 63 6b 73 20 74 6f 20 62 65 20 61 63 71 75 69  ocks to be acqui
5ac0: 72 65 64 20 6f 6e 20 61 6c 6c 20 64 61 74 61 62  red on all datab
5ad0: 61 73 65 73 2e 20 20 5e 41 66 74 65 72 20 61 20  ases.  ^After a 
5ae0: 42 45 47 49 4e 0a 45 58 43 4c 55 53 49 56 45 2c  BEGIN.EXCLUSIVE,
5af0: 20 6e 6f 20 6f 74 68 65 72 20 5b 64 61 74 61 62   no other [datab
5b00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
5b10: 65 78 63 65 70 74 20 66 6f 72 20 5b 72 65 61 64  except for [read
5b20: 5f 75 6e 63 6f 6d 6d 69 74 74 65 64 5d 0a 63 6f  _uncommitted].co
5b30: 6e 6e 65 63 74 69 6f 6e 73 20 77 69 6c 6c 20 62  nnections will b
5b40: 65 20 61 62 6c 65 20 74 6f 20 72 65 61 64 20 74  e able to read t
5b50: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
5b60: 6e 6f 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74  no other connect
5b70: 69 6f 6e 20 77 69 74 68 6f 75 74 0a 65 78 63 65  ion without.exce
5b80: 70 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 61 62  ption will be ab
5b90: 6c 65 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  le to write the 
5ba0: 64 61 74 61 62 61 73 65 20 75 6e 74 69 6c 20 74  database until t
5bb0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
5bc0: 73 0a 63 6f 6d 70 6c 65 74 65 2e 0a 3c 2f 70 3e  s.complete..</p>
5bd0: 0a 0a 3c 70 3e 0a 5e 28 41 6e 20 69 6d 70 6c 69  ..<p>.^(An impli
5be0: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
5bf0: 28 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  (a transaction t
5c00: 68 61 74 20 69 73 20 73 74 61 72 74 65 64 20 61  hat is started a
5c10: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2c 0a 6e 6f  utomatically,.no
5c20: 74 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  t a transaction 
5c30: 73 74 61 72 74 65 64 20 62 79 20 42 45 47 49 4e  started by BEGIN
5c40: 29 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 61  ) is committed a
5c50: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 77 68 65  utomatically whe
5c60: 6e 0a 74 68 65 20 6c 61 73 74 20 61 63 74 69 76  n.the last activ
5c70: 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  e statement fini
5c80: 73 68 65 73 2e 20 20 41 20 73 74 61 74 65 6d 65  shes.  A stateme
5c90: 6e 74 20 66 69 6e 69 73 68 65 73 20 77 68 65 6e  nt finishes when
5ca0: 20 69 74 73 0a 70 72 65 70 61 72 65 64 20 73 74   its.prepared st
5cb0: 61 74 65 6d 65 6e 74 20 69 73 20 5b 73 71 6c 69  atement is [sqli
5cc0: 74 65 33 5f 72 65 73 65 74 28 29 20 7c 20 72 65  te3_reset() | re
5cd0: 73 65 74 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33  set] or.[sqlite3
5ce0: 5f 66 69 6e 61 6c 69 7a 65 28 29 20 7c 20 66 69  _finalize() | fi
5cf0: 6e 61 6c 69 7a 65 64 5d 2e 20 20 41 6e 20 6f 70  nalized].  An op
5d00: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  en [sqlite3_blob
5d10: 5d 20 75 73 65 64 20 66 6f 72 0a 69 6e 63 72 65  ] used for.incre
5d20: 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 20  mental BLOB I/O 
5d30: 63 6f 75 6e 74 73 20 61 73 20 61 6e 20 75 6e 66  counts as an unf
5d40: 69 6e 69 73 68 65 64 20 73 74 61 74 65 6d 65 6e  inished statemen
5d50: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
5d60: 5f 62 6c 6f 62 5d 0a 66 69 6e 69 73 68 65 73 20  _blob].finishes 
5d70: 77 68 65 6e 20 69 74 20 69 73 20 5b 73 71 6c 69  when it is [sqli
5d80: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
5d90: 20 7c 20 63 6c 6f 73 65 64 5d 2e 29 5e 0a 3c 2f   | closed].)^.</
5da0: 70 3e 0a 0a 3c 70 3e 0a 5e 54 68 65 20 65 78 70  p>..<p>.^The exp
5db0: 6c 69 63 69 74 20 43 4f 4d 4d 49 54 20 63 6f 6d  licit COMMIT com
5dc0: 6d 61 6e 64 20 72 75 6e 73 20 69 6d 6d 65 64 69  mand runs immedi
5dd0: 61 74 65 6c 79 2c 20 65 76 65 6e 20 69 66 20 74  ately, even if t
5de0: 68 65 72 65 20 61 72 65 0a 70 65 6e 64 69 6e 67  here are.pending
5df0: 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
5e00: 65 6e 74 73 2e 20 20 5e 48 6f 77 65 76 65 72 2c  ents.  ^However,
5e10: 20 69 66 20 74 68 65 72 65 20 61 72 65 20 70 65   if there are pe
5e20: 6e 64 69 6e 67 0a 77 72 69 74 65 20 6f 70 65 72  nding.write oper
5e30: 61 74 69 6f 6e 73 2c 20 74 68 65 20 43 4f 4d 4d  ations, the COMM
5e40: 49 54 20 63 6f 6d 6d 61 6e 64 0a 77 69 6c 6c 20  IT command.will 
5e50: 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
5e60: 6f 72 20 63 6f 64 65 20 5b 53 51 4c 49 54 45 5f  or code [SQLITE_
5e70: 42 55 53 59 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  BUSY]..</p>..<p>
5e80: 0a 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  .^An attempt to 
5e90: 65 78 65 63 75 74 65 20 43 4f 4d 4d 49 54 20 6d  execute COMMIT m
5ea0: 69 67 68 74 20 61 6c 73 6f 20 72 65 73 75 6c 74  ight also result
5eb0: 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42   in an [SQLITE_B
5ec0: 55 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 65  USY] return code
5ed0: 0a 69 66 20 61 6e 20 61 6e 6f 74 68 65 72 20 74  .if an another t
5ee0: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
5ef0: 20 68 61 73 20 61 20 5b 73 68 61 72 65 64 20 6c   has a [shared l
5f00: 6f 63 6b 5d 20 6f 6e 20 74 68 65 20 64 61 74 61  ock] on the data
5f10: 62 61 73 65 0a 74 68 61 74 20 70 72 65 76 65 6e  base.that preven
5f20: 74 65 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ted the database
5f30: 20 66 72 6f 6d 20 62 65 69 6e 67 20 75 70 64 61   from being upda
5f40: 74 65 64 2e 20 20 5e 57 68 65 6e 20 43 4f 4d 4d  ted.  ^When COMM
5f50: 49 54 20 66 61 69 6c 73 20 69 6e 20 74 68 69 73  IT fails in this
5f60: 0a 77 61 79 2c 20 74 68 65 20 74 72 61 6e 73 61  .way, the transa
5f70: 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 61 63  ction remains ac
5f80: 74 69 76 65 20 61 6e 64 20 74 68 65 20 43 4f 4d  tive and the COM
5f90: 4d 49 54 20 63 61 6e 20 62 65 20 72 65 74 72 69  MIT can be retri
5fa0: 65 64 20 6c 61 74 65 72 0a 61 66 74 65 72 20 74  ed later.after t
5fb0: 68 65 20 72 65 61 64 65 72 20 68 61 73 20 68 61  he reader has ha
5fc0: 64 20 61 20 63 68 61 6e 63 65 20 74 6f 20 63 6c  d a chance to cl
5fd0: 65 61 72 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  ear..</p>..<p>.I
5fe0: 6e 20 76 65 72 79 20 6f 6c 64 20 76 65 72 73 69  n very old versi
5ff0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 62  ons of SQLite (b
6000: 65 66 6f 72 65 20 76 65 72 73 69 6f 6e 20 33 2e  efore version 3.
6010: 37 2e 31 31 20 2d 20 5b 64 61 74 65 6f 66 3a 33  7.11 - [dateof:3
6020: 2e 37 2e 31 31 5d 29 0a 74 68 65 20 52 4f 4c 4c  .7.11]).the ROLL
6030: 42 41 43 4b 20 77 69 6c 6c 20 66 61 69 6c 20 77  BACK will fail w
6040: 69 74 68 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  ith an error cod
6050: 65 20 0a 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  e .[SQLITE_BUSY]
6060: 20 69 66 20 74 68 65 72 65 20 61 72 65 20 61 6e   if there are an
6070: 79 20 70 65 6e 64 69 6e 67 20 71 75 65 72 69 65  y pending querie
6080: 73 2e 20 20 5e 49 6e 20 6d 6f 72 65 20 72 65 63  s.  ^In more rec
6090: 65 6e 74 0a 76 65 72 73 69 6f 6e 73 20 6f 66 20  ent.versions of 
60a0: 53 51 4c 69 74 65 2c 20 74 68 65 20 52 4f 4c 4c  SQLite, the ROLL
60b0: 42 41 43 4b 20 77 69 6c 6c 20 70 72 6f 63 65 65  BACK will procee
60c0: 64 20 61 6e 64 20 70 65 6e 64 69 6e 67 20 73 74  d and pending st
60d0: 61 74 65 6d 65 6e 74 73 0a 77 69 6c 6c 20 6f 66  atements.will of
60e0: 74 65 6e 20 62 65 20 61 62 6f 72 74 65 64 2c 20  ten be aborted, 
60f0: 63 61 75 73 69 6e 67 20 74 68 65 6d 20 74 6f 20  causing them to 
6100: 72 65 74 75 72 6e 20 61 6e 20 5b 53 51 4c 49 54  return an [SQLIT
6110: 45 5f 41 42 4f 52 54 5d 20 6f 72 0a 5b 53 51 4c  E_ABORT] or.[SQL
6120: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
6130: 43 4b 5d 20 65 72 72 6f 72 2e 0a 5e 49 6e 20 53  CK] error..^In S
6140: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
6150: 38 2e 38 20 28 5b 64 61 74 65 6f 66 3a 33 2e 38  8.8 ([dateof:3.8
6160: 2e 38 5d 29 20 61 6e 64 20 6c 61 74 65 72 2c 0a  .8]) and later,.
6170: 61 20 70 65 6e 64 69 6e 67 20 72 65 61 64 20 77  a pending read w
6180: 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 66 75 6e  ill continue fun
6190: 63 74 69 6f 6e 69 6e 67 0a 61 66 74 65 72 20 74  ctioning.after t
61a0: 68 65 20 52 4f 4c 4c 42 41 43 4b 20 61 73 20 6c  he ROLLBACK as l
61b0: 6f 6e 67 20 61 73 20 74 68 65 20 52 4f 4c 4c 42  ong as the ROLLB
61c0: 41 43 4b 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ACK does not mod
61d0: 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
61e0: 0a 73 63 68 65 6d 61 2e 0a 3c 2f 70 3e 0a 0a 3c  .schema..</p>..<
61f0: 70 3e 0a 49 66 20 5b 50 52 41 47 4d 41 20 6a 6f  p>.If [PRAGMA jo
6200: 75 72 6e 61 6c 5f 6d 6f 64 65 5d 20 69 73 20 73  urnal_mode] is s
6210: 65 74 20 74 6f 20 4f 46 46 20 28 74 68 75 73 20  et to OFF (thus 
6220: 64 69 73 61 62 6c 69 6e 67 20 74 68 65 20 72 6f  disabling the ro
6230: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 0a 66  llback journal.f
6240: 69 6c 65 29 20 74 68 65 6e 20 74 68 65 20 62 65  ile) then the be
6250: 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 52 4f  havior of the RO
6260: 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 69  LLBACK command i
6270: 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 3c 2f 70  s undefined..</p
6280: 3e 0a 0a 3c 68 33 3e 52 65 73 70 6f 6e 73 65 20  >..<h3>Response 
6290: 54 6f 20 45 72 72 6f 72 73 20 57 69 74 68 69 6e  To Errors Within
62a0: 20 41 20 54 72 61 6e 73 61 63 74 69 6f 6e 3c 2f   A Transaction</
62b0: 68 33 3e 0a 0a 3c 70 3e 20 5e 28 49 66 20 63 65  h3>..<p> ^(If ce
62c0: 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
62d0: 72 72 6f 72 73 20 6f 63 63 75 72 20 77 69 74 68  rrors occur with
62e0: 69 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  in a transaction
62f0: 2c 20 74 68 65 0a 74 72 61 6e 73 61 63 74 69 6f  , the.transactio
6300: 6e 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  n may or may not
6310: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
6320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
6330: 54 68 65 0a 65 72 72 6f 72 73 20 74 68 61 74 20  The.errors that 
6340: 63 61 6e 20 63 61 75 73 65 20 61 6e 20 61 75 74  can cause an aut
6350: 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
6360: 69 6e 63 6c 75 64 65 3a 3c 2f 70 3e 0a 0a 3c 75  include:</p>..<u
6370: 6c 3e 0a 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  l>.<li> [SQLITE_
6380: 46 55 4c 4c 5d 3a 20 64 61 74 61 62 61 73 65 20  FULL]: database 
6390: 6f 72 20 64 69 73 6b 20 66 75 6c 6c 0a 3c 6c 69  or disk full.<li
63a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  > [SQLITE_IOERR]
63b0: 3a 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  : disk I/O error
63c0: 0a 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 42 55  .<li> [SQLITE_BU
63d0: 53 59 5d 3a 20 64 61 74 61 62 61 73 65 20 69 6e  SY]: database in
63e0: 20 75 73 65 20 62 79 20 61 6e 6f 74 68 65 72 20   use by another 
63f0: 70 72 6f 63 65 73 73 0a 3c 6c 69 3e 20 5b 53 51  process.<li> [SQ
6400: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 3a 20 6f 75 74  LITE_NOMEM]: out
6410: 20 6f 72 20 6d 65 6d 6f 72 79 0a 3c 2f 75 6c 3e   or memory.</ul>
6420: 29 5e 0a 0a 3c 70 3e 0a 5e 46 6f 72 20 61 6c 6c  )^..<p>.^For all
6430: 20 6f 66 20 74 68 65 73 65 20 65 72 72 6f 72 73   of these errors
6440: 2c 20 53 51 4c 69 74 65 20 61 74 74 65 6d 70 74  , SQLite attempt
6450: 73 20 74 6f 20 75 6e 64 6f 20 6a 75 73 74 20 74  s to undo just t
6460: 68 65 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74  he one statement
6470: 0a 69 74 20 77 61 73 20 77 6f 72 6b 69 6e 67 20  .it was working 
6480: 6f 6e 20 61 6e 64 20 6c 65 61 76 65 20 63 68 61  on and leave cha
6490: 6e 67 65 73 20 66 72 6f 6d 20 70 72 69 6f 72 20  nges from prior 
64a0: 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69  statements withi
64b0: 6e 20 74 68 65 0a 73 61 6d 65 20 74 72 61 6e 73  n the.same trans
64c0: 61 63 74 69 6f 6e 20 69 6e 74 61 63 74 20 61 6e  action intact an
64d0: 64 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 20  d continue with 
64e0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  the transaction.
64f0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 0a 64 65 70    ^However, .dep
6500: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  ending on the st
6510: 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 76  atement being ev
6520: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
6530: 70 6f 69 6e 74 20 61 74 20 77 68 69 63 68 20 74  point at which t
6540: 68 65 0a 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  he.error occurs,
6550: 20 69 74 20 6d 69 67 68 74 20 62 65 20 6e 65 63   it might be nec
6560: 65 73 73 61 72 79 20 66 6f 72 20 53 51 4c 69 74  essary for SQLit
6570: 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20 61 6e  e to rollback an
6580: 64 0a 63 61 6e 63 65 6c 20 74 68 65 20 65 6e 74  d.cancel the ent
6590: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ire transaction.
65a0: 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
65b0: 6e 20 63 61 6e 20 74 65 6c 6c 20 77 68 69 63 68  n can tell which
65c0: 0a 63 6f 75 72 73 65 20 6f 66 20 61 63 74 69 6f  .course of actio
65d0: 6e 20 53 51 4c 69 74 65 20 74 6f 6f 6b 20 62 79  n SQLite took by
65e0: 20 75 73 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69   using the.[sqli
65f0: 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
6600: 69 74 28 29 5d 20 43 2d 6c 61 6e 67 75 61 67 65  it()] C-language
6610: 20 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70 3e 0a   interface.</p>.
6620: 0a 3c 70 3e 49 74 20 69 73 20 72 65 63 6f 6d 6d  .<p>It is recomm
6630: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
6640: 63 61 74 69 6f 6e 73 20 72 65 73 70 6f 6e 64 20  cations respond 
6650: 74 6f 20 74 68 65 20 65 72 72 6f 72 73 0a 6c 69  to the errors.li
6660: 73 74 65 64 20 61 62 6f 76 65 20 62 79 20 65 78  sted above by ex
6670: 70 6c 69 63 69 74 6c 79 20 69 73 73 75 69 6e 67  plicitly issuing
6680: 20 61 20 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d   a ROLLBACK comm
6690: 61 6e 64 2e 20 20 5e 49 66 20 74 68 65 20 0a 74  and.  ^If the .t
66a0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 61  ransaction has a
66b0: 6c 72 65 61 64 79 20 62 65 65 6e 20 72 6f 6c 6c  lready been roll
66c0: 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
66d0: 63 61 6c 6c 79 0a 62 79 20 74 68 65 20 65 72 72  cally.by the err
66e0: 6f 72 20 72 65 73 70 6f 6e 73 65 2c 20 74 68 65  or response, the
66f0: 6e 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63  n the ROLLBACK c
6700: 6f 6d 6d 61 6e 64 20 77 69 6c 6c 20 66 61 69 6c  ommand will fail
6710: 20 77 69 74 68 20 61 6e 0a 65 72 72 6f 72 2c 20   with an.error, 
6720: 62 75 74 20 6e 6f 20 68 61 72 6d 20 69 73 20 63  but no harm is c
6730: 61 75 73 65 64 20 62 79 20 74 68 69 73 2e 3c 2f  aused by this.</
6740: 70 3e 0a 0a 3c 70 3e 46 75 74 75 72 65 20 76 65  p>..<p>Future ve
6750: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
6760: 20 6d 61 79 20 65 78 74 65 6e 64 20 74 68 65 20   may extend the 
6770: 6c 69 73 74 20 6f 66 20 65 72 72 6f 72 73 20 77  list of errors w
6780: 68 69 63 68 0a 6d 69 67 68 74 20 63 61 75 73 65  hich.might cause
6790: 20 61 75 74 6f 6d 61 74 69 63 20 74 72 61 6e 73   automatic trans
67a0: 61 63 74 69 6f 6e 20 72 6f 6c 6c 62 61 63 6b 2e  action rollback.
67b0: 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
67c0: 73 20 6f 66 0a 53 51 4c 69 74 65 20 6d 69 67 68  s of.SQLite migh
67d0: 74 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72  t change the err
67e0: 6f 72 20 72 65 73 70 6f 6e 73 65 2e 20 20 49 6e  or response.  In
67f0: 20 70 61 72 74 69 63 75 6c 61 72 2c 20 77 65 20   particular, we 
6800: 6d 61 79 0a 63 68 6f 6f 73 65 20 74 6f 20 73 69  may.choose to si
6810: 6d 70 6c 69 66 79 20 74 68 65 20 69 6e 74 65 72  mplify the inter
6820: 66 61 63 65 20 69 6e 20 66 75 74 75 72 65 20 76  face in future v
6830: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
6840: 65 20 62 79 0a 63 61 75 73 69 6e 67 20 74 68 65  e by.causing the
6850: 20 65 72 72 6f 72 73 20 61 62 6f 76 65 20 74 6f   errors above to
6860: 20 66 6f 72 63 65 20 61 6e 20 75 6e 63 6f 6e 64   force an uncond
6870: 69 74 69 6f 6e 61 6c 20 72 6f 6c 6c 62 61 63 6b  itional rollback
6880: 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23  .</p>..<tcl>.###
6890: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
68a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
68b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
68c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
68d0: 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63  ############.Sec
68e0: 74 69 6f 6e 20 7b 53 41 56 45 50 4f 49 4e 54 7d  tion {SAVEPOINT}
68f0: 20 73 61 76 65 70 6f 69 6e 74 20 7b 53 41 56 45   savepoint {SAVE
6900: 50 4f 49 4e 54 20 52 45 4c 45 41 53 45 7d 0a 0a  POINT RELEASE}..
6910: 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
6920: 69 61 67 72 61 6d 20 73 61 76 65 70 6f 69 6e 74  iagram savepoint
6930: 2d 73 74 6d 74 0a 52 65 63 75 72 73 69 76 65 42  -stmt.RecursiveB
6940: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 65 6c  ubbleDiagram rel
6950: 65 61 73 65 2d 73 74 6d 74 0a 52 65 63 75 72 73  ease-stmt.Recurs
6960: 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d  iveBubbleDiagram
6970: 20 72 6f 6c 6c 62 61 63 6b 2d 73 74 6d 74 0a 3c   rollback-stmt.<
6980: 2f 74 63 6c 3e 0a 0a 3c 70 3e 20 5e 53 41 56 45  /tcl>..<p> ^SAVE
6990: 50 4f 49 4e 54 73 20 61 72 65 20 61 20 6d 65 74  POINTs are a met
69a0: 68 6f 64 20 6f 66 20 63 72 65 61 74 69 6e 67 20  hod of creating 
69b0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 2c 20 73 69  transactions, si
69c0: 6d 69 6c 61 72 20 74 6f 0a 5b 42 45 47 49 4e 5d  milar to.[BEGIN]
69d0: 20 61 6e 64 20 5b 43 4f 4d 4d 49 54 5d 2c 20 65   and [COMMIT], e
69e0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 53  xcept that the S
69f0: 41 56 45 50 4f 49 4e 54 20 61 6e 64 20 52 45 4c  AVEPOINT and REL
6a00: 45 41 53 45 20 63 6f 6d 6d 61 6e 64 73 0a 61 72  EASE commands.ar
6a10: 65 20 6e 61 6d 65 64 20 61 6e 64 20 6d 61 79 20  e named and may 
6a20: 62 65 20 6e 65 73 74 65 64 2e 3c 2f 70 3e 0a 0a  be nested.</p>..
6a30: 3c 70 3e 20 5e 54 68 65 20 53 41 56 45 50 4f 49  <p> ^The SAVEPOI
6a40: 4e 54 20 63 6f 6d 6d 61 6e 64 20 73 74 61 72 74  NT command start
6a50: 73 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63 74  s a new transact
6a60: 69 6f 6e 20 77 69 74 68 20 61 20 6e 61 6d 65 2e  ion with a name.
6a70: 0a 5e 54 68 65 20 74 72 61 6e 73 61 63 74 69 6f  .^The transactio
6a80: 6e 20 6e 61 6d 65 73 20 6e 65 65 64 20 6e 6f 74  n names need not
6a90: 20 62 65 20 75 6e 69 71 75 65 2e 0a 5e 28 41 20   be unique..^(A 
6aa0: 53 41 56 45 50 4f 49 4e 54 20 63 61 6e 20 62 65  SAVEPOINT can be
6ab0: 20 73 74 61 72 74 65 64 20 65 69 74 68 65 72 20   started either 
6ac0: 77 69 74 68 69 6e 20 6f 72 20 6f 75 74 73 69 64  within or outsid
6ad0: 65 20 6f 66 0a 61 20 5b 42 45 47 49 4e 5d 2e 2e  e of.a [BEGIN]..
6ae0: 2e 5b 43 4f 4d 4d 49 54 5d 2e 29 5e 20 20 5e 28  .[COMMIT].)^  ^(
6af0: 57 68 65 6e 20 61 20 53 41 56 45 50 4f 49 4e 54  When a SAVEPOINT
6b00: 20 69 73 20 74 68 65 20 6f 75 74 65 72 2d 6d 6f   is the outer-mo
6b10: 73 74 20 73 61 76 65 70 6f 69 6e 74 0a 61 6e 64  st savepoint.and
6b20: 20 69 74 20 69 73 20 6e 6f 74 20 77 69 74 68 69   it is not withi
6b30: 6e 20 61 20 5b 42 45 47 49 4e 5d 2e 2e 2e 5b 43  n a [BEGIN]...[C
6b40: 4f 4d 4d 49 54 5d 20 74 68 65 6e 20 74 68 65 20  OMMIT] then the 
6b50: 62 65 68 61 76 69 6f 72 20 69 73 20 74 68 65 0a  behavior is the.
6b60: 73 61 6d 65 20 61 73 20 42 45 47 49 4e 20 44 45  same as BEGIN DE
6b70: 46 45 52 52 45 44 20 54 52 41 4e 53 41 43 54 49  FERRED TRANSACTI
6b80: 4f 4e 2e 29 5e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54  ON.)^</p>..<p>^T
6b90: 68 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63  he ROLLBACK TO c
6ba0: 6f 6d 6d 61 6e 64 20 72 65 76 65 72 74 73 20 74  ommand reverts t
6bb0: 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
6bc0: 64 61 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f  database back to
6bd0: 20 77 68 61 74 0a 69 74 20 77 61 73 20 6a 75 73   what.it was jus
6be0: 74 20 61 66 74 65 72 20 74 68 65 20 63 6f 72 72  t after the corr
6bf0: 65 73 70 6f 6e 64 69 6e 67 20 53 41 56 45 50 4f  esponding SAVEPO
6c00: 49 4e 54 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  INT.  ^Note that
6c10: 20 75 6e 6c 69 6b 65 20 74 68 61 74 0a 70 6c 61   unlike that.pla
6c20: 69 6e 20 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f  in [ROLLBACK] co
6c30: 6d 6d 61 6e 64 20 28 77 69 74 68 6f 75 74 20 74  mmand (without t
6c40: 68 65 20 54 4f 20 6b 65 79 77 6f 72 64 29 20 74  he TO keyword) t
6c50: 68 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63  he ROLLBACK TO c
6c60: 6f 6d 6d 61 6e 64 0a 64 6f 65 73 20 6e 6f 74 20  ommand.does not 
6c70: 63 61 6e 63 65 6c 20 74 68 65 20 74 72 61 6e 73  cancel the trans
6c80: 61 63 74 69 6f 6e 2e 20 20 5e 49 6e 73 74 65 61  action.  ^Instea
6c90: 64 20 6f 66 20 63 61 6e 63 65 6c 6c 69 6e 67 20  d of cancelling 
6ca0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  the transaction,
6cb0: 0a 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f  .the ROLLBACK TO
6cc0: 20 63 6f 6d 6d 61 6e 64 20 72 65 73 74 61 72 74   command restart
6cd0: 73 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  s the transactio
6ce0: 6e 20 61 67 61 69 6e 20 61 74 20 74 68 65 20 62  n again at the b
6cf0: 65 67 69 6e 6e 69 6e 67 2e 0a 5e 41 6c 6c 20 69  eginning..^All i
6d00: 6e 74 65 72 76 65 6e 69 6e 67 20 53 41 56 45 50  ntervening SAVEP
6d10: 4f 49 4e 54 73 20 61 72 65 20 63 61 6e 63 65 6c  OINTs are cancel
6d20: 65 64 2c 20 68 6f 77 65 76 65 72 2e 3c 2f 70 3e  ed, however.</p>
6d30: 0a 0a 3c 70 3e 5e 54 68 65 20 52 45 4c 45 41 53  ..<p>^The RELEAS
6d40: 45 20 63 6f 6d 6d 61 6e 64 20 69 73 20 6c 69 6b  E command is lik
6d50: 65 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 66 6f 72  e a [COMMIT] for
6d60: 20 61 20 53 41 56 45 50 4f 49 4e 54 2e 0a 5e 54   a SAVEPOINT..^T
6d70: 68 65 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61  he RELEASE comma
6d80: 6e 64 20 63 61 75 73 65 73 20 61 6c 6c 20 73 61  nd causes all sa
6d90: 76 65 70 6f 69 6e 74 73 20 62 61 63 6b 20 74 6f  vepoints back to
6da0: 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 74   and including t
6db0: 68 65 20 0a 6d 6f 73 74 20 72 65 63 65 6e 74 20  he .most recent 
6dc0: 73 61 76 65 70 6f 69 6e 74 20 77 69 74 68 20 61  savepoint with a
6dd0: 20 6d 61 74 63 68 69 6e 67 20 6e 61 6d 65 20 74   matching name t
6de0: 6f 20 62 65 20 72 65 6d 6f 76 65 64 20 66 72 6f  o be removed fro
6df0: 6d 20 74 68 65 20 0a 74 72 61 6e 73 61 63 74 69  m the .transacti
6e00: 6f 6e 20 73 74 61 63 6b 2e 20 20 5e 54 68 65 20  on stack.  ^The 
6e10: 52 45 4c 45 41 53 45 20 6f 66 20 61 6e 20 69 6e  RELEASE of an in
6e20: 6e 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ner transaction.
6e30: 64 6f 65 73 20 6e 6f 74 20 63 61 75 73 65 20 61  does not cause a
6e40: 6e 79 20 63 68 61 6e 67 65 73 20 74 6f 20 62 65  ny changes to be
6e50: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
6e60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 3b 20 69  database file; i
6e70: 74 20 6d 65 72 65 6c 79 0a 72 65 6d 6f 76 65 73  t merely.removes
6e80: 20 73 61 76 65 70 6f 69 6e 74 73 20 66 72 6f 6d   savepoints from
6e90: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
6ea0: 20 73 74 61 63 6b 20 73 75 63 68 20 74 68 61 74   stack such that
6eb0: 20 69 74 20 69 73 0a 6e 6f 20 6c 6f 6e 67 65 72   it is.no longer
6ec0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 52 4f 4c   possible to ROL
6ed0: 4c 42 41 43 4b 20 54 4f 20 74 68 6f 73 65 20 73  LBACK TO those s
6ee0: 61 76 65 70 6f 69 6e 74 73 2e 0a 5e 49 66 20 61  avepoints..^If a
6ef0: 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64   RELEASE command
6f00: 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 6f 75   releases the ou
6f10: 74 65 72 6d 6f 73 74 20 73 61 76 65 70 6f 69 6e  termost savepoin
6f20: 74 2c 20 73 6f 0a 74 68 61 74 20 74 68 65 20 74  t, so.that the t
6f30: 72 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 63 6b  ransaction stack
6f40: 20 62 65 63 6f 6d 65 73 20 65 6d 70 74 79 2c 20   becomes empty, 
6f50: 74 68 65 6e 20 52 45 4c 45 41 53 45 20 69 73 20  then RELEASE is 
6f60: 74 68 65 20 73 61 6d 65 0a 61 73 20 5b 43 4f 4d  the same.as [COM
6f70: 4d 49 54 5d 2e 0a 5e 54 68 65 20 5b 43 4f 4d 4d  MIT]..^The [COMM
6f80: 49 54 5d 20 63 6f 6d 6d 61 6e 64 20 6d 61 79 20  IT] command may 
6f90: 62 65 20 75 73 65 64 20 74 6f 20 72 65 6c 65 61  be used to relea
6fa0: 73 65 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74  se all savepoint
6fb0: 73 20 61 6e 64 0a 63 6f 6d 6d 69 74 20 74 68 65  s and.commit the
6fc0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 65 76 65   transaction eve
6fd0: 6e 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63  n if the transac
6fe0: 74 69 6f 6e 20 77 61 73 20 6f 72 69 67 69 6e 61  tion was origina
6ff0: 6c 6c 79 20 73 74 61 72 74 65 64 0a 62 79 20 61  lly started.by a
7000: 20 53 41 56 45 50 4f 49 4e 54 20 63 6f 6d 6d 61   SAVEPOINT comma
7010: 6e 64 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  nd instead of a 
7020: 5b 42 45 47 49 4e 5d 20 63 6f 6d 6d 61 6e 64 2e  [BEGIN] command.
7030: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65  </p>..<p>^If the
7040: 20 73 61 76 65 70 6f 69 6e 74 2d 6e 61 6d 65 20   savepoint-name 
7050: 69 6e 20 61 20 52 45 4c 45 41 53 45 20 63 6f 6d  in a RELEASE com
7060: 6d 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6d 61  mand does not ma
7070: 74 63 68 20 61 6e 79 0a 73 61 76 65 70 6f 69 6e  tch any.savepoin
7080: 74 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 74  t currently in t
7090: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  he transaction s
70a0: 74 61 63 6b 2c 20 74 68 65 6e 20 6e 6f 20 73 61  tack, then no sa
70b0: 76 65 70 6f 69 6e 74 73 20 61 72 65 0a 72 65 6c  vepoints are.rel
70c0: 65 61 73 65 64 2c 20 74 68 65 20 64 61 74 61 62  eased, the datab
70d0: 61 73 65 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ase is unchanged
70e0: 2c 20 61 6e 64 20 74 68 65 20 52 45 4c 45 41 53  , and the RELEAS
70f0: 45 20 63 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e  E command return
7100: 73 0a 61 6e 20 65 72 72 6f 72 2e 3c 2f 70 3e 0a  s.an error.</p>.
7110: 0a 3c 70 3e 5e 4e 6f 74 65 20 74 68 61 74 20 61  .<p>^Note that a
7120: 6e 20 69 6e 6e 65 72 20 74 72 61 6e 73 61 63 74  n inner transact
7130: 69 6f 6e 20 6d 69 67 68 74 20 63 6f 6d 6d 69 74  ion might commit
7140: 20 28 75 73 69 6e 67 20 74 68 65 20 52 45 4c 45   (using the RELE
7150: 41 53 45 20 63 6f 6d 6d 61 6e 64 29 0a 62 75 74  ASE command).but
7160: 20 74 68 65 6e 20 6c 61 74 65 72 20 68 61 76 65   then later have
7170: 20 69 74 73 20 77 6f 72 6b 20 75 6e 64 6f 6e 65   its work undone
7180: 20 62 79 20 61 20 52 4f 4c 4c 42 41 43 4b 20 69   by a ROLLBACK i
7190: 6e 20 61 6e 20 6f 75 74 65 72 20 74 72 61 6e 73  n an outer trans
71a0: 61 63 74 69 6f 6e 2e 0a 5e 41 20 70 6f 77 65 72  action..^A power
71b0: 20 66 61 69 6c 75 72 65 20 6f 72 20 70 72 6f 67   failure or prog
71c0: 72 61 6d 20 63 72 61 73 68 20 6f 72 20 4f 53 20  ram crash or OS 
71d0: 63 72 61 73 68 20 77 69 6c 6c 20 63 61 75 73 65  crash will cause
71e0: 20 74 68 65 20 6f 75 74 65 72 2d 6d 6f 73 74 0a   the outer-most.
71f0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72  transaction to r
7200: 6f 6c 6c 62 61 63 6b 2c 20 75 6e 64 6f 69 6e 67  ollback, undoing
7210: 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 74 68 61   all changes tha
7220: 74 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  t have occurred 
7230: 77 69 74 68 69 6e 0a 74 68 61 74 20 6f 75 74 65  within.that oute
7240: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65  r transaction, e
7250: 76 65 6e 20 63 68 61 6e 67 65 73 20 74 68 61 74  ven changes that
7260: 20 68 61 76 65 20 73 75 70 70 6f 73 65 64 6c 79   have supposedly
7270: 20 62 65 65 6e 20 22 63 6f 6d 6d 69 74 74 65 64   been "committed
7280: 22 0a 62 79 20 74 68 65 20 52 45 4c 45 41 53 45  ".by the RELEASE
7290: 20 63 6f 6d 6d 61 6e 64 2e 20 20 5e 43 6f 6e 74   command.  ^Cont
72a0: 65 6e 74 20 69 73 20 6e 6f 74 20 61 63 74 75 61  ent is not actua
72b0: 6c 6c 79 20 63 6f 6d 6d 69 74 74 65 64 20 6f 6e  lly committed on
72c0: 20 74 68 65 20 64 69 73 6b 20 0a 75 6e 74 69 6c   the disk .until
72d0: 20 74 68 65 20 6f 75 74 65 72 6d 6f 73 74 20 74   the outermost t
72e0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
72f0: 74 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 72  ts.</p>..<p>Ther
7300: 65 20 61 72 65 20 73 65 76 65 72 61 6c 20 77 61  e are several wa
7310: 79 73 20 6f 66 20 74 68 69 6e 6b 69 6e 67 20 61  ys of thinking a
7320: 62 6f 75 74 20 74 68 65 20 52 45 4c 45 41 53 45  bout the RELEASE
7330: 20 63 6f 6d 6d 61 6e 64 3a 3c 2f 70 3e 0a 0a 3c   command:</p>..<
7340: 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 53 6f 6d 65  ul>.<li><p>.Some
7350: 20 70 65 6f 70 6c 65 20 76 69 65 77 20 52 45 4c   people view REL
7360: 45 41 53 45 20 61 73 20 74 68 65 20 65 71 75 69  EASE as the equi
7370: 76 61 6c 65 6e 74 20 6f 66 20 43 4f 4d 4d 49 54  valent of COMMIT
7380: 20 66 6f 72 20 61 20 53 41 56 45 50 4f 49 4e 54   for a SAVEPOINT
7390: 2e 0a 54 68 69 73 20 69 73 20 61 6e 20 61 63 63  ..This is an acc
73a0: 65 70 74 61 62 6c 65 20 70 6f 69 6e 74 20 6f 66  eptable point of
73b0: 20 76 69 65 77 20 61 73 20 6c 6f 6e 67 20 61 73   view as long as
73c0: 20 6f 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 74   one remembers t
73d0: 68 61 74 20 74 68 65 0a 63 68 61 6e 67 65 73 20  hat the.changes 
73e0: 63 6f 6d 6d 69 74 74 65 64 20 62 79 20 61 6e 20  committed by an 
73f0: 69 6e 6e 65 72 20 74 72 61 6e 73 61 63 74 69 6f  inner transactio
7400: 6e 20 6d 69 67 68 74 20 6c 61 74 65 72 20 62 65  n might later be
7410: 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 72 6f 6c   undone by a.rol
7420: 6c 62 61 63 6b 20 69 6e 20 61 6e 20 6f 75 74 65  lback in an oute
7430: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 3c 2f  r transaction.</
7440: 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e  p></li>..<li><p>
7450: 0a 41 6e 6f 74 68 65 72 20 76 69 65 77 20 6f 66  .Another view of
7460: 20 52 45 4c 45 41 53 45 20 69 73 20 74 68 61 74   RELEASE is that
7470: 20 69 74 20 6d 65 72 67 65 73 20 61 20 6e 61 6d   it merges a nam
7480: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ed transaction i
7490: 6e 74 6f 20 69 74 73 0a 70 61 72 65 6e 74 20 74  nto its.parent t
74a0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 73 6f 20 74  ransaction, so t
74b0: 68 61 74 20 74 68 65 20 6e 61 6d 65 64 20 74 72  hat the named tr
74c0: 61 6e 73 61 63 74 69 6f 6e 20 61 6e 64 20 69 74  ansaction and it
74d0: 73 20 70 61 72 65 6e 74 20 62 65 63 6f 6d 65 0a  s parent become.
74e0: 74 68 65 20 73 61 6d 65 20 74 72 61 6e 73 61 63  the same transac
74f0: 74 69 6f 6e 2e 20 20 41 66 74 65 72 20 52 45 4c  tion.  After REL
7500: 45 41 53 45 2c 20 74 68 65 20 6e 61 6d 65 64 20  EASE, the named 
7510: 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 6e 64 20  transaction and 
7520: 69 74 73 20 70 61 72 65 6e 74 0a 77 69 6c 6c 20  its parent.will 
7530: 63 6f 6d 6d 69 74 20 6f 72 20 72 6f 6c 6c 62 61  commit or rollba
7540: 63 6b 20 74 6f 67 65 74 68 65 72 2c 20 77 68 61  ck together, wha
7550: 74 65 76 65 72 20 74 68 65 69 72 20 66 61 74 65  tever their fate
7560: 20 6d 61 79 20 62 65 2e 0a 3c 2f 70 3e 3c 2f 6c   may be..</p></l
7570: 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 4f 6e 65 20  i>..<li><p>.One 
7580: 63 61 6e 20 61 6c 73 6f 20 74 68 69 6e 6b 20 6f  can also think o
7590: 66 20 73 61 76 65 70 6f 69 6e 74 73 20 61 73 0a  f savepoints as.
75a0: 22 6d 61 72 6b 73 22 20 69 6e 20 74 68 65 20 74  "marks" in the t
75b0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 69 6d 65 6c  ransaction timel
75c0: 69 6e 65 2e 20 20 49 6e 20 74 68 69 73 20 76 69  ine.  In this vi
75d0: 65 77 2c 20 74 68 65 20 53 41 56 45 50 4f 49 4e  ew, the SAVEPOIN
75e0: 54 20 63 6f 6d 6d 61 6e 64 0a 63 72 65 61 74 65  T command.create
75f0: 73 20 61 20 6e 65 77 20 6d 61 72 6b 2c 20 74 68  s a new mark, th
7600: 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f  e ROLLBACK TO co
7610: 6d 6d 61 6e 64 20 72 65 77 69 6e 64 73 20 74 68  mmand rewinds th
7620: 65 20 74 69 6d 65 6c 69 6e 65 20 62 61 63 6b 0a  e timeline back.
7630: 74 6f 20 61 20 70 6f 69 6e 74 20 6a 75 73 74 20  to a point just 
7640: 61 66 74 65 72 20 74 68 65 20 6e 61 6d 65 64 20  after the named 
7650: 6d 61 72 6b 2c 20 61 6e 64 20 74 68 65 20 52 45  mark, and the RE
7660: 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 0a 65 72  LEASE command.er
7670: 61 73 65 73 20 6d 61 72 6b 73 20 66 72 6f 6d 20  ases marks from 
7680: 74 68 65 20 74 69 6d 65 6c 69 6e 65 20 77 69 74  the timeline wit
7690: 68 6f 75 74 20 61 63 74 75 61 6c 6c 79 20 6d 61  hout actually ma
76a0: 6b 69 6e 67 20 61 6e 79 0a 63 68 61 6e 67 65 73  king any.changes
76b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
76c0: 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c  ..</p></li>.</ul
76d0: 3e 0a 0a 0a 0a 3c 68 33 3e 54 72 61 6e 73 61 63  >....<h3>Transac
76e0: 74 69 6f 6e 20 4e 65 73 74 69 6e 67 20 52 75 6c  tion Nesting Rul
76f0: 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65  es</h3>..<p>^The
7700: 20 6c 61 73 74 20 74 72 61 6e 73 61 63 74 69 6f   last transactio
7710: 6e 20 73 74 61 72 74 65 64 20 77 69 6c 6c 20 62  n started will b
7720: 65 20 74 68 65 20 66 69 72 73 74 0a 74 72 61 6e  e the first.tran
7730: 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 74 65  saction committe
7740: 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b  d or rolled back
7750: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b  .</p>..<p>^The [
7760: 42 45 47 49 4e 5d 20 63 6f 6d 6d 61 6e 64 20 6f  BEGIN] command o
7770: 6e 6c 79 20 77 6f 72 6b 73 20 69 66 20 74 68 65  nly works if the
7780: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 74 61   transaction sta
7790: 63 6b 20 69 73 20 65 6d 70 74 79 2c 20 6f 72 0a  ck is empty, or.
77a0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 20 69  in other words i
77b0: 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 70  f there are no p
77c0: 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69  ending transacti
77d0: 6f 6e 73 2e 20 20 5e 49 66 20 74 68 65 20 74 72  ons.  ^If the tr
77e0: 61 6e 73 61 63 74 69 6f 6e 0a 73 74 61 63 6b 20  ansaction.stack 
77f0: 69 73 20 6e 6f 74 20 65 6d 70 74 79 20 77 68 65  is not empty whe
7800: 6e 20 74 68 65 20 5b 42 45 47 49 4e 5d 20 63 6f  n the [BEGIN] co
7810: 6d 6d 61 6e 64 20 69 73 20 69 6e 76 6f 6b 65 64  mmand is invoked
7820: 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 61  , then the comma
7830: 6e 64 0a 66 61 69 6c 73 20 77 69 74 68 20 61 6e  nd.fails with an
7840: 20 65 72 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e   error.</p>..<p>
7850: 5e 54 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 63 6f  ^The [COMMIT] co
7860: 6d 6d 61 6e 64 20 63 6f 6d 6d 69 74 73 20 61 6c  mmand commits al
7870: 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 74 72  l outstanding tr
7880: 61 6e 73 61 63 74 69 6f 6e 73 20 61 6e 64 20 6c  ansactions and l
7890: 65 61 76 65 73 0a 74 68 65 20 74 72 61 6e 73 61  eaves.the transa
78a0: 63 74 69 6f 6e 20 73 74 61 63 6b 20 65 6d 70 74  ction stack empt
78b0: 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  y.</p>..<p>^The 
78c0: 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20  RELEASE command 
78d0: 73 74 61 72 74 73 20 77 69 74 68 20 74 68 65 20  starts with the 
78e0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 61 64 64 69  most recent addi
78f0: 74 69 6f 6e 20 74 6f 20 74 68 65 0a 74 72 61 6e  tion to the.tran
7900: 73 61 63 74 69 6f 6e 20 73 74 61 63 6b 20 61 6e  saction stack an
7910: 64 20 72 65 6c 65 61 73 65 73 20 73 61 76 65 70  d releases savep
7920: 6f 69 6e 74 73 20 62 61 63 6b 77 61 72 64 73 20  oints backwards 
7930: 0a 69 6e 20 74 69 6d 65 20 75 6e 74 69 6c 20 69  .in time until i
7940: 74 20 72 65 6c 65 61 73 65 73 20 61 20 73 61 76  t releases a sav
7950: 65 70 6f 69 6e 74 20 77 69 74 68 20 61 20 6d 61  epoint with a ma
7960: 74 63 68 69 6e 67 20 73 61 76 65 70 6f 69 6e 74  tching savepoint
7970: 2d 6e 61 6d 65 2e 0a 5e 50 72 69 6f 72 20 73 61  -name..^Prior sa
7980: 76 65 70 6f 69 6e 74 73 2c 20 65 76 65 6e 20 73  vepoints, even s
7990: 61 76 65 70 6f 69 6e 74 73 20 77 69 74 68 20 6d  avepoints with m
79a0: 61 74 63 68 69 6e 67 20 73 61 76 65 70 6f 69 6e  atching savepoin
79b0: 74 2d 6e 61 6d 65 73 2c 20 61 72 65 0a 75 6e 63  t-names, are.unc
79c0: 68 61 6e 67 65 64 2e 0a 5e 49 66 20 74 68 65 20  hanged..^If the 
79d0: 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20  RELEASE command 
79e0: 63 61 75 73 65 73 20 74 68 65 0a 74 72 61 6e 73  causes the.trans
79f0: 61 63 74 69 6f 6e 20 73 74 61 63 6b 20 74 6f 20  action stack to 
7a00: 62 65 63 6f 6d 65 20 65 6d 70 74 79 20 28 69 66  become empty (if
7a10: 20 74 68 65 20 52 45 4c 45 41 53 45 20 63 6f 6d   the RELEASE com
7a20: 6d 61 6e 64 20 72 65 6c 65 61 73 65 73 20 74 68  mand releases th
7a30: 65 0a 6f 75 74 65 72 6d 6f 73 74 20 74 72 61 6e  e.outermost tran
7a40: 73 61 63 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65  saction from the
7a50: 20 73 74 61 63 6b 29 20 74 68 65 6e 20 74 68 65   stack) then the
7a60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
7a70: 6d 69 74 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54  mits.</p>..<p>^T
7a80: 68 65 20 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f  he [ROLLBACK] co
7a90: 6d 6d 61 6e 64 20 77 69 74 68 6f 75 74 20 61 20  mmand without a 
7aa0: 54 4f 20 63 6c 61 75 73 65 20 72 6f 6c 6c 73 20  TO clause rolls 
7ab0: 62 61 63 6b 73 20 61 6c 6c 20 74 72 61 6e 73 61  backs all transa
7ac0: 63 74 69 6f 6e 73 0a 61 6e 64 20 6c 65 61 76 65  ctions.and leave
7ad0: 73 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  s the transactio
7ae0: 6e 20 73 74 61 63 6b 20 65 6d 70 74 79 2e 3c 2f  n stack empty.</
7af0: 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 52 4f 4c 4c  p>..<p>^The ROLL
7b00: 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 77 69 74  BACK command wit
7b10: 68 20 61 20 54 4f 20 63 6c 61 75 73 65 20 72 6f  h a TO clause ro
7b20: 6c 6c 73 20 62 61 63 6b 20 74 72 61 6e 73 61 63  lls back transac
7b30: 74 69 6f 6e 73 20 67 6f 69 6e 67 0a 62 61 63 6b  tions going.back
7b40: 77 61 72 64 73 20 69 6e 20 74 69 6d 65 20 62 61  wards in time ba
7b50: 63 6b 20 74 6f 20 74 68 65 20 6d 6f 73 74 20 72  ck to the most r
7b60: 65 63 65 6e 74 20 53 41 56 45 50 4f 49 4e 54 20  ecent SAVEPOINT 
7b70: 77 69 74 68 20 61 20 6d 61 74 63 68 69 6e 67 20  with a matching 
7b80: 6e 61 6d 65 2e 0a 5e 54 68 65 20 53 41 56 45 50  name..^The SAVEP
7b90: 4f 49 4e 54 20 77 69 74 68 20 74 68 65 20 6d 61  OINT with the ma
7ba0: 74 63 68 69 6e 67 20 6e 61 6d 65 20 72 65 6d 61  tching name rema
7bb0: 69 6e 73 20 6f 6e 20 74 68 65 20 74 72 61 6e 73  ins on the trans
7bc0: 61 63 74 69 6f 6e 20 73 74 61 63 6b 2c 0a 62 75  action stack,.bu
7bd0: 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  t all database c
7be0: 68 61 6e 67 65 73 20 74 68 61 74 20 6f 63 63 75  hanges that occu
7bf0: 72 72 65 64 20 61 66 74 65 72 20 74 68 61 74 20  rred after that 
7c00: 53 41 56 45 50 4f 49 4e 54 20 77 61 73 20 63 72  SAVEPOINT was cr
7c10: 65 61 74 65 64 0a 61 72 65 20 72 6f 6c 6c 65 64  eated.are rolled
7c20: 20 62 61 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   back.  ^If the 
7c30: 73 61 76 65 70 6f 69 6e 74 2d 6e 61 6d 65 20 69  savepoint-name i
7c40: 6e 20 61 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20  n a ROLLBACK TO 
7c50: 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 20 6e 6f 74  command does not
7c60: 0a 6d 61 74 63 68 20 61 6e 79 20 53 41 56 45 50  .match any SAVEP
7c70: 4f 49 4e 54 20 6f 6e 20 74 68 65 20 73 74 61 63  OINT on the stac
7c80: 6b 2c 20 74 68 65 6e 20 74 68 65 20 52 4f 4c 4c  k, then the ROLL
7c90: 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 66 61 69  BACK command fai
7ca0: 6c 73 20 77 69 74 68 20 61 6e 0a 65 72 72 6f 72  ls with an.error
7cb0: 20 61 6e 64 20 6c 65 61 76 65 73 20 74 68 65 20   and leaves the 
7cc0: 73 74 61 74 65 20 6f 66 20 74 68 65 20 64 61 74  state of the dat
7cd0: 61 62 61 73 65 20 75 6e 63 68 61 6e 67 65 64 2e  abase unchanged.
7ce0: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  </p>..<tcl>.####
7cf0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7d00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7d10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7d20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
7d30: 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
7d40: 69 6f 6e 20 63 6f 6d 6d 65 6e 74 20 63 6f 6d 6d  ion comment comm
7d50: 65 6e 74 20 7b 63 6f 6d 6d 65 6e 74 20 2a 63 6f  ent {comment *co
7d60: 6d 6d 65 6e 74 73 7d 0a 0a 52 65 63 75 72 73 69  mments}..Recursi
7d70: 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
7d80: 63 6f 6d 6d 65 6e 74 2d 73 79 6e 74 61 78 0a 3c  comment-syntax.<
7d90: 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 43 6f 6d 6d 65  /tcl>..<p>^Comme
7da0: 6e 74 73 20 61 72 65 20 6e 6f 74 20 53 51 4c 20  nts are not SQL 
7db0: 63 6f 6d 6d 61 6e 64 73 2c 20 62 75 74 20 63 61  commands, but ca
7dc0: 6e 20 6f 63 63 75 72 20 77 69 74 68 69 6e 20 74  n occur within t
7dd0: 68 65 20 74 65 78 74 20 6f 66 0a 53 51 4c 20 71  he text of.SQL q
7de0: 75 65 72 69 65 73 20 70 61 73 73 65 64 20 74 6f  ueries passed to
7df0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
7e00: 65 5f 76 32 28 29 5d 20 61 6e 64 20 72 65 6c 61  e_v2()] and rela
7e10: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ted interfaces..
7e20: 5e 43 6f 6d 6d 65 6e 74 73 20 61 72 65 20 74 72  ^Comments are tr
7e30: 65 61 74 65 64 20 61 73 20 77 68 69 74 65 73 70  eated as whitesp
7e40: 61 63 65 20 62 79 20 74 68 65 20 70 61 72 73 65  ace by the parse
7e50: 72 2e 0a 5e 43 6f 6d 6d 65 6e 74 73 20 63 61 6e  r..^Comments can
7e60: 20 62 65 67 69 6e 20 61 6e 79 77 68 65 72 65 20   begin anywhere 
7e70: 77 68 69 74 65 73 70 61 63 65 20 0a 63 61 6e 20  whitespace .can 
7e80: 62 65 20 66 6f 75 6e 64 2c 20 69 6e 63 6c 75 64  be found, includ
7e90: 69 6e 67 20 69 6e 73 69 64 65 20 65 78 70 72 65  ing inside expre
7ea0: 73 73 69 6f 6e 73 20 74 68 61 74 20 73 70 61 6e  ssions that span
7eb0: 20 6d 75 6c 74 69 70 6c 65 20 6c 69 6e 65 73 2e   multiple lines.
7ec0: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e 53 51 4c 20 63  .</p>..<p>^SQL c
7ed0: 6f 6d 6d 65 6e 74 73 20 62 65 67 69 6e 20 77 69  omments begin wi
7ee0: 74 68 20 74 77 6f 20 63 6f 6e 73 65 63 75 74 69  th two consecuti
7ef0: 76 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  ve "-" character
7f00: 73 20 28 41 53 43 49 49 20 30 78 32 64 29 0a 61  s (ASCII 0x2d).a
7f10: 6e 64 20 65 78 74 65 6e 64 20 75 70 20 74 6f 20  nd extend up to 
7f20: 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  and including th
7f30: 65 20 6e 65 78 74 20 6e 65 77 6c 69 6e 65 20 63  e next newline c
7f40: 68 61 72 61 63 74 65 72 20 28 41 53 43 49 49 20  haracter (ASCII 
7f50: 30 78 30 61 29 0a 6f 72 20 75 6e 74 69 6c 20 74  0x0a).or until t
7f60: 68 65 20 65 6e 64 20 6f 66 20 69 6e 70 75 74 2c  he end of input,
7f70: 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
7f80: 20 66 69 72 73 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e   first.</p>..<p>
7f90: 5e 43 2d 73 74 79 6c 65 20 63 6f 6d 6d 65 6e 74  ^C-style comment
7fa0: 73 20 62 65 67 69 6e 0a 77 69 74 68 20 22 2f 2a  s begin.with "/*
7fb0: 22 20 61 6e 64 20 65 78 74 65 6e 64 20 75 70 20  " and extend up 
7fc0: 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
7fd0: 20 74 68 65 20 6e 65 78 74 20 22 2a 2f 22 20 63   the next "*/" c
7fe0: 68 61 72 61 63 74 65 72 20 70 61 69 72 0a 6f 72  haracter pair.or
7ff0: 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 64 20 6f   until the end o
8000: 66 20 69 6e 70 75 74 2c 20 77 68 69 63 68 65 76  f input, whichev
8010: 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
8020: 20 5e 43 2d 73 74 79 6c 65 20 63 6f 6d 6d 65 6e   ^C-style commen
8030: 74 73 0a 63 61 6e 20 73 70 61 6e 20 6d 75 6c 74  ts.can span mult
8040: 69 70 6c 65 20 6c 69 6e 65 73 2e 20 3c 2f 70 3e  iple lines. </p>
8050: 0a 0a 3c 70 3e 5e 43 6f 6d 6d 65 6e 74 73 20 63  ..<p>^Comments c
8060: 61 6e 20 61 70 70 65 61 72 20 61 6e 79 77 68 65  an appear anywhe
8070: 72 65 20 77 68 69 74 65 73 70 61 63 65 20 63 61  re whitespace ca
8080: 6e 20 6f 63 63 75 72 2c 0a 69 6e 63 6c 75 64 69  n occur,.includi
8090: 6e 67 20 69 6e 73 69 64 65 20 65 78 70 72 65 73  ng inside expres
80a0: 73 69 6f 6e 73 20 61 6e 64 20 69 6e 20 74 68 65  sions and in the
80b0: 20 6d 69 64 64 6c 65 20 6f 66 20 6f 74 68 65 72   middle of other
80c0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
80d0: 0a 5e 43 6f 6d 6d 65 6e 74 73 20 64 6f 20 6e 6f  .^Comments do no
80e0: 74 20 6e 65 73 74 2e 0a 3c 2f 70 3e 0a 0a 0a 3c  t nest..</p>...<
80f0: 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
8100: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8110: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8120: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8130: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8140: 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45  ###.Section {CRE
8150: 41 54 45 20 49 4e 44 45 58 7d 20 63 72 65 61 74  ATE INDEX} creat
8160: 65 69 6e 64 65 78 20 7b 7b 43 52 45 41 54 45 20  eindex {{CREATE 
8170: 49 4e 44 45 58 7d 7d 0a 0a 52 65 63 75 72 73 69  INDEX}}..Recursi
8180: 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
8190: 63 72 65 61 74 65 2d 69 6e 64 65 78 2d 73 74 6d  create-index-stm
81a0: 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68  t.</tcl>..<p>^Th
81b0: 65 20 43 52 45 41 54 45 20 49 4e 44 45 58 20 63  e CREATE INDEX c
81c0: 6f 6d 6d 61 6e 64 20 63 6f 6e 73 69 73 74 73 20  ommand consists 
81d0: 6f 66 20 74 68 65 20 6b 65 79 77 6f 72 64 73 20  of the keywords 
81e0: 22 43 52 45 41 54 45 20 49 4e 44 45 58 22 20 66  "CREATE INDEX" f
81f0: 6f 6c 6c 6f 77 65 64 0a 62 79 20 74 68 65 20 6e  ollowed.by the n
8200: 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 69  ame of the new i
8210: 6e 64 65 78 2c 20 74 68 65 20 6b 65 79 77 6f 72  ndex, the keywor
8220: 64 20 22 4f 4e 22 2c 20 74 68 65 20 6e 61 6d 65  d "ON", the name
8230: 20 6f 66 20 61 20 70 72 65 76 69 6f 75 73 6c 79   of a previously
8240: 0a 63 72 65 61 74 65 64 20 74 61 62 6c 65 20 74  .created table t
8250: 68 61 74 20 69 73 20 74 6f 20 62 65 20 69 6e 64  hat is to be ind
8260: 65 78 65 64 2c 20 61 6e 64 20 61 20 70 61 72 65  exed, and a pare
8270: 6e 74 68 65 73 69 7a 65 64 20 6c 69 73 74 20 6f  nthesized list o
8280: 66 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 0a 6e  f table column.n
8290: 61 6d 65 73 20 61 6e 64 2f 6f 72 20 65 78 70 72  ames and/or expr
82a0: 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
82b0: 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 69 6e   used for the in
82c0: 64 65 78 20 6b 65 79 2e 0a 49 66 20 74 68 65 20  dex key..If the 
82d0: 6f 70 74 69 6f 6e 61 6c 20 57 48 45 52 45 20 63  optional WHERE c
82e0: 6c 61 75 73 65 20 69 73 20 69 6e 63 6c 75 64 65  lause is include
82f0: 64 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 64 65  d, then the inde
8300: 78 20 69 73 20 61 20 22 5b 70 61 72 74 69 61 6c  x is a "[partial
8310: 20 69 6e 64 65 78 5d 22 2e 0a 3c 2f 70 3e 0a 0a   index]"..</p>..
8320: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
8330: 20 7b 64 65 73 63 69 64 78 7d 20 7b 64 65 73 63   {descidx} {desc
8340: 65 6e 64 69 6e 67 20 69 6e 64 69 63 65 73 7d 20  ending indices} 
8350: 7b 64 65 73 63 65 6e 64 69 6e 67 20 69 6e 64 65  {descending inde
8360: 78 7d 20 5c 0a 20 20 20 20 7b 64 65 73 63 65 6e  x} \.    {descen
8370: 64 69 6e 67 20 69 6e 64 65 78 65 73 7d 20 7b 44  ding indexes} {D
8380: 45 53 43 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 45  ESC}</tcl>.<p>^E
8390: 61 63 68 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20  ach column name 
83a0: 6f 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  or expression ca
83b0: 6e 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79  n be followed by
83c0: 20 6f 6e 65 0a 6f 66 20 74 68 65 20 22 41 53 43   one.of the "ASC
83d0: 22 20 6f 72 20 22 44 45 53 43 22 20 6b 65 79 77  " or "DESC" keyw
83e0: 6f 72 64 73 20 74 6f 20 69 6e 64 69 63 61 74 65  ords to indicate
83f0: 20 73 6f 72 74 20 6f 72 64 65 72 2e 0a 5e 54 68   sort order..^Th
8400: 65 20 73 6f 72 74 20 6f 72 64 65 72 20 6d 61 79  e sort order may
8410: 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 69   or may not be i
8420: 67 6e 6f 72 65 64 20 64 65 70 65 6e 64 69 6e 67  gnored depending
8430: 0a 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  .on the database
8440: 20 66 69 6c 65 20 66 6f 72 6d 61 74 2c 20 61 6e   file format, an
8450: 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
8460: 74 68 65 20 5b 73 63 68 65 6d 61 20 66 6f 72 6d  the [schema form
8470: 61 74 20 6e 75 6d 62 65 72 5d 2e 0a 5e 54 68 65  at number]..^The
8480: 20 22 6c 65 67 61 63 79 22 20 73 63 68 65 6d 61   "legacy" schema
8490: 20 66 6f 72 6d 61 74 20 28 31 29 20 69 67 6e 6f   format (1) igno
84a0: 72 65 73 20 69 6e 64 65 78 0a 73 6f 72 74 20 6f  res index.sort o
84b0: 72 64 65 72 2e 20 20 5e 54 68 65 20 64 65 73 63  rder.  ^The desc
84c0: 65 6e 64 69 6e 67 20 69 6e 64 65 78 20 73 63 68  ending index sch
84d0: 65 6d 61 20 66 6f 72 6d 61 74 20 28 34 29 20 74  ema format (4) t
84e0: 61 6b 65 73 20 69 6e 64 65 78 20 73 6f 72 74 20  akes index sort 
84f0: 6f 72 64 65 72 0a 69 6e 74 6f 20 61 63 63 6f 75  order.into accou
8500: 6e 74 2e 20 20 4f 6e 6c 79 20 76 65 72 73 69 6f  nt.  Only versio
8510: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 33 2e 33  ns of SQLite 3.3
8520: 2e 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 33 2e  .0 ([dateof:3.3.
8530: 30 5d 29 0a 61 6e 64 20 6c 61 74 65 72 20 61 72  0]).and later ar
8540: 65 20 61 62 6c 65 20 74 6f 20 75 6e 64 65 72 73  e able to unders
8550: 74 61 6e 64 0a 74 68 65 20 64 65 73 63 65 6e 64  tand.the descend
8560: 69 6e 67 20 69 6e 64 65 78 20 66 6f 72 6d 61 74  ing index format
8570: 2e 20 46 6f 72 20 63 6f 6d 70 61 74 69 62 69 6c  . For compatibil
8580: 69 74 79 2c 20 76 65 72 73 69 6f 6e 20 6f 66 20  ity, version of 
8590: 53 51 4c 69 74 65 20 62 65 74 77 65 65 6e 20 33  SQLite between 3
85a0: 2e 33 2e 30 0a 61 6e 64 20 33 2e 37 2e 39 20 75  .3.0.and 3.7.9 u
85b0: 73 65 20 74 68 65 20 6c 65 67 61 63 79 20 73 63  se the legacy sc
85c0: 68 65 6d 61 20 66 6f 72 6d 61 74 20 62 79 20 64  hema format by d
85d0: 65 66 61 75 6c 74 2e 20 20 54 68 65 20 6e 65 77  efault.  The new
85e0: 65 72 20 73 63 68 65 6d 61 20 66 6f 72 6d 61 74  er schema format
85f0: 20 69 73 0a 75 73 65 64 20 62 79 20 64 65 66 61   is.used by defa
8600: 75 6c 74 20 69 6e 20 76 65 72 73 69 6f 6e 20 33  ult in version 3
8610: 2e 37 2e 31 30 20 28 5b 64 61 74 65 6f 66 3a 33  .7.10 ([dateof:3
8620: 2e 37 2e 31 30 5d 29 20 61 6e 64 20 6c 61 74 65  .7.10]) and late
8630: 72 2e 0a 5e 54 68 65 20 5b 6c 65 67 61 63 79 5f  r..^The [legacy_
8640: 66 69 6c 65 5f 66 6f 72 6d 61 74 20 70 72 61 67  file_format prag
8650: 6d 61 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ma] can be used 
8660: 74 6f 20 63 68 61 6e 67 65 20 73 65 74 20 74 68  to change set th
8670: 65 20 73 70 65 63 69 66 69 63 0a 62 65 68 61 76  e specific.behav
8680: 69 6f 72 20 66 6f 72 20 61 6e 79 20 76 65 72 73  ior for any vers
8690: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 3c 2f  ion of SQLite.</
86a0: 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  p>..<tcl>hd_frag
86b0: 6d 65 6e 74 20 63 6f 6c 6c 69 64 78 20 7b 43 4f  ment collidx {CO
86c0: 4c 4c 41 54 45 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e  LLATE}</tcl>.<p>
86d0: 5e 54 68 65 20 43 4f 4c 4c 41 54 45 20 63 6c 61  ^The COLLATE cla
86e0: 75 73 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66  use optionally f
86f0: 6f 6c 6c 6f 77 69 6e 67 20 65 61 63 68 20 63 6f  ollowing each co
8700: 6c 75 6d 6e 20 6e 61 6d 65 0a 6f 72 20 65 78 70  lumn name.or exp
8710: 72 65 73 73 69 6f 6e 20 64 65 66 69 6e 65 73 20  ression defines 
8720: 61 0a 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  a.collating sequ
8730: 65 6e 63 65 20 75 73 65 64 20 66 6f 72 20 74 65  ence used for te
8740: 78 74 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68  xt entries in th
8750: 61 74 20 63 6f 6c 75 6d 6e 2e 0a 5e 54 68 65 20  at column..^The 
8760: 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6e  default collatin
8770: 67 0a 73 65 71 75 65 6e 63 65 20 69 73 20 74 68  g.sequence is th
8780: 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  e collating sequ
8790: 65 6e 63 65 20 64 65 66 69 6e 65 64 20 66 6f 72  ence defined for
87a0: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 6e 20   that column in 
87b0: 74 68 65 0a 5b 43 52 45 41 54 45 20 54 41 42 4c  the.[CREATE TABL
87c0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  E] statement.  ^
87d0: 4f 72 20 69 66 20 6e 6f 20 63 6f 6c 6c 61 74 69  Or if no collati
87e0: 6e 67 20 73 65 71 75 65 6e 63 65 20 69 73 20 6f  ng sequence is o
87f0: 74 68 65 72 77 69 73 65 20 64 65 66 69 6e 65 64  therwise defined
8800: 2c 0a 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 42  ,.the built-in B
8810: 49 4e 41 52 59 20 63 6f 6c 6c 61 74 69 6e 67 20  INARY collating 
8820: 73 65 71 75 65 6e 63 65 20 69 73 20 75 73 65 64  sequence is used
8830: 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
8840: 72 61 67 6d 65 6e 74 20 69 6e 64 65 78 65 78 70  ragment indexexp
8850: 72 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 45 78 70 72  r</tcl>.<p>^Expr
8860: 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e 20 69 6e  essions in an in
8870: 64 65 78 20 6d 61 79 20 6e 6f 74 20 72 65 66 65  dex may not refe
8880: 72 65 6e 63 65 20 6f 74 68 65 72 20 74 61 62 6c  rence other tabl
8890: 65 73 0a 61 6e 64 20 6d 61 79 20 6e 6f 74 20 75  es.and may not u
88a0: 73 65 20 73 75 62 71 75 65 72 69 65 73 20 6e 6f  se subqueries no
88b0: 72 20 66 75 6e 63 74 69 6f 6e 73 20 77 68 6f 73  r functions whos
88c0: 65 20 72 65 73 75 6c 74 20 6d 69 67 68 74 0a 63  e result might.c
88d0: 68 61 6e 67 65 20 28 65 78 3a 20 5b 72 61 6e 64  hange (ex: [rand
88e0: 6f 6d 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  om()] or [sqlite
88f0: 5f 76 65 72 73 69 6f 6e 28 29 5d 29 2e 0a 5e 45  _version()])..^E
8900: 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e  xpressions in an
8910: 20 69 6e 64 65 78 20 6d 61 79 20 6f 6e 6c 79 20   index may only 
8920: 72 65 66 65 72 20 74 6f 20 63 6f 6c 75 6d 6e 73  refer to columns
8930: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 0a 74 68   in the table.th
8940: 61 74 20 69 73 20 62 65 69 6e 67 20 69 6e 64 65  at is being inde
8950: 78 65 64 2e 0a 49 6e 64 65 78 65 73 20 6f 6e 20  xed..Indexes on 
8960: 65 78 70 72 65 73 73 69 6f 6e 20 77 69 6c 6c 20  expression will 
8970: 6e 6f 74 20 77 6f 72 6b 20 77 69 74 68 20 76 65  not work with ve
8980: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
8990: 20 70 72 69 6f 72 0a 74 6f 20 5b 76 65 72 73 69   prior.to [versi
89a0: 6f 6e 20 33 2e 39 2e 30 5d 20 28 5b 64 61 74 65  on 3.9.0] ([date
89b0: 6f 66 3a 33 2e 39 2e 30 5d 29 2e 0a 53 65 65 20  of:3.9.0])..See 
89c0: 74 68 65 20 5b 49 6e 64 65 78 65 73 20 4f 6e 20  the [Indexes On 
89d0: 45 78 70 72 65 73 73 69 6f 6e 73 5d 20 64 6f 63  Expressions] doc
89e0: 75 6d 65 6e 74 20 66 6f 72 20 61 64 64 69 74 69  ument for additi
89f0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8a00: 0a 61 62 6f 75 74 20 75 73 69 6e 67 20 67 65 6e  .about using gen
8a10: 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 73  eral expressions
8a20: 20 69 6e 20 43 52 45 41 54 45 20 49 4e 44 45 58   in CREATE INDEX
8a30: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 0a 3c 70   statements...<p
8a40: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
8a50: 62 69 74 72 61 72 79 20 6c 69 6d 69 74 73 20 6f  bitrary limits o
8a60: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
8a70: 69 6e 64 69 63 65 73 20 74 68 61 74 20 63 61 6e  indices that can
8a80: 20 62 65 0a 61 74 74 61 63 68 65 64 20 74 6f 20   be.attached to 
8a90: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 2e 20  a single table. 
8aa0: 20 5e 28 54 68 65 20 6e 75 6d 62 65 72 20 6f 66   ^(The number of
8ab0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
8ac0: 6e 64 65 78 20 69 73 20 0a 6c 69 6d 69 74 65 64  ndex is .limited
8ad0: 20 74 6f 20 74 68 65 20 76 61 6c 75 65 20 73 65   to the value se
8ae0: 74 20 62 79 0a 5b 73 71 6c 69 74 65 33 5f 6c 69  t by.[sqlite3_li
8af0: 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
8b00: 49 54 5f 43 4f 4c 55 4d 4e 5d 2c 2e 2e 2e 29 2e  IT_COLUMN],...).
8b10: 29 5e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  )^</p>..<tcl>hd_
8b20: 66 72 61 67 6d 65 6e 74 20 75 6e 69 71 75 65 69  fragment uniquei
8b30: 64 78 20 7b 75 6e 69 71 75 65 20 69 6e 64 65 78  dx {unique index
8b40: 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 49 66 20 74  }</tcl>.<p>^If t
8b50: 68 65 20 55 4e 49 51 55 45 20 6b 65 79 77 6f 72  he UNIQUE keywor
8b60: 64 20 61 70 70 65 61 72 73 20 62 65 74 77 65 65  d appears betwee
8b70: 6e 20 43 52 45 41 54 45 20 61 6e 64 20 49 4e 44  n CREATE and IND
8b80: 45 58 20 74 68 65 6e 20 64 75 70 6c 69 63 61 74  EX then duplicat
8b90: 65 0a 69 6e 64 65 78 20 65 6e 74 72 69 65 73 20  e.index entries 
8ba0: 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 2e  are not allowed.
8bb0: 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74    ^Any attempt t
8bc0: 6f 20 69 6e 73 65 72 74 20 61 20 64 75 70 6c 69  o insert a dupli
8bd0: 63 61 74 65 20 65 6e 74 72 79 0a 77 69 6c 6c 20  cate entry.will 
8be0: 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 65 72 72  result in an err
8bf0: 6f 72 2e 20 20 5e 46 6f 72 20 74 68 65 20 70 75  or.  ^For the pu
8c00: 72 70 6f 73 65 73 20 6f 66 20 75 6e 69 71 75 65  rposes of unique
8c10: 20 69 6e 64 69 63 65 73 2c 20 61 6c 6c 20 4e 55   indices, all NU
8c20: 4c 4c 20 76 61 6c 75 65 73 0a 61 72 65 20 63 6f  LL values.are co
8c30: 6e 73 69 64 65 72 65 64 20 74 6f 20 64 69 66 66  nsidered to diff
8c40: 65 72 65 6e 74 20 66 72 6f 6d 20 61 6c 6c 20 6f  erent from all o
8c50: 74 68 65 72 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ther NULL values
8c60: 20 61 6e 64 20 61 72 65 20 74 68 75 73 20 75 6e   and are thus un
8c70: 69 71 75 65 2e 0a 54 68 69 73 20 69 73 20 6f 6e  ique..This is on
8c80: 65 20 6f 66 20 74 68 65 20 74 77 6f 20 70 6f 73  e of the two pos
8c90: 73 69 62 6c 65 20 69 6e 74 65 72 70 72 65 74 61  sible interpreta
8ca0: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 53 51 4c  tions of the SQL
8cb0: 2d 39 32 20 73 74 61 6e 64 61 72 64 0a 28 74 68  -92 standard.(th
8cc0: 65 20 6c 61 6e 67 75 61 67 65 20 69 6e 20 74 68  e language in th
8cd0: 65 20 73 74 61 6e 64 61 72 64 20 69 73 20 61 6d  e standard is am
8ce0: 62 69 67 75 6f 75 73 29 20 61 6e 64 20 69 73 20  biguous) and is 
8cf0: 74 68 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  the interpretati
8d00: 6f 6e 0a 66 6f 6c 6c 6f 77 65 64 20 62 79 20 50  on.followed by P
8d10: 6f 73 74 67 72 65 53 51 4c 2c 20 4d 79 53 51 4c  ostgreSQL, MySQL
8d20: 2c 20 46 69 72 65 62 69 72 64 2c 20 61 6e 64 20  , Firebird, and 
8d30: 4f 72 61 63 6c 65 2e 20 20 49 6e 66 6f 72 6d 69  Oracle.  Informi
8d40: 78 20 61 6e 64 0a 4d 69 63 72 6f 73 6f 66 74 20  x and.Microsoft 
8d50: 53 51 4c 20 53 65 72 76 65 72 20 66 6f 6c 6c 6f  SQL Server follo
8d60: 77 20 74 68 65 20 6f 74 68 65 72 20 69 6e 74 65  w the other inte
8d70: 72 70 72 65 74 61 74 69 6f 6e 20 6f 66 20 74 68  rpretation of th
8d80: 65 20 73 74 61 6e 64 61 72 64 2e 3c 2f 70 3e 0a  e standard.</p>.
8d90: 0a 3c 70 3e 5e 49 66 20 74 68 65 20 6f 70 74 69  .<p>^If the opti
8da0: 6f 6e 61 6c 20 49 46 20 4e 4f 54 20 45 58 49 53  onal IF NOT EXIS
8db0: 54 53 20 63 6c 61 75 73 65 20 69 73 20 70 72 65  TS clause is pre
8dc0: 73 65 6e 74 20 61 6e 64 20 61 6e 6f 74 68 65 72  sent and another
8dd0: 20 69 6e 64 65 78 0a 77 69 74 68 20 74 68 65 20   index.with the 
8de0: 73 61 6d 65 20 6e 61 6d 65 20 61 6c 72 65 61 64  same name alread
8df0: 79 20 65 78 69 73 74 73 2c 20 74 68 65 6e 20 74  y exists, then t
8e00: 68 69 73 20 63 6f 6d 6d 61 6e 64 20 62 65 63 6f  his command beco
8e10: 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 3c 2f 70 3e  mes a no-op.</p>
8e20: 0a 0a 3c 70 3e 5e 49 6e 64 65 78 65 73 20 61 72  ..<p>^Indexes ar
8e30: 65 20 72 65 6d 6f 76 65 64 20 77 69 74 68 20 74  e removed with t
8e40: 68 65 20 5b 44 52 4f 50 20 49 4e 44 45 58 5d 20  he [DROP INDEX] 
8e50: 63 6f 6d 6d 61 6e 64 2e 3c 2f 70 3e 0a 0a 0a 3c  command.</p>...<
8e60: 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
8e70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8e80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8e90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8ea0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8eb0: 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45  ###.Section {CRE
8ec0: 41 54 45 20 54 41 42 4c 45 7d 20 7b 63 72 65 61  ATE TABLE} {crea
8ed0: 74 65 74 61 62 6c 65 7d 20 7b 7b 43 52 45 41 54  tetable} {{CREAT
8ee0: 45 20 54 41 42 4c 45 7d 7d 0a 0a 52 65 63 75 72  E TABLE}}..Recur
8ef0: 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61  siveBubbleDiagra
8f00: 6d 20 63 72 65 61 74 65 2d 74 61 62 6c 65 2d 73  m create-table-s
8f10: 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54  tmt.</tcl>..<p>T
8f20: 68 65 20 22 43 52 45 41 54 45 20 54 41 42 4c 45  he "CREATE TABLE
8f30: 22 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65  " command is use
8f40: 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65  d to create a ne
8f50: 77 20 74 61 62 6c 65 20 69 6e 20 61 6e 20 53 51  w table in an SQ
8f60: 4c 69 74 65 20 0a 64 61 74 61 62 61 73 65 2e 20  Lite .database. 
8f70: 41 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 63  A CREATE TABLE c
8f80: 6f 6d 6d 61 6e 64 20 73 70 65 63 69 66 69 65 73  ommand specifies
8f90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61   the following a
8fa0: 74 74 72 69 62 75 74 65 73 20 6f 66 20 74 68 65  ttributes of the
8fb0: 0a 6e 65 77 20 74 61 62 6c 65 3a 0a 0a 3c 75 6c  .new table:..<ul
8fc0: 3e 0a 20 20 3c 6c 69 3e 3c 70 3e 54 68 65 20 6e  >.  <li><p>The n
8fd0: 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 74  ame of the new t
8fe0: 61 62 6c 65 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e  able...  <li><p>
8ff0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   The database in
9000: 20 77 68 69 63 68 20 74 68 65 20 6e 65 77 20 74   which the new t
9010: 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64 2e  able is created.
9020: 20 54 61 62 6c 65 73 20 6d 61 79 20 62 65 20 0a   Tables may be .
9030: 20 20 20 20 20 20 63 72 65 61 74 65 64 20 69 6e        created in
9040: 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
9050: 73 65 2c 20 74 68 65 20 74 65 6d 70 20 64 61 74  se, the temp dat
9060: 61 62 61 73 65 2c 20 6f 72 20 69 6e 20 61 6e 79  abase, or in any
9070: 20 61 74 74 61 63 68 65 64 0a 20 20 20 20 20 20   attached.      
9080: 64 61 74 61 62 61 73 65 2e 0a 0a 20 20 3c 6c 69  database...  <li
9090: 3e 3c 70 3e 20 54 68 65 20 6e 61 6d 65 20 6f 66  ><p> The name of
90a0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20   each column in 
90b0: 74 68 65 20 74 61 62 6c 65 2e 0a 0a 20 20 3c 6c  the table...  <l
90c0: 69 3e 3c 70 3e 20 54 68 65 20 64 65 63 6c 61 72  i><p> The declar
90d0: 65 64 20 74 79 70 65 20 6f 66 20 65 61 63 68 20  ed type of each 
90e0: 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 74 61  column in the ta
90f0: 62 6c 65 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20  ble...  <li><p> 
9100: 41 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  A default value 
9110: 6f 72 20 65 78 70 72 65 73 73 69 6f 6e 20 66 6f  or expression fo
9120: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
9130: 20 74 68 65 20 74 61 62 6c 65 2e 0a 0a 20 20 3c   the table...  <
9140: 6c 69 3e 3c 70 3e 20 41 20 64 65 66 61 75 6c 74  li><p> A default
9150: 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
9160: 6e 63 65 20 74 6f 20 75 73 65 20 77 69 74 68 20  nce to use with 
9170: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 0a 20 20  each column...  
9180: 3c 6c 69 3e 3c 70 3e 20 4f 70 74 69 6f 6e 61 6c  <li><p> Optional
9190: 6c 79 2c 20 61 20 50 52 49 4d 41 52 59 20 4b 45  ly, a PRIMARY KE
91a0: 59 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 2e  Y for the table.
91b0: 20 42 6f 74 68 20 73 69 6e 67 6c 65 20 63 6f 6c   Both single col
91c0: 75 6d 6e 20 61 6e 64 0a 20 20 20 20 20 20 20 63  umn and.       c
91d0: 6f 6d 70 6f 73 69 74 65 20 28 6d 75 6c 74 69 70  omposite (multip
91e0: 6c 65 20 63 6f 6c 75 6d 6e 29 20 70 72 69 6d 61  le column) prima
91f0: 72 79 20 6b 65 79 73 20 61 72 65 20 73 75 70 70  ry keys are supp
9200: 6f 72 74 65 64 2e 0a 0a 20 20 3c 6c 69 3e 3c 70  orted...  <li><p
9210: 3e 20 41 20 73 65 74 20 6f 66 20 53 51 4c 20 63  > A set of SQL c
9220: 6f 6e 73 74 72 61 69 6e 74 73 20 66 6f 72 20 65  onstraints for e
9230: 61 63 68 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ach table. SQLit
9240: 65 20 73 75 70 70 6f 72 74 73 20 55 4e 49 51 55  e supports UNIQU
9250: 45 2c 20 4e 4f 54 0a 20 20 20 20 20 20 20 4e 55  E, NOT.       NU
9260: 4c 4c 2c 20 43 48 45 43 4b 20 61 6e 64 20 46 4f  LL, CHECK and FO
9270: 52 45 49 47 4e 20 4b 45 59 20 63 6f 6e 73 74 72  REIGN KEY constr
9280: 61 69 6e 74 73 2e 0a 0a 20 20 3c 6c 69 3e 3c 70  aints...  <li><p
9290: 3e 20 57 68 65 74 68 65 72 20 74 68 65 20 74 61  > Whether the ta
92a0: 62 6c 65 20 69 73 20 61 20 5b 57 49 54 48 4f 55  ble is a [WITHOU
92b0: 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 2e 0a  T ROWID] table..
92c0: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 45 76 65 72 79 20  </ul>..<p>Every 
92d0: 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74 61  CREATE TABLE sta
92e0: 74 65 6d 65 6e 74 20 6d 75 73 74 20 73 70 65 63  tement must spec
92f0: 69 66 79 20 61 20 6e 61 6d 65 20 66 6f 72 20 74  ify a name for t
9300: 68 65 20 6e 65 77 20 74 61 62 6c 65 2e 0a 20 20  he new table..  
9310: 5e 28 54 61 62 6c 65 20 6e 61 6d 65 73 20 74 68  ^(Table names th
9320: 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 22 73  at begin with "s
9330: 71 6c 69 74 65 5f 22 20 61 72 65 20 72 65 73 65  qlite_" are rese
9340: 72 76 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  rved for interna
9350: 6c 20 75 73 65 2e 20 49 74 0a 20 20 69 73 20 61  l use. It.  is a
9360: 6e 20 65 72 72 6f 72 20 74 6f 20 61 74 74 65 6d  n error to attem
9370: 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 74  pt to create a t
9380: 61 62 6c 65 20 77 69 74 68 20 61 20 6e 61 6d 65  able with a name
9390: 20 74 68 61 74 20 73 74 61 72 74 73 20 77 69 74   that starts wit
93a0: 68 0a 20 20 22 73 71 6c 69 74 65 5f 22 2e 29 5e  h.  "sqlite_".)^
93b0: 0a 0a 3c 70 3e 20 5e 49 66 20 61 20 3c 79 79 74  ..<p> ^If a <yyt
93c0: 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c  erm>schema-name<
93d0: 2f 79 79 74 65 72 6d 3e 20 69 73 20 73 70 65 63  /yyterm> is spec
93e0: 69 66 69 65 64 2c 20 69 74 20 6d 75 73 74 20 62  ified, it must b
93f0: 65 20 65 69 74 68 65 72 20 22 6d 61 69 6e 22 2c  e either "main",
9400: 20 0a 20 20 22 74 65 6d 70 22 2c 20 6f 72 20 74   .  "temp", or t
9410: 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 20 5b 41  he name of an [A
9420: 54 54 41 43 48 20 44 41 54 41 42 41 53 45 7c 61  TTACH DATABASE|a
9430: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
9440: 5d 2e 20 5e 49 6e 20 74 68 69 73 20 63 61 73 65  ]. ^In this case
9450: 0a 20 20 74 68 65 20 6e 65 77 20 74 61 62 6c 65  .  the new table
9460: 20 69 73 20 63 72 65 61 74 65 64 20 69 6e 20 74   is created in t
9470: 68 65 20 6e 61 6d 65 64 20 64 61 74 61 62 61 73  he named databas
9480: 65 2e 20 5e 49 66 20 74 68 65 20 22 54 45 4d 50  e. ^If the "TEMP
9490: 22 20 6f 72 20 22 54 45 4d 50 4f 52 41 52 59 22  " or "TEMPORARY"
94a0: 0a 20 20 6b 65 79 77 6f 72 64 20 6f 63 63 75 72  .  keyword occur
94b0: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 22 43  s between the "C
94c0: 52 45 41 54 45 22 20 61 6e 64 20 22 54 41 42 4c  REATE" and "TABL
94d0: 45 22 20 74 68 65 6e 20 74 68 65 20 6e 65 77 20  E" then the new 
94e0: 74 61 62 6c 65 20 69 73 0a 20 20 63 72 65 61 74  table is.  creat
94f0: 65 64 20 69 6e 20 74 68 65 20 74 65 6d 70 20 64  ed in the temp d
9500: 61 74 61 62 61 73 65 2e 20 5e 49 74 20 69 73 20  atabase. ^It is 
9510: 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
9520: 69 66 79 20 62 6f 74 68 20 61 20 0a 20 20 3c 79  ify both a .  <y
9530: 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d  yterm>schema-nam
9540: 65 3c 2f 79 79 74 65 72 6d 3e 20 61 6e 64 20 74  e</yyterm> and t
9550: 68 65 20 54 45 4d 50 20 6f 72 20 54 45 4d 50 4f  he TEMP or TEMPO
9560: 52 41 52 59 20 6b 65 79 77 6f 72 64 2c 20 75 6e  RARY keyword, un
9570: 6c 65 73 73 20 74 68 65 0a 20 20 3c 79 79 74 65  less the.  <yyte
9580: 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f  rm>schema-name</
9590: 79 79 74 65 72 6d 3e 20 69 73 20 22 74 65 6d 70  yyterm> is "temp
95a0: 22 2e 20 0a 20 20 5e 49 66 20 6e 6f 20 73 63 68  ". .  ^If no sch
95b0: 65 6d 61 20 6e 61 6d 65 20 69 73 20 73 70 65 63  ema name is spec
95c0: 69 66 69 65 64 20 61 6e 64 20 74 68 65 0a 20 20  ified and the.  
95d0: 54 45 4d 50 20 6b 65 79 77 6f 72 64 20 69 73 20  TEMP keyword is 
95e0: 6e 6f 74 20 70 72 65 73 65 6e 74 20 74 68 65 6e  not present then
95f0: 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 63 72   the table is cr
9600: 65 61 74 65 64 20 69 6e 20 74 68 65 20 6d 61 69  eated in the mai
9610: 6e 0a 20 20 64 61 74 61 62 61 73 65 2e 0a 0a 3c  n.  database...<
9620: 70 3e 0a 20 20 5e 49 74 20 69 73 20 75 73 75 61  p>.  ^It is usua
9630: 6c 6c 79 20 61 6e 20 65 72 72 6f 72 20 74 6f 20  lly an error to 
9640: 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
9650: 65 20 61 20 6e 65 77 20 74 61 62 6c 65 20 69 6e  e a new table in
9660: 20 61 20 64 61 74 61 62 61 73 65 20 74 68 61 74   a database that
9670: 0a 20 20 61 6c 72 65 61 64 79 20 63 6f 6e 74 61  .  already conta
9680: 69 6e 73 20 61 20 74 61 62 6c 65 2c 20 69 6e 64  ins a table, ind
9690: 65 78 20 6f 72 20 76 69 65 77 20 6f 66 20 74 68  ex or view of th
96a0: 65 20 73 61 6d 65 20 6e 61 6d 65 2e 20 5e 48 6f  e same name. ^Ho
96b0: 77 65 76 65 72 2c 20 69 66 20 74 68 65 0a 20 20  wever, if the.  
96c0: 22 49 46 20 4e 4f 54 20 45 58 49 53 54 53 22 20  "IF NOT EXISTS" 
96d0: 63 6c 61 75 73 65 20 69 73 20 73 70 65 63 69 66  clause is specif
96e0: 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ied as part of t
96f0: 68 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  he CREATE TABLE 
9700: 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 0a 20 20  statement and.  
9710: 61 20 74 61 62 6c 65 20 6f 72 20 76 69 65 77 20  a table or view 
9720: 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  of the same name
9730: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2c   already exists,
9740: 20 74 68 65 20 43 52 45 41 54 45 20 54 41 42 4c   the CREATE TABL
9750: 45 20 63 6f 6d 6d 61 6e 64 0a 20 20 73 69 6d 70  E command.  simp
9760: 6c 79 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  ly has no effect
9770: 20 28 61 6e 64 20 6e 6f 20 65 72 72 6f 72 20 6d   (and no error m
9780: 65 73 73 61 67 65 20 69 73 20 72 65 74 75 72 6e  essage is return
9790: 65 64 29 2e 20 5e 41 6e 20 65 72 72 6f 72 20 69  ed). ^An error i
97a0: 73 20 73 74 69 6c 6c 0a 20 20 72 65 74 75 72 6e  s still.  return
97b0: 65 64 20 69 66 20 74 68 65 20 74 61 62 6c 65 20  ed if the table 
97c0: 63 61 6e 6e 6f 74 20 62 65 20 63 72 65 61 74 65  cannot be create
97d0: 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 20  d because of an 
97e0: 65 78 69 73 74 69 6e 67 20 69 6e 64 65 78 2c 20  existing index, 
97f0: 65 76 65 6e 20 0a 20 20 69 66 20 74 68 65 20 22  even .  if the "
9800: 49 46 20 4e 4f 54 20 45 58 49 53 54 53 22 20 63  IF NOT EXISTS" c
9810: 6c 61 75 73 65 20 69 73 20 73 70 65 63 69 66 69  lause is specifi
9820: 65 64 2e 0a 0a 3c 70 3e 5e 49 74 20 69 73 20 6e  ed...<p>^It is n
9830: 6f 74 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 63  ot an error to c
9840: 72 65 61 74 65 20 61 20 74 61 62 6c 65 20 74 68  reate a table th
9850: 61 74 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  at has the same 
9860: 6e 61 6d 65 20 61 73 20 61 6e 20 0a 20 20 65 78  name as an .  ex
9870: 69 73 74 69 6e 67 20 5b 43 52 45 41 54 45 20 54  isting [CREATE T
9880: 52 49 47 47 45 52 7c 74 72 69 67 67 65 72 5d 2e  RIGGER|trigger].
9890: 0a 0a 3c 70 3e 5e 54 61 62 6c 65 73 20 61 72 65  ..<p>^Tables are
98a0: 20 72 65 6d 6f 76 65 64 20 75 73 69 6e 67 20 74   removed using t
98b0: 68 65 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  he [DROP TABLE] 
98c0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 3c 2f 70 3e  statement.  </p>
98d0: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
98e0: 6e 74 20 63 72 65 61 74 65 74 61 62 61 73 20 7b  nt createtabas {
98f0: 43 52 45 41 54 45 20 54 41 42 4c 45 20 41 53 7d  CREATE TABLE AS}
9900: 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 43 52 45 41 54  </tcl>.<h3>CREAT
9910: 45 20 54 41 42 4c 45 20 2e 2e 2e 20 41 53 20 53  E TABLE ... AS S
9920: 45 4c 45 43 54 20 53 74 61 74 65 6d 65 6e 74 73  ELECT Statements
9930: 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 41 20 22 43  </h3>..<p>^(A "C
9940: 52 45 41 54 45 20 54 41 42 4c 45 20 2e 2e 2e 20  REATE TABLE ... 
9950: 41 53 20 53 45 4c 45 43 54 22 20 73 74 61 74 65  AS SELECT" state
9960: 6d 65 6e 74 20 63 72 65 61 74 65 73 20 61 6e 64  ment creates and
9970: 20 70 6f 70 75 6c 61 74 65 73 20 61 20 64 61 74   populates a dat
9980: 61 62 61 73 65 0a 74 61 62 6c 65 20 62 61 73 65  abase.table base
9990: 64 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 73  d on the results
99a0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
99b0: 74 65 6d 65 6e 74 2e 29 5e 20 5e 28 54 68 65 20  tement.)^ ^(The 
99c0: 74 61 62 6c 65 20 68 61 73 20 74 68 65 20 73 61  table has the sa
99d0: 6d 65 0a 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  me.number of col
99e0: 75 6d 6e 73 20 61 73 20 74 68 65 20 72 6f 77 73  umns as the rows
99f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
9a00: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
9a10: 74 2e 20 54 68 65 20 6e 61 6d 65 20 6f 66 0a 65  t. The name of.e
9a20: 61 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ach column is th
9a30: 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 6e 61  e same as the na
9a40: 6d 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  me of the corres
9a50: 70 6f 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 69  ponding column i
9a60: 6e 20 74 68 65 20 72 65 73 75 6c 74 0a 73 65 74  n the result.set
9a70: 20 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20 73   of the SELECT s
9a80: 74 61 74 65 6d 65 6e 74 2e 29 5e 20 5e 28 54 68  tatement.)^ ^(Th
9a90: 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
9aa0: 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69  of each column i
9ab0: 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 62 79 20  s determined.by 
9ac0: 74 68 65 20 5b 65 78 70 72 65 73 73 69 6f 6e 20  the [expression 
9ad0: 61 66 66 69 6e 69 74 79 5d 20 6f 66 20 74 68 65  affinity] of the
9ae0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
9af0: 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74 68 65  xpression in the
9b00: 20 72 65 73 75 6c 74 20 73 65 74 0a 6f 66 20 74   result set.of t
9b10: 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
9b20: 65 6e 74 2c 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ent, as follows:
9b30: 0a 3c 2f 70 3e 0a 0a 3c 63 65 6e 74 65 72 3e 3c  .</p>..<center><
9b40: 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 3e 0a  table border=1>.
9b50: 20 20 3c 74 72 3e 3c 74 68 3e 45 78 70 72 65 73    <tr><th>Expres
9b60: 73 69 6f 6e 20 41 66 66 69 6e 69 74 79 20 20 20  sion Affinity   
9b70: 3c 74 68 3e 43 6f 6c 75 6d 6e 20 44 65 63 6c 61  <th>Column Decla
9b80: 72 65 64 20 54 79 70 65 0a 20 20 3c 74 72 3e 3c  red Type.  <tr><
9b90: 74 64 3e 54 45 58 54 20 20 20 20 20 20 20 20 20  td>TEXT         
9ba0: 20 20 20 20 20 20 20 20 20 3c 74 64 3e 22 54 45           <td>"TE
9bb0: 58 54 22 0a 20 20 3c 74 72 3e 3c 74 64 3e 4e 55  XT".  <tr><td>NU
9bc0: 4d 45 52 49 43 20 20 20 20 20 20 20 20 20 20 20  MERIC           
9bd0: 20 20 20 20 3c 74 64 3e 22 4e 55 4d 22 0a 20 20      <td>"NUM".  
9be0: 3c 74 72 3e 3c 74 64 3e 49 4e 54 45 47 45 52 20  <tr><td>INTEGER 
9bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 74                <t
9c00: 64 3e 22 49 4e 54 22 0a 20 20 3c 74 72 3e 3c 74  d>"INT".  <tr><t
9c10: 64 3e 52 45 41 4c 20 20 20 20 20 20 20 20 20 20  d>REAL          
9c20: 20 20 20 20 20 20 20 20 3c 74 64 3e 22 52 45 41          <td>"REA
9c30: 4c 22 0a 20 20 3c 74 72 3e 3c 74 64 3e 4e 4f 4e  L".  <tr><td>NON
9c40: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
9c50: 20 20 20 3c 74 64 3e 22 22 20 28 65 6d 70 74 79     <td>"" (empty
9c60: 20 73 74 72 69 6e 67 29 0a 3c 2f 74 61 62 6c 65   string).</table
9c70: 3e 3c 2f 63 65 6e 74 65 72 3e 29 5e 0a 0a 3c 70  ></center>)^..<p
9c80: 3e 5e 28 41 20 74 61 62 6c 65 20 63 72 65 61 74  >^(A table creat
9c90: 65 64 20 75 73 69 6e 67 20 43 52 45 41 54 45 20  ed using CREATE 
9ca0: 54 41 42 4c 45 20 41 53 20 68 61 73 20 6e 6f 20  TABLE AS has no 
9cb0: 50 52 49 4d 41 52 59 20 4b 45 59 20 61 6e 64 20  PRIMARY KEY and 
9cc0: 6e 6f 0a 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  no.constraints o
9cd0: 66 20 61 6e 79 20 6b 69 6e 64 2e 20 54 68 65 20  f any kind. The 
9ce0: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
9cf0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20   each column is 
9d00: 4e 55 4c 4c 2e 20 54 68 65 20 64 65 66 61 75 6c  NULL. The defaul
9d10: 74 0a 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t.collation sequ
9d20: 65 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 6f  ence for each co
9d30: 6c 75 6d 6e 20 6f 66 20 74 68 65 20 6e 65 77 20  lumn of the new 
9d40: 74 61 62 6c 65 20 69 73 20 42 49 4e 41 52 59 2e  table is BINARY.
9d50: 29 5e 0a 0a 3c 70 3e 5e 54 61 62 6c 65 73 20 63  )^..<p>^Tables c
9d60: 72 65 61 74 65 64 20 75 73 69 6e 67 20 43 52 45  reated using CRE
9d70: 41 54 45 20 54 41 42 4c 45 20 41 53 20 61 72 65  ATE TABLE AS are
9d80: 20 69 6e 69 74 69 61 6c 6c 79 20 70 6f 70 75 6c   initially popul
9d90: 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 72 6f  ated with the.ro
9da0: 77 73 20 6f 66 20 64 61 74 61 20 72 65 74 75 72  ws of data retur
9db0: 6e 65 64 20 62 79 20 74 68 65 20 53 45 4c 45 43  ned by the SELEC
9dc0: 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 52 6f  T statement. ^Ro
9dd0: 77 73 20 61 72 65 20 61 73 73 69 67 6e 65 64 20  ws are assigned 
9de0: 63 6f 6e 74 69 67 75 6f 75 73 6c 79 0a 61 73 63  contiguously.asc
9df0: 65 6e 64 69 6e 67 20 5b 72 6f 77 69 64 5d 20 76  ending [rowid] v
9e00: 61 6c 75 65 73 2c 20 73 74 61 72 74 69 6e 67 20  alues, starting 
9e10: 77 69 74 68 20 31 2c 20 69 6e 20 74 68 65 20 5b  with 1, in the [
9e20: 6f 72 64 65 72 20 62 79 7c 6f 72 64 65 72 5d 20  order by|order] 
9e30: 74 68 61 74 20 74 68 65 79 0a 61 72 65 20 72 65  that they.are re
9e40: 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 53 45  turned by the SE
9e50: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
9e60: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
9e70: 74 20 7b 74 61 62 6c 65 63 6f 6c 64 65 66 7d 20  t {tablecoldef} 
9e80: 7b 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69  {column definiti
9e90: 6f 6e 7d 20 7b 63 6f 6c 75 6d 6e 20 64 65 66 69  on} {column defi
9ea0: 6e 69 74 69 6f 6e 73 7d 3c 2f 74 63 6c 3e 0a 3c  nitions}</tcl>.<
9eb0: 68 33 3e 43 6f 6c 75 6d 6e 20 44 65 66 69 6e 69  h3>Column Defini
9ec0: 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 55  tions</h3>..<p>U
9ed0: 6e 6c 65 73 73 20 69 74 20 69 73 20 61 20 43 52  nless it is a CR
9ee0: 45 41 54 45 20 54 41 42 4c 45 20 2e 2e 2e 20 41  EATE TABLE ... A
9ef0: 53 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  S SELECT stateme
9f00: 6e 74 2c 20 61 20 43 52 45 41 54 45 20 54 41 42  nt, a CREATE TAB
9f10: 4c 45 20 69 6e 63 6c 75 64 65 73 0a 6f 6e 65 20  LE includes.one 
9f20: 6f 72 20 6d 6f 72 65 20 5b 63 6f 6c 75 6d 6e 2d  or more [column-
9f30: 64 65 66 7c 63 6f 6c 75 6d 6e 20 64 65 66 69 6e  def|column defin
9f40: 69 74 69 6f 6e 73 5d 2c 20 6f 70 74 69 6f 6e 61  itions], optiona
9f50: 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  lly followed by 
9f60: 61 20 6c 69 73 74 20 6f 66 0a 5b 74 61 62 6c 65  a list of.[table
9f70: 2d 63 6f 6e 73 74 72 61 69 6e 74 7c 74 61 62 6c  -constraint|tabl
9f80: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  e constraints]. 
9f90: 20 45 61 63 68 20 63 6f 6c 75 6d 6e 20 64 65 66   Each column def
9fa0: 69 6e 69 74 69 6f 6e 20 63 6f 6e 73 69 73 74 73  inition consists
9fb0: 20 6f 66 20 74 68 65 0a 6e 61 6d 65 20 6f 66 20   of the.name of 
9fc0: 74 68 65 20 63 6f 6c 75 6d 6e 2c 20 6f 70 74 69  the column, opti
9fd0: 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
9fe0: 62 79 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  by the declared 
9ff0: 74 79 70 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  type of the colu
a000: 6d 6e 2c 0a 74 68 65 6e 20 6f 6e 65 20 6f 72 20  mn,.then one or 
a010: 6d 6f 72 65 20 6f 70 74 69 6f 6e 61 6c 20 5b 63  more optional [c
a020: 6f 6c 75 6d 6e 2d 63 6f 6e 73 74 72 61 69 6e 74  olumn-constraint
a030: 7c 63 6f 6c 75 6d 6e 20 63 6f 6e 73 74 72 61 69  |column constrai
a040: 6e 74 73 5d 2e 20 49 6e 63 6c 75 64 65 64 20 69  nts]. Included i
a050: 6e 0a 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  n.the definition
a060: 20 6f 66 20 22 63 6f 6c 75 6d 6e 20 63 6f 6e 73   of "column cons
a070: 74 72 61 69 6e 74 73 22 20 66 6f 72 20 74 68 65  traints" for the
a080: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 65   purposes of the
a090: 20 70 72 65 76 69 6f 75 73 0a 73 74 61 74 65 6d   previous.statem
a0a0: 65 6e 74 20 61 72 65 20 74 68 65 20 43 4f 4c 4c  ent are the COLL
a0b0: 41 54 45 20 61 6e 64 20 44 45 46 41 55 4c 54 20  ATE and DEFAULT 
a0c0: 63 6c 61 75 73 65 73 2c 20 65 76 65 6e 20 74 68  clauses, even th
a0d0: 6f 75 67 68 20 74 68 65 73 65 20 61 72 65 20 6e  ough these are n
a0e0: 6f 74 20 72 65 61 6c 6c 79 0a 63 6f 6e 73 74 72  ot really.constr
a0f0: 61 69 6e 74 73 20 69 6e 20 74 68 65 20 73 65 6e  aints in the sen
a100: 73 65 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  se that they do 
a110: 6e 6f 74 20 72 65 73 74 72 69 63 74 20 74 68 65  not restrict the
a120: 20 64 61 74 61 20 74 68 61 74 20 74 68 65 20 74   data that the t
a130: 61 62 6c 65 20 6d 61 79 0a 63 6f 6e 74 61 69 6e  able may.contain
a140: 2e 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6e 73  . The other cons
a150: 74 72 61 69 6e 74 73 20 2d 20 4e 4f 54 20 4e 55  traints - NOT NU
a160: 4c 4c 2c 20 43 48 45 43 4b 2c 20 55 4e 49 51 55  LL, CHECK, UNIQU
a170: 45 2c 20 50 52 49 4d 41 52 59 20 4b 45 59 20 61  E, PRIMARY KEY a
a180: 6e 64 0a 46 4f 52 45 49 47 4e 20 4b 45 59 20 63  nd.FOREIGN KEY c
a190: 6f 6e 73 74 72 61 69 6e 74 73 20 2d 20 69 6d 70  onstraints - imp
a1a0: 6f 73 65 20 72 65 73 74 72 69 63 74 69 6f 6e 73  ose restrictions
a1b0: 20 6f 6e 20 74 68 65 20 74 61 62 6c 65 73 20 64   on the tables d
a1c0: 61 74 61 2c 20 61 6e 64 20 61 72 65 20 61 72 65  ata, and are are
a1d0: 0a 64 65 73 63 72 69 62 65 64 20 75 6e 64 65 72  .described under
a1e0: 20 5b 63 6f 6e 73 74 72 61 69 6e 74 73 7c 53 51   [constraints|SQ
a1f0: 4c 20 44 61 74 61 20 43 6f 6e 73 74 72 61 69 6e  L Data Constrain
a200: 74 73 5d 20 62 65 6c 6f 77 2e 0a 0a 3c 70 3e 5e  ts] below...<p>^
a210: 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 53 51 4c 20  Unlike most SQL 
a220: 64 61 74 61 62 61 73 65 73 2c 20 53 51 4c 69 74  databases, SQLit
a230: 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 74 72  e does not restr
a240: 69 63 74 20 74 68 65 20 74 79 70 65 20 6f 66 20  ict the type of 
a250: 64 61 74 61 20 74 68 61 74 0a 6d 61 79 20 62 65  data that.may be
a260: 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61   inserted into a
a270: 20 63 6f 6c 75 6d 6e 20 62 61 73 65 64 20 6f 6e   column based on
a280: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 64 65 63   the columns dec
a290: 6c 61 72 65 64 20 74 79 70 65 2e 20 49 6e 73 74  lared type. Inst
a2a0: 65 61 64 2c 0a 53 51 4c 69 74 65 20 75 73 65 73  ead,.SQLite uses
a2b0: 20 5b 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67   [dynamic typing
a2c0: 5d 2e 20 5e 54 68 65 20 64 65 63 6c 61 72 65 64  ]. ^The declared
a2d0: 20 74 79 70 65 20 6f 66 20 61 20 63 6f 6c 75 6d   type of a colum
a2e0: 6e 20 69 73 20 75 73 65 64 20 74 6f 0a 64 65 74  n is used to.det
a2f0: 65 72 6d 69 6e 65 20 74 68 65 20 5b 61 66 66 69  ermine the [affi
a300: 6e 69 74 79 5d 20 6f 66 20 74 68 65 20 63 6f 6c  nity] of the col
a310: 75 6d 6e 20 6f 6e 6c 79 2e 0a 0a 3c 74 63 6c 3e  umn only...<tcl>
a320: 68 64 5f 66 72 61 67 6d 65 6e 74 20 64 66 6c 74  hd_fragment dflt
a330: 76 61 6c 20 7b 64 65 66 61 75 6c 74 20 63 6f 6c  val {default col
a340: 75 6d 6e 20 76 61 6c 75 65 7d 20 7b 64 65 66 61  umn value} {defa
a350: 75 6c 74 20 76 61 6c 75 65 7d 3c 2f 74 63 6c 3e  ult value}</tcl>
a360: 0a 3c 70 3e 54 68 65 20 44 45 46 41 55 4c 54 20  .<p>The DEFAULT 
a370: 63 6c 61 75 73 65 20 73 70 65 63 69 66 69 65 73  clause specifies
a380: 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
a390: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20   to use for the 
a3a0: 63 6f 6c 75 6d 6e 20 69 66 20 6e 6f 0a 76 61 6c  column if no.val
a3b0: 75 65 20 69 73 20 65 78 70 6c 69 63 69 74 6c 79  ue is explicitly
a3c0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
a3d0: 20 75 73 65 72 20 77 68 65 6e 20 64 6f 69 6e 67   user when doing
a3e0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 2e 20 5e 49   an [INSERT]. ^I
a3f0: 66 20 74 68 65 72 65 0a 69 73 20 6e 6f 20 65 78  f there.is no ex
a400: 70 6c 69 63 69 74 20 44 45 46 41 55 4c 54 20 63  plicit DEFAULT c
a410: 6c 61 75 73 65 20 61 74 74 61 63 68 65 64 20 74  lause attached t
a420: 6f 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e  o a column defin
a430: 69 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ition, then the 
a440: 0a 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f  .default value o
a450: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
a460: 4e 55 4c 4c 2e 20 5e 28 41 6e 20 65 78 70 6c 69  NULL. ^(An expli
a470: 63 69 74 20 44 45 46 41 55 4c 54 20 63 6c 61 75  cit DEFAULT clau
a480: 73 65 20 6d 61 79 20 73 70 65 63 69 66 79 0a 74  se may specify.t
a490: 68 61 74 20 74 68 65 20 64 65 66 61 75 6c 74 20  hat the default 
a4a0: 76 61 6c 75 65 20 69 73 20 4e 55 4c 4c 2c 20 61  value is NULL, a
a4b0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
a4c0: 2c 20 61 20 62 6c 6f 62 20 63 6f 6e 73 74 61 6e  , a blob constan
a4d0: 74 2c 20 61 0a 73 69 67 6e 65 64 2d 6e 75 6d 62  t, a.signed-numb
a4e0: 65 72 2c 20 6f 72 20 61 6e 79 20 63 6f 6e 73 74  er, or any const
a4f0: 61 6e 74 20 65 78 70 72 65 73 73 69 6f 6e 20 65  ant expression e
a500: 6e 63 6c 6f 73 65 64 20 69 6e 20 70 61 72 65 6e  nclosed in paren
a510: 74 68 65 73 65 73 2e 20 41 0a 64 65 66 61 75 6c  theses. A.defaul
a520: 74 20 76 61 6c 75 65 20 6d 61 79 20 61 6c 73 6f  t value may also
a530: 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 73   be one of the s
a540: 70 65 63 69 61 6c 20 63 61 73 65 2d 69 6e 64 65  pecial case-inde
a550: 70 65 6e 64 65 6e 74 20 6b 65 79 77 6f 72 64 73  pendent keywords
a560: 0a 43 55 52 52 45 4e 54 5f 54 49 4d 45 2c 20 43  .CURRENT_TIME, C
a570: 55 52 52 45 4e 54 5f 44 41 54 45 20 6f 72 20 43  URRENT_DATE or C
a580: 55 52 52 45 4e 54 5f 54 49 4d 45 53 54 41 4d 50  URRENT_TIMESTAMP
a590: 2e 29 5e 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .)^ ^For the pur
a5a0: 70 6f 73 65 73 20 6f 66 20 74 68 65 0a 44 45 46  poses of the.DEF
a5b0: 41 55 4c 54 20 63 6c 61 75 73 65 2c 20 61 6e 20  AULT clause, an 
a5c0: 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 63 6f  expression is co
a5d0: 6e 73 69 64 65 72 65 64 20 63 6f 6e 73 74 61 6e  nsidered constan
a5e0: 74 20 69 66 20 69 74 20 64 6f 65 73 0a 63 6f 6e  t if it does.con
a5f0: 74 61 69 6e 73 20 6e 6f 20 73 75 62 2d 71 75 65  tains no sub-que
a600: 72 69 65 73 2c 20 63 6f 6c 75 6d 6e 20 6f 72 20  ries, column or 
a610: 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
a620: 2c 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  , [bound paramet
a630: 65 72 73 5d 2c 0a 6f 72 20 73 74 72 69 6e 67 20  ers],.or string 
a640: 6c 69 74 65 72 61 6c 73 20 65 6e 63 6c 6f 73 65  literals enclose
a650: 64 20 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  d in double-quot
a660: 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
a670: 6e 67 6c 65 2d 71 75 6f 74 65 73 2e 0a 0a 3c 70  ngle-quotes...<p
a680: 3e 5e 28 45 61 63 68 20 74 69 6d 65 20 61 20 72  >^(Each time a r
a690: 6f 77 20 69 73 20 69 6e 73 65 72 74 65 64 20 69  ow is inserted i
a6a0: 6e 74 6f 20 74 68 65 20 74 61 62 6c 65 20 62 79  nto the table by
a6b0: 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74 65   an INSERT state
a6c0: 6d 65 6e 74 20 74 68 61 74 20 0a 64 6f 65 73 20  ment that .does 
a6d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 65 78 70 6c  not provide expl
a6e0: 69 63 69 74 20 76 61 6c 75 65 73 20 66 6f 72 20  icit values for 
a6f0: 61 6c 6c 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  all table column
a700: 73 20 74 68 65 20 76 61 6c 75 65 73 20 73 74 6f  s the values sto
a710: 72 65 64 20 69 6e 0a 74 68 65 20 6e 65 77 20 72  red in.the new r
a720: 6f 77 20 61 72 65 20 64 65 74 65 72 6d 69 6e 65  ow are determine
a730: 64 20 62 79 20 74 68 65 69 72 20 64 65 66 61 75  d by their defau
a740: 6c 74 20 76 61 6c 75 65 73 29 5e 2c 20 61 73 20  lt values)^, as 
a750: 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 75 6c 3e 0a 20  follows:..<ul>. 
a760: 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20   <li><p>^If the 
a770: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
a780: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 61   the column is a
a790: 20 63 6f 6e 73 74 61 6e 74 20 4e 55 4c 4c 2c 20   constant NULL, 
a7a0: 74 65 78 74 2c 20 62 6c 6f 62 20 6f 72 0a 20 20  text, blob or.  
a7b0: 20 20 73 69 67 6e 65 64 2d 6e 75 6d 62 65 72 20    signed-number 
a7c0: 76 61 6c 75 65 2c 20 74 68 65 6e 20 74 68 61 74  value, then that
a7d0: 20 76 61 6c 75 65 20 69 73 20 75 73 65 64 20 64   value is used d
a7e0: 69 72 65 63 74 6c 79 20 69 6e 20 74 68 65 20 6e  irectly in the n
a7f0: 65 77 20 72 6f 77 2e 0a 0a 20 20 3c 6c 69 3e 3c  ew row...  <li><
a800: 70 3e 5e 49 66 20 74 68 65 20 64 65 66 61 75 6c  p>^If the defaul
a810: 74 20 76 61 6c 75 65 20 6f 66 20 61 20 63 6f 6c  t value of a col
a820: 75 6d 6e 20 69 73 20 61 6e 20 65 78 70 72 65 73  umn is an expres
a830: 73 69 6f 6e 20 69 6e 20 70 61 72 65 6e 74 68 65  sion in parenthe
a840: 73 65 73 2c 20 74 68 65 6e 0a 20 20 20 20 74 68  ses, then.    th
a850: 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  e expression is 
a860: 65 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20 66  evaluated once f
a870: 6f 72 20 65 61 63 68 20 72 6f 77 20 69 6e 73 65  or each row inse
a880: 72 74 65 64 20 61 6e 64 20 74 68 65 20 72 65 73  rted and the res
a890: 75 6c 74 73 0a 20 20 20 20 75 73 65 64 20 69 6e  ults.    used in
a8a0: 20 74 68 65 20 6e 65 77 20 72 6f 77 2e 0a 0a 20   the new row... 
a8b0: 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20   <li><p>^If the 
a8c0: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
a8d0: 20 61 20 63 6f 6c 75 6d 6e 20 69 73 20 43 55 52   a column is CUR
a8e0: 52 45 4e 54 5f 54 49 4d 45 2c 20 43 55 52 52 45  RENT_TIME, CURRE
a8f0: 4e 54 5f 44 41 54 45 20 6f 72 0a 20 20 20 20 43  NT_DATE or.    C
a900: 55 52 52 45 4e 54 5f 54 49 4d 45 53 54 41 4d 50  URRENT_TIMESTAMP
a910: 2c 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  , then the value
a920: 20 75 73 65 64 20 69 6e 20 74 68 65 20 6e 65 77   used in the new
a930: 20 72 6f 77 20 69 73 20 61 20 74 65 78 74 0a 20   row is a text. 
a940: 20 20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f     representatio
a950: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
a960: 20 55 54 43 20 64 61 74 65 20 61 6e 64 2f 6f 72   UTC date and/or
a970: 20 74 69 6d 65 2e 20 5e 46 6f 72 20 43 55 52 52   time. ^For CURR
a980: 45 4e 54 5f 54 49 4d 45 2c 20 74 68 65 0a 20 20  ENT_TIME, the.  
a990: 20 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20    format of the 
a9a0: 76 61 6c 75 65 20 69 73 20 22 48 48 3a 4d 4d 3a  value is "HH:MM:
a9b0: 53 53 22 2e 20 5e 46 6f 72 20 43 55 52 52 45 4e  SS". ^For CURREN
a9c0: 54 5f 44 41 54 45 2c 20 22 59 59 59 59 2d 4d 4d  T_DATE, "YYYY-MM
a9d0: 2d 44 44 22 2e 20 5e 54 68 65 0a 20 20 20 20 66  -DD". ^The.    f
a9e0: 6f 72 6d 61 74 20 66 6f 72 20 43 55 52 52 45 4e  ormat for CURREN
a9f0: 54 5f 54 49 4d 45 53 54 41 4d 50 20 69 73 20 22  T_TIMESTAMP is "
aa00: 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48 3a 4d 4d  YYYY-MM-DD HH:MM
aa10: 3a 53 53 22 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  :SS"..</ul>..<p>
aa20: 5e 54 68 65 20 43 4f 4c 4c 41 54 45 20 63 6c 61  ^The COLLATE cla
aa30: 75 73 65 20 73 70 65 63 69 66 69 65 73 20 74 68  use specifies th
aa40: 65 20 6e 61 6d 65 20 6f 66 20 61 20 5b 63 6f 6c  e name of a [col
aa50: 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 5d  lating sequence]
aa60: 20 74 6f 20 75 73 65 20 61 73 0a 74 68 65 20 64   to use as.the d
aa70: 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
aa80: 20 73 65 71 75 65 6e 63 65 20 66 6f 72 20 74 68   sequence for th
aa90: 65 20 63 6f 6c 75 6d 6e 2e 20 5e 49 66 20 6e 6f  e column. ^If no
aaa0: 20 43 4f 4c 4c 41 54 45 20 63 6c 61 75 73 65 20   COLLATE clause 
aab0: 69 73 0a 73 70 65 63 69 66 69 65 64 2c 20 74 68  is.specified, th
aac0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
aad0: 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
aae0: 5b 42 49 4e 41 52 59 5d 2e 0a 0a 3c 70 3e 5e 54  [BINARY]...<p>^T
aaf0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
ab00: 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
ab10: 69 73 20 6c 69 6d 69 74 65 64 20 62 79 20 74 68  is limited by th
ab20: 65 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f  e [SQLITE_MAX_CO
ab30: 4c 55 4d 4e 5d 0a 63 6f 6d 70 69 6c 65 2d 74 69  LUMN].compile-ti
ab40: 6d 65 20 70 61 72 61 6d 65 74 65 72 2e 20 5e 41  me parameter. ^A
ab50: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
ab60: 20 74 61 62 6c 65 20 63 61 6e 6e 6f 74 20 73 74   table cannot st
ab70: 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e 0a 5b 53  ore more than.[S
ab80: 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
ab90: 5d 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 2e  ] bytes of data.
aba0: 20 5e 42 6f 74 68 20 6f 66 20 74 68 65 73 65 20   ^Both of these 
abb0: 6c 69 6d 69 74 73 20 63 61 6e 20 62 65 20 6c 6f  limits can be lo
abc0: 77 65 72 65 64 20 61 74 0a 72 75 6e 74 69 6d 65  wered at.runtime
abd0: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
abe0: 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 43 2f 43  te3_limit()] C/C
abf0: 2b 2b 20 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70  ++ interface.</p
ac00: 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
ac10: 65 6e 74 20 7b 63 6f 6e 73 74 72 61 69 6e 74 73  ent {constraints
ac20: 7d 20 7b 63 6f 6e 73 74 72 61 69 6e 74 73 7d 3c  } {constraints}<
ac30: 2f 74 63 6c 3e 0a 3c 68 33 3e 53 51 4c 20 44 61  /tcl>.<h3>SQL Da
ac40: 74 61 20 43 6f 6e 73 74 72 61 69 6e 74 73 3c 2f  ta Constraints</
ac50: 68 33 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  h3>..<tcl>hd_fra
ac60: 67 6d 65 6e 74 20 70 72 69 6d 6b 65 79 63 6f 6e  gment primkeycon
ac70: 73 74 20 7b 50 52 49 4d 41 52 59 20 4b 45 59 7d  st {PRIMARY KEY}
ac80: 20 7b 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f   {PRIMARY KEY co
ac90: 6e 73 74 72 61 69 6e 74 7d 3c 2f 74 63 6c 3e 0a  nstraint}</tcl>.
aca0: 3c 70 3e 5e 45 61 63 68 20 74 61 62 6c 65 20 69  <p>^Each table i
acb0: 6e 20 53 51 4c 69 74 65 20 6d 61 79 20 68 61 76  n SQLite may hav
acc0: 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 3c 62  e at most one <b
acd0: 3e 50 52 49 4d 41 52 59 20 4b 45 59 3c 2f 62 3e  >PRIMARY KEY</b>
ace0: 2e 20 5e 49 66 20 74 68 65 0a 20 20 6b 65 79 77  . ^If the.  keyw
acf0: 6f 72 64 73 20 50 52 49 4d 41 52 59 20 4b 45 59  ords PRIMARY KEY
ad00: 20 61 72 65 20 61 64 64 65 64 20 74 6f 20 61 20   are added to a 
ad10: 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f  column definitio
ad20: 6e 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6d  n, then the prim
ad30: 61 72 79 20 6b 65 79 0a 20 20 66 6f 72 20 74 68  ary key.  for th
ad40: 65 20 74 61 62 6c 65 20 63 6f 6e 73 69 73 74 73  e table consists
ad50: 20 6f 66 20 74 68 61 74 20 73 69 6e 67 6c 65 20   of that single 
ad60: 63 6f 6c 75 6d 6e 2e 20 5e 4f 72 2c 20 69 66 20  column. ^Or, if 
ad70: 61 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6c  a PRIMARY KEY cl
ad80: 61 75 73 65 20 0a 20 20 69 73 20 73 70 65 63 69  ause .  is speci
ad90: 66 69 65 64 20 61 73 20 61 20 5b 74 61 62 6c 65  fied as a [table
ada0: 2d 63 6f 6e 73 74 72 61 69 6e 74 5d 2c 20 74 68  -constraint], th
adb0: 65 6e 20 74 68 65 20 70 72 69 6d 61 72 79 20 6b  en the primary k
adc0: 65 79 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  ey of the table.
add0: 20 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68    consists of th
ade0: 65 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e  e list of column
adf0: 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  s specified as p
ae00: 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
ae10: 52 59 20 4b 45 59 20 63 6c 61 75 73 65 2e 0a 20  RY KEY clause.. 
ae20: 20 5e 54 68 65 20 50 52 49 4d 41 52 59 20 4b 45   ^The PRIMARY KE
ae30: 59 20 63 6c 61 75 73 65 20 6d 75 73 74 20 63 6f  Y clause must co
ae40: 6e 74 61 69 6e 20 6f 6e 6c 79 20 63 6f 6c 75 6d  ntain only colum
ae50: 6e 20 6e 61 6d 65 73 20 26 6d 64 61 73 68 3b 20  n names &mdash; 
ae60: 74 68 65 20 75 73 65 20 6f 66 20 0a 20 20 65 78  the use of .  ex
ae70: 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e 20  pressions in an 
ae80: 5b 69 6e 64 65 78 65 64 2d 63 6f 6c 75 6d 6e 5d  [indexed-column]
ae90: 20 6f 66 20 61 20 50 52 49 4d 41 52 59 20 4b 45   of a PRIMARY KE
aea0: 59 20 69 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  Y is not support
aeb0: 65 64 2e 0a 20 20 5e 41 6e 20 65 72 72 6f 72 20  ed..  ^An error 
aec0: 69 73 20 72 61 69 73 65 64 20 69 66 20 6d 6f 72  is raised if mor
aed0: 65 20 74 68 61 6e 20 6f 6e 65 20 50 52 49 4d 41  e than one PRIMA
aee0: 52 59 20 4b 45 59 20 63 6c 61 75 73 65 20 61 70  RY KEY clause ap
aef0: 70 65 61 72 73 20 69 6e 20 61 0a 20 20 43 52 45  pears in a.  CRE
af00: 41 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d  ATE TABLE statem
af10: 65 6e 74 2e 20 20 5e 54 68 65 20 50 52 49 4d 41  ent.  ^The PRIMA
af20: 52 59 20 4b 45 59 20 69 73 20 6f 70 74 69 6f 6e  RY KEY is option
af30: 61 6c 20 66 6f 72 20 6f 72 64 69 6e 61 72 79 20  al for ordinary 
af40: 74 61 62 6c 65 73 0a 20 20 62 75 74 20 69 73 20  tables.  but is 
af50: 72 65 71 75 69 72 65 64 20 66 6f 72 20 5b 57 49  required for [WI
af60: 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
af70: 6c 65 73 2e 0a 0a 3c 70 3e 49 66 20 61 20 74 61  les...<p>If a ta
af80: 62 6c 65 20 68 61 73 20 61 20 73 69 6e 67 6c 65  ble has a single
af90: 20 63 6f 6c 75 6d 6e 20 70 72 69 6d 61 72 79 20   column primary 
afa0: 6b 65 79 20 61 6e 64 20 74 68 65 20 64 65 63 6c  key and the decl
afb0: 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 61  ared type of tha
afc0: 74 0a 20 20 63 6f 6c 75 6d 6e 20 69 73 20 22 49  t.  column is "I
afd0: 4e 54 45 47 45 52 22 20 61 6e 64 20 74 68 65 20  NTEGER" and the 
afe0: 74 61 62 6c 65 20 69 73 20 6e 6f 74 20 61 20 5b  table is not a [
aff0: 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
b000: 61 62 6c 65 2c 0a 20 20 74 68 65 6e 20 74 68 65  able,.  then the
b010: 20 63 6f 6c 75 6d 6e 20 69 73 20 6b 6e 6f 77 6e   column is known
b020: 20 61 73 20 61 6e 20 5b 49 4e 54 45 47 45 52 20   as an [INTEGER 
b030: 50 52 49 4d 41 52 59 20 4b 45 59 5d 2e 0a 20 20  PRIMARY KEY]..  
b040: 53 65 65 20 5b 72 6f 77 69 64 7c 62 65 6c 6f 77  See [rowid|below
b050: 5d 20 66 6f 72 20 61 20 64 65 73 63 72 69 70 74  ] for a descript
b060: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
b070: 61 6c 20 70 72 6f 70 65 72 74 69 65 73 20 61 6e  al properties an
b080: 64 20 62 65 68 61 76 69 6f 72 73 0a 20 20 61 73  d behaviors.  as
b090: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 6e  sociated with an
b0a0: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
b0b0: 59 20 4b 45 59 5d 2e 0a 0a 3c 70 3e 5e 45 61 63  Y KEY]...<p>^Eac
b0c0: 68 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c 65  h row in a table
b0d0: 20 77 69 74 68 20 61 20 70 72 69 6d 61 72 79 20   with a primary 
b0e0: 6b 65 79 20 6d 75 73 74 20 68 61 76 65 20 61 20  key must have a 
b0f0: 75 6e 69 71 75 65 20 63 6f 6d 62 69 6e 61 74 69  unique combinati
b100: 6f 6e 0a 20 20 6f 66 20 76 61 6c 75 65 73 20 69  on.  of values i
b110: 6e 20 69 74 73 20 70 72 69 6d 61 72 79 20 6b 65  n its primary ke
b120: 79 20 63 6f 6c 75 6d 6e 73 2e 20 5e 46 6f 72 20  y columns. ^For 
b130: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
b140: 64 65 74 65 72 6d 69 6e 69 6e 67 0a 20 20 74 68  determining.  th
b150: 65 20 75 6e 69 71 75 65 6e 65 73 73 20 6f 66 20  e uniqueness of 
b160: 70 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75  primary key valu
b170: 65 73 2c 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  es, NULL values 
b180: 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 64  are considered d
b190: 69 73 74 69 6e 63 74 20 66 72 6f 6d 0a 20 20 61  istinct from.  a
b1a0: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 2c  ll other values,
b1b0: 20 69 6e 63 6c 75 64 69 6e 67 20 6f 74 68 65 72   including other
b1c0: 20 4e 55 4c 4c 73 2e 20 5e 49 66 20 61 6e 20 5b   NULLs. ^If an [
b1d0: 49 4e 53 45 52 54 5d 20 6f 72 20 5b 55 50 44 41  INSERT] or [UPDA
b1e0: 54 45 5d 0a 20 20 73 74 61 74 65 6d 65 6e 74 20  TE].  statement 
b1f0: 61 74 74 65 6d 70 74 73 20 74 6f 20 6d 6f 64 69  attempts to modi
b200: 66 79 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  fy the table con
b210: 74 65 6e 74 20 73 6f 20 74 68 61 74 20 74 77 6f  tent so that two
b220: 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 0a 20 20   or more rows.  
b230: 68 61 76 65 20 69 64 65 6e 74 69 63 61 6c 20 70  have identical p
b240: 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75 65  rimary key value
b250: 73 2c 20 74 68 61 74 20 69 73 20 61 20 63 6f 6e  s, that is a con
b260: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
b270: 6e 2e 0a 0a 3c 70 3e 20 41 63 63 6f 72 64 69 6e  n...<p> Accordin
b280: 67 20 74 6f 20 74 68 65 20 53 51 4c 20 73 74 61  g to the SQL sta
b290: 6e 64 61 72 64 2c 20 50 52 49 4d 41 52 59 20 4b  ndard, PRIMARY K
b2a0: 45 59 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  EY should always
b2b0: 20 69 6d 70 6c 79 20 4e 4f 54 20 4e 55 4c 4c 2e   imply NOT NULL.
b2c0: 0a 20 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79  .  Unfortunately
b2d0: 2c 20 64 75 65 20 74 6f 20 61 20 62 75 67 20 69  , due to a bug i
b2e0: 6e 20 73 6f 6d 65 20 65 61 72 6c 79 20 76 65 72  n some early ver
b2f0: 73 69 6f 6e 73 2c 20 74 68 69 73 20 69 73 20 6e  sions, this is n
b300: 6f 74 20 74 68 65 0a 20 20 63 61 73 65 20 69 6e  ot the.  case in
b310: 20 53 51 4c 69 74 65 2e 20 5e 55 6e 6c 65 73 73   SQLite. ^Unless
b320: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 61   the column is a
b330: 6e 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  n [INTEGER PRIMA
b340: 52 59 20 4b 45 59 5d 20 6f 72 0a 20 20 74 68 65  RY KEY] or.  the
b350: 20 74 61 62 6c 65 20 69 73 20 61 20 5b 57 49 54   table is a [WIT
b360: 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
b370: 65 20 6f 72 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e or the column 
b380: 69 73 20 64 65 63 6c 61 72 65 64 20 4e 4f 54 20  is declared NOT 
b390: 4e 55 4c 4c 2c 0a 20 20 53 51 4c 69 74 65 20 61  NULL,.  SQLite a
b3a0: 6c 6c 6f 77 73 20 4e 55 4c 4c 20 76 61 6c 75 65  llows NULL value
b3b0: 73 20 69 6e 20 61 20 50 52 49 4d 41 52 59 20 4b  s in a PRIMARY K
b3c0: 45 59 20 63 6f 6c 75 6d 6e 2e 20 20 53 51 4c 69  EY column.  SQLi
b3d0: 74 65 20 63 6f 75 6c 64 20 62 65 20 66 69 78 65  te could be fixe
b3e0: 64 20 74 6f 0a 20 20 63 6f 6e 66 6f 72 6d 20 74  d to.  conform t
b3f0: 6f 20 74 68 65 20 73 74 61 6e 64 61 72 64 2c 20  o the standard, 
b400: 62 75 74 20 64 6f 69 6e 67 20 73 6f 20 6d 69 67  but doing so mig
b410: 68 74 20 62 72 65 61 6b 20 6c 65 67 61 63 79 20  ht break legacy 
b420: 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 0a 20 20  applications..  
b430: 48 65 6e 63 65 2c 20 69 74 20 68 61 73 20 62 65  Hence, it has be
b440: 65 6e 20 64 65 63 69 64 65 64 20 74 6f 20 6d 65  en decided to me
b450: 72 65 6c 79 20 64 6f 63 75 6d 65 6e 74 20 74 68  rely document th
b460: 65 20 66 61 63 74 20 74 68 61 74 20 53 51 4c 69  e fact that SQLi
b470: 74 65 0a 20 20 61 6c 6c 6f 77 69 6e 67 20 4e 55  te.  allowing NU
b480: 4c 4c 73 20 69 6e 20 6d 6f 73 74 20 50 52 49 4d  LLs in most PRIM
b490: 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 73 2e  ARY KEY columns.
b4a0: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
b4b0: 6e 74 20 75 6e 69 71 75 65 63 6f 6e 73 74 20 7b  nt uniqueconst {
b4c0: 55 4e 49 51 55 45 7d 20 7b 75 6e 69 71 75 65 20  UNIQUE} {unique 
b4d0: 63 6f 6e 73 74 72 61 69 6e 74 7d 20 7b 55 4e 49  constraint} {UNI
b4e0: 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74 7d 3c  QUE constraint}<
b4f0: 2f 74 63 6c 3e 0a 3c 70 3e 5e 41 20 3c 62 3e 55  /tcl>.<p>^A <b>U
b500: 4e 49 51 55 45 3c 2f 62 3e 20 63 6f 6e 73 74 72  NIQUE</b> constr
b510: 61 69 6e 74 20 69 73 20 73 69 6d 69 6c 61 72 20  aint is similar 
b520: 74 6f 20 61 20 50 52 49 4d 41 52 59 20 4b 45 59  to a PRIMARY KEY
b530: 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 65 78 63   constraint, exc
b540: 65 70 74 0a 20 20 74 68 61 74 20 61 20 73 69 6e  ept.  that a sin
b550: 67 6c 65 20 74 61 62 6c 65 20 6d 61 79 20 68 61  gle table may ha
b560: 76 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ve any number of
b570: 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69   UNIQUE constrai
b580: 6e 74 73 2e 20 5e 46 6f 72 20 65 61 63 68 0a 20  nts. ^For each. 
b590: 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69   UNIQUE constrai
b5a0: 6e 74 20 6f 6e 20 74 68 65 20 74 61 62 6c 65 2c  nt on the table,
b5b0: 20 65 61 63 68 20 72 6f 77 20 6d 75 73 74 20 63   each row must c
b5c0: 6f 6e 74 61 69 6e 20 61 20 75 6e 69 71 75 65 20  ontain a unique 
b5d0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 0a 20 20 6f 66  combination.  of
b5e0: 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
b5f0: 6f 6c 75 6d 6e 73 20 69 64 65 6e 74 69 66 69 65  olumns identifie
b600: 64 20 62 79 20 74 68 65 20 55 4e 49 51 55 45 20  d by the UNIQUE 
b610: 63 6f 6e 73 74 72 61 69 6e 74 2e 20 0a 20 20 5e  constraint. .  ^
b620: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
b630: 20 6f 66 20 55 4e 49 51 55 45 20 63 6f 6e 73 74   of UNIQUE const
b640: 72 61 69 6e 74 73 2c 20 4e 55 4c 4c 20 76 61 6c  raints, NULL val
b650: 75 65 73 0a 20 20 61 72 65 20 63 6f 6e 73 69 64  ues.  are consid
b660: 65 72 65 64 20 64 69 73 74 69 6e 63 74 20 66 72  ered distinct fr
b670: 6f 6d 20 61 6c 6c 20 6f 74 68 65 72 20 76 61 6c  om all other val
b680: 75 65 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6f  ues, including o
b690: 74 68 65 72 20 4e 55 4c 4c 73 2e 0a 20 20 5e 41  ther NULLs..  ^A
b6a0: 73 20 77 69 74 68 20 50 52 49 4d 41 52 59 20 4b  s with PRIMARY K
b6b0: 45 59 73 2c 20 61 20 55 4e 49 51 55 45 20 5b 74  EYs, a UNIQUE [t
b6c0: 61 62 6c 65 2d 63 6f 6e 73 74 72 61 69 6e 74 5d  able-constraint]
b6d0: 20 63 6c 61 75 73 65 20 6d 75 73 74 20 63 6f 6e   clause must con
b6e0: 74 61 69 6e 0a 20 20 6f 6e 6c 79 20 63 6f 6c 75  tain.  only colu
b6f0: 6d 6e 20 6e 61 6d 65 73 20 26 6d 64 61 73 68 3b  mn names &mdash;
b700: 20 74 68 65 20 75 73 65 20 6f 66 20 0a 20 20 65   the use of .  e
b710: 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e  xpressions in an
b720: 20 5b 69 6e 64 65 78 65 64 2d 63 6f 6c 75 6d 6e   [indexed-column
b730: 5d 20 6f 66 20 61 20 55 4e 49 51 55 45 20 5b 74  ] of a UNIQUE [t
b740: 61 62 6c 65 2d 63 6f 6e 73 74 72 61 69 6e 74 5d  able-constraint]
b750: 0a 20 20 69 73 20 6e 6f 74 20 73 75 70 70 6f 72  .  is not suppor
b760: 74 65 64 2e 0a 20 20 0a 0a 3c 70 3e 5e 49 6e 20  ted..  ..<p>^In 
b770: 6d 6f 73 74 20 63 61 73 65 73 2c 20 55 4e 49 51  most cases, UNIQ
b780: 55 45 20 61 6e 64 20 50 52 49 4d 41 52 59 20 4b  UE and PRIMARY K
b790: 45 59 0a 20 20 63 6f 6e 73 74 72 61 69 6e 74 73  EY.  constraints
b7a0: 20 61 72 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   are implemented
b7b0: 20 62 79 20 63 72 65 61 74 69 6e 67 20 61 20 75   by creating a u
b7c0: 6e 69 71 75 65 20 69 6e 64 65 78 20 69 6e 20 74  nique index in t
b7d0: 68 65 20 64 61 74 61 62 61 73 65 2e 0a 20 20 28  he database..  (
b7e0: 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 61  The exceptions a
b7f0: 72 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  re [INTEGER PRIM
b800: 41 52 59 20 4b 45 59 5d 20 61 6e 64 20 50 52 49  ARY KEY] and PRI
b810: 4d 41 52 59 20 4b 45 59 73 20 6f 6e 20 0a 20 20  MARY KEYs on .  
b820: 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
b830: 74 61 62 6c 65 73 2e 29 0a 20 20 48 65 6e 63 65  tables.).  Hence
b840: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
b850: 73 63 68 65 6d 61 73 20 61 72 65 20 6c 6f 67 69  schemas are logi
b860: 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74  cally equivalent
b870: 3a 0a 0a 20 20 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e  :..  <ol>.  <li>
b880: 3c 70 3e 43 52 45 41 54 45 20 54 41 42 4c 45 20  <p>CREATE TABLE 
b890: 74 31 28 61 2c 20 62 20 55 4e 49 51 55 45 29 3b  t1(a, b UNIQUE);
b8a0: 0a 20 20 3c 6c 69 3e 3c 70 3e 43 52 45 41 54 45  .  <li><p>CREATE
b8b0: 20 54 41 42 4c 45 20 74 31 28 61 2c 20 62 20 50   TABLE t1(a, b P
b8c0: 52 49 4d 41 52 59 20 4b 45 59 29 3b 0a 20 20 3c  RIMARY KEY);.  <
b8d0: 6c 69 3e 3c 70 3e 43 52 45 41 54 45 20 54 41 42  li><p>CREATE TAB
b8e0: 4c 45 20 74 31 28 61 2c 20 62 29 3b 3c 62 72 3e  LE t1(a, b);<br>
b8f0: 0a 20 20 20 20 20 20 20 20 20 43 52 45 41 54 45  .         CREATE
b900: 20 55 4e 49 51 55 45 20 49 4e 44 45 58 20 74 31   UNIQUE INDEX t1
b910: 62 20 4f 4e 20 74 31 28 62 29 3b 0a 20 20 3c 2f  b ON t1(b);.  </
b920: 6f 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ol>..<tcl>hd_fra
b930: 67 6d 65 6e 74 20 7b 63 6b 63 6f 6e 73 74 7d 20  gment {ckconst} 
b940: 7b 43 48 45 43 4b 7d 20 7b 43 48 45 43 4b 20 63  {CHECK} {CHECK c
b950: 6f 6e 73 74 72 61 69 6e 74 7d 20 7b 43 48 45 43  onstraint} {CHEC
b960: 4b 20 63 6f 6e 73 74 72 61 69 6e 74 73 7d 3c 2f  K constraints}</
b970: 74 63 6c 3e 0a 3c 70 3e 5e 28 41 20 3c 62 3e 43  tcl>.<p>^(A <b>C
b980: 48 45 43 4b 3c 2f 62 3e 20 63 6f 6e 73 74 72 61  HECK</b> constra
b990: 69 6e 74 20 6d 61 79 20 62 65 20 61 74 74 61 63  int may be attac
b9a0: 68 65 64 20 74 6f 20 61 20 63 6f 6c 75 6d 6e 20  hed to a column 
b9b0: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 0a 20 20  definition or.  
b9c0: 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 74  specified as a t
b9d0: 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e 74 2e  able constraint.
b9e0: 20 49 6e 20 70 72 61 63 74 69 63 65 20 69 74 20   In practice it 
b9f0: 6d 61 6b 65 73 20 6e 6f 20 64 69 66 66 65 72 65  makes no differe
ba00: 6e 63 65 2e 29 5e 20 5e 28 45 61 63 68 0a 20 20  nce.)^ ^(Each.  
ba10: 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 69  time a new row i
ba20: 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  s inserted into 
ba30: 74 68 65 20 74 61 62 6c 65 20 6f 72 20 61 6e 20  the table or an 
ba40: 65 78 69 73 74 69 6e 67 20 72 6f 77 20 69 73 20  existing row is 
ba50: 75 70 64 61 74 65 64 2c 0a 20 20 74 68 65 20 65  updated,.  the e
ba60: 78 70 72 65 73 73 69 6f 6e 20 61 73 73 6f 63 69  xpression associ
ba70: 61 74 65 64 20 77 69 74 68 20 65 61 63 68 20 43  ated with each C
ba80: 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 20  HECK constraint 
ba90: 69 73 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  is evaluated and
baa0: 0a 20 20 63 61 73 74 20 74 6f 20 61 20 4e 55 4d  .  cast to a NUM
bab0: 45 52 49 43 20 76 61 6c 75 65 20 69 6e 20 74 68  ERIC value in th
bac0: 65 20 73 61 6d 65 20 77 61 79 20 61 73 20 61 20  e same way as a 
bad0: 5b 43 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e  [CAST expression
bae0: 5d 2e 20 49 66 20 74 68 65 20 0a 20 20 72 65 73  ]. If the .  res
baf0: 75 6c 74 20 69 73 20 7a 65 72 6f 20 28 69 6e 74  ult is zero (int
bb00: 65 67 65 72 20 76 61 6c 75 65 20 30 20 6f 72 20  eger value 0 or 
bb10: 72 65 61 6c 20 76 61 6c 75 65 20 30 2e 30 29 2c  real value 0.0),
bb20: 20 74 68 65 6e 20 61 20 63 6f 6e 73 74 72 61 69   then a constrai
bb30: 6e 74 0a 20 20 76 69 6f 6c 61 74 69 6f 6e 20 68  nt.  violation h
bb40: 61 73 20 6f 63 63 75 72 72 65 64 2e 29 5e 20 5e  as occurred.)^ ^
bb50: 49 66 20 74 68 65 20 43 48 45 43 4b 20 65 78 70  If the CHECK exp
bb60: 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74 65  ression evaluate
bb70: 73 20 74 6f 20 4e 55 4c 4c 2c 20 6f 72 0a 20 20  s to NULL, or.  
bb80: 61 6e 79 20 6f 74 68 65 72 20 6e 6f 6e 2d 7a 65  any other non-ze
bb90: 72 6f 20 76 61 6c 75 65 2c 20 69 74 20 69 73 20  ro value, it is 
bba0: 6e 6f 74 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  not a constraint
bbb0: 20 76 69 6f 6c 61 74 69 6f 6e 2e 0a 20 20 5e 54   violation..  ^T
bbc0: 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 66  he expression of
bbd0: 20 61 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61   a CHECK constra
bbe0: 69 6e 74 20 6d 61 79 20 6e 6f 74 20 63 6f 6e 74  int may not cont
bbf0: 61 69 6e 20 61 20 73 75 62 71 75 65 72 79 2e 0a  ain a subquery..
bc00: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
bc10: 74 20 7b 6e 6f 74 6e 75 6c 6c 63 6f 6e 73 74 7d  t {notnullconst}
bc20: 20 7b 4e 4f 54 20 4e 55 4c 4c 7d 20 7b 4e 4f 54   {NOT NULL} {NOT
bc30: 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
bc40: 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 41 20 3c 62  }</tcl>.<p>^A <b
bc50: 3e 4e 4f 54 20 4e 55 4c 4c 3c 2f 62 3e 20 63 6f  >NOT NULL</b> co
bc60: 6e 73 74 72 61 69 6e 74 20 6d 61 79 20 6f 6e 6c  nstraint may onl
bc70: 79 20 62 65 20 61 74 74 61 63 68 65 64 20 74 6f  y be attached to
bc80: 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69   a column defini
bc90: 74 69 6f 6e 2c 0a 20 20 6e 6f 74 20 73 70 65 63  tion,.  not spec
bca0: 69 66 69 65 64 20 61 73 20 61 20 74 61 62 6c 65  ified as a table
bcb0: 20 63 6f 6e 73 74 72 61 69 6e 74 2e 20 20 4e 6f   constraint.  No
bcc0: 74 20 73 75 72 70 72 69 73 69 6e 67 6c 79 2c 20  t surprisingly, 
bcd0: 5e 28 61 20 4e 4f 54 20 4e 55 4c 4c 0a 20 20 63  ^(a NOT NULL.  c
bce0: 6f 6e 73 74 72 61 69 6e 74 20 64 69 63 74 61 74  onstraint dictat
bcf0: 65 73 20 74 68 61 74 20 74 68 65 20 61 73 73 6f  es that the asso
bd00: 63 69 61 74 65 64 20 63 6f 6c 75 6d 6e 20 6d 61  ciated column ma
bd10: 79 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20  y not contain a 
bd20: 4e 55 4c 4c 20 76 61 6c 75 65 2e 0a 20 20 41 74  NULL value..  At
bd30: 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
bd40: 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  the column value
bd50: 20 74 6f 20 4e 55 4c 4c 20 77 68 65 6e 20 69 6e   to NULL when in
bd60: 73 65 72 74 69 6e 67 20 61 20 6e 65 77 20 72 6f  serting a new ro
bd70: 77 20 6f 72 0a 20 20 75 70 64 61 74 69 6e 67 20  w or.  updating 
bd80: 61 6e 20 65 78 69 73 74 69 6e 67 20 6f 6e 65 20  an existing one 
bd90: 63 61 75 73 65 73 20 61 20 63 6f 6e 73 74 72 61  causes a constra
bda0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2e 29 5e  int violation.)^
bdb0: 0a 0a 3c 70 3e 45 78 61 63 74 6c 79 20 68 6f 77  ..<p>Exactly how
bdc0: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
bdd0: 6f 6c 61 74 69 6f 6e 20 69 73 20 64 65 61 6c 74  olation is dealt
bde0: 20 77 69 74 68 20 69 73 20 64 65 74 65 72 6d 69   with is determi
bdf0: 6e 65 64 20 62 79 20 74 68 65 0a 20 20 5b 63 6f  ned by the.  [co
be00: 6e 66 6c 69 63 74 20 63 6c 61 75 73 65 7c 63 6f  nflict clause|co
be10: 6e 73 74 72 61 69 6e 74 20 63 6f 6e 66 6c 69 63  nstraint conflic
be20: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67  t resolution alg
be30: 6f 72 69 74 68 6d 5d 2e 20 45 61 63 68 20 0a 20  orithm]. Each . 
be40: 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 55 4e   PRIMARY KEY, UN
be50: 49 51 55 45 2c 20 4e 4f 54 20 4e 55 4c 4c 20 61  IQUE, NOT NULL a
be60: 6e 64 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61  nd CHECK constra
be70: 69 6e 74 20 68 61 73 20 61 20 64 65 66 61 75 6c  int has a defaul
be80: 74 20 63 6f 6e 66 6c 69 63 74 0a 20 20 72 65 73  t conflict.  res
be90: 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
bea0: 6d 2e 20 5e 50 52 49 4d 41 52 59 20 4b 45 59 2c  m. ^PRIMARY KEY,
beb0: 20 55 4e 49 51 55 45 20 61 6e 64 20 4e 4f 54 20   UNIQUE and NOT 
bec0: 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 73  NULL constraints
bed0: 20 6d 61 79 20 62 65 0a 20 20 65 78 70 6c 69 63   may be.  explic
bee0: 69 74 6c 79 20 61 73 73 69 67 6e 65 64 20 61 20  itly assigned a 
bef0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 6c 69 63 74  default conflict
bf00: 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f   resolution algo
bf10: 72 69 74 68 6d 20 62 79 20 69 6e 63 6c 75 64 69  rithm by includi
bf20: 6e 67 0a 20 20 61 20 5b 63 6f 6e 66 6c 69 63 74  ng.  a [conflict
bf30: 2d 63 6c 61 75 73 65 5d 20 69 6e 20 74 68 65 69  -clause] in thei
bf40: 72 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 5e  r definitions. ^
bf50: 4f 72 2c 20 69 66 20 61 20 63 6f 6e 73 74 72 61  Or, if a constra
bf60: 69 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 0a 20  int definition. 
bf70: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
bf80: 65 20 61 20 5b 63 6f 6e 66 6c 69 63 74 2d 63 6c  e a [conflict-cl
bf90: 61 75 73 65 5d 20 6f 72 20 69 74 20 69 73 20 61  ause] or it is a
bfa0: 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e   CHECK constrain
bfb0: 74 2c 20 74 68 65 20 64 65 66 61 75 6c 74 0a 20  t, the default. 
bfc0: 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75   conflict resolu
bfd0: 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 69  tion algorithm i
bfe0: 73 20 41 42 4f 52 54 2e 20 5e 44 69 66 66 65 72  s ABORT. ^Differ
bff0: 65 6e 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ent constraints 
c000: 77 69 74 68 69 6e 20 74 68 65 0a 20 20 73 61 6d  within the.  sam
c010: 65 20 74 61 62 6c 65 20 6d 61 79 20 68 61 76 65  e table may have
c020: 20 64 69 66 66 65 72 65 6e 74 20 64 65 66 61 75   different defau
c030: 6c 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  lt conflict reso
c040: 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d  lution algorithm
c050: 73 2e 20 53 65 65 0a 20 20 74 68 65 20 73 65 63  s. See.  the sec
c060: 74 69 6f 6e 20 74 69 74 6c 65 64 20 5b 4f 4e 20  tion titled [ON 
c070: 43 4f 4e 46 4c 49 43 54 5d 20 66 6f 72 20 61 64  CONFLICT] for ad
c080: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
c090: 74 69 6f 6e 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  tion...<tcl>hd_f
c0a0: 72 61 67 6d 65 6e 74 20 72 6f 77 69 64 20 7b 49  ragment rowid {I
c0b0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
c0c0: 45 59 7d 20 52 4f 57 49 44 20 72 6f 77 69 64 3c  EY} ROWID rowid<
c0d0: 2f 74 63 6c 3e 0a 3c 68 33 3e 52 4f 57 49 44 73  /tcl>.<h3>ROWIDs
c0e0: 20 61 6e 64 20 74 68 65 20 49 4e 54 45 47 45 52   and the INTEGER
c0f0: 20 50 52 49 4d 41 52 59 20 4b 45 59 3c 2f 68 33   PRIMARY KEY</h3
c100: 3e 0a 0a 3c 70 3e 5e 45 78 63 65 70 74 20 66 6f  >..<p>^Except fo
c110: 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
c120: 5d 20 74 61 62 6c 65 73 2c 20 61 6c 6c 20 72 6f  ] tables, all ro
c130: 77 73 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  ws within SQLite
c140: 20 74 61 62 6c 65 73 0a 68 61 76 65 20 61 20 36   tables.have a 6
c150: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
c160: 65 67 65 72 20 6b 65 79 20 74 68 61 74 20 75 6e  eger key that un
c170: 69 71 75 65 6c 79 20 69 64 65 6e 74 69 66 69 65  iquely identifie
c180: 73 20 74 68 65 20 72 6f 77 20 77 69 74 68 69 6e  s the row within
c190: 20 69 74 73 20 74 61 62 6c 65 2e 0a 54 68 69 73   its table..This
c1a0: 20 69 6e 74 65 67 65 72 20 69 73 20 75 73 75 61   integer is usua
c1b0: 6c 6c 79 0a 63 61 6c 6c 65 64 20 74 68 65 20 22  lly.called the "
c1c0: 72 6f 77 69 64 22 2e 20 5e 54 68 65 20 72 6f 77  rowid". ^The row
c1d0: 69 64 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20  id value can be 
c1e0: 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 6f  accessed using o
c1f0: 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  ne of the specia
c200: 6c 0a 63 61 73 65 2d 69 6e 64 65 70 65 6e 64 65  l.case-independe
c210: 6e 74 20 6e 61 6d 65 73 20 22 72 6f 77 69 64 22  nt names "rowid"
c220: 2c 20 22 6f 69 64 22 2c 20 6f 72 20 22 5f 72 6f  , "oid", or "_ro
c230: 77 69 64 5f 22 20 69 6e 20 70 6c 61 63 65 20 6f  wid_" in place o
c240: 66 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  f a column name.
c250: 0a 5e 49 66 20 61 20 74 61 62 6c 65 20 63 6f 6e  .^If a table con
c260: 74 61 69 6e 73 20 61 20 75 73 65 72 20 64 65 66  tains a user def
c270: 69 6e 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ined column name
c280: 64 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  d "rowid", "oid"
c290: 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 2c 0a 74   or "_rowid_",.t
c2a0: 68 65 6e 20 74 68 61 74 20 6e 61 6d 65 20 61 6c  hen that name al
c2b0: 77 61 79 73 20 72 65 66 65 72 73 20 74 68 65 20  ways refers the 
c2c0: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
c2d0: 72 65 64 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 63  red column and c
c2e0: 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 0a 74 6f  annot be used.to
c2f0: 20 72 65 74 72 69 65 76 65 20 74 68 65 20 69 6e   retrieve the in
c300: 74 65 67 65 72 20 72 6f 77 69 64 20 76 61 6c 75  teger rowid valu
c310: 65 2e 0a 0a 3c 70 3e 54 68 65 20 72 6f 77 69 64  e...<p>The rowid
c320: 20 28 61 6e 64 20 22 6f 69 64 22 20 61 6e 64 20   (and "oid" and 
c330: 22 5f 72 6f 77 69 64 5f 22 29 20 69 73 20 6f 6d  "_rowid_") is om
c340: 69 74 74 65 64 20 69 6e 20 5b 57 49 54 48 4f 55  itted in [WITHOU
c350: 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 2e  T ROWID] tables.
c360: 0a 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 74  .WITHOUT ROWID t
c370: 61 62 6c 65 73 20 61 72 65 20 6f 6e 6c 79 20 61  ables are only a
c380: 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69  vailable in SQLi
c390: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 38 2e  te [version 3.8.
c3a0: 32 5d 0a 28 5b 64 61 74 65 6f 66 3a 33 2e 38 2e  2].([dateof:3.8.
c3b0: 32 5d 29 20 61 6e 64 20 6c 61 74 65 72 2e 0a 41  2]) and later..A
c3c0: 20 74 61 62 6c 65 20 74 68 61 74 20 6c 61 63 6b   table that lack
c3d0: 73 20 74 68 65 20 57 49 54 48 4f 55 54 20 52 4f  s the WITHOUT RO
c3e0: 57 49 44 20 63 6c 61 75 73 65 20 69 73 20 63 61  WID clause is ca
c3f0: 6c 6c 65 64 20 61 20 22 72 6f 77 69 64 20 74 61  lled a "rowid ta
c400: 62 6c 65 22 2e 0a 0a 3c 70 3e 54 68 65 20 64 61  ble"...<p>The da
c410: 74 61 20 66 6f 72 20 72 6f 77 69 64 20 74 61 62  ta for rowid tab
c420: 6c 65 73 20 69 73 20 73 74 6f 72 65 64 20 61 73  les is stored as
c430: 20 61 20 42 2d 54 72 65 65 20 73 74 72 75 63 74   a B-Tree struct
c440: 75 72 65 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 6f  ure containing.o
c450: 6e 65 20 65 6e 74 72 79 20 66 6f 72 20 65 61 63  ne entry for eac
c460: 68 20 74 61 62 6c 65 20 72 6f 77 2c 20 75 73 69  h table row, usi
c470: 6e 67 20 74 68 65 20 72 6f 77 69 64 20 76 61 6c  ng the rowid val
c480: 75 65 20 61 73 20 74 68 65 20 6b 65 79 2e 20 54  ue as the key. T
c490: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 0a 72  his means that.r
c4a0: 65 74 72 69 65 76 69 6e 67 20 6f 72 20 73 6f 72  etrieving or sor
c4b0: 74 69 6e 67 20 72 65 63 6f 72 64 73 20 62 79 20  ting records by 
c4c0: 72 6f 77 69 64 20 69 73 20 66 61 73 74 2e 20 53  rowid is fast. S
c4d0: 65 61 72 63 68 69 6e 67 20 66 6f 72 20 61 20 72  earching for a r
c4e0: 65 63 6f 72 64 20 77 69 74 68 20 61 0a 73 70 65  ecord with a.spe
c4f0: 63 69 66 69 63 20 72 6f 77 69 64 2c 20 6f 72 20  cific rowid, or 
c500: 66 6f 72 20 61 6c 6c 20 72 65 63 6f 72 64 73 20  for all records 
c510: 77 69 74 68 20 72 6f 77 69 64 73 20 77 69 74 68  with rowids with
c520: 69 6e 20 61 20 73 70 65 63 69 66 69 65 64 20 72  in a specified r
c530: 61 6e 67 65 20 69 73 0a 61 72 6f 75 6e 64 20 74  ange is.around t
c540: 77 69 63 65 20 61 73 20 66 61 73 74 20 61 73 20  wice as fast as 
c550: 61 20 73 69 6d 69 6c 61 72 20 73 65 61 72 63 68  a similar search
c560: 20 6d 61 64 65 20 62 79 20 73 70 65 63 69 66 79   made by specify
c570: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 50 52  ing any other PR
c580: 49 4d 41 52 59 0a 4b 45 59 20 6f 72 20 69 6e 64  IMARY.KEY or ind
c590: 65 78 65 64 20 76 61 6c 75 65 2e 0a 0a 3c 70 3e  exed value...<p>
c5a0: 20 5e 57 69 74 68 20 6f 6e 65 20 65 78 63 65 70   ^With one excep
c5b0: 74 69 6f 6e 20 6e 6f 74 65 64 20 62 65 6c 6f 77  tion noted below
c5c0: 2c 20 69 66 20 61 20 72 6f 77 69 64 20 74 61 62  , if a rowid tab
c5d0: 6c 65 20 68 61 73 20 61 20 70 72 69 6d 61 72 79  le has a primary
c5e0: 20 6b 65 79 20 74 68 61 74 20 63 6f 6e 73 69 73   key that consis
c5f0: 74 73 0a 6f 66 20 61 20 73 69 6e 67 6c 65 20 63  ts.of a single c
c600: 6f 6c 75 6d 6e 20 61 6e 64 20 74 68 65 20 64 65  olumn and the de
c610: 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
c620: 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 22 49  hat column is "I
c630: 4e 54 45 47 45 52 22 20 69 6e 20 61 6e 79 20 6d  NTEGER" in any m
c640: 69 78 74 75 72 65 20 6f 66 0a 75 70 70 65 72 20  ixture of.upper 
c650: 61 6e 64 20 6c 6f 77 65 72 20 63 61 73 65 2c 20  and lower case, 
c660: 74 68 65 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  then the column 
c670: 62 65 63 6f 6d 65 73 20 61 6e 20 61 6c 69 61 73  becomes an alias
c680: 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 20   for the rowid. 
c690: 53 75 63 68 20 61 0a 63 6f 6c 75 6d 6e 20 69 73  Such a.column is
c6a0: 20 75 73 75 61 6c 6c 79 20 72 65 66 65 72 72 65   usually referre
c6b0: 64 20 74 6f 20 61 73 20 61 6e 20 22 69 6e 74 65  d to as an "inte
c6c0: 67 65 72 20 70 72 69 6d 61 72 79 20 6b 65 79 22  ger primary key"
c6d0: 2e 20 41 20 50 52 49 4d 41 52 59 20 4b 45 59 20  . A PRIMARY KEY 
c6e0: 63 6f 6c 75 6d 6e 0a 6f 6e 6c 79 20 62 65 63 6f  column.only beco
c6f0: 6d 65 73 20 61 6e 20 69 6e 74 65 67 65 72 20 70  mes an integer p
c700: 72 69 6d 61 72 79 20 6b 65 79 20 69 66 20 74 68  rimary key if th
c710: 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
c720: 6e 61 6d 65 20 69 73 20 65 78 61 63 74 6c 79 0a  name is exactly.
c730: 22 49 4e 54 45 47 45 52 22 2e 20 20 5e 4f 74 68  "INTEGER".  ^Oth
c740: 65 72 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  er integer type 
c750: 6e 61 6d 65 73 20 6c 69 6b 65 20 22 49 4e 54 22  names like "INT"
c760: 20 6f 72 20 22 42 49 47 49 4e 54 22 20 6f 72 20   or "BIGINT" or 
c770: 22 53 48 4f 52 54 20 49 4e 54 45 47 45 52 22 0a  "SHORT INTEGER".
c780: 6f 72 20 22 55 4e 53 49 47 4e 45 44 20 49 4e 54  or "UNSIGNED INT
c790: 45 47 45 52 22 20 63 61 75 73 65 73 20 74 68 65  EGER" causes the
c7a0: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 63 6f 6c   primary key col
c7b0: 75 6d 6e 20 74 6f 20 62 65 68 61 76 65 20 61 73  umn to behave as
c7c0: 20 61 6e 20 6f 72 64 69 6e 61 72 79 0a 74 61 62   an ordinary.tab
c7d0: 6c 65 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20 69  le column with i
c7e0: 6e 74 65 67 65 72 20 5b 61 66 66 69 6e 69 74 79  nteger [affinity
c7f0: 5d 20 61 6e 64 20 61 20 75 6e 69 71 75 65 20 69  ] and a unique i
c800: 6e 64 65 78 2c 20 6e 6f 74 20 61 73 20 61 6e 20  ndex, not as an 
c810: 61 6c 69 61 73 20 66 6f 72 0a 74 68 65 20 72 6f  alias for.the ro
c820: 77 69 64 2e 0a 0a 3c 70 3e 20 54 68 65 20 65 78  wid...<p> The ex
c830: 63 65 70 74 69 6f 6e 20 6d 65 6e 74 69 6f 6e 65  ception mentione
c840: 64 20 61 62 6f 76 65 20 69 73 20 74 68 61 74 20  d above is that 
c850: 5e 69 66 20 74 68 65 20 64 65 63 6c 61 72 61 74  ^if the declarat
c860: 69 6f 6e 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20  ion of a column 
c870: 77 69 74 68 0a 64 65 63 6c 61 72 65 64 20 74 79  with.declared ty
c880: 70 65 20 22 49 4e 54 45 47 45 52 22 20 69 6e 63  pe "INTEGER" inc
c890: 6c 75 64 65 73 20 61 6e 20 22 50 52 49 4d 41 52  ludes an "PRIMAR
c8a0: 59 20 4b 45 59 20 44 45 53 43 22 20 63 6c 61 75  Y KEY DESC" clau
c8b0: 73 65 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 0a  se, it does not.
c8c0: 62 65 63 6f 6d 65 20 61 6e 20 61 6c 69 61 73 20  become an alias 
c8d0: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 20 61 6e  for the rowid an
c8e0: 64 20 69 73 20 6e 6f 74 20 63 6c 61 73 73 69 66  d is not classif
c8f0: 69 65 64 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ied as an intege
c900: 72 20 70 72 69 6d 61 72 79 20 6b 65 79 2e 0a 54  r primary key..T
c910: 68 69 73 20 71 75 69 72 6b 20 69 73 20 6e 6f 74  his quirk is not
c920: 20 62 79 20 64 65 73 69 67 6e 2e 20 49 74 20 69   by design. It i
c930: 73 20 64 75 65 20 74 6f 20 61 20 62 75 67 20 69  s due to a bug i
c940: 6e 20 65 61 72 6c 79 20 76 65 72 73 69 6f 6e 73  n early versions
c950: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 42 75 74 20   of SQLite..But 
c960: 66 69 78 69 6e 67 20 74 68 65 20 62 75 67 20 63  fixing the bug c
c970: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 62  ould result in b
c980: 61 63 6b 77 61 72 64 73 20 69 6e 63 6f 6d 70 61  ackwards incompa
c990: 74 69 62 69 6c 69 74 69 65 73 2e 0a 48 65 6e 63  tibilities..Henc
c9a0: 65 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  e, the original 
c9b0: 62 65 68 61 76 69 6f 72 20 68 61 73 20 62 65 65  behavior has bee
c9c0: 6e 20 72 65 74 61 69 6e 65 64 20 28 61 6e 64 20  n retained (and 
c9d0: 64 6f 63 75 6d 65 6e 74 65 64 29 20 62 65 63 61  documented) beca
c9e0: 75 73 65 20 6f 64 64 0a 62 65 68 61 76 69 6f 72  use odd.behavior
c9f0: 20 69 6e 20 61 20 63 6f 72 6e 65 72 20 63 61 73   in a corner cas
ca00: 65 20 69 73 20 66 61 72 20 62 65 74 74 65 72 20  e is far better 
ca10: 74 68 61 6e 20 61 20 63 6f 6d 70 61 74 69 62 69  than a compatibi
ca20: 6c 69 74 79 20 62 72 65 61 6b 2e 20 20 54 68 69  lity break.  Thi
ca30: 73 20 6d 65 61 6e 73 0a 74 68 61 74 20 5e 28 74  s means.that ^(t
ca40: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
ca50: 65 65 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  ee table declara
ca60: 74 69 6f 6e 73 20 61 6c 6c 20 63 61 75 73 65 20  tions all cause 
ca70: 74 68 65 20 63 6f 6c 75 6d 6e 20 22 78 22 20 74  the column "x" t
ca80: 6f 20 62 65 20 61 6e 0a 61 6c 69 61 73 20 66 6f  o be an.alias fo
ca90: 72 20 74 68 65 20 72 6f 77 69 64 20 28 61 6e 20  r the rowid (an 
caa0: 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79 20  integer primary 
cab0: 6b 65 79 29 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  key):..<ul>.<li>
cac0: 3c 74 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45  <tt>CREATE TABLE
cad0: 20 74 28 78 20 49 4e 54 45 47 45 52 20 50 52 49   t(x INTEGER PRI
cae0: 4d 41 52 59 20 4b 45 59 20 41 53 43 2c 20 79 2c  MARY KEY ASC, y,
caf0: 20 7a 29 3b 3c 2f 74 74 3e 0a 3c 6c 69 3e 3c 74   z);</tt>.<li><t
cb00: 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  t>CREATE TABLE t
cb10: 28 78 20 49 4e 54 45 47 45 52 2c 20 79 2c 20 7a  (x INTEGER, y, z
cb20: 2c 20 50 52 49 4d 41 52 59 20 4b 45 59 28 78 20  , PRIMARY KEY(x 
cb30: 41 53 43 29 29 3b 3c 2f 74 74 3e 0a 3c 6c 69 3e  ASC));</tt>.<li>
cb40: 3c 74 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45  <tt>CREATE TABLE
cb50: 20 74 28 78 20 49 4e 54 45 47 45 52 2c 20 79 2c   t(x INTEGER, y,
cb60: 20 7a 2c 20 50 52 49 4d 41 52 59 20 4b 45 59 28   z, PRIMARY KEY(
cb70: 78 20 44 45 53 43 29 29 3b 3c 2f 74 74 3e 0a 3c  x DESC));</tt>.<
cb80: 2f 75 6c 3e 29 5e 0a 0a 3c 70 3e 42 75 74 20 5e  /ul>)^..<p>But ^
cb90: 28 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64  (the following d
cba0: 65 63 6c 61 72 61 74 69 6f 6e 20 64 6f 65 73 20  eclaration does 
cbb0: 6e 6f 74 20 72 65 73 75 6c 74 20 69 6e 20 22 78  not result in "x
cbc0: 22 20 62 65 69 6e 67 20 61 6e 20 61 6c 69 61 73  " being an alias
cbd0: 20 66 6f 72 0a 74 68 65 20 72 6f 77 69 64 3a 0a   for.the rowid:.
cbe0: 3c 75 6c 3e 0a 3c 6c 69 3e 3c 74 74 3e 43 52 45  <ul>.<li><tt>CRE
cbf0: 41 54 45 20 54 41 42 4c 45 20 74 28 78 20 49 4e  ATE TABLE t(x IN
cc00: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
cc10: 59 20 44 45 53 43 2c 20 79 2c 20 7a 29 3b 3c 2f  Y DESC, y, z);</
cc20: 74 74 3e 0a 3c 2f 75 6c 3e 29 5e 0a 0a 3c 70 3e  tt>.</ul>)^..<p>
cc30: 5e 52 6f 77 69 64 20 76 61 6c 75 65 73 20 6d 61  ^Rowid values ma
cc40: 79 20 62 65 20 6d 6f 64 69 66 69 65 64 20 75 73  y be modified us
cc50: 69 6e 67 20 61 6e 20 55 50 44 41 54 45 20 73 74  ing an UPDATE st
cc60: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 73  atement in the s
cc70: 61 6d 65 0a 77 61 79 20 61 73 20 61 6e 79 20 6f  ame.way as any o
cc80: 74 68 65 72 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ther column valu
cc90: 65 20 63 61 6e 2c 20 65 69 74 68 65 72 20 75 73  e can, either us
cca0: 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 62  ing one of the b
ccb0: 75 69 6c 74 2d 69 6e 20 61 6c 69 61 73 65 73 0a  uilt-in aliases.
ccc0: 28 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20  ("rowid", "oid" 
ccd0: 6f 72 20 22 5f 72 6f 77 69 64 5f 22 29 20 6f 72  or "_rowid_") or
cce0: 20 62 79 20 75 73 69 6e 67 20 61 6e 20 61 6c 69   by using an ali
ccf0: 61 73 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  as created by an
cd00: 20 69 6e 74 65 67 65 72 0a 70 72 69 6d 61 72 79   integer.primary
cd10: 20 6b 65 79 2e 20 5e 53 69 6d 69 6c 61 72 6c 79   key. ^Similarly
cd20: 2c 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74  , an INSERT stat
cd30: 65 6d 65 6e 74 20 6d 61 79 20 70 72 6f 76 69 64  ement may provid
cd40: 65 20 61 20 76 61 6c 75 65 20 74 6f 20 75 73 65  e a value to use
cd50: 20 61 73 20 74 68 65 0a 72 6f 77 69 64 20 66 6f   as the.rowid fo
cd60: 72 20 65 61 63 68 20 72 6f 77 20 69 6e 73 65 72  r each row inser
cd70: 74 65 64 2e 20 5e 28 55 6e 6c 69 6b 65 20 6e 6f  ted. ^(Unlike no
cd80: 72 6d 61 6c 20 53 51 4c 69 74 65 20 63 6f 6c 75  rmal SQLite colu
cd90: 6d 6e 73 2c 20 61 6e 20 69 6e 74 65 67 65 72 20  mns, an integer 
cda0: 70 72 69 6d 61 72 79 0a 6b 65 79 20 6f 72 20 72  primary.key or r
cdb0: 6f 77 69 64 20 63 6f 6c 75 6d 6e 20 6d 75 73 74  owid column must
cdc0: 20 63 6f 6e 74 61 69 6e 20 69 6e 74 65 67 65 72   contain integer
cdd0: 20 76 61 6c 75 65 73 2e 20 49 6e 74 65 67 65 72   values. Integer
cde0: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 6f 72 20   primary key or 
cdf0: 72 6f 77 69 64 0a 63 6f 6c 75 6d 6e 73 20 61 72  rowid.columns ar
ce00: 65 20 6e 6f 74 20 61 62 6c 65 20 74 6f 20 68 6f  e not able to ho
ce10: 6c 64 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ld floating poin
ce20: 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
ce30: 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
ce40: 4c 73 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 61 6e  Ls.)^..<p>^If an
ce50: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
ce60: 74 20 61 74 74 65 6d 70 74 73 20 74 6f 20 73 65  t attempts to se
ce70: 74 20 61 6e 20 69 6e 74 65 67 65 72 20 70 72 69  t an integer pri
ce80: 6d 61 72 79 20 6b 65 79 20 6f 72 20 72 6f 77 69  mary key or rowi
ce90: 64 20 63 6f 6c 75 6d 6e 0a 74 6f 20 61 20 4e 55  d column.to a NU
cea0: 4c 4c 20 6f 72 20 62 6c 6f 62 20 76 61 6c 75 65  LL or blob value
ceb0: 2c 20 6f 72 20 74 6f 20 61 20 73 74 72 69 6e 67  , or to a string
cec0: 20 6f 72 20 72 65 61 6c 20 76 61 6c 75 65 20 74   or real value t
ced0: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 6c 6f  hat cannot be lo
cee0: 73 73 6c 65 73 73 6c 79 0a 63 6f 6e 76 65 72 74  sslessly.convert
cef0: 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ed to an integer
cf00: 2c 20 61 20 22 64 61 74 61 74 79 70 65 20 6d 69  , a "datatype mi
cf10: 73 6d 61 74 63 68 22 20 65 72 72 6f 72 20 6f 63  smatch" error oc
cf20: 63 75 72 73 20 61 6e 64 20 74 68 65 20 73 74 61  curs and the sta
cf30: 74 65 6d 65 6e 74 0a 69 73 20 61 62 6f 72 74 65  tement.is aborte
cf40: 64 2e 20 5e 49 66 20 61 6e 20 49 4e 53 45 52 54  d. ^If an INSERT
cf50: 20 73 74 61 74 65 6d 65 6e 74 20 61 74 74 65 6d   statement attem
cf60: 70 74 73 20 74 6f 20 69 6e 73 65 72 74 20 61 20  pts to insert a 
cf70: 62 6c 6f 62 20 76 61 6c 75 65 2c 20 6f 72 20 61  blob value, or a
cf80: 20 73 74 72 69 6e 67 0a 6f 72 20 72 65 61 6c 20   string.or real 
cf90: 76 61 6c 75 65 20 74 68 61 74 20 63 61 6e 6e 6f  value that canno
cfa0: 74 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 20  t be losslessly 
cfb0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20  converted to an 
cfc0: 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 61 6e 0a  integer into an.
cfd0: 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79 20  integer primary 
cfe0: 6b 65 79 20 6f 72 20 72 6f 77 69 64 20 63 6f 6c  key or rowid col
cff0: 75 6d 6e 2c 20 61 20 22 64 61 74 61 74 79 70 65  umn, a "datatype
d000: 20 6d 69 73 6d 61 74 63 68 22 20 65 72 72 6f 72   mismatch" error
d010: 20 6f 63 63 75 72 73 20 61 6e 64 20 74 68 65 0a   occurs and the.
d020: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 62 6f  statement is abo
d030: 72 74 65 64 2e 0a 0a 3c 70 3e 5e 49 66 20 61 6e  rted...<p>^If an
d040: 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e   INSERT statemen
d050: 74 20 61 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  t attempts to in
d060: 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
d070: 65 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 6f  e into a rowid o
d080: 72 0a 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72  r.integer primar
d090: 79 20 6b 65 79 20 63 6f 6c 75 6d 6e 2c 20 74 68  y key column, th
d0a0: 65 20 73 79 73 74 65 6d 20 63 68 6f 6f 73 65 73  e system chooses
d0b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75   an integer valu
d0c0: 65 20 74 6f 20 75 73 65 20 61 73 20 74 68 65 0a  e to use as the.
d0d0: 72 6f 77 69 64 20 61 75 74 6f 6d 61 74 69 63 61  rowid automatica
d0e0: 6c 6c 79 2e 20 41 20 64 65 74 61 69 6c 65 64 20  lly. A detailed 
d0f0: 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 68  description of h
d100: 6f 77 20 74 68 69 73 20 69 73 20 64 6f 6e 65 20  ow this is done 
d110: 69 73 20 70 72 6f 76 69 64 65 64 0a 3c 61 20 68  is provided.<a h
d120: 72 65 66 3d 22 61 75 74 6f 69 6e 63 2e 68 74 6d  ref="autoinc.htm
d130: 6c 22 3e 73 65 70 61 72 61 74 65 6c 79 3c 2f 61  l">separately</a
d140: 3e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 28 54 68 65  >.</p>..<p>^(The
d150: 20 5b 70 61 72 65 6e 74 20 6b 65 79 5d 20 6f 66   [parent key] of
d160: 20 61 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20   a [foreign key 
d170: 63 6f 6e 73 74 72 61 69 6e 74 5d 20 69 73 20 6e  constraint] is n
d180: 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 75 73  ot allowed to.us
d190: 65 20 74 68 65 20 72 6f 77 69 64 2e 20 20 54 68  e the rowid.  Th
d1a0: 65 20 70 61 72 65 6e 74 20 6b 65 79 20 6d 75 73  e parent key mus
d1b0: 74 20 75 73 65 64 20 6e 61 6d 65 64 20 63 6f 6c  t used named col
d1c0: 75 6d 6e 73 20 6f 6e 6c 79 2e 29 5e 3c 2f 70 3e  umns only.)^</p>
d1d0: 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
d1e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
d1f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
d200: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
d210: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
d220: 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b  ######.Section {
d230: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 7d 20  CREATE TRIGGER} 
d240: 63 72 65 61 74 65 74 72 69 67 67 65 72 20 7b 7b  createtrigger {{
d250: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 7d 7d  CREATE TRIGGER}}
d260: 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  ..RecursiveBubbl
d270: 65 44 69 61 67 72 61 6d 20 63 72 65 61 74 65 2d  eDiagram create-
d280: 74 72 69 67 67 65 72 2d 73 74 6d 74 0a 3c 2f 74  trigger-stmt.</t
d290: 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 43 52 45  cl>..<p>^The CRE
d2a0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
d2b0: 65 6d 65 6e 74 20 69 73 20 75 73 65 64 20 74 6f  ement is used to
d2c0: 20 61 64 64 20 74 72 69 67 67 65 72 73 20 74 6f   add triggers to
d2d0: 20 74 68 65 20 0a 64 61 74 61 62 61 73 65 20 73   the .database s
d2e0: 63 68 65 6d 61 2e 20 5e 54 72 69 67 67 65 72 73  chema. ^Triggers
d2f0: 20 61 72 65 20 64 61 74 61 62 61 73 65 20 6f 70   are database op
d300: 65 72 61 74 69 6f 6e 73 20 0a 74 68 61 74 20 61  erations .that a
d310: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
d320: 20 70 65 72 66 6f 72 6d 65 64 20 77 68 65 6e 20   performed when 
d330: 61 20 73 70 65 63 69 66 69 65 64 20 64 61 74 61  a specified data
d340: 62 61 73 65 20 65 76 65 6e 74 0a 6f 63 63 75 72  base event.occur
d350: 73 2e 20 20 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41 20  s.  </p>..<p>^A 
d360: 74 72 69 67 67 65 72 20 6d 61 79 20 62 65 20 73  trigger may be s
d370: 70 65 63 69 66 69 65 64 20 74 6f 20 66 69 72 65  pecified to fire
d380: 20 77 68 65 6e 65 76 65 72 20 61 20 5b 44 45 4c   whenever a [DEL
d390: 45 54 45 5d 2c 20 5b 49 4e 53 45 52 54 5d 2c 0a  ETE], [INSERT],.
d3a0: 6f 72 20 5b 55 50 44 41 54 45 5d 20 6f 66 20 61  or [UPDATE] of a
d3b0: 0a 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61  .particular data
d3c0: 62 61 73 65 20 74 61 62 6c 65 20 6f 63 63 75 72  base table occur
d3d0: 73 2c 20 6f 72 20 77 68 65 6e 65 76 65 72 20 61  s, or whenever a
d3e0: 6e 20 5b 55 50 44 41 54 45 5d 20 6f 63 63 75 72  n [UPDATE] occur
d3f0: 73 20 6f 6e 0a 6f 6e 20 6f 6e 65 20 6f 72 20 6d  s on.on one or m
d400: 6f 72 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  ore specified co
d410: 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
d420: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41 74 20 74 68  .</p>..<p>^At th
d430: 69 73 20 74 69 6d 65 20 53 51 4c 69 74 65 20 73  is time SQLite s
d440: 75 70 70 6f 72 74 73 20 6f 6e 6c 79 20 46 4f 52  upports only FOR
d450: 20 45 41 43 48 20 52 4f 57 20 74 72 69 67 67 65   EACH ROW trigge
d460: 72 73 2c 20 6e 6f 74 20 46 4f 52 20 45 41 43 48  rs, not FOR EACH
d470: 0a 53 54 41 54 45 4d 45 4e 54 20 74 72 69 67 67  .STATEMENT trigg
d480: 65 72 73 2e 20 5e 48 65 6e 63 65 20 65 78 70 6c  ers. ^Hence expl
d490: 69 63 69 74 6c 79 20 73 70 65 63 69 66 79 69 6e  icitly specifyin
d4a0: 67 20 46 4f 52 20 45 41 43 48 20 52 4f 57 20 69  g FOR EACH ROW i
d4b0: 73 20 6f 70 74 69 6f 6e 61 6c 2e 0a 5e 46 4f 52  s optional..^FOR
d4c0: 20 45 41 43 48 20 52 4f 57 20 69 6d 70 6c 69 65   EACH ROW implie
d4d0: 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  s that the SQL s
d4e0: 74 61 74 65 6d 65 6e 74 73 20 73 70 65 63 69 66  tatements specif
d4f0: 69 65 64 20 69 6e 20 74 68 65 20 74 72 69 67 67  ied in the trigg
d500: 65 72 0a 6d 61 79 20 62 65 20 65 78 65 63 75 74  er.may be execut
d510: 65 64 20 28 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ed (depending on
d520: 20 74 68 65 20 57 48 45 4e 20 63 6c 61 75 73 65   the WHEN clause
d530: 29 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  ) for each datab
d540: 61 73 65 20 72 6f 77 20 62 65 69 6e 67 0a 69 6e  ase row being.in
d550: 73 65 72 74 65 64 2c 20 75 70 64 61 74 65 64 20  serted, updated 
d560: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
d570: 65 20 73 74 61 74 65 6d 65 6e 74 20 63 61 75 73  e statement caus
d580: 69 6e 67 20 74 68 65 20 74 72 69 67 67 65 72 20  ing the trigger 
d590: 74 6f 20 66 69 72 65 2e 3c 2f 70 3e 0a 0a 3c 70  to fire.</p>..<p
d5a0: 3e 5e 28 42 6f 74 68 20 74 68 65 20 57 48 45 4e  >^(Both the WHEN
d5b0: 20 63 6c 61 75 73 65 20 61 6e 64 20 74 68 65 20   clause and the 
d5c0: 74 72 69 67 67 65 72 20 61 63 74 69 6f 6e 73 20  trigger actions 
d5d0: 6d 61 79 20 61 63 63 65 73 73 20 65 6c 65 6d 65  may access eleme
d5e0: 6e 74 73 20 6f 66 20 0a 74 68 65 20 72 6f 77 20  nts of .the row 
d5f0: 62 65 69 6e 67 20 69 6e 73 65 72 74 65 64 2c 20  being inserted, 
d600: 64 65 6c 65 74 65 64 20 6f 72 20 75 70 64 61 74  deleted or updat
d610: 65 64 20 75 73 69 6e 67 20 72 65 66 65 72 65 6e  ed using referen
d620: 63 65 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ces of the form 
d630: 0a 22 4e 45 57 2e 3c 69 3e 63 6f 6c 75 6d 6e 2d  ."NEW.<i>column-
d640: 6e 61 6d 65 3c 2f 69 3e 22 20 61 6e 64 20 22 4f  name</i>" and "O
d650: 4c 44 2e 3c 69 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d  LD.<i>column-nam
d660: 65 3c 2f 69 3e 22 2c 20 77 68 65 72 65 0a 3c 69  e</i>", where.<i
d670: 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 69 3e  >column-name</i>
d680: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
d690: 61 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 74 68  a column from th
d6a0: 65 20 74 61 62 6c 65 20 74 68 61 74 20 74 68 65  e table that the
d6b0: 20 74 72 69 67 67 65 72 0a 69 73 20 61 73 73 6f   trigger.is asso
d6c0: 63 69 61 74 65 64 20 77 69 74 68 2e 29 5e 20 5e  ciated with.)^ ^
d6d0: 28 4f 4c 44 20 61 6e 64 20 4e 45 57 20 72 65 66  (OLD and NEW ref
d6e0: 65 72 65 6e 63 65 73 20 6d 61 79 20 6f 6e 6c 79  erences may only
d6f0: 20 62 65 20 75 73 65 64 20 69 6e 20 74 72 69 67   be used in trig
d700: 67 65 72 73 20 6f 6e 0a 65 76 65 6e 74 73 20 66  gers on.events f
d710: 6f 72 20 77 68 69 63 68 20 74 68 65 79 20 61 72  or which they ar
d720: 65 20 72 65 6c 65 76 61 6e 74 2c 20 61 73 20 66  e relevant, as f
d730: 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 74 61  ollows:</p>..<ta
d740: 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c  ble border=0 cel
d750: 6c 70 61 64 64 69 6e 67 3d 31 30 3e 0a 3c 74 72  lpadding=10>.<tr
d760: 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  >.<td valign="to
d770: 70 22 20 61 6c 69 67 6e 3d 22 72 69 67 68 74 22  p" align="right"
d780: 20 77 69 64 74 68 3d 31 32 30 3e 3c 69 3e 49 4e   width=120><i>IN
d790: 53 45 52 54 3c 2f 69 3e 3c 2f 74 64 3e 0a 3c 74  SERT</i></td>.<t
d7a0: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 4e  d valign="top">N
d7b0: 45 57 20 72 65 66 65 72 65 6e 63 65 73 20 61 72  EW references ar
d7c0: 65 20 76 61 6c 69 64 3c 2f 74 64 3e 0a 3c 2f 74  e valid</td>.</t
d7d0: 72 3e 0a 3c 74 72 3e 0a 3c 74 64 20 76 61 6c 69  r>.<tr>.<td vali
d7e0: 67 6e 3d 22 74 6f 70 22 20 61 6c 69 67 6e 3d 22  gn="top" align="
d7f0: 72 69 67 68 74 22 20 77 69 64 74 68 3d 31 32 30  right" width=120
d800: 3e 3c 69 3e 55 50 44 41 54 45 3c 2f 69 3e 3c 2f  ><i>UPDATE</i></
d810: 74 64 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22  td>.<td valign="
d820: 74 6f 70 22 3e 4e 45 57 20 61 6e 64 20 4f 4c 44  top">NEW and OLD
d830: 20 72 65 66 65 72 65 6e 63 65 73 20 61 72 65 20   references are 
d840: 76 61 6c 69 64 3c 2f 74 64 3e 0a 3c 2f 74 72 3e  valid</td>.</tr>
d850: 0a 3c 74 72 3e 0a 3c 74 64 20 76 61 6c 69 67 6e  .<tr>.<td valign
d860: 3d 22 74 6f 70 22 20 61 6c 69 67 6e 3d 22 72 69  ="top" align="ri
d870: 67 68 74 22 20 77 69 64 74 68 3d 31 32 30 3e 3c  ght" width=120><
d880: 69 3e 44 45 4c 45 54 45 3c 2f 69 3e 3c 2f 74 64  i>DELETE</i></td
d890: 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  >.<td valign="to
d8a0: 70 22 3e 4f 4c 44 20 72 65 66 65 72 65 6e 63 65  p">OLD reference
d8b0: 73 20 61 72 65 20 76 61 6c 69 64 3c 2f 74 64 3e  s are valid</td>
d8c0: 0a 3c 2f 74 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a  .</tr>.</table>.
d8d0: 3c 2f 70 3e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 61  </p>)^..<p>^If a
d8e0: 20 57 48 45 4e 20 63 6c 61 75 73 65 20 69 73 20   WHEN clause is 
d8f0: 73 75 70 70 6c 69 65 64 2c 20 74 68 65 20 53 51  supplied, the SQ
d900: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 70 65  L statements spe
d910: 63 69 66 69 65 64 0a 61 72 65 20 6f 6e 6c 79 20  cified.are only 
d920: 65 78 65 63 75 74 65 64 20 69 66 20 74 68 65 20  executed if the 
d930: 57 48 45 4e 20 63 6c 61 75 73 65 20 69 73 20 74  WHEN clause is t
d940: 72 75 65 2e 0a 5e 49 66 20 6e 6f 20 57 48 45 4e  rue..^If no WHEN
d950: 20 63 6c 61 75 73 65 20 69 73 20 73 75 70 70 6c   clause is suppl
d960: 69 65 64 2c 20 74 68 65 20 53 51 4c 20 73 74 61  ied, the SQL sta
d970: 74 65 6d 65 6e 74 73 0a 61 72 65 20 65 78 65 63  tements.are exec
d980: 75 74 65 64 20 65 76 65 72 79 20 74 69 6d 65 20  uted every time 
d990: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
d9a0: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  s.</p>..<p>^The 
d9b0: 42 45 46 4f 52 45 20 6f 72 20 41 46 54 45 52 20  BEFORE or AFTER 
d9c0: 6b 65 79 77 6f 72 64 20 64 65 74 65 72 6d 69 6e  keyword determin
d9d0: 65 73 20 77 68 65 6e 20 74 68 65 20 74 72 69 67  es when the trig
d9e0: 67 65 72 20 61 63 74 69 6f 6e 73 0a 77 69 6c 6c  ger actions.will
d9f0: 20 62 65 20 65 78 65 63 75 74 65 64 20 72 65 6c   be executed rel
da00: 61 74 69 76 65 20 74 6f 20 74 68 65 20 69 6e 73  ative to the ins
da10: 65 72 74 69 6f 6e 2c 20 6d 6f 64 69 66 69 63 61  ertion, modifica
da20: 74 69 6f 6e 20 6f 72 20 72 65 6d 6f 76 61 6c 20  tion or removal 
da30: 6f 66 20 74 68 65 0a 61 73 73 6f 63 69 61 74 65  of the.associate
da40: 64 20 72 6f 77 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  d row.</p>..<p>^
da50: 41 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  An [ON CONFLICT]
da60: 20 63 6c 61 75 73 65 20 6d 61 79 20 62 65 20 73   clause may be s
da70: 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
da80: 20 6f 66 20 61 6e 20 5b 55 50 44 41 54 45 5d 20   of an [UPDATE] 
da90: 6f 72 20 5b 49 4e 53 45 52 54 5d 0a 61 63 74 69  or [INSERT].acti
daa0: 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  on within the bo
dab0: 64 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 65  dy of the trigge
dac0: 72 2e 0a 5e 48 6f 77 65 76 65 72 20 69 66 20 61  r..^However if a
dad0: 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  n [ON CONFLICT] 
dae0: 63 6c 61 75 73 65 20 69 73 20 73 70 65 63 69 66  clause is specif
daf0: 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 0a  ied as part of .
db00: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 63 61  the statement ca
db10: 75 73 69 6e 67 20 74 68 65 20 74 72 69 67 67 65  using the trigge
db20: 72 20 74 6f 20 66 69 72 65 2c 20 74 68 65 6e 20  r to fire, then 
db30: 63 6f 6e 66 6c 69 63 74 20 68 61 6e 64 6c 69 6e  conflict handlin
db40: 67 0a 70 6f 6c 69 63 79 20 6f 66 20 74 68 65 20  g.policy of the 
db50: 6f 75 74 65 72 20 73 74 61 74 65 6d 65 6e 74 20  outer statement 
db60: 69 73 20 75 73 65 64 20 69 6e 73 74 65 61 64 2e  is used instead.
db70: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 72 69 67 67 65  </p>..<p>^Trigge
db80: 72 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  rs are automatic
db90: 61 6c 6c 79 20 5b 44 52 4f 50 20 54 52 49 47 47  ally [DROP TRIGG
dba0: 45 52 20 7c 20 64 72 6f 70 70 65 64 5d 0a 77 68  ER | dropped].wh
dbb0: 65 6e 20 74 68 65 20 74 61 62 6c 65 20 74 68 61  en the table tha
dbc0: 74 20 74 68 65 79 20 61 72 65 20 0a 61 73 73 6f  t they are .asso
dbd0: 63 69 61 74 65 64 20 77 69 74 68 20 28 74 68 65  ciated with (the
dbe0: 20 3c 69 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f   <i>table-name</
dbf0: 69 3e 20 74 61 62 6c 65 29 20 69 73 20 0a 5b 44  i> table) is .[D
dc00: 52 4f 50 20 54 41 42 4c 45 20 7c 20 64 72 6f 70  ROP TABLE | drop
dc10: 70 65 64 5d 2e 20 20 5e 48 6f 77 65 76 65 72 20  ped].  ^However 
dc20: 69 66 20 74 68 65 20 74 72 69 67 67 65 72 20 61  if the trigger a
dc30: 63 74 69 6f 6e 73 20 72 65 66 65 72 65 6e 63 65  ctions reference
dc40: 0a 6f 74 68 65 72 20 74 61 62 6c 65 73 2c 20 74  .other tables, t
dc50: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 6e 6f  he trigger is no
dc60: 74 20 64 72 6f 70 70 65 64 20 6f 72 20 6d 6f 64  t dropped or mod
dc70: 69 66 69 65 64 20 69 66 20 74 68 6f 73 65 20 6f  ified if those o
dc80: 74 68 65 72 0a 74 61 62 6c 65 73 20 61 72 65 20  ther.tables are 
dc90: 5b 44 52 4f 50 20 54 41 42 4c 45 20 7c 20 64 72  [DROP TABLE | dr
dca0: 6f 70 70 65 64 5d 20 6f 72 20 5b 41 4c 54 45 52  opped] or [ALTER
dcb0: 20 54 41 42 4c 45 20 7c 20 6d 6f 64 69 66 69 65   TABLE | modifie
dcc0: 64 5d 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 72 69  d].</p>..<p>^Tri
dcd0: 67 67 65 72 73 20 61 72 65 20 72 65 6d 6f 76 65  ggers are remove
dce0: 64 20 75 73 69 6e 67 20 74 68 65 20 5b 44 52 4f  d using the [DRO
dcf0: 50 20 54 52 49 47 47 45 52 5d 20 73 74 61 74 65  P TRIGGER] state
dd00: 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 53  ment.</p>..<h3>S
dd10: 79 6e 74 61 78 20 52 65 73 74 72 69 63 74 69 6f  yntax Restrictio
dd20: 6e 73 20 4f 6e 20 55 50 44 41 54 45 2c 20 44 45  ns On UPDATE, DE
dd30: 4c 45 54 45 2c 20 61 6e 64 20 49 4e 53 45 52 54  LETE, and INSERT
dd40: 20 53 74 61 74 65 6d 65 6e 74 73 20 57 69 74 68   Statements With
dd50: 69 6e 0a 20 20 20 20 54 72 69 67 67 65 72 73 3c  in.    Triggers<
dd60: 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b 55  /h3>..<p>^The [U
dd70: 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
dd80: 2c 20 61 6e 64 20 5b 49 4e 53 45 52 54 5d 0a 73  , and [INSERT].s
dd90: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e  tatements within
dda0: 20 74 72 69 67 67 65 72 73 20 64 6f 20 6e 6f 74   triggers do not
ddb0: 20 73 75 70 70 6f 72 74 0a 74 68 65 20 66 75 6c   support.the ful
ddc0: 6c 20 73 79 6e 74 61 78 20 66 6f 72 20 5b 55 50  l syntax for [UP
ddd0: 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c  DATE], [DELETE],
dde0: 20 61 6e 64 20 5b 49 4e 53 45 52 54 5d 20 73 74   and [INSERT] st
ddf0: 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 66  atements.  The f
de00: 6f 6c 6c 6f 77 69 6e 67 0a 72 65 73 74 72 69 63  ollowing.restric
de10: 74 69 6f 6e 73 20 61 70 70 6c 79 3a 3c 2f 70 3e  tions apply:</p>
de20: 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 20  ..<ul>.<li><p>. 
de30: 20 5e 28 54 68 65 20 6e 61 6d 65 20 6f 66 20 74   ^(The name of t
de40: 68 65 20 74 61 62 6c 65 20 74 6f 20 62 65 20 6d  he table to be m
de50: 6f 64 69 66 69 65 64 20 69 6e 20 61 6e 20 5b 55  odified in an [U
de60: 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
de70: 2c 20 6f 72 20 5b 49 4e 53 45 52 54 5d 0a 20 20  , or [INSERT].  
de80: 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 62  statement must b
de90: 65 20 61 6e 20 75 6e 71 75 61 6c 69 66 69 65 64  e an unqualified
dea0: 20 74 61 62 6c 65 20 6e 61 6d 65 2e 20 20 49 6e   table name.  In
deb0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 6f 6e   other words, on
dec0: 65 20 6d 75 73 74 0a 20 20 75 73 65 20 6a 75 73  e must.  use jus
ded0: 74 20 22 3c 69 3e 74 61 62 6c 65 6e 61 6d 65 3c  t "<i>tablename<
dee0: 2f 69 3e 22 20 6e 6f 74 20 22 3c 69 3e 64 61 74  /i>" not "<i>dat
def0: 61 62 61 73 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62  abase</i><b>.</b
df00: 3e 3c 69 3e 74 61 62 6c 65 6e 61 6d 65 3c 2f 69  ><i>tablename</i
df10: 3e 22 0a 20 20 77 68 65 6e 20 73 70 65 63 69 66  >".  when specif
df20: 79 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 29  ying the table.)
df30: 5e 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69  ^ </p></li>..<li
df40: 3e 3c 70 3e 0a 20 5e 46 6f 72 20 6e 6f 6e 2d 54  ><p>. ^For non-T
df50: 45 4d 50 20 74 72 69 67 67 65 72 73 2c 0a 20 20  EMP triggers,.  
df60: 74 68 65 20 74 61 62 6c 65 20 74 6f 20 62 65 20  the table to be 
df70: 6d 6f 64 69 66 69 65 64 20 6f 72 20 71 75 65 72  modified or quer
df80: 69 65 64 20 6d 75 73 74 20 65 78 69 73 74 20 69  ied must exist i
df90: 6e 20 74 68 65 0a 20 20 73 61 6d 65 20 64 61 74  n the.  same dat
dfa0: 61 62 61 73 65 20 61 73 20 74 68 65 20 74 61 62  abase as the tab
dfb0: 6c 65 20 6f 72 20 76 69 65 77 20 74 6f 20 77 68  le or view to wh
dfc0: 69 63 68 20 74 68 65 20 74 72 69 67 67 65 72 20  ich the trigger 
dfd0: 69 73 20 61 74 74 61 63 68 65 64 2e 0a 20 20 5e  is attached..  ^
dfe0: 28 54 45 4d 50 20 74 72 69 67 67 65 72 73 20 61  (TEMP triggers a
dff0: 72 65 20 6e 6f 74 20 73 75 62 6a 65 63 74 20 74  re not subject t
e000: 6f 20 74 68 65 20 73 61 6d 65 2d 64 61 74 61 62  o the same-datab
e010: 61 73 65 20 72 75 6c 65 2e 20 20 41 20 54 45 4d  ase rule.  A TEM
e020: 50 0a 20 20 74 72 69 67 67 65 72 20 69 73 20 61  P.  trigger is a
e030: 6c 6c 6f 77 65 64 20 74 6f 20 71 75 65 72 79 20  llowed to query 
e040: 6f 72 20 6d 6f 64 69 66 79 20 61 6e 79 20 74 61  or modify any ta
e050: 62 6c 65 20 69 6e 20 61 6e 79 20 5b 41 54 54 41  ble in any [ATTA
e060: 43 48 5d 2d 65 64 20 64 61 74 61 62 61 73 65 2e  CH]-ed database.
e070: 29 5e 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  )^.  </p></li>..
e080: 3c 6c 69 3e 3c 70 3e 0a 20 20 5e 54 68 65 20 22  <li><p>.  ^The "
e090: 49 4e 53 45 52 54 20 49 4e 54 4f 20 3c 69 3e 74  INSERT INTO <i>t
e0a0: 61 62 6c 65 3c 2f 69 3e 20 44 45 46 41 55 4c 54  able</i> DEFAULT
e0b0: 20 56 41 4c 55 45 53 22 20 66 6f 72 6d 20 6f 66   VALUES" form of
e0c0: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 20 73 74   the [INSERT] st
e0d0: 61 74 65 6d 65 6e 74 0a 20 20 69 73 20 6e 6f 74  atement.  is not
e0e0: 20 73 75 70 70 6f 72 74 65 64 2e 0a 20 20 3c 2f   supported..  </
e0f0: 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e  p></li>..<li><p>
e100: 0a 20 20 5e 54 68 65 20 49 4e 44 45 58 45 44 20  .  ^The INDEXED 
e110: 42 59 20 61 6e 64 20 4e 4f 54 20 49 4e 44 45 58  BY and NOT INDEX
e120: 45 44 20 63 6c 61 75 73 65 73 20 61 72 65 20 6e  ED clauses are n
e130: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  ot supported for
e140: 20 5b 55 50 44 41 54 45 5d 20 61 6e 64 0a 20 20   [UPDATE] and.  
e150: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
e160: 6e 74 73 2e 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e  nts..  </p></li>
e170: 0a 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 5e 28 54 68  ..<li><p>.  ^(Th
e180: 65 20 4f 52 44 45 52 20 42 59 20 61 6e 64 20 4c  e ORDER BY and L
e190: 49 4d 49 54 20 63 6c 61 75 73 65 73 20 6f 6e 20  IMIT clauses on 
e1a0: 5b 55 50 44 41 54 45 5d 20 61 6e 64 20 5b 44 45  [UPDATE] and [DE
e1b0: 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
e1c0: 20 61 72 65 20 6e 6f 74 0a 20 20 73 75 70 70 6f   are not.  suppo
e1d0: 72 74 65 64 2e 20 20 4f 52 44 45 52 20 42 59 20  rted.  ORDER BY 
e1e0: 61 6e 64 20 4c 49 4d 49 54 20 61 72 65 20 6e 6f  and LIMIT are no
e1f0: 74 20 6e 6f 72 6d 61 6c 6c 79 20 73 75 70 70 6f  t normally suppo
e200: 72 74 65 64 20 66 6f 72 20 5b 55 50 44 41 54 45  rted for [UPDATE
e210: 5d 20 6f 72 0a 20 20 5b 44 45 4c 45 54 45 5d 20  ] or.  [DELETE] 
e220: 69 6e 20 61 6e 79 20 63 6f 6e 74 65 78 74 20 62  in any context b
e230: 75 74 20 63 61 6e 20 62 65 20 65 6e 61 62 6c 65  ut can be enable
e240: 64 20 66 6f 72 20 74 6f 70 2d 6c 65 76 65 6c 20  d for top-level 
e250: 73 74 61 74 65 6d 65 6e 74 73 0a 20 20 75 73 69  statements.  usi
e260: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ng the [SQLITE_E
e270: 4e 41 42 4c 45 5f 55 50 44 41 54 45 5f 44 45 4c  NABLE_UPDATE_DEL
e280: 45 54 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  ETE_LIMIT] compi
e290: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
e2a0: 20 48 6f 77 65 76 65 72 2c 0a 20 20 74 68 61 74   However,.  that
e2b0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e2c0: 74 69 6f 6e 20 6f 6e 6c 79 20 61 70 70 6c 69 65  tion only applie
e2d0: 73 20 74 6f 20 74 6f 70 2d 6c 65 76 65 6c 20 5b  s to top-level [
e2e0: 55 50 44 41 54 45 5d 20 61 6e 64 20 5b 44 45 4c  UPDATE] and [DEL
e2f0: 45 54 45 5d 0a 20 20 73 74 61 74 65 6d 65 6e 74  ETE].  statement
e300: 73 2c 20 6e 6f 74 20 5b 55 50 44 41 54 45 5d 20  s, not [UPDATE] 
e310: 61 6e 64 20 5b 44 45 4c 45 54 45 5d 20 73 74 61  and [DELETE] sta
e320: 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 74  tements within t
e330: 72 69 67 67 65 72 73 2e 29 5e 0a 20 20 3c 2f 70  riggers.)^.  </p
e340: 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a  ></li>..<li><p>.
e350: 20 20 5e 5b 63 6f 6d 6d 6f 6e 2d 74 61 62 6c 65    ^[common-table
e360: 2d 65 78 70 72 65 73 73 69 6f 6e 7c 43 6f 6d 6d  -expression|Comm
e370: 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73  on table express
e380: 69 6f 6e 5d 20 61 72 65 20 6e 6f 74 20 73 75 70  ion] are not sup
e390: 70 6f 72 74 65 64 20 66 6f 72 0a 20 20 73 74 61  ported for.  sta
e3a0: 74 65 6d 65 6e 74 73 20 69 6e 73 69 64 65 20 6f  tements inside o
e3b0: 66 20 74 72 69 67 67 65 72 73 2e 0a 20 20 3c 2f  f triggers..  </
e3c0: 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c  p></li>.</ul>..<
e3d0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
e3e0: 69 6e 73 74 65 61 64 5f 6f 66 5f 74 72 69 67 67  instead_of_trigg
e3f0: 65 72 20 7b 49 4e 53 54 45 41 44 20 4f 46 7d 20  er {INSTEAD OF} 
e400: 7b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  {INSTEAD OF trig
e410: 67 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 49  ger}</tcl>.<h3>I
e420: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
e430: 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 72 69  rs</h3>..<p>^Tri
e440: 67 67 65 72 73 20 6d 61 79 20 62 65 20 63 72 65  ggers may be cre
e450: 61 74 65 64 20 6f 6e 20 5b 76 69 65 77 73 5d 2c  ated on [views],
e460: 20 61 73 20 77 65 6c 6c 20 61 73 20 6f 72 64 69   as well as ordi
e470: 6e 61 72 79 20 74 61 62 6c 65 73 2c 20 62 79 0a  nary tables, by.
e480: 73 70 65 63 69 66 79 69 6e 67 20 49 4e 53 54 45  specifying INSTE
e490: 41 44 20 4f 46 20 69 6e 20 74 68 65 20 43 52 45  AD OF in the CRE
e4a0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
e4b0: 65 6d 65 6e 74 2e 20 0a 5e 49 66 20 6f 6e 65 20  ement. .^If one 
e4c0: 6f 72 20 6d 6f 72 65 20 4f 4e 20 49 4e 53 45 52  or more ON INSER
e4d0: 54 2c 20 4f 4e 20 44 45 4c 45 54 45 0a 6f 72 20  T, ON DELETE.or 
e4e0: 4f 4e 20 55 50 44 41 54 45 20 74 72 69 67 67 65  ON UPDATE trigge
e4f0: 72 73 20 61 72 65 20 64 65 66 69 6e 65 64 20 6f  rs are defined o
e500: 6e 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 69  n a view, then i
e510: 74 20 69 73 20 6e 6f 74 20 61 6e 0a 65 72 72 6f  t is not an.erro
e520: 72 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 20  r to execute an 
e530: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 20 6f  INSERT, DELETE o
e540: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
e550: 6e 74 20 6f 6e 20 74 68 65 20 76 69 65 77 2c 20  nt on the view, 
e560: 0a 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20  .respectively.  
e570: 5e 49 6e 73 74 65 61 64 2c 0a 65 78 65 63 75 74  ^Instead,.execut
e580: 69 6e 67 20 61 6e 20 49 4e 53 45 52 54 2c 20 44  ing an INSERT, D
e590: 45 4c 45 54 45 20 6f 72 20 55 50 44 41 54 45 20  ELETE or UPDATE 
e5a0: 6f 6e 20 74 68 65 20 76 69 65 77 20 63 61 75 73  on the view caus
e5b0: 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
e5c0: 64 0a 74 72 69 67 67 65 72 73 20 74 6f 20 66 69  d.triggers to fi
e5d0: 72 65 2e 20 5e 54 68 65 20 72 65 61 6c 20 74 61  re. ^The real ta
e5e0: 62 6c 65 73 20 75 6e 64 65 72 6c 79 69 6e 67 20  bles underlying 
e5f0: 74 68 65 20 76 69 65 77 20 61 72 65 20 6e 6f 74  the view are not
e600: 20 6d 6f 64 69 66 69 65 64 0a 28 65 78 63 65 70   modified.(excep
e610: 74 20 70 6f 73 73 69 62 6c 79 20 65 78 70 6c 69  t possibly expli
e620: 63 69 74 6c 79 2c 20 62 79 20 61 20 74 72 69 67  citly, by a trig
e630: 67 65 72 20 70 72 6f 67 72 61 6d 29 2e 3c 2f 70  ger program).</p
e640: 3e 0a 0a 3c 70 3e 5e 4e 6f 74 65 20 74 68 61 74  >..<p>^Note that
e650: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
e660: 61 6e 67 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  anges()] and [sq
e670: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
e680: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
e690: 73 0a 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 49  s.do not count I
e6a0: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
e6b0: 72 20 66 69 72 69 6e 67 73 2c 20 62 75 74 20 74  r firings, but t
e6c0: 68 65 0a 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  he.[count_change
e6d0: 73 20 70 72 61 67 6d 61 5d 20 64 6f 65 73 20 63  s pragma] does c
e6e0: 6f 75 6e 74 20 49 4e 53 54 45 41 44 20 4f 46 20  ount INSTEAD OF 
e6f0: 74 72 69 67 67 65 72 20 66 69 72 69 6e 67 2e 3c  trigger firing.<
e700: 2f 70 3e 0a 0a 3c 68 33 3e 53 6f 6d 65 20 45 78  /p>..<h3>Some Ex
e710: 61 6d 70 6c 65 20 54 72 69 67 67 65 72 73 3c 2f  ample Triggers</
e720: 68 33 3e 0a 0a 3c 70 3e 5e 28 41 73 73 75 6d 69  h3>..<p>^(Assumi
e730: 6e 67 20 74 68 61 74 20 63 75 73 74 6f 6d 65 72  ng that customer
e740: 20 72 65 63 6f 72 64 73 20 61 72 65 20 73 74 6f   records are sto
e750: 72 65 64 20 69 6e 20 74 68 65 20 22 63 75 73 74  red in the "cust
e760: 6f 6d 65 72 73 22 20 74 61 62 6c 65 2c 20 61 6e  omers" table, an
e770: 64 0a 74 68 61 74 20 6f 72 64 65 72 20 72 65 63  d.that order rec
e780: 6f 72 64 73 20 61 72 65 20 73 74 6f 72 65 64 20  ords are stored 
e790: 69 6e 20 74 68 65 20 22 6f 72 64 65 72 73 22 20  in the "orders" 
e7a0: 74 61 62 6c 65 2c 20 74 68 65 20 66 6f 6c 6c 6f  table, the follo
e7b0: 77 69 6e 67 0a 55 50 44 41 54 45 20 74 72 69 67  wing.UPDATE trig
e7c0: 67 65 72 0a 65 6e 73 75 72 65 73 20 74 68 61 74  ger.ensures that
e7d0: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20   all associated 
e7e0: 6f 72 64 65 72 73 20 61 72 65 20 72 65 64 69 72  orders are redir
e7f0: 65 63 74 65 64 20 77 68 65 6e 20 61 20 63 75 73  ected when a cus
e800: 74 6f 6d 65 72 20 63 68 61 6e 67 65 73 0a 68 69  tomer changes.hi
e810: 73 20 6f 72 20 68 65 72 20 61 64 64 72 65 73 73  s or her address
e820: 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 45 78 61 6d  :</p>..<tcl>Exam
e830: 70 6c 65 20 7b 0a 43 52 45 41 54 45 20 54 52 49  ple {.CREATE TRI
e840: 47 47 45 52 20 75 70 64 61 74 65 5f 63 75 73 74  GGER update_cust
e850: 6f 6d 65 72 5f 61 64 64 72 65 73 73 20 55 50 44  omer_address UPD
e860: 41 54 45 20 4f 46 20 61 64 64 72 65 73 73 20 4f  ATE OF address O
e870: 4e 20 63 75 73 74 6f 6d 65 72 73 20 0a 20 20 42  N customers .  B
e880: 45 47 49 4e 0a 20 20 20 20 55 50 44 41 54 45 20  EGIN.    UPDATE 
e890: 6f 72 64 65 72 73 20 53 45 54 20 61 64 64 72 65  orders SET addre
e8a0: 73 73 20 3d 20 6e 65 77 2e 61 64 64 72 65 73 73  ss = new.address
e8b0: 20 57 48 45 52 45 20 63 75 73 74 6f 6d 65 72 5f   WHERE customer_
e8c0: 6e 61 6d 65 20 3d 20 6f 6c 64 2e 6e 61 6d 65 3b  name = old.name;
e8d0: 0a 20 20 45 4e 44 3b 0a 7d 3c 2f 74 63 6c 3e 0a  .  END;.}</tcl>.
e8e0: 0a 3c 70 3e 57 69 74 68 20 74 68 69 73 20 74 72  .<p>With this tr
e8f0: 69 67 67 65 72 20 69 6e 73 74 61 6c 6c 65 64 2c  igger installed,
e900: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 73   executing the s
e910: 74 61 74 65 6d 65 6e 74 3a 3c 2f 70 3e 0a 0a 3c  tatement:</p>..<
e920: 74 63 6c 3e 45 78 61 6d 70 6c 65 20 7b 0a 55 50  tcl>Example {.UP
e930: 44 41 54 45 20 63 75 73 74 6f 6d 65 72 73 20 53  DATE customers S
e940: 45 54 20 61 64 64 72 65 73 73 20 3d 20 27 31 20  ET address = '1 
e950: 4d 61 69 6e 20 53 74 2e 27 20 57 48 45 52 45 20  Main St.' WHERE 
e960: 6e 61 6d 65 20 3d 20 27 4a 61 63 6b 20 4a 6f 6e  name = 'Jack Jon
e970: 65 73 27 3b 0a 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70  es';.}</tcl>..<p
e980: 3e 63 61 75 73 65 73 20 74 68 65 20 66 6f 6c 6c  >causes the foll
e990: 6f 77 69 6e 67 20 74 6f 20 62 65 20 61 75 74 6f  owing to be auto
e9a0: 6d 61 74 69 63 61 6c 6c 79 20 65 78 65 63 75 74  matically execut
e9b0: 65 64 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 45 78  ed:</p>..<tcl>Ex
e9c0: 61 6d 70 6c 65 20 7b 0a 55 50 44 41 54 45 20 6f  ample {.UPDATE o
e9d0: 72 64 65 72 73 20 53 45 54 20 61 64 64 72 65 73  rders SET addres
e9e0: 73 20 3d 20 27 31 20 4d 61 69 6e 20 53 74 2e 27  s = '1 Main St.'
e9f0: 20 57 48 45 52 45 20 63 75 73 74 6f 6d 65 72 5f   WHERE customer_
ea00: 6e 61 6d 65 20 3d 20 27 4a 61 63 6b 20 4a 6f 6e  name = 'Jack Jon
ea10: 65 73 27 3b 0a 7d 3c 2f 74 63 6c 3e 29 5e 0a 0a  es';.}</tcl>)^..
ea20: 3c 70 3e 46 6f 72 20 61 6e 20 65 78 61 6d 70 6c  <p>For an exampl
ea30: 65 20 6f 66 20 61 6e 20 49 4e 53 54 45 41 44 20  e of an INSTEAD 
ea40: 4f 46 20 74 72 69 67 67 65 72 2c 20 63 6f 6e 73  OF trigger, cons
ea50: 69 64 65 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ider the followi
ea60: 6e 67 20 73 63 68 65 6d 61 3a 0a 0a 3c 74 63 6c  ng schema:..<tcl
ea70: 3e 45 78 61 6d 70 6c 65 20 7b 0a 43 52 45 41 54  >Example {.CREAT
ea80: 45 20 54 41 42 4c 45 20 63 75 73 74 6f 6d 65 72  E TABLE customer
ea90: 28 0a 20 20 63 75 73 74 5f 69 64 20 49 4e 54 45  (.  cust_id INTE
eaa0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  GER PRIMARY KEY,
eab0: 0a 20 20 63 75 73 74 5f 6e 61 6d 65 20 54 45 58  .  cust_name TEX
eac0: 54 2c 0a 20 20 63 75 73 74 5f 61 64 64 72 20 54  T,.  cust_addr T
ead0: 45 58 54 0a 29 3b 0a 43 52 45 41 54 45 20 56 49  EXT.);.CREATE VI
eae0: 45 57 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72  EW customer_addr
eaf0: 65 73 73 20 41 53 0a 20 20 20 53 45 4c 45 43 54  ess AS.   SELECT
eb00: 20 63 75 73 74 5f 69 64 2c 20 63 75 73 74 5f 61   cust_id, cust_a
eb10: 64 64 72 20 46 52 4f 4d 20 63 75 73 74 6f 6d 65  ddr FROM custome
eb20: 72 3b 0a 43 52 45 41 54 45 20 54 52 49 47 47 45  r;.CREATE TRIGGE
eb30: 52 20 63 75 73 74 5f 61 64 64 72 5f 63 68 6e 67  R cust_addr_chng
eb40: 0a 49 4e 53 54 45 41 44 20 4f 46 20 55 50 44 41  .INSTEAD OF UPDA
eb50: 54 45 20 4f 46 20 63 75 73 74 5f 61 64 64 72 20  TE OF cust_addr 
eb60: 4f 4e 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72  ON customer_addr
eb70: 65 73 73 0a 42 45 47 49 4e 0a 20 20 55 50 44 41  ess.BEGIN.  UPDA
eb80: 54 45 20 63 75 73 74 6f 6d 65 72 20 53 45 54 20  TE customer SET 
eb90: 63 75 73 74 5f 61 64 64 72 3d 4e 45 57 2e 63 75  cust_addr=NEW.cu
eba0: 73 74 5f 61 64 64 72 0a 20 20 20 57 48 45 52 45  st_addr.   WHERE
ebb0: 20 63 75 73 74 5f 69 64 3d 4e 45 57 2e 63 75 73   cust_id=NEW.cus
ebc0: 74 5f 69 64 3b 0a 45 4e 44 3b 0a 7d 3c 2f 74 63  t_id;.END;.}</tc
ebd0: 6c 3e 0a 0a 3c 70 3e 57 69 74 68 20 74 68 65 20  l>..<p>With the 
ebe0: 73 63 68 65 6d 61 20 61 62 6f 76 65 2c 20 61 20  schema above, a 
ebf0: 73 74 61 74 65 6d 65 6e 74 20 6f 66 20 74 68 65  statement of the
ec00: 20 66 6f 72 6d 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c   form:</p>..<tcl
ec10: 3e 45 78 61 6d 70 6c 65 20 7b 0a 55 50 44 41 54  >Example {.UPDAT
ec20: 45 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72 65  E customer_addre
ec30: 73 73 20 53 45 54 20 63 75 73 74 5f 61 64 64 72  ss SET cust_addr
ec40: 3d 24 6e 65 77 5f 61 64 64 72 65 73 73 20 57 48  =$new_address WH
ec50: 45 52 45 20 63 75 73 74 5f 69 64 3d 24 63 75 73  ERE cust_id=$cus
ec60: 74 5f 69 64 3b 0a 7d 3c 2f 74 63 6c 3e 0a 0a 3c  t_id;.}</tcl>..<
ec70: 70 3e 43 61 75 73 65 73 20 74 68 65 20 63 75 73  p>Causes the cus
ec80: 74 6f 6d 65 72 2e 63 75 73 74 5f 61 64 64 72 20  tomer.cust_addr 
ec90: 66 69 65 6c 64 20 74 6f 20 62 65 20 75 70 64 61  field to be upda
eca0: 74 65 64 20 66 6f 72 20 61 20 73 70 65 63 69 66  ted for a specif
ecb0: 69 63 0a 63 75 73 74 6f 6d 65 72 20 65 6e 74 72  ic.customer entr
ecc0: 79 20 74 68 61 74 20 68 61 73 20 63 75 73 74 6f  y that has custo
ecd0: 6d 65 72 2e 63 75 73 74 5f 69 64 20 65 71 75 61  mer.cust_id equa
ece0: 6c 20 74 6f 20 74 68 65 20 24 63 75 73 74 5f 69  l to the $cust_i
ecf0: 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 4e 6f 74  d parameter..Not
ed00: 65 20 68 6f 77 20 74 68 65 20 76 61 6c 75 65 73  e how the values
ed10: 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65   assigned to the
ed20: 20 76 69 65 77 20 61 72 65 20 6d 61 64 65 20 61   view are made a
ed30: 76 61 69 6c 61 62 6c 65 20 61 73 20 66 69 65 6c  vailable as fiel
ed40: 64 0a 69 6e 20 74 68 65 20 73 70 65 63 69 61 6c  d.in the special
ed50: 20 22 4e 45 57 22 20 74 61 62 6c 65 20 77 69 74   "NEW" table wit
ed60: 68 69 6e 20 74 68 65 20 74 72 69 67 67 65 72 20  hin the trigger 
ed70: 62 6f 64 79 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  body.</p>..<tcl>
ed80: 68 64 5f 66 72 61 67 6d 65 6e 74 20 75 6e 64 65  hd_fragment unde
ed90: 66 5f 62 65 66 6f 72 65 20 7b 75 6e 64 65 66 69  f_before {undefi
eda0: 6e 65 64 20 42 45 46 4f 52 45 20 74 72 69 67 67  ned BEFORE trigg
edb0: 65 72 20 62 65 68 61 76 69 6f 72 7d 3c 2f 74 63  er behavior}</tc
edc0: 6c 3e 0a 3c 68 33 3e 43 61 75 74 69 6f 6e 73 20  l>.<h3>Cautions 
edd0: 4f 6e 20 54 68 65 20 55 73 65 20 4f 66 20 42 45  On The Use Of BE
ede0: 46 4f 52 45 20 74 72 69 67 67 65 72 73 3c 2f 68  FORE triggers</h
edf0: 33 3e 0a 0a 3c 70 3e 49 66 20 61 20 42 45 46 4f  3>..<p>If a BEFO
ee00: 52 45 20 55 50 44 41 54 45 20 6f 72 20 42 45 46  RE UPDATE or BEF
ee10: 4f 52 45 20 44 45 4c 45 54 45 20 74 72 69 67 67  ORE DELETE trigg
ee20: 65 72 20 6d 6f 64 69 66 69 65 73 20 6f 72 20 64  er modifies or d
ee30: 65 6c 65 74 65 73 20 61 20 72 6f 77 0a 74 68 61  eletes a row.tha
ee40: 74 20 77 61 73 20 74 6f 20 68 61 76 65 20 62 65  t was to have be
ee50: 65 6e 20 75 70 64 61 74 65 64 20 6f 72 20 64 65  en updated or de
ee60: 6c 65 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  leted, then the 
ee70: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 73 75  result of the su
ee80: 62 73 65 71 75 65 6e 74 0a 75 70 64 61 74 65 20  bsequent.update 
ee90: 6f 72 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  or delete operat
eea0: 69 6f 6e 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ion is undefined
eeb0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
eec0: 69 66 20 61 20 42 45 46 4f 52 45 20 74 72 69 67  if a BEFORE trig
eed0: 67 65 72 0a 6d 6f 64 69 66 69 65 73 20 6f 72 20  ger.modifies or 
eee0: 64 65 6c 65 74 65 73 20 61 20 72 6f 77 2c 20 74  deletes a row, t
eef0: 68 65 6e 20 69 74 20 69 73 20 75 6e 64 65 66 69  hen it is undefi
ef00: 6e 65 64 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ned whether or n
ef10: 6f 74 20 41 46 54 45 52 20 74 72 69 67 67 65 72  ot AFTER trigger
ef20: 73 0a 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  s.that would hav
ef30: 65 20 6f 74 68 65 72 77 69 73 65 20 72 75 6e 20  e otherwise run 
ef40: 6f 6e 20 74 68 6f 73 65 20 72 6f 77 73 20 77 69  on those rows wi
ef50: 6c 6c 20 69 6e 20 66 61 63 74 20 72 75 6e 2e 0a  ll in fact run..
ef60: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 76 61 6c  </p>..<p>The val
ef70: 75 65 20 6f 66 20 4e 45 57 2e 72 6f 77 69 64 20  ue of NEW.rowid 
ef80: 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 6e 20  is undefined in 
ef90: 61 20 42 45 46 4f 52 45 20 49 4e 53 45 52 54 20  a BEFORE INSERT 
efa0: 74 72 69 67 67 65 72 20 69 6e 20 77 68 69 63 68  trigger in which
efb0: 0a 74 68 65 20 72 6f 77 69 64 20 69 73 20 6e 6f  .the rowid is no
efc0: 74 20 65 78 70 6c 69 63 69 74 6c 79 20 73 65 74  t explicitly set
efd0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 3c   to an integer.<
efe0: 2f 70 3e 0a 0a 3c 70 3e 42 65 63 61 75 73 65 20  /p>..<p>Because 
eff0: 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 73  of the behaviors
f000: 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
f010: 2c 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 61 72  , programmers ar
f020: 65 20 65 6e 63 6f 75 72 61 67 65 64 20 74 6f 0a  e encouraged to.
f030: 70 72 65 66 65 72 20 41 46 54 45 52 20 74 72 69  prefer AFTER tri
f040: 67 67 65 72 73 20 6f 76 65 72 20 42 45 46 4f 52  ggers over BEFOR
f050: 45 20 74 72 69 67 67 65 72 73 2e 3c 2f 70 3e 0a  E triggers.</p>.
f060: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
f070: 74 20 72 61 69 73 65 20 7b 52 41 49 53 45 20 66  t raise {RAISE f
f080: 75 6e 63 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c  unction}</tcl>.<
f090: 68 33 3e 54 68 65 20 52 41 49 53 45 28 29 20 66  h3>The RAISE() f
f0a0: 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70  unction</h3>..<p
f0b0: 3e 5e 28 41 20 73 70 65 63 69 61 6c 20 53 51 4c  >^(A special SQL
f0c0: 20 66 75 6e 63 74 69 6f 6e 20 52 41 49 53 45 28   function RAISE(
f0d0: 29 20 6d 61 79 20 62 65 20 75 73 65 64 20 77 69  ) may be used wi
f0e0: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2d 70  thin a trigger-p
f0f0: 72 6f 67 72 61 6d 2c 29 5e 0a 77 69 74 68 20 74  rogram,)^.with t
f100: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 79 6e  he following syn
f110: 74 61 78 3c 2f 70 3e 20 0a 0a 3c 74 63 6c 3e 42  tax</p> ..<tcl>B
f120: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 61 69  ubbleDiagram rai
f130: 73 65 2d 66 75 6e 63 74 69 6f 6e 3c 2f 74 63 6c  se-function</tcl
f140: 3e 0a 0a 3c 70 3e 5e 28 57 68 65 6e 20 6f 6e 65  >..<p>^(When one
f150: 20 6f 66 20 52 41 49 53 45 28 52 4f 4c 4c 42 41   of RAISE(ROLLBA
f160: 43 4b 2c 2e 2e 2e 29 2c 20 52 41 49 53 45 28 41  CK,...), RAISE(A
f170: 42 4f 52 54 2c 2e 2e 2e 29 20 6f 72 20 52 41 49  BORT,...) or RAI
f180: 53 45 28 46 41 49 4c 2c 2e 2e 2e 29 0a 69 73 20  SE(FAIL,...).is 
f190: 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20 74 72  called during tr
f1a0: 69 67 67 65 72 2d 70 72 6f 67 72 61 6d 0a 65 78  igger-program.ex
f1b0: 65 63 75 74 69 6f 6e 2c 20 74 68 65 20 73 70 65  ecution, the spe
f1c0: 63 69 66 69 65 64 20 5b 4f 4e 20 43 4f 4e 46 4c  cified [ON CONFL
f1d0: 49 43 54 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  ICT] processing 
f1e0: 69 73 20 70 65 72 66 6f 72 6d 65 64 0a 74 68 65  is performed.the
f1f0: 20 63 75 72 72 65 6e 74 20 71 75 65 72 79 20 74   current query t
f200: 65 72 6d 69 6e 61 74 65 73 2e 29 5e 0a 41 6e 20  erminates.)^.An 
f210: 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
f220: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
f230: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  ] is returned to
f240: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f250: 2c 0a 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65  ,.along with the
f260: 20 73 70 65 63 69 66 69 65 64 20 65 72 72 6f 72   specified error
f270: 20 6d 65 73 73 61 67 65 2e 3c 2f 70 3e 0a 0a 3c   message.</p>..<
f280: 70 3e 5e 57 68 65 6e 20 52 41 49 53 45 28 49 47  p>^When RAISE(IG
f290: 4e 4f 52 45 29 20 69 73 20 63 61 6c 6c 65 64 2c  NORE) is called,
f2a0: 20 74 68 65 20 72 65 6d 61 69 6e 64 65 72 20 6f   the remainder o
f2b0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  f the current tr
f2c0: 69 67 67 65 72 20 70 72 6f 67 72 61 6d 2c 0a 74  igger program,.t
f2d0: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
f2e0: 74 20 63 61 75 73 65 64 20 74 68 65 20 74 72 69  t caused the tri
f2f0: 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 6f 20  gger program to 
f300: 65 78 65 63 75 74 65 20 61 6e 64 20 61 6e 79 20  execute and any 
f310: 73 75 62 73 65 71 75 65 6e 74 0a 74 72 69 67 67  subsequent.trigg
f320: 65 72 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  er programs that
f330: 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
f340: 20 65 78 65 63 75 74 65 64 20 61 72 65 20 61 62   executed are ab
f350: 61 6e 64 6f 6e 65 64 2e 20 5e 4e 6f 20 64 61 74  andoned. ^No dat
f360: 61 62 61 73 65 0a 63 68 61 6e 67 65 73 20 61 72  abase.changes ar
f370: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20  e rolled back.  
f380: 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
f390: 74 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  t that caused th
f3a0: 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
f3b0: 6d 0a 74 6f 20 65 78 65 63 75 74 65 20 69 73 20  m.to execute is 
f3c0: 69 74 73 65 6c 66 20 70 61 72 74 20 6f 66 20 61  itself part of a
f3d0: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
f3e0: 2c 20 74 68 65 6e 20 74 68 61 74 20 74 72 69 67  , then that trig
f3f0: 67 65 72 20 70 72 6f 67 72 61 6d 0a 72 65 73 75  ger program.resu
f400: 6d 65 73 20 65 78 65 63 75 74 69 6f 6e 20 61 74  mes execution at
f410: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
f420: 66 20 74 68 65 20 6e 65 78 74 20 73 74 65 70 2e  f the next step.
f430: 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
f440: 72 61 67 6d 65 6e 74 20 74 65 6d 70 74 72 69 67  ragment temptrig
f450: 20 7b 54 45 4d 50 20 74 72 69 67 67 65 72 73 20   {TEMP triggers 
f460: 6f 6e 20 6e 6f 6e 2d 54 45 4d 50 20 74 61 62 6c  on non-TEMP tabl
f470: 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 45  es}</tcl>.<h3>TE
f480: 4d 50 20 54 72 69 67 67 65 72 73 20 6f 6e 20 4e  MP Triggers on N
f490: 6f 6e 2d 54 45 4d 50 20 54 61 62 6c 65 73 3c 2f  on-TEMP Tables</
f4a0: 68 33 3e 0a 0a 3c 70 3e 5e 28 41 20 74 72 69 67  h3>..<p>^(A trig
f4b0: 67 65 72 20 6e 6f 72 6d 61 6c 6c 79 20 65 78 69  ger normally exi
f4c0: 73 74 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  sts in the same 
f4d0: 64 61 74 61 62 61 73 65 20 61 73 20 74 68 65 20  database as the 
f4e0: 74 61 62 6c 65 20 6e 61 6d 65 64 0a 61 66 74 65  table named.afte
f4f0: 72 20 74 68 65 20 22 4f 4e 22 20 6b 65 79 77 6f  r the "ON" keywo
f500: 72 64 20 69 6e 20 74 68 65 20 43 52 45 41 54 45  rd in the CREATE
f510: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
f520: 6e 74 2e 20 20 45 78 63 65 70 74 2c 20 69 74 20  nt.  Except, it 
f530: 69 73 0a 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  is.possible to c
f540: 72 65 61 74 65 20 61 20 54 45 4d 50 20 54 52 49  reate a TEMP TRI
f550: 47 47 45 52 20 6f 6e 20 61 20 74 61 62 6c 65 20  GGER on a table 
f560: 69 6e 20 61 6e 6f 74 68 65 72 20 64 61 74 61 62  in another datab
f570: 61 73 65 2e 29 5e 20 20 0a 53 75 63 68 20 61 20  ase.)^  .Such a 
f580: 74 72 69 67 67 65 72 20 77 69 6c 6c 20 6f 6e 6c  trigger will onl
f590: 79 20 66 69 72 65 20 77 68 65 6e 20 63 68 61 6e  y fire when chan
f5a0: 67 65 73 0a 61 72 65 20 6d 61 64 65 20 74 6f 20  ges.are made to 
f5b0: 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
f5c0: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
f5d0: 69 6f 6e 20 74 68 61 74 20 64 65 66 69 6e 65 64  ion that defined
f5e0: 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 4f 74   the trigger..Ot
f5f0: 68 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  her applications
f600: 20 74 68 61 74 20 6d 6f 64 69 66 79 20 74 68 65   that modify the
f610: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 6e   database will n
f620: 6f 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 65  ot be able to se
f630: 65 20 74 68 65 0a 54 45 4d 50 20 74 72 69 67 67  e the.TEMP trigg
f640: 65 72 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6e  er and hence can
f650: 6e 6f 74 20 72 75 6e 20 74 68 65 20 74 72 69 67  not run the trig
f660: 67 65 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65  ger.</p>..<p>Whe
f670: 6e 20 64 65 66 69 6e 69 6e 67 20 61 20 54 45 4d  n defining a TEM
f680: 50 20 74 72 69 67 67 65 72 20 6f 6e 20 61 20 6e  P trigger on a n
f690: 6f 6e 2d 54 45 4d 50 20 74 61 62 6c 65 2c 20 69  on-TEMP table, i
f6a0: 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74  t is important t
f6b0: 6f 0a 73 70 65 63 69 66 79 20 74 68 65 20 64 61  o.specify the da
f6c0: 74 61 62 61 73 65 20 68 6f 6c 64 69 6e 67 20 74  tabase holding t
f6d0: 68 65 20 6e 6f 6e 2d 54 45 4d 50 20 74 61 62 6c  he non-TEMP tabl
f6e0: 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  e.  For example,
f6f0: 0a 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .in the followin
f700: 67 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20  g statement, it 
f710: 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20  is important to 
f720: 73 61 79 20 22 6d 61 69 6e 2e 74 61 62 31 22 20  say "main.tab1" 
f730: 69 6e 73 74 65 61 64 0a 6f 66 20 6a 75 73 74 20  instead.of just 
f740: 22 74 61 62 31 22 3a 3c 2f 70 3e 0a 0a 3c 62 6c  "tab1":</p>..<bl
f750: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43  ockquote><pre>.C
f760: 52 45 41 54 45 20 54 45 4d 50 20 54 52 49 47 47  REATE TEMP TRIGG
f770: 45 52 20 65 78 31 20 41 46 54 45 52 20 49 4e 53  ER ex1 AFTER INS
f780: 45 52 54 20 4f 4e 20 3c 62 3e 6d 61 69 6e 2e 3c  ERT ON <b>main.<
f790: 2f 62 3e 74 61 62 31 20 42 45 47 49 4e 20 2e 2e  /b>tab1 BEGIN ..
f7a0: 2e 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ..</pre></blockq
f7b0: 75 6f 74 65 3e 0a 0a 3c 70 3e 46 61 69 6c 75 72  uote>..<p>Failur
f7c0: 65 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  e to specify the
f7d0: 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 6f 6e 20   schema name on 
f7e0: 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
f7f0: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 0a 69 6e   could result.in
f800: 20 74 68 65 20 54 45 4d 50 20 74 72 69 67 67 65   the TEMP trigge
f810: 72 20 62 65 69 6e 67 20 72 65 61 74 74 61 63 68  r being reattach
f820: 65 64 20 74 6f 20 61 20 74 61 62 6c 65 20 77 69  ed to a table wi
f830: 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
f840: 20 69 6e 0a 61 6e 6f 74 68 65 72 20 64 61 74 61   in.another data
f850: 62 61 73 65 20 77 68 65 6e 65 76 65 72 20 61 6e  base whenever an
f860: 79 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 20  y schema change 
f870: 6f 63 63 75 72 73 2e 3c 2f 70 3e 0a 0a 3c 74 63  occurs.</p>..<tc
f880: 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  l>.#############
f890: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f8a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f8b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f8c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f8d0: 23 23 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45 41  ##.Section {CREA
f8e0: 54 45 20 56 49 45 57 7d 20 7b 63 72 65 61 74 65  TE VIEW} {create
f8f0: 76 69 65 77 7d 20 7b 7b 43 52 45 41 54 45 20 56  view} {{CREATE V
f900: 49 45 57 7d 20 76 69 65 77 20 56 49 45 57 20 2a  IEW} view VIEW *
f910: 76 69 65 77 73 7d 0a 0a 52 65 63 75 72 73 69 76  views}..Recursiv
f920: 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63  eBubbleDiagram c
f930: 72 65 61 74 65 2d 76 69 65 77 2d 73 74 6d 74 0a  reate-view-stmt.
f940: 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20  </tcl>..<p>^The 
f950: 43 52 45 41 54 45 20 56 49 45 57 20 63 6f 6d 6d  CREATE VIEW comm
f960: 61 6e 64 20 61 73 73 69 67 6e 73 20 61 20 6e 61  and assigns a na
f970: 6d 65 20 74 6f 20 61 20 70 72 65 2d 70 61 63 6b  me to a pre-pack
f980: 61 67 65 64 20 0a 5b 53 45 4c 45 43 54 5d 20 73  aged .[SELECT] s
f990: 74 61 74 65 6d 65 6e 74 2e 20 0a 5e 4f 6e 63 65  tatement. .^Once
f9a0: 20 74 68 65 20 76 69 65 77 20 69 73 20 63 72 65   the view is cre
f9b0: 61 74 65 64 2c 20 69 74 20 63 61 6e 20 62 65 20  ated, it can be 
f9c0: 75 73 65 64 20 69 6e 20 74 68 65 20 46 52 4f 4d  used in the FROM
f9d0: 20 63 6c 61 75 73 65 0a 6f 66 20 61 6e 6f 74 68   clause.of anoth
f9e0: 65 72 20 5b 53 45 4c 45 43 54 5d 20 69 6e 20 70  er [SELECT] in p
f9f0: 6c 61 63 65 20 6f 66 20 61 20 74 61 62 6c 65 20  lace of a table 
fa00: 6e 61 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e  name..</p>..<p>^
fa10: 49 66 20 74 68 65 20 22 54 45 4d 50 22 20 6f 72  If the "TEMP" or
fa20: 20 22 54 45 4d 50 4f 52 41 52 59 22 20 6b 65 79   "TEMPORARY" key
fa30: 77 6f 72 64 20 6f 63 63 75 72 73 20 69 6e 20 62  word occurs in b
fa40: 65 74 77 65 65 6e 20 22 43 52 45 41 54 45 22 0a  etween "CREATE".
fa50: 61 6e 64 20 22 56 49 45 57 22 20 74 68 65 6e 20  and "VIEW" then 
fa60: 74 68 65 20 76 69 65 77 20 74 68 61 74 20 69 73  the view that is
fa70: 20 63 72 65 61 74 65 64 20 69 73 20 6f 6e 6c 79   created is only
fa80: 20 76 69 73 69 62 6c 65 20 74 6f 20 74 68 65 0a   visible to the.
fa90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
faa0: 74 69 6f 6e 5d 20 74 68 61 74 20 63 72 65 61 74  tion] that creat
fab0: 65 64 20 69 74 20 61 6e 64 20 69 73 20 61 75 74  ed it and is aut
fac0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
fad0: 65 64 20 77 68 65 6e 0a 74 68 65 20 64 61 74 61  ed when.the data
fae0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
faf0: 69 73 20 63 6c 6f 73 65 64 2e 3c 2f 70 3e 0a 0a  is closed.</p>..
fb00: 3c 70 3e 20 5e 49 66 20 61 20 3c 79 79 74 65 72  <p> ^If a <yyter
fb10: 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79  m>schema-name</y
fb20: 79 74 65 72 6d 3e 20 69 73 20 73 70 65 63 69 66  yterm> is specif
fb30: 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 76 69  ied, then the vi
fb40: 65 77 20 0a 69 73 20 63 72 65 61 74 65 64 20 69  ew .is created i
fb50: 6e 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  n the specified 
fb60: 64 61 74 61 62 61 73 65 2e 0a 5e 49 74 20 69 73  database..^It is
fb70: 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
fb80: 63 69 66 79 20 62 6f 74 68 20 61 20 3c 79 79 74  cify both a <yyt
fb90: 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c  erm>schema-name<
fba0: 2f 79 79 74 65 72 6d 3e 0a 61 6e 64 20 74 68 65  /yyterm>.and the
fbb0: 20 54 45 4d 50 20 6b 65 79 77 6f 72 64 20 6f 6e   TEMP keyword on
fbc0: 20 61 20 56 49 45 57 2c 20 75 6e 6c 65 73 73 20   a VIEW, unless 
fbd0: 74 68 65 20 3c 79 79 74 65 72 6d 3e 73 63 68 65  the <yyterm>sche
fbe0: 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  ma-name</yyterm>
fbf0: 20 0a 69 73 20 22 74 65 6d 70 22 2e 0a 5e 49 66   .is "temp"..^If
fc00: 20 6e 6f 20 73 63 68 65 6d 61 20 6e 61 6d 65 20   no schema name 
fc10: 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 61 6e  is specified, an
fc20: 64 20 74 68 65 20 54 45 4d 50 20 6b 65 79 77 6f  d the TEMP keywo
fc30: 72 64 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e  rd is not presen
fc40: 74 2c 0a 74 68 65 20 56 49 45 57 20 69 73 20 63  t,.the VIEW is c
fc50: 72 65 61 74 65 64 20 69 6e 20 74 68 65 20 6d 61  reated in the ma
fc60: 69 6e 20 64 61 74 61 62 61 73 65 2e 3c 2f 70 3e  in database.</p>
fc70: 0a 0a 3c 70 3e 5e 59 6f 75 20 63 61 6e 6e 6f 74  ..<p>^You cannot
fc80: 20 5b 44 45 4c 45 54 45 5d 2c 20 5b 49 4e 53 45   [DELETE], [INSE
fc90: 52 54 5d 2c 20 6f 72 20 5b 55 50 44 41 54 45 5d  RT], or [UPDATE]
fca0: 20 61 20 76 69 65 77 2e 20 20 5e 56 69 65 77 73   a view.  ^Views
fcb0: 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   are read-only .
fcc0: 69 6e 20 53 51 4c 69 74 65 2e 20 20 5e 48 6f 77  in SQLite.  ^How
fcd0: 65 76 65 72 2c 20 69 6e 20 6d 61 6e 79 20 63 61  ever, in many ca
fce0: 73 65 73 20 79 6f 75 20 63 61 6e 20 75 73 65 20  ses you can use 
fcf0: 61 6e 0a 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an.[INSTEAD OF t
fd00: 72 69 67 67 65 72 5d 20 6f 6e 20 74 68 65 20 76  rigger] on the v
fd10: 69 65 77 20 74 6f 20 61 63 63 6f 6d 70 6c 69 73  iew to accomplis
fd20: 68 20 0a 74 68 65 20 73 61 6d 65 20 74 68 69 6e  h .the same thin
fd30: 67 2e 20 20 5e 56 69 65 77 73 20 61 72 65 20 72  g.  ^Views are r
fd40: 65 6d 6f 76 65 64 20 0a 77 69 74 68 20 74 68 65  emoved .with the
fd50: 20 5b 44 52 4f 50 20 56 49 45 57 5d 20 63 6f 6d   [DROP VIEW] com
fd60: 6d 61 6e 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49  mand.</p>..<p>^I
fd70: 66 20 61 20 3c 79 79 74 65 72 6d 3e 63 6f 6c 75  f a <yyterm>colu
fd80: 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  mn-name</yyterm>
fd90: 20 6c 69 73 74 20 66 6f 6c 6c 6f 77 73 20 0a 74   list follows .t
fda0: 68 65 20 3c 79 79 74 65 72 6d 3e 76 69 65 77 2d  he <yyterm>view-
fdb0: 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2c 20 74  name</yyterm>, t
fdc0: 68 65 6e 20 74 68 61 74 20 6c 69 73 74 20 64 65  hen that list de
fdd0: 74 65 72 6d 69 6e 65 73 0a 74 68 65 20 6e 61 6d  termines.the nam
fde0: 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
fdf0: 73 20 66 6f 72 20 74 68 65 20 76 69 65 77 2e 20  s for the view. 
fe00: 20 5e 49 66 20 74 68 65 20 3c 79 79 74 65 72 6d   ^If the <yyterm
fe10: 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79  >column-name</yy
fe20: 74 65 72 6d 3e 0a 6c 69 73 74 20 69 73 20 6f 6d  term>.list is om
fe30: 69 74 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  itted, then the 
fe40: 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
fe50: 75 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 65 77  umns in the view
fe60: 20 61 72 65 20 64 65 72 69 76 65 64 0a 66 72 6f   are derived.fro
fe70: 6d 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  m the names of t
fe80: 68 65 20 72 65 73 75 6c 74 2d 73 65 74 20 63 6f  he result-set co
fe90: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 73 65  lumns in the [se
fea0: 6c 65 63 74 2d 73 74 6d 74 5d 2e 0a 4e 6f 74 65  lect-stmt]..Note
feb0: 20 74 68 61 74 20 74 68 65 20 3c 79 79 74 65 72   that the <yyter
fec0: 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79  m>column-name</y
fed0: 79 74 65 72 6d 3e 20 6c 69 73 74 20 73 79 6e 74  yterm> list synt
fee0: 61 78 20 69 73 20 6f 6e 6c 79 0a 73 75 70 70 6f  ax is only.suppo
fef0: 72 74 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  rted in SQLite v
ff00: 65 72 73 69 6f 6e 73 20 33 2e 39 2e 30 20 28 5b  ersions 3.9.0 ([
ff10: 64 61 74 65 6f 66 3a 33 2e 39 2e 30 5d 29 20 61  dateof:3.9.0]) a
ff20: 6e 64 20 6c 61 74 65 72 2e 0a 0a 3c 74 63 6c 3e  nd later...<tcl>
ff30: 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
ff40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ff50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ff60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ff70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
ff80: 53 65 63 74 69 6f 6e 20 7b 43 52 45 41 54 45 20  Section {CREATE 
ff90: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 7d 20 7b  VIRTUAL TABLE} {
ffa0: 63 72 65 61 74 65 76 74 61 62 7d 20 7b 7b 43 52  createvtab} {{CR
ffb0: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
ffc0: 4c 45 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  LE}}..RecursiveB
ffd0: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 72 65  ubbleDiagram cre
ffe0: 61 74 65 2d 76 69 72 74 75 61 6c 2d 74 61 62 6c  ate-virtual-tabl
fff0: 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  e-stmt.</tcl>..<
10000 70 3e 41 20 5b 76 69 72 74 75 61 6c 20 74 61 62  p>A [virtual tab
10010 6c 65 5d 20 69 73 20 61 6e 20 69 6e 74 65 72 66  le] is an interf
10020 61 63 65 20 74 6f 20 61 6e 20 65 78 74 65 72 6e  ace to an extern
10030 61 6c 20 73 74 6f 72 61 67 65 20 6f 72 20 63 6f  al storage or co
10040 6d 70 75 74 61 74 69 6f 6e 0a 65 6e 67 69 6e 65  mputation.engine
10050 20 74 68 61 74 20 61 70 70 65 61 72 73 20 74 6f   that appears to
10060 20 62 65 20 61 20 74 61 62 6c 65 20 62 75 74 20   be a table but 
10070 64 6f 65 73 20 6e 6f 74 20 61 63 74 75 61 6c 6c  does not actuall
10080 79 20 73 74 6f 72 65 20 69 6e 66 6f 72 6d 61 74  y store informat
10090 69 6f 6e 0a 69 6e 20 74 68 65 20 64 61 74 61 62  ion.in the datab
100a0 61 73 65 20 66 69 6c 65 2e 3c 2f 70 3e 0a 0a 3c  ase file.</p>..<
100b0 70 3e 49 6e 20 67 65 6e 65 72 61 6c 2c 20 79 6f  p>In general, yo
100c0 75 20 63 61 6e 20 64 6f 20 61 6e 79 74 68 69 6e  u can do anythin
100d0 67 20 77 69 74 68 20 61 20 5b 76 69 72 74 75 61  g with a [virtua
100e0 6c 20 74 61 62 6c 65 5d 20 74 68 61 74 20 63 61  l table] that ca
100f0 6e 20 62 65 20 64 6f 6e 65 0a 77 69 74 68 20 61  n be done.with a
10100 6e 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  n ordinary table
10110 2c 20 65 78 63 65 70 74 20 74 68 61 74 20 5e 79  , except that ^y
10120 6f 75 20 63 61 6e 6e 6f 74 20 63 72 65 61 74 65  ou cannot create
10130 20 69 6e 64 69 63 65 73 20 6f 72 20 74 72 69 67   indices or trig
10140 67 65 72 73 20 6f 6e 20 61 0a 76 69 72 74 75 61  gers on a.virtua
10150 6c 20 74 61 62 6c 65 2e 20 20 5e 53 6f 6d 65 20  l table.  ^Some 
10160 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
10170 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
10180 67 68 74 20 69 6d 70 6f 73 65 20 61 64 64 69 74  ght impose addit
10190 69 6f 6e 61 6c 0a 72 65 73 74 72 69 63 74 69 6f  ional.restrictio
101a0 6e 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ns.  For example
101b0 2c 20 6d 61 6e 79 20 76 69 72 74 75 61 6c 20 74  , many virtual t
101c0 61 62 6c 65 73 20 61 72 65 20 72 65 61 64 2d 6f  ables are read-o
101d0 6e 6c 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  nly.</p>..<p>The
101e0 20 3c 79 79 74 65 72 6d 3e 6d 6f 64 75 6c 65 2d   <yyterm>module-
101f0 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 69 73  name</yyterm> is
10200 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 20   the name of an 
10210 6f 62 6a 65 63 74 20 74 68 61 74 20 69 6d 70 6c  object that impl
10220 65 6d 65 6e 74 73 0a 74 68 65 20 76 69 72 74 75  ements.the virtu
10230 61 6c 20 74 61 62 6c 65 2e 20 20 5e 54 68 65 20  al table.  ^The 
10240 3c 79 79 74 65 72 6d 3e 6d 6f 64 75 6c 65 2d 6e  <yyterm>module-n
10250 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 6d 75 73  ame</yyterm> mus
10260 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
10270 77 69 74 68 0a 74 68 65 20 53 51 4c 69 74 65 20  with.the SQLite 
10280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10290 69 6f 6e 20 75 73 69 6e 67 0a 5b 73 71 6c 69 74  ion using.[sqlit
102a0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
102b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
102c0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
102d0 28 29 5d 0a 70 72 69 6f 72 20 74 6f 20 69 73 73  ()].prior to iss
102e0 75 69 6e 67 20 74 68 65 20 43 52 45 41 54 45 20  uing the CREATE 
102f0 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
10300 61 74 65 6d 65 6e 74 2e 0a 5e 54 68 65 20 6d 6f  atement..^The mo
10310 64 75 6c 65 20 74 61 6b 65 73 20 7a 65 72 6f 20  dule takes zero 
10320 6f 72 20 6d 6f 72 65 20 63 6f 6d 6d 61 2d 73 65  or more comma-se
10330 70 61 72 61 74 65 64 20 61 72 67 75 6d 65 6e 74  parated argument
10340 73 2e 0a 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s..^The argument
10350 73 20 63 61 6e 20 62 65 20 6a 75 73 74 20 61 62  s can be just ab
10360 6f 75 74 20 61 6e 79 20 74 65 78 74 20 61 73 20  out any text as 
10370 6c 6f 6e 67 20 61 73 20 69 74 20 68 61 73 20 62  long as it has b
10380 61 6c 61 6e 63 65 64 0a 70 61 72 65 6e 74 68 65  alanced.parenthe
10390 73 65 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ses.  The argume
103a0 6e 74 20 73 79 6e 74 61 78 20 69 73 20 73 75 66  nt syntax is suf
103b0 66 69 63 69 65 6e 74 6c 79 20 67 65 6e 65 72 61  ficiently genera
103c0 6c 20 74 68 61 74 20 74 68 65 0a 61 72 67 75 6d  l that the.argum
103d0 65 6e 74 73 20 63 61 6e 20 62 65 20 6d 61 64 65  ents can be made
103e0 20 74 6f 20 61 70 70 65 61 72 20 61 73 20 5b 63   to appear as [c
103f0 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e  olumn definition
10400 73 5d 20 69 6e 20 61 20 74 72 61 64 69 74 69 6f  s] in a traditio
10410 6e 61 6c 0a 5b 43 52 45 41 54 45 20 54 41 42 4c  nal.[CREATE TABL
10420 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 0a  E] statement.  .
10430 5e 53 51 4c 69 74 65 20 70 61 73 73 65 73 20 74  ^SQLite passes t
10440 68 65 20 6d 6f 64 75 6c 65 20 61 72 67 75 6d 65  he module argume
10450 6e 74 73 20 64 69 72 65 63 74 6c 79 0a 74 6f 20  nts directly.to 
10460 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
10470 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
10480 68 6f 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  hods of the modu
10490 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
104a0 6e 0a 77 69 74 68 6f 75 74 20 61 6e 79 20 69 6e  n.without any in
104b0 74 65 72 70 72 65 74 61 74 69 6f 6e 2e 20 20 49  terpretation.  I
104c0 74 20 69 73 20 74 68 65 20 72 65 73 70 6f 6e 73  t is the respons
104d0 69 62 69 6c 69 74 79 0a 6f 66 20 74 68 65 20 6d  ibility.of the m
104e0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
104f0 74 69 6f 6e 20 74 6f 20 70 61 72 73 65 20 61 6e  tion to parse an
10500 64 20 69 6e 74 65 72 70 72 65 74 20 69 74 73 20  d interpret its 
10510 6f 77 6e 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f  own arguments.</
10520 70 3e 0a 0a 3c 70 3e 5e 41 20 76 69 72 74 75 61  p>..<p>^A virtua
10530 6c 20 74 61 62 6c 65 20 69 73 20 64 65 73 74 72  l table is destr
10540 6f 79 65 64 20 75 73 69 6e 67 20 74 68 65 20 6f  oyed using the o
10550 72 64 69 6e 61 72 79 0a 5b 44 52 4f 50 20 54 41  rdinary.[DROP TA
10560 42 4c 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  BLE] statement. 
10570 20 54 68 65 72 65 20 69 73 20 6e 6f 0a 44 52 4f   There is no.DRO
10580 50 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  P VIRTUAL TABLE 
10590 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a  statement.</p>..
105a0 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
105b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
105c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
105d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
105e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
105f0 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 44 45 4c  ####.Section DEL
10600 45 54 45 20 64 65 6c 65 74 65 20 7b 44 45 4c 45  ETE delete {DELE
10610 54 45 20 2a 44 45 4c 45 54 45 73 7d 0a 0a 52 65  TE *DELETEs}..Re
10620 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
10630 67 72 61 6d 20 64 65 6c 65 74 65 2d 73 74 6d 74  gram delete-stmt
10640 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68 65 20  .</tcl>..<p>The 
10650 44 45 4c 45 54 45 20 63 6f 6d 6d 61 6e 64 20 72  DELETE command r
10660 65 6d 6f 76 65 73 20 72 65 63 6f 72 64 73 20 66  emoves records f
10670 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 20 69 64  rom the table id
10680 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 0a  entified by the.
10690 20 20 20 5b 71 75 61 6c 69 66 69 65 64 2d 74 61     [qualified-ta
106a0 62 6c 65 2d 6e 61 6d 65 5d 2e 0a 0a 3c 70 3e 5e  ble-name]...<p>^
106b0 49 66 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  If the WHERE cla
106c0 75 73 65 20 69 73 20 6e 6f 74 20 70 72 65 73 65  use is not prese
106d0 6e 74 2c 20 61 6c 6c 20 72 65 63 6f 72 64 73 20  nt, all records 
106e0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 61 72 65  in the table are
106f0 20 64 65 6c 65 74 65 64 2e 0a 20 20 20 5e 49 66   deleted..   ^If
10700 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
10710 69 73 20 73 75 70 70 6c 69 65 64 2c 20 74 68 65  is supplied, the
10720 6e 20 6f 6e 6c 79 20 74 68 6f 73 65 20 72 6f 77  n only those row
10730 73 20 66 6f 72 20 77 68 69 63 68 20 74 68 65 0a  s for which the.
10740 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
10750 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73  [boolean express
10760 69 6f 6e 5d 20 69 73 20 74 72 75 65 20 61 72 65  ion] is true are
10770 20 64 65 6c 65 74 65 64 2e 0a 20 20 20 5e 52 6f   deleted..   ^Ro
10780 77 73 20 66 6f 72 20 77 68 69 63 68 20 74 68 65  ws for which the
10790 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 66   expression is f
107a0 61 6c 73 65 20 6f 72 20 4e 55 4c 4c 20 61 72 65  alse or NULL are
107b0 20 72 65 74 61 69 6e 65 64 2e 0a 0a 3c 68 33 3e   retained...<h3>
107c0 52 65 73 74 72 69 63 74 69 6f 6e 73 20 6f 6e 20  Restrictions on 
107d0 44 45 4c 45 54 45 20 53 74 61 74 65 6d 65 6e 74  DELETE Statement
107e0 73 20 57 69 74 68 69 6e 20 43 52 45 41 54 45 20  s Within CREATE 
107f0 54 52 49 47 47 45 52 3c 2f 68 33 3e 0a 0a 3c 70  TRIGGER</h3>..<p
10800 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 72  >The following r
10810 65 73 74 72 69 63 74 69 6f 6e 73 20 61 70 70 6c  estrictions appl
10820 79 20 74 6f 20 44 45 4c 45 54 45 20 73 74 61 74  y to DELETE stat
10830 65 6d 65 6e 74 73 20 74 68 61 74 20 6f 63 63 75  ements that occu
10840 72 20 77 69 74 68 69 6e 20 74 68 65 0a 20 20 20  r within the.   
10850 62 6f 64 79 20 6f 66 20 61 20 5b 43 52 45 41 54  body of a [CREAT
10860 45 20 54 52 49 47 47 45 52 5d 20 73 74 61 74 65  E TRIGGER] state
10870 6d 65 6e 74 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  ment:..<ul>.  <l
10880 69 3e 3c 70 3e 5e 54 68 65 20 3c 79 79 74 65 72  i><p>^The <yyter
10890 6d 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79  m>table-name</yy
108a0 74 65 72 6d 3e 20 73 70 65 63 69 66 69 65 64 20  term> specified 
108b0 61 73 20 70 61 72 74 20 6f 66 20 61 20 0a 20 20  as part of a .  
108c0 20 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65    DELETE stateme
108d0 6e 74 20 77 69 74 68 69 6e 0a 20 20 20 20 61 20  nt within.    a 
108e0 74 72 69 67 67 65 72 20 62 6f 64 79 20 6d 75 73  trigger body mus
108f0 74 20 62 65 20 75 6e 71 75 61 6c 69 66 69 65 64  t be unqualified
10900 2e 20 20 5e 28 49 6e 20 6f 74 68 65 72 20 77 6f  .  ^(In other wo
10910 72 64 73 2c 20 74 68 65 0a 20 20 20 20 3c 69 3e  rds, the.    <i>
10920 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69 3e 3c  schema-name</i><
10930 62 3e 2e 3c 2f 62 3e 20 70 72 65 66 69 78 20 6f  b>.</b> prefix o
10940 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
10950 20 69 73 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20   is not allowed 
10960 0a 20 20 20 20 77 69 74 68 69 6e 20 74 72 69 67  .    within trig
10970 67 65 72 73 2e 29 5e 20 5e 49 66 20 74 68 65 20  gers.)^ ^If the 
10980 74 61 62 6c 65 20 74 6f 20 77 68 69 63 68 20 74  table to which t
10990 68 65 20 74 72 69 67 67 65 72 20 69 73 20 61 74  he trigger is at
109a0 74 61 63 68 65 64 20 69 73 0a 20 20 20 20 6e 6f  tached is.    no
109b0 74 20 69 6e 20 74 68 65 20 74 65 6d 70 20 64 61  t in the temp da
109c0 74 61 62 61 73 65 2c 20 74 68 65 6e 20 44 45 4c  tabase, then DEL
109d0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 77  ETE statements w
109e0 69 74 68 69 6e 20 74 68 65 20 74 72 69 67 67 65  ithin the trigge
109f0 72 0a 20 20 20 20 62 6f 64 79 20 6d 75 73 74 20  r.    body must 
10a00 6f 70 65 72 61 74 65 20 6f 6e 20 74 61 62 6c 65  operate on table
10a10 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
10a20 65 20 64 61 74 61 62 61 73 65 20 61 73 20 69 74  e database as it
10a30 2e 20 5e 49 66 20 74 68 65 20 74 61 62 6c 65 0a  . ^If the table.
10a40 20 20 20 20 74 6f 20 77 68 69 63 68 20 74 68 65      to which the
10a50 20 74 72 69 67 67 65 72 20 69 73 20 61 74 74 61   trigger is atta
10a60 63 68 65 64 20 69 73 20 69 6e 20 74 68 65 20 54  ched is in the T
10a70 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 74 68  EMP database, th
10a80 65 6e 20 74 68 65 0a 20 20 20 20 75 6e 71 75 61  en the.    unqua
10a90 6c 69 66 69 65 64 20 6e 61 6d 65 20 6f 66 20 74  lified name of t
10aa0 68 65 20 74 61 62 6c 65 20 62 65 69 6e 67 20 64  he table being d
10ab0 65 6c 65 74 65 64 20 69 73 20 72 65 73 6f 6c 76  eleted is resolv
10ac0 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77  ed in the same w
10ad0 61 79 20 61 73 0a 20 20 20 20 69 74 20 69 73 20  ay as.    it is 
10ae0 66 6f 72 20 61 20 74 6f 70 2d 6c 65 76 65 6c 20  for a top-level 
10af0 73 74 61 74 65 6d 65 6e 74 20 28 62 79 20 73 65  statement (by se
10b00 61 72 63 68 69 6e 67 20 66 69 72 73 74 20 74 68  arching first th
10b10 65 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c  e TEMP database,
10b20 20 74 68 65 6e 0a 20 20 20 20 74 68 65 20 6d 61   then.    the ma
10b30 69 6e 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  in database, the
10b40 6e 20 61 6e 79 20 6f 74 68 65 72 20 64 61 74 61  n any other data
10b50 62 61 73 65 73 20 69 6e 20 74 68 65 20 6f 72 64  bases in the ord
10b60 65 72 20 74 68 65 79 20 77 65 72 65 0a 20 20 20  er they were.   
10b70 20 61 74 74 61 63 68 65 64 29 2e 0a 20 20 20 20   attached)..    
10b80 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 49  .  <li><p>^The I
10b90 4e 44 45 58 45 44 20 42 59 20 61 6e 64 20 4e 4f  NDEXED BY and NO
10ba0 54 20 49 4e 44 45 58 45 44 20 63 6c 61 75 73 65  T INDEXED clause
10bb0 73 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  s are not allowe
10bc0 64 20 6f 6e 20 44 45 4c 45 54 45 0a 20 20 20 20  d on DELETE.    
10bd0 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69  statements withi
10be0 6e 20 74 72 69 67 67 65 72 73 2e 3c 2f 70 3e 0a  n triggers.</p>.
10bf0 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 4c  .  <li><p>^The L
10c00 49 4d 49 54 20 61 6e 64 20 4f 52 44 45 52 20 42  IMIT and ORDER B
10c10 59 20 63 6c 61 75 73 65 73 20 28 64 65 73 63 72  Y clauses (descr
10c20 69 62 65 64 20 62 65 6c 6f 77 29 20 61 72 65 20  ibed below) are 
10c30 75 6e 73 75 70 70 6f 72 74 65 64 20 66 6f 72 0a  unsupported for.
10c40 20 20 20 20 44 45 4c 45 54 45 20 73 74 61 74 65      DELETE state
10c50 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 74 72 69  ments within tri
10c60 67 67 65 72 73 2e 3c 2f 70 3e 0a 3c 2f 75 6c 3e  ggers.</p>.</ul>
10c70 0a 0a 3c 68 33 3e 4f 70 74 69 6f 6e 61 6c 20 4c  ..<h3>Optional L
10c80 49 4d 49 54 20 61 6e 64 20 4f 52 44 45 52 20 42  IMIT and ORDER B
10c90 59 20 63 6c 61 75 73 65 73 3c 2f 68 33 3e 0a 0a  Y clauses</h3>..
10ca0 3c 70 3e 5e 28 49 66 20 53 51 4c 69 74 65 20 69  <p>^(If SQLite i
10cb0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10cc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
10cd0 4c 45 5f 55 50 44 41 54 45 5f 44 45 4c 45 54 45  LE_UPDATE_DELETE
10ce0 5f 4c 49 4d 49 54 5d 0a 63 6f 6d 70 69 6c 65 2d  _LIMIT].compile-
10cf0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
10d00 6e 20 74 68 65 20 73 79 6e 74 61 78 20 6f 66 20  n the syntax of 
10d10 74 68 65 20 44 45 4c 45 54 45 20 73 74 61 74 65  the DELETE state
10d20 6d 65 6e 74 20 69 73 0a 65 78 74 65 6e 64 65 64  ment is.extended
10d30 20 62 79 20 74 68 65 20 61 64 64 69 74 69 6f 6e   by the addition
10d40 20 6f 66 20 6f 70 74 69 6f 6e 61 6c 20 4f 52 44   of optional ORD
10d50 45 52 20 42 59 20 61 6e 64 20 4c 49 4d 49 54 20  ER BY and LIMIT 
10d60 63 6c 61 75 73 65 73 3a 29 5e 3c 2f 70 3e 0a 0a  clauses:)^</p>..
10d70 3c 74 63 6c 3e 42 75 62 62 6c 65 44 69 61 67 72  <tcl>BubbleDiagr
10d80 61 6d 20 64 65 6c 65 74 65 2d 73 74 6d 74 2d 6c  am delete-stmt-l
10d90 69 6d 69 74 65 64 3c 2f 74 63 6c 3e 0a 0a 3c 70  imited</tcl>..<p
10da0 3e 5e 49 66 20 61 20 44 45 4c 45 54 45 20 73 74  >^If a DELETE st
10db0 61 74 65 6d 65 6e 74 20 68 61 73 20 61 20 4c 49  atement has a LI
10dc0 4d 49 54 20 63 6c 61 75 73 65 2c 20 74 68 65 20  MIT clause, the 
10dd0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10de0 66 20 72 6f 77 73 20 74 68 61 74 0a 77 69 6c 6c  f rows that.will
10df0 20 62 65 20 64 65 6c 65 74 65 64 20 69 73 20 66   be deleted is f
10e00 6f 75 6e 64 20 62 79 20 65 76 61 6c 75 61 74 69  ound by evaluati
10e10 6e 67 20 74 68 65 20 61 63 63 6f 6d 70 61 6e 79  ng the accompany
10e20 69 6e 67 20 65 78 70 72 65 73 73 69 6f 6e 20 61  ing expression a
10e30 6e 64 20 63 61 73 74 69 6e 67 0a 69 74 20 74 6f  nd casting.it to
10e40 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75   an integer valu
10e50 65 2e 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  e. ^If the resul
10e60 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
10e70 69 6e 67 20 74 68 65 20 4c 49 4d 49 54 20 63 6c  ing the LIMIT cl
10e80 61 75 73 65 0a 63 61 6e 6e 6f 74 20 62 65 20 6c  ause.cannot be l
10e90 6f 73 73 6c 65 73 73 6c 79 20 63 6f 6e 76 65 72  osslessly conver
10ea0 74 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ted to an intege
10eb0 72 20 76 61 6c 75 65 2c 20 69 74 20 69 73 20 61  r value, it is a
10ec0 6e 20 65 72 72 6f 72 2e 20 5e 41 20 0a 6e 65 67  n error. ^A .neg
10ed0 61 74 69 76 65 20 4c 49 4d 49 54 20 76 61 6c 75  ative LIMIT valu
10ee0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
10ef0 20 61 73 20 22 6e 6f 20 6c 69 6d 69 74 22 2e 20   as "no limit". 
10f00 5e 28 49 66 20 74 68 65 20 44 45 4c 45 54 45 20  ^(If the DELETE 
10f10 73 74 61 74 65 6d 65 6e 74 20 0a 61 6c 73 6f 20  statement .also 
10f20 68 61 73 20 61 6e 20 4f 46 46 53 45 54 20 63 6c  has an OFFSET cl
10f30 61 75 73 65 2c 20 74 68 65 6e 20 69 74 20 69 73  ause, then it is
10f40 20 73 69 6d 69 6c 61 72 6c 79 20 65 76 61 6c 75   similarly evalu
10f50 61 74 65 64 20 61 6e 64 20 63 61 73 74 20 74 6f  ated and cast to
10f60 20 61 6e 0a 69 6e 74 65 67 65 72 20 76 61 6c 75   an.integer valu
10f70 65 2e 20 41 67 61 69 6e 2c 20 69 74 20 69 73 20  e. Again, it is 
10f80 61 6e 20 65 72 72 6f 72 20 69 66 20 74 68 65 20  an error if the 
10f90 76 61 6c 75 65 20 63 61 6e 6e 6f 74 20 62 65 20  value cannot be 
10fa0 6c 6f 73 73 6c 65 73 73 6c 79 0a 63 6f 6e 76 65  losslessly.conve
10fb0 72 74 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67  rted to an integ
10fc0 65 72 2e 29 5e 20 5e 49 66 20 74 68 65 72 65 20  er.)^ ^If there 
10fd0 69 73 20 6e 6f 20 4f 46 46 53 45 54 20 63 6c 61  is no OFFSET cla
10fe0 75 73 65 2c 20 6f 72 20 74 68 65 20 63 61 6c 63  use, or the calc
10ff0 75 6c 61 74 65 64 0a 69 6e 74 65 67 65 72 20 76  ulated.integer v
11000 61 6c 75 65 20 69 73 20 6e 65 67 61 74 69 76 65  alue is negative
11010 2c 20 74 68 65 20 65 66 66 65 63 74 69 76 65 20  , the effective 
11020 4f 46 46 53 45 54 20 76 61 6c 75 65 20 69 73 20  OFFSET value is 
11030 7a 65 72 6f 2e 0a 0a 3c 70 3e 5e 28 49 66 20 74  zero...<p>^(If t
11040 68 65 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  he DELETE statem
11050 65 6e 74 20 68 61 73 20 61 6e 20 4f 52 44 45 52  ent has an ORDER
11060 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 6e   BY clause, then
11070 20 61 6c 6c 20 72 6f 77 73 20 74 68 61 74 20 77   all rows that w
11080 6f 75 6c 64 20 0a 62 65 20 64 65 6c 65 74 65 64  ould .be deleted
11090 20 69 6e 20 74 68 65 20 61 62 73 65 6e 63 65 20   in the absence 
110a0 6f 66 20 74 68 65 20 4c 49 4d 49 54 20 63 6c 61  of the LIMIT cla
110b0 75 73 65 20 61 72 65 20 73 6f 72 74 65 64 20 61  use are sorted a
110c0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
110d0 0a 4f 52 44 45 52 20 42 59 2e 20 54 68 65 20 66  .ORDER BY. The f
110e0 69 72 73 74 20 3c 69 3e 4d 3c 2f 69 3e 20 72 6f  irst <i>M</i> ro
110f0 77 73 2c 20 77 68 65 72 65 20 3c 69 3e 4d 3c 2f  ws, where <i>M</
11100 69 3e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  i> is the value 
11110 66 6f 75 6e 64 20 62 79 0a 65 76 61 6c 75 61 74  found by.evaluat
11120 69 6e 67 20 74 68 65 20 4f 46 46 53 45 54 20 63  ing the OFFSET c
11130 6c 61 75 73 65 20 65 78 70 72 65 73 73 69 6f 6e  lause expression
11140 2c 20 61 72 65 20 73 6b 69 70 70 65 64 2c 20 61  , are skipped, a
11150 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
11160 20 0a 3c 69 3e 4e 3c 2f 69 3e 2c 20 77 68 65 72   .<i>N</i>, wher
11170 65 20 3c 69 3e 4e 3c 2f 69 3e 20 69 73 20 74 68  e <i>N</i> is th
11180 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 4c  e value of the L
11190 49 4d 49 54 20 65 78 70 72 65 73 73 69 6f 6e 2c  IMIT expression,
111a0 20 61 72 65 20 64 65 6c 65 74 65 64 2e 29 5e 0a   are deleted.)^.
111b0 5e 49 66 20 74 68 65 72 65 20 61 72 65 20 6c 65  ^If there are le
111c0 73 73 20 74 68 61 6e 20 3c 69 3e 4e 3c 2f 69 3e  ss than <i>N</i>
111d0 20 72 6f 77 73 20 72 65 6d 61 69 6e 69 6e 67 20   rows remaining 
111e0 61 66 74 65 72 20 74 61 6b 69 6e 67 20 74 68 65  after taking the
111f0 20 4f 46 46 53 45 54 20 63 6c 61 75 73 65 0a 69   OFFSET clause.i
11200 6e 74 6f 20 61 63 63 6f 75 6e 74 2c 20 6f 72 20  nto account, or 
11210 69 66 20 74 68 65 20 4c 49 4d 49 54 20 63 6c 61  if the LIMIT cla
11220 75 73 65 20 65 76 61 6c 75 61 74 65 64 20 74 6f  use evaluated to
11230 20 61 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   a negative valu
11240 65 2c 20 74 68 65 6e 20 61 6c 6c 0a 72 65 6d 61  e, then all.rema
11250 69 6e 69 6e 67 20 72 6f 77 73 20 61 72 65 20 64  ining rows are d
11260 65 6c 65 74 65 64 2e 0a 0a 3c 70 3e 5e 49 66 20  eleted...<p>^If 
11270 74 68 65 20 44 45 4c 45 54 45 20 73 74 61 74 65  the DELETE state
11280 6d 65 6e 74 20 68 61 73 20 6e 6f 20 4f 52 44 45  ment has no ORDE
11290 52 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65  R BY clause, the
112a0 6e 20 61 6c 6c 20 72 6f 77 73 20 74 68 61 74 0a  n all rows that.
112b0 77 6f 75 6c 64 20 62 65 20 64 65 6c 65 74 65 64  would be deleted
112c0 20 69 6e 20 74 68 65 20 61 62 73 65 6e 63 65 20   in the absence 
112d0 6f 66 20 74 68 65 20 4c 49 4d 49 54 20 63 6c 61  of the LIMIT cla
112e0 75 73 65 20 61 72 65 20 61 73 73 65 6d 62 6c 65  use are assemble
112f0 64 20 69 6e 20 61 6e 0a 61 72 62 69 74 72 61 72  d in an.arbitrar
11300 79 20 6f 72 64 65 72 20 62 65 66 6f 72 65 20 61  y order before a
11310 70 70 6c 79 69 6e 67 20 74 68 65 20 4c 49 4d 49  pplying the LIMI
11320 54 20 61 6e 64 20 4f 46 46 53 45 54 20 63 6c 61  T and OFFSET cla
11330 75 73 65 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  uses to determin
11340 65 20 0a 74 68 65 20 73 75 62 73 65 74 20 74 68  e .the subset th
11350 61 74 20 61 72 65 20 61 63 74 75 61 6c 6c 79 20  at are actually 
11360 64 65 6c 65 74 65 64 2e 0a 0a 3c 70 3e 5e 28 54  deleted...<p>^(T
11370 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
11380 73 65 20 6f 6e 20 61 20 44 45 4c 45 54 45 20 73  se on a DELETE s
11390 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 65 64  tatement is used
113a0 20 6f 6e 6c 79 20 74 6f 20 64 65 74 65 72 6d 69   only to determi
113b0 6e 65 20 77 68 69 63 68 0a 72 6f 77 73 20 66 61  ne which.rows fa
113c0 6c 6c 20 77 69 74 68 69 6e 20 74 68 65 20 4c 49  ll within the LI
113d0 4d 49 54 2e 20 54 68 65 20 6f 72 64 65 72 20 69  MIT. The order i
113e0 6e 20 77 68 69 63 68 20 72 6f 77 73 20 61 72 65  n which rows are
113f0 20 64 65 6c 65 74 65 64 20 69 73 20 61 72 62 69   deleted is arbi
11400 74 72 61 72 79 0a 61 6e 64 20 69 73 20 6e 6f 74  trary.and is not
11410 20 69 6e 66 6c 75 65 6e 63 65 64 20 62 79 20 74   influenced by t
11420 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
11430 73 65 2e 29 5e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  se.)^..<tcl>hd_f
11440 72 61 67 6d 65 6e 74 20 74 72 75 6e 63 61 74 65  ragment truncate
11450 6f 70 74 20 7b 74 72 75 6e 63 61 74 65 20 6f 70  opt {truncate op
11460 74 69 6d 69 7a 61 74 69 6f 6e 7d 3c 2f 74 63 6c  timization}</tcl
11470 3e 0a 3c 68 33 3e 54 68 65 20 54 72 75 6e 63 61  >.<h3>The Trunca
11480 74 65 20 4f 70 74 69 6d 69 7a 61 74 69 6f 6e 3c  te Optimization<
11490 2f 68 33 3e 0a 0a 3c 70 3e 5e 57 68 65 6e 20 74  /h3>..<p>^When t
114a0 68 65 20 57 48 45 52 45 20 69 73 20 6f 6d 69 74  he WHERE is omit
114b0 74 65 64 20 66 72 6f 6d 20 61 20 44 45 4c 45 54  ted from a DELET
114c0 45 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  E statement and 
114d0 74 68 65 20 74 61 62 6c 65 0a 62 65 69 6e 67 20  the table.being 
114e0 64 65 6c 65 74 65 64 20 68 61 73 20 6e 6f 20 74  deleted has no t
114f0 72 69 67 67 65 72 73 2c 0a 53 51 4c 69 74 65 20  riggers,.SQLite 
11500 75 73 65 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61  uses an optimiza
11510 74 69 6f 6e 20 74 6f 20 65 72 61 73 65 20 74 68  tion to erase th
11520 65 20 65 6e 74 69 72 65 20 74 61 62 6c 65 20 63  e entire table c
11530 6f 6e 74 65 6e 74 0a 77 69 74 68 6f 75 74 20 68  ontent.without h
11540 61 76 69 6e 67 20 74 6f 20 76 69 73 69 74 20 65  aving to visit e
11550 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 74  ach row of the t
11560 61 62 6c 65 20 69 6e 64 69 76 69 64 75 61 6c 6c  able individuall
11570 79 2e 0a 54 68 69 73 20 22 74 72 75 6e 63 61 74  y..This "truncat
11580 65 22 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  e" optimization 
11590 6d 61 6b 65 73 20 74 68 65 20 64 65 6c 65 74 65  makes the delete
115a0 20 72 75 6e 20 6d 75 63 68 20 66 61 73 74 65 72   run much faster
115b0 2e 0a 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  ..Prior to SQLit
115c0 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 35  e [version 3.6.5
115d0 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 35  ] ([dateof:3.6.5
115e0 5d 29 2c 20 74 68 65 20 74 72 75 6e 63 61 74 65  ]), the truncate
115f0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 0a 61 6c   optimization.al
11600 73 6f 20 6d 65 61 6e 74 20 74 68 61 74 20 74 68  so meant that th
11610 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11620 65 73 28 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74  es()] and.[sqlit
11630 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11640 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 61  ()] interfaces.a
11650 6e 64 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68  nd the [count_ch
11660 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 77 69  anges pragma].wi
11670 6c 6c 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  ll not actually 
11680 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
11690 72 20 6f 66 20 64 65 6c 65 74 65 64 20 72 6f 77  r of deleted row
116a0 73 2e 20 20 0a 54 68 61 74 20 70 72 6f 62 6c 65  s.  .That proble
116b0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
116c0 20 61 73 20 6f 66 20 5b 76 65 72 73 69 6f 6e 20   as of [version 
116d0 33 2e 36 2e 35 5d 20 28 5b 64 61 74 65 6f 66 3a  3.6.5] ([dateof:
116e0 33 2e 36 2e 35 5d 29 2e 0a 0a 3c 70 3e 5e 54 68  3.6.5])...<p>^Th
116f0 65 20 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d  e truncate optim
11700 69 7a 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 70  ization can be p
11710 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61 62  ermanently disab
11720 6c 65 64 20 66 6f 72 20 61 6c 6c 20 71 75 65 72  led for all quer
11730 69 65 73 0a 62 79 20 72 65 63 6f 6d 70 69 6c 69  ies.by recompili
11740 6e 67 0a 53 51 4c 69 74 65 20 77 69 74 68 20 74  ng.SQLite with t
11750 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
11760 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a  TRUNCATE_OPTIMIZ
11770 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  ATION] compile-t
11780 69 6d 65 20 73 77 69 74 63 68 2e 3c 2f 70 3e 0a  ime switch.</p>.
11790 0a 3c 70 3e 54 68 65 20 74 72 75 6e 63 61 74 65  .<p>The truncate
117a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 63 61   optimization ca
117b0 6e 20 61 6c 73 6f 20 62 65 20 64 69 73 61 62 6c  n also be disabl
117c0 65 64 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73  ed at runtime us
117d0 69 6e 67 0a 74 68 65 20 5b 73 71 6c 69 74 65 33  ing.the [sqlite3
117e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
117f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 5e  )] interface.  ^
11800 49 66 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  If an authorizer
11810 20 63 61 6c 6c 62 61 63 6b 0a 72 65 74 75 72 6e   callback.return
11820 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
11830 5d 20 66 6f 72 20 61 6e 20 5b 53 51 4c 49 54 45  ] for an [SQLITE
11840 5f 44 45 4c 45 54 45 5d 20 61 63 74 69 6f 6e 20  _DELETE] action 
11850 63 6f 64 65 2c 20 74 68 65 6e 0a 74 68 65 20 44  code, then.the D
11860 45 4c 45 54 45 20 6f 70 65 72 61 74 69 6f 6e 20  ELETE operation 
11870 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 62 75 74  will proceed but
11880 20 74 68 65 20 74 72 75 6e 63 61 74 65 20 6f 70   the truncate op
11890 74 69 6d 69 7a 61 74 69 6f 6e 20 77 69 6c 6c 0a  timization will.
118a0 62 65 20 62 79 70 61 73 73 65 64 20 61 6e 64 20  be bypassed and 
118b0 72 6f 77 73 20 77 69 6c 6c 20 62 65 20 64 65 6c  rows will be del
118c0 65 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 2e  eted one by one.
118d0 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  </p>..<tcl>.####
118e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
118f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11900 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11910 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11920 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
11930 69 6f 6e 20 7b 44 45 54 41 43 48 20 44 41 54 41  ion {DETACH DATA
11940 42 41 53 45 7d 20 64 65 74 61 63 68 20 2a 44 45  BASE} detach *DE
11950 54 41 43 48 0a 0a 52 65 63 75 72 73 69 76 65 42  TACH..RecursiveB
11960 75 62 62 6c 65 44 69 61 67 72 61 6d 20 64 65 74  ubbleDiagram det
11970 61 63 68 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a  ach-stmt.</tcl>.
11980 0a 3c 70 3e 5e 54 68 69 73 20 73 74 61 74 65 6d  .<p>^This statem
11990 65 6e 74 20 64 65 74 61 63 68 65 73 20 61 6e 20  ent detaches an 
119a0 61 64 64 69 74 69 6f 6e 61 6c 20 64 61 74 61 62  additional datab
119b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
119c0 72 65 76 69 6f 75 73 6c 79 20 0a 61 74 74 61 63  reviously .attac
119d0 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41  hed using the [A
119e0 54 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  TTACH] statement
119f0 2e 20 20 0a 5e 57 68 65 6e 20 6e 6f 74 20 69 6e  .  .^When not in
11a00 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
11a10 6f 64 65 5d 2c 20 0a 69 74 20 69 73 20 70 6f 73  ode], .it is pos
11a20 73 69 62 6c 65 20 74 6f 20 68 61 76 65 20 74 68  sible to have th
11a30 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
11a40 66 69 6c 65 20 61 74 74 61 63 68 65 64 20 6d 75  file attached mu
11a50 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
11a60 6e 67 20 0a 64 69 66 66 65 72 65 6e 74 20 6e 61  ng .different na
11a70 6d 65 73 2c 20 61 6e 64 20 64 65 74 61 63 68 69  mes, and detachi
11a80 6e 67 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f  ng one connectio
11a90 6e 20 74 6f 20 61 20 66 69 6c 65 20 77 69 6c 6c  n to a file will
11aa0 20 6c 65 61 76 65 20 74 68 65 20 0a 6f 74 68 65   leave the .othe
11ab0 72 73 20 69 6e 74 61 63 74 2e 3c 2f 70 3e 0a 5e  rs intact.</p>.^
11ac0 49 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  In [shared cache
11ad0 20 6d 6f 64 65 5d 2c 20 61 74 74 65 6d 70 74 69   mode], attempti
11ae0 6e 67 20 74 6f 20 61 74 74 61 63 68 20 74 68 65  ng to attach the
11af0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 66   same database f
11b00 69 6c 65 20 6d 6f 72 65 0a 74 68 61 6e 20 6f 6e  ile more.than on
11b10 63 65 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  ce results in an
11b20 20 65 72 72 6f 72 2e 0a 0a 3c 70 3e 5e 54 68 69   error...<p>^Thi
11b30 73 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  s statement will
11b40 20 66 61 69 6c 20 69 66 20 53 51 4c 69 74 65 20   fail if SQLite 
11b50 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
11b60 20 6f 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   of a transactio
11b70 6e 2e 3c 2f 70 3e 0a 0a 0a 3c 74 63 6c 3e 0a 23  n.</p>...<tcl>.#
11b80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11b90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11ba0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11bb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11bc0 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
11bd0 63 74 69 6f 6e 20 7b 44 52 4f 50 20 49 4e 44 45  ction {DROP INDE
11be0 58 7d 20 64 72 6f 70 69 6e 64 65 78 20 7b 7b 44  X} dropindex {{D
11bf0 52 4f 50 20 49 4e 44 45 58 7d 7d 0a 0a 52 65 63  ROP INDEX}}..Rec
11c00 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
11c10 72 61 6d 20 64 72 6f 70 2d 69 6e 64 65 78 2d 73  ram drop-index-s
11c20 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e  tmt.</tcl>..<p>^
11c30 54 68 65 20 44 52 4f 50 20 49 4e 44 45 58 20 73  The DROP INDEX s
11c40 74 61 74 65 6d 65 6e 74 20 72 65 6d 6f 76 65 73  tatement removes
11c50 20 61 6e 20 69 6e 64 65 78 20 61 64 64 65 64 0a   an index added.
11c60 77 69 74 68 20 74 68 65 20 5b 43 52 45 41 54 45  with the [CREATE
11c70 20 49 4e 44 45 58 5d 20 73 74 61 74 65 6d 65 6e   INDEX] statemen
11c80 74 2e 20 20 54 68 65 20 69 6e 64 65 78 20 69 73  t.  The index is
11c90 20 63 6f 6d 70 6c 65 74 65 6c 79 20 72 65 6d 6f   completely remo
11ca0 76 65 64 20 66 72 6f 6d 0a 74 68 65 20 64 69 73  ved from.the dis
11cb0 6b 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  k.  The only way
11cc0 20 74 6f 20 72 65 63 6f 76 65 72 20 74 68 65 20   to recover the 
11cd0 69 6e 64 65 78 20 69 73 20 74 6f 20 72 65 65 6e  index is to reen
11ce0 74 65 72 20 74 68 65 0a 61 70 70 72 6f 70 72 69  ter the.appropri
11cf0 61 74 65 20 5b 43 52 45 41 54 45 20 49 4e 44 45  ate [CREATE INDE
11d00 58 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70 3e 0a  X] command.</p>.
11d10 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23  .<tcl>.#########
11d20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11d30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11d40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11d50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11d60 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44  #####.Section {D
11d70 52 4f 50 20 54 41 42 4c 45 7d 20 64 72 6f 70 74  ROP TABLE} dropt
11d80 61 62 6c 65 20 7b 7b 44 52 4f 50 20 54 41 42 4c  able {{DROP TABL
11d90 45 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75  E}}..RecursiveBu
11da0 62 62 6c 65 44 69 61 67 72 61 6d 20 64 72 6f 70  bbleDiagram drop
11db0 2d 74 61 62 6c 65 2d 73 74 6d 74 0a 3c 2f 74 63  -table-stmt.</tc
11dc0 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 44 52 4f 50  l>..<p>^The DROP
11dd0 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
11de0 20 72 65 6d 6f 76 65 73 20 61 20 74 61 62 6c 65   removes a table
11df0 20 61 64 64 65 64 20 77 69 74 68 20 74 68 65 0a   added with the.
11e00 5b 43 52 45 41 54 45 20 54 41 42 4c 45 5d 20 73  [CREATE TABLE] s
11e10 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 6e  tatement.  The n
11e20 61 6d 65 20 73 70 65 63 69 66 69 65 64 20 69 73  ame specified is
11e30 20 74 68 65 0a 74 61 62 6c 65 20 6e 61 6d 65 2e   the.table name.
11e40 20 20 5e 54 68 65 20 64 72 6f 70 70 65 64 20 74    ^The dropped t
11e50 61 62 6c 65 20 69 73 20 63 6f 6d 70 6c 65 74 65  able is complete
11e60 6c 79 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20  ly removed from 
11e70 74 68 65 20 64 61 74 61 62 61 73 65 20 0a 73 63  the database .sc
11e80 68 65 6d 61 20 61 6e 64 20 74 68 65 20 64 69 73  hema and the dis
11e90 6b 20 66 69 6c 65 2e 20 20 54 68 65 20 74 61 62  k file.  The tab
11ea0 6c 65 20 63 61 6e 20 6e 6f 74 20 62 65 20 72 65  le can not be re
11eb0 63 6f 76 65 72 65 64 2e 20 20 0a 5e 41 6c 6c 20  covered.  .^All 
11ec0 69 6e 64 69 63 65 73 20 61 6e 64 20 74 72 69 67  indices and trig
11ed0 67 65 72 73 0a 61 73 73 6f 63 69 61 74 65 64 20  gers.associated 
11ee0 77 69 74 68 20 74 68 65 20 74 61 62 6c 65 20 61  with the table a
11ef0 72 65 20 61 6c 73 6f 20 64 65 6c 65 74 65 64 2e  re also deleted.
11f00 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 6f 70  </p>..<p>^The op
11f10 74 69 6f 6e 61 6c 20 49 46 20 45 58 49 53 54 53  tional IF EXISTS
11f20 20 63 6c 61 75 73 65 20 73 75 70 70 72 65 73 73   clause suppress
11f30 65 73 20 74 68 65 20 65 72 72 6f 72 20 74 68 61  es the error tha
11f40 74 20 77 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79  t would normally
11f50 0a 72 65 73 75 6c 74 20 69 66 20 74 68 65 20 74  .result if the t
11f60 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65 78  able does not ex
11f70 69 73 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66  ist.</p>..<p>^If
11f80 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
11f90 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65  nstraints] are e
11fa0 6e 61 62 6c 65 64 2c 20 61 20 44 52 4f 50 20 54  nabled, a DROP T
11fb0 41 42 4c 45 20 63 6f 6d 6d 61 6e 64 20 70 65 72  ABLE command per
11fc0 66 6f 72 6d 73 20 61 6e 0a 69 6d 70 6c 69 63 69  forms an.implici
11fd0 74 20 5b 44 45 4c 45 54 45 20 7c 20 44 45 4c 45  t [DELETE | DELE
11fe0 54 45 20 46 52 4f 4d 5d 20 63 6f 6d 6d 61 6e 64  TE FROM] command
11ff0 20 62 65 66 6f 72 65 20 72 65 6d 6f 76 69 6e 67   before removing
12000 20 74 68 65 0a 74 61 62 6c 65 20 66 72 6f 6d 20   the.table from 
12010 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
12020 65 6d 61 2e 20 5e 41 6e 79 20 74 72 69 67 67 65  ema. ^Any trigge
12030 72 73 20 61 74 74 61 63 68 65 64 20 74 6f 20 74  rs attached to t
12040 68 65 20 74 61 62 6c 65 20 61 72 65 0a 64 72 6f  he table are.dro
12050 70 70 65 64 20 66 72 6f 6d 20 74 68 65 20 64 61  pped from the da
12060 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 62 65  tabase schema be
12070 66 6f 72 65 20 74 68 65 20 69 6d 70 6c 69 63 69  fore the implici
12080 74 20 44 45 4c 45 54 45 20 46 52 4f 4d 0a 69 73  t DELETE FROM.is
12090 20 65 78 65 63 75 74 65 64 2c 20 73 6f 20 74 68   executed, so th
120a0 69 73 20 63 61 6e 6e 6f 74 20 63 61 75 73 65 20  is cannot cause 
120b0 61 6e 79 20 74 72 69 67 67 65 72 73 20 74 6f 20  any triggers to 
120c0 66 69 72 65 2e 20 42 79 20 63 6f 6e 74 72 61 73  fire. By contras
120d0 74 2c 20 5e 61 6e 0a 69 6d 70 6c 69 63 69 74 20  t, ^an.implicit 
120e0 44 45 4c 45 54 45 20 46 52 4f 4d 20 64 6f 65 73  DELETE FROM does
120f0 20 63 61 75 73 65 20 61 6e 79 20 63 6f 6e 66 69   cause any confi
12100 67 75 72 65 64 0a 5b 66 6f 72 65 69 67 6e 20 6b  gured.[foreign k
12110 65 79 20 61 63 74 69 6f 6e 73 5d 20 74 6f 20 74  ey actions] to t
12120 61 6b 65 20 70 6c 61 63 65 2e 20 0a 5e 49 66 20  ake place. .^If 
12130 74 68 65 20 69 6d 70 6c 69 63 69 74 20 44 45 4c  the implicit DEL
12140 45 54 45 20 46 52 4f 4d 20 65 78 65 63 75 74 65  ETE FROM execute
12150 64 0a 61 73 20 70 61 72 74 20 6f 66 20 61 20 44  d.as part of a D
12160 52 4f 50 20 54 41 42 4c 45 20 63 6f 6d 6d 61 6e  ROP TABLE comman
12170 64 20 76 69 6f 6c 61 74 65 73 20 61 6e 79 20 69  d violates any i
12180 6d 6d 65 64 69 61 74 65 20 66 6f 72 65 69 67 6e  mmediate foreign
12190 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
121a0 2c 0a 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  ,.an error is re
121b0 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 74  turned and the t
121c0 61 62 6c 65 20 69 73 20 6e 6f 74 20 64 72 6f 70  able is not drop
121d0 70 65 64 2e 20 5e 49 66 20 0a 74 68 65 20 69 6d  ped. ^If .the im
121e0 70 6c 69 63 69 74 20 44 45 4c 45 54 45 20 46 52  plicit DELETE FR
121f0 4f 4d 20 63 61 75 73 65 73 20 61 6e 79 20 0a 64  OM causes any .d
12200 65 66 65 72 72 65 64 20 66 6f 72 65 69 67 6e 20  eferred foreign 
12210 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  key constraints 
12220 74 6f 20 62 65 20 76 69 6f 6c 61 74 65 64 2c 20  to be violated, 
12230 61 6e 64 20 74 68 65 20 76 69 6f 6c 61 74 69 6f  and the violatio
12240 6e 73 20 73 74 69 6c 6c 0a 65 78 69 73 74 20 77  ns still.exist w
12250 68 65 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74  hen the transact
12260 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
12270 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
12280 74 75 72 6e 65 64 20 61 74 20 74 68 65 20 74 69  turned at the ti
12290 6d 65 0a 6f 66 20 63 6f 6d 6d 69 74 2e 0a 0a 3c  me.of commit...<
122a0 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
122b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
122c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
122d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
122e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
122f0 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44 52 4f  ###.Section {DRO
12300 50 20 54 52 49 47 47 45 52 7d 20 64 72 6f 70 74  P TRIGGER} dropt
12310 72 69 67 67 65 72 20 7b 7b 44 52 4f 50 20 54 52  rigger {{DROP TR
12320 49 47 47 45 52 7d 7d 0a 0a 52 65 63 75 72 73 69  IGGER}}..Recursi
12330 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
12340 64 72 6f 70 2d 74 72 69 67 67 65 72 2d 73 74 6d  drop-trigger-stm
12350 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68  t.</tcl>..<p>^Th
12360 65 20 44 52 4f 50 20 54 52 49 47 47 45 52 20 73  e DROP TRIGGER s
12370 74 61 74 65 6d 65 6e 74 20 72 65 6d 6f 76 65 73  tatement removes
12380 20 61 20 74 72 69 67 67 65 72 20 63 72 65 61 74   a trigger creat
12390 65 64 20 62 79 20 74 68 65 20 0a 5b 43 52 45 41  ed by the .[CREA
123a0 54 45 20 54 52 49 47 47 45 52 5d 20 73 74 61 74  TE TRIGGER] stat
123b0 65 6d 65 6e 74 2e 20 5e 4f 6e 63 65 20 72 65 6d  ement. ^Once rem
123c0 6f 76 65 64 2c 20 74 68 65 20 74 72 69 67 67 65  oved, the trigge
123d0 72 20 64 65 66 69 6e 69 74 69 6f 6e 20 69 73 20  r definition is 
123e0 6e 6f 0a 6c 6f 6e 67 65 72 20 70 72 65 73 65 6e  no.longer presen
123f0 74 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 5f  t in the sqlite_
12400 6d 61 73 74 65 72 20 28 6f 72 20 73 71 6c 69 74  master (or sqlit
12410 65 5f 74 65 6d 70 5f 6d 61 73 74 65 72 29 20 74  e_temp_master) t
12420 61 62 6c 65 20 61 6e 64 20 69 73 0a 6e 6f 74 20  able and is.not 
12430 66 69 72 65 64 20 62 79 20 61 6e 79 20 73 75 62  fired by any sub
12440 73 65 71 75 65 6e 74 20 49 4e 53 45 52 54 2c 20  sequent INSERT, 
12450 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
12460 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 0a 3c 70   statements...<p
12470 3e 5e 4e 6f 74 65 20 74 68 61 74 20 74 72 69 67  >^Note that trig
12480 67 65 72 73 20 61 72 65 20 61 75 74 6f 6d 61 74  gers are automat
12490 69 63 61 6c 6c 79 20 64 72 6f 70 70 65 64 20 77  ically dropped w
124a0 68 65 6e 20 74 68 65 20 61 73 73 6f 63 69 61 74  hen the associat
124b0 65 64 20 74 61 62 6c 65 20 69 73 0a 64 72 6f 70  ed table is.drop
124c0 70 65 64 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  ped...<tcl>.####
124d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
124e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
124f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12500 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12510 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
12520 6f 6e 20 7b 44 52 4f 50 20 56 49 45 57 7d 20 64  on {DROP VIEW} d
12530 72 6f 70 76 69 65 77 20 7b 7b 44 52 4f 50 20 56  ropview {{DROP V
12540 49 45 57 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65  IEW}}..Recursive
12550 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 64 72  BubbleDiagram dr
12560 6f 70 2d 76 69 65 77 2d 73 74 6d 74 0a 3c 2f 74  op-view-stmt.</t
12570 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 44 52 4f  cl>..<p>^The DRO
12580 50 20 56 49 45 57 20 73 74 61 74 65 6d 65 6e 74  P VIEW statement
12590 20 72 65 6d 6f 76 65 73 20 61 20 76 69 65 77 20   removes a view 
125a0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 20 5b  created by the [
125b0 43 52 45 41 54 45 20 56 49 45 57 5d 20 0a 20 20  CREATE VIEW] .  
125c0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
125d0 76 69 65 77 20 64 65 66 69 6e 69 74 69 6f 6e 20  view definition 
125e0 69 73 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20  is removed from 
125f0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
12600 65 6d 61 2c 20 62 75 74 20 0a 20 20 6e 6f 20 61  ema, but .  no a
12610 63 74 75 61 6c 20 64 61 74 61 20 69 6e 20 74 68  ctual data in th
12620 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 62 61 73  e underlying bas
12630 65 20 74 61 62 6c 65 73 20 69 73 20 6d 6f 64 69  e tables is modi
12640 66 69 65 64 2e 0a 0a 3c 70 3e 5e 28 54 68 65 20  fied...<p>^(The 
12650 76 69 65 77 20 74 6f 20 64 72 6f 70 20 69 73 20  view to drop is 
12660 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
12670 65 20 76 69 65 77 2d 6e 61 6d 65 20 61 6e 64 20  e view-name and 
12680 6f 70 74 69 6f 6e 61 6c 20 0a 20 20 73 63 68 65  optional .  sche
12690 6d 61 2d 6e 61 6d 65 20 73 70 65 63 69 66 69 65  ma-name specifie
126a0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
126b0 20 44 52 4f 50 20 56 49 45 57 20 73 74 61 74 65   DROP VIEW state
126c0 6d 65 6e 74 2e 20 54 68 69 73 20 0a 20 20 72 65  ment. This .  re
126d0 66 65 72 65 6e 63 65 20 69 73 20 72 65 73 6f 6c  ference is resol
126e0 76 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 74  ved using the st
126f0 61 6e 64 61 72 64 20 70 72 6f 63 65 64 75 72 65  andard procedure
12700 20 66 6f 72 20 5b 6f 62 6a 65 63 74 20 72 65 73   for [object res
12710 6f 6c 75 74 69 6f 6e 5d 2e 29 5e 0a 0a 3c 70 3e  olution].)^..<p>
12720 0a 20 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  .  ^If the speci
12730 66 69 65 64 20 76 69 65 77 20 63 61 6e 6e 6f 74  fied view cannot
12740 20 62 65 20 66 6f 75 6e 64 20 61 6e 64 20 74 68   be found and th
12750 65 20 49 46 20 45 58 49 53 54 53 20 63 6c 61 75  e IF EXISTS clau
12760 73 65 20 69 73 20 6e 6f 74 20 0a 20 20 70 72 65  se is not .  pre
12770 73 65 6e 74 2c 20 69 74 20 69 73 20 61 6e 20 65  sent, it is an e
12780 72 72 6f 72 2e 20 5e 49 66 20 74 68 65 20 73 70  rror. ^If the sp
12790 65 63 69 66 69 65 64 20 76 69 65 77 20 63 61 6e  ecified view can
127a0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 20 61 6e 64  not be found and
127b0 20 61 6e 20 49 46 0a 20 20 45 58 49 53 54 53 20   an IF.  EXISTS 
127c0 63 6c 61 75 73 65 20 69 73 20 70 72 65 73 65 6e  clause is presen
127d0 74 20 69 6e 20 74 68 65 20 44 52 4f 50 20 56 49  t in the DROP VI
127e0 45 57 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68  EW statement, th
127f0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
12800 0a 20 20 69 73 20 61 20 6e 6f 2d 6f 70 2e 0a 0a  .  is a no-op...
12810 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23  .<tcl>.#########
12820 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12830 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12840 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12850 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12860 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44  #####.Section {D
12870 61 74 61 62 61 73 65 20 4f 62 6a 65 63 74 20 4e  atabase Object N
12880 61 6d 65 20 52 65 73 6f 6c 75 74 69 6f 6e 7d 20  ame Resolution} 
12890 7b 6e 61 6d 69 6e 67 7d 20 7b 7b 6f 62 6a 65 63  {naming} {{objec
128a0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 7d 7d 0a 3c  t resolution}}.<
128b0 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 20 20 49 6e 20  /tcl>..<p>.  In 
128c0 53 51 4c 69 74 65 2c 20 61 20 64 61 74 61 62 61  SQLite, a databa
128d0 73 65 20 6f 62 6a 65 63 74 20 28 61 20 74 61 62  se object (a tab
128e0 6c 65 2c 20 69 6e 64 65 78 2c 20 74 72 69 67 67  le, index, trigg
128f0 65 72 20 6f 72 20 76 69 65 77 29 20 69 73 20 69  er or view) is i
12900 64 65 6e 74 69 66 69 65 64 0a 20 20 62 79 20 74  dentified.  by t
12910 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
12920 62 6a 65 63 74 20 61 6e 64 20 74 68 65 20 6e 61  bject and the na
12930 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
12940 73 65 20 74 68 61 74 20 69 74 20 72 65 73 69 64  se that it resid
12950 65 73 20 69 6e 2e 20 0a 20 20 44 61 74 61 62 61  es in. .  Databa
12960 73 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 72  se objects may r
12970 65 73 69 64 65 20 69 6e 20 74 68 65 20 6d 61 69  eside in the mai
12980 6e 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 20  n database, the 
12990 74 65 6d 70 20 64 61 74 61 62 61 73 65 2c 20 6f  temp database, o
129a0 72 20 69 6e 0a 20 20 61 6e 20 5b 41 54 54 41 43  r in.  an [ATTAC
129b0 48 7c 61 74 74 61 63 68 65 64 20 64 61 74 61 62  H|attached datab
129c0 61 73 65 5d 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65  ase]...<p>.  The
129d0 20 73 79 6e 74 61 78 20 6f 66 20 74 68 65 20 5b   syntax of the [
129e0 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 5b 44 52  DROP TABLE], [DR
129f0 4f 50 20 49 4e 44 45 58 5d 2c 20 5b 44 52 4f 50  OP INDEX], [DROP
12a00 20 56 49 45 57 5d 2c 20 5b 44 52 4f 50 20 54 52   VIEW], [DROP TR
12a10 49 47 47 45 52 5d 2c 0a 20 20 5b 52 45 49 4e 44  IGGER],.  [REIND
12a20 45 58 5d 2c 20 5b 41 4c 54 45 52 20 54 41 42 4c  EX], [ALTER TABL
12a30 45 5d 20 61 6e 64 20 6d 61 6e 79 20 6f 74 68 65  E] and many othe
12a40 72 20 63 6f 6d 6d 61 6e 64 73 20 61 6c 6c 20 70  r commands all p
12a50 65 72 6d 69 74 20 74 68 65 20 75 73 65 72 20 74  ermit the user t
12a60 6f 0a 20 20 73 70 65 63 69 66 79 20 61 20 64 61  o.  specify a da
12a70 74 61 62 61 73 65 20 6f 62 6a 65 63 74 20 65 69  tabase object ei
12a80 74 68 65 72 20 62 79 20 69 74 73 20 6e 61 6d 65  ther by its name
12a90 20 61 6c 6f 6e 65 2c 20 6f 72 20 62 79 20 61 20   alone, or by a 
12aa0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 20  combination of. 
12ab0 20 69 74 73 20 6e 61 6d 65 20 61 6e 64 20 74 68   its name and th
12ac0 65 20 6e 61 6d 65 20 6f 66 20 69 74 73 20 64 61  e name of its da
12ad0 74 61 62 61 73 65 2e 20 5e 28 49 66 20 6e 6f 20  tabase. ^(If no 
12ae0 64 61 74 61 62 61 73 65 20 69 73 20 73 70 65 63  database is spec
12af0 69 66 69 65 64 20 61 73 20 70 61 72 74 0a 20 20  ified as part.  
12b00 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 72 65  of the object re
12b10 66 65 72 65 6e 63 65 2c 20 74 68 65 6e 20 53 51  ference, then SQ
12b20 4c 69 74 65 20 73 65 61 72 63 68 65 73 20 74 68  Lite searches th
12b30 65 20 6d 61 69 6e 2c 20 74 65 6d 70 20 61 6e 64  e main, temp and
12b40 20 61 6c 6c 20 61 74 74 61 63 68 65 64 0a 20 20   all attached.  
12b50 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 61 6e  databases for an
12b60 20 6f 62 6a 65 63 74 20 77 69 74 68 20 61 20 6d   object with a m
12b70 61 74 63 68 69 6e 67 20 6e 61 6d 65 2e 20 54 68  atching name. Th
12b80 65 20 74 65 6d 70 20 64 61 74 61 62 61 73 65 20  e temp database 
12b90 69 73 20 73 65 61 72 63 68 65 64 0a 20 20 66 69  is searched.  fi
12ba0 72 73 74 2c 20 66 6f 6c 6c 6f 77 65 64 20 62 79  rst, followed by
12bb0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
12bc0 73 65 2c 20 66 6f 6c 6c 6f 77 65 64 20 61 6c 6c  se, followed all
12bd0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
12be0 73 65 73 20 69 6e 20 74 68 65 0a 20 20 6f 72 64  ses in the.  ord
12bf0 65 72 20 74 68 61 74 20 74 68 65 79 20 77 65 72  er that they wer
12c00 65 20 61 74 74 61 63 68 65 64 2e 20 54 68 65 20  e attached. The 
12c10 72 65 66 65 72 65 6e 63 65 20 72 65 73 6f 6c 76  reference resolv
12c20 65 73 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  es to the first 
12c30 6d 61 74 63 68 0a 20 20 66 6f 75 6e 64 2e 29 5e  match.  found.)^
12c40 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c   For example:..<
12c50 70 72 65 3e 5e 28 0a 20 20 20 20 20 20 2f 2a 20  pre>^(.      /* 
12c60 41 64 64 20 61 20 74 61 62 6c 65 20 6e 61 6d 65  Add a table name
12c70 64 20 27 74 31 27 20 74 6f 20 74 68 65 20 74 65  d 't1' to the te
12c80 6d 70 2c 20 6d 61 69 6e 20 61 6e 64 20 61 6e 20  mp, main and an 
12c90 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
12ca0 65 20 2a 2f 0a 20 20 20 20 20 20 41 54 54 41 43  e */.      ATTAC
12cb0 48 20 27 66 69 6c 65 2e 64 62 27 20 41 53 20 61  H 'file.db' AS a
12cc0 75 78 3b 0a 20 20 20 20 20 20 43 52 45 41 54 45  ux;.      CREATE
12cd0 20 54 41 42 4c 45 20 74 31 28 78 2c 20 79 29 3b   TABLE t1(x, y);
12ce0 0a 20 20 20 20 20 20 43 52 45 41 54 45 20 54 45  .      CREATE TE
12cf0 4d 50 20 54 41 42 4c 45 20 74 31 28 78 2c 20 79  MP TABLE t1(x, y
12d00 29 3b 0a 20 20 20 20 20 20 43 52 45 41 54 45 20  );.      CREATE 
12d10 54 41 42 4c 45 20 61 75 78 2e 74 31 28 78 2c 20  TABLE aux.t1(x, 
12d20 79 29 3b 0a 0a 20 20 20 20 20 20 44 52 4f 50 20  y);..      DROP 
12d30 54 41 42 4c 45 20 74 31 3b 20 20 20 20 20 20 20  TABLE t1;       
12d40 20 20 2f 2a 20 44 72 6f 70 20 74 61 62 6c 65 20    /* Drop table 
12d50 69 6e 20 74 65 6d 70 20 64 61 74 61 62 61 73 65  in temp database
12d60 20 2a 2f 0a 20 20 20 20 20 20 44 52 4f 50 20 54   */.      DROP T
12d70 41 42 4c 45 20 74 31 3b 20 20 20 20 20 20 20 20  ABLE t1;        
12d80 20 2f 2a 20 44 72 6f 70 20 74 61 62 6c 65 20 69   /* Drop table i
12d90 6e 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  n main database 
12da0 2a 2f 0a 20 20 20 20 20 20 44 52 4f 50 20 54 41  */.      DROP TA
12db0 42 4c 45 20 74 31 3b 20 20 20 20 20 20 20 20 20  BLE t1;         
12dc0 2f 2a 20 44 72 6f 70 20 74 61 62 6c 65 20 69 6e  /* Drop table in
12dd0 20 61 75 78 20 64 61 74 61 62 61 73 65 20 2a 2f   aux database */
12de0 0a 29 5e 3c 2f 70 72 65 3e 0a 0a 3c 70 3e 0a 20  .)^</pre>..<p>. 
12df0 20 5e 49 66 20 61 20 73 63 68 65 6d 61 20 6e 61   ^If a schema na
12e00 6d 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  me is specified 
12e10 61 73 20 70 61 72 74 20 6f 66 20 61 6e 20 6f 62  as part of an ob
12e20 6a 65 63 74 20 72 65 66 65 72 65 6e 63 65 2c 20  ject reference, 
12e30 69 74 20 6d 75 73 74 20 62 65 0a 20 20 65 69 74  it must be.  eit
12e40 68 65 72 20 22 6d 61 69 6e 22 2c 20 6f 72 20 22  her "main", or "
12e50 74 65 6d 70 22 20 6f 72 20 74 68 65 20 73 63 68  temp" or the sch
12e60 65 6d 61 2d 6e 61 6d 65 20 6f 66 20 61 6e 20 61  ema-name of an a
12e70 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
12e80 2e 0a 20 20 5e 4c 69 6b 65 20 6f 74 68 65 72 20  ..  ^Like other 
12e90 53 51 4c 20 69 64 65 6e 74 69 66 69 65 72 73 2c  SQL identifiers,
12ea0 20 73 63 68 65 6d 61 20 6e 61 6d 65 73 20 61 72   schema names ar
12eb0 65 20 63 61 73 65 2d 69 6e 73 65 6e 73 69 74 69  e case-insensiti
12ec0 76 65 2e 0a 20 20 5e 49 66 20 61 20 73 63 68 65  ve..  ^If a sche
12ed0 6d 61 20 6e 61 6d 65 20 69 73 20 73 70 65 63 69  ma name is speci
12ee0 66 69 65 64 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  fied, then only 
12ef0 74 68 61 74 20 6f 6e 65 20 73 63 68 65 6d 61 20  that one schema 
12f00 69 73 20 73 65 61 72 63 68 65 64 20 66 6f 72 0a  is searched for.
12f10 20 20 74 68 65 20 6e 61 6d 65 64 20 6f 62 6a 65    the named obje
12f20 63 74 2e 0a 0a 3c 70 3e 0a 20 20 4d 6f 73 74 20  ct...<p>.  Most 
12f30 6f 62 6a 65 63 74 20 72 65 66 65 72 65 6e 63 65  object reference
12f40 73 20 6d 61 79 20 6f 6e 6c 79 20 72 65 73 6f 6c  s may only resol
12f50 76 65 20 74 6f 20 61 20 73 70 65 63 69 66 69 63  ve to a specific
12f60 20 74 79 70 65 20 6f 66 20 6f 62 6a 65 63 74 20   type of object 
12f70 28 66 6f 72 0a 20 20 65 78 61 6d 70 6c 65 20 61  (for.  example a
12f80 20 72 65 66 65 72 65 6e 63 65 20 74 68 61 74 20   reference that 
12f90 69 73 20 70 61 72 74 20 6f 66 20 61 20 44 52 4f  is part of a DRO
12fa0 50 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  P TABLE statemen
12fb0 74 20 6d 61 79 20 6f 6e 6c 79 20 72 65 73 6f 6c  t may only resol
12fc0 76 65 0a 20 20 74 6f 20 61 20 74 61 62 6c 65 20  ve.  to a table 
12fd0 6f 62 6a 65 63 74 2c 20 6e 6f 74 20 61 6e 20 69  object, not an i
12fe0 6e 64 65 78 2c 20 74 72 69 67 67 65 72 20 6f 72  ndex, trigger or
12ff0 20 76 69 65 77 29 2e 20 48 6f 77 65 76 65 72 20   view). However 
13000 69 6e 20 73 6f 6d 65 20 63 6f 6e 74 65 78 74 73  in some contexts
13010 20 0a 20 20 28 65 2e 67 2e 20 5b 52 45 49 4e 44   .  (e.g. [REIND
13020 45 58 5d 29 20 61 6e 20 6f 62 6a 65 63 74 20 72  EX]) an object r
13030 65 66 65 72 65 6e 63 65 20 6d 61 79 20 62 65 20  eference may be 
13040 72 65 73 6f 6c 76 65 20 74 6f 20 6d 6f 72 65 20  resolve to more 
13050 74 68 61 6e 20 6f 6e 65 20 74 79 70 65 0a 20 20  than one type.  
13060 6f 66 20 6f 62 6a 65 63 74 2e 20 5e 57 68 65 6e  of object. ^When
13070 20 73 65 61 72 63 68 69 6e 67 20 64 61 74 61 62   searching datab
13080 61 73 65 20 73 63 68 65 6d 61 73 20 66 6f 72 20  ase schemas for 
13090 61 20 6e 61 6d 65 64 20 6f 62 6a 65 63 74 2c 20  a named object, 
130a0 6f 62 6a 65 63 74 73 20 6f 66 0a 20 20 74 79 70  objects of.  typ
130b0 65 73 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  es that cannot b
130c0 65 20 75 73 65 64 20 69 6e 20 74 68 65 20 63 6f  e used in the co
130d0 6e 74 65 78 74 20 6f 66 20 74 68 65 20 72 65 66  ntext of the ref
130e0 65 72 65 6e 63 65 20 61 72 65 20 61 6c 77 61 79  erence are alway
130f0 73 20 0a 20 20 69 67 6e 6f 72 65 64 2e 0a 0a 3c  s .  ignored...<
13100 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
13110 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13120 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13130 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13140 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13150 23 23 23 0a 53 65 63 74 69 6f 6e 20 45 58 50 4c  ###.Section EXPL
13160 41 49 4e 20 65 78 70 6c 61 69 6e 20 45 58 50 4c  AIN explain EXPL
13170 41 49 4e 0a 0a 42 75 62 62 6c 65 44 69 61 67 72  AIN..BubbleDiagr
13180 61 6d 20 73 71 6c 2d 73 74 6d 74 0a 3c 2f 74 63  am sql-stmt.</tc
13190 6c 3e 0a 0a 3c 70 3e 5e 41 6e 20 53 51 4c 20 73  l>..<p>^An SQL s
131a0 74 61 74 65 6d 65 6e 74 20 63 61 6e 20 62 65 20  tatement can be 
131b0 70 72 65 63 65 64 65 64 20 62 79 20 74 68 65 20  preceded by the 
131c0 6b 65 79 77 6f 72 64 20 22 45 58 50 4c 41 49 4e  keyword "EXPLAIN
131d0 22 20 6f 72 0a 62 79 20 74 68 65 20 70 68 72 61  " or.by the phra
131e0 73 65 20 22 45 58 50 4c 41 49 4e 20 51 55 45 52  se "EXPLAIN QUER
131f0 59 20 50 4c 41 4e 22 2e 20 20 5e 45 69 74 68 65  Y PLAN".  ^Eithe
13200 72 20 6d 6f 64 69 66 69 63 61 74 69 6f 6e 20 63  r modification c
13210 61 75 73 65 73 20 74 68 65 0a 53 51 4c 20 73 74  auses the.SQL st
13220 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 68 61 76  atement to behav
13230 65 20 61 73 20 61 20 71 75 65 72 79 20 61 6e 64  e as a query and
13240 20 74 6f 20 72 65 74 75 72 6e 20 69 6e 66 6f 72   to return infor
13250 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 68 6f 77  mation about.how
13260 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
13270 6e 74 20 77 6f 75 6c 64 20 68 61 76 65 20 6f 70  nt would have op
13280 65 72 61 74 65 64 20 69 66 20 74 68 65 20 45 58  erated if the EX
13290 50 4c 41 49 4e 20 6b 65 79 77 6f 72 64 20 6f 72  PLAIN keyword or
132a0 0a 70 68 72 61 73 65 20 68 61 64 20 62 65 65 6e  .phrase had been
132b0 20 6f 6d 69 74 74 65 64 2e 3c 2f 70 3e 0a 0a 3c   omitted.</p>..<
132c0 70 3e 54 68 65 20 6f 75 74 70 75 74 20 66 72 6f  p>The output fro
132d0 6d 20 45 58 50 4c 41 49 4e 20 61 6e 64 20 45 58  m EXPLAIN and EX
132e0 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e  PLAIN QUERY PLAN
132f0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
13300 0a 69 6e 74 65 72 61 63 74 69 76 65 20 61 6e 61  .interactive ana
13310 6c 79 73 69 73 20 61 6e 64 20 74 72 6f 75 62 6c  lysis and troubl
13320 65 73 68 6f 6f 74 69 6e 67 20 6f 6e 6c 79 2e 20  eshooting only. 
13330 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
13340 74 68 65 20 0a 6f 75 74 70 75 74 20 66 6f 72 6d  the .output form
13350 61 74 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  at are subject t
13360 6f 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e  o change from on
13370 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
13380 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
13390 0a 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68  .Applications sh
133a0 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 45 58 50  ould not use EXP
133b0 4c 41 49 4e 20 6f 72 20 45 58 50 4c 41 49 4e 20  LAIN or EXPLAIN 
133c0 51 55 45 52 59 20 50 4c 41 4e 20 73 69 6e 63 65  QUERY PLAN since
133d0 0a 74 68 65 69 72 20 65 78 61 63 74 20 62 65 68  .their exact beh
133e0 61 76 69 6f 72 20 69 73 20 76 61 72 69 61 62 6c  avior is variabl
133f0 65 20 61 6e 64 20 6f 6e 6c 79 20 70 61 72 74 69  e and only parti
13400 61 6c 6c 79 20 64 6f 63 75 6d 65 6e 74 65 64 2e  ally documented.
13410 3c 2f 70 3e 0a 0a 3c 70 3e 5e 57 68 65 6e 20 74  </p>..<p>^When t
13420 68 65 20 45 58 50 4c 41 49 4e 20 6b 65 79 77 6f  he EXPLAIN keywo
13430 72 64 20 61 70 70 65 61 72 73 20 62 79 20 69 74  rd appears by it
13440 73 65 6c 66 20 69 74 20 63 61 75 73 65 73 20 74  self it causes t
13450 68 65 20 73 74 61 74 65 6d 65 6e 74 0a 74 6f 20  he statement.to 
13460 62 65 68 61 76 65 20 61 73 20 61 20 71 75 65 72  behave as a quer
13470 79 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 74  y that returns t
13480 68 65 20 73 65 71 75 65 6e 63 65 20 6f 66 20 0a  he sequence of .
13490 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
134a0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 69   instructions] i
134b0 74 20 77 6f 75 6c 64 20 68 61 76 65 20 75 73 65  t would have use
134c0 64 20 74 6f 20 65 78 65 63 75 74 65 20 74 68 65  d to execute the
134d0 20 63 6f 6d 6d 61 6e 64 20 68 61 64 0a 74 68 65   command had.the
134e0 20 45 58 50 4c 41 49 4e 20 6b 65 79 77 6f 72 64   EXPLAIN keyword
134f0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 73 65 6e   not been presen
13500 74 2e 20 5e 57 68 65 6e 20 74 68 65 20 45 58 50  t. ^When the EXP
13510 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20  LAIN QUERY PLAN 
13520 70 68 72 61 73 65 0a 61 70 70 65 61 72 73 2c 20  phrase.appears, 
13530 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 72 65  the statement re
13540 74 75 72 6e 73 20 68 69 67 68 2d 6c 65 76 65 6c  turns high-level
13550 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 72 65 67   information reg
13560 61 72 64 69 6e 67 20 74 68 65 20 71 75 65 72 79  arding the query
13570 0a 70 6c 61 6e 20 74 68 61 74 20 77 6f 75 6c 64  .plan that would
13580 20 68 61 76 65 20 62 65 65 6e 20 75 73 65 64 2e   have been used.
13590 0a 0a 54 68 65 20 45 58 50 4c 41 49 4e 20 51 55  ..The EXPLAIN QU
135a0 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64  ERY PLAN command
135b0 20 69 73 20 64 65 73 63 72 69 62 65 64 20 69 6e   is described in
135c0 20 0a 5b 65 78 70 6c 61 69 6e 20 71 75 65 72 79   .[explain query
135d0 20 70 6c 61 6e 7c 6d 6f 72 65 20 64 65 74 61 69   plan|more detai
135e0 6c 20 68 65 72 65 5d 2e 0a 0a 3c 74 63 6c 3e 0a  l here]...<tcl>.
135f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13600 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13610 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13620 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13630 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
13640 65 63 74 69 6f 6e 20 65 78 70 72 65 73 73 69 6f  ection expressio
13650 6e 20 65 78 70 72 20 7b 2a 65 78 70 72 65 73 73  n expr {*express
13660 69 6f 6e 20 7b 65 78 70 72 65 73 73 69 6f 6e 20  ion {expression 
13670 73 79 6e 74 61 78 7d 7d 0a 0a 52 65 63 75 72 73  syntax}}..Recurs
13680 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d  iveBubbleDiagram
13690 20 65 78 70 72 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70   expr.</tcl>..<p
136a0 3e 54 68 69 73 20 73 65 63 74 69 6f 6e 20 69 73  >This section is
136b0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
136c0 74 68 65 20 6f 74 68 65 72 73 2e 20 20 4d 6f 73  the others.  Mos
136d0 74 20 6f 74 68 65 72 20 73 65 63 74 69 6f 6e 73  t other sections
136e0 20 6f 66 0a 74 68 69 73 20 64 6f 63 75 6d 65 6e   of.this documen
136f0 74 20 74 61 6c 6b 73 20 61 62 6f 75 74 20 61 20  t talks about a 
13700 70 61 72 74 69 63 75 6c 61 72 20 53 51 4c 20 63  particular SQL c
13710 6f 6d 6d 61 6e 64 2e 20 20 54 68 69 73 20 73 65  ommand.  This se
13720 63 74 69 6f 6e 20 64 6f 65 73 0a 6e 6f 74 20 74  ction does.not t
13730 61 6c 6b 20 61 62 6f 75 74 20 61 20 73 74 61 6e  alk about a stan
13740 64 61 6c 6f 6e 65 20 63 6f 6d 6d 61 6e 64 20 62  dalone command b
13750 75 74 20 61 62 6f 75 74 20 22 65 78 70 72 65 73  ut about "expres
13760 73 69 6f 6e 73 22 20 77 68 69 63 68 20 61 72 65  sions" which are
13770 20 0a 73 75 62 63 6f 6d 70 6f 6e 65 6e 74 73 20   .subcomponents 
13780 6f 66 20 6d 6f 73 74 20 6f 74 68 65 72 20 63 6f  of most other co
13790 6d 6d 61 6e 64 73 2e 3c 2f 70 3e 0a 0a 3c 74 63  mmands.</p>..<tc
137a0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 62 69  l>hd_fragment bi
137b0 6e 61 72 79 6f 70 73 20 7b 62 69 6e 61 72 79 20  naryops {binary 
137c0 6f 70 65 72 61 74 6f 72 73 7d 3c 2f 74 63 6c 3e  operators}</tcl>
137d0 0a 3c 68 33 3e 4f 70 65 72 61 74 6f 72 73 3c 2f  .<h3>Operators</
137e0 68 33 3e 0a 3c 70 3e 5e 28 53 51 4c 69 74 65 20  h3>.<p>^(SQLite 
137f0 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
13800 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 6e 61 72 79  following binary
13810 20 6f 70 65 72 61 74 6f 72 73 2c 20 69 6e 20 6f   operators, in o
13820 72 64 65 72 20 66 72 6f 6d 0a 68 69 67 68 65 73  rder from.highes
13830 74 20 74 6f 20 6c 6f 77 65 73 74 20 70 72 65 63  t to lowest prec
13840 65 64 65 6e 63 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c  edence:</p>..<bl
13850 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 3c  ockquote><pre>.<
13860 66 6f 6e 74 20 63 6f 6c 6f 72 3d 22 23 32 63 32  font color="#2c2
13870 63 66 30 22 3e 3c 62 69 67 3e 7c 7c 0a 2a 20 20  cf0"><big>||.*  
13880 20 20 2f 20 20 20 20 25 0a 2b 20 20 20 20 2d 0a    /    %.+    -.
13890 26 6c 74 3b 26 6c 74 3b 20 20 20 26 67 74 3b 26  &lt;&lt;   &gt;&
138a0 67 74 3b 20 20 20 26 61 6d 70 3b 20 20 20 20 7c  gt;   &amp;    |
138b0 0a 26 6c 74 3b 20 20 20 20 26 6c 74 3b 3d 20 20  .&lt;    &lt;=  
138c0 20 26 67 74 3b 20 20 20 20 26 67 74 3b 3d 0a 3d   &gt;    &gt;=.=
138d0 20 20 20 20 3d 3d 20 20 20 21 3d 20 20 20 26 6c      ==   !=   &l
138e0 74 3b 26 67 74 3b 20 20 20 3c 2f 62 69 67 3e 49  t;&gt;   </big>I
138f0 53 20 20 20 49 53 20 4e 4f 54 20 20 20 49 4e 20  S   IS NOT   IN 
13900 20 20 4c 49 4b 45 20 20 20 47 4c 4f 42 20 20 20    LIKE   GLOB   
13910 4d 41 54 43 48 20 20 20 52 45 47 45 58 50 0a 41  MATCH   REGEXP.A
13920 4e 44 20 20 20 0a 4f 52 3c 2f 66 6f 6e 74 3e 0a  ND   .OR</font>.
13930 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13940 74 65 3e 29 5e 0a 0a 3c 70 3e 5e 28 53 75 70 70  te>)^..<p>^(Supp
13950 6f 72 74 65 64 20 75 6e 61 72 79 20 70 72 65 66  orted unary pref
13960 69 78 20 6f 70 65 72 61 74 6f 72 73 20 61 72 65  ix operators are
13970 20 74 68 65 73 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c   these:</p>..<bl
13980 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 3c  ockquote><pre>.<
13990 66 6f 6e 74 20 63 6f 6c 6f 72 3d 22 23 32 63 32  font color="#2c2
139a0 63 66 30 22 3e 3c 62 69 67 3e 2d 20 20 20 20 2b  cf0"><big>-    +
139b0 20 20 20 20 7e 20 20 20 20 4e 4f 54 3c 2f 62 69      ~    NOT</bi
139c0 67 3e 3c 2f 66 6f 6e 74 3e 0a 3c 2f 70 72 65 3e  g></font>.</pre>
139d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
139e0 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
139f0 74 20 63 6f 6c 6c 61 74 65 6f 70 20 7b 43 4f 4c  t collateop {COL
13a00 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 7d 3c 2f  LATE operator}</
13a10 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 43 4f 4c  tcl>.<p>^The COL
13a20 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 20 69 73  LATE operator is
13a30 20 61 20 75 6e 61 72 79 20 70 6f 73 74 66 69 78   a unary postfix
13a40 0a 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 61  .operator that a
13a50 73 73 69 67 6e 73 20 61 20 5b 63 6f 6c 6c 61 74  ssigns a [collat
13a60 69 6e 67 20 73 65 71 75 65 6e 63 65 5d 20 74 6f  ing sequence] to
13a70 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a   an expression..
13a80 5e 54 68 65 20 43 4f 4c 4c 41 54 45 20 6f 70 65  ^The COLLATE ope
13a90 72 61 74 6f 72 20 68 61 73 20 61 20 68 69 67 68  rator has a high
13aa0 65 72 20 70 72 65 63 65 64 65 6e 63 65 20 28 62  er precedence (b
13ab0 69 6e 64 73 20 6d 6f 72 65 20 74 69 67 68 74 6c  inds more tightl
13ac0 79 29 20 74 68 61 6e 20 61 6e 79 0a 62 69 6e 61  y) than any.bina
13ad0 72 79 20 6f 70 65 72 61 74 6f 72 20 61 6e 64 20  ry operator and 
13ae0 61 6e 79 20 75 6e 61 72 79 20 70 72 65 66 69 78  any unary prefix
13af0 20 6f 70 65 72 61 74 6f 72 20 65 78 63 65 70 74   operator except
13b00 20 22 7e 22 2e 0a 28 43 4f 4c 4c 41 54 45 20 61   "~"..(COLLATE a
13b10 6e 64 20 22 7e 22 20 61 72 65 20 61 73 73 6f 63  nd "~" are assoc
13b20 69 61 74 69 76 65 20 73 6f 20 74 68 65 69 72 20  iative so their 
13b30 62 69 6e 64 69 6e 67 20 6f 72 64 65 72 20 64 6f  binding order do
13b40 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 2e 29 0a  es not matter.).
13b50 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73  ^The collating s
13b60 65 71 75 65 6e 63 65 20 73 65 74 20 62 79 20 74  equence set by t
13b70 68 65 20 43 4f 4c 4c 41 54 45 20 6f 70 65 72 61  he COLLATE opera
13b80 74 6f 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  tor overrides th
13b90 65 0a 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  e.collating sequ
13ba0 65 6e 63 65 20 64 65 74 65 72 6d 69 6e 65 64 20  ence determined 
13bb0 62 79 20 74 68 65 20 43 4f 4c 4c 41 54 45 20 63  by the COLLATE c
13bc0 6c 61 75 73 65 20 69 6e 20 61 20 74 61 62 6c 65  lause in a table
13bd0 0a 5b 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74  .[column definit
13be0 69 6f 6e 5d 2e 0a 53 65 65 20 74 68 65 20 5b 63  ion]..See the [c
13bf0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
13c00 65 7c 20 64 65 74 61 69 6c 65 64 20 64 69 73 63  e| detailed disc
13c10 75 73 73 69 6f 6e 20 6f 6e 20 63 6f 6c 6c 61 74  ussion on collat
13c20 69 6e 67 20 73 65 71 75 65 6e 63 65 73 5d 0a 69  ing sequences].i
13c30 6e 20 74 68 65 20 5b 64 61 74 61 74 79 70 65 20  n the [datatype 
13c40 7c 20 44 61 74 61 74 79 70 65 20 49 6e 20 53 51  | Datatype In SQ
13c50 4c 69 74 65 33 5d 20 64 6f 63 75 6d 65 6e 74 20  Lite3] document 
13c60 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
13c70 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 3c 2f 70 3e  nformation..</p>
13c80 0a 0a 3c 74 63 6c 3e 68 64 5f 70 75 74 73 20 22  ..<tcl>hd_puts "
13c90 0a 3c 70 3e 5e 54 68 65 20 75 6e 61 72 79 20 6f  .<p>^The unary o
13ca0 70 65 72 61 74 6f 72 20 5b 4f 70 65 72 61 74 6f  perator [Operato
13cb0 72 20 2b 5d 20 69 73 20 61 20 6e 6f 2d 6f 70 2e  r +] is a no-op.
13cc0 20 20 5e 49 74 20 63 61 6e 20 62 65 20 61 70 70    ^It can be app
13cd0 6c 69 65 64 0a 74 6f 20 73 74 72 69 6e 67 73 2c  lied.to strings,
13ce0 20 6e 75 6d 62 65 72 73 2c 20 62 6c 6f 62 73 20   numbers, blobs 
13cf0 6f 72 20 4e 55 4c 4c 20 61 6e 64 20 69 74 20 61  or NULL and it a
13d00 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
13d10 72 65 73 75 6c 74 0a 77 69 74 68 20 74 68 65 20  result.with the 
13d20 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68  same value as th
13d30 65 20 6f 70 65 72 61 6e 64 2e 3c 2f 70 3e 22 3c  e operand.</p>"<
13d40 2f 74 63 6c 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74  /tcl>..<p>Note t
13d50 68 61 74 20 74 68 65 72 65 20 61 72 65 20 74 77  hat there are tw
13d60 6f 20 76 61 72 69 61 74 69 6f 6e 73 20 6f 66 20  o variations of 
13d70 74 68 65 20 65 71 75 61 6c 73 20 61 6e 64 20 6e  the equals and n
13d80 6f 74 20 65 71 75 61 6c 73 0a 6f 70 65 72 61 74  ot equals.operat
13d90 6f 72 73 2e 20 20 5e 45 71 75 61 6c 73 20 63 61  ors.  ^Equals ca
13da0 6e 20 62 65 20 65 69 74 68 65 72 0a 0a 3c 74 63  n be either..<tc
13db0 6c 3e 0a 68 64 5f 70 75 74 73 20 22 5b 4f 70 65  l>.hd_puts "[Ope
13dc0 72 61 74 6f 72 20 3d 5d 20 6f 72 20 5b 4f 70 65  rator =] or [Ope
13dd0 72 61 74 6f 72 20 3d 3d 5d 2e 0a 5e 54 68 65 20  rator ==]..^The 
13de0 6e 6f 6e 2d 65 71 75 61 6c 73 20 6f 70 65 72 61  non-equals opera
13df0 74 6f 72 20 63 61 6e 20 62 65 20 65 69 74 68 65  tor can be eithe
13e00 72 0a 5b 4f 70 65 72 61 74 6f 72 20 21 3d 5d 20  r.[Operator !=] 
13e10 6f 72 20 5b 4f 70 65 72 61 74 6f 72 20 7b 26 6c  or [Operator {&l
13e20 74 3b 26 67 74 3b 7d 5d 2e 0a 5e 54 68 65 20 5b  t;&gt;}]..^The [
13e30 4f 70 65 72 61 74 6f 72 20 7c 7c 5d 20 6f 70 65  Operator ||] ope
13e40 72 61 74 6f 72 20 69 73 20 5c 22 63 6f 6e 63 61  rator is \"conca
13e50 74 65 6e 61 74 65 5c 22 20 2d 20 69 74 20 6a 6f  tenate\" - it jo
13e60 69 6e 73 20 74 6f 67 65 74 68 65 72 0a 74 68 65  ins together.the
13e70 20 74 77 6f 20 73 74 72 69 6e 67 73 20 6f 66 20   two strings of 
13e80 69 74 73 20 6f 70 65 72 61 6e 64 73 2e 0a 5e 54  its operands..^T
13e90 68 65 20 6f 70 65 72 61 74 6f 72 20 5b 4f 70 65  he operator [Ope
13ea0 72 61 74 6f 72 20 25 5d 20 6f 75 74 70 75 74 73  rator %] outputs
13eb0 20 74 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   the integer val
13ec0 75 65 20 6f 66 20 69 74 73 20 6c 65 66 74 20 0a  ue of its left .
13ed0 6f 70 65 72 61 6e 64 20 6d 6f 64 75 6c 6f 20 69  operand modulo i
13ee0 74 73 20 72 69 67 68 74 20 6f 70 65 72 61 6e 64  ts right operand
13ef0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13f00 73 2c 20 74 68 65 0a 6f 70 65 72 61 74 6f 72 20  s, the.operator 
13f10 5b 4f 70 65 72 61 74 6f 72 20 25 5d 20 77 6f 72  [Operator %] wor
13f20 6b 73 20 69 6e 20 53 51 4c 69 74 65 20 74 68 65  ks in SQLite the
13f30 20 73 61 6d 65 20 61 73 20 69 74 20 64 6f 65 73   same as it does
13f40 0a 69 6e 20 41 4e 53 49 2d 43 2e 3c 2f 70 3e 0a  .in ANSI-C.</p>.
13f50 0a 3c 70 3e 5e 54 68 65 20 72 65 73 75 6c 74 20  .<p>^The result 
13f60 6f 66 20 61 6e 79 20 62 69 6e 61 72 79 20 6f 70  of any binary op
13f70 65 72 61 74 6f 72 20 69 73 20 65 69 74 68 65 72  erator is either
13f80 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
13f90 20 6f 72 20 0a 4e 55 4c 4c 2c 20 65 78 63 65 70   or .NULL, excep
13fa0 74 20 66 6f 72 20 74 68 65 20 5b 4f 70 65 72 61  t for the [Opera
13fb0 74 6f 72 20 7c 7c 5d 20 63 6f 6e 63 61 74 65 6e  tor ||] concaten
13fc0 61 74 69 6f 6e 20 6f 70 65 72 61 74 6f 72 20 77  ation operator w
13fd0 68 69 63 68 20 61 6c 77 61 79 73 20 0a 65 76 61  hich always .eva
13fe0 6c 75 61 74 65 73 20 74 6f 20 65 69 74 68 65 72  luates to either
13ff0 20 4e 55 4c 4c 20 6f 72 20 61 20 74 65 78 74 20   NULL or a text 
14000 76 61 6c 75 65 2e 3c 2f 70 3e 22 0a 0a 68 64 5f  value.</p>"..hd_
14010 66 72 61 67 6d 65 6e 74 20 7b 69 73 69 73 6e 6f  fragment {isisno
14020 74 7d 20 7b 49 53 20 6f 70 65 72 61 74 6f 72 7d  t} {IS operator}
14030 20 7b 49 53 20 4e 4f 54 20 6f 70 65 72 61 74 6f   {IS NOT operato
14040 72 7d 0a 0a 68 64 5f 70 75 74 73 20 22 3c 70 3e  r}..hd_puts "<p>
14050 5e 54 68 65 20 5b 4f 70 65 72 61 74 6f 72 20 49  ^The [Operator I
14060 53 5d 20 61 6e 64 20 5b 4f 70 65 72 61 74 6f 72  S] and [Operator
14070 20 7b 49 53 20 4e 4f 54 7d 5d 20 6f 70 65 72 61   {IS NOT}] opera
14080 74 6f 72 73 20 77 6f 72 6b 0a 6c 69 6b 65 20 5b  tors work.like [
14090 4f 70 65 72 61 74 6f 72 20 3d 5d 20 61 6e 64 20  Operator =] and 
140a0 5b 4f 70 65 72 61 74 6f 72 20 21 3d 5d 20 65 78  [Operator !=] ex
140b0 63 65 70 74 20 77 68 65 6e 20 6f 6e 65 20 6f 72  cept when one or
140c0 20 62 6f 74 68 20 6f 66 20 74 68 65 0a 6f 70 65   both of the.ope
140d0 72 61 6e 64 73 20 61 72 65 20 4e 55 4c 4c 2e 20  rands are NULL. 
140e0 5e 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 69  ^In this case, i
140f0 66 20 62 6f 74 68 20 6f 70 65 72 61 6e 64 73 20  f both operands 
14100 61 72 65 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  are NULL, then t
14110 68 65 0a 49 53 20 6f 70 65 72 61 74 6f 72 20 65  he.IS operator e
14120 76 61 6c 75 61 74 65 73 20 74 6f 20 31 20 28 74  valuates to 1 (t
14130 72 75 65 29 20 61 6e 64 20 74 68 65 20 49 53 20  rue) and the IS 
14140 4e 4f 54 20 6f 70 65 72 61 74 6f 72 20 65 76 61  NOT operator eva
14150 6c 75 61 74 65 73 0a 74 6f 20 30 20 28 66 61 6c  luates.to 0 (fal
14160 73 65 29 2e 20 5e 49 66 20 6f 6e 65 20 6f 70 65  se). ^If one ope
14170 72 61 6e 64 20 69 73 20 4e 55 4c 4c 20 61 6e 64  rand is NULL and
14180 20 74 68 65 20 6f 74 68 65 72 20 69 73 20 6e 6f   the other is no
14190 74 2c 20 74 68 65 6e 20 74 68 65 0a 49 53 20 6f  t, then the.IS o
141a0 70 65 72 61 74 6f 72 20 65 76 61 6c 75 61 74 65  perator evaluate
141b0 73 20 74 6f 20 30 20 28 66 61 6c 73 65 29 20 61  s to 0 (false) a
141c0 6e 64 20 74 68 65 20 49 53 20 4e 4f 54 20 6f 70  nd the IS NOT op
141d0 65 72 61 74 6f 72 20 69 73 20 31 20 28 74 72 75  erator is 1 (tru
141e0 65 29 2e 0a 5e 49 74 20 69 73 20 6e 6f 74 20 70  e)..^It is not p
141f0 6f 73 73 69 62 6c 65 20 66 6f 72 20 61 6e 20 49  ossible for an I
14200 53 20 6f 72 20 49 53 20 4e 4f 54 20 65 78 70 72  S or IS NOT expr
14210 65 73 73 69 6f 6e 20 74 6f 20 65 76 61 6c 75 61  ession to evalua
14220 74 65 20 74 6f 20 4e 55 4c 4c 2e 0a 5e 4f 70 65  te to NULL..^Ope
14230 72 61 74 6f 72 73 20 5b 4f 70 65 72 61 74 6f 72  rators [Operator
14240 20 49 53 5d 20 61 6e 64 20 5b 4f 70 65 72 61 74   IS] and [Operat
14250 6f 72 20 7b 49 53 20 4e 4f 54 7d 5d 20 68 61 76  or {IS NOT}] hav
14260 65 20 74 68 65 20 73 61 6d 65 20 0a 70 72 65 63  e the same .prec
14270 65 64 65 6e 63 65 20 61 73 20 5b 4f 70 65 72 61  edence as [Opera
14280 74 6f 72 20 3d 5d 2e 22 0a 0a 3c 74 63 6c 3e 68  tor =]."..<tcl>h
14290 64 5f 66 72 61 67 6d 65 6e 74 20 6c 69 74 76 61  d_fragment litva
142a0 6c 75 65 20 7b 6c 69 74 65 72 61 6c 20 76 61 6c  lue {literal val
142b0 75 65 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 4c 69  ue}</tcl>.<h3>Li
142c0 74 65 72 61 6c 20 56 61 6c 75 65 73 20 28 43 6f  teral Values (Co
142d0 6e 73 74 61 6e 74 73 29 3c 2f 68 33 3e 0a 3c 70  nstants)</h3>.<p
142e0 3e 0a 41 20 6c 69 74 65 72 61 6c 20 76 61 6c 75  >.A literal valu
142f0 65 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 63  e represents a c
14300 6f 6e 73 74 61 6e 74 2e 0a 5e 4c 69 74 65 72 61  onstant..^Litera
14310 6c 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  l values may be 
14320 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
14330 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 73  ng point numbers
14340 2c 20 73 74 72 69 6e 67 73 2c 0a 42 4c 4f 42 73  , strings,.BLOBs
14350 2c 20 6f 72 20 4e 55 4c 4c 73 2e 0a 3c 70 3e 0a  , or NULLs..<p>.
14360 54 68 65 20 73 79 6e 74 61 78 20 66 6f 72 20 69  The syntax for i
14370 6e 74 65 67 65 72 20 61 6e 64 20 66 6c 6f 61 74  nteger and float
14380 69 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72 61  ing point litera
14390 6c 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ls (collectively
143a0 0a 22 6e 75 6d 65 72 69 63 20 6c 69 74 65 72 61  ."numeric litera
143b0 6c 73 22 29 20 69 73 20 73 68 6f 77 6e 20 62 79  ls") is shown by
143c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   the following d
143d0 69 61 67 72 61 6d 3a 3c 2f 70 3e 0a 0a 3c 74 63  iagram:</p>..<tc
143e0 6c 3e 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  l>BubbleDiagram 
143f0 6e 75 6d 65 72 69 63 2d 6c 69 74 65 72 61 6c 3c  numeric-literal<
14400 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 5e 28 49 66 20  /tcl>..<p>.^(If 
14410 61 20 6e 75 6d 65 72 69 63 20 6c 69 74 65 72 61  a numeric litera
14420 6c 20 68 61 73 20 61 20 64 65 63 69 6d 61 6c 20  l has a decimal 
14430 70 6f 69 6e 74 20 6f 72 20 61 6e 20 65 78 70 6f  point or an expo
14440 6e 65 6e 74 69 61 74 69 6f 6e 0a 63 6c 61 75 73  nentiation.claus
14450 65 20 6f 72 20 69 66 20 69 74 73 20 6d 61 67 6e  e or if its magn
14460 69 74 75 64 65 20 69 73 20 6c 65 73 73 20 74 68  itude is less th
14470 61 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  an -922337203685
14480 34 37 37 35 38 30 38 20 6f 72 0a 67 72 65 61 74  4775808 or.great
14490 65 72 20 74 68 61 6e 20 39 32 32 33 33 37 32 30  er than 92233720
144a0 33 36 38 35 34 37 37 35 38 30 37 2c 20 74 68 65  36854775807, the
144b0 6e 20 69 74 20 69 73 20 61 20 66 6c 6f 61 74 69  n it is a floati
144c0 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72 61 6c  ng point literal
144d0 2e 0a 4f 74 68 65 72 77 69 73 65 20 69 73 20 69  ..Otherwise is i
144e0 74 20 69 73 20 61 6e 20 20 69 6e 74 65 67 65 72  t is an  integer
144f0 20 6c 69 74 65 72 61 6c 2e 29 5e 0a 5e 54 68 65   literal.)^.^The
14500 20 22 45 22 20 63 68 61 72 61 63 74 65 72 20 74   "E" character t
14510 68 61 74 20 62 65 67 69 6e 73 20 74 68 65 20 65  hat begins the e
14520 78 70 6f 6e 65 6e 74 69 61 74 69 6f 6e 0a 63 6c  xponentiation.cl
14530 61 75 73 65 20 6f 66 20 61 20 66 6c 6f 61 74 69  ause of a floati
14540 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72 61 6c  ng point literal
14550 20 63 61 6e 20 62 65 20 65 69 74 68 65 72 20 75   can be either u
14560 70 70 65 72 20 6f 72 20 6c 6f 77 65 72 20 63 61  pper or lower ca
14570 73 65 2e 0a 5e 28 54 68 65 20 22 2e 22 20 63 68  se..^(The "." ch
14580 61 72 61 63 74 65 72 20 69 73 20 61 6c 77 61 79  aracter is alway
14590 73 20 75 73 65 64 20 0a 61 73 20 74 68 65 20 64  s used .as the d
145a0 65 63 69 6d 61 6c 20 70 6f 69 6e 74 20 65 76 65  ecimal point eve
145b0 6e 20 69 66 20 74 68 65 20 6c 6f 63 61 6c 65 20  n if the locale 
145c0 73 65 74 74 69 6e 67 20 73 70 65 63 69 66 69 65  setting specifie
145d0 73 20 22 2c 22 20 66 6f 72 0a 74 68 69 73 20 72  s "," for.this r
145e0 6f 6c 65 20 2d 20 74 68 65 20 75 73 65 20 6f 66  ole - the use of
145f0 20 22 2c 22 20 66 6f 72 20 74 68 65 20 64 65 63   "," for the dec
14600 69 6d 61 6c 20 70 6f 69 6e 74 20 77 6f 75 6c 64  imal point would
14610 20 72 65 73 75 6c 74 20 69 6e 0a 73 79 6e 74 61   result in.synta
14620 63 74 69 63 20 61 6d 62 69 67 75 69 74 79 2e 29  ctic ambiguity.)
14630 5e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ^..<tcl>hd_fragm
14640 65 6e 74 20 68 65 78 69 6e 74 20 7b 68 65 78 61  ent hexint {hexa
14650 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 20  decimal integer 
14660 6c 69 74 65 72 61 6c 73 7d 20 7b 68 65 78 61 64  literals} {hexad
14670 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 73 7d  ecimal integers}
14680 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 48 65 78 61 64  </tcl>.<p>^Hexad
14690 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 20 6c  ecimal integer l
146a0 69 74 65 72 61 6c 73 20 66 6f 6c 6c 6f 77 20 74  iterals follow t
146b0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 6e 6f  he C-language no
146c0 74 61 74 69 6f 6e 20 6f 66 0a 22 30 78 22 20 6f  tation of."0x" o
146d0 72 20 22 30 58 22 20 66 6f 6c 6c 6f 77 65 64 20  r "0X" followed 
146e0 62 79 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  by hexadecimal d
146f0 69 67 69 74 73 2e 0a 5e 46 6f 72 20 65 78 61 6d  igits..^For exam
14700 70 6c 65 2c 20 30 78 31 32 33 34 20 6d 65 61 6e  ple, 0x1234 mean
14710 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 34 36  s the same as 46
14720 36 30 0a 61 6e 64 20 30 78 38 30 30 30 30 30 30  60.and 0x8000000
14730 30 30 30 30 30 30 30 30 30 20 6d 65 61 6e 73 20  000000000 means 
14740 74 68 65 20 73 61 6d 65 20 61 73 20 2d 39 32 32  the same as -922
14750 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
14760 2e 0a 20 5e 28 48 65 78 61 64 65 63 69 6d 61 6c  .. ^(Hexadecimal
14770 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
14780 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
14790 64 20 61 73 20 36 34 2d 62 69 74 0a 74 77 6f 27  d as 64-bit.two'
147a0 73 2d 63 6f 6d 70 6c 65 6d 65 6e 74 20 69 6e 74  s-complement int
147b0 65 67 65 72 73 20 61 6e 64 20 61 72 65 20 74 68  egers and are th
147c0 75 73 20 6c 69 6d 69 74 65 64 0a 74 6f 20 73 69  us limited.to si
147d0 78 74 65 65 6e 20 73 69 67 6e 69 66 69 63 61 6e  xteen significan
147e0 74 20 64 69 67 69 74 73 20 6f 66 20 70 72 65 63  t digits of prec
147f0 69 73 69 6f 6e 2e 29 5e 0a 53 75 70 70 6f 72 74  ision.)^.Support
14800 20 66 6f 72 20 68 65 78 61 64 65 63 69 6d 61 6c   for hexadecimal
14810 20 69 6e 74 65 67 65 72 73 20 77 61 73 20 61 64   integers was ad
14820 64 65 64 20 74 6f 20 53 51 4c 69 74 65 0a 76 65  ded to SQLite.ve
14830 72 73 69 6f 6e 20 33 2e 38 2e 36 20 28 5b 64 61  rsion 3.8.6 ([da
14840 74 65 6f 66 3a 33 2e 38 2e 36 5d 29 2e 0a 5e 46  teof:3.8.6])..^F
14850 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14860 70 61 74 69 62 69 6c 69 74 79 2c 20 74 68 65 20  patibility, the 
14870 22 30 78 22 20 68 65 78 61 64 65 63 69 6d 61 6c  "0x" hexadecimal
14880 20 69 6e 74 65 67 65 72 0a 6e 6f 74 61 74 69 6f   integer.notatio
14890 6e 20 69 73 20 6f 6e 6c 79 20 75 6e 64 65 72 73  n is only unders
148a0 74 6f 6f 64 20 62 79 20 74 68 65 20 53 51 4c 20  tood by the SQL 
148b0 6c 61 6e 67 75 61 67 65 20 70 61 72 73 65 72 2c  language parser,
148c0 20 6e 6f 74 20 62 79 20 74 68 65 0a 74 79 70 65   not by the.type
148d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 72 6f 75   conversions rou
148e0 74 69 6e 65 73 2e 0a 5e 28 53 74 72 69 6e 67 20  tines..^(String 
148f0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 0a 63  variables that.c
14900 6f 6e 74 61 69 6e 20 74 65 78 74 20 66 6f 72 6d  ontain text form
14910 61 74 74 65 64 20 6c 69 6b 65 20 68 65 78 61 64  atted like hexad
14920 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 73 20  ecimal integers 
14930 61 72 65 20 6e 6f 74 0a 69 6e 74 65 72 70 72 65  are not.interpre
14940 74 65 64 20 61 73 20 68 65 78 61 64 65 63 69 6d  ted as hexadecim
14950 61 6c 20 69 6e 74 65 67 65 72 73 20 77 68 65 6e  al integers when
14960 20 63 6f 65 72 63 69 6e 67 20 74 68 65 20 73 74   coercing the st
14970 72 69 6e 67 20 76 61 6c 75 65 0a 69 6e 74 6f 20  ring value.into 
14980 61 6e 20 69 6e 74 65 67 65 72 20 64 75 65 20 74  an integer due t
14990 6f 20 61 20 5b 43 41 53 54 20 65 78 70 72 65 73  o a [CAST expres
149a0 73 69 6f 6e 5d 20 6f 72 20 66 6f 72 20 61 20 5b  sion] or for a [
149b0 63 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79 5d  column affinity]
149c0 0a 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 20  .transformation 
149d0 6f 72 20 70 72 69 6f 72 20 74 6f 20 70 65 72 66  or prior to perf
149e0 6f 72 6d 69 6e 67 20 61 20 6e 75 6d 65 72 69 63  orming a numeric
149f0 20 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 66 6f   operation or fo
14a00 72 0a 61 6e 79 20 6f 74 68 65 72 20 72 75 6e 2d  r.any other run-
14a10 74 69 6d 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  time conversions
14a20 2e 29 5e 20 20 5e 28 57 68 65 6e 20 63 6f 65 72  .)^  ^(When coer
14a30 63 69 6e 67 20 61 0a 73 74 72 69 6e 67 20 76 61  cing a.string va
14a40 6c 75 65 20 69 6e 20 74 68 65 20 66 6f 72 6d 61  lue in the forma
14a50 74 20 6f 66 20 61 20 68 65 78 61 64 65 63 69 6d  t of a hexadecim
14a60 61 6c 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  al integer into 
14a70 61 6e 20 69 6e 74 65 67 65 72 0a 76 61 6c 75 65  an integer.value
14a80 2c 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  , the conversion
14a90 20 70 72 6f 63 65 73 73 20 73 74 6f 70 73 20 77   process stops w
14aa0 68 65 6e 20 74 68 65 20 27 78 27 20 63 68 61 72  hen the 'x' char
14ab0 61 63 74 65 72 20 69 73 20 73 65 65 6e 0a 73 6f  acter is seen.so
14ac0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 69   the resulting i
14ad0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 69 73 20  nteger value is 
14ae0 61 6c 77 61 79 73 20 7a 65 72 6f 2e 29 5e 0a 5e  always zero.)^.^
14af0 28 53 51 4c 69 74 65 20 6f 6e 6c 79 20 75 6e 64  (SQLite only und
14b00 65 72 73 74 61 6e 64 73 20 74 68 65 20 68 65 78  erstands the hex
14b10 61 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72  adecimal integer
14b20 20 6e 6f 74 61 74 69 6f 6e 20 77 68 65 6e 20 69   notation when i
14b30 74 0a 61 70 70 65 61 72 73 20 69 6e 20 74 68 65  t.appears in the
14b40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14b50 65 78 74 2c 20 6e 6f 74 20 77 68 65 6e 20 69 74  ext, not when it
14b60 20 61 70 70 65 61 72 73 20 61 73 0a 70 61 72 74   appears as.part
14b70 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14b80 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  of the database.
14b90 29 5e 0a 0a 3c 70 3e 20 5e 41 20 73 74 72 69 6e  )^..<p> ^A strin
14ba0 67 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 66 6f  g constant is fo
14bb0 72 6d 65 64 20 62 79 20 65 6e 63 6c 6f 73 69 6e  rmed by enclosin
14bc0 67 20 74 68 65 0a 73 74 72 69 6e 67 20 69 6e 20  g the.string in 
14bd0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 28 27  single quotes ('
14be0 29 2e 20 20 5e 41 20 73 69 6e 67 6c 65 20 71 75  ).  ^A single qu
14bf0 6f 74 65 20 77 69 74 68 69 6e 20 74 68 65 20 73  ote within the s
14c00 74 72 69 6e 67 20 63 61 6e 0a 62 65 20 65 6e 63  tring can.be enc
14c10 6f 64 65 64 20 62 79 20 70 75 74 74 69 6e 67 20  oded by putting 
14c20 74 77 6f 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  two single quote
14c30 73 20 69 6e 20 61 20 72 6f 77 20 2d 20 61 73 20  s in a row - as 
14c40 69 6e 20 50 61 73 63 61 6c 2e 0a 43 2d 73 74 79  in Pascal..C-sty
14c50 6c 65 20 65 73 63 61 70 65 73 20 75 73 69 6e 67  le escapes using
14c60 20 74 68 65 20 62 61 63 6b 73 6c 61 73 68 20 63   the backslash c
14c70 68 61 72 61 63 74 65 72 20 61 72 65 20 6e 6f 74  haracter are not
14c80 20 73 75 70 70 6f 72 74 65 64 20 62 65 63 61 75   supported becau
14c90 73 65 0a 74 68 65 79 20 61 72 65 20 6e 6f 74 20  se.they are not 
14ca0 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 0a 0a 3c  standard SQL...<
14cb0 70 3e 20 5e 42 4c 4f 42 20 6c 69 74 65 72 61 6c  p> ^BLOB literal
14cc0 73 20 61 72 65 20 73 74 72 69 6e 67 20 6c 69 74  s are string lit
14cd0 65 72 61 6c 73 20 63 6f 6e 74 61 69 6e 69 6e 67  erals containing
14ce0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 61 74   hexadecimal dat
14cf0 61 20 61 6e 64 0a 70 72 65 63 65 64 65 64 20 62  a and.preceded b
14d00 79 20 61 20 73 69 6e 67 6c 65 20 22 78 22 20 6f  y a single "x" o
14d10 72 20 22 58 22 20 63 68 61 72 61 63 74 65 72 2e  r "X" character.
14d20 20 20 5e 28 45 78 61 6d 70 6c 65 3a 20 58 27 35    ^(Example: X'5
14d30 33 35 31 34 43 36 39 37 34 36 35 27 29 5e 0a 0a  3514C697465')^..
14d40 3c 70 3e 0a 5e 41 20 6c 69 74 65 72 61 6c 20 76  <p>.^A literal v
14d50 61 6c 75 65 20 63 61 6e 20 61 6c 73 6f 20 62 65  alue can also be
14d60 20 74 68 65 20 74 6f 6b 65 6e 20 22 4e 55 4c 4c   the token "NULL
14d70 22 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  "..</p>..<tcl>hd
14d80 5f 66 72 61 67 6d 65 6e 74 20 76 61 72 70 61 72  _fragment varpar
14d90 61 6d 20 70 61 72 61 6d 65 74 65 72 20 70 61 72  am parameter par
14da0 61 6d 65 74 65 72 73 20 7b 62 6f 75 6e 64 20 70  ameters {bound p
14db0 61 72 61 6d 65 74 65 72 7d 20 7b 62 6f 75 6e 64  arameter} {bound
14dc0 20 70 61 72 61 6d 65 74 65 72 73 7d 3c 2f 74 63   parameters}</tc
14dd0 6c 3e 0a 3c 68 33 3e 50 61 72 61 6d 65 74 65 72  l>.<h3>Parameter
14de0 73 3c 2f 68 33 3e 0a 3c 70 3e 0a 41 20 22 76 61  s</h3>.<p>.A "va
14df0 72 69 61 62 6c 65 22 20 6f 72 20 22 70 61 72 61  riable" or "para
14e00 6d 65 74 65 72 22 20 74 6f 6b 65 6e 0a 73 70 65  meter" token.spe
14e10 63 69 66 69 65 73 20 61 20 70 6c 61 63 65 68 6f  cifies a placeho
14e20 6c 64 65 72 20 69 6e 20 74 68 65 20 65 78 70 72  lder in the expr
14e30 65 73 73 69 6f 6e 20 66 6f 72 20 61 20 0a 76 61  ession for a .va
14e40 6c 75 65 20 74 68 61 74 20 69 73 20 66 69 6c 6c  lue that is fill
14e50 65 64 20 69 6e 20 61 74 20 72 75 6e 74 69 6d 65  ed in at runtime
14e60 20 75 73 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69   using the.[sqli
14e70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
14e80 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  | sqlite3_bind()
14e90 5d 20 66 61 6d 69 6c 79 20 6f 66 20 43 2f 43 2b  ] family of C/C+
14ea0 2b 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 50 61  + interfaces..Pa
14eb0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 74 61 6b  rameters can tak
14ec0 65 20 73 65 76 65 72 61 6c 20 66 6f 72 6d 73 3a  e several forms:
14ed0 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
14ee0 74 65 3e 0a 3c 74 61 62 6c 65 3e 0a 3c 74 72 3e  te>.<table>.<tr>
14ef0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69 67 68  .<td align="righ
14f00 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  t" valign="top">
14f10 3c 62 3e 3f 3c 2f 62 3e 3c 69 3e 4e 4e 4e 3c 2f  <b>?</b><i>NNN</
14f20 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74 68  i></td><td width
14f30 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74 64 3e  ="20"></td>.<td>
14f40 5e 28 41 20 71 75 65 73 74 69 6f 6e 20 6d 61 72  ^(A question mar
14f50 6b 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  k followed by a 
14f60 6e 75 6d 62 65 72 20 3c 69 3e 4e 4e 4e 3c 2f 69  number <i>NNN</i
14f70 3e 20 68 6f 6c 64 73 20 61 20 73 70 6f 74 20 66  > holds a spot f
14f80 6f 72 20 74 68 65 0a 4e 4e 4e 2d 74 68 20 70 61  or the.NNN-th pa
14f90 72 61 6d 65 74 65 72 2e 20 20 4e 4e 4e 20 6d 75  rameter.  NNN mu
14fa0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
14fb0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  and [SQLITE_MAX_
14fc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
14fd0 2e 29 5e 0a 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a  .)^.</td>.</tr>.
14fe0 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  <tr>.<td align="
14ff0 72 69 67 68 74 22 20 76 61 6c 69 67 6e 3d 22 74  right" valign="t
15000 6f 70 22 3e 3c 62 3e 3f 3c 2f 62 3e 3c 2f 74 64  op"><b>?</b></td
15010 3e 3c 74 64 20 77 69 64 74 68 3d 22 32 30 22 3e  ><td width="20">
15020 3c 2f 74 64 3e 0a 3c 74 64 3e 5e 41 20 71 75 65  </td>.<td>^A que
15030 73 74 69 6f 6e 20 6d 61 72 6b 20 74 68 61 74 20  stion mark that 
15040 69 73 20 6e 6f 74 20 66 6f 6c 6c 6f 77 65 64 20  is not followed 
15050 62 79 20 61 20 6e 75 6d 62 65 72 20 63 72 65 61  by a number crea
15060 74 65 73 20 61 20 70 61 72 61 6d 65 74 65 72 0a  tes a parameter.
15070 77 69 74 68 20 61 20 6e 75 6d 62 65 72 20 6f 6e  with a number on
15080 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  e greater than t
15090 68 65 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d  he largest param
150a0 65 74 65 72 20 6e 75 6d 62 65 72 20 61 6c 72 65  eter number alre
150b0 61 64 79 20 61 73 73 69 67 6e 65 64 2e 0a 5e 49  ady assigned..^I
150c0 66 20 74 68 69 73 20 6d 65 61 6e 73 20 74 68 65  f this means the
150d0 20 70 61 72 61 6d 65 74 65 72 20 6e 75 6d 62 65   parameter numbe
150e0 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  r is greater tha
150f0 6e 0a 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  n.[SQLITE_MAX_VA
15100 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 2c 20  RIABLE_NUMBER], 
15110 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 0a  it is an error..
15120 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 66  This parameter f
15130 6f 72 6d 61 74 20 69 73 20 70 72 6f 76 69 64 65  ormat is provide
15140 64 20 66 6f 72 20 63 6f 6d 70 61 74 69 62 69 6c  d for compatibil
15150 69 74 79 20 77 69 74 68 20 6f 74 68 65 72 20 64  ity with other d
15160 61 74 61 62 61 73 65 0a 65 6e 67 69 6e 65 73 2e  atabase.engines.
15170 20 20 42 75 74 20 62 65 63 61 75 73 65 20 69 74    But because it
15180 20 69 73 20 65 61 73 79 20 74 6f 20 6d 69 73 63   is easy to misc
15190 6f 75 6e 74 20 74 68 65 20 71 75 65 73 74 69 6f  ount the questio
151a0 6e 20 6d 61 72 6b 73 2c 20 74 68 65 0a 75 73 65  n marks, the.use
151b0 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
151c0 65 72 20 66 6f 72 6d 61 74 20 69 73 20 64 69 73  er format is dis
151d0 63 6f 75 72 61 67 65 64 2e 20 20 50 72 6f 67 72  couraged.  Progr
151e0 61 6d 6d 65 72 73 20 61 72 65 20 65 6e 63 6f 75  ammers are encou
151f0 72 61 67 65 64 0a 74 6f 20 75 73 65 20 6f 6e 65  raged.to use one
15200 20 6f 66 20 74 68 65 20 73 79 6d 62 6f 6c 69 63   of the symbolic
15210 20 66 6f 72 6d 61 74 73 20 62 65 6c 6f 77 20 6f   formats below o
15220 72 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 61  r the ?NNN forma
15230 74 20 61 62 6f 76 65 20 69 6e 73 74 65 61 64 2e  t above instead.
15240 0a 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74 72  .</td>.</tr>.<tr
15250 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69 67  >.<td align="rig
15260 68 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22  ht" valign="top"
15270 3e 3c 62 3e 3a 3c 2f 62 3e 3c 69 3e 41 41 41 41  ><b>:</b><i>AAAA
15280 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64  </i></td><td wid
15290 74 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74  th="20"></td>.<t
152a0 64 3e 5e 41 20 63 6f 6c 6f 6e 20 66 6f 6c 6c 6f  d>^A colon follo
152b0 77 65 64 20 62 79 20 61 6e 20 69 64 65 6e 74 69  wed by an identi
152c0 66 69 65 72 20 6e 61 6d 65 20 68 6f 6c 64 73 20  fier name holds 
152d0 61 20 73 70 6f 74 20 66 6f 72 20 61 20 0a 5b 73  a spot for a .[s
152e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
152f0 6d 65 74 65 72 5f 6e 61 6d 65 7c 6e 61 6d 65 64  meter_name|named
15300 20 70 61 72 61 6d 65 74 65 72 5d 20 77 69 74 68   parameter] with
15310 20 74 68 65 20 6e 61 6d 65 20 3a 41 41 41 41 2e   the name :AAAA.
15320 20 20 0a 5e 28 4e 61 6d 65 64 20 70 61 72 61 6d    .^(Named param
15330 65 74 65 72 73 20 61 72 65 20 61 6c 73 6f 20 6e  eters are also n
15340 75 6d 62 65 72 65 64 2e 20 54 68 65 20 6e 75 6d  umbered. The num
15350 62 65 72 20 61 73 73 69 67 6e 65 64 20 69 73 20  ber assigned is 
15360 6f 6e 65 20 67 72 65 61 74 65 72 20 74 68 61 6e  one greater than
15370 0a 74 68 65 20 6c 61 72 67 65 73 74 20 70 61 72  .the largest par
15380 61 6d 65 74 65 72 20 6e 75 6d 62 65 72 20 61 6c  ameter number al
15390 72 65 61 64 79 20 61 73 73 69 67 6e 65 64 2e 29  ready assigned.)
153a0 5e 20 5e 49 66 20 74 68 69 73 20 6d 65 61 6e 73  ^ ^If this means
153b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 77   the parameter.w
153c0 6f 75 6c 64 20 62 65 20 61 73 73 69 67 6e 65 64  ould be assigned
153d0 20 61 20 6e 75 6d 62 65 72 20 67 72 65 61 74 65   a number greate
153e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4d  r than [SQLITE_M
153f0 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
15400 45 52 5d 2c 20 69 74 20 69 73 0a 61 6e 20 65 72  ER], it is.an er
15410 72 6f 72 2e 20 54 6f 20 61 76 6f 69 64 20 63 6f  ror. To avoid co
15420 6e 66 75 73 69 6f 6e 2c 20 69 74 20 69 73 20 62  nfusion, it is b
15430 65 73 74 20 74 6f 20 61 76 6f 69 64 20 6d 69 78  est to avoid mix
15440 69 6e 67 20 6e 61 6d 65 64 20 61 6e 64 20 6e 75  ing named and nu
15450 6d 62 65 72 65 64 0a 70 61 72 61 6d 65 74 65 72  mbered.parameter
15460 73 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74  s.</td>.</tr>.<t
15470 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69  r>.<td align="ri
15480 67 68 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70  ght" valign="top
15490 22 3e 3c 62 3e 40 3c 2f 62 3e 3c 69 3e 41 41 41  "><b>@</b><i>AAA
154a0 41 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69  A</i></td><td wi
154b0 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c  dth="20"></td>.<
154c0 74 64 3e 5e 41 6e 20 22 61 74 22 20 73 69 67 6e  td>^An "at" sign
154d0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
154e0 69 6b 65 20 61 20 63 6f 6c 6f 6e 2c 20 65 78 63  ike a colon, exc
154f0 65 70 74 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ept that the nam
15500 65 20 6f 66 0a 74 68 65 20 70 61 72 61 6d 65 74  e of.the paramet
15510 65 72 20 63 72 65 61 74 65 64 20 69 73 20 40 41  er created is @A
15520 41 41 41 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a  AAA.</td>.</tr>.
15530 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  <tr>.<td align="
15540 72 69 67 68 74 22 20 76 61 6c 69 67 6e 3d 22 74  right" valign="t
15550 6f 70 22 3e 3c 62 3e 24 3c 2f 62 3e 3c 69 3e 41  op"><b>$</b><i>A
15560 41 41 41 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20  AAA</i></td><td 
15570 77 69 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64 3e  width="20"></td>
15580 0a 3c 74 64 3e 5e 41 20 64 6f 6c 6c 61 72 2d 73  .<td>^A dollar-s
15590 69 67 6e 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ign followed by 
155a0 61 6e 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  an identifier na
155b0 6d 65 20 61 6c 73 6f 20 68 6f 6c 64 73 20 61 20  me also holds a 
155c0 73 70 6f 74 20 66 6f 72 20 61 20 6e 61 6d 65 64  spot for a named
155d0 0a 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20  .parameter with 
155e0 74 68 65 20 6e 61 6d 65 20 24 41 41 41 41 2e 20  the name $AAAA. 
155f0 20 5e 28 54 68 65 20 69 64 65 6e 74 69 66 69 65   ^(The identifie
15600 72 20 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 63  r name in this c
15610 61 73 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 0a  ase can include.
15620 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 63 63 75  one or more occu
15630 72 72 65 6e 63 65 73 20 6f 66 20 22 3a 3a 22 20  rrences of "::" 
15640 61 6e 64 20 61 20 73 75 66 66 69 78 20 65 6e 63  and a suffix enc
15650 6c 6f 73 65 64 20 69 6e 20 22 28 2e 2e 2e 29 22  losed in "(...)"
15660 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 61 6e 79 20   containing.any 
15670 74 65 78 74 20 61 74 20 61 6c 6c 2e 29 5e 20 20  text at all.)^  
15680 54 68 69 73 20 73 79 6e 74 61 78 20 69 73 20 74  This syntax is t
15690 68 65 20 66 6f 72 6d 20 6f 66 20 61 20 76 61 72  he form of a var
156a0 69 61 62 6c 65 20 6e 61 6d 65 20 69 6e 20 74 68  iable name in th
156b0 65 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 74 63  e.[http://www.tc
156c0 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 20 7c 20 54 63  l-lang.org/ | Tc
156d0 6c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61  l programming la
156e0 6e 67 75 61 67 65 5d 2e 20 20 54 68 65 20 70 72  nguage].  The pr
156f0 65 73 65 6e 63 65 0a 6f 66 20 74 68 69 73 20 73  esence.of this s
15700 79 6e 74 61 78 20 72 65 73 75 6c 74 73 20 66 72  yntax results fr
15710 6f 6d 20 74 68 65 20 66 61 63 74 20 74 68 61 74  om the fact that
15720 20 53 51 4c 69 74 65 20 69 73 20 72 65 61 6c 6c   SQLite is reall
15730 79 20 61 20 0a 5b 54 63 6c 20 65 78 74 65 6e 73  y a .[Tcl extens
15740 69 6f 6e 5d 20 74 68 61 74 20 68 61 73 20 65 73  ion] that has es
15750 63 61 70 65 64 20 69 6e 74 6f 20 74 68 65 20 77  caped into the w
15760 69 6c 64 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a  ild.</td>.</tr>.
15770 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b  </table>.</block
15780 71 75 6f 74 65 3e 0a 0a 3c 70 3e 5e 50 61 72 61  quote>..<p>^Para
15790 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
157a0 6e 6f 74 20 61 73 73 69 67 6e 65 64 20 76 61 6c  not assigned val
157b0 75 65 73 20 75 73 69 6e 67 0a 5b 73 71 6c 69 74  ues using.[sqlit
157c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 7c  e3_bind_blob() |
157d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d   sqlite3_bind()]
157e0 20 61 72 65 20 74 72 65 61 74 65 64 0a 61 73 20   are treated.as 
157f0 4e 55 4c 4c 2e 20 20 54 68 65 20 5b 73 71 6c 69  NULL.  The [sqli
15800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
15810 65 72 5f 69 6e 64 65 78 28 29 5d 20 69 6e 74 65  er_index()] inte
15820 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
15830 64 0a 74 6f 20 74 72 61 6e 73 6c 61 74 65 20 61  d.to translate a
15840 20 73 79 6d 62 6f 6c 69 63 20 70 61 72 61 6d 65   symbolic parame
15850 74 65 72 20 6e 61 6d 65 20 69 6e 74 6f 20 69 74  ter name into it
15860 73 20 65 71 75 69 76 61 6c 65 6e 74 20 6e 75 6d  s equivalent num
15870 65 72 69 63 20 69 6e 64 65 78 2e 3c 2f 70 3e 0a  eric index.</p>.
15880 0a 3c 70 3e 5e 54 68 65 20 6d 61 78 69 6d 75 6d  .<p>^The maximum
15890 20 70 61 72 61 6d 65 74 65 72 20 6e 75 6d 62 65   parameter numbe
158a0 72 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  r is set at comp
158b0 69 6c 65 2d 74 69 6d 65 20 62 79 0a 74 68 65 20  ile-time by.the 
158c0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49  [SQLITE_MAX_VARI
158d0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 6d 61 63  ABLE_NUMBER] mac
158e0 72 6f 2e 20 20 5e 28 41 6e 20 69 6e 64 69 76 69  ro.  ^(An indivi
158f0 64 75 61 6c 20 5b 64 61 74 61 62 61 73 65 20 63  dual [database c
15900 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 44 20 63 61 6e  onnection].D can
15910 20 72 65 64 75 63 65 20 69 74 73 20 6d 61 78 69   reduce its maxi
15920 6d 75 6d 20 70 61 72 61 6d 65 74 65 72 20 6e 75  mum parameter nu
15930 6d 62 65 72 20 62 65 6c 6f 77 20 74 68 65 20 63  mber below the c
15940 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
15950 6d 75 6d 0a 75 73 69 6e 67 20 74 68 65 20 5b 73  mum.using the [s
15960 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 44 2c  qlite3_limit](D,
15970 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
15980 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 2c  ARIABLE_NUMBER],
15990 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63 65 2e 29  ...) interface.)
159a0 5e 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  ^.</p>..<tcl>hd_
159b0 66 72 61 67 6d 65 6e 74 20 6c 69 6b 65 20 4c 49  fragment like LI
159c0 4b 45 20 45 53 43 41 50 45 3c 2f 74 63 6c 3e 0a  KE ESCAPE</tcl>.
159d0 3c 68 33 3e 54 68 65 20 4c 49 4b 45 2c 20 47 4c  <h3>The LIKE, GL
159e0 4f 42 2c 20 52 45 47 45 58 50 2c 20 61 6e 64 20  OB, REGEXP, and 
159f0 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 73 3c  MATCH operators<
15a00 2f 68 33 3e 0a 3c 70 3e 5e 54 68 65 20 4c 49 4b  /h3>.<p>^The LIK
15a10 45 20 6f 70 65 72 61 74 6f 72 20 64 6f 65 73 20  E operator does 
15a20 61 20 70 61 74 74 65 72 6e 20 6d 61 74 63 68 69  a pattern matchi
15a30 6e 67 20 63 6f 6d 70 61 72 69 73 6f 6e 2e 20 5e  ng comparison. ^
15a40 54 68 65 20 6f 70 65 72 61 6e 64 0a 74 6f 20 74  The operand.to t
15a50 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
15a60 4c 49 4b 45 20 6f 70 65 72 61 74 6f 72 20 63 6f  LIKE operator co
15a70 6e 74 61 69 6e 73 20 74 68 65 20 70 61 74 74 65  ntains the patte
15a80 72 6e 20 61 6e 64 20 74 68 65 20 6c 65 66 74 20  rn and the left 
15a90 68 61 6e 64 0a 6f 70 65 72 61 6e 64 20 63 6f 6e  hand.operand con
15aa0 74 61 69 6e 73 20 74 68 65 20 73 74 72 69 6e 67  tains the string
15ab0 20 74 6f 20 6d 61 74 63 68 20 61 67 61 69 6e 73   to match agains
15ac0 74 20 74 68 65 20 70 61 74 74 65 72 6e 2e 0a 0a  t the pattern...
15ad0 3c 74 63 6c 3e 68 64 5f 70 75 74 73 20 22 5e 41  <tcl>hd_puts "^A
15ae0 20 70 65 72 63 65 6e 74 20 73 79 6d 62 6f 6c 20   percent symbol 
15af0 28 5c 22 25 5c 22 29 20 69 6e 20 74 68 65 20 4c  (\"%\") in the L
15b00 49 4b 45 20 70 61 74 74 65 72 6e 20 6d 61 74 63  IKE pattern matc
15b10 68 65 73 20 61 6e 79 0a 73 65 71 75 65 6e 63 65  hes any.sequence
15b20 20 6f 66 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65   of zero or more
15b30 20 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 74   characters in t
15b40 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 41 6e 20  he string.  ^An 
15b50 75 6e 64 65 72 73 63 6f 72 65 0a 28 5c 22 5f 5c  underscore.(\"_\
15b60 22 29 20 69 6e 20 74 68 65 20 4c 49 4b 45 20 70  ") in the LIKE p
15b70 61 74 74 65 72 6e 20 6d 61 74 63 68 65 73 20 61  attern matches a
15b80 6e 79 20 73 69 6e 67 6c 65 20 63 68 61 72 61 63  ny single charac
15b90 74 65 72 20 69 6e 20 74 68 65 0a 73 74 72 69 6e  ter in the.strin
15ba0 67 2e 20 20 5e 28 41 6e 79 20 6f 74 68 65 72 20  g.  ^(Any other 
15bb0 63 68 61 72 61 63 74 65 72 20 6d 61 74 63 68 65  character matche
15bc0 73 20 69 74 73 65 6c 66 20 6f 72 20 69 74 73 20  s itself or its 
15bd0 6c 6f 77 65 72 2f 75 70 70 65 72 20 63 61 73 65  lower/upper case
15be0 0a 65 71 75 69 76 61 6c 65 6e 74 20 28 69 2e 65  .equivalent (i.e
15bf0 2e 20 63 61 73 65 2d 69 6e 73 65 6e 73 69 74 69  . case-insensiti
15c00 76 65 20 6d 61 74 63 68 69 6e 67 29 2e 29 5e 0a  ve matching).)^.
15c10 0a 3c 75 3e 49 6d 70 6f 72 74 61 6e 74 20 4e 6f  .<u>Important No
15c20 74 65 3a 3c 2f 75 3e 20 5e 53 51 4c 69 74 65 20  te:</u> ^SQLite 
15c30 6f 6e 6c 79 0a 75 6e 64 65 72 73 74 61 6e 64 73  only.understands
15c40 20 75 70 70 65 72 2f 6c 6f 77 65 72 20 63 61 73   upper/lower cas
15c50 65 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72  e for ASCII char
15c60 61 63 74 65 72 73 20 62 79 20 64 65 66 61 75 6c  acters by defaul
15c70 74 2e 20 20 5e 54 68 65 0a 4c 49 4b 45 20 6f 70  t.  ^The.LIKE op
15c80 65 72 61 74 6f 72 20 69 73 20 63 61 73 65 20 73  erator is case s
15c90 65 6e 73 69 74 69 76 65 20 62 79 20 64 65 66 61  ensitive by defa
15ca0 75 6c 74 20 66 6f 72 20 75 6e 69 63 6f 64 65 20  ult for unicode 
15cb0 63 68 61 72 61 63 74 65 72 73 20 74 68 61 74 20  characters that 
15cc0 61 72 65 0a 62 65 79 6f 6e 64 20 74 68 65 20 41  are.beyond the A
15cd0 53 43 49 49 20 72 61 6e 67 65 2e 20 20 46 6f 72  SCII range.  For
15ce0 20 65 78 61 6d 70 6c 65 2c 0a 5e 74 68 65 20 65   example,.^the e
15cf0 78 70 72 65 73 73 69 6f 6e 20 3c 62 3e 27 61 27  xpression <b>'a'
15d00 26 6e 62 73 70 3b 4c 49 4b 45 26 6e 62 73 70 3b  &nbsp;LIKE&nbsp;
15d10 27 41 27 3c 2f 62 3e 0a 69 73 20 54 52 55 45 20  'A'</b>.is TRUE 
15d20 62 75 74 20 3c 62 3e 27 26 61 65 6c 69 67 3b 27  but <b>'&aelig;'
15d30 26 6e 62 73 70 3b 4c 49 4b 45 26 6e 62 73 70 3b  &nbsp;LIKE&nbsp;
15d40 27 26 41 45 6c 69 67 3b 27 3c 2f 62 3e 20 69 73  '&AElig;'</b> is
15d50 20 46 41 4c 53 45 2e 22 3c 2f 74 63 6c 3e 0a 54   FALSE."</tcl>.T
15d60 68 65 20 49 43 55 20 65 78 74 65 6e 73 69 6f 6e  he ICU extension
15d70 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 63 6c 75   to SQLite inclu
15d80 64 65 73 20 61 6e 20 65 6e 68 61 6e 63 65 64 20  des an enhanced 
15d90 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 0a 4c  version of the.L
15da0 49 4b 45 20 6f 70 65 72 61 74 6f 72 20 74 68 61  IKE operator tha
15db0 74 20 64 6f 65 73 20 63 61 73 65 20 66 6f 6c 64  t does case fold
15dc0 69 6e 67 20 61 63 72 6f 73 73 20 61 6c 6c 20 75  ing across all u
15dd0 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 65 72  nicode character
15de0 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74  s.</p>..<p>^If t
15df0 68 65 20 6f 70 74 69 6f 6e 61 6c 20 45 53 43 41  he optional ESCA
15e00 50 45 20 63 6c 61 75 73 65 20 69 73 20 70 72 65  PE clause is pre
15e10 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 65  sent, then the e
15e20 78 70 72 65 73 73 69 6f 6e 0a 66 6f 6c 6c 6f 77  xpression.follow
15e30 69 6e 67 20 74 68 65 20 45 53 43 41 50 45 20 6b  ing the ESCAPE k
15e40 65 79 77 6f 72 64 20 6d 75 73 74 20 65 76 61 6c  eyword must eval
15e50 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
15e60 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 0a 61   consisting of.a
15e70 20 73 69 6e 67 6c 65 20 63 68 61 72 61 63 74 65   single characte
15e80 72 2e 20 5e 54 68 69 73 20 63 68 61 72 61 63 74  r. ^This charact
15e90 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 69  er may be used i
15ea0 6e 20 74 68 65 20 4c 49 4b 45 20 70 61 74 74 65  n the LIKE patte
15eb0 72 6e 0a 74 6f 20 69 6e 63 6c 75 64 65 20 6c 69  rn.to include li
15ec0 74 65 72 61 6c 20 70 65 72 63 65 6e 74 20 6f 72  teral percent or
15ed0 20 75 6e 64 65 72 73 63 6f 72 65 20 63 68 61 72   underscore char
15ee0 61 63 74 65 72 73 2e 20 5e 54 68 65 20 65 73 63  acters. ^The esc
15ef0 61 70 65 0a 63 68 61 72 61 63 74 65 72 20 66 6f  ape.character fo
15f00 6c 6c 6f 77 65 64 20 62 79 20 61 20 70 65 72 63  llowed by a perc
15f10 65 6e 74 20 73 79 6d 62 6f 6c 20 28 25 29 2c 20  ent symbol (%), 
15f20 75 6e 64 65 72 73 63 6f 72 65 20 28 5f 29 2c 20  underscore (_), 
15f30 6f 72 20 61 20 73 65 63 6f 6e 64 0a 69 6e 73 74  or a second.inst
15f40 61 6e 63 65 20 6f 66 20 74 68 65 20 65 73 63 61  ance of the esca
15f50 70 65 20 63 68 61 72 61 63 74 65 72 20 69 74 73  pe character its
15f60 65 6c 66 20 6d 61 74 63 68 65 73 20 61 0a 6c 69  elf matches a.li
15f70 74 65 72 61 6c 20 70 65 72 63 65 6e 74 20 73 79  teral percent sy
15f80 6d 62 6f 6c 2c 20 75 6e 64 65 72 73 63 6f 72 65  mbol, underscore
15f90 2c 20 6f 72 20 61 20 73 69 6e 67 6c 65 20 65 73  , or a single es
15fa0 63 61 70 65 20 63 68 61 72 61 63 74 65 72 2c 0a  cape character,.
15fb0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 0a 3c  respectively...<
15fc0 70 3e 5e 54 68 65 20 69 6e 66 69 78 20 4c 49 4b  p>^The infix LIK
15fd0 45 20 6f 70 65 72 61 74 6f 72 20 69 73 20 69 6d  E operator is im
15fe0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 63 61 6c  plemented by cal
15ff0 6c 69 6e 67 20 74 68 65 0a 61 70 70 6c 69 63 61  ling the.applica
16000 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
16010 20 66 75 6e 63 74 69 6f 6e 73 20 5b 6c 69 6b 65   functions [like
16020 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f  (<i>Y</i>,<i>X</
16030 69 3e 29 5d 20 6f 72 0a 5b 6c 69 6b 65 28 3c 69  i>)] or.[like(<i
16040 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f 69 3e 2c  >Y</i>,<i>X</i>,
16050 3c 69 3e 5a 3c 2f 69 3e 29 5d 3c 2f 61 3e 2e 3c  <i>Z</i>)]</a>.<
16060 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 4c 49 4b  /p>..<p>^The LIK
16070 45 20 6f 70 65 72 61 74 6f 72 20 63 61 6e 20 62  E operator can b
16080 65 20 6d 61 64 65 20 63 61 73 65 20 73 65 6e 73  e made case sens
16090 69 74 69 76 65 20 75 73 69 6e 67 20 74 68 65 0a  itive using the.
160a0 5b 63 61 73 65 5f 73 65 6e 73 69 74 69 76 65 5f  [case_sensitive_
160b0 6c 69 6b 65 20 70 72 61 67 6d 61 5d 2e 3c 2f 70  like pragma].</p
160c0 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
160d0 65 6e 74 20 67 6c 6f 62 20 47 4c 4f 42 3c 2f 74  ent glob GLOB</t
160e0 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 47 4c 4f 42  cl>.<p>^The GLOB
160f0 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 69 6d   operator is sim
16100 69 6c 61 72 20 74 6f 20 4c 49 4b 45 20 62 75 74  ilar to LIKE but
16110 20 75 73 65 73 20 74 68 65 20 55 6e 69 78 0a 66   uses the Unix.f
16120 69 6c 65 20 67 6c 6f 62 62 69 6e 67 20 73 79 6e  ile globbing syn
16130 74 61 78 20 66 6f 72 20 69 74 73 20 77 69 6c 64  tax for its wild
16140 63 61 72 64 73 2e 20 20 5e 41 6c 73 6f 2c 20 47  cards.  ^Also, G
16150 4c 4f 42 20 69 73 20 63 61 73 65 0a 73 65 6e 73  LOB is case.sens
16160 69 74 69 76 65 2c 20 75 6e 6c 69 6b 65 20 4c 49  itive, unlike LI
16170 4b 45 2e 20 20 5e 42 6f 74 68 20 47 4c 4f 42 20  KE.  ^Both GLOB 
16180 61 6e 64 20 4c 49 4b 45 20 6d 61 79 20 62 65 20  and LIKE may be 
16190 70 72 65 63 65 64 65 64 20 62 79 0a 74 68 65 20  preceded by.the 
161a0 4e 4f 54 20 6b 65 79 77 6f 72 64 20 74 6f 20 69  NOT keyword to i
161b0 6e 76 65 72 74 20 74 68 65 20 73 65 6e 73 65 20  nvert the sense 
161c0 6f 66 20 74 68 65 20 74 65 73 74 2e 20 20 5e 54  of the test.  ^T
161d0 68 65 20 69 6e 66 69 78 20 47 4c 4f 42 20 0a 6f  he infix GLOB .o
161e0 70 65 72 61 74 6f 72 20 69 73 20 69 6d 70 6c 65  perator is imple
161f0 6d 65 6e 74 65 64 20 62 79 20 63 61 6c 6c 69 6e  mented by callin
16200 67 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 0a 5b  g the function.[
16210 67 6c 6f 62 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69  glob(<i>Y</i>,<i
16220 3e 58 3c 2f 69 3e 29 5d 20 61 6e 64 20 63 61 6e  >X</i>)] and can
16230 20 62 65 20 6d 6f 64 69 66 69 65 64 20 62 79 20   be modified by 
16240 6f 76 65 72 72 69 64 69 6e 67 0a 74 68 61 74 20  overriding.that 
16250 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c  function.</p>..<
16260 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
16270 72 65 67 65 78 70 20 52 45 47 45 58 50 3c 2f 74  regexp REGEXP</t
16280 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 52 45 47 45  cl>.<p>^The REGE
16290 58 50 20 6f 70 65 72 61 74 6f 72 20 69 73 20 61  XP operator is a
162a0 20 73 70 65 63 69 61 6c 20 73 79 6e 74 61 78 20   special syntax 
162b0 66 6f 72 20 74 68 65 20 72 65 67 65 78 70 28 29  for the regexp()
162c0 0a 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 2e 20  .user function. 
162d0 20 5e 4e 6f 20 72 65 67 65 78 70 28 29 20 75 73   ^No regexp() us
162e0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  er function is d
162f0 65 66 69 6e 65 64 20 62 79 20 64 65 66 61 75 6c  efined by defaul
16300 74 0a 61 6e 64 20 73 6f 20 75 73 65 20 6f 66 20  t.and so use of 
16310 74 68 65 20 52 45 47 45 58 50 20 6f 70 65 72 61  the REGEXP opera
16320 74 6f 72 20 77 69 6c 6c 20 6e 6f 72 6d 61 6c 6c  tor will normall
16330 79 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 0a 65  y result in an.e
16340 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
16350 49 66 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69  If an [applicati
16360 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
16370 75 6e 63 74 69 6f 6e 5d 20 6e 61 6d 65 64 20 22  unction] named "
16380 72 65 67 65 78 70 22 0a 69 73 20 61 64 64 65 64  regexp".is added
16390 20 61 74 20 72 75 6e 2d 74 69 6d 65 2c 20 74 68   at run-time, th
163a0 65 6e 20 74 68 65 20 22 3c 69 3e 58 3c 2f 69 3e  en the "<i>X</i>
163b0 20 52 45 47 45 58 50 20 3c 69 3e 59 3c 2f 69 3e   REGEXP <i>Y</i>
163c0 22 20 6f 70 65 72 61 74 6f 72 20 77 69 6c 6c 0a  " operator will.
163d0 62 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  be implemented a
163e0 73 20 61 20 63 61 6c 6c 20 74 6f 20 22 72 65 67  s a call to "reg
163f0 65 78 70 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69 3e  exp(<i>Y</i>,<i>
16400 58 3c 2f 69 3e 29 22 2e 3c 2f 70 3e 0a 0a 3c 74  X</i>)".</p>..<t
16410 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d  cl>hd_fragment m
16420 61 74 63 68 20 4d 41 54 43 48 3c 2f 74 63 6c 3e  atch MATCH</tcl>
16430 0a 3c 70 3e 5e 54 68 65 20 4d 41 54 43 48 20 6f  .<p>^The MATCH o
16440 70 65 72 61 74 6f 72 20 69 73 20 61 20 73 70 65  perator is a spe
16450 63 69 61 6c 20 73 79 6e 74 61 78 20 66 6f 72 20  cial syntax for 
16460 74 68 65 20 6d 61 74 63 68 28 29 0a 61 70 70 6c  the match().appl
16470 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16480 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 54 68 65 20  function.  ^The 
16490 64 65 66 61 75 6c 74 20 6d 61 74 63 68 28 29 20  default match() 
164a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
164b0 6e 74 61 74 69 6f 6e 0a 72 61 69 73 65 73 20 61  ntation.raises a
164c0 6e 20 65 78 63 65 70 74 69 6f 6e 20 61 6e 64 20  n exception and 
164d0 69 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  is not really us
164e0 65 66 75 6c 20 66 6f 72 20 61 6e 79 74 68 69 6e  eful for anythin
164f0 67 2e 0a 5e 42 75 74 20 65 78 74 65 6e 73 69 6f  g..^But extensio
16500 6e 73 20 63 61 6e 20 6f 76 65 72 72 69 64 65 20  ns can override 
16510 74 68 65 20 6d 61 74 63 68 28 29 20 66 75 6e 63  the match() func
16520 74 69 6f 6e 20 77 69 74 68 20 6d 6f 72 65 0a 68  tion with more.h
16530 65 6c 70 66 75 6c 20 6c 6f 67 69 63 2e 3c 2f 70  elpful logic.</p
16540 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
16550 65 6e 74 20 62 65 74 77 65 65 6e 20 42 45 54 57  ent between BETW
16560 45 45 4e 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68  EEN</tcl>.<h3>Th
16570 65 20 42 45 54 57 45 45 4e 20 6f 70 65 72 61 74  e BETWEEN operat
16580 6f 72 3c 2f 68 33 3e 0a 3c 70 3e 5e 28 54 68 65  or</h3>.<p>^(The
16590 20 42 45 54 57 45 45 4e 20 6f 70 65 72 61 74 6f   BETWEEN operato
165a0 72 20 69 73 20 6c 6f 67 69 63 61 6c 6c 79 20 65  r is logically e
165b0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 70  quivalent to a p
165c0 61 69 72 20 6f 66 20 63 6f 6d 70 61 72 69 73 6f  air of compariso
165d0 6e 73 2e 0a 22 3c 69 3e 78 3c 2f 69 3e 20 3c 62  ns.."<i>x</i> <b
165e0 3e 42 45 54 57 45 45 4e 3c 2f 62 3e 20 3c 69 3e  >BETWEEN</b> <i>
165f0 79 3c 2f 69 3e 20 3c 62 3e 41 4e 44 3c 2f 62 3e  y</i> <b>AND</b>
16600 20 3c 69 3e 7a 3c 2f 69 3e 22 20 69 73 20 0a 65   <i>z</i>" is .e
16610 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 0a 22 3c  quivalent to ."<
16620 69 3e 78 3c 2f 69 3e 3c 62 3e 26 67 74 3b 3d 3c  i>x</i><b>&gt;=<
16630 2f 62 3e 3c 69 3e 79 3c 2f 69 3e 20 3c 62 3e 41  /b><i>y</i> <b>A
16640 4e 44 3c 2f 62 3e 20 3c 69 3e 78 3c 2f 69 3e 3c  ND</b> <i>x</i><
16650 62 3e 26 6c 74 3b 3d 3c 2f 62 3e 3c 69 3e 7a 3c  b>&lt;=</b><i>z<
16660 2f 69 3e 22 20 65 78 63 65 70 74 0a 74 68 61 74  /i>" except.that
16670 20 77 69 74 68 20 42 45 54 57 45 45 4e 2c 20 74   with BETWEEN, t
16680 68 65 20 3c 69 3e 78 3c 2f 69 3e 20 65 78 70 72  he <i>x</i> expr
16690 65 73 73 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 65  ession is only e
166a0 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 2e 29 5e  valuated once.)^
166b0 0a 5e 54 68 65 20 70 72 65 63 65 64 65 6e 63 65  .^The precedence
166c0 20 6f 66 20 74 68 65 20 42 45 54 57 45 45 4e 20   of the BETWEEN 
166d0 6f 70 65 72 61 74 6f 72 20 69 73 20 74 68 65 20  operator is the 
166e0 73 61 6d 65 20 61 73 20 74 68 65 20 70 72 65 63  same as the prec
166f0 65 64 65 6e 63 65 0a 61 73 20 6f 70 65 72 61 74  edence.as operat
16700 6f 72 73 20 3c 62 3e 3d 3d 3c 2f 62 3e 20 61 6e  ors <b>==</b> an
16710 64 20 3c 62 3e 21 3d 3c 2f 62 3e 20 61 6e 64 20  d <b>!=</b> and 
16720 3c 62 3e 4c 49 4b 45 3c 2f 62 3e 20 61 6e 64 20  <b>LIKE</b> and 
16730 67 72 6f 75 70 73 20 6c 65 66 74 20 74 6f 20 72  groups left to r
16740 69 67 68 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  ight...<tcl>hd_f
16750 72 61 67 6d 65 6e 74 20 63 61 73 65 20 7b 43 41  ragment case {CA
16760 53 45 20 65 78 70 72 65 73 73 69 6f 6e 7d 3c 2f  SE expression}</
16770 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 43 41 53  tcl>.<h3>The CAS
16780 45 20 65 78 70 72 65 73 73 69 6f 6e 3c 2f 68 33  E expression</h3
16790 3e 0a 3c 70 3e 41 20 43 41 53 45 20 65 78 70 72  >.<p>A CASE expr
167a0 65 73 73 69 6f 6e 20 73 65 72 76 65 73 20 61 20  ession serves a 
167b0 72 6f 6c 65 20 73 69 6d 69 6c 61 72 20 74 6f 20  role similar to 
167c0 49 46 2d 54 48 45 4e 2d 45 4c 53 45 20 69 6e 20  IF-THEN-ELSE in 
167d0 6f 74 68 65 72 0a 70 72 6f 67 72 61 6d 6d 69 6e  other.programmin
167e0 67 20 6c 61 6e 67 75 61 67 65 73 2e 20 20 0a 0a  g languages.  ..
167f0 3c 70 3e 54 68 65 20 6f 70 74 69 6f 6e 61 6c 20  <p>The optional 
16800 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20  expression that 
16810 6f 63 63 75 72 73 20 69 6e 20 62 65 74 77 65 65  occurs in betwee
16820 6e 20 74 68 65 20 43 41 53 45 20 6b 65 79 77 6f  n the CASE keywo
16830 72 64 20 61 6e 64 20 74 68 65 0a 66 69 72 73 74  rd and the.first
16840 20 57 48 45 4e 20 6b 65 79 77 6f 72 64 20 69 73   WHEN keyword is
16850 20 63 61 6c 6c 65 64 20 74 68 65 20 22 62 61 73   called the "bas
16860 65 22 20 65 78 70 72 65 73 73 69 6f 6e 2e 20 5e  e" expression. ^
16870 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 62 61  There are two ba
16880 73 69 63 20 66 6f 72 6d 73 0a 6f 66 20 74 68 65  sic forms.of the
16890 20 43 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e   CASE expression
168a0 3a 20 74 68 6f 73 65 20 77 69 74 68 20 61 20 62  : those with a b
168b0 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e 20 61  ase expression a
168c0 6e 64 20 74 68 6f 73 65 20 77 69 74 68 6f 75 74  nd those without
168d0 2e 0a 0a 3c 70 3e 5e 49 6e 20 61 20 43 41 53 45  ...<p>^In a CASE
168e0 20 77 69 74 68 6f 75 74 20 61 20 62 61 73 65 20   without a base 
168f0 65 78 70 72 65 73 73 69 6f 6e 2c 20 65 61 63 68  expression, each
16900 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
16910 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 61 6e   is evaluated.an
16920 64 20 74 68 65 20 72 65 73 75 6c 74 20 74 72 65  d the result tre
16930 61 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  ated as a boolea
16940 6e 2c 20 73 74 61 72 74 69 6e 67 20 77 69 74 68  n, starting with
16950 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 61 6e   the leftmost an
16960 64 20 63 6f 6e 74 69 6e 75 69 6e 67 0a 74 6f 20  d continuing.to 
16970 74 68 65 20 72 69 67 68 74 2e 20 5e 54 68 65 20  the right. ^The 
16980 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 43 41  result of the CA
16990 53 45 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  SE expression is
169a0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
169b0 6f 66 20 74 68 65 20 54 48 45 4e 0a 65 78 70 72  of the THEN.expr
169c0 65 73 73 69 6f 6e 20 74 68 61 74 20 63 6f 72 72  ession that corr
169d0 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20 66  esponds to the f
169e0 69 72 73 74 20 57 48 45 4e 20 65 78 70 72 65 73  irst WHEN expres
169f0 73 69 6f 6e 20 74 68 61 74 20 65 76 61 6c 75 61  sion that evalua
16a00 74 65 73 20 74 6f 0a 74 72 75 65 2e 20 5e 4f 72  tes to.true. ^Or
16a10 2c 20 69 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65  , if none of the
16a20 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
16a30 73 20 65 76 61 6c 75 61 74 65 20 74 6f 20 74 72  s evaluate to tr
16a40 75 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ue, the result o
16a50 66 0a 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  f.evaluating the
16a60 20 45 4c 53 45 20 65 78 70 72 65 73 73 69 6f 6e   ELSE expression
16a70 2c 20 69 66 20 61 6e 79 2e 20 5e 49 66 20 74 68  , if any. ^If th
16a80 65 72 65 20 69 73 20 6e 6f 20 45 4c 53 45 20 65  ere is no ELSE e
16a90 78 70 72 65 73 73 69 6f 6e 20 61 6e 64 0a 6e 6f  xpression and.no
16aa0 6e 65 20 6f 66 20 74 68 65 20 57 48 45 4e 20 65  ne of the WHEN e
16ab0 78 70 72 65 73 73 69 6f 6e 73 20 61 72 65 20 74  xpressions are t
16ac0 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 6f 76  rue, then the ov
16ad0 65 72 61 6c 6c 20 72 65 73 75 6c 74 20 69 73 20  erall result is 
16ae0 4e 55 4c 4c 2e 0a 0a 3c 70 3e 5e 41 20 4e 55 4c  NULL...<p>^A NUL
16af0 4c 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73  L result is cons
16b00 69 64 65 72 65 64 20 75 6e 74 72 75 65 20 77 68  idered untrue wh
16b10 65 6e 20 65 76 61 6c 75 61 74 69 6e 67 20 57 48  en evaluating WH
16b20 45 4e 20 74 65 72 6d 73 2e 0a 0a 3c 70 3e 5e 49  EN terms...<p>^I
16b30 6e 20 61 20 43 41 53 45 20 77 69 74 68 20 61 20  n a CASE with a 
16b40 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2c  base expression,
16b50 20 74 68 65 20 62 61 73 65 20 65 78 70 72 65 73   the base expres
16b60 73 69 6f 6e 20 69 73 20 65 76 61 6c 75 61 74 65  sion is evaluate
16b70 64 20 6a 75 73 74 0a 6f 6e 63 65 20 61 6e 64 20  d just.once and 
16b80 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 63 6f  the result is co
16b90 6d 70 61 72 65 64 20 61 67 61 69 6e 73 74 20 74  mpared against t
16ba0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
16bb0 20 65 61 63 68 20 57 48 45 4e 20 0a 65 78 70 72   each WHEN .expr
16bc0 65 73 73 69 6f 6e 20 66 72 6f 6d 20 6c 65 66 74  ession from left
16bd0 20 74 6f 20 72 69 67 68 74 2e 20 5e 54 68 65 20   to right. ^The 
16be0 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 43 41  result of the CA
16bf0 53 45 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  SE expression is
16c00 20 74 68 65 20 0a 65 76 61 6c 75 61 74 69 6f 6e   the .evaluation
16c10 20 6f 66 20 74 68 65 20 54 48 45 4e 20 65 78 70   of the THEN exp
16c20 72 65 73 73 69 6f 6e 20 74 68 61 74 20 63 6f 72  ression that cor
16c30 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20  responds to the 
16c40 66 69 72 73 74 20 57 48 45 4e 0a 65 78 70 72 65  first WHEN.expre
16c50 73 73 69 6f 6e 20 66 6f 72 20 77 68 69 63 68 20  ssion for which 
16c60 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 69  the comparison i
16c70 73 20 74 72 75 65 2e 20 5e 4f 72 2c 20 69 66 20  s true. ^Or, if 
16c80 6e 6f 6e 65 20 6f 66 20 74 68 65 20 57 48 45 4e  none of the WHEN
16c90 0a 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76 61  .expressions eva
16ca0 6c 75 61 74 65 20 74 6f 20 61 20 76 61 6c 75 65  luate to a value
16cb0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 62 61   equal to the ba
16cc0 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 74  se expression, t
16cd0 68 65 20 72 65 73 75 6c 74 0a 6f 66 20 65 76 61  he result.of eva
16ce0 6c 75 61 74 69 6e 67 20 74 68 65 20 45 4c 53 45  luating the ELSE
16cf0 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 66 20   expression, if 
16d00 61 6e 79 2e 20 5e 49 66 20 74 68 65 72 65 20 69  any. ^If there i
16d10 73 20 6e 6f 20 45 4c 53 45 20 65 78 70 72 65 73  s no ELSE expres
16d20 73 69 6f 6e 20 61 6e 64 0a 6e 6f 6e 65 20 6f 66  sion and.none of
16d30 20 74 68 65 20 57 48 45 4e 20 65 78 70 72 65 73   the WHEN expres
16d40 73 69 6f 6e 73 20 70 72 6f 64 75 63 65 20 61 20  sions produce a 
16d50 72 65 73 75 6c 74 20 65 71 75 61 6c 20 74 6f 20  result equal to 
16d60 74 68 65 20 62 61 73 65 20 65 78 70 72 65 73 73  the base express
16d70 69 6f 6e 2c 0a 74 68 65 20 6f 76 65 72 61 6c 6c  ion,.the overall
16d80 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2e   result is NULL.
16d90 0a 0a 3c 70 3e 5e 57 68 65 6e 20 63 6f 6d 70 61  ..<p>^When compa
16da0 72 69 6e 67 20 61 20 62 61 73 65 20 65 78 70 72  ring a base expr
16db0 65 73 73 69 6f 6e 20 61 67 61 69 6e 73 74 20 61  ession against a
16dc0 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
16dd0 2c 20 74 68 65 20 73 61 6d 65 0a 63 6f 6c 6c 61  , the same.colla
16de0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 61  ting sequence, a
16df0 66 66 69 6e 69 74 79 2c 20 61 6e 64 20 4e 55 4c  ffinity, and NUL
16e00 4c 2d 68 61 6e 64 6c 69 6e 67 20 72 75 6c 65 73  L-handling rules
16e10 20 61 70 70 6c 79 20 61 73 20 69 66 20 74 68 65   apply as if the
16e20 0a 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e  .base expression
16e30 20 61 6e 64 20 57 48 45 4e 20 65 78 70 72 65 73   and WHEN expres
16e40 73 69 6f 6e 20 61 72 65 20 72 65 73 70 65 63 74  sion are respect
16e50 69 76 65 6c 79 20 74 68 65 20 6c 65 66 74 2d 20  ively the left- 
16e60 61 6e 64 0a 72 69 67 68 74 2d 68 61 6e 64 20 6f  and.right-hand o
16e70 70 65 72 61 6e 64 73 20 6f 66 20 61 6e 20 3c 62  perands of an <b
16e80 69 67 3e 3c 62 3e 3d 3c 2f 62 3e 3c 2f 62 69 67  ig><b>=</b></big
16e90 3e 20 6f 70 65 72 61 74 6f 72 2e 3c 2f 70 3e 20  > operator.</p> 
16ea0 5e 49 66 20 74 68 65 20 62 61 73 65 20 0a 65 78  ^If the base .ex
16eb0 70 72 65 73 73 69 6f 6e 20 69 73 20 4e 55 4c 4c  pression is NULL
16ec0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
16ed0 20 6f 66 20 74 68 65 20 43 41 53 45 20 69 73 20   of the CASE is 
16ee0 61 6c 77 61 79 73 20 74 68 65 20 72 65 73 75 6c  always the resul
16ef0 74 20 0a 6f 66 20 65 76 61 6c 75 61 74 69 6e 67  t .of evaluating
16f00 20 74 68 65 20 45 4c 53 45 20 65 78 70 72 65 73   the ELSE expres
16f10 73 69 6f 6e 20 69 66 20 69 74 20 65 78 69 73 74  sion if it exist
16f20 73 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 74  s, or NULL if it
16f30 20 64 6f 65 73 20 6e 6f 74 2e 0a 0a 3c 70 3e 5e   does not...<p>^
16f40 42 6f 74 68 20 66 6f 72 6d 73 20 6f 66 20 74 68  Both forms of th
16f50 65 20 43 41 53 45 20 65 78 70 72 65 73 73 69 6f  e CASE expressio
16f60 6e 20 75 73 65 20 6c 61 7a 79 2c 20 6f 72 20 73  n use lazy, or s
16f70 68 6f 72 74 2d 63 69 72 63 75 69 74 2c 20 0a 65  hort-circuit, .e
16f80 76 61 6c 75 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 5e  valuation...<p>^
16f90 28 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72  (The only differ
16fa0 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  ence between the
16fb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 43   following two C
16fc0 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e 73 20  ASE expressions 
16fd0 69 73 20 74 68 61 74 20 0a 74 68 65 20 3c 69 3e  is that .the <i>
16fe0 78 3c 2f 69 3e 20 65 78 70 72 65 73 73 69 6f 6e  x</i> expression
16ff0 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 65 78   is evaluated ex
17000 61 63 74 6c 79 20 6f 6e 63 65 20 69 6e 20 74 68  actly once in th
17010 65 20 66 69 72 73 74 20 65 78 61 6d 70 6c 65 20  e first example 
17020 62 75 74 20 0a 6d 69 67 68 74 20 62 65 20 65 76  but .might be ev
17030 61 6c 75 61 74 65 64 20 6d 75 6c 74 69 70 6c 65  aluated multiple
17040 20 74 69 6d 65 73 20 69 6e 20 74 68 65 20 73 65   times in the se
17050 63 6f 6e 64 3a 0a 0a 3c 75 6c 3e 3c 70 72 65 3e  cond:..<ul><pre>
17060 0a 3c 6c 69 3e 43 41 53 45 20 78 20 57 48 45 4e  .<li>CASE x WHEN
17070 20 77 31 20 54 48 45 4e 20 72 31 20 57 48 45 4e   w1 THEN r1 WHEN
17080 20 77 32 20 54 48 45 4e 20 72 32 20 45 4c 53 45   w2 THEN r2 ELSE
17090 20 72 33 20 45 4e 44 0a 3c 6c 69 3e 43 41 53 45   r3 END.<li>CASE
170a0 20 57 48 45 4e 20 78 3d 77 31 20 54 48 45 4e 20   WHEN x=w1 THEN 
170b0 72 31 20 57 48 45 4e 20 78 3d 77 32 20 54 48 45  r1 WHEN x=w2 THE
170c0 4e 20 72 32 20 45 4c 53 45 20 72 33 20 45 4e 44  N r2 ELSE r3 END
170d0 0a 3c 2f 70 72 65 3e 3c 2f 75 6c 3e 29 5e 0a 0a  .</pre></ul>)^..
170e0 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
170f0 74 20 69 6e 5f 6f 70 20 7b 49 4e 20 6f 70 65 72  t in_op {IN oper
17100 61 74 6f 72 7d 20 7b 4e 4f 54 20 49 4e 20 6f 70  ator} {NOT IN op
17110 65 72 61 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68  erator}</tcl>.<h
17120 33 3e 54 68 65 20 49 4e 20 61 6e 64 20 4e 4f 54  3>The IN and NOT
17130 20 49 4e 20 6f 70 65 72 61 74 6f 72 73 3c 2f 68   IN operators</h
17140 33 3e 0a 3c 70 3e 5e 54 68 65 20 49 4e 20 61 6e  3>.<p>^The IN an
17150 64 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74 6f  d NOT IN operato
17160 72 73 20 74 61 6b 65 20 61 6e 20 65 78 70 72 65  rs take an expre
17170 73 73 69 6f 6e 20 6f 6e 20 74 68 65 0a 6c 65 66  ssion on the.lef
17180 74 20 61 6e 64 20 61 20 6c 69 73 74 20 6f 66 20  t and a list of 
17190 76 61 6c 75 65 73 20 6f 72 20 61 20 73 75 62 71  values or a subq
171a0 75 65 72 79 20 6f 6e 20 74 68 65 20 72 69 67 68  uery on the righ
171b0 74 2e 0a 5e 57 68 65 6e 20 74 68 65 20 72 69 67  t..^When the rig
171c0 68 74 20 6f 70 65 72 61 6e 64 20 6f 66 20 61 6e  ht operand of an
171d0 20 49 4e 20 6f 72 20 4e 4f 54 20 49 4e 20 6f 70   IN or NOT IN op
171e0 65 72 61 74 6f 72 20 69 73 20 61 20 73 75 62 71  erator is a subq
171f0 75 65 72 79 2c 20 74 68 65 0a 73 75 62 71 75 65  uery, the.subque
17200 72 79 20 6d 75 73 74 20 68 61 76 65 20 74 68 65  ry must have the
17210 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20   same number of 
17220 63 6f 6c 75 6d 6e 73 20 61 73 20 74 68 65 72 65  columns as there
17230 20 61 72 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 0a   are columns in.
17240 74 68 65 20 5b 72 6f 77 20 76 61 6c 75 65 5d 20  the [row value] 
17250 6f 66 20 74 68 65 20 6c 65 66 74 20 6f 70 65 72  of the left oper
17260 61 6e 64 2e 20 20 5e 54 68 65 20 73 75 62 71 75  and.  ^The subqu
17270 65 72 79 20 6f 6e 20 74 68 65 0a 72 69 67 68 74  ery on the.right
17280 20 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f 54   of an IN or NOT
17290 20 49 4e 20 6f 70 65 72 61 74 6f 72 20 6d 75 73   IN operator mus
172a0 74 20 62 65 20 61 20 73 63 61 6c 61 72 20 73 75  t be a scalar su
172b0 62 71 75 65 72 79 20 69 66 20 74 68 65 20 6c 65  bquery if the le
172c0 66 74 0a 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ft.expression is
172d0 20 6e 6f 74 20 61 20 5b 72 6f 77 20 76 61 6c 75   not a [row valu
172e0 65 5d 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 5e  e] expression..^
172f0 49 66 20 74 68 65 20 72 69 67 68 74 20 6f 70 65  If the right ope
17300 72 61 6e 64 20 6f 66 20 61 6e 20 49 4e 20 6f 72  rand of an IN or
17310 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74 6f 72   NOT IN operator
17320 20 69 73 20 61 20 6c 69 73 74 20 6f 66 20 76 61   is a list of va
17330 6c 75 65 73 2c 0a 65 61 63 68 20 6f 66 20 74 68  lues,.each of th
17340 6f 73 65 20 76 61 6c 75 65 73 20 6d 75 73 74 20  ose values must 
17350 62 65 20 73 63 61 6c 61 72 73 20 61 6e 64 20 74  be scalars and t
17360 68 65 20 6c 65 66 74 20 65 78 70 72 65 73 73 69  he left expressi
17370 6f 6e 20 6d 75 73 74 20 61 6c 73 6f 0a 62 65 20  on must also.be 
17380 61 20 73 63 61 6c 61 72 2e 0a 5e 54 68 65 20 72  a scalar..^The r
17390 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
173a0 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f 54 20 49  f an IN or NOT I
173b0 4e 20 6f 70 65 72 61 74 6f 72 20 63 61 6e 20 62  N operator can b
173c0 65 20 61 0a 74 61 62 6c 65 20 3c 69 3e 6e 61 6d  e a.table <i>nam
173d0 65 3c 2f 69 3e 20 6f 72 20 5b 74 61 62 6c 65 2d  e</i> or [table-
173e0 76 61 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 5d  valued function]
173f0 20 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 69 6e 20   <i>name</i> in 
17400 77 68 69 63 68 20 0a 63 61 73 65 20 74 68 65 20  which .case the 
17410 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
17420 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 74 6f  is understood to
17430 20 62 65 20 73 75 62 71 75 65 72 79 20 6f 66 0a   be subquery of.
17440 74 68 65 20 66 6f 72 6d 20 22 28 53 45 4c 45 43  the form "(SELEC
17450 54 20 2a 20 46 52 4f 4d 20 3c 69 3e 6e 61 6d 65  T * FROM <i>name
17460 3c 2f 69 3e 29 22 2e 0a 5e 57 68 65 6e 20 74 68  </i>)"..^When th
17470 65 20 72 69 67 68 74 20 6f 70 65 72 61 6e 64 20  e right operand 
17480 69 73 20 61 6e 20 65 6d 70 74 79 20 73 65 74 2c  is an empty set,
17490 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 49   the result of I
174a0 4e 20 69 73 20 66 61 6c 73 65 20 61 6e 64 20 74  N is false and t
174b0 68 65 0a 72 65 73 75 6c 74 20 6f 66 20 4e 4f 54  he.result of NOT
174c0 20 49 4e 20 69 73 20 74 72 75 65 2c 20 72 65 67   IN is true, reg
174d0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c  ardless of the l
174e0 65 66 74 20 6f 70 65 72 61 6e 64 20 61 6e 64 20  eft operand and 
174f0 65 76 65 6e 20 69 66 20 74 68 65 0a 6c 65 66 74  even if the.left
17500 20 6f 70 65 72 61 6e 64 20 69 73 20 4e 55 4c 4c   operand is NULL
17510 2e 0a 3c 70 3e 5e 28 54 68 65 20 72 65 73 75 6c  ..<p>^(The resul
17520 74 20 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f  t of an IN or NO
17530 54 20 49 4e 20 6f 70 65 72 61 74 6f 72 20 69 73  T IN operator is
17540 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
17550 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 6d 61 74  he following.mat
17560 72 69 78 3a 0a 0a 3c 63 65 6e 74 65 72 3e 0a 3c  rix:..<center>.<
17570 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 3e 0a  table border=1>.
17580 3c 74 72 3e 0a 3c 74 68 3e 4c 65 66 74 20 6f 70  <tr>.<th>Left op
17590 65 72 61 6e 64 20 3c 62 72 3e 69 73 20 4e 55 4c  erand <br>is NUL
175a0 4c 0a 3c 74 68 3e 52 69 67 68 74 20 6f 70 65 72  L.<th>Right oper
175b0 61 6e 64 20 3c 62 72 3e 63 6f 6e 74 61 69 6e 73  and <br>contains
175c0 20 4e 55 4c 4c 0a 3c 74 68 3e 52 69 67 68 74 20   NULL.<th>Right 
175d0 6f 70 65 72 61 6e 64 20 3c 62 72 3e 69 73 20 61  operand <br>is a
175e0 6e 20 65 6d 70 74 79 20 73 65 74 0a 3c 74 68 3e  n empty set.<th>
175f0 4c 65 66 74 20 6f 70 65 72 61 6e 64 20 66 6f 75  Left operand fou
17600 6e 64 20 3c 62 72 3e 77 69 74 68 69 6e 20 72 69  nd <br>within ri
17610 67 68 74 20 6f 70 65 72 61 6e 64 0a 3c 74 68 3e  ght operand.<th>
17620 52 65 73 75 6c 74 20 6f 66 20 3c 62 72 3e 49 4e  Result of <br>IN
17630 20 6f 70 65 72 61 74 6f 72 0a 3c 74 68 3e 52 65   operator.<th>Re
17640 73 75 6c 74 20 6f 66 20 3c 62 72 3e 4e 4f 54 20  sult of <br>NOT 
17650 49 4e 20 6f 70 65 72 61 74 6f 72 0a 3c 74 72 3e  IN operator.<tr>
17660 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
17670 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e  er">no.<td align
17680 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64  ="center">no.<td
17690 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
176a0 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65  no.<td align="ce
176b0 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69  nter">no.<td ali
176c0 67 6e 3d 22 63 65 6e 74 65 72 22 3e 66 61 6c 73  gn="center">fals
176d0 65 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e  e.<td align="cen
176e0 74 65 72 22 3e 74 72 75 65 0a 3c 74 72 3e 0a 3c  ter">true.<tr>.<
176f0 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
17700 22 3e 64 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65  ">does not matte
17710 72 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e  r.<td align="cen
17720 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67  ter">no.<td alig
17730 6e 3d 22 63 65 6e 74 65 72 22 3e 79 65 73 0a 3c  n="center">yes.<
17740 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
17750 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  ">no.<td align="
17760 63 65 6e 74 65 72 22 3e 66 61 6c 73 65 0a 3c 74  center">false.<t
17770 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22  d align="center"
17780 3e 74 72 75 65 0a 3c 74 72 3e 0a 3c 74 64 20 61  >true.<tr>.<td a
17790 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f  lign="center">no
177a0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
177b0 65 72 22 3e 64 6f 65 73 20 6e 6f 74 20 6d 61 74  er">does not mat
177c0 74 65 72 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  ter.<td align="c
177d0 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c  enter">no.<td al
177e0 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 79 65 73  ign="center">yes
177f0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
17800 65 72 22 3e 74 72 75 65 0a 3c 74 64 20 61 6c 69  er">true.<td ali
17810 67 6e 3d 22 63 65 6e 74 65 72 22 3e 66 61 6c 73  gn="center">fals
17820 65 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e  e.<tr>.<td align
17830 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64  ="center">no.<td
17840 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
17850 79 65 73 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  yes.<td align="c
17860 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c  enter">no.<td al
17870 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a  ign="center">no.
17880 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
17890 72 22 3e 4e 55 4c 4c 0a 3c 74 64 20 61 6c 69 67  r">NULL.<td alig
178a0 6e 3d 22 63 65 6e 74 65 72 22 3e 4e 55 4c 4c 0a  n="center">NULL.
178b0 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  <tr>.<td align="
178c0 63 65 6e 74 65 72 22 3e 79 65 73 0a 3c 74 64 20  center">yes.<td 
178d0 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 64  align="center">d
178e0 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 0a 3c  oes not matter.<
178f0 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
17900 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  ">no.<td align="
17910 63 65 6e 74 65 72 22 3e 64 6f 65 73 20 6e 6f 74  center">does not
17920 20 6d 61 74 74 65 72 0a 3c 74 64 20 61 6c 69 67   matter.<td alig
17930 6e 3d 22 63 65 6e 74 65 72 22 3e 4e 55 4c 4c 0a  n="center">NULL.
17940 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
17950 72 22 3e 4e 55 4c 4c 0a 3c 2f 74 61 62 6c 65 3e  r">NULL.</table>
17960 0a 3c 2f 63 65 6e 74 65 72 3e 29 5e 0a 0a 3c 70  .</center>)^..<p
17970 3e 5e 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  >^Note that SQLi
17980 74 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 70 61  te allows the pa
17990 72 65 6e 74 68 65 73 69 7a 65 64 20 6c 69 73 74  renthesized list
179a0 20 6f 66 20 73 63 61 6c 61 72 20 76 61 6c 75 65   of scalar value
179b0 73 20 6f 6e 0a 74 68 65 20 72 69 67 68 74 2d 68  s on.the right-h
179c0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 6e 20 49  and side of an I
179d0 4e 20 6f 72 20 4e 4f 54 20 49 4e 20 6f 70 65 72  N or NOT IN oper
179e0 61 74 6f 72 20 74 6f 20 62 65 20 61 6e 20 65 6d  ator to be an em
179f0 70 74 79 20 6c 69 73 74 20 62 75 74 0a 6d 6f 73  pty list but.mos
17a00 74 20 6f 74 68 65 72 20 53 51 4c 20 64 61 74 61  t other SQL data
17a10 62 61 73 65 20 64 61 74 61 62 61 73 65 20 65 6e  base database en
17a20 67 69 6e 65 73 20 61 6e 64 20 74 68 65 20 53 51  gines and the SQ
17a30 4c 39 32 20 73 74 61 6e 64 61 72 64 20 72 65 71  L92 standard req
17a40 75 69 72 65 0a 74 68 65 20 6c 69 73 74 20 74 6f  uire.the list to
17a50 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61 73   contain at leas
17a60 74 20 6f 6e 65 20 65 6c 65 6d 65 6e 74 2e 3c 2f  t one element.</
17a70 70 3e 0a 0a 3c 68 33 3e 54 61 62 6c 65 20 43 6f  p>..<h3>Table Co
17a80 6c 75 6d 6e 20 4e 61 6d 65 73 3c 2f 68 33 3e 0a  lumn Names</h3>.
17a90 0a 3c 70 3e 5e 41 20 63 6f 6c 75 6d 6e 20 6e 61  .<p>^A column na
17aa0 6d 65 20 63 61 6e 20 62 65 20 61 6e 79 20 6f 66  me can be any of
17ab0 20 74 68 65 20 6e 61 6d 65 73 20 64 65 66 69 6e   the names defin
17ac0 65 64 20 69 6e 20 74 68 65 20 5b 43 52 45 41 54  ed in the [CREAT
17ad0 45 20 54 41 42 4c 45 5d 0a 73 74 61 74 65 6d 65  E TABLE].stateme
17ae0 6e 74 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  nt or one of the
17af0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 70 65 63 69   following speci
17b00 61 6c 20 69 64 65 6e 74 69 66 69 65 72 73 3a 20  al identifiers: 
17b10 22 3c 62 3e 52 4f 57 49 44 3c 2f 62 3e 22 2c 0a  "<b>ROWID</b>",.
17b20 22 3c 62 3e 4f 49 44 3c 2f 62 3e 22 2c 20 6f 72  "<b>OID</b>", or
17b30 20 22 3c 62 3e 5f 52 4f 57 49 44 5f 3c 2f 62 3e   "<b>_ROWID_</b>
17b40 22 2e 0a 5e 54 68 65 20 74 68 72 65 65 20 73 70  "..^The three sp
17b50 65 63 69 61 6c 20 69 64 65 6e 74 69 66 69 65 72  ecial identifier
17b60 73 20 64 65 73 63 72 69 62 65 20 74 68 65 0a 75  s describe the.u
17b70 6e 69 71 75 65 20 69 6e 74 65 67 65 72 20 6b 65  nique integer ke
17b80 79 20 28 74 68 65 20 5b 72 6f 77 69 64 5d 29 20  y (the [rowid]) 
17b90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
17ba0 65 76 65 72 79 20 0a 72 6f 77 20 6f 66 20 65 76  every .row of ev
17bb0 65 72 79 20 74 61 62 6c 65 20 61 6e 64 20 73 6f  ery table and so
17bc0 20 61 72 65 20 6e 6f 74 20 61 76 61 69 6c 61 62   are not availab
17bd0 6c 65 20 6f 6e 20 5b 57 49 54 48 4f 55 54 20 52  le on [WITHOUT R
17be0 4f 57 49 44 5d 20 74 61 62 6c 65 73 2e 0a 5e 54  OWID] tables..^T
17bf0 68 65 20 73 70 65 63 69 61 6c 20 69 64 65 6e 74  he special ident
17c00 69 66 69 65 72 73 20 6f 6e 6c 79 20 72 65 66 65  ifiers only refe
17c10 72 20 74 6f 20 74 68 65 20 72 6f 77 20 6b 65 79  r to the row key
17c20 20 69 66 20 74 68 65 20 5b 43 52 45 41 54 45 20   if the [CREATE 
17c30 54 41 42 4c 45 5d 0a 73 74 61 74 65 6d 65 6e 74  TABLE].statement
17c40 20 64 6f 65 73 20 6e 6f 74 20 64 65 66 69 6e 65   does not define
17c50 20 61 20 72 65 61 6c 20 63 6f 6c 75 6d 6e 20 77   a real column w
17c60 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
17c70 65 2e 0a 5e 54 68 65 20 72 6f 77 69 64 20 63 61  e..^The rowid ca
17c80 6e 20 62 65 20 75 73 65 64 20 61 6e 79 77 68 65  n be used anywhe
17c90 72 65 20 61 20 72 65 67 75 6c 61 72 0a 63 6f 6c  re a regular.col
17ca0 75 6d 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2e  umn can be used.
17cb0 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
17cc0 61 67 6d 65 6e 74 20 69 6e 5f 6f 70 20 7b 45 58  agment in_op {EX
17cd0 49 53 54 53 20 6f 70 65 72 61 74 6f 72 7d 20 7b  ISTS operator} {
17ce0 4e 4f 54 20 45 58 49 53 54 53 20 6f 70 65 72 61  NOT EXISTS opera
17cf0 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54  tor}</tcl>.<h3>T
17d00 68 65 20 45 58 49 53 54 53 20 6f 70 65 72 61 74  he EXISTS operat
17d10 6f 72 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65  or</h3>..<p>^The
17d20 20 45 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72   EXISTS operator
17d30 20 61 6c 77 61 79 73 20 65 76 61 6c 75 61 74 65   always evaluate
17d40 73 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20  s to one of the 
17d50 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 30  integer values 0
17d60 20 0a 61 6e 64 20 31 2e 20 5e 49 66 20 65 78 65   .and 1. ^If exe
17d70 63 75 74 69 6e 67 20 74 68 65 20 53 45 4c 45 43  cuting the SELEC
17d80 54 20 73 74 61 74 65 6d 65 6e 74 20 73 70 65 63  T statement spec
17d90 69 66 69 65 64 20 61 73 20 74 68 65 20 72 69 67  ified as the rig
17da0 68 74 2d 68 61 6e 64 20 0a 6f 70 65 72 61 6e 64  ht-hand .operand
17db0 20 6f 66 20 74 68 65 20 45 58 49 53 54 53 20 6f   of the EXISTS o
17dc0 70 65 72 61 74 6f 72 20 77 6f 75 6c 64 20 72 65  perator would re
17dd0 74 75 72 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  turn one or more
17de0 20 72 6f 77 73 2c 20 74 68 65 6e 20 74 68 65 0a   rows, then the.
17df0 45 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72 20  EXISTS operator 
17e00 65 76 61 6c 75 61 74 65 73 20 74 6f 20 31 2e 20  evaluates to 1. 
17e10 5e 49 66 20 65 78 65 63 75 74 69 6e 67 20 74 68  ^If executing th
17e20 65 20 53 45 4c 45 43 54 20 77 6f 75 6c 64 20 72  e SELECT would r
17e30 65 74 75 72 6e 0a 6e 6f 20 72 6f 77 73 20 61 74  eturn.no rows at
17e40 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 45   all, then the E
17e50 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72 20 65  XISTS operator e
17e60 76 61 6c 75 61 74 65 73 20 74 6f 20 30 2e 20 0a  valuates to 0. .
17e70 0a 3c 70 3e 5e 54 68 65 20 6e 75 6d 62 65 72 20  .<p>^The number 
17e80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 65 61  of columns in ea
17e90 63 68 20 72 6f 77 20 72 65 74 75 72 6e 65 64 20  ch row returned 
17ea0 62 79 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  by the SELECT st
17eb0 61 74 65 6d 65 6e 74 0a 28 69 66 20 61 6e 79 29  atement.(if any)
17ec0 20 61 6e 64 20 74 68 65 20 73 70 65 63 69 66 69   and the specifi
17ed0 63 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  c values returne
17ee0 64 20 68 61 76 65 20 6e 6f 20 65 66 66 65 63 74  d have no effect
17ef0 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 73 0a   on the results.
17f00 6f 66 20 74 68 65 20 45 58 49 53 54 53 20 6f 70  of the EXISTS op
17f10 65 72 61 74 6f 72 2e 20 5e 49 6e 20 70 61 72 74  erator. ^In part
17f20 69 63 75 6c 61 72 2c 20 72 6f 77 73 20 63 6f 6e  icular, rows con
17f30 74 61 69 6e 69 6e 67 20 4e 55 4c 4c 20 76 61 6c  taining NULL val
17f40 75 65 73 20 61 72 65 0a 6e 6f 74 20 68 61 6e 64  ues are.not hand
17f50 6c 65 64 20 61 6e 79 20 64 69 66 66 65 72 65 6e  led any differen
17f60 74 6c 79 20 66 72 6f 6d 20 72 6f 77 73 20 77 69  tly from rows wi
17f70 74 68 6f 75 74 20 4e 55 4c 4c 20 76 61 6c 75 65  thout NULL value
17f80 73 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  s...<tcl>hd_frag
17f90 6d 65 6e 74 20 73 75 62 71 20 7b 53 75 62 71 75  ment subq {Subqu
17fa0 65 72 69 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33  eries}</tcl>.<h3
17fb0 3e 53 75 62 71 75 65 72 79 20 45 78 70 72 65 73  >Subquery Expres
17fc0 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e  sions</h3>..<p>^
17fd0 41 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  A [SELECT] state
17fe0 6d 65 6e 74 20 65 6e 63 6c 6f 73 65 64 20 69 6e  ment enclosed in
17ff0 20 70 61 72 65 6e 74 68 65 73 65 73 20 69 73 20   parentheses is 
18000 61 20 73 75 62 71 75 65 72 79 2e 0a 5e 41 6c 6c  a subquery..^All
18010 20 74 79 70 65 73 20 6f 66 20 53 45 4c 45 43 54   types of SELECT
18020 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 63 6c   statement, incl
18030 75 64 69 6e 67 0a 61 67 67 72 65 67 61 74 65 20  uding.aggregate 
18040 61 6e 64 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  and compound SEL
18050 45 43 54 20 71 75 65 72 69 65 73 20 28 71 75 65  ECT queries (que
18060 72 69 65 73 20 77 69 74 68 20 6b 65 79 77 6f 72  ries with keywor
18070 64 73 20 6c 69 6b 65 0a 55 4e 49 4f 4e 20 6f 72  ds like.UNION or
18080 20 45 58 43 45 50 54 29 20 61 72 65 20 61 6c 6c   EXCEPT) are all
18090 6f 77 65 64 20 61 73 20 73 63 61 6c 61 72 20 73  owed as scalar s
180a0 75 62 71 75 65 72 69 65 73 2e 0a 5e 54 68 65 20  ubqueries..^The 
180b0 76 61 6c 75 65 20 6f 66 20 61 20 73 75 62 71 75  value of a subqu
180c0 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ery expression i
180d0 73 20 74 68 65 20 66 69 72 73 74 20 72 6f 77 20  s the first row 
180e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 66 72  of the result.fr
180f0 6f 6d 20 74 68 65 20 65 6e 63 6c 6f 73 65 64 20  om the enclosed 
18100 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
18110 6e 74 2e 0a 5e 49 6e 20 6f 74 68 65 72 20 77 6f  nt..^In other wo
18120 72 64 73 2c 20 61 6e 20 69 6d 70 6c 69 65 64 20  rds, an implied 
18130 22 4c 49 4d 49 54 20 31 22 20 69 73 20 61 64 64  "LIMIT 1" is add
18140 65 64 20 74 6f 20 74 68 65 20 73 75 62 71 75 65  ed to the subque
18150 72 79 2c 20 6f 76 65 72 72 69 64 69 6e 67 0a 61  ry, overriding.a
18160 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 63 6f 64  n explicitly cod
18170 65 64 20 4c 49 4d 49 54 2e 0a 5e 54 68 65 20 76  ed LIMIT..^The v
18180 61 6c 75 65 20 6f 66 20 61 20 73 75 62 71 75 65  alue of a subque
18190 72 79 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ry expression is
181a0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 65 6e 63   NULL if the enc
181b0 6c 6f 73 65 64 0a 5b 53 45 4c 45 43 54 5d 20 73  losed.[SELECT] s
181c0 74 61 74 65 6d 65 6e 74 20 72 65 74 75 72 6e 73  tatement returns
181d0 20 6e 6f 20 72 6f 77 73 2e 0a 0a 3c 70 3e 41 20   no rows...<p>A 
181e0 73 75 62 71 75 65 72 79 20 74 68 61 74 20 72 65  subquery that re
181f0 74 75 72 6e 73 20 61 20 73 69 6e 67 6c 65 20 63  turns a single c
18200 6f 6c 75 6d 6e 20 69 73 20 61 20 73 63 61 6c 61  olumn is a scala
18210 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 63  r subquery and c
18220 61 6e 0a 62 65 20 75 73 65 64 20 6d 6f 73 74 20  an.be used most 
18230 61 6e 79 77 68 65 72 65 2e 0a 5e 41 20 73 75 62  anywhere..^A sub
18240 71 75 65 72 79 20 74 68 61 74 20 72 65 74 75 72  query that retur
18250 6e 73 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  ns two or more c
18260 6f 6c 75 6d 6e 73 20 69 73 20 61 20 5b 72 6f 77  olumns is a [row
18270 20 76 61 6c 75 65 5d 0a 73 75 62 71 75 65 72 79   value].subquery
18280 20 61 6e 64 20 63 61 6e 20 6f 6e 6c 79 20 62 65   and can only be
18290 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 70 65   used as the ope
182a0 72 61 6e 64 20 6f 66 20 61 20 63 6f 6d 70 61 72  rand of a compar
182b0 69 73 6f 6e 20 6f 70 65 72 61 74 6f 72 2e 0a 0a  ison operator...
182c0 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
182d0 20 63 6f 73 75 62 20 7b 63 6f 72 72 65 6c 61 74   cosub {correlat
182e0 65 64 20 73 75 62 71 75 65 72 69 65 73 7d 3c 2f  ed subqueries}</
182f0 74 63 6c 3e 0a 3c 68 33 3e 43 6f 72 72 65 6c 61  tcl>.<h3>Correla
18300 74 65 64 20 53 75 62 71 75 65 72 69 65 73 3c 2f  ted Subqueries</
18310 68 33 3e 0a 0a 3c 70 3e 5e 41 20 5b 53 45 4c 45  h3>..<p>^A [SELE
18320 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 75 73  CT] statement us
18330 65 64 20 61 73 20 65 69 74 68 65 72 20 61 20 73  ed as either a s
18340 63 61 6c 61 72 20 73 75 62 71 75 65 72 79 20 6f  calar subquery o
18350 72 20 61 73 20 74 68 65 20 0a 72 69 67 68 74 2d  r as the .right-
18360 68 61 6e 64 20 6f 70 65 72 61 6e 64 20 6f 66 20  hand operand of 
18370 61 6e 20 49 4e 2c 20 4e 4f 54 20 49 4e 20 6f 72  an IN, NOT IN or
18380 20 45 58 49 53 54 53 20 65 78 70 72 65 73 73 69   EXISTS expressi
18390 6f 6e 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 0a  on may contain .
183a0 72 65 66 65 72 65 6e 63 65 73 20 74 6f 20 63 6f  references to co
183b0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 6f 75 74  lumns in the out
183c0 65 72 20 71 75 65 72 79 2e 20 53 75 63 68 20 61  er query. Such a
183d0 20 73 75 62 71 75 65 72 79 20 69 73 20 6b 6e 6f   subquery is kno
183e0 77 6e 20 61 73 0a 61 20 63 6f 72 72 65 6c 61 74  wn as.a correlat
183f0 65 64 20 73 75 62 71 75 65 72 79 2e 20 5e 41 20  ed subquery. ^A 
18400 63 6f 72 72 65 6c 61 74 65 64 20 73 75 62 71 75  correlated subqu
18410 65 72 79 20 69 73 20 72 65 65 76 61 6c 75 61 74  ery is reevaluat
18420 65 64 20 65 61 63 68 20 74 69 6d 65 0a 69 74 73  ed each time.its
18430 20 72 65 73 75 6c 74 20 69 73 20 72 65 71 75 69   result is requi
18440 72 65 64 2e 20 5e 41 6e 20 75 6e 63 6f 72 72 65  red. ^An uncorre
18450 6c 61 74 65 64 20 73 75 62 71 75 65 72 79 20 69  lated subquery i
18460 73 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 6c 79  s evaluated only
18470 20 6f 6e 63 65 0a 61 6e 64 20 74 68 65 20 72 65   once.and the re
18480 73 75 6c 74 20 72 65 75 73 65 64 20 61 73 20 6e  sult reused as n
18490 65 63 65 73 73 61 72 79 2e 0a 0a 3c 74 63 6c 3e  ecessary...<tcl>
184a0 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 61 73 74  hd_fragment cast
184b0 65 78 70 72 20 7b 43 41 53 54 20 65 78 70 72 65  expr {CAST expre
184c0 73 73 69 6f 6e 7d 20 7b 43 41 53 54 7d 20 7b 63  ssion} {CAST} {c
184d0 61 73 74 7d 20 7b 43 41 53 54 20 6f 70 65 72 61  ast} {CAST opera
184e0 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 43  tor}</tcl>.<h3>C
184f0 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e 73 3c  AST expressions<
18500 2f 68 33 3e 0a 0a 3c 70 3e 41 20 43 41 53 54 20  /h3>..<p>A CAST 
18510 65 78 70 72 65 73 73 69 6f 6e 20 6f 66 20 74 68  expression of th
18520 65 20 66 6f 72 6d 20 22 43 41 53 54 28 3c 69 3e  e form "CAST(<i>
18530 65 78 70 72 3c 2f 69 3e 20 41 53 20 3c 69 3e 74  expr</i> AS <i>t
18540 79 70 65 2d 6e 61 6d 65 3c 2f 69 3e 29 22 0a 69  ype-name</i>)".i
18550 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 76 65 72  s used to conver
18560 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 3c  t the value of <
18570 69 3e 65 78 70 72 3c 2f 69 3e 20 74 6f 20 0a 61  i>expr</i> to .a
18580 20 64 69 66 66 65 72 65 6e 74 20 5b 73 74 6f 72   different [stor
18590 61 67 65 20 63 6c 61 73 73 5d 20 73 70 65 63 69  age class] speci
185a0 66 69 65 64 20 62 79 20 3c 79 79 74 65 72 6d 3e  fied by <yyterm>
185b0 74 79 70 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  type-name</yyter
185c0 6d 3e 2e 0a 5e 41 20 43 41 53 54 20 63 6f 6e 76  m>..^A CAST conv
185d0 65 72 73 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61  ersion is simila
185e0 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 73  r to the convers
185f0 69 6f 6e 20 74 68 61 74 20 74 61 6b 65 73 0a 70  ion that takes.p
18600 6c 61 63 65 20 77 68 65 6e 20 61 20 5b 63 6f 6c  lace when a [col
18610 75 6d 6e 20 61 66 66 69 6e 69 74 79 5d 20 69 73  umn affinity] is
18620 20 61 70 70 6c 69 65 64 20 74 6f 20 61 20 76 61   applied to a va
18630 6c 75 65 20 65 78 63 65 70 74 20 74 68 61 74 20  lue except that 
18640 77 69 74 68 0a 74 68 65 20 43 41 53 54 20 6f 70  with.the CAST op
18650 65 72 61 74 6f 72 20 74 68 65 20 63 6f 6e 76 65  erator the conve
18660 72 73 69 6f 6e 20 61 6c 77 61 79 73 20 74 61 6b  rsion always tak
18670 65 73 20 70 6c 61 63 65 20 65 76 65 6e 20 69 66  es place even if
18680 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a   the conversion.
18690 6c 6f 73 73 79 20 61 6e 64 20 69 72 72 65 76 65  lossy and irreve
186a0 72 73 69 62 6c 65 2c 20 77 68 65 72 65 61 73 20  rsible, whereas 
186b0 63 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79 20  column affinity 
186c0 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 65  only changes the
186d0 20 64 61 74 61 20 74 79 70 65 0a 6f 66 20 61 20   data type.of a 
186e0 76 61 6c 75 65 20 69 66 20 74 68 65 20 63 68 61  value if the cha
186f0 6e 67 65 20 69 73 20 6c 6f 73 73 6c 65 73 73 20  nge is lossless 
18700 61 6e 64 20 72 65 76 65 72 73 69 62 6c 65 2e 0a  and reversible..
18710 0a 3c 70 3e 5e 49 66 20 74 68 65 20 76 61 6c 75  .<p>^If the valu
18720 65 20 6f 66 20 3c 69 3e 65 78 70 72 3c 2f 69 3e  e of <i>expr</i>
18730 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74   is NULL, then t
18740 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
18750 20 43 41 53 54 0a 65 78 70 72 65 73 73 69 6f 6e   CAST.expression
18760 20 69 73 20 61 6c 73 6f 20 4e 55 4c 4c 2e 20 5e   is also NULL. ^
18770 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 73  Otherwise, the s
18780 74 6f 72 61 67 65 20 63 6c 61 73 73 20 6f 66 20  torage class of 
18790 74 68 65 20 72 65 73 75 6c 74 0a 69 73 20 64 65  the result.is de
187a0 74 65 72 6d 69 6e 65 64 20 62 79 20 61 70 70 6c  termined by appl
187b0 79 69 6e 67 20 74 68 65 20 5b 72 75 6c 65 73 20  ying the [rules 
187c0 66 6f 72 20 64 65 74 65 72 6d 69 6e 69 6e 67 20  for determining 
187d0 63 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79 5d  column affinity]
187e0 20 74 6f 0a 74 68 65 20 3c 79 79 74 65 72 6d 3e   to.the <yyterm>
187f0 74 79 70 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  type-name</yyter
18800 6d 3e 2e 0a 0a 3c 74 61 62 6c 65 20 62 6f 72 64  m>...<table bord
18810 65 72 3d 31 3e 0a 3c 74 72 3e 0a 20 20 3c 74 68  er=1>.<tr>.  <th
18820 3e 20 41 66 66 69 6e 69 74 79 20 6f 66 20 3c 79  > Affinity of <y
18830 79 74 65 72 6d 3e 74 79 70 65 2d 6e 61 6d 65 3c  yterm>type-name<
18840 2f 79 79 74 65 72 6d 3e 0a 20 20 3c 74 68 3e 20  /yyterm>.  <th> 
18850 43 6f 6e 76 65 72 73 69 6f 6e 20 50 72 6f 63 65  Conversion Proce
18860 73 73 69 6e 67 0a 3c 74 72 3e 0a 20 20 3c 74 64  ssing.<tr>.  <td
18870 3e 20 4e 4f 4e 45 20 0a 20 20 3c 74 64 3e 20 5e  > NONE .  <td> ^
18880 43 61 73 74 69 6e 67 20 61 20 76 61 6c 75 65 20  Casting a value 
18890 74 6f 20 61 20 3c 79 79 74 65 72 6d 3e 74 79 70  to a <yyterm>typ
188a0 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  e-name</yyterm> 
188b0 77 69 74 68 20 6e 6f 20 61 66 66 69 6e 69 74 79  with no affinity
188c0 20 0a 20 20 63 61 75 73 65 73 20 74 68 65 20 76   .  causes the v
188d0 61 6c 75 65 20 74 6f 0a 20 20 62 65 20 63 6f 6e  alue to.  be con
188e0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 42 4c  verted into a BL
188f0 4f 42 2e 20 20 5e 43 61 73 74 69 6e 67 20 74 6f  OB.  ^Casting to
18900 20 61 20 42 4c 4f 42 20 63 6f 6e 73 69 73 74 73   a BLOB consists
18910 20 6f 66 20 66 69 72 73 74 20 63 61 73 74 69 6e   of first castin
18920 67 0a 20 20 74 68 65 20 76 61 6c 75 65 20 74 6f  g.  the value to
18930 20 54 45 58 54 20 69 6e 20 74 68 65 20 5b 65 6e   TEXT in the [en
18940 63 6f 64 69 6e 67 5d 20 6f 66 20 74 68 65 20 64  coding] of the d
18950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18960 6f 6e 2c 20 74 68 65 6e 0a 20 20 69 6e 74 65 72  on, then.  inter
18970 70 72 65 74 69 6e 67 20 74 68 65 20 72 65 73 75  preting the resu
18980 6c 74 69 6e 67 20 62 79 74 65 20 73 65 71 75 65  lting byte seque
18990 6e 63 65 20 61 73 20 61 20 42 4c 4f 42 20 69 6e  nce as a BLOB in
189a0 73 74 65 61 64 20 6f 66 20 61 73 20 54 45 58 54  stead of as TEXT
189b0 2e 0a 0a 3c 74 72 3e 0a 20 20 3c 74 64 3e 20 54  ...<tr>.  <td> T
189c0 45 58 54 0a 20 20 3c 74 64 3e 20 5e 54 6f 20 63  EXT.  <td> ^To c
189d0 61 73 74 20 61 20 42 4c 4f 42 20 76 61 6c 75 65  ast a BLOB value
189e0 20 74 6f 20 54 45 58 54 2c 20 74 68 65 20 73 65   to TEXT, the se
189f0 71 75 65 6e 63 65 20 6f 66 20 62 79 74 65 73 20  quence of bytes 
18a00 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65  that make up the
18a10 0a 20 20 42 4c 4f 42 20 69 73 20 69 6e 74 65 72  .  BLOB is inter
18a20 70 72 65 74 65 64 20 61 73 20 74 65 78 74 20 65  preted as text e
18a30 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 74 68 65  ncoded using the
18a40 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
18a50 6e 67 2e 0a 20 20 3c 70 3e 0a 20 20 20 5e 43 61  ng..  <p>.   ^Ca
18a60 73 74 69 6e 67 20 61 6e 20 49 4e 54 45 47 45 52  sting an INTEGER
18a70 20 6f 72 20 52 45 41 4c 20 76 61 6c 75 65 20 69   or REAL value i
18a80 6e 74 6f 20 54 45 58 54 20 72 65 6e 64 65 72 73  nto TEXT renders
18a90 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 69 66   the value as if
18aa0 20 76 69 61 20 0a 20 20 20 20 5b 73 71 6c 69 74   via .    [sqlit
18ab0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 65  e3_snprintf()] e
18ac0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 72  xcept that the r
18ad0 65 73 75 6c 74 69 6e 67 20 54 45 58 54 20 75 73  esulting TEXT us
18ae0 65 73 20 74 68 65 20 5b 65 6e 63 6f 64 69 6e 67  es the [encoding
18af0 5d 20 6f 66 0a 20 20 20 20 74 68 65 20 64 61 74  ] of.    the dat
18b00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18b10 2e 0a 0a 3c 74 72 3e 0a 20 20 3c 74 64 3e 20 52  ...<tr>.  <td> R
18b20 45 41 4c 0a 20 20 3c 74 64 3e 20 5e 57 68 65 6e  EAL.  <td> ^When
18b30 20 63 61 73 74 69 6e 67 20 61 20 42 4c 4f 42 20   casting a BLOB 
18b40 76 61 6c 75 65 20 74 6f 20 61 20 52 45 41 4c 2c  value to a REAL,
18b50 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 66 69   the value is fi
18b60 72 73 74 20 63 6f 6e 76 65 72 74 65 64 20 74 6f  rst converted to
18b70 0a 20 20 20 20 20 20 20 20 54 45 58 54 2e 0a 20  .        TEXT.. 
18b80 20 20 20 20 20 20 3c 70 3e 5e 57 68 65 6e 20 63        <p>^When c
18b90 61 73 74 69 6e 67 20 61 20 54 45 58 54 20 76 61  asting a TEXT va
18ba0 6c 75 65 20 74 6f 20 52 45 41 4c 2c 20 74 68 65  lue to REAL, the
18bb0 20 6c 6f 6e 67 65 73 74 20 70 6f 73 73 69 62 6c   longest possibl
18bc0 65 20 70 72 65 66 69 78 20 6f 66 0a 20 20 20 20  e prefix of.    
18bd0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 74 68      the value th
18be0 61 74 20 63 61 6e 20 62 65 20 69 6e 74 65 72 70  at can be interp
18bf0 72 65 74 65 64 20 61 73 20 61 20 72 65 61 6c 20  reted as a real 
18c00 6e 75 6d 62 65 72 20 69 73 20 65 78 74 72 61 63  number is extrac
18c10 74 65 64 20 66 72 6f 6d 0a 20 20 20 20 20 20 20  ted from.       
18c20 20 74 68 65 20 54 45 58 54 20 76 61 6c 75 65 20   the TEXT value 
18c30 61 6e 64 20 74 68 65 20 72 65 6d 61 69 6e 64 65  and the remainde
18c40 72 20 69 67 6e 6f 72 65 64 2e 20 5e 41 6e 79 20  r ignored. ^Any 
18c50 6c 65 61 64 69 6e 67 20 73 70 61 63 65 73 20 69  leading spaces i
18c60 6e 20 74 68 65 0a 20 20 20 20 20 20 20 20 54 45  n the.        TE
18c70 58 54 20 76 61 6c 75 65 20 61 72 65 20 69 67 6e  XT value are ign
18c80 6f 72 65 64 20 77 68 65 6e 20 63 6f 6e 76 65 72  ored when conver
18c90 67 69 6e 67 20 66 72 6f 6d 20 54 45 58 54 20 74  ging from TEXT t
18ca0 6f 20 52 45 41 4c 2e 20 5e 28 49 66 20 74 68 65  o REAL. ^(If the
18cb0 72 65 20 69 73 0a 20 20 20 20 20 20 20 20 6e 6f  re is.        no
18cc0 20 70 72 65 66 69 78 20 74 68 61 74 20 63 61 6e   prefix that can
18cd0 20 62 65 20 69 6e 74 65 72 70 72 65 74 65 64 20   be interpreted 
18ce0 61 73 20 61 20 72 65 61 6c 20 6e 75 6d 62 65 72  as a real number
18cf0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
18d00 74 68 65 0a 20 20 20 20 20 20 20 20 63 6f 6e 76  the.        conv
18d10 65 72 73 69 6f 6e 20 69 73 20 30 2e 30 2e 29 5e  ersion is 0.0.)^
18d20 0a 0a 3c 74 72 3e 0a 20 20 3c 74 64 3e 20 49 4e  ..<tr>.  <td> IN
18d30 54 45 47 45 52 0a 20 20 3c 74 64 3e 20 5e 57 68  TEGER.  <td> ^Wh
18d40 65 6e 20 63 61 73 74 69 6e 67 20 61 20 42 4c 4f  en casting a BLO
18d50 42 20 76 61 6c 75 65 20 74 6f 20 49 4e 54 45 47  B value to INTEG
18d60 45 52 2c 20 74 68 65 20 76 61 6c 75 65 20 69 73  ER, the value is
18d70 20 66 69 72 73 74 20 63 6f 6e 76 65 72 74 65 64   first converted
18d80 20 74 6f 0a 20 20 20 20 20 20 20 20 54 45 58 54   to.        TEXT
18d90 2e 0a 20 20 20 20 20 20 20 3c 70 3e 5e 57 68 65  ..       <p>^Whe
18da0 6e 20 63 61 73 74 69 6e 67 20 61 20 54 45 58 54  n casting a TEXT
18db0 20 76 61 6c 75 65 20 74 6f 20 49 4e 54 45 47 45   value to INTEGE
18dc0 52 2c 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 70  R, the longest p
18dd0 6f 73 73 69 62 6c 65 20 70 72 65 66 69 78 20 6f  ossible prefix o
18de0 66 0a 20 20 20 20 20 20 20 20 74 68 65 20 76 61  f.        the va
18df0 6c 75 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  lue that can be 
18e00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
18e10 6e 20 69 6e 74 65 67 65 72 20 6e 75 6d 62 65 72  n integer number
18e20 20 69 73 20 65 78 74 72 61 63 74 65 64 20 66 72   is extracted fr
18e30 6f 6d 0a 20 20 20 20 20 20 20 20 74 68 65 20 54  om.        the T
18e40 45 58 54 20 76 61 6c 75 65 20 61 6e 64 20 74 68  EXT value and th
18e50 65 20 72 65 6d 61 69 6e 64 65 72 20 69 67 6e 6f  e remainder igno
18e60 72 65 64 2e 20 5e 41 6e 79 20 6c 65 61 64 69 6e  red. ^Any leadin
18e70 67 20 73 70 61 63 65 73 20 69 6e 20 74 68 65 0a  g spaces in the.
18e80 20 20 20 20 20 20 20 20 54 45 58 54 20 76 61 6c          TEXT val
18e90 75 65 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ue when converti
18ea0 6e 67 20 66 72 6f 6d 20 54 45 58 54 20 74 6f 20  ng from TEXT to 
18eb0 49 4e 54 45 47 45 52 20 61 72 65 20 69 67 6e 6f  INTEGER are igno
18ec0 72 65 64 2e 20 5e 49 66 20 74 68 65 72 65 0a 20  red. ^If there. 
18ed0 20 20 20 20 20 20 20 69 73 20 6e 6f 20 70 72 65         is no pre
18ee0 66 69 78 20 74 68 61 74 20 63 61 6e 20 62 65 20  fix that can be 
18ef0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
18f00 6e 20 69 6e 74 65 67 65 72 20 6e 75 6d 62 65 72  n integer number
18f10 2c 20 74 68 65 20 72 65 73 75 6c 74 0a 20 20 20  , the result.   
18f20 20 20 20 20 20 6f 66 20 74 68 65 20 63 6f 6e 76       of the conv
18f30 65 72 73 69 6f 6e 20 69 73 20 30 2e 20 20 5e 28  ersion is 0.  ^(
18f40 54 68 65 20 43 41 53 54 20 6f 70 65 72 61 74 6f  The CAST operato
18f50 72 20 75 6e 64 65 72 73 74 61 6e 64 73 20 64 65  r understands de
18f60 63 69 6d 61 6c 0a 20 20 20 20 20 20 20 20 69 6e  cimal.        in
18f70 74 65 67 65 72 73 20 6f 6e 6c 79 20 26 6d 64 61  tegers only &mda
18f80 73 68 3b 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  sh; conversion o
18f90 66 20 5b 68 65 78 61 64 65 63 69 6d 61 6c 20 69  f [hexadecimal i
18fa0 6e 74 65 67 65 72 73 5d 20 73 74 6f 70 73 20 0a  ntegers] stops .
18fb0 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 22          at the "
18fc0 78 22 20 69 6e 20 74 68 65 20 22 30 78 22 20 70  x" in the "0x" p
18fd0 72 65 66 69 78 20 6f 66 20 74 68 65 20 68 65 78  refix of the hex
18fe0 61 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72  adecimal integer
18ff0 20 73 74 72 69 6e 67 20 0a 20 20 20 20 20 20 20   string .       
19000 20 61 6e 64 20 74 68 75 73 20 72 65 73 75 6c 74   and thus result
19010 20 6f 66 20 74 68 65 20 43 41 53 54 20 69 73 20   of the CAST is 
19020 61 6c 77 61 79 73 20 7a 65 72 6f 2e 29 5e 0a 0a  always zero.)^..
19030 20 20 20 20 20 20 3c 70 3e 5e 41 20 63 61 73 74        <p>^A cast
19040 20 6f 66 20 61 20 52 45 41 4c 20 76 61 6c 75 65   of a REAL value
19050 20 69 6e 74 6f 20 61 6e 20 49 4e 54 45 47 45 52   into an INTEGER
19060 20 72 65 73 75 6c 74 73 20 69 6e 20 74 68 65 20   results in the 
19070 69 6e 74 65 67 65 72 0a 20 20 20 20 20 20 62 65  integer.      be
19080 74 77 65 65 6e 20 74 68 65 20 52 45 41 4c 20 76  tween the REAL v
19090 61 6c 75 65 20 61 6e 64 20 7a 65 72 6f 20 74 68  alue and zero th
190a0 61 74 20 69 73 20 63 6c 6f 73 65 73 74 20 74 6f  at is closest to
190b0 20 74 68 65 20 52 45 41 4c 20 76 61 6c 75 65 2e   the REAL value.
190c0 0a 20 20 20 20 20 20 5e 49 66 20 61 20 52 45 41  .      ^If a REA
190d0 4c 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  L is greater tha
190e0 6e 20 74 68 65 20 67 72 65 61 74 65 73 74 20 70  n the greatest p
190f0 6f 73 73 69 62 6c 65 20 73 69 67 6e 65 64 0a 20  ossible signed. 
19100 20 20 20 20 20 69 6e 74 65 67 65 72 20 28 2b 39       integer (+9
19110 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
19120 30 37 29 20 74 68 65 6e 20 74 68 65 20 72 65 73  07) then the res
19130 75 6c 74 20 69 73 20 74 68 65 20 67 72 65 61 74  ult is the great
19140 65 73 74 20 70 6f 73 73 69 62 6c 65 0a 20 20 20  est possible.   
19150 20 20 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65     signed intege
19160 72 20 61 6e 64 20 69 66 20 74 68 65 20 52 45 41  r and if the REA
19170 4c 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  L is less than t
19180 68 65 20 6c 65 61 73 74 20 70 6f 73 73 69 62 6c  he least possibl
19190 65 20 73 69 67 6e 65 64 0a 20 20 20 20 20 20 69  e signed.      i
191a0 6e 74 65 67 65 72 20 28 2d 39 32 32 33 33 37 32  nteger (-9223372
191b0 30 33 36 38 35 34 37 37 35 38 30 38 29 20 74 68  036854775808) th
191c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  en the result is
191d0 20 74 68 65 20 6c 65 61 73 74 20 70 6f 73 73 69   the least possi
191e0 62 6c 65 0a 20 20 20 20 20 20 73 69 67 6e 65 64  ble.      signed
191f0 20 69 6e 74 65 67 65 72 2e 0a 0a 20 20 20 20 20   integer...     
19200 20 3c 70 3e 50 72 69 6f 72 20 74 6f 20 53 51 4c   <p>Prior to SQL
19210 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 38 2e  ite version 3.8.
19220 32 20 28 5b 64 61 74 65 6f 66 3a 33 2e 38 2e 32  2 ([dateof:3.8.2
19230 5d 29 2c 0a 20 20 20 20 20 20 63 61 73 74 69 6e  ]),.      castin
19240 67 20 61 20 52 45 41 4c 20 76 61 6c 75 65 20 67  g a REAL value g
19250 72 65 61 74 65 72 20 74 68 61 6e 0a 20 20 20 20  reater than.    
19260 20 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34    +9223372036854
19270 37 37 35 38 30 37 2e 30 20 69 6e 74 6f 20 61 6e  775807.0 into an
19280 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 65   integer resulte
19290 64 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 6e 65  d in the most ne
192a0 67 61 74 69 76 65 0a 20 20 20 20 20 20 69 6e 74  gative.      int
192b0 65 67 65 72 2c 20 2d 39 32 32 33 33 37 32 30 33  eger, -922337203
192c0 36 38 35 34 37 37 35 38 30 38 2e 20 20 54 68 69  6854775808.  Thi
192d0 73 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 6d  s behavior was m
192e0 65 61 6e 74 20 74 6f 20 65 6d 75 6c 61 74 65 20  eant to emulate 
192f0 74 68 65 0a 20 20 20 20 20 20 62 65 68 61 76 69  the.      behavi
19300 6f 72 20 6f 66 20 78 38 36 2f 78 36 34 20 68 61  or of x86/x64 ha
19310 72 64 77 61 72 65 20 77 68 65 6e 20 64 6f 69 6e  rdware when doin
19320 67 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  g the equivalent
19330 20 63 61 73 74 2e 0a 0a 3c 74 72 3e 0a 20 20 3c   cast...<tr>.  <
19340 74 64 3e 20 4e 55 4d 45 52 49 43 0a 20 20 3c 74  td> NUMERIC.  <t
19350 64 3e 20 5e 43 61 73 74 69 6e 67 20 61 20 54 45  d> ^Casting a TE
19360 58 54 20 6f 72 20 42 4c 4f 42 20 76 61 6c 75 65  XT or BLOB value
19370 20 69 6e 74 6f 20 4e 55 4d 45 52 49 43 20 66 69   into NUMERIC fi
19380 72 73 74 20 64 6f 65 73 20 61 20 66 6f 72 63 65  rst does a force
19390 64 0a 20 20 20 63 6f 6e 76 65 72 73 69 6f 6e 20  d.   conversion 
193a0 69 6e 74 6f 20 52 45 41 4c 20 62 75 74 20 74 68  into REAL but th
193b0 65 6e 20 66 75 72 74 68 65 72 20 63 6f 6e 76 65  en further conve
193c0 72 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  rts the result i
193d0 6e 74 6f 20 49 4e 54 45 47 45 52 20 69 66 0a 20  nto INTEGER if. 
193e0 20 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68    and only if th
193f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  e conversion fro
19400 6d 20 52 45 41 4c 20 74 6f 20 49 4e 54 45 47 45  m REAL to INTEGE
19410 52 20 69 73 20 6c 6f 73 73 6c 65 73 73 20 61 6e  R is lossless an
19420 64 20 72 65 76 65 72 73 69 62 6c 65 2e 0a 20 20  d reversible..  
19430 20 54 68 69 73 20 69 73 20 74 68 65 20 6f 6e 6c   This is the onl
19440 79 20 63 6f 6e 74 65 78 74 20 69 6e 20 53 51 4c  y context in SQL
19450 69 74 65 20 77 68 65 72 65 20 74 68 65 20 4e 55  ite where the NU
19460 4d 45 52 49 43 20 61 6e 64 20 49 4e 54 45 47 45  MERIC and INTEGE
19470 52 20 5b 61 66 66 69 6e 69 74 69 65 73 5d 0a 20  R [affinities]. 
19480 20 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65    behave differe
19490 6e 74 6c 79 2e 0a 20 20 20 3c 70 3e 20 5e 43 61  ntly..   <p> ^Ca
194a0 73 74 69 6e 67 20 61 20 52 45 41 4c 20 6f 72 20  sting a REAL or 
194b0 49 4e 54 45 47 45 52 20 76 61 6c 75 65 20 74 6f  INTEGER value to
194c0 20 4e 55 4d 45 52 49 43 20 69 73 20 61 20 6e 6f   NUMERIC is a no
194d0 2d 6f 70 2c 20 65 76 65 6e 20 69 66 20 61 20 72  -op, even if a r
194e0 65 61 6c 0a 20 20 20 76 61 6c 75 65 20 63 6f 75  eal.   value cou
194f0 6c 64 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79  ld be losslessly
19500 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e   converted to an
19510 20 69 6e 74 65 67 65 72 2e 0a 0a 3c 2f 74 72 3e   integer...</tr>
19520 0a 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 5e  ..</table>..<p>^
19530 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 72 65  Note that the re
19540 73 75 6c 74 20 66 72 6f 6d 20 63 61 73 74 69 6e  sult from castin
19550 67 20 61 6e 79 20 6e 6f 6e 2d 42 4c 4f 42 20 76  g any non-BLOB v
19560 61 6c 75 65 20 69 6e 74 6f 20 61 20 0a 42 4c 4f  alue into a .BLO
19570 42 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  B and the result
19580 20 66 72 6f 6d 20 63 61 73 74 69 6e 67 20 61 6e   from casting an
19590 79 20 42 4c 4f 42 20 76 61 6c 75 65 20 69 6e 74  y BLOB value int
195a0 6f 20 61 20 6e 6f 6e 2d 42 4c 4f 42 20 76 61 6c  o a non-BLOB val
195b0 75 65 0a 6d 61 79 20 62 65 20 64 69 66 66 65 72  ue.may be differ
195c0 65 6e 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ent depending on
195d0 20 77 68 65 74 68 65 72 20 74 68 65 20 64 61 74   whether the dat
195e0 61 62 61 73 65 20 5b 65 6e 63 6f 64 69 6e 67 5d  abase [encoding]
195f0 20 69 73 20 55 54 46 2d 38 2c 0a 55 54 46 2d 31   is UTF-8,.UTF-1
19600 36 62 65 2c 20 6f 72 20 55 54 46 2d 31 36 6c 65  6be, or UTF-16le
19610 2e 0a 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  ....<tcl>hd_frag
19620 6d 65 6e 74 20 62 6f 6f 6c 65 61 6e 65 78 70 72  ment booleanexpr
19630 20 7b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73   {boolean expres
19640 73 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  sion}</tcl>.<h3>
19650 42 6f 6f 6c 65 61 6e 20 45 78 70 72 65 73 73 69  Boolean Expressi
19660 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  ons</h3>..<p>The
19670 20 53 51 4c 20 6c 61 6e 67 75 61 67 65 20 66 65   SQL language fe
19680 61 74 75 72 65 73 20 73 65 76 65 72 61 6c 20 63  atures several c
19690 6f 6e 74 65 78 74 73 20 77 68 65 72 65 20 61 6e  ontexts where an
196a0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 0a   expression is .
196b0 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
196c0 65 20 72 65 73 75 6c 74 20 63 6f 6e 76 65 72 74  e result convert
196d0 65 64 20 74 6f 20 61 20 62 6f 6f 6c 65 61 6e 20  ed to a boolean 
196e0 28 74 72 75 65 20 6f 72 20 66 61 6c 73 65 29 20  (true or false) 
196f0 76 61 6c 75 65 2e 20 54 68 65 73 65 0a 63 6f 6e  value. These.con
19700 74 65 78 74 73 20 61 72 65 3a 0a 0a 20 20 3c 75  texts are:..  <u
19710 6c 3e 0a 20 20 20 20 3c 6c 69 3e 20 74 68 65 20  l>.    <li> the 
19720 57 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 20  WHERE clause of 
19730 61 20 53 45 4c 45 43 54 2c 20 55 50 44 41 54 45  a SELECT, UPDATE
19740 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
19750 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69 3e 20 74  ment,.    <li> t
19760 68 65 20 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63  he ON or USING c
19770 6c 61 75 73 65 20 6f 66 20 61 20 6a 6f 69 6e 20  lause of a join 
19780 69 6e 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  in a SELECT stat
19790 65 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69 3e 20  ement,.    <li> 
197a0 74 68 65 20 48 41 56 49 4e 47 20 63 6c 61 75 73  the HAVING claus
197b0 65 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  e of a SELECT st
197c0 61 74 65 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69  atement,.    <li
197d0 3e 20 74 68 65 20 57 48 45 4e 20 63 6c 61 75 73  > the WHEN claus
197e0 65 20 6f 66 20 61 6e 20 53 51 4c 20 74 72 69 67  e of an SQL trig
197f0 67 65 72 2c 20 61 6e 64 0a 20 20 20 20 3c 6c 69  ger, and.    <li
19800 3e 20 74 68 65 20 57 48 45 4e 20 63 6c 61 75 73  > the WHEN claus
19810 65 20 6f 72 20 63 6c 61 75 73 65 73 20 6f 66 20  e or clauses of 
19820 73 6f 6d 65 20 43 41 53 45 20 65 78 70 72 65 73  some CASE expres
19830 73 69 6f 6e 73 2e 0a 20 20 3c 2f 75 6c 3e 0a 0a  sions..  </ul>..
19840 3c 70 3e 5e 28 54 6f 20 63 6f 6e 76 65 72 74 20  <p>^(To convert 
19850 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 61  the results of a
19860 6e 20 53 51 4c 20 65 78 70 72 65 73 73 69 6f 6e  n SQL expression
19870 20 74 6f 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61   to a boolean va
19880 6c 75 65 2c 20 53 51 4c 69 74 65 0a 66 69 72 73  lue, SQLite.firs
19890 74 20 63 61 73 74 73 20 74 68 65 20 72 65 73 75  t casts the resu
198a0 6c 74 20 74 6f 20 61 20 4e 55 4d 45 52 49 43 20  lt to a NUMERIC 
198b0 76 61 6c 75 65 20 69 6e 20 74 68 65 20 73 61 6d  value in the sam
198c0 65 20 77 61 79 20 61 73 20 61 20 0a 5b 43 41 53  e way as a .[CAS
198d0 54 20 65 78 70 72 65 73 73 69 6f 6e 5d 2e 20 41  T expression]. A
198e0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 20 76 61   numeric zero va
198f0 6c 75 65 20 28 69 6e 74 65 67 65 72 20 76 61 6c  lue (integer val
19900 75 65 20 30 20 6f 72 20 72 65 61 6c 20 0a 76 61  ue 0 or real .va
19910 6c 75 65 20 30 2e 30 29 20 69 73 20 63 6f 6e 73  lue 0.0) is cons
19920 69 64 65 72 65 64 20 74 6f 20 62 65 20 66 61 6c  idered to be fal
19930 73 65 2e 20 20 41 20 4e 55 4c 4c 20 76 61 6c 75  se.  A NULL valu
19940 65 20 69 73 20 73 74 69 6c 6c 20 4e 55 4c 4c 2e  e is still NULL.
19950 0a 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65  .All other value
19960 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64  s are considered
19970 20 74 72 75 65 2e 29 5e 0a 0a 3c 70 3e 5e 28 46   true.)^..<p>^(F
19980 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20  or example, the 
19990 76 61 6c 75 65 73 20 4e 55 4c 4c 2c 20 30 2e 30  values NULL, 0.0
199a0 2c 20 30 2c 20 27 65 6e 67 6c 69 73 68 27 20 61  , 0, 'english' a
199b0 6e 64 20 27 30 27 20 61 72 65 20 61 6c 6c 20 63  nd '0' are all c
199c0 6f 6e 73 69 64 65 72 65 64 0a 74 6f 20 62 65 20  onsidered.to be 
199d0 66 61 6c 73 65 2e 29 5e 20 5e 28 56 61 6c 75 65  false.)^ ^(Value
199e0 73 20 31 2c 20 31 2e 30 2c 20 30 2e 31 2c 20 2d  s 1, 1.0, 0.1, -
199f0 30 2e 31 20 61 6e 64 20 27 31 65 6e 67 6c 69 73  0.1 and '1englis
19a00 68 27 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65  h' are considere
19a10 64 20 74 6f 20 0a 62 65 20 74 72 75 65 2e 29 5e  d to .be true.)^
19a20 0a 0a 3c 68 33 3e 46 75 6e 63 74 69 6f 6e 73 3c  ..<h3>Functions<
19a30 2f 68 33 3e 0a 3c 70 3e 53 51 4c 69 74 65 20 73  /h3>.<p>SQLite s
19a40 75 70 70 6f 72 74 73 20 6d 61 6e 79 20 5b 63 6f  upports many [co
19a50 72 65 66 75 6e 63 7c 73 69 6d 70 6c 65 5d 20 61  refunc|simple] a
19a60 6e 64 20 5b 61 67 67 66 75 6e 63 7c 61 67 67 72  nd [aggfunc|aggr
19a70 65 67 61 74 65 5d 0a 53 51 4c 20 66 75 6e 63 74  egate].SQL funct
19a80 69 6f 6e 73 2e 20 20 46 6f 72 20 70 72 65 73 65  ions.  For prese
19a90 6e 74 61 74 69 6f 6e 20 70 75 72 70 6f 73 65 73  ntation purposes
19aa0 2c 20 73 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f  , simple functio
19ab0 6e 73 20 61 72 65 20 66 75 72 74 68 65 72 0a 73  ns are further.s
19ac0 75 62 64 69 76 69 64 65 64 20 69 6e 74 6f 20 5b  ubdivided into [
19ad0 63 6f 72 65 66 75 6e 63 20 7c 20 63 6f 72 65 20  corefunc | core 
19ae0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  functions] and [
19af0 64 61 74 65 66 75 6e 63 7c 64 61 74 65 2d 74 69  datefunc|date-ti
19b00 6d 65 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 41  me functions]..A
19b10 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61 6e 20  pplications can 
19b20 61 64 64 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  add new function
19b30 73 2c 20 77 72 69 74 74 65 6e 20 69 6e 20 43 2f  s, written in C/
19b40 43 2b 2b 2c 20 75 73 69 6e 67 20 74 68 65 0a 5b  C++, using the.[
19b50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
19b60 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 74 65 72  unction()] inter
19b70 66 61 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e  face..</p>..<p>^
19b80 49 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20 74  It is possible t
19b90 6f 20 68 61 76 65 20 61 6e 20 61 67 67 72 65 67  o have an aggreg
19ba0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ate function wit
19bb0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
19bc0 61 73 20 61 0a 73 69 6d 70 6c 65 20 66 75 6e 63  as a.simple func
19bd0 74 69 6f 6e 2c 20 61 73 20 6c 6f 6e 67 20 61 73  tion, as long as
19be0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
19bf0 72 67 75 6d 65 6e 74 73 20 66 6f 72 20 74 68 65  rguments for the
19c00 20 74 77 6f 20 66 6f 72 6d 73 20 6f 66 20 74 68   two forms of th
19c10 65 0a 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  e.function are d
19c20 69 66 66 65 72 65 6e 74 2e 20 20 5e 46 6f 72 20  ifferent.  ^For 
19c30 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 5b 61 67  example, the [ag
19c40 67 5f 6d 61 78 7c 6d 61 78 28 29 5d 20 66 75 6e  g_max|max()] fun
19c50 63 74 69 6f 6e 20 77 69 74 68 20 61 0a 73 69 6e  ction with a.sin
19c60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  gle argument is 
19c70 61 6e 20 61 67 67 72 65 67 61 74 65 20 61 6e 64  an aggregate and
19c80 20 74 68 65 20 5b 6d 61 78 28 29 5d 20 66 75 6e   the [max()] fun
19c90 63 74 69 6f 6e 20 77 69 74 68 20 74 77 6f 20 6f  ction with two o
19ca0 72 20 6d 6f 72 65 0a 61 72 67 75 6d 65 6e 74 73  r more.arguments
19cb0 20 69 73 20 61 20 73 69 6d 70 6c 65 20 66 75 6e   is a simple fun
19cc0 63 74 69 6f 6e 2e 0a 0a 3c 74 63 6c 3e 0a 23 23  ction...<tcl>.##
19cd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
19ce0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
19cf0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
19d00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
19d10 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63  ############.Sec
19d20 74 69 6f 6e 20 7b 43 6f 72 65 20 46 75 6e 63 74  tion {Core Funct
19d30 69 6f 6e 73 7d 20 63 6f 72 65 66 75 6e 63 20 7b  ions} corefunc {
19d40 2a 63 6f 72 65 66 75 6e 63 7d 0a 75 6e 73 65 74  *corefunc}.unset
19d50 20 2d 6e 6f 63 6f 6d 70 6c 61 69 6e 20 63 6f 72   -nocomplain cor
19d60 65 66 75 6e 63 73 65 74 0a 70 72 6f 63 20 66 75  efuncset.proc fu
19d70 6e 63 64 65 66 20 7b 73 79 6e 74 61 78 20 6b 65  ncdef {syntax ke
19d80 79 77 6f 72 64 73 20 64 65 73 63 7d 20 7b 0a 20  ywords desc} {. 
19d90 20 67 6c 6f 62 61 6c 20 63 6f 72 65 66 75 6e 63   global corefunc
19da0 73 65 74 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b  set.  regexp {^[
19db0 61 2d 7a 5f 5d 2b 7d 20 24 73 79 6e 74 61 78 20  a-z_]+} $syntax 
19dc0 62 61 73 65 73 79 6e 74 61 78 0a 20 20 73 65 74  basesyntax.  set
19dd0 20 63 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61   corefuncset($ba
19de0 73 65 73 79 6e 74 61 78 29 20 5b 6c 69 73 74 20  sesyntax) [list 
19df0 24 73 79 6e 74 61 78 20 24 6b 65 79 77 6f 72 64  $syntax $keyword
19e00 73 20 24 64 65 73 63 5d 0a 7d 0a 66 75 6e 63 64  s $desc].}.funcd
19e10 65 66 20 7b 61 62 73 28 58 29 7d 20 7b 7d 20 7b  ef {abs(X)} {} {
19e20 0a 20 20 5e 54 68 65 20 61 62 73 28 58 29 20 66  .  ^The abs(X) f
19e30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19e40 74 68 65 20 61 62 73 6f 6c 75 74 65 20 76 61 6c  the absolute val
19e50 75 65 20 6f 66 20 74 68 65 20 6e 75 6d 65 72 69  ue of the numeri
19e60 63 0a 20 20 61 72 67 75 6d 65 6e 74 20 58 2e 20  c.  argument X. 
19e70 20 5e 41 62 73 28 58 29 20 72 65 74 75 72 6e 73   ^Abs(X) returns
19e80 20 4e 55 4c 4c 20 69 66 20 58 20 69 73 20 4e 55   NULL if X is NU
19e90 4c 4c 2e 20 0a 20 20 5e 28 41 62 73 28 58 29 20  LL. .  ^(Abs(X) 
19ea0 72 65 74 75 72 6e 73 20 30 2e 30 20 69 66 20 58  returns 0.0 if X
19eb0 20 69 73 20 61 20 73 74 72 69 6e 67 20 6f 72 20   is a string or 
19ec0 62 6c 6f 62 0a 20 20 74 68 61 74 20 63 61 6e 6e  blob.  that cann
19ed0 6f 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  ot be converted 
19ee0 74 6f 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  to a numeric val
19ef0 75 65 2e 29 5e 20 20 5e 49 66 20 58 20 69 73 20  ue.)^  ^If X is 
19f00 74 68 65 20 0a 20 20 69 6e 74 65 67 65 72 20 2d  the .  integer -
19f10 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
19f20 38 30 38 20 74 68 65 6e 20 61 62 73 28 58 29 20  808 then abs(X) 
19f30 74 68 72 6f 77 73 20 61 6e 20 69 6e 74 65 67 65  throws an intege
19f40 72 20 6f 76 65 72 66 6c 6f 77 0a 20 20 65 72 72  r overflow.  err
19f50 6f 72 20 73 69 6e 63 65 20 74 68 65 72 65 20 69  or since there i
19f60 73 20 6e 6f 20 65 71 75 69 76 61 6c 65 6e 74 20  s no equivalent 
19f70 70 6f 73 69 74 69 76 65 20 36 34 2d 62 69 74 20  positive 64-bit 
19f80 74 77 6f 20 63 6f 6d 70 6c 65 6d 65 6e 74 20 76  two complement v
19f90 61 6c 75 65 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  alue..}..funcdef
19fa0 20 7b 63 68 61 6e 67 65 73 28 29 7d 20 7b 7d 20   {changes()} {} 
19fb0 7b 0a 20 20 5e 54 68 65 20 63 68 61 6e 67 65 73  {.  ^The changes
19fc0 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
19fd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
19fe0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
19ff0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
1a000 64 0a 20 20 6f 72 20 69 6e 73 65 72 74 65 64 20  d.  or inserted 
1a010 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
1a020 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1a030 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1a040 2c 20 44 45 4c 45 54 45 2c 0a 20 20 6f 72 20 55  , DELETE,.  or U
1a050 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2c  PDATE statement,
1a060 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 73 74   exclusive of st
1a070 61 74 65 6d 65 6e 74 73 20 69 6e 20 6c 6f 77 65  atements in lowe
1a080 72 2d 6c 65 76 65 6c 20 74 72 69 67 67 65 72 73  r-level triggers
1a090 2e 0a 20 20 5e 54 68 65 20 63 68 61 6e 67 65 73  ..  ^The changes
1a0a0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1a0b0 69 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  is a wrapper aro
1a0c0 75 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  und the [sqlite3
1a0d0 5f 63 68 61 6e 67 65 73 28 29 5d 0a 20 20 43 2f  _changes()].  C/
1a0e0 43 2b 2b 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64  C++ function and
1a0f0 20 68 65 6e 63 65 20 66 6f 6c 6c 6f 77 73 20 74   hence follows t
1a100 68 65 20 73 61 6d 65 20 72 75 6c 65 73 20 66 6f  he same rules fo
1a110 72 20 63 6f 75 6e 74 69 6e 67 20 63 68 61 6e 67  r counting chang
1a120 65 73 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  es..}..funcdef {
1a130 63 68 61 72 28 58 31 2c 58 32 2c 2e 2e 2e 2c 58  char(X1,X2,...,X
1a140 4e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 28 54 68 65  N)} {} {.  ^(The
1a150 20 63 68 61 72 28 58 31 2c 58 32 2c 2e 2e 2e 2c   char(X1,X2,...,
1a160 58 4e 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  XN) function ret
1a170 75 72 6e 73 20 61 20 73 74 72 69 6e 67 20 63 6f  urns a string co
1a180 6d 70 6f 73 65 64 20 6f 66 20 63 68 61 72 61 63  mposed of charac
1a190 74 65 72 73 20 68 61 76 69 6e 67 20 74 68 65 0a  ters having the.
1a1a0 20 20 20 75 6e 69 63 6f 64 65 20 63 6f 64 65 20     unicode code 
1a1b0 70 6f 69 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  point values of 
1a1c0 69 6e 74 65 67 65 72 73 20 58 31 20 74 68 72 6f  integers X1 thro
1a1d0 75 67 68 20 58 4e 2c 20 72 65 73 70 65 63 74 69  ugh XN, respecti
1a1e0 76 65 6c 79 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64  vely.)^.}..funcd
1a1f0 65 66 20 7b 63 6f 61 6c 65 73 63 65 28 58 2c 59  ef {coalesce(X,Y
1a200 2c 2e 2e 2e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  ,...)} {} {.  ^T
1a210 68 65 20 63 6f 61 6c 65 73 63 65 28 29 20 66 75  he coalesce() fu
1a220 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1a230 20 63 6f 70 79 20 6f 66 20 69 74 73 20 66 69 72   copy of its fir
1a240 73 74 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 72 67 75  st non-NULL argu
1a250 6d 65 6e 74 2c 20 6f 72 0a 20 20 4e 55 4c 4c 20  ment, or.  NULL 
1a260 69 66 20 61 6c 6c 20 61 72 67 75 6d 65 6e 74 73  if all arguments
1a270 20 61 72 65 20 4e 55 4c 4c 2e 20 20 5e 43 6f 61   are NULL.  ^Coa
1a280 6c 65 73 63 65 28 29 20 6d 75 73 74 20 68 61 76  lesce() must hav
1a290 65 20 61 74 20 6c 65 61 73 74 20 0a 20 20 32 20  e at least .  2 
1a2a0 61 72 67 75 6d 65 6e 74 73 2e 0a 7d 0a 0a 66 75  arguments..}..fu
1a2b0 6e 63 64 65 66 20 7b 67 6c 6f 62 28 58 2c 59 29  ncdef {glob(X,Y)
1a2c0 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 67 6c  } {} {.  ^The gl
1a2d0 6f 62 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e  ob(X,Y) function
1a2e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1a2f0 6f 20 74 68 65 0a 20 20 65 78 70 72 65 73 73 69  o the.  expressi
1a300 6f 6e 20 22 3c 62 3e 59 20 47 4c 4f 42 20 58 3c  on "<b>Y GLOB X<
1a310 2f 62 3e 22 2e 0a 20 20 4e 6f 74 65 20 74 68 61  /b>"..  Note tha
1a320 74 20 74 68 65 20 58 20 61 6e 64 20 59 20 61 72  t the X and Y ar
1a330 67 75 6d 65 6e 74 73 20 61 72 65 20 72 65 76 65  guments are reve
1a340 72 73 65 64 20 69 6e 20 74 68 65 20 67 6c 6f 62  rsed in the glob
1a350 28 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20 72 65  () function.  re
1a360 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 69 6e  lative to the in
1a370 66 69 78 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  fix [GLOB] opera
1a380 74 6f 72 2e 0a 20 20 5e 49 66 20 74 68 65 20 5b  tor..  ^If the [
1a390 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1a3a0 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 74 65 72  unction()] inter
1a3b0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 0a  face is used to.
1a3c0 20 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 67    override the g
1a3d0 6c 6f 62 28 58 2c 59 29 20 66 75 6e 63 74 69 6f  lob(X,Y) functio
1a3e0 6e 20 77 69 74 68 20 61 6e 20 61 6c 74 65 72 6e  n with an altern
1a3f0 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
1a400 74 69 6f 6e 20 74 68 65 6e 0a 20 20 74 68 65 20  tion then.  the 
1a410 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
1a420 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
1a430 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
1a440 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 7d 0a 0a 66  ementation..}..f
1a450 75 6e 63 64 65 66 20 7b 69 66 6e 75 6c 6c 28 58  uncdef {ifnull(X
1a460 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65  ,Y)} {} {.  ^The
1a470 20 69 66 6e 75 6c 6c 28 29 20 66 75 6e 63 74 69   ifnull() functi
1a480 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  on returns a cop
1a490 79 20 6f 66 20 69 74 73 20 66 69 72 73 74 20 6e  y of its first n
1a4a0 6f 6e 2d 4e 55 4c 4c 20 61 72 67 75 6d 65 6e 74  on-NULL argument
1a4b0 2c 20 6f 72 0a 20 20 4e 55 4c 4c 20 69 66 20 62  , or.  NULL if b
1a4c0 6f 74 68 20 61 72 67 75 6d 65 6e 74 73 20 61 72  oth arguments ar
1a4d0 65 20 4e 55 4c 4c 2e 20 20 5e 49 66 6e 75 6c 6c  e NULL.  ^Ifnull
1a4e0 28 29 20 6d 75 73 74 20 68 61 76 65 20 65 78 61  () must have exa
1a4f0 63 74 6c 79 20 32 20 61 72 67 75 6d 65 6e 74 73  ctly 2 arguments
1a500 2e 0a 20 20 5e 54 68 65 20 69 66 6e 75 6c 6c 28  ..  ^The ifnull(
1a510 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 65 71  ) function is eq
1a520 75 69 76 61 6c 65 6e 74 20 74 6f 20 5b 63 6f 61  uivalent to [coa
1a530 6c 65 73 63 65 28 29 5d 20 77 69 74 68 20 74 77  lesce()] with tw
1a540 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 7d 0a 0a  o arguments..}..
1a550 66 75 6e 63 64 65 66 20 7b 69 6e 73 74 72 28 58  funcdef {instr(X
1a560 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65  ,Y)} {} {.  ^The
1a570 20 69 6e 73 74 72 28 58 2c 59 29 20 66 75 6e 63   instr(X,Y) func
1a580 74 69 6f 6e 20 66 69 6e 64 73 20 74 68 65 20 66  tion finds the f
1a590 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 20  irst occurrence 
1a5a0 6f 66 20 73 74 72 69 6e 67 20 59 20 77 69 74 68  of string Y with
1a5b0 69 6e 20 0a 20 20 73 74 72 69 6e 67 20 58 20 61  in .  string X a
1a5c0 6e 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  nd returns the n
1a5d0 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 63  umber of prior c
1a5e0 68 61 72 61 63 74 65 72 73 20 70 6c 75 73 20 31  haracters plus 1
1a5f0 2c 20 6f 72 20 30 20 69 66 0a 20 20 59 20 69 73  , or 0 if.  Y is
1a600 20 6e 6f 77 68 65 72 65 20 66 6f 75 6e 64 20 77   nowhere found w
1a610 69 74 68 69 6e 20 58 2e 0a 20 20 5e 4f 72 2c 20  ithin X..  ^Or, 
1a620 69 66 20 58 20 61 6e 64 20 59 20 61 72 65 20 62  if X and Y are b
1a630 6f 74 68 20 42 4c 4f 42 73 2c 20 74 68 65 6e 20  oth BLOBs, then 
1a640 69 6e 73 74 72 28 58 2c 59 29 20 72 65 74 75 72  instr(X,Y) retur
1a650 6e 73 20 6f 6e 65 0a 20 20 6d 6f 72 65 20 74 68  ns one.  more th
1a660 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 62 79  an the number by
1a670 74 65 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65  tes prior to the
1a680 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1a690 65 20 6f 66 20 59 2c 20 6f 72 20 30 20 69 66 0a  e of Y, or 0 if.
1a6a0 20 20 59 20 64 6f 65 73 20 6e 6f 74 20 6f 63 63    Y does not occ
1a6b0 75 72 20 61 6e 79 77 68 65 72 65 20 77 69 74 68  ur anywhere with
1a6c0 69 6e 20 58 2e 0a 20 20 5e 49 66 20 62 6f 74 68  in X..  ^If both
1a6d0 20 61 72 67 75 6d 65 6e 74 73 20 58 20 61 6e 64   arguments X and
1a6e0 20 59 20 74 6f 20 69 6e 73 74 72 28 58 2c 59 29   Y to instr(X,Y)
1a6f0 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e   are non-NULL an
1a700 64 20 61 72 65 20 6e 6f 74 20 42 4c 4f 42 73 0a  d are not BLOBs.
1a710 20 20 74 68 65 6e 20 62 6f 74 68 20 61 72 65 20    then both are 
1a720 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 73  interpreted as s
1a730 74 72 69 6e 67 73 2e 0a 20 20 5e 49 66 20 65 69  trings..  ^If ei
1a740 74 68 65 72 20 58 20 6f 72 20 59 20 61 72 65 20  ther X or Y are 
1a750 4e 55 4c 4c 20 69 6e 20 69 6e 73 74 72 28 58 2c  NULL in instr(X,
1a760 59 29 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  Y) then the resu
1a770 6c 74 20 69 73 20 4e 55 4c 4c 2e 0a 7d 0a 0a 66  lt is NULL..}..f
1a780 75 6e 63 64 65 66 20 7b 68 65 78 28 58 29 7d 20  uncdef {hex(X)} 
1a790 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 68 65 78 28  {} {.  ^The hex(
1a7a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 6e 74 65 72  ) function inter
1a7b0 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
1a7c0 6e 74 20 61 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt as a BLOB and
1a7d0 20 72 65 74 75 72 6e 73 0a 20 20 61 20 73 74 72   returns.  a str
1a7e0 69 6e 67 20 77 68 69 63 68 20 69 73 20 74 68 65  ing which is the
1a7f0 20 75 70 70 65 72 2d 63 61 73 65 20 68 65 78 61   upper-case hexa
1a800 64 65 63 69 6d 61 6c 20 72 65 6e 64 65 72 69 6e  decimal renderin
1a810 67 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  g of the content
1a820 20 6f 66 0a 20 20 74 68 61 74 20 62 6c 6f 62 2e   of.  that blob.
1a830 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 61 73  .}..funcdef {las
1a840 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a850 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c 61  } {} {.  ^The la
1a860 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a870 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1a880 6e 73 20 74 68 65 20 5b 52 4f 57 49 44 5d 0a 20  ns the [ROWID]. 
1a890 20 6f 66 20 74 68 65 20 6c 61 73 74 20 72 6f 77   of the last row
1a8a0 20 69 6e 73 65 72 74 20 66 72 6f 6d 20 74 68 65   insert from the
1a8b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a8c0 74 69 6f 6e 20 77 68 69 63 68 20 69 6e 76 6f 6b  tion which invok
1a8d0 65 64 20 74 68 65 0a 20 20 66 75 6e 63 74 69 6f  ed the.  functio
1a8e0 6e 2e 0a 20 20 5e 54 68 65 20 6c 61 73 74 5f 69  n..  ^The last_i
1a8f0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
1a900 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  L function is a 
1a910 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74  wrapper around t
1a920 68 65 0a 20 20 5b 73 71 6c 69 74 65 33 5f 6c 61  he.  [sqlite3_la
1a930 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a940 29 5d 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61  )] C/C++ interfa
1a950 63 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 7d 0a 0a  ce function..}..
1a960 66 75 6e 63 64 65 66 20 7b 6c 65 6e 67 74 68 28  funcdef {length(
1a970 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 46 6f 72 20  X)} {} {.  ^For 
1a980 61 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 58  a string value X
1a990 2c 20 74 68 65 20 6c 65 6e 67 74 68 28 58 29 20  , the length(X) 
1a9a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a9b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1a9c0 20 20 63 68 61 72 61 63 74 65 72 73 20 28 6e 6f    characters (no
1a9d0 74 20 62 79 74 65 73 29 20 69 6e 20 58 20 70 72  t bytes) in X pr
1a9e0 69 6f 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ior to the first
1a9f0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 2e 0a   NUL character..
1aa00 20 20 53 69 6e 63 65 20 53 51 4c 69 74 65 20 73    Since SQLite s
1aa10 74 72 69 6e 67 73 20 64 6f 20 6e 6f 74 20 6e 6f  trings do not no
1aa20 72 6d 61 6c 6c 79 20 63 6f 6e 74 61 69 6e 20 4e  rmally contain N
1aa30 55 4c 20 63 68 61 72 61 63 74 65 72 73 2c 20 74  UL characters, t
1aa40 68 65 20 6c 65 6e 67 74 68 28 58 29 0a 20 20 66  he length(X).  f
1aa50 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 75 73 75  unction will usu
1aa60 61 6c 6c 79 20 72 65 74 75 72 6e 20 74 68 65 20  ally return the 
1aa70 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
1aa80 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 74 68  characters in th
1aa90 65 20 73 74 72 69 6e 67 20 58 2e 0a 20 20 5e 46  e string X..  ^F
1aaa0 6f 72 20 61 20 62 6c 6f 62 20 76 61 6c 75 65 20  or a blob value 
1aab0 58 2c 20 6c 65 6e 67 74 68 28 58 29 20 72 65 74  X, length(X) ret
1aac0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1aad0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1aae0 62 6c 6f 62 2e 0a 20 20 5e 49 66 20 58 20 69 73  blob..  ^If X is
1aaf0 20 4e 55 4c 4c 20 74 68 65 6e 20 6c 65 6e 67 74   NULL then lengt
1ab00 68 28 58 29 20 69 73 20 4e 55 4c 4c 2e 0a 20 20  h(X) is NULL..  
1ab10 5e 49 66 20 58 20 69 73 20 6e 75 6d 65 72 69 63  ^If X is numeric
1ab20 20 74 68 65 6e 20 6c 65 6e 67 74 68 28 58 29 20   then length(X) 
1ab30 72 65 74 75 72 6e 73 20 74 68 65 20 6c 65 6e 67  returns the leng
1ab40 74 68 20 6f 66 20 61 20 73 74 72 69 6e 67 0a 20  th of a string. 
1ab50 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1ab60 6f 66 20 58 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  of X..}..funcdef
1ab70 20 7b 6c 69 6b 65 28 58 2c 59 29 20 6c 69 6b 65   {like(X,Y) like
1ab80 28 58 2c 59 2c 5a 29 7d 20 7b 7d 20 7b 0a 20 20  (X,Y,Z)} {} {.  
1ab90 5e 54 68 65 20 6c 69 6b 65 28 29 20 66 75 6e 63  ^The like() func
1aba0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
1abb0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 0a 20 20  implement the.  
1abc0 22 3c 62 3e 59 20 4c 49 4b 45 20 58 20 26 23 39  "<b>Y LIKE X &#9
1abd0 31 3b 45 53 43 41 50 45 20 5a 26 23 39 33 3b 3c  1;ESCAPE Z&#93;<
1abe0 2f 62 3e 22 20 65 78 70 72 65 73 73 69 6f 6e 2e  /b>" expression.
1abf0 20 0a 20 20 5e 49 66 20 74 68 65 20 6f 70 74 69   .  ^If the opti
1ac00 6f 6e 61 6c 20 45 53 43 41 50 45 20 63 6c 61 75  onal ESCAPE clau
1ac10 73 65 20 69 73 20 70 72 65 73 65 6e 74 2c 20 74  se is present, t
1ac20 68 65 6e 20 74 68 65 0a 20 20 6c 69 6b 65 28 29  hen the.  like()
1ac30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
1ac40 6f 6b 65 64 20 77 69 74 68 20 74 68 72 65 65 20  oked with three 
1ac50 61 72 67 75 6d 65 6e 74 73 2e 20 20 5e 4f 74 68  arguments.  ^Oth
1ac60 65 72 77 69 73 65 2c 20 69 74 20 69 73 0a 20 20  erwise, it is.  
1ac70 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1ac80 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 6c 79 2e   arguments only.
1ac90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 58   Note that the X
1aca0 20 61 6e 64 20 59 20 70 61 72 61 6d 65 74 65 72   and Y parameter
1acb0 73 20 61 72 65 0a 20 20 72 65 76 65 72 73 65 64  s are.  reversed
1acc0 20 69 6e 20 74 68 65 20 6c 69 6b 65 28 29 20 66   in the like() f
1acd0 75 6e 63 74 69 6f 6e 20 72 65 6c 61 74 69 76 65  unction relative
1ace0 20 74 6f 20 74 68 65 20 69 6e 66 69 78 20 5b 4c   to the infix [L
1acf0 49 4b 45 5d 20 6f 70 65 72 61 74 6f 72 2e 0a 20  IKE] operator.. 
1ad00 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63   ^The [sqlite3_c
1ad10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1ad20 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
1ad30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 72  be used to overr
1ad40 69 64 65 20 74 68 65 0a 20 20 6c 69 6b 65 28 29  ide the.  like()
1ad50 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20 74 68   function and th
1ad60 65 72 65 62 79 20 63 68 61 6e 67 65 20 74 68 65  ereby change the
1ad70 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
1ad80 65 0a 20 20 5b 4c 49 4b 45 5d 20 6f 70 65 72 61  e.  [LIKE] opera
1ad90 74 6f 72 2e 20 20 57 68 65 6e 20 6f 76 65 72 72  tor.  When overr
1ada0 69 64 69 6e 67 20 74 68 65 20 6c 69 6b 65 28 29  iding the like()
1adb0 20 66 75 6e 63 74 69 6f 6e 2c 20 69 74 20 6d 61   function, it ma
1adc0 79 20 62 65 20 69 6d 70 6f 72 74 61 6e 74 0a 20  y be important. 
1add0 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 6f 74   to override bot
1ade0 68 20 74 68 65 20 74 77 6f 20 61 6e 64 20 74 68  h the two and th
1adf0 72 65 65 20 61 72 67 75 6d 65 6e 74 20 76 65 72  ree argument ver
1ae00 73 69 6f 6e 73 20 6f 66 20 74 68 65 20 6c 69 6b  sions of the lik
1ae10 65 28 29 20 0a 20 20 66 75 6e 63 74 69 6f 6e 2e  e() .  function.
1ae20 20 4f 74 68 65 72 77 69 73 65 2c 20 64 69 66 66   Otherwise, diff
1ae30 65 72 65 6e 74 20 63 6f 64 65 20 6d 61 79 20 62  erent code may b
1ae40 65 20 63 61 6c 6c 65 64 20 74 6f 20 69 6d 70 6c  e called to impl
1ae50 65 6d 65 6e 74 20 74 68 65 0a 20 20 5b 4c 49 4b  ement the.  [LIK
1ae60 45 5d 20 6f 70 65 72 61 74 6f 72 20 64 65 70 65  E] operator depe
1ae70 6e 64 69 6e 67 20 6f 6e 20 77 68 65 74 68 65 72  nding on whether
1ae80 20 6f 72 20 6e 6f 74 20 61 6e 20 45 53 43 41 50   or not an ESCAP
1ae90 45 20 63 6c 61 75 73 65 20 77 61 73 20 0a 20 20  E clause was .  
1aea0 73 70 65 63 69 66 69 65 64 2e 0a 7d 0a 0a 0a 66  specified..}...f
1aeb0 75 6e 63 64 65 66 20 7b 6c 69 6b 65 6c 69 68 6f  uncdef {likeliho
1aec0 6f 64 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20  od(X,Y)} {} {.  
1aed0 5e 54 68 65 20 6c 69 6b 65 6c 69 68 6f 6f 64 28  ^The likelihood(
1aee0 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  X,Y) function re
1aef0 74 75 72 6e 73 20 61 72 67 75 6d 65 6e 74 20 58  turns argument X
1af00 20 75 6e 63 68 61 6e 67 65 64 2e 0a 20 20 5e 28   unchanged..  ^(
1af10 54 68 65 20 76 61 6c 75 65 20 59 20 69 6e 20 6c  The value Y in l
1af20 69 6b 65 6c 69 68 6f 6f 64 28 58 2c 59 29 20 6d  ikelihood(X,Y) m
1af30 75 73 74 20 62 65 20 61 20 66 6c 6f 61 74 69 6e  ust be a floatin
1af40 67 20 70 6f 69 6e 74 20 63 6f 6e 73 74 61 6e 74  g point constant
1af50 0a 20 20 62 65 74 77 65 65 6e 20 30 2e 30 20 61  .  between 0.0 a
1af60 6e 64 20 31 2e 30 2c 20 69 6e 63 6c 75 73 69 76  nd 1.0, inclusiv
1af70 65 2e 29 5e 0a 20 20 5e 54 68 65 20 6c 69 6b 65  e.)^.  ^The like
1af80 6c 69 68 6f 6f 64 28 58 29 20 66 75 6e 63 74 69  lihood(X) functi
1af90 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 74 68  on is a no-op th
1afa0 61 74 20 74 68 65 20 63 6f 64 65 20 67 65 6e 65  at the code gene
1afb0 72 61 74 6f 72 0a 20 20 6f 70 74 69 6d 69 7a 65  rator.  optimize
1afc0 73 20 61 77 61 79 20 73 6f 20 74 68 61 74 20 69  s away so that i
1afd0 74 20 63 6f 6e 73 75 6d 65 73 20 6e 6f 20 43 50  t consumes no CP
1afe0 55 20 63 79 63 6c 65 73 20 64 75 72 69 6e 67 20  U cycles during 
1aff0 72 75 6e 2d 74 69 6d 65 0a 20 20 28 74 68 61 74  run-time.  (that
1b000 20 69 73 2c 20 64 75 72 69 6e 67 20 63 61 6c 6c   is, during call
1b010 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  s to [sqlite3_st
1b020 65 70 28 29 5d 29 2e 0a 20 20 5e 54 68 65 20 70  ep()])..  ^The p
1b030 75 72 70 6f 73 65 20 6f 66 20 74 68 65 20 6c 69  urpose of the li
1b040 6b 65 6c 69 68 6f 6f 64 28 58 2c 59 29 20 66 75  kelihood(X,Y) fu
1b050 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 70 72 6f  nction is to pro
1b060 76 69 64 65 20 61 20 68 69 6e 74 0a 20 20 74 6f  vide a hint.  to
1b070 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e   the query plann
1b080 65 72 20 74 68 61 74 20 74 68 65 20 61 72 67 75  er that the argu
1b090 6d 65 6e 74 20 58 20 69 73 20 61 20 62 6f 6f 6c  ment X is a bool
1b0a0 65 61 6e 20 74 68 61 74 20 69 73 0a 20 20 74 72  ean that is.  tr
1b0b0 75 65 20 77 69 74 68 20 61 20 70 72 6f 62 61 62  ue with a probab
1b0c0 69 6c 69 74 79 20 6f 66 20 61 70 70 72 6f 78 69  ility of approxi
1b0d0 6d 61 74 65 6c 79 20 59 2e 0a 20 20 5e 28 54 68  mately Y..  ^(Th
1b0e0 65 20 5b 75 6e 6c 69 6b 65 6c 79 28 58 29 5d 20  e [unlikely(X)] 
1b0f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 68 6f 72  function is shor
1b100 74 2d 68 61 6e 64 20 66 6f 72 20 6c 69 6b 65 6c  t-hand for likel
1b110 69 68 6f 6f 64 28 58 2c 30 2e 30 36 32 35 29 2e  ihood(X,0.0625).
1b120 29 5e 0a 20 20 5e 28 54 68 65 20 5b 6c 69 6b 65  )^.  ^(The [like
1b130 6c 79 28 58 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ly(X)] function 
1b140 69 73 20 73 68 6f 72 74 2d 68 61 6e 64 20 66 6f  is short-hand fo
1b150 72 20 6c 69 6b 65 6c 69 68 6f 6f 64 28 58 2c 30  r likelihood(X,0
1b160 2e 39 33 37 35 29 2e 29 5e 0a 7d 0a 0a 66 75 6e  .9375).)^.}..fun
1b170 63 64 65 66 20 7b 6c 69 6b 65 6c 79 28 58 29 7d  cdef {likely(X)}
1b180 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c 69 6b   {} {.  ^The lik
1b190 65 6c 79 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  ely(X) function 
1b1a0 72 65 74 75 72 6e 73 20 74 68 65 20 61 72 67 75  returns the argu
1b1b0 6d 65 6e 74 20 58 20 75 6e 63 68 61 6e 67 65 64  ment X unchanged
1b1c0 2e 0a 20 20 5e 54 68 65 20 6c 69 6b 65 6c 79 28  ..  ^The likely(
1b1d0 58 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  X) function is a
1b1e0 20 6e 6f 2d 6f 70 20 74 68 61 74 20 74 68 65 20   no-op that the 
1b1f0 63 6f 64 65 20 67 65 6e 65 72 61 74 6f 72 0a 20  code generator. 
1b200 20 6f 70 74 69 6d 69 7a 65 73 20 61 77 61 79 20   optimizes away 
1b210 73 6f 20 74 68 61 74 20 69 74 20 63 6f 6e 73 75  so that it consu
1b220 6d 65 73 20 6e 6f 20 43 50 55 20 63 79 63 6c 65  mes no CPU cycle
1b230 73 20 61 74 0a 20 20 72 75 6e 2d 74 69 6d 65 20  s at.  run-time 
1b240 28 74 68 61 74 20 69 73 2c 20 64 75 72 69 6e 67  (that is, during
1b250 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1b260 65 33 5f 73 74 65 70 28 29 5d 29 2e 0a 20 20 5e  e3_step()])..  ^
1b270 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
1b280 68 65 20 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e  he likely(X) fun
1b290 63 74 69 6f 6e 20 69 73 20 74 6f 20 70 72 6f 76  ction is to prov
1b2a0 69 64 65 20 61 20 68 69 6e 74 0a 20 20 74 6f 20  ide a hint.  to 
1b2b0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
1b2c0 72 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  r that the argum
1b2d0 65 6e 74 20 58 20 69 73 20 61 20 62 6f 6f 6c 65  ent X is a boole
1b2e0 61 6e 20 76 61 6c 75 65 0a 20 20 74 68 61 74 20  an value.  that 
1b2f0 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e  is usually true.
1b300 20 5e 28 54 68 65 20 6c 69 6b 65 6c 79 28 58 29   ^(The likely(X)
1b310 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 65 71 75   function is equ
1b320 69 76 61 6c 65 6e 74 0a 20 20 74 6f 20 5b 6c 69  ivalent.  to [li
1b330 6b 65 6c 69 68 6f 6f 64 5d 28 58 2c 30 2e 39 33  kelihood](X,0.93
1b340 37 35 29 2e 29 5e 20 53 65 65 20 61 6c 73 6f 3a  75).)^ See also:
1b350 20 5b 75 6e 6c 69 6b 65 6c 79 28 58 29 5d 2e 0a   [unlikely(X)]..
1b360 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 6f 61 64  }..funcdef {load
1b370 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 6c 6f  _extension(X) lo
1b380 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 58 2c 59  ad_extension(X,Y
1b390 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c  )} {} {.  ^The l
1b3a0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 58 2c  oad_extension(X,
1b3b0 59 29 20 66 75 6e 63 74 69 6f 6e 20 6c 6f 61 64  Y) function load
1b3c0 73 20 5b 53 51 4c 69 74 65 20 65 78 74 65 6e 73  s [SQLite extens
1b3d0 69 6f 6e 73 5d 20 6f 75 74 20 6f 66 20 74 68 65  ions] out of the
1b3e0 20 73 68 61 72 65 64 0a 20 20 6c 69 62 72 61 72   shared.  librar
1b3f0 79 20 66 69 6c 65 20 6e 61 6d 65 64 20 58 20 75  y file named X u
1b400 73 69 6e 67 20 74 68 65 20 65 6e 74 72 79 20 70  sing the entry p
1b410 6f 69 6e 74 20 59 2e 20 20 5e 54 68 65 20 72 65  oint Y.  ^The re
1b420 73 75 6c 74 20 6f 66 20 6c 6f 61 64 5f 65 78 74  sult of load_ext
1b430 65 6e 73 69 6f 6e 28 29 0a 20 20 69 73 20 61 6c  ension().  is al
1b440 77 61 79 73 20 61 20 4e 55 4c 4c 2e 20 20 5e 49  ways a NULL.  ^I
1b450 66 20 59 20 69 73 20 6f 6d 69 74 74 65 64 20 74  f Y is omitted t
1b460 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1b470 65 6e 74 72 79 20 70 6f 69 6e 74 20 6e 61 6d 65  entry point name
1b480 20 69 73 20 75 73 65 64 2e 0a 20 20 5e 54 68 65   is used..  ^The
1b490 20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28   load_extension(
1b4a0 29 20 66 75 6e 63 74 69 6f 6e 20 72 61 69 73 65  ) function raise
1b4b0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  s an exception i
1b4c0 66 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  f the extension 
1b4d0 66 61 69 6c 73 20 74 6f 0a 20 20 6c 6f 61 64 20  fails to.  load 
1b4e0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 63 6f  or initialize co
1b4f0 72 72 65 63 74 6c 79 2e 0a 0a 20 20 3c 70 3e 5e  rrectly...  <p>^
1b500 54 68 65 20 6c 6f 61 64 5f 65 78 74 65 6e 73 69  The load_extensi
1b510 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  on() function wi
1b520 6c 6c 20 66 61 69 6c 20 69 66 20 74 68 65 20 65  ll fail if the e
1b530 78 74 65 6e 73 69 6f 6e 20 61 74 74 65 6d 70 74  xtension attempt
1b540 73 20 74 6f 20 0a 20 20 6d 6f 64 69 66 79 20 6f  s to .  modify o
1b550 72 20 64 65 6c 65 74 65 20 61 6e 20 53 51 4c 20  r delete an SQL 
1b560 66 75 6e 63 74 69 6f 6e 20 6f 72 20 63 6f 6c 6c  function or coll
1b570 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2e 20  ating sequence. 
1b580 20 5e 54 68 65 0a 20 20 65 78 74 65 6e 73 69 6f   ^The.  extensio
1b590 6e 20 63 61 6e 20 61 64 64 20 6e 65 77 20 66 75  n can add new fu
1b5a0 6e 63 74 69 6f 6e 73 20 6f 72 20 63 6f 6c 6c 61  nctions or colla
1b5b0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73 2c 20  ting sequences, 
1b5c0 62 75 74 20 63 61 6e 6e 6f 74 0a 20 20 6d 6f 64  but cannot.  mod
1b5d0 69 66 79 20 6f 72 20 64 65 6c 65 74 65 20 65 78  ify or delete ex
1b5e0 69 73 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  isting functions
1b5f0 20 6f 72 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65   or collating se
1b600 71 75 65 6e 63 65 73 20 62 65 63 61 75 73 65 0a  quences because.
1b610 20 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e    those function
1b620 73 20 61 6e 64 2f 6f 72 20 63 6f 6c 6c 61 74 69  s and/or collati
1b630 6e 67 20 73 65 71 75 65 6e 63 65 73 20 6d 69 67  ng sequences mig
1b640 68 74 20 62 65 20 75 73 65 64 20 65 6c 73 65 77  ht be used elsew
1b650 68 65 72 65 0a 20 20 69 6e 20 74 68 65 20 63 75  here.  in the cu
1b660 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
1b670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b680 54 6f 20 6c 6f 61 64 20 61 6e 20 65 78 74 65 6e  To load an exten
1b690 73 69 6f 6e 20 74 68 61 74 0a 20 20 63 68 61 6e  sion that.  chan
1b6a0 67 65 73 20 6f 72 20 64 65 6c 65 74 65 73 20 66  ges or deletes f
1b6b0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 63 6f 6c 6c  unctions or coll
1b6c0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73 2c  ating sequences,
1b6d0 20 75 73 65 20 74 68 65 0a 20 20 5b 73 71 6c 69   use the.  [sqli
1b6e0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1b6f0 6f 6e 28 29 5d 20 43 2d 6c 61 6e 67 75 61 67 65  on()] C-language
1b700 20 41 50 49 2e 3c 2f 70 3e 0a 0a 20 20 3c 70 3e   API.</p>..  <p>
1b710 46 6f 72 20 73 65 63 75 72 69 74 79 20 72 65 61  For security rea
1b720 73 6f 6e 73 2c 20 65 78 74 65 6e 73 69 6f 6e 20  sons, extension 
1b730 6c 6f 61 64 65 64 20 69 73 20 74 75 72 6e 65 64  loaded is turned
1b740 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20   off by default 
1b750 61 6e 64 20 6d 75 73 74 0a 20 20 62 65 20 65 6e  and must.  be en
1b760 61 62 6c 65 64 20 62 79 20 61 20 70 72 69 6f 72  abled by a prior
1b770 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1b780 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1b790 74 65 6e 73 69 6f 6e 28 29 5d 2e 3c 2f 70 3e 0a  tension()].</p>.
1b7a0 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 6f 77 65  }..funcdef {lowe
1b7b0 72 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  r(X)} {} {.  ^Th
1b7c0 65 20 6c 6f 77 65 72 28 58 29 20 66 75 6e 63 74  e lower(X) funct
1b7d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ion returns a co
1b7e0 70 79 20 6f 66 20 73 74 72 69 6e 67 20 58 20 77  py of string X w
1b7f0 69 74 68 20 61 6c 6c 20 41 53 43 49 49 20 63 68  ith all ASCII ch
1b800 61 72 61 63 74 65 72 73 0a 20 20 63 6f 6e 76 65  aracters.  conve
1b810 72 74 65 64 20 74 6f 20 6c 6f 77 65 72 20 63 61  rted to lower ca
1b820 73 65 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  se.  ^The defaul
1b830 74 20 62 75 69 6c 74 2d 69 6e 20 6c 6f 77 65 72  t built-in lower
1b840 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 6f 72 6b  () function work
1b850 73 0a 20 20 66 6f 72 20 41 53 43 49 49 20 63 68  s.  for ASCII ch
1b860 61 72 61 63 74 65 72 73 20 6f 6e 6c 79 2e 20 20  aracters only.  
1b870 54 6f 20 64 6f 20 63 61 73 65 20 63 6f 6e 76 65  To do case conve
1b880 72 73 69 6f 6e 73 20 6f 6e 20 6e 6f 6e 2d 41 53  rsions on non-AS
1b890 43 49 49 0a 20 20 63 68 61 72 61 63 74 65 72 73  CII.  characters
1b8a0 2c 20 6c 6f 61 64 20 74 68 65 20 49 43 55 20 65  , load the ICU e
1b8b0 78 74 65 6e 73 69 6f 6e 2e 0a 7d 0a 0a 66 75 6e  xtension..}..fun
1b8c0 63 64 65 66 20 7b 6c 74 72 69 6d 28 58 29 20 6c  cdef {ltrim(X) l
1b8d0 74 72 69 6d 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a  trim(X,Y)} {} {.
1b8e0 20 20 5e 54 68 65 20 6c 74 72 69 6d 28 58 2c 59    ^The ltrim(X,Y
1b8f0 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1b900 6e 73 20 61 20 73 74 72 69 6e 67 20 66 6f 72 6d  ns a string form
1b910 65 64 20 62 79 20 72 65 6d 6f 76 69 6e 67 20 61  ed by removing a
1b920 6e 79 20 61 6e 64 20 61 6c 6c 0a 20 20 63 68 61  ny and all.  cha
1b930 72 61 63 74 65 72 73 20 74 68 61 74 20 61 70 70  racters that app
1b940 65 61 72 20 69 6e 20 59 20 66 72 6f 6d 20 74 68  ear in Y from th
1b950 65 20 6c 65 66 74 20 73 69 64 65 20 6f 66 20 58  e left side of X
1b960 2e 0a 20 20 5e 49 66 20 74 68 65 20 59 20 61 72  ..  ^If the Y ar
1b970 67 75 6d 65 6e 74 20 69 73 20 6f 6d 69 74 74 65  gument is omitte
1b980 64 2c 20 6c 74 72 69 6d 28 58 29 20 72 65 6d 6f  d, ltrim(X) remo
1b990 76 65 73 20 73 70 61 63 65 73 20 66 72 6f 6d 20  ves spaces from 
1b9a0 74 68 65 20 6c 65 66 74 20 73 69 64 65 0a 20 20  the left side.  
1b9b0 6f 66 20 58 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  of X..}..funcdef
1b9c0 20 7b 6d 61 78 28 58 2c 59 2c 2e 2e 2e 29 7d 20   {max(X,Y,...)} 
1b9d0 7b 2a 6d 61 78 43 6f 72 65 46 75 6e 63 20 2a 6d  {*maxCoreFunc *m
1b9e0 61 78 20 7b 6d 61 78 28 29 20 53 51 4c 20 66 75  ax {max() SQL fu
1b9f0 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68  nction}} {.  ^Th
1ba00 65 20 6d 75 6c 74 69 2d 61 72 67 75 6d 65 6e 74  e multi-argument
1ba10 20 6d 61 78 28 29 20 66 75 6e 63 74 69 6f 6e 20   max() function 
1ba20 72 65 74 75 72 6e 73 20 74 68 65 20 61 72 67 75  returns the argu
1ba30 6d 65 6e 74 20 77 69 74 68 20 74 68 65 20 0a 20  ment with the . 
1ba40 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 2c 20   maximum value, 
1ba50 6f 72 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  or return NULL i
1ba60 66 20 61 6e 79 20 61 72 67 75 6d 65 6e 74 20 69  f any argument i
1ba70 73 20 4e 55 4c 4c 2e 20 0a 20 20 5e 54 68 65 20  s NULL. .  ^The 
1ba80 6d 75 6c 74 69 2d 61 72 67 75 6d 65 6e 74 20 6d  multi-argument m
1ba90 61 78 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 65  ax() function se
1baa0 61 72 63 68 65 73 20 69 74 73 20 61 72 67 75 6d  arches its argum
1bab0 65 6e 74 73 20 66 72 6f 6d 20 6c 65 66 74 20 74  ents from left t
1bac0 6f 20 72 69 67 68 74 0a 20 20 66 6f 72 20 61 6e  o right.  for an
1bad0 20 61 72 67 75 6d 65 6e 74 20 74 68 61 74 20 64   argument that d
1bae0 65 66 69 6e 65 73 20 61 20 63 6f 6c 6c 61 74 69  efines a collati
1baf0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20  ng function and 
1bb00 75 73 65 73 20 74 68 61 74 20 63 6f 6c 6c 61 74  uses that collat
1bb10 69 6e 67 0a 20 20 66 75 6e 63 74 69 6f 6e 20 66  ing.  function f
1bb20 6f 72 20 61 6c 6c 20 73 74 72 69 6e 67 20 63 6f  or all string co
1bb30 6d 70 61 72 69 73 6f 6e 73 2e 20 20 5e 49 66 20  mparisons.  ^If 
1bb40 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 72 67 75  none of the argu
1bb50 6d 65 6e 74 73 20 74 6f 20 6d 61 78 28 29 0a 20  ments to max(). 
1bb60 20 64 65 66 69 6e 65 20 61 20 63 6f 6c 6c 61 74   define a collat
1bb70 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68  ing function, th
1bb80 65 6e 20 74 68 65 20 42 49 4e 41 52 59 20 63 6f  en the BINARY co
1bb90 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
1bba0 20 69 73 20 75 73 65 64 2e 0a 20 20 5e 28 4e 6f   is used..  ^(No
1bbb0 74 65 20 74 68 61 74 20 3c 62 3e 6d 61 78 28 29  te that <b>max()
1bbc0 3c 2f 62 3e 20 69 73 20 61 20 73 69 6d 70 6c 65  </b> is a simple
1bbd0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 0a 20   function when. 
1bbe0 20 69 74 20 68 61 73 20 32 20 6f 72 20 6d 6f 72   it has 2 or mor
1bbf0 65 20 61 72 67 75 6d 65 6e 74 73 20 62 75 74 20  e arguments but 
1bc00 6f 70 65 72 61 74 65 73 20 61 73 20 61 6e 0a 20  operates as an. 
1bc10 20 5b 6d 61 78 41 67 67 46 75 6e 63 20 7c 20 61   [maxAggFunc | a
1bc20 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
1bc30 6e 5d 20 69 66 20 67 69 76 65 6e 20 6f 6e 6c 79  n] if given only
1bc40 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
1bc50 6e 74 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66  nt.)^.}..funcdef
1bc60 20 7b 6d 69 6e 28 58 2c 59 2c 2e 2e 2e 29 7d 20   {min(X,Y,...)} 
1bc70 7b 2a 6d 69 6e 43 6f 72 65 46 75 6e 63 20 2a 6d  {*minCoreFunc *m
1bc80 69 6e 20 7b 6d 69 6e 28 29 20 53 51 4c 20 66 75  in {min() SQL fu
1bc90 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68  nction}} {.  ^Th
1bca0 65 20 6d 75 6c 74 69 2d 61 72 67 75 6d 65 6e 74  e multi-argument
1bcb0 20 6d 69 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20   min() function 
1bcc0 72 65 74 75 72 6e 73 20 74 68 65 20 61 72 67 75  returns the argu
1bcd0 6d 65 6e 74 20 77 69 74 68 20 74 68 65 0a 20 20  ment with the.  
1bce0 6d 69 6e 69 6d 75 6d 20 76 61 6c 75 65 2e 0a 20  minimum value.. 
1bcf0 20 5e 54 68 65 20 6d 75 6c 74 69 2d 61 72 67 75   ^The multi-argu
1bd00 6d 65 6e 74 20 6d 69 6e 28 29 20 66 75 6e 63 74  ment min() funct
1bd10 69 6f 6e 20 73 65 61 72 63 68 65 73 20 69 74 73  ion searches its
1bd20 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20   arguments from 
1bd30 6c 65 66 74 20 74 6f 20 72 69 67 68 74 0a 20 20  left to right.  
1bd40 66 6f 72 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  for an argument 
1bd50 74 68 61 74 20 64 65 66 69 6e 65 73 20 61 20 63  that defines a c
1bd60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
1bd70 6e 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  n and uses that 
1bd80 63 6f 6c 6c 61 74 69 6e 67 0a 20 20 66 75 6e 63  collating.  func
1bd90 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 73 74 72  tion for all str
1bda0 69 6e 67 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e  ing comparisons.
1bdb0 20 20 5e 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68    ^If none of th
1bdc0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 6d  e arguments to m
1bdd0 69 6e 28 29 0a 20 20 64 65 66 69 6e 65 20 61 20  in().  define a 
1bde0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
1bdf0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 42 49 4e  on, then the BIN
1be00 41 52 59 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ARY collating fu
1be10 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  nction is used..
1be20 20 20 5e 28 4e 6f 74 65 20 74 68 61 74 20 3c 62    ^(Note that <b
1be30 3e 6d 69 6e 28 29 3c 2f 62 3e 20 69 73 20 61 20  >min()</b> is a 
1be40 73 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f 6e 20  simple function 
1be50 77 68 65 6e 0a 20 20 69 74 20 68 61 73 20 32 20  when.  it has 2 
1be60 6f 72 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e 74  or more argument
1be70 73 20 62 75 74 20 6f 70 65 72 61 74 65 73 20 61  s but operates a
1be80 73 20 61 6e 20 0a 20 20 5b 6d 69 6e 41 67 67 46  s an .  [minAggF
1be90 75 6e 63 20 7c 20 61 67 67 72 65 67 61 74 65 20  unc | aggregate 
1bea0 66 75 6e 63 74 69 6f 6e 5d 20 69 66 20 67 69 76  function] if giv
1beb0 65 6e 0a 20 20 6f 6e 6c 79 20 61 20 73 69 6e 67  en.  only a sing
1bec0 6c 65 20 61 72 67 75 6d 65 6e 74 2e 29 5e 0a 7d  le argument.)^.}
1bed0 0a 0a 66 75 6e 63 64 65 66 20 7b 6e 75 6c 6c 69  ..funcdef {nulli
1bee0 66 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e  f(X,Y)} {} {.  ^
1bef0 54 68 65 20 6e 75 6c 6c 69 66 28 58 2c 59 29 20  The nullif(X,Y) 
1bf00 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1bf10 20 69 74 73 20 66 69 72 73 74 20 61 72 67 75 6d   its first argum
1bf20 65 6e 74 20 69 66 20 74 68 65 20 61 72 67 75 6d  ent if the argum
1bf30 65 6e 74 73 20 61 72 65 0a 20 20 64 69 66 66 65  ents are.  diffe
1bf40 72 65 6e 74 20 61 6e 64 20 4e 55 4c 4c 20 69 66  rent and NULL if
1bf50 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20 61   the arguments a
1bf60 72 65 20 74 68 65 20 73 61 6d 65 2e 20 20 5e 54  re the same.  ^T
1bf70 68 65 20 6e 75 6c 6c 69 66 28 58 2c 59 29 20 66  he nullif(X,Y) f
1bf80 75 6e 63 74 69 6f 6e 0a 20 20 73 65 61 72 63 68  unction.  search
1bf90 65 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 73  es its arguments
1bfa0 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69   from left to ri
1bfb0 67 68 74 20 66 6f 72 20 61 6e 20 61 72 67 75 6d  ght for an argum
1bfc0 65 6e 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ent that defines
1bfd0 20 61 0a 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66   a.  collating f
1bfe0 75 6e 63 74 69 6f 6e 20 61 6e 64 20 75 73 65 73  unction and uses
1bff0 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6e 67 20   that collating 
1c000 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  function for all
1c010 20 73 74 72 69 6e 67 0a 20 20 63 6f 6d 70 61 72   string.  compar
1c020 69 73 6f 6e 73 2e 20 20 5e 49 66 20 6e 65 69 74  isons.  ^If neit
1c030 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
1c040 6e 75 6c 6c 69 66 28 29 20 64 65 66 69 6e 65 73  nullif() defines
1c050 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
1c060 63 74 69 6f 6e 0a 20 20 74 68 65 6e 20 74 68 65  ction.  then the
1c070 20 42 49 4e 41 52 59 20 69 73 20 75 73 65 64 2e   BINARY is used.
1c080 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 70 72 69  .}..funcdef {pri
1c090 6e 74 66 28 46 4f 52 4d 41 54 2c 2e 2e 2e 29 7d  ntf(FORMAT,...)}
1c0a0 20 7b 7d 20 7b 0a 20 20 5e 28 54 68 65 20 70 72   {} {.  ^(The pr
1c0b0 69 6e 74 66 28 46 4f 52 4d 41 54 2c 2e 2e 2e 29  intf(FORMAT,...)
1c0c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 6f   SQL function wo
1c0d0 72 6b 73 20 6c 69 6b 65 20 74 68 65 20 5b 73 71  rks like the [sq
1c0e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
1c0f0 20 43 2d 6c 61 6e 67 75 61 67 65 0a 20 20 66 75   C-language.  fu
1c100 6e 63 74 69 6f 6e 20 61 6e 64 20 74 68 65 20 70  nction and the p
1c110 72 69 6e 74 66 28 29 20 66 75 6e 63 74 69 6f 6e  rintf() function
1c120 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1c130 72 64 20 43 20 6c 69 62 72 61 72 79 2e 29 5e 0a  rd C library.)^.
1c140 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
1c150 6d 65 6e 74 20 69 73 20 61 20 66 6f 72 6d 61 74  ment is a format
1c160 20 73 74 72 69 6e 67 20 74 68 61 74 20 73 70 65   string that spe
1c170 63 69 66 69 65 73 20 68 6f 77 20 74 6f 20 63 6f  cifies how to co
1c180 6e 73 74 72 75 63 74 20 74 68 65 20 6f 75 74 70  nstruct the outp
1c190 75 74 0a 20 20 73 74 72 69 6e 67 20 75 73 69 6e  ut.  string usin
1c1a0 67 20 76 61 6c 75 65 73 20 74 61 6b 65 6e 20 66  g values taken f
1c1b0 72 6f 6d 20 73 75 62 73 65 71 75 65 6e 74 20 61  rom subsequent a
1c1c0 72 67 75 6d 65 6e 74 73 2e 20 20 5e 49 66 20 74  rguments.  ^If t
1c1d0 68 65 20 46 4f 52 4d 41 54 20 61 72 67 75 6d 65  he FORMAT argume
1c1e0 6e 74 20 69 73 0a 20 20 6d 69 73 73 69 6e 67 20  nt is.  missing 
1c1f0 6f 72 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  or NULL then the
1c200 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2e   result is NULL.
1c210 20 20 5e 54 68 65 20 25 6e 20 66 6f 72 6d 61 74    ^The %n format
1c220 20 69 73 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e   is silently ign
1c230 6f 72 65 64 20 61 6e 64 0a 20 20 64 6f 65 73 20  ored and.  does 
1c240 6e 6f 74 20 63 6f 6e 73 75 6d 65 20 61 6e 20 61  not consume an a
1c250 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 25  rgument.  ^The %
1c260 70 20 66 6f 72 6d 61 74 20 69 73 20 61 6e 20 61  p format is an a
1c270 6c 69 61 73 20 66 6f 72 20 25 58 2e 20 20 5e 54  lias for %X.  ^T
1c280 68 65 20 25 7a 20 66 6f 72 6d 61 74 0a 20 20 69  he %z format.  i
1c290 73 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  s interchangeabl
1c2a0 65 20 77 69 74 68 20 25 73 2e 20 20 5e 28 49 66  e with %s.  ^(If
1c2b0 20 74 68 65 72 65 20 61 72 65 20 74 6f 6f 20 66   there are too f
1c2c0 65 77 20 61 72 67 75 6d 65 6e 74 73 20 69 6e 20  ew arguments in 
1c2d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1c2e0 74 2c 0a 20 20 6d 69 73 73 69 6e 67 20 61 72 67  t,.  missing arg
1c2f0 75 6d 65 6e 74 73 20 61 72 65 20 61 73 73 75 6d  uments are assum
1c300 65 64 20 74 6f 20 68 61 76 65 20 61 20 4e 55 4c  ed to have a NUL
1c310 4c 20 76 61 6c 75 65 2c 20 77 68 69 63 68 20 69  L value, which i
1c320 73 20 74 72 61 6e 73 6c 61 74 65 64 20 69 6e 74  s translated int
1c330 6f 0a 20 20 30 20 6f 72 20 30 2e 30 20 66 6f 72  o.  0 or 0.0 for
1c340 20 6e 75 6d 65 72 69 63 20 66 6f 72 6d 61 74 73   numeric formats
1c350 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
1c360 69 6e 67 20 66 6f 72 20 25 73 2e 29 5e 0a 7d 0a  ing for %s.)^.}.
1c370 20 20 0a 0a 66 75 6e 63 64 65 66 20 7b 71 75 6f    ..funcdef {quo
1c380 74 65 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  te(X)} {} {.  ^T
1c390 68 65 20 71 75 6f 74 65 28 58 29 20 66 75 6e 63  he quote(X) func
1c3a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1c3b0 20 74 65 78 74 20 6f 66 20 61 6e 20 53 51 4c 20   text of an SQL 
1c3c0 6c 69 74 65 72 61 6c 20 77 68 69 63 68 0a 20 20  literal which.  
1c3d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
1c3e0 69 74 73 20 61 72 67 75 6d 65 6e 74 20 73 75 69  its argument sui
1c3f0 74 61 62 6c 65 20 66 6f 72 20 69 6e 63 6c 75 73  table for inclus
1c400 69 6f 6e 20 69 6e 74 6f 20 61 6e 20 53 51 4c 20  ion into an SQL 
1c410 73 74 61 74 65 6d 65 6e 74 2e 0a 20 20 5e 53 74  statement..  ^St
1c420 72 69 6e 67 73 20 61 72 65 20 73 75 72 72 6f 75  rings are surrou
1c430 6e 64 65 64 20 62 79 20 73 69 6e 67 6c 65 2d 71  nded by single-q
1c440 75 6f 74 65 73 20 77 69 74 68 20 65 73 63 61 70  uotes with escap
1c450 65 73 20 6f 6e 20 69 6e 74 65 72 69 6f 72 20 71  es on interior q
1c460 75 6f 74 65 73 0a 20 20 61 73 20 6e 65 65 64 65  uotes.  as neede
1c470 64 2e 20 20 5e 42 4c 4f 42 73 20 61 72 65 20 65  d.  ^BLOBs are e
1c480 6e 63 6f 64 65 64 20 61 73 20 68 65 78 61 64 65  ncoded as hexade
1c490 63 69 6d 61 6c 20 6c 69 74 65 72 61 6c 73 2e 0a  cimal literals..
1c4a0 20 20 5e 53 74 72 69 6e 67 73 20 77 69 74 68 20    ^Strings with 
1c4b0 65 6d 62 65 64 64 65 64 20 4e 55 4c 20 63 68 61  embedded NUL cha
1c4c0 72 61 63 74 65 72 73 20 63 61 6e 6e 6f 74 20 62  racters cannot b
1c4d0 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  e represented as
1c4e0 20 73 74 72 69 6e 67 0a 20 20 6c 69 74 65 72 61   string.  litera
1c4f0 6c 73 20 69 6e 20 53 51 4c 20 61 6e 64 20 68 65  ls in SQL and he
1c500 6e 63 65 20 74 68 65 20 72 65 74 75 72 6e 65 64  nce the returned
1c510 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
1c520 69 73 20 74 72 75 6e 63 61 74 65 64 20 70 72 69  is truncated pri
1c530 6f 72 0a 20 20 74 6f 20 74 68 65 20 66 69 72 73  or.  to the firs
1c540 74 20 4e 55 4c 2e 0a 7d 0a 0a 66 75 6e 63 64 65  t NUL..}..funcde
1c550 66 20 7b 72 61 6e 64 6f 6d 28 29 7d 20 7b 7d 20  f {random()} {} 
1c560 7b 0a 20 20 5e 54 68 65 20 72 61 6e 64 6f 6d 28  {.  ^The random(
1c570 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1c580 6e 73 20 61 20 70 73 65 75 64 6f 2d 72 61 6e 64  ns a pseudo-rand
1c590 6f 6d 20 69 6e 74 65 67 65 72 0a 20 20 62 65 74  om integer.  bet
1c5a0 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
1c5b0 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
1c5c0 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
1c5d0 30 37 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  07..}..funcdef {
1c5e0 72 61 6e 64 6f 6d 62 6c 6f 62 28 4e 29 7d 20 7b  randomblob(N)} {
1c5f0 7d 20 7b 0a 20 20 5e 54 68 65 20 72 61 6e 64 6f  } {.  ^The rando
1c600 6d 62 6c 6f 62 28 4e 29 20 66 75 6e 63 74 69 6f  mblob(N) functio
1c610 6e 20 72 65 74 75 72 6e 20 61 6e 20 4e 2d 62 79  n return an N-by
1c620 74 65 20 62 6c 6f 62 20 63 6f 6e 74 61 69 6e 69  te blob containi
1c630 6e 67 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ng pseudo-random
1c640 0a 20 20 62 79 74 65 73 2e 20 5e 49 66 20 4e 20  .  bytes. ^If N 
1c650 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 20 74  is less than 1 t
1c660 68 65 6e 20 61 20 31 2d 62 79 74 65 20 72 61 6e  hen a 1-byte ran
1c670 64 6f 6d 20 62 6c 6f 62 20 69 73 20 72 65 74 75  dom blob is retu
1c680 72 6e 65 64 2e 0a 0a 20 20 3c 70 3e 48 69 6e 74  rned...  <p>Hint
1c690 3a 20 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  :  applications 
1c6a0 63 61 6e 20 67 65 6e 65 72 61 74 65 20 67 6c 6f  can generate glo
1c6b0 62 61 6c 6c 79 20 75 6e 69 71 75 65 20 69 64 65  bally unique ide
1c6c0 6e 74 69 66 69 65 72 73 0a 20 20 75 73 69 6e 67  ntifiers.  using
1c6d0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 74   this function t
1c6e0 6f 67 65 74 68 65 72 20 77 69 74 68 20 5b 68 65  ogether with [he
1c6f0 78 28 29 5d 20 61 6e 64 2f 6f 72 0a 20 20 5b 6c  x()] and/or.  [l
1c700 6f 77 65 72 28 29 5d 20 6c 69 6b 65 20 74 68 69  ower()] like thi
1c710 73 3a 3c 2f 70 3e 0a 0a 20 20 3c 62 6c 6f 63 6b  s:</p>..  <block
1c720 71 75 6f 74 65 3e 0a 20 20 68 65 78 28 72 61 6e  quote>.  hex(ran
1c730 64 6f 6d 62 6c 6f 62 28 31 36 29 29 3c 62 72 3e  domblob(16))<br>
1c740 3c 2f 62 72 3e 0a 20 20 6c 6f 77 65 72 28 68 65  </br>.  lower(he
1c750 78 28 72 61 6e 64 6f 6d 62 6c 6f 62 28 31 36 29  x(randomblob(16)
1c760 29 29 0a 20 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  )).  </blockquot
1c770 65 3e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 72  e>.}..funcdef {r
1c780 65 70 6c 61 63 65 28 58 2c 59 2c 5a 29 7d 20 7b  eplace(X,Y,Z)} {
1c790 7d 20 7b 0a 20 20 5e 54 68 65 20 72 65 70 6c 61  } {.  ^The repla
1c7a0 63 65 28 58 2c 59 2c 5a 29 20 66 75 6e 63 74 69  ce(X,Y,Z) functi
1c7b0 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73 74 72  on returns a str
1c7c0 69 6e 67 20 66 6f 72 6d 65 64 20 62 79 20 73 75  ing formed by su
1c7d0 62 73 74 69 74 75 74 69 6e 67 0a 20 20 73 74 72  bstituting.  str
1c7e0 69 6e 67 20 5a 20 66 6f 72 20 65 76 65 72 79 20  ing Z for every 
1c7f0 6f 63 63 75 72 72 65 6e 63 65 20 6f 66 20 73 74  occurrence of st
1c800 72 69 6e 67 20 59 20 69 6e 20 73 74 72 69 6e 67  ring Y in string
1c810 20 58 2e 20 20 5e 54 68 65 20 5b 42 49 4e 41 52   X.  ^The [BINAR
1c820 59 5d 0a 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73  Y].  collating s
1c830 65 71 75 65 6e 63 65 20 69 73 20 75 73 65 64 20  equence is used 
1c840 66 6f 72 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e  for comparisons.
1c850 20 20 5e 49 66 20 59 20 69 73 20 61 6e 20 65 6d    ^If Y is an em
1c860 70 74 79 0a 20 20 73 74 72 69 6e 67 20 74 68 65  pty.  string the
1c870 6e 20 72 65 74 75 72 6e 20 58 20 75 6e 63 68 61  n return X uncha
1c880 6e 67 65 64 2e 20 20 5e 49 66 20 5a 20 69 73 20  nged.  ^If Z is 
1c890 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 0a 20 20  not initially.  
1c8a0 61 20 73 74 72 69 6e 67 2c 20 69 74 20 69 73 20  a string, it is 
1c8b0 63 61 73 74 20 74 6f 20 61 20 55 54 46 2d 38 20  cast to a UTF-8 
1c8c0 73 74 72 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  string prior to 
1c8d0 70 72 6f 63 65 73 73 69 6e 67 2e 0a 7d 0a 0a 66  processing..}..f
1c8e0 75 6e 63 64 65 66 20 7b 72 6f 75 6e 64 28 58 29  uncdef {round(X)
1c8f0 20 72 6f 75 6e 64 28 58 2c 59 29 7d 20 7b 7d 20   round(X,Y)} {} 
1c900 7b 0a 20 20 5e 54 68 65 20 72 6f 75 6e 64 28 58  {.  ^The round(X
1c910 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ,Y) function ret
1c920 75 72 6e 73 20 61 20 66 6c 6f 61 74 69 6e 67 2d  urns a floating-
1c930 70 6f 69 6e 74 0a 20 20 76 61 6c 75 65 20 58 20  point.  value X 
1c940 72 6f 75 6e 64 65 64 20 74 6f 20 59 20 64 69 67  rounded to Y dig
1c950 69 74 73 20 74 6f 20 74 68 65 20 72 69 67 68 74  its to the right
1c960 20 6f 66 20 74 68 65 20 64 65 63 69 6d 61 6c 20   of the decimal 
1c970 70 6f 69 6e 74 2e 0a 20 20 5e 49 66 20 74 68 65  point..  ^If the
1c980 20 59 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   Y argument is o
1c990 6d 69 74 74 65 64 2c 20 69 74 20 69 73 20 61 73  mitted, it is as
1c9a0 73 75 6d 65 64 20 74 6f 20 62 65 20 30 2e 0a 7d  sumed to be 0..}
1c9b0 0a 0a 66 75 6e 63 64 65 66 20 7b 72 74 72 69 6d  ..funcdef {rtrim
1c9c0 28 58 29 20 72 74 72 69 6d 28 58 2c 59 29 7d 20  (X) rtrim(X,Y)} 
1c9d0 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72 74 72 69  {} {.  ^The rtri
1c9e0 6d 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20  m(X,Y) function 
1c9f0 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e 67  returns a string
1ca00 20 66 6f 72 6d 65 64 20 62 79 20 72 65 6d 6f 76   formed by remov
1ca10 69 6e 67 20 61 6e 79 20 61 6e 64 20 61 6c 6c 0a  ing any and all.
1ca20 20 20 63 68 61 72 61 63 74 65 72 73 20 74 68 61    characters tha
1ca30 74 20 61 70 70 65 61 72 20 69 6e 20 59 20 66 72  t appear in Y fr
1ca40 6f 6d 20 74 68 65 20 72 69 67 68 74 20 73 69 64  om the right sid
1ca50 65 20 6f 66 20 58 2e 0a 20 20 5e 49 66 20 74 68  e of X..  ^If th
1ca60 65 20 59 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e Y argument is 
1ca70 6f 6d 69 74 74 65 64 2c 20 72 74 72 69 6d 28 58  omitted, rtrim(X
1ca80 29 20 72 65 6d 6f 76 65 73 20 73 70 61 63 65 73  ) removes spaces
1ca90 20 66 72 6f 6d 20 74 68 65 20 72 69 67 68 74 0a   from the right.
1caa0 20 20 73 69 64 65 20 6f 66 20 58 2e 0a 7d 0a 0a    side of X..}..
1cab0 66 75 6e 63 64 65 66 20 7b 73 6f 75 6e 64 65 78  funcdef {soundex
1cac0 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65  (X)} {} {.  ^The
1cad0 20 73 6f 75 6e 64 65 78 28 58 29 20 66 75 6e 63   soundex(X) func
1cae0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73  tion returns a s
1caf0 74 72 69 6e 67 20 74 68 61 74 20 69 73 20 74 68  tring that is th
1cb00 65 20 73 6f 75 6e 64 65 78 20 65 6e 63 6f 64 69  e soundex encodi
1cb10 6e 67 20 0a 20 20 6f 66 20 74 68 65 20 73 74 72  ng .  of the str
1cb20 69 6e 67 20 58 2e 0a 20 20 5e 54 68 65 20 73 74  ing X..  ^The st
1cb30 72 69 6e 67 20 22 3f 30 30 30 22 20 69 73 20 72  ring "?000" is r
1cb40 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 61  eturned if the a
1cb50 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
1cb60 6f 72 20 63 6f 6e 74 61 69 6e 73 0a 20 20 6e 6f  or contains.  no
1cb70 20 41 53 43 49 49 20 61 6c 70 68 61 62 65 74 69   ASCII alphabeti
1cb80 63 20 63 68 61 72 61 63 74 65 72 73 2e 0a 20 20  c characters..  
1cb90 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
1cba0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
1cbb0 53 51 4c 69 74 65 20 62 79 20 64 65 66 61 75 6c  SQLite by defaul
1cbc0 74 2e 0a 20 20 49 74 20 69 73 20 6f 6e 6c 79 20  t..  It is only 
1cbd0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
1cbe0 20 5b 53 51 4c 49 54 45 5f 53 4f 55 4e 44 45 58   [SQLITE_SOUNDEX
1cbf0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1cc00 70 74 69 6f 6e 0a 20 20 69 73 20 75 73 65 64 20  ption.  is used 
1cc10 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 62  when SQLite is b
1cc20 75 69 6c 74 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64  uilt.)^.}..funcd
1cc30 65 66 20 7b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ef {sqlite_compi
1cc40 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 4e 29 7d  leoption_get(N)}
1cc50 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 73 71 6c   {} {.  ^The sql
1cc60 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1cc70 6e 5f 67 65 74 28 29 20 53 51 4c 20 66 75 6e 63  n_get() SQL func
1cc80 74 69 6f 6e 20 69 73 20 61 20 77 72 61 70 70 65  tion is a wrappe
1cc90 72 20 61 72 6f 75 6e 64 20 74 68 65 0a 20 20 5b  r around the.  [
1cca0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1ccb0 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 43 2f 43  ption_get()] C/C
1ccc0 2b 2b 20 66 75 6e 63 74 69 6f 6e 2e 0a 20 20 5e  ++ function..  ^
1ccd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1cce0 75 72 6e 73 20 74 68 65 20 4e 2d 74 68 20 63 6f  urns the N-th co
1ccf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1cd00 6e 20 75 73 65 64 20 74 6f 20 62 75 69 6c 64 20  n used to build 
1cd10 53 51 4c 69 74 65 0a 20 20 6f 72 20 4e 55 4c 4c  SQLite.  or NULL
1cd20 20 69 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20   if N is out of 
1cd30 72 61 6e 67 65 2e 20 20 53 65 65 20 61 6c 73 6f  range.  See also
1cd40 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1cd50 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 7d  tions pragma]..}
1cd60 0a 0a 66 75 6e 63 64 65 66 20 7b 73 71 6c 69 74  ..funcdef {sqlit
1cd70 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1cd80 75 73 65 64 28 58 29 7d 20 7b 7d 20 7b 0a 20 20  used(X)} {} {.  
1cd90 5e 54 68 65 20 73 71 6c 69 74 65 5f 63 6f 6d 70  ^The sqlite_comp
1cda0 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1cdb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
1cdc0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1cdd0 64 20 74 68 65 0a 20 20 5b 73 71 6c 69 74 65 33  d the.  [sqlite3
1cde0 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1cdf0 73 65 64 28 29 5d 20 43 2f 43 2b 2b 20 66 75 6e  sed()] C/C++ fun
1ce00 63 74 69 6f 6e 2e 0a 20 20 5e 57 68 65 6e 20 74  ction..  ^When t
1ce10 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 74 6f  he argument X to
1ce20 20 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f   sqlite_compileo
1ce30 70 74 69 6f 6e 5f 75 73 65 64 28 58 29 20 69 73  ption_used(X) is
1ce40 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a   a string which.
1ce50 20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66    is the name of
1ce60 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
1ce70 6f 70 74 69 6f 6e 2c 20 74 68 69 73 20 72 6f 75  option, this rou
1ce80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
1ce90 65 20 28 31 29 20 6f 72 0a 20 20 66 61 6c 73 65  e (1) or.  false
1cea0 20 28 30 29 20 64 65 70 65 6e 64 69 6e 67 20 6f   (0) depending o
1ceb0 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
1cec0 20 74 68 61 74 20 6f 70 74 69 6f 6e 20 77 61 73   that option was
1ced0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 68 65   used during the
1cee0 0a 20 20 62 75 69 6c 64 2e 0a 7d 0a 0a 66 75 6e  .  build..}..fun
1cef0 63 64 65 66 20 7b 73 71 6c 69 74 65 5f 73 6f 75  cdef {sqlite_sou
1cf00 72 63 65 5f 69 64 28 29 7d 20 7b 7d 20 7b 0a 20  rce_id()} {} {. 
1cf10 20 5e 54 68 65 20 73 71 6c 69 74 65 5f 73 6f 75   ^The sqlite_sou
1cf20 72 63 65 5f 69 64 28 29 20 66 75 6e 63 74 69 6f  rce_id() functio
1cf30 6e 20 72 65 74 75 72 6e 73 20 61 20 73 74 72 69  n returns a stri
1cf40 6e 67 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  ng that identifi
1cf50 65 73 20 74 68 65 0a 20 20 73 70 65 63 69 66 69  es the.  specifi
1cf60 63 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  c version of the
1cf70 20 73 6f 75 72 63 65 20 63 6f 64 65 20 74 68 61   source code tha
1cf80 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 62 75  t was used to bu
1cf90 69 6c 64 20 74 68 65 20 53 51 4c 69 74 65 0a 20  ild the SQLite. 
1cfa0 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
1cfb0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
1cfc0 62 79 20 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  by sqlite_source
1cfd0 5f 69 64 28 29 20 69 73 0a 20 20 74 68 65 20 64  _id() is.  the d
1cfe0 61 74 65 20 61 6e 64 20 74 69 6d 65 20 74 68 61  ate and time tha
1cff0 74 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64  t the source cod
1d000 65 20 77 61 73 20 63 68 65 63 6b 65 64 20 69 6e  e was checked in
1d010 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 20 20 74   followed by.  t
1d020 68 65 20 53 48 41 31 20 68 61 73 68 20 66 6f 72  he SHA1 hash for
1d030 20 74 68 61 74 20 63 68 65 63 6b 2d 69 6e 2e 20   that check-in. 
1d040 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1d050 69 73 0a 20 20 61 6e 20 53 51 4c 20 77 72 61 70  is.  an SQL wrap
1d060 70 65 72 20 61 72 6f 75 6e 64 20 74 68 65 20 5b  per around the [
1d070 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1d080 28 29 5d 20 43 20 69 6e 74 65 72 66 61 63 65 2e  ()] C interface.
1d090 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 73 71 6c  .}..funcdef {sql
1d0a0 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 7d 20 7b  ite_version()} {
1d0b0 7d 20 7b 0a 20 20 5e 54 68 65 20 73 71 6c 69 74  } {.  ^The sqlit
1d0c0 65 5f 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  e_version() func
1d0d0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1d0e0 20 76 65 72 73 69 6f 6e 20 73 74 72 69 6e 67 20   version string 
1d0f0 66 6f 72 20 74 68 65 20 53 51 4c 69 74 65 0a 20  for the SQLite. 
1d100 20 6c 69 62 72 61 72 79 20 74 68 61 74 20 69 73   library that is
1d110 20 72 75 6e 6e 69 6e 67 2e 20 20 5e 54 68 69 73   running.  ^This
1d120 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
1d130 53 51 4c 0a 20 20 77 72 61 70 70 65 72 20 61 72  SQL.  wrapper ar
1d140 6f 75 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65  ound the [sqlite
1d150 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20  3_libversion()] 
1d160 43 2d 69 6e 74 65 72 66 61 63 65 2e 0a 7d 0a 0a  C-interface..}..
1d170 66 75 6e 63 64 65 66 20 7b 73 75 62 73 74 72 28  funcdef {substr(
1d180 58 2c 59 2c 5a 29 20 73 75 62 73 74 72 28 58 2c  X,Y,Z) substr(X,
1d190 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20  Y)} {} {.  ^The 
1d1a0 73 75 62 73 74 72 28 58 2c 59 2c 5a 29 20 66 75  substr(X,Y,Z) fu
1d1b0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1d1c0 20 73 75 62 73 74 72 69 6e 67 20 6f 66 20 69 6e   substring of in
1d1d0 70 75 74 20 73 74 72 69 6e 67 20 58 20 74 68 61  put string X tha
1d1e0 74 20 62 65 67 69 6e 73 0a 20 20 77 69 74 68 20  t begins.  with 
1d1f0 74 68 65 20 59 2d 74 68 20 63 68 61 72 61 63 74  the Y-th charact
1d200 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
1d210 5a 20 63 68 61 72 61 63 74 65 72 73 20 6c 6f 6e  Z characters lon
1d220 67 2e 0a 20 20 5e 49 66 20 5a 20 69 73 20 6f 6d  g..  ^If Z is om
1d230 69 74 74 65 64 20 74 68 65 6e 20 73 75 62 73 74  itted then subst
1d240 72 28 58 2c 59 29 20 72 65 74 75 72 6e 73 20 61  r(X,Y) returns a
1d250 6c 6c 20 63 68 61 72 61 63 74 65 72 73 20 74 68  ll characters th
1d260 72 6f 75 67 68 20 74 68 65 20 65 6e 64 0a 20 20  rough the end.  
1d270 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 58 20  of the string X 
1d280 62 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 74  beginning with t
1d290 68 65 20 59 2d 74 68 2e 0a 20 20 5e 54 68 65 20  he Y-th..  ^The 
1d2a0 6c 65 66 74 2d 6d 6f 73 74 20 63 68 61 72 61 63  left-most charac
1d2b0 74 65 72 20 6f 66 20 58 20 69 73 20 6e 75 6d 62  ter of X is numb
1d2c0 65 72 20 31 2e 20 20 5e 49 66 20 59 20 69 73 20  er 1.  ^If Y is 
1d2d0 6e 65 67 61 74 69 76 65 0a 20 20 74 68 65 6e 20  negative.  then 
1d2e0 74 68 65 20 66 69 72 73 74 20 63 68 61 72 61 63  the first charac
1d2f0 74 65 72 20 6f 66 20 74 68 65 20 73 75 62 73 74  ter of the subst
1d300 72 69 6e 67 20 69 73 20 66 6f 75 6e 64 20 62 79  ring is found by
1d310 20 63 6f 75 6e 74 69 6e 67 20 66 72 6f 6d 20 74   counting from t
1d320 68 65 0a 20 20 72 69 67 68 74 20 72 61 74 68 65  he.  right rathe
1d330 72 20 74 68 61 6e 20 74 68 65 20 6c 65 66 74 2e  r than the left.
1d340 20 20 5e 49 66 20 5a 20 69 73 20 6e 65 67 61 74    ^If Z is negat
1d350 69 76 65 20 74 68 65 6e 0a 20 20 74 68 65 20 61  ive then.  the a
1d360 62 73 28 5a 29 20 63 68 61 72 61 63 74 65 72 73  bs(Z) characters
1d370 20 70 72 65 63 65 64 69 6e 67 20 74 68 65 20 59   preceding the Y
1d380 2d 74 68 20 63 68 61 72 61 63 74 65 72 20 61 72  -th character ar
1d390 65 20 72 65 74 75 72 6e 65 64 2e 0a 20 20 5e 49  e returned..  ^I
1d3a0 66 20 58 20 69 73 20 61 20 73 74 72 69 6e 67 20  f X is a string 
1d3b0 74 68 65 6e 20 63 68 61 72 61 63 74 65 72 73 20  then characters 
1d3c0 69 6e 64 69 63 65 73 20 72 65 66 65 72 20 74 6f  indices refer to
1d3d0 20 61 63 74 75 61 6c 20 55 54 46 2d 38 20 0a 20   actual UTF-8 . 
1d3e0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 5e 49   characters.  ^I
1d3f0 66 20 58 20 69 73 20 61 20 42 4c 4f 42 20 74 68  f X is a BLOB th
1d400 65 6e 20 74 68 65 20 69 6e 64 69 63 65 73 20 72  en the indices r
1d410 65 66 65 72 20 74 6f 20 62 79 74 65 73 2e 0a 7d  efer to bytes..}
1d420 0a 0a 66 75 6e 63 64 65 66 20 7b 74 6f 74 61 6c  ..funcdef {total
1d430 5f 63 68 61 6e 67 65 73 28 29 7d 20 7b 7d 20 7b  _changes()} {} {
1d440 0a 20 20 5e 54 68 65 20 74 6f 74 61 6c 5f 63 68  .  ^The total_ch
1d450 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1d460 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1d470 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
1d480 65 73 0a 20 20 63 61 75 73 65 64 20 62 79 20 49  es.  caused by I
1d490 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1d4a0 20 44 45 4c 45 54 45 0a 20 20 73 74 61 74 65 6d   DELETE.  statem
1d4b0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 63  ents since the c
1d4c0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
1d4d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1d4e0 70 65 6e 65 64 2e 0a 20 20 5e 54 68 69 73 20 66  pened..  ^This f
1d4f0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 77 72 61  unction is a wra
1d500 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68 65 20  pper around the 
1d510 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1d520 68 61 6e 67 65 73 28 29 5d 0a 20 20 43 2f 43 2b  hanges()].  C/C+
1d530 2b 20 69 6e 74 65 72 66 61 63 65 2e 0a 7d 0a 0a  + interface..}..
1d540 66 75 6e 63 64 65 66 20 7b 74 72 69 6d 28 58 29  funcdef {trim(X)
1d550 20 74 72 69 6d 28 58 2c 59 29 7d 20 7b 7d 20 7b   trim(X,Y)} {} {
1d560 0a 20 20 5e 54 68 65 20 74 72 69 6d 28 58 2c 59  .  ^The trim(X,Y
1d570 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1d580 6e 73 20 61 20 73 74 72 69 6e 67 20 66 6f 72 6d  ns a string form
1d590 65 64 20 62 79 20 72 65 6d 6f 76 69 6e 67 20 61  ed by removing a
1d5a0 6e 79 20 61 6e 64 20 61 6c 6c 0a 20 20 63 68 61  ny and all.  cha
1d5b0 72 61 63 74 65 72 73 20 74 68 61 74 20 61 70 70  racters that app
1d5c0 65 61 72 20 69 6e 20 59 20 66 72 6f 6d 20 62 6f  ear in Y from bo
1d5d0 74 68 20 65 6e 64 73 20 6f 66 20 58 2e 0a 20 20  th ends of X..  
1d5e0 5e 49 66 20 74 68 65 20 59 20 61 72 67 75 6d 65  ^If the Y argume
1d5f0 6e 74 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 74  nt is omitted, t
1d600 72 69 6d 28 58 29 20 72 65 6d 6f 76 65 73 20 73  rim(X) removes s
1d610 70 61 63 65 73 20 66 72 6f 6d 20 62 6f 74 68 20  paces from both 
1d620 65 6e 64 73 20 6f 66 20 58 2e 0a 7d 0a 0a 66 75  ends of X..}..fu
1d630 6e 63 64 65 66 20 7b 74 79 70 65 6f 66 28 58 29  ncdef {typeof(X)
1d640 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 74 79  } {} {.  ^The ty
1d650 70 65 6f 66 28 58 29 20 66 75 6e 63 74 69 6f 6e  peof(X) function
1d660 20 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e   returns a strin
1d670 67 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  g that indicates
1d680 20 74 68 65 20 5b 64 61 74 61 74 79 70 65 5d 20   the [datatype] 
1d690 6f 66 0a 20 20 74 68 65 20 65 78 70 72 65 73 73  of.  the express
1d6a0 69 6f 6e 20 58 3a 20 22 6e 75 6c 6c 22 2c 20 22  ion X: "null", "
1d6b0 69 6e 74 65 67 65 72 22 2c 20 22 72 65 61 6c 22  integer", "real"
1d6c0 2c 20 22 74 65 78 74 22 2c 20 6f 72 20 22 62 6c  , "text", or "bl
1d6d0 6f 62 22 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  ob"..}..funcdef 
1d6e0 7b 75 6e 6c 69 6b 65 6c 79 28 58 29 7d 20 7b 7d  {unlikely(X)} {}
1d6f0 20 7b 0a 20 20 5e 54 68 65 20 75 6e 6c 69 6b 65   {.  ^The unlike
1d700 6c 79 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 72  ly(X) function r
1d710 65 74 75 72 6e 73 20 74 68 65 20 61 72 67 75 6d  eturns the argum
1d720 65 6e 74 20 58 20 75 6e 63 68 61 6e 67 65 64 2e  ent X unchanged.
1d730 0a 20 20 5e 54 68 65 20 75 6e 6c 69 6b 65 6c 79  .  ^The unlikely
1d740 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  (X) function is 
1d750 61 20 6e 6f 2d 6f 70 20 74 68 61 74 20 74 68 65  a no-op that the
1d760 20 63 6f 64 65 20 67 65 6e 65 72 61 74 6f 72 0a   code generator.
1d770 20 20 6f 70 74 69 6d 69 7a 65 73 20 61 77 61 79    optimizes away
1d780 20 73 6f 20 74 68 61 74 20 69 74 20 63 6f 6e 73   so that it cons
1d790 75 6d 65 73 20 6e 6f 20 43 50 55 20 63 79 63 6c  umes no CPU cycl
1d7a0 65 73 20 61 74 0a 20 20 72 75 6e 2d 74 69 6d 65  es at.  run-time
1d7b0 20 28 74 68 61 74 20 69 73 2c 20 64 75 72 69 6e   (that is, durin
1d7c0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
1d7d0 74 65 33 5f 73 74 65 70 28 29 5d 29 2e 0a 20 20  te3_step()])..  
1d7e0 5e 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20  ^The purpose of 
1d7f0 74 68 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20  the unlikely(X) 
1d800 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 70  function is to p
1d810 72 6f 76 69 64 65 20 61 20 68 69 6e 74 0a 20 20  rovide a hint.  
1d820 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  to the query pla
1d830 6e 6e 65 72 20 74 68 61 74 20 74 68 65 20 61 72  nner that the ar
1d840 67 75 6d 65 6e 74 20 58 20 69 73 20 61 20 62 6f  gument X is a bo
1d850 6f 6c 65 61 6e 20 76 61 6c 75 65 0a 20 20 74 68  olean value.  th
1d860 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  at is usually no
1d870 74 20 74 72 75 65 2e 20 5e 28 54 68 65 20 75 6e  t true. ^(The un
1d880 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e 63 74 69  likely(X) functi
1d890 6f 6e 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  on is equivalent
1d8a0 0a 20 20 74 6f 20 5b 6c 69 6b 65 6c 69 68 6f 6f  .  to [likelihoo
1d8b0 64 5d 28 58 2c 20 30 2e 30 36 32 35 29 2e 29 5e  d](X, 0.0625).)^
1d8c0 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 75 6e 69  .}..funcdef {uni
1d8d0 63 6f 64 65 28 58 29 7d 20 7b 7d 20 7b 0a 20 20  code(X)} {} {.  
1d8e0 5e 54 68 65 20 75 6e 69 63 6f 64 65 28 58 29 20  ^The unicode(X) 
1d8f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1d900 20 74 68 65 20 6e 75 6d 65 72 69 63 20 75 6e 69   the numeric uni
1d910 63 6f 64 65 20 63 6f 64 65 20 70 6f 69 6e 74 20  code code point 
1d920 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 74 6f  corresponding to
1d930 0a 20 20 74 68 65 20 66 69 72 73 74 20 63 68 61  .  the first cha
1d940 72 61 63 74 65 72 20 6f 66 20 74 68 65 20 73 74  racter of the st
1d950 72 69 6e 67 20 58 2e 20 20 49 66 20 74 68 65 20  ring X.  If the 
1d960 61 72 67 75 6d 65 6e 74 20 74 6f 20 75 6e 69 63  argument to unic
1d970 6f 64 65 28 58 29 20 69 73 20 6e 6f 74 20 61 20  ode(X) is not a 
1d980 73 74 72 69 6e 67 0a 20 20 74 68 65 6e 20 74 68  string.  then th
1d990 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
1d9a0 66 69 6e 65 64 2e 0a 7d 0a 0a 66 75 6e 63 64 65  fined..}..funcde
1d9b0 66 20 7b 75 70 70 65 72 28 58 29 7d 20 7b 7d 20  f {upper(X)} {} 
1d9c0 7b 0a 20 20 5e 54 68 65 20 75 70 70 65 72 28 58  {.  ^The upper(X
1d9d0 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1d9e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 69 6e 70  ns a copy of inp
1d9f0 75 74 20 73 74 72 69 6e 67 20 58 20 69 6e 20 77  ut string X in w
1da00 68 69 63 68 20 61 6c 6c 20 0a 20 20 6c 6f 77 65  hich all .  lowe
1da10 72 2d 63 61 73 65 20 41 53 43 49 49 20 63 68 61  r-case ASCII cha
1da20 72 61 63 74 65 72 73 20 61 72 65 20 63 6f 6e 76  racters are conv
1da30 65 72 74 65 64 20 74 6f 20 74 68 65 69 72 20 75  erted to their u
1da40 70 70 65 72 2d 63 61 73 65 20 65 71 75 69 76 61  pper-case equiva
1da50 6c 65 6e 74 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  lent..}..funcdef
1da60 20 7b 7a 65 72 6f 62 6c 6f 62 28 4e 29 7d 20 7b   {zeroblob(N)} {
1da70 7d 20 7b 0a 20 20 5e 54 68 65 20 7a 65 72 6f 62  } {.  ^The zerob
1da80 6c 6f 62 28 4e 29 20 66 75 6e 63 74 69 6f 6e 20  lob(N) function 
1da90 72 65 74 75 72 6e 73 20 61 20 42 4c 4f 42 20 63  returns a BLOB c
1daa0 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 4e 20 62  onsisting of N b
1dab0 79 74 65 73 20 6f 66 20 30 78 30 30 2e 0a 20 20  ytes of 0x00..  
1dac0 53 51 4c 69 74 65 20 6d 61 6e 61 67 65 73 20 74  SQLite manages t
1dad0 68 65 73 65 20 7a 65 72 6f 62 6c 6f 62 73 20 76  hese zeroblobs v
1dae0 65 72 79 20 65 66 66 69 63 69 65 6e 74 6c 79 2e  ery efficiently.
1daf0 20 20 5a 65 72 6f 62 6c 6f 62 73 20 63 61 6e 20    Zeroblobs can 
1db00 62 65 20 75 73 65 64 20 74 6f 0a 20 20 72 65 73  be used to.  res
1db10 65 72 76 65 20 73 70 61 63 65 20 66 6f 72 20 61  erve space for a
1db20 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 6c 61   BLOB that is la
1db30 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
1db40 67 20 0a 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g .  [sqlite3_bl
1db50 6f 62 5f 6f 70 65 6e 28 29 20 7c 20 69 6e 63 72  ob_open() | incr
1db60 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1db70 5d 2e 0a 20 20 5e 54 68 69 73 20 53 51 4c 20 66  ]..  ^This SQL f
1db80 75 6e 63 74 69 6f 6e 20 69 73 20 69 6d 70 6c 65  unction is imple
1db90 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 74 68 65  mented using the
1dba0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1dbb0 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 0a 20 20 72  _zeroblob()].  r
1dbc0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 74 68 65 20  outine from the 
1dbd0 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65 2e  C/C++ interface.
1dbe0 0a 7d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68  .}.</tcl>..<p>Th
1dbf0 65 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73  e core functions
1dc00 20 73 68 6f 77 6e 20 62 65 6c 6f 77 20 61 72 65   shown below are
1dc10 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65   available by de
1dc20 66 61 75 6c 74 2e 20 0a 5b 64 61 74 65 66 75 6e  fault. .[datefun
1dc30 63 20 7c 20 44 61 74 65 20 26 61 6d 70 3b 20 54  c | Date &amp; T
1dc40 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 0a  ime functions],.
1dc50 5b 61 67 67 66 75 6e 63 20 7c 20 61 67 67 72 65  [aggfunc | aggre
1dc60 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 5d 2c  gate functions],
1dc70 20 61 6e 64 0a 5b 6a 73 6f 6e 31 20 7c 20 4a 53   and.[json1 | JS
1dc80 4f 4e 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  ON functions] ar
1dc90 65 20 64 6f 63 75 6d 65 6e 74 65 64 20 73 65 70  e documented sep
1dca0 61 72 61 74 65 6c 79 2e 20 20 41 6e 0a 61 70 70  arately.  An.app
1dcb0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 64 65 66  lication may def
1dcc0 69 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 0a 66  ine additional.f
1dcd0 75 6e 63 74 69 6f 6e 73 20 77 72 69 74 74 65 6e  unctions written
1dce0 20 69 6e 20 43 20 61 6e 64 20 61 64 64 65 64 20   in C and added 
1dcf0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1dd00 65 6e 67 69 6e 65 20 75 73 69 6e 67 0a 74 68 65  engine using.the
1dd10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1dd20 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 41 50 49  _function()] API
1dd30 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 73 65 74  .</p>..<tcl>.set
1dd40 20 6c 78 20 7b 7d 0a 66 6f 72 65 61 63 68 20 62   lx {}.foreach b
1dd50 61 73 65 73 79 6e 74 61 78 20 5b 61 72 72 61 79  asesyntax [array
1dd60 20 6e 61 6d 65 73 20 63 6f 72 65 66 75 6e 63 73   names corefuncs
1dd70 65 74 5d 20 7b 0a 20 20 66 6f 72 65 61 63 68 20  et] {.  foreach 
1dd80 7b 73 79 6e 74 61 78 20 6b 65 79 77 6f 72 64 73  {syntax keywords
1dd90 20 64 65 73 63 7d 20 24 63 6f 72 65 66 75 6e 63   desc} $corefunc
1dda0 73 65 74 28 24 62 61 73 65 73 79 6e 74 61 78 29  set($basesyntax)
1ddb0 20 62 72 65 61 6b 0a 20 20 72 65 67 65 78 70 20   break.  regexp 
1ddc0 7b 5e 5b 61 2d 7a 5f 5d 2b 7d 20 24 62 61 73 65  {^[a-z_]+} $base
1ddd0 73 79 6e 74 61 78 20 66 72 61 67 6d 65 6e 74 0a  syntax fragment.
1dde0 20 20 66 6f 72 65 61 63 68 20 63 6f 72 65 73 79    foreach coresy
1ddf0 6e 74 61 78 20 24 73 79 6e 74 61 78 20 7b 0a 20  ntax $syntax {. 
1de00 20 20 20 6c 61 70 70 65 6e 64 20 6c 78 20 5b 6c     lappend lx [l
1de10 69 73 74 20 24 66 72 61 67 6d 65 6e 74 20 24 63  ist $fragment $c
1de20 6f 72 65 73 79 6e 74 61 78 20 30 5d 0a 20 20 7d  oresyntax 0].  }
1de30 0a 7d 0a 68 64 5f 6c 69 73 74 5f 6f 66 5f 6c 69  .}.hd_list_of_li
1de40 6e 6b 73 20 7b 7d 20 32 32 35 20 5b 6c 73 6f 72  nks {} 225 [lsor
1de50 74 20 2d 69 6e 64 65 78 20 31 20 24 6c 78 5d 0a  t -index 1 $lx].
1de60 0a 68 64 5f 70 75 74 73 6e 6c 20 22 3c 68 72 20  .hd_putsnl "<hr 
1de70 63 6c 61 73 73 3d 27 78 68 72 27 3e 22 0a 68 64  class='xhr'>".hd
1de80 5f 70 75 74 73 6e 6c 20 22 3c 64 6c 3e 22 0a 66  _putsnl "<dl>".f
1de90 6f 72 65 61 63 68 20 62 61 73 65 73 79 6e 74 61  oreach basesynta
1dea0 78 20 5b 6c 73 6f 72 74 20 5b 61 72 72 61 79 20  x [lsort [array 
1deb0 6e 61 6d 65 73 20 63 6f 72 65 66 75 6e 63 73 65  names corefuncse
1dec0 74 5d 5d 20 7b 0a 20 20 66 6f 72 65 61 63 68 20  t]] {.  foreach 
1ded0 7b 73 79 6e 74 61 78 20 6b 65 79 77 6f 72 64 73  {syntax keywords
1dee0 20 64 65 73 63 7d 20 24 63 6f 72 65 66 75 6e 63   desc} $corefunc
1def0 73 65 74 28 24 62 61 73 65 73 79 6e 74 61 78 29  set($basesyntax)
1df00 20 62 72 65 61 6b 0a 20 20 72 65 67 73 75 62 20   break.  regsub 
1df10 2d 61 6c 6c 20 7b 5c 73 2b 7d 20 5b 73 74 72 69  -all {\s+} [stri
1df20 6e 67 20 74 72 69 6d 20 24 73 79 6e 74 61 78 5d  ng trim $syntax]
1df30 20 7b 3c 62 72 20 2f 3e 7d 20 73 79 6e 74 61 78   {<br />} syntax
1df40 0a 20 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b  .  regsub -all {
1df50 5c 28 28 5b 5e 2a 29 5d 2b 29 5c 29 7d 20 24 73  \(([^*)]+)\)} $s
1df60 79 6e 74 61 78 20 7b 28 3c 69 3e 5c 31 3c 2f 69  yntax {(<i>\1</i
1df70 3e 29 7d 20 73 79 6e 74 61 78 0a 20 20 72 65 67  >)} syntax.  reg
1df80 73 75 62 20 2d 61 6c 6c 20 7b 2c 7d 20 24 73 79  sub -all {,} $sy
1df90 6e 74 61 78 20 7b 3c 2f 69 3e 2c 3c 69 3e 7d 20  ntax {</i>,<i>} 
1dfa0 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75 62 20  syntax.  regsub 
1dfb0 2d 61 6c 6c 20 7b 3c 69 3e 5c 2e 5c 2e 5c 2e 3c  -all {<i>\.\.\.<
1dfc0 2f 69 3e 7d 20 24 73 79 6e 74 61 78 20 7b 2e 2e  /i>} $syntax {..
1dfd0 2e 7d 20 73 79 6e 74 61 78 0a 20 20 72 65 67 65  .} syntax.  rege
1dfe0 78 70 20 7b 5e 5b 61 2d 7a 5d 2b 7d 20 24 62 61  xp {^[a-z]+} $ba
1dff0 73 65 73 79 6e 74 61 78 20 66 72 61 67 6d 65 6e  sesyntax fragmen
1e000 74 0a 20 20 69 66 20 7b 5b 6c 6c 65 6e 67 74 68  t.  if {[llength
1e010 20 24 6b 65 79 77 6f 72 64 73 5d 3d 3d 30 7d 20   $keywords]==0} 
1e020 7b 0a 20 20 20 20 72 65 67 65 78 70 20 7b 5b 61  {.    regexp {[a
1e030 2d 7a 5f 5d 2b 7d 20 24 73 79 6e 74 61 78 20 6e  -z_]+} $syntax n
1e040 61 6d 65 0a 20 20 20 20 68 64 5f 66 72 61 67 6d  ame.    hd_fragm
1e050 65 6e 74 20 24 6e 61 6d 65 20 2a 24 6e 61 6d 65  ent $name *$name
1e060 20 22 24 7b 6e 61 6d 65 7d 28 29 20 53 51 4c 20   "${name}() SQL 
1e070 66 75 6e 63 74 69 6f 6e 22 0a 20 20 7d 20 65 6c  function".  } el
1e080 73 65 20 7b 0a 20 20 20 20 73 65 74 20 66 72 61  se {.    set fra
1e090 67 6e 61 6d 65 20 5b 6c 69 6e 64 65 78 20 24 6b  gname [lindex $k
1e0a0 65 79 77 6f 72 64 73 20 30 5d 0a 20 20 20 20 72  eywords 0].    r
1e0b0 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5b 5e 61 2d  egsub -all {[^a-
1e0c0 7a 5d 7d 20 24 66 72 61 67 6e 61 6d 65 20 7b 7d  z]} $fragname {}
1e0d0 20 66 72 61 67 6e 61 6d 65 0a 20 20 20 20 68 64   fragname.    hd
1e0e0 5f 66 72 61 67 6d 65 6e 74 20 24 66 72 61 67 6e  _fragment $fragn
1e0f0 61 6d 65 0a 20 20 20 20 65 76 61 6c 20 68 64 5f  ame.    eval hd_
1e100 6b 65 79 77 6f 72 64 73 20 5b 73 74 72 69 6e 67  keywords [string
1e110 20 6d 61 70 20 7b 5c 6e 20 7b 20 7d 7d 20 24 6b   map {\n { }} $k
1e120 65 79 77 6f 72 64 73 5d 0a 20 20 7d 0a 20 20 68  eywords].  }.  h
1e130 64 5f 70 75 74 73 20 22 3c 64 74 3e 3c 70 3e 3c  d_puts "<dt><p><
1e140 62 3e 24 73 79 6e 74 61 78 3c 2f 62 3e 3c 2f 64  b>$syntax</b></d
1e150 74 3e 22 0a 20 20 68 64 5f 72 65 73 6f 6c 76 65  t>".  hd_resolve
1e160 20 22 3c 64 64 3e 3c 70 3e 24 64 65 73 63 3c 2f   "<dd><p>$desc</
1e170 64 64 3e 5c 6e 22 0a 7d 0a 68 64 5f 70 75 74 73  dd>\n".}.hd_puts
1e180 6e 6c 20 22 3c 2f 64 6c 3e 22 0a 0a 23 23 23 23  nl "</dl>"..####
1e190 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1e1a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1e1b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1e1c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1e1d0 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
1e1e0 6f 6e 20 7b 44 61 74 65 20 41 6e 64 20 54 69 6d  on {Date And Tim
1e1f0 65 20 46 75 6e 63 74 69 6f 6e 73 7d 20 64 61 74  e Functions} dat
1e200 65 66 75 6e 63 20 7b 2a 64 61 74 65 66 75 6e 63  efunc {*datefunc
1e210 20 7b 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20   {date and time 
1e220 66 75 6e 63 74 69 6f 6e 73 7d 7d 0a 68 64 5f 6b  functions}}.hd_k
1e230 65 79 77 6f 72 64 73 20 7b 64 61 74 65 28 29 20  eywords {date() 
1e240 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b 74  SQL function} {t
1e250 69 6d 65 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ime() SQL functi
1e260 6f 6e 7d 0a 68 64 5f 6b 65 79 77 6f 72 64 73 20  on}.hd_keywords 
1e270 7b 64 61 74 65 74 69 6d 65 28 29 20 53 51 4c 20  {datetime() SQL 
1e280 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 75 6c 69 61  function} {julia
1e290 6e 64 61 79 28 29 20 53 51 4c 20 66 75 6e 63 74  nday() SQL funct
1e2a0 69 6f 6e 7d 0a 68 64 5f 6b 65 79 77 6f 72 64 73  ion}.hd_keywords
1e2b0 20 7b 73 74 72 66 74 69 6d 65 28 29 20 53 51 4c   {strftime() SQL
1e2c0 20 66 75 6e 63 74 69 6f 6e 7d 0a 3c 2f 74 63 6c   function}.</tcl
1e2d0 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 73 75  >..<p>.SQLite su
1e2e0 70 70 6f 72 74 73 20 66 69 76 65 20 64 61 74 65  pports five date
1e2f0 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63 74 69   and time functi
1e300 6f 6e 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ons as follows:.
1e310 3c 2f 70 3e 0a 0a 3c 70 3e 0a 3c 6f 6c 3e 0a 3c  </p>..<p>.<ol>.<
1e320 6c 69 3e 20 5e 28 3c 62 3e 64 61 74 65 28 3c 2f  li> ^(<b>date(</
1e330 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69 6e 67 2c  b><i>timestring,
1e340 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64 69 66   modifier, modif
1e350 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29  ier, ...</i><b>)
1e360 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 6c 69  </b>)^ </li>.<li
1e370 3e 20 5e 28 3c 62 3e 74 69 6d 65 28 3c 2f 62 3e  > ^(<b>time(</b>
1e380 3c 69 3e 74 69 6d 65 73 74 72 69 6e 67 2c 20 6d  <i>timestring, m
1e390 6f 64 69 66 69 65 72 2c 20 6d 6f 64 69 66 69 65  odifier, modifie
1e3a0 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29 3c 2f  r, ...</i><b>)</
1e3b0 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 6c 69 3e 20  b>)^ </li>.<li> 
1e3c0 5e 28 3c 62 3e 64 61 74 65 74 69 6d 65 28 3c 2f  ^(<b>datetime(</
1e3d0 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69 6e 67 2c  b><i>timestring,
1e3e0 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64 69 66   modifier, modif
1e3f0 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29  ier, ...</i><b>)
1e400 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 6c 69  </b>)^ </li>.<li
1e410 3e 20 5e 28 3c 62 3e 6a 75 6c 69 61 6e 64 61 79  > ^(<b>julianday
1e420 28 3c 2f 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69  (</b><i>timestri
1e430 6e 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f  ng, modifier, mo
1e440 64 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c  difier, ...</i><
1e450 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a  b>)</b>)^ </li>.
1e460 3c 6c 69 3e 20 5e 28 3c 62 3e 73 74 72 66 74 69  <li> ^(<b>strfti
1e470 6d 65 28 3c 2f 62 3e 3c 69 3e 66 6f 72 6d 61 74  me(</b><i>format
1e480 2c 20 74 69 6d 65 73 74 72 69 6e 67 2c 20 6d 6f  , timestring, mo
1e490 64 69 66 69 65 72 2c 20 6d 6f 64 69 66 69 65 72  difier, modifier
1e4a0 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29 3c 2f 62  , ...</i><b>)</b
1e4b0 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a  >)^ </li>.</ol>.
1e4c0 0a 3c 70 3e 0a 5e 41 6c 6c 20 66 69 76 65 20 64  .<p>.^All five d
1e4d0 61 74 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e  ate and time fun
1e4e0 63 74 69 6f 6e 73 20 74 61 6b 65 20 61 20 74 69  ctions take a ti
1e4f0 6d 65 20 73 74 72 69 6e 67 20 61 73 20 61 6e 20  me string as an 
1e500 61 72 67 75 6d 65 6e 74 2e 20 0a 5e 54 68 65 20  argument. .^The 
1e510 74 69 6d 65 20 73 74 72 69 6e 67 20 69 73 20 66  time string is f
1e520 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72 6f 20  ollowed by zero 
1e530 6f 72 20 6d 6f 72 65 20 6d 6f 64 69 66 69 65 72  or more modifier
1e540 73 2e 20 0a 5e 54 68 65 20 73 74 72 66 74 69 6d  s. .^The strftim
1e550 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 73  e() function als
1e560 6f 20 74 61 6b 65 73 20 61 20 66 6f 72 6d 61 74  o takes a format
1e570 20 73 74 72 69 6e 67 20 61 73 20 69 74 73 20 66   string as its f
1e580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 3c  irst argument..<
1e590 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 64 61 74  /p>..<p>.The dat
1e5a0 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63 74  e and time funct
1e5b0 69 6f 6e 73 20 75 73 65 20 61 20 73 75 62 73 65  ions use a subse
1e5c0 74 20 6f 66 0a 5b 68 74 74 70 3a 2f 2f 65 6e 2e  t of.[http://en.
1e5d0 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69  wikipedia.org/wi
1e5e0 6b 69 2f 49 53 4f 5f 38 36 30 31 20 7c 20 49 53  ki/ISO_8601 | IS
1e5f0 30 2d 38 36 30 31 5d 20 64 61 74 65 20 61 6e 64  0-8601] date and
1e600 20 74 69 6d 65 0a 66 6f 72 6d 61 74 73 2e 0a 5e   time.formats..^
1e610 54 68 65 20 64 61 74 65 28 29 20 66 75 6e 63 74  The date() funct
1e620 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1e630 64 61 74 65 20 69 6e 20 74 68 69 73 20 66 6f 72  date in this for
1e640 6d 61 74 3a 20 59 59 59 59 2d 4d 4d 2d 44 44 2e  mat: YYYY-MM-DD.
1e650 20 0a 5e 54 68 65 20 74 69 6d 65 28 29 20 66 75   .^The time() fu
1e660 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1e670 68 65 20 74 69 6d 65 20 61 73 20 48 48 3a 4d 4d  he time as HH:MM
1e680 3a 53 53 2e 20 0a 5e 54 68 65 20 64 61 74 65 74  :SS. .^The datet
1e690 69 6d 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ime() function r
1e6a0 65 74 75 72 6e 73 20 22 59 59 59 59 2d 4d 4d 2d  eturns "YYYY-MM-
1e6b0 44 44 20 48 48 3a 4d 4d 3a 53 53 22 2e 20 0a 5e  DD HH:MM:SS". .^
1e6c0 28 54 68 65 20 6a 75 6c 69 61 6e 64 61 79 28 29  (The julianday()
1e6d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1e6e0 73 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f 65  s the .[http://e
1e6f0 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f  n.wikipedia.org/
1e700 77 69 6b 69 2f 4a 75 6c 69 61 6e 5f 64 61 79 20  wiki/Julian_day 
1e710 7c 20 4a 75 6c 69 61 6e 20 64 61 79 5d 20 2d 20  | Julian day] - 
1e720 74 68 65 0a 6e 75 6d 62 65 72 20 6f 66 20 64 61  the.number of da
1e730 79 73 20 73 69 6e 63 65 20 6e 6f 6f 6e 20 69 6e  ys since noon in
1e740 20 47 72 65 65 6e 77 69 63 68 20 6f 6e 20 4e 6f   Greenwich on No
1e750 76 65 6d 62 65 72 20 32 34 2c 20 34 37 31 34 20  vember 24, 4714 
1e760 42 2e 43 2e 20 0a 28 5b 68 74 74 70 3a 2f 2f 65  B.C. .([http://e
1e770 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f  n.wikipedia.org/
1e780 77 69 6b 69 2f 50 72 6f 6c 65 70 74 69 63 5f 47  wiki/Proleptic_G
1e790 72 65 67 6f 72 69 61 6e 5f 63 61 6c 65 6e 64 61  regorian_calenda
1e7a0 72 20 7c 20 50 72 6f 6c 65 70 74 69 63 20 47 72  r | Proleptic Gr
1e7b0 65 67 6f 72 69 61 6e 20 63 61 6c 65 6e 64 61 72  egorian calendar
1e7c0 5d 29 2e 29 5e 0a 5e 54 68 65 20 73 74 72 66 74  ]).)^.^The strft
1e7d0 69 6d 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ime() routine re
1e7e0 74 75 72 6e 73 20 74 68 65 20 64 61 74 65 20 66  turns the date f
1e7f0 6f 72 6d 61 74 74 65 64 20 61 63 63 6f 72 64 69  ormatted accordi
1e800 6e 67 20 74 6f 20 0a 74 68 65 20 66 6f 72 6d 61  ng to .the forma
1e810 74 20 73 74 72 69 6e 67 20 73 70 65 63 69 66 69  t string specifi
1e820 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
1e830 61 72 67 75 6d 65 6e 74 2e 0a 5e 54 68 65 20 66  argument..^The f
1e840 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 73 75 70  ormat string sup
1e850 70 6f 72 74 73 20 74 68 65 20 6d 6f 73 74 20 63  ports the most c
1e860 6f 6d 6d 6f 6e 20 73 75 62 73 74 69 74 75 74 69  ommon substituti
1e870 6f 6e 73 20 66 6f 75 6e 64 20 69 6e 20 74 68 65  ons found in the
1e880 20 0a 5b 68 74 74 70 3a 2f 2f 6f 70 65 6e 67 72   .[http://opengr
1e890 6f 75 70 2e 6f 72 67 2f 6f 6e 6c 69 6e 65 70 75  oup.org/onlinepu
1e8a0 62 73 2f 30 30 37 39 30 38 37 39 39 2f 78 73 68  bs/007908799/xsh
1e8b0 2f 73 74 72 66 74 69 6d 65 2e 68 74 6d 6c 20 7c  /strftime.html |
1e8c0 20 73 74 72 66 74 69 6d 65 28 29 20 66 75 6e 63   strftime() func
1e8d0 74 69 6f 6e 5d 0a 66 72 6f 6d 20 74 68 65 20 73  tion].from the s
1e8e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1e8f0 79 20 70 6c 75 73 20 74 77 6f 20 6e 65 77 20 73  y plus two new s
1e900 75 62 73 74 69 74 75 74 69 6f 6e 73 2c 20 25 66  ubstitutions, %f
1e910 20 61 6e 64 20 25 4a 2e 0a 5e 28 54 68 65 20 66   and %J..^(The f
1e920 6f 6c 6c 6f 77 69 6e 67 20 69 73 20 61 20 63 6f  ollowing is a co
1e930 6d 70 6c 65 74 65 20 6c 69 73 74 20 6f 66 20 76  mplete list of v
1e940 61 6c 69 64 20 73 74 72 66 74 69 6d 65 28 29 20  alid strftime() 
1e950 73 75 62 73 74 69 74 75 74 69 6f 6e 73 3a 0a 3c  substitutions:.<
1e960 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
1e970 3e 0a 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  >.<table border=
1e980 22 30 22 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  "0" cellpadding=
1e990 22 30 22 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d  "0" cellspacing=
1e9a0 22 30 22 3e 0a 3c 74 72 3e 3c 74 64 3e 3c 74 64  "0">.<tr><td><td
1e9b0 20 77 69 64 74 68 3d 22 31 30 22 3e 3c 74 64 3e   width="10"><td>
1e9c0 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c 74 64 3e 20  </tr>..<tr><td> 
1e9d0 25 64 20 3c 74 64 3e 3c 74 64 3e 20 64 61 79 20  %d <td><td> day 
1e9e0 6f 66 20 6d 6f 6e 74 68 3a 20 30 30 0a 3c 74 72  of month: 00.<tr
1e9f0 3e 3c 74 64 3e 20 25 66 20 3c 74 64 3e 3c 74 64  ><td> %f <td><td
1ea00 3e 20 66 72 61 63 74 69 6f 6e 61 6c 20 73 65 63  > fractional sec
1ea10 6f 6e 64 73 3a 20 53 53 2e 53 53 53 0a 3c 74 72  onds: SS.SSS.<tr
1ea20 3e 3c 74 64 3e 20 25 48 20 3c 74 64 3e 3c 74 64  ><td> %H <td><td
1ea30 3e 20 68 6f 75 72 3a 20 30 30 2d 32 34 20 0a 3c  > hour: 00-24 .<
1ea40 74 72 3e 3c 74 64 3e 20 25 6a 20 3c 74 64 3e 3c  tr><td> %j <td><
1ea50 74 64 3e 20 64 61 79 20 6f 66 20 79 65 61 72 3a  td> day of year:
1ea60 20 30 30 31 2d 33 36 36 0a 3c 74 72 3e 3c 74 64   001-366.<tr><td
1ea70 3e 20 25 4a 20 3c 74 64 3e 3c 74 64 3e 20 4a 75  > %J <td><td> Ju
1ea80 6c 69 61 6e 20 64 61 79 20 6e 75 6d 62 65 72 0a  lian day number.
1ea90 3c 74 72 3e 3c 74 64 3e 20 25 6d 20 3c 74 64 3e  <tr><td> %m <td>
1eaa0 3c 74 64 3e 20 6d 6f 6e 74 68 3a 20 30 31 2d 31  <td> month: 01-1
1eab0 32 0a 3c 74 72 3e 3c 74 64 3e 20 25 4d 20 3c 74  2.<tr><td> %M <t
1eac0 64 3e 3c 74 64 3e 20 6d 69 6e 75 74 65 3a 20 30  d><td> minute: 0
1ead0 30 2d 35 39 0a 3c 74 72 3e 3c 74 64 3e 20 25 73  0-59.<tr><td> %s
1eae0 20 3c 74 64 3e 3c 74 64 3e 20 73 65 63 6f 6e 64   <td><td> second
1eaf0 73 20 73 69 6e 63 65 20 31 39 37 30 2d 30 31 2d  s since 1970-01-
1eb00 30 31 0a 3c 74 72 3e 3c 74 64 3e 20 25 53 20 3c  01.<tr><td> %S <
1eb10 74 64 3e 3c 74 64 3e 20 73 65 63 6f 6e 64 73 3a  td><td> seconds:
1eb20 20 30 30 2d 35 39 0a 3c 74 72 3e 3c 74 64 3e 20   00-59.<tr><td> 
1eb30 25 77 20 3c 74 64 3e 3c 74 64 3e 20 64 61 79 20  %w <td><td> day 
1eb40 6f 66 20 77 65 65 6b 20 30 2d 36 20 77 69 74 68  of week 0-6 with
1eb50 20 53 75 6e 64 61 79 3d 3d 30 0a 3c 74 72 3e 3c   Sunday==0.<tr><
1eb60 74 64 3e 20 25 57 20 3c 74 64 3e 3c 74 64 3e 20  td> %W <td><td> 
1eb70 77 65 65 6b 20 6f 66 20 79 65 61 72 3a 20 30 30  week of year: 00
1eb80 2d 35 33 0a 3c 74 72 3e 3c 74 64 3e 20 25 59 20  -53.<tr><td> %Y 
1eb90 3c 74 64 3e 3c 74 64 3e 20 79 65 61 72 3a 20 30  <td><td> year: 0
1eba0 30 30 30 2d 39 39 39 39 0a 3c 74 72 3e 3c 74 64  000-9999.<tr><td
1ebb0 3e 20 25 25 20 3c 74 64 3e 3c 74 64 3e 20 25 0a  > %% <td><td> %.
1ebc0 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b  </table>.</block
1ebd0 71 75 6f 74 65 3e 29 5e 0a 0a 3c 70 3e 0a 5e 28  quote>)^..<p>.^(
1ebe0 4e 6f 74 69 63 65 20 74 68 61 74 20 61 6c 6c 20  Notice that all 
1ebf0 6f 74 68 65 72 20 64 61 74 65 20 61 6e 64 20 74  other date and t
1ec00 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ime functions ca
1ec10 6e 20 62 65 20 65 78 70 72 65 73 73 65 64 0a 69  n be expressed.i
1ec20 6e 20 74 65 72 6d 73 20 6f 66 20 73 74 72 66 74  n terms of strft
1ec30 69 6d 65 28 29 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c  ime():.</p>..<bl
1ec40 6f 63 6b 71 75 6f 74 65 3e 0a 3c 74 61 62 6c 65  ockquote>.<table
1ec50 20 62 6f 72 64 65 72 3d 22 30 22 20 63 65 6c 6c   border="0" cell
1ec60 70 61 64 64 69 6e 67 3d 22 30 22 20 63 65 6c 6c  padding="0" cell
1ec70 73 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c 74 72  spacing="0">.<tr
1ec80 3e 3c 74 64 3e 3c 62 3e 46 75 6e 63 74 69 6f 6e  ><td><b>Function
1ec90 3c 2f 62 3e 3c 74 64 20 77 69 64 74 68 3d 22 33  </b><td width="3
1eca0 30 22 3e 3c 74 64 3e 3c 62 3e 45 71 75 69 76 61  0"><td><b>Equiva
1ecb0 6c 65 6e 74 20 73 74 72 66 74 69 6d 65 28 29 3c  lent strftime()<
1ecc0 2f 62 3e 0a 3c 74 72 3e 3c 74 64 3e 20 20 20 64  /b>.<tr><td>   d
1ecd0 61 74 65 28 2e 2e 2e 29 20 20 20 20 20 20 3c 74  ate(...)      <t
1ece0 64 3e 3c 74 64 3e 20 20 73 74 72 66 74 69 6d 65  d><td>  strftime
1ecf0 28 27 25 59 2d 25 6d 2d 25 64 27 2c 20 2e 2e 2e  ('%Y-%m-%d', ...
1ed00 29 0a 3c 74 72 3e 3c 74 64 3e 20 20 20 74 69 6d  ).<tr><td>   tim
1ed10 65 28 2e 2e 2e 29 20 20 20 20 20 20 3c 74 64 3e  e(...)      <td>
1ed20 3c 74 64 3e 20 20 73 74 72 66 74 69 6d 65 28 27  <td>  strftime('
1ed30 25 48 3a 25 4d 3a 25 53 27 2c 20 2e 2e 2e 29 0a  %H:%M:%S', ...).
1ed40 3c 74 72 3e 3c 74 64 3e 20 20 20 64 61 74 65 74  <tr><td>   datet
1ed50 69 6d 65 28 2e 2e 2e 29 20 20 3c 74 64 3e 3c 74  ime(...)  <td><t
1ed60 64 3e 20 20 73 74 72 66 74 69 6d 65 28 27 25 59  d>  strftime('%Y
1ed70 2d 25 6d 2d 25 64 20 25 48 3a 25 4d 3a 25 53 27  -%m-%d %H:%M:%S'
1ed80 2c 20 2e 2e 2e 29 0a 3c 74 72 3e 3c 74 64 3e 20  , ...).<tr><td> 
1ed90 20 20 6a 75 6c 69 61 6e 64 61 79 28 2e 2e 2e 29    julianday(...)
1eda0 20 3c 74 64 3e 3c 74 64 3e 20 20 73 74 72 66 74   <td><td>  strft
1edb0 69 6d 65 28 27 25 4a 27 2c 20 2e 2e 2e 29 0a 3c  ime('%J', ...).<
1edc0 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71  /table>.</blockq
1edd0 75 6f 74 65 3e 29 5e 0a 0a 3c 70 3e 0a 54 68 65  uote>)^..<p>.The
1ede0 20 6f 6e 6c 79 20 72 65 61 73 6f 6e 73 20 66 6f   only reasons fo
1edf0 72 20 70 72 6f 76 69 64 69 6e 67 20 66 75 6e 63  r providing func
1ee00 74 69 6f 6e 73 20 6f 74 68 65 72 20 74 68 61 6e  tions other than
1ee10 20 73 74 72 66 74 69 6d 65 28 29 20 69 73 0a 66   strftime() is.f
1ee20 6f 72 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 61  or convenience a
1ee30 6e 64 20 66 6f 72 20 65 66 66 69 63 69 65 6e 63  nd for efficienc
1ee40 79 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 54 69 6d  y..</p>..<h3>Tim
1ee50 65 20 53 74 72 69 6e 67 73 3c 2f 68 33 3e 0a 0a  e Strings</h3>..
1ee60 3c 70 3e 5e 28 41 20 74 69 6d 65 20 73 74 72 69  <p>^(A time stri
1ee70 6e 67 20 63 61 6e 20 62 65 20 69 6e 20 61 6e 79  ng can be in any
1ee80 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
1ee90 67 20 66 6f 72 6d 61 74 73 3a 3c 2f 70 3e 0a 0a  g formats:</p>..
1eea0 3c 6f 6c 3e 0a 3c 6c 69 3e 20 3c 69 3e 59 59 59  <ol>.<li> <i>YYY
1eeb0 59 2d 4d 4d 2d 44 44 3c 2f 69 3e 0a 3c 6c 69 3e  Y-MM-DD</i>.<li>
1eec0 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 20 48   <i>YYYY-MM-DD H
1eed0 48 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69  H:MM</i>.<li> <i
1eee0 3e 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48 3a 4d  >YYYY-MM-DD HH:M
1eef0 4d 3a 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69  M:SS</i>.<li> <i
1ef00 3e 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48 3a 4d  >YYYY-MM-DD HH:M
1ef10 4d 3a 53 53 2e 53 53 53 3c 2f 69 3e 0a 3c 6c 69  M:SS.SSS</i>.<li
1ef20 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 3c  > <i>YYYY-MM-DD<
1ef30 2f 69 3e 3c 62 3e 54 3c 2f 62 3e 3c 69 3e 48 48  /i><b>T</b><i>HH
1ef40 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e  :MM</i>.<li> <i>
1ef50 59 59 59 59 2d 4d 4d 2d 44 44 3c 2f 69 3e 3c 62  YYYY-MM-DD</i><b
1ef60 3e 54 3c 2f 62 3e 3c 69 3e 48 48 3a 4d 4d 3a 53  >T</b><i>HH:MM:S
1ef70 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e 59 59  S</i>.<li> <i>YY
1ef80 59 59 2d 4d 4d 2d 44 44 3c 2f 69 3e 3c 62 3e 54  YY-MM-DD</i><b>T
1ef90 3c 2f 62 3e 3c 69 3e 48 48 3a 4d 4d 3a 53 53 2e  </b><i>HH:MM:SS.
1efa0 53 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e  SSS</i>.<li> <i>
1efb0 48 48 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c  HH:MM</i>.<li> <
1efc0 69 3e 48 48 3a 4d 4d 3a 53 53 3c 2f 69 3e 0a 3c  i>HH:MM:SS</i>.<
1efd0 6c 69 3e 20 3c 69 3e 48 48 3a 4d 4d 3a 53 53 2e  li> <i>HH:MM:SS.
1efe0 53 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 62 3e  SSS</i>.<li> <b>
1eff0 6e 6f 77 3c 2f 62 3e 0a 3c 6c 69 3e 20 3c 69 3e  now</b>.<li> <i>
1f000 44 44 44 44 44 44 44 44 44 44 3c 2f 69 3e 0a 3c  DDDDDDDDDD</i>.<
1f010 2f 6f 6c 3e 29 5e 0a 0a 3c 70 3e 0a 5e 49 6e 20  /ol>)^..<p>.^In 
1f020 66 6f 72 6d 61 74 73 20 35 20 74 68 72 6f 75 67  formats 5 throug
1f030 68 20 37 2c 20 74 68 65 20 22 54 22 20 69 73 20  h 7, the "T" is 
1f040 61 20 6c 69 74 65 72 61 6c 20 63 68 61 72 61 63  a literal charac
1f050 74 65 72 20 73 65 70 61 72 61 74 69 6e 67 20 0a  ter separating .
1f060 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 68 65  the date and the
1f070 20 74 69 6d 65 2c 20 61 73 20 72 65 71 75 69 72   time, as requir
1f080 65 64 20 62 79 20 0a 5b 68 74 74 70 3a 2f 2f 77  ed by .[http://w
1f090 77 77 2e 77 33 63 2e 6f 72 67 2f 54 52 2f 4e 4f  ww.w3c.org/TR/NO
1f0a0 54 45 2d 64 61 74 65 74 69 6d 65 20 7c 20 49 53  TE-datetime | IS
1f0b0 4f 2d 38 36 30 31 5d 2e 20 0a 5e 46 6f 72 6d 61  O-8601]. .^Forma
1f0c0 74 73 20 38 20 74 68 72 6f 75 67 68 20 31 30 20  ts 8 through 10 
1f0d0 74 68 61 74 20 73 70 65 63 69 66 79 20 6f 6e 6c  that specify onl
1f0e0 79 20 61 20 74 69 6d 65 20 61 73 73 75 6d 65 20  y a time assume 
1f0f0 61 20 64 61 74 65 20 6f 66 20 0a 32 30 30 30 2d  a date of .2000-
1f100 30 31 2d 30 31 2e 20 46 6f 72 6d 61 74 20 31 31  01-01. Format 11
1f110 2c 20 74 68 65 20 73 74 72 69 6e 67 20 27 6e 6f  , the string 'no
1f120 77 27 2c 20 69 73 20 63 6f 6e 76 65 72 74 65 64  w', is converted
1f130 20 69 6e 74 6f 20 74 68 65 20 0a 63 75 72 72 65   into the .curre
1f140 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
1f150 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
1f160 6d 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  m the xCurrentTi
1f170 6d 65 20 6d 65 74 68 6f 64 0a 6f 66 20 74 68 65  me method.of the
1f180 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1f190 62 6a 65 63 74 20 69 6e 20 75 73 65 2e 0a 5e 54  bject in use..^T
1f1a0 68 65 20 27 6e 6f 77 27 20 61 72 67 75 6d 65 6e  he 'now' argumen
1f1b0 74 20 74 6f 20 64 61 74 65 20 61 6e 64 20 74 69  t to date and ti
1f1c0 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 6c 77  me functions alw
1f1d0 61 79 73 20 72 65 74 75 72 6e 73 20 65 78 61 63  ays returns exac
1f1e0 74 6c 79 20 74 68 65 0a 73 61 6d 65 20 76 61 6c  tly the.same val
1f1f0 75 65 20 66 6f 72 20 6d 75 6c 74 69 70 6c 65 20  ue for multiple 
1f200 69 6e 76 6f 63 61 74 69 6f 6e 73 20 77 69 74 68  invocations with
1f210 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  in the same [sql
1f220 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
1f230 6c 2e 0a 5e 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77  l..^[http://en.w
1f240 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b  ikipedia.org/wik
1f250 69 2f 43 6f 6f 72 64 69 6e 61 74 65 64 5f 55 6e  i/Coordinated_Un
1f260 69 76 65 72 73 61 6c 5f 54 69 6d 65 20 7c 20 55  iversal_Time | U
1f270 6e 69 76 65 72 73 61 6c 20 43 6f 6f 72 64 69 6e  niversal Coordin
1f280 61 74 65 64 20 54 69 6d 65 20 28 55 54 43 29 5d  ated Time (UTC)]
1f290 20 69 73 20 75 73 65 64 2e 20 0a 5e 46 6f 72 6d   is used. .^Form
1f2a0 61 74 20 31 32 20 69 73 20 74 68 65 20 0a 5b 68  at 12 is the .[h
1f2b0 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
1f2c0 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4a 75 6c 69  ia.org/wiki/Juli
1f2d0 61 6e 5f 64 61 79 20 7c 20 4a 75 6c 69 61 6e 20  an_day | Julian 
1f2e0 64 61 79 20 6e 75 6d 62 65 72 5d 0a 65 78 70 72  day number].expr
1f2f0 65 73 73 65 64 20 61 73 20 61 20 66 6c 6f 61 74  essed as a float
1f300 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
1f310 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 46 6f 72 6d 61  .</p>..<p>.Forma
1f320 74 73 20 32 20 74 68 72 6f 75 67 68 20 31 30 20  ts 2 through 10 
1f330 6d 61 79 20 62 65 20 6f 70 74 69 6f 6e 61 6c 6c  may be optionall
1f340 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  y followed by a 
1f350 74 69 6d 65 7a 6f 6e 65 20 69 6e 64 69 63 61 74  timezone indicat
1f360 6f 72 20 6f 66 20 74 68 65 20 66 6f 72 6d 0a 22  or of the form."
1f370 3c 69 3e 26 23 39 31 3b 2b 2d 26 23 39 33 3b 48  <i>&#91;+-&#93;H
1f380 48 3a 4d 4d 3c 2f 69 3e 22 20 6f 72 20 6a 75 73  H:MM</i>" or jus
1f390 74 20 22 3c 69 3e 5a 3c 2f 69 3e 22 2e 20 20 54  t "<i>Z</i>".  T
1f3a0 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
1f3b0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 55   functions use U
1f3c0 54 43 20 6f 72 20 22 7a 75 6c 75 22 0a 74 69 6d  TC or "zulu".tim
1f3d0 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 61 6e  e internally, an
1f3e0 64 20 73 6f 20 74 68 65 20 22 5a 22 20 73 75 66  d so the "Z" suf
1f3f0 66 69 78 20 69 73 20 61 20 6e 6f 2d 6f 70 2e 20  fix is a no-op. 
1f400 20 41 6e 79 20 6e 6f 6e 2d 7a 65 72 6f 20 22 48   Any non-zero "H
1f410 48 3a 4d 4d 22 20 73 75 66 66 69 78 20 69 73 0a  H:MM" suffix is.
1f420 73 75 62 74 72 61 63 74 65 64 20 66 72 6f 6d 20  subtracted from 
1f430 74 68 65 20 69 6e 64 69 63 61 74 65 64 20 64 61  the indicated da
1f440 74 65 20 61 6e 64 20 74 69 6d 65 20 69 6e 20 6f  te and time in o
1f450 72 64 65 72 20 74 6f 20 63 6f 6d 70 75 74 65 20  rder to compute 
1f460 7a 75 6c 75 20 74 69 6d 65 2e 0a 46 6f 72 20 65  zulu time..For e
1f470 78 61 6d 70 6c 65 2c 20 61 6c 6c 20 6f 66 20 74  xample, all of t
1f480 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 69 6d  he following tim
1f490 65 20 73 74 72 69 6e 67 73 20 61 72 65 20 65 71  e strings are eq
1f4a0 75 69 76 61 6c 65 6e 74 3a 0a 3c 2f 70 3e 0a 0a  uivalent:.</p>..
1f4b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 32 30 31  <blockquote>.201
1f4c0 33 2d 31 30 2d 30 37 20 30 38 3a 32 33 3a 31 39  3-10-07 08:23:19
1f4d0 2e 31 32 30 3c 62 72 3e 0a 32 30 31 33 2d 31 30  .120<br>.2013-10
1f4e0 2d 30 37 54 30 38 3a 32 33 3a 31 39 2e 31 32 30  -07T08:23:19.120
1f4f0 5a 3c 62 72 3e 0a 32 30 31 33 2d 31 30 2d 30 37  Z<br>.2013-10-07
1f500 20 30 34 3a 32 33 3a 31 39 2e 31 32 30 2d 30 34   04:23:19.120-04
1f510 3a 30 30 3c 62 72 3e 0a 32 34 35 36 35 37 32 2e  :00<br>.2456572.
1f520 38 34 39 35 32 36 38 35 0a 3c 2f 62 6c 6f 63 6b  84952685.</block
1f530 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 5e 28 49 6e  quote>..<p>.^(In
1f540 20 66 6f 72 6d 61 74 73 20 34 2c 20 37 2c 20 61   formats 4, 7, a
1f550 6e 64 20 31 30 2c 20 74 68 65 20 66 72 61 63 74  nd 10, the fract
1f560 69 6f 6e 61 6c 20 73 65 63 6f 6e 64 73 20 76 61  ional seconds va
1f570 6c 75 65 20 53 53 2e 53 53 53 20 63 61 6e 20 68  lue SS.SSS can h
1f580 61 76 65 0a 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ave.one or more 
1f590 64 69 67 69 74 73 20 66 6f 6c 6c 6f 77 69 6e 67  digits following
1f5a0 20 74 68 65 20 64 65 63 69 6d 61 6c 20 70 6f 69   the decimal poi
1f5b0 6e 74 2e 20 20 45 78 61 63 74 6c 79 20 74 68 72  nt.  Exactly thr
1f5c0 65 65 20 64 69 67 69 74 73 20 61 72 65 0a 73 68  ee digits are.sh
1f5d0 6f 77 6e 20 69 6e 20 74 68 65 20 65 78 61 6d 70  own in the examp
1f5e0 6c 65 73 20 62 65 63 61 75 73 65 20 6f 6e 6c 79  les because only
1f5f0 20 74 68 65 20 66 69 72 73 74 20 74 68 72 65 65   the first three
1f600 20 64 69 67 69 74 73 20 61 72 65 20 73 69 67 6e   digits are sign
1f610 69 66 69 63 61 6e 74 0a 74 6f 20 74 68 65 20 72  ificant.to the r
1f620 65 73 75 6c 74 2c 20 62 75 74 20 74 68 65 20 69  esult, but the i
1f630 6e 70 75 74 20 73 74 72 69 6e 67 20 63 61 6e 20  nput string can 
1f640 68 61 76 65 20 66 65 77 65 72 20 6f 72 20 6d 6f  have fewer or mo
1f650 72 65 20 74 68 61 6e 20 74 68 72 65 65 20 64 69  re than three di
1f660 67 69 74 73 0a 61 6e 64 20 74 68 65 20 64 61 74  gits.and the dat
1f670 65 2f 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73  e/time functions
1f680 20 77 69 6c 6c 20 73 74 69 6c 6c 20 6f 70 65 72   will still oper
1f690 61 74 65 20 63 6f 72 72 65 63 74 6c 79 2e 29 5e  ate correctly.)^
1f6a0 0a 53 69 6d 69 6c 61 72 6c 79 2c 20 66 6f 72 6d  .Similarly, form
1f6b0 61 74 20 31 32 20 69 73 20 73 68 6f 77 6e 20 77  at 12 is shown w
1f6c0 69 74 68 20 31 30 20 73 69 67 6e 69 66 69 63 61  ith 10 significa
1f6d0 6e 74 20 64 69 67 69 74 73 2c 20 62 75 74 20 74  nt digits, but t
1f6e0 68 65 20 64 61 74 65 2f 74 69 6d 65 0a 66 75 6e  he date/time.fun
1f6f0 63 74 69 6f 6e 73 20 77 69 6c 6c 20 72 65 61 6c  ctions will real
1f700 6c 79 20 61 63 63 65 70 74 20 61 73 20 6d 61 6e  ly accept as man
1f710 79 20 6f 72 20 61 73 20 66 65 77 20 64 69 67 69  y or as few digi
1f720 74 73 20 61 73 20 61 72 65 20 6e 65 63 65 73 73  ts as are necess
1f730 61 72 79 20 74 6f 0a 72 65 70 72 65 73 65 6e 74  ary to.represent
1f740 20 74 68 65 20 4a 75 6c 69 61 6e 20 64 61 79 20   the Julian day 
1f750 6e 75 6d 62 65 72 2e 0a 3c 2f 70 3e 0a 0a 3c 68  number..</p>..<h
1f760 33 3e 4d 6f 64 69 66 69 65 72 73 3c 2f 68 33 3e  3>Modifiers</h3>
1f770 0a 0a 3c 70 3e 5e 54 68 65 20 74 69 6d 65 20 73  ..<p>^The time s
1f780 74 72 69 6e 67 20 63 61 6e 20 62 65 20 66 6f 6c  tring can be fol
1f790 6c 6f 77 65 64 20 62 79 20 7a 65 72 6f 20 6f 72  lowed by zero or
1f7a0 20 6d 6f 72 65 20 6d 6f 64 69 66 69 65 72 73 20   more modifiers 
1f7b0 74 68 61 74 20 0a 61 6c 74 65 72 20 64 61 74 65  that .alter date
1f7c0 20 61 6e 64 2f 6f 72 20 74 69 6d 65 2e 20 5e 45   and/or time. ^E
1f7d0 61 63 68 20 6d 6f 64 69 66 69 65 72 0a 69 73 20  ach modifier.is 
1f7e0 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
1f7f0 20 74 68 61 74 20 69 73 20 61 70 70 6c 69 65 64   that is applied
1f800 20 74 6f 20 74 68 65 20 74 69 6d 65 20 76 61 6c   to the time val
1f810 75 65 20 74 6f 20 69 74 73 20 6c 65 66 74 2e 0a  ue to its left..
1f820 5e 4d 6f 64 69 66 69 65 72 73 20 61 72 65 20 61  ^Modifiers are a
1f830 70 70 6c 69 65 64 20 66 72 6f 6d 20 6c 65 66 74  pplied from left
1f840 20 74 6f 20 72 69 67 68 74 3b 20 6f 72 64 65 72   to right; order
1f850 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 5e   is important..^
1f860 28 54 68 65 20 61 76 61 69 6c 61 62 6c 65 20 6d  (The available m
1f870 6f 64 69 66 69 65 72 73 20 61 72 65 20 61 73 20  odifiers are as 
1f880 66 6f 6c 6c 6f 77 73 2e 3c 2f 70 3e 0a 0a 3c 6f  follows.</p>..<o
1f890 6c 3e 0a 3c 6c 69 3e 20 4e 4e 4e 20 64 61 79 73  l>.<li> NNN days
1f8a0 0a 3c 6c 69 3e 20 4e 4e 4e 20 68 6f 75 72 73 0a  .<li> NNN hours.
1f8b0 3c 6c 69 3e 20 4e 4e 4e 20 6d 69 6e 75 74 65 73  <li> NNN minutes
1f8c0 0a 3c 6c 69 3e 20 4e 4e 4e 2e 4e 4e 4e 4e 20 73  .<li> NNN.NNNN s
1f8d0 65 63 6f 6e 64 73 0a 3c 6c 69 3e 20 4e 4e 4e 20  econds.<li> NNN 
1f8e0 6d 6f 6e 74 68 73 0a 3c 6c 69 3e 20 4e 4e 4e 20  months.<li> NNN 
1f8f0 79 65 61 72 73 0a 3c 6c 69 3e 20 73 74 61 72 74  years.<li> start
1f900 20 6f 66 20 6d 6f 6e 74 68 0a 3c 6c 69 3e 20 73   of month.<li> s
1f910 74 61 72 74 20 6f 66 20 79 65 61 72 0a 3c 6c 69  tart of year.<li
1f920 3e 20 73 74 61 72 74 20 6f 66 20 64 61 79 0a 3c  > start of day.<
1f930 6c 69 3e 20 77 65 65 6b 64 61 79 20 4e 0a 3c 6c  li> weekday N.<l
1f940 69 3e 20 75 6e 69 78 65 70 6f 63 68 0a 3c 6c 69  i> unixepoch.<li
1f950 3e 20 6c 6f 63 61 6c 74 69 6d 65 0a 3c 6c 69 3e  > localtime.<li>
1f960 20 75 74 63 20 0a 3c 2f 6f 6c 3e 29 5e 0a 0a 3c   utc .</ol>)^..<
1f970 70 3e 5e 54 68 65 20 66 69 72 73 74 20 73 69 78  p>^The first six
1f980 20 6d 6f 64 69 66 69 65 72 73 20 28 31 20 74 68   modifiers (1 th
1f990 72 6f 75 67 68 20 36 29 20 0a 73 69 6d 70 6c 79  rough 6) .simply
1f9a0 20 61 64 64 20 74 68 65 20 73 70 65 63 69 66 69   add the specifi
1f9b0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1f9c0 65 20 74 6f 20 74 68 65 20 64 61 74 65 20 61 6e  e to the date an
1f9d0 64 20 74 69 6d 65 20 0a 73 70 65 63 69 66 69 65  d time .specifie
1f9e0 64 20 62 79 20 74 68 65 20 70 72 65 63 65 64 69  d by the precedi
1f9f0 6e 67 20 74 69 6d 65 73 74 72 69 6e 67 20 61 6e  ng timestring an
1fa00 64 20 6d 6f 64 69 66 69 65 72 73 2e 0a 5e 54 68  d modifiers..^Th
1fa10 65 20 27 73 27 20 63 68 61 72 61 63 74 65 72 20  e 's' character 
1fa20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  at the end of th
1fa30 65 20 6d 6f 64 69 66 69 65 72 20 6e 61 6d 65 73  e modifier names
1fa40 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 0a 5e 4e   is optional..^N
1fa50 6f 74 65 20 74 68 61 74 20 22 26 70 6c 75 73 6d  ote that "&plusm
1fa60 6e 3b 4e 4e 4e 20 6d 6f 6e 74 68 73 22 20 77 6f  n;NNN months" wo
1fa70 72 6b 73 20 62 79 20 72 65 6e 64 65 72 69 6e 67  rks by rendering
1fa80 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 64 61   the original da
1fa90 74 65 20 69 6e 74 6f 0a 74 68 65 20 59 59 59 59  te into.the YYYY
1faa0 2d 4d 4d 2d 44 44 20 66 6f 72 6d 61 74 2c 20 61  -MM-DD format, a
1fab0 64 64 69 6e 67 20 74 68 65 20 26 70 6c 75 73 6d  dding the &plusm
1fac0 6e 3b 4e 4e 4e 20 74 6f 20 74 68 65 20 4d 4d 20  n;NNN to the MM 
1fad0 6d 6f 6e 74 68 20 76 61 6c 75 65 2c 20 74 68 65  month value, the
1fae0 6e 0a 6e 6f 72 6d 61 6c 69 7a 69 6e 67 20 74 68  n.normalizing th
1faf0 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 75 73  e result.  ^Thus
1fb00 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
1fb10 68 65 20 64 61 74 61 20 32 30 30 31 2d 30 33 2d  he data 2001-03-
1fb20 33 31 20 6d 6f 64 69 66 69 65 64 0a 62 79 20 27  31 modified.by '
1fb30 2b 31 20 6d 6f 6e 74 68 27 20 69 6e 69 74 69 61  +1 month' initia
1fb40 6c 6c 79 20 79 69 65 6c 64 73 20 32 30 30 31 2d  lly yields 2001-
1fb50 30 34 2d 33 31 2c 20 62 75 74 20 41 70 72 69 6c  04-31, but April
1fb60 20 6f 6e 6c 79 20 68 61 73 20 33 30 20 64 61 79   only has 30 day
1fb70 73 0a 73 6f 20 74 68 65 20 64 61 74 65 20 69 73  s.so the date is
1fb80 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 74 6f 20 32   normalized to 2
1fb90 30 30 31 2d 30 35 2d 30 31 2e 20 20 5e 41 20 73  001-05-01.  ^A s
1fba0 69 6d 69 6c 61 72 20 65 66 66 65 63 74 20 6f 63  imilar effect oc
1fbb0 63 75 72 73 20 77 68 65 6e 0a 74 68 65 20 6f 72  curs when.the or
1fbc0 69 67 69 6e 61 6c 20 64 61 74 65 20 69 73 20 46  iginal date is F
1fbd0 65 62 72 75 61 72 79 20 32 39 20 6f 66 20 61 20  ebruary 29 of a 
1fbe0 6c 65 61 70 79 65 61 72 20 61 6e 64 20 74 68 65  leapyear and the
1fbf0 20 6d 6f 64 69 66 69 65 72 20 69 73 0a 26 70 6c   modifier is.&pl
1fc00 75 73 6d 6e 3b 4e 20 79 65 61 72 73 20 77 68 65  usmn;N years whe
1fc10 72 65 20 4e 20 69 73 20 6e 6f 74 20 61 20 6d 75  re N is not a mu
1fc20 6c 74 69 70 6c 65 20 6f 66 20 66 6f 75 72 2e 3c  ltiple of four.<
1fc30 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 22 73 74  /p>..<p>^The "st
1fc40 61 72 74 20 6f 66 22 20 6d 6f 64 69 66 69 65 72  art of" modifier
1fc50 73 20 28 37 20 74 68 72 6f 75 67 68 20 39 29 20  s (7 through 9) 
1fc60 73 68 69 66 74 20 74 68 65 20 64 61 74 65 20 62  shift the date b
1fc70 61 63 6b 77 61 72 64 73 20 0a 74 6f 20 74 68 65  ackwards .to the
1fc80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68   beginning of th
1fc90 65 20 63 75 72 72 65 6e 74 20 6d 6f 6e 74 68 2c  e current month,
1fca0 20 79 65 61 72 20 6f 72 20 64 61 79 2e 3c 2f 70   year or day.</p
1fcb0 3e 0a 0a 3c 70 3e 5e 54 68 65 20 22 77 65 65 6b  >..<p>^The "week
1fcc0 64 61 79 22 20 6d 6f 64 69 66 69 65 72 20 61 64  day" modifier ad
1fcd0 76 61 6e 63 65 73 20 74 68 65 20 64 61 74 65 20  vances the date 
1fce0 66 6f 72 77 61 72 64 20 74 6f 20 74 68 65 20 6e  forward to the n
1fcf0 65 78 74 20 64 61 74 65 20 0a 77 68 65 72 65 20  ext date .where 
1fd00 74 68 65 20 77 65 65 6b 64 61 79 20 6e 75 6d 62  the weekday numb
1fd10 65 72 20 69 73 20 4e 2e 20 53 75 6e 64 61 79 20  er is N. Sunday 
1fd20 69 73 20 30 2c 20 4d 6f 6e 64 61 79 20 69 73 20  is 0, Monday is 
1fd30 31 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 2e  1, and so forth.
1fd40 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 22 75  </p>..<p>^The "u
1fd50 6e 69 78 65 70 6f 63 68 22 20 6d 6f 64 69 66 69  nixepoch" modifi
1fd60 65 72 20 28 31 31 29 20 6f 6e 6c 79 20 77 6f 72  er (11) only wor
1fd70 6b 73 20 69 66 20 69 74 20 69 6d 6d 65 64 69 61  ks if it immedia
1fd80 74 65 6c 79 20 66 6f 6c 6c 6f 77 73 20 0a 61 20  tely follows .a 
1fd90 74 69 6d 65 73 74 72 69 6e 67 20 69 6e 20 74 68  timestring in th
1fda0 65 20 44 44 44 44 44 44 44 44 44 44 20 66 6f 72  e DDDDDDDDDD for
1fdb0 6d 61 74 2e 20 0a 5e 54 68 69 73 20 6d 6f 64 69  mat. .^This modi
1fdc0 66 69 65 72 20 63 61 75 73 65 73 20 74 68 65 20  fier causes the 
1fdd0 44 44 44 44 44 44 44 44 44 44 20 74 6f 20 62 65  DDDDDDDDDD to be
1fde0 20 69 6e 74 65 72 70 72 65 74 65 64 20 6e 6f 74   interpreted not
1fdf0 20 0a 61 73 20 61 20 4a 75 6c 69 61 6e 20 64 61   .as a Julian da
1fe00 79 20 6e 75 6d 62 65 72 20 61 73 20 69 74 20 6e  y number as it n
1fe10 6f 72 6d 61 6c 6c 79 20 77 6f 75 6c 64 20 62 65  ormally would be
1fe20 2c 20 62 75 74 20 61 73 0a 5b 68 74 74 70 3a 2f  , but as.[http:/
1fe30 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72  /en.wikipedia.or
1fe40 67 2f 77 69 6b 69 2f 55 6e 69 78 5f 74 69 6d 65  g/wiki/Unix_time
1fe50 20 7c 20 55 6e 69 78 20 54 69 6d 65 5d 20 2d 20   | Unix Time] - 
1fe60 74 68 65 20 0a 6e 75 6d 62 65 72 20 6f 66 20 73  the .number of s
1fe70 65 63 6f 6e 64 73 20 73 69 6e 63 65 20 31 39 37  econds since 197
1fe80 30 2e 20 20 49 66 20 74 68 65 20 22 75 6e 69 78  0.  If the "unix
1fe90 65 70 6f 63 68 22 20 6d 6f 64 69 66 69 65 72 20  epoch" modifier 
1fea0 64 6f 65 73 20 6e 6f 74 0a 66 6f 6c 6c 6f 77 20  does not.follow 
1feb0 61 20 74 69 6d 65 73 74 72 69 6e 67 20 6f 66 20  a timestring of 
1fec0 74 68 65 20 66 6f 72 6d 20 44 44 44 44 44 44 44  the form DDDDDDD
1fed0 44 44 44 20 77 68 69 63 68 20 65 78 70 72 65 73  DDD which expres
1fee0 73 65 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 6f  ses the number.o
1fef0 66 20 73 65 63 6f 6e 64 73 20 73 69 6e 63 65 20  f seconds since 
1ff00 31 39 37 30 20 6f 72 20 69 66 20 6f 74 68 65 72  1970 or if other
1ff10 20 6d 6f 64 69 66 69 65 72 73 0a 73 65 70 61 72   modifiers.separ
1ff20 61 74 65 20 74 68 65 20 22 75 6e 69 78 65 70 6f  ate the "unixepo
1ff30 63 68 22 20 6d 6f 64 69 66 69 65 72 20 66 72 6f  ch" modifier fro
1ff40 6d 20 70 72 69 6f 72 20 44 44 44 44 44 44 44 44  m prior DDDDDDDD
1ff50 44 44 20 74 68 65 6e 20 74 68 65 0a 62 65 68 61  DD then the.beha
1ff60 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1ff70 64 2e 0a 46 6f 72 20 53 51 4c 69 74 65 20 76 65  d..For SQLite ve
1ff80 72 73 69 6f 6e 73 20 62 65 66 6f 72 65 20 33 2e  rsions before 3.
1ff90 31 36 2e 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e  16.0 ([dateof:3.
1ffa0 31 36 2e 30 5d 29 2c 20 0a 74 68 65 20 22 75 6e  16.0]), .the "un
1ffb0 69 78 65 70 6f 63 68 22 20 6d 6f 64 69 66 69 65  ixepoch" modifie
1ffc0 72 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 66 6f 72  r only works for
1ffd0 0a 64 61 74 65 73 20 62 65 74 77 65 65 6e 20 30  .dates between 0
1ffe0 30 30 30 2d 30 31 2d 30 31 20 30 30 3a 30 30 3a  000-01-01 00:00:
1fff0 30 30 20 61 6e 64 20 35 33 35 32 2d 31 31 2d 30  00 and 5352-11-0
20000 31 20 31 30 3a 35 32 3a 34 37 20 28 75 6e 69 78  1 10:52:47 (unix
20010 20 74 69 6d 65 73 0a 6f 66 20 2d 36 32 31 36 37   times.of -62167
20020 32 31 39 32 30 30 20 74 68 72 6f 75 67 68 20 31  219200 through 1
20030 30 36 37 35 31 39 39 31 31 36 37 29 2e 3c 2f 70  06751991167).</p
20040 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
20050 65 6e 74 20 6c 6f 63 61 6c 74 69 6d 65 20 7b 6c  ent localtime {l
20060 6f 63 61 6c 74 69 6d 65 20 6d 6f 64 69 66 69 65  ocaltime modifie
20070 72 7d 20 7b 27 75 74 63 27 20 6d 6f 64 69 66 69  r} {'utc' modifi
20080 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 54 68  er}</tcl>.<p>^Th
20090 65 20 22 6c 6f 63 61 6c 74 69 6d 65 22 20 6d 6f  e "localtime" mo
200a0 64 69 66 69 65 72 20 28 31 32 29 20 61 73 73 75  difier (12) assu
200b0 6d 65 73 20 74 68 65 20 74 69 6d 65 20 73 74 72  mes the time str
200c0 69 6e 67 20 74 6f 20 69 74 73 20 6c 65 66 74 20  ing to its left 
200d0 69 73 20 69 6e 0a 55 6e 69 76 65 72 73 61 6c 20  is in.Universal 
200e0 43 6f 6f 72 64 69 6e 61 74 65 64 20 54 69 6d 65  Coordinated Time
200f0 20 28 55 54 43 29 20 61 6e 64 20 61 64 6a 75 73   (UTC) and adjus
20100 74 73 20 74 68 65 20 74 69 6d 65 0a 73 74 72 69  ts the time.stri
20110 6e 67 20 73 6f 20 74 68 61 74 20 69 74 20 64 69  ng so that it di
20120 73 70 6c 61 79 73 20 6c 6f 63 61 6c 74 69 6d 65  splays localtime
20130 2e 20 20 49 66 20 22 6c 6f 63 61 6c 74 69 6d 65  .  If "localtime
20140 22 0a 66 6f 6c 6c 6f 77 73 20 61 20 74 69 6d 65  ".follows a time
20150 20 74 68 61 74 20 69 73 20 6e 6f 74 20 55 54 43   that is not UTC
20160 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
20170 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
20180 2e 0a 5e 28 54 68 65 20 22 75 74 63 22 20 6d 6f  ..^(The "utc" mo
20190 64 69 66 69 65 72 20 69 73 20 74 68 65 20 6f 70  difier is the op
201a0 70 6f 73 69 74 65 20 6f 66 20 22 6c 6f 63 61 6c  posite of "local
201b0 74 69 6d 65 22 2e 20 20 0a 22 75 74 63 22 20 61  time".  ."utc" a
201c0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
201d0 73 74 72 69 6e 67 0a 74 6f 20 69 74 73 20 6c 65  string.to its le
201e0 66 74 20 69 73 20 69 6e 20 74 68 65 20 6c 6f 63  ft is in the loc
201f0 61 6c 20 74 69 6d 65 7a 6f 6e 65 20 61 6e 64 20  al timezone and 
20200 61 64 6a 75 73 74 73 20 74 68 61 74 20 73 74 72  adjusts that str
20210 69 6e 67 20 74 6f 20 62 65 20 69 6e 20 55 54 43  ing to be in UTC
20220 2e 29 5e 0a 49 66 20 74 68 65 20 70 72 69 6f 72  .)^.If the prior
20230 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 74 20 69   string is not i
20240 6e 20 6c 6f 63 61 6c 74 69 6d 65 2c 20 74 68 65  n localtime, the
20250 6e 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  n the result of 
20260 22 75 74 63 22 20 69 73 0a 75 6e 64 65 66 69 6e  "utc" is.undefin
20270 65 64 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 45 78 61  ed.</p>..<h3>Exa
20280 6d 70 6c 65 73 3c 2f 68 33 3e 0a 0a 5e 28 3c 70  mples</h3>..^(<p
20290 3e 43 6f 6d 70 75 74 65 20 74 68 65 20 63 75 72  >Compute the cur
202a0 72 65 6e 74 20 64 61 74 65 2e 3c 70 3e 0a 0a 3c  rent date.<p>..<
202b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 53 45 4c 45 43  blockquote>SELEC
202c0 54 20 64 61 74 65 28 27 6e 6f 77 27 29 3b 3c 2f  T date('now');</
202d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e  blockquote>)^..^
202e0 28 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68 65 20  (<p>Compute the 
202f0 6c 61 73 74 20 64 61 79 20 6f 66 20 74 68 65 20  last day of the 
20300 63 75 72 72 65 6e 74 20 6d 6f 6e 74 68 2e 3c 2f  current month.</
20310 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
20320 53 45 4c 45 43 54 20 64 61 74 65 28 27 6e 6f 77  SELECT date('now
20330 27 2c 27 73 74 61 72 74 20 6f 66 20 6d 6f 6e 74  ','start of mont
20340 68 27 2c 27 2b 31 20 6d 6f 6e 74 68 27 2c 27 2d  h','+1 month','-
20350 31 20 64 61 79 27 29 3b 0a 3c 2f 62 6c 6f 63 6b  1 day');.</block
20360 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43  quote>)^..^(<p>C
20370 6f 6d 70 75 74 65 20 74 68 65 20 64 61 74 65 20  ompute the date 
20380 61 6e 64 20 74 69 6d 65 20 67 69 76 65 6e 20 61  and time given a
20390 20 75 6e 69 78 20 74 69 6d 65 73 74 61 6d 70 20   unix timestamp 
203a0 31 30 39 32 39 34 31 34 36 36 2e 3c 2f 70 3e 0a  1092941466.</p>.
203b0 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20 20  .<blockquote>.  
203c0 20 20 53 45 4c 45 43 54 20 64 61 74 65 74 69 6d    SELECT datetim
203d0 65 28 31 30 39 32 39 34 31 34 36 36 2c 20 27 75  e(1092941466, 'u
203e0 6e 69 78 65 70 6f 63 68 27 29 3b 0a 3c 2f 62 6c  nixepoch');.</bl
203f0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c  ockquote>)^..^(<
20400 70 3e 43 6f 6d 70 75 74 65 20 74 68 65 20 64 61  p>Compute the da
20410 74 65 20 61 6e 64 20 74 69 6d 65 20 67 69 76 65  te and time give
20420 6e 20 61 20 75 6e 69 78 20 74 69 6d 65 73 74 61  n a unix timesta
20430 6d 70 20 31 30 39 32 39 34 31 34 36 36 2c 20 61  mp 1092941466, a
20440 6e 64 20 0a 63 6f 6d 70 65 6e 73 61 74 65 20 66  nd .compensate f
20450 6f 72 20 79 6f 75 72 20 6c 6f 63 61 6c 20 74 69  or your local ti
20460 6d 65 7a 6f 6e 65 2e 3c 2f 70 3e 0a 0a 3c 62 6c  mezone.</p>..<bl
20470 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c 45  ockquote>.  SELE
20480 43 54 20 64 61 74 65 74 69 6d 65 28 31 30 39 32  CT datetime(1092
20490 39 34 31 34 36 36 2c 20 27 75 6e 69 78 65 70 6f  941466, 'unixepo
204a0 63 68 27 2c 20 27 6c 6f 63 61 6c 74 69 6d 65 27  ch', 'localtime'
204b0 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  );.</blockquote>
204c0 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75 74 65  )^..^(<p>Compute
204d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 75 6e 69   the current uni
204e0 78 20 74 69 6d 65 73 74 61 6d 70 2e 3c 2f 70 3e  x timestamp.</p>
204f0 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20  ..<blockquote>. 
20500 20 53 45 4c 45 43 54 20 73 74 72 66 74 69 6d 65   SELECT strftime
20510 28 27 25 73 27 2c 27 6e 6f 77 27 29 3b 0a 3c 2f  ('%s','now');.</
20520 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e  blockquote>)^..^
20530 28 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68 65 20  (<p>Compute the 
20540 6e 75 6d 62 65 72 20 6f 66 20 64 61 79 73 20 73  number of days s
20550 69 6e 63 65 20 74 68 65 20 73 69 67 6e 69 6e 67  ince the signing
20560 20 6f 66 20 74 68 65 20 55 53 20 44 65 63 6c 61   of the US Decla
20570 72 61 74 69 6f 6e 0a 6f 66 20 49 6e 64 65 70 65  ration.of Indepe
20580 6e 64 65 6e 63 65 2e 3c 2f 70 3e 0a 0a 3c 62 6c  ndence.</p>..<bl
20590 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c 45  ockquote>.  SELE
205a0 43 54 20 6a 75 6c 69 61 6e 64 61 79 28 27 6e 6f  CT julianday('no
205b0 77 27 29 20 2d 20 6a 75 6c 69 61 6e 64 61 79 28  w') - julianday(
205c0 27 31 37 37 36 2d 30 37 2d 30 34 27 29 3b 0a 3c  '1776-07-04');.<
205d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a  /blockquote>)^..
205e0 5e 28 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68 65  ^(<p>Compute the
205f0 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 63 6f 6e   number of secon
20600 64 73 20 73 69 6e 63 65 20 61 20 70 61 72 74 69  ds since a parti
20610 63 75 6c 61 72 20 6d 6f 6d 65 6e 74 20 69 6e 20  cular moment in 
20620 32 30 30 34 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  2004:</p>..<bloc
20630 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c 45 43 54  kquote>.  SELECT
20640 20 73 74 72 66 74 69 6d 65 28 27 25 73 27 2c 27   strftime('%s','
20650 6e 6f 77 27 29 20 2d 20 73 74 72 66 74 69 6d 65  now') - strftime
20660 28 27 25 73 27 2c 27 32 30 30 34 2d 30 31 2d 30  ('%s','2004-01-0
20670 31 20 30 32 3a 33 34 3a 35 36 27 29 3b 0a 3c 2f  1 02:34:56');.</
20680 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e  blockquote>)^..^
20690 28 3c 70 3e 0a 43 6f 6d 70 75 74 65 20 74 68 65  (<p>.Compute the
206a0 20 64 61 74 65 20 6f 66 20 74 68 65 20 66 69 72   date of the fir
206b0 73 74 20 54 75 65 73 64 61 79 20 69 6e 20 4f 63  st Tuesday in Oc
206c0 74 6f 62 65 72 0a 66 6f 72 20 74 68 65 20 63 75  tober.for the cu
206d0 72 72 65 6e 74 20 79 65 61 72 2e 0a 3c 2f 70 3e  rrent year..</p>
206e0 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20  ..<blockquote>. 
206f0 20 53 45 4c 45 43 54 20 64 61 74 65 28 27 6e 6f   SELECT date('no
20700 77 27 2c 27 73 74 61 72 74 20 6f 66 20 79 65 61  w','start of yea
20710 72 27 2c 27 2b 39 20 6d 6f 6e 74 68 73 27 2c 27  r','+9 months','
20720 77 65 65 6b 64 61 79 20 32 27 29 3b 0a 3c 2f 62  weekday 2');.</b
20730 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28  lockquote>)^..^(
20740 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68 65 20 74  <p>Compute the t
20750 69 6d 65 20 73 69 6e 63 65 20 74 68 65 20 75 6e  ime since the un
20760 69 78 20 65 70 6f 63 68 20 69 6e 20 73 65 63 6f  ix epoch in seco
20770 6e 64 73 20 0a 28 6c 69 6b 65 20 73 74 72 66 74  nds .(like strft
20780 69 6d 65 28 27 25 73 27 2c 27 6e 6f 77 27 29 20  ime('%s','now') 
20790 65 78 63 65 70 74 20 69 6e 63 6c 75 64 65 73 20  except includes 
207a0 66 72 61 63 74 69 6f 6e 61 6c 20 70 61 72 74 29  fractional part)
207b0 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
207c0 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 28 6a 75  te>.  SELECT (ju
207d0 6c 69 61 6e 64 61 79 28 27 6e 6f 77 27 29 20 2d  lianday('now') -
207e0 20 32 34 34 30 35 38 37 2e 35 29 2a 38 36 34 30   2440587.5)*8640
207f0 30 2e 30 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  0.0;.</blockquot
20800 65 3e 29 5e 0a 0a 3c 68 33 3e 43 61 76 65 61 74  e>)^..<h3>Caveat
20810 73 20 41 6e 64 20 42 75 67 73 3c 2f 68 33 3e 0a  s And Bugs</h3>.
20820 0a 3c 70 3e 54 68 65 20 63 6f 6d 70 75 74 61 74  .<p>The computat
20830 69 6f 6e 20 6f 66 20 6c 6f 63 61 6c 20 74 69 6d  ion of local tim
20840 65 20 64 65 70 65 6e 64 73 20 68 65 61 76 69 6c  e depends heavil
20850 79 20 6f 6e 20 74 68 65 20 77 68 69 6d 20 0a 6f  y on the whim .o
20860 66 20 70 6f 6c 69 74 69 63 69 61 6e 73 20 61 6e  f politicians an
20870 64 20 69 73 20 74 68 75 73 20 64 69 66 66 69 63  d is thus diffic
20880 75 6c 74 20 74 6f 20 67 65 74 20 63 6f 72 72 65  ult to get corre
20890 63 74 20 66 6f 72 20 0a 61 6c 6c 20 6c 6f 63 61  ct for .all loca
208a0 6c 65 73 2e 20 5e 49 6e 20 74 68 69 73 20 69 6d  les. ^In this im
208b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
208c0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
208d0 72 61 72 79 20 0a 66 75 6e 63 74 69 6f 6e 20 6c  rary .function l
208e0 6f 63 61 6c 74 69 6d 65 5f 72 28 29 20 69 73 20  ocaltime_r() is 
208f0 75 73 65 64 20 74 6f 20 61 73 73 69 73 74 20 69  used to assist i
20900 6e 20 74 68 65 20 63 61 6c 63 75 6c 61 74 69 6f  n the calculatio
20910 6e 20 6f 66 20 0a 6c 6f 63 61 6c 20 74 69 6d 65  n of .local time
20920 2e 20 20 5e 28 54 68 65 20 0a 6c 6f 63 61 6c 74  .  ^(The .localt
20930 69 6d 65 5f 72 28 29 20 43 20 66 75 6e 63 74 69  ime_r() C functi
20940 6f 6e 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79  on normally only
20950 20 77 6f 72 6b 73 20 66 6f 72 20 79 65 61 72 73   works for years
20960 0a 62 65 74 77 65 65 6e 20 31 39 37 30 20 61 6e  .between 1970 an
20970 64 20 32 30 33 37 2e 20 46 6f 72 20 64 61 74 65  d 2037. For date
20980 73 20 6f 75 74 73 69 64 65 20 74 68 69 73 20 72  s outside this r
20990 61 6e 67 65 2c 20 53 51 4c 69 74 65 20 0a 61 74  ange, SQLite .at
209a0 74 65 6d 70 74 73 20 74 6f 20 6d 61 70 20 74 68  tempts to map th
209b0 65 20 79 65 61 72 20 69 6e 74 6f 20 61 6e 20 65  e year into an e
209c0 71 75 69 76 61 6c 65 6e 74 20 79 65 61 72 20 77  quivalent year w
209d0 69 74 68 69 6e 20 0a 74 68 69 73 20 72 61 6e 67  ithin .this rang
209e0 65 2c 20 64 6f 20 74 68 65 20 63 61 6c 63 75 6c  e, do the calcul
209f0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 61 70 20  ation, then map 
20a00 74 68 65 20 79 65 61 72 20 62 61 63 6b 2e 29 5e  the year back.)^
20a10 3c 2f 70 3e 0a 0a 0a 3c 70 3e 5e 28 54 68 65 73  </p>...<p>^(Thes
20a20 65 20 66 75 6e 63 74 69 6f 6e 73 20 6f 6e 6c 79  e functions only
20a30 20 77 6f 72 6b 20 66 6f 72 20 64 61 74 65 73 20   work for dates 
20a40 62 65 74 77 65 65 6e 20 30 30 30 30 2d 30 31 2d  between 0000-01-
20a50 30 31 20 30 30 3a 30 30 3a 30 30 0a 61 6e 64 20  01 00:00:00.and 
20a60 39 39 39 39 2d 31 32 2d 33 31 20 32 33 3a 35 39  9999-12-31 23:59
20a70 3a 35 39 20 28 6a 75 6c 69 64 61 6e 20 64 61 79  :59 (julidan day
20a80 20 6e 75 6d 62 65 72 73 20 31 37 32 31 30 35 39   numbers 1721059
20a90 2e 35 20 74 68 72 6f 75 67 68 20 35 33 37 33 34  .5 through 53734
20aa0 38 34 2e 35 29 2e 29 5e 0a 46 6f 72 20 64 61 74  84.5).)^.For dat
20ab0 65 73 20 6f 75 74 73 69 64 65 20 74 68 61 74 20  es outside that 
20ac0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
20ad0 74 73 20 6f 66 20 74 68 65 73 65 0a 66 75 6e 63  ts of these.func
20ae0 74 69 6f 6e 73 20 61 72 65 20 75 6e 64 65 66 69  tions are undefi
20af0 6e 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4e 6f 6e  ned.</p>..<p>Non
20b00 2d 56 69 73 74 61 20 57 69 6e 64 6f 77 73 20 70  -Vista Windows p
20b10 6c 61 74 66 6f 72 6d 73 20 6f 6e 6c 79 20 73 75  latforms only su
20b20 70 70 6f 72 74 20 6f 6e 65 20 73 65 74 20 6f 66  pport one set of
20b30 20 44 53 54 20 72 75 6c 65 73 2e 20 0a 56 69 73   DST rules. .Vis
20b40 74 61 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 73  ta only supports
20b50 20 74 77 6f 2e 20 54 68 65 72 65 66 6f 72 65 2c   two. Therefore,
20b60 20 6f 6e 20 74 68 65 73 65 20 70 6c 61 74 66 6f   on these platfo
20b70 72 6d 73 2c 20 0a 68 69 73 74 6f 72 69 63 61 6c  rms, .historical
20b80 20 44 53 54 20 63 61 6c 63 75 6c 61 74 69 6f 6e   DST calculation
20b90 73 20 77 69 6c 6c 20 62 65 20 69 6e 63 6f 72 72  s will be incorr
20ba0 65 63 74 2e 20 0a 46 6f 72 20 65 78 61 6d 70 6c  ect. .For exampl
20bb0 65 2c 20 69 6e 20 74 68 65 20 55 53 2c 20 69 6e  e, in the US, in
20bc0 20 32 30 30 37 20 74 68 65 20 44 53 54 20 72 75   2007 the DST ru
20bd0 6c 65 73 20 63 68 61 6e 67 65 64 2e 20 0a 4e 6f  les changed. .No
20be0 6e 2d 56 69 73 74 61 20 57 69 6e 64 6f 77 73 20  n-Vista Windows 
20bf0 70 6c 61 74 66 6f 72 6d 73 20 61 70 70 6c 79 20  platforms apply 
20c00 74 68 65 20 6e 65 77 20 32 30 30 37 20 44 53 54  the new 2007 DST
20c10 20 72 75 6c 65 73 20 0a 74 6f 20 61 6c 6c 20 70   rules .to all p
20c20 72 65 76 69 6f 75 73 20 79 65 61 72 73 20 61 73  revious years as
20c30 20 77 65 6c 6c 2e 20 56 69 73 74 61 20 64 6f 65   well. Vista doe
20c40 73 20 73 6f 6d 65 77 68 61 74 20 62 65 74 74 65  s somewhat bette
20c50 72 0a 67 65 74 74 69 6e 67 20 72 65 73 75 6c 74  r.getting result
20c60 73 20 63 6f 72 72 65 63 74 20 62 61 63 6b 20 74  s correct back t
20c70 6f 20 31 39 38 36 2c 20 77 68 65 6e 20 74 68 65  o 1986, when the
20c80 20 72 75 6c 65 73 20 77 65 72 65 20 61 6c 73 6f   rules were also
20c90 20 63 68 61 6e 67 65 64 2e 3c 2f 70 3e 0a 0a 3c   changed.</p>..<
20ca0 70 3e 41 6c 6c 20 69 6e 74 65 72 6e 61 6c 20 63  p>All internal c
20cb0 6f 6d 70 75 74 61 74 69 6f 6e 73 20 61 73 73 75  omputations assu
20cc0 6d 65 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f  me the .[http://
20cd0 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67  en.wikipedia.org
20ce0 2f 77 69 6b 69 2f 47 72 65 67 6f 72 69 61 6e 5f  /wiki/Gregorian_
20cf0 63 61 6c 65 6e 64 61 72 20 7c 20 47 72 65 67 6f  calendar | Grego
20d00 72 69 61 6e 20 63 61 6c 65 6e 64 61 72 5d 0a 73  rian calendar].s
20d10 79 73 74 65 6d 2e 20 20 49 74 20 69 73 20 61 6c  ystem.  It is al
20d20 73 6f 20 61 73 73 75 6d 65 64 20 74 68 61 74 20  so assumed that 
20d30 65 76 65 72 79 0a 64 61 79 20 69 73 20 65 78 61  every.day is exa
20d40 63 74 6c 79 20 38 36 34 30 30 20 73 65 63 6f 6e  ctly 86400 secon
20d50 64 73 20 69 6e 20 64 75 72 61 74 69 6f 6e 2e 3c  ds in duration.<
20d60 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  /p>..<tcl>.#####
20d70 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
20d80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
20d90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
20da0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
20db0 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
20dc0 6e 20 7b 41 67 67 72 65 67 61 74 65 20 46 75 6e  n {Aggregate Fun
20dd0 63 74 69 6f 6e 73 7d 20 61 67 67 66 75 6e 63 20  ctions} aggfunc 
20de0 7b 2a 61 67 67 66 75 6e 63 7d 0a 75 6e 73 65 74  {*aggfunc}.unset
20df0 20 2d 6e 6f 63 6f 6d 70 6c 61 69 6e 20 63 6f 72   -nocomplain cor
20e00 65 66 75 6e 63 73 65 74 0a 0a 66 75 6e 63 64 65  efuncset..funcde
20e10 66 20 7b 61 76 67 28 58 29 7d 20 7b 2a 61 76 67  f {avg(X)} {*avg
20e20 20 7b 61 76 67 28 29 20 61 67 67 72 65 67 61 74   {avg() aggregat
20e30 65 20 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20  e function}} {. 
20e40 20 5e 54 68 65 20 61 76 67 28 29 20 66 75 6e 63   ^The avg() func
20e50 74 69 6f 6e 0a 20 20 72 65 74 75 72 6e 73 20 74  tion.  returns t
20e60 68 65 20 61 76 65 72 61 67 65 20 76 61 6c 75 65  he average value
20e70 20 6f 66 20 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c   of all non-NULL
20e80 20 3c 69 3e 58 3c 2f 69 3e 20 77 69 74 68 69 6e   <i>X</i> within
20e90 20 61 0a 20 20 67 72 6f 75 70 2e 20 20 5e 53 74   a.  group.  ^St
20ea0 72 69 6e 67 20 61 6e 64 20 42 4c 4f 42 20 76 61  ring and BLOB va
20eb0 6c 75 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  lues that do not
20ec0 20 6c 6f 6f 6b 20 6c 69 6b 65 20 6e 75 6d 62 65   look like numbe
20ed0 72 73 20 61 72 65 0a 20 20 69 6e 74 65 72 70 72  rs are.  interpr
20ee0 65 74 65 64 20 61 73 20 30 2e 0a 20 20 5e 54 68  eted as 0..  ^Th
20ef0 65 20 72 65 73 75 6c 74 20 6f 66 20 61 76 67 28  e result of avg(
20f00 29 20 69 73 20 61 6c 77 61 79 73 20 61 20 66 6c  ) is always a fl
20f10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
20f20 75 65 20 61 73 20 6c 6f 6e 67 20 61 73 0a 20 20  ue as long as.  
20f30 61 74 20 74 68 65 72 65 20 69 73 20 61 74 20 6c  at there is at l
20f40 65 61 73 74 20 6f 6e 65 20 6e 6f 6e 2d 4e 55 4c  east one non-NUL
20f50 4c 20 69 6e 70 75 74 20 65 76 65 6e 20 69 66 20  L input even if 
20f60 61 6c 6c 0a 20 20 69 6e 70 75 74 73 20 61 72 65  all.  inputs are
20f70 20 69 6e 74 65 67 65 72 73 2e 20 20 5e 54 68 65   integers.  ^The
20f80 20 72 65 73 75 6c 74 20 6f 66 20 61 76 67 28 29   result of avg()
20f90 20 69 73 20 4e 55 4c 4c 20 69 66 20 61 6e 64 20   is NULL if and 
20fa0 6f 6e 6c 79 20 69 66 0a 20 20 74 68 65 72 65 20  only if.  there 
20fb0 61 72 65 20 6e 6f 20 6e 6f 6e 2d 4e 55 4c 4c 20  are no non-NULL 
20fc0 69 6e 70 75 74 73 2e 20 20 0a 7d 0a 0a 66 75 6e  inputs.  .}..fun
20fd0 63 64 65 66 20 7b 63 6f 75 6e 74 28 58 29 20 63  cdef {count(X) c
20fe0 6f 75 6e 74 28 2a 29 7d 20 7b 2a 63 6f 75 6e 74  ount(*)} {*count
20ff0 20 7b 63 6f 75 6e 74 28 29 20 61 67 67 72 65 67   {count() aggreg
21000 61 74 65 20 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b  ate function}} {
21010 0a 20 20 5e 54 68 65 20 63 6f 75 6e 74 28 58 29  .  ^The count(X)
21020 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
21030 73 0a 20 20 61 20 63 6f 75 6e 74 20 6f 66 20 74  s.  a count of t
21040 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
21050 65 73 0a 20 20 74 68 61 74 20 3c 69 3e 58 3c 2f  es.  that <i>X</
21060 69 3e 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 69  i> is not NULL i
21070 6e 20 61 20 67 72 6f 75 70 2e 20 20 5e 54 68 65  n a group.  ^The
21080 20 63 6f 75 6e 74 28 2a 29 20 66 75 6e 63 74 69   count(*) functi
21090 6f 6e 0a 20 20 28 77 69 74 68 20 6e 6f 20 61 72  on.  (with no ar
210a0 67 75 6d 65 6e 74 73 29 20 72 65 74 75 72 6e 73  guments) returns
210b0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
210c0 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
210d0 20 67 72 6f 75 70 2e 0a 7d 0a 0a 66 75 6e 63 64   group..}..funcd
210e0 65 66 20 7b 67 72 6f 75 70 5f 63 6f 6e 63 61 74  ef {group_concat
210f0 28 58 29 20 67 72 6f 75 70 5f 63 6f 6e 63 61 74  (X) group_concat
21100 28 58 2c 59 29 7d 20 7b 0a 20 20 2a 67 72 6f 75  (X,Y)} {.  *grou
21110 70 5f 63 6f 6e 63 61 74 20 7b 67 72 6f 75 70 5f  p_concat {group_
21120 63 6f 6e 63 61 74 28 29 20 61 67 67 72 65 67 61  concat() aggrega
21130 74 65 20 66 75 6e 63 74 69 6f 6e 7d 0a 7d 20 7b  te function}.} {
21140 0a 20 20 5e 54 68 65 20 67 72 6f 75 70 5f 63 6f  .  ^The group_co
21150 6e 63 61 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  ncat() function 
21160 72 65 74 75 72 6e 73 0a 20 20 61 20 73 74 72 69  returns.  a stri
21170 6e 67 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ng which is the 
21180 63 6f 6e 63 61 74 65 6e 61 74 69 6f 6e 20 6f 66  concatenation of
21190 0a 20 20 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20  .  all non-NULL 
211a0 76 61 6c 75 65 73 20 6f 66 20 3c 69 3e 58 3c 2f  values of <i>X</
211b0 69 3e 2e 20 20 5e 49 66 20 70 61 72 61 6d 65 74  i>.  ^If paramet
211c0 65 72 20 3c 69 3e 59 3c 2f 69 3e 20 69 73 20 70  er <i>Y</i> is p
211d0 72 65 73 65 6e 74 20 74 68 65 6e 0a 20 20 69 74  resent then.  it
211e0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
211f0 73 65 70 61 72 61 74 6f 72 0a 20 20 62 65 74 77  separator.  betw
21200 65 65 6e 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  een instances of
21210 20 3c 69 3e 58 3c 2f 69 3e 2e 20 20 5e 41 20 63   <i>X</i>.  ^A c
21220 6f 6d 6d 61 20 28 22 2c 22 29 20 69 73 20 75 73  omma (",") is us
21230 65 64 20 61 73 20 74 68 65 20 73 65 70 61 72 61  ed as the separa
21240 74 6f 72 0a 20 20 69 66 20 3c 69 3e 59 3c 2f 69  tor.  if <i>Y</i
21250 3e 20 69 73 20 6f 6d 69 74 74 65 64 2e 20 20 54  > is omitted.  T
21260 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  he order of the 
21270 63 6f 6e 63 61 74 65 6e 61 74 65 64 20 65 6c 65  concatenated ele
21280 6d 65 6e 74 73 20 69 73 0a 20 20 61 72 62 69 74  ments is.  arbit
21290 72 61 72 79 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  rary..}..funcdef
212a0 20 7b 6d 61 78 28 58 29 7d 20 7b 2a 6d 61 78 41   {max(X)} {*maxA
212b0 67 67 46 75 6e 63 20 2a 61 67 67 5f 6d 61 78 20  ggFunc *agg_max 
212c0 7b 6d 61 78 28 29 20 61 67 67 72 65 67 61 74 65  {max() aggregate
212d0 20 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20   function}} {.  
212e0 5e 54 68 65 20 6d 61 78 28 29 20 61 67 67 72 65  ^The max() aggre
212f0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 20 20  gate function.  
21300 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
21310 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 6c 6c  mum value of all
21320 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 67   values in the g
21330 72 6f 75 70 2e 0a 20 20 5e 54 68 65 20 6d 61 78  roup..  ^The max
21340 69 6d 75 6d 20 76 61 6c 75 65 20 69 73 20 74 68  imum value is th
21350 65 20 76 61 6c 75 65 20 74 68 61 74 20 77 6f 75  e value that wou
21360 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 20 6c  ld be returned l
21370 61 73 74 20 69 6e 20 61 6e 0a 20 20 4f 52 44 45  ast in an.  ORDE
21380 52 20 42 59 20 6f 6e 20 74 68 65 20 73 61 6d 65  R BY on the same
21390 20 63 6f 6c 75 6d 6e 2e 20 20 5e 41 67 67 72 65   column.  ^Aggre
213a0 67 61 74 65 20 6d 61 78 28 29 20 72 65 74 75 72  gate max() retur
213b0 6e 73 20 4e 55 4c 4c 20 0a 20 20 69 66 20 61 6e  ns NULL .  if an
213c0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 72 65 20  d only if there 
213d0 61 72 65 20 6e 6f 20 6e 6f 6e 2d 4e 55 4c 4c 20  are no non-NULL 
213e0 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 67 72  values in the gr
213f0 6f 75 70 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  oup..}..funcdef 
21400 7b 6d 69 6e 28 58 29 7d 20 7b 2a 6d 69 6e 41 67  {min(X)} {*minAg
21410 67 46 75 6e 63 20 2a 61 67 67 5f 6d 69 6e 20 7b  gFunc *agg_min {
21420 6d 69 6e 28 29 20 61 67 67 72 65 67 61 74 65 20  min() aggregate 
21430 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e  function}} {.  ^
21440 54 68 65 20 6d 69 6e 28 29 20 61 67 67 72 65 67  The min() aggreg
21450 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 20 20 72  ate function.  r
21460 65 74 75 72 6e 73 20 74 68 65 20 6d 69 6e 69 6d  eturns the minim
21470 75 6d 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75  um non-NULL valu
21480 65 20 6f 66 20 61 6c 6c 20 76 61 6c 75 65 73 20  e of all values 
21490 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 0a 20 20  in the group..  
214a0 5e 54 68 65 20 6d 69 6e 69 6d 75 6d 20 76 61 6c  ^The minimum val
214b0 75 65 20 69 73 20 74 68 65 20 66 69 72 73 74 20  ue is the first 
214c0 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 74  non-NULL value t
214d0 68 61 74 20 77 6f 75 6c 64 20 61 70 70 65 61 72  hat would appear
214e0 0a 20 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  .  in an ORDER B
214f0 59 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 2e  Y of the column.
21500 0a 20 20 5e 41 67 67 72 65 67 61 74 65 20 6d 69  .  ^Aggregate mi
21510 6e 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  n() returns NULL
21520 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
21530 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6e 6f 6e  there are no non
21540 2d 4e 55 4c 4c 0a 20 20 76 61 6c 75 65 73 20 69  -NULL.  values i
21550 6e 20 74 68 65 20 67 72 6f 75 70 2e 0a 7d 0a 0a  n the group..}..
21560 66 75 6e 63 64 65 66 20 7b 73 75 6d 28 58 29 20  funcdef {sum(X) 
21570 74 6f 74 61 6c 28 58 29 7d 20 7b 0a 20 20 2a 73  total(X)} {.  *s
21580 75 6d 46 75 6e 63 20 2a 73 75 6d 20 2a 74 6f 74  umFunc *sum *tot
21590 61 6c 0a 20 20 7b 73 75 6d 28 29 20 61 67 67 72  al.  {sum() aggr
215a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 7d 0a  egate function}.
215b0 20 20 7b 74 6f 74 61 6c 28 29 20 61 67 67 72 65    {total() aggre
215c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 7d 0a 7d  gate function}.}
215d0 20 7b 0a 20 20 5e 54 68 65 20 73 75 6d 28 29 20   {.  ^The sum() 
215e0 61 6e 64 20 74 6f 74 61 6c 28 29 20 61 67 67 72  and total() aggr
215f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 0a  egate functions.
21600 20 20 72 65 74 75 72 6e 20 73 75 6d 20 6f 66 20    return sum of 
21610 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c  all non-NULL val
21620 75 65 73 20 69 6e 20 74 68 65 20 67 72 6f 75 70  ues in the group
21630 2e 0a 20 20 5e 49 66 20 74 68 65 72 65 20 61 72  ..  ^If there ar
21640 65 20 6e 6f 20 6e 6f 6e 2d 4e 55 4c 4c 20 69 6e  e no non-NULL in
21650 70 75 74 20 72 6f 77 73 20 74 68 65 6e 20 73 75  put rows then su
21660 6d 28 29 20 72 65 74 75 72 6e 73 0a 20 20 4e 55  m() returns.  NU
21670 4c 4c 20 62 75 74 20 74 6f 74 61 6c 28 29 20 72  LL but total() r
21680 65 74 75 72 6e 73 20 30 2e 30 2e 0a 20 20 4e 55  eturns 0.0..  NU
21690 4c 4c 20 69 73 20 6e 6f 74 20 6e 6f 72 6d 61 6c  LL is not normal
216a0 6c 79 20 61 20 68 65 6c 70 66 75 6c 20 72 65 73  ly a helpful res
216b0 75 6c 74 20 66 6f 72 20 74 68 65 20 73 75 6d 20  ult for the sum 
216c0 6f 66 20 6e 6f 20 72 6f 77 73 0a 20 20 62 75 74  of no rows.  but
216d0 20 74 68 65 20 53 51 4c 20 73 74 61 6e 64 61 72   the SQL standar
216e0 64 20 72 65 71 75 69 72 65 73 20 69 74 20 61 6e  d requires it an
216f0 64 20 6d 6f 73 74 20 6f 74 68 65 72 0a 20 20 53  d most other.  S
21700 51 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  QL database engi
21710 6e 65 73 20 69 6d 70 6c 65 6d 65 6e 74 20 73 75  nes implement su
21720 6d 28 29 20 74 68 61 74 20 77 61 79 20 73 6f 20  m() that way so 
21730 53 51 4c 69 74 65 20 64 6f 65 73 20 69 74 20 69  SQLite does it i
21740 6e 20 74 68 65 0a 20 20 73 61 6d 65 20 77 61 79  n the.  same way
21750 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20   in order to be 
21760 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 20 54 68  compatible.   Th
21770 65 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 74  e non-standard t
21780 6f 74 61 6c 28 29 20 66 75 6e 63 74 69 6f 6e 0a  otal() function.
21790 20 20 69 73 20 70 72 6f 76 69 64 65 64 20 61 73    is provided as
217a0 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61   a convenient wa
217b0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
217c0 20 74 68 69 73 20 64 65 73 69 67 6e 20 70 72 6f   this design pro
217d0 62 6c 65 6d 0a 20 20 69 6e 20 74 68 65 20 53 51  blem.  in the SQ
217e0 4c 20 6c 61 6e 67 75 61 67 65 2e 3c 2f 70 3e 0a  L language.</p>.
217f0 0a 20 20 3c 70 3e 5e 54 68 65 20 72 65 73 75 6c  .  <p>^The resul
21800 74 20 6f 66 20 74 6f 74 61 6c 28 29 20 69 73 20  t of total() is 
21810 61 6c 77 61 79 73 20 61 20 66 6c 6f 61 74 69 6e  always a floatin
21820 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 20  g point value.. 
21830 20 5e 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20   ^The result of 
21840 73 75 6d 28 29 20 69 73 20 61 6e 20 69 6e 74 65  sum() is an inte
21850 67 65 72 20 76 61 6c 75 65 20 69 66 20 61 6c 6c  ger value if all
21860 20 6e 6f 6e 2d 4e 55 4c 4c 20 69 6e 70 75 74 73   non-NULL inputs
21870 20 61 72 65 20 69 6e 74 65 67 65 72 73 2e 0a 20   are integers.. 
21880 20 5e 49 66 20 61 6e 79 20 69 6e 70 75 74 20 74   ^If any input t
21890 6f 20 73 75 6d 28 29 20 69 73 20 6e 65 69 74 68  o sum() is neith
218a0 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  er an integer or
218b0 20 61 20 4e 55 4c 4c 0a 20 20 74 68 65 6e 20 73   a NULL.  then s
218c0 75 6d 28 29 20 72 65 74 75 72 6e 73 20 61 20 66  um() returns a f
218d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
218e0 6c 75 65 0a 20 20 77 68 69 63 68 20 6d 69 67 68  lue.  which migh
218f0 74 20 62 65 20 61 6e 20 61 70 70 72 6f 78 69 6d  t be an approxim
21900 61 74 69 6f 6e 20 74 6f 20 74 68 65 20 74 72 75  ation to the tru
21910 65 20 73 75 6d 2e 3c 2f 70 3e 0a 0a 20 20 3c 70  e sum.</p>..  <p
21920 3e 5e 53 75 6d 28 29 20 77 69 6c 6c 20 74 68 72  >^Sum() will thr
21930 6f 77 20 61 6e 20 22 69 6e 74 65 67 65 72 20 6f  ow an "integer o
21940 76 65 72 66 6c 6f 77 22 20 65 78 63 65 70 74 69  verflow" excepti
21950 6f 6e 20 69 66 20 61 6c 6c 20 69 6e 70 75 74 73  on if all inputs
21960 0a 20 20 61 72 65 20 69 6e 74 65 67 65 72 73 20  .  are integers 
21970 6f 72 20 4e 55 4c 4c 0a 20 20 61 6e 64 20 61 6e  or NULL.  and an
21980 20 69 6e 74 65 67 65 72 20 6f 76 65 72 66 6c 6f   integer overflo
21990 77 20 6f 63 63 75 72 73 20 61 74 20 61 6e 79 20  w occurs at any 
219a0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
219b0 20 63 6f 6d 70 75 74 61 74 69 6f 6e 2e 0a 20 20   computation..  
219c0 5e 54 6f 74 61 6c 28 29 20 6e 65 76 65 72 20 74  ^Total() never t
219d0 68 72 6f 77 73 20 61 6e 20 69 6e 74 65 67 65 72  hrows an integer
219e0 20 6f 76 65 72 66 6c 6f 77 2e 0a 7d 0a 3c 2f 74   overflow..}.</t
219f0 63 6c 3e 0a 0a 0a 3c 70 3e 0a 54 68 65 20 61 67  cl>...<p>.The ag
21a00 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
21a10 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 20 61 72  s shown below ar
21a20 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20 64  e available by d
21a30 65 66 61 75 6c 74 2e 20 20 41 64 64 69 74 69 6f  efault.  Additio
21a40 6e 61 6c 0a 61 67 67 72 65 67 61 74 65 20 66 75  nal.aggregate fu
21a50 6e 63 74 69 6f 6e 73 20 77 72 69 74 74 65 6e 20  nctions written 
21a60 69 6e 20 43 20 6d 61 79 20 62 65 20 61 64 64 65  in C may be adde
21a70 64 20 75 73 69 6e 67 20 74 68 65 20 0a 5b 73 71  d using the .[sq
21a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
21a90 63 74 69 6f 6e 28 29 5d 3c 2f 61 3e 0a 41 50 49  ction()]</a>.API
21aa0 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 49 6e 20 61  .</p>..<p>.^In a
21ab0 6e 79 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ny aggregate fun
21ac0 63 74 69 6f 6e 20 74 68 61 74 20 74 61 6b 65 73  ction that takes
21ad0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
21ae0 6e 74 2c 20 74 68 61 74 20 61 72 67 75 6d 65 6e  nt, that argumen
21af0 74 0a 63 61 6e 20 62 65 20 70 72 65 63 65 64 65  t.can be precede
21b00 64 20 62 79 20 74 68 65 20 6b 65 79 77 6f 72 64  d by the keyword
21b10 20 44 49 53 54 49 4e 43 54 2e 20 20 5e 49 6e 20   DISTINCT.  ^In 
21b20 73 75 63 68 20 63 61 73 65 73 2c 20 64 75 70 6c  such cases, dupl
21b30 69 63 61 74 65 0a 65 6c 65 6d 65 6e 74 73 20 61  icate.elements a
21b40 72 65 20 66 69 6c 74 65 72 65 64 20 62 65 66 6f  re filtered befo
21b50 72 65 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  re being passed 
21b60 69 6e 74 6f 20 74 68 65 20 61 67 67 72 65 67 61  into the aggrega
21b70 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 5e 46 6f  te function..^Fo
21b80 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66  r example, the f
21b90 75 6e 63 74 69 6f 6e 20 22 63 6f 75 6e 74 28 64  unction "count(d
21ba0 69 73 74 69 6e 63 74 20 58 29 22 20 77 69 6c 6c  istinct X)" will
21bb0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   return the numb
21bc0 65 72 0a 6f 66 20 64 69 73 74 69 6e 63 74 20 76  er.of distinct v
21bd0 61 6c 75 65 73 20 6f 66 20 63 6f 6c 75 6d 6e 20  alues of column 
21be0 58 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  X instead of the
21bf0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
21c00 20 6e 6f 6e 2d 6e 75 6c 6c 0a 76 61 6c 75 65 73   non-null.values
21c10 20 69 6e 20 63 6f 6c 75 6d 6e 20 58 2e 0a 3c 2f   in column X..</
21c20 70 3e 0a 0a 3c 74 63 6c 3e 0a 73 65 74 20 6c 78  p>..<tcl>.set lx
21c30 20 7b 7d 0a 66 6f 72 65 61 63 68 20 62 61 73 65   {}.foreach base
21c40 73 79 6e 74 61 78 20 5b 61 72 72 61 79 20 6e 61  syntax [array na
21c50 6d 65 73 20 63 6f 72 65 66 75 6e 63 73 65 74 5d  mes corefuncset]
21c60 20 7b 0a 20 20 66 6f 72 65 61 63 68 20 7b 73 79   {.  foreach {sy
21c70 6e 74 61 78 20 6b 65 79 77 6f 72 64 73 20 64 65  ntax keywords de
21c80 73 63 7d 20 24 63 6f 72 65 66 75 6e 63 73 65 74  sc} $corefuncset
21c90 28 24 62 61 73 65 73 79 6e 74 61 78 29 20 62 72  ($basesyntax) br
21ca0 65 61 6b 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b  eak.  regexp {^[
21cb0 61 2d 7a 5f 5d 2b 7d 20 24 62 61 73 65 73 79 6e  a-z_]+} $basesyn
21cc0 74 61 78 20 66 72 61 67 6d 65 6e 74 0a 20 20 66  tax fragment.  f
21cd0 6f 72 65 61 63 68 20 63 6f 72 65 73 79 6e 74 61  oreach coresynta
21ce0 78 20 24 73 79 6e 74 61 78 20 7b 0a 20 20 20 20  x $syntax {.    
21cf0 6c 61 70 70 65 6e 64 20 6c 78 20 5b 6c 69 73 74  lappend lx [list
21d00 20 24 66 72 61 67 6d 65 6e 74 20 24 63 6f 72 65   $fragment $core
21d10 73 79 6e 74 61 78 20 30 5d 0a 20 20 7d 0a 7d 0a  syntax 0].  }.}.
21d20 68 64 5f 6c 69 73 74 5f 6f 66 5f 6c 69 6e 6b 73  hd_list_of_links
21d30 20 7b 7d 20 32 32 35 20 5b 6c 73 6f 72 74 20 2d   {} 225 [lsort -
21d40 69 6e 64 65 78 20 31 20 24 6c 78 5d 0a 0a 68 64  index 1 $lx]..hd
21d50 5f 70 75 74 73 6e 6c 20 22 3c 68 72 20 63 6c 61  _putsnl "<hr cla
21d60 73 73 3d 27 78 68 72 27 3e 22 0a 68 64 5f 70 75  ss='xhr'>".hd_pu
21d70 74 73 6e 6c 20 22 3c 64 6c 3e 22 0a 66 6f 72 65  tsnl "<dl>".fore
21d80 61 63 68 20 62 61 73 65 73 79 6e 74 61 78 20 5b  ach basesyntax [
21d90 6c 73 6f 72 74 20 5b 61 72 72 61 79 20 6e 61 6d  lsort [array nam
21da0 65 73 20 63 6f 72 65 66 75 6e 63 73 65 74 5d 5d  es corefuncset]]
21db0 20 7b 0a 20 20 66 6f 72 65 61 63 68 20 7b 73 79   {.  foreach {sy
21dc0 6e 74 61 78 20 6b 65 79 77 6f 72 64 73 20 64 65  ntax keywords de
21dd0 73 63 7d 20 24 63 6f 72 65 66 75 6e 63 73 65 74  sc} $corefuncset
21de0 28 24 62 61 73 65 73 79 6e 74 61 78 29 20 62 72  ($basesyntax) br
21df0 65 61 6b 0a 20 20 72 65 67 73 75 62 20 2d 61 6c  eak.  regsub -al
21e00 6c 20 7b 5c 73 2b 7d 20 5b 73 74 72 69 6e 67 20  l {\s+} [string 
21e10 74 72 69 6d 20 24 73 79 6e 74 61 78 5d 20 7b 3c  trim $syntax] {<
21e20 62 72 20 2f 3e 7d 20 73 79 6e 74 61 78 0a 20 20  br />} syntax.  
21e30 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5c 28 28  regsub -all {\((
21e40 5b 5e 2a 29 5d 2b 29 5c 29 7d 20 24 73 79 6e 74  [^*)]+)\)} $synt
21e50 61 78 20 7b 28 3c 69 3e 5c 31 3c 2f 69 3e 29 7d  ax {(<i>\1</i>)}
21e60 20 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75 62   syntax.  regsub
21e70 20 2d 61 6c 6c 20 7b 2c 7d 20 24 73 79 6e 74 61   -all {,} $synta
21e80 78 20 7b 3c 2f 69 3e 2c 3c 69 3e 7d 20 73 79 6e  x {</i>,<i>} syn
21e90 74 61 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c  tax.  regsub -al
21ea0 6c 20 7b 3c 69 3e 5c 2e 5c 2e 5c 2e 3c 2f 69 3e  l {<i>\.\.\.</i>
21eb0 7d 20 24 73 79 6e 74 61 78 20 7b 2e 2e 2e 7d 20  } $syntax {...} 
21ec0 73 79 6e 74 61 78 0a 20 20 72 65 67 65 78 70 20  syntax.  regexp 
21ed0 7b 5e 5b 61 2d 7a 5d 2b 7d 20 24 62 61 73 65 73  {^[a-z]+} $bases
21ee0 79 6e 74 61 78 20 66 72 61 67 6d 65 6e 74 0a 20  yntax fragment. 
21ef0 20 69 66 20 7b 5b 6c 6c 65 6e 67 74 68 20 24 6b   if {[llength $k
21f00 65 79 77 6f 72 64 73 5d 3d 3d 30 7d 20 7b 0a 20  eywords]==0} {. 
21f10 20 20 20 72 65 67 65 78 70 20 7b 5b 61 2d 7a 5f     regexp {[a-z_
21f20 5d 2b 7d 20 24 73 79 6e 74 61 78 20 6e 61 6d 65  ]+} $syntax name
21f30 0a 20 20 20 20 68 64 5f 66 72 61 67 6d 65 6e 74  .    hd_fragment
21f40 20 24 6e 61 6d 65 20 2a 24 6e 61 6d 65 20 22 24   $name *$name "$
21f50 7b 6e 61 6d 65 7d 28 29 20 53 51 4c 20 66 75 6e  {name}() SQL fun
21f60 63 74 69 6f 6e 22 0a 20 20 7d 20 65 6c 73 65 20  ction".  } else 
21f70 7b 0a 20 20 20 20 73 65 74 20 66 72 61 67 6e 61  {.    set fragna
21f80 6d 65 20 5b 6c 69 6e 64 65 78 20 24 6b 65 79 77  me [lindex $keyw
21f90 6f 72 64 73 20 30 5d 0a 20 20 20 20 72 65 67 73  ords 0].    regs
21fa0 75 62 20 2d 61 6c 6c 20 7b 5b 5e 61 2d 7a 5d 7d  ub -all {[^a-z]}
21fb0 20 24 66 72 61 67 6e 61 6d 65 20 7b 7d 20 66 72   $fragname {} fr
21fc0 61 67 6e 61 6d 65 0a 20 20 20 20 68 64 5f 66 72  agname.    hd_fr
21fd0 61 67 6d 65 6e 74 20 24 66 72 61 67 6e 61 6d 65  agment $fragname
21fe0 0a 20 20 20 20 65 76 61 6c 20 68 64 5f 6b 65 79  .    eval hd_key
21ff0 77 6f 72 64 73 20 5b 73 74 72 69 6e 67 20 6d 61  words [string ma
22000 70 20 7b 5c 6e 20 7b 20 7d 7d 20 24 6b 65 79 77  p {\n { }} $keyw
22010 6f 72 64 73 5d 0a 20 20 7d 0a 20 20 68 64 5f 70  ords].  }.  hd_p
22020 75 74 73 20 22 3c 64 74 3e 3c 70 3e 3c 62 3e 24  uts "<dt><p><b>$
22030 73 79 6e 74 61 78 3c 2f 62 3e 3c 2f 64 74 3e 22  syntax</b></dt>"
22040 0a 20 20 68 64 5f 72 65 73 6f 6c 76 65 20 22 3c  .  hd_resolve "<
22050 64 64 3e 3c 70 3e 24 64 65 73 63 3c 2f 64 64 3e  dd><p>$desc</dd>
22060 5c 6e 22 0a 7d 0a 68 64 5f 70 75 74 73 6e 6c 20  \n".}.hd_putsnl 
22070 22 3c 2f 64 6c 3e 22 0a 0a 23 23 23 23 23 23 23  "</dl>"..#######
22080 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
22090 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
220a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
220b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
220c0 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
220d0 49 4e 53 45 52 54 20 69 6e 73 65 72 74 20 7b 49  INSERT insert {I
220e0 4e 53 45 52 54 20 2a 49 4e 53 45 52 54 73 7d 0a  NSERT *INSERTs}.
220f0 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65  .RecursiveBubble
22100 44 69 61 67 72 61 6d 20 69 6e 73 65 72 74 2d 73  Diagram insert-s
22110 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54  tmt.</tcl>..<p>T
22120 68 65 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d  he INSERT statem
22130 65 6e 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 72  ent comes in thr
22140 65 65 20 62 61 73 69 63 20 66 6f 72 6d 73 2e 20  ee basic forms. 
22150 20 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 3c 62   .<ol>.<li><p><b
22160 3e 49 4e 53 45 52 54 20 49 4e 54 4f 20 3c 2f 62  >INSERT INTO </b
22170 3e 3c 69 3e 74 61 62 6c 65 3c 2f 69 3e 3c 62 3e  ><i>table</i><b>
22180 20 56 41 4c 55 45 53 28 2e 2e 2e 29 3b 3c 2f 62   VALUES(...);</b
22190 3e 0a 3c 70 3e 5e 54 68 65 20 66 69 72 73 74 20  >.<p>^The first 
221a0 66 6f 72 6d 20 28 77 69 74 68 20 74 68 65 20 22  form (with the "
221b0 56 41 4c 55 45 53 22 20 6b 65 79 77 6f 72 64 29  VALUES" keyword)
221c0 20 63 72 65 61 74 65 73 20 6f 6e 65 20 6f 72 20   creates one or 
221d0 6d 6f 72 65 0a 6e 65 77 20 72 6f 77 73 20 69 6e  more.new rows in
221e0 0a 61 6e 20 65 78 69 73 74 69 6e 67 20 74 61 62  .an existing tab
221f0 6c 65 2e 20 5e 49 66 20 74 68 65 20 3c 79 79 74  le. ^If the <yyt
22200 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c  erm>column-name<
22210 2f 79 79 74 65 72 6d 3e 20 6c 69 73 74 20 61 66  /yyterm> list af
22220 74 65 72 0a 3c 79 79 74 65 72 6d 3e 74 61 62 6c  ter.<yyterm>tabl
22230 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  e-name</yyterm> 
22240 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 6e 20  is omitted then 
22250 74 68 65 20 6e 75 6d 62 65 72 0a 6f 66 20 76 61  the number.of va
22260 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e  lues inserted in
22270 74 6f 20 65 61 63 68 20 72 6f 77 0a 6d 75 73 74  to each row.must
22280 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20   be the same as 
22290 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
222a0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62  lumns in the tab
222b0 6c 65 2e 20 5e 49 6e 20 74 68 69 73 20 63 61 73  le. ^In this cas
222c0 65 0a 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e.the result of 
222d0 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 6c  evaluating the l
222e0 65 66 74 2d 6d 6f 73 74 20 65 78 70 72 65 73 73  eft-most express
222f0 69 6f 6e 20 66 72 6f 6d 20 65 61 63 68 20 74 65  ion from each te
22300 72 6d 20 6f 66 0a 74 68 65 20 56 41 4c 55 45 53  rm of.the VALUES
22310 20 6c 69 73 74 20 69 73 20 69 6e 73 65 72 74 65   list is inserte
22320 64 20 69 6e 74 6f 20 74 68 65 20 6c 65 66 74 2d  d into the left-
22330 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 65  most column of e
22340 61 63 68 20 6e 65 77 20 72 6f 77 2c 0a 61 6e 64  ach new row,.and
22350 20 73 6f 20 66 6f 72 74 68 20 66 6f 72 20 65 61   so forth for ea
22360 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 65 78  ch subsequent ex
22370 70 72 65 73 73 69 6f 6e 2e 20 5e 49 66 20 61 20  pression. ^If a 
22380 3c 79 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e  <yyterm>column-n
22390 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 0a 6c 69 73  ame</yyterm>.lis
223a0 74 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  t is specified, 
223b0 74 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  then the number 
223c0 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 65 61 63  of values in eac
223d0 68 20 74 65 72 6d 20 6f 66 20 74 68 65 0a 56 41  h term of the.VA
223e0 4c 55 45 20 6c 69 73 74 20 6d 75 73 74 20 6d 61  LUE list must ma
223f0 74 63 68 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  tch the number o
22400 66 0a 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  f.specified colu
22410 6d 6e 73 2e 20 5e 45 61 63 68 20 6f 66 20 74 68  mns. ^Each of th
22420 65 20 6e 61 6d 65 64 20 63 6f 6c 75 6d 6e 73 20  e named columns 
22430 6f 66 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69  of the new row i
22440 73 20 70 6f 70 75 6c 61 74 65 64 0a 77 69 74 68  s populated.with
22450 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
22460 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 63  evaluating the c
22470 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 56 41 4c  orresponding VAL
22480 55 45 53 20 65 78 70 72 65 73 73 69 6f 6e 2e 20  UES expression. 
22490 5e 54 61 62 6c 65 0a 63 6f 6c 75 6d 6e 73 20 74  ^Table.columns t
224a0 68 61 74 20 64 6f 20 6e 6f 74 20 61 70 70 65 61  hat do not appea
224b0 72 20 69 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  r in the column 
224c0 6c 69 73 74 20 61 72 65 20 70 6f 70 75 6c 61 74  list are populat
224d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 5b 64 65  ed with the .[de
224e0 66 61 75 6c 74 20 63 6f 6c 75 6d 6e 20 76 61 6c  fault column val
224f0 75 65 5d 20 28 73 70 65 63 69 66 69 65 64 20 61  ue] (specified a
22500 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 5b 43  s part of the [C
22510 52 45 41 54 45 20 54 41 42 4c 45 5d 20 73 74 61  REATE TABLE] sta
22520 74 65 6d 65 6e 74 29 2c 20 6f 72 0a 77 69 74 68  tement), or.with
22530 20 4e 55 4c 4c 20 69 66 20 6e 6f 20 5b 64 65 66   NULL if no [def
22540 61 75 6c 74 20 76 61 6c 75 65 5d 20 69 73 20 73  ault value] is s
22550 70 65 63 69 66 69 65 64 2e 0a 0a 3c 6c 69 3e 3c  pecified...<li><
22560 70 3e 3c 62 3e 49 4e 53 45 52 54 20 49 4e 54 4f  p><b>INSERT INTO
22570 20 3c 2f 62 3e 3c 69 3e 74 61 62 6c 65 3c 2f 69   </b><i>table</i
22580 3e 3c 62 3e 20 53 45 4c 45 43 54 20 2e 2e 2e 3b  ><b> SELECT ...;
22590 3c 2f 62 3e 0a 3c 70 3e 54 68 65 20 73 65 63 6f  </b>.<p>The seco
225a0 6e 64 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 49  nd form of the I
225b0 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20  NSERT statement 
225c0 63 6f 6e 74 61 69 6e 73 20 61 20 5b 53 45 4c 45  contains a [SELE
225d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 0a 69 6e  CT] statement.in
225e0 73 74 65 61 64 20 6f 66 20 61 20 56 41 4c 55 45  stead of a VALUE
225f0 53 20 63 6c 61 75 73 65 2e 20 5e 41 20 6e 65 77  S clause. ^A new
22600 20 65 6e 74 72 79 20 69 73 20 69 6e 73 65 72 74   entry is insert
22610 65 64 20 69 6e 74 6f 20 74 68 65 20 74 61 62 6c  ed into the tabl
22620 65 20 66 6f 72 20 65 61 63 68 0a 72 6f 77 20 6f  e for each.row o
22630 66 20 64 61 74 61 20 72 65 74 75 72 6e 65 64 20  f data returned 
22640 62 79 20 65 78 65 63 75 74 69 6e 67 20 74 68 65  by executing the
22650 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22660 74 2e 20 5e 49 66 20 61 20 63 6f 6c 75 6d 6e 2d  t. ^If a column-
22670 6c 69 73 74 20 69 73 0a 73 70 65 63 69 66 69 65  list is.specifie
22680 64 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  d, the number of
22690 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
226a0 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 53 45  result of the SE
226b0 4c 45 43 54 20 6d 75 73 74 20 62 65 20 74 68 65  LECT must be the
226c0 20 73 61 6d 65 0a 61 73 20 74 68 65 20 6e 75 6d   same.as the num
226d0 62 65 72 20 6f 66 20 69 74 65 6d 73 20 69 6e 20  ber of items in 
226e0 74 68 65 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 2e  the column-list.
226f0 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20   ^Otherwise, if 
22700 6e 6f 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 20 69  no column-list i
22710 73 0a 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s.specified, the
22720 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
22730 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
22740 20 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20 6d   of the SELECT m
22750 75 73 74 20 62 65 20 74 68 65 20 73 61 6d 65 0a  ust be the same.
22760 61 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  as the number of
22770 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
22780 74 61 62 6c 65 2e 20 5e 41 6e 79 20 53 45 4c 45  table. ^Any SELE
22790 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  CT statement, in
227a0 63 6c 75 64 69 6e 67 0a 5b 63 6f 6d 70 6f 75 6e  cluding.[compoun
227b0 64 20 53 45 4c 45 43 54 73 5d 20 61 6e 64 20 53  d SELECTs] and S
227c0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
227d0 20 77 69 74 68 20 5b 4f 52 44 45 52 20 42 59 5d   with [ORDER BY]
227e0 20 61 6e 64 2f 6f 72 20 5b 4c 49 4d 49 54 5d 20   and/or [LIMIT] 
227f0 63 6c 61 75 73 65 73 2c 20 0a 6d 61 79 20 62 65  clauses, .may be
22800 20 75 73 65 64 20 69 6e 20 61 6e 20 49 4e 53 45   used in an INSE
22810 52 54 20 73 74 61 74 65 6d 65 6e 74 20 6f 66 20  RT statement of 
22820 74 68 69 73 20 66 6f 72 6d 2e 0a 0a 3c 6c 69 3e  this form...<li>
22830 3c 70 3e 3c 62 3e 49 4e 53 45 52 54 20 49 4e 54  <p><b>INSERT INT
22840 4f 20 3c 2f 62 3e 3c 69 3e 74 61 62 6c 65 3c 2f  O </b><i>table</
22850 69 3e 3c 62 3e 20 44 45 46 41 55 4c 54 20 56 41  i><b> DEFAULT VA
22860 4c 55 45 53 3b 3c 2f 62 3e 0a 3c 70 3e 54 68 65  LUES;</b>.<p>The
22870 20 74 68 69 72 64 20 66 6f 72 6d 20 6f 66 20 61   third form of a
22880 6e 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65  n INSERT stateme
22890 6e 74 20 69 73 20 77 69 74 68 20 44 45 46 41 55  nt is with DEFAU
228a0 4c 54 20 56 41 4c 55 45 53 2e 0a 5e 28 54 68 65  LT VALUES..^(The
228b0 20 49 4e 53 45 52 54 20 2e 2e 2e 20 44 45 46 41   INSERT ... DEFA
228c0 55 4c 54 20 56 41 4c 55 45 53 20 73 74 61 74 65  ULT VALUES state
228d0 6d 65 6e 74 20 69 6e 73 65 72 74 73 20 61 20 73  ment inserts a s
228e0 69 6e 67 6c 65 20 6e 65 77 20 72 6f 77 20 69 6e  ingle new row in
228f0 74 6f 20 74 68 65 0a 6e 61 6d 65 64 20 74 61 62  to the.named tab
22900 6c 65 2e 29 5e 20 5e 45 61 63 68 20 63 6f 6c 75  le.)^ ^Each colu
22910 6d 6e 20 6f 66 20 74 68 65 20 6e 65 77 20 72 6f  mn of the new ro
22920 77 20 69 73 20 70 6f 70 75 6c 61 74 65 64 20 77  w is populated w
22930 69 74 68 20 69 74 73 20 0a 5b 64 65 66 61 75 6c  ith its .[defaul
22940 74 20 76 61 6c 75 65 5d 2c 20 6f 72 20 77 69 74  t value], or wit
22950 68 20 61 20 4e 55 4c 4c 20 69 66 20 6e 6f 20 64  h a NULL if no d
22960 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
22970 73 70 65 63 69 66 69 65 64 20 0a 61 73 20 70 61  specified .as pa
22980 72 74 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  rt of the column
22990 20 64 65 66 69 6e 69 74 69 6f 6e 20 69 6e 20 74   definition in t
229a0 68 65 20 5b 43 52 45 41 54 45 20 54 41 42 4c 45  he [CREATE TABLE
229b0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 2f  ] statement...</
229c0 6f 6c 3e 0a 0a 3c 70 3e 0a 5e 54 68 65 20 69 6e  ol>..<p>.^The in
229d0 69 74 69 61 6c 20 22 49 4e 53 45 52 54 22 20 6b  itial "INSERT" k
229e0 65 79 77 6f 72 64 20 63 61 6e 20 62 65 20 72 65  eyword can be re
229f0 70 6c 61 63 65 64 20 62 79 0a 22 52 45 50 4c 41  placed by."REPLA
22a00 43 45 22 20 6f 72 20 22 49 4e 53 45 52 54 20 4f  CE" or "INSERT O
22a10 52 20 3c 69 3e 61 63 74 69 6f 6e 3c 2f 69 3e 22  R <i>action</i>"
22a20 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
22a30 6c 74 65 72 6e 61 74 69 76 65 0a 63 6f 6e 73 74  lternative.const
22a40 72 61 69 6e 74 20 5b 4f 4e 20 43 4f 4e 46 4c 49  raint [ON CONFLI
22a50 43 54 7c 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  CT|conflict reso
22a60 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d  lution algorithm
22a70 5d 20 74 6f 20 75 73 65 20 64 75 72 69 6e 67 20  ] to use during 
22a80 0a 74 68 61 74 20 6f 6e 65 20 49 4e 53 45 52 54  .that one INSERT
22a90 20 63 6f 6d 6d 61 6e 64 2e 0a 46 6f 72 20 63 6f   command..For co
22aa0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
22ab0 20 4d 79 53 51 4c 2c 20 5e 74 68 65 20 70 61 72   MySQL, ^the par
22ac0 73 65 72 20 61 6c 6c 6f 77 73 20 74 68 65 20 75  ser allows the u
22ad0 73 65 20 6f 66 20 74 68 65 0a 73 69 6e 67 6c 65  se of the.single
22ae0 20 6b 65 79 77 6f 72 64 20 3c 61 20 68 72 65 66   keyword <a href
22af0 3d 22 6c 61 6e 67 5f 72 65 70 6c 61 63 65 2e 68  ="lang_replace.h
22b00 74 6d 6c 22 3e 52 45 50 4c 41 43 45 3c 2f 61 3e  tml">REPLACE</a>
22b10 20 61 73 20 61 6e 20 0a 61 6c 69 61 73 20 66 6f   as an .alias fo
22b20 72 20 22 49 4e 53 45 52 54 20 4f 52 20 52 45 50  r "INSERT OR REP
22b30 4c 41 43 45 22 2e 0a 0a 3c 70 3e 5e 28 54 68 65  LACE"...<p>^(The
22b40 20 6f 70 74 69 6f 6e 61 6c 20 22 3c 69 3e 73 63   optional "<i>sc
22b50 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69 3e 3c 62 3e  hema-name</i><b>
22b60 2e 3c 2f 62 3e 22 20 70 72 65 66 69 78 20 6f 6e  .</b>" prefix on
22b70 20 74 68 65 20 0a 3c 79 79 74 65 72 6d 3e 74 61   the .<yyterm>ta
22b80 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  ble-name</yyterm
22b90 3e 0a 69 73 20 73 75 70 70 6f 72 74 65 64 20 66  >.is supported f
22ba0 6f 72 20 74 6f 70 2d 6c 65 76 65 6c 20 49 4e 53  or top-level INS
22bb0 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ERT statements o
22bc0 6e 6c 79 2e 29 5e 20 20 5e 54 68 65 20 74 61 62  nly.)^  ^The tab
22bd0 6c 65 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 0a  le name must be.
22be0 75 6e 71 75 61 6c 69 66 69 65 64 20 66 6f 72 20  unqualified for 
22bf0 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74  INSERT statement
22c00 73 20 74 68 61 74 20 6f 63 63 75 72 20 77 69 74  s that occur wit
22c10 68 69 6e 20 5b 43 52 45 41 54 45 20 54 52 49 47  hin [CREATE TRIG
22c20 47 45 52 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GER] statements.
22c30 0a 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 74 68 65  .^Similarly, the
22c40 20 22 44 45 46 41 55 4c 54 20 56 41 4c 55 45 53   "DEFAULT VALUES
22c50 22 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 49 4e  " form of the IN
22c60 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20 69  SERT statement i
22c70 73 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 0a  s supported for.
22c80 74 6f 70 2d 6c 65 76 65 6c 20 49 4e 53 45 52 54  top-level INSERT
22c90 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 6c 79   statements only
22ca0 20 61 6e 64 20 6e 6f 74 20 66 6f 72 20 49 4e 53   and not for INS
22cb0 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73 20 77  ERT statements w
22cc0 69 74 68 69 6e 0a 74 72 69 67 67 65 72 73 2e 0a  ithin.triggers..
22cd0 3c 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  <p>..<tcl>.#####
22ce0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
22cf0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
22d00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
22d10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
22d20 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
22d30 6e 20 7b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63  n {ON CONFLICT c
22d40 6c 61 75 73 65 7d 20 63 6f 6e 66 6c 69 63 74 20  lause} conflict 
22d50 7b 7b 63 6f 6e 66 6c 69 63 74 20 63 6c 61 75 73  {{conflict claus
22d60 65 7d 20 7b 4f 4e 20 43 4f 4e 46 4c 49 43 54 7d  e} {ON CONFLICT}
22d70 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
22d80 6c 65 44 69 61 67 72 61 6d 20 63 6f 6e 66 6c 69  leDiagram confli
22d90 63 74 2d 63 6c 61 75 73 65 0a 3c 2f 74 63 6c 3e  ct-clause.</tcl>
22da0 0a 0a 3c 70 3e 54 68 65 20 4f 4e 20 43 4f 4e 46  ..<p>The ON CONF
22db0 4c 49 43 54 20 63 6c 61 75 73 65 20 69 73 20 6e  LICT clause is n
22dc0 6f 74 20 61 20 73 65 70 61 72 61 74 65 20 53 51  ot a separate SQ
22dd0 4c 20 63 6f 6d 6d 61 6e 64 2e 20 20 49 74 20 69  L command.  It i
22de0 73 20 61 0a 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  s a.non-standard
22df0 20 63 6c 61 75 73 65 20 74 68 61 74 20 63 61 6e   clause that can
22e00 20 61 70 70 65 61 72 20 69 6e 20 6d 61 6e 79 20   appear in many 
22e10 6f 74 68 65 72 20 53 51 4c 20 63 6f 6d 6d 61 6e  other SQL comman
22e20 64 73 2e 0a 49 74 20 69 73 20 67 69 76 65 6e 20  ds..It is given 
22e30 69 74 73 20 6f 77 6e 20 73 65 63 74 69 6f 6e 20  its own section 
22e40 69 6e 20 74 68 69 73 20 64 6f 63 75 6d 65 6e 74  in this document
22e50 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 6e   because it is n
22e60 6f 74 0a 70 61 72 74 20 6f 66 20 73 74 61 6e 64  ot.part of stand
22e70 61 72 64 20 53 51 4c 20 61 6e 64 20 74 68 65 72  ard SQL and ther
22e80 65 66 6f 72 65 20 6d 69 67 68 74 20 6e 6f 74 20  efore might not 
22e90 62 65 20 66 61 6d 69 6c 69 61 72 2e 3c 2f 70 3e  be familiar.</p>
22ea0 0a 0a 3c 70 3e 5e 54 68 65 20 73 79 6e 74 61 78  ..<p>^The syntax
22eb0 20 66 6f 72 20 74 68 65 20 4f 4e 20 43 4f 4e 46   for the ON CONF
22ec0 4c 49 43 54 20 63 6c 61 75 73 65 20 69 73 20 61  LICT clause is a
22ed0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 66 6f  s shown above fo
22ee0 72 0a 74 68 65 20 43 52 45 41 54 45 20 54 41 42  r.the CREATE TAB
22ef0 4c 45 20 63 6f 6d 6d 61 6e 64 2e 20 20 5e 46 6f  LE command.  ^Fo
22f00 72 20 74 68 65 20 49 4e 53 45 52 54 20 61 6e 64  r the INSERT and
22f10 0a 55 50 44 41 54 45 20 63 6f 6d 6d 61 6e 64 73  .UPDATE commands
22f20 2c 20 74 68 65 20 6b 65 79 77 6f 72 64 73 20 22  , the keywords "
22f30 4f 4e 20 43 4f 4e 46 4c 49 43 54 22 20 61 72 65  ON CONFLICT" are
22f40 20 72 65 70 6c 61 63 65 64 20 62 79 20 22 4f 52   replaced by "OR
22f50 22 20 73 6f 20 74 68 61 74 0a 74 68 65 20 73 79  " so that.the sy
22f60 6e 74 61 78 20 72 65 61 64 73 20 6d 6f 72 65 20  ntax reads more 
22f70 6e 61 74 75 72 61 6c 6c 79 2e 20 20 46 6f 72 20  naturally.  For 
22f80 65 78 61 6d 70 6c 65 2c 20 69 6e 73 74 65 61 64  example, instead
22f90 20 6f 66 0a 22 49 4e 53 45 52 54 20 4f 4e 20 43   of."INSERT ON C
22fa0 4f 4e 46 4c 49 43 54 20 49 47 4e 4f 52 45 22 20  ONFLICT IGNORE" 
22fb0 77 65 20 68 61 76 65 20 22 49 4e 53 45 52 54 20  we have "INSERT 
22fc0 4f 52 20 49 47 4e 4f 52 45 22 2e 0a 54 68 65 20  OR IGNORE"..The 
22fd0 6b 65 79 77 6f 72 64 73 20 63 68 61 6e 67 65 20  keywords change 
22fe0 62 75 74 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  but the meaning 
22ff0 6f 66 20 74 68 65 20 63 6c 61 75 73 65 20 69 73  of the clause is
23000 20 74 68 65 20 73 61 6d 65 0a 65 69 74 68 65 72   the same.either
23010 20 77 61 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68   way.</p>..<p>Th
23020 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63 6c  e ON CONFLICT cl
23030 61 75 73 65 20 61 70 70 6c 69 65 73 20 74 6f 20  ause applies to 
23040 5b 55 4e 49 51 55 45 5d 2c 20 5b 4e 4f 54 20 4e  [UNIQUE], [NOT N
23050 55 4c 4c 5d 2c 0a 5b 43 48 45 43 4b 5d 2c 20 61  ULL],.[CHECK], a
23060 6e 64 20 5b 50 52 49 4d 41 52 59 20 4b 45 59 5d  nd [PRIMARY KEY]
23070 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 0a 54 68   constraints..Th
23080 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 61 6c  e ON CONFLICT al
23090 67 6f 72 69 74 68 6d 20 64 6f 65 73 20 6e 6f 74  gorithm does not
230a0 0a 61 70 70 6c 79 20 74 6f 20 5b 46 4f 52 45 49  .apply to [FOREI
230b0 47 4e 20 4b 45 59 20 63 6f 6e 73 74 72 61 69 6e  GN KEY constrain
230c0 74 73 5d 2e 0a 54 68 65 72 65 20 61 72 65 20 66  ts]..There are f
230d0 69 76 65 20 63 6f 6e 66 6c 69 63 74 20 72 65 73  ive conflict res
230e0 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
230f0 6d 20 63 68 6f 69 63 65 73 3a 0a 52 4f 4c 4c 42  m choices:.ROLLB
23100 41 43 4b 2c 20 41 42 4f 52 54 2c 20 46 41 49 4c  ACK, ABORT, FAIL
23110 2c 20 49 47 4e 4f 52 45 2c 20 61 6e 64 20 52 45  , IGNORE, and RE
23120 50 4c 41 43 45 2e 0a 5e 54 68 65 20 64 65 66 61  PLACE..^The defa
23130 75 6c 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73  ult conflict res
23140 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
23150 6d 20 69 73 20 41 42 4f 52 54 2e 20 20 54 68 69  m is ABORT.  Thi
23160 73 0a 69 73 20 77 68 61 74 20 74 68 65 79 20 6d  s.is what they m
23170 65 61 6e 3a 3c 2f 70 3e 0a 0a 3c 64 6c 3e 0a 3c  ean:</p>..<dl>.<
23180 64 74 3e 3c 62 3e 52 4f 4c 4c 42 41 43 4b 3c 2f  dt><b>ROLLBACK</
23190 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20  b></dt>.<dd><p> 
231a0 5e 57 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61  ^When an applica
231b0 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  ble constraint v
231c0 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c  iolation occurs,
231d0 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 0a 72 65   the ROLLBACK.re
231e0 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74  solution algorit
231f0 68 6d 20 61 62 6f 72 74 73 20 74 68 65 20 63 75  hm aborts the cu
23200 72 72 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  rrent SQL statem
23210 65 6e 74 20 77 69 74 68 0a 61 6e 20 53 51 4c 49  ent with.an SQLI
23220 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 65 72  TE_CONSTRAINT er
23230 72 6f 72 20 61 6e 64 20 72 6f 6c 6c 73 20 62 61  ror and rolls ba
23240 63 6b 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  ck the current t
23250 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e 49 66 20  ransaction..^If 
23260 6e 6f 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  no transaction i
23270 73 0a 61 63 74 69 76 65 20 28 6f 74 68 65 72 20  s.active (other 
23280 74 68 61 6e 20 74 68 65 20 69 6d 70 6c 69 65 64  than the implied
23290 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 61   transaction tha
232a0 74 20 69 73 20 63 72 65 61 74 65 64 20 6f 6e 20  t is created on 
232b0 65 76 65 72 79 0a 63 6f 6d 6d 61 6e 64 29 20 74  every.command) t
232c0 68 65 6e 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b  hen the ROLLBACK
232d0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f   resolution algo
232e0 72 69 74 68 6d 20 77 6f 72 6b 73 20 74 68 65 20  rithm works the 
232f0 73 61 6d 65 20 61 73 20 74 68 65 0a 41 42 4f 52  same as the.ABOR
23300 54 20 61 6c 67 6f 72 69 74 68 6d 2e 3c 2f 70 3e  T algorithm.</p>
23310 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 41 42  </dd>..<dt><b>AB
23320 4f 52 54 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64  ORT</b></dt>.<dd
23330 3e 3c 70 3e 20 5e 57 68 65 6e 20 61 6e 20 61 70  ><p> ^When an ap
23340 70 6c 69 63 61 62 6c 65 20 63 6f 6e 73 74 72 61  plicable constra
23350 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63  int violation oc
23360 63 75 72 73 2c 20 74 68 65 20 41 42 4f 52 54 0a  curs, the ABORT.
23370 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72  resolution algor
23380 69 74 68 6d 20 61 62 6f 72 74 73 20 74 68 65 20  ithm aborts the 
23390 63 75 72 72 65 6e 74 20 53 51 4c 20 73 74 61 74  current SQL stat
233a0 65 6d 65 6e 74 0a 77 69 74 68 20 61 6e 20 53 51  ement.with an SQ
233b0 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
233c0 65 72 72 6f 72 20 61 6e 64 20 62 61 63 6b 73 20  error and backs 
233d0 6f 75 74 20 61 6e 79 20 63 68 61 6e 67 65 73 0a  out any changes.
233e0 6d 61 64 65 20 62 79 20 74 68 65 20 63 75 72 72  made by the curr
233f0 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
23400 74 3b 20 62 75 74 20 63 68 61 6e 67 65 73 20 63  t; but changes c
23410 61 75 73 65 64 0a 62 79 20 70 72 69 6f 72 20 53  aused.by prior S
23420 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69  QL statements wi
23430 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
23440 61 6e 73 61 63 74 69 6f 6e 20 61 72 65 20 70 72  ansaction are pr
23450 65 73 65 72 76 65 64 20 61 6e 64 20 74 68 65 0a  eserved and the.
23460 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 65 6d 61  transaction rema
23470 69 6e 73 20 61 63 74 69 76 65 2e 0a 54 68 69 73  ins active..This
23480 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
23490 62 65 68 61 76 69 6f 72 20 61 6e 64 20 74 68 65  behavior and the
234a0 20 62 65 68 61 76 69 6f 72 20 73 70 65 63 69 66   behavior specif
234b0 69 65 64 20 62 79 20 74 68 65 20 53 51 4c 0a 73  ied by the SQL.s
234c0 74 61 6e 64 61 72 64 2e 3c 2f 70 3e 3c 2f 64 64  tandard.</p></dd
234d0 3e 0a 0a 3c 64 74 3e 3c 62 3e 46 41 49 4c 3c 2f  >..<dt><b>FAIL</
234e0 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20  b></dt>.<dd><p> 
234f0 5e 57 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61  ^When an applica
23500 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  ble constraint v
23510 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c  iolation occurs,
23520 20 74 68 65 20 46 41 49 4c 0a 72 65 73 6f 6c 75   the FAIL.resolu
23530 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 61  tion algorithm a
23540 62 6f 72 74 73 20 74 68 65 20 63 75 72 72 65 6e  borts the curren
23550 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
23560 77 69 74 68 20 61 6e 0a 53 51 4c 49 54 45 5f 43  with an.SQLITE_C
23570 4f 4e 53 54 52 41 49 4e 54 20 65 72 72 6f 72 2e  ONSTRAINT error.
23580 20 20 5e 42 75 74 20 74 68 65 20 46 41 49 4c 20    ^But the FAIL 
23590 72 65 73 6f 6c 75 74 69 6f 6e 20 64 6f 65 73 20  resolution does 
235a0 6e 6f 74 0a 62 61 63 6b 20 6f 75 74 20 70 72 69  not.back out pri
235b0 6f 72 20 63 68 61 6e 67 65 73 20 6f 66 20 74 68  or changes of th
235c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
235d0 74 68 61 74 20 66 61 69 6c 65 64 20 6e 6f 72 20  that failed nor 
235e0 64 6f 65 73 0a 69 74 20 65 6e 64 20 74 68 65 20  does.it end the 
235f0 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e 46 6f  transaction..^Fo
23600 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
23610 20 55 50 44 41 54 45 0a 73 74 61 74 65 6d 65 6e   UPDATE.statemen
23620 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 20  t encountered a 
23630 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
23640 74 69 6f 6e 20 6f 6e 20 74 68 65 20 31 30 30 74  tion on the 100t
23650 68 20 72 6f 77 20 74 68 61 74 0a 69 74 20 61 74  h row that.it at
23660 74 65 6d 70 74 73 20 74 6f 20 75 70 64 61 74 65  tempts to update
23670 2c 20 74 68 65 6e 20 74 68 65 20 66 69 72 73 74  , then the first
23680 20 39 39 20 72 6f 77 20 63 68 61 6e 67 65 73 20   99 row changes 
23690 61 72 65 20 70 72 65 73 65 72 76 65 64 0a 62 75  are preserved.bu
236a0 74 20 63 68 61 6e 67 65 73 20 74 6f 20 72 6f 77  t changes to row
236b0 73 20 31 30 30 20 61 6e 64 20 62 65 79 6f 6e 64  s 100 and beyond
236c0 20 6e 65 76 65 72 20 6f 63 63 75 72 2e 3c 2f 70   never occur.</p
236d0 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 49  ></dd>..<dt><b>I
236e0 47 4e 4f 52 45 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c  GNORE</b></dt>.<
236f0 64 64 3e 3c 70 3e 20 5e 57 68 65 6e 20 61 6e 20  dd><p> ^When an 
23700 61 70 70 6c 69 63 61 62 6c 65 20 63 6f 6e 73 74  applicable const
23710 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
23720 6f 63 63 75 72 73 2c 20 0a 74 68 65 20 49 47 4e  occurs, .the IGN
23730 4f 52 45 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  ORE resolution a
23740 6c 67 6f 72 69 74 68 6d 20 73 6b 69 70 73 20 74  lgorithm skips t
23750 68 65 20 6f 6e 65 20 72 6f 77 20 74 68 61 74 20  he one row that 
23760 63 6f 6e 74 61 69 6e 73 0a 74 68 65 20 63 6f 6e  contains.the con
23770 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
23780 6e 20 61 6e 64 20 63 6f 6e 74 69 6e 75 65 73 20  n and continues 
23790 70 72 6f 63 65 73 73 69 6e 67 20 73 75 62 73 65  processing subse
237a0 71 75 65 6e 74 20 72 6f 77 73 0a 6f 66 20 74 68  quent rows.of th
237b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
237c0 61 73 20 69 66 20 6e 6f 74 68 69 6e 67 20 77 65  as if nothing we
237d0 6e 74 20 77 72 6f 6e 67 2e 0a 4f 74 68 65 72 20  nt wrong..Other 
237e0 72 6f 77 73 20 62 65 66 6f 72 65 20 61 6e 64 20  rows before and 
237f0 61 66 74 65 72 20 74 68 65 20 72 6f 77 20 74 68  after the row th
23800 61 74 0a 63 6f 6e 74 61 69 6e 65 64 20 74 68 65  at.contained the
23810 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
23820 61 74 69 6f 6e 20 61 72 65 20 69 6e 73 65 72 74  ation are insert
23830 65 64 20 6f 72 20 75 70 64 61 74 65 64 0a 6e 6f  ed or updated.no
23840 72 6d 61 6c 6c 79 2e 20 5e 4e 6f 20 65 72 72 6f  rmally. ^No erro
23850 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 77 68  r is returned wh
23860 65 6e 20 74 68 65 20 49 47 4e 4f 52 45 20 63 6f  en the IGNORE co
23870 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
23880 6e 0a 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 75  n.algorithm is u
23890 73 65 64 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c  sed.</p></dd>..<
238a0 64 74 3e 3c 62 3e 52 45 50 4c 41 43 45 3c 2f 62  dt><b>REPLACE</b
238b0 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20 5e  ></dt>.<dd><p> ^
238c0 57 68 65 6e 20 61 20 5b 55 4e 49 51 55 45 5d 20  When a [UNIQUE] 
238d0 6f 72 20 5b 50 52 49 4d 41 52 59 20 4b 45 59 5d  or [PRIMARY KEY]
238e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
238f0 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20 0a 74  ation occurs, .t
23900 68 65 20 52 45 50 4c 41 43 45 20 61 6c 67 6f 72  he REPLACE algor
23910 69 74 68 6d 0a 64 65 6c 65 74 65 73 20 70 72 65  ithm.deletes pre
23920 2d 65 78 69 73 74 69 6e 67 20 72 6f 77 73 20 74  -existing rows t
23930 68 61 74 20 61 72 65 20 63 61 75 73 69 6e 67 20  hat are causing 
23940 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  the constraint v
23950 69 6f 6c 61 74 69 6f 6e 0a 70 72 69 6f 72 20 74  iolation.prior t
23960 6f 20 69 6e 73 65 72 74 69 6e 67 20 6f 72 20 75  o inserting or u
23970 70 64 61 74 69 6e 67 20 74 68 65 20 63 75 72 72  pdating the curr
23980 65 6e 74 20 72 6f 77 20 61 6e 64 20 74 68 65 20  ent row and the 
23990 63 6f 6d 6d 61 6e 64 20 63 6f 6e 74 69 6e 75 65  command continue
239a0 73 20 0a 65 78 65 63 75 74 69 6e 67 20 6e 6f 72  s .executing nor
239b0 6d 61 6c 6c 79 2e 0a 5e 49 66 20 61 20 5b 4e 4f  mally..^If a [NO
239c0 54 20 4e 55 4c 4c 5d 20 63 6f 6e 73 74 72 61 69  T NULL] constrai
239d0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63  nt violation occ
239e0 75 72 73 2c 20 74 68 65 20 52 45 50 4c 41 43 45  urs, the REPLACE
239f0 20 63 6f 6e 66 6c 69 63 74 0a 72 65 73 6f 6c 75   conflict.resolu
23a00 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
23a10 65 20 4e 55 4c 4c 20 76 61 6c 75 65 20 77 69 74  e NULL value wit
23a20 68 0a 74 68 65 20 64 65 66 61 75 6c 74 20 76 61  h.the default va
23a30 6c 75 65 20 66 6f 72 20 74 68 61 74 20 63 6f 6c  lue for that col
23a40 75 6d 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  umn, or if the c
23a50 6f 6c 75 6d 6e 20 68 61 73 20 6e 6f 20 64 65 66  olumn has no def
23a60 61 75 6c 74 0a 76 61 6c 75 65 2c 20 74 68 65 6e  ault.value, then
23a70 20 74 68 65 20 41 42 4f 52 54 20 61 6c 67 6f 72   the ABORT algor
23a80 69 74 68 6d 20 69 73 20 75 73 65 64 2e 0a 5e 49  ithm is used..^I
23a90 66 20 61 20 5b 43 48 45 43 4b 5d 20 63 6f 6e 73  f a [CHECK] cons
23aa0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
23ab0 20 6f 63 63 75 72 73 2c 20 74 68 65 20 52 45 50   occurs, the REP
23ac0 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 20 72 65  LACE conflict re
23ad0 73 6f 6c 75 74 69 6f 6e 0a 61 6c 67 6f 72 69 74  solution.algorit
23ae0 68 6d 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20  hm always works 
23af0 6c 69 6b 65 20 41 42 4f 52 54 2e 3c 2f 70 3e 0a  like ABORT.</p>.
23b00 0a 3c 70 3e 5e 57 68 65 6e 20 74 68 65 20 52 45  .<p>^When the RE
23b10 50 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 20 72  PLACE conflict r
23b20 65 73 6f 6c 75 74 69 6f 6e 20 73 74 72 61 74 65  esolution strate
23b30 67 79 20 64 65 6c 65 74 65 73 20 72 6f 77 73 20  gy deletes rows 
23b40 69 6e 20 6f 72 64 65 72 20 74 6f 0a 73 61 74 69  in order to.sati
23b50 73 66 79 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  sfy a constraint
23b60 2c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  , [CREATE TRIGGE
23b70 52 20 7c 20 64 65 6c 65 74 65 20 74 72 69 67 67  R | delete trigg
23b80 65 72 73 5d 20 66 69 72 65 20 69 66 20 61 6e 64  ers] fire if and
23b90 20 6f 6e 6c 79 20 69 66 0a 5b 72 65 63 75 72 73   only if.[recurs
23ba0 69 76 65 5f 74 72 69 67 67 65 72 73 20 70 72 61  ive_triggers pra
23bb0 67 6d 61 20 7c 20 72 65 63 75 72 73 69 76 65 20  gma | recursive 
23bc0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 65 6e  triggers] are en
23bd0 61 62 6c 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  abled.</p>..<p>^
23be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  The [sqlite3_upd
23bf0 61 74 65 5f 68 6f 6f 6b 20 7c 20 75 70 64 61 74  ate_hook | updat
23c00 65 20 68 6f 6f 6b 5d 20 69 73 20 6e 6f 74 20 69  e hook] is not i
23c10 6e 76 6f 6b 65 64 20 66 6f 72 20 72 6f 77 73 20  nvoked for rows 
23c20 74 68 61 74 0a 61 72 65 20 64 65 6c 65 74 65 64  that.are deleted
23c30 20 62 79 20 74 68 65 20 52 45 50 4c 41 43 45 20   by the REPLACE 
23c40 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
23c50 69 6f 6e 20 73 74 72 61 74 65 67 79 2e 20 20 5e  ion strategy.  ^
23c60 4e 6f 72 20 64 6f 65 73 0a 52 45 50 4c 41 43 45  Nor does.REPLACE
23c70 20 69 6e 63 72 65 6d 65 6e 74 20 74 68 65 20 5b   increment the [
23c80 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 20  sqlite3_changes 
23c90 7c 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 65 72  | change counter
23ca0 5d 2e 0a 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ]..The exception
23cb0 61 6c 20 62 65 68 61 76 69 6f 72 73 20 64 65 66  al behaviors def
23cc0 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
23cd0 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
23ce0 6e 67 65 20 0a 69 6e 20 61 20 66 75 74 75 72 65  nge .in a future
23cf0 20 72 65 6c 65 61 73 65 2e 3c 2f 70 3e 0a 3c 2f   release.</p>.</
23d00 64 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 61 6c 67  dl>..<p>^The alg
23d10 6f 72 69 74 68 6d 20 73 70 65 63 69 66 69 65 64  orithm specified
23d20 20 69 6e 20 74 68 65 20 4f 52 20 63 6c 61 75 73   in the OR claus
23d30 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  e of an INSERT o
23d40 72 20 55 50 44 41 54 45 0a 6f 76 65 72 72 69 64  r UPDATE.overrid
23d50 65 73 20 61 6e 79 20 61 6c 67 6f 72 69 74 68 6d  es any algorithm
23d60 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 61 20   specified in a 
23d70 43 52 45 41 54 45 20 54 41 42 4c 45 2e 0a 5e 49  CREATE TABLE..^I
23d80 66 20 6e 6f 20 61 6c 67 6f 72 69 74 68 6d 20 69  f no algorithm i
23d90 73 20 73 70 65 63 69 66 69 65 64 20 61 6e 79 77  s specified anyw
23da0 68 65 72 65 2c 20 74 68 65 20 41 42 4f 52 54 20  here, the ABORT 
23db0 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 75 73 65  algorithm is use
23dc0 64 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23  d.</p>..<tcl>.##
23dd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
23de0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
23df0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
23e00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
23e10 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63  ############.Sec
23e20 74 69 6f 6e 20 52 45 49 4e 44 45 58 20 72 65 69  tion REINDEX rei
23e30 6e 64 65 78 20 52 45 49 4e 44 45 58 0a 0a 52 65  ndex REINDEX..Re
23e40 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
23e50 67 72 61 6d 20 72 65 69 6e 64 65 78 2d 73 74 6d  gram reindex-stm
23e60 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68  t.</tcl>..<p>^Th
23e70 65 20 52 45 49 4e 44 45 58 20 63 6f 6d 6d 61 6e  e REINDEX comman
23e80 64 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c  d is used to del
23e90 65 74 65 20 61 6e 64 20 72 65 63 72 65 61 74 65  ete and recreate
23ea0 20 69 6e 64 69 63 65 73 20 66 72 6f 6d 20 73 63   indices from sc
23eb0 72 61 74 63 68 2e 0a 54 68 69 73 20 69 73 20 75  ratch..This is u
23ec0 73 65 66 75 6c 20 77 68 65 6e 20 74 68 65 20 64  seful when the d
23ed0 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 61 20 63  efinition of a c
23ee0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
23ef0 65 20 68 61 73 20 63 68 61 6e 67 65 64 2e 0a 3c  e has changed..<
23f00 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20  /p>..<p>^If the 
23f10 52 45 49 4e 44 45 58 20 6b 65 79 77 6f 72 64 20  REINDEX keyword 
23f20 69 73 20 6e 6f 74 20 66 6f 6c 6c 6f 77 65 64 20  is not followed 
23f30 62 79 20 61 20 63 6f 6c 6c 61 74 69 6f 6e 2d 73  by a collation-s
23f40 65 71 75 65 6e 63 65 20 6f 72 20 64 61 74 61 62  equence or datab
23f50 61 73 65 20 0a 6f 62 6a 65 63 74 20 69 64 65 6e  ase .object iden
23f60 74 69 66 69 65 72 2c 20 74 68 65 6e 20 61 6c 6c  tifier, then all
23f70 20 69 6e 64 69 63 65 73 20 69 6e 20 61 6c 6c 20   indices in all 
23f80 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
23f90 65 73 20 61 72 65 20 72 65 62 75 69 6c 74 2e 0a  es are rebuilt..
23fa0 0a 3c 70 3e 5e 49 66 20 74 68 65 20 52 45 49 4e  .<p>^If the REIN
23fb0 44 45 58 20 6b 65 79 77 6f 72 64 20 69 73 20 66  DEX keyword is f
23fc0 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 63 6f 6c  ollowed by a col
23fd0 6c 61 74 69 6f 6e 2d 73 65 71 75 65 6e 63 65 20  lation-sequence 
23fe0 6e 61 6d 65 2c 20 74 68 65 6e 0a 61 6c 6c 20 69  name, then.all i
23ff0 6e 64 69 63 65 73 20 69 6e 20 61 6c 6c 20 61 74  ndices in all at
24000 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
24010 20 74 68 61 74 20 75 73 65 20 74 68 65 20 6e 61   that use the na
24020 6d 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  med collation se
24030 71 75 65 6e 63 65 73 0a 61 72 65 20 72 65 63 72  quences.are recr
24040 65 61 74 65 64 2e 20 0a 0a 3c 70 3e 5e 4f 72 2c  eated. ..<p>^Or,
24050 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
24060 20 61 74 74 61 63 68 65 64 20 74 6f 20 74 68 65   attached to the
24070 20 52 45 49 4e 44 45 58 20 69 64 65 6e 74 69 66   REINDEX identif
24080 69 65 73 20 61 20 73 70 65 63 69 66 69 63 20 0a  ies a specific .
24090 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2c 20  database table, 
240a0 74 68 65 6e 20 61 6c 6c 20 69 6e 64 69 63 65 73  then all indices
240b0 20 61 74 74 61 63 68 65 64 20 74 6f 20 74 68 65   attached to the
240c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
240d0 61 72 65 20 72 65 62 75 69 6c 74 2e 20 0a 5e 49  are rebuilt. .^I
240e0 66 20 69 74 20 69 64 65 6e 74 69 66 69 65 73 20  f it identifies 
240f0 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62  a specific datab
24100 61 73 65 20 69 6e 64 65 78 2c 20 74 68 65 6e 20  ase index, then 
24110 6a 75 73 74 20 74 68 61 74 20 69 6e 64 65 78 20  just that index 
24120 69 73 20 72 65 63 72 65 61 74 65 64 2e 0a 0a 3c  is recreated...<
24130 70 3e 5e 46 6f 72 20 61 20 63 6f 6d 6d 61 6e 64  p>^For a command
24140 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 52 45   of the form "RE
24150 49 4e 44 45 58 20 3c 69 3e 6e 61 6d 65 3c 2f 69  INDEX <i>name</i
24160 3e 22 2c 20 61 20 6d 61 74 63 68 0a 61 67 61 69  >", a match.agai
24170 6e 73 74 20 3c 79 79 74 65 72 6d 3e 63 6f 6c 6c  nst <yyterm>coll
24180 61 74 69 6f 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65  ation-name</yyte
24190 72 6d 3e 20 74 61 6b 65 73 20 70 72 65 63 65 64  rm> takes preced
241a0 65 6e 63 65 20 6f 76 65 72 20 61 20 6d 61 74 63  ence over a matc
241b0 68 0a 61 67 61 69 6e 73 74 20 3c 79 79 74 65 72  h.against <yyter
241c0 6d 3e 69 6e 64 65 78 2d 6e 61 6d 65 3c 2f 79 79  m>index-name</yy
241d0 74 65 72 6d 3e 20 6f 72 20 3c 79 79 74 65 72 6d  term> or <yyterm
241e0 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74  >table-name</yyt
241f0 65 72 6d 3e 2e 0a 54 68 69 73 20 61 6d 62 69 67  erm>..This ambig
24200 75 69 74 79 20 69 6e 20 74 68 65 20 73 79 6e 74  uity in the synt
24210 61 78 20 6d 61 79 20 62 65 20 61 76 6f 69 64 65  ax may be avoide
24220 64 20 62 79 20 61 6c 77 61 79 73 20 73 70 65 63  d by always spec
24230 69 66 79 69 6e 67 20 61 0a 3c 79 79 74 65 72 6d  ifying a.<yyterm
24240 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79  >schema-name</yy
24250 74 65 72 6d 3e 20 77 68 65 6e 20 72 65 69 6e 64  term> when reind
24260 65 78 69 6e 67 20 61 20 73 70 65 63 69 66 69 63  exing a specific
24270 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e   table or index.
24280 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
24290 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
242a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
242b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
242c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
242d0 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
242e0 52 45 50 4c 41 43 45 20 72 65 70 6c 61 63 65 20  REPLACE replace 
242f0 52 45 50 4c 41 43 45 0a 0a 3c 2f 74 63 6c 3e 0a  REPLACE..</tcl>.
24300 0a 3c 70 3e 5e 54 68 65 20 52 45 50 4c 41 43 45  .<p>^The REPLACE
24310 20 63 6f 6d 6d 61 6e 64 20 69 73 20 61 6e 20 61   command is an a
24320 6c 69 61 73 20 66 6f 72 20 74 68 65 20 22 5b 4f  lias for the "[O
24330 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 49 4e 53  N CONFLICT | INS
24340 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 5d 22  ERT OR REPLACE]"
24350 0a 76 61 72 69 61 6e 74 20 6f 66 20 74 68 65 20  .variant of the 
24360 5b 49 4e 53 45 52 54 5d 20 63 6f 6d 6d 61 6e 64  [INSERT] command
24370 2e 20 20 0a 54 68 69 73 20 61 6c 69 61 73 20 69  .  .This alias i
24380 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 63  s provided for c
24390 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 74 68  ompatibility oth
243a0 65 72 20 53 51 4c 20 64 61 74 61 62 61 73 65 20  er SQL database 
243b0 65 6e 67 69 6e 65 73 2e 20 20 53 65 65 20 74 68  engines.  See th
243c0 65 20 0a 5b 49 4e 53 45 52 54 5d 20 63 6f 6d 6d  e .[INSERT] comm
243d0 61 6e 64 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  and documentatio
243e0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
243f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 70   information.</p
24400 3e 20 20 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  >  ..<tcl>.#####
24410 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24420 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24430 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24440 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24450 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
24460 6f 6e 20 7b 57 49 54 48 20 63 6c 61 75 73 65 7d  on {WITH clause}
24470 20 77 69 74 68 20 7b 7b 63 6f 6d 6d 6f 6e 20 74   with {{common t
24480 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73  able expressions
24490 7d 20 57 49 54 48 7d 0a 0a 52 65 63 75 72 73 69  } WITH}..Recursi
244a0 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
244b0 77 69 74 68 2d 63 6c 61 75 73 65 0a 3c 2f 74 63  with-clause.</tc
244c0 6c 3e 0a 0a 3c 70 3e 43 6f 6d 6d 6f 6e 20 54 61  l>..<p>Common Ta
244d0 62 6c 65 20 45 78 70 72 65 73 73 69 6f 6e 73 20  ble Expressions 
244e0 6f 72 20 43 54 45 73 20 61 63 74 20 6c 69 6b 65  or CTEs act like
244f0 20 74 65 6d 70 6f 72 61 72 79 20 5b 76 69 65 77   temporary [view
24500 73 5d 20 74 68 61 74 20 65 78 69 73 74 0a 6f 6e  s] that exist.on
24510 6c 79 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ly for the durat
24520 69 6f 6e 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ion of a single 
24530 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
24540 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 6b 69  There are two ki
24550 6e 64 73 20 6f 66 0a 63 6f 6d 6d 6f 6e 20 74 61  nds of.common ta
24560 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73 3a  ble expressions:
24570 20 22 6f 72 64 69 6e 61 72 79 22 20 61 6e 64 20   "ordinary" and 
24580 22 72 65 63 75 72 73 69 76 65 22 2e 20 4f 72 64  "recursive". Ord
24590 69 6e 61 72 79 20 0a 63 6f 6d 6d 6f 6e 20 74 61  inary .common ta
245a0 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20  ble expressions 
245b0 61 72 65 20 68 65 6c 70 66 75 6c 20 66 6f 72 20  are helpful for 
245c0 6d 61 6b 69 6e 67 0a 71 75 65 72 69 65 73 20 65  making.queries e
245d0 61 73 69 65 72 20 74 6f 20 75 6e 64 65 72 73 74  asier to underst
245e0 61 6e 64 20 62 79 20 66 61 63 74 6f 72 69 6e 67  and by factoring
245f0 0a 73 75 62 71 75 65 72 69 65 73 20 6f 75 74 20  .subqueries out 
24600 6f 66 20 74 68 65 20 6d 61 69 6e 20 53 51 4c 20  of the main SQL 
24610 73 74 61 74 65 6d 65 6e 74 2e 0a 52 65 63 75 72  statement..Recur
24620 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c  sive common tabl
24630 65 20 65 78 70 72 65 73 73 69 6f 6e 73 0a 70 72  e expressions.pr
24640 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 74  ovide the abilit
24650 79 20 74 6f 20 64 6f 20 68 69 65 72 61 72 63 68  y to do hierarch
24660 69 63 61 6c 20 6f 72 0a 72 65 63 75 72 73 69 76  ical or.recursiv
24670 65 20 71 75 65 72 69 65 73 20 6f 66 20 74 72 65  e queries of tre
24680 65 73 20 61 6e 64 20 67 72 61 70 68 73 2c 20 61  es and graphs, a
24690 20 63 61 70 61 62 69 6c 69 74 79 0a 74 68 61 74   capability.that
246a0 20 69 73 20 6e 6f 74 20 6f 74 68 65 72 77 69 73   is not otherwis
246b0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
246c0 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67 65 2e  he SQL language.
246d0 0a 0a 3c 70 3e 41 6c 6c 20 63 6f 6d 6d 6f 6e 20  ..<p>All common 
246e0 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e  table expression
246f0 73 20 28 6f 72 64 69 6e 61 72 79 20 61 6e 64 20  s (ordinary and 
24700 72 65 63 75 72 73 69 76 65 29 20 61 72 65 20 0a  recursive) are .
24710 63 72 65 61 74 65 64 20 62 79 20 70 72 65 70 65  created by prepe
24720 6e 64 69 6e 67 20 61 20 57 49 54 48 20 63 6c 61  nding a WITH cla
24730 75 73 65 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  use in front of 
24740 61 20 5b 53 45 4c 45 43 54 5d 2c 20 5b 49 4e 53  a [SELECT], [INS
24750 45 52 54 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 0a  ERT], [DELETE],.
24760 6f 72 20 5b 55 50 44 41 54 45 5d 20 73 74 61 74  or [UPDATE] stat
24770 65 6d 65 6e 74 2e 20 20 41 20 73 69 6e 67 6c 65  ement.  A single
24780 20 57 49 54 48 20 63 6c 61 75 73 65 20 63 61 6e   WITH clause can
24790 20 73 70 65 63 69 66 79 20 6f 6e 65 20 6f 72 20   specify one or 
247a0 6d 6f 72 65 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c  more.common tabl
247b0 65 20 65 78 70 72 65 73 73 69 6f 6e 73 2c 20 73  e expressions, s
247c0 6f 6d 65 20 6f 66 20 77 68 69 63 68 20 61 72 65  ome of which are
247d0 20 6f 72 64 69 6e 61 72 79 20 61 6e 64 20 73 6f   ordinary and so
247e0 6d 65 20 6f 66 20 77 68 69 63 68 0a 61 72 65 20  me of which.are 
247f0 72 65 63 75 72 73 69 76 65 2e 0a 0a 3c 74 63 6c  recursive...<tcl
24800 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6f 72 64  >hd_fragment ord
24810 69 6e 61 72 79 63 74 65 20 7b 6f 72 64 69 6e 61  inarycte {ordina
24820 72 79 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20  ry common table 
24830 65 78 70 72 65 73 73 69 6f 6e 73 7d 3c 2f 74 63  expressions}</tc
24840 6c 3e 0a 3c 68 33 3e 4f 72 64 69 6e 61 72 79 20  l>.<h3>Ordinary 
24850 43 6f 6d 6d 6f 6e 20 54 61 62 6c 65 20 45 78 70  Common Table Exp
24860 72 65 73 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c  ressions</h3>..<
24870 70 3e 41 6e 20 6f 72 64 69 6e 61 72 79 20 63 6f  p>An ordinary co
24880 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65  mmon table expre
24890 73 73 69 6f 6e 20 77 6f 72 6b 73 20 61 73 20 69  ssion works as i
248a0 66 20 69 74 20 77 65 72 65 20 61 20 5b 76 69 65  f it were a [vie
248b0 77 5d 20 74 68 61 74 0a 65 78 69 73 74 73 20 66  w] that.exists f
248c0 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
248d0 6f 66 20 61 20 73 69 6e 67 6c 65 20 73 74 61 74  of a single stat
248e0 65 6d 65 6e 74 2e 20 20 4f 72 64 69 6e 61 72 79  ement.  Ordinary
248f0 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 0a 65 78   common table.ex
24900 70 72 65 73 73 69 6f 6e 73 20 61 72 65 20 75 73  pressions are us
24910 65 66 75 6c 20 66 6f 72 20 66 61 63 74 6f 72 69  eful for factori
24920 6e 67 20 6f 75 74 20 73 75 62 71 75 65 72 69 65  ng out subquerie
24930 73 20 61 6e 64 20 6d 61 6b 69 6e 67 20 74 68 65  s and making the
24940 20 6f 76 65 72 61 6c 6c 0a 53 51 4c 20 73 74 61   overall.SQL sta
24950 74 65 6d 65 6e 74 20 65 61 73 69 65 72 20 74 6f  tement easier to
24960 20 72 65 61 64 20 61 6e 64 20 75 6e 64 65 72 73   read and unders
24970 74 61 6e 64 2e 0a 0a 3c 70 3e 41 20 57 49 54 48  tand...<p>A WITH
24980 20 63 6c 61 75 73 65 20 63 61 6e 20 63 6f 6e 74   clause can cont
24990 61 69 6e 20 6f 72 64 69 6e 61 72 79 20 63 6f 6d  ain ordinary com
249a0 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
249b0 73 69 6f 6e 73 20 65 76 65 6e 20 69 66 0a 69 74  sions even if.it
249c0 20 69 6e 63 6c 75 64 65 73 20 74 68 65 20 52 45   includes the RE
249d0 43 55 52 53 49 56 45 20 6b 65 79 77 6f 72 64 2e  CURSIVE keyword.
249e0 20 20 54 68 65 20 75 73 65 20 6f 66 20 52 45 43    The use of REC
249f0 55 52 53 49 56 45 20 64 6f 65 73 20 6e 6f 74 20  URSIVE does not 
24a00 66 6f 72 63 65 0a 63 6f 6d 6d 6f 6e 20 74 61 62  force.common tab
24a10 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  le expressions t
24a20 6f 20 62 65 20 72 65 63 75 72 73 69 76 65 2e 0a  o be recursive..
24a30 0a 3c 74 63 6c 3e 0a 68 64 5f 66 72 61 67 6d 65  .<tcl>.hd_fragme
24a40 6e 74 20 72 65 63 75 72 73 69 76 65 63 74 65 20  nt recursivecte 
24a50 7b 72 65 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f  {recursive commo
24a60 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69  n table expressi
24a70 6f 6e 73 7d 20 5c 0a 7b 72 65 63 75 72 73 69 76  ons} \.{recursiv
24a80 65 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65  e common table e
24a90 78 70 72 65 73 73 69 6f 6e 7d 20 7b 72 65 63 75  xpression} {recu
24aa0 72 73 69 76 65 20 71 75 65 72 79 7d 0a 3c 2f 74  rsive query}.</t
24ab0 63 6c 3e 0a 3c 68 33 3e 52 65 63 75 72 73 69 76  cl>.<h3>Recursiv
24ac0 65 20 43 6f 6d 6d 6f 6e 20 54 61 62 6c 65 20 45  e Common Table E
24ad0 78 70 72 65 73 73 69 6f 6e 73 3c 2f 68 33 3e 0a  xpressions</h3>.
24ae0 0a 3c 70 3e 41 20 72 65 63 75 72 73 69 76 65 20  .<p>A recursive 
24af0 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70  common table exp
24b00 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 75  ression can be u
24b10 73 65 64 20 74 6f 20 77 72 69 74 65 20 61 20 71  sed to write a q
24b20 75 65 72 79 20 74 68 61 74 0a 77 61 6c 6b 73 20  uery that.walks 
24b30 61 20 74 72 65 65 20 6f 72 20 67 72 61 70 68 2e  a tree or graph.
24b40 20 20 41 20 72 65 63 75 72 73 69 76 65 20 63 6f    A recursive co
24b50 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65  mmon table expre
24b60 73 73 69 6f 6e 20 68 61 73 20 74 68 65 20 73 61  ssion has the sa
24b70 6d 65 0a 62 61 73 69 63 20 73 79 6e 74 61 78 20  me.basic syntax 
24b80 61 73 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 63  as an ordinary c
24b90 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72  ommon table expr
24ba0 65 73 73 69 6f 6e 2c 20 62 75 74 20 77 69 74 68  ession, but with
24bb0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 61   the following.a
24bc0 64 64 69 74 69 6f 6e 61 6c 20 66 65 61 74 75 72  dditional featur
24bd0 65 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 54  es:..<ol>.<li> T
24be0 68 65 20 22 5b 73 65 6c 65 63 74 2d 73 74 6d 74  he "[select-stmt
24bf0 5d 22 0a 20 20 20 20 20 6d 75 73 74 20 62 65 20  ]".     must be 
24c00 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 73 65 6c 65  a [compound sele
24c10 63 74 5d 20 77 68 65 72 65 20 74 68 65 20 72 69  ct] where the ri
24c20 67 68 74 2d 6d 6f 73 74 20 5b 63 6f 6d 70 6f 75  ght-most [compou
24c30 6e 64 2d 6f 70 65 72 61 74 6f 72 5d 20 69 73 0a  nd-operator] is.
24c40 20 20 20 20 20 65 69 74 68 65 72 20 55 4e 49 4f       either UNIO
24c50 4e 20 6f 72 20 55 4e 49 4f 4e 20 41 4c 4c 2e 0a  N or UNION ALL..
24c60 3c 6c 69 3e 20 54 68 65 20 74 61 62 6c 65 20 6e  <li> The table n
24c70 61 6d 65 64 20 6f 6e 20 74 68 65 20 6c 65 66 74  amed on the left
24c80 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
24c90 65 20 41 53 20 6b 65 79 77 6f 72 64 20 6d 75 73  e AS keyword mus
24ca0 74 20 61 70 70 65 61 72 0a 20 20 20 20 20 65 78  t appear.     ex
24cb0 61 63 74 6c 79 20 6f 6e 63 65 20 69 6e 20 74 68  actly once in th
24cc0 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f 66  e FROM clause of
24cd0 20 74 68 65 20 72 69 67 68 74 2d 6d 6f 73 74 20   the right-most 
24ce0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
24cf0 0a 20 20 20 20 20 6f 66 20 74 68 65 20 63 6f 6d  .     of the com
24d00 70 6f 75 6e 64 20 73 65 6c 65 63 74 2c 20 61 6e  pound select, an
24d10 64 20 6e 6f 77 68 65 72 65 20 65 6c 73 65 2e 0a  d nowhere else..
24d20 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 54 6f 20 70 75 74  </ol>..<p>To put
24d30 20 69 74 20 61 6e 6f 74 68 65 72 20 77 61 79 2c   it another way,
24d40 20 61 20 72 65 63 75 72 73 69 76 65 20 63 6f 6d   a recursive com
24d50 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
24d60 73 69 6f 6e 20 6d 75 73 74 0a 6c 6f 6f 6b 20 6c  sion must.look l
24d70 69 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ike the followin
24d80 67 3a 0a 0a 3c 74 63 6c 3e 52 65 63 75 72 73 69  g:..<tcl>Recursi
24d90 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
24da0 72 65 63 75 72 73 69 76 65 2d 63 74 65 3c 2f 74  recursive-cte</t
24db0 63 6c 3e 0a 0a 3c 70 3e 43 61 6c 6c 20 74 68 65  cl>..<p>Call the
24dc0 20 74 61 62 6c 65 20 6e 61 6d 65 64 20 62 79 20   table named by 
24dd0 74 68 65 20 5b 63 74 65 2d 74 61 62 6c 65 2d 6e  the [cte-table-n
24de0 61 6d 65 5d 20 69 6e 20 61 20 72 65 63 75 72 73  ame] in a recurs
24df0 69 76 65 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65  ive.common table
24e00 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 65 20   expression the 
24e10 22 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65  "recursive table
24e20 22 2e 0a 49 6e 20 74 68 65 20 5b 72 65 63 75 72  "..In the [recur
24e30 73 69 76 65 2d 63 74 65 5d 20 62 75 62 62 6c 65  sive-cte] bubble
24e40 20 64 69 61 67 72 61 6d 20 61 62 6f 76 65 2c 20   diagram above, 
24e50 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 74 61  the recursive.ta
24e60 62 6c 65 20 6d 75 73 74 20 61 70 70 65 61 72 20  ble must appear 
24e70 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 6e 20  exactly once in 
24e80 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20  the FROM clause 
24e90 6f 66 20 74 68 65 20 0a 3c 79 79 74 65 72 6d 3e  of the .<yyterm>
24ea0 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74  recursive-select
24eb0 3c 2f 79 79 74 65 72 6d 3e 0a 61 6e 64 20 6d 75  </yyterm>.and mu
24ec0 73 74 20 6e 6f 74 20 61 70 70 65 61 72 20 61 6e  st not appear an
24ed0 79 77 68 65 72 65 20 65 6c 73 65 20 69 6e 20 65  ywhere else in e
24ee0 69 74 68 65 72 20 74 68 65 0a 3c 79 79 74 65 72  ither the.<yyter
24ef0 6d 3e 69 6e 69 74 69 61 6c 2d 73 65 6c 65 63 74  m>initial-select
24f00 3c 2f 79 79 74 65 72 6d 3e 20 6f 72 20 74 68 65  </yyterm> or the
24f10 0a 3c 79 79 74 65 72 6d 3e 72 65 63 75 72 73 69  .<yyterm>recursi
24f20 76 65 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72  ve-select</yyter
24f30 6d 3e 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 75  m>, including su
24f40 62 71 75 65 72 69 65 73 2e 0a 54 68 65 20 3c 79  bqueries..The <y
24f50 79 74 65 72 6d 3e 69 6e 69 74 69 61 6c 2d 73 65  yterm>initial-se
24f60 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e 20 6d 61  lect</yyterm> ma
24f70 79 20 62 65 0a 61 20 5b 63 6f 6d 70 6f 75 6e 64  y be.a [compound
24f80 20 73 65 6c 65 63 74 5d 2c 20 62 75 74 20 69 74   select], but it
24f90 20 6d 61 79 20 6e 6f 74 20 69 6e 63 6c 75 64 65   may not include
24fa0 20 61 6e 20 4f 52 44 45 52 20 42 59 2c 20 4c 49   an ORDER BY, LI
24fb0 4d 49 54 2c 20 6f 72 20 4f 46 46 53 45 54 2e 0a  MIT, or OFFSET..
24fc0 54 68 65 20 72 65 63 75 72 73 69 76 65 2d 73 65  The recursive-se
24fd0 6c 65 63 74 20 6d 75 73 74 20 62 65 20 61 20 73  lect must be a s
24fe0 69 6d 70 6c 65 20 73 65 6c 65 63 74 2c 20 6e 6f  imple select, no
24ff0 74 20 61 20 63 6f 6d 70 6f 75 6e 64 2e 20 20 54  t a compound.  T
25000 68 65 0a 72 65 63 75 72 73 69 76 65 2d 73 65 6c  he.recursive-sel
25010 65 63 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74  ect is allowed t
25020 6f 20 69 6e 63 6c 75 64 65 20 61 6e 20 4f 52 44  o include an ORD
25030 45 52 20 42 59 2c 20 4c 49 4d 49 54 2c 20 61 6e  ER BY, LIMIT, an
25040 64 2f 6f 72 20 4f 46 46 53 45 54 2e 0a 0a 3c 70  d/or OFFSET...<p
25050 3e 54 68 65 20 62 61 73 69 63 20 61 6c 67 6f 72  >The basic algor
25060 69 74 68 6d 20 66 6f 72 20 63 6f 6d 70 75 74 69  ithm for computi
25070 6e 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ng the content o
25080 66 20 74 68 65 20 72 65 63 75 72 73 69 76 65 20  f the recursive 
25090 74 61 62 6c 65 0a 69 73 20 61 73 20 66 6f 6c 6c  table.is as foll
250a0 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20  ows:..<ol>.<li> 
250b0 52 75 6e 20 74 68 65 20 3c 79 79 74 65 72 6d 3e  Run the <yyterm>
250c0 69 6e 69 74 69 61 6c 2d 73 65 6c 65 63 74 3c 2f  initial-select</
250d0 79 79 74 65 72 6d 3e 20 61 6e 64 20 61 64 64 20  yyterm> and add 
250e0 74 68 65 20 72 65 73 75 6c 74 73 20 74 6f 20 61  the results to a
250f0 20 71 75 65 75 65 2e 0a 3c 6c 69 3e 20 57 68 69   queue..<li> Whi
25100 6c 65 20 74 68 65 20 71 75 65 75 65 20 69 73 20  le the queue is 
25110 6e 6f 74 20 65 6d 70 74 79 3a 0a 3c 6f 6c 20 74  not empty:.<ol t
25120 79 70 65 3d 22 61 22 3e 0a 3c 6c 69 3e 20 45 78  ype="a">.<li> Ex
25130 74 72 61 63 74 20 61 20 73 69 6e 67 6c 65 20 72  tract a single r
25140 6f 77 20 66 72 6f 6d 20 74 68 65 20 71 75 65 75  ow from the queu
25150 65 2e 0a 3c 6c 69 3e 20 49 6e 73 65 72 74 20 74  e..<li> Insert t
25160 68 61 74 20 73 69 6e 67 6c 65 20 72 6f 77 20 69  hat single row i
25170 6e 74 6f 20 74 68 65 20 72 65 63 75 72 73 69 76  nto the recursiv
25180 65 20 74 61 62 6c 65 0a 3c 6c 69 3e 20 50 72 65  e table.<li> Pre
25190 74 65 6e 64 20 74 68 61 74 20 74 68 65 20 73 69  tend that the si
251a0 6e 67 6c 65 20 72 6f 77 20 6a 75 73 74 20 65 78  ngle row just ex
251b0 74 72 61 63 74 65 64 20 69 73 20 74 68 65 20 6f  tracted is the o
251c0 6e 6c 79 0a 20 20 20 20 20 72 6f 77 20 69 6e 20  nly.     row in 
251d0 74 68 65 20 72 65 63 75 72 73 69 76 65 20 74 61  the recursive ta
251e0 62 6c 65 20 61 6e 64 20 72 75 6e 20 74 68 65 20  ble and run the 
251f0 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74  recursive-select
25200 2c 0a 20 20 20 20 20 61 64 64 69 6e 67 20 61 6c  ,.     adding al
25210 6c 20 72 65 73 75 6c 74 73 20 74 6f 20 74 68 65  l results to the
25220 20 71 75 65 75 65 2e 0a 3c 2f 6f 6c 3e 0a 3c 2f   queue..</ol>.</
25230 6f 6c 3e 0a 0a 3c 70 3e 54 68 65 20 62 61 73 69  ol>..<p>The basi
25240 63 20 70 72 6f 63 65 64 75 72 65 20 61 62 6f 76  c procedure abov
25250 65 20 6d 61 79 20 6d 6f 64 69 66 69 65 64 20 62  e may modified b
25260 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
25270 61 64 64 69 74 69 6f 6e 61 6c 20 72 75 6c 65 73  additional rules
25280 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a  :..<ul>.<li><p>.
25290 20 20 49 66 20 61 20 55 4e 49 4f 4e 20 6f 70 65    If a UNION ope
252a0 72 61 74 6f 72 20 63 6f 6e 6e 65 63 74 73 20 74  rator connects t
252b0 68 65 20 3c 79 79 74 65 72 6d 3e 69 6e 69 74 69  he <yyterm>initi
252c0 61 6c 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72  al-select</yyter
252d0 6d 3e 20 77 69 74 68 20 74 68 65 0a 20 20 3c 79  m> with the.  <y
252e0 79 74 65 72 6d 3e 72 65 63 75 72 73 69 76 65 2d  yterm>recursive-
252f0 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e 2c  select</yyterm>,
25300 20 74 68 65 6e 20 6f 6e 6c 79 20 61 64 64 20 72   then only add r
25310 6f 77 73 20 74 6f 20 74 68 65 20 71 75 65 75 65  ows to the queue
25320 20 69 66 20 0a 20 20 6e 6f 20 69 64 65 6e 74 69   if .  no identi
25330 63 61 6c 20 72 6f 77 20 68 61 73 0a 20 20 62 65  cal row has.  be
25340 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 61 64  en previously ad
25350 64 65 64 20 74 6f 20 74 68 65 20 71 75 65 75 65  ded to the queue
25360 2e 20 20 52 65 70 65 61 74 65 64 20 72 6f 77 73  .  Repeated rows
25370 20 61 72 65 20 64 69 73 63 61 72 64 65 64 20 62   are discarded b
25380 65 66 6f 72 65 20 62 65 69 6e 67 0a 20 20 61 64  efore being.  ad
25390 64 65 64 20 74 6f 20 74 68 65 20 71 75 65 75 65  ded to the queue
253a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 72 65 70   even if the rep
253b0 65 61 74 65 64 20 72 6f 77 73 20 68 61 76 65 20  eated rows have 
253c0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 65 78 74  already been ext
253d0 72 61 63 74 65 64 0a 20 20 66 72 6f 6d 20 74 68  racted.  from th
253e0 65 20 71 75 65 75 65 20 62 79 20 74 68 65 20 72  e queue by the r
253f0 65 63 75 72 73 69 6f 6e 20 73 74 65 70 2e 20 20  ecursion step.  
25400 49 66 20 74 68 65 20 6f 70 65 72 61 74 6f 72 20  If the operator 
25410 69 73 20 55 4e 49 4f 4e 20 41 4c 4c 2c 0a 20 20  is UNION ALL,.  
25420 74 68 65 6e 20 61 6c 6c 20 72 6f 77 73 20 67 65  then all rows ge
25430 6e 65 72 61 74 65 64 20 62 79 20 62 6f 74 68 20  nerated by both 
25440 74 68 65 20 3c 79 79 74 65 72 6d 3e 69 6e 69 74  the <yyterm>init
25450 69 61 6c 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65  ial-select</yyte
25460 72 6d 3e 20 61 6e 64 20 74 68 65 0a 20 20 3c 79  rm> and the.  <y
25470 79 74 65 72 6d 3e 72 65 63 75 72 73 69 76 65 2d  yterm>recursive-
25480 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e 20  select</yyterm> 
25490 61 72 65 20 61 6c 77 61 79 73 20 61 64 64 65 64  are always added
254a0 20 74 6f 20 74 68 65 20 71 75 65 75 65 20 65 76   to the queue ev
254b0 65 6e 20 69 66 0a 20 20 74 68 65 79 20 61 72 65  en if.  they are
254c0 20 72 65 70 65 61 74 73 2e 0a 20 20 57 68 65 6e   repeats..  When
254d0 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 69 66 20   determining if 
254e0 61 20 72 6f 77 20 69 73 20 72 65 70 65 61 74 65  a row is repeate
254f0 64 2c 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 63  d, NULL values c
25500 6f 6d 70 61 72 65 0a 20 20 65 71 75 61 6c 20 74  ompare.  equal t
25510 6f 20 6f 6e 65 20 61 6e 6f 74 68 65 72 20 61 6e  o one another an
25520 64 20 6e 6f 74 20 65 71 75 61 6c 20 74 6f 20 61  d not equal to a
25530 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 2e 0a  ny other value..
25540 3c 6c 69 3e 3c 70 3e 0a 20 20 54 68 65 20 4c 49  <li><p>.  The LI
25550 4d 49 54 20 63 6c 61 75 73 65 2c 20 69 66 20 70  MIT clause, if p
25560 72 65 73 65 6e 74 2c 20 64 65 74 65 72 6d 69 6e  resent, determin
25570 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  es the maximum n
25580 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68  umber of rows th
25590 61 74 0a 20 20 77 69 6c 6c 20 65 76 65 72 20 62  at.  will ever b
255a0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 72  e added to the r
255b0 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 20 69  ecursive table i
255c0 6e 20 73 74 65 70 20 32 62 2e 0a 20 20 4f 6e 63  n step 2b..  Onc
255d0 65 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 72  e the limit is r
255e0 65 61 63 68 65 64 2c 20 74 68 65 20 72 65 63 75  eached, the recu
255f0 72 73 69 6f 6e 20 73 74 6f 70 73 2e 0a 20 20 41  rsion stops..  A
25600 20 6c 69 6d 69 74 20 6f 66 20 7a 65 72 6f 20 6d   limit of zero m
25610 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 72 6f 77  eans that no row
25620 73 20 61 72 65 20 65 76 65 72 20 61 64 64 65 64  s are ever added
25630 20 74 6f 20 74 68 65 0a 20 20 72 65 63 75 72 73   to the.  recurs
25640 69 76 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 61  ive table, and a
25650 20 6e 65 67 61 74 69 76 65 20 6c 69 6d 69 74 20   negative limit 
25660 6d 65 61 6e 73 20 61 6e 20 75 6e 6c 69 6d 69 74  means an unlimit
25670 65 64 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  ed number of row
25680 73 0a 20 20 6d 61 79 20 62 65 20 61 64 64 65 64  s.  may be added
25690 20 74 6f 20 74 68 65 20 72 65 63 75 72 73 69 76   to the recursiv
256a0 65 20 74 61 62 6c 65 2e 0a 3c 6c 69 3e 3c 70 3e  e table..<li><p>
256b0 0a 20 20 54 68 65 20 4f 46 46 53 45 54 20 63 6c  .  The OFFSET cl
256c0 61 75 73 65 2c 20 69 66 20 69 74 20 69 73 20 70  ause, if it is p
256d0 72 65 73 65 6e 74 20 61 6e 64 20 68 61 73 20 61  resent and has a
256e0 20 70 6f 73 69 74 69 76 65 20 76 61 6c 75 65 20   positive value 
256f0 4e 2c 20 70 72 65 76 65 6e 74 73 20 74 68 65 0a  N, prevents the.
25700 20 20 66 69 72 73 74 20 4e 20 72 6f 77 73 20 66    first N rows f
25710 72 6f 6d 20 62 65 69 6e 67 20 61 64 64 65 64 20  rom being added 
25720 74 6f 20 74 68 65 20 72 65 63 75 72 73 69 76 65  to the recursive
25730 20 74 61 62 6c 65 2e 0a 20 20 54 68 65 20 66 69   table..  The fi
25740 72 73 74 20 4e 20 72 6f 77 73 20 61 72 65 20 73  rst N rows are s
25750 74 69 6c 6c 20 70 72 6f 63 65 73 73 65 64 0a 20  till processed. 
25760 20 62 79 20 74 68 65 20 3c 79 79 74 65 72 6d 3e   by the <yyterm>
25770 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74  recursive-select
25780 3c 2f 79 79 74 65 72 6d 3e 20 26 6d 64 61 73 68  </yyterm> &mdash
25790 3b 20 74 68 65 79 0a 20 20 6a 75 73 74 20 61 72  ; they.  just ar
257a0 65 20 6e 6f 74 20 61 64 64 65 64 20 74 6f 20 74  e not added to t
257b0 68 65 20 72 65 63 75 72 73 69 76 65 20 74 61 62  he recursive tab
257c0 6c 65 2e 20 20 52 6f 77 73 20 61 72 65 20 6e 6f  le.  Rows are no
257d0 74 20 63 6f 75 6e 74 65 64 20 74 6f 77 61 72 64  t counted toward
257e0 0a 20 20 66 75 6c 66 69 6c 6c 69 6e 67 20 74 68  .  fulfilling th
257f0 65 20 4c 49 4d 49 54 20 75 6e 74 69 6c 20 61 6c  e LIMIT until al
25800 6c 20 4f 46 46 53 45 54 20 72 6f 77 73 20 68 61  l OFFSET rows ha
25810 76 65 20 62 65 65 6e 20 73 6b 69 70 70 65 64 2e  ve been skipped.
25820 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 49 66 20 61 6e  .<li><p>.  If an
25830 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
25840 20 69 73 20 70 72 65 73 65 6e 74 2c 20 69 74 20   is present, it 
25850 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 6f  determines the o
25860 72 64 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f  rder in which ro
25870 77 73 0a 20 20 61 72 65 20 65 78 74 72 61 63 74  ws.  are extract
25880 65 64 20 66 72 6f 6d 20 74 68 65 20 71 75 65 75  ed from the queu
25890 65 20 69 6e 20 73 74 65 70 20 32 61 2e 20 20 49  e in step 2a.  I
258a0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 4f 52  f there is no OR
258b0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 0a 20  DER BY clause,. 
258c0 20 74 68 65 6e 20 74 68 65 20 6f 72 64 65 72 20   then the order 
258d0 69 6e 20 77 68 69 63 68 20 72 6f 77 73 20 61 72  in which rows ar
258e0 65 20 65 78 74 72 61 63 74 65 64 20 69 73 20 75  e extracted is u
258f0 6e 64 65 66 69 6e 65 64 2e 20 20 28 49 6e 20 74  ndefined.  (In t
25900 68 65 20 63 75 72 72 65 6e 74 0a 20 20 69 6d 70  he current.  imp
25910 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
25920 20 71 75 65 75 65 20 62 65 63 6f 6d 65 73 20 61   queue becomes a
25930 20 46 49 46 4f 20 69 66 20 74 68 65 20 4f 52 44   FIFO if the ORD
25940 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
25950 6f 6d 69 74 74 65 64 2c 0a 20 20 62 75 74 20 61  omitted,.  but a
25960 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
25970 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 20 6f 6e  ld not depend on
25980 20 74 68 61 74 20 66 61 63 74 20 73 69 6e 63 65   that fact since
25990 20 69 74 20 6d 69 67 68 74 20 63 68 61 6e 67 65   it might change
259a0 2e 29 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 68  .).</ul>..<tcl>h
259b0 64 5f 66 72 61 67 6d 65 6e 74 20 72 63 65 78 31  d_fragment rcex1
259c0 3c 2f 74 63 6c 3e 0a 3c 68 34 3e 52 65 63 75 72  </tcl>.<h4>Recur
259d0 73 69 76 65 20 51 75 65 72 79 20 45 78 61 6d 70  sive Query Examp
259e0 6c 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65  les</h4>..<p>The
259f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
25a00 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 69 6e 74   returns all int
25a10 65 67 65 72 73 20 62 65 74 77 65 65 6e 20 31 20  egers between 1 
25a20 61 6e 64 20 31 30 30 30 30 30 30 3a 0a 0a 3c 62  and 1000000:..<b
25a30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
25a40 57 49 54 48 20 52 45 43 55 52 53 49 56 45 0a 20  WITH RECURSIVE. 
25a50 20 63 6e 74 28 78 29 20 41 53 20 28 56 41 4c 55   cnt(x) AS (VALU
25a60 45 53 28 31 29 20 55 4e 49 4f 4e 20 41 4c 4c 20  ES(1) UNION ALL 
25a70 53 45 4c 45 43 54 20 78 2b 31 20 46 52 4f 4d 20  SELECT x+1 FROM 
25a80 63 6e 74 20 57 48 45 52 45 20 78 3c 31 30 30 30  cnt WHERE x<1000
25a90 30 30 30 29 0a 53 45 4c 45 43 54 20 78 20 46 52  000).SELECT x FR
25aa0 4f 4d 20 63 6e 74 3b 0a 3c 2f 70 72 65 3e 3c 2f  OM cnt;.</pre></
25ab0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
25ac0 43 6f 6e 73 69 64 65 72 20 68 6f 77 20 74 68 69  Consider how thi
25ad0 73 20 71 75 65 72 79 20 77 6f 72 6b 73 2e 20 20  s query works.  
25ae0 54 68 65 20 69 6e 69 74 69 61 6c 2d 73 65 6c 65  The initial-sele
25af0 63 74 0a 72 75 6e 73 20 66 69 72 73 74 20 61 6e  ct.runs first an
25b00 64 20 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67  d returns a sing
25b10 6c 65 20 72 6f 77 0a 77 69 74 68 20 61 20 73 69  le row.with a si
25b20 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 22 31 22 2e  ngle column "1".
25b30 20 20 54 68 69 73 20 6f 6e 65 20 72 6f 77 20 69    This one row i
25b40 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 71  s added to the q
25b50 75 65 75 65 2e 20 20 49 6e 0a 73 74 65 70 20 32  ueue.  In.step 2
25b60 61 2c 20 74 68 61 74 20 6f 6e 65 20 72 6f 77 20  a, that one row 
25b70 69 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  is extracted fro
25b80 6d 20 74 68 65 20 71 75 65 75 65 20 61 6e 64 20  m the queue and 
25b90 61 64 64 65 64 20 74 6f 20 22 63 6e 74 22 2e 0a  added to "cnt"..
25ba0 54 68 65 6e 20 74 68 65 20 72 65 63 75 72 73 69  Then the recursi
25bb0 76 65 2d 73 65 6c 65 63 74 20 69 73 20 72 75 6e  ve-select is run
25bc0 20 69 6e 20 61 63 63 6f 72 64 61 6e 63 65 20 77   in accordance w
25bd0 69 74 68 20 73 74 65 70 20 32 63 20 67 65 6e 65  ith step 2c gene
25be0 72 61 74 69 6e 67 0a 61 20 73 69 6e 67 6c 65 20  rating.a single 
25bf0 6e 65 77 20 72 6f 77 20 77 69 74 68 20 76 61 6c  new row with val
25c00 75 65 20 22 32 22 20 74 6f 20 61 64 64 20 74 6f  ue "2" to add to
25c10 20 74 68 65 20 71 75 65 75 65 2e 20 20 54 68 65   the queue.  The
25c20 20 71 75 65 75 65 20 73 74 69 6c 6c 0a 68 61 73   queue still.has
25c30 20 6f 6e 65 20 72 6f 77 2c 20 73 6f 20 73 74 65   one row, so ste
25c40 70 20 32 20 72 65 70 65 61 74 73 2e 20 20 54 68  p 2 repeats.  Th
25c50 65 20 22 32 22 20 72 6f 77 20 69 73 20 65 78 74  e "2" row is ext
25c60 72 61 63 74 65 64 20 61 6e 64 20 61 64 64 65 64  racted and added
25c70 20 74 6f 20 74 68 65 0a 72 65 63 75 72 73 69 76   to the.recursiv
25c80 65 20 74 61 62 6c 65 20 62 79 20 73 74 65 70 73  e table by steps
25c90 20 32 61 20 61 6e 64 20 32 62 2e 20 20 54 68 65   2a and 2b.  The
25ca0 6e 20 74 68 65 20 72 6f 77 20 63 6f 6e 74 61 69  n the row contai
25cb0 6e 69 6e 67 20 32 20 69 73 20 75 73 65 64 20 0a  ning 2 is used .
25cc0 61 73 20 69 66 20 69 74 20 77 65 72 65 20 74 68  as if it were th
25cd0 65 20 63 6f 6d 70 6c 65 74 65 20 63 6f 6e 74 65  e complete conte
25ce0 6e 74 20 6f 66 20 74 68 65 20 72 65 63 75 72 73  nt of the recurs
25cf0 69 76 65 20 74 61 62 6c 65 20 61 6e 64 20 74 68  ive table and th
25d00 65 20 0a 72 65 63 75 72 73 69 76 65 2d 73 65 6c  e .recursive-sel
25d10 65 63 74 20 69 73 20 72 75 6e 20 61 67 61 69 6e  ect is run again
25d20 2c 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 61  , resulting in a
25d30 20 72 6f 77 20 77 69 74 68 20 76 61 6c 75 65 20   row with value 
25d40 22 33 22 20 62 65 69 6e 67 20 61 64 64 65 64 0a  "3" being added.
25d50 74 6f 20 74 68 65 20 71 75 65 75 65 2e 20 20 54  to the queue.  T
25d60 68 69 73 20 72 65 70 65 61 74 73 20 39 39 39 39  his repeats 9999
25d70 39 39 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 66  99 times until f
25d80 69 6e 61 6c 6c 79 20 61 74 20 73 74 65 70 20 32  inally at step 2
25d90 61 20 74 68 65 0a 6f 6e 6c 79 20 76 61 6c 75 65  a the.only value
25da0 20 6f 6e 20 74 68 65 20 71 75 65 75 65 20 69 73   on the queue is
25db0 20 61 20 72 6f 77 20 63 6f 6e 74 61 69 6e 69 6e   a row containin
25dc0 67 20 31 30 30 30 30 30 30 2e 20 20 54 68 61 74  g 1000000.  That
25dd0 20 72 6f 77 20 69 73 0a 65 78 74 72 61 63 74 65   row is.extracte
25de0 64 20 61 6e 64 20 61 64 64 65 64 20 74 6f 20 74  d and added to t
25df0 68 65 20 72 65 63 75 72 73 69 76 65 20 74 61 62  he recursive tab
25e00 6c 65 2e 20 20 42 75 74 20 74 68 69 73 20 74 69  le.  But this ti
25e10 6d 65 2c 20 74 68 65 0a 57 48 45 52 45 20 63 6c  me, the.WHERE cl
25e20 61 75 73 65 20 63 61 75 73 65 73 20 74 68 65 20  ause causes the 
25e30 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74  recursive-select
25e40 20 74 6f 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f   to return no ro
25e50 77 73 2c 20 73 6f 20 74 68 65 0a 71 75 65 75 65  ws, so the.queue
25e60 20 72 65 6d 61 69 6e 73 20 65 6d 70 74 79 20 61   remains empty a
25e70 6e 64 20 74 68 65 20 72 65 63 75 72 73 69 6f 6e  nd the recursion
25e80 20 73 74 6f 70 73 2e 0a 0a 3c 70 3e 3c 62 3e 4f   stops...<p><b>O
25e90 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6e 6f 74 65  ptimization note
25ea0 3a 3c 2f 62 3e 0a 49 6e 20 74 68 65 20 64 69 73  :</b>.In the dis
25eb0 63 75 73 73 69 6f 6e 20 61 62 6f 76 65 2c 20 73  cussion above, s
25ec0 74 61 74 65 6d 65 6e 74 73 20 6c 69 6b 65 20 22  tatements like "
25ed0 69 6e 73 65 72 74 20 74 68 65 20 72 6f 77 20 69  insert the row i
25ee0 6e 74 6f 0a 74 68 65 20 72 65 63 75 72 73 69 76  nto.the recursiv
25ef0 65 20 74 61 62 6c 65 22 20 73 68 6f 75 6c 64 20  e table" should 
25f00 62 65 20 75 6e 64 65 72 73 74 6f 6f 64 20 63 6f  be understood co
25f10 6e 63 65 70 74 75 61 6c 6c 79 2c 20 6e 6f 74 20  nceptually, not 
25f20 6c 69 74 65 72 61 6c 6c 79 2e 0a 49 74 20 73 6f  literally..It so
25f30 75 6e 64 73 20 61 73 20 69 66 20 53 51 4c 69 74  unds as if SQLit
25f40 65 20 69 73 20 61 63 63 75 6d 75 6c 61 74 69 6e  e is accumulatin
25f50 67 20 61 20 68 75 67 65 20 74 61 62 6c 65 0a 63  g a huge table.c
25f60 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 65 20 6d 69  ontaining one mi
25f70 6c 6c 69 6f 6e 20 72 6f 77 73 2c 20 74 68 65 6e  llion rows, then
25f80 20 67 6f 69 6e 67 20 62 61 63 6b 20 61 6e 64 20   going back and 
25f90 73 63 61 6e 6e 69 6e 67 20 74 68 61 74 20 74 61  scanning that ta
25fa0 62 6c 65 0a 66 72 6f 6d 20 74 6f 70 20 74 6f 20  ble.from top to 
25fb0 62 6f 74 74 6f 6d 20 74 6f 20 67 65 6e 65 72 61  bottom to genera
25fc0 74 65 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  te the result.  
25fd0 57 68 61 74 20 72 65 61 6c 6c 79 20 68 61 70 70  What really happ
25fe0 65 6e 73 0a 69 73 20 74 68 61 74 20 74 68 65 20  ens.is that the 
25ff0 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20  query optimizer 
26000 73 65 65 73 20 74 68 61 74 20 76 61 6c 75 65 73  sees that values
26010 20 69 6e 20 74 68 65 0a 22 63 6e 74 22 20 72 65   in the."cnt" re
26020 63 75 72 73 69 76 65 20 74 61 62 6c 65 20 61 72  cursive table ar
26030 65 20 6f 6e 6c 79 20 75 73 65 64 20 6f 6e 63 65  e only used once
26040 2e 20 20 53 6f 20 61 73 20 65 61 63 68 20 72 6f  .  So as each ro
26050 77 20 69 73 20 61 64 64 65 64 20 74 6f 0a 74 68  w is added to.th
26060 65 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c  e recursive tabl
26070 65 2c 20 74 68 61 74 20 72 6f 77 20 69 73 20 69  e, that row is i
26080 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
26090 6e 65 64 20 61 73 20 61 20 72 65 73 75 6c 74 20  ned as a result 
260a0 6f 66 20 74 68 65 20 6d 61 69 6e 0a 53 45 4c 45  of the main.SELE
260b0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT statement and
260c0 20 74 68 65 6e 20 64 69 73 63 61 72 64 65 64 2e   then discarded.
260d0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 3c 65    SQLite does <e
260e0 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 61 63 63 75 6d  m>not</em> accum
260f0 75 6c 61 74 65 0a 61 20 74 65 6d 70 6f 72 61 72  ulate.a temporar
26100 79 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 69  y table containi
26110 6e 67 20 61 20 6d 69 6c 6c 69 6f 6e 20 72 6f 77  ng a million row
26120 73 2e 20 20 56 65 72 79 20 6c 69 74 74 6c 65 20  s.  Very little 
26130 6d 65 6d 6f 72 79 20 69 73 0a 6e 65 65 64 65 64  memory is.needed
26140 20 74 6f 20 72 75 6e 20 74 68 65 20 61 62 6f 76   to run the abov
26150 65 20 65 78 61 6d 70 6c 65 2e 20 20 48 6f 77 65  e example.  Howe
26160 76 65 72 2c 20 69 66 20 74 68 65 20 65 78 61 6d  ver, if the exam
26170 70 6c 65 20 68 61 64 20 75 73 65 64 0a 55 4e 49  ple had used.UNI
26180 4f 4e 20 69 6e 73 74 65 61 64 20 6f 66 20 55 4e  ON instead of UN
26190 49 4f 4e 20 41 4c 4c 2c 20 74 68 65 6e 20 53 51  ION ALL, then SQ
261a0 4c 69 74 65 20 77 6f 75 6c 64 20 68 61 76 65 20  Lite would have 
261b0 68 61 64 20 74 6f 20 6b 65 65 70 20 61 72 6f 75  had to keep arou
261c0 6e 64 0a 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  nd.all previousl
261d0 79 20 67 65 6e 65 72 61 74 65 64 20 63 6f 6e 74  y generated cont
261e0 65 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ent in order to 
261f0 63 68 65 63 6b 20 66 6f 72 20 64 75 70 6c 69 63  check for duplic
26200 61 74 65 73 2e 0a 46 6f 72 20 74 68 69 73 20 72  ates..For this r
26210 65 61 73 6f 6e 2c 20 70 72 6f 67 72 61 6d 6d 65  eason, programme
26220 72 73 20 73 68 6f 75 6c 64 20 73 74 72 69 76 65  rs should strive
26230 20 74 6f 20 75 73 65 20 55 4e 49 4f 4e 20 41 4c   to use UNION AL
26240 4c 20 69 6e 73 74 65 61 64 0a 6f 66 20 55 4e 49  L instead.of UNI
26250 4f 4e 20 77 68 65 6e 20 66 65 61 73 69 62 6c 65  ON when feasible
26260 2e 0a 0a 3c 70 3e 48 65 72 65 20 69 73 20 61 20  ...<p>Here is a 
26270 76 61 72 69 61 74 69 6f 6e 20 6f 6e 20 74 68 65  variation on the
26280 20 70 72 65 76 69 6f 75 73 20 65 78 61 6d 70 6c   previous exampl
26290 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  e:..<blockquote>
262a0 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55 52  <pre>.WITH RECUR
262b0 53 49 56 45 0a 20 20 63 6e 74 28 78 29 20 41 53  SIVE.  cnt(x) AS
262c0 20 28 0a 20 20 20 20 20 53 45 4c 45 43 54 20 31   (.     SELECT 1
262d0 0a 20 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a  .     UNION ALL.
262e0 20 20 20 20 20 53 45 4c 45 43 54 20 78 2b 31 20       SELECT x+1 
262f0 46 52 4f 4d 20 63 6e 74 0a 20 20 20 20 20 20 4c  FROM cnt.      L
26300 49 4d 49 54 20 31 30 30 30 30 30 30 0a 20 20 29  IMIT 1000000.  )
26310 0a 53 45 4c 45 43 54 20 78 20 46 52 4f 4d 20 63  .SELECT x FROM c
26320 6e 74 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  nt;.</pre></bloc
26330 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 72  kquote>..<p>Ther
26340 65 20 61 72 65 20 74 77 6f 20 64 69 66 66 65 72  e are two differ
26350 65 6e 63 65 73 20 69 6e 20 74 68 69 73 20 76 61  ences in this va
26360 72 69 61 74 69 6f 6e 2e 20 20 54 68 65 20 69 6e  riation.  The in
26370 69 74 69 61 6c 2d 73 65 6c 65 63 74 20 69 73 0a  itial-select is.
26380 22 53 45 4c 45 43 54 20 31 22 20 69 6e 73 74 65  "SELECT 1" inste
26390 61 64 20 6f 66 20 22 56 41 4c 55 45 53 28 31 29  ad of "VALUES(1)
263a0 22 2e 20 20 42 75 74 20 74 68 6f 73 65 20 61 72  ".  But those ar
263b0 65 20 6a 75 73 74 20 64 69 66 66 65 72 65 6e 74  e just different
263c0 0a 73 79 6e 74 61 78 65 73 20 66 6f 72 20 73 61  .syntaxes for sa
263d0 79 69 6e 67 20 65 78 61 63 74 6c 79 20 74 68 65  ying exactly the
263e0 20 73 61 6d 65 20 74 68 69 6e 67 2e 20 20 54 68   same thing.  Th
263f0 65 20 6f 74 68 65 72 20 63 68 61 6e 67 65 20 69  e other change i
26400 73 20 74 68 61 74 20 74 68 65 0a 72 65 63 75 72  s that the.recur
26410 73 69 6f 6e 20 69 73 20 73 74 6f 70 70 65 64 20  sion is stopped 
26420 62 79 20 61 20 4c 49 4d 49 54 20 72 61 74 68 65  by a LIMIT rathe
26430 72 20 74 68 61 6e 20 61 20 57 48 45 52 45 20 63  r than a WHERE c
26440 6c 61 75 73 65 2e 20 20 54 68 65 20 75 73 65 20  lause.  The use 
26450 6f 66 0a 4c 49 4d 49 54 20 6d 65 61 6e 73 20 74  of.LIMIT means t
26460 68 61 74 20 77 68 65 6e 20 74 68 65 20 6f 6e 65  hat when the one
26470 2d 6d 69 6c 6c 69 6f 6e 74 68 20 72 6f 77 20 69  -millionth row i
26480 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 22  s added to the "
26490 63 6e 74 22 20 74 61 62 6c 65 0a 28 61 6e 64 20  cnt" table.(and 
264a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
264b0 6d 61 69 6e 20 53 45 4c 45 43 54 2c 20 74 68 61  main SELECT, tha
264c0 6e 6b 73 20 74 6f 20 74 68 65 20 71 75 65 72 79  nks to the query
264d0 20 6f 70 74 69 6d 69 7a 65 72 29 0a 74 68 65 6e   optimizer).then
264e0 20 74 68 65 20 72 65 63 75 72 73 69 6f 6e 20 73   the recursion s
264f0 74 6f 70 73 20 69 6d 6d 65 64 69 61 74 65 6c 79  tops immediately
26500 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 68   regardless of h
26510 6f 77 20 6d 61 6e 79 20 72 6f 77 73 20 6d 69 67  ow many rows mig
26520 68 74 20 62 65 0a 6c 65 66 74 20 69 6e 20 74 68  ht be.left in th
26530 65 20 71 75 65 75 65 2e 20 20 4f 6e 20 6d 6f 72  e queue.  On mor
26540 65 20 63 6f 6d 70 6c 65 78 20 71 75 65 72 69 65  e complex querie
26550 73 2c 20 69 74 20 63 61 6e 20 73 6f 6d 65 74 69  s, it can someti
26560 6d 65 73 20 62 65 0a 64 69 66 66 69 63 75 6c 74  mes be.difficult
26570 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
26580 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
26590 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
265a0 20 63 61 75 73 65 20 74 68 65 0a 71 75 65 75 65   cause the.queue
265b0 20 74 6f 20 64 72 61 69 6e 20 61 6e 64 20 74 68   to drain and th
265c0 65 20 72 65 63 75 72 73 69 6f 6e 20 74 6f 20 74  e recursion to t
265d0 65 72 6d 69 6e 61 74 65 2e 20 20 42 75 74 20 74  erminate.  But t
265e0 68 65 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20  he LIMIT clause 
265f0 77 69 6c 6c 0a 61 6c 77 61 79 73 20 73 74 6f 70  will.always stop
26600 20 74 68 65 20 72 65 63 75 72 73 69 6f 6e 2e 20   the recursion. 
26610 20 53 6f 20 69 74 20 69 73 20 67 6f 6f 64 20 70   So it is good p
26620 72 61 63 74 69 63 65 20 74 6f 20 61 6c 77 61 79  ractice to alway
26630 73 20 69 6e 63 6c 75 64 65 20 61 0a 4c 49 4d 49  s include a.LIMI
26640 54 20 63 6c 61 75 73 65 20 61 73 20 61 20 73 61  T clause as a sa
26650 66 65 74 79 20 69 66 20 61 6e 20 75 70 70 65 72  fety if an upper
26660 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
26670 7a 65 20 6f 66 20 74 68 65 20 72 65 63 75 72 73  ze of the recurs
26680 69 6f 6e 20 0a 69 73 20 6b 6e 6f 77 6e 2e 0a 0a  ion .is known...
26690 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
266a0 20 72 63 65 78 32 3c 2f 74 63 6c 3e 0a 3c 68 34   rcex2</tcl>.<h4
266b0 3e 48 69 65 72 61 72 63 68 69 63 61 6c 20 51 75  >Hierarchical Qu
266c0 65 72 79 20 45 78 61 6d 70 6c 65 73 3c 2f 68 34  ery Examples</h4
266d0 3e 0a 0a 3c 70 3e 43 6f 6e 73 69 64 65 72 20 61  >..<p>Consider a
266e0 20 74 61 62 6c 65 20 74 68 61 74 20 64 65 73 63   table that desc
266f0 72 69 62 65 73 20 74 68 65 20 6d 65 6d 62 65 72  ribes the member
26700 73 20 6f 66 20 61 6e 20 6f 72 67 61 6e 69 7a 61  s of an organiza
26710 74 69 6f 6e 20 61 73 0a 77 65 6c 6c 20 61 73 20  tion as.well as 
26720 74 68 65 20 63 68 61 69 6e 2d 6f 66 2d 63 6f 6d  the chain-of-com
26730 6d 61 6e 64 20 77 69 74 68 69 6e 20 74 68 61 74  mand within that
26740 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 3a 0a 0a   organization:..
26750 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
26760 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20 6f  >.CREATE TABLE o
26770 72 67 28 0a 20 20 6e 61 6d 65 20 54 45 58 54 20  rg(.  name TEXT 
26780 50 52 49 4d 41 52 59 20 4b 45 59 2c 0a 20 20 62  PRIMARY KEY,.  b
26790 6f 73 73 20 54 45 58 54 20 52 45 46 45 52 45 4e  oss TEXT REFEREN
267a0 43 45 53 20 6f 72 67 2c 0a 20 20 68 65 69 67 68  CES org,.  heigh
267b0 74 20 49 4e 54 2c 0a 20 20 2d 2d 20 6f 74 68 65  t INT,.  -- othe
267c0 72 20 63 6f 6e 74 65 6e 74 20 6f 6d 69 74 74 65  r content omitte
267d0 64 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  d.);.</pre></blo
267e0 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 45 76 65  ckquote>..<p>Eve
267f0 72 79 20 6d 65 6d 62 65 72 20 69 6e 20 74 68 65  ry member in the
26800 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 68 61   organization ha
26810 73 20 61 20 6e 61 6d 65 2c 20 61 6e 64 20 6d 6f  s a name, and mo
26820 73 74 20 6d 65 6d 62 65 72 73 20 68 61 76 65 0a  st members have.
26830 61 20 73 69 6e 67 6c 65 20 62 6f 73 73 2e 20 20  a single boss.  
26840 28 54 68 65 20 68 65 61 64 20 6f 66 20 74 68 65  (The head of the
26850 20 77 68 6f 6c 65 20 6f 72 67 61 6e 69 7a 61 74   whole organizat
26860 69 6f 6e 20 68 61 73 20 61 20 4e 55 4c 4c 0a 22  ion has a NULL."
26870 62 6f 73 73 22 20 66 69 65 6c 64 2e 29 20 54 68  boss" field.) Th
26880 65 20 72 6f 77 73 20 6f 66 20 74 68 65 20 22 6f  e rows of the "o
26890 72 67 22 20 74 61 62 6c 65 20 66 6f 72 6d 20 61  rg" table form a
268a0 20 74 72 65 65 2e 0a 0a 3c 70 3e 48 65 72 65 20   tree...<p>Here 
268b0 69 73 20 61 20 71 75 65 72 79 20 74 68 61 74 20  is a query that 
268c0 63 6f 6d 70 75 74 65 73 20 74 68 65 20 61 76 65  computes the ave
268d0 72 61 67 65 20 68 65 69 67 68 74 20 6f 76 65 72  rage height over
268e0 20 65 76 65 72 79 6f 6e 65 0a 69 6e 20 41 6c 69   everyone.in Ali
268f0 63 65 27 73 20 6f 72 67 61 6e 69 7a 61 74 69 6f  ce's organizatio
26900 6e 2c 20 69 6e 63 6c 75 64 69 6e 67 20 41 6c 69  n, including Ali
26910 63 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  ce:..<blockquote
26920 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55  ><pre>.WITH RECU
26930 52 53 49 56 45 0a 20 20 77 6f 72 6b 73 5f 66 6f  RSIVE.  works_fo
26940 72 5f 61 6c 69 63 65 28 6e 29 20 41 53 20 28 0a  r_alice(n) AS (.
26950 20 20 20 20 56 41 4c 55 45 53 28 27 41 6c 69 63      VALUES('Alic
26960 65 27 29 0a 20 20 20 20 55 4e 49 4f 4e 0a 20 20  e').    UNION.  
26970 20 20 53 45 4c 45 43 54 20 6e 61 6d 65 20 46 52    SELECT name FR
26980 4f 4d 20 6f 72 67 2c 20 77 6f 72 6b 73 5f 66 6f  OM org, works_fo
26990 72 5f 61 6c 69 63 65 0a 20 20 20 20 20 57 48 45  r_alice.     WHE
269a0 52 45 20 6f 72 67 2e 62 6f 73 73 3d 77 6f 72 6b  RE org.boss=work
269b0 73 5f 66 6f 72 5f 61 6c 69 63 65 2e 6e 0a 20 20  s_for_alice.n.  
269c0 29 0a 53 45 4c 45 43 54 20 61 76 67 28 68 65 69  ).SELECT avg(hei
269d0 67 68 74 29 20 46 52 4f 4d 20 6f 72 67 0a 20 57  ght) FROM org. W
269e0 48 45 52 45 20 6f 72 67 2e 6e 61 6d 65 20 49 4e  HERE org.name IN
269f0 20 77 6f 72 6b 73 5f 66 6f 72 5f 61 6c 69 63 65   works_for_alice
26a00 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
26a10 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6e 65  uote>..<p>The ne
26a20 78 74 20 65 78 61 6d 70 6c 65 20 75 73 65 73 20  xt example uses 
26a30 74 77 6f 20 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c  two .common tabl
26a40 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  e expressions in
26a50 20 61 20 73 69 6e 67 6c 65 20 57 49 54 48 20 63   a single WITH c
26a60 6c 61 75 73 65 2e 20 20 0a 54 68 65 20 66 6f 6c  lause.  .The fol
26a70 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 72 65 63  lowing table rec
26a80 6f 72 64 73 20 61 20 66 61 6d 69 6c 79 20 74 72  ords a family tr
26a90 65 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  ee:..<blockquote
26aa0 3e 3c 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41  ><pre>.CREATE TA
26ab0 42 4c 45 20 66 61 6d 69 6c 79 28 0a 20 20 6e 61  BLE family(.  na
26ac0 6d 65 20 54 45 58 54 20 50 52 49 4d 41 52 59 20  me TEXT PRIMARY 
26ad0 4b 45 59 2c 0a 20 20 6d 6f 6d 20 54 45 58 54 20  KEY,.  mom TEXT 
26ae0 52 45 46 45 52 45 4e 43 45 53 20 66 61 6d 69 6c  REFERENCES famil
26af0 79 2c 0a 20 20 64 61 64 20 54 45 58 54 20 52 45  y,.  dad TEXT RE
26b00 46 45 52 45 4e 43 45 53 20 66 61 6d 69 6c 79 2c  FERENCES family,
26b10 0a 20 20 62 6f 72 6e 20 44 41 54 45 54 49 4d 45  .  born DATETIME
26b20 2c 0a 20 20 64 69 65 64 20 44 41 54 45 54 49 4d  ,.  died DATETIM
26b30 45 2c 20 2d 2d 20 4e 55 4c 4c 20 69 66 20 73 74  E, -- NULL if st
26b40 69 6c 6c 20 61 6c 69 76 65 0a 20 20 2d 2d 20 6f  ill alive.  -- o
26b50 74 68 65 72 20 63 6f 6e 74 65 6e 74 0a 29 3b 0a  ther content.);.
26b60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
26b70 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 22 66 61 6d  te>..<p>The "fam
26b80 69 6c 79 22 20 74 61 62 6c 65 20 69 73 20 73 69  ily" table is si
26b90 6d 69 6c 61 72 20 74 6f 20 74 68 65 20 65 61 72  milar to the ear
26ba0 6c 69 65 72 20 22 6f 72 67 22 20 74 61 62 6c 65  lier "org" table
26bb0 20 65 78 63 65 70 74 20 74 68 61 74 20 0a 6e 6f   except that .no
26bc0 77 20 74 68 65 72 65 20 61 72 65 20 74 77 6f 20  w there are two 
26bd0 70 61 72 65 6e 74 73 20 74 6f 20 65 61 63 68 20  parents to each 
26be0 6d 65 6d 62 65 72 2e 0a 57 65 20 77 61 6e 74 20  member..We want 
26bf0 74 6f 20 6b 6e 6f 77 20 61 6c 6c 20 6c 69 76 69  to know all livi
26c00 6e 67 20 61 6e 63 65 73 74 6f 72 73 20 6f 66 20  ng ancestors of 
26c10 41 6c 69 63 65 2c 20 66 72 6f 6d 20 6f 6c 64 65  Alice, from olde
26c20 73 74 20 74 6f 20 79 6f 75 6e 67 65 73 74 2e 0a  st to youngest..
26c30 41 6e 20 6f 72 64 69 6e 61 72 79 20 63 6f 6d 6d  An ordinary comm
26c40 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73  on table express
26c50 69 6f 6e 2c 20 22 70 61 72 65 6e 74 5f 6f 66 22  ion, "parent_of"
26c60 2c 20 69 73 20 64 65 66 69 6e 65 64 20 66 69 72  , is defined fir
26c70 73 74 2e 20 20 54 68 61 74 0a 6f 72 64 69 6e 61  st.  That.ordina
26c80 72 79 20 43 54 45 20 69 73 20 61 20 76 69 65 77  ry CTE is a view
26c90 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
26ca0 64 20 74 6f 20 66 69 6e 64 20 61 6c 6c 20 70 61  d to find all pa
26cb0 72 65 6e 74 73 20 6f 66 20 61 6e 79 0a 69 6e 64  rents of any.ind
26cc0 69 76 69 64 75 61 6c 2e 20 20 54 68 61 74 20 6f  ividual.  That o
26cd0 72 64 69 6e 61 72 79 20 43 54 45 20 69 73 20 74  rdinary CTE is t
26ce0 68 65 6e 20 75 73 65 64 20 69 6e 20 74 68 65 20  hen used in the 
26cf0 22 61 6e 63 65 73 74 6f 72 5f 6f 66 5f 61 6c 69  "ancestor_of_ali
26d00 63 65 22 0a 72 65 63 75 72 73 69 76 65 20 43 54  ce".recursive CT
26d10 45 2e 20 20 54 68 65 20 72 65 63 75 72 73 69 76  E.  The recursiv
26d20 65 20 43 54 45 20 69 73 20 74 68 65 6e 20 75 73  e CTE is then us
26d30 65 64 20 69 6e 20 74 68 65 20 66 69 6e 61 6c 20  ed in the final 
26d40 71 75 65 72 79 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  query:..<blockqu
26d50 6f 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52  ote><pre>.WITH R
26d60 45 43 55 52 53 49 56 45 0a 20 20 70 61 72 65 6e  ECURSIVE.  paren
26d70 74 5f 6f 66 28 6e 61 6d 65 2c 20 70 61 72 65 6e  t_of(name, paren
26d80 74 29 20 41 53 0a 20 20 20 20 28 53 45 4c 45 43  t) AS.    (SELEC
26d90 54 20 6e 61 6d 65 2c 20 6d 6f 6d 20 46 52 4f 4d  T name, mom FROM
26da0 20 66 61 6d 69 6c 79 20 55 4e 49 4f 4e 20 53 45   family UNION SE
26db0 4c 45 43 54 20 6e 61 6d 65 2c 20 64 61 64 20 46  LECT name, dad F
26dc0 52 4f 4d 20 66 61 6d 69 6c 79 29 2c 0a 20 20 61  ROM family),.  a
26dd0 6e 63 65 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65  ncestor_of_alice
26de0 28 6e 61 6d 65 29 20 41 53 0a 20 20 20 20 28 53  (name) AS.    (S
26df0 45 4c 45 43 54 20 70 61 72 65 6e 74 20 46 52 4f  ELECT parent FRO
26e00 4d 20 70 61 72 65 6e 74 5f 6f 66 20 57 48 45 52  M parent_of WHER
26e10 45 20 6e 61 6d 65 3d 27 41 6c 69 63 65 27 0a 20  E name='Alice'. 
26e20 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20      UNION ALL.  
26e30 20 20 20 53 45 4c 45 43 54 20 70 61 72 65 6e 74     SELECT parent
26e40 20 46 52 4f 4d 20 70 61 72 65 6e 74 5f 6f 66 20   FROM parent_of 
26e50 4a 4f 49 4e 20 61 6e 63 65 73 74 6f 72 5f 6f 66  JOIN ancestor_of
26e60 5f 61 6c 69 63 65 20 55 53 49 4e 47 28 6e 61 6d  _alice USING(nam
26e70 65 29 29 0a 53 45 4c 45 43 54 20 66 61 6d 69 6c  e)).SELECT famil
26e80 79 2e 6e 61 6d 65 20 46 52 4f 4d 20 61 6e 63 65  y.name FROM ance
26e90 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65 2c 20 66  stor_of_alice, f
26ea0 61 6d 69 6c 79 0a 20 57 48 45 52 45 20 61 6e 63  amily. WHERE anc
26eb0 65 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65 2e 6e  estor_of_alice.n
26ec0 61 6d 65 3d 66 61 6d 69 6c 79 2e 6e 61 6d 65 0a  ame=family.name.
26ed0 20 20 20 41 4e 44 20 64 69 65 64 20 49 53 20 4e     AND died IS N
26ee0 55 4c 4c 0a 20 4f 52 44 45 52 20 42 59 20 62 6f  ULL. ORDER BY bo
26ef0 72 6e 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  rn;.</pre></bloc
26f00 6b 71 75 6f 74 65 3e 0a 0a 3c 74 63 6c 3e 68 64  kquote>..<tcl>hd
26f10 5f 66 72 61 67 6d 65 6e 74 20 72 63 65 78 32 3c  _fragment rcex2<
26f20 2f 74 63 6c 3e 0a 3c 68 34 3e 51 75 65 72 69 65  /tcl>.<h4>Querie
26f30 73 20 41 67 61 69 6e 73 74 20 41 20 47 72 61 70  s Against A Grap
26f40 68 3c 2f 68 34 3e 0a 0a 3c 70 3e 41 20 76 65 72  h</h4>..<p>A ver
26f50 73 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 79 73  sion control sys
26f60 74 65 6d 20 28 56 43 53 29 20 77 69 6c 6c 20 74  tem (VCS) will t
26f70 79 70 69 63 61 6c 6c 79 20 73 74 6f 72 65 20 74  ypically store t
26f80 68 65 20 65 76 6f 6c 76 69 6e 67 0a 76 65 72 73  he evolving.vers
26f90 69 6f 6e 73 20 6f 66 20 61 20 70 72 6f 6a 65 63  ions of a projec
26fa0 74 20 61 73 20 61 20 64 69 72 65 63 74 65 64 20  t as a directed 
26fb0 61 63 79 63 6c 69 63 20 67 72 61 70 68 20 28 44  acyclic graph (D
26fc0 41 47 29 2e 20 20 43 61 6c 6c 20 65 61 63 68 0a  AG).  Call each.
26fd0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 70  version of the p
26fe0 72 6f 6a 65 63 74 20 61 20 22 63 68 65 63 6b 69  roject a "checki
26ff0 6e 22 2e 20 20 41 20 73 69 6e 67 6c 65 0a 63 68  n".  A single.ch
27000 65 63 6b 69 6e 20 63 61 6e 20 68 61 76 65 20 7a  eckin can have z
27010 65 72 6f 20 6f 72 20 6d 6f 72 65 20 70 61 72 65  ero or more pare
27020 6e 74 73 2e 20 20 4d 6f 73 74 20 63 68 65 63 6b  nts.  Most check
27030 69 6e 73 20 28 65 78 63 65 70 74 20 74 68 65 0a  ins (except the.
27040 66 69 72 73 74 29 20 68 61 76 65 20 61 20 73 69  first) have a si
27050 6e 67 6c 65 20 70 61 72 65 6e 74 2c 20 62 75 74  ngle parent, but
27060 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
27070 61 20 6d 65 72 67 65 2c 20 61 20 63 68 65 63 6b  a merge, a check
27080 69 6e 0a 6d 69 67 68 74 20 68 61 76 65 20 74 77  in.might have tw
27090 6f 20 6f 72 20 74 68 72 65 65 20 6f 72 20 6d 6f  o or three or mo
270a0 72 65 20 70 61 72 65 6e 74 73 2e 20 20 41 20 73  re parents.  A s
270b0 63 68 65 6d 61 20 74 6f 20 6b 65 65 70 20 74 72  chema to keep tr
270c0 61 63 6b 20 6f 66 0a 63 68 65 63 6b 69 6e 73 20  ack of.checkins 
270d0 61 6e 64 20 74 68 65 20 6f 72 64 65 72 20 69 6e  and the order in
270e0 20 77 68 69 63 68 20 74 68 65 79 20 6f 63 63 75   which they occu
270f0 72 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 73 6f 6d  r might look som
27100 65 74 68 69 6e 67 20 6c 69 6b 65 0a 74 68 69 73  ething like.this
27110 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  :..<blockquote><
27120 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c  pre>.CREATE TABL
27130 45 20 63 68 65 63 6b 69 6e 28 0a 20 20 69 64 20  E checkin(.  id 
27140 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
27150 4b 45 59 2c 0a 20 20 6d 74 69 6d 65 20 49 4e 54  KEY,.  mtime INT
27160 45 47 45 52 20 2d 2d 20 74 69 6d 65 73 74 61 6d  EGER -- timestam
27170 70 20 77 68 65 6e 20 74 68 69 73 20 63 68 65 63  p when this chec
27180 6b 69 6e 20 6f 63 63 75 72 72 65 64 0a 29 3b 0a  kin occurred.);.
27190 43 52 45 41 54 45 20 54 41 42 4c 45 20 64 65 72  CREATE TABLE der
271a0 69 76 65 64 66 72 6f 6d 28 0a 20 20 78 66 72 6f  ivedfrom(.  xfro
271b0 6d 20 49 4e 54 45 47 45 52 20 4e 4f 54 20 4e 55  m INTEGER NOT NU
271c0 4c 4c 20 52 45 46 45 52 45 4e 43 45 53 20 63 68  LL REFERENCES ch
271d0 65 63 6b 69 6e 2c 20 2d 2d 20 70 61 72 65 6e 74  eckin, -- parent
271e0 20 63 68 65 63 6b 69 6e 0a 20 20 78 74 6f 20 49   checkin.  xto I
271f0 4e 54 45 47 45 52 20 4e 4f 54 20 4e 55 4c 4c 20  NTEGER NOT NULL 
27200 52 45 46 45 52 45 4e 43 45 53 20 63 68 65 63 6b  REFERENCES check
27210 69 6e 2c 20 20 20 2d 2d 20 64 65 72 69 76 65 64  in,   -- derived
27220 20 63 68 65 63 6b 69 6e 0a 20 20 50 52 49 4d 41   checkin.  PRIMA
27230 52 59 20 4b 45 59 28 78 66 72 6f 6d 2c 78 74 6f  RY KEY(xfrom,xto
27240 29 0a 29 3b 0a 43 52 45 41 54 45 20 49 4e 44 45  ).);.CREATE INDE
27250 58 20 64 65 72 69 76 65 64 66 72 6f 6d 5f 62 61  X derivedfrom_ba
27260 63 6b 20 4f 4e 20 64 65 72 69 76 65 64 66 72 6f  ck ON derivedfro
27270 6d 28 78 74 6f 2c 78 66 72 6f 6d 29 3b 0a 3c 2f  m(xto,xfrom);.</
27280 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
27290 3e 0a 0a 3c 70 3e 54 68 69 73 20 67 72 61 70 68  >..<p>This graph
272a0 20 69 73 20 61 63 79 63 6c 69 63 2e 20 20 41 6e   is acyclic.  An
272b0 64 20 77 65 20 61 73 73 75 6d 65 20 74 68 61 74  d we assume that
272c0 20 74 68 65 20 6d 74 69 6d 65 20 6f 66 20 65 76   the mtime of ev
272d0 65 72 79 0a 63 68 69 6c 64 20 63 68 65 63 6b 69  ery.child checki
272e0 6e 20 69 73 20 6e 6f 20 6c 65 73 73 20 74 68 61  n is no less tha
272f0 6e 20 74 68 65 20 6d 74 69 6d 65 20 6f 66 20 61  n the mtime of a
27300 6c 6c 20 69 74 73 20 70 61 72 65 6e 74 73 2e 20  ll its parents. 
27310 20 42 75 74 0a 75 6e 6c 69 6b 65 20 74 68 65 20   But.unlike the 
27320 65 61 72 6c 69 65 72 20 65 78 61 6d 70 6c 65 73  earlier examples
27330 2c 20 74 68 69 73 20 67 72 61 70 68 20 6d 69 67  , this graph mig
27340 68 74 20 68 61 76 65 20 6d 75 6c 74 69 70 6c 65  ht have multiple
27350 20 70 61 74 68 73 20 6f 66 0a 64 69 66 66 65 72   paths of.differ
27360 69 6e 67 20 6c 65 6e 67 74 68 73 20 62 65 74 77  ing lengths betw
27370 65 65 6e 20 61 6e 79 20 74 77 6f 20 63 68 65 63  een any two chec
27380 6b 69 6e 73 2e 0a 0a 3c 70 3e 57 65 20 77 61 6e  kins...<p>We wan
27390 74 20 74 6f 20 6b 6e 6f 77 20 74 68 65 20 74 77  t to know the tw
273a0 65 6e 74 79 20 6d 6f 73 74 20 72 65 63 65 6e 74  enty most recent
273b0 20 61 6e 63 65 73 74 6f 72 73 20 69 6e 20 74 69   ancestors in ti
273c0 6d 65 20 28 6f 75 74 20 6f 66 0a 74 68 65 20 74  me (out of.the t
273d0 68 6f 75 73 61 6e 64 73 20 61 6e 64 20 74 68 6f  housands and tho
273e0 75 73 61 6e 64 73 20 6f 66 20 61 6e 63 65 73 74  usands of ancest
273f0 6f 72 73 20 69 6e 20 74 68 65 20 77 68 6f 6c 65  ors in the whole
27400 20 44 41 47 29 20 66 6f 72 0a 63 68 65 63 6b 69   DAG) for.checki
27410 6e 20 22 40 42 41 53 45 4c 49 4e 45 22 2e 20 20  n "@BASELINE".  
27420 28 41 20 71 75 65 72 79 20 73 69 6d 69 6c 61 72  (A query similar
27430 20 74 6f 20 74 68 69 73 20 69 73 20 75 73 65 64   to this is used
27440 0a 62 79 20 74 68 65 20 3c 61 20 68 72 65 66 3d  .by the <a href=
27450 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
27460 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73  il-scm.org/">Fos
27470 73 69 6c 3c 2f 61 3e 20 56 43 53 20 74 6f 0a 73  sil</a> VCS to.s
27480 68 6f 77 20 74 68 65 20 4e 20 6d 6f 73 74 20 72  how the N most r
27490 65 63 65 6e 74 20 61 6e 63 65 73 74 6f 72 73 20  ecent ancestors 
274a0 6f 66 20 61 20 63 68 65 63 6b 2e 20 20 46 6f 72  of a check.  For
274b0 20 65 78 61 6d 70 6c 65 3a 0a 3c 61 20 68 72 65   example:.<a hre
274c0 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71  f="http://www.sq
274d0 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 74 69 6d  lite.org/src/tim
274e0 65 6c 69 6e 65 3f 70 3d 74 72 75 6e 6b 26 6e 3d  eline?p=trunk&n=
274f0 33 30 22 3e 68 74 74 70 3a 2f 2f 77 77 77 2e 73  30">http://www.s
27500 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 74 69  qlite.org/src/ti
27510 6d 65 6c 69 6e 65 3f 70 3d 74 72 75 6e 6b 26 6e  meline?p=trunk&n
27520 3d 33 30 3c 2f 61 3e 2e 29 0a 0a 3c 62 6c 6f 63  =30</a>.)..<bloc
27530 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57 49 54  kquote><pre>.WIT
27540 48 20 52 45 43 55 52 53 49 56 45 0a 20 20 61 6e  H RECURSIVE.  an
27550 63 65 73 74 6f 72 28 69 64 2c 6d 74 69 6d 65 29  cestor(id,mtime)
27560 20 41 53 20 28 0a 20 20 20 20 53 45 4c 45 43 54   AS (.    SELECT
27570 20 69 64 2c 20 6d 74 69 6d 65 20 46 52 4f 4d 20   id, mtime FROM 
27580 63 68 65 63 6b 69 6e 20 57 48 45 52 45 20 69 64  checkin WHERE id
27590 3d 40 42 41 53 45 4c 49 4e 45 0a 20 20 20 20 55  =@BASELINE.    U
275a0 4e 49 4f 4e 0a 20 20 20 20 53 45 4c 45 43 54 20  NION.    SELECT 
275b0 64 65 72 69 76 65 64 66 72 6f 6d 2e 78 66 72 6f  derivedfrom.xfro
275c0 6d 2c 20 63 68 65 63 6b 69 6e 2e 6d 74 69 6d 65  m, checkin.mtime
275d0 0a 20 20 20 20 20 20 46 52 4f 4d 20 61 6e 63 65  .      FROM ance
275e0 73 74 6f 72 2c 20 64 65 72 69 76 65 64 66 72 6f  stor, derivedfro
275f0 6d 2c 20 63 68 65 63 6b 69 6e 0a 20 20 20 20 20  m, checkin.     
27600 57 48 45 52 45 20 61 6e 63 65 73 74 6f 72 2e 69  WHERE ancestor.i
27610 64 3d 64 65 72 69 76 65 64 66 72 6f 6d 2e 78 74  d=derivedfrom.xt
27620 6f 0a 20 20 20 20 20 20 20 41 4e 44 20 63 68 65  o.       AND che
27630 63 6b 69 6e 2e 69 64 3d 64 65 72 69 76 65 64 66  ckin.id=derivedf
27640 72 6f 6d 2e 78 66 72 6f 6d 0a 20 20 20 20 20 4f  rom.xfrom.     O
27650 52 44 45 52 20 42 59 20 63 68 65 63 6b 69 6e 2e  RDER BY checkin.
27660 6d 74 69 6d 65 20 44 45 53 43 0a 20 20 20 20 20  mtime DESC.     
27670 4c 49 4d 49 54 20 32 30 0a 20 20 29 0a 53 45 4c  LIMIT 20.  ).SEL
27680 45 43 54 20 2a 20 46 52 4f 4d 20 63 68 65 63 6b  ECT * FROM check
27690 69 6e 20 4a 4f 49 4e 20 61 6e 63 65 73 74 6f 72  in JOIN ancestor
276a0 20 55 53 49 4e 47 28 69 64 29 3b 0a 3c 2f 70 72   USING(id);.</pr
276b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
276c0 0a 3c 70 3e 0a 54 68 65 20 22 4f 52 44 45 52 20  .<p>.The "ORDER 
276d0 42 59 20 63 68 65 63 6b 69 6e 2e 6d 74 69 6d 65  BY checkin.mtime
276e0 20 44 45 53 43 22 20 74 65 72 6d 20 69 6e 20 74   DESC" term in t
276f0 68 65 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c  he recursive-sel
27700 65 63 74 20 6d 61 6b 65 73 0a 74 68 65 20 71 75  ect makes.the qu
27710 65 72 79 20 72 75 6e 20 6d 75 63 68 20 66 61 73  ery run much fas
27720 74 65 72 20 62 79 20 70 72 65 76 65 6e 74 69 6e  ter by preventin
27730 67 20 69 74 20 66 72 6f 6d 20 66 6f 6c 6c 6f 77  g it from follow
27740 69 6e 67 0a 62 72 61 6e 63 68 65 73 20 74 68 61  ing.branches tha
27750 74 20 6d 65 72 67 65 20 63 68 65 63 6b 69 6e 73  t merge checkins
27760 0a 66 72 6f 6d 20 6c 6f 6e 67 20 61 67 6f 2e 20  .from long ago. 
27770 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 66 6f   The ORDER BY fo
27780 72 63 65 73 20 74 68 65 20 72 65 63 75 72 73 69  rces the recursi
27790 76 65 2d 73 65 6c 65 63 74 20 74 6f 20 66 6f 63  ve-select to foc
277a0 75 73 0a 6f 6e 20 74 68 65 20 6d 6f 73 74 20 72  us.on the most r
277b0 65 63 65 6e 74 20 63 68 65 63 6b 69 6e 73 2c 20  ecent checkins, 
277c0 74 68 65 20 6f 6e 65 73 20 77 65 20 77 61 6e 74  the ones we want
277d0 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 4f  .  Without the O
277e0 52 44 45 52 20 42 59 0a 6f 6e 20 74 68 65 20 72  RDER BY.on the r
277f0 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 2c  ecursive-select,
27800 20 6f 6e 65 20 77 6f 75 6c 64 20 62 65 20 66 6f   one would be fo
27810 72 63 65 64 20 74 6f 20 63 6f 6d 70 75 74 65 20  rced to compute 
27820 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 73 65 74  the complete set
27830 20 6f 66 0a 74 68 6f 75 73 61 6e 64 73 20 6f 66   of.thousands of
27840 20 61 6e 63 65 73 74 6f 72 73 2c 20 73 6f 72 74   ancestors, sort
27850 20 74 68 65 6d 20 61 6c 6c 20 62 79 20 6d 74 69   them all by mti
27860 6d 65 2c 20 74 68 65 6e 20 74 61 6b 65 20 74 68  me, then take th
27870 65 20 74 6f 70 20 74 77 65 6e 74 79 2e 0a 54 68  e top twenty..Th
27880 65 20 4f 52 44 45 52 20 42 59 20 65 73 73 65 6e  e ORDER BY essen
27890 74 69 61 6c 6c 79 20 73 65 74 73 20 75 70 20 61  tially sets up a
278a0 20 70 72 69 6f 72 69 74 79 20 71 75 65 75 65 20   priority queue 
278b0 74 68 61 74 0a 66 6f 72 63 65 73 20 74 68 65 20  that.forces the 
278c0 72 65 63 75 72 73 69 76 65 20 71 75 65 72 79 20  recursive query 
278d0 74 6f 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 6d  to look at the m
278e0 6f 73 74 20 72 65 63 65 6e 74 20 61 6e 63 65 73  ost recent ances
278f0 74 6f 72 73 20 66 69 72 73 74 2c 0a 61 6c 6c 6f  tors first,.allo
27900 77 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  wing the use of 
27910 61 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 74  a LIMIT clause t
27920 6f 20 72 65 73 74 72 69 63 74 20 74 68 65 20 73  o restrict the s
27930 63 6f 70 65 20 6f 66 20 74 68 65 0a 71 75 65 72  cope of the.quer
27940 79 20 74 6f 20 6a 75 73 74 20 74 68 65 20 63 68  y to just the ch
27950 65 63 6b 69 6e 73 20 6f 66 20 69 6e 74 65 72 65  eckins of intere
27960 73 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  st...<tcl>hd_fra
27970 67 6d 65 6e 74 20 77 69 74 68 6f 72 64 65 72 62  gment withorderb
27980 79 3c 2f 74 63 6c 3e 0a 3c 68 34 3e 43 6f 6e 74  y</tcl>.<h4>Cont
27990 72 6f 6c 6c 69 6e 67 20 44 65 70 74 68 2d 46 69  rolling Depth-Fi
279a0 72 73 74 20 56 65 72 73 75 73 20 42 72 65 61 64  rst Versus Bread
279b0 74 68 2d 46 69 72 73 74 20 53 65 61 72 63 68 20  th-First Search 
279c0 4f 66 20 61 20 54 72 65 65 0a 55 73 69 6e 67 20  Of a Tree.Using 
279d0 4f 52 44 45 52 20 42 59 3c 2f 68 34 3e 0a 0a 3c  ORDER BY</h4>..<
279e0 70 3e 41 6e 20 4f 52 44 45 52 20 42 59 20 63 6c  p>An ORDER BY cl
279f0 61 75 73 65 20 6f 6e 20 74 68 65 20 72 65 63 75  ause on the recu
27a00 72 73 69 76 65 2d 73 65 6c 65 63 74 20 63 61 6e  rsive-select can
27a10 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 74   be used to cont
27a20 72 6f 6c 0a 77 68 65 74 68 65 72 20 74 68 65 20  rol.whether the 
27a30 73 65 61 72 63 68 20 6f 66 20 61 20 74 72 65 65  search of a tree
27a40 20 69 73 20 64 65 70 74 68 2d 66 69 72 73 74 20   is depth-first 
27a50 6f 72 20 62 72 65 61 64 74 68 2d 66 69 72 73 74  or breadth-first
27a60 2e 20 20 54 6f 0a 69 6c 6c 75 73 74 72 61 74 65  .  To.illustrate
27a70 2c 20 77 65 20 77 69 6c 6c 20 75 73 65 20 61 20  , we will use a 
27a80 76 61 72 69 61 74 69 6f 6e 20 6f 6e 20 74 68 65  variation on the
27a90 20 22 6f 72 67 22 20 74 61 62 6c 65 20 66 72 6f   "org" table fro
27aa0 6d 20 61 6e 20 65 78 61 6d 70 6c 65 0a 61 62 6f  m an example.abo
27ab0 76 65 2c 20 77 69 74 68 6f 75 74 20 74 68 65 20  ve, without the 
27ac0 22 68 65 69 67 68 74 22 20 63 6f 6c 75 6d 6e 2c  "height" column,
27ad0 20 61 6e 64 20 77 69 74 68 20 73 6f 6d 65 20 72   and with some r
27ae0 65 61 6c 20 64 61 74 61 20 69 6e 73 65 72 74 65  eal data inserte
27af0 64 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  d:..<blockquote>
27b00 3c 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42  <pre>.CREATE TAB
27b10 4c 45 20 6f 72 67 28 0a 20 20 6e 61 6d 65 20 54  LE org(.  name T
27b20 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  EXT PRIMARY KEY,
27b30 0a 20 20 62 6f 73 73 20 54 45 58 54 20 52 45 46  .  boss TEXT REF
27b40 45 52 45 4e 43 45 53 20 6f 72 67 0a 29 20 57 49  ERENCES org.) WI
27b50 54 48 4f 55 54 20 52 4f 57 49 44 3b 0a 49 4e 53  THOUT ROWID;.INS
27b60 45 52 54 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c  ERT INTO org VAL
27b70 55 45 53 28 27 41 6c 69 63 65 27 2c 4e 55 4c 4c  UES('Alice',NULL
27b80 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f  );.INSERT INTO o
27b90 72 67 20 56 41 4c 55 45 53 28 27 42 6f 62 27 2c  rg VALUES('Bob',
27ba0 27 41 6c 69 63 65 27 29 3b 0a 49 4e 53 45 52 54  'Alice');.INSERT
27bb0 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c 55 45 53   INTO org VALUES
27bc0 28 27 43 69 6e 64 79 27 2c 27 41 6c 69 63 65 27  ('Cindy','Alice'
27bd0 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f  );.INSERT INTO o
27be0 72 67 20 56 41 4c 55 45 53 28 27 44 61 76 65 27  rg VALUES('Dave'
27bf0 2c 27 42 6f 62 27 29 3b 0a 49 4e 53 45 52 54 20  ,'Bob');.INSERT 
27c00 49 4e 54 4f 20 6f 72 67 20 56 41 4c 55 45 53 28  INTO org VALUES(
27c10 27 45 6d 6d 61 27 2c 27 42 6f 62 27 29 3b 0a 49  'Emma','Bob');.I
27c20 4e 53 45 52 54 20 49 4e 54 4f 20 6f 72 67 20 56  NSERT INTO org V
27c30 41 4c 55 45 53 28 27 46 72 65 64 27 2c 27 43 69  ALUES('Fred','Ci
27c40 6e 64 79 27 29 3b 0a 49 4e 53 45 52 54 20 49 4e  ndy');.INSERT IN
27c50 54 4f 20 6f 72 67 20 56 41 4c 55 45 53 28 27 47  TO org VALUES('G
27c60 61 69 6c 27 2c 27 43 69 6e 64 79 27 29 3b 0a 3c  ail','Cindy');.<
27c70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
27c80 65 3e 0a 0a 3c 70 3e 48 65 72 65 20 69 73 20 61  e>..<p>Here is a
27c90 20 71 75 65 72 79 20 74 6f 20 73 68 6f 77 20 74   query to show t
27ca0 68 65 20 74 72 65 65 20 73 74 72 75 63 74 75 72  he tree structur
27cb0 65 20 69 6e 20 61 20 62 72 65 61 64 74 68 2d 66  e in a breadth-f
27cc0 69 72 73 74 20 70 61 74 74 65 72 6e 3a 0a 0a 3c  irst pattern:..<
27cd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
27ce0 0a 57 49 54 48 20 52 45 43 55 52 53 49 56 45 0a  .WITH RECURSIVE.
27cf0 20 20 75 6e 64 65 72 5f 61 6c 69 63 65 28 6e 61    under_alice(na
27d00 6d 65 2c 6c 65 76 65 6c 29 20 41 53 20 28 0a 20  me,level) AS (. 
27d10 20 20 20 56 41 4c 55 45 53 28 27 41 6c 69 63 65     VALUES('Alice
27d20 27 2c 30 29 0a 20 20 20 20 55 4e 49 4f 4e 20 41  ',0).    UNION A
27d30 4c 4c 0a 20 20 20 20 53 45 4c 45 43 54 20 6f 72  LL.    SELECT or
27d40 67 2e 6e 61 6d 65 2c 20 75 6e 64 65 72 5f 61 6c  g.name, under_al
27d50 69 63 65 2e 6c 65 76 65 6c 2b 31 0a 20 20 20 20  ice.level+1.    
27d60 20 20 46 52 4f 4d 20 6f 72 67 20 4a 4f 49 4e 20    FROM org JOIN 
27d70 75 6e 64 65 72 5f 61 6c 69 63 65 20 4f 4e 20 6f  under_alice ON o
27d80 72 67 2e 62 6f 73 73 3d 75 6e 64 65 72 5f 61 6c  rg.boss=under_al
27d90 69 63 65 2e 6e 61 6d 65 0a 20 20 20 20 20 4f 52  ice.name.     OR
27da0 44 45 52 20 42 59 20 32 0a 20 20 29 0a 53 45 4c  DER BY 2.  ).SEL
27db0 45 43 54 20 73 75 62 73 74 72 28 27 2e 2e 2e 2e  ECT substr('....
27dc0 2e 2e 2e 2e 2e 2e 27 2c 31 2c 6c 65 76 65 6c 2a  ......',1,level*
27dd0 33 29 20 7c 7c 20 6e 61 6d 65 20 46 52 4f 4d 20  3) || name FROM 
27de0 75 6e 64 65 72 5f 61 6c 69 63 65 3b 0a 3c 2f 70  under_alice;.</p
27df0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
27e00 0a 0a 3c 70 3e 54 68 65 20 22 4f 52 44 45 52 20  ..<p>The "ORDER 
27e10 42 59 20 32 22 20 28 77 68 69 63 68 20 6d 65 61  BY 2" (which mea
27e20 6e 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 22  ns the same as "
27e30 4f 52 44 45 52 20 42 59 20 75 6e 64 65 72 5f 61  ORDER BY under_a
27e40 6c 69 63 65 2e 6c 65 76 65 6c 2b 31 22 29 0a 63  lice.level+1").c
27e50 61 75 73 65 73 20 68 69 67 68 65 72 20 6c 65 76  auses higher lev
27e60 65 6c 73 20 69 6e 20 74 68 65 20 6f 72 67 61 6e  els in the organ
27e70 69 7a 61 74 69 6f 6e 20 63 68 61 72 74 20 28 77  ization chart (w
27e80 69 74 68 20 73 6d 61 6c 6c 65 72 20 22 6c 65 76  ith smaller "lev
27e90 65 6c 22 20 76 61 6c 75 65 73 29 0a 74 6f 20 62  el" values).to b
27ea0 65 20 70 72 6f 63 65 73 73 65 64 20 66 69 72 73  e processed firs
27eb0 74 2c 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 20  t, resulting in 
27ec0 61 20 62 72 65 61 64 74 68 2d 66 69 72 73 74 20  a breadth-first 
27ed0 73 65 61 72 63 68 2e 20 20 54 68 65 20 6f 75 74  search.  The out
27ee0 70 75 74 20 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71  put is:..<blockq
27ef0 75 6f 74 65 3e 3c 70 72 65 3e 0a 41 6c 69 63 65  uote><pre>.Alice
27f00 0a 2e 2e 2e 42 6f 62 0a 2e 2e 2e 43 69 6e 64 79  ....Bob....Cindy
27f10 0a 2e 2e 2e 2e 2e 2e 44 61 76 65 0a 2e 2e 2e 2e  .......Dave.....
27f20 2e 2e 45 6d 6d 61 0a 2e 2e 2e 2e 2e 2e 46 72 65  ..Emma.......Fre
27f30 64 0a 2e 2e 2e 2e 2e 2e 47 61 69 6c 0a 3c 2f 70  d.......Gail.</p
27f40 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
27f50 0a 0a 3c 70 3e 42 75 74 20 69 66 20 77 65 20 63  ..<p>But if we c
27f60 68 61 6e 67 65 20 74 68 65 20 4f 52 44 45 52 20  hange the ORDER 
27f70 42 59 20 63 6c 61 75 73 65 20 74 6f 20 61 64 64  BY clause to add
27f80 20 74 68 65 20 22 44 45 53 43 22 20 6d 6f 64 69   the "DESC" modi
27f90 66 69 65 72 2c 20 74 68 61 74 20 77 69 6c 6c 0a  fier, that will.
27fa0 63 61 75 73 65 20 6c 6f 77 65 72 20 6c 65 76 65  cause lower leve
27fb0 6c 73 20 69 6e 20 74 68 65 20 6f 72 67 61 6e 69  ls in the organi
27fc0 7a 61 74 69 6f 6e 20 28 77 69 74 68 20 6c 61 72  zation (with lar
27fd0 67 65 72 20 22 6c 65 76 65 6c 22 20 76 61 6c 75  ger "level" valu
27fe0 65 73 29 20 74 6f 20 62 65 0a 70 72 6f 63 65 73  es) to be.proces
27ff0 73 65 64 20 66 69 72 73 74 20 62 79 20 74 68 65  sed first by the
28000 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63   recursive-selec
28010 74 2c 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 20  t, resulting in 
28020 61 20 64 65 70 74 68 2d 66 69 72 73 74 20 73 65  a depth-first se
28030 61 72 63 68 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  arch:..<blockquo
28040 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45  te><pre>.WITH RE
28050 43 55 52 53 49 56 45 0a 20 20 75 6e 64 65 72 5f  CURSIVE.  under_
28060 61 6c 69 63 65 28 6e 61 6d 65 2c 6c 65 76 65 6c  alice(name,level
28070 29 20 41 53 20 28 0a 20 20 20 20 56 41 4c 55 45  ) AS (.    VALUE
28080 53 28 27 41 6c 69 63 65 27 2c 30 29 0a 20 20 20  S('Alice',0).   
28090 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20 53   UNION ALL.    S
280a0 45 4c 45 43 54 20 6f 72 67 2e 6e 61 6d 65 2c 20  ELECT org.name, 
280b0 75 6e 64 65 72 5f 61 6c 69 63 65 2e 6c 65 76 65  under_alice.leve
280c0 6c 2b 31 0a 20 20 20 20 20 20 46 52 4f 4d 20 6f  l+1.      FROM o
280d0 72 67 20 4a 4f 49 4e 20 75 6e 64 65 72 5f 61 6c  rg JOIN under_al
280e0 69 63 65 20 4f 4e 20 6f 72 67 2e 62 6f 73 73 3d  ice ON org.boss=
280f0 75 6e 64 65 72 5f 61 6c 69 63 65 2e 6e 61 6d 65  under_alice.name
28100 0a 20 20 20 20 20 4f 52 44 45 52 20 42 59 20 32  .     ORDER BY 2
28110 20 3c 62 3e 44 45 53 43 3c 2f 62 3e 0a 20 20 29   <b>DESC</b>.  )
28120 0a 53 45 4c 45 43 54 20 73 75 62 73 74 72 28 27  .SELECT substr('
28130 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 27 2c 31 2c 6c 65  ..........',1,le
28140 76 65 6c 2a 33 29 20 7c 7c 20 6e 61 6d 65 20 46  vel*3) || name F
28150 52 4f 4d 20 75 6e 64 65 72 5f 61 6c 69 63 65 3b  ROM under_alice;
28160 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
28170 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6f 75 74  ote>..<p>The out
28180 70 75 74 20 6f 66 20 74 68 69 73 20 72 65 76 69  put of this revi
28190 73 65 64 20 71 75 65 72 79 20 69 73 3a 0a 0a 3c  sed query is:..<
281a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
281b0 0a 41 6c 69 63 65 0a 2e 2e 2e 42 6f 62 0a 2e 2e  .Alice....Bob...
281c0 2e 2e 2e 2e 44 61 76 65 0a 2e 2e 2e 2e 2e 2e 45  ....Dave.......E
281d0 6d 6d 61 0a 2e 2e 2e 43 69 6e 64 79 0a 2e 2e 2e  mma....Cindy....
281e0 2e 2e 2e 46 72 65 64 0a 2e 2e 2e 2e 2e 2e 47 61  ...Fred.......Ga
281f0 69 6c 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  il.</pre></block
28200 71 75 6f 74 65 3e 0a 0a 3c 70 3e 57 68 65 6e 20  quote>..<p>When 
28210 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
28220 75 73 65 20 69 73 20 6f 6d 69 74 74 65 64 20 66  use is omitted f
28230 72 6f 6d 20 74 68 65 20 72 65 63 75 72 73 69 76  rom the recursiv
28240 65 2d 73 65 6c 65 63 74 2c 20 74 68 65 0a 71 75  e-select, the.qu
28250 65 75 65 20 62 65 68 61 76 65 73 20 61 73 20 61  eue behaves as a
28260 20 46 49 46 4f 2c 20 77 68 69 63 68 20 72 65 73   FIFO, which res
28270 75 6c 74 73 20 69 6e 20 61 20 62 72 65 61 64 74  ults in a breadt
28280 68 2d 66 69 72 73 74 20 73 65 61 72 63 68 2e 0a  h-first search..
28290 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
282a0 6e 74 20 6d 61 6e 64 65 6c 62 72 6f 74 20 7b 63  nt mandelbrot {c
282b0 6f 6d 70 75 74 65 20 74 68 65 20 4d 61 6e 64 65  ompute the Mande
282c0 6c 62 72 6f 74 20 73 65 74 7d 3c 2f 74 63 6c 3e  lbrot set}</tcl>
282d0 0a 3c 68 34 3e 4f 75 74 6c 61 6e 64 69 73 68 20  .<h4>Outlandish 
282e0 52 65 63 75 72 73 69 76 65 20 51 75 65 72 79 20  Recursive Query 
282f0 45 78 61 6d 70 6c 65 73 3c 2f 68 34 3e 0a 0a 3c  Examples</h4>..<
28300 70 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  p>The following 
28310 71 75 65 72 79 20 63 6f 6d 70 75 74 65 73 20 61  query computes a
28320 6e 20 61 70 70 72 6f 78 69 6d 61 74 69 6f 6e 20  n approximation 
28330 6f 66 20 74 68 65 20 4d 61 6e 64 65 6c 62 72 6f  of the Mandelbro
28340 74 20 53 65 74 0a 61 6e 64 20 6f 75 74 70 75 74  t Set.and output
28350 73 20 74 68 65 20 72 65 73 75 6c 74 20 61 73 20  s the result as 
28360 41 53 43 49 49 2d 61 72 74 3a 0a 0a 3c 62 6c 6f  ASCII-art:..<blo
28370 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57 49  ckquote><pre>.WI
28380 54 48 20 52 45 43 55 52 53 49 56 45 0a 20 20 78  TH RECURSIVE.  x
28390 61 78 69 73 28 78 29 20 41 53 20 28 56 41 4c 55  axis(x) AS (VALU
283a0 45 53 28 2d 32 2e 30 29 20 55 4e 49 4f 4e 20 41  ES(-2.0) UNION A
283b0 4c 4c 20 53 45 4c 45 43 54 20 78 2b 30 2e 30 35  LL SELECT x+0.05
283c0 20 46 52 4f 4d 20 78 61 78 69 73 20 57 48 45 52   FROM xaxis WHER
283d0 45 20 78 26 6c 74 3b 31 2e 32 29 2c 0a 20 20 79  E x&lt;1.2),.  y
283e0 61 78 69 73 28 79 29 20 41 53 20 28 56 41 4c 55  axis(y) AS (VALU
283f0 45 53 28 2d 31 2e 30 29 20 55 4e 49 4f 4e 20 41  ES(-1.0) UNION A
28400 4c 4c 20 53 45 4c 45 43 54 20 79 2b 30 2e 31 20  LL SELECT y+0.1 
28410 46 52 4f 4d 20 79 61 78 69 73 20 57 48 45 52 45  FROM yaxis WHERE
28420 20 79 26 6c 74 3b 31 2e 30 29 2c 0a 20 20 6d 28   y&lt;1.0),.  m(
28430 69 74 65 72 2c 20 63 78 2c 20 63 79 2c 20 78 2c  iter, cx, cy, x,
28440 20 79 29 20 41 53 20 28 0a 20 20 20 20 53 45 4c   y) AS (.    SEL
28450 45 43 54 20 30 2c 20 78 2c 20 79 2c 20 30 2e 30  ECT 0, x, y, 0.0
28460 2c 20 30 2e 30 20 46 52 4f 4d 20 78 61 78 69 73  , 0.0 FROM xaxis
28470 2c 20 79 61 78 69 73 0a 20 20 20 20 55 4e 49 4f  , yaxis.    UNIO
28480 4e 20 41 4c 4c 0a 20 20 20 20 53 45 4c 45 43 54  N ALL.    SELECT
28490 20 69 74 65 72 2b 31 2c 20 63 78 2c 20 63 79 2c   iter+1, cx, cy,
284a0 20 78 2a 78 2d 79 2a 79 20 2b 20 63 78 2c 20 32   x*x-y*y + cx, 2
284b0 2e 30 2a 78 2a 79 20 2b 20 63 79 20 46 52 4f 4d  .0*x*y + cy FROM
284c0 20 6d 20 0a 20 20 20 20 20 57 48 45 52 45 20 28   m .     WHERE (
284d0 78 2a 78 20 2b 20 79 2a 79 29 20 26 6c 74 3b 20  x*x + y*y) &lt; 
284e0 34 2e 30 20 41 4e 44 20 69 74 65 72 26 6c 74 3b  4.0 AND iter&lt;
284f0 32 38 0a 20 20 29 2c 0a 20 20 6d 32 28 69 74 65  28.  ),.  m2(ite
28500 72 2c 20 63 78 2c 20 63 79 29 20 41 53 20 28 0a  r, cx, cy) AS (.
28510 20 20 20 20 53 45 4c 45 43 54 20 6d 61 78 28 69      SELECT max(i
28520 74 65 72 29 2c 20 63 78 2c 20 63 79 20 46 52 4f  ter), cx, cy FRO
28530 4d 20 6d 20 47 52 4f 55 50 20 42 59 20 63 78 2c  M m GROUP BY cx,
28540 20 63 79 0a 20 20 29 2c 0a 20 20 61 28 74 29 20   cy.  ),.  a(t) 
28550 41 53 20 28 0a 20 20 20 20 53 45 4c 45 43 54 20  AS (.    SELECT 
28560 67 72 6f 75 70 5f 63 6f 6e 63 61 74 28 20 73 75  group_concat( su
28570 62 73 74 72 28 27 20 2e 2b 2a 23 27 2c 20 31 2b  bstr(' .+*#', 1+
28580 6d 69 6e 28 69 74 65 72 2f 37 2c 34 29 2c 20 31  min(iter/7,4), 1
28590 29 2c 20 27 27 29 20 0a 20 20 20 20 46 52 4f 4d  ), '') .    FROM
285a0 20 6d 32 20 47 52 4f 55 50 20 42 59 20 63 79 0a   m2 GROUP BY cy.
285b0 20 20 29 0a 53 45 4c 45 43 54 20 67 72 6f 75 70    ).SELECT group
285c0 5f 63 6f 6e 63 61 74 28 72 74 72 69 6d 28 74 29  _concat(rtrim(t)
285d0 2c 78 27 30 61 27 29 20 46 52 4f 4d 20 61 3b 0a  ,x'0a') FROM a;.
285e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
285f0 74 65 3e 0a 0a 3c 70 3e 49 6e 20 74 68 69 73 20  te>..<p>In this 
28600 71 75 65 72 79 2c 20 74 68 65 20 22 78 61 78 69  query, the "xaxi
28610 73 22 20 61 6e 64 20 22 79 61 78 69 73 22 20 43  s" and "yaxis" C
28620 54 45 73 20 64 65 66 69 6e 65 20 74 68 65 20 67  TEs define the g
28630 72 69 64 20 6f 66 20 70 6f 69 6e 74 73 20 66 6f  rid of points fo
28640 72 0a 77 68 69 63 68 20 74 68 65 20 4d 61 6e 64  r.which the Mand
28650 65 6c 62 72 6f 74 20 53 65 74 20 77 69 6c 6c 20  elbrot Set will 
28660 62 65 20 61 70 70 72 6f 78 69 6d 61 74 65 64 2e  be approximated.
28670 20 20 45 61 63 68 20 72 6f 77 20 69 6e 20 74 68    Each row in th
28680 65 0a 22 6d 28 69 74 65 72 2c 63 78 2c 63 79 2c  e."m(iter,cx,cy,
28690 78 2c 79 29 22 20 43 54 45 20 6d 65 61 6e 73 20  x,y)" CTE means 
286a0 74 68 61 74 20 61 66 74 65 72 20 22 69 74 65 72  that after "iter
286b0 22 20 69 74 65 72 61 74 69 6f 6e 73 2c 20 74 68  " iterations, th
286c0 65 20 4d 61 6e 64 65 6c 62 72 6f 74 0a 69 74 65  e Mandelbrot.ite
286d0 72 61 74 69 6f 6e 20 73 74 61 72 74 69 6e 67 20  ration starting 
286e0 61 74 20 63 78 2c 63 79 20 68 61 73 20 72 65 61  at cx,cy has rea
286f0 63 68 65 64 20 70 6f 69 6e 74 20 78 2c 79 2e 20  ched point x,y. 
28700 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 69   The number of i
28710 74 65 72 61 74 69 6f 6e 73 0a 69 6e 20 74 68 69  terations.in thi
28720 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6c 69 6d  s example is lim
28730 69 74 65 64 20 74 6f 20 32 38 20 28 77 68 69 63  ited to 28 (whic
28740 68 20 73 65 76 65 72 65 6c 79 20 6c 69 6d 69 74  h severely limit
28750 73 20 74 68 65 20 72 65 73 6f 6c 75 74 69 6f 6e  s the resolution
28760 20 6f 66 0a 74 68 65 20 63 6f 6d 70 75 74 61 74   of.the computat
28770 69 6f 6e 2c 20 62 75 74 20 69 73 20 73 75 66 66  ion, but is suff
28780 69 63 69 65 6e 74 20 66 6f 72 20 6c 6f 77 2d 72  icient for low-r
28790 65 73 6f 6c 75 74 69 6f 6e 20 41 53 43 49 49 2d  esolution ASCII-
287a0 61 72 74 20 6f 75 74 70 75 74 29 2e 0a 54 68 65  art output)..The
287b0 20 22 6d 32 28 69 74 65 72 2c 63 78 2c 63 79 29   "m2(iter,cx,cy)
287c0 22 20 43 54 45 20 68 6f 6c 64 73 20 74 68 65 20  " CTE holds the 
287d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
287e0 66 20 69 74 65 72 61 74 69 6f 6e 73 20 72 65 61  f iterations rea
287f0 63 68 65 64 20 77 68 65 6e 0a 73 74 61 72 74 69  ched when.starti
28800 6e 67 20 61 74 20 70 6f 69 6e 74 20 63 78 2c 63  ng at point cx,c
28810 79 2e 0a 46 69 6e 61 6c 6c 79 2c 20 65 61 63 68  y..Finally, each
28820 20 72 6f 77 20 69 6e 20 74 68 65 20 22 61 28 74   row in the "a(t
28830 29 22 20 43 54 45 20 68 6f 6c 64 73 20 61 20 73  )" CTE holds a s
28840 74 72 69 6e 67 20 0a 77 68 69 63 68 20 69 73 20  tring .which is 
28850 61 20 73 69 6e 67 6c 65 20 6c 69 6e 65 20 6f 66  a single line of
28860 20 74 68 65 20 6f 75 74 70 75 74 20 41 53 43 49   the output ASCI
28870 49 2d 61 72 74 2e 0a 54 68 65 20 53 45 4c 45 43  I-art..The SELEC
28880 54 20 73 74 61 74 65 6d 65 6e 74 20 61 74 20 74  T statement at t
28890 68 65 20 65 6e 64 20 6a 75 73 74 20 71 75 65 72  he end just quer
288a0 69 65 73 20 74 68 65 20 22 61 22 20 43 54 45 20  ies the "a" CTE 
288b0 74 6f 0a 72 65 74 72 69 65 76 65 20 61 6c 6c 20  to.retrieve all 
288c0 6c 69 6e 65 73 20 6f 66 20 41 53 43 49 49 2d 61  lines of ASCII-a
288d0 72 74 2c 20 6f 6e 65 20 62 79 20 6f 6e 65 2e 0a  rt, one by one..
288e0 0a 3c 70 3e 52 75 6e 6e 69 6e 67 20 74 68 65 20  .<p>Running the 
288f0 71 75 65 72 79 20 61 62 6f 76 65 20 69 6e 20 61  query above in a
28900 6e 20 53 51 4c 69 74 65 20 5b 63 6f 6d 6d 61 6e  n SQLite [comman
28910 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 5d 20 72 65  d-line shell] re
28920 73 75 6c 74 73 0a 69 6e 20 74 68 65 20 66 6f 6c  sults.in the fol
28930 6c 6f 77 69 6e 67 20 6f 75 74 70 75 74 3a 0a 0a  lowing output:..
28940 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
28950 3e 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  >.              
28960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28970 20 20 20 20 20 20 2e 2e 2e 2e 23 0a 20 20 20 20        ....#.    
28980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e                 .
289a0 2e 23 2a 2e 2e 0a 20 20 20 20 20 20 20 20 20 20  .#*...          
289b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
289c0 20 20 20 20 20 20 20 2e 2e 2b 23 23 23 23 2b 2e         ..+####+.
289d0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
289e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e               ...
289f0 2e 2e 2e 2e 2b 23 23 23 23 2e 2e 2e 2e 20 20 20  ....+####....   
28a00 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  +.              
28a10 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 23               ..#
28a20 23 2b 2a 23 23 23 23 23 23 23 23 23 23 2b 2e 2b  #+*##########+.+
28a30 2b 2b 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20  +++.            
28a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2b                .+
28a50 2e 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
28a60 23 23 23 2b 2e 0a 20 20 20 20 20 20 20 20 20 20  ###+..          
28a70 20 20 20 20 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e      ............
28a80 2e 2b 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .+##############
28a90 23 23 23 23 23 2b 2e 2b 0a 20 20 20 20 20 20 20  #####+.+.       
28aa0 20 20 20 20 20 20 20 2e 2e 2b 2b 2e 2e 23 2e 2e         ..++..#..
28ab0 2e 2e 2e 2a 23 23 23 23 23 23 23 23 23 23 23 23  ...*############
28ac0 23 23 23 23 23 23 23 23 23 2b 2e 0a 20 20 20 20  #########+..    
28ad0 20 20 20 20 20 20 20 20 20 2e 2e 2e 2b 23 23 23           ...+###
28ae0 23 23 23 23 2b 2b 23 23 23 23 23 23 23 23 23 23  ####++##########
28af0 23 23 23 23 23 23 23 23 23 23 23 23 23 2e 0a 20  #############.. 
28b00 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e 2b 2a 23           ....+*#
28b10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28b20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 2e  ###############.
28b30 0a 20 23 23 23 23 23 23 23 23 23 23 23 23 23 23  . ##############
28b40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28b50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 2e  ###############.
28b60 2e 2e 0a 20 20 20 20 20 20 20 20 20 20 2e 2e 2e  ...          ...
28b70 2e 2b 2a 23 23 23 23 23 23 23 23 23 23 23 23 23  .+*#############
28b80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28b90 23 23 23 2e 0a 20 20 20 20 20 20 20 20 20 20 20  ###..           
28ba0 20 20 2e 2e 2e 2b 23 23 23 23 23 23 23 2b 2b 23    ...+#######++#
28bb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28bc0 23 23 23 23 23 23 2e 0a 20 20 20 20 20 20 20 20  ######..        
28bd0 20 20 20 20 20 20 2e 2e 2b 2b 2e 2e 23 2e 2e 2e        ..++..#...
28be0 2e 2e 2a 23 23 23 23 23 23 23 23 23 23 23 23 23  ..*#############
28bf0 23 23 23 23 23 23 23 23 2b 2e 0a 20 20 20 20 20  ########+..     
28c00 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e 2e 2e 2e           .......
28c10 2e 2e 2e 2e 2e 2e 2b 23 23 23 23 23 23 23 23 23  ......+#########
28c20 23 23 23 23 23 23 23 23 23 23 2b 2e 2b 0a 20 20  ##########+.+.  
28c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28c40 20 20 20 20 20 20 20 20 2e 2b 2e 23 23 23 23 23          .+.#####
28c50 23 23 23 23 23 23 23 23 23 23 23 23 23 2b 2e 0a  #############+..
28c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28c70 20 20 20 20 20 20 20 20 20 20 20 2e 2e 23 23 2b             ..##+
28c80 2a 23 23 23 23 23 23 23 23 23 23 2b 2e 2b 2b 2b  *##########+.+++
28c90 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  +.              
28ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e                ..
28cb0 2e 2e 2e 2e 2e 2b 23 23 23 23 2e 2e 2e 2e 20 20  .....+####....  
28cc0 20 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20   +.             
28cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28ce0 20 20 20 20 2e 2e 2b 23 23 23 23 2b 2e 0a 20 20      ..+####+..  
28cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d10 20 2e 2e 23 2a 2e 2e 0a 20 20 20 20 20 20 20 20   ..#*...        
28d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d30 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e              ....
28d40 23 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  #.              
28d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d60 20 20 20 20 20 20 2b 2e 0a 3c 2f 70 72 65 3e 3c        +..</pre><
28d70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 74  /blockquote>..<t
28d80 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 73  cl>hd_fragment s
28d90 75 64 6f 6b 75 20 7b 73 6f 6c 76 65 20 53 75 64  udoku {solve Sud
28da0 6f 6b 75 20 70 75 7a 7a 6c 65 73 7d 20 3c 2f 74  oku puzzles} </t
28db0 63 6c 3e 0a 3c 70 3e 54 68 69 73 20 6e 65 78 74  cl>.<p>This next
28dc0 20 71 75 65 72 79 20 73 6f 6c 76 65 73 20 61 20   query solves a 
28dd0 53 75 64 6f 6b 75 20 70 75 7a 7a 6c 65 2e 20 20  Sudoku puzzle.  
28de0 54 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  The state of the
28df0 20 70 75 7a 7a 6c 65 20 69 73 0a 64 65 66 69 6e   puzzle is.defin
28e00 65 64 20 62 79 20 61 6e 20 38 31 2d 63 68 61 72  ed by an 81-char
28e10 61 63 74 65 72 20 73 74 72 69 6e 67 20 66 6f 72  acter string for
28e20 6d 65 64 20 62 79 20 72 65 61 64 69 6e 67 20 65  med by reading e
28e30 6e 74 72 69 65 73 20 66 72 6f 6d 20 74 68 65 0a  ntries from the.
28e40 70 75 7a 7a 6c 65 20 62 6f 78 20 72 6f 77 20 62  puzzle box row b
28e50 79 20 72 6f 77 20 66 72 6f 6d 20 6c 65 66 74 20  y row from left 
28e60 74 6f 20 72 69 67 68 74 20 61 6e 64 20 74 68 65  to right and the
28e70 6e 20 66 72 6f 6d 20 74 6f 70 20 74 6f 20 62 6f  n from top to bo
28e80 74 74 6f 6d 2e 0a 42 6c 61 6e 6b 20 73 71 75 61  ttom..Blank squa
28e90 72 65 73 20 69 6e 20 74 68 65 20 70 75 7a 7a 6c  res in the puzzl
28ea0 65 20 61 72 65 20 64 65 6e 6f 74 65 64 20 62 79  e are denoted by
28eb0 20 61 20 22 2e 22 20 63 68 61 72 61 63 74 65 72   a "." character
28ec0 2e 20 20 0a 54 68 75 73 20 74 68 65 20 69 6e 70  .  .Thus the inp
28ed0 75 74 20 73 74 72 69 6e 67 3a 0a 0a 3c 62 6c 6f  ut string:..<blo
28ee0 63 6b 71 75 6f 74 65 3e 0a 35 33 2e 2e 37 2e 2e  ckquote>.53..7..
28ef0 2e 2e 36 2e 2e 31 39 35 2e 2e 2e 2e 39 38 2e 2e  ..6..195....98..
28f00 2e 2e 36 2e 38 2e 2e 2e 36 2e 2e 2e 33 34 2e 2e  ..6.8...6...34..
28f10 38 2e 33 2e 2e 31 37 2e 2e 2e 32 2e 2e 2e 36 2e  8.3..17...2...6.
28f20 36 2e 2e 2e 2e 32 38 2e 2e 2e 2e 34 31 39 2e 2e  6....28....419..
28f30 35 2e 2e 2e 2e 38 2e 2e 37 39 0a 3c 2f 62 6c 6f  5....8..79.</blo
28f40 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 43 6f 72  ckquote>..<p>Cor
28f50 72 65 73 70 6f 6e 64 73 20 74 6f 20 61 20 70 75  responds to a pu
28f60 7a 7a 6c 65 20 6c 69 6b 65 20 74 68 69 73 3a 0a  zzle like this:.
28f70 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 74  .<blockquote>.<t
28f80 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
28f90 63 65 6c 6c 70 61 64 64 69 6e 67 3d 22 35 22 3e  cellpadding="5">
28fa0 0a 3c 74 72 3e 3c 74 64 3e 35 3c 74 64 3e 33 3c  .<tr><td>5<td>3<
28fb0 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 37 3c 74  td> <td> <td>7<t
28fc0 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64  d> <td> <td> <td
28fd0 3e 0a 3c 74 72 3e 3c 74 64 3e 36 3c 74 64 3e 20  >.<tr><td>6<td> 
28fe0 3c 74 64 3e 20 3c 74 64 3e 31 3c 74 64 3e 39 3c  <td> <td>1<td>9<
28ff0 74 64 3e 35 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td>5<td> <td> <t
29000 64 3e 0a 3c 74 72 3e 3c 74 64 3e 20 3c 74 64 3e  d>.<tr><td> <td>
29010 39 3c 74 64 3e 38 3c 74 64 3e 20 3c 74 64 3e 20  9<td>8<td> <td> 
29020 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 36 3c  <td> <td> <td>6<
29030 74 64 3e 0a 3c 74 72 3e 3c 74 64 3e 38 3c 74 64  td>.<tr><td>8<td
29040 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e  > <td> <td> <td>
29050 36 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20  6<td> <td> <td> 
29060 3c 74 64 3e 33 0a 3c 74 72 3e 3c 74 64 3e 34 3c  <td>3.<tr><td>4<
29070 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 38 3c 74  td> <td> <td>8<t
29080 64 3e 20 3c 74 64 3e 33 3c 74 64 3e 20 3c 74 64  d> <td>3<td> <td
29090 3e 20 3c 74 64 3e 31 0a 3c 74 72 3e 3c 74 64 3e  > <td>1.<tr><td>
290a0 37 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20  7<td> <td> <td> 
290b0 3c 74 64 3e 32 3c 74 64 3e 20 3c 74 64 3e 20 3c  <td>2<td> <td> <
290c0 74 64 3e 20 3c 74 64 3e 36 0a 3c 74 72 3e 3c 74  td> <td>6.<tr><t
290d0 64 3e 20 3c 74 64 3e 36 3c 74 64 3e 20 3c 74 64  d> <td>6<td> <td
290e0 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e  > <td> <td> <td>
290f0 32 3c 74 64 3e 38 3c 74 64 3e 0a 3c 74 72 3e 3c  2<td>8<td>.<tr><
29100 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
29110 64 3e 34 3c 74 64 3e 31 3c 74 64 3e 39 3c 74 64  d>4<td>1<td>9<td
29120 3e 20 3c 74 64 3e 20 3c 74 64 3e 35 0a 3c 74 72  > <td> <td>5.<tr
29130 3e 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20  ><td> <td> <td> 
29140 3c 74 64 3e 20 3c 74 64 3e 38 3c 74 64 3e 20 3c  <td> <td>8<td> <
29150 74 64 3e 20 3c 74 64 3e 37 3c 74 64 3e 39 0a 3c  td> <td>7<td>9.<
29160 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71  /table>.</blockq
29170 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 69  uote>..<p>This i
29180 73 20 74 68 65 20 71 75 65 72 79 20 74 68 61 74  s the query that
29190 20 73 6f 6c 76 65 73 20 74 68 65 20 70 75 7a 7a   solves the puzz
291a0 6c 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  le:..<blockquote
291b0 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55  ><pre>.WITH RECU
291c0 52 53 49 56 45 0a 20 20 69 6e 70 75 74 28 73 75  RSIVE.  input(su
291d0 64 29 20 41 53 20 28 0a 20 20 20 20 56 41 4c 55  d) AS (.    VALU
291e0 45 53 28 27 35 33 2e 2e 37 2e 2e 2e 2e 36 2e 2e  ES('53..7....6..
291f0 31 39 35 2e 2e 2e 2e 39 38 2e 2e 2e 2e 36 2e 38  195....98....6.8
29200 2e 2e 2e 36 2e 2e 2e 33 34 2e 2e 38 2e 33 2e 2e  ...6...34..8.3..
29210 31 37 2e 2e 2e 32 2e 2e 2e 36 2e 36 2e 2e 2e 2e  17...2...6.6....
29220 32 38 2e 2e 2e 2e 34 31 39 2e 2e 35 2e 2e 2e 2e  28....419..5....
29230 38 2e 2e 37 39 27 29 0a 20 20 29 2c 0a 20 20 64  8..79').  ),.  d
29240 69 67 69 74 73 28 7a 2c 20 6c 70 29 20 41 53 20  igits(z, lp) AS 
29250 28 0a 20 20 20 20 56 41 4c 55 45 53 28 27 31 27  (.    VALUES('1'
29260 2c 20 31 29 0a 20 20 20 20 55 4e 49 4f 4e 20 41  , 1).    UNION A
29270 4c 4c 20 53 45 4c 45 43 54 0a 20 20 20 20 43 41  LL SELECT.    CA
29280 53 54 28 6c 70 2b 31 20 41 53 20 54 45 58 54 29  ST(lp+1 AS TEXT)
29290 2c 20 6c 70 2b 31 20 46 52 4f 4d 20 64 69 67 69  , lp+1 FROM digi
292a0 74 73 20 57 48 45 52 45 20 6c 70 26 6c 74 3b 39  ts WHERE lp&lt;9
292b0 0a 20 20 29 2c 0a 20 20 78 28 73 2c 20 69 6e 64  .  ),.  x(s, ind
292c0 29 20 41 53 20 28 0a 20 20 20 20 53 45 4c 45 43  ) AS (.    SELEC
292d0 54 20 73 75 64 2c 20 69 6e 73 74 72 28 73 75 64  T sud, instr(sud
292e0 2c 20 27 2e 27 29 20 46 52 4f 4d 20 69 6e 70 75  , '.') FROM inpu
292f0 74 0a 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a  t.    UNION ALL.
29300 20 20 20 20 53 45 4c 45 43 54 0a 20 20 20 20 20      SELECT.     
29310 20 73 75 62 73 74 72 28 73 2c 20 31 2c 20 69 6e   substr(s, 1, in
29320 64 2d 31 29 20 7c 7c 20 7a 20 7c 7c 20 73 75 62  d-1) || z || sub
29330 73 74 72 28 73 2c 20 69 6e 64 2b 31 29 2c 0a 20  str(s, ind+1),. 
29340 20 20 20 20 20 69 6e 73 74 72 28 20 73 75 62 73       instr( subs
29350 74 72 28 73 2c 20 31 2c 20 69 6e 64 2d 31 29 20  tr(s, 1, ind-1) 
29360 7c 7c 20 7a 20 7c 7c 20 73 75 62 73 74 72 28 73  || z || substr(s
29370 2c 20 69 6e 64 2b 31 29 2c 20 27 2e 27 20 29 0a  , ind+1), '.' ).
29380 20 20 20 20 20 46 52 4f 4d 20 78 2c 20 64 69 67       FROM x, dig
29390 69 74 73 20 41 53 20 7a 0a 20 20 20 20 57 48 45  its AS z.    WHE
293a0 52 45 20 69 6e 64 3e 30 0a 20 20 20 20 20 20 41  RE ind>0.      A
293b0 4e 44 20 4e 4f 54 20 45 58 49 53 54 53 20 28 0a  ND NOT EXISTS (.
293c0 20 20 20 20 20 20 20 20 20 20 20 20 53 45 4c 45              SELE
293d0 43 54 20 31 0a 20 20 20 20 20 20 20 20 20 20 20  CT 1.           
293e0 20 20 20 46 52 4f 4d 20 64 69 67 69 74 73 20 41     FROM digits A
293f0 53 20 6c 70 0a 20 20 20 20 20 20 20 20 20 20 20  S lp.           
29400 20 20 57 48 45 52 45 20 7a 2e 7a 20 3d 20 73 75    WHERE z.z = su
29410 62 73 74 72 28 73 2c 20 28 28 69 6e 64 2d 31 29  bstr(s, ((ind-1)
29420 2f 39 29 2a 39 20 2b 20 6c 70 2c 20 31 29 0a 20  /9)*9 + lp, 1). 
29430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4f                 O
29440 52 20 7a 2e 7a 20 3d 20 73 75 62 73 74 72 28 73  R z.z = substr(s
29450 2c 20 28 28 69 6e 64 2d 31 29 25 39 29 20 2b 20  , ((ind-1)%9) + 
29460 28 6c 70 2d 31 29 2a 39 20 2b 20 31 2c 20 31 29  (lp-1)*9 + 1, 1)
29470 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
29480 20 4f 52 20 7a 2e 7a 20 3d 20 73 75 62 73 74 72   OR z.z = substr
29490 28 73 2c 20 28 28 28 69 6e 64 2d 31 29 2f 33 29  (s, (((ind-1)/3)
294a0 20 25 20 33 29 20 2a 20 33 0a 20 20 20 20 20 20   % 3) * 3.      
294b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
294c0 20 20 2b 20 28 28 69 6e 64 2d 31 29 2f 32 37 29    + ((ind-1)/27)
294d0 20 2a 20 32 37 20 2b 20 6c 70 0a 20 20 20 20 20   * 27 + lp.     
294e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
294f0 20 20 20 2b 20 28 28 6c 70 2d 31 29 20 2f 20 33     + ((lp-1) / 3
29500 29 20 2a 20 36 2c 20 31 29 0a 20 20 20 20 20 20  ) * 6, 1).      
29510 20 20 20 29 0a 20 20 29 0a 53 45 4c 45 43 54 20     ).  ).SELECT 
29520 73 20 46 52 4f 4d 20 78 20 57 48 45 52 45 20 69  s FROM x WHERE i
29530 6e 64 3d 30 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  nd=0;.</pre></bl
29540 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
29550 65 20 22 69 6e 70 75 74 22 20 43 54 45 20 64 65  e "input" CTE de
29560 66 69 6e 65 73 20 74 68 65 20 69 6e 70 75 74 20  fines the input 
29570 70 75 7a 7a 6c 65 2e 0a 54 68 65 20 22 64 69 67  puzzle..The "dig
29580 69 74 73 22 20 43 54 45 20 64 65 66 69 6e 65 73  its" CTE defines
29590 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 68 6f   a table that ho
295a0 6c 64 73 20 61 6c 6c 20 64 69 67 69 74 73 20 62  lds all digits b
295b0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 39 2e 0a  etween 1 and 9..
295c0 54 68 65 20 77 6f 72 6b 20 6f 66 20 73 6f 6c 76  The work of solv
295d0 69 6e 67 20 74 68 65 20 70 75 7a 7a 6c 65 20 69  ing the puzzle i
295e0 73 20 75 6e 64 65 72 74 61 6b 65 6e 20 62 79 20  s undertaken by 
295f0 74 68 65 20 22 78 22 20 43 54 45 2e 0a 41 6e 20  the "x" CTE..An 
29600 65 6e 74 72 79 20 69 6e 20 78 28 73 2c 69 6e 64  entry in x(s,ind
29610 29 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ) means that the
29620 20 38 31 2d 63 68 61 72 61 63 74 65 72 20 73 74   81-character st
29630 72 69 6e 67 20 22 73 22 20 69 73 20 61 20 76 61  ring "s" is a va
29640 6c 69 64 0a 73 75 64 6f 6b 75 20 70 75 7a 7a 6c  lid.sudoku puzzl
29650 65 20 28 69 74 20 68 61 73 20 6e 6f 20 63 6f 6e  e (it has no con
29660 66 6c 69 63 74 73 29 20 61 6e 64 20 74 68 61 74  flicts) and that
29670 20 74 68 65 20 66 69 72 73 74 20 75 6e 6b 6e 6f   the first unkno
29680 77 6e 20 63 68 61 72 61 63 74 65 72 0a 69 73 20  wn character.is 
29690 61 74 20 70 6f 73 69 74 69 6f 6e 20 22 69 6e 64  at position "ind
296a0 22 2c 20 6f 72 20 69 6e 64 3d 3d 30 20 69 66 20  ", or ind==0 if 
296b0 61 6c 6c 20 63 68 61 72 61 63 74 65 72 20 70 6f  all character po
296c0 73 69 74 69 6f 6e 73 20 61 72 65 20 66 69 6c 6c  sitions are fill
296d0 65 64 20 69 6e 2e 0a 54 68 65 20 67 6f 61 6c 2c  ed in..The goal,
296e0 20 74 68 65 6e 2c 20 69 73 20 74 6f 20 63 6f 6d   then, is to com
296f0 70 75 74 65 20 65 6e 74 72 69 65 73 20 66 6f 72  pute entries for
29700 20 22 78 22 20 77 69 74 68 20 61 6e 20 22 69 6e   "x" with an "in
29710 64 22 20 6f 66 20 30 2e 0a 0a 3c 70 3e 54 68 65  d" of 0...<p>The
29720 20 73 6f 6c 76 65 72 20 77 6f 72 6b 73 20 62 79   solver works by
29730 20 61 64 64 69 6e 67 20 6e 65 77 20 65 6e 74 72   adding new entr
29740 69 65 73 20 74 6f 20 74 68 65 20 22 78 22 20 72  ies to the "x" r
29750 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 2e 0a  ecursive table..
29760 47 69 76 65 6e 20 70 72 69 6f 72 20 65 6e 74 72  Given prior entr
29770 69 65 73 2c 20 74 68 65 20 72 65 63 75 72 73 69  ies, the recursi
29780 76 65 2d 73 65 6c 65 63 74 20 74 72 69 65 73 20  ve-select tries 
29790 74 6f 20 66 69 6c 6c 20 69 6e 20 61 20 73 69 6e  to fill in a sin
297a0 67 6c 65 20 6e 65 77 0a 70 6f 73 69 74 69 6f 6e  gle new.position
297b0 20 77 69 74 68 20 61 6c 6c 20 76 61 6c 75 65 73   with all values
297c0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 39   between 1 and 9
297d0 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
297e0 6f 72 6b 20 69 6e 20 74 68 61 74 0a 70 6f 73 69  ork in that.posi
297f0 74 69 6f 6e 2e 20 20 54 68 65 20 63 6f 6d 70 6c  tion.  The compl
29800 69 63 61 74 65 64 20 22 4e 4f 54 20 45 58 49 53  icated "NOT EXIS
29810 54 53 22 20 73 75 62 71 75 65 72 79 20 69 73 20  TS" subquery is 
29820 74 68 65 20 6d 61 67 69 63 20 74 68 61 74 0a 66  the magic that.f
29830 69 67 75 72 65 73 20 6f 75 74 20 77 68 65 74 68  igures out wheth
29840 65 72 20 6f 72 20 6e 6f 74 20 65 61 63 68 20 63  er or not each c
29850 61 6e 64 69 64 61 74 65 20 22 73 22 20 73 74 72  andidate "s" str
29860 69 6e 67 20 69 73 20 61 20 76 61 6c 69 64 0a 73  ing is a valid.s
29870 75 64 6f 6b 75 20 70 75 7a 7a 6c 65 20 6f 72 20  udoku puzzle or 
29880 6e 6f 74 2e 0a 0a 3c 70 3e 54 68 65 20 66 69 6e  not...<p>The fin
29890 61 6c 20 61 6e 73 77 65 72 20 69 73 20 66 6f 75  al answer is fou
298a0 6e 64 20 62 79 20 6c 6f 6f 6b 69 6e 67 20 66 6f  nd by looking fo
298b0 72 20 61 20 73 74 72 69 6e 67 20 77 69 74 68 20  r a string with 
298c0 69 6e 64 3d 3d 30 2e 0a 49 66 20 74 68 65 20 6f  ind==0..If the o
298d0 72 69 67 69 6e 61 6c 20 73 75 64 6f 6b 75 20 70  riginal sudoku p
298e0 72 6f 62 6c 65 6d 20 64 69 64 20 6e 6f 74 20 68  roblem did not h
298f0 61 76 65 20 61 20 75 6e 69 71 75 65 20 73 6f 6c  ave a unique sol
29900 75 74 69 6f 6e 2c 20 74 68 65 6e 0a 74 68 65 20  ution, then.the 
29910 71 75 65 72 79 20 77 69 6c 6c 20 72 65 74 75 72  query will retur
29920 6e 20 61 6c 6c 20 70 6f 73 73 69 62 6c 65 20 73  n all possible s
29930 6f 6c 75 74 69 6f 6e 73 2e 20 20 49 66 20 74 68  olutions.  If th
29940 65 20 6f 72 69 67 69 6e 61 6c 20 70 72 6f 62 6c  e original probl
29950 65 6d 0a 77 61 73 20 75 6e 73 6f 6c 76 61 62 6c  em.was unsolvabl
29960 65 2c 20 74 68 65 6e 20 6e 6f 20 72 6f 77 73 20  e, then no rows 
29970 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
29980 2e 20 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c  .  In this case,
29990 20 74 68 65 20 75 6e 69 71 75 65 0a 61 6e 73 77   the unique.answ
299a0 65 72 20 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  er is:..<blockqu
299b0 6f 74 65 3e 0a 35 33 34 36 37 38 39 31 32 36 37  ote>.53467891267
299c0 32 31 39 35 33 34 38 31 39 38 33 34 32 35 36 37  2195348198342567
299d0 38 35 39 37 36 31 34 32 33 34 32 36 38 35 33 37  8597614234268537
299e0 39 31 37 31 33 39 32 34 38 35 36 39 36 31 35 33  9171392485696153
299f0 37 32 38 34 32 38 37 34 31 39 36 33 35 33 34 35  7284287419635345
29a00 32 38 36 31 37 39 0a 3c 2f 62 6c 6f 63 6b 71 75  286179.</blockqu
29a10 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 73 6f 6c  ote>..<p>The sol
29a20 75 74 69 6f 6e 20 77 61 73 20 63 6f 6d 70 75 74  ution was comput
29a30 65 64 20 69 6e 20 6c 65 73 73 20 74 68 61 6e 20  ed in less than 
29a40 33 30 30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  300 milliseconds
29a50 20 6f 6e 20 61 20 6d 6f 64 65 72 6e 0a 77 6f 72   on a modern.wor
29a60 6b 73 74 61 74 69 6f 6e 2e 0a 0a 3c 68 33 3e 4c  kstation...<h3>L
29a70 69 6d 69 74 61 74 69 6f 6e 73 20 41 6e 64 20 43  imitations And C
29a80 61 76 65 61 74 73 3c 2f 68 33 3e 0a 0a 3c 75 6c  aveats</h3>..<ul
29a90 3e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20 57 49  >.<li><p>.The WI
29aa0 54 48 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f 74  TH clause cannot
29ab0 20 62 65 20 75 73 65 64 20 77 69 74 68 69 6e 20   be used within 
29ac0 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
29ad0 52 5d 2e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20  R]..<li><p>.The 
29ae0 57 49 54 48 20 63 6c 61 75 73 65 20 6d 75 73 74  WITH clause must
29af0 20 61 70 70 65 61 72 20 61 74 20 74 68 65 20 62   appear at the b
29b00 65 67 69 6e 6e 69 6e 67 20 6f 66 20 61 20 74 6f  eginning of a to
29b10 70 2d 6c 65 76 65 6c 20 5b 53 45 4c 45 43 54 5d  p-level [SELECT]
29b20 20 73 74 61 74 65 6d 65 6e 74 0a 6f 72 20 61 74   statement.or at
29b30 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
29b40 66 20 61 20 73 75 62 71 75 65 72 79 2e 20 20 54  f a subquery.  T
29b50 68 65 20 57 49 54 48 20 63 6c 61 75 73 65 20 63  he WITH clause c
29b60 61 6e 6e 6f 74 20 62 65 20 70 72 65 70 65 6e 64  annot be prepend
29b70 65 64 20 74 6f 0a 74 68 65 20 73 65 63 6f 6e 64  ed to.the second
29b80 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 53   or subsequent S
29b90 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
29ba0 6f 66 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 73  of a [compound s
29bb0 65 6c 65 63 74 5d 2e 0a 3c 6c 69 3e 3c 70 3e 0a  elect]..<li><p>.
29bc0 54 68 65 20 53 51 4c 3a 31 39 39 39 20 73 70 65  The SQL:1999 spe
29bd0 63 20 72 65 71 75 69 72 65 73 20 74 68 61 74 20  c requires that 
29be0 74 68 65 20 52 45 43 55 52 53 49 56 45 20 6b 65  the RECURSIVE ke
29bf0 79 77 6f 72 64 20 66 6f 6c 6c 6f 77 20 57 49 54  yword follow WIT
29c00 48 20 69 6e 20 61 6e 79 0a 57 49 54 48 20 63 6c  H in any.WITH cl
29c10 61 75 73 65 20 74 68 61 74 20 69 6e 63 6c 75 64  ause that includ
29c20 65 73 20 61 20 72 65 63 75 72 73 69 76 65 20 63  es a recursive c
29c30 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72  ommon table expr
29c40 65 73 73 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72  ession.  However
29c50 2c 20 66 6f 72 0a 63 6f 6d 70 61 74 69 62 69 6c  , for.compatibil
29c60 69 74 79 20 77 69 74 68 20 53 71 6c 53 65 72 76  ity with SqlServ
29c70 65 72 20 61 6e 64 20 4f 72 61 63 6c 65 2c 20 53  er and Oracle, S
29c80 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 65  QLite does not e
29c90 6e 66 6f 72 63 65 20 74 68 69 73 20 72 75 6c 65  nforce this rule
29ca0 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 0a 23  ..</ul>..<tcl>.#
29cb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29cc0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29cd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29ce0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29cf0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
29d00 65 63 74 69 6f 6e 20 53 45 4c 45 43 54 20 73 65  ection SELECT se
29d10 6c 65 63 74 20 7b 53 45 4c 45 43 54 20 71 75 65  lect {SELECT que
29d20 72 79 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75  ry}..RecursiveBu
29d30 62 62 6c 65 44 69 61 67 72 61 6d 20 73 65 6c 65  bbleDiagram sele
29d40 63 74 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  ct-stmt.</tcl>..
29d50 0a 3c 70 3e 54 68 65 20 53 45 4c 45 43 54 20 73  .<p>The SELECT s
29d60 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 65 64  tatement is used
29d70 20 74 6f 20 71 75 65 72 79 20 74 68 65 20 64 61   to query the da
29d80 74 61 62 61 73 65 2e 20 20 54 68 65 0a 72 65 73  tabase.  The.res
29d90 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  ult of a SELECT 
29da0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
29db0 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 68 65  rows of data whe
29dc0 72 65 20 65 61 63 68 20 72 6f 77 0a 68 61 73 20  re each row.has 
29dd0 61 20 66 69 78 65 64 20 6e 75 6d 62 65 72 20 6f  a fixed number o
29de0 66 20 63 6f 6c 75 6d 6e 73 2e 20 20 41 20 53 45  f columns.  A SE
29df0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 64  LECT statement d
29e00 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 0a 61 6e 79  oes not make.any
29e10 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
29e20 64 61 74 61 62 61 73 65 2e 0a 0a 3c 70 3e 54 68  database...<p>Th
29e30 65 20 22 5b 73 65 6c 65 63 74 2d 73 74 6d 74 5d  e "[select-stmt]
29e40 22 20 73 79 6e 74 61 78 20 64 69 61 67 72 61 6d  " syntax diagram
29e50 20 61 62 6f 76 65 20 61 74 74 65 6d 70 74 73 20   above attempts 
29e60 74 6f 20 73 68 6f 77 20 61 73 20 6d 75 63 68 20  to show as much 
29e70 6f 66 20 74 68 65 0a 53 45 4c 45 43 54 20 73 74  of the.SELECT st
29e80 61 74 65 6d 65 6e 74 20 73 79 6e 74 61 78 20 61  atement syntax a
29e90 73 20 70 6f 73 73 69 62 6c 65 20 69 6e 20 61 20  s possible in a 
29ea0 73 69 6e 67 6c 65 20 64 69 61 67 72 61 6d 2c 20  single diagram, 
29eb0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 72 65 61  because some rea
29ec0 64 65 72 73 0a 66 69 6e 64 20 74 68 61 74 20 68  ders.find that h
29ed0 65 6c 70 66 75 6c 2e 20 20 54 68 65 20 66 6f 6c  elpful.  The fol
29ee0 6c 6f 77 69 6e 67 20 22 5b 66 61 63 74 6f 72 65  lowing "[factore
29ef0 64 2d 73 65 6c 65 63 74 2d 73 74 6d 74 5d 22 20  d-select-stmt]" 
29f00 69 73 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  is an alternativ
29f10 65 0a 73 79 6e 74 61 78 20 64 69 61 67 72 61 6d  e.syntax diagram
29f20 73 20 74 68 61 74 20 65 78 70 72 65 73 73 65 73  s that expresses
29f30 20 74 68 65 20 73 61 6d 65 20 73 79 6e 74 61 78   the same syntax
29f40 20 62 75 74 20 74 72 69 65 73 20 74 6f 20 62 72   but tries to br
29f50 65 61 6b 20 74 68 65 20 73 79 6e 74 61 78 20 0a  eak the syntax .
29f60 64 6f 77 6e 20 69 6e 74 6f 20 73 6d 61 6c 6c 65  down into smalle
29f70 72 20 63 68 75 6e 6b 73 2e 0a 0a 3c 74 63 6c 3e  r chunks...<tcl>
29f80 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65  .RecursiveBubble
29f90 44 69 61 67 72 61 6d 20 2d 2d 69 6e 69 74 69 61  Diagram --initia
29fa0 6c 6c 79 2d 68 69 64 64 65 6e 20 66 61 63 74 6f  lly-hidden facto
29fb0 72 65 64 2d 73 65 6c 65 63 74 2d 73 74 6d 74 20  red-select-stmt 
29fc0 73 65 6c 65 63 74 2d 63 6f 72 65 0a 3c 2f 74 63  select-core.</tc
29fd0 6c 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74  l>..<p>Note that
29fe0 20 74 68 65 72 65 20 61 72 65 20 70 61 74 68 73   there are paths
29ff0 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 79 6e   through the syn
2a000 74 61 78 20 64 69 61 67 72 61 6d 73 20 74 68 61  tax diagrams tha
2a010 74 0a 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  t.are not allowe
2a020 64 20 69 6e 20 70 72 61 63 74 69 63 65 2e 20 20  d in practice.  
2a030 53 6f 6d 65 20 65 78 61 6d 70 6c 65 73 3a 0a 3c  Some examples:.<
2a040 75 6c 3e 0a 3c 6c 69 3e 41 20 5b 56 41 4c 55 45  ul>.<li>A [VALUE
2a050 53 5d 20 63 6c 61 75 73 65 20 63 61 6e 20 62 65  S] clause can be
2a060 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
2a070 6e 74 20 69 6e 20 61 20 5b 63 6f 6d 70 6f 75 6e  nt in a [compoun
2a080 64 20 53 45 4c 45 43 54 5d 0a 20 20 20 20 74 68  d SELECT].    th
2a090 61 74 20 75 73 65 73 20 61 20 5b 57 49 54 48 5d  at uses a [WITH]
2a0a0 20 63 6c 61 75 73 65 2c 20 62 75 74 20 61 20 5b   clause, but a [
2a0b0 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 5d 20 74  simple SELECT] t
2a0c0 68 61 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 0a  hat consists of.
2a0d0 20 20 20 20 6a 75 73 74 20 61 20 5b 56 41 4c 55      just a [VALU
2a0e0 45 53 5d 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f  ES] clause canno
2a0f0 74 20 62 65 20 70 72 65 63 65 64 65 64 20 62 79  t be preceded by
2a100 20 61 20 5b 57 49 54 48 5d 20 63 6c 61 75 73 65   a [WITH] clause
2a110 2e 0a 3c 6c 69 3e 54 68 65 20 5b 57 49 54 48 5d  ..<li>The [WITH]
2a120 20 63 6c 61 75 73 65 20 6d 75 73 74 20 6f 63 63   clause must occ
2a130 75 72 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  ur on the first 
2a140 53 45 4c 45 43 54 20 6f 66 20 61 20 5b 63 6f 6d  SELECT of a [com
2a150 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d 2e 0a 20  pound SELECT].. 
2a160 20 20 20 49 74 20 63 61 6e 6e 6f 74 20 66 6f 6c     It cannot fol
2a170 6c 6f 77 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 2d  low a [compound-
2a180 6f 70 65 72 61 74 6f 72 5d 2e 0a 3c 2f 75 6c 3e  operator]..</ul>
2a190 0a 54 68 65 73 65 20 61 6e 64 20 6f 74 68 65 72  .These and other
2a1a0 20 73 69 6d 69 6c 61 72 20 73 79 6e 74 61 78 20   similar syntax 
2a1b0 72 65 73 74 72 69 63 74 69 6f 6e 73 20 61 72 65  restrictions are
2a1c0 20 64 65 73 63 72 69 62 65 64 20 69 6e 20 74 68   described in th
2a1d0 65 20 74 65 78 74 2e 0a 0a 3c 70 3e 54 68 65 20  e text...<p>The 
2a1e0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2a1f0 20 69 73 20 74 68 65 20 6d 6f 73 74 20 63 6f 6d   is the most com
2a200 70 6c 69 63 61 74 65 64 20 63 6f 6d 6d 61 6e 64  plicated command
2a210 20 69 6e 20 74 68 65 20 53 51 4c 20 6c 61 6e 67   in the SQL lang
2a220 75 61 67 65 2e 0a 54 6f 20 6d 61 6b 65 20 74 68  uage..To make th
2a230 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 65 61  e description ea
2a240 73 69 65 72 20 74 6f 20 66 6f 6c 6c 6f 77 2c 20  sier to follow, 
2a250 73 6f 6d 65 20 6f 66 20 74 68 65 20 70 61 73 73  some of the pass
2a260 61 67 65 73 20 62 65 6c 6f 77 20 64 65 73 63 72  ages below descr
2a270 69 62 65 0a 74 68 65 20 77 61 79 20 74 68 65 20  ibe.the way the 
2a280 64 61 74 61 20 72 65 74 75 72 6e 65 64 20 62 79  data returned by
2a290 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
2a2a0 65 6e 74 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ent is determine
2a2b0 64 20 61 73 20 61 20 73 65 72 69 65 73 20 6f 66  d as a series of
2a2c0 0a 73 74 65 70 73 2e 20 49 74 20 69 73 20 69 6d  .steps. It is im
2a2d0 70 6f 72 74 61 6e 74 20 74 6f 20 6b 65 65 70 20  portant to keep 
2a2e0 69 6e 20 6d 69 6e 64 20 74 68 61 74 20 74 68 69  in mind that thi
2a2f0 73 20 69 73 20 70 75 72 65 6c 79 20 69 6c 6c 75  s is purely illu
2a300 73 74 72 61 74 69 76 65 20 2d 0a 69 6e 20 70 72  strative -.in pr
2a310 61 63 74 69 63 65 20 6e 65 69 74 68 65 72 20 53  actice neither S
2a320 51 4c 69 74 65 20 6e 6f 72 20 61 6e 79 20 6f 74  QLite nor any ot
2a330 68 65 72 20 53 51 4c 20 65 6e 67 69 6e 65 20 69  her SQL engine i
2a340 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 66 6f  s required to fo
2a350 6c 6c 6f 77 20 0a 74 68 69 73 20 6f 72 20 61 6e  llow .this or an
2a360 79 20 6f 74 68 65 72 20 73 70 65 63 69 66 69 63  y other specific
2a370 20 70 72 6f 63 65 73 73 2e 0a 0a 3c 74 63 6c 3e   process...<tcl>
2a380 68 64 5f 66 72 61 67 6d 65 6e 74 20 73 69 6d 70  hd_fragment simp
2a390 6c 65 73 65 6c 65 63 74 20 7b 73 69 6d 70 6c 65  leselect {simple
2a3a0 20 53 45 4c 45 43 54 7d 3c 2f 74 63 6c 3e 0a 3c   SELECT}</tcl>.<
2a3b0 68 33 3e 53 69 6d 70 6c 65 20 53 65 6c 65 63 74  h3>Simple Select
2a3c0 20 50 72 6f 63 65 73 73 69 6e 67 3c 2f 68 33 3e   Processing</h3>
2a3d0 0a 0a 3c 70 3e 54 68 65 20 63 6f 72 65 20 6f 66  ..<p>The core of
2a3e0 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
2a3f0 65 6e 74 20 69 73 20 61 20 22 73 69 6d 70 6c 65  ent is a "simple
2a400 20 53 45 4c 45 43 54 22 20 73 68 6f 77 6e 20 62   SELECT" shown b
2a410 79 20 74 68 65 0a 5b 73 65 6c 65 63 74 2d 63 6f  y the.[select-co
2a420 72 65 5d 20 61 6e 64 20 5b 73 69 6d 70 6c 65 2d  re] and [simple-
2a430 73 65 6c 65 63 74 2d 73 74 6d 74 5d 20 73 79 6e  select-stmt] syn
2a440 74 61 78 20 64 69 61 67 72 61 6d 73 20 62 65 6c  tax diagrams bel
2a450 6f 77 2e 20 20 0a 49 6e 20 70 72 61 63 74 69 63  ow.  .In practic
2a460 65 2c 20 6d 6f 73 74 20 53 45 4c 45 43 54 20 73  e, most SELECT s
2a470 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 69  tatements are si
2a480 6d 70 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74  mple SELECT stat
2a490 65 6d 65 6e 74 73 2e 0a 0a 3c 74 63 6c 3e 0a 52  ements...<tcl>.R
2a4a0 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
2a4b0 61 67 72 61 6d 20 73 69 6d 70 6c 65 2d 73 65 6c  agram simple-sel
2a4c0 65 63 74 2d 73 74 6d 74 20 73 65 6c 65 63 74 2d  ect-stmt select-
2a4d0 63 6f 72 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e  core.</tcl>..<p>
2a4e0 47 65 6e 65 72 61 74 69 6e 67 20 74 68 65 20 72  Generating the r
2a4f0 65 73 75 6c 74 73 20 6f 66 20 61 20 73 69 6d 70  esults of a simp
2a500 6c 65 20 53 45 4c 45 43 54 0a 73 74 61 74 65 6d  le SELECT.statem
2a510 65 6e 74 20 69 73 20 70 72 65 73 65 6e 74 65 64  ent is presented
2a520 20 61 73 20 61 20 66 6f 75 72 20 73 74 65 70 20   as a four step 
2a530 70 72 6f 63 65 73 73 20 69 6e 20 74 68 65 20 64  process in the d
2a540 65 73 63 72 69 70 74 69 6f 6e 20 62 65 6c 6f 77  escription below
2a550 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 3c  :..<ol>.  <li> <
2a560 70 3e 5b 46 52 4f 4d 20 63 6c 61 75 73 65 5d 20  p>[FROM clause] 
2a570 70 72 6f 63 65 73 73 69 6e 67 3a 20 54 68 65 20  processing: The 
2a580 69 6e 70 75 74 20 64 61 74 61 20 66 6f 72 20 74  input data for t
2a590 68 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54  he simple SELECT
2a5a0 20 69 73 0a 20 20 20 20 20 20 20 64 65 74 65 72   is.       deter
2a5b0 6d 69 6e 65 64 2e 20 54 68 65 20 69 6e 70 75 74  mined. The input
2a5c0 20 64 61 74 61 20 69 73 20 65 69 74 68 65 72 20   data is either 
2a5d0 69 6d 70 6c 69 63 69 74 6c 79 20 61 20 73 69 6e  implicitly a sin
2a5e0 67 6c 65 20 72 6f 77 20 77 69 74 68 20 30 0a 20  gle row with 0. 
2a5f0 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 28 69        columns (i
2a600 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 46 52  f there is no FR
2a610 4f 4d 20 63 6c 61 75 73 65 29 20 6f 72 20 69 73  OM clause) or is
2a620 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2a630 68 65 20 46 52 4f 4d 0a 20 20 20 20 20 20 20 63  he FROM.       c
2a640 6c 61 75 73 65 2e 0a 20 20 3c 6c 69 3e 20 3c 70  lause..  <li> <p
2a650 3e 5b 57 48 45 52 45 20 63 6c 61 75 73 65 5d 20  >[WHERE clause] 
2a660 70 72 6f 63 65 73 73 69 6e 67 3a 20 54 68 65 20  processing: The 
2a670 69 6e 70 75 74 20 64 61 74 61 20 69 73 20 66 69  input data is fi
2a680 6c 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  ltered using the
2a690 20 57 48 45 52 45 0a 20 20 20 20 20 20 20 63 6c   WHERE.       cl
2a6a0 61 75 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2e  ause expression.
2a6b0 20 20 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5b 47 52    .  <li> <p>[GR
2a6c0 4f 55 50 20 42 59 7c 47 52 4f 55 50 20 42 59 2c  OUP BY|GROUP BY,
2a6d0 20 48 41 56 49 4e 47 20 61 6e 64 20 72 65 73 75   HAVING and resu
2a6e0 6c 74 2d 63 6f 6c 75 6d 6e 20 65 78 70 72 65 73  lt-column expres
2a6f0 73 69 6f 6e 5d 20 70 72 6f 63 65 73 73 69 6e 67  sion] processing
2a700 3a 20 0a 20 20 20 20 20 20 20 54 68 65 20 73 65  : .       The se
2a710 74 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  t of result rows
2a720 20 69 73 20 63 6f 6d 70 75 74 65 64 20 62 79 20   is computed by 
2a730 61 67 67 72 65 67 61 74 69 6e 67 20 74 68 65 20  aggregating the 
2a740 64 61 74 61 20 61 63 63 6f 72 64 69 6e 67 20 74  data according t
2a750 6f 0a 20 20 20 20 20 20 20 61 6e 79 20 47 52 4f  o.       any GRO
2a760 55 50 20 42 59 20 63 6c 61 75 73 65 20 61 6e 64  UP BY clause and
2a770 20 63 61 6c 63 75 6c 61 74 69 6e 67 20 74 68 65   calculating the
2a780 20 72 65 73 75 6c 74 2d 73 65 74 20 65 78 70 72   result-set expr
2a790 65 73 73 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  essions for the.
2a7a0 20 20 20 20 20 20 20 72 6f 77 73 20 6f 66 20 74         rows of t
2a7b0 68 65 20 66 69 6c 74 65 72 65 64 20 69 6e 70 75  he filtered inpu
2a7c0 74 20 64 61 74 61 73 65 74 2e 20 20 0a 20 20 3c  t dataset.  .  <
2a7d0 6c 69 3e 20 3c 70 3e 5b 44 49 53 54 49 4e 43 54  li> <p>[DISTINCT
2a7e0 7c 44 49 53 54 49 4e 43 54 2f 41 4c 4c 20 6b 65  |DISTINCT/ALL ke
2a7f0 79 77 6f 72 64 5d 20 70 72 6f 63 65 73 73 69 6e  yword] processin
2a800 67 3a 20 49 66 20 74 68 65 20 71 75 65 72 79 20  g: If the query 
2a810 69 73 20 61 20 22 53 45 4c 45 43 54 0a 20 20 20  is a "SELECT.   
2a820 20 20 20 20 44 49 53 54 49 4e 43 54 22 20 71 75      DISTINCT" qu
2a830 65 72 79 2c 20 64 75 70 6c 69 63 61 74 65 20 72  ery, duplicate r
2a840 6f 77 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20  ows are removed 
2a850 66 72 6f 6d 20 74 68 65 20 73 65 74 20 6f 66 20  from the set of 
2a860 72 65 73 75 6c 74 20 72 6f 77 73 2e 0a 3c 2f 6f  result rows..</o
2a870 6c 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65  l>..<p>There are
2a880 20 74 77 6f 20 74 79 70 65 73 20 6f 66 20 73 69   two types of si
2a890 6d 70 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74  mple SELECT stat
2a8a0 65 6d 65 6e 74 20 2d 20 61 67 67 72 65 67 61 74  ement - aggregat
2a8b0 65 20 61 6e 64 20 0a 6e 6f 6e 2d 61 67 67 72 65  e and .non-aggre
2a8c0 67 61 74 65 20 71 75 65 72 69 65 73 2e 20 5e 41  gate queries. ^A
2a8d0 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 73   simple SELECT s
2a8e0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 61  tatement is an a
2a8f0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 69  ggregate query i
2a900 66 0a 69 74 20 63 6f 6e 74 61 69 6e 73 20 65 69  f.it contains ei
2a910 74 68 65 72 20 61 20 47 52 4f 55 50 20 42 59 20  ther a GROUP BY 
2a920 63 6c 61 75 73 65 20 6f 72 20 6f 6e 65 20 6f 72  clause or one or
2a930 20 6d 6f 72 65 20 61 67 67 72 65 67 61 74 65 20   more aggregate 
2a940 66 75 6e 63 74 69 6f 6e 73 0a 69 6e 20 74 68 65  functions.in the
2a950 20 72 65 73 75 6c 74 2d 73 65 74 2e 20 5e 4f 74   result-set. ^Ot
2a960 68 65 72 77 69 73 65 2c 20 69 66 20 61 20 73 69  herwise, if a si
2a970 6d 70 6c 65 20 53 45 4c 45 43 54 20 63 6f 6e 74  mple SELECT cont
2a980 61 69 6e 73 20 6e 6f 20 61 67 67 72 65 67 61 74  ains no aggregat
2a990 65 0a 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  e.functions or a
2a9a0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2a9b0 2c 20 69 74 20 69 73 20 61 20 6e 6f 6e 2d 61 67  , it is a non-ag
2a9c0 67 72 65 67 61 74 65 20 71 75 65 72 79 2e 0a 0a  gregate query...
2a9d0 3c 70 3e 3c 62 3e 31 2e 20 44 65 74 65 72 6d 69  <p><b>1. Determi
2a9e0 6e 61 74 69 6f 6e 20 6f 66 20 69 6e 70 75 74 20  nation of input 
2a9f0 64 61 74 61 20 28 46 52 4f 4d 20 63 6c 61 75 73  data (FROM claus
2aa00 65 20 70 72 6f 63 65 73 73 69 6e 67 29 2e 3c 2f  e processing).</
2aa10 62 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  b>.<tcl>hd_fragm
2aa20 65 6e 74 20 66 72 6f 6d 63 6c 61 75 73 65 3c 2f  ent fromclause</
2aa30 74 63 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79  tcl>.<tcl>hd_key
2aa40 77 6f 72 64 73 20 7b 46 52 4f 4d 20 63 6c 61 75  words {FROM clau
2aa50 73 65 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68  se}</tcl>..<p>Th
2aa60 65 20 69 6e 70 75 74 20 64 61 74 61 20 75 73 65  e input data use
2aa70 64 20 62 79 20 61 20 73 69 6d 70 6c 65 20 53 45  d by a simple SE
2aa80 4c 45 43 54 20 71 75 65 72 79 20 69 73 20 61 20  LECT query is a 
2aa90 73 65 74 20 6f 66 20 3c 69 3e 4e 3c 2f 69 3e 20  set of <i>N</i> 
2aaa0 72 6f 77 73 20 0a 65 61 63 68 20 3c 69 3e 4d 3c  rows .each <i>M<
2aab0 2f 69 3e 20 63 6f 6c 75 6d 6e 73 20 77 69 64 65  /i> columns wide
2aac0 2e 0a 0a 3c 70 3e 5e 28 49 66 20 74 68 65 20 46  ...<p>^(If the F
2aad0 52 4f 4d 20 63 6c 61 75 73 65 20 69 73 20 6f 6d  ROM clause is om
2aae0 69 74 74 65 64 20 66 72 6f 6d 20 61 20 73 69 6d  itted from a sim
2aaf0 70 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  ple SELECT state
2ab00 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 0a  ment, then the .
2ab10 69 6e 70 75 74 20 64 61 74 61 20 69 73 20 69 6d  input data is im
2ab20 70 6c 69 63 69 74 6c 79 20 61 20 73 69 6e 67 6c  plicitly a singl
2ab30 65 20 72 6f 77 20 7a 65 72 6f 20 63 6f 6c 75 6d  e row zero colum
2ab40 6e 73 20 77 69 64 65 29 5e 20 28 69 2e 65 2e 20  ns wide)^ (i.e. 
2ab50 3c 69 3e 4e 3c 2f 69 3e 3d 31 20 61 6e 64 0a 3c  <i>N</i>=1 and.<
2ab60 69 3e 4d 3c 2f 69 3e 3d 30 29 2e 0a 0a 3c 70 3e  i>M</i>=0)...<p>
2ab70 49 66 20 61 20 46 52 4f 4d 20 63 6c 61 75 73 65  If a FROM clause
2ab80 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
2ab90 68 65 20 64 61 74 61 20 6f 6e 20 77 68 69 63 68  he data on which
2aba0 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54   a simple SELECT
2abb0 20 71 75 65 72 79 0a 6f 70 65 72 61 74 65 73 20   query.operates 
2abc0 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 6f  comes from the o
2abd0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 61 62 6c 65  ne or more table
2abe0 73 20 6f 72 20 73 75 62 71 75 65 72 69 65 73 20  s or subqueries 
2abf0 28 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e  (SELECT statemen
2ac00 74 73 0a 69 6e 20 70 61 72 65 6e 74 68 65 73 69  ts.in parenthesi
2ac10 73 29 20 73 70 65 63 69 66 69 65 64 20 66 6f 6c  s) specified fol
2ac20 6c 6f 77 69 6e 67 20 74 68 65 20 46 52 4f 4d 20  lowing the FROM 
2ac30 6b 65 79 77 6f 72 64 2e 20 5e 41 20 73 75 62 71  keyword. ^A subq
2ac40 75 65 72 79 20 73 70 65 63 69 66 69 65 64 0a 69  uery specified.i
2ac50 6e 20 74 68 65 20 3c 79 79 74 65 72 6d 3e 74 61  n the <yyterm>ta
2ac60 62 6c 65 2d 6f 72 2d 73 75 62 71 75 65 72 79 3c  ble-or-subquery<
2ac70 2f 79 79 74 65 72 6d 3e 20 66 6f 6c 6c 6f 77 69  /yyterm> followi
2ac80 6e 67 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75  ng the FROM clau
2ac90 73 65 20 69 6e 20 61 20 0a 73 69 6d 70 6c 65 20  se in a .simple 
2aca0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2acb0 20 69 73 0a 68 61 6e 64 6c 65 64 20 61 73 20 69   is.handled as i
2acc0 66 20 69 74 20 77 61 73 20 61 20 74 61 62 6c 65  f it was a table
2acd0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2ace0 64 61 74 61 20 72 65 74 75 72 6e 65 64 20 62 79  data returned by
2acf0 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 0a 73   executing the.s
2ad00 75 62 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e  ubquery statemen
2ad10 74 2e 20 5e 45 61 63 68 20 63 6f 6c 75 6d 6e 20  t. ^Each column 
2ad20 6f 66 20 74 68 65 20 73 75 62 71 75 65 72 79 20  of the subquery 
2ad30 68 61 73 20 74 68 65 0a 5b 63 6f 6c 6c 61 74 69  has the.[collati
2ad40 6f 6e 7c 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  on|collation seq
2ad50 75 65 6e 63 65 5d 20 61 6e 64 20 5b 61 66 66 69  uence] and [affi
2ad60 6e 69 74 79 5d 20 6f 66 20 74 68 65 20 63 6f 72  nity] of the cor
2ad70 72 65 73 70 6f 6e 64 69 6e 67 20 65 78 70 72 65  responding expre
2ad80 73 73 69 6f 6e 0a 69 6e 20 74 68 65 20 73 75 62  ssion.in the sub
2ad90 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 2e  query statement.
2ada0 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 72 65 20 69  ..<p>^If there i
2adb0 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2adc0 74 61 62 6c 65 20 6f 72 20 73 75 62 71 75 65 72  table or subquer
2add0 79 20 69 6e 20 74 68 65 20 46 52 4f 4d 0a 63 6c  y in the FROM.cl
2ade0 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20 69  ause, then the i
2adf0 6e 70 75 74 20 64 61 74 61 20 75 73 65 64 20 62  nput data used b
2ae00 79 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  y the SELECT sta
2ae10 74 65 6d 65 6e 74 20 69 73 20 74 68 65 20 63 6f  tement is the co
2ae20 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 0a 6e 61  ntents of the.na
2ae30 6d 65 64 20 74 61 62 6c 65 2e 20 5e 49 66 20 74  med table. ^If t
2ae40 68 65 72 65 20 69 73 20 6d 6f 72 65 20 74 68 61  here is more tha
2ae50 6e 20 6f 6e 65 20 74 61 62 6c 65 20 6f 72 20 73  n one table or s
2ae60 75 62 71 75 65 72 79 20 69 6e 20 46 52 4f 4d 20  ubquery in FROM 
2ae70 63 6c 61 75 73 65 0a 74 68 65 6e 20 74 68 65 20  clause.then the 
2ae80 63 6f 6e 74 65 6e 74 73 20 6f 66 20 61 6c 6c 20  contents of all 
2ae90 74 61 62 6c 65 73 20 61 6e 64 2f 6f 72 20 73 75  tables and/or su
2aea0 62 71 75 65 72 69 65 73 0a 61 72 65 20 6a 6f 69  bqueries.are joi
2aeb0 6e 65 64 20 69 6e 74 6f 20 61 20 73 69 6e 67 6c  ned into a singl
2aec0 65 20 64 61 74 61 73 65 74 20 66 6f 72 20 74 68  e dataset for th
2aed0 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20  e simple SELECT 
2aee0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 6f 70 65  statement to ope
2aef0 72 61 74 65 20 6f 6e 2e 0a 45 78 61 63 74 6c 79  rate on..Exactly
2af00 20 68 6f 77 20 74 68 65 20 64 61 74 61 20 69 73   how the data is
2af10 20 63 6f 6d 62 69 6e 65 64 20 64 65 70 65 6e 64   combined depend
2af20 73 20 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69  s on the specifi
2af30 63 20 5b 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72  c [join-operator
2af40 5d 20 61 6e 64 0a 5b 6a 6f 69 6e 2d 63 6f 6e 73  ] and.[join-cons
2af50 74 72 61 69 6e 74 5d 20 75 73 65 64 20 74 6f 20  traint] used to 
2af60 63 6f 6e 6e 65 63 74 20 74 68 65 20 74 61 62 6c  connect the tabl
2af70 65 73 20 6f 72 20 73 75 62 71 75 65 72 69 65 73  es or subqueries
2af80 20 74 6f 67 65 74 68 65 72 2e 0a 0a 3c 70 3e 41   together...<p>A
2af90 6c 6c 20 6a 6f 69 6e 73 20 69 6e 20 53 51 4c 69  ll joins in SQLi
2afa0 74 65 20 61 72 65 20 62 61 73 65 64 20 6f 6e 20  te are based on 
2afb0 74 68 65 20 63 61 72 74 65 73 69 61 6e 20 70 72  the cartesian pr
2afc0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 6c 65 66  oduct of the lef
2afd0 74 20 61 6e 64 0a 72 69 67 68 74 2d 68 61 6e 64  t and.right-hand
2afe0 20 64 61 74 61 73 65 74 73 2e 20 5e 54 68 65 20   datasets. ^The 
2aff0 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20 63  columns of the c
2b000 61 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74  artesian product
2b010 20 64 61 74 61 73 65 74 20 61 72 65 2c 20 69 6e   dataset are, in
2b020 20 0a 6f 72 64 65 72 2c 20 61 6c 6c 20 74 68 65   .order, all the
2b030 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20   columns of the 
2b040 6c 65 66 74 2d 68 61 6e 64 20 64 61 74 61 73 65  left-hand datase
2b050 74 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6c  t followed by al
2b060 6c 20 74 68 65 20 63 6f 6c 75 6d 6e 73 0a 6f 66  l the columns.of
2b070 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
2b080 64 61 74 61 73 65 74 2e 20 5e 54 68 65 72 65 20  dataset. ^There 
2b090 69 73 20 61 20 72 6f 77 20 69 6e 20 74 68 65 20  is a row in the 
2b0a0 63 61 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63  cartesian produc
2b0b0 74 20 64 61 74 61 73 65 74 0a 66 6f 72 6d 65 64  t dataset.formed
2b0c0 20 62 79 20 63 6f 6d 62 69 6e 69 6e 67 20 65 61   by combining ea
2b0d0 63 68 20 75 6e 69 71 75 65 20 63 6f 6d 62 69 6e  ch unique combin
2b0e0 61 74 69 6f 6e 20 6f 66 20 61 20 72 6f 77 20 66  ation of a row f
2b0f0 72 6f 6d 20 74 68 65 20 6c 65 66 74 2d 68 61 6e  rom the left-han
2b100 64 20 0a 61 6e 64 20 72 69 67 68 74 2d 68 61 6e  d .and right-han
2b110 64 20 64 61 74 61 73 65 74 73 2e 20 5e 28 49 6e  d datasets. ^(In
2b120 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
2b130 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 64   the left-hand d
2b140 61 74 61 73 65 74 20 63 6f 6e 73 69 73 74 73 20  ataset consists 
2b150 6f 66 0a 3c 69 3e 4e 3c 73 75 62 3e 3c 73 6d 61  of.<i>N<sub><sma
2b160 6c 6c 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c  ll>left</small><
2b170 2f 73 75 62 3e 3c 2f 69 3e 20 72 6f 77 73 20 6f  /sub></i> rows o
2b180 66 20 0a 3c 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61  f .<i>M<sub><sma
2b190 6c 6c 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c  ll>left</small><
2b1a0 2f 73 75 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d 6e  /sub></i> column
2b1b0 73 2c 20 61 6e 64 20 74 68 65 20 72 69 67 68 74  s, and the right
2b1c0 2d 68 61 6e 64 20 64 61 74 61 73 65 74 20 6f 66  -hand dataset of
2b1d0 0a 3c 69 3e 4e 3c 73 75 62 3e 3c 73 6d 61 6c 6c  .<i>N<sub><small
2b1e0 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f  >right</small></
2b1f0 73 75 62 3e 3c 2f 69 3e 20 72 6f 77 73 20 6f 66  sub></i> rows of
2b200 0a 3c 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61 6c 6c  .<i>M<sub><small
2b210 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f  >right</small></
2b220 73 75 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d 6e 73  sub></i> columns
2b230 2c 20 74 68 65 6e 20 74 68 65 20 63 61 72 74 65  , then the carte
2b240 73 69 61 6e 20 70 72 6f 64 75 63 74 20 69 73 20  sian product is 
2b250 61 0a 64 61 74 61 73 65 74 20 6f 66 20 0a 3c 69  a.dataset of .<i
2b260 3e 4e 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 6c 65  >N<sub><small>le
2b270 66 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e  ft</small></sub>
2b280 26 74 69 6d 65 73 3b 4e 3c 73 75 62 3e 3c 73 6d  &times;N<sub><sm
2b290 61 6c 6c 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c  all>right</small
2b2a0 3e 3c 2f 73 75 62 3e 3c 2f 69 3e 0a 72 6f 77 73  ></sub></i>.rows
2b2b0 2c 20 65 61 63 68 20 63 6f 6e 74 61 69 6e 69 6e  , each containin
2b2c0 67 20 0a 3c 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61  g .<i>M<sub><sma
2b2d0 6c 6c 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c  ll>left</small><
2b2e0 2f 73 75 62 3e 2b 4d 3c 73 75 62 3e 3c 73 6d 61  /sub>+M<sub><sma
2b2f0 6c 6c 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e  ll>right</small>
2b300 3c 2f 73 75 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d  </sub></i> colum
2b310 6e 73 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 74 68  ns.)^..<p>^If th
2b320 65 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20  e join-operator 
2b330 69 73 20 22 43 52 4f 53 53 20 4a 4f 49 4e 22 2c  is "CROSS JOIN",
2b340 20 22 49 4e 4e 45 52 20 4a 4f 49 4e 22 2c 20 22   "INNER JOIN", "
2b350 4a 4f 49 4e 22 20 6f 72 20 61 20 63 6f 6d 6d 61  JOIN" or a comma
2b360 0a 28 22 2c 22 29 20 61 6e 64 20 74 68 65 72 65  .(",") and there
2b370 20 69 73 20 6e 6f 20 4f 4e 20 6f 72 20 55 53 49   is no ON or USI
2b380 4e 47 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20  NG clause, then 
2b390 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
2b3a0 65 20 6a 6f 69 6e 20 69 73 0a 73 69 6d 70 6c 79  e join is.simply
2b3b0 20 74 68 65 20 63 61 72 74 65 73 69 61 6e 20 70   the cartesian p
2b3c0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 6c 65  roduct of the le
2b3d0 66 74 20 61 6e 64 20 72 69 67 68 74 2d 68 61 6e  ft and right-han
2b3e0 64 20 64 61 74 61 73 65 74 73 2e 20 0a 49 66 20  d datasets. .If 
2b3f0 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20 64 6f  join-operator do
2b400 65 73 20 68 61 76 65 20 4f 4e 20 6f 72 20 55 53  es have ON or US
2b410 49 4e 47 20 63 6c 61 75 73 65 73 2c 20 74 68 6f  ING clauses, tho
2b420 73 65 20 61 72 65 20 68 61 6e 64 6c 65 64 20 61  se are handled a
2b430 63 63 6f 72 64 69 6e 67 20 74 6f 0a 74 68 65 20  ccording to.the 
2b440 66 6f 6c 6c 6f 77 69 6e 67 20 62 75 6c 6c 65 74  following bullet
2b450 20 70 6f 69 6e 74 73 3a 0a 0a 3c 75 6c 3e 0a 20   points:..<ul>. 
2b460 20 3c 6c 69 3e 20 3c 70 3e 5e 28 49 66 20 74 68   <li> <p>^(If th
2b470 65 72 65 20 69 73 20 61 6e 20 4f 4e 20 63 6c 61  ere is an ON cla
2b480 75 73 65 20 74 68 65 6e 20 74 68 65 20 4f 4e 20  use then the ON 
2b490 65 78 70 72 65 73 73 69 6f 6e 20 69 73 0a 20 20  expression is.  
2b4a0 20 20 20 20 20 65 76 61 6c 75 61 74 65 64 20 66       evaluated f
2b4b0 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  or each row of t
2b4c0 68 65 20 63 61 72 74 65 73 69 61 6e 20 70 72 6f  he cartesian pro
2b4d0 64 75 63 74 20 61 73 20 61 20 0a 20 20 20 20 20  duct as a .     
2b4e0 20 20 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65    [boolean expre
2b4f0 73 73 69 6f 6e 5d 2e 20 4f 6e 6c 79 20 72 6f 77  ssion]. Only row
2b500 73 20 66 6f 72 20 77 68 69 63 68 20 74 68 65 20  s for which the 
2b510 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75  expression evalu
2b520 61 74 65 73 20 74 6f 20 0a 20 20 20 20 20 20 20  ates to .       
2b530 74 72 75 65 20 61 72 65 20 69 6e 63 6c 75 64 65  true are include
2b540 64 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 73  d from the datas
2b550 65 74 2e 29 5e 0a 0a 20 20 3c 6c 69 3e 20 3c 70  et.)^..  <li> <p
2b560 3e 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 20  >^If there is a 
2b570 55 53 49 4e 47 20 63 6c 61 75 73 65 0a 20 20 20  USING clause.   
2b580 20 20 20 20 74 68 65 6e 20 65 61 63 68 20 6f 66      then each of
2b590 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2b5a0 73 20 73 70 65 63 69 66 69 65 64 20 6d 75 73 74  s specified must
2b5b0 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 64 61   exist in the da
2b5c0 74 61 73 65 74 73 20 74 6f 20 0a 20 20 20 20 20  tasets to .     
2b5d0 20 20 62 6f 74 68 20 74 68 65 20 6c 65 66 74 20    both the left 
2b5e0 61 6e 64 20 72 69 67 68 74 20 6f 66 20 74 68 65  and right of the
2b5f0 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 2e 20   join-operator. 
2b600 5e 28 46 6f 72 20 65 61 63 68 20 70 61 69 72 20  ^(For each pair 
2b610 6f 66 20 6e 61 6d 65 64 0a 20 20 20 20 20 20 20  of named.       
2b620 63 6f 6c 75 6d 6e 73 2c 20 74 68 65 20 65 78 70  columns, the exp
2b630 72 65 73 73 69 6f 6e 20 22 6c 68 73 2e 58 20 3d  ression "lhs.X =
2b640 20 72 68 73 2e 58 22 20 69 73 20 65 76 61 6c 75   rhs.X" is evalu
2b650 61 74 65 64 20 66 6f 72 20 65 61 63 68 20 72 6f  ated for each ro
2b660 77 20 6f 66 0a 20 20 20 20 20 20 20 74 68 65 20  w of.       the 
2b670 63 61 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63  cartesian produc
2b680 74 20 61 73 20 61 20 5b 62 6f 6f 6c 65 61 6e 20  t as a [boolean 
2b690 65 78 70 72 65 73 73 69 6f 6e 5d 2e 20 4f 6e 6c  expression]. Onl
2b6a0 79 20 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68  y rows for which
2b6b0 0a 20 20 20 20 20 20 20 61 6c 6c 20 73 75 63 68  .       all such
2b6c0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76 61   expressions eva
2b6d0 6c 75 61 74 65 73 20 74 6f 20 74 72 75 65 20 61  luates to true a
2b6e0 72 65 20 69 6e 63 6c 75 64 65 64 20 66 72 6f 6d  re included from
2b6f0 20 74 68 65 0a 20 20 20 20 20 20 20 72 65 73 75   the.       resu
2b700 6c 74 20 73 65 74 2e 29 5e 20 5e 57 68 65 6e 20  lt set.)^ ^When 
2b710 63 6f 6d 70 61 72 69 6e 67 20 76 61 6c 75 65 73  comparing values
2b720 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2b730 61 20 55 53 49 4e 47 20 63 6c 61 75 73 65 2c 20  a USING clause, 
2b740 74 68 65 0a 20 20 20 20 20 20 20 6e 6f 72 6d 61  the.       norma
2b750 6c 20 72 75 6c 65 73 20 66 6f 72 20 68 61 6e 64  l rules for hand
2b760 6c 69 6e 67 20 61 66 66 69 6e 69 74 69 65 73 2c  ling affinities,
2b770 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b780 6e 63 65 73 20 61 6e 64 20 4e 55 4c 4c 0a 20 20  nces and NULL.  
2b790 20 20 20 20 20 76 61 6c 75 65 73 20 69 6e 20 63       values in c
2b7a0 6f 6d 70 61 72 69 73 6f 6e 73 20 61 70 70 6c 79  omparisons apply
2b7b0 2e 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 66 72  . ^The column fr
2b7c0 6f 6d 20 74 68 65 20 64 61 74 61 73 65 74 20 6f  om the dataset o
2b7d0 6e 20 74 68 65 0a 20 20 20 20 20 20 20 6c 65 66  n the.       lef
2b7e0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
2b7f0 68 65 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72  he join-operator
2b800 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
2b810 6f 20 62 65 20 6f 6e 20 74 68 65 20 6c 65 66 74  o be on the left
2b820 2d 68 61 6e 64 0a 20 20 20 20 20 20 20 73 69 64  -hand.       sid
2b830 65 20 6f 66 20 74 68 65 20 63 6f 6d 70 61 72 69  e of the compari
2b840 73 6f 6e 20 6f 70 65 72 61 74 6f 72 20 28 3d 29  son operator (=)
2b850 20 66 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   for the purpose
2b860 73 20 6f 66 20 63 6f 6c 6c 61 74 69 6f 6e 20 0a  s of collation .
2b870 20 20 20 20 20 20 20 73 65 71 75 65 6e 63 65 20         sequence 
2b880 61 6e 64 20 61 66 66 69 6e 69 74 79 20 70 72 65  and affinity pre
2b890 63 65 64 65 6e 63 65 2e 0a 0a 20 20 20 20 20 20  cedence...      
2b8a0 20 3c 70 3e 5e 46 6f 72 20 65 61 63 68 20 70 61   <p>^For each pa
2b8b0 69 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 64  ir of columns id
2b8c0 65 6e 74 69 66 69 65 64 20 62 79 20 61 20 55 53  entified by a US
2b8d0 49 4e 47 20 63 6c 61 75 73 65 2c 20 74 68 65 20  ING clause, the 
2b8e0 63 6f 6c 75 6d 6e 0a 20 20 20 20 20 20 20 66 72  column.       fr
2b8f0 6f 6d 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  om the right-han
2b900 64 20 64 61 74 61 73 65 74 20 69 73 20 6f 6d 69  d dataset is omi
2b910 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6a 6f  tted from the jo
2b920 69 6e 65 64 20 64 61 74 61 73 65 74 2e 20 5e 54  ined dataset. ^T
2b930 68 69 73 20 0a 20 20 20 20 20 20 20 69 73 20 74  his .       is t
2b940 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
2b950 63 65 20 62 65 74 77 65 65 6e 20 61 20 55 53 49  ce between a USI
2b960 4e 47 20 63 6c 61 75 73 65 20 61 6e 64 20 69 74  NG clause and it
2b970 73 20 65 71 75 69 76 61 6c 65 6e 74 20 4f 4e 0a  s equivalent ON.
2b980 20 20 20 20 20 20 20 63 6f 6e 73 74 72 61 69 6e         constrain
2b990 74 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5e 28  t...  <li> <p>^(
2b9a0 49 66 20 74 68 65 20 4e 41 54 55 52 41 4c 20 6b  If the NATURAL k
2b9b0 65 79 77 6f 72 64 20 69 73 20 69 6e 20 74 68 65  eyword is in the
2b9c0 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20 74   join-operator t
2b9d0 68 65 6e 20 61 6e 0a 20 20 20 20 20 20 20 69 6d  hen an.       im
2b9e0 70 6c 69 63 69 74 20 55 53 49 4e 47 20 63 6c 61  plicit USING cla
2b9f0 75 73 65 20 69 73 20 61 64 64 65 64 20 74 6f 20  use is added to 
2ba00 74 68 65 20 6a 6f 69 6e 2d 63 6f 6e 73 74 72 61  the join-constra
2ba10 69 6e 74 73 2e 20 54 68 65 20 69 6d 70 6c 69 63  ints. The implic
2ba20 69 74 0a 20 20 20 20 20 20 20 55 53 49 4e 47 20  it.       USING 
2ba30 63 6c 61 75 73 65 20 63 6f 6e 74 61 69 6e 73 20  clause contains 
2ba40 65 61 63 68 20 6f 66 20 74 68 65 20 63 6f 6c 75  each of the colu
2ba50 6d 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 61 70  mn names that ap
2ba60 70 65 61 72 20 69 6e 20 62 6f 74 68 0a 20 20 20  pear in both.   
2ba70 20 20 20 20 74 68 65 20 6c 65 66 74 20 61 6e 64      the left and
2ba80 20 72 69 67 68 74 2d 68 61 6e 64 20 69 6e 70 75   right-hand inpu
2ba90 74 20 64 61 74 61 73 65 74 73 2e 29 5e 20 5e 49  t datasets.)^ ^I
2baa0 66 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72  f the left and r
2bab0 69 67 68 74 2d 68 61 6e 64 0a 20 20 20 20 20 20  ight-hand.      
2bac0 20 69 6e 70 75 74 20 64 61 74 61 73 65 74 73 20   input datasets 
2bad0 66 65 61 74 75 72 65 20 6e 6f 20 63 6f 6d 6d 6f  feature no commo
2bae0 6e 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 2c 20  n column names, 
2baf0 74 68 65 6e 20 74 68 65 20 4e 41 54 55 52 41 4c  then the NATURAL
2bb00 20 6b 65 79 77 6f 72 64 0a 20 20 20 20 20 20 20   keyword.       
2bb10 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
2bb20 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
2bb30 74 68 65 20 6a 6f 69 6e 2e 20 5e 41 20 55 53 49  the join. ^A USI
2bb40 4e 47 20 6f 72 20 4f 4e 20 63 6c 61 75 73 65 20  NG or ON clause 
2bb50 6d 61 79 0a 20 20 20 20 20 20 20 6e 6f 74 20 62  may.       not b
2bb60 65 20 61 64 64 65 64 20 74 6f 20 61 20 6a 6f 69  e added to a joi
2bb70 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  n that specifies
2bb80 20 74 68 65 20 4e 41 54 55 52 41 4c 20 6b 65 79   the NATURAL key
2bb90 77 6f 72 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70  word...  <li> <p
2bba0 3e 5e 28 49 66 20 74 68 65 20 6a 6f 69 6e 2d 6f  >^(If the join-o
2bbb0 70 65 72 61 74 6f 72 20 69 73 20 61 20 22 4c 45  perator is a "LE
2bbc0 46 54 20 4a 4f 49 4e 22 20 6f 72 20 22 4c 45 46  FT JOIN" or "LEF
2bbd0 54 20 4f 55 54 45 52 20 4a 4f 49 4e 22 2c 20 74  T OUTER JOIN", t
2bbe0 68 65 6e 0a 20 20 20 20 20 20 20 61 66 74 65 72  hen.       after
2bbf0 0a 20 20 20 20 20 20 20 74 68 65 20 4f 4e 20 6f  .       the ON o
2bc00 72 20 55 53 49 4e 47 20 66 69 6c 74 65 72 69 6e  r USING filterin
2bc10 67 20 63 6c 61 75 73 65 73 20 68 61 76 65 20 62  g clauses have b
2bc20 65 65 6e 20 61 70 70 6c 69 65 64 2c 20 61 6e 20  een applied, an 
2bc30 65 78 74 72 61 20 72 6f 77 20 69 73 20 0a 20 20  extra row is .  
2bc40 20 20 20 20 20 61 64 64 65 64 20 74 6f 20 74 68       added to th
2bc50 65 20 6f 75 74 70 75 74 20 66 6f 72 20 65 61 63  e output for eac
2bc60 68 20 72 6f 77 20 69 6e 20 74 68 65 20 6f 72 69  h row in the ori
2bc70 67 69 6e 61 6c 20 6c 65 66 74 2d 68 61 6e 64 20  ginal left-hand 
2bc80 69 6e 70 75 74 20 0a 20 20 20 20 20 20 20 64 61  input .       da
2bc90 74 61 73 65 74 20 74 68 61 74 20 63 6f 72 72 65  taset that corre
2bca0 73 70 6f 6e 64 73 20 74 6f 20 6e 6f 20 72 6f 77  sponds to no row
2bcb0 73 20 61 74 20 61 6c 6c 20 69 6e 20 74 68 65 20  s at all in the 
2bcc0 63 6f 6d 70 6f 73 69 74 65 0a 20 20 20 20 20 20  composite.      
2bcd0 20 64 61 74 61 73 65 74 20 28 69 66 20 61 6e 79   dataset (if any
2bce0 29 2e 29 5e 20 5e 54 68 65 20 61 64 64 65 64 20  ).)^ ^The added 
2bcf0 72 6f 77 73 20 63 6f 6e 74 61 69 6e 20 4e 55 4c  rows contain NUL
2bd00 4c 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  L values in the 
2bd10 63 6f 6c 75 6d 6e 73 0a 20 20 20 20 20 20 20 74  columns.       t
2bd20 68 61 74 20 77 6f 75 6c 64 20 6e 6f 72 6d 61 6c  hat would normal
2bd30 6c 79 20 63 6f 6e 74 61 69 6e 20 76 61 6c 75 65  ly contain value
2bd40 73 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  s copied from th
2bd50 65 20 72 69 67 68 74 2d 68 61 6e 64 20 69 6e 70  e right-hand inp
2bd60 75 74 0a 20 20 20 20 20 20 20 64 61 74 61 73 65  ut.       datase
2bd70 74 2e 20 20 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e  t.  .</ul>..<p>^
2bd80 28 57 68 65 6e 20 6d 6f 72 65 20 74 68 61 6e 20  (When more than 
2bd90 74 77 6f 20 74 61 62 6c 65 73 20 61 72 65 20 6a  two tables are j
2bda0 6f 69 6e 65 64 20 74 6f 67 65 74 68 65 72 20 61  oined together a
2bdb0 73 20 70 61 72 74 20 6f 66 20 61 20 46 52 4f 4d  s part of a FROM
2bdc0 20 63 6c 61 75 73 65 2c 0a 74 68 65 20 6a 6f 69   clause,.the joi
2bdd0 6e 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  n operations are
2bde0 20 70 72 6f 63 65 73 73 65 64 20 69 6e 20 6f 72   processed in or
2bdf0 64 65 72 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f  der from left to
2be00 20 72 69 67 68 74 2e 20 49 6e 20 6f 74 68 65 72   right. In other
2be10 20 0a 77 6f 72 64 73 2c 20 74 68 65 20 46 52 4f   .words, the FRO
2be20 4d 20 63 6c 61 75 73 65 20 28 41 20 6a 6f 69 6e  M clause (A join
2be30 2d 6f 70 2d 31 20 42 20 6a 6f 69 6e 2d 6f 70 2d  -op-1 B join-op-
2be40 32 20 43 29 20 69 73 20 63 6f 6d 70 75 74 65 64  2 C) is computed
2be50 20 61 73 20 0a 28 28 41 20 6a 6f 69 6e 2d 6f 70   as .((A join-op
2be60 2d 31 20 42 29 20 6a 6f 69 6e 2d 6f 70 2d 32 20  -1 B) join-op-2 
2be70 43 29 2e 29 5e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  C).)^..<tcl>hd_f
2be80 72 61 67 6d 65 6e 74 20 63 72 6f 73 73 6a 6f 69  ragment crossjoi
2be90 6e 20 7b 74 72 65 61 74 73 20 74 68 65 20 43 52  n {treats the CR
2bea0 4f 53 53 20 4a 4f 49 4e 20 6f 70 65 72 61 74 6f  OSS JOIN operato
2beb0 72 20 73 70 65 63 69 61 6c 6c 79 7d 3c 2f 74 63  r specially}</tc
2bec0 6c 3e 0a 3c 70 3e 3c 62 3e 53 69 64 65 20 6e 6f  l>.<p><b>Side no
2bed0 74 65 3a 20 53 70 65 63 69 61 6c 20 68 61 6e 64  te: Special hand
2bee0 6c 69 6e 67 20 6f 66 20 43 52 4f 53 53 20 4a 4f  ling of CROSS JO
2bef0 49 4e 2e 3c 2f 62 3e 0a 5e 54 68 65 72 65 20 69  IN.</b>.^There i
2bf00 73 20 6e 6f 20 64 69 66 66 65 72 65 6e 63 65 20  s no difference 
2bf10 62 65 74 77 65 65 6e 20 74 68 65 20 22 49 4e 4e  between the "INN
2bf20 45 52 20 4a 4f 49 4e 22 2c 20 22 4a 4f 49 4e 22  ER JOIN", "JOIN"
2bf30 20 61 6e 64 20 22 2c 22 20 6a 6f 69 6e 0a 6f 70   and "," join.op
2bf40 65 72 61 74 6f 72 73 2e 20 54 68 65 79 20 61 72  erators. They ar
2bf50 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 69 6e 74  e completely int
2bf60 65 72 63 68 61 6e 67 65 61 62 6c 65 20 69 6e 20  erchangeable in 
2bf70 53 51 4c 69 74 65 2e 0a 5e 28 54 68 65 20 22 43  SQLite..^(The "C
2bf80 52 4f 53 53 20 4a 4f 49 4e 22 20 6a 6f 69 6e 20  ROSS JOIN" join 
2bf90 6f 70 65 72 61 74 6f 72 20 70 72 6f 64 75 63 65  operator produce
2bfa0 73 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  s the same resul
2bfb0 74 20 61 73 20 74 68 65 20 0a 22 49 4e 4e 45 52  t as the ."INNER
2bfc0 20 4a 4f 49 4e 22 2c 20 22 4a 4f 49 4e 22 20 61   JOIN", "JOIN" a
2bfd0 6e 64 20 22 2c 22 20 6f 70 65 72 61 74 6f 72 73  nd "," operators
2bfe0 29 5e 2c 20 62 75 74 20 69 73 20 0a 5b 43 52 4f  )^, but is .[CRO
2bff0 53 53 20 4a 4f 49 4e 7c 68 61 6e 64 6c 65 64 20  SS JOIN|handled 
2c000 64 69 66 66 65 72 65 6e 74 6c 79 20 62 79 20 74  differently by t
2c010 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
2c020 65 72 5d 0a 69 6e 20 74 68 61 74 20 69 74 20 70  er].in that it p
2c030 72 65 76 65 6e 74 73 20 74 68 65 20 71 75 65 72  revents the quer
2c040 79 20 6f 70 74 69 6d 69 7a 65 72 20 66 72 6f 6d  y optimizer from
2c050 20 72 65 6f 72 64 65 72 69 6e 67 0a 74 68 65 20   reordering.the 
2c060 74 61 62 6c 65 73 20 69 6e 20 74 68 65 20 6a 6f  tables in the jo
2c070 69 6e 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  in.  An applicat
2c080 69 6f 6e 20 70 72 6f 67 72 61 6d 6d 65 72 20 63  ion programmer c
2c090 61 6e 20 75 73 65 20 74 68 65 20 43 52 4f 53 53  an use the CROSS
2c0a0 20 4a 4f 49 4e 20 0a 6f 70 65 72 61 74 6f 72 20   JOIN .operator 
2c0b0 74 6f 20 64 69 72 65 63 74 6c 79 20 69 6e 66 6c  to directly infl
2c0c0 75 65 6e 63 65 20 74 68 65 20 61 6c 67 6f 72 69  uence the algori
2c0d0 74 68 6d 20 74 68 61 74 20 69 73 20 63 68 6f 73  thm that is chos
2c0e0 65 6e 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  en to implement.
2c0f0 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
2c100 6d 65 6e 74 2e 20 20 41 76 6f 69 64 20 75 73 69  ment.  Avoid usi
2c110 6e 67 20 43 52 4f 53 53 20 4a 4f 49 4e 20 65 78  ng CROSS JOIN ex
2c120 63 65 70 74 20 69 6e 20 73 70 65 63 69 66 69 63  cept in specific
2c130 20 73 69 74 75 61 74 69 6f 6e 73 20 0a 77 68 65   situations .whe
2c140 72 65 20 6d 61 6e 75 61 6c 20 63 6f 6e 74 72 6f  re manual contro
2c150 6c 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 6f  l of the query o
2c160 70 74 69 6d 69 7a 65 72 20 69 73 20 64 65 73 69  ptimizer is desi
2c170 72 65 64 2e 20 20 41 76 6f 69 64 20 75 73 69 6e  red.  Avoid usin
2c180 67 0a 43 52 4f 53 53 20 4a 4f 49 4e 20 65 61 72  g.CROSS JOIN ear
2c190 6c 79 20 69 6e 20 74 68 65 20 64 65 76 65 6c 6f  ly in the develo
2c1a0 70 6d 65 6e 74 20 6f 66 20 61 6e 20 61 70 70 6c  pment of an appl
2c1b0 69 63 61 74 69 6f 6e 20 61 73 20 64 6f 69 6e 67  ication as doing
2c1c0 20 73 6f 20 69 73 0a 61 20 3c 61 20 68 72 65 66   so is.a <a href
2c1d0 3d 22 68 74 74 70 3a 2f 2f 63 32 2e 63 6f 6d 2f  ="http://c2.com/
2c1e0 63 67 69 2f 77 69 6b 69 3f 50 72 65 6d 61 74 75  cgi/wiki?Prematu
2c1f0 72 65 4f 70 74 69 6d 69 7a 61 74 69 6f 6e 22 3e  reOptimization">
2c200 70 72 65 6d 61 74 75 72 65 0a 6f 70 74 69 6d 69  premature.optimi
2c210 7a 61 74 69 6f 6e 3c 2f 61 3e 2e 20 20 54 68 65  zation</a>.  The
2c220 20 73 70 65 63 69 61 6c 20 68 61 6e 64 6c 69 6e   special handlin
2c230 67 20 6f 66 20 43 52 4f 53 53 20 4a 4f 49 4e 20  g of CROSS JOIN 
2c240 69 73 20 61 6e 20 53 51 4c 69 74 65 2d 73 70 65  is an SQLite-spe
2c250 63 69 66 69 63 0a 66 65 61 74 75 72 65 20 61 6e  cific.feature an
2c260 64 20 69 73 20 6e 6f 74 20 61 20 70 61 72 74 20  d is not a part 
2c270 6f 66 20 73 74 61 6e 64 61 72 64 20 53 51 4c 2e  of standard SQL.
2c280 0a 20 20 20 20 20 20 20 0a 0a 3c 74 63 6c 3e 68  .       ..<tcl>h
2c290 64 5f 66 72 61 67 6d 65 6e 74 20 77 68 65 72 65  d_fragment where
2c2a0 63 6c 61 75 73 65 3c 2f 74 63 6c 3e 0a 3c 74 63  clause</tcl>.<tc
2c2b0 6c 3e 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b 57  l>hd_keywords {W
2c2c0 48 45 52 45 20 63 6c 61 75 73 65 7d 3c 2f 74 63  HERE clause}</tc
2c2d0 6c 3e 0a 3c 70 3e 3c 62 3e 32 2e 20 57 48 45 52  l>.<p><b>2. WHER
2c2e0 45 20 63 6c 61 75 73 65 20 66 69 6c 74 65 72 69  E clause filteri
2c2f0 6e 67 2e 3c 2f 62 3e 0a 0a 3c 70 3e 5e 28 49 66  ng.</b>..<p>^(If
2c300 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
2c310 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
2c320 65 20 57 48 45 52 45 20 65 78 70 72 65 73 73 69  e WHERE expressi
2c330 6f 6e 20 69 73 20 65 76 61 6c 75 61 74 65 64 20  on is evaluated 
2c340 66 6f 72 20 0a 65 61 63 68 20 72 6f 77 20 69 6e  for .each row in
2c350 20 74 68 65 20 69 6e 70 75 74 20 64 61 74 61 20   the input data 
2c360 61 73 20 61 20 5b 62 6f 6f 6c 65 61 6e 20 65 78  as a [boolean ex
2c370 70 72 65 73 73 69 6f 6e 5d 2e 20 4f 6e 6c 79 20  pression]. Only 
2c380 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68 20 74  rows for which t
2c390 68 65 0a 57 48 45 52 45 20 63 6c 61 75 73 65 20  he.WHERE clause 
2c3a0 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75  expression evalu
2c3b0 61 74 65 73 20 74 6f 20 74 72 75 65 20 61 72 65  ates to true are
2c3c0 20 69 6e 63 6c 75 64 65 64 20 66 72 6f 6d 20 74   included from t
2c3d0 68 65 20 64 61 74 61 73 65 74 20 62 65 66 6f 72  he dataset befor
2c3e0 65 0a 63 6f 6e 74 69 6e 75 69 6e 67 2e 29 5e 20  e.continuing.)^ 
2c3f0 20 52 6f 77 73 20 61 72 65 20 65 78 63 6c 75 64   Rows are exclud
2c400 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ed from the resu
2c410 6c 74 20 69 66 20 74 68 65 20 57 48 45 52 45 20  lt if the WHERE 
2c420 63 6c 61 75 73 65 0a 65 76 61 6c 75 61 74 65 73  clause.evaluates
2c430 20 74 6f 20 65 69 74 68 65 72 20 66 61 6c 73 65   to either false
2c440 20 6f 72 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 46 6f   or NULL...<p>Fo
2c450 72 20 61 20 4a 4f 49 4e 20 6f 72 20 49 4e 4e 45  r a JOIN or INNE
2c460 52 20 4a 4f 49 4e 20 6f 72 20 43 52 4f 53 53 20  R JOIN or CROSS 
2c470 4a 4f 49 4e 2c 20 74 68 65 72 65 20 69 73 20 6e  JOIN, there is n
2c480 6f 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  o difference bet
2c490 77 65 65 6e 20 0a 61 20 63 6f 6e 73 74 72 61 69  ween .a constrai
2c4a0 6e 74 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e  nt expression in
2c4b0 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
2c4c0 65 20 61 6e 64 20 6f 6e 65 20 69 6e 20 74 68 65  e and one in the
2c4d0 20 4f 4e 20 63 6c 61 75 73 65 2e 20 20 48 6f 77   ON clause.  How
2c4e0 65 76 65 72 2c 0a 66 6f 72 20 61 20 4c 45 46 54  ever,.for a LEFT
2c4f0 20 4a 4f 49 4e 20 6f 72 20 4c 45 46 54 20 4f 55   JOIN or LEFT OU
2c500 54 45 52 20 4a 4f 49 4e 2c 20 74 68 65 20 64 69  TER JOIN, the di
2c510 66 66 65 72 65 6e 63 65 20 69 73 20 76 65 72 79  fference is very
2c520 20 69 6d 70 6f 72 74 61 6e 74 2e 20 20 0a 49 6e   important.  .In
2c530 20 61 20 4c 45 46 54 20 4a 4f 49 4e 2c 0a 74 68   a LEFT JOIN,.th
2c540 65 20 65 78 74 72 61 20 4e 55 4c 4c 20 72 6f 77  e extra NULL row
2c550 20 66 6f 72 20 74 68 65 20 72 69 67 68 74 2d 68   for the right-h
2c560 61 6e 64 20 74 61 62 6c 65 20 69 73 20 61 64 64  and table is add
2c570 65 64 20 61 66 74 65 72 20 4f 4e 20 63 6c 61 75  ed after ON clau
2c580 73 65 20 70 72 6f 63 65 73 73 69 6e 67 0a 62 75  se processing.bu
2c590 74 20 62 65 66 6f 72 65 20 57 48 45 52 45 20 63  t before WHERE c
2c5a0 6c 61 75 73 65 20 70 72 6f 63 65 73 73 69 6e 67  lause processing
2c5b0 2e 20 20 41 20 63 6f 6e 73 74 72 61 69 6e 74 20  .  A constraint 
2c5c0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 6c 65 66  of the form "lef
2c5d0 74 2e 78 3d 72 69 67 68 74 2e 79 22 0a 69 6e 20  t.x=right.y".in 
2c5e0 61 6e 20 4f 4e 20 63 6c 61 75 73 65 20 77 69 6c  an ON clause wil
2c5f0 6c 20 74 68 65 72 65 66 6f 72 65 20 61 6c 6c 6f  l therefore allo
2c600 77 20 74 68 72 6f 75 67 68 20 74 68 65 20 61 64  w through the ad
2c610 64 65 64 20 61 6c 6c 2d 4e 55 4c 4c 20 72 6f 77  ded all-NULL row
2c620 73 20 6f 66 20 74 68 65 0a 72 69 67 68 74 20 74  s of the.right t
2c630 61 62 6c 65 2e 20 20 42 75 74 20 69 66 20 74 68  able.  But if th
2c640 61 74 20 73 61 6d 65 20 63 6f 6e 73 74 72 61 69  at same constrai
2c650 6e 74 20 69 73 20 69 6e 20 74 68 65 20 57 48 45  nt is in the WHE
2c660 52 45 20 63 6c 61 75 73 65 20 61 20 4e 55 4c 4c  RE clause a NULL
2c670 20 69 6e 0a 22 72 69 67 68 74 2e 79 22 20 77 69   in."right.y" wi
2c680 6c 6c 20 70 72 65 76 65 6e 74 20 74 68 65 20 65  ll prevent the e
2c690 78 70 72 65 73 73 69 6f 6e 20 22 6c 65 66 74 2e  xpression "left.
2c6a0 78 3d 72 69 67 68 74 2e 79 22 20 66 72 6f 6d 20  x=right.y" from 
2c6b0 62 65 69 6e 67 20 74 72 75 65 2c 20 61 6e 64 0a  being true, and.
2c6c0 74 68 75 73 20 65 78 63 6c 75 64 65 20 74 68 61  thus exclude tha
2c6d0 74 20 72 6f 77 20 66 72 6f 6d 20 74 68 65 20 6f  t row from the o
2c6e0 75 74 70 75 74 2e 0a 0a 3c 70 3e 3c 62 3e 33 2e  utput...<p><b>3.
2c6f0 20 47 65 6e 65 72 61 74 69 6f 6e 20 6f 66 20 74   Generation of t
2c700 68 65 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74  he set of result
2c710 20 72 6f 77 73 2e 3c 2f 62 3e 0a 3c 74 63 6c 3e   rows.</b>.<tcl>
2c720 68 64 5f 66 72 61 67 6d 65 6e 74 20 72 65 73 75  hd_fragment resu
2c730 6c 74 73 65 74 3c 2f 74 63 6c 3e 0a 3c 74 63 6c  ltset</tcl>.<tcl
2c740 3e 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b 72 65  >hd_keywords {re
2c750 73 75 6c 74 2d 73 65 74 20 65 78 70 72 65 73 73  sult-set express
2c760 69 6f 6e 73 7d 20 7b 47 52 4f 55 50 20 42 59 7d  ions} {GROUP BY}
2c770 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 4f 6e 63 65 20  </tcl>..<p>Once 
2c780 74 68 65 20 69 6e 70 75 74 20 64 61 74 61 20 66  the input data f
2c790 72 6f 6d 20 74 68 65 20 46 52 4f 4d 20 63 6c 61  rom the FROM cla
2c7a0 75 73 65 20 68 61 73 20 62 65 65 6e 20 66 69 6c  use has been fil
2c7b0 74 65 72 65 64 20 62 79 20 74 68 65 0a 57 48 45  tered by the.WHE
2c7c0 52 45 20 63 6c 61 75 73 65 20 65 78 70 72 65 73  RE clause expres
2c7d0 73 69 6f 6e 20 28 69 66 20 61 6e 79 29 2c 20 74  sion (if any), t
2c7e0 68 65 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74  he set of result
2c7f0 20 72 6f 77 73 20 66 6f 72 20 74 68 65 20 73 69   rows for the si
2c800 6d 70 6c 65 20 0a 53 45 4c 45 43 54 20 61 72 65  mple .SELECT are
2c810 20 63 61 6c 63 75 6c 61 74 65 64 2e 20 45 78 61   calculated. Exa
2c820 63 74 6c 79 20 68 6f 77 20 74 68 69 73 20 69 73  ctly how this is
2c830 20 64 6f 6e 65 20 64 65 70 65 6e 64 73 20 6f 6e   done depends on
2c840 20 77 68 65 74 68 65 72 20 74 68 65 20 73 69 6d   whether the sim
2c850 70 6c 65 20 0a 53 45 4c 45 43 54 20 69 73 20 61  ple .SELECT is a
2c860 6e 20 61 67 67 72 65 67 61 74 65 20 6f 72 20 6e  n aggregate or n
2c870 6f 6e 2d 61 67 67 72 65 67 61 74 65 20 71 75 65  on-aggregate que
2c880 72 79 2c 20 61 6e 64 20 77 68 65 74 68 65 72 20  ry, and whether 
2c890 6f 72 20 6e 6f 74 20 61 20 47 52 4f 55 50 0a 42  or not a GROUP.B
2c8a0 59 20 63 6c 61 75 73 65 20 77 61 73 20 73 70 65  Y clause was spe
2c8b0 63 69 66 69 65 64 2e 0a 0a 3c 70 3e 20 54 68 65  cified...<p> The
2c8c0 20 6c 69 73 74 20 6f 66 20 65 78 70 72 65 73 73   list of express
2c8d0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 74 68 65  ions between the
2c8e0 20 53 45 4c 45 43 54 20 61 6e 64 20 46 52 4f 4d   SELECT and FROM
2c8f0 20 6b 65 79 77 6f 72 64 73 20 69 73 20 6b 6e 6f   keywords is kno
2c900 77 6e 20 61 73 0a 74 68 65 20 72 65 73 75 6c 74  wn as.the result
2c910 20 65 78 70 72 65 73 73 69 6f 6e 20 6c 69 73 74   expression list
2c920 2e 20 20 5e 49 66 20 61 20 72 65 73 75 6c 74 20  .  ^If a result 
2c930 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 74 68  expression is th
2c940 65 20 73 70 65 63 69 61 6c 20 65 78 70 72 65 73  e special expres
2c950 73 69 6f 6e 0a 22 2a 22 20 74 68 65 6e 20 61 6c  sion."*" then al
2c960 6c 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  l columns in the
2c970 20 69 6e 70 75 74 20 64 61 74 61 20 61 72 65 20   input data are 
2c980 73 75 62 73 74 69 74 75 74 65 64 20 66 6f 72 20  substituted for 
2c990 74 68 61 74 20 6f 6e 65 20 65 78 70 72 65 73 73  that one express
2c9a0 69 6f 6e 2e 0a 5e 28 49 66 20 74 68 65 20 65 78  ion..^(If the ex
2c9b0 70 72 65 73 73 69 6f 6e 20 69 73 20 74 68 65 20  pression is the 
2c9c0 61 6c 69 61 73 20 6f 66 20 61 20 74 61 62 6c 65  alias of a table
2c9d0 20 6f 72 20 73 75 62 71 75 65 72 79 20 69 6e 20   or subquery in 
2c9e0 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 0a  the FROM clause.
2c9f0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 2e 2a 22  followed by ".*"
2ca00 20 74 68 65 6e 20 61 6c 6c 20 63 6f 6c 75 6d 6e   then all column
2ca10 73 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  s from the named
2ca20 20 74 61 62 6c 65 20 6f 72 20 73 75 62 71 75 65   table or subque
2ca30 72 79 20 61 72 65 0a 73 75 62 73 74 69 74 75 74  ry are.substitut
2ca40 65 64 20 66 6f 72 20 74 68 65 20 73 69 6e 67 6c  ed for the singl
2ca50 65 20 65 78 70 72 65 73 73 69 6f 6e 2e 29 5e 20  e expression.)^ 
2ca60 5e 28 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72  ^(It is an error
2ca70 20 74 6f 20 75 73 65 20 61 20 22 2a 22 20 6f 72   to use a "*" or
2ca80 0a 22 61 6c 69 61 73 2e 2a 22 20 65 78 70 72 65  ."alias.*" expre
2ca90 73 73 69 6f 6e 20 69 6e 20 61 6e 79 20 63 6f 6e  ssion in any con
2caa0 74 65 78 74 20 6f 74 68 65 72 20 74 68 61 6e 20  text other than 
2cab0 61 20 72 65 73 75 6c 74 20 65 78 70 72 65 73 73  a result express
2cac0 69 6f 6e 20 6c 69 73 74 2e 29 5e 0a 5e 28 49 74  ion list.)^.^(It
2cad0 20 69 73 20 61 6c 73 6f 20 61 6e 20 65 72 72 6f   is also an erro
2cae0 72 20 74 6f 20 75 73 65 20 61 20 22 2a 22 20 6f  r to use a "*" o
2caf0 72 20 22 61 6c 69 61 73 2e 2a 22 20 65 78 70 72  r "alias.*" expr
2cb00 65 73 73 69 6f 6e 20 69 6e 20 61 20 73 69 6d 70  ession in a simp
2cb10 6c 65 20 53 45 4c 45 43 54 0a 71 75 65 72 79 20  le SELECT.query 
2cb20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 68 61  that does not ha
2cb30 76 65 20 61 20 46 52 4f 4d 20 63 6c 61 75 73 65  ve a FROM clause
2cb40 2e 29 5e 0a 0a 3c 70 3e 20 5e 28 54 68 65 20 6e  .)^..<p> ^(The n
2cb50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2cb60 20 69 6e 20 74 68 65 20 72 6f 77 73 20 72 65 74   in the rows ret
2cb70 75 72 6e 65 64 20 62 79 20 61 20 73 69 6d 70 6c  urned by a simpl
2cb80 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
2cb90 6e 74 0a 69 73 20 65 71 75 61 6c 20 74 6f 20 74  nt.is equal to t
2cba0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 70  he number of exp
2cbb0 72 65 73 73 69 6f 6e 73 20 69 6e 20 74 68 65 20  ressions in the 
2cbc0 72 65 73 75 6c 74 20 65 78 70 72 65 73 73 69 6f  result expressio
2cbd0 6e 20 6c 69 73 74 20 61 66 74 65 72 0a 73 75 62  n list after.sub
2cbe0 73 74 69 74 75 74 69 6f 6e 20 6f 66 20 2a 20 61  stitution of * a
2cbf0 6e 64 20 61 6c 69 61 73 2e 2a 20 65 78 70 72 65  nd alias.* expre
2cc00 73 73 69 6f 6e 73 2e 29 5e 20 45 61 63 68 20 72  ssions.)^ Each r
2cc10 65 73 75 6c 74 20 72 6f 77 20 69 73 20 63 61 6c  esult row is cal
2cc20 63 75 6c 61 74 65 64 20 62 79 0a 65 76 61 6c 75  culated by.evalu
2cc30 61 74 69 6e 67 20 74 68 65 20 65 78 70 72 65 73  ating the expres
2cc40 73 69 6f 6e 73 20 69 6e 20 74 68 65 20 72 65 73  sions in the res
2cc50 75 6c 74 20 65 78 70 72 65 73 73 69 6f 6e 20 6c  ult expression l
2cc60 69 73 74 20 77 69 74 68 20 72 65 73 70 65 63 74  ist with respect
2cc70 20 74 6f 20 61 0a 73 69 6e 67 6c 65 20 72 6f 77   to a.single row
2cc80 20 6f 66 20 69 6e 70 75 74 20 64 61 74 61 20 6f   of input data o
2cc90 72 2c 20 66 6f 72 20 61 67 67 72 65 67 61 74 65  r, for aggregate
2cca0 20 71 75 65 72 69 65 73 2c 20 77 69 74 68 20 72   queries, with r
2ccb0 65 73 70 65 63 74 20 74 6f 20 61 20 67 72 6f 75  espect to a grou
2ccc0 70 0a 6f 66 20 72 6f 77 73 2e 0a 0a 3c 75 6c 3e  p.of rows...<ul>
2ccd0 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68  .  <li><p>^If th
2cce0 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
2ccf0 6e 74 20 69 73 20 3c 62 3e 61 20 6e 6f 6e 2d 61  nt is <b>a non-a
2cd00 67 67 72 65 67 61 74 65 20 71 75 65 72 79 3c 2f  ggregate query</
2cd10 62 3e 2c 20 74 68 65 6e 20 0a 20 20 20 20 65 61  b>, then .    ea
2cd20 63 68 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e  ch expression in
2cd30 20 74 68 65 20 72 65 73 75 6c 74 20 65 78 70 72   the result expr
2cd40 65 73 73 69 6f 6e 20 6c 69 73 74 20 69 73 20 65  ession list is e
2cd50 76 61 6c 75 61 74 65 64 20 66 6f 72 20 65 61 63  valuated for eac
2cd60 68 20 72 6f 77 20 69 6e 0a 20 20 20 20 74 68 65  h row in.    the
2cd70 20 64 61 74 61 73 65 74 20 66 69 6c 74 65 72 65   dataset filtere
2cd80 64 20 62 79 20 74 68 65 20 57 48 45 52 45 20 63  d by the WHERE c
2cd90 6c 61 75 73 65 2e 0a 0a 20 20 3c 6c 69 3e 3c 70  lause...  <li><p
2cda0 3e 5e 49 66 20 74 68 65 20 53 45 4c 45 43 54 20  >^If the SELECT 
2cdb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 3c 62 3e  statement is <b>
2cdc0 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
2cdd0 72 79 20 77 69 74 68 6f 75 74 20 61 20 47 52 4f  ry without a GRO
2cde0 55 50 0a 20 20 20 20 42 59 3c 2f 62 3e 20 63 6c  UP.    BY</b> cl
2cdf0 61 75 73 65 2c 20 74 68 65 6e 20 65 61 63 68 20  ause, then each 
2ce00 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73  aggregate expres
2ce10 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65 73 75  sion in the resu
2ce20 6c 74 2d 73 65 74 20 69 73 20 0a 20 20 20 20 65  lt-set is .    e
2ce30 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20 61 63  valuated once ac
2ce40 72 6f 73 73 20 74 68 65 20 65 6e 74 69 72 65 20  ross the entire 
2ce50 64 61 74 61 73 65 74 2e 20 5e 45 61 63 68 20 6e  dataset. ^Each n
2ce60 6f 6e 2d 61 67 67 72 65 67 61 74 65 20 65 78 70  on-aggregate exp
2ce70 72 65 73 73 69 6f 6e 0a 20 20 20 20 69 6e 20 74  ression.    in t
2ce80 68 65 20 72 65 73 75 6c 74 2d 73 65 74 20 69 73  he result-set is
2ce90 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20   evaluated once 
2cea0 66 6f 72 20 61 6e 20 61 72 62 69 74 72 61 72 69  for an arbitrari
2ceb0 6c 79 20 73 65 6c 65 63 74 65 64 20 72 6f 77 20  ly selected row 
2cec0 6f 66 0a 20 20 20 20 74 68 65 20 64 61 74 61 73  of.    the datas
2ced0 65 74 2e 20 5e 54 68 65 20 73 61 6d 65 20 61 72  et. ^The same ar
2cee0 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65 63 74  bitrarily select
2cef0 65 64 20 72 6f 77 20 69 73 20 75 73 65 64 20 66  ed row is used f
2cf00 6f 72 20 65 61 63 68 0a 20 20 20 20 6e 6f 6e 2d  or each.    non-
2cf10 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73  aggregate expres
2cf20 73 69 6f 6e 2e 20 5e 4f 72 2c 20 69 66 20 74 68  sion. ^Or, if th
2cf30 65 20 64 61 74 61 73 65 74 20 63 6f 6e 74 61 69  e dataset contai
2cf40 6e 73 20 7a 65 72 6f 20 72 6f 77 73 2c 20 74 68  ns zero rows, th
2cf50 65 6e 20 0a 20 20 20 20 65 61 63 68 20 6e 6f 6e  en .    each non
2cf60 2d 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65  -aggregate expre
2cf70 73 73 69 6f 6e 20 69 73 20 65 76 61 6c 75 61 74  ssion is evaluat
2cf80 65 64 20 61 67 61 69 6e 73 74 20 61 20 72 6f 77  ed against a row
2cf90 20 63 6f 6e 73 69 73 74 69 6e 67 0a 20 20 20 20   consisting.    
2cfa0 65 6e 74 69 72 65 6c 79 20 6f 66 20 4e 55 4c 4c  entirely of NULL
2cfb0 20 76 61 6c 75 65 73 2e 0a 0a 20 20 20 3c 70 3e   values...   <p>
2cfc0 5e 54 68 65 20 73 69 6e 67 6c 65 20 72 6f 77 20  ^The single row 
2cfd0 6f 66 20 72 65 73 75 6c 74 2d 73 65 74 20 64 61  of result-set da
2cfe0 74 61 20 63 72 65 61 74 65 64 20 62 79 20 65 76  ta created by ev
2cff0 61 6c 75 61 74 69 6e 67 20 74 68 65 20 61 67 67  aluating the agg
2d000 72 65 67 61 74 65 0a 20 20 20 20 61 6e 64 20 6e  regate.    and n
2d010 6f 6e 2d 61 67 67 72 65 67 61 74 65 20 65 78 70  on-aggregate exp
2d020 72 65 73 73 69 6f 6e 73 20 69 6e 20 74 68 65 20  ressions in the 
2d030 72 65 73 75 6c 74 2d 73 65 74 20 66 6f 72 6d 73  result-set forms
2d040 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61   the result of a
2d050 6e 0a 20 20 20 20 61 67 67 72 65 67 61 74 65 20  n.    aggregate 
2d060 71 75 65 72 79 20 77 69 74 68 6f 75 74 20 61 20  query without a 
2d070 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
2d080 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 71   ^An aggregate q
2d090 75 65 72 79 20 77 69 74 68 6f 75 74 20 61 0a 20  uery without a. 
2d0a0 20 20 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75     GROUP BY clau
2d0b0 73 65 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  se always return
2d0c0 73 20 65 78 61 63 74 6c 79 20 6f 6e 65 20 72 6f  s exactly one ro
2d0d0 77 20 6f 66 20 64 61 74 61 2c 20 65 76 65 6e 20  w of data, even 
2d0e0 69 66 20 74 68 65 72 65 20 61 72 65 0a 20 20 20  if there are.   
2d0f0 20 7a 65 72 6f 20 72 6f 77 73 20 6f 66 20 69 6e   zero rows of in
2d100 70 75 74 20 64 61 74 61 2e 0a 0a 20 20 3c 6c 69  put data...  <li
2d110 3e 3c 70 3e 5e 28 49 66 20 74 68 65 20 53 45 4c  ><p>^(If the SEL
2d120 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73  ECT statement is
2d130 20 3c 62 3e 61 6e 20 61 67 67 72 65 67 61 74 65   <b>an aggregate
2d140 20 71 75 65 72 79 20 77 69 74 68 20 61 20 47 52   query with a GR
2d150 4f 55 50 0a 20 20 20 20 42 59 3c 2f 62 3e 20 63  OUP.    BY</b> c
2d160 6c 61 75 73 65 2c 20 74 68 65 6e 20 65 61 63 68  lause, then each
2d170 20 6f 66 20 74 68 65 20 65 78 70 72 65 73 73 69   of the expressi
2d180 6f 6e 73 20 73 70 65 63 69 66 69 65 64 20 61 73  ons specified as
2d190 20 70 61 72 74 20 6f 66 20 74 68 65 0a 20 20 20   part of the.   
2d1a0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2d1b0 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 66 6f   is evaluated fo
2d1c0 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68  r each row of th
2d1d0 65 20 64 61 74 61 73 65 74 2e 20 45 61 63 68 20  e dataset. Each 
2d1e0 72 6f 77 0a 20 20 20 20 69 73 20 74 68 65 6e 20  row.    is then 
2d1f0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 22 67  assigned to a "g
2d200 72 6f 75 70 22 20 62 61 73 65 64 20 6f 6e 20 74  roup" based on t
2d210 68 65 20 72 65 73 75 6c 74 73 3b 20 72 6f 77 73  he results; rows
2d220 20 66 6f 72 20 77 68 69 63 68 0a 20 20 20 20 74   for which.    t
2d230 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 65 76  he results of ev
2d240 61 6c 75 61 74 69 6e 67 20 74 68 65 20 47 52 4f  aluating the GRO
2d250 55 50 20 42 59 20 65 78 70 72 65 73 73 69 6f 6e  UP BY expression
2d260 73 20 61 72 65 20 74 68 65 20 73 61 6d 65 20 67  s are the same g
2d270 65 74 0a 20 20 20 20 61 73 73 69 67 6e 65 64 20  et.    assigned 
2d280 74 6f 20 74 68 65 20 73 61 6d 65 20 67 72 6f 75  to the same grou
2d290 70 2e 29 5e 20 5e 46 6f 72 20 74 68 65 20 70 75  p.)^ ^For the pu
2d2a0 72 70 6f 73 65 73 20 6f 66 20 67 72 6f 75 70 69  rposes of groupi
2d2b0 6e 67 20 72 6f 77 73 2c 20 4e 55 4c 4c 20 0a 20  ng rows, NULL . 
2d2c0 20 20 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f     values are co
2d2d0 6e 73 69 64 65 72 65 64 20 65 71 75 61 6c 2e 20  nsidered equal. 
2d2e0 5e 54 68 65 20 75 73 75 61 6c 20 72 75 6c 65 73  ^The usual rules
2d2f0 20 66 6f 72 20 5b 63 6f 6c 6c 61 74 69 6f 6e 7c   for [collation|
2d300 73 65 6c 65 63 74 69 6e 67 20 61 0a 20 20 20 20  selecting a.    
2d310 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2d320 63 65 5d 20 77 69 74 68 20 77 68 69 63 68 20 74  ce] with which t
2d330 6f 20 63 6f 6d 70 61 72 65 20 74 65 78 74 20 76  o compare text v
2d340 61 6c 75 65 73 20 61 70 70 6c 79 20 77 68 65 6e  alues apply when
2d350 20 65 76 61 6c 75 61 74 69 6e 67 0a 20 20 20 20   evaluating.    
2d360 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61  expressions in a
2d370 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2d380 2e 20 20 5e 54 68 65 20 65 78 70 72 65 73 73 69  .  ^The expressi
2d390 6f 6e 73 20 69 6e 20 74 68 65 20 47 52 4f 55 50  ons in the GROUP
2d3a0 20 42 59 20 63 6c 61 75 73 65 0a 20 20 20 20 64   BY clause.    d
2d3b0 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 68  o <em>not</em> h
2d3c0 61 76 65 20 74 6f 20 62 65 20 65 78 70 72 65 73  ave to be expres
2d3d0 73 69 6f 6e 73 20 74 68 61 74 20 61 70 70 65 61  sions that appea
2d3e0 72 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  r in the result.
2d3f0 20 5e 54 68 65 0a 20 20 20 20 65 78 70 72 65 73   ^The.    expres
2d400 73 69 6f 6e 73 20 69 6e 20 61 20 47 52 4f 55 50  sions in a GROUP
2d410 20 42 59 20 63 6c 61 75 73 65 20 6d 61 79 20 6e   BY clause may n
2d420 6f 74 20 62 65 20 61 67 67 72 65 67 61 74 65 20  ot be aggregate 
2d430 65 78 70 72 65 73 73 69 6f 6e 73 2e 0a 0a 20 20  expressions...  
2d440 20 20 3c 70 3e 5e 28 49 66 20 61 20 48 41 56 49    <p>^(If a HAVI
2d450 4e 47 20 63 6c 61 75 73 65 20 69 73 20 73 70 65  NG clause is spe
2d460 63 69 66 69 65 64 2c 20 69 74 20 69 73 20 65 76  cified, it is ev
2d470 61 6c 75 61 74 65 64 20 6f 6e 63 65 20 66 6f 72  aluated once for
2d480 20 65 61 63 68 20 67 72 6f 75 70 20 0a 20 20 20   each group .   
2d490 20 6f 66 20 72 6f 77 73 20 61 73 20 61 20 5b 62   of rows as a [b
2d4a0 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f  oolean expressio
2d4b0 6e 5d 2e 20 49 66 20 74 68 65 20 72 65 73 75 6c  n]. If the resul
2d4c0 74 20 6f 66 20 65 76 61 6c 75 61 74 69 6e 67 20  t of evaluating 
2d4d0 74 68 65 0a 20 20 20 20 48 41 56 49 4e 47 20 63  the.    HAVING c
2d4e0 6c 61 75 73 65 20 69 73 20 66 61 6c 73 65 2c 20  lause is false, 
2d4f0 74 68 65 20 67 72 6f 75 70 20 69 73 20 64 69 73  the group is dis
2d500 63 61 72 64 65 64 2e 29 5e 20 5e 49 66 20 74 68  carded.)^ ^If th
2d510 65 20 48 41 56 49 4e 47 20 63 6c 61 75 73 65 20  e HAVING clause 
2d520 69 73 0a 20 20 20 20 61 6e 20 61 67 67 72 65 67  is.    an aggreg
2d530 61 74 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20  ate expression, 
2d540 69 74 20 69 73 20 65 76 61 6c 75 61 74 65 64 20  it is evaluated 
2d550 61 63 72 6f 73 73 20 61 6c 6c 20 72 6f 77 73 20  across all rows 
2d560 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 20 5e 49  in the group. ^I
2d570 66 0a 20 20 20 20 61 20 48 41 56 49 4e 47 20 63  f.    a HAVING c
2d580 6c 61 75 73 65 20 69 73 20 61 20 6e 6f 6e 2d 61  lause is a non-a
2d590 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73 73  ggregate express
2d5a0 69 6f 6e 2c 20 69 74 20 69 73 20 65 76 61 6c 75  ion, it is evalu
2d5b0 61 74 65 64 20 77 69 74 68 20 72 65 73 70 65 63  ated with respec
2d5c0 74 0a 20 20 20 20 74 6f 20 61 6e 20 61 72 62 69  t.    to an arbi
2d5d0 74 72 61 72 69 6c 79 20 73 65 6c 65 63 74 65 64  trarily selected
2d5e0 20 72 6f 77 20 66 72 6f 6d 20 74 68 65 20 67 72   row from the gr
2d5f0 6f 75 70 2e 20 20 5e 54 68 65 20 48 41 56 49 4e  oup.  ^The HAVIN
2d600 47 20 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 79  G expression may
2d610 0a 20 20 20 20 72 65 66 65 72 20 74 6f 20 76 61  .    refer to va
2d620 6c 75 65 73 2c 20 65 76 65 6e 20 61 67 67 72 65  lues, even aggre
2d630 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  gate functions, 
2d640 74 68 61 74 20 61 72 65 20 6e 6f 74 20 69 6e 20  that are not in 
2d650 74 68 65 20 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a  the result.</p>.
2d660 0a 20 20 20 20 3c 70 3e 5e 45 61 63 68 20 65 78  .    <p>^Each ex
2d670 70 72 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20  pression in the 
2d680 72 65 73 75 6c 74 2d 73 65 74 20 69 73 20 74 68  result-set is th
2d690 65 6e 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 63  en evaluated onc
2d6a0 65 20 66 6f 72 20 65 61 63 68 0a 20 20 20 20 67  e for each.    g
2d6b0 72 6f 75 70 20 6f 66 20 72 6f 77 73 2e 20 5e 49  roup of rows. ^I
2d6c0 66 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e  f the expression
2d6d0 20 69 73 20 61 6e 20 61 67 67 72 65 67 61 74 65   is an aggregate
2d6e0 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 74 20   expression, it 
2d6f0 69 73 20 0a 20 20 20 20 65 76 61 6c 75 61 74 65  is .    evaluate
2d700 64 20 61 63 72 6f 73 73 20 61 6c 6c 20 72 6f 77  d across all row
2d710 73 20 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 20  s in the group. 
2d720 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 74 20 69  ^Otherwise, it i
2d730 73 20 65 76 61 6c 75 61 74 65 64 20 61 67 61 69  s evaluated agai
2d740 6e 73 74 0a 20 20 20 20 61 20 73 69 6e 67 6c 65  nst.    a single
2d750 20 61 72 62 69 74 72 61 72 69 6c 79 20 63 68 6f   arbitrarily cho
2d760 73 65 6e 20 72 6f 77 20 66 72 6f 6d 20 77 69 74  sen row from wit
2d770 68 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 20 5e  hin the group. ^
2d780 49 66 20 74 68 65 72 65 20 69 73 20 6d 6f 72 65  If there is more
2d790 0a 20 20 20 20 74 68 61 6e 20 6f 6e 65 20 6e 6f  .    than one no
2d7a0 6e 2d 61 67 67 72 65 67 61 74 65 20 65 78 70 72  n-aggregate expr
2d7b0 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65  ession in the re
2d7c0 73 75 6c 74 2d 73 65 74 2c 20 74 68 65 6e 20 61  sult-set, then a
2d7d0 6c 6c 20 73 75 63 68 0a 20 20 20 20 65 78 70 72  ll such.    expr
2d7e0 65 73 73 69 6f 6e 73 20 61 72 65 20 65 76 61 6c  essions are eval
2d7f0 75 61 74 65 64 20 66 6f 72 20 74 68 65 20 73 61  uated for the sa
2d800 6d 65 20 72 6f 77 2e 0a 0a 20 20 20 20 3c 70 3e  me row...    <p>
2d810 5e 45 61 63 68 20 67 72 6f 75 70 20 6f 66 20 69  ^Each group of i
2d820 6e 70 75 74 20 64 61 74 61 73 65 74 20 72 6f 77  nput dataset row
2d830 73 20 63 6f 6e 74 72 69 62 75 74 65 73 20 61 20  s contributes a 
2d840 73 69 6e 67 6c 65 20 72 6f 77 20 74 6f 20 74 68  single row to th
2d850 65 20 0a 20 20 20 20 73 65 74 20 6f 66 20 72 65  e .    set of re
2d860 73 75 6c 74 20 72 6f 77 73 2e 20 5e 53 75 62 6a  sult rows. ^Subj
2d870 65 63 74 20 74 6f 20 66 69 6c 74 65 72 69 6e 67  ect to filtering
2d880 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d890 20 74 68 65 20 44 49 53 54 49 4e 43 54 0a 20 20   the DISTINCT.  
2d8a0 20 20 6b 65 79 77 6f 72 64 2c 20 74 68 65 20 6e    keyword, the n
2d8b0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65  umber of rows re
2d8c0 74 75 72 6e 65 64 20 62 79 20 61 6e 20 61 67 67  turned by an agg
2d8d0 72 65 67 61 74 65 20 71 75 65 72 79 20 77 69 74  regate query wit
2d8e0 68 20 61 20 47 52 4f 55 50 0a 20 20 20 20 42 59  h a GROUP.    BY
2d8f0 20 63 6c 61 75 73 65 20 69 73 20 74 68 65 20 73   clause is the s
2d900 61 6d 65 20 61 73 20 74 68 65 20 6e 75 6d 62 65  ame as the numbe
2d910 72 20 6f 66 20 67 72 6f 75 70 73 20 6f 66 20 72  r of groups of r
2d920 6f 77 73 20 70 72 6f 64 75 63 65 64 20 62 79 20  ows produced by 
2d930 61 70 70 6c 79 69 6e 67 0a 20 20 20 20 74 68 65  applying.    the
2d940 20 47 52 4f 55 50 20 42 59 20 61 6e 64 20 48 41   GROUP BY and HA
2d950 56 49 4e 47 20 63 6c 61 75 73 65 73 20 74 6f 20  VING clauses to 
2d960 74 68 65 20 66 69 6c 74 65 72 65 64 20 69 6e 70  the filtered inp
2d970 75 74 20 64 61 74 61 73 65 74 2e 0a 3c 2f 75 6c  ut dataset..</ul
2d980 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
2d990 65 6e 74 20 62 61 72 65 61 67 67 20 7b 62 61 72  ent bareagg {bar
2d9a0 65 20 61 67 67 72 65 67 61 74 65 20 74 65 72 6d  e aggregate term
2d9b0 73 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 3c 62 3e 53  s}</tcl>.<p><b>S
2d9c0 69 64 65 20 6e 6f 74 65 3a 20 42 61 72 65 20 63  ide note: Bare c
2d9d0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 61 67 67  olumns in an agg
2d9e0 72 65 67 61 74 65 20 71 75 65 72 69 65 73 2e 3c  regate queries.<
2d9f0 2f 62 3e 0a 54 68 65 20 75 73 75 61 6c 20 63 61  /b>.The usual ca
2da00 73 65 20 69 73 20 74 68 61 74 20 61 6c 6c 20 63  se is that all c
2da10 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 20 61  olumn names in a
2da20 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
2da30 79 20 61 72 65 20 65 69 74 68 65 72 0a 61 72 67  y are either.arg
2da40 75 6d 65 6e 74 73 20 74 6f 20 5b 61 67 67 66 75  uments to [aggfu
2da50 6e 63 7c 61 67 67 72 65 67 61 74 65 20 66 75 6e  nc|aggregate fun
2da60 63 74 69 6f 6e 73 5d 20 6f 72 20 65 6c 73 65 20  ctions] or else 
2da70 61 70 70 65 61 72 20 69 6e 20 74 68 65 20 47 52  appear in the GR
2da80 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 0a 41  OUP BY clause..A
2da90 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2daa0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 61 20  hich contains a 
2dab0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74  column name that
2dac0 20 69 73 20 6e 6f 74 20 77 69 74 68 69 6e 20 61   is not within a
2dad0 6e 0a 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n.aggregate func
2dae0 74 69 6f 6e 20 61 6e 64 20 74 68 61 74 20 64 6f  tion and that do
2daf0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e  es not appear in
2db00 20 74 68 65 20 47 52 4f 55 50 20 42 59 20 63 6c   the GROUP BY cl
2db10 61 75 73 65 20 28 69 66 0a 6f 6e 65 20 65 78 69  ause (if.one exi
2db20 73 74 73 29 20 69 73 20 63 61 6c 6c 65 64 20 61  sts) is called a
2db30 20 22 62 61 72 65 22 20 63 6f 6c 75 6d 6e 2e 0a   "bare" column..
2db40 45 78 61 6d 70 6c 65 3a 0a 3c 62 6c 6f 63 6b 71  Example:.<blockq
2db50 75 6f 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45 43  uote><pre>.SELEC
2db60 54 20 61 2c 20 62 2c 20 73 75 6d 28 63 29 20 46  T a, b, sum(c) F
2db70 52 4f 4d 20 74 61 62 31 20 47 52 4f 55 50 20 42  ROM tab1 GROUP B
2db80 59 20 61 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  Y a;.</pre></blo
2db90 63 6b 71 75 6f 74 65 3e 0a 3c 70 3e 49 6e 20 74  ckquote>.<p>In t
2dba0 68 65 20 71 75 65 72 79 20 61 62 6f 76 65 2c 20  he query above, 
2dbb0 74 68 65 20 22 61 22 20 63 6f 6c 75 6d 6e 20 69  the "a" column i
2dbc0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 47 52  s part of the GR
2dbd0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 0a 61 6e  OUP BY clause.an
2dbe0 64 20 73 6f 20 65 61 63 68 20 72 6f 77 20 6f 66  d so each row of
2dbf0 20 74 68 65 20 6f 75 74 70 75 74 20 63 6f 6e 74   the output cont
2dc00 61 69 6e 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  ains one of the 
2dc10 64 69 73 74 69 6e 63 74 20 76 61 6c 75 65 73 20  distinct values 
2dc20 66 6f 72 0a 22 61 22 2e 20 20 54 68 65 20 22 63  for."a".  The "c
2dc30 22 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6e 74  " column is cont
2dc40 61 69 6e 65 64 20 77 69 74 68 69 6e 20 74 68 65  ained within the
2dc50 20 5b 73 75 6d 28 29 5d 20 61 67 67 72 65 67 61   [sum()] aggrega
2dc60 74 65 20 66 75 6e 63 74 69 6f 6e 0a 61 6e 64 20  te function.and 
2dc70 73 6f 20 74 68 61 74 20 6f 75 74 70 75 74 20 63  so that output c
2dc80 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 73 75 6d  olumn is the sum
2dc90 20 6f 66 20 61 6c 6c 20 22 63 22 20 76 61 6c 75   of all "c" valu
2dca0 65 73 20 69 6e 20 72 6f 77 73 20 74 68 61 74 0a  es in rows that.
2dcb0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 76 61  have the same va
2dcc0 6c 75 65 20 66 6f 72 20 22 61 22 2e 20 20 42 75  lue for "a".  Bu
2dcd0 74 20 77 68 61 74 20 69 73 20 74 68 65 20 72 65  t what is the re
2dce0 73 75 6c 74 20 6f 66 20 74 68 65 20 62 61 72 65  sult of the bare
2dcf0 20 0a 63 6f 6c 75 6d 6e 20 22 62 22 3f 20 54 68   .column "b"? Th
2dd00 65 20 61 6e 73 77 65 72 20 69 73 20 74 68 61 74  e answer is that
2dd10 20 74 68 65 20 22 62 22 20 72 65 73 75 6c 74 20   the "b" result 
2dd20 77 69 6c 6c 20 62 65 20 74 68 65 0a 76 61 6c 75  will be the.valu
2dd30 65 20 66 6f 72 20 22 62 22 20 69 6e 20 6f 6e 65  e for "b" in one
2dd40 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 72 6f   of the input ro
2dd50 77 73 20 74 68 61 74 20 66 6f 72 6d 20 74 68 65  ws that form the
2dd60 20 61 67 67 72 65 67 61 74 65 2e 0a 54 68 65 20   aggregate..The 
2dd70 70 72 6f 62 6c 65 6d 20 69 73 20 74 68 61 74 20  problem is that 
2dd80 79 6f 75 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  you usually do n
2dd90 6f 74 20 6b 6e 6f 77 20 77 68 69 63 68 20 69 6e  ot know which in
2dda0 70 75 74 20 72 6f 77 20 69 73 20 75 73 65 64 0a  put row is used.
2ddb0 74 6f 20 63 6f 6d 70 75 74 65 20 22 62 22 2c 20  to compute "b", 
2ddc0 61 6e 64 20 73 6f 20 69 6e 20 6d 61 6e 79 20 63  and so in many c
2ddd0 61 73 65 73 20 74 68 65 20 76 61 6c 75 65 20 66  ases the value f
2dde0 6f 72 20 22 62 22 20 69 73 20 75 6e 64 65 66 69  or "b" is undefi
2ddf0 6e 65 64 2e 0a 3c 2f 70 3e 0a 3c 70 3e 0a 53 70  ned..</p>.<p>.Sp
2de00 65 63 69 61 6c 20 70 72 6f 63 65 73 73 69 6e 67  ecial processing
2de10 20 6f 63 63 75 72 73 20 6f 63 63 75 72 73 20 77   occurs occurs w
2de20 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2de30 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 0a 65  e function is .e
2de40 69 74 68 65 72 20 5b 6d 61 78 41 67 67 46 75 6e  ither [maxAggFun
2de50 63 7c 6d 69 6e 28 29 5d 20 6f 72 20 5b 6d 69 6e  c|min()] or [min
2de60 41 67 67 46 75 6e 63 7c 6d 61 78 28 29 5d 2e 20  AggFunc|max()]. 
2de70 20 45 78 61 6d 70 6c 65 3a 0a 3c 62 6c 6f 63 6b   Example:.<block
2de80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45  quote><pre>.SELE
2de90 43 54 20 61 2c 20 62 2c 20 6d 61 78 28 63 29 20  CT a, b, max(c) 
2dea0 46 52 4f 4d 20 74 61 62 31 20 47 52 4f 55 50 20  FROM tab1 GROUP 
2deb0 42 59 20 61 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  BY a;.</pre></bl
2dec0 6f 63 6b 71 75 6f 74 65 3e 0a 57 68 65 6e 20 74  ockquote>.When t
2ded0 68 65 20 5b 6d 61 78 41 67 67 46 75 6e 63 7c 6d  he [maxAggFunc|m
2dee0 69 6e 28 29 5d 20 6f 72 20 5b 6d 69 6e 41 67 67  in()] or [minAgg
2def0 46 75 6e 63 7c 6d 61 78 28 29 5d 20 61 67 67 72  Func|max()] aggr
2df00 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  egate functions 
2df10 0a 61 72 65 20 75 73 65 64 20 69 6e 20 61 6e 20  .are used in an 
2df20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
2df30 20 61 6c 6c 20 62 61 72 65 20 63 6f 6c 75 6d 6e   all bare column
2df40 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2df50 73 65 74 20 0a 74 61 6b 65 20 76 61 6c 75 65 73  set .take values
2df60 20 66 72 6f 6d 20 74 68 65 20 69 6e 70 75 74 0a   from the input.
2df70 72 6f 77 20 77 68 69 63 68 20 61 6c 73 6f 20 63  row which also c
2df80 6f 6e 74 61 69 6e 73 20 74 68 65 20 6d 69 6e 69  ontains the mini
2df90 6d 75 6d 20 6f 72 20 6d 61 78 69 6d 75 6d 2e 20  mum or maximum. 
2dfa0 20 53 6f 20 69 6e 20 74 68 65 20 71 75 65 72 79   So in the query
2dfb0 0a 61 62 6f 76 65 2c 20 74 68 65 20 76 61 6c 75  .above, the valu
2dfc0 65 20 6f 66 20 74 68 65 20 22 62 22 20 63 6f 6c  e of the "b" col
2dfd0 75 6d 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  umn in the outpu
2dfe0 74 20 77 69 6c 6c 20 62 65 20 74 68 65 20 76 61  t will be the va
2dff0 6c 75 65 20 6f 66 0a 74 68 65 20 22 62 22 20 63  lue of.the "b" c
2e000 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 69 6e 70  olumn in the inp
2e010 75 74 20 72 6f 77 20 74 68 61 74 20 68 61 73 20  ut row that has 
2e020 74 68 65 20 6c 61 72 67 65 73 74 20 22 63 22 20  the largest "c" 
2e030 76 61 6c 75 65 2e 0a 54 68 65 72 65 20 69 73 20  value..There is 
2e040 73 74 69 6c 6c 20 61 6e 20 61 6d 62 69 67 75 69  still an ambigui
2e050 74 79 20 69 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ty if two or mor
2e060 65 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 72  e of the input r
2e070 6f 77 73 20 68 61 76 65 20 74 68 65 0a 73 61 6d  ows have the.sam
2e080 65 20 6d 69 6e 69 6d 75 6d 20 6f 72 20 6d 61 78  e minimum or max
2e090 69 6d 75 6d 20 76 61 6c 75 65 20 6f 72 20 69 66  imum value or if
2e0a0 20 74 68 65 20 71 75 65 72 79 20 63 6f 6e 74 61   the query conta
2e0b0 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ins more than on
2e0c0 65 0a 6d 69 6e 28 29 20 61 6e 64 2f 6f 72 20 6d  e.min() and/or m
2e0d0 61 78 28 29 20 61 67 67 72 65 67 61 74 65 20 66  ax() aggregate f
2e0e0 75 6e 63 74 69 6f 6e 2e 20 4f 6e 6c 79 20 74 68  unction. Only th
2e0f0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 6d 69 6e 41  e built-in [minA
2e100 67 67 46 75 6e 63 7c 6d 69 6e 28 29 5d 20 0a 61  ggFunc|min()] .a
2e110 6e 64 20 5b 6d 61 78 41 67 67 46 75 6e 63 7c 6d  nd [maxAggFunc|m
2e120 61 78 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20  ax()] functions 
2e130 77 6f 72 6b 20 74 68 69 73 20 77 61 79 2e 0a 3c  work this way..<
2e140 2f 70 3e 0a 0a 3c 70 3e 3c 62 3e 34 2e 20 52 65  /p>..<p><b>4. Re
2e150 6d 6f 76 61 6c 20 6f 66 20 64 75 70 6c 69 63 61  moval of duplica
2e160 74 65 20 72 6f 77 73 20 28 44 49 53 54 49 4e 43  te rows (DISTINC
2e170 54 20 70 72 6f 63 65 73 73 69 6e 67 29 2e 3c 2f  T processing).</
2e180 62 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  b>.<tcl>hd_fragm
2e190 65 6e 74 20 64 69 73 74 69 6e 63 74 3c 2f 74 63  ent distinct</tc
2e1a0 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f  l>.<tcl>hd_keywo
2e1b0 72 64 73 20 7b 44 49 53 54 49 4e 43 54 7d 3c 2f  rds {DISTINCT}</
2e1c0 74 63 6c 3e 0a 0a 3c 70 3e 5e 4f 6e 65 20 6f 66  tcl>..<p>^One of
2e1d0 20 74 68 65 20 41 4c 4c 20 6f 72 20 44 49 53 54   the ALL or DIST
2e1e0 49 4e 43 54 20 6b 65 79 77 6f 72 64 73 20 6d 61  INCT keywords ma
2e1f0 79 20 66 6f 6c 6c 6f 77 20 74 68 65 20 53 45 4c  y follow the SEL
2e200 45 43 54 20 6b 65 79 77 6f 72 64 20 69 6e 20 61  ECT keyword in a
2e210 20 0a 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20   .simple SELECT 
2e220 73 74 61 74 65 6d 65 6e 74 2e 20 5e 49 66 20 74  statement. ^If t
2e230 68 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54  he simple SELECT
2e240 20 69 73 20 61 20 53 45 4c 45 43 54 20 41 4c 4c   is a SELECT ALL
2e250 2c 20 74 68 65 6e 20 74 68 65 0a 65 6e 74 69 72  , then the.entir
2e260 65 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20  e set of result 
2e270 72 6f 77 73 20 61 72 65 20 72 65 74 75 72 6e 65  rows are returne
2e280 64 20 62 79 20 74 68 65 20 53 45 4c 45 43 54 2e  d by the SELECT.
2e290 20 5e 49 66 20 6e 65 69 74 68 65 72 20 41 4c 4c   ^If neither ALL
2e2a0 20 6f 72 0a 44 49 53 54 49 4e 43 54 20 61 72 65   or.DISTINCT are
2e2b0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
2e2c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61  he behavior is a
2e2d0 73 20 69 66 20 41 4c 4c 20 77 65 72 65 20 73 70  s if ALL were sp
2e2e0 65 63 69 66 69 65 64 2e 20 0a 5e 49 66 20 74 68  ecified. .^If th
2e2f0 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20  e simple SELECT 
2e300 69 73 20 61 20 53 45 4c 45 43 54 20 44 49 53 54  is a SELECT DIST
2e310 49 4e 43 54 2c 20 74 68 65 6e 20 64 75 70 6c 69  INCT, then dupli
2e320 63 61 74 65 20 72 6f 77 73 20 61 72 65 20 72 65  cate rows are re
2e330 6d 6f 76 65 64 0a 66 72 6f 6d 20 74 68 65 20 73  moved.from the s
2e340 65 74 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  et of result row
2e350 73 20 62 65 66 6f 72 65 20 69 74 20 69 73 20 72  s before it is r
2e360 65 74 75 72 6e 65 64 2e 20 5e 46 6f 72 20 74 68  eturned. ^For th
2e370 65 20 70 75 72 70 6f 73 65 73 20 6f 66 0a 64 65  e purposes of.de
2e380 74 65 63 74 69 6e 67 20 64 75 70 6c 69 63 61 74  tecting duplicat
2e390 65 20 72 6f 77 73 2c 20 74 77 6f 20 4e 55 4c 4c  e rows, two NULL
2e3a0 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f 6e 73   values are cons
2e3b0 69 64 65 72 65 64 20 74 6f 20 62 65 20 65 71 75  idered to be equ
2e3c0 61 6c 2e 20 5e 54 68 65 0a 5b 68 6f 77 20 63 6f  al. ^The.[how co
2e3d0 6c 6c 61 74 69 6f 6e 20 69 73 20 64 65 74 65 72  llation is deter
2e3e0 6d 69 6e 65 64 7c 75 73 75 61 6c 20 72 75 6c 65  mined|usual rule
2e3f0 73 5d 20 61 70 70 6c 79 20 66 6f 72 20 73 65 6c  s] apply for sel
2e400 65 63 74 69 6e 67 20 61 20 63 6f 6c 6c 61 74 69  ecting a collati
2e410 6f 6e 0a 73 65 71 75 65 6e 63 65 20 74 6f 20 63  on.sequence to c
2e420 6f 6d 70 61 72 65 20 74 65 78 74 20 76 61 6c 75  ompare text valu
2e430 65 73 2e 0a 0a 3c 74 63 6c 3e 0a 68 64 5f 66 72  es...<tcl>.hd_fr
2e440 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 75 6e 64 20  agment compound 
2e450 7b 63 6f 6d 70 6f 75 6e 64 20 73 65 6c 65 63 74  {compound select
2e460 7d 20 7b 63 6f 6d 70 6f 75 6e 64 20 71 75 65 72  } {compound quer
2e470 79 7d 20 7b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  y} {compound SEL
2e480 45 43 54 7d 20 7b 63 6f 6d 70 6f 75 6e 64 20 53  ECT} {compound S
2e490 45 4c 45 43 54 73 7d 0a 3c 2f 74 63 6c 3e 0a 3c  ELECTs}.</tcl>.<
2e4a0 68 33 3e 43 6f 6d 70 6f 75 6e 64 20 53 65 6c 65  h3>Compound Sele
2e4b0 63 74 20 53 74 61 74 65 6d 65 6e 74 73 3c 2f 68  ct Statements</h
2e4c0 33 3e 0a 0a 3c 70 3e 54 77 6f 20 6f 72 20 6d 6f  3>..<p>Two or mo
2e4d0 72 65 20 5b 73 69 6d 70 6c 65 20 53 45 4c 45 43  re [simple SELEC
2e4e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 61  T] statements ma
2e4f0 79 20 62 65 20 63 6f 6e 6e 65 63 74 65 64 20 74  y be connected t
2e500 6f 67 65 74 68 65 72 20 74 6f 20 66 6f 72 6d 0a  ogether to form.
2e510 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
2e520 54 20 75 73 69 6e 67 20 74 68 65 20 55 4e 49 4f  T using the UNIO
2e530 4e 2c 20 55 4e 49 4f 4e 20 41 4c 4c 2c 20 49 4e  N, UNION ALL, IN
2e540 54 45 52 53 45 43 54 20 6f 72 20 45 58 43 45 50  TERSECT or EXCEP
2e550 54 20 6f 70 65 72 61 74 6f 72 2c 0a 61 73 20 73  T operator,.as s
2e560 68 6f 77 6e 20 62 79 20 74 68 65 20 66 6f 6c 6c  hown by the foll
2e570 6f 77 69 6e 67 20 64 69 61 67 72 61 6d 3a 0a 0a  owing diagram:..
2e580 3c 74 63 6c 3e 0a 52 65 63 75 72 73 69 76 65 42  <tcl>.RecursiveB
2e590 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 6f 6d  ubbleDiagram com
2e5a0 70 6f 75 6e 64 2d 73 65 6c 65 63 74 2d 73 74 6d  pound-select-stm
2e5b0 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 49 6e  t.</tcl>..<p>^In
2e5c0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2e5d0 43 54 2c 20 61 6c 6c 20 74 68 65 20 63 6f 6e 73  CT, all the cons
2e5e0 74 69 74 75 65 6e 74 20 53 45 4c 45 43 54 73 20  tituent SELECTs 
2e5f0 6d 75 73 74 20 72 65 74 75 72 6e 20 74 68 65 20  must return the 
2e600 73 61 6d 65 20 0a 6e 75 6d 62 65 72 20 6f 66 20  same .number of 
2e610 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 2e 20  result columns. 
2e620 5e 41 73 20 74 68 65 20 63 6f 6d 70 6f 6e 65 6e  ^As the componen
2e630 74 73 20 6f 66 20 61 20 63 6f 6d 70 6f 75 6e 64  ts of a compound
2e640 20 53 45 4c 45 43 54 20 6d 75 73 74 0a 62 65 20   SELECT must.be 
2e650 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 73 74  simple SELECT st
2e660 61 74 65 6d 65 6e 74 73 2c 20 74 68 65 79 20 6d  atements, they m
2e670 61 79 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 5b  ay not contain [
2e680 4f 52 44 45 52 20 42 59 5d 20 6f 72 20 5b 4c 49  ORDER BY] or [LI
2e690 4d 49 54 5d 20 63 6c 61 75 73 65 73 2e 0a 5e 5b  MIT] clauses..^[
2e6a0 4f 52 44 45 52 20 42 59 5d 20 61 6e 64 20 5b 4c  ORDER BY] and [L
2e6b0 49 4d 49 54 5d 20 63 6c 61 75 73 65 73 20 6d 61  IMIT] clauses ma
2e6c0 79 20 6f 6e 6c 79 20 6f 63 63 75 72 20 61 74 20  y only occur at 
2e6d0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 65  the end of the e
2e6e0 6e 74 69 72 65 20 63 6f 6d 70 6f 75 6e 64 0a 53  ntire compound.S
2e6f0 45 4c 45 43 54 2c 20 61 6e 64 20 74 68 65 6e 20  ELECT, and then 
2e700 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6e 61  only if the fina
2e710 6c 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  l element of the
2e720 20 63 6f 6d 70 6f 75 6e 64 20 69 73 20 6e 6f 74   compound is not
2e730 20 61 20 5b 56 41 4c 55 45 53 5d 20 63 6c 61 75   a [VALUES] clau
2e740 73 65 2e 0a 0a 3c 70 3e 5e 41 20 63 6f 6d 70 6f  se...<p>^A compo
2e750 75 6e 64 20 53 45 4c 45 43 54 20 63 72 65 61 74  und SELECT creat
2e760 65 64 20 75 73 69 6e 67 20 55 4e 49 4f 4e 20 41  ed using UNION A
2e770 4c 4c 20 6f 70 65 72 61 74 6f 72 20 72 65 74 75  LL operator retu
2e780 72 6e 73 20 61 6c 6c 20 74 68 65 20 72 6f 77 73  rns all the rows
2e790 0a 66 72 6f 6d 20 74 68 65 20 53 45 4c 45 43 54  .from the SELECT
2e7a0 20 74 6f 20 74 68 65 20 6c 65 66 74 20 6f 66 20   to the left of 
2e7b0 74 68 65 20 55 4e 49 4f 4e 20 41 4c 4c 20 6f 70  the UNION ALL op
2e7c0 65 72 61 74 6f 72 2c 20 61 6e 64 20 61 6c 6c 20  erator, and all 
2e7d0 74 68 65 20 72 6f 77 73 0a 66 72 6f 6d 20 74 68  the rows.from th
2e7e0 65 20 53 45 4c 45 43 54 20 74 6f 20 74 68 65 20  e SELECT to the 
2e7f0 72 69 67 68 74 20 6f 66 20 69 74 2e 20 5e 54 68  right of it. ^Th
2e800 65 20 55 4e 49 4f 4e 20 6f 70 65 72 61 74 6f 72  e UNION operator
2e810 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
2e820 77 61 79 20 61 73 0a 55 4e 49 4f 4e 20 41 4c 4c  way as.UNION ALL
2e830 2c 20 65 78 63 65 70 74 20 74 68 61 74 20 64 75  , except that du
2e840 70 6c 69 63 61 74 65 20 72 6f 77 73 20 61 72 65  plicate rows are
2e850 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74 68   removed from th
2e860 65 20 66 69 6e 61 6c 20 72 65 73 75 6c 74 20 73  e final result s
2e870 65 74 2e 0a 5e 54 68 65 20 49 4e 54 45 52 53 45  et..^The INTERSE
2e880 43 54 20 6f 70 65 72 61 74 6f 72 20 72 65 74 75  CT operator retu
2e890 72 6e 73 20 74 68 65 20 69 6e 74 65 72 73 65 63  rns the intersec
2e8a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 73 75  tion of the resu
2e8b0 6c 74 73 20 6f 66 20 74 68 65 20 6c 65 66 74 20  lts of the left 
2e8c0 61 6e 64 0a 72 69 67 68 74 20 53 45 4c 45 43 54  and.right SELECT
2e8d0 73 2e 20 20 5e 54 68 65 20 45 58 43 45 50 54 20  s.  ^The EXCEPT 
2e8e0 6f 70 65 72 61 74 6f 72 20 72 65 74 75 72 6e 73  operator returns
2e8f0 20 74 68 65 20 73 75 62 73 65 74 20 6f 66 20 72   the subset of r
2e900 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ows returned by 
2e910 74 68 65 0a 6c 65 66 74 20 53 45 4c 45 43 54 20  the.left SELECT 
2e920 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 6c 73  that are not als
2e930 6f 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  o returned by th
2e940 65 20 72 69 67 68 74 2d 68 61 6e 64 20 53 45 4c  e right-hand SEL
2e950 45 43 54 2e 20 5e 44 75 70 6c 69 63 61 74 65 0a  ECT. ^Duplicate.
2e960 72 6f 77 73 20 61 72 65 20 72 65 6d 6f 76 65 64  rows are removed
2e970 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
2e980 73 20 6f 66 20 49 4e 54 45 52 53 45 43 54 20 61  s of INTERSECT a
2e990 6e 64 20 45 58 43 45 50 54 20 6f 70 65 72 61 74  nd EXCEPT operat
2e9a0 6f 72 73 20 62 65 66 6f 72 65 20 74 68 65 0a 72  ors before the.r
2e9b0 65 73 75 6c 74 20 73 65 74 20 69 73 20 72 65 74  esult set is ret
2e9c0 75 72 6e 65 64 2e 0a 0a 3c 70 3e 5e 46 6f 72 20  urned...<p>^For 
2e9d0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2e9e0 64 65 74 65 72 6d 69 6e 69 6e 67 20 64 75 70 6c  determining dupl
2e9f0 69 63 61 74 65 20 72 6f 77 73 20 66 6f 72 20 74  icate rows for t
2ea00 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 63 6f  he results of co
2ea10 6d 70 6f 75 6e 64 0a 53 45 4c 45 43 54 20 6f 70  mpound.SELECT op
2ea20 65 72 61 74 6f 72 73 2c 20 4e 55 4c 4c 20 76 61  erators, NULL va
2ea30 6c 75 65 73 20 61 72 65 20 63 6f 6e 73 69 64 65  lues are conside
2ea40 72 65 64 20 65 71 75 61 6c 20 74 6f 20 6f 74 68  red equal to oth
2ea50 65 72 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 61  er NULL values a
2ea60 6e 64 0a 64 69 73 74 69 6e 63 74 20 66 72 6f 6d  nd.distinct from
2ea70 20 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61   all non-NULL va
2ea80 6c 75 65 73 2e 20 5e 54 68 65 20 63 6f 6c 6c 61  lues. ^The colla
2ea90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 75 73  tion sequence us
2eaa0 65 64 20 74 6f 20 63 6f 6d 70 61 72 65 20 0a 74  ed to compare .t
2eab0 77 6f 20 74 65 78 74 20 76 61 6c 75 65 73 20 69  wo text values i
2eac0 73 20 64 65 74 65 72 6d 69 6e 65 64 20 61 73 20  s determined as 
2ead0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f  if the columns o
2eae0 66 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72  f the left and r
2eaf0 69 67 68 74 2d 68 61 6e 64 0a 53 45 4c 45 43 54  ight-hand.SELECT
2eb00 20 73 74 61 74 65 6d 65 6e 74 73 20 77 65 72 65   statements were
2eb10 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72 69   the left and ri
2eb20 67 68 74 2d 68 61 6e 64 20 6f 70 65 72 61 6e 64  ght-hand operand
2eb30 73 20 6f 66 20 74 68 65 20 65 71 75 61 6c 73 20  s of the equals 
2eb40 28 3d 29 0a 6f 70 65 72 61 74 6f 72 2c 20 65 78  (=).operator, ex
2eb50 63 65 70 74 20 74 68 61 74 20 67 72 65 61 74 65  cept that greate
2eb60 72 20 70 72 65 63 65 64 65 6e 63 65 20 69 73 20  r precedence is 
2eb70 6e 6f 74 20 61 73 73 69 67 6e 65 64 20 74 6f 20  not assigned to 
2eb80 61 20 63 6f 6c 6c 61 74 69 6f 6e 20 0a 73 65 71  a collation .seq
2eb90 75 65 6e 63 65 20 73 70 65 63 69 66 69 65 64 20  uence specified 
2eba0 77 69 74 68 20 74 68 65 20 70 6f 73 74 66 69 78  with the postfix
2ebb0 20 43 4f 4c 4c 41 54 45 20 6f 70 65 72 61 74 6f   COLLATE operato
2ebc0 72 2e 20 5e 4e 6f 20 61 66 66 69 6e 69 74 79 0a  r. ^No affinity.
2ebd0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 73 20  transformations 
2ebe0 61 72 65 20 61 70 70 6c 69 65 64 20 74 6f 20 61  are applied to a
2ebf0 6e 79 20 76 61 6c 75 65 73 20 77 68 65 6e 20 63  ny values when c
2ec00 6f 6d 70 61 72 69 6e 67 20 72 6f 77 73 20 61 73  omparing rows as
2ec10 20 70 61 72 74 20 6f 66 20 61 0a 63 6f 6d 70 6f   part of a.compo
2ec20 75 6e 64 20 53 45 4c 45 43 54 2e 20 0a 0a 3c 70  und SELECT. ..<p
2ec30 3e 5e 28 57 68 65 6e 20 74 68 72 65 65 20 6f 72  >^(When three or
2ec40 20 6d 6f 72 65 20 73 69 6d 70 6c 65 20 53 45 4c   more simple SEL
2ec50 45 43 54 73 20 61 72 65 20 63 6f 6e 6e 65 63 74  ECTs are connect
2ec60 65 64 20 69 6e 74 6f 20 61 20 63 6f 6d 70 6f 75  ed into a compou
2ec70 6e 64 20 53 45 4c 45 43 54 2c 0a 74 68 65 79 20  nd SELECT,.they 
2ec80 67 72 6f 75 70 20 66 72 6f 6d 20 6c 65 66 74 20  group from left 
2ec90 74 6f 20 72 69 67 68 74 2e 20 49 6e 20 6f 74 68  to right. In oth
2eca0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 22 41 22  er words, if "A"
2ecb0 2c 20 22 42 22 20 61 6e 64 20 22 43 22 20 61 72  , "B" and "C" ar
2ecc0 65 20 61 6c 6c 0a 73 69 6d 70 6c 65 20 53 45 4c  e all.simple SEL
2ecd0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  ECT statements, 
2ece0 28 41 20 6f 70 20 42 20 6f 70 20 43 29 20 69 73  (A op B op C) is
2ecf0 20 70 72 6f 63 65 73 73 65 64 20 61 73 20 28 28   processed as ((
2ed00 41 20 6f 70 20 42 29 20 6f 70 20 43 29 2e 29 5e  A op B) op C).)^
2ed10 0a 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  ..</p>..<tcl>hd_
2ed20 66 72 61 67 6d 65 6e 74 20 6f 72 64 65 72 62 79  fragment orderby
2ed30 20 7b 6f 72 64 65 72 20 62 79 7d 20 7b 4f 52 44   {order by} {ORD
2ed40 45 52 20 42 59 7d 3c 2f 74 63 6c 3e 0a 3c 68 33  ER BY}</tcl>.<h3
2ed50 3e 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c  >The ORDER BY cl
2ed60 61 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 49 66  ause</h3>..<p>If
2ed70 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
2ed80 65 6e 74 20 74 68 61 74 20 72 65 74 75 72 6e 73  ent that returns
2ed90 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 72   more than one r
2eda0 6f 77 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ow does not have
2edb0 20 61 6e 0a 4f 52 44 45 52 20 42 59 20 63 6c 61   an.ORDER BY cla
2edc0 75 73 65 2c 20 74 68 65 20 6f 72 64 65 72 20 69  use, the order i
2edd0 6e 20 77 68 69 63 68 20 74 68 65 20 72 6f 77 73  n which the rows
2ede0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 69 73   are returned is
2edf0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 4f 72 2c 20   undefined..Or, 
2ee00 69 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  if a SELECT stat
2ee10 65 6d 65 6e 74 20 64 6f 65 73 20 68 61 76 65 20  ement does have 
2ee20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  an ORDER BY clau
2ee30 73 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 73  se, then the lis
2ee40 74 20 6f 66 0a 65 78 70 72 65 73 73 69 6f 6e 73  t of.expressions
2ee50 20 61 74 74 61 63 68 65 64 20 74 6f 20 74 68 65   attached to the
2ee60 20 4f 52 44 45 52 20 42 59 20 64 65 74 65 72 6d   ORDER BY determ
2ee70 69 6e 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e  ine the order in
2ee80 20 77 68 69 63 68 20 72 6f 77 73 0a 61 72 65 20   which rows.are 
2ee90 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
2eea0 75 73 65 72 2e 0a 0a 3c 70 3e 0a 5e 49 6e 20 61  user...<p>.^In a
2eeb0 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43   [compound SELEC
2eec0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 6e  T] statement, on
2eed0 6c 79 20 74 68 65 20 6c 61 73 74 20 6f 72 20 72  ly the last or r
2eee0 69 67 68 74 2d 6d 6f 73 74 20 5b 73 69 6d 70 6c  ight-most [simpl
2eef0 65 20 53 45 4c 45 43 54 5d 0a 6d 61 79 20 68 61  e SELECT].may ha
2ef00 76 65 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63  ve an ORDER BY c
2ef10 6c 61 75 73 65 2e 20 5e 54 68 61 74 20 4f 52 44  lause. ^That ORD
2ef20 45 52 20 42 59 20 63 6c 61 75 73 65 20 77 69 6c  ER BY clause wil
2ef30 6c 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  l apply across a
2ef40 6c 6c 20 65 6c 65 6d 65 6e 74 73 20 6f 66 0a 74  ll elements of.t
2ef50 68 65 20 63 6f 6d 70 6f 75 6e 64 2e 20 5e 49 66  he compound. ^If
2ef60 20 74 68 65 20 72 69 67 68 74 2d 6d 6f 73 74 20   the right-most 
2ef70 65 6c 65 6d 65 6e 74 20 6f 66 20 61 20 5b 63 6f  element of a [co
2ef80 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d 20 69  mpound SELECT] i
2ef90 73 20 61 20 5b 56 41 4c 55 45 53 5d 20 63 6c 61  s a [VALUES] cla
2efa0 75 73 65 2c 0a 74 68 65 6e 20 6e 6f 20 4f 52 44  use,.then no ORD
2efb0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
2efc0 61 6c 6c 6f 77 65 64 20 6f 6e 20 74 68 61 74 20  allowed on that 
2efd0 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 0a 3c 70 3e  statement....<p>
2efe0 5e 52 6f 77 73 20 61 72 65 20 66 69 72 73 74 20  ^Rows are first 
2eff0 73 6f 72 74 65 64 20 62 61 73 65 64 20 6f 6e 20  sorted based on 
2f000 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 0a 65  the results of.e
2f010 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 6c 65  valuating the le
2f020 66 74 2d 6d 6f 73 74 20 65 78 70 72 65 73 73 69  ft-most expressi
2f030 6f 6e 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  on in the ORDER 
2f040 42 59 20 6c 69 73 74 2c 20 74 68 65 6e 20 74 69  BY list, then ti
2f050 65 73 20 61 72 65 20 62 72 6f 6b 65 6e 0a 62 79  es are broken.by
2f060 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
2f070 73 65 63 6f 6e 64 20 6c 65 66 74 2d 6d 6f 73 74  second left-most
2f080 20 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64 20   expression and 
2f090 73 6f 20 6f 6e 2e 20 54 68 65 20 6f 72 64 65 72  so on. The order
2f0a0 20 69 6e 20 77 68 69 63 68 0a 74 77 6f 20 72 6f   in which.two ro
2f0b0 77 73 20 66 6f 72 20 77 68 69 63 68 20 61 6c 6c  ws for which all
2f0c0 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65 73   ORDER BY expres
2f0d0 73 69 6f 6e 73 20 65 76 61 6c 75 61 74 65 20 74  sions evaluate t
2f0e0 6f 20 65 71 75 61 6c 20 76 61 6c 75 65 73 20 61  o equal values a
2f0f0 72 65 0a 72 65 74 75 72 6e 65 64 20 69 73 20 75  re.returned is u
2f100 6e 64 65 66 69 6e 65 64 2e 20 5e 45 61 63 68 20  ndefined. ^Each 
2f110 4f 52 44 45 52 20 42 59 20 65 78 70 72 65 73 73  ORDER BY express
2f120 69 6f 6e 20 6d 61 79 20 62 65 20 6f 70 74 69 6f  ion may be optio
2f130 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 0a 62  nally followed.b
2f140 79 20 6f 6e 65 20 6f 66 20 74 68 65 20 6b 65 79  y one of the key
2f150 77 6f 72 64 73 20 41 53 43 20 28 73 6d 61 6c 6c  words ASC (small
2f160 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  er values are re
2f170 74 75 72 6e 65 64 20 66 69 72 73 74 29 20 6f 72  turned first) or
2f180 20 44 45 53 43 20 28 6c 61 72 67 65 72 0a 76 61   DESC (larger.va
2f190 6c 75 65 73 20 61 72 65 20 72 65 74 75 72 6e 65  lues are returne
2f1a0 64 20 66 69 72 73 74 29 2e 20 5e 49 66 20 6e 65  d first). ^If ne
2f1b0 69 74 68 65 72 20 41 53 43 20 6f 72 20 44 45 53  ither ASC or DES
2f1c0 43 20 61 72 65 20 73 70 65 63 69 66 69 65 64 2c  C are specified,
2f1d0 20 72 6f 77 73 0a 61 72 65 20 73 6f 72 74 65 64   rows.are sorted
2f1e0 20 69 6e 20 61 73 63 65 6e 64 69 6e 67 20 28 73   in ascending (s
2f1f0 6d 61 6c 6c 65 72 20 76 61 6c 75 65 73 20 66 69  maller values fi
2f200 72 73 74 29 20 6f 72 64 65 72 20 62 79 20 64 65  rst) order by de
2f210 66 61 75 6c 74 2e 0a 0a 3c 70 3e 45 61 63 68 20  fault...<p>Each 
2f220 4f 52 44 45 52 20 42 59 20 65 78 70 72 65 73 73  ORDER BY express
2f230 69 6f 6e 20 69 73 20 70 72 6f 63 65 73 73 65 64  ion is processed
2f240 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e   as follows:</p>
2f250 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 5e 49  ..<ol>.<li><p>^I
2f260 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 65  f the ORDER BY e
2f270 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 20 63  xpression is a c
2f280 6f 6e 73 74 61 6e 74 20 69 6e 74 65 67 65 72 20  onstant integer 
2f290 4b 20 74 68 65 6e 20 74 68 65 0a 65 78 70 72 65  K then the.expre
2f2a0 73 73 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ssion is conside
2f2b0 72 65 64 20 61 6e 20 61 6c 69 61 73 20 66 6f 72  red an alias for
2f2c0 20 74 68 65 20 4b 2d 74 68 20 63 6f 6c 75 6d 6e   the K-th column
2f2d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2f2e0 65 74 0a 28 63 6f 6c 75 6d 6e 73 20 61 72 65 20  et.(columns are 
2f2f0 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 6c 65  numbered from le
2f300 66 74 20 74 6f 20 72 69 67 68 74 20 73 74 61 72  ft to right star
2f310 74 69 6e 67 20 77 69 74 68 20 31 29 2e 0a 0a 3c  ting with 1)...<
2f320 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20 4f 52  li><p>^If the OR
2f330 44 45 52 20 42 59 20 65 78 70 72 65 73 73 69 6f  DER BY expressio
2f340 6e 20 69 73 20 61 6e 20 69 64 65 6e 74 69 66 69  n is an identifi
2f350 65 72 20 74 68 61 74 20 63 6f 72 72 65 73 70 6f  er that correspo
2f360 6e 64 73 20 74 6f 0a 74 68 65 20 61 6c 69 61 73  nds to.the alias
2f370 20 6f 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 6f   of one of the o
2f380 75 74 70 75 74 20 63 6f 6c 75 6d 6e 73 2c 20 74  utput columns, t
2f390 68 65 6e 20 74 68 65 20 65 78 70 72 65 73 73 69  hen the expressi
2f3a0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
2f3b0 0a 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68  .an alias for th
2f3c0 61 74 20 63 6f 6c 75 6d 6e 2e 0a 0a 3c 6c 69 3e  at column...<li>
2f3d0 3c 70 3e 5e 4f 74 68 65 72 77 69 73 65 2c 20 69  <p>^Otherwise, i
2f3e0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 65  f the ORDER BY e
2f3f0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 6e 79  xpression is any
2f400 20 6f 74 68 65 72 20 65 78 70 72 65 73 73 69 6f   other expressio
2f410 6e 2c 20 69 74 20 0a 69 73 20 65 76 61 6c 75 61  n, it .is evalua
2f420 74 65 64 20 61 6e 64 20 74 68 65 20 72 65 74 75  ted and the retu
2f430 72 6e 65 64 20 76 61 6c 75 65 20 75 73 65 64 20  rned value used 
2f440 74 6f 20 6f 72 64 65 72 20 74 68 65 20 6f 75 74  to order the out
2f450 70 75 74 20 72 6f 77 73 2e 20 5e 49 66 0a 74 68  put rows. ^If.th
2f460 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
2f470 6e 74 20 69 73 20 61 20 73 69 6d 70 6c 65 20 53  nt is a simple S
2f480 45 4c 45 43 54 2c 20 74 68 65 6e 20 61 6e 20 4f  ELECT, then an O
2f490 52 44 45 52 20 42 59 20 6d 61 79 20 63 6f 6e 74  RDER BY may cont
2f4a0 61 69 6e 20 61 6e 79 0a 61 72 62 69 74 72 61 72  ain any.arbitrar
2f4b0 79 20 65 78 70 72 65 73 73 69 6f 6e 73 2e 20 5e  y expressions. ^
2f4c0 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
2f4d0 53 45 4c 45 43 54 20 69 73 20 61 20 63 6f 6d 70  SELECT is a comp
2f4e0 6f 75 6e 64 20 53 45 4c 45 43 54 2c 20 74 68 65  ound SELECT, the
2f4f0 6e 0a 4f 52 44 45 52 20 42 59 20 65 78 70 72 65  n.ORDER BY expre
2f500 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2f510 6e 6f 74 20 61 6c 69 61 73 65 73 20 74 6f 20 6f  not aliases to o
2f520 75 74 70 75 74 20 63 6f 6c 75 6d 6e 73 20 6d 75  utput columns mu
2f530 73 74 20 62 65 20 65 78 61 63 74 6c 79 0a 74 68  st be exactly.th
2f540 65 20 73 61 6d 65 20 61 73 20 61 6e 20 65 78 70  e same as an exp
2f550 72 65 73 73 69 6f 6e 20 75 73 65 64 20 61 73 20  ression used as 
2f560 61 6e 20 6f 75 74 70 75 74 20 63 6f 6c 75 6d 6e  an output column
2f570 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 5e 46 6f 72  ..</ol>..<p>^For
2f580 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
2f590 20 73 6f 72 74 69 6e 67 20 72 6f 77 73 2c 20 76   sorting rows, v
2f5a0 61 6c 75 65 73 20 61 72 65 20 63 6f 6d 70 61 72  alues are compar
2f5b0 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77  ed in the same w
2f5c0 61 79 0a 61 73 20 66 6f 72 20 5b 63 6f 6d 70 61  ay.as for [compa
2f5d0 72 69 73 6f 6e 20 65 78 70 72 65 73 73 69 6f 6e  rison expression
2f5e0 73 5d 2e 20 54 68 65 20 63 6f 6c 6c 61 74 69 6f  s]. The collatio
2f5f0 6e 20 73 65 71 75 65 6e 63 65 20 75 73 65 64 20  n sequence used 
2f600 74 6f 20 63 6f 6d 70 61 72 65 0a 74 77 6f 20 74  to compare.two t
2f610 65 78 74 20 76 61 6c 75 65 73 20 69 73 20 64 65  ext values is de
2f620 74 65 72 6d 69 6e 65 64 20 61 73 20 66 6f 6c 6c  termined as foll
2f630 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69  ows:..<ol>.  <li
2f640 3e 3c 70 3e 5e 49 66 20 74 68 65 20 4f 52 44 45  ><p>^If the ORDE
2f650 52 20 42 59 20 65 78 70 72 65 73 73 69 6f 6e 20  R BY expression 
2f660 69 73 20 61 73 73 69 67 6e 65 64 20 61 20 63 6f  is assigned a co
2f670 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f680 20 75 73 69 6e 67 0a 20 20 74 68 65 20 70 6f 73   using.  the pos
2f690 74 66 69 78 20 5b 43 4f 4c 4c 41 54 45 20 6f 70  tfix [COLLATE op
2f6a0 65 72 61 74 6f 72 5d 2c 20 74 68 65 6e 20 74 68  erator], then th
2f6b0 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 6c  e specified coll
2f6c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2f6d0 73 0a 20 20 75 73 65 64 2e 0a 20 20 3c 6c 69 3e  s.  used..  <li>
2f6e0 3c 70 3e 5e 4f 74 68 65 72 77 69 73 65 2c 20 69  <p>^Otherwise, i
2f6f0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 65  f the ORDER BY e
2f700 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 6e 20  xpression is an 
2f710 61 6c 69 61 73 20 74 6f 20 61 6e 20 65 78 70 72  alias to an expr
2f720 65 73 73 69 6f 6e 0a 20 20 74 68 61 74 20 68 61  ession.  that ha
2f730 73 20 62 65 65 6e 20 61 73 73 69 67 6e 65 64 20  s been assigned 
2f740 61 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  a collation sequ
2f750 65 6e 63 65 20 75 73 69 6e 67 20 74 68 65 20 70  ence using the p
2f760 6f 73 74 66 69 78 20 0a 20 20 5b 43 4f 4c 4c 41  ostfix .  [COLLA
2f770 54 45 20 6f 70 65 72 61 74 6f 72 5d 2c 20 74 68  TE operator], th
2f780 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2f790 20 73 65 71 75 65 6e 63 65 20 61 73 73 69 67 6e   sequence assign
2f7a0 65 64 20 74 6f 20 74 68 65 20 61 6c 69 61 73 65  ed to the aliase
2f7b0 64 0a 20 20 65 78 70 72 65 73 73 69 6f 6e 20 69  d.  expression i
2f7c0 73 20 75 73 65 64 2e 0a 20 20 3c 6c 69 3e 3c 70  s used..  <li><p
2f7d0 3e 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20  >^Otherwise, if 
2f7e0 74 68 65 20 4f 52 44 45 52 20 42 59 20 65 78 70  the ORDER BY exp
2f7f0 72 65 73 73 69 6f 6e 20 69 73 20 61 20 63 6f 6c  ression is a col
2f800 75 6d 6e 20 6f 72 20 61 6e 20 61 6c 69 61 73 20  umn or an alias 
2f810 6f 66 0a 20 20 61 6e 20 65 78 70 72 65 73 73 69  of.  an expressi
2f820 6f 6e 20 74 68 61 74 20 69 73 20 61 20 63 6f 6c  on that is a col
2f830 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 64 65  umn, then the de
2f840 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
2f850 73 65 71 75 65 6e 63 65 20 66 6f 72 0a 20 20 74  sequence for.  t
2f860 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 73 65  he column is use
2f870 64 2e 20 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 4f 74  d. .  <li><p>^Ot
2f880 68 65 72 77 69 73 65 2c 20 74 68 65 20 5b 42 49  herwise, the [BI
2f890 4e 41 52 59 5d 20 63 6f 6c 6c 61 74 69 6f 6e 20  NARY] collation 
2f8a0 73 65 71 75 65 6e 63 65 20 69 73 20 75 73 65 64  sequence is used
2f8b0 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 49 6e 20 61  ..</ol>..<p>In a
2f8c0 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43   [compound SELEC
2f8d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6c  T] statement, al
2f8e0 6c 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65  l ORDER BY expre
2f8f0 73 73 69 6f 6e 73 20 61 72 65 20 68 61 6e 64 6c  ssions are handl
2f900 65 64 0a 61 73 20 61 6c 69 61 73 65 73 20 66 6f  ed.as aliases fo
2f910 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 72 65 73  r one of the res
2f920 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74  ult columns of t
2f930 68 65 20 63 6f 6d 70 6f 75 6e 64 2e 0a 5e 28 49  he compound..^(I
2f940 66 20 61 6e 20 4f 52 44 45 52 20 42 59 20 65 78  f an ORDER BY ex
2f950 70 72 65 73 73 69 6f 6e 20 69 73 20 6e 6f 74 20  pression is not 
2f960 61 6e 20 69 6e 74 65 67 65 72 20 61 6c 69 61 73  an integer alias
2f970 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 73 65  , then SQLite se
2f980 61 72 63 68 65 73 0a 74 68 65 20 6c 65 66 74 2d  arches.the left-
2f990 6d 6f 73 74 20 53 45 4c 45 43 54 20 69 6e 20 74  most SELECT in t
2f9a0 68 65 20 63 6f 6d 70 6f 75 6e 64 20 66 6f 72 20  he compound for 
2f9b0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2f9c0 74 68 61 74 20 6d 61 74 63 68 65 73 20 65 69 74  that matches eit
2f9d0 68 65 72 0a 74 68 65 20 73 65 63 6f 6e 64 20 6f  her.the second o
2f9e0 72 20 74 68 69 72 64 20 72 75 6c 65 73 20 61 62  r third rules ab
2f9f0 6f 76 65 2e 20 49 66 20 61 20 6d 61 74 63 68 20  ove. If a match 
2fa00 69 73 20 66 6f 75 6e 64 2c 20 74 68 65 20 73 65  is found, the se
2fa10 61 72 63 68 20 73 74 6f 70 73 20 61 6e 64 0a 74  arch stops and.t
2fa20 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  he expression is
2fa30 20 68 61 6e 64 6c 65 64 20 61 73 20 61 6e 20 61   handled as an a
2fa40 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 65 73  lias for the res
2fa50 75 6c 74 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ult column that 
2fa60 69 74 20 68 61 73 20 62 65 65 6e 0a 6d 61 74 63  it has been.matc
2fa70 68 65 64 20 61 67 61 69 6e 73 74 2e 20 4f 74 68  hed against. Oth
2fa80 65 72 77 69 73 65 2c 20 74 68 65 20 6e 65 78 74  erwise, the next
2fa90 20 53 45 4c 45 43 54 20 74 6f 20 74 68 65 20 72   SELECT to the r
2faa0 69 67 68 74 20 69 73 20 74 72 69 65 64 2c 20 61  ight is tried, a
2fab0 6e 64 20 73 6f 20 6f 6e 2e 29 5e 0a 5e 49 66 20  nd so on.)^.^If 
2fac0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 65 78 70 72  no matching expr
2fad0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 66 6f  ession can be fo
2fae0 75 6e 64 20 69 6e 20 74 68 65 20 72 65 73 75 6c  und in the resul
2faf0 74 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 6e 79  t columns of any
2fb00 0a 63 6f 6e 73 74 69 74 75 65 6e 74 20 53 45 4c  .constituent SEL
2fb10 45 43 54 2c 20 69 74 20 69 73 20 61 6e 20 65 72  ECT, it is an er
2fb20 72 6f 72 2e 20 5e 45 61 63 68 20 74 65 72 6d 20  ror. ^Each term 
2fb30 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
2fb40 63 6c 61 75 73 65 20 69 73 0a 70 72 6f 63 65 73  clause is.proces
2fb50 73 65 64 20 73 65 70 61 72 61 74 65 6c 79 20 61  sed separately a
2fb60 6e 64 20 6d 61 79 20 62 65 20 6d 61 74 63 68 65  nd may be matche
2fb70 64 20 61 67 61 69 6e 73 74 20 72 65 73 75 6c 74  d against result
2fb80 20 63 6f 6c 75 6d 6e 73 20 66 72 6f 6d 20 64 69   columns from di
2fb90 66 66 65 72 65 6e 74 0a 53 45 4c 45 43 54 20 73  fferent.SELECT s
2fba0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
2fbb0 20 63 6f 6d 70 6f 75 6e 64 2e 3c 2f 70 3e 0a 0a   compound.</p>..
2fbc0 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
2fbd0 20 6c 69 6d 69 74 6f 66 66 73 65 74 20 7b 4c 49   limitoffset {LI
2fbe0 4d 49 54 7d 20 7b 4f 46 46 53 45 54 7d 3c 2f 74  MIT} {OFFSET}</t
2fbf0 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 4c 49 4d 49  cl>.<h3>The LIMI
2fc00 54 20 63 6c 61 75 73 65 3c 2f 68 33 3e 0a 0a 3c  T clause</h3>..<
2fc10 70 3e 5e 54 68 65 20 4c 49 4d 49 54 20 63 6c 61  p>^The LIMIT cla
2fc20 75 73 65 20 69 73 20 75 73 65 64 20 74 6f 20 70  use is used to p
2fc30 6c 61 63 65 20 61 6e 20 75 70 70 65 72 20 62 6f  lace an upper bo
2fc40 75 6e 64 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65  und on the numbe
2fc50 72 20 6f 66 20 72 6f 77 73 0a 72 65 74 75 72 6e  r of rows.return
2fc60 65 64 20 62 79 20 74 68 65 20 65 6e 74 69 72 65  ed by the entire
2fc70 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2fc80 74 2e 0a 0a 3c 70 3e 5e 49 6e 20 61 20 5b 63 6f  t...<p>^In a [co
2fc90 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d 2c 20  mpound SELECT], 
2fca0 6f 6e 6c 79 20 74 68 65 0a 6c 61 73 74 20 6f 72  only the.last or
2fcb0 20 72 69 67 68 74 2d 6d 6f 73 74 20 5b 73 69 6d   right-most [sim
2fcc0 70 6c 65 20 53 45 4c 45 43 54 5d 20 6d 61 79 20  ple SELECT] may 
2fcd0 63 6f 6e 74 61 69 6e 20 61 20 4c 49 4d 49 54 20  contain a LIMIT 
2fce0 63 6c 61 75 73 65 2e 20 20 0a 5e 49 6e 20 61 20  clause.  .^In a 
2fcf0 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54  [compound SELECT
2fd00 5d 2c 20 0a 74 68 65 20 4c 49 4d 49 54 20 63 6c  ], .the LIMIT cl
2fd10 61 75 73 65 20 61 70 70 6c 69 65 73 20 74 6f 20  ause applies to 
2fd20 74 68 65 20 65 6e 74 69 72 65 20 63 6f 6d 70 6f  the entire compo
2fd30 75 6e 64 2c 20 6e 6f 74 20 6a 75 73 74 20 74 68  und, not just th
2fd40 65 20 66 69 6e 61 6c 20 53 45 4c 45 43 54 2e 0a  e final SELECT..
2fd50 5e 49 66 20 74 68 65 20 72 69 67 68 74 2d 6d 6f  ^If the right-mo
2fd60 73 74 20 5b 73 69 6d 70 6c 65 20 53 45 4c 45 43  st [simple SELEC
2fd70 54 5d 20 69 73 20 61 20 5b 56 41 4c 55 45 53 20  T] is a [VALUES 
2fd80 63 6c 61 75 73 65 5d 20 74 68 65 6e 20 6e 6f 20  clause] then no 
2fd90 4c 49 4d 49 54 20 63 6c 61 75 73 65 0a 69 73 20  LIMIT clause.is 
2fda0 61 6c 6c 6f 77 65 64 2e 0a 0a 3c 70 3e 5e 41 6e  allowed...<p>^An
2fdb0 79 20 73 63 61 6c 61 72 20 65 78 70 72 65 73 73  y scalar express
2fdc0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
2fdd0 69 6e 20 74 68 65 20 0a 4c 49 4d 49 54 20 63 6c  in the .LIMIT cl
2fde0 61 75 73 65 2c 20 73 6f 20 6c 6f 6e 67 20 61 73  ause, so long as
2fdf0 20 69 74 20 65 76 61 6c 75 61 74 65 73 20 74 6f   it evaluates to
2fe00 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 61   an integer or a
2fe10 20 76 61 6c 75 65 20 74 68 61 74 20 63 61 6e 20   value that can 
2fe20 62 65 0a 6c 6f 73 73 6c 65 73 73 6c 79 20 63 6f  be.losslessly co
2fe30 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20 69 6e  nverted to an in
2fe40 74 65 67 65 72 2e 20 5e 49 66 20 74 68 65 20 65  teger. ^If the e
2fe50 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61  xpression evalua
2fe60 74 65 73 20 74 6f 20 61 20 4e 55 4c 4c 20 0a 76  tes to a NULL .v
2fe70 61 6c 75 65 20 6f 72 20 61 6e 79 20 6f 74 68 65  alue or any othe
2fe80 72 20 76 61 6c 75 65 20 74 68 61 74 20 63 61 6e  r value that can
2fe90 6e 6f 74 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c  not be losslessl
2fea0 79 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61  y converted to a
2feb0 6e 20 69 6e 74 65 67 65 72 2c 20 61 6e 0a 65 72  n integer, an.er
2fec0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
2fed0 20 5e 49 66 20 74 68 65 20 4c 49 4d 49 54 20 65   ^If the LIMIT e
2fee0 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61  xpression evalua
2fef0 74 65 73 20 74 6f 20 61 20 6e 65 67 61 74 69 76  tes to a negativ
2ff00 65 20 76 61 6c 75 65 2c 0a 74 68 65 6e 20 74 68  e value,.then th
2ff10 65 72 65 20 69 73 20 6e 6f 20 75 70 70 65 72 20  ere is no upper 
2ff20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 6e 75 6d  bound on the num
2ff30 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65 74 75  ber of rows retu
2ff40 72 6e 65 64 2e 20 5e 4f 74 68 65 72 77 69 73 65  rned. ^Otherwise
2ff50 2c 20 74 68 65 0a 53 45 4c 45 43 54 20 72 65 74  , the.SELECT ret
2ff60 75 72 6e 73 20 74 68 65 20 66 69 72 73 74 20 4e  urns the first N
2ff70 20 72 6f 77 73 20 6f 66 20 69 74 73 20 72 65 73   rows of its res
2ff80 75 6c 74 20 73 65 74 20 6f 6e 6c 79 2c 20 77 68  ult set only, wh
2ff90 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
2ffa0 75 65 0a 74 68 61 74 20 74 68 65 20 4c 49 4d 49  ue.that the LIMI
2ffb0 54 20 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61  T expression eva
2ffc0 6c 75 61 74 65 73 20 74 6f 2e 20 5e 4f 72 2c 20  luates to. ^Or, 
2ffd0 69 66 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  if the SELECT st
2ffe0 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 72 65  atement would.re
2fff0 74 75 72 6e 20 6c 65 73 73 20 74 68 61 6e 20 4e  turn less than N
30000 20 72 6f 77 73 20 77 69 74 68 6f 75 74 20 61 20   rows without a 
30010 4c 49 4d 49 54 20 63 6c 61 75 73 65 2c 20 74 68  LIMIT clause, th
30020 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 72 65  en the entire re
30030 73 75 6c 74 20 73 65 74 20 69 73 0a 72 65 74 75  sult set is.retu
30040 72 6e 65 64 2e 20 0a 0a 3c 70 3e 5e 54 68 65 20  rned. ..<p>^The 
30050 65 78 70 72 65 73 73 69 6f 6e 20 61 74 74 61 63  expression attac
30060 68 65 64 20 74 6f 20 74 68 65 20 6f 70 74 69 6f  hed to the optio
30070 6e 61 6c 20 4f 46 46 53 45 54 20 63 6c 61 75 73  nal OFFSET claus
30080 65 20 74 68 61 74 20 6d 61 79 20 66 6f 6c 6c 6f  e that may follo
30090 77 20 61 0a 4c 49 4d 49 54 20 63 6c 61 75 73 65  w a.LIMIT clause
300a0 20 6d 75 73 74 20 61 6c 73 6f 20 65 76 61 6c 75   must also evalu
300b0 61 74 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ate to an intege
300c0 72 2c 20 6f 72 20 61 20 76 61 6c 75 65 20 74 68  r, or a value th
300d0 61 74 20 63 61 6e 20 62 65 0a 6c 6f 73 73 6c 65  at can be.lossle
300e0 73 73 6c 79 20 63 6f 6e 76 65 72 74 65 64 20 74  ssly converted t
300f0 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 20 5e 49  o an integer. ^I
30100 66 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  f an expression 
30110 68 61 73 20 61 6e 20 4f 46 46 53 45 54 20 63 6c  has an OFFSET cl
30120 61 75 73 65 2c 0a 74 68 65 6e 20 74 68 65 20 66  ause,.then the f
30130 69 72 73 74 20 4d 20 72 6f 77 73 20 61 72 65 20  irst M rows are 
30140 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
30150 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
30160 72 6e 65 64 20 62 79 20 74 68 65 20 53 45 4c 45  rned by the SELE
30170 43 54 0a 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT.statement and
30180 20 74 68 65 20 6e 65 78 74 20 4e 20 72 6f 77 73   the next N rows
30190 20 61 72 65 20 72 65 74 75 72 6e 65 64 2c 20 77   are returned, w
301a0 68 65 72 65 20 4d 20 61 6e 64 20 4e 20 61 72 65  here M and N are
301b0 20 74 68 65 20 76 61 6c 75 65 73 20 74 68 61 74   the values that
301c0 0a 74 68 65 20 4f 46 46 53 45 54 20 61 6e 64 20  .the OFFSET and 
301d0 4c 49 4d 49 54 20 63 6c 61 75 73 65 73 20 65 76  LIMIT clauses ev
301e0 61 6c 75 61 74 65 20 74 6f 2c 20 72 65 73 70 65  aluate to, respe
301f0 63 74 69 76 65 6c 79 2e 20 5e 4f 72 2c 20 69 66  ctively. ^Or, if
30200 20 74 68 65 20 53 45 4c 45 43 54 0a 77 6f 75 6c   the SELECT.woul
30210 64 20 72 65 74 75 72 6e 20 6c 65 73 73 20 74 68  d return less th
30220 61 6e 20 4d 2b 4e 20 72 6f 77 73 20 69 66 20 69  an M+N rows if i
30230 74 20 64 69 64 20 6e 6f 74 20 68 61 76 65 20 61  t did not have a
30240 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 2c 20 74   LIMIT clause, t
30250 68 65 6e 20 74 68 65 0a 66 69 72 73 74 20 4d 20  hen the.first M 
30260 72 6f 77 73 20 61 72 65 20 73 6b 69 70 70 65 64  rows are skipped
30270 20 61 6e 64 20 74 68 65 20 72 65 6d 61 69 6e 69   and the remaini
30280 6e 67 20 72 6f 77 73 20 28 69 66 20 61 6e 79 29  ng rows (if any)
30290 20 61 72 65 20 72 65 74 75 72 6e 65 64 2e 20 5e   are returned. ^
302a0 49 66 20 74 68 65 0a 4f 46 46 53 45 54 20 63 6c  If the.OFFSET cl
302b0 61 75 73 65 20 65 76 61 6c 75 61 74 65 73 20 74  ause evaluates t
302c0 6f 20 61 20 6e 65 67 61 74 69 76 65 20 76 61 6c  o a negative val
302d0 75 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  ue, the results 
302e0 61 72 65 20 74 68 65 20 73 61 6d 65 20 61 73 20  are the same as 
302f0 69 66 20 69 74 0a 68 61 64 20 65 76 61 6c 75 61  if it.had evalua
30300 74 65 64 20 74 6f 20 7a 65 72 6f 2e 0a 0a 3c 70  ted to zero...<p
30310 3e 5e 49 6e 73 74 65 61 64 20 6f 66 20 61 20 73  >^Instead of a s
30320 65 70 61 72 61 74 65 20 4f 46 46 53 45 54 20 63  eparate OFFSET c
30330 6c 61 75 73 65 2c 20 74 68 65 20 4c 49 4d 49 54  lause, the LIMIT
30340 20 63 6c 61 75 73 65 20 6d 61 79 20 73 70 65 63   clause may spec
30350 69 66 79 20 74 77 6f 0a 73 63 61 6c 61 72 20 65  ify two.scalar e
30360 78 70 72 65 73 73 69 6f 6e 73 20 73 65 70 61 72  xpressions separ
30370 61 74 65 64 20 62 79 20 61 20 63 6f 6d 6d 61 2e  ated by a comma.
30380 20 5e 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20   ^In this case, 
30390 74 68 65 20 66 69 72 73 74 20 65 78 70 72 65 73  the first expres
303a0 73 69 6f 6e 0a 69 73 20 75 73 65 64 20 61 73 20  sion.is used as 
303b0 74 68 65 20 4f 46 46 53 45 54 20 65 78 70 72 65  the OFFSET expre
303c0 73 73 69 6f 6e 20 61 6e 64 20 74 68 65 20 73 65  ssion and the se
303d0 63 6f 6e 64 20 61 73 20 74 68 65 20 4c 49 4d 49  cond as the LIMI
303e0 54 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 54 68  T expression..Th
303f0 69 73 20 69 73 20 63 6f 75 6e 74 65 72 2d 69 6e  is is counter-in
30400 74 75 69 74 69 76 65 2c 20 61 73 20 77 68 65 6e  tuitive, as when
30410 20 75 73 69 6e 67 20 74 68 65 20 4f 46 46 53 45   using the OFFSE
30420 54 20 63 6c 61 75 73 65 20 74 68 65 20 73 65 63  T clause the sec
30430 6f 6e 64 20 6f 66 0a 74 68 65 20 74 77 6f 20 65  ond of.the two e
30440 78 70 72 65 73 73 69 6f 6e 73 20 69 73 20 74 68  xpressions is th
30450 65 20 4f 46 46 53 45 54 20 61 6e 64 20 74 68 65  e OFFSET and the
30460 20 66 69 72 73 74 20 74 68 65 20 4c 49 4d 49 54   first the LIMIT
30470 2e 20 0a 54 68 69 73 20 72 65 76 65 72 73 61 6c  . .This reversal
30480 20 6f 66 20 74 68 65 20 6f 66 66 73 65 74 20 61   of the offset a
30490 6e 64 20 6c 69 6d 69 74 20 69 73 20 69 6e 74 65  nd limit is inte
304a0 6e 74 69 6f 6e 61 6c 0a 2d 20 69 74 20 6d 61 78  ntional.- it max
304b0 69 6d 69 7a 65 73 20 63 6f 6d 70 61 74 69 62 69  imizes compatibi
304c0 6c 69 74 79 20 77 69 74 68 20 6f 74 68 65 72 20  lity with other 
304d0 53 51 4c 20 64 61 74 61 62 61 73 65 20 73 79 73  SQL database sys
304e0 74 65 6d 73 2e 0a 48 6f 77 65 76 65 72 2c 20 74  tems..However, t
304f0 6f 20 61 76 6f 69 64 20 63 6f 6e 66 75 73 69 6f  o avoid confusio
30500 6e 2c 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 61  n, programmers a
30510 72 65 20 73 74 72 6f 6e 67 6c 79 20 65 6e 63 6f  re strongly enco
30520 75 72 61 67 65 64 20 74 6f 20 75 73 65 0a 74 68  uraged to use.th
30530 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 4c 49  e form of the LI
30540 4d 49 54 20 63 6c 61 75 73 65 20 74 68 61 74 20  MIT clause that 
30550 75 73 65 73 20 74 68 65 20 22 4f 46 46 53 45 54  uses the "OFFSET
30560 22 20 6b 65 79 77 6f 72 64 20 61 6e 64 20 61 76  " keyword and av
30570 6f 69 64 0a 75 73 69 6e 67 20 61 20 4c 49 4d 49  oid.using a LIMI
30580 54 20 63 6c 61 75 73 65 20 77 69 74 68 20 61 20  T clause with a 
30590 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64 20  comma-separated 
305a0 6f 66 66 73 65 74 2e 0a 0a 3c 74 63 6c 3e 68 64  offset...<tcl>hd
305b0 5f 66 72 61 67 6d 65 6e 74 20 76 61 6c 75 65 73  _fragment values
305c0 20 7b 56 41 4c 55 45 53 20 63 6c 61 75 73 65 7d   {VALUES clause}
305d0 20 56 41 4c 55 45 53 3c 2f 74 63 6c 3e 0a 3c 68   VALUES</tcl>.<h
305e0 33 3e 54 68 65 20 56 41 4c 55 45 53 20 63 6c 61  3>The VALUES cla
305f0 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 54  use</h3>..<p>^(T
30600 68 65 20 70 68 72 61 73 65 20 22 56 41 4c 55 45  he phrase "VALUE
30610 53 28 3c 69 3e 65 78 70 72 2d 6c 69 73 74 3c 2f  S(<i>expr-list</
30620 69 3e 29 22 20 6d 65 61 6e 73 20 74 68 65 20 73  i>)" means the s
30630 61 6d 65 20 74 68 69 6e 67 0a 61 73 20 22 53 45  ame thing.as "SE
30640 4c 45 43 54 20 3c 69 3e 65 78 70 72 2d 6c 69 73  LECT <i>expr-lis
30650 74 3c 2f 69 3e 22 2e 29 5e 20 20 5e 28 54 68 65  t</i>".)^  ^(The
30660 20 70 68 72 61 73 65 0a 22 56 41 4c 55 45 53 28   phrase."VALUES(
30670 3c 69 3e 65 78 70 72 2d 6c 69 73 74 2d 31 3c 2f  <i>expr-list-1</
30680 69 3e 29 2c 2e 2e 2e 2c 28 3c 69 3e 65 78 70 72  i>),...,(<i>expr
30690 2d 6c 69 73 74 2d 4e 3c 2f 69 3e 29 22 20 6d 65  -list-N</i>)" me
306a0 61 6e 73 20 74 68 65 20 73 61 6d 65 0a 74 68 69  ans the same.thi
306b0 6e 67 20 61 73 20 22 53 45 4c 45 43 54 20 3c 69  ng as "SELECT <i
306c0 3e 65 78 70 72 2d 6c 69 73 74 2d 31 3c 2f 69 3e  >expr-list-1</i>
306d0 20 55 4e 49 4f 4e 20 41 4c 4c 20 2e 2e 2e 20 55   UNION ALL ... U
306e0 4e 49 4f 4e 20 41 4c 4c 0a 53 45 4c 45 43 54 20  NION ALL.SELECT 
306f0 3c 69 3e 65 78 70 72 2d 6c 69 73 74 2d 4e 3c 2f  <i>expr-list-N</
30700 69 3e 22 2e 29 5e 20 20 42 6f 74 68 20 66 6f 72  i>".)^  Both for
30710 6d 73 20 61 72 65 20 74 68 65 20 73 61 6d 65 2c  ms are the same,
30720 20 65 78 63 65 70 74 20 74 68 61 74 0a 74 68 65   except that.the
30730 20 6e 75 6d 62 65 72 20 6f 66 20 53 45 4c 45 43   number of SELEC
30740 54 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  T statements in 
30750 61 20 63 6f 6d 70 6f 75 6e 64 20 69 73 20 6c 69  a compound is li
30760 6d 69 74 65 64 20 62 79 0a 5b 53 51 4c 49 54 45  mited by.[SQLITE
30770 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
30780 53 45 4c 45 43 54 5d 20 77 68 65 72 65 61 73 20  SELECT] whereas 
30790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
307a0 77 73 20 69 6e 20 61 0a 56 41 4c 55 45 53 20 63  ws in a.VALUES c
307b0 6c 61 75 73 65 20 68 61 73 20 6e 6f 20 61 72 62  lause has no arb
307c0 69 74 72 61 72 79 20 6c 69 6d 69 74 2e 0a 0a 3c  itrary limit...<
307d0 70 3e 54 68 65 72 65 20 61 72 65 20 73 6f 6d 65  p>There are some
307e0 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20 6f 6e   restrictions on
307f0 20 74 68 65 20 75 73 65 20 6f 66 20 61 20 56 41   the use of a VA
30800 4c 55 45 53 20 63 6c 61 75 73 65 20 74 68 61 74  LUES clause that
30810 20 61 72 65 0a 6e 6f 74 20 73 68 6f 77 6e 20 6f   are.not shown o
30820 6e 20 74 68 65 20 73 79 6e 74 61 78 20 64 69 61  n the syntax dia
30830 67 72 61 6d 73 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69  grams:..<ul>.<li
30840 3e 3c 70 3e 0a 5e 41 20 56 41 4c 55 45 53 20 63  ><p>.^A VALUES c
30850 6c 61 75 73 65 20 63 61 6e 6e 6f 74 20 62 65 20  lause cannot be 
30860 66 6f 6c 6c 6f 77 65 64 20 62 79 20 5b 4f 52 44  followed by [ORD
30870 45 52 20 42 59 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e  ER BY]...<li><p>
30880 0a 5e 41 20 56 41 4c 55 45 53 20 63 6c 61 75 73  .^A VALUES claus
30890 65 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 6c 6c  e cannot be foll
308a0 6f 77 65 64 20 62 79 20 5b 4c 49 4d 49 54 5d 2e  owed by [LIMIT].
308b0 0a 3c 2f 75 6c 3e 0a 0a 0a 3c 68 33 3e 54 68 65  .</ul>...<h3>The
308c0 20 57 49 54 48 20 43 6c 61 75 73 65 3c 2f 68 33   WITH Clause</h3
308d0 3e 0a 0a 3c 70 3e 5e 53 45 4c 45 43 54 20 73 74  >..<p>^SELECT st
308e0 61 74 65 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  atements may be 
308f0 6f 70 74 69 6f 6e 61 6c 6c 79 20 70 72 65 63 65  optionally prece
30900 64 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 0a  ded by a single.
30910 5b 57 49 54 48 20 63 6c 61 75 73 65 5d 20 74 68  [WITH clause] th
30920 61 74 20 64 65 66 69 6e 65 73 20 6f 6e 65 20 6f  at defines one o
30930 72 20 6d 6f 72 65 20 5b 63 6f 6d 6d 6f 6e 20 74  r more [common t
30940 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73  able expressions
30950 5d 0a 66 6f 72 20 75 73 65 20 77 69 74 68 69 6e  ].for use within
30960 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
30970 65 6d 65 6e 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f  ement...<tcl>hd_
30980 66 72 61 67 6d 65 6e 74 20 74 61 62 66 75 6e 63  fragment tabfunc
30990 31 20 7b 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  1 {table-valued 
309a0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
309b0 20 46 52 4f 4d 20 63 6c 61 75 73 65 7d 3c 2f 74   FROM clause}</t
309c0 63 6c 3e 0a 3c 68 33 3e 54 61 62 6c 65 2d 76 61  cl>.<h3>Table-va
309d0 6c 75 65 64 20 46 75 6e 63 74 69 6f 6e 73 20 49  lued Functions I
309e0 6e 20 54 68 65 20 46 52 4f 4d 20 43 6c 61 75 73  n The FROM Claus
309f0 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 20 5b 76 69  e</h3>..<p>A [vi
30a00 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 74 68 61  rtual table] tha
30a10 74 20 63 6f 6e 74 61 69 6e 73 20 5b 68 69 64 64  t contains [hidd
30a20 65 6e 20 63 6f 6c 75 6d 6e 73 5d 20 63 61 6e 20  en columns] can 
30a30 62 65 20 75 73 65 64 20 6c 69 6b 65 0a 61 20 5b  be used like.a [
30a40 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
30a50 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 46 52  ction] in the FR
30a60 4f 4d 20 63 6c 61 75 73 65 2e 20 20 54 68 65 20  OM clause.  The 
30a70 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
30a80 0a 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75  .table-valued fu
30a90 6e 63 74 69 6f 6e 20 62 65 63 6f 6d 65 20 63 6f  nction become co
30aa0 6e 73 74 72 61 69 6e 74 73 20 6f 6e 20 74 68 65  nstraints on the
30ab0 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 20   HIDDEN columns 
30ac0 6f 66 0a 74 68 65 20 76 69 72 74 75 61 6c 20 74  of.the virtual t
30ad0 61 62 6c 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  able.  Additiona
30ae0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61  l information ca
30af0 6e 20 62 65 20 66 6f 75 6e 64 20 69 6e 20 74 68  n be found in th
30b00 65 0a 5b 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  e.[table-valued 
30b10 66 75 6e 63 74 69 6f 6e 73 7c 76 69 72 74 75 61  functions|virtua
30b20 6c 20 74 61 62 6c 65 20 64 6f 63 75 6d 65 6e 74  l table document
30b30 61 74 69 6f 6e 5d 2e 0a 0a 3c 74 63 6c 3e 0a 23  ation]...<tcl>.#
30b40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30b50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30b60 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30b70 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
30b80 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
30b90 63 74 69 6f 6e 20 55 50 44 41 54 45 20 75 70 64  ction UPDATE upd
30ba0 61 74 65 20 7b 55 50 44 41 54 45 20 2a 55 50 44  ate {UPDATE *UPD
30bb0 41 54 45 73 7d 0a 0a 52 65 63 75 72 73 69 76 65  ATEs}..Recursive
30bc0 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 75 70  BubbleDiagram up
30bd0 64 61 74 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e  date-stmt.</tcl>
30be0 0a 0a 3c 70 3e 5e 41 6e 20 55 50 44 41 54 45 20  ..<p>^An UPDATE 
30bf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 65  statement is use
30c00 64 20 74 6f 20 6d 6f 64 69 66 79 20 61 20 73 75  d to modify a su
30c10 62 73 65 74 20 6f 66 20 74 68 65 20 76 61 6c 75  bset of the valu
30c20 65 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 7a 65  es stored in .ze
30c30 72 6f 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20  ro or more rows 
30c40 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
30c50 74 61 62 6c 65 20 69 64 65 6e 74 69 66 69 65 64  table identified
30c60 20 62 79 20 74 68 65 20 0a 5b 71 75 61 6c 69 66   by the .[qualif
30c70 69 65 64 2d 74 61 62 6c 65 2d 6e 61 6d 65 5d 20  ied-table-name] 
30c80 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
30c90 74 20 6f 66 20 74 68 65 20 55 50 44 41 54 45 20  t of the UPDATE 
30ca0 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 5e  statement...<p>^
30cb0 49 66 20 74 68 65 20 55 50 44 41 54 45 20 73 74  If the UPDATE st
30cc0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
30cd0 20 68 61 76 65 20 61 20 57 48 45 52 45 20 63 6c   have a WHERE cl
30ce0 61 75 73 65 2c 20 61 6c 6c 20 72 6f 77 73 20 69  ause, all rows i
30cf0 6e 20 74 68 65 0a 74 61 62 6c 65 20 61 72 65 20  n the.table are 
30d00 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
30d10 55 50 44 41 54 45 2e 20 5e 4f 74 68 65 72 77 69  UPDATE. ^Otherwi
30d20 73 65 2c 20 74 68 65 20 55 50 44 41 54 45 20 61  se, the UPDATE a
30d30 66 66 65 63 74 73 20 6f 6e 6c 79 20 74 68 6f 73  ffects only thos
30d40 65 0a 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68  e.rows for which
30d50 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
30d60 65 0a 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65  e.[boolean expre
30d70 73 73 69 6f 6e 7c 62 6f 6f 6c 65 61 6e 20 65 78  ssion|boolean ex
30d80 70 72 65 73 73 69 6f 6e 20 69 73 20 74 72 75 65  pression is true
30d90 5d 2e 20 5e 49 74 20 69 73 20 6e 6f 74 20 61 6e  ]. ^It is not an
30da0 20 65 72 72 6f 72 20 69 66 20 74 68 65 0a 57 48   error if the.WH
30db0 45 52 45 20 63 6c 61 75 73 65 20 64 6f 65 73 20  ERE clause does 
30dc0 6e 6f 74 20 65 76 61 6c 75 61 74 65 20 74 6f 20  not evaluate to 
30dd0 74 72 75 65 20 66 6f 72 20 61 6e 79 20 72 6f 77  true for any row
30de0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 2d 20   in the table - 
30df0 74 68 69 73 20 6a 75 73 74 0a 6d 65 61 6e 73 20  this just.means 
30e00 74 68 61 74 20 74 68 65 20 55 50 44 41 54 45 20  that the UPDATE 
30e10 73 74 61 74 65 6d 65 6e 74 20 61 66 66 65 63 74  statement affect
30e20 73 20 7a 65 72 6f 20 72 6f 77 73 2e 0a 0a 3c 70  s zero rows...<p
30e30 3e 54 68 65 20 6d 6f 64 69 66 69 63 61 74 69 6f  >The modificatio
30e40 6e 73 20 6d 61 64 65 20 74 6f 20 65 61 63 68 20  ns made to each 
30e50 72 6f 77 20 61 66 66 65 63 74 65 64 20 62 79 20  row affected by 
30e60 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  an UPDATE statem
30e70 65 6e 74 20 61 72 65 0a 64 65 74 65 72 6d 69 6e  ent are.determin
30e80 65 64 20 62 79 20 74 68 65 20 6c 69 73 74 20 6f  ed by the list o
30e90 66 20 61 73 73 69 67 6e 6d 65 6e 74 73 20 66 6f  f assignments fo
30ea0 6c 6c 6f 77 69 6e 67 20 74 68 65 20 53 45 54 20  llowing the SET 
30eb0 6b 65 79 77 6f 72 64 2e 20 45 61 63 68 0a 61 73  keyword. Each.as
30ec0 73 69 67 6e 6d 65 6e 74 20 73 70 65 63 69 66 69  signment specifi
30ed0 65 73 20 61 20 3c 79 79 74 65 72 6d 3e 63 6f 6c  es a <yyterm>col
30ee0 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  umn-name</yyterm
30ef0 3e 20 74 6f 20 74 68 65 20 6c 65 66 74 20 6f 66  > to the left of
30f00 20 74 68 65 20 0a 65 71 75 61 6c 73 20 73 69 67   the .equals sig
30f10 6e 20 61 6e 64 20 61 20 73 63 61 6c 61 72 20 65  n and a scalar e
30f20 78 70 72 65 73 73 69 6f 6e 20 74 6f 20 74 68 65  xpression to the
30f30 20 72 69 67 68 74 2e 20 0a 5e 46 6f 72 20 65 61   right. .^For ea
30f40 63 68 20 61 66 66 65 63 74 65 64 20 72 6f 77 2c  ch affected row,
30f50 20 74 68 65 20 6e 61 6d 65 64 20 63 6f 6c 75 6d   the named colum
30f60 6e 73 0a 61 72 65 20 73 65 74 20 74 6f 20 74 68  ns.are set to th
30f70 65 20 76 61 6c 75 65 73 20 66 6f 75 6e 64 20 62  e values found b
30f80 79 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  y evaluating the
30f90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
30fa0 63 61 6c 61 72 20 0a 65 78 70 72 65 73 73 69 6f  calar .expressio
30fb0 6e 73 2e 20 5e 49 66 20 61 20 73 69 6e 67 6c 65  ns. ^If a single
30fc0 20 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 20 61 70 70   column-name app
30fd0 65 61 72 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ears more than o
30fe0 6e 63 65 20 69 6e 20 74 68 65 20 6c 69 73 74 20  nce in the list 
30ff0 6f 66 0a 61 73 73 69 67 6e 6d 65 6e 74 20 65 78  of.assignment ex
31000 70 72 65 73 73 69 6f 6e 73 2c 20 61 6c 6c 20 62  pressions, all b
31010 75 74 20 74 68 65 20 72 69 67 68 74 6d 6f 73 74  ut the rightmost
31020 20 6f 63 63 75 72 72 65 6e 63 65 20 69 73 20 69   occurrence is i
31030 67 6e 6f 72 65 64 2e 20 5e 43 6f 6c 75 6d 6e 73  gnored. ^Columns
31040 0a 74 68 61 74 20 64 6f 20 6e 6f 74 20 61 70 70  .that do not app
31050 65 61 72 20 69 6e 20 74 68 65 20 6c 69 73 74 20  ear in the list 
31060 6f 66 20 61 73 73 69 67 6e 6d 65 6e 74 73 20 61  of assignments a
31070 72 65 20 6c 65 66 74 20 75 6e 6d 6f 64 69 66 69  re left unmodifi
31080 65 64 2e 20 5e 54 68 65 20 73 63 61 6c 61 72 0a  ed. ^The scalar.
31090 65 78 70 72 65 73 73 69 6f 6e 73 20 6d 61 79 20  expressions may 
310a0 72 65 66 65 72 20 74 6f 20 63 6f 6c 75 6d 6e 73  refer to columns
310b0 20 6f 66 20 74 68 65 20 72 6f 77 20 62 65 69 6e   of the row bein
310c0 67 20 75 70 64 61 74 65 64 2e 20 5e 49 6e 20 74  g updated. ^In t
310d0 68 69 73 20 63 61 73 65 20 61 6c 6c 0a 73 63 61  his case all.sca
310e0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 73 20  lar expressions 
310f0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
31100 66 6f 72 65 20 61 6e 79 20 61 73 73 69 67 6e 6d  fore any assignm
31110 65 6e 74 73 20 61 72 65 20 6d 61 64 65 2e 0a 0a  ents are made...
31120 3c 70 3e 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20  <p>Beginning in 
31130 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
31140 33 2e 31 35 2e 30 5d 20 28 5b 64 61 74 65 6f 66  3.15.0] ([dateof
31150 3a 33 2e 31 35 2e 30 5d 29 2c 20 61 6e 20 61 73  :3.15.0]), an as
31160 73 69 67 6e 6d 65 6e 74 20 69 6e 0a 74 68 65 20  signment in.the 
31170 53 45 54 20 63 6c 61 75 73 65 20 63 61 6e 20 62  SET clause can b
31180 65 20 61 20 0a 5b 63 6f 6c 75 6d 6e 2d 6e 61 6d  e a .[column-nam
31190 65 2d 6c 69 73 74 7c 70 61 72 65 6e 74 68 65 73  e-list|parenthes
311a0 69 7a 65 64 20 6c 69 73 74 20 6f 66 20 63 6f 6c  ized list of col
311b0 75 6d 6e 20 6e 61 6d 65 73 5d 20 6f 6e 20 74 68  umn names] on th
311c0 65 20 6c 65 66 74 20 61 6e 64 20 61 0a 5b 72 6f  e left and a.[ro
311d0 77 20 76 61 6c 75 65 5d 20 6f 66 20 74 68 65 20  w value] of the 
311e0 73 61 6d 65 20 73 69 7a 65 20 6f 6e 20 74 68 65  same size on the
311f0 20 72 69 67 68 74 2e 0a 0a 0a 3c 70 3e 5e 54 68   right....<p>^Th
31200 65 20 6f 70 74 69 6f 6e 61 6c 20 22 4f 52 20 3c  e optional "OR <
31210 69 3e 61 63 74 69 6f 6e 3c 2f 69 3e 22 20 63 6f  i>action</i>" co
31220 6e 66 6c 69 63 74 20 63 6c 61 75 73 65 20 74 68  nflict clause th
31230 61 74 20 66 6f 6c 6c 6f 77 73 20 74 68 65 0a 55  at follows the.U
31240 50 44 41 54 45 20 6b 65 79 77 6f 72 64 20 61 6c  PDATE keyword al
31250 6c 6f 77 73 20 74 68 65 20 75 73 65 72 20 74 6f  lows the user to
31260 20 6e 6f 6d 69 6e 61 74 65 20 61 20 73 70 65 63   nominate a spec
31270 69 66 69 63 0a 63 6f 6e 73 74 72 61 69 6e 74 20  ific.constraint 
31280 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
31290 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 74 6f  ion algorithm to
312a0 20 75 73 65 20 64 75 72 69 6e 67 20 74 68 69 73   use during this
312b0 20 6f 6e 65 20 55 50 44 41 54 45 20 63 6f 6d 6d   one UPDATE comm
312c0 61 6e 64 2e 0a 52 65 66 65 72 20 74 6f 20 74 68  and..Refer to th
312d0 65 20 73 65 63 74 69 6f 6e 20 65 6e 74 69 74 6c  e section entitl
312e0 65 64 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  ed [ON CONFLICT]
312f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
31300 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 0a 3c 68  information...<h
31310 33 3e 52 65 73 74 72 69 63 74 69 6f 6e 73 20 6f  3>Restrictions o
31320 6e 20 55 50 44 41 54 45 20 53 74 61 74 65 6d 65  n UPDATE Stateme
31330 6e 74 73 20 57 69 74 68 69 6e 20 43 52 45 41 54  nts Within CREAT
31340 45 20 54 52 49 47 47 45 52 3c 2f 68 33 3e 0a 0a  E TRIGGER</h3>..
31350 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  <p>The following
31360 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 79 6e 74   additional synt
31370 61 78 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20  ax restrictions 
31380 61 70 70 6c 79 20 74 6f 20 55 50 44 41 54 45 20  apply to UPDATE 
31390 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 0a  statements that.
313a0 6f 63 63 75 72 20 77 69 74 68 69 6e 20 74 68 65  occur within the
313b0 20 62 6f 64 79 20 6f 66 20 61 20 5b 43 52 45 41   body of a [CREA
313c0 54 45 20 54 52 49 47 47 45 52 5d 20 73 74 61 74  TE TRIGGER] stat
313d0 65 6d 65 6e 74 2e 20 20 0a 0a 3c 75 6c 3e 0a 20  ement.  ..<ul>. 
313e0 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 3c 79 79   <li><p>^The <yy
313f0 74 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c  term>table-name<
31400 2f 79 79 74 65 72 6d 3e 20 73 70 65 63 69 66 69  /yyterm> specifi
31410 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 61 6e  ed as part of an
31420 20 55 50 44 41 54 45 20 0a 20 20 20 20 20 20 73   UPDATE .      s
31430 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 0a  tatement within.
31440 20 20 20 20 20 20 61 20 74 72 69 67 67 65 72 20        a trigger 
31450 62 6f 64 79 20 6d 75 73 74 20 62 65 20 75 6e 71  body must be unq
31460 75 61 6c 69 66 69 65 64 2e 20 5e 28 49 6e 20 6f  ualified. ^(In o
31470 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 0a  ther words, the.
31480 20 20 20 20 20 20 3c 69 3e 73 63 68 65 6d 61 2d        <i>schema-
31490 6e 61 6d 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62 3e  name</i><b>.</b>
314a0 20 70 72 65 66 69 78 20 6f 6e 20 74 68 65 20 74   prefix on the t
314b0 61 62 6c 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  able name of the
314c0 20 55 50 44 41 54 45 20 69 73 0a 20 20 20 20 20   UPDATE is.     
314d0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 77 69 74   not allowed wit
314e0 68 69 6e 20 74 72 69 67 67 65 72 73 2e 29 5e 20  hin triggers.)^ 
314f0 5e 55 6e 6c 65 73 73 20 74 68 65 20 74 61 62 6c  ^Unless the tabl
31500 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 74  e to which the t
31510 72 69 67 67 65 72 0a 20 20 20 20 20 20 69 73 20  rigger.      is 
31520 61 74 74 61 63 68 65 64 20 69 73 20 69 6e 20 74  attached is in t
31530 68 65 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  he TEMP database
31540 2c 20 74 68 65 20 74 61 62 6c 65 20 62 65 69 6e  , the table bein
31550 67 20 75 70 64 61 74 65 64 20 62 79 20 74 68 65  g updated by the
31560 0a 20 20 20 20 20 20 74 72 69 67 67 65 72 20 70  .      trigger p
31570 72 6f 67 72 61 6d 20 6d 75 73 74 20 72 65 73 69  rogram must resi
31580 64 65 20 69 6e 20 74 68 65 20 73 61 6d 65 20 64  de in the same d
31590 61 74 61 62 61 73 65 20 61 73 20 69 74 2e 20 5e  atabase as it. ^
315a0 49 66 20 74 68 65 20 74 61 62 6c 65 0a 20 20 20  If the table.   
315b0 20 20 20 74 6f 20 77 68 69 63 68 20 74 68 65 20     to which the 
315c0 74 72 69 67 67 65 72 20 69 73 20 61 74 74 61 63  trigger is attac
315d0 68 65 64 20 69 73 20 69 6e 20 74 68 65 20 54 45  hed is in the TE
315e0 4d 50 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  MP database, the
315f0 6e 20 74 68 65 0a 20 20 20 20 20 20 75 6e 71 75  n the.      unqu
31600 61 6c 69 66 69 65 64 20 6e 61 6d 65 20 6f 66 20  alified name of 
31610 74 68 65 20 74 61 62 6c 65 20 62 65 69 6e 67 20  the table being 
31620 75 70 64 61 74 65 64 20 69 73 20 72 65 73 6f 6c  updated is resol
31630 76 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ved in the same 
31640 77 61 79 0a 20 20 20 20 20 20 61 73 20 69 74 20  way.      as it 
31650 69 73 20 66 6f 72 20 61 20 74 6f 70 2d 6c 65 76  is for a top-lev
31660 65 6c 20 73 74 61 74 65 6d 65 6e 74 20 28 62 79  el statement (by
31670 20 73 65 61 72 63 68 69 6e 67 20 66 69 72 73 74   searching first
31680 20 74 68 65 20 54 45 4d 50 20 64 61 74 61 62 61   the TEMP databa
31690 73 65 2c 0a 20 20 20 20 20 20 74 68 65 6e 20 74  se,.      then t
316a0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
316b0 2c 20 74 68 65 6e 20 61 6e 79 20 6f 74 68 65 72  , then any other
316c0 20 64 61 74 61 62 61 73 65 73 20 69 6e 20 74 68   databases in th
316d0 65 20 6f 72 64 65 72 20 74 68 65 79 20 77 65 72  e order they wer
316e0 65 0a 20 20 20 20 20 20 61 74 74 61 63 68 65 64  e.      attached
316f0 29 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68  )...  <li><p>^Th
31700 65 20 49 4e 44 45 58 45 44 20 42 59 20 61 6e 64  e INDEXED BY and
31710 20 4e 4f 54 20 49 4e 44 45 58 45 44 20 63 6c 61   NOT INDEXED cla
31720 75 73 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 6c  uses are not all
31730 6f 77 65 64 20 6f 6e 20 55 50 44 41 54 45 0a 20  owed on UPDATE. 
31740 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
31750 77 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 2e  within triggers.
31760 3c 2f 70 3e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  </p>..  <li><p>^
31770 54 68 65 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52  The LIMIT and OR
31780 44 45 52 20 42 59 20 63 6c 61 75 73 65 73 20 66  DER BY clauses f
31790 6f 72 20 55 50 44 41 54 45 20 61 72 65 20 75 6e  or UPDATE are un
317a0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
317b0 0a 20 20 20 20 20 20 74 72 69 67 67 65 72 73 2c  .      triggers,
317c0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
317d0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  he compilation o
317e0 70 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ptions used to b
317f0 75 69 6c 64 20 53 51 4c 69 74 65 2e 0a 3c 2f 75  uild SQLite..</u
31800 6c 3e 0a 0a 3c 68 33 3e 4f 70 74 69 6f 6e 61 6c  l>..<h3>Optional
31810 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52 44 45 52   LIMIT and ORDER
31820 20 42 59 20 43 6c 61 75 73 65 73 3c 2f 68 33 3e   BY Clauses</h3>
31830 0a 0a 3c 70 3e 5e 28 49 66 20 53 51 4c 69 74 65  ..<p>^(If SQLite
31840 20 69 73 20 62 75 69 6c 74 20 77 69 74 68 20 74   is built with t
31850 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
31860 45 5f 55 50 44 41 54 45 5f 44 45 4c 45 54 45 5f  E_UPDATE_DELETE_
31870 4c 49 4d 49 54 5d 0a 63 6f 6d 70 69 6c 65 2d 74  LIMIT].compile-t
31880 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 20  ime option then 
31890 74 68 65 20 73 79 6e 74 61 78 20 6f 66 20 74 68  the syntax of th
318a0 65 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  e UPDATE stateme
318b0 6e 74 20 69 73 20 65 78 74 65 6e 64 65 64 0a 77  nt is extended.w
318c0 69 74 68 20 6f 70 74 69 6f 6e 61 6c 20 4f 52 44  ith optional ORD
318d0 45 52 20 42 59 20 61 6e 64 20 4c 49 4d 49 54 20  ER BY and LIMIT 
318e0 63 6c 61 75 73 65 73 29 5e 20 61 73 20 66 6f 6c  clauses)^ as fol
318f0 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  lows:</p>..<tcl>
31900 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 75 70  BubbleDiagram up
31910 64 61 74 65 2d 73 74 6d 74 2d 6c 69 6d 69 74 65  date-stmt-limite
31920 64 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 49 66 20  d</tcl>..<p>^If 
31930 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  an UPDATE statem
31940 65 6e 74 20 68 61 73 20 61 20 4c 49 4d 49 54 20  ent has a LIMIT 
31950 63 6c 61 75 73 65 2c 20 74 68 65 20 6d 61 78 69  clause, the maxi
31960 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  mum number of ro
31970 77 73 20 74 68 61 74 0a 77 69 6c 6c 20 62 65 20  ws that.will be 
31980 75 70 64 61 74 65 64 20 69 73 20 66 6f 75 6e 64  updated is found
31990 20 62 79 20 65 76 61 6c 75 61 74 69 6e 67 20 74   by evaluating t
319a0 68 65 20 61 63 63 6f 6d 70 61 6e 79 69 6e 67 20  he accompanying 
319b0 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64 20 63  expression and c
319c0 61 73 74 69 6e 67 0a 69 74 20 74 6f 20 61 6e 20  asting.it to an 
319d0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 2e 20 5e  integer value. ^
319e0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
319f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
31a00 61 73 20 22 6e 6f 20 6c 69 6d 69 74 22 2e 0a 0a  as "no limit"...
31a10 3c 70 3e 5e 49 66 20 74 68 65 20 4c 49 4d 49 54  <p>^If the LIMIT
31a20 20 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c   expression eval
31a30 75 61 74 65 73 20 74 6f 20 6e 6f 6e 2d 6e 65 67  uates to non-neg
31a40 61 74 69 76 65 20 76 61 6c 75 65 20 3c 69 3e 4e  ative value <i>N
31a50 3c 2f 69 3e 20 61 6e 64 20 74 68 65 0a 55 50 44  </i> and the.UPD
31a60 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20 68 61  ATE statement ha
31a70 73 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c  s an ORDER BY cl
31a80 61 75 73 65 2c 20 74 68 65 6e 20 61 6c 6c 20 72  ause, then all r
31a90 6f 77 73 20 74 68 61 74 20 77 6f 75 6c 64 20 62  ows that would b
31aa0 65 20 75 70 64 61 74 65 64 20 69 6e 0a 74 68 65  e updated in.the
31ab0 20 61 62 73 65 6e 63 65 20 6f 66 20 74 68 65 20   absence of the 
31ac0 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 61 72 65  LIMIT clause are
31ad0 20 73 6f 72 74 65 64 20 61 63 63 6f 72 64 69 6e   sorted accordin
31ae0 67 20 74 6f 20 74 68 65 20 4f 52 44 45 52 20 42  g to the ORDER B
31af0 59 20 61 6e 64 20 74 68 65 0a 66 69 72 73 74 20  Y and the.first 
31b00 3c 69 3e 4e 3c 2f 69 3e 20 75 70 64 61 74 65 64  <i>N</i> updated
31b10 2e 20 5e 28 49 66 20 74 68 65 20 55 50 44 41 54  . ^(If the UPDAT
31b20 45 20 73 74 61 74 65 6d 65 6e 74 20 61 6c 73 6f  E statement also
31b30 20 68 61 73 20 61 6e 20 4f 46 46 53 45 54 20 63   has an OFFSET c
31b40 6c 61 75 73 65 2c 0a 74 68 65 6e 20 69 74 20 69  lause,.then it i
31b50 73 20 73 69 6d 69 6c 61 72 6c 79 20 65 76 61 6c  s similarly eval
31b60 75 61 74 65 64 20 61 6e 64 20 63 61 73 74 20 74  uated and cast t
31b70 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c  o an integer val
31b80 75 65 2e 20 49 66 20 74 68 65 20 4f 46 46 53 45  ue. If the OFFSE
31b90 54 0a 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61  T.expression eva
31ba0 6c 75 61 74 65 73 20 74 6f 20 61 20 6e 6f 6e 2d  luates to a non-
31bb0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 3c  negative value <
31bc0 69 3e 4d 3c 2f 69 3e 2c 20 74 68 65 6e 20 74 68  i>M</i>, then th
31bd0 65 20 66 69 72 73 74 20 3c 69 3e 4d 3c 2f 69 3e  e first <i>M</i>
31be0 0a 72 6f 77 73 20 61 72 65 20 73 6b 69 70 70 65  .rows are skippe
31bf0 64 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  d and the follow
31c00 69 6e 67 20 3c 69 3e 4e 3c 2f 69 3e 20 72 6f 77  ing <i>N</i> row
31c10 73 20 75 70 64 61 74 65 64 20 69 6e 73 74 65 61  s updated instea
31c20 64 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65  d.)^..<p>^If the
31c30 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
31c40 74 20 68 61 73 20 6e 6f 20 4f 52 44 45 52 20 42  t has no ORDER B
31c50 59 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20 61  Y clause, then a
31c60 6c 6c 20 72 6f 77 73 20 74 68 61 74 0a 77 6f 75  ll rows that.wou
31c70 6c 64 20 62 65 20 75 70 64 61 74 65 64 20 69 6e  ld be updated in
31c80 20 74 68 65 20 61 62 73 65 6e 63 65 20 6f 66 20   the absence of 
31c90 74 68 65 20 4c 49 4d 49 54 20 63 6c 61 75 73 65  the LIMIT clause
31ca0 20 61 72 65 20 61 73 73 65 6d 62 6c 65 64 20 69   are assembled i
31cb0 6e 20 61 6e 0a 61 72 62 69 74 72 61 72 79 20 6f  n an.arbitrary o
31cc0 72 64 65 72 20 62 65 66 6f 72 65 20 61 70 70 6c  rder before appl
31cd0 79 69 6e 67 20 74 68 65 20 4c 49 4d 49 54 20 61  ying the LIMIT a
31ce0 6e 64 20 4f 46 46 53 45 54 20 63 6c 61 75 73 65  nd OFFSET clause
31cf0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 0a  s to determine .
31d00 77 68 69 63 68 20 61 72 65 20 61 63 74 75 61 6c  which are actual
31d10 6c 79 20 75 70 64 61 74 65 64 2e 0a 0a 3c 70 3e  ly updated...<p>
31d20 5e 28 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  ^(The ORDER BY c
31d30 6c 61 75 73 65 20 6f 6e 20 61 6e 20 55 50 44 41  lause on an UPDA
31d40 54 45 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  TE statement is 
31d50 75 73 65 64 20 6f 6e 6c 79 20 74 6f 20 64 65 74  used only to det
31d60 65 72 6d 69 6e 65 20 77 68 69 63 68 0a 72 6f 77  ermine which.row
31d70 73 20 66 61 6c 6c 20 77 69 74 68 69 6e 20 74 68  s fall within th
31d80 65 20 4c 49 4d 49 54 2e 20 54 68 65 20 6f 72 64  e LIMIT. The ord
31d90 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f 77 73  er in which rows
31da0 20 61 72 65 20 6d 6f 64 69 66 69 65 64 20 69 73   are modified is
31db0 20 61 72 62 69 74 72 61 72 79 0a 61 6e 64 20 69   arbitrary.and i
31dc0 73 20 6e 6f 74 20 69 6e 66 6c 75 65 6e 63 65 64  s not influenced
31dd0 20 62 79 20 74 68 65 20 4f 52 44 45 52 20 42 59   by the ORDER BY
31de0 20 63 6c 61 75 73 65 2e 29 5e 0a 0a 3c 74 63 6c   clause.)^..<tcl
31df0 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
31e00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31e10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31e20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31e30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
31e40 0a 53 65 63 74 69 6f 6e 20 56 41 43 55 55 4d 20  .Section VACUUM 
31e50 76 61 63 75 75 6d 20 56 41 43 55 55 4d 0a 0a 52  vacuum VACUUM..R
31e60 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
31e70 61 67 72 61 6d 20 76 61 63 75 75 6d 2d 73 74 6d  agram vacuum-stm
31e80 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 20 20  t.</tcl>..<p>.  
31e90 54 68 65 20 56 41 43 55 55 4d 20 63 6f 6d 6d 61  The VACUUM comma
31ea0 6e 64 20 72 65 62 75 69 6c 64 73 20 74 68 65 20  nd rebuilds the 
31eb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 72  database file, r
31ec0 65 70 61 63 6b 69 6e 67 20 69 74 20 69 6e 74 6f  epacking it into
31ed0 20 61 20 6d 69 6e 69 6d 61 6c 0a 20 20 61 6d 6f   a minimal.  amo
31ee0 75 6e 74 20 6f 66 20 64 69 73 6b 20 73 70 61 63  unt of disk spac
31ef0 65 2e 20 54 68 65 72 65 20 61 72 65 20 73 65 76  e. There are sev
31f00 65 72 61 6c 20 0a 20 20 72 65 61 73 6f 6e 73 20  eral .  reasons 
31f10 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
31f20 69 67 68 74 20 64 6f 20 74 68 69 73 3a 0a 0a 3c  ight do this:..<
31f30 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 20 5e  ul>.  <li> <p> ^
31f40 55 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  Unless SQLite is
31f50 20 72 75 6e 6e 69 6e 67 20 69 6e 20 22 61 75 74   running in "aut
31f60 6f 5f 76 61 63 75 75 6d 3d 46 55 4c 4c 22 20 6d  o_vacuum=FULL" m
31f70 6f 64 65 2c 20 77 68 65 6e 20 61 20 6c 61 72 67  ode, when a larg
31f80 65 0a 20 20 20 20 20 61 6d 6f 75 6e 74 20 6f 66  e.     amount of
31f90 20 64 61 74 61 20 69 73 20 64 65 6c 65 74 65 64   data is deleted
31fa0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
31fb0 73 65 20 66 69 6c 65 20 69 74 20 6c 65 61 76 65  se file it leave
31fc0 73 20 62 65 68 69 6e 64 20 65 6d 70 74 79 0a 20  s behind empty. 
31fd0 20 20 20 20 73 70 61 63 65 2c 20 6f 72 20 22 66      space, or "f
31fe0 72 65 65 22 20 64 61 74 61 62 61 73 65 20 70 61  ree" database pa
31ff0 67 65 73 2e 20 54 68 69 73 20 6d 65 61 6e 73 20  ges. This means 
32000 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
32010 65 20 6d 69 67 68 74 0a 20 20 20 20 20 62 65 20  e might.     be 
32020 6c 61 72 67 65 72 20 74 68 61 6e 20 73 74 72 69  larger than stri
32030 63 74 6c 79 20 6e 65 63 65 73 73 61 72 79 2e 20  ctly necessary. 
32040 5e 52 75 6e 6e 69 6e 67 20 56 41 43 55 55 4d 20  ^Running VACUUM 
32050 74 6f 20 72 65 62 75 69 6c 64 20 74 68 65 20 0a  to rebuild the .
32060 20 20 20 20 20 64 61 74 61 62 61 73 65 20 72 65       database re
32070 63 6c 61 69 6d 73 20 74 68 69 73 20 73 70 61 63  claims this spac
32080 65 20 61 6e 64 20 72 65 64 75 63 65 73 20 74 68  e and reduces th
32090 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
320a0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 0a 20 20  tabase file...  
320b0 3c 6c 69 3e 20 3c 70 3e 20 5e 46 72 65 71 75 65  <li> <p> ^Freque
320c0 6e 74 20 69 6e 73 65 72 74 73 2c 20 75 70 64 61  nt inserts, upda
320d0 74 65 73 2c 20 61 6e 64 20 64 65 6c 65 74 65 73  tes, and deletes
320e0 20 63 61 6e 20 63 61 75 73 65 20 74 68 65 20 64   can cause the d
320f0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 20 20 20  atabase file.   
32100 20 20 74 6f 20 62 65 63 6f 6d 65 20 66 72 61 67    to become frag
32110 6d 65 6e 74 65 64 20 2d 20 77 68 65 72 65 20 64  mented - where d
32120 61 74 61 20 66 6f 72 20 61 20 73 69 6e 67 6c 65  ata for a single
32130 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 20   table or index 
32140 69 73 20 73 63 61 74 74 65 72 65 64 20 0a 20 20  is scattered .  
32150 20 20 20 61 72 6f 75 6e 64 20 74 68 65 20 64 61     around the da
32160 74 61 62 61 73 65 20 66 69 6c 65 2e 20 5e 52 75  tabase file. ^Ru
32170 6e 6e 69 6e 67 20 56 41 43 55 55 4d 20 65 6e 73  nning VACUUM ens
32180 75 72 65 73 20 74 68 61 74 20 65 61 63 68 20 74  ures that each t
32190 61 62 6c 65 20 61 6e 64 0a 20 20 20 20 20 69 6e  able and.     in
321a0 64 65 78 20 69 73 20 6c 61 72 67 65 6c 79 20 73  dex is largely s
321b0 74 6f 72 65 64 20 63 6f 6e 74 69 67 75 6f 75 73  tored contiguous
321c0 6c 79 20 77 69 74 68 69 6e 20 74 68 65 20 64 61  ly within the da
321d0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 5e 49 6e  tabase file. ^In
321e0 20 73 6f 6d 65 0a 20 20 20 20 20 63 61 73 65 73   some.     cases
321f0 2c 20 56 41 43 55 55 4d 20 6d 61 79 20 61 6c 73  , VACUUM may als
32200 6f 20 72 65 64 75 63 65 20 74 68 65 20 6e 75 6d  o reduce the num
32210 62 65 72 20 6f 66 20 70 61 72 74 69 61 6c 6c 79  ber of partially
32220 20 66 69 6c 6c 65 64 20 70 61 67 65 73 20 69 6e   filled pages in
32230 0a 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61  .     the databa
32240 73 65 2c 20 72 65 64 75 63 69 6e 67 20 74 68 65  se, reducing the
32250 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
32260 61 62 61 73 65 20 66 69 6c 65 20 66 75 72 74 68  abase file furth
32270 65 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 20  er...  <li> <p> 
32280 5e 4e 6f 72 6d 61 6c 6c 79 2c 20 74 68 65 20 64  ^Normally, the d
32290 61 74 61 62 61 73 65 20 5b 70 61 67 65 5f 73 69  atabase [page_si
322a0 7a 65 5d 20 61 6e 64 20 77 68 65 74 68 65 72 20  ze] and whether 
322b0 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62  or not the datab
322c0 61 73 65 0a 20 20 20 20 20 73 75 70 70 6f 72 74  ase.     support
322d0 73 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20  s [auto_vacuum] 
322e0 6d 75 73 74 20 62 65 20 63 6f 6e 66 69 67 75 72  must be configur
322f0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ed before the da
32300 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 0a 20  tabase file is. 
32310 20 20 20 20 61 63 74 75 61 6c 6c 79 20 63 72 65      actually cre
32320 61 74 65 64 2e 20 5e 48 6f 77 65 76 65 72 2c 20  ated. ^However, 
32330 77 68 65 6e 20 6e 6f 74 20 69 6e 20 5b 77 72 69  when not in [wri
32340 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 20 6d 6f  te-ahead log] mo
32350 64 65 2c 20 74 68 65 20 0a 20 20 20 20 20 5b 70  de, the .     [p
32360 61 67 65 5f 73 69 7a 65 5d 20 61 6e 64 2f 6f 72  age_size] and/or
32370 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20 70   [auto_vacuum] p
32380 72 6f 70 65 72 74 69 65 73 20 6f 66 20 61 6e 20  roperties of an 
32390 65 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  existing databas
323a0 65 20 6d 61 79 20 62 65 0a 20 20 20 20 20 63 68  e may be.     ch
323b0 61 6e 67 65 64 20 62 79 20 75 73 69 6e 67 20 74  anged by using t
323c0 68 65 20 5b 70 61 67 65 5f 73 69 7a 65 20 70 72  he [page_size pr
323d0 61 67 6d 61 7c 70 61 67 65 5f 73 69 7a 65 5d 20  agma|page_size] 
323e0 20 61 6e 64 2f 6f 72 20 0a 20 20 20 20 20 5b 61   and/or .     [a
323f0 75 74 6f 5f 76 61 63 75 75 6d 7c 70 72 61 67 6d  uto_vacuum|pragm
32400 61 20 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20 70  a auto_vacuum] p
32410 72 61 67 6d 61 73 20 61 6e 64 20 74 68 65 6e 20  ragmas and then 
32420 69 6d 6d 65 64 69 61 74 65 6c 79 20 56 41 43 55  immediately VACU
32430 55 4d 69 6e 67 0a 20 20 20 20 20 74 68 65 20 64  UMing.     the d
32440 61 74 61 62 61 73 65 2e 20 5e 57 68 65 6e 20 69  atabase. ^When i
32450 6e 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c  n [write-ahead l
32460 6f 67 5d 20 6d 6f 64 65 2c 20 6f 6e 6c 79 20 74  og] mode, only t
32470 68 65 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d  he [auto_vacuum]
32480 0a 20 20 20 20 20 73 75 70 70 6f 72 74 20 70 72  .     support pr
32490 6f 70 65 72 74 79 20 63 61 6e 20 62 65 20 63 68  operty can be ch
324a0 61 6e 67 65 64 20 75 73 69 6e 67 20 56 41 43 55  anged using VACU
324b0 55 4d 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e 42  UM..</ul>..<p>^B
324c0 79 20 64 65 66 61 75 6c 74 2c 20 56 41 43 55 55  y default, VACUU
324d0 4d 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 6c  M only works onl
324e0 79 20 6f 6e 20 74 68 65 20 6d 61 69 6e 20 64 61  y on the main da
324f0 74 61 62 61 73 65 2e 0a 5e 5b 41 54 54 41 43 48  tabase..^[ATTACH
32500 7c 41 74 74 61 63 68 65 64 20 64 61 74 61 62 61  |Attached databa
32510 73 65 73 5d 20 63 61 6e 20 62 65 20 76 61 63 75  ses] can be vacu
32520 75 6d 65 64 20 62 79 20 61 70 70 65 6e 64 69 6e  umed by appendin
32530 67 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  g the appropriat
32540 65 0a 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d 61  e.<yyterm>schema
32550 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 74  -name</yyterm> t
32560 6f 20 74 68 65 20 56 41 43 55 55 4d 20 73 74 61  o the VACUUM sta
32570 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 3c 62 3e 43  tement...<p><b>C
32580 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 57 61 72  ompatibility War
32590 6e 69 6e 67 3a 3c 2f 62 3e 20 54 68 65 20 61 62  ning:</b> The ab
325a0 69 6c 69 74 79 20 74 6f 20 76 61 63 75 75 6d 20  ility to vacuum 
325b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
325c0 65 73 20 77 61 73 0a 61 64 64 65 64 20 69 6e 20  es was.added in 
325d0 5b 76 65 72 73 69 6f 6e 20 33 2e 31 35 2e 30 5d  [version 3.15.0]
325e0 20 28 5b 64 61 74 65 6f 66 3a 33 2e 31 35 2e 30   ([dateof:3.15.0
325f0 5d 29 2e 20 20 50 72 69 6f 72 20 74 6f 20 74 68  ]).  Prior to th
32600 61 74 2c 20 61 20 0a 3c 79 79 74 65 72 6d 3e 73  at, a .<yyterm>s
32610 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74 65  chema-name</yyte
32620 72 6d 3e 20 61 64 64 65 64 20 74 6f 20 74 68 65  rm> added to the
32630 0a 56 41 43 55 55 4d 20 73 74 61 74 65 6d 65 6e  .VACUUM statemen
32640 74 20 77 6f 75 6c 64 20 62 65 20 73 69 6c 65 6e  t would be silen
32650 74 6c 79 20 69 67 6e 6f 72 65 64 20 61 6e 64 20  tly ignored and 
32660 74 68 65 20 22 6d 61 69 6e 22 20 73 63 68 65 6d  the "main" schem
32670 61 20 77 6f 75 6c 64 20 62 65 0a 76 61 63 75 75  a would be.vacuu
32680 6d 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68  med.</p>..<p>^Th
32690 65 20 56 41 43 55 55 4d 20 63 6f 6d 6d 61 6e 64  e VACUUM command
326a0 20 77 6f 72 6b 73 20 62 79 20 63 6f 70 79 69 6e   works by copyin
326b0 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  g the contents o
326c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
326d0 6e 74 6f 0a 61 20 74 65 6d 70 6f 72 61 72 79 20  nto.a temporary 
326e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 6e  database file an
326f0 64 20 74 68 65 6e 20 6f 76 65 72 77 72 69 74 69  d then overwriti
32700 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
32710 77 69 74 68 20 74 68 65 20 0a 63 6f 6e 74 65 6e  with the .conten
32720 74 73 20 6f 66 20 74 68 65 20 74 65 6d 70 6f 72  ts of the tempor
32730 61 72 79 20 66 69 6c 65 2e 20 5e 57 68 65 6e 20  ary file. ^When 
32740 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20  overwriting the 
32750 6f 72 69 67 69 6e 61 6c 2c 20 61 20 72 6f 6c 6c  original, a roll
32760 62 61 63 6b 0a 6a 6f 75 72 6e 61 6c 20 6f 72 20  back.journal or 
32770 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
32780 5d 20 57 41 4c 20 66 69 6c 65 20 69 73 20 75 73  ] WAL file is us
32790 65 64 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  ed just as it wo
327a0 75 6c 64 20 62 65 20 66 6f 72 20 61 6e 79 0a 6f  uld be for any.o
327b0 74 68 65 72 20 64 61 74 61 62 61 73 65 20 74 72  ther database tr
327c0 61 6e 73 61 63 74 69 6f 6e 2e 20 5e 54 68 69 73  ansaction. ^This
327d0 20 6d 65 61 6e 73 20 74 68 61 74 20 77 68 65 6e   means that when
327e0 20 56 41 43 55 55 4d 69 6e 67 20 61 20 64 61 74   VACUUMing a dat
327f0 61 62 61 73 65 2c 20 0a 61 73 20 6d 75 63 68 20  abase, .as much 
32800 61 73 20 74 77 69 63 65 20 74 68 65 20 73 69 7a  as twice the siz
32810 65 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  e of the origina
32820 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  l database file 
32830 69 73 20 72 65 71 75 69 72 65 64 20 69 6e 20 66  is required in f
32840 72 65 65 0a 64 69 73 6b 20 73 70 61 63 65 2e 0a  ree.disk space..
32850 0a 3c 70 3e 5e 54 68 65 20 56 41 43 55 55 4d 20  .<p>^The VACUUM 
32860 63 6f 6d 6d 61 6e 64 20 6d 61 79 20 63 68 61 6e  command may chan
32870 67 65 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ge the [ROWID | 
32880 52 4f 57 49 44 73 5d 20 6f 66 20 65 6e 74 72 69  ROWIDs] of entri
32890 65 73 20 69 6e 20 61 6e 79 0a 74 61 62 6c 65 73  es in any.tables
328a0 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 68 61 76   that do not hav
328b0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 5b 49  e an explicit [I
328c0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
328d0 45 59 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41  EY]..</p>..<p>^A
328e0 20 56 41 43 55 55 4d 20 77 69 6c 6c 20 66 61 69   VACUUM will fai
328f0 6c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  l if there is an
32900 20 6f 70 65 6e 20 74 72 61 6e 73 61 63 74 69 6f   open transactio
32910 6e 2c 20 6f 72 20 69 66 20 74 68 65 72 65 20 61  n, or if there a
32920 72 65 20 6f 6e 65 20 6f 72 0a 6d 6f 72 65 20 61  re one or.more a
32930 63 74 69 76 65 20 53 51 4c 20 73 74 61 74 65 6d  ctive SQL statem
32940 65 6e 74 73 20 77 68 65 6e 20 69 74 20 69 73 20  ents when it is 
32950 72 75 6e 2e 0a 0a 3c 70 3e 5e 28 41 6e 20 61 6c  run...<p>^(An al
32960 74 65 72 6e 61 74 69 76 65 20 74 6f 20 75 73 69  ternative to usi
32970 6e 67 20 74 68 65 20 56 41 43 55 55 4d 20 63 6f  ng the VACUUM co
32980 6d 6d 61 6e 64 20 74 6f 0a 72 65 63 6c 61 69 6d  mmand to.reclaim
32990 20 73 70 61 63 65 20 61 66 74 65 72 20 64 61 74   space after dat
329a0 61 20 68 61 73 20 62 65 65 6e 20 64 65 6c 65 74  a has been delet
329b0 65 64 20 69 73 20 61 75 74 6f 2d 76 61 63 75 75  ed is auto-vacuu
329c0 6d 20 6d 6f 64 65 2c 20 65 6e 61 62 6c 65 64 20  m mode, enabled 
329d0 75 73 69 6e 67 0a 74 68 65 20 5b 61 75 74 6f 5f  using.the [auto_
329e0 76 61 63 75 75 6d 5d 20 70 72 61 67 6d 61 2e 29  vacuum] pragma.)
329f0 5e 20 5e 57 68 65 6e 20 5b 61 75 74 6f 5f 76 61  ^ ^When [auto_va
32a00 63 75 75 6d 5d 20 69 73 20 65 6e 61 62 6c 65 64  cuum] is enabled
32a10 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 0a   for a database.
32a20 66 72 65 65 20 70 61 67 65 73 20 6d 61 79 20 62  free pages may b
32a30 65 20 72 65 63 6c 61 69 6d 65 64 20 61 66 74 65  e reclaimed afte
32a40 72 20 64 65 6c 65 74 69 6e 67 20 64 61 74 61 2c  r deleting data,
32a50 20 63 61 75 73 69 6e 67 20 74 68 65 20 66 69 6c   causing the fil
32a60 65 20 74 6f 20 73 68 72 69 6e 6b 2c 0a 77 69 74  e to shrink,.wit
32a70 68 6f 75 74 20 72 65 62 75 69 6c 64 69 6e 67 20  hout rebuilding 
32a80 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
32a90 61 73 65 20 75 73 69 6e 67 20 56 41 43 55 55 4d  ase using VACUUM
32aa0 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 75 73 69  .  ^However, usi
32ab0 6e 67 0a 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d  ng.[auto_vacuum]
32ac0 20 63 61 6e 20 6c 65 61 64 20 74 6f 20 65 78 74   can lead to ext
32ad0 72 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ra database file
32ae0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 2e 20   fragmentation. 
32af0 20 5e 41 6e 64 20 5b 61 75 74 6f 5f 76 61 63 75   ^And [auto_vacu
32b00 75 6d 5d 0a 64 6f 65 73 20 6e 6f 74 20 63 6f 6d  um].does not com
32b10 70 61 63 74 20 70 61 72 74 69 61 6c 6c 79 20 66  pact partially f
32b20 69 6c 6c 65 64 20 70 61 67 65 73 20 6f 66 20 74  illed pages of t
32b30 68 65 20 64 61 74 61 62 61 73 65 20 61 73 20 56  he database as V
32b40 41 43 55 55 4d 20 64 6f 65 73 2e 0a 0a 3c 2f 70  ACUUM does...</p
32b50 3e 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  >...<tcl>.######
32b60 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
32b70 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
32b80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
32b90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
32ba0 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
32bb0 20 7b 49 4e 44 45 58 45 44 20 42 59 7d 20 69 6e   {INDEXED BY} in
32bc0 64 65 78 65 64 62 79 20 7b 7b 49 4e 44 45 58 45  dexedby {{INDEXE
32bd0 44 20 42 59 7d 20 7b 4e 4f 54 20 49 4e 44 45 58  D BY} {NOT INDEX
32be0 45 44 7d 7d 0a 0a 3c 2f 74 63 6c 3e 0a 3c 70 3e  ED}}..</tcl>.<p>
32bf0 5e 54 68 65 20 49 4e 44 45 58 45 44 20 42 59 20  ^The INDEXED BY 
32c00 70 68 72 61 73 65 20 66 6f 72 63 65 73 20 74 68  phrase forces th
32c10 65 20 5b 53 51 4c 69 74 65 20 71 75 65 72 79 20  e [SQLite query 
32c20 70 6c 61 6e 6e 65 72 5d 20 74 6f 20 75 73 65 20  planner] to use 
32c30 61 0a 70 61 72 74 69 63 75 6c 61 72 20 6e 61 6d  a.particular nam
32c40 65 64 20 69 6e 64 65 78 20 6f 6e 20 61 20 5b 44  ed index on a [D
32c50 45 4c 45 54 45 5d 2c 20 5b 53 45 4c 45 43 54 5d  ELETE], [SELECT]
32c60 2c 20 6f 72 20 5b 55 50 44 41 54 45 5d 20 73 74  , or [UPDATE] st
32c70 61 74 65 6d 65 6e 74 2e 0a 54 68 65 20 49 4e 44  atement..The IND
32c80 45 58 45 44 20 42 59 20 70 68 72 61 73 65 20 69  EXED BY phrase i
32c90 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
32ca0 6e 73 69 6f 6e 20 61 6e 64 0a 69 73 20 6e 6f 74  nsion and.is not
32cb0 20 70 6f 72 74 61 62 6c 65 20 74 6f 20 6f 74 68   portable to oth
32cc0 65 72 20 53 51 4c 20 64 61 74 61 62 61 73 65 20  er SQL database 
32cd0 65 6e 67 69 6e 65 73 2e 3c 2f 70 3e 0a 0a 3c 74  engines.</p>..<t
32ce0 63 6c 3e 0a 52 65 63 75 72 73 69 76 65 42 75 62  cl>.RecursiveBub
32cf0 62 6c 65 44 69 61 67 72 61 6d 20 71 75 61 6c 69  bleDiagram quali
32d00 66 69 65 64 2d 74 61 62 6c 65 2d 6e 61 6d 65 0a  fied-table-name.
32d10 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20  </tcl>..<p>^The 
32d20 22 49 4e 44 45 58 45 44 20 42 59 20 3c 79 79 74  "INDEXED BY <yyt
32d30 65 72 6d 3e 69 6e 64 65 78 2d 6e 61 6d 65 3c 2f  erm>index-name</
32d40 79 79 74 65 72 6d 3e 22 20 70 68 72 61 73 65 20  yyterm>" phrase 
32d50 73 70 65 63 69 66 69 65 73 20 0a 74 68 61 74 20  specifies .that 
32d60 74 68 65 20 6e 61 6d 65 64 20 69 6e 64 65 78 0a  the named index.
32d70 6d 75 73 74 20 62 65 20 75 73 65 64 20 69 6e 20  must be used in 
32d80 6f 72 64 65 72 20 74 6f 20 6c 6f 6f 6b 20 75 70  order to look up
32d90 20 76 61 6c 75 65 73 20 6f 6e 20 74 68 65 20 70   values on the p
32da0 72 65 63 65 64 69 6e 67 20 74 61 62 6c 65 2e 0a  receding table..
32db0 5e 49 66 20 3c 79 79 74 65 72 6d 3e 69 6e 64 65  ^If <yyterm>inde
32dc0 78 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  x-name</yyterm> 
32dd0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 6f  does not exist o
32de0 72 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  r cannot be used
32df0 20 0a 66 6f 72 20 74 68 65 20 71 75 65 72 79 2c   .for the query,
32e00 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   then the prepar
32e10 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
32e20 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
32e30 2e 0a 5e 28 54 68 65 20 22 4e 4f 54 20 49 4e 44  ..^(The "NOT IND
32e40 45 58 45 44 22 20 63 6c 61 75 73 65 20 73 70 65  EXED" clause spe
32e50 63 69 66 69 65 73 20 74 68 61 74 20 6e 6f 20 69  cifies that no i
32e60 6e 64 65 78 20 73 68 61 6c 6c 20 62 65 20 75 73  ndex shall be us
32e70 65 64 20 77 68 65 6e 0a 61 63 63 65 73 73 69 6e  ed when.accessin
32e80 67 20 74 68 65 20 70 72 65 63 65 64 69 6e 67 20  g the preceding 
32e90 74 61 62 6c 65 2c 20 69 6e 63 6c 75 64 69 6e 67  table, including
32ea0 20 69 6d 70 6c 69 65 64 20 69 6e 64 69 63 65 73   implied indices
32eb0 20 63 72 65 61 74 65 20 62 79 0a 55 4e 49 51 55   create by.UNIQU
32ec0 45 20 61 6e 64 20 50 52 49 4d 41 52 59 20 4b 45  E and PRIMARY KE
32ed0 59 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 20 20  Y constraints.  
32ee0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b 72 6f  However, the [ro
32ef0 77 69 64 5d 0a 63 61 6e 20 73 74 69 6c 6c 20 62  wid].can still b
32f00 65 20 75 73 65 64 20 74 6f 20 6c 6f 6f 6b 20 75  e used to look u
32f10 70 20 65 6e 74 72 69 65 73 20 65 76 65 6e 20 77  p entries even w
32f20 68 65 6e 20 22 4e 4f 54 20 49 4e 44 45 58 45 44  hen "NOT INDEXED
32f30 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2e 29  " is specified.)
32f40 5e 3c 2f 70 3e 0a 0a 3c 70 3e 53 6f 6d 65 20 53  ^</p>..<p>Some S
32f50 51 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  QL database engi
32f60 6e 65 73 20 70 72 6f 76 69 64 65 20 6e 6f 6e 2d  nes provide non-
32f70 73 74 61 6e 64 61 72 64 20 22 68 69 6e 74 22 20  standard "hint" 
32f80 6d 65 63 68 61 6e 69 73 6d 73 20 77 68 69 63 68  mechanisms which
32f90 0a 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20  .can be used to 
32fa0 67 69 76 65 20 74 68 65 20 71 75 65 72 79 20 6f  give the query o
32fb0 70 74 69 6d 69 7a 65 72 20 63 6c 75 65 73 20 61  ptimizer clues a
32fc0 62 6f 75 74 20 77 68 61 74 20 69 6e 64 69 63 65  bout what indice
32fd0 73 20 69 74 20 73 68 6f 75 6c 64 0a 75 73 65 20  s it should.use 
32fe0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
32ff0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
33000 20 49 4e 44 45 58 20 42 59 20 63 6c 61 75 73 65   INDEX BY clause
33010 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 0a 3c   of SQLite is .<
33020 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 61 20 68 69  em>not</em> a hi
33030 6e 74 69 6e 67 20 6d 65 63 68 61 6e 69 73 6d 20  nting mechanism 
33040 61 6e 64 20 69 74 20 73 68 6f 75 6c 64 20 6e 6f  and it should no
33050 74 20 62 65 20 75 73 65 64 20 61 73 20 73 75 63  t be used as suc
33060 68 2e 0a 5e 54 68 65 20 49 4e 44 45 58 45 44 20  h..^The INDEXED 
33070 42 59 20 63 6c 61 75 73 65 20 64 6f 65 73 20 6e  BY clause does n
33080 6f 74 20 67 69 76 65 20 74 68 65 20 6f 70 74 69  ot give the opti
33090 6d 69 7a 65 72 20 68 69 6e 74 73 20 61 62 6f 75  mizer hints abou
330a0 74 20 77 68 69 63 68 20 69 6e 64 65 78 0a 74 6f  t which index.to
330b0 20 75 73 65 3b 20 69 74 20 67 69 76 65 73 20 74   use; it gives t
330c0 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 20 72  he optimizer a r
330d0 65 71 75 69 72 65 6d 65 6e 74 20 6f 66 20 77 68  equirement of wh
330e0 69 63 68 20 69 6e 64 65 78 20 74 6f 20 75 73 65  ich index to use
330f0 2e 0a 5e 49 66 20 74 68 65 20 71 75 65 72 79 20  ..^If the query 
33100 6f 70 74 69 6d 69 7a 65 72 20 69 73 20 75 6e 61  optimizer is una
33110 62 6c 65 20 74 6f 20 75 73 65 20 74 68 65 20 69  ble to use the i
33120 6e 64 65 78 20 73 70 65 63 69 66 69 65 64 20 62  ndex specified b
33130 79 20 74 68 65 0a 49 4e 44 45 58 20 42 59 20 63  y the.INDEX BY c
33140 6c 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20  lause, then the 
33150 71 75 65 72 79 20 77 69 6c 6c 20 66 61 69 6c 20  query will fail 
33160 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 3c 2f  with an error.</
33170 70 3e 0a 0a 3c 70 3e 54 68 65 20 49 4e 44 45 58  p>..<p>The INDEX
33180 45 44 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ED BY clause is 
33190 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 69 6e 74  <em>not</em> int
331a0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
331b0 20 74 75 6e 69 6e 67 0a 74 68 65 20 70 65 72 66   tuning.the perf
331c0 6f 72 6d 61 6e 63 65 20 6f 66 20 61 20 71 75 65  ormance of a que
331d0 72 79 2e 20 20 54 68 65 20 69 6e 74 65 6e 74 20  ry.  The intent 
331e0 6f 66 20 74 68 65 20 49 4e 44 45 58 45 44 20 42  of the INDEXED B
331f0 59 20 63 6c 61 75 73 65 20 69 73 0a 74 6f 20 72  Y clause is.to r
33200 61 69 73 65 20 61 20 72 75 6e 2d 74 69 6d 65 20  aise a run-time 
33210 65 72 72 6f 72 20 69 66 20 61 20 73 63 68 65 6d  error if a schem
33220 61 20 63 68 61 6e 67 65 2c 20 73 75 63 68 20 61  a change, such a
33230 73 20 64 72 6f 70 70 69 6e 67 20 6f 72 0a 63 72  s dropping or.cr
33240 65 61 74 69 6e 67 20 61 6e 20 69 6e 64 65 78 2c  eating an index,
33250 20 63 61 75 73 65 73 20 74 68 65 20 71 75 65 72   causes the quer
33260 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 74 69 6d  y plan for a tim
33270 65 2d 73 65 6e 73 69 74 69 76 65 20 71 75 65 72  e-sensitive quer
33280 79 0a 74 6f 20 63 68 61 6e 67 65 2e 20 20 54 68  y.to change.  Th
33290 65 20 49 4e 44 45 58 45 44 20 42 59 20 63 6c 61  e INDEXED BY cla
332a0 75 73 65 20 69 73 20 64 65 73 69 67 6e 65 64 20  use is designed 
332b0 74 6f 20 68 65 6c 70 20 64 65 74 65 63 74 0a 75  to help detect.u
332c0 6e 64 65 73 69 72 61 62 6c 65 20 71 75 65 72 79  ndesirable query
332d0 20 70 6c 61 6e 20 63 68 61 6e 67 65 73 20 64 75   plan changes du
332e0 72 69 6e 67 20 72 65 67 72 65 73 73 69 6f 6e 20  ring regression 
332f0 74 65 73 74 69 6e 67 2e 0a 41 70 70 6c 69 63 61  testing..Applica
33300 74 69 6f 6e 20 0a 64 65 76 65 6c 6f 70 65 72 73  tion .developers
33310 20 61 72 65 20 61 64 6d 6f 6e 69 73 68 65 64 20   are admonished 
33320 74 6f 20 6f 6d 69 74 20 61 6c 6c 20 75 73 65 20  to omit all use 
33330 6f 66 20 49 4e 44 45 58 45 44 20 42 59 20 64 75  of INDEXED BY du
33340 72 69 6e 67 0a 61 70 70 6c 69 63 61 74 69 6f 6e  ring.application
33350 20 64 65 73 69 67 6e 2c 20 69 6d 70 6c 65 6d 65   design, impleme
33360 6e 74 61 74 69 6f 6e 2c 20 74 65 73 74 69 6e 67  ntation, testing
33370 2c 20 61 6e 64 20 74 75 6e 69 6e 67 2e 20 20 49  , and tuning.  I
33380 66 0a 49 4e 44 45 58 45 44 20 42 59 20 69 73 20  f.INDEXED BY is 
33390 74 6f 20 62 65 20 75 73 65 64 20 61 74 20 61 6c  to be used at al
333a0 6c 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 20  l, it should be 
333b0 69 6e 73 65 72 74 65 64 20 61 74 20 74 68 65 20  inserted at the 
333c0 76 65 72 79 0a 65 6e 64 20 6f 66 20 74 68 65 20  very.end of the 
333d0 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 63  development proc
333e0 65 73 73 20 77 68 65 6e 20 22 6c 6f 63 6b 69 6e  ess when "lockin
333f0 67 20 64 6f 77 6e 22 20 61 20 64 65 73 69 67 6e  g down" a design
33400 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 53 65 65 20 41  .</p>..<h3>See A
33410 6c 73 6f 3a 3c 2f 68 33 3e 0a 0a 3c 6f 6c 3e 0a  lso:</h3>..<ol>.
33420 3c 6c 69 3e 3c 70 3e 54 68 65 20 5b 71 75 65 72  <li><p>The [quer
33430 79 20 70 6c 61 6e 6e 65 72 20 63 68 65 63 6b 6c  y planner checkl
33440 69 73 74 5d 20 64 65 73 63 72 69 62 65 73 20 73  ist] describes s
33450 74 65 70 73 20 74 68 61 74 20 61 70 70 6c 69 63  teps that applic
33460 61 74 69 6f 6e 0a 64 65 76 65 6c 6f 70 65 72 73  ation.developers
33470 20 73 68 6f 75 6c 64 20 66 6f 6c 6c 6f 77 69 6e   should followin
33480 67 20 74 6f 20 68 65 6c 70 20 72 65 73 6f 6c 76  g to help resolv
33490 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
334a0 70 72 6f 62 6c 65 6d 73 2e 0a 4e 6f 74 69 63 65  problems..Notice
334b0 20 74 68 65 20 74 68 61 74 20 74 68 65 20 75 73   the that the us
334c0 65 20 6f 66 20 49 4e 44 45 58 45 44 20 42 59 20  e of INDEXED BY 
334d0 69 73 20 61 20 6c 61 73 74 20 72 65 73 6f 72 74  is a last resort
334e0 2c 20 74 6f 20 62 65 20 75 73 65 64 20 6f 6e 6c  , to be used onl
334f0 79 0a 77 68 65 6e 20 61 6c 6c 20 6f 74 68 65 72  y.when all other
33500 20 6d 65 61 73 75 72 65 73 20 66 61 69 6c 2e 3c   measures fail.<
33510 2f 70 3e 0a 0a 3c 6c 69 3e 3c 70 3e 5b 75 70 6c  /p>..<li><p>[upl
33520 75 73 63 6f 6e 74 72 6f 6c 7c 54 68 65 20 75 6e  uscontrol|The un
33530 61 72 79 20 22 2b 22 20 6f 70 65 72 61 74 6f 72  ary "+" operator
33540 5d 0a 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ].can be used to
33550 20 64 69 73 71 75 61 6c 69 66 79 20 74 65 72 6d   disqualify term
33560 73 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63  s in the WHERE c
33570 6c 61 75 73 65 20 66 72 6f 6d 20 75 73 65 20 62  lause from use b
33580 79 20 69 6e 64 69 63 65 73 2e 0a 43 61 72 65 66  y indices..Caref
33590 75 6c 20 75 73 65 20 6f 66 20 75 6e 61 72 79 20  ul use of unary 
335a0 2b 20 63 61 6e 20 73 6f 6d 65 74 69 6d 65 73 20  + can sometimes 
335b0 68 65 6c 70 20 70 72 65 76 65 6e 74 20 74 68 65  help prevent the
335c0 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 66   query planner f
335d0 72 6f 6d 0a 63 68 6f 6f 73 69 6e 67 20 61 20 70  rom.choosing a p
335e0 6f 6f 72 20 69 6e 64 65 78 20 77 69 74 68 6f 75  oor index withou
335f0 74 20 72 65 73 74 72 69 63 74 69 6e 67 20 69 74  t restricting it
33600 20 74 6f 20 75 73 69 6e 67 20 6f 6e 65 20 73 70   to using one sp
33610 65 63 69 66 69 63 20 69 6e 64 65 78 2e 0a 43 61  ecific index..Ca
33620 72 65 66 75 6c 20 70 6c 61 63 65 6d 65 6e 74 20  reful placement 
33630 6f 66 20 75 6e 61 72 79 20 2b 20 6f 70 65 72 61  of unary + opera
33640 74 6f 72 73 20 69 73 20 61 20 62 65 74 74 65 72  tors is a better
33650 20 6d 65 74 68 6f 64 20 66 6f 72 20 63 6f 6e 74   method for cont
33660 72 6f 6c 6c 69 6e 67 20 0a 77 68 69 63 68 20 69  rolling .which i
33670 6e 64 69 63 65 73 20 61 72 65 20 75 73 65 64 20  ndices are used 
33680 62 79 20 61 20 71 75 65 72 79 2e 3c 2f 70 3e 0a  by a query.</p>.
33690 0a 3c 6c 69 3e 3c 70 3e 54 68 65 20 5b 73 71 6c  .<li><p>The [sql
336a0 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73  ite3_stmt_status
336b0 28 29 5d 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66  ()] C/C++ interf
336c0 61 63 65 20 74 6f 67 65 74 68 65 72 20 77 69 74  ace together wit
336d0 68 20 74 68 65 0a 5b 53 51 4c 49 54 45 5f 53 54  h the.[SQLITE_ST
336e0 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41  MTSTATUS_FULLSCA
336f0 4e 5f 53 54 45 50 5d 20 61 6e 64 20 5b 53 51 4c  N_STEP] and [SQL
33700 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53  ITE_STMTSTATUS_S
33710 4f 52 54 5d 20 76 65 72 62 73 0a 63 61 6e 20 62  ORT] verbs.can b
33720 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 63 74  e used to detect
33730 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 77 68 65   at run-time whe
33740 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
33750 6e 74 20 69 73 20 6e 6f 74 0a 6d 61 6b 69 6e 67  nt is not.making
33760 20 65 66 66 65 63 74 69 76 65 20 75 73 65 20 6f   effective use o
33770 66 20 69 6e 64 69 63 65 73 2e 20 20 4d 61 6e 79  f indices.  Many
33780 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   applications ma
33790 79 20 70 72 65 66 65 72 20 74 6f 0a 75 73 65 20  y prefer to.use 
337a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
337b0 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65  t_status()] inte
337c0 72 66 61 63 65 20 74 6f 20 64 65 74 65 63 74 20  rface to detect 
337d0 69 6e 64 65 78 20 6d 69 73 75 73 65 0a 72 61 74  index misuse.rat
337e0 68 65 72 20 74 68 61 6e 20 74 68 65 20 49 4e 44  her than the IND
337f0 45 58 45 44 20 42 59 20 70 68 72 61 73 65 20 64  EXED BY phrase d
33800 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 3c 2f  escribed here.</
33810 70 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 74 63 6c 3e 0a  p>.</ol>..<tcl>.
33820 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33830 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33840 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33850 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
33860 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 23 20  #############.# 
33870 41 20 6c 69 73 74 20 6f 66 20 6b 65 79 77 6f 72  A list of keywor
33880 64 73 2e 20 20 41 20 61 73 74 65 72 69 73 6b 20  ds.  A asterisk 
33890 6f 63 63 75 72 73 20 61 66 74 65 72 20 74 68 65  occurs after the
338a0 20 6b 65 79 77 6f 72 64 20 69 66 20 69 74 20 69   keyword if it i
338b0 73 20 6f 6e 0a 23 20 74 68 65 20 66 61 6c 6c 62  s on.# the fallb
338c0 61 63 6b 20 6c 69 73 74 2e 0a 23 0a 73 65 74 20  ack list..#.set 
338d0 6b 65 79 77 6f 72 64 5f 6c 69 73 74 20 5b 6c 73  keyword_list [ls
338e0 6f 72 74 20 7b 0a 20 20 20 41 42 4f 52 54 0a 20  ort {.   ABORT. 
338f0 20 20 41 43 54 49 4f 4e 0a 20 20 20 41 44 44 0a    ACTION.   ADD.
33900 20 20 20 41 46 54 45 52 0a 20 20 20 41 4c 4c 0a     AFTER.   ALL.
33910 20 20 20 41 4c 54 45 52 0a 20 20 20 41 4e 41 4c     ALTER.   ANAL
33920 59 5a 45 0a 20 20 20 41 4e 44 0a 20 20 20 41 53  YZE.   AND.   AS
33930 0a 20 20 20 41 53 43 0a 20 20 20 41 54 54 41 43  .   ASC.   ATTAC
33940 48 0a 20 20 20 41 55 54 4f 49 4e 43 52 45 4d 45  H.   AUTOINCREME
33950 4e 54 0a 20 20 20 42 45 46 4f 52 45 0a 20 20 20  NT.   BEFORE.   
33960 42 45 47 49 4e 0a 20 20 20 42 45 54 57 45 45 4e  BEGIN.   BETWEEN
33970 0a 20 20 20 42 59 0a 20 20 20 43 41 53 43 41 44  .   BY.   CASCAD
33980 45 0a 20 20 20 43 41 53 45 0a 20 20 20 43 41 53  E.   CASE.   CAS
33990 54 0a 20 20 20 43 48 45 43 4b 0a 20 20 20 43 4f  T.   CHECK.   CO
339a0 4c 4c 41 54 45 0a 20 20 20 43 4f 4c 55 4d 4e 0a  LLATE.   COLUMN.
339b0 20 20 20 43 4f 4d 4d 49 54 0a 20 20 20 43 4f 4e     COMMIT.   CON
339c0 46 4c 49 43 54 0a 20 20 20 43 4f 4e 53 54 52 41  FLICT.   CONSTRA
339d0 49 4e 54 0a 20 20 20 43 52 45 41 54 45 0a 20 20  INT.   CREATE.  
339e0 20 43 52 4f 53 53 0a 20 20 20 43 55 52 52 45 4e   CROSS.   CURREN
339f0 54 5f 44 41 54 45 0a 20 20 20 43 55 52 52 45 4e  T_DATE.   CURREN
33a00 54 5f 54 49 4d 45 0a 20 20 20 43 55 52 52 45 4e  T_TIME.   CURREN
33a10 54 5f 54 49 4d 45 53 54 41 4d 50 0a 20 20 20 44  T_TIMESTAMP.   D
33a20 41 54 41 42 41 53 45 0a 20 20 20 44 45 46 41 55  ATABASE.   DEFAU
33a30 4c 54 0a 20 20 20 44 45 46 45 52 52 45 44 0a 20  LT.   DEFERRED. 
33a40 20 20 44 45 46 45 52 52 41 42 4c 45 0a 20 20 20    DEFERRABLE.   
33a50 44 45 4c 45 54 45 0a 20 20 20 44 45 53 43 0a 20  DELETE.   DESC. 
33a60 20 20 44 45 54 41 43 48 0a 20 20 20 44 49 53 54    DETACH.   DIST
33a70 49 4e 43 54 0a 20 20 20 44 52 4f 50 0a 20 20 20  INCT.   DROP.   
33a80 45 4e 44 0a 20 20 20 45 41 43 48 0a 20 20 20 45  END.   EACH.   E
33a90 4c 53 45 0a 20 20 20 45 53 43 41 50 45 0a 20 20  LSE.   ESCAPE.  
33aa0 20 45 58 43 45 50 54 0a 20 20 20 45 58 43 4c 55   EXCEPT.   EXCLU
33ab0 53 49 56 45 0a 20 20 20 45 58 49 53 54 53 0a 20  SIVE.   EXISTS. 
33ac0 20 20 45 58 50 4c 41 49 4e 0a 20 20 20 46 41 49    EXPLAIN.   FAI
33ad0 4c 0a 20 20 20 46 4f 52 0a 20 20 20 46 4f 52 45  L.   FOR.   FORE
33ae0 49 47 4e 0a 20 20 20 46 52 4f 4d 0a 20 20 20 46  IGN.   FROM.   F
33af0 55 4c 4c 0a 20 20 20 47 4c 4f 42 0a 20 20 20 47  ULL.   GLOB.   G
33b00 52 4f 55 50 0a 20 20 20 48 41 56 49 4e 47 0a 20  ROUP.   HAVING. 
33b10 20 20 49 46 0a 20 20 20 49 47 4e 4f 52 45 0a 20    IF.   IGNORE. 
33b20 20 20 49 4d 4d 45 44 49 41 54 45 0a 20 20 20 49    IMMEDIATE.   I
33b30 4e 0a 20 20 20 49 4e 44 45 58 0a 20 20 20 49 4e  N.   INDEX.   IN
33b40 44 45 58 45 44 0a 20 20 20 49 4e 49 54 49 41 4c  DEXED.   INITIAL
33b50 4c 59 0a 20 20 20 49 4e 4e 45 52 0a 20 20 20 49  LY.   INNER.   I
33b60 4e 53 45 52 54 0a 20 20 20 49 4e 53 54 45 41 44  NSERT.   INSTEAD
33b70 0a 20 20 20 49 4e 54 45 52 53 45 43 54 0a 20 20  .   INTERSECT.  
33b80 20 49 4e 54 4f 0a 20 20 20 49 53 0a 20 20 20 49   INTO.   IS.   I
33b90 53 4e 55 4c 4c 0a 20 20 20 4a 4f 49 4e 0a 20 20  SNULL.   JOIN.  
33ba0 20 4b 45 59 0a 20 20 20 4c 45 46 54 0a 20 20 20   KEY.   LEFT.   
33bb0 4c 49 4b 45 0a 20 20 20 4c 49 4d 49 54 0a 20 20  LIKE.   LIMIT.  
33bc0 20 4d 41 54 43 48 0a 20 20 20 4e 41 54 55 52 41   MATCH.   NATURA
33bd0 4c 0a 20 20 20 4e 4f 0a 20 20 20 4e 4f 54 0a 20  L.   NO.   NOT. 
33be0 20 20 4e 4f 54 4e 55 4c 4c 0a 20 20 20 4e 55 4c    NOTNULL.   NUL
33bf0 4c 0a 20 20 20 4f 46 0a 20 20 20 4f 46 46 53 45  L.   OF.   OFFSE
33c00 54 0a 20 20 20 4f 4e 0a 20 20 20 4f 52 0a 20 20  T.   ON.   OR.  
33c10 20 4f 52 44 45 52 0a 20 20 20 4f 55 54 45 52 0a   ORDER.   OUTER.
33c20 20 20 20 50 4c 41 4e 0a 20 20 20 50 52 41 47 4d     PLAN.   PRAGM
33c30 41 0a 20 20 20 50 52 49 4d 41 52 59 0a 20 20 20  A.   PRIMARY.   
33c40 51 55 45 52 59 0a 20 20 20 52 41 49 53 45 0a 20  QUERY.   RAISE. 
33c50 20 20 52 45 43 55 52 53 49 56 45 0a 20 20 20 52    RECURSIVE.   R
33c60 45 46 45 52 45 4e 43 45 53 0a 20 20 20 52 45 47  EFERENCES.   REG
33c70 45 58 50 0a 20 20 20 52 45 49 4e 44 45 58 0a 20  EXP.   REINDEX. 
33c80 20 20 52 45 4c 45 41 53 45 0a 20 20 20 52 45 4e    RELEASE.   REN
33c90 41 4d 45 0a 20 20 20 52 45 50 4c 41 43 45 0a 20  AME.   REPLACE. 
33ca0 20 20 52 45 53 54 52 49 43 54 0a 20 20 20 52 49    RESTRICT.   RI
33cb0 47 48 54 0a 20 20 20 52 4f 4c 4c 42 41 43 4b 0a  GHT.   ROLLBACK.
33cc0 20 20 20 52 4f 57 0a 20 20 20 53 41 56 45 50 4f     ROW.   SAVEPO
33cd0 49 4e 54 0a 20 20 20 53 45 4c 45 43 54 0a 20 20  INT.   SELECT.  
33ce0 20 53 45 54 0a 20 20 20 54 41 42 4c 45 0a 20 20   SET.   TABLE.  
33cf0 20 54 45 4d 50 0a 20 20 20 54 45 4d 50 4f 52 41   TEMP.   TEMPORA
33d00 52 59 0a 20 20 20 54 48 45 4e 0a 20 20 20 54 4f  RY.   THEN.   TO
33d10 0a 20 20 20 54 52 41 4e 53 41 43 54 49 4f 4e 0a  .   TRANSACTION.
33d20 20 20 20 54 52 49 47 47 45 52 0a 20 20 20 55 4e     TRIGGER.   UN
33d30 49 4f 4e 0a 20 20 20 55 4e 49 51 55 45 0a 20 20  ION.   UNIQUE.  
33d40 20 55 50 44 41 54 45 0a 20 20 20 55 53 49 4e 47   UPDATE.   USING
33d50 0a 20 20 20 56 41 43 55 55 4d 0a 20 20 20 56 41  .   VACUUM.   VA
33d60 4c 55 45 53 0a 20 20 20 56 49 45 57 0a 20 20 20  LUES.   VIEW.   
33d70 56 49 52 54 55 41 4c 0a 20 20 20 57 49 54 48 0a  VIRTUAL.   WITH.
33d80 20 20 20 57 49 54 48 4f 55 54 0a 20 20 20 57 48     WITHOUT.   WH
33d90 45 4e 0a 20 20 20 57 48 45 52 45 0a 7d 5d 0a 0a  EN.   WHERE.}]..
33da0 68 64 5f 70 75 74 73 20 7b 3c 44 49 56 20 63 6c  hd_puts {<DIV cl
33db0 61 73 73 3d 22 70 64 66 5f 73 65 63 74 69 6f 6e  ass="pdf_section
33dc0 22 3e 7d 0a 53 65 63 74 69 6f 6e 20 7b 53 51 4c  ">}.Section {SQL
33dd0 69 74 65 20 4b 65 79 77 6f 72 64 73 7d 20 6b 65  ite Keywords} ke
33de0 79 77 6f 72 64 73 20 7b 7b 2a 53 51 4c 20 6b 65  ywords {{*SQL ke
33df0 79 77 6f 72 64 7d 20 7b 53 51 4c 20 6b 65 79 77  yword} {SQL keyw
33e00 6f 72 64 73 7d 7d 0a 68 64 5f 70 75 74 73 20 7b  ords}}.hd_puts {
33e10 3c 2f 44 49 56 3e 7d 0a 3c 2f 74 63 6c 3e 0a 0a  </DIV>}.</tcl>..
33e20 3c 70 3e 54 68 65 20 53 51 4c 20 73 74 61 6e 64  <p>The SQL stand
33e30 61 72 64 20 73 70 65 63 69 66 69 65 73 20 61 20  ard specifies a 
33e40 68 75 67 65 20 6e 75 6d 62 65 72 20 6f 66 20 6b  huge number of k
33e50 65 79 77 6f 72 64 73 20 77 68 69 63 68 20 6d 61  eywords which ma
33e60 79 20 6e 6f 74 0a 62 65 20 75 73 65 64 20 61 73  y not.be used as
33e70 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 61   the names of ta
33e80 62 6c 65 73 2c 20 69 6e 64 69 63 65 73 2c 20 63  bles, indices, c
33e90 6f 6c 75 6d 6e 73 2c 20 64 61 74 61 62 61 73 65  olumns, database
33ea0 73 2c 20 75 73 65 72 2d 64 65 66 69 6e 65 64 0a  s, user-defined.
33eb0 66 75 6e 63 74 69 6f 6e 73 2c 20 63 6f 6c 6c 61  functions, colla
33ec0 74 69 6f 6e 73 2c 20 76 69 72 74 75 61 6c 20 74  tions, virtual t
33ed0 61 62 6c 65 20 6d 6f 64 75 6c 65 73 2c 20 6f 72  able modules, or
33ee0 20 61 6e 79 20 6f 74 68 65 72 20 6e 61 6d 65 64   any other named
33ef0 20 6f 62 6a 65 63 74 2e 0a 54 68 65 20 6c 69 73   object..The lis
33f00 74 20 6f 66 20 6b 65 79 77 6f 72 64 73 20 69 73  t of keywords is
33f10 20 73 6f 20 6c 6f 6e 67 20 74 68 61 74 20 66 65   so long that fe
33f20 77 20 70 65 6f 70 6c 65 20 63 61 6e 20 72 65 6d  w people can rem
33f30 65 6d 62 65 72 20 74 68 65 6d 20 61 6c 6c 2e 0a  ember them all..
33f40 46 6f 72 20 6d 6f 73 74 20 53 51 4c 20 63 6f 64  For most SQL cod
33f50 65 2c 20 79 6f 75 72 20 73 61 66 65 73 74 20 62  e, your safest b
33f60 65 74 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75  et is to never u
33f70 73 65 20 61 6e 79 20 45 6e 67 6c 69 73 68 20 6c  se any English l
33f80 61 6e 67 75 61 67 65 0a 77 6f 72 64 20 61 73 20  anguage.word as 
33f90 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 75 73  the name of a us
33fa0 65 72 2d 64 65 66 69 6e 65 64 20 6f 62 6a 65 63  er-defined objec
33fb0 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 79 6f  t.</p>..<p>If yo
33fc0 75 20 77 61 6e 74 20 74 6f 20 75 73 65 20 61 20  u want to use a 
33fd0 6b 65 79 77 6f 72 64 20 61 73 20 61 20 6e 61 6d  keyword as a nam
33fe0 65 2c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 71  e, you need to q
33ff0 75 6f 74 65 20 69 74 2e 20 20 54 68 65 72 65 0a  uote it.  There.
34000 61 72 65 20 66 6f 75 72 20 77 61 79 73 20 6f 66  are four ways of
34010 20 71 75 6f 74 69 6e 67 20 6b 65 79 77 6f 72 64   quoting keyword
34020 73 20 69 6e 20 53 51 4c 69 74 65 3a 3c 2f 70 3e  s in SQLite:</p>
34030 0a 0a 3c 70 3e 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ..<p>.<blockquot
34040 65 3e 0a 3c 74 61 62 6c 65 3e 0a 3c 74 72 3e 09  e>.<table>.<tr>.
34050 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22  <td valign="top"
34060 3e 3c 62 3e 27 6b 65 79 77 6f 72 64 27 3c 2f 62  ><b>'keyword'</b
34070 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74 68 3d  ></td><td width=
34080 22 32 30 22 3e 3c 2f 74 64 3e 0a 09 3c 74 64 3e  "20"></td>..<td>
34090 5e 41 20 6b 65 79 77 6f 72 64 20 69 6e 20 73 69  ^A keyword in si
340a0 6e 67 6c 65 20 71 75 6f 74 65 73 20 69 73 20 61  ngle quotes is a
340b0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
340c0 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e  </td></tr>..<tr>
340d0 09 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70  .<td valign="top
340e0 22 3e 3c 62 3e 22 6b 65 79 77 6f 72 64 22 3c 2f  "><b>"keyword"</
340f0 62 3e 3c 2f 74 64 3e 3c 74 64 3e 3c 2f 74 64 3e  b></td><td></td>
34100 0a 09 3c 74 64 3e 5e 41 20 6b 65 79 77 6f 72 64  ..<td>^A keyword
34110 20 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65   in double-quote
34120 73 20 69 73 20 61 6e 20 69 64 65 6e 74 69 66 69  s is an identifi
34130 65 72 2e 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 0a 3c  er.</td></tr>..<
34140 74 72 3e 09 3c 74 64 20 76 61 6c 69 67 6e 3d 22  tr>.<td valign="
34150 74 6f 70 22 3e 3c 62 3e 26 23 39 31 3b 6b 65 79  top"><b>&#91;key
34160 77 6f 72 64 26 23 39 33 3b 3c 2f 62 3e 3c 2f 74  word&#93;</b></t
34170 64 3e 3c 74 64 3e 3c 2f 74 64 3e 0a 09 3c 74 64  d><td></td>..<td
34180 3e 5e 41 20 6b 65 79 77 6f 72 64 20 65 6e 63 6c  >^A keyword encl
34190 6f 73 65 64 20 69 6e 20 73 71 75 61 72 65 20 62  osed in square b
341a0 72 61 63 6b 65 74 73 20 69 73 20 0a 20 20 20 20  rackets is .    
341b0 20 20 20 20 61 6e 20 69 64 65 6e 74 69 66 69 65      an identifie
341c0 72 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  r.  This is not 
341d0 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 20 20 54  standard SQL.  T
341e0 68 69 73 20 71 75 6f 74 69 6e 67 20 6d 65 63 68  his quoting mech
341f0 61 6e 69 73 6d 0a 20 20 20 20 20 20 20 20 69 73  anism.        is
34200 20 75 73 65 64 20 62 79 20 4d 53 20 41 63 63 65   used by MS Acce
34210 73 73 20 61 6e 64 20 53 51 4c 20 53 65 72 76 65  ss and SQL Serve
34220 72 20 61 6e 64 20 69 73 20 69 6e 63 6c 75 64 65  r and is include
34230 64 20 69 6e 20 53 51 4c 69 74 65 20 66 6f 72 0a  d in SQLite for.
34240 20 20 20 20 20 20 20 20 63 6f 6d 70 61 74 69 62          compatib
34250 69 6c 69 74 79 2e 3c 2f 74 64 3e 3c 2f 74 72 3e  ility.</td></tr>
34260 0a 0a 3c 74 72 3e 09 3c 74 64 20 76 61 6c 69 67  ..<tr>.<td valig
34270 6e 3d 22 74 6f 70 22 3e 3c 62 3e 26 23 39 36 3b  n="top"><b>&#96;
34280 6b 65 79 77 6f 72 64 26 23 39 36 3b 3c 2f 62 3e  keyword&#96;</b>
34290 3c 2f 74 64 3e 3c 74 64 3e 3c 2f 74 64 3e 0a 09  </td><td></td>..
342a0 3c 74 64 3e 5e 41 20 6b 65 79 77 6f 72 64 20 65  <td>^A keyword e
342b0 6e 63 6c 6f 73 65 64 20 69 6e 20 67 72 61 76 65  nclosed in grave
342c0 20 61 63 63 65 6e 74 73 20 28 41 53 43 49 49 20   accents (ASCII 
342d0 63 6f 64 65 20 39 36 29 20 69 73 20 0a 20 20 20  code 96) is .   
342e0 20 20 20 20 20 61 6e 20 69 64 65 6e 74 69 66 69       an identifi
342f0 65 72 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  er.  This is not
34300 20 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 20 20   standard SQL.  
34310 54 68 69 73 20 71 75 6f 74 69 6e 67 20 6d 65 63  This quoting mec
34320 68 61 6e 69 73 6d 0a 20 20 20 20 20 20 20 20 69  hanism.        i
34330 73 20 75 73 65 64 20 62 79 20 4d 79 53 51 4c 20  s used by MySQL 
34340 61 6e 64 20 69 73 20 69 6e 63 6c 75 64 65 64 20  and is included 
34350 69 6e 20 53 51 4c 69 74 65 20 66 6f 72 0a 20 20  in SQLite for.  
34360 20 20 20 20 20 20 63 6f 6d 70 61 74 69 62 69 6c        compatibil
34370 69 74 79 2e 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c  ity.</td></tr>.<
34380 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71  /table>.</blockq
34390 75 6f 74 65 3e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 46  uote>.</p>..<p>F
343a0 6f 72 20 72 65 73 69 6c 69 65 6e 63 65 20 77 68  or resilience wh
343b0 65 6e 20 63 6f 6e 66 72 6f 6e 74 65 64 20 77 69  en confronted wi
343c0 74 68 20 68 69 73 74 6f 72 69 63 61 6c 20 53 51  th historical SQ
343d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 53 51  L statements, SQ
343e0 4c 69 74 65 0a 77 69 6c 6c 20 73 6f 6d 65 74 69  Lite.will someti
343f0 6d 65 73 20 62 65 6e 64 20 74 68 65 20 71 75 6f  mes bend the quo
34400 74 69 6e 67 20 72 75 6c 65 73 20 61 62 6f 76 65  ting rules above
34410 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  :</p>..<ul>.<li>
34420 3c 70 3e 5e 49 66 20 61 20 6b 65 79 77 6f 72 64  <p>^If a keyword
34430 20 69 6e 20 73 69 6e 67 6c 65 0a 71 75 6f 74 65   in single.quote
34440 73 20 28 65 78 3a 20 3c 62 3e 27 6b 65 79 27 3c  s (ex: <b>'key'<
34450 2f 62 3e 20 6f 72 20 3c 62 3e 27 67 6c 6f 62 27  /b> or <b>'glob'
34460 3c 2f 62 3e 29 20 69 73 20 75 73 65 64 20 69 6e  </b>) is used in
34470 20 61 20 63 6f 6e 74 65 78 74 20 77 68 65 72 65   a context where
34480 0a 61 6e 20 69 64 65 6e 74 69 66 69 65 72 20 69  .an identifier i
34490 73 20 61 6c 6c 6f 77 65 64 20 62 75 74 20 77 68  s allowed but wh
344a0 65 72 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ere a string lit
344b0 65 72 61 6c 20 69 73 20 6e 6f 74 20 61 6c 6c 6f  eral is not allo
344c0 77 65 64 2c 20 74 68 65 6e 0a 74 68 65 20 74 6f  wed, then.the to
344d0 6b 65 6e 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  ken is understoo
344e0 64 20 74 6f 20 62 65 20 61 6e 20 69 64 65 6e 74  d to be an ident
344f0 69 66 69 65 72 20 69 6e 73 74 65 61 64 20 6f 66  ifier instead of
34500 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
34510 6c 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c  l..</p></li>..<l
34520 69 3e 3c 70 3e 5e 49 66 20 61 20 6b 65 79 77 6f  i><p>^If a keywo
34530 72 64 20 69 6e 20 64 6f 75 62 6c 65 0a 71 75 6f  rd in double.quo
34540 74 65 73 20 28 65 78 3a 20 3c 62 3e 22 6b 65 79  tes (ex: <b>"key
34550 22 3c 2f 62 3e 20 6f 72 20 3c 62 3e 22 67 6c 6f  "</b> or <b>"glo
34560 62 22 3c 2f 62 3e 29 20 69 73 20 75 73 65 64 20  b"</b>) is used 
34570 69 6e 20 61 20 63 6f 6e 74 65 78 74 20 77 68 65  in a context whe
34580 72 65 0a 69 74 20 63 61 6e 6e 6f 74 20 62 65 20  re.it cannot be 
34590 72 65 73 6f 6c 76 65 64 20 74 6f 20 61 6e 20 69  resolved to an i
345a0 64 65 6e 74 69 66 69 65 72 20 62 75 74 20 77 68  dentifier but wh
345b0 65 72 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ere a string lit
345c0 65 72 61 6c 0a 69 73 20 61 6c 6c 6f 77 65 64 2c  eral.is allowed,
345d0 20 74 68 65 6e 20 74 68 65 20 74 6f 6b 65 6e 20   then the token 
345e0 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 74 6f  is understood to
345f0 20 62 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74   be a string lit
34600 65 72 61 6c 20 69 6e 73 74 65 61 64 0a 6f 66 20  eral instead.of 
34610 61 6e 20 69 64 65 6e 74 69 66 69 65 72 2e 3c 2f  an identifier.</
34620 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c  p></li>.</ul>..<
34630 70 3e 50 72 6f 67 72 61 6d 6d 65 72 73 20 61 72  p>Programmers ar
34640 65 20 63 61 75 74 69 6f 6e 65 64 20 6e 6f 74 20  e cautioned not 
34650 74 6f 20 75 73 65 20 74 68 65 20 74 77 6f 20 65  to use the two e
34660 78 63 65 70 74 69 6f 6e 73 20 64 65 73 63 72 69  xceptions descri
34670 62 65 64 20 69 6e 0a 74 68 65 20 70 72 65 76 69  bed in.the previ
34680 6f 75 73 20 62 75 6c 6c 65 74 73 2e 20 20 57 65  ous bullets.  We
34690 20 65 6d 70 68 61 73 69 7a 65 20 74 68 61 74 20   emphasize that 
346a0 74 68 65 79 20 65 78 69 73 74 20 6f 6e 6c 79 20  they exist only 
346b0 73 6f 20 74 68 61 74 20 6f 6c 64 0a 61 6e 64 20  so that old.and 
346c0 69 6c 6c 2d 66 6f 72 6d 65 64 20 53 51 4c 20 73  ill-formed SQL s
346d0 74 61 74 65 6d 65 6e 74 73 20 77 69 6c 6c 20 72  tatements will r
346e0 75 6e 20 63 6f 72 72 65 63 74 6c 79 2e 20 20 46  un correctly.  F
346f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
34700 66 0a 53 51 4c 69 74 65 20 6d 69 67 68 74 20 72  f.SQLite might r
34710 61 69 73 65 20 65 72 72 6f 72 73 20 69 6e 73 74  aise errors inst
34720 65 61 64 20 6f 66 20 61 63 63 65 70 74 69 6e 67  ead of accepting
34730 20 74 68 65 20 6d 61 6c 66 6f 72 6d 65 64 0a 73   the malformed.s
34740 74 61 74 65 6d 65 6e 74 73 20 63 6f 76 65 72 65  tatements covere
34750 64 20 62 79 20 74 68 65 20 65 78 63 65 70 74 69  d by the excepti
34760 6f 6e 73 20 61 62 6f 76 65 2e 3c 2f 70 3e 0a 0a  ons above.</p>..
34770 3c 70 3e 0a 53 51 4c 69 74 65 20 61 64 64 73 20  <p>.SQLite adds 
34780 6e 65 77 20 6b 65 79 77 6f 72 64 73 20 66 72 6f  new keywords fro
34790 6d 20 74 69 6d 65 20 74 6f 20 74 69 6d 65 20 77  m time to time w
347a0 68 65 6e 20 69 74 20 74 61 6b 65 73 20 6f 6e 20  hen it takes on 
347b0 6e 65 77 20 66 65 61 74 75 72 65 73 2e 0a 53 6f  new features..So
347c0 20 74 6f 20 70 72 65 76 65 6e 74 20 79 6f 75 72   to prevent your
347d0 20 63 6f 64 65 20 66 72 6f 6d 20 62 65 69 6e 67   code from being
347e0 20 62 72 6f 6b 65 6e 20 62 79 20 66 75 74 75 72   broken by futur
347f0 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 2c 20  e enhancements, 
34800 79 6f 75 20 73 68 6f 75 6c 64 0a 6e 6f 72 6d 61  you should.norma
34810 6c 6c 79 20 71 75 6f 74 65 20 61 6e 79 20 69 64  lly quote any id
34820 65 6e 74 69 66 69 65 72 20 74 68 61 74 20 69 73  entifier that is
34830 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
34840 75 61 67 65 20 77 6f 72 64 2c 20 65 76 65 6e 20  uage word, even 
34850 69 66 0a 79 6f 75 20 64 6f 20 6e 6f 74 20 68 61  if.you do not ha
34860 76 65 20 74 6f 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  ve to..</p>..<p>
34870 0a 54 68 65 20 6c 69 73 74 20 62 65 6c 6f 77 20  .The list below 
34880 73 68 6f 77 73 20 61 6c 6c 20 70 6f 73 73 69 62  shows all possib
34890 6c 65 20 6b 65 79 77 6f 72 64 73 20 75 73 65 64  le keywords used
348a0 20 62 79 20 61 6e 79 20 62 75 69 6c 64 20 6f 66   by any build of
348b0 0a 53 51 4c 69 74 65 20 72 65 67 61 72 64 6c 65  .SQLite regardle
348c0 73 73 20 6f 66 20 5b 63 6f 6d 70 69 6c 65 2d 74  ss of [compile-t
348d0 69 6d 65 20 6f 70 74 69 6f 6e 73 5d 2e 20 20 0a  ime options].  .
348e0 4d 6f 73 74 20 72 65 61 73 6f 6e 61 62 6c 65 20  Most reasonable 
348f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 73 20 75  configurations u
34900 73 65 20 6d 6f 73 74 20 6f 72 20 61 6c 6c 20 6f  se most or all o
34910 66 20 74 68 65 73 65 20 6b 65 79 77 6f 72 64 73  f these keywords
34920 2c 0a 62 75 74 20 73 6f 6d 65 20 6b 65 79 77 6f  ,.but some keywo
34930 72 64 73 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  rds may be omitt
34940 65 64 20 77 68 65 6e 20 53 51 4c 20 6c 61 6e 67  ed when SQL lang
34950 75 61 67 65 20 66 65 61 74 75 72 65 73 20 61 72  uage features ar
34960 65 0a 64 69 73 61 62 6c 65 64 2e 0a 5e 28 52 65  e.disabled..^(Re
34970 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
34980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
34990 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 79 20  figuration, any 
349a0 69 64 65 6e 74 69 66 69 65 72 20 74 68 61 74 20  identifier that 
349b0 69 73 20 6e 6f 74 20 6f 6e 0a 74 68 65 20 66 6f  is not on.the fo
349c0 6c 6c 6f 77 69 6e 67 20 3c 74 63 6c 3e 68 64 5f  llowing <tcl>hd_
349d0 70 75 74 73 20 5b 6c 6c 65 6e 67 74 68 20 24 6b  puts [llength $k
349e0 65 79 77 6f 72 64 5f 6c 69 73 74 5d 3c 2f 74 63  eyword_list]</tc
349f0 6c 3e 20 65 6c 65 6d 65 6e 74 0a 6c 69 73 74 20  l> element.list 
34a00 69 73 20 6e 6f 74 20 61 20 6b 65 79 77 6f 72 64  is not a keyword
34a10 20 74 6f 20 74 68 65 20 53 51 4c 20 70 61 72 73   to the SQL pars
34a20 65 72 20 69 6e 20 53 51 4c 69 74 65 3a 0a 3c 2f  er in SQLite:.</
34a30 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 74 63 6c 3e 0a 73  p>..<ol>.<tcl>.s
34a40 65 74 20 6c 78 20 7b 7d 0a 66 6f 72 65 61 63 68  et lx {}.foreach
34a50 20 77 6f 72 64 20 5b 6c 73 6f 72 74 20 24 6b 65   word [lsort $ke
34a60 79 77 6f 72 64 5f 6c 69 73 74 5d 20 7b 0a 20 20  yword_list] {.  
34a70 68 64 5f 70 75 74 73 6e 6c 20 22 3c 6c 69 3e 24  hd_putsnl "<li>$
34a80 77 6f 72 64 3c 2f 6c 69 3e 22 0a 7d 0a 68 64 5f  word</li>".}.hd_
34a90 70 75 74 73 6e 6c 20 22 3c 2f 6f 6c 3e 29 5e 22  putsnl "</ol>)^"
34aa0 0a 3c 2f 74 63 6c 3e 0a                          .</tcl>.