Documentation Source Text

Hex Artifact Content
Login

Artifact 34cd4dd9301d937b3c60b05a434c1e8328cbcf72f05a3df55bf64561e8009118:


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 55 50 53 45 52 54 20 75 70 73 65 72     {UPSERT upser
0380: 74 7d 0a 20 20 20 20 7b 52 45 50 4c 41 43 45 20  t}.    {REPLACE 
0390: 72 65 70 6c 61 63 65 7d 0a 20 20 20 20 7b 44 45  replace}.    {DE
03a0: 4c 45 54 45 20 64 65 6c 65 74 65 7d 0a 20 20 20  LETE delete}.   
03b0: 20 7b 55 50 44 41 54 45 20 75 70 64 61 74 65 7d   {UPDATE update}
03c0: 0a 20 20 20 20 7b 53 45 4c 45 43 54 20 73 65 6c  .    {SELECT sel
03d0: 65 63 74 7d 0a 20 20 20 20 7b 7b 57 49 54 48 20  ect}.    {{WITH 
03e0: 63 6c 61 75 73 65 7d 20 77 69 74 68 63 6c 61 75  clause} withclau
03f0: 73 65 7d 0a 20 20 20 20 7b 63 6f 6d 6d 65 6e 74  se}.    {comment
0400: 20 63 6f 6d 6d 65 6e 74 7d 0a 20 20 20 20 7b 45   comment}.    {E
0410: 58 50 4c 41 49 4e 20 65 78 70 6c 61 69 6e 7d 0a  XPLAIN explain}.
0420: 20 20 20 20 7b 65 78 70 72 65 73 73 69 6f 6e 20      {expression 
0430: 65 78 70 72 7d 0a 20 20 20 20 7b 7b 42 45 47 49  expr}.    {{BEGI
0440: 4e 20 54 52 41 4e 53 41 43 54 49 4f 4e 7d 20 74  N TRANSACTION} t
0450: 72 61 6e 73 61 63 74 69 6f 6e 7d 0a 20 20 20 20  ransaction}.    
0460: 7b 7b 43 4f 4d 4d 49 54 20 54 52 41 4e 53 41 43  {{COMMIT TRANSAC
0470: 54 49 4f 4e 7d 20 74 72 61 6e 73 61 63 74 69 6f  TION} transactio
0480: 6e 20 43 4f 4d 4d 49 54 7d 0a 20 20 20 20 7b 7b  n COMMIT}.    {{
0490: 45 4e 44 20 54 52 41 4e 53 41 43 54 49 4f 4e 7d  END TRANSACTION}
04a0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 43 4f 4d   transaction COM
04b0: 4d 49 54 7d 0a 20 20 20 20 7b 7b 52 4f 4c 4c 42  MIT}.    {{ROLLB
04c0: 41 43 4b 20 54 52 41 4e 53 41 43 54 49 4f 4e 7d  ACK TRANSACTION}
04d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 52 4f 4c   transaction ROL
04e0: 4c 42 41 43 4b 7d 0a 20 20 20 20 7b 53 41 56 45  LBACK}.    {SAVE
04f0: 50 4f 49 4e 54 20 73 61 76 65 70 6f 69 6e 74 7d  POINT savepoint}
0500: 0a 20 20 20 20 7b 7b 52 45 4c 45 41 53 45 20 53  .    {{RELEASE S
0510: 41 56 45 50 4f 49 4e 54 7d 20 73 61 76 65 70 6f  AVEPOINT} savepo
0520: 69 6e 74 20 53 41 56 45 50 4f 49 4e 54 7d 0a 20  int SAVEPOINT}. 
0530: 20 20 20 7b 50 52 41 47 4d 41 20 70 72 61 67 6d     {PRAGMA pragm
0540: 61 2e 68 74 6d 6c 7d 0a 20 20 20 20 7b 7b 4f 4e  a.html}.    {{ON
0550: 20 43 4f 4e 46 4c 49 43 54 20 63 6c 61 75 73 65   CONFLICT clause
0560: 7d 20 63 6f 6e 66 6c 69 63 74 7d 0a 20 20 20 20  } conflict}.    
0570: 7b 7b 43 52 45 41 54 45 20 56 49 45 57 7d 20 63  {{CREATE VIEW} c
0580: 72 65 61 74 65 76 69 65 77 7d 0a 20 20 20 20 7b  reateview}.    {
0590: 7b 44 52 4f 50 20 56 49 45 57 7d 20 64 72 6f 70  {DROP VIEW} drop
05a0: 76 69 65 77 7d 0a 20 20 20 20 7b 7b 43 52 45 41  view}.    {{CREA
05b0: 54 45 20 54 52 49 47 47 45 52 7d 20 63 72 65 61  TE TRIGGER} crea
05c0: 74 65 74 72 69 67 67 65 72 7d 0a 20 20 20 20 7b  tetrigger}.    {
05d0: 7b 44 52 4f 50 20 54 52 49 47 47 45 52 7d 20 64  {DROP TRIGGER} d
05e0: 72 6f 70 74 72 69 67 67 65 72 7d 0a 20 20 20 20  roptrigger}.    
05f0: 7b 7b 41 54 54 41 43 48 20 44 41 54 41 42 41 53  {{ATTACH DATABAS
0600: 45 7d 20 61 74 74 61 63 68 7d 0a 20 20 20 20 7b  E} attach}.    {
0610: 7b 44 45 54 41 43 48 20 44 41 54 41 42 41 53 45  {DETACH DATABASE
0620: 7d 20 64 65 74 61 63 68 7d 0a 20 20 20 20 20 20  } detach}.      
0630: 7b 52 45 49 4e 44 45 58 20 72 65 69 6e 64 65 78  {REINDEX reindex
0640: 7d 0a 20 20 20 20 7b 7b 41 4c 54 45 52 20 54 41  }.    {{ALTER TA
0650: 42 4c 45 7d 20 61 6c 74 65 72 74 61 62 6c 65 7d  BLE} altertable}
0660: 0a 20 20 20 20 7b 7b 41 4e 41 4c 59 5a 45 7d 20  .    {{ANALYZE} 
0670: 61 6e 61 6c 79 7a 65 7d 0a 20 20 20 20 7b 7b 49  analyze}.    {{I
0680: 4e 44 45 58 45 44 20 42 59 7d 20 69 6e 64 65 78  NDEXED BY} index
0690: 65 64 62 79 7d 0a 20 20 20 20 7b 7b 61 67 67 72  edby}.    {{aggr
06a0: 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 7d  egate functions}
06b0: 20 61 67 67 66 75 6e 63 20 61 67 67 66 75 6e 63   aggfunc aggfunc
06c0: 7d 0a 20 20 20 20 7b 7b 63 6f 72 65 20 66 75 6e  }.    {{core fun
06d0: 63 74 69 6f 6e 73 7d 20 63 6f 72 65 66 75 6e 63  ctions} corefunc
06e0: 20 63 6f 72 65 66 75 6e 63 7d 0a 20 20 20 20 7b   corefunc}.    {
06f0: 7b 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 66  {date and time f
0700: 75 6e 63 74 69 6f 6e 73 7d 20 64 61 74 65 66 75  unctions} datefu
0710: 6e 63 20 64 61 74 65 66 75 6e 63 7d 0a 20 20 20  nc datefunc}.   
0720: 20 7b 6b 65 79 77 6f 72 64 73 20 6b 65 79 77 6f   {keywords keywo
0730: 72 64 73 20 7b 53 51 4c 20 6b 65 79 77 6f 72 64  rds {SQL keyword
0740: 73 7d 7d 0a 20 20 7d 0a 20 20 73 65 74 20 6c 78  s}}.  }.  set lx
0750: 20 7b 7d 0a 20 20 66 6f 72 65 61 63 68 20 7b 73   {}.  foreach {s
0760: 65 63 74 69 6f 6e 7d 20 5b 6c 73 6f 72 74 20 2d  ection} [lsort -
0770: 69 6e 64 65 78 20 30 20 2d 64 69 63 74 69 6f 6e  index 0 -diction
0780: 61 72 79 20 24 6c 61 6e 67 5f 73 65 63 74 69 6f  ary $lang_sectio
0790: 6e 5f 6c 69 73 74 5d 20 7b 0a 20 20 20 20 66 6f  n_list] {.    fo
07a0: 72 65 61 63 68 20 7b 73 5f 74 69 74 6c 65 20 73  reach {s_title s
07b0: 5f 74 61 67 20 73 5f 6b 77 7d 20 24 73 65 63 74  _tag s_kw} $sect
07c0: 69 6f 6e 20 7b 7d 0a 20 20 20 20 69 66 20 7b 24  ion {}.    if {$
07d0: 73 5f 6b 77 20 3d 3d 20 22 22 7d 20 7b 0a 20 20  s_kw == ""} {.  
07e0: 20 20 20 20 73 65 74 20 73 5f 6b 77 20 24 73 5f      set s_kw $s_
07f0: 74 69 74 6c 65 0a 20 20 20 20 7d 0a 20 20 20 20  title.    }.    
0800: 6c 61 70 70 65 6e 64 20 6c 78 20 5b 6c 69 73 74  lappend lx [list
0810: 20 24 73 5f 6b 77 20 24 73 5f 74 69 74 6c 65 20   $s_kw $s_title 
0820: 30 5d 0a 20 20 7d 0a 20 20 68 64 5f 6c 69 73 74  0].  }.  hd_list
0830: 5f 6f 66 5f 6c 69 6e 6b 73 20 7b 7d 20 33 34 30  _of_links {} 340
0840: 20 24 6c 78 0a 3c 2f 74 63 6c 3e 0a 3c 2f 75 6c   $lx.</tcl>.</ul
0850: 3e 3c 2f 74 64 3e 3c 2f 74 72 3e 3c 2f 74 61 62  ></td></tr></tab
0860: 6c 65 3e 0a 0a 3c 70 3e 5e 54 68 65 20 72 6f 75  le>..<p>^The rou
0870: 74 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  tines [sqlite3_p
0880: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
0890: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
08a0: 5d 2c 0a 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ],.[sqlite3_prep
08b0: 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
08c0: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
08d0: 29 5d 2c 20 0a 5b 73 71 6c 69 74 65 33 5f 65 78  )], .[sqlite3_ex
08e0: 65 63 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ec()], and [sqli
08f0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
0900: 20 61 63 63 65 70 74 0a 61 6e 20 53 51 4c 20 73   accept.an SQL s
0910: 74 61 74 65 6d 65 6e 74 20 6c 69 73 74 20 28 73  tatement list (s
0920: 71 6c 2d 73 74 6d 74 2d 6c 69 73 74 29 20 77 68  ql-stmt-list) wh
0930: 69 63 68 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  ich is a semicol
0940: 6f 6e 2d 73 65 70 61 72 61 74 65 64 0a 6c 69 73  on-separated.lis
0950: 74 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 73 2e  t of statements.
0960: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 42 75 62 62 6c  </p>..<tcl>Bubbl
0970: 65 44 69 61 67 72 61 6d 20 73 71 6c 2d 73 74 6d  eDiagram sql-stm
0980: 74 2d 6c 69 73 74 3c 2f 74 63 6c 3e 0a 0a 3c 70  t-list</tcl>..<p
0990: 3e 45 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d  >Each SQL statem
09a0: 65 6e 74 20 69 6e 20 74 68 65 20 73 74 61 74 65  ent in the state
09b0: 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 6e 20  ment list is an 
09c0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
09d0: 66 6f 6c 6c 6f 77 69 6e 67 3a 3c 2f 70 3e 0a 0a  following:</p>..
09e0: 3c 74 63 6c 3e 42 75 62 62 6c 65 44 69 61 67 72  <tcl>BubbleDiagr
09f0: 61 6d 20 73 71 6c 2d 73 74 6d 74 3c 2f 74 63 6c  am sql-stmt</tcl
0a00: 3e 0a 0a 3c 74 63 6c 3e 0a 70 72 6f 63 20 4f 70  >..<tcl>.proc Op
0a10: 65 72 61 74 6f 72 20 7b 6e 61 6d 65 7d 20 7b 0a  erator {name} {.
0a20: 20 20 72 65 74 75 72 6e 20 22 3c 66 6f 6e 74 20    return "<font 
0a30: 63 6f 6c 6f 72 3d 5c 22 23 32 63 32 63 66 30 5c  color=\"#2c2cf0\
0a40: 22 3e 3c 62 69 67 3e 24 6e 61 6d 65 3c 2f 62 69  "><big>$name</bi
0a50: 67 3e 3c 2f 66 6f 6e 74 3e 22 0a 7d 0a 70 72 6f  g></font>".}.pro
0a60: 63 20 4e 6f 6e 74 65 72 6d 69 6e 61 6c 20 7b 6e  c Nonterminal {n
0a70: 61 6d 65 7d 20 7b 0a 20 20 72 65 74 75 72 6e 20  ame} {.  return 
0a80: 22 3c 69 3e 3c 66 6f 6e 74 20 63 6f 6c 6f 72 3d  "<i><font color=
0a90: 5c 22 23 66 66 33 34 33 34 5c 22 3e 24 6e 61 6d  \"#ff3434\">$nam
0aa0: 65 3c 2f 66 6f 6e 74 3e 3c 2f 69 3e 22 0a 7d 0a  e</font></i>".}.
0ab0: 70 72 6f 63 20 4b 65 79 77 6f 72 64 20 7b 6e 61  proc Keyword {na
0ac0: 6d 65 7d 20 7b 0a 20 20 72 65 74 75 72 6e 20 22  me} {.  return "
0ad0: 3c 66 6f 6e 74 20 63 6f 6c 6f 72 3d 5c 22 23 32  <font color=\"#2
0ae0: 63 32 63 66 30 5c 22 3e 24 6e 61 6d 65 3c 2f 66  c2cf0\">$name</f
0af0: 6f 6e 74 3e 22 0a 7d 0a 70 72 6f 63 20 45 78 61  ont>".}.proc Exa
0b00: 6d 70 6c 65 20 7b 74 65 78 74 7d 20 7b 0a 20 20  mple {text} {.  
0b10: 68 64 5f 70 75 74 73 20 22 3c 62 6c 6f 63 6b 71  hd_puts "<blockq
0b20: 75 6f 74 65 3e 3c 70 72 65 3e 24 74 65 78 74 3c  uote><pre>$text<
0b30: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
0b40: 65 3e 22 0a 7d 0a 0a 70 72 6f 63 20 53 65 63 74  e>".}..proc Sect
0b50: 69 6f 6e 20 7b 6e 61 6d 65 20 6c 61 62 65 6c 20  ion {name label 
0b60: 6b 65 79 77 6f 72 64 73 7d 20 7b 0a 20 20 67 6c  keywords} {.  gl
0b70: 6f 62 61 6c 20 44 4f 43 0a 20 20 68 64 5f 63 6c  obal DOC.  hd_cl
0b80: 6f 73 65 5f 6d 61 69 6e 0a 20 20 68 64 5f 6f 70  ose_main.  hd_op
0b90: 65 6e 5f 6d 61 69 6e 20 6c 61 6e 67 5f 24 6c 61  en_main lang_$la
0ba0: 62 65 6c 2e 68 74 6d 6c 0a 20 20 68 64 5f 68 65  bel.html.  hd_he
0bb0: 61 64 65 72 20 22 53 51 4c 69 74 65 20 51 75 65  ader "SQLite Que
0bc0: 72 79 20 4c 61 6e 67 75 61 67 65 3a 20 24 6e 61  ry Language: $na
0bd0: 6d 65 22 20 24 44 4f 43 2f 70 61 67 65 73 2f 6c  me" $DOC/pages/l
0be0: 61 6e 67 2e 69 6e 0a 20 20 65 76 61 6c 20 68 64  ang.in.  eval hd
0bf0: 5f 6b 65 79 77 6f 72 64 73 20 24 6b 65 79 77 6f  _keywords $keywo
0c00: 72 64 73 0a 20 20 69 66 20 7b 5b 6c 73 65 61 72  rds.  if {[lsear
0c10: 63 68 20 24 6b 65 79 77 6f 72 64 73 20 24 6e 61  ch $keywords $na
0c20: 6d 65 5d 20 3d 3d 20 2d 31 20 26 26 20 5b 6c 73  me] == -1 && [ls
0c30: 65 61 72 63 68 20 24 6b 65 79 77 6f 72 64 73 20  earch $keywords 
0c40: 2a 24 6e 61 6d 65 5d 20 3d 3d 20 2d 31 7d 20 7b  *$name] == -1} {
0c50: 0a 20 20 20 20 65 76 61 6c 20 68 64 5f 6b 65 79  .    eval hd_key
0c60: 77 6f 72 64 73 20 7b 20 24 6e 61 6d 65 20 7d 0a  words { $name }.
0c70: 20 20 7d 0a 20 20 68 64 5f 70 75 74 73 20 7b 3c    }.  hd_puts {<
0c80: 64 69 76 20 63 6c 61 73 73 3d 6e 6f 73 65 61 72  div class=nosear
0c90: 63 68 3e 7d 0a 20 20 68 64 5f 70 75 74 73 20 7b  ch>}.  hd_puts {
0ca0: 3c 68 31 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <h1 align="cente
0cb0: 72 22 3e 53 51 4c 20 41 73 20 55 6e 64 65 72 73  r">SQL As Unders
0cc0: 74 6f 6f 64 20 42 79 20 53 51 4c 69 74 65 3c 2f  tood By SQLite</
0cd0: 68 31 3e 7d 0a 20 20 68 64 5f 70 75 74 73 20 7b  h1>}.  hd_puts {
0ce0: 3c 70 3e 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67  <p><a href="lang
0cf0: 2e 68 74 6d 6c 22 3e 5b 54 6f 70 5d 3c 2f 61 3e  .html">[Top]</a>
0d00: 3c 2f 70 3e 7d 0a 20 20 68 64 5f 70 75 74 73 20  </p>}.  hd_puts 
0d10: 22 3c 68 32 3e 24 6e 61 6d 65 3c 2f 68 32 3e 22  "<h2>$name</h2>"
0d20: 0a 20 20 68 64 5f 70 75 74 73 20 7b 3c 2f 64 69  .  hd_puts {</di
0d30: 76 3e 7d 0a 7d 0a 0a 23 23 23 23 23 23 23 23 23  v>}.}..#########
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 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
0d80: 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b  ######.Section {
0d90: 41 4c 54 45 52 20 54 41 42 4c 45 7d 20 61 6c 74  ALTER TABLE} alt
0da0: 65 72 74 61 62 6c 65 20 7b 7b 41 4c 54 45 52 20  ertable {{ALTER 
0db0: 54 41 42 4c 45 7d 20 7b 2a 41 4c 54 45 52 7d 7d  TABLE} {*ALTER}}
0dc0: 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  ..RecursiveBubbl
0dd0: 65 44 69 61 67 72 61 6d 20 61 6c 74 65 72 2d 74  eDiagram alter-t
0de0: 61 62 6c 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e  able-stmt.</tcl>
0df0: 0a 0a 3c 70 3e 53 51 4c 69 74 65 20 73 75 70 70  ..<p>SQLite supp
0e00: 6f 72 74 73 20 61 20 6c 69 6d 69 74 65 64 20 73  orts a limited s
0e10: 75 62 73 65 74 20 6f 66 20 41 4c 54 45 52 20 54  ubset of ALTER T
0e20: 41 42 4c 45 2e 0a 54 68 65 20 41 4c 54 45 52 20  ABLE..The ALTER 
0e30: 54 41 42 4c 45 20 63 6f 6d 6d 61 6e 64 20 69 6e  TABLE command in
0e40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 74   SQLite allows t
0e50: 68 65 20 75 73 65 72 20 74 6f 20 72 65 6e 61 6d  he user to renam
0e60: 65 20 61 20 74 61 62 6c 65 2c 0a 74 6f 20 72 65  e a table,.to re
0e70: 6e 61 6d 65 20 61 20 63 6f 6c 75 6d 6e 20 77 69  name a column wi
0e80: 74 68 69 6e 20 61 20 74 61 62 6c 65 2c 20 6f 72  thin a table, or
0e90: 20 74 6f 20 61 64 64 20 61 20 6e 65 77 20 63 6f   to add a new co
0ea0: 6c 75 6d 6e 20 74 6f 20 61 6e 20 65 78 69 73 74  lumn to an exist
0eb0: 69 6e 67 20 74 61 62 6c 65 2e 0a 0a 3c 74 63 6c  ing table...<tcl
0ec0: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 61 6c 74  >hd_fragment alt
0ed0: 65 72 74 61 62 72 65 6e 61 6d 65 20 7b 41 4c 54  ertabrename {ALT
0ee0: 45 52 20 54 41 42 4c 45 20 52 45 4e 41 4d 45 7d  ER TABLE RENAME}
0ef0: 20 7b 72 65 6e 61 6d 65 20 74 61 62 6c 65 7d 20   {rename table} 
0f00: 5c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  \.              
0f10: 20 20 20 7b 41 4c 54 45 52 20 54 41 42 4c 45 20     {ALTER TABLE 
0f20: 52 45 4e 41 4d 45 20 64 6f 63 75 6d 65 6e 74 61  RENAME documenta
0f30: 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  tion}</tcl>.<h3>
0f40: 41 4c 54 45 52 20 54 41 42 4c 45 20 52 45 4e 41  ALTER TABLE RENA
0f50: 4d 45 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 5e 28 54  ME</h3>..<p> ^(T
0f60: 68 65 20 52 45 4e 41 4d 45 20 54 4f 20 73 79 6e  he RENAME TO syn
0f70: 74 61 78 20 63 68 61 6e 67 65 73 20 74 68 65 20  tax changes the 
0f80: 6e 61 6d 65 20 6f 66 20 3c 79 79 74 65 72 6d 3e  name of <yyterm>
0f90: 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65  table-name</yyte
0fa0: 72 6d 3e 0a 74 6f 20 3c 79 79 74 65 72 6d 3e 6e  rm>.to <yyterm>n
0fb0: 65 77 2d 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79  ew-table-name</y
0fc0: 79 74 65 72 6d 3e 2e 29 5e 0a 54 68 69 73 20 63  yterm>.)^.This c
0fd0: 6f 6d 6d 61 6e 64 20 0a 63 61 6e 6e 6f 74 20 62  ommand .cannot b
0fe0: 65 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 61  e used to move a
0ff0: 20 74 61 62 6c 65 20 62 65 74 77 65 65 6e 20 61   table between a
1000: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1010: 73 2c 20 6f 6e 6c 79 20 74 6f 20 72 65 6e 61 6d  s, only to renam
1020: 65 20 0a 61 20 74 61 62 6c 65 20 77 69 74 68 69  e .a table withi
1030: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1040: 61 73 65 2e 0a 5e 49 66 20 74 68 65 20 74 61 62  ase..^If the tab
1050: 6c 65 20 62 65 69 6e 67 20 72 65 6e 61 6d 65 64  le being renamed
1060: 20 68 61 73 20 74 72 69 67 67 65 72 73 20 6f 72   has triggers or
1070: 20 69 6e 64 69 63 65 73 2c 20 74 68 65 6e 20 74   indices, then t
1080: 68 65 73 65 20 72 65 6d 61 69 6e 0a 61 74 74 61  hese remain.atta
1090: 63 68 65 64 20 74 6f 20 74 68 65 20 74 61 62 6c  ched to the tabl
10a0: 65 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  e after it has b
10b0: 65 65 6e 20 72 65 6e 61 6d 65 64 2e 0a 0a 3c 62  een renamed...<b
10c0: 6c 6f 63 6b 71 75 6f 74 65 20 73 74 79 6c 65 3d  lockquote style=
10d0: 27 62 61 63 6b 67 72 6f 75 6e 64 2d 63 6f 6c 6f  'background-colo
10e0: 72 3a 20 23 66 66 64 30 64 30 3b 27 3e 0a 3c 62  r: #ffd0d0;'>.<b
10f0: 3e 43 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 4e  >Compatibility N
1100: 6f 74 65 3a 3c 2f 62 3e 0a 54 68 65 20 62 65 68  ote:</b>.The beh
1110: 61 76 69 6f 72 20 6f 66 20 41 4c 54 45 52 20 54  avior of ALTER T
1120: 41 42 4c 45 20 77 68 65 6e 20 72 65 6e 61 6d 69  ABLE when renami
1130: 6e 67 20 61 20 74 61 62 6c 65 20 77 61 73 20 65  ng a table was e
1140: 6e 68 61 6e 63 65 64 0a 69 6e 20 76 65 72 73 69  nhanced.in versi
1150: 6f 6e 73 20 33 2e 32 35 2e 30 20 28 5b 64 61 74  ons 3.25.0 ([dat
1160: 65 6f 66 3a 33 2e 32 35 2e 30 5d 29 20 61 6e 64  eof:3.25.0]) and
1170: 20 33 2e 32 36 2e 30 20 28 5b 64 61 74 65 6f 66   3.26.0 ([dateof
1180: 3a 33 2e 32 36 2e 30 5d 29 0a 69 6e 20 6f 72 64  :3.26.0]).in ord
1190: 65 72 20 74 6f 20 63 61 72 72 79 20 74 68 65 20  er to carry the 
11a0: 72 65 6e 61 6d 65 20 6f 70 65 72 61 74 69 6f 6e  rename operation
11b0: 20 66 6f 72 77 61 72 64 20 69 6e 74 6f 20 74 72   forward into tr
11c0: 69 67 67 65 72 73 20 61 6e 64 0a 76 69 65 77 73  iggers and.views
11d0: 20 74 68 61 74 20 72 65 66 65 72 65 6e 63 65 20   that reference 
11e0: 74 68 65 20 72 65 6e 61 6d 65 64 20 74 61 62 6c  the renamed tabl
11f0: 65 2e 20 20 54 68 69 73 20 69 73 20 63 6f 6e 73  e.  This is cons
1200: 69 64 65 72 65 64 20 61 6e 0a 69 6d 70 72 6f 76  idered an.improv
1210: 65 6d 65 6e 74 2e 20 41 70 70 6c 69 63 61 74 69  ement. Applicati
1220: 6f 6e 73 20 74 68 61 74 20 64 65 70 65 6e 64 20  ons that depend 
1230: 6f 6e 20 74 68 65 20 6f 6c 64 65 72 20 28 61 6e  on the older (an
1240: 64 0a 61 72 67 75 61 62 6c 79 20 62 75 67 67 79  d.arguably buggy
1250: 29 20 62 65 68 61 76 69 6f 72 20 63 61 6e 20 75  ) behavior can u
1260: 73 65 20 74 68 65 0a 5b 50 52 41 47 4d 41 20 6c  se the.[PRAGMA l
1270: 65 67 61 63 79 5f 61 6c 74 65 72 5f 74 61 62 6c  egacy_alter_tabl
1280: 65 3d 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 20  e=ON] statement 
1290: 6f 72 20 74 68 65 0a 5b 53 51 4c 49 54 45 5f 44  or the.[SQLITE_D
12a0: 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41  BCONFIG_LEGACY_A
12b0: 4c 54 45 52 5f 54 41 42 4c 45 5d 20 63 6f 6e 66  LTER_TABLE] conf
12c0: 69 67 75 72 61 74 69 6f 6e 20 70 61 72 61 6d 65  iguration parame
12d0: 74 65 72 0a 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  ter.on [sqlite3_
12e0: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
12f0: 65 72 66 61 63 65 20 74 6f 20 6d 61 6b 65 20 41  erface to make A
1300: 4c 54 45 52 20 54 41 42 4c 45 20 52 45 4e 41 4d  LTER TABLE RENAM
1310: 45 0a 62 65 68 61 76 65 20 61 73 20 69 74 20 64  E.behave as it d
1320: 69 64 20 70 72 69 6f 72 20 74 6f 20 76 65 72 73  id prior to vers
1330: 69 6f 6e 20 33 2e 32 35 2e 30 2e 0a 3c 2f 62 6c  ion 3.25.0..</bl
1340: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 42  ockquote>..<p>.B
1350: 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 72 65  eginning with re
1360: 6c 65 61 73 65 20 33 2e 32 35 2e 30 20 28 5b 64  lease 3.25.0 ([d
1370: 61 74 65 6f 66 3a 33 2e 32 35 2e 30 5d 29 2c 20  ateof:3.25.0]), 
1380: 72 65 66 65 72 65 6e 63 65 73 20 74 6f 20 74 68  references to th
1390: 65 20 74 61 62 6c 65 0a 77 69 74 68 69 6e 20 74  e table.within t
13a0: 72 69 67 67 65 72 20 62 6f 64 69 65 73 20 61 6e  rigger bodies an
13b0: 64 20 76 69 65 77 20 64 65 66 69 6e 69 74 69 6f  d view definitio
13c0: 6e 73 20 61 72 65 20 61 6c 73 6f 20 72 65 6e 61  ns are also rena
13d0: 6d 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 50  med..</p>..<p> P
13e0: 72 69 6f 72 20 74 6f 20 76 65 72 73 69 6f 6e 20  rior to version 
13f0: 33 2e 32 36 2e 30 20 28 5b 64 61 74 65 6f 66 3a  3.26.0 ([dateof:
1400: 33 2e 32 36 2e 30 5d 29 2c 20 46 4f 52 45 49 47  3.26.0]), FOREIG
1410: 4e 20 4b 45 59 20 72 65 66 65 72 65 6e 63 65 73  N KEY references
1420: 0a 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  .to a table that
1430: 20 69 73 20 72 65 6e 61 6d 65 64 20 77 65 72 65   is renamed were
1440: 20 6f 6e 6c 79 20 65 64 69 74 65 64 20 69 66 20   only edited if 
1450: 74 68 65 0a 5b 50 52 41 47 4d 41 20 66 6f 72 65  the.[PRAGMA fore
1460: 69 67 6e 5f 6b 65 79 73 3d 4f 4e 5d 2c 20 6f 72  ign_keys=ON], or
1470: 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 20   in other words 
1480: 69 66 0a 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  if.[foreign key 
1490: 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 77 65 72  constraints] wer
14a0: 65 20 62 65 67 69 6e 20 65 6e 66 6f 72 63 65 64  e begin enforced
14b0: 2e 20 20 57 69 74 68 0a 5b 50 52 41 47 4d 41 20  .  With.[PRAGMA 
14c0: 66 6f 72 65 69 67 6e 5f 6b 65 79 73 3d 4f 46 46  foreign_keys=OFF
14d0: 5d 2c 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 63  ], FOREIGN KEY c
14e0: 6f 6e 73 74 72 61 69 6e 74 73 20 77 6f 75 6c 64  onstraints would
14f0: 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 0a   not be changed.
1500: 77 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20 74  when the table t
1510: 68 61 74 20 74 68 65 20 66 6f 72 65 69 67 6e 20  hat the foreign 
1520: 6b 65 79 20 72 65 66 65 72 72 65 64 20 74 6f 20  key referred to 
1530: 28 74 68 65 20 22 5b 70 61 72 65 6e 74 20 74 61  (the "[parent ta
1540: 62 6c 65 5d 22 29 0a 77 61 73 20 72 65 6e 61 6d  ble]").was renam
1550: 65 64 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ed.  Beginning w
1560: 69 74 68 20 76 65 72 73 69 6f 6e 20 33 2e 32 36  ith version 3.26
1570: 2e 30 2c 20 46 4f 52 45 49 47 4e 20 4b 45 59 20  .0, FOREIGN KEY 
1580: 63 6f 6e 73 74 72 61 69 6e 74 73 0a 61 72 65 20  constraints.are 
1590: 61 6c 77 61 79 73 20 63 6f 6e 76 65 72 74 65 64  always converted
15a0: 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
15b0: 20 72 65 6e 61 6d 65 64 2c 20 75 6e 6c 65 73 73   renamed, unless
15c0: 20 74 68 65 0a 5b 50 52 41 47 4d 41 20 6c 65 67   the.[PRAGMA leg
15d0: 61 63 79 5f 61 6c 74 65 72 5f 74 61 62 6c 65 3d  acy_alter_table=
15e0: 4f 4e 5d 20 73 65 74 74 69 6e 67 20 69 73 20 65  ON] setting is e
15f0: 6e 67 61 67 65 64 2e 20 20 54 68 65 20 66 6f 6c  ngaged.  The fol
1600: 6c 6f 77 69 6e 67 0a 74 61 62 6c 65 20 73 75 6d  lowing.table sum
1610: 6d 61 72 69 65 73 20 74 68 65 20 64 69 66 66 65  maries the diffe
1620: 72 65 6e 63 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  rence:</p>..<blo
1630: 63 6b 71 75 6f 74 65 3e 0a 3c 74 61 62 6c 65 20  ckquote>.<table 
1640: 62 6f 72 64 65 72 3d 22 31 22 20 63 65 6c 6c 70  border="1" cellp
1650: 61 64 64 69 6e 67 3d 22 32 22 20 63 65 6c 6c 73  adding="2" cells
1660: 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c 74 72 3e  pacing="0">.<tr>
1670: 0a 3c 74 68 3e 50 52 41 47 4d 41 20 66 6f 72 65  .<th>PRAGMA fore
1680: 69 67 6e 5f 6b 65 79 73 0a 3c 74 68 3e 50 52 41  ign_keys.<th>PRA
1690: 47 4d 41 20 6c 65 67 61 63 79 5f 61 6c 74 65 72  GMA legacy_alter
16a0: 5f 74 61 62 6c 65 0a 3c 74 68 3e 5b 70 61 72 65  _table.<th>[pare
16b0: 6e 74 20 74 61 62 6c 65 7c 50 61 72 65 6e 74 20  nt table|Parent 
16c0: 54 61 62 6c 65 5d 0a 72 65 66 65 72 65 6e 63 65  Table].reference
16d0: 73 20 61 72 65 20 75 70 64 61 74 65 64 0a 3c 74  s are updated.<t
16e0: 68 3e 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h>SQLite version
16f0: 0a 3c 74 72 3e 3c 74 64 20 61 6c 69 67 6e 3d 22  .<tr><td align="
1700: 63 65 6e 74 65 72 22 3e 4f 66 66 3c 74 64 20 61  center">Off<td a
1710: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4f 66  lign="center">Of
1720: 66 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  f<td align="cent
1730: 65 72 22 3e 4e 6f 3c 74 64 20 61 6c 69 67 6e 3d  er">No<td align=
1740: 22 63 65 6e 74 65 72 22 3e 26 6c 74 3b 20 33 2e  "center">&lt; 3.
1750: 32 36 2e 30 0a 3c 74 72 3e 3c 74 64 20 61 6c 69  26.0.<tr><td ali
1760: 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4f 66 66 3c  gn="center">Off<
1770: 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
1780: 22 3e 4f 66 66 3c 74 64 20 61 6c 69 67 6e 3d 22  ">Off<td align="
1790: 63 65 6e 74 65 72 22 3e 59 65 73 3c 74 64 20 61  center">Yes<td a
17a0: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 26 67  lign="center">&g
17b0: 74 3b 3d 20 33 2e 32 36 2e 30 0a 3c 74 72 3e 3c  t;= 3.26.0.<tr><
17c0: 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
17d0: 22 3e 4f 6e 3c 74 64 20 61 6c 69 67 6e 3d 22 63  ">On<td align="c
17e0: 65 6e 74 65 72 22 3e 4f 66 66 3c 74 64 20 61 6c  enter">Off<td al
17f0: 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 59 65 73  ign="center">Yes
1800: 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
1810: 72 22 3e 61 6c 6c 0a 3c 74 72 3e 3c 74 64 20 61  r">all.<tr><td a
1820: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4f 66  lign="center">Of
1830: 66 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  f<td align="cent
1840: 65 72 22 3e 4f 6e 3c 74 64 20 61 6c 69 67 6e 3d  er">On<td align=
1850: 22 63 65 6e 74 65 72 22 3e 4e 6f 3c 74 64 20 61  "center">No<td a
1860: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 61 6c  lign="center">al
1870: 6c 0a 3c 74 72 3e 3c 74 64 20 61 6c 69 67 6e 3d  l.<tr><td align=
1880: 22 63 65 6e 74 65 72 22 3e 4f 6e 3c 74 64 20 61  "center">On<td a
1890: 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4f 6e  lign="center">On
18a0: 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
18b0: 72 22 3e 59 65 73 3c 74 64 20 61 6c 69 67 6e 3d  r">Yes<td align=
18c0: 22 63 65 6e 74 65 72 22 3e 61 6c 6c 0a 3c 2f 74  "center">all.</t
18d0: 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  able>.</blockquo
18e0: 74 65 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  te>..<tcl>hd_fra
18f0: 67 6d 65 6e 74 20 61 6c 74 65 72 74 61 62 6d 76  gment altertabmv
1900: 63 6f 6c 20 7b 41 4c 54 45 52 20 54 41 42 4c 45  col {ALTER TABLE
1910: 20 52 45 4e 41 4d 45 20 43 4f 4c 55 4d 4e 7d 20   RENAME COLUMN} 
1920: 7b 72 65 6e 61 6d 65 20 63 6f 6c 75 6d 6e 7d 3c  {rename column}<
1930: 2f 74 63 6c 3e 0a 3c 68 33 3e 41 4c 54 45 52 20  /tcl>.<h3>ALTER 
1940: 54 41 42 4c 45 20 52 45 4e 41 4d 45 20 43 4f 4c  TABLE RENAME COL
1950: 55 4d 4e 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68  UMN</h3>..<p> Th
1960: 65 20 52 45 4e 41 4d 45 20 43 4f 4c 55 4d 4e 20  e RENAME COLUMN 
1970: 54 4f 20 73 79 6e 74 61 78 20 63 68 61 6e 67 65  TO syntax change
1980: 73 20 74 68 65 0a 3c 79 79 74 65 72 6d 3e 63 6f  s the.<yyterm>co
1990: 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  lumn-name</yyter
19a0: 6d 3e 20 6f 66 20 74 61 62 6c 65 20 3c 79 79 74  m> of table <yyt
19b0: 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f  erm>table-name</
19c0: 79 79 74 65 72 6d 3e 0a 69 6e 74 6f 20 3c 79 79  yyterm>.into <yy
19d0: 74 65 72 6d 3e 6e 65 77 2d 63 6f 6c 75 6d 6e 2d  term>new-column-
19e0: 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2e 20 20  name</yyterm>.  
19f0: 54 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20  The column name 
1a00: 69 73 20 63 68 61 6e 67 65 64 20 62 6f 74 68 0a  is changed both.
1a10: 77 69 74 68 69 6e 20 74 68 65 20 74 61 62 6c 65  within the table
1a20: 20 64 65 66 69 6e 69 74 69 6f 6e 20 69 74 73 65   definition itse
1a30: 6c 66 20 61 6e 64 20 61 6c 73 6f 20 77 69 74 68  lf and also with
1a40: 69 6e 20 61 6c 6c 20 69 6e 64 65 78 65 73 2c 20  in all indexes, 
1a50: 74 72 69 67 67 65 72 73 2c 0a 61 6e 64 20 76 69  triggers,.and vi
1a60: 65 77 73 20 74 68 61 74 20 72 65 66 65 72 65 6e  ews that referen
1a70: 63 65 20 74 68 65 20 63 6f 6c 75 6d 6e 2e 20 20  ce the column.  
1a80: 49 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  If the column na
1a90: 6d 65 20 63 68 61 6e 67 65 20 77 6f 75 6c 64 0a  me change would.
1aa0: 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 6d 61  result in a sema
1ab0: 6e 74 69 63 20 61 6d 62 69 67 75 69 74 79 20 69  ntic ambiguity i
1ac0: 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 76  n a trigger or v
1ad0: 69 65 77 2c 20 74 68 65 6e 20 74 68 65 20 52 45  iew, then the RE
1ae0: 4e 41 4d 45 0a 43 4f 4c 55 4d 4e 20 66 61 69 6c  NAME.COLUMN fail
1af0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  s with an error 
1b00: 61 6e 64 20 6e 6f 20 63 68 61 6e 67 65 73 20 61  and no changes a
1b10: 72 65 20 61 70 70 6c 69 65 64 2e 0a 0a 3c 74 63  re applied...<tc
1b20: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 61 6c  l>hd_fragment al
1b30: 74 65 72 74 61 62 61 64 64 63 6f 6c 20 7b 41 4c  tertabaddcol {AL
1b40: 54 45 52 20 54 41 42 4c 45 20 41 44 44 20 43 4f  TER TABLE ADD CO
1b50: 4c 55 4d 4e 7d 20 7b 61 64 64 20 63 6f 6c 75 6d  LUMN} {add colum
1b60: 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 41 4c 54  n}</tcl>.<h3>ALT
1b70: 45 52 20 54 41 42 4c 45 20 41 44 44 20 43 4f 4c  ER TABLE ADD COL
1b80: 55 4d 4e 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 5e 54  UMN</h3>..<p> ^T
1b90: 68 65 20 41 44 44 20 43 4f 4c 55 4d 4e 20 73 79  he ADD COLUMN sy
1ba0: 6e 74 61 78 0a 69 73 20 75 73 65 64 20 74 6f 20  ntax.is used to 
1bb0: 61 64 64 20 61 20 6e 65 77 20 63 6f 6c 75 6d 6e  add a new column
1bc0: 20 74 6f 20 61 6e 20 65 78 69 73 74 69 6e 67 20   to an existing 
1bd0: 74 61 62 6c 65 2e 0a 5e 54 68 65 20 6e 65 77 20  table..^The new 
1be0: 63 6f 6c 75 6d 6e 20 69 73 20 61 6c 77 61 79 73  column is always
1bf0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65   appended to the
1c00: 20 65 6e 64 20 6f 66 20 74 68 65 20 6c 69 73 74   end of the list
1c10: 20 6f 66 20 65 78 69 73 74 69 6e 67 20 63 6f 6c   of existing col
1c20: 75 6d 6e 73 2e 0a 54 68 65 20 5b 63 6f 6c 75 6d  umns..The [colum
1c30: 6e 2d 64 65 66 5d 20 72 75 6c 65 20 64 65 66 69  n-def] rule defi
1c40: 6e 65 73 20 74 68 65 20 63 68 61 72 61 63 74 65  nes the characte
1c50: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6e  ristics of the n
1c60: 65 77 20 63 6f 6c 75 6d 6e 2e 0a 5e 28 54 68 65  ew column..^(The
1c70: 20 6e 65 77 20 63 6f 6c 75 6d 6e 20 6d 61 79 20   new column may 
1c80: 74 61 6b 65 20 61 6e 79 20 6f 66 20 74 68 65 20  take any of the 
1c90: 66 6f 72 6d 73 20 70 65 72 6d 69 73 73 69 62 6c  forms permissibl
1ca0: 65 20 69 6e 20 61 20 5b 43 52 45 41 54 45 20 54  e in a [CREATE T
1cb0: 41 42 4c 45 5d 0a 73 74 61 74 65 6d 65 6e 74 2c  ABLE].statement,
1cc0: 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77   with the follow
1cd0: 69 6e 67 20 72 65 73 74 72 69 63 74 69 6f 6e 73  ing restrictions
1ce0: 3a 29 5e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 5e 54 68  :)^.<ul>.<li>^Th
1cf0: 65 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 6e 6f 74  e column may not
1d00: 20 68 61 76 65 20 61 20 50 52 49 4d 41 52 59 20   have a PRIMARY 
1d10: 4b 45 59 20 6f 72 20 55 4e 49 51 55 45 20 63 6f  KEY or UNIQUE co
1d20: 6e 73 74 72 61 69 6e 74 2e 3c 2f 6c 69 3e 0a 3c  nstraint.</li>.<
1d30: 6c 69 3e 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 6d  li>^The column m
1d40: 61 79 20 6e 6f 74 20 68 61 76 65 20 61 20 64 65  ay not have a de
1d50: 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 43  fault value of C
1d60: 55 52 52 45 4e 54 5f 54 49 4d 45 2c 20 43 55 52  URRENT_TIME, CUR
1d70: 52 45 4e 54 5f 44 41 54 45 2c 20 0a 20 20 20 20  RENT_DATE, .    
1d80: 43 55 52 52 45 4e 54 5f 54 49 4d 45 53 54 41 4d  CURRENT_TIMESTAM
1d90: 50 2c 20 6f 72 20 61 6e 20 65 78 70 72 65 73 73  P, or an express
1da0: 69 6f 6e 20 69 6e 20 70 61 72 65 6e 74 68 65 73  ion in parenthes
1db0: 65 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 5e 49 66  es.</li>.<li>^If
1dc0: 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
1dd0: 74 72 61 69 6e 74 20 69 73 20 73 70 65 63 69 66  traint is specif
1de0: 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  ied, then the co
1df0: 6c 75 6d 6e 20 6d 75 73 74 20 68 61 76 65 20 61  lumn must have a
1e00: 0a 20 20 20 20 64 65 66 61 75 6c 74 20 76 61 6c  .    default val
1e10: 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 4e 55  ue other than NU
1e20: 4c 4c 2e 0a 3c 6c 69 3e 5e 49 66 20 5b 66 6f 72  LL..<li>^If [for
1e30: 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
1e40: 69 6e 74 73 5d 20 61 72 65 20 5b 66 6f 72 65 69  ints] are [forei
1e50: 67 6e 5f 6b 65 79 73 20 70 72 61 67 6d 61 20 7c  gn_keys pragma |
1e60: 20 65 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 20 20   enabled] and.  
1e70: 20 20 61 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20    a column with 
1e80: 61 20 5b 66 6f 72 65 69 67 6e 2d 6b 65 79 2d 63  a [foreign-key-c
1e90: 6c 61 75 73 65 20 7c 20 52 45 46 45 52 45 4e 43  lause | REFERENC
1ea0: 45 53 20 63 6c 61 75 73 65 5d 0a 20 20 20 20 69  ES clause].    i
1eb0: 73 20 61 64 64 65 64 2c 20 74 68 65 20 63 6f 6c  s added, the col
1ec0: 75 6d 6e 20 6d 75 73 74 20 68 61 76 65 20 61 20  umn must have a 
1ed0: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
1ee0: 20 4e 55 4c 4c 2e 0a 3c 6c 69 3e 5e 54 68 65 20   NULL..<li>^The 
1ef0: 63 6f 6c 75 6d 6e 20 6d 61 79 20 6e 6f 74 20 62  column may not b
1f00: 65 20 5b 67 65 6e 65 72 61 74 65 64 20 63 6f 6c  e [generated col
1f10: 75 6d 6e 73 7c 47 45 4e 45 52 41 54 45 44 20 41  umns|GENERATED A
1f20: 4c 57 41 59 53 20 2e 2e 2e 20 53 54 4f 52 45 44  LWAYS ... STORED
1f30: 5d 2c 0a 74 68 6f 75 67 68 20 56 49 52 54 55 41  ],.though VIRTUA
1f40: 4c 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 61 6c  L columns are al
1f50: 6c 6f 77 65 64 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  lowed..</ul>..<p
1f60: 3e 5e 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  >^Note also that
1f70: 20 77 68 65 6e 20 61 64 64 69 6e 67 20 61 20 5b   when adding a [
1f80: 43 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74  CHECK constraint
1f90: 5d 2c 20 74 68 65 20 43 48 45 43 4b 20 63 6f 6e  ], the CHECK con
1fa0: 73 74 72 61 69 6e 74 0a 69 73 20 6e 6f 74 20 74  straint.is not t
1fb0: 65 73 74 65 64 20 61 67 61 69 6e 73 74 20 70 72  ested against pr
1fc0: 65 65 78 69 73 74 69 6e 67 20 72 6f 77 73 20 6f  eexisting rows o
1fd0: 66 20 74 68 65 20 74 61 62 6c 65 2e 0a 5e 54 68  f the table..^Th
1fe0: 69 73 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  is can result in
1ff0: 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 63 6f   a table that co
2000: 6e 74 61 69 6e 73 20 64 61 74 61 20 74 68 61 74  ntains data that
2010: 0a 69 73 20 69 6e 20 76 69 6f 6c 61 74 69 6f 6e  .is in violation
2020: 20 6f 66 20 74 68 65 20 43 48 45 43 4b 20 63 6f   of the CHECK co
2030: 6e 73 74 72 61 69 6e 74 2e 20 20 46 75 74 75 72  nstraint.  Futur
2040: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
2050: 4c 69 74 65 20 6d 69 67 68 74 0a 63 68 61 6e 67  Lite might.chang
2060: 65 20 74 6f 20 76 61 6c 69 64 61 74 65 20 43 48  e to validate CH
2070: 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ECK constraints 
2080: 61 73 20 74 68 65 79 20 61 72 65 20 61 64 64 65  as they are adde
2090: 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 41  d.</p>..<p>The A
20a0: 4c 54 45 52 20 54 41 42 4c 45 20 63 6f 6d 6d 61  LTER TABLE comma
20b0: 6e 64 20 77 6f 72 6b 73 20 62 79 20 6d 6f 64 69  nd works by modi
20c0: 66 79 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  fying the SQL te
20d0: 78 74 20 6f 66 20 74 68 65 20 73 63 68 65 6d 61  xt of the schema
20e0: 0a 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 5b  .stored in the [
20f0: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 74 61  sqlite_master ta
2100: 62 6c 65 5d 2e 0a 4e 6f 20 63 68 61 6e 67 65 73  ble]..No changes
2110: 20 61 72 65 20 6d 61 64 65 20 74 6f 20 74 61 62   are made to tab
2120: 6c 65 20 63 6f 6e 74 65 6e 74 2e 0a 42 65 63 61  le content..Beca
2130: 75 73 65 20 6f 66 20 74 68 69 73 2c 0a 74 68 65  use of this,.the
2140: 20 65 78 65 63 75 74 69 6f 6e 20 74 69 6d 65 20   execution time 
2150: 6f 66 20 74 68 65 20 41 4c 54 45 52 20 54 41 42  of the ALTER TAB
2160: 4c 45 20 63 6f 6d 6d 61 6e 64 20 69 73 20 69 6e  LE command is in
2170: 64 65 70 65 6e 64 65 6e 74 20 6f 66 0a 74 68 65  dependent of.the
2180: 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2190: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54  in the table.  T
21a0: 68 65 20 41 4c 54 45 52 20 54 41 42 4c 45 20 63  he ALTER TABLE c
21b0: 6f 6d 6d 61 6e 64 20 72 75 6e 73 20 61 73 20 71  ommand runs as q
21c0: 75 69 63 6b 6c 79 0a 6f 6e 20 61 20 74 61 62 6c  uickly.on a tabl
21d0: 65 20 77 69 74 68 20 31 30 20 6d 69 6c 6c 69 6f  e with 10 millio
21e0: 6e 20 72 6f 77 73 20 61 73 20 69 74 20 64 6f 65  n rows as it doe
21f0: 73 20 6f 6e 20 61 20 74 61 62 6c 65 20 77 69 74  s on a table wit
2200: 68 20 31 20 72 6f 77 2e 0a 3c 2f 70 3e 0a 0a 3c  h 1 row..</p>..<
2210: 70 3e 41 66 74 65 72 20 41 44 44 20 43 4f 4c 55  p>After ADD COLU
2220: 4d 4e 20 68 61 73 20 62 65 65 6e 20 72 75 6e 20  MN has been run 
2230: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 2c 20 74  on a database, t
2240: 68 61 74 20 64 61 74 61 62 61 73 65 20 77 69 6c  hat database wil
2250: 6c 20 6e 6f 74 0a 62 65 20 72 65 61 64 61 62 6c  l not.be readabl
2260: 65 20 62 79 20 53 51 4c 69 74 65 20 76 65 72 73  e by SQLite vers
2270: 69 6f 6e 20 33 2e 31 2e 33 20 28 5b 64 61 74 65  ion 3.1.3 ([date
2280: 6f 66 3a 33 2e 31 2e 33 5d 29 20 61 6e 64 20 65  of:3.1.3]) and e
2290: 61 72 6c 69 65 72 2e 3c 2f 70 3e 0a 0a 3c 74 63  arlier.</p>..<tc
22a0: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6f 74  l>hd_fragment ot
22b0: 68 65 72 61 6c 74 65 72 20 7b 67 65 6e 65 72 61  heralter {genera
22c0: 6c 69 7a 65 64 20 41 4c 54 45 52 20 54 41 42 4c  lized ALTER TABL
22d0: 45 20 70 72 6f 63 65 64 75 72 65 7d 3c 2f 74 63  E procedure}</tc
22e0: 6c 3e 0a 3c 68 33 3e 4d 61 6b 69 6e 67 20 4f 74  l>.<h3>Making Ot
22f0: 68 65 72 20 4b 69 6e 64 73 20 4f 66 20 54 61 62  her Kinds Of Tab
2300: 6c 65 20 53 63 68 65 6d 61 20 43 68 61 6e 67 65  le Schema Change
2310: 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20  s</h3>..<p> The 
2320: 6f 6e 6c 79 20 73 63 68 65 6d 61 20 61 6c 74 65  only schema alte
2330: 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 73 20 64 69  ring commands di
2340: 72 65 63 74 6c 79 20 73 75 70 70 6f 72 74 65 64  rectly supported
2350: 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 20 74   by SQLite are t
2360: 68 65 0a 22 5b 72 65 6e 61 6d 65 20 74 61 62 6c  he."[rename tabl
2370: 65 5d 22 2c 20 22 5b 72 65 6e 61 6d 65 20 63 6f  e]", "[rename co
2380: 6c 75 6d 6e 5d 22 2c 20 61 6e 64 20 22 5b 61 64  lumn]", and "[ad
2390: 64 20 63 6f 6c 75 6d 6e 5d 22 20 63 6f 6d 6d 61  d column]" comma
23a0: 6e 64 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e  nds shown above.
23b0: 20 20 0a 48 6f 77 65 76 65 72 2c 20 61 70 70 6c    .However, appl
23c0: 69 63 61 74 69 6f 6e 73 0a 63 61 6e 20 6d 61 6b  ications.can mak
23d0: 65 20 6f 74 68 65 72 20 61 72 62 69 74 72 61 72  e other arbitrar
23e0: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
23f0: 20 66 6f 72 6d 61 74 20 6f 66 20 61 20 74 61 62   format of a tab
2400: 6c 65 20 75 73 69 6e 67 20 61 20 73 69 6d 70 6c  le using a simpl
2410: 65 0a 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 70  e.sequence of op
2420: 65 72 61 74 69 6f 6e 73 2e 0a 54 68 65 20 73 74  erations..The st
2430: 65 70 73 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  eps to make arbi
2440: 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
2450: 20 74 68 65 20 73 63 68 65 6d 61 20 64 65 73 69   the schema desi
2460: 67 6e 20 6f 66 20 73 6f 6d 65 20 74 61 62 6c 65  gn of some table
2470: 20 58 0a 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77   X.are as follow
2480: 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e  s:..<ol>.<li><p>
2490: 0a 49 66 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  .If foreign key 
24a0: 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 72 65 20  constraints are 
24b0: 65 6e 61 62 6c 65 64 2c 20 64 69 73 61 62 6c 65  enabled, disable
24c0: 20 74 68 65 6d 20 75 73 69 6e 67 20 5b 50 52 41   them using [PRA
24d0: 47 4d 41 20 66 6f 72 65 69 67 6e 5f 6b 65 79 73  GMA foreign_keys
24e0: 3d 4f 46 46 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a  =OFF]...<li><p>.
24f0: 53 74 61 72 74 20 61 20 74 72 61 6e 73 61 63 74  Start a transact
2500: 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 52 65  ion...<li><p>.Re
2510: 6d 65 6d 62 65 72 20 74 68 65 20 66 6f 72 6d 61  member the forma
2520: 74 20 6f 66 20 61 6c 6c 20 69 6e 64 65 78 65 73  t of all indexes
2530: 2c 20 74 72 69 67 67 65 72 73 2c 20 61 6e 64 20  , triggers, and 
2540: 76 69 65 77 73 20 61 73 73 6f 63 69 61 74 65 64  views associated
2550: 20 77 69 74 68 20 74 61 62 6c 65 20 58 2e 0a 54   with table X..T
2560: 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  his information 
2570: 77 69 6c 6c 20 62 65 20 6e 65 65 64 65 64 20 69  will be needed i
2580: 6e 20 73 74 65 70 20 38 20 62 65 6c 6f 77 2e 20  n step 8 below. 
2590: 20 4f 6e 65 20 77 61 79 20 74 6f 20 64 6f 20 74   One way to do t
25a0: 68 69 73 20 69 73 0a 74 6f 20 72 75 6e 20 61 20  his is.to run a 
25b0: 71 75 65 72 79 20 6c 69 6b 65 20 74 68 65 20 66  query like the f
25c0: 6f 6c 6c 6f 77 69 6e 67 3a 0a 53 45 4c 45 43 54  ollowing:.SELECT
25d0: 20 74 79 70 65 2c 20 73 71 6c 20 46 52 4f 4d 20   type, sql FROM 
25e0: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 57 48  sqlite_master WH
25f0: 45 52 45 20 74 62 6c 5f 6e 61 6d 65 3d 27 58 27  ERE tbl_name='X'
2600: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20 5b  ...<li><p>.Use [
2610: 43 52 45 41 54 45 20 54 41 42 4c 45 5d 20 74 6f  CREATE TABLE] to
2620: 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2630: 20 74 61 62 6c 65 20 22 6e 65 77 5f 58 22 20 74   table "new_X" t
2640: 68 61 74 20 69 73 20 69 6e 20 74 68 65 20 64 65  hat is in the de
2650: 73 69 72 65 64 0a 72 65 76 69 73 65 64 20 66 6f  sired.revised fo
2660: 72 6d 61 74 20 6f 66 20 74 61 62 6c 65 20 58 2e  rmat of table X.
2670: 20 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74    Make sure that
2680: 20 74 68 65 20 6e 61 6d 65 20 22 6e 65 77 5f 58   the name "new_X
2690: 22 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6c 6c 69  " does not colli
26a0: 64 65 0a 77 69 74 68 20 61 6e 79 20 65 78 69 73  de.with any exis
26b0: 74 69 6e 67 20 74 61 62 6c 65 20 6e 61 6d 65 2c  ting table name,
26c0: 20 6f 66 20 63 6f 75 72 73 65 2e 0a 0a 3c 6c 69   of course...<li
26d0: 3e 3c 70 3e 0a 54 72 61 6e 73 66 65 72 20 63 6f  ><p>.Transfer co
26e0: 6e 74 65 6e 74 20 66 72 6f 6d 20 58 20 69 6e 74  ntent from X int
26f0: 6f 20 6e 65 77 5f 58 20 75 73 69 6e 67 20 61 20  o new_X using a 
2700: 73 74 61 74 65 6d 65 6e 74 0a 6c 69 6b 65 3a 20  statement.like: 
2710: 49 4e 53 45 52 54 20 49 4e 54 4f 20 6e 65 77 5f  INSERT INTO new_
2720: 58 20 53 45 4c 45 43 54 20 2e 2e 2e 20 46 52 4f  X SELECT ... FRO
2730: 4d 20 58 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 44 72  M X...<li><p>.Dr
2740: 6f 70 20 74 68 65 20 6f 6c 64 20 74 61 62 6c 65  op the old table
2750: 20 58 3a 20 20 5b 44 52 4f 50 20 54 41 42 4c 45   X:  [DROP TABLE
2760: 20 7c 20 44 52 4f 50 20 54 41 42 4c 45 20 58 5d   | DROP TABLE X]
2770: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 68 61 6e 67  ...<li><p>.Chang
2780: 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 6e 65  e the name of ne
2790: 77 5f 58 20 74 6f 20 58 20 75 73 69 6e 67 3a 20  w_X to X using: 
27a0: 41 4c 54 45 52 20 54 41 42 4c 45 20 6e 65 77 5f  ALTER TABLE new_
27b0: 58 20 52 45 4e 41 4d 45 20 54 4f 20 58 2e 0a 0a  X RENAME TO X...
27c0: 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20 5b 43 52 45  <li><p>.Use [CRE
27d0: 41 54 45 20 49 4e 44 45 58 5d 2c 20 5b 43 52 45  ATE INDEX], [CRE
27e0: 41 54 45 20 54 52 49 47 47 45 52 5d 2c 20 61 6e  ATE TRIGGER], an
27f0: 64 20 5b 43 52 45 41 54 45 20 56 49 45 57 5d 0a  d [CREATE VIEW].
2800: 74 6f 20 72 65 63 6f 6e 73 74 72 75 63 74 20 69  to reconstruct i
2810: 6e 64 65 78 65 73 2c 20 74 72 69 67 67 65 72 73  ndexes, triggers
2820: 2c 20 61 6e 64 20 76 69 65 77 73 0a 61 73 73 6f  , and views.asso
2830: 63 69 61 74 65 64 20 77 69 74 68 20 74 61 62 6c  ciated with tabl
2840: 65 20 58 2e 20 20 50 65 72 68 61 70 73 20 75 73  e X.  Perhaps us
2850: 65 20 74 68 65 20 6f 6c 64 20 66 6f 72 6d 61 74  e the old format
2860: 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72 73   of the triggers
2870: 2c 0a 69 6e 64 65 78 65 73 2c 20 61 6e 64 20 76  ,.indexes, and v
2880: 69 65 77 73 20 73 61 76 65 64 20 66 72 6f 6d 20  iews saved from 
2890: 73 74 65 70 20 33 20 61 62 6f 76 65 20 61 73 20  step 3 above as 
28a0: 61 20 67 75 69 64 65 2c 20 6d 61 6b 69 6e 67 20  a guide, making 
28b0: 63 68 61 6e 67 65 73 0a 61 73 20 61 70 70 72 6f  changes.as appro
28c0: 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 61  priate for the a
28d0: 6c 74 65 72 61 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e  lteration...<li>
28e0: 3c 70 3e 49 66 20 61 6e 79 20 76 69 65 77 73 20  <p>If any views 
28f0: 72 65 66 65 72 20 74 6f 20 74 61 62 6c 65 20 58  refer to table X
2900: 20 69 6e 20 61 20 77 61 79 20 74 68 61 74 20 69   in a way that i
2910: 73 20 61 66 66 65 63 74 65 64 20 62 79 20 74 68  s affected by th
2920: 65 0a 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  e.schema change,
2930: 20 74 68 65 6e 20 64 72 6f 70 20 74 68 6f 73 65   then drop those
2940: 20 76 69 65 77 73 20 75 73 69 6e 67 20 5b 44 52   views using [DR
2950: 4f 50 20 56 49 45 57 5d 20 61 6e 64 20 72 65 63  OP VIEW] and rec
2960: 72 65 61 74 65 20 74 68 65 6d 0a 77 69 74 68 20  reate them.with 
2970: 77 68 61 74 65 76 65 72 20 63 68 61 6e 67 65 73  whatever changes
2980: 20 61 72 65 20 6e 65 63 65 73 73 61 72 79 20 74   are necessary t
2990: 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 74 68  o accommodate th
29a0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 0a  e schema change.
29b0: 75 73 69 6e 67 20 5b 43 52 45 41 54 45 20 56 49  using [CREATE VI
29c0: 45 57 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49 66  EW]...<li><p>.If
29d0: 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e   foreign key con
29e0: 73 74 72 61 69 6e 74 73 20 77 65 72 65 20 6f 72  straints were or
29f0: 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c 65 64  iginally enabled
2a00: 0a 74 68 65 6e 20 72 75 6e 20 5b 50 52 41 47 4d  .then run [PRAGM
2a10: 41 20 66 6f 72 65 69 67 6e 5f 6b 65 79 5f 63 68  A foreign_key_ch
2a20: 65 63 6b 5d 20 74 6f 20 76 65 72 69 66 79 20 74  eck] to verify t
2a30: 68 61 74 20 74 68 65 20 73 63 68 65 6d 61 0a 63  hat the schema.c
2a40: 68 61 6e 67 65 20 64 69 64 20 6e 6f 74 20 62 72  hange did not br
2a50: 65 61 6b 20 61 6e 79 20 66 6f 72 65 69 67 6e 20  eak any foreign 
2a60: 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e  key constraints.
2a70: 0a 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 6f 6d 6d 69  ...<li><p>.Commi
2a80: 74 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  t the transactio
2a90: 6e 20 73 74 61 72 74 65 64 20 69 6e 20 73 74 65  n started in ste
2aa0: 70 20 32 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49 66  p 2...<li><p>.If
2ab0: 20 66 6f 72 65 69 67 6e 20 6b 65 79 73 20 63 6f   foreign keys co
2ac0: 6e 73 74 72 61 69 6e 74 73 20 77 65 72 65 20 6f  nstraints were o
2ad0: 72 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c 65  riginally enable
2ae0: 64 2c 20 72 65 65 6e 61 62 6c 65 20 74 68 65 6d  d, reenable them
2af0: 20 6e 6f 77 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 74 63   now..</ol>..<tc
2b00: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 61  l>hd_fragment ca
2b10: 75 74 69 6f 6e 3c 2f 74 63 6c 3e 0a 3c 70 3e 0a  ution</tcl>.<p>.
2b20: 3c 62 3e 43 61 75 74 69 6f 6e 3a 3c 2f 62 3e 0a  <b>Caution:</b>.
2b30: 54 61 6b 65 20 63 61 72 65 20 74 6f 20 66 6f 6c  Take care to fol
2b40: 6c 6f 77 20 74 68 65 20 70 72 6f 63 65 64 75 72  low the procedur
2b50: 65 20 61 62 6f 76 65 20 70 72 65 63 69 73 65 6c  e above precisel
2b60: 79 2e 20 20 54 68 65 20 62 6f 78 65 73 20 62 65  y.  The boxes be
2b70: 6c 6f 77 0a 73 75 6d 6d 61 72 69 7a 65 20 74 77  low.summarize tw
2b80: 6f 20 70 72 6f 63 65 64 75 72 65 73 20 66 6f 72  o procedures for
2b90: 20 6d 6f 64 69 66 79 69 6e 67 20 61 20 74 61 62   modifying a tab
2ba0: 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  le definition.  
2bb0: 41 74 20 66 69 72 73 74 0a 67 6c 61 6e 63 65 2c  At first.glance,
2bc0: 20 74 68 65 79 20 62 6f 74 68 20 61 70 70 65 61   they both appea
2bd0: 72 20 74 6f 20 61 63 63 6f 6d 70 6c 69 73 68 20  r to accomplish 
2be0: 74 68 65 20 73 61 6d 65 20 74 68 69 6e 67 2e 20  the same thing. 
2bf0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 0a 70 72   However, the.pr
2c00: 6f 63 65 64 75 72 65 20 6f 6e 20 74 68 65 20 72  ocedure on the r
2c10: 69 67 68 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  ight does not al
2c20: 77 61 79 73 20 77 6f 72 6b 2c 20 65 73 70 65 63  ways work, espec
2c30: 69 61 6c 6c 79 20 77 69 74 68 20 74 68 65 0a 65  ially with the.e
2c40: 6e 68 61 6e 63 65 64 20 5b 72 65 6e 61 6d 65 20  nhanced [rename 
2c50: 74 61 62 6c 65 5d 20 63 61 70 61 62 69 6c 69 74  table] capabilit
2c60: 69 65 73 20 61 64 64 65 64 20 62 79 20 76 65 72  ies added by ver
2c70: 73 69 6f 6e 73 20 33 2e 32 35 2e 30 20 61 6e 64  sions 3.25.0 and
2c80: 0a 33 2e 32 36 2e 30 2e 20 20 49 6e 20 74 68 65  .3.26.0.  In the
2c90: 20 70 72 6f 63 65 64 75 72 65 20 6f 6e 20 74 68   procedure on th
2ca0: 65 20 72 69 67 68 74 2c 20 74 68 65 20 69 6e 69  e right, the ini
2cb0: 74 69 61 6c 20 72 65 6e 61 6d 65 20 6f 66 20 74  tial rename of t
2cc0: 68 65 0a 74 61 62 6c 65 20 74 6f 20 61 20 74 65  he.table to a te
2cd0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 6d 69 67  mporary name mig
2ce0: 68 74 20 63 6f 72 72 75 70 74 20 72 65 66 65 72  ht corrupt refer
2cf0: 65 6e 63 65 73 20 74 6f 20 74 68 61 74 20 74 61  ences to that ta
2d00: 62 6c 65 20 69 6e 0a 74 72 69 67 67 65 72 73 2c  ble in.triggers,
2d10: 20 76 69 65 77 73 2c 20 61 6e 64 20 66 6f 72 65   views, and fore
2d20: 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
2d30: 6e 74 73 2e 20 20 54 68 65 20 73 61 66 65 20 70  nts.  The safe p
2d40: 72 6f 63 65 64 75 72 65 20 6f 6e 0a 74 68 65 20  rocedure on.the 
2d50: 6c 65 66 74 20 63 6f 6e 73 74 72 75 63 74 73 20  left constructs 
2d60: 74 68 65 20 72 65 76 69 73 65 64 20 74 61 62 6c  the revised tabl
2d70: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 75 73 69  e definition usi
2d80: 6e 67 20 61 20 6e 65 77 20 74 65 6d 70 6f 72 61  ng a new tempora
2d90: 72 79 0a 6e 61 6d 65 2c 20 74 68 65 6e 20 72 65  ry.name, then re
2da0: 6e 61 6d 65 73 20 74 68 65 20 74 61 62 6c 65 20  names the table 
2db0: 69 6e 74 6f 20 69 74 73 20 66 69 6e 61 6c 20 6e  into its final n
2dc0: 61 6d 65 2c 20 77 68 69 63 68 20 64 6f 65 73 20  ame, which does 
2dd0: 6e 6f 74 20 62 72 65 61 6b 0a 6c 69 6e 6b 73 2e  not break.links.
2de0: 0a 0a 3c 63 65 6e 74 65 72 3e 0a 3c 74 61 62 6c  ..<center>.<tabl
2df0: 65 20 62 6f 72 64 65 72 3d 22 31 22 20 63 65 6c  e border="1" cel
2e00: 6c 70 61 64 64 69 6e 67 3d 22 31 30 22 20 63 65  lpadding="10" ce
2e10: 6c 6c 73 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c  llspacing="0">.<
2e20: 74 72 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22  tr>.<td valign="
2e30: 74 6f 70 22 3e 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 43  top">.<ol>.<li>C
2e40: 72 65 61 74 65 20 6e 65 77 20 74 61 62 6c 65 0a  reate new table.
2e50: 3c 6c 69 3e 43 6f 70 79 20 64 61 74 61 0a 3c 6c  <li>Copy data.<l
2e60: 69 3e 44 72 6f 70 20 6f 6c 64 20 74 61 62 6c 65  i>Drop old table
2e70: 0a 3c 6c 69 3e 52 65 6e 61 6d 65 20 6e 65 77 20  .<li>Rename new 
2e80: 69 6e 74 6f 20 6f 6c 64 0a 3c 2f 6f 6c 3e 0a 3c  into old.</ol>.<
2e90: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
2ea0: 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 52 65 6e 61 6d 65  .<ol>.<li>Rename
2eb0: 20 6f 6c 64 20 74 61 62 6c 65 0a 3c 6c 69 3e 43   old table.<li>C
2ec0: 72 65 61 74 65 20 6e 65 77 20 74 61 62 6c 65 0a  reate new table.
2ed0: 3c 6c 69 3e 43 6f 70 79 20 64 61 74 61 0a 3c 6c  <li>Copy data.<l
2ee0: 69 3e 44 72 6f 70 20 6f 6c 64 20 74 61 62 6c 65  i>Drop old table
2ef0: 0a 3c 2f 6f 6c 3e 0a 3c 74 72 3e 0a 3c 74 68 3e  .</ol>.<tr>.<th>
2f00: 26 75 61 72 72 3b 3c 62 72 3e 43 6f 72 72 65 63  &uarr;<br>Correc
2f10: 74 0a 3c 74 68 3e 26 75 61 72 72 3b 3c 62 72 3e  t.<th>&uarr;<br>
2f20: 49 6e 63 6f 72 72 65 63 74 0a 3c 2f 74 61 62 6c  Incorrect.</tabl
2f30: 65 3e 0a 3c 2f 63 65 6e 74 65 72 3e 0a 0a 3c 70  e>.</center>..<p
2f40: 3e 54 68 65 20 31 32 2d 73 74 65 70 20 5b 67 65  >The 12-step [ge
2f50: 6e 65 72 61 6c 69 7a 65 64 20 41 4c 54 45 52 20  neralized ALTER 
2f60: 54 41 42 4c 45 20 70 72 6f 63 65 64 75 72 65 5d  TABLE procedure]
2f70: 0a 61 62 6f 76 65 20 77 69 6c 6c 20 77 6f 72 6b  .above will work
2f80: 20 65 76 65 6e 20 69 66 20 74 68 65 0a 73 63 68   even if the.sch
2f90: 65 6d 61 20 63 68 61 6e 67 65 20 63 61 75 73 65  ema change cause
2fa0: 73 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f  s the informatio
2fb0: 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  n stored in the 
2fc0: 74 61 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 2e  table to change.
2fd0: 0a 53 6f 20 74 68 65 20 66 75 6c 6c 20 31 32 2d  .So the full 12-
2fe0: 73 74 65 70 20 70 72 6f 63 65 64 75 72 65 20 61  step procedure a
2ff0: 62 6f 76 65 20 69 73 20 61 70 70 72 6f 70 72 69  bove is appropri
3000: 61 74 65 20 66 6f 72 20 64 72 6f 70 70 69 6e 67  ate for dropping
3010: 20 61 20 63 6f 6c 75 6d 6e 2c 0a 63 68 61 6e 67   a column,.chang
3020: 69 6e 67 20 74 68 65 20 6f 72 64 65 72 20 6f 66  ing the order of
3030: 20 63 6f 6c 75 6d 6e 73 2c 20 61 64 64 69 6e 67   columns, adding
3040: 20 6f 72 20 72 65 6d 6f 76 69 6e 67 20 61 20 55   or removing a U
3050: 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74  NIQUE constraint
3060: 0a 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  .or PRIMARY KEY,
3070: 20 61 64 64 69 6e 67 20 43 48 45 43 4b 20 6f 72   adding CHECK or
3080: 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72 20   FOREIGN KEY or 
3090: 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
30a0: 69 6e 74 73 2c 0a 6f 72 20 63 68 61 6e 67 69 6e  ints,.or changin
30b0: 67 20 74 68 65 20 64 61 74 61 74 79 70 65 20 66  g the datatype f
30c0: 6f 72 20 61 20 63 6f 6c 75 6d 6e 2c 20 66 6f 72  or a column, for
30d0: 20 65 78 61 6d 70 6c 65 2e 20 20 48 6f 77 65 76   example.  Howev
30e0: 65 72 2c 20 61 20 73 69 6d 70 6c 65 72 0a 61 6e  er, a simpler.an
30f0: 64 20 66 61 73 74 65 72 20 70 72 6f 63 65 64 75  d faster procedu
3100: 72 65 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  re can optionall
3110: 79 20 62 65 20 75 73 65 64 20 66 6f 72 0a 73 6f  y be used for.so
3120: 6d 65 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  me changes that 
3130: 64 6f 20 6e 6f 20 61 66 66 65 63 74 20 74 68 65  do no affect the
3140: 20 6f 6e 2d 64 69 73 6b 20 63 6f 6e 74 65 6e 74   on-disk content
3150: 20 69 6e 20 61 6e 79 20 77 61 79 2e 0a 54 68 65   in any way..The
3160: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 69 6d 70 6c   following simpl
3170: 65 72 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  er procedure is 
3180: 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
3190: 72 65 6d 6f 76 69 6e 67 0a 43 48 45 43 4b 20 6f  removing.CHECK o
31a0: 72 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72  r FOREIGN KEY or
31b0: 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
31c0: 61 69 6e 74 73 2c 0a 6f 72 20 61 64 64 69 6e 67  aints,.or adding
31d0: 2c 20 72 65 6d 6f 76 69 6e 67 2c 20 6f 72 20 63  , removing, or c
31e0: 68 61 6e 67 69 6e 67 20 64 65 66 61 75 6c 74 20  hanging default 
31f0: 76 61 6c 75 65 73 20 6f 6e 0a 61 20 63 6f 6c 75  values on.a colu
3200: 6d 6e 2e 0a 0a 3c 6f 6c 3e 0a 3c 6c 49 3e 3c 70  mn...<ol>.<lI><p
3210: 3e 20 53 74 61 72 74 20 61 20 74 72 61 6e 73 61  > Start a transa
3220: 63 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e 20  ction...<li><p> 
3230: 52 75 6e 20 5b 50 52 41 47 4d 41 20 73 63 68 65  Run [PRAGMA sche
3240: 6d 61 5f 76 65 72 73 69 6f 6e 5d 20 74 6f 20 64  ma_version] to d
3250: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 63 75 72  etermine the cur
3260: 72 65 6e 74 20 73 63 68 65 6d 61 0a 76 65 72 73  rent schema.vers
3270: 69 6f 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ion number.  Thi
3280: 73 20 6e 75 6d 62 65 72 20 77 69 6c 6c 20 62 65  s number will be
3290: 20 6e 65 65 64 65 64 20 66 6f 72 20 73 74 65 70   needed for step
32a0: 20 36 20 62 65 6c 6f 77 2e 0a 0a 3c 6c 69 3e 3c   6 below...<li><
32b0: 70 3e 20 41 63 74 69 76 61 74 65 20 73 63 68 65  p> Activate sche
32c0: 6d 61 20 65 64 69 74 69 6e 67 20 75 73 69 6e 67  ma editing using
32d0: 20 0a 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62   .[PRAGMA writab
32e0: 6c 65 5f 73 63 68 65 6d 61 20 7c 20 50 52 41 47  le_schema | PRAG
32f0: 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65  MA writable_sche
3300: 6d 61 3d 4f 4e 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e  ma=ON]...<li><p>
3310: 20 52 75 6e 20 61 6e 20 5b 55 50 44 41 54 45 5d   Run an [UPDATE]
3320: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 68   statement to ch
3330: 61 6e 67 65 20 74 68 65 20 64 65 66 69 6e 69 74  ange the definit
3340: 69 6f 6e 20 6f 66 20 74 61 62 6c 65 20 58 0a 69  ion of table X.i
3350: 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 6d 61  n the [sqlite_ma
3360: 73 74 65 72 20 74 61 62 6c 65 5d 3a 20 0a 55 50  ster table]: .UP
3370: 44 41 54 45 20 73 71 6c 69 74 65 5f 6d 61 73 74  DATE sqlite_mast
3380: 65 72 20 53 45 54 20 73 71 6c 3d 2e 2e 2e 20 57  er SET sql=... W
3390: 48 45 52 45 20 74 79 70 65 3d 27 74 61 62 6c 65  HERE type='table
33a0: 27 20 41 4e 44 20 6e 61 6d 65 3d 27 58 27 3b 0a  ' AND name='X';.
33b0: 3c 70 3e 3c 65 6d 3e 43 61 75 74 69 6f 6e 3a 3c  <p><em>Caution:<
33c0: 2f 65 6d 3e 20 20 4d 61 6b 69 6e 67 20 61 20 63  /em>  Making a c
33d0: 68 61 6e 67 65 20 74 6f 20 74 68 65 20 73 71 6c  hange to the sql
33e0: 69 74 65 5f 6d 61 73 74 65 72 20 74 61 62 6c 65  ite_master table
33f0: 20 6c 69 6b 65 20 74 68 69 73 20 77 69 6c 6c 0a   like this will.
3400: 72 65 6e 64 65 72 20 74 68 65 20 64 61 74 61 62  render the datab
3410: 61 73 65 20 63 6f 72 72 75 70 74 20 61 6e 64 20  ase corrupt and 
3420: 75 6e 72 65 61 64 61 62 6c 65 20 69 66 20 74 68  unreadable if th
3430: 65 20 63 68 61 6e 67 65 20 63 6f 6e 74 61 69 6e  e change contain
3440: 73 0a 61 20 73 79 6e 74 61 78 20 65 72 72 6f 72  s.a syntax error
3450: 2e 20 20 49 74 20 69 73 20 73 75 67 67 65 73 74  .  It is suggest
3460: 65 64 20 74 68 61 74 20 63 61 72 65 66 75 6c 20  ed that careful 
3470: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 55  testing of the U
3480: 50 44 41 54 45 0a 73 74 61 74 65 6d 65 6e 74 20  PDATE.statement 
3490: 62 65 20 64 6f 6e 65 20 6f 6e 20 61 20 73 65 70  be done on a sep
34a0: 61 72 61 74 65 20 62 6c 61 6e 6b 20 64 61 74 61  arate blank data
34b0: 62 61 73 65 20 70 72 69 6f 72 20 74 6f 20 75 73  base prior to us
34c0: 69 6e 67 20 69 74 20 6f 6e 0a 61 20 64 61 74 61  ing it on.a data
34d0: 62 61 73 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  base containing 
34e0: 69 6d 70 6f 72 74 61 6e 74 20 64 61 74 61 2e 0a  important data..
34f0: 0a 3c 6c 69 3e 3c 70 3e 20 49 66 20 74 68 65 20  .<li><p> If the 
3500: 63 68 61 6e 67 65 20 74 6f 20 74 61 62 6c 65 20  change to table 
3510: 58 20 61 6c 73 6f 20 61 66 66 65 63 74 73 20 6f  X also affects o
3520: 74 68 65 72 20 74 61 62 6c 65 73 20 6f 72 20 69  ther tables or i
3530: 6e 64 65 78 65 73 20 6f 72 0a 74 72 69 67 67 65  ndexes or.trigge
3540: 72 73 20 61 72 65 20 76 69 65 77 73 20 77 69 74  rs are views wit
3550: 68 69 6e 20 73 63 68 65 6d 61 2c 20 74 68 65 6e  hin schema, then
3560: 20 72 75 6e 20 5b 55 50 44 41 54 45 5d 20 73 74   run [UPDATE] st
3570: 61 74 65 6d 65 6e 74 73 20 74 6f 20 6d 6f 64 69  atements to modi
3580: 66 79 0a 74 68 6f 73 65 20 6f 74 68 65 72 20 74  fy.those other t
3590: 61 62 6c 65 73 20 69 6e 64 65 78 65 73 20 61 6e  ables indexes an
35a0: 64 20 76 69 65 77 73 20 74 6f 6f 2e 20 20 46 6f  d views too.  Fo
35b0: 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  r example, if th
35c0: 65 20 6e 61 6d 65 20 6f 66 0a 61 20 63 6f 6c 75  e name of.a colu
35d0: 6d 6e 20 63 68 61 6e 67 65 73 2c 20 61 6c 6c 20  mn changes, all 
35e0: 46 4f 52 45 49 47 4e 20 4b 45 59 20 63 6f 6e 73  FOREIGN KEY cons
35f0: 74 72 61 69 6e 74 73 2c 20 74 72 69 67 67 65 72  traints, trigger
3600: 73 2c 20 69 6e 64 65 78 65 73 2c 20 61 6e 64 0a  s, indexes, and.
3610: 76 69 65 77 73 20 74 68 61 74 20 72 65 66 65 72  views that refer
3620: 20 74 6f 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   to that column 
3630: 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64  must be modified
3640: 2e 0a 3c 70 3e 3c 65 6d 3e 43 61 75 74 69 6f 6e  ..<p><em>Caution
3650: 3a 3c 2f 65 6d 3e 20 20 4f 6e 63 65 20 61 67 61  :</em>  Once aga
3660: 69 6e 2c 20 6d 61 6b 69 6e 67 20 63 68 61 6e 67  in, making chang
3670: 65 73 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  es to the sqlite
3680: 5f 6d 61 73 74 65 72 20 0a 74 61 62 6c 65 20 6c  _master .table l
3690: 69 6b 65 20 74 68 69 73 20 77 69 6c 6c 20 72 65  ike this will re
36a0: 6e 64 65 72 20 74 68 65 20 64 61 74 61 62 61 73  nder the databas
36b0: 65 20 63 6f 72 72 75 70 74 20 61 6e 64 20 75 6e  e corrupt and un
36c0: 72 65 61 64 61 62 6c 65 20 69 66 20 74 68 65 20  readable if the 
36d0: 0a 63 68 61 6e 67 65 20 63 6f 6e 74 61 69 6e 73  .change contains
36e0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 43 61 72 65   an error.  Care
36f0: 66 75 6c 6c 79 20 74 65 73 74 20 74 68 69 73 20  fully test this 
3700: 65 6e 74 69 72 65 20 70 72 6f 63 65 64 75 72 65  entire procedure
3710: 0a 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74  .on a separate t
3720: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 72 69  est database pri
3730: 6f 72 20 74 6f 20 75 73 69 6e 67 20 69 74 20 6f  or to using it o
3740: 6e 0a 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n.a database con
3750: 74 61 69 6e 69 6e 67 20 69 6d 70 6f 72 74 61 6e  taining importan
3760: 74 20 64 61 74 61 20 61 6e 64 2f 6f 72 20 6d 61  t data and/or ma
3770: 6b 65 20 62 61 63 6b 75 70 20 63 6f 70 69 65 73  ke backup copies
3780: 20 6f 66 0a 69 6d 70 6f 72 74 61 6e 74 20 64 61   of.important da
3790: 74 61 62 61 73 65 73 20 70 72 69 6f 72 20 74 6f  tabases prior to
37a0: 20 72 75 6e 6e 69 6e 67 20 74 68 69 73 20 70 72   running this pr
37b0: 6f 63 65 64 75 72 65 2e 0a 0a 3c 6c 69 3e 3c 70  ocedure...<li><p
37c0: 3e 20 49 6e 63 72 65 6d 65 6e 74 20 74 68 65 20  > Increment the 
37d0: 73 63 68 65 6d 61 20 76 65 72 73 69 6f 6e 20 6e  schema version n
37e0: 75 6d 62 65 72 20 75 73 69 6e 67 0a 5b 50 52 41  umber using.[PRA
37f0: 47 4d 41 20 73 63 68 65 6d 61 5f 76 65 72 73 69  GMA schema_versi
3800: 6f 6e 20 7c 20 50 52 41 47 4d 41 20 73 63 68 65  on | PRAGMA sche
3810: 6d 61 5f 76 65 72 73 69 6f 6e 3d 58 5d 20 77 68  ma_version=X] wh
3820: 65 72 65 20 58 20 69 73 20 6f 6e 65 0a 6d 6f 72  ere X is one.mor
3830: 65 20 74 68 61 6e 20 74 68 65 20 6f 6c 64 20 73  e than the old s
3840: 63 68 65 6d 61 20 76 65 72 73 69 6f 6e 20 6e 75  chema version nu
3850: 6d 62 65 72 20 66 6f 75 6e 64 20 69 6e 20 73 74  mber found in st
3860: 65 70 20 32 20 61 62 6f 76 65 2e 0a 0a 3c 6c 69  ep 2 above...<li
3870: 3e 3c 70 3e 20 44 69 73 61 62 6c 65 20 73 63 68  ><p> Disable sch
3880: 65 6d 61 20 65 64 69 74 69 6e 67 20 75 73 69 6e  ema editing usin
3890: 67 20 0a 5b 50 52 41 47 4d 41 20 77 72 69 74 61  g .[PRAGMA writa
38a0: 62 6c 65 5f 73 63 68 65 6d 61 20 7c 20 50 52 41  ble_schema | PRA
38b0: 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
38c0: 65 6d 61 3d 4f 46 46 5d 2e 0a 0a 3c 6c 69 3e 3c  ema=OFF]...<li><
38d0: 70 3e 20 28 4f 70 74 69 6f 6e 61 6c 29 20 52 75  p> (Optional) Ru
38e0: 6e 20 5b 50 52 41 47 4d 41 20 69 6e 74 65 67 72  n [PRAGMA integr
38f0: 69 74 79 5f 63 68 65 63 6b 5d 20 74 6f 20 76 65  ity_check] to ve
3900: 72 69 66 79 20 74 68 61 74 20 74 68 65 0a 73 63  rify that the.sc
3910: 68 65 6d 61 20 63 68 61 6e 67 65 73 20 64 69 64  hema changes did
3920: 20 6e 6f 74 20 64 61 6d 61 67 65 20 74 68 65 20   not damage the 
3930: 64 61 74 61 62 61 73 65 2e 0a 0a 3c 6c 69 3e 3c  database...<li><
3940: 70 3e 20 43 6f 6d 6d 69 74 20 74 68 65 20 74 72  p> Commit the tr
3950: 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 72 74 65  ansaction starte
3960: 64 20 6f 6e 20 73 74 65 70 20 31 20 61 62 6f 76  d on step 1 abov
3970: 65 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 49 66 20  e..</ol>..<p>If 
3980: 73 6f 6d 65 20 66 75 74 75 72 65 20 76 65 72 73  some future vers
3990: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 61 64  ion of SQLite ad
39a0: 64 73 20 6e 65 77 20 41 4c 54 45 52 20 54 41 42  ds new ALTER TAB
39b0: 4c 45 20 63 61 70 61 62 69 6c 69 74 69 65 73 2c  LE capabilities,
39c0: 20 0a 74 68 6f 73 65 20 63 61 70 61 62 69 6c 69   .those capabili
39d0: 74 69 65 73 20 77 69 6c 6c 20 76 65 72 79 20 6c  ties will very l
39e0: 69 6b 65 6c 79 20 75 73 65 20 6f 6e 65 20 6f 66  ikely use one of
39f0: 20 74 68 65 20 74 77 6f 20 70 72 6f 63 65 64 75   the two procedu
3a00: 72 65 73 0a 6f 75 74 6c 69 6e 65 64 20 61 62 6f  res.outlined abo
3a10: 76 65 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ve...<tcl>hd_fra
3a20: 67 6d 65 6e 74 20 61 6c 74 65 72 74 61 62 6c 65  gment altertable
3a30: 69 73 68 61 72 64 20 7b 77 68 79 20 41 4c 54 45  ishard {why ALTE
3a40: 52 20 54 41 42 4c 45 20 69 73 20 73 6f 20 64 69  R TABLE is so di
3a50: 66 66 69 63 75 6c 74 7d 3c 2f 74 63 6c 3e 0a 3c  fficult}</tcl>.<
3a60: 68 33 3e 57 68 79 20 41 4c 54 45 52 20 54 41 42  h3>Why ALTER TAB
3a70: 4c 45 20 69 73 20 73 75 63 68 20 61 20 70 72 6f  LE is such a pro
3a80: 62 6c 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 3c  blem for SQLite<
3a90: 2f 68 33 3e 0a 0a 3c 70 3e 4d 6f 73 74 20 53 51  /h3>..<p>Most SQ
3aa0: 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  L database engin
3ab0: 65 73 20 73 74 6f 72 65 20 74 68 65 20 73 63 68  es store the sch
3ac0: 65 6d 61 20 61 6c 72 65 61 64 79 20 70 61 72 73  ema already pars
3ad0: 65 64 20 69 6e 74 6f 0a 76 61 72 69 6f 75 73 20  ed into.various 
3ae0: 73 79 73 74 65 6d 20 74 61 62 6c 65 73 2e 20 20  system tables.  
3af0: 4f 6e 20 74 68 6f 73 65 20 64 61 74 61 62 61 73  On those databas
3b00: 65 20 65 6e 67 69 6e 65 73 2c 20 41 4c 54 45 52  e engines, ALTER
3b10: 20 54 41 42 4c 45 20 6d 65 72 65 6c 79 20 0a 68   TABLE merely .h
3b20: 61 73 20 74 6f 20 6d 61 6b 65 20 6d 6f 64 69 66  as to make modif
3b30: 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
3b40: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 79  corresponding sy
3b50: 73 74 65 6d 20 74 61 62 6c 65 73 2e 0a 0a 3c 70  stem tables...<p
3b60: 3e 53 51 4c 69 74 65 20 69 73 20 64 69 66 66 65  >SQLite is diffe
3b70: 72 65 6e 74 20 69 6e 20 74 68 61 74 20 69 74 20  rent in that it 
3b80: 73 74 6f 72 65 73 20 74 68 65 20 73 63 68 65 6d  stores the schem
3b90: 61 0a 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  a.in the [sqlite
3ba0: 5f 6d 61 73 74 65 72 5d 20 74 61 62 6c 65 20 61  _master] table a
3bb0: 73 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  s the original t
3bc0: 65 78 74 20 6f 66 20 74 68 65 20 43 52 45 41 54  ext of the CREAT
3bd0: 45 0a 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  E.statements tha
3be0: 74 20 64 65 66 69 6e 65 20 74 68 65 20 73 63 68  t define the sch
3bf0: 65 6d 61 2e 20 20 48 65 6e 63 65 20 41 4c 54 45  ema.  Hence ALTE
3c00: 52 20 54 41 42 4c 45 20 6e 65 65 64 73 0a 74 6f  R TABLE needs.to
3c10: 20 72 65 76 69 73 65 20 74 68 65 20 74 65 78 74   revise the text
3c20: 20 6f 66 20 74 68 65 20 43 52 45 41 54 45 20 73   of the CREATE s
3c30: 74 61 74 65 6d 65 6e 74 2e 20 20 44 6f 69 6e 67  tatement.  Doing
3c40: 0a 73 6f 20 63 61 6e 20 62 65 20 74 72 69 63 6b  .so can be trick
3c50: 79 20 66 6f 72 20 63 65 72 74 61 69 6e 20 22 63  y for certain "c
3c60: 72 65 61 74 69 76 65 22 20 73 63 68 65 6d 61 20  reative" schema 
3c70: 64 65 73 69 67 6e 73 2e 0a 0a 3c 70 3e 54 68 65  designs...<p>The
3c80: 20 53 51 4c 69 74 65 20 61 70 70 72 6f 61 63 68   SQLite approach
3c90: 20 6f 66 20 73 74 6f 72 69 6e 67 20 74 68 65 20   of storing the 
3ca0: 73 63 68 65 6d 61 20 61 73 20 74 65 78 74 20 68  schema as text h
3cb0: 61 73 20 61 64 76 61 6e 74 61 67 65 73 0a 66 6f  as advantages.fo
3cc0: 72 20 61 6e 20 65 6d 62 65 64 64 65 64 20 72 65  r an embedded re
3cd0: 6c 61 74 69 6f 6e 61 6c 20 64 61 74 61 62 61 73  lational databas
3ce0: 65 2e 20 20 46 6f 72 20 6f 6e 65 2c 20 69 74 20  e.  For one, it 
3cf0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 73  means that the.s
3d00: 63 68 65 6d 61 20 74 61 6b 65 73 20 75 70 20 6c  chema takes up l
3d10: 65 73 73 20 73 70 61 63 65 20 69 6e 20 74 68 65  ess space in the
3d20: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
3d30: 20 54 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   This is importa
3d40: 6e 74 0a 73 69 6e 63 65 20 61 20 63 6f 6d 6d 6f  nt.since a commo
3d50: 6e 20 53 51 4c 69 74 65 20 75 73 61 67 65 20 70  n SQLite usage p
3d60: 61 74 74 65 72 6e 20 69 73 20 74 6f 20 68 61 76  attern is to hav
3d70: 65 20 6d 61 6e 79 20 73 6d 61 6c 6c 2c 0a 73 65  e many small,.se
3d80: 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 20  parate database 
3d90: 66 69 6c 65 73 20 69 6e 73 74 65 61 64 20 6f 66  files instead of
3da0: 20 70 75 74 74 69 6e 67 20 65 76 65 72 79 74 68   putting everyth
3db0: 69 6e 67 20 69 6e 20 6f 6e 65 0a 62 69 67 20 67  ing in one.big g
3dc0: 6c 6f 62 61 6c 20 64 61 74 61 62 61 73 65 20 66  lobal database f
3dd0: 69 6c 65 2c 20 77 68 69 63 68 20 69 73 20 74 68  ile, which is th
3de0: 65 20 75 73 75 61 6c 20 61 70 70 72 6f 61 63 68  e usual approach
3df0: 20 66 6f 72 20 63 6c 69 65 6e 74 2f 73 65 72 76   for client/serv
3e00: 65 72 0a 64 61 74 61 62 61 73 65 20 65 6e 67 69  er.database engi
3e10: 6e 65 73 2e 0a 53 69 6e 63 65 20 74 68 65 20 73  nes..Since the s
3e20: 63 68 65 6d 61 20 69 73 20 64 75 70 6c 69 63 61  chema is duplica
3e30: 74 65 64 20 69 6e 20 65 61 63 68 20 73 65 70 61  ted in each sepa
3e40: 72 61 74 65 20 64 61 74 61 62 61 73 65 20 66 69  rate database fi
3e50: 6c 65 2c 20 69 74 20 69 73 0a 69 6d 70 6f 72 74  le, it is.import
3e60: 61 6e 74 20 74 6f 20 6b 65 65 70 20 74 68 65 20  ant to keep the 
3e70: 73 63 68 65 6d 61 20 72 65 70 72 65 73 65 6e 74  schema represent
3e80: 61 74 69 6f 6e 20 63 6f 6d 70 61 63 74 2e 0a 0a  ation compact...
3e90: 3c 70 3e 53 74 6f 72 69 6e 67 20 74 68 65 20 73  <p>Storing the s
3ea0: 63 68 65 6d 61 20 61 73 20 74 65 78 74 20 72 61  chema as text ra
3eb0: 74 68 65 72 20 74 68 61 6e 20 61 73 20 70 61 72  ther than as par
3ec0: 73 65 64 20 74 61 62 6c 65 73 20 61 6c 73 6f 0a  sed tables also.
3ed0: 67 69 76 65 20 66 6c 65 78 69 62 69 6c 69 74 79  give flexibility
3ee0: 20 74 6f 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   to the implemen
3ef0: 74 61 74 69 6f 6e 2e 20 20 53 69 6e 63 65 20 74  tation.  Since t
3f00: 68 65 20 69 6e 74 65 72 6e 61 6c 20 70 61 72 73  he internal pars
3f10: 65 0a 6f 66 20 74 68 65 20 73 63 68 65 6d 61 20  e.of the schema 
3f20: 69 73 20 72 65 67 65 6e 65 72 61 74 65 64 20 65  is regenerated e
3f30: 61 63 68 20 74 69 6d 65 20 74 68 65 20 64 61 74  ach time the dat
3f40: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 2c  abase is opened,
3f50: 20 74 68 65 0a 69 6e 74 65 72 6e 61 6c 20 72 65   the.internal re
3f60: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
3f70: 74 68 65 20 73 63 68 65 6d 61 20 63 61 6e 20 63  the schema can c
3f80: 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 72  hange from one r
3f90: 65 6c 65 61 73 65 0a 74 6f 20 74 68 65 20 6e 65  elease.to the ne
3fa0: 78 74 2e 20 20 54 68 69 73 20 69 73 20 69 6d 70  xt.  This is imp
3fb0: 6f 72 74 61 6e 74 2c 20 61 73 20 73 6f 6d 65 74  ortant, as somet
3fc0: 69 6d 65 73 20 6e 65 77 20 66 65 61 74 75 72 65  imes new feature
3fd0: 73 20 72 65 71 75 69 72 65 0a 65 6e 68 61 6e 63  s require.enhanc
3fe0: 65 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 69 6e  ements to the in
3ff0: 74 65 72 6e 61 6c 20 73 63 68 65 6d 61 20 72 65  ternal schema re
4000: 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20 20 43  presentation.  C
4010: 68 61 6e 67 69 6e 67 20 74 68 65 0a 69 6e 74 65  hanging the.inte
4020: 72 6e 61 6c 20 73 63 68 65 6d 61 20 72 65 70 72  rnal schema repr
4030: 65 73 65 6e 74 61 74 69 6f 6e 20 77 6f 75 6c 64  esentation would
4040: 20 62 65 20 6d 75 63 68 20 6d 6f 72 65 20 64 69   be much more di
4050: 66 66 69 63 75 6c 74 20 69 66 20 74 68 65 0a 73  fficult if the.s
4060: 63 68 65 6d 61 20 72 65 70 72 65 73 65 6e 74 61  chema representa
4070: 74 69 6f 6e 20 77 61 73 20 65 78 70 6f 73 65 64  tion was exposed
4080: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4090: 20 66 69 6c 65 2e 20 20 53 6f 2c 20 69 6e 20 6f   file.  So, in o
40a0: 74 68 65 72 0a 77 6f 72 64 73 2c 20 73 74 6f 72  ther.words, stor
40b0: 69 6e 67 20 74 68 65 20 73 63 68 65 6d 61 20 61  ing the schema a
40c0: 73 20 74 65 78 74 20 68 65 6c 70 73 20 6d 61 69  s text helps mai
40d0: 6e 74 61 69 6e 20 62 61 63 6b 77 61 72 64 73 20  ntain backwards 
40e0: 0a 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20  .compatibility, 
40f0: 61 6e 64 20 68 65 6c 70 73 20 65 6e 73 75 72 65  and helps ensure
4100: 20 74 68 61 74 20 6f 6c 64 65 72 20 64 61 74 61   that older data
4110: 62 61 73 65 20 66 69 6c 65 73 20 63 61 6e 20 62  base files can b
4120: 65 0a 72 65 61 64 20 61 6e 64 20 77 72 69 74 74  e.read and writt
4130: 65 6e 20 62 79 20 6e 65 77 65 72 20 76 65 72 73  en by newer vers
4140: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
4150: 0a 3c 70 3e 53 74 6f 72 69 6e 67 20 74 68 65 20  .<p>Storing the 
4160: 73 63 68 65 6d 61 20 61 20 74 65 78 74 20 61 6c  schema a text al
4170: 73 6f 20 6d 61 6b 65 73 20 74 68 65 20 0a 5b 53  so makes the .[S
4180: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
4190: 69 6c 65 20 66 6f 72 6d 61 74 5d 20 65 61 73 69  ile format] easi
41a0: 65 72 20 74 6f 20 64 65 66 69 6e 65 2c 20 64 6f  er to define, do
41b0: 63 75 6d 65 6e 74 2c 20 61 6e 64 20 0a 75 6e 64  cument, and .und
41c0: 65 72 73 74 61 6e 64 2e 20 54 68 69 73 20 68 65  erstand. This he
41d0: 6c 70 73 20 6d 61 6b 65 20 53 51 4c 69 74 65 20  lps make SQLite 
41e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 61  database files a
41f0: 0a 5b 72 65 63 6f 6d 6d 65 6e 64 65 64 20 73 74  .[recommended st
4200: 6f 72 61 67 65 20 66 6f 72 6d 61 74 5d 20 66 6f  orage format] fo
4210: 72 20 6c 6f 6e 67 2d 74 65 72 6d 20 61 72 63 68  r long-term arch
4220: 69 76 69 6e 67 20 6f 66 20 64 61 74 61 2e 0a 0a  iving of data...
4230: 3c 70 3e 54 68 65 20 64 6f 77 6e 73 69 64 65 20  <p>The downside 
4240: 6f 66 20 73 74 6f 72 69 6e 67 20 73 63 68 65 6d  of storing schem
4250: 61 20 61 20 74 65 78 74 20 69 73 20 74 68 61 74  a a text is that
4260: 20 69 74 20 63 61 6e 20 6d 61 6b 65 0a 74 68 65   it can make.the
4270: 20 73 63 68 65 6d 61 20 74 72 69 63 6b 79 20 74   schema tricky t
4280: 6f 20 6d 6f 64 69 66 79 2e 20 20 41 6e 64 20 66  o modify.  And f
4290: 6f 72 20 74 68 61 74 20 72 65 61 73 6f 6e 2c 20  or that reason, 
42a0: 74 68 65 20 41 4c 54 45 52 20 54 41 42 4c 45 0a  the ALTER TABLE.
42b0: 73 75 70 70 6f 72 74 20 69 6e 20 53 51 4c 69 74  support in SQLit
42c0: 65 20 68 61 73 20 74 72 61 64 69 74 69 6f 6e 61  e has traditiona
42d0: 6c 6c 79 20 6c 61 67 67 65 64 20 62 65 68 69 6e  lly lagged behin
42e0: 64 20 6f 74 68 65 72 20 53 51 4c 0a 64 61 74 61  d other SQL.data
42f0: 62 61 73 65 20 65 6e 67 69 6e 65 73 20 74 68 61  base engines tha
4300: 74 20 73 74 6f 72 65 20 74 68 65 69 72 20 73 63  t store their sc
4310: 68 65 6d 61 73 20 61 73 20 70 61 72 73 65 64 20  hemas as parsed 
4320: 73 79 73 74 65 6d 20 74 61 62 6c 65 73 0a 74 68  system tables.th
4330: 61 74 20 61 72 65 20 65 61 73 69 65 72 20 74 6f  at are easier to
4340: 20 6d 6f 64 69 66 79 2e 0a 0a 0a 0a 3c 74 63 6c   modify.....<tcl
4350: 3e 0a 23 20 20 4f 6e 65 20 6f 66 20 74 68 65 20  >.#  One of the 
4360: 72 65 61 73 6f 6e 73 20 74 68 61 74 0a 23 20 53  reasons that.# S
4370: 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63  QLite does not c
4380: 75 72 72 65 6e 74 6c 79 20 73 75 70 70 6f 72 74  urrently support
4390: 20 6d 6f 72 65 20 41 4c 54 45 52 20 54 41 42 4c   more ALTER TABL
43a0: 45 20 63 61 70 61 62 69 6c 69 74 69 65 73 20 69  E capabilities i
43b0: 73 20 74 68 61 74 0a 23 20 74 68 65 20 70 72 6f  s that.# the pro
43c0: 63 65 64 75 72 65 20 73 68 6f 77 6e 20 61 62 6f  cedure shown abo
43d0: 76 65 20 69 73 20 64 69 66 66 69 63 75 6c 74 20  ve is difficult 
43e0: 74 6f 20 61 75 74 6f 6d 61 74 65 20 66 6f 72 20  to automate for 
43f0: 61 6e 20 61 72 62 69 74 72 61 72 79 20 73 63 68  an arbitrary sch
4400: 65 6d 61 2e 0a 23 20 50 61 72 74 69 63 75 6c 61  ema..# Particula
4410: 72 6c 79 20 74 72 6f 75 62 6c 65 73 6f 6d 65 20  rly troublesome 
4420: 61 72 65 61 73 20 61 72 65 20 69 64 65 6e 74 69  areas are identi
4430: 66 79 69 6e 67 20 61 6c 6c 20 76 69 65 77 73 20  fying all views 
4440: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
4450: 23 20 74 61 62 6c 65 20 58 20 69 6e 20 73 74 65  # table X in ste
4460: 70 20 31 20 61 6e 64 20 63 72 65 61 74 69 6e 67  p 1 and creating
4470: 20 6e 65 77 20 76 69 65 77 73 20 61 6e 64 20 74   new views and t
4480: 72 69 67 67 65 72 73 20 74 68 61 74 20 61 72 65  riggers that are
4490: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 23 20 77 69   compatible.# wi
44a0: 74 68 20 74 68 65 20 61 6c 74 65 72 65 64 20 73  th the altered s
44b0: 63 68 65 6d 61 20 66 6f 72 20 74 61 62 6c 65 20  chema for table 
44c0: 58 20 69 6e 20 73 74 65 70 20 36 2e 20 20 49 74  X in step 6.  It
44d0: 20 69 73 20 61 20 74 72 69 63 6b 79 20 62 75 74   is a tricky but
44e0: 20 73 6f 6c 76 61 62 6c 65 0a 23 20 70 72 6f 62   solvable.# prob
44f0: 6c 65 6d 20 74 6f 20 63 72 65 61 74 65 20 63 6f  lem to create co
4500: 64 65 20 74 68 61 74 20 77 69 6c 6c 20 70 65 72  de that will per
4510: 66 6f 72 6d 20 74 68 65 20 73 74 65 70 73 20 61  form the steps a
4520: 62 6f 76 65 20 0a 23 20 66 6f 72 20 22 72 65 61  bove .# for "rea
4530: 73 6f 6e 61 62 6c 65 22 20 73 63 68 65 6d 61 73  sonable" schemas
4540: 20 63 6f 6d 6d 6f 6e 6c 79 20 66 6f 75 6e 64 20   commonly found 
4550: 69 6e 20 70 72 61 63 74 69 63 65 2e 20 20 0a 23  in practice.  .#
4560: 20 42 75 74 20 74 68 65 72 65 20 65 78 69 73 74   But there exist
4570: 20 6d 61 6c 65 76 6f 6c 65 6e 74 20 73 63 68 65   malevolent sche
4580: 6d 61 73 20 66 6f 72 20 77 68 69 63 68 0a 23 20  mas for which.# 
4590: 74 68 65 73 65 20 73 74 65 70 73 20 61 72 65 20  these steps are 
45a0: 6d 61 64 64 65 6e 69 6e 67 6c 79 20 64 69 66 66  maddeningly diff
45b0: 69 63 75 6c 74 20 74 6f 20 64 6f 20 63 6f 72 72  icult to do corr
45c0: 65 63 74 6c 79 2e 20 20 52 61 74 68 65 72 20 74  ectly.  Rather t
45d0: 68 61 6e 20 63 72 65 61 74 65 0a 23 20 41 4c 54  han create.# ALT
45e0: 45 52 20 54 41 42 4c 45 20 66 65 61 74 75 72 65  ER TABLE feature
45f0: 73 20 74 68 61 74 20 77 6f 72 6b 20 63 6f 72 72  s that work corr
4600: 65 63 74 6c 79 20 39 39 2e 39 25 20 6f 66 20 74  ectly 99.9% of t
4610: 68 65 20 74 69 6d 65 20 62 75 74 20 70 6f 73 73  he time but poss
4620: 69 62 6c 79 0a 23 20 63 6f 72 72 75 70 74 20 74  ibly.# corrupt t
4630: 68 65 20 73 63 68 65 6d 61 20 6f 6e 20 74 68 65  he schema on the
4640: 20 6f 74 68 65 72 20 30 2e 31 25 2c 20 74 68 65   other 0.1%, the
4650: 20 53 51 4c 69 74 65 20 64 65 76 65 6c 6f 70 65   SQLite develope
4660: 72 73 20 68 61 76 65 20 64 65 63 69 64 65 64 0a  rs have decided.
4670: 23 20 74 6f 20 70 75 73 68 20 74 68 65 20 70 72  # to push the pr
4680: 6f 62 6c 65 6d 20 69 6e 74 6f 20 74 68 65 20 61  oblem into the a
4690: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 6d 61 69  pplication domai
46a0: 6e 2c 20 77 68 65 72 65 20 69 74 20 69 73 20 6d  n, where it is m
46b0: 75 63 68 20 65 61 73 69 65 72 0a 23 20 74 6f 20  uch easier.# to 
46c0: 73 6f 6c 76 65 2e 0a 3c 2f 74 63 6c 3e 0a 0a 0a  solve..</tcl>...
46d0: 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
46e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
46f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4700: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4710: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4720: 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 41 4e  ####.Section {AN
4730: 41 4c 59 5a 45 7d 20 61 6e 61 6c 79 7a 65 20 41  ALYZE} analyze A
4740: 4e 41 4c 59 5a 45 0a 0a 52 65 63 75 72 73 69 76  NALYZE..Recursiv
4750: 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 61  eBubbleDiagram a
4760: 6e 61 6c 79 7a 65 2d 73 74 6d 74 0a 3c 2f 74 63  nalyze-stmt.</tc
4770: 6c 3e 0a 0a 3c 70 3e 20 5e 54 68 65 20 41 4e 41  l>..<p> ^The ANA
4780: 4c 59 5a 45 20 63 6f 6d 6d 61 6e 64 20 67 61 74  LYZE command gat
4790: 68 65 72 73 20 73 74 61 74 69 73 74 69 63 73 20  hers statistics 
47a0: 61 62 6f 75 74 20 74 61 62 6c 65 73 20 61 6e 64  about tables and
47b0: 0a 69 6e 64 69 63 65 73 20 61 6e 64 20 73 74 6f  .indices and sto
47c0: 72 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 65  res the collecte
47d0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 69 6e  d information.in
47e0: 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61 62 6c 65   [internal table
47f0: 73 5d 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  s] of the databa
4800: 73 65 20 77 68 65 72 65 20 74 68 65 20 71 75 65  se where the que
4810: 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 63 61 6e  ry optimizer can
4820: 0a 61 63 63 65 73 73 20 74 68 65 20 69 6e 66 6f  .access the info
4830: 72 6d 61 74 69 6f 6e 20 61 6e 64 20 75 73 65 20  rmation and use 
4840: 69 74 20 74 6f 20 68 65 6c 70 20 6d 61 6b 65 20  it to help make 
4850: 62 65 74 74 65 72 20 71 75 65 72 79 20 70 6c 61  better query pla
4860: 6e 6e 69 6e 67 20 63 68 6f 69 63 65 73 2e 0a 5e  nning choices..^
4870: 49 66 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  If no arguments 
4880: 61 72 65 20 67 69 76 65 6e 2c 20 61 6c 6c 20 61  are given, all a
4890: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
48a0: 73 20 61 72 65 0a 61 6e 61 6c 79 7a 65 64 2e 20  s are.analyzed. 
48b0: 20 5e 49 66 20 61 20 73 63 68 65 6d 61 20 6e 61   ^If a schema na
48c0: 6d 65 20 69 73 20 67 69 76 65 6e 20 61 73 20 74  me is given as t
48d0: 68 65 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65  he argument, the
48e0: 6e 20 61 6c 6c 20 74 61 62 6c 65 73 0a 61 6e 64  n all tables.and
48f0: 20 69 6e 64 69 63 65 73 20 69 6e 20 74 68 61 74   indices in that
4900: 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20 61 72   one database ar
4910: 65 20 61 6e 61 6c 79 7a 65 64 2e 20 20 0a 5e 49  e analyzed.  .^I
4920: 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
4930: 73 20 61 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  s a table name, 
4940: 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74 20 74  then only that t
4950: 61 62 6c 65 20 61 6e 64 20 74 68 65 0a 69 6e 64  able and the.ind
4960: 69 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20  ices associated 
4970: 77 69 74 68 20 74 68 61 74 20 74 61 62 6c 65 20  with that table 
4980: 61 72 65 20 61 6e 61 6c 79 7a 65 64 2e 20 20 5e  are analyzed.  ^
4990: 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  If the argument.
49a0: 69 73 20 61 6e 20 69 6e 64 65 78 20 6e 61 6d 65  is an index name
49b0: 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74  , then only that
49c0: 20 6f 6e 65 20 69 6e 64 65 78 20 69 73 20 61 6e   one index is an
49d0: 61 6c 79 7a 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e  alyzed.</p>..<p>
49e0: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d   ^The default im
49f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 74 6f  plementation sto
4a00: 72 65 73 20 61 6c 6c 20 73 74 61 74 69 73 74 69  res all statisti
4a10: 63 73 20 69 6e 20 61 20 73 69 6e 67 6c 65 0a 74  cs in a single.t
4a20: 61 62 6c 65 20 6e 61 6d 65 64 20 22 5b 73 71 6c  able named "[sql
4a30: 69 74 65 5f 73 74 61 74 31 5d 22 2e 20 20 5e 49  ite_stat1]".  ^I
4a40: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
4a50: 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 5b 53  iled with the.[S
4a60: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
4a70: 54 33 5d 20 6f 70 74 69 6f 6e 20 61 6e 64 20 77  T3] option and w
4a80: 69 74 68 6f 75 74 20 74 68 65 20 5b 53 51 4c 49  ithout the [SQLI
4a90: 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 34 5d  TE_ENABLE_STAT4]
4aa0: 0a 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 61 64  .option, then ad
4ab0: 64 69 74 69 6f 6e 61 6c 20 68 69 73 74 6f 67 72  ditional histogr
4ac0: 61 6d 20 64 61 74 61 20 69 73 0a 63 6f 6c 6c 65  am data is.colle
4ad0: 63 74 65 64 20 61 6e 64 20 73 74 6f 72 65 64 20  cted and stored 
4ae0: 69 6e 20 5b 73 71 6c 69 74 65 5f 73 74 61 74 33  in [sqlite_stat3
4af0: 5d 2e 0a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ].. ^If SQLite i
4b00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
4b10: 74 68 65 0a 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the.[SQLITE_ENAB
4b20: 4c 45 5f 53 54 41 54 34 5d 20 6f 70 74 69 6f 6e  LE_STAT4] option
4b30: 2c 20 74 68 65 6e 20 61 64 64 69 74 69 6f 6e 61  , then additiona
4b40: 6c 20 68 69 73 74 6f 67 72 61 6d 20 64 61 74 61  l histogram data
4b50: 20 69 73 0a 63 6f 6c 6c 65 63 74 65 64 20 61 6e   is.collected an
4b60: 64 20 73 74 6f 72 65 64 20 69 6e 20 5b 73 71 6c  d stored in [sql
4b70: 69 74 65 5f 73 74 61 74 34 5d 2e 0a 4f 6c 64 65  ite_stat4]..Olde
4b80: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4b90: 4c 69 74 65 20 77 6f 75 6c 64 20 6d 61 6b 65 20  Lite would make 
4ba0: 75 73 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  use of the [sqli
4bb0: 74 65 5f 73 74 61 74 32 5d 20 74 61 62 6c 65 0a  te_stat2] table.
4bc0: 77 68 65 6e 20 63 6f 6d 70 69 6c 65 64 20 77 69  when compiled wi
4bd0: 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
4be0: 45 5f 53 54 41 54 32 5d 20 62 75 74 20 61 6c 6c  E_STAT2] but all
4bf0: 20 72 65 63 65 6e 74 20 76 65 72 73 69 6f 6e 73   recent versions
4c00: 20 6f 66 0a 53 51 4c 69 74 65 20 69 67 6e 6f 72   of.SQLite ignor
4c10: 65 20 74 68 65 20 73 71 6c 69 74 65 5f 73 74 61  e the sqlite_sta
4c20: 74 32 20 74 61 62 6c 65 2e 0a 46 75 74 75 72 65  t2 table..Future
4c30: 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 6d 61   enhancements ma
4c40: 79 20 63 72 65 61 74 65 0a 61 64 64 69 74 69 6f  y create.additio
4c50: 6e 61 6c 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61  nal [internal ta
4c60: 62 6c 65 73 5d 20 77 69 74 68 20 74 68 65 20 73  bles] with the s
4c70: 61 6d 65 20 6e 61 6d 65 20 70 61 74 74 65 72 6e  ame name pattern
4c80: 20 65 78 63 65 70 74 20 77 69 74 68 0a 66 69 6e   except with.fin
4c90: 61 6c 20 64 69 67 69 74 20 6c 61 72 67 65 72 20  al digit larger 
4ca0: 74 68 61 6e 20 22 34 22 2e 0a 41 6c 6c 20 6f 66  than "4"..All of
4cb0: 20 74 68 65 73 65 20 74 61 62 6c 65 73 20 61 72   these tables ar
4cc0: 65 20 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 72  e collectively r
4cd0: 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 73  eferred to as "s
4ce0: 74 61 74 69 73 74 69 63 73 20 74 61 62 6c 65 73  tatistics tables
4cf0: 22 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 54 68  "..</p>..<p> ^Th
4d00: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
4d10: 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62 6c   statistics tabl
4d20: 65 73 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  es can be querie
4d30: 64 20 75 73 69 6e 67 20 5b 53 45 4c 45 43 54 5d  d using [SELECT]
4d40: 0a 61 6e 64 20 63 61 6e 20 62 65 20 63 68 61 6e  .and can be chan
4d50: 67 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 44  ged using the [D
4d60: 45 4c 45 54 45 5d 2c 20 5b 49 4e 53 45 52 54 5d  ELETE], [INSERT]
4d70: 2c 20 61 6e 64 20 5b 55 50 44 41 54 45 5d 20 63  , and [UPDATE] c
4d80: 6f 6d 6d 61 6e 64 73 2e 0a 5e 28 54 68 65 20 5b  ommands..^(The [
4d90: 44 52 4f 50 20 54 41 42 4c 45 5d 20 63 6f 6d 6d  DROP TABLE] comm
4da0: 61 6e 64 20 77 6f 72 6b 73 20 6f 6e 20 73 74 61  and works on sta
4db0: 74 69 73 74 69 63 73 20 74 61 62 6c 65 73 0a 61  tistics tables.a
4dc0: 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
4dd0: 69 6f 6e 20 33 2e 37 2e 39 2e 29 5e 20 28 5b 64  ion 3.7.9.)^ ([d
4de0: 61 74 65 6f 66 3a 33 2e 37 2e 39 5d 29 0a 5e 54  ateof:3.7.9]).^T
4df0: 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45 5d  he [ALTER TABLE]
4e00: 20 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 20 6e 6f   command does no
4e10: 74 20 77 6f 72 6b 20 6f 6e 20 73 74 61 74 69 73  t work on statis
4e20: 74 69 63 73 20 74 61 62 6c 65 73 2e 0a 41 70 70  tics tables..App
4e30: 72 6f 70 72 69 61 74 65 20 63 61 72 65 20 73 68  ropriate care sh
4e40: 6f 75 6c 64 20 62 65 20 75 73 65 64 20 77 68 65  ould be used whe
4e50: 6e 20 63 68 61 6e 67 69 6e 67 20 74 68 65 20 63  n changing the c
4e60: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 73 74  ontent of the st
4e70: 61 74 69 73 74 69 63 73 0a 74 61 62 6c 65 73 20  atistics.tables 
4e80: 61 73 20 69 6e 76 61 6c 69 64 20 63 6f 6e 74 65  as invalid conte
4e90: 6e 74 20 63 61 6e 20 63 61 75 73 65 20 53 51 4c  nt can cause SQL
4ea0: 69 74 65 20 74 6f 20 73 65 6c 65 63 74 20 69 6e  ite to select in
4eb0: 65 66 66 69 63 69 65 6e 74 0a 71 75 65 72 79 20  efficient.query 
4ec0: 70 6c 61 6e 73 2e 20 20 47 65 6e 65 72 61 6c 6c  plans.  Generall
4ed0: 79 20 73 70 65 61 6b 69 6e 67 2c 20 6f 6e 65 20  y speaking, one 
4ee0: 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 6f 64 69 66  should not modif
4ef0: 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
4f00: 0a 74 68 65 20 73 74 61 74 69 73 74 69 63 73 20  .the statistics 
4f10: 74 61 62 6c 65 73 20 62 79 20 61 6e 79 20 6d 65  tables by any me
4f20: 63 68 61 6e 69 73 6d 20 6f 74 68 65 72 20 74 68  chanism other th
4f30: 61 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a  an invoking the.
4f40: 41 4e 41 4c 59 5a 45 20 63 6f 6d 6d 61 6e 64 2e  ANALYZE command.
4f50: 20 20 0a 53 65 65 20 22 5b 4d 61 6e 75 61 6c 20    .See "[Manual 
4f60: 43 6f 6e 74 72 6f 6c 20 4f 66 20 51 75 65 72 79  Control Of Query
4f70: 20 50 6c 61 6e 73 20 55 73 69 6e 67 20 53 51 4c   Plans Using SQL
4f80: 49 54 45 5f 53 54 41 54 20 54 61 62 6c 65 73 5d  ITE_STAT Tables]
4f90: 22 20 66 6f 72 0a 66 75 72 74 68 65 72 20 69 6e  " for.further in
4fa0: 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a  formation.</p>..
4fb0: 3c 70 3e 20 5e 53 74 61 74 69 73 74 69 63 73 20  <p> ^Statistics 
4fc0: 67 61 74 68 65 72 65 64 20 62 79 20 41 4e 41 4c  gathered by ANAL
4fd0: 59 5a 45 20 61 72 65 20 6e 6f 74 20 61 75 74 6f  YZE are not auto
4fe0: 6d 61 74 69 63 61 6c 6c 79 20 75 70 64 61 74 65  matically update
4ff0: 64 20 61 73 0a 74 68 65 20 63 6f 6e 74 65 6e 74  d as.the content
5000: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
5010: 20 63 68 61 6e 67 65 73 2e 20 20 49 66 20 74 68   changes.  If th
5020: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
5030: 20 64 61 74 61 62 61 73 65 0a 63 68 61 6e 67 65   database.change
5040: 73 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79 2c  s significantly,
5050: 20 6f 72 20 69 66 20 74 68 65 20 64 61 74 61 62   or if the datab
5060: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
5070: 65 73 2c 20 74 68 65 6e 20 6f 6e 65 20 73 68 6f  es, then one sho
5080: 75 6c 64 0a 63 6f 6e 73 69 64 65 72 20 72 65 72  uld.consider rer
5090: 75 6e 6e 69 6e 67 20 74 68 65 20 41 4e 41 4c 59  unning the ANALY
50a0: 5a 45 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 6f 72  ZE command in or
50b0: 64 65 72 20 74 6f 20 75 70 64 61 74 65 20 74 68  der to update th
50c0: 65 20 73 74 61 74 69 73 74 69 63 73 2e 3c 2f 70  e statistics.</p
50d0: 3e 0a 0a 3c 70 3e 20 54 68 65 20 71 75 65 72 79  >..<p> The query
50e0: 20 70 6c 61 6e 6e 65 72 20 6c 6f 61 64 73 20 74   planner loads t
50f0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
5100: 65 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62  e statistics tab
5110: 6c 65 73 0a 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  les.into memory 
5120: 77 68 65 6e 20 74 68 65 20 73 63 68 65 6d 61 20  when the schema 
5130: 69 73 20 72 65 61 64 2e 20 20 5e 48 65 6e 63 65  is read.  ^Hence
5140: 2c 20 77 68 65 6e 20 61 6e 20 61 70 70 6c 69 63  , when an applic
5150: 61 74 69 6f 6e 0a 63 68 61 6e 67 65 73 20 74 68  ation.changes th
5160: 65 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62  e statistics tab
5170: 6c 65 73 20 64 69 72 65 63 74 6c 79 2c 20 53 51  les directly, SQ
5180: 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6d  Lite will not im
5190: 6d 65 64 69 61 74 65 6c 79 0a 6e 6f 74 69 63 65  mediately.notice
51a0: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 5e 41   the changes. ^A
51b0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 63 61  n application.ca
51c0: 6e 20 66 6f 72 63 65 20 74 68 65 20 71 75 65 72  n force the quer
51d0: 79 20 70 6c 61 6e 6e 65 72 20 74 6f 20 72 65 72  y planner to rer
51e0: 65 61 64 20 74 68 65 20 73 74 61 74 69 73 74 69  ead the statisti
51f0: 63 73 20 74 61 62 6c 65 73 20 62 79 20 72 75 6e  cs tables by run
5200: 6e 69 6e 67 0a 3c 62 3e 41 4e 41 4c 59 5a 45 20  ning.<b>ANALYZE 
5210: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 3c 2f 62  sqlite_master</b
5220: 3e 2e 20 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  >. </p>..<tcl>hd
5230: 5f 66 72 61 67 6d 65 6e 74 20 61 75 74 6f 61 6e  _fragment autoan
5240: 61 6c 79 7a 65 20 7b 61 75 74 6f 6d 61 74 69 63  alyze {automatic
5250: 61 6c 6c 79 20 72 75 6e 6e 69 6e 67 20 41 4e 41  ally running ANA
5260: 4c 59 5a 45 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  LYZE}</tcl>.<h2>
5270: 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 52 75  Automatically Ru
5280: 6e 6e 69 6e 67 20 41 4e 41 4c 59 5a 45 3c 2f 68  nning ANALYZE</h
5290: 32 3e 0a 0a 3c 70 3e 54 68 65 20 5b 50 52 41 47  2>..<p>The [PRAG
52a0: 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 63 6f 6d  MA optimize] com
52b0: 6d 61 6e 64 20 77 69 6c 6c 20 61 75 74 6f 6d 61  mand will automa
52c0: 74 69 63 61 6c 6c 79 20 72 75 6e 20 41 4e 41 4c  tically run ANAL
52d0: 59 5a 45 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  YZE on individua
52e0: 6c 0a 74 61 62 6c 65 73 20 6f 6e 20 61 6e 20 61  l.tables on an a
52f0: 73 2d 6e 65 65 64 65 64 20 62 61 73 69 73 2e 20  s-needed basis. 
5300: 20 54 68 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64   The recommended
5310: 20 70 72 61 63 74 69 63 65 20 69 73 20 66 6f 72   practice is for
5320: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 74 6f   applications.to
5330: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 50 52 41   invoke the [PRA
5340: 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 73 74  GMA optimize] st
5350: 61 74 65 6d 65 6e 74 20 6a 75 73 74 20 62 65 66  atement just bef
5360: 6f 72 65 20 63 6c 6f 73 69 6e 67 20 65 61 63 68  ore closing each
5370: 20 64 61 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63   database.connec
5380: 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 45 61  tion.</p>..<p>Ea
5390: 63 68 20 53 51 4c 69 74 65 20 5b 64 61 74 61 62  ch SQLite [datab
53a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
53b0: 72 65 63 6f 72 64 73 20 63 61 73 65 73 20 77 68  records cases wh
53c0: 65 6e 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  en the query pla
53d0: 6e 6e 65 72 20 77 6f 75 6c 64 0a 62 65 6e 65 66  nner would.benef
53e0: 69 74 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 61  it from having a
53f0: 63 63 75 72 61 74 65 20 72 65 73 75 6c 74 73 20  ccurate results 
5400: 6f 66 20 41 4e 41 4c 59 5a 45 20 61 74 20 68 61  of ANALYZE at ha
5410: 6e 64 2e 20 20 54 68 65 73 65 20 72 65 63 6f 72  nd.  These recor
5420: 64 73 0a 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  ds.are held in m
5430: 65 6d 6f 72 79 20 61 6e 64 20 61 63 63 75 6d 75  emory and accumu
5440: 6c 61 74 65 20 6f 76 65 72 20 74 68 65 20 6c 69  late over the li
5450: 66 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  fe of a database
5460: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 54 68 65   connection..The
5470: 20 5b 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a   [PRAGMA optimiz
5480: 65 5d 20 63 6f 6d 6d 61 6e 64 20 6c 6f 6f 6b 73  e] command looks
5490: 20 61 74 20 74 68 6f 73 65 20 72 65 63 6f 72 64   at those record
54a0: 73 20 61 6e 64 20 72 75 6e 73 20 41 4e 41 4c 59  s and runs ANALY
54b0: 5a 45 20 6f 6e 20 6f 6e 6c 79 0a 74 68 6f 73 65  ZE on only.those
54c0: 20 74 61 62 6c 65 73 20 66 6f 72 20 77 68 69 63   tables for whic
54d0: 68 20 6e 65 77 20 6f 72 20 75 70 64 61 74 65 64  h new or updated
54e0: 20 41 4e 41 4c 59 5a 45 20 64 61 74 61 20 73 65   ANALYZE data se
54f0: 65 6d 73 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  ems likely to be
5500: 20 75 73 65 66 75 6c 2e 0a 49 6e 20 6d 6f 73 74   useful..In most
5510: 20 63 61 73 65 73 20 5b 50 52 41 47 4d 41 20 6f   cases [PRAGMA o
5520: 70 74 69 6d 69 7a 65 5d 20 77 69 6c 6c 20 6e 6f  ptimize] will no
5530: 74 20 72 75 6e 20 41 4e 41 4c 59 5a 45 2c 20 62  t run ANALYZE, b
5540: 75 74 20 69 74 20 77 69 6c 6c 20 6f 63 63 61 73  ut it will occas
5550: 69 6f 6e 61 6c 6c 79 0a 64 6f 20 73 6f 20 65 69  ionally.do so ei
5560: 74 68 65 72 20 66 6f 72 20 74 61 62 6c 65 73 20  ther for tables 
5570: 74 68 61 74 20 68 61 76 65 20 6e 65 76 65 72 20  that have never 
5580: 62 65 66 6f 72 65 20 62 65 65 6e 20 61 6e 61 6c  before been anal
5590: 79 7a 65 64 2c 20 6f 72 20 66 6f 72 20 74 61 62  yzed, or for tab
55a0: 6c 65 73 0a 74 68 61 74 20 68 61 76 65 20 67 72  les.that have gr
55b0: 6f 77 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 6c  own significantl
55c0: 79 20 73 69 6e 63 65 20 74 68 65 79 20 77 65 72  y since they wer
55d0: 65 20 6c 61 73 74 20 61 6e 61 6c 79 7a 65 64 2e  e last analyzed.
55e0: 3c 2f 70 3e 0a 0a 3c 70 3e 53 69 6e 63 65 20 74  </p>..<p>Since t
55f0: 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 5b 50  he actions of [P
5600: 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20  RAGMA optimize] 
5610: 61 72 65 20 64 65 74 65 72 6d 69 6e 65 64 20 74  are determined t
5620: 6f 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  o some extent by
5630: 0a 70 72 69 6f 72 20 71 75 65 72 69 65 73 20 74  .prior queries t
5640: 68 61 74 20 68 61 76 65 20 62 65 65 6e 20 65 76  hat have been ev
5650: 61 6c 75 61 74 65 64 20 6f 6e 20 74 68 65 20 73  aluated on the s
5660: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
5670: 6e 65 63 74 69 6f 6e 2c 20 69 74 0a 69 73 20 72  nection, it.is r
5680: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
5690: 5b 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65  [PRAGMA optimize
56a0: 5d 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  ] be deferred un
56b0: 74 69 6c 20 74 68 65 20 64 61 74 61 62 61 73 65  til the database
56c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 69 73 20 63   connection.is c
56d0: 6c 6f 73 69 6e 67 20 61 6e 64 20 68 61 73 20 74  losing and has t
56e0: 68 75 73 20 68 61 64 20 61 6e 20 6f 70 70 6f 72  hus had an oppor
56f0: 74 75 6e 69 74 79 20 74 6f 20 61 63 63 75 6d 75  tunity to accumu
5700: 6c 61 74 65 20 61 73 20 6d 75 63 68 20 75 73 61  late as much usa
5710: 67 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61  ge information.a
5720: 73 20 70 6f 73 73 69 62 6c 65 2e 20 20 49 74 20  s possible.  It 
5730: 69 73 20 61 6c 73 6f 20 72 65 61 73 6f 6e 61 62  is also reasonab
5740: 6c 65 20 74 6f 20 73 65 74 20 61 20 74 69 6d 65  le to set a time
5750: 72 20 74 6f 20 72 75 6e 20 5b 50 52 41 47 4d 41  r to run [PRAGMA
5760: 20 6f 70 74 69 6d 69 7a 65 5d 0a 65 76 65 72 79   optimize].every
5770: 20 66 65 77 20 68 6f 75 72 73 2c 20 6f 72 20 65   few hours, or e
5780: 76 65 72 79 20 66 65 77 20 64 61 79 73 2c 20 66  very few days, f
5790: 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  or database conn
57a0: 65 63 74 69 6f 6e 73 20 74 68 61 74 20 73 74 61  ections that sta
57b0: 79 20 6f 70 65 6e 0a 66 6f 72 20 61 20 6c 6f 6e  y open.for a lon
57c0: 67 20 74 69 6d 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e  g time.</p>..<p>
57d0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
57e0: 74 20 64 65 73 69 72 65 20 6d 6f 72 65 20 63 6f  t desire more co
57f0: 6e 74 72 6f 6c 20 63 61 6e 20 72 75 6e 20 5b 50  ntrol can run [P
5800: 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 28 30  RAGMA optimize(0
5810: 78 30 33 29 5d 20 74 6f 20 0a 6f 62 74 61 69 6e  x03)] to .obtain
5820: 20 61 20 6c 69 73 74 20 6f 66 20 41 4e 41 4c 59   a list of ANALY
5830: 5a 45 20 63 6f 6d 6d 61 6e 64 73 20 74 68 61 74  ZE commands that
5840: 20 53 51 4c 69 74 65 20 74 68 69 6e 6b 73 20 61   SQLite thinks a
5850: 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  re appropriate t
5860: 6f 20 72 75 6e 2c 0a 62 75 74 20 77 69 74 68 6f  o run,.but witho
5870: 75 74 20 61 63 74 75 61 6c 6c 79 20 72 75 6e 6e  ut actually runn
5880: 69 6e 67 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  ing those comman
5890: 64 73 2e 20 20 49 66 20 74 68 65 20 72 65 74 75  ds.  If the retu
58a0: 72 6e 65 64 20 73 65 74 20 69 73 20 0a 6e 6f 6e  rned set is .non
58b0: 2d 65 6d 70 74 79 2c 20 74 68 65 20 61 70 70 6c  -empty, the appl
58c0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 74 68 65 6e  ication can then
58d0: 20 6d 61 6b 65 20 61 20 64 65 63 69 73 69 6f 6e   make a decision
58e0: 20 61 62 6f 75 74 20 77 68 65 74 68 65 72 20 6f   about whether o
58f0: 72 20 6e 6f 74 0a 74 6f 20 72 75 6e 20 74 68 65  r not.to run the
5900: 20 73 75 67 67 65 73 74 65 64 20 41 4e 41 4c 59   suggested ANALY
5910: 5a 45 20 63 6f 6d 6d 61 6e 64 73 2c 20 70 65 72  ZE commands, per
5920: 68 61 70 73 20 61 66 74 65 72 20 70 72 6f 6d 70  haps after promp
5930: 74 69 6e 67 20 74 68 65 20 75 73 65 72 0a 66 6f  ting the user.fo
5940: 72 20 67 75 69 64 61 6e 63 65 2e 3c 2f 70 3e 0a  r guidance.</p>.
5950: 0a 3c 70 3e 54 68 65 20 5b 50 52 41 47 4d 41 20  .<p>The [PRAGMA 
5960: 6f 70 74 69 6d 69 7a 65 5d 20 63 6f 6d 6d 61 6e  optimize] comman
5970: 64 20 77 61 73 20 66 69 72 73 74 20 69 6e 74 72  d was first intr
5980: 6f 64 75 63 65 64 20 77 69 74 68 20 0a 53 51 4c  oduced with .SQL
5990: 69 74 65 20 33 2e 31 38 2e 30 20 28 5b 64 61 74  ite 3.18.0 ([dat
59a0: 65 6f 66 3a 33 2e 31 38 2e 30 5d 29 20 61 6e 64  eof:3.18.0]) and
59b0: 20 69 73 20 61 20 6e 6f 2d 6f 70 20 66 6f 72 20   is a no-op for 
59c0: 61 6c 6c 20 70 72 69 6f 72 20 72 65 6c 65 61 73  all prior releas
59d0: 65 73 0a 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70  es.of SQLite.</p
59e0: 3e 0a 0a 3c 68 32 3e 41 6e 74 69 63 69 70 61 74  >..<h2>Anticipat
59f0: 65 64 20 46 75 74 75 72 65 20 45 6e 68 61 6e 63  ed Future Enhanc
5a00: 65 6d 65 6e 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  ements</h2>..<p>
5a10: 41 6c 6c 20 65 78 69 73 74 69 6e 67 20 76 65 72  All existing ver
5a20: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
5a30: 64 6f 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20  do a full table 
5a40: 73 63 61 6e 20 66 6f 72 20 41 4e 41 4c 59 5a 45  scan for ANALYZE
5a50: 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 0a 73  .  This can be.s
5a60: 6c 6f 77 20 66 6f 72 20 6d 75 6c 74 69 2d 67 69  low for multi-gi
5a70: 67 61 62 79 74 65 20 61 6e 64 20 6c 61 72 67 65  gabyte and large
5a80: 72 20 64 61 74 61 62 61 73 65 73 2e 20 20 46 75  r databases.  Fu
5a90: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
5aa0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 75 73   SQLite might.us
5ab0: 65 20 72 61 6e 64 6f 6d 20 73 61 6d 70 6c 69 6e  e random samplin
5ac0: 67 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 20  g rather than a 
5ad0: 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20  full table scan 
5ae0: 74 6f 20 6f 62 74 61 69 6e 20 65 73 74 69 6d 61  to obtain estima
5af0: 74 65 73 20 66 6f 72 20 74 68 65 0a 64 61 74 61  tes for the.data
5b00: 62 61 73 65 20 73 68 61 70 65 2c 20 65 73 70 65  base shape, espe
5b10: 63 69 61 6c 6c 79 20 6f 6e 20 6c 61 72 67 65 72  cially on larger
5b20: 20 74 61 62 6c 65 73 2e 20 20 54 68 65 20 72 65   tables.  The re
5b30: 73 75 6c 74 73 20 77 6f 75 6c 64 20 61 70 70 72  sults would appr
5b40: 6f 78 69 6d 61 74 65 2c 20 62 75 74 20 0a 77 69  oximate, but .wi
5b50: 6c 6c 20 62 65 20 63 6c 6f 73 65 20 65 6e 6f 75  ll be close enou
5b60: 67 68 20 66 6f 72 20 71 75 65 72 79 20 70 6c 61  gh for query pla
5b70: 6e 6e 69 6e 67 20 70 75 72 70 6f 73 65 73 2e 20  nning purposes. 
5b80: 20 41 73 20 6f 66 20 32 30 31 37 2d 30 33 2d 32   As of 2017-03-2
5b90: 30 2c 20 74 68 69 73 0a 63 6f 6e 63 65 70 74 20  0, this.concept 
5ba0: 68 61 73 20 62 65 65 6e 20 74 65 73 74 65 64 20  has been tested 
5bb0: 69 6e 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  in experimental 
5bc0: 62 72 61 6e 63 68 65 73 20 61 6e 64 20 61 70 70  branches and app
5bd0: 65 61 72 73 20 74 6f 20 77 6f 72 6b 20 77 65 6c  ears to work wel
5be0: 6c 2c 20 62 75 74 0a 68 61 73 20 6e 6f 74 20 62  l, but.has not b
5bf0: 65 65 6e 20 66 6f 6c 64 65 64 20 69 6e 74 6f 20  een folded into 
5c00: 61 6e 20 6f 66 66 69 63 69 61 6c 20 72 65 6c 65  an official rele
5c10: 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a  ase.</p>..<tcl>.
5c20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5c30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5c40: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5c50: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5c60: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
5c70: 65 63 74 69 6f 6e 20 7b 41 54 54 41 43 48 20 44  ection {ATTACH D
5c80: 41 54 41 42 41 53 45 7d 20 61 74 74 61 63 68 20  ATABASE} attach 
5c90: 7b 61 74 74 61 63 68 65 64 20 2a 41 54 54 41 43  {attached *ATTAC
5ca0: 48 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  H}..RecursiveBub
5cb0: 62 6c 65 44 69 61 67 72 61 6d 20 61 74 74 61 63  bleDiagram attac
5cc0: 68 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  h-stmt.</tcl>..<
5cd0: 70 3e 20 5e 54 68 65 20 41 54 54 41 43 48 20 44  p> ^The ATTACH D
5ce0: 41 54 41 42 41 53 45 20 73 74 61 74 65 6d 65 6e  ATABASE statemen
5cf0: 74 20 61 64 64 73 20 61 6e 6f 74 68 65 72 20 64  t adds another d
5d00: 61 74 61 62 61 73 65 20 0a 66 69 6c 65 20 74 6f  atabase .file to
5d10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 5b 64 61   the current [da
5d20: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5d30: 6e 5d 2e 20 0a 44 61 74 61 62 61 73 65 20 66 69  n]. .Database fi
5d40: 6c 65 73 20 74 68 61 74 20 77 65 72 65 20 70 72  les that were pr
5d50: 65 76 69 6f 75 73 6c 79 20 61 74 74 61 63 68 65  eviously attache
5d60: 64 20 63 61 6e 20 62 65 20 72 65 6d 6f 76 65 64  d can be removed
5d70: 20 75 73 69 6e 67 0a 74 68 65 20 5b 44 45 54 41   using.the [DETA
5d80: 43 48 20 44 41 54 41 42 41 53 45 5d 20 63 6f 6d  CH DATABASE] com
5d90: 6d 61 6e 64 2e 0a 0a 3c 70 3e 5e 54 68 65 20 66  mand...<p>^The f
5da0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ilename for the 
5db0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 61  database to be a
5dc0: 74 74 61 63 68 65 64 20 69 73 20 74 68 65 20 76  ttached is the v
5dd0: 61 6c 75 65 20 6f 66 0a 74 68 65 20 65 78 70 72  alue of.the expr
5de0: 65 73 73 69 6f 6e 20 74 68 61 74 20 6f 63 63 75  ession that occu
5df0: 72 73 20 62 65 66 6f 72 65 20 74 68 65 20 41 53  rs before the AS
5e00: 20 6b 65 79 77 6f 72 64 2e 0a 5e 54 68 65 20 66   keyword..^The f
5e10: 69 6c 65 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ilename of the d
5e20: 61 74 61 62 61 73 65 20 66 6f 6c 6c 6f 77 73 20  atabase follows 
5e30: 74 68 65 20 73 61 6d 65 20 73 65 6d 61 6e 74 69  the same semanti
5e40: 63 73 20 61 73 20 74 68 65 0a 66 69 6c 65 6e 61  cs as the.filena
5e50: 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
5e60: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
5e70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
5e80: 6e 5f 76 32 28 29 5d 3b 20 74 68 65 0a 73 70 65  n_v2()]; the.spe
5e90: 63 69 61 6c 20 6e 61 6d 65 20 22 5b 3a 6d 65 6d  cial name "[:mem
5ea0: 6f 72 79 3a 5d 22 20 72 65 73 75 6c 74 73 20 69  ory:]" results i
5eb0: 6e 20 61 6e 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  n an [in-memory 
5ec0: 64 61 74 61 62 61 73 65 5d 20 61 6e 64 20 61 6e  database] and an
5ed0: 0a 65 6d 70 74 79 20 73 74 72 69 6e 67 20 72 65  .empty string re
5ee0: 73 75 6c 74 73 20 69 6e 20 61 20 6e 65 77 20 74  sults in a new t
5ef0: 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73  emporary databas
5f00: 65 2e 0a 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  e..^The filename
5f10: 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
5f20: 20 61 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65   a [URI filename
5f30: 5d 20 69 66 20 55 52 49 20 66 69 6c 65 6e 61 6d  ] if URI filenam
5f40: 65 20 70 72 6f 63 65 73 73 69 6e 67 0a 69 73 20  e processing.is 
5f50: 65 6e 61 62 6c 65 20 6f 6e 20 74 68 65 20 64 61  enable on the da
5f60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5f70: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
5f80: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 0a  behavior is for.
5f90: 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 74 6f  URI filenames to
5fa0: 20 62 65 20 64 69 73 61 62 6c 65 64 2c 20 68 6f   be disabled, ho
5fb0: 77 65 76 65 72 20 74 68 61 74 20 6d 69 67 68 74  wever that might
5fc0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
5fd0: 75 72 65 20 72 65 6c 65 61 73 65 0a 6f 66 20 53  ure release.of S
5fe0: 51 4c 69 74 65 2c 20 73 6f 20 61 70 70 6c 69 63  QLite, so applic
5ff0: 61 74 69 6f 6e 20 64 65 76 65 6c 6f 70 65 72 73  ation developers
6000: 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
6010: 70 6c 61 6e 20 61 63 63 6f 72 64 69 6e 67 6c 79  plan accordingly
6020: 2e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 20 74  ...<p>The name t
6030: 68 61 74 20 6f 63 63 75 72 73 20 61 66 74 65 72  hat occurs after
6040: 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
6050: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
6060: 68 65 20 64 61 74 61 62 61 73 65 0a 75 73 65 64  he database.used
6070: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
6080: 51 4c 69 74 65 2e 0a 5e 54 68 65 20 73 63 68 65  QLite..^The sche
6090: 6d 61 2d 6e 61 6d 65 73 20 27 6d 61 69 6e 27 20  ma-names 'main' 
60a0: 61 6e 64 20 0a 27 74 65 6d 70 27 20 72 65 66 65  and .'temp' refe
60b0: 72 20 74 6f 20 74 68 65 20 6d 61 69 6e 20 64 61  r to the main da
60c0: 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64  tabase and the d
60d0: 61 74 61 62 61 73 65 20 75 73 65 64 20 66 6f 72  atabase used for
60e0: 20 0a 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c   .temporary tabl
60f0: 65 73 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 61  es.  ^The main a
6100: 6e 64 20 74 65 6d 70 20 64 61 74 61 62 61 73 65  nd temp database
6110: 73 20 63 61 6e 6e 6f 74 20 62 65 20 61 74 74 61  s cannot be atta
6120: 63 68 65 64 20 6f 72 0a 64 65 74 61 63 68 65 64  ched or.detached
6130: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28 54 61 62  .</p>..<p> ^(Tab
6140: 6c 65 73 20 69 6e 20 61 6e 20 61 74 74 61 63 68  les in an attach
6150: 65 64 20 64 61 74 61 62 61 73 65 20 63 61 6e 20  ed database can 
6160: 62 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 75  be referred to u
6170: 73 69 6e 67 20 74 68 65 20 73 79 6e 74 61 78 20  sing the syntax 
6180: 0a 3c 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 2e  .<i>schema-name.
6190: 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 69 3e 2e 29  table-name</i>.)
61a0: 5e 20 20 5e 49 66 20 74 68 65 20 6e 61 6d 65 20  ^  ^If the name 
61b0: 6f 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20  of the table is 
61c0: 75 6e 69 71 75 65 0a 61 63 72 6f 73 73 20 61 6c  unique.across al
61d0: 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
61e0: 61 73 65 73 20 61 6e 64 20 74 68 65 20 6d 61 69  ases and the mai
61f0: 6e 20 61 6e 64 20 74 65 6d 70 20 64 61 74 61 62  n and temp datab
6200: 61 73 65 73 2c 20 74 68 65 6e 20 74 68 65 0a 3c  ases, then the.<
6210: 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69  i>schema-name</i
6220: 3e 20 70 72 65 66 69 78 20 69 73 20 6e 6f 74 20  > prefix is not 
6230: 72 65 71 75 69 72 65 64 2e 20 20 5e 49 66 20 74  required.  ^If t
6240: 77 6f 20 6f 72 20 6d 6f 72 65 20 74 61 62 6c 65  wo or more table
6250: 73 20 69 6e 0a 64 69 66 66 65 72 65 6e 74 20 64  s in.different d
6260: 61 74 61 62 61 73 65 73 20 68 61 76 65 20 74 68  atabases have th
6270: 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 6e 64 20  e same name and 
6280: 74 68 65 20 0a 3c 69 3e 73 63 68 65 6d 61 2d 6e  the .<i>schema-n
6290: 61 6d 65 3c 2f 69 3e 20 70 72 65 66 69 78 20 69  ame</i> prefix i
62a0: 73 20 6e 6f 74 20 75 73 65 64 20 6f 6e 20 61 20  s not used on a 
62b0: 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 2c  table reference,
62c0: 20 74 68 65 6e 20 74 68 65 0a 74 61 62 6c 65 20   then the.table 
62d0: 63 68 6f 73 65 6e 20 69 73 20 74 68 65 20 6f 6e  chosen is the on
62e0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
62f0: 65 20 74 68 61 74 20 77 61 73 20 6c 65 61 73 74  e that was least
6300: 20 72 65 63 65 6e 74 6c 79 20 61 74 74 61 63 68   recently attach
6310: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 72  ed.</p>..<p>.^Tr
6320: 61 6e 73 61 63 74 69 6f 6e 73 20 69 6e 76 6f 6c  ansactions invol
6330: 76 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 61 74  ving multiple at
6340: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
6350: 20 61 72 65 20 61 74 6f 6d 69 63 2c 0a 61 73 73   are atomic,.ass
6360: 75 6d 69 6e 67 20 74 68 61 74 20 74 68 65 20 6d  uming that the m
6370: 61 69 6e 20 64 61 74 61 62 61 73 65 20 69 73 20  ain database is 
6380: 6e 6f 74 20 22 5b 3a 6d 65 6d 6f 72 79 3a 5d 22  not "[:memory:]"
6390: 20 61 6e 64 20 74 68 65 20 0a 5b 6a 6f 75 72 6e   and the .[journ
63a0: 61 6c 5f 6d 6f 64 65 5d 20 69 73 20 6e 6f 74 20  al_mode] is not 
63b0: 5b 57 41 4c 5d 2e 20 20 5e 28 49 66 20 74 68 65  [WAL].  ^(If the
63c0: 20 6d 61 69 6e 0a 64 61 74 61 62 61 73 65 20 69   main.database i
63d0: 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 20 6f 72 20  s ":memory:" or 
63e0: 69 66 20 74 68 65 20 6a 6f 75 72 6e 61 6c 5f 6d  if the journal_m
63f0: 6f 64 65 20 69 73 20 57 41 4c 2c 20 74 68 65 6e  ode is WAL, then
6400: 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63   .transactions c
6410: 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 61 74  ontinue to be at
6420: 6f 6d 69 63 20 77 69 74 68 69 6e 20 65 61 63 68  omic within each
6430: 20 69 6e 64 69 76 69 64 75 61 6c 0a 64 61 74 61   individual.data
6440: 62 61 73 65 20 66 69 6c 65 2e 20 42 75 74 20 69  base file. But i
6450: 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
6460: 74 65 72 20 63 72 61 73 68 65 73 20 69 6e 20 74  ter crashes in t
6470: 68 65 20 6d 69 64 64 6c 65 0a 6f 66 20 61 20 5b  he middle.of a [
6480: 43 4f 4d 4d 49 54 5d 20 77 68 65 72 65 20 74 77  COMMIT] where tw
6490: 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61  o or more databa
64a0: 73 65 20 66 69 6c 65 73 20 61 72 65 20 75 70 64  se files are upd
64b0: 61 74 65 64 2c 0a 73 6f 6d 65 20 6f 66 20 74 68  ated,.some of th
64c0: 6f 73 65 20 66 69 6c 65 73 20 6d 69 67 68 74 20  ose files might 
64d0: 67 65 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  get the changes 
64e0: 77 68 65 72 65 20 6f 74 68 65 72 73 0a 6d 69 67  where others.mig
64f0: 68 74 20 6e 6f 74 2e 29 5e 0a 3c 2f 70 3e 0a 0a  ht not.)^.</p>..
6500: 3c 70 3e 20 5e 54 68 65 72 65 20 69 73 20 61 20  <p> ^There is a 
6510: 6c 69 6d 69 74 2c 20 73 65 74 20 75 73 69 6e 67  limit, set using
6520: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
6530: 29 5d 20 61 6e 64 20 0a 5b 53 51 4c 49 54 45 5f  )] and .[SQLITE_
6540: 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 2c  LIMIT_ATTACHED],
6550: 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
6560: 66 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  f databases that
6570: 20 63 61 6e 20 62 65 0a 73 69 6d 75 6c 74 61 6e   can be.simultan
6580: 65 6f 75 73 6c 79 20 61 74 74 61 63 68 65 64 20  eously attached 
6590: 74 6f 20 61 20 73 69 6e 67 6c 65 20 64 61 74 61  to a single data
65a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
65b0: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  </p>..<tcl>.####
65c0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
65d0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
65e0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
65f0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6600: 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
6610: 69 6f 6e 20 7b 42 45 47 49 4e 20 54 52 41 4e 53  ion {BEGIN TRANS
6620: 41 43 54 49 4f 4e 7d 20 74 72 61 6e 73 61 63 74  ACTION} transact
6630: 69 6f 6e 20 7b 2a 42 45 47 49 4e 20 43 4f 4d 4d  ion {*BEGIN COMM
6640: 49 54 20 52 4f 4c 4c 42 41 43 4b 7d 0a 0a 52 65  IT ROLLBACK}..Re
6650: 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
6660: 67 72 61 6d 20 62 65 67 69 6e 2d 73 74 6d 74 0a  gram begin-stmt.
6670: 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
6680: 69 61 67 72 61 6d 20 63 6f 6d 6d 69 74 2d 73 74  iagram commit-st
6690: 6d 74 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  mt.RecursiveBubb
66a0: 6c 65 44 69 61 67 72 61 6d 20 72 6f 6c 6c 62 61  leDiagram rollba
66b0: 63 6b 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  ck-stmt.</tcl>..
66c0: 3c 70 3e 0a 5e 4e 6f 20 72 65 61 64 73 20 6f 72  <p>.^No reads or
66d0: 20 77 72 69 74 65 73 20 6f 63 63 75 72 20 65 78   writes occur ex
66e0: 63 65 70 74 20 77 69 74 68 69 6e 20 61 20 74 72  cept within a tr
66f0: 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e 41 6e 79 20  ansaction..^Any 
6700: 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 61 63 63  command that acc
6710: 65 73 73 65 73 20 74 68 65 20 64 61 74 61 62 61  esses the databa
6720: 73 65 20 28 62 61 73 69 63 61 6c 6c 79 2c 20 61  se (basically, a
6730: 6e 79 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 2c 0a  ny SQL command,.
6740: 65 78 63 65 70 74 20 61 20 66 65 77 20 5b 50 52  except a few [PR
6750: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
6760: 29 0a 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ).will automatic
6770: 61 6c 6c 79 20 73 74 61 72 74 20 61 20 74 72 61  ally start a tra
6780: 6e 73 61 63 74 69 6f 6e 20 69 66 0a 6f 6e 65 20  nsaction if.one 
6790: 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69  is not already i
67a0: 6e 20 65 66 66 65 63 74 2e 20 20 5e 41 75 74 6f  n effect.  ^Auto
67b0: 6d 61 74 69 63 61 6c 6c 79 20 73 74 61 72 74 65  matically starte
67c0: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 61  d transactions.a
67d0: 72 65 20 63 6f 6d 6d 69 74 74 65 64 20 77 68 65  re committed whe
67e0: 6e 20 74 68 65 20 6c 61 73 74 20 53 51 4c 20 73  n the last SQL s
67f0: 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
6800: 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 72  s..</p>..<p>.^Tr
6810: 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 20 62  ansactions can b
6820: 65 20 73 74 61 72 74 65 64 20 6d 61 6e 75 61 6c  e started manual
6830: 6c 79 20 75 73 69 6e 67 20 74 68 65 20 42 45 47  ly using the BEG
6840: 49 4e 0a 63 6f 6d 6d 61 6e 64 2e 20 20 5e 28 53  IN.command.  ^(S
6850: 75 63 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  uch transactions
6860: 20 75 73 75 61 6c 6c 79 20 70 65 72 73 69 73 74   usually persist
6870: 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
6880: 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41  COMMIT or ROLLBA
6890: 43 4b 20 63 6f 6d 6d 61 6e 64 2e 20 20 42 75 74  CK command.  But
68a0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77   a transaction w
68b0: 69 6c 6c 20 61 6c 73 6f 20 0a 52 4f 4c 4c 42 41  ill also .ROLLBA
68c0: 43 4b 20 69 66 20 74 68 65 20 64 61 74 61 62 61  CK if the databa
68d0: 73 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  se is closed or 
68e0: 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
68f0: 72 73 0a 61 6e 64 20 74 68 65 20 52 4f 4c 4c 42  rs.and the ROLLB
6900: 41 43 4b 20 63 6f 6e 66 6c 69 63 74 20 72 65 73  ACK conflict res
6910: 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
6920: 6d 20 69 73 20 73 70 65 63 69 66 69 65 64 2e 29  m is specified.)
6930: 5e 0a 53 65 65 20 74 68 65 20 64 6f 63 75 6d 65  ^.See the docume
6940: 6e 74 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 5b  ntation on the [
6950: 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 0a 63 6c 61  ON CONFLICT].cla
6960: 75 73 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  use for addition
6970: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  al information a
6980: 62 6f 75 74 20 74 68 65 20 52 4f 4c 4c 42 41 43  bout the ROLLBAC
6990: 4b 0a 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  K.conflict resol
69a0: 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 2e  ution algorithm.
69b0: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 45 4e 44 20  .</p>..<p>.^END 
69c0: 54 52 41 4e 53 41 43 54 49 4f 4e 20 69 73 20 61  TRANSACTION is a
69d0: 6e 20 61 6c 69 61 73 20 66 6f 72 20 43 4f 4d 4d  n alias for COMM
69e0: 49 54 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28  IT..</p>..<p> ^(
69f0: 54 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 72 65  Transactions cre
6a00: 61 74 65 64 20 75 73 69 6e 67 20 42 45 47 49 4e  ated using BEGIN
6a10: 2e 2e 2e 43 4f 4d 4d 49 54 20 64 6f 20 6e 6f 74  ...COMMIT do not
6a20: 20 6e 65 73 74 2e 29 5e 0a 5e 46 6f 72 20 6e 65   nest.)^.^For ne
6a30: 73 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e  sted transaction
6a40: 73 2c 20 75 73 65 20 74 68 65 20 5b 53 41 56 45  s, use the [SAVE
6a50: 50 4f 49 4e 54 5d 20 61 6e 64 20 5b 52 45 4c 45  POINT] and [RELE
6a60: 41 53 45 5d 20 63 6f 6d 6d 61 6e 64 73 2e 0a 54  ASE] commands..T
6a70: 68 65 20 22 54 4f 20 53 41 56 45 50 4f 49 4e 54  he "TO SAVEPOINT
6a80: 20 3c 79 79 74 65 72 6d 3e 6e 61 6d 65 3c 2f 79   <yyterm>name</y
6a90: 79 74 65 72 6d 3e 22 20 63 6c 61 75 73 65 20 6f  yterm>" clause o
6aa0: 66 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63  f the ROLLBACK c
6ab0: 6f 6d 6d 61 6e 64 20 73 68 6f 77 6e 0a 69 6e 20  ommand shown.in 
6ac0: 74 68 65 20 73 79 6e 74 61 78 20 64 69 61 67 72  the syntax diagr
6ad0: 61 6d 20 61 62 6f 76 65 20 69 73 20 6f 6e 6c 79  am above is only
6ae0: 20 61 70 70 6c 69 63 61 62 6c 65 20 74 6f 20 5b   applicable to [
6af0: 53 41 56 45 50 4f 49 4e 54 5d 0a 74 72 61 6e 73  SAVEPOINT].trans
6b00: 61 63 74 69 6f 6e 73 2e 20 20 5e 41 6e 20 61 74  actions.  ^An at
6b10: 74 65 6d 70 74 20 74 6f 20 69 6e 76 6f 6b 65 20  tempt to invoke 
6b20: 74 68 65 20 42 45 47 49 4e 20 63 6f 6d 6d 61 6e  the BEGIN comman
6b30: 64 20 77 69 74 68 69 6e 0a 61 20 74 72 61 6e 73  d within.a trans
6b40: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 66 61 69 6c  action will fail
6b50: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2c 20   with an error, 
6b60: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
6b70: 65 74 68 65 72 0a 74 68 65 20 74 72 61 6e 73 61  ether.the transa
6b80: 63 74 69 6f 6e 20 77 61 73 20 73 74 61 72 74 65  ction was starte
6b90: 64 20 62 79 20 5b 53 41 56 45 50 4f 49 4e 54 5d  d by [SAVEPOINT]
6ba0: 20 6f 72 20 61 20 70 72 69 6f 72 20 42 45 47 49   or a prior BEGI
6bb0: 4e 2e 0a 5e 54 68 65 20 43 4f 4d 4d 49 54 20 63  N..^The COMMIT c
6bc0: 6f 6d 6d 61 6e 64 20 61 6e 64 20 74 68 65 20 52  ommand and the R
6bd0: 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20  OLLBACK command 
6be0: 77 69 74 68 6f 75 74 20 74 68 65 20 54 4f 20 63  without the TO c
6bf0: 6c 61 75 73 65 0a 77 6f 72 6b 20 74 68 65 20 73  lause.work the s
6c00: 61 6d 65 20 6f 6e 20 5b 53 41 56 45 50 4f 49 4e  ame on [SAVEPOIN
6c10: 54 5d 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  T] transactions 
6c20: 61 73 20 74 68 65 79 20 64 6f 20 77 69 74 68 20  as they do with 
6c30: 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 73 74 61  transactions.sta
6c40: 72 74 65 64 20 62 79 20 42 45 47 49 4e 2e 3c 2f  rted by BEGIN.</
6c50: 70 3e 0a 0a 3c 68 33 3e 52 65 61 64 20 74 72 61  p>..<h3>Read tra
6c60: 6e 73 61 63 74 69 6f 6e 73 20 76 65 72 73 75 73  nsactions versus
6c70: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
6c80: 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51 4c  ons</h3>..<p>SQL
6c90: 69 74 65 20 63 75 72 72 65 6e 74 20 73 75 70 70  ite current supp
6ca0: 6f 72 74 73 20 6d 75 6c 74 69 70 6c 65 20 73 69  orts multiple si
6cb0: 6d 75 6c 74 61 6e 65 6f 75 73 20 72 65 61 64 20  multaneous read 
6cc0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 63 6f 6d  transactions.com
6cd0: 69 6e 67 20 66 72 6f 6d 20 73 65 70 61 72 61 74  ing from separat
6ce0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
6cf0: 63 74 69 6f 6e 73 2c 20 70 6f 73 73 69 62 6c 79  ctions, possibly
6d00: 20 69 6e 20 73 65 70 61 72 61 74 65 0a 74 68 72   in separate.thr
6d10: 65 61 64 73 20 6f 72 20 70 72 6f 63 65 73 73 65  eads or processe
6d20: 73 2c 20 62 75 74 20 6f 6e 6c 79 20 6f 6e 65 20  s, but only one 
6d30: 73 69 6d 75 6c 74 61 6e 65 6f 75 73 20 77 72 69  simultaneous wri
6d40: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a  te transaction..
6d50: 3c 70 3e 0a 0a 3c 70 3e 41 20 72 65 61 64 20 74  <p>..<p>A read t
6d60: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 75 73  ransaction is us
6d70: 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  ed for reading o
6d80: 6e 6c 79 2e 20 20 41 20 77 72 69 74 65 20 74 72  nly.  A write tr
6d90: 61 6e 73 61 63 74 69 6f 6e 0a 61 6c 6c 6f 77 73  ansaction.allows
6da0: 20 62 6f 74 68 20 72 65 61 64 69 6e 67 20 61 6e   both reading an
6db0: 64 20 77 72 69 74 69 6e 67 2e 20 20 41 20 72 65  d writing.  A re
6dc0: 61 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad transaction i
6dd0: 73 20 73 74 61 72 74 65 64 0a 62 79 20 61 20 53  s started.by a S
6de0: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c  ELECT statement,
6df0: 20 61 6e 64 20 61 20 77 72 69 74 65 20 74 72 61   and a write tra
6e00: 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 74 61 72  nsaction is star
6e10: 74 65 64 20 62 79 20 0a 73 74 61 74 65 6d 65 6e  ted by .statemen
6e20: 74 73 20 6c 69 6b 65 20 43 52 45 41 54 45 2c 20  ts like CREATE, 
6e30: 44 45 4c 45 54 45 2c 20 44 52 4f 50 2c 20 49 4e  DELETE, DROP, IN
6e40: 53 45 52 54 2c 20 6f 72 20 55 50 44 41 54 45 20  SERT, or UPDATE 
6e50: 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 0a 22 77  (collectively."w
6e60: 72 69 74 65 20 73 74 61 74 65 6d 65 6e 74 73 22  rite statements"
6e70: 29 2e 20 20 49 66 20 61 20 77 72 69 74 65 20 73  ).  If a write s
6e80: 74 61 74 65 6d 65 6e 74 20 6f 63 63 75 72 73 20  tatement occurs 
6e90: 77 68 69 6c 65 0a 61 20 72 65 61 64 20 74 72 61  while.a read tra
6ea0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 63 74 69  nsaction is acti
6eb0: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 72 65 61  ve, then the rea
6ec0: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  d transaction is
6ed0: 20 75 70 67 72 61 64 65 64 0a 74 6f 20 77 72 69   upgraded.to wri
6ee0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  te transaction i
6ef0: 66 20 70 6f 73 73 69 62 6c 65 2e 20 20 49 66 20  f possible.  If 
6f00: 73 6f 6d 65 20 6f 74 68 65 72 20 64 61 74 61 62  some other datab
6f10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 68  ase connection.h
6f20: 61 73 20 61 6c 72 65 61 64 79 20 6d 6f 64 69 66  as already modif
6f30: 69 65 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ied the database
6f40: 20 6f 72 20 69 73 20 61 6c 72 65 61 64 79 20 69   or is already i
6f50: 6e 20 74 68 65 20 70 72 6f 63 65 73 73 20 6f 66  n the process of
6f60: 0a 6d 6f 64 69 66 79 69 6e 67 20 74 68 65 20 64  .modifying the d
6f70: 61 74 61 62 61 73 65 2c 20 74 68 65 6e 20 75 70  atabase, then up
6f80: 67 72 61 64 69 6e 67 20 74 6f 20 61 20 77 72 69  grading to a wri
6f90: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  te transaction i
6fa0: 73 0a 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  s.not possible a
6fb0: 6e 64 20 74 68 65 20 77 72 69 74 65 20 73 74 61  nd the write sta
6fc0: 74 65 6d 65 6e 74 20 77 69 6c 6c 20 66 61 69 6c  tement will fail
6fd0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 42 55   with [SQLITE_BU
6fe0: 53 59 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57  SY]..</p>..<p>.W
6ff0: 68 69 6c 65 20 61 20 72 65 61 64 20 74 72 61 6e  hile a read tran
7000: 73 61 63 74 69 6f 6e 20 69 73 20 61 63 74 69 76  saction is activ
7010: 65 2c 20 61 6e 79 20 63 68 61 6e 67 65 73 20 74  e, any changes t
7020: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
7030: 68 61 74 0a 61 72 65 20 69 6d 70 6c 65 6d 65 6e  hat.are implemen
7040: 74 65 64 20 62 79 20 73 65 70 61 72 61 74 65 20  ted by separate 
7050: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7060: 69 6f 6e 73 20 77 69 6c 6c 20 6e 6f 74 20 62 65  ions will not be
7070: 20 73 65 65 6e 0a 62 79 20 74 68 65 20 64 61 74   seen.by the dat
7080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7090: 20 74 68 61 74 20 73 74 61 72 74 65 64 20 74 68   that started th
70a0: 65 20 72 65 61 64 20 74 72 61 6e 73 61 63 74 69  e read transacti
70b0: 6f 6e 2e 20 20 49 66 20 64 61 74 61 62 61 73 65  on.  If database
70c0: 0a 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73  .connection X is
70d0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
70e0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 69 74 20  transaction, it 
70f0: 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74  is possible that
7100: 20 73 6f 6d 65 0a 6f 74 68 65 72 20 64 61 74 61   some.other data
7110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
7120: 59 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  Y might change t
7130: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
7140: 65 20 64 61 74 61 62 61 73 65 0a 77 68 69 6c 65  e database.while
7150: 20 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e   X's transaction
7160: 20 69 73 20 73 74 69 6c 6c 20 6f 70 65 6e 2c 20   is still open, 
7170: 68 6f 77 65 76 65 72 20 58 20 77 69 6c 6c 20 6e  however X will n
7180: 6f 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 65  ot be able to se
7190: 65 20 0a 74 68 6f 73 65 20 63 68 61 6e 67 65 73  e .those changes
71a0: 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
71b0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 65 6e 64   transaction end
71c0: 73 2e 20 20 57 68 69 6c 65 20 69 74 73 20 72 65  s.  While its re
71d0: 61 64 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad.transaction i
71e0: 73 20 61 63 74 69 76 65 2c 20 58 20 77 69 6c 6c  s active, X will
71f0: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 65 65   continue to see
7200: 20 61 6e 20 68 69 73 74 6f 72 69 63 20 73 6e 61   an historic sna
7210: 70 73 68 6f 74 0a 74 68 65 20 64 61 74 61 62 61  pshot.the databa
7220: 73 65 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  se prior to the 
7230: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
7240: 74 65 64 20 62 79 20 59 2e 0a 3c 2f 70 3e 0a 0a  ted by Y..</p>..
7250: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
7260: 74 20 69 6d 6d 65 64 69 61 74 65 20 7b 42 45 47  t immediate {BEG
7270: 49 4e 20 49 4d 4d 45 44 49 41 54 45 7d 20 7b 42  IN IMMEDIATE} {B
7280: 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 7d 3c  EGIN EXCLUSIVE}<
7290: 2f 74 63 6c 3e 0a 3c 68 33 3e 44 45 46 45 52 52  /tcl>.<h3>DEFERR
72a0: 45 44 2c 20 49 4d 4d 45 44 49 41 54 45 2c 20 61  ED, IMMEDIATE, a
72b0: 6e 64 20 45 58 43 4c 55 53 49 56 45 20 74 72 61  nd EXCLUSIVE tra
72c0: 6e 73 61 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a  nsactions</h3>..
72d0: 3c 70 3e 0a 5e 54 72 61 6e 73 61 63 74 69 6f 6e  <p>.^Transaction
72e0: 73 20 63 61 6e 20 62 65 20 44 45 46 45 52 52 45  s can be DEFERRE
72f0: 44 2c 20 49 4d 4d 45 44 49 41 54 45 2c 20 6f 72  D, IMMEDIATE, or
7300: 20 45 58 43 4c 55 53 49 56 45 2e 0a 5e 54 68 65   EXCLUSIVE..^The
7310: 20 64 65 66 61 75 6c 74 20 74 72 61 6e 73 61 63   default transac
7320: 74 69 6f 6e 20 62 65 68 61 76 69 6f 72 20 69 73  tion behavior is
7330: 20 44 45 46 45 52 52 45 44 2e 0a 3c 2f 70 3e 0a   DEFERRED..</p>.
7340: 0a 3c 70 3e 0a 5e 44 45 46 45 52 52 45 44 20 6d  .<p>.^DEFERRED m
7350: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 72  eans that the tr
7360: 61 6e 73 61 63 74 69 6f 6e 20 64 6f 65 73 20 6e  ansaction does n
7370: 6f 74 20 61 63 74 75 61 6c 6c 79 0a 73 74 61 72  ot actually.star
7380: 74 20 75 6e 74 69 6c 20 74 68 65 20 64 61 74 61  t until the data
7390: 62 61 73 65 20 69 73 20 66 69 72 73 74 20 61 63  base is first ac
73a0: 63 65 73 73 65 64 2e 20 20 5e 49 6e 74 65 72 6e  cessed.  ^Intern
73b0: 61 6c 6c 79 2c 0a 74 68 65 20 42 45 47 49 4e 20  ally,.the BEGIN 
73c0: 44 45 46 45 52 52 52 45 44 20 73 74 61 74 65 6d  DEFERRRED statem
73d0: 65 6e 74 20 6d 65 72 65 6c 79 20 73 65 74 73 20  ent merely sets 
73e0: 61 20 66 6c 61 67 20 6f 6e 20 74 68 65 20 64 61  a flag on the da
73f0: 74 61 62 61 73 65 20 0a 63 6f 6e 6e 65 63 74 69  tabase .connecti
7400: 6f 6e 20 74 68 61 74 20 74 75 72 6e 73 20 6f 66  on that turns of
7410: 66 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  f the automatic 
7420: 63 6f 6d 6d 69 74 20 74 68 61 74 20 77 6f 75 6c  commit that woul
7430: 64 20 6e 6f 72 6d 61 6c 6c 79 0a 6f 63 63 75 72  d normally.occur
7440: 20 77 68 65 6e 20 74 68 65 20 6c 61 73 74 20 73   when the last s
7450: 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
7460: 73 2e 20 20 54 68 69 73 20 63 61 75 73 65 73 20  s.  This causes 
7470: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  the transaction.
7480: 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69  that is automati
7490: 63 61 6c 6c 79 20 73 74 61 72 74 65 64 20 74 6f  cally started to
74a0: 20 70 65 72 73 69 73 74 20 75 6e 74 69 6c 20 61   persist until a
74b0: 6e 20 65 78 70 6c 69 63 69 74 0a 43 4f 4d 4d 49  n explicit.COMMI
74c0: 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 20 6f 72  T or ROLLBACK or
74d0: 20 75 6e 74 69 6c 20 61 20 72 6f 6c 6c 62 61 63   until a rollbac
74e0: 6b 20 69 73 20 70 72 6f 76 6f 6b 65 64 20 62 79  k is provoked by
74f0: 20 61 6e 20 65 72 72 6f 72 0a 6f 72 20 61 6e 20   an error.or an 
7500: 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 4f 4c 4c  ON CONFLICT ROLL
7510: 42 41 43 4b 20 63 6c 61 75 73 65 2e 20 20 49 66  BACK clause.  If
7520: 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
7530: 6d 65 6e 74 20 61 66 74 65 72 0a 42 45 47 49 4e  ment after.BEGIN
7540: 20 44 45 46 45 52 52 45 44 20 69 73 20 61 20 53   DEFERRED is a S
7550: 45 4c 45 43 54 2c 20 74 68 65 6e 20 61 20 72 65  ELECT, then a re
7560: 61 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad transaction i
7570: 73 20 73 74 61 72 74 65 64 2e 0a 53 75 62 73 65  s started..Subse
7580: 71 75 65 6e 74 20 77 72 69 74 65 20 73 74 61 74  quent write stat
7590: 65 6d 65 6e 74 73 20 77 69 6c 6c 20 75 70 67 72  ements will upgr
75a0: 61 64 65 20 74 68 65 20 74 72 61 6e 73 61 63 74  ade the transact
75b0: 69 6f 6e 20 74 6f 20 61 0a 77 72 69 74 65 20 74  ion to a.write t
75c0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 66 20 70 6f  ransaction if po
75d0: 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 74 75 72  ssible, or retur
75e0: 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
75f0: 49 66 20 74 68 65 0a 66 69 72 73 74 20 73 74 61  If the.first sta
7600: 74 65 6d 65 6e 74 20 61 66 74 65 72 20 42 45 47  tement after BEG
7610: 49 4e 20 44 45 46 45 52 52 45 44 20 69 73 20 61  IN DEFERRED is a
7620: 20 77 72 69 74 65 20 73 74 61 74 65 6d 65 6e 74   write statement
7630: 2c 20 74 68 65 6e 0a 61 20 77 72 69 74 65 20 74  , then.a write t
7640: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 74  ransaction is st
7650: 61 72 74 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  arted..</p>..<p>
7660: 0a 5e 49 4d 4d 45 44 49 41 54 45 20 63 61 75 73  .^IMMEDIATE caus
7670: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
7680: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 73 74 61  onnection to sta
7690: 72 74 20 61 20 6e 65 77 20 77 72 69 74 65 0a 69  rt a new write.i
76a0: 6d 6d 65 64 69 61 74 65 6c 79 2c 20 77 69 74 68  mmediately, with
76b0: 6f 75 74 20 77 61 69 74 69 6e 67 20 66 6f 72 20  out waiting for 
76c0: 61 20 77 72 69 74 65 73 20 73 74 61 74 65 6d 65  a writes stateme
76d0: 6e 74 2e 20 20 54 68 65 20 0a 42 45 47 49 4e 20  nt.  The .BEGIN 
76e0: 49 4d 4d 45 44 49 41 54 45 20 6d 69 67 68 74 20  IMMEDIATE might 
76f0: 66 61 69 6c 20 77 69 74 68 20 5b 53 51 4c 49 54  fail with [SQLIT
7700: 45 5f 42 55 53 59 5d 20 69 66 20 61 6e 6f 74 68  E_BUSY] if anoth
7710: 65 72 20 77 72 69 74 65 0a 74 72 61 6e 73 61 63  er write.transac
7720: 74 69 6f 6e 20 69 73 20 61 6c 72 65 61 64 79 20  tion is already 
7730: 61 63 74 69 76 65 20 6f 6e 20 61 6e 6f 74 68 65  active on anothe
7740: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
7750: 63 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  ction..</p>..<p>
7760: 0a 5e 45 58 43 4c 55 53 49 56 45 20 69 73 20 73  .^EXCLUSIVE is s
7770: 69 6d 69 6c 61 72 20 74 6f 20 49 4d 4d 45 44 49  imilar to IMMEDI
7780: 41 54 45 20 69 6e 20 74 68 61 74 20 61 20 77 72  ATE in that a wr
7790: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ite transaction.
77a0: 69 73 20 73 74 61 72 74 65 64 20 69 6d 6d 65 64  is started immed
77b0: 69 61 74 65 6c 79 2e 20 20 45 58 43 4c 55 53 49  iately.  EXCLUSI
77c0: 56 45 20 61 6e 64 20 49 4d 4d 45 44 49 41 54 45  VE and IMMEDIATE
77d0: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 69 6e   are the same.in
77e0: 20 5b 57 41 4c 20 6d 6f 64 65 5d 2c 20 62 75 74   [WAL mode], but
77f0: 20 69 6e 20 6f 74 68 65 72 20 6a 6f 75 72 6e 61   in other journa
7800: 6c 69 6e 67 20 6d 6f 64 65 73 2c 20 45 58 43 4c  ling modes, EXCL
7810: 55 53 49 56 45 20 70 72 65 76 65 6e 74 73 0a 6f  USIVE prevents.o
7820: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
7830: 6e 6e 65 63 74 69 6f 6e 73 20 66 72 6f 6d 20 72  nnections from r
7840: 65 61 64 69 6e 67 20 74 68 65 20 64 61 74 61 62  eading the datab
7850: 61 73 65 20 77 68 69 6c 65 20 74 68 65 0a 74 72  ase while the.tr
7860: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 75 6e 64  ansaction is und
7870: 65 72 77 61 79 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33  erway..</p>..<h3
7880: 3e 49 6d 70 6c 69 63 69 74 20 76 65 72 73 75 73  >Implicit versus
7890: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
78a0: 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  ctions</h3>..<p>
78b0: 0a 41 6e 20 69 6d 70 6c 69 63 69 74 20 74 72 61  .An implicit tra
78c0: 6e 73 61 63 74 69 6f 6e 20 28 61 20 74 72 61 6e  nsaction (a tran
78d0: 73 61 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  saction that is 
78e0: 73 74 61 72 74 65 64 20 61 75 74 6f 6d 61 74 69  started automati
78f0: 63 61 6c 6c 79 2c 0a 6e 6f 74 20 61 20 74 72 61  cally,.not a tra
7900: 6e 73 61 63 74 69 6f 6e 20 73 74 61 72 74 65 64  nsaction started
7910: 20 62 79 20 42 45 47 49 4e 29 20 69 73 20 63 6f   by BEGIN) is co
7920: 6d 6d 69 74 74 65 64 20 61 75 74 6f 6d 61 74 69  mmitted automati
7930: 63 61 6c 6c 79 20 77 68 65 6e 0a 74 68 65 20 6c  cally when.the l
7940: 61 73 74 20 61 63 74 69 76 65 20 73 74 61 74 65  ast active state
7950: 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
7960: 41 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  A statement fini
7970: 73 68 65 73 20 77 68 65 6e 20 69 74 73 0a 6c 61  shes when its.la
7980: 73 74 20 63 75 72 73 6f 72 20 63 6c 6f 73 65 73  st cursor closes
7990: 2c 20 77 68 69 63 68 20 69 73 20 67 75 61 72 61  , which is guara
79a0: 6e 74 65 65 64 20 74 6f 20 68 61 70 70 65 6e 20  nteed to happen 
79b0: 77 68 65 6e 20 74 68 65 0a 70 72 65 70 61 72 65  when the.prepare
79c0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 5b  d statement is [
79d0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
79e0: 7c 20 72 65 73 65 74 5d 20 6f 72 0a 5b 73 71 6c  | reset] or.[sql
79f0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
7a00: 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 2e 20 20 53  | finalized].  S
7a10: 6f 6d 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  ome statements m
7a20: 69 67 68 74 20 22 66 69 6e 69 73 68 22 0a 66 6f  ight "finish".fo
7a30: 72 20 74 68 65 20 70 75 72 70 6f 73 65 20 6f 66  r the purpose of
7a40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
7a50: 74 72 6f 6c 20 70 72 69 6f 72 20 74 6f 20 62 65  trol prior to be
7a60: 69 6e 67 20 72 65 73 65 74 20 6f 72 20 66 69 6e  ing reset or fin
7a70: 61 6c 69 7a 65 64 2c 0a 62 75 74 20 74 68 65 72  alized,.but ther
7a80: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
7a90: 65 20 6f 66 20 74 68 69 73 2e 20 20 54 68 65 20  e of this.  The 
7aa0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 65 6e 73 75  only way to ensu
7ab0: 72 65 20 74 68 61 74 20 61 0a 73 74 61 74 65 6d  re that a.statem
7ac0: 65 6e 74 20 68 61 73 20 22 66 69 6e 69 73 68 65  ent has "finishe
7ad0: 64 22 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  d" is to invoke 
7ae0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
7af0: 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 66 69  ] or.[sqlite3_fi
7b00: 6e 61 6c 69 7a 65 28 29 5d 20 6f 6e 20 74 68 61  nalize()] on tha
7b10: 74 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 6e  t statement.  An
7b20: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
7b30: 6c 6f 62 5d 20 75 73 65 64 20 66 6f 72 0a 69 6e  lob] used for.in
7b40: 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
7b50: 2f 4f 20 61 6c 73 6f 20 63 6f 75 6e 74 73 20 61  /O also counts a
7b60: 73 20 61 6e 20 75 6e 66 69 6e 69 73 68 65 64 20  s an unfinished 
7b70: 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 20 5b  statement..The [
7b80: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 66 69  sqlite3_blob] fi
7b90: 6e 69 73 68 65 73 20 77 68 65 6e 20 69 74 20 69  nishes when it i
7ba0: 73 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  s [sqlite3_blob_
7bb0: 63 6c 6f 73 65 28 29 20 7c 20 63 6c 6f 73 65 64  close() | closed
7bc0: 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 68  ]..</p>..<p>.^Th
7bd0: 65 20 65 78 70 6c 69 63 69 74 20 43 4f 4d 4d 49  e explicit COMMI
7be0: 54 20 63 6f 6d 6d 61 6e 64 20 72 75 6e 73 20 69  T command runs i
7bf0: 6d 6d 65 64 69 61 74 65 6c 79 2c 20 65 76 65 6e  mmediately, even
7c00: 20 69 66 20 74 68 65 72 65 20 61 72 65 0a 70 65   if there are.pe
7c10: 6e 64 69 6e 67 20 5b 53 45 4c 45 43 54 5d 20 73  nding [SELECT] s
7c20: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 48 6f 77  tatements.  ^How
7c30: 65 76 65 72 2c 20 69 66 20 74 68 65 72 65 20 61  ever, if there a
7c40: 72 65 20 70 65 6e 64 69 6e 67 0a 77 72 69 74 65  re pending.write
7c50: 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 74 68 65   operations, the
7c60: 20 43 4f 4d 4d 49 54 20 63 6f 6d 6d 61 6e 64 0a   COMMIT command.
7c70: 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
7c80: 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 5b 53 51  n error code [SQ
7c90: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 3c 2f 70 3e  LITE_BUSY]..</p>
7ca0: 0a 0a 3c 70 3e 0a 5e 41 6e 20 61 74 74 65 6d 70  ..<p>.^An attemp
7cb0: 74 20 74 6f 20 65 78 65 63 75 74 65 20 43 4f 4d  t to execute COM
7cc0: 4d 49 54 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  MIT might also r
7cd0: 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
7ce0: 49 54 45 5f 42 55 53 59 5d 20 72 65 74 75 72 6e  ITE_BUSY] return
7cf0: 20 63 6f 64 65 0a 69 66 20 61 6e 20 61 6e 6f 74   code.if an anot
7d00: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
7d10: 6f 63 65 73 73 20 68 61 73 20 61 6e 20 6f 70 65  ocess has an ope
7d20: 6e 20 72 65 61 64 20 63 6f 6e 6e 65 63 74 69 6f  n read connectio
7d30: 6e 2e 0a 5e 57 68 65 6e 20 43 4f 4d 4d 49 54 20  n..^When COMMIT 
7d40: 66 61 69 6c 73 20 69 6e 20 74 68 69 73 0a 77 61  fails in this.wa
7d50: 79 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  y, the transacti
7d60: 6f 6e 20 72 65 6d 61 69 6e 73 20 61 63 74 69 76  on remains activ
7d70: 65 20 61 6e 64 20 74 68 65 20 43 4f 4d 4d 49 54  e and the COMMIT
7d80: 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 64 20   can be retried 
7d90: 6c 61 74 65 72 0a 61 66 74 65 72 20 74 68 65 20  later.after the 
7da0: 72 65 61 64 65 72 20 68 61 73 20 68 61 64 20 61  reader has had a
7db0: 20 63 68 61 6e 63 65 20 74 6f 20 63 6c 65 61 72   chance to clear
7dc0: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 6e 20 76  ..</p>..<p>.In v
7dd0: 65 72 79 20 6f 6c 64 20 76 65 72 73 69 6f 6e 73  ery old versions
7de0: 20 6f 66 20 53 51 4c 69 74 65 20 28 62 65 66 6f   of SQLite (befo
7df0: 72 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  re version 3.7.1
7e00: 31 20 2d 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e  1 - [dateof:3.7.
7e10: 31 31 5d 29 0a 74 68 65 20 52 4f 4c 4c 42 41 43  11]).the ROLLBAC
7e20: 4b 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  K will fail with
7e30: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 0a   an error code .
7e40: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66  [SQLITE_BUSY] if
7e50: 20 74 68 65 72 65 20 61 72 65 20 61 6e 79 20 70   there are any p
7e60: 65 6e 64 69 6e 67 20 71 75 65 72 69 65 73 2e 20  ending queries. 
7e70: 20 5e 49 6e 20 6d 6f 72 65 20 72 65 63 65 6e 74   ^In more recent
7e80: 0a 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c  .versions of SQL
7e90: 69 74 65 2c 20 74 68 65 20 52 4f 4c 4c 42 41 43  ite, the ROLLBAC
7ea0: 4b 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 61  K will proceed a
7eb0: 6e 64 20 70 65 6e 64 69 6e 67 20 73 74 61 74 65  nd pending state
7ec0: 6d 65 6e 74 73 0a 77 69 6c 6c 20 6f 66 74 65 6e  ments.will often
7ed0: 20 62 65 20 61 62 6f 72 74 65 64 2c 20 63 61 75   be aborted, cau
7ee0: 73 69 6e 67 20 74 68 65 6d 20 74 6f 20 72 65 74  sing them to ret
7ef0: 75 72 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 41  urn an [SQLITE_A
7f00: 42 4f 52 54 5d 20 6f 72 0a 5b 53 51 4c 49 54 45  BORT] or.[SQLITE
7f10: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 5d  _ABORT_ROLLBACK]
7f20: 20 65 72 72 6f 72 2e 0a 5e 49 6e 20 53 51 4c 69   error..^In SQLi
7f30: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 38 2e 38  te version 3.8.8
7f40: 20 28 5b 64 61 74 65 6f 66 3a 33 2e 38 2e 38 5d   ([dateof:3.8.8]
7f50: 29 20 61 6e 64 20 6c 61 74 65 72 2c 0a 61 20 70  ) and later,.a p
7f60: 65 6e 64 69 6e 67 20 72 65 61 64 20 77 69 6c 6c  ending read will
7f70: 20 63 6f 6e 74 69 6e 75 65 20 66 75 6e 63 74 69   continue functi
7f80: 6f 6e 69 6e 67 0a 61 66 74 65 72 20 74 68 65 20  oning.after the 
7f90: 52 4f 4c 4c 42 41 43 4b 20 61 73 20 6c 6f 6e 67  ROLLBACK as long
7fa0: 20 61 73 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b   as the ROLLBACK
7fb0: 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
7fc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 73 63   the database.sc
7fd0: 68 65 6d 61 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  hema..</p>..<p>.
7fe0: 49 66 20 5b 50 52 41 47 4d 41 20 6a 6f 75 72 6e  If [PRAGMA journ
7ff0: 61 6c 5f 6d 6f 64 65 5d 20 69 73 20 73 65 74 20  al_mode] is set 
8000: 74 6f 20 4f 46 46 20 28 74 68 75 73 20 64 69 73  to OFF (thus dis
8010: 61 62 6c 69 6e 67 20 74 68 65 20 72 6f 6c 6c 62  abling the rollb
8020: 61 63 6b 20 6a 6f 75 72 6e 61 6c 0a 66 69 6c 65  ack journal.file
8030: 29 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  ) then the behav
8040: 69 6f 72 20 6f 66 20 74 68 65 20 52 4f 4c 4c 42  ior of the ROLLB
8050: 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75  ACK command is u
8060: 6e 64 65 66 69 6e 65 64 2e 0a 3c 2f 70 3e 0a 0a  ndefined..</p>..
8070: 3c 68 33 3e 52 65 73 70 6f 6e 73 65 20 54 6f 20  <h3>Response To 
8080: 45 72 72 6f 72 73 20 57 69 74 68 69 6e 20 41 20  Errors Within A 
8090: 54 72 61 6e 73 61 63 74 69 6f 6e 3c 2f 68 33 3e  Transaction</h3>
80a0: 0a 0a 3c 70 3e 20 5e 28 49 66 20 63 65 72 74 61  ..<p> ^(If certa
80b0: 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
80c0: 72 73 20 6f 63 63 75 72 20 77 69 74 68 69 6e 20  rs occur within 
80d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  a transaction, t
80e0: 68 65 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  he.transaction m
80f0: 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
8100: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
8110: 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
8120: 0a 65 72 72 6f 72 73 20 74 68 61 74 20 63 61 6e  .errors that can
8130: 20 63 61 75 73 65 20 61 6e 20 61 75 74 6f 6d 61   cause an automa
8140: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 69 6e 63  tic rollback inc
8150: 6c 75 64 65 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a  lude:</p>..<ul>.
8160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 46 55 4c  <li> [SQLITE_FUL
8170: 4c 5d 3a 20 64 61 74 61 62 61 73 65 20 6f 72 20  L]: database or 
8180: 64 69 73 6b 20 66 75 6c 6c 0a 3c 6c 69 3e 20 5b  disk full.<li> [
8190: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 3a 20 64  SQLITE_IOERR]: d
81a0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 0a 3c 6c  isk I/O error.<l
81b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  i> [SQLITE_BUSY]
81c0: 3a 20 64 61 74 61 62 61 73 65 20 69 6e 20 75 73  : database in us
81d0: 65 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f  e by another pro
81e0: 63 65 73 73 0a 3c 6c 69 3e 20 5b 53 51 4c 49 54  cess.<li> [SQLIT
81f0: 45 5f 4e 4f 4d 45 4d 5d 3a 20 6f 75 74 20 6f 72  E_NOMEM]: out or
8200: 20 6d 65 6d 6f 72 79 0a 3c 2f 75 6c 3e 29 5e 0a   memory.</ul>)^.
8210: 0a 3c 70 3e 0a 5e 46 6f 72 20 61 6c 6c 20 6f 66  .<p>.^For all of
8220: 20 74 68 65 73 65 20 65 72 72 6f 72 73 2c 20 53   these errors, S
8230: 51 4c 69 74 65 20 61 74 74 65 6d 70 74 73 20 74  QLite attempts t
8240: 6f 20 75 6e 64 6f 20 6a 75 73 74 20 74 68 65 20  o undo just the 
8250: 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 0a 69 74  one statement.it
8260: 20 77 61 73 20 77 6f 72 6b 69 6e 67 20 6f 6e 20   was working on 
8270: 61 6e 64 20 6c 65 61 76 65 20 63 68 61 6e 67 65  and leave change
8280: 73 20 66 72 6f 6d 20 70 72 69 6f 72 20 73 74 61  s from prior sta
8290: 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 74  tements within t
82a0: 68 65 0a 73 61 6d 65 20 74 72 61 6e 73 61 63 74  he.same transact
82b0: 69 6f 6e 20 69 6e 74 61 63 74 20 61 6e 64 20 63  ion intact and c
82c0: 6f 6e 74 69 6e 75 65 20 77 69 74 68 20 74 68 65  ontinue with the
82d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 5e   transaction.  ^
82e0: 48 6f 77 65 76 65 72 2c 20 0a 64 65 70 65 6e 64  However, .depend
82f0: 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 65  ing on the state
8300: 6d 65 6e 74 20 62 65 69 6e 67 20 65 76 61 6c 75  ment being evalu
8310: 61 74 65 64 20 61 6e 64 20 74 68 65 20 70 6f 69  ated and the poi
8320: 6e 74 20 61 74 20 77 68 69 63 68 20 74 68 65 0a  nt at which the.
8330: 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 69 74  error occurs, it
8340: 20 6d 69 67 68 74 20 62 65 20 6e 65 63 65 73 73   might be necess
8350: 61 72 79 20 66 6f 72 20 53 51 4c 69 74 65 20 74  ary for SQLite t
8360: 6f 20 72 6f 6c 6c 62 61 63 6b 20 61 6e 64 0a 63  o rollback and.c
8370: 61 6e 63 65 6c 20 74 68 65 20 65 6e 74 69 72 65  ancel the entire
8380: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 5e   transaction.  ^
8390: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  An application c
83a0: 61 6e 20 74 65 6c 6c 20 77 68 69 63 68 0a 63 6f  an tell which.co
83b0: 75 72 73 65 20 6f 66 20 61 63 74 69 6f 6e 20 53  urse of action S
83c0: 51 4c 69 74 65 20 74 6f 6f 6b 20 62 79 20 75 73  QLite took by us
83d0: 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69 74 65 33  ing the.[sqlite3
83e0: 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
83f0: 29 5d 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6e  )] C-language in
8400: 74 65 72 66 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 70  terface.</p>..<p
8410: 3e 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  >It is recommend
8420: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
8430: 69 6f 6e 73 20 72 65 73 70 6f 6e 64 20 74 6f 20  ions respond to 
8440: 74 68 65 20 65 72 72 6f 72 73 0a 6c 69 73 74 65  the errors.liste
8450: 64 20 61 62 6f 76 65 20 62 79 20 65 78 70 6c 69  d above by expli
8460: 63 69 74 6c 79 20 69 73 73 75 69 6e 67 20 61 20  citly issuing a 
8470: 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64  ROLLBACK command
8480: 2e 20 20 5e 49 66 20 74 68 65 20 0a 74 72 61 6e  .  ^If the .tran
8490: 73 61 63 74 69 6f 6e 20 68 61 73 20 61 6c 72 65  saction has alre
84a0: 61 64 79 20 62 65 65 6e 20 72 6f 6c 6c 65 64 20  ady been rolled 
84b0: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
84c0: 6c 79 0a 62 79 20 74 68 65 20 65 72 72 6f 72 20  ly.by the error 
84d0: 72 65 73 70 6f 6e 73 65 2c 20 74 68 65 6e 20 74  response, then t
84e0: 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d  he ROLLBACK comm
84f0: 61 6e 64 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  and will fail wi
8500: 74 68 20 61 6e 0a 65 72 72 6f 72 2c 20 62 75 74  th an.error, but
8510: 20 6e 6f 20 68 61 72 6d 20 69 73 20 63 61 75 73   no harm is caus
8520: 65 64 20 62 79 20 74 68 69 73 2e 3c 2f 70 3e 0a  ed by this.</p>.
8530: 0a 3c 70 3e 46 75 74 75 72 65 20 76 65 72 73 69  .<p>Future versi
8540: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
8550: 79 20 65 78 74 65 6e 64 20 74 68 65 20 6c 69 73  y extend the lis
8560: 74 20 6f 66 20 65 72 72 6f 72 73 20 77 68 69 63  t of errors whic
8570: 68 0a 6d 69 67 68 74 20 63 61 75 73 65 20 61 75  h.might cause au
8580: 74 6f 6d 61 74 69 63 20 74 72 61 6e 73 61 63 74  tomatic transact
8590: 69 6f 6e 20 72 6f 6c 6c 62 61 63 6b 2e 20 20 46  ion rollback.  F
85a0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
85b0: 66 0a 53 51 4c 69 74 65 20 6d 69 67 68 74 20 63  f.SQLite might c
85c0: 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
85d0: 72 65 73 70 6f 6e 73 65 2e 20 20 49 6e 20 70 61  response.  In pa
85e0: 72 74 69 63 75 6c 61 72 2c 20 77 65 20 6d 61 79  rticular, we may
85f0: 0a 63 68 6f 6f 73 65 20 74 6f 20 73 69 6d 70 6c  .choose to simpl
8600: 69 66 79 20 74 68 65 20 69 6e 74 65 72 66 61 63  ify the interfac
8610: 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
8620: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 62  ions of SQLite b
8630: 79 0a 63 61 75 73 69 6e 67 20 74 68 65 20 65 72  y.causing the er
8640: 72 6f 72 73 20 61 62 6f 76 65 20 74 6f 20 66 6f  rors above to fo
8650: 72 63 65 20 61 6e 20 75 6e 63 6f 6e 64 69 74 69  rce an unconditi
8660: 6f 6e 61 6c 20 72 6f 6c 6c 62 61 63 6b 2e 3c 2f  onal rollback.</
8670: 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  p>..<tcl>.######
8680: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8690: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
86a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
86b0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
86c0: 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
86d0: 6e 20 7b 53 41 56 45 50 4f 49 4e 54 7d 20 73 61  n {SAVEPOINT} sa
86e0: 76 65 70 6f 69 6e 74 20 7b 53 41 56 45 50 4f 49  vepoint {SAVEPOI
86f0: 4e 54 20 52 45 4c 45 41 53 45 7d 0a 0a 52 65 63  NT RELEASE}..Rec
8700: 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
8710: 72 61 6d 20 73 61 76 65 70 6f 69 6e 74 2d 73 74  ram savepoint-st
8720: 6d 74 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  mt.RecursiveBubb
8730: 6c 65 44 69 61 67 72 61 6d 20 72 65 6c 65 61 73  leDiagram releas
8740: 65 2d 73 74 6d 74 0a 52 65 63 75 72 73 69 76 65  e-stmt.Recursive
8750: 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 6f  BubbleDiagram ro
8760: 6c 6c 62 61 63 6b 2d 73 74 6d 74 0a 3c 2f 74 63  llback-stmt.</tc
8770: 6c 3e 0a 0a 3c 70 3e 20 5e 53 41 56 45 50 4f 49  l>..<p> ^SAVEPOI
8780: 4e 54 73 20 61 72 65 20 61 20 6d 65 74 68 6f 64  NTs are a method
8790: 20 6f 66 20 63 72 65 61 74 69 6e 67 20 74 72 61   of creating tra
87a0: 6e 73 61 63 74 69 6f 6e 73 2c 20 73 69 6d 69 6c  nsactions, simil
87b0: 61 72 20 74 6f 0a 5b 42 45 47 49 4e 5d 20 61 6e  ar to.[BEGIN] an
87c0: 64 20 5b 43 4f 4d 4d 49 54 5d 2c 20 65 78 63 65  d [COMMIT], exce
87d0: 70 74 20 74 68 61 74 20 74 68 65 20 53 41 56 45  pt that the SAVE
87e0: 50 4f 49 4e 54 20 61 6e 64 20 52 45 4c 45 41 53  POINT and RELEAS
87f0: 45 20 63 6f 6d 6d 61 6e 64 73 0a 61 72 65 20 6e  E commands.are n
8800: 61 6d 65 64 20 61 6e 64 20 6d 61 79 20 62 65 20  amed and may be 
8810: 6e 65 73 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e  nested.</p>..<p>
8820: 20 5e 54 68 65 20 53 41 56 45 50 4f 49 4e 54 20   ^The SAVEPOINT 
8830: 63 6f 6d 6d 61 6e 64 20 73 74 61 72 74 73 20 61  command starts a
8840: 20 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e   new transaction
8850: 20 77 69 74 68 20 61 20 6e 61 6d 65 2e 0a 5e 54   with a name..^T
8860: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6e  he transaction n
8870: 61 6d 65 73 20 6e 65 65 64 20 6e 6f 74 20 62 65  ames need not be
8880: 20 75 6e 69 71 75 65 2e 0a 5e 28 41 20 53 41 56   unique..^(A SAV
8890: 45 50 4f 49 4e 54 20 63 61 6e 20 62 65 20 73 74  EPOINT can be st
88a0: 61 72 74 65 64 20 65 69 74 68 65 72 20 77 69 74  arted either wit
88b0: 68 69 6e 20 6f 72 20 6f 75 74 73 69 64 65 20 6f  hin or outside o
88c0: 66 0a 61 20 5b 42 45 47 49 4e 5d 2e 2e 2e 5b 43  f.a [BEGIN]...[C
88d0: 4f 4d 4d 49 54 5d 2e 29 5e 20 20 5e 28 57 68 65  OMMIT].)^  ^(Whe
88e0: 6e 20 61 20 53 41 56 45 50 4f 49 4e 54 20 69 73  n a SAVEPOINT is
88f0: 20 74 68 65 20 6f 75 74 65 72 2d 6d 6f 73 74 20   the outer-most 
8900: 73 61 76 65 70 6f 69 6e 74 0a 61 6e 64 20 69 74  savepoint.and it
8910: 20 69 73 20 6e 6f 74 20 77 69 74 68 69 6e 20 61   is not within a
8920: 20 5b 42 45 47 49 4e 5d 2e 2e 2e 5b 43 4f 4d 4d   [BEGIN]...[COMM
8930: 49 54 5d 20 74 68 65 6e 20 74 68 65 20 62 65 68  IT] then the beh
8940: 61 76 69 6f 72 20 69 73 20 74 68 65 0a 73 61 6d  avior is the.sam
8950: 65 20 61 73 20 42 45 47 49 4e 20 44 45 46 45 52  e as BEGIN DEFER
8960: 52 45 44 20 54 52 41 4e 53 41 43 54 49 4f 4e 2e  RED TRANSACTION.
8970: 29 5e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  )^</p>..<p>^The 
8980: 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d  ROLLBACK TO comm
8990: 61 6e 64 20 72 65 76 65 72 74 73 20 74 68 65 20  and reverts the 
89a0: 73 74 61 74 65 20 6f 66 20 74 68 65 20 64 61 74  state of the dat
89b0: 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 77 68  abase back to wh
89c0: 61 74 0a 69 74 20 77 61 73 20 6a 75 73 74 20 61  at.it was just a
89d0: 66 74 65 72 20 74 68 65 20 63 6f 72 72 65 73 70  fter the corresp
89e0: 6f 6e 64 69 6e 67 20 53 41 56 45 50 4f 49 4e 54  onding SAVEPOINT
89f0: 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 75 6e  .  ^Note that un
8a00: 6c 69 6b 65 20 74 68 61 74 0a 70 6c 61 69 6e 20  like that.plain 
8a10: 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f 6d 6d 61  [ROLLBACK] comma
8a20: 6e 64 20 28 77 69 74 68 6f 75 74 20 74 68 65 20  nd (without the 
8a30: 54 4f 20 6b 65 79 77 6f 72 64 29 20 74 68 65 20  TO keyword) the 
8a40: 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d  ROLLBACK TO comm
8a50: 61 6e 64 0a 64 6f 65 73 20 6e 6f 74 20 63 61 6e  and.does not can
8a60: 63 65 6c 20 74 68 65 20 74 72 61 6e 73 61 63 74  cel the transact
8a70: 69 6f 6e 2e 20 20 5e 49 6e 73 74 65 61 64 20 6f  ion.  ^Instead o
8a80: 66 20 63 61 6e 63 65 6c 6c 69 6e 67 20 74 68 65  f cancelling the
8a90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 0a 74 68   transaction,.th
8aa0: 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f  e ROLLBACK TO co
8ab0: 6d 6d 61 6e 64 20 72 65 73 74 61 72 74 73 20 74  mmand restarts t
8ac0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
8ad0: 67 61 69 6e 20 61 74 20 74 68 65 20 62 65 67 69  gain at the begi
8ae0: 6e 6e 69 6e 67 2e 0a 5e 41 6c 6c 20 69 6e 74 65  nning..^All inte
8af0: 72 76 65 6e 69 6e 67 20 53 41 56 45 50 4f 49 4e  rvening SAVEPOIN
8b00: 54 73 20 61 72 65 20 63 61 6e 63 65 6c 65 64 2c  Ts are canceled,
8b10: 20 68 6f 77 65 76 65 72 2e 3c 2f 70 3e 0a 0a 3c   however.</p>..<
8b20: 70 3e 5e 54 68 65 20 52 45 4c 45 41 53 45 20 63  p>^The RELEASE c
8b30: 6f 6d 6d 61 6e 64 20 69 73 20 6c 69 6b 65 20 61  ommand is like a
8b40: 20 5b 43 4f 4d 4d 49 54 5d 20 66 6f 72 20 61 20   [COMMIT] for a 
8b50: 53 41 56 45 50 4f 49 4e 54 2e 0a 5e 54 68 65 20  SAVEPOINT..^The 
8b60: 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20  RELEASE command 
8b70: 63 61 75 73 65 73 20 61 6c 6c 20 73 61 76 65 70  causes all savep
8b80: 6f 69 6e 74 73 20 62 61 63 6b 20 74 6f 20 61 6e  oints back to an
8b90: 64 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  d including the 
8ba0: 0a 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 61 76  .most recent sav
8bb0: 65 70 6f 69 6e 74 20 77 69 74 68 20 61 20 6d 61  epoint with a ma
8bc0: 74 63 68 69 6e 67 20 6e 61 6d 65 20 74 6f 20 62  tching name to b
8bd0: 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74  e removed from t
8be0: 68 65 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20  he .transaction 
8bf0: 73 74 61 63 6b 2e 20 20 5e 54 68 65 20 52 45 4c  stack.  ^The REL
8c00: 45 41 53 45 20 6f 66 20 61 6e 20 69 6e 6e 65 72  EASE of an inner
8c10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 64 6f 65   transaction.doe
8c20: 73 20 6e 6f 74 20 63 61 75 73 65 20 61 6e 79 20  s not cause any 
8c30: 63 68 61 6e 67 65 73 20 74 6f 20 62 65 20 77 72  changes to be wr
8c40: 69 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74  itten to the dat
8c50: 61 62 61 73 65 20 66 69 6c 65 3b 20 69 74 20 6d  abase file; it m
8c60: 65 72 65 6c 79 0a 72 65 6d 6f 76 65 73 20 73 61  erely.removes sa
8c70: 76 65 70 6f 69 6e 74 73 20 66 72 6f 6d 20 74 68  vepoints from th
8c80: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 74  e transaction st
8c90: 61 63 6b 20 73 75 63 68 20 74 68 61 74 20 69 74  ack such that it
8ca0: 20 69 73 0a 6e 6f 20 6c 6f 6e 67 65 72 20 70 6f   is.no longer po
8cb0: 73 73 69 62 6c 65 20 74 6f 20 52 4f 4c 4c 42 41  ssible to ROLLBA
8cc0: 43 4b 20 54 4f 20 74 68 6f 73 65 20 73 61 76 65  CK TO those save
8cd0: 70 6f 69 6e 74 73 2e 0a 5e 49 66 20 61 20 52 45  points..^If a RE
8ce0: 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 72 65  LEASE command re
8cf0: 6c 65 61 73 65 73 20 74 68 65 20 6f 75 74 65 72  leases the outer
8d00: 6d 6f 73 74 20 73 61 76 65 70 6f 69 6e 74 2c 20  most savepoint, 
8d10: 73 6f 0a 74 68 61 74 20 74 68 65 20 74 72 61 6e  so.that the tran
8d20: 73 61 63 74 69 6f 6e 20 73 74 61 63 6b 20 62 65  saction stack be
8d30: 63 6f 6d 65 73 20 65 6d 70 74 79 2c 20 74 68 65  comes empty, the
8d40: 6e 20 52 45 4c 45 41 53 45 20 69 73 20 74 68 65  n RELEASE is the
8d50: 20 73 61 6d 65 0a 61 73 20 5b 43 4f 4d 4d 49 54   same.as [COMMIT
8d60: 5d 2e 0a 5e 54 68 65 20 5b 43 4f 4d 4d 49 54 5d  ]..^The [COMMIT]
8d70: 20 63 6f 6d 6d 61 6e 64 20 6d 61 79 20 62 65 20   command may be 
8d80: 75 73 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  used to release 
8d90: 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 61  all savepoints a
8da0: 6e 64 0a 63 6f 6d 6d 69 74 20 74 68 65 20 74 72  nd.commit the tr
8db0: 61 6e 73 61 63 74 69 6f 6e 20 65 76 65 6e 20 69  ansaction even i
8dc0: 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
8dd0: 6e 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79  n was originally
8de0: 20 73 74 61 72 74 65 64 0a 62 79 20 61 20 53 41   started.by a SA
8df0: 56 45 50 4f 49 4e 54 20 63 6f 6d 6d 61 6e 64 20  VEPOINT command 
8e00: 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 42 45  instead of a [BE
8e10: 47 49 4e 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70  GIN] command.</p
8e20: 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 73 61  >..<p>^If the sa
8e30: 76 65 70 6f 69 6e 74 2d 6e 61 6d 65 20 69 6e 20  vepoint-name in 
8e40: 61 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e  a RELEASE comman
8e50: 64 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  d does not match
8e60: 20 61 6e 79 0a 73 61 76 65 70 6f 69 6e 74 20 63   any.savepoint c
8e70: 75 72 72 65 6e 74 6c 79 20 69 6e 20 74 68 65 20  urrently in the 
8e80: 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 63  transaction stac
8e90: 6b 2c 20 74 68 65 6e 20 6e 6f 20 73 61 76 65 70  k, then no savep
8ea0: 6f 69 6e 74 73 20 61 72 65 0a 72 65 6c 65 61 73  oints are.releas
8eb0: 65 64 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  ed, the database
8ec0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2c 20 61   is unchanged, a
8ed0: 6e 64 20 74 68 65 20 52 45 4c 45 41 53 45 20 63  nd the RELEASE c
8ee0: 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e 73 0a 61  ommand returns.a
8ef0: 6e 20 65 72 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70  n error.</p>..<p
8f00: 3e 5e 4e 6f 74 65 20 74 68 61 74 20 61 6e 20 69  >^Note that an i
8f10: 6e 6e 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e  nner transaction
8f20: 20 6d 69 67 68 74 20 63 6f 6d 6d 69 74 20 28 75   might commit (u
8f30: 73 69 6e 67 20 74 68 65 20 52 45 4c 45 41 53 45  sing the RELEASE
8f40: 20 63 6f 6d 6d 61 6e 64 29 0a 62 75 74 20 74 68   command).but th
8f50: 65 6e 20 6c 61 74 65 72 20 68 61 76 65 20 69 74  en later have it
8f60: 73 20 77 6f 72 6b 20 75 6e 64 6f 6e 65 20 62 79  s work undone by
8f70: 20 61 20 52 4f 4c 4c 42 41 43 4b 20 69 6e 20 61   a ROLLBACK in a
8f80: 6e 20 6f 75 74 65 72 20 74 72 61 6e 73 61 63 74  n outer transact
8f90: 69 6f 6e 2e 0a 5e 41 20 70 6f 77 65 72 20 66 61  ion..^A power fa
8fa0: 69 6c 75 72 65 20 6f 72 20 70 72 6f 67 72 61 6d  ilure or program
8fb0: 20 63 72 61 73 68 20 6f 72 20 4f 53 20 63 72 61   crash or OS cra
8fc0: 73 68 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68  sh will cause th
8fd0: 65 20 6f 75 74 65 72 2d 6d 6f 73 74 0a 74 72 61  e outer-most.tra
8fe0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72 6f 6c 6c  nsaction to roll
8ff0: 62 61 63 6b 2c 20 75 6e 64 6f 69 6e 67 20 61 6c  back, undoing al
9000: 6c 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 68  l changes that h
9010: 61 76 65 20 6f 63 63 75 72 72 65 64 20 77 69 74  ave occurred wit
9020: 68 69 6e 0a 74 68 61 74 20 6f 75 74 65 72 20 74  hin.that outer t
9030: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65 76 65 6e  ransaction, even
9040: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 68 61   changes that ha
9050: 76 65 20 73 75 70 70 6f 73 65 64 6c 79 20 62 65  ve supposedly be
9060: 65 6e 20 22 63 6f 6d 6d 69 74 74 65 64 22 0a 62  en "committed".b
9070: 79 20 74 68 65 20 52 45 4c 45 41 53 45 20 63 6f  y the RELEASE co
9080: 6d 6d 61 6e 64 2e 20 20 5e 43 6f 6e 74 65 6e 74  mmand.  ^Content
9090: 20 69 73 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   is not actually
90a0: 20 63 6f 6d 6d 69 74 74 65 64 20 6f 6e 20 74 68   committed on th
90b0: 65 20 64 69 73 6b 20 0a 75 6e 74 69 6c 20 74 68  e disk .until th
90c0: 65 20 6f 75 74 65 72 6d 6f 73 74 20 74 72 61 6e  e outermost tran
90d0: 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e  saction commits.
90e0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  </p>..<p>There a
90f0: 72 65 20 73 65 76 65 72 61 6c 20 77 61 79 73 20  re several ways 
9100: 6f 66 20 74 68 69 6e 6b 69 6e 67 20 61 62 6f 75  of thinking abou
9110: 74 20 74 68 65 20 52 45 4c 45 41 53 45 20 63 6f  t the RELEASE co
9120: 6d 6d 61 6e 64 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e  mmand:</p>..<ul>
9130: 0a 3c 6c 69 3e 3c 70 3e 0a 53 6f 6d 65 20 70 65  .<li><p>.Some pe
9140: 6f 70 6c 65 20 76 69 65 77 20 52 45 4c 45 41 53  ople view RELEAS
9150: 45 20 61 73 20 74 68 65 20 65 71 75 69 76 61 6c  E as the equival
9160: 65 6e 74 20 6f 66 20 43 4f 4d 4d 49 54 20 66 6f  ent of COMMIT fo
9170: 72 20 61 20 53 41 56 45 50 4f 49 4e 54 2e 0a 54  r a SAVEPOINT..T
9180: 68 69 73 20 69 73 20 61 6e 20 61 63 63 65 70 74  his is an accept
9190: 61 62 6c 65 20 70 6f 69 6e 74 20 6f 66 20 76 69  able point of vi
91a0: 65 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 6f 6e  ew as long as on
91b0: 65 20 72 65 6d 65 6d 62 65 72 73 20 74 68 61 74  e remembers that
91c0: 20 74 68 65 0a 63 68 61 6e 67 65 73 20 63 6f 6d   the.changes com
91d0: 6d 69 74 74 65 64 20 62 79 20 61 6e 20 69 6e 6e  mitted by an inn
91e0: 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  er transaction m
91f0: 69 67 68 74 20 6c 61 74 65 72 20 62 65 20 75 6e  ight later be un
9200: 64 6f 6e 65 20 62 79 20 61 0a 72 6f 6c 6c 62 61  done by a.rollba
9210: 63 6b 20 69 6e 20 61 6e 20 6f 75 74 65 72 20 74  ck in an outer t
9220: 72 61 6e 73 61 63 74 69 6f 6e 2e 3c 2f 70 3e 3c  ransaction.</p><
9230: 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 41 6e  /li>..<li><p>.An
9240: 6f 74 68 65 72 20 76 69 65 77 20 6f 66 20 52 45  other view of RE
9250: 4c 45 41 53 45 20 69 73 20 74 68 61 74 20 69 74  LEASE is that it
9260: 20 6d 65 72 67 65 73 20 61 20 6e 61 6d 65 64 20   merges a named 
9270: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 6e 74 6f  transaction into
9280: 20 69 74 73 0a 70 61 72 65 6e 74 20 74 72 61 6e   its.parent tran
9290: 73 61 63 74 69 6f 6e 2c 20 73 6f 20 74 68 61 74  saction, so that
92a0: 20 74 68 65 20 6e 61 6d 65 64 20 74 72 61 6e 73   the named trans
92b0: 61 63 74 69 6f 6e 20 61 6e 64 20 69 74 73 20 70  action and its p
92c0: 61 72 65 6e 74 20 62 65 63 6f 6d 65 0a 74 68 65  arent become.the
92d0: 20 73 61 6d 65 20 74 72 61 6e 73 61 63 74 69 6f   same transactio
92e0: 6e 2e 20 20 41 66 74 65 72 20 52 45 4c 45 41 53  n.  After RELEAS
92f0: 45 2c 20 74 68 65 20 6e 61 6d 65 64 20 74 72 61  E, the named tra
9300: 6e 73 61 63 74 69 6f 6e 20 61 6e 64 20 69 74 73  nsaction and its
9310: 20 70 61 72 65 6e 74 0a 77 69 6c 6c 20 63 6f 6d   parent.will com
9320: 6d 69 74 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  mit or rollback 
9330: 74 6f 67 65 74 68 65 72 2c 20 77 68 61 74 65 76  together, whatev
9340: 65 72 20 74 68 65 69 72 20 66 61 74 65 20 6d 61  er their fate ma
9350: 79 20 62 65 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a  y be..</p></li>.
9360: 0a 3c 6c 69 3e 3c 70 3e 0a 4f 6e 65 20 63 61 6e  .<li><p>.One can
9370: 20 61 6c 73 6f 20 74 68 69 6e 6b 20 6f 66 20 73   also think of s
9380: 61 76 65 70 6f 69 6e 74 73 20 61 73 0a 22 6d 61  avepoints as."ma
9390: 72 6b 73 22 20 69 6e 20 74 68 65 20 74 72 61 6e  rks" in the tran
93a0: 73 61 63 74 69 6f 6e 20 74 69 6d 65 6c 69 6e 65  saction timeline
93b0: 2e 20 20 49 6e 20 74 68 69 73 20 76 69 65 77 2c  .  In this view,
93c0: 20 74 68 65 20 53 41 56 45 50 4f 49 4e 54 20 63   the SAVEPOINT c
93d0: 6f 6d 6d 61 6e 64 0a 63 72 65 61 74 65 73 20 61  ommand.creates a
93e0: 20 6e 65 77 20 6d 61 72 6b 2c 20 74 68 65 20 52   new mark, the R
93f0: 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d 61  OLLBACK TO comma
9400: 6e 64 20 72 65 77 69 6e 64 73 20 74 68 65 20 74  nd rewinds the t
9410: 69 6d 65 6c 69 6e 65 20 62 61 63 6b 0a 74 6f 20  imeline back.to 
9420: 61 20 70 6f 69 6e 74 20 6a 75 73 74 20 61 66 74  a point just aft
9430: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 6d 61 72  er the named mar
9440: 6b 2c 20 61 6e 64 20 74 68 65 20 52 45 4c 45 41  k, and the RELEA
9450: 53 45 20 63 6f 6d 6d 61 6e 64 0a 65 72 61 73 65  SE command.erase
9460: 73 20 6d 61 72 6b 73 20 66 72 6f 6d 20 74 68 65  s marks from the
9470: 20 74 69 6d 65 6c 69 6e 65 20 77 69 74 68 6f 75   timeline withou
9480: 74 20 61 63 74 75 61 6c 6c 79 20 6d 61 6b 69 6e  t actually makin
9490: 67 20 61 6e 79 0a 63 68 61 6e 67 65 73 20 74 6f  g any.changes to
94a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 3c   the database..<
94b0: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a  /p></li>.</ul>..
94c0: 0a 0a 3c 68 33 3e 54 72 61 6e 73 61 63 74 69 6f  ..<h3>Transactio
94d0: 6e 20 4e 65 73 74 69 6e 67 20 52 75 6c 65 73 3c  n Nesting Rules<
94e0: 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65 20 6c 61  /h3>..<p>^The la
94f0: 73 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  st transaction s
9500: 74 61 72 74 65 64 20 77 69 6c 6c 20 62 65 20 74  tarted will be t
9510: 68 65 20 66 69 72 73 74 0a 74 72 61 6e 73 61 63  he first.transac
9520: 74 69 6f 6e 20 63 6f 6d 6d 69 74 74 65 64 20 6f  tion committed o
9530: 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 3c 2f  r rolled back.</
9540: 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b 42 45 47  p>..<p>^The [BEG
9550: 49 4e 5d 20 63 6f 6d 6d 61 6e 64 20 6f 6e 6c 79  IN] command only
9560: 20 77 6f 72 6b 73 20 69 66 20 74 68 65 20 74 72   works if the tr
9570: 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 63 6b 20  ansaction stack 
9580: 69 73 20 65 6d 70 74 79 2c 20 6f 72 0a 69 6e 20  is empty, or.in 
9590: 6f 74 68 65 72 20 77 6f 72 64 73 20 69 66 20 74  other words if t
95a0: 68 65 72 65 20 61 72 65 20 6e 6f 20 70 65 6e 64  here are no pend
95b0: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  ing transactions
95c0: 2e 20 20 5e 49 66 20 74 68 65 20 74 72 61 6e 73  .  ^If the trans
95d0: 61 63 74 69 6f 6e 0a 73 74 61 63 6b 20 69 73 20  action.stack is 
95e0: 6e 6f 74 20 65 6d 70 74 79 20 77 68 65 6e 20 74  not empty when t
95f0: 68 65 20 5b 42 45 47 49 4e 5d 20 63 6f 6d 6d 61  he [BEGIN] comma
9600: 6e 64 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  nd is invoked, t
9610: 68 65 6e 20 74 68 65 20 63 6f 6d 6d 61 6e 64 0a  hen the command.
9620: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
9630: 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68  ror.</p>..<p>^Th
9640: 65 20 5b 43 4f 4d 4d 49 54 5d 20 63 6f 6d 6d 61  e [COMMIT] comma
9650: 6e 64 20 63 6f 6d 6d 69 74 73 20 61 6c 6c 20 6f  nd commits all o
9660: 75 74 73 74 61 6e 64 69 6e 67 20 74 72 61 6e 73  utstanding trans
9670: 61 63 74 69 6f 6e 73 20 61 6e 64 20 6c 65 61 76  actions and leav
9680: 65 73 0a 74 68 65 20 74 72 61 6e 73 61 63 74 69  es.the transacti
9690: 6f 6e 20 73 74 61 63 6b 20 65 6d 70 74 79 2e 3c  on stack empty.<
96a0: 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 52 45 4c  /p>..<p>^The REL
96b0: 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 73 74 61  EASE command sta
96c0: 72 74 73 20 77 69 74 68 20 74 68 65 20 6d 6f 73  rts with the mos
96d0: 74 20 72 65 63 65 6e 74 20 61 64 64 69 74 69 6f  t recent additio
96e0: 6e 20 74 6f 20 74 68 65 0a 74 72 61 6e 73 61 63  n to the.transac
96f0: 74 69 6f 6e 20 73 74 61 63 6b 20 61 6e 64 20 72  tion stack and r
9700: 65 6c 65 61 73 65 73 20 73 61 76 65 70 6f 69 6e  eleases savepoin
9710: 74 73 20 62 61 63 6b 77 61 72 64 73 20 0a 69 6e  ts backwards .in
9720: 20 74 69 6d 65 20 75 6e 74 69 6c 20 69 74 20 72   time until it r
9730: 65 6c 65 61 73 65 73 20 61 20 73 61 76 65 70 6f  eleases a savepo
9740: 69 6e 74 20 77 69 74 68 20 61 20 6d 61 74 63 68  int with a match
9750: 69 6e 67 20 73 61 76 65 70 6f 69 6e 74 2d 6e 61  ing savepoint-na
9760: 6d 65 2e 0a 5e 50 72 69 6f 72 20 73 61 76 65 70  me..^Prior savep
9770: 6f 69 6e 74 73 2c 20 65 76 65 6e 20 73 61 76 65  oints, even save
9780: 70 6f 69 6e 74 73 20 77 69 74 68 20 6d 61 74 63  points with matc
9790: 68 69 6e 67 20 73 61 76 65 70 6f 69 6e 74 2d 6e  hing savepoint-n
97a0: 61 6d 65 73 2c 20 61 72 65 0a 75 6e 63 68 61 6e  ames, are.unchan
97b0: 67 65 64 2e 0a 5e 49 66 20 74 68 65 20 52 45 4c  ged..^If the REL
97c0: 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 63 61 75  EASE command cau
97d0: 73 65 73 20 74 68 65 0a 74 72 61 6e 73 61 63 74  ses the.transact
97e0: 69 6f 6e 20 73 74 61 63 6b 20 74 6f 20 62 65 63  ion stack to bec
97f0: 6f 6d 65 20 65 6d 70 74 79 20 28 69 66 20 74 68  ome empty (if th
9800: 65 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e  e RELEASE comman
9810: 64 20 72 65 6c 65 61 73 65 73 20 74 68 65 0a 6f  d releases the.o
9820: 75 74 65 72 6d 6f 73 74 20 74 72 61 6e 73 61 63  utermost transac
9830: 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 73 74  tion from the st
9840: 61 63 6b 29 20 74 68 65 6e 20 74 68 65 20 74 72  ack) then the tr
9850: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
9860: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  s.</p>..<p>^The 
9870: 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f 6d 6d 61  [ROLLBACK] comma
9880: 6e 64 20 77 69 74 68 6f 75 74 20 61 20 54 4f 20  nd without a TO 
9890: 63 6c 61 75 73 65 20 72 6f 6c 6c 73 20 62 61 63  clause rolls bac
98a0: 6b 73 20 61 6c 6c 20 74 72 61 6e 73 61 63 74 69  ks all transacti
98b0: 6f 6e 73 0a 61 6e 64 20 6c 65 61 76 65 73 20 74  ons.and leaves t
98c0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  he transaction s
98d0: 74 61 63 6b 20 65 6d 70 74 79 2e 3c 2f 70 3e 0a  tack empty.</p>.
98e0: 0a 3c 70 3e 5e 54 68 65 20 52 4f 4c 4c 42 41 43  .<p>^The ROLLBAC
98f0: 4b 20 63 6f 6d 6d 61 6e 64 20 77 69 74 68 20 61  K command with a
9900: 20 54 4f 20 63 6c 61 75 73 65 20 72 6f 6c 6c 73   TO clause rolls
9910: 20 62 61 63 6b 20 74 72 61 6e 73 61 63 74 69 6f   back transactio
9920: 6e 73 20 67 6f 69 6e 67 0a 62 61 63 6b 77 61 72  ns going.backwar
9930: 64 73 20 69 6e 20 74 69 6d 65 20 62 61 63 6b 20  ds in time back 
9940: 74 6f 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  to the most rece
9950: 6e 74 20 53 41 56 45 50 4f 49 4e 54 20 77 69 74  nt SAVEPOINT wit
9960: 68 20 61 20 6d 61 74 63 68 69 6e 67 20 6e 61 6d  h a matching nam
9970: 65 2e 0a 5e 54 68 65 20 53 41 56 45 50 4f 49 4e  e..^The SAVEPOIN
9980: 54 20 77 69 74 68 20 74 68 65 20 6d 61 74 63 68  T with the match
9990: 69 6e 67 20 6e 61 6d 65 20 72 65 6d 61 69 6e 73  ing name remains
99a0: 20 6f 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   on the transact
99b0: 69 6f 6e 20 73 74 61 63 6b 2c 0a 62 75 74 20 61  ion stack,.but a
99c0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ll database chan
99d0: 67 65 73 20 74 68 61 74 20 6f 63 63 75 72 72 65  ges that occurre
99e0: 64 20 61 66 74 65 72 20 74 68 61 74 20 53 41 56  d after that SAV
99f0: 45 50 4f 49 4e 54 20 77 61 73 20 63 72 65 61 74  EPOINT was creat
9a00: 65 64 0a 61 72 65 20 72 6f 6c 6c 65 64 20 62 61  ed.are rolled ba
9a10: 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 73 61 76  ck.  ^If the sav
9a20: 65 70 6f 69 6e 74 2d 6e 61 6d 65 20 69 6e 20 61  epoint-name in a
9a30: 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d   ROLLBACK TO com
9a40: 6d 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 6d 61  mand does not.ma
9a50: 74 63 68 20 61 6e 79 20 53 41 56 45 50 4f 49 4e  tch any SAVEPOIN
9a60: 54 20 6f 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  T on the stack, 
9a70: 74 68 65 6e 20 74 68 65 20 52 4f 4c 4c 42 41 43  then the ROLLBAC
9a80: 4b 20 63 6f 6d 6d 61 6e 64 20 66 61 69 6c 73 20  K command fails 
9a90: 77 69 74 68 20 61 6e 0a 65 72 72 6f 72 20 61 6e  with an.error an
9aa0: 64 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61  d leaves the sta
9ab0: 74 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  te of the databa
9ac0: 73 65 20 75 6e 63 68 61 6e 67 65 64 2e 3c 2f 70  se unchanged.</p
9ad0: 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23  >..<tcl>.#######
9ae0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9af0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9b00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9b10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9b20: 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
9b30: 20 63 6f 6d 6d 65 6e 74 20 63 6f 6d 6d 65 6e 74   comment comment
9b40: 20 7b 63 6f 6d 6d 65 6e 74 20 2a 63 6f 6d 6d 65   {comment *comme
9b50: 6e 74 73 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  nts}..RecursiveB
9b60: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 6f 6d  ubbleDiagram com
9b70: 6d 65 6e 74 2d 73 79 6e 74 61 78 0a 3c 2f 74 63  ment-syntax.</tc
9b80: 6c 3e 0a 0a 3c 70 3e 5e 43 6f 6d 6d 65 6e 74 73  l>..<p>^Comments
9b90: 20 61 72 65 20 6e 6f 74 20 53 51 4c 20 63 6f 6d   are not SQL com
9ba0: 6d 61 6e 64 73 2c 20 62 75 74 20 63 61 6e 20 6f  mands, but can o
9bb0: 63 63 75 72 20 77 69 74 68 69 6e 20 74 68 65 20  ccur within the 
9bc0: 74 65 78 74 20 6f 66 0a 53 51 4c 20 71 75 65 72  text of.SQL quer
9bd0: 69 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  ies passed to [s
9be0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
9bf0: 32 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64  2()] and related
9c00: 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 5e 43 6f   interfaces..^Co
9c10: 6d 6d 65 6e 74 73 20 61 72 65 20 74 72 65 61 74  mments are treat
9c20: 65 64 20 61 73 20 77 68 69 74 65 73 70 61 63 65  ed as whitespace
9c30: 20 62 79 20 74 68 65 20 70 61 72 73 65 72 2e 0a   by the parser..
9c40: 5e 43 6f 6d 6d 65 6e 74 73 20 63 61 6e 20 62 65  ^Comments can be
9c50: 67 69 6e 20 61 6e 79 77 68 65 72 65 20 77 68 69  gin anywhere whi
9c60: 74 65 73 70 61 63 65 20 0a 63 61 6e 20 62 65 20  tespace .can be 
9c70: 66 6f 75 6e 64 2c 20 69 6e 63 6c 75 64 69 6e 67  found, including
9c80: 20 69 6e 73 69 64 65 20 65 78 70 72 65 73 73 69   inside expressi
9c90: 6f 6e 73 20 74 68 61 74 20 73 70 61 6e 20 6d 75  ons that span mu
9ca0: 6c 74 69 70 6c 65 20 6c 69 6e 65 73 2e 0a 3c 2f  ltiple lines..</
9cb0: 70 3e 0a 0a 3c 70 3e 5e 53 51 4c 20 63 6f 6d 6d  p>..<p>^SQL comm
9cc0: 65 6e 74 73 20 62 65 67 69 6e 20 77 69 74 68 20  ents begin with 
9cd0: 74 77 6f 20 63 6f 6e 73 65 63 75 74 69 76 65 20  two consecutive 
9ce0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 20 28  "-" characters (
9cf0: 41 53 43 49 49 20 30 78 32 64 29 0a 61 6e 64 20  ASCII 0x2d).and 
9d00: 65 78 74 65 6e 64 20 75 70 20 74 6f 20 61 6e 64  extend up to and
9d10: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 6e   including the n
9d20: 65 78 74 20 6e 65 77 6c 69 6e 65 20 63 68 61 72  ext newline char
9d30: 61 63 74 65 72 20 28 41 53 43 49 49 20 30 78 30  acter (ASCII 0x0
9d40: 61 29 0a 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  a).or until the 
9d50: 65 6e 64 20 6f 66 20 69 6e 70 75 74 2c 20 77 68  end of input, wh
9d60: 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
9d70: 72 73 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 43 2d  rst.</p>..<p>^C-
9d80: 73 74 79 6c 65 20 63 6f 6d 6d 65 6e 74 73 20 62  style comments b
9d90: 65 67 69 6e 0a 77 69 74 68 20 22 2f 2a 22 20 61  egin.with "/*" a
9da0: 6e 64 20 65 78 74 65 6e 64 20 75 70 20 74 6f 20  nd extend up to 
9db0: 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  and including th
9dc0: 65 20 6e 65 78 74 20 22 2a 2f 22 20 63 68 61 72  e next "*/" char
9dd0: 61 63 74 65 72 20 70 61 69 72 0a 6f 72 20 75 6e  acter pair.or un
9de0: 74 69 6c 20 74 68 65 20 65 6e 64 20 6f 66 20 69  til the end of i
9df0: 6e 70 75 74 2c 20 77 68 69 63 68 65 76 65 72 20  nput, whichever 
9e00: 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 20 5e 43  comes first.  ^C
9e10: 2d 73 74 79 6c 65 20 63 6f 6d 6d 65 6e 74 73 0a  -style comments.
9e20: 63 61 6e 20 73 70 61 6e 20 6d 75 6c 74 69 70 6c  can span multipl
9e30: 65 20 6c 69 6e 65 73 2e 20 3c 2f 70 3e 0a 0a 3c  e lines. </p>..<
9e40: 70 3e 5e 43 6f 6d 6d 65 6e 74 73 20 63 61 6e 20  p>^Comments can 
9e50: 61 70 70 65 61 72 20 61 6e 79 77 68 65 72 65 20  appear anywhere 
9e60: 77 68 69 74 65 73 70 61 63 65 20 63 61 6e 20 6f  whitespace can o
9e70: 63 63 75 72 2c 0a 69 6e 63 6c 75 64 69 6e 67 20  ccur,.including 
9e80: 69 6e 73 69 64 65 20 65 78 70 72 65 73 73 69 6f  inside expressio
9e90: 6e 73 20 61 6e 64 20 69 6e 20 74 68 65 20 6d 69  ns and in the mi
9ea0: 64 64 6c 65 20 6f 66 20 6f 74 68 65 72 20 53 51  ddle of other SQ
9eb0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 5e 43  L statements..^C
9ec0: 6f 6d 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 6e  omments do not n
9ed0: 65 73 74 2e 0a 3c 2f 70 3e 0a 0a 0a 3c 74 63 6c  est..</p>...<tcl
9ee0: 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
9ef0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9f00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9f10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9f20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9f30: 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45 41 54 45  .Section {CREATE
9f40: 20 49 4e 44 45 58 7d 20 63 72 65 61 74 65 69 6e   INDEX} createin
9f50: 64 65 78 20 7b 7b 43 52 45 41 54 45 20 49 4e 44  dex {{CREATE IND
9f60: 45 58 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  EX}}..RecursiveB
9f70: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 72 65  ubbleDiagram cre
9f80: 61 74 65 2d 69 6e 64 65 78 2d 73 74 6d 74 0a 3c  ate-index-stmt.<
9f90: 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 43  /tcl>..<p>^The C
9fa0: 52 45 41 54 45 20 49 4e 44 45 58 20 63 6f 6d 6d  REATE INDEX comm
9fb0: 61 6e 64 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  and consists of 
9fc0: 74 68 65 20 6b 65 79 77 6f 72 64 73 20 22 43 52  the keywords "CR
9fd0: 45 41 54 45 20 49 4e 44 45 58 22 20 66 6f 6c 6c  EATE INDEX" foll
9fe0: 6f 77 65 64 0a 62 79 20 74 68 65 20 6e 61 6d 65  owed.by the name
9ff0: 20 6f 66 20 74 68 65 20 6e 65 77 20 69 6e 64 65   of the new inde
a000: 78 2c 20 74 68 65 20 6b 65 79 77 6f 72 64 20 22  x, the keyword "
a010: 4f 4e 22 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ON", the name of
a020: 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 63 72   a previously.cr
a030: 65 61 74 65 64 20 74 61 62 6c 65 20 74 68 61 74  eated table that
a040: 20 69 73 20 74 6f 20 62 65 20 69 6e 64 65 78 65   is to be indexe
a050: 64 2c 20 61 6e 64 20 61 20 70 61 72 65 6e 74 68  d, and a parenth
a060: 65 73 69 7a 65 64 20 6c 69 73 74 20 6f 66 20 74  esized list of t
a070: 61 62 6c 65 20 63 6f 6c 75 6d 6e 0a 6e 61 6d 65  able column.name
a080: 73 20 61 6e 64 2f 6f 72 20 65 78 70 72 65 73 73  s and/or express
a090: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
a0a0: 65 64 20 66 6f 72 20 74 68 65 20 69 6e 64 65 78  ed for the index
a0b0: 20 6b 65 79 2e 0a 49 66 20 74 68 65 20 6f 70 74   key..If the opt
a0c0: 69 6f 6e 61 6c 20 57 48 45 52 45 20 63 6c 61 75  ional WHERE clau
a0d0: 73 65 20 69 73 20 69 6e 63 6c 75 64 65 64 2c 20  se is included, 
a0e0: 74 68 65 6e 20 74 68 65 20 69 6e 64 65 78 20 69  then the index i
a0f0: 73 20 61 20 22 5b 70 61 72 74 69 61 6c 20 69 6e  s a "[partial in
a100: 64 65 78 5d 22 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63  dex]"..</p>..<tc
a110: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b 64  l>hd_fragment {d
a120: 65 73 63 69 64 78 7d 20 7b 64 65 73 63 65 6e 64  escidx} {descend
a130: 69 6e 67 20 69 6e 64 69 63 65 73 7d 20 7b 64 65  ing indices} {de
a140: 73 63 65 6e 64 69 6e 67 20 69 6e 64 65 78 7d 20  scending index} 
a150: 5c 0a 20 20 20 20 7b 64 65 73 63 65 6e 64 69 6e  \.    {descendin
a160: 67 20 69 6e 64 65 78 65 73 7d 20 7b 44 45 53 43  g indexes} {DESC
a170: 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 45 61 63 68  }</tcl>.<p>^Each
a180: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 6f 72 20   column name or 
a190: 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
a1a0: 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6f 6e  e followed by on
a1b0: 65 0a 6f 66 20 74 68 65 20 22 41 53 43 22 20 6f  e.of the "ASC" o
a1c0: 72 20 22 44 45 53 43 22 20 6b 65 79 77 6f 72 64  r "DESC" keyword
a1d0: 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 6f  s to indicate so
a1e0: 72 74 20 6f 72 64 65 72 2e 0a 5e 54 68 65 20 73  rt order..^The s
a1f0: 6f 72 74 20 6f 72 64 65 72 20 6d 61 79 20 6f 72  ort order may or
a200: 20 6d 61 79 20 6e 6f 74 20 62 65 20 69 67 6e 6f   may not be igno
a210: 72 65 64 20 64 65 70 65 6e 64 69 6e 67 0a 6f 6e  red depending.on
a220: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a230: 6c 65 20 66 6f 72 6d 61 74 2c 20 61 6e 64 20 69  le format, and i
a240: 6e 20 70 61 72 74 69 63 75 6c 61 72 20 74 68 65  n particular the
a250: 20 5b 73 63 68 65 6d 61 20 66 6f 72 6d 61 74 20   [schema format 
a260: 6e 75 6d 62 65 72 5d 2e 0a 5e 54 68 65 20 22 6c  number]..^The "l
a270: 65 67 61 63 79 22 20 73 63 68 65 6d 61 20 66 6f  egacy" schema fo
a280: 72 6d 61 74 20 28 31 29 20 69 67 6e 6f 72 65 73  rmat (1) ignores
a290: 20 69 6e 64 65 78 0a 73 6f 72 74 20 6f 72 64 65   index.sort orde
a2a0: 72 2e 20 20 5e 54 68 65 20 64 65 73 63 65 6e 64  r.  ^The descend
a2b0: 69 6e 67 20 69 6e 64 65 78 20 73 63 68 65 6d 61  ing index schema
a2c0: 20 66 6f 72 6d 61 74 20 28 34 29 20 74 61 6b 65   format (4) take
a2d0: 73 20 69 6e 64 65 78 20 73 6f 72 74 20 6f 72 64  s index sort ord
a2e0: 65 72 0a 69 6e 74 6f 20 61 63 63 6f 75 6e 74 2e  er.into account.
a2f0: 20 20 4f 6e 6c 79 20 76 65 72 73 69 6f 6e 73 20    Only versions 
a300: 6f 66 20 53 51 4c 69 74 65 20 33 2e 33 2e 30 20  of SQLite 3.3.0 
a310: 28 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 30 5d 29  ([dateof:3.3.0])
a320: 0a 61 6e 64 20 6c 61 74 65 72 20 61 72 65 20 61  .and later are a
a330: 62 6c 65 20 74 6f 20 75 6e 64 65 72 73 74 61 6e  ble to understan
a340: 64 0a 74 68 65 20 64 65 73 63 65 6e 64 69 6e 67  d.the descending
a350: 20 69 6e 64 65 78 20 66 6f 72 6d 61 74 2e 20 46   index format. F
a360: 6f 72 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  or compatibility
a370: 2c 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  , version of SQL
a380: 69 74 65 20 62 65 74 77 65 65 6e 20 33 2e 33 2e  ite between 3.3.
a390: 30 0a 61 6e 64 20 33 2e 37 2e 39 20 75 73 65 20  0.and 3.7.9 use 
a3a0: 74 68 65 20 6c 65 67 61 63 79 20 73 63 68 65 6d  the legacy schem
a3b0: 61 20 66 6f 72 6d 61 74 20 62 79 20 64 65 66 61  a format by defa
a3c0: 75 6c 74 2e 20 20 54 68 65 20 6e 65 77 65 72 20  ult.  The newer 
a3d0: 73 63 68 65 6d 61 20 66 6f 72 6d 61 74 20 69 73  schema format is
a3e0: 0a 75 73 65 64 20 62 79 20 64 65 66 61 75 6c 74  .used by default
a3f0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e   in version 3.7.
a400: 31 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 37 2e  10 ([dateof:3.7.
a410: 31 30 5d 29 20 61 6e 64 20 6c 61 74 65 72 2e 0a  10]) and later..
a420: 5e 54 68 65 20 5b 6c 65 67 61 63 79 5f 66 69 6c  ^The [legacy_fil
a430: 65 5f 66 6f 72 6d 61 74 20 70 72 61 67 6d 61 5d  e_format pragma]
a440: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a450: 63 68 61 6e 67 65 20 73 65 74 20 74 68 65 20 73  change set the s
a460: 70 65 63 69 66 69 63 0a 62 65 68 61 76 69 6f 72  pecific.behavior
a470: 20 66 6f 72 20 61 6e 79 20 76 65 72 73 69 6f 6e   for any version
a480: 20 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a   of SQLite.</p>.
a490: 0a 3c 70 3e 54 68 65 20 4e 55 4c 4c 53 20 46 49  .<p>The NULLS FI
a4a0: 52 53 54 20 61 6e 64 20 4e 55 4c 4c 53 20 4c 41  RST and NULLS LA
a4b0: 53 54 20 70 72 65 64 69 63 61 74 65 73 20 61 72  ST predicates ar
a4c0: 65 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 0a  e not supported.
a4d0: 66 6f 72 20 69 6e 64 65 78 65 73 2e 20 20 46 6f  for indexes.  Fo
a4e0: 72 20 5b 73 6f 72 74 20 6f 72 64 65 72 7c 73 6f  r [sort order|so
a4f0: 72 74 69 6e 67 20 70 75 72 70 6f 73 65 73 5d 2c  rting purposes],
a500: 20 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72   SQLite consider
a510: 73 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 0a 74  s NULL values .t
a520: 6f 20 62 65 20 73 6d 61 6c 6c 65 72 20 74 68 61  o be smaller tha
a530: 6e 20 61 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75  n all other valu
a540: 65 73 2e 20 20 48 65 6e 63 65 73 20 4e 55 4c 4c  es.  Hences NULL
a550: 20 76 61 6c 75 65 73 20 61 6c 77 61 79 73 20 61   values always a
a560: 70 70 65 61 72 20 61 74 0a 74 68 65 20 62 65 67  ppear at.the beg
a570: 69 6e 6e 69 6e 67 20 6f 66 20 61 6e 20 41 53 43  inning of an ASC
a580: 20 69 6e 64 65 78 20 61 6e 64 20 61 74 20 74 68   index and at th
a590: 65 20 65 6e 64 20 6f 66 20 61 20 44 45 53 43 20  e end of a DESC 
a5a0: 69 6e 64 65 78 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  index.</p>..<tcl
a5b0: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f 6c  >hd_fragment col
a5c0: 6c 69 64 78 20 7b 43 4f 4c 4c 41 54 45 7d 3c 2f  lidx {COLLATE}</
a5d0: 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 43 4f 4c  tcl>.<p>^The COL
a5e0: 4c 41 54 45 20 63 6c 61 75 73 65 20 6f 70 74 69  LATE clause opti
a5f0: 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 69 6e 67  onally following
a600: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6e 61 6d   each column nam
a610: 65 0a 6f 72 20 65 78 70 72 65 73 73 69 6f 6e 20  e.or expression 
a620: 64 65 66 69 6e 65 73 20 61 0a 63 6f 6c 6c 61 74  defines a.collat
a630: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 75 73 65  ing sequence use
a640: 64 20 66 6f 72 20 74 65 78 74 20 65 6e 74 72 69  d for text entri
a650: 65 73 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  es in that colum
a660: 6e 2e 0a 5e 54 68 65 20 64 65 66 61 75 6c 74 20  n..^The default 
a670: 63 6f 6c 6c 61 74 69 6e 67 0a 73 65 71 75 65 6e  collating.sequen
a680: 63 65 20 69 73 20 74 68 65 20 63 6f 6c 6c 61 74  ce is the collat
a690: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 64 65 66  ing sequence def
a6a0: 69 6e 65 64 20 66 6f 72 20 74 68 61 74 20 63 6f  ined for that co
a6b0: 6c 75 6d 6e 20 69 6e 20 74 68 65 0a 5b 43 52 45  lumn in the.[CRE
a6c0: 41 54 45 20 54 41 42 4c 45 5d 20 73 74 61 74 65  ATE TABLE] state
a6d0: 6d 65 6e 74 2e 20 20 5e 4f 72 20 69 66 20 6e 6f  ment.  ^Or if no
a6e0: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
a6f0: 6e 63 65 20 69 73 20 6f 74 68 65 72 77 69 73 65  nce is otherwise
a700: 20 64 65 66 69 6e 65 64 2c 0a 74 68 65 20 62 75   defined,.the bu
a710: 69 6c 74 2d 69 6e 20 42 49 4e 41 52 59 20 63 6f  ilt-in BINARY co
a720: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
a730: 20 69 73 20 75 73 65 64 2e 3c 2f 70 3e 0a 0a 3c   is used.</p>..<
a740: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
a750: 69 6e 64 65 78 65 78 70 72 3c 2f 74 63 6c 3e 0a  indexexpr</tcl>.
a760: 3c 70 3e 5e 45 78 70 72 65 73 73 69 6f 6e 73 20  <p>^Expressions 
a770: 69 6e 20 61 6e 20 69 6e 64 65 78 20 6d 61 79 20  in an index may 
a780: 6e 6f 74 20 72 65 66 65 72 65 6e 63 65 20 6f 74  not reference ot
a790: 68 65 72 20 74 61 62 6c 65 73 0a 61 6e 64 20 6d  her tables.and m
a7a0: 61 79 20 6e 6f 74 20 75 73 65 20 73 75 62 71 75  ay not use subqu
a7b0: 65 72 69 65 73 20 6e 6f 72 20 66 75 6e 63 74 69  eries nor functi
a7c0: 6f 6e 73 20 77 68 6f 73 65 20 72 65 73 75 6c 74  ons whose result
a7d0: 20 6d 69 67 68 74 0a 63 68 61 6e 67 65 20 28 65   might.change (e
a7e0: 78 3a 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 6f 72  x: [random()] or
a7f0: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
a800: 28 29 5d 29 2e 0a 5e 45 78 70 72 65 73 73 69 6f  ()])..^Expressio
a810: 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 20 6d  ns in an index m
a820: 61 79 20 6f 6e 6c 79 20 72 65 66 65 72 20 74 6f  ay only refer to
a830: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
a840: 74 61 62 6c 65 0a 74 68 61 74 20 69 73 20 62 65  table.that is be
a850: 69 6e 67 20 69 6e 64 65 78 65 64 2e 0a 49 6e 64  ing indexed..Ind
a860: 65 78 65 73 20 6f 6e 20 65 78 70 72 65 73 73 69  exes on expressi
a870: 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 77 6f 72 6b  on will not work
a880: 20 77 69 74 68 20 76 65 72 73 69 6f 6e 73 20 6f   with versions o
a890: 66 20 53 51 4c 69 74 65 20 70 72 69 6f 72 0a 74  f SQLite prior.t
a8a0: 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 39 2e 30  o [version 3.9.0
a8b0: 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 39 2e 30  ] ([dateof:3.9.0
a8c0: 5d 29 2e 0a 53 65 65 20 74 68 65 20 5b 49 6e 64  ])..See the [Ind
a8d0: 65 78 65 73 20 4f 6e 20 45 78 70 72 65 73 73 69  exes On Expressi
a8e0: 6f 6e 73 5d 20 64 6f 63 75 6d 65 6e 74 20 66 6f  ons] document fo
a8f0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
a900: 6f 72 6d 61 74 69 6f 6e 0a 61 62 6f 75 74 20 75  ormation.about u
a910: 73 69 6e 67 20 67 65 6e 65 72 61 6c 20 65 78 70  sing general exp
a920: 72 65 73 73 69 6f 6e 73 20 69 6e 20 43 52 45 41  ressions in CREA
a930: 54 45 20 49 4e 44 45 58 20 73 74 61 74 65 6d 65  TE INDEX stateme
a940: 6e 74 73 2e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  nts...<p>There a
a950: 72 65 20 6e 6f 20 61 72 62 69 74 72 61 72 79 20  re no arbitrary 
a960: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 6e 75  limits on the nu
a970: 6d 62 65 72 20 6f 66 20 69 6e 64 69 63 65 73 20  mber of indices 
a980: 74 68 61 74 20 63 61 6e 20 62 65 0a 61 74 74 61  that can be.atta
a990: 63 68 65 64 20 74 6f 20 61 20 73 69 6e 67 6c 65  ched to a single
a9a0: 20 74 61 62 6c 65 2e 20 20 5e 28 54 68 65 20 6e   table.  ^(The n
a9b0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
a9c0: 20 69 6e 20 61 6e 20 69 6e 64 65 78 20 69 73 20   in an index is 
a9d0: 0a 6c 69 6d 69 74 65 64 20 74 6f 20 74 68 65 20  .limited to the 
a9e0: 76 61 6c 75 65 20 73 65 74 20 62 79 0a 5b 73 71  value set by.[sq
a9f0: 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
aa00: 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
aa10: 4e 5d 2c 2e 2e 2e 29 2e 29 5e 3c 2f 70 3e 0a 0a  N],...).)^</p>..
aa20: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
aa30: 20 75 6e 69 71 75 65 69 64 78 20 7b 75 6e 69 71   uniqueidx {uniq
aa40: 75 65 20 69 6e 64 65 78 7d 3c 2f 74 63 6c 3e 0a  ue index}</tcl>.
aa50: 3c 70 3e 5e 49 66 20 74 68 65 20 55 4e 49 51 55  <p>^If the UNIQU
aa60: 45 20 6b 65 79 77 6f 72 64 20 61 70 70 65 61 72  E keyword appear
aa70: 73 20 62 65 74 77 65 65 6e 20 43 52 45 41 54 45  s between CREATE
aa80: 20 61 6e 64 20 49 4e 44 45 58 20 74 68 65 6e 20   and INDEX then 
aa90: 64 75 70 6c 69 63 61 74 65 0a 69 6e 64 65 78 20  duplicate.index 
aaa0: 65 6e 74 72 69 65 73 20 61 72 65 20 6e 6f 74 20  entries are not 
aab0: 61 6c 6c 6f 77 65 64 2e 20 20 5e 41 6e 79 20 61  allowed.  ^Any a
aac0: 74 74 65 6d 70 74 20 74 6f 20 69 6e 73 65 72 74  ttempt to insert
aad0: 20 61 20 64 75 70 6c 69 63 61 74 65 20 65 6e 74   a duplicate ent
aae0: 72 79 0a 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ry.will result i
aaf0: 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 46 6f  n an error.  ^Fo
ab00: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
ab10: 66 20 75 6e 69 71 75 65 20 69 6e 64 69 63 65 73  f unique indices
ab20: 2c 20 61 6c 6c 20 4e 55 4c 4c 20 76 61 6c 75 65  , all NULL value
ab30: 73 0a 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64  s.are considered
ab40: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
ab50: 61 6c 6c 20 6f 74 68 65 72 20 4e 55 4c 4c 20 76  all other NULL v
ab60: 61 6c 75 65 73 20 61 6e 64 20 61 72 65 20 74 68  alues and are th
ab70: 75 73 20 75 6e 69 71 75 65 2e 0a 54 68 69 73 20  us unique..This 
ab80: 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 74 77  is one of the tw
ab90: 6f 20 70 6f 73 73 69 62 6c 65 20 69 6e 74 65 72  o possible inter
aba0: 70 72 65 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  pretations of th
abb0: 65 20 53 51 4c 2d 39 32 20 73 74 61 6e 64 61 72  e SQL-92 standar
abc0: 64 0a 28 74 68 65 20 6c 61 6e 67 75 61 67 65 20  d.(the language 
abd0: 69 6e 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  in the standard 
abe0: 69 73 20 61 6d 62 69 67 75 6f 75 73 29 20 61 6e  is ambiguous) an
abf0: 64 20 69 73 20 74 68 65 20 69 6e 74 65 72 70 72  d is the interpr
ac00: 65 74 61 74 69 6f 6e 0a 66 6f 6c 6c 6f 77 65 64  etation.followed
ac10: 20 62 79 20 50 6f 73 74 67 72 65 53 51 4c 2c 20   by PostgreSQL, 
ac20: 4d 79 53 51 4c 2c 20 46 69 72 65 62 69 72 64 2c  MySQL, Firebird,
ac30: 20 61 6e 64 20 4f 72 61 63 6c 65 2e 20 20 49 6e   and Oracle.  In
ac40: 66 6f 72 6d 69 78 20 61 6e 64 0a 4d 69 63 72 6f  formix and.Micro
ac50: 73 6f 66 74 20 53 51 4c 20 53 65 72 76 65 72 20  soft SQL Server 
ac60: 66 6f 6c 6c 6f 77 20 74 68 65 20 6f 74 68 65 72  follow the other
ac70: 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
ac80: 6f 66 20 74 68 65 20 73 74 61 6e 64 61 72 64 2e  of the standard.
ac90: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65  </p>..<p>^If the
aca0: 20 6f 70 74 69 6f 6e 61 6c 20 49 46 20 4e 4f 54   optional IF NOT
acb0: 20 45 58 49 53 54 53 20 63 6c 61 75 73 65 20 69   EXISTS clause i
acc0: 73 20 70 72 65 73 65 6e 74 20 61 6e 64 20 61 6e  s present and an
acd0: 6f 74 68 65 72 20 69 6e 64 65 78 0a 77 69 74 68  other index.with
ace0: 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
acf0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2c 20 74  lready exists, t
ad00: 68 65 6e 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64  hen this command
ad10: 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
ad20: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 6e 64 65 78  .</p>..<p>^Index
ad30: 65 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20 77  es are removed w
ad40: 69 74 68 20 74 68 65 20 5b 44 52 4f 50 20 49 4e  ith the [DROP IN
ad50: 44 45 58 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70  DEX] command.</p
ad60: 3e 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  >...<tcl>.######
ad70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ada0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
adb0: 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
adc0: 20 7b 43 52 45 41 54 45 20 54 41 42 4c 45 7d 20   {CREATE TABLE} 
add0: 7b 63 72 65 61 74 65 74 61 62 6c 65 7d 20 7b 7b  {createtable} {{
ade0: 43 52 45 41 54 45 20 54 41 42 4c 45 7d 7d 0a 0a  CREATE TABLE}}..
adf0: 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
ae00: 69 61 67 72 61 6d 20 63 72 65 61 74 65 2d 74 61  iagram create-ta
ae10: 62 6c 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a  ble-stmt.</tcl>.
ae20: 0a 3c 70 3e 54 68 65 20 22 43 52 45 41 54 45 20  .<p>The "CREATE 
ae30: 54 41 42 4c 45 22 20 63 6f 6d 6d 61 6e 64 20 69  TABLE" command i
ae40: 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
ae50: 20 61 20 6e 65 77 20 74 61 62 6c 65 20 69 6e 20   a new table in 
ae60: 61 6e 20 53 51 4c 69 74 65 20 0a 64 61 74 61 62  an SQLite .datab
ae70: 61 73 65 2e 20 41 20 43 52 45 41 54 45 20 54 41  ase. A CREATE TA
ae80: 42 4c 45 20 63 6f 6d 6d 61 6e 64 20 73 70 65 63  BLE command spec
ae90: 69 66 69 65 73 20 74 68 65 20 66 6f 6c 6c 6f 77  ifies the follow
aea0: 69 6e 67 20 61 74 74 72 69 62 75 74 65 73 20 6f  ing attributes o
aeb0: 66 20 74 68 65 0a 6e 65 77 20 74 61 62 6c 65 3a  f the.new table:
aec0: 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 3c 70 3e  ..<ul>.  <li><p>
aed0: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
aee0: 6e 65 77 20 74 61 62 6c 65 2e 0a 0a 20 20 3c 6c  new table...  <l
aef0: 69 3e 3c 70 3e 20 54 68 65 20 64 61 74 61 62 61  i><p> The databa
af00: 73 65 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  se in which the 
af10: 6e 65 77 20 74 61 62 6c 65 20 69 73 20 63 72 65  new table is cre
af20: 61 74 65 64 2e 20 54 61 62 6c 65 73 20 6d 61 79  ated. Tables may
af30: 20 62 65 20 0a 20 20 20 20 20 20 63 72 65 61 74   be .      creat
af40: 65 64 20 69 6e 20 74 68 65 20 6d 61 69 6e 20 64  ed in the main d
af50: 61 74 61 62 61 73 65 2c 20 74 68 65 20 74 65 6d  atabase, the tem
af60: 70 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 69  p database, or i
af70: 6e 20 61 6e 79 20 61 74 74 61 63 68 65 64 0a 20  n any attached. 
af80: 20 20 20 20 20 64 61 74 61 62 61 73 65 2e 0a 0a       database...
af90: 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 6e 61    <li><p> The na
afa0: 6d 65 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  me of each colum
afb0: 6e 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a  n in the table..
afc0: 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 64  .  <li><p> The d
afd0: 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
afe0: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  each column in t
aff0: 68 65 20 74 61 62 6c 65 2e 0a 0a 20 20 3c 6c 69  he table...  <li
b000: 3e 3c 70 3e 20 41 20 64 65 66 61 75 6c 74 20 76  ><p> A default v
b010: 61 6c 75 65 20 6f 72 20 65 78 70 72 65 73 73 69  alue or expressi
b020: 6f 6e 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  on for each colu
b030: 6d 6e 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  mn in the table.
b040: 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 41 20 64 65  ..  <li><p> A de
b050: 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
b060: 73 65 71 75 65 6e 63 65 20 74 6f 20 75 73 65 20  sequence to use 
b070: 77 69 74 68 20 65 61 63 68 20 63 6f 6c 75 6d 6e  with each column
b080: 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 4f 70 74  ...  <li><p> Opt
b090: 69 6f 6e 61 6c 6c 79 2c 20 61 20 50 52 49 4d 41  ionally, a PRIMA
b0a0: 52 59 20 4b 45 59 20 66 6f 72 20 74 68 65 20 74  RY KEY for the t
b0b0: 61 62 6c 65 2e 20 42 6f 74 68 20 73 69 6e 67 6c  able. Both singl
b0c0: 65 20 63 6f 6c 75 6d 6e 20 61 6e 64 0a 20 20 20  e column and.   
b0d0: 20 20 20 20 63 6f 6d 70 6f 73 69 74 65 20 28 6d      composite (m
b0e0: 75 6c 74 69 70 6c 65 20 63 6f 6c 75 6d 6e 29 20  ultiple column) 
b0f0: 70 72 69 6d 61 72 79 20 6b 65 79 73 20 61 72 65  primary keys are
b100: 20 73 75 70 70 6f 72 74 65 64 2e 0a 0a 20 20 3c   supported...  <
b110: 6c 69 3e 3c 70 3e 20 41 20 73 65 74 20 6f 66 20  li><p> A set of 
b120: 53 51 4c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  SQL constraints 
b130: 66 6f 72 20 65 61 63 68 20 74 61 62 6c 65 2e 20  for each table. 
b140: 53 51 4c 69 74 65 20 73 75 70 70 6f 72 74 73 20  SQLite supports 
b150: 55 4e 49 51 55 45 2c 20 4e 4f 54 0a 20 20 20 20  UNIQUE, NOT.    
b160: 20 20 20 4e 55 4c 4c 2c 20 43 48 45 43 4b 20 61     NULL, CHECK a
b170: 6e 64 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 63  nd FOREIGN KEY c
b180: 6f 6e 73 74 72 61 69 6e 74 73 2e 0a 0a 20 20 3c  onstraints...  <
b190: 6c 69 3e 3c 70 3e 20 4f 70 74 69 6f 6e 61 6c 6c  li><p> Optionall
b1a0: 79 2c 20 61 20 5b 67 65 6e 65 72 61 74 65 64 20  y, a [generated 
b1b0: 63 6f 6c 75 6d 6e 5d 20 63 6f 6e 73 74 72 61 69  column] constrai
b1c0: 6e 74 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 57  nt...  <li><p> W
b1d0: 68 65 74 68 65 72 20 74 68 65 20 74 61 62 6c 65  hether the table
b1e0: 20 69 73 20 61 20 5b 57 49 54 48 4f 55 54 20 52   is a [WITHOUT R
b1f0: 4f 57 49 44 5d 20 74 61 62 6c 65 2e 0a 3c 2f 75  OWID] table..</u
b200: 6c 3e 0a 0a 3c 70 3e 45 76 65 72 79 20 43 52 45  l>..<p>Every CRE
b210: 41 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d  ATE TABLE statem
b220: 65 6e 74 20 6d 75 73 74 20 73 70 65 63 69 66 79  ent must specify
b230: 20 61 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20   a name for the 
b240: 6e 65 77 20 74 61 62 6c 65 2e 0a 20 20 5e 28 54  new table..  ^(T
b250: 61 62 6c 65 20 6e 61 6d 65 73 20 74 68 61 74 20  able names that 
b260: 62 65 67 69 6e 20 77 69 74 68 20 22 73 71 6c 69  begin with "sqli
b270: 74 65 5f 22 20 61 72 65 20 72 65 73 65 72 76 65  te_" are reserve
b280: 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 20 75  d for internal u
b290: 73 65 2e 20 49 74 0a 20 20 69 73 20 61 6e 20 65  se. It.  is an e
b2a0: 72 72 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 20  rror to attempt 
b2b0: 74 6f 20 63 72 65 61 74 65 20 61 20 74 61 62 6c  to create a tabl
b2c0: 65 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68  e with a name th
b2d0: 61 74 20 73 74 61 72 74 73 20 77 69 74 68 0a 20  at starts with. 
b2e0: 20 22 73 71 6c 69 74 65 5f 22 2e 29 5e 0a 0a 3c   "sqlite_".)^..<
b2f0: 70 3e 20 5e 49 66 20 61 20 3c 79 79 74 65 72 6d  p> ^If a <yyterm
b300: 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79  >schema-name</yy
b310: 74 65 72 6d 3e 20 69 73 20 73 70 65 63 69 66 69  term> is specifi
b320: 65 64 2c 20 69 74 20 6d 75 73 74 20 62 65 20 65  ed, it must be e
b330: 69 74 68 65 72 20 22 6d 61 69 6e 22 2c 20 0a 20  ither "main", . 
b340: 20 22 74 65 6d 70 22 2c 20 6f 72 20 74 68 65 20   "temp", or the 
b350: 6e 61 6d 65 20 6f 66 20 61 6e 20 5b 41 54 54 41  name of an [ATTA
b360: 43 48 20 44 41 54 41 42 41 53 45 7c 61 74 74 61  CH DATABASE|atta
b370: 63 68 65 64 20 64 61 74 61 62 61 73 65 5d 2e 20  ched database]. 
b380: 5e 49 6e 20 74 68 69 73 20 63 61 73 65 0a 20 20  ^In this case.  
b390: 74 68 65 20 6e 65 77 20 74 61 62 6c 65 20 69 73  the new table is
b3a0: 20 63 72 65 61 74 65 64 20 69 6e 20 74 68 65 20   created in the 
b3b0: 6e 61 6d 65 64 20 64 61 74 61 62 61 73 65 2e 20  named database. 
b3c0: 5e 49 66 20 74 68 65 20 22 54 45 4d 50 22 20 6f  ^If the "TEMP" o
b3d0: 72 20 22 54 45 4d 50 4f 52 41 52 59 22 0a 20 20  r "TEMPORARY".  
b3e0: 6b 65 79 77 6f 72 64 20 6f 63 63 75 72 73 20 62  keyword occurs b
b3f0: 65 74 77 65 65 6e 20 74 68 65 20 22 43 52 45 41  etween the "CREA
b400: 54 45 22 20 61 6e 64 20 22 54 41 42 4c 45 22 20  TE" and "TABLE" 
b410: 74 68 65 6e 20 74 68 65 20 6e 65 77 20 74 61 62  then the new tab
b420: 6c 65 20 69 73 0a 20 20 63 72 65 61 74 65 64 20  le is.  created 
b430: 69 6e 20 74 68 65 20 74 65 6d 70 20 64 61 74 61  in the temp data
b440: 62 61 73 65 2e 20 5e 49 74 20 69 73 20 61 6e 20  base. ^It is an 
b450: 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
b460: 20 62 6f 74 68 20 61 20 0a 20 20 3c 79 79 74 65   both a .  <yyte
b470: 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f  rm>schema-name</
b480: 79 79 74 65 72 6d 3e 20 61 6e 64 20 74 68 65 20  yyterm> and the 
b490: 54 45 4d 50 20 6f 72 20 54 45 4d 50 4f 52 41 52  TEMP or TEMPORAR
b4a0: 59 20 6b 65 79 77 6f 72 64 2c 20 75 6e 6c 65 73  Y keyword, unles
b4b0: 73 20 74 68 65 0a 20 20 3c 79 79 74 65 72 6d 3e  s the.  <yyterm>
b4c0: 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74  schema-name</yyt
b4d0: 65 72 6d 3e 20 69 73 20 22 74 65 6d 70 22 2e 20  erm> is "temp". 
b4e0: 0a 20 20 5e 49 66 20 6e 6f 20 73 63 68 65 6d 61  .  ^If no schema
b4f0: 20 6e 61 6d 65 20 69 73 20 73 70 65 63 69 66 69   name is specifi
b500: 65 64 20 61 6e 64 20 74 68 65 0a 20 20 54 45 4d  ed and the.  TEM
b510: 50 20 6b 65 79 77 6f 72 64 20 69 73 20 6e 6f 74  P keyword is not
b520: 20 70 72 65 73 65 6e 74 20 74 68 65 6e 20 74 68   present then th
b530: 65 20 74 61 62 6c 65 20 69 73 20 63 72 65 61 74  e table is creat
b540: 65 64 20 69 6e 20 74 68 65 20 6d 61 69 6e 0a 20  ed in the main. 
b550: 20 64 61 74 61 62 61 73 65 2e 0a 0a 3c 70 3e 0a   database...<p>.
b560: 20 20 5e 49 74 20 69 73 20 75 73 75 61 6c 6c 79    ^It is usually
b570: 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 61 74 74   an error to att
b580: 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
b590: 20 6e 65 77 20 74 61 62 6c 65 20 69 6e 20 61 20   new table in a 
b5a0: 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 20 20  database that.  
b5b0: 61 6c 72 65 61 64 79 20 63 6f 6e 74 61 69 6e 73  already contains
b5c0: 20 61 20 74 61 62 6c 65 2c 20 69 6e 64 65 78 20   a table, index 
b5d0: 6f 72 20 76 69 65 77 20 6f 66 20 74 68 65 20 73  or view of the s
b5e0: 61 6d 65 20 6e 61 6d 65 2e 20 5e 48 6f 77 65 76  ame name. ^Howev
b5f0: 65 72 2c 20 69 66 20 74 68 65 0a 20 20 22 49 46  er, if the.  "IF
b600: 20 4e 4f 54 20 45 58 49 53 54 53 22 20 63 6c 61   NOT EXISTS" cla
b610: 75 73 65 20 69 73 20 73 70 65 63 69 66 69 65 64  use is specified
b620: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
b630: 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74 61  CREATE TABLE sta
b640: 74 65 6d 65 6e 74 20 61 6e 64 0a 20 20 61 20 74  tement and.  a t
b650: 61 62 6c 65 20 6f 72 20 76 69 65 77 20 6f 66 20  able or view of 
b660: 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 6c  the same name al
b670: 72 65 61 64 79 20 65 78 69 73 74 73 2c 20 74 68  ready exists, th
b680: 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 63  e CREATE TABLE c
b690: 6f 6d 6d 61 6e 64 0a 20 20 73 69 6d 70 6c 79 20  ommand.  simply 
b6a0: 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 28 61  has no effect (a
b6b0: 6e 64 20 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73  nd no error mess
b6c0: 61 67 65 20 69 73 20 72 65 74 75 72 6e 65 64 29  age is returned)
b6d0: 2e 20 5e 41 6e 20 65 72 72 6f 72 20 69 73 20 73  . ^An error is s
b6e0: 74 69 6c 6c 0a 20 20 72 65 74 75 72 6e 65 64 20  till.  returned 
b6f0: 69 66 20 74 68 65 20 74 61 62 6c 65 20 63 61 6e  if the table can
b700: 6e 6f 74 20 62 65 20 63 72 65 61 74 65 64 20 62  not be created b
b710: 65 63 61 75 73 65 20 6f 66 20 61 6e 20 65 78 69  ecause of an exi
b720: 73 74 69 6e 67 20 69 6e 64 65 78 2c 20 65 76 65  sting index, eve
b730: 6e 20 0a 20 20 69 66 20 74 68 65 20 22 49 46 20  n .  if the "IF 
b740: 4e 4f 54 20 45 58 49 53 54 53 22 20 63 6c 61 75  NOT EXISTS" clau
b750: 73 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2e  se is specified.
b760: 0a 0a 3c 70 3e 5e 49 74 20 69 73 20 6e 6f 74 20  ..<p>^It is not 
b770: 61 6e 20 65 72 72 6f 72 20 74 6f 20 63 72 65 61  an error to crea
b780: 74 65 20 61 20 74 61 62 6c 65 20 74 68 61 74 20  te a table that 
b790: 68 61 73 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  has the same nam
b7a0: 65 20 61 73 20 61 6e 20 0a 20 20 65 78 69 73 74  e as an .  exist
b7b0: 69 6e 67 20 5b 43 52 45 41 54 45 20 54 52 49 47  ing [CREATE TRIG
b7c0: 47 45 52 7c 74 72 69 67 67 65 72 5d 2e 0a 0a 3c  GER|trigger]...<
b7d0: 70 3e 5e 54 61 62 6c 65 73 20 61 72 65 20 72 65  p>^Tables are re
b7e0: 6d 6f 76 65 64 20 75 73 69 6e 67 20 74 68 65 20  moved using the 
b7f0: 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 73 74 61  [DROP TABLE] sta
b800: 74 65 6d 65 6e 74 2e 20 20 3c 2f 70 3e 0a 0a 3c  tement.  </p>..<
b810: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
b820: 63 72 65 61 74 65 74 61 62 61 73 20 7b 43 52 45  createtabas {CRE
b830: 41 54 45 20 54 41 42 4c 45 20 41 53 7d 3c 2f 74  ATE TABLE AS}</t
b840: 63 6c 3e 0a 3c 68 33 3e 43 52 45 41 54 45 20 54  cl>.<h3>CREATE T
b850: 41 42 4c 45 20 2e 2e 2e 20 41 53 20 53 45 4c 45  ABLE ... AS SELE
b860: 43 54 20 53 74 61 74 65 6d 65 6e 74 73 3c 2f 68  CT Statements</h
b870: 33 3e 0a 0a 3c 70 3e 5e 28 41 20 22 43 52 45 41  3>..<p>^(A "CREA
b880: 54 45 20 54 41 42 4c 45 20 2e 2e 2e 20 41 53 20  TE TABLE ... AS 
b890: 53 45 4c 45 43 54 22 20 73 74 61 74 65 6d 65 6e  SELECT" statemen
b8a0: 74 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  t creates and po
b8b0: 70 75 6c 61 74 65 73 20 61 20 64 61 74 61 62 61  pulates a databa
b8c0: 73 65 0a 74 61 62 6c 65 20 62 61 73 65 64 20 6f  se.table based o
b8d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  n the results of
b8e0: 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
b8f0: 65 6e 74 2e 29 5e 20 5e 28 54 68 65 20 74 61 62  ent.)^ ^(The tab
b900: 6c 65 20 68 61 73 20 74 68 65 20 73 61 6d 65 0a  le has the same.
b910: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
b920: 73 20 61 73 20 74 68 65 20 72 6f 77 73 20 72 65  s as the rows re
b930: 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 53 45  turned by the SE
b940: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20  LECT statement. 
b950: 54 68 65 20 6e 61 6d 65 20 6f 66 0a 65 61 63 68  The name of.each
b960: 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 73   column is the s
b970: 61 6d 65 20 61 73 20 74 68 65 20 6e 61 6d 65 20  ame as the name 
b980: 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
b990: 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  ding column in t
b9a0: 68 65 20 72 65 73 75 6c 74 0a 73 65 74 20 6f 66  he result.set of
b9b0: 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
b9c0: 65 6d 65 6e 74 2e 29 5e 20 5e 28 54 68 65 20 64  ement.)^ ^(The d
b9d0: 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
b9e0: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20 64  each column is d
b9f0: 65 74 65 72 6d 69 6e 65 64 0a 62 79 20 74 68 65  etermined.by the
ba00: 20 5b 65 78 70 72 65 73 73 69 6f 6e 20 61 66 66   [expression aff
ba10: 69 6e 69 74 79 5d 20 6f 66 20 74 68 65 20 63 6f  inity] of the co
ba20: 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 78 70 72  rresponding expr
ba30: 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65  ession in the re
ba40: 73 75 6c 74 20 73 65 74 0a 6f 66 20 74 68 65 20  sult set.of the 
ba50: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
ba60: 2c 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 3c 2f  , as follows:.</
ba70: 70 3e 0a 0a 3c 63 65 6e 74 65 72 3e 3c 74 61 62  p>..<center><tab
ba80: 6c 65 20 62 6f 72 64 65 72 3d 31 3e 0a 20 20 3c  le border=1>.  <
ba90: 74 72 3e 3c 74 68 3e 45 78 70 72 65 73 73 69 6f  tr><th>Expressio
baa0: 6e 20 41 66 66 69 6e 69 74 79 20 20 20 3c 74 68  n Affinity   <th
bab0: 3e 43 6f 6c 75 6d 6e 20 44 65 63 6c 61 72 65 64  >Column Declared
bac0: 20 54 79 70 65 0a 20 20 3c 74 72 3e 3c 74 64 3e   Type.  <tr><td>
bad0: 54 45 58 54 20 20 20 20 20 20 20 20 20 20 20 20  TEXT            
bae0: 20 20 20 20 20 20 3c 74 64 3e 22 54 45 58 54 22        <td>"TEXT"
baf0: 0a 20 20 3c 74 72 3e 3c 74 64 3e 4e 55 4d 45 52  .  <tr><td>NUMER
bb00: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
bb10: 20 3c 74 64 3e 22 4e 55 4d 22 0a 20 20 3c 74 72   <td>"NUM".  <tr
bb20: 3e 3c 74 64 3e 49 4e 54 45 47 45 52 20 20 20 20  ><td>INTEGER    
bb30: 20 20 20 20 20 20 20 20 20 20 20 3c 74 64 3e 22             <td>"
bb40: 49 4e 54 22 0a 20 20 3c 74 72 3e 3c 74 64 3e 52  INT".  <tr><td>R
bb50: 45 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  EAL             
bb60: 20 20 20 20 20 3c 74 64 3e 22 52 45 41 4c 22 0a       <td>"REAL".
bb70: 20 20 3c 74 72 3e 3c 74 64 3e 42 4c 4f 42 20 28    <tr><td>BLOB (
bb80: 61 2e 6b 2e 61 20 22 4e 4f 4e 45 22 29 20 20 20  a.k.a "NONE")   
bb90: 3c 74 64 3e 22 22 20 28 65 6d 70 74 79 20 73 74  <td>"" (empty st
bba0: 72 69 6e 67 29 0a 3c 2f 74 61 62 6c 65 3e 3c 2f  ring).</table></
bbb0: 63 65 6e 74 65 72 3e 29 5e 0a 0a 3c 70 3e 5e 28  center>)^..<p>^(
bbc0: 41 20 74 61 62 6c 65 20 63 72 65 61 74 65 64 20  A table created 
bbd0: 75 73 69 6e 67 20 43 52 45 41 54 45 20 54 41 42  using CREATE TAB
bbe0: 4c 45 20 41 53 20 68 61 73 20 6e 6f 20 50 52 49  LE AS has no PRI
bbf0: 4d 41 52 59 20 4b 45 59 20 61 6e 64 20 6e 6f 0a  MARY KEY and no.
bc00: 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 61  constraints of a
bc10: 6e 79 20 6b 69 6e 64 2e 20 54 68 65 20 64 65 66  ny kind. The def
bc20: 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 65 61  ault value of ea
bc30: 63 68 20 63 6f 6c 75 6d 6e 20 69 73 20 4e 55 4c  ch column is NUL
bc40: 4c 2e 20 54 68 65 20 64 65 66 61 75 6c 74 0a 63  L. The default.c
bc50: 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
bc60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
bc70: 6e 20 6f 66 20 74 68 65 20 6e 65 77 20 74 61 62  n of the new tab
bc80: 6c 65 20 69 73 20 42 49 4e 41 52 59 2e 29 5e 0a  le is BINARY.)^.
bc90: 0a 3c 70 3e 5e 54 61 62 6c 65 73 20 63 72 65 61  .<p>^Tables crea
bca0: 74 65 64 20 75 73 69 6e 67 20 43 52 45 41 54 45  ted using CREATE
bcb0: 20 54 41 42 4c 45 20 41 53 20 61 72 65 20 69 6e   TABLE AS are in
bcc0: 69 74 69 61 6c 6c 79 20 70 6f 70 75 6c 61 74 65  itially populate
bcd0: 64 20 77 69 74 68 20 74 68 65 0a 72 6f 77 73 20  d with the.rows 
bce0: 6f 66 20 64 61 74 61 20 72 65 74 75 72 6e 65 64  of data returned
bcf0: 20 62 79 20 74 68 65 20 53 45 4c 45 43 54 20 73   by the SELECT s
bd00: 74 61 74 65 6d 65 6e 74 2e 20 5e 52 6f 77 73 20  tatement. ^Rows 
bd10: 61 72 65 20 61 73 73 69 67 6e 65 64 20 63 6f 6e  are assigned con
bd20: 74 69 67 75 6f 75 73 6c 79 0a 61 73 63 65 6e 64  tiguously.ascend
bd30: 69 6e 67 20 5b 72 6f 77 69 64 5d 20 76 61 6c 75  ing [rowid] valu
bd40: 65 73 2c 20 73 74 61 72 74 69 6e 67 20 77 69 74  es, starting wit
bd50: 68 20 31 2c 20 69 6e 20 74 68 65 20 5b 6f 72 64  h 1, in the [ord
bd60: 65 72 20 62 79 7c 6f 72 64 65 72 5d 20 74 68 61  er by|order] tha
bd70: 74 20 74 68 65 79 0a 61 72 65 20 72 65 74 75 72  t they.are retur
bd80: 6e 65 64 20 62 79 20 74 68 65 20 53 45 4c 45 43  ned by the SELEC
bd90: 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 74  T statement...<t
bda0: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b  cl>hd_fragment {
bdb0: 74 61 62 6c 65 63 6f 6c 64 65 66 7d 20 7b 63 6f  tablecoldef} {co
bdc0: 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 7d  lumn definition}
bdd0: 20 7b 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74   {column definit
bde0: 69 6f 6e 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  ions}</tcl>.<h3>
bdf0: 43 6f 6c 75 6d 6e 20 44 65 66 69 6e 69 74 69 6f  Column Definitio
be00: 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 55 6e 6c 65  ns</h3>..<p>Unle
be10: 73 73 20 69 74 20 69 73 20 61 20 43 52 45 41 54  ss it is a CREAT
be20: 45 20 54 41 42 4c 45 20 2e 2e 2e 20 41 53 20 53  E TABLE ... AS S
be30: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c  ELECT statement,
be40: 20 61 20 43 52 45 41 54 45 20 54 41 42 4c 45 20   a CREATE TABLE 
be50: 69 6e 63 6c 75 64 65 73 0a 6f 6e 65 20 6f 72 20  includes.one or 
be60: 6d 6f 72 65 20 5b 63 6f 6c 75 6d 6e 2d 64 65 66  more [column-def
be70: 7c 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69  |column definiti
be80: 6f 6e 73 5d 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  ons], optionally
be90: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 6c   followed by a l
bea0: 69 73 74 20 6f 66 0a 5b 74 61 62 6c 65 2d 63 6f  ist of.[table-co
beb0: 6e 73 74 72 61 69 6e 74 7c 74 61 62 6c 65 20 63  nstraint|table c
bec0: 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 45 61  onstraints].  Ea
bed0: 63 68 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69  ch column defini
bee0: 74 69 6f 6e 20 63 6f 6e 73 69 73 74 73 20 6f 66  tion consists of
bef0: 20 74 68 65 0a 6e 61 6d 65 20 6f 66 20 74 68 65   the.name of the
bf00: 20 63 6f 6c 75 6d 6e 2c 20 6f 70 74 69 6f 6e 61   column, optiona
bf10: 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  lly followed by 
bf20: 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
bf30: 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 2c  e of the column,
bf40: 0a 74 68 65 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72  .then one or mor
bf50: 65 20 6f 70 74 69 6f 6e 61 6c 20 5b 63 6f 6c 75  e optional [colu
bf60: 6d 6e 2d 63 6f 6e 73 74 72 61 69 6e 74 7c 63 6f  mn-constraint|co
bf70: 6c 75 6d 6e 20 63 6f 6e 73 74 72 61 69 6e 74 73  lumn constraints
bf80: 5d 2e 20 49 6e 63 6c 75 64 65 64 20 69 6e 0a 74  ]. Included in.t
bf90: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66  he definition of
bfa0: 20 22 63 6f 6c 75 6d 6e 20 63 6f 6e 73 74 72 61   "column constra
bfb0: 69 6e 74 73 22 20 66 6f 72 20 74 68 65 20 70 75  ints" for the pu
bfc0: 72 70 6f 73 65 73 20 6f 66 20 74 68 65 20 70 72  rposes of the pr
bfd0: 65 76 69 6f 75 73 0a 73 74 61 74 65 6d 65 6e 74  evious.statement
bfe0: 20 61 72 65 20 74 68 65 20 43 4f 4c 4c 41 54 45   are the COLLATE
bff0: 20 61 6e 64 20 44 45 46 41 55 4c 54 20 63 6c 61   and DEFAULT cla
c000: 75 73 65 73 2c 20 65 76 65 6e 20 74 68 6f 75 67  uses, even thoug
c010: 68 20 74 68 65 73 65 20 61 72 65 20 6e 6f 74 20  h these are not 
c020: 72 65 61 6c 6c 79 0a 63 6f 6e 73 74 72 61 69 6e  really.constrain
c030: 74 73 20 69 6e 20 74 68 65 20 73 65 6e 73 65 20  ts in the sense 
c040: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
c050: 20 72 65 73 74 72 69 63 74 20 74 68 65 20 64 61   restrict the da
c060: 74 61 20 74 68 61 74 20 74 68 65 20 74 61 62 6c  ta that the tabl
c070: 65 20 6d 61 79 0a 63 6f 6e 74 61 69 6e 2e 20 54  e may.contain. T
c080: 68 65 20 6f 74 68 65 72 20 63 6f 6e 73 74 72 61  he other constra
c090: 69 6e 74 73 20 2d 20 4e 4f 54 20 4e 55 4c 4c 2c  ints - NOT NULL,
c0a0: 20 43 48 45 43 4b 2c 20 55 4e 49 51 55 45 2c 20   CHECK, UNIQUE, 
c0b0: 50 52 49 4d 41 52 59 20 4b 45 59 20 61 6e 64 0a  PRIMARY KEY and.
c0c0: 46 4f 52 45 49 47 4e 20 4b 45 59 20 63 6f 6e 73  FOREIGN KEY cons
c0d0: 74 72 61 69 6e 74 73 20 2d 20 69 6d 70 6f 73 65  traints - impose
c0e0: 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20 6f 6e   restrictions on
c0f0: 20 74 68 65 20 74 61 62 6c 65 73 20 64 61 74 61   the tables data
c100: 2c 20 61 6e 64 20 61 72 65 20 61 72 65 0a 64 65  , and are are.de
c110: 73 63 72 69 62 65 64 20 75 6e 64 65 72 20 5b 63  scribed under [c
c120: 6f 6e 73 74 72 61 69 6e 74 73 7c 53 51 4c 20 44  onstraints|SQL D
c130: 61 74 61 20 43 6f 6e 73 74 72 61 69 6e 74 73 5d  ata Constraints]
c140: 20 62 65 6c 6f 77 2e 20 54 68 65 0a 5b 67 65 6e   below. The.[gen
c150: 65 72 61 74 65 64 20 63 6f 6c 75 6d 6e 5d 20 73  erated column] s
c160: 79 6e 74 61 78 20 69 73 20 73 75 70 70 6f 72 74  yntax is support
c170: 65 64 20 73 69 6e 63 65 20 53 51 4c 69 74 65 20  ed since SQLite 
c180: 33 2e 33 31 2e 30 20 28 5b 64 61 74 65 6f 66 3a  3.31.0 ([dateof:
c190: 33 2e 33 31 2e 30 5d 29 2e 0a 0a 3c 70 3e 5e 55  3.31.0])...<p>^U
c1a0: 6e 6c 69 6b 65 20 6d 6f 73 74 20 53 51 4c 20 64  nlike most SQL d
c1b0: 61 74 61 62 61 73 65 73 2c 20 53 51 4c 69 74 65  atabases, SQLite
c1c0: 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 74 72 69   does not restri
c1d0: 63 74 20 74 68 65 20 74 79 70 65 20 6f 66 20 64  ct the type of d
c1e0: 61 74 61 20 74 68 61 74 0a 6d 61 79 20 62 65 20  ata that.may be 
c1f0: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 20  inserted into a 
c200: 63 6f 6c 75 6d 6e 20 62 61 73 65 64 20 6f 6e 20  column based on 
c210: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 64 65 63 6c  the columns decl
c220: 61 72 65 64 20 74 79 70 65 2e 20 49 6e 73 74 65  ared type. Inste
c230: 61 64 2c 0a 53 51 4c 69 74 65 20 75 73 65 73 20  ad,.SQLite uses 
c240: 5b 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 5d  [dynamic typing]
c250: 2e 20 5e 54 68 65 20 64 65 63 6c 61 72 65 64 20  . ^The declared 
c260: 74 79 70 65 20 6f 66 20 61 20 63 6f 6c 75 6d 6e  type of a column
c270: 20 69 73 20 75 73 65 64 20 74 6f 0a 64 65 74 65   is used to.dete
c280: 72 6d 69 6e 65 20 74 68 65 20 5b 61 66 66 69 6e  rmine the [affin
c290: 69 74 79 5d 20 6f 66 20 74 68 65 20 63 6f 6c 75  ity] of the colu
c2a0: 6d 6e 20 6f 6e 6c 79 2e 0a 0a 3c 74 63 6c 3e 68  mn only...<tcl>h
c2b0: 64 5f 66 72 61 67 6d 65 6e 74 20 64 66 6c 74 76  d_fragment dfltv
c2c0: 61 6c 20 7b 64 65 66 61 75 6c 74 20 63 6f 6c 75  al {default colu
c2d0: 6d 6e 20 76 61 6c 75 65 7d 20 7b 64 65 66 61 75  mn value} {defau
c2e0: 6c 74 20 76 61 6c 75 65 7d 3c 2f 74 63 6c 3e 0a  lt value}</tcl>.
c2f0: 3c 70 3e 54 68 65 20 44 45 46 41 55 4c 54 20 63  <p>The DEFAULT c
c300: 6c 61 75 73 65 20 73 70 65 63 69 66 69 65 73 20  lause specifies 
c310: 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
c320: 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20 63  to use for the c
c330: 6f 6c 75 6d 6e 20 69 66 20 6e 6f 0a 76 61 6c 75  olumn if no.valu
c340: 65 20 69 73 20 65 78 70 6c 69 63 69 74 6c 79 20  e is explicitly 
c350: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
c360: 75 73 65 72 20 77 68 65 6e 20 64 6f 69 6e 67 20  user when doing 
c370: 61 6e 20 5b 49 4e 53 45 52 54 5d 2e 20 5e 49 66  an [INSERT]. ^If
c380: 20 74 68 65 72 65 0a 69 73 20 6e 6f 20 65 78 70   there.is no exp
c390: 6c 69 63 69 74 20 44 45 46 41 55 4c 54 20 63 6c  licit DEFAULT cl
c3a0: 61 75 73 65 20 61 74 74 61 63 68 65 64 20 74 6f  ause attached to
c3b0: 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69   a column defini
c3c0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 0a  tion, then the .
c3d0: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
c3e0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 4e   the column is N
c3f0: 55 4c 4c 2e 20 5e 28 41 6e 20 65 78 70 6c 69 63  ULL. ^(An explic
c400: 69 74 20 44 45 46 41 55 4c 54 20 63 6c 61 75 73  it DEFAULT claus
c410: 65 20 6d 61 79 20 73 70 65 63 69 66 79 0a 74 68  e may specify.th
c420: 61 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 76  at the default v
c430: 61 6c 75 65 20 69 73 20 4e 55 4c 4c 2c 20 61 20  alue is NULL, a 
c440: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2c  string constant,
c450: 20 61 20 62 6c 6f 62 20 63 6f 6e 73 74 61 6e 74   a blob constant
c460: 2c 20 61 0a 73 69 67 6e 65 64 2d 6e 75 6d 62 65  , a.signed-numbe
c470: 72 2c 20 6f 72 20 61 6e 79 20 63 6f 6e 73 74 61  r, or any consta
c480: 6e 74 20 65 78 70 72 65 73 73 69 6f 6e 20 65 6e  nt expression en
c490: 63 6c 6f 73 65 64 20 69 6e 20 70 61 72 65 6e 74  closed in parent
c4a0: 68 65 73 65 73 2e 20 41 0a 64 65 66 61 75 6c 74  heses. A.default
c4b0: 20 76 61 6c 75 65 20 6d 61 79 20 61 6c 73 6f 20   value may also 
c4c0: 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70  be one of the sp
c4d0: 65 63 69 61 6c 20 63 61 73 65 2d 69 6e 64 65 70  ecial case-indep
c4e0: 65 6e 64 65 6e 74 20 6b 65 79 77 6f 72 64 73 0a  endent keywords.
c4f0: 43 55 52 52 45 4e 54 5f 54 49 4d 45 2c 20 43 55  CURRENT_TIME, CU
c500: 52 52 45 4e 54 5f 44 41 54 45 20 6f 72 20 43 55  RRENT_DATE or CU
c510: 52 52 45 4e 54 5f 54 49 4d 45 53 54 41 4d 50 2e  RRENT_TIMESTAMP.
c520: 29 5e 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  )^ ^For the purp
c530: 6f 73 65 73 20 6f 66 20 74 68 65 0a 44 45 46 41  oses of the.DEFA
c540: 55 4c 54 20 63 6c 61 75 73 65 2c 20 61 6e 20 65  ULT clause, an e
c550: 78 70 72 65 73 73 69 6f 6e 20 69 73 20 63 6f 6e  xpression is con
c560: 73 69 64 65 72 65 64 20 63 6f 6e 73 74 61 6e 74  sidered constant
c570: 20 69 66 20 69 74 0a 63 6f 6e 74 61 69 6e 73 20   if it.contains 
c580: 6e 6f 20 73 75 62 2d 71 75 65 72 69 65 73 2c 20  no sub-queries, 
c590: 63 6f 6c 75 6d 6e 20 6f 72 20 74 61 62 6c 65 20  column or table 
c5a0: 72 65 66 65 72 65 6e 63 65 73 2c 20 5b 62 6f 75  references, [bou
c5b0: 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2c 0a  nd parameters],.
c5c0: 6f 72 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  or string litera
c5d0: 6c 73 20 65 6e 63 6c 6f 73 65 64 20 69 6e 20 64  ls enclosed in d
c5e0: 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
c5f0: 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 2d 71  tead of single-q
c600: 75 6f 74 65 73 2e 0a 0a 3c 70 3e 5e 28 45 61 63  uotes...<p>^(Eac
c610: 68 20 74 69 6d 65 20 61 20 72 6f 77 20 69 73 20  h time a row is 
c620: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74 68  inserted into th
c630: 65 20 74 61 62 6c 65 20 62 79 20 61 6e 20 49 4e  e table by an IN
c640: 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20 74  SERT statement t
c650: 68 61 74 20 0a 64 6f 65 73 20 6e 6f 74 20 70 72  hat .does not pr
c660: 6f 76 69 64 65 20 65 78 70 6c 69 63 69 74 20 76  ovide explicit v
c670: 61 6c 75 65 73 20 66 6f 72 20 61 6c 6c 20 74 61  alues for all ta
c680: 62 6c 65 20 63 6f 6c 75 6d 6e 73 20 74 68 65 20  ble columns the 
c690: 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  values stored in
c6a0: 0a 74 68 65 20 6e 65 77 20 72 6f 77 20 61 72 65  .the new row are
c6b0: 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
c6c0: 68 65 69 72 20 64 65 66 61 75 6c 74 20 76 61 6c  heir default val
c6d0: 75 65 73 29 5e 2c 20 61 73 20 66 6f 6c 6c 6f 77  ues)^, as follow
c6e0: 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 3c  s:..<ul>.  <li><
c6f0: 70 3e 5e 49 66 20 74 68 65 20 64 65 66 61 75 6c  p>^If the defaul
c700: 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63  t value of the c
c710: 6f 6c 75 6d 6e 20 69 73 20 61 20 63 6f 6e 73 74  olumn is a const
c720: 61 6e 74 20 4e 55 4c 4c 2c 20 74 65 78 74 2c 20  ant NULL, text, 
c730: 62 6c 6f 62 20 6f 72 0a 20 20 20 20 73 69 67 6e  blob or.    sign
c740: 65 64 2d 6e 75 6d 62 65 72 20 76 61 6c 75 65 2c  ed-number value,
c750: 20 74 68 65 6e 20 74 68 61 74 20 76 61 6c 75 65   then that value
c760: 20 69 73 20 75 73 65 64 20 64 69 72 65 63 74 6c   is used directl
c770: 79 20 69 6e 20 74 68 65 20 6e 65 77 20 72 6f 77  y in the new row
c780: 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20  ...  <li><p>^If 
c790: 74 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  the default valu
c7a0: 65 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20 69 73  e of a column is
c7b0: 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 69   an expression i
c7c0: 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2c 20 74  n parentheses, t
c7d0: 68 65 6e 0a 20 20 20 20 74 68 65 20 65 78 70 72  hen.    the expr
c7e0: 65 73 73 69 6f 6e 20 69 73 20 65 76 61 6c 75 61  ession is evalua
c7f0: 74 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ted once for eac
c800: 68 20 72 6f 77 20 69 6e 73 65 72 74 65 64 20 61  h row inserted a
c810: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 73 0a 20  nd the results. 
c820: 20 20 20 75 73 65 64 20 69 6e 20 74 68 65 20 6e     used in the n
c830: 65 77 20 72 6f 77 2e 0a 0a 20 20 3c 6c 69 3e 3c  ew row...  <li><
c840: 70 3e 5e 49 66 20 74 68 65 20 64 65 66 61 75 6c  p>^If the defaul
c850: 74 20 76 61 6c 75 65 20 6f 66 20 61 20 63 6f 6c  t value of a col
c860: 75 6d 6e 20 69 73 20 43 55 52 52 45 4e 54 5f 54  umn is CURRENT_T
c870: 49 4d 45 2c 20 43 55 52 52 45 4e 54 5f 44 41 54  IME, CURRENT_DAT
c880: 45 20 6f 72 0a 20 20 20 20 43 55 52 52 45 4e 54  E or.    CURRENT
c890: 5f 54 49 4d 45 53 54 41 4d 50 2c 20 74 68 65 6e  _TIMESTAMP, then
c8a0: 20 74 68 65 20 76 61 6c 75 65 20 75 73 65 64 20   the value used 
c8b0: 69 6e 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69  in the new row i
c8c0: 73 20 61 20 74 65 78 74 0a 20 20 20 20 72 65 70  s a text.    rep
c8d0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  resentation of t
c8e0: 68 65 20 63 75 72 72 65 6e 74 20 55 54 43 20 64  he current UTC d
c8f0: 61 74 65 20 61 6e 64 2f 6f 72 20 74 69 6d 65 2e  ate and/or time.
c900: 20 5e 46 6f 72 20 43 55 52 52 45 4e 54 5f 54 49   ^For CURRENT_TI
c910: 4d 45 2c 20 74 68 65 0a 20 20 20 20 66 6f 72 6d  ME, the.    form
c920: 61 74 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20  at of the value 
c930: 69 73 20 22 48 48 3a 4d 4d 3a 53 53 22 2e 20 5e  is "HH:MM:SS". ^
c940: 46 6f 72 20 43 55 52 52 45 4e 54 5f 44 41 54 45  For CURRENT_DATE
c950: 2c 20 22 59 59 59 59 2d 4d 4d 2d 44 44 22 2e 20  , "YYYY-MM-DD". 
c960: 5e 54 68 65 0a 20 20 20 20 66 6f 72 6d 61 74 20  ^The.    format 
c970: 66 6f 72 20 43 55 52 52 45 4e 54 5f 54 49 4d 45  for CURRENT_TIME
c980: 53 54 41 4d 50 20 69 73 20 22 59 59 59 59 2d 4d  STAMP is "YYYY-M
c990: 4d 2d 44 44 20 48 48 3a 4d 4d 3a 53 53 22 2e 0a  M-DD HH:MM:SS"..
c9a0: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 43  </ul>..<p>^The C
c9b0: 4f 4c 4c 41 54 45 20 63 6c 61 75 73 65 20 73 70  OLLATE clause sp
c9c0: 65 63 69 66 69 65 73 20 74 68 65 20 6e 61 6d 65  ecifies the name
c9d0: 20 6f 66 20 61 20 5b 63 6f 6c 6c 61 74 69 6e 67   of a [collating
c9e0: 20 73 65 71 75 65 6e 63 65 5d 20 74 6f 20 75 73   sequence] to us
c9f0: 65 20 61 73 0a 74 68 65 20 64 65 66 61 75 6c 74  e as.the default
ca00: 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
ca10: 6e 63 65 20 66 6f 72 20 74 68 65 20 63 6f 6c 75  nce for the colu
ca20: 6d 6e 2e 20 5e 49 66 20 6e 6f 20 43 4f 4c 4c 41  mn. ^If no COLLA
ca30: 54 45 20 63 6c 61 75 73 65 20 69 73 0a 73 70 65  TE clause is.spe
ca40: 63 69 66 69 65 64 2c 20 74 68 65 20 64 65 66 61  cified, the defa
ca50: 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
ca60: 71 75 65 6e 63 65 20 69 73 20 5b 42 49 4e 41 52  quence is [BINAR
ca70: 59 5d 2e 0a 0a 3c 70 3e 5e 54 68 65 20 6e 75 6d  Y]...<p>^The num
ca80: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
ca90: 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 69 6d  n a table is lim
caa0: 69 74 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c  ited by the [SQL
cab0: 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 5d 0a  ITE_MAX_COLUMN].
cac0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 70 61 72  compile-time par
cad0: 61 6d 65 74 65 72 2e 20 5e 41 20 73 69 6e 67 6c  ameter. ^A singl
cae0: 65 20 72 6f 77 20 6f 66 20 61 20 74 61 62 6c 65  e row of a table
caf0: 20 63 61 6e 6e 6f 74 20 73 74 6f 72 65 20 6d 6f   cannot store mo
cb00: 72 65 20 74 68 61 6e 0a 5b 53 51 4c 49 54 45 5f  re than.[SQLITE_
cb10: 4d 41 58 5f 4c 45 4e 47 54 48 5d 20 62 79 74 65  MAX_LENGTH] byte
cb20: 73 20 6f 66 20 64 61 74 61 2e 20 5e 42 6f 74 68  s of data. ^Both
cb30: 20 6f 66 20 74 68 65 73 65 20 6c 69 6d 69 74 73   of these limits
cb40: 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
cb50: 61 74 0a 72 75 6e 74 69 6d 65 20 75 73 69 6e 67  at.runtime using
cb60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
cb70: 6d 69 74 28 29 5d 20 43 2f 43 2b 2b 20 69 6e 74  mit()] C/C++ int
cb80: 65 72 66 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 74 63  erface.</p>..<tc
cb90: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b 63  l>hd_fragment {c
cba0: 6f 6e 73 74 72 61 69 6e 74 73 7d 20 7b 63 6f 6e  onstraints} {con
cbb0: 73 74 72 61 69 6e 74 73 7d 3c 2f 74 63 6c 3e 0a  straints}</tcl>.
cbc0: 3c 68 33 3e 53 51 4c 20 44 61 74 61 20 43 6f 6e  <h3>SQL Data Con
cbd0: 73 74 72 61 69 6e 74 73 3c 2f 68 33 3e 0a 0a 3c  straints</h3>..<
cbe0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
cbf0: 70 72 69 6d 6b 65 79 63 6f 6e 73 74 20 7b 50 52  primkeyconst {PR
cc00: 49 4d 41 52 59 20 4b 45 59 7d 20 7b 50 52 49 4d  IMARY KEY} {PRIM
cc10: 41 52 59 20 4b 45 59 20 63 6f 6e 73 74 72 61 69  ARY KEY constrai
cc20: 6e 74 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 45 61  nt}</tcl>.<p>^Ea
cc30: 63 68 20 74 61 62 6c 65 20 69 6e 20 53 51 4c 69  ch table in SQLi
cc40: 74 65 20 6d 61 79 20 68 61 76 65 20 61 74 20 6d  te may have at m
cc50: 6f 73 74 20 6f 6e 65 20 3c 62 3e 50 52 49 4d 41  ost one <b>PRIMA
cc60: 52 59 20 4b 45 59 3c 2f 62 3e 2e 20 5e 49 66 20  RY KEY</b>. ^If 
cc70: 74 68 65 0a 20 20 6b 65 79 77 6f 72 64 73 20 50  the.  keywords P
cc80: 52 49 4d 41 52 59 20 4b 45 59 20 61 72 65 20 61  RIMARY KEY are a
cc90: 64 64 65 64 20 74 6f 20 61 20 63 6f 6c 75 6d 6e  dded to a column
cca0: 20 64 65 66 69 6e 69 74 69 6f 6e 2c 20 74 68 65   definition, the
ccb0: 6e 20 74 68 65 20 70 72 69 6d 61 72 79 20 6b 65  n the primary ke
ccc0: 79 0a 20 20 66 6f 72 20 74 68 65 20 74 61 62 6c  y.  for the tabl
ccd0: 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68  e consists of th
cce0: 61 74 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e  at single column
ccf0: 2e 20 5e 4f 72 2c 20 69 66 20 61 20 50 52 49 4d  . ^Or, if a PRIM
cd00: 41 52 59 20 4b 45 59 20 63 6c 61 75 73 65 20 0a  ARY KEY clause .
cd10: 20 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61    is specified a
cd20: 73 20 61 20 5b 74 61 62 6c 65 2d 63 6f 6e 73 74  s a [table-const
cd30: 72 61 69 6e 74 5d 2c 20 74 68 65 6e 20 74 68 65  raint], then the
cd40: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 6f 66 20   primary key of 
cd50: 74 68 65 20 74 61 62 6c 65 0a 20 20 63 6f 6e 73  the table.  cons
cd60: 69 73 74 73 20 6f 66 20 74 68 65 20 6c 69 73 74  ists of the list
cd70: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 73 70 65 63   of columns spec
cd80: 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
cd90: 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
cda0: 20 63 6c 61 75 73 65 2e 0a 20 20 5e 54 68 65 20   clause..  ^The 
cdb0: 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6c 61 75  PRIMARY KEY clau
cdc0: 73 65 20 6d 75 73 74 20 63 6f 6e 74 61 69 6e 20  se must contain 
cdd0: 6f 6e 6c 79 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  only column name
cde0: 73 20 26 6d 64 61 73 68 3b 20 74 68 65 20 75 73  s &mdash; the us
cdf0: 65 20 6f 66 20 0a 20 20 65 78 70 72 65 73 73 69  e of .  expressi
ce00: 6f 6e 73 20 69 6e 20 61 6e 20 5b 69 6e 64 65 78  ons in an [index
ce10: 65 64 2d 63 6f 6c 75 6d 6e 5d 20 6f 66 20 61 20  ed-column] of a 
ce20: 50 52 49 4d 41 52 59 20 4b 45 59 20 69 73 20 6e  PRIMARY KEY is n
ce30: 6f 74 20 73 75 70 70 6f 72 74 65 64 2e 0a 20 20  ot supported..  
ce40: 5e 41 6e 20 65 72 72 6f 72 20 69 73 20 72 61 69  ^An error is rai
ce50: 73 65 64 20 69 66 20 6d 6f 72 65 20 74 68 61 6e  sed if more than
ce60: 20 6f 6e 65 20 50 52 49 4d 41 52 59 20 4b 45 59   one PRIMARY KEY
ce70: 20 63 6c 61 75 73 65 20 61 70 70 65 61 72 73 20   clause appears 
ce80: 69 6e 20 61 0a 20 20 43 52 45 41 54 45 20 54 41  in a.  CREATE TA
ce90: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  BLE statement.  
cea0: 5e 54 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59  ^The PRIMARY KEY
ceb0: 20 69 73 20 6f 70 74 69 6f 6e 61 6c 20 66 6f 72   is optional for
cec0: 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
ced0: 0a 20 20 62 75 74 20 69 73 20 72 65 71 75 69 72  .  but is requir
cee0: 65 64 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  ed for [WITHOUT 
cef0: 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 2e 0a 0a  ROWID] tables...
cf00: 3c 70 3e 49 66 20 61 20 74 61 62 6c 65 20 68 61  <p>If a table ha
cf10: 73 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  s a single colum
cf20: 6e 20 70 72 69 6d 61 72 79 20 6b 65 79 20 61 6e  n primary key an
cf30: 64 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  d the declared t
cf40: 79 70 65 20 6f 66 20 74 68 61 74 0a 20 20 63 6f  ype of that.  co
cf50: 6c 75 6d 6e 20 69 73 20 22 49 4e 54 45 47 45 52  lumn is "INTEGER
cf60: 22 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20  " and the table 
cf70: 69 73 20 6e 6f 74 20 61 20 5b 57 49 54 48 4f 55  is not a [WITHOU
cf80: 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 2c 0a  T ROWID] table,.
cf90: 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 75 6d    then the colum
cfa0: 6e 20 69 73 20 6b 6e 6f 77 6e 20 61 73 20 61 6e  n is known as an
cfb0: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
cfc0: 59 20 4b 45 59 5d 2e 0a 20 20 53 65 65 20 5b 72  Y KEY]..  See [r
cfd0: 6f 77 69 64 7c 62 65 6c 6f 77 5d 20 66 6f 72 20  owid|below] for 
cfe0: 61 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  a description of
cff0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 70 72 6f   the special pro
d000: 70 65 72 74 69 65 73 20 61 6e 64 20 62 65 68 61  perties and beha
d010: 76 69 6f 72 73 0a 20 20 61 73 73 6f 63 69 61 74  viors.  associat
d020: 65 64 20 77 69 74 68 20 61 6e 20 5b 49 4e 54 45  ed with an [INTE
d030: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
d040: 2e 0a 0a 3c 70 3e 5e 45 61 63 68 20 72 6f 77 20  ...<p>^Each row 
d050: 69 6e 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  in a table with 
d060: 61 20 70 72 69 6d 61 72 79 20 6b 65 79 20 6d 75  a primary key mu
d070: 73 74 20 68 61 76 65 20 61 20 75 6e 69 71 75 65  st have a unique
d080: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 0a 20 20 6f   combination.  o
d090: 66 20 76 61 6c 75 65 73 20 69 6e 20 69 74 73 20  f values in its 
d0a0: 70 72 69 6d 61 72 79 20 6b 65 79 20 63 6f 6c 75  primary key colu
d0b0: 6d 6e 73 2e 20 5e 46 6f 72 20 74 68 65 20 70 75  mns. ^For the pu
d0c0: 72 70 6f 73 65 73 20 6f 66 20 64 65 74 65 72 6d  rposes of determ
d0d0: 69 6e 69 6e 67 0a 20 20 74 68 65 20 75 6e 69 71  ining.  the uniq
d0e0: 75 65 6e 65 73 73 20 6f 66 20 70 72 69 6d 61 72  ueness of primar
d0f0: 79 20 6b 65 79 20 76 61 6c 75 65 73 2c 20 4e 55  y key values, NU
d100: 4c 4c 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f  LL values are co
d110: 6e 73 69 64 65 72 65 64 20 64 69 73 74 69 6e 63  nsidered distinc
d120: 74 20 66 72 6f 6d 0a 20 20 61 6c 6c 20 6f 74 68  t from.  all oth
d130: 65 72 20 76 61 6c 75 65 73 2c 20 69 6e 63 6c 75  er values, inclu
d140: 64 69 6e 67 20 6f 74 68 65 72 20 4e 55 4c 4c 73  ding other NULLs
d150: 2e 20 5e 49 66 20 61 6e 20 5b 49 4e 53 45 52 54  . ^If an [INSERT
d160: 5d 20 6f 72 20 5b 55 50 44 41 54 45 5d 0a 20 20  ] or [UPDATE].  
d170: 73 74 61 74 65 6d 65 6e 74 20 61 74 74 65 6d 70  statement attemp
d180: 74 73 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ts to modify the
d190: 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 20 73   table content s
d1a0: 6f 20 74 68 61 74 20 74 77 6f 20 6f 72 20 6d 6f  o that two or mo
d1b0: 72 65 20 72 6f 77 73 0a 20 20 68 61 76 65 20 69  re rows.  have i
d1c0: 64 65 6e 74 69 63 61 6c 20 70 72 69 6d 61 72 79  dentical primary
d1d0: 20 6b 65 79 20 76 61 6c 75 65 73 2c 20 74 68 61   key values, tha
d1e0: 74 20 69 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  t is a constrain
d1f0: 74 20 76 69 6f 6c 61 74 69 6f 6e 2e 0a 0a 3c 70  t violation...<p
d200: 3e 20 41 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  > According to t
d210: 68 65 20 53 51 4c 20 73 74 61 6e 64 61 72 64 2c  he SQL standard,
d220: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 73 68 6f   PRIMARY KEY sho
d230: 75 6c 64 20 61 6c 77 61 79 73 20 69 6d 70 6c 79  uld always imply
d240: 20 4e 4f 54 20 4e 55 4c 4c 2e 0a 20 20 55 6e 66   NOT NULL..  Unf
d250: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 64 75 65 20  ortunately, due 
d260: 74 6f 20 61 20 62 75 67 20 69 6e 20 73 6f 6d 65  to a bug in some
d270: 20 65 61 72 6c 79 20 76 65 72 73 69 6f 6e 73 2c   early versions,
d280: 20 74 68 69 73 20 69 73 20 6e 6f 74 20 74 68 65   this is not the
d290: 0a 20 20 63 61 73 65 20 69 6e 20 53 51 4c 69 74  .  case in SQLit
d2a0: 65 2e 20 5e 55 6e 6c 65 73 73 20 74 68 65 20 63  e. ^Unless the c
d2b0: 6f 6c 75 6d 6e 20 69 73 20 61 6e 20 5b 49 4e 54  olumn is an [INT
d2c0: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
d2d0: 5d 20 6f 72 0a 20 20 74 68 65 20 74 61 62 6c 65  ] or.  the table
d2e0: 20 69 73 20 61 20 5b 57 49 54 48 4f 55 54 20 52   is a [WITHOUT R
d2f0: 4f 57 49 44 5d 20 74 61 62 6c 65 20 6f 72 20 74  OWID] table or t
d300: 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 64 65 63  he column is dec
d310: 6c 61 72 65 64 20 4e 4f 54 20 4e 55 4c 4c 2c 0a  lared NOT NULL,.
d320: 20 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20    SQLite allows 
d330: 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69 6e 20 61  NULL values in a
d340: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
d350: 75 6d 6e 2e 20 20 53 51 4c 69 74 65 20 63 6f 75  umn.  SQLite cou
d360: 6c 64 20 62 65 20 66 69 78 65 64 20 74 6f 0a 20  ld be fixed to. 
d370: 20 63 6f 6e 66 6f 72 6d 20 74 6f 20 74 68 65 20   conform to the 
d380: 73 74 61 6e 64 61 72 64 2c 20 62 75 74 20 64 6f  standard, but do
d390: 69 6e 67 20 73 6f 20 6d 69 67 68 74 20 62 72 65  ing so might bre
d3a0: 61 6b 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ak legacy applic
d3b0: 61 74 69 6f 6e 73 2e 0a 20 20 48 65 6e 63 65 2c  ations..  Hence,
d3c0: 20 69 74 20 68 61 73 20 62 65 65 6e 20 64 65 63   it has been dec
d3d0: 69 64 65 64 20 74 6f 20 6d 65 72 65 6c 79 20 64  ided to merely d
d3e0: 6f 63 75 6d 65 6e 74 20 74 68 65 20 66 61 63 74  ocument the fact
d3f0: 20 74 68 61 74 20 53 51 4c 69 74 65 0a 20 20 61   that SQLite.  a
d400: 6c 6c 6f 77 69 6e 67 20 4e 55 4c 4c 73 20 69 6e  llowing NULLs in
d410: 20 6d 6f 73 74 20 50 52 49 4d 41 52 59 20 4b 45   most PRIMARY KE
d420: 59 20 63 6f 6c 75 6d 6e 73 2e 0a 0a 3c 74 63 6c  Y columns...<tcl
d430: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 75 6e 69  >hd_fragment uni
d440: 71 75 65 63 6f 6e 73 74 20 7b 55 4e 49 51 55 45  queconst {UNIQUE
d450: 7d 20 7b 75 6e 69 71 75 65 20 63 6f 6e 73 74 72  } {unique constr
d460: 61 69 6e 74 7d 20 7b 55 4e 49 51 55 45 20 63 6f  aint} {UNIQUE co
d470: 6e 73 74 72 61 69 6e 74 7d 3c 2f 74 63 6c 3e 0a  nstraint}</tcl>.
d480: 3c 70 3e 5e 41 20 3c 62 3e 55 4e 49 51 55 45 3c  <p>^A <b>UNIQUE<
d490: 2f 62 3e 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  /b> constraint i
d4a0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 61 20 50  s similar to a P
d4b0: 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6e 73 74  RIMARY KEY const
d4c0: 72 61 69 6e 74 2c 20 65 78 63 65 70 74 0a 20 20  raint, except.  
d4d0: 74 68 61 74 20 61 20 73 69 6e 67 6c 65 20 74 61  that a single ta
d4e0: 62 6c 65 20 6d 61 79 20 68 61 76 65 20 61 6e 79  ble may have any
d4f0: 20 6e 75 6d 62 65 72 20 6f 66 20 55 4e 49 51 55   number of UNIQU
d500: 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 20 5e  E constraints. ^
d510: 46 6f 72 20 65 61 63 68 0a 20 20 55 4e 49 51 55  For each.  UNIQU
d520: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 6f 6e 20  E constraint on 
d530: 74 68 65 20 74 61 62 6c 65 2c 20 65 61 63 68 20  the table, each 
d540: 72 6f 77 20 6d 75 73 74 20 63 6f 6e 74 61 69 6e  row must contain
d550: 20 61 20 75 6e 69 71 75 65 20 63 6f 6d 62 69 6e   a unique combin
d560: 61 74 69 6f 6e 0a 20 20 6f 66 20 76 61 6c 75 65  ation.  of value
d570: 73 20 69 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s in the columns
d580: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
d590: 68 65 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72  he UNIQUE constr
d5a0: 61 69 6e 74 2e 20 0a 20 20 5e 46 6f 72 20 74 68  aint. .  ^For th
d5b0: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 55 4e  e purposes of UN
d5c0: 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  IQUE constraints
d5d0: 2c 20 4e 55 4c 4c 20 76 61 6c 75 65 73 0a 20 20  , NULL values.  
d5e0: 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 64  are considered d
d5f0: 69 73 74 69 6e 63 74 20 66 72 6f 6d 20 61 6c 6c  istinct from all
d600: 20 6f 74 68 65 72 20 76 61 6c 75 65 73 2c 20 69   other values, i
d610: 6e 63 6c 75 64 69 6e 67 20 6f 74 68 65 72 20 4e  ncluding other N
d620: 55 4c 4c 73 2e 0a 20 20 5e 41 73 20 77 69 74 68  ULLs..  ^As with
d630: 20 50 52 49 4d 41 52 59 20 4b 45 59 73 2c 20 61   PRIMARY KEYs, a
d640: 20 55 4e 49 51 55 45 20 5b 74 61 62 6c 65 2d 63   UNIQUE [table-c
d650: 6f 6e 73 74 72 61 69 6e 74 5d 20 63 6c 61 75 73  onstraint] claus
d660: 65 20 6d 75 73 74 20 63 6f 6e 74 61 69 6e 0a 20  e must contain. 
d670: 20 6f 6e 6c 79 20 63 6f 6c 75 6d 6e 20 6e 61 6d   only column nam
d680: 65 73 20 26 6d 64 61 73 68 3b 20 74 68 65 20 75  es &mdash; the u
d690: 73 65 20 6f 66 20 0a 20 20 65 78 70 72 65 73 73  se of .  express
d6a0: 69 6f 6e 73 20 69 6e 20 61 6e 20 5b 69 6e 64 65  ions in an [inde
d6b0: 78 65 64 2d 63 6f 6c 75 6d 6e 5d 20 6f 66 20 61  xed-column] of a
d6c0: 20 55 4e 49 51 55 45 20 5b 74 61 62 6c 65 2d 63   UNIQUE [table-c
d6d0: 6f 6e 73 74 72 61 69 6e 74 5d 0a 20 20 69 73 20  onstraint].  is 
d6e0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 2e 0a 20  not supported.. 
d6f0: 20 0a 0a 3c 70 3e 5e 49 6e 20 6d 6f 73 74 20 63   ..<p>^In most c
d700: 61 73 65 73 2c 20 55 4e 49 51 55 45 20 61 6e 64  ases, UNIQUE and
d710: 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 20 20 63   PRIMARY KEY.  c
d720: 6f 6e 73 74 72 61 69 6e 74 73 20 61 72 65 20 69  onstraints are i
d730: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 63 72  mplemented by cr
d740: 65 61 74 69 6e 67 20 61 20 75 6e 69 71 75 65 20  eating a unique 
d750: 69 6e 64 65 78 20 69 6e 20 74 68 65 20 64 61 74  index in the dat
d760: 61 62 61 73 65 2e 0a 20 20 28 54 68 65 20 65 78  abase..  (The ex
d770: 63 65 70 74 69 6f 6e 73 20 61 72 65 20 5b 49 4e  ceptions are [IN
d780: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
d790: 59 5d 20 61 6e 64 20 50 52 49 4d 41 52 59 20 4b  Y] and PRIMARY K
d7a0: 45 59 73 20 6f 6e 20 0a 20 20 5b 57 49 54 48 4f  EYs on .  [WITHO
d7b0: 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
d7c0: 2e 29 0a 20 20 48 65 6e 63 65 2c 20 74 68 65 20  .).  Hence, the 
d7d0: 66 6f 6c 6c 6f 77 69 6e 67 20 73 63 68 65 6d 61  following schema
d7e0: 73 20 61 72 65 20 6c 6f 67 69 63 61 6c 6c 79 20  s are logically 
d7f0: 65 71 75 69 76 61 6c 65 6e 74 3a 0a 0a 20 20 3c  equivalent:..  <
d800: 6f 6c 3e 0a 20 20 3c 6c 69 3e 3c 70 3e 43 52 45  ol>.  <li><p>CRE
d810: 41 54 45 20 54 41 42 4c 45 20 74 31 28 61 2c 20  ATE TABLE t1(a, 
d820: 62 20 55 4e 49 51 55 45 29 3b 0a 20 20 3c 6c 69  b UNIQUE);.  <li
d830: 3e 3c 70 3e 43 52 45 41 54 45 20 54 41 42 4c 45  ><p>CREATE TABLE
d840: 20 74 31 28 61 2c 20 62 20 50 52 49 4d 41 52 59   t1(a, b PRIMARY
d850: 20 4b 45 59 29 3b 0a 20 20 3c 6c 69 3e 3c 70 3e   KEY);.  <li><p>
d860: 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
d870: 61 2c 20 62 29 3b 3c 62 72 3e 0a 20 20 20 20 20  a, b);<br>.     
d880: 20 20 20 20 43 52 45 41 54 45 20 55 4e 49 51 55      CREATE UNIQU
d890: 45 20 49 4e 44 45 58 20 74 31 62 20 4f 4e 20 74  E INDEX t1b ON t
d8a0: 31 28 62 29 3b 0a 20 20 3c 2f 6f 6c 3e 0a 0a 3c  1(b);.  </ol>..<
d8b0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
d8c0: 7b 63 6b 63 6f 6e 73 74 7d 20 7b 43 48 45 43 4b  {ckconst} {CHECK
d8d0: 7d 20 7b 43 48 45 43 4b 20 63 6f 6e 73 74 72 61  } {CHECK constra
d8e0: 69 6e 74 7d 20 7b 43 48 45 43 4b 20 63 6f 6e 73  int} {CHECK cons
d8f0: 74 72 61 69 6e 74 73 7d 3c 2f 74 63 6c 3e 0a 3c  traints}</tcl>.<
d900: 70 3e 5e 28 41 20 3c 62 3e 43 48 45 43 4b 3c 2f  p>^(A <b>CHECK</
d910: 62 3e 20 63 6f 6e 73 74 72 61 69 6e 74 20 6d 61  b> constraint ma
d920: 79 20 62 65 20 61 74 74 61 63 68 65 64 20 74 6f  y be attached to
d930: 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69   a column defini
d940: 74 69 6f 6e 20 6f 72 0a 20 20 73 70 65 63 69 66  tion or.  specif
d950: 69 65 64 20 61 73 20 61 20 74 61 62 6c 65 20 63  ied as a table c
d960: 6f 6e 73 74 72 61 69 6e 74 2e 20 49 6e 20 70 72  onstraint. In pr
d970: 61 63 74 69 63 65 20 69 74 20 6d 61 6b 65 73 20  actice it makes 
d980: 6e 6f 20 64 69 66 66 65 72 65 6e 63 65 2e 29 5e  no difference.)^
d990: 20 5e 28 45 61 63 68 0a 20 20 74 69 6d 65 20 61   ^(Each.  time a
d9a0: 20 6e 65 77 20 72 6f 77 20 69 73 20 69 6e 73 65   new row is inse
d9b0: 72 74 65 64 20 69 6e 74 6f 20 74 68 65 20 74 61  rted into the ta
d9c0: 62 6c 65 20 6f 72 20 61 6e 20 65 78 69 73 74 69  ble or an existi
d9d0: 6e 67 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ng row is update
d9e0: 64 2c 0a 20 20 74 68 65 20 65 78 70 72 65 73 73  d,.  the express
d9f0: 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
da00: 69 74 68 20 65 61 63 68 20 43 48 45 43 4b 20 63  ith each CHECK c
da10: 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 65 76 61  onstraint is eva
da20: 6c 75 61 74 65 64 20 61 6e 64 0a 20 20 63 61 73  luated and.  cas
da30: 74 20 74 6f 20 61 20 4e 55 4d 45 52 49 43 20 76  t to a NUMERIC v
da40: 61 6c 75 65 20 69 6e 20 74 68 65 20 73 61 6d 65  alue in the same
da50: 20 77 61 79 20 61 73 20 61 20 5b 43 41 53 54 20   way as a [CAST 
da60: 65 78 70 72 65 73 73 69 6f 6e 5d 2e 20 49 66 20  expression]. If 
da70: 74 68 65 20 0a 20 20 72 65 73 75 6c 74 20 69 73  the .  result is
da80: 20 7a 65 72 6f 20 28 69 6e 74 65 67 65 72 20 76   zero (integer v
da90: 61 6c 75 65 20 30 20 6f 72 20 72 65 61 6c 20 76  alue 0 or real v
daa0: 61 6c 75 65 20 30 2e 30 29 2c 20 74 68 65 6e 20  alue 0.0), then 
dab0: 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 20 20 76  a constraint.  v
dac0: 69 6f 6c 61 74 69 6f 6e 20 68 61 73 20 6f 63 63  iolation has occ
dad0: 75 72 72 65 64 2e 29 5e 20 5e 49 66 20 74 68 65  urred.)^ ^If the
dae0: 20 43 48 45 43 4b 20 65 78 70 72 65 73 73 69 6f   CHECK expressio
daf0: 6e 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 4e  n evaluates to N
db00: 55 4c 4c 2c 20 6f 72 0a 20 20 61 6e 79 20 6f 74  ULL, or.  any ot
db10: 68 65 72 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c  her non-zero val
db20: 75 65 2c 20 69 74 20 69 73 20 6e 6f 74 20 61 20  ue, it is not a 
db30: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
db40: 74 69 6f 6e 2e 0a 20 20 5e 54 68 65 20 65 78 70  tion..  ^The exp
db50: 72 65 73 73 69 6f 6e 20 6f 66 20 61 20 43 48 45  ression of a CHE
db60: 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 20 6d 61  CK constraint ma
db70: 79 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20  y not contain a 
db80: 73 75 62 71 75 65 72 79 2e 0a 0a 3c 74 63 6c 3e  subquery...<tcl>
db90: 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b 6e 6f 74  hd_fragment {not
dba0: 6e 75 6c 6c 63 6f 6e 73 74 7d 20 7b 4e 4f 54 20  nullconst} {NOT 
dbb0: 4e 55 4c 4c 7d 20 7b 4e 4f 54 20 4e 55 4c 4c 20  NULL} {NOT NULL 
dbc0: 63 6f 6e 73 74 72 61 69 6e 74 7d 3c 2f 74 63 6c  constraint}</tcl
dbd0: 3e 0a 3c 70 3e 5e 41 20 3c 62 3e 4e 4f 54 20 4e  >.<p>^A <b>NOT N
dbe0: 55 4c 4c 3c 2f 62 3e 20 63 6f 6e 73 74 72 61 69  ULL</b> constrai
dbf0: 6e 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 61  nt may only be a
dc00: 74 74 61 63 68 65 64 20 74 6f 20 61 20 63 6f 6c  ttached to a col
dc10: 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 2c 0a  umn definition,.
dc20: 20 20 6e 6f 74 20 73 70 65 63 69 66 69 65 64 20    not specified 
dc30: 61 73 20 61 20 74 61 62 6c 65 20 63 6f 6e 73 74  as a table const
dc40: 72 61 69 6e 74 2e 20 20 4e 6f 74 20 73 75 72 70  raint.  Not surp
dc50: 72 69 73 69 6e 67 6c 79 2c 20 5e 28 61 20 4e 4f  risingly, ^(a NO
dc60: 54 20 4e 55 4c 4c 0a 20 20 63 6f 6e 73 74 72 61  T NULL.  constra
dc70: 69 6e 74 20 64 69 63 74 61 74 65 73 20 74 68 61  int dictates tha
dc80: 74 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  t the associated
dc90: 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 6e 6f 74 20   column may not 
dca0: 63 6f 6e 74 61 69 6e 20 61 20 4e 55 4c 4c 20 76  contain a NULL v
dcb0: 61 6c 75 65 2e 0a 20 20 41 74 74 65 6d 70 74 69  alue..  Attempti
dcc0: 6e 67 20 74 6f 20 73 65 74 20 74 68 65 20 63 6f  ng to set the co
dcd0: 6c 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 4e 55  lumn value to NU
dce0: 4c 4c 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  LL when insertin
dcf0: 67 20 61 20 6e 65 77 20 72 6f 77 20 6f 72 0a 20  g a new row or. 
dd00: 20 75 70 64 61 74 69 6e 67 20 61 6e 20 65 78 69   updating an exi
dd10: 73 74 69 6e 67 20 6f 6e 65 20 63 61 75 73 65 73  sting one causes
dd20: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
dd30: 6f 6c 61 74 69 6f 6e 2e 29 5e 0a 0a 3c 70 3e 45  olation.)^..<p>E
dd40: 78 61 63 74 6c 79 20 68 6f 77 20 61 20 63 6f 6e  xactly how a con
dd50: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
dd60: 6e 20 69 73 20 64 65 61 6c 74 20 77 69 74 68 20  n is dealt with 
dd70: 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  is determined by
dd80: 20 74 68 65 0a 20 20 5b 63 6f 6e 66 6c 69 63 74   the.  [conflict
dd90: 20 63 6c 61 75 73 65 7c 63 6f 6e 73 74 72 61 69   clause|constrai
dda0: 6e 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  nt conflict reso
ddb0: 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d  lution algorithm
ddc0: 5d 2e 20 45 61 63 68 20 0a 20 20 50 52 49 4d 41  ]. Each .  PRIMA
ddd0: 52 59 20 4b 45 59 2c 20 55 4e 49 51 55 45 2c 20  RY KEY, UNIQUE, 
dde0: 4e 4f 54 20 4e 55 4c 4c 20 61 6e 64 20 43 48 45  NOT NULL and CHE
ddf0: 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 20 68 61  CK constraint ha
de00: 73 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  s a default conf
de10: 6c 69 63 74 0a 20 20 72 65 73 6f 6c 75 74 69 6f  lict.  resolutio
de20: 6e 20 61 6c 67 6f 72 69 74 68 6d 2e 20 5e 50 52  n algorithm. ^PR
de30: 49 4d 41 52 59 20 4b 45 59 2c 20 55 4e 49 51 55  IMARY KEY, UNIQU
de40: 45 20 61 6e 64 20 4e 4f 54 20 4e 55 4c 4c 20 63  E and NOT NULL c
de50: 6f 6e 73 74 72 61 69 6e 74 73 20 6d 61 79 20 62  onstraints may b
de60: 65 0a 20 20 65 78 70 6c 69 63 69 74 6c 79 20 61  e.  explicitly a
de70: 73 73 69 67 6e 65 64 20 61 20 64 65 66 61 75 6c  ssigned a defaul
de80: 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  t conflict resol
de90: 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20  ution algorithm 
dea0: 62 79 20 69 6e 63 6c 75 64 69 6e 67 0a 20 20 61  by including.  a
deb0: 20 5b 63 6f 6e 66 6c 69 63 74 2d 63 6c 61 75 73   [conflict-claus
dec0: 65 5d 20 69 6e 20 74 68 65 69 72 20 64 65 66 69  e] in their defi
ded0: 6e 69 74 69 6f 6e 73 2e 20 5e 4f 72 2c 20 69 66  nitions. ^Or, if
dee0: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 64 65   a constraint de
def0: 66 69 6e 69 74 69 6f 6e 0a 20 20 64 6f 65 73 20  finition.  does 
df00: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 61 20 5b 63  not include a [c
df10: 6f 6e 66 6c 69 63 74 2d 63 6c 61 75 73 65 5d 20  onflict-clause] 
df20: 6f 72 20 69 74 20 69 73 20 61 20 43 48 45 43 4b  or it is a CHECK
df30: 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74 68 65   constraint, the
df40: 20 64 65 66 61 75 6c 74 0a 20 20 63 6f 6e 66 6c   default.  confl
df50: 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  ict resolution a
df60: 6c 67 6f 72 69 74 68 6d 20 69 73 20 41 42 4f 52  lgorithm is ABOR
df70: 54 2e 20 5e 44 69 66 66 65 72 65 6e 74 20 63 6f  T. ^Different co
df80: 6e 73 74 72 61 69 6e 74 73 20 77 69 74 68 69 6e  nstraints within
df90: 20 74 68 65 0a 20 20 73 61 6d 65 20 74 61 62 6c   the.  same tabl
dfa0: 65 20 6d 61 79 20 68 61 76 65 20 64 69 66 66 65  e may have diffe
dfb0: 72 65 6e 74 20 64 65 66 61 75 6c 74 20 63 6f 6e  rent default con
dfc0: 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
dfd0: 20 61 6c 67 6f 72 69 74 68 6d 73 2e 20 53 65 65   algorithms. See
dfe0: 0a 20 20 74 68 65 20 73 65 63 74 69 6f 6e 20 74  .  the section t
dff0: 69 74 6c 65 64 20 5b 4f 4e 20 43 4f 4e 46 4c 49  itled [ON CONFLI
e000: 43 54 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  CT] for addition
e010: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
e020: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
e030: 74 20 72 6f 77 69 64 20 7b 49 4e 54 45 47 45 52  t rowid {INTEGER
e040: 20 50 52 49 4d 41 52 59 20 4b 45 59 7d 20 52 4f   PRIMARY KEY} RO
e050: 57 49 44 20 72 6f 77 69 64 3c 2f 74 63 6c 3e 0a  WID rowid</tcl>.
e060: 3c 68 33 3e 52 4f 57 49 44 73 20 61 6e 64 20 74  <h3>ROWIDs and t
e070: 68 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  he INTEGER PRIMA
e080: 52 59 20 4b 45 59 3c 2f 68 33 3e 0a 0a 3c 70 3e  RY KEY</h3>..<p>
e090: 5e 45 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  ^Except for [WIT
e0a0: 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
e0b0: 65 73 2c 20 61 6c 6c 20 72 6f 77 73 20 77 69 74  es, all rows wit
e0c0: 68 69 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65  hin SQLite table
e0d0: 73 0a 68 61 76 65 20 61 20 36 34 2d 62 69 74 20  s.have a 64-bit 
e0e0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 6b  signed integer k
e0f0: 65 79 20 74 68 61 74 20 75 6e 69 71 75 65 6c 79  ey that uniquely
e100: 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
e110: 72 6f 77 20 77 69 74 68 69 6e 20 69 74 73 20 74  row within its t
e120: 61 62 6c 65 2e 0a 54 68 69 73 20 69 6e 74 65 67  able..This integ
e130: 65 72 20 69 73 20 75 73 75 61 6c 6c 79 0a 63 61  er is usually.ca
e140: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22  lled the "rowid"
e150: 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 76 61 6c  . ^The rowid val
e160: 75 65 20 63 61 6e 20 62 65 20 61 63 63 65 73 73  ue can be access
e170: 65 64 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  ed using one of 
e180: 74 68 65 20 73 70 65 63 69 61 6c 0a 63 61 73 65  the special.case
e190: 2d 69 6e 64 65 70 65 6e 64 65 6e 74 20 6e 61 6d  -independent nam
e1a0: 65 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  es "rowid", "oid
e1b0: 22 2c 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  ", or "_rowid_" 
e1c0: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 6f  in place of a co
e1d0: 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 5e 49 66 20 61  lumn name..^If a
e1e0: 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20   table contains 
e1f0: 61 20 75 73 65 72 20 64 65 66 69 6e 65 64 20 63  a user defined c
e200: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 22 72 6f 77  olumn named "row
e210: 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
e220: 72 6f 77 69 64 5f 22 2c 0a 74 68 65 6e 20 74 68  rowid_",.then th
e230: 61 74 20 6e 61 6d 65 20 61 6c 77 61 79 73 20 72  at name always r
e240: 65 66 65 72 73 20 74 68 65 20 65 78 70 6c 69 63  efers the explic
e250: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
e260: 6c 75 6d 6e 20 61 6e 64 20 63 61 6e 6e 6f 74 20  lumn and cannot 
e270: 62 65 20 75 73 65 64 0a 74 6f 20 72 65 74 72 69  be used.to retri
e280: 65 76 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  eve the integer 
e290: 72 6f 77 69 64 20 76 61 6c 75 65 2e 0a 0a 3c 70  rowid value...<p
e2a0: 3e 54 68 65 20 72 6f 77 69 64 20 28 61 6e 64 20  >The rowid (and 
e2b0: 22 6f 69 64 22 20 61 6e 64 20 22 5f 72 6f 77 69  "oid" and "_rowi
e2c0: 64 5f 22 29 20 69 73 20 6f 6d 69 74 74 65 64 20  d_") is omitted 
e2d0: 69 6e 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  in [WITHOUT ROWI
e2e0: 44 5d 20 74 61 62 6c 65 73 2e 0a 57 49 54 48 4f  D] tables..WITHO
e2f0: 55 54 20 52 4f 57 49 44 20 74 61 62 6c 65 73 20  UT ROWID tables 
e300: 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
e310: 6c 65 20 69 6e 20 53 51 4c 69 74 65 20 5b 76 65  le in SQLite [ve
e320: 72 73 69 6f 6e 20 33 2e 38 2e 32 5d 0a 28 5b 64  rsion 3.8.2].([d
e330: 61 74 65 6f 66 3a 33 2e 38 2e 32 5d 29 20 61 6e  ateof:3.8.2]) an
e340: 64 20 6c 61 74 65 72 2e 0a 41 20 74 61 62 6c 65  d later..A table
e350: 20 74 68 61 74 20 6c 61 63 6b 73 20 74 68 65 20   that lacks the 
e360: 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 63 6c  WITHOUT ROWID cl
e370: 61 75 73 65 20 69 73 20 63 61 6c 6c 65 64 20 61  ause is called a
e380: 20 22 72 6f 77 69 64 20 74 61 62 6c 65 22 2e 0a   "rowid table"..
e390: 0a 3c 70 3e 54 68 65 20 64 61 74 61 20 66 6f 72  .<p>The data for
e3a0: 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 69 73   rowid tables is
e3b0: 20 73 74 6f 72 65 64 20 61 73 20 61 20 42 2d 54   stored as a B-T
e3c0: 72 65 65 20 73 74 72 75 63 74 75 72 65 20 63 6f  ree structure co
e3d0: 6e 74 61 69 6e 69 6e 67 0a 6f 6e 65 20 65 6e 74  ntaining.one ent
e3e0: 72 79 20 66 6f 72 20 65 61 63 68 20 74 61 62 6c  ry for each tabl
e3f0: 65 20 72 6f 77 2c 20 75 73 69 6e 67 20 74 68 65  e row, using the
e400: 20 72 6f 77 69 64 20 76 61 6c 75 65 20 61 73 20   rowid value as 
e410: 74 68 65 20 6b 65 79 2e 20 54 68 69 73 20 6d 65  the key. This me
e420: 61 6e 73 20 74 68 61 74 0a 72 65 74 72 69 65 76  ans that.retriev
e430: 69 6e 67 20 6f 72 20 73 6f 72 74 69 6e 67 20 72  ing or sorting r
e440: 65 63 6f 72 64 73 20 62 79 20 72 6f 77 69 64 20  ecords by rowid 
e450: 69 73 20 66 61 73 74 2e 20 53 65 61 72 63 68 69  is fast. Searchi
e460: 6e 67 20 66 6f 72 20 61 20 72 65 63 6f 72 64 20  ng for a record 
e470: 77 69 74 68 20 61 0a 73 70 65 63 69 66 69 63 20  with a.specific 
e480: 72 6f 77 69 64 2c 20 6f 72 20 66 6f 72 20 61 6c  rowid, or for al
e490: 6c 20 72 65 63 6f 72 64 73 20 77 69 74 68 20 72  l records with r
e4a0: 6f 77 69 64 73 20 77 69 74 68 69 6e 20 61 20 73  owids within a s
e4b0: 70 65 63 69 66 69 65 64 20 72 61 6e 67 65 20 69  pecified range i
e4c0: 73 0a 61 72 6f 75 6e 64 20 74 77 69 63 65 20 61  s.around twice a
e4d0: 73 20 66 61 73 74 20 61 73 20 61 20 73 69 6d 69  s fast as a simi
e4e0: 6c 61 72 20 73 65 61 72 63 68 20 6d 61 64 65 20  lar search made 
e4f0: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  by specifying an
e500: 79 20 6f 74 68 65 72 20 50 52 49 4d 41 52 59 0a  y other PRIMARY.
e510: 4b 45 59 20 6f 72 20 69 6e 64 65 78 65 64 20 76  KEY or indexed v
e520: 61 6c 75 65 2e 0a 0a 3c 70 3e 20 5e 57 69 74 68  alue...<p> ^With
e530: 20 6f 6e 65 20 65 78 63 65 70 74 69 6f 6e 20 6e   one exception n
e540: 6f 74 65 64 20 62 65 6c 6f 77 2c 20 69 66 20 61  oted below, if a
e550: 20 72 6f 77 69 64 20 74 61 62 6c 65 20 68 61 73   rowid table has
e560: 20 61 20 70 72 69 6d 61 72 79 20 6b 65 79 20 74   a primary key t
e570: 68 61 74 20 63 6f 6e 73 69 73 74 73 0a 6f 66 20  hat consists.of 
e580: 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
e590: 61 6e 64 20 74 68 65 20 64 65 63 6c 61 72 65 64  and the declared
e5a0: 20 74 79 70 65 20 6f 66 20 74 68 61 74 20 63 6f   type of that co
e5b0: 6c 75 6d 6e 20 69 73 20 22 49 4e 54 45 47 45 52  lumn is "INTEGER
e5c0: 22 20 69 6e 20 61 6e 79 20 6d 69 78 74 75 72 65  " in any mixture
e5d0: 20 6f 66 0a 75 70 70 65 72 20 61 6e 64 20 6c 6f   of.upper and lo
e5e0: 77 65 72 20 63 61 73 65 2c 20 74 68 65 6e 20 74  wer case, then t
e5f0: 68 65 20 63 6f 6c 75 6d 6e 20 62 65 63 6f 6d 65  he column become
e600: 73 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74  s an alias for t
e610: 68 65 20 72 6f 77 69 64 2e 20 53 75 63 68 20 61  he rowid. Such a
e620: 0a 63 6f 6c 75 6d 6e 20 69 73 20 75 73 75 61 6c  .column is usual
e630: 6c 79 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  ly referred to a
e640: 73 20 61 6e 20 22 69 6e 74 65 67 65 72 20 70 72  s an "integer pr
e650: 69 6d 61 72 79 20 6b 65 79 22 2e 20 41 20 50 52  imary key". A PR
e660: 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e  IMARY KEY column
e670: 0a 6f 6e 6c 79 20 62 65 63 6f 6d 65 73 20 61 6e  .only becomes an
e680: 20 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79   integer primary
e690: 20 6b 65 79 20 69 66 20 74 68 65 20 64 65 63 6c   key if the decl
e6a0: 61 72 65 64 20 74 79 70 65 20 6e 61 6d 65 20 69  ared type name i
e6b0: 73 20 65 78 61 63 74 6c 79 0a 22 49 4e 54 45 47  s exactly."INTEG
e6c0: 45 52 22 2e 20 20 5e 4f 74 68 65 72 20 69 6e 74  ER".  ^Other int
e6d0: 65 67 65 72 20 74 79 70 65 20 6e 61 6d 65 73 20  eger type names 
e6e0: 6c 69 6b 65 20 22 49 4e 54 22 20 6f 72 20 22 42  like "INT" or "B
e6f0: 49 47 49 4e 54 22 20 6f 72 20 22 53 48 4f 52 54  IGINT" or "SHORT
e700: 20 49 4e 54 45 47 45 52 22 0a 6f 72 20 22 55 4e   INTEGER".or "UN
e710: 53 49 47 4e 45 44 20 49 4e 54 45 47 45 52 22 20  SIGNED INTEGER" 
e720: 63 61 75 73 65 73 20 74 68 65 20 70 72 69 6d 61  causes the prima
e730: 72 79 20 6b 65 79 20 63 6f 6c 75 6d 6e 20 74 6f  ry key column to
e740: 20 62 65 68 61 76 65 20 61 73 20 61 6e 20 6f 72   behave as an or
e750: 64 69 6e 61 72 79 0a 74 61 62 6c 65 20 63 6f 6c  dinary.table col
e760: 75 6d 6e 20 77 69 74 68 20 69 6e 74 65 67 65 72  umn with integer
e770: 20 5b 61 66 66 69 6e 69 74 79 5d 20 61 6e 64 20   [affinity] and 
e780: 61 20 75 6e 69 71 75 65 20 69 6e 64 65 78 2c 20  a unique index, 
e790: 6e 6f 74 20 61 73 20 61 6e 20 61 6c 69 61 73 20  not as an alias 
e7a0: 66 6f 72 0a 74 68 65 20 72 6f 77 69 64 2e 0a 0a  for.the rowid...
e7b0: 3c 70 3e 20 54 68 65 20 65 78 63 65 70 74 69 6f  <p> The exceptio
e7c0: 6e 20 6d 65 6e 74 69 6f 6e 65 64 20 61 62 6f 76  n mentioned abov
e7d0: 65 20 69 73 20 74 68 61 74 20 5e 69 66 20 74 68  e is that ^if th
e7e0: 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 6f 66  e declaration of
e7f0: 20 61 20 63 6f 6c 75 6d 6e 20 77 69 74 68 0a 64   a column with.d
e800: 65 63 6c 61 72 65 64 20 74 79 70 65 20 22 49 4e  eclared type "IN
e810: 54 45 47 45 52 22 20 69 6e 63 6c 75 64 65 73 20  TEGER" includes 
e820: 61 6e 20 22 50 52 49 4d 41 52 59 20 4b 45 59 20  an "PRIMARY KEY 
e830: 44 45 53 43 22 20 63 6c 61 75 73 65 2c 20 69 74  DESC" clause, it
e840: 20 64 6f 65 73 20 6e 6f 74 0a 62 65 63 6f 6d 65   does not.become
e850: 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68   an alias for th
e860: 65 20 72 6f 77 69 64 20 61 6e 64 20 69 73 20 6e  e rowid and is n
e870: 6f 74 20 63 6c 61 73 73 69 66 69 65 64 20 61 73  ot classified as
e880: 20 61 6e 20 69 6e 74 65 67 65 72 20 70 72 69 6d   an integer prim
e890: 61 72 79 20 6b 65 79 2e 0a 54 68 69 73 20 71 75  ary key..This qu
e8a0: 69 72 6b 20 69 73 20 6e 6f 74 20 62 79 20 64 65  irk is not by de
e8b0: 73 69 67 6e 2e 20 49 74 20 69 73 20 64 75 65 20  sign. It is due 
e8c0: 74 6f 20 61 20 62 75 67 20 69 6e 20 65 61 72 6c  to a bug in earl
e8d0: 79 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  y versions of SQ
e8e0: 4c 69 74 65 2e 0a 42 75 74 20 66 69 78 69 6e 67  Lite..But fixing
e8f0: 20 74 68 65 20 62 75 67 20 63 6f 75 6c 64 20 72   the bug could r
e900: 65 73 75 6c 74 20 69 6e 20 62 61 63 6b 77 61 72  esult in backwar
e910: 64 73 20 69 6e 63 6f 6d 70 61 74 69 62 69 6c 69  ds incompatibili
e920: 74 69 65 73 2e 0a 48 65 6e 63 65 2c 20 74 68 65  ties..Hence, the
e930: 20 6f 72 69 67 69 6e 61 6c 20 62 65 68 61 76 69   original behavi
e940: 6f 72 20 68 61 73 20 62 65 65 6e 20 72 65 74 61  or has been reta
e950: 69 6e 65 64 20 28 61 6e 64 20 64 6f 63 75 6d 65  ined (and docume
e960: 6e 74 65 64 29 20 62 65 63 61 75 73 65 20 6f 64  nted) because od
e970: 64 0a 62 65 68 61 76 69 6f 72 20 69 6e 20 61 20  d.behavior in a 
e980: 63 6f 72 6e 65 72 20 63 61 73 65 20 69 73 20 66  corner case is f
e990: 61 72 20 62 65 74 74 65 72 20 74 68 61 6e 20 61  ar better than a
e9a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
e9b0: 72 65 61 6b 2e 20 20 54 68 69 73 20 6d 65 61 6e  reak.  This mean
e9c0: 73 0a 74 68 61 74 20 5e 28 74 68 65 20 66 6f 6c  s.that ^(the fol
e9d0: 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 74 61 62  lowing three tab
e9e0: 6c 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 20  le declarations 
e9f0: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 6f  all cause the co
ea00: 6c 75 6d 6e 20 22 78 22 20 74 6f 20 62 65 20 61  lumn "x" to be a
ea10: 6e 0a 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  n.alias for the 
ea20: 72 6f 77 69 64 20 28 61 6e 20 69 6e 74 65 67 65  rowid (an intege
ea30: 72 20 70 72 69 6d 61 72 79 20 6b 65 79 29 3a 0a  r primary key):.
ea40: 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 74 74 3e 43 52  .<ul>.<li><tt>CR
ea50: 45 41 54 45 20 54 41 42 4c 45 20 74 28 78 20 49  EATE TABLE t(x I
ea60: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
ea70: 45 59 20 41 53 43 2c 20 79 2c 20 7a 29 3b 3c 2f  EY ASC, y, z);</
ea80: 74 74 3e 0a 3c 6c 69 3e 3c 74 74 3e 43 52 45 41  tt>.<li><tt>CREA
ea90: 54 45 20 54 41 42 4c 45 20 74 28 78 20 49 4e 54  TE TABLE t(x INT
eaa0: 45 47 45 52 2c 20 79 2c 20 7a 2c 20 50 52 49 4d  EGER, y, z, PRIM
eab0: 41 52 59 20 4b 45 59 28 78 20 41 53 43 29 29 3b  ARY KEY(x ASC));
eac0: 3c 2f 74 74 3e 0a 3c 6c 69 3e 3c 74 74 3e 43 52  </tt>.<li><tt>CR
ead0: 45 41 54 45 20 54 41 42 4c 45 20 74 28 78 20 49  EATE TABLE t(x I
eae0: 4e 54 45 47 45 52 2c 20 79 2c 20 7a 2c 20 50 52  NTEGER, y, z, PR
eaf0: 49 4d 41 52 59 20 4b 45 59 28 78 20 44 45 53 43  IMARY KEY(x DESC
eb00: 29 29 3b 3c 2f 74 74 3e 0a 3c 2f 75 6c 3e 29 5e  ));</tt>.</ul>)^
eb10: 0a 0a 3c 70 3e 42 75 74 20 5e 28 74 68 65 20 66  ..<p>But ^(the f
eb20: 6f 6c 6c 6f 77 69 6e 67 20 64 65 63 6c 61 72 61  ollowing declara
eb30: 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 72 65  tion does not re
eb40: 73 75 6c 74 20 69 6e 20 22 78 22 20 62 65 69 6e  sult in "x" bein
eb50: 67 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 0a 74  g an alias for.t
eb60: 68 65 20 72 6f 77 69 64 3a 0a 3c 75 6c 3e 0a 3c  he rowid:.<ul>.<
eb70: 6c 69 3e 3c 74 74 3e 43 52 45 41 54 45 20 54 41  li><tt>CREATE TA
eb80: 42 4c 45 20 74 28 78 20 49 4e 54 45 47 45 52 20  BLE t(x INTEGER 
eb90: 50 52 49 4d 41 52 59 20 4b 45 59 20 44 45 53 43  PRIMARY KEY DESC
eba0: 2c 20 79 2c 20 7a 29 3b 3c 2f 74 74 3e 0a 3c 2f  , y, z);</tt>.</
ebb0: 75 6c 3e 29 5e 0a 0a 3c 70 3e 5e 52 6f 77 69 64  ul>)^..<p>^Rowid
ebc0: 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 6d   values may be m
ebd0: 6f 64 69 66 69 65 64 20 75 73 69 6e 67 20 61 6e  odified using an
ebe0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
ebf0: 74 20 69 6e 20 74 68 65 20 73 61 6d 65 0a 77 61  t in the same.wa
ec00: 79 20 61 73 20 61 6e 79 20 6f 74 68 65 72 20 63  y as any other c
ec10: 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 63 61 6e 2c  olumn value can,
ec20: 20 65 69 74 68 65 72 20 75 73 69 6e 67 20 6f 6e   either using on
ec30: 65 20 6f 66 20 74 68 65 20 62 75 69 6c 74 2d 69  e of the built-i
ec40: 6e 20 61 6c 69 61 73 65 73 0a 28 22 72 6f 77 69  n aliases.("rowi
ec50: 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
ec60: 6f 77 69 64 5f 22 29 20 6f 72 20 62 79 20 75 73  owid_") or by us
ec70: 69 6e 67 20 61 6e 20 61 6c 69 61 73 20 63 72 65  ing an alias cre
ec80: 61 74 65 64 20 62 79 20 61 6e 20 69 6e 74 65 67  ated by an integ
ec90: 65 72 0a 70 72 69 6d 61 72 79 20 6b 65 79 2e 20  er.primary key. 
eca0: 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 61 6e 20 49  ^Similarly, an I
ecb0: 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20  NSERT statement 
ecc0: 6d 61 79 20 70 72 6f 76 69 64 65 20 61 20 76 61  may provide a va
ecd0: 6c 75 65 20 74 6f 20 75 73 65 20 61 73 20 74 68  lue to use as th
ece0: 65 0a 72 6f 77 69 64 20 66 6f 72 20 65 61 63 68  e.rowid for each
ecf0: 20 72 6f 77 20 69 6e 73 65 72 74 65 64 2e 20 5e   row inserted. ^
ed00: 28 55 6e 6c 69 6b 65 20 6e 6f 72 6d 61 6c 20 53  (Unlike normal S
ed10: 51 4c 69 74 65 20 63 6f 6c 75 6d 6e 73 2c 20 61  QLite columns, a
ed20: 6e 20 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72  n integer primar
ed30: 79 0a 6b 65 79 20 6f 72 20 72 6f 77 69 64 20 63  y.key or rowid c
ed40: 6f 6c 75 6d 6e 20 6d 75 73 74 20 63 6f 6e 74 61  olumn must conta
ed50: 69 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  in integer value
ed60: 73 2e 20 49 6e 74 65 67 65 72 20 70 72 69 6d 61  s. Integer prima
ed70: 72 79 20 6b 65 79 20 6f 72 20 72 6f 77 69 64 0a  ry key or rowid.
ed80: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20  columns are not 
ed90: 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 66 6c 6f  able to hold flo
eda0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
edb0: 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
edc0: 42 73 2c 20 6f 72 20 4e 55 4c 4c 73 2e 29 5e 0a  Bs, or NULLs.)^.
edd0: 0a 3c 70 3e 5e 49 66 20 61 6e 20 55 50 44 41 54  .<p>^If an UPDAT
ede0: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 74 74 65  E statement atte
edf0: 6d 70 74 73 20 74 6f 20 73 65 74 20 61 6e 20 69  mpts to set an i
ee00: 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79 20 6b  nteger primary k
ee10: 65 79 20 6f 72 20 72 6f 77 69 64 20 63 6f 6c 75  ey or rowid colu
ee20: 6d 6e 0a 74 6f 20 61 20 4e 55 4c 4c 20 6f 72 20  mn.to a NULL or 
ee30: 62 6c 6f 62 20 76 61 6c 75 65 2c 20 6f 72 20 74  blob value, or t
ee40: 6f 20 61 20 73 74 72 69 6e 67 20 6f 72 20 72 65  o a string or re
ee50: 61 6c 20 76 61 6c 75 65 20 74 68 61 74 20 63 61  al value that ca
ee60: 6e 6e 6f 74 20 62 65 20 6c 6f 73 73 6c 65 73 73  nnot be lossless
ee70: 6c 79 0a 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  ly.converted to 
ee80: 61 6e 20 69 6e 74 65 67 65 72 2c 20 61 20 22 64  an integer, a "d
ee90: 61 74 61 74 79 70 65 20 6d 69 73 6d 61 74 63 68  atatype mismatch
eea0: 22 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  " error occurs a
eeb0: 6e 64 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  nd the statement
eec0: 0a 69 73 20 61 62 6f 72 74 65 64 2e 20 5e 49 66  .is aborted. ^If
eed0: 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74 65   an INSERT state
eee0: 6d 65 6e 74 20 61 74 74 65 6d 70 74 73 20 74 6f  ment attempts to
eef0: 20 69 6e 73 65 72 74 20 61 20 62 6c 6f 62 20 76   insert a blob v
ef00: 61 6c 75 65 2c 20 6f 72 20 61 20 73 74 72 69 6e  alue, or a strin
ef10: 67 0a 6f 72 20 72 65 61 6c 20 76 61 6c 75 65 20  g.or real value 
ef20: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 6c  that cannot be l
ef30: 6f 73 73 6c 65 73 73 6c 79 20 63 6f 6e 76 65 72  osslessly conver
ef40: 74 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ted to an intege
ef50: 72 20 69 6e 74 6f 20 61 6e 0a 69 6e 74 65 67 65  r into an.intege
ef60: 72 20 70 72 69 6d 61 72 79 20 6b 65 79 20 6f 72  r primary key or
ef70: 20 72 6f 77 69 64 20 63 6f 6c 75 6d 6e 2c 20 61   rowid column, a
ef80: 20 22 64 61 74 61 74 79 70 65 20 6d 69 73 6d 61   "datatype misma
ef90: 74 63 68 22 20 65 72 72 6f 72 20 6f 63 63 75 72  tch" error occur
efa0: 73 20 61 6e 64 20 74 68 65 0a 73 74 61 74 65 6d  s and the.statem
efb0: 65 6e 74 20 69 73 20 61 62 6f 72 74 65 64 2e 0a  ent is aborted..
efc0: 0a 3c 70 3e 5e 49 66 20 61 6e 20 49 4e 53 45 52  .<p>^If an INSER
efd0: 54 20 73 74 61 74 65 6d 65 6e 74 20 61 74 74 65  T statement atte
efe0: 6d 70 74 73 20 74 6f 20 69 6e 73 65 72 74 20 61  mpts to insert a
eff0: 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 74 6f   NULL value into
f000: 20 61 20 72 6f 77 69 64 20 6f 72 0a 69 6e 74 65   a rowid or.inte
f010: 67 65 72 20 70 72 69 6d 61 72 79 20 6b 65 79 20  ger primary key 
f020: 63 6f 6c 75 6d 6e 2c 20 74 68 65 20 73 79 73 74  column, the syst
f030: 65 6d 20 63 68 6f 6f 73 65 73 20 61 6e 20 69 6e  em chooses an in
f040: 74 65 67 65 72 20 76 61 6c 75 65 20 74 6f 20 75  teger value to u
f050: 73 65 20 61 73 20 74 68 65 0a 72 6f 77 69 64 20  se as the.rowid 
f060: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 41  automatically. A
f070: 20 64 65 74 61 69 6c 65 64 20 64 65 73 63 72 69   detailed descri
f080: 70 74 69 6f 6e 20 6f 66 20 68 6f 77 20 74 68 69  ption of how thi
f090: 73 20 69 73 20 64 6f 6e 65 20 69 73 20 70 72 6f  s is done is pro
f0a0: 76 69 64 65 64 0a 3c 61 20 68 72 65 66 3d 22 61  vided.<a href="a
f0b0: 75 74 6f 69 6e 63 2e 68 74 6d 6c 22 3e 73 65 70  utoinc.html">sep
f0c0: 61 72 61 74 65 6c 79 3c 2f 61 3e 2e 3c 2f 70 3e  arately</a>.</p>
f0d0: 0a 0a 3c 70 3e 5e 28 54 68 65 20 5b 70 61 72 65  ..<p>^(The [pare
f0e0: 6e 74 20 6b 65 79 5d 20 6f 66 20 61 20 5b 66 6f  nt key] of a [fo
f0f0: 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
f100: 61 69 6e 74 5d 20 69 73 20 6e 6f 74 20 61 6c 6c  aint] is not all
f110: 6f 77 65 64 20 74 6f 0a 75 73 65 20 74 68 65 20  owed to.use the 
f120: 72 6f 77 69 64 2e 20 20 54 68 65 20 70 61 72 65  rowid.  The pare
f130: 6e 74 20 6b 65 79 20 6d 75 73 74 20 75 73 65 64  nt key must used
f140: 20 6e 61 6d 65 64 20 63 6f 6c 75 6d 6e 73 20 6f   named columns o
f150: 6e 6c 79 2e 29 5e 3c 2f 70 3e 0a 0a 3c 74 63 6c  nly.)^</p>..<tcl
f160: 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
f170: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f180: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f190: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f1a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f1b0: 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45 41 54 45  .Section {CREATE
f1c0: 20 54 52 49 47 47 45 52 7d 20 63 72 65 61 74 65   TRIGGER} create
f1d0: 74 72 69 67 67 65 72 20 7b 7b 43 52 45 41 54 45  trigger {{CREATE
f1e0: 20 54 52 49 47 47 45 52 7d 7d 0a 0a 52 65 63 75   TRIGGER}}..Recu
f1f0: 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72  rsiveBubbleDiagr
f200: 61 6d 20 63 72 65 61 74 65 2d 74 72 69 67 67 65  am create-trigge
f210: 72 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  r-stmt.</tcl>..<
f220: 70 3e 5e 54 68 65 20 43 52 45 41 54 45 20 54 52  p>^The CREATE TR
f230: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 20  IGGER statement 
f240: 69 73 20 75 73 65 64 20 74 6f 20 61 64 64 20 74  is used to add t
f250: 72 69 67 67 65 72 73 20 74 6f 20 74 68 65 20 0a  riggers to the .
f260: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 2e  database schema.
f270: 20 5e 54 72 69 67 67 65 72 73 20 61 72 65 20 64   ^Triggers are d
f280: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
f290: 6e 73 20 0a 74 68 61 74 20 61 72 65 20 61 75 74  ns .that are aut
f2a0: 6f 6d 61 74 69 63 61 6c 6c 79 20 70 65 72 66 6f  omatically perfo
f2b0: 72 6d 65 64 20 77 68 65 6e 20 61 20 73 70 65 63  rmed when a spec
f2c0: 69 66 69 65 64 20 64 61 74 61 62 61 73 65 20 65  ified database e
f2d0: 76 65 6e 74 0a 6f 63 63 75 72 73 2e 20 20 3c 2f  vent.occurs.  </
f2e0: 70 3e 0a 0a 3c 70 3e 5e 45 61 63 68 20 74 72 69  p>..<p>^Each tri
f2f0: 67 67 65 72 20 6d 75 73 74 20 73 70 65 63 69 66  gger must specif
f300: 79 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 66  y that it will f
f310: 69 72 65 20 66 6f 72 20 6f 6e 65 20 6f 66 0a 74  ire for one of.t
f320: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 65  he following ope
f330: 72 61 74 69 6f 6e 73 3a 20 5b 44 45 4c 45 54 45  rations: [DELETE
f340: 5d 2c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ], [INSERT], [UP
f350: 44 41 54 45 5d 2e 0a 54 68 65 20 74 72 69 67 67  DATE]..The trigg
f360: 65 72 20 66 69 72 65 73 20 6f 6e 63 65 20 66 6f  er fires once fo
f370: 72 20 65 61 63 68 20 72 6f 77 20 74 68 61 74 20  r each row that 
f380: 69 73 20 64 65 6c 65 74 65 64 2c 20 69 6e 73 65  is deleted, inse
f390: 72 74 65 64 2c 0a 6f 72 20 75 70 64 61 74 65 64  rted,.or updated
f3a0: 2e 20 20 49 66 20 74 68 65 20 22 55 50 44 41 54  .  If the "UPDAT
f3b0: 45 20 4f 46 20 3c 79 79 74 65 72 6d 3e 63 6f 6c  E OF <yyterm>col
f3c0: 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  umn-name</yyterm
f3d0: 3e 22 0a 73 79 6e 74 61 78 20 69 73 20 75 73 65  >".syntax is use
f3e0: 64 2c 20 74 68 65 6e 20 74 68 65 20 74 72 69 67  d, then the trig
f3f0: 67 65 72 20 77 69 6c 6c 20 6f 6e 6c 79 20 66 69  ger will only fi
f400: 72 65 20 69 66 0a 3c 79 79 74 65 72 6d 3e 63 6f  re if.<yyterm>co
f410: 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  lumn-name</yyter
f420: 6d 3e 20 61 70 70 65 61 72 73 20 6f 6e 20 74 68  m> appears on th
f430: 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
f440: 20 6f 66 0a 6f 6e 65 20 6f 66 20 74 68 65 20 74   of.one of the t
f450: 65 72 6d 73 20 69 6e 20 74 68 65 20 53 45 54 20  erms in the SET 
f460: 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20 5b 55  clause of the [U
f470: 50 44 41 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  PDATE] statement
f480: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 44 75 65 20 74 6f  .</p>..<p>Due to
f490: 20 61 6e 20 68 69 73 74 6f 72 69 63 61 6c 20 6f   an historical o
f4a0: 76 65 72 73 69 67 68 74 2c 20 63 6f 6c 75 6d 6e  versight, column
f4b0: 73 20 6e 61 6d 65 64 20 69 6e 20 74 68 65 20 22  s named in the "
f4c0: 55 50 44 41 54 45 20 4f 46 22 0a 63 6c 61 75 73  UPDATE OF".claus
f4d0: 65 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  e do not actuall
f4e0: 79 20 68 61 76 65 20 74 6f 20 65 78 69 73 74 20  y have to exist 
f4f0: 69 6e 20 74 68 65 20 74 61 62 6c 65 20 62 65 69  in the table bei
f500: 6e 67 20 75 70 64 61 74 65 64 2e 0a 55 6e 72 65  ng updated..Unre
f510: 63 6f 67 6e 69 7a 65 64 20 63 6f 6c 75 6d 6e 20  cognized column 
f520: 6e 61 6d 65 73 20 61 72 65 20 73 69 6c 65 6e 74  names are silent
f530: 6c 79 20 69 67 6e 6f 72 65 64 2e 0a 49 74 20 77  ly ignored..It w
f540: 6f 75 6c 64 20 62 65 20 6d 6f 72 65 20 68 65 6c  ould be more hel
f550: 70 66 75 6c 20 69 66 20 53 51 4c 69 74 65 20 77  pful if SQLite w
f560: 6f 75 6c 64 20 66 61 69 6c 20 74 68 65 20 43 52  ould fail the CR
f570: 45 41 54 45 20 54 52 49 47 47 45 52 0a 73 74 61  EATE TRIGGER.sta
f580: 74 65 6d 65 6e 74 20 69 66 20 61 6e 79 20 6f 66  tement if any of
f590: 20 74 68 65 20 6e 61 6d 65 73 20 69 6e 20 74 68   the names in th
f5a0: 65 20 22 55 50 44 41 54 45 20 4f 46 22 20 63 6c  e "UPDATE OF" cl
f5b0: 61 75 73 65 20 61 72 65 20 6e 6f 74 0a 63 6f 6c  ause are not.col
f5c0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c  umns in the tabl
f5d0: 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 61 73 20  e.  However, as 
f5e0: 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 77 61 73  this problem was
f5f0: 20 64 69 73 63 6f 76 65 72 65 64 0a 6d 61 6e 79   discovered.many
f600: 20 79 65 61 72 73 20 61 66 74 65 72 20 53 51 4c   years after SQL
f610: 69 74 65 20 77 61 73 20 77 69 64 65 6c 79 20 64  ite was widely d
f620: 65 70 6c 6f 79 65 64 2c 20 77 65 20 68 61 76 65  eployed, we have
f630: 20 72 65 73 69 73 74 65 64 0a 66 69 78 69 6e 67   resisted.fixing
f640: 20 74 68 65 20 70 72 6f 62 6c 65 6d 20 66 6f 72   the problem for
f650: 20 66 65 61 72 20 6f 66 20 62 72 65 61 6b 69 6e   fear of breakin
f660: 67 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  g legacy applica
f670: 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  tions.</p>..<p>^
f680: 41 74 20 74 68 69 73 20 74 69 6d 65 20 53 51 4c  At this time SQL
f690: 69 74 65 20 73 75 70 70 6f 72 74 73 20 6f 6e 6c  ite supports onl
f6a0: 79 20 46 4f 52 20 45 41 43 48 20 52 4f 57 20 74  y FOR EACH ROW t
f6b0: 72 69 67 67 65 72 73 2c 20 6e 6f 74 20 46 4f 52  riggers, not FOR
f6c0: 20 45 41 43 48 0a 53 54 41 54 45 4d 45 4e 54 20   EACH.STATEMENT 
f6d0: 74 72 69 67 67 65 72 73 2e 20 5e 48 65 6e 63 65  triggers. ^Hence
f6e0: 20 65 78 70 6c 69 63 69 74 6c 79 20 73 70 65 63   explicitly spec
f6f0: 69 66 79 69 6e 67 20 46 4f 52 20 45 41 43 48 20  ifying FOR EACH 
f700: 52 4f 57 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e  ROW is optional.
f710: 0a 5e 46 4f 52 20 45 41 43 48 20 52 4f 57 20 69  .^FOR EACH ROW i
f720: 6d 70 6c 69 65 73 20 74 68 61 74 20 74 68 65 20  mplies that the 
f730: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  SQL statements s
f740: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
f750: 74 72 69 67 67 65 72 0a 6d 61 79 20 62 65 20 65  trigger.may be e
f760: 78 65 63 75 74 65 64 20 28 64 65 70 65 6e 64 69  xecuted (dependi
f770: 6e 67 20 6f 6e 20 74 68 65 20 57 48 45 4e 20 63  ng on the WHEN c
f780: 6c 61 75 73 65 29 20 66 6f 72 20 65 61 63 68 20  lause) for each 
f790: 64 61 74 61 62 61 73 65 20 72 6f 77 20 62 65 69  database row bei
f7a0: 6e 67 0a 69 6e 73 65 72 74 65 64 2c 20 75 70 64  ng.inserted, upd
f7b0: 61 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  ated or deleted 
f7c0: 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
f7d0: 20 63 61 75 73 69 6e 67 20 74 68 65 20 74 72 69   causing the tri
f7e0: 67 67 65 72 20 74 6f 20 66 69 72 65 2e 3c 2f 70  gger to fire.</p
f7f0: 3e 0a 0a 3c 70 3e 5e 28 42 6f 74 68 20 74 68 65  >..<p>^(Both the
f800: 20 57 48 45 4e 20 63 6c 61 75 73 65 20 61 6e 64   WHEN clause and
f810: 20 74 68 65 20 74 72 69 67 67 65 72 20 61 63 74   the trigger act
f820: 69 6f 6e 73 20 6d 61 79 20 61 63 63 65 73 73 20  ions may access 
f830: 65 6c 65 6d 65 6e 74 73 20 6f 66 20 0a 74 68 65  elements of .the
f840: 20 72 6f 77 20 62 65 69 6e 67 20 69 6e 73 65 72   row being inser
f850: 74 65 64 2c 20 64 65 6c 65 74 65 64 20 6f 72 20  ted, deleted or 
f860: 75 70 64 61 74 65 64 20 75 73 69 6e 67 20 72 65  updated using re
f870: 66 65 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  ferences of the 
f880: 66 6f 72 6d 20 0a 22 4e 45 57 2e 3c 69 3e 63 6f  form ."NEW.<i>co
f890: 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 69 3e 22 20 61  lumn-name</i>" a
f8a0: 6e 64 20 22 4f 4c 44 2e 3c 69 3e 63 6f 6c 75 6d  nd "OLD.<i>colum
f8b0: 6e 2d 6e 61 6d 65 3c 2f 69 3e 22 2c 20 77 68 65  n-name</i>", whe
f8c0: 72 65 0a 3c 69 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d  re.<i>column-nam
f8d0: 65 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e 61 6d  e</i> is the nam
f8e0: 65 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20 66 72  e of a column fr
f8f0: 6f 6d 20 74 68 65 20 74 61 62 6c 65 20 74 68 61  om the table tha
f900: 74 20 74 68 65 20 74 72 69 67 67 65 72 0a 69 73  t the trigger.is
f910: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
f920: 2e 29 5e 20 5e 28 4f 4c 44 20 61 6e 64 20 4e 45  .)^ ^(OLD and NE
f930: 57 20 72 65 66 65 72 65 6e 63 65 73 20 6d 61 79  W references may
f940: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6e   only be used in
f950: 20 74 72 69 67 67 65 72 73 20 6f 6e 0a 65 76 65   triggers on.eve
f960: 6e 74 73 20 66 6f 72 20 77 68 69 63 68 20 74 68  nts for which th
f970: 65 79 20 61 72 65 20 72 65 6c 65 76 61 6e 74 2c  ey are relevant,
f980: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e   as follows:</p>
f990: 0a 0a 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  ..<table border=
f9a0: 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 31 30  0 cellpadding=10
f9b0: 3e 0a 3c 74 72 3e 0a 3c 74 64 20 76 61 6c 69 67  >.<tr>.<td valig
f9c0: 6e 3d 22 74 6f 70 22 20 61 6c 69 67 6e 3d 22 72  n="top" align="r
f9d0: 69 67 68 74 22 20 77 69 64 74 68 3d 31 32 30 3e  ight" width=120>
f9e0: 3c 69 3e 49 4e 53 45 52 54 3c 2f 69 3e 3c 2f 74  <i>INSERT</i></t
f9f0: 64 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74  d>.<td valign="t
fa00: 6f 70 22 3e 4e 45 57 20 72 65 66 65 72 65 6e 63  op">NEW referenc
fa10: 65 73 20 61 72 65 20 76 61 6c 69 64 3c 2f 74 64  es are valid</td
fa20: 3e 0a 3c 2f 74 72 3e 0a 3c 74 72 3e 0a 3c 74 64  >.</tr>.<tr>.<td
fa30: 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 20 61 6c   valign="top" al
fa40: 69 67 6e 3d 22 72 69 67 68 74 22 20 77 69 64 74  ign="right" widt
fa50: 68 3d 31 32 30 3e 3c 69 3e 55 50 44 41 54 45 3c  h=120><i>UPDATE<
fa60: 2f 69 3e 3c 2f 74 64 3e 0a 3c 74 64 20 76 61 6c  /i></td>.<td val
fa70: 69 67 6e 3d 22 74 6f 70 22 3e 4e 45 57 20 61 6e  ign="top">NEW an
fa80: 64 20 4f 4c 44 20 72 65 66 65 72 65 6e 63 65 73  d OLD references
fa90: 20 61 72 65 20 76 61 6c 69 64 3c 2f 74 64 3e 0a   are valid</td>.
faa0: 3c 2f 74 72 3e 0a 3c 74 72 3e 0a 3c 74 64 20 76  </tr>.<tr>.<td v
fab0: 61 6c 69 67 6e 3d 22 74 6f 70 22 20 61 6c 69 67  align="top" alig
fac0: 6e 3d 22 72 69 67 68 74 22 20 77 69 64 74 68 3d  n="right" width=
fad0: 31 32 30 3e 3c 69 3e 44 45 4c 45 54 45 3c 2f 69  120><i>DELETE</i
fae0: 3e 3c 2f 74 64 3e 0a 3c 74 64 20 76 61 6c 69 67  ></td>.<td valig
faf0: 6e 3d 22 74 6f 70 22 3e 4f 4c 44 20 72 65 66 65  n="top">OLD refe
fb00: 72 65 6e 63 65 73 20 61 72 65 20 76 61 6c 69 64  rences are valid
fb10: 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 2f 74 61  </td>.</tr>.</ta
fb20: 62 6c 65 3e 0a 3c 2f 70 3e 29 5e 0a 0a 3c 70 3e  ble>.</p>)^..<p>
fb30: 5e 49 66 20 61 20 57 48 45 4e 20 63 6c 61 75 73  ^If a WHEN claus
fb40: 65 20 69 73 20 73 75 70 70 6c 69 65 64 2c 20 74  e is supplied, t
fb50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
fb60: 73 20 73 70 65 63 69 66 69 65 64 0a 61 72 65 20  s specified.are 
fb70: 6f 6e 6c 79 20 65 78 65 63 75 74 65 64 20 69 66  only executed if
fb80: 20 74 68 65 20 57 48 45 4e 20 63 6c 61 75 73 65   the WHEN clause
fb90: 20 69 73 20 74 72 75 65 2e 0a 5e 49 66 20 6e 6f   is true..^If no
fba0: 20 57 48 45 4e 20 63 6c 61 75 73 65 20 69 73 20   WHEN clause is 
fbb0: 73 75 70 70 6c 69 65 64 2c 20 74 68 65 20 53 51  supplied, the SQ
fbc0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 61 72 65  L statements.are
fbd0: 20 65 78 65 63 75 74 65 64 20 65 76 65 72 79 20   executed every 
fbe0: 74 69 6d 65 20 74 68 65 20 74 72 69 67 67 65 72  time the trigger
fbf0: 20 66 69 72 65 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e   fires.</p>..<p>
fc00: 5e 54 68 65 20 42 45 46 4f 52 45 20 6f 72 20 41  ^The BEFORE or A
fc10: 46 54 45 52 20 6b 65 79 77 6f 72 64 20 64 65 74  FTER keyword det
fc20: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 74 68 65  ermines when the
fc30: 20 74 72 69 67 67 65 72 20 61 63 74 69 6f 6e 73   trigger actions
fc40: 0a 77 69 6c 6c 20 62 65 20 65 78 65 63 75 74 65  .will be execute
fc50: 64 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68  d relative to th
fc60: 65 20 69 6e 73 65 72 74 69 6f 6e 2c 20 6d 6f 64  e insertion, mod
fc70: 69 66 69 63 61 74 69 6f 6e 20 6f 72 20 72 65 6d  ification or rem
fc80: 6f 76 61 6c 20 6f 66 20 74 68 65 0a 61 73 73 6f  oval of the.asso
fc90: 63 69 61 74 65 64 20 72 6f 77 2e 3c 2f 70 3e 0a  ciated row.</p>.
fca0: 0a 3c 70 3e 5e 41 6e 20 5b 4f 4e 20 43 4f 4e 46  .<p>^An [ON CONF
fcb0: 4c 49 43 54 5d 20 63 6c 61 75 73 65 20 6d 61 79  LICT] clause may
fcc0: 20 62 65 20 73 70 65 63 69 66 69 65 64 20 61 73   be specified as
fcd0: 20 70 61 72 74 20 6f 66 20 61 6e 20 5b 55 50 44   part of an [UPD
fce0: 41 54 45 5d 20 6f 72 20 5b 49 4e 53 45 52 54 5d  ATE] or [INSERT]
fcf0: 0a 61 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74  .action within t
fd00: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 74  he body of the t
fd10: 72 69 67 67 65 72 2e 0a 5e 48 6f 77 65 76 65 72  rigger..^However
fd20: 20 69 66 20 61 6e 20 5b 4f 4e 20 43 4f 4e 46 4c   if an [ON CONFL
fd30: 49 43 54 5d 20 63 6c 61 75 73 65 20 69 73 20 73  ICT] clause is s
fd40: 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
fd50: 20 6f 66 20 0a 74 68 65 20 73 74 61 74 65 6d 65   of .the stateme
fd60: 6e 74 20 63 61 75 73 69 6e 67 20 74 68 65 20 74  nt causing the t
fd70: 72 69 67 67 65 72 20 74 6f 20 66 69 72 65 2c 20  rigger to fire, 
fd80: 74 68 65 6e 20 63 6f 6e 66 6c 69 63 74 20 68 61  then conflict ha
fd90: 6e 64 6c 69 6e 67 0a 70 6f 6c 69 63 79 20 6f 66  ndling.policy of
fda0: 20 74 68 65 20 6f 75 74 65 72 20 73 74 61 74 65   the outer state
fdb0: 6d 65 6e 74 20 69 73 20 75 73 65 64 20 69 6e 73  ment is used ins
fdc0: 74 65 61 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54  tead.</p>..<p>^T
fdd0: 72 69 67 67 65 72 73 20 61 72 65 20 61 75 74 6f  riggers are auto
fde0: 6d 61 74 69 63 61 6c 6c 79 20 5b 44 52 4f 50 20  matically [DROP 
fdf0: 54 52 49 47 47 45 52 20 7c 20 64 72 6f 70 70 65  TRIGGER | droppe
fe00: 64 5d 0a 77 68 65 6e 20 74 68 65 20 74 61 62 6c  d].when the tabl
fe10: 65 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  e that they are 
fe20: 0a 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68  .associated with
fe30: 20 28 74 68 65 20 3c 69 3e 74 61 62 6c 65 2d 6e   (the <i>table-n
fe40: 61 6d 65 3c 2f 69 3e 20 74 61 62 6c 65 29 20 69  ame</i> table) i
fe50: 73 20 0a 5b 44 52 4f 50 20 54 41 42 4c 45 20 7c  s .[DROP TABLE |
fe60: 20 64 72 6f 70 70 65 64 5d 2e 20 20 5e 48 6f 77   dropped].  ^How
fe70: 65 76 65 72 20 69 66 20 74 68 65 20 74 72 69 67  ever if the trig
fe80: 67 65 72 20 61 63 74 69 6f 6e 73 20 72 65 66 65  ger actions refe
fe90: 72 65 6e 63 65 0a 6f 74 68 65 72 20 74 61 62 6c  rence.other tabl
fea0: 65 73 2c 20 74 68 65 20 74 72 69 67 67 65 72 20  es, the trigger 
feb0: 69 73 20 6e 6f 74 20 64 72 6f 70 70 65 64 20 6f  is not dropped o
fec0: 72 20 6d 6f 64 69 66 69 65 64 20 69 66 20 74 68  r modified if th
fed0: 6f 73 65 20 6f 74 68 65 72 0a 74 61 62 6c 65 73  ose other.tables
fee0: 20 61 72 65 20 5b 44 52 4f 50 20 54 41 42 4c 45   are [DROP TABLE
fef0: 20 7c 20 64 72 6f 70 70 65 64 5d 20 6f 72 20 5b   | dropped] or [
ff00: 41 4c 54 45 52 20 54 41 42 4c 45 20 7c 20 6d 6f  ALTER TABLE | mo
ff10: 64 69 66 69 65 64 5d 2e 3c 2f 70 3e 0a 0a 3c 70  dified].</p>..<p
ff20: 3e 5e 54 72 69 67 67 65 72 73 20 61 72 65 20 72  >^Triggers are r
ff30: 65 6d 6f 76 65 64 20 75 73 69 6e 67 20 74 68 65  emoved using the
ff40: 20 5b 44 52 4f 50 20 54 52 49 47 47 45 52 5d 20   [DROP TRIGGER] 
ff50: 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a  statement.</p>..
ff60: 3c 68 33 3e 53 79 6e 74 61 78 20 52 65 73 74 72  <h3>Syntax Restr
ff70: 69 63 74 69 6f 6e 73 20 4f 6e 20 55 50 44 41 54  ictions On UPDAT
ff80: 45 2c 20 44 45 4c 45 54 45 2c 20 61 6e 64 20 49  E, DELETE, and I
ff90: 4e 53 45 52 54 20 53 74 61 74 65 6d 65 6e 74 73  NSERT Statements
ffa0: 20 57 69 74 68 69 6e 0a 20 20 20 20 54 72 69 67   Within.    Trig
ffb0: 67 65 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54  gers</h3>..<p>^T
ffc0: 68 65 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  he [UPDATE], [DE
ffd0: 4c 45 54 45 5d 2c 20 61 6e 64 20 5b 49 4e 53 45  LETE], and [INSE
ffe0: 52 54 5d 0a 73 74 61 74 65 6d 65 6e 74 73 20 77  RT].statements w
fff0: 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 20 64  ithin triggers d
10000 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 0a 74 68  o not support.th
10010 65 20 66 75 6c 6c 20 73 79 6e 74 61 78 20 66 6f  e full syntax fo
10020 72 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c  r [UPDATE], [DEL
10030 45 54 45 5d 2c 20 61 6e 64 20 5b 49 4e 53 45 52  ETE], and [INSER
10040 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  T] statements.  
10050 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 72 65  The following.re
10060 73 74 72 69 63 74 69 6f 6e 73 20 61 70 70 6c 79  strictions apply
10070 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  :</p>..<ul>.<li>
10080 3c 70 3e 0a 20 20 5e 28 54 68 65 20 6e 61 6d 65  <p>.  ^(The name
10090 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 74 6f   of the table to
100a0 20 62 65 20 6d 6f 64 69 66 69 65 64 20 69 6e 20   be modified in 
100b0 61 6e 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  an [UPDATE], [DE
100c0 4c 45 54 45 5d 2c 20 6f 72 20 5b 49 4e 53 45 52  LETE], or [INSER
100d0 54 5d 0a 20 20 73 74 61 74 65 6d 65 6e 74 20 6d  T].  statement m
100e0 75 73 74 20 62 65 20 61 6e 20 75 6e 71 75 61 6c  ust be an unqual
100f0 69 66 69 65 64 20 74 61 62 6c 65 20 6e 61 6d 65  ified table name
10100 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10110 73 2c 20 6f 6e 65 20 6d 75 73 74 0a 20 20 75 73  s, one must.  us
10120 65 20 6a 75 73 74 20 22 3c 69 3e 74 61 62 6c 65  e just "<i>table
10130 6e 61 6d 65 3c 2f 69 3e 22 20 6e 6f 74 20 22 3c  name</i>" not "<
10140 69 3e 64 61 74 61 62 61 73 65 3c 2f 69 3e 3c 62  i>database</i><b
10150 3e 2e 3c 2f 62 3e 3c 69 3e 74 61 62 6c 65 6e 61  >.</b><i>tablena
10160 6d 65 3c 2f 69 3e 22 0a 20 20 77 68 65 6e 20 73  me</i>".  when s
10170 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 74 61  pecifying the ta
10180 62 6c 65 2e 29 5e 20 3c 2f 70 3e 3c 2f 6c 69 3e  ble.)^ </p></li>
10190 0a 0a 3c 6c 69 3e 3c 70 3e 0a 20 5e 46 6f 72 20  ..<li><p>. ^For 
101a0 6e 6f 6e 2d 54 45 4d 50 20 74 72 69 67 67 65 72  non-TEMP trigger
101b0 73 2c 0a 20 20 74 68 65 20 74 61 62 6c 65 20 74  s,.  the table t
101c0 6f 20 62 65 20 6d 6f 64 69 66 69 65 64 20 6f 72  o be modified or
101d0 20 71 75 65 72 69 65 64 20 6d 75 73 74 20 65 78   queried must ex
101e0 69 73 74 20 69 6e 20 74 68 65 0a 20 20 73 61 6d  ist in the.  sam
101f0 65 20 64 61 74 61 62 61 73 65 20 61 73 20 74 68  e database as th
10200 65 20 74 61 62 6c 65 20 6f 72 20 76 69 65 77 20  e table or view 
10210 74 6f 20 77 68 69 63 68 20 74 68 65 20 74 72 69  to which the tri
10220 67 67 65 72 20 69 73 20 61 74 74 61 63 68 65 64  gger is attached
10230 2e 0a 20 20 5e 28 54 45 4d 50 20 74 72 69 67 67  ..  ^(TEMP trigg
10240 65 72 73 20 61 72 65 20 6e 6f 74 20 73 75 62 6a  ers are not subj
10250 65 63 74 20 74 6f 20 74 68 65 20 73 61 6d 65 2d  ect to the same-
10260 64 61 74 61 62 61 73 65 20 72 75 6c 65 2e 20 20  database rule.  
10270 41 20 54 45 4d 50 0a 20 20 74 72 69 67 67 65 72  A TEMP.  trigger
10280 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 71   is allowed to q
10290 75 65 72 79 20 6f 72 20 6d 6f 64 69 66 79 20 61  uery or modify a
102a0 6e 79 20 74 61 62 6c 65 20 69 6e 20 61 6e 79 20  ny table in any 
102b0 5b 41 54 54 41 43 48 5d 2d 65 64 20 64 61 74 61  [ATTACH]-ed data
102c0 62 61 73 65 2e 29 5e 0a 20 20 3c 2f 70 3e 3c 2f  base.)^.  </p></
102d0 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 5e  li>..<li><p>.  ^
102e0 54 68 65 20 22 49 4e 53 45 52 54 20 49 4e 54 4f  The "INSERT INTO
102f0 20 3c 69 3e 74 61 62 6c 65 3c 2f 69 3e 20 44 45   <i>table</i> DE
10300 46 41 55 4c 54 20 56 41 4c 55 45 53 22 20 66 6f  FAULT VALUES" fo
10310 72 6d 20 6f 66 20 74 68 65 20 5b 49 4e 53 45 52  rm of the [INSER
10320 54 5d 20 73 74 61 74 65 6d 65 6e 74 0a 20 20 69  T] statement.  i
10330 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 2e  s not supported.
10340 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c  .  </p></li>..<l
10350 69 3e 3c 70 3e 0a 20 20 5e 54 68 65 20 49 4e 44  i><p>.  ^The IND
10360 45 58 45 44 20 42 59 20 61 6e 64 20 4e 4f 54 20  EXED BY and NOT 
10370 49 4e 44 45 58 45 44 20 63 6c 61 75 73 65 73 20  INDEXED clauses 
10380 61 72 65 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  are not supporte
10390 64 20 66 6f 72 20 5b 55 50 44 41 54 45 5d 20 61  d for [UPDATE] a
103a0 6e 64 0a 20 20 5b 44 45 4c 45 54 45 5d 20 73 74  nd.  [DELETE] st
103b0 61 74 65 6d 65 6e 74 73 2e 0a 20 20 3c 2f 70 3e  atements..  </p>
103c0 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 20  </li>..<li><p>. 
103d0 20 5e 28 54 68 65 20 4f 52 44 45 52 20 42 59 20   ^(The ORDER BY 
103e0 61 6e 64 20 4c 49 4d 49 54 20 63 6c 61 75 73 65  and LIMIT clause
103f0 73 20 6f 6e 20 5b 55 50 44 41 54 45 5d 20 61 6e  s on [UPDATE] an
10400 64 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  d [DELETE] state
10410 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 20 20  ments are not.  
10420 73 75 70 70 6f 72 74 65 64 2e 20 20 4f 52 44 45  supported.  ORDE
10430 52 20 42 59 20 61 6e 64 20 4c 49 4d 49 54 20 61  R BY and LIMIT a
10440 72 65 20 6e 6f 74 20 6e 6f 72 6d 61 6c 6c 79 20  re not normally 
10450 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 5b 55  supported for [U
10460 50 44 41 54 45 5d 20 6f 72 0a 20 20 5b 44 45 4c  PDATE] or.  [DEL
10470 45 54 45 5d 20 69 6e 20 61 6e 79 20 63 6f 6e 74  ETE] in any cont
10480 65 78 74 20 62 75 74 20 63 61 6e 20 62 65 20 65  ext but can be e
10490 6e 61 62 6c 65 64 20 66 6f 72 20 74 6f 70 2d 6c  nabled for top-l
104a0 65 76 65 6c 20 73 74 61 74 65 6d 65 6e 74 73 0a  evel statements.
104b0 20 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c    using the [SQL
104c0 49 54 45 5f 45 4e 41 42 4c 45 5f 55 50 44 41 54  ITE_ENABLE_UPDAT
104d0 45 5f 44 45 4c 45 54 45 5f 4c 49 4d 49 54 5d 20  E_DELETE_LIMIT] 
104e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
104f0 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c 0a 20  ion.  However,. 
10500 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
10510 6d 65 20 6f 70 74 69 6f 6e 20 6f 6e 6c 79 20 61  me option only a
10520 70 70 6c 69 65 73 20 74 6f 20 74 6f 70 2d 6c 65  pplies to top-le
10530 76 65 6c 20 5b 55 50 44 41 54 45 5d 20 61 6e 64  vel [UPDATE] and
10540 20 5b 44 45 4c 45 54 45 5d 0a 20 20 73 74 61 74   [DELETE].  stat
10550 65 6d 65 6e 74 73 2c 20 6e 6f 74 20 5b 55 50 44  ements, not [UPD
10560 41 54 45 5d 20 61 6e 64 20 5b 44 45 4c 45 54 45  ATE] and [DELETE
10570 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74  ] statements wit
10580 68 69 6e 20 74 72 69 67 67 65 72 73 2e 29 5e 0a  hin triggers.)^.
10590 20 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69    </p></li>..<li
105a0 3e 3c 70 3e 0a 20 20 5e 5b 63 6f 6d 6d 6f 6e 2d  ><p>.  ^[common-
105b0 74 61 62 6c 65 2d 65 78 70 72 65 73 73 69 6f 6e  table-expression
105c0 7c 43 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78  |Common table ex
105d0 70 72 65 73 73 69 6f 6e 5d 20 61 72 65 20 6e 6f  pression] are no
105e0 74 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 0a  t supported for.
105f0 20 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 73    statements ins
10600 69 64 65 20 6f 66 20 74 72 69 67 67 65 72 73 2e  ide of triggers.
10610 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75  .  </p></li>.</u
10620 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  l>..<tcl>hd_frag
10630 6d 65 6e 74 20 69 6e 73 74 65 61 64 5f 6f 66 5f  ment instead_of_
10640 74 72 69 67 67 65 72 20 7b 49 4e 53 54 45 41 44  trigger {INSTEAD
10650 20 4f 46 7d 20 7b 49 4e 53 54 45 41 44 20 4f 46   OF} {INSTEAD OF
10660 20 74 72 69 67 67 65 72 7d 3c 2f 74 63 6c 3e 0a   trigger}</tcl>.
10670 3c 68 33 3e 49 4e 53 54 45 41 44 20 4f 46 20 74  <h3>INSTEAD OF t
10680 72 69 67 67 65 72 73 3c 2f 68 33 3e 0a 0a 3c 70  riggers</h3>..<p
10690 3e 5e 54 72 69 67 67 65 72 73 20 6d 61 79 20 62  >^Triggers may b
106a0 65 20 63 72 65 61 74 65 64 20 6f 6e 20 5b 76 69  e created on [vi
106b0 65 77 73 5d 2c 20 61 73 20 77 65 6c 6c 20 61 73  ews], as well as
106c0 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
106d0 2c 20 62 79 0a 73 70 65 63 69 66 79 69 6e 67 20  , by.specifying 
106e0 49 4e 53 54 45 41 44 20 4f 46 20 69 6e 20 74 68  INSTEAD OF in th
106f0 65 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  e CREATE TRIGGER
10700 20 73 74 61 74 65 6d 65 6e 74 2e 20 0a 5e 49 66   statement. .^If
10710 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 4f 4e 20   one or more ON 
10720 49 4e 53 45 52 54 2c 20 4f 4e 20 44 45 4c 45 54  INSERT, ON DELET
10730 45 0a 6f 72 20 4f 4e 20 55 50 44 41 54 45 20 74  E.or ON UPDATE t
10740 72 69 67 67 65 72 73 20 61 72 65 20 64 65 66 69  riggers are defi
10750 6e 65 64 20 6f 6e 20 61 20 76 69 65 77 2c 20 74  ned on a view, t
10760 68 65 6e 20 69 74 20 69 73 20 6e 6f 74 20 61 6e  hen it is not an
10770 0a 65 72 72 6f 72 20 74 6f 20 65 78 65 63 75 74  .error to execut
10780 65 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  e an INSERT, DEL
10790 45 54 45 20 6f 72 20 55 50 44 41 54 45 20 73 74  ETE or UPDATE st
107a0 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 76  atement on the v
107b0 69 65 77 2c 20 0a 72 65 73 70 65 63 74 69 76 65  iew, .respective
107c0 6c 79 2e 20 20 5e 49 6e 73 74 65 61 64 2c 0a 65  ly.  ^Instead,.e
107d0 78 65 63 75 74 69 6e 67 20 61 6e 20 49 4e 53 45  xecuting an INSE
107e0 52 54 2c 20 44 45 4c 45 54 45 20 6f 72 20 55 50  RT, DELETE or UP
107f0 44 41 54 45 20 6f 6e 20 74 68 65 20 76 69 65 77  DATE on the view
10800 20 63 61 75 73 65 73 20 74 68 65 20 61 73 73 6f   causes the asso
10810 63 69 61 74 65 64 0a 74 72 69 67 67 65 72 73 20  ciated.triggers 
10820 74 6f 20 66 69 72 65 2e 20 5e 54 68 65 20 72 65  to fire. ^The re
10830 61 6c 20 74 61 62 6c 65 73 20 75 6e 64 65 72 6c  al tables underl
10840 79 69 6e 67 20 74 68 65 20 76 69 65 77 20 61 72  ying the view ar
10850 65 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 0a 28  e not modified.(
10860 65 78 63 65 70 74 20 70 6f 73 73 69 62 6c 79 20  except possibly 
10870 65 78 70 6c 69 63 69 74 6c 79 2c 20 62 79 20 61  explicitly, by a
10880 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
10890 29 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 4e 6f 74 65  ).</p>..<p>^Note
108a0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
108b0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 61 6e  e3_changes()] an
108c0 64 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  d [sqlite3_total
108d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
108e0 72 66 61 63 65 73 0a 64 6f 20 6e 6f 74 20 63 6f  rfaces.do not co
108f0 75 6e 74 20 49 4e 53 54 45 41 44 20 4f 46 20 74  unt INSTEAD OF t
10900 72 69 67 67 65 72 20 66 69 72 69 6e 67 73 2c 20  rigger firings, 
10910 62 75 74 20 74 68 65 0a 5b 63 6f 75 6e 74 5f 63  but the.[count_c
10920 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 20 64  hanges pragma] d
10930 6f 65 73 20 63 6f 75 6e 74 20 49 4e 53 54 45 41  oes count INSTEA
10940 44 20 4f 46 20 74 72 69 67 67 65 72 20 66 69 72  D OF trigger fir
10950 69 6e 67 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 53 6f  ing.</p>..<h3>So
10960 6d 65 20 45 78 61 6d 70 6c 65 20 54 72 69 67 67  me Example Trigg
10970 65 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 41  ers</h3>..<p>^(A
10980 73 73 75 6d 69 6e 67 20 74 68 61 74 20 63 75 73  ssuming that cus
10990 74 6f 6d 65 72 20 72 65 63 6f 72 64 73 20 61 72  tomer records ar
109a0 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  e stored in the 
109b0 22 63 75 73 74 6f 6d 65 72 73 22 20 74 61 62 6c  "customers" tabl
109c0 65 2c 20 61 6e 64 0a 74 68 61 74 20 6f 72 64 65  e, and.that orde
109d0 72 20 72 65 63 6f 72 64 73 20 61 72 65 20 73 74  r records are st
109e0 6f 72 65 64 20 69 6e 20 74 68 65 20 22 6f 72 64  ored in the "ord
109f0 65 72 73 22 20 74 61 62 6c 65 2c 20 74 68 65 20  ers" table, the 
10a00 66 6f 6c 6c 6f 77 69 6e 67 0a 55 50 44 41 54 45  following.UPDATE
10a10 20 74 72 69 67 67 65 72 0a 65 6e 73 75 72 65 73   trigger.ensures
10a20 20 74 68 61 74 20 61 6c 6c 20 61 73 73 6f 63 69   that all associ
10a30 61 74 65 64 20 6f 72 64 65 72 73 20 61 72 65 20  ated orders are 
10a40 72 65 64 69 72 65 63 74 65 64 20 77 68 65 6e 20  redirected when 
10a50 61 20 63 75 73 74 6f 6d 65 72 20 63 68 61 6e 67  a customer chang
10a60 65 73 0a 68 69 73 20 6f 72 20 68 65 72 20 61 64  es.his or her ad
10a70 64 72 65 73 73 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c  dress:</p>..<tcl
10a80 3e 45 78 61 6d 70 6c 65 20 7b 0a 43 52 45 41 54  >Example {.CREAT
10a90 45 20 54 52 49 47 47 45 52 20 75 70 64 61 74 65  E TRIGGER update
10aa0 5f 63 75 73 74 6f 6d 65 72 5f 61 64 64 72 65 73  _customer_addres
10ab0 73 20 55 50 44 41 54 45 20 4f 46 20 61 64 64 72  s UPDATE OF addr
10ac0 65 73 73 20 4f 4e 20 63 75 73 74 6f 6d 65 72 73  ess ON customers
10ad0 20 0a 20 20 42 45 47 49 4e 0a 20 20 20 20 55 50   .  BEGIN.    UP
10ae0 44 41 54 45 20 6f 72 64 65 72 73 20 53 45 54 20  DATE orders SET 
10af0 61 64 64 72 65 73 73 20 3d 20 6e 65 77 2e 61 64  address = new.ad
10b00 64 72 65 73 73 20 57 48 45 52 45 20 63 75 73 74  dress WHERE cust
10b10 6f 6d 65 72 5f 6e 61 6d 65 20 3d 20 6f 6c 64 2e  omer_name = old.
10b20 6e 61 6d 65 3b 0a 20 20 45 4e 44 3b 0a 7d 3c 2f  name;.  END;.}</
10b30 74 63 6c 3e 0a 0a 3c 70 3e 57 69 74 68 20 74 68  tcl>..<p>With th
10b40 69 73 20 74 72 69 67 67 65 72 20 69 6e 73 74 61  is trigger insta
10b50 6c 6c 65 64 2c 20 65 78 65 63 75 74 69 6e 67 20  lled, executing 
10b60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 3a 3c 2f  the statement:</
10b70 70 3e 0a 0a 3c 74 63 6c 3e 45 78 61 6d 70 6c 65  p>..<tcl>Example
10b80 20 7b 0a 55 50 44 41 54 45 20 63 75 73 74 6f 6d   {.UPDATE custom
10b90 65 72 73 20 53 45 54 20 61 64 64 72 65 73 73 20  ers SET address 
10ba0 3d 20 27 31 20 4d 61 69 6e 20 53 74 2e 27 20 57  = '1 Main St.' W
10bb0 48 45 52 45 20 6e 61 6d 65 20 3d 20 27 4a 61 63  HERE name = 'Jac
10bc0 6b 20 4a 6f 6e 65 73 27 3b 0a 7d 3c 2f 74 63 6c  k Jones';.}</tcl
10bd0 3e 0a 0a 3c 70 3e 63 61 75 73 65 73 20 74 68 65  >..<p>causes the
10be0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 6f 20 62 65   following to be
10bf0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 65   automatically e
10c00 78 65 63 75 74 65 64 3a 3c 2f 70 3e 0a 0a 3c 74  xecuted:</p>..<t
10c10 63 6c 3e 45 78 61 6d 70 6c 65 20 7b 0a 55 50 44  cl>Example {.UPD
10c20 41 54 45 20 6f 72 64 65 72 73 20 53 45 54 20 61  ATE orders SET a
10c30 64 64 72 65 73 73 20 3d 20 27 31 20 4d 61 69 6e  ddress = '1 Main
10c40 20 53 74 2e 27 20 57 48 45 52 45 20 63 75 73 74   St.' WHERE cust
10c50 6f 6d 65 72 5f 6e 61 6d 65 20 3d 20 27 4a 61 63  omer_name = 'Jac
10c60 6b 20 4a 6f 6e 65 73 27 3b 0a 7d 3c 2f 74 63 6c  k Jones';.}</tcl
10c70 3e 29 5e 0a 0a 3c 70 3e 46 6f 72 20 61 6e 20 65  >)^..<p>For an e
10c80 78 61 6d 70 6c 65 20 6f 66 20 61 6e 20 49 4e 53  xample of an INS
10c90 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 2c  TEAD OF trigger,
10ca0 20 63 6f 6e 73 69 64 65 72 20 74 68 65 20 66 6f   consider the fo
10cb0 6c 6c 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a 0a  llowing schema:.
10cc0 0a 3c 74 63 6c 3e 45 78 61 6d 70 6c 65 20 7b 0a  .<tcl>Example {.
10cd0 43 52 45 41 54 45 20 54 41 42 4c 45 20 63 75 73  CREATE TABLE cus
10ce0 74 6f 6d 65 72 28 0a 20 20 63 75 73 74 5f 69 64  tomer(.  cust_id
10cf0 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
10d00 20 4b 45 59 2c 0a 20 20 63 75 73 74 5f 6e 61 6d   KEY,.  cust_nam
10d10 65 20 54 45 58 54 2c 0a 20 20 63 75 73 74 5f 61  e TEXT,.  cust_a
10d20 64 64 72 20 54 45 58 54 0a 29 3b 0a 43 52 45 41  ddr TEXT.);.CREA
10d30 54 45 20 56 49 45 57 20 63 75 73 74 6f 6d 65 72  TE VIEW customer
10d40 5f 61 64 64 72 65 73 73 20 41 53 0a 20 20 20 53  _address AS.   S
10d50 45 4c 45 43 54 20 63 75 73 74 5f 69 64 2c 20 63  ELECT cust_id, c
10d60 75 73 74 5f 61 64 64 72 20 46 52 4f 4d 20 63 75  ust_addr FROM cu
10d70 73 74 6f 6d 65 72 3b 0a 43 52 45 41 54 45 20 54  stomer;.CREATE T
10d80 52 49 47 47 45 52 20 63 75 73 74 5f 61 64 64 72  RIGGER cust_addr
10d90 5f 63 68 6e 67 0a 49 4e 53 54 45 41 44 20 4f 46  _chng.INSTEAD OF
10da0 20 55 50 44 41 54 45 20 4f 46 20 63 75 73 74 5f   UPDATE OF cust_
10db0 61 64 64 72 20 4f 4e 20 63 75 73 74 6f 6d 65 72  addr ON customer
10dc0 5f 61 64 64 72 65 73 73 0a 42 45 47 49 4e 0a 20  _address.BEGIN. 
10dd0 20 55 50 44 41 54 45 20 63 75 73 74 6f 6d 65 72   UPDATE customer
10de0 20 53 45 54 20 63 75 73 74 5f 61 64 64 72 3d 4e   SET cust_addr=N
10df0 45 57 2e 63 75 73 74 5f 61 64 64 72 0a 20 20 20  EW.cust_addr.   
10e00 57 48 45 52 45 20 63 75 73 74 5f 69 64 3d 4e 45  WHERE cust_id=NE
10e10 57 2e 63 75 73 74 5f 69 64 3b 0a 45 4e 44 3b 0a  W.cust_id;.END;.
10e20 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 57 69 74 68  }</tcl>..<p>With
10e30 20 74 68 65 20 73 63 68 65 6d 61 20 61 62 6f 76   the schema abov
10e40 65 2c 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  e, a statement o
10e50 66 20 74 68 65 20 66 6f 72 6d 3a 3c 2f 70 3e 0a  f the form:</p>.
10e60 0a 3c 74 63 6c 3e 45 78 61 6d 70 6c 65 20 7b 0a  .<tcl>Example {.
10e70 55 50 44 41 54 45 20 63 75 73 74 6f 6d 65 72 5f  UPDATE customer_
10e80 61 64 64 72 65 73 73 20 53 45 54 20 63 75 73 74  address SET cust
10e90 5f 61 64 64 72 3d 24 6e 65 77 5f 61 64 64 72 65  _addr=$new_addre
10ea0 73 73 20 57 48 45 52 45 20 63 75 73 74 5f 69 64  ss WHERE cust_id
10eb0 3d 24 63 75 73 74 5f 69 64 3b 0a 7d 3c 2f 74 63  =$cust_id;.}</tc
10ec0 6c 3e 0a 0a 3c 70 3e 43 61 75 73 65 73 20 74 68  l>..<p>Causes th
10ed0 65 20 63 75 73 74 6f 6d 65 72 2e 63 75 73 74 5f  e customer.cust_
10ee0 61 64 64 72 20 66 69 65 6c 64 20 74 6f 20 62 65  addr field to be
10ef0 20 75 70 64 61 74 65 64 20 66 6f 72 20 61 20 73   updated for a s
10f00 70 65 63 69 66 69 63 0a 63 75 73 74 6f 6d 65 72  pecific.customer
10f10 20 65 6e 74 72 79 20 74 68 61 74 20 68 61 73 20   entry that has 
10f20 63 75 73 74 6f 6d 65 72 2e 63 75 73 74 5f 69 64  customer.cust_id
10f30 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 24 63   equal to the $c
10f40 75 73 74 5f 69 64 20 70 61 72 61 6d 65 74 65 72  ust_id parameter
10f50 2e 0a 4e 6f 74 65 20 68 6f 77 20 74 68 65 20 76  ..Note how the v
10f60 61 6c 75 65 73 20 61 73 73 69 67 6e 65 64 20 74  alues assigned t
10f70 6f 20 74 68 65 20 76 69 65 77 20 61 72 65 20 6d  o the view are m
10f80 61 64 65 20 61 76 61 69 6c 61 62 6c 65 20 61 73  ade available as
10f90 20 66 69 65 6c 64 0a 69 6e 20 74 68 65 20 73 70   field.in the sp
10fa0 65 63 69 61 6c 20 22 4e 45 57 22 20 74 61 62 6c  ecial "NEW" tabl
10fb0 65 20 77 69 74 68 69 6e 20 74 68 65 20 74 72 69  e within the tri
10fc0 67 67 65 72 20 62 6f 64 79 2e 3c 2f 70 3e 0a 0a  gger body.</p>..
10fd0 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
10fe0 20 75 6e 64 65 66 5f 62 65 66 6f 72 65 20 7b 75   undef_before {u
10ff0 6e 64 65 66 69 6e 65 64 20 42 45 46 4f 52 45 20  ndefined BEFORE 
11000 74 72 69 67 67 65 72 20 62 65 68 61 76 69 6f 72  trigger behavior
11010 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 43 61 75 74  }</tcl>.<h3>Caut
11020 69 6f 6e 73 20 4f 6e 20 54 68 65 20 55 73 65 20  ions On The Use 
11030 4f 66 20 42 45 46 4f 52 45 20 74 72 69 67 67 65  Of BEFORE trigge
11040 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 49 66 20 61  rs</h3>..<p>If a
11050 20 42 45 46 4f 52 45 20 55 50 44 41 54 45 20 6f   BEFORE UPDATE o
11060 72 20 42 45 46 4f 52 45 20 44 45 4c 45 54 45 20  r BEFORE DELETE 
11070 74 72 69 67 67 65 72 20 6d 6f 64 69 66 69 65 73  trigger modifies
11080 20 6f 72 20 64 65 6c 65 74 65 73 20 61 20 72 6f   or deletes a ro
11090 77 0a 74 68 61 74 20 77 61 73 20 74 6f 20 68 61  w.that was to ha
110a0 76 65 20 62 65 65 6e 20 75 70 64 61 74 65 64 20  ve been updated 
110b0 6f 72 20 64 65 6c 65 74 65 64 2c 20 74 68 65 6e  or deleted, then
110c0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
110d0 68 65 20 73 75 62 73 65 71 75 65 6e 74 0a 75 70  he subsequent.up
110e0 64 61 74 65 20 6f 72 20 64 65 6c 65 74 65 20 6f  date or delete o
110f0 70 65 72 61 74 69 6f 6e 20 69 73 20 75 6e 64 65  peration is unde
11100 66 69 6e 65 64 2e 20 20 46 75 72 74 68 65 72 6d  fined.  Furtherm
11110 6f 72 65 2c 20 69 66 20 61 20 42 45 46 4f 52 45  ore, if a BEFORE
11120 20 74 72 69 67 67 65 72 0a 6d 6f 64 69 66 69 65   trigger.modifie
11130 73 20 6f 72 20 64 65 6c 65 74 65 73 20 61 20 72  s or deletes a r
11140 6f 77 2c 20 74 68 65 6e 20 69 74 20 69 73 20 75  ow, then it is u
11150 6e 64 65 66 69 6e 65 64 20 77 68 65 74 68 65 72  ndefined whether
11160 20 6f 72 20 6e 6f 74 20 41 46 54 45 52 20 74 72   or not AFTER tr
11170 69 67 67 65 72 73 0a 74 68 61 74 20 77 6f 75 6c  iggers.that woul
11180 64 20 68 61 76 65 20 6f 74 68 65 72 77 69 73 65  d have otherwise
11190 20 72 75 6e 20 6f 6e 20 74 68 6f 73 65 20 72 6f   run on those ro
111a0 77 73 20 77 69 6c 6c 20 69 6e 20 66 61 63 74 20  ws will in fact 
111b0 72 75 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  run..</p>..<p>Th
111c0 65 20 76 61 6c 75 65 20 6f 66 20 4e 45 57 2e 72  e value of NEW.r
111d0 6f 77 69 64 20 69 73 20 75 6e 64 65 66 69 6e 65  owid is undefine
111e0 64 20 69 6e 20 61 20 42 45 46 4f 52 45 20 49 4e  d in a BEFORE IN
111f0 53 45 52 54 20 74 72 69 67 67 65 72 20 69 6e 20  SERT trigger in 
11200 77 68 69 63 68 0a 74 68 65 20 72 6f 77 69 64 20  which.the rowid 
11210 69 73 20 6e 6f 74 20 65 78 70 6c 69 63 69 74 6c  is not explicitl
11220 79 20 73 65 74 20 74 6f 20 61 6e 20 69 6e 74 65  y set to an inte
11230 67 65 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 63  ger.</p>..<p>Bec
11240 61 75 73 65 20 6f 66 20 74 68 65 20 62 65 68 61  ause of the beha
11250 76 69 6f 72 73 20 64 65 73 63 72 69 62 65 64 20  viors described 
11260 61 62 6f 76 65 2c 20 70 72 6f 67 72 61 6d 6d 65  above, programme
11270 72 73 20 61 72 65 20 65 6e 63 6f 75 72 61 67 65  rs are encourage
11280 64 20 74 6f 0a 70 72 65 66 65 72 20 41 46 54 45  d to.prefer AFTE
11290 52 20 74 72 69 67 67 65 72 73 20 6f 76 65 72 20  R triggers over 
112a0 42 45 46 4f 52 45 20 74 72 69 67 67 65 72 73 2e  BEFORE triggers.
112b0 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
112c0 61 67 6d 65 6e 74 20 72 61 69 73 65 20 7b 52 41  agment raise {RA
112d0 49 53 45 20 66 75 6e 63 74 69 6f 6e 7d 3c 2f 74  ISE function}</t
112e0 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 52 41 49 53  cl>.<h3>The RAIS
112f0 45 28 29 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 33  E() function</h3
11300 3e 0a 0a 3c 70 3e 5e 28 41 20 73 70 65 63 69 61  >..<p>^(A specia
11310 6c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 52  l SQL function R
11320 41 49 53 45 28 29 20 6d 61 79 20 62 65 20 75 73  AISE() may be us
11330 65 64 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  ed within a trig
11340 67 65 72 2d 70 72 6f 67 72 61 6d 2c 29 5e 0a 77  ger-program,)^.w
11350 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ith the followin
11360 67 20 73 79 6e 74 61 78 3c 2f 70 3e 20 0a 0a 3c  g syntax</p> ..<
11370 74 63 6c 3e 42 75 62 62 6c 65 44 69 61 67 72 61  tcl>BubbleDiagra
11380 6d 20 72 61 69 73 65 2d 66 75 6e 63 74 69 6f 6e  m raise-function
11390 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 28 57 68 65  </tcl>..<p>^(Whe
113a0 6e 20 6f 6e 65 20 6f 66 20 52 41 49 53 45 28 52  n one of RAISE(R
113b0 4f 4c 4c 42 41 43 4b 2c 2e 2e 2e 29 2c 20 52 41  OLLBACK,...), RA
113c0 49 53 45 28 41 42 4f 52 54 2c 2e 2e 2e 29 20 6f  ISE(ABORT,...) o
113d0 72 20 52 41 49 53 45 28 46 41 49 4c 2c 2e 2e 2e  r RAISE(FAIL,...
113e0 29 0a 69 73 20 63 61 6c 6c 65 64 20 64 75 72 69  ).is called duri
113f0 6e 67 20 74 72 69 67 67 65 72 2d 70 72 6f 67 72  ng trigger-progr
11400 61 6d 0a 65 78 65 63 75 74 69 6f 6e 2c 20 74 68  am.execution, th
11410 65 20 73 70 65 63 69 66 69 65 64 20 5b 4f 4e 20  e specified [ON 
11420 43 4f 4e 46 4c 49 43 54 5d 20 70 72 6f 63 65 73  CONFLICT] proces
11430 73 69 6e 67 20 69 73 20 70 65 72 66 6f 72 6d 65  sing is performe
11440 64 0a 74 68 65 20 63 75 72 72 65 6e 74 20 71 75  d.the current qu
11450 65 72 79 20 74 65 72 6d 69 6e 61 74 65 73 2e 29  ery terminates.)
11460 5e 0a 41 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  ^.An error code 
11470 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 53 54  of [SQLITE_CONST
11480 52 41 49 4e 54 5d 20 69 73 20 72 65 74 75 72 6e  RAINT] is return
11490 65 64 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ed to the applic
114a0 61 74 69 6f 6e 2c 0a 61 6c 6f 6e 67 20 77 69 74  ation,.along wit
114b0 68 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  h the specified 
114c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 3c 2f  error message.</
114d0 70 3e 0a 0a 3c 70 3e 5e 57 68 65 6e 20 52 41 49  p>..<p>^When RAI
114e0 53 45 28 49 47 4e 4f 52 45 29 20 69 73 20 63 61  SE(IGNORE) is ca
114f0 6c 6c 65 64 2c 20 74 68 65 20 72 65 6d 61 69 6e  lled, the remain
11500 64 65 72 20 6f 66 20 74 68 65 20 63 75 72 72 65  der of the curre
11510 6e 74 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  nt trigger progr
11520 61 6d 2c 0a 74 68 65 20 73 74 61 74 65 6d 65 6e  am,.the statemen
11530 74 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  t that caused th
11540 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
11550 6d 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64  m to execute and
11560 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 0a   any subsequent.
11570 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
11580 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
11590 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 20 61   been executed a
115a0 72 65 20 61 62 61 6e 64 6f 6e 65 64 2e 20 5e 4e  re abandoned. ^N
115b0 6f 20 64 61 74 61 62 61 73 65 0a 63 68 61 6e 67  o database.chang
115c0 65 73 20 61 72 65 20 72 6f 6c 6c 65 64 20 62 61  es are rolled ba
115d0 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ck.  ^If the sta
115e0 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 75 73  tement that caus
115f0 65 64 20 74 68 65 20 74 72 69 67 67 65 72 20 70  ed the trigger p
11600 72 6f 67 72 61 6d 0a 74 6f 20 65 78 65 63 75 74  rogram.to execut
11610 65 20 69 73 20 69 74 73 65 6c 66 20 70 61 72 74  e is itself part
11620 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 70 72   of a trigger pr
11630 6f 67 72 61 6d 2c 20 74 68 65 6e 20 74 68 61 74  ogram, then that
11640 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
11650 0a 72 65 73 75 6d 65 73 20 65 78 65 63 75 74 69  .resumes executi
11660 6f 6e 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  on at the beginn
11670 69 6e 67 20 6f 66 20 74 68 65 20 6e 65 78 74 20  ing of the next 
11680 73 74 65 70 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c  step..</p>..<tcl
11690 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 74 65 6d  >hd_fragment tem
116a0 70 74 72 69 67 20 7b 54 45 4d 50 20 74 72 69 67  ptrig {TEMP trig
116b0 67 65 72 73 20 6f 6e 20 6e 6f 6e 2d 54 45 4d 50  gers on non-TEMP
116c0 20 74 61 62 6c 65 73 7d 3c 2f 74 63 6c 3e 0a 3c   tables}</tcl>.<
116d0 68 33 3e 54 45 4d 50 20 54 72 69 67 67 65 72 73  h3>TEMP Triggers
116e0 20 6f 6e 20 4e 6f 6e 2d 54 45 4d 50 20 54 61 62   on Non-TEMP Tab
116f0 6c 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 41  les</h3>..<p>^(A
11700 20 74 72 69 67 67 65 72 20 6e 6f 72 6d 61 6c 6c   trigger normall
11710 79 20 65 78 69 73 74 73 20 69 6e 20 74 68 65 20  y exists in the 
11720 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 73  same database as
11730 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 64   the table named
11740 0a 61 66 74 65 72 20 74 68 65 20 22 4f 4e 22 20  .after the "ON" 
11750 6b 65 79 77 6f 72 64 20 69 6e 20 74 68 65 20 43  keyword in the C
11760 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
11770 61 74 65 6d 65 6e 74 2e 20 20 45 78 63 65 70 74  atement.  Except
11780 2c 20 69 74 20 69 73 0a 70 6f 73 73 69 62 6c 65  , it is.possible
11790 20 74 6f 20 63 72 65 61 74 65 20 61 20 54 45 4d   to create a TEM
117a0 50 20 54 52 49 47 47 45 52 20 6f 6e 20 61 20 74  P TRIGGER on a t
117b0 61 62 6c 65 20 69 6e 20 61 6e 6f 74 68 65 72 20  able in another 
117c0 64 61 74 61 62 61 73 65 2e 29 5e 20 20 0a 53 75  database.)^  .Su
117d0 63 68 20 61 20 74 72 69 67 67 65 72 20 77 69 6c  ch a trigger wil
117e0 6c 20 6f 6e 6c 79 20 66 69 72 65 20 77 68 65 6e  l only fire when
117f0 20 63 68 61 6e 67 65 73 0a 61 72 65 20 6d 61 64   changes.are mad
11800 65 20 74 6f 20 74 68 65 20 74 61 72 67 65 74 20  e to the target 
11810 74 61 62 6c 65 20 62 79 20 74 68 65 20 61 70 70  table by the app
11820 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 64 65  lication that de
11830 66 69 6e 65 64 20 74 68 65 20 74 72 69 67 67 65  fined the trigge
11840 72 2e 0a 4f 74 68 65 72 20 61 70 70 6c 69 63 61  r..Other applica
11850 74 69 6f 6e 73 20 74 68 61 74 20 6d 6f 64 69 66  tions that modif
11860 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  y the database w
11870 69 6c 6c 20 6e 6f 74 20 62 65 20 61 62 6c 65 20  ill not be able 
11880 74 6f 20 73 65 65 20 74 68 65 0a 54 45 4d 50 20  to see the.TEMP 
11890 74 72 69 67 67 65 72 20 61 6e 64 20 68 65 6e 63  trigger and henc
118a0 65 20 63 61 6e 6e 6f 74 20 72 75 6e 20 74 68 65  e cannot run the
118b0 20 74 72 69 67 67 65 72 2e 3c 2f 70 3e 0a 0a 3c   trigger.</p>..<
118c0 70 3e 57 68 65 6e 20 64 65 66 69 6e 69 6e 67 20  p>When defining 
118d0 61 20 54 45 4d 50 20 74 72 69 67 67 65 72 20 6f  a TEMP trigger o
118e0 6e 20 61 20 6e 6f 6e 2d 54 45 4d 50 20 74 61 62  n a non-TEMP tab
118f0 6c 65 2c 20 69 74 20 69 73 20 69 6d 70 6f 72 74  le, it is import
11900 61 6e 74 20 74 6f 0a 73 70 65 63 69 66 79 20 74  ant to.specify t
11910 68 65 20 64 61 74 61 62 61 73 65 20 68 6f 6c 64  he database hold
11920 69 6e 67 20 74 68 65 20 6e 6f 6e 2d 54 45 4d 50  ing the non-TEMP
11930 20 74 61 62 6c 65 2e 20 20 46 6f 72 20 65 78 61   table.  For exa
11940 6d 70 6c 65 2c 0a 69 6e 20 74 68 65 20 66 6f 6c  mple,.in the fol
11950 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
11960 2c 20 69 74 20 69 73 20 69 6d 70 6f 72 74 61 6e  , it is importan
11970 74 20 74 6f 20 73 61 79 20 22 6d 61 69 6e 2e 74  t to say "main.t
11980 61 62 31 22 20 69 6e 73 74 65 61 64 0a 6f 66 20  ab1" instead.of 
11990 6a 75 73 74 20 22 74 61 62 31 22 3a 3c 2f 70 3e  just "tab1":</p>
119a0 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
119b0 72 65 3e 0a 43 52 45 41 54 45 20 54 45 4d 50 20  re>.CREATE TEMP 
119c0 54 52 49 47 47 45 52 20 65 78 31 20 41 46 54 45  TRIGGER ex1 AFTE
119d0 52 20 49 4e 53 45 52 54 20 4f 4e 20 3c 62 3e 6d  R INSERT ON <b>m
119e0 61 69 6e 2e 3c 2f 62 3e 74 61 62 31 20 42 45 47  ain.</b>tab1 BEG
119f0 49 4e 20 2e 2e 2e 0a 3c 2f 70 72 65 3e 3c 2f 62  IN ....</pre></b
11a00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 46  lockquote>..<p>F
11a10 61 69 6c 75 72 65 20 74 6f 20 73 70 65 63 69 66  ailure to specif
11a20 79 20 74 68 65 20 73 63 68 65 6d 61 20 6e 61 6d  y the schema nam
11a30 65 20 6f 6e 20 74 68 65 20 74 61 72 67 65 74 20  e on the target 
11a40 74 61 62 6c 65 20 63 6f 75 6c 64 20 72 65 73 75  table could resu
11a50 6c 74 0a 69 6e 20 74 68 65 20 54 45 4d 50 20 74  lt.in the TEMP t
11a60 72 69 67 67 65 72 20 62 65 69 6e 67 20 72 65 61  rigger being rea
11a70 74 74 61 63 68 65 64 20 74 6f 20 61 20 74 61 62  ttached to a tab
11a80 6c 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  le with the same
11a90 20 6e 61 6d 65 20 69 6e 0a 61 6e 6f 74 68 65 72   name in.another
11aa0 20 64 61 74 61 62 61 73 65 20 77 68 65 6e 65 76   database whenev
11ab0 65 72 20 61 6e 79 20 73 63 68 65 6d 61 20 63 68  er any schema ch
11ac0 61 6e 67 65 20 6f 63 63 75 72 73 2e 3c 2f 70 3e  ange occurs.</p>
11ad0 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
11ae0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11af0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11b00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11b10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11b20 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
11b30 7b 43 52 45 41 54 45 20 56 49 45 57 7d 20 7b 63  {CREATE VIEW} {c
11b40 72 65 61 74 65 76 69 65 77 7d 20 7b 7b 43 52 45  reateview} {{CRE
11b50 41 54 45 20 56 49 45 57 7d 20 76 69 65 77 20 56  ATE VIEW} view V
11b60 49 45 57 20 2a 76 69 65 77 73 7d 0a 0a 52 65 63  IEW *views}..Rec
11b70 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
11b80 72 61 6d 20 63 72 65 61 74 65 2d 76 69 65 77 2d  ram create-view-
11b90 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e  stmt.</tcl>..<p>
11ba0 5e 54 68 65 20 43 52 45 41 54 45 20 56 49 45 57  ^The CREATE VIEW
11bb0 20 63 6f 6d 6d 61 6e 64 20 61 73 73 69 67 6e 73   command assigns
11bc0 20 61 20 6e 61 6d 65 20 74 6f 20 61 20 70 72 65   a name to a pre
11bd0 2d 70 61 63 6b 61 67 65 64 20 0a 5b 53 45 4c 45  -packaged .[SELE
11be0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 0a  CT] statement. .
11bf0 5e 4f 6e 63 65 20 74 68 65 20 76 69 65 77 20 69  ^Once the view i
11c00 73 20 63 72 65 61 74 65 64 2c 20 69 74 20 63 61  s created, it ca
11c10 6e 20 62 65 20 75 73 65 64 20 69 6e 20 74 68 65  n be used in the
11c20 20 46 52 4f 4d 20 63 6c 61 75 73 65 0a 6f 66 20   FROM clause.of 
11c30 61 6e 6f 74 68 65 72 20 5b 53 45 4c 45 43 54 5d  another [SELECT]
11c40 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 74   in place of a t
11c50 61 62 6c 65 20 6e 61 6d 65 2e 0a 3c 2f 70 3e 0a  able name..</p>.
11c60 0a 3c 70 3e 5e 49 66 20 74 68 65 20 22 54 45 4d  .<p>^If the "TEM
11c70 50 22 20 6f 72 20 22 54 45 4d 50 4f 52 41 52 59  P" or "TEMPORARY
11c80 22 20 6b 65 79 77 6f 72 64 20 6f 63 63 75 72 73  " keyword occurs
11c90 20 69 6e 20 62 65 74 77 65 65 6e 20 22 43 52 45   in between "CRE
11ca0 41 54 45 22 0a 61 6e 64 20 22 56 49 45 57 22 20  ATE".and "VIEW" 
11cb0 74 68 65 6e 20 74 68 65 20 76 69 65 77 20 74 68  then the view th
11cc0 61 74 20 69 73 20 63 72 65 61 74 65 64 20 69 73  at is created is
11cd0 20 6f 6e 6c 79 20 76 69 73 69 62 6c 65 20 74 6f   only visible to
11ce0 20 74 68 65 0a 5b 64 61 74 61 62 61 73 65 20 63   the.[database c
11cf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
11d00 63 72 65 61 74 65 64 20 69 74 20 61 6e 64 20 69  created it and i
11d10 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
11d20 64 65 6c 65 74 65 64 20 77 68 65 6e 0a 74 68 65  deleted when.the
11d30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11d40 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 3c  tion is closed.<
11d50 2f 70 3e 0a 0a 3c 70 3e 20 5e 49 66 20 61 20 3c  /p>..<p> ^If a <
11d60 79 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61  yyterm>schema-na
11d70 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 69 73 20 73  me</yyterm> is s
11d80 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
11d90 68 65 20 76 69 65 77 20 0a 69 73 20 63 72 65 61  he view .is crea
11da0 74 65 64 20 69 6e 20 74 68 65 20 73 70 65 63 69  ted in the speci
11db0 66 69 65 64 20 64 61 74 61 62 61 73 65 2e 0a 5e  fied database..^
11dc0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
11dd0 6f 20 73 70 65 63 69 66 79 20 62 6f 74 68 20 61  o specify both a
11de0 20 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d   <yyterm>schema-
11df0 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 0a 61 6e  name</yyterm>.an
11e00 64 20 74 68 65 20 54 45 4d 50 20 6b 65 79 77 6f  d the TEMP keywo
11e10 72 64 20 6f 6e 20 61 20 56 49 45 57 2c 20 75 6e  rd on a VIEW, un
11e20 6c 65 73 73 20 74 68 65 20 3c 79 79 74 65 72 6d  less the <yyterm
11e30 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79  >schema-name</yy
11e40 74 65 72 6d 3e 20 0a 69 73 20 22 74 65 6d 70 22  term> .is "temp"
11e50 2e 0a 5e 49 66 20 6e 6f 20 73 63 68 65 6d 61 20  ..^If no schema 
11e60 6e 61 6d 65 20 69 73 20 73 70 65 63 69 66 69 65  name is specifie
11e70 64 2c 20 61 6e 64 20 74 68 65 20 54 45 4d 50 20  d, and the TEMP 
11e80 6b 65 79 77 6f 72 64 20 69 73 20 6e 6f 74 20 70  keyword is not p
11e90 72 65 73 65 6e 74 2c 0a 74 68 65 20 56 49 45 57  resent,.the VIEW
11ea0 20 69 73 20 63 72 65 61 74 65 64 20 69 6e 20 74   is created in t
11eb0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
11ec0 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 59 6f 75 20 63  .</p>..<p>^You c
11ed0 61 6e 6e 6f 74 20 5b 44 45 4c 45 54 45 5d 2c 20  annot [DELETE], 
11ee0 5b 49 4e 53 45 52 54 5d 2c 20 6f 72 20 5b 55 50  [INSERT], or [UP
11ef0 44 41 54 45 5d 20 61 20 76 69 65 77 2e 20 20 5e  DATE] a view.  ^
11f00 56 69 65 77 73 20 61 72 65 20 72 65 61 64 2d 6f  Views are read-o
11f10 6e 6c 79 20 0a 69 6e 20 53 51 4c 69 74 65 2e 20  nly .in SQLite. 
11f20 20 5e 48 6f 77 65 76 65 72 2c 20 69 6e 20 6d 61   ^However, in ma
11f30 6e 79 20 63 61 73 65 73 20 79 6f 75 20 63 61 6e  ny cases you can
11f40 20 75 73 65 20 61 6e 0a 5b 49 4e 53 54 45 41 44   use an.[INSTEAD
11f50 20 4f 46 20 74 72 69 67 67 65 72 5d 20 6f 6e 20   OF trigger] on 
11f60 74 68 65 20 76 69 65 77 20 74 6f 20 61 63 63 6f  the view to acco
11f70 6d 70 6c 69 73 68 20 0a 74 68 65 20 73 61 6d 65  mplish .the same
11f80 20 74 68 69 6e 67 2e 20 20 5e 56 69 65 77 73 20   thing.  ^Views 
11f90 61 72 65 20 72 65 6d 6f 76 65 64 20 0a 77 69 74  are removed .wit
11fa0 68 20 74 68 65 20 5b 44 52 4f 50 20 56 49 45 57  h the [DROP VIEW
11fb0 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70 3e 0a 0a  ] command.</p>..
11fc0 3c 70 3e 5e 49 66 20 61 20 3c 79 79 74 65 72 6d  <p>^If a <yyterm
11fd0 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79  >column-name</yy
11fe0 74 65 72 6d 3e 20 6c 69 73 74 20 66 6f 6c 6c 6f  term> list follo
11ff0 77 73 20 0a 74 68 65 20 3c 79 79 74 65 72 6d 3e  ws .the <yyterm>
12000 76 69 65 77 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  view-name</yyter
12010 6d 3e 2c 20 74 68 65 6e 20 74 68 61 74 20 6c 69  m>, then that li
12020 73 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 74 68  st determines.th
12030 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
12040 6f 6c 75 6d 6e 73 20 66 6f 72 20 74 68 65 20 76  olumns for the v
12050 69 65 77 2e 20 20 5e 49 66 20 74 68 65 20 3c 79  iew.  ^If the <y
12060 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d  yterm>column-nam
12070 65 3c 2f 79 79 74 65 72 6d 3e 0a 6c 69 73 74 20  e</yyterm>.list 
12080 69 73 20 6f 6d 69 74 74 65 64 2c 20 74 68 65 6e  is omitted, then
12090 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
120a0 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  e columns in the
120b0 20 76 69 65 77 20 61 72 65 20 64 65 72 69 76 65   view are derive
120c0 64 0a 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 73  d.from the names
120d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2d 73   of the result-s
120e0 65 74 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  et columns in th
120f0 65 20 5b 73 65 6c 65 63 74 2d 73 74 6d 74 5d 2e  e [select-stmt].
12100 0a 54 68 65 20 75 73 65 20 6f 66 20 3c 79 79 74  .The use of <yyt
12110 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c  erm>column-name<
12120 2f 79 79 74 65 72 6d 3e 20 6c 69 73 74 20 69 73  /yyterm> list is
12130 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 20 20 4f   recommended.  O
12140 72 2c 20 69 66 0a 3c 79 79 74 65 72 6d 3e 63 6f  r, if.<yyterm>co
12150 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  lumn-name</yyter
12160 6d 3e 20 6c 69 73 74 20 69 73 20 6f 6d 69 74 74  m> list is omitt
12170 65 64 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ed, then the res
12180 75 6c 74 0a 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  ult.columns in t
12190 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
121a0 65 6d 65 6e 74 20 74 68 61 74 20 64 65 66 69 6e  ement that defin
121b0 65 73 20 74 68 65 20 76 69 65 77 20 73 68 6f 75  es the view shou
121c0 6c 64 20 68 61 76 65 0a 77 65 6c 6c 2d 64 65 66  ld have.well-def
121d0 69 6e 65 64 20 6e 61 6d 65 73 20 75 73 69 6e 67  ined names using
121e0 20 74 68 65 20 0a 22 5b 72 65 73 75 6c 74 2d 63   the ."[result-c
121f0 6f 6c 75 6d 6e 7c 41 53 20 63 6f 6c 75 6d 6e 2d  olumn|AS column-
12200 61 6c 69 61 73 5d 22 20 73 79 6e 74 61 78 2e 0a  alias]" syntax..
12210 53 51 4c 69 74 65 20 61 6c 6c 6f 77 73 20 79 6f  SQLite allows yo
12220 75 20 74 6f 20 63 72 65 61 74 65 20 76 69 65 77  u to create view
12230 73 20 74 68 61 74 20 64 65 70 65 6e 64 20 6f 6e  s that depend on
12240 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 0a   automatically .
12250 67 65 6e 65 72 61 74 65 64 20 63 6f 6c 75 6d 6e  generated column
12260 20 6e 61 6d 65 73 2c 20 62 75 74 20 79 6f 75 20   names, but you 
12270 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 75 73 69  should avoid usi
12280 6e 67 20 74 68 65 6d 20 73 69 6e 63 65 20 74 68  ng them since th
12290 65 20 0a 72 75 6c 65 73 20 75 73 65 64 20 74 6f  e .rules used to
122a0 20 67 65 6e 65 72 61 74 65 20 63 6f 6c 75 6d 6e   generate column
122b0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
122c0 20 64 65 66 69 6e 65 64 20 70 61 72 74 20 6f 66   defined part of
122d0 20 74 68 65 0a 69 6e 74 65 72 66 61 63 65 20 61   the.interface a
122e0 6e 64 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  nd might change 
122f0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
12300 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 0a 3c  es of SQLite...<
12310 70 3e 54 68 65 20 3c 79 79 74 65 72 6d 3e 63 6f  p>The <yyterm>co
12320 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  lumn-name</yyter
12330 6d 3e 20 6c 69 73 74 20 73 79 6e 74 61 78 20 77  m> list syntax w
12340 61 73 20 61 64 64 65 64 20 69 6e 0a 53 51 4c 69  as added in.SQLi
12350 74 65 20 76 65 72 73 69 6f 6e 73 20 33 2e 39 2e  te versions 3.9.
12360 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 39 2e 30  0 ([dateof:3.9.0
12370 5d 29 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  ])...<tcl>.#####
12380 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12390 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
123a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
123b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
123c0 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
123d0 6e 20 7b 43 52 45 41 54 45 20 56 49 52 54 55 41  n {CREATE VIRTUA
123e0 4c 20 54 41 42 4c 45 7d 20 7b 63 72 65 61 74 65  L TABLE} {create
123f0 76 74 61 62 7d 20 7b 7b 43 52 45 41 54 45 20 56  vtab} {{CREATE V
12400 49 52 54 55 41 4c 20 54 41 42 4c 45 7d 7d 0a 0a  IRTUAL TABLE}}..
12410 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
12420 69 61 67 72 61 6d 20 63 72 65 61 74 65 2d 76 69  iagram create-vi
12430 72 74 75 61 6c 2d 74 61 62 6c 65 2d 73 74 6d 74  rtual-table-stmt
12440 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 41 20 5b 76  .</tcl>..<p>A [v
12450 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 73  irtual table] is
12460 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 74 6f   an interface to
12470 20 61 6e 20 65 78 74 65 72 6e 61 6c 20 73 74 6f   an external sto
12480 72 61 67 65 20 6f 72 20 63 6f 6d 70 75 74 61 74  rage or computat
12490 69 6f 6e 0a 65 6e 67 69 6e 65 20 74 68 61 74 20  ion.engine that 
124a0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
124b0 74 61 62 6c 65 20 62 75 74 20 64 6f 65 73 20 6e  table but does n
124c0 6f 74 20 61 63 74 75 61 6c 6c 79 20 73 74 6f 72  ot actually stor
124d0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 69 6e  e information.in
124e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
124f0 6c 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 6e 20 67  le.</p>..<p>In g
12500 65 6e 65 72 61 6c 2c 20 79 6f 75 20 63 61 6e 20  eneral, you can 
12510 64 6f 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  do anything with
12520 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
12530 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65 20 64  e] that can be d
12540 6f 6e 65 0a 77 69 74 68 20 61 6e 20 6f 72 64 69  one.with an ordi
12550 6e 61 72 79 20 74 61 62 6c 65 2c 20 65 78 63 65  nary table, exce
12560 70 74 20 74 68 61 74 20 5e 79 6f 75 20 63 61 6e  pt that ^you can
12570 6e 6f 74 20 63 72 65 61 74 65 20 69 6e 64 69 63  not create indic
12580 65 73 20 6f 72 20 74 72 69 67 67 65 72 73 20 6f  es or triggers o
12590 6e 20 61 0a 76 69 72 74 75 61 6c 20 74 61 62 6c  n a.virtual tabl
125a0 65 2e 20 20 5e 53 6f 6d 65 20 76 69 72 74 75 61  e.  ^Some virtua
125b0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
125c0 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 69 6d  tations might im
125d0 70 6f 73 65 20 61 64 64 69 74 69 6f 6e 61 6c 0a  pose additional.
125e0 72 65 73 74 72 69 63 74 69 6f 6e 73 2e 20 20 46  restrictions.  F
125f0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6d 61 6e 79  or example, many
12600 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
12610 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 3c 2f  are read-only.</
12620 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 79 79 74 65  p>..<p>The <yyte
12630 72 6d 3e 6d 6f 64 75 6c 65 2d 6e 61 6d 65 3c 2f  rm>module-name</
12640 79 79 74 65 72 6d 3e 20 69 73 20 74 68 65 20 6e  yyterm> is the n
12650 61 6d 65 20 6f 66 20 61 6e 20 6f 62 6a 65 63 74  ame of an object
12660 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
12670 0a 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62  .the virtual tab
12680 6c 65 2e 20 20 5e 54 68 65 20 3c 79 79 74 65 72  le.  ^The <yyter
12690 6d 3e 6d 6f 64 75 6c 65 2d 6e 61 6d 65 3c 2f 79  m>module-name</y
126a0 79 74 65 72 6d 3e 20 6d 75 73 74 20 62 65 20 72  yterm> must be r
126b0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 74  egistered with.t
126c0 68 65 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  he SQLite databa
126d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
126e0 69 6e 67 0a 5b 73 71 6c 69 74 65 33 5f 63 72 65  ing.[sqlite3_cre
126f0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
12700 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
12710 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 0a 70 72  _module_v2()].pr
12720 69 6f 72 20 74 6f 20 69 73 73 75 69 6e 67 20 74  ior to issuing t
12730 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41  he CREATE VIRTUA
12740 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  L TABLE statemen
12750 74 2e 0a 5e 54 68 65 20 6d 6f 64 75 6c 65 20 74  t..^The module t
12760 61 6b 65 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  akes zero or mor
12770 65 20 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65  e comma-separate
12780 64 20 61 72 67 75 6d 65 6e 74 73 2e 0a 5e 54 68  d arguments..^Th
12790 65 20 61 72 67 75 6d 65 6e 74 73 20 63 61 6e 20  e arguments can 
127a0 62 65 20 6a 75 73 74 20 61 62 6f 75 74 20 61 6e  be just about an
127b0 79 20 74 65 78 74 20 61 73 20 6c 6f 6e 67 20 61  y text as long a
127c0 73 20 69 74 20 68 61 73 20 62 61 6c 61 6e 63 65  s it has balance
127d0 64 0a 70 61 72 65 6e 74 68 65 73 65 73 2e 20 20  d.parentheses.  
127e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 79 6e  The argument syn
127f0 74 61 78 20 69 73 20 73 75 66 66 69 63 69 65 6e  tax is sufficien
12800 74 6c 79 20 67 65 6e 65 72 61 6c 20 74 68 61 74  tly general that
12810 20 74 68 65 0a 61 72 67 75 6d 65 6e 74 73 20 63   the.arguments c
12820 61 6e 20 62 65 20 6d 61 64 65 20 74 6f 20 61 70  an be made to ap
12830 70 65 61 72 20 61 73 20 5b 63 6f 6c 75 6d 6e 20  pear as [column 
12840 64 65 66 69 6e 69 74 69 6f 6e 73 5d 20 69 6e 20  definitions] in 
12850 61 20 74 72 61 64 69 74 69 6f 6e 61 6c 0a 5b 43  a traditional.[C
12860 52 45 41 54 45 20 54 41 42 4c 45 5d 20 73 74 61  REATE TABLE] sta
12870 74 65 6d 65 6e 74 2e 20 20 0a 5e 53 51 4c 69 74  tement.  .^SQLit
12880 65 20 70 61 73 73 65 73 20 74 68 65 20 6d 6f 64  e passes the mod
12890 75 6c 65 20 61 72 67 75 6d 65 6e 74 73 20 64 69  ule arguments di
128a0 72 65 63 74 6c 79 0a 74 6f 20 74 68 65 20 5b 78  rectly.to the [x
128b0 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
128c0 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
128d0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
128e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 77 69 74 68  lementation.with
128f0 6f 75 74 20 61 6e 79 20 69 6e 74 65 72 70 72 65  out any interpre
12900 74 61 74 69 6f 6e 2e 20 20 49 74 20 69 73 20 74  tation.  It is t
12910 68 65 20 72 65 73 70 6f 6e 73 69 62 69 6c 69 74  he responsibilit
12920 79 0a 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  y.of the module 
12930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
12940 6f 20 70 61 72 73 65 20 61 6e 64 20 69 6e 74 65  o parse and inte
12950 72 70 72 65 74 20 69 74 73 20 6f 77 6e 20 61 72  rpret its own ar
12960 67 75 6d 65 6e 74 73 2e 3c 2f 70 3e 0a 0a 3c 70  guments.</p>..<p
12970 3e 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c  >^A virtual tabl
12980 65 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  e is destroyed u
12990 73 69 6e 67 20 74 68 65 20 6f 72 64 69 6e 61 72  sing the ordinar
129a0 79 0a 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 73  y.[DROP TABLE] s
129b0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 72 65  tatement.  There
129c0 20 69 73 20 6e 6f 0a 44 52 4f 50 20 56 49 52 54   is no.DROP VIRT
129d0 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d  UAL TABLE statem
129e0 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a  ent.</p>..<tcl>.
129f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12a00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12a10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12a20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12a30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
12a40 65 63 74 69 6f 6e 20 44 45 4c 45 54 45 20 64 65  ection DELETE de
12a50 6c 65 74 65 20 7b 44 45 4c 45 54 45 20 2a 44 45  lete {DELETE *DE
12a60 4c 45 54 45 73 7d 0a 0a 52 65 63 75 72 73 69 76  LETEs}..Recursiv
12a70 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 64  eBubbleDiagram d
12a80 65 6c 65 74 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c  elete-stmt.</tcl
12a90 3e 0a 0a 3c 70 3e 54 68 65 20 44 45 4c 45 54 45  >..<p>The DELETE
12aa0 20 63 6f 6d 6d 61 6e 64 20 72 65 6d 6f 76 65 73   command removes
12ab0 20 72 65 63 6f 72 64 73 20 66 72 6f 6d 20 74 68   records from th
12ac0 65 20 74 61 62 6c 65 20 69 64 65 6e 74 69 66 69  e table identifi
12ad0 65 64 20 62 79 20 74 68 65 0a 20 20 20 5b 71 75  ed by the.   [qu
12ae0 61 6c 69 66 69 65 64 2d 74 61 62 6c 65 2d 6e 61  alified-table-na
12af0 6d 65 5d 2e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65  me]...<p>^If the
12b00 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 73   WHERE clause is
12b10 20 6e 6f 74 20 70 72 65 73 65 6e 74 2c 20 61 6c   not present, al
12b20 6c 20 72 65 63 6f 72 64 73 20 69 6e 20 74 68 65  l records in the
12b30 20 74 61 62 6c 65 20 61 72 65 20 64 65 6c 65 74   table are delet
12b40 65 64 2e 0a 20 20 20 5e 49 66 20 61 20 57 48 45  ed..   ^If a WHE
12b50 52 45 20 63 6c 61 75 73 65 20 69 73 20 73 75 70  RE clause is sup
12b60 70 6c 69 65 64 2c 20 74 68 65 6e 20 6f 6e 6c 79  plied, then only
12b70 20 74 68 6f 73 65 20 72 6f 77 73 20 66 6f 72 20   those rows for 
12b80 77 68 69 63 68 20 74 68 65 0a 20 20 20 57 48 45  which the.   WHE
12b90 52 45 20 63 6c 61 75 73 65 20 5b 62 6f 6f 6c 65  RE clause [boole
12ba0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 5d 20 69  an expression] i
12bb0 73 20 74 72 75 65 20 61 72 65 20 64 65 6c 65 74  s true are delet
12bc0 65 64 2e 0a 20 20 20 5e 52 6f 77 73 20 66 6f 72  ed..   ^Rows for
12bd0 20 77 68 69 63 68 20 74 68 65 20 65 78 70 72 65   which the expre
12be0 73 73 69 6f 6e 20 69 73 20 66 61 6c 73 65 20 6f  ssion is false o
12bf0 72 20 4e 55 4c 4c 20 61 72 65 20 72 65 74 61 69  r NULL are retai
12c00 6e 65 64 2e 0a 0a 3c 68 33 3e 52 65 73 74 72 69  ned...<h3>Restri
12c10 63 74 69 6f 6e 73 20 6f 6e 20 44 45 4c 45 54 45  ctions on DELETE
12c20 20 53 74 61 74 65 6d 65 6e 74 73 20 57 69 74 68   Statements With
12c30 69 6e 20 43 52 45 41 54 45 20 54 52 49 47 47 45  in CREATE TRIGGE
12c40 52 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 66  R</h3>..<p>The f
12c50 6f 6c 6c 6f 77 69 6e 67 20 72 65 73 74 72 69 63  ollowing restric
12c60 74 69 6f 6e 73 20 61 70 70 6c 79 20 74 6f 20 44  tions apply to D
12c70 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
12c80 20 74 68 61 74 20 6f 63 63 75 72 20 77 69 74 68   that occur with
12c90 69 6e 20 74 68 65 0a 20 20 20 62 6f 64 79 20 6f  in the.   body o
12ca0 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
12cb0 47 45 52 5d 20 73 74 61 74 65 6d 65 6e 74 3a 0a  GER] statement:.
12cc0 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  .<ul>.  <li><p>^
12cd0 54 68 65 20 3c 79 79 74 65 72 6d 3e 74 61 62 6c  The <yyterm>tabl
12ce0 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  e-name</yyterm> 
12cf0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
12d00 74 20 6f 66 20 61 20 0a 20 20 20 20 44 45 4c 45  t of a .    DELE
12d10 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
12d20 68 69 6e 0a 20 20 20 20 61 20 74 72 69 67 67 65  hin.    a trigge
12d30 72 20 62 6f 64 79 20 6d 75 73 74 20 62 65 20 75  r body must be u
12d40 6e 71 75 61 6c 69 66 69 65 64 2e 20 20 5e 28 49  nqualified.  ^(I
12d50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12d60 68 65 0a 20 20 20 20 3c 69 3e 73 63 68 65 6d 61  he.    <i>schema
12d70 2d 6e 61 6d 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62  -name</i><b>.</b
12d80 3e 20 70 72 65 66 69 78 20 6f 6e 20 74 68 65 20  > prefix on the 
12d90 74 61 62 6c 65 20 6e 61 6d 65 20 69 73 20 6e 6f  table name is no
12da0 74 20 61 6c 6c 6f 77 65 64 20 0a 20 20 20 20 77  t allowed .    w
12db0 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 2e 29  ithin triggers.)
12dc0 5e 20 5e 49 66 20 74 68 65 20 74 61 62 6c 65 20  ^ ^If the table 
12dd0 74 6f 20 77 68 69 63 68 20 74 68 65 20 74 72 69  to which the tri
12de0 67 67 65 72 20 69 73 20 61 74 74 61 63 68 65 64  gger is attached
12df0 20 69 73 0a 20 20 20 20 6e 6f 74 20 69 6e 20 74   is.    not in t
12e00 68 65 20 74 65 6d 70 20 64 61 74 61 62 61 73 65  he temp database
12e10 2c 20 74 68 65 6e 20 44 45 4c 45 54 45 20 73 74  , then DELETE st
12e20 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e 20  atements within 
12e30 74 68 65 20 74 72 69 67 67 65 72 0a 20 20 20 20  the trigger.    
12e40 62 6f 64 79 20 6d 75 73 74 20 6f 70 65 72 61 74  body must operat
12e50 65 20 6f 6e 20 74 61 62 6c 65 73 20 77 69 74 68  e on tables with
12e60 69 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  in the same data
12e70 62 61 73 65 20 61 73 20 69 74 2e 20 5e 49 66 20  base as it. ^If 
12e80 74 68 65 20 74 61 62 6c 65 0a 20 20 20 20 74 6f  the table.    to
12e90 20 77 68 69 63 68 20 74 68 65 20 74 72 69 67 67   which the trigg
12ea0 65 72 20 69 73 20 61 74 74 61 63 68 65 64 20 69  er is attached i
12eb0 73 20 69 6e 20 74 68 65 20 54 45 4d 50 20 64 61  s in the TEMP da
12ec0 74 61 62 61 73 65 2c 20 74 68 65 6e 20 74 68 65  tabase, then the
12ed0 0a 20 20 20 20 75 6e 71 75 61 6c 69 66 69 65 64  .    unqualified
12ee0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
12ef0 6c 65 20 62 65 69 6e 67 20 64 65 6c 65 74 65 64  le being deleted
12f00 20 69 73 20 72 65 73 6f 6c 76 65 64 20 69 6e 20   is resolved in 
12f10 74 68 65 20 73 61 6d 65 20 77 61 79 20 61 73 0a  the same way as.
12f20 20 20 20 20 69 74 20 69 73 20 66 6f 72 20 61 20      it is for a 
12f30 74 6f 70 2d 6c 65 76 65 6c 20 73 74 61 74 65 6d  top-level statem
12f40 65 6e 74 20 28 62 79 20 73 65 61 72 63 68 69 6e  ent (by searchin
12f50 67 20 66 69 72 73 74 20 74 68 65 20 54 45 4d 50  g first the TEMP
12f60 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
12f70 20 20 20 20 74 68 65 20 6d 61 69 6e 20 64 61 74      the main dat
12f80 61 62 61 73 65 2c 20 74 68 65 6e 20 61 6e 79 20  abase, then any 
12f90 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 73 20  other databases 
12fa0 69 6e 20 74 68 65 20 6f 72 64 65 72 20 74 68 65  in the order the
12fb0 79 20 77 65 72 65 0a 20 20 20 20 61 74 74 61 63  y were.    attac
12fc0 68 65 64 29 2e 0a 20 20 20 20 0a 20 20 3c 6c 69  hed)..    .  <li
12fd0 3e 3c 70 3e 5e 54 68 65 20 49 4e 44 45 58 45 44  ><p>^The INDEXED
12fe0 20 42 59 20 61 6e 64 20 4e 4f 54 20 49 4e 44 45   BY and NOT INDE
12ff0 58 45 44 20 63 6c 61 75 73 65 73 20 61 72 65 20  XED clauses are 
13000 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 6f 6e 20 44  not allowed on D
13010 45 4c 45 54 45 0a 20 20 20 20 73 74 61 74 65 6d  ELETE.    statem
13020 65 6e 74 73 20 77 69 74 68 69 6e 20 74 72 69 67  ents within trig
13030 67 65 72 73 2e 3c 2f 70 3e 0a 0a 20 20 3c 6c 69  gers.</p>..  <li
13040 3e 3c 70 3e 5e 54 68 65 20 4c 49 4d 49 54 20 61  ><p>^The LIMIT a
13050 6e 64 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  nd ORDER BY clau
13060 73 65 73 20 28 64 65 73 63 72 69 62 65 64 20 62  ses (described b
13070 65 6c 6f 77 29 20 61 72 65 20 75 6e 73 75 70 70  elow) are unsupp
13080 6f 72 74 65 64 20 66 6f 72 0a 20 20 20 20 44 45  orted for.    DE
13090 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
130a0 77 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 2e  within triggers.
130b0 3c 2f 70 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 68 33 3e  </p>.</ul>..<h3>
130c0 4f 70 74 69 6f 6e 61 6c 20 4c 49 4d 49 54 20 61  Optional LIMIT a
130d0 6e 64 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  nd ORDER BY clau
130e0 73 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 49  ses</h3>..<p>^(I
130f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13100 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
13110 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 55 50 44  QLITE_ENABLE_UPD
13120 41 54 45 5f 44 45 4c 45 54 45 5f 4c 49 4d 49 54  ATE_DELETE_LIMIT
13130 5d 0a 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ].compile-time o
13140 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
13150 73 79 6e 74 61 78 20 6f 66 20 74 68 65 20 44 45  syntax of the DE
13160 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 69  LETE statement i
13170 73 0a 65 78 74 65 6e 64 65 64 20 62 79 20 74 68  s.extended by th
13180 65 20 61 64 64 69 74 69 6f 6e 20 6f 66 20 6f 70  e addition of op
13190 74 69 6f 6e 61 6c 20 4f 52 44 45 52 20 42 59 20  tional ORDER BY 
131a0 61 6e 64 20 4c 49 4d 49 54 20 63 6c 61 75 73 65  and LIMIT clause
131b0 73 3a 29 5e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 42  s:)^</p>..<tcl>B
131c0 75 62 62 6c 65 44 69 61 67 72 61 6d 20 64 65 6c  ubbleDiagram del
131d0 65 74 65 2d 73 74 6d 74 2d 6c 69 6d 69 74 65 64  ete-stmt-limited
131e0 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 49 66 20 61  </tcl>..<p>^If a
131f0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
13200 74 20 68 61 73 20 61 20 4c 49 4d 49 54 20 63 6c  t has a LIMIT cl
13210 61 75 73 65 2c 20 74 68 65 20 6d 61 78 69 6d 75  ause, the maximu
13220 6d 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  m number of rows
13230 20 74 68 61 74 0a 77 69 6c 6c 20 62 65 20 64 65   that.will be de
13240 6c 65 74 65 64 20 69 73 20 66 6f 75 6e 64 20 62  leted is found b
13250 79 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  y evaluating the
13260 20 61 63 63 6f 6d 70 61 6e 79 69 6e 67 20 65 78   accompanying ex
13270 70 72 65 73 73 69 6f 6e 20 61 6e 64 20 63 61 73  pression and cas
13280 74 69 6e 67 0a 69 74 20 74 6f 20 61 6e 20 69 6e  ting.it to an in
13290 74 65 67 65 72 20 76 61 6c 75 65 2e 20 5e 49 66  teger value. ^If
132a0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
132b0 68 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  he evaluating th
132c0 65 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 0a 63  e LIMIT clause.c
132d0 61 6e 6e 6f 74 20 62 65 20 6c 6f 73 73 6c 65 73  annot be lossles
132e0 73 6c 79 20 63 6f 6e 76 65 72 74 65 64 20 74 6f  sly converted to
132f0 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75   an integer valu
13300 65 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  e, it is an erro
13310 72 2e 20 5e 41 20 0a 6e 65 67 61 74 69 76 65 20  r. ^A .negative 
13320 4c 49 4d 49 54 20 76 61 6c 75 65 20 69 73 20 69  LIMIT value is i
13330 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 22 6e  nterpreted as "n
13340 6f 20 6c 69 6d 69 74 22 2e 20 5e 28 49 66 20 74  o limit". ^(If t
13350 68 65 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  he DELETE statem
13360 65 6e 74 20 0a 61 6c 73 6f 20 68 61 73 20 61 6e  ent .also has an
13370 20 4f 46 46 53 45 54 20 63 6c 61 75 73 65 2c 20   OFFSET clause, 
13380 74 68 65 6e 20 69 74 20 69 73 20 73 69 6d 69 6c  then it is simil
13390 61 72 6c 79 20 65 76 61 6c 75 61 74 65 64 20 61  arly evaluated a
133a0 6e 64 20 63 61 73 74 20 74 6f 20 61 6e 0a 69 6e  nd cast to an.in
133b0 74 65 67 65 72 20 76 61 6c 75 65 2e 20 41 67 61  teger value. Aga
133c0 69 6e 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72  in, it is an err
133d0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
133e0 63 61 6e 6e 6f 74 20 62 65 20 6c 6f 73 73 6c 65  cannot be lossle
133f0 73 73 6c 79 0a 63 6f 6e 76 65 72 74 65 64 20 74  ssly.converted t
13400 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 29 5e 20  o an integer.)^ 
13410 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
13420 4f 46 46 53 45 54 20 63 6c 61 75 73 65 2c 20 6f  OFFSET clause, o
13430 72 20 74 68 65 20 63 61 6c 63 75 6c 61 74 65 64  r the calculated
13440 0a 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 69  .integer value i
13450 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
13460 65 66 66 65 63 74 69 76 65 20 4f 46 46 53 45 54  effective OFFSET
13470 20 76 61 6c 75 65 20 69 73 20 7a 65 72 6f 2e 0a   value is zero..
13480 0a 3c 70 3e 5e 28 49 66 20 74 68 65 20 44 45 4c  .<p>^(If the DEL
13490 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 68 61  ETE statement ha
134a0 73 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c  s an ORDER BY cl
134b0 61 75 73 65 2c 20 74 68 65 6e 20 61 6c 6c 20 72  ause, then all r
134c0 6f 77 73 20 74 68 61 74 20 77 6f 75 6c 64 20 0a  ows that would .
134d0 62 65 20 64 65 6c 65 74 65 64 20 69 6e 20 74 68  be deleted in th
134e0 65 20 61 62 73 65 6e 63 65 20 6f 66 20 74 68 65  e absence of the
134f0 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 61 72   LIMIT clause ar
13500 65 20 73 6f 72 74 65 64 20 61 63 63 6f 72 64 69  e sorted accordi
13510 6e 67 20 74 6f 20 74 68 65 20 0a 4f 52 44 45 52  ng to the .ORDER
13520 20 42 59 2e 20 54 68 65 20 66 69 72 73 74 20 3c   BY. The first <
13530 69 3e 4d 3c 2f 69 3e 20 72 6f 77 73 2c 20 77 68  i>M</i> rows, wh
13540 65 72 65 20 3c 69 3e 4d 3c 2f 69 3e 20 69 73 20  ere <i>M</i> is 
13550 74 68 65 20 76 61 6c 75 65 20 66 6f 75 6e 64 20  the value found 
13560 62 79 0a 65 76 61 6c 75 61 74 69 6e 67 20 74 68  by.evaluating th
13570 65 20 4f 46 46 53 45 54 20 63 6c 61 75 73 65 20  e OFFSET clause 
13580 65 78 70 72 65 73 73 69 6f 6e 2c 20 61 72 65 20  expression, are 
13590 73 6b 69 70 70 65 64 2c 20 61 6e 64 20 74 68 65  skipped, and the
135a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 0a 3c 69 3e 4e   following .<i>N
135b0 3c 2f 69 3e 2c 20 77 68 65 72 65 20 3c 69 3e 4e  </i>, where <i>N
135c0 3c 2f 69 3e 20 69 73 20 74 68 65 20 76 61 6c 75  </i> is the valu
135d0 65 20 6f 66 20 74 68 65 20 4c 49 4d 49 54 20 65  e of the LIMIT e
135e0 78 70 72 65 73 73 69 6f 6e 2c 20 61 72 65 20 64  xpression, are d
135f0 65 6c 65 74 65 64 2e 29 5e 0a 5e 49 66 20 74 68  eleted.)^.^If th
13600 65 72 65 20 61 72 65 20 6c 65 73 73 20 74 68 61  ere are less tha
13610 6e 20 3c 69 3e 4e 3c 2f 69 3e 20 72 6f 77 73 20  n <i>N</i> rows 
13620 72 65 6d 61 69 6e 69 6e 67 20 61 66 74 65 72 20  remaining after 
13630 74 61 6b 69 6e 67 20 74 68 65 20 4f 46 46 53 45  taking the OFFSE
13640 54 20 63 6c 61 75 73 65 0a 69 6e 74 6f 20 61 63  T clause.into ac
13650 63 6f 75 6e 74 2c 20 6f 72 20 69 66 20 74 68 65  count, or if the
13660 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 65 76   LIMIT clause ev
13670 61 6c 75 61 74 65 64 20 74 6f 20 61 20 6e 65 67  aluated to a neg
13680 61 74 69 76 65 20 76 61 6c 75 65 2c 20 74 68 65  ative value, the
13690 6e 20 61 6c 6c 0a 72 65 6d 61 69 6e 69 6e 67 20  n all.remaining 
136a0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
136b0 2e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 44 45  ...<p>^If the DE
136c0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 68  LETE statement h
136d0 61 73 20 6e 6f 20 4f 52 44 45 52 20 42 59 20 63  as no ORDER BY c
136e0 6c 61 75 73 65 2c 20 74 68 65 6e 20 61 6c 6c 20  lause, then all 
136f0 72 6f 77 73 20 74 68 61 74 0a 77 6f 75 6c 64 20  rows that.would 
13700 62 65 20 64 65 6c 65 74 65 64 20 69 6e 20 74 68  be deleted in th
13710 65 20 61 62 73 65 6e 63 65 20 6f 66 20 74 68 65  e absence of the
13720 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 61 72   LIMIT clause ar
13730 65 20 61 73 73 65 6d 62 6c 65 64 20 69 6e 20 61  e assembled in a
13740 6e 0a 61 72 62 69 74 72 61 72 79 20 6f 72 64 65  n.arbitrary orde
13750 72 20 62 65 66 6f 72 65 20 61 70 70 6c 79 69 6e  r before applyin
13760 67 20 74 68 65 20 4c 49 4d 49 54 20 61 6e 64 20  g the LIMIT and 
13770 4f 46 46 53 45 54 20 63 6c 61 75 73 65 73 20 74  OFFSET clauses t
13780 6f 20 64 65 74 65 72 6d 69 6e 65 20 0a 74 68 65  o determine .the
13790 20 73 75 62 73 65 74 20 74 68 61 74 20 61 72 65   subset that are
137a0 20 61 63 74 75 61 6c 6c 79 20 64 65 6c 65 74 65   actually delete
137b0 64 2e 0a 0a 3c 70 3e 5e 28 54 68 65 20 4f 52 44  d...<p>^(The ORD
137c0 45 52 20 42 59 20 63 6c 61 75 73 65 20 6f 6e 20  ER BY clause on 
137d0 61 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  a DELETE stateme
137e0 6e 74 20 69 73 20 75 73 65 64 20 6f 6e 6c 79 20  nt is used only 
137f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 69  to determine whi
13800 63 68 0a 72 6f 77 73 20 66 61 6c 6c 20 77 69 74  ch.rows fall wit
13810 68 69 6e 20 74 68 65 20 4c 49 4d 49 54 2e 20 54  hin the LIMIT. T
13820 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
13830 68 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  h rows are delet
13840 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 0a  ed is arbitrary.
13850 61 6e 64 20 69 73 20 6e 6f 74 20 69 6e 66 6c 75  and is not influ
13860 65 6e 63 65 64 20 62 79 20 74 68 65 20 4f 52 44  enced by the ORD
13870 45 52 20 42 59 20 63 6c 61 75 73 65 2e 29 5e 0a  ER BY clause.)^.
13880 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
13890 74 20 74 72 75 6e 63 61 74 65 6f 70 74 20 7b 74  t truncateopt {t
138a0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
138b0 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  tion}</tcl>.<h3>
138c0 54 68 65 20 54 72 75 6e 63 61 74 65 20 4f 70 74  The Truncate Opt
138d0 69 6d 69 7a 61 74 69 6f 6e 3c 2f 68 33 3e 0a 0a  imization</h3>..
138e0 3c 70 3e 5e 57 68 65 6e 20 74 68 65 20 57 48 45  <p>^When the WHE
138f0 52 45 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  RE is omitted fr
13900 6f 6d 20 61 20 44 45 4c 45 54 45 20 73 74 61 74  om a DELETE stat
13910 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 74 61  ement and the ta
13920 62 6c 65 0a 62 65 69 6e 67 20 64 65 6c 65 74 65  ble.being delete
13930 64 20 68 61 73 20 6e 6f 20 74 72 69 67 67 65 72  d has no trigger
13940 73 2c 0a 53 51 4c 69 74 65 20 75 73 65 73 20 61  s,.SQLite uses a
13950 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 74  n optimization t
13960 6f 20 65 72 61 73 65 20 74 68 65 20 65 6e 74 69  o erase the enti
13970 72 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  re table content
13980 0a 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20  .without having 
13990 74 6f 20 76 69 73 69 74 20 65 61 63 68 20 72 6f  to visit each ro
139a0 77 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 69  w of the table i
139b0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 54 68 69  ndividually..Thi
139c0 73 20 22 74 72 75 6e 63 61 74 65 22 20 6f 70 74  s "truncate" opt
139d0 69 6d 69 7a 61 74 69 6f 6e 20 6d 61 6b 65 73 20  imization makes 
139e0 74 68 65 20 64 65 6c 65 74 65 20 72 75 6e 20 6d  the delete run m
139f0 75 63 68 20 66 61 73 74 65 72 2e 0a 50 72 69 6f  uch faster..Prio
13a00 72 20 74 6f 20 53 51 4c 69 74 65 20 5b 76 65 72  r to SQLite [ver
13a10 73 69 6f 6e 20 33 2e 36 2e 35 5d 20 28 5b 64 61  sion 3.6.5] ([da
13a20 74 65 6f 66 3a 33 2e 36 2e 35 5d 29 2c 20 74 68  teof:3.6.5]), th
13a30 65 20 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d  e truncate optim
13a40 69 7a 61 74 69 6f 6e 0a 61 6c 73 6f 20 6d 65 61  ization.also mea
13a50 6e 74 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  nt that the [sql
13a60 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
13a70 61 6e 64 0a 5b 73 71 6c 69 74 65 33 5f 74 6f 74  and.[sqlite3_tot
13a80 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
13a90 74 65 72 66 61 63 65 73 0a 61 6e 64 20 74 68 65  terfaces.and the
13aa0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
13ab0 70 72 61 67 6d 61 5d 0a 77 69 6c 6c 20 6e 6f 74  pragma].will not
13ac0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
13ad0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
13ae0 65 6c 65 74 65 64 20 72 6f 77 73 2e 20 20 0a 54  eleted rows.  .T
13af0 68 61 74 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  hat problem has 
13b00 62 65 65 6e 20 66 69 78 65 64 20 61 73 20 6f 66  been fixed as of
13b10 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 35 5d   [version 3.6.5]
13b20 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 35 5d   ([dateof:3.6.5]
13b30 29 2e 0a 0a 3c 70 3e 5e 54 68 65 20 74 72 75 6e  )...<p>^The trun
13b40 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
13b50 6e 20 63 61 6e 20 62 65 20 70 65 72 6d 61 6e 65  n can be permane
13b60 6e 74 6c 79 20 64 69 73 61 62 6c 65 64 20 66 6f  ntly disabled fo
13b70 72 20 61 6c 6c 20 71 75 65 72 69 65 73 0a 62 79  r all queries.by
13b80 20 72 65 63 6f 6d 70 69 6c 69 6e 67 0a 53 51 4c   recompiling.SQL
13b90 69 74 65 20 77 69 74 68 20 74 68 65 20 5b 53 51  ite with the [SQ
13ba0 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41  LITE_OMIT_TRUNCA
13bb0 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d  TE_OPTIMIZATION]
13bc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 77   compile-time sw
13bd0 69 74 63 68 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  itch.</p>..<p>Th
13be0 65 20 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d  e truncate optim
13bf0 69 7a 61 74 69 6f 6e 20 63 61 6e 20 61 6c 73 6f  ization can also
13c00 20 62 65 20 64 69 73 61 62 6c 65 64 20 61 74 20   be disabled at 
13c10 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 0a 74 68  runtime using.th
13c20 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
13c30 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
13c40 65 72 66 61 63 65 2e 20 20 5e 49 66 20 61 6e 20  erface.  ^If an 
13c50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
13c60 61 63 6b 0a 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack.returns [SQL
13c70 49 54 45 5f 49 47 4e 4f 52 45 5d 20 66 6f 72 20  ITE_IGNORE] for 
13c80 61 6e 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  an [SQLITE_DELET
13c90 45 5d 20 61 63 74 69 6f 6e 20 63 6f 64 65 2c 20  E] action code, 
13ca0 74 68 65 6e 0a 74 68 65 20 44 45 4c 45 54 45 20  then.the DELETE 
13cb0 6f 70 65 72 61 74 69 6f 6e 20 77 69 6c 6c 20 70  operation will p
13cc0 72 6f 63 65 65 64 20 62 75 74 20 74 68 65 20 74  roceed but the t
13cd0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
13ce0 74 69 6f 6e 20 77 69 6c 6c 0a 62 65 20 62 79 70  tion will.be byp
13cf0 61 73 73 65 64 20 61 6e 64 20 72 6f 77 73 20 77  assed and rows w
13d00 69 6c 6c 20 62 65 20 64 65 6c 65 74 65 64 20 6f  ill be deleted o
13d10 6e 65 20 62 79 20 6f 6e 65 2e 3c 2f 70 3e 0a 0a  ne by one.</p>..
13d20 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
13d30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13d40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13d50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13d60 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13d70 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44  #####.Section {D
13d80 45 54 41 43 48 20 44 41 54 41 42 41 53 45 7d 20  ETACH DATABASE} 
13d90 64 65 74 61 63 68 20 2a 44 45 54 41 43 48 0a 0a  detach *DETACH..
13da0 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
13db0 69 61 67 72 61 6d 20 64 65 74 61 63 68 2d 73 74  iagram detach-st
13dc0 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54  mt.</tcl>..<p>^T
13dd0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 64 65  his statement de
13de0 74 61 63 68 65 73 20 61 6e 20 61 64 64 69 74 69  taches an additi
13df0 6f 6e 61 6c 20 64 61 74 61 62 61 73 65 20 63 6f  onal database co
13e00 6e 6e 65 63 74 69 6f 6e 20 70 72 65 76 69 6f 75  nnection previou
13e10 73 6c 79 20 0a 61 74 74 61 63 68 65 64 20 75 73  sly .attached us
13e20 69 6e 67 20 74 68 65 20 5b 41 54 54 41 43 48 5d  ing the [ATTACH]
13e30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 0a 5e 57   statement.  .^W
13e40 68 65 6e 20 6e 6f 74 20 69 6e 20 5b 73 68 61 72  hen not in [shar
13e50 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
13e60 0a 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20  .it is possible 
13e70 74 6f 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  to have the same
13e80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
13e90 74 74 61 63 68 65 64 20 6d 75 6c 74 69 70 6c 65  ttached multiple
13ea0 20 74 69 6d 65 73 20 75 73 69 6e 67 20 0a 64 69   times using .di
13eb0 66 66 65 72 65 6e 74 20 6e 61 6d 65 73 2c 20 61  fferent names, a
13ec0 6e 64 20 64 65 74 61 63 68 69 6e 67 20 6f 6e 65  nd detaching one
13ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61   connection to a
13ee0 20 66 69 6c 65 20 77 69 6c 6c 20 6c 65 61 76 65   file will leave
13ef0 20 74 68 65 20 0a 6f 74 68 65 72 73 20 69 6e 74   the .others int
13f00 61 63 74 2e 3c 2f 70 3e 0a 5e 49 6e 20 5b 73 68  act.</p>.^In [sh
13f10 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
13f20 2c 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  , attempting to 
13f30 61 74 74 61 63 68 20 74 68 65 20 73 61 6d 65 20  attach the same 
13f40 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6d 6f  database file mo
13f50 72 65 0a 74 68 61 6e 20 6f 6e 63 65 20 72 65 73  re.than once res
13f60 75 6c 74 73 20 69 6e 20 61 6e 20 65 72 72 6f 72  ults in an error
13f70 2e 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  ....<tcl>.######
13f80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13f90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13fa0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13fb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13fc0 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
13fd0 20 7b 44 52 4f 50 20 49 4e 44 45 58 7d 20 64 72   {DROP INDEX} dr
13fe0 6f 70 69 6e 64 65 78 20 7b 7b 44 52 4f 50 20 49  opindex {{DROP I
13ff0 4e 44 45 58 7d 7d 0a 0a 52 65 63 75 72 73 69 76  NDEX}}..Recursiv
14000 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 64  eBubbleDiagram d
14010 72 6f 70 2d 69 6e 64 65 78 2d 73 74 6d 74 0a 3c  rop-index-stmt.<
14020 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 44  /tcl>..<p>^The D
14030 52 4f 50 20 49 4e 44 45 58 20 73 74 61 74 65 6d  ROP INDEX statem
14040 65 6e 74 20 72 65 6d 6f 76 65 73 20 61 6e 20 69  ent removes an i
14050 6e 64 65 78 20 61 64 64 65 64 0a 77 69 74 68 20  ndex added.with 
14060 74 68 65 20 5b 43 52 45 41 54 45 20 49 4e 44 45  the [CREATE INDE
14070 58 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  X] statement.  T
14080 68 65 20 69 6e 64 65 78 20 69 73 20 63 6f 6d 70  he index is comp
14090 6c 65 74 65 6c 79 20 72 65 6d 6f 76 65 64 20 66  letely removed f
140a0 72 6f 6d 0a 74 68 65 20 64 69 73 6b 2e 20 20 54  rom.the disk.  T
140b0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 72  he only way to r
140c0 65 63 6f 76 65 72 20 74 68 65 20 69 6e 64 65 78  ecover the index
140d0 20 69 73 20 74 6f 20 72 65 65 6e 74 65 72 20 74   is to reenter t
140e0 68 65 0a 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he.appropriate [
140f0 43 52 45 41 54 45 20 49 4e 44 45 58 5d 20 63 6f  CREATE INDEX] co
14100 6d 6d 61 6e 64 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  mmand.</p>..<tcl
14110 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
14120 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14130 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14140 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14150 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14160 0a 53 65 63 74 69 6f 6e 20 7b 44 52 4f 50 20 54  .Section {DROP T
14170 41 42 4c 45 7d 20 64 72 6f 70 74 61 62 6c 65 20  ABLE} droptable 
14180 7b 7b 44 52 4f 50 20 54 41 42 4c 45 7d 7d 0a 0a  {{DROP TABLE}}..
14190 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
141a0 69 61 67 72 61 6d 20 64 72 6f 70 2d 74 61 62 6c  iagram drop-tabl
141b0 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  e-stmt.</tcl>..<
141c0 70 3e 5e 54 68 65 20 44 52 4f 50 20 54 41 42 4c  p>^The DROP TABL
141d0 45 20 73 74 61 74 65 6d 65 6e 74 20 72 65 6d 6f  E statement remo
141e0 76 65 73 20 61 20 74 61 62 6c 65 20 61 64 64 65  ves a table adde
141f0 64 20 77 69 74 68 20 74 68 65 0a 5b 43 52 45 41  d with the.[CREA
14200 54 45 20 54 41 42 4c 45 5d 20 73 74 61 74 65 6d  TE TABLE] statem
14210 65 6e 74 2e 20 20 54 68 65 20 6e 61 6d 65 20 73  ent.  The name s
14220 70 65 63 69 66 69 65 64 20 69 73 20 74 68 65 0a  pecified is the.
14230 74 61 62 6c 65 20 6e 61 6d 65 2e 20 20 5e 54 68  table name.  ^Th
14240 65 20 64 72 6f 70 70 65 64 20 74 61 62 6c 65 20  e dropped table 
14250 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 72 65  is completely re
14260 6d 6f 76 65 64 20 66 72 6f 6d 20 74 68 65 20 64  moved from the d
14270 61 74 61 62 61 73 65 20 0a 73 63 68 65 6d 61 20  atabase .schema 
14280 61 6e 64 20 74 68 65 20 64 69 73 6b 20 66 69 6c  and the disk fil
14290 65 2e 20 20 54 68 65 20 74 61 62 6c 65 20 63 61  e.  The table ca
142a0 6e 20 6e 6f 74 20 62 65 20 72 65 63 6f 76 65 72  n not be recover
142b0 65 64 2e 20 20 0a 5e 41 6c 6c 20 69 6e 64 69 63  ed.  .^All indic
142c0 65 73 20 61 6e 64 20 74 72 69 67 67 65 72 73 0a  es and triggers.
142d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
142e0 74 68 65 20 74 61 62 6c 65 20 61 72 65 20 61 6c  the table are al
142f0 73 6f 20 64 65 6c 65 74 65 64 2e 3c 2f 70 3e 0a  so deleted.</p>.
14300 0a 3c 70 3e 5e 54 68 65 20 6f 70 74 69 6f 6e 61  .<p>^The optiona
14310 6c 20 49 46 20 45 58 49 53 54 53 20 63 6c 61 75  l IF EXISTS clau
14320 73 65 20 73 75 70 70 72 65 73 73 65 73 20 74 68  se suppresses th
14330 65 20 65 72 72 6f 72 20 74 68 61 74 20 77 6f 75  e error that wou
14340 6c 64 20 6e 6f 72 6d 61 6c 6c 79 0a 72 65 73 75  ld normally.resu
14350 6c 74 20 69 66 20 74 68 65 20 74 61 62 6c 65 20  lt if the table 
14360 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 3c  does not exist.<
14370 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 5b 66 6f 72  /p>..<p>^If [for
14380 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
14390 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  ints] are enable
143a0 64 2c 20 61 20 44 52 4f 50 20 54 41 42 4c 45 20  d, a DROP TABLE 
143b0 63 6f 6d 6d 61 6e 64 20 70 65 72 66 6f 72 6d 73  command performs
143c0 20 61 6e 0a 69 6d 70 6c 69 63 69 74 20 5b 44 45   an.implicit [DE
143d0 4c 45 54 45 20 7c 20 44 45 4c 45 54 45 20 46 52  LETE | DELETE FR
143e0 4f 4d 5d 20 63 6f 6d 6d 61 6e 64 20 62 65 66 6f  OM] command befo
143f0 72 65 20 72 65 6d 6f 76 69 6e 67 20 74 68 65 0a  re removing the.
14400 74 61 62 6c 65 20 66 72 6f 6d 20 74 68 65 20 64  table from the d
14410 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 2e 20  atabase schema. 
14420 5e 41 6e 79 20 74 72 69 67 67 65 72 73 20 61 74  ^Any triggers at
14430 74 61 63 68 65 64 20 74 6f 20 74 68 65 20 74 61  tached to the ta
14440 62 6c 65 20 61 72 65 0a 64 72 6f 70 70 65 64 20  ble are.dropped 
14450 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
14460 65 20 73 63 68 65 6d 61 20 62 65 66 6f 72 65 20  e schema before 
14470 74 68 65 20 69 6d 70 6c 69 63 69 74 20 44 45 4c  the implicit DEL
14480 45 54 45 20 46 52 4f 4d 0a 69 73 20 65 78 65 63  ETE FROM.is exec
14490 75 74 65 64 2c 20 73 6f 20 74 68 69 73 20 63 61  uted, so this ca
144a0 6e 6e 6f 74 20 63 61 75 73 65 20 61 6e 79 20 74  nnot cause any t
144b0 72 69 67 67 65 72 73 20 74 6f 20 66 69 72 65 2e  riggers to fire.
144c0 20 42 79 20 63 6f 6e 74 72 61 73 74 2c 20 5e 61   By contrast, ^a
144d0 6e 0a 69 6d 70 6c 69 63 69 74 20 44 45 4c 45 54  n.implicit DELET
144e0 45 20 46 52 4f 4d 20 64 6f 65 73 20 63 61 75 73  E FROM does caus
144f0 65 20 61 6e 79 20 63 6f 6e 66 69 67 75 72 65 64  e any configured
14500 0a 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  .[foreign key ac
14510 74 69 6f 6e 73 5d 20 74 6f 20 74 61 6b 65 20 70  tions] to take p
14520 6c 61 63 65 2e 20 0a 5e 49 66 20 74 68 65 20 69  lace. .^If the i
14530 6d 70 6c 69 63 69 74 20 44 45 4c 45 54 45 20 46  mplicit DELETE F
14540 52 4f 4d 20 65 78 65 63 75 74 65 64 0a 61 73 20  ROM executed.as 
14550 70 61 72 74 20 6f 66 20 61 20 44 52 4f 50 20 54  part of a DROP T
14560 41 42 4c 45 20 63 6f 6d 6d 61 6e 64 20 76 69 6f  ABLE command vio
14570 6c 61 74 65 73 20 61 6e 79 20 69 6d 6d 65 64 69  lates any immedi
14580 61 74 65 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  ate foreign key 
14590 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 61 6e 20  constraints,.an 
145a0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
145b0 64 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20  d and the table 
145c0 69 73 20 6e 6f 74 20 64 72 6f 70 70 65 64 2e 20  is not dropped. 
145d0 5e 49 66 20 0a 74 68 65 20 69 6d 70 6c 69 63 69  ^If .the implici
145e0 74 20 44 45 4c 45 54 45 20 46 52 4f 4d 20 63 61  t DELETE FROM ca
145f0 75 73 65 73 20 61 6e 79 20 0a 64 65 66 65 72 72  uses any .deferr
14600 65 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  ed foreign key c
14610 6f 6e 73 74 72 61 69 6e 74 73 20 74 6f 20 62 65  onstraints to be
14620 20 76 69 6f 6c 61 74 65 64 2c 20 61 6e 64 20 74   violated, and t
14630 68 65 20 76 69 6f 6c 61 74 69 6f 6e 73 20 73 74  he violations st
14640 69 6c 6c 0a 65 78 69 73 74 20 77 68 65 6e 20 74  ill.exist when t
14650 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
14660 73 20 63 6f 6d 6d 69 74 74 65 64 2c 20 61 6e 20  s committed, an 
14670 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
14680 64 20 61 74 20 74 68 65 20 74 69 6d 65 0a 6f 66  d at the time.of
14690 20 63 6f 6d 6d 69 74 2e 0a 0a 3c 74 63 6c 3e 0a   commit...<tcl>.
146a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
146b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
146c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
146d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
146e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
146f0 65 63 74 69 6f 6e 20 7b 44 52 4f 50 20 54 52 49  ection {DROP TRI
14700 47 47 45 52 7d 20 64 72 6f 70 74 72 69 67 67 65  GGER} droptrigge
14710 72 20 7b 7b 44 52 4f 50 20 54 52 49 47 47 45 52  r {{DROP TRIGGER
14720 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  }}..RecursiveBub
14730 62 6c 65 44 69 61 67 72 61 6d 20 64 72 6f 70 2d  bleDiagram drop-
14740 74 72 69 67 67 65 72 2d 73 74 6d 74 0a 3c 2f 74  trigger-stmt.</t
14750 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 44 52 4f  cl>..<p>^The DRO
14760 50 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  P TRIGGER statem
14770 65 6e 74 20 72 65 6d 6f 76 65 73 20 61 20 74 72  ent removes a tr
14780 69 67 67 65 72 20 63 72 65 61 74 65 64 20 62 79  igger created by
14790 20 74 68 65 20 0a 5b 43 52 45 41 54 45 20 54 52   the .[CREATE TR
147a0 49 47 47 45 52 5d 20 73 74 61 74 65 6d 65 6e 74  IGGER] statement
147b0 2e 20 5e 4f 6e 63 65 20 72 65 6d 6f 76 65 64 2c  . ^Once removed,
147c0 20 74 68 65 20 74 72 69 67 67 65 72 20 64 65 66   the trigger def
147d0 69 6e 69 74 69 6f 6e 20 69 73 20 6e 6f 0a 6c 6f  inition is no.lo
147e0 6e 67 65 72 20 70 72 65 73 65 6e 74 20 69 6e 20  nger present in 
147f0 74 68 65 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  the sqlite_maste
14800 72 20 28 6f 72 20 73 71 6c 69 74 65 5f 74 65 6d  r (or sqlite_tem
14810 70 5f 6d 61 73 74 65 72 29 20 74 61 62 6c 65 20  p_master) table 
14820 61 6e 64 20 69 73 0a 6e 6f 74 20 66 69 72 65 64  and is.not fired
14830 20 62 79 20 61 6e 79 20 73 75 62 73 65 71 75 65   by any subseque
14840 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
14850 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
14860 65 6d 65 6e 74 73 2e 0a 0a 3c 70 3e 5e 4e 6f 74  ements...<p>^Not
14870 65 20 74 68 61 74 20 74 72 69 67 67 65 72 73 20  e that triggers 
14880 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
14890 79 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74  y dropped when t
148a0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 74 61  he associated ta
148b0 62 6c 65 20 69 73 0a 64 72 6f 70 70 65 64 2e 0a  ble is.dropped..
148c0 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23  .<tcl>.#########
148d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
148e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
148f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14900 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14910 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44  #####.Section {D
14920 52 4f 50 20 56 49 45 57 7d 20 64 72 6f 70 76 69  ROP VIEW} dropvi
14930 65 77 20 7b 7b 44 52 4f 50 20 56 49 45 57 7d 7d  ew {{DROP VIEW}}
14940 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  ..RecursiveBubbl
14950 65 44 69 61 67 72 61 6d 20 64 72 6f 70 2d 76 69  eDiagram drop-vi
14960 65 77 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  ew-stmt.</tcl>..
14970 3c 70 3e 5e 54 68 65 20 44 52 4f 50 20 56 49 45  <p>^The DROP VIE
14980 57 20 73 74 61 74 65 6d 65 6e 74 20 72 65 6d 6f  W statement remo
14990 76 65 73 20 61 20 76 69 65 77 20 63 72 65 61 74  ves a view creat
149a0 65 64 20 62 79 20 74 68 65 20 5b 43 52 45 41 54  ed by the [CREAT
149b0 45 20 56 49 45 57 5d 20 0a 20 20 73 74 61 74 65  E VIEW] .  state
149c0 6d 65 6e 74 2e 20 5e 54 68 65 20 76 69 65 77 20  ment. ^The view 
149d0 64 65 66 69 6e 69 74 69 6f 6e 20 69 73 20 72 65  definition is re
149e0 6d 6f 76 65 64 20 66 72 6f 6d 20 74 68 65 20 64  moved from the d
149f0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 2c 20  atabase schema, 
14a00 62 75 74 20 0a 20 20 6e 6f 20 61 63 74 75 61 6c  but .  no actual
14a10 20 64 61 74 61 20 69 6e 20 74 68 65 20 75 6e 64   data in the und
14a20 65 72 6c 79 69 6e 67 20 62 61 73 65 20 74 61 62  erlying base tab
14a30 6c 65 73 20 69 73 20 6d 6f 64 69 66 69 65 64 2e  les is modified.
14a40 0a 0a 3c 70 3e 5e 28 54 68 65 20 76 69 65 77 20  ..<p>^(The view 
14a50 74 6f 20 64 72 6f 70 20 69 73 20 69 64 65 6e 74  to drop is ident
14a60 69 66 69 65 64 20 62 79 20 74 68 65 20 76 69 65  ified by the vie
14a70 77 2d 6e 61 6d 65 20 61 6e 64 20 6f 70 74 69 6f  w-name and optio
14a80 6e 61 6c 20 0a 20 20 73 63 68 65 6d 61 2d 6e 61  nal .  schema-na
14a90 6d 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20  me specified as 
14aa0 70 61 72 74 20 6f 66 20 74 68 65 20 44 52 4f 50  part of the DROP
14ab0 20 56 49 45 57 20 73 74 61 74 65 6d 65 6e 74 2e   VIEW statement.
14ac0 20 54 68 69 73 20 0a 20 20 72 65 66 65 72 65 6e   This .  referen
14ad0 63 65 20 69 73 20 72 65 73 6f 6c 76 65 64 20 75  ce is resolved u
14ae0 73 69 6e 67 20 74 68 65 20 73 74 61 6e 64 61 72  sing the standar
14af0 64 20 70 72 6f 63 65 64 75 72 65 20 66 6f 72 20  d procedure for 
14b00 5b 6f 62 6a 65 63 74 20 72 65 73 6f 6c 75 74 69  [object resoluti
14b10 6f 6e 5d 2e 29 5e 0a 0a 3c 70 3e 0a 20 20 5e 49  on].)^..<p>.  ^I
14b20 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
14b30 76 69 65 77 20 63 61 6e 6e 6f 74 20 62 65 20 66  view cannot be f
14b40 6f 75 6e 64 20 61 6e 64 20 74 68 65 20 49 46 20  ound and the IF 
14b50 45 58 49 53 54 53 20 63 6c 61 75 73 65 20 69 73  EXISTS clause is
14b60 20 6e 6f 74 20 0a 20 20 70 72 65 73 65 6e 74 2c   not .  present,
14b70 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 2e   it is an error.
14b80 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
14b90 65 64 20 76 69 65 77 20 63 61 6e 6e 6f 74 20 62  ed view cannot b
14ba0 65 20 66 6f 75 6e 64 20 61 6e 64 20 61 6e 20 49  e found and an I
14bb0 46 0a 20 20 45 58 49 53 54 53 20 63 6c 61 75 73  F.  EXISTS claus
14bc0 65 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 20  e is present in 
14bd0 74 68 65 20 44 52 4f 50 20 56 49 45 57 20 73 74  the DROP VIEW st
14be0 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68  atement, then th
14bf0 65 20 73 74 61 74 65 6d 65 6e 74 0a 20 20 69 73  e statement.  is
14c00 20 61 20 6e 6f 2d 6f 70 2e 0a 0a 0a 3c 74 63 6c   a no-op....<tcl
14c10 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
14c20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14c30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14c40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14c50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14c60 0a 53 65 63 74 69 6f 6e 20 7b 44 61 74 61 62 61  .Section {Databa
14c70 73 65 20 4f 62 6a 65 63 74 20 4e 61 6d 65 20 52  se Object Name R
14c80 65 73 6f 6c 75 74 69 6f 6e 7d 20 7b 6e 61 6d 69  esolution} {nami
14c90 6e 67 7d 20 7b 7b 6f 62 6a 65 63 74 20 72 65 73  ng} {{object res
14ca0 6f 6c 75 74 69 6f 6e 7d 7d 0a 3c 2f 74 63 6c 3e  olution}}.</tcl>
14cb0 0a 0a 3c 70 3e 0a 20 20 49 6e 20 53 51 4c 69 74  ..<p>.  In SQLit
14cc0 65 2c 20 61 20 64 61 74 61 62 61 73 65 20 6f 62  e, a database ob
14cd0 6a 65 63 74 20 28 61 20 74 61 62 6c 65 2c 20 69  ject (a table, i
14ce0 6e 64 65 78 2c 20 74 72 69 67 67 65 72 20 6f 72  ndex, trigger or
14cf0 20 76 69 65 77 29 20 69 73 20 69 64 65 6e 74 69   view) is identi
14d00 66 69 65 64 0a 20 20 62 79 20 74 68 65 20 6e 61  fied.  by the na
14d10 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
14d20 20 61 6e 64 20 74 68 65 20 6e 61 6d 65 20 6f 66   and the name of
14d30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
14d40 61 74 20 69 74 20 72 65 73 69 64 65 73 20 69 6e  at it resides in
14d50 2e 20 0a 20 20 44 61 74 61 62 61 73 65 20 6f 62  . .  Database ob
14d60 6a 65 63 74 73 20 6d 61 79 20 72 65 73 69 64 65  jects may reside
14d70 20 69 6e 20 74 68 65 20 6d 61 69 6e 20 64 61 74   in the main dat
14d80 61 62 61 73 65 2c 20 74 68 65 20 74 65 6d 70 20  abase, the temp 
14d90 64 61 74 61 62 61 73 65 2c 20 6f 72 20 69 6e 0a  database, or in.
14da0 20 20 61 6e 20 5b 41 54 54 41 43 48 7c 61 74 74    an [ATTACH|att
14db0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 5d 2e  ached database].
14dc0 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 73 79 6e 74  ..<p>.  The synt
14dd0 61 78 20 6f 66 20 74 68 65 20 5b 44 52 4f 50 20  ax of the [DROP 
14de0 54 41 42 4c 45 5d 2c 20 5b 44 52 4f 50 20 49 4e  TABLE], [DROP IN
14df0 44 45 58 5d 2c 20 5b 44 52 4f 50 20 56 49 45 57  DEX], [DROP VIEW
14e00 5d 2c 20 5b 44 52 4f 50 20 54 52 49 47 47 45 52  ], [DROP TRIGGER
14e10 5d 2c 0a 20 20 5b 52 45 49 4e 44 45 58 5d 2c 20  ],.  [REINDEX], 
14e20 5b 41 4c 54 45 52 20 54 41 42 4c 45 5d 20 61 6e  [ALTER TABLE] an
14e30 64 20 6d 61 6e 79 20 6f 74 68 65 72 20 63 6f 6d  d many other com
14e40 6d 61 6e 64 73 20 61 6c 6c 20 70 65 72 6d 69 74  mands all permit
14e50 20 74 68 65 20 75 73 65 72 20 74 6f 0a 20 20 73   the user to.  s
14e60 70 65 63 69 66 79 20 61 20 64 61 74 61 62 61 73  pecify a databas
14e70 65 20 6f 62 6a 65 63 74 20 65 69 74 68 65 72 20  e object either 
14e80 62 79 20 69 74 73 20 6e 61 6d 65 20 61 6c 6f 6e  by its name alon
14e90 65 2c 20 6f 72 20 62 79 20 61 20 63 6f 6d 62 69  e, or by a combi
14ea0 6e 61 74 69 6f 6e 20 6f 66 0a 20 20 69 74 73 20  nation of.  its 
14eb0 6e 61 6d 65 20 61 6e 64 20 74 68 65 20 6e 61 6d  name and the nam
14ec0 65 20 6f 66 20 69 74 73 20 64 61 74 61 62 61 73  e of its databas
14ed0 65 2e 20 5e 28 49 66 20 6e 6f 20 64 61 74 61 62  e. ^(If no datab
14ee0 61 73 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ase is specified
14ef0 20 61 73 20 70 61 72 74 0a 20 20 6f 66 20 74 68   as part.  of th
14f00 65 20 6f 62 6a 65 63 74 20 72 65 66 65 72 65 6e  e object referen
14f10 63 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ce, then SQLite 
14f20 73 65 61 72 63 68 65 73 20 74 68 65 20 6d 61 69  searches the mai
14f30 6e 2c 20 74 65 6d 70 20 61 6e 64 20 61 6c 6c 20  n, temp and all 
14f40 61 74 74 61 63 68 65 64 0a 20 20 64 61 74 61 62  attached.  datab
14f50 61 73 65 73 20 66 6f 72 20 61 6e 20 6f 62 6a 65  ases for an obje
14f60 63 74 20 77 69 74 68 20 61 20 6d 61 74 63 68 69  ct with a matchi
14f70 6e 67 20 6e 61 6d 65 2e 20 54 68 65 20 74 65 6d  ng name. The tem
14f80 70 20 64 61 74 61 62 61 73 65 20 69 73 20 73 65  p database is se
14f90 61 72 63 68 65 64 0a 20 20 66 69 72 73 74 2c 20  arched.  first, 
14fa0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20  followed by the 
14fb0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 66  main database, f
14fc0 6f 6c 6c 6f 77 65 64 20 61 6c 6c 20 61 74 74 61  ollowed all atta
14fd0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 69  ched databases i
14fe0 6e 20 74 68 65 0a 20 20 6f 72 64 65 72 20 74 68  n the.  order th
14ff0 61 74 20 74 68 65 79 20 77 65 72 65 20 61 74 74  at they were att
15000 61 63 68 65 64 2e 20 54 68 65 20 72 65 66 65 72  ached. The refer
15010 65 6e 63 65 20 72 65 73 6f 6c 76 65 73 20 74 6f  ence resolves to
15020 20 74 68 65 20 66 69 72 73 74 20 6d 61 74 63 68   the first match
15030 0a 20 20 66 6f 75 6e 64 2e 29 5e 20 46 6f 72 20  .  found.)^ For 
15040 65 78 61 6d 70 6c 65 3a 0a 0a 3c 70 72 65 3e 5e  example:..<pre>^
15050 28 0a 20 20 20 20 20 20 2f 2a 20 41 64 64 20 61  (.      /* Add a
15060 20 74 61 62 6c 65 20 6e 61 6d 65 64 20 27 74 31   table named 't1
15070 27 20 74 6f 20 74 68 65 20 74 65 6d 70 2c 20 6d  ' to the temp, m
15080 61 69 6e 20 61 6e 64 20 61 6e 20 61 74 74 61 63  ain and an attac
15090 68 65 64 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  hed database */.
150a0 20 20 20 20 20 20 41 54 54 41 43 48 20 27 66 69        ATTACH 'fi
150b0 6c 65 2e 64 62 27 20 41 53 20 61 75 78 3b 0a 20  le.db' AS aux;. 
150c0 20 20 20 20 20 43 52 45 41 54 45 20 54 41 42 4c       CREATE TABL
150d0 45 20 74 31 28 78 2c 20 79 29 3b 0a 20 20 20 20  E t1(x, y);.    
150e0 20 20 43 52 45 41 54 45 20 54 45 4d 50 20 54 41    CREATE TEMP TA
150f0 42 4c 45 20 74 31 28 78 2c 20 79 29 3b 0a 20 20  BLE t1(x, y);.  
15100 20 20 20 20 43 52 45 41 54 45 20 54 41 42 4c 45      CREATE TABLE
15110 20 61 75 78 2e 74 31 28 78 2c 20 79 29 3b 0a 0a   aux.t1(x, y);..
15120 20 20 20 20 20 20 44 52 4f 50 20 54 41 42 4c 45        DROP TABLE
15130 20 74 31 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   t1;         /* 
15140 44 72 6f 70 20 74 61 62 6c 65 20 69 6e 20 74 65  Drop table in te
15150 6d 70 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  mp database */. 
15160 20 20 20 20 20 44 52 4f 50 20 54 41 42 4c 45 20       DROP TABLE 
15170 74 31 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 44  t1;         /* D
15180 72 6f 70 20 74 61 62 6c 65 20 69 6e 20 6d 61 69  rop table in mai
15190 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
151a0 20 20 20 20 44 52 4f 50 20 54 41 42 4c 45 20 74      DROP TABLE t
151b0 31 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 44 72  1;         /* Dr
151c0 6f 70 20 74 61 62 6c 65 20 69 6e 20 61 75 78 20  op table in aux 
151d0 64 61 74 61 62 61 73 65 20 2a 2f 0a 29 5e 3c 2f  database */.)^</
151e0 70 72 65 3e 0a 0a 3c 70 3e 0a 20 20 5e 49 66 20  pre>..<p>.  ^If 
151f0 61 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 73  a schema name is
15200 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
15210 72 74 20 6f 66 20 61 6e 20 6f 62 6a 65 63 74 20  rt of an object 
15220 72 65 66 65 72 65 6e 63 65 2c 20 69 74 20 6d 75  reference, it mu
15230 73 74 20 62 65 0a 20 20 65 69 74 68 65 72 20 22  st be.  either "
15240 6d 61 69 6e 22 2c 20 6f 72 20 22 74 65 6d 70 22  main", or "temp"
15250 20 6f 72 20 74 68 65 20 73 63 68 65 6d 61 2d 6e   or the schema-n
15260 61 6d 65 20 6f 66 20 61 6e 20 61 74 74 61 63 68  ame of an attach
15270 65 64 20 64 61 74 61 62 61 73 65 2e 0a 20 20 5e  ed database..  ^
15280 4c 69 6b 65 20 6f 74 68 65 72 20 53 51 4c 20 69  Like other SQL i
15290 64 65 6e 74 69 66 69 65 72 73 2c 20 73 63 68 65  dentifiers, sche
152a0 6d 61 20 6e 61 6d 65 73 20 61 72 65 20 63 61 73  ma names are cas
152b0 65 2d 69 6e 73 65 6e 73 69 74 69 76 65 2e 0a 20  e-insensitive.. 
152c0 20 5e 49 66 20 61 20 73 63 68 65 6d 61 20 6e 61   ^If a schema na
152d0 6d 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  me is specified,
152e0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74 20   then only that 
152f0 6f 6e 65 20 73 63 68 65 6d 61 20 69 73 20 73 65  one schema is se
15300 61 72 63 68 65 64 20 66 6f 72 0a 20 20 74 68 65  arched for.  the
15310 20 6e 61 6d 65 64 20 6f 62 6a 65 63 74 2e 0a 0a   named object...
15320 3c 70 3e 0a 20 20 4d 6f 73 74 20 6f 62 6a 65 63  <p>.  Most objec
15330 74 20 72 65 66 65 72 65 6e 63 65 73 20 6d 61 79  t references may
15340 20 6f 6e 6c 79 20 72 65 73 6f 6c 76 65 20 74 6f   only resolve to
15350 20 61 20 73 70 65 63 69 66 69 63 20 74 79 70 65   a specific type
15360 20 6f 66 20 6f 62 6a 65 63 74 20 28 66 6f 72 0a   of object (for.
15370 20 20 65 78 61 6d 70 6c 65 20 61 20 72 65 66 65    example a refe
15380 72 65 6e 63 65 20 74 68 61 74 20 69 73 20 70 61  rence that is pa
15390 72 74 20 6f 66 20 61 20 44 52 4f 50 20 54 41 42  rt of a DROP TAB
153a0 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  LE statement may
153b0 20 6f 6e 6c 79 20 72 65 73 6f 6c 76 65 0a 20 20   only resolve.  
153c0 74 6f 20 61 20 74 61 62 6c 65 20 6f 62 6a 65 63  to a table objec
153d0 74 2c 20 6e 6f 74 20 61 6e 20 69 6e 64 65 78 2c  t, not an index,
153e0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
153f0 29 2e 20 48 6f 77 65 76 65 72 20 69 6e 20 73 6f  ). However in so
15400 6d 65 20 63 6f 6e 74 65 78 74 73 20 0a 20 20 28  me contexts .  (
15410 65 2e 67 2e 20 5b 52 45 49 4e 44 45 58 5d 29 20  e.g. [REINDEX]) 
15420 61 6e 20 6f 62 6a 65 63 74 20 72 65 66 65 72 65  an object refere
15430 6e 63 65 20 6d 61 79 20 62 65 20 72 65 73 6f 6c  nce may be resol
15440 76 65 20 74 6f 20 6d 6f 72 65 20 74 68 61 6e 20  ve to more than 
15450 6f 6e 65 20 74 79 70 65 0a 20 20 6f 66 20 6f 62  one type.  of ob
15460 6a 65 63 74 2e 20 5e 57 68 65 6e 20 73 65 61 72  ject. ^When sear
15470 63 68 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  ching database s
15480 63 68 65 6d 61 73 20 66 6f 72 20 61 20 6e 61 6d  chemas for a nam
15490 65 64 20 6f 62 6a 65 63 74 2c 20 6f 62 6a 65 63  ed object, objec
154a0 74 73 20 6f 66 0a 20 20 74 79 70 65 73 20 74 68  ts of.  types th
154b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  at cannot be use
154c0 64 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  d in the context
154d0 20 6f 66 20 74 68 65 20 72 65 66 65 72 65 6e 63   of the referenc
154e0 65 20 61 72 65 20 61 6c 77 61 79 73 20 0a 20 20  e are always .  
154f0 69 67 6e 6f 72 65 64 2e 0a 0a 3c 74 63 6c 3e 0a  ignored...<tcl>.
15500 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15510 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15520 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15530 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15540 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
15550 65 63 74 69 6f 6e 20 45 58 50 4c 41 49 4e 20 65  ection EXPLAIN e
15560 78 70 6c 61 69 6e 20 45 58 50 4c 41 49 4e 0a 0a  xplain EXPLAIN..
15570 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 73 71  BubbleDiagram sq
15580 6c 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  l-stmt.</tcl>..<
15590 70 3e 5e 41 6e 20 53 51 4c 20 73 74 61 74 65 6d  p>^An SQL statem
155a0 65 6e 74 20 63 61 6e 20 62 65 20 70 72 65 63 65  ent can be prece
155b0 64 65 64 20 62 79 20 74 68 65 20 6b 65 79 77 6f  ded by the keywo
155c0 72 64 20 22 45 58 50 4c 41 49 4e 22 20 6f 72 0a  rd "EXPLAIN" or.
155d0 62 79 20 74 68 65 20 70 68 72 61 73 65 20 22 45  by the phrase "E
155e0 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
155f0 4e 22 2e 20 20 5e 45 69 74 68 65 72 20 6d 6f 64  N".  ^Either mod
15600 69 66 69 63 61 74 69 6f 6e 20 63 61 75 73 65 73  ification causes
15610 20 74 68 65 0a 53 51 4c 20 73 74 61 74 65 6d 65   the.SQL stateme
15620 6e 74 20 74 6f 20 62 65 68 61 76 65 20 61 73 20  nt to behave as 
15630 61 20 71 75 65 72 79 20 61 6e 64 20 74 6f 20 72  a query and to r
15640 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
15650 6e 20 61 62 6f 75 74 0a 68 6f 77 20 74 68 65 20  n about.how the 
15660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
15670 75 6c 64 20 68 61 76 65 20 6f 70 65 72 61 74 65  uld have operate
15680 64 20 69 66 20 74 68 65 20 45 58 50 4c 41 49 4e  d if the EXPLAIN
15690 20 6b 65 79 77 6f 72 64 20 6f 72 0a 70 68 72 61   keyword or.phra
156a0 73 65 20 68 61 64 20 62 65 65 6e 20 6f 6d 69 74  se had been omit
156b0 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ted.</p>..<p>The
156c0 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 45 58 50   output from EXP
156d0 4c 41 49 4e 20 61 6e 64 20 45 58 50 4c 41 49 4e  LAIN and EXPLAIN
156e0 20 51 55 45 52 59 20 50 4c 41 4e 20 69 73 20 69   QUERY PLAN is i
156f0 6e 74 65 6e 64 65 64 20 66 6f 72 0a 69 6e 74 65  ntended for.inte
15700 72 61 63 74 69 76 65 20 61 6e 61 6c 79 73 69 73  ractive analysis
15710 20 61 6e 64 20 74 72 6f 75 62 6c 65 73 68 6f 6f   and troubleshoo
15720 74 69 6e 67 20 6f 6e 6c 79 2e 20 20 54 68 65 20  ting only.  The 
15730 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 0a  details of the .
15740 6f 75 74 70 75 74 20 66 6f 72 6d 61 74 20 61 72  output format ar
15750 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
15760 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  nge from one rel
15770 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
15780 6f 20 74 68 65 20 6e 65 78 74 2e 0a 41 70 70 6c  o the next..Appl
15790 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
157a0 6e 6f 74 20 75 73 65 20 45 58 50 4c 41 49 4e 20  not use EXPLAIN 
157b0 6f 72 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59  or EXPLAIN QUERY
157c0 20 50 4c 41 4e 20 73 69 6e 63 65 0a 74 68 65 69   PLAN since.thei
157d0 72 20 65 78 61 63 74 20 62 65 68 61 76 69 6f 72  r exact behavior
157e0 20 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64   is variable and
157f0 20 6f 6e 6c 79 20 70 61 72 74 69 61 6c 6c 79 20   only partially 
15800 64 6f 63 75 6d 65 6e 74 65 64 2e 3c 2f 70 3e 0a  documented.</p>.
15810 0a 3c 70 3e 5e 57 68 65 6e 20 74 68 65 20 45 58  .<p>^When the EX
15820 50 4c 41 49 4e 20 6b 65 79 77 6f 72 64 20 61 70  PLAIN keyword ap
15830 70 65 61 72 73 20 62 79 20 69 74 73 65 6c 66 20  pears by itself 
15840 69 74 20 63 61 75 73 65 73 20 74 68 65 20 73 74  it causes the st
15850 61 74 65 6d 65 6e 74 0a 74 6f 20 62 65 68 61 76  atement.to behav
15860 65 20 61 73 20 61 20 71 75 65 72 79 20 74 68 61  e as a query tha
15870 74 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  t returns the se
15880 71 75 65 6e 63 65 20 6f 66 20 0a 5b 76 69 72 74  quence of .[virt
15890 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
158a0 72 75 63 74 69 6f 6e 73 5d 20 69 74 20 77 6f 75  ructions] it wou
158b0 6c 64 20 68 61 76 65 20 75 73 65 64 20 74 6f 20  ld have used to 
158c0 65 78 65 63 75 74 65 20 74 68 65 20 63 6f 6d 6d  execute the comm
158d0 61 6e 64 20 68 61 64 0a 74 68 65 20 45 58 50 4c  and had.the EXPL
158e0 41 49 4e 20 6b 65 79 77 6f 72 64 20 6e 6f 74 20  AIN keyword not 
158f0 62 65 65 6e 20 70 72 65 73 65 6e 74 2e 20 5e 57  been present. ^W
15900 68 65 6e 20 74 68 65 20 45 58 50 4c 41 49 4e 20  hen the EXPLAIN 
15910 51 55 45 52 59 20 50 4c 41 4e 20 70 68 72 61 73  QUERY PLAN phras
15920 65 0a 61 70 70 65 61 72 73 2c 20 74 68 65 20 73  e.appears, the s
15930 74 61 74 65 6d 65 6e 74 20 72 65 74 75 72 6e 73  tatement returns
15940 20 68 69 67 68 2d 6c 65 76 65 6c 20 69 6e 66 6f   high-level info
15950 72 6d 61 74 69 6f 6e 20 72 65 67 61 72 64 69 6e  rmation regardin
15960 67 20 74 68 65 20 71 75 65 72 79 0a 70 6c 61 6e  g the query.plan
15970 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
15980 20 62 65 65 6e 20 75 73 65 64 2e 0a 0a 3c 70 3e   been used...<p>
15990 54 68 65 20 45 58 50 4c 41 49 4e 20 51 55 45 52  The EXPLAIN QUER
159a0 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 20 69  Y PLAN command i
159b0 73 20 64 65 73 63 72 69 62 65 64 20 69 6e 20 0a  s described in .
159c0 5b 65 78 70 6c 61 69 6e 20 71 75 65 72 79 20 70  [explain query p
159d0 6c 61 6e 7c 6d 6f 72 65 20 64 65 74 61 69 6c 20  lan|more detail 
159e0 68 65 72 65 5d 2e 0a 0a 3c 68 33 3e 45 58 50 4c  here]...<h3>EXPL
159f0 41 49 4e 20 6f 70 65 72 61 74 65 73 20 61 74 20  AIN operates at 
15a00 72 75 6e 2d 74 69 6d 65 2c 20 6e 6f 74 20 61 74  run-time, not at
15a10 20 70 72 65 70 61 72 65 2d 74 69 6d 65 3c 2f 68   prepare-time</h
15a20 33 3e 0a 0a 3c 70 3e 54 68 65 20 45 58 50 4c 41  3>..<p>The EXPLA
15a30 49 4e 20 61 6e 64 20 45 58 50 4c 41 49 4e 20 51  IN and EXPLAIN Q
15a40 55 45 52 59 20 50 4c 41 4e 20 70 72 65 66 69 78  UERY PLAN prefix
15a50 65 73 20 61 66 66 65 63 74 20 74 68 65 20 62 65  es affect the be
15a60 68 61 76 69 6f 72 20 6f 66 0a 72 75 6e 6e 69 6e  havior of.runnin
15a70 67 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  g a [prepared st
15a80 61 74 65 6d 65 6e 74 5d 20 75 73 69 6e 67 20 5b  atement] using [
15a90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
15aa0 20 20 54 68 65 20 70 72 6f 63 65 73 73 20 6f 66    The process of
15ab0 0a 67 65 6e 65 72 61 74 69 6e 67 20 61 20 6e 65  .generating a ne
15ac0 77 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  w prepared state
15ad0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
15ae0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15af0 72 20 73 69 6d 69 6c 61 72 0a 69 73 20 28 6d 6f  r similar.is (mo
15b00 73 74 6c 79 29 20 75 6e 61 66 66 65 63 74 65 64  stly) unaffected
15b10 20 62 79 20 45 58 50 4c 41 49 4e 2e 20 20 28 54   by EXPLAIN.  (T
15b20 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  he exception to 
15b30 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
15b40 74 65 6e 63 65 0a 69 73 20 74 68 61 74 20 73 6f  tence.is that so
15b50 6d 65 20 73 70 65 63 69 61 6c 20 6f 70 63 6f 64  me special opcod
15b60 65 73 20 75 73 65 64 20 62 79 20 45 58 50 4c 41  es used by EXPLA
15b70 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 61 72  IN QUERY PLAN ar
15b80 65 20 6f 6d 69 74 74 65 64 20 77 68 65 6e 0a 62  e omitted when.b
15b90 75 69 6c 64 69 6e 67 20 61 6e 20 45 58 50 4c 41  uilding an EXPLA
15ba0 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 70 72  IN QUERY PLAN pr
15bb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15bc0 2c 20 61 73 20 61 20 70 65 72 66 6f 72 6d 61 6e  , as a performan
15bd0 63 65 0a 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  ce.optimization.
15be0 29 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 61 6e 73  )..<p>This means
15bf0 20 74 68 61 74 20 61 63 74 69 6f 6e 73 20 74 68   that actions th
15c00 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 20  at occur during 
15c10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
15c20 29 20 61 72 65 0a 75 6e 61 66 66 65 63 74 65 64  ) are.unaffected
15c30 20 62 79 20 45 58 50 4c 41 49 4e 2e 0a 0a 3c 75   by EXPLAIN...<u
15c40 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 53 6f 6d 65 20  l>.<li><p>.Some 
15c50 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
15c60 6e 74 73 20 64 6f 20 74 68 65 69 72 20 77 6f 72  nts do their wor
15c70 6b 20 64 75 72 69 6e 67 20 73 71 6c 69 74 65 33  k during sqlite3
15c80 5f 70 72 65 70 61 72 65 28 29 20 72 61 74 68 65  _prepare() rathe
15c90 72 0a 74 68 61 6e 20 64 75 72 69 6e 67 20 73 71  r.than during sq
15ca0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
15cb0 68 6f 73 65 20 50 52 41 47 4d 41 20 73 74 61 74  hose PRAGMA stat
15cc0 65 6d 65 6e 74 73 20 61 72 65 20 75 6e 61 66 66  ements are unaff
15cd0 65 63 74 65 64 0a 62 79 20 45 58 50 4c 41 49 4e  ected.by EXPLAIN
15ce0 2e 20 20 54 68 65 79 20 6f 70 65 72 61 74 65 20  .  They operate 
15cf0 74 68 65 20 73 61 6d 65 20 77 69 74 68 20 6f 72  the same with or
15d00 20 77 69 74 68 6f 75 74 20 74 68 65 20 45 58 50   without the EXP
15d10 4c 41 49 4e 20 70 72 65 66 69 78 2e 0a 54 68 65  LAIN prefix..The
15d20 20 73 65 74 20 6f 66 20 50 52 41 47 4d 41 20 73   set of PRAGMA s
15d30 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
15d40 72 65 20 75 6e 61 66 66 65 63 74 65 64 20 62 79  re unaffected by
15d50 20 45 58 50 4c 41 49 4e 20 63 61 6e 20 76 61 72   EXPLAIN can var
15d60 79 0a 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  y.from one relea
15d70 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
15d80 20 53 6f 6d 65 20 50 52 41 47 4d 41 20 73 74 61   Some PRAGMA sta
15d90 74 65 6d 65 6e 74 73 20 6f 70 65 72 61 74 65 20  tements operate 
15da0 64 75 72 69 6e 67 0a 73 71 6c 69 74 65 33 5f 70  during.sqlite3_p
15db0 72 65 70 61 72 65 28 29 20 64 65 70 65 6e 64 69  repare() dependi
15dc0 6e 67 20 6f 6e 20 74 68 65 69 72 20 61 72 67 75  ng on their argu
15dd0 6d 65 6e 74 73 2e 20 20 46 6f 72 20 63 6f 6e 73  ments.  For cons
15de0 69 73 74 65 6e 74 0a 72 65 73 75 6c 74 73 2c 20  istent.results, 
15df0 61 76 6f 69 64 20 75 73 69 6e 67 20 45 58 50 4c  avoid using EXPL
15e00 41 49 4e 20 6f 6e 20 50 52 41 47 4d 41 20 73 74  AIN on PRAGMA st
15e10 61 74 65 6d 65 6e 74 73 2e 0a 0a 3c 6c 69 3e 3c  atements...<li><
15e20 70 3e 0a 54 68 65 20 5b 61 75 74 68 6f 72 69 7a  p>.The [authoriz
15e30 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
15e40 69 6e 76 6f 6b 65 64 20 72 65 67 61 72 64 6c 65  invoked regardle
15e50 73 73 20 6f 66 20 74 68 65 20 70 72 65 73 65 6e  ss of the presen
15e60 63 65 20 6f 66 0a 45 58 50 4c 41 49 4e 20 6f 72  ce of.EXPLAIN or
15e70 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50   EXPLAIN QUERY P
15e80 4c 41 4e 2e 0a 3c 2f 75 6c 3e 0a 3c 74 63 6c 3e  LAN..</ul>.<tcl>
15e90 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
15ea0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15eb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15ec0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15ed0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
15ee0 53 65 63 74 69 6f 6e 20 65 78 70 72 65 73 73 69  Section expressi
15ef0 6f 6e 20 65 78 70 72 20 7b 2a 65 78 70 72 65 73  on expr {*expres
15f00 73 69 6f 6e 20 7b 65 78 70 72 65 73 73 69 6f 6e  sion {expression
15f10 20 73 79 6e 74 61 78 7d 7d 0a 0a 52 65 63 75 72   syntax}}..Recur
15f20 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61  siveBubbleDiagra
15f30 6d 20 65 78 70 72 0a 3c 2f 74 63 6c 3e 0a 0a 3c  m expr.</tcl>..<
15f40 70 3e 54 68 69 73 20 73 65 63 74 69 6f 6e 20 69  p>This section i
15f50 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
15f60 20 74 68 65 20 6f 74 68 65 72 73 2e 20 20 4d 6f   the others.  Mo
15f70 73 74 20 6f 74 68 65 72 20 73 65 63 74 69 6f 6e  st other section
15f80 73 20 6f 66 0a 74 68 69 73 20 64 6f 63 75 6d 65  s of.this docume
15f90 6e 74 20 74 61 6c 6b 73 20 61 62 6f 75 74 20 61  nt talks about a
15fa0 20 70 61 72 74 69 63 75 6c 61 72 20 53 51 4c 20   particular SQL 
15fb0 63 6f 6d 6d 61 6e 64 2e 20 20 54 68 69 73 20 73  command.  This s
15fc0 65 63 74 69 6f 6e 20 64 6f 65 73 0a 6e 6f 74 20  ection does.not 
15fd0 74 61 6c 6b 20 61 62 6f 75 74 20 61 20 73 74 61  talk about a sta
15fe0 6e 64 61 6c 6f 6e 65 20 63 6f 6d 6d 61 6e 64 20  ndalone command 
15ff0 62 75 74 20 61 62 6f 75 74 20 22 65 78 70 72 65  but about "expre
16000 73 73 69 6f 6e 73 22 20 77 68 69 63 68 20 61 72  ssions" which ar
16010 65 20 0a 73 75 62 63 6f 6d 70 6f 6e 65 6e 74 73  e .subcomponents
16020 20 6f 66 20 6d 6f 73 74 20 6f 74 68 65 72 20 63   of most other c
16030 6f 6d 6d 61 6e 64 73 2e 3c 2f 70 3e 0a 0a 3c 74  ommands.</p>..<t
16040 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 62  cl>hd_fragment b
16050 69 6e 61 72 79 6f 70 73 20 7b 62 69 6e 61 72 79  inaryops {binary
16060 20 6f 70 65 72 61 74 6f 72 73 7d 3c 2f 74 63 6c   operators}</tcl
16070 3e 0a 3c 68 33 3e 4f 70 65 72 61 74 6f 72 73 3c  >.<h3>Operators<
16080 2f 68 33 3e 0a 3c 70 3e 5e 28 53 51 4c 69 74 65  /h3>.<p>^(SQLite
16090 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65   understands the
160a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 6e 61 72   following binar
160b0 79 20 6f 70 65 72 61 74 6f 72 73 2c 20 69 6e 20  y operators, in 
160c0 6f 72 64 65 72 20 66 72 6f 6d 0a 68 69 67 68 65  order from.highe
160d0 73 74 20 74 6f 20 6c 6f 77 65 73 74 20 70 72 65  st to lowest pre
160e0 63 65 64 65 6e 63 65 3a 3c 2f 70 3e 0a 0a 3c 62  cedence:</p>..<b
160f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16100 3c 66 6f 6e 74 20 63 6f 6c 6f 72 3d 22 23 32 63  <font color="#2c
16110 32 63 66 30 22 3e 3c 62 69 67 3e 7c 7c 0a 2a 20  2cf0"><big>||.* 
16120 20 20 20 2f 20 20 20 20 25 0a 2b 20 20 20 20 2d     /    %.+    -
16130 0a 26 6c 74 3b 26 6c 74 3b 20 20 20 26 67 74 3b  .&lt;&lt;   &gt;
16140 26 67 74 3b 20 20 20 26 61 6d 70 3b 20 20 20 20  &gt;   &amp;    
16150 7c 0a 26 6c 74 3b 20 20 20 20 26 6c 74 3b 3d 20  |.&lt;    &lt;= 
16160 20 20 26 67 74 3b 20 20 20 20 26 67 74 3b 3d 0a    &gt;    &gt;=.
16170 3d 20 20 20 20 3d 3d 20 20 20 21 3d 20 20 20 26  =    ==   !=   &
16180 6c 74 3b 26 67 74 3b 20 20 20 3c 2f 62 69 67 3e  lt;&gt;   </big>
16190 49 53 20 20 20 49 53 20 4e 4f 54 20 20 20 49 4e  IS   IS NOT   IN
161a0 20 20 20 4c 49 4b 45 20 20 20 47 4c 4f 42 20 20     LIKE   GLOB  
161b0 20 4d 41 54 43 48 20 20 20 52 45 47 45 58 50 0a   MATCH   REGEXP.
161c0 41 4e 44 20 20 20 0a 4f 52 3c 2f 66 6f 6e 74 3e  AND   .OR</font>
161d0 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
161e0 6f 74 65 3e 29 5e 0a 0a 3c 70 3e 5e 28 53 75 70  ote>)^..<p>^(Sup
161f0 70 6f 72 74 65 64 20 75 6e 61 72 79 20 70 72 65  ported unary pre
16200 66 69 78 20 6f 70 65 72 61 74 6f 72 73 20 61 72  fix operators ar
16210 65 20 74 68 65 73 65 3a 3c 2f 70 3e 0a 0a 3c 62  e these:</p>..<b
16220 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16230 3c 66 6f 6e 74 20 63 6f 6c 6f 72 3d 22 23 32 63  <font color="#2c
16240 32 63 66 30 22 3e 3c 62 69 67 3e 2d 20 20 20 20  2cf0"><big>-    
16250 2b 20 20 20 20 7e 20 20 20 20 4e 4f 54 3c 2f 62  +    ~    NOT</b
16260 69 67 3e 3c 2f 66 6f 6e 74 3e 0a 3c 2f 70 72 65  ig></font>.</pre
16270 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
16280 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
16290 6e 74 20 63 6f 6c 6c 61 74 65 6f 70 20 7b 43 4f  nt collateop {CO
162a0 4c 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 7d 3c  LLATE operator}<
162b0 2f 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 43 4f  /tcl>.<p>^The CO
162c0 4c 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 20 69  LLATE operator i
162d0 73 20 61 20 75 6e 61 72 79 20 70 6f 73 74 66 69  s a unary postfi
162e0 78 0a 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20  x.operator that 
162f0 61 73 73 69 67 6e 73 20 61 20 5b 63 6f 6c 6c 61  assigns a [colla
16300 74 69 6e 67 20 73 65 71 75 65 6e 63 65 5d 20 74  ting sequence] t
16310 6f 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 2e  o an expression.
16320 0a 5e 54 68 65 20 43 4f 4c 4c 41 54 45 20 6f 70  .^The COLLATE op
16330 65 72 61 74 6f 72 20 68 61 73 20 61 20 68 69 67  erator has a hig
16340 68 65 72 20 70 72 65 63 65 64 65 6e 63 65 20 28  her precedence (
16350 62 69 6e 64 73 20 6d 6f 72 65 20 74 69 67 68 74  binds more tight
16360 6c 79 29 20 74 68 61 6e 20 61 6e 79 0a 62 69 6e  ly) than any.bin
16370 61 72 79 20 6f 70 65 72 61 74 6f 72 20 61 6e 64  ary operator and
16380 20 61 6e 79 20 75 6e 61 72 79 20 70 72 65 66 69   any unary prefi
16390 78 20 6f 70 65 72 61 74 6f 72 20 65 78 63 65 70  x operator excep
163a0 74 20 22 7e 22 2e 0a 28 43 4f 4c 4c 41 54 45 20  t "~"..(COLLATE 
163b0 61 6e 64 20 22 7e 22 20 61 72 65 20 61 73 73 6f  and "~" are asso
163c0 63 69 61 74 69 76 65 20 73 6f 20 74 68 65 69 72  ciative so their
163d0 20 62 69 6e 64 69 6e 67 20 6f 72 64 65 72 20 64   binding order d
163e0 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 2e 29  oes not matter.)
163f0 0a 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  .^The collating 
16400 73 65 71 75 65 6e 63 65 20 73 65 74 20 62 79 20  sequence set by 
16410 74 68 65 20 43 4f 4c 4c 41 54 45 20 6f 70 65 72  the COLLATE oper
16420 61 74 6f 72 20 6f 76 65 72 72 69 64 65 73 20 74  ator overrides t
16430 68 65 0a 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he.collating seq
16440 75 65 6e 63 65 20 64 65 74 65 72 6d 69 6e 65 64  uence determined
16450 20 62 79 20 74 68 65 20 43 4f 4c 4c 41 54 45 20   by the COLLATE 
16460 63 6c 61 75 73 65 20 69 6e 20 61 20 74 61 62 6c  clause in a tabl
16470 65 0a 5b 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69  e.[column defini
16480 74 69 6f 6e 5d 2e 0a 53 65 65 20 74 68 65 20 5b  tion]..See the [
16490 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
164a0 63 65 7c 20 64 65 74 61 69 6c 65 64 20 64 69 73  ce| detailed dis
164b0 63 75 73 73 69 6f 6e 20 6f 6e 20 63 6f 6c 6c 61  cussion on colla
164c0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 73 5d 0a  ting sequences].
164d0 69 6e 20 74 68 65 20 5b 64 61 74 61 74 79 70 65  in the [datatype
164e0 20 7c 20 44 61 74 61 74 79 70 65 20 49 6e 20 53   | Datatype In S
164f0 51 4c 69 74 65 33 5d 20 64 6f 63 75 6d 65 6e 74  QLite3] document
16500 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
16510 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 3c 2f 70  information..</p
16520 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 70 75 74 73 20  >..<tcl>hd_puts 
16530 22 0a 3c 70 3e 5e 54 68 65 20 75 6e 61 72 79 20  ".<p>^The unary 
16540 6f 70 65 72 61 74 6f 72 20 5b 4f 70 65 72 61 74  operator [Operat
16550 6f 72 20 2b 5d 20 69 73 20 61 20 6e 6f 2d 6f 70  or +] is a no-op
16560 2e 20 20 5e 49 74 20 63 61 6e 20 62 65 20 61 70  .  ^It can be ap
16570 70 6c 69 65 64 0a 74 6f 20 73 74 72 69 6e 67 73  plied.to strings
16580 2c 20 6e 75 6d 62 65 72 73 2c 20 62 6c 6f 62 73  , numbers, blobs
16590 20 6f 72 20 4e 55 4c 4c 20 61 6e 64 20 69 74 20   or NULL and it 
165a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
165b0 20 72 65 73 75 6c 74 0a 77 69 74 68 20 74 68 65   result.with the
165c0 20 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74   same value as t
165d0 68 65 20 6f 70 65 72 61 6e 64 2e 3c 2f 70 3e 22  he operand.</p>"
165e0 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 4e 6f 74 65 20  </tcl>..<p>Note 
165f0 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 74  that there are t
16600 77 6f 20 76 61 72 69 61 74 69 6f 6e 73 20 6f 66  wo variations of
16610 20 74 68 65 20 65 71 75 61 6c 73 20 61 6e 64 20   the equals and 
16620 6e 6f 74 20 65 71 75 61 6c 73 0a 6f 70 65 72 61  not equals.opera
16630 74 6f 72 73 2e 20 20 5e 45 71 75 61 6c 73 20 63  tors.  ^Equals c
16640 61 6e 20 62 65 20 65 69 74 68 65 72 0a 0a 3c 74  an be either..<t
16650 63 6c 3e 0a 68 64 5f 70 75 74 73 20 22 5b 4f 70  cl>.hd_puts "[Op
16660 65 72 61 74 6f 72 20 3d 5d 20 6f 72 20 5b 4f 70  erator =] or [Op
16670 65 72 61 74 6f 72 20 3d 3d 5d 2e 0a 5e 54 68 65  erator ==]..^The
16680 20 6e 6f 6e 2d 65 71 75 61 6c 73 20 6f 70 65 72   non-equals oper
16690 61 74 6f 72 20 63 61 6e 20 62 65 20 65 69 74 68  ator can be eith
166a0 65 72 0a 5b 4f 70 65 72 61 74 6f 72 20 21 3d 5d  er.[Operator !=]
166b0 20 6f 72 20 5b 4f 70 65 72 61 74 6f 72 20 7b 26   or [Operator {&
166c0 6c 74 3b 26 67 74 3b 7d 5d 2e 0a 5e 54 68 65 20  lt;&gt;}]..^The 
166d0 5b 4f 70 65 72 61 74 6f 72 20 7c 7c 5d 20 6f 70  [Operator ||] op
166e0 65 72 61 74 6f 72 20 69 73 20 5c 22 63 6f 6e 63  erator is \"conc
166f0 61 74 65 6e 61 74 65 5c 22 20 2d 20 69 74 20 6a  atenate\" - it j
16700 6f 69 6e 73 20 74 6f 67 65 74 68 65 72 0a 74 68  oins together.th
16710 65 20 74 77 6f 20 73 74 72 69 6e 67 73 20 6f 66  e two strings of
16720 20 69 74 73 20 6f 70 65 72 61 6e 64 73 2e 0a 5e   its operands..^
16730 54 68 65 20 6f 70 65 72 61 74 6f 72 20 5b 4f 70  The operator [Op
16740 65 72 61 74 6f 72 20 25 5d 20 6f 75 74 70 75 74  erator %] output
16750 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 76 61  s the integer va
16760 6c 75 65 20 6f 66 20 69 74 73 20 6c 65 66 74 20  lue of its left 
16770 0a 6f 70 65 72 61 6e 64 20 6d 6f 64 75 6c 6f 20  .operand modulo 
16780 69 74 73 20 72 69 67 68 74 20 6f 70 65 72 61 6e  its right operan
16790 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
167a0 64 73 2c 20 74 68 65 0a 6f 70 65 72 61 74 6f 72  ds, the.operator
167b0 20 5b 4f 70 65 72 61 74 6f 72 20 25 5d 20 77 6f   [Operator %] wo
167c0 72 6b 73 20 69 6e 20 53 51 4c 69 74 65 20 74 68  rks in SQLite th
167d0 65 20 73 61 6d 65 20 61 73 20 69 74 20 64 6f 65  e same as it doe
167e0 73 0a 69 6e 20 41 4e 53 49 2d 43 2e 3c 2f 70 3e  s.in ANSI-C.</p>
167f0 0a 0a 3c 70 3e 5e 54 68 65 20 72 65 73 75 6c 74  ..<p>^The result
16800 20 6f 66 20 61 6e 79 20 62 69 6e 61 72 79 20 6f   of any binary o
16810 70 65 72 61 74 6f 72 20 69 73 20 65 69 74 68 65  perator is eithe
16820 72 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  r a numeric valu
16830 65 20 6f 72 20 0a 4e 55 4c 4c 2c 20 65 78 63 65  e or .NULL, exce
16840 70 74 20 66 6f 72 20 74 68 65 20 5b 4f 70 65 72  pt for the [Oper
16850 61 74 6f 72 20 7c 7c 5d 20 63 6f 6e 63 61 74 65  ator ||] concate
16860 6e 61 74 69 6f 6e 20 6f 70 65 72 61 74 6f 72 20  nation operator 
16870 77 68 69 63 68 20 61 6c 77 61 79 73 20 0a 65 76  which always .ev
16880 61 6c 75 61 74 65 73 20 74 6f 20 65 69 74 68 65  aluates to eithe
16890 72 20 4e 55 4c 4c 20 6f 72 20 61 20 74 65 78 74  r NULL or a text
168a0 20 76 61 6c 75 65 2e 3c 2f 70 3e 22 0a 0a 68 64   value.</p>"..hd
168b0 5f 66 72 61 67 6d 65 6e 74 20 7b 69 73 69 73 6e  _fragment {isisn
168c0 6f 74 7d 20 7b 49 53 20 6f 70 65 72 61 74 6f 72  ot} {IS operator
168d0 7d 20 7b 49 53 20 4e 4f 54 20 6f 70 65 72 61 74  } {IS NOT operat
168e0 6f 72 7d 0a 0a 68 64 5f 70 75 74 73 20 22 3c 70  or}..hd_puts "<p
168f0 3e 5e 54 68 65 20 5b 4f 70 65 72 61 74 6f 72 20  >^The [Operator 
16900 49 53 5d 20 61 6e 64 20 5b 4f 70 65 72 61 74 6f  IS] and [Operato
16910 72 20 7b 49 53 20 4e 4f 54 7d 5d 20 6f 70 65 72  r {IS NOT}] oper
16920 61 74 6f 72 73 20 77 6f 72 6b 0a 6c 69 6b 65 20  ators work.like 
16930 5b 4f 70 65 72 61 74 6f 72 20 3d 5d 20 61 6e 64  [Operator =] and
16940 20 5b 4f 70 65 72 61 74 6f 72 20 21 3d 5d 20 65   [Operator !=] e
16950 78 63 65 70 74 20 77 68 65 6e 20 6f 6e 65 20 6f  xcept when one o
16960 72 20 62 6f 74 68 20 6f 66 20 74 68 65 0a 6f 70  r both of the.op
16970 65 72 61 6e 64 73 20 61 72 65 20 4e 55 4c 4c 2e  erands are NULL.
16980 20 5e 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20   ^In this case, 
16990 69 66 20 62 6f 74 68 20 6f 70 65 72 61 6e 64 73  if both operands
169a0 20 61 72 65 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   are NULL, then 
169b0 74 68 65 0a 49 53 20 6f 70 65 72 61 74 6f 72 20  the.IS operator 
169c0 65 76 61 6c 75 61 74 65 73 20 74 6f 20 31 20 28  evaluates to 1 (
169d0 74 72 75 65 29 20 61 6e 64 20 74 68 65 20 49 53  true) and the IS
169e0 20 4e 4f 54 20 6f 70 65 72 61 74 6f 72 20 65 76   NOT operator ev
169f0 61 6c 75 61 74 65 73 0a 74 6f 20 30 20 28 66 61  aluates.to 0 (fa
16a00 6c 73 65 29 2e 20 5e 49 66 20 6f 6e 65 20 6f 70  lse). ^If one op
16a10 65 72 61 6e 64 20 69 73 20 4e 55 4c 4c 20 61 6e  erand is NULL an
16a20 64 20 74 68 65 20 6f 74 68 65 72 20 69 73 20 6e  d the other is n
16a30 6f 74 2c 20 74 68 65 6e 20 74 68 65 0a 49 53 20  ot, then the.IS 
16a40 6f 70 65 72 61 74 6f 72 20 65 76 61 6c 75 61 74  operator evaluat
16a50 65 73 20 74 6f 20 30 20 28 66 61 6c 73 65 29 20  es to 0 (false) 
16a60 61 6e 64 20 74 68 65 20 49 53 20 4e 4f 54 20 6f  and the IS NOT o
16a70 70 65 72 61 74 6f 72 20 69 73 20 31 20 28 74 72  perator is 1 (tr
16a80 75 65 29 2e 0a 5e 49 74 20 69 73 20 6e 6f 74 20  ue)..^It is not 
16a90 70 6f 73 73 69 62 6c 65 20 66 6f 72 20 61 6e 20  possible for an 
16aa0 49 53 20 6f 72 20 49 53 20 4e 4f 54 20 65 78 70  IS or IS NOT exp
16ab0 72 65 73 73 69 6f 6e 20 74 6f 20 65 76 61 6c 75  ression to evalu
16ac0 61 74 65 20 74 6f 20 4e 55 4c 4c 2e 0a 5e 4f 70  ate to NULL..^Op
16ad0 65 72 61 74 6f 72 73 20 5b 4f 70 65 72 61 74 6f  erators [Operato
16ae0 72 20 49 53 5d 20 61 6e 64 20 5b 4f 70 65 72 61  r IS] and [Opera
16af0 74 6f 72 20 7b 49 53 20 4e 4f 54 7d 5d 20 68 61  tor {IS NOT}] ha
16b00 76 65 20 74 68 65 20 73 61 6d 65 20 0a 70 72 65  ve the same .pre
16b10 63 65 64 65 6e 63 65 20 61 73 20 5b 4f 70 65 72  cedence as [Oper
16b20 61 74 6f 72 20 3d 5d 2e 22 0a 0a 3c 74 63 6c 3e  ator =]."..<tcl>
16b30 68 64 5f 66 72 61 67 6d 65 6e 74 20 6c 69 74 76  hd_fragment litv
16b40 61 6c 75 65 20 7b 6c 69 74 65 72 61 6c 20 76 61  alue {literal va
16b50 6c 75 65 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 4c  lue}</tcl>.<h3>L
16b60 69 74 65 72 61 6c 20 56 61 6c 75 65 73 20 28 43  iteral Values (C
16b70 6f 6e 73 74 61 6e 74 73 29 3c 2f 68 33 3e 0a 3c  onstants)</h3>.<
16b80 70 3e 0a 41 20 6c 69 74 65 72 61 6c 20 76 61 6c  p>.A literal val
16b90 75 65 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ue represents a 
16ba0 63 6f 6e 73 74 61 6e 74 2e 0a 5e 4c 69 74 65 72  constant..^Liter
16bb0 61 6c 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  al values may be
16bc0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
16bd0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
16be0 73 2c 20 73 74 72 69 6e 67 73 2c 0a 42 4c 4f 42  s, strings,.BLOB
16bf0 73 2c 20 6f 72 20 4e 55 4c 4c 73 2e 0a 3c 70 3e  s, or NULLs..<p>
16c00 0a 54 68 65 20 73 79 6e 74 61 78 20 66 6f 72 20  .The syntax for 
16c10 69 6e 74 65 67 65 72 20 61 6e 64 20 66 6c 6f 61  integer and floa
16c20 74 69 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72  ting point liter
16c30 61 6c 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  als (collectivel
16c40 79 0a 22 6e 75 6d 65 72 69 63 20 6c 69 74 65 72  y."numeric liter
16c50 61 6c 73 22 29 20 69 73 20 73 68 6f 77 6e 20 62  als") is shown b
16c60 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
16c70 64 69 61 67 72 61 6d 3a 3c 2f 70 3e 0a 0a 3c 74  diagram:</p>..<t
16c80 63 6c 3e 42 75 62 62 6c 65 44 69 61 67 72 61 6d  cl>BubbleDiagram
16c90 20 6e 75 6d 65 72 69 63 2d 6c 69 74 65 72 61 6c   numeric-literal
16ca0 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 5e 28 49 66  </tcl>..<p>.^(If
16cb0 20 61 20 6e 75 6d 65 72 69 63 20 6c 69 74 65 72   a numeric liter
16cc0 61 6c 20 68 61 73 20 61 20 64 65 63 69 6d 61 6c  al has a decimal
16cd0 20 70 6f 69 6e 74 20 6f 72 20 61 6e 20 65 78 70   point or an exp
16ce0 6f 6e 65 6e 74 69 61 74 69 6f 6e 0a 63 6c 61 75  onentiation.clau
16cf0 73 65 20 6f 72 20 69 66 20 69 74 73 20 6d 61 67  se or if its mag
16d00 6e 69 74 75 64 65 20 69 73 20 6c 65 73 73 20 74  nitude is less t
16d10 68 61 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  han -92233720368
16d20 35 34 37 37 35 38 30 38 20 6f 72 0a 67 72 65 61  54775808 or.grea
16d30 74 65 72 20 74 68 61 6e 20 39 32 32 33 33 37 32  ter than 9223372
16d40 30 33 36 38 35 34 37 37 35 38 30 37 2c 20 74 68  036854775807, th
16d50 65 6e 20 69 74 20 69 73 20 61 20 66 6c 6f 61 74  en it is a float
16d60 69 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72 61  ing point litera
16d70 6c 2e 0a 4f 74 68 65 72 77 69 73 65 20 69 73 20  l..Otherwise is 
16d80 69 74 20 69 73 20 61 6e 20 20 69 6e 74 65 67 65  it is an  intege
16d90 72 20 6c 69 74 65 72 61 6c 2e 29 5e 0a 5e 54 68  r literal.)^.^Th
16da0 65 20 22 45 22 20 63 68 61 72 61 63 74 65 72 20  e "E" character 
16db0 74 68 61 74 20 62 65 67 69 6e 73 20 74 68 65 20  that begins the 
16dc0 65 78 70 6f 6e 65 6e 74 69 61 74 69 6f 6e 0a 63  exponentiation.c
16dd0 6c 61 75 73 65 20 6f 66 20 61 20 66 6c 6f 61 74  lause of a float
16de0 69 6e 67 20 70 6f 69 6e 74 20 6c 69 74 65 72 61  ing point litera
16df0 6c 20 63 61 6e 20 62 65 20 65 69 74 68 65 72 20  l can be either 
16e00 75 70 70 65 72 20 6f 72 20 6c 6f 77 65 72 20 63  upper or lower c
16e10 61 73 65 2e 0a 5e 28 54 68 65 20 22 2e 22 20 63  ase..^(The "." c
16e20 68 61 72 61 63 74 65 72 20 69 73 20 61 6c 77 61  haracter is alwa
16e30 79 73 20 75 73 65 64 20 0a 61 73 20 74 68 65 20  ys used .as the 
16e40 64 65 63 69 6d 61 6c 20 70 6f 69 6e 74 20 65 76  decimal point ev
16e50 65 6e 20 69 66 20 74 68 65 20 6c 6f 63 61 6c 65  en if the locale
16e60 20 73 65 74 74 69 6e 67 20 73 70 65 63 69 66 69   setting specifi
16e70 65 73 20 22 2c 22 20 66 6f 72 0a 74 68 69 73 20  es "," for.this 
16e80 72 6f 6c 65 20 2d 20 74 68 65 20 75 73 65 20 6f  role - the use o
16e90 66 20 22 2c 22 20 66 6f 72 20 74 68 65 20 64 65  f "," for the de
16ea0 63 69 6d 61 6c 20 70 6f 69 6e 74 20 77 6f 75 6c  cimal point woul
16eb0 64 20 72 65 73 75 6c 74 20 69 6e 0a 73 79 6e 74  d result in.synt
16ec0 61 63 74 69 63 20 61 6d 62 69 67 75 69 74 79 2e  actic ambiguity.
16ed0 29 5e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  )^..<tcl>hd_frag
16ee0 6d 65 6e 74 20 68 65 78 69 6e 74 20 7b 68 65 78  ment hexint {hex
16ef0 61 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72  adecimal integer
16f00 20 6c 69 74 65 72 61 6c 73 7d 20 7b 68 65 78 61   literals} {hexa
16f10 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 73  decimal integers
16f20 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 48 65 78 61  }</tcl>.<p>^Hexa
16f30 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 20  decimal integer 
16f40 6c 69 74 65 72 61 6c 73 20 66 6f 6c 6c 6f 77 20  literals follow 
16f50 74 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 6e  the C-language n
16f60 6f 74 61 74 69 6f 6e 20 6f 66 0a 22 30 78 22 20  otation of."0x" 
16f70 6f 72 20 22 30 58 22 20 66 6f 6c 6c 6f 77 65 64  or "0X" followed
16f80 20 62 79 20 68 65 78 61 64 65 63 69 6d 61 6c 20   by hexadecimal 
16f90 64 69 67 69 74 73 2e 0a 5e 46 6f 72 20 65 78 61  digits..^For exa
16fa0 6d 70 6c 65 2c 20 30 78 31 32 33 34 20 6d 65 61  mple, 0x1234 mea
16fb0 6e 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 34  ns the same as 4
16fc0 36 36 30 0a 61 6e 64 20 30 78 38 30 30 30 30 30  660.and 0x800000
16fd0 30 30 30 30 30 30 30 30 30 30 20 6d 65 61 6e 73  0000000000 means
16fe0 20 74 68 65 20 73 61 6d 65 20 61 73 20 2d 39 32   the same as -92
16ff0 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
17000 38 2e 0a 20 5e 28 48 65 78 61 64 65 63 69 6d 61  8.. ^(Hexadecima
17010 6c 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  l integer litera
17020 6c 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ls are interpret
17030 65 64 20 61 73 20 36 34 2d 62 69 74 0a 74 77 6f  ed as 64-bit.two
17040 27 73 2d 63 6f 6d 70 6c 65 6d 65 6e 74 20 69 6e  's-complement in
17050 74 65 67 65 72 73 20 61 6e 64 20 61 72 65 20 74  tegers and are t
17060 68 75 73 20 6c 69 6d 69 74 65 64 0a 74 6f 20 73  hus limited.to s
17070 69 78 74 65 65 6e 20 73 69 67 6e 69 66 69 63 61  ixteen significa
17080 6e 74 20 64 69 67 69 74 73 20 6f 66 20 70 72 65  nt digits of pre
17090 63 69 73 69 6f 6e 2e 29 5e 0a 53 75 70 70 6f 72  cision.)^.Suppor
170a0 74 20 66 6f 72 20 68 65 78 61 64 65 63 69 6d 61  t for hexadecima
170b0 6c 20 69 6e 74 65 67 65 72 73 20 77 61 73 20 61  l integers was a
170c0 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 0a 76  dded to SQLite.v
170d0 65 72 73 69 6f 6e 20 33 2e 38 2e 36 20 28 5b 64  ersion 3.8.6 ([d
170e0 61 74 65 6f 66 3a 33 2e 38 2e 36 5d 29 2e 0a 5e  ateof:3.8.6])..^
170f0 46 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  For backwards co
17100 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 74 68 65  mpatibility, the
17110 20 22 30 78 22 20 68 65 78 61 64 65 63 69 6d 61   "0x" hexadecima
17120 6c 20 69 6e 74 65 67 65 72 0a 6e 6f 74 61 74 69  l integer.notati
17130 6f 6e 20 69 73 20 6f 6e 6c 79 20 75 6e 64 65 72  on is only under
17140 73 74 6f 6f 64 20 62 79 20 74 68 65 20 53 51 4c  stood by the SQL
17150 20 6c 61 6e 67 75 61 67 65 20 70 61 72 73 65 72   language parser
17160 2c 20 6e 6f 74 20 62 79 20 74 68 65 0a 74 79 70  , not by the.typ
17170 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 72 6f  e conversions ro
17180 75 74 69 6e 65 73 2e 0a 5e 28 53 74 72 69 6e 67  utines..^(String
17190 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 0a   variables that.
171a0 63 6f 6e 74 61 69 6e 20 74 65 78 74 20 66 6f 72  contain text for
171b0 6d 61 74 74 65 64 20 6c 69 6b 65 20 68 65 78 61  matted like hexa
171c0 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 73  decimal integers
171d0 20 61 72 65 20 6e 6f 74 0a 69 6e 74 65 72 70 72   are not.interpr
171e0 65 74 65 64 20 61 73 20 68 65 78 61 64 65 63 69  eted as hexadeci
171f0 6d 61 6c 20 69 6e 74 65 67 65 72 73 20 77 68 65  mal integers whe
17200 6e 20 63 6f 65 72 63 69 6e 67 20 74 68 65 20 73  n coercing the s
17210 74 72 69 6e 67 20 76 61 6c 75 65 0a 69 6e 74 6f  tring value.into
17220 20 61 6e 20 69 6e 74 65 67 65 72 20 64 75 65 20   an integer due 
17230 74 6f 20 61 20 5b 43 41 53 54 20 65 78 70 72 65  to a [CAST expre
17240 73 73 69 6f 6e 5d 20 6f 72 20 66 6f 72 20 61 20  ssion] or for a 
17250 5b 63 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79  [column affinity
17260 5d 0a 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  ].transformation
17270 20 6f 72 20 70 72 69 6f 72 20 74 6f 20 70 65 72   or prior to per
17280 66 6f 72 6d 69 6e 67 20 61 20 6e 75 6d 65 72 69  forming a numeri
17290 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 66  c operation or f
172a0 6f 72 0a 61 6e 79 20 6f 74 68 65 72 20 72 75 6e  or.any other run
172b0 2d 74 69 6d 65 20 63 6f 6e 76 65 72 73 69 6f 6e  -time conversion
172c0 73 2e 29 5e 20 20 5e 28 57 68 65 6e 20 63 6f 65  s.)^  ^(When coe
172d0 72 63 69 6e 67 20 61 0a 73 74 72 69 6e 67 20 76  rcing a.string v
172e0 61 6c 75 65 20 69 6e 20 74 68 65 20 66 6f 72 6d  alue in the form
172f0 61 74 20 6f 66 20 61 20 68 65 78 61 64 65 63 69  at of a hexadeci
17300 6d 61 6c 20 69 6e 74 65 67 65 72 20 69 6e 74 6f  mal integer into
17310 20 61 6e 20 69 6e 74 65 67 65 72 0a 76 61 6c 75   an integer.valu
17320 65 2c 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  e, the conversio
17330 6e 20 70 72 6f 63 65 73 73 20 73 74 6f 70 73 20  n process stops 
17340 77 68 65 6e 20 74 68 65 20 27 78 27 20 63 68 61  when the 'x' cha
17350 72 61 63 74 65 72 20 69 73 20 73 65 65 6e 0a 73  racter is seen.s
17360 6f 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  o the resulting 
17370 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 69 73  integer value is
17380 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 29 5e 0a   always zero.)^.
17390 5e 28 53 51 4c 69 74 65 20 6f 6e 6c 79 20 75 6e  ^(SQLite only un
173a0 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 68 65  derstands the he
173b0 78 61 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65  xadecimal intege
173c0 72 20 6e 6f 74 61 74 69 6f 6e 20 77 68 65 6e 20  r notation when 
173d0 69 74 0a 61 70 70 65 61 72 73 20 69 6e 20 74 68  it.appears in th
173e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
173f0 74 65 78 74 2c 20 6e 6f 74 20 77 68 65 6e 20 69  text, not when i
17400 74 20 61 70 70 65 61 72 73 20 61 73 0a 70 61 72  t appears as.par
17410 74 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  t of the content
17420 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
17430 2e 29 5e 0a 0a 3c 70 3e 20 5e 41 20 73 74 72 69  .)^..<p> ^A stri
17440 6e 67 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 66  ng constant is f
17450 6f 72 6d 65 64 20 62 79 20 65 6e 63 6c 6f 73 69  ormed by enclosi
17460 6e 67 20 74 68 65 0a 73 74 72 69 6e 67 20 69 6e  ng the.string in
17470 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 28   single quotes (
17480 27 29 2e 20 20 5e 41 20 73 69 6e 67 6c 65 20 71  ').  ^A single q
17490 75 6f 74 65 20 77 69 74 68 69 6e 20 74 68 65 20  uote within the 
174a0 73 74 72 69 6e 67 20 63 61 6e 0a 62 65 20 65 6e  string can.be en
174b0 63 6f 64 65 64 20 62 79 20 70 75 74 74 69 6e 67  coded by putting
174c0 20 74 77 6f 20 73 69 6e 67 6c 65 20 71 75 6f 74   two single quot
174d0 65 73 20 69 6e 20 61 20 72 6f 77 20 2d 20 61 73  es in a row - as
174e0 20 69 6e 20 50 61 73 63 61 6c 2e 0a 43 2d 73 74   in Pascal..C-st
174f0 79 6c 65 20 65 73 63 61 70 65 73 20 75 73 69 6e  yle escapes usin
17500 67 20 74 68 65 20 62 61 63 6b 73 6c 61 73 68 20  g the backslash 
17510 63 68 61 72 61 63 74 65 72 20 61 72 65 20 6e 6f  character are no
17520 74 20 73 75 70 70 6f 72 74 65 64 20 62 65 63 61  t supported beca
17530 75 73 65 0a 74 68 65 79 20 61 72 65 20 6e 6f 74  use.they are not
17540 20 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 0a 0a   standard SQL...
17550 3c 70 3e 20 5e 42 4c 4f 42 20 6c 69 74 65 72 61  <p> ^BLOB litera
17560 6c 73 20 61 72 65 20 73 74 72 69 6e 67 20 6c 69  ls are string li
17570 74 65 72 61 6c 73 20 63 6f 6e 74 61 69 6e 69 6e  terals containin
17580 67 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 61  g hexadecimal da
17590 74 61 20 61 6e 64 0a 70 72 65 63 65 64 65 64 20  ta and.preceded 
175a0 62 79 20 61 20 73 69 6e 67 6c 65 20 22 78 22 20  by a single "x" 
175b0 6f 72 20 22 58 22 20 63 68 61 72 61 63 74 65 72  or "X" character
175c0 2e 20 20 5e 28 45 78 61 6d 70 6c 65 3a 20 58 27  .  ^(Example: X'
175d0 35 33 35 31 34 43 36 39 37 34 36 35 27 29 5e 0a  53514C697465')^.
175e0 0a 3c 70 3e 0a 5e 41 20 6c 69 74 65 72 61 6c 20  .<p>.^A literal 
175f0 76 61 6c 75 65 20 63 61 6e 20 61 6c 73 6f 20 62  value can also b
17600 65 20 74 68 65 20 74 6f 6b 65 6e 20 22 4e 55 4c  e the token "NUL
17610 4c 22 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  L"..</p>..<tcl>h
17620 64 5f 66 72 61 67 6d 65 6e 74 20 76 61 72 70 61  d_fragment varpa
17630 72 61 6d 20 70 61 72 61 6d 65 74 65 72 20 70 61  ram parameter pa
17640 72 61 6d 65 74 65 72 73 20 7b 62 6f 75 6e 64 20  rameters {bound 
17650 70 61 72 61 6d 65 74 65 72 7d 20 7b 62 6f 75 6e  parameter} {boun
17660 64 20 70 61 72 61 6d 65 74 65 72 73 7d 3c 2f 74  d parameters}</t
17670 63 6c 3e 0a 3c 68 33 3e 50 61 72 61 6d 65 74 65  cl>.<h3>Paramete
17680 72 73 3c 2f 68 33 3e 0a 3c 70 3e 0a 41 20 22 76  rs</h3>.<p>.A "v
17690 61 72 69 61 62 6c 65 22 20 6f 72 20 22 70 61 72  ariable" or "par
176a0 61 6d 65 74 65 72 22 20 74 6f 6b 65 6e 0a 73 70  ameter" token.sp
176b0 65 63 69 66 69 65 73 20 61 20 70 6c 61 63 65 68  ecifies a placeh
176c0 6f 6c 64 65 72 20 69 6e 20 74 68 65 20 65 78 70  older in the exp
176d0 72 65 73 73 69 6f 6e 20 66 6f 72 20 61 20 0a 76  ression for a .v
176e0 61 6c 75 65 20 74 68 61 74 20 69 73 20 66 69 6c  alue that is fil
176f0 6c 65 64 20 69 6e 20 61 74 20 72 75 6e 74 69 6d  led in at runtim
17700 65 20 75 73 69 6e 67 20 74 68 65 0a 5b 73 71 6c  e using the.[sql
17710 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
17720 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
17730 29 5d 20 66 61 6d 69 6c 79 20 6f 66 20 43 2f 43  )] family of C/C
17740 2b 2b 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 50  ++ interfaces..P
17750 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 74 61  arameters can ta
17760 6b 65 20 73 65 76 65 72 61 6c 20 66 6f 72 6d 73  ke several forms
17770 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  :.</p>..<blockqu
17780 6f 74 65 3e 0a 3c 74 61 62 6c 65 3e 0a 3c 74 72  ote>.<table>.<tr
17790 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69 67  >.<td align="rig
177a0 68 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22  ht" valign="top"
177b0 3e 3c 62 3e 3f 3c 2f 62 3e 3c 69 3e 4e 4e 4e 3c  ><b>?</b><i>NNN<
177c0 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74  /i></td><td widt
177d0 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74 64  h="20"></td>.<td
177e0 3e 5e 28 41 20 71 75 65 73 74 69 6f 6e 20 6d 61  >^(A question ma
177f0 72 6b 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  rk followed by a
17800 20 6e 75 6d 62 65 72 20 3c 69 3e 4e 4e 4e 3c 2f   number <i>NNN</
17810 69 3e 20 68 6f 6c 64 73 20 61 20 73 70 6f 74 20  i> holds a spot 
17820 66 6f 72 20 74 68 65 0a 4e 4e 4e 2d 74 68 20 70  for the.NNN-th p
17830 61 72 61 6d 65 74 65 72 2e 20 20 4e 4e 4e 20 6d  arameter.  NNN m
17840 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
17850 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 41 58   and [SQLITE_MAX
17860 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
17870 5d 2e 29 5e 0a 3c 2f 74 64 3e 0a 3c 2f 74 72 3e  ].)^.</td>.</tr>
17880 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d  .<tr>.<td align=
17890 22 72 69 67 68 74 22 20 76 61 6c 69 67 6e 3d 22  "right" valign="
178a0 74 6f 70 22 3e 3c 62 3e 3f 3c 2f 62 3e 3c 2f 74  top"><b>?</b></t
178b0 64 3e 3c 74 64 20 77 69 64 74 68 3d 22 32 30 22  d><td width="20"
178c0 3e 3c 2f 74 64 3e 0a 3c 74 64 3e 5e 41 20 71 75  ></td>.<td>^A qu
178d0 65 73 74 69 6f 6e 20 6d 61 72 6b 20 74 68 61 74  estion mark that
178e0 20 69 73 20 6e 6f 74 20 66 6f 6c 6c 6f 77 65 64   is not followed
178f0 20 62 79 20 61 20 6e 75 6d 62 65 72 20 63 72 65   by a number cre
17900 61 74 65 73 20 61 20 70 61 72 61 6d 65 74 65 72  ates a parameter
17910 0a 77 69 74 68 20 61 20 6e 75 6d 62 65 72 20 6f  .with a number o
17920 6e 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ne greater than 
17930 74 68 65 20 6c 61 72 67 65 73 74 20 70 61 72 61  the largest para
17940 6d 65 74 65 72 20 6e 75 6d 62 65 72 20 61 6c 72  meter number alr
17950 65 61 64 79 20 61 73 73 69 67 6e 65 64 2e 0a 5e  eady assigned..^
17960 49 66 20 74 68 69 73 20 6d 65 61 6e 73 20 74 68  If this means th
17970 65 20 70 61 72 61 6d 65 74 65 72 20 6e 75 6d 62  e parameter numb
17980 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68  er is greater th
17990 61 6e 0a 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56  an.[SQLITE_MAX_V
179a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 2c  ARIABLE_NUMBER],
179b0 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 2e   it is an error.
179c0 0a 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20  .This parameter 
179d0 66 6f 72 6d 61 74 20 69 73 20 70 72 6f 76 69 64  format is provid
179e0 65 64 20 66 6f 72 20 63 6f 6d 70 61 74 69 62 69  ed for compatibi
179f0 6c 69 74 79 20 77 69 74 68 20 6f 74 68 65 72 20  lity with other 
17a00 64 61 74 61 62 61 73 65 0a 65 6e 67 69 6e 65 73  database.engines
17a10 2e 20 20 42 75 74 20 62 65 63 61 75 73 65 20 69  .  But because i
17a20 74 20 69 73 20 65 61 73 79 20 74 6f 20 6d 69 73  t is easy to mis
17a30 63 6f 75 6e 74 20 74 68 65 20 71 75 65 73 74 69  count the questi
17a40 6f 6e 20 6d 61 72 6b 73 2c 20 74 68 65 0a 75 73  on marks, the.us
17a50 65 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65  e of this parame
17a60 74 65 72 20 66 6f 72 6d 61 74 20 69 73 20 64 69  ter format is di
17a70 73 63 6f 75 72 61 67 65 64 2e 20 20 50 72 6f 67  scouraged.  Prog
17a80 72 61 6d 6d 65 72 73 20 61 72 65 20 65 6e 63 6f  rammers are enco
17a90 75 72 61 67 65 64 0a 74 6f 20 75 73 65 20 6f 6e  uraged.to use on
17aa0 65 20 6f 66 20 74 68 65 20 73 79 6d 62 6f 6c 69  e of the symboli
17ab0 63 20 66 6f 72 6d 61 74 73 20 62 65 6c 6f 77 20  c formats below 
17ac0 6f 72 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  or the ?NNN form
17ad0 61 74 20 61 62 6f 76 65 20 69 6e 73 74 65 61 64  at above instead
17ae0 2e 0a 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74  ..</td>.</tr>.<t
17af0 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69  r>.<td align="ri
17b00 67 68 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70  ght" valign="top
17b10 22 3e 3c 62 3e 3a 3c 2f 62 3e 3c 69 3e 41 41 41  "><b>:</b><i>AAA
17b20 41 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69  A</i></td><td wi
17b30 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c  dth="20"></td>.<
17b40 74 64 3e 5e 41 20 63 6f 6c 6f 6e 20 66 6f 6c 6c  td>^A colon foll
17b50 6f 77 65 64 20 62 79 20 61 6e 20 69 64 65 6e 74  owed by an ident
17b60 69 66 69 65 72 20 6e 61 6d 65 20 68 6f 6c 64 73  ifier name holds
17b70 20 61 20 73 70 6f 74 20 66 6f 72 20 61 20 0a 5b   a spot for a .[
17b80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
17b90 61 6d 65 74 65 72 5f 6e 61 6d 65 7c 6e 61 6d 65  ameter_name|name
17ba0 64 20 70 61 72 61 6d 65 74 65 72 5d 20 77 69 74  d parameter] wit
17bb0 68 20 74 68 65 20 6e 61 6d 65 20 3a 41 41 41 41  h the name :AAAA
17bc0 2e 20 20 0a 5e 28 4e 61 6d 65 64 20 70 61 72 61  .  .^(Named para
17bd0 6d 65 74 65 72 73 20 61 72 65 20 61 6c 73 6f 20  meters are also 
17be0 6e 75 6d 62 65 72 65 64 2e 20 54 68 65 20 6e 75  numbered. The nu
17bf0 6d 62 65 72 20 61 73 73 69 67 6e 65 64 20 69 73  mber assigned is
17c00 20 6f 6e 65 20 67 72 65 61 74 65 72 20 74 68 61   one greater tha
17c10 6e 0a 74 68 65 20 6c 61 72 67 65 73 74 20 70 61  n.the largest pa
17c20 72 61 6d 65 74 65 72 20 6e 75 6d 62 65 72 20 61  rameter number a
17c30 6c 72 65 61 64 79 20 61 73 73 69 67 6e 65 64 2e  lready assigned.
17c40 29 5e 20 5e 49 66 20 74 68 69 73 20 6d 65 61 6e  )^ ^If this mean
17c50 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  s the parameter.
17c60 77 6f 75 6c 64 20 62 65 20 61 73 73 69 67 6e 65  would be assigne
17c70 64 20 61 20 6e 75 6d 62 65 72 20 67 72 65 61 74  d a number great
17c80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
17c90 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
17ca0 42 45 52 5d 2c 20 69 74 20 69 73 0a 61 6e 20 65  BER], it is.an e
17cb0 72 72 6f 72 2e 20 54 6f 20 61 76 6f 69 64 20 63  rror. To avoid c
17cc0 6f 6e 66 75 73 69 6f 6e 2c 20 69 74 20 69 73 20  onfusion, it is 
17cd0 62 65 73 74 20 74 6f 20 61 76 6f 69 64 20 6d 69  best to avoid mi
17ce0 78 69 6e 67 20 6e 61 6d 65 64 20 61 6e 64 20 6e  xing named and n
17cf0 75 6d 62 65 72 65 64 0a 70 61 72 61 6d 65 74 65  umbered.paramete
17d00 72 73 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c  rs.</td>.</tr>.<
17d10 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72  tr>.<td align="r
17d20 69 67 68 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f  ight" valign="to
17d30 70 22 3e 3c 62 3e 40 3c 2f 62 3e 3c 69 3e 41 41  p"><b>@</b><i>AA
17d40 41 41 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77  AA</i></td><td w
17d50 69 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a  idth="20"></td>.
17d60 3c 74 64 3e 5e 41 6e 20 22 61 74 22 20 73 69 67  <td>^An "at" sig
17d70 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
17d80 6c 69 6b 65 20 61 20 63 6f 6c 6f 6e 2c 20 65 78  like a colon, ex
17d90 63 65 70 74 20 74 68 61 74 20 74 68 65 20 6e 61  cept that the na
17da0 6d 65 20 6f 66 0a 74 68 65 20 70 61 72 61 6d 65  me of.the parame
17db0 74 65 72 20 63 72 65 61 74 65 64 20 69 73 20 40  ter created is @
17dc0 41 41 41 41 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e  AAAA.</td>.</tr>
17dd0 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d  .<tr>.<td align=
17de0 22 72 69 67 68 74 22 20 76 61 6c 69 67 6e 3d 22  "right" valign="
17df0 74 6f 70 22 3e 3c 62 3e 24 3c 2f 62 3e 3c 69 3e  top"><b>$</b><i>
17e00 41 41 41 41 3c 2f 69 3e 3c 2f 74 64 3e 3c 74 64  AAAA</i></td><td
17e10 20 77 69 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64   width="20"></td
17e20 3e 0a 3c 74 64 3e 5e 41 20 64 6f 6c 6c 61 72 2d  >.<td>^A dollar-
17e30 73 69 67 6e 20 66 6f 6c 6c 6f 77 65 64 20 62 79  sign followed by
17e40 20 61 6e 20 69 64 65 6e 74 69 66 69 65 72 20 6e   an identifier n
17e50 61 6d 65 20 61 6c 73 6f 20 68 6f 6c 64 73 20 61  ame also holds a
17e60 20 73 70 6f 74 20 66 6f 72 20 61 20 6e 61 6d 65   spot for a name
17e70 64 0a 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  d.parameter with
17e80 20 74 68 65 20 6e 61 6d 65 20 24 41 41 41 41 2e   the name $AAAA.
17e90 20 20 5e 28 54 68 65 20 69 64 65 6e 74 69 66 69    ^(The identifi
17ea0 65 72 20 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  er name in this 
17eb0 63 61 73 65 20 63 61 6e 20 69 6e 63 6c 75 64 65  case can include
17ec0 0a 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 63 63  .one or more occ
17ed0 75 72 72 65 6e 63 65 73 20 6f 66 20 22 3a 3a 22  urrences of "::"
17ee0 20 61 6e 64 20 61 20 73 75 66 66 69 78 20 65 6e   and a suffix en
17ef0 63 6c 6f 73 65 64 20 69 6e 20 22 28 2e 2e 2e 29  closed in "(...)
17f00 22 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 61 6e 79  " containing.any
17f10 20 74 65 78 74 20 61 74 20 61 6c 6c 2e 29 5e 20   text at all.)^ 
17f20 20 54 68 69 73 20 73 79 6e 74 61 78 20 69 73 20   This syntax is 
17f30 74 68 65 20 66 6f 72 6d 20 6f 66 20 61 20 76 61  the form of a va
17f40 72 69 61 62 6c 65 20 6e 61 6d 65 20 69 6e 20 74  riable name in t
17f50 68 65 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 74  he.[http://www.t
17f60 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 20 7c 20 54  cl-lang.org/ | T
17f70 63 6c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c  cl programming l
17f80 61 6e 67 75 61 67 65 5d 2e 20 20 54 68 65 20 70  anguage].  The p
17f90 72 65 73 65 6e 63 65 0a 6f 66 20 74 68 69 73 20  resence.of this 
17fa0 73 79 6e 74 61 78 20 72 65 73 75 6c 74 73 20 66  syntax results f
17fb0 72 6f 6d 20 74 68 65 20 66 61 63 74 20 74 68 61  rom the fact tha
17fc0 74 20 53 51 4c 69 74 65 20 69 73 20 72 65 61 6c  t SQLite is real
17fd0 6c 79 20 61 20 0a 5b 54 63 6c 20 65 78 74 65 6e  ly a .[Tcl exten
17fe0 73 69 6f 6e 5d 20 74 68 61 74 20 68 61 73 20 65  sion] that has e
17ff0 73 63 61 70 65 64 20 69 6e 74 6f 20 74 68 65 20  scaped into the 
18000 77 69 6c 64 2e 3c 2f 74 64 3e 0a 3c 2f 74 72 3e  wild.</td>.</tr>
18010 0a 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63  .</table>.</bloc
18020 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 5e 50 61 72  kquote>..<p>^Par
18030 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
18040 20 6e 6f 74 20 61 73 73 69 67 6e 65 64 20 76 61   not assigned va
18050 6c 75 65 73 20 75 73 69 6e 67 0a 5b 73 71 6c 69  lues using.[sqli
18060 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
18070 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  | sqlite3_bind()
18080 5d 20 61 72 65 20 74 72 65 61 74 65 64 0a 61 73  ] are treated.as
18090 20 4e 55 4c 4c 2e 20 20 54 68 65 20 5b 73 71 6c   NULL.  The [sql
180a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
180b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 69 6e 74  ter_index()] int
180c0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
180d0 65 64 0a 74 6f 20 74 72 61 6e 73 6c 61 74 65 20  ed.to translate 
180e0 61 20 73 79 6d 62 6f 6c 69 63 20 70 61 72 61 6d  a symbolic param
180f0 65 74 65 72 20 6e 61 6d 65 20 69 6e 74 6f 20 69  eter name into i
18100 74 73 20 65 71 75 69 76 61 6c 65 6e 74 20 6e 75  ts equivalent nu
18110 6d 65 72 69 63 20 69 6e 64 65 78 2e 3c 2f 70 3e  meric index.</p>
18120 0a 0a 3c 70 3e 5e 54 68 65 20 6d 61 78 69 6d 75  ..<p>^The maximu
18130 6d 20 70 61 72 61 6d 65 74 65 72 20 6e 75 6d 62  m parameter numb
18140 65 72 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d  er is set at com
18150 70 69 6c 65 2d 74 69 6d 65 20 62 79 0a 74 68 65  pile-time by.the
18160 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52   [SQLITE_MAX_VAR
18170 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 6d 61  IABLE_NUMBER] ma
18180 63 72 6f 2e 20 20 5e 28 41 6e 20 69 6e 64 69 76  cro.  ^(An indiv
18190 69 64 75 61 6c 20 5b 64 61 74 61 62 61 73 65 20  idual [database 
181a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 44 20 63 61  connection].D ca
181b0 6e 20 72 65 64 75 63 65 20 69 74 73 20 6d 61 78  n reduce its max
181c0 69 6d 75 6d 20 70 61 72 61 6d 65 74 65 72 20 6e  imum parameter n
181d0 75 6d 62 65 72 20 62 65 6c 6f 77 20 74 68 65 20  umber below the 
181e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
181f0 69 6d 75 6d 0a 75 73 69 6e 67 20 74 68 65 20 5b  imum.using the [
18200 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 44  sqlite3_limit](D
18210 2c 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  , [SQLITE_LIMIT_
18220 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
18230 2c 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63 65 2e  ,...) interface.
18240 29 5e 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  )^.</p>..<tcl>hd
18250 5f 66 72 61 67 6d 65 6e 74 20 6c 69 6b 65 20 4c  _fragment like L
18260 49 4b 45 20 45 53 43 41 50 45 3c 2f 74 63 6c 3e  IKE ESCAPE</tcl>
18270 0a 3c 68 33 3e 54 68 65 20 4c 49 4b 45 2c 20 47  .<h3>The LIKE, G
18280 4c 4f 42 2c 20 52 45 47 45 58 50 2c 20 61 6e 64  LOB, REGEXP, and
18290 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 73   MATCH operators
182a0 3c 2f 68 33 3e 0a 3c 70 3e 5e 54 68 65 20 4c 49  </h3>.<p>^The LI
182b0 4b 45 20 6f 70 65 72 61 74 6f 72 20 64 6f 65 73  KE operator does
182c0 20 61 20 70 61 74 74 65 72 6e 20 6d 61 74 63 68   a pattern match
182d0 69 6e 67 20 63 6f 6d 70 61 72 69 73 6f 6e 2e 20  ing comparison. 
182e0 5e 54 68 65 20 6f 70 65 72 61 6e 64 0a 74 6f 20  ^The operand.to 
182f0 74 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65  the right of the
18300 20 4c 49 4b 45 20 6f 70 65 72 61 74 6f 72 20 63   LIKE operator c
18310 6f 6e 74 61 69 6e 73 20 74 68 65 20 70 61 74 74  ontains the patt
18320 65 72 6e 20 61 6e 64 20 74 68 65 20 6c 65 66 74  ern and the left
18330 20 68 61 6e 64 0a 6f 70 65 72 61 6e 64 20 63 6f   hand.operand co
18340 6e 74 61 69 6e 73 20 74 68 65 20 73 74 72 69 6e  ntains the strin
18350 67 20 74 6f 20 6d 61 74 63 68 20 61 67 61 69 6e  g to match again
18360 73 74 20 74 68 65 20 70 61 74 74 65 72 6e 2e 0a  st the pattern..
18370 0a 3c 74 63 6c 3e 68 64 5f 70 75 74 73 20 22 5e  .<tcl>hd_puts "^
18380 41 20 70 65 72 63 65 6e 74 20 73 79 6d 62 6f 6c  A percent symbol
18390 20 28 5c 22 25 5c 22 29 20 69 6e 20 74 68 65 20   (\"%\") in the 
183a0 4c 49 4b 45 20 70 61 74 74 65 72 6e 20 6d 61 74  LIKE pattern mat
183b0 63 68 65 73 20 61 6e 79 0a 73 65 71 75 65 6e 63  ches any.sequenc
183c0 65 20 6f 66 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  e of zero or mor
183d0 65 20 63 68 61 72 61 63 74 65 72 73 20 69 6e 20  e characters in 
183e0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 41 6e  the string.  ^An
183f0 20 75 6e 64 65 72 73 63 6f 72 65 0a 28 5c 22 5f   underscore.(\"_
18400 5c 22 29 20 69 6e 20 74 68 65 20 4c 49 4b 45 20  \") in the LIKE 
18410 70 61 74 74 65 72 6e 20 6d 61 74 63 68 65 73 20  pattern matches 
18420 61 6e 79 20 73 69 6e 67 6c 65 20 63 68 61 72 61  any single chara
18430 63 74 65 72 20 69 6e 20 74 68 65 0a 73 74 72 69  cter in the.stri
18440 6e 67 2e 20 20 5e 28 41 6e 79 20 6f 74 68 65 72  ng.  ^(Any other
18450 20 63 68 61 72 61 63 74 65 72 20 6d 61 74 63 68   character match
18460 65 73 20 69 74 73 65 6c 66 20 6f 72 20 69 74 73  es itself or its
18470 20 6c 6f 77 65 72 2f 75 70 70 65 72 20 63 61 73   lower/upper cas
18480 65 0a 65 71 75 69 76 61 6c 65 6e 74 20 28 69 2e  e.equivalent (i.
18490 65 2e 20 63 61 73 65 2d 69 6e 73 65 6e 73 69 74  e. case-insensit
184a0 69 76 65 20 6d 61 74 63 68 69 6e 67 29 2e 29 5e  ive matching).)^
184b0 0a 0a 3c 75 3e 49 6d 70 6f 72 74 61 6e 74 20 4e  ..<u>Important N
184c0 6f 74 65 3a 3c 2f 75 3e 20 5e 53 51 4c 69 74 65  ote:</u> ^SQLite
184d0 20 6f 6e 6c 79 0a 75 6e 64 65 72 73 74 61 6e 64   only.understand
184e0 73 20 75 70 70 65 72 2f 6c 6f 77 65 72 20 63 61  s upper/lower ca
184f0 73 65 20 66 6f 72 20 41 53 43 49 49 20 63 68 61  se for ASCII cha
18500 72 61 63 74 65 72 73 20 62 79 20 64 65 66 61 75  racters by defau
18510 6c 74 2e 20 20 5e 54 68 65 0a 4c 49 4b 45 20 6f  lt.  ^The.LIKE o
18520 70 65 72 61 74 6f 72 20 69 73 20 63 61 73 65 20  perator is case 
18530 73 65 6e 73 69 74 69 76 65 20 62 79 20 64 65 66  sensitive by def
18540 61 75 6c 74 20 66 6f 72 20 75 6e 69 63 6f 64 65  ault for unicode
18550 20 63 68 61 72 61 63 74 65 72 73 20 74 68 61 74   characters that
18560 20 61 72 65 0a 62 65 79 6f 6e 64 20 74 68 65 20   are.beyond the 
18570 41 53 43 49 49 20 72 61 6e 67 65 2e 20 20 46 6f  ASCII range.  Fo
18580 72 20 65 78 61 6d 70 6c 65 2c 0a 5e 74 68 65 20  r example,.^the 
18590 65 78 70 72 65 73 73 69 6f 6e 20 3c 62 3e 27 61  expression <b>'a
185a0 27 26 6e 62 73 70 3b 4c 49 4b 45 26 6e 62 73 70  '&nbsp;LIKE&nbsp
185b0 3b 27 41 27 3c 2f 62 3e 0a 69 73 20 54 52 55 45  ;'A'</b>.is TRUE
185c0 20 62 75 74 20 3c 62 3e 27 26 61 65 6c 69 67 3b   but <b>'&aelig;
185d0 27 26 6e 62 73 70 3b 4c 49 4b 45 26 6e 62 73 70  '&nbsp;LIKE&nbsp
185e0 3b 27 26 41 45 6c 69 67 3b 27 3c 2f 62 3e 20 69  ;'&AElig;'</b> i
185f0 73 20 46 41 4c 53 45 2e 22 3c 2f 74 63 6c 3e 0a  s FALSE."</tcl>.
18600 54 68 65 20 49 43 55 20 65 78 74 65 6e 73 69 6f  The ICU extensio
18610 6e 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 63 6c  n to SQLite incl
18620 75 64 65 73 20 61 6e 20 65 6e 68 61 6e 63 65 64  udes an enhanced
18630 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 0a   version of the.
18640 4c 49 4b 45 20 6f 70 65 72 61 74 6f 72 20 74 68  LIKE operator th
18650 61 74 20 64 6f 65 73 20 63 61 73 65 20 66 6f 6c  at does case fol
18660 64 69 6e 67 20 61 63 72 6f 73 73 20 61 6c 6c 20  ding across all 
18670 75 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 65  unicode characte
18680 72 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20  rs.</p>..<p>^If 
18690 74 68 65 20 6f 70 74 69 6f 6e 61 6c 20 45 53 43  the optional ESC
186a0 41 50 45 20 63 6c 61 75 73 65 20 69 73 20 70 72  APE clause is pr
186b0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
186c0 65 78 70 72 65 73 73 69 6f 6e 0a 66 6f 6c 6c 6f  expression.follo
186d0 77 69 6e 67 20 74 68 65 20 45 53 43 41 50 45 20  wing the ESCAPE 
186e0 6b 65 79 77 6f 72 64 20 6d 75 73 74 20 65 76 61  keyword must eva
186f0 6c 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e  luate to a strin
18700 67 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 0a  g consisting of.
18710 61 20 73 69 6e 67 6c 65 20 63 68 61 72 61 63 74  a single charact
18720 65 72 2e 20 5e 54 68 69 73 20 63 68 61 72 61 63  er. ^This charac
18730 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
18740 69 6e 20 74 68 65 20 4c 49 4b 45 20 70 61 74 74  in the LIKE patt
18750 65 72 6e 0a 74 6f 20 69 6e 63 6c 75 64 65 20 6c  ern.to include l
18760 69 74 65 72 61 6c 20 70 65 72 63 65 6e 74 20 6f  iteral percent o
18770 72 20 75 6e 64 65 72 73 63 6f 72 65 20 63 68 61  r underscore cha
18780 72 61 63 74 65 72 73 2e 20 5e 54 68 65 20 65 73  racters. ^The es
18790 63 61 70 65 0a 63 68 61 72 61 63 74 65 72 20 66  cape.character f
187a0 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 70 65 72  ollowed by a per
187b0 63 65 6e 74 20 73 79 6d 62 6f 6c 20 28 25 29 2c  cent symbol (%),
187c0 20 75 6e 64 65 72 73 63 6f 72 65 20 28 5f 29 2c   underscore (_),
187d0 20 6f 72 20 61 20 73 65 63 6f 6e 64 0a 69 6e 73   or a second.ins
187e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 65 73 63  tance of the esc
187f0 61 70 65 20 63 68 61 72 61 63 74 65 72 20 69 74  ape character it
18800 73 65 6c 66 20 6d 61 74 63 68 65 73 20 61 0a 6c  self matches a.l
18810 69 74 65 72 61 6c 20 70 65 72 63 65 6e 74 20 73  iteral percent s
18820 79 6d 62 6f 6c 2c 20 75 6e 64 65 72 73 63 6f 72  ymbol, underscor
18830 65 2c 20 6f 72 20 61 20 73 69 6e 67 6c 65 20 65  e, or a single e
18840 73 63 61 70 65 20 63 68 61 72 61 63 74 65 72 2c  scape character,
18850 0a 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 0a  .respectively...
18860 3c 70 3e 5e 54 68 65 20 69 6e 66 69 78 20 4c 49  <p>^The infix LI
18870 4b 45 20 6f 70 65 72 61 74 6f 72 20 69 73 20 69  KE operator is i
18880 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 63 61  mplemented by ca
18890 6c 6c 69 6e 67 20 74 68 65 0a 61 70 70 6c 69 63  lling the.applic
188a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
188b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 6c 69 6b  L functions [lik
188c0 65 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c  e(<i>Y</i>,<i>X<
188d0 2f 69 3e 29 5d 20 6f 72 0a 5b 6c 69 6b 65 28 3c  /i>)] or.[like(<
188e0 69 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f 69 3e  i>Y</i>,<i>X</i>
188f0 2c 3c 69 3e 5a 3c 2f 69 3e 29 5d 3c 2f 61 3e 2e  ,<i>Z</i>)]</a>.
18900 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 4c 49  </p>..<p>^The LI
18910 4b 45 20 6f 70 65 72 61 74 6f 72 20 63 61 6e 20  KE operator can 
18920 62 65 20 6d 61 64 65 20 63 61 73 65 20 73 65 6e  be made case sen
18930 73 69 74 69 76 65 20 75 73 69 6e 67 20 74 68 65  sitive using the
18940 0a 5b 63 61 73 65 5f 73 65 6e 73 69 74 69 76 65  .[case_sensitive
18950 5f 6c 69 6b 65 20 70 72 61 67 6d 61 5d 2e 3c 2f  _like pragma].</
18960 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  p>..<tcl>hd_frag
18970 6d 65 6e 74 20 67 6c 6f 62 20 47 4c 4f 42 3c 2f  ment glob GLOB</
18980 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 47 4c 4f  tcl>.<p>^The GLO
18990 42 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 69  B operator is si
189a0 6d 69 6c 61 72 20 74 6f 20 4c 49 4b 45 20 62 75  milar to LIKE bu
189b0 74 20 75 73 65 73 20 74 68 65 20 55 6e 69 78 0a  t uses the Unix.
189c0 66 69 6c 65 20 67 6c 6f 62 62 69 6e 67 20 73 79  file globbing sy
189d0 6e 74 61 78 20 66 6f 72 20 69 74 73 20 77 69 6c  ntax for its wil
189e0 64 63 61 72 64 73 2e 20 20 5e 41 6c 73 6f 2c 20  dcards.  ^Also, 
189f0 47 4c 4f 42 20 69 73 20 63 61 73 65 0a 73 65 6e  GLOB is case.sen
18a00 73 69 74 69 76 65 2c 20 75 6e 6c 69 6b 65 20 4c  sitive, unlike L
18a10 49 4b 45 2e 20 20 5e 42 6f 74 68 20 47 4c 4f 42  IKE.  ^Both GLOB
18a20 20 61 6e 64 20 4c 49 4b 45 20 6d 61 79 20 62 65   and LIKE may be
18a30 20 70 72 65 63 65 64 65 64 20 62 79 0a 74 68 65   preceded by.the
18a40 20 4e 4f 54 20 6b 65 79 77 6f 72 64 20 74 6f 20   NOT keyword to 
18a50 69 6e 76 65 72 74 20 74 68 65 20 73 65 6e 73 65  invert the sense
18a60 20 6f 66 20 74 68 65 20 74 65 73 74 2e 20 20 5e   of the test.  ^
18a70 54 68 65 20 69 6e 66 69 78 20 47 4c 4f 42 20 0a  The infix GLOB .
18a80 6f 70 65 72 61 74 6f 72 20 69 73 20 69 6d 70 6c  operator is impl
18a90 65 6d 65 6e 74 65 64 20 62 79 20 63 61 6c 6c 69  emented by calli
18aa0 6e 67 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 0a  ng the function.
18ab0 5b 67 6c 6f 62 28 3c 69 3e 59 3c 2f 69 3e 2c 3c  [glob(<i>Y</i>,<
18ac0 69 3e 58 3c 2f 69 3e 29 5d 20 61 6e 64 20 63 61  i>X</i>)] and ca
18ad0 6e 20 62 65 20 6d 6f 64 69 66 69 65 64 20 62 79  n be modified by
18ae0 20 6f 76 65 72 72 69 64 69 6e 67 0a 74 68 61 74   overriding.that
18af0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a   function.</p>..
18b00 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
18b10 20 72 65 67 65 78 70 20 52 45 47 45 58 50 3c 2f   regexp REGEXP</
18b20 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 52 45 47  tcl>.<p>^The REG
18b30 45 58 50 20 6f 70 65 72 61 74 6f 72 20 69 73 20  EXP operator is 
18b40 61 20 73 70 65 63 69 61 6c 20 73 79 6e 74 61 78  a special syntax
18b50 20 66 6f 72 20 74 68 65 20 72 65 67 65 78 70 28   for the regexp(
18b60 29 0a 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 2e  ).user function.
18b70 20 20 5e 4e 6f 20 72 65 67 65 78 70 28 29 20 75    ^No regexp() u
18b80 73 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ser function is 
18b90 64 65 66 69 6e 65 64 20 62 79 20 64 65 66 61 75  defined by defau
18ba0 6c 74 0a 61 6e 64 20 73 6f 20 75 73 65 20 6f 66  lt.and so use of
18bb0 20 74 68 65 20 52 45 47 45 58 50 20 6f 70 65 72   the REGEXP oper
18bc0 61 74 6f 72 20 77 69 6c 6c 20 6e 6f 72 6d 61 6c  ator will normal
18bd0 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 0a  ly result in an.
18be0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
18bf0 5e 49 66 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  ^If an [applicat
18c00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
18c10 66 75 6e 63 74 69 6f 6e 5d 20 6e 61 6d 65 64 20  function] named 
18c20 22 72 65 67 65 78 70 22 0a 69 73 20 61 64 64 65  "regexp".is adde
18c30 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2c 20 74  d at run-time, t
18c40 68 65 6e 20 74 68 65 20 22 3c 69 3e 58 3c 2f 69  hen the "<i>X</i
18c50 3e 20 52 45 47 45 58 50 20 3c 69 3e 59 3c 2f 69  > REGEXP <i>Y</i
18c60 3e 22 20 6f 70 65 72 61 74 6f 72 20 77 69 6c 6c  >" operator will
18c70 0a 62 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .be implemented 
18c80 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 22 72 65  as a call to "re
18c90 67 65 78 70 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69  gexp(<i>Y</i>,<i
18ca0 3e 58 3c 2f 69 3e 29 22 2e 3c 2f 70 3e 0a 0a 3c  >X</i>)".</p>..<
18cb0 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
18cc0 6d 61 74 63 68 20 4d 41 54 43 48 3c 2f 74 63 6c  match MATCH</tcl
18cd0 3e 0a 3c 70 3e 5e 54 68 65 20 4d 41 54 43 48 20  >.<p>^The MATCH 
18ce0 6f 70 65 72 61 74 6f 72 20 69 73 20 61 20 73 70  operator is a sp
18cf0 65 63 69 61 6c 20 73 79 6e 74 61 78 20 66 6f 72  ecial syntax for
18d00 20 74 68 65 20 6d 61 74 63 68 28 29 0a 61 70 70   the match().app
18d10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
18d20 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 54 68 65   function.  ^The
18d30 20 64 65 66 61 75 6c 74 20 6d 61 74 63 68 28 29   default match()
18d40 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
18d50 65 6e 74 61 74 69 6f 6e 0a 72 61 69 73 65 73 20  entation.raises 
18d60 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 61 6e 64  an exception and
18d70 20 69 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75   is not really u
18d80 73 65 66 75 6c 20 66 6f 72 20 61 6e 79 74 68 69  seful for anythi
18d90 6e 67 2e 0a 5e 42 75 74 20 65 78 74 65 6e 73 69  ng..^But extensi
18da0 6f 6e 73 20 63 61 6e 20 6f 76 65 72 72 69 64 65  ons can override
18db0 20 74 68 65 20 6d 61 74 63 68 28 29 20 66 75 6e   the match() fun
18dc0 63 74 69 6f 6e 20 77 69 74 68 20 6d 6f 72 65 0a  ction with more.
18dd0 68 65 6c 70 66 75 6c 20 6c 6f 67 69 63 2e 3c 2f  helpful logic.</
18de0 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  p>..<tcl>hd_frag
18df0 6d 65 6e 74 20 62 65 74 77 65 65 6e 20 42 45 54  ment between BET
18e00 57 45 45 4e 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54  WEEN</tcl>.<h3>T
18e10 68 65 20 42 45 54 57 45 45 4e 20 6f 70 65 72 61  he BETWEEN opera
18e20 74 6f 72 3c 2f 68 33 3e 0a 3c 70 3e 5e 28 54 68  tor</h3>.<p>^(Th
18e30 65 20 42 45 54 57 45 45 4e 20 6f 70 65 72 61 74  e BETWEEN operat
18e40 6f 72 20 69 73 20 6c 6f 67 69 63 61 6c 6c 79 20  or is logically 
18e50 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
18e60 70 61 69 72 20 6f 66 20 63 6f 6d 70 61 72 69 73  pair of comparis
18e70 6f 6e 73 2e 0a 22 3c 69 3e 78 3c 2f 69 3e 20 3c  ons.."<i>x</i> <
18e80 62 3e 42 45 54 57 45 45 4e 3c 2f 62 3e 20 3c 69  b>BETWEEN</b> <i
18e90 3e 79 3c 2f 69 3e 20 3c 62 3e 41 4e 44 3c 2f 62  >y</i> <b>AND</b
18ea0 3e 20 3c 69 3e 7a 3c 2f 69 3e 22 20 69 73 20 0a  > <i>z</i>" is .
18eb0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 0a 22  equivalent to ."
18ec0 3c 69 3e 78 3c 2f 69 3e 3c 62 3e 26 67 74 3b 3d  <i>x</i><b>&gt;=
18ed0 3c 2f 62 3e 3c 69 3e 79 3c 2f 69 3e 20 3c 62 3e  </b><i>y</i> <b>
18ee0 41 4e 44 3c 2f 62 3e 20 3c 69 3e 78 3c 2f 69 3e  AND</b> <i>x</i>
18ef0 3c 62 3e 26 6c 74 3b 3d 3c 2f 62 3e 3c 69 3e 7a  <b>&lt;=</b><i>z
18f00 3c 2f 69 3e 22 20 65 78 63 65 70 74 0a 74 68 61  </i>" except.tha
18f10 74 20 77 69 74 68 20 42 45 54 57 45 45 4e 2c 20  t with BETWEEN, 
18f20 74 68 65 20 3c 69 3e 78 3c 2f 69 3e 20 65 78 70  the <i>x</i> exp
18f30 72 65 73 73 69 6f 6e 20 69 73 20 6f 6e 6c 79 20  ression is only 
18f40 65 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 2e 29  evaluated once.)
18f50 5e 0a 5e 54 68 65 20 70 72 65 63 65 64 65 6e 63  ^.^The precedenc
18f60 65 20 6f 66 20 74 68 65 20 42 45 54 57 45 45 4e  e of the BETWEEN
18f70 20 6f 70 65 72 61 74 6f 72 20 69 73 20 74 68 65   operator is the
18f80 20 73 61 6d 65 20 61 73 20 74 68 65 20 70 72 65   same as the pre
18f90 63 65 64 65 6e 63 65 0a 61 73 20 6f 70 65 72 61  cedence.as opera
18fa0 74 6f 72 73 20 3c 62 3e 3d 3d 3c 2f 62 3e 20 61  tors <b>==</b> a
18fb0 6e 64 20 3c 62 3e 21 3d 3c 2f 62 3e 20 61 6e 64  nd <b>!=</b> and
18fc0 20 3c 62 3e 4c 49 4b 45 3c 2f 62 3e 20 61 6e 64   <b>LIKE</b> and
18fd0 20 67 72 6f 75 70 73 20 6c 65 66 74 20 74 6f 20   groups left to 
18fe0 72 69 67 68 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f  right...<tcl>hd_
18ff0 66 72 61 67 6d 65 6e 74 20 63 61 73 65 20 7b 43  fragment case {C
19000 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e 7d 3c  ASE expression}<
19010 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 43 41  /tcl>.<h3>The CA
19020 53 45 20 65 78 70 72 65 73 73 69 6f 6e 3c 2f 68  SE expression</h
19030 33 3e 0a 3c 70 3e 41 20 43 41 53 45 20 65 78 70  3>.<p>A CASE exp
19040 72 65 73 73 69 6f 6e 20 73 65 72 76 65 73 20 61  ression serves a
19050 20 72 6f 6c 65 20 73 69 6d 69 6c 61 72 20 74 6f   role similar to
19060 20 49 46 2d 54 48 45 4e 2d 45 4c 53 45 20 69 6e   IF-THEN-ELSE in
19070 20 6f 74 68 65 72 0a 70 72 6f 67 72 61 6d 6d 69   other.programmi
19080 6e 67 20 6c 61 6e 67 75 61 67 65 73 2e 20 20 0a  ng languages.  .
19090 0a 3c 70 3e 54 68 65 20 6f 70 74 69 6f 6e 61 6c  .<p>The optional
190a0 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
190b0 20 6f 63 63 75 72 73 20 69 6e 20 62 65 74 77 65   occurs in betwe
190c0 65 6e 20 74 68 65 20 43 41 53 45 20 6b 65 79 77  en the CASE keyw
190d0 6f 72 64 20 61 6e 64 20 74 68 65 0a 66 69 72 73  ord and the.firs
190e0 74 20 57 48 45 4e 20 6b 65 79 77 6f 72 64 20 69  t WHEN keyword i
190f0 73 20 63 61 6c 6c 65 64 20 74 68 65 20 22 62 61  s called the "ba
19100 73 65 22 20 65 78 70 72 65 73 73 69 6f 6e 2e 20  se" expression. 
19110 5e 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 62  ^There are two b
19120 61 73 69 63 20 66 6f 72 6d 73 0a 6f 66 20 74 68  asic forms.of th
19130 65 20 43 41 53 45 20 65 78 70 72 65 73 73 69 6f  e CASE expressio
19140 6e 3a 20 74 68 6f 73 65 20 77 69 74 68 20 61 20  n: those with a 
19150 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e 20  base expression 
19160 61 6e 64 20 74 68 6f 73 65 20 77 69 74 68 6f 75  and those withou
19170 74 2e 0a 0a 3c 70 3e 5e 49 6e 20 61 20 43 41 53  t...<p>^In a CAS
19180 45 20 77 69 74 68 6f 75 74 20 61 20 62 61 73 65  E without a base
19190 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 65 61 63   expression, eac
191a0 68 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f  h WHEN expressio
191b0 6e 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 61  n is evaluated.a
191c0 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 74 72  nd the result tr
191d0 65 61 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  eated as a boole
191e0 61 6e 2c 20 73 74 61 72 74 69 6e 67 20 77 69 74  an, starting wit
191f0 68 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 61  h the leftmost a
19200 6e 64 20 63 6f 6e 74 69 6e 75 69 6e 67 0a 74 6f  nd continuing.to
19210 20 74 68 65 20 72 69 67 68 74 2e 20 5e 54 68 65   the right. ^The
19220 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 43   result of the C
19230 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ASE expression i
19240 73 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  s the evaluation
19250 20 6f 66 20 74 68 65 20 54 48 45 4e 0a 65 78 70   of the THEN.exp
19260 72 65 73 73 69 6f 6e 20 74 68 61 74 20 63 6f 72  ression that cor
19270 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20  responds to the 
19280 66 69 72 73 74 20 57 48 45 4e 20 65 78 70 72 65  first WHEN expre
19290 73 73 69 6f 6e 20 74 68 61 74 20 65 76 61 6c 75  ssion that evalu
192a0 61 74 65 73 20 74 6f 0a 74 72 75 65 2e 20 5e 4f  ates to.true. ^O
192b0 72 2c 20 69 66 20 6e 6f 6e 65 20 6f 66 20 74 68  r, if none of th
192c0 65 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f  e WHEN expressio
192d0 6e 73 20 65 76 61 6c 75 61 74 65 20 74 6f 20 74  ns evaluate to t
192e0 72 75 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  rue, the result 
192f0 6f 66 0a 65 76 61 6c 75 61 74 69 6e 67 20 74 68  of.evaluating th
19300 65 20 45 4c 53 45 20 65 78 70 72 65 73 73 69 6f  e ELSE expressio
19310 6e 2c 20 69 66 20 61 6e 79 2e 20 5e 49 66 20 74  n, if any. ^If t
19320 68 65 72 65 20 69 73 20 6e 6f 20 45 4c 53 45 20  here is no ELSE 
19330 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64 0a 6e  expression and.n
19340 6f 6e 65 20 6f 66 20 74 68 65 20 57 48 45 4e 20  one of the WHEN 
19350 65 78 70 72 65 73 73 69 6f 6e 73 20 61 72 65 20  expressions are 
19360 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 6f  true, then the o
19370 76 65 72 61 6c 6c 20 72 65 73 75 6c 74 20 69 73  verall result is
19380 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 5e 41 20 4e 55   NULL...<p>^A NU
19390 4c 4c 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e  LL result is con
193a0 73 69 64 65 72 65 64 20 75 6e 74 72 75 65 20 77  sidered untrue w
193b0 68 65 6e 20 65 76 61 6c 75 61 74 69 6e 67 20 57  hen evaluating W
193c0 48 45 4e 20 74 65 72 6d 73 2e 0a 0a 3c 70 3e 5e  HEN terms...<p>^
193d0 49 6e 20 61 20 43 41 53 45 20 77 69 74 68 20 61  In a CASE with a
193e0 20 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e   base expression
193f0 2c 20 74 68 65 20 62 61 73 65 20 65 78 70 72 65  , the base expre
19400 73 73 69 6f 6e 20 69 73 20 65 76 61 6c 75 61 74  ssion is evaluat
19410 65 64 20 6a 75 73 74 0a 6f 6e 63 65 20 61 6e 64  ed just.once and
19420 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 63   the result is c
19430 6f 6d 70 61 72 65 64 20 61 67 61 69 6e 73 74 20  ompared against 
19440 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
19450 66 20 65 61 63 68 20 57 48 45 4e 20 0a 65 78 70  f each WHEN .exp
19460 72 65 73 73 69 6f 6e 20 66 72 6f 6d 20 6c 65 66  ression from lef
19470 74 20 74 6f 20 72 69 67 68 74 2e 20 5e 54 68 65  t to right. ^The
19480 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 43   result of the C
19490 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ASE expression i
194a0 73 20 74 68 65 20 0a 65 76 61 6c 75 61 74 69 6f  s the .evaluatio
194b0 6e 20 6f 66 20 74 68 65 20 54 48 45 4e 20 65 78  n of the THEN ex
194c0 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 63 6f  pression that co
194d0 72 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65  rresponds to the
194e0 20 66 69 72 73 74 20 57 48 45 4e 0a 65 78 70 72   first WHEN.expr
194f0 65 73 73 69 6f 6e 20 66 6f 72 20 77 68 69 63 68  ession for which
19500 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
19510 69 73 20 74 72 75 65 2e 20 5e 4f 72 2c 20 69 66  is true. ^Or, if
19520 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 57 48 45   none of the WHE
19530 4e 0a 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76  N.expressions ev
19540 61 6c 75 61 74 65 20 74 6f 20 61 20 76 61 6c 75  aluate to a valu
19550 65 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 62  e equal to the b
19560 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20  ase expression, 
19570 74 68 65 20 72 65 73 75 6c 74 0a 6f 66 20 65 76  the result.of ev
19580 61 6c 75 61 74 69 6e 67 20 74 68 65 20 45 4c 53  aluating the ELS
19590 45 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 66  E expression, if
195a0 20 61 6e 79 2e 20 5e 49 66 20 74 68 65 72 65 20   any. ^If there 
195b0 69 73 20 6e 6f 20 45 4c 53 45 20 65 78 70 72 65  is no ELSE expre
195c0 73 73 69 6f 6e 20 61 6e 64 0a 6e 6f 6e 65 20 6f  ssion and.none o
195d0 66 20 74 68 65 20 57 48 45 4e 20 65 78 70 72 65  f the WHEN expre
195e0 73 73 69 6f 6e 73 20 70 72 6f 64 75 63 65 20 61  ssions produce a
195f0 20 72 65 73 75 6c 74 20 65 71 75 61 6c 20 74 6f   result equal to
19600 20 74 68 65 20 62 61 73 65 20 65 78 70 72 65 73   the base expres
19610 73 69 6f 6e 2c 0a 74 68 65 20 6f 76 65 72 61 6c  sion,.the overal
19620 6c 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  l result is NULL
19630 2e 0a 0a 3c 70 3e 5e 57 68 65 6e 20 63 6f 6d 70  ...<p>^When comp
19640 61 72 69 6e 67 20 61 20 62 61 73 65 20 65 78 70  aring a base exp
19650 72 65 73 73 69 6f 6e 20 61 67 61 69 6e 73 74 20  ression against 
19660 61 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f  a WHEN expressio
19670 6e 2c 20 74 68 65 20 73 61 6d 65 0a 63 6f 6c 6c  n, the same.coll
19680 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
19690 61 66 66 69 6e 69 74 79 2c 20 61 6e 64 20 4e 55  affinity, and NU
196a0 4c 4c 2d 68 61 6e 64 6c 69 6e 67 20 72 75 6c 65  LL-handling rule
196b0 73 20 61 70 70 6c 79 20 61 73 20 69 66 20 74 68  s apply as if th
196c0 65 0a 62 61 73 65 20 65 78 70 72 65 73 73 69 6f  e.base expressio
196d0 6e 20 61 6e 64 20 57 48 45 4e 20 65 78 70 72 65  n and WHEN expre
196e0 73 73 69 6f 6e 20 61 72 65 20 72 65 73 70 65 63  ssion are respec
196f0 74 69 76 65 6c 79 20 74 68 65 20 6c 65 66 74 2d  tively the left-
19700 20 61 6e 64 0a 72 69 67 68 74 2d 68 61 6e 64 20   and.right-hand 
19710 6f 70 65 72 61 6e 64 73 20 6f 66 20 61 6e 20 3c  operands of an <
19720 62 69 67 3e 3c 62 3e 3d 3c 2f 62 3e 3c 2f 62 69  big><b>=</b></bi
19730 67 3e 20 6f 70 65 72 61 74 6f 72 2e 3c 2f 70 3e  g> operator.</p>
19740 20 5e 49 66 20 74 68 65 20 62 61 73 65 20 0a 65   ^If the base .e
19750 78 70 72 65 73 73 69 6f 6e 20 69 73 20 4e 55 4c  xpression is NUL
19760 4c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  L then the resul
19770 74 20 6f 66 20 74 68 65 20 43 41 53 45 20 69 73  t of the CASE is
19780 20 61 6c 77 61 79 73 20 74 68 65 20 72 65 73 75   always the resu
19790 6c 74 20 0a 6f 66 20 65 76 61 6c 75 61 74 69 6e  lt .of evaluatin
197a0 67 20 74 68 65 20 45 4c 53 45 20 65 78 70 72 65  g the ELSE expre
197b0 73 73 69 6f 6e 20 69 66 20 69 74 20 65 78 69 73  ssion if it exis
197c0 74 73 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ts, or NULL if i
197d0 74 20 64 6f 65 73 20 6e 6f 74 2e 0a 0a 3c 70 3e  t does not...<p>
197e0 5e 42 6f 74 68 20 66 6f 72 6d 73 20 6f 66 20 74  ^Both forms of t
197f0 68 65 20 43 41 53 45 20 65 78 70 72 65 73 73 69  he CASE expressi
19800 6f 6e 20 75 73 65 20 6c 61 7a 79 2c 20 6f 72 20  on use lazy, or 
19810 73 68 6f 72 74 2d 63 69 72 63 75 69 74 2c 20 0a  short-circuit, .
19820 65 76 61 6c 75 61 74 69 6f 6e 2e 0a 0a 3c 70 3e  evaluation...<p>
19830 5e 28 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65  ^(The only diffe
19840 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
19850 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
19860 43 41 53 45 20 65 78 70 72 65 73 73 69 6f 6e 73  CASE expressions
19870 20 69 73 20 74 68 61 74 20 0a 74 68 65 20 3c 69   is that .the <i
19880 3e 78 3c 2f 69 3e 20 65 78 70 72 65 73 73 69 6f  >x</i> expressio
19890 6e 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 65  n is evaluated e
198a0 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 6e 20 74  xactly once in t
198b0 68 65 20 66 69 72 73 74 20 65 78 61 6d 70 6c 65  he first example
198c0 20 62 75 74 20 0a 6d 69 67 68 74 20 62 65 20 65   but .might be e
198d0 76 61 6c 75 61 74 65 64 20 6d 75 6c 74 69 70 6c  valuated multipl
198e0 65 20 74 69 6d 65 73 20 69 6e 20 74 68 65 20 73  e times in the s
198f0 65 63 6f 6e 64 3a 0a 0a 3c 75 6c 3e 3c 70 72 65  econd:..<ul><pre
19900 3e 0a 3c 6c 69 3e 43 41 53 45 20 78 20 57 48 45  >.<li>CASE x WHE
19910 4e 20 77 31 20 54 48 45 4e 20 72 31 20 57 48 45  N w1 THEN r1 WHE
19920 4e 20 77 32 20 54 48 45 4e 20 72 32 20 45 4c 53  N w2 THEN r2 ELS
19930 45 20 72 33 20 45 4e 44 0a 3c 6c 69 3e 43 41 53  E r3 END.<li>CAS
19940 45 20 57 48 45 4e 20 78 3d 77 31 20 54 48 45 4e  E WHEN x=w1 THEN
19950 20 72 31 20 57 48 45 4e 20 78 3d 77 32 20 54 48   r1 WHEN x=w2 TH
19960 45 4e 20 72 32 20 45 4c 53 45 20 72 33 20 45 4e  EN r2 ELSE r3 EN
19970 44 0a 3c 2f 70 72 65 3e 3c 2f 75 6c 3e 29 5e 0a  D.</pre></ul>)^.
19980 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
19990 6e 74 20 69 6e 5f 6f 70 20 7b 49 4e 20 6f 70 65  nt in_op {IN ope
199a0 72 61 74 6f 72 7d 20 7b 4e 4f 54 20 49 4e 20 6f  rator} {NOT IN o
199b0 70 65 72 61 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c  perator}</tcl>.<
199c0 68 33 3e 54 68 65 20 49 4e 20 61 6e 64 20 4e 4f  h3>The IN and NO
199d0 54 20 49 4e 20 6f 70 65 72 61 74 6f 72 73 3c 2f  T IN operators</
199e0 68 33 3e 0a 3c 70 3e 5e 54 68 65 20 49 4e 20 61  h3>.<p>^The IN a
199f0 6e 64 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74  nd NOT IN operat
19a00 6f 72 73 20 74 61 6b 65 20 61 6e 20 65 78 70 72  ors take an expr
19a10 65 73 73 69 6f 6e 20 6f 6e 20 74 68 65 0a 6c 65  ession on the.le
19a20 66 74 20 61 6e 64 20 61 20 6c 69 73 74 20 6f 66  ft and a list of
19a30 20 76 61 6c 75 65 73 20 6f 72 20 61 20 73 75 62   values or a sub
19a40 71 75 65 72 79 20 6f 6e 20 74 68 65 20 72 69 67  query on the rig
19a50 68 74 2e 0a 5e 57 68 65 6e 20 74 68 65 20 72 69  ht..^When the ri
19a60 67 68 74 20 6f 70 65 72 61 6e 64 20 6f 66 20 61  ght operand of a
19a70 6e 20 49 4e 20 6f 72 20 4e 4f 54 20 49 4e 20 6f  n IN or NOT IN o
19a80 70 65 72 61 74 6f 72 20 69 73 20 61 20 73 75 62  perator is a sub
19a90 71 75 65 72 79 2c 20 74 68 65 0a 73 75 62 71 75  query, the.subqu
19aa0 65 72 79 20 6d 75 73 74 20 68 61 76 65 20 74 68  ery must have th
19ab0 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66  e same number of
19ac0 20 63 6f 6c 75 6d 6e 73 20 61 73 20 74 68 65 72   columns as ther
19ad0 65 20 61 72 65 20 63 6f 6c 75 6d 6e 73 20 69 6e  e are columns in
19ae0 0a 74 68 65 20 5b 72 6f 77 20 76 61 6c 75 65 5d  .the [row value]
19af0 20 6f 66 20 74 68 65 20 6c 65 66 74 20 6f 70 65   of the left ope
19b00 72 61 6e 64 2e 20 20 5e 54 68 65 20 73 75 62 71  rand.  ^The subq
19b10 75 65 72 79 20 6f 6e 20 74 68 65 0a 72 69 67 68  uery on the.righ
19b20 74 20 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f  t of an IN or NO
19b30 54 20 49 4e 20 6f 70 65 72 61 74 6f 72 20 6d 75  T IN operator mu
19b40 73 74 20 62 65 20 61 20 73 63 61 6c 61 72 20 73  st be a scalar s
19b50 75 62 71 75 65 72 79 20 69 66 20 74 68 65 20 6c  ubquery if the l
19b60 65 66 74 0a 65 78 70 72 65 73 73 69 6f 6e 20 69  eft.expression i
19b70 73 20 6e 6f 74 20 61 20 5b 72 6f 77 20 76 61 6c  s not a [row val
19b80 75 65 5d 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a  ue] expression..
19b90 5e 49 66 20 74 68 65 20 72 69 67 68 74 20 6f 70  ^If the right op
19ba0 65 72 61 6e 64 20 6f 66 20 61 6e 20 49 4e 20 6f  erand of an IN o
19bb0 72 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74 6f  r NOT IN operato
19bc0 72 20 69 73 20 61 20 6c 69 73 74 20 6f 66 20 76  r is a list of v
19bd0 61 6c 75 65 73 2c 0a 65 61 63 68 20 6f 66 20 74  alues,.each of t
19be0 68 6f 73 65 20 76 61 6c 75 65 73 20 6d 75 73 74  hose values must
19bf0 20 62 65 20 73 63 61 6c 61 72 73 20 61 6e 64 20   be scalars and 
19c00 74 68 65 20 6c 65 66 74 20 65 78 70 72 65 73 73  the left express
19c10 69 6f 6e 20 6d 75 73 74 20 61 6c 73 6f 0a 62 65  ion must also.be
19c20 20 61 20 73 63 61 6c 61 72 2e 0a 5e 54 68 65 20   a scalar..^The 
19c30 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
19c40 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f 54 20  of an IN or NOT 
19c50 49 4e 20 6f 70 65 72 61 74 6f 72 20 63 61 6e 20  IN operator can 
19c60 62 65 20 61 0a 74 61 62 6c 65 20 3c 69 3e 6e 61  be a.table <i>na
19c70 6d 65 3c 2f 69 3e 20 6f 72 20 5b 74 61 62 6c 65  me</i> or [table
19c80 2d 76 61 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e  -valued function
19c90 5d 20 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 69 6e  ] <i>name</i> in
19ca0 20 77 68 69 63 68 20 0a 63 61 73 65 20 74 68 65   which .case the
19cb0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
19cc0 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 74   is understood t
19cd0 6f 20 62 65 20 73 75 62 71 75 65 72 79 20 6f 66  o be subquery of
19ce0 0a 74 68 65 20 66 6f 72 6d 20 22 28 53 45 4c 45  .the form "(SELE
19cf0 43 54 20 2a 20 46 52 4f 4d 20 3c 69 3e 6e 61 6d  CT * FROM <i>nam
19d00 65 3c 2f 69 3e 29 22 2e 0a 5e 57 68 65 6e 20 74  e</i>)"..^When t
19d10 68 65 20 72 69 67 68 74 20 6f 70 65 72 61 6e 64  he right operand
19d20 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 65 74   is an empty set
19d30 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
19d40 49 4e 20 69 73 20 66 61 6c 73 65 20 61 6e 64 20  IN is false and 
19d50 74 68 65 0a 72 65 73 75 6c 74 20 6f 66 20 4e 4f  the.result of NO
19d60 54 20 49 4e 20 69 73 20 74 72 75 65 2c 20 72 65  T IN is true, re
19d70 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
19d80 6c 65 66 74 20 6f 70 65 72 61 6e 64 20 61 6e 64  left operand and
19d90 20 65 76 65 6e 20 69 66 20 74 68 65 0a 6c 65 66   even if the.lef
19da0 74 20 6f 70 65 72 61 6e 64 20 69 73 20 4e 55 4c  t operand is NUL
19db0 4c 2e 0a 3c 70 3e 5e 28 54 68 65 20 72 65 73 75  L..<p>^(The resu
19dc0 6c 74 20 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e  lt of an IN or N
19dd0 4f 54 20 49 4e 20 6f 70 65 72 61 74 6f 72 20 69  OT IN operator i
19de0 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  s determined by 
19df0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 6d 61  the following.ma
19e00 74 72 69 78 3a 0a 0a 3c 63 65 6e 74 65 72 3e 0a  trix:..<center>.
19e10 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 3e  <table border=1>
19e20 0a 3c 74 72 3e 0a 3c 74 68 3e 4c 65 66 74 20 6f  .<tr>.<th>Left o
19e30 70 65 72 61 6e 64 20 3c 62 72 3e 69 73 20 4e 55  perand <br>is NU
19e40 4c 4c 0a 3c 74 68 3e 52 69 67 68 74 20 6f 70 65  LL.<th>Right ope
19e50 72 61 6e 64 20 3c 62 72 3e 63 6f 6e 74 61 69 6e  rand <br>contain
19e60 73 20 4e 55 4c 4c 0a 3c 74 68 3e 52 69 67 68 74  s NULL.<th>Right
19e70 20 6f 70 65 72 61 6e 64 20 3c 62 72 3e 69 73 20   operand <br>is 
19e80 61 6e 20 65 6d 70 74 79 20 73 65 74 0a 3c 74 68  an empty set.<th
19e90 3e 4c 65 66 74 20 6f 70 65 72 61 6e 64 20 66 6f  >Left operand fo
19ea0 75 6e 64 20 3c 62 72 3e 77 69 74 68 69 6e 20 72  und <br>within r
19eb0 69 67 68 74 20 6f 70 65 72 61 6e 64 0a 3c 74 68  ight operand.<th
19ec0 3e 52 65 73 75 6c 74 20 6f 66 20 3c 62 72 3e 49  >Result of <br>I
19ed0 4e 20 6f 70 65 72 61 74 6f 72 0a 3c 74 68 3e 52  N operator.<th>R
19ee0 65 73 75 6c 74 20 6f 66 20 3c 62 72 3e 4e 4f 54  esult of <br>NOT
19ef0 20 49 4e 20 6f 70 65 72 61 74 6f 72 0a 3c 74 72   IN operator.<tr
19f00 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e  >.<td align="cen
19f10 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67  ter">no.<td alig
19f20 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74  n="center">no.<t
19f30 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22  d align="center"
19f40 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  >no.<td align="c
19f50 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c  enter">no.<td al
19f60 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 66 61 6c  ign="center">fal
19f70 73 65 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65  se.<td align="ce
19f80 6e 74 65 72 22 3e 74 72 75 65 0a 3c 74 72 3e 0a  nter">true.<tr>.
19f90 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
19fa0 72 22 3e 64 6f 65 73 20 6e 6f 74 20 6d 61 74 74  r">does not matt
19fb0 65 72 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65  er.<td align="ce
19fc0 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69  nter">no.<td ali
19fd0 67 6e 3d 22 63 65 6e 74 65 72 22 3e 79 65 73 0a  gn="center">yes.
19fe0 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
19ff0 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d  r">no.<td align=
1a000 22 63 65 6e 74 65 72 22 3e 66 61 6c 73 65 0a 3c  "center">false.<
1a010 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
1a020 22 3e 74 72 75 65 0a 3c 74 72 3e 0a 3c 74 64 20  ">true.<tr>.<td 
1a030 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e  align="center">n
1a040 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e  o.<td align="cen
1a050 74 65 72 22 3e 64 6f 65 73 20 6e 6f 74 20 6d 61  ter">does not ma
1a060 74 74 65 72 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  tter.<td align="
1a070 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61  center">no.<td a
1a080 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 79 65  lign="center">ye
1a090 73 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e  s.<td align="cen
1a0a0 74 65 72 22 3e 74 72 75 65 0a 3c 74 64 20 61 6c  ter">true.<td al
1a0b0 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 66 61 6c  ign="center">fal
1a0c0 73 65 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67  se.<tr>.<td alig
1a0d0 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74  n="center">no.<t
1a0e0 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22  d align="center"
1a0f0 3e 79 65 73 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  >yes.<td align="
1a100 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61  center">no.<td a
1a110 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f  lign="center">no
1a120 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
1a130 65 72 22 3e 4e 55 4c 4c 0a 3c 74 64 20 61 6c 69  er">NULL.<td ali
1a140 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4e 55 4c 4c  gn="center">NULL
1a150 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d  .<tr>.<td align=
1a160 22 63 65 6e 74 65 72 22 3e 79 65 73 0a 3c 74 64  "center">yes.<td
1a170 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
1a180 64 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 0a  does not matter.
1a190 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
1a1a0 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d  r">no.<td align=
1a1b0 22 63 65 6e 74 65 72 22 3e 64 6f 65 73 20 6e 6f  "center">does no
1a1c0 74 20 6d 61 74 74 65 72 0a 3c 74 64 20 61 6c 69  t matter.<td ali
1a1d0 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4e 55 4c 4c  gn="center">NULL
1a1e0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
1a1f0 65 72 22 3e 4e 55 4c 4c 0a 3c 2f 74 61 62 6c 65  er">NULL.</table
1a200 3e 0a 3c 2f 63 65 6e 74 65 72 3e 29 5e 0a 0a 3c  >.</center>)^..<
1a210 70 3e 5e 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  p>^Note that SQL
1a220 69 74 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 70  ite allows the p
1a230 61 72 65 6e 74 68 65 73 69 7a 65 64 20 6c 69 73  arenthesized lis
1a240 74 20 6f 66 20 73 63 61 6c 61 72 20 76 61 6c 75  t of scalar valu
1a250 65 73 20 6f 6e 0a 74 68 65 20 72 69 67 68 74 2d  es on.the right-
1a260 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 6e 20  hand side of an 
1a270 49 4e 20 6f 72 20 4e 4f 54 20 49 4e 20 6f 70 65  IN or NOT IN ope
1a280 72 61 74 6f 72 20 74 6f 20 62 65 20 61 6e 20 65  rator to be an e
1a290 6d 70 74 79 20 6c 69 73 74 20 62 75 74 0a 6d 6f  mpty list but.mo
1a2a0 73 74 20 6f 74 68 65 72 20 53 51 4c 20 64 61 74  st other SQL dat
1a2b0 61 62 61 73 65 20 64 61 74 61 62 61 73 65 20 65  abase database e
1a2c0 6e 67 69 6e 65 73 20 61 6e 64 20 74 68 65 20 53  ngines and the S
1a2d0 51 4c 39 32 20 73 74 61 6e 64 61 72 64 20 72 65  QL92 standard re
1a2e0 71 75 69 72 65 0a 74 68 65 20 6c 69 73 74 20 74  quire.the list t
1a2f0 6f 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61  o contain at lea
1a300 73 74 20 6f 6e 65 20 65 6c 65 6d 65 6e 74 2e 3c  st one element.<
1a310 2f 70 3e 0a 0a 3c 68 33 3e 54 61 62 6c 65 20 43  /p>..<h3>Table C
1a320 6f 6c 75 6d 6e 20 4e 61 6d 65 73 3c 2f 68 33 3e  olumn Names</h3>
1a330 0a 0a 3c 70 3e 5e 41 20 63 6f 6c 75 6d 6e 20 6e  ..<p>^A column n
1a340 61 6d 65 20 63 61 6e 20 62 65 20 61 6e 79 20 6f  ame can be any o
1a350 66 20 74 68 65 20 6e 61 6d 65 73 20 64 65 66 69  f the names defi
1a360 6e 65 64 20 69 6e 20 74 68 65 20 5b 43 52 45 41  ned in the [CREA
1a370 54 45 20 54 41 42 4c 45 5d 0a 73 74 61 74 65 6d  TE TABLE].statem
1a380 65 6e 74 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ent or one of th
1a390 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 70 65 63  e following spec
1a3a0 69 61 6c 20 69 64 65 6e 74 69 66 69 65 72 73 3a  ial identifiers:
1a3b0 20 22 3c 62 3e 52 4f 57 49 44 3c 2f 62 3e 22 2c   "<b>ROWID</b>",
1a3c0 0a 22 3c 62 3e 4f 49 44 3c 2f 62 3e 22 2c 20 6f  ."<b>OID</b>", o
1a3d0 72 20 22 3c 62 3e 5f 52 4f 57 49 44 5f 3c 2f 62  r "<b>_ROWID_</b
1a3e0 3e 22 2e 0a 5e 54 68 65 20 74 68 72 65 65 20 73  >"..^The three s
1a3f0 70 65 63 69 61 6c 20 69 64 65 6e 74 69 66 69 65  pecial identifie
1a400 72 73 20 64 65 73 63 72 69 62 65 20 74 68 65 0a  rs describe the.
1a410 75 6e 69 71 75 65 20 69 6e 74 65 67 65 72 20 6b  unique integer k
1a420 65 79 20 28 74 68 65 20 5b 72 6f 77 69 64 5d 29  ey (the [rowid])
1a430 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a440 20 65 76 65 72 79 20 0a 72 6f 77 20 6f 66 20 65   every .row of e
1a450 76 65 72 79 20 74 61 62 6c 65 20 61 6e 64 20 73  very table and s
1a460 6f 20 61 72 65 20 6e 6f 74 20 61 76 61 69 6c 61  o are not availa
1a470 62 6c 65 20 6f 6e 20 5b 57 49 54 48 4f 55 54 20  ble on [WITHOUT 
1a480 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 2e 0a 5e  ROWID] tables..^
1a490 54 68 65 20 73 70 65 63 69 61 6c 20 69 64 65 6e  The special iden
1a4a0 74 69 66 69 65 72 73 20 6f 6e 6c 79 20 72 65 66  tifiers only ref
1a4b0 65 72 20 74 6f 20 74 68 65 20 72 6f 77 20 6b 65  er to the row ke
1a4c0 79 20 69 66 20 74 68 65 20 5b 43 52 45 41 54 45  y if the [CREATE
1a4d0 20 54 41 42 4c 45 5d 0a 73 74 61 74 65 6d 65 6e   TABLE].statemen
1a4e0 74 20 64 6f 65 73 20 6e 6f 74 20 64 65 66 69 6e  t does not defin
1a4f0 65 20 61 20 72 65 61 6c 20 63 6f 6c 75 6d 6e 20  e a real column 
1a500 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
1a510 6d 65 2e 0a 5e 54 68 65 20 72 6f 77 69 64 20 63  me..^The rowid c
1a520 61 6e 20 62 65 20 75 73 65 64 20 61 6e 79 77 68  an be used anywh
1a530 65 72 65 20 61 20 72 65 67 75 6c 61 72 0a 63 6f  ere a regular.co
1a540 6c 75 6d 6e 20 63 61 6e 20 62 65 20 75 73 65 64  lumn can be used
1a550 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
1a560 72 61 67 6d 65 6e 74 20 65 78 69 73 74 73 5f 6f  ragment exists_o
1a570 70 20 7b 45 58 49 53 54 53 20 6f 70 65 72 61 74  p {EXISTS operat
1a580 6f 72 7d 20 7b 4e 4f 54 20 45 58 49 53 54 53 20  or} {NOT EXISTS 
1a590 6f 70 65 72 61 74 6f 72 7d 3c 2f 74 63 6c 3e 0a  operator}</tcl>.
1a5a0 3c 68 33 3e 54 68 65 20 45 58 49 53 54 53 20 6f  <h3>The EXISTS o
1a5b0 70 65 72 61 74 6f 72 3c 2f 68 33 3e 0a 0a 3c 70  perator</h3>..<p
1a5c0 3e 5e 54 68 65 20 45 58 49 53 54 53 20 6f 70 65  >^The EXISTS ope
1a5d0 72 61 74 6f 72 20 61 6c 77 61 79 73 20 65 76 61  rator always eva
1a5e0 6c 75 61 74 65 73 20 74 6f 20 6f 6e 65 20 6f 66  luates to one of
1a5f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   the integer val
1a600 75 65 73 20 30 20 0a 61 6e 64 20 31 2e 20 5e 49  ues 0 .and 1. ^I
1a610 66 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20  f executing the 
1a620 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1a630 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
1a640 65 20 72 69 67 68 74 2d 68 61 6e 64 20 0a 6f 70  e right-hand .op
1a650 65 72 61 6e 64 20 6f 66 20 74 68 65 20 45 58 49  erand of the EXI
1a660 53 54 53 20 6f 70 65 72 61 74 6f 72 20 77 6f 75  STS operator wou
1a670 6c 64 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 72  ld return one or
1a680 20 6d 6f 72 65 20 72 6f 77 73 2c 20 74 68 65 6e   more rows, then
1a690 20 74 68 65 0a 45 58 49 53 54 53 20 6f 70 65 72   the.EXISTS oper
1a6a0 61 74 6f 72 20 65 76 61 6c 75 61 74 65 73 20 74  ator evaluates t
1a6b0 6f 20 31 2e 20 5e 49 66 20 65 78 65 63 75 74 69  o 1. ^If executi
1a6c0 6e 67 20 74 68 65 20 53 45 4c 45 43 54 20 77 6f  ng the SELECT wo
1a6d0 75 6c 64 20 72 65 74 75 72 6e 0a 6e 6f 20 72 6f  uld return.no ro
1a6e0 77 73 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20  ws at all, then 
1a6f0 74 68 65 20 45 58 49 53 54 53 20 6f 70 65 72 61  the EXISTS opera
1a700 74 6f 72 20 65 76 61 6c 75 61 74 65 73 20 74 6f  tor evaluates to
1a710 20 30 2e 20 0a 0a 3c 70 3e 5e 54 68 65 20 6e 75   0. ..<p>^The nu
1a720 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1a730 69 6e 20 65 61 63 68 20 72 6f 77 20 72 65 74 75  in each row retu
1a740 72 6e 65 64 20 62 79 20 74 68 65 20 53 45 4c 45  rned by the SELE
1a750 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 28 69 66  CT statement.(if
1a760 20 61 6e 79 29 20 61 6e 64 20 74 68 65 20 73 70   any) and the sp
1a770 65 63 69 66 69 63 20 76 61 6c 75 65 73 20 72 65  ecific values re
1a780 74 75 72 6e 65 64 20 68 61 76 65 20 6e 6f 20 65  turned have no e
1a790 66 66 65 63 74 20 6f 6e 20 74 68 65 20 72 65 73  ffect on the res
1a7a0 75 6c 74 73 0a 6f 66 20 74 68 65 20 45 58 49 53  ults.of the EXIS
1a7b0 54 53 20 6f 70 65 72 61 74 6f 72 2e 20 5e 49 6e  TS operator. ^In
1a7c0 20 70 61 72 74 69 63 75 6c 61 72 2c 20 72 6f 77   particular, row
1a7d0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 4e 55 4c  s containing NUL
1a7e0 4c 20 76 61 6c 75 65 73 20 61 72 65 0a 6e 6f 74  L values are.not
1a7f0 20 68 61 6e 64 6c 65 64 20 61 6e 79 20 64 69 66   handled any dif
1a800 66 65 72 65 6e 74 6c 79 20 66 72 6f 6d 20 72 6f  ferently from ro
1a810 77 73 20 77 69 74 68 6f 75 74 20 4e 55 4c 4c 20  ws without NULL 
1a820 76 61 6c 75 65 73 2e 0a 0a 3c 74 63 6c 3e 68 64  values...<tcl>hd
1a830 5f 66 72 61 67 6d 65 6e 74 20 73 75 62 71 20 7b  _fragment subq {
1a840 53 75 62 71 75 65 72 69 65 73 7d 3c 2f 74 63 6c  Subqueries}</tcl
1a850 3e 0a 3c 68 33 3e 53 75 62 71 75 65 72 79 20 45  >.<h3>Subquery E
1a860 78 70 72 65 73 73 69 6f 6e 73 3c 2f 68 33 3e 0a  xpressions</h3>.
1a870 0a 3c 70 3e 5e 41 20 5b 53 45 4c 45 43 54 5d 20  .<p>^A [SELECT] 
1a880 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6c 6f 73  statement enclos
1a890 65 64 20 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ed in parenthese
1a8a0 73 20 69 73 20 61 20 73 75 62 71 75 65 72 79 2e  s is a subquery.
1a8b0 0a 5e 41 6c 6c 20 74 79 70 65 73 20 6f 66 20 53  .^All types of S
1a8c0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c  ELECT statement,
1a8d0 20 69 6e 63 6c 75 64 69 6e 67 0a 61 67 67 72 65   including.aggre
1a8e0 67 61 74 65 20 61 6e 64 20 63 6f 6d 70 6f 75 6e  gate and compoun
1a8f0 64 20 53 45 4c 45 43 54 20 71 75 65 72 69 65 73  d SELECT queries
1a900 20 28 71 75 65 72 69 65 73 20 77 69 74 68 20 6b   (queries with k
1a910 65 79 77 6f 72 64 73 20 6c 69 6b 65 0a 55 4e 49  eywords like.UNI
1a920 4f 4e 20 6f 72 20 45 58 43 45 50 54 29 20 61 72  ON or EXCEPT) ar
1a930 65 20 61 6c 6c 6f 77 65 64 20 61 73 20 73 63 61  e allowed as sca
1a940 6c 61 72 20 73 75 62 71 75 65 72 69 65 73 2e 0a  lar subqueries..
1a950 5e 54 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20  ^The value of a 
1a960 73 75 62 71 75 65 72 79 20 65 78 70 72 65 73 73  subquery express
1a970 69 6f 6e 20 69 73 20 74 68 65 20 66 69 72 73 74  ion is the first
1a980 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
1a990 6c 74 0a 66 72 6f 6d 20 74 68 65 20 65 6e 63 6c  lt.from the encl
1a9a0 6f 73 65 64 20 5b 53 45 4c 45 43 54 5d 20 73 74  osed [SELECT] st
1a9b0 61 74 65 6d 65 6e 74 2e 0a 5e 54 68 65 20 76 61  atement..^The va
1a9c0 6c 75 65 20 6f 66 20 61 20 73 75 62 71 75 65 72  lue of a subquer
1a9d0 79 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  y expression is 
1a9e0 4e 55 4c 4c 20 69 66 20 74 68 65 20 65 6e 63 6c  NULL if the encl
1a9f0 6f 73 65 64 0a 5b 53 45 4c 45 43 54 5d 20 73 74  osed.[SELECT] st
1aa00 61 74 65 6d 65 6e 74 20 72 65 74 75 72 6e 73 20  atement returns 
1aa10 6e 6f 20 72 6f 77 73 2e 0a 0a 3c 70 3e 41 20 73  no rows...<p>A s
1aa20 75 62 71 75 65 72 79 20 74 68 61 74 20 72 65 74  ubquery that ret
1aa30 75 72 6e 73 20 61 20 73 69 6e 67 6c 65 20 63 6f  urns a single co
1aa40 6c 75 6d 6e 20 69 73 20 61 20 73 63 61 6c 61 72  lumn is a scalar
1aa50 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 63 61   subquery and ca
1aa60 6e 0a 62 65 20 75 73 65 64 20 6d 6f 73 74 20 61  n.be used most a
1aa70 6e 79 77 68 65 72 65 2e 0a 5e 41 20 73 75 62 71  nywhere..^A subq
1aa80 75 65 72 79 20 74 68 61 74 20 72 65 74 75 72 6e  uery that return
1aa90 73 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  s two or more co
1aaa0 6c 75 6d 6e 73 20 69 73 20 61 20 5b 72 6f 77 20  lumns is a [row 
1aab0 76 61 6c 75 65 5d 0a 73 75 62 71 75 65 72 79 20  value].subquery 
1aac0 61 6e 64 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  and can only be 
1aad0 75 73 65 64 20 61 73 20 74 68 65 20 6f 70 65 72  used as the oper
1aae0 61 6e 64 20 6f 66 20 61 20 63 6f 6d 70 61 72 69  and of a compari
1aaf0 73 6f 6e 20 6f 70 65 72 61 74 6f 72 2e 0a 0a 3c  son operator...<
1ab00 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
1ab10 63 6f 73 75 62 20 7b 63 6f 72 72 65 6c 61 74 65  cosub {correlate
1ab20 64 20 73 75 62 71 75 65 72 69 65 73 7d 3c 2f 74  d subqueries}</t
1ab30 63 6c 3e 0a 3c 68 33 3e 43 6f 72 72 65 6c 61 74  cl>.<h3>Correlat
1ab40 65 64 20 53 75 62 71 75 65 72 69 65 73 3c 2f 68  ed Subqueries</h
1ab50 33 3e 0a 0a 3c 70 3e 5e 41 20 5b 53 45 4c 45 43  3>..<p>^A [SELEC
1ab60 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 75 73 65  T] statement use
1ab70 64 20 61 73 20 65 69 74 68 65 72 20 61 20 73 63  d as either a sc
1ab80 61 6c 61 72 20 73 75 62 71 75 65 72 79 20 6f 72  alar subquery or
1ab90 20 61 73 20 74 68 65 20 0a 72 69 67 68 74 2d 68   as the .right-h
1aba0 61 6e 64 20 6f 70 65 72 61 6e 64 20 6f 66 20 61  and operand of a
1abb0 6e 20 49 4e 2c 20 4e 4f 54 20 49 4e 20 6f 72 20  n IN, NOT IN or 
1abc0 45 58 49 53 54 53 20 65 78 70 72 65 73 73 69 6f  EXISTS expressio
1abd0 6e 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 0a 72  n may contain .r
1abe0 65 66 65 72 65 6e 63 65 73 20 74 6f 20 63 6f 6c  eferences to col
1abf0 75 6d 6e 73 20 69 6e 20 74 68 65 20 6f 75 74 65  umns in the oute
1ac00 72 20 71 75 65 72 79 2e 20 53 75 63 68 20 61 20  r query. Such a 
1ac10 73 75 62 71 75 65 72 79 20 69 73 20 6b 6e 6f 77  subquery is know
1ac20 6e 20 61 73 0a 61 20 63 6f 72 72 65 6c 61 74 65  n as.a correlate
1ac30 64 20 73 75 62 71 75 65 72 79 2e 20 5e 41 20 63  d subquery. ^A c
1ac40 6f 72 72 65 6c 61 74 65 64 20 73 75 62 71 75 65  orrelated subque
1ac50 72 79 20 69 73 20 72 65 65 76 61 6c 75 61 74 65  ry is reevaluate
1ac60 64 20 65 61 63 68 20 74 69 6d 65 0a 69 74 73 20  d each time.its 
1ac70 72 65 73 75 6c 74 20 69 73 20 72 65 71 75 69 72  result is requir
1ac80 65 64 2e 20 5e 41 6e 20 75 6e 63 6f 72 72 65 6c  ed. ^An uncorrel
1ac90 61 74 65 64 20 73 75 62 71 75 65 72 79 20 69 73  ated subquery is
1aca0 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 6c 79 20   evaluated only 
1acb0 6f 6e 63 65 0a 61 6e 64 20 74 68 65 20 72 65 73  once.and the res
1acc0 75 6c 74 20 72 65 75 73 65 64 20 61 73 20 6e 65  ult reused as ne
1acd0 63 65 73 73 61 72 79 2e 0a 0a 3c 74 63 6c 3e 68  cessary...<tcl>h
1ace0 64 5f 66 72 61 67 6d 65 6e 74 20 63 61 73 74 65  d_fragment caste
1acf0 78 70 72 20 7b 43 41 53 54 20 65 78 70 72 65 73  xpr {CAST expres
1ad00 73 69 6f 6e 7d 20 7b 43 41 53 54 7d 20 7b 63 61  sion} {CAST} {ca
1ad10 73 74 7d 20 7b 43 41 53 54 20 6f 70 65 72 61 74  st} {CAST operat
1ad20 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 43 41  or}</tcl>.<h3>CA
1ad30 53 54 20 65 78 70 72 65 73 73 69 6f 6e 73 3c 2f  ST expressions</
1ad40 68 33 3e 0a 0a 3c 70 3e 41 20 43 41 53 54 20 65  h3>..<p>A CAST e
1ad50 78 70 72 65 73 73 69 6f 6e 20 6f 66 20 74 68 65  xpression of the
1ad60 20 66 6f 72 6d 20 22 43 41 53 54 28 3c 69 3e 65   form "CAST(<i>e
1ad70 78 70 72 3c 2f 69 3e 20 41 53 20 3c 69 3e 74 79  xpr</i> AS <i>ty
1ad80 70 65 2d 6e 61 6d 65 3c 2f 69 3e 29 22 0a 69 73  pe-name</i>)".is
1ad90 20 75 73 65 64 20 74 6f 20 63 6f 6e 76 65 72 74   used to convert
1ada0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 3c 69   the value of <i
1adb0 3e 65 78 70 72 3c 2f 69 3e 20 74 6f 20 0a 61 20  >expr</i> to .a 
1adc0 64 69 66 66 65 72 65 6e 74 20 5b 73 74 6f 72 61  different [stora
1add0 67 65 20 63 6c 61 73 73 5d 20 73 70 65 63 69 66  ge class] specif
1ade0 69 65 64 20 62 79 20 3c 79 79 74 65 72 6d 3e 74  ied by <yyterm>t
1adf0 79 70 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  ype-name</yyterm
1ae00 3e 2e 0a 5e 41 20 43 41 53 54 20 63 6f 6e 76 65  >..^A CAST conve
1ae10 72 73 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72  rsion is similar
1ae20 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69   to the conversi
1ae30 6f 6e 20 74 68 61 74 20 74 61 6b 65 73 0a 70 6c  on that takes.pl
1ae40 61 63 65 20 77 68 65 6e 20 61 20 5b 63 6f 6c 75  ace when a [colu
1ae50 6d 6e 20 61 66 66 69 6e 69 74 79 5d 20 69 73 20  mn affinity] is 
1ae60 61 70 70 6c 69 65 64 20 74 6f 20 61 20 76 61 6c  applied to a val
1ae70 75 65 20 65 78 63 65 70 74 20 74 68 61 74 20 77  ue except that w
1ae80 69 74 68 0a 74 68 65 20 43 41 53 54 20 6f 70 65  ith.the CAST ope
1ae90 72 61 74 6f 72 20 74 68 65 20 63 6f 6e 76 65 72  rator the conver
1aea0 73 69 6f 6e 20 61 6c 77 61 79 73 20 74 61 6b 65  sion always take
1aeb0 73 20 70 6c 61 63 65 20 65 76 65 6e 20 69 66 20  s place even if 
1aec0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 6c  the conversion.l
1aed0 6f 73 73 79 20 61 6e 64 20 69 72 72 65 76 65 72  ossy and irrever
1aee0 73 69 62 6c 65 2c 20 77 68 65 72 65 61 73 20 63  sible, whereas c
1aef0 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79 20 6f  olumn affinity o
1af00 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 65 20  nly changes the 
1af10 64 61 74 61 20 74 79 70 65 0a 6f 66 20 61 20 76  data type.of a v
1af20 61 6c 75 65 20 69 66 20 74 68 65 20 63 68 61 6e  alue if the chan
1af30 67 65 20 69 73 20 6c 6f 73 73 6c 65 73 73 20 61  ge is lossless a
1af40 6e 64 20 72 65 76 65 72 73 69 62 6c 65 2e 0a 0a  nd reversible...
1af50 3c 70 3e 5e 49 66 20 74 68 65 20 76 61 6c 75 65  <p>^If the value
1af60 20 6f 66 20 3c 69 3e 65 78 70 72 3c 2f 69 3e 20   of <i>expr</i> 
1af70 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  is NULL, then th
1af80 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
1af90 43 41 53 54 0a 65 78 70 72 65 73 73 69 6f 6e 20  CAST.expression 
1afa0 69 73 20 61 6c 73 6f 20 4e 55 4c 4c 2e 20 5e 4f  is also NULL. ^O
1afb0 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 73 74  therwise, the st
1afc0 6f 72 61 67 65 20 63 6c 61 73 73 20 6f 66 20 74  orage class of t
1afd0 68 65 20 72 65 73 75 6c 74 0a 69 73 20 64 65 74  he result.is det
1afe0 65 72 6d 69 6e 65 64 20 62 79 20 61 70 70 6c 79  ermined by apply
1aff0 69 6e 67 20 74 68 65 20 5b 72 75 6c 65 73 20 66  ing the [rules f
1b000 6f 72 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 63  or determining c
1b010 6f 6c 75 6d 6e 20 61 66 66 69 6e 69 74 79 5d 20  olumn affinity] 
1b020 74 6f 0a 74 68 65 20 3c 79 79 74 65 72 6d 3e 74  to.the <yyterm>t
1b030 79 70 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  ype-name</yyterm
1b040 3e 2e 0a 0a 3c 74 61 62 6c 65 20 62 6f 72 64 65  >...<table borde
1b050 72 3d 31 3e 0a 3c 74 72 3e 0a 20 20 3c 74 68 3e  r=1>.<tr>.  <th>
1b060 20 41 66 66 69 6e 69 74 79 20 6f 66 20 3c 79 79   Affinity of <yy
1b070 74 65 72 6d 3e 3c 6e 6f 62 72 3e 74 79 70 65 2d  term><nobr>type-
1b080 6e 61 6d 65 3c 2f 6e 6f 62 72 3e 3c 2f 79 79 74  name</nobr></yyt
1b090 65 72 6d 3e 0a 20 20 3c 74 68 3e 20 43 6f 6e 76  erm>.  <th> Conv
1b0a0 65 72 73 69 6f 6e 20 50 72 6f 63 65 73 73 69 6e  ersion Processin
1b0b0 67 0a 3c 74 72 3e 0a 20 20 3c 74 64 3e 20 4e 4f  g.<tr>.  <td> NO
1b0c0 4e 45 20 0a 20 20 3c 74 64 3e 20 5e 43 61 73 74  NE .  <td> ^Cast
1b0d0 69 6e 67 20 61 20 76 61 6c 75 65 20 74 6f 20 61  ing a value to a
1b0e0 20 3c 79 79 74 65 72 6d 3e 74 79 70 65 2d 6e 61   <yyterm>type-na
1b0f0 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 77 69 74 68  me</yyterm> with
1b100 20 6e 6f 20 61 66 66 69 6e 69 74 79 20 0a 20 20   no affinity .  
1b110 63 61 75 73 65 73 20 74 68 65 20 76 61 6c 75 65  causes the value
1b120 20 74 6f 0a 20 20 62 65 20 63 6f 6e 76 65 72 74   to.  be convert
1b130 65 64 20 69 6e 74 6f 20 61 20 42 4c 4f 42 2e 20  ed into a BLOB. 
1b140 20 5e 43 61 73 74 69 6e 67 20 74 6f 20 61 20 42   ^Casting to a B
1b150 4c 4f 42 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  LOB consists of 
1b160 66 69 72 73 74 20 63 61 73 74 69 6e 67 0a 20 20  first casting.  
1b170 74 68 65 20 76 61 6c 75 65 20 74 6f 20 54 45 58  the value to TEX
1b180 54 20 69 6e 20 74 68 65 20 5b 65 6e 63 6f 64 69  T in the [encodi
1b190 6e 67 5d 20 6f 66 20 74 68 65 20 64 61 74 61 62  ng] of the datab
1b1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
1b1b0 74 68 65 6e 0a 20 20 69 6e 74 65 72 70 72 65 74  then.  interpret
1b1c0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 69 6e  ing the resultin
1b1d0 67 20 62 79 74 65 20 73 65 71 75 65 6e 63 65 20  g byte sequence 
1b1e0 61 73 20 61 20 42 4c 4f 42 20 69 6e 73 74 65 61  as a BLOB instea
1b1f0 64 20 6f 66 20 61 73 20 54 45 58 54 2e 0a 0a 3c  d of as TEXT...<
1b200 74 72 3e 0a 20 20 3c 74 64 3e 20 54 45 58 54 0a  tr>.  <td> TEXT.
1b210 20 20 3c 74 64 3e 20 5e 54 6f 20 63 61 73 74 20    <td> ^To cast 
1b220 61 20 42 4c 4f 42 20 76 61 6c 75 65 20 74 6f 20  a BLOB value to 
1b230 54 45 58 54 2c 20 74 68 65 20 73 65 71 75 65 6e  TEXT, the sequen
1b240 63 65 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  ce of bytes that
1b250 20 6d 61 6b 65 20 75 70 20 74 68 65 0a 20 20 42   make up the.  B
1b260 4c 4f 42 20 69 73 20 69 6e 74 65 72 70 72 65 74  LOB is interpret
1b270 65 64 20 61 73 20 74 65 78 74 20 65 6e 63 6f 64  ed as text encod
1b280 65 64 20 75 73 69 6e 67 20 74 68 65 20 64 61 74  ed using the dat
1b290 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 2e 0a  abase encoding..
1b2a0 20 20 3c 70 3e 0a 20 20 20 5e 43 61 73 74 69 6e    <p>.   ^Castin
1b2b0 67 20 61 6e 20 49 4e 54 45 47 45 52 20 6f 72 20  g an INTEGER or 
1b2c0 52 45 41 4c 20 76 61 6c 75 65 20 69 6e 74 6f 20  REAL value into 
1b2d0 54 45 58 54 20 72 65 6e 64 65 72 73 20 74 68 65  TEXT renders the
1b2e0 20 76 61 6c 75 65 20 61 73 20 69 66 20 76 69 61   value as if via
1b2f0 20 0a 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73   .    [sqlite3_s
1b300 6e 70 72 69 6e 74 66 28 29 5d 20 65 78 63 65 70  nprintf()] excep
1b310 74 20 74 68 61 74 20 74 68 65 20 72 65 73 75 6c  t that the resul
1b320 74 69 6e 67 20 54 45 58 54 20 75 73 65 73 20 74  ting TEXT uses t
1b330 68 65 20 5b 65 6e 63 6f 64 69 6e 67 5d 20 6f 66  he [encoding] of
1b340 0a 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73  .    the databas
1b350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 0a 3c  e connection...<
1b360 74 72 3e 0a 20 20 3c 74 64 3e 20 52 45 41 4c 0a  tr>.  <td> REAL.
1b370 20 20 3c 74 64 3e 20 5e 57 68 65 6e 20 63 61 73    <td> ^When cas
1b380 74 69 6e 67 20 61 20 42 4c 4f 42 20 76 61 6c 75  ting a BLOB valu
1b390 65 20 74 6f 20 61 20 52 45 41 4c 2c 20 74 68 65  e to a REAL, the
1b3a0 20 76 61 6c 75 65 20 69 73 20 66 69 72 73 74 20   value is first 
1b3b0 63 6f 6e 76 65 72 74 65 64 20 74 6f 0a 20 20 20  converted to.   
1b3c0 20 20 20 20 20 54 45 58 54 2e 0a 20 20 20 20 20       TEXT..     
1b3d0 20 20 3c 70 3e 5e 57 68 65 6e 20 63 61 73 74 69    <p>^When casti
1b3e0 6e 67 20 61 20 54 45 58 54 20 76 61 6c 75 65 20  ng a TEXT value 
1b3f0 74 6f 20 52 45 41 4c 2c 20 74 68 65 20 6c 6f 6e  to REAL, the lon
1b400 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 70 72  gest possible pr
1b410 65 66 69 78 20 6f 66 0a 20 20 20 20 20 20 20 20  efix of.        
1b420 74 68 65 20 76 61 6c 75 65 20 74 68 61 74 20 63  the value that c
1b430 61 6e 20 62 65 20 69 6e 74 65 72 70 72 65 74 65  an be interprete
1b440 64 20 61 73 20 61 20 72 65 61 6c 20 6e 75 6d 62  d as a real numb
1b450 65 72 20 69 73 20 65 78 74 72 61 63 74 65 64 20  er is extracted 
1b460 66 72 6f 6d 0a 20 20 20 20 20 20 20 20 74 68 65  from.        the
1b470 20 54 45 58 54 20 76 61 6c 75 65 20 61 6e 64 20   TEXT value and 
1b480 74 68 65 20 72 65 6d 61 69 6e 64 65 72 20 69 67  the remainder ig
1b490 6e 6f 72 65 64 2e 20 5e 41 6e 79 20 6c 65 61 64  nored. ^Any lead
1b4a0 69 6e 67 20 73 70 61 63 65 73 20 69 6e 20 74 68  ing spaces in th
1b4b0 65 0a 20 20 20 20 20 20 20 20 54 45 58 54 20 76  e.        TEXT v
1b4c0 61 6c 75 65 20 61 72 65 20 69 67 6e 6f 72 65 64  alue are ignored
1b4d0 20 77 68 65 6e 20 63 6f 6e 76 65 72 67 69 6e 67   when converging
1b4e0 20 66 72 6f 6d 20 54 45 58 54 20 74 6f 20 52 45   from TEXT to RE
1b4f0 41 4c 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  AL. ^(If there i
1b500 73 0a 20 20 20 20 20 20 20 20 6e 6f 20 70 72 65  s.        no pre
1b510 66 69 78 20 74 68 61 74 20 63 61 6e 20 62 65 20  fix that can be 
1b520 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1b530 20 72 65 61 6c 20 6e 75 6d 62 65 72 2c 20 74 68   real number, th
1b540 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 0a  e result of the.
1b550 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 73 69          conversi
1b560 6f 6e 20 69 73 20 30 2e 30 2e 29 5e 0a 0a 3c 74  on is 0.0.)^..<t
1b570 72 3e 0a 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  r>.  <td> INTEGE
1b580 52 0a 20 20 3c 74 64 3e 20 5e 57 68 65 6e 20 63  R.  <td> ^When c
1b590 61 73 74 69 6e 67 20 61 20 42 4c 4f 42 20 76 61  asting a BLOB va
1b5a0 6c 75 65 20 74 6f 20 49 4e 54 45 47 45 52 2c 20  lue to INTEGER, 
1b5b0 74 68 65 20 76 61 6c 75 65 20 69 73 20 66 69 72  the value is fir
1b5c0 73 74 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 0a  st converted to.
1b5d0 20 20 20 20 20 20 20 20 54 45 58 54 2e 0a 20 20          TEXT..  
1b5e0 20 20 20 20 20 3c 70 3e 5e 57 68 65 6e 20 63 61       <p>^When ca
1b5f0 73 74 69 6e 67 20 61 20 54 45 58 54 20 76 61 6c  sting a TEXT val
1b600 75 65 20 74 6f 20 49 4e 54 45 47 45 52 2c 20 74  ue to INTEGER, t
1b610 68 65 20 6c 6f 6e 67 65 73 74 20 70 6f 73 73 69  he longest possi
1b620 62 6c 65 20 70 72 65 66 69 78 20 6f 66 0a 20 20  ble prefix of.  
1b630 20 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20        the value 
1b640 74 68 61 74 20 63 61 6e 20 62 65 20 69 6e 74 65  that can be inte
1b650 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 69 6e  rpreted as an in
1b660 74 65 67 65 72 20 6e 75 6d 62 65 72 20 69 73 20  teger number is 
1b670 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 0a 20  extracted from. 
1b680 20 20 20 20 20 20 20 74 68 65 20 54 45 58 54 20         the TEXT 
1b690 76 61 6c 75 65 20 61 6e 64 20 74 68 65 20 72 65  value and the re
1b6a0 6d 61 69 6e 64 65 72 20 69 67 6e 6f 72 65 64 2e  mainder ignored.
1b6b0 20 5e 41 6e 79 20 6c 65 61 64 69 6e 67 20 73 70   ^Any leading sp
1b6c0 61 63 65 73 20 69 6e 20 74 68 65 0a 20 20 20 20  aces in the.    
1b6d0 20 20 20 20 54 45 58 54 20 76 61 6c 75 65 20 77      TEXT value w
1b6e0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 20 66  hen converting f
1b6f0 72 6f 6d 20 54 45 58 54 20 74 6f 20 49 4e 54 45  rom TEXT to INTE
1b700 47 45 52 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  GER are ignored.
1b710 20 5e 49 66 20 74 68 65 72 65 0a 20 20 20 20 20   ^If there.     
1b720 20 20 20 69 73 20 6e 6f 20 70 72 65 66 69 78 20     is no prefix 
1b730 74 68 61 74 20 63 61 6e 20 62 65 20 69 6e 74 65  that can be inte
1b740 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 69 6e  rpreted as an in
1b750 74 65 67 65 72 20 6e 75 6d 62 65 72 2c 20 74 68  teger number, th
1b760 65 20 72 65 73 75 6c 74 0a 20 20 20 20 20 20 20  e result.       
1b770 20 6f 66 20 74 68 65 20 63 6f 6e 76 65 72 73 69   of the conversi
1b780 6f 6e 20 69 73 20 30 2e 20 20 5e 49 66 20 74 68  on is 0.  ^If th
1b790 65 20 70 72 65 66 69 78 20 69 6e 74 65 67 65 72  e prefix integer
1b7a0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1b7b0 0a 20 20 20 20 20 20 20 20 2b 39 32 32 33 33 37  .        +922337
1b7c0 32 30 33 36 38 35 34 37 37 35 38 30 37 20 74 68  2036854775807 th
1b7d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  en the result of
1b7e0 20 74 68 65 20 63 61 73 74 20 69 73 20 65 78 61   the cast is exa
1b7f0 63 74 6c 79 0a 20 20 20 20 20 20 20 20 2b 39 32  ctly.        +92
1b800 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
1b810 37 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20  7.  ^Similarly, 
1b820 69 66 20 74 68 65 20 70 72 65 66 69 78 20 69 6e  if the prefix in
1b830 74 65 67 65 72 20 69 73 0a 20 20 20 20 20 20 20  teger is.       
1b840 20 6c 65 73 73 20 74 68 61 6e 20 2d 39 32 32 33   less than -9223
1b850 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20  372036854775808 
1b860 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 20  then the result 
1b870 6f 66 20 74 68 65 20 63 61 73 74 20 69 73 0a 20  of the cast is. 
1b880 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 2d         exactly -
1b890 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
1b8a0 38 30 38 2e 0a 0a 20 20 20 20 20 20 20 20 3c 70  808...        <p
1b8b0 3e 5e 57 68 65 6e 20 63 61 73 74 69 6e 67 20 74  >^When casting t
1b8c0 6f 20 49 4e 54 45 47 45 52 2c 20 69 66 20 74 68  o INTEGER, if th
1b8d0 65 20 74 65 78 74 20 6c 6f 6f 6b 73 20 6c 69 6b  e text looks lik
1b8e0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
1b8f0 6e 74 0a 20 20 20 20 20 20 20 20 76 61 6c 75 65  nt.        value
1b900 20 77 69 74 68 20 61 6e 20 65 78 70 6f 6e 65 6e   with an exponen
1b910 74 2c 20 74 68 65 20 65 78 70 6f 6e 65 6e 74 20  t, the exponent 
1b920 77 69 6c 6c 20 62 65 20 69 67 6e 6f 72 65 64 20  will be ignored 
1b930 62 65 63 61 75 73 65 20 69 74 20 69 73 0a 20 20  because it is.  
1b940 20 20 20 20 20 20 6e 6f 20 70 61 72 74 20 6f 66        no part of
1b950 20 74 68 65 20 69 6e 74 65 67 65 72 20 70 72 65   the integer pre
1b960 66 69 78 2e 20 20 5e 46 6f 72 20 65 78 61 6d 70  fix.  ^For examp
1b970 6c 65 2c 0a 20 20 20 20 20 20 20 20 22 28 43 41  le,.        "(CA
1b980 53 54 20 27 31 32 33 65 2b 35 27 20 41 53 20 49  ST '123e+5' AS I
1b990 4e 54 45 47 45 52 29 22 20 72 65 73 75 6c 74 73  NTEGER)" results
1b9a0 20 69 6e 20 31 32 33 2c 20 6e 6f 74 20 69 6e 20   in 123, not in 
1b9b0 31 32 33 30 30 30 30 30 2e 0a 0a 20 20 20 20 20  12300000...     
1b9c0 20 20 20 3c 70 3e 20 5e 28 54 68 65 20 43 41 53     <p> ^(The CAS
1b9d0 54 20 6f 70 65 72 61 74 6f 72 20 75 6e 64 65 72  T operator under
1b9e0 73 74 61 6e 64 73 20 64 65 63 69 6d 61 6c 0a 20  stands decimal. 
1b9f0 20 20 20 20 20 20 20 69 6e 74 65 67 65 72 73 20         integers 
1ba00 6f 6e 6c 79 20 26 6d 64 61 73 68 3b 20 63 6f 6e  only &mdash; con
1ba10 76 65 72 73 69 6f 6e 20 6f 66 20 5b 68 65 78 61  version of [hexa
1ba20 64 65 63 69 6d 61 6c 20 69 6e 74 65 67 65 72 73  decimal integers
1ba30 5d 20 73 74 6f 70 73 20 0a 20 20 20 20 20 20 20  ] stops .       
1ba40 20 61 74 20 74 68 65 20 22 78 22 20 69 6e 20 74   at the "x" in t
1ba50 68 65 20 22 30 78 22 20 70 72 65 66 69 78 20 6f  he "0x" prefix o
1ba60 66 20 74 68 65 20 68 65 78 61 64 65 63 69 6d 61  f the hexadecima
1ba70 6c 20 69 6e 74 65 67 65 72 20 73 74 72 69 6e 67  l integer string
1ba80 20 0a 20 20 20 20 20 20 20 20 61 6e 64 20 74 68   .        and th
1ba90 75 73 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  us result of the
1baa0 20 43 41 53 54 20 69 73 20 61 6c 77 61 79 73 20   CAST is always 
1bab0 7a 65 72 6f 2e 29 5e 0a 0a 20 20 20 20 20 20 3c  zero.)^..      <
1bac0 70 3e 5e 41 20 63 61 73 74 20 6f 66 20 61 20 52  p>^A cast of a R
1bad0 45 41 4c 20 76 61 6c 75 65 20 69 6e 74 6f 20 61  EAL value into a
1bae0 6e 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  n INTEGER result
1baf0 73 20 69 6e 20 74 68 65 20 69 6e 74 65 67 65 72  s in the integer
1bb00 0a 20 20 20 20 20 20 62 65 74 77 65 65 6e 20 74  .      between t
1bb10 68 65 20 52 45 41 4c 20 76 61 6c 75 65 20 61 6e  he REAL value an
1bb20 64 20 7a 65 72 6f 20 74 68 61 74 20 69 73 20 63  d zero that is c
1bb30 6c 6f 73 65 73 74 20 74 6f 20 74 68 65 20 52 45  losest to the RE
1bb40 41 4c 20 76 61 6c 75 65 2e 0a 20 20 20 20 20 20  AL value..      
1bb50 5e 49 66 20 61 20 52 45 41 4c 20 69 73 20 67 72  ^If a REAL is gr
1bb60 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 67  eater than the g
1bb70 72 65 61 74 65 73 74 20 70 6f 73 73 69 62 6c 65  reatest possible
1bb80 20 73 69 67 6e 65 64 0a 20 20 20 20 20 20 69 6e   signed.      in
1bb90 74 65 67 65 72 20 28 2b 39 32 32 33 33 37 32 30  teger (+92233720
1bba0 33 36 38 35 34 37 37 35 38 30 37 29 20 74 68 65  36854775807) the
1bbb0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  n the result is 
1bbc0 74 68 65 20 67 72 65 61 74 65 73 74 20 70 6f 73  the greatest pos
1bbd0 73 69 62 6c 65 0a 20 20 20 20 20 20 73 69 67 6e  sible.      sign
1bbe0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  ed integer and i
1bbf0 66 20 74 68 65 20 52 45 41 4c 20 69 73 20 6c 65  f the REAL is le
1bc00 73 73 20 74 68 61 6e 20 74 68 65 20 6c 65 61 73  ss than the leas
1bc10 74 20 70 6f 73 73 69 62 6c 65 20 73 69 67 6e 65  t possible signe
1bc20 64 0a 20 20 20 20 20 20 69 6e 74 65 67 65 72 20  d.      integer 
1bc30 28 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37  (-92233720368547
1bc40 37 35 38 30 38 29 20 74 68 65 6e 20 74 68 65 20  75808) then the 
1bc50 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 6c 65  result is the le
1bc60 61 73 74 20 70 6f 73 73 69 62 6c 65 0a 20 20 20  ast possible.   
1bc70 20 20 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65     signed intege
1bc80 72 2e 0a 0a 20 20 20 20 20 20 3c 70 3e 50 72 69  r...      <p>Pri
1bc90 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1bca0 73 69 6f 6e 20 33 2e 38 2e 32 20 28 5b 64 61 74  sion 3.8.2 ([dat
1bcb0 65 6f 66 3a 33 2e 38 2e 32 5d 29 2c 0a 20 20 20  eof:3.8.2]),.   
1bcc0 20 20 20 63 61 73 74 69 6e 67 20 61 20 52 45 41     casting a REA
1bcd0 4c 20 76 61 6c 75 65 20 67 72 65 61 74 65 72 20  L value greater 
1bce0 74 68 61 6e 0a 20 20 20 20 20 20 2b 39 32 32 33  than.      +9223
1bcf0 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 2e  372036854775807.
1bd00 30 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  0 into an intege
1bd10 72 20 72 65 73 75 6c 74 65 64 20 69 6e 20 74 68  r resulted in th
1bd20 65 20 6d 6f 73 74 20 6e 65 67 61 74 69 76 65 0a  e most negative.
1bd30 20 20 20 20 20 20 69 6e 74 65 67 65 72 2c 20 2d        integer, -
1bd40 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
1bd50 38 30 38 2e 20 20 54 68 69 73 20 62 65 68 61 76  808.  This behav
1bd60 69 6f 72 20 77 61 73 20 6d 65 61 6e 74 20 74 6f  ior was meant to
1bd70 20 65 6d 75 6c 61 74 65 20 74 68 65 0a 20 20 20   emulate the.   
1bd80 20 20 20 62 65 68 61 76 69 6f 72 20 6f 66 20 78     behavior of x
1bd90 38 36 2f 78 36 34 20 68 61 72 64 77 61 72 65 20  86/x64 hardware 
1bda0 77 68 65 6e 20 64 6f 69 6e 67 20 74 68 65 20 65  when doing the e
1bdb0 71 75 69 76 61 6c 65 6e 74 20 63 61 73 74 2e 0a  quivalent cast..
1bdc0 0a 3c 74 72 3e 0a 20 20 3c 74 64 3e 20 4e 55 4d  .<tr>.  <td> NUM
1bdd0 45 52 49 43 0a 20 20 3c 74 64 3e 20 5e 43 61 73  ERIC.  <td> ^Cas
1bde0 74 69 6e 67 20 61 20 54 45 58 54 20 6f 72 20 42  ting a TEXT or B
1bdf0 4c 4f 42 20 76 61 6c 75 65 20 69 6e 74 6f 20 4e  LOB value into N
1be00 55 4d 45 52 49 43 20 79 69 65 6c 64 73 20 65 69  UMERIC yields ei
1be10 74 68 65 72 20 61 6e 20 49 4e 54 45 47 45 52 20  ther an INTEGER 
1be20 6f 72 0a 20 20 20 61 20 52 45 41 4c 20 72 65 73  or.   a REAL res
1be30 75 6c 74 2e 0a 20 20 20 5e 49 66 20 74 68 65 20  ult..   ^If the 
1be40 69 6e 70 75 74 20 74 65 78 74 20 6c 6f 6f 6b 73  input text looks
1be50 20 6c 69 6b 65 20 61 6e 20 69 6e 74 65 67 65 72   like an integer
1be60 20 28 74 68 65 72 65 20 69 73 20 6e 6f 20 64 65   (there is no de
1be70 63 69 6d 61 6c 20 70 6f 69 6e 74 20 6e 6f 72 0a  cimal point nor.
1be80 20 20 20 65 78 70 6f 6e 65 6e 74 29 20 61 6e 64     exponent) and
1be90 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 73 6d   the value is sm
1bea0 61 6c 6c 20 65 6e 6f 75 67 68 20 74 6f 20 66 69  all enough to fi
1beb0 74 20 69 6e 20 61 20 36 34 2d 62 69 74 20 73 69  t in a 64-bit si
1bec0 67 6e 65 64 20 69 6e 74 65 67 65 72 2c 0a 20 20  gned integer,.  
1bed0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
1bee0 20 77 69 6c 6c 20 62 65 20 49 4e 54 45 47 45 52   will be INTEGER
1bef0 2e 0a 20 20 20 5e 49 6e 70 75 74 20 74 65 78 74  ..   ^Input text
1bf00 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
1bf10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1bf20 28 74 68 65 72 65 20 69 73 20 61 20 64 65 63 69  (there is a deci
1bf30 6d 61 6c 20 70 6f 69 6e 74 20 61 6e 64 2f 6f 72  mal point and/or
1bf40 0a 20 20 20 61 6e 20 65 78 70 6f 6e 65 6e 74 29  .   an exponent)
1bf50 20 61 6e 64 20 74 68 65 20 74 65 78 74 20 64 65   and the text de
1bf60 73 63 72 69 62 65 73 20 61 20 76 61 6c 75 65 20  scribes a value 
1bf70 74 68 61 74 20 0a 20 20 20 63 61 6e 20 62 65 20  that .   can be 
1bf80 6c 6f 73 73 6c 65 73 73 6c 79 20 63 6f 6e 76 65  losslessly conve
1bf90 72 74 65 64 20 62 61 63 6b 20 61 6e 64 20 66 6f  rted back and fo
1bfa0 72 74 68 20 62 65 74 77 65 65 6e 20 49 45 45 45  rth between IEEE
1bfb0 20 37 35 34 20 36 34 2d 62 69 74 20 66 6c 6f 61   754 64-bit floa
1bfc0 74 20 61 6e 64 20 61 0a 20 20 20 35 31 2d 62 69  t and a.   51-bi
1bfd0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1bfe0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
1bff0 74 20 69 73 20 49 4e 54 45 47 45 52 2e 0a 20 20  t is INTEGER..  
1c000 20 28 49 6e 20 74 68 65 20 70 72 65 76 69 6f 75   (In the previou
1c010 73 20 73 65 6e 74 65 6e 63 65 2c 20 61 20 35 31  s sentence, a 51
1c020 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 73 20  -bit integer is 
1c030 73 70 65 63 69 66 69 65 64 20 73 69 6e 63 65 20  specified since 
1c040 74 68 61 74 20 69 73 20 6f 6e 65 0a 20 20 20 62  that is one.   b
1c050 69 74 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  it less than the
1c060 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6d   length of the m
1c070 61 6e 74 69 73 73 61 20 6f 66 20 61 6e 20 49 45  antissa of an IE
1c080 45 45 20 37 35 34 20 36 34 2d 62 69 74 20 66 6c  EE 754 64-bit fl
1c090 6f 61 74 20 61 6e 64 0a 20 20 20 74 68 75 73 20  oat and.   thus 
1c0a0 70 72 6f 76 69 64 65 73 20 61 20 31 2d 62 69 74  provides a 1-bit
1c0b0 20 6f 66 20 6d 61 72 67 69 6e 20 66 6f 72 20 74   of margin for t
1c0c0 68 65 20 74 65 78 74 2d 74 6f 2d 66 6c 6f 61 74  he text-to-float
1c0d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 70 65 72   conversion oper
1c0e0 61 74 69 6f 6e 2e 29 0a 20 20 20 5e 41 6e 79 20  ation.).   ^Any 
1c0f0 74 65 78 74 20 69 6e 70 75 74 20 74 68 61 74 20  text input that 
1c100 64 65 73 63 72 69 62 65 73 20 61 20 76 61 6c 75  describes a valu
1c110 65 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61  e outside the ra
1c120 6e 67 65 20 6f 66 20 61 20 36 34 2d 62 69 74 0a  nge of a 64-bit.
1c130 20 20 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65     signed intege
1c140 72 20 79 69 65 6c 64 73 20 61 20 52 45 41 4c 20  r yields a REAL 
1c150 72 65 73 75 6c 74 2e 0a 20 20 20 3c 70 3e 20 5e  result..   <p> ^
1c160 43 61 73 74 69 6e 67 20 61 20 52 45 41 4c 20 6f  Casting a REAL o
1c170 72 20 49 4e 54 45 47 45 52 20 76 61 6c 75 65 20  r INTEGER value 
1c180 74 6f 20 4e 55 4d 45 52 49 43 20 69 73 20 61 20  to NUMERIC is a 
1c190 6e 6f 2d 6f 70 2c 20 65 76 65 6e 20 69 66 20 61  no-op, even if a
1c1a0 20 72 65 61 6c 0a 20 20 20 76 61 6c 75 65 20 63   real.   value c
1c1b0 6f 75 6c 64 20 62 65 20 6c 6f 73 73 6c 65 73 73  ould be lossless
1c1c0 6c 79 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  ly converted to 
1c1d0 61 6e 20 69 6e 74 65 67 65 72 2e 0a 0a 3c 2f 74  an integer...</t
1c1e0 72 3e 0a 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70  r>..</table>..<p
1c1f0 3e 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  >^Note that the 
1c200 72 65 73 75 6c 74 20 66 72 6f 6d 20 63 61 73 74  result from cast
1c210 69 6e 67 20 61 6e 79 20 6e 6f 6e 2d 42 4c 4f 42  ing any non-BLOB
1c220 20 76 61 6c 75 65 20 69 6e 74 6f 20 61 20 0a 42   value into a .B
1c230 4c 4f 42 20 61 6e 64 20 74 68 65 20 72 65 73 75  LOB and the resu
1c240 6c 74 20 66 72 6f 6d 20 63 61 73 74 69 6e 67 20  lt from casting 
1c250 61 6e 79 20 42 4c 4f 42 20 76 61 6c 75 65 20 69  any BLOB value i
1c260 6e 74 6f 20 61 20 6e 6f 6e 2d 42 4c 4f 42 20 76  nto a non-BLOB v
1c270 61 6c 75 65 0a 6d 61 79 20 62 65 20 64 69 66 66  alue.may be diff
1c280 65 72 65 6e 74 20 64 65 70 65 6e 64 69 6e 67 20  erent depending 
1c290 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 64  on whether the d
1c2a0 61 74 61 62 61 73 65 20 5b 65 6e 63 6f 64 69 6e  atabase [encodin
1c2b0 67 5d 20 69 73 20 55 54 46 2d 38 2c 0a 55 54 46  g] is UTF-8,.UTF
1c2c0 2d 31 36 62 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16be, or UTF-16
1c2d0 6c 65 2e 0a 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  le....<tcl>hd_fr
1c2e0 61 67 6d 65 6e 74 20 62 6f 6f 6c 65 61 6e 65 78  agment booleanex
1c2f0 70 72 20 7b 62 6f 6f 6c 65 61 6e 20 65 78 70 72  pr {boolean expr
1c300 65 73 73 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68  ession}</tcl>.<h
1c310 33 3e 42 6f 6f 6c 65 61 6e 20 45 78 70 72 65 73  3>Boolean Expres
1c320 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  sions</h3>..<p>T
1c330 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67 65 20  he SQL language 
1c340 66 65 61 74 75 72 65 73 20 73 65 76 65 72 61 6c  features several
1c350 20 63 6f 6e 74 65 78 74 73 20 77 68 65 72 65 20   contexts where 
1c360 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  an expression is
1c370 20 0a 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20   .evaluated and 
1c380 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6e 76 65  the result conve
1c390 72 74 65 64 20 74 6f 20 61 20 62 6f 6f 6c 65 61  rted to a boolea
1c3a0 6e 20 28 74 72 75 65 20 6f 72 20 66 61 6c 73 65  n (true or false
1c3b0 29 20 76 61 6c 75 65 2e 20 54 68 65 73 65 0a 63  ) value. These.c
1c3c0 6f 6e 74 65 78 74 73 20 61 72 65 3a 0a 0a 20 20  ontexts are:..  
1c3d0 3c 75 6c 3e 0a 20 20 20 20 3c 6c 69 3e 20 74 68  <ul>.    <li> th
1c3e0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e WHERE clause o
1c3f0 66 20 61 20 53 45 4c 45 43 54 2c 20 55 50 44 41  f a SELECT, UPDA
1c400 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1c410 74 65 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69 3e  tement,.    <li>
1c420 20 74 68 65 20 4f 4e 20 6f 72 20 55 53 49 4e 47   the ON or USING
1c430 20 63 6c 61 75 73 65 20 6f 66 20 61 20 6a 6f 69   clause of a joi
1c440 6e 20 69 6e 20 61 20 53 45 4c 45 43 54 20 73 74  n in a SELECT st
1c450 61 74 65 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69  atement,.    <li
1c460 3e 20 74 68 65 20 48 41 56 49 4e 47 20 63 6c 61  > the HAVING cla
1c470 75 73 65 20 6f 66 20 61 20 53 45 4c 45 43 54 20  use of a SELECT 
1c480 73 74 61 74 65 6d 65 6e 74 2c 0a 20 20 20 20 3c  statement,.    <
1c490 6c 69 3e 20 74 68 65 20 57 48 45 4e 20 63 6c 61  li> the WHEN cla
1c4a0 75 73 65 20 6f 66 20 61 6e 20 53 51 4c 20 74 72  use of an SQL tr
1c4b0 69 67 67 65 72 2c 20 61 6e 64 0a 20 20 20 20 3c  igger, and.    <
1c4c0 6c 69 3e 20 74 68 65 20 57 48 45 4e 20 63 6c 61  li> the WHEN cla
1c4d0 75 73 65 20 6f 72 20 63 6c 61 75 73 65 73 20 6f  use or clauses o
1c4e0 66 20 73 6f 6d 65 20 43 41 53 45 20 65 78 70 72  f some CASE expr
1c4f0 65 73 73 69 6f 6e 73 2e 0a 20 20 3c 2f 75 6c 3e  essions..  </ul>
1c500 0a 0a 3c 70 3e 5e 28 54 6f 20 63 6f 6e 76 65 72  ..<p>^(To conver
1c510 74 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  t the results of
1c520 20 61 6e 20 53 51 4c 20 65 78 70 72 65 73 73 69   an SQL expressi
1c530 6f 6e 20 74 6f 20 61 20 62 6f 6f 6c 65 61 6e 20  on to a boolean 
1c540 76 61 6c 75 65 2c 20 53 51 4c 69 74 65 0a 66 69  value, SQLite.fi
1c550 72 73 74 20 63 61 73 74 73 20 74 68 65 20 72 65  rst casts the re
1c560 73 75 6c 74 20 74 6f 20 61 20 4e 55 4d 45 52 49  sult to a NUMERI
1c570 43 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20 73  C value in the s
1c580 61 6d 65 20 77 61 79 20 61 73 20 61 20 0a 5b 43  ame way as a .[C
1c590 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e 5d 2e  AST expression].
1c5a0 20 41 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 20   A numeric zero 
1c5b0 76 61 6c 75 65 20 28 69 6e 74 65 67 65 72 20 76  value (integer v
1c5c0 61 6c 75 65 20 30 20 6f 72 20 72 65 61 6c 20 0a  alue 0 or real .
1c5d0 76 61 6c 75 65 20 30 2e 30 29 20 69 73 20 63 6f  value 0.0) is co
1c5e0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 66  nsidered to be f
1c5f0 61 6c 73 65 2e 20 20 41 20 4e 55 4c 4c 20 76 61  alse.  A NULL va
1c600 6c 75 65 20 69 73 20 73 74 69 6c 6c 20 4e 55 4c  lue is still NUL
1c610 4c 2e 0a 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  L..All other val
1c620 75 65 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72  ues are consider
1c630 65 64 20 74 72 75 65 2e 29 5e 0a 0a 3c 70 3e 5e  ed true.)^..<p>^
1c640 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68  (For example, th
1c650 65 20 76 61 6c 75 65 73 20 4e 55 4c 4c 2c 20 30  e values NULL, 0
1c660 2e 30 2c 20 30 2c 20 27 65 6e 67 6c 69 73 68 27  .0, 0, 'english'
1c670 20 61 6e 64 20 27 30 27 20 61 72 65 20 61 6c 6c   and '0' are all
1c680 20 63 6f 6e 73 69 64 65 72 65 64 0a 74 6f 20 62   considered.to b
1c690 65 20 66 61 6c 73 65 2e 29 5e 20 5e 28 56 61 6c  e false.)^ ^(Val
1c6a0 75 65 73 20 31 2c 20 31 2e 30 2c 20 30 2e 31 2c  ues 1, 1.0, 0.1,
1c6b0 20 2d 30 2e 31 20 61 6e 64 20 27 31 65 6e 67 6c   -0.1 and '1engl
1c6c0 69 73 68 27 20 61 72 65 20 63 6f 6e 73 69 64 65  ish' are conside
1c6d0 72 65 64 20 74 6f 20 0a 62 65 20 74 72 75 65 2e  red to .be true.
1c6e0 29 5e 0a 0a 3c 70 3e 42 65 67 69 6e 6e 69 6e 67  )^..<p>Beginning
1c6f0 20 77 69 74 68 20 53 51 4c 69 74 65 20 33 2e 32   with SQLite 3.2
1c700 33 2e 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 32  3.0 ([dateof:3.2
1c710 33 2e 30 5d 29 2c 20 53 51 4c 69 74 65 20 72 65  3.0]), SQLite re
1c720 63 6f 67 6e 69 7a 65 73 20 74 68 65 0a 69 64 65  cognizes the.ide
1c730 6e 74 69 66 69 65 72 73 20 22 54 52 55 45 22 20  ntifiers "TRUE" 
1c740 61 6e 64 20 22 46 41 4c 53 45 22 20 61 73 20 62  and "FALSE" as b
1c750 6f 6f 6c 65 61 6e 20 6c 69 74 65 72 61 6c 73 2c  oolean literals,
1c760 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1c770 74 68 6f 73 65 0a 69 64 65 6e 74 69 66 69 65 72  those.identifier
1c780 73 20 61 72 65 20 6e 6f 74 20 61 6c 72 65 61 64  s are not alread
1c790 79 20 75 73 65 64 20 66 6f 72 20 73 6f 6d 65 20  y used for some 
1c7a0 6f 74 68 65 72 20 6d 65 61 6e 69 6e 67 2e 20 20  other meaning.  
1c7b0 49 66 20 74 68 65 72 65 20 61 6c 72 65 61 64 79  If there already
1c7c0 0a 65 78 69 73 74 73 20 63 6f 6c 75 6d 6e 73 20  .exists columns 
1c7d0 6f 72 20 74 61 62 6c 65 73 20 6f 72 20 6f 74 68  or tables or oth
1c7e0 65 72 20 6f 62 6a 65 63 74 73 20 6e 61 6d 65 64  er objects named
1c7f0 20 54 52 55 45 20 6f 72 20 46 41 4c 53 45 2c 20   TRUE or FALSE, 
1c800 74 68 65 6e 20 66 6f 72 0a 74 68 65 20 73 61 6b  then for.the sak
1c810 65 20 6f 66 20 62 61 63 6b 77 61 72 64 73 20 63  e of backwards c
1c820 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 74 68  ompatibility, th
1c830 65 20 54 52 55 45 20 61 6e 64 20 46 41 4c 53 45  e TRUE and FALSE
1c840 20 69 64 65 6e 74 69 66 69 65 72 73 20 72 65 66   identifiers ref
1c850 65 72 0a 74 6f 20 74 68 6f 73 65 20 6f 74 68 65  er.to those othe
1c860 72 20 6f 62 6a 65 63 74 73 2c 20 6e 6f 74 20 74  r objects, not t
1c870 6f 20 74 68 65 20 62 6f 6f 6c 65 61 6e 20 76 61  o the boolean va
1c880 6c 75 65 73 2e 0a 0a 3c 70 3e 54 68 65 20 62 6f  lues...<p>The bo
1c890 6f 6c 65 61 6e 20 69 64 65 6e 74 69 66 69 65 72  olean identifier
1c8a0 73 20 54 52 55 45 20 61 6e 64 20 46 41 4c 53 45  s TRUE and FALSE
1c8b0 20 61 72 65 20 75 73 75 61 6c 6c 79 20 6a 75 73   are usually jus
1c8c0 74 20 61 6c 69 61 73 65 73 20 66 6f 72 0a 74 68  t aliases for.th
1c8d0 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
1c8e0 20 31 20 61 6e 64 20 30 2c 20 72 65 73 70 65 63   1 and 0, respec
1c8f0 74 69 76 65 6c 79 2e 20 20 48 6f 77 65 76 65 72  tively.  However
1c900 2c 20 69 66 20 54 52 55 45 20 6f 72 20 46 41 4c  , if TRUE or FAL
1c910 53 45 0a 6f 63 63 75 72 20 6f 6e 20 74 68 65 20  SE.occur on the 
1c920 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
1c930 6f 66 20 61 6e 20 49 53 20 6f 70 65 72 61 74 6f  of an IS operato
1c940 72 2c 20 74 68 65 6e 20 74 68 65 79 20 66 6f 72  r, then they for
1c950 6d 20 6e 65 77 0a 75 6e 61 72 79 20 70 6f 73 74  m new.unary post
1c960 66 69 78 20 6f 70 65 72 61 74 6f 72 73 20 22 49  fix operators "I
1c970 53 20 54 52 55 45 22 20 61 6e 64 20 22 49 53 20  S TRUE" and "IS 
1c980 46 41 4c 53 45 22 20 77 68 69 63 68 20 74 65 73  FALSE" which tes
1c990 74 20 74 68 65 20 62 6f 6f 6c 65 61 6e 0a 76 61  t the boolean.va
1c9a0 6c 75 65 20 6f 66 20 74 68 65 20 6f 70 65 72 61  lue of the opera
1c9b0 6e 64 20 6f 6e 20 74 68 65 20 6c 65 66 74 2e 0a  nd on the left..
1c9c0 0a 3c 68 33 3e 46 75 6e 63 74 69 6f 6e 73 3c 2f  .<h3>Functions</
1c9d0 68 33 3e 0a 3c 70 3e 53 51 4c 69 74 65 20 73 75  h3>.<p>SQLite su
1c9e0 70 70 6f 72 74 73 20 6d 61 6e 79 20 5b 63 6f 72  pports many [cor
1c9f0 65 66 75 6e 63 7c 73 69 6d 70 6c 65 5d 2c 20 5b  efunc|simple], [
1ca00 61 67 67 66 75 6e 63 7c 61 67 67 72 65 67 61 74  aggfunc|aggregat
1ca10 65 5d 2c 0a 61 6e 64 20 5b 77 69 6e 64 6f 77 20  e],.and [window 
1ca20 66 75 6e 63 74 69 6f 6e 73 7c 77 69 6e 64 6f 77  functions|window
1ca30 5d 0a 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ].SQL functions.
1ca40 20 20 46 6f 72 20 70 72 65 73 65 6e 74 61 74 69    For presentati
1ca50 6f 6e 20 70 75 72 70 6f 73 65 73 2c 20 73 69 6d  on purposes, sim
1ca60 70 6c 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ple functions ar
1ca70 65 20 66 75 72 74 68 65 72 0a 73 75 62 64 69 76  e further.subdiv
1ca80 69 64 65 64 20 69 6e 74 6f 20 5b 63 6f 72 65 66  ided into [coref
1ca90 75 6e 63 20 7c 20 63 6f 72 65 20 66 75 6e 63 74  unc | core funct
1caa0 69 6f 6e 73 5d 2c 20 5b 64 61 74 65 66 75 6e 63  ions], [datefunc
1cab0 7c 64 61 74 65 2d 74 69 6d 65 20 66 75 6e 63 74  |date-time funct
1cac0 69 6f 6e 73 5d 2c 0a 61 6e 64 20 5b 6a 73 6f 6e  ions],.and [json
1cad0 31 7c 4a 53 4f 4e 20 66 75 6e 63 74 69 6f 6e 73  1|JSON functions
1cae0 5d 2e 0a 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ]..Applications 
1caf0 63 61 6e 20 61 64 64 20 6e 65 77 20 66 75 6e 63  can add new func
1cb00 74 69 6f 6e 73 2c 20 77 72 69 74 74 65 6e 20 69  tions, written i
1cb10 6e 20 43 2f 43 2b 2b 2c 20 75 73 69 6e 67 20 74  n C/C++, using t
1cb20 68 65 0a 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he.[sqlite3_crea
1cb30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69  te_function()] i
1cb40 6e 74 65 72 66 61 63 65 2e 0a 3c 2f 70 3e 0a 0a  nterface..</p>..
1cb50 3c 70 3e 0a 54 68 65 20 6d 61 69 6e 20 65 78 70  <p>.The main exp
1cb60 72 65 73 73 69 6f 6e 20 62 75 62 62 6c 65 20 64  ression bubble d
1cb70 69 61 67 72 61 6d 20 61 62 6f 76 65 20 73 68 6f  iagram above sho
1cb80 77 73 20 61 20 73 69 6e 67 6c 65 20 73 79 6e 74  ws a single synt
1cb90 61 78 20 66 6f 72 0a 61 6c 6c 20 66 75 6e 63 74  ax for.all funct
1cba0 69 6f 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ion invocations.
1cbb0 20 20 42 75 74 20 74 68 69 73 20 69 73 20 6d 65    But this is me
1cbc0 72 65 6c 79 20 74 6f 20 73 69 6d 70 6c 69 66 79  rely to simplify
1cbd0 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 0a   the expression.
1cbe0 62 75 62 62 6c 65 20 64 69 61 67 72 61 6d 2e 20  bubble diagram. 
1cbf0 20 49 6e 20 72 65 61 6c 69 74 79 2c 20 65 61 63   In reality, eac
1cc00 68 20 74 79 70 65 20 6f 66 20 66 75 6e 63 74 69  h type of functi
1cc10 6f 6e 20 68 61 73 20 61 20 73 6c 69 67 68 74 6c  on has a slightl
1cc20 79 20 64 69 66 66 65 72 65 6e 74 0a 73 79 6e 74  y different.synt
1cc30 61 78 2c 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e  ax, shown below.
1cc40 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69    The function i
1cc50 6e 76 6f 63 61 74 69 6f 6e 20 73 79 6e 74 61 78  nvocation syntax
1cc60 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 6d 61   shown in the ma
1cc70 69 6e 0a 65 78 70 72 65 73 73 69 6f 6e 20 62 75  in.expression bu
1cc80 62 62 6c 65 20 64 69 61 67 72 61 6d 20 69 73 20  bble diagram is 
1cc90 74 68 65 20 75 6e 69 6f 6e 20 6f 66 20 74 68 65  the union of the
1cca0 20 74 68 72 65 65 20 73 79 6e 74 61 78 65 73 20   three syntaxes 
1ccb0 73 68 6f 77 6e 20 68 65 72 65 3a 0a 0a 3c 74 63  shown here:..<tc
1ccc0 6c 3e 0a 42 75 62 62 6c 65 44 69 61 67 72 61 6d  l>.BubbleDiagram
1ccd0 20 73 69 6d 70 6c 65 2d 66 75 6e 63 74 69 6f 6e   simple-function
1cce0 2d 69 6e 76 6f 63 61 74 69 6f 6e 0a 42 75 62 62  -invocation.Bubb
1ccf0 6c 65 44 69 61 67 72 61 6d 20 61 67 67 72 65 67  leDiagram aggreg
1cd00 61 74 65 2d 66 75 6e 63 74 69 6f 6e 2d 69 6e 76  ate-function-inv
1cd10 6f 63 61 74 69 6f 6e 0a 42 75 62 62 6c 65 44 69  ocation.BubbleDi
1cd20 61 67 72 61 6d 20 77 69 6e 64 6f 77 2d 66 75 6e  agram window-fun
1cd30 63 74 69 6f 6e 2d 69 6e 76 6f 63 61 74 69 6f 6e  ction-invocation
1cd40 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 54 68 65  .</tcl>..<p>.The
1cd50 20 4f 56 45 52 20 63 6c 61 75 73 65 20 69 73 20   OVER clause is 
1cd60 72 65 71 75 69 72 65 64 20 66 6f 72 20 5b 77 69  required for [wi
1cd70 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73 5d 20  ndow functions] 
1cd80 61 6e 64 20 69 73 20 70 72 6f 68 69 62 69 74 65  and is prohibite
1cd90 64 0a 6f 74 68 65 72 77 69 73 65 2e 20 20 54 68  d.otherwise.  Th
1cda0 65 20 44 49 53 54 49 4e 43 54 20 6b 65 79 77 6f  e DISTINCT keywo
1cdb0 72 64 20 69 73 20 6f 6e 6c 79 20 61 6c 6c 6f 77  rd is only allow
1cdc0 65 64 20 69 6e 20 5b 61 67 67 66 75 6e 63 7c 61  ed in [aggfunc|a
1cdd0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
1cde0 6e 73 5d 2e 0a 54 68 65 20 46 49 4c 54 45 52 20  ns]..The FILTER 
1cdf0 63 6c 61 75 73 65 20 6d 61 79 20 6e 6f 74 20 61  clause may not a
1ce00 70 70 65 61 72 20 6f 6e 20 61 20 5b 63 6f 72 65  ppear on a [core
1ce10 66 75 6e 63 7c 73 69 6d 70 6c 65 20 66 75 6e 63  func|simple func
1ce20 74 69 6f 6e 5d 2e 0a 0a 3c 70 3e 5e 49 74 20 69  tion]...<p>^It i
1ce30 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 68 61  s possible to ha
1ce40 76 65 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ve an aggregate 
1ce50 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
1ce60 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 61  e same name as a
1ce70 0a 73 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f 6e  .simple function
1ce80 2c 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  , as long as the
1ce90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1cea0 65 6e 74 73 20 66 6f 72 20 74 68 65 20 74 77 6f  ents for the two
1ceb0 20 66 6f 72 6d 73 20 6f 66 20 74 68 65 0a 66 75   forms of the.fu
1cec0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 66 66 65  nction are diffe
1ced0 72 65 6e 74 2e 20 20 5e 46 6f 72 20 65 78 61 6d  rent.  ^For exam
1cee0 70 6c 65 2c 20 74 68 65 20 5b 61 67 67 5f 6d 61  ple, the [agg_ma
1cef0 78 7c 6d 61 78 28 29 5d 20 66 75 6e 63 74 69 6f  x|max()] functio
1cf00 6e 20 77 69 74 68 20 61 0a 73 69 6e 67 6c 65 20  n with a.single 
1cf10 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 61  argument is an a
1cf20 67 67 72 65 67 61 74 65 20 61 6e 64 20 74 68 65  ggregate and the
1cf30 20 5b 6d 61 78 28 29 5d 20 66 75 6e 63 74 69 6f   [max()] functio
1cf40 6e 20 77 69 74 68 20 74 77 6f 20 6f 72 20 6d 6f  n with two or mo
1cf50 72 65 0a 61 72 67 75 6d 65 6e 74 73 20 69 73 20  re.arguments is 
1cf60 61 20 73 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f  a simple functio
1cf70 6e 2e 20 20 41 67 67 72 65 67 61 74 65 20 66 75  n.  Aggregate fu
1cf80 6e 63 74 69 6f 6e 73 20 63 61 6e 20 75 73 75 61  nctions can usua
1cf90 6c 6c 79 20 61 6c 73 6f 0a 62 65 20 75 73 65 64  lly also.be used
1cfa0 20 61 73 20 77 69 6e 64 6f 77 20 66 75 6e 63 74   as window funct
1cfb0 69 6f 6e 73 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23  ions...<tcl>.###
1cfc0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cfd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cfe0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cff0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1d000 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
1d010 69 6f 6e 20 7b 43 6f 72 65 20 46 75 6e 63 74 69  ion {Core Functi
1d020 6f 6e 73 7d 20 63 6f 72 65 66 75 6e 63 20 7b 2a  ons} corefunc {*
1d030 63 6f 72 65 66 75 6e 63 7d 0a 75 6e 73 65 74 20  corefunc}.unset 
1d040 2d 6e 6f 63 6f 6d 70 6c 61 69 6e 20 63 6f 72 65  -nocomplain core
1d050 66 75 6e 63 73 65 74 0a 70 72 6f 63 20 66 75 6e  funcset.proc fun
1d060 63 64 65 66 20 7b 73 79 6e 74 61 78 20 6b 65 79  cdef {syntax key
1d070 77 6f 72 64 73 20 64 65 73 63 7d 20 7b 0a 20 20  words desc} {.  
1d080 67 6c 6f 62 61 6c 20 63 6f 72 65 66 75 6e 63 73  global corefuncs
1d090 65 74 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b 61  et.  regexp {^[a
1d0a0 2d 7a 5f 5d 2b 7d 20 24 73 79 6e 74 61 78 20 62  -z_]+} $syntax b
1d0b0 61 73 65 73 79 6e 74 61 78 0a 20 20 73 65 74 20  asesyntax.  set 
1d0c0 63 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61 73  corefuncset($bas
1d0d0 65 73 79 6e 74 61 78 29 20 5b 6c 69 73 74 20 24  esyntax) [list $
1d0e0 73 79 6e 74 61 78 20 24 6b 65 79 77 6f 72 64 73  syntax $keywords
1d0f0 20 24 64 65 73 63 5d 0a 7d 0a 66 75 6e 63 64 65   $desc].}.funcde
1d100 66 20 7b 61 62 73 28 58 29 7d 20 7b 7d 20 7b 0a  f {abs(X)} {} {.
1d110 20 20 5e 54 68 65 20 61 62 73 28 58 29 20 66 75    ^The abs(X) fu
1d120 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1d130 68 65 20 61 62 73 6f 6c 75 74 65 20 76 61 6c 75  he absolute valu
1d140 65 20 6f 66 20 74 68 65 20 6e 75 6d 65 72 69 63  e of the numeric
1d150 0a 20 20 61 72 67 75 6d 65 6e 74 20 58 2e 20 20  .  argument X.  
1d160 5e 41 62 73 28 58 29 20 72 65 74 75 72 6e 73 20  ^Abs(X) returns 
1d170 4e 55 4c 4c 20 69 66 20 58 20 69 73 20 4e 55 4c  NULL if X is NUL
1d180 4c 2e 20 0a 20 20 5e 28 41 62 73 28 58 29 20 72  L. .  ^(Abs(X) r
1d190 65 74 75 72 6e 73 20 30 2e 30 20 69 66 20 58 20  eturns 0.0 if X 
1d1a0 69 73 20 61 20 73 74 72 69 6e 67 20 6f 72 20 62  is a string or b
1d1b0 6c 6f 62 0a 20 20 74 68 61 74 20 63 61 6e 6e 6f  lob.  that canno
1d1c0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1d1d0 6f 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  o a numeric valu
1d1e0 65 2e 29 5e 20 20 5e 49 66 20 58 20 69 73 20 74  e.)^  ^If X is t
1d1f0 68 65 20 0a 20 20 69 6e 74 65 67 65 72 20 2d 39  he .  integer -9
1d200 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
1d210 30 38 20 74 68 65 6e 20 61 62 73 28 58 29 20 74  08 then abs(X) t
1d220 68 72 6f 77 73 20 61 6e 20 69 6e 74 65 67 65 72  hrows an integer
1d230 20 6f 76 65 72 66 6c 6f 77 0a 20 20 65 72 72 6f   overflow.  erro
1d240 72 20 73 69 6e 63 65 20 74 68 65 72 65 20 69 73  r since there is
1d250 20 6e 6f 20 65 71 75 69 76 61 6c 65 6e 74 20 70   no equivalent p
1d260 6f 73 69 74 69 76 65 20 36 34 2d 62 69 74 20 74  ositive 64-bit t
1d270 77 6f 20 63 6f 6d 70 6c 65 6d 65 6e 74 20 76 61  wo complement va
1d280 6c 75 65 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  lue..}..funcdef 
1d290 7b 63 68 61 6e 67 65 73 28 29 7d 20 7b 7d 20 7b  {changes()} {} {
1d2a0 0a 20 20 5e 54 68 65 20 63 68 61 6e 67 65 73 28  .  ^The changes(
1d2b0 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1d2c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1d2d0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
1d2e0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
1d2f0 0a 20 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  .  or inserted o
1d300 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
1d310 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1d320 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
1d330 20 44 45 4c 45 54 45 2c 0a 20 20 6f 72 20 55 50   DELETE,.  or UP
1d340 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2c 20  DATE statement, 
1d350 65 78 63 6c 75 73 69 76 65 20 6f 66 20 73 74 61  exclusive of sta
1d360 74 65 6d 65 6e 74 73 20 69 6e 20 6c 6f 77 65 72  tements in lower
1d370 2d 6c 65 76 65 6c 20 74 72 69 67 67 65 72 73 2e  -level triggers.
1d380 0a 20 20 5e 54 68 65 20 63 68 61 6e 67 65 73 28  .  ^The changes(
1d390 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ) SQL function i
1d3a0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d3b0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
1d3c0 63 68 61 6e 67 65 73 28 29 5d 0a 20 20 43 2f 43  changes()].  C/C
1d3d0 2b 2b 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20  ++ function and 
1d3e0 68 65 6e 63 65 20 66 6f 6c 6c 6f 77 73 20 74 68  hence follows th
1d3f0 65 20 73 61 6d 65 20 72 75 6c 65 73 20 66 6f 72  e same rules for
1d400 20 63 6f 75 6e 74 69 6e 67 20 63 68 61 6e 67 65   counting change
1d410 73 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 63  s..}..funcdef {c
1d420 68 61 72 28 58 31 2c 58 32 2c 2e 2e 2e 2c 58 4e  har(X1,X2,...,XN
1d430 29 7d 20 7b 7d 20 7b 0a 20 20 5e 28 54 68 65 20  )} {} {.  ^(The 
1d440 63 68 61 72 28 58 31 2c 58 32 2c 2e 2e 2e 2c 58  char(X1,X2,...,X
1d450 4e 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  N) function retu
1d460 72 6e 73 20 61 20 73 74 72 69 6e 67 20 63 6f 6d  rns a string com
1d470 70 6f 73 65 64 20 6f 66 20 63 68 61 72 61 63 74  posed of charact
1d480 65 72 73 20 68 61 76 69 6e 67 20 74 68 65 0a 20  ers having the. 
1d490 20 20 75 6e 69 63 6f 64 65 20 63 6f 64 65 20 70    unicode code p
1d4a0 6f 69 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 69  oint values of i
1d4b0 6e 74 65 67 65 72 73 20 58 31 20 74 68 72 6f 75  ntegers X1 throu
1d4c0 67 68 20 58 4e 2c 20 72 65 73 70 65 63 74 69 76  gh XN, respectiv
1d4d0 65 6c 79 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65  ely.)^.}..funcde
1d4e0 66 20 7b 63 6f 61 6c 65 73 63 65 28 58 2c 59 2c  f {coalesce(X,Y,
1d4f0 2e 2e 2e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  ...)} {} {.  ^Th
1d500 65 20 63 6f 61 6c 65 73 63 65 28 29 20 66 75 6e  e coalesce() fun
1d510 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1d520 63 6f 70 79 20 6f 66 20 69 74 73 20 66 69 72 73  copy of its firs
1d530 74 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 72 67 75 6d  t non-NULL argum
1d540 65 6e 74 2c 20 6f 72 0a 20 20 4e 55 4c 4c 20 69  ent, or.  NULL i
1d550 66 20 61 6c 6c 20 61 72 67 75 6d 65 6e 74 73 20  f all arguments 
1d560 61 72 65 20 4e 55 4c 4c 2e 20 20 5e 43 6f 61 6c  are NULL.  ^Coal
1d570 65 73 63 65 28 29 20 6d 75 73 74 20 68 61 76 65  esce() must have
1d580 20 61 74 20 6c 65 61 73 74 20 0a 20 20 32 20 61   at least .  2 a
1d590 72 67 75 6d 65 6e 74 73 2e 0a 7d 0a 0a 66 75 6e  rguments..}..fun
1d5a0 63 64 65 66 20 7b 67 6c 6f 62 28 58 2c 59 29 7d  cdef {glob(X,Y)}
1d5b0 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 67 6c 6f   {} {.  ^The glo
1d5c0 62 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20  b(X,Y) function 
1d5d0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1d5e0 20 74 68 65 0a 20 20 65 78 70 72 65 73 73 69 6f   the.  expressio
1d5f0 6e 20 22 3c 62 3e 59 20 47 4c 4f 42 20 58 3c 2f  n "<b>Y GLOB X</
1d600 62 3e 22 2e 0a 20 20 4e 6f 74 65 20 74 68 61 74  b>"..  Note that
1d610 20 74 68 65 20 58 20 61 6e 64 20 59 20 61 72 67   the X and Y arg
1d620 75 6d 65 6e 74 73 20 61 72 65 20 72 65 76 65 72  uments are rever
1d630 73 65 64 20 69 6e 20 74 68 65 20 67 6c 6f 62 28  sed in the glob(
1d640 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20 72 65 6c  ) function.  rel
1d650 61 74 69 76 65 20 74 6f 20 74 68 65 20 69 6e 66  ative to the inf
1d660 69 78 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ix [GLOB] operat
1d670 6f 72 2e 20 20 59 20 69 73 20 74 68 65 20 73 74  or.  Y is the st
1d680 72 69 6e 67 20 61 6e 64 20 58 20 69 73 20 74 68  ring and X is th
1d690 65 0a 20 20 70 61 74 74 65 72 6e 2e 20 20 53 6f  e.  pattern.  So
1d6a0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
1d6b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 70  he following exp
1d6c0 72 65 73 73 69 6f 6e 73 20 61 72 65 20 65 71 75  ressions are equ
1d6d0 69 76 61 6c 65 6e 74 3a 0a 20 20 3c 62 6c 6f 63  ivalent:.  <bloc
1d6e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20  kquote><pre>.   
1d6f0 20 20 6e 61 6d 65 20 47 4c 4f 42 20 27 2a 68 65    name GLOB '*he
1d700 6c 69 75 6d 2a 27 0a 20 20 20 20 20 67 6c 6f 62  lium*'.     glob
1d710 28 27 2a 68 65 6c 69 75 6d 2a 27 2c 6e 61 6d 65  ('*helium*',name
1d720 29 0a 20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  ).  </pre></bloc
1d730 6b 71 75 6f 74 65 3e 0a 20 20 3c 70 3e 5e 49 66  kquote>.  <p>^If
1d740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
1d750 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
1d760 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1d770 65 64 20 74 6f 0a 20 20 6f 76 65 72 72 69 64 65  ed to.  override
1d780 20 74 68 65 20 67 6c 6f 62 28 58 2c 59 29 20 66   the glob(X,Y) f
1d790 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 6e 20  unction with an 
1d7a0 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
1d7b0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 65 6e 0a  ementation then.
1d7c0 20 20 74 68 65 20 5b 47 4c 4f 42 5d 20 6f 70 65    the [GLOB] ope
1d7d0 72 61 74 6f 72 20 77 69 6c 6c 20 69 6e 76 6f 6b  rator will invok
1d7e0 65 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  e the alternativ
1d7f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1d800 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 69 66  ..}..funcdef {if
1d810 6e 75 6c 6c 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a  null(X,Y)} {} {.
1d820 20 20 5e 54 68 65 20 69 66 6e 75 6c 6c 28 29 20    ^The ifnull() 
1d830 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1d840 20 61 20 63 6f 70 79 20 6f 66 20 69 74 73 20 66   a copy of its f
1d850 69 72 73 74 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 72  irst non-NULL ar
1d860 67 75 6d 65 6e 74 2c 20 6f 72 0a 20 20 4e 55 4c  gument, or.  NUL
1d870 4c 20 69 66 20 62 6f 74 68 20 61 72 67 75 6d 65  L if both argume
1d880 6e 74 73 20 61 72 65 20 4e 55 4c 4c 2e 20 20 5e  nts are NULL.  ^
1d890 49 66 6e 75 6c 6c 28 29 20 6d 75 73 74 20 68 61  Ifnull() must ha
1d8a0 76 65 20 65 78 61 63 74 6c 79 20 32 20 61 72 67  ve exactly 2 arg
1d8b0 75 6d 65 6e 74 73 2e 0a 20 20 5e 54 68 65 20 69  uments..  ^The i
1d8c0 66 6e 75 6c 6c 28 29 20 66 75 6e 63 74 69 6f 6e  fnull() function
1d8d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1d8e0 6f 20 5b 63 6f 61 6c 65 73 63 65 28 29 5d 20 77  o [coalesce()] w
1d8f0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
1d900 73 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 69  s..}..funcdef {i
1d910 6e 73 74 72 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a  nstr(X,Y)} {} {.
1d920 20 20 5e 54 68 65 20 69 6e 73 74 72 28 58 2c 59    ^The instr(X,Y
1d930 29 20 66 75 6e 63 74 69 6f 6e 20 66 69 6e 64 73  ) function finds
1d940 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
1d950 72 65 6e 63 65 20 6f 66 20 73 74 72 69 6e 67 20  rence of string 
1d960 59 20 77 69 74 68 69 6e 20 0a 20 20 73 74 72 69  Y within .  stri
1d970 6e 67 20 58 20 61 6e 64 20 72 65 74 75 72 6e 73  ng X and returns
1d980 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
1d990 72 69 6f 72 20 63 68 61 72 61 63 74 65 72 73 20  rior characters 
1d9a0 70 6c 75 73 20 31 2c 20 6f 72 20 30 20 69 66 0a  plus 1, or 0 if.
1d9b0 20 20 59 20 69 73 20 6e 6f 77 68 65 72 65 20 66    Y is nowhere f
1d9c0 6f 75 6e 64 20 77 69 74 68 69 6e 20 58 2e 0a 20  ound within X.. 
1d9d0 20 5e 4f 72 2c 20 69 66 20 58 20 61 6e 64 20 59   ^Or, if X and Y
1d9e0 20 61 72 65 20 62 6f 74 68 20 42 4c 4f 42 73 2c   are both BLOBs,
1d9f0 20 74 68 65 6e 20 69 6e 73 74 72 28 58 2c 59 29   then instr(X,Y)
1da00 20 72 65 74 75 72 6e 73 20 6f 6e 65 0a 20 20 6d   returns one.  m
1da10 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ore than the num
1da20 62 65 72 20 62 79 74 65 73 20 70 72 69 6f 72 20  ber bytes prior 
1da30 74 6f 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  to the first occ
1da40 75 72 72 65 6e 63 65 20 6f 66 20 59 2c 20 6f 72  urrence of Y, or
1da50 20 30 20 69 66 0a 20 20 59 20 64 6f 65 73 20 6e   0 if.  Y does n
1da60 6f 74 20 6f 63 63 75 72 20 61 6e 79 77 68 65 72  ot occur anywher
1da70 65 20 77 69 74 68 69 6e 20 58 2e 0a 20 20 5e 49  e within X..  ^I
1da80 66 20 62 6f 74 68 20 61 72 67 75 6d 65 6e 74 73  f both arguments
1da90 20 58 20 61 6e 64 20 59 20 74 6f 20 69 6e 73 74   X and Y to inst
1daa0 72 28 58 2c 59 29 20 61 72 65 20 6e 6f 6e 2d 4e  r(X,Y) are non-N
1dab0 55 4c 4c 20 61 6e 64 20 61 72 65 20 6e 6f 74 20  ULL and are not 
1dac0 42 4c 4f 42 73 0a 20 20 74 68 65 6e 20 62 6f 74  BLOBs.  then bot
1dad0 68 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  h are interprete
1dae0 64 20 61 73 20 73 74 72 69 6e 67 73 2e 0a 20 20  d as strings..  
1daf0 5e 49 66 20 65 69 74 68 65 72 20 58 20 6f 72 20  ^If either X or 
1db00 59 20 61 72 65 20 4e 55 4c 4c 20 69 6e 20 69 6e  Y are NULL in in
1db10 73 74 72 28 58 2c 59 29 20 74 68 65 6e 20 74 68  str(X,Y) then th
1db20 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
1db30 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 68 65  ..}..funcdef {he
1db40 78 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  x(X)} {} {.  ^Th
1db50 65 20 68 65 78 28 29 20 66 75 6e 63 74 69 6f 6e  e hex() function
1db60 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
1db70 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 42 4c  argument as a BL
1db80 4f 42 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 20  OB and returns. 
1db90 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
1dba0 69 73 20 74 68 65 20 75 70 70 65 72 2d 63 61 73  is the upper-cas
1dbb0 65 20 68 65 78 61 64 65 63 69 6d 61 6c 20 72 65  e hexadecimal re
1dbc0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 63  ndering of the c
1dbd0 6f 6e 74 65 6e 74 20 6f 66 0a 20 20 74 68 61 74  ontent of.  that
1dbe0 20 62 6c 6f 62 2e 0a 7d 0a 0a 66 75 6e 63 64 65   blob..}..funcde
1dbf0 66 20 7b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  f {last_insert_r
1dc00 6f 77 69 64 28 29 7d 20 7b 7d 20 7b 0a 20 20 5e  owid()} {} {.  ^
1dc10 54 68 65 20 6c 61 73 74 5f 69 6e 73 65 72 74 5f  The last_insert_
1dc20 72 6f 77 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rowid() function
1dc30 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 52 4f   returns the [RO
1dc40 57 49 44 5d 0a 20 20 6f 66 20 74 68 65 20 6c 61  WID].  of the la
1dc50 73 74 20 72 6f 77 20 69 6e 73 65 72 74 20 66 72  st row insert fr
1dc60 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
1dc70 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 63 68  connection which
1dc80 20 69 6e 76 6f 6b 65 64 20 74 68 65 0a 20 20 66   invoked the.  f
1dc90 75 6e 63 74 69 6f 6e 2e 0a 20 20 5e 54 68 65 20  unction..  ^The 
1dca0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1dcb0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1dcc0 20 69 73 20 61 20 77 72 61 70 70 65 72 20 61 72   is a wrapper ar
1dcd0 6f 75 6e 64 20 74 68 65 0a 20 20 5b 73 71 6c 69  ound the.  [sqli
1dce0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1dcf0 72 6f 77 69 64 28 29 5d 20 43 2f 43 2b 2b 20 69  rowid()] C/C++ i
1dd00 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1dd10 6e 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6c  n..}..funcdef {l
1dd20 65 6e 67 74 68 28 58 29 7d 20 7b 7d 20 7b 0a 20  ength(X)} {} {. 
1dd30 20 5e 46 6f 72 20 61 20 73 74 72 69 6e 67 20 76   ^For a string v
1dd40 61 6c 75 65 20 58 2c 20 74 68 65 20 6c 65 6e 67  alue X, the leng
1dd50 74 68 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 72  th(X) function r
1dd60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1dd70 72 20 6f 66 20 0a 20 20 63 68 61 72 61 63 74 65  r of .  characte
1dd80 72 73 20 28 6e 6f 74 20 62 79 74 65 73 29 20 69  rs (not bytes) i
1dd90 6e 20 58 20 70 72 69 6f 72 20 74 6f 20 74 68 65  n X prior to the
1dda0 20 66 69 72 73 74 20 4e 55 4c 20 63 68 61 72 61   first NUL chara
1ddb0 63 74 65 72 2e 0a 20 20 53 69 6e 63 65 20 53 51  cter..  Since SQ
1ddc0 4c 69 74 65 20 73 74 72 69 6e 67 73 20 64 6f 20  Lite strings do 
1ddd0 6e 6f 74 20 6e 6f 72 6d 61 6c 6c 79 20 63 6f 6e  not normally con
1dde0 74 61 69 6e 20 4e 55 4c 20 63 68 61 72 61 63 74  tain NUL charact
1ddf0 65 72 73 2c 20 74 68 65 20 6c 65 6e 67 74 68 28  ers, the length(
1de00 58 29 0a 20 20 66 75 6e 63 74 69 6f 6e 20 77 69  X).  function wi
1de10 6c 6c 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ll usually retur
1de20 6e 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  n the total numb
1de30 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1de40 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 58   in the string X
1de50 2e 0a 20 20 5e 46 6f 72 20 61 20 62 6c 6f 62 20  ..  ^For a blob 
1de60 76 61 6c 75 65 20 58 2c 20 6c 65 6e 67 74 68 28  value X, length(
1de70 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  X) returns the n
1de80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1de90 6e 20 74 68 65 20 62 6c 6f 62 2e 0a 20 20 5e 49  n the blob..  ^I
1dea0 66 20 58 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  f X is NULL then
1deb0 20 6c 65 6e 67 74 68 28 58 29 20 69 73 20 4e 55   length(X) is NU
1dec0 4c 4c 2e 0a 20 20 5e 49 66 20 58 20 69 73 20 6e  LL..  ^If X is n
1ded0 75 6d 65 72 69 63 20 74 68 65 6e 20 6c 65 6e 67  umeric then leng
1dee0 74 68 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  th(X) returns th
1def0 65 20 6c 65 6e 67 74 68 20 6f 66 20 61 20 73 74  e length of a st
1df00 72 69 6e 67 0a 20 20 72 65 70 72 65 73 65 6e 74  ring.  represent
1df10 61 74 69 6f 6e 20 6f 66 20 58 2e 0a 7d 0a 0a 66  ation of X..}..f
1df20 75 6e 63 64 65 66 20 7b 6c 69 6b 65 28 58 2c 59  uncdef {like(X,Y
1df30 29 20 6c 69 6b 65 28 58 2c 59 2c 5a 29 7d 20 7b  ) like(X,Y,Z)} {
1df40 7d 20 7b 0a 20 20 5e 54 68 65 20 6c 69 6b 65 28  } {.  ^The like(
1df50 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  ) function is us
1df60 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1df70 74 68 65 0a 20 20 22 3c 62 3e 59 20 4c 49 4b 45  the.  "<b>Y LIKE
1df80 20 58 20 26 23 39 31 3b 45 53 43 41 50 45 20 5a   X &#91;ESCAPE Z
1df90 26 23 39 33 3b 3c 2f 62 3e 22 20 65 78 70 72 65  &#93;</b>" expre
1dfa0 73 73 69 6f 6e 2e 20 0a 20 20 5e 49 66 20 74 68  ssion. .  ^If th
1dfb0 65 20 6f 70 74 69 6f 6e 61 6c 20 45 53 43 41 50  e optional ESCAP
1dfc0 45 20 63 6c 61 75 73 65 20 69 73 20 70 72 65 73  E clause is pres
1dfd0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 0a 20 20  ent, then the.  
1dfe0 6c 69 6b 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  like() function 
1dff0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1e000 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 2e  three arguments.
1e010 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 74    ^Otherwise, it
1e020 20 69 73 0a 20 20 69 6e 76 6f 6b 65 64 20 77 69   is.  invoked wi
1e030 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1e040 20 6f 6e 6c 79 2e 20 4e 6f 74 65 20 74 68 61 74   only. Note that
1e050 20 74 68 65 20 58 20 61 6e 64 20 59 20 70 61 72   the X and Y par
1e060 61 6d 65 74 65 72 73 20 61 72 65 0a 20 20 72 65  ameters are.  re
1e070 76 65 72 73 65 64 20 69 6e 20 74 68 65 20 6c 69  versed in the li
1e080 6b 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ke() function re
1e090 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 69 6e  lative to the in
1e0a0 66 69 78 20 5b 4c 49 4b 45 5d 20 6f 70 65 72 61  fix [LIKE] opera
1e0b0 74 6f 72 2e 0a 20 20 58 20 69 73 20 74 68 65 20  tor..  X is the 
1e0c0 70 61 74 74 65 72 6e 20 61 6e 64 20 59 20 69 73  pattern and Y is
1e0d0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 6d   the string to m
1e0e0 61 74 63 68 20 61 67 61 69 6e 73 74 20 74 68 61  atch against tha
1e0f0 74 20 70 61 74 74 65 72 6e 2e 0a 20 20 48 65 6e  t pattern..  Hen
1e100 63 65 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ce, the followin
1e110 67 20 65 78 70 72 65 73 73 69 6f 6e 73 20 61 72  g expressions ar
1e120 65 20 65 71 75 69 76 61 6c 65 6e 74 3a 0a 20 20  e equivalent:.  
1e130 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e140 3e 0a 20 20 20 20 20 6e 61 6d 65 20 4c 49 4b 45  >.     name LIKE
1e150 20 27 25 6e 65 6f 6e 25 27 0a 20 20 20 20 20 6c   '%neon%'.     l
1e160 69 6b 65 28 27 25 6e 65 6f 6e 25 27 2c 6e 61 6d  ike('%neon%',nam
1e170 65 29 0a 20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  e).  </pre></blo
1e180 63 6b 71 75 6f 74 65 3e 0a 20 20 5e 54 68 65 20  ckquote>.  ^The 
1e190 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1e1a0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 74 65  function()] inte
1e1b0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1e1c0 64 20 74 6f 20 6f 76 65 72 72 69 64 65 20 74 68  d to override th
1e1d0 65 0a 20 20 6c 69 6b 65 28 29 20 66 75 6e 63 74  e.  like() funct
1e1e0 69 6f 6e 20 61 6e 64 20 74 68 65 72 65 62 79 20  ion and thereby 
1e1f0 63 68 61 6e 67 65 20 74 68 65 20 6f 70 65 72 61  change the opera
1e200 74 69 6f 6e 20 6f 66 20 74 68 65 0a 20 20 5b 4c  tion of the.  [L
1e210 49 4b 45 5d 20 6f 70 65 72 61 74 6f 72 2e 20 20  IKE] operator.  
1e220 57 68 65 6e 20 6f 76 65 72 72 69 64 69 6e 67 20  When overriding 
1e230 74 68 65 20 6c 69 6b 65 28 29 20 66 75 6e 63 74  the like() funct
1e240 69 6f 6e 2c 20 69 74 20 6d 61 79 20 62 65 20 69  ion, it may be i
1e250 6d 70 6f 72 74 61 6e 74 0a 20 20 74 6f 20 6f 76  mportant.  to ov
1e260 65 72 72 69 64 65 20 62 6f 74 68 20 74 68 65 20  erride both the 
1e270 74 77 6f 20 61 6e 64 20 74 68 72 65 65 20 61 72  two and three ar
1e280 67 75 6d 65 6e 74 20 76 65 72 73 69 6f 6e 73 20  gument versions 
1e290 6f 66 20 74 68 65 20 6c 69 6b 65 28 29 20 0a 20  of the like() . 
1e2a0 20 66 75 6e 63 74 69 6f 6e 2e 20 4f 74 68 65 72   function. Other
1e2b0 77 69 73 65 2c 20 64 69 66 66 65 72 65 6e 74 20  wise, different 
1e2c0 63 6f 64 65 20 6d 61 79 20 62 65 20 63 61 6c 6c  code may be call
1e2d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1e2e0 74 68 65 0a 20 20 5b 4c 49 4b 45 5d 20 6f 70 65  the.  [LIKE] ope
1e2f0 72 61 74 6f 72 20 64 65 70 65 6e 64 69 6e 67 20  rator depending 
1e300 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
1e310 74 20 61 6e 20 45 53 43 41 50 45 20 63 6c 61 75  t an ESCAPE clau
1e320 73 65 20 77 61 73 20 0a 20 20 73 70 65 63 69 66  se was .  specif
1e330 69 65 64 2e 0a 7d 0a 0a 0a 66 75 6e 63 64 65 66  ied..}...funcdef
1e340 20 7b 6c 69 6b 65 6c 69 68 6f 6f 64 28 58 2c 59   {likelihood(X,Y
1e350 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c  )} {} {.  ^The l
1e360 69 6b 65 6c 69 68 6f 6f 64 28 58 2c 59 29 20 66  ikelihood(X,Y) f
1e370 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1e380 61 72 67 75 6d 65 6e 74 20 58 20 75 6e 63 68 61  argument X uncha
1e390 6e 67 65 64 2e 0a 20 20 5e 28 54 68 65 20 76 61  nged..  ^(The va
1e3a0 6c 75 65 20 59 20 69 6e 20 6c 69 6b 65 6c 69 68  lue Y in likelih
1e3b0 6f 6f 64 28 58 2c 59 29 20 6d 75 73 74 20 62 65  ood(X,Y) must be
1e3c0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
1e3d0 74 20 63 6f 6e 73 74 61 6e 74 0a 20 20 62 65 74  t constant.  bet
1e3e0 77 65 65 6e 20 30 2e 30 20 61 6e 64 20 31 2e 30  ween 0.0 and 1.0
1e3f0 2c 20 69 6e 63 6c 75 73 69 76 65 2e 29 5e 0a 20  , inclusive.)^. 
1e400 20 5e 54 68 65 20 6c 69 6b 65 6c 69 68 6f 6f 64   ^The likelihood
1e410 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  (X) function is 
1e420 61 20 6e 6f 2d 6f 70 20 74 68 61 74 20 74 68 65  a no-op that the
1e430 20 63 6f 64 65 20 67 65 6e 65 72 61 74 6f 72 0a   code generator.
1e440 20 20 6f 70 74 69 6d 69 7a 65 73 20 61 77 61 79    optimizes away
1e450 20 73 6f 20 74 68 61 74 20 69 74 20 63 6f 6e 73   so that it cons
1e460 75 6d 65 73 20 6e 6f 20 43 50 55 20 63 79 63 6c  umes no CPU cycl
1e470 65 73 20 64 75 72 69 6e 67 20 72 75 6e 2d 74 69  es during run-ti
1e480 6d 65 0a 20 20 28 74 68 61 74 20 69 73 2c 20 64  me.  (that is, d
1e490 75 72 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  uring calls to [
1e4a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 29  sqlite3_step()])
1e4b0 2e 0a 20 20 5e 54 68 65 20 70 75 72 70 6f 73 65  ..  ^The purpose
1e4c0 20 6f 66 20 74 68 65 20 6c 69 6b 65 6c 69 68 6f   of the likeliho
1e4d0 6f 64 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e  od(X,Y) function
1e4e0 20 69 73 20 74 6f 20 70 72 6f 76 69 64 65 20 61   is to provide a
1e4f0 20 68 69 6e 74 0a 20 20 74 6f 20 74 68 65 20 71   hint.  to the q
1e500 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 74 68 61  uery planner tha
1e510 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 58  t the argument X
1e520 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 74 68   is a boolean th
1e530 61 74 20 69 73 0a 20 20 74 72 75 65 20 77 69 74  at is.  true wit
1e540 68 20 61 20 70 72 6f 62 61 62 69 6c 69 74 79 20  h a probability 
1e550 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
1e560 20 59 2e 0a 20 20 5e 28 54 68 65 20 5b 75 6e 6c   Y..  ^(The [unl
1e570 69 6b 65 6c 79 28 58 29 5d 20 66 75 6e 63 74 69  ikely(X)] functi
1e580 6f 6e 20 69 73 20 73 68 6f 72 74 2d 68 61 6e 64  on is short-hand
1e590 20 66 6f 72 20 6c 69 6b 65 6c 69 68 6f 6f 64 28   for likelihood(
1e5a0 58 2c 30 2e 30 36 32 35 29 2e 29 5e 0a 20 20 5e  X,0.0625).)^.  ^
1e5b0 28 54 68 65 20 5b 6c 69 6b 65 6c 79 28 58 29 5d  (The [likely(X)]
1e5c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 68 6f   function is sho
1e5d0 72 74 2d 68 61 6e 64 20 66 6f 72 20 6c 69 6b 65  rt-hand for like
1e5e0 6c 69 68 6f 6f 64 28 58 2c 30 2e 39 33 37 35 29  lihood(X,0.9375)
1e5f0 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  .)^.}..funcdef {
1e600 6c 69 6b 65 6c 79 28 58 29 7d 20 7b 7d 20 7b 0a  likely(X)} {} {.
1e610 20 20 5e 54 68 65 20 6c 69 6b 65 6c 79 28 58 29    ^The likely(X)
1e620 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1e630 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 58  s the argument X
1e640 20 75 6e 63 68 61 6e 67 65 64 2e 0a 20 20 5e 54   unchanged..  ^T
1e650 68 65 20 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e  he likely(X) fun
1e660 63 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ction is a no-op
1e670 20 74 68 61 74 20 74 68 65 20 63 6f 64 65 20 67   that the code g
1e680 65 6e 65 72 61 74 6f 72 0a 20 20 6f 70 74 69 6d  enerator.  optim
1e690 69 7a 65 73 20 61 77 61 79 20 73 6f 20 74 68 61  izes away so tha
1e6a0 74 20 69 74 20 63 6f 6e 73 75 6d 65 73 20 6e 6f  t it consumes no
1e6b0 20 43 50 55 20 63 79 63 6c 65 73 20 61 74 0a 20   CPU cycles at. 
1e6c0 20 72 75 6e 2d 74 69 6d 65 20 28 74 68 61 74 20   run-time (that 
1e6d0 69 73 2c 20 64 75 72 69 6e 67 20 63 61 6c 6c 73  is, during calls
1e6e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
1e6f0 70 28 29 5d 29 2e 0a 20 20 5e 54 68 65 20 70 75  p()])..  ^The pu
1e700 72 70 6f 73 65 20 6f 66 20 74 68 65 20 6c 69 6b  rpose of the lik
1e710 65 6c 79 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  ely(X) function 
1e720 69 73 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  is to provide a 
1e730 68 69 6e 74 0a 20 20 74 6f 20 74 68 65 20 71 75  hint.  to the qu
1e740 65 72 79 20 70 6c 61 6e 6e 65 72 20 74 68 61 74  ery planner that
1e750 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20   the argument X 
1e760 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c  is a boolean val
1e770 75 65 0a 20 20 74 68 61 74 20 69 73 20 75 73 75  ue.  that is usu
1e780 61 6c 6c 79 20 74 72 75 65 2e 20 5e 28 54 68 65  ally true. ^(The
1e790 20 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e 63 74   likely(X) funct
1e7a0 69 6f 6e 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ion is equivalen
1e7b0 74 0a 20 20 74 6f 20 5b 6c 69 6b 65 6c 69 68 6f  t.  to [likeliho
1e7c0 6f 64 5d 28 58 2c 30 2e 39 33 37 35 29 2e 29 5e  od](X,0.9375).)^
1e7d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 75 6e 6c 69   See also: [unli
1e7e0 6b 65 6c 79 28 58 29 5d 2e 0a 7d 0a 0a 66 75 6e  kely(X)]..}..fun
1e7f0 63 64 65 66 20 7b 6c 6f 61 64 5f 65 78 74 65 6e  cdef {load_exten
1e800 73 69 6f 6e 28 58 29 20 6c 6f 61 64 5f 65 78 74  sion(X) load_ext
1e810 65 6e 73 69 6f 6e 28 58 2c 59 29 7d 20 7b 7d 20  ension(X,Y)} {} 
1e820 7b 0a 20 20 5e 54 68 65 20 6c 6f 61 64 5f 65 78  {.  ^The load_ex
1e830 74 65 6e 73 69 6f 6e 28 58 2c 59 29 20 66 75 6e  tension(X,Y) fun
1e840 63 74 69 6f 6e 20 6c 6f 61 64 73 20 5b 53 51 4c  ction loads [SQL
1e850 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 20  ite extensions] 
1e860 6f 75 74 20 6f 66 20 74 68 65 20 73 68 61 72 65  out of the share
1e870 64 0a 20 20 6c 69 62 72 61 72 79 20 66 69 6c 65  d.  library file
1e880 20 6e 61 6d 65 64 20 58 20 75 73 69 6e 67 20 74   named X using t
1e890 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 59  he entry point Y
1e8a0 2e 20 20 5e 54 68 65 20 72 65 73 75 6c 74 20 6f  .  ^The result o
1e8b0 66 20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  f load_extension
1e8c0 28 29 0a 20 20 69 73 20 61 6c 77 61 79 73 20 61  ().  is always a
1e8d0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 59 20 69 73   NULL.  ^If Y is
1e8e0 20 6f 6d 69 74 74 65 64 20 74 68 65 6e 20 74 68   omitted then th
1e8f0 65 20 64 65 66 61 75 6c 74 20 65 6e 74 72 79 20  e default entry 
1e900 70 6f 69 6e 74 20 6e 61 6d 65 20 69 73 20 75 73  point name is us
1e910 65 64 2e 0a 20 20 5e 54 68 65 20 6c 6f 61 64 5f  ed..  ^The load_
1e920 65 78 74 65 6e 73 69 6f 6e 28 29 20 66 75 6e 63  extension() func
1e930 74 69 6f 6e 20 72 61 69 73 65 73 20 61 6e 20 65  tion raises an e
1e940 78 63 65 70 74 69 6f 6e 20 69 66 20 74 68 65 20  xception if the 
1e950 65 78 74 65 6e 73 69 6f 6e 20 66 61 69 6c 73 20  extension fails 
1e960 74 6f 0a 20 20 6c 6f 61 64 20 6f 72 20 69 6e 69  to.  load or ini
1e970 74 69 61 6c 69 7a 65 20 63 6f 72 72 65 63 74 6c  tialize correctl
1e980 79 2e 0a 0a 20 20 3c 70 3e 5e 54 68 65 20 6c 6f  y...  <p>^The lo
1e990 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 66  ad_extension() f
1e9a0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 66 61 69  unction will fai
1e9b0 6c 20 69 66 20 74 68 65 20 65 78 74 65 6e 73 69  l if the extensi
1e9c0 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 0a  on attempts to .
1e9d0 20 20 6d 6f 64 69 66 79 20 6f 72 20 64 65 6c 65    modify or dele
1e9e0 74 65 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  te an SQL functi
1e9f0 6f 6e 20 6f 72 20 63 6f 6c 6c 61 74 69 6e 67 20  on or collating 
1ea00 73 65 71 75 65 6e 63 65 2e 20 20 5e 54 68 65 0a  sequence.  ^The.
1ea10 20 20 65 78 74 65 6e 73 69 6f 6e 20 63 61 6e 20    extension can 
1ea20 61 64 64 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  add new function
1ea30 73 20 6f 72 20 63 6f 6c 6c 61 74 69 6e 67 20 73  s or collating s
1ea40 65 71 75 65 6e 63 65 73 2c 20 62 75 74 20 63 61  equences, but ca
1ea50 6e 6e 6f 74 0a 20 20 6d 6f 64 69 66 79 20 6f 72  nnot.  modify or
1ea60 20 64 65 6c 65 74 65 20 65 78 69 73 74 69 6e 67   delete existing
1ea70 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 63 6f   functions or co
1ea80 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
1ea90 73 20 62 65 63 61 75 73 65 0a 20 20 74 68 6f 73  s because.  thos
1eaa0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 2f  e functions and/
1eab0 6f 72 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  or collating seq
1eac0 75 65 6e 63 65 73 20 6d 69 67 68 74 20 62 65 20  uences might be 
1ead0 75 73 65 64 20 65 6c 73 65 77 68 65 72 65 0a 20  used elsewhere. 
1eae0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 6c   in the currentl
1eaf0 79 20 72 75 6e 6e 69 6e 67 20 53 51 4c 20 73 74  y running SQL st
1eb00 61 74 65 6d 65 6e 74 2e 20 20 54 6f 20 6c 6f 61  atement.  To loa
1eb10 64 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 74  d an extension t
1eb20 68 61 74 0a 20 20 63 68 61 6e 67 65 73 20 6f 72  hat.  changes or
1eb30 20 64 65 6c 65 74 65 73 20 66 75 6e 63 74 69 6f   deletes functio
1eb40 6e 73 20 6f 72 20 63 6f 6c 6c 61 74 69 6e 67 20  ns or collating 
1eb50 73 65 71 75 65 6e 63 65 73 2c 20 75 73 65 20 74  sequences, use t
1eb60 68 65 0a 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  he.  [sqlite3_lo
1eb70 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1eb80 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 2e 3c  C-language API.<
1eb90 2f 70 3e 0a 0a 20 20 3c 70 3e 46 6f 72 20 73 65  /p>..  <p>For se
1eba0 63 75 72 69 74 79 20 72 65 61 73 6f 6e 73 2c 20  curity reasons, 
1ebb0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 65 64  extension loaded
1ebc0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 20 62   is turned off b
1ebd0 79 20 64 65 66 61 75 6c 74 20 61 6e 64 20 6d 75  y default and mu
1ebe0 73 74 0a 20 20 62 65 20 65 6e 61 62 6c 65 64 20  st.  be enabled 
1ebf0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
1ec00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  to [sqlite3_enab
1ec10 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
1ec20 6e 28 29 5d 2e 3c 2f 70 3e 0a 7d 0a 0a 66 75 6e  n()].</p>.}..fun
1ec30 63 64 65 66 20 7b 6c 6f 77 65 72 28 58 29 7d 20  cdef {lower(X)} 
1ec40 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c 6f 77 65  {} {.  ^The lowe
1ec50 72 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  r(X) function re
1ec60 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
1ec70 73 74 72 69 6e 67 20 58 20 77 69 74 68 20 61 6c  string X with al
1ec80 6c 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  l ASCII characte
1ec90 72 73 0a 20 20 63 6f 6e 76 65 72 74 65 64 20 74  rs.  converted t
1eca0 6f 20 6c 6f 77 65 72 20 63 61 73 65 2e 20 20 5e  o lower case.  ^
1ecb0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 69 6c  The default buil
1ecc0 74 2d 69 6e 20 6c 6f 77 65 72 28 29 20 66 75 6e  t-in lower() fun
1ecd0 63 74 69 6f 6e 20 77 6f 72 6b 73 0a 20 20 66 6f  ction works.  fo
1ece0 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  r ASCII characte
1ecf0 72 73 20 6f 6e 6c 79 2e 20 20 54 6f 20 64 6f 20  rs only.  To do 
1ed00 63 61 73 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  case conversions
1ed10 20 6f 6e 20 6e 6f 6e 2d 41 53 43 49 49 0a 20 20   on non-ASCII.  
1ed20 63 68 61 72 61 63 74 65 72 73 2c 20 6c 6f 61 64  characters, load
1ed30 20 74 68 65 20 49 43 55 20 65 78 74 65 6e 73 69   the ICU extensi
1ed40 6f 6e 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  on..}..funcdef {
1ed50 6c 74 72 69 6d 28 58 29 20 6c 74 72 69 6d 28 58  ltrim(X) ltrim(X
1ed60 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65  ,Y)} {} {.  ^The
1ed70 20 6c 74 72 69 6d 28 58 2c 59 29 20 66 75 6e 63   ltrim(X,Y) func
1ed80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73  tion returns a s
1ed90 74 72 69 6e 67 20 66 6f 72 6d 65 64 20 62 79 20  tring formed by 
1eda0 72 65 6d 6f 76 69 6e 67 20 61 6e 79 20 61 6e 64  removing any and
1edb0 20 61 6c 6c 0a 20 20 63 68 61 72 61 63 74 65 72   all.  character
1edc0 73 20 74 68 61 74 20 61 70 70 65 61 72 20 69 6e  s that appear in
1edd0 20 59 20 66 72 6f 6d 20 74 68 65 20 6c 65 66 74   Y from the left
1ede0 20 73 69 64 65 20 6f 66 20 58 2e 0a 20 20 5e 49   side of X..  ^I
1edf0 66 20 74 68 65 20 59 20 61 72 67 75 6d 65 6e 74  f the Y argument
1ee00 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 6c 74 72   is omitted, ltr
1ee10 69 6d 28 58 29 20 72 65 6d 6f 76 65 73 20 73 70  im(X) removes sp
1ee20 61 63 65 73 20 66 72 6f 6d 20 74 68 65 20 6c 65  aces from the le
1ee30 66 74 20 73 69 64 65 0a 20 20 6f 66 20 58 2e 0a  ft side.  of X..
1ee40 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6d 61 78 28  }..funcdef {max(
1ee50 58 2c 59 2c 2e 2e 2e 29 7d 20 7b 2a 6d 61 78 43  X,Y,...)} {*maxC
1ee60 6f 72 65 46 75 6e 63 20 2a 6d 61 78 20 7b 6d 61  oreFunc *max {ma
1ee70 78 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  x() SQL function
1ee80 7d 7d 20 7b 0a 20 20 5e 54 68 65 20 6d 75 6c 74  }} {.  ^The mult
1ee90 69 2d 61 72 67 75 6d 65 6e 74 20 6d 61 78 28 29  i-argument max()
1eea0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1eeb0 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 77  s the argument w
1eec0 69 74 68 20 74 68 65 20 0a 20 20 6d 61 78 69 6d  ith the .  maxim
1eed0 75 6d 20 76 61 6c 75 65 2c 20 6f 72 20 72 65 74  um value, or ret
1eee0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 6e 79 20  urn NULL if any 
1eef0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
1ef00 2e 20 0a 20 20 5e 54 68 65 20 6d 75 6c 74 69 2d  . .  ^The multi-
1ef10 61 72 67 75 6d 65 6e 74 20 6d 61 78 28 29 20 66  argument max() f
1ef20 75 6e 63 74 69 6f 6e 20 73 65 61 72 63 68 65 73  unction searches
1ef30 20 69 74 73 20 61 72 67 75 6d 65 6e 74 73 20 66   its arguments f
1ef40 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68  rom left to righ
1ef50 74 0a 20 20 66 6f 72 20 61 6e 20 61 72 67 75 6d  t.  for an argum
1ef60 65 6e 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ent that defines
1ef70 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
1ef80 63 74 69 6f 6e 20 61 6e 64 20 75 73 65 73 20 74  ction and uses t
1ef90 68 61 74 20 63 6f 6c 6c 61 74 69 6e 67 0a 20 20  hat collating.  
1efa0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  function for all
1efb0 20 73 74 72 69 6e 67 20 63 6f 6d 70 61 72 69 73   string comparis
1efc0 6f 6e 73 2e 20 20 5e 49 66 20 6e 6f 6e 65 20 6f  ons.  ^If none o
1efd0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20  f the arguments 
1efe0 74 6f 20 6d 61 78 28 29 0a 20 20 64 65 66 69 6e  to max().  defin
1eff0 65 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  e a collating fu
1f000 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  nction, then the
1f010 20 42 49 4e 41 52 59 20 63 6f 6c 6c 61 74 69 6e   BINARY collatin
1f020 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  g function is us
1f030 65 64 2e 0a 20 20 5e 28 4e 6f 74 65 20 74 68 61  ed..  ^(Note tha
1f040 74 20 3c 62 3e 6d 61 78 28 29 3c 2f 62 3e 20 69  t <b>max()</b> i
1f050 73 20 61 20 73 69 6d 70 6c 65 20 66 75 6e 63 74  s a simple funct
1f060 69 6f 6e 20 77 68 65 6e 0a 20 20 69 74 20 68 61  ion when.  it ha
1f070 73 20 32 20 6f 72 20 6d 6f 72 65 20 61 72 67 75  s 2 or more argu
1f080 6d 65 6e 74 73 20 62 75 74 20 6f 70 65 72 61 74  ments but operat
1f090 65 73 20 61 73 20 61 6e 0a 20 20 5b 6d 61 78 41  es as an.  [maxA
1f0a0 67 67 46 75 6e 63 20 7c 20 61 67 67 72 65 67 61  ggFunc | aggrega
1f0b0 74 65 20 66 75 6e 63 74 69 6f 6e 5d 20 69 66 20  te function] if 
1f0c0 67 69 76 65 6e 20 6f 6e 6c 79 20 61 20 73 69 6e  given only a sin
1f0d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 2e 29 5e 0a  gle argument.)^.
1f0e0 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6d 69 6e 28  }..funcdef {min(
1f0f0 58 2c 59 2c 2e 2e 2e 29 7d 20 7b 2a 6d 69 6e 43  X,Y,...)} {*minC
1f100 6f 72 65 46 75 6e 63 20 2a 6d 69 6e 20 7b 6d 69  oreFunc *min {mi
1f110 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  n() SQL function
1f120 7d 7d 20 7b 0a 20 20 5e 54 68 65 20 6d 75 6c 74  }} {.  ^The mult
1f130 69 2d 61 72 67 75 6d 65 6e 74 20 6d 69 6e 28 29  i-argument min()
1f140 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1f150 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 77  s the argument w
1f160 69 74 68 20 74 68 65 0a 20 20 6d 69 6e 69 6d 75  ith the.  minimu
1f170 6d 20 76 61 6c 75 65 2e 0a 20 20 5e 54 68 65 20  m value..  ^The 
1f180 6d 75 6c 74 69 2d 61 72 67 75 6d 65 6e 74 20 6d  multi-argument m
1f190 69 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 65  in() function se
1f1a0 61 72 63 68 65 73 20 69 74 73 20 61 72 67 75 6d  arches its argum
1f1b0 65 6e 74 73 20 66 72 6f 6d 20 6c 65 66 74 20 74  ents from left t
1f1c0 6f 20 72 69 67 68 74 0a 20 20 66 6f 72 20 61 6e  o right.  for an
1f1d0 20 61 72 67 75 6d 65 6e 74 20 74 68 61 74 20 64   argument that d
1f1e0 65 66 69 6e 65 73 20 61 20 63 6f 6c 6c 61 74 69  efines a collati
1f1f0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20  ng function and 
1f200 75 73 65 73 20 74 68 61 74 20 63 6f 6c 6c 61 74  uses that collat
1f210 69 6e 67 0a 20 20 66 75 6e 63 74 69 6f 6e 20 66  ing.  function f
1f220 6f 72 20 61 6c 6c 20 73 74 72 69 6e 67 20 63 6f  or all string co
1f230 6d 70 61 72 69 73 6f 6e 73 2e 20 20 5e 49 66 20  mparisons.  ^If 
1f240 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 72 67 75  none of the argu
1f250 6d 65 6e 74 73 20 74 6f 20 6d 69 6e 28 29 0a 20  ments to min(). 
1f260 20 64 65 66 69 6e 65 20 61 20 63 6f 6c 6c 61 74   define a collat
1f270 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68  ing function, th
1f280 65 6e 20 74 68 65 20 42 49 4e 41 52 59 20 63 6f  en the BINARY co
1f290 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
1f2a0 20 69 73 20 75 73 65 64 2e 0a 20 20 5e 28 4e 6f   is used..  ^(No
1f2b0 74 65 20 74 68 61 74 20 3c 62 3e 6d 69 6e 28 29  te that <b>min()
1f2c0 3c 2f 62 3e 20 69 73 20 61 20 73 69 6d 70 6c 65  </b> is a simple
1f2d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 0a 20   function when. 
1f2e0 20 69 74 20 68 61 73 20 32 20 6f 72 20 6d 6f 72   it has 2 or mor
1f2f0 65 20 61 72 67 75 6d 65 6e 74 73 20 62 75 74 20  e arguments but 
1f300 6f 70 65 72 61 74 65 73 20 61 73 20 61 6e 20 0a  operates as an .
1f310 20 20 5b 6d 69 6e 41 67 67 46 75 6e 63 20 7c 20    [minAggFunc | 
1f320 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
1f330 6f 6e 5d 20 69 66 20 67 69 76 65 6e 0a 20 20 6f  on] if given.  o
1f340 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 72 67  nly a single arg
1f350 75 6d 65 6e 74 2e 29 5e 0a 7d 0a 0a 66 75 6e 63  ument.)^.}..func
1f360 64 65 66 20 7b 6e 75 6c 6c 69 66 28 58 2c 59 29  def {nullif(X,Y)
1f370 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6e 75  } {} {.  ^The nu
1f380 6c 6c 69 66 28 58 2c 59 29 20 66 75 6e 63 74 69  llif(X,Y) functi
1f390 6f 6e 20 72 65 74 75 72 6e 73 20 69 74 73 20 66  on returns its f
1f3a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 66  irst argument if
1f3b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20 61   the arguments a
1f3c0 72 65 0a 20 20 64 69 66 66 65 72 65 6e 74 20 61  re.  different a
1f3d0 6e 64 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 61  nd NULL if the a
1f3e0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 74 68 65  rguments are the
1f3f0 20 73 61 6d 65 2e 20 20 5e 54 68 65 20 6e 75 6c   same.  ^The nul
1f400 6c 69 66 28 58 2c 59 29 20 66 75 6e 63 74 69 6f  lif(X,Y) functio
1f410 6e 0a 20 20 73 65 61 72 63 68 65 73 20 69 74 73  n.  searches its
1f420 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20   arguments from 
1f430 6c 65 66 74 20 74 6f 20 72 69 67 68 74 20 66 6f  left to right fo
1f440 72 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 68  r an argument th
1f450 61 74 20 64 65 66 69 6e 65 73 20 61 0a 20 20 63  at defines a.  c
1f460 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
1f470 6e 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  n and uses that 
1f480 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
1f490 6f 6e 20 66 6f 72 20 61 6c 6c 20 73 74 72 69 6e  on for all strin
1f4a0 67 0a 20 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e  g.  comparisons.
1f4b0 20 20 5e 49 66 20 6e 65 69 74 68 65 72 20 61 72    ^If neither ar
1f4c0 67 75 6d 65 6e 74 20 74 6f 20 6e 75 6c 6c 69 66  gument to nullif
1f4d0 28 29 20 64 65 66 69 6e 65 73 20 61 20 63 6f 6c  () defines a col
1f4e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a  lating function.
1f4f0 20 20 74 68 65 6e 20 74 68 65 20 42 49 4e 41 52    then the BINAR
1f500 59 20 69 73 20 75 73 65 64 2e 0a 7d 0a 0a 66 75  Y is used..}..fu
1f510 6e 63 64 65 66 20 7b 70 72 69 6e 74 66 28 46 4f  ncdef {printf(FO
1f520 52 4d 41 54 2c 2e 2e 2e 29 7d 20 7b 7d 20 7b 0a  RMAT,...)} {} {.
1f530 20 20 5e 28 54 68 65 20 70 72 69 6e 74 66 28 46    ^(The printf(F
1f540 4f 52 4d 41 54 2c 2e 2e 2e 29 20 53 51 4c 20 66  ORMAT,...) SQL f
1f550 75 6e 63 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69  unction works li
1f560 6b 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ke the [sqlite3_
1f570 6d 70 72 69 6e 74 66 28 29 5d 20 43 2d 6c 61 6e  mprintf()] C-lan
1f580 67 75 61 67 65 0a 20 20 66 75 6e 63 74 69 6f 6e  guage.  function
1f590 20 61 6e 64 20 74 68 65 20 70 72 69 6e 74 66 28   and the printf(
1f5a0 29 20 66 75 6e 63 74 69 6f 6e 20 66 72 6f 6d 20  ) function from 
1f5b0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1f5c0 69 62 72 61 72 79 2e 29 5e 0a 20 20 54 68 65 20  ibrary.)^.  The 
1f5d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
1f5e0 73 20 61 20 66 6f 72 6d 61 74 20 73 74 72 69 6e  s a format strin
1f5f0 67 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  g that specifies
1f600 20 68 6f 77 20 74 6f 20 63 6f 6e 73 74 72 75 63   how to construc
1f610 74 20 74 68 65 20 6f 75 74 70 75 74 0a 20 20 73  t the output.  s
1f620 74 72 69 6e 67 20 75 73 69 6e 67 20 76 61 6c 75  tring using valu
1f630 65 73 20 74 61 6b 65 6e 20 66 72 6f 6d 20 73 75  es taken from su
1f640 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
1f650 74 73 2e 20 20 5e 49 66 20 74 68 65 20 46 4f 52  ts.  ^If the FOR
1f660 4d 41 54 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  MAT argument is.
1f670 20 20 6d 69 73 73 69 6e 67 20 6f 72 20 4e 55 4c    missing or NUL
1f680 4c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  L then the resul
1f690 74 20 69 73 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  t is NULL.  ^The
1f6a0 20 25 6e 20 66 6f 72 6d 61 74 20 69 73 20 73 69   %n format is si
1f6b0 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 64 20 61  lently ignored a
1f6c0 6e 64 0a 20 20 64 6f 65 73 20 6e 6f 74 20 63 6f  nd.  does not co
1f6d0 6e 73 75 6d 65 20 61 6e 20 61 72 67 75 6d 65 6e  nsume an argumen
1f6e0 74 2e 20 20 5e 54 68 65 20 25 70 20 66 6f 72 6d  t.  ^The %p form
1f6f0 61 74 20 69 73 20 61 6e 20 61 6c 69 61 73 20 66  at is an alias f
1f700 6f 72 20 25 58 2e 20 20 5e 54 68 65 20 25 7a 20  or %X.  ^The %z 
1f710 66 6f 72 6d 61 74 0a 20 20 69 73 20 69 6e 74 65  format.  is inte
1f720 72 63 68 61 6e 67 65 61 62 6c 65 20 77 69 74 68  rchangeable with
1f730 20 25 73 2e 20 20 5e 28 49 66 20 74 68 65 72 65   %s.  ^(If there
1f740 20 61 72 65 20 74 6f 6f 20 66 65 77 20 61 72 67   are too few arg
1f750 75 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  uments in the ar
1f760 67 75 6d 65 6e 74 20 6c 69 73 74 2c 0a 20 20 6d  gument list,.  m
1f770 69 73 73 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  issing arguments
1f780 20 61 72 65 20 61 73 73 75 6d 65 64 20 74 6f 20   are assumed to 
1f790 68 61 76 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75  have a NULL valu
1f7a0 65 2c 20 77 68 69 63 68 20 69 73 20 74 72 61 6e  e, which is tran
1f7b0 73 6c 61 74 65 64 20 69 6e 74 6f 0a 20 20 30 20  slated into.  0 
1f7c0 6f 72 20 30 2e 30 20 66 6f 72 20 6e 75 6d 65 72  or 0.0 for numer
1f7d0 69 63 20 66 6f 72 6d 61 74 73 20 6f 72 20 61 6e  ic formats or an
1f7e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 66 6f   empty string fo
1f7f0 72 20 25 73 2e 29 5e 20 20 53 65 65 20 74 68 65  r %s.)^  See the
1f800 0a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  .  [built-in pri
1f810 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  ntf()] documenta
1f820 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
1f830 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
1f840 0a 7d 0a 20 20 0a 0a 66 75 6e 63 64 65 66 20 7b  .}.  ..funcdef {
1f850 71 75 6f 74 65 28 58 29 7d 20 7b 7d 20 7b 0a 20  quote(X)} {} {. 
1f860 20 5e 54 68 65 20 71 75 6f 74 65 28 58 29 20 66   ^The quote(X) f
1f870 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1f880 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 53  the text of an S
1f890 51 4c 20 6c 69 74 65 72 61 6c 20 77 68 69 63 68  QL literal which
1f8a0 0a 20 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  .  is the value 
1f8b0 6f 66 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  of its argument 
1f8c0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 69 6e 63  suitable for inc
1f8d0 6c 75 73 69 6f 6e 20 69 6e 74 6f 20 61 6e 20 53  lusion into an S
1f8e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 20 20  QL statement..  
1f8f0 5e 53 74 72 69 6e 67 73 20 61 72 65 20 73 75 72  ^Strings are sur
1f900 72 6f 75 6e 64 65 64 20 62 79 20 73 69 6e 67 6c  rounded by singl
1f910 65 2d 71 75 6f 74 65 73 20 77 69 74 68 20 65 73  e-quotes with es
1f920 63 61 70 65 73 20 6f 6e 20 69 6e 74 65 72 69 6f  capes on interio
1f930 72 20 71 75 6f 74 65 73 0a 20 20 61 73 20 6e 65  r quotes.  as ne
1f940 65 64 65 64 2e 20 20 5e 42 4c 4f 42 73 20 61 72  eded.  ^BLOBs ar
1f950 65 20 65 6e 63 6f 64 65 64 20 61 73 20 68 65 78  e encoded as hex
1f960 61 64 65 63 69 6d 61 6c 20 6c 69 74 65 72 61 6c  adecimal literal
1f970 73 2e 0a 20 20 5e 53 74 72 69 6e 67 73 20 77 69  s..  ^Strings wi
1f980 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 20  th embedded NUL 
1f990 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 6e 6f  characters canno
1f9a0 74 20 62 65 20 72 65 70 72 65 73 65 6e 74 65 64  t be represented
1f9b0 20 61 73 20 73 74 72 69 6e 67 0a 20 20 6c 69 74   as string.  lit
1f9c0 65 72 61 6c 73 20 69 6e 20 53 51 4c 20 61 6e 64  erals in SQL and
1f9d0 20 68 65 6e 63 65 20 74 68 65 20 72 65 74 75 72   hence the retur
1f9e0 6e 65 64 20 73 74 72 69 6e 67 20 6c 69 74 65 72  ned string liter
1f9f0 61 6c 20 69 73 20 74 72 75 6e 63 61 74 65 64 20  al is truncated 
1fa00 70 72 69 6f 72 0a 20 20 74 6f 20 74 68 65 20 66  prior.  to the f
1fa10 69 72 73 74 20 4e 55 4c 2e 0a 7d 0a 0a 66 75 6e  irst NUL..}..fun
1fa20 63 64 65 66 20 7b 72 61 6e 64 6f 6d 28 29 7d 20  cdef {random()} 
1fa30 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72 61 6e 64  {} {.  ^The rand
1fa40 6f 6d 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  om() function re
1fa50 74 75 72 6e 73 20 61 20 70 73 65 75 64 6f 2d 72  turns a pseudo-r
1fa60 61 6e 64 6f 6d 20 69 6e 74 65 67 65 72 0a 20 20  andom integer.  
1fa70 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
1fa80 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
1fa90 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
1faa0 37 35 38 30 37 2e 0a 7d 0a 0a 66 75 6e 63 64 65  75807..}..funcde
1fab0 66 20 7b 72 61 6e 64 6f 6d 62 6c 6f 62 28 4e 29  f {randomblob(N)
1fac0 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72 61  } {} {.  ^The ra
1fad0 6e 64 6f 6d 62 6c 6f 62 28 4e 29 20 66 75 6e 63  ndomblob(N) func
1fae0 74 69 6f 6e 20 72 65 74 75 72 6e 20 61 6e 20 4e  tion return an N
1faf0 2d 62 79 74 65 20 62 6c 6f 62 20 63 6f 6e 74 61  -byte blob conta
1fb00 69 6e 69 6e 67 20 70 73 65 75 64 6f 2d 72 61 6e  ining pseudo-ran
1fb10 64 6f 6d 0a 20 20 62 79 74 65 73 2e 20 5e 49 66  dom.  bytes. ^If
1fb20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1fb30 31 20 74 68 65 6e 20 61 20 31 2d 62 79 74 65 20  1 then a 1-byte 
1fb40 72 61 6e 64 6f 6d 20 62 6c 6f 62 20 69 73 20 72  random blob is r
1fb50 65 74 75 72 6e 65 64 2e 0a 0a 20 20 3c 70 3e 48  eturned...  <p>H
1fb60 69 6e 74 3a 20 20 61 70 70 6c 69 63 61 74 69 6f  int:  applicatio
1fb70 6e 73 20 63 61 6e 20 67 65 6e 65 72 61 74 65 20  ns can generate 
1fb80 67 6c 6f 62 61 6c 6c 79 20 75 6e 69 71 75 65 20  globally unique 
1fb90 69 64 65 6e 74 69 66 69 65 72 73 0a 20 20 75 73  identifiers.  us
1fba0 69 6e 67 20 74 68 69 73 20 66 75 6e 63 74 69 6f  ing this functio
1fbb0 6e 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  n together with 
1fbc0 5b 68 65 78 28 29 5d 20 61 6e 64 2f 6f 72 0a 20  [hex()] and/or. 
1fbd0 20 5b 6c 6f 77 65 72 28 29 5d 20 6c 69 6b 65 20   [lower()] like 
1fbe0 74 68 69 73 3a 3c 2f 70 3e 0a 0a 20 20 3c 62 6c  this:</p>..  <bl
1fbf0 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 68 65 78 28  ockquote>.  hex(
1fc00 72 61 6e 64 6f 6d 62 6c 6f 62 28 31 36 29 29 3c  randomblob(16))<
1fc10 62 72 3e 3c 2f 62 72 3e 0a 20 20 6c 6f 77 65 72  br></br>.  lower
1fc20 28 68 65 78 28 72 61 6e 64 6f 6d 62 6c 6f 62 28  (hex(randomblob(
1fc30 31 36 29 29 29 0a 20 20 3c 2f 62 6c 6f 63 6b 71  16))).  </blockq
1fc40 75 6f 74 65 3e 0a 7d 0a 0a 66 75 6e 63 64 65 66  uote>.}..funcdef
1fc50 20 7b 72 65 70 6c 61 63 65 28 58 2c 59 2c 5a 29   {replace(X,Y,Z)
1fc60 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72 65  } {} {.  ^The re
1fc70 70 6c 61 63 65 28 58 2c 59 2c 5a 29 20 66 75 6e  place(X,Y,Z) fun
1fc80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1fc90 73 74 72 69 6e 67 20 66 6f 72 6d 65 64 20 62 79  string formed by
1fca0 20 73 75 62 73 74 69 74 75 74 69 6e 67 0a 20 20   substituting.  
1fcb0 73 74 72 69 6e 67 20 5a 20 66 6f 72 20 65 76 65  string Z for eve
1fcc0 72 79 20 6f 63 63 75 72 72 65 6e 63 65 20 6f 66  ry occurrence of
1fcd0 20 73 74 72 69 6e 67 20 59 20 69 6e 20 73 74 72   string Y in str
1fce0 69 6e 67 20 58 2e 20 20 5e 54 68 65 20 5b 42 49  ing X.  ^The [BI
1fcf0 4e 41 52 59 5d 0a 20 20 63 6f 6c 6c 61 74 69 6e  NARY].  collatin
1fd00 67 20 73 65 71 75 65 6e 63 65 20 69 73 20 75 73  g sequence is us
1fd10 65 64 20 66 6f 72 20 63 6f 6d 70 61 72 69 73 6f  ed for compariso
1fd20 6e 73 2e 20 20 5e 49 66 20 59 20 69 73 20 61 6e  ns.  ^If Y is an
1fd30 20 65 6d 70 74 79 0a 20 20 73 74 72 69 6e 67 20   empty.  string 
1fd40 74 68 65 6e 20 72 65 74 75 72 6e 20 58 20 75 6e  then return X un
1fd50 63 68 61 6e 67 65 64 2e 20 20 5e 49 66 20 5a 20  changed.  ^If Z 
1fd60 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79  is not initially
1fd70 0a 20 20 61 20 73 74 72 69 6e 67 2c 20 69 74 20  .  a string, it 
1fd80 69 73 20 63 61 73 74 20 74 6f 20 61 20 55 54 46  is cast to a UTF
1fd90 2d 38 20 73 74 72 69 6e 67 20 70 72 69 6f 72 20  -8 string prior 
1fda0 74 6f 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 7d  to processing..}
1fdb0 0a 0a 66 75 6e 63 64 65 66 20 7b 72 6f 75 6e 64  ..funcdef {round
1fdc0 28 58 29 20 72 6f 75 6e 64 28 58 2c 59 29 7d 20  (X) round(X,Y)} 
1fdd0 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72 6f 75 6e  {} {.  ^The roun
1fde0 64 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20  d(X,Y) function 
1fdf0 72 65 74 75 72 6e 73 20 61 20 66 6c 6f 61 74 69  returns a floati
1fe00 6e 67 2d 70 6f 69 6e 74 0a 20 20 76 61 6c 75 65  ng-point.  value
1fe10 20 58 20 72 6f 75 6e 64 65 64 20 74 6f 20 59 20   X rounded to Y 
1fe20 64 69 67 69 74 73 20 74 6f 20 74 68 65 20 72 69  digits to the ri
1fe30 67 68 74 20 6f 66 20 74 68 65 20 64 65 63 69 6d  ght of the decim
1fe40 61 6c 20 70 6f 69 6e 74 2e 0a 20 20 5e 49 66 20  al point..  ^If 
1fe50 74 68 65 20 59 20 61 72 67 75 6d 65 6e 74 20 69  the Y argument i
1fe60 73 20 6f 6d 69 74 74 65 64 2c 20 69 74 20 69 73  s omitted, it is
1fe70 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 30   assumed to be 0
1fe80 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 72 74  ..}..funcdef {rt
1fe90 72 69 6d 28 58 29 20 72 74 72 69 6d 28 58 2c 59  rim(X) rtrim(X,Y
1fea0 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 72  )} {} {.  ^The r
1feb0 74 72 69 6d 28 58 2c 59 29 20 66 75 6e 63 74 69  trim(X,Y) functi
1fec0 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73 74 72  on returns a str
1fed0 69 6e 67 20 66 6f 72 6d 65 64 20 62 79 20 72 65  ing formed by re
1fee0 6d 6f 76 69 6e 67 20 61 6e 79 20 61 6e 64 20 61  moving any and a
1fef0 6c 6c 0a 20 20 63 68 61 72 61 63 74 65 72 73 20  ll.  characters 
1ff00 74 68 61 74 20 61 70 70 65 61 72 20 69 6e 20 59  that appear in Y
1ff10 20 66 72 6f 6d 20 74 68 65 20 72 69 67 68 74 20   from the right 
1ff20 73 69 64 65 20 6f 66 20 58 2e 0a 20 20 5e 49 66  side of X..  ^If
1ff30 20 74 68 65 20 59 20 61 72 67 75 6d 65 6e 74 20   the Y argument 
1ff40 69 73 20 6f 6d 69 74 74 65 64 2c 20 72 74 72 69  is omitted, rtri
1ff50 6d 28 58 29 20 72 65 6d 6f 76 65 73 20 73 70 61  m(X) removes spa
1ff60 63 65 73 20 66 72 6f 6d 20 74 68 65 20 72 69 67  ces from the rig
1ff70 68 74 0a 20 20 73 69 64 65 20 6f 66 20 58 2e 0a  ht.  side of X..
1ff80 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 73 6f 75 6e  }..funcdef {soun
1ff90 64 65 78 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e  dex(X)} {} {.  ^
1ffa0 54 68 65 20 73 6f 75 6e 64 65 78 28 58 29 20 66  The soundex(X) f
1ffb0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1ffc0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 69 73  a string that is
1ffd0 20 74 68 65 20 73 6f 75 6e 64 65 78 20 65 6e 63   the soundex enc
1ffe0 6f 64 69 6e 67 20 0a 20 20 6f 66 20 74 68 65 20  oding .  of the 
1fff0 73 74 72 69 6e 67 20 58 2e 0a 20 20 5e 54 68 65  string X..  ^The
20000 20 73 74 72 69 6e 67 20 22 3f 30 30 30 22 20 69   string "?000" i
20010 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
20020 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  e argument is NU
20030 4c 4c 20 6f 72 20 63 6f 6e 74 61 69 6e 73 0a 20  LL or contains. 
20040 20 6e 6f 20 41 53 43 49 49 20 61 6c 70 68 61 62   no ASCII alphab
20050 65 74 69 63 20 63 68 61 72 61 63 74 65 72 73 2e  etic characters.
20060 0a 20 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  .  ^(This functi
20070 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
20080 6f 6d 20 53 51 4c 69 74 65 20 62 79 20 64 65 66  om SQLite by def
20090 61 75 6c 74 2e 0a 20 20 49 74 20 69 73 20 6f 6e  ault..  It is on
200a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
200b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 53 4f 55 4e  the [SQLITE_SOUN
200c0 44 45 58 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  DEX] compile-tim
200d0 65 20 6f 70 74 69 6f 6e 0a 20 20 69 73 20 75 73  e option.  is us
200e0 65 64 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ed when SQLite i
200f0 73 20 62 75 69 6c 74 2e 29 5e 0a 7d 0a 0a 66 75  s built.)^.}..fu
20100 6e 63 64 65 66 20 7b 73 71 6c 69 74 65 5f 63 6f  ncdef {sqlite_co
20110 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
20120 4e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20  N)} {} {.  ^The 
20130 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
20140 74 69 6f 6e 5f 67 65 74 28 29 20 53 51 4c 20 66  tion_get() SQL f
20150 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 77 72 61  unction is a wra
20160 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68 65 0a  pper around the.
20170 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69    [sqlite3_compi
20180 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
20190 43 2f 43 2b 2b 20 66 75 6e 63 74 69 6f 6e 2e 0a  C/C++ function..
201a0 20 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20    ^This routine 
201b0 72 65 74 75 72 6e 73 20 74 68 65 20 4e 2d 74 68  returns the N-th
201c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
201d0 74 69 6f 6e 20 75 73 65 64 20 74 6f 20 62 75 69  tion used to bui
201e0 6c 64 20 53 51 4c 69 74 65 0a 20 20 6f 72 20 4e  ld SQLite.  or N
201f0 55 4c 4c 20 69 66 20 4e 20 69 73 20 6f 75 74 20  ULL if N is out 
20200 6f 66 20 72 61 6e 67 65 2e 20 20 53 65 65 20 61  of range.  See a
20210 6c 73 6f 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  lso the [compile
20220 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
20230 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 73 71  ..}..funcdef {sq
20240 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
20250 6f 6e 5f 75 73 65 64 28 58 29 7d 20 7b 7d 20 7b  on_used(X)} {} {
20260 0a 20 20 5e 54 68 65 20 73 71 6c 69 74 65 5f 63  .  ^The sqlite_c
20270 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
20280 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
20290 20 69 73 20 61 20 77 72 61 70 70 65 72 20 61 72   is a wrapper ar
202a0 6f 75 6e 64 20 74 68 65 0a 20 20 5b 73 71 6c 69  ound the.  [sqli
202b0 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
202c0 6e 5f 75 73 65 64 28 29 5d 20 43 2f 43 2b 2b 20  n_used()] C/C++ 
202d0 66 75 6e 63 74 69 6f 6e 2e 0a 20 20 5e 57 68 65  function..  ^Whe
202e0 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 58  n the argument X
202f0 20 74 6f 20 73 71 6c 69 74 65 5f 63 6f 6d 70 69   to sqlite_compi
20300 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 58 29  leoption_used(X)
20310 20 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69   is a string whi
20320 63 68 0a 20 20 69 73 20 74 68 65 20 6e 61 6d 65  ch.  is the name
20330 20 6f 66 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69   of a compile-ti
20340 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 69 73 20  me option, this 
20350 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20360 74 72 75 65 20 28 31 29 20 6f 72 0a 20 20 66 61  true (1) or.  fa
20370 6c 73 65 20 28 30 29 20 64 65 70 65 6e 64 69 6e  lse (0) dependin
20380 67 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  g on whether or 
20390 6e 6f 74 20 74 68 61 74 20 6f 70 74 69 6f 6e 20  not that option 
203a0 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20  was used during 
203b0 74 68 65 0a 20 20 62 75 69 6c 64 2e 0a 7d 0a 0a  the.  build..}..
203c0 66 75 6e 63 64 65 66 20 7b 73 71 6c 69 74 65 5f  funcdef {sqlite_
203d0 6f 66 66 73 65 74 28 58 29 7d 20 7b 7d 20 7b 0a  offset(X)} {} {.
203e0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 5f 6f 66    ^The sqlite_of
203f0 66 73 65 74 28 58 29 20 66 75 6e 63 74 69 6f 6e  fset(X) function
20400 20 72 65 74 75 72 6e 73 20 74 68 65 20 62 79 74   returns the byt
20410 65 20 6f 66 66 73 65 74 20 69 6e 20 74 68 65 20  e offset in the 
20420 64 61 74 61 62 61 73 65 0a 20 20 66 69 6c 65 20  database.  file 
20430 66 6f 72 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  for the beginnin
20440 67 20 6f 66 20 74 68 65 20 72 65 63 6f 72 64 20  g of the record 
20450 66 72 6f 6d 20 77 68 69 63 68 20 76 61 6c 75 65  from which value
20460 20 77 6f 75 6c 64 20 62 65 20 72 65 61 64 2e 0a   would be read..
20470 20 20 49 66 20 58 20 69 73 20 6e 6f 74 20 61 20    If X is not a 
20480 63 6f 6c 75 6d 6e 20 69 6e 20 61 6e 20 6f 72 64  column in an ord
20490 69 6e 61 72 79 20 74 61 62 6c 65 2c 20 74 68 65  inary table, the
204a0 6e 20 73 71 6c 69 74 65 5f 6f 66 66 73 65 74 28  n sqlite_offset(
204b0 58 29 20 72 65 74 75 72 6e 73 0a 20 20 4e 55 4c  X) returns.  NUL
204c0 4c 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  L.  The value re
204d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
204e0 5f 6f 66 66 73 65 74 28 58 29 20 6d 69 67 68 74  _offset(X) might
204f0 20 72 65 66 65 72 65 6e 63 65 20 65 69 74 68 65   reference eithe
20500 72 20 74 68 65 0a 20 20 6f 72 69 67 69 6e 61 6c  r the.  original
20510 20 74 61 62 6c 65 20 6f 72 20 61 6e 20 69 6e 64   table or an ind
20520 65 78 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ex, depending on
20530 20 74 68 65 20 71 75 65 72 79 2e 20 20 49 66 20   the query.  If 
20540 74 68 65 20 76 61 6c 75 65 20 58 20 77 6f 75 6c  the value X woul
20550 64 0a 20 20 6e 6f 72 6d 61 6c 6c 79 20 62 65 20  d.  normally be 
20560 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 61  extracted from a
20570 6e 20 69 6e 64 65 78 2c 20 74 68 65 20 73 71 6c  n index, the sql
20580 69 74 65 5f 6f 66 66 73 65 74 28 58 29 20 72 65  ite_offset(X) re
20590 74 75 72 6e 73 20 74 68 65 0a 20 20 6f 66 66 73  turns the.  offs
205a0 65 74 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  et to the corres
205b0 70 6f 6e 64 69 6e 67 20 69 6e 64 65 78 20 72 65  ponding index re
205c0 63 6f 72 64 2e 20 20 49 66 20 74 68 65 20 76 61  cord.  If the va
205d0 6c 75 65 20 58 20 77 6f 75 6c 64 20 62 65 0a 20  lue X would be. 
205e0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
205f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 61 62  the original tab
20600 6c 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 5f  le, then sqlite_
20610 6f 66 66 73 65 74 28 58 29 20 72 65 74 75 72 6e  offset(X) return
20620 73 20 74 68 65 20 6f 66 66 73 65 74 0a 20 20 74  s the offset.  t
20630 6f 20 74 68 65 20 74 61 62 6c 65 20 72 65 63 6f  o the table reco
20640 72 64 2e 0a 0a 20 20 3c 70 3e 54 68 65 20 73 71  rd...  <p>The sq
20650 6c 69 74 65 5f 6f 66 66 73 65 74 28 58 29 20 53  lite_offset(X) S
20660 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6f  QL function is o
20670 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
20680 20 53 51 4c 69 74 65 20 69 73 20 62 75 69 6c 74   SQLite is built
20690 0a 20 20 75 73 69 6e 67 20 74 68 65 20 5b 2d 44  .  using the [-D
206a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4f 46  SQLITE_ENABLE_OF
206b0 46 53 45 54 5f 53 51 4c 5f 46 55 4e 43 5d 20 63  FSET_SQL_FUNC] c
206c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
206d0 6f 6e 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  on..}..funcdef {
206e0 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
206f0 28 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20  ()} {} {.  ^The 
20700 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
20710 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
20720 72 6e 73 20 61 20 73 74 72 69 6e 67 20 74 68 61  rns a string tha
20730 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
20740 0a 20 20 73 70 65 63 69 66 69 63 20 76 65 72 73  .  specific vers
20750 69 6f 6e 20 6f 66 20 74 68 65 20 73 6f 75 72 63  ion of the sourc
20760 65 20 63 6f 64 65 20 74 68 61 74 20 77 61 73 20  e code that was 
20770 75 73 65 64 20 74 6f 20 62 75 69 6c 64 20 74 68  used to build th
20780 65 20 53 51 4c 69 74 65 0a 20 20 6c 69 62 72 61  e SQLite.  libra
20790 72 79 2e 20 20 5e 54 68 65 20 73 74 72 69 6e 67  ry.  ^The string
207a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
207b0 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 20  ite_source_id() 
207c0 69 73 0a 20 20 74 68 65 20 64 61 74 65 20 61 6e  is.  the date an
207d0 64 20 74 69 6d 65 20 74 68 61 74 20 74 68 65 20  d time that the 
207e0 73 6f 75 72 63 65 20 63 6f 64 65 20 77 61 73 20  source code was 
207f0 63 68 65 63 6b 65 64 20 69 6e 20 66 6f 6c 6c 6f  checked in follo
20800 77 65 64 20 62 79 0a 20 20 74 68 65 20 53 48 41  wed by.  the SHA
20810 31 20 68 61 73 68 20 66 6f 72 20 74 68 61 74 20  1 hash for that 
20820 63 68 65 63 6b 2d 69 6e 2e 20 20 5e 54 68 69 73  check-in.  ^This
20830 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 20 20 61   function is.  a
20840 6e 20 53 51 4c 20 77 72 61 70 70 65 72 20 61 72  n SQL wrapper ar
20850 6f 75 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65  ound the [sqlite
20860 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 20 43 20  3_sourceid()] C 
20870 69 6e 74 65 72 66 61 63 65 2e 0a 7d 0a 0a 66 75  interface..}..fu
20880 6e 63 64 65 66 20 7b 73 71 6c 69 74 65 5f 76 65  ncdef {sqlite_ve
20890 72 73 69 6f 6e 28 29 7d 20 7b 7d 20 7b 0a 20 20  rsion()} {} {.  
208a0 5e 54 68 65 20 73 71 6c 69 74 65 5f 76 65 72 73  ^The sqlite_vers
208b0 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
208c0 65 74 75 72 6e 73 20 74 68 65 20 76 65 72 73 69  eturns the versi
208d0 6f 6e 20 73 74 72 69 6e 67 20 66 6f 72 20 74 68  on string for th
208e0 65 20 53 51 4c 69 74 65 0a 20 20 6c 69 62 72 61  e SQLite.  libra
208f0 72 79 20 74 68 61 74 20 69 73 20 72 75 6e 6e 69  ry that is runni
20900 6e 67 2e 20 20 5e 54 68 69 73 20 66 75 6e 63 74  ng.  ^This funct
20910 69 6f 6e 20 69 73 20 61 6e 20 53 51 4c 0a 20 20  ion is an SQL.  
20920 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74  wrapper around t
20930 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  he [sqlite3_libv
20940 65 72 73 69 6f 6e 28 29 5d 20 43 2d 69 6e 74 65  ersion()] C-inte
20950 72 66 61 63 65 2e 0a 7d 0a 0a 66 75 6e 63 64 65  rface..}..funcde
20960 66 20 7b 73 75 62 73 74 72 28 58 2c 59 2c 5a 29  f {substr(X,Y,Z)
20970 20 73 75 62 73 74 72 28 58 2c 59 29 7d 20 7b 7d   substr(X,Y)} {}
20980 20 7b 0a 20 20 5e 54 68 65 20 73 75 62 73 74 72   {.  ^The substr
20990 28 58 2c 59 2c 5a 29 20 66 75 6e 63 74 69 6f 6e  (X,Y,Z) function
209a0 20 72 65 74 75 72 6e 73 20 61 20 73 75 62 73 74   returns a subst
209b0 72 69 6e 67 20 6f 66 20 69 6e 70 75 74 20 73 74  ring of input st
209c0 72 69 6e 67 20 58 20 74 68 61 74 20 62 65 67 69  ring X that begi
209d0 6e 73 0a 20 20 77 69 74 68 20 74 68 65 20 59 2d  ns.  with the Y-
209e0 74 68 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  th character and
209f0 20 77 68 69 63 68 20 69 73 20 5a 20 63 68 61 72   which is Z char
20a00 61 63 74 65 72 73 20 6c 6f 6e 67 2e 0a 20 20 5e  acters long..  ^
20a10 49 66 20 5a 20 69 73 20 6f 6d 69 74 74 65 64 20  If Z is omitted 
20a20 74 68 65 6e 20 73 75 62 73 74 72 28 58 2c 59 29  then substr(X,Y)
20a30 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 63 68 61   returns all cha
20a40 72 61 63 74 65 72 73 20 74 68 72 6f 75 67 68 20  racters through 
20a50 74 68 65 20 65 6e 64 0a 20 20 6f 66 20 74 68 65  the end.  of the
20a60 20 73 74 72 69 6e 67 20 58 20 62 65 67 69 6e 6e   string X beginn
20a70 69 6e 67 20 77 69 74 68 20 74 68 65 20 59 2d 74  ing with the Y-t
20a80 68 2e 0a 20 20 5e 54 68 65 20 6c 65 66 74 2d 6d  h..  ^The left-m
20a90 6f 73 74 20 63 68 61 72 61 63 74 65 72 20 6f 66  ost character of
20aa0 20 58 20 69 73 20 6e 75 6d 62 65 72 20 31 2e 20   X is number 1. 
20ab0 20 5e 49 66 20 59 20 69 73 20 6e 65 67 61 74 69   ^If Y is negati
20ac0 76 65 0a 20 20 74 68 65 6e 20 74 68 65 20 66 69  ve.  then the fi
20ad0 72 73 74 20 63 68 61 72 61 63 74 65 72 20 6f 66  rst character of
20ae0 20 74 68 65 20 73 75 62 73 74 72 69 6e 67 20 69   the substring i
20af0 73 20 66 6f 75 6e 64 20 62 79 20 63 6f 75 6e 74  s found by count
20b00 69 6e 67 20 66 72 6f 6d 20 74 68 65 0a 20 20 72  ing from the.  r
20b10 69 67 68 74 20 72 61 74 68 65 72 20 74 68 61 6e  ight rather than
20b20 20 74 68 65 20 6c 65 66 74 2e 20 20 5e 49 66 20   the left.  ^If 
20b30 5a 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  Z is negative th
20b40 65 6e 0a 20 20 74 68 65 20 61 62 73 28 5a 29 20  en.  the abs(Z) 
20b50 63 68 61 72 61 63 74 65 72 73 20 70 72 65 63 65  characters prece
20b60 64 69 6e 67 20 74 68 65 20 59 2d 74 68 20 63 68  ding the Y-th ch
20b70 61 72 61 63 74 65 72 20 61 72 65 20 72 65 74 75  aracter are retu
20b80 72 6e 65 64 2e 0a 20 20 5e 49 66 20 58 20 69 73  rned..  ^If X is
20b90 20 61 20 73 74 72 69 6e 67 20 74 68 65 6e 20 63   a string then c
20ba0 68 61 72 61 63 74 65 72 73 20 69 6e 64 69 63 65  haracters indice
20bb0 73 20 72 65 66 65 72 20 74 6f 20 61 63 74 75 61  s refer to actua
20bc0 6c 20 55 54 46 2d 38 20 0a 20 20 63 68 61 72 61  l UTF-8 .  chara
20bd0 63 74 65 72 73 2e 20 20 5e 49 66 20 58 20 69 73  cters.  ^If X is
20be0 20 61 20 42 4c 4f 42 20 74 68 65 6e 20 74 68 65   a BLOB then the
20bf0 20 69 6e 64 69 63 65 73 20 72 65 66 65 72 20 74   indices refer t
20c00 6f 20 62 79 74 65 73 2e 0a 7d 0a 0a 66 75 6e 63  o bytes..}..func
20c10 64 65 66 20 7b 74 6f 74 61 6c 5f 63 68 61 6e 67  def {total_chang
20c20 65 73 28 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  es()} {} {.  ^Th
20c30 65 20 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  e total_changes(
20c40 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
20c50 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
20c60 20 72 6f 77 20 63 68 61 6e 67 65 73 0a 20 20 63   row changes.  c
20c70 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
20c80 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
20c90 45 0a 20 20 73 74 61 74 65 6d 65 6e 74 73 20 73  E.  statements s
20ca0 69 6e 63 65 20 74 68 65 20 63 75 72 72 65 6e 74  ince the current
20cb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20cc0 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2e  tion was opened.
20cd0 0a 20 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  .  ^This functio
20ce0 6e 20 69 73 20 61 20 77 72 61 70 70 65 72 20 61  n is a wrapper a
20cf0 72 6f 75 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  round the [sqlit
20d00 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
20d10 28 29 5d 0a 20 20 43 2f 43 2b 2b 20 69 6e 74 65  ()].  C/C++ inte
20d20 72 66 61 63 65 2e 0a 7d 0a 0a 66 75 6e 63 64 65  rface..}..funcde
20d30 66 20 7b 74 72 69 6d 28 58 29 20 74 72 69 6d 28  f {trim(X) trim(
20d40 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  X,Y)} {} {.  ^Th
20d50 65 20 74 72 69 6d 28 58 2c 59 29 20 66 75 6e 63  e trim(X,Y) func
20d60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73  tion returns a s
20d70 74 72 69 6e 67 20 66 6f 72 6d 65 64 20 62 79 20  tring formed by 
20d80 72 65 6d 6f 76 69 6e 67 20 61 6e 79 20 61 6e 64  removing any and
20d90 20 61 6c 6c 0a 20 20 63 68 61 72 61 63 74 65 72   all.  character
20da0 73 20 74 68 61 74 20 61 70 70 65 61 72 20 69 6e  s that appear in
20db0 20 59 20 66 72 6f 6d 20 62 6f 74 68 20 65 6e 64   Y from both end
20dc0 73 20 6f 66 20 58 2e 0a 20 20 5e 49 66 20 74 68  s of X..  ^If th
20dd0 65 20 59 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e Y argument is 
20de0 6f 6d 69 74 74 65 64 2c 20 74 72 69 6d 28 58 29  omitted, trim(X)
20df0 20 72 65 6d 6f 76 65 73 20 73 70 61 63 65 73 20   removes spaces 
20e00 66 72 6f 6d 20 62 6f 74 68 20 65 6e 64 73 20 6f  from both ends o
20e10 66 20 58 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  f X..}..funcdef 
20e20 7b 74 79 70 65 6f 66 28 58 29 7d 20 7b 7d 20 7b  {typeof(X)} {} {
20e30 0a 20 20 5e 54 68 65 20 74 79 70 65 6f 66 28 58  .  ^The typeof(X
20e40 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
20e50 6e 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  ns a string that
20e60 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 5b   indicates the [
20e70 64 61 74 61 74 79 70 65 5d 20 6f 66 0a 20 20 74  datatype] of.  t
20e80 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 58 3a  he expression X:
20e90 20 22 6e 75 6c 6c 22 2c 20 22 69 6e 74 65 67 65   "null", "intege
20ea0 72 22 2c 20 22 72 65 61 6c 22 2c 20 22 74 65 78  r", "real", "tex
20eb0 74 22 2c 20 6f 72 20 22 62 6c 6f 62 22 2e 0a 7d  t", or "blob"..}
20ec0 0a 0a 66 75 6e 63 64 65 66 20 7b 75 6e 6c 69 6b  ..funcdef {unlik
20ed0 65 6c 79 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e  ely(X)} {} {.  ^
20ee0 54 68 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20  The unlikely(X) 
20ef0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
20f00 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20   the argument X 
20f10 75 6e 63 68 61 6e 67 65 64 2e 0a 20 20 5e 54 68  unchanged..  ^Th
20f20 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 66 75  e unlikely(X) fu
20f30 6e 63 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  nction is a no-o
20f40 70 20 74 68 61 74 20 74 68 65 20 63 6f 64 65 20  p that the code 
20f50 67 65 6e 65 72 61 74 6f 72 0a 20 20 6f 70 74 69  generator.  opti
20f60 6d 69 7a 65 73 20 61 77 61 79 20 73 6f 20 74 68  mizes away so th
20f70 61 74 20 69 74 20 63 6f 6e 73 75 6d 65 73 20 6e  at it consumes n
20f80 6f 20 43 50 55 20 63 79 63 6c 65 73 20 61 74 0a  o CPU cycles at.
20f90 20 20 72 75 6e 2d 74 69 6d 65 20 28 74 68 61 74    run-time (that
20fa0 20 69 73 2c 20 64 75 72 69 6e 67 20 63 61 6c 6c   is, during call
20fb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  s to [sqlite3_st
20fc0 65 70 28 29 5d 29 2e 0a 20 20 5e 54 68 65 20 70  ep()])..  ^The p
20fd0 75 72 70 6f 73 65 20 6f 66 20 74 68 65 20 75 6e  urpose of the un
20fe0 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e 63 74 69  likely(X) functi
20ff0 6f 6e 20 69 73 20 74 6f 20 70 72 6f 76 69 64 65  on is to provide
21000 20 61 20 68 69 6e 74 0a 20 20 74 6f 20 74 68 65   a hint.  to the
21010 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 74   query planner t
21020 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74  hat the argument
21030 20 58 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20   X is a boolean 
21040 76 61 6c 75 65 0a 20 20 74 68 61 74 20 69 73 20  value.  that is 
21050 75 73 75 61 6c 6c 79 20 6e 6f 74 20 74 72 75 65  usually not true
21060 2e 20 5e 28 54 68 65 20 75 6e 6c 69 6b 65 6c 79  . ^(The unlikely
21070 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  (X) function is 
21080 65 71 75 69 76 61 6c 65 6e 74 0a 20 20 74 6f 20  equivalent.  to 
21090 5b 6c 69 6b 65 6c 69 68 6f 6f 64 5d 28 58 2c 20  [likelihood](X, 
210a0 30 2e 30 36 32 35 29 2e 29 5e 0a 7d 0a 0a 66 75  0.0625).)^.}..fu
210b0 6e 63 64 65 66 20 7b 75 6e 69 63 6f 64 65 28 58  ncdef {unicode(X
210c0 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 75  )} {} {.  ^The u
210d0 6e 69 63 6f 64 65 28 58 29 20 66 75 6e 63 74 69  nicode(X) functi
210e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
210f0 75 6d 65 72 69 63 20 75 6e 69 63 6f 64 65 20 63  umeric unicode c
21100 6f 64 65 20 70 6f 69 6e 74 20 63 6f 72 72 65 73  ode point corres
21110 70 6f 6e 64 69 6e 67 20 74 6f 0a 20 20 74 68 65  ponding to.  the
21120 20 66 69 72 73 74 20 63 68 61 72 61 63 74 65 72   first character
21130 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 58   of the string X
21140 2e 20 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  .  If the argume
21150 6e 74 20 74 6f 20 75 6e 69 63 6f 64 65 28 58 29  nt to unicode(X)
21160 20 69 73 20 6e 6f 74 20 61 20 73 74 72 69 6e 67   is not a string
21170 0a 20 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  .  then the resu
21180 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
21190 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 75 70 70  .}..funcdef {upp
211a0 65 72 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  er(X)} {} {.  ^T
211b0 68 65 20 75 70 70 65 72 28 58 29 20 66 75 6e 63  he upper(X) func
211c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63  tion returns a c
211d0 6f 70 79 20 6f 66 20 69 6e 70 75 74 20 73 74 72  opy of input str
211e0 69 6e 67 20 58 20 69 6e 20 77 68 69 63 68 20 61  ing X in which a
211f0 6c 6c 20 0a 20 20 6c 6f 77 65 72 2d 63 61 73 65  ll .  lower-case
21200 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
21210 73 20 61 72 65 20 63 6f 6e 76 65 72 74 65 64 20  s are converted 
21220 74 6f 20 74 68 65 69 72 20 75 70 70 65 72 2d 63  to their upper-c
21230 61 73 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a  ase equivalent..
21240 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 7a 65 72 6f  }..funcdef {zero
21250 62 6c 6f 62 28 4e 29 7d 20 7b 7d 20 7b 0a 20 20  blob(N)} {} {.  
21260 5e 54 68 65 20 7a 65 72 6f 62 6c 6f 62 28 4e 29  ^The zeroblob(N)
21270 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
21280 73 20 61 20 42 4c 4f 42 20 63 6f 6e 73 69 73 74  s a BLOB consist
21290 69 6e 67 20 6f 66 20 4e 20 62 79 74 65 73 20 6f  ing of N bytes o
212a0 66 20 30 78 30 30 2e 0a 20 20 53 51 4c 69 74 65  f 0x00..  SQLite
212b0 20 6d 61 6e 61 67 65 73 20 74 68 65 73 65 20 7a   manages these z
212c0 65 72 6f 62 6c 6f 62 73 20 76 65 72 79 20 65 66  eroblobs very ef
212d0 66 69 63 69 65 6e 74 6c 79 2e 20 20 5a 65 72 6f  ficiently.  Zero
212e0 62 6c 6f 62 73 20 63 61 6e 20 62 65 20 75 73 65  blobs can be use
212f0 64 20 74 6f 0a 20 20 72 65 73 65 72 76 65 20 73  d to.  reserve s
21300 70 61 63 65 20 66 6f 72 20 61 20 42 4c 4f 42 20  pace for a BLOB 
21310 74 68 61 74 20 69 73 20 6c 61 74 65 72 20 77 72  that is later wr
21320 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 20 20 5b  itten using .  [
21330 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
21340 6e 28 29 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  n() | incrementa
21350 6c 20 42 4c 4f 42 20 49 2f 4f 5d 2e 0a 20 20 5e  l BLOB I/O]..  ^
21360 54 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  This SQL functio
21370 6e 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  n is implemented
21380 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
21390 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
213a0 6c 6f 62 28 29 5d 0a 20 20 72 6f 75 74 69 6e 65  lob()].  routine
213b0 20 66 72 6f 6d 20 74 68 65 20 43 2f 43 2b 2b 20   from the C/C++ 
213c0 69 6e 74 65 72 66 61 63 65 2e 0a 7d 0a 3c 2f 74  interface..}.</t
213d0 63 6c 3e 0a 0a 3c 70 3e 54 68 65 20 63 6f 72 65  cl>..<p>The core
213e0 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 6f 77 6e   functions shown
213f0 20 62 65 6c 6f 77 20 61 72 65 20 61 76 61 69 6c   below are avail
21400 61 62 6c 65 20 62 79 20 64 65 66 61 75 6c 74 2e  able by default.
21410 20 0a 5b 64 61 74 65 66 75 6e 63 20 7c 20 44 61   .[datefunc | Da
21420 74 65 20 26 61 6d 70 3b 20 54 69 6d 65 20 66 75  te &amp; Time fu
21430 6e 63 74 69 6f 6e 73 5d 2c 0a 5b 61 67 67 66 75  nctions],.[aggfu
21440 6e 63 20 7c 20 61 67 67 72 65 67 61 74 65 20 66  nc | aggregate f
21450 75 6e 63 74 69 6f 6e 73 5d 2c 0a 5b 62 75 69 6c  unctions],.[buil
21460 74 69 6e 20 77 69 6e 64 6f 77 20 66 75 6e 63 74  tin window funct
21470 69 6f 6e 73 7c 77 69 6e 64 6f 77 20 66 75 6e 63  ions|window func
21480 74 69 6f 6e 73 5d 2c 20 61 6e 64 0a 5b 6a 73 6f  tions], and.[jso
21490 6e 31 20 7c 20 4a 53 4f 4e 20 66 75 6e 63 74 69  n1 | JSON functi
214a0 6f 6e 73 5d 20 61 72 65 20 64 6f 63 75 6d 65 6e  ons] are documen
214b0 74 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ted separately. 
214c0 20 41 6e 0a 61 70 70 6c 69 63 61 74 69 6f 6e 20   An.application 
214d0 6d 61 79 20 64 65 66 69 6e 65 20 61 64 64 69 74  may define addit
214e0 69 6f 6e 61 6c 0a 66 75 6e 63 74 69 6f 6e 73 20  ional.functions 
214f0 77 72 69 74 74 65 6e 20 69 6e 20 43 20 61 6e 64  written in C and
21500 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 64 61   added to the da
21510 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73  tabase engine us
21520 69 6e 67 0a 74 68 65 20 5b 73 71 6c 69 74 65 33  ing.the [sqlite3
21530 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
21540 28 29 5d 20 41 50 49 2e 3c 2f 70 3e 0a 0a 3c 74  ()] API.</p>..<t
21550 63 6c 3e 0a 73 65 74 20 6c 78 20 7b 7d 0a 66 6f  cl>.set lx {}.fo
21560 72 65 61 63 68 20 62 61 73 65 73 79 6e 74 61 78  reach basesyntax
21570 20 5b 61 72 72 61 79 20 6e 61 6d 65 73 20 63 6f   [array names co
21580 72 65 66 75 6e 63 73 65 74 5d 20 7b 0a 20 20 66  refuncset] {.  f
21590 6f 72 65 61 63 68 20 7b 73 79 6e 74 61 78 20 6b  oreach {syntax k
215a0 65 79 77 6f 72 64 73 20 64 65 73 63 7d 20 24 63  eywords desc} $c
215b0 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61 73 65  orefuncset($base
215c0 73 79 6e 74 61 78 29 20 62 72 65 61 6b 0a 20 20  syntax) break.  
215d0 72 65 67 65 78 70 20 7b 5e 5b 61 2d 7a 5f 5d 2b  regexp {^[a-z_]+
215e0 7d 20 24 62 61 73 65 73 79 6e 74 61 78 20 66 72  } $basesyntax fr
215f0 61 67 6d 65 6e 74 0a 20 20 66 6f 72 65 61 63 68  agment.  foreach
21600 20 63 6f 72 65 73 79 6e 74 61 78 20 24 73 79 6e   coresyntax $syn
21610 74 61 78 20 7b 0a 20 20 20 20 6c 61 70 70 65 6e  tax {.    lappen
21620 64 20 6c 78 20 5b 6c 69 73 74 20 24 66 72 61 67  d lx [list $frag
21630 6d 65 6e 74 20 24 63 6f 72 65 73 79 6e 74 61 78  ment $coresyntax
21640 20 30 5d 0a 20 20 7d 0a 7d 0a 68 64 5f 6c 69 73   0].  }.}.hd_lis
21650 74 5f 6f 66 5f 6c 69 6e 6b 73 20 7b 7d 20 32 32  t_of_links {} 22
21660 35 20 5b 6c 73 6f 72 74 20 2d 69 6e 64 65 78 20  5 [lsort -index 
21670 31 20 24 6c 78 5d 0a 0a 68 64 5f 70 75 74 73 6e  1 $lx]..hd_putsn
21680 6c 20 22 3c 68 72 20 63 6c 61 73 73 3d 27 78 68  l "<hr class='xh
21690 72 27 3e 22 0a 68 64 5f 70 75 74 73 6e 6c 20 22  r'>".hd_putsnl "
216a0 3c 64 6c 3e 22 0a 66 6f 72 65 61 63 68 20 62 61  <dl>".foreach ba
216b0 73 65 73 79 6e 74 61 78 20 5b 6c 73 6f 72 74 20  sesyntax [lsort 
216c0 5b 61 72 72 61 79 20 6e 61 6d 65 73 20 63 6f 72  [array names cor
216d0 65 66 75 6e 63 73 65 74 5d 5d 20 7b 0a 20 20 66  efuncset]] {.  f
216e0 6f 72 65 61 63 68 20 7b 73 79 6e 74 61 78 20 6b  oreach {syntax k
216f0 65 79 77 6f 72 64 73 20 64 65 73 63 7d 20 24 63  eywords desc} $c
21700 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61 73 65  orefuncset($base
21710 73 79 6e 74 61 78 29 20 62 72 65 61 6b 0a 20 20  syntax) break.  
21720 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5c 73 2b  regsub -all {\s+
21730 7d 20 5b 73 74 72 69 6e 67 20 74 72 69 6d 20 24  } [string trim $
21740 73 79 6e 74 61 78 5d 20 7b 3c 62 72 20 2f 3e 7d  syntax] {<br />}
21750 20 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75 62   syntax.  regsub
21760 20 2d 61 6c 6c 20 7b 5c 28 28 5b 5e 2a 29 5d 2b   -all {\(([^*)]+
21770 29 5c 29 7d 20 24 73 79 6e 74 61 78 20 7b 28 3c  )\)} $syntax {(<
21780 69 3e 5c 31 3c 2f 69 3e 29 7d 20 73 79 6e 74 61  i>\1</i>)} synta
21790 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c 6c 20  x.  regsub -all 
217a0 7b 2c 7d 20 24 73 79 6e 74 61 78 20 7b 3c 2f 69  {,} $syntax {</i
217b0 3e 2c 3c 69 3e 7d 20 73 79 6e 74 61 78 0a 20 20  >,<i>} syntax.  
217c0 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 3c 69 3e  regsub -all {<i>
217d0 5c 2e 5c 2e 5c 2e 3c 2f 69 3e 7d 20 24 73 79 6e  \.\.\.</i>} $syn
217e0 74 61 78 20 7b 2e 2e 2e 7d 20 73 79 6e 74 61 78  tax {...} syntax
217f0 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b 61 2d 7a  .  regexp {^[a-z
21800 5d 2b 7d 20 24 62 61 73 65 73 79 6e 74 61 78 20  ]+} $basesyntax 
21810 66 72 61 67 6d 65 6e 74 0a 20 20 69 66 20 7b 5b  fragment.  if {[
21820 6c 6c 65 6e 67 74 68 20 24 6b 65 79 77 6f 72 64  llength $keyword
21830 73 5d 3d 3d 30 7d 20 7b 0a 20 20 20 20 72 65 67  s]==0} {.    reg
21840 65 78 70 20 7b 5b 61 2d 7a 5f 5d 2b 7d 20 24 73  exp {[a-z_]+} $s
21850 79 6e 74 61 78 20 6e 61 6d 65 0a 20 20 20 20 68  yntax name.    h
21860 64 5f 66 72 61 67 6d 65 6e 74 20 24 6e 61 6d 65  d_fragment $name
21870 20 2a 24 6e 61 6d 65 20 22 24 7b 6e 61 6d 65 7d   *$name "${name}
21880 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 22  () SQL function"
21890 0a 20 20 7d 20 65 6c 73 65 20 7b 0a 20 20 20 20  .  } else {.    
218a0 73 65 74 20 66 72 61 67 6e 61 6d 65 20 5b 6c 69  set fragname [li
218b0 6e 64 65 78 20 24 6b 65 79 77 6f 72 64 73 20 30  ndex $keywords 0
218c0 5d 0a 20 20 20 20 72 65 67 73 75 62 20 2d 61 6c  ].    regsub -al
218d0 6c 20 7b 5b 5e 61 2d 7a 5d 7d 20 24 66 72 61 67  l {[^a-z]} $frag
218e0 6e 61 6d 65 20 7b 7d 20 66 72 61 67 6e 61 6d 65  name {} fragname
218f0 0a 20 20 20 20 68 64 5f 66 72 61 67 6d 65 6e 74  .    hd_fragment
21900 20 24 66 72 61 67 6e 61 6d 65 0a 20 20 20 20 65   $fragname.    e
21910 76 61 6c 20 68 64 5f 6b 65 79 77 6f 72 64 73 20  val hd_keywords 
21920 5b 73 74 72 69 6e 67 20 6d 61 70 20 7b 5c 6e 20  [string map {\n 
21930 7b 20 7d 7d 20 24 6b 65 79 77 6f 72 64 73 5d 0a  { }} $keywords].
21940 20 20 7d 0a 20 20 68 64 5f 70 75 74 73 20 22 3c    }.  hd_puts "<
21950 64 74 3e 3c 70 3e 3c 62 3e 24 73 79 6e 74 61 78  dt><p><b>$syntax
21960 3c 2f 62 3e 3c 2f 64 74 3e 22 0a 20 20 68 64 5f  </b></dt>".  hd_
21970 72 65 73 6f 6c 76 65 20 22 3c 64 64 3e 3c 70 3e  resolve "<dd><p>
21980 24 64 65 73 63 3c 2f 64 64 3e 5c 6e 22 0a 7d 0a  $desc</dd>\n".}.
21990 68 64 5f 70 75 74 73 6e 6c 20 22 3c 2f 64 6c 3e  hd_putsnl "</dl>
219a0 22 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  "..#############
219b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
219c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
219d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
219e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
219f0 23 0a 53 65 63 74 69 6f 6e 20 7b 44 61 74 65 20  #.Section {Date 
21a00 41 6e 64 20 54 69 6d 65 20 46 75 6e 63 74 69 6f  And Time Functio
21a10 6e 73 7d 20 64 61 74 65 66 75 6e 63 20 7b 2a 64  ns} datefunc {*d
21a20 61 74 65 66 75 6e 63 20 7b 64 61 74 65 20 61 6e  atefunc {date an
21a30 64 20 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73  d time functions
21a40 7d 7d 0a 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b  }}.hd_keywords {
21a50 64 61 74 65 28 29 20 53 51 4c 20 66 75 6e 63 74  date() SQL funct
21a60 69 6f 6e 7d 20 7b 74 69 6d 65 28 29 20 53 51 4c  ion} {time() SQL
21a70 20 66 75 6e 63 74 69 6f 6e 7d 0a 68 64 5f 6b 65   function}.hd_ke
21a80 79 77 6f 72 64 73 20 7b 64 61 74 65 74 69 6d 65  ywords {datetime
21a90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  () SQL function}
21aa0 20 7b 6a 75 6c 69 61 6e 64 61 79 28 29 20 53 51   {julianday() SQ
21ab0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 68 64 5f 6b  L function}.hd_k
21ac0 65 79 77 6f 72 64 73 20 7b 73 74 72 66 74 69 6d  eywords {strftim
21ad0 65 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  e() SQL function
21ae0 7d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 53 51  }.</tcl>..<p>.SQ
21af0 4c 69 74 65 20 73 75 70 70 6f 72 74 73 20 66 69  Lite supports fi
21b00 76 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ve date and time
21b10 20 66 75 6e 63 74 69 6f 6e 73 20 61 73 20 66 6f   functions as fo
21b20 6c 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a 0a 3c 70 3e  llows:.</p>..<p>
21b30 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 5e 28 3c 62 3e  .<ol>.<li> ^(<b>
21b40 64 61 74 65 28 3c 2f 62 3e 3c 69 3e 74 69 6d 65  date(</b><i>time
21b50 73 74 72 69 6e 67 2c 20 6d 6f 64 69 66 69 65 72  string, modifier
21b60 2c 20 6d 6f 64 69 66 69 65 72 2c 20 2e 2e 2e 3c  , modifier, ...<
21b70 2f 69 3e 3c 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f  /i><b>)</b>)^ </
21b80 6c 69 3e 0a 3c 6c 69 3e 20 5e 28 3c 62 3e 74 69  li>.<li> ^(<b>ti
21b90 6d 65 28 3c 2f 62 3e 3c 69 3e 74 69 6d 65 73 74  me(</b><i>timest
21ba0 72 69 6e 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20  ring, modifier, 
21bb0 6d 6f 64 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69  modifier, ...</i
21bc0 3e 3c 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69  ><b>)</b>)^ </li
21bd0 3e 0a 3c 6c 69 3e 20 5e 28 3c 62 3e 64 61 74 65  >.<li> ^(<b>date
21be0 74 69 6d 65 28 3c 2f 62 3e 3c 69 3e 74 69 6d 65  time(</b><i>time
21bf0 73 74 72 69 6e 67 2c 20 6d 6f 64 69 66 69 65 72  string, modifier
21c00 2c 20 6d 6f 64 69 66 69 65 72 2c 20 2e 2e 2e 3c  , modifier, ...<
21c10 2f 69 3e 3c 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f  /i><b>)</b>)^ </
21c20 6c 69 3e 0a 3c 6c 69 3e 20 5e 28 3c 62 3e 6a 75  li>.<li> ^(<b>ju
21c30 6c 69 61 6e 64 61 79 28 3c 2f 62 3e 3c 69 3e 74  lianday(</b><i>t
21c40 69 6d 65 73 74 72 69 6e 67 2c 20 6d 6f 64 69 66  imestring, modif
21c50 69 65 72 2c 20 6d 6f 64 69 66 69 65 72 2c 20 2e  ier, modifier, .
21c60 2e 2e 3c 2f 69 3e 3c 62 3e 29 3c 2f 62 3e 29 5e  ..</i><b>)</b>)^
21c70 20 3c 2f 6c 69 3e 0a 3c 6c 69 3e 20 5e 28 3c 62   </li>.<li> ^(<b
21c80 3e 73 74 72 66 74 69 6d 65 28 3c 2f 62 3e 3c 69  >strftime(</b><i
21c90 3e 66 6f 72 6d 61 74 2c 20 74 69 6d 65 73 74 72  >format, timestr
21ca0 69 6e 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20 6d  ing, modifier, m
21cb0 6f 64 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e  odifier, ...</i>
21cc0 3c 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e  <b>)</b>)^ </li>
21cd0 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 5e 41 6c 6c  .</ol>..<p>.^All
21ce0 20 66 69 76 65 20 64 61 74 65 20 61 6e 64 20 74   five date and t
21cf0 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 61  ime functions ta
21d00 6b 65 20 61 20 74 69 6d 65 20 73 74 72 69 6e 67  ke a time string
21d10 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e   as an argument.
21d20 20 0a 5e 54 68 65 20 74 69 6d 65 20 73 74 72 69   .^The time stri
21d30 6e 67 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 62  ng is followed b
21d40 79 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 6d  y zero or more m
21d50 6f 64 69 66 69 65 72 73 2e 20 0a 5e 54 68 65 20  odifiers. .^The 
21d60 73 74 72 66 74 69 6d 65 28 29 20 66 75 6e 63 74  strftime() funct
21d70 69 6f 6e 20 61 6c 73 6f 20 74 61 6b 65 73 20 61  ion also takes a
21d80 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 61   format string a
21d90 73 20 69 74 73 20 66 69 72 73 74 20 61 72 67 75  s its first argu
21da0 6d 65 6e 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  ment..</p>..<p>.
21db0 54 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d  The date and tim
21dc0 65 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  e functions use 
21dd0 61 20 73 75 62 73 65 74 20 6f 66 0a 5b 68 74 74  a subset of.[htt
21de0 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61  p://en.wikipedia
21df0 2e 6f 72 67 2f 77 69 6b 69 2f 49 53 4f 5f 38 36  .org/wiki/ISO_86
21e00 30 31 20 7c 20 49 53 30 2d 38 36 30 31 5d 20 64  01 | IS0-8601] d
21e10 61 74 65 20 61 6e 64 20 74 69 6d 65 0a 66 6f 72  ate and time.for
21e20 6d 61 74 73 2e 0a 5e 54 68 65 20 64 61 74 65 28  mats..^The date(
21e30 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
21e40 6e 73 20 74 68 65 20 64 61 74 65 20 69 6e 20 74  ns the date in t
21e50 68 69 73 20 66 6f 72 6d 61 74 3a 20 59 59 59 59  his format: YYYY
21e60 2d 4d 4d 2d 44 44 2e 20 0a 5e 54 68 65 20 74 69  -MM-DD. .^The ti
21e70 6d 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  me() function re
21e80 74 75 72 6e 73 20 74 68 65 20 74 69 6d 65 20 61  turns the time a
21e90 73 20 48 48 3a 4d 4d 3a 53 53 2e 20 0a 5e 54 68  s HH:MM:SS. .^Th
21ea0 65 20 64 61 74 65 74 69 6d 65 28 29 20 66 75 6e  e datetime() fun
21eb0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 22 59  ction returns "Y
21ec0 59 59 59 2d 4d 4d 2d 44 44 20 48 48 3a 4d 4d 3a  YYY-MM-DD HH:MM:
21ed0 53 53 22 2e 20 0a 5e 28 54 68 65 20 6a 75 6c 69  SS". .^(The juli
21ee0 61 6e 64 61 79 28 29 20 66 75 6e 63 74 69 6f 6e  anday() function
21ef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 5b 68   returns the .[h
21f00 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
21f10 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4a 75 6c 69  ia.org/wiki/Juli
21f20 61 6e 5f 64 61 79 20 7c 20 4a 75 6c 69 61 6e 20  an_day | Julian 
21f30 64 61 79 5d 20 2d 20 74 68 65 0a 6e 75 6d 62 65  day] - the.numbe
21f40 72 20 6f 66 20 64 61 79 73 20 73 69 6e 63 65 20  r of days since 
21f50 6e 6f 6f 6e 20 69 6e 20 47 72 65 65 6e 77 69 63  noon in Greenwic
21f60 68 20 6f 6e 20 4e 6f 76 65 6d 62 65 72 20 32 34  h on November 24
21f70 2c 20 34 37 31 34 20 42 2e 43 2e 20 0a 28 5b 68  , 4714 B.C. .([h
21f80 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
21f90 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 50 72 6f 6c  ia.org/wiki/Prol
21fa0 65 70 74 69 63 5f 47 72 65 67 6f 72 69 61 6e 5f  eptic_Gregorian_
21fb0 63 61 6c 65 6e 64 61 72 20 7c 20 50 72 6f 6c 65  calendar | Prole
21fc0 70 74 69 63 20 47 72 65 67 6f 72 69 61 6e 20 63  ptic Gregorian c
21fd0 61 6c 65 6e 64 61 72 5d 29 2e 29 5e 0a 5e 54 68  alendar]).)^.^Th
21fe0 65 20 73 74 72 66 74 69 6d 65 28 29 20 72 6f 75  e strftime() rou
21ff0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
22000 20 64 61 74 65 20 66 6f 72 6d 61 74 74 65 64 20   date formatted 
22010 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 0a 74 68  according to .th
22020 65 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  e format string 
22030 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
22040 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
22050 0a 5e 54 68 65 20 66 6f 72 6d 61 74 20 73 74 72  .^The format str
22060 69 6e 67 20 73 75 70 70 6f 72 74 73 20 74 68 65  ing supports the
22070 20 6d 6f 73 74 20 63 6f 6d 6d 6f 6e 20 73 75 62   most common sub
22080 73 74 69 74 75 74 69 6f 6e 73 20 66 6f 75 6e 64  stitutions found
22090 20 69 6e 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f   in the .[http:/
220a0 2f 6f 70 65 6e 67 72 6f 75 70 2e 6f 72 67 2f 6f  /opengroup.org/o
220b0 6e 6c 69 6e 65 70 75 62 73 2f 30 30 37 39 30 38  nlinepubs/007908
220c0 37 39 39 2f 78 73 68 2f 73 74 72 66 74 69 6d 65  799/xsh/strftime
220d0 2e 68 74 6d 6c 20 7c 20 73 74 72 66 74 69 6d 65  .html | strftime
220e0 28 29 20 66 75 6e 63 74 69 6f 6e 5d 0a 66 72 6f  () function].fro
220f0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
22100 20 6c 69 62 72 61 72 79 20 70 6c 75 73 20 74 77   library plus tw
22110 6f 20 6e 65 77 20 73 75 62 73 74 69 74 75 74 69  o new substituti
22120 6f 6e 73 2c 20 25 66 20 61 6e 64 20 25 4a 2e 0a  ons, %f and %J..
22130 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
22140 69 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 6c 69  is a complete li
22150 73 74 20 6f 66 20 76 61 6c 69 64 20 73 74 72 66  st of valid strf
22160 74 69 6d 65 28 29 20 73 75 62 73 74 69 74 75 74  time() substitut
22170 69 6f 6e 73 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  ions:.</p>..<blo
22180 63 6b 71 75 6f 74 65 3e 0a 3c 74 61 62 6c 65 20  ckquote>.<table 
22190 62 6f 72 64 65 72 3d 22 30 22 20 63 65 6c 6c 70  border="0" cellp
221a0 61 64 64 69 6e 67 3d 22 30 22 20 63 65 6c 6c 73  adding="0" cells
221b0 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c 74 72 3e  pacing="0">.<tr>
221c0 3c 74 64 3e 3c 74 64 20 77 69 64 74 68 3d 22 31  <td><td width="1
221d0 30 22 3e 3c 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74  0"><td></tr>..<t
221e0 72 3e 3c 74 64 3e 20 25 64 20 3c 74 64 3e 3c 74  r><td> %d <td><t
221f0 64 3e 20 64 61 79 20 6f 66 20 6d 6f 6e 74 68 3a  d> day of month:
22200 20 30 30 0a 3c 74 72 3e 3c 74 64 3e 20 25 66 20   00.<tr><td> %f 
22210 3c 74 64 3e 3c 74 64 3e 20 66 72 61 63 74 69 6f  <td><td> fractio
22220 6e 61 6c 20 73 65 63 6f 6e 64 73 3a 20 53 53 2e  nal seconds: SS.
22230 53 53 53 0a 3c 74 72 3e 3c 74 64 3e 20 25 48 20  SSS.<tr><td> %H 
22240 3c 74 64 3e 3c 74 64 3e 20 68 6f 75 72 3a 20 30  <td><td> hour: 0
22250 30 2d 32 34 20 0a 3c 74 72 3e 3c 74 64 3e 20 25  0-24 .<tr><td> %
22260 6a 20 3c 74 64 3e 3c 74 64 3e 20 64 61 79 20 6f  j <td><td> day o
22270 66 20 79 65 61 72 3a 20 30 30 31 2d 33 36 36 0a  f year: 001-366.
22280 3c 74 72 3e 3c 74 64 3e 20 25 4a 20 3c 74 64 3e  <tr><td> %J <td>
22290 3c 74 64 3e 20 4a 75 6c 69 61 6e 20 64 61 79 20  <td> Julian day 
222a0 6e 75 6d 62 65 72 0a 3c 74 72 3e 3c 74 64 3e 20  number.<tr><td> 
222b0 25 6d 20 3c 74 64 3e 3c 74 64 3e 20 6d 6f 6e 74  %m <td><td> mont
222c0 68 3a 20 30 31 2d 31 32 0a 3c 74 72 3e 3c 74 64  h: 01-12.<tr><td
222d0 3e 20 25 4d 20 3c 74 64 3e 3c 74 64 3e 20 6d 69  > %M <td><td> mi
222e0 6e 75 74 65 3a 20 30 30 2d 35 39 0a 3c 74 72 3e  nute: 00-59.<tr>
222f0 3c 74 64 3e 20 25 73 20 3c 74 64 3e 3c 74 64 3e  <td> %s <td><td>
22300 20 73 65 63 6f 6e 64 73 20 73 69 6e 63 65 20 31   seconds since 1
22310 39 37 30 2d 30 31 2d 30 31 0a 3c 74 72 3e 3c 74  970-01-01.<tr><t
22320 64 3e 20 25 53 20 3c 74 64 3e 3c 74 64 3e 20 73  d> %S <td><td> s
22330 65 63 6f 6e 64 73 3a 20 30 30 2d 35 39 0a 3c 74  econds: 00-59.<t
22340 72 3e 3c 74 64 3e 20 25 77 20 3c 74 64 3e 3c 74  r><td> %w <td><t
22350 64 3e 20 64 61 79 20 6f 66 20 77 65 65 6b 20 30  d> day of week 0
22360 2d 36 20 77 69 74 68 20 53 75 6e 64 61 79 3d 3d  -6 with Sunday==
22370 30 0a 3c 74 72 3e 3c 74 64 3e 20 25 57 20 3c 74  0.<tr><td> %W <t
22380 64 3e 3c 74 64 3e 20 77 65 65 6b 20 6f 66 20 79  d><td> week of y
22390 65 61 72 3a 20 30 30 2d 35 33 0a 3c 74 72 3e 3c  ear: 00-53.<tr><
223a0 74 64 3e 20 25 59 20 3c 74 64 3e 3c 74 64 3e 20  td> %Y <td><td> 
223b0 79 65 61 72 3a 20 30 30 30 30 2d 39 39 39 39 0a  year: 0000-9999.
223c0 3c 74 72 3e 3c 74 64 3e 20 25 25 20 3c 74 64 3e  <tr><td> %% <td>
223d0 3c 74 64 3e 20 25 0a 3c 2f 74 61 62 6c 65 3e 0a  <td> %.</table>.
223e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
223f0 0a 3c 70 3e 0a 5e 28 4e 6f 74 69 63 65 20 74 68  .<p>.^(Notice th
22400 61 74 20 61 6c 6c 20 6f 74 68 65 72 20 64 61 74  at all other dat
22410 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63 74  e and time funct
22420 69 6f 6e 73 20 63 61 6e 20 62 65 20 65 78 70 72  ions can be expr
22430 65 73 73 65 64 0a 69 6e 20 74 65 72 6d 73 20 6f  essed.in terms o
22440 66 20 73 74 72 66 74 69 6d 65 28 29 3a 0a 3c 2f  f strftime():.</
22450 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
22460 0a 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22  .<table border="
22470 30 22 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 22  0" cellpadding="
22480 30 22 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 22  0" cellspacing="
22490 30 22 3e 0a 3c 74 72 3e 3c 74 64 3e 3c 62 3e 46  0">.<tr><td><b>F
224a0 75 6e 63 74 69 6f 6e 3c 2f 62 3e 3c 74 64 20 77  unction</b><td w
224b0 69 64 74 68 3d 22 33 30 22 3e 3c 74 64 3e 3c 62  idth="30"><td><b
224c0 3e 45 71 75 69 76 61 6c 65 6e 74 20 73 74 72 66  >Equivalent strf
224d0 74 69 6d 65 28 29 3c 2f 62 3e 0a 3c 74 72 3e 3c  time()</b>.<tr><
224e0 74 64 3e 20 20 20 64 61 74 65 28 2e 2e 2e 29 20  td>   date(...) 
224f0 20 20 20 20 20 3c 74 64 3e 3c 74 64 3e 20 20 73       <td><td>  s
22500 74 72 66 74 69 6d 65 28 27 25 59 2d 25 6d 2d 25  trftime('%Y-%m-%
22510 64 27 2c 20 2e 2e 2e 29 0a 3c 74 72 3e 3c 74 64  d', ...).<tr><td
22520 3e 20 20 20 74 69 6d 65 28 2e 2e 2e 29 20 20 20  >   time(...)   
22530 20 20 20 3c 74 64 3e 3c 74 64 3e 20 20 73 74 72     <td><td>  str
22540 66 74 69 6d 65 28 27 25 48 3a 25 4d 3a 25 53 27  ftime('%H:%M:%S'
22550 2c 20 2e 2e 2e 29 0a 3c 74 72 3e 3c 74 64 3e 20  , ...).<tr><td> 
22560 20 20 64 61 74 65 74 69 6d 65 28 2e 2e 2e 29 20    datetime(...) 
22570 20 3c 74 64 3e 3c 74 64 3e 20 20 73 74 72 66 74   <td><td>  strft
22580 69 6d 65 28 27 25 59 2d 25 6d 2d 25 64 20 25 48  ime('%Y-%m-%d %H
22590 3a 25 4d 3a 25 53 27 2c 20 2e 2e 2e 29 0a 3c 74  :%M:%S', ...).<t
225a0 72 3e 3c 74 64 3e 20 20 20 6a 75 6c 69 61 6e 64  r><td>   juliand
225b0 61 79 28 2e 2e 2e 29 20 3c 74 64 3e 3c 74 64 3e  ay(...) <td><td>
225c0 20 20 73 74 72 66 74 69 6d 65 28 27 25 4a 27 2c    strftime('%J',
225d0 20 2e 2e 2e 29 0a 3c 2f 74 61 62 6c 65 3e 0a 3c   ...).</table>.<
225e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a  /blockquote>)^..
225f0 3c 70 3e 0a 54 68 65 20 6f 6e 6c 79 20 72 65 61  <p>.The only rea
22600 73 6f 6e 73 20 66 6f 72 20 70 72 6f 76 69 64 69  sons for providi
22610 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 6f 74 68  ng functions oth
22620 65 72 20 74 68 61 6e 20 73 74 72 66 74 69 6d 65  er than strftime
22630 28 29 20 69 73 0a 66 6f 72 20 63 6f 6e 76 65 6e  () is.for conven
22640 69 65 6e 63 65 20 61 6e 64 20 66 6f 72 20 65 66  ience and for ef
22650 66 69 63 69 65 6e 63 79 2e 0a 3c 2f 70 3e 0a 0a  ficiency..</p>..
22660 3c 68 33 3e 54 69 6d 65 20 53 74 72 69 6e 67 73  <h3>Time Strings
22670 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 41 20 74 69  </h3>..<p>^(A ti
22680 6d 65 20 73 74 72 69 6e 67 20 63 61 6e 20 62 65  me string can be
22690 20 69 6e 20 61 6e 79 20 6f 66 20 74 68 65 20 66   in any of the f
226a0 6f 6c 6c 6f 77 69 6e 67 20 66 6f 72 6d 61 74 73  ollowing formats
226b0 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e  :</p>..<ol>.<li>
226c0 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 3c 2f   <i>YYYY-MM-DD</
226d0 69 3e 0a 3c 6c 69 3e 20 3c 69 3e 59 59 59 59 2d  i>.<li> <i>YYYY-
226e0 4d 4d 2d 44 44 20 48 48 3a 4d 4d 3c 2f 69 3e 0a  MM-DD HH:MM</i>.
226f0 3c 6c 69 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d  <li> <i>YYYY-MM-
22700 44 44 20 48 48 3a 4d 4d 3a 53 53 3c 2f 69 3e 0a  DD HH:MM:SS</i>.
22710 3c 6c 69 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d  <li> <i>YYYY-MM-
22720 44 44 20 48 48 3a 4d 4d 3a 53 53 2e 53 53 53 3c  DD HH:MM:SS.SSS<
22730 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e 59 59 59 59  /i>.<li> <i>YYYY
22740 2d 4d 4d 2d 44 44 3c 2f 69 3e 3c 62 3e 54 3c 2f  -MM-DD</i><b>T</
22750 62 3e 3c 69 3e 48 48 3a 4d 4d 3c 2f 69 3e 0a 3c  b><i>HH:MM</i>.<
22760 6c 69 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44  li> <i>YYYY-MM-D
22770 44 3c 2f 69 3e 3c 62 3e 54 3c 2f 62 3e 3c 69 3e  D</i><b>T</b><i>
22780 48 48 3a 4d 4d 3a 53 53 3c 2f 69 3e 0a 3c 6c 69  HH:MM:SS</i>.<li
22790 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 3c  > <i>YYYY-MM-DD<
227a0 2f 69 3e 3c 62 3e 54 3c 2f 62 3e 3c 69 3e 48 48  /i><b>T</b><i>HH
227b0 3a 4d 4d 3a 53 53 2e 53 53 53 3c 2f 69 3e 0a 3c  :MM:SS.SSS</i>.<
227c0 6c 69 3e 20 3c 69 3e 48 48 3a 4d 4d 3c 2f 69 3e  li> <i>HH:MM</i>
227d0 0a 3c 6c 69 3e 20 3c 69 3e 48 48 3a 4d 4d 3a 53  .<li> <i>HH:MM:S
227e0 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e 48 48  S</i>.<li> <i>HH
227f0 3a 4d 4d 3a 53 53 2e 53 53 53 3c 2f 69 3e 0a 3c  :MM:SS.SSS</i>.<
22800 6c 69 3e 20 3c 62 3e 6e 6f 77 3c 2f 62 3e 0a 3c  li> <b>now</b>.<
22810 6c 69 3e 20 3c 69 3e 44 44 44 44 44 44 44 44 44  li> <i>DDDDDDDDD
22820 44 3c 2f 69 3e 0a 3c 2f 6f 6c 3e 29 5e 0a 0a 3c  D</i>.</ol>)^..<
22830 70 3e 0a 5e 49 6e 20 66 6f 72 6d 61 74 73 20 35  p>.^In formats 5
22840 20 74 68 72 6f 75 67 68 20 37 2c 20 74 68 65 20   through 7, the 
22850 22 54 22 20 69 73 20 61 20 6c 69 74 65 72 61 6c  "T" is a literal
22860 20 63 68 61 72 61 63 74 65 72 20 73 65 70 61 72   character separ
22870 61 74 69 6e 67 20 0a 74 68 65 20 64 61 74 65 20  ating .the date 
22880 61 6e 64 20 74 68 65 20 74 69 6d 65 2c 20 61 73  and the time, as
22890 20 72 65 71 75 69 72 65 64 20 62 79 20 0a 5b 68   required by .[h
228a0 74 74 70 3a 2f 2f 77 77 77 2e 77 33 63 2e 6f 72  ttp://www.w3c.or
228b0 67 2f 54 52 2f 4e 4f 54 45 2d 64 61 74 65 74 69  g/TR/NOTE-dateti
228c0 6d 65 20 7c 20 49 53 4f 2d 38 36 30 31 5d 2e 20  me | ISO-8601]. 
228d0 0a 5e 46 6f 72 6d 61 74 73 20 38 20 74 68 72 6f  .^Formats 8 thro
228e0 75 67 68 20 31 30 20 74 68 61 74 20 73 70 65 63  ugh 10 that spec
228f0 69 66 79 20 6f 6e 6c 79 20 61 20 74 69 6d 65 20  ify only a time 
22900 61 73 73 75 6d 65 20 61 20 64 61 74 65 20 6f 66  assume a date of
22910 20 0a 32 30 30 30 2d 30 31 2d 30 31 2e 20 46 6f   .2000-01-01. Fo
22920 72 6d 61 74 20 31 31 2c 20 74 68 65 20 73 74 72  rmat 11, the str
22930 69 6e 67 20 27 6e 6f 77 27 2c 20 69 73 20 63 6f  ing 'now', is co
22940 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65  nverted into the
22950 20 0a 63 75 72 72 65 6e 74 20 64 61 74 65 20 61   .current date a
22960 6e 64 20 74 69 6d 65 20 61 73 20 6f 62 74 61 69  nd time as obtai
22970 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 43 75  ned from the xCu
22980 72 72 65 6e 74 54 69 6d 65 20 6d 65 74 68 6f 64  rrentTime method
22990 0a 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .of the [sqlite3
229a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 6e 20  _vfs] object in 
229b0 75 73 65 2e 0a 5e 54 68 65 20 27 6e 6f 77 27 20  use..^The 'now' 
229c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 64 61 74 65  argument to date
229d0 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63 74 69   and time functi
229e0 6f 6e 73 20 61 6c 77 61 79 73 20 72 65 74 75 72  ons always retur
229f0 6e 73 20 65 78 61 63 74 6c 79 20 74 68 65 0a 73  ns exactly the.s
22a00 61 6d 65 20 76 61 6c 75 65 20 66 6f 72 20 6d 75  ame value for mu
22a10 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
22a20 6e 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ns within the sa
22a30 6d 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  me [sqlite3_step
22a40 28 29 5d 20 63 61 6c 6c 2e 0a 5e 5b 68 74 74 70  ()] call..^[http
22a50 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e  ://en.wikipedia.
22a60 6f 72 67 2f 77 69 6b 69 2f 43 6f 6f 72 64 69 6e  org/wiki/Coordin
22a70 61 74 65 64 5f 55 6e 69 76 65 72 73 61 6c 5f 54  ated_Universal_T
22a80 69 6d 65 20 7c 20 55 6e 69 76 65 72 73 61 6c 20  ime | Universal 
22a90 43 6f 6f 72 64 69 6e 61 74 65 64 20 54 69 6d 65  Coordinated Time
22aa0 20 28 55 54 43 29 5d 20 69 73 20 75 73 65 64 2e   (UTC)] is used.
22ab0 20 0a 5e 46 6f 72 6d 61 74 20 31 32 20 69 73 20   .^Format 12 is 
22ac0 74 68 65 20 0a 5b 68 74 74 70 3a 2f 2f 65 6e 2e  the .[http://en.
22ad0 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69  wikipedia.org/wi
22ae0 6b 69 2f 4a 75 6c 69 61 6e 5f 64 61 79 20 7c 20  ki/Julian_day | 
22af0 4a 75 6c 69 61 6e 20 64 61 79 20 6e 75 6d 62 65  Julian day numbe
22b00 72 5d 0a 65 78 70 72 65 73 73 65 64 20 61 73 20  r].expressed as 
22b10 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
22b20 20 76 61 6c 75 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70   value..</p>..<p
22b30 3e 0a 46 6f 72 6d 61 74 73 20 32 20 74 68 72 6f  >.Formats 2 thro
22b40 75 67 68 20 31 30 20 6d 61 79 20 62 65 20 6f 70  ugh 10 may be op
22b50 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
22b60 64 20 62 79 20 61 20 74 69 6d 65 7a 6f 6e 65 20  d by a timezone 
22b70 69 6e 64 69 63 61 74 6f 72 20 6f 66 20 74 68 65  indicator of the
22b80 20 66 6f 72 6d 0a 22 3c 69 3e 26 23 39 31 3b 2b   form."<i>&#91;+
22b90 2d 26 23 39 33 3b 48 48 3a 4d 4d 3c 2f 69 3e 22  -&#93;HH:MM</i>"
22ba0 20 6f 72 20 6a 75 73 74 20 22 3c 69 3e 5a 3c 2f   or just "<i>Z</
22bb0 69 3e 22 2e 20 20 54 68 65 20 64 61 74 65 20 61  i>".  The date a
22bc0 6e 64 20 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e  nd time function
22bd0 73 20 75 73 65 20 55 54 43 20 6f 72 20 22 7a 75  s use UTC or "zu
22be0 6c 75 22 0a 74 69 6d 65 20 69 6e 74 65 72 6e 61  lu".time interna
22bf0 6c 6c 79 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  lly, and so the 
22c00 22 5a 22 20 73 75 66 66 69 78 20 69 73 20 61 20  "Z" suffix is a 
22c10 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 6e 6f 6e 2d  no-op.  Any non-
22c20 7a 65 72 6f 20 22 48 48 3a 4d 4d 22 20 73 75 66  zero "HH:MM" suf
22c30 66 69 78 20 69 73 0a 73 75 62 74 72 61 63 74 65  fix is.subtracte
22c40 64 20 66 72 6f 6d 20 74 68 65 20 69 6e 64 69 63  d from the indic
22c50 61 74 65 64 20 64 61 74 65 20 61 6e 64 20 74 69  ated date and ti
22c60 6d 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 63  me in order to c
22c70 6f 6d 70 75 74 65 20 7a 75 6c 75 20 74 69 6d 65  ompute zulu time
22c80 2e 0a 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  ..For example, a
22c90 6c 6c 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ll of the follow
22ca0 69 6e 67 20 74 69 6d 65 20 73 74 72 69 6e 67 73  ing time strings
22cb0 20 61 72 65 20 65 71 75 69 76 61 6c 65 6e 74 3a   are equivalent:
22cc0 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
22cd0 74 65 3e 0a 32 30 31 33 2d 31 30 2d 30 37 20 30  te>.2013-10-07 0
22ce0 38 3a 32 33 3a 31 39 2e 31 32 30 3c 62 72 3e 0a  8:23:19.120<br>.
22cf0 32 30 31 33 2d 31 30 2d 30 37 54 30 38 3a 32 33  2013-10-07T08:23
22d00 3a 31 39 2e 31 32 30 5a 3c 62 72 3e 0a 32 30 31  :19.120Z<br>.201
22d10 33 2d 31 30 2d 30 37 20 30 34 3a 32 33 3a 31 39  3-10-07 04:23:19
22d20 2e 31 32 30 2d 30 34 3a 30 30 3c 62 72 3e 0a 32  .120-04:00<br>.2
22d30 34 35 36 35 37 32 2e 38 34 39 35 32 36 38 35 0a  456572.84952685.
22d40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
22d50 70 3e 0a 5e 28 49 6e 20 66 6f 72 6d 61 74 73 20  p>.^(In formats 
22d60 34 2c 20 37 2c 20 61 6e 64 20 31 30 2c 20 74 68  4, 7, and 10, th
22d70 65 20 66 72 61 63 74 69 6f 6e 61 6c 20 73 65 63  e fractional sec
22d80 6f 6e 64 73 20 76 61 6c 75 65 20 53 53 2e 53 53  onds value SS.SS
22d90 53 20 63 61 6e 20 68 61 76 65 0a 6f 6e 65 20 6f  S can have.one o
22da0 72 20 6d 6f 72 65 20 64 69 67 69 74 73 20 66 6f  r more digits fo
22db0 6c 6c 6f 77 69 6e 67 20 74 68 65 20 64 65 63 69  llowing the deci
22dc0 6d 61 6c 20 70 6f 69 6e 74 2e 20 20 45 78 61 63  mal point.  Exac
22dd0 74 6c 79 20 74 68 72 65 65 20 64 69 67 69 74 73  tly three digits
22de0 20 61 72 65 0a 73 68 6f 77 6e 20 69 6e 20 74 68   are.shown in th
22df0 65 20 65 78 61 6d 70 6c 65 73 20 62 65 63 61 75  e examples becau
22e00 73 65 20 6f 6e 6c 79 20 74 68 65 20 66 69 72 73  se only the firs
22e10 74 20 74 68 72 65 65 20 64 69 67 69 74 73 20 61  t three digits a
22e20 72 65 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 74  re significant.t
22e30 6f 20 74 68 65 20 72 65 73 75 6c 74 2c 20 62 75  o the result, bu
22e40 74 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  t the input stri
22e50 6e 67 20 63 61 6e 20 68 61 76 65 20 66 65 77 65  ng can have fewe
22e60 72 20 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74  r or more than t
22e70 68 72 65 65 20 64 69 67 69 74 73 0a 61 6e 64 20  hree digits.and 
22e80 74 68 65 20 64 61 74 65 2f 74 69 6d 65 20 66 75  the date/time fu
22e90 6e 63 74 69 6f 6e 73 20 77 69 6c 6c 20 73 74 69  nctions will sti
22ea0 6c 6c 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  ll operate corre
22eb0 63 74 6c 79 2e 29 5e 0a 53 69 6d 69 6c 61 72 6c  ctly.)^.Similarl
22ec0 79 2c 20 66 6f 72 6d 61 74 20 31 32 20 69 73 20  y, format 12 is 
22ed0 73 68 6f 77 6e 20 77 69 74 68 20 31 30 20 73 69  shown with 10 si
22ee0 67 6e 69 66 69 63 61 6e 74 20 64 69 67 69 74 73  gnificant digits
22ef0 2c 20 62 75 74 20 74 68 65 20 64 61 74 65 2f 74  , but the date/t
22f00 69 6d 65 0a 66 75 6e 63 74 69 6f 6e 73 20 77 69  ime.functions wi
22f10 6c 6c 20 72 65 61 6c 6c 79 20 61 63 63 65 70 74  ll really accept
22f20 20 61 73 20 6d 61 6e 79 20 6f 72 20 61 73 20 66   as many or as f
22f30 65 77 20 64 69 67 69 74 73 20 61 73 20 61 72 65  ew digits as are
22f40 20 6e 65 63 65 73 73 61 72 79 20 74 6f 0a 72 65   necessary to.re
22f50 70 72 65 73 65 6e 74 20 74 68 65 20 4a 75 6c 69  present the Juli
22f60 61 6e 20 64 61 79 20 6e 75 6d 62 65 72 2e 0a 3c  an day number..<
22f70 2f 70 3e 0a 0a 3c 68 33 3e 4d 6f 64 69 66 69 65  /p>..<h3>Modifie
22f80 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65  rs</h3>..<p>^The
22f90 20 74 69 6d 65 20 73 74 72 69 6e 67 20 63 61 6e   time string can
22fa0 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20   be followed by 
22fb0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 6d 6f 64  zero or more mod
22fc0 69 66 69 65 72 73 20 74 68 61 74 20 0a 61 6c 74  ifiers that .alt
22fd0 65 72 20 64 61 74 65 20 61 6e 64 2f 6f 72 20 74  er date and/or t
22fe0 69 6d 65 2e 20 5e 45 61 63 68 20 6d 6f 64 69 66  ime. ^Each modif
22ff0 69 65 72 0a 69 73 20 61 20 74 72 61 6e 73 66 6f  ier.is a transfo
23000 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  rmation that is 
23010 61 70 70 6c 69 65 64 20 74 6f 20 74 68 65 20 74  applied to the t
23020 69 6d 65 20 76 61 6c 75 65 20 74 6f 20 69 74 73  ime value to its
23030 20 6c 65 66 74 2e 0a 5e 4d 6f 64 69 66 69 65 72   left..^Modifier
23040 73 20 61 72 65 20 61 70 70 6c 69 65 64 20 66 72  s are applied fr
23050 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74  om left to right
23060 3b 20 6f 72 64 65 72 20 69 73 20 69 6d 70 6f 72  ; order is impor
23070 74 61 6e 74 2e 0a 5e 28 54 68 65 20 61 76 61 69  tant..^(The avai
23080 6c 61 62 6c 65 20 6d 6f 64 69 66 69 65 72 73 20  lable modifiers 
23090 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 2e 3c  are as follows.<
230a0 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 4e  /p>..<ol>.<li> N
230b0 4e 4e 20 64 61 79 73 0a 3c 6c 69 3e 20 4e 4e 4e  NN days.<li> NNN
230c0 20 68 6f 75 72 73 0a 3c 6c 69 3e 20 4e 4e 4e 20   hours.<li> NNN 
230d0 6d 69 6e 75 74 65 73 0a 3c 6c 69 3e 20 4e 4e 4e  minutes.<li> NNN
230e0 2e 4e 4e 4e 4e 20 73 65 63 6f 6e 64 73 0a 3c 6c  .NNNN seconds.<l
230f0 69 3e 20 4e 4e 4e 20 6d 6f 6e 74 68 73 0a 3c 6c  i> NNN months.<l
23100 69 3e 20 4e 4e 4e 20 79 65 61 72 73 0a 3c 6c 69  i> NNN years.<li
23110 3e 20 73 74 61 72 74 20 6f 66 20 6d 6f 6e 74 68  > start of month
23120 0a 3c 6c 69 3e 20 73 74 61 72 74 20 6f 66 20 79  .<li> start of y
23130 65 61 72 0a 3c 6c 69 3e 20 73 74 61 72 74 20 6f  ear.<li> start o
23140 66 20 64 61 79 0a 3c 6c 69 3e 20 77 65 65 6b 64  f day.<li> weekd
23150 61 79 20 4e 0a 3c 6c 69 3e 20 75 6e 69 78 65 70  ay N.<li> unixep
23160 6f 63 68 0a 3c 6c 69 3e 20 6c 6f 63 61 6c 74 69  och.<li> localti
23170 6d 65 0a 3c 6c 69 3e 20 75 74 63 20 0a 3c 2f 6f  me.<li> utc .</o
23180 6c 3e 29 5e 0a 0a 3c 70 3e 5e 54 68 65 20 66 69  l>)^..<p>^The fi
23190 72 73 74 20 73 69 78 20 6d 6f 64 69 66 69 65 72  rst six modifier
231a0 73 20 28 31 20 74 68 72 6f 75 67 68 20 36 29 20  s (1 through 6) 
231b0 0a 73 69 6d 70 6c 79 20 61 64 64 20 74 68 65 20  .simply add the 
231c0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
231d0 20 6f 66 20 74 69 6d 65 20 74 6f 20 74 68 65 20   of time to the 
231e0 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 0a 73  date and time .s
231f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
23200 70 72 65 63 65 64 69 6e 67 20 74 69 6d 65 73 74  preceding timest
23210 72 69 6e 67 20 61 6e 64 20 6d 6f 64 69 66 69 65  ring and modifie
23220 72 73 2e 0a 5e 54 68 65 20 27 73 27 20 63 68 61  rs..^The 's' cha
23230 72 61 63 74 65 72 20 61 74 20 74 68 65 20 65 6e  racter at the en
23240 64 20 6f 66 20 74 68 65 20 6d 6f 64 69 66 69 65  d of the modifie
23250 72 20 6e 61 6d 65 73 20 69 73 20 6f 70 74 69 6f  r names is optio
23260 6e 61 6c 2e 0a 5e 4e 6f 74 65 20 74 68 61 74 20  nal..^Note that 
23270 22 26 70 6c 75 73 6d 6e 3b 4e 4e 4e 20 6d 6f 6e  "&plusmn;NNN mon
23280 74 68 73 22 20 77 6f 72 6b 73 20 62 79 20 72 65  ths" works by re
23290 6e 64 65 72 69 6e 67 20 74 68 65 20 6f 72 69 67  ndering the orig
232a0 69 6e 61 6c 20 64 61 74 65 20 69 6e 74 6f 0a 74  inal date into.t
232b0 68 65 20 59 59 59 59 2d 4d 4d 2d 44 44 20 66 6f  he YYYY-MM-DD fo
232c0 72 6d 61 74 2c 20 61 64 64 69 6e 67 20 74 68 65  rmat, adding the
232d0 20 26 70 6c 75 73 6d 6e 3b 4e 4e 4e 20 74 6f 20   &plusmn;NNN to 
232e0 74 68 65 20 4d 4d 20 6d 6f 6e 74 68 20 76 61 6c  the MM month val
232f0 75 65 2c 20 74 68 65 6e 0a 6e 6f 72 6d 61 6c 69  ue, then.normali
23300 7a 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  zing the result.
23310 20 20 5e 54 68 75 73 2c 20 66 6f 72 20 65 78 61    ^Thus, for exa
23320 6d 70 6c 65 2c 20 74 68 65 20 64 61 74 61 20 32  mple, the data 2
23330 30 30 31 2d 30 33 2d 33 31 20 6d 6f 64 69 66 69  001-03-31 modifi
23340 65 64 0a 62 79 20 27 2b 31 20 6d 6f 6e 74 68 27  ed.by '+1 month'
23350 20 69 6e 69 74 69 61 6c 6c 79 20 79 69 65 6c 64   initially yield
23360 73 20 32 30 30 31 2d 30 34 2d 33 31 2c 20 62 75  s 2001-04-31, bu
23370 74 20 41 70 72 69 6c 20 6f 6e 6c 79 20 68 61 73  t April only has
23380 20 33 30 20 64 61 79 73 0a 73 6f 20 74 68 65 20   30 days.so the 
23390 64 61 74 65 20 69 73 20 6e 6f 72 6d 61 6c 69 7a  date is normaliz
233a0 65 64 20 74 6f 20 32 30 30 31 2d 30 35 2d 30 31  ed to 2001-05-01
233b0 2e 20 20 5e 41 20 73 69 6d 69 6c 61 72 20 65 66  .  ^A similar ef
233c0 66 65 63 74 20 6f 63 63 75 72 73 20 77 68 65 6e  fect occurs when
233d0 0a 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 64 61  .the original da
233e0 74 65 20 69 73 20 46 65 62 72 75 61 72 79 20 32  te is February 2
233f0 39 20 6f 66 20 61 20 6c 65 61 70 79 65 61 72 20  9 of a leapyear 
23400 61 6e 64 20 74 68 65 20 6d 6f 64 69 66 69 65 72  and the modifier
23410 20 69 73 0a 26 70 6c 75 73 6d 6e 3b 4e 20 79 65   is.&plusmn;N ye
23420 61 72 73 20 77 68 65 72 65 20 4e 20 69 73 20 6e  ars where N is n
23430 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
23440 20 66 6f 75 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e   four.</p>..<p>^
23450 54 68 65 20 22 73 74 61 72 74 20 6f 66 22 20 6d  The "start of" m
23460 6f 64 69 66 69 65 72 73 20 28 37 20 74 68 72 6f  odifiers (7 thro
23470 75 67 68 20 39 29 20 73 68 69 66 74 20 74 68 65  ugh 9) shift the
23480 20 64 61 74 65 20 62 61 63 6b 77 61 72 64 73 20   date backwards 
23490 0a 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .to the beginnin
234a0 67 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  g of the current
234b0 20 6d 6f 6e 74 68 2c 20 79 65 61 72 20 6f 72 20   month, year or 
234c0 64 61 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 28 54  day.</p>..<p>^(T
234d0 68 65 20 22 77 65 65 6b 64 61 79 22 20 6d 6f 64  he "weekday" mod
234e0 69 66 69 65 72 20 61 64 76 61 6e 63 65 73 20 74  ifier advances t
234f0 68 65 20 64 61 74 65 20 66 6f 72 77 61 72 64 2c  he date forward,
23500 20 69 66 20 6e 65 63 65 73 73 61 72 79 2c 0a 74   if necessary,.t
23510 6f 20 74 68 65 20 6e 65 78 74 20 64 61 74 65 20  o the next date 
23520 77 68 65 72 65 20 74 68 65 20 77 65 65 6b 64 61  where the weekda
23530 79 20 6e 75 6d 62 65 72 20 69 73 20 4e 2e 20 53  y number is N. S
23540 75 6e 64 61 79 20 69 73 20 30 2c 20 4d 6f 6e 64  unday is 0, Mond
23550 61 79 20 69 73 20 31 2c 0a 61 6e 64 20 73 6f 20  ay is 1,.and so 
23560 66 6f 72 74 68 2e 29 5e 0a 5e 49 66 20 74 68 65  forth.)^.^If the
23570 20 64 61 74 65 20 69 73 20 61 6c 72 65 61 64 79   date is already
23580 20 6f 6e 20 74 68 65 20 64 65 73 69 72 65 64 20   on the desired 
23590 77 65 65 6b 64 61 79 2c 20 74 68 65 20 22 77 65  weekday, the "we
235a0 65 6b 64 61 79 22 20 6d 6f 64 69 66 69 65 72 0a  ekday" modifier.
235b0 6c 65 61 76 65 73 20 74 68 65 20 64 61 74 65 20  leaves the date 
235c0 75 6e 63 68 61 6e 67 65 64 2e 20 20 3c 2f 70 3e  unchanged.  </p>
235d0 0a 0a 3c 70 3e 5e 54 68 65 20 22 75 6e 69 78 65  ..<p>^The "unixe
235e0 70 6f 63 68 22 20 6d 6f 64 69 66 69 65 72 20 28  poch" modifier (
235f0 31 31 29 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 69  11) only works i
23600 66 20 69 74 20 69 6d 6d 65 64 69 61 74 65 6c 79  f it immediately
23610 20 66 6f 6c 6c 6f 77 73 20 0a 61 20 74 69 6d 65   follows .a time
23620 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20 44 44  string in the DD
23630 44 44 44 44 44 44 44 44 20 66 6f 72 6d 61 74 2e  DDDDDDDD format.
23640 20 0a 5e 54 68 69 73 20 6d 6f 64 69 66 69 65 72   .^This modifier
23650 20 63 61 75 73 65 73 20 74 68 65 20 44 44 44 44   causes the DDDD
23660 44 44 44 44 44 44 20 74 6f 20 62 65 20 69 6e 74  DDDDDD to be int
23670 65 72 70 72 65 74 65 64 20 6e 6f 74 20 0a 61 73  erpreted not .as
23680 20 61 20 4a 75 6c 69 61 6e 20 64 61 79 20 6e 75   a Julian day nu
23690 6d 62 65 72 20 61 73 20 69 74 20 6e 6f 72 6d 61  mber as it norma
236a0 6c 6c 79 20 77 6f 75 6c 64 20 62 65 2c 20 62 75  lly would be, bu
236b0 74 20 61 73 0a 5b 68 74 74 70 3a 2f 2f 65 6e 2e  t as.[http://en.
236c0 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69  wikipedia.org/wi
236d0 6b 69 2f 55 6e 69 78 5f 74 69 6d 65 20 7c 20 55  ki/Unix_time | U
236e0 6e 69 78 20 54 69 6d 65 5d 20 2d 20 74 68 65 20  nix Time] - the 
236f0 0a 6e 75 6d 62 65 72 20 6f 66 20 73 65 63 6f 6e  .number of secon
23700 64 73 20 73 69 6e 63 65 20 31 39 37 30 2e 20 20  ds since 1970.  
23710 49 66 20 74 68 65 20 22 75 6e 69 78 65 70 6f 63  If the "unixepoc
23720 68 22 20 6d 6f 64 69 66 69 65 72 20 64 6f 65 73  h" modifier does
23730 20 6e 6f 74 0a 66 6f 6c 6c 6f 77 20 61 20 74 69   not.follow a ti
23740 6d 65 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20  mestring of the 
23750 66 6f 72 6d 20 44 44 44 44 44 44 44 44 44 44 20  form DDDDDDDDDD 
23760 77 68 69 63 68 20 65 78 70 72 65 73 73 65 73 20  which expresses 
23770 74 68 65 20 6e 75 6d 62 65 72 0a 6f 66 20 73 65  the number.of se
23780 63 6f 6e 64 73 20 73 69 6e 63 65 20 31 39 37 30  conds since 1970
23790 20 6f 72 20 69 66 20 6f 74 68 65 72 20 6d 6f 64   or if other mod
237a0 69 66 69 65 72 73 0a 73 65 70 61 72 61 74 65 20  ifiers.separate 
237b0 74 68 65 20 22 75 6e 69 78 65 70 6f 63 68 22 20  the "unixepoch" 
237c0 6d 6f 64 69 66 69 65 72 20 66 72 6f 6d 20 70 72  modifier from pr
237d0 69 6f 72 20 44 44 44 44 44 44 44 44 44 44 20 74  ior DDDDDDDDDD t
237e0 68 65 6e 20 74 68 65 0a 62 65 68 61 76 69 6f 72  hen the.behavior
237f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 46   is undefined..F
23800 6f 72 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  or SQLite versio
23810 6e 73 20 62 65 66 6f 72 65 20 33 2e 31 36 2e 30  ns before 3.16.0
23820 20 28 5b 64 61 74 65 6f 66 3a 33 2e 31 36 2e 30   ([dateof:3.16.0
23830 5d 29 2c 20 0a 74 68 65 20 22 75 6e 69 78 65 70  ]), .the "unixep
23840 6f 63 68 22 20 6d 6f 64 69 66 69 65 72 20 6f 6e  och" modifier on
23850 6c 79 20 77 6f 72 6b 73 20 66 6f 72 0a 64 61 74  ly works for.dat
23860 65 73 20 62 65 74 77 65 65 6e 20 30 30 30 30 2d  es between 0000-
23870 30 31 2d 30 31 20 30 30 3a 30 30 3a 30 30 20 61  01-01 00:00:00 a
23880 6e 64 20 35 33 35 32 2d 31 31 2d 30 31 20 31 30  nd 5352-11-01 10
23890 3a 35 32 3a 34 37 20 28 75 6e 69 78 20 74 69 6d  :52:47 (unix tim
238a0 65 73 0a 6f 66 20 2d 36 32 31 36 37 32 31 39 32  es.of -621672192
238b0 30 30 20 74 68 72 6f 75 67 68 20 31 30 36 37 35  00 through 10675
238c0 31 39 39 31 31 36 37 29 2e 3c 2f 70 3e 0a 0a 3c  1991167).</p>..<
238d0 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
238e0 6c 6f 63 61 6c 74 69 6d 65 20 7b 6c 6f 63 61 6c  localtime {local
238f0 74 69 6d 65 20 6d 6f 64 69 66 69 65 72 7d 20 7b  time modifier} {
23900 27 75 74 63 27 20 6d 6f 64 69 66 69 65 72 7d 3c  'utc' modifier}<
23910 2f 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 22 6c  /tcl>.<p>^The "l
23920 6f 63 61 6c 74 69 6d 65 22 20 6d 6f 64 69 66 69  ocaltime" modifi
23930 65 72 20 28 31 32 29 20 61 73 73 75 6d 65 73 20  er (12) assumes 
23940 74 68 65 20 74 69 6d 65 20 73 74 72 69 6e 67 20  the time string 
23950 74 6f 20 69 74 73 20 6c 65 66 74 20 69 73 20 69  to its left is i
23960 6e 0a 55 6e 69 76 65 72 73 61 6c 20 43 6f 6f 72  n.Universal Coor
23970 64 69 6e 61 74 65 64 20 54 69 6d 65 20 28 55 54  dinated Time (UT
23980 43 29 20 61 6e 64 20 61 64 6a 75 73 74 73 20 74  C) and adjusts t
23990 68 65 20 74 69 6d 65 0a 73 74 72 69 6e 67 20 73  he time.string s
239a0 6f 20 74 68 61 74 20 69 74 20 64 69 73 70 6c 61  o that it displa
239b0 79 73 20 6c 6f 63 61 6c 74 69 6d 65 2e 20 20 49  ys localtime.  I
239c0 66 20 22 6c 6f 63 61 6c 74 69 6d 65 22 0a 66 6f  f "localtime".fo
239d0 6c 6c 6f 77 73 20 61 20 74 69 6d 65 20 74 68 61  llows a time tha
239e0 74 20 69 73 20 6e 6f 74 20 55 54 43 2c 20 74 68  t is not UTC, th
239f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
23a00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 5e 28  is undefined..^(
23a10 54 68 65 20 22 75 74 63 22 20 6d 6f 64 69 66 69  The "utc" modifi
23a20 65 72 20 69 73 20 74 68 65 20 6f 70 70 6f 73 69  er is the opposi
23a30 74 65 20 6f 66 20 22 6c 6f 63 61 6c 74 69 6d 65  te of "localtime
23a40 22 2e 20 20 0a 22 75 74 63 22 20 61 73 73 75 6d  ".  ."utc" assum
23a50 65 73 20 74 68 61 74 20 74 68 65 20 73 74 72 69  es that the stri
23a60 6e 67 0a 74 6f 20 69 74 73 20 6c 65 66 74 20 69  ng.to its left i
23a70 73 20 69 6e 20 74 68 65 20 6c 6f 63 61 6c 20 74  s in the local t
23a80 69 6d 65 7a 6f 6e 65 20 61 6e 64 20 61 64 6a 75  imezone and adju
23a90 73 74 73 20 74 68 61 74 20 73 74 72 69 6e 67 20  sts that string 
23aa0 74 6f 20 62 65 20 69 6e 20 55 54 43 2e 29 5e 0a  to be in UTC.)^.
23ab0 49 66 20 74 68 65 20 70 72 69 6f 72 20 73 74 72  If the prior str
23ac0 69 6e 67 20 69 73 20 6e 6f 74 20 69 6e 20 6c 6f  ing is not in lo
23ad0 63 61 6c 74 69 6d 65 2c 20 74 68 65 6e 20 74 68  caltime, then th
23ae0 65 20 72 65 73 75 6c 74 20 6f 66 20 22 75 74 63  e result of "utc
23af0 22 20 69 73 0a 75 6e 64 65 66 69 6e 65 64 2e 3c  " is.undefined.<
23b00 2f 70 3e 0a 0a 3c 68 33 3e 45 78 61 6d 70 6c 65  /p>..<h3>Example
23b10 73 3c 2f 68 33 3e 0a 0a 5e 28 3c 70 3e 43 6f 6d  s</h3>..^(<p>Com
23b20 70 75 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  pute the current
23b30 20 64 61 74 65 2e 3c 70 3e 0a 0a 3c 62 6c 6f 63   date.<p>..<bloc
23b40 6b 71 75 6f 74 65 3e 53 45 4c 45 43 54 20 64 61  kquote>SELECT da
23b50 74 65 28 27 6e 6f 77 27 29 3b 3c 2f 62 6c 6f 63  te('now');</bloc
23b60 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e  kquote>)^..^(<p>
23b70 43 6f 6d 70 75 74 65 20 74 68 65 20 6c 61 73 74  Compute the last
23b80 20 64 61 79 20 6f 66 20 74 68 65 20 63 75 72 72   day of the curr
23b90 65 6e 74 20 6d 6f 6e 74 68 2e 3c 2f 70 3e 0a 0a  ent month.</p>..
23ba0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 53 45 4c 45  <blockquote>SELE
23bb0 43 54 20 64 61 74 65 28 27 6e 6f 77 27 2c 27 73  CT date('now','s
23bc0 74 61 72 74 20 6f 66 20 6d 6f 6e 74 68 27 2c 27  tart of month','
23bd0 2b 31 20 6d 6f 6e 74 68 27 2c 27 2d 31 20 64 61  +1 month','-1 da
23be0 79 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  y');.</blockquot
23bf0 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75  e>)^..^(<p>Compu
23c00 74 65 20 74 68 65 20 64 61 74 65 20 61 6e 64 20  te the date and 
23c10 74 69 6d 65 20 67 69 76 65 6e 20 61 20 75 6e 69  time given a uni
23c20 78 20 74 69 6d 65 73 74 61 6d 70 20 31 30 39 32  x timestamp 1092
23c30 39 34 31 34 36 36 2e 3c 2f 70 3e 0a 0a 3c 62 6c  941466.</p>..<bl
23c40 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 20 20 53 45  ockquote>.    SE
23c50 4c 45 43 54 20 64 61 74 65 74 69 6d 65 28 31 30  LECT datetime(10
23c60 39 32 39 34 31 34 36 36 2c 20 27 75 6e 69 78 65  92941466, 'unixe
23c70 70 6f 63 68 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71  poch');.</blockq
23c80 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f  uote>)^..^(<p>Co
23c90 6d 70 75 74 65 20 74 68 65 20 64 61 74 65 20 61  mpute the date a
23ca0 6e 64 20 74 69 6d 65 20 67 69 76 65 6e 20 61 20  nd time given a 
23cb0 75 6e 69 78 20 74 69 6d 65 73 74 61 6d 70 20 31  unix timestamp 1
23cc0 30 39 32 39 34 31 34 36 36 2c 20 61 6e 64 20 0a  092941466, and .
23cd0 63 6f 6d 70 65 6e 73 61 74 65 20 66 6f 72 20 79  compensate for y
23ce0 6f 75 72 20 6c 6f 63 61 6c 20 74 69 6d 65 7a 6f  our local timezo
23cf0 6e 65 2e 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ne.</p>..<blockq
23d00 75 6f 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 64  uote>.  SELECT d
23d10 61 74 65 74 69 6d 65 28 31 30 39 32 39 34 31 34  atetime(10929414
23d20 36 36 2c 20 27 75 6e 69 78 65 70 6f 63 68 27 2c  66, 'unixepoch',
23d30 20 27 6c 6f 63 61 6c 74 69 6d 65 27 29 3b 0a 3c   'localtime');.<
23d40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a  /blockquote>)^..
23d50 5e 28 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68 65  ^(<p>Compute the
23d60 20 63 75 72 72 65 6e 74 20 75 6e 69 78 20 74 69   current unix ti
23d70 6d 65 73 74 61 6d 70 2e 3c 2f 70 3e 0a 0a 3c 62  mestamp.</p>..<b
23d80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c  lockquote>.  SEL
23d90 45 43 54 20 73 74 72 66 74 69 6d 65 28 27 25 73  ECT strftime('%s
23da0 27 2c 27 6e 6f 77 27 29 3b 0a 3c 2f 62 6c 6f 63  ','now');.</bloc
23db0 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e  kquote>)^..^(<p>
23dc0 43 6f 6d 70 75 74 65 20 74 68 65 20 6e 75 6d 62  Compute the numb
23dd0 65 72 20 6f 66 20 64 61 79 73 20 73 69 6e 63 65  er of days since
23de0 20 74 68 65 20 73 69 67 6e 69 6e 67 20 6f 66 20   the signing of 
23df0 74 68 65 20 55 53 20 44 65 63 6c 61 72 61 74 69  the US Declarati
23e00 6f 6e 0a 6f 66 20 49 6e 64 65 70 65 6e 64 65 6e  on.of Independen
23e10 63 65 2e 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ce.</p>..<blockq
23e20 75 6f 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 6a  uote>.  SELECT j
23e30 75 6c 69 61 6e 64 61 79 28 27 6e 6f 77 27 29 20  ulianday('now') 
23e40 2d 20 6a 75 6c 69 61 6e 64 61 79 28 27 31 37 37  - julianday('177
23e50 36 2d 30 37 2d 30 34 27 29 3b 0a 3c 2f 62 6c 6f  6-07-04');.</blo
23e60 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70  ckquote>)^..^(<p
23e70 3e 43 6f 6d 70 75 74 65 20 74 68 65 20 6e 75 6d  >Compute the num
23e80 62 65 72 20 6f 66 20 73 65 63 6f 6e 64 73 20 73  ber of seconds s
23e90 69 6e 63 65 20 61 20 70 61 72 74 69 63 75 6c 61  ince a particula
23ea0 72 20 6d 6f 6d 65 6e 74 20 69 6e 20 32 30 30 34  r moment in 2004
23eb0 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
23ec0 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 73 74 72  te>.  SELECT str
23ed0 66 74 69 6d 65 28 27 25 73 27 2c 27 6e 6f 77 27  ftime('%s','now'
23ee0 29 20 2d 20 73 74 72 66 74 69 6d 65 28 27 25 73  ) - strftime('%s
23ef0 27 2c 27 32 30 30 34 2d 30 31 2d 30 31 20 30 32  ','2004-01-01 02
23f00 3a 33 34 3a 35 36 27 29 3b 0a 3c 2f 62 6c 6f 63  :34:56');.</bloc
23f10 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e  kquote>)^..^(<p>
23f20 0a 43 6f 6d 70 75 74 65 20 74 68 65 20 64 61 74  .Compute the dat
23f30 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 54  e of the first T
23f40 75 65 73 64 61 79 20 69 6e 20 4f 63 74 6f 62 65  uesday in Octobe
23f50 72 0a 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r.for the curren
23f60 74 20 79 65 61 72 2e 0a 3c 2f 70 3e 0a 0a 3c 62  t year..</p>..<b
23f70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c  lockquote>.  SEL
23f80 45 43 54 20 64 61 74 65 28 27 6e 6f 77 27 2c 27  ECT date('now','
23f90 73 74 61 72 74 20 6f 66 20 79 65 61 72 27 2c 27  start of year','
23fa0 2b 39 20 6d 6f 6e 74 68 73 27 2c 27 77 65 65 6b  +9 months','week
23fb0 64 61 79 20 32 27 29 3b 0a 3c 2f 62 6c 6f 63 6b  day 2');.</block
23fc0 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43  quote>)^..^(<p>C
23fd0 6f 6d 70 75 74 65 20 74 68 65 20 74 69 6d 65 20  ompute the time 
23fe0 73 69 6e 63 65 20 74 68 65 20 75 6e 69 78 20 65  since the unix e
23ff0 70 6f 63 68 20 69 6e 20 73 65 63 6f 6e 64 73 20  poch in seconds 
24000 0a 28 6c 69 6b 65 20 73 74 72 66 74 69 6d 65 28  .(like strftime(
24010 27 25 73 27 2c 27 6e 6f 77 27 29 20 65 78 63 65  '%s','now') exce
24020 70 74 20 69 6e 63 6c 75 64 65 73 20 66 72 61 63  pt includes frac
24030 74 69 6f 6e 61 6c 20 70 61 72 74 29 3a 3c 2f 70  tional part):</p
24040 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
24050 20 20 53 45 4c 45 43 54 20 28 6a 75 6c 69 61 6e    SELECT (julian
24060 64 61 79 28 27 6e 6f 77 27 29 20 2d 20 32 34 34  day('now') - 244
24070 30 35 38 37 2e 35 29 2a 38 36 34 30 30 2e 30 3b  0587.5)*86400.0;
24080 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  .</blockquote>)^
24090 0a 0a 3c 68 33 3e 43 61 76 65 61 74 73 20 41 6e  ..<h3>Caveats An
240a0 64 20 42 75 67 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  d Bugs</h3>..<p>
240b0 54 68 65 20 63 6f 6d 70 75 74 61 74 69 6f 6e 20  The computation 
240c0 6f 66 20 6c 6f 63 61 6c 20 74 69 6d 65 20 64 65  of local time de
240d0 70 65 6e 64 73 20 68 65 61 76 69 6c 79 20 6f 6e  pends heavily on
240e0 20 74 68 65 20 77 68 69 6d 20 0a 6f 66 20 70 6f   the whim .of po
240f0 6c 69 74 69 63 69 61 6e 73 20 61 6e 64 20 69 73  liticians and is
24100 20 74 68 75 73 20 64 69 66 66 69 63 75 6c 74 20   thus difficult 
24110 74 6f 20 67 65 74 20 63 6f 72 72 65 63 74 20 66  to get correct f
24120 6f 72 20 0a 61 6c 6c 20 6c 6f 63 61 6c 65 73 2e  or .all locales.
24130 20 5e 49 6e 20 74 68 69 73 20 69 6d 70 6c 65 6d   ^In this implem
24140 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  entation, the st
24150 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
24160 20 0a 66 75 6e 63 74 69 6f 6e 20 6c 6f 63 61 6c   .function local
24170 74 69 6d 65 5f 72 28 29 20 69 73 20 75 73 65 64  time_r() is used
24180 20 74 6f 20 61 73 73 69 73 74 20 69 6e 20 74 68   to assist in th
24190 65 20 63 61 6c 63 75 6c 61 74 69 6f 6e 20 6f 66  e calculation of
241a0 20 0a 6c 6f 63 61 6c 20 74 69 6d 65 2e 20 20 5e   .local time.  ^
241b0 28 54 68 65 20 0a 6c 6f 63 61 6c 74 69 6d 65 5f  (The .localtime_
241c0 72 28 29 20 43 20 66 75 6e 63 74 69 6f 6e 20 6e  r() C function n
241d0 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 77 6f 72  ormally only wor
241e0 6b 73 20 66 6f 72 20 79 65 61 72 73 0a 62 65 74  ks for years.bet
241f0 77 65 65 6e 20 31 39 37 30 20 61 6e 64 20 32 30  ween 1970 and 20
24200 33 37 2e 20 46 6f 72 20 64 61 74 65 73 20 6f 75  37. For dates ou
24210 74 73 69 64 65 20 74 68 69 73 20 72 61 6e 67 65  tside this range
24220 2c 20 53 51 4c 69 74 65 20 0a 61 74 74 65 6d 70  , SQLite .attemp
24230 74 73 20 74 6f 20 6d 61 70 20 74 68 65 20 79 65  ts to map the ye
24240 61 72 20 69 6e 74 6f 20 61 6e 20 65 71 75 69 76  ar into an equiv
24250 61 6c 65 6e 74 20 79 65 61 72 20 77 69 74 68 69  alent year withi
24260 6e 20 0a 74 68 69 73 20 72 61 6e 67 65 2c 20 64  n .this range, d
24270 6f 20 74 68 65 20 63 61 6c 63 75 6c 61 74 69 6f  o the calculatio
24280 6e 2c 20 74 68 65 6e 20 6d 61 70 20 74 68 65 20  n, then map the 
24290 79 65 61 72 20 62 61 63 6b 2e 29 5e 3c 2f 70 3e  year back.)^</p>
242a0 0a 0a 0a 3c 70 3e 5e 28 54 68 65 73 65 20 66 75  ...<p>^(These fu
242b0 6e 63 74 69 6f 6e 73 20 6f 6e 6c 79 20 77 6f 72  nctions only wor
242c0 6b 20 66 6f 72 20 64 61 74 65 73 20 62 65 74 77  k for dates betw
242d0 65 65 6e 20 30 30 30 30 2d 30 31 2d 30 31 20 30  een 0000-01-01 0
242e0 30 3a 30 30 3a 30 30 0a 61 6e 64 20 39 39 39 39  0:00:00.and 9999
242f0 2d 31 32 2d 33 31 20 32 33 3a 35 39 3a 35 39 20  -12-31 23:59:59 
24300 28 6a 75 6c 69 61 6e 20 64 61 79 20 6e 75 6d 62  (julian day numb
24310 65 72 73 20 31 37 32 31 30 35 39 2e 35 20 74 68  ers 1721059.5 th
24320 72 6f 75 67 68 20 35 33 37 33 34 38 34 2e 35 29  rough 5373484.5)
24330 2e 29 5e 0a 46 6f 72 20 64 61 74 65 73 20 6f 75  .)^.For dates ou
24340 74 73 69 64 65 20 74 68 61 74 20 72 61 6e 67 65  tside that range
24350 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  , the results of
24360 20 74 68 65 73 65 0a 66 75 6e 63 74 69 6f 6e 73   these.functions
24370 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c   are undefined.<
24380 2f 70 3e 0a 0a 3c 70 3e 4e 6f 6e 2d 56 69 73 74  /p>..<p>Non-Vist
24390 61 20 57 69 6e 64 6f 77 73 20 70 6c 61 74 66 6f  a Windows platfo
243a0 72 6d 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74  rms only support
243b0 20 6f 6e 65 20 73 65 74 20 6f 66 20 44 53 54 20   one set of DST 
243c0 72 75 6c 65 73 2e 20 0a 56 69 73 74 61 20 6f 6e  rules. .Vista on
243d0 6c 79 20 73 75 70 70 6f 72 74 73 20 74 77 6f 2e  ly supports two.
243e0 20 54 68 65 72 65 66 6f 72 65 2c 20 6f 6e 20 74   Therefore, on t
243f0 68 65 73 65 20 70 6c 61 74 66 6f 72 6d 73 2c 20  hese platforms, 
24400 0a 68 69 73 74 6f 72 69 63 61 6c 20 44 53 54 20  .historical DST 
24410 63 61 6c 63 75 6c 61 74 69 6f 6e 73 20 77 69 6c  calculations wil
24420 6c 20 62 65 20 69 6e 63 6f 72 72 65 63 74 2e 20  l be incorrect. 
24430 0a 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e  .For example, in
24440 20 74 68 65 20 55 53 2c 20 69 6e 20 32 30 30 37   the US, in 2007
24450 20 74 68 65 20 44 53 54 20 72 75 6c 65 73 20 63   the DST rules c
24460 68 61 6e 67 65 64 2e 20 0a 4e 6f 6e 2d 56 69 73  hanged. .Non-Vis
24470 74 61 20 57 69 6e 64 6f 77 73 20 70 6c 61 74 66  ta Windows platf
24480 6f 72 6d 73 20 61 70 70 6c 79 20 74 68 65 20 6e  orms apply the n
24490 65 77 20 32 30 30 37 20 44 53 54 20 72 75 6c 65  ew 2007 DST rule
244a0 73 20 0a 74 6f 20 61 6c 6c 20 70 72 65 76 69 6f  s .to all previo
244b0 75 73 20 79 65 61 72 73 20 61 73 20 77 65 6c 6c  us years as well
244c0 2e 20 56 69 73 74 61 20 64 6f 65 73 20 73 6f 6d  . Vista does som
244d0 65 77 68 61 74 20 62 65 74 74 65 72 0a 67 65 74  ewhat better.get
244e0 74 69 6e 67 20 72 65 73 75 6c 74 73 20 63 6f 72  ting results cor
244f0 72 65 63 74 20 62 61 63 6b 20 74 6f 20 31 39 38  rect back to 198
24500 36 2c 20 77 68 65 6e 20 74 68 65 20 72 75 6c 65  6, when the rule
24510 73 20 77 65 72 65 20 61 6c 73 6f 20 63 68 61 6e  s were also chan
24520 67 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 6c 6c  ged.</p>..<p>All
24530 20 69 6e 74 65 72 6e 61 6c 20 63 6f 6d 70 75 74   internal comput
24540 61 74 69 6f 6e 73 20 61 73 73 75 6d 65 20 74 68  ations assume th
24550 65 20 0a 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77 69  e .[http://en.wi
24560 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69  kipedia.org/wiki
24570 2f 47 72 65 67 6f 72 69 61 6e 5f 63 61 6c 65 6e  /Gregorian_calen
24580 64 61 72 20 7c 20 47 72 65 67 6f 72 69 61 6e 20  dar | Gregorian 
24590 63 61 6c 65 6e 64 61 72 5d 0a 73 79 73 74 65 6d  calendar].system
245a0 2e 20 20 49 74 20 69 73 20 61 6c 73 6f 20 61 73  .  It is also as
245b0 73 75 6d 65 64 20 74 68 61 74 20 65 76 65 72 79  sumed that every
245c0 0a 64 61 79 20 69 73 20 65 78 61 63 74 6c 79 20  .day is exactly 
245d0 38 36 34 30 30 20 73 65 63 6f 6e 64 73 20 69 6e  86400 seconds in
245e0 20 64 75 72 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a   duration.</p>..
245f0 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
24600 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24610 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24620 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24630 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24640 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 41 67  ####.Section {Ag
24650 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
24660 73 7d 20 61 67 67 66 75 6e 63 20 7b 2a 61 67 67  s} aggfunc {*agg
24670 66 75 6e 63 7d 0a 75 6e 73 65 74 20 2d 6e 6f 63  func}.unset -noc
24680 6f 6d 70 6c 61 69 6e 20 63 6f 72 65 66 75 6e 63  omplain corefunc
24690 73 65 74 0a 0a 66 75 6e 63 64 65 66 20 7b 61 76  set..funcdef {av
246a0 67 28 58 29 7d 20 7b 2a 61 76 67 20 7b 61 76 67  g(X)} {*avg {avg
246b0 28 29 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  () aggregate fun
246c0 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68 65  ction}} {.  ^The
246d0 20 61 76 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a   avg() function.
246e0 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 76    returns the av
246f0 65 72 61 67 65 20 76 61 6c 75 65 20 6f 66 20 61  erage value of a
24700 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20 3c 69 3e 58  ll non-NULL <i>X
24710 3c 2f 69 3e 20 77 69 74 68 69 6e 20 61 0a 20 20  </i> within a.  
24720 67 72 6f 75 70 2e 20 20 5e 53 74 72 69 6e 67 20  group.  ^String 
24730 61 6e 64 20 42 4c 4f 42 20 76 61 6c 75 65 73 20  and BLOB values 
24740 74 68 61 74 20 64 6f 20 6e 6f 74 20 6c 6f 6f 6b  that do not look
24750 20 6c 69 6b 65 20 6e 75 6d 62 65 72 73 20 61 72   like numbers ar
24760 65 0a 20 20 69 6e 74 65 72 70 72 65 74 65 64 20  e.  interpreted 
24770 61 73 20 30 2e 0a 20 20 5e 54 68 65 20 72 65 73  as 0..  ^The res
24780 75 6c 74 20 6f 66 20 61 76 67 28 29 20 69 73 20  ult of avg() is 
24790 61 6c 77 61 79 73 20 61 20 66 6c 6f 61 74 69 6e  always a floatin
247a0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 73  g point value as
247b0 20 6c 6f 6e 67 20 61 73 0a 20 20 61 74 20 74 68   long as.  at th
247c0 65 72 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ere is at least 
247d0 6f 6e 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 69 6e 70  one non-NULL inp
247e0 75 74 20 65 76 65 6e 20 69 66 20 61 6c 6c 0a 20  ut even if all. 
247f0 20 69 6e 70 75 74 73 20 61 72 65 20 69 6e 74 65   inputs are inte
24800 67 65 72 73 2e 20 20 5e 54 68 65 20 72 65 73 75  gers.  ^The resu
24810 6c 74 20 6f 66 20 61 76 67 28 29 20 69 73 20 4e  lt of avg() is N
24820 55 4c 4c 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ULL if and only 
24830 69 66 0a 20 20 74 68 65 72 65 20 61 72 65 20 6e  if.  there are n
24840 6f 20 6e 6f 6e 2d 4e 55 4c 4c 20 69 6e 70 75 74  o non-NULL input
24850 73 2e 20 20 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  s.  .}..funcdef 
24860 7b 63 6f 75 6e 74 28 58 29 20 63 6f 75 6e 74 28  {count(X) count(
24870 2a 29 7d 20 7b 2a 63 6f 75 6e 74 20 7b 63 6f 75  *)} {*count {cou
24880 6e 74 28 29 20 61 67 67 72 65 67 61 74 65 20 66  nt() aggregate f
24890 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54  unction}} {.  ^T
248a0 68 65 20 63 6f 75 6e 74 28 58 29 20 66 75 6e 63  he count(X) func
248b0 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 20 20 61  tion returns.  a
248c0 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
248d0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 0a 20 20  mber of times.  
248e0 74 68 61 74 20 3c 69 3e 58 3c 2f 69 3e 20 69 73  that <i>X</i> is
248f0 20 6e 6f 74 20 4e 55 4c 4c 20 69 6e 20 61 20 67   not NULL in a g
24900 72 6f 75 70 2e 20 20 5e 54 68 65 20 63 6f 75 6e  roup.  ^The coun
24910 74 28 2a 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20  t(*) function.  
24920 28 77 69 74 68 20 6e 6f 20 61 72 67 75 6d 65 6e  (with no argumen
24930 74 73 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ts) returns the 
24940 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
24950 72 6f 77 73 20 69 6e 20 74 68 65 20 67 72 6f 75  rows in the grou
24960 70 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 67  p..}..funcdef {g
24970 72 6f 75 70 5f 63 6f 6e 63 61 74 28 58 29 20 67  roup_concat(X) g
24980 72 6f 75 70 5f 63 6f 6e 63 61 74 28 58 2c 59 29  roup_concat(X,Y)
24990 7d 20 7b 0a 20 20 2a 67 72 6f 75 70 5f 63 6f 6e  } {.  *group_con
249a0 63 61 74 20 7b 67 72 6f 75 70 5f 63 6f 6e 63 61  cat {group_conca
249b0 74 28 29 20 61 67 67 72 65 67 61 74 65 20 66 75  t() aggregate fu
249c0 6e 63 74 69 6f 6e 7d 0a 7d 20 7b 0a 20 20 5e 54  nction}.} {.  ^T
249d0 68 65 20 67 72 6f 75 70 5f 63 6f 6e 63 61 74 28  he group_concat(
249e0 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
249f0 6e 73 0a 20 20 61 20 73 74 72 69 6e 67 20 77 68  ns.  a string wh
24a00 69 63 68 20 69 73 20 74 68 65 20 63 6f 6e 63 61  ich is the conca
24a10 74 65 6e 61 74 69 6f 6e 20 6f 66 0a 20 20 61 6c  tenation of.  al
24a20 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65  l non-NULL value
24a30 73 20 6f 66 20 3c 69 3e 58 3c 2f 69 3e 2e 20 20  s of <i>X</i>.  
24a40 5e 49 66 20 70 61 72 61 6d 65 74 65 72 20 3c 69  ^If parameter <i
24a50 3e 59 3c 2f 69 3e 20 69 73 20 70 72 65 73 65 6e  >Y</i> is presen
24a60 74 20 74 68 65 6e 0a 20 20 69 74 20 69 73 20 75  t then.  it is u
24a70 73 65 64 20 61 73 20 74 68 65 20 73 65 70 61 72  sed as the separ
24a80 61 74 6f 72 0a 20 20 62 65 74 77 65 65 6e 20 69  ator.  between i
24a90 6e 73 74 61 6e 63 65 73 20 6f 66 20 3c 69 3e 58  nstances of <i>X
24aa0 3c 2f 69 3e 2e 20 20 5e 41 20 63 6f 6d 6d 61 20  </i>.  ^A comma 
24ab0 28 22 2c 22 29 20 69 73 20 75 73 65 64 20 61 73  (",") is used as
24ac0 20 74 68 65 20 73 65 70 61 72 61 74 6f 72 0a 20   the separator. 
24ad0 20 69 66 20 3c 69 3e 59 3c 2f 69 3e 20 69 73 20   if <i>Y</i> is 
24ae0 6f 6d 69 74 74 65 64 2e 20 20 54 68 65 20 6f 72  omitted.  The or
24af0 64 65 72 20 6f 66 20 74 68 65 20 63 6f 6e 63 61  der of the conca
24b00 74 65 6e 61 74 65 64 20 65 6c 65 6d 65 6e 74 73  tenated elements
24b10 20 69 73 0a 20 20 61 72 62 69 74 72 61 72 79 2e   is.  arbitrary.
24b20 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6d 61 78  .}..funcdef {max
24b30 28 58 29 7d 20 7b 2a 6d 61 78 41 67 67 46 75 6e  (X)} {*maxAggFun
24b40 63 20 2a 61 67 67 5f 6d 61 78 20 7b 6d 61 78 28  c *agg_max {max(
24b50 29 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  ) aggregate func
24b60 74 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68 65 20  tion}} {.  ^The 
24b70 6d 61 78 28 29 20 61 67 67 72 65 67 61 74 65 20  max() aggregate 
24b80 66 75 6e 63 74 69 6f 6e 0a 20 20 72 65 74 75 72  function.  retur
24b90 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ns the maximum v
24ba0 61 6c 75 65 20 6f 66 20 61 6c 6c 20 76 61 6c 75  alue of all valu
24bb0 65 73 20 69 6e 20 74 68 65 20 67 72 6f 75 70 2e  es in the group.
24bc0 0a 20 20 5e 54 68 65 20 6d 61 78 69 6d 75 6d 20  .  ^The maximum 
24bd0 76 61 6c 75 65 20 69 73 20 74 68 65 20 76 61 6c  value is the val
24be0 75 65 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  ue that would be
24bf0 20 72 65 74 75 72 6e 65 64 20 6c 61 73 74 20 69   returned last i
24c00 6e 20 61 6e 0a 20 20 4f 52 44 45 52 20 42 59 20  n an.  ORDER BY 
24c10 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
24c20 6d 6e 2e 20 20 5e 41 67 67 72 65 67 61 74 65 20  mn.  ^Aggregate 
24c30 6d 61 78 28 29 20 72 65 74 75 72 6e 73 20 4e 55  max() returns NU
24c40 4c 4c 20 0a 20 20 69 66 20 61 6e 64 20 6f 6e 6c  LL .  if and onl
24c50 79 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  y if there are n
24c60 6f 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65  o non-NULL value
24c70 73 20 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 0a  s in the group..
24c80 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6d 69 6e 28  }..funcdef {min(
24c90 58 29 7d 20 7b 2a 6d 69 6e 41 67 67 46 75 6e 63  X)} {*minAggFunc
24ca0 20 2a 61 67 67 5f 6d 69 6e 20 7b 6d 69 6e 28 29   *agg_min {min()
24cb0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
24cc0 69 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68 65 20 6d  ion}} {.  ^The m
24cd0 69 6e 28 29 20 61 67 67 72 65 67 61 74 65 20 66  in() aggregate f
24ce0 75 6e 63 74 69 6f 6e 0a 20 20 72 65 74 75 72 6e  unction.  return
24cf0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6e 6f  s the minimum no
24d00 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 6f 66 20  n-NULL value of 
24d10 61 6c 6c 20 76 61 6c 75 65 73 20 69 6e 20 74 68  all values in th
24d20 65 20 67 72 6f 75 70 2e 0a 20 20 5e 54 68 65 20  e group..  ^The 
24d30 6d 69 6e 69 6d 75 6d 20 76 61 6c 75 65 20 69 73  minimum value is
24d40 20 74 68 65 20 66 69 72 73 74 20 6e 6f 6e 2d 4e   the first non-N
24d50 55 4c 4c 20 76 61 6c 75 65 20 74 68 61 74 20 77  ULL value that w
24d60 6f 75 6c 64 20 61 70 70 65 61 72 0a 20 20 69 6e  ould appear.  in
24d70 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 66 20   an ORDER BY of 
24d80 74 68 65 20 63 6f 6c 75 6d 6e 2e 0a 20 20 5e 41  the column..  ^A
24d90 67 67 72 65 67 61 74 65 20 6d 69 6e 28 29 20 72  ggregate min() r
24da0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 61  eturns NULL if a
24db0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 72 65  nd only if there
24dc0 20 61 72 65 20 6e 6f 20 6e 6f 6e 2d 4e 55 4c 4c   are no non-NULL
24dd0 0a 20 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  .  values in the
24de0 20 67 72 6f 75 70 2e 0a 7d 0a 0a 66 75 6e 63 64   group..}..funcd
24df0 65 66 20 7b 73 75 6d 28 58 29 20 74 6f 74 61 6c  ef {sum(X) total
24e00 28 58 29 7d 20 7b 0a 20 20 2a 73 75 6d 46 75 6e  (X)} {.  *sumFun
24e10 63 20 2a 73 75 6d 20 2a 74 6f 74 61 6c 0a 20 20  c *sum *total.  
24e20 7b 73 75 6d 28 29 20 61 67 67 72 65 67 61 74 65  {sum() aggregate
24e30 20 66 75 6e 63 74 69 6f 6e 7d 0a 20 20 7b 74 6f   function}.  {to
24e40 74 61 6c 28 29 20 61 67 67 72 65 67 61 74 65 20  tal() aggregate 
24e50 66 75 6e 63 74 69 6f 6e 7d 0a 7d 20 7b 0a 20 20  function}.} {.  
24e60 5e 54 68 65 20 73 75 6d 28 29 20 61 6e 64 20 74  ^The sum() and t
24e70 6f 74 61 6c 28 29 20 61 67 67 72 65 67 61 74 65  otal() aggregate
24e80 20 66 75 6e 63 74 69 6f 6e 73 0a 20 20 72 65 74   functions.  ret
24e90 75 72 6e 20 73 75 6d 20 6f 66 20 61 6c 6c 20 6e  urn sum of all n
24ea0 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69  on-NULL values i
24eb0 6e 20 74 68 65 20 67 72 6f 75 70 2e 0a 20 20 5e  n the group..  ^
24ec0 49 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  If there are no 
24ed0 6e 6f 6e 2d 4e 55 4c 4c 20 69 6e 70 75 74 20 72  non-NULL input r
24ee0 6f 77 73 20 74 68 65 6e 20 73 75 6d 28 29 20 72  ows then sum() r
24ef0 65 74 75 72 6e 73 0a 20 20 4e 55 4c 4c 20 62 75  eturns.  NULL bu
24f00 74 20 74 6f 74 61 6c 28 29 20 72 65 74 75 72 6e  t total() return
24f10 73 20 30 2e 30 2e 0a 20 20 4e 55 4c 4c 20 69 73  s 0.0..  NULL is
24f20 20 6e 6f 74 20 6e 6f 72 6d 61 6c 6c 79 20 61 20   not normally a 
24f30 68 65 6c 70 66 75 6c 20 72 65 73 75 6c 74 20 66  helpful result f
24f40 6f 72 20 74 68 65 20 73 75 6d 20 6f 66 20 6e 6f  or the sum of no
24f50 20 72 6f 77 73 0a 20 20 62 75 74 20 74 68 65 20   rows.  but the 
24f60 53 51 4c 20 73 74 61 6e 64 61 72 64 20 72 65 71  SQL standard req
24f70 75 69 72 65 73 20 69 74 20 61 6e 64 20 6d 6f 73  uires it and mos
24f80 74 20 6f 74 68 65 72 0a 20 20 53 51 4c 20 64 61  t other.  SQL da
24f90 74 61 62 61 73 65 20 65 6e 67 69 6e 65 73 20 69  tabase engines i
24fa0 6d 70 6c 65 6d 65 6e 74 20 73 75 6d 28 29 20 74  mplement sum() t
24fb0 68 61 74 20 77 61 79 20 73 6f 20 53 51 4c 69 74  hat way so SQLit
24fc0 65 20 64 6f 65 73 20 69 74 20 69 6e 20 74 68 65  e does it in the
24fd0 0a 20 20 73 61 6d 65 20 77 61 79 20 69 6e 20 6f  .  same way in o
24fe0 72 64 65 72 20 74 6f 20 62 65 20 63 6f 6d 70 61  rder to be compa
24ff0 74 69 62 6c 65 2e 20 20 20 54 68 65 20 6e 6f 6e  tible.   The non
25000 2d 73 74 61 6e 64 61 72 64 20 74 6f 74 61 6c 28  -standard total(
25010 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20 69 73 20  ) function.  is 
25020 70 72 6f 76 69 64 65 64 20 61 73 20 61 20 63 6f  provided as a co
25030 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 74 6f 20  nvenient way to 
25040 77 6f 72 6b 20 61 72 6f 75 6e 64 20 74 68 69 73  work around this
25050 20 64 65 73 69 67 6e 20 70 72 6f 62 6c 65 6d 0a   design problem.
25060 20 20 69 6e 20 74 68 65 20 53 51 4c 20 6c 61 6e    in the SQL lan
25070 67 75 61 67 65 2e 3c 2f 70 3e 0a 0a 20 20 3c 70  guage.</p>..  <p
25080 3e 5e 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20  >^The result of 
25090 74 6f 74 61 6c 28 29 20 69 73 20 61 6c 77 61 79  total() is alway
250a0 73 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  s a floating poi
250b0 6e 74 20 76 61 6c 75 65 2e 0a 20 20 5e 54 68 65  nt value..  ^The
250c0 20 72 65 73 75 6c 74 20 6f 66 20 73 75 6d 28 29   result of sum()
250d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 76   is an integer v
250e0 61 6c 75 65 20 69 66 20 61 6c 6c 20 6e 6f 6e 2d  alue if all non-
250f0 4e 55 4c 4c 20 69 6e 70 75 74 73 20 61 72 65 20  NULL inputs are 
25100 69 6e 74 65 67 65 72 73 2e 0a 20 20 5e 49 66 20  integers..  ^If 
25110 61 6e 79 20 69 6e 70 75 74 20 74 6f 20 73 75 6d  any input to sum
25120 28 29 20 69 73 20 6e 65 69 74 68 65 72 20 61 6e  () is neither an
25130 20 69 6e 74 65 67 65 72 20 6f 72 20 61 20 4e 55   integer or a NU
25140 4c 4c 0a 20 20 74 68 65 6e 20 73 75 6d 28 29 20  LL.  then sum() 
25150 72 65 74 75 72 6e 73 20 61 20 66 6c 6f 61 74 69  returns a floati
25160 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 0a 20  ng point value. 
25170 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
25180 61 6e 20 61 70 70 72 6f 78 69 6d 61 74 69 6f 6e  an approximation
25190 20 74 6f 20 74 68 65 20 74 72 75 65 20 73 75 6d   to the true sum
251a0 2e 3c 2f 70 3e 0a 0a 20 20 3c 70 3e 5e 53 75 6d  .</p>..  <p>^Sum
251b0 28 29 20 77 69 6c 6c 20 74 68 72 6f 77 20 61 6e  () will throw an
251c0 20 22 69 6e 74 65 67 65 72 20 6f 76 65 72 66 6c   "integer overfl
251d0 6f 77 22 20 65 78 63 65 70 74 69 6f 6e 20 69 66  ow" exception if
251e0 20 61 6c 6c 20 69 6e 70 75 74 73 0a 20 20 61 72   all inputs.  ar
251f0 65 20 69 6e 74 65 67 65 72 73 20 6f 72 20 4e 55  e integers or NU
25200 4c 4c 0a 20 20 61 6e 64 20 61 6e 20 69 6e 74 65  LL.  and an inte
25210 67 65 72 20 6f 76 65 72 66 6c 6f 77 20 6f 63 63  ger overflow occ
25220 75 72 73 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  urs at any point
25230 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
25240 75 74 61 74 69 6f 6e 2e 0a 20 20 5e 54 6f 74 61  utation..  ^Tota
25250 6c 28 29 20 6e 65 76 65 72 20 74 68 72 6f 77 73  l() never throws
25260 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 76 65 72   an integer over
25270 66 6c 6f 77 2e 0a 7d 0a 3c 2f 74 63 6c 3e 0a 0a  flow..}.</tcl>..
25280 0a 3c 74 63 6c 3e 0a 52 65 63 75 72 73 69 76 65  .<tcl>.Recursive
25290 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 61 67  BubbleDiagram ag
252a0 67 72 65 67 61 74 65 2d 66 75 6e 63 74 69 6f 6e  gregate-function
252b0 2d 69 6e 76 6f 63 61 74 69 6f 6e 0a 3c 2f 74 63  -invocation.</tc
252c0 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20 61 67 67 72  l>..<p>.The aggr
252d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  egate functions 
252e0 73 68 6f 77 6e 20 62 65 6c 6f 77 20 61 72 65 20  shown below are 
252f0 61 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66  available by def
25300 61 75 6c 74 2e 20 20 41 64 64 69 74 69 6f 6e 61  ault.  Additiona
25310 6c 0a 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  l.aggregate func
25320 74 69 6f 6e 73 20 77 72 69 74 74 65 6e 20 69 6e  tions written in
25330 20 43 20 6d 61 79 20 62 65 20 61 64 64 65 64 20   C may be added 
25340 75 73 69 6e 67 20 74 68 65 20 0a 5b 73 71 6c 69  using the .[sqli
25350 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25360 69 6f 6e 28 29 5d 3c 2f 61 3e 0a 41 50 49 2e 3c  ion()]</a>.API.<
25370 2f 70 3e 0a 0a 3c 70 3e 0a 5e 49 6e 20 61 6e 79  /p>..<p>.^In any
25380 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
25390 69 6f 6e 20 74 68 61 74 20 74 61 6b 65 73 20 61  ion that takes a
253a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
253b0 2c 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 0a  , that argument.
253c0 63 61 6e 20 62 65 20 70 72 65 63 65 64 65 64 20  can be preceded 
253d0 62 79 20 74 68 65 20 6b 65 79 77 6f 72 64 20 44  by the keyword D
253e0 49 53 54 49 4e 43 54 2e 20 20 5e 49 6e 20 73 75  ISTINCT.  ^In su
253f0 63 68 20 63 61 73 65 73 2c 20 64 75 70 6c 69 63  ch cases, duplic
25400 61 74 65 0a 65 6c 65 6d 65 6e 74 73 20 61 72 65  ate.elements are
25410 20 66 69 6c 74 65 72 65 64 20 62 65 66 6f 72 65   filtered before
25420 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 69 6e   being passed in
25430 74 6f 20 74 68 65 20 61 67 67 72 65 67 61 74 65  to the aggregate
25440 20 66 75 6e 63 74 69 6f 6e 2e 0a 5e 46 6f 72 20   function..^For 
25450 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66 75 6e  example, the fun
25460 63 74 69 6f 6e 20 22 63 6f 75 6e 74 28 64 69 73  ction "count(dis
25470 74 69 6e 63 74 20 58 29 22 20 77 69 6c 6c 20 72  tinct X)" will r
25480 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
25490 0a 6f 66 20 64 69 73 74 69 6e 63 74 20 76 61 6c  .of distinct val
254a0 75 65 73 20 6f 66 20 63 6f 6c 75 6d 6e 20 58 20  ues of column X 
254b0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 74  instead of the t
254c0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 6e  otal number of n
254d0 6f 6e 2d 6e 75 6c 6c 0a 76 61 6c 75 65 73 20 69  on-null.values i
254e0 6e 20 63 6f 6c 75 6d 6e 20 58 2e 0a 3c 2f 70 3e  n column X..</p>
254f0 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
25500 6e 74 20 61 67 67 66 69 6c 74 65 72 20 7b 46 49  nt aggfilter {FI
25510 4c 54 45 52 20 63 6c 61 75 73 65 20 6f 6e 20 61  LTER clause on a
25520 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
25530 6e 73 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 0a 49 66  ns}</tcl>.<p>.If
25540 20 61 20 46 49 4c 54 45 52 20 63 6c 61 75 73 65   a FILTER clause
25550 20 69 73 20 70 72 6f 76 69 64 65 64 2c 20 74 68   is provided, th
25560 65 6e 20 6f 6e 6c 79 20 72 6f 77 73 20 66 6f 72  en only rows for
25570 20 77 68 69 63 68 20 74 68 65 20 3c 69 3e 65 78   which the <i>ex
25580 70 72 3c 2f 69 3e 20 69 73 0a 74 72 75 65 20 61  pr</i> is.true a
25590 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
255a0 68 65 20 61 67 67 72 65 67 61 74 65 2e 0a 3c 2f  he aggregate..</
255b0 70 3e 0a 0a 3c 74 63 6c 3e 0a 73 65 74 20 6c 78  p>..<tcl>.set lx
255c0 20 7b 7d 0a 66 6f 72 65 61 63 68 20 62 61 73 65   {}.foreach base
255d0 73 79 6e 74 61 78 20 5b 61 72 72 61 79 20 6e 61  syntax [array na
255e0 6d 65 73 20 63 6f 72 65 66 75 6e 63 73 65 74 5d  mes corefuncset]
255f0 20 7b 0a 20 20 66 6f 72 65 61 63 68 20 7b 73 79   {.  foreach {sy
25600 6e 74 61 78 20 6b 65 79 77 6f 72 64 73 20 64 65  ntax keywords de
25610 73 63 7d 20 24 63 6f 72 65 66 75 6e 63 73 65 74  sc} $corefuncset
25620 28 24 62 61 73 65 73 79 6e 74 61 78 29 20 62 72  ($basesyntax) br
25630 65 61 6b 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b  eak.  regexp {^[
25640 61 2d 7a 5f 5d 2b 7d 20 24 62 61 73 65 73 79 6e  a-z_]+} $basesyn
25650 74 61 78 20 66 72 61 67 6d 65 6e 74 0a 20 20 66  tax fragment.  f
25660 6f 72 65 61 63 68 20 63 6f 72 65 73 79 6e 74 61  oreach coresynta
25670 78 20 24 73 79 6e 74 61 78 20 7b 0a 20 20 20 20  x $syntax {.    
25680 6c 61 70 70 65 6e 64 20 6c 78 20 5b 6c 69 73 74  lappend lx [list
25690 20 24 66 72 61 67 6d 65 6e 74 20 24 63 6f 72 65   $fragment $core
256a0 73 79 6e 74 61 78 20 30 5d 0a 20 20 7d 0a 7d 0a  syntax 0].  }.}.
256b0 68 64 5f 6c 69 73 74 5f 6f 66 5f 6c 69 6e 6b 73  hd_list_of_links
256c0 20 7b 7d 20 32 32 35 20 5b 6c 73 6f 72 74 20 2d   {} 225 [lsort -
256d0 69 6e 64 65 78 20 31 20 24 6c 78 5d 0a 0a 68 64  index 1 $lx]..hd
256e0 5f 70 75 74 73 6e 6c 20 22 3c 68 72 20 63 6c 61  _putsnl "<hr cla
256f0 73 73 3d 27 78 68 72 27 3e 22 0a 68 64 5f 70 75  ss='xhr'>".hd_pu
25700 74 73 6e 6c 20 22 3c 64 6c 3e 22 0a 66 6f 72 65  tsnl "<dl>".fore
25710 61 63 68 20 62 61 73 65 73 79 6e 74 61 78 20 5b  ach basesyntax [
25720 6c 73 6f 72 74 20 5b 61 72 72 61 79 20 6e 61 6d  lsort [array nam
25730 65 73 20 63 6f 72 65 66 75 6e 63 73 65 74 5d 5d  es corefuncset]]
25740 20 7b 0a 20 20 66 6f 72 65 61 63 68 20 7b 73 79   {.  foreach {sy
25750 6e 74 61 78 20 6b 65 79 77 6f 72 64 73 20 64 65  ntax keywords de
25760 73 63 7d 20 24 63 6f 72 65 66 75 6e 63 73 65 74  sc} $corefuncset
25770 28 24 62 61 73 65 73 79 6e 74 61 78 29 20 62 72  ($basesyntax) br
25780 65 61 6b 0a 20 20 72 65 67 73 75 62 20 2d 61 6c  eak.  regsub -al
25790 6c 20 7b 5c 73 2b 7d 20 5b 73 74 72 69 6e 67 20  l {\s+} [string 
257a0 74 72 69 6d 20 24 73 79 6e 74 61 78 5d 20 7b 3c  trim $syntax] {<
257b0 62 72 20 2f 3e 7d 20 73 79 6e 74 61 78 0a 20 20  br />} syntax.  
257c0 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5c 28 28  regsub -all {\((
257d0 5b 5e 2a 29 5d 2b 29 5c 29 7d 20 24 73 79 6e 74  [^*)]+)\)} $synt
257e0 61 78 20 7b 28 3c 69 3e 5c 31 3c 2f 69 3e 29 7d  ax {(<i>\1</i>)}
257f0 20 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75 62   syntax.  regsub
25800 20 2d 61 6c 6c 20 7b 2c 7d 20 24 73 79 6e 74 61   -all {,} $synta
25810 78 20 7b 3c 2f 69 3e 2c 3c 69 3e 7d 20 73 79 6e  x {</i>,<i>} syn
25820 74 61 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c  tax.  regsub -al
25830 6c 20 7b 3c 69 3e 5c 2e 5c 2e 5c 2e 3c 2f 69 3e  l {<i>\.\.\.</i>
25840 7d 20 24 73 79 6e 74 61 78 20 7b 2e 2e 2e 7d 20  } $syntax {...} 
25850 73 79 6e 74 61 78 0a 20 20 72 65 67 65 78 70 20  syntax.  regexp 
25860 7b 5e 5b 61 2d 7a 5d 2b 7d 20 24 62 61 73 65 73  {^[a-z]+} $bases
25870 79 6e 74 61 78 20 66 72 61 67 6d 65 6e 74 0a 20  yntax fragment. 
25880 20 69 66 20 7b 5b 6c 6c 65 6e 67 74 68 20 24 6b   if {[llength $k
25890 65 79 77 6f 72 64 73 5d 3d 3d 30 7d 20 7b 0a 20  eywords]==0} {. 
258a0 20 20 20 72 65 67 65 78 70 20 7b 5b 61 2d 7a 5f     regexp {[a-z_
258b0 5d 2b 7d 20 24 73 79 6e 74 61 78 20 6e 61 6d 65  ]+} $syntax name
258c0 0a 20 20 20 20 68 64 5f 66 72 61 67 6d 65 6e 74  .    hd_fragment
258d0 20 24 6e 61 6d 65 20 2a 24 6e 61 6d 65 20 22 24   $name *$name "$
258e0 7b 6e 61 6d 65 7d 28 29 20 53 51 4c 20 66 75 6e  {name}() SQL fun
258f0 63 74 69 6f 6e 22 0a 20 20 7d 20 65 6c 73 65 20  ction".  } else 
25900 7b 0a 20 20 20 20 73 65 74 20 66 72 61 67 6e 61  {.    set fragna
25910 6d 65 20 5b 6c 69 6e 64 65 78 20 24 6b 65 79 77  me [lindex $keyw
25920 6f 72 64 73 20 30 5d 0a 20 20 20 20 72 65 67 73  ords 0].    regs
25930 75 62 20 2d 61 6c 6c 20 7b 5b 5e 61 2d 7a 5d 7d  ub -all {[^a-z]}
25940 20 24 66 72 61 67 6e 61 6d 65 20 7b 7d 20 66 72   $fragname {} fr
25950 61 67 6e 61 6d 65 0a 20 20 20 20 68 64 5f 66 72  agname.    hd_fr
25960 61 67 6d 65 6e 74 20 24 66 72 61 67 6e 61 6d 65  agment $fragname
25970 0a 20 20 20 20 65 76 61 6c 20 68 64 5f 6b 65 79  .    eval hd_key
25980 77 6f 72 64 73 20 5b 73 74 72 69 6e 67 20 6d 61  words [string ma
25990 70 20 7b 5c 6e 20 7b 20 7d 7d 20 24 6b 65 79 77  p {\n { }} $keyw
259a0 6f 72 64 73 5d 0a 20 20 7d 0a 20 20 68 64 5f 70  ords].  }.  hd_p
259b0 75 74 73 20 22 3c 64 74 3e 3c 70 3e 3c 62 3e 24  uts "<dt><p><b>$
259c0 73 79 6e 74 61 78 3c 2f 62 3e 3c 2f 64 74 3e 22  syntax</b></dt>"
259d0 0a 20 20 68 64 5f 72 65 73 6f 6c 76 65 20 22 3c  .  hd_resolve "<
259e0 64 64 3e 3c 70 3e 24 64 65 73 63 3c 2f 64 64 3e  dd><p>$desc</dd>
259f0 5c 6e 22 0a 7d 0a 68 64 5f 70 75 74 73 6e 6c 20  \n".}.hd_putsnl 
25a00 22 3c 2f 64 6c 3e 22 0a 0a 23 23 23 23 23 23 23  "</dl>"..#######
25a10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25a20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25a30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25a40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25a50 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
25a60 49 4e 53 45 52 54 20 69 6e 73 65 72 74 20 7b 49  INSERT insert {I
25a70 4e 53 45 52 54 20 2a 49 4e 53 45 52 54 73 7d 0a  NSERT *INSERTs}.
25a80 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65  .RecursiveBubble
25a90 44 69 61 67 72 61 6d 20 69 6e 73 65 72 74 2d 73  Diagram insert-s
25aa0 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54  tmt.</tcl>..<p>T
25ab0 68 65 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d  he INSERT statem
25ac0 65 6e 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 72  ent comes in thr
25ad0 65 65 20 62 61 73 69 63 20 66 6f 72 6d 73 2e 20  ee basic forms. 
25ae0 20 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 3c 62   .<ol>.<li><p><b
25af0 3e 49 4e 53 45 52 54 20 49 4e 54 4f 20 3c 2f 62  >INSERT INTO </b
25b00 3e 3c 69 3e 74 61 62 6c 65 3c 2f 69 3e 3c 62 3e  ><i>table</i><b>
25b10 20 56 41 4c 55 45 53 28 2e 2e 2e 29 3b 3c 2f 62   VALUES(...);</b
25b20 3e 0a 3c 70 3e 5e 54 68 65 20 66 69 72 73 74 20  >.<p>^The first 
25b30 66 6f 72 6d 20 28 77 69 74 68 20 74 68 65 20 22  form (with the "
25b40 56 41 4c 55 45 53 22 20 6b 65 79 77 6f 72 64 29  VALUES" keyword)
25b50 20 63 72 65 61 74 65 73 20 6f 6e 65 20 6f 72 20   creates one or 
25b60 6d 6f 72 65 0a 6e 65 77 20 72 6f 77 73 20 69 6e  more.new rows in
25b70 0a 61 6e 20 65 78 69 73 74 69 6e 67 20 74 61 62  .an existing tab
25b80 6c 65 2e 20 5e 49 66 20 74 68 65 20 3c 79 79 74  le. ^If the <yyt
25b90 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c  erm>column-name<
25ba0 2f 79 79 74 65 72 6d 3e 20 6c 69 73 74 20 61 66  /yyterm> list af
25bb0 74 65 72 0a 3c 79 79 74 65 72 6d 3e 74 61 62 6c  ter.<yyterm>tabl
25bc0 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  e-name</yyterm> 
25bd0 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 6e 20  is omitted then 
25be0 74 68 65 20 6e 75 6d 62 65 72 0a 6f 66 20 76 61  the number.of va
25bf0 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e  lues inserted in
25c00 74 6f 20 65 61 63 68 20 72 6f 77 0a 6d 75 73 74  to each row.must
25c10 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20   be the same as 
25c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
25c30 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62  lumns in the tab
25c40 6c 65 2e 20 5e 49 6e 20 74 68 69 73 20 63 61 73  le. ^In this cas
25c50 65 0a 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e.the result of 
25c60 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 6c  evaluating the l
25c70 65 66 74 2d 6d 6f 73 74 20 65 78 70 72 65 73 73  eft-most express
25c80 69 6f 6e 20 66 72 6f 6d 20 65 61 63 68 20 74 65  ion from each te
25c90 72 6d 20 6f 66 0a 74 68 65 20 56 41 4c 55 45 53  rm of.the VALUES
25ca0 20 6c 69 73 74 20 69 73 20 69 6e 73 65 72 74 65   list is inserte
25cb0 64 20 69 6e 74 6f 20 74 68 65 20 6c 65 66 74 2d  d into the left-
25cc0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 65  most column of e
25cd0 61 63 68 20 6e 65 77 20 72 6f 77 2c 0a 61 6e 64  ach new row,.and
25ce0 20 73 6f 20 66 6f 72 74 68 20 66 6f 72 20 65 61   so forth for ea
25cf0 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 65 78  ch subsequent ex
25d00 70 72 65 73 73 69 6f 6e 2e 20 5e 49 66 20 61 20  pression. ^If a 
25d10 3c 79 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e  <yyterm>column-n
25d20 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 0a 6c 69 73  ame</yyterm>.lis
25d30 74 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  t is specified, 
25d40 74 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  then the number 
25d50 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 65 61 63  of values in eac
25d60 68 20 74 65 72 6d 20 6f 66 20 74 68 65 0a 56 41  h term of the.VA
25d70 4c 55 45 20 6c 69 73 74 20 6d 75 73 74 20 6d 61  LUE list must ma
25d80 74 63 68 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  tch the number o
25d90 66 0a 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  f.specified colu
25da0 6d 6e 73 2e 20 5e 45 61 63 68 20 6f 66 20 74 68  mns. ^Each of th
25db0 65 20 6e 61 6d 65 64 20 63 6f 6c 75 6d 6e 73 20  e named columns 
25dc0 6f 66 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69  of the new row i
25dd0 73 20 70 6f 70 75 6c 61 74 65 64 0a 77 69 74 68  s populated.with
25de0 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
25df0 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 63  evaluating the c
25e00 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 56 41 4c  orresponding VAL
25e10 55 45 53 20 65 78 70 72 65 73 73 69 6f 6e 2e 20  UES expression. 
25e20 5e 54 61 62 6c 65 0a 63 6f 6c 75 6d 6e 73 20 74  ^Table.columns t
25e30 68 61 74 20 64 6f 20 6e 6f 74 20 61 70 70 65 61  hat do not appea
25e40 72 20 69 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  r in the column 
25e50 6c 69 73 74 20 61 72 65 20 70 6f 70 75 6c 61 74  list are populat
25e60 65 64 20 77 69 74 68 20 74 68 65 20 0a 5b 64 65  ed with the .[de
25e70 66 61 75 6c 74 20 63 6f 6c 75 6d 6e 20 76 61 6c  fault column val
25e80 75 65 5d 20 28 73 70 65 63 69 66 69 65 64 20 61  ue] (specified a
25e90 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 5b 43  s part of the [C
25ea0 52 45 41 54 45 20 54 41 42 4c 45 5d 20 73 74 61  REATE TABLE] sta
25eb0 74 65 6d 65 6e 74 29 2c 20 6f 72 0a 77 69 74 68  tement), or.with
25ec0 20 4e 55 4c 4c 20 69 66 20 6e 6f 20 5b 64 65 66   NULL if no [def
25ed0 61 75 6c 74 20 76 61 6c 75 65 5d 20 69 73 20 73  ault value] is s
25ee0 70 65 63 69 66 69 65 64 2e 0a 0a 3c 6c 69 3e 3c  pecified...<li><
25ef0 70 3e 3c 62 3e 49 4e 53 45 52 54 20 49 4e 54 4f  p><b>INSERT INTO
25f00 20 3c 2f 62 3e 3c 69 3e 74 61 62 6c 65 3c 2f 69   </b><i>table</i
25f10 3e 3c 62 3e 20 53 45 4c 45 43 54 20 2e 2e 2e 3b  ><b> SELECT ...;
25f20 3c 2f 62 3e 0a 3c 70 3e 54 68 65 20 73 65 63 6f  </b>.<p>The seco
25f30 6e 64 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 49  nd form of the I
25f40 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20  NSERT statement 
25f50 63 6f 6e 74 61 69 6e 73 20 61 20 5b 53 45 4c 45  contains a [SELE
25f60 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 0a 69 6e  CT] statement.in
25f70 73 74 65 61 64 20 6f 66 20 61 20 56 41 4c 55 45  stead of a VALUE
25f80 53 20 63 6c 61 75 73 65 2e 20 5e 41 20 6e 65 77  S clause. ^A new
25f90 20 65 6e 74 72 79 20 69 73 20 69 6e 73 65 72 74   entry is insert
25fa0 65 64 20 69 6e 74 6f 20 74 68 65 20 74 61 62 6c  ed into the tabl
25fb0 65 20 66 6f 72 20 65 61 63 68 0a 72 6f 77 20 6f  e for each.row o
25fc0 66 20 64 61 74 61 20 72 65 74 75 72 6e 65 64 20  f data returned 
25fd0 62 79 20 65 78 65 63 75 74 69 6e 67 20 74 68 65  by executing the
25fe0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
25ff0 74 2e 20 5e 49 66 20 61 20 63 6f 6c 75 6d 6e 2d  t. ^If a column-
26000 6c 69 73 74 20 69 73 0a 73 70 65 63 69 66 69 65  list is.specifie
26010 64 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  d, the number of
26020 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
26030 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 53 45  result of the SE
26040 4c 45 43 54 20 6d 75 73 74 20 62 65 20 74 68 65  LECT must be the
26050 20 73 61 6d 65 0a 61 73 20 74 68 65 20 6e 75 6d   same.as the num
26060 62 65 72 20 6f 66 20 69 74 65 6d 73 20 69 6e 20  ber of items in 
26070 74 68 65 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 2e  the column-list.
26080 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20   ^Otherwise, if 
26090 6e 6f 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 20 69  no column-list i
260a0 73 0a 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s.specified, the
260b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
260c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
260d0 20 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20 6d   of the SELECT m
260e0 75 73 74 20 62 65 20 74 68 65 20 73 61 6d 65 0a  ust be the same.
260f0 61 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  as the number of
26100 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
26110 74 61 62 6c 65 2e 20 5e 41 6e 79 20 53 45 4c 45  table. ^Any SELE
26120 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  CT statement, in
26130 63 6c 75 64 69 6e 67 0a 5b 63 6f 6d 70 6f 75 6e  cluding.[compoun
26140 64 20 53 45 4c 45 43 54 73 5d 20 61 6e 64 20 53  d SELECTs] and S
26150 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
26160 20 77 69 74 68 20 5b 4f 52 44 45 52 20 42 59 5d   with [ORDER BY]
26170 20 61 6e 64 2f 6f 72 20 5b 4c 49 4d 49 54 5d 20   and/or [LIMIT] 
26180 63 6c 61 75 73 65 73 2c 20 0a 6d 61 79 20 62 65  clauses, .may be
26190 20 75 73 65 64 20 69 6e 20 61 6e 20 49 4e 53 45   used in an INSE
261a0 52 54 20 73 74 61 74 65 6d 65 6e 74 20 6f 66 20  RT statement of 
261b0 74 68 69 73 20 66 6f 72 6d 2e 0a 0a 3c 70 3e 54  this form...<p>T
261c0 6f 20 61 76 6f 69 64 20 61 20 70 61 72 73 69 6e  o avoid a parsin
261d0 67 20 61 6d 62 69 67 75 69 74 79 2c 20 74 68 65  g ambiguity, the
261e0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
261f0 74 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  t should always.
26200 63 6f 6e 74 61 69 6e 20 61 20 57 48 45 52 45 20  contain a WHERE 
26210 63 6c 61 75 73 65 2c 20 65 76 65 6e 20 69 66 20  clause, even if 
26220 74 68 61 74 20 63 6c 61 75 73 65 20 69 73 20 73  that clause is s
26230 69 6d 70 6c 79 20 22 57 48 45 52 45 20 74 72 75  imply "WHERE tru
26240 65 22 2c 0a 69 66 20 74 68 65 20 5b 75 70 73 65  e",.if the [upse
26250 72 74 2d 63 6c 61 75 73 65 5d 20 69 73 20 70 72  rt-clause] is pr
26260 65 73 65 6e 74 2e 20 20 57 69 74 68 6f 75 74 20  esent.  Without 
26270 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
26280 2c 20 74 68 65 0a 70 61 72 73 65 72 20 64 6f 65  , the.parser doe
26290 73 20 6e 6f 74 20 6b 6e 6f 77 20 69 66 20 74 68  s not know if th
262a0 65 20 74 6f 6b 65 6e 20 22 4f 4e 22 20 69 73 20  e token "ON" is 
262b0 70 61 72 74 20 6f 66 20 61 20 6a 6f 69 6e 20 63  part of a join c
262c0 6f 6e 73 74 72 61 69 6e 74 0a 6f 6e 20 74 68 65  onstraint.on the
262d0 20 53 45 4c 45 43 54 2c 20 6f 72 20 74 68 65 20   SELECT, or the 
262e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68 65  beginning of the
262f0 20 5b 75 70 73 65 72 74 2d 63 6c 61 75 73 65 5d   [upsert-clause]
26300 2e 0a 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 49 4e 53  ...<li><p><b>INS
26310 45 52 54 20 49 4e 54 4f 20 3c 2f 62 3e 3c 69 3e  ERT INTO </b><i>
26320 74 61 62 6c 65 3c 2f 69 3e 3c 62 3e 20 44 45 46  table</i><b> DEF
26330 41 55 4c 54 20 56 41 4c 55 45 53 3b 3c 2f 62 3e  AULT VALUES;</b>
26340 0a 3c 70 3e 54 68 65 20 74 68 69 72 64 20 66 6f  .<p>The third fo
26350 72 6d 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20  rm of an INSERT 
26360 73 74 61 74 65 6d 65 6e 74 20 69 73 20 77 69 74  statement is wit
26370 68 20 44 45 46 41 55 4c 54 20 56 41 4c 55 45 53  h DEFAULT VALUES
26380 2e 0a 5e 28 54 68 65 20 49 4e 53 45 52 54 20 2e  ..^(The INSERT .
26390 2e 2e 20 44 45 46 41 55 4c 54 20 56 41 4c 55 45  .. DEFAULT VALUE
263a0 53 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 73 65  S statement inse
263b0 72 74 73 20 61 20 73 69 6e 67 6c 65 20 6e 65 77  rts a single new
263c0 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 0a 6e 61   row into the.na
263d0 6d 65 64 20 74 61 62 6c 65 2e 29 5e 20 5e 45 61  med table.)^ ^Ea
263e0 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  ch column of the
263f0 20 6e 65 77 20 72 6f 77 20 69 73 20 70 6f 70 75   new row is popu
26400 6c 61 74 65 64 20 77 69 74 68 20 69 74 73 20 0a  lated with its .
26410 5b 64 65 66 61 75 6c 74 20 76 61 6c 75 65 5d 2c  [default value],
26420 20 6f 72 20 77 69 74 68 20 61 20 4e 55 4c 4c 20   or with a NULL 
26430 69 66 20 6e 6f 20 64 65 66 61 75 6c 74 20 76 61  if no default va
26440 6c 75 65 20 69 73 20 73 70 65 63 69 66 69 65 64  lue is specified
26450 20 0a 61 73 20 70 61 72 74 20 6f 66 20 74 68 65   .as part of the
26460 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69   column definiti
26470 6f 6e 20 69 6e 20 74 68 65 20 5b 43 52 45 41 54  on in the [CREAT
26480 45 20 54 41 42 4c 45 5d 20 73 74 61 74 65 6d 65  E TABLE] stateme
26490 6e 74 2e 0a 54 68 65 20 5b 75 70 73 65 72 74 2d  nt..The [upsert-
264a0 63 6c 61 75 73 65 5d 20 69 73 20 6e 6f 74 20 73  clause] is not s
264b0 75 70 70 6f 72 74 65 64 20 61 66 74 65 72 20 44  upported after D
264c0 45 46 41 55 4c 54 20 56 41 4c 55 45 53 2e 0a 0a  EFAULT VALUES...
264d0 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 5e 54 68 65 20  </ol>..<p>.^The 
264e0 69 6e 69 74 69 61 6c 20 22 49 4e 53 45 52 54 22  initial "INSERT"
264f0 20 6b 65 79 77 6f 72 64 20 63 61 6e 20 62 65 20   keyword can be 
26500 72 65 70 6c 61 63 65 64 20 62 79 0a 22 52 45 50  replaced by."REP
26510 4c 41 43 45 22 20 6f 72 20 22 49 4e 53 45 52 54  LACE" or "INSERT
26520 20 4f 52 20 3c 69 3e 61 63 74 69 6f 6e 3c 2f 69   OR <i>action</i
26530 3e 22 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  >" to specify an
26540 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 63 6f 6e   alternative.con
26550 73 74 72 61 69 6e 74 20 5b 4f 4e 20 43 4f 4e 46  straint [ON CONF
26560 4c 49 43 54 7c 63 6f 6e 66 6c 69 63 74 20 72 65  LICT|conflict re
26570 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74  solution algorit
26580 68 6d 5d 20 74 6f 20 75 73 65 20 64 75 72 69 6e  hm] to use durin
26590 67 20 0a 74 68 61 74 20 6f 6e 65 20 49 4e 53 45  g .that one INSE
265a0 52 54 20 63 6f 6d 6d 61 6e 64 2e 0a 46 6f 72 20  RT command..For 
265b0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
265c0 74 68 20 4d 79 53 51 4c 2c 20 5e 74 68 65 20 70  th MySQL, ^the p
265d0 61 72 73 65 72 20 61 6c 6c 6f 77 73 20 74 68 65  arser allows the
265e0 20 75 73 65 20 6f 66 20 74 68 65 0a 73 69 6e 67   use of the.sing
265f0 6c 65 20 6b 65 79 77 6f 72 64 20 3c 61 20 68 72  le keyword <a hr
26600 65 66 3d 22 6c 61 6e 67 5f 72 65 70 6c 61 63 65  ef="lang_replace
26610 2e 68 74 6d 6c 22 3e 52 45 50 4c 41 43 45 3c 2f  .html">REPLACE</
26620 61 3e 20 61 73 20 61 6e 20 0a 61 6c 69 61 73 20  a> as an .alias 
26630 66 6f 72 20 22 49 4e 53 45 52 54 20 4f 52 20 52  for "INSERT OR R
26640 45 50 4c 41 43 45 22 2e 0a 0a 3c 70 3e 5e 28 54  EPLACE"...<p>^(T
26650 68 65 20 6f 70 74 69 6f 6e 61 6c 20 22 3c 69 3e  he optional "<i>
26660 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69 3e 3c  schema-name</i><
26670 62 3e 2e 3c 2f 62 3e 22 20 70 72 65 66 69 78 20  b>.</b>" prefix 
26680 6f 6e 20 74 68 65 20 0a 3c 79 79 74 65 72 6d 3e  on the .<yyterm>
26690 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65  table-name</yyte
266a0 72 6d 3e 0a 69 73 20 73 75 70 70 6f 72 74 65 64  rm>.is supported
266b0 20 66 6f 72 20 74 6f 70 2d 6c 65 76 65 6c 20 49   for top-level I
266c0 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73  NSERT statements
266d0 20 6f 6e 6c 79 2e 29 5e 20 20 5e 54 68 65 20 74   only.)^  ^The t
266e0 61 62 6c 65 20 6e 61 6d 65 20 6d 75 73 74 20 62  able name must b
266f0 65 0a 75 6e 71 75 61 6c 69 66 69 65 64 20 66 6f  e.unqualified fo
26700 72 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65  r INSERT stateme
26710 6e 74 73 20 74 68 61 74 20 6f 63 63 75 72 20 77  nts that occur w
26720 69 74 68 69 6e 20 5b 43 52 45 41 54 45 20 54 52  ithin [CREATE TR
26730 49 47 47 45 52 5d 20 73 74 61 74 65 6d 65 6e 74  IGGER] statement
26740 73 2e 0a 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 74  s..^Similarly, t
26750 68 65 20 22 44 45 46 41 55 4c 54 20 56 41 4c 55  he "DEFAULT VALU
26760 45 53 22 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ES" form of the 
26770 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74  INSERT statement
26780 20 69 73 20 73 75 70 70 6f 72 74 65 64 20 66 6f   is supported fo
26790 72 0a 74 6f 70 2d 6c 65 76 65 6c 20 49 4e 53 45  r.top-level INSE
267a0 52 54 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  RT statements on
267b0 6c 79 20 61 6e 64 20 6e 6f 74 20 66 6f 72 20 49  ly and not for I
267c0 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73  NSERT statements
267d0 20 77 69 74 68 69 6e 0a 74 72 69 67 67 65 72 73   within.triggers
267e0 2e 0a 3c 70 3e 0a 0a 3c 70 3e 54 68 65 20 6f 70  ..<p>..<p>The op
267f0 74 69 6f 6e 61 6c 20 22 41 53 20 3c 79 79 74 65  tional "AS <yyte
26800 72 6d 3e 61 6c 69 61 73 3c 2f 79 79 74 65 72 6d  rm>alias</yyterm
26810 3e 22 20 70 68 72 61 73 65 20 70 72 6f 76 69 64  >" phrase provid
26820 65 73 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  es an alternativ
26830 65 0a 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 74  e.name for the t
26840 61 62 6c 65 20 69 6e 74 6f 20 77 68 69 63 68 20  able into which 
26850 63 6f 6e 74 65 6e 74 20 69 73 20 62 65 69 6e 67  content is being
26860 20 69 6e 73 65 72 74 65 64 2e 20 20 54 68 65 20   inserted.  The 
26870 61 6c 69 61 73 20 6e 61 6d 65 0a 63 61 6e 20 62  alias name.can b
26880 65 20 75 73 65 64 20 77 69 74 68 69 6e 20 57 48  e used within WH
26890 45 52 45 20 61 6e 64 20 53 45 54 20 63 6c 61 75  ERE and SET clau
268a0 73 65 73 20 6f 66 20 74 68 65 20 5b 55 50 53 45  ses of the [UPSE
268b0 52 54 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  RT].  If there i
268c0 73 20 6e 6f 0a 5b 75 70 73 65 72 74 2d 63 6c 61  s no.[upsert-cla
268d0 75 73 65 5d 2c 20 74 68 65 6e 20 74 68 65 20 3c  use], then the <
268e0 79 79 74 65 72 6d 3e 61 6c 69 61 73 3c 2f 79 79  yyterm>alias</yy
268f0 74 65 72 6d 3e 20 69 73 20 70 6f 69 6e 74 6c 65  term> is pointle
26900 73 73 2c 20 62 75 74 20 61 6c 73 6f 0a 68 61 72  ss, but also.har
26910 6d 6c 65 73 73 2e 0a 0a 3c 70 3e 53 65 65 20 74  mless...<p>See t
26920 68 65 20 73 65 70 61 72 61 74 65 20 5b 55 50 53  he separate [UPS
26930 45 52 54 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ERT] documentati
26940 6f 6e 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  on for the addit
26950 69 6f 6e 61 6c 20 74 72 61 69 6c 69 6e 67 0a 73  ional trailing.s
26960 79 6e 74 61 78 20 74 68 61 74 20 63 61 6e 20 63  yntax that can c
26970 61 75 73 65 20 61 6e 20 49 4e 53 45 52 54 20 74  ause an INSERT t
26980 6f 20 62 65 68 61 76 65 20 61 73 20 61 6e 20 55  o behave as an U
26990 50 44 41 54 45 20 69 66 20 74 68 65 20 49 4e 53  PDATE if the INS
269a0 45 52 54 20 77 6f 75 6c 64 0a 6f 74 68 65 72 77  ERT would.otherw
269b0 69 73 65 20 76 69 6f 6c 61 74 65 20 61 20 75 6e  ise violate a un
269c0 69 71 75 65 6e 65 73 73 20 63 6f 6e 73 74 72 61  iqueness constra
269d0 69 6e 74 2e 20 20 54 68 65 20 5b 75 70 73 65 72  int.  The [upser
269e0 74 20 63 6c 61 75 73 65 5d 20 69 73 20 6e 6f 74  t clause] is not
269f0 0a 61 6c 6c 6f 77 65 64 20 6f 6e 20 61 6e 20 22  .allowed on an "
26a00 49 4e 53 45 52 54 20 2e 2e 2e 20 44 45 46 41 55  INSERT ... DEFAU
26a10 4c 54 20 56 41 4c 55 45 53 22 2e 0a 0a 0a 3c 74  LT VALUES"....<t
26a20 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23  cl>.############
26a30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26a40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26a50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26a60 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26a70 23 23 0a 53 65 63 74 69 6f 6e 20 75 70 73 65 72  ##.Section upser
26a80 74 20 55 50 53 45 52 54 20 7b 55 50 53 45 52 54  t UPSERT {UPSERT
26a90 20 7b 75 70 73 65 72 74 20 63 6c 61 75 73 65 7d   {upsert clause}
26aa0 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
26ab0 6c 65 44 69 61 67 72 61 6d 20 75 70 73 65 72 74  leDiagram upsert
26ac0 2d 63 6c 61 75 73 65 0a 3c 2f 74 63 6c 3e 0a 0a  -clause.</tcl>..
26ad0 3c 70 3e 55 50 53 45 52 54 20 69 73 20 61 20 73  <p>UPSERT is a s
26ae0 70 65 63 69 61 6c 20 73 79 6e 74 61 78 20 61 64  pecial syntax ad
26af0 64 69 74 69 6f 6e 20 74 6f 20 5b 49 4e 53 45 52  dition to [INSER
26b00 54 5d 20 74 68 61 74 20 63 61 75 73 65 73 20 74  T] that causes t
26b10 68 65 0a 49 4e 53 45 52 54 20 74 6f 20 62 65 68  he.INSERT to beh
26b20 61 76 65 20 61 73 20 61 6e 20 5b 55 50 44 41 54  ave as an [UPDAT
26b30 45 5d 20 6f 72 20 61 20 6e 6f 2d 6f 70 20 69 66  E] or a no-op if
26b40 20 74 68 65 20 49 4e 53 45 52 54 20 77 6f 75 6c   the INSERT woul
26b50 64 20 76 69 6f 6c 61 74 65 0a 61 20 75 6e 69 71  d violate.a uniq
26b60 75 65 6e 65 73 73 20 63 6f 6e 73 74 72 61 69 6e  ueness constrain
26b70 74 2e 0a 55 50 53 45 52 54 20 69 73 20 6e 6f 74  t..UPSERT is not
26b80 20 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 20 20   standard SQL.  
26b90 55 50 53 45 52 54 20 69 6e 20 53 51 4c 69 74 65  UPSERT in SQLite
26ba0 20 66 6f 6c 6c 6f 77 73 20 74 68 65 0a 73 79 6e   follows the.syn
26bb0 74 61 78 20 65 73 74 61 62 6c 69 73 68 65 64 20  tax established 
26bc0 62 79 20 50 6f 73 74 67 72 65 53 51 4c 2e 0a 55  by PostgreSQL..U
26bd0 50 53 45 52 54 20 73 79 6e 74 61 78 20 77 61 73  PSERT syntax was
26be0 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
26bf0 20 77 69 74 68 20 76 65 72 73 69 6f 6e 20 33 2e   with version 3.
26c00 32 34 2e 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e  24.0 ([dateof:3.
26c10 32 34 2e 30 5d 29 2e 0a 0a 3c 70 3e 41 6e 20 55  24.0])...<p>An U
26c20 50 53 45 52 54 20 69 73 20 61 6e 20 6f 72 64 69  PSERT is an ordi
26c30 6e 61 72 79 20 5b 49 4e 53 45 52 54 5d 20 73 74  nary [INSERT] st
26c40 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
26c50 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 74 68 65 20  followed by.the 
26c60 73 70 65 63 69 61 6c 20 4f 4e 20 43 4f 4e 46 4c  special ON CONFL
26c70 49 43 54 20 63 6c 61 75 73 65 20 73 68 6f 77 6e  ICT clause shown
26c80 20 61 62 6f 76 65 2e 0a 0a 3c 70 3e 54 68 65 20   above...<p>The 
26c90 73 79 6e 74 61 78 20 74 68 61 74 20 6f 63 63 75  syntax that occu
26ca0 72 73 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  rs in between th
26cb0 65 20 22 4f 4e 20 43 4f 4e 46 4c 49 43 54 22 20  e "ON CONFLICT" 
26cc0 61 6e 64 20 22 44 4f 22 20 6b 65 79 77 6f 72 64  and "DO" keyword
26cd0 73 0a 69 73 20 63 61 6c 6c 65 64 20 74 68 65 20  s.is called the 
26ce0 22 63 6f 6e 66 6c 69 63 74 20 74 61 72 67 65 74  "conflict target
26cf0 22 2e 20 20 54 68 65 20 63 6f 6e 66 6c 69 63 74  ".  The conflict
26d00 20 74 61 72 67 65 74 20 73 70 65 63 69 66 69 65   target specifie
26d10 73 20 61 20 73 70 65 63 69 66 69 63 0a 75 6e 69  s a specific.uni
26d20 71 75 65 6e 65 73 73 20 63 6f 6e 73 74 72 61 69  queness constrai
26d30 6e 74 20 74 68 61 74 20 77 69 6c 6c 20 74 72 69  nt that will tri
26d40 67 67 65 72 20 74 68 65 20 75 70 73 65 72 74 2e  gger the upsert.
26d50 20 20 54 68 65 20 63 6f 6e 66 6c 69 63 74 20 74    The conflict t
26d60 61 72 67 65 74 0a 69 73 20 72 65 71 75 69 72 65  arget.is require
26d70 64 20 66 6f 72 20 44 4f 20 55 50 44 41 54 45 20  d for DO UPDATE 
26d80 75 70 73 65 72 74 73 2c 20 62 75 74 20 69 73 20  upserts, but is 
26d90 6f 70 74 69 6f 6e 61 6c 20 66 6f 72 20 44 4f 20  optional for DO 
26da0 4e 4f 54 48 49 4e 47 2e 20 20 57 68 65 6e 0a 74  NOTHING.  When.t
26db0 68 65 20 63 6f 6e 66 6c 69 63 74 20 74 61 72 67  he conflict targ
26dc0 65 74 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 74  et is omitted, t
26dd0 68 65 20 75 70 73 65 72 74 20 62 65 68 61 76 69  he upsert behavi
26de0 6f 72 20 69 73 20 74 72 69 67 67 65 72 65 64 20  or is triggered 
26df0 62 79 20 61 0a 76 69 6f 6c 61 74 69 6f 6e 20 6f  by a.violation o
26e00 66 20 61 6e 79 20 75 6e 69 71 75 65 6e 65 73 73  f any uniqueness
26e10 20 63 6f 6e 73 74 72 61 69 6e 74 20 6f 6e 20 74   constraint on t
26e20 68 65 20 74 61 62 6c 65 20 6f 66 20 74 68 65 20  he table of the 
26e30 49 4e 53 45 52 54 2e 0a 0a 3c 70 3e 49 66 20 74  INSERT...<p>If t
26e40 68 65 20 69 6e 73 65 72 74 20 6f 70 65 72 61 74  he insert operat
26e50 69 6f 6e 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ion would cause 
26e60 74 68 65 20 75 6e 69 71 75 65 6e 65 73 73 20 63  the uniqueness c
26e70 6f 6e 73 74 72 61 69 6e 74 20 69 64 65 6e 74 69  onstraint identi
26e80 66 69 65 64 0a 62 79 20 74 68 65 20 63 6f 6e 66  fied.by the conf
26e90 6c 69 63 74 2d 74 61 72 67 65 74 20 63 6c 61 75  lict-target clau
26ea0 73 65 20 74 6f 20 66 61 69 6c 2c 20 74 68 65 6e  se to fail, then
26eb0 20 74 68 65 20 69 6e 73 65 72 74 20 69 73 20 6f   the insert is o
26ec0 6d 69 74 74 65 64 20 61 6e 64 0a 65 69 74 68 65  mitted and.eithe
26ed0 72 20 74 68 65 20 44 4f 20 4e 4f 54 48 49 4e 47  r the DO NOTHING
26ee0 20 6f 72 20 44 4f 20 55 50 44 41 54 45 20 6f 70   or DO UPDATE op
26ef0 65 72 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  eration is perfo
26f00 72 6d 65 64 20 69 6e 73 74 65 61 64 2e 0a 49 6e  rmed instead..In
26f10 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 20 6d   the case of a m
26f20 75 6c 74 69 2d 72 6f 77 20 69 6e 73 65 72 74 2c  ulti-row insert,
26f30 20 74 68 69 73 20 64 65 63 69 73 69 6f 6e 20 69   this decision i
26f40 73 20 6d 61 64 65 20 73 65 70 61 72 61 74 65 6c  s made separatel
26f50 79 0a 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  y.for each row o
26f60 66 20 74 68 65 20 69 6e 73 65 72 74 2e 0a 0a 3c  f the insert...<
26f70 70 3e 54 68 65 20 73 70 65 63 69 61 6c 20 55 50  p>The special UP
26f80 53 45 52 54 20 70 72 6f 63 65 73 73 69 6e 67 20  SERT processing 
26f90 68 61 70 70 65 6e 73 20 6f 6e 6c 79 20 66 6f 72  happens only for
26fa0 20 75 6e 69 71 75 65 6e 65 73 73 20 63 6f 6e 73   uniqueness cons
26fb0 74 72 61 69 6e 74 20 6f 6e 0a 74 68 65 20 74 61  traint on.the ta
26fc0 62 6c 65 20 74 68 61 74 20 69 73 20 72 65 63 65  ble that is rece
26fd0 69 76 69 6e 67 20 74 68 65 20 49 4e 53 45 52 54  iving the INSERT
26fe0 2e 20 41 20 22 75 6e 69 71 75 65 6e 65 73 73 20  . A "uniqueness 
26ff0 63 6f 6e 73 74 72 61 69 6e 74 22 0a 69 73 20 61  constraint".is a
27000 6e 20 65 78 70 6c 69 63 69 74 20 55 4e 49 51 55  n explicit UNIQU
27010 45 20 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59  E or PRIMARY KEY
27020 20 63 6f 6e 73 74 72 61 69 6e 74 20 77 69 74 68   constraint with
27030 69 6e 0a 74 68 65 20 43 52 45 41 54 45 20 54 41  in.the CREATE TA
27040 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  BLE statement, o
27050 72 20 61 20 5b 75 6e 69 71 75 65 20 69 6e 64 65  r a [unique inde
27060 78 5d 2e 0a 55 50 53 45 52 54 20 64 6f 65 73 20  x]..UPSERT does 
27070 6e 6f 74 20 69 6e 74 65 72 76 65 6e 65 20 66 6f  not intervene fo
27080 72 20 66 61 69 6c 65 64 20 4e 4f 54 20 4e 55 4c  r failed NOT NUL
27090 4c 20 6f 72 20 66 6f 72 65 69 67 6e 20 6b 65 79  L or foreign key
270a0 20 63 6f 6e 73 74 72 61 69 6e 74 73 0a 6f 72 20   constraints.or 
270b0 66 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  for constraints 
270c0 74 68 61 74 20 61 72 65 20 69 6d 70 6c 65 6d 65  that are impleme
270d0 6e 74 65 64 20 75 73 69 6e 67 20 74 72 69 67 67  nted using trigg
270e0 65 72 73 2e 0a 0a 3c 70 3e 43 6f 6c 75 6d 6e 20  ers...<p>Column 
270f0 6e 61 6d 65 73 20 69 6e 20 74 68 65 20 65 78 70  names in the exp
27100 72 65 73 73 69 6f 6e 73 20 6f 66 20 61 20 44 4f  ressions of a DO
27110 20 55 50 44 41 54 45 20 72 65 66 65 72 20 74 6f   UPDATE refer to
27120 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 75 6e   the original.un
27130 63 68 61 6e 67 65 64 20 76 61 6c 75 65 20 6f 66  changed value of
27140 20 74 68 65 20 63 6f 6c 75 6d 6e 2c 20 62 65 66   the column, bef
27150 6f 72 65 20 74 68 65 20 61 74 74 65 6d 70 74 65  ore the attempte
27160 64 20 49 4e 53 45 52 54 2e 20 20 54 6f 20 75 73  d INSERT.  To us
27170 65 20 74 68 65 0a 76 61 6c 75 65 20 74 68 61 74  e the.value that
27180 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
27190 20 69 6e 73 65 72 74 65 64 20 68 61 64 20 74 68   inserted had th
271a0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 6e 6f 74  e constraint not
271b0 20 66 61 69 6c 65 64 2c 0a 61 64 64 20 74 68 65   failed,.add the
271c0 20 73 70 65 63 69 61 6c 20 22 65 78 63 6c 75 64   special "exclud
271d0 65 64 2e 22 20 74 61 62 6c 65 20 71 75 61 6c 69  ed." table quali
271e0 66 69 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 75  fier to the colu
271f0 6d 6e 20 6e 61 6d 65 2e 0a 0a 3c 70 3e 53 6f 6d  mn name...<p>Som
27200 65 20 65 78 61 6d 70 6c 65 73 20 77 69 6c 6c 20  e examples will 
27210 68 65 6c 70 20 69 6c 6c 75 73 74 72 61 74 65 20  help illustrate 
27220 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 3a 0a  the difference:.
27230 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
27240 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20  e>.CREATE TABLE 
27250 76 6f 63 61 62 75 6c 61 72 79 28 77 6f 72 64 20  vocabulary(word 
27260 54 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45 59  TEXT PRIMARY KEY
27270 2c 20 63 6f 75 6e 74 20 49 4e 54 20 44 45 46 41  , count INT DEFA
27280 55 4c 54 20 31 29 3b 0a 49 4e 53 45 52 54 20 49  ULT 1);.INSERT I
27290 4e 54 4f 20 76 6f 63 61 62 75 6c 61 72 79 28 77  NTO vocabulary(w
272a0 6f 72 64 29 20 56 41 4c 55 45 53 28 27 6a 6f 76  ord) VALUES('jov
272b0 69 61 6c 27 29 0a 20 20 4f 4e 20 43 4f 4e 46 4c  ial').  ON CONFL
272c0 49 43 54 28 77 6f 72 64 29 20 44 4f 20 55 50 44  ICT(word) DO UPD
272d0 41 54 45 20 53 45 54 20 63 6f 75 6e 74 3d 63 6f  ATE SET count=co
272e0 75 6e 74 2b 31 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  unt+1;.</pre></b
272f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
27300 68 65 20 75 70 73 65 72 74 20 61 62 6f 76 65 20  he upsert above 
27310 69 6e 73 65 72 74 73 20 74 68 65 20 6e 65 77 20  inserts the new 
27320 76 6f 63 61 62 75 6c 61 72 79 20 77 6f 72 64 20  vocabulary word 
27330 22 6a 6f 76 69 61 6c 22 20 69 66 20 74 68 61 74  "jovial" if that
27340 0a 77 6f 72 64 20 69 73 20 6e 6f 74 20 61 6c 72  .word is not alr
27350 65 61 64 79 20 69 6e 20 74 68 65 20 64 69 63 74  eady in the dict
27360 69 6f 6e 61 72 79 2c 20 6f 72 20 69 66 20 69 74  ionary, or if it
27370 20 69 73 20 61 6c 72 65 61 64 79 20 69 6e 20 74   is already in t
27380 68 65 0a 64 69 63 74 69 6f 6e 61 72 79 2c 20 69  he.dictionary, i
27390 74 20 69 6e 63 72 65 6d 65 6e 74 73 20 74 68 65  t increments the
273a0 20 63 6f 75 6e 74 65 72 2e 20 20 54 68 65 20 22   counter.  The "
273b0 63 6f 75 6e 74 2b 31 22 20 65 78 70 72 65 73 73  count+1" express
273c0 69 6f 6e 0a 63 6f 75 6c 64 20 61 6c 73 6f 20 62  ion.could also b
273d0 65 20 77 72 69 74 74 65 6e 20 61 73 20 22 76 6f  e written as "vo
273e0 63 61 62 75 6c 61 72 79 2e 63 6f 75 6e 74 22 2e  cabulary.count".
273f0 20 20 50 6f 73 74 67 72 65 53 51 4c 20 72 65 71    PostgreSQL req
27400 75 69 72 65 73 20 74 68 65 0a 73 65 63 6f 6e 64  uires the.second
27410 20 66 6f 72 6d 2c 20 62 75 74 20 53 51 4c 69 74   form, but SQLit
27420 65 20 61 63 63 65 70 74 73 20 65 69 74 68 65 72  e accepts either
27430 2e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ...<blockquote><
27440 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c  pre>.CREATE TABL
27450 45 20 70 68 6f 6e 65 62 6f 6f 6b 28 6e 61 6d 65  E phonebook(name
27460 20 54 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45   TEXT PRIMARY KE
27470 59 2c 20 70 68 6f 6e 65 6e 75 6d 62 65 72 20 54  Y, phonenumber T
27480 45 58 54 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54  EXT);.INSERT INT
27490 4f 20 70 68 6f 6e 65 62 6f 6f 6b 28 6e 61 6d 65  O phonebook(name
274a0 2c 70 68 6f 6e 65 6e 75 6d 62 65 72 29 20 56 41  ,phonenumber) VA
274b0 4c 55 45 53 28 27 41 6c 69 63 65 27 2c 27 37 30  LUES('Alice','70
274c0 34 2d 35 35 35 2d 31 32 31 32 27 29 0a 20 20 4f  4-555-1212').  O
274d0 4e 20 43 4f 4e 46 4c 49 43 54 28 6e 61 6d 65 29  N CONFLICT(name)
274e0 20 44 4f 20 55 50 44 41 54 45 20 53 45 54 20 70   DO UPDATE SET p
274f0 68 6f 6e 65 6e 75 6d 62 65 72 3d 65 78 63 6c 75  honenumber=exclu
27500 64 65 64 2e 70 68 6f 6e 65 6e 75 6d 62 65 72 3b  ded.phonenumber;
27510 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
27520 6f 74 65 3e 0a 0a 3c 70 3e 49 6e 20 74 68 65 20  ote>..<p>In the 
27530 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 2c 20  second example, 
27540 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69  the expression i
27550 6e 20 74 68 65 20 44 4f 20 55 50 44 41 54 45 20  n the DO UPDATE 
27560 63 6c 61 75 73 65 20 69 73 0a 6f 66 20 74 68 65  clause is.of the
27570 20 66 6f 72 6d 20 22 65 78 63 6c 75 64 65 64 2e   form "excluded.
27580 70 68 6f 6e 65 6e 75 6d 62 65 72 22 2e 20 20 54  phonenumber".  T
27590 68 65 20 22 65 78 63 6c 75 64 65 64 2e 22 20 70  he "excluded." p
275a0 72 65 66 69 78 20 63 61 75 73 65 73 20 74 68 65  refix causes the
275b0 0a 22 70 68 6f 6e 65 6e 75 6d 62 65 72 22 20 74  ."phonenumber" t
275c0 6f 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 76  o refer to the v
275d0 61 6c 75 65 20 66 6f 72 20 70 68 6f 6e 65 6e 75  alue for phonenu
275e0 6d 62 65 72 20 74 68 61 74 20 77 6f 75 6c 64 20  mber that would 
275f0 68 61 76 65 20 62 65 65 6e 0a 69 6e 73 65 72 74  have been.insert
27600 65 64 20 68 61 64 20 74 68 65 72 65 20 62 65 65  ed had there bee
27610 6e 20 6e 6f 20 63 6f 6e 66 6c 69 63 74 2e 20 20  n no conflict.  
27620 48 65 6e 63 65 2c 20 74 68 65 20 65 66 66 65 63  Hence, the effec
27630 74 20 6f 66 20 74 68 65 20 75 70 73 65 72 74 0a  t of the upsert.
27640 69 73 20 74 6f 20 69 6e 73 65 72 74 20 61 20 70  is to insert a p
27650 68 6f 6e 65 6e 75 6d 62 65 72 20 6f 66 20 41 6c  honenumber of Al
27660 69 63 65 20 69 66 20 6e 6f 6e 65 20 65 78 69 73  ice if none exis
27670 74 73 2c 20 6f 72 20 74 6f 20 6f 76 65 72 77 72  ts, or to overwr
27680 69 74 65 0a 61 6e 79 20 70 72 69 6f 72 20 70 68  ite.any prior ph
27690 6f 6e 65 6e 75 6d 62 65 72 20 66 6f 72 20 41 6c  onenumber for Al
276a0 69 63 65 20 77 69 74 68 20 74 68 65 20 6e 65 77  ice with the new
276b0 20 6f 6e 65 2e 0a 0a 3c 70 3e 4e 6f 74 65 20 74   one...<p>Note t
276c0 68 61 74 20 74 68 65 20 44 4f 20 55 50 44 41 54  hat the DO UPDAT
276d0 45 20 63 6c 61 75 73 65 20 61 63 74 73 20 6f 6e  E clause acts on
276e0 6c 79 20 6f 6e 20 74 68 65 20 73 69 6e 67 6c 65  ly on the single
276f0 20 72 6f 77 0a 74 68 61 74 20 65 78 70 65 72 69   row.that experi
27700 65 6e 63 65 64 20 74 68 65 20 63 6f 6e 73 74 72  enced the constr
27710 61 69 6e 74 20 65 72 72 6f 72 20 64 75 72 69 6e  aint error durin
27720 67 20 49 4e 53 45 52 54 2e 20 20 49 74 20 69 73  g INSERT.  It is
27730 20 6e 6f 74 0a 6e 65 63 65 73 73 61 72 79 20 74   not.necessary t
27740 6f 20 69 6e 63 6c 75 64 65 20 61 20 57 48 45 52  o include a WHER
27750 45 20 63 6c 61 75 73 65 20 74 68 61 74 20 72 65  E clause that re
27760 73 74 72 69 63 74 69 6f 6e 73 20 74 68 65 20 61  strictions the a
27770 63 74 69 6f 6e 0a 74 6f 20 74 68 61 74 20 6f 6e  ction.to that on
27780 65 20 72 6f 77 2e 20 20 54 68 65 20 6f 6e 6c 79  e row.  The only
27790 20 75 73 65 20 66 6f 72 20 74 68 65 20 57 48 45   use for the WHE
277a0 52 45 20 63 6c 61 75 73 65 20 61 74 0a 74 68 65  RE clause at.the
277b0 20 65 6e 64 20 6f 66 20 74 68 65 20 44 4f 20 55   end of the DO U
277c0 50 44 41 54 45 20 69 73 20 74 6f 20 6f 70 74 69  PDATE is to opti
277d0 6f 6e 61 6c 6c 79 20 63 68 61 6e 67 65 20 74 68  onally change th
277e0 65 20 44 4f 20 55 50 44 41 54 45 0a 69 6e 74 6f  e DO UPDATE.into
277f0 20 61 20 6e 6f 2d 6f 70 20 64 65 70 65 6e 64 69   a no-op dependi
27800 6e 67 20 6f 6e 20 74 68 65 20 6f 72 69 67 69 6e  ng on the origin
27810 61 6c 20 61 6e 64 2f 6f 72 20 6e 65 77 20 76 61  al and/or new va
27820 6c 75 65 73 2e 0a 46 6f 72 20 65 78 61 6d 70 6c  lues..For exampl
27830 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  e:..<blockquote>
27840 3c 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42  <pre>.CREATE TAB
27850 4c 45 20 70 68 6f 6e 65 62 6f 6f 6b 32 28 0a 20  LE phonebook2(. 
27860 20 6e 61 6d 65 20 54 45 58 54 20 50 52 49 4d 41   name TEXT PRIMA
27870 52 59 20 4b 45 59 2c 0a 20 20 70 68 6f 6e 65 6e  RY KEY,.  phonen
27880 75 6d 62 65 72 20 54 45 58 54 2c 0a 20 20 76 61  umber TEXT,.  va
27890 6c 69 64 44 61 74 65 20 44 41 54 45 0a 29 3b 0a  lidDate DATE.);.
278a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 70 68 6f 6e  INSERT INTO phon
278b0 65 62 6f 6f 6b 32 28 6e 61 6d 65 2c 70 68 6f 6e  ebook2(name,phon
278c0 65 6e 75 6d 62 65 72 2c 76 61 6c 69 64 44 61 74  enumber,validDat
278d0 65 29 0a 20 20 56 41 4c 55 45 53 28 27 41 6c 69  e).  VALUES('Ali
278e0 63 65 27 2c 27 37 30 34 2d 35 35 35 2d 31 32 31  ce','704-555-121
278f0 32 27 2c 27 32 30 31 38 2d 30 35 2d 30 38 27 29  2','2018-05-08')
27900 0a 20 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 28 6e  .  ON CONFLICT(n
27910 61 6d 65 29 20 44 4f 20 55 50 44 41 54 45 20 53  ame) DO UPDATE S
27920 45 54 0a 20 20 20 20 70 68 6f 6e 65 6e 75 6d 62  ET.    phonenumb
27930 65 72 3d 65 78 63 6c 75 64 65 64 2e 70 68 6f 6e  er=excluded.phon
27940 65 6e 75 6d 62 65 72 2c 0a 20 20 20 20 76 61 6c  enumber,.    val
27950 69 64 44 61 74 65 3d 65 78 63 6c 75 64 65 64 2e  idDate=excluded.
27960 76 61 6c 69 64 44 61 74 65 0a 20 20 57 48 45 52  validDate.  WHER
27970 45 20 65 78 63 6c 75 64 65 64 2e 76 61 6c 69 64  E excluded.valid
27980 44 61 74 65 3e 70 68 6f 6e 65 62 6f 6f 6b 32 2e  Date>phonebook2.
27990 76 61 6c 69 64 44 61 74 65 3b 0a 3c 2f 70 72 65  validDate;.</pre
279a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
279b0 3c 70 3e 49 6e 20 74 68 69 73 20 6c 61 73 74 20  <p>In this last 
279c0 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 70 68 6f  example, the pho
279d0 6e 65 62 6f 6f 6b 32 20 65 6e 74 72 79 20 69 73  nebook2 entry is
279e0 20 6f 6e 6c 79 0a 75 70 64 61 74 65 64 20 69 66   only.updated if
279f0 20 74 68 65 20 76 61 6c 69 64 44 61 74 65 20 66   the validDate f
27a00 6f 72 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73  or the newly ins
27a10 65 72 74 65 64 20 76 61 6c 75 65 20 69 73 0a 6e  erted value is.n
27a20 65 77 65 72 20 74 68 61 6e 20 74 68 65 20 65 6e  ewer than the en
27a30 74 72 79 20 61 6c 72 65 61 64 79 20 69 6e 20 74  try already in t
27a40 68 65 20 74 61 62 6c 65 2e 20 20 49 66 20 74 68  he table.  If th
27a50 65 20 74 61 62 6c 65 20 61 6c 72 65 61 64 79 0a  e table already.
27a60 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 6e 74 72  contains an entr
27a70 79 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  y with the same 
27a80 6e 61 6d 65 20 61 6e 64 20 61 20 63 75 72 72 65  name and a curre
27a90 6e 74 20 76 61 6c 69 64 44 61 74 65 2c 0a 74 68  nt validDate,.th
27aa0 65 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  en the WHERE cla
27ab0 75 73 65 20 63 61 75 73 65 73 20 74 68 65 20 44  use causes the D
27ac0 4f 20 55 50 44 41 54 45 20 74 6f 20 62 65 63 6f  O UPDATE to beco
27ad0 6d 65 20 61 20 6e 6f 2d 6f 70 2e 0a 0a 3c 74 63  me a no-op...<tc
27ae0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 70 61  l>hd_fragment pa
27af0 72 73 65 61 6d 62 69 67 20 7b 55 50 53 45 52 54  rseambig {UPSERT
27b00 20 70 61 72 73 69 6e 67 20 61 6d 62 69 67 75 69   parsing ambigui
27b10 74 79 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 50 61  ty}</tcl>.<h3>Pa
27b20 72 73 69 6e 67 20 41 6d 62 69 67 75 69 74 79 3c  rsing Ambiguity<
27b30 2f 68 33 3e 0a 0a 3c 70 3e 57 68 65 6e 20 74 68  /h3>..<p>When th
27b40 65 20 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65  e [INSERT] state
27b50 6d 65 6e 74 20 74 6f 20 77 68 69 63 68 20 74 68  ment to which th
27b60 65 20 55 50 53 45 52 54 20 69 73 20 61 74 74 61  e UPSERT is atta
27b70 63 68 65 64 0a 74 61 6b 65 73 20 69 74 73 20 76  ched.takes its v
27b80 61 6c 75 65 73 20 66 72 6f 6d 20 61 20 5b 53 45  alues from a [SE
27b90 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2c  LECT] statement,
27ba0 20 74 68 65 72 65 20 69 73 20 61 20 70 6f 74 65   there is a pote
27bb0 6e 74 69 61 6c 0a 70 61 72 73 69 6e 67 20 61 6d  ntial.parsing am
27bc0 62 69 67 75 69 74 79 2e 20 20 54 68 65 20 70 61  biguity.  The pa
27bd0 72 73 65 72 20 6d 69 67 68 74 20 6e 6f 74 20 62  rser might not b
27be0 65 20 61 62 6c 65 20 74 6f 20 74 65 6c 6c 20 69  e able to tell i
27bf0 66 20 74 68 65 0a 22 4f 4e 22 20 6b 65 79 77 6f  f the."ON" keywo
27c00 72 64 20 69 73 20 69 6e 74 72 6f 64 75 63 69 6e  rd is introducin
27c10 67 20 74 68 65 20 55 50 53 45 52 54 20 6f 72 20  g the UPSERT or 
27c20 69 66 20 69 74 20 69 73 20 74 68 65 20 4f 4e 20  if it is the ON 
27c30 63 6c 61 75 73 65 0a 6f 66 20 61 20 6a 6f 69 6e  clause.of a join
27c40 2e 20 20 54 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  .  To work aroun
27c50 64 20 74 68 69 73 2c 20 74 68 65 20 53 45 4c 45  d this, the SELE
27c60 43 54 20 73 74 61 74 65 6d 65 6e 74 20 73 68 6f  CT statement sho
27c70 75 6c 64 20 61 6c 77 61 79 73 0a 69 6e 63 6c 75  uld always.inclu
27c80 64 65 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  de a WHERE claus
27c90 65 2c 20 65 76 65 6e 20 69 66 20 74 68 61 74 20  e, even if that 
27ca0 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 73 20  WHERE clause is 
27cb0 6a 75 73 74 0a 22 57 48 45 52 45 20 74 72 75 65  just."WHERE true
27cc0 22 2e 0a 0a 3c 70 3e 41 6d 62 69 67 75 6f 75 73  "...<p>Ambiguous
27cd0 20 75 73 65 20 6f 66 20 4f 4e 3a 0a 0a 3c 62 6c   use of ON:..<bl
27ce0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 49  ockquote><pre>.I
27cf0 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 20 53 45  NSERT INTO t1 SE
27d00 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 32 0a 4f  LECT * FROM t2.O
27d10 4e 20 43 4f 4e 46 4c 49 43 54 28 78 29 20 44 4f  N CONFLICT(x) DO
27d20 20 55 50 44 41 54 45 20 53 45 54 20 79 3d 65 78   UPDATE SET y=ex
27d30 63 6c 75 64 65 64 2e 79 3b 0a 3c 2f 70 72 65 3e  cluded.y;.</pre>
27d40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
27d50 70 3e 41 6d 62 69 67 75 69 74 79 20 72 65 73 6f  p>Ambiguity reso
27d60 6c 76 65 64 20 75 73 69 6e 67 20 61 20 57 48 45  lved using a WHE
27d70 52 45 20 63 6c 61 75 73 65 3a 0a 0a 3c 62 6c 6f  RE clause:..<blo
27d80 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e  ckquote><pre>.IN
27d90 53 45 52 54 20 49 4e 54 4f 20 74 31 20 53 45 4c  SERT INTO t1 SEL
27da0 45 43 54 20 2a 20 46 52 4f 4d 20 74 32 20 3c 66  ECT * FROM t2 <f
27db0 6f 6e 74 20 63 6f 6c 6f 72 3d 22 62 6c 75 65 22  ont color="blue"
27dc0 3e 57 48 45 52 45 20 74 72 75 65 3c 2f 66 6f 6e  >WHERE true</fon
27dd0 74 3e 0a 4f 4e 20 43 4f 4e 46 4c 49 43 54 28 78  t>.ON CONFLICT(x
27de0 29 20 44 4f 20 55 50 44 41 54 45 20 53 45 54 20  ) DO UPDATE SET 
27df0 79 3d 65 78 63 6c 75 64 65 64 2e 79 3b 0a 3c 2f  y=excluded.y;.</
27e00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
27e10 3e 0a 0a 3c 68 33 3e 4c 69 6d 69 74 61 74 69 6f  >..<h3>Limitatio
27e20 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 55 50 53 45  ns</h3>..<p>UPSE
27e30 52 54 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  RT does not curr
27e40 65 6e 74 6c 79 20 77 6f 72 6b 20 66 6f 72 20 5b  ently work for [
27e50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
27e60 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23  ...<tcl>.#######
27e70 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27e80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27e90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27ea0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27eb0 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
27ec0 7b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63 6c 61  {ON CONFLICT cla
27ed0 75 73 65 7d 20 63 6f 6e 66 6c 69 63 74 20 7b 7b  use} conflict {{
27ee0 63 6f 6e 66 6c 69 63 74 20 63 6c 61 75 73 65 7d  conflict clause}
27ef0 20 7b 4f 4e 20 43 4f 4e 46 4c 49 43 54 7d 7d 0a   {ON CONFLICT}}.
27f00 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65  .RecursiveBubble
27f10 44 69 61 67 72 61 6d 20 63 6f 6e 66 6c 69 63 74  Diagram conflict
27f20 2d 63 6c 61 75 73 65 0a 3c 2f 74 63 6c 3e 0a 0a  -clause.</tcl>..
27f30 3c 70 3e 54 68 65 20 4f 4e 20 43 4f 4e 46 4c 49  <p>The ON CONFLI
27f40 43 54 20 63 6c 61 75 73 65 20 69 73 20 61 0a 6e  CT clause is a.n
27f50 6f 6e 2d 73 74 61 6e 64 61 72 64 20 65 78 74 65  on-standard exte
27f60 6e 73 69 6f 6e 20 73 70 65 63 69 66 69 63 20 74  nsion specific t
27f70 6f 20 53 51 4c 69 74 65 20 0a 74 68 61 74 20 63  o SQLite .that c
27f80 61 6e 20 61 70 70 65 61 72 20 69 6e 20 6d 61 6e  an appear in man
27f90 79 20 6f 74 68 65 72 20 53 51 4c 20 63 6f 6d 6d  y other SQL comm
27fa0 61 6e 64 73 2e 0a 49 74 20 69 73 20 67 69 76 65  ands..It is give
27fb0 6e 20 69 74 73 20 6f 77 6e 20 73 65 63 74 69 6f  n its own sectio
27fc0 6e 20 69 6e 20 74 68 69 73 20 64 6f 63 75 6d 65  n in this docume
27fd0 6e 74 20 62 65 63 61 75 73 65 20 69 74 20 69 73  nt because it is
27fe0 20 6e 6f 74 0a 70 61 72 74 20 6f 66 20 73 74 61   not.part of sta
27ff0 6e 64 61 72 64 20 53 51 4c 20 61 6e 64 20 74 68  ndard SQL and th
28000 65 72 65 66 6f 72 65 20 6d 69 67 68 74 20 6e 6f  erefore might no
28010 74 20 62 65 20 66 61 6d 69 6c 69 61 72 2e 3c 2f  t be familiar.</
28020 70 3e 0a 0a 3c 70 3e 54 68 65 20 4f 4e 20 43 4f  p>..<p>The ON CO
28030 4e 46 4c 49 43 54 20 63 6c 61 75 73 65 20 64 65  NFLICT clause de
28040 73 63 72 69 62 65 64 20 68 65 72 65 20 68 61 73  scribed here has
28050 20 62 65 65 6e 20 61 20 70 61 72 74 20 6f 66 0a   been a part of.
28060 53 51 4c 69 74 65 20 73 69 6e 63 65 20 62 65 66  SQLite since bef
28070 6f 72 65 20 76 65 72 73 69 6f 6e 20 33 2e 30 2e  ore version 3.0.
28080 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 30 2e 30  0 ([dateof:3.0.0
28090 5d 29 2e 20 20 54 68 65 20 70 68 72 61 73 65 0a  ]).  The phrase.
280a0 22 4f 4e 26 6e 62 73 70 3b 43 4f 4e 46 4c 49 43  "ON&nbsp;CONFLIC
280b0 54 22 20 69 73 20 61 6c 73 6f 20 70 61 72 74 20  T" is also part 
280c0 6f 66 20 5b 55 50 53 45 52 54 5d 2c 20 77 68 69  of [UPSERT], whi
280d0 63 68 20 69 73 20 61 6e 20 65 78 74 65 6e 73 69  ch is an extensi
280e0 6f 6e 0a 74 6f 20 5b 49 4e 53 45 52 54 5d 20 61  on.to [INSERT] a
280f0 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
28100 33 2e 32 34 2e 30 20 28 5b 64 61 74 65 6f 66 3a  3.24.0 ([dateof:
28110 33 2e 32 34 2e 30 5d 29 2e 20 20 44 6f 20 6e 6f  3.24.0]).  Do no
28120 74 0a 63 6f 6e 66 75 73 65 20 74 68 65 73 65 20  t.confuse these 
28130 74 77 6f 20 73 65 70 61 72 61 74 65 20 75 73 65  two separate use
28140 73 20 6f 66 20 74 68 65 20 22 4f 4e 26 6e 62 73  s of the "ON&nbs
28150 70 3b 43 4f 4e 46 4c 49 43 54 22 20 70 68 72 61  p;CONFLICT" phra
28160 73 65 2e 0a 0a 3c 70 3e 5e 54 68 65 20 73 79 6e  se...<p>^The syn
28170 74 61 78 20 66 6f 72 20 74 68 65 20 4f 4e 20 43  tax for the ON C
28180 4f 4e 46 4c 49 43 54 20 63 6c 61 75 73 65 20 69  ONFLICT clause i
28190 73 20 61 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  s as shown above
281a0 20 66 6f 72 0a 74 68 65 20 43 52 45 41 54 45 20   for.the CREATE 
281b0 54 41 42 4c 45 20 63 6f 6d 6d 61 6e 64 2e 20 20  TABLE command.  
281c0 5e 46 6f 72 20 74 68 65 20 49 4e 53 45 52 54 20  ^For the INSERT 
281d0 61 6e 64 0a 55 50 44 41 54 45 20 63 6f 6d 6d 61  and.UPDATE comma
281e0 6e 64 73 2c 20 74 68 65 20 6b 65 79 77 6f 72 64  nds, the keyword
281f0 73 20 22 4f 4e 20 43 4f 4e 46 4c 49 43 54 22 20  s "ON CONFLICT" 
28200 61 72 65 20 72 65 70 6c 61 63 65 64 20 62 79 20  are replaced by 
28210 22 4f 52 22 20 73 6f 20 74 68 61 74 0a 74 68 65  "OR" so that.the
28220 20 73 79 6e 74 61 78 20 72 65 61 64 73 20 6d 6f   syntax reads mo
28230 72 65 20 6e 61 74 75 72 61 6c 6c 79 2e 20 20 46  re naturally.  F
28240 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 73 74  or example, inst
28250 65 61 64 20 6f 66 0a 22 49 4e 53 45 52 54 20 4f  ead of."INSERT O
28260 4e 20 43 4f 4e 46 4c 49 43 54 20 49 47 4e 4f 52  N CONFLICT IGNOR
28270 45 22 20 77 65 20 68 61 76 65 20 22 49 4e 53 45  E" we have "INSE
28280 52 54 20 4f 52 20 49 47 4e 4f 52 45 22 2e 0a 54  RT OR IGNORE"..T
28290 68 65 20 6b 65 79 77 6f 72 64 73 20 63 68 61 6e  he keywords chan
282a0 67 65 20 62 75 74 20 74 68 65 20 6d 65 61 6e 69  ge but the meani
282b0 6e 67 20 6f 66 20 74 68 65 20 63 6c 61 75 73 65  ng of the clause
282c0 20 69 73 20 74 68 65 20 73 61 6d 65 0a 65 69 74   is the same.eit
282d0 68 65 72 20 77 61 79 2e 3c 2f 70 3e 0a 0a 3c 70  her way.</p>..<p
282e0 3e 54 68 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  >The ON CONFLICT
282f0 20 63 6c 61 75 73 65 20 61 70 70 6c 69 65 73 20   clause applies 
28300 74 6f 20 5b 55 4e 49 51 55 45 5d 2c 20 5b 4e 4f  to [UNIQUE], [NO
28310 54 20 4e 55 4c 4c 5d 2c 0a 5b 43 48 45 43 4b 5d  T NULL],.[CHECK]
28320 2c 20 61 6e 64 20 5b 50 52 49 4d 41 52 59 20 4b  , and [PRIMARY K
28330 45 59 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e  EY] constraints.
28340 0a 54 68 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  .The ON CONFLICT
28350 20 61 6c 67 6f 72 69 74 68 6d 20 64 6f 65 73 20   algorithm does 
28360 6e 6f 74 0a 61 70 70 6c 79 20 74 6f 20 5b 46 4f  not.apply to [FO
28370 52 45 49 47 4e 20 4b 45 59 20 63 6f 6e 73 74 72  REIGN KEY constr
28380 61 69 6e 74 73 5d 2e 0a 54 68 65 72 65 20 61 72  aints]..There ar
28390 65 20 66 69 76 65 20 63 6f 6e 66 6c 69 63 74 20  e five conflict 
283a0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72  resolution algor
283b0 69 74 68 6d 20 63 68 6f 69 63 65 73 3a 0a 52 4f  ithm choices:.RO
283c0 4c 4c 42 41 43 4b 2c 20 41 42 4f 52 54 2c 20 46  LLBACK, ABORT, F
283d0 41 49 4c 2c 20 49 47 4e 4f 52 45 2c 20 61 6e 64  AIL, IGNORE, and
283e0 20 52 45 50 4c 41 43 45 2e 0a 5e 54 68 65 20 64   REPLACE..^The d
283f0 65 66 61 75 6c 74 20 63 6f 6e 66 6c 69 63 74 20  efault conflict 
28400 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72  resolution algor
28410 69 74 68 6d 20 69 73 20 41 42 4f 52 54 2e 20 20  ithm is ABORT.  
28420 54 68 69 73 0a 69 73 20 77 68 61 74 20 74 68 65  This.is what the
28430 79 20 6d 65 61 6e 3a 3c 2f 70 3e 0a 0a 3c 64 6c  y mean:</p>..<dl
28440 3e 0a 3c 64 74 3e 3c 62 3e 52 4f 4c 4c 42 41 43  >.<dt><b>ROLLBAC
28450 4b 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  K</b></dt>.<dd><
28460 70 3e 20 5e 57 68 65 6e 20 61 6e 20 61 70 70 6c  p> ^When an appl
28470 69 63 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e  icable constrain
28480 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75  t violation occu
28490 72 73 2c 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b  rs, the ROLLBACK
284a0 0a 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f  .resolution algo
284b0 72 69 74 68 6d 20 61 62 6f 72 74 73 20 74 68 65  rithm aborts the
284c0 20 63 75 72 72 65 6e 74 20 53 51 4c 20 73 74 61   current SQL sta
284d0 74 65 6d 65 6e 74 20 77 69 74 68 0a 61 6e 20 53  tement with.an S
284e0 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
284f0 20 65 72 72 6f 72 20 61 6e 64 20 72 6f 6c 6c 73   error and rolls
28500 20 62 61 63 6b 20 74 68 65 20 63 75 72 72 65 6e   back the curren
28510 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e  t transaction..^
28520 49 66 20 6e 6f 20 74 72 61 6e 73 61 63 74 69 6f  If no transactio
28530 6e 20 69 73 0a 61 63 74 69 76 65 20 28 6f 74 68  n is.active (oth
28540 65 72 20 74 68 61 6e 20 74 68 65 20 69 6d 70 6c  er than the impl
28550 69 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ied transaction 
28560 74 68 61 74 20 69 73 20 63 72 65 61 74 65 64 20  that is created 
28570 6f 6e 20 65 76 65 72 79 0a 63 6f 6d 6d 61 6e 64  on every.command
28580 29 20 74 68 65 6e 20 74 68 65 20 52 4f 4c 4c 42  ) then the ROLLB
28590 41 43 4b 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  ACK resolution a
285a0 6c 67 6f 72 69 74 68 6d 20 77 6f 72 6b 73 20 74  lgorithm works t
285b0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 0a 41  he same as the.A
285c0 42 4f 52 54 20 61 6c 67 6f 72 69 74 68 6d 2e 3c  BORT algorithm.<
285d0 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62  /p></dd>..<dt><b
285e0 3e 41 42 4f 52 54 3c 2f 62 3e 3c 2f 64 74 3e 0a  >ABORT</b></dt>.
285f0 3c 64 64 3e 3c 70 3e 20 5e 57 68 65 6e 20 61 6e  <dd><p> ^When an
28600 20 61 70 70 6c 69 63 61 62 6c 65 20 63 6f 6e 73   applicable cons
28610 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
28620 20 6f 63 63 75 72 73 2c 20 74 68 65 20 41 42 4f   occurs, the ABO
28630 52 54 0a 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c  RT.resolution al
28640 67 6f 72 69 74 68 6d 20 61 62 6f 72 74 73 20 74  gorithm aborts t
28650 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 73  he current SQL s
28660 74 61 74 65 6d 65 6e 74 0a 77 69 74 68 20 61 6e  tatement.with an
28670 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
28680 4e 54 20 65 72 72 6f 72 20 61 6e 64 20 62 61 63  NT error and bac
28690 6b 73 20 6f 75 74 20 61 6e 79 20 63 68 61 6e 67  ks out any chang
286a0 65 73 0a 6d 61 64 65 20 62 79 20 74 68 65 20 63  es.made by the c
286b0 75 72 72 65 6e 74 20 53 51 4c 20 73 74 61 74 65  urrent SQL state
286c0 6d 65 6e 74 3b 20 62 75 74 20 63 68 61 6e 67 65  ment; but change
286d0 73 20 63 61 75 73 65 64 0a 62 79 20 70 72 69 6f  s caused.by prio
286e0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
286f0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
28700 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 72 65   transaction are
28710 20 70 72 65 73 65 72 76 65 64 20 61 6e 64 20 74   preserved and t
28720 68 65 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 72  he.transaction r
28730 65 6d 61 69 6e 73 20 61 63 74 69 76 65 2e 0a 54  emains active..T
28740 68 69 73 20 69 73 20 74 68 65 20 64 65 66 61 75  his is the defau
28750 6c 74 20 62 65 68 61 76 69 6f 72 20 61 6e 64 20  lt behavior and 
28760 74 68 65 20 62 65 68 61 76 69 6f 72 20 73 70 65  the behavior spe
28770 63 69 66 69 65 64 20 62 79 20 74 68 65 20 53 51  cified by the SQ
28780 4c 0a 73 74 61 6e 64 61 72 64 2e 3c 2f 70 3e 3c  L.standard.</p><
28790 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 46 41 49  /dd>..<dt><b>FAI
287a0 4c 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  L</b></dt>.<dd><
287b0 70 3e 20 5e 57 68 65 6e 20 61 6e 20 61 70 70 6c  p> ^When an appl
287c0 69 63 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e  icable constrain
287d0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75  t violation occu
287e0 72 73 2c 20 74 68 65 20 46 41 49 4c 0a 72 65 73  rs, the FAIL.res
287f0 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
28800 6d 20 61 62 6f 72 74 73 20 74 68 65 20 63 75 72  m aborts the cur
28810 72 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rent SQL stateme
28820 6e 74 20 77 69 74 68 20 61 6e 0a 53 51 4c 49 54  nt with an.SQLIT
28830 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 65 72 72  E_CONSTRAINT err
28840 6f 72 2e 20 20 5e 42 75 74 20 74 68 65 20 46 41  or.  ^But the FA
28850 49 4c 20 72 65 73 6f 6c 75 74 69 6f 6e 20 64 6f  IL resolution do
28860 65 73 20 6e 6f 74 0a 62 61 63 6b 20 6f 75 74 20  es not.back out 
28870 70 72 69 6f 72 20 63 68 61 6e 67 65 73 20 6f 66  prior changes of
28880 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28890 6e 74 20 74 68 61 74 20 66 61 69 6c 65 64 20 6e  nt that failed n
288a0 6f 72 20 64 6f 65 73 0a 69 74 20 65 6e 64 20 74  or does.it end t
288b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a  he transaction..
288c0 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  ^For example, if
288d0 20 61 6e 20 55 50 44 41 54 45 0a 73 74 61 74 65   an UPDATE.state
288e0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
288f0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
28900 6f 6c 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 31  olation on the 1
28910 30 30 74 68 20 72 6f 77 20 74 68 61 74 0a 69 74  00th row that.it
28920 20 61 74 74 65 6d 70 74 73 20 74 6f 20 75 70 64   attempts to upd
28930 61 74 65 2c 20 74 68 65 6e 20 74 68 65 20 66 69  ate, then the fi
28940 72 73 74 20 39 39 20 72 6f 77 20 63 68 61 6e 67  rst 99 row chang
28950 65 73 20 61 72 65 20 70 72 65 73 65 72 76 65 64  es are preserved
28960 0a 62 75 74 20 63 68 61 6e 67 65 73 20 74 6f 20  .but changes to 
28970 72 6f 77 73 20 31 30 30 20 61 6e 64 20 62 65 79  rows 100 and bey
28980 6f 6e 64 20 6e 65 76 65 72 20 6f 63 63 75 72 2e  ond never occur.
28990 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 46 41 49  </p>..<p>The FAI
289a0 4c 20 62 65 68 61 76 69 6f 72 20 6f 6e 6c 79 20  L behavior only 
289b0 77 6f 72 6b 73 20 66 6f 72 20 75 6e 69 71 75 65  works for unique
289c0 6e 65 73 73 2c 20 4e 4f 54 20 4e 55 4c 4c 2c 20  ness, NOT NULL, 
289d0 61 6e 64 20 43 48 45 43 4b 20 0a 63 6f 6e 73 74  and CHECK .const
289e0 72 61 69 6e 74 73 2e 20 20 41 20 5b 66 6f 72 65  raints.  A [fore
289f0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
28a00 6e 74 5d 20 76 69 6f 6c 61 74 69 6f 6e 20 63 61  nt] violation ca
28a10 75 73 65 73 20 61 6e 20 41 42 4f 52 54 2e 0a 3c  uses an ABORT..<
28a20 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62  /p></dd>..<dt><b
28a30 3e 49 47 4e 4f 52 45 3c 2f 62 3e 3c 2f 64 74 3e  >IGNORE</b></dt>
28a40 0a 3c 64 64 3e 3c 70 3e 20 5e 57 68 65 6e 20 61  .<dd><p> ^When a
28a50 6e 20 61 70 70 6c 69 63 61 62 6c 65 20 63 6f 6e  n applicable con
28a60 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
28a70 6e 20 6f 63 63 75 72 73 2c 20 0a 74 68 65 20 49  n occurs, .the I
28a80 47 4e 4f 52 45 20 72 65 73 6f 6c 75 74 69 6f 6e  GNORE resolution
28a90 20 61 6c 67 6f 72 69 74 68 6d 20 73 6b 69 70 73   algorithm skips
28aa0 20 74 68 65 20 6f 6e 65 20 72 6f 77 20 74 68 61   the one row tha
28ab0 74 20 63 6f 6e 74 61 69 6e 73 0a 74 68 65 20 63  t contains.the c
28ac0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
28ad0 69 6f 6e 20 61 6e 64 20 63 6f 6e 74 69 6e 75 65  ion and continue
28ae0 73 20 70 72 6f 63 65 73 73 69 6e 67 20 73 75 62  s processing sub
28af0 73 65 71 75 65 6e 74 20 72 6f 77 73 0a 6f 66 20  sequent rows.of 
28b00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28b10 74 20 61 73 20 69 66 20 6e 6f 74 68 69 6e 67 20  t as if nothing 
28b20 77 65 6e 74 20 77 72 6f 6e 67 2e 0a 4f 74 68 65  went wrong..Othe
28b30 72 20 72 6f 77 73 20 62 65 66 6f 72 65 20 61 6e  r rows before an
28b40 64 20 61 66 74 65 72 20 74 68 65 20 72 6f 77 20  d after the row 
28b50 74 68 61 74 0a 63 6f 6e 74 61 69 6e 65 64 20 74  that.contained t
28b60 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  he constraint vi
28b70 6f 6c 61 74 69 6f 6e 20 61 72 65 20 69 6e 73 65  olation are inse
28b80 72 74 65 64 20 6f 72 20 75 70 64 61 74 65 64 0a  rted or updated.
28b90 6e 6f 72 6d 61 6c 6c 79 2e 20 5e 4e 6f 20 65 72  normally. ^No er
28ba0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
28bb0 66 6f 72 20 75 6e 69 71 75 65 6e 65 73 73 2c 20  for uniqueness, 
28bc0 4e 4f 54 20 4e 55 4c 4c 2c 20 61 6e 64 0a 55 4e  NOT NULL, and.UN
28bd0 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  IQUE constraint 
28be0 65 72 72 6f 72 73 20 77 68 65 6e 20 74 68 65 20  errors when the 
28bf0 49 47 4e 4f 52 45 20 63 6f 6e 66 6c 69 63 74 20  IGNORE conflict 
28c00 72 65 73 6f 6c 75 74 69 6f 6e 0a 61 6c 67 6f 72  resolution.algor
28c10 69 74 68 6d 20 69 73 20 75 73 65 64 2e 20 20 5e  ithm is used.  ^
28c20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 49 47 4e  However, the IGN
28c30 4f 52 45 20 63 6f 6e 66 6c 69 63 74 20 72 65 73  ORE conflict res
28c40 6f 6c 75 74 69 6f 6e 0a 61 6c 67 6f 72 69 74 68  olution.algorith
28c50 6d 20 77 6f 72 6b 73 20 6c 69 6b 65 20 41 42 4f  m works like ABO
28c60 52 54 20 66 6f 72 20 5b 66 6f 72 65 69 67 6e 20  RT for [foreign 
28c70 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 5d 20  key constraint] 
28c80 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 0a 3c 2f 64  errors..</p>.</d
28c90 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 52 45 50 4c 41  d>..<dt><b>REPLA
28ca0 43 45 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e  CE</b></dt>.<dd>
28cb0 3c 70 3e 20 5e 57 68 65 6e 20 61 20 5b 55 4e 49  <p> ^When a [UNI
28cc0 51 55 45 5d 20 6f 72 20 5b 50 52 49 4d 41 52 59  QUE] or [PRIMARY
28cd0 20 4b 45 59 5d 20 63 6f 6e 73 74 72 61 69 6e 74   KEY] constraint
28ce0 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75 72   violation occur
28cf0 73 2c 20 0a 74 68 65 20 52 45 50 4c 41 43 45 20  s, .the REPLACE 
28d00 61 6c 67 6f 72 69 74 68 6d 0a 64 65 6c 65 74 65  algorithm.delete
28d10 73 20 70 72 65 2d 65 78 69 73 74 69 6e 67 20 72  s pre-existing r
28d20 6f 77 73 20 74 68 61 74 20 61 72 65 20 63 61 75  ows that are cau
28d30 73 69 6e 67 20 74 68 65 20 63 6f 6e 73 74 72 61  sing the constra
28d40 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 0a 70 72  int violation.pr
28d50 69 6f 72 20 74 6f 20 69 6e 73 65 72 74 69 6e 67  ior to inserting
28d60 20 6f 72 20 75 70 64 61 74 69 6e 67 20 74 68 65   or updating the
28d70 20 63 75 72 72 65 6e 74 20 72 6f 77 20 61 6e 64   current row and
28d80 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 63 6f 6e   the command con
28d90 74 69 6e 75 65 73 20 0a 65 78 65 63 75 74 69 6e  tinues .executin
28da0 67 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 5e 49 66 20  g normally..^If 
28db0 61 20 5b 4e 4f 54 20 4e 55 4c 4c 5d 20 63 6f 6e  a [NOT NULL] con
28dc0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
28dd0 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20 52 45  n occurs, the RE
28de0 50 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 0a 72  PLACE conflict.r
28df0 65 73 6f 6c 75 74 69 6f 6e 20 72 65 70 6c 61 63  esolution replac
28e00 65 73 20 74 68 65 20 4e 55 4c 4c 20 76 61 6c 75  es the NULL valu
28e10 65 20 77 69 74 68 0a 74 68 65 20 64 65 66 61 75  e with.the defau
28e20 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 61  lt value for tha
28e30 74 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20  t column, or if 
28e40 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 6e  the column has n
28e50 6f 20 64 65 66 61 75 6c 74 0a 76 61 6c 75 65 2c  o default.value,
28e60 20 74 68 65 6e 20 74 68 65 20 41 42 4f 52 54 20   then the ABORT 
28e70 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 75 73 65  algorithm is use
28e80 64 2e 0a 5e 49 66 20 61 20 5b 43 48 45 43 4b 20  d..^If a [CHECK 
28e90 63 6f 6e 73 74 72 61 69 6e 74 5d 20 6f 72 20 5b  constraint] or [
28ea0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
28eb0 74 72 61 69 6e 74 5d 20 76 69 6f 6c 61 74 69 6f  traint] violatio
28ec0 6e 20 6f 63 63 75 72 73 2c 20 0a 74 68 65 20 52  n occurs, .the R
28ed0 45 50 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 20  EPLACE conflict 
28ee0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72  resolution algor
28ef0 69 74 68 6d 20 77 6f 72 6b 73 20 6c 69 6b 65 20  ithm works like 
28f00 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  ABORT.</p>..<p>^
28f10 57 68 65 6e 20 74 68 65 20 52 45 50 4c 41 43 45  When the REPLACE
28f20 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75   conflict resolu
28f30 74 69 6f 6e 20 73 74 72 61 74 65 67 79 20 64 65  tion strategy de
28f40 6c 65 74 65 73 20 72 6f 77 73 20 69 6e 20 6f 72  letes rows in or
28f50 64 65 72 20 74 6f 0a 73 61 74 69 73 66 79 20 61  der to.satisfy a
28f60 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 5b 43 52   constraint, [CR
28f70 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 64  EATE TRIGGER | d
28f80 65 6c 65 74 65 20 74 72 69 67 67 65 72 73 5d 20  elete triggers] 
28f90 66 69 72 65 20 69 66 20 61 6e 64 20 6f 6e 6c 79  fire if and only
28fa0 20 69 66 0a 5b 72 65 63 75 72 73 69 76 65 5f 74   if.[recursive_t
28fb0 72 69 67 67 65 72 73 20 70 72 61 67 6d 61 20 7c  riggers pragma |
28fc0 20 72 65 63 75 72 73 69 76 65 20 74 72 69 67 67   recursive trigg
28fd0 65 72 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  ers] are enabled
28fe0 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b  .</p>..<p>^The [
28ff0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
29000 6f 6f 6b 20 7c 20 75 70 64 61 74 65 20 68 6f 6f  ook | update hoo
29010 6b 5d 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  k] is not invoke
29020 64 20 66 6f 72 20 72 6f 77 73 20 74 68 61 74 0a  d for rows that.
29030 61 72 65 20 64 65 6c 65 74 65 64 20 62 79 20 74  are deleted by t
29040 68 65 20 52 45 50 4c 41 43 45 20 63 6f 6e 66 6c  he REPLACE confl
29050 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ict resolution s
29060 74 72 61 74 65 67 79 2e 20 20 5e 4e 6f 72 20 64  trategy.  ^Nor d
29070 6f 65 73 0a 52 45 50 4c 41 43 45 20 69 6e 63 72  oes.REPLACE incr
29080 65 6d 65 6e 74 20 74 68 65 20 5b 73 71 6c 69 74  ement the [sqlit
29090 65 33 5f 63 68 61 6e 67 65 73 20 7c 20 63 68 61  e3_changes | cha
290a0 6e 67 65 20 63 6f 75 6e 74 65 72 5d 2e 0a 54 68  nge counter]..Th
290b0 65 20 65 78 63 65 70 74 69 6f 6e 61 6c 20 62 65  e exceptional be
290c0 68 61 76 69 6f 72 73 20 64 65 66 69 6e 65 64 20  haviors defined 
290d0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
290e0 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 0a  h might change .
290f0 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
29100 61 73 65 2e 3c 2f 70 3e 0a 3c 2f 64 6c 3e 0a 0a  ase.</p>.</dl>..
29110 3c 70 3e 5e 54 68 65 20 61 6c 67 6f 72 69 74 68  <p>^The algorith
29120 6d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  m specified in t
29130 68 65 20 4f 52 20 63 6c 61 75 73 65 20 6f 66 20  he OR clause of 
29140 61 6e 20 49 4e 53 45 52 54 20 6f 72 20 55 50 44  an INSERT or UPD
29150 41 54 45 0a 6f 76 65 72 72 69 64 65 73 20 61 6e  ATE.overrides an
29160 79 20 61 6c 67 6f 72 69 74 68 6d 20 73 70 65 63  y algorithm spec
29170 69 66 69 65 64 20 69 6e 20 61 20 43 52 45 41 54  ified in a CREAT
29180 45 20 54 41 42 4c 45 2e 0a 5e 49 66 20 6e 6f 20  E TABLE..^If no 
29190 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 70 65  algorithm is spe
291a0 63 69 66 69 65 64 20 61 6e 79 77 68 65 72 65 2c  cified anywhere,
291b0 20 74 68 65 20 41 42 4f 52 54 20 61 6c 67 6f 72   the ABORT algor
291c0 69 74 68 6d 20 69 73 20 75 73 65 64 2e 3c 2f 70  ithm is used.</p
291d0 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23  >..<tcl>.#######
291e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
291f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29200 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29210 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29220 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
29230 52 45 49 4e 44 45 58 20 72 65 69 6e 64 65 78 20  REINDEX reindex 
29240 52 45 49 4e 44 45 58 0a 0a 52 65 63 75 72 73 69  REINDEX..Recursi
29250 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
29260 72 65 69 6e 64 65 78 2d 73 74 6d 74 0a 3c 2f 74  reindex-stmt.</t
29270 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 52 45 49  cl>..<p>^The REI
29280 4e 44 45 58 20 63 6f 6d 6d 61 6e 64 20 69 73 20  NDEX command is 
29290 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  used to delete a
292a0 6e 64 20 72 65 63 72 65 61 74 65 20 69 6e 64 69  nd recreate indi
292b0 63 65 73 20 66 72 6f 6d 20 73 63 72 61 74 63 68  ces from scratch
292c0 2e 0a 54 68 69 73 20 69 73 20 75 73 65 66 75 6c  ..This is useful
292d0 20 77 68 65 6e 20 74 68 65 20 64 65 66 69 6e 69   when the defini
292e0 74 69 6f 6e 20 6f 66 20 61 20 63 6f 6c 6c 61 74  tion of a collat
292f0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 68 61 73  ion sequence has
29300 20 63 68 61 6e 67 65 64 2e 0a 3c 2f 70 3e 0a 0a   changed..</p>..
29310 3c 70 3e 5e 49 66 20 74 68 65 20 52 45 49 4e 44  <p>^If the REIND
29320 45 58 20 6b 65 79 77 6f 72 64 20 69 73 20 6e 6f  EX keyword is no
29330 74 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  t followed by a 
29340 63 6f 6c 6c 61 74 69 6f 6e 2d 73 65 71 75 65 6e  collation-sequen
29350 63 65 20 6f 72 20 64 61 74 61 62 61 73 65 20 0a  ce or database .
29360 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65  object identifie
29370 72 2c 20 74 68 65 6e 20 61 6c 6c 20 69 6e 64 69  r, then all indi
29380 63 65 73 20 69 6e 20 61 6c 6c 20 61 74 74 61 63  ces in all attac
29390 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
293a0 65 20 72 65 62 75 69 6c 74 2e 0a 0a 3c 70 3e 5e  e rebuilt...<p>^
293b0 49 66 20 74 68 65 20 52 45 49 4e 44 45 58 20 6b  If the REINDEX k
293c0 65 79 77 6f 72 64 20 69 73 20 66 6f 6c 6c 6f 77  eyword is follow
293d0 65 64 20 62 79 20 61 20 63 6f 6c 6c 61 74 69 6f  ed by a collatio
293e0 6e 2d 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 2c  n-sequence name,
293f0 20 74 68 65 6e 0a 61 6c 6c 20 69 6e 64 69 63 65   then.all indice
29400 73 20 69 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  s in all attache
29410 64 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  d databases that
29420 20 75 73 65 20 74 68 65 20 6e 61 6d 65 64 20 63   use the named c
29430 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
29440 65 73 0a 61 72 65 20 72 65 63 72 65 61 74 65 64  es.are recreated
29450 2e 20 0a 0a 3c 70 3e 5e 4f 72 2c 20 69 66 20 74  . ..<p>^Or, if t
29460 68 65 20 61 72 67 75 6d 65 6e 74 20 61 74 74 61  he argument atta
29470 63 68 65 64 20 74 6f 20 74 68 65 20 52 45 49 4e  ched to the REIN
29480 44 45 58 20 69 64 65 6e 74 69 66 69 65 73 20 61  DEX identifies a
29490 20 73 70 65 63 69 66 69 63 20 0a 64 61 74 61 62   specific .datab
294a0 61 73 65 20 74 61 62 6c 65 2c 20 74 68 65 6e 20  ase table, then 
294b0 61 6c 6c 20 69 6e 64 69 63 65 73 20 61 74 74 61  all indices atta
294c0 63 68 65 64 20 74 6f 20 74 68 65 20 64 61 74 61  ched to the data
294d0 62 61 73 65 20 74 61 62 6c 65 20 61 72 65 20 72  base table are r
294e0 65 62 75 69 6c 74 2e 20 0a 5e 49 66 20 69 74 20  ebuilt. .^If it 
294f0 69 64 65 6e 74 69 66 69 65 73 20 61 20 73 70 65  identifies a spe
29500 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20 69  cific database i
29510 6e 64 65 78 2c 20 74 68 65 6e 20 6a 75 73 74 20  ndex, then just 
29520 74 68 61 74 20 69 6e 64 65 78 20 69 73 20 72 65  that index is re
29530 63 72 65 61 74 65 64 2e 0a 0a 3c 70 3e 5e 46 6f  created...<p>^Fo
29540 72 20 61 20 63 6f 6d 6d 61 6e 64 20 6f 66 20 74  r a command of t
29550 68 65 20 66 6f 72 6d 20 22 52 45 49 4e 44 45 58  he form "REINDEX
29560 20 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 22 2c 20 61   <i>name</i>", a
29570 20 6d 61 74 63 68 0a 61 67 61 69 6e 73 74 20 3c   match.against <
29580 79 79 74 65 72 6d 3e 63 6f 6c 6c 61 74 69 6f 6e  yyterm>collation
29590 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 74  -name</yyterm> t
295a0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
295b0 6f 76 65 72 20 61 20 6d 61 74 63 68 0a 61 67 61  over a match.aga
295c0 69 6e 73 74 20 3c 79 79 74 65 72 6d 3e 69 6e 64  inst <yyterm>ind
295d0 65 78 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  ex-name</yyterm>
295e0 20 6f 72 20 3c 79 79 74 65 72 6d 3e 74 61 62 6c   or <yyterm>tabl
295f0 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2e  e-name</yyterm>.
29600 0a 54 68 69 73 20 61 6d 62 69 67 75 69 74 79 20  .This ambiguity 
29610 69 6e 20 74 68 65 20 73 79 6e 74 61 78 20 6d 61  in the syntax ma
29620 79 20 62 65 20 61 76 6f 69 64 65 64 20 62 79 20  y be avoided by 
29630 61 6c 77 61 79 73 20 73 70 65 63 69 66 79 69 6e  always specifyin
29640 67 20 61 0a 3c 79 79 74 65 72 6d 3e 73 63 68 65  g a.<yyterm>sche
29650 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  ma-name</yyterm>
29660 20 77 68 65 6e 20 72 65 69 6e 64 65 78 69 6e 67   when reindexing
29670 20 61 20 73 70 65 63 69 66 69 63 20 74 61 62 6c   a specific tabl
29680 65 20 6f 72 20 69 6e 64 65 78 2e 0a 0a 3c 74 63  e or index...<tc
29690 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  l>.#############
296a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
296b0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
296c0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
296d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
296e0 23 23 0a 53 65 63 74 69 6f 6e 20 52 45 50 4c 41  ##.Section REPLA
296f0 43 45 20 72 65 70 6c 61 63 65 20 52 45 50 4c 41  CE replace REPLA
29700 43 45 0a 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e  CE..</tcl>..<p>^
29710 54 68 65 20 52 45 50 4c 41 43 45 20 63 6f 6d 6d  The REPLACE comm
29720 61 6e 64 20 69 73 20 61 6e 20 61 6c 69 61 73 20  and is an alias 
29730 66 6f 72 20 74 68 65 20 22 5b 4f 4e 20 43 4f 4e  for the "[ON CON
29740 46 4c 49 43 54 20 7c 20 49 4e 53 45 52 54 20 4f  FLICT | INSERT O
29750 52 20 52 45 50 4c 41 43 45 5d 22 0a 76 61 72 69  R REPLACE]".vari
29760 61 6e 74 20 6f 66 20 74 68 65 20 5b 49 4e 53 45  ant of the [INSE
29770 52 54 5d 20 63 6f 6d 6d 61 6e 64 2e 20 20 0a 54  RT] command.  .T
29780 68 69 73 20 61 6c 69 61 73 20 69 73 20 70 72 6f  his alias is pro
29790 76 69 64 65 64 20 66 6f 72 20 63 6f 6d 70 61 74  vided for compat
297a0 69 62 69 6c 69 74 79 20 6f 74 68 65 72 20 53 51  ibility other SQ
297b0 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  L database engin
297c0 65 73 2e 20 20 53 65 65 20 74 68 65 20 0a 5b 49  es.  See the .[I
297d0 4e 53 45 52 54 5d 20 63 6f 6d 6d 61 6e 64 20 64  NSERT] command d
297e0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
297f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
29800 72 6d 61 74 69 6f 6e 2e 3c 2f 70 3e 20 20 0a 0a  rmation.</p>  ..
29810 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
29820 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29830 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29840 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29850 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29860 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 57  #####.Section {W
29870 49 54 48 20 63 6c 61 75 73 65 7d 20 77 69 74 68  ITH clause} with
29880 20 7b 7b 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20   {{common table 
29890 65 78 70 72 65 73 73 69 6f 6e 73 7d 20 57 49 54  expressions} WIT
298a0 48 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  H}..RecursiveBub
298b0 62 6c 65 44 69 61 67 72 61 6d 20 77 69 74 68 2d  bleDiagram with-
298c0 63 6c 61 75 73 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c  clause.</tcl>..<
298d0 70 3e 43 6f 6d 6d 6f 6e 20 54 61 62 6c 65 20 45  p>Common Table E
298e0 78 70 72 65 73 73 69 6f 6e 73 20 6f 72 20 43 54  xpressions or CT
298f0 45 73 20 61 63 74 20 6c 69 6b 65 20 74 65 6d 70  Es act like temp
29900 6f 72 61 72 79 20 5b 76 69 65 77 73 5d 20 74 68  orary [views] th
29910 61 74 20 65 78 69 73 74 0a 6f 6e 6c 79 20 66 6f  at exist.only fo
29920 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
29930 66 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  f a single SQL s
29940 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 72 65  tatement.  There
29950 20 61 72 65 20 74 77 6f 20 6b 69 6e 64 73 20 6f   are two kinds o
29960 66 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65  f.common table e
29970 78 70 72 65 73 73 69 6f 6e 73 3a 20 22 6f 72 64  xpressions: "ord
29980 69 6e 61 72 79 22 20 61 6e 64 20 22 72 65 63 75  inary" and "recu
29990 72 73 69 76 65 22 2e 20 4f 72 64 69 6e 61 72 79  rsive". Ordinary
299a0 20 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65   .common table e
299b0 78 70 72 65 73 73 69 6f 6e 73 20 61 72 65 20 68  xpressions are h
299c0 65 6c 70 66 75 6c 20 66 6f 72 20 6d 61 6b 69 6e  elpful for makin
299d0 67 0a 71 75 65 72 69 65 73 20 65 61 73 69 65 72  g.queries easier
299e0 20 74 6f 20 75 6e 64 65 72 73 74 61 6e 64 20 62   to understand b
299f0 79 20 66 61 63 74 6f 72 69 6e 67 0a 73 75 62 71  y factoring.subq
29a00 75 65 72 69 65 73 20 6f 75 74 20 6f 66 20 74 68  ueries out of th
29a10 65 20 6d 61 69 6e 20 53 51 4c 20 73 74 61 74 65  e main SQL state
29a20 6d 65 6e 74 2e 0a 52 65 63 75 72 73 69 76 65 20  ment..Recursive 
29a30 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70  common table exp
29a40 72 65 73 73 69 6f 6e 73 0a 70 72 6f 76 69 64 65  ressions.provide
29a50 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
29a60 64 6f 20 68 69 65 72 61 72 63 68 69 63 61 6c 20  do hierarchical 
29a70 6f 72 0a 72 65 63 75 72 73 69 76 65 20 71 75 65  or.recursive que
29a80 72 69 65 73 20 6f 66 20 74 72 65 65 73 20 61 6e  ries of trees an
29a90 64 20 67 72 61 70 68 73 2c 20 61 20 63 61 70 61  d graphs, a capa
29aa0 62 69 6c 69 74 79 0a 74 68 61 74 20 69 73 20 6e  bility.that is n
29ab0 6f 74 20 6f 74 68 65 72 77 69 73 65 20 61 76 61  ot otherwise ava
29ac0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51  ilable in the SQ
29ad0 4c 20 6c 61 6e 67 75 61 67 65 2e 0a 0a 3c 70 3e  L language...<p>
29ae0 41 6c 6c 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65  All common table
29af0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 28 6f 72   expressions (or
29b00 64 69 6e 61 72 79 20 61 6e 64 20 72 65 63 75 72  dinary and recur
29b10 73 69 76 65 29 20 61 72 65 20 0a 63 72 65 61 74  sive) are .creat
29b20 65 64 20 62 79 20 70 72 65 70 65 6e 64 69 6e 67  ed by prepending
29b30 20 61 20 57 49 54 48 20 63 6c 61 75 73 65 20 69   a WITH clause i
29b40 6e 20 66 72 6f 6e 74 20 6f 66 20 61 20 5b 53 45  n front of a [SE
29b50 4c 45 43 54 5d 2c 20 5b 49 4e 53 45 52 54 5d 2c  LECT], [INSERT],
29b60 20 5b 44 45 4c 45 54 45 5d 2c 0a 6f 72 20 5b 55   [DELETE],.or [U
29b70 50 44 41 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  PDATE] statement
29b80 2e 20 20 41 20 73 69 6e 67 6c 65 20 57 49 54 48  .  A single WITH
29b90 20 63 6c 61 75 73 65 20 63 61 6e 20 73 70 65 63   clause can spec
29ba0 69 66 79 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  ify one or more.
29bb0 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70  common table exp
29bc0 72 65 73 73 69 6f 6e 73 2c 20 73 6f 6d 65 20 6f  ressions, some o
29bd0 66 20 77 68 69 63 68 20 61 72 65 20 6f 72 64 69  f which are ordi
29be0 6e 61 72 79 20 61 6e 64 20 73 6f 6d 65 20 6f 66  nary and some of
29bf0 20 77 68 69 63 68 0a 61 72 65 20 72 65 63 75 72   which.are recur
29c00 73 69 76 65 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  sive...<tcl>hd_f
29c10 72 61 67 6d 65 6e 74 20 6f 72 64 69 6e 61 72 79  ragment ordinary
29c20 63 74 65 20 7b 6f 72 64 69 6e 61 72 79 20 63 6f  cte {ordinary co
29c30 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65  mmon table expre
29c40 73 73 69 6f 6e 73 7d 3c 2f 74 63 6c 3e 0a 3c 68  ssions}</tcl>.<h
29c50 33 3e 4f 72 64 69 6e 61 72 79 20 43 6f 6d 6d 6f  3>Ordinary Commo
29c60 6e 20 54 61 62 6c 65 20 45 78 70 72 65 73 73 69  n Table Expressi
29c70 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 6e 20  ons</h3>..<p>An 
29c80 6f 72 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20  ordinary common 
29c90 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e  table expression
29ca0 20 77 6f 72 6b 73 20 61 73 20 69 66 20 69 74 20   works as if it 
29cb0 77 65 72 65 20 61 20 5b 76 69 65 77 5d 20 74 68  were a [view] th
29cc0 61 74 0a 65 78 69 73 74 73 20 66 6f 72 20 74 68  at.exists for th
29cd0 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  e duration of a 
29ce0 73 69 6e 67 6c 65 20 73 74 61 74 65 6d 65 6e 74  single statement
29cf0 2e 20 20 4f 72 64 69 6e 61 72 79 20 63 6f 6d 6d  .  Ordinary comm
29d00 6f 6e 20 74 61 62 6c 65 0a 65 78 70 72 65 73 73  on table.express
29d10 69 6f 6e 73 20 61 72 65 20 75 73 65 66 75 6c 20  ions are useful 
29d20 66 6f 72 20 66 61 63 74 6f 72 69 6e 67 20 6f 75  for factoring ou
29d30 74 20 73 75 62 71 75 65 72 69 65 73 20 61 6e 64  t subqueries and
29d40 20 6d 61 6b 69 6e 67 20 74 68 65 20 6f 76 65 72   making the over
29d50 61 6c 6c 0a 53 51 4c 20 73 74 61 74 65 6d 65 6e  all.SQL statemen
29d60 74 20 65 61 73 69 65 72 20 74 6f 20 72 65 61 64  t easier to read
29d70 20 61 6e 64 20 75 6e 64 65 72 73 74 61 6e 64 2e   and understand.
29d80 0a 0a 3c 70 3e 41 20 57 49 54 48 20 63 6c 61 75  ..<p>A WITH clau
29d90 73 65 20 63 61 6e 20 63 6f 6e 74 61 69 6e 20 6f  se can contain o
29da0 72 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20 74  rdinary common t
29db0 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73  able expressions
29dc0 20 65 76 65 6e 20 69 66 0a 69 74 20 69 6e 63 6c   even if.it incl
29dd0 75 64 65 73 20 74 68 65 20 52 45 43 55 52 53 49  udes the RECURSI
29de0 56 45 20 6b 65 79 77 6f 72 64 2e 20 20 54 68 65  VE keyword.  The
29df0 20 75 73 65 20 6f 66 20 52 45 43 55 52 53 49 56   use of RECURSIV
29e00 45 20 64 6f 65 73 20 6e 6f 74 20 66 6f 72 63 65  E does not force
29e10 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78  .common table ex
29e20 70 72 65 73 73 69 6f 6e 73 20 74 6f 20 62 65 20  pressions to be 
29e30 72 65 63 75 72 73 69 76 65 2e 0a 0a 3c 74 63 6c  recursive...<tcl
29e40 3e 0a 68 64 5f 66 72 61 67 6d 65 6e 74 20 72 65  >.hd_fragment re
29e50 63 75 72 73 69 76 65 63 74 65 20 7b 72 65 63 75  cursivecte {recu
29e60 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74 61 62  rsive common tab
29e70 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 73 7d 20  le expressions} 
29e80 5c 0a 7b 72 65 63 75 72 73 69 76 65 20 63 6f 6d  \.{recursive com
29e90 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
29ea0 73 69 6f 6e 7d 20 7b 72 65 63 75 72 73 69 76 65  sion} {recursive
29eb0 20 71 75 65 72 79 7d 0a 3c 2f 74 63 6c 3e 0a 3c   query}.</tcl>.<
29ec0 68 33 3e 52 65 63 75 72 73 69 76 65 20 43 6f 6d  h3>Recursive Com
29ed0 6d 6f 6e 20 54 61 62 6c 65 20 45 78 70 72 65 73  mon Table Expres
29ee0 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 41  sions</h3>..<p>A
29ef0 20 72 65 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f   recursive commo
29f00 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69  n table expressi
29f10 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
29f20 6f 20 77 72 69 74 65 20 61 20 71 75 65 72 79 20  o write a query 
29f30 74 68 61 74 0a 77 61 6c 6b 73 20 61 20 74 72 65  that.walks a tre
29f40 65 20 6f 72 20 67 72 61 70 68 2e 20 20 41 20 72  e or graph.  A r
29f50 65 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20  ecursive common 
29f60 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e  table expression
29f70 20 68 61 73 20 74 68 65 20 73 61 6d 65 0a 62 61   has the same.ba
29f80 73 69 63 20 73 79 6e 74 61 78 20 61 73 20 61 6e  sic syntax as an
29f90 20 6f 72 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e   ordinary common
29fa0 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f   table expressio
29fb0 6e 2c 20 62 75 74 20 77 69 74 68 20 74 68 65 20  n, but with the 
29fc0 66 6f 6c 6c 6f 77 69 6e 67 0a 61 64 64 69 74 69  following.additi
29fd0 6f 6e 61 6c 20 66 65 61 74 75 72 65 73 3a 0a 0a  onal features:..
29fe0 3c 6f 6c 3e 0a 3c 6c 69 3e 20 54 68 65 20 22 5b  <ol>.<li> The "[
29ff0 73 65 6c 65 63 74 2d 73 74 6d 74 5d 22 0a 20 20  select-stmt]".  
2a000 20 20 20 6d 75 73 74 20 62 65 20 61 20 5b 63 6f     must be a [co
2a010 6d 70 6f 75 6e 64 20 73 65 6c 65 63 74 5d 20 77  mpound select] w
2a020 68 65 72 65 20 74 68 65 20 72 69 67 68 74 2d 6d  here the right-m
2a030 6f 73 74 20 5b 63 6f 6d 70 6f 75 6e 64 2d 6f 70  ost [compound-op
2a040 65 72 61 74 6f 72 5d 20 69 73 0a 20 20 20 20 20  erator] is.     
2a050 65 69 74 68 65 72 20 55 4e 49 4f 4e 20 6f 72 20  either UNION or 
2a060 55 4e 49 4f 4e 20 41 4c 4c 2e 0a 3c 6c 69 3e 20  UNION ALL..<li> 
2a070 54 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 64 20  The table named 
2a080 6f 6e 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  on the left-hand
2a090 20 73 69 64 65 20 6f 66 20 74 68 65 20 41 53 20   side of the AS 
2a0a0 6b 65 79 77 6f 72 64 20 6d 75 73 74 20 61 70 70  keyword must app
2a0b0 65 61 72 0a 20 20 20 20 20 65 78 61 63 74 6c 79  ear.     exactly
2a0c0 20 6f 6e 63 65 20 69 6e 20 74 68 65 20 46 52 4f   once in the FRO
2a0d0 4d 20 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20  M clause of the 
2a0e0 72 69 67 68 74 2d 6d 6f 73 74 20 53 45 4c 45 43  right-most SELEC
2a0f0 54 20 73 74 61 74 65 6d 65 6e 74 0a 20 20 20 20  T statement.    
2a100 20 6f 66 20 74 68 65 20 63 6f 6d 70 6f 75 6e 64   of the compound
2a110 20 73 65 6c 65 63 74 2c 20 61 6e 64 20 6e 6f 77   select, and now
2a120 68 65 72 65 20 65 6c 73 65 2e 0a 3c 6c 69 3e 20  here else..<li> 
2a130 54 68 65 20 72 69 67 68 74 2d 6d 6f 73 74 20 53  The right-most S
2a140 45 4c 45 43 54 20 6f 66 20 74 68 65 20 63 6f 6d  ELECT of the com
2a150 70 6f 75 6e 64 20 73 65 6c 65 63 74 20 6d 75 73  pound select mus
2a160 74 20 6e 6f 74 20 6d 61 6b 65 20 75 73 65 20 6f  t not make use o
2a170 66 0a 20 20 20 20 20 5b 41 67 67 72 65 67 61 74  f.     [Aggregat
2a180 65 20 46 75 6e 63 74 69 6f 6e 73 7c 61 67 67 72  e Functions|aggr
2a190 65 67 61 74 65 5d 20 6f 72 20 5b 77 69 6e 64 6f  egate] or [windo
2a1a0 77 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 3c 2f  w functions]..</
2a1b0 6f 6c 3e 0a 0a 3c 70 3e 54 6f 20 70 75 74 20 69  ol>..<p>To put i
2a1c0 74 20 61 6e 6f 74 68 65 72 20 77 61 79 2c 20 61  t another way, a
2a1d0 20 72 65 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f   recursive commo
2a1e0 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69  n table expressi
2a1f0 6f 6e 20 6d 75 73 74 0a 6c 6f 6f 6b 20 6c 69 6b  on must.look lik
2a200 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  e the following:
2a210 0a 0a 3c 74 63 6c 3e 52 65 63 75 72 73 69 76 65  ..<tcl>Recursive
2a220 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 65  BubbleDiagram re
2a230 63 75 72 73 69 76 65 2d 63 74 65 3c 2f 74 63 6c  cursive-cte</tcl
2a240 3e 0a 0a 3c 70 3e 43 61 6c 6c 20 74 68 65 20 74  >..<p>Call the t
2a250 61 62 6c 65 20 6e 61 6d 65 64 20 62 79 20 74 68  able named by th
2a260 65 20 5b 63 74 65 2d 74 61 62 6c 65 2d 6e 61 6d  e [cte-table-nam
2a270 65 5d 20 69 6e 20 61 20 72 65 63 75 72 73 69 76  e] in a recursiv
2a280 65 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65  e.common table e
2a290 78 70 72 65 73 73 69 6f 6e 20 74 68 65 20 22 72  xpression the "r
2a2a0 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 22 2e  ecursive table".
2a2b0 0a 49 6e 20 74 68 65 20 5b 72 65 63 75 72 73 69  .In the [recursi
2a2c0 76 65 2d 63 74 65 5d 20 62 75 62 62 6c 65 20 64  ve-cte] bubble d
2a2d0 69 61 67 72 61 6d 20 61 62 6f 76 65 2c 20 74 68  iagram above, th
2a2e0 65 20 72 65 63 75 72 73 69 76 65 0a 74 61 62 6c  e recursive.tabl
2a2f0 65 20 6d 75 73 74 20 61 70 70 65 61 72 20 65 78  e must appear ex
2a300 61 63 74 6c 79 20 6f 6e 63 65 20 69 6e 20 74 68  actly once in th
2a310 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f 66  e FROM clause of
2a320 20 74 68 65 20 0a 3c 79 79 74 65 72 6d 3e 72 65   the .<yyterm>re
2a330 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 3c 2f  cursive-select</
2a340 79 79 74 65 72 6d 3e 0a 61 6e 64 20 6d 75 73 74  yyterm>.and must
2a350 20 6e 6f 74 20 61 70 70 65 61 72 20 61 6e 79 77   not appear anyw
2a360 68 65 72 65 20 65 6c 73 65 20 69 6e 20 65 69 74  here else in eit
2a370 68 65 72 20 74 68 65 0a 3c 79 79 74 65 72 6d 3e  her the.<yyterm>
2a380 69 6e 69 74 69 61 6c 2d 73 65 6c 65 63 74 3c 2f  initial-select</
2a390 79 79 74 65 72 6d 3e 20 6f 72 20 74 68 65 0a 3c  yyterm> or the.<
2a3a0 79 79 74 65 72 6d 3e 72 65 63 75 72 73 69 76 65  yyterm>recursive
2a3b0 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e  -select</yyterm>
2a3c0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 75 62 71  , including subq
2a3d0 75 65 72 69 65 73 2e 0a 54 68 65 20 3c 79 79 74  ueries..The <yyt
2a3e0 65 72 6d 3e 69 6e 69 74 69 61 6c 2d 73 65 6c 65  erm>initial-sele
2a3f0 63 74 3c 2f 79 79 74 65 72 6d 3e 20 6d 61 79 20  ct</yyterm> may 
2a400 62 65 0a 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 73  be.a [compound s
2a410 65 6c 65 63 74 5d 2c 20 62 75 74 20 69 74 20 6d  elect], but it m
2a420 61 79 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 61  ay not include a
2a430 6e 20 4f 52 44 45 52 20 42 59 2c 20 4c 49 4d 49  n ORDER BY, LIMI
2a440 54 2c 20 6f 72 20 4f 46 46 53 45 54 2e 0a 54 68  T, or OFFSET..Th
2a450 65 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65  e recursive-sele
2a460 63 74 20 6d 75 73 74 20 62 65 20 61 20 73 69 6d  ct must be a sim
2a470 70 6c 65 20 73 65 6c 65 63 74 2c 20 6e 6f 74 20  ple select, not 
2a480 61 20 63 6f 6d 70 6f 75 6e 64 2e 20 20 54 68 65  a compound.  The
2a490 0a 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63  .recursive-selec
2a4a0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  t is allowed to 
2a4b0 69 6e 63 6c 75 64 65 20 61 6e 20 4f 52 44 45 52  include an ORDER
2a4c0 20 42 59 2c 20 4c 49 4d 49 54 2c 20 61 6e 64 2f   BY, LIMIT, and/
2a4d0 6f 72 20 4f 46 46 53 45 54 2e 0a 0a 3c 70 3e 54  or OFFSET...<p>T
2a4e0 68 65 20 62 61 73 69 63 20 61 6c 67 6f 72 69 74  he basic algorit
2a4f0 68 6d 20 66 6f 72 20 63 6f 6d 70 75 74 69 6e 67  hm for computing
2a500 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2a510 74 68 65 20 72 65 63 75 72 73 69 76 65 20 74 61  the recursive ta
2a520 62 6c 65 0a 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ble.is as follow
2a530 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 52 75  s:..<ol>.<li> Ru
2a540 6e 20 74 68 65 20 3c 79 79 74 65 72 6d 3e 69 6e  n the <yyterm>in
2a550 69 74 69 61 6c 2d 73 65 6c 65 63 74 3c 2f 79 79  itial-select</yy
2a560 74 65 72 6d 3e 20 61 6e 64 20 61 64 64 20 74 68  term> and add th
2a570 65 20 72 65 73 75 6c 74 73 20 74 6f 20 61 20 71  e results to a q
2a580 75 65 75 65 2e 0a 3c 6c 69 3e 20 57 68 69 6c 65  ueue..<li> While
2a590 20 74 68 65 20 71 75 65 75 65 20 69 73 20 6e 6f   the queue is no
2a5a0 74 20 65 6d 70 74 79 3a 0a 3c 6f 6c 20 74 79 70  t empty:.<ol typ
2a5b0 65 3d 22 61 22 3e 0a 3c 6c 69 3e 20 45 78 74 72  e="a">.<li> Extr
2a5c0 61 63 74 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  act a single row
2a5d0 20 66 72 6f 6d 20 74 68 65 20 71 75 65 75 65 2e   from the queue.
2a5e0 0a 3c 6c 69 3e 20 49 6e 73 65 72 74 20 74 68 61  .<li> Insert tha
2a5f0 74 20 73 69 6e 67 6c 65 20 72 6f 77 20 69 6e 74  t single row int
2a600 6f 20 74 68 65 20 72 65 63 75 72 73 69 76 65 20  o the recursive 
2a610 74 61 62 6c 65 0a 3c 6c 69 3e 20 50 72 65 74 65  table.<li> Prete
2a620 6e 64 20 74 68 61 74 20 74 68 65 20 73 69 6e 67  nd that the sing
2a630 6c 65 20 72 6f 77 20 6a 75 73 74 20 65 78 74 72  le row just extr
2a640 61 63 74 65 64 20 69 73 20 74 68 65 20 6f 6e 6c  acted is the onl
2a650 79 0a 20 20 20 20 20 72 6f 77 20 69 6e 20 74 68  y.     row in th
2a660 65 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c  e recursive tabl
2a670 65 20 61 6e 64 20 72 75 6e 20 74 68 65 20 72 65  e and run the re
2a680 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 2c 0a  cursive-select,.
2a690 20 20 20 20 20 61 64 64 69 6e 67 20 61 6c 6c 20       adding all 
2a6a0 72 65 73 75 6c 74 73 20 74 6f 20 74 68 65 20 71  results to the q
2a6b0 75 65 75 65 2e 0a 3c 2f 6f 6c 3e 0a 3c 2f 6f 6c  ueue..</ol>.</ol
2a6c0 3e 0a 0a 3c 70 3e 54 68 65 20 62 61 73 69 63 20  >..<p>The basic 
2a6d0 70 72 6f 63 65 64 75 72 65 20 61 62 6f 76 65 20  procedure above 
2a6e0 6d 61 79 20 6d 6f 64 69 66 69 65 64 20 62 79 20  may modified by 
2a6f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 64  the following ad
2a700 64 69 74 69 6f 6e 61 6c 20 72 75 6c 65 73 3a 0a  ditional rules:.
2a710 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 20 20  .<ul>.<li><p>.  
2a720 49 66 20 61 20 55 4e 49 4f 4e 20 6f 70 65 72 61  If a UNION opera
2a730 74 6f 72 20 63 6f 6e 6e 65 63 74 73 20 74 68 65  tor connects the
2a740 20 3c 79 79 74 65 72 6d 3e 69 6e 69 74 69 61 6c   <yyterm>initial
2a750 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e  -select</yyterm>
2a760 20 77 69 74 68 20 74 68 65 0a 20 20 3c 79 79 74   with the.  <yyt
2a770 65 72 6d 3e 72 65 63 75 72 73 69 76 65 2d 73 65  erm>recursive-se
2a780 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e 2c 20 74  lect</yyterm>, t
2a790 68 65 6e 20 6f 6e 6c 79 20 61 64 64 20 72 6f 77  hen only add row
2a7a0 73 20 74 6f 20 74 68 65 20 71 75 65 75 65 20 69  s to the queue i
2a7b0 66 20 0a 20 20 6e 6f 20 69 64 65 6e 74 69 63 61  f .  no identica
2a7c0 6c 20 72 6f 77 20 68 61 73 0a 20 20 62 65 65 6e  l row has.  been
2a7d0 20 70 72 65 76 69 6f 75 73 6c 79 20 61 64 64 65   previously adde
2a7e0 64 20 74 6f 20 74 68 65 20 71 75 65 75 65 2e 20  d to the queue. 
2a7f0 20 52 65 70 65 61 74 65 64 20 72 6f 77 73 20 61   Repeated rows a
2a800 72 65 20 64 69 73 63 61 72 64 65 64 20 62 65 66  re discarded bef
2a810 6f 72 65 20 62 65 69 6e 67 0a 20 20 61 64 64 65  ore being.  adde
2a820 64 20 74 6f 20 74 68 65 20 71 75 65 75 65 20 65  d to the queue e
2a830 76 65 6e 20 69 66 20 74 68 65 20 72 65 70 65 61  ven if the repea
2a840 74 65 64 20 72 6f 77 73 20 68 61 76 65 20 61 6c  ted rows have al
2a850 72 65 61 64 79 20 62 65 65 6e 20 65 78 74 72 61  ready been extra
2a860 63 74 65 64 0a 20 20 66 72 6f 6d 20 74 68 65 20  cted.  from the 
2a870 71 75 65 75 65 20 62 79 20 74 68 65 20 72 65 63  queue by the rec
2a880 75 72 73 69 6f 6e 20 73 74 65 70 2e 20 20 49 66  ursion step.  If
2a890 20 74 68 65 20 6f 70 65 72 61 74 6f 72 20 69 73   the operator is
2a8a0 20 55 4e 49 4f 4e 20 41 4c 4c 2c 0a 20 20 74 68   UNION ALL,.  th
2a8b0 65 6e 20 61 6c 6c 20 72 6f 77 73 20 67 65 6e 65  en all rows gene
2a8c0 72 61 74 65 64 20 62 79 20 62 6f 74 68 20 74 68  rated by both th
2a8d0 65 20 3c 79 79 74 65 72 6d 3e 69 6e 69 74 69 61  e <yyterm>initia
2a8e0 6c 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d  l-select</yyterm
2a8f0 3e 20 61 6e 64 20 74 68 65 0a 20 20 3c 79 79 74  > and the.  <yyt
2a900 65 72 6d 3e 72 65 63 75 72 73 69 76 65 2d 73 65  erm>recursive-se
2a910 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e 20 61 72  lect</yyterm> ar
2a920 65 20 61 6c 77 61 79 73 20 61 64 64 65 64 20 74  e always added t
2a930 6f 20 74 68 65 20 71 75 65 75 65 20 65 76 65 6e  o the queue even
2a940 20 69 66 0a 20 20 74 68 65 79 20 61 72 65 20 72   if.  they are r
2a950 65 70 65 61 74 73 2e 0a 20 20 57 68 65 6e 20 64  epeats..  When d
2a960 65 74 65 72 6d 69 6e 69 6e 67 20 69 66 20 61 20  etermining if a 
2a970 72 6f 77 20 69 73 20 72 65 70 65 61 74 65 64 2c  row is repeated,
2a980 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 63 6f 6d   NULL values com
2a990 70 61 72 65 0a 20 20 65 71 75 61 6c 20 74 6f 20  pare.  equal to 
2a9a0 6f 6e 65 20 61 6e 6f 74 68 65 72 20 61 6e 64 20  one another and 
2a9b0 6e 6f 74 20 65 71 75 61 6c 20 74 6f 20 61 6e 79  not equal to any
2a9c0 20 6f 74 68 65 72 20 76 61 6c 75 65 2e 0a 3c 6c   other value..<l
2a9d0 69 3e 3c 70 3e 0a 20 20 54 68 65 20 4c 49 4d 49  i><p>.  The LIMI
2a9e0 54 20 63 6c 61 75 73 65 2c 20 69 66 20 70 72 65  T clause, if pre
2a9f0 73 65 6e 74 2c 20 64 65 74 65 72 6d 69 6e 65 73  sent, determines
2aa00 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
2aa10 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74  ber of rows that
2aa20 0a 20 20 77 69 6c 6c 20 65 76 65 72 20 62 65 20  .  will ever be 
2aa30 61 64 64 65 64 20 74 6f 20 74 68 65 20 72 65 63  added to the rec
2aa40 75 72 73 69 76 65 20 74 61 62 6c 65 20 69 6e 20  ursive table in 
2aa50 73 74 65 70 20 32 62 2e 0a 20 20 4f 6e 63 65 20  step 2b..  Once 
2aa60 74 68 65 20 6c 69 6d 69 74 20 69 73 20 72 65 61  the limit is rea
2aa70 63 68 65 64 2c 20 74 68 65 20 72 65 63 75 72 73  ched, the recurs
2aa80 69 6f 6e 20 73 74 6f 70 73 2e 0a 20 20 41 20 6c  ion stops..  A l
2aa90 69 6d 69 74 20 6f 66 20 7a 65 72 6f 20 6d 65 61  imit of zero mea
2aaa0 6e 73 20 74 68 61 74 20 6e 6f 20 72 6f 77 73 20  ns that no rows 
2aab0 61 72 65 20 65 76 65 72 20 61 64 64 65 64 20 74  are ever added t
2aac0 6f 20 74 68 65 0a 20 20 72 65 63 75 72 73 69 76  o the.  recursiv
2aad0 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 61 20 6e  e table, and a n
2aae0 65 67 61 74 69 76 65 20 6c 69 6d 69 74 20 6d 65  egative limit me
2aaf0 61 6e 73 20 61 6e 20 75 6e 6c 69 6d 69 74 65 64  ans an unlimited
2ab00 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
2ab10 20 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 74    may be added t
2ab20 6f 20 74 68 65 20 72 65 63 75 72 73 69 76 65 20  o the recursive 
2ab30 74 61 62 6c 65 2e 0a 3c 6c 69 3e 3c 70 3e 0a 20  table..<li><p>. 
2ab40 20 54 68 65 20 4f 46 46 53 45 54 20 63 6c 61 75   The OFFSET clau
2ab50 73 65 2c 20 69 66 20 69 74 20 69 73 20 70 72 65  se, if it is pre
2ab60 73 65 6e 74 20 61 6e 64 20 68 61 73 20 61 20 70  sent and has a p
2ab70 6f 73 69 74 69 76 65 20 76 61 6c 75 65 20 4e 2c  ositive value N,
2ab80 20 70 72 65 76 65 6e 74 73 20 74 68 65 0a 20 20   prevents the.  
2ab90 66 69 72 73 74 20 4e 20 72 6f 77 73 20 66 72 6f  first N rows fro
2aba0 6d 20 62 65 69 6e 67 20 61 64 64 65 64 20 74 6f  m being added to
2abb0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 20 74   the recursive t
2abc0 61 62 6c 65 2e 0a 20 20 54 68 65 20 66 69 72 73  able..  The firs
2abd0 74 20 4e 20 72 6f 77 73 20 61 72 65 20 73 74 69  t N rows are sti
2abe0 6c 6c 20 70 72 6f 63 65 73 73 65 64 0a 20 20 62  ll processed.  b
2abf0 79 20 74 68 65 20 3c 79 79 74 65 72 6d 3e 72 65  y the <yyterm>re
2ac00 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 3c 2f  cursive-select</
2ac10 79 79 74 65 72 6d 3e 20 26 6d 64 61 73 68 3b 20  yyterm> &mdash; 
2ac20 74 68 65 79 0a 20 20 6a 75 73 74 20 61 72 65 20  they.  just are 
2ac30 6e 6f 74 20 61 64 64 65 64 20 74 6f 20 74 68 65  not added to the
2ac40 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65   recursive table
2ac50 2e 20 20 52 6f 77 73 20 61 72 65 20 6e 6f 74 20  .  Rows are not 
2ac60 63 6f 75 6e 74 65 64 20 74 6f 77 61 72 64 0a 20  counted toward. 
2ac70 20 66 75 6c 66 69 6c 6c 69 6e 67 20 74 68 65 20   fulfilling the 
2ac80 4c 49 4d 49 54 20 75 6e 74 69 6c 20 61 6c 6c 20  LIMIT until all 
2ac90 4f 46 46 53 45 54 20 72 6f 77 73 20 68 61 76 65  OFFSET rows have
2aca0 20 62 65 65 6e 20 73 6b 69 70 70 65 64 2e 0a 3c   been skipped..<
2acb0 6c 69 3e 3c 70 3e 0a 20 20 49 66 20 61 6e 20 4f  li><p>.  If an O
2acc0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
2acd0 73 20 70 72 65 73 65 6e 74 2c 20 69 74 20 64 65  s present, it de
2ace0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 6f 72 64  termines the ord
2acf0 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f 77 73  er in which rows
2ad00 0a 20 20 61 72 65 20 65 78 74 72 61 63 74 65 64  .  are extracted
2ad10 20 66 72 6f 6d 20 74 68 65 20 71 75 65 75 65 20   from the queue 
2ad20 69 6e 20 73 74 65 70 20 32 61 2e 20 20 49 66 20  in step 2a.  If 
2ad30 74 68 65 72 65 20 69 73 20 6e 6f 20 4f 52 44 45  there is no ORDE
2ad40 52 20 42 59 20 63 6c 61 75 73 65 2c 0a 20 20 74  R BY clause,.  t
2ad50 68 65 6e 20 74 68 65 20 6f 72 64 65 72 20 69 6e  hen the order in
2ad60 20 77 68 69 63 68 20 72 6f 77 73 20 61 72 65 20   which rows are 
2ad70 65 78 74 72 61 63 74 65 64 20 69 73 20 75 6e 64  extracted is und
2ad80 65 66 69 6e 65 64 2e 20 20 28 49 6e 20 74 68 65  efined.  (In the
2ad90 20 63 75 72 72 65 6e 74 0a 20 20 69 6d 70 6c 65   current.  imple
2ada0 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 71  mentation, the q
2adb0 75 65 75 65 20 62 65 63 6f 6d 65 73 20 61 20 46  ueue becomes a F
2adc0 49 46 4f 20 69 66 20 74 68 65 20 4f 52 44 45 52  IFO if the ORDER
2add0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 6f 6d   BY clause is om
2ade0 69 74 74 65 64 2c 0a 20 20 62 75 74 20 61 70 70  itted,.  but app
2adf0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2ae00 20 6e 6f 74 20 64 65 70 65 6e 64 20 6f 6e 20 74   not depend on t
2ae10 68 61 74 20 66 61 63 74 20 73 69 6e 63 65 20 69  hat fact since i
2ae20 74 20 6d 69 67 68 74 20 63 68 61 6e 67 65 2e 29  t might change.)
2ae30 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  .</ul>..<tcl>hd_
2ae40 66 72 61 67 6d 65 6e 74 20 72 63 65 78 31 3c 2f  fragment rcex1</
2ae50 74 63 6c 3e 0a 3c 68 34 3e 52 65 63 75 72 73 69  tcl>.<h4>Recursi
2ae60 76 65 20 51 75 65 72 79 20 45 78 61 6d 70 6c 65  ve Query Example
2ae70 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 66  s</h4>..<p>The f
2ae80 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 72  ollowing query r
2ae90 65 74 75 72 6e 73 20 61 6c 6c 20 69 6e 74 65 67  eturns all integ
2aea0 65 72 73 20 62 65 74 77 65 65 6e 20 31 20 61 6e  ers between 1 an
2aeb0 64 20 31 30 30 30 30 30 30 3a 0a 0a 3c 62 6c 6f  d 1000000:..<blo
2aec0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57 49  ckquote><pre>.WI
2aed0 54 48 20 52 45 43 55 52 53 49 56 45 0a 20 20 63  TH RECURSIVE.  c
2aee0 6e 74 28 78 29 20 41 53 20 28 56 41 4c 55 45 53  nt(x) AS (VALUES
2aef0 28 31 29 20 55 4e 49 4f 4e 20 41 4c 4c 20 53 45  (1) UNION ALL SE
2af00 4c 45 43 54 20 78 2b 31 20 46 52 4f 4d 20 63 6e  LECT x+1 FROM cn
2af10 74 20 57 48 45 52 45 20 78 3c 31 30 30 30 30 30  t WHERE x<100000
2af20 30 29 0a 53 45 4c 45 43 54 20 78 20 46 52 4f 4d  0).SELECT x FROM
2af30 20 63 6e 74 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c   cnt;.</pre></bl
2af40 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 43 6f  ockquote>..<p>Co
2af50 6e 73 69 64 65 72 20 68 6f 77 20 74 68 69 73 20  nsider how this 
2af60 71 75 65 72 79 20 77 6f 72 6b 73 2e 20 20 54 68  query works.  Th
2af70 65 20 69 6e 69 74 69 61 6c 2d 73 65 6c 65 63 74  e initial-select
2af80 0a 72 75 6e 73 20 66 69 72 73 74 20 61 6e 64 20  .runs first and 
2af90 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67 6c 65  returns a single
2afa0 20 72 6f 77 0a 77 69 74 68 20 61 20 73 69 6e 67   row.with a sing
2afb0 6c 65 20 63 6f 6c 75 6d 6e 20 22 31 22 2e 20 20  le column "1".  
2afc0 54 68 69 73 20 6f 6e 65 20 72 6f 77 20 69 73 20  This one row is 
2afd0 61 64 64 65 64 20 74 6f 20 74 68 65 20 71 75 65  added to the que
2afe0 75 65 2e 20 20 49 6e 0a 73 74 65 70 20 32 61 2c  ue.  In.step 2a,
2aff0 20 74 68 61 74 20 6f 6e 65 20 72 6f 77 20 69 73   that one row is
2b000 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
2b010 74 68 65 20 71 75 65 75 65 20 61 6e 64 20 61 64  the queue and ad
2b020 64 65 64 20 74 6f 20 22 63 6e 74 22 2e 0a 54 68  ded to "cnt"..Th
2b030 65 6e 20 74 68 65 20 72 65 63 75 72 73 69 76 65  en the recursive
2b040 2d 73 65 6c 65 63 74 20 69 73 20 72 75 6e 20 69  -select is run i
2b050 6e 20 61 63 63 6f 72 64 61 6e 63 65 20 77 69 74  n accordance wit
2b060 68 20 73 74 65 70 20 32 63 20 67 65 6e 65 72 61  h step 2c genera
2b070 74 69 6e 67 0a 61 20 73 69 6e 67 6c 65 20 6e 65  ting.a single ne
2b080 77 20 72 6f 77 20 77 69 74 68 20 76 61 6c 75 65  w row with value
2b090 20 22 32 22 20 74 6f 20 61 64 64 20 74 6f 20 74   "2" to add to t
2b0a0 68 65 20 71 75 65 75 65 2e 20 20 54 68 65 20 71  he queue.  The q
2b0b0 75 65 75 65 20 73 74 69 6c 6c 0a 68 61 73 20 6f  ueue still.has o
2b0c0 6e 65 20 72 6f 77 2c 20 73 6f 20 73 74 65 70 20  ne row, so step 
2b0d0 32 20 72 65 70 65 61 74 73 2e 20 20 54 68 65 20  2 repeats.  The 
2b0e0 22 32 22 20 72 6f 77 20 69 73 20 65 78 74 72 61  "2" row is extra
2b0f0 63 74 65 64 20 61 6e 64 20 61 64 64 65 64 20 74  cted and added t
2b100 6f 20 74 68 65 0a 72 65 63 75 72 73 69 76 65 20  o the.recursive 
2b110 74 61 62 6c 65 20 62 79 20 73 74 65 70 73 20 32  table by steps 2
2b120 61 20 61 6e 64 20 32 62 2e 20 20 54 68 65 6e 20  a and 2b.  Then 
2b130 74 68 65 20 72 6f 77 20 63 6f 6e 74 61 69 6e 69  the row containi
2b140 6e 67 20 32 20 69 73 20 75 73 65 64 20 0a 61 73  ng 2 is used .as
2b150 20 69 66 20 69 74 20 77 65 72 65 20 74 68 65 20   if it were the 
2b160 63 6f 6d 70 6c 65 74 65 20 63 6f 6e 74 65 6e 74  complete content
2b170 20 6f 66 20 74 68 65 20 72 65 63 75 72 73 69 76   of the recursiv
2b180 65 20 74 61 62 6c 65 20 61 6e 64 20 74 68 65 20  e table and the 
2b190 0a 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63  .recursive-selec
2b1a0 74 20 69 73 20 72 75 6e 20 61 67 61 69 6e 2c 20  t is run again, 
2b1b0 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 61 20 72  resulting in a r
2b1c0 6f 77 20 77 69 74 68 20 76 61 6c 75 65 20 22 33  ow with value "3
2b1d0 22 20 62 65 69 6e 67 20 61 64 64 65 64 0a 74 6f  " being added.to
2b1e0 20 74 68 65 20 71 75 65 75 65 2e 20 20 54 68 69   the queue.  Thi
2b1f0 73 20 72 65 70 65 61 74 73 20 39 39 39 39 39 39  s repeats 999999
2b200 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 66 69 6e   times until fin
2b210 61 6c 6c 79 20 61 74 20 73 74 65 70 20 32 61 20  ally at step 2a 
2b220 74 68 65 0a 6f 6e 6c 79 20 76 61 6c 75 65 20 6f  the.only value o
2b230 6e 20 74 68 65 20 71 75 65 75 65 20 69 73 20 61  n the queue is a
2b240 20 72 6f 77 20 63 6f 6e 74 61 69 6e 69 6e 67 20   row containing 
2b250 31 30 30 30 30 30 30 2e 20 20 54 68 61 74 20 72  1000000.  That r
2b260 6f 77 20 69 73 0a 65 78 74 72 61 63 74 65 64 20  ow is.extracted 
2b270 61 6e 64 20 61 64 64 65 64 20 74 6f 20 74 68 65  and added to the
2b280 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65   recursive table
2b290 2e 20 20 42 75 74 20 74 68 69 73 20 74 69 6d 65  .  But this time
2b2a0 2c 20 74 68 65 0a 57 48 45 52 45 20 63 6c 61 75  , the.WHERE clau
2b2b0 73 65 20 63 61 75 73 65 73 20 74 68 65 20 72 65  se causes the re
2b2c0 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 20 74  cursive-select t
2b2d0 6f 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73  o return no rows
2b2e0 2c 20 73 6f 20 74 68 65 0a 71 75 65 75 65 20 72  , so the.queue r
2b2f0 65 6d 61 69 6e 73 20 65 6d 70 74 79 20 61 6e 64  emains empty and
2b300 20 74 68 65 20 72 65 63 75 72 73 69 6f 6e 20 73   the recursion s
2b310 74 6f 70 73 2e 0a 0a 3c 70 3e 3c 62 3e 4f 70 74  tops...<p><b>Opt
2b320 69 6d 69 7a 61 74 69 6f 6e 20 6e 6f 74 65 3a 3c  imization note:<
2b330 2f 62 3e 0a 49 6e 20 74 68 65 20 64 69 73 63 75  /b>.In the discu
2b340 73 73 69 6f 6e 20 61 62 6f 76 65 2c 20 73 74 61  ssion above, sta
2b350 74 65 6d 65 6e 74 73 20 6c 69 6b 65 20 22 69 6e  tements like "in
2b360 73 65 72 74 20 74 68 65 20 72 6f 77 20 69 6e 74  sert the row int
2b370 6f 0a 74 68 65 20 72 65 63 75 72 73 69 76 65 20  o.the recursive 
2b380 74 61 62 6c 65 22 20 73 68 6f 75 6c 64 20 62 65  table" should be
2b390 20 75 6e 64 65 72 73 74 6f 6f 64 20 63 6f 6e 63   understood conc
2b3a0 65 70 74 75 61 6c 6c 79 2c 20 6e 6f 74 20 6c 69  eptually, not li
2b3b0 74 65 72 61 6c 6c 79 2e 0a 49 74 20 73 6f 75 6e  terally..It soun
2b3c0 64 73 20 61 73 20 69 66 20 53 51 4c 69 74 65 20  ds as if SQLite 
2b3d0 69 73 20 61 63 63 75 6d 75 6c 61 74 69 6e 67 20  is accumulating 
2b3e0 61 20 68 75 67 65 20 74 61 62 6c 65 0a 63 6f 6e  a huge table.con
2b3f0 74 61 69 6e 69 6e 67 20 6f 6e 65 20 6d 69 6c 6c  taining one mill
2b400 69 6f 6e 20 72 6f 77 73 2c 20 74 68 65 6e 20 67  ion rows, then g
2b410 6f 69 6e 67 20 62 61 63 6b 20 61 6e 64 20 73 63  oing back and sc
2b420 61 6e 6e 69 6e 67 20 74 68 61 74 20 74 61 62 6c  anning that tabl
2b430 65 0a 66 72 6f 6d 20 74 6f 70 20 74 6f 20 62 6f  e.from top to bo
2b440 74 74 6f 6d 20 74 6f 20 67 65 6e 65 72 61 74 65  ttom to generate
2b450 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 57 68   the result.  Wh
2b460 61 74 20 72 65 61 6c 6c 79 20 68 61 70 70 65 6e  at really happen
2b470 73 0a 69 73 20 74 68 61 74 20 74 68 65 20 71 75  s.is that the qu
2b480 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 73 65  ery optimizer se
2b490 65 73 20 74 68 61 74 20 76 61 6c 75 65 73 20 69  es that values i
2b4a0 6e 20 74 68 65 0a 22 63 6e 74 22 20 72 65 63 75  n the."cnt" recu
2b4b0 72 73 69 76 65 20 74 61 62 6c 65 20 61 72 65 20  rsive table are 
2b4c0 6f 6e 6c 79 20 75 73 65 64 20 6f 6e 63 65 2e 20  only used once. 
2b4d0 20 53 6f 20 61 73 20 65 61 63 68 20 72 6f 77 20   So as each row 
2b4e0 69 73 20 61 64 64 65 64 20 74 6f 0a 74 68 65 20  is added to.the 
2b4f0 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 2c  recursive table,
2b500 20 74 68 61 74 20 72 6f 77 20 69 73 20 69 6d 6d   that row is imm
2b510 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 65  ediately returne
2b520 64 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  d as a result of
2b530 20 74 68 65 20 6d 61 69 6e 0a 53 45 4c 45 43 54   the main.SELECT
2b540 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2b550 68 65 6e 20 64 69 73 63 61 72 64 65 64 2e 20 20  hen discarded.  
2b560 53 51 4c 69 74 65 20 64 6f 65 73 20 3c 65 6d 3e  SQLite does <em>
2b570 6e 6f 74 3c 2f 65 6d 3e 20 61 63 63 75 6d 75 6c  not</em> accumul
2b580 61 74 65 0a 61 20 74 65 6d 70 6f 72 61 72 79 20  ate.a temporary 
2b590 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67  table containing
2b5a0 20 61 20 6d 69 6c 6c 69 6f 6e 20 72 6f 77 73 2e   a million rows.
2b5b0 20 20 56 65 72 79 20 6c 69 74 74 6c 65 20 6d 65    Very little me
2b5c0 6d 6f 72 79 20 69 73 0a 6e 65 65 64 65 64 20 74  mory is.needed t
2b5d0 6f 20 72 75 6e 20 74 68 65 20 61 62 6f 76 65 20  o run the above 
2b5e0 65 78 61 6d 70 6c 65 2e 20 20 48 6f 77 65 76 65  example.  Howeve
2b5f0 72 2c 20 69 66 20 74 68 65 20 65 78 61 6d 70 6c  r, if the exampl
2b600 65 20 68 61 64 20 75 73 65 64 0a 55 4e 49 4f 4e  e had used.UNION
2b610 20 69 6e 73 74 65 61 64 20 6f 66 20 55 4e 49 4f   instead of UNIO
2b620 4e 20 41 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69  N ALL, then SQLi
2b630 74 65 20 77 6f 75 6c 64 20 68 61 76 65 20 68 61  te would have ha
2b640 64 20 74 6f 20 6b 65 65 70 20 61 72 6f 75 6e 64  d to keep around
2b650 0a 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20  .all previously 
2b660 67 65 6e 65 72 61 74 65 64 20 63 6f 6e 74 65 6e  generated conten
2b670 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 63 68  t in order to ch
2b680 65 63 6b 20 66 6f 72 20 64 75 70 6c 69 63 61 74  eck for duplicat
2b690 65 73 2e 0a 46 6f 72 20 74 68 69 73 20 72 65 61  es..For this rea
2b6a0 73 6f 6e 2c 20 70 72 6f 67 72 61 6d 6d 65 72 73  son, programmers
2b6b0 20 73 68 6f 75 6c 64 20 73 74 72 69 76 65 20 74   should strive t
2b6c0 6f 20 75 73 65 20 55 4e 49 4f 4e 20 41 4c 4c 20  o use UNION ALL 
2b6d0 69 6e 73 74 65 61 64 0a 6f 66 20 55 4e 49 4f 4e  instead.of UNION
2b6e0 20 77 68 65 6e 20 66 65 61 73 69 62 6c 65 2e 0a   when feasible..
2b6f0 0a 3c 70 3e 48 65 72 65 20 69 73 20 61 20 76 61  .<p>Here is a va
2b700 72 69 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  riation on the p
2b710 72 65 76 69 6f 75 73 20 65 78 61 6d 70 6c 65 3a  revious example:
2b720 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
2b730 72 65 3e 0a 57 49 54 48 20 52 45 43 55 52 53 49  re>.WITH RECURSI
2b740 56 45 0a 20 20 63 6e 74 28 78 29 20 41 53 20 28  VE.  cnt(x) AS (
2b750 0a 20 20 20 20 20 53 45 4c 45 43 54 20 31 0a 20  .     SELECT 1. 
2b760 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20      UNION ALL.  
2b770 20 20 20 53 45 4c 45 43 54 20 78 2b 31 20 46 52     SELECT x+1 FR
2b780 4f 4d 20 63 6e 74 0a 20 20 20 20 20 20 4c 49 4d  OM cnt.      LIM
2b790 49 54 20 31 30 30 30 30 30 30 0a 20 20 29 0a 53  IT 1000000.  ).S
2b7a0 45 4c 45 43 54 20 78 20 46 52 4f 4d 20 63 6e 74  ELECT x FROM cnt
2b7b0 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
2b7c0 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 72 65 20  uote>..<p>There 
2b7d0 61 72 65 20 74 77 6f 20 64 69 66 66 65 72 65 6e  are two differen
2b7e0 63 65 73 20 69 6e 20 74 68 69 73 20 76 61 72 69  ces in this vari
2b7f0 61 74 69 6f 6e 2e 20 20 54 68 65 20 69 6e 69 74  ation.  The init
2b800 69 61 6c 2d 73 65 6c 65 63 74 20 69 73 0a 22 53  ial-select is."S
2b810 45 4c 45 43 54 20 31 22 20 69 6e 73 74 65 61 64  ELECT 1" instead
2b820 20 6f 66 20 22 56 41 4c 55 45 53 28 31 29 22 2e   of "VALUES(1)".
2b830 20 20 42 75 74 20 74 68 6f 73 65 20 61 72 65 20    But those are 
2b840 6a 75 73 74 20 64 69 66 66 65 72 65 6e 74 0a 73  just different.s
2b850 79 6e 74 61 78 65 73 20 66 6f 72 20 73 61 79 69  yntaxes for sayi
2b860 6e 67 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  ng exactly the s
2b870 61 6d 65 20 74 68 69 6e 67 2e 20 20 54 68 65 20  ame thing.  The 
2b880 6f 74 68 65 72 20 63 68 61 6e 67 65 20 69 73 20  other change is 
2b890 74 68 61 74 20 74 68 65 0a 72 65 63 75 72 73 69  that the.recursi
2b8a0 6f 6e 20 69 73 20 73 74 6f 70 70 65 64 20 62 79  on is stopped by
2b8b0 20 61 20 4c 49 4d 49 54 20 72 61 74 68 65 72 20   a LIMIT rather 
2b8c0 74 68 61 6e 20 61 20 57 48 45 52 45 20 63 6c 61  than a WHERE cla
2b8d0 75 73 65 2e 20 20 54 68 65 20 75 73 65 20 6f 66  use.  The use of
2b8e0 0a 4c 49 4d 49 54 20 6d 65 61 6e 73 20 74 68 61  .LIMIT means tha
2b8f0 74 20 77 68 65 6e 20 74 68 65 20 6f 6e 65 2d 6d  t when the one-m
2b900 69 6c 6c 69 6f 6e 74 68 20 72 6f 77 20 69 73 20  illionth row is 
2b910 61 64 64 65 64 20 74 6f 20 74 68 65 20 22 63 6e  added to the "cn
2b920 74 22 20 74 61 62 6c 65 0a 28 61 6e 64 20 72 65  t" table.(and re
2b930 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6d 61  turned by the ma
2b940 69 6e 20 53 45 4c 45 43 54 2c 20 74 68 61 6e 6b  in SELECT, thank
2b950 73 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 6f  s to the query o
2b960 70 74 69 6d 69 7a 65 72 29 0a 74 68 65 6e 20 74  ptimizer).then t
2b970 68 65 20 72 65 63 75 72 73 69 6f 6e 20 73 74 6f  he recursion sto
2b980 70 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72  ps immediately r
2b990 65 67 61 72 64 6c 65 73 73 20 6f 66 20 68 6f 77  egardless of how
2b9a0 20 6d 61 6e 79 20 72 6f 77 73 20 6d 69 67 68 74   many rows might
2b9b0 20 62 65 0a 6c 65 66 74 20 69 6e 20 74 68 65 20   be.left in the 
2b9c0 71 75 65 75 65 2e 20 20 4f 6e 20 6d 6f 72 65 20  queue.  On more 
2b9d0 63 6f 6d 70 6c 65 78 20 71 75 65 72 69 65 73 2c  complex queries,
2b9e0 20 69 74 20 63 61 6e 20 73 6f 6d 65 74 69 6d 65   it can sometime
2b9f0 73 20 62 65 0a 64 69 66 66 69 63 75 6c 74 20 74  s be.difficult t
2ba00 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
2ba10 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 77  e WHERE clause w
2ba20 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 63  ill eventually c
2ba30 61 75 73 65 20 74 68 65 0a 71 75 65 75 65 20 74  ause the.queue t
2ba40 6f 20 64 72 61 69 6e 20 61 6e 64 20 74 68 65 20  o drain and the 
2ba50 72 65 63 75 72 73 69 6f 6e 20 74 6f 20 74 65 72  recursion to ter
2ba60 6d 69 6e 61 74 65 2e 20 20 42 75 74 20 74 68 65  minate.  But the
2ba70 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 77 69   LIMIT clause wi
2ba80 6c 6c 0a 61 6c 77 61 79 73 20 73 74 6f 70 20 74  ll.always stop t
2ba90 68 65 20 72 65 63 75 72 73 69 6f 6e 2e 20 20 53  he recursion.  S
2baa0 6f 20 69 74 20 69 73 20 67 6f 6f 64 20 70 72 61  o it is good pra
2bab0 63 74 69 63 65 20 74 6f 20 61 6c 77 61 79 73 20  ctice to always 
2bac0 69 6e 63 6c 75 64 65 20 61 0a 4c 49 4d 49 54 20  include a.LIMIT 
2bad0 63 6c 61 75 73 65 20 61 73 20 61 20 73 61 66 65  clause as a safe
2bae0 74 79 20 69 66 20 61 6e 20 75 70 70 65 72 20 62  ty if an upper b
2baf0 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65  ound on the size
2bb00 20 6f 66 20 74 68 65 20 72 65 63 75 72 73 69 6f   of the recursio
2bb10 6e 20 0a 69 73 20 6b 6e 6f 77 6e 2e 0a 0a 3c 74  n .is known...<t
2bb20 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 72  cl>hd_fragment r
2bb30 63 65 78 32 3c 2f 74 63 6c 3e 0a 3c 68 34 3e 48  cex2</tcl>.<h4>H
2bb40 69 65 72 61 72 63 68 69 63 61 6c 20 51 75 65 72  ierarchical Quer
2bb50 79 20 45 78 61 6d 70 6c 65 73 3c 2f 68 34 3e 0a  y Examples</h4>.
2bb60 0a 3c 70 3e 43 6f 6e 73 69 64 65 72 20 61 20 74  .<p>Consider a t
2bb70 61 62 6c 65 20 74 68 61 74 20 64 65 73 63 72 69  able that descri
2bb80 62 65 73 20 74 68 65 20 6d 65 6d 62 65 72 73 20  bes the members 
2bb90 6f 66 20 61 6e 20 6f 72 67 61 6e 69 7a 61 74 69  of an organizati
2bba0 6f 6e 20 61 73 0a 77 65 6c 6c 20 61 73 20 74 68  on as.well as th
2bbb0 65 20 63 68 61 69 6e 2d 6f 66 2d 63 6f 6d 6d 61  e chain-of-comma
2bbc0 6e 64 20 77 69 74 68 69 6e 20 74 68 61 74 20 6f  nd within that o
2bbd0 72 67 61 6e 69 7a 61 74 69 6f 6e 3a 0a 0a 3c 62  rganization:..<b
2bbe0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2bbf0 43 52 45 41 54 45 20 54 41 42 4c 45 20 6f 72 67  CREATE TABLE org
2bc00 28 0a 20 20 6e 61 6d 65 20 54 45 58 54 20 50 52  (.  name TEXT PR
2bc10 49 4d 41 52 59 20 4b 45 59 2c 0a 20 20 62 6f 73  IMARY KEY,.  bos
2bc20 73 20 54 45 58 54 20 52 45 46 45 52 45 4e 43 45  s TEXT REFERENCE
2bc30 53 20 6f 72 67 2c 0a 20 20 68 65 69 67 68 74 20  S org,.  height 
2bc40 49 4e 54 2c 0a 20 20 2d 2d 20 6f 74 68 65 72 20  INT,.  -- other 
2bc50 63 6f 6e 74 65 6e 74 20 6f 6d 69 74 74 65 64 0a  content omitted.
2bc60 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  );.</pre></block
2bc70 71 75 6f 74 65 3e 0a 0a 3c 70 3e 45 76 65 72 79  quote>..<p>Every
2bc80 20 6d 65 6d 62 65 72 20 69 6e 20 74 68 65 20 6f   member in the o
2bc90 72 67 61 6e 69 7a 61 74 69 6f 6e 20 68 61 73 20  rganization has 
2bca0 61 20 6e 61 6d 65 2c 20 61 6e 64 20 6d 6f 73 74  a name, and most
2bcb0 20 6d 65 6d 62 65 72 73 20 68 61 76 65 0a 61 20   members have.a 
2bcc0 73 69 6e 67 6c 65 20 62 6f 73 73 2e 20 20 28 54  single boss.  (T
2bcd0 68 65 20 68 65 61 64 20 6f 66 20 74 68 65 20 77  he head of the w
2bce0 68 6f 6c 65 20 6f 72 67 61 6e 69 7a 61 74 69 6f  hole organizatio
2bcf0 6e 20 68 61 73 20 61 20 4e 55 4c 4c 0a 22 62 6f  n has a NULL."bo
2bd00 73 73 22 20 66 69 65 6c 64 2e 29 20 54 68 65 20  ss" field.) The 
2bd10 72 6f 77 73 20 6f 66 20 74 68 65 20 22 6f 72 67  rows of the "org
2bd20 22 20 74 61 62 6c 65 20 66 6f 72 6d 20 61 20 74  " table form a t
2bd30 72 65 65 2e 0a 0a 3c 70 3e 48 65 72 65 20 69 73  ree...<p>Here is
2bd40 20 61 20 71 75 65 72 79 20 74 68 61 74 20 63 6f   a query that co
2bd50 6d 70 75 74 65 73 20 74 68 65 20 61 76 65 72 61  mputes the avera
2bd60 67 65 20 68 65 69 67 68 74 20 6f 76 65 72 20 65  ge height over e
2bd70 76 65 72 79 6f 6e 65 0a 69 6e 20 41 6c 69 63 65  veryone.in Alice
2bd80 27 73 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 2c  's organization,
2bd90 20 69 6e 63 6c 75 64 69 6e 67 20 41 6c 69 63 65   including Alice
2bda0 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  :..<blockquote><
2bdb0 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55 52 53  pre>.WITH RECURS
2bdc0 49 56 45 0a 20 20 77 6f 72 6b 73 5f 66 6f 72 5f  IVE.  works_for_
2bdd0 61 6c 69 63 65 28 6e 29 20 41 53 20 28 0a 20 20  alice(n) AS (.  
2bde0 20 20 56 41 4c 55 45 53 28 27 41 6c 69 63 65 27    VALUES('Alice'
2bdf0 29 0a 20 20 20 20 55 4e 49 4f 4e 0a 20 20 20 20  ).    UNION.    
2be00 53 45 4c 45 43 54 20 6e 61 6d 65 20 46 52 4f 4d  SELECT name FROM
2be10 20 6f 72 67 2c 20 77 6f 72 6b 73 5f 66 6f 72 5f   org, works_for_
2be20 61 6c 69 63 65 0a 20 20 20 20 20 57 48 45 52 45  alice.     WHERE
2be30 20 6f 72 67 2e 62 6f 73 73 3d 77 6f 72 6b 73 5f   org.boss=works_
2be40 66 6f 72 5f 61 6c 69 63 65 2e 6e 0a 20 20 29 0a  for_alice.n.  ).
2be50 53 45 4c 45 43 54 20 61 76 67 28 68 65 69 67 68  SELECT avg(heigh
2be60 74 29 20 46 52 4f 4d 20 6f 72 67 0a 20 57 48 45  t) FROM org. WHE
2be70 52 45 20 6f 72 67 2e 6e 61 6d 65 20 49 4e 20 77  RE org.name IN w
2be80 6f 72 6b 73 5f 66 6f 72 5f 61 6c 69 63 65 3b 0a  orks_for_alice;.
2be90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2bea0 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6e 65 78 74  te>..<p>The next
2beb0 20 65 78 61 6d 70 6c 65 20 75 73 65 73 20 74 77   example uses tw
2bec0 6f 20 0a 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20  o .common table 
2bed0 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61  expressions in a
2bee0 20 73 69 6e 67 6c 65 20 57 49 54 48 20 63 6c 61   single WITH cla
2bef0 75 73 65 2e 20 20 0a 54 68 65 20 66 6f 6c 6c 6f  use.  .The follo
2bf00 77 69 6e 67 20 74 61 62 6c 65 20 72 65 63 6f 72  wing table recor
2bf10 64 73 20 61 20 66 61 6d 69 6c 79 20 74 72 65 65  ds a family tree
2bf20 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  :..<blockquote><
2bf30 70 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c  pre>.CREATE TABL
2bf40 45 20 66 61 6d 69 6c 79 28 0a 20 20 6e 61 6d 65  E family(.  name
2bf50 20 54 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45   TEXT PRIMARY KE
2bf60 59 2c 0a 20 20 6d 6f 6d 20 54 45 58 54 20 52 45  Y,.  mom TEXT RE
2bf70 46 45 52 45 4e 43 45 53 20 66 61 6d 69 6c 79 2c  FERENCES family,
2bf80 0a 20 20 64 61 64 20 54 45 58 54 20 52 45 46 45  .  dad TEXT REFE
2bf90 52 45 4e 43 45 53 20 66 61 6d 69 6c 79 2c 0a 20  RENCES family,. 
2bfa0 20 62 6f 72 6e 20 44 41 54 45 54 49 4d 45 2c 0a   born DATETIME,.
2bfb0 20 20 64 69 65 64 20 44 41 54 45 54 49 4d 45 2c    died DATETIME,
2bfc0 20 2d 2d 20 4e 55 4c 4c 20 69 66 20 73 74 69 6c   -- NULL if stil
2bfd0 6c 20 61 6c 69 76 65 0a 20 20 2d 2d 20 6f 74 68  l alive.  -- oth
2bfe0 65 72 20 63 6f 6e 74 65 6e 74 0a 29 3b 0a 3c 2f  er content.);.</
2bff0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2c000 3e 0a 0a 3c 70 3e 54 68 65 20 22 66 61 6d 69 6c  >..<p>The "famil
2c010 79 22 20 74 61 62 6c 65 20 69 73 20 73 69 6d 69  y" table is simi
2c020 6c 61 72 20 74 6f 20 74 68 65 20 65 61 72 6c 69  lar to the earli
2c030 65 72 20 22 6f 72 67 22 20 74 61 62 6c 65 20 65  er "org" table e
2c040 78 63 65 70 74 20 74 68 61 74 20 0a 6e 6f 77 20  xcept that .now 
2c050 74 68 65 72 65 20 61 72 65 20 74 77 6f 20 70 61  there are two pa
2c060 72 65 6e 74 73 20 74 6f 20 65 61 63 68 20 6d 65  rents to each me
2c070 6d 62 65 72 2e 0a 57 65 20 77 61 6e 74 20 74 6f  mber..We want to
2c080 20 6b 6e 6f 77 20 61 6c 6c 20 6c 69 76 69 6e 67   know all living
2c090 20 61 6e 63 65 73 74 6f 72 73 20 6f 66 20 41 6c   ancestors of Al
2c0a0 69 63 65 2c 20 66 72 6f 6d 20 6f 6c 64 65 73 74  ice, from oldest
2c0b0 20 74 6f 20 79 6f 75 6e 67 65 73 74 2e 0a 41 6e   to youngest..An
2c0c0 20 6f 72 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e   ordinary common
2c0d0 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f   table expressio
2c0e0 6e 2c 20 22 70 61 72 65 6e 74 5f 6f 66 22 2c 20  n, "parent_of", 
2c0f0 69 73 20 64 65 66 69 6e 65 64 20 66 69 72 73 74  is defined first
2c100 2e 20 20 54 68 61 74 0a 6f 72 64 69 6e 61 72 79  .  That.ordinary
2c110 20 43 54 45 20 69 73 20 61 20 76 69 65 77 20 74   CTE is a view t
2c120 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
2c130 74 6f 20 66 69 6e 64 20 61 6c 6c 20 70 61 72 65  to find all pare
2c140 6e 74 73 20 6f 66 20 61 6e 79 0a 69 6e 64 69 76  nts of any.indiv
2c150 69 64 75 61 6c 2e 20 20 54 68 61 74 20 6f 72 64  idual.  That ord
2c160 69 6e 61 72 79 20 43 54 45 20 69 73 20 74 68 65  inary CTE is the
2c170 6e 20 75 73 65 64 20 69 6e 20 74 68 65 20 22 61  n used in the "a
2c180 6e 63 65 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65  ncestor_of_alice
2c190 22 0a 72 65 63 75 72 73 69 76 65 20 43 54 45 2e  ".recursive CTE.
2c1a0 20 20 54 68 65 20 72 65 63 75 72 73 69 76 65 20    The recursive 
2c1b0 43 54 45 20 69 73 20 74 68 65 6e 20 75 73 65 64  CTE is then used
2c1c0 20 69 6e 20 74 68 65 20 66 69 6e 61 6c 20 71 75   in the final qu
2c1d0 65 72 79 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ery:..<blockquot
2c1e0 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43  e><pre>.WITH REC
2c1f0 55 52 53 49 56 45 0a 20 20 70 61 72 65 6e 74 5f  URSIVE.  parent_
2c200 6f 66 28 6e 61 6d 65 2c 20 70 61 72 65 6e 74 29  of(name, parent)
2c210 20 41 53 0a 20 20 20 20 28 53 45 4c 45 43 54 20   AS.    (SELECT 
2c220 6e 61 6d 65 2c 20 6d 6f 6d 20 46 52 4f 4d 20 66  name, mom FROM f
2c230 61 6d 69 6c 79 20 55 4e 49 4f 4e 20 53 45 4c 45  amily UNION SELE
2c240 43 54 20 6e 61 6d 65 2c 20 64 61 64 20 46 52 4f  CT name, dad FRO
2c250 4d 20 66 61 6d 69 6c 79 29 2c 0a 20 20 61 6e 63  M family),.  anc
2c260 65 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65 28 6e  estor_of_alice(n
2c270 61 6d 65 29 20 41 53 0a 20 20 20 20 28 53 45 4c  ame) AS.    (SEL
2c280 45 43 54 20 70 61 72 65 6e 74 20 46 52 4f 4d 20  ECT parent FROM 
2c290 70 61 72 65 6e 74 5f 6f 66 20 57 48 45 52 45 20  parent_of WHERE 
2c2a0 6e 61 6d 65 3d 27 41 6c 69 63 65 27 0a 20 20 20  name='Alice'.   
2c2b0 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20    UNION ALL.    
2c2c0 20 53 45 4c 45 43 54 20 70 61 72 65 6e 74 20 46   SELECT parent F
2c2d0 52 4f 4d 20 70 61 72 65 6e 74 5f 6f 66 20 4a 4f  ROM parent_of JO
2c2e0 49 4e 20 61 6e 63 65 73 74 6f 72 5f 6f 66 5f 61  IN ancestor_of_a
2c2f0 6c 69 63 65 20 55 53 49 4e 47 28 6e 61 6d 65 29  lice USING(name)
2c300 29 0a 53 45 4c 45 43 54 20 66 61 6d 69 6c 79 2e  ).SELECT family.
2c310 6e 61 6d 65 20 46 52 4f 4d 20 61 6e 63 65 73 74  name FROM ancest
2c320 6f 72 5f 6f 66 5f 61 6c 69 63 65 2c 20 66 61 6d  or_of_alice, fam
2c330 69 6c 79 0a 20 57 48 45 52 45 20 61 6e 63 65 73  ily. WHERE ances
2c340 74 6f 72 5f 6f 66 5f 61 6c 69 63 65 2e 6e 61 6d  tor_of_alice.nam
2c350 65 3d 66 61 6d 69 6c 79 2e 6e 61 6d 65 0a 20 20  e=family.name.  
2c360 20 41 4e 44 20 64 69 65 64 20 49 53 20 4e 55 4c   AND died IS NUL
2c370 4c 0a 20 4f 52 44 45 52 20 42 59 20 62 6f 72 6e  L. ORDER BY born
2c380 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
2c390 75 6f 74 65 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  uote>..<tcl>hd_f
2c3a0 72 61 67 6d 65 6e 74 20 72 63 65 78 33 3c 2f 74  ragment rcex3</t
2c3b0 63 6c 3e 0a 3c 68 34 3e 51 75 65 72 69 65 73 20  cl>.<h4>Queries 
2c3c0 41 67 61 69 6e 73 74 20 41 20 47 72 61 70 68 3c  Against A Graph<
2c3d0 2f 68 34 3e 0a 0a 3c 70 3e 41 20 76 65 72 73 69  /h4>..<p>A versi
2c3e0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 79 73 74 65  on control syste
2c3f0 6d 20 28 56 43 53 29 20 77 69 6c 6c 20 74 79 70  m (VCS) will typ
2c400 69 63 61 6c 6c 79 20 73 74 6f 72 65 20 74 68 65  ically store the
2c410 20 65 76 6f 6c 76 69 6e 67 0a 76 65 72 73 69 6f   evolving.versio
2c420 6e 73 20 6f 66 20 61 20 70 72 6f 6a 65 63 74 20  ns of a project 
2c430 61 73 20 61 20 64 69 72 65 63 74 65 64 20 61 63  as a directed ac
2c440 79 63 6c 69 63 20 67 72 61 70 68 20 28 44 41 47  yclic graph (DAG
2c450 29 2e 20 20 43 61 6c 6c 20 65 61 63 68 0a 76 65  ).  Call each.ve
2c460 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 6f  rsion of the pro
2c470 6a 65 63 74 20 61 20 22 63 68 65 63 6b 69 6e 22  ject a "checkin"
2c480 2e 20 20 41 20 73 69 6e 67 6c 65 0a 63 68 65 63  .  A single.chec
2c490 6b 69 6e 20 63 61 6e 20 68 61 76 65 20 7a 65 72  kin can have zer
2c4a0 6f 20 6f 72 20 6d 6f 72 65 20 70 61 72 65 6e 74  o or more parent
2c4b0 73 2e 20 20 4d 6f 73 74 20 63 68 65 63 6b 69 6e  s.  Most checkin
2c4c0 73 20 28 65 78 63 65 70 74 20 74 68 65 0a 66 69  s (except the.fi
2c4d0 72 73 74 29 20 68 61 76 65 20 61 20 73 69 6e 67  rst) have a sing
2c4e0 6c 65 20 70 61 72 65 6e 74 2c 20 62 75 74 20 69  le parent, but i
2c4f0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 20  n the case of a 
2c500 6d 65 72 67 65 2c 20 61 20 63 68 65 63 6b 69 6e  merge, a checkin
2c510 0a 6d 69 67 68 74 20 68 61 76 65 20 74 77 6f 20  .might have two 
2c520 6f 72 20 74 68 72 65 65 20 6f 72 20 6d 6f 72 65  or three or more
2c530 20 70 61 72 65 6e 74 73 2e 20 20 41 20 73 63 68   parents.  A sch
2c540 65 6d 61 20 74 6f 20 6b 65 65 70 20 74 72 61 63  ema to keep trac
2c550 6b 20 6f 66 0a 63 68 65 63 6b 69 6e 73 20 61 6e  k of.checkins an
2c560 64 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  d the order in w
2c570 68 69 63 68 20 74 68 65 79 20 6f 63 63 75 72 20  hich they occur 
2c580 6d 69 67 68 74 20 6c 6f 6f 6b 20 73 6f 6d 65 74  might look somet
2c590 68 69 6e 67 20 6c 69 6b 65 0a 74 68 69 73 3a 0a  hing like.this:.
2c5a0 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
2c5b0 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20  e>.CREATE TABLE 
2c5c0 63 68 65 63 6b 69 6e 28 0a 20 20 69 64 20 49 4e  checkin(.  id IN
2c5d0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
2c5e0 59 2c 0a 20 20 6d 74 69 6d 65 20 49 4e 54 45 47  Y,.  mtime INTEG
2c5f0 45 52 20 2d 2d 20 74 69 6d 65 73 74 61 6d 70 20  ER -- timestamp 
2c600 77 68 65 6e 20 74 68 69 73 20 63 68 65 63 6b 69  when this checki
2c610 6e 20 6f 63 63 75 72 72 65 64 0a 29 3b 0a 43 52  n occurred.);.CR
2c620 45 41 54 45 20 54 41 42 4c 45 20 64 65 72 69 76  EATE TABLE deriv
2c630 65 64 66 72 6f 6d 28 0a 20 20 78 66 72 6f 6d 20  edfrom(.  xfrom 
2c640 49 4e 54 45 47 45 52 20 4e 4f 54 20 4e 55 4c 4c  INTEGER NOT NULL
2c650 20 52 45 46 45 52 45 4e 43 45 53 20 63 68 65 63   REFERENCES chec
2c660 6b 69 6e 2c 20 2d 2d 20 70 61 72 65 6e 74 20 63  kin, -- parent c
2c670 68 65 63 6b 69 6e 0a 20 20 78 74 6f 20 49 4e 54  heckin.  xto INT
2c680 45 47 45 52 20 4e 4f 54 20 4e 55 4c 4c 20 52 45  EGER NOT NULL RE
2c690 46 45 52 45 4e 43 45 53 20 63 68 65 63 6b 69 6e  FERENCES checkin
2c6a0 2c 20 20 20 2d 2d 20 64 65 72 69 76 65 64 20 63  ,   -- derived c
2c6b0 68 65 63 6b 69 6e 0a 20 20 50 52 49 4d 41 52 59  heckin.  PRIMARY
2c6c0 20 4b 45 59 28 78 66 72 6f 6d 2c 78 74 6f 29 0a   KEY(xfrom,xto).
2c6d0 29 3b 0a 43 52 45 41 54 45 20 49 4e 44 45 58 20  );.CREATE INDEX 
2c6e0 64 65 72 69 76 65 64 66 72 6f 6d 5f 62 61 63 6b  derivedfrom_back
2c6f0 20 4f 4e 20 64 65 72 69 76 65 64 66 72 6f 6d 28   ON derivedfrom(
2c700 78 74 6f 2c 78 66 72 6f 6d 29 3b 0a 3c 2f 70 72  xto,xfrom);.</pr
2c710 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2c720 0a 3c 70 3e 54 68 69 73 20 67 72 61 70 68 20 69  .<p>This graph i
2c730 73 20 61 63 79 63 6c 69 63 2e 20 20 41 6e 64 20  s acyclic.  And 
2c740 77 65 20 61 73 73 75 6d 65 20 74 68 61 74 20 74  we assume that t
2c750 68 65 20 6d 74 69 6d 65 20 6f 66 20 65 76 65 72  he mtime of ever
2c760 79 0a 63 68 69 6c 64 20 63 68 65 63 6b 69 6e 20  y.child checkin 
2c770 69 73 20 6e 6f 20 6c 65 73 73 20 74 68 61 6e 20  is no less than 
2c780 74 68 65 20 6d 74 69 6d 65 20 6f 66 20 61 6c 6c  the mtime of all
2c790 20 69 74 73 20 70 61 72 65 6e 74 73 2e 20 20 42   its parents.  B
2c7a0 75 74 0a 75 6e 6c 69 6b 65 20 74 68 65 20 65 61  ut.unlike the ea
2c7b0 72 6c 69 65 72 20 65 78 61 6d 70 6c 65 73 2c 20  rlier examples, 
2c7c0 74 68 69 73 20 67 72 61 70 68 20 6d 69 67 68 74  this graph might
2c7d0 20 68 61 76 65 20 6d 75 6c 74 69 70 6c 65 20 70   have multiple p
2c7e0 61 74 68 73 20 6f 66 0a 64 69 66 66 65 72 69 6e  aths of.differin
2c7f0 67 20 6c 65 6e 67 74 68 73 20 62 65 74 77 65 65  g lengths betwee
2c800 6e 20 61 6e 79 20 74 77 6f 20 63 68 65 63 6b 69  n any two checki
2c810 6e 73 2e 0a 0a 3c 70 3e 57 65 20 77 61 6e 74 20  ns...<p>We want 
2c820 74 6f 20 6b 6e 6f 77 20 74 68 65 20 74 77 65 6e  to know the twen
2c830 74 79 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 61  ty most recent a
2c840 6e 63 65 73 74 6f 72 73 20 69 6e 20 74 69 6d 65  ncestors in time
2c850 20 28 6f 75 74 20 6f 66 0a 74 68 65 20 74 68 6f   (out of.the tho
2c860 75 73 61 6e 64 73 20 61 6e 64 20 74 68 6f 75 73  usands and thous
2c870 61 6e 64 73 20 6f 66 20 61 6e 63 65 73 74 6f 72  ands of ancestor
2c880 73 20 69 6e 20 74 68 65 20 77 68 6f 6c 65 20 44  s in the whole D
2c890 41 47 29 20 66 6f 72 0a 63 68 65 63 6b 69 6e 20  AG) for.checkin 
2c8a0 22 40 42 41 53 45 4c 49 4e 45 22 2e 20 20 28 41  "@BASELINE".  (A
2c8b0 20 71 75 65 72 79 20 73 69 6d 69 6c 61 72 20 74   query similar t
2c8c0 6f 20 74 68 69 73 20 69 73 20 75 73 65 64 0a 62  o this is used.b
2c8d0 79 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 68  y the <a href="h
2c8e0 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
2c8f0 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
2c900 6c 3c 2f 61 3e 20 56 43 53 20 74 6f 0a 73 68 6f  l</a> VCS to.sho
2c910 77 20 74 68 65 20 4e 20 6d 6f 73 74 20 72 65 63  w the N most rec
2c920 65 6e 74 20 61 6e 63 65 73 74 6f 72 73 20 6f 66  ent ancestors of
2c930 20 61 20 63 68 65 63 6b 2e 20 20 46 6f 72 20 65   a check.  For e
2c940 78 61 6d 70 6c 65 3a 0a 3c 61 20 68 72 65 66 3d  xample:.<a href=
2c950 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
2c960 74 65 2e 6f 72 67 2f 73 72 63 2f 74 69 6d 65 6c  te.org/src/timel
2c970 69 6e 65 3f 70 3d 74 72 75 6e 6b 26 6e 3d 33 30  ine?p=trunk&n=30
2c980 22 3e 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  ">http://www.sql
2c990 69 74 65 2e 6f 72 67 2f 73 72 63 2f 74 69 6d 65  ite.org/src/time
2c9a0 6c 69 6e 65 3f 70 3d 74 72 75 6e 6b 26 6e 3d 33  line?p=trunk&n=3
2c9b0 30 3c 2f 61 3e 2e 29 0a 0a 3c 62 6c 6f 63 6b 71  0</a>.)..<blockq
2c9c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20  uote><pre>.WITH 
2c9d0 52 45 43 55 52 53 49 56 45 0a 20 20 61 6e 63 65  RECURSIVE.  ance
2c9e0 73 74 6f 72 28 69 64 2c 6d 74 69 6d 65 29 20 41  stor(id,mtime) A
2c9f0 53 20 28 0a 20 20 20 20 53 45 4c 45 43 54 20 69  S (.    SELECT i
2ca00 64 2c 20 6d 74 69 6d 65 20 46 52 4f 4d 20 63 68  d, mtime FROM ch
2ca10 65 63 6b 69 6e 20 57 48 45 52 45 20 69 64 3d 40  eckin WHERE id=@
2ca20 42 41 53 45 4c 49 4e 45 0a 20 20 20 20 55 4e 49  BASELINE.    UNI
2ca30 4f 4e 0a 20 20 20 20 53 45 4c 45 43 54 20 64 65  ON.    SELECT de
2ca40 72 69 76 65 64 66 72 6f 6d 2e 78 66 72 6f 6d 2c  rivedfrom.xfrom,
2ca50 20 63 68 65 63 6b 69 6e 2e 6d 74 69 6d 65 0a 20   checkin.mtime. 
2ca60 20 20 20 20 20 46 52 4f 4d 20 61 6e 63 65 73 74       FROM ancest
2ca70 6f 72 2c 20 64 65 72 69 76 65 64 66 72 6f 6d 2c  or, derivedfrom,
2ca80 20 63 68 65 63 6b 69 6e 0a 20 20 20 20 20 57 48   checkin.     WH
2ca90 45 52 45 20 61 6e 63 65 73 74 6f 72 2e 69 64 3d  ERE ancestor.id=
2caa0 64 65 72 69 76 65 64 66 72 6f 6d 2e 78 74 6f 0a  derivedfrom.xto.
2cab0 20 20 20 20 20 20 20 41 4e 44 20 63 68 65 63 6b         AND check
2cac0 69 6e 2e 69 64 3d 64 65 72 69 76 65 64 66 72 6f  in.id=derivedfro
2cad0 6d 2e 78 66 72 6f 6d 0a 20 20 20 20 20 4f 52 44  m.xfrom.     ORD
2cae0 45 52 20 42 59 20 63 68 65 63 6b 69 6e 2e 6d 74  ER BY checkin.mt
2caf0 69 6d 65 20 44 45 53 43 0a 20 20 20 20 20 4c 49  ime DESC.     LI
2cb00 4d 49 54 20 32 30 0a 20 20 29 0a 53 45 4c 45 43  MIT 20.  ).SELEC
2cb10 54 20 2a 20 46 52 4f 4d 20 63 68 65 63 6b 69 6e  T * FROM checkin
2cb20 20 4a 4f 49 4e 20 61 6e 63 65 73 74 6f 72 20 55   JOIN ancestor U
2cb30 53 49 4e 47 28 69 64 29 3b 0a 3c 2f 70 72 65 3e  SING(id);.</pre>
2cb40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
2cb50 70 3e 0a 54 68 65 20 22 4f 52 44 45 52 20 42 59  p>.The "ORDER BY
2cb60 20 63 68 65 63 6b 69 6e 2e 6d 74 69 6d 65 20 44   checkin.mtime D
2cb70 45 53 43 22 20 74 65 72 6d 20 69 6e 20 74 68 65  ESC" term in the
2cb80 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63   recursive-selec
2cb90 74 20 6d 61 6b 65 73 0a 74 68 65 20 71 75 65 72  t makes.the quer
2cba0 79 20 72 75 6e 20 6d 75 63 68 20 66 61 73 74 65  y run much faste
2cbb0 72 20 62 79 20 70 72 65 76 65 6e 74 69 6e 67 20  r by preventing 
2cbc0 69 74 20 66 72 6f 6d 20 66 6f 6c 6c 6f 77 69 6e  it from followin
2cbd0 67 0a 62 72 61 6e 63 68 65 73 20 74 68 61 74 20  g.branches that 
2cbe0 6d 65 72 67 65 20 63 68 65 63 6b 69 6e 73 0a 66  merge checkins.f
2cbf0 72 6f 6d 20 6c 6f 6e 67 20 61 67 6f 2e 20 20 54  rom long ago.  T
2cc00 68 65 20 4f 52 44 45 52 20 42 59 20 66 6f 72 63  he ORDER BY forc
2cc10 65 73 20 74 68 65 20 72 65 63 75 72 73 69 76 65  es the recursive
2cc20 2d 73 65 6c 65 63 74 20 74 6f 20 66 6f 63 75 73  -select to focus
2cc30 0a 6f 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .on the most rec
2cc40 65 6e 74 20 63 68 65 63 6b 69 6e 73 2c 20 74 68  ent checkins, th
2cc50 65 20 6f 6e 65 73 20 77 65 20 77 61 6e 74 2e 20  e ones we want. 
2cc60 20 57 69 74 68 6f 75 74 20 74 68 65 20 4f 52 44   Without the ORD
2cc70 45 52 20 42 59 0a 6f 6e 20 74 68 65 20 72 65 63  ER BY.on the rec
2cc80 75 72 73 69 76 65 2d 73 65 6c 65 63 74 2c 20 6f  ursive-select, o
2cc90 6e 65 20 77 6f 75 6c 64 20 62 65 20 66 6f 72 63  ne would be forc
2cca0 65 64 20 74 6f 20 63 6f 6d 70 75 74 65 20 74 68  ed to compute th
2ccb0 65 20 63 6f 6d 70 6c 65 74 65 20 73 65 74 20 6f  e complete set o
2ccc0 66 0a 74 68 6f 75 73 61 6e 64 73 20 6f 66 20 61  f.thousands of a
2ccd0 6e 63 65 73 74 6f 72 73 2c 20 73 6f 72 74 20 74  ncestors, sort t
2cce0 68 65 6d 20 61 6c 6c 20 62 79 20 6d 74 69 6d 65  hem all by mtime
2ccf0 2c 20 74 68 65 6e 20 74 61 6b 65 20 74 68 65 20  , then take the 
2cd00 74 6f 70 20 74 77 65 6e 74 79 2e 0a 54 68 65 20  top twenty..The 
2cd10 4f 52 44 45 52 20 42 59 20 65 73 73 65 6e 74 69  ORDER BY essenti
2cd20 61 6c 6c 79 20 73 65 74 73 20 75 70 20 61 20 70  ally sets up a p
2cd30 72 69 6f 72 69 74 79 20 71 75 65 75 65 20 74 68  riority queue th
2cd40 61 74 0a 66 6f 72 63 65 73 20 74 68 65 20 72 65  at.forces the re
2cd50 63 75 72 73 69 76 65 20 71 75 65 72 79 20 74 6f  cursive query to
2cd60 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 6d 6f 73   look at the mos
2cd70 74 20 72 65 63 65 6e 74 20 61 6e 63 65 73 74 6f  t recent ancesto
2cd80 72 73 20 66 69 72 73 74 2c 0a 61 6c 6c 6f 77 69  rs first,.allowi
2cd90 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 61 20  ng the use of a 
2cda0 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 74 6f 20  LIMIT clause to 
2cdb0 72 65 73 74 72 69 63 74 20 74 68 65 20 73 63 6f  restrict the sco
2cdc0 70 65 20 6f 66 20 74 68 65 0a 71 75 65 72 79 20  pe of the.query 
2cdd0 74 6f 20 6a 75 73 74 20 74 68 65 20 63 68 65 63  to just the chec
2cde0 6b 69 6e 73 20 6f 66 20 69 6e 74 65 72 65 73 74  kins of interest
2cdf0 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
2ce00 65 6e 74 20 77 69 74 68 6f 72 64 65 72 62 79 3c  ent withorderby<
2ce10 2f 74 63 6c 3e 0a 3c 68 34 3e 43 6f 6e 74 72 6f  /tcl>.<h4>Contro
2ce20 6c 6c 69 6e 67 20 44 65 70 74 68 2d 46 69 72 73  lling Depth-Firs
2ce30 74 20 56 65 72 73 75 73 20 42 72 65 61 64 74 68  t Versus Breadth
2ce40 2d 46 69 72 73 74 20 53 65 61 72 63 68 20 4f 66  -First Search Of
2ce50 20 61 20 54 72 65 65 0a 55 73 69 6e 67 20 4f 52   a Tree.Using OR
2ce60 44 45 52 20 42 59 3c 2f 68 34 3e 0a 0a 3c 70 3e  DER BY</h4>..<p>
2ce70 41 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  An ORDER BY clau
2ce80 73 65 20 6f 6e 20 74 68 65 20 72 65 63 75 72 73  se on the recurs
2ce90 69 76 65 2d 73 65 6c 65 63 74 20 63 61 6e 20 62  ive-select can b
2cea0 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 72 6f  e used to contro
2ceb0 6c 0a 77 68 65 74 68 65 72 20 74 68 65 20 73 65  l.whether the se
2cec0 61 72 63 68 20 6f 66 20 61 20 74 72 65 65 20 69  arch of a tree i
2ced0 73 20 64 65 70 74 68 2d 66 69 72 73 74 20 6f 72  s depth-first or
2cee0 20 62 72 65 61 64 74 68 2d 66 69 72 73 74 2e 20   breadth-first. 
2cef0 20 54 6f 0a 69 6c 6c 75 73 74 72 61 74 65 2c 20   To.illustrate, 
2cf00 77 65 20 77 69 6c 6c 20 75 73 65 20 61 20 76 61  we will use a va
2cf10 72 69 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 22  riation on the "
2cf20 6f 72 67 22 20 74 61 62 6c 65 20 66 72 6f 6d 20  org" table from 
2cf30 61 6e 20 65 78 61 6d 70 6c 65 0a 61 62 6f 76 65  an example.above
2cf40 2c 20 77 69 74 68 6f 75 74 20 74 68 65 20 22 68  , without the "h
2cf50 65 69 67 68 74 22 20 63 6f 6c 75 6d 6e 2c 20 61  eight" column, a
2cf60 6e 64 20 77 69 74 68 20 73 6f 6d 65 20 72 65 61  nd with some rea
2cf70 6c 20 64 61 74 61 20 69 6e 73 65 72 74 65 64 3a  l data inserted:
2cf80 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
2cf90 72 65 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45  re>.CREATE TABLE
2cfa0 20 6f 72 67 28 0a 20 20 6e 61 6d 65 20 54 45 58   org(.  name TEX
2cfb0 54 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 0a 20  T PRIMARY KEY,. 
2cfc0 20 62 6f 73 73 20 54 45 58 54 20 52 45 46 45 52   boss TEXT REFER
2cfd0 45 4e 43 45 53 20 6f 72 67 0a 29 20 57 49 54 48  ENCES org.) WITH
2cfe0 4f 55 54 20 52 4f 57 49 44 3b 0a 49 4e 53 45 52  OUT ROWID;.INSER
2cff0 54 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c 55 45  T INTO org VALUE
2d000 53 28 27 41 6c 69 63 65 27 2c 4e 55 4c 4c 29 3b  S('Alice',NULL);
2d010 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f 72 67  .INSERT INTO org
2d020 20 56 41 4c 55 45 53 28 27 42 6f 62 27 2c 27 41   VALUES('Bob','A
2d030 6c 69 63 65 27 29 3b 0a 49 4e 53 45 52 54 20 49  lice');.INSERT I
2d040 4e 54 4f 20 6f 72 67 20 56 41 4c 55 45 53 28 27  NTO org VALUES('
2d050 43 69 6e 64 79 27 2c 27 41 6c 69 63 65 27 29 3b  Cindy','Alice');
2d060 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f 72 67  .INSERT INTO org
2d070 20 56 41 4c 55 45 53 28 27 44 61 76 65 27 2c 27   VALUES('Dave','
2d080 42 6f 62 27 29 3b 0a 49 4e 53 45 52 54 20 49 4e  Bob');.INSERT IN
2d090 54 4f 20 6f 72 67 20 56 41 4c 55 45 53 28 27 45  TO org VALUES('E
2d0a0 6d 6d 61 27 2c 27 42 6f 62 27 29 3b 0a 49 4e 53  mma','Bob');.INS
2d0b0 45 52 54 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c  ERT INTO org VAL
2d0c0 55 45 53 28 27 46 72 65 64 27 2c 27 43 69 6e 64  UES('Fred','Cind
2d0d0 79 27 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f  y');.INSERT INTO
2d0e0 20 6f 72 67 20 56 41 4c 55 45 53 28 27 47 61 69   org VALUES('Gai
2d0f0 6c 27 2c 27 43 69 6e 64 79 27 29 3b 0a 3c 2f 70  l','Cindy');.</p
2d100 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2d110 0a 0a 3c 70 3e 48 65 72 65 20 69 73 20 61 20 71  ..<p>Here is a q
2d120 75 65 72 79 20 74 6f 20 73 68 6f 77 20 74 68 65  uery to show the
2d130 20 74 72 65 65 20 73 74 72 75 63 74 75 72 65 20   tree structure 
2d140 69 6e 20 61 20 62 72 65 61 64 74 68 2d 66 69 72  in a breadth-fir
2d150 73 74 20 70 61 74 74 65 72 6e 3a 0a 0a 3c 62 6c  st pattern:..<bl
2d160 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57  ockquote><pre>.W
2d170 49 54 48 20 52 45 43 55 52 53 49 56 45 0a 20 20  ITH RECURSIVE.  
2d180 75 6e 64 65 72 5f 61 6c 69 63 65 28 6e 61 6d 65  under_alice(name
2d190 2c 6c 65 76 65 6c 29 20 41 53 20 28 0a 20 20 20  ,level) AS (.   
2d1a0 20 56 41 4c 55 45 53 28 27 41 6c 69 63 65 27 2c   VALUES('Alice',
2d1b0 30 29 0a 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c  0).    UNION ALL
2d1c0 0a 20 20 20 20 53 45 4c 45 43 54 20 6f 72 67 2e  .    SELECT org.
2d1d0 6e 61 6d 65 2c 20 75 6e 64 65 72 5f 61 6c 69 63  name, under_alic
2d1e0 65 2e 6c 65 76 65 6c 2b 31 0a 20 20 20 20 20 20  e.level+1.      
2d1f0 46 52 4f 4d 20 6f 72 67 20 4a 4f 49 4e 20 75 6e  FROM org JOIN un
2d200 64 65 72 5f 61 6c 69 63 65 20 4f 4e 20 6f 72 67  der_alice ON org
2d210 2e 62 6f 73 73 3d 75 6e 64 65 72 5f 61 6c 69 63  .boss=under_alic
2d220 65 2e 6e 61 6d 65 0a 20 20 20 20 20 4f 52 44 45  e.name.     ORDE
2d230 52 20 42 59 20 32 0a 20 20 29 0a 53 45 4c 45 43  R BY 2.  ).SELEC
2d240 54 20 73 75 62 73 74 72 28 27 2e 2e 2e 2e 2e 2e  T substr('......
2d250 2e 2e 2e 2e 27 2c 31 2c 6c 65 76 65 6c 2a 33 29  ....',1,level*3)
2d260 20 7c 7c 20 6e 61 6d 65 20 46 52 4f 4d 20 75 6e   || name FROM un
2d270 64 65 72 5f 61 6c 69 63 65 3b 0a 3c 2f 70 72 65  der_alice;.</pre
2d280 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2d290 3c 70 3e 54 68 65 20 22 4f 52 44 45 52 20 42 59  <p>The "ORDER BY
2d2a0 20 32 22 20 28 77 68 69 63 68 20 6d 65 61 6e 73   2" (which means
2d2b0 20 74 68 65 20 73 61 6d 65 20 61 73 20 22 4f 52   the same as "OR
2d2c0 44 45 52 20 42 59 20 75 6e 64 65 72 5f 61 6c 69  DER BY under_ali
2d2d0 63 65 2e 6c 65 76 65 6c 2b 31 22 29 0a 63 61 75  ce.level+1").cau
2d2e0 73 65 73 20 68 69 67 68 65 72 20 6c 65 76 65 6c  ses higher level
2d2f0 73 20 69 6e 20 74 68 65 20 6f 72 67 61 6e 69 7a  s in the organiz
2d300 61 74 69 6f 6e 20 63 68 61 72 74 20 28 77 69 74  ation chart (wit
2d310 68 20 73 6d 61 6c 6c 65 72 20 22 6c 65 76 65 6c  h smaller "level
2d320 22 20 76 61 6c 75 65 73 29 0a 74 6f 20 62 65 20  " values).to be 
2d330 70 72 6f 63 65 73 73 65 64 20 66 69 72 73 74 2c  processed first,
2d340 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 61 20   resulting in a 
2d350 62 72 65 61 64 74 68 2d 66 69 72 73 74 20 73 65  breadth-first se
2d360 61 72 63 68 2e 20 20 54 68 65 20 6f 75 74 70 75  arch.  The outpu
2d370 74 20 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  t is:..<blockquo
2d380 74 65 3e 3c 70 72 65 3e 0a 41 6c 69 63 65 0a 2e  te><pre>.Alice..
2d390 2e 2e 42 6f 62 0a 2e 2e 2e 43 69 6e 64 79 0a 2e  ..Bob....Cindy..
2d3a0 2e 2e 2e 2e 2e 44 61 76 65 0a 2e 2e 2e 2e 2e 2e  .....Dave.......
2d3b0 45 6d 6d 61 0a 2e 2e 2e 2e 2e 2e 46 72 65 64 0a  Emma.......Fred.
2d3c0 2e 2e 2e 2e 2e 2e 47 61 69 6c 0a 3c 2f 70 72 65  ......Gail.</pre
2d3d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2d3e0 3c 70 3e 42 75 74 20 69 66 20 77 65 20 63 68 61  <p>But if we cha
2d3f0 6e 67 65 20 74 68 65 20 4f 52 44 45 52 20 42 59  nge the ORDER BY
2d400 20 63 6c 61 75 73 65 20 74 6f 20 61 64 64 20 74   clause to add t
2d410 68 65 20 22 44 45 53 43 22 20 6d 6f 64 69 66 69  he "DESC" modifi
2d420 65 72 2c 20 74 68 61 74 20 77 69 6c 6c 0a 63 61  er, that will.ca
2d430 75 73 65 20 6c 6f 77 65 72 20 6c 65 76 65 6c 73  use lower levels
2d440 20 69 6e 20 74 68 65 20 6f 72 67 61 6e 69 7a 61   in the organiza
2d450 74 69 6f 6e 20 28 77 69 74 68 20 6c 61 72 67 65  tion (with large
2d460 72 20 22 6c 65 76 65 6c 22 20 76 61 6c 75 65 73  r "level" values
2d470 29 20 74 6f 20 62 65 0a 70 72 6f 63 65 73 73 65  ) to be.processe
2d480 64 20 66 69 72 73 74 20 62 79 20 74 68 65 20 72  d first by the r
2d490 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 2c  ecursive-select,
2d4a0 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 61 20   resulting in a 
2d4b0 64 65 70 74 68 2d 66 69 72 73 74 20 73 65 61 72  depth-first sear
2d4c0 63 68 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  ch:..<blockquote
2d4d0 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55  ><pre>.WITH RECU
2d4e0 52 53 49 56 45 0a 20 20 75 6e 64 65 72 5f 61 6c  RSIVE.  under_al
2d4f0 69 63 65 28 6e 61 6d 65 2c 6c 65 76 65 6c 29 20  ice(name,level) 
2d500 41 53 20 28 0a 20 20 20 20 56 41 4c 55 45 53 28  AS (.    VALUES(
2d510 27 41 6c 69 63 65 27 2c 30 29 0a 20 20 20 20 55  'Alice',0).    U
2d520 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20 53 45 4c  NION ALL.    SEL
2d530 45 43 54 20 6f 72 67 2e 6e 61 6d 65 2c 20 75 6e  ECT org.name, un
2d540 64 65 72 5f 61 6c 69 63 65 2e 6c 65 76 65 6c 2b  der_alice.level+
2d550 31 0a 20 20 20 20 20 20 46 52 4f 4d 20 6f 72 67  1.      FROM org
2d560 20 4a 4f 49 4e 20 75 6e 64 65 72 5f 61 6c 69 63   JOIN under_alic
2d570 65 20 4f 4e 20 6f 72 67 2e 62 6f 73 73 3d 75 6e  e ON org.boss=un
2d580 64 65 72 5f 61 6c 69 63 65 2e 6e 61 6d 65 0a 20  der_alice.name. 
2d590 20 20 20 20 4f 52 44 45 52 20 42 59 20 32 20 3c      ORDER BY 2 <
2d5a0 62 3e 44 45 53 43 3c 2f 62 3e 0a 20 20 29 0a 53  b>DESC</b>.  ).S
2d5b0 45 4c 45 43 54 20 73 75 62 73 74 72 28 27 2e 2e  ELECT substr('..
2d5c0 2e 2e 2e 2e 2e 2e 2e 2e 27 2c 31 2c 6c 65 76 65  ........',1,leve
2d5d0 6c 2a 33 29 20 7c 7c 20 6e 61 6d 65 20 46 52 4f  l*3) || name FRO
2d5e0 4d 20 75 6e 64 65 72 5f 61 6c 69 63 65 3b 0a 3c  M under_alice;.<
2d5f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2d600 65 3e 0a 0a 3c 70 3e 54 68 65 20 6f 75 74 70 75  e>..<p>The outpu
2d610 74 20 6f 66 20 74 68 69 73 20 72 65 76 69 73 65  t of this revise
2d620 64 20 71 75 65 72 79 20 69 73 3a 0a 0a 3c 62 6c  d query is:..<bl
2d630 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 41  ockquote><pre>.A
2d640 6c 69 63 65 0a 2e 2e 2e 42 6f 62 0a 2e 2e 2e 2e  lice....Bob.....
2d650 2e 2e 44 61 76 65 0a 2e 2e 2e 2e 2e 2e 45 6d 6d  ..Dave.......Emm
2d660 61 0a 2e 2e 2e 43 69 6e 64 79 0a 2e 2e 2e 2e 2e  a....Cindy......
2d670 2e 46 72 65 64 0a 2e 2e 2e 2e 2e 2e 47 61 69 6c  .Fred.......Gail
2d680 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
2d690 6f 74 65 3e 0a 0a 3c 70 3e 57 68 65 6e 20 74 68  ote>..<p>When th
2d6a0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2d6b0 65 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  e is omitted fro
2d6c0 6d 20 74 68 65 20 72 65 63 75 72 73 69 76 65 2d  m the recursive-
2d6d0 73 65 6c 65 63 74 2c 20 74 68 65 0a 71 75 65 75  select, the.queu
2d6e0 65 20 62 65 68 61 76 65 73 20 61 73 20 61 20 46  e behaves as a F
2d6f0 49 46 4f 2c 20 77 68 69 63 68 20 72 65 73 75 6c  IFO, which resul
2d700 74 73 20 69 6e 20 61 20 62 72 65 61 64 74 68 2d  ts in a breadth-
2d710 66 69 72 73 74 20 73 65 61 72 63 68 2e 0a 0a 0a  first search....
2d720 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
2d730 20 6d 61 6e 64 65 6c 62 72 6f 74 20 7b 63 6f 6d   mandelbrot {com
2d740 70 75 74 65 20 74 68 65 20 4d 61 6e 64 65 6c 62  pute the Mandelb
2d750 72 6f 74 20 73 65 74 7d 3c 2f 74 63 6c 3e 0a 3c  rot set}</tcl>.<
2d760 68 34 3e 4f 75 74 6c 61 6e 64 69 73 68 20 52 65  h4>Outlandish Re
2d770 63 75 72 73 69 76 65 20 51 75 65 72 79 20 45 78  cursive Query Ex
2d780 61 6d 70 6c 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e  amples</h4>..<p>
2d790 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  The following qu
2d7a0 65 72 79 20 63 6f 6d 70 75 74 65 73 20 61 6e 20  ery computes an 
2d7b0 61 70 70 72 6f 78 69 6d 61 74 69 6f 6e 20 6f 66  approximation of
2d7c0 20 74 68 65 20 4d 61 6e 64 65 6c 62 72 6f 74 20   the Mandelbrot 
2d7d0 53 65 74 0a 61 6e 64 20 6f 75 74 70 75 74 73 20  Set.and outputs 
2d7e0 74 68 65 20 72 65 73 75 6c 74 20 61 73 20 41 53  the result as AS
2d7f0 43 49 49 2d 61 72 74 3a 0a 0a 3c 62 6c 6f 63 6b  CII-art:..<block
2d800 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48  quote><pre>.WITH
2d810 20 52 45 43 55 52 53 49 56 45 0a 20 20 78 61 78   RECURSIVE.  xax
2d820 69 73 28 78 29 20 41 53 20 28 56 41 4c 55 45 53  is(x) AS (VALUES
2d830 28 2d 32 2e 30 29 20 55 4e 49 4f 4e 20 41 4c 4c  (-2.0) UNION ALL
2d840 20 53 45 4c 45 43 54 20 78 2b 30 2e 30 35 20 46   SELECT x+0.05 F
2d850 52 4f 4d 20 78 61 78 69 73 20 57 48 45 52 45 20  ROM xaxis WHERE 
2d860 78 26 6c 74 3b 31 2e 32 29 2c 0a 20 20 79 61 78  x&lt;1.2),.  yax
2d870 69 73 28 79 29 20 41 53 20 28 56 41 4c 55 45 53  is(y) AS (VALUES
2d880 28 2d 31 2e 30 29 20 55 4e 49 4f 4e 20 41 4c 4c  (-1.0) UNION ALL
2d890 20 53 45 4c 45 43 54 20 79 2b 30 2e 31 20 46 52   SELECT y+0.1 FR
2d8a0 4f 4d 20 79 61 78 69 73 20 57 48 45 52 45 20 79  OM yaxis WHERE y
2d8b0 26 6c 74 3b 31 2e 30 29 2c 0a 20 20 6d 28 69 74  &lt;1.0),.  m(it
2d8c0 65 72 2c 20 63 78 2c 20 63 79 2c 20 78 2c 20 79  er, cx, cy, x, y
2d8d0 29 20 41 53 20 28 0a 20 20 20 20 53 45 4c 45 43  ) AS (.    SELEC
2d8e0 54 20 30 2c 20 78 2c 20 79 2c 20 30 2e 30 2c 20  T 0, x, y, 0.0, 
2d8f0 30 2e 30 20 46 52 4f 4d 20 78 61 78 69 73 2c 20  0.0 FROM xaxis, 
2d900 79 61 78 69 73 0a 20 20 20 20 55 4e 49 4f 4e 20  yaxis.    UNION 
2d910 41 4c 4c 0a 20 20 20 20 53 45 4c 45 43 54 20 69  ALL.    SELECT i
2d920 74 65 72 2b 31 2c 20 63 78 2c 20 63 79 2c 20 78  ter+1, cx, cy, x
2d930 2a 78 2d 79 2a 79 20 2b 20 63 78 2c 20 32 2e 30  *x-y*y + cx, 2.0
2d940 2a 78 2a 79 20 2b 20 63 79 20 46 52 4f 4d 20 6d  *x*y + cy FROM m
2d950 20 0a 20 20 20 20 20 57 48 45 52 45 20 28 78 2a   .     WHERE (x*
2d960 78 20 2b 20 79 2a 79 29 20 26 6c 74 3b 20 34 2e  x + y*y) &lt; 4.
2d970 30 20 41 4e 44 20 69 74 65 72 26 6c 74 3b 32 38  0 AND iter&lt;28
2d980 0a 20 20 29 2c 0a 20 20 6d 32 28 69 74 65 72 2c  .  ),.  m2(iter,
2d990 20 63 78 2c 20 63 79 29 20 41 53 20 28 0a 20 20   cx, cy) AS (.  
2d9a0 20 20 53 45 4c 45 43 54 20 6d 61 78 28 69 74 65    SELECT max(ite
2d9b0 72 29 2c 20 63 78 2c 20 63 79 20 46 52 4f 4d 20  r), cx, cy FROM 
2d9c0 6d 20 47 52 4f 55 50 20 42 59 20 63 78 2c 20 63  m GROUP BY cx, c
2d9d0 79 0a 20 20 29 2c 0a 20 20 61 28 74 29 20 41 53  y.  ),.  a(t) AS
2d9e0 20 28 0a 20 20 20 20 53 45 4c 45 43 54 20 67 72   (.    SELECT gr
2d9f0 6f 75 70 5f 63 6f 6e 63 61 74 28 20 73 75 62 73  oup_concat( subs
2da00 74 72 28 27 20 2e 2b 2a 23 27 2c 20 31 2b 6d 69  tr(' .+*#', 1+mi
2da10 6e 28 69 74 65 72 2f 37 2c 34 29 2c 20 31 29 2c  n(iter/7,4), 1),
2da20 20 27 27 29 20 0a 20 20 20 20 46 52 4f 4d 20 6d   '') .    FROM m
2da30 32 20 47 52 4f 55 50 20 42 59 20 63 79 0a 20 20  2 GROUP BY cy.  
2da40 29 0a 53 45 4c 45 43 54 20 67 72 6f 75 70 5f 63  ).SELECT group_c
2da50 6f 6e 63 61 74 28 72 74 72 69 6d 28 74 29 2c 78  oncat(rtrim(t),x
2da60 27 30 61 27 29 20 46 52 4f 4d 20 61 3b 0a 3c 2f  '0a') FROM a;.</
2da70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2da80 3e 0a 0a 3c 70 3e 49 6e 20 74 68 69 73 20 71 75  >..<p>In this qu
2da90 65 72 79 2c 20 74 68 65 20 22 78 61 78 69 73 22  ery, the "xaxis"
2daa0 20 61 6e 64 20 22 79 61 78 69 73 22 20 43 54 45   and "yaxis" CTE
2dab0 73 20 64 65 66 69 6e 65 20 74 68 65 20 67 72 69  s define the gri
2dac0 64 20 6f 66 20 70 6f 69 6e 74 73 20 66 6f 72 0a  d of points for.
2dad0 77 68 69 63 68 20 74 68 65 20 4d 61 6e 64 65 6c  which the Mandel
2dae0 62 72 6f 74 20 53 65 74 20 77 69 6c 6c 20 62 65  brot Set will be
2daf0 20 61 70 70 72 6f 78 69 6d 61 74 65 64 2e 20 20   approximated.  
2db00 45 61 63 68 20 72 6f 77 20 69 6e 20 74 68 65 0a  Each row in the.
2db10 22 6d 28 69 74 65 72 2c 63 78 2c 63 79 2c 78 2c  "m(iter,cx,cy,x,
2db20 79 29 22 20 43 54 45 20 6d 65 61 6e 73 20 74 68  y)" CTE means th
2db30 61 74 20 61 66 74 65 72 20 22 69 74 65 72 22 20  at after "iter" 
2db40 69 74 65 72 61 74 69 6f 6e 73 2c 20 74 68 65 20  iterations, the 
2db50 4d 61 6e 64 65 6c 62 72 6f 74 0a 69 74 65 72 61  Mandelbrot.itera
2db60 74 69 6f 6e 20 73 74 61 72 74 69 6e 67 20 61 74  tion starting at
2db70 20 63 78 2c 63 79 20 68 61 73 20 72 65 61 63 68   cx,cy has reach
2db80 65 64 20 70 6f 69 6e 74 20 78 2c 79 2e 20 20 54  ed point x,y.  T
2db90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 69 74 65  he number of ite
2dba0 72 61 74 69 6f 6e 73 0a 69 6e 20 74 68 69 73 20  rations.in this 
2dbb0 65 78 61 6d 70 6c 65 20 69 73 20 6c 69 6d 69 74  example is limit
2dbc0 65 64 20 74 6f 20 32 38 20 28 77 68 69 63 68 20  ed to 28 (which 
2dbd0 73 65 76 65 72 65 6c 79 20 6c 69 6d 69 74 73 20  severely limits 
2dbe0 74 68 65 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  the resolution o
2dbf0 66 0a 74 68 65 20 63 6f 6d 70 75 74 61 74 69 6f  f.the computatio
2dc00 6e 2c 20 62 75 74 20 69 73 20 73 75 66 66 69 63  n, but is suffic
2dc10 69 65 6e 74 20 66 6f 72 20 6c 6f 77 2d 72 65 73  ient for low-res
2dc20 6f 6c 75 74 69 6f 6e 20 41 53 43 49 49 2d 61 72  olution ASCII-ar
2dc30 74 20 6f 75 74 70 75 74 29 2e 0a 54 68 65 20 22  t output)..The "
2dc40 6d 32 28 69 74 65 72 2c 63 78 2c 63 79 29 22 20  m2(iter,cx,cy)" 
2dc50 43 54 45 20 68 6f 6c 64 73 20 74 68 65 20 6d 61  CTE holds the ma
2dc60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2dc70 69 74 65 72 61 74 69 6f 6e 73 20 72 65 61 63 68  iterations reach
2dc80 65 64 20 77 68 65 6e 0a 73 74 61 72 74 69 6e 67  ed when.starting
2dc90 20 61 74 20 70 6f 69 6e 74 20 63 78 2c 63 79 2e   at point cx,cy.
2dca0 0a 46 69 6e 61 6c 6c 79 2c 20 65 61 63 68 20 72  .Finally, each r
2dcb0 6f 77 20 69 6e 20 74 68 65 20 22 61 28 74 29 22  ow in the "a(t)"
2dcc0 20 43 54 45 20 68 6f 6c 64 73 20 61 20 73 74 72   CTE holds a str
2dcd0 69 6e 67 20 0a 77 68 69 63 68 20 69 73 20 61 20  ing .which is a 
2dce0 73 69 6e 67 6c 65 20 6c 69 6e 65 20 6f 66 20 74  single line of t
2dcf0 68 65 20 6f 75 74 70 75 74 20 41 53 43 49 49 2d  he output ASCII-
2dd00 61 72 74 2e 0a 54 68 65 20 53 45 4c 45 43 54 20  art..The SELECT 
2dd10 73 74 61 74 65 6d 65 6e 74 20 61 74 20 74 68 65  statement at the
2dd20 20 65 6e 64 20 6a 75 73 74 20 71 75 65 72 69 65   end just querie
2dd30 73 20 74 68 65 20 22 61 22 20 43 54 45 20 74 6f  s the "a" CTE to
2dd40 0a 72 65 74 72 69 65 76 65 20 61 6c 6c 20 6c 69  .retrieve all li
2dd50 6e 65 73 20 6f 66 20 41 53 43 49 49 2d 61 72 74  nes of ASCII-art
2dd60 2c 20 6f 6e 65 20 62 79 20 6f 6e 65 2e 0a 0a 3c  , one by one...<
2dd70 70 3e 52 75 6e 6e 69 6e 67 20 74 68 65 20 71 75  p>Running the qu
2dd80 65 72 79 20 61 62 6f 76 65 20 69 6e 20 61 6e 20  ery above in an 
2dd90 53 51 4c 69 74 65 20 5b 63 6f 6d 6d 61 6e 64 2d  SQLite [command-
2dda0 6c 69 6e 65 20 73 68 65 6c 6c 5d 20 72 65 73 75  line shell] resu
2ddb0 6c 74 73 0a 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  lts.in the follo
2ddc0 77 69 6e 67 20 6f 75 74 70 75 74 3a 0a 0a 3c 62  wing output:..<b
2ddd0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2dde0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ddf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de00 20 20 20 20 2e 2e 2e 2e 23 0a 20 20 20 20 20 20      ....#.      
2de10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 23               ..#
2de30 2a 2e 2e 0a 20 20 20 20 20 20 20 20 20 20 20 20  *...            
2de40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de50 20 20 20 20 20 2e 2e 2b 23 23 23 23 2b 2e 0a 20       ..+####+.. 
2de60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de70 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e 2e             .....
2de80 2e 2e 2b 23 23 23 23 2e 2e 2e 2e 20 20 20 2b 0a  ..+####....   +.
2de90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dea0 20 20 20 20 20 20 20 20 20 20 20 2e 2e 23 23 2b             ..##+
2deb0 2a 23 23 23 23 23 23 23 23 23 23 2b 2e 2b 2b 2b  *##########+.+++
2dec0 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  +.              
2ded0 20 20 20 20 20 20 20 20 20 20 20 20 2e 2b 2e 23              .+.#
2dee0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2def0 23 2b 2e 0a 20 20 20 20 20 20 20 20 20 20 20 20  #+..            
2df00 20 20 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2b    .............+
2df10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2df20 23 23 23 2b 2e 2b 0a 20 20 20 20 20 20 20 20 20  ###+.+.         
2df30 20 20 20 20 20 2e 2e 2b 2b 2e 2e 23 2e 2e 2e 2e       ..++..#....
2df40 2e 2a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .*##############
2df50 23 23 23 23 23 23 23 2b 2e 0a 20 20 20 20 20 20  #######+..      
2df60 20 20 20 20 20 20 20 2e 2e 2e 2b 23 23 23 23 23         ...+#####
2df70 23 23 2b 2b 23 23 23 23 23 23 23 23 23 23 23 23  ##++############
2df80 23 23 23 23 23 23 23 23 23 23 23 2e 0a 20 20 20  ###########..   
2df90 20 20 20 20 20 20 20 2e 2e 2e 2e 2b 2a 23 23 23         ....+*###
2dfa0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dfb0 23 23 23 23 23 23 23 23 23 23 23 23 23 2e 0a 20  #############.. 
2dfc0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dfd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dfe0 23 23 23 23 23 23 23 23 23 23 23 23 23 2e 2e 2e  #############...
2dff0 0a 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e 2b  .          ....+
2e000 2a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  *###############
2e010 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e020 23 2e 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  #..             
2e030 2e 2e 2e 2b 23 23 23 23 23 23 23 2b 2b 23 23 23  ...+#######++###
2e040 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2e050 23 23 23 23 2e 0a 20 20 20 20 20 20 20 20 20 20  ####..          
2e060 20 20 20 20 2e 2e 2b 2b 2e 2e 23 2e 2e 2e 2e 2e      ..++..#.....
2e070 2a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  *###############
2e080 23 23 23 23 23 23 2b 2e 0a 20 20 20 20 20 20 20  ######+..       
2e090 20 20 20 20 20 20 20 2e 2e 2e 2e 2e 2e 2e 2e 2e         .........
2e0a0 2e 2e 2e 2e 2b 23 23 23 23 23 23 23 23 23 23 23  ....+###########
2e0b0 23 23 23 23 23 23 23 23 2b 2e 2b 0a 20 20 20 20  ########+.+.    
2e0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e0d0 20 20 20 20 20 20 2e 2b 2e 23 23 23 23 23 23 23        .+.#######
2e0e0 23 23 23 23 23 23 23 23 23 23 23 2b 2e 0a 20 20  ###########+..  
2e0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e100 20 20 20 20 20 20 20 20 20 2e 2e 23 23 2b 2a 23           ..##+*#
2e110 23 23 23 23 23 23 23 23 23 2b 2e 2b 2b 2b 2b 0a  #########+.++++.
2e120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e130 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e              ....
2e140 2e 2e 2e 2b 23 23 23 23 2e 2e 2e 2e 20 20 20 2b  ...+####....   +
2e150 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e170 20 20 2e 2e 2b 23 23 23 23 2b 2e 0a 20 20 20 20    ..+####+..    
2e180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e                 .
2e1a0 2e 23 2a 2e 2e 0a 20 20 20 20 20 20 20 20 20 20  .#*...          
2e1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e1c0 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2e 23 0a            ....#.
2e1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e1e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e1f0 20 20 20 20 2b 2e 0a 3c 2f 70 72 65 3e 3c 2f 62      +..</pre></b
2e200 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 74 63 6c  lockquote>..<tcl
2e210 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 73 75 64  >hd_fragment sud
2e220 6f 6b 75 20 7b 73 6f 6c 76 65 20 53 75 64 6f 6b  oku {solve Sudok
2e230 75 20 70 75 7a 7a 6c 65 73 7d 20 3c 2f 74 63 6c  u puzzles} </tcl
2e240 3e 0a 3c 70 3e 54 68 69 73 20 6e 65 78 74 20 71  >.<p>This next q
2e250 75 65 72 79 20 73 6f 6c 76 65 73 20 61 20 53 75  uery solves a Su
2e260 64 6f 6b 75 20 70 75 7a 7a 6c 65 2e 20 20 54 68  doku puzzle.  Th
2e270 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 70  e state of the p
2e280 75 7a 7a 6c 65 20 69 73 0a 64 65 66 69 6e 65 64  uzzle is.defined
2e290 20 62 79 20 61 6e 20 38 31 2d 63 68 61 72 61 63   by an 81-charac
2e2a0 74 65 72 20 73 74 72 69 6e 67 20 66 6f 72 6d 65  ter string forme
2e2b0 64 20 62 79 20 72 65 61 64 69 6e 67 20 65 6e 74  d by reading ent
2e2c0 72 69 65 73 20 66 72 6f 6d 20 74 68 65 0a 70 75  ries from the.pu
2e2d0 7a 7a 6c 65 20 62 6f 78 20 72 6f 77 20 62 79 20  zzle box row by 
2e2e0 72 6f 77 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f  row from left to
2e2f0 20 72 69 67 68 74 20 61 6e 64 20 74 68 65 6e 20   right and then 
2e300 66 72 6f 6d 20 74 6f 70 20 74 6f 20 62 6f 74 74  from top to bott
2e310 6f 6d 2e 0a 42 6c 61 6e 6b 20 73 71 75 61 72 65  om..Blank square
2e320 73 20 69 6e 20 74 68 65 20 70 75 7a 7a 6c 65 20  s in the puzzle 
2e330 61 72 65 20 64 65 6e 6f 74 65 64 20 62 79 20 61  are denoted by a
2e340 20 22 2e 22 20 63 68 61 72 61 63 74 65 72 2e 20   "." character. 
2e350 20 0a 54 68 75 73 20 74 68 65 20 69 6e 70 75 74   .Thus the input
2e360 20 73 74 72 69 6e 67 3a 0a 0a 3c 62 6c 6f 63 6b   string:..<block
2e370 71 75 6f 74 65 3e 0a 35 33 2e 2e 37 2e 2e 2e 2e  quote>.53..7....
2e380 36 2e 2e 31 39 35 2e 2e 2e 2e 39 38 2e 2e 2e 2e  6..195....98....
2e390 36 2e 38 2e 2e 2e 36 2e 2e 2e 33 34 2e 2e 38 2e  6.8...6...34..8.
2e3a0 33 2e 2e 31 37 2e 2e 2e 32 2e 2e 2e 36 2e 36 2e  3..17...2...6.6.
2e3b0 2e 2e 2e 32 38 2e 2e 2e 2e 34 31 39 2e 2e 35 2e  ...28....419..5.
2e3c0 2e 2e 2e 38 2e 2e 37 39 0a 3c 2f 62 6c 6f 63 6b  ...8..79.</block
2e3d0 71 75 6f 74 65 3e 0a 0a 3c 70 3e 43 6f 72 72 65  quote>..<p>Corre
2e3e0 73 70 6f 6e 64 73 20 74 6f 20 61 20 70 75 7a 7a  sponds to a puzz
2e3f0 6c 65 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a 3c  le like this:..<
2e400 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 74 61 62  blockquote>.<tab
2e410 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 63 65  le border="1" ce
2e420 6c 6c 70 61 64 64 69 6e 67 3d 22 35 22 3e 0a 3c  llpadding="5">.<
2e430 74 72 3e 3c 74 64 3e 35 3c 74 64 3e 33 3c 74 64  tr><td>5<td>3<td
2e440 3e 20 3c 74 64 3e 20 3c 74 64 3e 37 3c 74 64 3e  > <td> <td>7<td>
2e450 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 0a   <td> <td> <td>.
2e460 3c 74 72 3e 3c 74 64 3e 36 3c 74 64 3e 20 3c 74  <tr><td>6<td> <t
2e470 64 3e 20 3c 74 64 3e 31 3c 74 64 3e 39 3c 74 64  d> <td>1<td>9<td
2e480 3e 35 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e  >5<td> <td> <td>
2e490 0a 3c 74 72 3e 3c 74 64 3e 20 3c 74 64 3e 39 3c  .<tr><td> <td>9<
2e4a0 74 64 3e 38 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td>8<td> <td> <t
2e4b0 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 36 3c 74 64  d> <td> <td>6<td
2e4c0 3e 0a 3c 74 72 3e 3c 74 64 3e 38 3c 74 64 3e 20  >.<tr><td>8<td> 
2e4d0 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 36 3c  <td> <td> <td>6<
2e4e0 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
2e4f0 64 3e 33 0a 3c 74 72 3e 3c 74 64 3e 34 3c 74 64  d>3.<tr><td>4<td
2e500 3e 20 3c 74 64 3e 20 3c 74 64 3e 38 3c 74 64 3e  > <td> <td>8<td>
2e510 20 3c 74 64 3e 33 3c 74 64 3e 20 3c 74 64 3e 20   <td>3<td> <td> 
2e520 3c 74 64 3e 31 0a 3c 74 72 3e 3c 74 64 3e 37 3c  <td>1.<tr><td>7<
2e530 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
2e540 64 3e 32 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64  d>2<td> <td> <td
2e550 3e 20 3c 74 64 3e 36 0a 3c 74 72 3e 3c 74 64 3e  > <td>6.<tr><td>
2e560 20 3c 74 64 3e 36 3c 74 64 3e 20 3c 74 64 3e 20   <td>6<td> <td> 
2e570 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 32 3c  <td> <td> <td>2<
2e580 74 64 3e 38 3c 74 64 3e 0a 3c 74 72 3e 3c 74 64  td>8<td>.<tr><td
2e590 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e  > <td> <td> <td>
2e5a0 34 3c 74 64 3e 31 3c 74 64 3e 39 3c 74 64 3e 20  4<td>1<td>9<td> 
2e5b0 3c 74 64 3e 20 3c 74 64 3e 35 0a 3c 74 72 3e 3c  <td> <td>5.<tr><
2e5c0 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
2e5d0 64 3e 20 3c 74 64 3e 38 3c 74 64 3e 20 3c 74 64  d> <td>8<td> <td
2e5e0 3e 20 3c 74 64 3e 37 3c 74 64 3e 39 0a 3c 2f 74  > <td>7<td>9.</t
2e5f0 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  able>.</blockquo
2e600 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20  te>..<p>This is 
2e610 74 68 65 20 71 75 65 72 79 20 74 68 61 74 20 73  the query that s
2e620 6f 6c 76 65 73 20 74 68 65 20 70 75 7a 7a 6c 65  olves the puzzle
2e630 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  :..<blockquote><
2e640 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55 52 53  pre>.WITH RECURS
2e650 49 56 45 0a 20 20 69 6e 70 75 74 28 73 75 64 29  IVE.  input(sud)
2e660 20 41 53 20 28 0a 20 20 20 20 56 41 4c 55 45 53   AS (.    VALUES
2e670 28 27 35 33 2e 2e 37 2e 2e 2e 2e 36 2e 2e 31 39  ('53..7....6..19
2e680 35 2e 2e 2e 2e 39 38 2e 2e 2e 2e 36 2e 38 2e 2e  5....98....6.8..
2e690 2e 36 2e 2e 2e 33 34 2e 2e 38 2e 33 2e 2e 31 37  .6...34..8.3..17
2e6a0 2e 2e 2e 32 2e 2e 2e 36 2e 36 2e 2e 2e 2e 32 38  ...2...6.6....28
2e6b0 2e 2e 2e 2e 34 31 39 2e 2e 35 2e 2e 2e 2e 38 2e  ....419..5....8.
2e6c0 2e 37 39 27 29 0a 20 20 29 2c 0a 20 20 64 69 67  .79').  ),.  dig
2e6d0 69 74 73 28 7a 2c 20 6c 70 29 20 41 53 20 28 0a  its(z, lp) AS (.
2e6e0 20 20 20 20 56 41 4c 55 45 53 28 27 31 27 2c 20      VALUES('1', 
2e6f0 31 29 0a 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c  1).    UNION ALL
2e700 20 53 45 4c 45 43 54 0a 20 20 20 20 43 41 53 54   SELECT.    CAST
2e710 28 6c 70 2b 31 20 41 53 20 54 45 58 54 29 2c 20  (lp+1 AS TEXT), 
2e720 6c 70 2b 31 20 46 52 4f 4d 20 64 69 67 69 74 73  lp+1 FROM digits
2e730 20 57 48 45 52 45 20 6c 70 26 6c 74 3b 39 0a 20   WHERE lp&lt;9. 
2e740 20 29 2c 0a 20 20 78 28 73 2c 20 69 6e 64 29 20   ),.  x(s, ind) 
2e750 41 53 20 28 0a 20 20 20 20 53 45 4c 45 43 54 20  AS (.    SELECT 
2e760 73 75 64 2c 20 69 6e 73 74 72 28 73 75 64 2c 20  sud, instr(sud, 
2e770 27 2e 27 29 20 46 52 4f 4d 20 69 6e 70 75 74 0a  '.') FROM input.
2e780 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20      UNION ALL.  
2e790 20 20 53 45 4c 45 43 54 0a 20 20 20 20 20 20 73    SELECT.      s
2e7a0 75 62 73 74 72 28 73 2c 20 31 2c 20 69 6e 64 2d  ubstr(s, 1, ind-
2e7b0 31 29 20 7c 7c 20 7a 20 7c 7c 20 73 75 62 73 74  1) || z || subst
2e7c0 72 28 73 2c 20 69 6e 64 2b 31 29 2c 0a 20 20 20  r(s, ind+1),.   
2e7d0 20 20 20 69 6e 73 74 72 28 20 73 75 62 73 74 72     instr( substr
2e7e0 28 73 2c 20 31 2c 20 69 6e 64 2d 31 29 20 7c 7c  (s, 1, ind-1) ||
2e7f0 20 7a 20 7c 7c 20 73 75 62 73 74 72 28 73 2c 20   z || substr(s, 
2e800 69 6e 64 2b 31 29 2c 20 27 2e 27 20 29 0a 20 20  ind+1), '.' ).  
2e810 20 20 20 46 52 4f 4d 20 78 2c 20 64 69 67 69 74     FROM x, digit
2e820 73 20 41 53 20 7a 0a 20 20 20 20 57 48 45 52 45  s AS z.    WHERE
2e830 20 69 6e 64 3e 30 0a 20 20 20 20 20 20 41 4e 44   ind>0.      AND
2e840 20 4e 4f 54 20 45 58 49 53 54 53 20 28 0a 20 20   NOT EXISTS (.  
2e850 20 20 20 20 20 20 20 20 20 20 53 45 4c 45 43 54            SELECT
2e860 20 31 0a 20 20 20 20 20 20 20 20 20 20 20 20 20   1.             
2e870 20 46 52 4f 4d 20 64 69 67 69 74 73 20 41 53 20   FROM digits AS 
2e880 6c 70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  lp.             
2e890 57 48 45 52 45 20 7a 2e 7a 20 3d 20 73 75 62 73  WHERE z.z = subs
2e8a0 74 72 28 73 2c 20 28 28 69 6e 64 2d 31 29 2f 39  tr(s, ((ind-1)/9
2e8b0 29 2a 39 20 2b 20 6c 70 2c 20 31 29 0a 20 20 20  )*9 + lp, 1).   
2e8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 4f 52 20               OR 
2e8d0 7a 2e 7a 20 3d 20 73 75 62 73 74 72 28 73 2c 20  z.z = substr(s, 
2e8e0 28 28 69 6e 64 2d 31 29 25 39 29 20 2b 20 28 6c  ((ind-1)%9) + (l
2e8f0 70 2d 31 29 2a 39 20 2b 20 31 2c 20 31 29 0a 20  p-1)*9 + 1, 1). 
2e900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4f                 O
2e910 52 20 7a 2e 7a 20 3d 20 73 75 62 73 74 72 28 73  R z.z = substr(s
2e920 2c 20 28 28 28 69 6e 64 2d 31 29 2f 33 29 20 25  , (((ind-1)/3) %
2e930 20 33 29 20 2a 20 33 0a 20 20 20 20 20 20 20 20   3) * 3.        
2e940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e950 2b 20 28 28 69 6e 64 2d 31 29 2f 32 37 29 20 2a  + ((ind-1)/27) *
2e960 20 32 37 20 2b 20 6c 70 0a 20 20 20 20 20 20 20   27 + lp.       
2e970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e980 20 2b 20 28 28 6c 70 2d 31 29 20 2f 20 33 29 20   + ((lp-1) / 3) 
2e990 2a 20 36 2c 20 31 29 0a 20 20 20 20 20 20 20 20  * 6, 1).        
2e9a0 20 29 0a 20 20 29 0a 53 45 4c 45 43 54 20 73 20   ).  ).SELECT s 
2e9b0 46 52 4f 4d 20 78 20 57 48 45 52 45 20 69 6e 64  FROM x WHERE ind
2e9c0 3d 30 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  =0;.</pre></bloc
2e9d0 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
2e9e0 22 69 6e 70 75 74 22 20 43 54 45 20 64 65 66 69  "input" CTE defi
2e9f0 6e 65 73 20 74 68 65 20 69 6e 70 75 74 20 70 75  nes the input pu
2ea00 7a 7a 6c 65 2e 0a 54 68 65 20 22 64 69 67 69 74  zzle..The "digit
2ea10 73 22 20 43 54 45 20 64 65 66 69 6e 65 73 20 61  s" CTE defines a
2ea20 20 74 61 62 6c 65 20 74 68 61 74 20 68 6f 6c 64   table that hold
2ea30 73 20 61 6c 6c 20 64 69 67 69 74 73 20 62 65 74  s all digits bet
2ea40 77 65 65 6e 20 31 20 61 6e 64 20 39 2e 0a 54 68  ween 1 and 9..Th
2ea50 65 20 77 6f 72 6b 20 6f 66 20 73 6f 6c 76 69 6e  e work of solvin
2ea60 67 20 74 68 65 20 70 75 7a 7a 6c 65 20 69 73 20  g the puzzle is 
2ea70 75 6e 64 65 72 74 61 6b 65 6e 20 62 79 20 74 68  undertaken by th
2ea80 65 20 22 78 22 20 43 54 45 2e 0a 41 6e 20 65 6e  e "x" CTE..An en
2ea90 74 72 79 20 69 6e 20 78 28 73 2c 69 6e 64 29 20  try in x(s,ind) 
2eaa0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 38  means that the 8
2eab0 31 2d 63 68 61 72 61 63 74 65 72 20 73 74 72 69  1-character stri
2eac0 6e 67 20 22 73 22 20 69 73 20 61 20 76 61 6c 69  ng "s" is a vali
2ead0 64 0a 73 75 64 6f 6b 75 20 70 75 7a 7a 6c 65 20  d.sudoku puzzle 
2eae0 28 69 74 20 68 61 73 20 6e 6f 20 63 6f 6e 66 6c  (it has no confl
2eaf0 69 63 74 73 29 20 61 6e 64 20 74 68 61 74 20 74  icts) and that t
2eb00 68 65 20 66 69 72 73 74 20 75 6e 6b 6e 6f 77 6e  he first unknown
2eb10 20 63 68 61 72 61 63 74 65 72 0a 69 73 20 61 74   character.is at
2eb20 20 70 6f 73 69 74 69 6f 6e 20 22 69 6e 64 22 2c   position "ind",
2eb30 20 6f 72 20 69 6e 64 3d 3d 30 20 69 66 20 61 6c   or ind==0 if al
2eb40 6c 20 63 68 61 72 61 63 74 65 72 20 70 6f 73 69  l character posi
2eb50 74 69 6f 6e 73 20 61 72 65 20 66 69 6c 6c 65 64  tions are filled
2eb60 20 69 6e 2e 0a 54 68 65 20 67 6f 61 6c 2c 20 74   in..The goal, t
2eb70 68 65 6e 2c 20 69 73 20 74 6f 20 63 6f 6d 70 75  hen, is to compu
2eb80 74 65 20 65 6e 74 72 69 65 73 20 66 6f 72 20 22  te entries for "
2eb90 78 22 20 77 69 74 68 20 61 6e 20 22 69 6e 64 22  x" with an "ind"
2eba0 20 6f 66 20 30 2e 0a 0a 3c 70 3e 54 68 65 20 73   of 0...<p>The s
2ebb0 6f 6c 76 65 72 20 77 6f 72 6b 73 20 62 79 20 61  olver works by a
2ebc0 64 64 69 6e 67 20 6e 65 77 20 65 6e 74 72 69 65  dding new entrie
2ebd0 73 20 74 6f 20 74 68 65 20 22 78 22 20 72 65 63  s to the "x" rec
2ebe0 75 72 73 69 76 65 20 74 61 62 6c 65 2e 0a 47 69  ursive table..Gi
2ebf0 76 65 6e 20 70 72 69 6f 72 20 65 6e 74 72 69 65  ven prior entrie
2ec00 73 2c 20 74 68 65 20 72 65 63 75 72 73 69 76 65  s, the recursive
2ec10 2d 73 65 6c 65 63 74 20 74 72 69 65 73 20 74 6f  -select tries to
2ec20 20 66 69 6c 6c 20 69 6e 20 61 20 73 69 6e 67 6c   fill in a singl
2ec30 65 20 6e 65 77 0a 70 6f 73 69 74 69 6f 6e 20 77  e new.position w
2ec40 69 74 68 20 61 6c 6c 20 76 61 6c 75 65 73 20 62  ith all values b
2ec50 65 74 77 65 65 6e 20 31 20 61 6e 64 20 39 20 74  etween 1 and 9 t
2ec60 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
2ec70 6b 20 69 6e 20 74 68 61 74 0a 70 6f 73 69 74 69  k in that.positi
2ec80 6f 6e 2e 20 20 54 68 65 20 63 6f 6d 70 6c 69 63  on.  The complic
2ec90 61 74 65 64 20 22 4e 4f 54 20 45 58 49 53 54 53  ated "NOT EXISTS
2eca0 22 20 73 75 62 71 75 65 72 79 20 69 73 20 74 68  " subquery is th
2ecb0 65 20 6d 61 67 69 63 20 74 68 61 74 0a 66 69 67  e magic that.fig
2ecc0 75 72 65 73 20 6f 75 74 20 77 68 65 74 68 65 72  ures out whether
2ecd0 20 6f 72 20 6e 6f 74 20 65 61 63 68 20 63 61 6e   or not each can
2ece0 64 69 64 61 74 65 20 22 73 22 20 73 74 72 69 6e  didate "s" strin
2ecf0 67 20 69 73 20 61 20 76 61 6c 69 64 0a 73 75 64  g is a valid.sud
2ed00 6f 6b 75 20 70 75 7a 7a 6c 65 20 6f 72 20 6e 6f  oku puzzle or no
2ed10 74 2e 0a 0a 3c 70 3e 54 68 65 20 66 69 6e 61 6c  t...<p>The final
2ed20 20 61 6e 73 77 65 72 20 69 73 20 66 6f 75 6e 64   answer is found
2ed30 20 62 79 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 20   by looking for 
2ed40 61 20 73 74 72 69 6e 67 20 77 69 74 68 20 69 6e  a string with in
2ed50 64 3d 3d 30 2e 0a 49 66 20 74 68 65 20 6f 72 69  d==0..If the ori
2ed60 67 69 6e 61 6c 20 73 75 64 6f 6b 75 20 70 72 6f  ginal sudoku pro
2ed70 62 6c 65 6d 20 64 69 64 20 6e 6f 74 20 68 61 76  blem did not hav
2ed80 65 20 61 20 75 6e 69 71 75 65 20 73 6f 6c 75 74  e a unique solut
2ed90 69 6f 6e 2c 20 74 68 65 6e 0a 74 68 65 20 71 75  ion, then.the qu
2eda0 65 72 79 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ery will return 
2edb0 61 6c 6c 20 70 6f 73 73 69 62 6c 65 20 73 6f 6c  all possible sol
2edc0 75 74 69 6f 6e 73 2e 20 20 49 66 20 74 68 65 20  utions.  If the 
2edd0 6f 72 69 67 69 6e 61 6c 20 70 72 6f 62 6c 65 6d  original problem
2ede0 0a 77 61 73 20 75 6e 73 6f 6c 76 61 62 6c 65 2c  .was unsolvable,
2edf0 20 74 68 65 6e 20 6e 6f 20 72 6f 77 73 20 77 69   then no rows wi
2ee00 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
2ee10 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74   In this case, t
2ee20 68 65 20 75 6e 69 71 75 65 0a 61 6e 73 77 65 72  he unique.answer
2ee30 20 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74   is:..<blockquot
2ee40 65 3e 0a 35 33 34 36 37 38 39 31 32 36 37 32 31  e>.5346789126721
2ee50 39 35 33 34 38 31 39 38 33 34 32 35 36 37 38 35  9534819834256785
2ee60 39 37 36 31 34 32 33 34 32 36 38 35 33 37 39 31  9761423426853791
2ee70 37 31 33 39 32 34 38 35 36 39 36 31 35 33 37 32  7139248569615372
2ee80 38 34 32 38 37 34 31 39 36 33 35 33 34 35 32 38  8428741963534528
2ee90 36 31 37 39 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  6179.</blockquot
2eea0 65 3e 0a 0a 3c 70 3e 54 68 65 20 73 6f 6c 75 74  e>..<p>The solut
2eeb0 69 6f 6e 20 77 61 73 20 63 6f 6d 70 75 74 65 64  ion was computed
2eec0 20 69 6e 20 6c 65 73 73 20 74 68 61 6e 20 33 30   in less than 30
2eed0 30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  0 milliseconds o
2eee0 6e 20 61 20 6d 6f 64 65 72 6e 0a 77 6f 72 6b 73  n a modern.works
2eef0 74 61 74 69 6f 6e 2e 0a 0a 3c 68 33 3e 4c 69 6d  tation...<h3>Lim
2ef00 69 74 61 74 69 6f 6e 73 20 41 6e 64 20 43 61 76  itations And Cav
2ef10 65 61 74 73 3c 2f 68 33 3e 0a 0a 3c 75 6c 3e 0a  eats</h3>..<ul>.
2ef20 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20 57 49 54 48  <li><p>.The WITH
2ef30 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f 74 20 62   clause cannot b
2ef40 65 20 75 73 65 64 20 77 69 74 68 69 6e 20 61 20  e used within a 
2ef50 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 5d  [CREATE TRIGGER]
2ef60 2e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20 57 49  ..<li><p>.The WI
2ef70 54 48 20 63 6c 61 75 73 65 20 6d 75 73 74 20 61  TH clause must a
2ef80 70 70 65 61 72 20 61 74 20 74 68 65 20 62 65 67  ppear at the beg
2ef90 69 6e 6e 69 6e 67 20 6f 66 20 61 20 74 6f 70 2d  inning of a top-
2efa0 6c 65 76 65 6c 20 5b 53 45 4c 45 43 54 5d 20 73  level [SELECT] s
2efb0 74 61 74 65 6d 65 6e 74 0a 6f 72 20 61 74 20 74  tatement.or at t
2efc0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2efd0 61 20 73 75 62 71 75 65 72 79 2e 20 20 54 68 65  a subquery.  The
2efe0 20 57 49 54 48 20 63 6c 61 75 73 65 20 63 61 6e   WITH clause can
2eff0 6e 6f 74 20 62 65 20 70 72 65 70 65 6e 64 65 64  not be prepended
2f000 20 74 6f 0a 74 68 65 20 73 65 63 6f 6e 64 20 6f   to.the second o
2f010 72 20 73 75 62 73 65 71 75 65 6e 74 20 53 45 4c  r subsequent SEL
2f020 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 6f 66  ECT statement of
2f030 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 73 65 6c   a [compound sel
2f040 65 63 74 5d 2e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68  ect]..<li><p>.Th
2f050 65 20 53 51 4c 3a 31 39 39 39 20 73 70 65 63 20  e SQL:1999 spec 
2f060 72 65 71 75 69 72 65 73 20 74 68 61 74 20 74 68  requires that th
2f070 65 20 52 45 43 55 52 53 49 56 45 20 6b 65 79 77  e RECURSIVE keyw
2f080 6f 72 64 20 66 6f 6c 6c 6f 77 20 57 49 54 48 20  ord follow WITH 
2f090 69 6e 20 61 6e 79 0a 57 49 54 48 20 63 6c 61 75  in any.WITH clau
2f0a0 73 65 20 74 68 61 74 20 69 6e 63 6c 75 64 65 73  se that includes
2f0b0 20 61 20 72 65 63 75 72 73 69 76 65 20 63 6f 6d   a recursive com
2f0c0 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
2f0d0 73 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20  sion.  However, 
2f0e0 66 6f 72 0a 63 6f 6d 70 61 74 69 62 69 6c 69 74  for.compatibilit
2f0f0 79 20 77 69 74 68 20 53 71 6c 53 65 72 76 65 72  y with SqlServer
2f100 20 61 6e 64 20 4f 72 61 63 6c 65 2c 20 53 51 4c   and Oracle, SQL
2f110 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 65 6e 66  ite does not enf
2f120 6f 72 63 65 20 74 68 69 73 20 72 75 6c 65 2e 0a  orce this rule..
2f130 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23  </ul>..<tcl>.###
2f140 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f150 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f160 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f170 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2f180 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63  ############.Sec
2f190 74 69 6f 6e 20 53 45 4c 45 43 54 20 73 65 6c 65  tion SELECT sele
2f1a0 63 74 20 7b 53 45 4c 45 43 54 20 71 75 65 72 79  ct {SELECT query
2f1b0 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
2f1c0 6c 65 44 69 61 67 72 61 6d 20 73 65 6c 65 63 74  leDiagram select
2f1d0 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c  -stmt.</tcl>...<
2f1e0 70 3e 54 68 65 20 53 45 4c 45 43 54 20 73 74 61  p>The SELECT sta
2f1f0 74 65 6d 65 6e 74 20 69 73 20 75 73 65 64 20 74  tement is used t
2f200 6f 20 71 75 65 72 79 20 74 68 65 20 64 61 74 61  o query the data
2f210 62 61 73 65 2e 20 20 54 68 65 0a 72 65 73 75 6c  base.  The.resul
2f220 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 69 73  t of a SELECT is
2f230 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 72 6f   zero or more ro
2f240 77 73 20 6f 66 20 64 61 74 61 20 77 68 65 72 65  ws of data where
2f250 20 65 61 63 68 20 72 6f 77 0a 68 61 73 20 61 20   each row.has a 
2f260 66 69 78 65 64 20 6e 75 6d 62 65 72 20 6f 66 20  fixed number of 
2f270 63 6f 6c 75 6d 6e 73 2e 20 20 41 20 53 45 4c 45  columns.  A SELE
2f280 43 54 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  CT statement doe
2f290 73 20 6e 6f 74 20 6d 61 6b 65 0a 61 6e 79 20 63  s not make.any c
2f2a0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 64 61  hanges to the da
2f2b0 74 61 62 61 73 65 2e 0a 0a 3c 70 3e 54 68 65 20  tabase...<p>The 
2f2c0 22 5b 73 65 6c 65 63 74 2d 73 74 6d 74 5d 22 20  "[select-stmt]" 
2f2d0 73 79 6e 74 61 78 20 64 69 61 67 72 61 6d 20 61  syntax diagram a
2f2e0 62 6f 76 65 20 61 74 74 65 6d 70 74 73 20 74 6f  bove attempts to
2f2f0 20 73 68 6f 77 20 61 73 20 6d 75 63 68 20 6f 66   show as much of
2f300 20 74 68 65 0a 53 45 4c 45 43 54 20 73 74 61 74   the.SELECT stat
2f310 65 6d 65 6e 74 20 73 79 6e 74 61 78 20 61 73 20  ement syntax as 
2f320 70 6f 73 73 69 62 6c 65 20 69 6e 20 61 20 73 69  possible in a si
2f330 6e 67 6c 65 20 64 69 61 67 72 61 6d 2c 20 62 65  ngle diagram, be
2f340 63 61 75 73 65 20 73 6f 6d 65 20 72 65 61 64 65  cause some reade
2f350 72 73 0a 66 69 6e 64 20 74 68 61 74 20 68 65 6c  rs.find that hel
2f360 70 66 75 6c 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  pful.  The follo
2f370 77 69 6e 67 20 22 5b 66 61 63 74 6f 72 65 64 2d  wing "[factored-
2f380 73 65 6c 65 63 74 2d 73 74 6d 74 5d 22 20 69 73  select-stmt]" is
2f390 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
2f3a0 73 79 6e 74 61 78 20 64 69 61 67 72 61 6d 73 20  syntax diagrams 
2f3b0 74 68 61 74 20 65 78 70 72 65 73 73 65 73 20 74  that expresses t
2f3c0 68 65 20 73 61 6d 65 20 73 79 6e 74 61 78 20 62  he same syntax b
2f3d0 75 74 20 74 72 69 65 73 20 74 6f 20 62 72 65 61  ut tries to brea
2f3e0 6b 20 74 68 65 20 73 79 6e 74 61 78 20 0a 64 6f  k the syntax .do
2f3f0 77 6e 20 69 6e 74 6f 20 73 6d 61 6c 6c 65 72 20  wn into smaller 
2f400 63 68 75 6e 6b 73 2e 0a 0a 3c 74 63 6c 3e 0a 52  chunks...<tcl>.R
2f410 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
2f420 61 67 72 61 6d 20 2d 2d 69 6e 69 74 69 61 6c 6c  agram --initiall
2f430 79 2d 68 69 64 64 65 6e 20 66 61 63 74 6f 72 65  y-hidden factore
2f440 64 2d 73 65 6c 65 63 74 2d 73 74 6d 74 20 73 65  d-select-stmt se
2f450 6c 65 63 74 2d 63 6f 72 65 0a 3c 2f 74 63 6c 3e  lect-core.</tcl>
2f460 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20 74  ..<p>Note that t
2f470 68 65 72 65 20 61 72 65 20 70 61 74 68 73 20 74  here are paths t
2f480 68 72 6f 75 67 68 20 74 68 65 20 73 79 6e 74 61  hrough the synta
2f490 78 20 64 69 61 67 72 61 6d 73 20 74 68 61 74 0a  x diagrams that.
2f4a0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
2f4b0 69 6e 20 70 72 61 63 74 69 63 65 2e 20 20 53 6f  in practice.  So
2f4c0 6d 65 20 65 78 61 6d 70 6c 65 73 3a 0a 3c 75 6c  me examples:.<ul
2f4d0 3e 0a 3c 6c 69 3e 41 20 5b 56 41 4c 55 45 53 5d  >.<li>A [VALUES]
2f4e0 20 63 6c 61 75 73 65 20 63 61 6e 20 62 65 20 74   clause can be t
2f4f0 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
2f500 20 69 6e 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20   in a [compound 
2f510 53 45 4c 45 43 54 5d 0a 20 20 20 20 74 68 61 74  SELECT].    that
2f520 20 75 73 65 73 20 61 20 5b 57 49 54 48 5d 20 63   uses a [WITH] c
2f530 6c 61 75 73 65 2c 20 62 75 74 20 61 20 5b 73 69  lause, but a [si
2f540 6d 70 6c 65 20 53 45 4c 45 43 54 5d 20 74 68 61  mple SELECT] tha
2f550 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 0a 20 20  t consists of.  
2f560 20 20 6a 75 73 74 20 61 20 5b 56 41 4c 55 45 53    just a [VALUES
2f570 5d 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f 74 20  ] clause cannot 
2f580 62 65 20 70 72 65 63 65 64 65 64 20 62 79 20 61  be preceded by a
2f590 20 5b 57 49 54 48 5d 20 63 6c 61 75 73 65 2e 0a   [WITH] clause..
2f5a0 3c 6c 69 3e 54 68 65 20 5b 57 49 54 48 5d 20 63  <li>The [WITH] c
2f5b0 6c 61 75 73 65 20 6d 75 73 74 20 6f 63 63 75 72  lause must occur
2f5c0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 53 45   on the first SE
2f5d0 4c 45 43 54 20 6f 66 20 61 20 5b 63 6f 6d 70 6f  LECT of a [compo
2f5e0 75 6e 64 20 53 45 4c 45 43 54 5d 2e 0a 20 20 20  und SELECT]..   
2f5f0 20 49 74 20 63 61 6e 6e 6f 74 20 66 6f 6c 6c 6f   It cannot follo
2f600 77 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 2d 6f 70  w a [compound-op
2f610 65 72 61 74 6f 72 5d 2e 0a 3c 2f 75 6c 3e 0a 54  erator]..</ul>.T
2f620 68 65 73 65 20 61 6e 64 20 6f 74 68 65 72 20 73  hese and other s
2f630 69 6d 69 6c 61 72 20 73 79 6e 74 61 78 20 72 65  imilar syntax re
2f640 73 74 72 69 63 74 69 6f 6e 73 20 61 72 65 20 64  strictions are d
2f650 65 73 63 72 69 62 65 64 20 69 6e 20 74 68 65 20  escribed in the 
2f660 74 65 78 74 2e 0a 0a 3c 70 3e 54 68 65 20 53 45  text...<p>The SE
2f670 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69  LECT statement i
2f680 73 20 74 68 65 20 6d 6f 73 74 20 63 6f 6d 70 6c  s the most compl
2f690 69 63 61 74 65 64 20 63 6f 6d 6d 61 6e 64 20 69  icated command i
2f6a0 6e 20 74 68 65 20 53 51 4c 20 6c 61 6e 67 75 61  n the SQL langua
2f6b0 67 65 2e 0a 54 6f 20 6d 61 6b 65 20 74 68 65 20  ge..To make the 
2f6c0 64 65 73 63 72 69 70 74 69 6f 6e 20 65 61 73 69  description easi
2f6d0 65 72 20 74 6f 20 66 6f 6c 6c 6f 77 2c 20 73 6f  er to follow, so
2f6e0 6d 65 20 6f 66 20 74 68 65 20 70 61 73 73 61 67  me of the passag
2f6f0 65 73 20 62 65 6c 6f 77 20 64 65 73 63 72 69 62  es below describ
2f700 65 0a 74 68 65 20 77 61 79 20 74 68 65 20 64 61  e.the way the da
2f710 74 61 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ta returned by a
2f720 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2f730 74 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20  t is determined 
2f740 61 73 20 61 20 73 65 72 69 65 73 20 6f 66 0a 73  as a series of.s
2f750 74 65 70 73 2e 20 49 74 20 69 73 20 69 6d 70 6f  teps. It is impo
2f760 72 74 61 6e 74 20 74 6f 20 6b 65 65 70 20 69 6e  rtant to keep in
2f770 20 6d 69 6e 64 20 74 68 61 74 20 74 68 69 73 20   mind that this 
2f780 69 73 20 70 75 72 65 6c 79 20 69 6c 6c 75 73 74  is purely illust
2f790 72 61 74 69 76 65 20 2d 0a 69 6e 20 70 72 61 63  rative -.in prac
2f7a0 74 69 63 65 20 6e 65 69 74 68 65 72 20 53 51 4c  tice neither SQL
2f7b0 69 74 65 20 6e 6f 72 20 61 6e 79 20 6f 74 68 65  ite nor any othe
2f7c0 72 20 53 51 4c 20 65 6e 67 69 6e 65 20 69 73 20  r SQL engine is 
2f7d0 72 65 71 75 69 72 65 64 20 74 6f 20 66 6f 6c 6c  required to foll
2f7e0 6f 77 20 0a 74 68 69 73 20 6f 72 20 61 6e 79 20  ow .this or any 
2f7f0 6f 74 68 65 72 20 73 70 65 63 69 66 69 63 20 70  other specific p
2f800 72 6f 63 65 73 73 2e 0a 0a 3c 74 63 6c 3e 68 64  rocess...<tcl>hd
2f810 5f 66 72 61 67 6d 65 6e 74 20 73 69 6d 70 6c 65  _fragment simple
2f820 73 65 6c 65 63 74 20 7b 73 69 6d 70 6c 65 20 53  select {simple S
2f830 45 4c 45 43 54 7d 3c 2f 74 63 6c 3e 0a 3c 68 33  ELECT}</tcl>.<h3
2f840 3e 53 69 6d 70 6c 65 20 53 65 6c 65 63 74 20 50  >Simple Select P
2f850 72 6f 63 65 73 73 69 6e 67 3c 2f 68 33 3e 0a 0a  rocessing</h3>..
2f860 3c 70 3e 54 68 65 20 63 6f 72 65 20 6f 66 20 61  <p>The core of a
2f870 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2f880 74 20 69 73 20 61 20 22 73 69 6d 70 6c 65 20 53  t is a "simple S
2f890 45 4c 45 43 54 22 20 73 68 6f 77 6e 20 62 79 20  ELECT" shown by 
2f8a0 74 68 65 0a 5b 73 65 6c 65 63 74 2d 63 6f 72 65  the.[select-core
2f8b0 5d 20 61 6e 64 20 5b 73 69 6d 70 6c 65 2d 73 65  ] and [simple-se
2f8c0 6c 65 63 74 2d 73 74 6d 74 5d 20 73 79 6e 74 61  lect-stmt] synta
2f8d0 78 20 64 69 61 67 72 61 6d 73 20 62 65 6c 6f 77  x diagrams below
2f8e0 2e 20 20 0a 49 6e 20 70 72 61 63 74 69 63 65 2c  .  .In practice,
2f8f0 20 6d 6f 73 74 20 53 45 4c 45 43 54 20 73 74 61   most SELECT sta
2f900 74 65 6d 65 6e 74 73 20 61 72 65 20 73 69 6d 70  tements are simp
2f910 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  le SELECT statem
2f920 65 6e 74 73 2e 0a 0a 3c 74 63 6c 3e 0a 52 65 63  ents...<tcl>.Rec
2f930 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
2f940 72 61 6d 20 73 69 6d 70 6c 65 2d 73 65 6c 65 63  ram simple-selec
2f950 74 2d 73 74 6d 74 20 73 65 6c 65 63 74 2d 63 6f  t-stmt select-co
2f960 72 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 47 65  re.</tcl>..<p>Ge
2f970 6e 65 72 61 74 69 6e 67 20 74 68 65 20 72 65 73  nerating the res
2f980 75 6c 74 73 20 6f 66 20 61 20 73 69 6d 70 6c 65  ults of a simple
2f990 20 53 45 4c 45 43 54 0a 73 74 61 74 65 6d 65 6e   SELECT.statemen
2f9a0 74 20 69 73 20 70 72 65 73 65 6e 74 65 64 20 61  t is presented a
2f9b0 73 20 61 20 66 6f 75 72 20 73 74 65 70 20 70 72  s a four step pr
2f9c0 6f 63 65 73 73 20 69 6e 20 74 68 65 20 64 65 73  ocess in the des
2f9d0 63 72 69 70 74 69 6f 6e 20 62 65 6c 6f 77 3a 0a  cription below:.
2f9e0 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e  .<ol>.  <li> <p>
2f9f0 5b 46 52 4f 4d 20 63 6c 61 75 73 65 5d 20 70 72  [FROM clause] pr
2fa00 6f 63 65 73 73 69 6e 67 3a 20 54 68 65 20 69 6e  ocessing: The in
2fa10 70 75 74 20 64 61 74 61 20 66 6f 72 20 74 68 65  put data for the
2fa20 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 69   simple SELECT i
2fa30 73 0a 20 20 20 20 20 20 20 64 65 74 65 72 6d 69  s.       determi
2fa40 6e 65 64 2e 20 54 68 65 20 69 6e 70 75 74 20 64  ned. The input d
2fa50 61 74 61 20 69 73 20 65 69 74 68 65 72 20 69 6d  ata is either im
2fa60 70 6c 69 63 69 74 6c 79 20 61 20 73 69 6e 67 6c  plicitly a singl
2fa70 65 20 72 6f 77 20 77 69 74 68 20 30 0a 20 20 20  e row with 0.   
2fa80 20 20 20 20 63 6f 6c 75 6d 6e 73 20 28 69 66 20      columns (if 
2fa90 74 68 65 72 65 20 69 73 20 6e 6f 20 46 52 4f 4d  there is no FROM
2faa0 20 63 6c 61 75 73 65 29 20 6f 72 20 69 73 20 64   clause) or is d
2fab0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2fac0 20 46 52 4f 4d 0a 20 20 20 20 20 20 20 63 6c 61   FROM.       cla
2fad0 75 73 65 2e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5b  use..  <li> <p>[
2fae0 57 48 45 52 45 20 63 6c 61 75 73 65 5d 20 70 72  WHERE clause] pr
2faf0 6f 63 65 73 73 69 6e 67 3a 20 54 68 65 20 69 6e  ocessing: The in
2fb00 70 75 74 20 64 61 74 61 20 69 73 20 66 69 6c 74  put data is filt
2fb10 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 57  ered using the W
2fb20 48 45 52 45 0a 20 20 20 20 20 20 20 63 6c 61 75  HERE.       clau
2fb30 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2e 20 20  se expression.  
2fb40 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5b 47 52 4f 55  .  <li> <p>[GROU
2fb50 50 20 42 59 7c 47 52 4f 55 50 20 42 59 2c 20 48  P BY|GROUP BY, H
2fb60 41 56 49 4e 47 20 61 6e 64 20 72 65 73 75 6c 74  AVING and result
2fb70 2d 63 6f 6c 75 6d 6e 20 65 78 70 72 65 73 73 69  -column expressi
2fb80 6f 6e 5d 20 70 72 6f 63 65 73 73 69 6e 67 3a 20  on] processing: 
2fb90 0a 20 20 20 20 20 20 20 54 68 65 20 73 65 74 20  .       The set 
2fba0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 69  of result rows i
2fbb0 73 20 63 6f 6d 70 75 74 65 64 20 62 79 20 61 67  s computed by ag
2fbc0 67 72 65 67 61 74 69 6e 67 20 74 68 65 20 64 61  gregating the da
2fbd0 74 61 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 0a  ta according to.
2fbe0 20 20 20 20 20 20 20 61 6e 79 20 47 52 4f 55 50         any GROUP
2fbf0 20 42 59 20 63 6c 61 75 73 65 20 61 6e 64 20 63   BY clause and c
2fc00 61 6c 63 75 6c 61 74 69 6e 67 20 74 68 65 20 72  alculating the r
2fc10 65 73 75 6c 74 2d 73 65 74 20 65 78 70 72 65 73  esult-set expres
2fc20 73 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 20 20  sions for the.  
2fc30 20 20 20 20 20 72 6f 77 73 20 6f 66 20 74 68 65       rows of the
2fc40 20 66 69 6c 74 65 72 65 64 20 69 6e 70 75 74 20   filtered input 
2fc50 64 61 74 61 73 65 74 2e 20 20 0a 20 20 3c 6c 69  dataset.  .  <li
2fc60 3e 20 3c 70 3e 5b 44 49 53 54 49 4e 43 54 7c 44  > <p>[DISTINCT|D
2fc70 49 53 54 49 4e 43 54 2f 41 4c 4c 20 6b 65 79 77  ISTINCT/ALL keyw
2fc80 6f 72 64 5d 20 70 72 6f 63 65 73 73 69 6e 67 3a  ord] processing:
2fc90 20 49 66 20 74 68 65 20 71 75 65 72 79 20 69 73   If the query is
2fca0 20 61 20 22 53 45 4c 45 43 54 0a 20 20 20 20 20   a "SELECT.     
2fcb0 20 20 44 49 53 54 49 4e 43 54 22 20 71 75 65 72    DISTINCT" quer
2fcc0 79 2c 20 64 75 70 6c 69 63 61 74 65 20 72 6f 77  y, duplicate row
2fcd0 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20 66 72  s are removed fr
2fce0 6f 6d 20 74 68 65 20 73 65 74 20 6f 66 20 72 65  om the set of re
2fcf0 73 75 6c 74 20 72 6f 77 73 2e 0a 3c 2f 6f 6c 3e  sult rows..</ol>
2fd00 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20 74  ..<p>There are t
2fd10 77 6f 20 74 79 70 65 73 20 6f 66 20 73 69 6d 70  wo types of simp
2fd20 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  le SELECT statem
2fd30 65 6e 74 20 2d 20 61 67 67 72 65 67 61 74 65 20  ent - aggregate 
2fd40 61 6e 64 20 0a 6e 6f 6e 2d 61 67 67 72 65 67 61  and .non-aggrega
2fd50 74 65 20 71 75 65 72 69 65 73 2e 20 5e 41 20 73  te queries. ^A s
2fd60 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 73 74 61  imple SELECT sta
2fd70 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 61 67 67  tement is an agg
2fd80 72 65 67 61 74 65 20 71 75 65 72 79 20 69 66 0a  regate query if.
2fd90 69 74 20 63 6f 6e 74 61 69 6e 73 20 65 69 74 68  it contains eith
2fda0 65 72 20 61 20 47 52 4f 55 50 20 42 59 20 63 6c  er a GROUP BY cl
2fdb0 61 75 73 65 20 6f 72 20 6f 6e 65 20 6f 72 20 6d  ause or one or m
2fdc0 6f 72 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ore aggregate fu
2fdd0 6e 63 74 69 6f 6e 73 0a 69 6e 20 74 68 65 20 72  nctions.in the r
2fde0 65 73 75 6c 74 2d 73 65 74 2e 20 5e 4f 74 68 65  esult-set. ^Othe
2fdf0 72 77 69 73 65 2c 20 69 66 20 61 20 73 69 6d 70  rwise, if a simp
2fe00 6c 65 20 53 45 4c 45 43 54 20 63 6f 6e 74 61 69  le SELECT contai
2fe10 6e 73 20 6e 6f 20 61 67 67 72 65 67 61 74 65 0a  ns no aggregate.
2fe20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 20 47  functions or a G
2fe30 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2c 20  ROUP BY clause, 
2fe40 69 74 20 69 73 20 61 20 6e 6f 6e 2d 61 67 67 72  it is a non-aggr
2fe50 65 67 61 74 65 20 71 75 65 72 79 2e 0a 0a 3c 70  egate query...<p
2fe60 3e 3c 62 3e 31 2e 20 44 65 74 65 72 6d 69 6e 61  ><b>1. Determina
2fe70 74 69 6f 6e 20 6f 66 20 69 6e 70 75 74 20 64 61  tion of input da
2fe80 74 61 20 28 46 52 4f 4d 20 63 6c 61 75 73 65 20  ta (FROM clause 
2fe90 70 72 6f 63 65 73 73 69 6e 67 29 2e 3c 2f 62 3e  processing).</b>
2fea0 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
2feb0 74 20 66 72 6f 6d 63 6c 61 75 73 65 3c 2f 74 63  t fromclause</tc
2fec0 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f  l>.<tcl>hd_keywo
2fed0 72 64 73 20 7b 46 52 4f 4d 20 63 6c 61 75 73 65  rds {FROM clause
2fee0 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68 65 20  }</tcl>..<p>The 
2fef0 69 6e 70 75 74 20 64 61 74 61 20 75 73 65 64 20  input data used 
2ff00 62 79 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45  by a simple SELE
2ff10 43 54 20 71 75 65 72 79 20 69 73 20 61 20 73 65  CT query is a se
2ff20 74 20 6f 66 20 3c 69 3e 4e 3c 2f 69 3e 20 72 6f  t of <i>N</i> ro
2ff30 77 73 20 0a 65 61 63 68 20 3c 69 3e 4d 3c 2f 69  ws .each <i>M</i
2ff40 3e 20 63 6f 6c 75 6d 6e 73 20 77 69 64 65 2e 0a  > columns wide..
2ff50 0a 3c 70 3e 5e 28 49 66 20 74 68 65 20 46 52 4f  .<p>^(If the FRO
2ff60 4d 20 63 6c 61 75 73 65 20 69 73 20 6f 6d 69 74  M clause is omit
2ff70 74 65 64 20 66 72 6f 6d 20 61 20 73 69 6d 70 6c  ted from a simpl
2ff80 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
2ff90 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 0a 69 6e  nt, then the .in
2ffa0 70 75 74 20 64 61 74 61 20 69 73 20 69 6d 70 6c  put data is impl
2ffb0 69 63 69 74 6c 79 20 61 20 73 69 6e 67 6c 65 20  icitly a single 
2ffc0 72 6f 77 20 7a 65 72 6f 20 63 6f 6c 75 6d 6e 73  row zero columns
2ffd0 20 77 69 64 65 29 5e 20 28 69 2e 65 2e 20 3c 69   wide)^ (i.e. <i
2ffe0 3e 4e 3c 2f 69 3e 3d 31 20 61 6e 64 0a 3c 69 3e  >N</i>=1 and.<i>
2fff0 4d 3c 2f 69 3e 3d 30 29 2e 0a 0a 3c 70 3e 49 66  M</i>=0)...<p>If
30000 20 61 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 69   a FROM clause i
30010 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
30020 20 64 61 74 61 20 6f 6e 20 77 68 69 63 68 20 61   data on which a
30030 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 71   simple SELECT q
30040 75 65 72 79 0a 6f 70 65 72 61 74 65 73 20 63 6f  uery.operates co
30050 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 6f 6e 65  mes from the one
30060 20 6f 72 20 6d 6f 72 65 20 74 61 62 6c 65 73 20   or more tables 
30070 6f 72 20 73 75 62 71 75 65 72 69 65 73 20 28 53  or subqueries (S
30080 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
30090 0a 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 29  .in parentheses)
300a0 20 73 70 65 63 69 66 69 65 64 20 66 6f 6c 6c 6f   specified follo
300b0 77 69 6e 67 20 74 68 65 20 46 52 4f 4d 20 6b 65  wing the FROM ke
300c0 79 77 6f 72 64 2e 20 5e 41 20 73 75 62 71 75 65  yword. ^A subque
300d0 72 79 20 73 70 65 63 69 66 69 65 64 0a 69 6e 20  ry specified.in 
300e0 74 68 65 20 3c 79 79 74 65 72 6d 3e 74 61 62 6c  the <yyterm>tabl
300f0 65 2d 6f 72 2d 73 75 62 71 75 65 72 79 3c 2f 79  e-or-subquery</y
30100 79 74 65 72 6d 3e 20 66 6f 6c 6c 6f 77 69 6e 67  yterm> following
30110 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65   the FROM clause
30120 20 69 6e 20 61 20 0a 73 69 6d 70 6c 65 20 53 45   in a .simple SE
30130 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69  LECT statement i
30140 73 0a 68 61 6e 64 6c 65 64 20 61 73 20 69 66 20  s.handled as if 
30150 69 74 20 77 61 73 20 61 20 74 61 62 6c 65 20 63  it was a table c
30160 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
30170 74 61 20 72 65 74 75 72 6e 65 64 20 62 79 20 65  ta returned by e
30180 78 65 63 75 74 69 6e 67 20 74 68 65 0a 73 75 62  xecuting the.sub
30190 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 2e  query statement.
301a0 20 5e 45 61 63 68 20 63 6f 6c 75 6d 6e 20 6f 66   ^Each column of
301b0 20 74 68 65 20 73 75 62 71 75 65 72 79 20 68 61   the subquery ha
301c0 73 20 74 68 65 0a 5b 63 6f 6c 6c 61 74 69 6f 6e  s the.[collation
301d0 7c 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65  |collation seque
301e0 6e 63 65 5d 20 61 6e 64 20 5b 61 66 66 69 6e 69  nce] and [affini
301f0 74 79 5d 20 6f 66 20 74 68 65 20 63 6f 72 72 65  ty] of the corre
30200 73 70 6f 6e 64 69 6e 67 20 65 78 70 72 65 73 73  sponding express
30210 69 6f 6e 0a 69 6e 20 74 68 65 20 73 75 62 71 75  ion.in the subqu
30220 65 72 79 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a  ery statement...
30230 3c 70 3e 5e 49 66 20 74 68 65 72 65 20 69 73 20  <p>^If there is 
30240 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 74 61  only a single ta
30250 62 6c 65 20 6f 72 20 73 75 62 71 75 65 72 79 20  ble or subquery 
30260 69 6e 20 74 68 65 20 46 52 4f 4d 0a 63 6c 61 75  in the FROM.clau
30270 73 65 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 70  se, then the inp
30280 75 74 20 64 61 74 61 20 75 73 65 64 20 62 79 20  ut data used by 
30290 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
302a0 6d 65 6e 74 20 69 73 20 74 68 65 20 63 6f 6e 74  ment is the cont
302b0 65 6e 74 73 20 6f 66 20 74 68 65 0a 6e 61 6d 65  ents of the.name
302c0 64 20 74 61 62 6c 65 2e 20 5e 49 66 20 74 68 65  d table. ^If the
302d0 72 65 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  re is more than 
302e0 6f 6e 65 20 74 61 62 6c 65 20 6f 72 20 73 75 62  one table or sub
302f0 71 75 65 72 79 20 69 6e 20 46 52 4f 4d 20 63 6c  query in FROM cl
30300 61 75 73 65 0a 74 68 65 6e 20 74 68 65 20 63 6f  ause.then the co
30310 6e 74 65 6e 74 73 20 6f 66 20 61 6c 6c 20 74 61  ntents of all ta
30320 62 6c 65 73 20 61 6e 64 2f 6f 72 20 73 75 62 71  bles and/or subq
30330 75 65 72 69 65 73 0a 61 72 65 20 6a 6f 69 6e 65  ueries.are joine
30340 64 20 69 6e 74 6f 20 61 20 73 69 6e 67 6c 65 20  d into a single 
30350 64 61 74 61 73 65 74 20 66 6f 72 20 74 68 65 20  dataset for the 
30360 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 73 74  simple SELECT st
30370 61 74 65 6d 65 6e 74 20 74 6f 20 6f 70 65 72 61  atement to opera
30380 74 65 20 6f 6e 2e 0a 45 78 61 63 74 6c 79 20 68  te on..Exactly h
30390 6f 77 20 74 68 65 20 64 61 74 61 20 69 73 20 63  ow the data is c
303a0 6f 6d 62 69 6e 65 64 20 64 65 70 65 6e 64 73 20  ombined depends 
303b0 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69 63 20  on the specific 
303c0 5b 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 5d 20  [join-operator] 
303d0 61 6e 64 0a 5b 6a 6f 69 6e 2d 63 6f 6e 73 74 72  and.[join-constr
303e0 61 69 6e 74 5d 20 75 73 65 64 20 74 6f 20 63 6f  aint] used to co
303f0 6e 6e 65 63 74 20 74 68 65 20 74 61 62 6c 65 73  nnect the tables
30400 20 6f 72 20 73 75 62 71 75 65 72 69 65 73 20 74   or subqueries t
30410 6f 67 65 74 68 65 72 2e 0a 0a 3c 70 3e 41 6c 6c  ogether...<p>All
30420 20 6a 6f 69 6e 73 20 69 6e 20 53 51 4c 69 74 65   joins in SQLite
30430 20 61 72 65 20 62 61 73 65 64 20 6f 6e 20 74 68   are based on th
30440 65 20 63 61 72 74 65 73 69 61 6e 20 70 72 6f 64  e cartesian prod
30450 75 63 74 20 6f 66 20 74 68 65 20 6c 65 66 74 20  uct of the left 
30460 61 6e 64 0a 72 69 67 68 74 2d 68 61 6e 64 20 64  and.right-hand d
30470 61 74 61 73 65 74 73 2e 20 5e 54 68 65 20 63 6f  atasets. ^The co
30480 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20 63 61 72  lumns of the car
30490 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20 64  tesian product d
304a0 61 74 61 73 65 74 20 61 72 65 2c 20 69 6e 20 0a  ataset are, in .
304b0 6f 72 64 65 72 2c 20 61 6c 6c 20 74 68 65 20 63  order, all the c
304c0 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20 6c 65  olumns of the le
304d0 66 74 2d 68 61 6e 64 20 64 61 74 61 73 65 74 20  ft-hand dataset 
304e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6c 6c 20  followed by all 
304f0 74 68 65 20 63 6f 6c 75 6d 6e 73 0a 6f 66 20 74  the columns.of t
30500 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 64 61  he right-hand da
30510 74 61 73 65 74 2e 20 5e 54 68 65 72 65 20 69 73  taset. ^There is
30520 20 61 20 72 6f 77 20 69 6e 20 74 68 65 20 63 61   a row in the ca
30530 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20  rtesian product 
30540 64 61 74 61 73 65 74 0a 66 6f 72 6d 65 64 20 62  dataset.formed b
30550 79 20 63 6f 6d 62 69 6e 69 6e 67 20 65 61 63 68  y combining each
30560 20 75 6e 69 71 75 65 20 63 6f 6d 62 69 6e 61 74   unique combinat
30570 69 6f 6e 20 6f 66 20 61 20 72 6f 77 20 66 72 6f  ion of a row fro
30580 6d 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  m the left-hand 
30590 0a 61 6e 64 20 72 69 67 68 74 2d 68 61 6e 64 20  .and right-hand 
305a0 64 61 74 61 73 65 74 73 2e 20 5e 28 49 6e 20 6f  datasets. ^(In o
305b0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 74  ther words, if t
305c0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 64 61 74  he left-hand dat
305d0 61 73 65 74 20 63 6f 6e 73 69 73 74 73 20 6f 66  aset consists of
305e0 0a 3c 69 3e 4e 3c 73 75 62 3e 3c 73 6d 61 6c 6c  .<i>N<sub><small
305f0 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73  >left</small></s
30600 75 62 3e 3c 2f 69 3e 20 72 6f 77 73 20 6f 66 20  ub></i> rows of 
30610 0a 3c 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61 6c 6c  .<i>M<sub><small
30620 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73  >left</small></s
30630 75 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d 6e 73 2c  ub></i> columns,
30640 20 61 6e 64 20 74 68 65 20 72 69 67 68 74 2d 68   and the right-h
30650 61 6e 64 20 64 61 74 61 73 65 74 20 6f 66 0a 3c  and dataset of.<
30660 69 3e 4e 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 72  i>N<sub><small>r
30670 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75  ight</small></su
30680 62 3e 3c 2f 69 3e 20 72 6f 77 73 20 6f 66 0a 3c  b></i> rows of.<
30690 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 72  i>M<sub><small>r
306a0 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75  ight</small></su
306b0 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d 6e 73 2c 20  b></i> columns, 
306c0 74 68 65 6e 20 74 68 65 20 63 61 72 74 65 73 69  then the cartesi
306d0 61 6e 20 70 72 6f 64 75 63 74 20 69 73 20 61 0a  an product is a.
306e0 64 61 74 61 73 65 74 20 6f 66 20 0a 3c 69 3e 4e  dataset of .<i>N
306f0 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 6c 65 66 74  <sub><small>left
30700 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 26 74  </small></sub>&t
30710 69 6d 65 73 3b 4e 3c 73 75 62 3e 3c 73 6d 61 6c  imes;N<sub><smal
30720 6c 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c  l>right</small><
30730 2f 73 75 62 3e 3c 2f 69 3e 0a 72 6f 77 73 2c 20  /sub></i>.rows, 
30740 65 61 63 68 20 63 6f 6e 74 61 69 6e 69 6e 67 20  each containing 
30750 0a 3c 69 3e 4d 3c 73 75 62 3e 3c 73 6d 61 6c 6c  .<i>M<sub><small
30760 3e 6c 65 66 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73  >left</small></s
30770 75 62 3e 2b 4d 3c 73 75 62 3e 3c 73 6d 61 6c 6c  ub>+M<sub><small
30780 3e 72 69 67 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f  >right</small></
30790 73 75 62 3e 3c 2f 69 3e 20 63 6f 6c 75 6d 6e 73  sub></i> columns
307a0 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20  .)^..<p>^If the 
307b0 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20 69 73  join-operator is
307c0 20 22 43 52 4f 53 53 20 4a 4f 49 4e 22 2c 20 22   "CROSS JOIN", "
307d0 49 4e 4e 45 52 20 4a 4f 49 4e 22 2c 20 22 4a 4f  INNER JOIN", "JO
307e0 49 4e 22 20 6f 72 20 61 20 63 6f 6d 6d 61 0a 28  IN" or a comma.(
307f0 22 2c 22 29 20 61 6e 64 20 74 68 65 72 65 20 69  ",") and there i
30800 73 20 6e 6f 20 4f 4e 20 6f 72 20 55 53 49 4e 47  s no ON or USING
30810 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20 74 68   clause, then th
30820 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
30830 6a 6f 69 6e 20 69 73 0a 73 69 6d 70 6c 79 20 74  join is.simply t
30840 68 65 20 63 61 72 74 65 73 69 61 6e 20 70 72 6f  he cartesian pro
30850 64 75 63 74 20 6f 66 20 74 68 65 20 6c 65 66 74  duct of the left
30860 20 61 6e 64 20 72 69 67 68 74 2d 68 61 6e 64 20   and right-hand 
30870 64 61 74 61 73 65 74 73 2e 20 0a 49 66 20 6a 6f  datasets. .If jo
30880 69 6e 2d 6f 70 65 72 61 74 6f 72 20 64 6f 65 73  in-operator does
30890 20 68 61 76 65 20 4f 4e 20 6f 72 20 55 53 49 4e   have ON or USIN
308a0 47 20 63 6c 61 75 73 65 73 2c 20 74 68 6f 73 65  G clauses, those
308b0 20 61 72 65 20 68 61 6e 64 6c 65 64 20 61 63 63   are handled acc
308c0 6f 72 64 69 6e 67 20 74 6f 0a 74 68 65 20 66 6f  ording to.the fo
308d0 6c 6c 6f 77 69 6e 67 20 62 75 6c 6c 65 74 20 70  llowing bullet p
308e0 6f 69 6e 74 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c  oints:..<ul>.  <
308f0 6c 69 3e 20 3c 70 3e 5e 28 49 66 20 74 68 65 72  li> <p>^(If ther
30900 65 20 69 73 20 61 6e 20 4f 4e 20 63 6c 61 75 73  e is an ON claus
30910 65 20 74 68 65 6e 20 74 68 65 20 4f 4e 20 65 78  e then the ON ex
30920 70 72 65 73 73 69 6f 6e 20 69 73 0a 20 20 20 20  pression is.    
30930 20 20 20 65 76 61 6c 75 61 74 65 64 20 66 6f 72     evaluated for
30940 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
30950 20 63 61 72 74 65 73 69 61 6e 20 70 72 6f 64 75   cartesian produ
30960 63 74 20 61 73 20 61 20 0a 20 20 20 20 20 20 20  ct as a .       
30970 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73  [boolean express
30980 69 6f 6e 5d 2e 20 4f 6e 6c 79 20 72 6f 77 73 20  ion]. Only rows 
30990 66 6f 72 20 77 68 69 63 68 20 74 68 65 20 65 78  for which the ex
309a0 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74  pression evaluat
309b0 65 73 20 74 6f 20 0a 20 20 20 20 20 20 20 74 72  es to .       tr
309c0 75 65 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  ue are included 
309d0 66 72 6f 6d 20 74 68 65 20 64 61 74 61 73 65 74  from the dataset
309e0 2e 29 5e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5e  .)^..  <li> <p>^
309f0 49 66 20 74 68 65 72 65 20 69 73 20 61 20 55 53  If there is a US
30a00 49 4e 47 20 63 6c 61 75 73 65 0a 20 20 20 20 20  ING clause.     
30a10 20 20 74 68 65 6e 20 65 61 63 68 20 6f 66 20 74    then each of t
30a20 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  he column names 
30a30 73 70 65 63 69 66 69 65 64 20 6d 75 73 74 20 65  specified must e
30a40 78 69 73 74 20 69 6e 20 74 68 65 20 64 61 74 61  xist in the data
30a50 73 65 74 73 20 74 6f 20 0a 20 20 20 20 20 20 20  sets to .       
30a60 62 6f 74 68 20 74 68 65 20 6c 65 66 74 20 61 6e  both the left an
30a70 64 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 6a  d right of the j
30a80 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 2e 20 5e 28  oin-operator. ^(
30a90 46 6f 72 20 65 61 63 68 20 70 61 69 72 20 6f 66  For each pair of
30aa0 20 6e 61 6d 65 64 0a 20 20 20 20 20 20 20 63 6f   named.       co
30ab0 6c 75 6d 6e 73 2c 20 74 68 65 20 65 78 70 72 65  lumns, the expre
30ac0 73 73 69 6f 6e 20 22 6c 68 73 2e 58 20 3d 20 72  ssion "lhs.X = r
30ad0 68 73 2e 58 22 20 69 73 20 65 76 61 6c 75 61 74  hs.X" is evaluat
30ae0 65 64 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ed for each row 
30af0 6f 66 0a 20 20 20 20 20 20 20 74 68 65 20 63 61  of.       the ca
30b00 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20  rtesian product 
30b10 61 73 20 61 20 5b 62 6f 6f 6c 65 61 6e 20 65 78  as a [boolean ex
30b20 70 72 65 73 73 69 6f 6e 5d 2e 20 4f 6e 6c 79 20  pression]. Only 
30b30 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68 0a 20  rows for which. 
30b40 20 20 20 20 20 20 61 6c 6c 20 73 75 63 68 20 65        all such e
30b50 78 70 72 65 73 73 69 6f 6e 73 20 65 76 61 6c 75  xpressions evalu
30b60 61 74 65 73 20 74 6f 20 74 72 75 65 20 61 72 65  ates to true are
30b70 20 69 6e 63 6c 75 64 65 64 20 66 72 6f 6d 20 74   included from t
30b80 68 65 0a 20 20 20 20 20 20 20 72 65 73 75 6c 74  he.       result
30b90 20 73 65 74 2e 29 5e 20 5e 57 68 65 6e 20 63 6f   set.)^ ^When co
30ba0 6d 70 61 72 69 6e 67 20 76 61 6c 75 65 73 20 61  mparing values a
30bb0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  s a result of a 
30bc0 55 53 49 4e 47 20 63 6c 61 75 73 65 2c 20 74 68  USING clause, th
30bd0 65 0a 20 20 20 20 20 20 20 6e 6f 72 6d 61 6c 20  e.       normal 
30be0 72 75 6c 65 73 20 66 6f 72 20 68 61 6e 64 6c 69  rules for handli
30bf0 6e 67 20 61 66 66 69 6e 69 74 69 65 73 2c 20 63  ng affinities, c
30c00 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
30c10 65 73 20 61 6e 64 20 4e 55 4c 4c 0a 20 20 20 20  es and NULL.    
30c20 20 20 20 76 61 6c 75 65 73 20 69 6e 20 63 6f 6d     values in com
30c30 70 61 72 69 73 6f 6e 73 20 61 70 70 6c 79 2e 20  parisons apply. 
30c40 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  ^The column from
30c50 20 74 68 65 20 64 61 74 61 73 65 74 20 6f 6e 20   the dataset on 
30c60 74 68 65 0a 20 20 20 20 20 20 20 6c 65 66 74 2d  the.       left-
30c70 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
30c80 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20 69   join-operator i
30c90 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  s considered to 
30ca0 62 65 20 6f 6e 20 74 68 65 20 6c 65 66 74 2d 68  be on the left-h
30cb0 61 6e 64 0a 20 20 20 20 20 20 20 73 69 64 65 20  and.       side 
30cc0 6f 66 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  of the compariso
30cd0 6e 20 6f 70 65 72 61 74 6f 72 20 28 3d 29 20 66  n operator (=) f
30ce0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
30cf0 6f 66 20 63 6f 6c 6c 61 74 69 6f 6e 20 0a 20 20  of collation .  
30d00 20 20 20 20 20 73 65 71 75 65 6e 63 65 20 61 6e       sequence an
30d10 64 20 61 66 66 69 6e 69 74 79 20 70 72 65 63 65  d affinity prece
30d20 64 65 6e 63 65 2e 0a 0a 20 20 20 20 20 20 20 3c  dence...       <
30d30 70 3e 5e 46 6f 72 20 65 61 63 68 20 70 61 69 72  p>^For each pair
30d40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 64 65 6e   of columns iden
30d50 74 69 66 69 65 64 20 62 79 20 61 20 55 53 49 4e  tified by a USIN
30d60 47 20 63 6c 61 75 73 65 2c 20 74 68 65 20 63 6f  G clause, the co
30d70 6c 75 6d 6e 0a 20 20 20 20 20 20 20 66 72 6f 6d  lumn.       from
30d80 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
30d90 64 61 74 61 73 65 74 20 69 73 20 6f 6d 69 74 74  dataset is omitt
30da0 65 64 20 66 72 6f 6d 20 74 68 65 20 6a 6f 69 6e  ed from the join
30db0 65 64 20 64 61 74 61 73 65 74 2e 20 5e 54 68 69  ed dataset. ^Thi
30dc0 73 20 0a 20 20 20 20 20 20 20 69 73 20 74 68 65  s .       is the
30dd0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30de0 20 62 65 74 77 65 65 6e 20 61 20 55 53 49 4e 47   between a USING
30df0 20 63 6c 61 75 73 65 20 61 6e 64 20 69 74 73 20   clause and its 
30e00 65 71 75 69 76 61 6c 65 6e 74 20 4f 4e 0a 20 20  equivalent ON.  
30e10 20 20 20 20 20 63 6f 6e 73 74 72 61 69 6e 74 2e       constraint.
30e20 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5e 28 49 66  ..  <li> <p>^(If
30e30 20 74 68 65 20 4e 41 54 55 52 41 4c 20 6b 65 79   the NATURAL key
30e40 77 6f 72 64 20 69 73 20 69 6e 20 74 68 65 20 6a  word is in the j
30e50 6f 69 6e 2d 6f 70 65 72 61 74 6f 72 20 74 68 65  oin-operator the
30e60 6e 20 61 6e 0a 20 20 20 20 20 20 20 69 6d 70 6c  n an.       impl
30e70 69 63 69 74 20 55 53 49 4e 47 20 63 6c 61 75 73  icit USING claus
30e80 65 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  e is added to th
30e90 65 20 6a 6f 69 6e 2d 63 6f 6e 73 74 72 61 69 6e  e join-constrain
30ea0 74 73 2e 20 54 68 65 20 69 6d 70 6c 69 63 69 74  ts. The implicit
30eb0 0a 20 20 20 20 20 20 20 55 53 49 4e 47 20 63 6c  .       USING cl
30ec0 61 75 73 65 20 63 6f 6e 74 61 69 6e 73 20 65 61  ause contains ea
30ed0 63 68 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ch of the column
30ee0 20 6e 61 6d 65 73 20 74 68 61 74 20 61 70 70 65   names that appe
30ef0 61 72 20 69 6e 20 62 6f 74 68 0a 20 20 20 20 20  ar in both.     
30f00 20 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72    the left and r
30f10 69 67 68 74 2d 68 61 6e 64 20 69 6e 70 75 74 20  ight-hand input 
30f20 64 61 74 61 73 65 74 73 2e 29 5e 20 5e 49 66 20  datasets.)^ ^If 
30f30 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72 69 67  the left and rig
30f40 68 74 2d 68 61 6e 64 0a 20 20 20 20 20 20 20 69  ht-hand.       i
30f50 6e 70 75 74 20 64 61 74 61 73 65 74 73 20 66 65  nput datasets fe
30f60 61 74 75 72 65 20 6e 6f 20 63 6f 6d 6d 6f 6e 20  ature no common 
30f70 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 2c 20 74 68  column names, th
30f80 65 6e 20 74 68 65 20 4e 41 54 55 52 41 4c 20 6b  en the NATURAL k
30f90 65 79 77 6f 72 64 0a 20 20 20 20 20 20 20 68 61  eyword.       ha
30fa0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 74  s no effect on t
30fb0 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68  he results of th
30fc0 65 20 6a 6f 69 6e 2e 20 5e 41 20 55 53 49 4e 47  e join. ^A USING
30fd0 20 6f 72 20 4f 4e 20 63 6c 61 75 73 65 20 6d 61   or ON clause ma
30fe0 79 0a 20 20 20 20 20 20 20 6e 6f 74 20 62 65 20  y.       not be 
30ff0 61 64 64 65 64 20 74 6f 20 61 20 6a 6f 69 6e 20  added to a join 
31000 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
31010 68 65 20 4e 41 54 55 52 41 4c 20 6b 65 79 77 6f  he NATURAL keywo
31020 72 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5e  rd...  <li> <p>^
31030 28 49 66 20 74 68 65 20 6a 6f 69 6e 2d 6f 70 65  (If the join-ope
31040 72 61 74 6f 72 20 69 73 20 61 20 22 4c 45 46 54  rator is a "LEFT
31050 20 4a 4f 49 4e 22 20 6f 72 20 22 4c 45 46 54 20   JOIN" or "LEFT 
31060 4f 55 54 45 52 20 4a 4f 49 4e 22 2c 20 74 68 65  OUTER JOIN", the
31070 6e 0a 20 20 20 20 20 20 20 61 66 74 65 72 0a 20  n.       after. 
31080 20 20 20 20 20 20 74 68 65 20 4f 4e 20 6f 72 20        the ON or 
31090 55 53 49 4e 47 20 66 69 6c 74 65 72 69 6e 67 20  USING filtering 
310a0 63 6c 61 75 73 65 73 20 68 61 76 65 20 62 65 65  clauses have bee
310b0 6e 20 61 70 70 6c 69 65 64 2c 20 61 6e 20 65 78  n applied, an ex
310c0 74 72 61 20 72 6f 77 20 69 73 20 0a 20 20 20 20  tra row is .    
310d0 20 20 20 61 64 64 65 64 20 74 6f 20 74 68 65 20     added to the 
310e0 6f 75 74 70 75 74 20 66 6f 72 20 65 61 63 68 20  output for each 
310f0 72 6f 77 20 69 6e 20 74 68 65 20 6f 72 69 67 69  row in the origi
31100 6e 61 6c 20 6c 65 66 74 2d 68 61 6e 64 20 69 6e  nal left-hand in
31110 70 75 74 20 0a 20 20 20 20 20 20 20 64 61 74 61  put .       data
31120 73 65 74 20 74 68 61 74 20 63 6f 72 72 65 73 70  set that corresp
31130 6f 6e 64 73 20 74 6f 20 6e 6f 20 72 6f 77 73 20  onds to no rows 
31140 61 74 20 61 6c 6c 20 69 6e 20 74 68 65 20 63 6f  at all in the co
31150 6d 70 6f 73 69 74 65 0a 20 20 20 20 20 20 20 64  mposite.       d
31160 61 74 61 73 65 74 20 28 69 66 20 61 6e 79 29 2e  ataset (if any).
31170 29 5e 20 5e 54 68 65 20 61 64 64 65 64 20 72 6f  )^ ^The added ro
31180 77 73 20 63 6f 6e 74 61 69 6e 20 4e 55 4c 4c 20  ws contain NULL 
31190 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 6f  values in the co
311a0 6c 75 6d 6e 73 0a 20 20 20 20 20 20 20 74 68 61  lumns.       tha
311b0 74 20 77 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79  t would normally
311c0 20 63 6f 6e 74 61 69 6e 20 76 61 6c 75 65 73 20   contain values 
311d0 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
311e0 72 69 67 68 74 2d 68 61 6e 64 20 69 6e 70 75 74  right-hand input
311f0 0a 20 20 20 20 20 20 20 64 61 74 61 73 65 74 2e  .       dataset.
31200 20 20 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e 28 57    .</ul>..<p>^(W
31210 68 65 6e 20 6d 6f 72 65 20 74 68 61 6e 20 74 77  hen more than tw
31220 6f 20 74 61 62 6c 65 73 20 61 72 65 20 6a 6f 69  o tables are joi
31230 6e 65 64 20 74 6f 67 65 74 68 65 72 20 61 73 20  ned together as 
31240 70 61 72 74 20 6f 66 20 61 20 46 52 4f 4d 20 63  part of a FROM c
31250 6c 61 75 73 65 2c 0a 74 68 65 20 6a 6f 69 6e 20  lause,.the join 
31260 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 70  operations are p
31270 72 6f 63 65 73 73 65 64 20 69 6e 20 6f 72 64 65  rocessed in orde
31280 72 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72  r from left to r
31290 69 67 68 74 2e 20 49 6e 20 6f 74 68 65 72 20 0a  ight. In other .
312a0 77 6f 72 64 73 2c 20 74 68 65 20 46 52 4f 4d 20  words, the FROM 
312b0 63 6c 61 75 73 65 20 28 41 20 6a 6f 69 6e 2d 6f  clause (A join-o
312c0 70 2d 31 20 42 20 6a 6f 69 6e 2d 6f 70 2d 32 20  p-1 B join-op-2 
312d0 43 29 20 69 73 20 63 6f 6d 70 75 74 65 64 20 61  C) is computed a
312e0 73 20 0a 28 28 41 20 6a 6f 69 6e 2d 6f 70 2d 31  s .((A join-op-1
312f0 20 42 29 20 6a 6f 69 6e 2d 6f 70 2d 32 20 43 29   B) join-op-2 C)
31300 2e 29 5e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  .)^..<tcl>hd_fra
31310 67 6d 65 6e 74 20 63 72 6f 73 73 6a 6f 69 6e 20  gment crossjoin 
31320 7b 74 72 65 61 74 73 20 74 68 65 20 43 52 4f 53  {treats the CROS
31330 53 20 4a 4f 49 4e 20 6f 70 65 72 61 74 6f 72 20  S JOIN operator 
31340 73 70 65 63 69 61 6c 6c 79 7d 3c 2f 74 63 6c 3e  specially}</tcl>
31350 0a 3c 70 3e 3c 62 3e 53 69 64 65 20 6e 6f 74 65  .<p><b>Side note
31360 3a 20 53 70 65 63 69 61 6c 20 68 61 6e 64 6c 69  : Special handli
31370 6e 67 20 6f 66 20 43 52 4f 53 53 20 4a 4f 49 4e  ng of CROSS JOIN
31380 2e 3c 2f 62 3e 0a 5e 54 68 65 72 65 20 69 73 20  .</b>.^There is 
31390 6e 6f 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  no difference be
313a0 74 77 65 65 6e 20 74 68 65 20 22 49 4e 4e 45 52  tween the "INNER
313b0 20 4a 4f 49 4e 22 2c 20 22 4a 4f 49 4e 22 20 61   JOIN", "JOIN" a
313c0 6e 64 20 22 2c 22 20 6a 6f 69 6e 0a 6f 70 65 72  nd "," join.oper
313d0 61 74 6f 72 73 2e 20 54 68 65 79 20 61 72 65 20  ators. They are 
313e0 63 6f 6d 70 6c 65 74 65 6c 79 20 69 6e 74 65 72  completely inter
313f0 63 68 61 6e 67 65 61 62 6c 65 20 69 6e 20 53 51  changeable in SQ
31400 4c 69 74 65 2e 0a 5e 28 54 68 65 20 22 43 52 4f  Lite..^(The "CRO
31410 53 53 20 4a 4f 49 4e 22 20 6a 6f 69 6e 20 6f 70  SS JOIN" join op
31420 65 72 61 74 6f 72 20 70 72 6f 64 75 63 65 73 20  erator produces 
31430 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
31440 61 73 20 74 68 65 20 0a 22 49 4e 4e 45 52 20 4a  as the ."INNER J
31450 4f 49 4e 22 2c 20 22 4a 4f 49 4e 22 20 61 6e 64  OIN", "JOIN" and
31460 20 22 2c 22 20 6f 70 65 72 61 74 6f 72 73 29 5e   "," operators)^
31470 2c 20 62 75 74 20 69 73 20 0a 5b 43 52 4f 53 53  , but is .[CROSS
31480 20 4a 4f 49 4e 7c 68 61 6e 64 6c 65 64 20 64 69   JOIN|handled di
31490 66 66 65 72 65 6e 74 6c 79 20 62 79 20 74 68 65  fferently by the
314a0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
314b0 5d 0a 69 6e 20 74 68 61 74 20 69 74 20 70 72 65  ].in that it pre
314c0 76 65 6e 74 73 20 74 68 65 20 71 75 65 72 79 20  vents the query 
314d0 6f 70 74 69 6d 69 7a 65 72 20 66 72 6f 6d 20 72  optimizer from r
314e0 65 6f 72 64 65 72 69 6e 67 0a 74 68 65 20 74 61  eordering.the ta
314f0 62 6c 65 73 20 69 6e 20 74 68 65 20 6a 6f 69 6e  bles in the join
31500 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
31510 6e 20 70 72 6f 67 72 61 6d 6d 65 72 20 63 61 6e  n programmer can
31520 20 75 73 65 20 74 68 65 20 43 52 4f 53 53 20 4a   use the CROSS J
31530 4f 49 4e 20 0a 6f 70 65 72 61 74 6f 72 20 74 6f  OIN .operator to
31540 20 64 69 72 65 63 74 6c 79 20 69 6e 66 6c 75 65   directly influe
31550 6e 63 65 20 74 68 65 20 61 6c 67 6f 72 69 74 68  nce the algorith
31560 6d 20 74 68 61 74 20 69 73 20 63 68 6f 73 65 6e  m that is chosen
31570 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 74 68   to implement.th
31580 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
31590 6e 74 2e 20 20 41 76 6f 69 64 20 75 73 69 6e 67  nt.  Avoid using
315a0 20 43 52 4f 53 53 20 4a 4f 49 4e 20 65 78 63 65   CROSS JOIN exce
315b0 70 74 20 69 6e 20 73 70 65 63 69 66 69 63 20 73  pt in specific s
315c0 69 74 75 61 74 69 6f 6e 73 20 0a 77 68 65 72 65  ituations .where
315d0 20 6d 61 6e 75 61 6c 20 63 6f 6e 74 72 6f 6c 20   manual control 
315e0 6f 66 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  of the query opt
315f0 69 6d 69 7a 65 72 20 69 73 20 64 65 73 69 72 65  imizer is desire
31600 64 2e 20 20 41 76 6f 69 64 20 75 73 69 6e 67 0a  d.  Avoid using.
31610 43 52 4f 53 53 20 4a 4f 49 4e 20 65 61 72 6c 79  CROSS JOIN early
31620 20 69 6e 20 74 68 65 20 64 65 76 65 6c 6f 70 6d   in the developm
31630 65 6e 74 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ent of an applic
31640 61 74 69 6f 6e 20 61 73 20 64 6f 69 6e 67 20 73  ation as doing s
31650 6f 20 69 73 0a 61 20 3c 61 20 68 72 65 66 3d 22  o is.a <a href="
31660 68 74 74 70 3a 2f 2f 63 32 2e 63 6f 6d 2f 63 67  http://c2.com/cg
31670 69 2f 77 69 6b 69 3f 50 72 65 6d 61 74 75 72 65  i/wiki?Premature
31680 4f 70 74 69 6d 69 7a 61 74 69 6f 6e 22 3e 70 72  Optimization">pr
31690 65 6d 61 74 75 72 65 0a 6f 70 74 69 6d 69 7a 61  emature.optimiza
316a0 74 69 6f 6e 3c 2f 61 3e 2e 20 20 54 68 65 20 73  tion</a>.  The s
316b0 70 65 63 69 61 6c 20 68 61 6e 64 6c 69 6e 67 20  pecial handling 
316c0 6f 66 20 43 52 4f 53 53 20 4a 4f 49 4e 20 69 73  of CROSS JOIN is
316d0 20 61 6e 20 53 51 4c 69 74 65 2d 73 70 65 63 69   an SQLite-speci
316e0 66 69 63 0a 66 65 61 74 75 72 65 20 61 6e 64 20  fic.feature and 
316f0 69 73 20 6e 6f 74 20 61 20 70 61 72 74 20 6f 66  is not a part of
31700 20 73 74 61 6e 64 61 72 64 20 53 51 4c 2e 0a 20   standard SQL.. 
31710 20 20 20 20 20 20 0a 0a 3c 74 63 6c 3e 68 64 5f        ..<tcl>hd_
31720 66 72 61 67 6d 65 6e 74 20 77 68 65 72 65 63 6c  fragment wherecl
31730 61 75 73 65 3c 2f 74 63 6c 3e 0a 3c 74 63 6c 3e  ause</tcl>.<tcl>
31740 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b 57 48 45  hd_keywords {WHE
31750 52 45 20 63 6c 61 75 73 65 7d 3c 2f 74 63 6c 3e  RE clause}</tcl>
31760 0a 3c 70 3e 3c 62 3e 32 2e 20 57 48 45 52 45 20  .<p><b>2. WHERE 
31770 63 6c 61 75 73 65 20 66 69 6c 74 65 72 69 6e 67  clause filtering
31780 2e 3c 2f 62 3e 0a 0a 3c 70 3e 5e 28 49 66 20 61  .</b>..<p>^(If a
31790 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 73   WHERE clause is
317a0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 20   specified, the 
317b0 57 48 45 52 45 20 65 78 70 72 65 73 73 69 6f 6e  WHERE expression
317c0 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 66 6f   is evaluated fo
317d0 72 20 0a 65 61 63 68 20 72 6f 77 20 69 6e 20 74  r .each row in t
317e0 68 65 20 69 6e 70 75 74 20 64 61 74 61 20 61 73  he input data as
317f0 20 61 20 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72   a [boolean expr
31800 65 73 73 69 6f 6e 5d 2e 20 4f 6e 6c 79 20 72 6f  ession]. Only ro
31810 77 73 20 66 6f 72 20 77 68 69 63 68 20 74 68 65  ws for which the
31820 0a 57 48 45 52 45 20 63 6c 61 75 73 65 20 65 78  .WHERE clause ex
31830 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74  pression evaluat
31840 65 73 20 74 6f 20 74 72 75 65 20 61 72 65 20 69  es to true are i
31850 6e 63 6c 75 64 65 64 20 66 72 6f 6d 20 74 68 65  ncluded from the
31860 20 64 61 74 61 73 65 74 20 62 65 66 6f 72 65 0a   dataset before.
31870 63 6f 6e 74 69 6e 75 69 6e 67 2e 29 5e 20 20 52  continuing.)^  R
31880 6f 77 73 20 61 72 65 20 65 78 63 6c 75 64 65 64  ows are excluded
31890 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
318a0 20 69 66 20 74 68 65 20 57 48 45 52 45 20 63 6c   if the WHERE cl
318b0 61 75 73 65 0a 65 76 61 6c 75 61 74 65 73 20 74  ause.evaluates t
318c0 6f 20 65 69 74 68 65 72 20 66 61 6c 73 65 20 6f  o either false o
318d0 72 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 46 6f 72 20  r NULL...<p>For 
318e0 61 20 4a 4f 49 4e 20 6f 72 20 49 4e 4e 45 52 20  a JOIN or INNER 
318f0 4a 4f 49 4e 20 6f 72 20 43 52 4f 53 53 20 4a 4f  JOIN or CROSS JO
31900 49 4e 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  IN, there is no 
31910 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
31920 65 6e 20 0a 61 20 63 6f 6e 73 74 72 61 69 6e 74  en .a constraint
31930 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74   expression in t
31940 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
31950 61 6e 64 20 6f 6e 65 20 69 6e 20 74 68 65 20 4f  and one in the O
31960 4e 20 63 6c 61 75 73 65 2e 20 20 48 6f 77 65 76  N clause.  Howev
31970 65 72 2c 0a 66 6f 72 20 61 20 4c 45 46 54 20 4a  er,.for a LEFT J
31980 4f 49 4e 20 6f 72 20 4c 45 46 54 20 4f 55 54 45  OIN or LEFT OUTE
31990 52 20 4a 4f 49 4e 2c 20 74 68 65 20 64 69 66 66  R JOIN, the diff
319a0 65 72 65 6e 63 65 20 69 73 20 76 65 72 79 20 69  erence is very i
319b0 6d 70 6f 72 74 61 6e 74 2e 20 20 0a 49 6e 20 61  mportant.  .In a
319c0 20 4c 45 46 54 20 4a 4f 49 4e 2c 0a 74 68 65 20   LEFT JOIN,.the 
319d0 65 78 74 72 61 20 4e 55 4c 4c 20 72 6f 77 20 66  extra NULL row f
319e0 6f 72 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  or the right-han
319f0 64 20 74 61 62 6c 65 20 69 73 20 61 64 64 65 64  d table is added
31a00 20 61 66 74 65 72 20 4f 4e 20 63 6c 61 75 73 65   after ON clause
31a10 20 70 72 6f 63 65 73 73 69 6e 67 0a 62 75 74 20   processing.but 
31a20 62 65 66 6f 72 65 20 57 48 45 52 45 20 63 6c 61  before WHERE cla
31a30 75 73 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  use processing. 
31a40 20 41 20 63 6f 6e 73 74 72 61 69 6e 74 20 6f 66   A constraint of
31a50 20 74 68 65 20 66 6f 72 6d 20 22 6c 65 66 74 2e   the form "left.
31a60 78 3d 72 69 67 68 74 2e 79 22 0a 69 6e 20 61 6e  x=right.y".in an
31a70 20 4f 4e 20 63 6c 61 75 73 65 20 77 69 6c 6c 20   ON clause will 
31a80 74 68 65 72 65 66 6f 72 65 20 61 6c 6c 6f 77 20  therefore allow 
31a90 74 68 72 6f 75 67 68 20 74 68 65 20 61 64 64 65  through the adde
31aa0 64 20 61 6c 6c 2d 4e 55 4c 4c 20 72 6f 77 73 20  d all-NULL rows 
31ab0 6f 66 20 74 68 65 0a 72 69 67 68 74 20 74 61 62  of the.right tab
31ac0 6c 65 2e 20 20 42 75 74 20 69 66 20 74 68 61 74  le.  But if that
31ad0 20 73 61 6d 65 20 63 6f 6e 73 74 72 61 69 6e 74   same constraint
31ae0 20 69 73 20 69 6e 20 74 68 65 20 57 48 45 52 45   is in the WHERE
31af0 20 63 6c 61 75 73 65 20 61 20 4e 55 4c 4c 20 69   clause a NULL i
31b00 6e 0a 22 72 69 67 68 74 2e 79 22 20 77 69 6c 6c  n."right.y" will
31b10 20 70 72 65 76 65 6e 74 20 74 68 65 20 65 78 70   prevent the exp
31b20 72 65 73 73 69 6f 6e 20 22 6c 65 66 74 2e 78 3d  ression "left.x=
31b30 72 69 67 68 74 2e 79 22 20 66 72 6f 6d 20 62 65  right.y" from be
31b40 69 6e 67 20 74 72 75 65 2c 20 61 6e 64 0a 74 68  ing true, and.th
31b50 75 73 20 65 78 63 6c 75 64 65 20 74 68 61 74 20  us exclude that 
31b60 72 6f 77 20 66 72 6f 6d 20 74 68 65 20 6f 75 74  row from the out
31b70 70 75 74 2e 0a 0a 3c 70 3e 3c 62 3e 33 2e 20 47  put...<p><b>3. G
31b80 65 6e 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  eneration of the
31b90 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20 72   set of result r
31ba0 6f 77 73 2e 3c 2f 62 3e 0a 3c 74 63 6c 3e 68 64  ows.</b>.<tcl>hd
31bb0 5f 66 72 61 67 6d 65 6e 74 20 72 65 73 75 6c 74  _fragment result
31bc0 73 65 74 3c 2f 74 63 6c 3e 0a 3c 74 63 6c 3e 68  set</tcl>.<tcl>h
31bd0 64 5f 6b 65 79 77 6f 72 64 73 20 7b 72 65 73 75  d_keywords {resu
31be0 6c 74 2d 73 65 74 20 65 78 70 72 65 73 73 69 6f  lt-set expressio
31bf0 6e 73 7d 20 7b 47 52 4f 55 50 20 42 59 7d 3c 2f  ns} {GROUP BY}</
31c00 74 63 6c 3e 0a 0a 3c 70 3e 4f 6e 63 65 20 74 68  tcl>..<p>Once th
31c10 65 20 69 6e 70 75 74 20 64 61 74 61 20 66 72 6f  e input data fro
31c20 6d 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73  m the FROM claus
31c30 65 20 68 61 73 20 62 65 65 6e 20 66 69 6c 74 65  e has been filte
31c40 72 65 64 20 62 79 20 74 68 65 0a 57 48 45 52 45  red by the.WHERE
31c50 20 63 6c 61 75 73 65 20 65 78 70 72 65 73 73 69   clause expressi
31c60 6f 6e 20 28 69 66 20 61 6e 79 29 2c 20 74 68 65  on (if any), the
31c70 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20 72   set of result r
31c80 6f 77 73 20 66 6f 72 20 74 68 65 20 73 69 6d 70  ows for the simp
31c90 6c 65 20 0a 53 45 4c 45 43 54 20 61 72 65 20 63  le .SELECT are c
31ca0 61 6c 63 75 6c 61 74 65 64 2e 20 45 78 61 63 74  alculated. Exact
31cb0 6c 79 20 68 6f 77 20 74 68 69 73 20 69 73 20 64  ly how this is d
31cc0 6f 6e 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 77  one depends on w
31cd0 68 65 74 68 65 72 20 74 68 65 20 73 69 6d 70 6c  hether the simpl
31ce0 65 20 0a 53 45 4c 45 43 54 20 69 73 20 61 6e 20  e .SELECT is an 
31cf0 61 67 67 72 65 67 61 74 65 20 6f 72 20 6e 6f 6e  aggregate or non
31d00 2d 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79  -aggregate query
31d10 2c 20 61 6e 64 20 77 68 65 74 68 65 72 20 6f 72  , and whether or
31d20 20 6e 6f 74 20 61 20 47 52 4f 55 50 0a 42 59 20   not a GROUP.BY 
31d30 63 6c 61 75 73 65 20 77 61 73 20 73 70 65 63 69  clause was speci
31d40 66 69 65 64 2e 0a 0a 3c 70 3e 20 54 68 65 20 6c  fied...<p> The l
31d50 69 73 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ist of expressio
31d60 6e 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 53  ns between the S
31d70 45 4c 45 43 54 20 61 6e 64 20 46 52 4f 4d 20 6b  ELECT and FROM k
31d80 65 79 77 6f 72 64 73 20 69 73 20 6b 6e 6f 77 6e  eywords is known
31d90 20 61 73 0a 74 68 65 20 72 65 73 75 6c 74 20 65   as.the result e
31da0 78 70 72 65 73 73 69 6f 6e 20 6c 69 73 74 2e 20  xpression list. 
31db0 20 5e 49 66 20 61 20 72 65 73 75 6c 74 20 65 78   ^If a result ex
31dc0 70 72 65 73 73 69 6f 6e 20 69 73 20 74 68 65 20  pression is the 
31dd0 73 70 65 63 69 61 6c 20 65 78 70 72 65 73 73 69  special expressi
31de0 6f 6e 0a 22 2a 22 20 74 68 65 6e 20 61 6c 6c 20  on."*" then all 
31df0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 69  columns in the i
31e00 6e 70 75 74 20 64 61 74 61 20 61 72 65 20 73 75  nput data are su
31e10 62 73 74 69 74 75 74 65 64 20 66 6f 72 20 74 68  bstituted for th
31e20 61 74 20 6f 6e 65 20 65 78 70 72 65 73 73 69 6f  at one expressio
31e30 6e 2e 0a 5e 28 49 66 20 74 68 65 20 65 78 70 72  n..^(If the expr
31e40 65 73 73 69 6f 6e 20 69 73 20 74 68 65 20 61 6c  ession is the al
31e50 69 61 73 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  ias of a table o
31e60 72 20 73 75 62 71 75 65 72 79 20 69 6e 20 74 68  r subquery in th
31e70 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 0a 66 6f  e FROM clause.fo
31e80 6c 6c 6f 77 65 64 20 62 79 20 22 2e 2a 22 20 74  llowed by ".*" t
31e90 68 65 6e 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20  hen all columns 
31ea0 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 74  from the named t
31eb0 61 62 6c 65 20 6f 72 20 73 75 62 71 75 65 72 79  able or subquery
31ec0 20 61 72 65 0a 73 75 62 73 74 69 74 75 74 65 64   are.substituted
31ed0 20 66 6f 72 20 74 68 65 20 73 69 6e 67 6c 65 20   for the single 
31ee0 65 78 70 72 65 73 73 69 6f 6e 2e 29 5e 20 5e 28  expression.)^ ^(
31ef0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
31f00 6f 20 75 73 65 20 61 20 22 2a 22 20 6f 72 0a 22  o use a "*" or."
31f10 61 6c 69 61 73 2e 2a 22 20 65 78 70 72 65 73 73  alias.*" express
31f20 69 6f 6e 20 69 6e 20 61 6e 79 20 63 6f 6e 74 65  ion in any conte
31f30 78 74 20 6f 74 68 65 72 20 74 68 61 6e 20 61 20  xt other than a 
31f40 72 65 73 75 6c 74 20 65 78 70 72 65 73 73 69 6f  result expressio
31f50 6e 20 6c 69 73 74 2e 29 5e 0a 5e 28 49 74 20 69  n list.)^.^(It i
31f60 73 20 61 6c 73 6f 20 61 6e 20 65 72 72 6f 72 20  s also an error 
31f70 74 6f 20 75 73 65 20 61 20 22 2a 22 20 6f 72 20  to use a "*" or 
31f80 22 61 6c 69 61 73 2e 2a 22 20 65 78 70 72 65 73  "alias.*" expres
31f90 73 69 6f 6e 20 69 6e 20 61 20 73 69 6d 70 6c 65  sion in a simple
31fa0 20 53 45 4c 45 43 54 0a 71 75 65 72 79 20 74 68   SELECT.query th
31fb0 61 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  at does not have
31fc0 20 61 20 46 52 4f 4d 20 63 6c 61 75 73 65 2e 29   a FROM clause.)
31fd0 5e 0a 0a 3c 70 3e 20 5e 28 54 68 65 20 6e 75 6d  ^..<p> ^(The num
31fe0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31ff0 6e 20 74 68 65 20 72 6f 77 73 20 72 65 74 75 72  n the rows retur
32000 6e 65 64 20 62 79 20 61 20 73 69 6d 70 6c 65 20  ned by a simple 
32010 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
32020 0a 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65  .is equal to the
32030 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 70 72 65   number of expre
32040 73 73 69 6f 6e 73 20 69 6e 20 74 68 65 20 72 65  ssions in the re
32050 73 75 6c 74 20 65 78 70 72 65 73 73 69 6f 6e 20  sult expression 
32060 6c 69 73 74 20 61 66 74 65 72 0a 73 75 62 73 74  list after.subst
32070 69 74 75 74 69 6f 6e 20 6f 66 20 2a 20 61 6e 64  itution of * and
32080 20 61 6c 69 61 73 2e 2a 20 65 78 70 72 65 73 73   alias.* express
32090 69 6f 6e 73 2e 29 5e 20 45 61 63 68 20 72 65 73  ions.)^ Each res
320a0 75 6c 74 20 72 6f 77 20 69 73 20 63 61 6c 63 75  ult row is calcu
320b0 6c 61 74 65 64 20 62 79 0a 65 76 61 6c 75 61 74  lated by.evaluat
320c0 69 6e 67 20 74 68 65 20 65 78 70 72 65 73 73 69  ing the expressi
320d0 6f 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  ons in the resul
320e0 74 20 65 78 70 72 65 73 73 69 6f 6e 20 6c 69 73  t expression lis
320f0 74 20 77 69 74 68 20 72 65 73 70 65 63 74 20 74  t with respect t
32100 6f 20 61 0a 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a.single row o
32110 66 20 69 6e 70 75 74 20 64 61 74 61 20 6f 72 2c  f input data or,
32120 20 66 6f 72 20 61 67 67 72 65 67 61 74 65 20 71   for aggregate q
32130 75 65 72 69 65 73 2c 20 77 69 74 68 20 72 65 73  ueries, with res
32140 70 65 63 74 20 74 6f 20 61 20 67 72 6f 75 70 0a  pect to a group.
32150 6f 66 20 72 6f 77 73 2e 0a 0a 3c 75 6c 3e 0a 20  of rows...<ul>. 
32160 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20   <li><p>^If the 
32170 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
32180 20 69 73 20 3c 62 3e 61 20 6e 6f 6e 2d 61 67 67   is <b>a non-agg
32190 72 65 67 61 74 65 20 71 75 65 72 79 3c 2f 62 3e  regate query</b>
321a0 2c 20 74 68 65 6e 20 0a 20 20 20 20 65 61 63 68  , then .    each
321b0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74   expression in t
321c0 68 65 20 72 65 73 75 6c 74 20 65 78 70 72 65 73  he result expres
321d0 73 69 6f 6e 20 6c 69 73 74 20 69 73 20 65 76 61  sion list is eva
321e0 6c 75 61 74 65 64 20 66 6f 72 20 65 61 63 68 20  luated for each 
321f0 72 6f 77 20 69 6e 0a 20 20 20 20 74 68 65 20 64  row in.    the d
32200 61 74 61 73 65 74 20 66 69 6c 74 65 72 65 64 20  ataset filtered 
32210 62 79 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  by the WHERE cla
32220 75 73 65 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  use...  <li><p>^
32230 49 66 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  If the SELECT st
32240 61 74 65 6d 65 6e 74 20 69 73 20 3c 62 3e 61 6e  atement is <b>an
32250 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
32260 20 77 69 74 68 6f 75 74 20 61 20 47 52 4f 55 50   without a GROUP
32270 0a 20 20 20 20 42 59 3c 2f 62 3e 20 63 6c 61 75  .    BY</b> clau
32280 73 65 2c 20 74 68 65 6e 20 65 61 63 68 20 61 67  se, then each ag
32290 67 72 65 67 61 74 65 20 65 78 70 72 65 73 73 69  gregate expressi
322a0 6f 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  on in the result
322b0 2d 73 65 74 20 69 73 20 0a 20 20 20 20 65 76 61  -set is .    eva
322c0 6c 75 61 74 65 64 20 6f 6e 63 65 20 61 63 72 6f  luated once acro
322d0 73 73 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  ss the entire da
322e0 74 61 73 65 74 2e 20 5e 45 61 63 68 20 6e 6f 6e  taset. ^Each non
322f0 2d 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65  -aggregate expre
32300 73 73 69 6f 6e 0a 20 20 20 20 69 6e 20 74 68 65  ssion.    in the
32310 20 72 65 73 75 6c 74 2d 73 65 74 20 69 73 20 65   result-set is e
32320 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20 66 6f  valuated once fo
32330 72 20 61 6e 20 61 72 62 69 74 72 61 72 69 6c 79  r an arbitrarily
32340 20 73 65 6c 65 63 74 65 64 20 72 6f 77 20 6f 66   selected row of
32350 0a 20 20 20 20 74 68 65 20 64 61 74 61 73 65 74  .    the dataset
32360 2e 20 5e 54 68 65 20 73 61 6d 65 20 61 72 62 69  . ^The same arbi
32370 74 72 61 72 69 6c 79 20 73 65 6c 65 63 74 65 64  trarily selected
32380 20 72 6f 77 20 69 73 20 75 73 65 64 20 66 6f 72   row is used for
32390 20 65 61 63 68 0a 20 20 20 20 6e 6f 6e 2d 61 67   each.    non-ag
323a0 67 72 65 67 61 74 65 20 65 78 70 72 65 73 73 69  gregate expressi
323b0 6f 6e 2e 20 5e 4f 72 2c 20 69 66 20 74 68 65 20  on. ^Or, if the 
323c0 64 61 74 61 73 65 74 20 63 6f 6e 74 61 69 6e 73  dataset contains
323d0 20 7a 65 72 6f 20 72 6f 77 73 2c 20 74 68 65 6e   zero rows, then
323e0 20 0a 20 20 20 20 65 61 63 68 20 6e 6f 6e 2d 61   .    each non-a
323f0 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73 73  ggregate express
32400 69 6f 6e 20 69 73 20 65 76 61 6c 75 61 74 65 64  ion is evaluated
32410 20 61 67 61 69 6e 73 74 20 61 20 72 6f 77 20 63   against a row c
32420 6f 6e 73 69 73 74 69 6e 67 0a 20 20 20 20 65 6e  onsisting.    en
32430 74 69 72 65 6c 79 20 6f 66 20 4e 55 4c 4c 20 76  tirely of NULL v
32440 61 6c 75 65 73 2e 0a 0a 20 20 20 3c 70 3e 5e 54  alues...   <p>^T
32450 68 65 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66  he single row of
32460 20 72 65 73 75 6c 74 2d 73 65 74 20 64 61 74 61   result-set data
32470 20 63 72 65 61 74 65 64 20 62 79 20 65 76 61 6c   created by eval
32480 75 61 74 69 6e 67 20 74 68 65 20 61 67 67 72 65  uating the aggre
32490 67 61 74 65 0a 20 20 20 20 61 6e 64 20 6e 6f 6e  gate.    and non
324a0 2d 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65  -aggregate expre
324b0 73 73 69 6f 6e 73 20 69 6e 20 74 68 65 20 72 65  ssions in the re
324c0 73 75 6c 74 2d 73 65 74 20 66 6f 72 6d 73 20 74  sult-set forms t
324d0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 0a  he result of an.
324e0 20 20 20 20 61 67 67 72 65 67 61 74 65 20 71 75      aggregate qu
324f0 65 72 79 20 77 69 74 68 6f 75 74 20 61 20 47 52  ery without a GR
32500 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 20 5e  OUP BY clause. ^
32510 41 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  An aggregate que
32520 72 79 20 77 69 74 68 6f 75 74 20 61 0a 20 20 20  ry without a.   
32530 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
32540 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
32550 65 78 61 63 74 6c 79 20 6f 6e 65 20 72 6f 77 20  exactly one row 
32560 6f 66 20 64 61 74 61 2c 20 65 76 65 6e 20 69 66  of data, even if
32570 20 74 68 65 72 65 20 61 72 65 0a 20 20 20 20 7a   there are.    z
32580 65 72 6f 20 72 6f 77 73 20 6f 66 20 69 6e 70 75  ero rows of inpu
32590 74 20 64 61 74 61 2e 0a 0a 20 20 3c 6c 69 3e 3c  t data...  <li><
325a0 70 3e 5e 28 49 66 20 74 68 65 20 53 45 4c 45 43  p>^(If the SELEC
325b0 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 3c  T statement is <
325c0 62 3e 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  b>an aggregate q
325d0 75 65 72 79 20 77 69 74 68 20 61 20 47 52 4f 55  uery with a GROU
325e0 50 0a 20 20 20 20 42 59 3c 2f 62 3e 20 63 6c 61  P.    BY</b> cla
325f0 75 73 65 2c 20 74 68 65 6e 20 65 61 63 68 20 6f  use, then each o
32600 66 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e  f the expression
32610 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  s specified as p
32620 61 72 74 20 6f 66 20 74 68 65 0a 20 20 20 20 47  art of the.    G
32630 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 20 69  ROUP BY clause i
32640 73 20 65 76 61 6c 75 61 74 65 64 20 66 6f 72 20  s evaluated for 
32650 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20  each row of the 
32660 64 61 74 61 73 65 74 2e 20 45 61 63 68 20 72 6f  dataset. Each ro
32670 77 0a 20 20 20 20 69 73 20 74 68 65 6e 20 61 73  w.    is then as
32680 73 69 67 6e 65 64 20 74 6f 20 61 20 22 67 72 6f  signed to a "gro
32690 75 70 22 20 62 61 73 65 64 20 6f 6e 20 74 68 65  up" based on the
326a0 20 72 65 73 75 6c 74 73 3b 20 72 6f 77 73 20 66   results; rows f
326b0 6f 72 20 77 68 69 63 68 0a 20 20 20 20 74 68 65  or which.    the
326c0 20 72 65 73 75 6c 74 73 20 6f 66 20 65 76 61 6c   results of eval
326d0 75 61 74 69 6e 67 20 74 68 65 20 47 52 4f 55 50  uating the GROUP
326e0 20 42 59 20 65 78 70 72 65 73 73 69 6f 6e 73 20   BY expressions 
326f0 61 72 65 20 74 68 65 20 73 61 6d 65 20 67 65 74  are the same get
32700 0a 20 20 20 20 61 73 73 69 67 6e 65 64 20 74 6f  .    assigned to
32710 20 74 68 65 20 73 61 6d 65 20 67 72 6f 75 70 2e   the same group.
32720 29 5e 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  )^ ^For the purp
32730 6f 73 65 73 20 6f 66 20 67 72 6f 75 70 69 6e 67  oses of grouping
32740 20 72 6f 77 73 2c 20 4e 55 4c 4c 20 0a 20 20 20   rows, NULL .   
32750 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f 6e 73   values are cons
32760 69 64 65 72 65 64 20 65 71 75 61 6c 2e 20 5e 54  idered equal. ^T
32770 68 65 20 75 73 75 61 6c 20 72 75 6c 65 73 20 66  he usual rules f
32780 6f 72 20 5b 63 6f 6c 6c 61 74 69 6f 6e 7c 73 65  or [collation|se
32790 6c 65 63 74 69 6e 67 20 61 0a 20 20 20 20 63 6f  lecting a.    co
327a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
327b0 5d 20 77 69 74 68 20 77 68 69 63 68 20 74 6f 20  ] with which to 
327c0 63 6f 6d 70 61 72 65 20 74 65 78 74 20 76 61 6c  compare text val
327d0 75 65 73 20 61 70 70 6c 79 20 77 68 65 6e 20 65  ues apply when e
327e0 76 61 6c 75 61 74 69 6e 67 0a 20 20 20 20 65 78  valuating.    ex
327f0 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 20 47  pressions in a G
32800 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 20  ROUP BY clause. 
32810 20 5e 54 68 65 20 65 78 70 72 65 73 73 69 6f 6e   ^The expression
32820 73 20 69 6e 20 74 68 65 20 47 52 4f 55 50 20 42  s in the GROUP B
32830 59 20 63 6c 61 75 73 65 0a 20 20 20 20 64 6f 20  Y clause.    do 
32840 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 68 61 76  <em>not</em> hav
32850 65 20 74 6f 20 62 65 20 65 78 70 72 65 73 73 69  e to be expressi
32860 6f 6e 73 20 74 68 61 74 20 61 70 70 65 61 72 20  ons that appear 
32870 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 5e  in the result. ^
32880 54 68 65 0a 20 20 20 20 65 78 70 72 65 73 73 69  The.    expressi
32890 6f 6e 73 20 69 6e 20 61 20 47 52 4f 55 50 20 42  ons in a GROUP B
328a0 59 20 63 6c 61 75 73 65 20 6d 61 79 20 6e 6f 74  Y clause may not
328b0 20 62 65 20 61 67 67 72 65 67 61 74 65 20 65 78   be aggregate ex
328c0 70 72 65 73 73 69 6f 6e 73 2e 0a 0a 20 20 20 20  pressions...    
328d0 3c 70 3e 5e 28 49 66 20 61 20 48 41 56 49 4e 47  <p>^(If a HAVING
328e0 20 63 6c 61 75 73 65 20 69 73 20 73 70 65 63 69   clause is speci
328f0 66 69 65 64 2c 20 69 74 20 69 73 20 65 76 61 6c  fied, it is eval
32900 75 61 74 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  uated once for e
32910 61 63 68 20 67 72 6f 75 70 20 0a 20 20 20 20 6f  ach group .    o
32920 66 20 72 6f 77 73 20 61 73 20 61 20 5b 62 6f 6f  f rows as a [boo
32930 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 5d  lean expression]
32940 2e 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  . If the result 
32950 6f 66 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  of evaluating th
32960 65 0a 20 20 20 20 48 41 56 49 4e 47 20 63 6c 61  e.    HAVING cla
32970 75 73 65 20 69 73 20 66 61 6c 73 65 2c 20 74 68  use is false, th
32980 65 20 67 72 6f 75 70 20 69 73 20 64 69 73 63 61  e group is disca
32990 72 64 65 64 2e 29 5e 20 5e 49 66 20 74 68 65 20  rded.)^ ^If the 
329a0 48 41 56 49 4e 47 20 63 6c 61 75 73 65 20 69 73  HAVING clause is
329b0 0a 20 20 20 20 61 6e 20 61 67 67 72 65 67 61 74  .    an aggregat
329c0 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 74  e expression, it
329d0 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 61 63   is evaluated ac
329e0 72 6f 73 73 20 61 6c 6c 20 72 6f 77 73 20 69 6e  ross all rows in
329f0 20 74 68 65 20 67 72 6f 75 70 2e 20 5e 49 66 0a   the group. ^If.
32a00 20 20 20 20 61 20 48 41 56 49 4e 47 20 63 6c 61      a HAVING cla
32a10 75 73 65 20 69 73 20 61 20 6e 6f 6e 2d 61 67 67  use is a non-agg
32a20 72 65 67 61 74 65 20 65 78 70 72 65 73 73 69 6f  regate expressio
32a30 6e 2c 20 69 74 20 69 73 20 65 76 61 6c 75 61 74  n, it is evaluat
32a40 65 64 20 77 69 74 68 20 72 65 73 70 65 63 74 0a  ed with respect.
32a50 20 20 20 20 74 6f 20 61 6e 20 61 72 62 69 74 72      to an arbitr
32a60 61 72 69 6c 79 20 73 65 6c 65 63 74 65 64 20 72  arily selected r
32a70 6f 77 20 66 72 6f 6d 20 74 68 65 20 67 72 6f 75  ow from the grou
32a80 70 2e 20 20 5e 54 68 65 20 48 41 56 49 4e 47 20  p.  ^The HAVING 
32a90 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 79 0a 20  expression may. 
32aa0 20 20 20 72 65 66 65 72 20 74 6f 20 76 61 6c 75     refer to valu
32ab0 65 73 2c 20 65 76 65 6e 20 61 67 67 72 65 67 61  es, even aggrega
32ac0 74 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 74 68  te functions, th
32ad0 61 74 20 61 72 65 20 6e 6f 74 20 69 6e 20 74 68  at are not in th
32ae0 65 20 72 65 73 75 6c 74 2e 3c 2f 70 3e 0a 0a 20  e result.</p>.. 
32af0 20 20 20 3c 70 3e 5e 45 61 63 68 20 65 78 70 72     <p>^Each expr
32b00 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65  ession in the re
32b10 73 75 6c 74 2d 73 65 74 20 69 73 20 74 68 65 6e  sult-set is then
32b20 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20   evaluated once 
32b30 66 6f 72 20 65 61 63 68 0a 20 20 20 20 67 72 6f  for each.    gro
32b40 75 70 20 6f 66 20 72 6f 77 73 2e 20 5e 49 66 20  up of rows. ^If 
32b50 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69  the expression i
32b60 73 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 65  s an aggregate e
32b70 78 70 72 65 73 73 69 6f 6e 2c 20 69 74 20 69 73  xpression, it is
32b80 20 0a 20 20 20 20 65 76 61 6c 75 61 74 65 64 20   .    evaluated 
32b90 61 63 72 6f 73 73 20 61 6c 6c 20 72 6f 77 73 20  across all rows 
32ba0 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 20 5e 4f  in the group. ^O
32bb0 74 68 65 72 77 69 73 65 2c 20 69 74 20 69 73 20  therwise, it is 
32bc0 65 76 61 6c 75 61 74 65 64 20 61 67 61 69 6e 73  evaluated agains
32bd0 74 0a 20 20 20 20 61 20 73 69 6e 67 6c 65 20 61  t.    a single a
32be0 72 62 69 74 72 61 72 69 6c 79 20 63 68 6f 73 65  rbitrarily chose
32bf0 6e 20 72 6f 77 20 66 72 6f 6d 20 77 69 74 68 69  n row from withi
32c00 6e 20 74 68 65 20 67 72 6f 75 70 2e 20 5e 49 66  n the group. ^If
32c10 20 74 68 65 72 65 20 69 73 20 6d 6f 72 65 0a 20   there is more. 
32c20 20 20 20 74 68 61 6e 20 6f 6e 65 20 6e 6f 6e 2d     than one non-
32c30 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73  aggregate expres
32c40 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65 73 75  sion in the resu
32c50 6c 74 2d 73 65 74 2c 20 74 68 65 6e 20 61 6c 6c  lt-set, then all
32c60 20 73 75 63 68 0a 20 20 20 20 65 78 70 72 65 73   such.    expres
32c70 73 69 6f 6e 73 20 61 72 65 20 65 76 61 6c 75 61  sions are evalua
32c80 74 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ted for the same
32c90 20 72 6f 77 2e 0a 0a 20 20 20 20 3c 70 3e 5e 45   row...    <p>^E
32ca0 61 63 68 20 67 72 6f 75 70 20 6f 66 20 69 6e 70  ach group of inp
32cb0 75 74 20 64 61 74 61 73 65 74 20 72 6f 77 73 20  ut dataset rows 
32cc0 63 6f 6e 74 72 69 62 75 74 65 73 20 61 20 73 69  contributes a si
32cd0 6e 67 6c 65 20 72 6f 77 20 74 6f 20 74 68 65 20  ngle row to the 
32ce0 0a 20 20 20 20 73 65 74 20 6f 66 20 72 65 73 75  .    set of resu
32cf0 6c 74 20 72 6f 77 73 2e 20 5e 53 75 62 6a 65 63  lt rows. ^Subjec
32d00 74 20 74 6f 20 66 69 6c 74 65 72 69 6e 67 20 61  t to filtering a
32d10 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
32d20 68 65 20 44 49 53 54 49 4e 43 54 0a 20 20 20 20  he DISTINCT.    
32d30 6b 65 79 77 6f 72 64 2c 20 74 68 65 20 6e 75 6d  keyword, the num
32d40 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65 74 75  ber of rows retu
32d50 72 6e 65 64 20 62 79 20 61 6e 20 61 67 67 72 65  rned by an aggre
32d60 67 61 74 65 20 71 75 65 72 79 20 77 69 74 68 20  gate query with 
32d70 61 20 47 52 4f 55 50 0a 20 20 20 20 42 59 20 63  a GROUP.    BY c
32d80 6c 61 75 73 65 20 69 73 20 74 68 65 20 73 61 6d  lause is the sam
32d90 65 20 61 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e as the number 
32da0 6f 66 20 67 72 6f 75 70 73 20 6f 66 20 72 6f 77  of groups of row
32db0 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 61 70  s produced by ap
32dc0 70 6c 79 69 6e 67 0a 20 20 20 20 74 68 65 20 47  plying.    the G
32dd0 52 4f 55 50 20 42 59 20 61 6e 64 20 48 41 56 49  ROUP BY and HAVI
32de0 4e 47 20 63 6c 61 75 73 65 73 20 74 6f 20 74 68  NG clauses to th
32df0 65 20 66 69 6c 74 65 72 65 64 20 69 6e 70 75 74  e filtered input
32e00 20 64 61 74 61 73 65 74 2e 0a 3c 2f 75 6c 3e 0a   dataset..</ul>.
32e10 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
32e20 74 20 62 61 72 65 61 67 67 20 7b 62 61 72 65 20  t bareagg {bare 
32e30 61 67 67 72 65 67 61 74 65 20 74 65 72 6d 73 7d  aggregate terms}
32e40 3c 2f 74 63 6c 3e 0a 3c 70 3e 3c 62 3e 53 69 64  </tcl>.<p><b>Sid
32e50 65 20 6e 6f 74 65 3a 20 42 61 72 65 20 63 6f 6c  e note: Bare col
32e60 75 6d 6e 73 20 69 6e 20 61 6e 20 61 67 67 72 65  umns in an aggre
32e70 67 61 74 65 20 71 75 65 72 69 65 73 2e 3c 2f 62  gate queries.</b
32e80 3e 0a 54 68 65 20 75 73 75 61 6c 20 63 61 73 65  >.The usual case
32e90 20 69 73 20 74 68 61 74 20 61 6c 6c 20 63 6f 6c   is that all col
32ea0 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 20 61 6e 20  umn names in an 
32eb0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
32ec0 61 72 65 20 65 69 74 68 65 72 0a 61 72 67 75 6d  are either.argum
32ed0 65 6e 74 73 20 74 6f 20 5b 61 67 67 66 75 6e 63  ents to [aggfunc
32ee0 7c 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74  |aggregate funct
32ef0 69 6f 6e 73 5d 20 6f 72 20 65 6c 73 65 20 61 70  ions] or else ap
32f00 70 65 61 72 20 69 6e 20 74 68 65 20 47 52 4f 55  pear in the GROU
32f10 50 20 42 59 20 63 6c 61 75 73 65 2e 0a 41 20 72  P BY clause..A r
32f20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 68 69  esult column whi
32f30 63 68 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  ch contains a co
32f40 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69  lumn name that i
32f50 73 20 6e 6f 74 20 77 69 74 68 69 6e 20 61 6e 0a  s not within an.
32f60 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
32f70 6f 6e 20 61 6e 64 20 74 68 61 74 20 64 6f 65 73  on and that does
32f80 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74   not appear in t
32f90 68 65 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  he GROUP BY clau
32fa0 73 65 20 28 69 66 0a 6f 6e 65 20 65 78 69 73 74  se (if.one exist
32fb0 73 29 20 69 73 20 63 61 6c 6c 65 64 20 61 20 22  s) is called a "
32fc0 62 61 72 65 22 20 63 6f 6c 75 6d 6e 2e 0a 45 78  bare" column..Ex
32fd0 61 6d 70 6c 65 3a 0a 3c 62 6c 6f 63 6b 71 75 6f  ample:.<blockquo
32fe0 74 65 3e 3c 70 72 65 3e 0a 53 45 4c 45 43 54 20  te><pre>.SELECT 
32ff0 61 2c 20 62 2c 20 73 75 6d 28 63 29 20 46 52 4f  a, b, sum(c) FRO
33000 4d 20 74 61 62 31 20 47 52 4f 55 50 20 42 59 20  M tab1 GROUP BY 
33010 61 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  a;.</pre></block
33020 71 75 6f 74 65 3e 0a 3c 70 3e 49 6e 20 74 68 65  quote>.<p>In the
33030 20 71 75 65 72 79 20 61 62 6f 76 65 2c 20 74 68   query above, th
33040 65 20 22 61 22 20 63 6f 6c 75 6d 6e 20 69 73 20  e "a" column is 
33050 70 61 72 74 20 6f 66 20 74 68 65 20 47 52 4f 55  part of the GROU
33060 50 20 42 59 20 63 6c 61 75 73 65 0a 61 6e 64 20  P BY clause.and 
33070 73 6f 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  so each row of t
33080 68 65 20 6f 75 74 70 75 74 20 63 6f 6e 74 61 69  he output contai
33090 6e 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 69  ns one of the di
330a0 73 74 69 6e 63 74 20 76 61 6c 75 65 73 20 66 6f  stinct values fo
330b0 72 0a 22 61 22 2e 20 20 54 68 65 20 22 63 22 20  r."a".  The "c" 
330c0 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6e 74 61 69  column is contai
330d0 6e 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 5b  ned within the [
330e0 73 75 6d 28 29 5d 20 61 67 67 72 65 67 61 74 65  sum()] aggregate
330f0 20 66 75 6e 63 74 69 6f 6e 0a 61 6e 64 20 73 6f   function.and so
33100 20 74 68 61 74 20 6f 75 74 70 75 74 20 63 6f 6c   that output col
33110 75 6d 6e 20 69 73 20 74 68 65 20 73 75 6d 20 6f  umn is the sum o
33120 66 20 61 6c 6c 20 22 63 22 20 76 61 6c 75 65 73  f all "c" values
33130 20 69 6e 20 72 6f 77 73 20 74 68 61 74 0a 68 61   in rows that.ha
33140 76 65 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  ve the same valu
33150 65 20 66 6f 72 20 22 61 22 2e 20 20 42 75 74 20  e for "a".  But 
33160 77 68 61 74 20 69 73 20 74 68 65 20 72 65 73 75  what is the resu
33170 6c 74 20 6f 66 20 74 68 65 20 62 61 72 65 20 0a  lt of the bare .
33180 63 6f 6c 75 6d 6e 20 22 62 22 3f 20 54 68 65 20  column "b"? The 
33190 61 6e 73 77 65 72 20 69 73 20 74 68 61 74 20 74  answer is that t
331a0 68 65 20 22 62 22 20 72 65 73 75 6c 74 20 77 69  he "b" result wi
331b0 6c 6c 20 62 65 20 74 68 65 0a 76 61 6c 75 65 20  ll be the.value 
331c0 66 6f 72 20 22 62 22 20 69 6e 20 6f 6e 65 20 6f  for "b" in one o
331d0 66 20 74 68 65 20 69 6e 70 75 74 20 72 6f 77 73  f the input rows
331e0 20 74 68 61 74 20 66 6f 72 6d 20 74 68 65 20 61   that form the a
331f0 67 67 72 65 67 61 74 65 2e 0a 54 68 65 20 70 72  ggregate..The pr
33200 6f 62 6c 65 6d 20 69 73 20 74 68 61 74 20 79 6f  oblem is that yo
33210 75 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  u usually do not
33220 20 6b 6e 6f 77 20 77 68 69 63 68 20 69 6e 70 75   know which inpu
33230 74 20 72 6f 77 20 69 73 20 75 73 65 64 0a 74 6f  t row is used.to
33240 20 63 6f 6d 70 75 74 65 20 22 62 22 2c 20 61 6e   compute "b", an
33250 64 20 73 6f 20 69 6e 20 6d 61 6e 79 20 63 61 73  d so in many cas
33260 65 73 20 74 68 65 20 76 61 6c 75 65 20 66 6f 72  es the value for
33270 20 22 62 22 20 69 73 20 75 6e 64 65 66 69 6e 65   "b" is undefine
33280 64 2e 0a 3c 2f 70 3e 0a 3c 70 3e 0a 53 70 65 63  d..</p>.<p>.Spec
33290 69 61 6c 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  ial processing o
332a0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 20 61  ccurs when the a
332b0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
332c0 6e 20 69 73 20 0a 65 69 74 68 65 72 20 5b 6d 61  n is .either [ma
332d0 78 41 67 67 46 75 6e 63 7c 6d 69 6e 28 29 5d 20  xAggFunc|min()] 
332e0 6f 72 20 5b 6d 69 6e 41 67 67 46 75 6e 63 7c 6d  or [minAggFunc|m
332f0 61 78 28 29 5d 2e 20 20 45 78 61 6d 70 6c 65 3a  ax()].  Example:
33300 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
33310 65 3e 0a 53 45 4c 45 43 54 20 61 2c 20 62 2c 20  e>.SELECT a, b, 
33320 6d 61 78 28 63 29 20 46 52 4f 4d 20 74 61 62 31  max(c) FROM tab1
33330 20 47 52 4f 55 50 20 42 59 20 61 3b 0a 3c 2f 70   GROUP BY a;.</p
33340 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
33350 0a 57 68 65 6e 20 74 68 65 20 5b 6d 61 78 41 67  .When the [maxAg
33360 67 46 75 6e 63 7c 6d 69 6e 28 29 5d 20 6f 72 20  gFunc|min()] or 
33370 5b 6d 69 6e 41 67 67 46 75 6e 63 7c 6d 61 78 28  [minAggFunc|max(
33380 29 5d 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  )] aggregate fun
33390 63 74 69 6f 6e 73 20 0a 61 72 65 20 75 73 65 64  ctions .are used
333a0 20 69 6e 20 61 6e 20 61 67 67 72 65 67 61 74 65   in an aggregate
333b0 20 71 75 65 72 79 2c 20 61 6c 6c 20 62 61 72 65   query, all bare
333c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
333d0 72 65 73 75 6c 74 20 73 65 74 20 0a 74 61 6b 65  result set .take
333e0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
333f0 20 69 6e 70 75 74 0a 72 6f 77 20 77 68 69 63 68   input.row which
33400 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 73 20 74   also contains t
33410 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 72 20 6d 61  he minimum or ma
33420 78 69 6d 75 6d 2e 20 20 53 6f 20 69 6e 20 74 68  ximum.  So in th
33430 65 20 71 75 65 72 79 0a 61 62 6f 76 65 2c 20 74  e query.above, t
33440 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
33450 22 62 22 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  "b" column in th
33460 65 20 6f 75 74 70 75 74 20 77 69 6c 6c 20 62 65  e output will be
33470 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 74 68   the value of.th
33480 65 20 22 62 22 20 63 6f 6c 75 6d 6e 20 69 6e 20  e "b" column in 
33490 74 68 65 20 69 6e 70 75 74 20 72 6f 77 20 74 68  the input row th
334a0 61 74 20 68 61 73 20 74 68 65 20 6c 61 72 67 65  at has the large
334b0 73 74 20 22 63 22 20 76 61 6c 75 65 2e 0a 54 68  st "c" value..Th
334c0 65 72 65 20 69 73 20 73 74 69 6c 6c 20 61 6e 20  ere is still an 
334d0 61 6d 62 69 67 75 69 74 79 20 69 66 20 74 77 6f  ambiguity if two
334e0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
334f0 69 6e 70 75 74 20 72 6f 77 73 20 68 61 76 65 20  input rows have 
33500 74 68 65 0a 73 61 6d 65 20 6d 69 6e 69 6d 75 6d  the.same minimum
33510 20 6f 72 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75   or maximum valu
33520 65 20 6f 72 20 69 66 20 74 68 65 20 71 75 65 72  e or if the quer
33530 79 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20  y contains more 
33540 74 68 61 6e 20 6f 6e 65 0a 6d 69 6e 28 29 20 61  than one.min() a
33550 6e 64 2f 6f 72 20 6d 61 78 28 29 20 61 67 67 72  nd/or max() aggr
33560 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 20  egate function. 
33570 4f 6e 6c 79 20 74 68 65 20 62 75 69 6c 74 2d 69  Only the built-i
33580 6e 20 5b 6d 69 6e 41 67 67 46 75 6e 63 7c 6d 69  n [minAggFunc|mi
33590 6e 28 29 5d 20 0a 61 6e 64 20 5b 6d 61 78 41 67  n()] .and [maxAg
335a0 67 46 75 6e 63 7c 6d 61 78 28 29 5d 20 66 75 6e  gFunc|max()] fun
335b0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 74 68 69 73  ctions work this
335c0 20 77 61 79 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 3c   way..</p>..<p><
335d0 62 3e 34 2e 20 52 65 6d 6f 76 61 6c 20 6f 66 20  b>4. Removal of 
335e0 64 75 70 6c 69 63 61 74 65 20 72 6f 77 73 20 28  duplicate rows (
335f0 44 49 53 54 49 4e 43 54 20 70 72 6f 63 65 73 73  DISTINCT process
33600 69 6e 67 29 2e 3c 2f 62 3e 0a 3c 74 63 6c 3e 68  ing).</b>.<tcl>h
33610 64 5f 66 72 61 67 6d 65 6e 74 20 64 69 73 74 69  d_fragment disti
33620 6e 63 74 3c 2f 74 63 6c 3e 0a 3c 74 63 6c 3e 68  nct</tcl>.<tcl>h
33630 64 5f 6b 65 79 77 6f 72 64 73 20 7b 44 49 53 54  d_keywords {DIST
33640 49 4e 43 54 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e  INCT}</tcl>..<p>
33650 5e 4f 6e 65 20 6f 66 20 74 68 65 20 41 4c 4c 20  ^One of the ALL 
33660 6f 72 20 44 49 53 54 49 4e 43 54 20 6b 65 79 77  or DISTINCT keyw
33670 6f 72 64 73 20 6d 61 79 20 66 6f 6c 6c 6f 77 20  ords may follow 
33680 74 68 65 20 53 45 4c 45 43 54 20 6b 65 79 77 6f  the SELECT keywo
33690 72 64 20 69 6e 20 61 20 0a 73 69 6d 70 6c 65 20  rd in a .simple 
336a0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
336b0 2e 20 5e 49 66 20 74 68 65 20 73 69 6d 70 6c 65  . ^If the simple
336c0 20 53 45 4c 45 43 54 20 69 73 20 61 20 53 45 4c   SELECT is a SEL
336d0 45 43 54 20 41 4c 4c 2c 20 74 68 65 6e 20 74 68  ECT ALL, then th
336e0 65 0a 65 6e 74 69 72 65 20 73 65 74 20 6f 66 20  e.entire set of 
336f0 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 20  result rows are 
33700 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
33710 53 45 4c 45 43 54 2e 20 5e 49 66 20 6e 65 69 74  SELECT. ^If neit
33720 68 65 72 20 41 4c 4c 20 6f 72 0a 44 49 53 54 49  her ALL or.DISTI
33730 4e 43 54 20 61 72 65 20 70 72 65 73 65 6e 74 2c  NCT are present,
33740 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
33750 6f 72 20 69 73 20 61 73 20 69 66 20 41 4c 4c 20  or is as if ALL 
33760 77 65 72 65 20 73 70 65 63 69 66 69 65 64 2e 20  were specified. 
33770 0a 5e 49 66 20 74 68 65 20 73 69 6d 70 6c 65 20  .^If the simple 
33780 53 45 4c 45 43 54 20 69 73 20 61 20 53 45 4c 45  SELECT is a SELE
33790 43 54 20 44 49 53 54 49 4e 43 54 2c 20 74 68 65  CT DISTINCT, the
337a0 6e 20 64 75 70 6c 69 63 61 74 65 20 72 6f 77 73  n duplicate rows
337b0 20 61 72 65 20 72 65 6d 6f 76 65 64 0a 66 72 6f   are removed.fro
337c0 6d 20 74 68 65 20 73 65 74 20 6f 66 20 72 65 73  m the set of res
337d0 75 6c 74 20 72 6f 77 73 20 62 65 66 6f 72 65 20  ult rows before 
337e0 69 74 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  it is returned. 
337f0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
33800 73 20 6f 66 0a 64 65 74 65 63 74 69 6e 67 20 64  s of.detecting d
33810 75 70 6c 69 63 61 74 65 20 72 6f 77 73 2c 20 74  uplicate rows, t
33820 77 6f 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 61  wo NULL values a
33830 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  re considered to
33840 20 62 65 20 65 71 75 61 6c 2e 20 5e 54 68 65 0a   be equal. ^The.
33850 5b 68 6f 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  [how collation i
33860 73 20 64 65 74 65 72 6d 69 6e 65 64 7c 75 73 75  s determined|usu
33870 61 6c 20 72 75 6c 65 73 5d 20 61 70 70 6c 79 20  al rules] apply 
33880 66 6f 72 20 73 65 6c 65 63 74 69 6e 67 20 61 20  for selecting a 
33890 63 6f 6c 6c 61 74 69 6f 6e 0a 73 65 71 75 65 6e  collation.sequen
338a0 63 65 20 74 6f 20 63 6f 6d 70 61 72 65 20 74 65  ce to compare te
338b0 78 74 20 76 61 6c 75 65 73 2e 0a 0a 3c 74 63 6c  xt values...<tcl
338c0 3e 0a 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f  >.hd_fragment co
338d0 6d 70 6f 75 6e 64 20 7b 63 6f 6d 70 6f 75 6e 64  mpound {compound
338e0 20 73 65 6c 65 63 74 7d 20 7b 63 6f 6d 70 6f 75   select} {compou
338f0 6e 64 20 71 75 65 72 79 7d 20 7b 63 6f 6d 70 6f  nd query} {compo
33900 75 6e 64 20 53 45 4c 45 43 54 7d 20 7b 63 6f 6d  und SELECT} {com
33910 70 6f 75 6e 64 20 53 45 4c 45 43 54 73 7d 0a 3c  pound SELECTs}.<
33920 2f 74 63 6c 3e 0a 3c 68 33 3e 43 6f 6d 70 6f 75  /tcl>.<h3>Compou
33930 6e 64 20 53 65 6c 65 63 74 20 53 74 61 74 65 6d  nd Select Statem
33940 65 6e 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 77  ents</h3>..<p>Tw
33950 6f 20 6f 72 20 6d 6f 72 65 20 5b 73 69 6d 70 6c  o or more [simpl
33960 65 20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d  e SELECT] statem
33970 65 6e 74 73 20 6d 61 79 20 62 65 20 63 6f 6e 6e  ents may be conn
33980 65 63 74 65 64 20 74 6f 67 65 74 68 65 72 20 74  ected together t
33990 6f 20 66 6f 72 6d 0a 61 20 63 6f 6d 70 6f 75 6e  o form.a compoun
339a0 64 20 53 45 4c 45 43 54 20 75 73 69 6e 67 20 74  d SELECT using t
339b0 68 65 20 55 4e 49 4f 4e 2c 20 55 4e 49 4f 4e 20  he UNION, UNION 
339c0 41 4c 4c 2c 20 49 4e 54 45 52 53 45 43 54 20 6f  ALL, INTERSECT o
339d0 72 20 45 58 43 45 50 54 20 6f 70 65 72 61 74 6f  r EXCEPT operato
339e0 72 2c 0a 61 73 20 73 68 6f 77 6e 20 62 79 20 74  r,.as shown by t
339f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 69 61  he following dia
33a00 67 72 61 6d 3a 0a 0a 3c 74 63 6c 3e 0a 52 65 63  gram:..<tcl>.Rec
33a10 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
33a20 72 61 6d 20 63 6f 6d 70 6f 75 6e 64 2d 73 65 6c  ram compound-sel
33a30 65 63 74 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a  ect-stmt.</tcl>.
33a40 0a 3c 70 3e 5e 49 6e 20 61 20 63 6f 6d 70 6f 75  .<p>^In a compou
33a50 6e 64 20 53 45 4c 45 43 54 2c 20 61 6c 6c 20 74  nd SELECT, all t
33a60 68 65 20 63 6f 6e 73 74 69 74 75 65 6e 74 20 53  he constituent S
33a70 45 4c 45 43 54 73 20 6d 75 73 74 20 72 65 74 75  ELECTs must retu
33a80 72 6e 20 74 68 65 20 73 61 6d 65 20 0a 6e 75 6d  rn the same .num
33a90 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
33aa0 6c 75 6d 6e 73 2e 20 5e 41 73 20 74 68 65 20 63  lumns. ^As the c
33ab0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 63  omponents of a c
33ac0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 6d  ompound SELECT m
33ad0 75 73 74 0a 62 65 20 73 69 6d 70 6c 65 20 53 45  ust.be simple SE
33ae0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c  LECT statements,
33af0 20 74 68 65 79 20 6d 61 79 20 6e 6f 74 20 63 6f   they may not co
33b00 6e 74 61 69 6e 20 5b 4f 52 44 45 52 20 42 59 5d  ntain [ORDER BY]
33b10 20 6f 72 20 5b 4c 49 4d 49 54 5d 20 63 6c 61 75   or [LIMIT] clau
33b20 73 65 73 2e 0a 5e 5b 4f 52 44 45 52 20 42 59 5d  ses..^[ORDER BY]
33b30 20 61 6e 64 20 5b 4c 49 4d 49 54 5d 20 63 6c 61   and [LIMIT] cla
33b40 75 73 65 73 20 6d 61 79 20 6f 6e 6c 79 20 6f 63  uses may only oc
33b50 63 75 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f  cur at the end o
33b60 66 20 74 68 65 20 65 6e 74 69 72 65 20 63 6f 6d  f the entire com
33b70 70 6f 75 6e 64 0a 53 45 4c 45 43 54 2c 20 61 6e  pound.SELECT, an
33b80 64 20 74 68 65 6e 20 6f 6e 6c 79 20 69 66 20 74  d then only if t
33b90 68 65 20 66 69 6e 61 6c 20 65 6c 65 6d 65 6e 74  he final element
33ba0 20 6f 66 20 74 68 65 20 63 6f 6d 70 6f 75 6e 64   of the compound
33bb0 20 69 73 20 6e 6f 74 20 61 20 5b 56 41 4c 55 45   is not a [VALUE
33bc0 53 5d 20 63 6c 61 75 73 65 2e 0a 0a 3c 70 3e 5e  S] clause...<p>^
33bd0 41 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  A compound SELEC
33be0 54 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  T created using 
33bf0 55 4e 49 4f 4e 20 41 4c 4c 20 6f 70 65 72 61 74  UNION ALL operat
33c00 6f 72 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 74  or returns all t
33c10 68 65 20 72 6f 77 73 0a 66 72 6f 6d 20 74 68 65  he rows.from the
33c20 20 53 45 4c 45 43 54 20 74 6f 20 74 68 65 20 6c   SELECT to the l
33c30 65 66 74 20 6f 66 20 74 68 65 20 55 4e 49 4f 4e  eft of the UNION
33c40 20 41 4c 4c 20 6f 70 65 72 61 74 6f 72 2c 20 61   ALL operator, a
33c50 6e 64 20 61 6c 6c 20 74 68 65 20 72 6f 77 73 0a  nd all the rows.
33c60 66 72 6f 6d 20 74 68 65 20 53 45 4c 45 43 54 20  from the SELECT 
33c70 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20  to the right of 
33c80 69 74 2e 20 5e 54 68 65 20 55 4e 49 4f 4e 20 6f  it. ^The UNION o
33c90 70 65 72 61 74 6f 72 20 77 6f 72 6b 73 20 74 68  perator works th
33ca0 65 20 73 61 6d 65 20 77 61 79 20 61 73 0a 55 4e  e same way as.UN
33cb0 49 4f 4e 20 41 4c 4c 2c 20 65 78 63 65 70 74 20  ION ALL, except 
33cc0 74 68 61 74 20 64 75 70 6c 69 63 61 74 65 20 72  that duplicate r
33cd0 6f 77 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20  ows are removed 
33ce0 66 72 6f 6d 20 74 68 65 20 66 69 6e 61 6c 20 72  from the final r
33cf0 65 73 75 6c 74 20 73 65 74 2e 0a 5e 54 68 65 20  esult set..^The 
33d00 49 4e 54 45 52 53 45 43 54 20 6f 70 65 72 61 74  INTERSECT operat
33d10 6f 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  or returns the i
33d20 6e 74 65 72 73 65 63 74 69 6f 6e 20 6f 66 20 74  ntersection of t
33d30 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68  he results of th
33d40 65 20 6c 65 66 74 20 61 6e 64 0a 72 69 67 68 74  e left and.right
33d50 20 53 45 4c 45 43 54 73 2e 20 20 5e 54 68 65 20   SELECTs.  ^The 
33d60 45 58 43 45 50 54 20 6f 70 65 72 61 74 6f 72 20  EXCEPT operator 
33d70 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 73  returns the subs
33d80 65 74 20 6f 66 20 72 6f 77 73 20 72 65 74 75 72  et of rows retur
33d90 6e 65 64 20 62 79 20 74 68 65 0a 6c 65 66 74 20  ned by the.left 
33da0 53 45 4c 45 43 54 20 74 68 61 74 20 61 72 65 20  SELECT that are 
33db0 6e 6f 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 65  not also returne
33dc0 64 20 62 79 20 74 68 65 20 72 69 67 68 74 2d 68  d by the right-h
33dd0 61 6e 64 20 53 45 4c 45 43 54 2e 20 5e 44 75 70  and SELECT. ^Dup
33de0 6c 69 63 61 74 65 0a 72 6f 77 73 20 61 72 65 20  licate.rows are 
33df0 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74 68 65  removed from the
33e00 20 72 65 73 75 6c 74 73 20 6f 66 20 49 4e 54 45   results of INTE
33e10 52 53 45 43 54 20 61 6e 64 20 45 58 43 45 50 54  RSECT and EXCEPT
33e20 20 6f 70 65 72 61 74 6f 72 73 20 62 65 66 6f 72   operators befor
33e30 65 20 74 68 65 0a 72 65 73 75 6c 74 20 73 65 74  e the.result set
33e40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 0a 3c   is returned...<
33e50 70 3e 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  p>^For the purpo
33e60 73 65 73 20 6f 66 20 64 65 74 65 72 6d 69 6e 69  ses of determini
33e70 6e 67 20 64 75 70 6c 69 63 61 74 65 20 72 6f 77  ng duplicate row
33e80 73 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  s for the result
33e90 73 20 6f 66 20 63 6f 6d 70 6f 75 6e 64 0a 53 45  s of compound.SE
33ea0 4c 45 43 54 20 6f 70 65 72 61 74 6f 72 73 2c 20  LECT operators, 
33eb0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 61 72 65 20  NULL values are 
33ec0 63 6f 6e 73 69 64 65 72 65 64 20 65 71 75 61 6c  considered equal
33ed0 20 74 6f 20 6f 74 68 65 72 20 4e 55 4c 4c 20 76   to other NULL v
33ee0 61 6c 75 65 73 20 61 6e 64 0a 64 69 73 74 69 6e  alues and.distin
33ef0 63 74 20 66 72 6f 6d 20 61 6c 6c 20 6e 6f 6e 2d  ct from all non-
33f00 4e 55 4c 4c 20 76 61 6c 75 65 73 2e 20 5e 54 68  NULL values. ^Th
33f10 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
33f20 65 6e 63 65 20 75 73 65 64 20 74 6f 20 63 6f 6d  ence used to com
33f30 70 61 72 65 20 0a 74 77 6f 20 74 65 78 74 20 76  pare .two text v
33f40 61 6c 75 65 73 20 69 73 20 64 65 74 65 72 6d 69  alues is determi
33f50 6e 65 64 20 61 73 20 69 66 20 74 68 65 20 63 6f  ned as if the co
33f60 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20 6c 65 66  lumns of the lef
33f70 74 20 61 6e 64 20 72 69 67 68 74 2d 68 61 6e 64  t and right-hand
33f80 0a 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e  .SELECT statemen
33f90 74 73 20 77 65 72 65 20 74 68 65 20 6c 65 66 74  ts were the left
33fa0 20 61 6e 64 20 72 69 67 68 74 2d 68 61 6e 64 20   and right-hand 
33fb0 6f 70 65 72 61 6e 64 73 20 6f 66 20 74 68 65 20  operands of the 
33fc0 65 71 75 61 6c 73 20 28 3d 29 0a 6f 70 65 72 61  equals (=).opera
33fd0 74 6f 72 2c 20 65 78 63 65 70 74 20 74 68 61 74  tor, except that
33fe0 20 67 72 65 61 74 65 72 20 70 72 65 63 65 64 65   greater precede
33ff0 6e 63 65 20 69 73 20 6e 6f 74 20 61 73 73 69 67  nce is not assig
34000 6e 65 64 20 74 6f 20 61 20 63 6f 6c 6c 61 74 69  ned to a collati
34010 6f 6e 20 0a 73 65 71 75 65 6e 63 65 20 73 70 65  on .sequence spe
34020 63 69 66 69 65 64 20 77 69 74 68 20 74 68 65 20  cified with the 
34030 70 6f 73 74 66 69 78 20 43 4f 4c 4c 41 54 45 20  postfix COLLATE 
34040 6f 70 65 72 61 74 6f 72 2e 20 5e 4e 6f 20 61 66  operator. ^No af
34050 66 69 6e 69 74 79 0a 74 72 61 6e 73 66 6f 72 6d  finity.transform
34060 61 74 69 6f 6e 73 20 61 72 65 20 61 70 70 6c 69  ations are appli
34070 65 64 20 74 6f 20 61 6e 79 20 76 61 6c 75 65 73  ed to any values
34080 20 77 68 65 6e 20 63 6f 6d 70 61 72 69 6e 67 20   when comparing 
34090 72 6f 77 73 20 61 73 20 70 61 72 74 20 6f 66 20  rows as part of 
340a0 61 0a 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a.compound SELEC
340b0 54 2e 20 0a 0a 3c 70 3e 5e 28 57 68 65 6e 20 74  T. ..<p>^(When t
340c0 68 72 65 65 20 6f 72 20 6d 6f 72 65 20 73 69 6d  hree or more sim
340d0 70 6c 65 20 53 45 4c 45 43 54 73 20 61 72 65 20  ple SELECTs are 
340e0 63 6f 6e 6e 65 63 74 65 64 20 69 6e 74 6f 20 61  connected into a
340f0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
34100 2c 0a 74 68 65 79 20 67 72 6f 75 70 20 66 72 6f  ,.they group fro
34110 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74 2e  m left to right.
34120 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
34130 20 69 66 20 22 41 22 2c 20 22 42 22 20 61 6e 64   if "A", "B" and
34140 20 22 43 22 20 61 72 65 20 61 6c 6c 0a 73 69 6d   "C" are all.sim
34150 70 6c 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  ple SELECT state
34160 6d 65 6e 74 73 2c 20 28 41 20 6f 70 20 42 20 6f  ments, (A op B o
34170 70 20 43 29 20 69 73 20 70 72 6f 63 65 73 73 65  p C) is processe
34180 64 20 61 73 20 28 28 41 20 6f 70 20 42 29 20 6f  d as ((A op B) o
34190 70 20 43 29 2e 29 5e 0a 0a 3c 2f 70 3e 0a 0a 3c  p C).)^..</p>..<
341a0 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
341b0 6f 72 64 65 72 62 79 20 7b 6f 72 64 65 72 20 62  orderby {order b
341c0 79 7d 20 7b 4f 52 44 45 52 20 42 59 7d 3c 2f 74  y} {ORDER BY}</t
341d0 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 4f 52 44 45  cl>.<h3>The ORDE
341e0 52 20 42 59 20 63 6c 61 75 73 65 3c 2f 68 33 3e  R BY clause</h3>
341f0 0a 0a 3c 70 3e 49 66 20 61 20 53 45 4c 45 43 54  ..<p>If a SELECT
34200 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
34210 72 65 74 75 72 6e 73 20 6d 6f 72 65 20 74 68 61  returns more tha
34220 6e 20 6f 6e 65 20 72 6f 77 20 64 6f 65 73 20 6e  n one row does n
34230 6f 74 20 68 61 76 65 20 61 6e 0a 4f 52 44 45 52  ot have an.ORDER
34240 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 20   BY clause, the 
34250 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 20 74  order in which t
34260 68 65 20 72 6f 77 73 20 61 72 65 20 72 65 74 75  he rows are retu
34270 72 6e 65 64 20 69 73 20 75 6e 64 65 66 69 6e 65  rned is undefine
34280 64 2e 0a 4f 72 2c 20 69 66 20 61 20 53 45 4c 45  d..Or, if a SELE
34290 43 54 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  CT statement doe
342a0 73 20 68 61 76 65 20 61 6e 20 4f 52 44 45 52 20  s have an ORDER 
342b0 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20  BY clause, then 
342c0 74 68 65 20 6c 69 73 74 20 6f 66 0a 65 78 70 72  the list of.expr
342d0 65 73 73 69 6f 6e 73 20 61 74 74 61 63 68 65 64  essions attached
342e0 20 74 6f 20 74 68 65 20 4f 52 44 45 52 20 42 59   to the ORDER BY
342f0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 6f   determine the o
34300 72 64 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f  rder in which ro
34310 77 73 0a 61 72 65 20 72 65 74 75 72 6e 65 64 20  ws.are returned 
34320 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 0a 3c 70  to the user...<p
34330 3e 0a 5e 49 6e 20 61 20 5b 63 6f 6d 70 6f 75 6e  >.^In a [compoun
34340 64 20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d  d SELECT] statem
34350 65 6e 74 2c 20 6f 6e 6c 79 20 74 68 65 20 6c 61  ent, only the la
34360 73 74 20 6f 72 20 72 69 67 68 74 2d 6d 6f 73 74  st or right-most
34370 20 5b 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 5d   [simple SELECT]
34380 0a 6d 61 79 20 68 61 76 65 20 61 6e 20 4f 52 44  .may have an ORD
34390 45 52 20 42 59 20 63 6c 61 75 73 65 2e 20 5e 54  ER BY clause. ^T
343a0 68 61 74 20 4f 52 44 45 52 20 42 59 20 63 6c 61  hat ORDER BY cla
343b0 75 73 65 20 77 69 6c 6c 20 61 70 70 6c 79 20 61  use will apply a
343c0 63 72 6f 73 73 20 61 6c 6c 20 65 6c 65 6d 65 6e  cross all elemen
343d0 74 73 20 6f 66 0a 74 68 65 20 63 6f 6d 70 6f 75  ts of.the compou
343e0 6e 64 2e 20 5e 49 66 20 74 68 65 20 72 69 67 68  nd. ^If the righ
343f0 74 2d 6d 6f 73 74 20 65 6c 65 6d 65 6e 74 20 6f  t-most element o
34400 66 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45  f a [compound SE
34410 4c 45 43 54 5d 20 69 73 20 61 20 5b 56 41 4c 55  LECT] is a [VALU
34420 45 53 5d 20 63 6c 61 75 73 65 2c 0a 74 68 65 6e  ES] clause,.then
34430 20 6e 6f 20 4f 52 44 45 52 20 42 59 20 63 6c 61   no ORDER BY cla
34440 75 73 65 20 69 73 20 61 6c 6c 6f 77 65 64 20 6f  use is allowed o
34450 6e 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  n that statement
34460 2e 0a 0a 0a 3c 70 3e 5e 52 6f 77 73 20 61 72 65  ....<p>^Rows are
34470 20 66 69 72 73 74 20 73 6f 72 74 65 64 20 62 61   first sorted ba
34480 73 65 64 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  sed on the resul
34490 74 73 20 6f 66 0a 65 76 61 6c 75 61 74 69 6e 67  ts of.evaluating
344a0 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 65   the left-most e
344b0 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74 68 65  xpression in the
344c0 20 4f 52 44 45 52 20 42 59 20 6c 69 73 74 2c 20   ORDER BY list, 
344d0 74 68 65 6e 20 74 69 65 73 20 61 72 65 20 62 72  then ties are br
344e0 6f 6b 65 6e 0a 62 79 20 65 76 61 6c 75 61 74 69  oken.by evaluati
344f0 6e 67 20 74 68 65 20 73 65 63 6f 6e 64 20 6c 65  ng the second le
34500 66 74 2d 6d 6f 73 74 20 65 78 70 72 65 73 73 69  ft-most expressi
34510 6f 6e 20 61 6e 64 20 73 6f 20 6f 6e 2e 20 54 68  on and so on. Th
34520 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
34530 0a 74 77 6f 20 72 6f 77 73 20 66 6f 72 20 77 68  .two rows for wh
34540 69 63 68 20 61 6c 6c 20 4f 52 44 45 52 20 42 59  ich all ORDER BY
34550 20 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76 61   expressions eva
34560 6c 75 61 74 65 20 74 6f 20 65 71 75 61 6c 20 76  luate to equal v
34570 61 6c 75 65 73 20 61 72 65 0a 72 65 74 75 72 6e  alues are.return
34580 65 64 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ed is undefined.
34590 20 5e 45 61 63 68 20 4f 52 44 45 52 20 42 59 20   ^Each ORDER BY 
345a0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 79 20 62  expression may b
345b0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  e optionally fol
345c0 6c 6f 77 65 64 0a 62 79 20 6f 6e 65 20 6f 66 20  lowed.by one of 
345d0 74 68 65 20 6b 65 79 77 6f 72 64 73 20 41 53 43  the keywords ASC
345e0 20 28 73 6d 61 6c 6c 65 72 20 76 61 6c 75 65 73   (smaller values
345f0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 66 69   are returned fi
34600 72 73 74 29 20 6f 72 20 44 45 53 43 20 28 6c 61  rst) or DESC (la
34610 72 67 65 72 0a 76 61 6c 75 65 73 20 61 72 65 20  rger.values are 
34620 72 65 74 75 72 6e 65 64 20 66 69 72 73 74 29 2e  returned first).
34630 20 5e 49 66 20 6e 65 69 74 68 65 72 20 41 53 43   ^If neither ASC
34640 20 6f 72 20 44 45 53 43 20 61 72 65 20 73 70 65   or DESC are spe
34650 63 69 66 69 65 64 2c 20 72 6f 77 73 0a 61 72 65  cified, rows.are
34660 20 73 6f 72 74 65 64 20 69 6e 20 61 73 63 65 6e   sorted in ascen
34670 64 69 6e 67 20 28 73 6d 61 6c 6c 65 72 20 76 61  ding (smaller va
34680 6c 75 65 73 20 66 69 72 73 74 29 20 6f 72 64 65  lues first) orde
34690 72 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 0a 3c  r by default...<
346a0 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
346b0 6e 75 6c 6c 73 6c 61 73 74 20 7b 4e 55 4c 4c 53  nullslast {NULLS
346c0 20 46 49 52 53 54 7d 20 7b 4e 55 4c 4c 53 20 4c   FIRST} {NULLS L
346d0 41 53 54 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 53 51  AST}</tcl>.<p>SQ
346e0 4c 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 4e  Lite considers N
346f0 55 4c 4c 20 76 61 6c 75 65 73 20 74 6f 20 62 65  ULL values to be
34700 20 73 6d 61 6c 6c 65 72 20 74 68 61 6e 20 61 6e   smaller than an
34710 79 20 6f 74 68 65 72 20 76 61 6c 75 65 73 0a 66  y other values.f
34720 6f 72 20 73 6f 72 74 69 6e 67 20 70 75 72 70 6f  or sorting purpo
34730 73 65 73 2e 20 20 48 65 6e 63 65 2c 20 4e 55 4c  ses.  Hence, NUL
34740 4c 73 20 6e 61 74 75 72 61 6c 6c 79 20 61 70 70  Ls naturally app
34750 65 61 72 20 61 74 20 74 68 65 20 62 65 67 69 6e  ear at the begin
34760 6e 69 6e 67 0a 6f 66 20 61 6e 20 41 53 43 20 6f  ning.of an ASC o
34770 72 64 65 72 2d 62 79 20 61 6e 64 20 61 74 20 74  rder-by and at t
34780 68 65 20 65 6e 64 20 6f 66 20 61 20 44 45 53 43  he end of a DESC
34790 20 6f 72 64 65 72 2d 62 79 2e 20 20 54 68 69 73   order-by.  This
347a0 20 63 61 6e 20 62 65 20 63 68 61 6e 67 65 64 0a   can be changed.
347b0 75 73 69 6e 67 20 74 68 65 20 22 41 53 43 20 4e  using the "ASC N
347c0 55 4c 4c 53 20 4c 41 53 54 22 20 6f 72 20 22 44  ULLS LAST" or "D
347d0 45 53 43 20 4e 55 4c 4c 53 20 46 49 52 53 54 22  ESC NULLS FIRST"
347e0 20 73 79 6e 74 61 78 2e 0a 0a 3c 70 3e 45 61 63   syntax...<p>Eac
347f0 68 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65  h ORDER BY expre
34800 73 73 69 6f 6e 20 69 73 20 70 72 6f 63 65 73 73  ssion is process
34810 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f  ed as follows:</
34820 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e  p>..<ol>.<li><p>
34830 5e 49 66 20 74 68 65 20 4f 52 44 45 52 20 42 59  ^If the ORDER BY
34840 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61   expression is a
34850 20 63 6f 6e 73 74 61 6e 74 20 69 6e 74 65 67 65   constant intege
34860 72 20 4b 20 74 68 65 6e 20 74 68 65 0a 65 78 70  r K then the.exp
34870 72 65 73 73 69 6f 6e 20 69 73 20 63 6f 6e 73 69  ression is consi
34880 64 65 72 65 64 20 61 6e 20 61 6c 69 61 73 20 66  dered an alias f
34890 6f 72 20 74 68 65 20 4b 2d 74 68 20 63 6f 6c 75  or the K-th colu
348a0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
348b0 20 73 65 74 0a 28 63 6f 6c 75 6d 6e 73 20 61 72   set.(columns ar
348c0 65 20 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20  e numbered from 
348d0 6c 65 66 74 20 74 6f 20 72 69 67 68 74 20 73 74  left to right st
348e0 61 72 74 69 6e 67 20 77 69 74 68 20 31 29 2e 0a  arting with 1)..
348f0 0a 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20  .<li><p>^If the 
34900 4f 52 44 45 52 20 42 59 20 65 78 70 72 65 73 73  ORDER BY express
34910 69 6f 6e 20 69 73 20 61 6e 20 69 64 65 6e 74 69  ion is an identi
34920 66 69 65 72 20 74 68 61 74 20 63 6f 72 72 65 73  fier that corres
34930 70 6f 6e 64 73 20 74 6f 0a 74 68 65 20 61 6c 69  ponds to.the ali
34940 61 73 20 6f 66 20 6f 6e 65 20 6f 66 20 74 68 65  as of one of the
34950 20 6f 75 74 70 75 74 20 63 6f 6c 75 6d 6e 73 2c   output columns,
34960 20 74 68 65 6e 20 74 68 65 20 65 78 70 72 65 73   then the expres
34970 73 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  sion is consider
34980 65 64 0a 61 6e 20 61 6c 69 61 73 20 66 6f 72 20  ed.an alias for 
34990 74 68 61 74 20 63 6f 6c 75 6d 6e 2e 0a 0a 3c 6c  that column...<l
349a0 69 3e 3c 70 3e 5e 4f 74 68 65 72 77 69 73 65 2c  i><p>^Otherwise,
349b0 20 69 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   if the ORDER BY
349c0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61   expression is a
349d0 6e 79 20 6f 74 68 65 72 20 65 78 70 72 65 73 73  ny other express
349e0 69 6f 6e 2c 20 69 74 20 0a 69 73 20 65 76 61 6c  ion, it .is eval
349f0 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 72 65  uated and the re
34a00 74 75 72 6e 65 64 20 76 61 6c 75 65 20 75 73 65  turned value use
34a10 64 20 74 6f 20 6f 72 64 65 72 20 74 68 65 20 6f  d to order the o
34a20 75 74 70 75 74 20 72 6f 77 73 2e 20 5e 49 66 0a  utput rows. ^If.
34a30 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
34a40 6d 65 6e 74 20 69 73 20 61 20 73 69 6d 70 6c 65  ment is a simple
34a50 20 53 45 4c 45 43 54 2c 20 74 68 65 6e 20 61 6e   SELECT, then an
34a60 20 4f 52 44 45 52 20 42 59 20 6d 61 79 20 63 6f   ORDER BY may co
34a70 6e 74 61 69 6e 20 61 6e 79 0a 61 72 62 69 74 72  ntain any.arbitr
34a80 61 72 79 20 65 78 70 72 65 73 73 69 6f 6e 73 2e  ary expressions.
34a90 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68   ^However, if th
34aa0 65 20 53 45 4c 45 43 54 20 69 73 20 61 20 63 6f  e SELECT is a co
34ab0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 2c 20 74  mpound SELECT, t
34ac0 68 65 6e 0a 4f 52 44 45 52 20 42 59 20 65 78 70  hen.ORDER BY exp
34ad0 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
34ae0 65 20 6e 6f 74 20 61 6c 69 61 73 65 73 20 74 6f  e not aliases to
34af0 20 6f 75 74 70 75 74 20 63 6f 6c 75 6d 6e 73 20   output columns 
34b00 6d 75 73 74 20 62 65 20 65 78 61 63 74 6c 79 0a  must be exactly.
34b10 74 68 65 20 73 61 6d 65 20 61 73 20 61 6e 20 65  the same as an e
34b20 78 70 72 65 73 73 69 6f 6e 20 75 73 65 64 20 61  xpression used a
34b30 73 20 61 6e 20 6f 75 74 70 75 74 20 63 6f 6c 75  s an output colu
34b40 6d 6e 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 5e 46  mn..</ol>..<p>^F
34b50 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
34b60 6f 66 20 73 6f 72 74 69 6e 67 20 72 6f 77 73 2c  of sorting rows,
34b70 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f 6d 70   values are comp
34b80 61 72 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65  ared in the same
34b90 20 77 61 79 0a 61 73 20 66 6f 72 20 5b 63 6f 6d   way.as for [com
34ba0 70 61 72 69 73 6f 6e 20 65 78 70 72 65 73 73 69  parison expressi
34bb0 6f 6e 73 5d 2e 20 54 68 65 20 63 6f 6c 6c 61 74  ons]. The collat
34bc0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 75 73 65  ion sequence use
34bd0 64 20 74 6f 20 63 6f 6d 70 61 72 65 0a 74 77 6f  d to compare.two
34be0 20 74 65 78 74 20 76 61 6c 75 65 73 20 69 73 20   text values is 
34bf0 64 65 74 65 72 6d 69 6e 65 64 20 61 73 20 66 6f  determined as fo
34c00 6c 6c 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c  llows:..<ol>.  <
34c10 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20 4f 52  li><p>^If the OR
34c20 44 45 52 20 42 59 20 65 78 70 72 65 73 73 69 6f  DER BY expressio
34c30 6e 20 69 73 20 61 73 73 69 67 6e 65 64 20 61 20  n is assigned a 
34c40 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
34c50 63 65 20 75 73 69 6e 67 0a 20 20 74 68 65 20 70  ce using.  the p
34c60 6f 73 74 66 69 78 20 5b 43 4f 4c 4c 41 54 45 20  ostfix [COLLATE 
34c70 6f 70 65 72 61 74 6f 72 5d 2c 20 74 68 65 6e 20  operator], then 
34c80 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
34c90 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34ca0 20 69 73 0a 20 20 75 73 65 64 2e 0a 20 20 3c 6c   is.  used..  <l
34cb0 69 3e 3c 70 3e 5e 4f 74 68 65 72 77 69 73 65 2c  i><p>^Otherwise,
34cc0 20 69 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   if the ORDER BY
34cd0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61   expression is a
34ce0 6e 20 61 6c 69 61 73 20 74 6f 20 61 6e 20 65 78  n alias to an ex
34cf0 70 72 65 73 73 69 6f 6e 0a 20 20 74 68 61 74 20  pression.  that 
34d00 68 61 73 20 62 65 65 6e 20 61 73 73 69 67 6e 65  has been assigne
34d10 64 20 61 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  d a collation se
34d20 71 75 65 6e 63 65 20 75 73 69 6e 67 20 74 68 65  quence using the
34d30 20 70 6f 73 74 66 69 78 20 0a 20 20 5b 43 4f 4c   postfix .  [COL
34d40 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 5d 2c 20  LATE operator], 
34d50 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
34d60 6f 6e 20 73 65 71 75 65 6e 63 65 20 61 73 73 69  on sequence assi
34d70 67 6e 65 64 20 74 6f 20 74 68 65 20 61 6c 69 61  gned to the alia
34d80 73 65 64 0a 20 20 65 78 70 72 65 73 73 69 6f 6e  sed.  expression
34d90 20 69 73 20 75 73 65 64 2e 0a 20 20 3c 6c 69 3e   is used..  <li>
34da0 3c 70 3e 5e 4f 74 68 65 72 77 69 73 65 2c 20 69  <p>^Otherwise, i
34db0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 65  f the ORDER BY e
34dc0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 20 63  xpression is a c
34dd0 6f 6c 75 6d 6e 20 6f 72 20 61 6e 20 61 6c 69 61  olumn or an alia
34de0 73 20 6f 66 0a 20 20 61 6e 20 65 78 70 72 65 73  s of.  an expres
34df0 73 69 6f 6e 20 74 68 61 74 20 69 73 20 61 20 63  sion that is a c
34e00 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
34e10 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
34e20 6e 20 73 65 71 75 65 6e 63 65 20 66 6f 72 0a 20  n sequence for. 
34e30 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
34e40 73 65 64 2e 20 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  sed. .  <li><p>^
34e50 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 5b  Otherwise, the [
34e60 42 49 4e 41 52 59 5d 20 63 6f 6c 6c 61 74 69 6f  BINARY] collatio
34e70 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 75 73  n sequence is us
34e80 65 64 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 49 6e  ed..</ol>..<p>In
34e90 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c   a [compound SEL
34ea0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2c 20  ECT] statement, 
34eb0 61 6c 6c 20 4f 52 44 45 52 20 42 59 20 65 78 70  all ORDER BY exp
34ec0 72 65 73 73 69 6f 6e 73 20 61 72 65 20 68 61 6e  ressions are han
34ed0 64 6c 65 64 0a 61 73 20 61 6c 69 61 73 65 73 20  dled.as aliases 
34ee0 66 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 72  for one of the r
34ef0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 6f 66  esult columns of
34f00 20 74 68 65 20 63 6f 6d 70 6f 75 6e 64 2e 0a 5e   the compound..^
34f10 28 49 66 20 61 6e 20 4f 52 44 45 52 20 42 59 20  (If an ORDER BY 
34f20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 6e 6f  expression is no
34f30 74 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6c 69  t an integer ali
34f40 61 73 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  as, then SQLite 
34f50 73 65 61 72 63 68 65 73 0a 74 68 65 20 6c 65 66  searches.the lef
34f60 74 2d 6d 6f 73 74 20 53 45 4c 45 43 54 20 69 6e  t-most SELECT in
34f70 20 74 68 65 20 63 6f 6d 70 6f 75 6e 64 20 66 6f   the compound fo
34f80 72 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  r a result colum
34f90 6e 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 65  n that matches e
34fa0 69 74 68 65 72 0a 74 68 65 20 73 65 63 6f 6e 64  ither.the second
34fb0 20 6f 72 20 74 68 69 72 64 20 72 75 6c 65 73 20   or third rules 
34fc0 61 62 6f 76 65 2e 20 49 66 20 61 20 6d 61 74 63  above. If a matc
34fd0 68 20 69 73 20 66 6f 75 6e 64 2c 20 74 68 65 20  h is found, the 
34fe0 73 65 61 72 63 68 20 73 74 6f 70 73 20 61 6e 64  search stops and
34ff0 0a 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20  .the expression 
35000 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 6e  is handled as an
35010 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
35020 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 74 68 61  esult column tha
35030 74 20 69 74 20 68 61 73 20 62 65 65 6e 0a 6d 61  t it has been.ma
35040 74 63 68 65 64 20 61 67 61 69 6e 73 74 2e 20 4f  tched against. O
35050 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 6e 65  therwise, the ne
35060 78 74 20 53 45 4c 45 43 54 20 74 6f 20 74 68 65  xt SELECT to the
35070 20 72 69 67 68 74 20 69 73 20 74 72 69 65 64 2c   right is tried,
35080 20 61 6e 64 20 73 6f 20 6f 6e 2e 29 5e 0a 5e 49   and so on.)^.^I
35090 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 65 78  f no matching ex
350a0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
350b0 66 6f 75 6e 64 20 69 6e 20 74 68 65 20 72 65 73  found in the res
350c0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  ult columns of a
350d0 6e 79 0a 63 6f 6e 73 74 69 74 75 65 6e 74 20 53  ny.constituent S
350e0 45 4c 45 43 54 2c 20 69 74 20 69 73 20 61 6e 20  ELECT, it is an 
350f0 65 72 72 6f 72 2e 20 5e 45 61 63 68 20 74 65 72  error. ^Each ter
35100 6d 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  m of the ORDER B
35110 59 20 63 6c 61 75 73 65 20 69 73 0a 70 72 6f 63  Y clause is.proc
35120 65 73 73 65 64 20 73 65 70 61 72 61 74 65 6c 79  essed separately
35130 20 61 6e 64 20 6d 61 79 20 62 65 20 6d 61 74 63   and may be matc
35140 68 65 64 20 61 67 61 69 6e 73 74 20 72 65 73 75  hed against resu
35150 6c 74 20 63 6f 6c 75 6d 6e 73 20 66 72 6f 6d 20  lt columns from 
35160 64 69 66 66 65 72 65 6e 74 0a 53 45 4c 45 43 54  different.SELECT
35170 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
35180 68 65 20 63 6f 6d 70 6f 75 6e 64 2e 3c 2f 70 3e  he compound.</p>
35190 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
351a0 6e 74 20 6c 69 6d 69 74 6f 66 66 73 65 74 20 7b  nt limitoffset {
351b0 4c 49 4d 49 54 7d 20 7b 4f 46 46 53 45 54 7d 3c  LIMIT} {OFFSET}<
351c0 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 4c 49  /tcl>.<h3>The LI
351d0 4d 49 54 20 63 6c 61 75 73 65 3c 2f 68 33 3e 0a  MIT clause</h3>.
351e0 0a 3c 70 3e 5e 54 68 65 20 4c 49 4d 49 54 20 63  .<p>^The LIMIT c
351f0 6c 61 75 73 65 20 69 73 20 75 73 65 64 20 74 6f  lause is used to
35200 20 70 6c 61 63 65 20 61 6e 20 75 70 70 65 72 20   place an upper 
35210 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 6e 75 6d  bound on the num
35220 62 65 72 20 6f 66 20 72 6f 77 73 0a 72 65 74 75  ber of rows.retu
35230 72 6e 65 64 20 62 79 20 74 68 65 20 65 6e 74 69  rned by the enti
35240 72 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  re SELECT statem
35250 65 6e 74 2e 0a 0a 3c 70 3e 5e 49 6e 20 61 20 5b  ent...<p>^In a [
35260 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d  compound SELECT]
35270 2c 20 6f 6e 6c 79 20 74 68 65 0a 6c 61 73 74 20  , only the.last 
35280 6f 72 20 72 69 67 68 74 2d 6d 6f 73 74 20 5b 73  or right-most [s
35290 69 6d 70 6c 65 20 53 45 4c 45 43 54 5d 20 6d 61  imple SELECT] ma
352a0 79 20 63 6f 6e 74 61 69 6e 20 61 20 4c 49 4d 49  y contain a LIMI
352b0 54 20 63 6c 61 75 73 65 2e 20 20 0a 5e 49 6e 20  T clause.  .^In 
352c0 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45  a [compound SELE
352d0 43 54 5d 2c 20 0a 74 68 65 20 4c 49 4d 49 54 20  CT], .the LIMIT 
352e0 63 6c 61 75 73 65 20 61 70 70 6c 69 65 73 20 74  clause applies t
352f0 6f 20 74 68 65 20 65 6e 74 69 72 65 20 63 6f 6d  o the entire com
35300 70 6f 75 6e 64 2c 20 6e 6f 74 20 6a 75 73 74 20  pound, not just 
35310 74 68 65 20 66 69 6e 61 6c 20 53 45 4c 45 43 54  the final SELECT
35320 2e 0a 5e 49 66 20 74 68 65 20 72 69 67 68 74 2d  ..^If the right-
35330 6d 6f 73 74 20 5b 73 69 6d 70 6c 65 20 53 45 4c  most [simple SEL
35340 45 43 54 5d 20 69 73 20 61 20 5b 56 41 4c 55 45  ECT] is a [VALUE
35350 53 20 63 6c 61 75 73 65 5d 20 74 68 65 6e 20 6e  S clause] then n
35360 6f 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 0a 69  o LIMIT clause.i
35370 73 20 61 6c 6c 6f 77 65 64 2e 0a 0a 3c 70 3e 5e  s allowed...<p>^
35380 41 6e 79 20 73 63 61 6c 61 72 20 65 78 70 72 65  Any scalar expre
35390 73 73 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65  ssion may be use
353a0 64 20 69 6e 20 74 68 65 20 0a 4c 49 4d 49 54 20  d in the .LIMIT 
353b0 63 6c 61 75 73 65 2c 20 73 6f 20 6c 6f 6e 67 20  clause, so long 
353c0 61 73 20 69 74 20 65 76 61 6c 75 61 74 65 73 20  as it evaluates 
353d0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
353e0 20 61 20 76 61 6c 75 65 20 74 68 61 74 20 63 61   a value that ca
353f0 6e 20 62 65 0a 6c 6f 73 73 6c 65 73 73 6c 79 20  n be.losslessly 
35400 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20  converted to an 
35410 69 6e 74 65 67 65 72 2e 20 5e 49 66 20 74 68 65  integer. ^If the
35420 20 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c   expression eval
35430 75 61 74 65 73 20 74 6f 20 61 20 4e 55 4c 4c 20  uates to a NULL 
35440 0a 76 61 6c 75 65 20 6f 72 20 61 6e 79 20 6f 74  .value or any ot
35450 68 65 72 20 76 61 6c 75 65 20 74 68 61 74 20 63  her value that c
35460 61 6e 6e 6f 74 20 62 65 20 6c 6f 73 73 6c 65 73  annot be lossles
35470 73 6c 79 20 63 6f 6e 76 65 72 74 65 64 20 74 6f  sly converted to
35480 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 61 6e 0a   an integer, an.
35490 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
354a0 64 2e 20 5e 49 66 20 74 68 65 20 4c 49 4d 49 54  d. ^If the LIMIT
354b0 20 65 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c   expression eval
354c0 75 61 74 65 73 20 74 6f 20 61 20 6e 65 67 61 74  uates to a negat
354d0 69 76 65 20 76 61 6c 75 65 2c 0a 74 68 65 6e 20  ive value,.then 
354e0 74 68 65 72 65 20 69 73 20 6e 6f 20 75 70 70 65  there is no uppe
354f0 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 6e  r bound on the n
35500 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65  umber of rows re
35510 74 75 72 6e 65 64 2e 20 5e 4f 74 68 65 72 77 69  turned. ^Otherwi
35520 73 65 2c 20 74 68 65 0a 53 45 4c 45 43 54 20 72  se, the.SELECT r
35530 65 74 75 72 6e 73 20 74 68 65 20 66 69 72 73 74  eturns the first
35540 20 4e 20 72 6f 77 73 20 6f 66 20 69 74 73 20 72   N rows of its r
35550 65 73 75 6c 74 20 73 65 74 20 6f 6e 6c 79 2c 20  esult set only, 
35560 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
35570 61 6c 75 65 0a 74 68 61 74 20 74 68 65 20 4c 49  alue.that the LI
35580 4d 49 54 20 65 78 70 72 65 73 73 69 6f 6e 20 65  MIT expression e
35590 76 61 6c 75 61 74 65 73 20 74 6f 2e 20 5e 4f 72  valuates to. ^Or
355a0 2c 20 69 66 20 74 68 65 20 53 45 4c 45 43 54 20  , if the SELECT 
355b0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
355c0 72 65 74 75 72 6e 20 6c 65 73 73 20 74 68 61 6e  return less than
355d0 20 4e 20 72 6f 77 73 20 77 69 74 68 6f 75 74 20   N rows without 
355e0 61 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 2c 20  a LIMIT clause, 
355f0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
35600 72 65 73 75 6c 74 20 73 65 74 20 69 73 0a 72 65  result set is.re
35610 74 75 72 6e 65 64 2e 20 0a 0a 3c 70 3e 5e 54 68  turned. ..<p>^Th
35620 65 20 65 78 70 72 65 73 73 69 6f 6e 20 61 74 74  e expression att
35630 61 63 68 65 64 20 74 6f 20 74 68 65 20 6f 70 74  ached to the opt
35640 69 6f 6e 61 6c 20 4f 46 46 53 45 54 20 63 6c 61  ional OFFSET cla
35650 75 73 65 20 74 68 61 74 20 6d 61 79 20 66 6f 6c  use that may fol
35660 6c 6f 77 20 61 0a 4c 49 4d 49 54 20 63 6c 61 75  low a.LIMIT clau
35670 73 65 20 6d 75 73 74 20 61 6c 73 6f 20 65 76 61  se must also eva
35680 6c 75 61 74 65 20 74 6f 20 61 6e 20 69 6e 74 65  luate to an inte
35690 67 65 72 2c 20 6f 72 20 61 20 76 61 6c 75 65 20  ger, or a value 
356a0 74 68 61 74 20 63 61 6e 20 62 65 0a 6c 6f 73 73  that can be.loss
356b0 6c 65 73 73 6c 79 20 63 6f 6e 76 65 72 74 65 64  lessly converted
356c0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 20   to an integer. 
356d0 5e 49 66 20 61 6e 20 65 78 70 72 65 73 73 69 6f  ^If an expressio
356e0 6e 20 68 61 73 20 61 6e 20 4f 46 46 53 45 54 20  n has an OFFSET 
356f0 63 6c 61 75 73 65 2c 0a 74 68 65 6e 20 74 68 65  clause,.then the
35700 20 66 69 72 73 74 20 4d 20 72 6f 77 73 20 61 72   first M rows ar
35710 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
35720 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
35730 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 53 45  turned by the SE
35740 4c 45 43 54 0a 73 74 61 74 65 6d 65 6e 74 20 61  LECT.statement a
35750 6e 64 20 74 68 65 20 6e 65 78 74 20 4e 20 72 6f  nd the next N ro
35760 77 73 20 61 72 65 20 72 65 74 75 72 6e 65 64 2c  ws are returned,
35770 20 77 68 65 72 65 20 4d 20 61 6e 64 20 4e 20 61   where M and N a
35780 72 65 20 74 68 65 20 76 61 6c 75 65 73 20 74 68  re the values th
35790 61 74 0a 74 68 65 20 4f 46 46 53 45 54 20 61 6e  at.the OFFSET an
357a0 64 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 73 20  d LIMIT clauses 
357b0 65 76 61 6c 75 61 74 65 20 74 6f 2c 20 72 65 73  evaluate to, res
357c0 70 65 63 74 69 76 65 6c 79 2e 20 5e 4f 72 2c 20  pectively. ^Or, 
357d0 69 66 20 74 68 65 20 53 45 4c 45 43 54 0a 77 6f  if the SELECT.wo
357e0 75 6c 64 20 72 65 74 75 72 6e 20 6c 65 73 73 20  uld return less 
357f0 74 68 61 6e 20 4d 2b 4e 20 72 6f 77 73 20 69 66  than M+N rows if
35800 20 69 74 20 64 69 64 20 6e 6f 74 20 68 61 76 65   it did not have
35810 20 61 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 2c   a LIMIT clause,
35820 20 74 68 65 6e 20 74 68 65 0a 66 69 72 73 74 20   then the.first 
35830 4d 20 72 6f 77 73 20 61 72 65 20 73 6b 69 70 70  M rows are skipp
35840 65 64 20 61 6e 64 20 74 68 65 20 72 65 6d 61 69  ed and the remai
35850 6e 69 6e 67 20 72 6f 77 73 20 28 69 66 20 61 6e  ning rows (if an
35860 79 29 20 61 72 65 20 72 65 74 75 72 6e 65 64 2e  y) are returned.
35870 20 5e 49 66 20 74 68 65 0a 4f 46 46 53 45 54 20   ^If the.OFFSET 
35880 63 6c 61 75 73 65 20 65 76 61 6c 75 61 74 65 73  clause evaluates
35890 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 76   to a negative v
358a0 61 6c 75 65 2c 20 74 68 65 20 72 65 73 75 6c 74  alue, the result
358b0 73 20 61 72 65 20 74 68 65 20 73 61 6d 65 20 61  s are the same a
358c0 73 20 69 66 20 69 74 0a 68 61 64 20 65 76 61 6c  s if it.had eval
358d0 75 61 74 65 64 20 74 6f 20 7a 65 72 6f 2e 0a 0a  uated to zero...
358e0 3c 70 3e 5e 49 6e 73 74 65 61 64 20 6f 66 20 61  <p>^Instead of a
358f0 20 73 65 70 61 72 61 74 65 20 4f 46 46 53 45 54   separate OFFSET
35900 20 63 6c 61 75 73 65 2c 20 74 68 65 20 4c 49 4d   clause, the LIM
35910 49 54 20 63 6c 61 75 73 65 20 6d 61 79 20 73 70  IT clause may sp
35920 65 63 69 66 79 20 74 77 6f 0a 73 63 61 6c 61 72  ecify two.scalar
35930 20 65 78 70 72 65 73 73 69 6f 6e 73 20 73 65 70   expressions sep
35940 61 72 61 74 65 64 20 62 79 20 61 20 63 6f 6d 6d  arated by a comm
35950 61 2e 20 5e 49 6e 20 74 68 69 73 20 63 61 73 65  a. ^In this case
35960 2c 20 74 68 65 20 66 69 72 73 74 20 65 78 70 72  , the first expr
35970 65 73 73 69 6f 6e 0a 69 73 20 75 73 65 64 20 61  ession.is used a
35980 73 20 74 68 65 20 4f 46 46 53 45 54 20 65 78 70  s the OFFSET exp
35990 72 65 73 73 69 6f 6e 20 61 6e 64 20 74 68 65 20  ression and the 
359a0 73 65 63 6f 6e 64 20 61 73 20 74 68 65 20 4c 49  second as the LI
359b0 4d 49 54 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a  MIT expression..
359c0 54 68 69 73 20 69 73 20 63 6f 75 6e 74 65 72 2d  This is counter-
359d0 69 6e 74 75 69 74 69 76 65 2c 20 61 73 20 77 68  intuitive, as wh
359e0 65 6e 20 75 73 69 6e 67 20 74 68 65 20 4f 46 46  en using the OFF
359f0 53 45 54 20 63 6c 61 75 73 65 20 74 68 65 20 73  SET clause the s
35a00 65 63 6f 6e 64 20 6f 66 0a 74 68 65 20 74 77 6f  econd of.the two
35a10 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 73 20   expressions is 
35a20 74 68 65 20 4f 46 46 53 45 54 20 61 6e 64 20 74  the OFFSET and t
35a30 68 65 20 66 69 72 73 74 20 74 68 65 20 4c 49 4d  he first the LIM
35a40 49 54 2e 20 0a 54 68 69 73 20 72 65 76 65 72 73  IT. .This revers
35a50 61 6c 20 6f 66 20 74 68 65 20 6f 66 66 73 65 74  al of the offset
35a60 20 61 6e 64 20 6c 69 6d 69 74 20 69 73 20 69 6e   and limit is in
35a70 74 65 6e 74 69 6f 6e 61 6c 0a 2d 20 69 74 20 6d  tentional.- it m
35a80 61 78 69 6d 69 7a 65 73 20 63 6f 6d 70 61 74 69  aximizes compati
35a90 62 69 6c 69 74 79 20 77 69 74 68 20 6f 74 68 65  bility with othe
35aa0 72 20 53 51 4c 20 64 61 74 61 62 61 73 65 20 73  r SQL database s
35ab0 79 73 74 65 6d 73 2e 0a 48 6f 77 65 76 65 72 2c  ystems..However,
35ac0 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 75 73   to avoid confus
35ad0 69 6f 6e 2c 20 70 72 6f 67 72 61 6d 6d 65 72 73  ion, programmers
35ae0 20 61 72 65 20 73 74 72 6f 6e 67 6c 79 20 65 6e   are strongly en
35af0 63 6f 75 72 61 67 65 64 20 74 6f 20 75 73 65 0a  couraged to use.
35b00 74 68 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  the form of the 
35b10 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 74 68 61  LIMIT clause tha
35b20 74 20 75 73 65 73 20 74 68 65 20 22 4f 46 46 53  t uses the "OFFS
35b30 45 54 22 20 6b 65 79 77 6f 72 64 20 61 6e 64 20  ET" keyword and 
35b40 61 76 6f 69 64 0a 75 73 69 6e 67 20 61 20 4c 49  avoid.using a LI
35b50 4d 49 54 20 63 6c 61 75 73 65 20 77 69 74 68 20  MIT clause with 
35b60 61 20 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65  a comma-separate
35b70 64 20 6f 66 66 73 65 74 2e 0a 0a 3c 74 63 6c 3e  d offset...<tcl>
35b80 68 64 5f 66 72 61 67 6d 65 6e 74 20 76 61 6c 75  hd_fragment valu
35b90 65 73 20 7b 56 41 4c 55 45 53 20 63 6c 61 75 73  es {VALUES claus
35ba0 65 7d 20 56 41 4c 55 45 53 3c 2f 74 63 6c 3e 0a  e} VALUES</tcl>.
35bb0 3c 68 33 3e 54 68 65 20 56 41 4c 55 45 53 20 63  <h3>The VALUES c
35bc0 6c 61 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e  lause</h3>..<p>^
35bd0 28 54 68 65 20 70 68 72 61 73 65 20 22 56 41 4c  (The phrase "VAL
35be0 55 45 53 28 3c 69 3e 65 78 70 72 2d 6c 69 73 74  UES(<i>expr-list
35bf0 3c 2f 69 3e 29 22 20 6d 65 61 6e 73 20 74 68 65  </i>)" means the
35c00 20 73 61 6d 65 20 74 68 69 6e 67 0a 61 73 20 22   same thing.as "
35c10 53 45 4c 45 43 54 20 3c 69 3e 65 78 70 72 2d 6c  SELECT <i>expr-l
35c20 69 73 74 3c 2f 69 3e 22 2e 29 5e 20 20 5e 28 54  ist</i>".)^  ^(T
35c30 68 65 20 70 68 72 61 73 65 0a 22 56 41 4c 55 45  he phrase."VALUE
35c40 53 28 3c 69 3e 65 78 70 72 2d 6c 69 73 74 2d 31  S(<i>expr-list-1
35c50 3c 2f 69 3e 29 2c 2e 2e 2e 2c 28 3c 69 3e 65 78  </i>),...,(<i>ex
35c60 70 72 2d 6c 69 73 74 2d 4e 3c 2f 69 3e 29 22 20  pr-list-N</i>)" 
35c70 6d 65 61 6e 73 20 74 68 65 20 73 61 6d 65 0a 74  means the same.t
35c80 68 69 6e 67 20 61 73 20 22 53 45 4c 45 43 54 20  hing as "SELECT 
35c90 3c 69 3e 65 78 70 72 2d 6c 69 73 74 2d 31 3c 2f  <i>expr-list-1</
35ca0 69 3e 20 55 4e 49 4f 4e 20 41 4c 4c 20 2e 2e 2e  i> UNION ALL ...
35cb0 20 55 4e 49 4f 4e 20 41 4c 4c 0a 53 45 4c 45 43   UNION ALL.SELEC
35cc0 54 20 3c 69 3e 65 78 70 72 2d 6c 69 73 74 2d 4e  T <i>expr-list-N
35cd0 3c 2f 69 3e 22 2e 29 5e 20 20 42 6f 74 68 20 66  </i>".)^  Both f
35ce0 6f 72 6d 73 20 61 72 65 20 74 68 65 20 73 61 6d  orms are the sam
35cf0 65 2c 20 65 78 63 65 70 74 20 74 68 61 74 0a 74  e, except that.t
35d00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 53 45 4c  he number of SEL
35d10 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 20 69  ECT statements i
35d20 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 69 73 20  n a compound is 
35d30 6c 69 6d 69 74 65 64 20 62 79 0a 5b 53 51 4c 49  limited by.[SQLI
35d40 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
35d50 44 5f 53 45 4c 45 43 54 5d 20 77 68 65 72 65 61  D_SELECT] wherea
35d60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
35d70 72 6f 77 73 20 69 6e 20 61 0a 56 41 4c 55 45 53  rows in a.VALUES
35d80 20 63 6c 61 75 73 65 20 68 61 73 20 6e 6f 20 61   clause has no a
35d90 72 62 69 74 72 61 72 79 20 6c 69 6d 69 74 2e 0a  rbitrary limit..
35da0 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20 73 6f  .<p>There are so
35db0 6d 65 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20  me restrictions 
35dc0 6f 6e 20 74 68 65 20 75 73 65 20 6f 66 20 61 20  on the use of a 
35dd0 56 41 4c 55 45 53 20 63 6c 61 75 73 65 20 74 68  VALUES clause th
35de0 61 74 20 61 72 65 0a 6e 6f 74 20 73 68 6f 77 6e  at are.not shown
35df0 20 6f 6e 20 74 68 65 20 73 79 6e 74 61 78 20 64   on the syntax d
35e00 69 61 67 72 61 6d 73 3a 0a 0a 3c 75 6c 3e 0a 3c  iagrams:..<ul>.<
35e10 6c 69 3e 3c 70 3e 0a 5e 41 20 56 41 4c 55 45 53  li><p>.^A VALUES
35e20 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f 74 20 62   clause cannot b
35e30 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 5b 4f  e followed by [O
35e40 52 44 45 52 20 42 59 5d 2e 0a 0a 3c 6c 69 3e 3c  RDER BY]...<li><
35e50 70 3e 0a 5e 41 20 56 41 4c 55 45 53 20 63 6c 61  p>.^A VALUES cla
35e60 75 73 65 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  use cannot be fo
35e70 6c 6c 6f 77 65 64 20 62 79 20 5b 4c 49 4d 49 54  llowed by [LIMIT
35e80 5d 2e 0a 3c 2f 75 6c 3e 0a 0a 0a 3c 68 33 3e 54  ]..</ul>...<h3>T
35e90 68 65 20 57 49 54 48 20 43 6c 61 75 73 65 3c 2f  he WITH Clause</
35ea0 68 33 3e 0a 0a 3c 70 3e 5e 53 45 4c 45 43 54 20  h3>..<p>^SELECT 
35eb0 73 74 61 74 65 6d 65 6e 74 73 20 6d 61 79 20 62  statements may b
35ec0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 70 72 65  e optionally pre
35ed0 63 65 64 65 64 20 62 79 20 61 20 73 69 6e 67 6c  ceded by a singl
35ee0 65 0a 5b 57 49 54 48 20 63 6c 61 75 73 65 5d 20  e.[WITH clause] 
35ef0 74 68 61 74 20 64 65 66 69 6e 65 73 20 6f 6e 65  that defines one
35f00 20 6f 72 20 6d 6f 72 65 20 5b 63 6f 6d 6d 6f 6e   or more [common
35f10 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f   table expressio
35f20 6e 73 5d 0a 66 6f 72 20 75 73 65 20 77 69 74 68  ns].for use with
35f30 69 6e 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  in the SELECT st
35f40 61 74 65 6d 65 6e 74 2e 0a 0a 3c 74 63 6c 3e 68  atement...<tcl>h
35f50 64 5f 66 72 61 67 6d 65 6e 74 20 74 61 62 66 75  d_fragment tabfu
35f60 6e 63 31 20 7b 74 61 62 6c 65 2d 76 61 6c 75 65  nc1 {table-value
35f70 64 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  d functions in t
35f80 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 7d 3c  he FROM clause}<
35f90 2f 74 63 6c 3e 0a 3c 68 33 3e 54 61 62 6c 65 2d  /tcl>.<h3>Table-
35fa0 76 61 6c 75 65 64 20 46 75 6e 63 74 69 6f 6e 73  valued Functions
35fb0 20 49 6e 20 54 68 65 20 46 52 4f 4d 20 43 6c 61   In The FROM Cla
35fc0 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 20 5b  use</h3>..<p>A [
35fd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 74  virtual table] t
35fe0 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 5b 68 69  hat contains [hi
35ff0 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 5d 20 63 61  dden columns] ca
36000 6e 20 62 65 20 75 73 65 64 20 6c 69 6b 65 0a 61  n be used like.a
36010 20 5b 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66   [table-valued f
36020 75 6e 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20  unction] in the 
36030 46 52 4f 4d 20 63 6c 61 75 73 65 2e 20 20 54 68  FROM clause.  Th
36040 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
36050 68 65 0a 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  he.table-valued 
36060 66 75 6e 63 74 69 6f 6e 20 62 65 63 6f 6d 65 20  function become 
36070 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e 20 74  constraints on t
36080 68 65 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e  he HIDDEN column
36090 73 20 6f 66 0a 74 68 65 20 76 69 72 74 75 61 6c  s of.the virtual
360a0 20 74 61 62 6c 65 2e 20 20 41 64 64 69 74 69 6f   table.  Additio
360b0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
360c0 63 61 6e 20 62 65 20 66 6f 75 6e 64 20 69 6e 20  can be found in 
360d0 74 68 65 0a 5b 74 61 62 6c 65 2d 76 61 6c 75 65  the.[table-value
360e0 64 20 66 75 6e 63 74 69 6f 6e 73 7c 76 69 72 74  d functions|virt
360f0 75 61 6c 20 74 61 62 6c 65 20 64 6f 63 75 6d 65  ual table docume
36100 6e 74 61 74 69 6f 6e 5d 2e 0a 0a 3c 74 63 6c 3e  ntation]...<tcl>
36110 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
36120 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36130 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36140 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
36150 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
36160 53 65 63 74 69 6f 6e 20 55 50 44 41 54 45 20 75  Section UPDATE u
36170 70 64 61 74 65 20 7b 55 50 44 41 54 45 20 2a 55  pdate {UPDATE *U
36180 50 44 41 54 45 73 7d 0a 0a 52 65 63 75 72 73 69  PDATEs}..Recursi
36190 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  veBubbleDiagram 
361a0 75 70 64 61 74 65 2d 73 74 6d 74 0a 3c 2f 74 63  update-stmt.</tc
361b0 6c 3e 0a 0a 3c 70 3e 5e 41 6e 20 55 50 44 41 54  l>..<p>^An UPDAT
361c0 45 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75  E statement is u
361d0 73 65 64 20 74 6f 20 6d 6f 64 69 66 79 20 61 20  sed to modify a 
361e0 73 75 62 73 65 74 20 6f 66 20 74 68 65 20 76 61  subset of the va
361f0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 0a  lues stored in .
36200 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 72 6f 77  zero or more row
36210 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
36220 65 20 74 61 62 6c 65 20 69 64 65 6e 74 69 66 69  e table identifi
36230 65 64 20 62 79 20 74 68 65 20 0a 5b 71 75 61 6c  ed by the .[qual
36240 69 66 69 65 64 2d 74 61 62 6c 65 2d 6e 61 6d 65  ified-table-name
36250 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  ] specified as p
36260 61 72 74 20 6f 66 20 74 68 65 20 55 50 44 41 54  art of the UPDAT
36270 45 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 70  E statement...<p
36280 3e 5e 49 66 20 74 68 65 20 55 50 44 41 54 45 20  >^If the UPDATE 
36290 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
362a0 6f 74 20 68 61 76 65 20 61 20 57 48 45 52 45 20  ot have a WHERE 
362b0 63 6c 61 75 73 65 2c 20 61 6c 6c 20 72 6f 77 73  clause, all rows
362c0 20 69 6e 20 74 68 65 0a 74 61 62 6c 65 20 61 72   in the.table ar
362d0 65 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  e modified by th
362e0 65 20 55 50 44 41 54 45 2e 20 5e 4f 74 68 65 72  e UPDATE. ^Other
362f0 77 69 73 65 2c 20 74 68 65 20 55 50 44 41 54 45  wise, the UPDATE
36300 20 61 66 66 65 63 74 73 20 6f 6e 6c 79 20 74 68   affects only th
36310 6f 73 65 0a 72 6f 77 73 20 66 6f 72 20 77 68 69  ose.rows for whi
36320 63 68 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  ch the WHERE cla
36330 75 73 65 0a 5b 62 6f 6f 6c 65 61 6e 20 65 78 70  use.[boolean exp
36340 72 65 73 73 69 6f 6e 7c 62 6f 6f 6c 65 61 6e 20  ression|boolean 
36350 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 74 72  expression is tr
36360 75 65 5d 2e 20 5e 49 74 20 69 73 20 6e 6f 74 20  ue]. ^It is not 
36370 61 6e 20 65 72 72 6f 72 20 69 66 20 74 68 65 0a  an error if the.
36380 57 48 45 52 45 20 63 6c 61 75 73 65 20 64 6f 65  WHERE clause doe
36390 73 20 6e 6f 74 20 65 76 61 6c 75 61 74 65 20 74  s not evaluate t
363a0 6f 20 74 72 75 65 20 66 6f 72 20 61 6e 79 20 72  o true for any r
363b0 6f 77 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ow in the table 
363c0 2d 20 74 68 69 73 20 6a 75 73 74 0a 6d 65 61 6e  - this just.mean
363d0 73 20 74 68 61 74 20 74 68 65 20 55 50 44 41 54  s that the UPDAT
363e0 45 20 73 74 61 74 65 6d 65 6e 74 20 61 66 66 65  E statement affe
363f0 63 74 73 20 7a 65 72 6f 20 72 6f 77 73 2e 0a 0a  cts zero rows...
36400 3c 70 3e 54 68 65 20 6d 6f 64 69 66 69 63 61 74  <p>The modificat
36410 69 6f 6e 73 20 6d 61 64 65 20 74 6f 20 65 61 63  ions made to eac
36420 68 20 72 6f 77 20 61 66 66 65 63 74 65 64 20 62  h row affected b
36430 79 20 61 6e 20 55 50 44 41 54 45 20 73 74 61 74  y an UPDATE stat
36440 65 6d 65 6e 74 20 61 72 65 0a 64 65 74 65 72 6d  ement are.determ
36450 69 6e 65 64 20 62 79 20 74 68 65 20 6c 69 73 74  ined by the list
36460 20 6f 66 20 61 73 73 69 67 6e 6d 65 6e 74 73 20   of assignments 
36470 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 53 45  following the SE
36480 54 20 6b 65 79 77 6f 72 64 2e 20 45 61 63 68 0a  T keyword. Each.
36490 61 73 73 69 67 6e 6d 65 6e 74 20 73 70 65 63 69  assignment speci
364a0 66 69 65 73 20 61 20 3c 79 79 74 65 72 6d 3e 63  fies a <yyterm>c
364b0 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65  olumn-name</yyte
364c0 72 6d 3e 20 74 6f 20 74 68 65 20 6c 65 66 74 20  rm> to the left 
364d0 6f 66 20 74 68 65 20 0a 65 71 75 61 6c 73 20 73  of the .equals s
364e0 69 67 6e 20 61 6e 64 20 61 20 73 63 61 6c 61 72  ign and a scalar
364f0 20 65 78 70 72 65 73 73 69 6f 6e 20 74 6f 20 74   expression to t
36500 68 65 20 72 69 67 68 74 2e 20 0a 5e 46 6f 72 20  he right. .^For 
36510 65 61 63 68 20 61 66 66 65 63 74 65 64 20 72 6f  each affected ro
36520 77 2c 20 74 68 65 20 6e 61 6d 65 64 20 63 6f 6c  w, the named col
36530 75 6d 6e 73 0a 61 72 65 20 73 65 74 20 74 6f 20  umns.are set to 
36540 74 68 65 20 76 61 6c 75 65 73 20 66 6f 75 6e 64  the values found
36550 20 62 79 20 65 76 61 6c 75 61 74 69 6e 67 20 74   by evaluating t
36560 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36570 20 73 63 61 6c 61 72 20 0a 65 78 70 72 65 73 73   scalar .express
36580 69 6f 6e 73 2e 20 5e 49 66 20 61 20 73 69 6e 67  ions. ^If a sing
36590 6c 65 20 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 20 61  le column-name a
365a0 70 70 65 61 72 73 20 6d 6f 72 65 20 74 68 61 6e  ppears more than
365b0 20 6f 6e 63 65 20 69 6e 20 74 68 65 20 6c 69 73   once in the lis
365c0 74 20 6f 66 0a 61 73 73 69 67 6e 6d 65 6e 74 20  t of.assignment 
365d0 65 78 70 72 65 73 73 69 6f 6e 73 2c 20 61 6c 6c  expressions, all
365e0 20 62 75 74 20 74 68 65 20 72 69 67 68 74 6d 6f   but the rightmo
365f0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 20 69 73  st occurrence is
36600 20 69 67 6e 6f 72 65 64 2e 20 5e 43 6f 6c 75 6d   ignored. ^Colum
36610 6e 73 0a 74 68 61 74 20 64 6f 20 6e 6f 74 20 61  ns.that do not a
36620 70 70 65 61 72 20 69 6e 20 74 68 65 20 6c 69 73  ppear in the lis
36630 74 20 6f 66 20 61 73 73 69 67 6e 6d 65 6e 74 73  t of assignments
36640 20 61 72 65 20 6c 65 66 74 20 75 6e 6d 6f 64 69   are left unmodi
36650 66 69 65 64 2e 20 5e 54 68 65 20 73 63 61 6c 61  fied. ^The scala
36660 72 0a 65 78 70 72 65 73 73 69 6f 6e 73 20 6d 61  r.expressions ma
36670 79 20 72 65 66 65 72 20 74 6f 20 63 6f 6c 75 6d  y refer to colum
36680 6e 73 20 6f 66 20 74 68 65 20 72 6f 77 20 62 65  ns of the row be
36690 69 6e 67 20 75 70 64 61 74 65 64 2e 20 5e 49 6e  ing updated. ^In
366a0 20 74 68 69 73 20 63 61 73 65 20 61 6c 6c 0a 73   this case all.s
366b0 63 61 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  calar expression
366c0 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
366d0 62 65 66 6f 72 65 20 61 6e 79 20 61 73 73 69 67  before any assig
366e0 6e 6d 65 6e 74 73 20 61 72 65 20 6d 61 64 65 2e  nments are made.
366f0 0a 0a 3c 70 3e 42 65 67 69 6e 6e 69 6e 67 20 69  ..<p>Beginning i
36700 6e 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  n SQLite [versio
36710 6e 20 33 2e 31 35 2e 30 5d 20 28 5b 64 61 74 65  n 3.15.0] ([date
36720 6f 66 3a 33 2e 31 35 2e 30 5d 29 2c 20 61 6e 20  of:3.15.0]), an 
36730 61 73 73 69 67 6e 6d 65 6e 74 20 69 6e 0a 74 68  assignment in.th
36740 65 20 53 45 54 20 63 6c 61 75 73 65 20 63 61 6e  e SET clause can
36750 20 62 65 20 61 20 0a 5b 63 6f 6c 75 6d 6e 2d 6e   be a .[column-n
36760 61 6d 65 2d 6c 69 73 74 7c 70 61 72 65 6e 74 68  ame-list|parenth
36770 65 73 69 7a 65 64 20 6c 69 73 74 20 6f 66 20 63  esized list of c
36780 6f 6c 75 6d 6e 20 6e 61 6d 65 73 5d 20 6f 6e 20  olumn names] on 
36790 74 68 65 20 6c 65 66 74 20 61 6e 64 20 61 0a 5b  the left and a.[
367a0 72 6f 77 20 76 61 6c 75 65 5d 20 6f 66 20 74 68  row value] of th
367b0 65 20 73 61 6d 65 20 73 69 7a 65 20 6f 6e 20 74  e same size on t
367c0 68 65 20 72 69 67 68 74 2e 0a 0a 0a 3c 70 3e 5e  he right....<p>^
367d0 54 68 65 20 6f 70 74 69 6f 6e 61 6c 20 22 4f 52  The optional "OR
367e0 20 3c 69 3e 61 63 74 69 6f 6e 3c 2f 69 3e 22 20   <i>action</i>" 
367f0 63 6f 6e 66 6c 69 63 74 20 63 6c 61 75 73 65 20  conflict clause 
36800 74 68 61 74 20 66 6f 6c 6c 6f 77 73 20 74 68 65  that follows the
36810 0a 55 50 44 41 54 45 20 6b 65 79 77 6f 72 64 20  .UPDATE keyword 
36820 61 6c 6c 6f 77 73 20 74 68 65 20 75 73 65 72 20  allows the user 
36830 74 6f 20 6e 6f 6d 69 6e 61 74 65 20 61 20 73 70  to nominate a sp
36840 65 63 69 66 69 63 0a 63 6f 6e 73 74 72 61 69 6e  ecific.constrain
36850 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  t conflict resol
36860 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20  ution algorithm 
36870 74 6f 20 75 73 65 20 64 75 72 69 6e 67 20 74 68  to use during th
36880 69 73 20 6f 6e 65 20 55 50 44 41 54 45 20 63 6f  is one UPDATE co
36890 6d 6d 61 6e 64 2e 0a 52 65 66 65 72 20 74 6f 20  mmand..Refer to 
368a0 74 68 65 20 73 65 63 74 69 6f 6e 20 65 6e 74 69  the section enti
368b0 74 6c 65 64 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  tled [ON CONFLIC
368c0 54 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  T] for additiona
368d0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 0a  l information...
368e0 3c 68 33 3e 52 65 73 74 72 69 63 74 69 6f 6e 73  <h3>Restrictions
368f0 20 6f 6e 20 55 50 44 41 54 45 20 53 74 61 74 65   on UPDATE State
36900 6d 65 6e 74 73 20 57 69 74 68 69 6e 20 43 52 45  ments Within CRE
36910 41 54 45 20 54 52 49 47 47 45 52 3c 2f 68 33 3e  ATE TRIGGER</h3>
36920 0a 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f 77 69  ..<p>The followi
36930 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 79  ng additional sy
36940 6e 74 61 78 20 72 65 73 74 72 69 63 74 69 6f 6e  ntax restriction
36950 73 20 61 70 70 6c 79 20 74 6f 20 55 50 44 41 54  s apply to UPDAT
36960 45 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  E statements tha
36970 74 0a 6f 63 63 75 72 20 77 69 74 68 69 6e 20 74  t.occur within t
36980 68 65 20 62 6f 64 79 20 6f 66 20 61 20 5b 43 52  he body of a [CR
36990 45 41 54 45 20 54 52 49 47 47 45 52 5d 20 73 74  EATE TRIGGER] st
369a0 61 74 65 6d 65 6e 74 2e 20 20 0a 0a 3c 75 6c 3e  atement.  ..<ul>
369b0 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 3c  .  <li><p>^The <
369c0 79 79 74 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d  yyterm>table-nam
369d0 65 3c 2f 79 79 74 65 72 6d 3e 20 73 70 65 63 69  e</yyterm> speci
369e0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
369f0 61 6e 20 55 50 44 41 54 45 20 0a 20 20 20 20 20  an UPDATE .     
36a00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
36a10 6e 0a 20 20 20 20 20 20 61 20 74 72 69 67 67 65  n.      a trigge
36a20 72 20 62 6f 64 79 20 6d 75 73 74 20 62 65 20 75  r body must be u
36a30 6e 71 75 61 6c 69 66 69 65 64 2e 20 5e 28 49 6e  nqualified. ^(In
36a40 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
36a50 65 0a 20 20 20 20 20 20 3c 69 3e 73 63 68 65 6d  e.      <i>schem
36a60 61 2d 6e 61 6d 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f  a-name</i><b>.</
36a70 62 3e 20 70 72 65 66 69 78 20 6f 6e 20 74 68 65  b> prefix on the
36a80 20 74 61 62 6c 65 20 6e 61 6d 65 20 6f 66 20 74   table name of t
36a90 68 65 20 55 50 44 41 54 45 20 69 73 0a 20 20 20  he UPDATE is.   
36aa0 20 20 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 77     not allowed w
36ab0 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 2e 29  ithin triggers.)
36ac0 5e 20 5e 55 6e 6c 65 73 73 20 74 68 65 20 74 61  ^ ^Unless the ta
36ad0 62 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ble to which the
36ae0 20 74 72 69 67 67 65 72 0a 20 20 20 20 20 20 69   trigger.      i
36af0 73 20 61 74 74 61 63 68 65 64 20 69 73 20 69 6e  s attached is in
36b00 20 74 68 65 20 54 45 4d 50 20 64 61 74 61 62 61   the TEMP databa
36b10 73 65 2c 20 74 68 65 20 74 61 62 6c 65 20 62 65  se, the table be
36b20 69 6e 67 20 75 70 64 61 74 65 64 20 62 79 20 74  ing updated by t
36b30 68 65 0a 20 20 20 20 20 20 74 72 69 67 67 65 72  he.      trigger
36b40 20 70 72 6f 67 72 61 6d 20 6d 75 73 74 20 72 65   program must re
36b50 73 69 64 65 20 69 6e 20 74 68 65 20 73 61 6d 65  side in the same
36b60 20 64 61 74 61 62 61 73 65 20 61 73 20 69 74 2e   database as it.
36b70 20 5e 49 66 20 74 68 65 20 74 61 62 6c 65 0a 20   ^If the table. 
36b80 20 20 20 20 20 74 6f 20 77 68 69 63 68 20 74 68       to which th
36b90 65 20 74 72 69 67 67 65 72 20 69 73 20 61 74 74  e trigger is att
36ba0 61 63 68 65 64 20 69 73 20 69 6e 20 74 68 65 20  ached is in the 
36bb0 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 74  TEMP database, t
36bc0 68 65 6e 20 74 68 65 0a 20 20 20 20 20 20 75 6e  hen the.      un
36bd0 71 75 61 6c 69 66 69 65 64 20 6e 61 6d 65 20 6f  qualified name o
36be0 66 20 74 68 65 20 74 61 62 6c 65 20 62 65 69 6e  f the table bein
36bf0 67 20 75 70 64 61 74 65 64 20 69 73 20 72 65 73  g updated is res
36c00 6f 6c 76 65 64 20 69 6e 20 74 68 65 20 73 61 6d  olved in the sam
36c10 65 20 77 61 79 0a 20 20 20 20 20 20 61 73 20 69  e way.      as i
36c20 74 20 69 73 20 66 6f 72 20 61 20 74 6f 70 2d 6c  t is for a top-l
36c30 65 76 65 6c 20 73 74 61 74 65 6d 65 6e 74 20 28  evel statement (
36c40 62 79 20 73 65 61 72 63 68 69 6e 67 20 66 69 72  by searching fir
36c50 73 74 20 74 68 65 20 54 45 4d 50 20 64 61 74 61  st the TEMP data
36c60 62 61 73 65 2c 0a 20 20 20 20 20 20 74 68 65 6e  base,.      then
36c70 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
36c80 73 65 2c 20 74 68 65 6e 20 61 6e 79 20 6f 74 68  se, then any oth
36c90 65 72 20 64 61 74 61 62 61 73 65 73 20 69 6e 20  er databases in 
36ca0 74 68 65 20 6f 72 64 65 72 20 74 68 65 79 20 77  the order they w
36cb0 65 72 65 0a 20 20 20 20 20 20 61 74 74 61 63 68  ere.      attach
36cc0 65 64 29 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  ed)...  <li><p>^
36cd0 54 68 65 20 49 4e 44 45 58 45 44 20 42 59 20 61  The INDEXED BY a
36ce0 6e 64 20 4e 4f 54 20 49 4e 44 45 58 45 44 20 63  nd NOT INDEXED c
36cf0 6c 61 75 73 65 73 20 61 72 65 20 6e 6f 74 20 61  lauses are not a
36d00 6c 6c 6f 77 65 64 20 6f 6e 20 55 50 44 41 54 45  llowed on UPDATE
36d10 0a 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74  .      statement
36d20 73 20 77 69 74 68 69 6e 20 74 72 69 67 67 65 72  s within trigger
36d30 73 2e 3c 2f 70 3e 0a 0a 20 20 3c 6c 69 3e 3c 70  s.</p>..  <li><p
36d40 3e 5e 54 68 65 20 4c 49 4d 49 54 20 61 6e 64 20  >^The LIMIT and 
36d50 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 73  ORDER BY clauses
36d60 20 66 6f 72 20 55 50 44 41 54 45 20 61 72 65 20   for UPDATE are 
36d70 75 6e 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  unsupported with
36d80 69 6e 0a 20 20 20 20 20 20 74 72 69 67 67 65 72  in.      trigger
36d90 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  s, regardless of
36da0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
36db0 20 6f 70 74 69 6f 6e 73 20 75 73 65 64 20 74 6f   options used to
36dc0 20 62 75 69 6c 64 20 53 51 4c 69 74 65 2e 0a 3c   build SQLite..<
36dd0 2f 75 6c 3e 0a 0a 3c 68 33 3e 4f 70 74 69 6f 6e  /ul>..<h3>Option
36de0 61 6c 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52 44  al LIMIT and ORD
36df0 45 52 20 42 59 20 43 6c 61 75 73 65 73 3c 2f 68  ER BY Clauses</h
36e00 33 3e 0a 0a 3c 70 3e 5e 28 49 66 20 53 51 4c 69  3>..<p>^(If SQLi
36e10 74 65 20 69 73 20 62 75 69 6c 74 20 77 69 74 68  te is built with
36e20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
36e30 42 4c 45 5f 55 50 44 41 54 45 5f 44 45 4c 45 54  BLE_UPDATE_DELET
36e40 45 5f 4c 49 4d 49 54 5d 0a 63 6f 6d 70 69 6c 65  E_LIMIT].compile
36e50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
36e60 6e 20 74 68 65 20 73 79 6e 74 61 78 20 6f 66 20  n the syntax of 
36e70 74 68 65 20 55 50 44 41 54 45 20 73 74 61 74 65  the UPDATE state
36e80 6d 65 6e 74 20 69 73 20 65 78 74 65 6e 64 65 64  ment is extended
36e90 0a 77 69 74 68 20 6f 70 74 69 6f 6e 61 6c 20 4f  .with optional O
36ea0 52 44 45 52 20 42 59 20 61 6e 64 20 4c 49 4d 49  RDER BY and LIMI
36eb0 54 20 63 6c 61 75 73 65 73 29 5e 20 61 73 20 66  T clauses)^ as f
36ec0 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 74 63  ollows:</p>..<tc
36ed0 6c 3e 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20  l>BubbleDiagram 
36ee0 75 70 64 61 74 65 2d 73 74 6d 74 2d 6c 69 6d 69  update-stmt-limi
36ef0 74 65 64 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 49  ted</tcl>..<p>^I
36f00 66 20 61 6e 20 55 50 44 41 54 45 20 73 74 61 74  f an UPDATE stat
36f10 65 6d 65 6e 74 20 68 61 73 20 61 20 4c 49 4d 49  ement has a LIMI
36f20 54 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6d 61  T clause, the ma
36f30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
36f40 72 6f 77 73 20 74 68 61 74 0a 77 69 6c 6c 20 62  rows that.will b
36f50 65 20 75 70 64 61 74 65 64 20 69 73 20 66 6f 75  e updated is fou
36f60 6e 64 20 62 79 20 65 76 61 6c 75 61 74 69 6e 67  nd by evaluating
36f70 20 74 68 65 20 61 63 63 6f 6d 70 61 6e 79 69 6e   the accompanyin
36f80 67 20 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64  g expression and
36f90 20 63 61 73 74 69 6e 67 0a 69 74 20 74 6f 20 61   casting.it to a
36fa0 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 2e  n integer value.
36fb0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
36fc0 75 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ue is interprete
36fd0 64 20 61 73 20 22 6e 6f 20 6c 69 6d 69 74 22 2e  d as "no limit".
36fe0 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 4c 49 4d  ..<p>^If the LIM
36ff0 49 54 20 65 78 70 72 65 73 73 69 6f 6e 20 65 76  IT expression ev
37000 61 6c 75 61 74 65 73 20 74 6f 20 6e 6f 6e 2d 6e  aluates to non-n
37010 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 3c 69  egative value <i
37020 3e 4e 3c 2f 69 3e 20 61 6e 64 20 74 68 65 0a 55  >N</i> and the.U
37030 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20  PDATE statement 
37040 68 61 73 20 61 6e 20 4f 52 44 45 52 20 42 59 20  has an ORDER BY 
37050 63 6c 61 75 73 65 2c 20 74 68 65 6e 20 61 6c 6c  clause, then all
37060 20 72 6f 77 73 20 74 68 61 74 20 77 6f 75 6c 64   rows that would
37070 20 62 65 20 75 70 64 61 74 65 64 20 69 6e 0a 74   be updated in.t
37080 68 65 20 61 62 73 65 6e 63 65 20 6f 66 20 74 68  he absence of th
37090 65 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 61  e LIMIT clause a
370a0 72 65 20 73 6f 72 74 65 64 20 61 63 63 6f 72 64  re sorted accord
370b0 69 6e 67 20 74 6f 20 74 68 65 20 4f 52 44 45 52  ing to the ORDER
370c0 20 42 59 20 61 6e 64 20 74 68 65 0a 66 69 72 73   BY and the.firs
370d0 74 20 3c 69 3e 4e 3c 2f 69 3e 20 75 70 64 61 74  t <i>N</i> updat
370e0 65 64 2e 20 5e 28 49 66 20 74 68 65 20 55 50 44  ed. ^(If the UPD
370f0 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 6c  ATE statement al
37100 73 6f 20 68 61 73 20 61 6e 20 4f 46 46 53 45 54  so has an OFFSET
37110 20 63 6c 61 75 73 65 2c 0a 74 68 65 6e 20 69 74   clause,.then it
37120 20 69 73 20 73 69 6d 69 6c 61 72 6c 79 20 65 76   is similarly ev
37130 61 6c 75 61 74 65 64 20 61 6e 64 20 63 61 73 74  aluated and cast
37140 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 76   to an integer v
37150 61 6c 75 65 2e 20 49 66 20 74 68 65 20 4f 46 46  alue. If the OFF
37160 53 45 54 0a 65 78 70 72 65 73 73 69 6f 6e 20 65  SET.expression e
37170 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 6e 6f  valuates to a no
37180 6e 2d 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  n-negative value
37190 20 3c 69 3e 4d 3c 2f 69 3e 2c 20 74 68 65 6e 20   <i>M</i>, then 
371a0 74 68 65 20 66 69 72 73 74 20 3c 69 3e 4d 3c 2f  the first <i>M</
371b0 69 3e 0a 72 6f 77 73 20 61 72 65 20 73 6b 69 70  i>.rows are skip
371c0 70 65 64 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  ped and the foll
371d0 6f 77 69 6e 67 20 3c 69 3e 4e 3c 2f 69 3e 20 72  owing <i>N</i> r
371e0 6f 77 73 20 75 70 64 61 74 65 64 20 69 6e 73 74  ows updated inst
371f0 65 61 64 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 74  ead.)^..<p>^If t
37200 68 65 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  he UPDATE statem
37210 65 6e 74 20 68 61 73 20 6e 6f 20 4f 52 44 45 52  ent has no ORDER
37220 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 6e   BY clause, then
37230 20 61 6c 6c 20 72 6f 77 73 20 74 68 61 74 0a 77   all rows that.w
37240 6f 75 6c 64 20 62 65 20 75 70 64 61 74 65 64 20  ould be updated 
37250 69 6e 20 74 68 65 20 61 62 73 65 6e 63 65 20 6f  in the absence o
37260 66 20 74 68 65 20 4c 49 4d 49 54 20 63 6c 61 75  f the LIMIT clau
37270 73 65 20 61 72 65 20 61 73 73 65 6d 62 6c 65 64  se are assembled
37280 20 69 6e 20 61 6e 0a 61 72 62 69 74 72 61 72 79   in an.arbitrary
37290 20 6f 72 64 65 72 20 62 65 66 6f 72 65 20 61 70   order before ap
372a0 70 6c 79 69 6e 67 20 74 68 65 20 4c 49 4d 49 54  plying the LIMIT
372b0 20 61 6e 64 20 4f 46 46 53 45 54 20 63 6c 61 75   and OFFSET clau
372c0 73 65 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ses to determine
372d0 20 0a 77 68 69 63 68 20 61 72 65 20 61 63 74 75   .which are actu
372e0 61 6c 6c 79 20 75 70 64 61 74 65 64 2e 0a 0a 3c  ally updated...<
372f0 70 3e 5e 28 54 68 65 20 4f 52 44 45 52 20 42 59  p>^(The ORDER BY
37300 20 63 6c 61 75 73 65 20 6f 6e 20 61 6e 20 55 50   clause on an UP
37310 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20 69  DATE statement i
37320 73 20 75 73 65 64 20 6f 6e 6c 79 20 74 6f 20 64  s used only to d
37330 65 74 65 72 6d 69 6e 65 20 77 68 69 63 68 0a 72  etermine which.r
37340 6f 77 73 20 66 61 6c 6c 20 77 69 74 68 69 6e 20  ows fall within 
37350 74 68 65 20 4c 49 4d 49 54 2e 20 54 68 65 20 6f  the LIMIT. The o
37360 72 64 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f  rder in which ro
37370 77 73 20 61 72 65 20 6d 6f 64 69 66 69 65 64 20  ws are modified 
37380 69 73 20 61 72 62 69 74 72 61 72 79 0a 61 6e 64  is arbitrary.and
37390 20 69 73 20 6e 6f 74 20 69 6e 66 6c 75 65 6e 63   is not influenc
373a0 65 64 20 62 79 20 74 68 65 20 4f 52 44 45 52 20  ed by the ORDER 
373b0 42 59 20 63 6c 61 75 73 65 2e 29 5e 0a 0a 3c 74  BY clause.)^..<t
373c0 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23  cl>.############
373d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
373e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
373f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37400 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37410 23 23 0a 53 65 63 74 69 6f 6e 20 56 41 43 55 55  ##.Section VACUU
37420 4d 20 76 61 63 75 75 6d 20 56 41 43 55 55 4d 0a  M vacuum VACUUM.
37430 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65  .RecursiveBubble
37440 44 69 61 67 72 61 6d 20 76 61 63 75 75 6d 2d 73  Diagram vacuum-s
37450 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a  tmt.</tcl>..<p>.
37460 20 20 54 68 65 20 56 41 43 55 55 4d 20 63 6f 6d    The VACUUM com
37470 6d 61 6e 64 20 72 65 62 75 69 6c 64 73 20 74 68  mand rebuilds th
37480 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
37490 20 72 65 70 61 63 6b 69 6e 67 20 69 74 20 69 6e   repacking it in
374a0 74 6f 20 61 20 6d 69 6e 69 6d 61 6c 0a 20 20 61  to a minimal.  a
374b0 6d 6f 75 6e 74 20 6f 66 20 64 69 73 6b 20 73 70  mount of disk sp
374c0 61 63 65 2e 20 54 68 65 72 65 20 61 72 65 20 73  ace. There are s
374d0 65 76 65 72 61 6c 20 0a 20 20 72 65 61 73 6f 6e  everal .  reason
374e0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
374f0 20 6d 69 67 68 74 20 64 6f 20 74 68 69 73 3a 0a   might do this:.
37500 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e  .<ul>.  <li> <p>
37510 20 5e 55 6e 6c 65 73 73 20 53 51 4c 69 74 65 20   ^Unless SQLite 
37520 69 73 20 72 75 6e 6e 69 6e 67 20 69 6e 20 22 61  is running in "a
37530 75 74 6f 5f 76 61 63 75 75 6d 3d 46 55 4c 4c 22  uto_vacuum=FULL"
37540 20 6d 6f 64 65 2c 20 77 68 65 6e 20 61 20 6c 61   mode, when a la
37550 72 67 65 0a 20 20 20 20 20 61 6d 6f 75 6e 74 20  rge.     amount 
37560 6f 66 20 64 61 74 61 20 69 73 20 64 65 6c 65 74  of data is delet
37570 65 64 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61  ed from the data
37580 62 61 73 65 20 66 69 6c 65 20 69 74 20 6c 65 61  base file it lea
37590 76 65 73 20 62 65 68 69 6e 64 20 65 6d 70 74 79  ves behind empty
375a0 0a 20 20 20 20 20 73 70 61 63 65 2c 20 6f 72 20  .     space, or 
375b0 22 66 72 65 65 22 20 64 61 74 61 62 61 73 65 20  "free" database 
375c0 70 61 67 65 73 2e 20 54 68 69 73 20 6d 65 61 6e  pages. This mean
375d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
375e0 69 6c 65 20 6d 69 67 68 74 0a 20 20 20 20 20 62  ile might.     b
375f0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 74  e larger than st
37600 72 69 63 74 6c 79 20 6e 65 63 65 73 73 61 72 79  rictly necessary
37610 2e 20 5e 52 75 6e 6e 69 6e 67 20 56 41 43 55 55  . ^Running VACUU
37620 4d 20 74 6f 20 72 65 62 75 69 6c 64 20 74 68 65  M to rebuild the
37630 20 0a 20 20 20 20 20 64 61 74 61 62 61 73 65 20   .     database 
37640 72 65 63 6c 61 69 6d 73 20 74 68 69 73 20 73 70  reclaims this sp
37650 61 63 65 20 61 6e 64 20 72 65 64 75 63 65 73 20  ace and reduces 
37660 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
37670 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 0a  database file...
37680 20 20 3c 6c 69 3e 20 3c 70 3e 20 5e 46 72 65 71    <li> <p> ^Freq
37690 75 65 6e 74 20 69 6e 73 65 72 74 73 2c 20 75 70  uent inserts, up
376a0 64 61 74 65 73 2c 20 61 6e 64 20 64 65 6c 65 74  dates, and delet
376b0 65 73 20 63 61 6e 20 63 61 75 73 65 20 74 68 65  es can cause the
376c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 20   database file. 
376d0 20 20 20 20 74 6f 20 62 65 63 6f 6d 65 20 66 72      to become fr
376e0 61 67 6d 65 6e 74 65 64 20 2d 20 77 68 65 72 65  agmented - where
376f0 20 64 61 74 61 20 66 6f 72 20 61 20 73 69 6e 67   data for a sing
37700 6c 65 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65  le table or inde
37710 78 20 69 73 20 73 63 61 74 74 65 72 65 64 20 0a  x is scattered .
37720 20 20 20 20 20 61 72 6f 75 6e 64 20 74 68 65 20       around the 
37730 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 5e  database file. ^
37740 52 75 6e 6e 69 6e 67 20 56 41 43 55 55 4d 20 65  Running VACUUM e
37750 6e 73 75 72 65 73 20 74 68 61 74 20 65 61 63 68  nsures that each
37760 20 74 61 62 6c 65 20 61 6e 64 0a 20 20 20 20 20   table and.     
37770 69 6e 64 65 78 20 69 73 20 6c 61 72 67 65 6c 79  index is largely
37780 20 73 74 6f 72 65 64 20 63 6f 6e 74 69 67 75 6f   stored contiguo
37790 75 73 6c 79 20 77 69 74 68 69 6e 20 74 68 65 20  usly within the 
377a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 5e  database file. ^
377b0 49 6e 20 73 6f 6d 65 0a 20 20 20 20 20 63 61 73  In some.     cas
377c0 65 73 2c 20 56 41 43 55 55 4d 20 6d 61 79 20 61  es, VACUUM may a
377d0 6c 73 6f 20 72 65 64 75 63 65 20 74 68 65 20 6e  lso reduce the n
377e0 75 6d 62 65 72 20 6f 66 20 70 61 72 74 69 61 6c  umber of partial
377f0 6c 79 20 66 69 6c 6c 65 64 20 70 61 67 65 73 20  ly filled pages 
37800 69 6e 0a 20 20 20 20 20 74 68 65 20 64 61 74 61  in.     the data
37810 62 61 73 65 2c 20 72 65 64 75 63 69 6e 67 20 74  base, reducing t
37820 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
37830 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 75 72  atabase file fur
37840 74 68 65 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70  ther...  <li> <p
37850 3e 20 57 68 65 6e 20 63 6f 6e 74 65 6e 74 20 69  > When content i
37860 73 20 64 65 6c 65 74 65 64 20 66 72 6f 6d 20 61  s deleted from a
37870 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
37880 65 2c 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 69  e, the content i
37890 73 20 6e 6f 74 0a 20 20 20 20 20 75 73 75 61 6c  s not.     usual
378a0 6c 79 20 65 72 61 73 65 64 20 62 75 74 20 72 61  ly erased but ra
378b0 74 68 65 72 20 74 68 65 20 73 70 61 63 65 20 75  ther the space u
378c0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  sed to hold the 
378d0 63 6f 6e 74 65 6e 74 20 69 73 20 6d 61 72 6b 65  content is marke
378e0 64 20 61 73 0a 20 20 20 20 20 62 65 69 6e 67 20  d as.     being 
378f0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65  available for re
37900 75 73 65 2e 20 20 54 68 69 73 20 63 61 6e 20 61  use.  This can a
37910 6c 6c 6f 77 20 64 65 6c 65 74 65 64 20 63 6f 6e  llow deleted con
37920 74 65 6e 74 20 74 6f 20 62 65 20 72 65 63 6f 76  tent to be recov
37930 65 72 65 64 0a 20 20 20 20 20 62 79 20 61 20 68  ered.     by a h
37940 61 63 6b 65 72 20 6f 72 20 62 79 20 66 6f 72 65  acker or by fore
37950 6e 73 69 63 20 61 6e 61 6c 79 73 69 73 2e 20 20  nsic analysis.  
37960 52 75 6e 6e 69 6e 67 20 56 41 43 55 55 4d 20 77  Running VACUUM w
37970 69 6c 6c 20 63 6c 65 61 6e 20 74 68 65 20 64 61  ill clean the da
37980 74 61 62 61 73 65 0a 20 20 20 20 20 6f 66 20 61  tabase.     of a
37990 6c 6c 20 74 72 61 63 65 73 20 6f 66 20 64 65 6c  ll traces of del
379a0 65 74 65 64 20 63 6f 6e 74 65 6e 74 2c 20 74 68  eted content, th
379b0 75 73 20 70 72 65 76 65 6e 74 69 6e 67 20 61 6e  us preventing an
379c0 20 61 64 76 65 72 73 61 72 79 20 66 72 6f 6d 20   adversary from 
379d0 72 65 63 6f 76 65 72 69 6e 67 0a 20 20 20 20 20  recovering.     
379e0 64 65 6c 65 74 65 64 20 63 6f 6e 74 65 6e 74 2e  deleted content.
379f0 20 20 55 73 69 6e 67 20 56 41 43 55 55 4d 20 69    Using VACUUM i
37a00 6e 20 74 68 69 73 20 77 61 79 20 69 73 20 61 6e  n this way is an
37a10 20 61 6c 74 65 72 6e 61 74 69 76 65 20 74 6f 20   alternative to 
37a20 73 65 74 74 69 6e 67 0a 20 20 20 20 20 5b 50 52  setting.     [PR
37a30 41 47 4d 41 20 73 65 63 75 72 65 5f 64 65 6c 65  AGMA secure_dele
37a40 74 65 3d 4f 4e 5d 2e 20 0a 0a 20 20 3c 6c 69 3e  te=ON]. ..  <li>
37a50 20 3c 70 3e 20 5e 4e 6f 72 6d 61 6c 6c 79 2c 20   <p> ^Normally, 
37a60 74 68 65 20 64 61 74 61 62 61 73 65 20 5b 70 61  the database [pa
37a70 67 65 5f 73 69 7a 65 5d 20 61 6e 64 20 77 68 65  ge_size] and whe
37a80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
37a90 64 61 74 61 62 61 73 65 0a 20 20 20 20 20 73 75  database.     su
37aa0 70 70 6f 72 74 73 20 5b 61 75 74 6f 5f 76 61 63  pports [auto_vac
37ab0 75 75 6d 5d 20 6d 75 73 74