Documentation Source Text

Hex Artifact Content
Login

Artifact 709bea593834b5fa171ee6090c0b9a10c3ad5feb5f20601cc7e9b2bdb6d32dbb:


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 2f 75 6c 3e 0a 0a 3c 70   NULL..</ul>..<p
1ef0: 3e 5e 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  >^Note also that
1f00: 20 77 68 65 6e 20 61 64 64 69 6e 67 20 61 20 5b   when adding a [
1f10: 43 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74  CHECK constraint
1f20: 5d 2c 20 74 68 65 20 43 48 45 43 4b 20 63 6f 6e  ], the CHECK con
1f30: 73 74 72 61 69 6e 74 0a 69 73 20 6e 6f 74 20 74  straint.is not t
1f40: 65 73 74 65 64 20 61 67 61 69 6e 73 74 20 70 72  ested against pr
1f50: 65 65 78 69 73 74 69 6e 67 20 72 6f 77 73 20 6f  eexisting rows o
1f60: 66 20 74 68 65 20 74 61 62 6c 65 2e 0a 5e 54 68  f the table..^Th
1f70: 69 73 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  is can result in
1f80: 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 63 6f   a table that co
1f90: 6e 74 61 69 6e 73 20 64 61 74 61 20 74 68 61 74  ntains data that
1fa0: 0a 69 73 20 69 6e 20 76 69 6f 6c 61 74 69 6f 6e  .is in violation
1fb0: 20 6f 66 20 74 68 65 20 43 48 45 43 4b 20 63 6f   of the CHECK co
1fc0: 6e 73 74 72 61 69 6e 74 2e 20 20 46 75 74 75 72  nstraint.  Futur
1fd0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1fe0: 4c 69 74 65 20 6d 69 67 68 74 0a 63 68 61 6e 67  Lite might.chang
1ff0: 65 20 74 6f 20 76 61 6c 69 64 61 74 65 20 43 48  e to validate CH
2000: 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ECK constraints 
2010: 61 73 20 74 68 65 79 20 61 72 65 20 61 64 64 65  as they are adde
2020: 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 41  d.</p>..<p>The A
2030: 4c 54 45 52 20 54 41 42 4c 45 20 63 6f 6d 6d 61  LTER TABLE comma
2040: 6e 64 20 77 6f 72 6b 73 20 62 79 20 6d 6f 64 69  nd works by modi
2050: 66 79 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  fying the SQL te
2060: 78 74 20 6f 66 20 74 68 65 20 73 63 68 65 6d 61  xt of the schema
2070: 0a 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 5b  .stored in the [
2080: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 74 61  sqlite_master ta
2090: 62 6c 65 5d 2e 0a 4e 6f 20 63 68 61 6e 67 65 73  ble]..No changes
20a0: 20 61 72 65 20 6d 61 64 65 20 74 6f 20 74 61 62   are made to tab
20b0: 6c 65 20 63 6f 6e 74 65 6e 74 2e 0a 42 65 63 61  le content..Beca
20c0: 75 73 65 20 6f 66 20 74 68 69 73 2c 0a 74 68 65  use of this,.the
20d0: 20 65 78 65 63 75 74 69 6f 6e 20 74 69 6d 65 20   execution time 
20e0: 6f 66 20 74 68 65 20 41 4c 54 45 52 20 54 41 42  of the ALTER TAB
20f0: 4c 45 20 63 6f 6d 6d 61 6e 64 20 69 73 20 69 6e  LE command is in
2100: 64 65 70 65 6e 64 65 6e 74 20 6f 66 0a 74 68 65  dependent of.the
2110: 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2120: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54  in the table.  T
2130: 68 65 20 41 4c 54 45 52 20 54 41 42 4c 45 20 63  he ALTER TABLE c
2140: 6f 6d 6d 61 6e 64 20 72 75 6e 73 20 61 73 20 71  ommand runs as q
2150: 75 69 63 6b 6c 79 0a 6f 6e 20 61 20 74 61 62 6c  uickly.on a tabl
2160: 65 20 77 69 74 68 20 31 30 20 6d 69 6c 6c 69 6f  e with 10 millio
2170: 6e 20 72 6f 77 73 20 61 73 20 69 74 20 64 6f 65  n rows as it doe
2180: 73 20 6f 6e 20 61 20 74 61 62 6c 65 20 77 69 74  s on a table wit
2190: 68 20 31 20 72 6f 77 2e 0a 3c 2f 70 3e 0a 0a 3c  h 1 row..</p>..<
21a0: 70 3e 41 66 74 65 72 20 41 44 44 20 43 4f 4c 55  p>After ADD COLU
21b0: 4d 4e 20 68 61 73 20 62 65 65 6e 20 72 75 6e 20  MN has been run 
21c0: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 2c 20 74  on a database, t
21d0: 68 61 74 20 64 61 74 61 62 61 73 65 20 77 69 6c  hat database wil
21e0: 6c 20 6e 6f 74 0a 62 65 20 72 65 61 64 61 62 6c  l not.be readabl
21f0: 65 20 62 79 20 53 51 4c 69 74 65 20 76 65 72 73  e by SQLite vers
2200: 69 6f 6e 20 33 2e 31 2e 33 20 28 5b 64 61 74 65  ion 3.1.3 ([date
2210: 6f 66 3a 33 2e 31 2e 33 5d 29 20 61 6e 64 20 65  of:3.1.3]) and e
2220: 61 72 6c 69 65 72 2e 3c 2f 70 3e 0a 0a 3c 74 63  arlier.</p>..<tc
2230: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6f 74  l>hd_fragment ot
2240: 68 65 72 61 6c 74 65 72 20 7b 67 65 6e 65 72 61  heralter {genera
2250: 6c 69 7a 65 64 20 41 4c 54 45 52 20 54 41 42 4c  lized ALTER TABL
2260: 45 20 70 72 6f 63 65 64 75 72 65 7d 3c 2f 74 63  E procedure}</tc
2270: 6c 3e 0a 3c 68 33 3e 4d 61 6b 69 6e 67 20 4f 74  l>.<h3>Making Ot
2280: 68 65 72 20 4b 69 6e 64 73 20 4f 66 20 54 61 62  her Kinds Of Tab
2290: 6c 65 20 53 63 68 65 6d 61 20 43 68 61 6e 67 65  le Schema Change
22a0: 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20  s</h3>..<p> The 
22b0: 6f 6e 6c 79 20 73 63 68 65 6d 61 20 61 6c 74 65  only schema alte
22c0: 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 73 20 64 69  ring commands di
22d0: 72 65 63 74 6c 79 20 73 75 70 70 6f 72 74 65 64  rectly supported
22e0: 20 62 79 20 53 51 4c 69 74 65 20 61 72 65 20 74   by SQLite are t
22f0: 68 65 0a 22 5b 72 65 6e 61 6d 65 20 74 61 62 6c  he."[rename tabl
2300: 65 5d 22 2c 20 22 5b 72 65 6e 61 6d 65 20 63 6f  e]", "[rename co
2310: 6c 75 6d 6e 5d 22 2c 20 61 6e 64 20 22 5b 61 64  lumn]", and "[ad
2320: 64 20 63 6f 6c 75 6d 6e 5d 22 20 63 6f 6d 6d 61  d column]" comma
2330: 6e 64 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e  nds shown above.
2340: 20 20 0a 48 6f 77 65 76 65 72 2c 20 61 70 70 6c    .However, appl
2350: 69 63 61 74 69 6f 6e 73 0a 63 61 6e 20 6d 61 6b  ications.can mak
2360: 65 20 6f 74 68 65 72 20 61 72 62 69 74 72 61 72  e other arbitrar
2370: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
2380: 20 66 6f 72 6d 61 74 20 6f 66 20 61 20 74 61 62   format of a tab
2390: 6c 65 20 75 73 69 6e 67 20 61 20 73 69 6d 70 6c  le using a simpl
23a0: 65 0a 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 70  e.sequence of op
23b0: 65 72 61 74 69 6f 6e 73 2e 0a 54 68 65 20 73 74  erations..The st
23c0: 65 70 73 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  eps to make arbi
23d0: 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
23e0: 20 74 68 65 20 73 63 68 65 6d 61 20 64 65 73 69   the schema desi
23f0: 67 6e 20 6f 66 20 73 6f 6d 65 20 74 61 62 6c 65  gn of some table
2400: 20 58 0a 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77   X.are as follow
2410: 73 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e  s:..<ol>.<li><p>
2420: 0a 49 66 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  .If foreign key 
2430: 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 72 65 20  constraints are 
2440: 65 6e 61 62 6c 65 64 2c 20 64 69 73 61 62 6c 65  enabled, disable
2450: 20 74 68 65 6d 20 75 73 69 6e 67 20 5b 50 52 41   them using [PRA
2460: 47 4d 41 20 66 6f 72 65 69 67 6e 5f 6b 65 79 73  GMA foreign_keys
2470: 3d 4f 46 46 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a  =OFF]...<li><p>.
2480: 53 74 61 72 74 20 61 20 74 72 61 6e 73 61 63 74  Start a transact
2490: 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 52 65  ion...<li><p>.Re
24a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 6f 72 6d 61  member the forma
24b0: 74 20 6f 66 20 61 6c 6c 20 69 6e 64 65 78 65 73  t of all indexes
24c0: 2c 20 74 72 69 67 67 65 72 73 2c 20 61 6e 64 20  , triggers, and 
24d0: 76 69 65 77 73 20 61 73 73 6f 63 69 61 74 65 64  views associated
24e0: 20 77 69 74 68 20 74 61 62 6c 65 20 58 2e 0a 54   with table X..T
24f0: 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  his information 
2500: 77 69 6c 6c 20 62 65 20 6e 65 65 64 65 64 20 69  will be needed i
2510: 6e 20 73 74 65 70 20 38 20 62 65 6c 6f 77 2e 20  n step 8 below. 
2520: 20 4f 6e 65 20 77 61 79 20 74 6f 20 64 6f 20 74   One way to do t
2530: 68 69 73 20 69 73 0a 74 6f 20 72 75 6e 20 61 20  his is.to run a 
2540: 71 75 65 72 79 20 6c 69 6b 65 20 74 68 65 20 66  query like the f
2550: 6f 6c 6c 6f 77 69 6e 67 3a 0a 53 45 4c 45 43 54  ollowing:.SELECT
2560: 20 74 79 70 65 2c 20 73 71 6c 20 46 52 4f 4d 20   type, sql FROM 
2570: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 57 48  sqlite_master WH
2580: 45 52 45 20 74 62 6c 5f 6e 61 6d 65 3d 27 58 27  ERE tbl_name='X'
2590: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20 5b  ...<li><p>.Use [
25a0: 43 52 45 41 54 45 20 54 41 42 4c 45 5d 20 74 6f  CREATE TABLE] to
25b0: 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
25c0: 20 74 61 62 6c 65 20 22 6e 65 77 5f 58 22 20 74   table "new_X" t
25d0: 68 61 74 20 69 73 20 69 6e 20 74 68 65 20 64 65  hat is in the de
25e0: 73 69 72 65 64 0a 72 65 76 69 73 65 64 20 66 6f  sired.revised fo
25f0: 72 6d 61 74 20 6f 66 20 74 61 62 6c 65 20 58 2e  rmat of table X.
2600: 20 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74    Make sure that
2610: 20 74 68 65 20 6e 61 6d 65 20 22 6e 65 77 5f 58   the name "new_X
2620: 22 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6c 6c 69  " does not colli
2630: 64 65 0a 77 69 74 68 20 61 6e 79 20 65 78 69 73  de.with any exis
2640: 74 69 6e 67 20 74 61 62 6c 65 20 6e 61 6d 65 2c  ting table name,
2650: 20 6f 66 20 63 6f 75 72 73 65 2e 0a 0a 3c 6c 69   of course...<li
2660: 3e 3c 70 3e 0a 54 72 61 6e 73 66 65 72 20 63 6f  ><p>.Transfer co
2670: 6e 74 65 6e 74 20 66 72 6f 6d 20 58 20 69 6e 74  ntent from X int
2680: 6f 20 6e 65 77 5f 58 20 75 73 69 6e 67 20 61 20  o new_X using a 
2690: 73 74 61 74 65 6d 65 6e 74 0a 6c 69 6b 65 3a 20  statement.like: 
26a0: 49 4e 53 45 52 54 20 49 4e 54 4f 20 6e 65 77 5f  INSERT INTO new_
26b0: 58 20 53 45 4c 45 43 54 20 2e 2e 2e 20 46 52 4f  X SELECT ... FRO
26c0: 4d 20 58 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 44 72  M X...<li><p>.Dr
26d0: 6f 70 20 74 68 65 20 6f 6c 64 20 74 61 62 6c 65  op the old table
26e0: 20 58 3a 20 20 5b 44 52 4f 50 20 54 41 42 4c 45   X:  [DROP TABLE
26f0: 20 7c 20 44 52 4f 50 20 54 41 42 4c 45 20 58 5d   | DROP TABLE X]
2700: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 68 61 6e 67  ...<li><p>.Chang
2710: 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 6e 65  e the name of ne
2720: 77 5f 58 20 74 6f 20 58 20 75 73 69 6e 67 3a 20  w_X to X using: 
2730: 41 4c 54 45 52 20 54 41 42 4c 45 20 6e 65 77 5f  ALTER TABLE new_
2740: 58 20 52 45 4e 41 4d 45 20 54 4f 20 58 2e 0a 0a  X RENAME TO X...
2750: 3c 6c 69 3e 3c 70 3e 0a 55 73 65 20 5b 43 52 45  <li><p>.Use [CRE
2760: 41 54 45 20 49 4e 44 45 58 5d 2c 20 5b 43 52 45  ATE INDEX], [CRE
2770: 41 54 45 20 54 52 49 47 47 45 52 5d 2c 20 61 6e  ATE TRIGGER], an
2780: 64 20 5b 43 52 45 41 54 45 20 56 49 45 57 5d 0a  d [CREATE VIEW].
2790: 74 6f 20 72 65 63 6f 6e 73 74 72 75 63 74 20 69  to reconstruct i
27a0: 6e 64 65 78 65 73 2c 20 74 72 69 67 67 65 72 73  ndexes, triggers
27b0: 2c 20 61 6e 64 20 76 69 65 77 73 0a 61 73 73 6f  , and views.asso
27c0: 63 69 61 74 65 64 20 77 69 74 68 20 74 61 62 6c  ciated with tabl
27d0: 65 20 58 2e 20 20 50 65 72 68 61 70 73 20 75 73  e X.  Perhaps us
27e0: 65 20 74 68 65 20 6f 6c 64 20 66 6f 72 6d 61 74  e the old format
27f0: 20 6f 66 20 74 68 65 20 74 72 69 67 67 65 72 73   of the triggers
2800: 2c 0a 69 6e 64 65 78 65 73 2c 20 61 6e 64 20 76  ,.indexes, and v
2810: 69 65 77 73 20 73 61 76 65 64 20 66 72 6f 6d 20  iews saved from 
2820: 73 74 65 70 20 33 20 61 62 6f 76 65 20 61 73 20  step 3 above as 
2830: 61 20 67 75 69 64 65 2c 20 6d 61 6b 69 6e 67 20  a guide, making 
2840: 63 68 61 6e 67 65 73 0a 61 73 20 61 70 70 72 6f  changes.as appro
2850: 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 61  priate for the a
2860: 6c 74 65 72 61 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e  lteration...<li>
2870: 3c 70 3e 49 66 20 61 6e 79 20 76 69 65 77 73 20  <p>If any views 
2880: 72 65 66 65 72 20 74 6f 20 74 61 62 6c 65 20 58  refer to table X
2890: 20 69 6e 20 61 20 77 61 79 20 74 68 61 74 20 69   in a way that i
28a0: 73 20 61 66 66 65 63 74 65 64 20 62 79 20 74 68  s affected by th
28b0: 65 0a 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  e.schema change,
28c0: 20 74 68 65 6e 20 64 72 6f 70 20 74 68 6f 73 65   then drop those
28d0: 20 76 69 65 77 73 20 75 73 69 6e 67 20 5b 44 52   views using [DR
28e0: 4f 50 20 56 49 45 57 5d 20 61 6e 64 20 72 65 63  OP VIEW] and rec
28f0: 72 65 61 74 65 20 74 68 65 6d 0a 77 69 74 68 20  reate them.with 
2900: 77 68 61 74 65 76 65 72 20 63 68 61 6e 67 65 73  whatever changes
2910: 20 61 72 65 20 6e 65 63 65 73 73 61 72 79 20 74   are necessary t
2920: 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 74 68  o accommodate th
2930: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 0a  e schema change.
2940: 75 73 69 6e 67 20 5b 43 52 45 41 54 45 20 56 49  using [CREATE VI
2950: 45 57 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49 66  EW]...<li><p>.If
2960: 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e   foreign key con
2970: 73 74 72 61 69 6e 74 73 20 77 65 72 65 20 6f 72  straints were or
2980: 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c 65 64  iginally enabled
2990: 0a 74 68 65 6e 20 72 75 6e 20 5b 50 52 41 47 4d  .then run [PRAGM
29a0: 41 20 66 6f 72 65 69 67 6e 5f 6b 65 79 5f 63 68  A foreign_key_ch
29b0: 65 63 6b 5d 20 74 6f 20 76 65 72 69 66 79 20 74  eck] to verify t
29c0: 68 61 74 20 74 68 65 20 73 63 68 65 6d 61 0a 63  hat the schema.c
29d0: 68 61 6e 67 65 20 64 69 64 20 6e 6f 74 20 62 72  hange did not br
29e0: 65 61 6b 20 61 6e 79 20 66 6f 72 65 69 67 6e 20  eak any foreign 
29f0: 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e  key constraints.
2a00: 0a 0a 0a 3c 6c 69 3e 3c 70 3e 0a 43 6f 6d 6d 69  ...<li><p>.Commi
2a10: 74 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  t the transactio
2a20: 6e 20 73 74 61 72 74 65 64 20 69 6e 20 73 74 65  n started in ste
2a30: 70 20 32 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49 66  p 2...<li><p>.If
2a40: 20 66 6f 72 65 69 67 6e 20 6b 65 79 73 20 63 6f   foreign keys co
2a50: 6e 73 74 72 61 69 6e 74 73 20 77 65 72 65 20 6f  nstraints were o
2a60: 72 69 67 69 6e 61 6c 6c 79 20 65 6e 61 62 6c 65  riginally enable
2a70: 64 2c 20 72 65 65 6e 61 62 6c 65 20 74 68 65 6d  d, reenable them
2a80: 20 6e 6f 77 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 74 63   now..</ol>..<tc
2a90: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 61  l>hd_fragment ca
2aa0: 75 74 69 6f 6e 3c 2f 74 63 6c 3e 0a 3c 70 3e 0a  ution</tcl>.<p>.
2ab0: 3c 62 3e 43 61 75 74 69 6f 6e 3a 3c 2f 62 3e 0a  <b>Caution:</b>.
2ac0: 54 61 6b 65 20 63 61 72 65 20 74 6f 20 66 6f 6c  Take care to fol
2ad0: 6c 6f 77 20 74 68 65 20 70 72 6f 63 65 64 75 72  low the procedur
2ae0: 65 20 61 62 6f 76 65 20 70 72 65 63 69 73 65 6c  e above precisel
2af0: 79 2e 20 20 54 68 65 20 62 6f 78 65 73 20 62 65  y.  The boxes be
2b00: 6c 6f 77 0a 73 75 6d 6d 61 72 69 7a 65 20 74 77  low.summarize tw
2b10: 6f 20 70 72 6f 63 65 64 75 72 65 73 20 66 6f 72  o procedures for
2b20: 20 6d 6f 64 69 66 79 69 6e 67 20 61 20 74 61 62   modifying a tab
2b30: 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  le definition.  
2b40: 41 74 20 66 69 72 73 74 0a 67 6c 61 6e 63 65 2c  At first.glance,
2b50: 20 74 68 65 79 20 62 6f 74 68 20 61 70 70 65 61   they both appea
2b60: 72 20 74 6f 20 61 63 63 6f 6d 70 6c 69 73 68 20  r to accomplish 
2b70: 74 68 65 20 73 61 6d 65 20 74 68 69 6e 67 2e 20  the same thing. 
2b80: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 0a 70 72   However, the.pr
2b90: 6f 63 65 64 75 72 65 20 6f 6e 20 74 68 65 20 72  ocedure on the r
2ba0: 69 67 68 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  ight does not al
2bb0: 77 61 79 73 20 77 6f 72 6b 2c 20 65 73 70 65 63  ways work, espec
2bc0: 69 61 6c 6c 79 20 77 69 74 68 20 74 68 65 0a 65  ially with the.e
2bd0: 6e 68 61 6e 63 65 64 20 5b 72 65 6e 61 6d 65 20  nhanced [rename 
2be0: 74 61 62 6c 65 5d 20 63 61 70 61 62 69 6c 69 74  table] capabilit
2bf0: 69 65 73 20 61 64 64 65 64 20 62 79 20 76 65 72  ies added by ver
2c00: 73 69 6f 6e 73 20 33 2e 32 35 2e 30 20 61 6e 64  sions 3.25.0 and
2c10: 0a 33 2e 32 36 2e 30 2e 20 20 49 6e 20 74 68 65  .3.26.0.  In the
2c20: 20 70 72 6f 63 65 64 75 72 65 20 6f 6e 20 74 68   procedure on th
2c30: 65 20 72 69 67 68 74 2c 20 74 68 65 20 69 6e 69  e right, the ini
2c40: 74 69 61 6c 20 72 65 6e 61 6d 65 20 6f 66 20 74  tial rename of t
2c50: 68 65 0a 74 61 62 6c 65 20 74 6f 20 61 20 74 65  he.table to a te
2c60: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 6d 69 67  mporary name mig
2c70: 68 74 20 63 6f 72 72 75 70 74 20 72 65 66 65 72  ht corrupt refer
2c80: 65 6e 63 65 73 20 74 6f 20 74 68 61 74 20 74 61  ences to that ta
2c90: 62 6c 65 20 69 6e 0a 74 72 69 67 67 65 72 73 2c  ble in.triggers,
2ca0: 20 76 69 65 77 73 2c 20 61 6e 64 20 66 6f 72 65   views, and fore
2cb0: 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
2cc0: 6e 74 73 2e 20 20 54 68 65 20 73 61 66 65 20 70  nts.  The safe p
2cd0: 72 6f 63 65 64 75 72 65 20 6f 6e 0a 74 68 65 20  rocedure on.the 
2ce0: 6c 65 66 74 20 63 6f 6e 73 74 72 75 63 74 73 20  left constructs 
2cf0: 74 68 65 20 72 65 76 69 73 65 64 20 74 61 62 6c  the revised tabl
2d00: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 75 73 69  e definition usi
2d10: 6e 67 20 61 20 6e 65 77 20 74 65 6d 70 6f 72 61  ng a new tempora
2d20: 72 79 0a 6e 61 6d 65 2c 20 74 68 65 6e 20 72 65  ry.name, then re
2d30: 6e 61 6d 65 73 20 74 68 65 20 74 61 62 6c 65 20  names the table 
2d40: 69 6e 74 6f 20 69 74 73 20 66 69 6e 61 6c 20 6e  into its final n
2d50: 61 6d 65 2c 20 77 68 69 63 68 20 64 6f 65 73 20  ame, which does 
2d60: 6e 6f 74 20 62 72 65 61 6b 0a 6c 69 6e 6b 73 2e  not break.links.
2d70: 0a 0a 3c 63 65 6e 74 65 72 3e 0a 3c 74 61 62 6c  ..<center>.<tabl
2d80: 65 20 62 6f 72 64 65 72 3d 22 31 22 20 63 65 6c  e border="1" cel
2d90: 6c 70 61 64 64 69 6e 67 3d 22 31 30 22 20 63 65  lpadding="10" ce
2da0: 6c 6c 73 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c  llspacing="0">.<
2db0: 74 72 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22  tr>.<td valign="
2dc0: 74 6f 70 22 3e 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 43  top">.<ol>.<li>C
2dd0: 72 65 61 74 65 20 6e 65 77 20 74 61 62 6c 65 0a  reate new table.
2de0: 3c 6c 69 3e 43 6f 70 79 20 64 61 74 61 0a 3c 6c  <li>Copy data.<l
2df0: 69 3e 44 72 6f 70 20 6f 6c 64 20 74 61 62 6c 65  i>Drop old table
2e00: 0a 3c 6c 69 3e 52 65 6e 61 6d 65 20 6e 65 77 20  .<li>Rename new 
2e10: 69 6e 74 6f 20 6f 6c 64 0a 3c 2f 6f 6c 3e 0a 3c  into old.</ol>.<
2e20: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
2e30: 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 52 65 6e 61 6d 65  .<ol>.<li>Rename
2e40: 20 6f 6c 64 20 74 61 62 6c 65 0a 3c 6c 69 3e 43   old table.<li>C
2e50: 72 65 61 74 65 20 6e 65 77 20 74 61 62 6c 65 0a  reate new table.
2e60: 3c 6c 69 3e 43 6f 70 79 20 64 61 74 61 0a 3c 6c  <li>Copy data.<l
2e70: 69 3e 44 72 6f 70 20 6f 6c 64 20 74 61 62 6c 65  i>Drop old table
2e80: 0a 3c 2f 6f 6c 3e 0a 3c 74 72 3e 0a 3c 74 68 3e  .</ol>.<tr>.<th>
2e90: 26 75 61 72 72 3b 3c 62 72 3e 43 6f 72 72 65 63  &uarr;<br>Correc
2ea0: 74 0a 3c 74 68 3e 26 75 61 72 72 3b 3c 62 72 3e  t.<th>&uarr;<br>
2eb0: 49 6e 63 6f 72 72 65 63 74 0a 3c 2f 74 61 62 6c  Incorrect.</tabl
2ec0: 65 3e 0a 3c 2f 63 65 6e 74 65 72 3e 0a 0a 3c 70  e>.</center>..<p
2ed0: 3e 54 68 65 20 31 32 2d 73 74 65 70 20 5b 67 65  >The 12-step [ge
2ee0: 6e 65 72 61 6c 69 7a 65 64 20 41 4c 54 45 52 20  neralized ALTER 
2ef0: 54 41 42 4c 45 20 70 72 6f 63 65 64 75 72 65 5d  TABLE procedure]
2f00: 0a 61 62 6f 76 65 20 77 69 6c 6c 20 77 6f 72 6b  .above will work
2f10: 20 65 76 65 6e 20 69 66 20 74 68 65 0a 73 63 68   even if the.sch
2f20: 65 6d 61 20 63 68 61 6e 67 65 20 63 61 75 73 65  ema change cause
2f30: 73 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f  s the informatio
2f40: 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  n stored in the 
2f50: 74 61 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 2e  table to change.
2f60: 0a 53 6f 20 74 68 65 20 66 75 6c 6c 20 31 32 2d  .So the full 12-
2f70: 73 74 65 70 20 70 72 6f 63 65 64 75 72 65 20 61  step procedure a
2f80: 62 6f 76 65 20 69 73 20 61 70 70 72 6f 70 72 69  bove is appropri
2f90: 61 74 65 20 66 6f 72 20 64 72 6f 70 70 69 6e 67  ate for dropping
2fa0: 20 61 20 63 6f 6c 75 6d 6e 2c 0a 63 68 61 6e 67   a column,.chang
2fb0: 69 6e 67 20 74 68 65 20 6f 72 64 65 72 20 6f 66  ing the order of
2fc0: 20 63 6f 6c 75 6d 6e 73 2c 20 61 64 64 69 6e 67   columns, adding
2fd0: 20 6f 72 20 72 65 6d 6f 76 69 6e 67 20 61 20 55   or removing a U
2fe0: 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74  NIQUE constraint
2ff0: 0a 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  .or PRIMARY KEY,
3000: 20 61 64 64 69 6e 67 20 43 48 45 43 4b 20 6f 72   adding CHECK or
3010: 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72 20   FOREIGN KEY or 
3020: 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
3030: 69 6e 74 73 2c 0a 6f 72 20 63 68 61 6e 67 69 6e  ints,.or changin
3040: 67 20 74 68 65 20 64 61 74 61 74 79 70 65 20 66  g the datatype f
3050: 6f 72 20 61 20 63 6f 6c 75 6d 6e 2c 20 66 6f 72  or a column, for
3060: 20 65 78 61 6d 70 6c 65 2e 20 20 48 6f 77 65 76   example.  Howev
3070: 65 72 2c 20 61 20 73 69 6d 70 6c 65 72 0a 61 6e  er, a simpler.an
3080: 64 20 66 61 73 74 65 72 20 70 72 6f 63 65 64 75  d faster procedu
3090: 72 65 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  re can optionall
30a0: 79 20 62 65 20 75 73 65 64 20 66 6f 72 0a 73 6f  y be used for.so
30b0: 6d 65 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  me changes that 
30c0: 64 6f 20 6e 6f 20 61 66 66 65 63 74 20 74 68 65  do no affect the
30d0: 20 6f 6e 2d 64 69 73 6b 20 63 6f 6e 74 65 6e 74   on-disk content
30e0: 20 69 6e 20 61 6e 79 20 77 61 79 2e 0a 54 68 65   in any way..The
30f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 69 6d 70 6c   following simpl
3100: 65 72 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  er procedure is 
3110: 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
3120: 72 65 6d 6f 76 69 6e 67 0a 43 48 45 43 4b 20 6f  removing.CHECK o
3130: 72 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 6f 72  r FOREIGN KEY or
3140: 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
3150: 61 69 6e 74 73 2c 0a 6f 72 20 61 64 64 69 6e 67  aints,.or adding
3160: 2c 20 72 65 6d 6f 76 69 6e 67 2c 20 6f 72 20 63  , removing, or c
3170: 68 61 6e 67 69 6e 67 20 64 65 66 61 75 6c 74 20  hanging default 
3180: 76 61 6c 75 65 73 20 6f 6e 0a 61 20 63 6f 6c 75  values on.a colu
3190: 6d 6e 2e 0a 0a 3c 6f 6c 3e 0a 3c 6c 49 3e 3c 70  mn...<ol>.<lI><p
31a0: 3e 20 53 74 61 72 74 20 61 20 74 72 61 6e 73 61  > Start a transa
31b0: 63 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e 20  ction...<li><p> 
31c0: 52 75 6e 20 5b 50 52 41 47 4d 41 20 73 63 68 65  Run [PRAGMA sche
31d0: 6d 61 5f 76 65 72 73 69 6f 6e 5d 20 74 6f 20 64  ma_version] to d
31e0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 63 75 72  etermine the cur
31f0: 72 65 6e 74 20 73 63 68 65 6d 61 0a 76 65 72 73  rent schema.vers
3200: 69 6f 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ion number.  Thi
3210: 73 20 6e 75 6d 62 65 72 20 77 69 6c 6c 20 62 65  s number will be
3220: 20 6e 65 65 64 65 64 20 66 6f 72 20 73 74 65 70   needed for step
3230: 20 36 20 62 65 6c 6f 77 2e 0a 0a 3c 6c 69 3e 3c   6 below...<li><
3240: 70 3e 20 41 63 74 69 76 61 74 65 20 73 63 68 65  p> Activate sche
3250: 6d 61 20 65 64 69 74 69 6e 67 20 75 73 69 6e 67  ma editing using
3260: 20 0a 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62   .[PRAGMA writab
3270: 6c 65 5f 73 63 68 65 6d 61 20 7c 20 50 52 41 47  le_schema | PRAG
3280: 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65  MA writable_sche
3290: 6d 61 3d 4f 4e 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e  ma=ON]...<li><p>
32a0: 20 52 75 6e 20 61 6e 20 5b 55 50 44 41 54 45 5d   Run an [UPDATE]
32b0: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 68   statement to ch
32c0: 61 6e 67 65 20 74 68 65 20 64 65 66 69 6e 69 74  ange the definit
32d0: 69 6f 6e 20 6f 66 20 74 61 62 6c 65 20 58 0a 69  ion of table X.i
32e0: 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 6d 61  n the [sqlite_ma
32f0: 73 74 65 72 20 74 61 62 6c 65 5d 3a 20 0a 55 50  ster table]: .UP
3300: 44 41 54 45 20 73 71 6c 69 74 65 5f 6d 61 73 74  DATE sqlite_mast
3310: 65 72 20 53 45 54 20 73 71 6c 3d 2e 2e 2e 20 57  er SET sql=... W
3320: 48 45 52 45 20 74 79 70 65 3d 27 74 61 62 6c 65  HERE type='table
3330: 27 20 41 4e 44 20 6e 61 6d 65 3d 27 58 27 3b 0a  ' AND name='X';.
3340: 3c 70 3e 3c 65 6d 3e 43 61 75 74 69 6f 6e 3a 3c  <p><em>Caution:<
3350: 2f 65 6d 3e 20 20 4d 61 6b 69 6e 67 20 61 20 63  /em>  Making a c
3360: 68 61 6e 67 65 20 74 6f 20 74 68 65 20 73 71 6c  hange to the sql
3370: 69 74 65 5f 6d 61 73 74 65 72 20 74 61 62 6c 65  ite_master table
3380: 20 6c 69 6b 65 20 74 68 69 73 20 77 69 6c 6c 0a   like this will.
3390: 72 65 6e 64 65 72 20 74 68 65 20 64 61 74 61 62  render the datab
33a0: 61 73 65 20 63 6f 72 72 75 70 74 20 61 6e 64 20  ase corrupt and 
33b0: 75 6e 72 65 61 64 61 62 6c 65 20 69 66 20 74 68  unreadable if th
33c0: 65 20 63 68 61 6e 67 65 20 63 6f 6e 74 61 69 6e  e change contain
33d0: 73 0a 61 20 73 79 6e 74 61 78 20 65 72 72 6f 72  s.a syntax error
33e0: 2e 20 20 49 74 20 69 73 20 73 75 67 67 65 73 74  .  It is suggest
33f0: 65 64 20 74 68 61 74 20 63 61 72 65 66 75 6c 20  ed that careful 
3400: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 55  testing of the U
3410: 50 44 41 54 45 0a 73 74 61 74 65 6d 65 6e 74 20  PDATE.statement 
3420: 62 65 20 64 6f 6e 65 20 6f 6e 20 61 20 73 65 70  be done on a sep
3430: 61 72 61 74 65 20 62 6c 61 6e 6b 20 64 61 74 61  arate blank data
3440: 62 61 73 65 20 70 72 69 6f 72 20 74 6f 20 75 73  base prior to us
3450: 69 6e 67 20 69 74 20 6f 6e 0a 61 20 64 61 74 61  ing it on.a data
3460: 62 61 73 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  base containing 
3470: 69 6d 70 6f 72 74 61 6e 74 20 64 61 74 61 2e 0a  important data..
3480: 0a 3c 6c 69 3e 3c 70 3e 20 49 66 20 74 68 65 20  .<li><p> If the 
3490: 63 68 61 6e 67 65 20 74 6f 20 74 61 62 6c 65 20  change to table 
34a0: 58 20 61 6c 73 6f 20 61 66 66 65 63 74 73 20 6f  X also affects o
34b0: 74 68 65 72 20 74 61 62 6c 65 73 20 6f 72 20 69  ther tables or i
34c0: 6e 64 65 78 65 73 20 6f 72 0a 74 72 69 67 67 65  ndexes or.trigge
34d0: 72 73 20 61 72 65 20 76 69 65 77 73 20 77 69 74  rs are views wit
34e0: 68 69 6e 20 73 63 68 65 6d 61 2c 20 74 68 65 6e  hin schema, then
34f0: 20 72 75 6e 20 5b 55 50 44 41 54 45 5d 20 73 74   run [UPDATE] st
3500: 61 74 65 6d 65 6e 74 73 20 74 6f 20 6d 6f 64 69  atements to modi
3510: 66 79 0a 74 68 6f 73 65 20 6f 74 68 65 72 20 74  fy.those other t
3520: 61 62 6c 65 73 20 69 6e 64 65 78 65 73 20 61 6e  ables indexes an
3530: 64 20 76 69 65 77 73 20 74 6f 6f 2e 20 20 46 6f  d views too.  Fo
3540: 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  r example, if th
3550: 65 20 6e 61 6d 65 20 6f 66 0a 61 20 63 6f 6c 75  e name of.a colu
3560: 6d 6e 20 63 68 61 6e 67 65 73 2c 20 61 6c 6c 20  mn changes, all 
3570: 46 4f 52 45 49 47 4e 20 4b 45 59 20 63 6f 6e 73  FOREIGN KEY cons
3580: 74 72 61 69 6e 74 73 2c 20 74 72 69 67 67 65 72  traints, trigger
3590: 73 2c 20 69 6e 64 65 78 65 73 2c 20 61 6e 64 0a  s, indexes, and.
35a0: 76 69 65 77 73 20 74 68 61 74 20 72 65 66 65 72  views that refer
35b0: 20 74 6f 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   to that column 
35c0: 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64  must be modified
35d0: 2e 0a 3c 70 3e 3c 65 6d 3e 43 61 75 74 69 6f 6e  ..<p><em>Caution
35e0: 3a 3c 2f 65 6d 3e 20 20 4f 6e 63 65 20 61 67 61  :</em>  Once aga
35f0: 69 6e 2c 20 6d 61 6b 69 6e 67 20 63 68 61 6e 67  in, making chang
3600: 65 73 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  es to the sqlite
3610: 5f 6d 61 73 74 65 72 20 0a 74 61 62 6c 65 20 6c  _master .table l
3620: 69 6b 65 20 74 68 69 73 20 77 69 6c 6c 20 72 65  ike this will re
3630: 6e 64 65 72 20 74 68 65 20 64 61 74 61 62 61 73  nder the databas
3640: 65 20 63 6f 72 72 75 70 74 20 61 6e 64 20 75 6e  e corrupt and un
3650: 72 65 61 64 61 62 6c 65 20 69 66 20 74 68 65 20  readable if the 
3660: 0a 63 68 61 6e 67 65 20 63 6f 6e 74 61 69 6e 73  .change contains
3670: 20 61 6e 20 65 72 72 6f 72 2e 20 20 43 61 72 65   an error.  Care
3680: 66 75 6c 6c 79 20 74 65 73 74 20 74 68 69 73 20  fully test this 
3690: 65 6e 74 69 72 65 20 70 72 6f 63 65 64 75 72 65  entire procedure
36a0: 0a 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74  .on a separate t
36b0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 72 69  est database pri
36c0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 69 74 20 6f  or to using it o
36d0: 6e 0a 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n.a database con
36e0: 74 61 69 6e 69 6e 67 20 69 6d 70 6f 72 74 61 6e  taining importan
36f0: 74 20 64 61 74 61 20 61 6e 64 2f 6f 72 20 6d 61  t data and/or ma
3700: 6b 65 20 62 61 63 6b 75 70 20 63 6f 70 69 65 73  ke backup copies
3710: 20 6f 66 0a 69 6d 70 6f 72 74 61 6e 74 20 64 61   of.important da
3720: 74 61 62 61 73 65 73 20 70 72 69 6f 72 20 74 6f  tabases prior to
3730: 20 72 75 6e 6e 69 6e 67 20 74 68 69 73 20 70 72   running this pr
3740: 6f 63 65 64 75 72 65 2e 0a 0a 3c 6c 69 3e 3c 70  ocedure...<li><p
3750: 3e 20 49 6e 63 72 65 6d 65 6e 74 20 74 68 65 20  > Increment the 
3760: 73 63 68 65 6d 61 20 76 65 72 73 69 6f 6e 20 6e  schema version n
3770: 75 6d 62 65 72 20 75 73 69 6e 67 0a 5b 50 52 41  umber using.[PRA
3780: 47 4d 41 20 73 63 68 65 6d 61 5f 76 65 72 73 69  GMA schema_versi
3790: 6f 6e 20 7c 20 50 52 41 47 4d 41 20 73 63 68 65  on | PRAGMA sche
37a0: 6d 61 5f 76 65 72 73 69 6f 6e 3d 58 5d 20 77 68  ma_version=X] wh
37b0: 65 72 65 20 58 20 69 73 20 6f 6e 65 0a 6d 6f 72  ere X is one.mor
37c0: 65 20 74 68 61 6e 20 74 68 65 20 6f 6c 64 20 73  e than the old s
37d0: 63 68 65 6d 61 20 76 65 72 73 69 6f 6e 20 6e 75  chema version nu
37e0: 6d 62 65 72 20 66 6f 75 6e 64 20 69 6e 20 73 74  mber found in st
37f0: 65 70 20 32 20 61 62 6f 76 65 2e 0a 0a 3c 6c 69  ep 2 above...<li
3800: 3e 3c 70 3e 20 44 69 73 61 62 6c 65 20 73 63 68  ><p> Disable sch
3810: 65 6d 61 20 65 64 69 74 69 6e 67 20 75 73 69 6e  ema editing usin
3820: 67 20 0a 5b 50 52 41 47 4d 41 20 77 72 69 74 61  g .[PRAGMA writa
3830: 62 6c 65 5f 73 63 68 65 6d 61 20 7c 20 50 52 41  ble_schema | PRA
3840: 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73 63 68  GMA writable_sch
3850: 65 6d 61 3d 4f 46 46 5d 2e 0a 0a 3c 6c 69 3e 3c  ema=OFF]...<li><
3860: 70 3e 20 28 4f 70 74 69 6f 6e 61 6c 29 20 52 75  p> (Optional) Ru
3870: 6e 20 5b 50 52 41 47 4d 41 20 69 6e 74 65 67 72  n [PRAGMA integr
3880: 69 74 79 5f 63 68 65 63 6b 5d 20 74 6f 20 76 65  ity_check] to ve
3890: 72 69 66 79 20 74 68 61 74 20 74 68 65 0a 73 63  rify that the.sc
38a0: 68 65 6d 61 20 63 68 61 6e 67 65 73 20 64 69 64  hema changes did
38b0: 20 6e 6f 74 20 64 61 6d 61 67 65 20 74 68 65 20   not damage the 
38c0: 64 61 74 61 62 61 73 65 2e 0a 0a 3c 6c 69 3e 3c  database...<li><
38d0: 70 3e 20 43 6f 6d 6d 69 74 20 74 68 65 20 74 72  p> Commit the tr
38e0: 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 72 74 65  ansaction starte
38f0: 64 20 6f 6e 20 73 74 65 70 20 31 20 61 62 6f 76  d on step 1 abov
3900: 65 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 49 66 20  e..</ol>..<p>If 
3910: 73 6f 6d 65 20 66 75 74 75 72 65 20 76 65 72 73  some future vers
3920: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 61 64  ion of SQLite ad
3930: 64 73 20 6e 65 77 20 41 4c 54 45 52 20 54 41 42  ds new ALTER TAB
3940: 4c 45 20 63 61 70 61 62 69 6c 69 74 69 65 73 2c  LE capabilities,
3950: 20 0a 74 68 6f 73 65 20 63 61 70 61 62 69 6c 69   .those capabili
3960: 74 69 65 73 20 77 69 6c 6c 20 76 65 72 79 20 6c  ties will very l
3970: 69 6b 65 6c 79 20 75 73 65 20 6f 6e 65 20 6f 66  ikely use one of
3980: 20 74 68 65 20 74 77 6f 20 70 72 6f 63 65 64 75   the two procedu
3990: 72 65 73 0a 6f 75 74 6c 69 6e 65 64 20 61 62 6f  res.outlined abo
39a0: 76 65 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ve...<tcl>hd_fra
39b0: 67 6d 65 6e 74 20 61 6c 74 65 72 74 61 62 6c 65  gment altertable
39c0: 69 73 68 61 72 64 20 7b 77 68 79 20 41 4c 54 45  ishard {why ALTE
39d0: 52 20 54 41 42 4c 45 20 69 73 20 73 6f 20 64 69  R TABLE is so di
39e0: 66 66 69 63 75 6c 74 7d 3c 2f 74 63 6c 3e 0a 3c  fficult}</tcl>.<
39f0: 68 33 3e 57 68 79 20 41 4c 54 45 52 20 54 41 42  h3>Why ALTER TAB
3a00: 4c 45 20 69 73 20 73 75 63 68 20 61 20 70 72 6f  LE is such a pro
3a10: 62 6c 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 3c  blem for SQLite<
3a20: 2f 68 33 3e 0a 0a 3c 70 3e 4d 6f 73 74 20 53 51  /h3>..<p>Most SQ
3a30: 4c 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  L database engin
3a40: 65 73 20 73 74 6f 72 65 20 74 68 65 20 73 63 68  es store the sch
3a50: 65 6d 61 20 61 6c 72 65 61 64 79 20 70 61 72 73  ema already pars
3a60: 65 64 20 69 6e 74 6f 0a 76 61 72 69 6f 75 73 20  ed into.various 
3a70: 73 79 73 74 65 6d 20 74 61 62 6c 65 73 2e 20 20  system tables.  
3a80: 4f 6e 20 74 68 6f 73 65 20 64 61 74 61 62 61 73  On those databas
3a90: 65 20 65 6e 67 69 6e 65 73 2c 20 41 4c 54 45 52  e engines, ALTER
3aa0: 20 54 41 42 4c 45 20 6d 65 72 65 6c 79 20 0a 68   TABLE merely .h
3ab0: 61 73 20 74 6f 20 6d 61 6b 65 20 6d 6f 64 69 66  as to make modif
3ac0: 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
3ad0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 79  corresponding sy
3ae0: 73 74 65 6d 20 74 61 62 6c 65 73 2e 0a 0a 3c 70  stem tables...<p
3af0: 3e 53 51 4c 69 74 65 20 69 73 20 64 69 66 66 65  >SQLite is diffe
3b00: 72 65 6e 74 20 69 6e 20 74 68 61 74 20 69 74 20  rent in that it 
3b10: 73 74 6f 72 65 73 20 74 68 65 20 73 63 68 65 6d  stores the schem
3b20: 61 0a 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  a.in the [sqlite
3b30: 5f 6d 61 73 74 65 72 5d 20 74 61 62 6c 65 20 61  _master] table a
3b40: 73 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  s the original t
3b50: 65 78 74 20 6f 66 20 74 68 65 20 43 52 45 41 54  ext of the CREAT
3b60: 45 0a 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  E.statements tha
3b70: 74 20 64 65 66 69 6e 65 20 74 68 65 20 73 63 68  t define the sch
3b80: 65 6d 61 2e 20 20 48 65 6e 63 65 20 41 4c 54 45  ema.  Hence ALTE
3b90: 52 20 54 41 42 4c 45 20 6e 65 65 64 73 0a 74 6f  R TABLE needs.to
3ba0: 20 72 65 76 69 73 65 20 74 68 65 20 74 65 78 74   revise the text
3bb0: 20 6f 66 20 74 68 65 20 43 52 45 41 54 45 20 73   of the CREATE s
3bc0: 74 61 74 65 6d 65 6e 74 2e 20 20 44 6f 69 6e 67  tatement.  Doing
3bd0: 0a 73 6f 20 63 61 6e 20 62 65 20 74 72 69 63 6b  .so can be trick
3be0: 79 20 66 6f 72 20 63 65 72 74 61 69 6e 20 22 63  y for certain "c
3bf0: 72 65 61 74 69 76 65 22 20 73 63 68 65 6d 61 20  reative" schema 
3c00: 64 65 73 69 67 6e 73 2e 0a 0a 3c 70 3e 54 68 65  designs...<p>The
3c10: 20 53 51 4c 69 74 65 20 61 70 70 72 6f 61 63 68   SQLite approach
3c20: 20 6f 66 20 73 74 6f 72 69 6e 67 20 74 68 65 20   of storing the 
3c30: 73 63 68 65 6d 61 20 61 73 20 74 65 78 74 20 68  schema as text h
3c40: 61 73 20 61 64 76 61 6e 74 61 67 65 73 0a 66 6f  as advantages.fo
3c50: 72 20 61 6e 20 65 6d 62 65 64 64 65 64 20 72 65  r an embedded re
3c60: 6c 61 74 69 6f 6e 61 6c 20 64 61 74 61 62 61 73  lational databas
3c70: 65 2e 20 20 46 6f 72 20 6f 6e 65 2c 20 69 74 20  e.  For one, it 
3c80: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 73  means that the.s
3c90: 63 68 65 6d 61 20 74 61 6b 65 73 20 75 70 20 6c  chema takes up l
3ca0: 65 73 73 20 73 70 61 63 65 20 69 6e 20 74 68 65  ess space in the
3cb0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
3cc0: 20 54 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   This is importa
3cd0: 6e 74 0a 73 69 6e 63 65 20 61 20 63 6f 6d 6d 6f  nt.since a commo
3ce0: 6e 20 53 51 4c 69 74 65 20 75 73 61 67 65 20 70  n SQLite usage p
3cf0: 61 74 74 65 72 6e 20 69 73 20 74 6f 20 68 61 76  attern is to hav
3d00: 65 20 6d 61 6e 79 20 73 6d 61 6c 6c 2c 0a 73 65  e many small,.se
3d10: 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 20  parate database 
3d20: 66 69 6c 65 73 20 69 6e 73 74 65 61 64 20 6f 66  files instead of
3d30: 20 70 75 74 74 69 6e 67 20 65 76 65 72 79 74 68   putting everyth
3d40: 69 6e 67 20 69 6e 20 6f 6e 65 0a 62 69 67 20 67  ing in one.big g
3d50: 6c 6f 62 61 6c 20 64 61 74 61 62 61 73 65 20 66  lobal database f
3d60: 69 6c 65 2c 20 77 68 69 63 68 20 69 73 20 74 68  ile, which is th
3d70: 65 20 75 73 75 61 6c 20 61 70 70 72 6f 61 63 68  e usual approach
3d80: 20 66 6f 72 20 63 6c 69 65 6e 74 2f 73 65 72 76   for client/serv
3d90: 65 72 0a 64 61 74 61 62 61 73 65 20 65 6e 67 69  er.database engi
3da0: 6e 65 73 2e 0a 53 69 6e 63 65 20 74 68 65 20 73  nes..Since the s
3db0: 63 68 65 6d 61 20 69 73 20 64 75 70 6c 69 63 61  chema is duplica
3dc0: 74 65 64 20 69 6e 20 65 61 63 68 20 73 65 70 61  ted in each sepa
3dd0: 72 61 74 65 20 64 61 74 61 62 61 73 65 20 66 69  rate database fi
3de0: 6c 65 2c 20 69 74 20 69 73 0a 69 6d 70 6f 72 74  le, it is.import
3df0: 61 6e 74 20 74 6f 20 6b 65 65 70 20 74 68 65 20  ant to keep the 
3e00: 73 63 68 65 6d 61 20 72 65 70 72 65 73 65 6e 74  schema represent
3e10: 61 74 69 6f 6e 20 63 6f 6d 70 61 63 74 2e 0a 0a  ation compact...
3e20: 3c 70 3e 53 74 6f 72 69 6e 67 20 74 68 65 20 73  <p>Storing the s
3e30: 63 68 65 6d 61 20 61 73 20 74 65 78 74 20 72 61  chema as text ra
3e40: 74 68 65 72 20 74 68 61 6e 20 61 73 20 70 61 72  ther than as par
3e50: 73 65 64 20 74 61 62 6c 65 73 20 61 6c 73 6f 0a  sed tables also.
3e60: 67 69 76 65 20 66 6c 65 78 69 62 69 6c 69 74 79  give flexibility
3e70: 20 74 6f 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   to the implemen
3e80: 74 61 74 69 6f 6e 2e 20 20 53 69 6e 63 65 20 74  tation.  Since t
3e90: 68 65 20 69 6e 74 65 72 6e 61 6c 20 70 61 72 73  he internal pars
3ea0: 65 0a 6f 66 20 74 68 65 20 73 63 68 65 6d 61 20  e.of the schema 
3eb0: 69 73 20 72 65 67 65 6e 65 72 61 74 65 64 20 65  is regenerated e
3ec0: 61 63 68 20 74 69 6d 65 20 74 68 65 20 64 61 74  ach time the dat
3ed0: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 2c  abase is opened,
3ee0: 20 74 68 65 0a 69 6e 74 65 72 6e 61 6c 20 72 65   the.internal re
3ef0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
3f00: 74 68 65 20 73 63 68 65 6d 61 20 63 61 6e 20 63  the schema can c
3f10: 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 72  hange from one r
3f20: 65 6c 65 61 73 65 0a 74 6f 20 74 68 65 20 6e 65  elease.to the ne
3f30: 78 74 2e 20 20 54 68 69 73 20 69 73 20 69 6d 70  xt.  This is imp
3f40: 6f 72 74 61 6e 74 2c 20 61 73 20 73 6f 6d 65 74  ortant, as somet
3f50: 69 6d 65 73 20 6e 65 77 20 66 65 61 74 75 72 65  imes new feature
3f60: 73 20 72 65 71 75 69 72 65 0a 65 6e 68 61 6e 63  s require.enhanc
3f70: 65 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 69 6e  ements to the in
3f80: 74 65 72 6e 61 6c 20 73 63 68 65 6d 61 20 72 65  ternal schema re
3f90: 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20 20 43  presentation.  C
3fa0: 68 61 6e 67 69 6e 67 20 74 68 65 0a 69 6e 74 65  hanging the.inte
3fb0: 72 6e 61 6c 20 73 63 68 65 6d 61 20 72 65 70 72  rnal schema repr
3fc0: 65 73 65 6e 74 61 74 69 6f 6e 20 77 6f 75 6c 64  esentation would
3fd0: 20 62 65 20 6d 75 63 68 20 6d 6f 72 65 20 64 69   be much more di
3fe0: 66 66 69 63 75 6c 74 20 69 66 20 74 68 65 0a 73  fficult if the.s
3ff0: 63 68 65 6d 61 20 72 65 70 72 65 73 65 6e 74 61  chema representa
4000: 74 69 6f 6e 20 77 61 73 20 65 78 70 6f 73 65 64  tion was exposed
4010: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4020: 20 66 69 6c 65 2e 20 20 53 6f 2c 20 69 6e 20 6f   file.  So, in o
4030: 74 68 65 72 0a 77 6f 72 64 73 2c 20 73 74 6f 72  ther.words, stor
4040: 69 6e 67 20 74 68 65 20 73 63 68 65 6d 61 20 61  ing the schema a
4050: 73 20 74 65 78 74 20 68 65 6c 70 73 20 6d 61 69  s text helps mai
4060: 6e 74 61 69 6e 20 62 61 63 6b 77 61 72 64 73 20  ntain backwards 
4070: 0a 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20  .compatibility, 
4080: 61 6e 64 20 68 65 6c 70 73 20 65 6e 73 75 72 65  and helps ensure
4090: 20 74 68 61 74 20 6f 6c 64 65 72 20 64 61 74 61   that older data
40a0: 62 61 73 65 20 66 69 6c 65 73 20 63 61 6e 20 62  base files can b
40b0: 65 0a 72 65 61 64 20 61 6e 64 20 77 72 69 74 74  e.read and writt
40c0: 65 6e 20 62 79 20 6e 65 77 65 72 20 76 65 72 73  en by newer vers
40d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
40e0: 0a 3c 70 3e 53 74 6f 72 69 6e 67 20 74 68 65 20  .<p>Storing the 
40f0: 73 63 68 65 6d 61 20 61 20 74 65 78 74 20 61 6c  schema a text al
4100: 73 6f 20 6d 61 6b 65 73 20 74 68 65 20 0a 5b 53  so makes the .[S
4110: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
4120: 69 6c 65 20 66 6f 72 6d 61 74 5d 20 65 61 73 69  ile format] easi
4130: 65 72 20 74 6f 20 64 65 66 69 6e 65 2c 20 64 6f  er to define, do
4140: 63 75 6d 65 6e 74 2c 20 61 6e 64 20 0a 75 6e 64  cument, and .und
4150: 65 72 73 74 61 6e 64 2e 20 54 68 69 73 20 68 65  erstand. This he
4160: 6c 70 73 20 6d 61 6b 65 20 53 51 4c 69 74 65 20  lps make SQLite 
4170: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 61  database files a
4180: 0a 5b 72 65 63 6f 6d 6d 65 6e 64 65 64 20 73 74  .[recommended st
4190: 6f 72 61 67 65 20 66 6f 72 6d 61 74 5d 20 66 6f  orage format] fo
41a0: 72 20 6c 6f 6e 67 2d 74 65 72 6d 20 61 72 63 68  r long-term arch
41b0: 69 76 69 6e 67 20 6f 66 20 64 61 74 61 2e 0a 0a  iving of data...
41c0: 3c 70 3e 54 68 65 20 64 6f 77 6e 73 69 64 65 20  <p>The downside 
41d0: 6f 66 20 73 74 6f 72 69 6e 67 20 73 63 68 65 6d  of storing schem
41e0: 61 20 61 20 74 65 78 74 20 69 73 20 74 68 61 74  a a text is that
41f0: 20 69 74 20 63 61 6e 20 6d 61 6b 65 0a 74 68 65   it can make.the
4200: 20 73 63 68 65 6d 61 20 74 72 69 63 6b 79 20 74   schema tricky t
4210: 6f 20 6d 6f 64 69 66 79 2e 20 20 41 6e 64 20 66  o modify.  And f
4220: 6f 72 20 74 68 61 74 20 72 65 61 73 6f 6e 2c 20  or that reason, 
4230: 74 68 65 20 41 4c 54 45 52 20 54 41 42 4c 45 0a  the ALTER TABLE.
4240: 73 75 70 70 6f 72 74 20 69 6e 20 53 51 4c 69 74  support in SQLit
4250: 65 20 68 61 73 20 74 72 61 64 69 74 69 6f 6e 61  e has traditiona
4260: 6c 6c 79 20 6c 61 67 67 65 64 20 62 65 68 69 6e  lly lagged behin
4270: 64 20 6f 74 68 65 72 20 53 51 4c 0a 64 61 74 61  d other SQL.data
4280: 62 61 73 65 20 65 6e 67 69 6e 65 73 20 74 68 61  base engines tha
4290: 74 20 73 74 6f 72 65 20 74 68 65 69 72 20 73 63  t store their sc
42a0: 68 65 6d 61 73 20 61 73 20 70 61 72 73 65 64 20  hemas as parsed 
42b0: 73 79 73 74 65 6d 20 74 61 62 6c 65 73 0a 74 68  system tables.th
42c0: 61 74 20 61 72 65 20 65 61 73 69 65 72 20 74 6f  at are easier to
42d0: 20 6d 6f 64 69 66 79 2e 0a 0a 0a 0a 3c 74 63 6c   modify.....<tcl
42e0: 3e 0a 23 20 20 4f 6e 65 20 6f 66 20 74 68 65 20  >.#  One of the 
42f0: 72 65 61 73 6f 6e 73 20 74 68 61 74 0a 23 20 53  reasons that.# S
4300: 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63  QLite does not c
4310: 75 72 72 65 6e 74 6c 79 20 73 75 70 70 6f 72 74  urrently support
4320: 20 6d 6f 72 65 20 41 4c 54 45 52 20 54 41 42 4c   more ALTER TABL
4330: 45 20 63 61 70 61 62 69 6c 69 74 69 65 73 20 69  E capabilities i
4340: 73 20 74 68 61 74 0a 23 20 74 68 65 20 70 72 6f  s that.# the pro
4350: 63 65 64 75 72 65 20 73 68 6f 77 6e 20 61 62 6f  cedure shown abo
4360: 76 65 20 69 73 20 64 69 66 66 69 63 75 6c 74 20  ve is difficult 
4370: 74 6f 20 61 75 74 6f 6d 61 74 65 20 66 6f 72 20  to automate for 
4380: 61 6e 20 61 72 62 69 74 72 61 72 79 20 73 63 68  an arbitrary sch
4390: 65 6d 61 2e 0a 23 20 50 61 72 74 69 63 75 6c 61  ema..# Particula
43a0: 72 6c 79 20 74 72 6f 75 62 6c 65 73 6f 6d 65 20  rly troublesome 
43b0: 61 72 65 61 73 20 61 72 65 20 69 64 65 6e 74 69  areas are identi
43c0: 66 79 69 6e 67 20 61 6c 6c 20 76 69 65 77 73 20  fying all views 
43d0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
43e0: 23 20 74 61 62 6c 65 20 58 20 69 6e 20 73 74 65  # table X in ste
43f0: 70 20 31 20 61 6e 64 20 63 72 65 61 74 69 6e 67  p 1 and creating
4400: 20 6e 65 77 20 76 69 65 77 73 20 61 6e 64 20 74   new views and t
4410: 72 69 67 67 65 72 73 20 74 68 61 74 20 61 72 65  riggers that are
4420: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 23 20 77 69   compatible.# wi
4430: 74 68 20 74 68 65 20 61 6c 74 65 72 65 64 20 73  th the altered s
4440: 63 68 65 6d 61 20 66 6f 72 20 74 61 62 6c 65 20  chema for table 
4450: 58 20 69 6e 20 73 74 65 70 20 36 2e 20 20 49 74  X in step 6.  It
4460: 20 69 73 20 61 20 74 72 69 63 6b 79 20 62 75 74   is a tricky but
4470: 20 73 6f 6c 76 61 62 6c 65 0a 23 20 70 72 6f 62   solvable.# prob
4480: 6c 65 6d 20 74 6f 20 63 72 65 61 74 65 20 63 6f  lem to create co
4490: 64 65 20 74 68 61 74 20 77 69 6c 6c 20 70 65 72  de that will per
44a0: 66 6f 72 6d 20 74 68 65 20 73 74 65 70 73 20 61  form the steps a
44b0: 62 6f 76 65 20 0a 23 20 66 6f 72 20 22 72 65 61  bove .# for "rea
44c0: 73 6f 6e 61 62 6c 65 22 20 73 63 68 65 6d 61 73  sonable" schemas
44d0: 20 63 6f 6d 6d 6f 6e 6c 79 20 66 6f 75 6e 64 20   commonly found 
44e0: 69 6e 20 70 72 61 63 74 69 63 65 2e 20 20 0a 23  in practice.  .#
44f0: 20 42 75 74 20 74 68 65 72 65 20 65 78 69 73 74   But there exist
4500: 20 6d 61 6c 65 76 6f 6c 65 6e 74 20 73 63 68 65   malevolent sche
4510: 6d 61 73 20 66 6f 72 20 77 68 69 63 68 0a 23 20  mas for which.# 
4520: 74 68 65 73 65 20 73 74 65 70 73 20 61 72 65 20  these steps are 
4530: 6d 61 64 64 65 6e 69 6e 67 6c 79 20 64 69 66 66  maddeningly diff
4540: 69 63 75 6c 74 20 74 6f 20 64 6f 20 63 6f 72 72  icult to do corr
4550: 65 63 74 6c 79 2e 20 20 52 61 74 68 65 72 20 74  ectly.  Rather t
4560: 68 61 6e 20 63 72 65 61 74 65 0a 23 20 41 4c 54  han create.# ALT
4570: 45 52 20 54 41 42 4c 45 20 66 65 61 74 75 72 65  ER TABLE feature
4580: 73 20 74 68 61 74 20 77 6f 72 6b 20 63 6f 72 72  s that work corr
4590: 65 63 74 6c 79 20 39 39 2e 39 25 20 6f 66 20 74  ectly 99.9% of t
45a0: 68 65 20 74 69 6d 65 20 62 75 74 20 70 6f 73 73  he time but poss
45b0: 69 62 6c 79 0a 23 20 63 6f 72 72 75 70 74 20 74  ibly.# corrupt t
45c0: 68 65 20 73 63 68 65 6d 61 20 6f 6e 20 74 68 65  he schema on the
45d0: 20 6f 74 68 65 72 20 30 2e 31 25 2c 20 74 68 65   other 0.1%, the
45e0: 20 53 51 4c 69 74 65 20 64 65 76 65 6c 6f 70 65   SQLite develope
45f0: 72 73 20 68 61 76 65 20 64 65 63 69 64 65 64 0a  rs have decided.
4600: 23 20 74 6f 20 70 75 73 68 20 74 68 65 20 70 72  # to push the pr
4610: 6f 62 6c 65 6d 20 69 6e 74 6f 20 74 68 65 20 61  oblem into the a
4620: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 6d 61 69  pplication domai
4630: 6e 2c 20 77 68 65 72 65 20 69 74 20 69 73 20 6d  n, where it is m
4640: 75 63 68 20 65 61 73 69 65 72 0a 23 20 74 6f 20  uch easier.# to 
4650: 73 6f 6c 76 65 2e 0a 3c 2f 74 63 6c 3e 0a 0a 0a  solve..</tcl>...
4660: 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
4670: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4680: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
4690: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
46a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
46b0: 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 41 4e  ####.Section {AN
46c0: 41 4c 59 5a 45 7d 20 61 6e 61 6c 79 7a 65 20 41  ALYZE} analyze A
46d0: 4e 41 4c 59 5a 45 0a 0a 52 65 63 75 72 73 69 76  NALYZE..Recursiv
46e0: 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 61  eBubbleDiagram a
46f0: 6e 61 6c 79 7a 65 2d 73 74 6d 74 0a 3c 2f 74 63  nalyze-stmt.</tc
4700: 6c 3e 0a 0a 3c 70 3e 20 5e 54 68 65 20 41 4e 41  l>..<p> ^The ANA
4710: 4c 59 5a 45 20 63 6f 6d 6d 61 6e 64 20 67 61 74  LYZE command gat
4720: 68 65 72 73 20 73 74 61 74 69 73 74 69 63 73 20  hers statistics 
4730: 61 62 6f 75 74 20 74 61 62 6c 65 73 20 61 6e 64  about tables and
4740: 0a 69 6e 64 69 63 65 73 20 61 6e 64 20 73 74 6f  .indices and sto
4750: 72 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 65  res the collecte
4760: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 69 6e  d information.in
4770: 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61 62 6c 65   [internal table
4780: 73 5d 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  s] of the databa
4790: 73 65 20 77 68 65 72 65 20 74 68 65 20 71 75 65  se where the que
47a0: 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 63 61 6e  ry optimizer can
47b0: 0a 61 63 63 65 73 73 20 74 68 65 20 69 6e 66 6f  .access the info
47c0: 72 6d 61 74 69 6f 6e 20 61 6e 64 20 75 73 65 20  rmation and use 
47d0: 69 74 20 74 6f 20 68 65 6c 70 20 6d 61 6b 65 20  it to help make 
47e0: 62 65 74 74 65 72 20 71 75 65 72 79 20 70 6c 61  better query pla
47f0: 6e 6e 69 6e 67 20 63 68 6f 69 63 65 73 2e 0a 5e  nning choices..^
4800: 49 66 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  If no arguments 
4810: 61 72 65 20 67 69 76 65 6e 2c 20 61 6c 6c 20 61  are given, all a
4820: 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
4830: 73 20 61 72 65 0a 61 6e 61 6c 79 7a 65 64 2e 20  s are.analyzed. 
4840: 20 5e 49 66 20 61 20 73 63 68 65 6d 61 20 6e 61   ^If a schema na
4850: 6d 65 20 69 73 20 67 69 76 65 6e 20 61 73 20 74  me is given as t
4860: 68 65 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 65  he argument, the
4870: 6e 20 61 6c 6c 20 74 61 62 6c 65 73 0a 61 6e 64  n all tables.and
4880: 20 69 6e 64 69 63 65 73 20 69 6e 20 74 68 61 74   indices in that
4890: 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20 61 72   one database ar
48a0: 65 20 61 6e 61 6c 79 7a 65 64 2e 20 20 0a 5e 49  e analyzed.  .^I
48b0: 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
48c0: 73 20 61 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  s a table name, 
48d0: 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74 20 74  then only that t
48e0: 61 62 6c 65 20 61 6e 64 20 74 68 65 0a 69 6e 64  able and the.ind
48f0: 69 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20  ices associated 
4900: 77 69 74 68 20 74 68 61 74 20 74 61 62 6c 65 20  with that table 
4910: 61 72 65 20 61 6e 61 6c 79 7a 65 64 2e 20 20 5e  are analyzed.  ^
4920: 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  If the argument.
4930: 69 73 20 61 6e 20 69 6e 64 65 78 20 6e 61 6d 65  is an index name
4940: 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 61 74  , then only that
4950: 20 6f 6e 65 20 69 6e 64 65 78 20 69 73 20 61 6e   one index is an
4960: 61 6c 79 7a 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e  alyzed.</p>..<p>
4970: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d   ^The default im
4980: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 74 6f  plementation sto
4990: 72 65 73 20 61 6c 6c 20 73 74 61 74 69 73 74 69  res all statisti
49a0: 63 73 20 69 6e 20 61 20 73 69 6e 67 6c 65 0a 74  cs in a single.t
49b0: 61 62 6c 65 20 6e 61 6d 65 64 20 22 5b 73 71 6c  able named "[sql
49c0: 69 74 65 5f 73 74 61 74 31 5d 22 2e 20 20 5e 49  ite_stat1]".  ^I
49d0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
49e0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 5b 53  iled with the.[S
49f0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
4a00: 54 33 5d 20 6f 70 74 69 6f 6e 20 61 6e 64 20 77  T3] option and w
4a10: 69 74 68 6f 75 74 20 74 68 65 20 5b 53 51 4c 49  ithout the [SQLI
4a20: 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 34 5d  TE_ENABLE_STAT4]
4a30: 0a 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 61 64  .option, then ad
4a40: 64 69 74 69 6f 6e 61 6c 20 68 69 73 74 6f 67 72  ditional histogr
4a50: 61 6d 20 64 61 74 61 20 69 73 0a 63 6f 6c 6c 65  am data is.colle
4a60: 63 74 65 64 20 61 6e 64 20 73 74 6f 72 65 64 20  cted and stored 
4a70: 69 6e 20 5b 73 71 6c 69 74 65 5f 73 74 61 74 33  in [sqlite_stat3
4a80: 5d 2e 0a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ].. ^If SQLite i
4a90: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
4aa0: 74 68 65 0a 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the.[SQLITE_ENAB
4ab0: 4c 45 5f 53 54 41 54 34 5d 20 6f 70 74 69 6f 6e  LE_STAT4] option
4ac0: 2c 20 74 68 65 6e 20 61 64 64 69 74 69 6f 6e 61  , then additiona
4ad0: 6c 20 68 69 73 74 6f 67 72 61 6d 20 64 61 74 61  l histogram data
4ae0: 20 69 73 0a 63 6f 6c 6c 65 63 74 65 64 20 61 6e   is.collected an
4af0: 64 20 73 74 6f 72 65 64 20 69 6e 20 5b 73 71 6c  d stored in [sql
4b00: 69 74 65 5f 73 74 61 74 34 5d 2e 0a 4f 6c 64 65  ite_stat4]..Olde
4b10: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4b20: 4c 69 74 65 20 77 6f 75 6c 64 20 6d 61 6b 65 20  Lite would make 
4b30: 75 73 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  use of the [sqli
4b40: 74 65 5f 73 74 61 74 32 5d 20 74 61 62 6c 65 0a  te_stat2] table.
4b50: 77 68 65 6e 20 63 6f 6d 70 69 6c 65 64 20 77 69  when compiled wi
4b60: 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
4b70: 45 5f 53 54 41 54 32 5d 20 62 75 74 20 61 6c 6c  E_STAT2] but all
4b80: 20 72 65 63 65 6e 74 20 76 65 72 73 69 6f 6e 73   recent versions
4b90: 20 6f 66 0a 53 51 4c 69 74 65 20 69 67 6e 6f 72   of.SQLite ignor
4ba0: 65 20 74 68 65 20 73 71 6c 69 74 65 5f 73 74 61  e the sqlite_sta
4bb0: 74 32 20 74 61 62 6c 65 2e 0a 46 75 74 75 72 65  t2 table..Future
4bc0: 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 6d 61   enhancements ma
4bd0: 79 20 63 72 65 61 74 65 0a 61 64 64 69 74 69 6f  y create.additio
4be0: 6e 61 6c 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61  nal [internal ta
4bf0: 62 6c 65 73 5d 20 77 69 74 68 20 74 68 65 20 73  bles] with the s
4c00: 61 6d 65 20 6e 61 6d 65 20 70 61 74 74 65 72 6e  ame name pattern
4c10: 20 65 78 63 65 70 74 20 77 69 74 68 0a 66 69 6e   except with.fin
4c20: 61 6c 20 64 69 67 69 74 20 6c 61 72 67 65 72 20  al digit larger 
4c30: 74 68 61 6e 20 22 34 22 2e 0a 41 6c 6c 20 6f 66  than "4"..All of
4c40: 20 74 68 65 73 65 20 74 61 62 6c 65 73 20 61 72   these tables ar
4c50: 65 20 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 72  e collectively r
4c60: 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 73  eferred to as "s
4c70: 74 61 74 69 73 74 69 63 73 20 74 61 62 6c 65 73  tatistics tables
4c80: 22 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 54 68  "..</p>..<p> ^Th
4c90: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
4ca0: 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62 6c   statistics tabl
4cb0: 65 73 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  es can be querie
4cc0: 64 20 75 73 69 6e 67 20 5b 53 45 4c 45 43 54 5d  d using [SELECT]
4cd0: 0a 61 6e 64 20 63 61 6e 20 62 65 20 63 68 61 6e  .and can be chan
4ce0: 67 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 44  ged using the [D
4cf0: 45 4c 45 54 45 5d 2c 20 5b 49 4e 53 45 52 54 5d  ELETE], [INSERT]
4d00: 2c 20 61 6e 64 20 5b 55 50 44 41 54 45 5d 20 63  , and [UPDATE] c
4d10: 6f 6d 6d 61 6e 64 73 2e 0a 5e 28 54 68 65 20 5b  ommands..^(The [
4d20: 44 52 4f 50 20 54 41 42 4c 45 5d 20 63 6f 6d 6d  DROP TABLE] comm
4d30: 61 6e 64 20 77 6f 72 6b 73 20 6f 6e 20 73 74 61  and works on sta
4d40: 74 69 73 74 69 63 73 20 74 61 62 6c 65 73 0a 61  tistics tables.a
4d50: 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
4d60: 69 6f 6e 20 33 2e 37 2e 39 2e 29 5e 20 28 5b 64  ion 3.7.9.)^ ([d
4d70: 61 74 65 6f 66 3a 33 2e 37 2e 39 5d 29 0a 5e 54  ateof:3.7.9]).^T
4d80: 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45 5d  he [ALTER TABLE]
4d90: 20 63 6f 6d 6d 61 6e 64 20 64 6f 65 73 20 6e 6f   command does no
4da0: 74 20 77 6f 72 6b 20 6f 6e 20 73 74 61 74 69 73  t work on statis
4db0: 74 69 63 73 20 74 61 62 6c 65 73 2e 0a 41 70 70  tics tables..App
4dc0: 72 6f 70 72 69 61 74 65 20 63 61 72 65 20 73 68  ropriate care sh
4dd0: 6f 75 6c 64 20 62 65 20 75 73 65 64 20 77 68 65  ould be used whe
4de0: 6e 20 63 68 61 6e 67 69 6e 67 20 74 68 65 20 63  n changing the c
4df0: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 73 74  ontent of the st
4e00: 61 74 69 73 74 69 63 73 0a 74 61 62 6c 65 73 20  atistics.tables 
4e10: 61 73 20 69 6e 76 61 6c 69 64 20 63 6f 6e 74 65  as invalid conte
4e20: 6e 74 20 63 61 6e 20 63 61 75 73 65 20 53 51 4c  nt can cause SQL
4e30: 69 74 65 20 74 6f 20 73 65 6c 65 63 74 20 69 6e  ite to select in
4e40: 65 66 66 69 63 69 65 6e 74 0a 71 75 65 72 79 20  efficient.query 
4e50: 70 6c 61 6e 73 2e 20 20 47 65 6e 65 72 61 6c 6c  plans.  Generall
4e60: 79 20 73 70 65 61 6b 69 6e 67 2c 20 6f 6e 65 20  y speaking, one 
4e70: 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 6f 64 69 66  should not modif
4e80: 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
4e90: 0a 74 68 65 20 73 74 61 74 69 73 74 69 63 73 20  .the statistics 
4ea0: 74 61 62 6c 65 73 20 62 79 20 61 6e 79 20 6d 65  tables by any me
4eb0: 63 68 61 6e 69 73 6d 20 6f 74 68 65 72 20 74 68  chanism other th
4ec0: 61 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a  an invoking the.
4ed0: 41 4e 41 4c 59 5a 45 20 63 6f 6d 6d 61 6e 64 2e  ANALYZE command.
4ee0: 20 20 0a 53 65 65 20 22 5b 4d 61 6e 75 61 6c 20    .See "[Manual 
4ef0: 43 6f 6e 74 72 6f 6c 20 4f 66 20 51 75 65 72 79  Control Of Query
4f00: 20 50 6c 61 6e 73 20 55 73 69 6e 67 20 53 51 4c   Plans Using SQL
4f10: 49 54 45 5f 53 54 41 54 20 54 61 62 6c 65 73 5d  ITE_STAT Tables]
4f20: 22 20 66 6f 72 0a 66 75 72 74 68 65 72 20 69 6e  " for.further in
4f30: 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a  formation.</p>..
4f40: 3c 70 3e 20 5e 53 74 61 74 69 73 74 69 63 73 20  <p> ^Statistics 
4f50: 67 61 74 68 65 72 65 64 20 62 79 20 41 4e 41 4c  gathered by ANAL
4f60: 59 5a 45 20 61 72 65 20 6e 6f 74 20 61 75 74 6f  YZE are not auto
4f70: 6d 61 74 69 63 61 6c 6c 79 20 75 70 64 61 74 65  matically update
4f80: 64 20 61 73 0a 74 68 65 20 63 6f 6e 74 65 6e 74  d as.the content
4f90: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
4fa0: 20 63 68 61 6e 67 65 73 2e 20 20 49 66 20 74 68   changes.  If th
4fb0: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
4fc0: 20 64 61 74 61 62 61 73 65 0a 63 68 61 6e 67 65   database.change
4fd0: 73 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79 2c  s significantly,
4fe0: 20 6f 72 20 69 66 20 74 68 65 20 64 61 74 61 62   or if the datab
4ff0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
5000: 65 73 2c 20 74 68 65 6e 20 6f 6e 65 20 73 68 6f  es, then one sho
5010: 75 6c 64 0a 63 6f 6e 73 69 64 65 72 20 72 65 72  uld.consider rer
5020: 75 6e 6e 69 6e 67 20 74 68 65 20 41 4e 41 4c 59  unning the ANALY
5030: 5a 45 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 6f 72  ZE command in or
5040: 64 65 72 20 74 6f 20 75 70 64 61 74 65 20 74 68  der to update th
5050: 65 20 73 74 61 74 69 73 74 69 63 73 2e 3c 2f 70  e statistics.</p
5060: 3e 0a 0a 3c 70 3e 20 54 68 65 20 71 75 65 72 79  >..<p> The query
5070: 20 70 6c 61 6e 6e 65 72 20 6c 6f 61 64 73 20 74   planner loads t
5080: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
5090: 65 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62  e statistics tab
50a0: 6c 65 73 0a 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  les.into memory 
50b0: 77 68 65 6e 20 74 68 65 20 73 63 68 65 6d 61 20  when the schema 
50c0: 69 73 20 72 65 61 64 2e 20 20 5e 48 65 6e 63 65  is read.  ^Hence
50d0: 2c 20 77 68 65 6e 20 61 6e 20 61 70 70 6c 69 63  , when an applic
50e0: 61 74 69 6f 6e 0a 63 68 61 6e 67 65 73 20 74 68  ation.changes th
50f0: 65 20 73 74 61 74 69 73 74 69 63 73 20 74 61 62  e statistics tab
5100: 6c 65 73 20 64 69 72 65 63 74 6c 79 2c 20 53 51  les directly, SQ
5110: 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6d  Lite will not im
5120: 6d 65 64 69 61 74 65 6c 79 0a 6e 6f 74 69 63 65  mediately.notice
5130: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 5e 41   the changes. ^A
5140: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 63 61  n application.ca
5150: 6e 20 66 6f 72 63 65 20 74 68 65 20 71 75 65 72  n force the quer
5160: 79 20 70 6c 61 6e 6e 65 72 20 74 6f 20 72 65 72  y planner to rer
5170: 65 61 64 20 74 68 65 20 73 74 61 74 69 73 74 69  ead the statisti
5180: 63 73 20 74 61 62 6c 65 73 20 62 79 20 72 75 6e  cs tables by run
5190: 6e 69 6e 67 0a 3c 62 3e 41 4e 41 4c 59 5a 45 20  ning.<b>ANALYZE 
51a0: 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 3c 2f 62  sqlite_master</b
51b0: 3e 2e 20 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  >. </p>..<tcl>hd
51c0: 5f 66 72 61 67 6d 65 6e 74 20 61 75 74 6f 61 6e  _fragment autoan
51d0: 61 6c 79 7a 65 20 7b 61 75 74 6f 6d 61 74 69 63  alyze {automatic
51e0: 61 6c 6c 79 20 72 75 6e 6e 69 6e 67 20 41 4e 41  ally running ANA
51f0: 4c 59 5a 45 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  LYZE}</tcl>.<h2>
5200: 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 52 75  Automatically Ru
5210: 6e 6e 69 6e 67 20 41 4e 41 4c 59 5a 45 3c 2f 68  nning ANALYZE</h
5220: 32 3e 0a 0a 3c 70 3e 54 68 65 20 5b 50 52 41 47  2>..<p>The [PRAG
5230: 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 63 6f 6d  MA optimize] com
5240: 6d 61 6e 64 20 77 69 6c 6c 20 61 75 74 6f 6d 61  mand will automa
5250: 74 69 63 61 6c 6c 79 20 72 75 6e 20 41 4e 41 4c  tically run ANAL
5260: 59 5a 45 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  YZE on individua
5270: 6c 0a 74 61 62 6c 65 73 20 6f 6e 20 61 6e 20 61  l.tables on an a
5280: 73 2d 6e 65 65 64 65 64 20 62 61 73 69 73 2e 20  s-needed basis. 
5290: 20 54 68 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64   The recommended
52a0: 20 70 72 61 63 74 69 63 65 20 69 73 20 66 6f 72   practice is for
52b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 74 6f   applications.to
52c0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 50 52 41   invoke the [PRA
52d0: 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20 73 74  GMA optimize] st
52e0: 61 74 65 6d 65 6e 74 20 6a 75 73 74 20 62 65 66  atement just bef
52f0: 6f 72 65 20 63 6c 6f 73 69 6e 67 20 65 61 63 68  ore closing each
5300: 20 64 61 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63   database.connec
5310: 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 45 61  tion.</p>..<p>Ea
5320: 63 68 20 53 51 4c 69 74 65 20 5b 64 61 74 61 62  ch SQLite [datab
5330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
5340: 72 65 63 6f 72 64 73 20 63 61 73 65 73 20 77 68  records cases wh
5350: 65 6e 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  en the query pla
5360: 6e 6e 65 72 20 77 6f 75 6c 64 0a 62 65 6e 65 66  nner would.benef
5370: 69 74 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 61  it from having a
5380: 63 63 75 72 61 74 65 20 72 65 73 75 6c 74 73 20  ccurate results 
5390: 6f 66 20 41 4e 41 4c 59 5a 45 20 61 74 20 68 61  of ANALYZE at ha
53a0: 6e 64 2e 20 20 54 68 65 73 65 20 72 65 63 6f 72  nd.  These recor
53b0: 64 73 0a 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  ds.are held in m
53c0: 65 6d 6f 72 79 20 61 6e 64 20 61 63 63 75 6d 75  emory and accumu
53d0: 6c 61 74 65 20 6f 76 65 72 20 74 68 65 20 6c 69  late over the li
53e0: 66 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  fe of a database
53f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 54 68 65   connection..The
5400: 20 5b 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a   [PRAGMA optimiz
5410: 65 5d 20 63 6f 6d 6d 61 6e 64 20 6c 6f 6f 6b 73  e] command looks
5420: 20 61 74 20 74 68 6f 73 65 20 72 65 63 6f 72 64   at those record
5430: 73 20 61 6e 64 20 72 75 6e 73 20 41 4e 41 4c 59  s and runs ANALY
5440: 5a 45 20 6f 6e 20 6f 6e 6c 79 0a 74 68 6f 73 65  ZE on only.those
5450: 20 74 61 62 6c 65 73 20 66 6f 72 20 77 68 69 63   tables for whic
5460: 68 20 6e 65 77 20 6f 72 20 75 70 64 61 74 65 64  h new or updated
5470: 20 41 4e 41 4c 59 5a 45 20 64 61 74 61 20 73 65   ANALYZE data se
5480: 65 6d 73 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  ems likely to be
5490: 20 75 73 65 66 75 6c 2e 0a 49 6e 20 6d 6f 73 74   useful..In most
54a0: 20 63 61 73 65 73 20 5b 50 52 41 47 4d 41 20 6f   cases [PRAGMA o
54b0: 70 74 69 6d 69 7a 65 5d 20 77 69 6c 6c 20 6e 6f  ptimize] will no
54c0: 74 20 72 75 6e 20 41 4e 41 4c 59 5a 45 2c 20 62  t run ANALYZE, b
54d0: 75 74 20 69 74 20 77 69 6c 6c 20 6f 63 63 61 73  ut it will occas
54e0: 69 6f 6e 61 6c 6c 79 0a 64 6f 20 73 6f 20 65 69  ionally.do so ei
54f0: 74 68 65 72 20 66 6f 72 20 74 61 62 6c 65 73 20  ther for tables 
5500: 74 68 61 74 20 68 61 76 65 20 6e 65 76 65 72 20  that have never 
5510: 62 65 66 6f 72 65 20 62 65 65 6e 20 61 6e 61 6c  before been anal
5520: 79 7a 65 64 2c 20 6f 72 20 66 6f 72 20 74 61 62  yzed, or for tab
5530: 6c 65 73 0a 74 68 61 74 20 68 61 76 65 20 67 72  les.that have gr
5540: 6f 77 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 6c  own significantl
5550: 79 20 73 69 6e 63 65 20 74 68 65 79 20 77 65 72  y since they wer
5560: 65 20 6c 61 73 74 20 61 6e 61 6c 79 7a 65 64 2e  e last analyzed.
5570: 3c 2f 70 3e 0a 0a 3c 70 3e 53 69 6e 63 65 20 74  </p>..<p>Since t
5580: 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 5b 50  he actions of [P
5590: 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 5d 20  RAGMA optimize] 
55a0: 61 72 65 20 64 65 74 65 72 6d 69 6e 65 64 20 74  are determined t
55b0: 6f 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  o some extent by
55c0: 0a 70 72 69 6f 72 20 71 75 65 72 69 65 73 20 74  .prior queries t
55d0: 68 61 74 20 68 61 76 65 20 62 65 65 6e 20 65 76  hat have been ev
55e0: 61 6c 75 61 74 65 64 20 6f 6e 20 74 68 65 20 73  aluated on the s
55f0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
5600: 6e 65 63 74 69 6f 6e 2c 20 69 74 0a 69 73 20 72  nection, it.is r
5610: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
5620: 5b 50 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65  [PRAGMA optimize
5630: 5d 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  ] be deferred un
5640: 74 69 6c 20 74 68 65 20 64 61 74 61 62 61 73 65  til the database
5650: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 69 73 20 63   connection.is c
5660: 6c 6f 73 69 6e 67 20 61 6e 64 20 68 61 73 20 74  losing and has t
5670: 68 75 73 20 68 61 64 20 61 6e 20 6f 70 70 6f 72  hus had an oppor
5680: 74 75 6e 69 74 79 20 74 6f 20 61 63 63 75 6d 75  tunity to accumu
5690: 6c 61 74 65 20 61 73 20 6d 75 63 68 20 75 73 61  late as much usa
56a0: 67 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61  ge information.a
56b0: 73 20 70 6f 73 73 69 62 6c 65 2e 20 20 49 74 20  s possible.  It 
56c0: 69 73 20 61 6c 73 6f 20 72 65 61 73 6f 6e 61 62  is also reasonab
56d0: 6c 65 20 74 6f 20 73 65 74 20 61 20 74 69 6d 65  le to set a time
56e0: 72 20 74 6f 20 72 75 6e 20 5b 50 52 41 47 4d 41  r to run [PRAGMA
56f0: 20 6f 70 74 69 6d 69 7a 65 5d 0a 65 76 65 72 79   optimize].every
5700: 20 66 65 77 20 68 6f 75 72 73 2c 20 6f 72 20 65   few hours, or e
5710: 76 65 72 79 20 66 65 77 20 64 61 79 73 2c 20 66  very few days, f
5720: 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  or database conn
5730: 65 63 74 69 6f 6e 73 20 74 68 61 74 20 73 74 61  ections that sta
5740: 79 20 6f 70 65 6e 0a 66 6f 72 20 61 20 6c 6f 6e  y open.for a lon
5750: 67 20 74 69 6d 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e  g time.</p>..<p>
5760: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
5770: 74 20 64 65 73 69 72 65 20 6d 6f 72 65 20 63 6f  t desire more co
5780: 6e 74 72 6f 6c 20 63 61 6e 20 72 75 6e 20 5b 50  ntrol can run [P
5790: 52 41 47 4d 41 20 6f 70 74 69 6d 69 7a 65 28 30  RAGMA optimize(0
57a0: 78 30 33 29 5d 20 74 6f 20 0a 6f 62 74 61 69 6e  x03)] to .obtain
57b0: 20 61 20 6c 69 73 74 20 6f 66 20 41 4e 41 4c 59   a list of ANALY
57c0: 5a 45 20 63 6f 6d 6d 61 6e 64 73 20 74 68 61 74  ZE commands that
57d0: 20 53 51 4c 69 74 65 20 74 68 69 6e 6b 73 20 61   SQLite thinks a
57e0: 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  re appropriate t
57f0: 6f 20 72 75 6e 2c 0a 62 75 74 20 77 69 74 68 6f  o run,.but witho
5800: 75 74 20 61 63 74 75 61 6c 6c 79 20 72 75 6e 6e  ut actually runn
5810: 69 6e 67 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  ing those comman
5820: 64 73 2e 20 20 49 66 20 74 68 65 20 72 65 74 75  ds.  If the retu
5830: 72 6e 65 64 20 73 65 74 20 69 73 20 0a 6e 6f 6e  rned set is .non
5840: 2d 65 6d 70 74 79 2c 20 74 68 65 20 61 70 70 6c  -empty, the appl
5850: 69 63 61 74 69 6f 6e 20 63 61 6e 20 74 68 65 6e  ication can then
5860: 20 6d 61 6b 65 20 61 20 64 65 63 69 73 69 6f 6e   make a decision
5870: 20 61 62 6f 75 74 20 77 68 65 74 68 65 72 20 6f   about whether o
5880: 72 20 6e 6f 74 0a 74 6f 20 72 75 6e 20 74 68 65  r not.to run the
5890: 20 73 75 67 67 65 73 74 65 64 20 41 4e 41 4c 59   suggested ANALY
58a0: 5a 45 20 63 6f 6d 6d 61 6e 64 73 2c 20 70 65 72  ZE commands, per
58b0: 68 61 70 73 20 61 66 74 65 72 20 70 72 6f 6d 70  haps after promp
58c0: 74 69 6e 67 20 74 68 65 20 75 73 65 72 0a 66 6f  ting the user.fo
58d0: 72 20 67 75 69 64 61 6e 63 65 2e 3c 2f 70 3e 0a  r guidance.</p>.
58e0: 0a 3c 70 3e 54 68 65 20 5b 50 52 41 47 4d 41 20  .<p>The [PRAGMA 
58f0: 6f 70 74 69 6d 69 7a 65 5d 20 63 6f 6d 6d 61 6e  optimize] comman
5900: 64 20 77 61 73 20 66 69 72 73 74 20 69 6e 74 72  d was first intr
5910: 6f 64 75 63 65 64 20 77 69 74 68 20 0a 53 51 4c  oduced with .SQL
5920: 69 74 65 20 33 2e 31 38 2e 30 20 28 5b 64 61 74  ite 3.18.0 ([dat
5930: 65 6f 66 3a 33 2e 31 38 2e 30 5d 29 20 61 6e 64  eof:3.18.0]) and
5940: 20 69 73 20 61 20 6e 6f 2d 6f 70 20 66 6f 72 20   is a no-op for 
5950: 61 6c 6c 20 70 72 69 6f 72 20 72 65 6c 65 61 73  all prior releas
5960: 65 73 0a 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70  es.of SQLite.</p
5970: 3e 0a 0a 3c 68 32 3e 41 6e 74 69 63 69 70 61 74  >..<h2>Anticipat
5980: 65 64 20 46 75 74 75 72 65 20 45 6e 68 61 6e 63  ed Future Enhanc
5990: 65 6d 65 6e 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  ements</h2>..<p>
59a0: 41 6c 6c 20 65 78 69 73 74 69 6e 67 20 76 65 72  All existing ver
59b0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
59c0: 64 6f 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20  do a full table 
59d0: 73 63 61 6e 20 66 6f 72 20 41 4e 41 4c 59 5a 45  scan for ANALYZE
59e0: 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 0a 73  .  This can be.s
59f0: 6c 6f 77 20 66 6f 72 20 6d 75 6c 74 69 2d 67 69  low for multi-gi
5a00: 67 61 62 79 74 65 20 61 6e 64 20 6c 61 72 67 65  gabyte and large
5a10: 72 20 64 61 74 61 62 61 73 65 73 2e 20 20 46 75  r databases.  Fu
5a20: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
5a30: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 75 73   SQLite might.us
5a40: 65 20 72 61 6e 64 6f 6d 20 73 61 6d 70 6c 69 6e  e random samplin
5a50: 67 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 20  g rather than a 
5a60: 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 20  full table scan 
5a70: 74 6f 20 6f 62 74 61 69 6e 20 65 73 74 69 6d 61  to obtain estima
5a80: 74 65 73 20 66 6f 72 20 74 68 65 0a 64 61 74 61  tes for the.data
5a90: 62 61 73 65 20 73 68 61 70 65 2c 20 65 73 70 65  base shape, espe
5aa0: 63 69 61 6c 6c 79 20 6f 6e 20 6c 61 72 67 65 72  cially on larger
5ab0: 20 74 61 62 6c 65 73 2e 20 20 54 68 65 20 72 65   tables.  The re
5ac0: 73 75 6c 74 73 20 77 6f 75 6c 64 20 61 70 70 72  sults would appr
5ad0: 6f 78 69 6d 61 74 65 2c 20 62 75 74 20 0a 77 69  oximate, but .wi
5ae0: 6c 6c 20 62 65 20 63 6c 6f 73 65 20 65 6e 6f 75  ll be close enou
5af0: 67 68 20 66 6f 72 20 71 75 65 72 79 20 70 6c 61  gh for query pla
5b00: 6e 6e 69 6e 67 20 70 75 72 70 6f 73 65 73 2e 20  nning purposes. 
5b10: 20 41 73 20 6f 66 20 32 30 31 37 2d 30 33 2d 32   As of 2017-03-2
5b20: 30 2c 20 74 68 69 73 0a 63 6f 6e 63 65 70 74 20  0, this.concept 
5b30: 68 61 73 20 62 65 65 6e 20 74 65 73 74 65 64 20  has been tested 
5b40: 69 6e 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  in experimental 
5b50: 62 72 61 6e 63 68 65 73 20 61 6e 64 20 61 70 70  branches and app
5b60: 65 61 72 73 20 74 6f 20 77 6f 72 6b 20 77 65 6c  ears to work wel
5b70: 6c 2c 20 62 75 74 0a 68 61 73 20 6e 6f 74 20 62  l, but.has not b
5b80: 65 65 6e 20 66 6f 6c 64 65 64 20 69 6e 74 6f 20  een folded into 
5b90: 61 6e 20 6f 66 66 69 63 69 61 6c 20 72 65 6c 65  an official rele
5ba0: 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a  ase.</p>..<tcl>.
5bb0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5bc0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5bd0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5be0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
5bf0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53  ##############.S
5c00: 65 63 74 69 6f 6e 20 7b 41 54 54 41 43 48 20 44  ection {ATTACH D
5c10: 41 54 41 42 41 53 45 7d 20 61 74 74 61 63 68 20  ATABASE} attach 
5c20: 7b 61 74 74 61 63 68 65 64 20 2a 41 54 54 41 43  {attached *ATTAC
5c30: 48 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  H}..RecursiveBub
5c40: 62 6c 65 44 69 61 67 72 61 6d 20 61 74 74 61 63  bleDiagram attac
5c50: 68 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  h-stmt.</tcl>..<
5c60: 70 3e 20 5e 54 68 65 20 41 54 54 41 43 48 20 44  p> ^The ATTACH D
5c70: 41 54 41 42 41 53 45 20 73 74 61 74 65 6d 65 6e  ATABASE statemen
5c80: 74 20 61 64 64 73 20 61 6e 6f 74 68 65 72 20 64  t adds another d
5c90: 61 74 61 62 61 73 65 20 0a 66 69 6c 65 20 74 6f  atabase .file to
5ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 5b 64 61   the current [da
5cb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5cc0: 6e 5d 2e 20 0a 44 61 74 61 62 61 73 65 20 66 69  n]. .Database fi
5cd0: 6c 65 73 20 74 68 61 74 20 77 65 72 65 20 70 72  les that were pr
5ce0: 65 76 69 6f 75 73 6c 79 20 61 74 74 61 63 68 65  eviously attache
5cf0: 64 20 63 61 6e 20 62 65 20 72 65 6d 6f 76 65 64  d can be removed
5d00: 20 75 73 69 6e 67 0a 74 68 65 20 5b 44 45 54 41   using.the [DETA
5d10: 43 48 20 44 41 54 41 42 41 53 45 5d 20 63 6f 6d  CH DATABASE] com
5d20: 6d 61 6e 64 2e 0a 0a 3c 70 3e 5e 54 68 65 20 66  mand...<p>^The f
5d30: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ilename for the 
5d40: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 61  database to be a
5d50: 74 74 61 63 68 65 64 20 69 73 20 74 68 65 20 76  ttached is the v
5d60: 61 6c 75 65 20 6f 66 0a 74 68 65 20 65 78 70 72  alue of.the expr
5d70: 65 73 73 69 6f 6e 20 74 68 61 74 20 6f 63 63 75  ession that occu
5d80: 72 73 20 62 65 66 6f 72 65 20 74 68 65 20 41 53  rs before the AS
5d90: 20 6b 65 79 77 6f 72 64 2e 0a 5e 54 68 65 20 66   keyword..^The f
5da0: 69 6c 65 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ilename of the d
5db0: 61 74 61 62 61 73 65 20 66 6f 6c 6c 6f 77 73 20  atabase follows 
5dc0: 74 68 65 20 73 61 6d 65 20 73 65 6d 61 6e 74 69  the same semanti
5dd0: 63 73 20 61 73 20 74 68 65 0a 66 69 6c 65 6e 61  cs as the.filena
5de0: 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
5df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
5e00: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
5e10: 6e 5f 76 32 28 29 5d 3b 20 74 68 65 0a 73 70 65  n_v2()]; the.spe
5e20: 63 69 61 6c 20 6e 61 6d 65 20 22 5b 3a 6d 65 6d  cial name "[:mem
5e30: 6f 72 79 3a 5d 22 20 72 65 73 75 6c 74 73 20 69  ory:]" results i
5e40: 6e 20 61 6e 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  n an [in-memory 
5e50: 64 61 74 61 62 61 73 65 5d 20 61 6e 64 20 61 6e  database] and an
5e60: 0a 65 6d 70 74 79 20 73 74 72 69 6e 67 20 72 65  .empty string re
5e70: 73 75 6c 74 73 20 69 6e 20 61 20 6e 65 77 20 74  sults in a new t
5e80: 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73  emporary databas
5e90: 65 2e 0a 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  e..^The filename
5ea0: 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
5eb0: 20 61 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65   a [URI filename
5ec0: 5d 20 69 66 20 55 52 49 20 66 69 6c 65 6e 61 6d  ] if URI filenam
5ed0: 65 20 70 72 6f 63 65 73 73 69 6e 67 0a 69 73 20  e processing.is 
5ee0: 65 6e 61 62 6c 65 20 6f 6e 20 74 68 65 20 64 61  enable on the da
5ef0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5f00: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
5f10: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 0a  behavior is for.
5f20: 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 74 6f  URI filenames to
5f30: 20 62 65 20 64 69 73 61 62 6c 65 64 2c 20 68 6f   be disabled, ho
5f40: 77 65 76 65 72 20 74 68 61 74 20 6d 69 67 68 74  wever that might
5f50: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
5f60: 75 72 65 20 72 65 6c 65 61 73 65 0a 6f 66 20 53  ure release.of S
5f70: 51 4c 69 74 65 2c 20 73 6f 20 61 70 70 6c 69 63  QLite, so applic
5f80: 61 74 69 6f 6e 20 64 65 76 65 6c 6f 70 65 72 73  ation developers
5f90: 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
5fa0: 70 6c 61 6e 20 61 63 63 6f 72 64 69 6e 67 6c 79  plan accordingly
5fb0: 2e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 20 74  ...<p>The name t
5fc0: 68 61 74 20 6f 63 63 75 72 73 20 61 66 74 65 72  hat occurs after
5fd0: 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
5fe0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
5ff0: 68 65 20 64 61 74 61 62 61 73 65 0a 75 73 65 64  he database.used
6000: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
6010: 51 4c 69 74 65 2e 0a 5e 54 68 65 20 73 63 68 65  QLite..^The sche
6020: 6d 61 2d 6e 61 6d 65 73 20 27 6d 61 69 6e 27 20  ma-names 'main' 
6030: 61 6e 64 20 0a 27 74 65 6d 70 27 20 72 65 66 65  and .'temp' refe
6040: 72 20 74 6f 20 74 68 65 20 6d 61 69 6e 20 64 61  r to the main da
6050: 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 64  tabase and the d
6060: 61 74 61 62 61 73 65 20 75 73 65 64 20 66 6f 72  atabase used for
6070: 20 0a 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c   .temporary tabl
6080: 65 73 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 61  es.  ^The main a
6090: 6e 64 20 74 65 6d 70 20 64 61 74 61 62 61 73 65  nd temp database
60a0: 73 20 63 61 6e 6e 6f 74 20 62 65 20 61 74 74 61  s cannot be atta
60b0: 63 68 65 64 20 6f 72 0a 64 65 74 61 63 68 65 64  ched or.detached
60c0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28 54 61 62  .</p>..<p> ^(Tab
60d0: 6c 65 73 20 69 6e 20 61 6e 20 61 74 74 61 63 68  les in an attach
60e0: 65 64 20 64 61 74 61 62 61 73 65 20 63 61 6e 20  ed database can 
60f0: 62 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 75  be referred to u
6100: 73 69 6e 67 20 74 68 65 20 73 79 6e 74 61 78 20  sing the syntax 
6110: 0a 3c 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 2e  .<i>schema-name.
6120: 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 69 3e 2e 29  table-name</i>.)
6130: 5e 20 20 5e 49 66 20 74 68 65 20 6e 61 6d 65 20  ^  ^If the name 
6140: 6f 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20  of the table is 
6150: 75 6e 69 71 75 65 0a 61 63 72 6f 73 73 20 61 6c  unique.across al
6160: 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
6170: 61 73 65 73 20 61 6e 64 20 74 68 65 20 6d 61 69  ases and the mai
6180: 6e 20 61 6e 64 20 74 65 6d 70 20 64 61 74 61 62  n and temp datab
6190: 61 73 65 73 2c 20 74 68 65 6e 20 74 68 65 0a 3c  ases, then the.<
61a0: 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 69  i>schema-name</i
61b0: 3e 20 70 72 65 66 69 78 20 69 73 20 6e 6f 74 20  > prefix is not 
61c0: 72 65 71 75 69 72 65 64 2e 20 20 5e 49 66 20 74  required.  ^If t
61d0: 77 6f 20 6f 72 20 6d 6f 72 65 20 74 61 62 6c 65  wo or more table
61e0: 73 20 69 6e 0a 64 69 66 66 65 72 65 6e 74 20 64  s in.different d
61f0: 61 74 61 62 61 73 65 73 20 68 61 76 65 20 74 68  atabases have th
6200: 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 6e 64 20  e same name and 
6210: 74 68 65 20 0a 3c 69 3e 73 63 68 65 6d 61 2d 6e  the .<i>schema-n
6220: 61 6d 65 3c 2f 69 3e 20 70 72 65 66 69 78 20 69  ame</i> prefix i
6230: 73 20 6e 6f 74 20 75 73 65 64 20 6f 6e 20 61 20  s not used on a 
6240: 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 2c  table reference,
6250: 20 74 68 65 6e 20 74 68 65 0a 74 61 62 6c 65 20   then the.table 
6260: 63 68 6f 73 65 6e 20 69 73 20 74 68 65 20 6f 6e  chosen is the on
6270: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
6280: 65 20 74 68 61 74 20 77 61 73 20 6c 65 61 73 74  e that was least
6290: 20 72 65 63 65 6e 74 6c 79 20 61 74 74 61 63 68   recently attach
62a0: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 72  ed.</p>..<p>.^Tr
62b0: 61 6e 73 61 63 74 69 6f 6e 73 20 69 6e 76 6f 6c  ansactions invol
62c0: 76 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 61 74  ving multiple at
62d0: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
62e0: 20 61 72 65 20 61 74 6f 6d 69 63 2c 0a 61 73 73   are atomic,.ass
62f0: 75 6d 69 6e 67 20 74 68 61 74 20 74 68 65 20 6d  uming that the m
6300: 61 69 6e 20 64 61 74 61 62 61 73 65 20 69 73 20  ain database is 
6310: 6e 6f 74 20 22 5b 3a 6d 65 6d 6f 72 79 3a 5d 22  not "[:memory:]"
6320: 20 61 6e 64 20 74 68 65 20 0a 5b 6a 6f 75 72 6e   and the .[journ
6330: 61 6c 5f 6d 6f 64 65 5d 20 69 73 20 6e 6f 74 20  al_mode] is not 
6340: 5b 57 41 4c 5d 2e 20 20 5e 28 49 66 20 74 68 65  [WAL].  ^(If the
6350: 20 6d 61 69 6e 0a 64 61 74 61 62 61 73 65 20 69   main.database i
6360: 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 20 6f 72 20  s ":memory:" or 
6370: 69 66 20 74 68 65 20 6a 6f 75 72 6e 61 6c 5f 6d  if the journal_m
6380: 6f 64 65 20 69 73 20 57 41 4c 2c 20 74 68 65 6e  ode is WAL, then
6390: 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63   .transactions c
63a0: 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 61 74  ontinue to be at
63b0: 6f 6d 69 63 20 77 69 74 68 69 6e 20 65 61 63 68  omic within each
63c0: 20 69 6e 64 69 76 69 64 75 61 6c 0a 64 61 74 61   individual.data
63d0: 62 61 73 65 20 66 69 6c 65 2e 20 42 75 74 20 69  base file. But i
63e0: 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
63f0: 74 65 72 20 63 72 61 73 68 65 73 20 69 6e 20 74  ter crashes in t
6400: 68 65 20 6d 69 64 64 6c 65 0a 6f 66 20 61 20 5b  he middle.of a [
6410: 43 4f 4d 4d 49 54 5d 20 77 68 65 72 65 20 74 77  COMMIT] where tw
6420: 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61  o or more databa
6430: 73 65 20 66 69 6c 65 73 20 61 72 65 20 75 70 64  se files are upd
6440: 61 74 65 64 2c 0a 73 6f 6d 65 20 6f 66 20 74 68  ated,.some of th
6450: 6f 73 65 20 66 69 6c 65 73 20 6d 69 67 68 74 20  ose files might 
6460: 67 65 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  get the changes 
6470: 77 68 65 72 65 20 6f 74 68 65 72 73 0a 6d 69 67  where others.mig
6480: 68 74 20 6e 6f 74 2e 29 5e 0a 3c 2f 70 3e 0a 0a  ht not.)^.</p>..
6490: 3c 70 3e 20 5e 54 68 65 72 65 20 69 73 20 61 20  <p> ^There is a 
64a0: 6c 69 6d 69 74 2c 20 73 65 74 20 75 73 69 6e 67  limit, set using
64b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
64c0: 29 5d 20 61 6e 64 20 0a 5b 53 51 4c 49 54 45 5f  )] and .[SQLITE_
64d0: 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 2c  LIMIT_ATTACHED],
64e0: 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
64f0: 66 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  f databases that
6500: 20 63 61 6e 20 62 65 0a 73 69 6d 75 6c 74 61 6e   can be.simultan
6510: 65 6f 75 73 6c 79 20 61 74 74 61 63 68 65 64 20  eously attached 
6520: 74 6f 20 61 20 73 69 6e 67 6c 65 20 64 61 74 61  to a single data
6530: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
6540: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  </p>..<tcl>.####
6550: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6560: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6570: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6580: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
6590: 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
65a0: 69 6f 6e 20 7b 42 45 47 49 4e 20 54 52 41 4e 53  ion {BEGIN TRANS
65b0: 41 43 54 49 4f 4e 7d 20 74 72 61 6e 73 61 63 74  ACTION} transact
65c0: 69 6f 6e 20 7b 2a 42 45 47 49 4e 20 43 4f 4d 4d  ion {*BEGIN COMM
65d0: 49 54 20 52 4f 4c 4c 42 41 43 4b 7d 0a 0a 52 65  IT ROLLBACK}..Re
65e0: 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
65f0: 67 72 61 6d 20 62 65 67 69 6e 2d 73 74 6d 74 0a  gram begin-stmt.
6600: 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
6610: 69 61 67 72 61 6d 20 63 6f 6d 6d 69 74 2d 73 74  iagram commit-st
6620: 6d 74 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  mt.RecursiveBubb
6630: 6c 65 44 69 61 67 72 61 6d 20 72 6f 6c 6c 62 61  leDiagram rollba
6640: 63 6b 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  ck-stmt.</tcl>..
6650: 3c 70 3e 0a 5e 4e 6f 20 72 65 61 64 73 20 6f 72  <p>.^No reads or
6660: 20 77 72 69 74 65 73 20 6f 63 63 75 72 20 65 78   writes occur ex
6670: 63 65 70 74 20 77 69 74 68 69 6e 20 61 20 74 72  cept within a tr
6680: 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e 41 6e 79 20  ansaction..^Any 
6690: 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 61 63 63  command that acc
66a0: 65 73 73 65 73 20 74 68 65 20 64 61 74 61 62 61  esses the databa
66b0: 73 65 20 28 62 61 73 69 63 61 6c 6c 79 2c 20 61  se (basically, a
66c0: 6e 79 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 2c 0a  ny SQL command,.
66d0: 65 78 63 65 70 74 20 61 20 66 65 77 20 5b 50 52  except a few [PR
66e0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
66f0: 29 0a 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ).will automatic
6700: 61 6c 6c 79 20 73 74 61 72 74 20 61 20 74 72 61  ally start a tra
6710: 6e 73 61 63 74 69 6f 6e 20 69 66 0a 6f 6e 65 20  nsaction if.one 
6720: 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69  is not already i
6730: 6e 20 65 66 66 65 63 74 2e 20 20 5e 41 75 74 6f  n effect.  ^Auto
6740: 6d 61 74 69 63 61 6c 6c 79 20 73 74 61 72 74 65  matically starte
6750: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 61  d transactions.a
6760: 72 65 20 63 6f 6d 6d 69 74 74 65 64 20 77 68 65  re committed whe
6770: 6e 20 74 68 65 20 6c 61 73 74 20 53 51 4c 20 73  n the last SQL s
6780: 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
6790: 73 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 72  s..</p>..<p>.^Tr
67a0: 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 20 62  ansactions can b
67b0: 65 20 73 74 61 72 74 65 64 20 6d 61 6e 75 61 6c  e started manual
67c0: 6c 79 20 75 73 69 6e 67 20 74 68 65 20 42 45 47  ly using the BEG
67d0: 49 4e 0a 63 6f 6d 6d 61 6e 64 2e 20 20 5e 28 53  IN.command.  ^(S
67e0: 75 63 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  uch transactions
67f0: 20 75 73 75 61 6c 6c 79 20 70 65 72 73 69 73 74   usually persist
6800: 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
6810: 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41  COMMIT or ROLLBA
6820: 43 4b 20 63 6f 6d 6d 61 6e 64 2e 20 20 42 75 74  CK command.  But
6830: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77   a transaction w
6840: 69 6c 6c 20 61 6c 73 6f 20 0a 52 4f 4c 4c 42 41  ill also .ROLLBA
6850: 43 4b 20 69 66 20 74 68 65 20 64 61 74 61 62 61  CK if the databa
6860: 73 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  se is closed or 
6870: 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
6880: 72 73 0a 61 6e 64 20 74 68 65 20 52 4f 4c 4c 42  rs.and the ROLLB
6890: 41 43 4b 20 63 6f 6e 66 6c 69 63 74 20 72 65 73  ACK conflict res
68a0: 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
68b0: 6d 20 69 73 20 73 70 65 63 69 66 69 65 64 2e 29  m is specified.)
68c0: 5e 0a 53 65 65 20 74 68 65 20 64 6f 63 75 6d 65  ^.See the docume
68d0: 6e 74 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 5b  ntation on the [
68e0: 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 0a 63 6c 61  ON CONFLICT].cla
68f0: 75 73 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  use for addition
6900: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  al information a
6910: 62 6f 75 74 20 74 68 65 20 52 4f 4c 4c 42 41 43  bout the ROLLBAC
6920: 4b 0a 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  K.conflict resol
6930: 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 2e  ution algorithm.
6940: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 45 4e 44 20  .</p>..<p>.^END 
6950: 54 52 41 4e 53 41 43 54 49 4f 4e 20 69 73 20 61  TRANSACTION is a
6960: 6e 20 61 6c 69 61 73 20 66 6f 72 20 43 4f 4d 4d  n alias for COMM
6970: 49 54 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 20 5e 28  IT..</p>..<p> ^(
6980: 54 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 72 65  Transactions cre
6990: 61 74 65 64 20 75 73 69 6e 67 20 42 45 47 49 4e  ated using BEGIN
69a0: 2e 2e 2e 43 4f 4d 4d 49 54 20 64 6f 20 6e 6f 74  ...COMMIT do not
69b0: 20 6e 65 73 74 2e 29 5e 0a 5e 46 6f 72 20 6e 65   nest.)^.^For ne
69c0: 73 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e  sted transaction
69d0: 73 2c 20 75 73 65 20 74 68 65 20 5b 53 41 56 45  s, use the [SAVE
69e0: 50 4f 49 4e 54 5d 20 61 6e 64 20 5b 52 45 4c 45  POINT] and [RELE
69f0: 41 53 45 5d 20 63 6f 6d 6d 61 6e 64 73 2e 0a 54  ASE] commands..T
6a00: 68 65 20 22 54 4f 20 53 41 56 45 50 4f 49 4e 54  he "TO SAVEPOINT
6a10: 20 3c 79 79 74 65 72 6d 3e 6e 61 6d 65 3c 2f 79   <yyterm>name</y
6a20: 79 74 65 72 6d 3e 22 20 63 6c 61 75 73 65 20 6f  yterm>" clause o
6a30: 66 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63  f the ROLLBACK c
6a40: 6f 6d 6d 61 6e 64 20 73 68 6f 77 6e 0a 69 6e 20  ommand shown.in 
6a50: 74 68 65 20 73 79 6e 74 61 78 20 64 69 61 67 72  the syntax diagr
6a60: 61 6d 20 61 62 6f 76 65 20 69 73 20 6f 6e 6c 79  am above is only
6a70: 20 61 70 70 6c 69 63 61 62 6c 65 20 74 6f 20 5b   applicable to [
6a80: 53 41 56 45 50 4f 49 4e 54 5d 0a 74 72 61 6e 73  SAVEPOINT].trans
6a90: 61 63 74 69 6f 6e 73 2e 20 20 5e 41 6e 20 61 74  actions.  ^An at
6aa0: 74 65 6d 70 74 20 74 6f 20 69 6e 76 6f 6b 65 20  tempt to invoke 
6ab0: 74 68 65 20 42 45 47 49 4e 20 63 6f 6d 6d 61 6e  the BEGIN comman
6ac0: 64 20 77 69 74 68 69 6e 0a 61 20 74 72 61 6e 73  d within.a trans
6ad0: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 66 61 69 6c  action will fail
6ae0: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2c 20   with an error, 
6af0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
6b00: 65 74 68 65 72 0a 74 68 65 20 74 72 61 6e 73 61  ether.the transa
6b10: 63 74 69 6f 6e 20 77 61 73 20 73 74 61 72 74 65  ction was starte
6b20: 64 20 62 79 20 5b 53 41 56 45 50 4f 49 4e 54 5d  d by [SAVEPOINT]
6b30: 20 6f 72 20 61 20 70 72 69 6f 72 20 42 45 47 49   or a prior BEGI
6b40: 4e 2e 0a 5e 54 68 65 20 43 4f 4d 4d 49 54 20 63  N..^The COMMIT c
6b50: 6f 6d 6d 61 6e 64 20 61 6e 64 20 74 68 65 20 52  ommand and the R
6b60: 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64 20  OLLBACK command 
6b70: 77 69 74 68 6f 75 74 20 74 68 65 20 54 4f 20 63  without the TO c
6b80: 6c 61 75 73 65 0a 77 6f 72 6b 20 74 68 65 20 73  lause.work the s
6b90: 61 6d 65 20 6f 6e 20 5b 53 41 56 45 50 4f 49 4e  ame on [SAVEPOIN
6ba0: 54 5d 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  T] transactions 
6bb0: 61 73 20 74 68 65 79 20 64 6f 20 77 69 74 68 20  as they do with 
6bc0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 73 74 61  transactions.sta
6bd0: 72 74 65 64 20 62 79 20 42 45 47 49 4e 2e 3c 2f  rted by BEGIN.</
6be0: 70 3e 0a 0a 3c 68 33 3e 52 65 61 64 20 74 72 61  p>..<h3>Read tra
6bf0: 6e 73 61 63 74 69 6f 6e 73 20 76 65 72 73 75 73  nsactions versus
6c00: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
6c10: 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 51 4c  ons</h3>..<p>SQL
6c20: 69 74 65 20 63 75 72 72 65 6e 74 20 73 75 70 70  ite current supp
6c30: 6f 72 74 73 20 6d 75 6c 74 69 70 6c 65 20 73 69  orts multiple si
6c40: 6d 75 6c 74 61 6e 65 6f 75 73 20 72 65 61 64 20  multaneous read 
6c50: 74 72 61 6e 73 61 63 74 69 6f 6e 73 0a 63 6f 6d  transactions.com
6c60: 69 6e 67 20 66 72 6f 6d 20 73 65 70 61 72 61 74  ing from separat
6c70: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
6c80: 63 74 69 6f 6e 73 2c 20 70 6f 73 73 69 62 6c 79  ctions, possibly
6c90: 20 69 6e 20 73 65 70 61 72 61 74 65 0a 74 68 72   in separate.thr
6ca0: 65 61 64 73 20 6f 72 20 70 72 6f 63 65 73 73 65  eads or processe
6cb0: 73 2c 20 62 75 74 20 6f 6e 6c 79 20 6f 6e 65 20  s, but only one 
6cc0: 73 69 6d 75 6c 74 61 6e 65 6f 75 73 20 77 72 69  simultaneous wri
6cd0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a  te transaction..
6ce0: 3c 70 3e 0a 0a 3c 70 3e 41 20 72 65 61 64 20 74  <p>..<p>A read t
6cf0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 75 73  ransaction is us
6d00: 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  ed for reading o
6d10: 6e 6c 79 2e 20 20 41 20 77 72 69 74 65 20 74 72  nly.  A write tr
6d20: 61 6e 73 61 63 74 69 6f 6e 0a 61 6c 6c 6f 77 73  ansaction.allows
6d30: 20 62 6f 74 68 20 72 65 61 64 69 6e 67 20 61 6e   both reading an
6d40: 64 20 77 72 69 74 69 6e 67 2e 20 20 41 20 72 65  d writing.  A re
6d50: 61 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad transaction i
6d60: 73 20 73 74 61 72 74 65 64 0a 62 79 20 61 20 53  s started.by a S
6d70: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c  ELECT statement,
6d80: 20 61 6e 64 20 61 20 77 72 69 74 65 20 74 72 61   and a write tra
6d90: 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 74 61 72  nsaction is star
6da0: 74 65 64 20 62 79 20 0a 73 74 61 74 65 6d 65 6e  ted by .statemen
6db0: 74 73 20 6c 69 6b 65 20 43 52 45 41 54 45 2c 20  ts like CREATE, 
6dc0: 44 45 4c 45 54 45 2c 20 44 52 4f 50 2c 20 49 4e  DELETE, DROP, IN
6dd0: 53 45 52 54 2c 20 6f 72 20 55 50 44 41 54 45 20  SERT, or UPDATE 
6de0: 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 0a 22 77  (collectively."w
6df0: 72 69 74 65 20 73 74 61 74 65 6d 65 6e 74 73 22  rite statements"
6e00: 29 2e 20 20 49 66 20 61 20 77 72 69 74 65 20 73  ).  If a write s
6e10: 74 61 74 65 6d 65 6e 74 20 6f 63 63 75 72 73 20  tatement occurs 
6e20: 77 68 69 6c 65 0a 61 20 72 65 61 64 20 74 72 61  while.a read tra
6e30: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 63 74 69  nsaction is acti
6e40: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 72 65 61  ve, then the rea
6e50: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  d transaction is
6e60: 20 75 70 67 72 61 64 65 64 0a 74 6f 20 77 72 69   upgraded.to wri
6e70: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  te transaction i
6e80: 66 20 70 6f 73 73 69 62 6c 65 2e 20 20 49 66 20  f possible.  If 
6e90: 73 6f 6d 65 20 6f 74 68 65 72 20 64 61 74 61 62  some other datab
6ea0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 68  ase connection.h
6eb0: 61 73 20 61 6c 72 65 61 64 79 20 6d 6f 64 69 66  as already modif
6ec0: 69 65 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ied the database
6ed0: 20 6f 72 20 69 73 20 61 6c 72 65 61 64 79 20 69   or is already i
6ee0: 6e 20 74 68 65 20 70 72 6f 63 65 73 73 20 6f 66  n the process of
6ef0: 0a 6d 6f 64 69 66 79 69 6e 67 20 74 68 65 20 64  .modifying the d
6f00: 61 74 61 62 61 73 65 2c 20 74 68 65 6e 20 75 70  atabase, then up
6f10: 67 72 61 64 69 6e 67 20 74 6f 20 61 20 77 72 69  grading to a wri
6f20: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  te transaction i
6f30: 73 0a 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  s.not possible a
6f40: 6e 64 20 74 68 65 20 77 72 69 74 65 20 73 74 61  nd the write sta
6f50: 74 65 6d 65 6e 74 20 77 69 6c 6c 20 66 61 69 6c  tement will fail
6f60: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 42 55   with [SQLITE_BU
6f70: 53 59 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57  SY]..</p>..<p>.W
6f80: 68 69 6c 65 20 61 20 72 65 61 64 20 74 72 61 6e  hile a read tran
6f90: 73 61 63 74 69 6f 6e 20 69 73 20 61 63 74 69 76  saction is activ
6fa0: 65 2c 20 61 6e 79 20 63 68 61 6e 67 65 73 20 74  e, any changes t
6fb0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
6fc0: 68 61 74 0a 61 72 65 20 69 6d 70 6c 65 6d 65 6e  hat.are implemen
6fd0: 74 65 64 20 62 79 20 73 65 70 61 72 61 74 65 20  ted by separate 
6fe0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
6ff0: 69 6f 6e 73 20 77 69 6c 6c 20 6e 6f 74 20 62 65  ions will not be
7000: 20 73 65 65 6e 0a 62 79 20 74 68 65 20 64 61 74   seen.by the dat
7010: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7020: 20 74 68 61 74 20 73 74 61 72 74 65 64 20 74 68   that started th
7030: 65 20 72 65 61 64 20 74 72 61 6e 73 61 63 74 69  e read transacti
7040: 6f 6e 2e 20 20 49 66 20 64 61 74 61 62 61 73 65  on.  If database
7050: 0a 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73  .connection X is
7060: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
7070: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 69 74 20  transaction, it 
7080: 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74  is possible that
7090: 20 73 6f 6d 65 0a 6f 74 68 65 72 20 64 61 74 61   some.other data
70a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
70b0: 59 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  Y might change t
70c0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
70d0: 65 20 64 61 74 61 62 61 73 65 0a 77 68 69 6c 65  e database.while
70e0: 20 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e   X's transaction
70f0: 20 69 73 20 73 74 69 6c 6c 20 6f 70 65 6e 2c 20   is still open, 
7100: 68 6f 77 65 76 65 72 20 58 20 77 69 6c 6c 20 6e  however X will n
7110: 6f 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 65  ot be able to se
7120: 65 20 0a 74 68 6f 73 65 20 63 68 61 6e 67 65 73  e .those changes
7130: 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
7140: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 65 6e 64   transaction end
7150: 73 2e 20 20 57 68 69 6c 65 20 69 74 73 20 72 65  s.  While its re
7160: 61 64 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad.transaction i
7170: 73 20 61 63 74 69 76 65 2c 20 58 20 77 69 6c 6c  s active, X will
7180: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 65 65   continue to see
7190: 20 61 6e 20 68 69 73 74 6f 72 69 63 20 73 6e 61   an historic sna
71a0: 70 73 68 6f 74 0a 74 68 65 20 64 61 74 61 62 61  pshot.the databa
71b0: 73 65 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  se prior to the 
71c0: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
71d0: 74 65 64 20 62 79 20 59 2e 0a 3c 2f 70 3e 0a 0a  ted by Y..</p>..
71e0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
71f0: 74 20 69 6d 6d 65 64 69 61 74 65 20 7b 42 45 47  t immediate {BEG
7200: 49 4e 20 49 4d 4d 45 44 49 41 54 45 7d 20 7b 42  IN IMMEDIATE} {B
7210: 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 7d 3c  EGIN EXCLUSIVE}<
7220: 2f 74 63 6c 3e 0a 3c 68 33 3e 44 45 46 45 52 52  /tcl>.<h3>DEFERR
7230: 45 44 2c 20 49 4d 4d 45 44 49 41 54 45 2c 20 61  ED, IMMEDIATE, a
7240: 6e 64 20 45 58 43 4c 55 53 49 56 45 20 74 72 61  nd EXCLUSIVE tra
7250: 6e 73 61 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a  nsactions</h3>..
7260: 3c 70 3e 0a 5e 54 72 61 6e 73 61 63 74 69 6f 6e  <p>.^Transaction
7270: 73 20 63 61 6e 20 62 65 20 44 45 46 45 52 52 45  s can be DEFERRE
7280: 44 2c 20 49 4d 4d 45 44 49 41 54 45 2c 20 6f 72  D, IMMEDIATE, or
7290: 20 45 58 43 4c 55 53 49 56 45 2e 0a 5e 54 68 65   EXCLUSIVE..^The
72a0: 20 64 65 66 61 75 6c 74 20 74 72 61 6e 73 61 63   default transac
72b0: 74 69 6f 6e 20 62 65 68 61 76 69 6f 72 20 69 73  tion behavior is
72c0: 20 44 45 46 45 52 52 45 44 2e 0a 3c 2f 70 3e 0a   DEFERRED..</p>.
72d0: 0a 3c 70 3e 0a 5e 44 45 46 45 52 52 45 44 20 6d  .<p>.^DEFERRED m
72e0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 72  eans that the tr
72f0: 61 6e 73 61 63 74 69 6f 6e 20 64 6f 65 73 20 6e  ansaction does n
7300: 6f 74 20 61 63 74 75 61 6c 6c 79 0a 73 74 61 72  ot actually.star
7310: 74 20 75 6e 74 69 6c 20 74 68 65 20 64 61 74 61  t until the data
7320: 62 61 73 65 20 69 73 20 66 69 72 73 74 20 61 63  base is first ac
7330: 63 65 73 73 65 64 2e 20 20 5e 49 6e 74 65 72 6e  cessed.  ^Intern
7340: 61 6c 6c 79 2c 0a 74 68 65 20 42 45 47 49 4e 20  ally,.the BEGIN 
7350: 44 45 46 45 52 52 52 45 44 20 73 74 61 74 65 6d  DEFERRRED statem
7360: 65 6e 74 20 6d 65 72 65 6c 79 20 73 65 74 73 20  ent merely sets 
7370: 61 20 66 6c 61 67 20 6f 6e 20 74 68 65 20 64 61  a flag on the da
7380: 74 61 62 61 73 65 20 0a 63 6f 6e 6e 65 63 74 69  tabase .connecti
7390: 6f 6e 20 74 68 61 74 20 74 75 72 6e 73 20 6f 66  on that turns of
73a0: 66 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  f the automatic 
73b0: 63 6f 6d 6d 69 74 20 74 68 61 74 20 77 6f 75 6c  commit that woul
73c0: 64 20 6e 6f 72 6d 61 6c 6c 79 0a 6f 63 63 75 72  d normally.occur
73d0: 20 77 68 65 6e 20 74 68 65 20 6c 61 73 74 20 73   when the last s
73e0: 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
73f0: 73 2e 20 20 54 68 69 73 20 63 61 75 73 65 73 20  s.  This causes 
7400: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  the transaction.
7410: 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69  that is automati
7420: 63 61 6c 6c 79 20 73 74 61 72 74 65 64 20 74 6f  cally started to
7430: 20 70 65 72 73 69 73 74 20 75 6e 74 69 6c 20 61   persist until a
7440: 6e 20 65 78 70 6c 69 63 69 74 0a 43 4f 4d 4d 49  n explicit.COMMI
7450: 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 20 6f 72  T or ROLLBACK or
7460: 20 75 6e 74 69 6c 20 61 20 72 6f 6c 6c 62 61 63   until a rollbac
7470: 6b 20 69 73 20 70 72 6f 76 6f 6b 65 64 20 62 79  k is provoked by
7480: 20 61 6e 20 65 72 72 6f 72 0a 6f 72 20 61 6e 20   an error.or an 
7490: 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 4f 4c 4c  ON CONFLICT ROLL
74a0: 42 41 43 4b 20 63 6c 61 75 73 65 2e 20 20 49 66  BACK clause.  If
74b0: 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
74c0: 6d 65 6e 74 20 61 66 74 65 72 0a 42 45 47 49 4e  ment after.BEGIN
74d0: 20 44 45 46 45 52 52 45 44 20 69 73 20 61 20 53   DEFERRED is a S
74e0: 45 4c 45 43 54 2c 20 74 68 65 6e 20 61 20 72 65  ELECT, then a re
74f0: 61 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  ad transaction i
7500: 73 20 73 74 61 72 74 65 64 2e 0a 53 75 62 73 65  s started..Subse
7510: 71 75 65 6e 74 20 77 72 69 74 65 20 73 74 61 74  quent write stat
7520: 65 6d 65 6e 74 73 20 77 69 6c 6c 20 75 70 67 72  ements will upgr
7530: 61 64 65 20 74 68 65 20 74 72 61 6e 73 61 63 74  ade the transact
7540: 69 6f 6e 20 74 6f 20 61 0a 77 72 69 74 65 20 74  ion to a.write t
7550: 72 61 6e 73 61 63 74 69 6f 6e 20 69 66 20 70 6f  ransaction if po
7560: 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 74 75 72  ssible, or retur
7570: 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
7580: 49 66 20 74 68 65 0a 66 69 72 73 74 20 73 74 61  If the.first sta
7590: 74 65 6d 65 6e 74 20 61 66 74 65 72 20 42 45 47  tement after BEG
75a0: 49 4e 20 44 45 46 45 52 52 45 44 20 69 73 20 61  IN DEFERRED is a
75b0: 20 77 72 69 74 65 20 73 74 61 74 65 6d 65 6e 74   write statement
75c0: 2c 20 74 68 65 6e 0a 61 20 77 72 69 74 65 20 74  , then.a write t
75d0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 74  ransaction is st
75e0: 61 72 74 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  arted..</p>..<p>
75f0: 0a 5e 49 4d 4d 45 44 49 41 54 45 20 63 61 75 73  .^IMMEDIATE caus
7600: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
7610: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 73 74 61  onnection to sta
7620: 72 74 20 61 20 6e 65 77 20 77 72 69 74 65 0a 69  rt a new write.i
7630: 6d 6d 65 64 69 61 74 65 6c 79 2c 20 77 69 74 68  mmediately, with
7640: 6f 75 74 20 77 61 69 74 69 6e 67 20 66 6f 72 20  out waiting for 
7650: 61 20 77 72 69 74 65 73 20 73 74 61 74 65 6d 65  a writes stateme
7660: 6e 74 2e 20 20 54 68 65 20 0a 42 45 47 49 4e 20  nt.  The .BEGIN 
7670: 49 4d 4d 45 44 49 41 54 45 20 6d 69 67 68 74 20  IMMEDIATE might 
7680: 66 61 69 6c 20 77 69 74 68 20 5b 53 51 4c 49 54  fail with [SQLIT
7690: 45 5f 42 55 53 59 5d 20 69 66 20 61 6e 6f 74 68  E_BUSY] if anoth
76a0: 65 72 20 77 72 69 74 65 0a 74 72 61 6e 73 61 63  er write.transac
76b0: 74 69 6f 6e 20 69 73 20 61 6c 72 65 61 64 79 20  tion is already 
76c0: 61 63 74 69 76 65 20 6f 6e 20 61 6e 6f 74 68 65  active on anothe
76d0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
76e0: 63 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  ction..</p>..<p>
76f0: 0a 5e 45 58 43 4c 55 53 49 56 45 20 69 73 20 73  .^EXCLUSIVE is s
7700: 69 6d 69 6c 61 72 20 74 6f 20 49 4d 4d 45 44 49  imilar to IMMEDI
7710: 41 54 45 20 69 6e 20 74 68 61 74 20 61 20 77 72  ATE in that a wr
7720: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ite transaction.
7730: 69 73 20 73 74 61 72 74 65 64 20 69 6d 6d 65 64  is started immed
7740: 69 61 74 65 6c 79 2e 20 20 45 58 43 4c 55 53 49  iately.  EXCLUSI
7750: 56 45 20 61 6e 64 20 49 4d 4d 45 44 49 41 54 45  VE and IMMEDIATE
7760: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 69 6e   are the same.in
7770: 20 5b 57 41 4c 20 6d 6f 64 65 5d 2c 20 62 75 74   [WAL mode], but
7780: 20 69 6e 20 6f 74 68 65 72 20 6a 6f 75 72 6e 61   in other journa
7790: 6c 69 6e 67 20 6d 6f 64 65 73 2c 20 45 58 43 4c  ling modes, EXCL
77a0: 55 53 49 56 45 20 70 72 65 76 65 6e 74 73 0a 6f  USIVE prevents.o
77b0: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
77c0: 6e 6e 65 63 74 69 6f 6e 73 20 66 72 6f 6d 20 72  nnections from r
77d0: 65 61 64 69 6e 67 20 74 68 65 20 64 61 74 61 62  eading the datab
77e0: 61 73 65 20 77 68 69 6c 65 20 74 68 65 0a 74 72  ase while the.tr
77f0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 75 6e 64  ansaction is und
7800: 65 72 77 61 79 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33  erway..</p>..<h3
7810: 3e 49 6d 70 6c 69 63 69 74 20 76 65 72 73 75 73  >Implicit versus
7820: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
7830: 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  ctions</h3>..<p>
7840: 0a 41 6e 20 69 6d 70 6c 69 63 69 74 20 74 72 61  .An implicit tra
7850: 6e 73 61 63 74 69 6f 6e 20 28 61 20 74 72 61 6e  nsaction (a tran
7860: 73 61 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  saction that is 
7870: 73 74 61 72 74 65 64 20 61 75 74 6f 6d 61 74 69  started automati
7880: 63 61 6c 6c 79 2c 0a 6e 6f 74 20 61 20 74 72 61  cally,.not a tra
7890: 6e 73 61 63 74 69 6f 6e 20 73 74 61 72 74 65 64  nsaction started
78a0: 20 62 79 20 42 45 47 49 4e 29 20 69 73 20 63 6f   by BEGIN) is co
78b0: 6d 6d 69 74 74 65 64 20 61 75 74 6f 6d 61 74 69  mmitted automati
78c0: 63 61 6c 6c 79 20 77 68 65 6e 0a 74 68 65 20 6c  cally when.the l
78d0: 61 73 74 20 61 63 74 69 76 65 20 73 74 61 74 65  ast active state
78e0: 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
78f0: 41 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  A statement fini
7900: 73 68 65 73 20 77 68 65 6e 20 69 74 73 0a 6c 61  shes when its.la
7910: 73 74 20 63 75 72 73 6f 72 20 63 6c 6f 73 65 73  st cursor closes
7920: 2c 20 77 68 69 63 68 20 69 73 20 67 75 61 72 61  , which is guara
7930: 6e 74 65 65 64 20 74 6f 20 68 61 70 70 65 6e 20  nteed to happen 
7940: 77 68 65 6e 20 74 68 65 0a 70 72 65 70 61 72 65  when the.prepare
7950: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 5b  d statement is [
7960: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
7970: 7c 20 72 65 73 65 74 5d 20 6f 72 0a 5b 73 71 6c  | reset] or.[sql
7980: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
7990: 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 2e 20 20 53  | finalized].  S
79a0: 6f 6d 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  ome statements m
79b0: 69 67 68 74 20 22 66 69 6e 69 73 68 22 0a 66 6f  ight "finish".fo
79c0: 72 20 74 68 65 20 70 75 72 70 6f 73 65 20 6f 66  r the purpose of
79d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
79e0: 74 72 6f 6c 20 70 72 69 6f 72 20 74 6f 20 62 65  trol prior to be
79f0: 69 6e 67 20 72 65 73 65 74 20 6f 72 20 66 69 6e  ing reset or fin
7a00: 61 6c 69 7a 65 64 2c 0a 62 75 74 20 74 68 65 72  alized,.but ther
7a10: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
7a20: 65 20 6f 66 20 74 68 69 73 2e 20 20 54 68 65 20  e of this.  The 
7a30: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 65 6e 73 75  only way to ensu
7a40: 72 65 20 74 68 61 74 20 61 0a 73 74 61 74 65 6d  re that a.statem
7a50: 65 6e 74 20 68 61 73 20 22 66 69 6e 69 73 68 65  ent has "finishe
7a60: 64 22 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  d" is to invoke 
7a70: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
7a80: 5d 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f 66 69  ] or.[sqlite3_fi
7a90: 6e 61 6c 69 7a 65 28 29 5d 20 6f 6e 20 74 68 61  nalize()] on tha
7aa0: 74 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 6e  t statement.  An
7ab0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
7ac0: 6c 6f 62 5d 20 75 73 65 64 20 66 6f 72 0a 69 6e  lob] used for.in
7ad0: 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
7ae0: 2f 4f 20 61 6c 73 6f 20 63 6f 75 6e 74 73 20 61  /O also counts a
7af0: 73 20 61 6e 20 75 6e 66 69 6e 69 73 68 65 64 20  s an unfinished 
7b00: 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 20 5b  statement..The [
7b10: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 66 69  sqlite3_blob] fi
7b20: 6e 69 73 68 65 73 20 77 68 65 6e 20 69 74 20 69  nishes when it i
7b30: 73 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  s [sqlite3_blob_
7b40: 63 6c 6f 73 65 28 29 20 7c 20 63 6c 6f 73 65 64  close() | closed
7b50: 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 68  ]..</p>..<p>.^Th
7b60: 65 20 65 78 70 6c 69 63 69 74 20 43 4f 4d 4d 49  e explicit COMMI
7b70: 54 20 63 6f 6d 6d 61 6e 64 20 72 75 6e 73 20 69  T command runs i
7b80: 6d 6d 65 64 69 61 74 65 6c 79 2c 20 65 76 65 6e  mmediately, even
7b90: 20 69 66 20 74 68 65 72 65 20 61 72 65 0a 70 65   if there are.pe
7ba0: 6e 64 69 6e 67 20 5b 53 45 4c 45 43 54 5d 20 73  nding [SELECT] s
7bb0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 48 6f 77  tatements.  ^How
7bc0: 65 76 65 72 2c 20 69 66 20 74 68 65 72 65 20 61  ever, if there a
7bd0: 72 65 20 70 65 6e 64 69 6e 67 0a 77 72 69 74 65  re pending.write
7be0: 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 74 68 65   operations, the
7bf0: 20 43 4f 4d 4d 49 54 20 63 6f 6d 6d 61 6e 64 0a   COMMIT command.
7c00: 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
7c10: 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 5b 53 51  n error code [SQ
7c20: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 3c 2f 70 3e  LITE_BUSY]..</p>
7c30: 0a 0a 3c 70 3e 0a 5e 41 6e 20 61 74 74 65 6d 70  ..<p>.^An attemp
7c40: 74 20 74 6f 20 65 78 65 63 75 74 65 20 43 4f 4d  t to execute COM
7c50: 4d 49 54 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  MIT might also r
7c60: 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
7c70: 49 54 45 5f 42 55 53 59 5d 20 72 65 74 75 72 6e  ITE_BUSY] return
7c80: 20 63 6f 64 65 0a 69 66 20 61 6e 20 61 6e 6f 74   code.if an anot
7c90: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
7ca0: 6f 63 65 73 73 20 68 61 73 20 61 6e 20 6f 70 65  ocess has an ope
7cb0: 6e 20 72 65 61 64 20 63 6f 6e 6e 65 63 74 69 6f  n read connectio
7cc0: 6e 2e 0a 5e 57 68 65 6e 20 43 4f 4d 4d 49 54 20  n..^When COMMIT 
7cd0: 66 61 69 6c 73 20 69 6e 20 74 68 69 73 0a 77 61  fails in this.wa
7ce0: 79 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  y, the transacti
7cf0: 6f 6e 20 72 65 6d 61 69 6e 73 20 61 63 74 69 76  on remains activ
7d00: 65 20 61 6e 64 20 74 68 65 20 43 4f 4d 4d 49 54  e and the COMMIT
7d10: 20 63 61 6e 20 62 65 20 72 65 74 72 69 65 64 20   can be retried 
7d20: 6c 61 74 65 72 0a 61 66 74 65 72 20 74 68 65 20  later.after the 
7d30: 72 65 61 64 65 72 20 68 61 73 20 68 61 64 20 61  reader has had a
7d40: 20 63 68 61 6e 63 65 20 74 6f 20 63 6c 65 61 72   chance to clear
7d50: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 6e 20 76  ..</p>..<p>.In v
7d60: 65 72 79 20 6f 6c 64 20 76 65 72 73 69 6f 6e 73  ery old versions
7d70: 20 6f 66 20 53 51 4c 69 74 65 20 28 62 65 66 6f   of SQLite (befo
7d80: 72 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  re version 3.7.1
7d90: 31 20 2d 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e  1 - [dateof:3.7.
7da0: 31 31 5d 29 0a 74 68 65 20 52 4f 4c 4c 42 41 43  11]).the ROLLBAC
7db0: 4b 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  K will fail with
7dc0: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 0a   an error code .
7dd0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66  [SQLITE_BUSY] if
7de0: 20 74 68 65 72 65 20 61 72 65 20 61 6e 79 20 70   there are any p
7df0: 65 6e 64 69 6e 67 20 71 75 65 72 69 65 73 2e 20  ending queries. 
7e00: 20 5e 49 6e 20 6d 6f 72 65 20 72 65 63 65 6e 74   ^In more recent
7e10: 0a 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c  .versions of SQL
7e20: 69 74 65 2c 20 74 68 65 20 52 4f 4c 4c 42 41 43  ite, the ROLLBAC
7e30: 4b 20 77 69 6c 6c 20 70 72 6f 63 65 65 64 20 61  K will proceed a
7e40: 6e 64 20 70 65 6e 64 69 6e 67 20 73 74 61 74 65  nd pending state
7e50: 6d 65 6e 74 73 0a 77 69 6c 6c 20 6f 66 74 65 6e  ments.will often
7e60: 20 62 65 20 61 62 6f 72 74 65 64 2c 20 63 61 75   be aborted, cau
7e70: 73 69 6e 67 20 74 68 65 6d 20 74 6f 20 72 65 74  sing them to ret
7e80: 75 72 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 41  urn an [SQLITE_A
7e90: 42 4f 52 54 5d 20 6f 72 0a 5b 53 51 4c 49 54 45  BORT] or.[SQLITE
7ea0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 5d  _ABORT_ROLLBACK]
7eb0: 20 65 72 72 6f 72 2e 0a 5e 49 6e 20 53 51 4c 69   error..^In SQLi
7ec0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 38 2e 38  te version 3.8.8
7ed0: 20 28 5b 64 61 74 65 6f 66 3a 33 2e 38 2e 38 5d   ([dateof:3.8.8]
7ee0: 29 20 61 6e 64 20 6c 61 74 65 72 2c 0a 61 20 70  ) and later,.a p
7ef0: 65 6e 64 69 6e 67 20 72 65 61 64 20 77 69 6c 6c  ending read will
7f00: 20 63 6f 6e 74 69 6e 75 65 20 66 75 6e 63 74 69   continue functi
7f10: 6f 6e 69 6e 67 0a 61 66 74 65 72 20 74 68 65 20  oning.after the 
7f20: 52 4f 4c 4c 42 41 43 4b 20 61 73 20 6c 6f 6e 67  ROLLBACK as long
7f30: 20 61 73 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b   as the ROLLBACK
7f40: 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
7f50: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 73 63   the database.sc
7f60: 68 65 6d 61 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  hema..</p>..<p>.
7f70: 49 66 20 5b 50 52 41 47 4d 41 20 6a 6f 75 72 6e  If [PRAGMA journ
7f80: 61 6c 5f 6d 6f 64 65 5d 20 69 73 20 73 65 74 20  al_mode] is set 
7f90: 74 6f 20 4f 46 46 20 28 74 68 75 73 20 64 69 73  to OFF (thus dis
7fa0: 61 62 6c 69 6e 67 20 74 68 65 20 72 6f 6c 6c 62  abling the rollb
7fb0: 61 63 6b 20 6a 6f 75 72 6e 61 6c 0a 66 69 6c 65  ack journal.file
7fc0: 29 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  ) then the behav
7fd0: 69 6f 72 20 6f 66 20 74 68 65 20 52 4f 4c 4c 42  ior of the ROLLB
7fe0: 41 43 4b 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75  ACK command is u
7ff0: 6e 64 65 66 69 6e 65 64 2e 0a 3c 2f 70 3e 0a 0a  ndefined..</p>..
8000: 3c 68 33 3e 52 65 73 70 6f 6e 73 65 20 54 6f 20  <h3>Response To 
8010: 45 72 72 6f 72 73 20 57 69 74 68 69 6e 20 41 20  Errors Within A 
8020: 54 72 61 6e 73 61 63 74 69 6f 6e 3c 2f 68 33 3e  Transaction</h3>
8030: 0a 0a 3c 70 3e 20 5e 28 49 66 20 63 65 72 74 61  ..<p> ^(If certa
8040: 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
8050: 72 73 20 6f 63 63 75 72 20 77 69 74 68 69 6e 20  rs occur within 
8060: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  a transaction, t
8070: 68 65 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  he.transaction m
8080: 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
8090: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
80a0: 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
80b0: 0a 65 72 72 6f 72 73 20 74 68 61 74 20 63 61 6e  .errors that can
80c0: 20 63 61 75 73 65 20 61 6e 20 61 75 74 6f 6d 61   cause an automa
80d0: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 69 6e 63  tic rollback inc
80e0: 6c 75 64 65 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a  lude:</p>..<ul>.
80f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 46 55 4c  <li> [SQLITE_FUL
8100: 4c 5d 3a 20 64 61 74 61 62 61 73 65 20 6f 72 20  L]: database or 
8110: 64 69 73 6b 20 66 75 6c 6c 0a 3c 6c 69 3e 20 5b  disk full.<li> [
8120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 3a 20 64  SQLITE_IOERR]: d
8130: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 0a 3c 6c  isk I/O error.<l
8140: 69 3e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  i> [SQLITE_BUSY]
8150: 3a 20 64 61 74 61 62 61 73 65 20 69 6e 20 75 73  : database in us
8160: 65 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f  e by another pro
8170: 63 65 73 73 0a 3c 6c 69 3e 20 5b 53 51 4c 49 54  cess.<li> [SQLIT
8180: 45 5f 4e 4f 4d 45 4d 5d 3a 20 6f 75 74 20 6f 72  E_NOMEM]: out or
8190: 20 6d 65 6d 6f 72 79 0a 3c 2f 75 6c 3e 29 5e 0a   memory.</ul>)^.
81a0: 0a 3c 70 3e 0a 5e 46 6f 72 20 61 6c 6c 20 6f 66  .<p>.^For all of
81b0: 20 74 68 65 73 65 20 65 72 72 6f 72 73 2c 20 53   these errors, S
81c0: 51 4c 69 74 65 20 61 74 74 65 6d 70 74 73 20 74  QLite attempts t
81d0: 6f 20 75 6e 64 6f 20 6a 75 73 74 20 74 68 65 20  o undo just the 
81e0: 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 0a 69 74  one statement.it
81f0: 20 77 61 73 20 77 6f 72 6b 69 6e 67 20 6f 6e 20   was working on 
8200: 61 6e 64 20 6c 65 61 76 65 20 63 68 61 6e 67 65  and leave change
8210: 73 20 66 72 6f 6d 20 70 72 69 6f 72 20 73 74 61  s from prior sta
8220: 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 74  tements within t
8230: 68 65 0a 73 61 6d 65 20 74 72 61 6e 73 61 63 74  he.same transact
8240: 69 6f 6e 20 69 6e 74 61 63 74 20 61 6e 64 20 63  ion intact and c
8250: 6f 6e 74 69 6e 75 65 20 77 69 74 68 20 74 68 65  ontinue with the
8260: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 5e   transaction.  ^
8270: 48 6f 77 65 76 65 72 2c 20 0a 64 65 70 65 6e 64  However, .depend
8280: 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 65  ing on the state
8290: 6d 65 6e 74 20 62 65 69 6e 67 20 65 76 61 6c 75  ment being evalu
82a0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 70 6f 69  ated and the poi
82b0: 6e 74 20 61 74 20 77 68 69 63 68 20 74 68 65 0a  nt at which the.
82c0: 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 69 74  error occurs, it
82d0: 20 6d 69 67 68 74 20 62 65 20 6e 65 63 65 73 73   might be necess
82e0: 61 72 79 20 66 6f 72 20 53 51 4c 69 74 65 20 74  ary for SQLite t
82f0: 6f 20 72 6f 6c 6c 62 61 63 6b 20 61 6e 64 0a 63  o rollback and.c
8300: 61 6e 63 65 6c 20 74 68 65 20 65 6e 74 69 72 65  ancel the entire
8310: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 5e   transaction.  ^
8320: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  An application c
8330: 61 6e 20 74 65 6c 6c 20 77 68 69 63 68 0a 63 6f  an tell which.co
8340: 75 72 73 65 20 6f 66 20 61 63 74 69 6f 6e 20 53  urse of action S
8350: 51 4c 69 74 65 20 74 6f 6f 6b 20 62 79 20 75 73  QLite took by us
8360: 69 6e 67 20 74 68 65 0a 5b 73 71 6c 69 74 65 33  ing the.[sqlite3
8370: 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
8380: 29 5d 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6e  )] C-language in
8390: 74 65 72 66 61 63 65 2e 3c 2f 70 3e 0a 0a 3c 70  terface.</p>..<p
83a0: 3e 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  >It is recommend
83b0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
83c0: 69 6f 6e 73 20 72 65 73 70 6f 6e 64 20 74 6f 20  ions respond to 
83d0: 74 68 65 20 65 72 72 6f 72 73 0a 6c 69 73 74 65  the errors.liste
83e0: 64 20 61 62 6f 76 65 20 62 79 20 65 78 70 6c 69  d above by expli
83f0: 63 69 74 6c 79 20 69 73 73 75 69 6e 67 20 61 20  citly issuing a 
8400: 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d 61 6e 64  ROLLBACK command
8410: 2e 20 20 5e 49 66 20 74 68 65 20 0a 74 72 61 6e  .  ^If the .tran
8420: 73 61 63 74 69 6f 6e 20 68 61 73 20 61 6c 72 65  saction has alre
8430: 61 64 79 20 62 65 65 6e 20 72 6f 6c 6c 65 64 20  ady been rolled 
8440: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
8450: 6c 79 0a 62 79 20 74 68 65 20 65 72 72 6f 72 20  ly.by the error 
8460: 72 65 73 70 6f 6e 73 65 2c 20 74 68 65 6e 20 74  response, then t
8470: 68 65 20 52 4f 4c 4c 42 41 43 4b 20 63 6f 6d 6d  he ROLLBACK comm
8480: 61 6e 64 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  and will fail wi
8490: 74 68 20 61 6e 0a 65 72 72 6f 72 2c 20 62 75 74  th an.error, but
84a0: 20 6e 6f 20 68 61 72 6d 20 69 73 20 63 61 75 73   no harm is caus
84b0: 65 64 20 62 79 20 74 68 69 73 2e 3c 2f 70 3e 0a  ed by this.</p>.
84c0: 0a 3c 70 3e 46 75 74 75 72 65 20 76 65 72 73 69  .<p>Future versi
84d0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
84e0: 79 20 65 78 74 65 6e 64 20 74 68 65 20 6c 69 73  y extend the lis
84f0: 74 20 6f 66 20 65 72 72 6f 72 73 20 77 68 69 63  t of errors whic
8500: 68 0a 6d 69 67 68 74 20 63 61 75 73 65 20 61 75  h.might cause au
8510: 74 6f 6d 61 74 69 63 20 74 72 61 6e 73 61 63 74  tomatic transact
8520: 69 6f 6e 20 72 6f 6c 6c 62 61 63 6b 2e 20 20 46  ion rollback.  F
8530: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
8540: 66 0a 53 51 4c 69 74 65 20 6d 69 67 68 74 20 63  f.SQLite might c
8550: 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
8560: 72 65 73 70 6f 6e 73 65 2e 20 20 49 6e 20 70 61  response.  In pa
8570: 72 74 69 63 75 6c 61 72 2c 20 77 65 20 6d 61 79  rticular, we may
8580: 0a 63 68 6f 6f 73 65 20 74 6f 20 73 69 6d 70 6c  .choose to simpl
8590: 69 66 79 20 74 68 65 20 69 6e 74 65 72 66 61 63  ify the interfac
85a0: 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
85b0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 62  ions of SQLite b
85c0: 79 0a 63 61 75 73 69 6e 67 20 74 68 65 20 65 72  y.causing the er
85d0: 72 6f 72 73 20 61 62 6f 76 65 20 74 6f 20 66 6f  rors above to fo
85e0: 72 63 65 20 61 6e 20 75 6e 63 6f 6e 64 69 74 69  rce an unconditi
85f0: 6f 6e 61 6c 20 72 6f 6c 6c 62 61 63 6b 2e 3c 2f  onal rollback.</
8600: 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  p>..<tcl>.######
8610: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8620: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8630: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8640: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
8650: 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
8660: 6e 20 7b 53 41 56 45 50 4f 49 4e 54 7d 20 73 61  n {SAVEPOINT} sa
8670: 76 65 70 6f 69 6e 74 20 7b 53 41 56 45 50 4f 49  vepoint {SAVEPOI
8680: 4e 54 20 52 45 4c 45 41 53 45 7d 0a 0a 52 65 63  NT RELEASE}..Rec
8690: 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
86a0: 72 61 6d 20 73 61 76 65 70 6f 69 6e 74 2d 73 74  ram savepoint-st
86b0: 6d 74 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  mt.RecursiveBubb
86c0: 6c 65 44 69 61 67 72 61 6d 20 72 65 6c 65 61 73  leDiagram releas
86d0: 65 2d 73 74 6d 74 0a 52 65 63 75 72 73 69 76 65  e-stmt.Recursive
86e0: 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 6f  BubbleDiagram ro
86f0: 6c 6c 62 61 63 6b 2d 73 74 6d 74 0a 3c 2f 74 63  llback-stmt.</tc
8700: 6c 3e 0a 0a 3c 70 3e 20 5e 53 41 56 45 50 4f 49  l>..<p> ^SAVEPOI
8710: 4e 54 73 20 61 72 65 20 61 20 6d 65 74 68 6f 64  NTs are a method
8720: 20 6f 66 20 63 72 65 61 74 69 6e 67 20 74 72 61   of creating tra
8730: 6e 73 61 63 74 69 6f 6e 73 2c 20 73 69 6d 69 6c  nsactions, simil
8740: 61 72 20 74 6f 0a 5b 42 45 47 49 4e 5d 20 61 6e  ar to.[BEGIN] an
8750: 64 20 5b 43 4f 4d 4d 49 54 5d 2c 20 65 78 63 65  d [COMMIT], exce
8760: 70 74 20 74 68 61 74 20 74 68 65 20 53 41 56 45  pt that the SAVE
8770: 50 4f 49 4e 54 20 61 6e 64 20 52 45 4c 45 41 53  POINT and RELEAS
8780: 45 20 63 6f 6d 6d 61 6e 64 73 0a 61 72 65 20 6e  E commands.are n
8790: 61 6d 65 64 20 61 6e 64 20 6d 61 79 20 62 65 20  amed and may be 
87a0: 6e 65 73 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e  nested.</p>..<p>
87b0: 20 5e 54 68 65 20 53 41 56 45 50 4f 49 4e 54 20   ^The SAVEPOINT 
87c0: 63 6f 6d 6d 61 6e 64 20 73 74 61 72 74 73 20 61  command starts a
87d0: 20 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e   new transaction
87e0: 20 77 69 74 68 20 61 20 6e 61 6d 65 2e 0a 5e 54   with a name..^T
87f0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6e  he transaction n
8800: 61 6d 65 73 20 6e 65 65 64 20 6e 6f 74 20 62 65  ames need not be
8810: 20 75 6e 69 71 75 65 2e 0a 5e 28 41 20 53 41 56   unique..^(A SAV
8820: 45 50 4f 49 4e 54 20 63 61 6e 20 62 65 20 73 74  EPOINT can be st
8830: 61 72 74 65 64 20 65 69 74 68 65 72 20 77 69 74  arted either wit
8840: 68 69 6e 20 6f 72 20 6f 75 74 73 69 64 65 20 6f  hin or outside o
8850: 66 0a 61 20 5b 42 45 47 49 4e 5d 2e 2e 2e 5b 43  f.a [BEGIN]...[C
8860: 4f 4d 4d 49 54 5d 2e 29 5e 20 20 5e 28 57 68 65  OMMIT].)^  ^(Whe
8870: 6e 20 61 20 53 41 56 45 50 4f 49 4e 54 20 69 73  n a SAVEPOINT is
8880: 20 74 68 65 20 6f 75 74 65 72 2d 6d 6f 73 74 20   the outer-most 
8890: 73 61 76 65 70 6f 69 6e 74 0a 61 6e 64 20 69 74  savepoint.and it
88a0: 20 69 73 20 6e 6f 74 20 77 69 74 68 69 6e 20 61   is not within a
88b0: 20 5b 42 45 47 49 4e 5d 2e 2e 2e 5b 43 4f 4d 4d   [BEGIN]...[COMM
88c0: 49 54 5d 20 74 68 65 6e 20 74 68 65 20 62 65 68  IT] then the beh
88d0: 61 76 69 6f 72 20 69 73 20 74 68 65 0a 73 61 6d  avior is the.sam
88e0: 65 20 61 73 20 42 45 47 49 4e 20 44 45 46 45 52  e as BEGIN DEFER
88f0: 52 45 44 20 54 52 41 4e 53 41 43 54 49 4f 4e 2e  RED TRANSACTION.
8900: 29 5e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  )^</p>..<p>^The 
8910: 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d  ROLLBACK TO comm
8920: 61 6e 64 20 72 65 76 65 72 74 73 20 74 68 65 20  and reverts the 
8930: 73 74 61 74 65 20 6f 66 20 74 68 65 20 64 61 74  state of the dat
8940: 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 77 68  abase back to wh
8950: 61 74 0a 69 74 20 77 61 73 20 6a 75 73 74 20 61  at.it was just a
8960: 66 74 65 72 20 74 68 65 20 63 6f 72 72 65 73 70  fter the corresp
8970: 6f 6e 64 69 6e 67 20 53 41 56 45 50 4f 49 4e 54  onding SAVEPOINT
8980: 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 75 6e  .  ^Note that un
8990: 6c 69 6b 65 20 74 68 61 74 0a 70 6c 61 69 6e 20  like that.plain 
89a0: 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f 6d 6d 61  [ROLLBACK] comma
89b0: 6e 64 20 28 77 69 74 68 6f 75 74 20 74 68 65 20  nd (without the 
89c0: 54 4f 20 6b 65 79 77 6f 72 64 29 20 74 68 65 20  TO keyword) the 
89d0: 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d  ROLLBACK TO comm
89e0: 61 6e 64 0a 64 6f 65 73 20 6e 6f 74 20 63 61 6e  and.does not can
89f0: 63 65 6c 20 74 68 65 20 74 72 61 6e 73 61 63 74  cel the transact
8a00: 69 6f 6e 2e 20 20 5e 49 6e 73 74 65 61 64 20 6f  ion.  ^Instead o
8a10: 66 20 63 61 6e 63 65 6c 6c 69 6e 67 20 74 68 65  f cancelling the
8a20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 0a 74 68   transaction,.th
8a30: 65 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f  e ROLLBACK TO co
8a40: 6d 6d 61 6e 64 20 72 65 73 74 61 72 74 73 20 74  mmand restarts t
8a50: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
8a60: 67 61 69 6e 20 61 74 20 74 68 65 20 62 65 67 69  gain at the begi
8a70: 6e 6e 69 6e 67 2e 0a 5e 41 6c 6c 20 69 6e 74 65  nning..^All inte
8a80: 72 76 65 6e 69 6e 67 20 53 41 56 45 50 4f 49 4e  rvening SAVEPOIN
8a90: 54 73 20 61 72 65 20 63 61 6e 63 65 6c 65 64 2c  Ts are canceled,
8aa0: 20 68 6f 77 65 76 65 72 2e 3c 2f 70 3e 0a 0a 3c   however.</p>..<
8ab0: 70 3e 5e 54 68 65 20 52 45 4c 45 41 53 45 20 63  p>^The RELEASE c
8ac0: 6f 6d 6d 61 6e 64 20 69 73 20 6c 69 6b 65 20 61  ommand is like a
8ad0: 20 5b 43 4f 4d 4d 49 54 5d 20 66 6f 72 20 61 20   [COMMIT] for a 
8ae0: 53 41 56 45 50 4f 49 4e 54 2e 0a 5e 54 68 65 20  SAVEPOINT..^The 
8af0: 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20  RELEASE command 
8b00: 63 61 75 73 65 73 20 61 6c 6c 20 73 61 76 65 70  causes all savep
8b10: 6f 69 6e 74 73 20 62 61 63 6b 20 74 6f 20 61 6e  oints back to an
8b20: 64 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  d including the 
8b30: 0a 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 61 76  .most recent sav
8b40: 65 70 6f 69 6e 74 20 77 69 74 68 20 61 20 6d 61  epoint with a ma
8b50: 74 63 68 69 6e 67 20 6e 61 6d 65 20 74 6f 20 62  tching name to b
8b60: 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74  e removed from t
8b70: 68 65 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20  he .transaction 
8b80: 73 74 61 63 6b 2e 20 20 5e 54 68 65 20 52 45 4c  stack.  ^The REL
8b90: 45 41 53 45 20 6f 66 20 61 6e 20 69 6e 6e 65 72  EASE of an inner
8ba0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 64 6f 65   transaction.doe
8bb0: 73 20 6e 6f 74 20 63 61 75 73 65 20 61 6e 79 20  s not cause any 
8bc0: 63 68 61 6e 67 65 73 20 74 6f 20 62 65 20 77 72  changes to be wr
8bd0: 69 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74  itten to the dat
8be0: 61 62 61 73 65 20 66 69 6c 65 3b 20 69 74 20 6d  abase file; it m
8bf0: 65 72 65 6c 79 0a 72 65 6d 6f 76 65 73 20 73 61  erely.removes sa
8c00: 76 65 70 6f 69 6e 74 73 20 66 72 6f 6d 20 74 68  vepoints from th
8c10: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 74  e transaction st
8c20: 61 63 6b 20 73 75 63 68 20 74 68 61 74 20 69 74  ack such that it
8c30: 20 69 73 0a 6e 6f 20 6c 6f 6e 67 65 72 20 70 6f   is.no longer po
8c40: 73 73 69 62 6c 65 20 74 6f 20 52 4f 4c 4c 42 41  ssible to ROLLBA
8c50: 43 4b 20 54 4f 20 74 68 6f 73 65 20 73 61 76 65  CK TO those save
8c60: 70 6f 69 6e 74 73 2e 0a 5e 49 66 20 61 20 52 45  points..^If a RE
8c70: 4c 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 72 65  LEASE command re
8c80: 6c 65 61 73 65 73 20 74 68 65 20 6f 75 74 65 72  leases the outer
8c90: 6d 6f 73 74 20 73 61 76 65 70 6f 69 6e 74 2c 20  most savepoint, 
8ca0: 73 6f 0a 74 68 61 74 20 74 68 65 20 74 72 61 6e  so.that the tran
8cb0: 73 61 63 74 69 6f 6e 20 73 74 61 63 6b 20 62 65  saction stack be
8cc0: 63 6f 6d 65 73 20 65 6d 70 74 79 2c 20 74 68 65  comes empty, the
8cd0: 6e 20 52 45 4c 45 41 53 45 20 69 73 20 74 68 65  n RELEASE is the
8ce0: 20 73 61 6d 65 0a 61 73 20 5b 43 4f 4d 4d 49 54   same.as [COMMIT
8cf0: 5d 2e 0a 5e 54 68 65 20 5b 43 4f 4d 4d 49 54 5d  ]..^The [COMMIT]
8d00: 20 63 6f 6d 6d 61 6e 64 20 6d 61 79 20 62 65 20   command may be 
8d10: 75 73 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  used to release 
8d20: 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 61  all savepoints a
8d30: 6e 64 0a 63 6f 6d 6d 69 74 20 74 68 65 20 74 72  nd.commit the tr
8d40: 61 6e 73 61 63 74 69 6f 6e 20 65 76 65 6e 20 69  ansaction even i
8d50: 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
8d60: 6e 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79  n was originally
8d70: 20 73 74 61 72 74 65 64 0a 62 79 20 61 20 53 41   started.by a SA
8d80: 56 45 50 4f 49 4e 54 20 63 6f 6d 6d 61 6e 64 20  VEPOINT command 
8d90: 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 42 45  instead of a [BE
8da0: 47 49 4e 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70  GIN] command.</p
8db0: 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 73 61  >..<p>^If the sa
8dc0: 76 65 70 6f 69 6e 74 2d 6e 61 6d 65 20 69 6e 20  vepoint-name in 
8dd0: 61 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e  a RELEASE comman
8de0: 64 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  d does not match
8df0: 20 61 6e 79 0a 73 61 76 65 70 6f 69 6e 74 20 63   any.savepoint c
8e00: 75 72 72 65 6e 74 6c 79 20 69 6e 20 74 68 65 20  urrently in the 
8e10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 63  transaction stac
8e20: 6b 2c 20 74 68 65 6e 20 6e 6f 20 73 61 76 65 70  k, then no savep
8e30: 6f 69 6e 74 73 20 61 72 65 0a 72 65 6c 65 61 73  oints are.releas
8e40: 65 64 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  ed, the database
8e50: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2c 20 61   is unchanged, a
8e60: 6e 64 20 74 68 65 20 52 45 4c 45 41 53 45 20 63  nd the RELEASE c
8e70: 6f 6d 6d 61 6e 64 20 72 65 74 75 72 6e 73 0a 61  ommand returns.a
8e80: 6e 20 65 72 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70  n error.</p>..<p
8e90: 3e 5e 4e 6f 74 65 20 74 68 61 74 20 61 6e 20 69  >^Note that an i
8ea0: 6e 6e 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e  nner transaction
8eb0: 20 6d 69 67 68 74 20 63 6f 6d 6d 69 74 20 28 75   might commit (u
8ec0: 73 69 6e 67 20 74 68 65 20 52 45 4c 45 41 53 45  sing the RELEASE
8ed0: 20 63 6f 6d 6d 61 6e 64 29 0a 62 75 74 20 74 68   command).but th
8ee0: 65 6e 20 6c 61 74 65 72 20 68 61 76 65 20 69 74  en later have it
8ef0: 73 20 77 6f 72 6b 20 75 6e 64 6f 6e 65 20 62 79  s work undone by
8f00: 20 61 20 52 4f 4c 4c 42 41 43 4b 20 69 6e 20 61   a ROLLBACK in a
8f10: 6e 20 6f 75 74 65 72 20 74 72 61 6e 73 61 63 74  n outer transact
8f20: 69 6f 6e 2e 0a 5e 41 20 70 6f 77 65 72 20 66 61  ion..^A power fa
8f30: 69 6c 75 72 65 20 6f 72 20 70 72 6f 67 72 61 6d  ilure or program
8f40: 20 63 72 61 73 68 20 6f 72 20 4f 53 20 63 72 61   crash or OS cra
8f50: 73 68 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68  sh will cause th
8f60: 65 20 6f 75 74 65 72 2d 6d 6f 73 74 0a 74 72 61  e outer-most.tra
8f70: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72 6f 6c 6c  nsaction to roll
8f80: 62 61 63 6b 2c 20 75 6e 64 6f 69 6e 67 20 61 6c  back, undoing al
8f90: 6c 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 68  l changes that h
8fa0: 61 76 65 20 6f 63 63 75 72 72 65 64 20 77 69 74  ave occurred wit
8fb0: 68 69 6e 0a 74 68 61 74 20 6f 75 74 65 72 20 74  hin.that outer t
8fc0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 65 76 65 6e  ransaction, even
8fd0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 68 61   changes that ha
8fe0: 76 65 20 73 75 70 70 6f 73 65 64 6c 79 20 62 65  ve supposedly be
8ff0: 65 6e 20 22 63 6f 6d 6d 69 74 74 65 64 22 0a 62  en "committed".b
9000: 79 20 74 68 65 20 52 45 4c 45 41 53 45 20 63 6f  y the RELEASE co
9010: 6d 6d 61 6e 64 2e 20 20 5e 43 6f 6e 74 65 6e 74  mmand.  ^Content
9020: 20 69 73 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   is not actually
9030: 20 63 6f 6d 6d 69 74 74 65 64 20 6f 6e 20 74 68   committed on th
9040: 65 20 64 69 73 6b 20 0a 75 6e 74 69 6c 20 74 68  e disk .until th
9050: 65 20 6f 75 74 65 72 6d 6f 73 74 20 74 72 61 6e  e outermost tran
9060: 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e  saction commits.
9070: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  </p>..<p>There a
9080: 72 65 20 73 65 76 65 72 61 6c 20 77 61 79 73 20  re several ways 
9090: 6f 66 20 74 68 69 6e 6b 69 6e 67 20 61 62 6f 75  of thinking abou
90a0: 74 20 74 68 65 20 52 45 4c 45 41 53 45 20 63 6f  t the RELEASE co
90b0: 6d 6d 61 6e 64 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e  mmand:</p>..<ul>
90c0: 0a 3c 6c 69 3e 3c 70 3e 0a 53 6f 6d 65 20 70 65  .<li><p>.Some pe
90d0: 6f 70 6c 65 20 76 69 65 77 20 52 45 4c 45 41 53  ople view RELEAS
90e0: 45 20 61 73 20 74 68 65 20 65 71 75 69 76 61 6c  E as the equival
90f0: 65 6e 74 20 6f 66 20 43 4f 4d 4d 49 54 20 66 6f  ent of COMMIT fo
9100: 72 20 61 20 53 41 56 45 50 4f 49 4e 54 2e 0a 54  r a SAVEPOINT..T
9110: 68 69 73 20 69 73 20 61 6e 20 61 63 63 65 70 74  his is an accept
9120: 61 62 6c 65 20 70 6f 69 6e 74 20 6f 66 20 76 69  able point of vi
9130: 65 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 6f 6e  ew as long as on
9140: 65 20 72 65 6d 65 6d 62 65 72 73 20 74 68 61 74  e remembers that
9150: 20 74 68 65 0a 63 68 61 6e 67 65 73 20 63 6f 6d   the.changes com
9160: 6d 69 74 74 65 64 20 62 79 20 61 6e 20 69 6e 6e  mitted by an inn
9170: 65 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  er transaction m
9180: 69 67 68 74 20 6c 61 74 65 72 20 62 65 20 75 6e  ight later be un
9190: 64 6f 6e 65 20 62 79 20 61 0a 72 6f 6c 6c 62 61  done by a.rollba
91a0: 63 6b 20 69 6e 20 61 6e 20 6f 75 74 65 72 20 74  ck in an outer t
91b0: 72 61 6e 73 61 63 74 69 6f 6e 2e 3c 2f 70 3e 3c  ransaction.</p><
91c0: 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 41 6e  /li>..<li><p>.An
91d0: 6f 74 68 65 72 20 76 69 65 77 20 6f 66 20 52 45  other view of RE
91e0: 4c 45 41 53 45 20 69 73 20 74 68 61 74 20 69 74  LEASE is that it
91f0: 20 6d 65 72 67 65 73 20 61 20 6e 61 6d 65 64 20   merges a named 
9200: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 6e 74 6f  transaction into
9210: 20 69 74 73 0a 70 61 72 65 6e 74 20 74 72 61 6e   its.parent tran
9220: 73 61 63 74 69 6f 6e 2c 20 73 6f 20 74 68 61 74  saction, so that
9230: 20 74 68 65 20 6e 61 6d 65 64 20 74 72 61 6e 73   the named trans
9240: 61 63 74 69 6f 6e 20 61 6e 64 20 69 74 73 20 70  action and its p
9250: 61 72 65 6e 74 20 62 65 63 6f 6d 65 0a 74 68 65  arent become.the
9260: 20 73 61 6d 65 20 74 72 61 6e 73 61 63 74 69 6f   same transactio
9270: 6e 2e 20 20 41 66 74 65 72 20 52 45 4c 45 41 53  n.  After RELEAS
9280: 45 2c 20 74 68 65 20 6e 61 6d 65 64 20 74 72 61  E, the named tra
9290: 6e 73 61 63 74 69 6f 6e 20 61 6e 64 20 69 74 73  nsaction and its
92a0: 20 70 61 72 65 6e 74 0a 77 69 6c 6c 20 63 6f 6d   parent.will com
92b0: 6d 69 74 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  mit or rollback 
92c0: 74 6f 67 65 74 68 65 72 2c 20 77 68 61 74 65 76  together, whatev
92d0: 65 72 20 74 68 65 69 72 20 66 61 74 65 20 6d 61  er their fate ma
92e0: 79 20 62 65 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a  y be..</p></li>.
92f0: 0a 3c 6c 69 3e 3c 70 3e 0a 4f 6e 65 20 63 61 6e  .<li><p>.One can
9300: 20 61 6c 73 6f 20 74 68 69 6e 6b 20 6f 66 20 73   also think of s
9310: 61 76 65 70 6f 69 6e 74 73 20 61 73 0a 22 6d 61  avepoints as."ma
9320: 72 6b 73 22 20 69 6e 20 74 68 65 20 74 72 61 6e  rks" in the tran
9330: 73 61 63 74 69 6f 6e 20 74 69 6d 65 6c 69 6e 65  saction timeline
9340: 2e 20 20 49 6e 20 74 68 69 73 20 76 69 65 77 2c  .  In this view,
9350: 20 74 68 65 20 53 41 56 45 50 4f 49 4e 54 20 63   the SAVEPOINT c
9360: 6f 6d 6d 61 6e 64 0a 63 72 65 61 74 65 73 20 61  ommand.creates a
9370: 20 6e 65 77 20 6d 61 72 6b 2c 20 74 68 65 20 52   new mark, the R
9380: 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d 6d 61  OLLBACK TO comma
9390: 6e 64 20 72 65 77 69 6e 64 73 20 74 68 65 20 74  nd rewinds the t
93a0: 69 6d 65 6c 69 6e 65 20 62 61 63 6b 0a 74 6f 20  imeline back.to 
93b0: 61 20 70 6f 69 6e 74 20 6a 75 73 74 20 61 66 74  a point just aft
93c0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 6d 61 72  er the named mar
93d0: 6b 2c 20 61 6e 64 20 74 68 65 20 52 45 4c 45 41  k, and the RELEA
93e0: 53 45 20 63 6f 6d 6d 61 6e 64 0a 65 72 61 73 65  SE command.erase
93f0: 73 20 6d 61 72 6b 73 20 66 72 6f 6d 20 74 68 65  s marks from the
9400: 20 74 69 6d 65 6c 69 6e 65 20 77 69 74 68 6f 75   timeline withou
9410: 74 20 61 63 74 75 61 6c 6c 79 20 6d 61 6b 69 6e  t actually makin
9420: 67 20 61 6e 79 0a 63 68 61 6e 67 65 73 20 74 6f  g any.changes to
9430: 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 3c   the database..<
9440: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a  /p></li>.</ul>..
9450: 0a 0a 3c 68 33 3e 54 72 61 6e 73 61 63 74 69 6f  ..<h3>Transactio
9460: 6e 20 4e 65 73 74 69 6e 67 20 52 75 6c 65 73 3c  n Nesting Rules<
9470: 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65 20 6c 61  /h3>..<p>^The la
9480: 73 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  st transaction s
9490: 74 61 72 74 65 64 20 77 69 6c 6c 20 62 65 20 74  tarted will be t
94a0: 68 65 20 66 69 72 73 74 0a 74 72 61 6e 73 61 63  he first.transac
94b0: 74 69 6f 6e 20 63 6f 6d 6d 69 74 74 65 64 20 6f  tion committed o
94c0: 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 3c 2f  r rolled back.</
94d0: 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b 42 45 47  p>..<p>^The [BEG
94e0: 49 4e 5d 20 63 6f 6d 6d 61 6e 64 20 6f 6e 6c 79  IN] command only
94f0: 20 77 6f 72 6b 73 20 69 66 20 74 68 65 20 74 72   works if the tr
9500: 61 6e 73 61 63 74 69 6f 6e 20 73 74 61 63 6b 20  ansaction stack 
9510: 69 73 20 65 6d 70 74 79 2c 20 6f 72 0a 69 6e 20  is empty, or.in 
9520: 6f 74 68 65 72 20 77 6f 72 64 73 20 69 66 20 74  other words if t
9530: 68 65 72 65 20 61 72 65 20 6e 6f 20 70 65 6e 64  here are no pend
9540: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  ing transactions
9550: 2e 20 20 5e 49 66 20 74 68 65 20 74 72 61 6e 73  .  ^If the trans
9560: 61 63 74 69 6f 6e 0a 73 74 61 63 6b 20 69 73 20  action.stack is 
9570: 6e 6f 74 20 65 6d 70 74 79 20 77 68 65 6e 20 74  not empty when t
9580: 68 65 20 5b 42 45 47 49 4e 5d 20 63 6f 6d 6d 61  he [BEGIN] comma
9590: 6e 64 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  nd is invoked, t
95a0: 68 65 6e 20 74 68 65 20 63 6f 6d 6d 61 6e 64 0a  hen the command.
95b0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
95c0: 72 6f 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68  ror.</p>..<p>^Th
95d0: 65 20 5b 43 4f 4d 4d 49 54 5d 20 63 6f 6d 6d 61  e [COMMIT] comma
95e0: 6e 64 20 63 6f 6d 6d 69 74 73 20 61 6c 6c 20 6f  nd commits all o
95f0: 75 74 73 74 61 6e 64 69 6e 67 20 74 72 61 6e 73  utstanding trans
9600: 61 63 74 69 6f 6e 73 20 61 6e 64 20 6c 65 61 76  actions and leav
9610: 65 73 0a 74 68 65 20 74 72 61 6e 73 61 63 74 69  es.the transacti
9620: 6f 6e 20 73 74 61 63 6b 20 65 6d 70 74 79 2e 3c  on stack empty.<
9630: 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 52 45 4c  /p>..<p>^The REL
9640: 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 73 74 61  EASE command sta
9650: 72 74 73 20 77 69 74 68 20 74 68 65 20 6d 6f 73  rts with the mos
9660: 74 20 72 65 63 65 6e 74 20 61 64 64 69 74 69 6f  t recent additio
9670: 6e 20 74 6f 20 74 68 65 0a 74 72 61 6e 73 61 63  n to the.transac
9680: 74 69 6f 6e 20 73 74 61 63 6b 20 61 6e 64 20 72  tion stack and r
9690: 65 6c 65 61 73 65 73 20 73 61 76 65 70 6f 69 6e  eleases savepoin
96a0: 74 73 20 62 61 63 6b 77 61 72 64 73 20 0a 69 6e  ts backwards .in
96b0: 20 74 69 6d 65 20 75 6e 74 69 6c 20 69 74 20 72   time until it r
96c0: 65 6c 65 61 73 65 73 20 61 20 73 61 76 65 70 6f  eleases a savepo
96d0: 69 6e 74 20 77 69 74 68 20 61 20 6d 61 74 63 68  int with a match
96e0: 69 6e 67 20 73 61 76 65 70 6f 69 6e 74 2d 6e 61  ing savepoint-na
96f0: 6d 65 2e 0a 5e 50 72 69 6f 72 20 73 61 76 65 70  me..^Prior savep
9700: 6f 69 6e 74 73 2c 20 65 76 65 6e 20 73 61 76 65  oints, even save
9710: 70 6f 69 6e 74 73 20 77 69 74 68 20 6d 61 74 63  points with matc
9720: 68 69 6e 67 20 73 61 76 65 70 6f 69 6e 74 2d 6e  hing savepoint-n
9730: 61 6d 65 73 2c 20 61 72 65 0a 75 6e 63 68 61 6e  ames, are.unchan
9740: 67 65 64 2e 0a 5e 49 66 20 74 68 65 20 52 45 4c  ged..^If the REL
9750: 45 41 53 45 20 63 6f 6d 6d 61 6e 64 20 63 61 75  EASE command cau
9760: 73 65 73 20 74 68 65 0a 74 72 61 6e 73 61 63 74  ses the.transact
9770: 69 6f 6e 20 73 74 61 63 6b 20 74 6f 20 62 65 63  ion stack to bec
9780: 6f 6d 65 20 65 6d 70 74 79 20 28 69 66 20 74 68  ome empty (if th
9790: 65 20 52 45 4c 45 41 53 45 20 63 6f 6d 6d 61 6e  e RELEASE comman
97a0: 64 20 72 65 6c 65 61 73 65 73 20 74 68 65 0a 6f  d releases the.o
97b0: 75 74 65 72 6d 6f 73 74 20 74 72 61 6e 73 61 63  utermost transac
97c0: 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 73 74  tion from the st
97d0: 61 63 6b 29 20 74 68 65 6e 20 74 68 65 20 74 72  ack) then the tr
97e0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
97f0: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  s.</p>..<p>^The 
9800: 5b 52 4f 4c 4c 42 41 43 4b 5d 20 63 6f 6d 6d 61  [ROLLBACK] comma
9810: 6e 64 20 77 69 74 68 6f 75 74 20 61 20 54 4f 20  nd without a TO 
9820: 63 6c 61 75 73 65 20 72 6f 6c 6c 73 20 62 61 63  clause rolls bac
9830: 6b 73 20 61 6c 6c 20 74 72 61 6e 73 61 63 74 69  ks all transacti
9840: 6f 6e 73 0a 61 6e 64 20 6c 65 61 76 65 73 20 74  ons.and leaves t
9850: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73  he transaction s
9860: 74 61 63 6b 20 65 6d 70 74 79 2e 3c 2f 70 3e 0a  tack empty.</p>.
9870: 0a 3c 70 3e 5e 54 68 65 20 52 4f 4c 4c 42 41 43  .<p>^The ROLLBAC
9880: 4b 20 63 6f 6d 6d 61 6e 64 20 77 69 74 68 20 61  K command with a
9890: 20 54 4f 20 63 6c 61 75 73 65 20 72 6f 6c 6c 73   TO clause rolls
98a0: 20 62 61 63 6b 20 74 72 61 6e 73 61 63 74 69 6f   back transactio
98b0: 6e 73 20 67 6f 69 6e 67 0a 62 61 63 6b 77 61 72  ns going.backwar
98c0: 64 73 20 69 6e 20 74 69 6d 65 20 62 61 63 6b 20  ds in time back 
98d0: 74 6f 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  to the most rece
98e0: 6e 74 20 53 41 56 45 50 4f 49 4e 54 20 77 69 74  nt SAVEPOINT wit
98f0: 68 20 61 20 6d 61 74 63 68 69 6e 67 20 6e 61 6d  h a matching nam
9900: 65 2e 0a 5e 54 68 65 20 53 41 56 45 50 4f 49 4e  e..^The SAVEPOIN
9910: 54 20 77 69 74 68 20 74 68 65 20 6d 61 74 63 68  T with the match
9920: 69 6e 67 20 6e 61 6d 65 20 72 65 6d 61 69 6e 73  ing name remains
9930: 20 6f 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   on the transact
9940: 69 6f 6e 20 73 74 61 63 6b 2c 0a 62 75 74 20 61  ion stack,.but a
9950: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ll database chan
9960: 67 65 73 20 74 68 61 74 20 6f 63 63 75 72 72 65  ges that occurre
9970: 64 20 61 66 74 65 72 20 74 68 61 74 20 53 41 56  d after that SAV
9980: 45 50 4f 49 4e 54 20 77 61 73 20 63 72 65 61 74  EPOINT was creat
9990: 65 64 0a 61 72 65 20 72 6f 6c 6c 65 64 20 62 61  ed.are rolled ba
99a0: 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 73 61 76  ck.  ^If the sav
99b0: 65 70 6f 69 6e 74 2d 6e 61 6d 65 20 69 6e 20 61  epoint-name in a
99c0: 20 52 4f 4c 4c 42 41 43 4b 20 54 4f 20 63 6f 6d   ROLLBACK TO com
99d0: 6d 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 6d 61  mand does not.ma
99e0: 74 63 68 20 61 6e 79 20 53 41 56 45 50 4f 49 4e  tch any SAVEPOIN
99f0: 54 20 6f 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  T on the stack, 
9a00: 74 68 65 6e 20 74 68 65 20 52 4f 4c 4c 42 41 43  then the ROLLBAC
9a10: 4b 20 63 6f 6d 6d 61 6e 64 20 66 61 69 6c 73 20  K command fails 
9a20: 77 69 74 68 20 61 6e 0a 65 72 72 6f 72 20 61 6e  with an.error an
9a30: 64 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61  d leaves the sta
9a40: 74 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  te of the databa
9a50: 73 65 20 75 6e 63 68 61 6e 67 65 64 2e 3c 2f 70  se unchanged.</p
9a60: 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23  >..<tcl>.#######
9a70: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9a80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9a90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9aa0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9ab0: 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
9ac0: 20 63 6f 6d 6d 65 6e 74 20 63 6f 6d 6d 65 6e 74   comment comment
9ad0: 20 7b 63 6f 6d 6d 65 6e 74 20 2a 63 6f 6d 6d 65   {comment *comme
9ae0: 6e 74 73 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  nts}..RecursiveB
9af0: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 6f 6d  ubbleDiagram com
9b00: 6d 65 6e 74 2d 73 79 6e 74 61 78 0a 3c 2f 74 63  ment-syntax.</tc
9b10: 6c 3e 0a 0a 3c 70 3e 5e 43 6f 6d 6d 65 6e 74 73  l>..<p>^Comments
9b20: 20 61 72 65 20 6e 6f 74 20 53 51 4c 20 63 6f 6d   are not SQL com
9b30: 6d 61 6e 64 73 2c 20 62 75 74 20 63 61 6e 20 6f  mands, but can o
9b40: 63 63 75 72 20 77 69 74 68 69 6e 20 74 68 65 20  ccur within the 
9b50: 74 65 78 74 20 6f 66 0a 53 51 4c 20 71 75 65 72  text of.SQL quer
9b60: 69 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  ies passed to [s
9b70: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
9b80: 32 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64  2()] and related
9b90: 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 5e 43 6f   interfaces..^Co
9ba0: 6d 6d 65 6e 74 73 20 61 72 65 20 74 72 65 61 74  mments are treat
9bb0: 65 64 20 61 73 20 77 68 69 74 65 73 70 61 63 65  ed as whitespace
9bc0: 20 62 79 20 74 68 65 20 70 61 72 73 65 72 2e 0a   by the parser..
9bd0: 5e 43 6f 6d 6d 65 6e 74 73 20 63 61 6e 20 62 65  ^Comments can be
9be0: 67 69 6e 20 61 6e 79 77 68 65 72 65 20 77 68 69  gin anywhere whi
9bf0: 74 65 73 70 61 63 65 20 0a 63 61 6e 20 62 65 20  tespace .can be 
9c00: 66 6f 75 6e 64 2c 20 69 6e 63 6c 75 64 69 6e 67  found, including
9c10: 20 69 6e 73 69 64 65 20 65 78 70 72 65 73 73 69   inside expressi
9c20: 6f 6e 73 20 74 68 61 74 20 73 70 61 6e 20 6d 75  ons that span mu
9c30: 6c 74 69 70 6c 65 20 6c 69 6e 65 73 2e 0a 3c 2f  ltiple lines..</
9c40: 70 3e 0a 0a 3c 70 3e 5e 53 51 4c 20 63 6f 6d 6d  p>..<p>^SQL comm
9c50: 65 6e 74 73 20 62 65 67 69 6e 20 77 69 74 68 20  ents begin with 
9c60: 74 77 6f 20 63 6f 6e 73 65 63 75 74 69 76 65 20  two consecutive 
9c70: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 20 28  "-" characters (
9c80: 41 53 43 49 49 20 30 78 32 64 29 0a 61 6e 64 20  ASCII 0x2d).and 
9c90: 65 78 74 65 6e 64 20 75 70 20 74 6f 20 61 6e 64  extend up to and
9ca0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 6e   including the n
9cb0: 65 78 74 20 6e 65 77 6c 69 6e 65 20 63 68 61 72  ext newline char
9cc0: 61 63 74 65 72 20 28 41 53 43 49 49 20 30 78 30  acter (ASCII 0x0
9cd0: 61 29 0a 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  a).or until the 
9ce0: 65 6e 64 20 6f 66 20 69 6e 70 75 74 2c 20 77 68  end of input, wh
9cf0: 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
9d00: 72 73 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 43 2d  rst.</p>..<p>^C-
9d10: 73 74 79 6c 65 20 63 6f 6d 6d 65 6e 74 73 20 62  style comments b
9d20: 65 67 69 6e 0a 77 69 74 68 20 22 2f 2a 22 20 61  egin.with "/*" a
9d30: 6e 64 20 65 78 74 65 6e 64 20 75 70 20 74 6f 20  nd extend up to 
9d40: 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  and including th
9d50: 65 20 6e 65 78 74 20 22 2a 2f 22 20 63 68 61 72  e next "*/" char
9d60: 61 63 74 65 72 20 70 61 69 72 0a 6f 72 20 75 6e  acter pair.or un
9d70: 74 69 6c 20 74 68 65 20 65 6e 64 20 6f 66 20 69  til the end of i
9d80: 6e 70 75 74 2c 20 77 68 69 63 68 65 76 65 72 20  nput, whichever 
9d90: 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 20 5e 43  comes first.  ^C
9da0: 2d 73 74 79 6c 65 20 63 6f 6d 6d 65 6e 74 73 0a  -style comments.
9db0: 63 61 6e 20 73 70 61 6e 20 6d 75 6c 74 69 70 6c  can span multipl
9dc0: 65 20 6c 69 6e 65 73 2e 20 3c 2f 70 3e 0a 0a 3c  e lines. </p>..<
9dd0: 70 3e 5e 43 6f 6d 6d 65 6e 74 73 20 63 61 6e 20  p>^Comments can 
9de0: 61 70 70 65 61 72 20 61 6e 79 77 68 65 72 65 20  appear anywhere 
9df0: 77 68 69 74 65 73 70 61 63 65 20 63 61 6e 20 6f  whitespace can o
9e00: 63 63 75 72 2c 0a 69 6e 63 6c 75 64 69 6e 67 20  ccur,.including 
9e10: 69 6e 73 69 64 65 20 65 78 70 72 65 73 73 69 6f  inside expressio
9e20: 6e 73 20 61 6e 64 20 69 6e 20 74 68 65 20 6d 69  ns and in the mi
9e30: 64 64 6c 65 20 6f 66 20 6f 74 68 65 72 20 53 51  ddle of other SQ
9e40: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 5e 43  L statements..^C
9e50: 6f 6d 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 6e  omments do not n
9e60: 65 73 74 2e 0a 3c 2f 70 3e 0a 0a 0a 3c 74 63 6c  est..</p>...<tcl
9e70: 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
9e80: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9e90: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9ea0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9eb0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
9ec0: 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45 41 54 45  .Section {CREATE
9ed0: 20 49 4e 44 45 58 7d 20 63 72 65 61 74 65 69 6e   INDEX} createin
9ee0: 64 65 78 20 7b 7b 43 52 45 41 54 45 20 49 4e 44  dex {{CREATE IND
9ef0: 45 58 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  EX}}..RecursiveB
9f00: 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63 72 65  ubbleDiagram cre
9f10: 61 74 65 2d 69 6e 64 65 78 2d 73 74 6d 74 0a 3c  ate-index-stmt.<
9f20: 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 43  /tcl>..<p>^The C
9f30: 52 45 41 54 45 20 49 4e 44 45 58 20 63 6f 6d 6d  REATE INDEX comm
9f40: 61 6e 64 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  and consists of 
9f50: 74 68 65 20 6b 65 79 77 6f 72 64 73 20 22 43 52  the keywords "CR
9f60: 45 41 54 45 20 49 4e 44 45 58 22 20 66 6f 6c 6c  EATE INDEX" foll
9f70: 6f 77 65 64 0a 62 79 20 74 68 65 20 6e 61 6d 65  owed.by the name
9f80: 20 6f 66 20 74 68 65 20 6e 65 77 20 69 6e 64 65   of the new inde
9f90: 78 2c 20 74 68 65 20 6b 65 79 77 6f 72 64 20 22  x, the keyword "
9fa0: 4f 4e 22 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ON", the name of
9fb0: 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 63 72   a previously.cr
9fc0: 65 61 74 65 64 20 74 61 62 6c 65 20 74 68 61 74  eated table that
9fd0: 20 69 73 20 74 6f 20 62 65 20 69 6e 64 65 78 65   is to be indexe
9fe0: 64 2c 20 61 6e 64 20 61 20 70 61 72 65 6e 74 68  d, and a parenth
9ff0: 65 73 69 7a 65 64 20 6c 69 73 74 20 6f 66 20 74  esized list of t
a000: 61 62 6c 65 20 63 6f 6c 75 6d 6e 0a 6e 61 6d 65  able column.name
a010: 73 20 61 6e 64 2f 6f 72 20 65 78 70 72 65 73 73  s and/or express
a020: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
a030: 65 64 20 66 6f 72 20 74 68 65 20 69 6e 64 65 78  ed for the index
a040: 20 6b 65 79 2e 0a 49 66 20 74 68 65 20 6f 70 74   key..If the opt
a050: 69 6f 6e 61 6c 20 57 48 45 52 45 20 63 6c 61 75  ional WHERE clau
a060: 73 65 20 69 73 20 69 6e 63 6c 75 64 65 64 2c 20  se is included, 
a070: 74 68 65 6e 20 74 68 65 20 69 6e 64 65 78 20 69  then the index i
a080: 73 20 61 20 22 5b 70 61 72 74 69 61 6c 20 69 6e  s a "[partial in
a090: 64 65 78 5d 22 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63  dex]"..</p>..<tc
a0a0: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 7b 64  l>hd_fragment {d
a0b0: 65 73 63 69 64 78 7d 20 7b 64 65 73 63 65 6e 64  escidx} {descend
a0c0: 69 6e 67 20 69 6e 64 69 63 65 73 7d 20 7b 64 65  ing indices} {de
a0d0: 73 63 65 6e 64 69 6e 67 20 69 6e 64 65 78 7d 20  scending index} 
a0e0: 5c 0a 20 20 20 20 7b 64 65 73 63 65 6e 64 69 6e  \.    {descendin
a0f0: 67 20 69 6e 64 65 78 65 73 7d 20 7b 44 45 53 43  g indexes} {DESC
a100: 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 45 61 63 68  }</tcl>.<p>^Each
a110: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 6f 72 20   column name or 
a120: 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
a130: 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6f 6e  e followed by on
a140: 65 0a 6f 66 20 74 68 65 20 22 41 53 43 22 20 6f  e.of the "ASC" o
a150: 72 20 22 44 45 53 43 22 20 6b 65 79 77 6f 72 64  r "DESC" keyword
a160: 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 6f  s to indicate so
a170: 72 74 20 6f 72 64 65 72 2e 0a 5e 54 68 65 20 73  rt order..^The s
a180: 6f 72 74 20 6f 72 64 65 72 20 6d 61 79 20 6f 72  ort order may or
a190: 20 6d 61 79 20 6e 6f 74 20 62 65 20 69 67 6e 6f   may not be igno
a1a0: 72 65 64 20 64 65 70 65 6e 64 69 6e 67 0a 6f 6e  red depending.on
a1b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1c0: 6c 65 20 66 6f 72 6d 61 74 2c 20 61 6e 64 20 69  le format, and i
a1d0: 6e 20 70 61 72 74 69 63 75 6c 61 72 20 74 68 65  n particular the
a1e0: 20 5b 73 63 68 65 6d 61 20 66 6f 72 6d 61 74 20   [schema format 
a1f0: 6e 75 6d 62 65 72 5d 2e 0a 5e 54 68 65 20 22 6c  number]..^The "l
a200: 65 67 61 63 79 22 20 73 63 68 65 6d 61 20 66 6f  egacy" schema fo
a210: 72 6d 61 74 20 28 31 29 20 69 67 6e 6f 72 65 73  rmat (1) ignores
a220: 20 69 6e 64 65 78 0a 73 6f 72 74 20 6f 72 64 65   index.sort orde
a230: 72 2e 20 20 5e 54 68 65 20 64 65 73 63 65 6e 64  r.  ^The descend
a240: 69 6e 67 20 69 6e 64 65 78 20 73 63 68 65 6d 61  ing index schema
a250: 20 66 6f 72 6d 61 74 20 28 34 29 20 74 61 6b 65   format (4) take
a260: 73 20 69 6e 64 65 78 20 73 6f 72 74 20 6f 72 64  s index sort ord
a270: 65 72 0a 69 6e 74 6f 20 61 63 63 6f 75 6e 74 2e  er.into account.
a280: 20 20 4f 6e 6c 79 20 76 65 72 73 69 6f 6e 73 20    Only versions 
a290: 6f 66 20 53 51 4c 69 74 65 20 33 2e 33 2e 30 20  of SQLite 3.3.0 
a2a0: 28 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 30 5d 29  ([dateof:3.3.0])
a2b0: 0a 61 6e 64 20 6c 61 74 65 72 20 61 72 65 20 61  .and later are a
a2c0: 62 6c 65 20 74 6f 20 75 6e 64 65 72 73 74 61 6e  ble to understan
a2d0: 64 0a 74 68 65 20 64 65 73 63 65 6e 64 69 6e 67  d.the descending
a2e0: 20 69 6e 64 65 78 20 66 6f 72 6d 61 74 2e 20 46   index format. F
a2f0: 6f 72 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  or compatibility
a300: 2c 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  , version of SQL
a310: 69 74 65 20 62 65 74 77 65 65 6e 20 33 2e 33 2e  ite between 3.3.
a320: 30 0a 61 6e 64 20 33 2e 37 2e 39 20 75 73 65 20  0.and 3.7.9 use 
a330: 74 68 65 20 6c 65 67 61 63 79 20 73 63 68 65 6d  the legacy schem
a340: 61 20 66 6f 72 6d 61 74 20 62 79 20 64 65 66 61  a format by defa
a350: 75 6c 74 2e 20 20 54 68 65 20 6e 65 77 65 72 20  ult.  The newer 
a360: 73 63 68 65 6d 61 20 66 6f 72 6d 61 74 20 69 73  schema format is
a370: 0a 75 73 65 64 20 62 79 20 64 65 66 61 75 6c 74  .used by default
a380: 20 69 6e 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e   in version 3.7.
a390: 31 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 37 2e  10 ([dateof:3.7.
a3a0: 31 30 5d 29 20 61 6e 64 20 6c 61 74 65 72 2e 0a  10]) and later..
a3b0: 5e 54 68 65 20 5b 6c 65 67 61 63 79 5f 66 69 6c  ^The [legacy_fil
a3c0: 65 5f 66 6f 72 6d 61 74 20 70 72 61 67 6d 61 5d  e_format pragma]
a3d0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a3e0: 63 68 61 6e 67 65 20 73 65 74 20 74 68 65 20 73  change set the s
a3f0: 70 65 63 69 66 69 63 0a 62 65 68 61 76 69 6f 72  pecific.behavior
a400: 20 66 6f 72 20 61 6e 79 20 76 65 72 73 69 6f 6e   for any version
a410: 20 6f 66 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a   of SQLite.</p>.
a420: 0a 3c 70 3e 54 68 65 20 4e 55 4c 4c 53 20 46 49  .<p>The NULLS FI
a430: 52 53 54 20 61 6e 64 20 4e 55 4c 4c 53 20 4c 41  RST and NULLS LA
a440: 53 54 20 70 72 65 64 69 63 61 74 65 73 20 61 72  ST predicates ar
a450: 65 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 0a  e not supported.
a460: 66 6f 72 20 69 6e 64 65 78 65 73 2e 20 20 46 6f  for indexes.  Fo
a470: 72 20 5b 73 6f 72 74 20 6f 72 64 65 72 7c 73 6f  r [sort order|so
a480: 72 74 69 6e 67 20 70 75 72 70 6f 73 65 73 5d 2c  rting purposes],
a490: 20 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 72   SQLite consider
a4a0: 73 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 0a 74  s NULL values .t
a4b0: 6f 20 62 65 20 73 6d 61 6c 6c 65 72 20 74 68 61  o be smaller tha
a4c0: 6e 20 61 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75  n all other valu
a4d0: 65 73 2e 20 20 48 65 6e 63 65 73 20 4e 55 4c 4c  es.  Hences NULL
a4e0: 20 76 61 6c 75 65 73 20 61 6c 77 61 79 73 20 61   values always a
a4f0: 70 70 65 61 72 20 61 74 0a 74 68 65 20 62 65 67  ppear at.the beg
a500: 69 6e 6e 69 6e 67 20 6f 66 20 61 6e 20 41 53 43  inning of an ASC
a510: 20 69 6e 64 65 78 20 61 6e 64 20 61 74 20 74 68   index and at th
a520: 65 20 65 6e 64 20 6f 66 20 61 20 44 45 53 43 20  e end of a DESC 
a530: 69 6e 64 65 78 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  index.</p>..<tcl
a540: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f 6c  >hd_fragment col
a550: 6c 69 64 78 20 7b 43 4f 4c 4c 41 54 45 7d 3c 2f  lidx {COLLATE}</
a560: 74 63 6c 3e 0a 3c 70 3e 5e 54 68 65 20 43 4f 4c  tcl>.<p>^The COL
a570: 4c 41 54 45 20 63 6c 61 75 73 65 20 6f 70 74 69  LATE clause opti
a580: 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 69 6e 67  onally following
a590: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6e 61 6d   each column nam
a5a0: 65 0a 6f 72 20 65 78 70 72 65 73 73 69 6f 6e 20  e.or expression 
a5b0: 64 65 66 69 6e 65 73 20 61 0a 63 6f 6c 6c 61 74  defines a.collat
a5c0: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 75 73 65  ing sequence use
a5d0: 64 20 66 6f 72 20 74 65 78 74 20 65 6e 74 72 69  d for text entri
a5e0: 65 73 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  es in that colum
a5f0: 6e 2e 0a 5e 54 68 65 20 64 65 66 61 75 6c 74 20  n..^The default 
a600: 63 6f 6c 6c 61 74 69 6e 67 0a 73 65 71 75 65 6e  collating.sequen
a610: 63 65 20 69 73 20 74 68 65 20 63 6f 6c 6c 61 74  ce is the collat
a620: 69 6e 67 20 73 65 71 75 65 6e 63 65 20 64 65 66  ing sequence def
a630: 69 6e 65 64 20 66 6f 72 20 74 68 61 74 20 63 6f  ined for that co
a640: 6c 75 6d 6e 20 69 6e 20 74 68 65 0a 5b 43 52 45  lumn in the.[CRE
a650: 41 54 45 20 54 41 42 4c 45 5d 20 73 74 61 74 65  ATE TABLE] state
a660: 6d 65 6e 74 2e 20 20 5e 4f 72 20 69 66 20 6e 6f  ment.  ^Or if no
a670: 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
a680: 6e 63 65 20 69 73 20 6f 74 68 65 72 77 69 73 65  nce is otherwise
a690: 20 64 65 66 69 6e 65 64 2c 0a 74 68 65 20 62 75   defined,.the bu
a6a0: 69 6c 74 2d 69 6e 20 42 49 4e 41 52 59 20 63 6f  ilt-in BINARY co
a6b0: 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
a6c0: 20 69 73 20 75 73 65 64 2e 3c 2f 70 3e 0a 0a 3c   is used.</p>..<
a6d0: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
a6e0: 69 6e 64 65 78 65 78 70 72 3c 2f 74 63 6c 3e 0a  indexexpr</tcl>.
a6f0: 3c 70 3e 5e 45 78 70 72 65 73 73 69 6f 6e 73 20  <p>^Expressions 
a700: 69 6e 20 61 6e 20 69 6e 64 65 78 20 6d 61 79 20  in an index may 
a710: 6e 6f 74 20 72 65 66 65 72 65 6e 63 65 20 6f 74  not reference ot
a720: 68 65 72 20 74 61 62 6c 65 73 0a 61 6e 64 20 6d  her tables.and m
a730: 61 79 20 6e 6f 74 20 75 73 65 20 73 75 62 71 75  ay not use subqu
a740: 65 72 69 65 73 20 6e 6f 72 20 66 75 6e 63 74 69  eries nor functi
a750: 6f 6e 73 20 77 68 6f 73 65 20 72 65 73 75 6c 74  ons whose result
a760: 20 6d 69 67 68 74 0a 63 68 61 6e 67 65 20 28 65   might.change (e
a770: 78 3a 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 6f 72  x: [random()] or
a780: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
a790: 28 29 5d 29 2e 0a 5e 45 78 70 72 65 73 73 69 6f  ()])..^Expressio
a7a0: 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 20 6d  ns in an index m
a7b0: 61 79 20 6f 6e 6c 79 20 72 65 66 65 72 20 74 6f  ay only refer to
a7c0: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
a7d0: 74 61 62 6c 65 0a 74 68 61 74 20 69 73 20 62 65  table.that is be
a7e0: 69 6e 67 20 69 6e 64 65 78 65 64 2e 0a 49 6e 64  ing indexed..Ind
a7f0: 65 78 65 73 20 6f 6e 20 65 78 70 72 65 73 73 69  exes on expressi
a800: 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 77 6f 72 6b  on will not work
a810: 20 77 69 74 68 20 76 65 72 73 69 6f 6e 73 20 6f   with versions o
a820: 66 20 53 51 4c 69 74 65 20 70 72 69 6f 72 0a 74  f SQLite prior.t
a830: 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 39 2e 30  o [version 3.9.0
a840: 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 39 2e 30  ] ([dateof:3.9.0
a850: 5d 29 2e 0a 53 65 65 20 74 68 65 20 5b 49 6e 64  ])..See the [Ind
a860: 65 78 65 73 20 4f 6e 20 45 78 70 72 65 73 73 69  exes On Expressi
a870: 6f 6e 73 5d 20 64 6f 63 75 6d 65 6e 74 20 66 6f  ons] document fo
a880: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
a890: 6f 72 6d 61 74 69 6f 6e 0a 61 62 6f 75 74 20 75  ormation.about u
a8a0: 73 69 6e 67 20 67 65 6e 65 72 61 6c 20 65 78 70  sing general exp
a8b0: 72 65 73 73 69 6f 6e 73 20 69 6e 20 43 52 45 41  ressions in CREA
a8c0: 54 45 20 49 4e 44 45 58 20 73 74 61 74 65 6d 65  TE INDEX stateme
a8d0: 6e 74 73 2e 0a 0a 3c 70 3e 54 68 65 72 65 20 61  nts...<p>There a
a8e0: 72 65 20 6e 6f 20 61 72 62 69 74 72 61 72 79 20  re no arbitrary 
a8f0: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 6e 75  limits on the nu
a900: 6d 62 65 72 20 6f 66 20 69 6e 64 69 63 65 73 20  mber of indices 
a910: 74 68 61 74 20 63 61 6e 20 62 65 0a 61 74 74 61  that can be.atta
a920: 63 68 65 64 20 74 6f 20 61 20 73 69 6e 67 6c 65  ched to a single
a930: 20 74 61 62 6c 65 2e 20 20 5e 28 54 68 65 20 6e   table.  ^(The n
a940: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
a950: 20 69 6e 20 61 6e 20 69 6e 64 65 78 20 69 73 20   in an index is 
a960: 0a 6c 69 6d 69 74 65 64 20 74 6f 20 74 68 65 20  .limited to the 
a970: 76 61 6c 75 65 20 73 65 74 20 62 79 0a 5b 73 71  value set by.[sq
a980: 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
a990: 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
a9a0: 4e 5d 2c 2e 2e 2e 29 2e 29 5e 3c 2f 70 3e 0a 0a  N],...).)^</p>..
a9b0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
a9c0: 20 75 6e 69 71 75 65 69 64 78 20 7b 75 6e 69 71   uniqueidx {uniq
a9d0: 75 65 20 69 6e 64 65 78 7d 3c 2f 74 63 6c 3e 0a  ue index}</tcl>.
a9e0: 3c 70 3e 5e 49 66 20 74 68 65 20 55 4e 49 51 55  <p>^If the UNIQU
a9f0: 45 20 6b 65 79 77 6f 72 64 20 61 70 70 65 61 72  E keyword appear
aa00: 73 20 62 65 74 77 65 65 6e 20 43 52 45 41 54 45  s between CREATE
aa10: 20 61 6e 64 20 49 4e 44 45 58 20 74 68 65 6e 20   and INDEX then 
aa20: 64 75 70 6c 69 63 61 74 65 0a 69 6e 64 65 78 20  duplicate.index 
aa30: 65 6e 74 72 69 65 73 20 61 72 65 20 6e 6f 74 20  entries are not 
aa40: 61 6c 6c 6f 77 65 64 2e 20 20 5e 41 6e 79 20 61  allowed.  ^Any a
aa50: 74 74 65 6d 70 74 20 74 6f 20 69 6e 73 65 72 74  ttempt to insert
aa60: 20 61 20 64 75 70 6c 69 63 61 74 65 20 65 6e 74   a duplicate ent
aa70: 72 79 0a 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ry.will result i
aa80: 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 46 6f  n an error.  ^Fo
aa90: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
aaa0: 66 20 75 6e 69 71 75 65 20 69 6e 64 69 63 65 73  f unique indices
aab0: 2c 20 61 6c 6c 20 4e 55 4c 4c 20 76 61 6c 75 65  , all NULL value
aac0: 73 0a 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64  s.are considered
aad0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
aae0: 61 6c 6c 20 6f 74 68 65 72 20 4e 55 4c 4c 20 76  all other NULL v
aaf0: 61 6c 75 65 73 20 61 6e 64 20 61 72 65 20 74 68  alues and are th
ab00: 75 73 20 75 6e 69 71 75 65 2e 0a 54 68 69 73 20  us unique..This 
ab10: 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 74 77  is one of the tw
ab20: 6f 20 70 6f 73 73 69 62 6c 65 20 69 6e 74 65 72  o possible inter
ab30: 70 72 65 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  pretations of th
ab40: 65 20 53 51 4c 2d 39 32 20 73 74 61 6e 64 61 72  e SQL-92 standar
ab50: 64 0a 28 74 68 65 20 6c 61 6e 67 75 61 67 65 20  d.(the language 
ab60: 69 6e 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  in the standard 
ab70: 69 73 20 61 6d 62 69 67 75 6f 75 73 29 20 61 6e  is ambiguous) an
ab80: 64 20 69 73 20 74 68 65 20 69 6e 74 65 72 70 72  d is the interpr
ab90: 65 74 61 74 69 6f 6e 0a 66 6f 6c 6c 6f 77 65 64  etation.followed
aba0: 20 62 79 20 50 6f 73 74 67 72 65 53 51 4c 2c 20   by PostgreSQL, 
abb0: 4d 79 53 51 4c 2c 20 46 69 72 65 62 69 72 64 2c  MySQL, Firebird,
abc0: 20 61 6e 64 20 4f 72 61 63 6c 65 2e 20 20 49 6e   and Oracle.  In
abd0: 66 6f 72 6d 69 78 20 61 6e 64 0a 4d 69 63 72 6f  formix and.Micro
abe0: 73 6f 66 74 20 53 51 4c 20 53 65 72 76 65 72 20  soft SQL Server 
abf0: 66 6f 6c 6c 6f 77 20 74 68 65 20 6f 74 68 65 72  follow the other
ac00: 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
ac10: 6f 66 20 74 68 65 20 73 74 61 6e 64 61 72 64 2e  of the standard.
ac20: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65  </p>..<p>^If the
ac30: 20 6f 70 74 69 6f 6e 61 6c 20 49 46 20 4e 4f 54   optional IF NOT
ac40: 20 45 58 49 53 54 53 20 63 6c 61 75 73 65 20 69   EXISTS clause i
ac50: 73 20 70 72 65 73 65 6e 74 20 61 6e 64 20 61 6e  s present and an
ac60: 6f 74 68 65 72 20 69 6e 64 65 78 0a 77 69 74 68  other index.with
ac70: 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
ac80: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2c 20 74  lready exists, t
ac90: 68 65 6e 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64  hen this command
aca0: 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
acb0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 6e 64 65 78  .</p>..<p>^Index
acc0: 65 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20 77  es are removed w
acd0: 69 74 68 20 74 68 65 20 5b 44 52 4f 50 20 49 4e  ith the [DROP IN
ace0: 44 45 58 5d 20 63 6f 6d 6d 61 6e 64 2e 3c 2f 70  DEX] command.</p
acf0: 3e 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23  >...<tcl>.######
ad00: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad10: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad20: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad30: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
ad40: 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e  ########.Section
ad50: 20 7b 43 52 45 41 54 45 20 54 41 42 4c 45 7d 20   {CREATE TABLE} 
ad60: 7b 63 72 65 61 74 65 74 61 62 6c 65 7d 20 7b 7b  {createtable} {{
ad70: 43 52 45 41 54 45 20 54 41 42 4c 45 7d 7d 0a 0a  CREATE TABLE}}..
ad80: 52 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44  RecursiveBubbleD
ad90: 69 61 67 72 61 6d 20 63 72 65 61 74 65 2d 74 61  iagram create-ta
ada0: 62 6c 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a  ble-stmt.</tcl>.
adb0: 0a 3c 70 3e 54 68 65 20 22 43 52 45 41 54 45 20  .<p>The "CREATE 
adc0: 54 41 42 4c 45 22 20 63 6f 6d 6d 61 6e 64 20 69  TABLE" command i
add0: 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
ade0: 20 61 20 6e 65 77 20 74 61 62 6c 65 20 69 6e 20   a new table in 
adf0: 61 6e 20 53 51 4c 69 74 65 20 0a 64 61 74 61 62  an SQLite .datab
ae00: 61 73 65 2e 20 41 20 43 52 45 41 54 45 20 54 41  ase. A CREATE TA
ae10: 42 4c 45 20 63 6f 6d 6d 61 6e 64 20 73 70 65 63  BLE command spec
ae20: 69 66 69 65 73 20 74 68 65 20 66 6f 6c 6c 6f 77  ifies the follow
ae30: 69 6e 67 20 61 74 74 72 69 62 75 74 65 73 20 6f  ing attributes o
ae40: 66 20 74 68 65 0a 6e 65 77 20 74 61 62 6c 65 3a  f the.new table:
ae50: 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 3c 70 3e  ..<ul>.  <li><p>
ae60: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
ae70: 6e 65 77 20 74 61 62 6c 65 2e 0a 0a 20 20 3c 6c  new table...  <l
ae80: 69 3e 3c 70 3e 20 54 68 65 20 64 61 74 61 62 61  i><p> The databa
ae90: 73 65 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  se in which the 
aea0: 6e 65 77 20 74 61 62 6c 65 20 69 73 20 63 72 65  new table is cre
aeb0: 61 74 65 64 2e 20 54 61 62 6c 65 73 20 6d 61 79  ated. Tables may
aec0: 20 62 65 20 0a 20 20 20 20 20 20 63 72 65 61 74   be .      creat
aed0: 65 64 20 69 6e 20 74 68 65 20 6d 61 69 6e 20 64  ed in the main d
aee0: 61 74 61 62 61 73 65 2c 20 74 68 65 20 74 65 6d  atabase, the tem
aef0: 70 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 69  p database, or i
af00: 6e 20 61 6e 79 20 61 74 74 61 63 68 65 64 0a 20  n any attached. 
af10: 20 20 20 20 20 64 61 74 61 62 61 73 65 2e 0a 0a       database...
af20: 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 6e 61    <li><p> The na
af30: 6d 65 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  me of each colum
af40: 6e 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a  n in the table..
af50: 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 64  .  <li><p> The d
af60: 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
af70: 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  each column in t
af80: 68 65 20 74 61 62 6c 65 2e 0a 0a 20 20 3c 6c 69  he table...  <li
af90: 3e 3c 70 3e 20 41 20 64 65 66 61 75 6c 74 20 76  ><p> A default v
afa0: 61 6c 75 65 20 6f 72 20 65 78 70 72 65 73 73 69  alue or expressi
afb0: 6f 6e 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  on for each colu
afc0: 6d 6e 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  mn in the table.
afd0: 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 41 20 64 65  ..  <li><p> A de
afe0: 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
aff0: 73 65 71 75 65 6e 63 65 20 74 6f 20 75 73 65 20  sequence to use 
b000: 77 69 74 68 20 65 61 63 68 20 63 6f 6c 75 6d 6e  with each column
b010: 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 4f 70 74  ...  <li><p> Opt
b020: 69 6f 6e 61 6c 6c 79 2c 20 61 20 50 52 49 4d 41  ionally, a PRIMA
b030: 52 59 20 4b 45 59 20 66 6f 72 20 74 68 65 20 74  RY KEY for the t
b040: 61 62 6c 65 2e 20 42 6f 74 68 20 73 69 6e 67 6c  able. Both singl
b050: 65 20 63 6f 6c 75 6d 6e 20 61 6e 64 0a 20 20 20  e column and.   
b060: 20 20 20 20 63 6f 6d 70 6f 73 69 74 65 20 28 6d      composite (m
b070: 75 6c 74 69 70 6c 65 20 63 6f 6c 75 6d 6e 29 20  ultiple column) 
b080: 70 72 69 6d 61 72 79 20 6b 65 79 73 20 61 72 65  primary keys are
b090: 20 73 75 70 70 6f 72 74 65 64 2e 0a 0a 20 20 3c   supported...  <
b0a0: 6c 69 3e 3c 70 3e 20 41 20 73 65 74 20 6f 66 20  li><p> A set of 
b0b0: 53 51 4c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  SQL constraints 
b0c0: 66 6f 72 20 65 61 63 68 20 74 61 62 6c 65 2e 20  for each table. 
b0d0: 53 51 4c 69 74 65 20 73 75 70 70 6f 72 74 73 20  SQLite supports 
b0e0: 55 4e 49 51 55 45 2c 20 4e 4f 54 0a 20 20 20 20  UNIQUE, NOT.    
b0f0: 20 20 20 4e 55 4c 4c 2c 20 43 48 45 43 4b 20 61     NULL, CHECK a
b100: 6e 64 20 46 4f 52 45 49 47 4e 20 4b 45 59 20 63  nd FOREIGN KEY c
b110: 6f 6e 73 74 72 61 69 6e 74 73 2e 0a 0a 20 20 3c  onstraints...  <
b120: 6c 69 3e 3c 70 3e 20 57 68 65 74 68 65 72 20 74  li><p> Whether t
b130: 68 65 20 74 61 62 6c 65 20 69 73 20 61 20 5b 57  he table is a [W
b140: 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
b150: 62 6c 65 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 45  ble..</ul>..<p>E
b160: 76 65 72 79 20 43 52 45 41 54 45 20 54 41 42 4c  very CREATE TABL
b170: 45 20 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74  E statement must
b180: 20 73 70 65 63 69 66 79 20 61 20 6e 61 6d 65 20   specify a name 
b190: 66 6f 72 20 74 68 65 20 6e 65 77 20 74 61 62 6c  for the new tabl
b1a0: 65 2e 0a 20 20 5e 28 54 61 62 6c 65 20 6e 61 6d  e..  ^(Table nam
b1b0: 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
b1c0: 74 68 20 22 73 71 6c 69 74 65 5f 22 20 61 72 65  th "sqlite_" are
b1d0: 20 72 65 73 65 72 76 65 64 20 66 6f 72 20 69 6e   reserved for in
b1e0: 74 65 72 6e 61 6c 20 75 73 65 2e 20 49 74 0a 20  ternal use. It. 
b1f0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
b200: 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
b210: 65 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 61  e a table with a
b220: 20 6e 61 6d 65 20 74 68 61 74 20 73 74 61 72 74   name that start
b230: 73 20 77 69 74 68 0a 20 20 22 73 71 6c 69 74 65  s with.  "sqlite
b240: 5f 22 2e 29 5e 0a 0a 3c 70 3e 20 5e 49 66 20 61  _".)^..<p> ^If a
b250: 20 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d   <yyterm>schema-
b260: 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 69 73  name</yyterm> is
b270: 20 73 70 65 63 69 66 69 65 64 2c 20 69 74 20 6d   specified, it m
b280: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 22 6d  ust be either "m
b290: 61 69 6e 22 2c 20 0a 20 20 22 74 65 6d 70 22 2c  ain", .  "temp",
b2a0: 20 6f 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   or the name of 
b2b0: 61 6e 20 5b 41 54 54 41 43 48 20 44 41 54 41 42  an [ATTACH DATAB
b2c0: 41 53 45 7c 61 74 74 61 63 68 65 64 20 64 61 74  ASE|attached dat
b2d0: 61 62 61 73 65 5d 2e 20 5e 49 6e 20 74 68 69 73  abase]. ^In this
b2e0: 20 63 61 73 65 0a 20 20 74 68 65 20 6e 65 77 20   case.  the new 
b2f0: 74 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64  table is created
b300: 20 69 6e 20 74 68 65 20 6e 61 6d 65 64 20 64 61   in the named da
b310: 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
b320: 22 54 45 4d 50 22 20 6f 72 20 22 54 45 4d 50 4f  "TEMP" or "TEMPO
b330: 52 41 52 59 22 0a 20 20 6b 65 79 77 6f 72 64 20  RARY".  keyword 
b340: 6f 63 63 75 72 73 20 62 65 74 77 65 65 6e 20 74  occurs between t
b350: 68 65 20 22 43 52 45 41 54 45 22 20 61 6e 64 20  he "CREATE" and 
b360: 22 54 41 42 4c 45 22 20 74 68 65 6e 20 74 68 65  "TABLE" then the
b370: 20 6e 65 77 20 74 61 62 6c 65 20 69 73 0a 20 20   new table is.  
b380: 63 72 65 61 74 65 64 20 69 6e 20 74 68 65 20 74  created in the t
b390: 65 6d 70 20 64 61 74 61 62 61 73 65 2e 20 5e 49  emp database. ^I
b3a0: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
b3b0: 20 73 70 65 63 69 66 79 20 62 6f 74 68 20 61 20   specify both a 
b3c0: 0a 20 20 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d  .  <yyterm>schem
b3d0: 61 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20  a-name</yyterm> 
b3e0: 61 6e 64 20 74 68 65 20 54 45 4d 50 20 6f 72 20  and the TEMP or 
b3f0: 54 45 4d 50 4f 52 41 52 59 20 6b 65 79 77 6f 72  TEMPORARY keywor
b400: 64 2c 20 75 6e 6c 65 73 73 20 74 68 65 0a 20 20  d, unless the.  
b410: 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d 6e  <yyterm>schema-n
b420: 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 69 73 20  ame</yyterm> is 
b430: 22 74 65 6d 70 22 2e 20 0a 20 20 5e 49 66 20 6e  "temp". .  ^If n
b440: 6f 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 73  o schema name is
b450: 20 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 74   specified and t
b460: 68 65 0a 20 20 54 45 4d 50 20 6b 65 79 77 6f 72  he.  TEMP keywor
b470: 64 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74  d is not present
b480: 20 74 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20   then the table 
b490: 69 73 20 63 72 65 61 74 65 64 20 69 6e 20 74 68  is created in th
b4a0: 65 20 6d 61 69 6e 0a 20 20 64 61 74 61 62 61 73  e main.  databas
b4b0: 65 2e 0a 0a 3c 70 3e 0a 20 20 5e 49 74 20 69 73  e...<p>.  ^It is
b4c0: 20 75 73 75 61 6c 6c 79 20 61 6e 20 65 72 72 6f   usually an erro
b4d0: 72 20 74 6f 20 61 74 74 65 6d 70 74 20 74 6f 20  r to attempt to 
b4e0: 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 61 62  create a new tab
b4f0: 6c 65 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  le in a database
b500: 20 74 68 61 74 0a 20 20 61 6c 72 65 61 64 79 20   that.  already 
b510: 63 6f 6e 74 61 69 6e 73 20 61 20 74 61 62 6c 65  contains a table
b520: 2c 20 69 6e 64 65 78 20 6f 72 20 76 69 65 77 20  , index or view 
b530: 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  of the same name
b540: 2e 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 74  . ^However, if t
b550: 68 65 0a 20 20 22 49 46 20 4e 4f 54 20 45 58 49  he.  "IF NOT EXI
b560: 53 54 53 22 20 63 6c 61 75 73 65 20 69 73 20 73  STS" clause is s
b570: 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
b580: 20 6f 66 20 74 68 65 20 43 52 45 41 54 45 20 54   of the CREATE T
b590: 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 61  ABLE statement a
b5a0: 6e 64 0a 20 20 61 20 74 61 62 6c 65 20 6f 72 20  nd.  a table or 
b5b0: 76 69 65 77 20 6f 66 20 74 68 65 20 73 61 6d 65  view of the same
b5c0: 20 6e 61 6d 65 20 61 6c 72 65 61 64 79 20 65 78   name already ex
b5d0: 69 73 74 73 2c 20 74 68 65 20 43 52 45 41 54 45  ists, the CREATE
b5e0: 20 54 41 42 4c 45 20 63 6f 6d 6d 61 6e 64 0a 20   TABLE command. 
b5f0: 20 73 69 6d 70 6c 79 20 68 61 73 20 6e 6f 20 65   simply has no e
b600: 66 66 65 63 74 20 28 61 6e 64 20 6e 6f 20 65 72  ffect (and no er
b610: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 72  ror message is r
b620: 65 74 75 72 6e 65 64 29 2e 20 5e 41 6e 20 65 72  eturned). ^An er
b630: 72 6f 72 20 69 73 20 73 74 69 6c 6c 0a 20 20 72  ror is still.  r
b640: 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 74  eturned if the t
b650: 61 62 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  able cannot be c
b660: 72 65 61 74 65 64 20 62 65 63 61 75 73 65 20 6f  reated because o
b670: 66 20 61 6e 20 65 78 69 73 74 69 6e 67 20 69 6e  f an existing in
b680: 64 65 78 2c 20 65 76 65 6e 20 0a 20 20 69 66 20  dex, even .  if 
b690: 74 68 65 20 22 49 46 20 4e 4f 54 20 45 58 49 53  the "IF NOT EXIS
b6a0: 54 53 22 20 63 6c 61 75 73 65 20 69 73 20 73 70  TS" clause is sp
b6b0: 65 63 69 66 69 65 64 2e 0a 0a 3c 70 3e 5e 49 74  ecified...<p>^It
b6c0: 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   is not an error
b6d0: 20 74 6f 20 63 72 65 61 74 65 20 61 20 74 61 62   to create a tab
b6e0: 6c 65 20 74 68 61 74 20 68 61 73 20 74 68 65 20  le that has the 
b6f0: 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 61 6e 20  same name as an 
b700: 0a 20 20 65 78 69 73 74 69 6e 67 20 5b 43 52 45  .  existing [CRE
b710: 41 54 45 20 54 52 49 47 47 45 52 7c 74 72 69 67  ATE TRIGGER|trig
b720: 67 65 72 5d 2e 0a 0a 3c 70 3e 5e 54 61 62 6c 65  ger]...<p>^Table
b730: 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20 75 73  s are removed us
b740: 69 6e 67 20 74 68 65 20 5b 44 52 4f 50 20 54 41  ing the [DROP TA
b750: 42 4c 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  BLE] statement. 
b760: 20 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66   </p>..<tcl>hd_f
b770: 72 61 67 6d 65 6e 74 20 63 72 65 61 74 65 74 61  ragment createta
b780: 62 61 73 20 7b 43 52 45 41 54 45 20 54 41 42 4c  bas {CREATE TABL
b790: 45 20 41 53 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  E AS}</tcl>.<h3>
b7a0: 43 52 45 41 54 45 20 54 41 42 4c 45 20 2e 2e 2e  CREATE TABLE ...
b7b0: 20 41 53 20 53 45 4c 45 43 54 20 53 74 61 74 65   AS SELECT State
b7c0: 6d 65 6e 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e  ments</h3>..<p>^
b7d0: 28 41 20 22 43 52 45 41 54 45 20 54 41 42 4c 45  (A "CREATE TABLE
b7e0: 20 2e 2e 2e 20 41 53 20 53 45 4c 45 43 54 22 20   ... AS SELECT" 
b7f0: 73 74 61 74 65 6d 65 6e 74 20 63 72 65 61 74 65  statement create
b800: 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20  s and populates 
b810: 61 20 64 61 74 61 62 61 73 65 0a 74 61 62 6c 65  a database.table
b820: 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 72 65   based on the re
b830: 73 75 6c 74 73 20 6f 66 20 61 20 53 45 4c 45 43  sults of a SELEC
b840: 54 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 20 5e  T statement.)^ ^
b850: 28 54 68 65 20 74 61 62 6c 65 20 68 61 73 20 74  (The table has t
b860: 68 65 20 73 61 6d 65 0a 6e 75 6d 62 65 72 20 6f  he same.number o
b870: 66 20 63 6f 6c 75 6d 6e 73 20 61 73 20 74 68 65  f columns as the
b880: 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62   rows returned b
b890: 79 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  y the SELECT sta
b8a0: 74 65 6d 65 6e 74 2e 20 54 68 65 20 6e 61 6d 65  tement. The name
b8b0: 20 6f 66 0a 65 61 63 68 20 63 6f 6c 75 6d 6e 20   of.each column 
b8c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
b8d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
b8e0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6c  orresponding col
b8f0: 75 6d 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c  umn in the resul
b900: 74 0a 73 65 74 20 6f 66 20 74 68 65 20 53 45 4c  t.set of the SEL
b910: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  ECT statement.)^
b920: 20 5e 28 54 68 65 20 64 65 63 6c 61 72 65 64 20   ^(The declared 
b930: 74 79 70 65 20 6f 66 20 65 61 63 68 20 63 6f 6c  type of each col
b940: 75 6d 6e 20 69 73 20 64 65 74 65 72 6d 69 6e 65  umn is determine
b950: 64 0a 62 79 20 74 68 65 20 5b 65 78 70 72 65 73  d.by the [expres
b960: 73 69 6f 6e 20 61 66 66 69 6e 69 74 79 5d 20 6f  sion affinity] o
b970: 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
b980: 69 6e 67 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ing expression i
b990: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
b9a0: 0a 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20 73  .of the SELECT s
b9b0: 74 61 74 65 6d 65 6e 74 2c 20 61 73 20 66 6f 6c  tatement, as fol
b9c0: 6c 6f 77 73 3a 0a 3c 2f 70 3e 0a 0a 3c 63 65 6e  lows:.</p>..<cen
b9d0: 74 65 72 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ter><table borde
b9e0: 72 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 45  r=1>.  <tr><th>E
b9f0: 78 70 72 65 73 73 69 6f 6e 20 41 66 66 69 6e 69  xpression Affini
ba00: 74 79 20 20 20 3c 74 68 3e 43 6f 6c 75 6d 6e 20  ty   <th>Column 
ba10: 44 65 63 6c 61 72 65 64 20 54 79 70 65 0a 20 20  Declared Type.  
ba20: 3c 74 72 3e 3c 74 64 3e 54 45 58 54 20 20 20 20  <tr><td>TEXT    
ba30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 74                <t
ba40: 64 3e 22 54 45 58 54 22 0a 20 20 3c 74 72 3e 3c  d>"TEXT".  <tr><
ba50: 74 64 3e 4e 55 4d 45 52 49 43 20 20 20 20 20 20  td>NUMERIC      
ba60: 20 20 20 20 20 20 20 20 20 3c 74 64 3e 22 4e 55           <td>"NU
ba70: 4d 22 0a 20 20 3c 74 72 3e 3c 74 64 3e 49 4e 54  M".  <tr><td>INT
ba80: 45 47 45 52 20 20 20 20 20 20 20 20 20 20 20 20  EGER            
ba90: 20 20 20 3c 74 64 3e 22 49 4e 54 22 0a 20 20 3c     <td>"INT".  <
baa0: 74 72 3e 3c 74 64 3e 52 45 41 4c 20 20 20 20 20  tr><td>REAL     
bab0: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 74 64               <td
bac0: 3e 22 52 45 41 4c 22 0a 20 20 3c 74 72 3e 3c 74  >"REAL".  <tr><t
bad0: 64 3e 42 4c 4f 42 20 28 61 2e 6b 2e 61 20 22 4e  d>BLOB (a.k.a "N
bae0: 4f 4e 45 22 29 20 20 20 3c 74 64 3e 22 22 20 28  ONE")   <td>"" (
baf0: 65 6d 70 74 79 20 73 74 72 69 6e 67 29 0a 3c 2f  empty string).</
bb00: 74 61 62 6c 65 3e 3c 2f 63 65 6e 74 65 72 3e 29  table></center>)
bb10: 5e 0a 0a 3c 70 3e 5e 28 41 20 74 61 62 6c 65 20  ^..<p>^(A table 
bb20: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 43 52  created using CR
bb30: 45 41 54 45 20 54 41 42 4c 45 20 41 53 20 68 61  EATE TABLE AS ha
bb40: 73 20 6e 6f 20 50 52 49 4d 41 52 59 20 4b 45 59  s no PRIMARY KEY
bb50: 20 61 6e 64 20 6e 6f 0a 63 6f 6e 73 74 72 61 69   and no.constrai
bb60: 6e 74 73 20 6f 66 20 61 6e 79 20 6b 69 6e 64 2e  nts of any kind.
bb70: 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
bb80: 75 65 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  ue of each colum
bb90: 6e 20 69 73 20 4e 55 4c 4c 2e 20 54 68 65 20 64  n is NULL. The d
bba0: 65 66 61 75 6c 74 0a 63 6f 6c 6c 61 74 69 6f 6e  efault.collation
bbb0: 20 73 65 71 75 65 6e 63 65 20 66 6f 72 20 65 61   sequence for ea
bbc0: 63 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  ch column of the
bbd0: 20 6e 65 77 20 74 61 62 6c 65 20 69 73 20 42 49   new table is BI
bbe0: 4e 41 52 59 2e 29 5e 0a 0a 3c 70 3e 5e 54 61 62  NARY.)^..<p>^Tab
bbf0: 6c 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  les created usin
bc00: 67 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 41  g CREATE TABLE A
bc10: 53 20 61 72 65 20 69 6e 69 74 69 61 6c 6c 79 20  S are initially 
bc20: 70 6f 70 75 6c 61 74 65 64 20 77 69 74 68 20 74  populated with t
bc30: 68 65 0a 72 6f 77 73 20 6f 66 20 64 61 74 61 20  he.rows of data 
bc40: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
bc50: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
bc60: 2e 20 5e 52 6f 77 73 20 61 72 65 20 61 73 73 69  . ^Rows are assi
bc70: 67 6e 65 64 20 63 6f 6e 74 69 67 75 6f 75 73 6c  gned contiguousl
bc80: 79 0a 61 73 63 65 6e 64 69 6e 67 20 5b 72 6f 77  y.ascending [row
bc90: 69 64 5d 20 76 61 6c 75 65 73 2c 20 73 74 61 72  id] values, star
bca0: 74 69 6e 67 20 77 69 74 68 20 31 2c 20 69 6e 20  ting with 1, in 
bcb0: 74 68 65 20 5b 6f 72 64 65 72 20 62 79 7c 6f 72  the [order by|or
bcc0: 64 65 72 5d 20 74 68 61 74 20 74 68 65 79 0a 61  der] that they.a
bcd0: 72 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  re returned by t
bce0: 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
bcf0: 65 6e 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  ent...<tcl>hd_fr
bd00: 61 67 6d 65 6e 74 20 7b 74 61 62 6c 65 63 6f 6c  agment {tablecol
bd10: 64 65 66 7d 20 7b 63 6f 6c 75 6d 6e 20 64 65 66  def} {column def
bd20: 69 6e 69 74 69 6f 6e 7d 20 7b 63 6f 6c 75 6d 6e  inition} {column
bd30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 3c 2f 74   definitions}</t
bd40: 63 6c 3e 0a 3c 68 33 3e 43 6f 6c 75 6d 6e 20 44  cl>.<h3>Column D
bd50: 65 66 69 6e 69 74 69 6f 6e 73 3c 2f 68 33 3e 0a  efinitions</h3>.
bd60: 0a 3c 70 3e 55 6e 6c 65 73 73 20 69 74 20 69 73  .<p>Unless it is
bd70: 20 61 20 43 52 45 41 54 45 20 54 41 42 4c 45 20   a CREATE TABLE 
bd80: 2e 2e 2e 20 41 53 20 53 45 4c 45 43 54 20 73 74  ... AS SELECT st
bd90: 61 74 65 6d 65 6e 74 2c 20 61 20 43 52 45 41 54  atement, a CREAT
bda0: 45 20 54 41 42 4c 45 20 69 6e 63 6c 75 64 65 73  E TABLE includes
bdb0: 0a 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 5b 63 6f  .one or more [co
bdc0: 6c 75 6d 6e 2d 64 65 66 7c 63 6f 6c 75 6d 6e 20  lumn-def|column 
bdd0: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 2c 20 6f 70  definitions], op
bde0: 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
bdf0: 64 20 62 79 20 61 20 6c 69 73 74 20 6f 66 0a 5b  d by a list of.[
be00: 74 61 62 6c 65 2d 63 6f 6e 73 74 72 61 69 6e 74  table-constraint
be10: 7c 74 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e  |table constrain
be20: 74 73 5d 2e 20 20 45 61 63 68 20 63 6f 6c 75 6d  ts].  Each colum
be30: 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20 63 6f 6e  n definition con
be40: 73 69 73 74 73 20 6f 66 20 74 68 65 0a 6e 61 6d  sists of the.nam
be50: 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 2c  e of the column,
be60: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
be70: 6f 77 65 64 20 62 79 20 74 68 65 20 64 65 63 6c  owed by the decl
be80: 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
be90: 20 63 6f 6c 75 6d 6e 2c 0a 74 68 65 6e 20 6f 6e   column,.then on
bea0: 65 20 6f 72 20 6d 6f 72 65 20 6f 70 74 69 6f 6e  e or more option
beb0: 61 6c 20 5b 63 6f 6c 75 6d 6e 2d 63 6f 6e 73 74  al [column-const
bec0: 72 61 69 6e 74 7c 63 6f 6c 75 6d 6e 20 63 6f 6e  raint|column con
bed0: 73 74 72 61 69 6e 74 73 5d 2e 20 49 6e 63 6c 75  straints]. Inclu
bee0: 64 65 64 20 69 6e 0a 74 68 65 20 64 65 66 69 6e  ded in.the defin
bef0: 69 74 69 6f 6e 20 6f 66 20 22 63 6f 6c 75 6d 6e  ition of "column
bf00: 20 63 6f 6e 73 74 72 61 69 6e 74 73 22 20 66 6f   constraints" fo
bf10: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
bf20: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 73  f the previous.s
bf30: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 74 68 65  tatement are the
bf40: 20 43 4f 4c 4c 41 54 45 20 61 6e 64 20 44 45 46   COLLATE and DEF
bf50: 41 55 4c 54 20 63 6c 61 75 73 65 73 2c 20 65 76  AULT clauses, ev
bf60: 65 6e 20 74 68 6f 75 67 68 20 74 68 65 73 65 20  en though these 
bf70: 61 72 65 20 6e 6f 74 20 72 65 61 6c 6c 79 0a 63  are not really.c
bf80: 6f 6e 73 74 72 61 69 6e 74 73 20 69 6e 20 74 68  onstraints in th
bf90: 65 20 73 65 6e 73 65 20 74 68 61 74 20 74 68 65  e sense that the
bfa0: 79 20 64 6f 20 6e 6f 74 20 72 65 73 74 72 69 63  y do not restric
bfb0: 74 20 74 68 65 20 64 61 74 61 20 74 68 61 74 20  t the data that 
bfc0: 74 68 65 20 74 61 62 6c 65 20 6d 61 79 0a 63 6f  the table may.co
bfd0: 6e 74 61 69 6e 2e 20 54 68 65 20 6f 74 68 65 72  ntain. The other
bfe0: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2d 20 4e   constraints - N
bff0: 4f 54 20 4e 55 4c 4c 2c 20 43 48 45 43 4b 2c 20  OT NULL, CHECK, 
c000: 55 4e 49 51 55 45 2c 20 50 52 49 4d 41 52 59 20  UNIQUE, PRIMARY 
c010: 4b 45 59 20 61 6e 64 0a 46 4f 52 45 49 47 4e 20  KEY and.FOREIGN 
c020: 4b 45 59 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  KEY constraints 
c030: 2d 20 69 6d 70 6f 73 65 20 72 65 73 74 72 69 63  - impose restric
c040: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 74 61 62  tions on the tab
c050: 6c 65 73 20 64 61 74 61 2c 20 61 6e 64 20 61 72  les data, and ar
c060: 65 20 61 72 65 0a 64 65 73 63 72 69 62 65 64 20  e are.described 
c070: 75 6e 64 65 72 20 5b 63 6f 6e 73 74 72 61 69 6e  under [constrain
c080: 74 73 7c 53 51 4c 20 44 61 74 61 20 43 6f 6e 73  ts|SQL Data Cons
c090: 74 72 61 69 6e 74 73 5d 20 62 65 6c 6f 77 2e 0a  traints] below..
c0a0: 0a 3c 70 3e 5e 55 6e 6c 69 6b 65 20 6d 6f 73 74  .<p>^Unlike most
c0b0: 20 53 51 4c 20 64 61 74 61 62 61 73 65 73 2c 20   SQL databases, 
c0c0: 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
c0d0: 72 65 73 74 72 69 63 74 20 74 68 65 20 74 79 70  restrict the typ
c0e0: 65 20 6f 66 20 64 61 74 61 20 74 68 61 74 0a 6d  e of data that.m
c0f0: 61 79 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  ay be inserted i
c100: 6e 74 6f 20 61 20 63 6f 6c 75 6d 6e 20 62 61 73  nto a column bas
c110: 65 64 20 6f 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  ed on the column
c120: 73 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  s declared type.
c130: 20 49 6e 73 74 65 61 64 2c 0a 53 51 4c 69 74 65   Instead,.SQLite
c140: 20 75 73 65 73 20 5b 64 79 6e 61 6d 69 63 20 74   uses [dynamic t
c150: 79 70 69 6e 67 5d 2e 20 5e 54 68 65 20 64 65 63  yping]. ^The dec
c160: 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 61 20  lared type of a 
c170: 63 6f 6c 75 6d 6e 20 69 73 20 75 73 65 64 20 74  column is used t
c180: 6f 0a 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o.determine the 
c190: 5b 61 66 66 69 6e 69 74 79 5d 20 6f 66 20 74 68  [affinity] of th
c1a0: 65 20 63 6f 6c 75 6d 6e 20 6f 6e 6c 79 2e 0a 0a  e column only...
c1b0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
c1c0: 20 64 66 6c 74 76 61 6c 20 7b 64 65 66 61 75 6c   dfltval {defaul
c1d0: 74 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 7d 20  t column value} 
c1e0: 7b 64 65 66 61 75 6c 74 20 76 61 6c 75 65 7d 3c  {default value}<
c1f0: 2f 74 63 6c 3e 0a 3c 70 3e 54 68 65 20 44 45 46  /tcl>.<p>The DEF
c200: 41 55 4c 54 20 63 6c 61 75 73 65 20 73 70 65 63  AULT clause spec
c210: 69 66 69 65 73 20 61 20 64 65 66 61 75 6c 74 20  ifies a default 
c220: 76 61 6c 75 65 20 74 6f 20 75 73 65 20 66 6f 72  value to use for
c230: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 66 20 6e   the column if n
c240: 6f 0a 76 61 6c 75 65 20 69 73 20 65 78 70 6c 69  o.value is expli
c250: 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64 20 62  citly provided b
c260: 79 20 74 68 65 20 75 73 65 72 20 77 68 65 6e 20  y the user when 
c270: 64 6f 69 6e 67 20 61 6e 20 5b 49 4e 53 45 52 54  doing an [INSERT
c280: 5d 2e 20 5e 49 66 20 74 68 65 72 65 0a 69 73 20  ]. ^If there.is 
c290: 6e 6f 20 65 78 70 6c 69 63 69 74 20 44 45 46 41  no explicit DEFA
c2a0: 55 4c 54 20 63 6c 61 75 73 65 20 61 74 74 61 63  ULT clause attac
c2b0: 68 65 64 20 74 6f 20 61 20 63 6f 6c 75 6d 6e 20  hed to a column 
c2c0: 64 65 66 69 6e 69 74 69 6f 6e 2c 20 74 68 65 6e  definition, then
c2d0: 20 74 68 65 20 0a 64 65 66 61 75 6c 74 20 76 61   the .default va
c2e0: 6c 75 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  lue of the colum
c2f0: 6e 20 69 73 20 4e 55 4c 4c 2e 20 5e 28 41 6e 20  n is NULL. ^(An 
c300: 65 78 70 6c 69 63 69 74 20 44 45 46 41 55 4c 54  explicit DEFAULT
c310: 20 63 6c 61 75 73 65 20 6d 61 79 20 73 70 65 63   clause may spec
c320: 69 66 79 0a 74 68 61 74 20 74 68 65 20 64 65 66  ify.that the def
c330: 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 4e 55  ault value is NU
c340: 4c 4c 2c 20 61 20 73 74 72 69 6e 67 20 63 6f 6e  LL, a string con
c350: 73 74 61 6e 74 2c 20 61 20 62 6c 6f 62 20 63 6f  stant, a blob co
c360: 6e 73 74 61 6e 74 2c 20 61 0a 73 69 67 6e 65 64  nstant, a.signed
c370: 2d 6e 75 6d 62 65 72 2c 20 6f 72 20 61 6e 79 20  -number, or any 
c380: 63 6f 6e 73 74 61 6e 74 20 65 78 70 72 65 73 73  constant express
c390: 69 6f 6e 20 65 6e 63 6c 6f 73 65 64 20 69 6e 20  ion enclosed in 
c3a0: 70 61 72 65 6e 74 68 65 73 65 73 2e 20 41 0a 64  parentheses. A.d
c3b0: 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
c3c0: 20 61 6c 73 6f 20 62 65 20 6f 6e 65 20 6f 66 20   also be one of 
c3d0: 74 68 65 20 73 70 65 63 69 61 6c 20 63 61 73 65  the special case
c3e0: 2d 69 6e 64 65 70 65 6e 64 65 6e 74 20 6b 65 79  -independent key
c3f0: 77 6f 72 64 73 0a 43 55 52 52 45 4e 54 5f 54 49  words.CURRENT_TI
c400: 4d 45 2c 20 43 55 52 52 45 4e 54 5f 44 41 54 45  ME, CURRENT_DATE
c410: 20 6f 72 20 43 55 52 52 45 4e 54 5f 54 49 4d 45   or CURRENT_TIME
c420: 53 54 41 4d 50 2e 29 5e 20 5e 46 6f 72 20 74 68  STAMP.)^ ^For th
c430: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
c440: 65 0a 44 45 46 41 55 4c 54 20 63 6c 61 75 73 65  e.DEFAULT clause
c450: 2c 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  , an expression 
c460: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 63 6f  is considered co
c470: 6e 73 74 61 6e 74 20 69 66 20 69 74 0a 63 6f 6e  nstant if it.con
c480: 74 61 69 6e 73 20 6e 6f 20 73 75 62 2d 71 75 65  tains no sub-que
c490: 72 69 65 73 2c 20 63 6f 6c 75 6d 6e 20 6f 72 20  ries, column or 
c4a0: 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
c4b0: 2c 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  , [bound paramet
c4c0: 65 72 73 5d 2c 0a 6f 72 20 73 74 72 69 6e 67 20  ers],.or string 
c4d0: 6c 69 74 65 72 61 6c 73 20 65 6e 63 6c 6f 73 65  literals enclose
c4e0: 64 20 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  d in double-quot
c4f0: 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
c500: 6e 67 6c 65 2d 71 75 6f 74 65 73 2e 0a 0a 3c 70  ngle-quotes...<p
c510: 3e 5e 28 45 61 63 68 20 74 69 6d 65 20 61 20 72  >^(Each time a r
c520: 6f 77 20 69 73 20 69 6e 73 65 72 74 65 64 20 69  ow is inserted i
c530: 6e 74 6f 20 74 68 65 20 74 61 62 6c 65 20 62 79  nto the table by
c540: 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74 65   an INSERT state
c550: 6d 65 6e 74 20 74 68 61 74 20 0a 64 6f 65 73 20  ment that .does 
c560: 6e 6f 74 20 70 72 6f 76 69 64 65 20 65 78 70 6c  not provide expl
c570: 69 63 69 74 20 76 61 6c 75 65 73 20 66 6f 72 20  icit values for 
c580: 61 6c 6c 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  all table column
c590: 73 20 74 68 65 20 76 61 6c 75 65 73 20 73 74 6f  s the values sto
c5a0: 72 65 64 20 69 6e 0a 74 68 65 20 6e 65 77 20 72  red in.the new r
c5b0: 6f 77 20 61 72 65 20 64 65 74 65 72 6d 69 6e 65  ow are determine
c5c0: 64 20 62 79 20 74 68 65 69 72 20 64 65 66 61 75  d by their defau
c5d0: 6c 74 20 76 61 6c 75 65 73 29 5e 2c 20 61 73 20  lt values)^, as 
c5e0: 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 75 6c 3e 0a 20  follows:..<ul>. 
c5f0: 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20   <li><p>^If the 
c600: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
c610: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 61   the column is a
c620: 20 63 6f 6e 73 74 61 6e 74 20 4e 55 4c 4c 2c 20   constant NULL, 
c630: 74 65 78 74 2c 20 62 6c 6f 62 20 6f 72 0a 20 20  text, blob or.  
c640: 20 20 73 69 67 6e 65 64 2d 6e 75 6d 62 65 72 20    signed-number 
c650: 76 61 6c 75 65 2c 20 74 68 65 6e 20 74 68 61 74  value, then that
c660: 20 76 61 6c 75 65 20 69 73 20 75 73 65 64 20 64   value is used d
c670: 69 72 65 63 74 6c 79 20 69 6e 20 74 68 65 20 6e  irectly in the n
c680: 65 77 20 72 6f 77 2e 0a 0a 20 20 3c 6c 69 3e 3c  ew row...  <li><
c690: 70 3e 5e 49 66 20 74 68 65 20 64 65 66 61 75 6c  p>^If the defaul
c6a0: 74 20 76 61 6c 75 65 20 6f 66 20 61 20 63 6f 6c  t value of a col
c6b0: 75 6d 6e 20 69 73 20 61 6e 20 65 78 70 72 65 73  umn is an expres
c6c0: 73 69 6f 6e 20 69 6e 20 70 61 72 65 6e 74 68 65  sion in parenthe
c6d0: 73 65 73 2c 20 74 68 65 6e 0a 20 20 20 20 74 68  ses, then.    th
c6e0: 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  e expression is 
c6f0: 65 76 61 6c 75 61 74 65 64 20 6f 6e 63 65 20 66  evaluated once f
c700: 6f 72 20 65 61 63 68 20 72 6f 77 20 69 6e 73 65  or each row inse
c710: 72 74 65 64 20 61 6e 64 20 74 68 65 20 72 65 73  rted and the res
c720: 75 6c 74 73 0a 20 20 20 20 75 73 65 64 20 69 6e  ults.    used in
c730: 20 74 68 65 20 6e 65 77 20 72 6f 77 2e 0a 0a 20   the new row... 
c740: 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68 65 20   <li><p>^If the 
c750: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66  default value of
c760: 20 61 20 63 6f 6c 75 6d 6e 20 69 73 20 43 55 52   a column is CUR
c770: 52 45 4e 54 5f 54 49 4d 45 2c 20 43 55 52 52 45  RENT_TIME, CURRE
c780: 4e 54 5f 44 41 54 45 20 6f 72 0a 20 20 20 20 43  NT_DATE or.    C
c790: 55 52 52 45 4e 54 5f 54 49 4d 45 53 54 41 4d 50  URRENT_TIMESTAMP
c7a0: 2c 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  , then the value
c7b0: 20 75 73 65 64 20 69 6e 20 74 68 65 20 6e 65 77   used in the new
c7c0: 20 72 6f 77 20 69 73 20 61 20 74 65 78 74 0a 20   row is a text. 
c7d0: 20 20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f     representatio
c7e0: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
c7f0: 20 55 54 43 20 64 61 74 65 20 61 6e 64 2f 6f 72   UTC date and/or
c800: 20 74 69 6d 65 2e 20 5e 46 6f 72 20 43 55 52 52   time. ^For CURR
c810: 45 4e 54 5f 54 49 4d 45 2c 20 74 68 65 0a 20 20  ENT_TIME, the.  
c820: 20 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20    format of the 
c830: 76 61 6c 75 65 20 69 73 20 22 48 48 3a 4d 4d 3a  value is "HH:MM:
c840: 53 53 22 2e 20 5e 46 6f 72 20 43 55 52 52 45 4e  SS". ^For CURREN
c850: 54 5f 44 41 54 45 2c 20 22 59 59 59 59 2d 4d 4d  T_DATE, "YYYY-MM
c860: 2d 44 44 22 2e 20 5e 54 68 65 0a 20 20 20 20 66  -DD". ^The.    f
c870: 6f 72 6d 61 74 20 66 6f 72 20 43 55 52 52 45 4e  ormat for CURREN
c880: 54 5f 54 49 4d 45 53 54 41 4d 50 20 69 73 20 22  T_TIMESTAMP is "
c890: 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48 3a 4d 4d  YYYY-MM-DD HH:MM
c8a0: 3a 53 53 22 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  :SS"..</ul>..<p>
c8b0: 5e 54 68 65 20 43 4f 4c 4c 41 54 45 20 63 6c 61  ^The COLLATE cla
c8c0: 75 73 65 20 73 70 65 63 69 66 69 65 73 20 74 68  use specifies th
c8d0: 65 20 6e 61 6d 65 20 6f 66 20 61 20 5b 63 6f 6c  e name of a [col
c8e0: 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 5d  lating sequence]
c8f0: 20 74 6f 20 75 73 65 20 61 73 0a 74 68 65 20 64   to use as.the d
c900: 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
c910: 20 73 65 71 75 65 6e 63 65 20 66 6f 72 20 74 68   sequence for th
c920: 65 20 63 6f 6c 75 6d 6e 2e 20 5e 49 66 20 6e 6f  e column. ^If no
c930: 20 43 4f 4c 4c 41 54 45 20 63 6c 61 75 73 65 20   COLLATE clause 
c940: 69 73 0a 73 70 65 63 69 66 69 65 64 2c 20 74 68  is.specified, th
c950: 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
c960: 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
c970: 5b 42 49 4e 41 52 59 5d 2e 0a 0a 3c 70 3e 5e 54  [BINARY]...<p>^T
c980: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
c990: 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
c9a0: 69 73 20 6c 69 6d 69 74 65 64 20 62 79 20 74 68  is limited by th
c9b0: 65 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f  e [SQLITE_MAX_CO
c9c0: 4c 55 4d 4e 5d 0a 63 6f 6d 70 69 6c 65 2d 74 69  LUMN].compile-ti
c9d0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2e 20 5e 41  me parameter. ^A
c9e0: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
c9f0: 20 74 61 62 6c 65 20 63 61 6e 6e 6f 74 20 73 74   table cannot st
ca00: 6f 72 65 20 6d 6f 72 65 20 74 68 61 6e 0a 5b 53  ore more than.[S
ca10: 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
ca20: 5d 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 2e  ] bytes of data.
ca30: 20 5e 42 6f 74 68 20 6f 66 20 74 68 65 73 65 20   ^Both of these 
ca40: 6c 69 6d 69 74 73 20 63 61 6e 20 62 65 20 6c 6f  limits can be lo
ca50: 77 65 72 65 64 20 61 74 0a 72 75 6e 74 69 6d 65  wered at.runtime
ca60: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
ca70: 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 43 2f 43  te3_limit()] C/C
ca80: 2b 2b 20 69 6e 74 65 72 66 61 63 65 2e 3c 2f 70  ++ interface.</p
ca90: 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
caa0: 65 6e 74 20 7b 63 6f 6e 73 74 72 61 69 6e 74 73  ent {constraints
cab0: 7d 20 7b 63 6f 6e 73 74 72 61 69 6e 74 73 7d 3c  } {constraints}<
cac0: 2f 74 63 6c 3e 0a 3c 68 33 3e 53 51 4c 20 44 61  /tcl>.<h3>SQL Da
cad0: 74 61 20 43 6f 6e 73 74 72 61 69 6e 74 73 3c 2f  ta Constraints</
cae0: 68 33 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  h3>..<tcl>hd_fra
caf0: 67 6d 65 6e 74 20 70 72 69 6d 6b 65 79 63 6f 6e  gment primkeycon
cb00: 73 74 20 7b 50 52 49 4d 41 52 59 20 4b 45 59 7d  st {PRIMARY KEY}
cb10: 20 7b 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f   {PRIMARY KEY co
cb20: 6e 73 74 72 61 69 6e 74 7d 3c 2f 74 63 6c 3e 0a  nstraint}</tcl>.
cb30: 3c 70 3e 5e 45 61 63 68 20 74 61 62 6c 65 20 69  <p>^Each table i
cb40: 6e 20 53 51 4c 69 74 65 20 6d 61 79 20 68 61 76  n SQLite may hav
cb50: 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 3c 62  e at most one <b
cb60: 3e 50 52 49 4d 41 52 59 20 4b 45 59 3c 2f 62 3e  >PRIMARY KEY</b>
cb70: 2e 20 5e 49 66 20 74 68 65 0a 20 20 6b 65 79 77  . ^If the.  keyw
cb80: 6f 72 64 73 20 50 52 49 4d 41 52 59 20 4b 45 59  ords PRIMARY KEY
cb90: 20 61 72 65 20 61 64 64 65 64 20 74 6f 20 61 20   are added to a 
cba0: 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f  column definitio
cbb0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6d  n, then the prim
cbc0: 61 72 79 20 6b 65 79 0a 20 20 66 6f 72 20 74 68  ary key.  for th
cbd0: 65 20 74 61 62 6c 65 20 63 6f 6e 73 69 73 74 73  e table consists
cbe0: 20 6f 66 20 74 68 61 74 20 73 69 6e 67 6c 65 20   of that single 
cbf0: 63 6f 6c 75 6d 6e 2e 20 5e 4f 72 2c 20 69 66 20  column. ^Or, if 
cc00: 61 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6c  a PRIMARY KEY cl
cc10: 61 75 73 65 20 0a 20 20 69 73 20 73 70 65 63 69  ause .  is speci
cc20: 66 69 65 64 20 61 73 20 61 20 5b 74 61 62 6c 65  fied as a [table
cc30: 2d 63 6f 6e 73 74 72 61 69 6e 74 5d 2c 20 74 68  -constraint], th
cc40: 65 6e 20 74 68 65 20 70 72 69 6d 61 72 79 20 6b  en the primary k
cc50: 65 79 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  ey of the table.
cc60: 20 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68    consists of th
cc70: 65 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e  e list of column
cc80: 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  s specified as p
cc90: 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
cca0: 52 59 20 4b 45 59 20 63 6c 61 75 73 65 2e 0a 20  RY KEY clause.. 
ccb0: 20 5e 54 68 65 20 50 52 49 4d 41 52 59 20 4b 45   ^The PRIMARY KE
ccc0: 59 20 63 6c 61 75 73 65 20 6d 75 73 74 20 63 6f  Y clause must co
ccd0: 6e 74 61 69 6e 20 6f 6e 6c 79 20 63 6f 6c 75 6d  ntain only colum
cce0: 6e 20 6e 61 6d 65 73 20 26 6d 64 61 73 68 3b 20  n names &mdash; 
ccf0: 74 68 65 20 75 73 65 20 6f 66 20 0a 20 20 65 78  the use of .  ex
cd00: 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e 20  pressions in an 
cd10: 5b 69 6e 64 65 78 65 64 2d 63 6f 6c 75 6d 6e 5d  [indexed-column]
cd20: 20 6f 66 20 61 20 50 52 49 4d 41 52 59 20 4b 45   of a PRIMARY KE
cd30: 59 20 69 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  Y is not support
cd40: 65 64 2e 0a 20 20 5e 41 6e 20 65 72 72 6f 72 20  ed..  ^An error 
cd50: 69 73 20 72 61 69 73 65 64 20 69 66 20 6d 6f 72  is raised if mor
cd60: 65 20 74 68 61 6e 20 6f 6e 65 20 50 52 49 4d 41  e than one PRIMA
cd70: 52 59 20 4b 45 59 20 63 6c 61 75 73 65 20 61 70  RY KEY clause ap
cd80: 70 65 61 72 73 20 69 6e 20 61 0a 20 20 43 52 45  pears in a.  CRE
cd90: 41 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d  ATE TABLE statem
cda0: 65 6e 74 2e 20 20 5e 54 68 65 20 50 52 49 4d 41  ent.  ^The PRIMA
cdb0: 52 59 20 4b 45 59 20 69 73 20 6f 70 74 69 6f 6e  RY KEY is option
cdc0: 61 6c 20 66 6f 72 20 6f 72 64 69 6e 61 72 79 20  al for ordinary 
cdd0: 74 61 62 6c 65 73 0a 20 20 62 75 74 20 69 73 20  tables.  but is 
cde0: 72 65 71 75 69 72 65 64 20 66 6f 72 20 5b 57 49  required for [WI
cdf0: 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
ce00: 6c 65 73 2e 0a 0a 3c 70 3e 49 66 20 61 20 74 61  les...<p>If a ta
ce10: 62 6c 65 20 68 61 73 20 61 20 73 69 6e 67 6c 65  ble has a single
ce20: 20 63 6f 6c 75 6d 6e 20 70 72 69 6d 61 72 79 20   column primary 
ce30: 6b 65 79 20 61 6e 64 20 74 68 65 20 64 65 63 6c  key and the decl
ce40: 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 61  ared type of tha
ce50: 74 0a 20 20 63 6f 6c 75 6d 6e 20 69 73 20 22 49  t.  column is "I
ce60: 4e 54 45 47 45 52 22 20 61 6e 64 20 74 68 65 20  NTEGER" and the 
ce70: 74 61 62 6c 65 20 69 73 20 6e 6f 74 20 61 20 5b  table is not a [
ce80: 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
ce90: 61 62 6c 65 2c 0a 20 20 74 68 65 6e 20 74 68 65  able,.  then the
cea0: 20 63 6f 6c 75 6d 6e 20 69 73 20 6b 6e 6f 77 6e   column is known
ceb0: 20 61 73 20 61 6e 20 5b 49 4e 54 45 47 45 52 20   as an [INTEGER 
cec0: 50 52 49 4d 41 52 59 20 4b 45 59 5d 2e 0a 20 20  PRIMARY KEY]..  
ced0: 53 65 65 20 5b 72 6f 77 69 64 7c 62 65 6c 6f 77  See [rowid|below
cee0: 5d 20 66 6f 72 20 61 20 64 65 73 63 72 69 70 74  ] for a descript
cef0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
cf00: 61 6c 20 70 72 6f 70 65 72 74 69 65 73 20 61 6e  al properties an
cf10: 64 20 62 65 68 61 76 69 6f 72 73 0a 20 20 61 73  d behaviors.  as
cf20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 6e  sociated with an
cf30: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
cf40: 59 20 4b 45 59 5d 2e 0a 0a 3c 70 3e 5e 45 61 63  Y KEY]...<p>^Eac
cf50: 68 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c 65  h row in a table
cf60: 20 77 69 74 68 20 61 20 70 72 69 6d 61 72 79 20   with a primary 
cf70: 6b 65 79 20 6d 75 73 74 20 68 61 76 65 20 61 20  key must have a 
cf80: 75 6e 69 71 75 65 20 63 6f 6d 62 69 6e 61 74 69  unique combinati
cf90: 6f 6e 0a 20 20 6f 66 20 76 61 6c 75 65 73 20 69  on.  of values i
cfa0: 6e 20 69 74 73 20 70 72 69 6d 61 72 79 20 6b 65  n its primary ke
cfb0: 79 20 63 6f 6c 75 6d 6e 73 2e 20 5e 46 6f 72 20  y columns. ^For 
cfc0: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
cfd0: 64 65 74 65 72 6d 69 6e 69 6e 67 0a 20 20 74 68  determining.  th
cfe0: 65 20 75 6e 69 71 75 65 6e 65 73 73 20 6f 66 20  e uniqueness of 
cff0: 70 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75  primary key valu
d000: 65 73 2c 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  es, NULL values 
d010: 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 64  are considered d
d020: 69 73 74 69 6e 63 74 20 66 72 6f 6d 0a 20 20 61  istinct from.  a
d030: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 2c  ll other values,
d040: 20 69 6e 63 6c 75 64 69 6e 67 20 6f 74 68 65 72   including other
d050: 20 4e 55 4c 4c 73 2e 20 5e 49 66 20 61 6e 20 5b   NULLs. ^If an [
d060: 49 4e 53 45 52 54 5d 20 6f 72 20 5b 55 50 44 41  INSERT] or [UPDA
d070: 54 45 5d 0a 20 20 73 74 61 74 65 6d 65 6e 74 20  TE].  statement 
d080: 61 74 74 65 6d 70 74 73 20 74 6f 20 6d 6f 64 69  attempts to modi
d090: 66 79 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  fy the table con
d0a0: 74 65 6e 74 20 73 6f 20 74 68 61 74 20 74 77 6f  tent so that two
d0b0: 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 0a 20 20   or more rows.  
d0c0: 68 61 76 65 20 69 64 65 6e 74 69 63 61 6c 20 70  have identical p
d0d0: 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75 65  rimary key value
d0e0: 73 2c 20 74 68 61 74 20 69 73 20 61 20 63 6f 6e  s, that is a con
d0f0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
d100: 6e 2e 0a 0a 3c 70 3e 20 41 63 63 6f 72 64 69 6e  n...<p> Accordin
d110: 67 20 74 6f 20 74 68 65 20 53 51 4c 20 73 74 61  g to the SQL sta
d120: 6e 64 61 72 64 2c 20 50 52 49 4d 41 52 59 20 4b  ndard, PRIMARY K
d130: 45 59 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  EY should always
d140: 20 69 6d 70 6c 79 20 4e 4f 54 20 4e 55 4c 4c 2e   imply NOT NULL.
d150: 0a 20 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79  .  Unfortunately
d160: 2c 20 64 75 65 20 74 6f 20 61 20 62 75 67 20 69  , due to a bug i
d170: 6e 20 73 6f 6d 65 20 65 61 72 6c 79 20 76 65 72  n some early ver
d180: 73 69 6f 6e 73 2c 20 74 68 69 73 20 69 73 20 6e  sions, this is n
d190: 6f 74 20 74 68 65 0a 20 20 63 61 73 65 20 69 6e  ot the.  case in
d1a0: 20 53 51 4c 69 74 65 2e 20 5e 55 6e 6c 65 73 73   SQLite. ^Unless
d1b0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 61   the column is a
d1c0: 6e 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  n [INTEGER PRIMA
d1d0: 52 59 20 4b 45 59 5d 20 6f 72 0a 20 20 74 68 65  RY KEY] or.  the
d1e0: 20 74 61 62 6c 65 20 69 73 20 61 20 5b 57 49 54   table is a [WIT
d1f0: 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
d200: 65 20 6f 72 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e or the column 
d210: 69 73 20 64 65 63 6c 61 72 65 64 20 4e 4f 54 20  is declared NOT 
d220: 4e 55 4c 4c 2c 0a 20 20 53 51 4c 69 74 65 20 61  NULL,.  SQLite a
d230: 6c 6c 6f 77 73 20 4e 55 4c 4c 20 76 61 6c 75 65  llows NULL value
d240: 73 20 69 6e 20 61 20 50 52 49 4d 41 52 59 20 4b  s in a PRIMARY K
d250: 45 59 20 63 6f 6c 75 6d 6e 2e 20 20 53 51 4c 69  EY column.  SQLi
d260: 74 65 20 63 6f 75 6c 64 20 62 65 20 66 69 78 65  te could be fixe
d270: 64 20 74 6f 0a 20 20 63 6f 6e 66 6f 72 6d 20 74  d to.  conform t
d280: 6f 20 74 68 65 20 73 74 61 6e 64 61 72 64 2c 20  o the standard, 
d290: 62 75 74 20 64 6f 69 6e 67 20 73 6f 20 6d 69 67  but doing so mig
d2a0: 68 74 20 62 72 65 61 6b 20 6c 65 67 61 63 79 20  ht break legacy 
d2b0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 0a 20 20  applications..  
d2c0: 48 65 6e 63 65 2c 20 69 74 20 68 61 73 20 62 65  Hence, it has be
d2d0: 65 6e 20 64 65 63 69 64 65 64 20 74 6f 20 6d 65  en decided to me
d2e0: 72 65 6c 79 20 64 6f 63 75 6d 65 6e 74 20 74 68  rely document th
d2f0: 65 20 66 61 63 74 20 74 68 61 74 20 53 51 4c 69  e fact that SQLi
d300: 74 65 0a 20 20 61 6c 6c 6f 77 69 6e 67 20 4e 55  te.  allowing NU
d310: 4c 4c 73 20 69 6e 20 6d 6f 73 74 20 50 52 49 4d  LLs in most PRIM
d320: 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 73 2e  ARY KEY columns.
d330: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
d340: 6e 74 20 75 6e 69 71 75 65 63 6f 6e 73 74 20 7b  nt uniqueconst {
d350: 55 4e 49 51 55 45 7d 20 7b 75 6e 69 71 75 65 20  UNIQUE} {unique 
d360: 63 6f 6e 73 74 72 61 69 6e 74 7d 20 7b 55 4e 49  constraint} {UNI
d370: 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74 7d 3c  QUE constraint}<
d380: 2f 74 63 6c 3e 0a 3c 70 3e 5e 41 20 3c 62 3e 55  /tcl>.<p>^A <b>U
d390: 4e 49 51 55 45 3c 2f 62 3e 20 63 6f 6e 73 74 72  NIQUE</b> constr
d3a0: 61 69 6e 74 20 69 73 20 73 69 6d 69 6c 61 72 20  aint is similar 
d3b0: 74 6f 20 61 20 50 52 49 4d 41 52 59 20 4b 45 59  to a PRIMARY KEY
d3c0: 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 65 78 63   constraint, exc
d3d0: 65 70 74 0a 20 20 74 68 61 74 20 61 20 73 69 6e  ept.  that a sin
d3e0: 67 6c 65 20 74 61 62 6c 65 20 6d 61 79 20 68 61  gle table may ha
d3f0: 76 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ve any number of
d400: 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69   UNIQUE constrai
d410: 6e 74 73 2e 20 5e 46 6f 72 20 65 61 63 68 0a 20  nts. ^For each. 
d420: 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69   UNIQUE constrai
d430: 6e 74 20 6f 6e 20 74 68 65 20 74 61 62 6c 65 2c  nt on the table,
d440: 20 65 61 63 68 20 72 6f 77 20 6d 75 73 74 20 63   each row must c
d450: 6f 6e 74 61 69 6e 20 61 20 75 6e 69 71 75 65 20  ontain a unique 
d460: 63 6f 6d 62 69 6e 61 74 69 6f 6e 0a 20 20 6f 66  combination.  of
d470: 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
d480: 6f 6c 75 6d 6e 73 20 69 64 65 6e 74 69 66 69 65  olumns identifie
d490: 64 20 62 79 20 74 68 65 20 55 4e 49 51 55 45 20  d by the UNIQUE 
d4a0: 63 6f 6e 73 74 72 61 69 6e 74 2e 20 0a 20 20 5e  constraint. .  ^
d4b0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
d4c0: 20 6f 66 20 55 4e 49 51 55 45 20 63 6f 6e 73 74   of UNIQUE const
d4d0: 72 61 69 6e 74 73 2c 20 4e 55 4c 4c 20 76 61 6c  raints, NULL val
d4e0: 75 65 73 0a 20 20 61 72 65 20 63 6f 6e 73 69 64  ues.  are consid
d4f0: 65 72 65 64 20 64 69 73 74 69 6e 63 74 20 66 72  ered distinct fr
d500: 6f 6d 20 61 6c 6c 20 6f 74 68 65 72 20 76 61 6c  om all other val
d510: 75 65 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6f  ues, including o
d520: 74 68 65 72 20 4e 55 4c 4c 73 2e 0a 20 20 5e 41  ther NULLs..  ^A
d530: 73 20 77 69 74 68 20 50 52 49 4d 41 52 59 20 4b  s with PRIMARY K
d540: 45 59 73 2c 20 61 20 55 4e 49 51 55 45 20 5b 74  EYs, a UNIQUE [t
d550: 61 62 6c 65 2d 63 6f 6e 73 74 72 61 69 6e 74 5d  able-constraint]
d560: 20 63 6c 61 75 73 65 20 6d 75 73 74 20 63 6f 6e   clause must con
d570: 74 61 69 6e 0a 20 20 6f 6e 6c 79 20 63 6f 6c 75  tain.  only colu
d580: 6d 6e 20 6e 61 6d 65 73 20 26 6d 64 61 73 68 3b  mn names &mdash;
d590: 20 74 68 65 20 75 73 65 20 6f 66 20 0a 20 20 65   the use of .  e
d5a0: 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 61 6e  xpressions in an
d5b0: 20 5b 69 6e 64 65 78 65 64 2d 63 6f 6c 75 6d 6e   [indexed-column
d5c0: 5d 20 6f 66 20 61 20 55 4e 49 51 55 45 20 5b 74  ] of a UNIQUE [t
d5d0: 61 62 6c 65 2d 63 6f 6e 73 74 72 61 69 6e 74 5d  able-constraint]
d5e0: 0a 20 20 69 73 20 6e 6f 74 20 73 75 70 70 6f 72  .  is not suppor
d5f0: 74 65 64 2e 0a 20 20 0a 0a 3c 70 3e 5e 49 6e 20  ted..  ..<p>^In 
d600: 6d 6f 73 74 20 63 61 73 65 73 2c 20 55 4e 49 51  most cases, UNIQ
d610: 55 45 20 61 6e 64 20 50 52 49 4d 41 52 59 20 4b  UE and PRIMARY K
d620: 45 59 0a 20 20 63 6f 6e 73 74 72 61 69 6e 74 73  EY.  constraints
d630: 20 61 72 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   are implemented
d640: 20 62 79 20 63 72 65 61 74 69 6e 67 20 61 20 75   by creating a u
d650: 6e 69 71 75 65 20 69 6e 64 65 78 20 69 6e 20 74  nique index in t
d660: 68 65 20 64 61 74 61 62 61 73 65 2e 0a 20 20 28  he database..  (
d670: 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 61  The exceptions a
d680: 72 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  re [INTEGER PRIM
d690: 41 52 59 20 4b 45 59 5d 20 61 6e 64 20 50 52 49  ARY KEY] and PRI
d6a0: 4d 41 52 59 20 4b 45 59 73 20 6f 6e 20 0a 20 20  MARY KEYs on .  
d6b0: 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
d6c0: 74 61 62 6c 65 73 2e 29 0a 20 20 48 65 6e 63 65  tables.).  Hence
d6d0: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
d6e0: 73 63 68 65 6d 61 73 20 61 72 65 20 6c 6f 67 69  schemas are logi
d6f0: 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74  cally equivalent
d700: 3a 0a 0a 20 20 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e  :..  <ol>.  <li>
d710: 3c 70 3e 43 52 45 41 54 45 20 54 41 42 4c 45 20  <p>CREATE TABLE 
d720: 74 31 28 61 2c 20 62 20 55 4e 49 51 55 45 29 3b  t1(a, b UNIQUE);
d730: 0a 20 20 3c 6c 69 3e 3c 70 3e 43 52 45 41 54 45  .  <li><p>CREATE
d740: 20 54 41 42 4c 45 20 74 31 28 61 2c 20 62 20 50   TABLE t1(a, b P
d750: 52 49 4d 41 52 59 20 4b 45 59 29 3b 0a 20 20 3c  RIMARY KEY);.  <
d760: 6c 69 3e 3c 70 3e 43 52 45 41 54 45 20 54 41 42  li><p>CREATE TAB
d770: 4c 45 20 74 31 28 61 2c 20 62 29 3b 3c 62 72 3e  LE t1(a, b);<br>
d780: 0a 20 20 20 20 20 20 20 20 20 43 52 45 41 54 45  .         CREATE
d790: 20 55 4e 49 51 55 45 20 49 4e 44 45 58 20 74 31   UNIQUE INDEX t1
d7a0: 62 20 4f 4e 20 74 31 28 62 29 3b 0a 20 20 3c 2f  b ON t1(b);.  </
d7b0: 6f 6c 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ol>..<tcl>hd_fra
d7c0: 67 6d 65 6e 74 20 7b 63 6b 63 6f 6e 73 74 7d 20  gment {ckconst} 
d7d0: 7b 43 48 45 43 4b 7d 20 7b 43 48 45 43 4b 20 63  {CHECK} {CHECK c
d7e0: 6f 6e 73 74 72 61 69 6e 74 7d 20 7b 43 48 45 43  onstraint} {CHEC
d7f0: 4b 20 63 6f 6e 73 74 72 61 69 6e 74 73 7d 3c 2f  K constraints}</
d800: 74 63 6c 3e 0a 3c 70 3e 5e 28 41 20 3c 62 3e 43  tcl>.<p>^(A <b>C
d810: 48 45 43 4b 3c 2f 62 3e 20 63 6f 6e 73 74 72 61  HECK</b> constra
d820: 69 6e 74 20 6d 61 79 20 62 65 20 61 74 74 61 63  int may be attac
d830: 68 65 64 20 74 6f 20 61 20 63 6f 6c 75 6d 6e 20  hed to a column 
d840: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 0a 20 20  definition or.  
d850: 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 74  specified as a t
d860: 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e 74 2e  able constraint.
d870: 20 49 6e 20 70 72 61 63 74 69 63 65 20 69 74 20   In practice it 
d880: 6d 61 6b 65 73 20 6e 6f 20 64 69 66 66 65 72 65  makes no differe
d890: 6e 63 65 2e 29 5e 20 5e 28 45 61 63 68 0a 20 20  nce.)^ ^(Each.  
d8a0: 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 69  time a new row i
d8b0: 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  s inserted into 
d8c0: 74 68 65 20 74 61 62 6c 65 20 6f 72 20 61 6e 20  the table or an 
d8d0: 65 78 69 73 74 69 6e 67 20 72 6f 77 20 69 73 20  existing row is 
d8e0: 75 70 64 61 74 65 64 2c 0a 20 20 74 68 65 20 65  updated,.  the e
d8f0: 78 70 72 65 73 73 69 6f 6e 20 61 73 73 6f 63 69  xpression associ
d900: 61 74 65 64 20 77 69 74 68 20 65 61 63 68 20 43  ated with each C
d910: 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e 74 20  HECK constraint 
d920: 69 73 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  is evaluated and
d930: 0a 20 20 63 61 73 74 20 74 6f 20 61 20 4e 55 4d  .  cast to a NUM
d940: 45 52 49 43 20 76 61 6c 75 65 20 69 6e 20 74 68  ERIC value in th
d950: 65 20 73 61 6d 65 20 77 61 79 20 61 73 20 61 20  e same way as a 
d960: 5b 43 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e  [CAST expression
d970: 5d 2e 20 49 66 20 74 68 65 20 0a 20 20 72 65 73  ]. If the .  res
d980: 75 6c 74 20 69 73 20 7a 65 72 6f 20 28 69 6e 74  ult is zero (int
d990: 65 67 65 72 20 76 61 6c 75 65 20 30 20 6f 72 20  eger value 0 or 
d9a0: 72 65 61 6c 20 76 61 6c 75 65 20 30 2e 30 29 2c  real value 0.0),
d9b0: 20 74 68 65 6e 20 61 20 63 6f 6e 73 74 72 61 69   then a constrai
d9c0: 6e 74 0a 20 20 76 69 6f 6c 61 74 69 6f 6e 20 68  nt.  violation h
d9d0: 61 73 20 6f 63 63 75 72 72 65 64 2e 29 5e 20 5e  as occurred.)^ ^
d9e0: 49 66 20 74 68 65 20 43 48 45 43 4b 20 65 78 70  If the CHECK exp
d9f0: 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74 65  ression evaluate
da00: 73 20 74 6f 20 4e 55 4c 4c 2c 20 6f 72 0a 20 20  s to NULL, or.  
da10: 61 6e 79 20 6f 74 68 65 72 20 6e 6f 6e 2d 7a 65  any other non-ze
da20: 72 6f 20 76 61 6c 75 65 2c 20 69 74 20 69 73 20  ro value, it is 
da30: 6e 6f 74 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  not a constraint
da40: 20 76 69 6f 6c 61 74 69 6f 6e 2e 0a 20 20 5e 54   violation..  ^T
da50: 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 66  he expression of
da60: 20 61 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61   a CHECK constra
da70: 69 6e 74 20 6d 61 79 20 6e 6f 74 20 63 6f 6e 74  int may not cont
da80: 61 69 6e 20 61 20 73 75 62 71 75 65 72 79 2e 0a  ain a subquery..
da90: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
daa0: 74 20 7b 6e 6f 74 6e 75 6c 6c 63 6f 6e 73 74 7d  t {notnullconst}
dab0: 20 7b 4e 4f 54 20 4e 55 4c 4c 7d 20 7b 4e 4f 54   {NOT NULL} {NOT
dac0: 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
dad0: 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 5e 41 20 3c 62  }</tcl>.<p>^A <b
dae0: 3e 4e 4f 54 20 4e 55 4c 4c 3c 2f 62 3e 20 63 6f  >NOT NULL</b> co
daf0: 6e 73 74 72 61 69 6e 74 20 6d 61 79 20 6f 6e 6c  nstraint may onl
db00: 79 20 62 65 20 61 74 74 61 63 68 65 64 20 74 6f  y be attached to
db10: 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69   a column defini
db20: 74 69 6f 6e 2c 0a 20 20 6e 6f 74 20 73 70 65 63  tion,.  not spec
db30: 69 66 69 65 64 20 61 73 20 61 20 74 61 62 6c 65  ified as a table
db40: 20 63 6f 6e 73 74 72 61 69 6e 74 2e 20 20 4e 6f   constraint.  No
db50: 74 20 73 75 72 70 72 69 73 69 6e 67 6c 79 2c 20  t surprisingly, 
db60: 5e 28 61 20 4e 4f 54 20 4e 55 4c 4c 0a 20 20 63  ^(a NOT NULL.  c
db70: 6f 6e 73 74 72 61 69 6e 74 20 64 69 63 74 61 74  onstraint dictat
db80: 65 73 20 74 68 61 74 20 74 68 65 20 61 73 73 6f  es that the asso
db90: 63 69 61 74 65 64 20 63 6f 6c 75 6d 6e 20 6d 61  ciated column ma
dba0: 79 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20  y not contain a 
dbb0: 4e 55 4c 4c 20 76 61 6c 75 65 2e 0a 20 20 41 74  NULL value..  At
dbc0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
dbd0: 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  the column value
dbe0: 20 74 6f 20 4e 55 4c 4c 20 77 68 65 6e 20 69 6e   to NULL when in
dbf0: 73 65 72 74 69 6e 67 20 61 20 6e 65 77 20 72 6f  serting a new ro
dc00: 77 20 6f 72 0a 20 20 75 70 64 61 74 69 6e 67 20  w or.  updating 
dc10: 61 6e 20 65 78 69 73 74 69 6e 67 20 6f 6e 65 20  an existing one 
dc20: 63 61 75 73 65 73 20 61 20 63 6f 6e 73 74 72 61  causes a constra
dc30: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2e 29 5e  int violation.)^
dc40: 0a 0a 3c 70 3e 45 78 61 63 74 6c 79 20 68 6f 77  ..<p>Exactly how
dc50: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
dc60: 6f 6c 61 74 69 6f 6e 20 69 73 20 64 65 61 6c 74  olation is dealt
dc70: 20 77 69 74 68 20 69 73 20 64 65 74 65 72 6d 69   with is determi
dc80: 6e 65 64 20 62 79 20 74 68 65 0a 20 20 5b 63 6f  ned by the.  [co
dc90: 6e 66 6c 69 63 74 20 63 6c 61 75 73 65 7c 63 6f  nflict clause|co
dca0: 6e 73 74 72 61 69 6e 74 20 63 6f 6e 66 6c 69 63  nstraint conflic
dcb0: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67  t resolution alg
dcc0: 6f 72 69 74 68 6d 5d 2e 20 45 61 63 68 20 0a 20  orithm]. Each . 
dcd0: 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 55 4e   PRIMARY KEY, UN
dce0: 49 51 55 45 2c 20 4e 4f 54 20 4e 55 4c 4c 20 61  IQUE, NOT NULL a
dcf0: 6e 64 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61  nd CHECK constra
dd00: 69 6e 74 20 68 61 73 20 61 20 64 65 66 61 75 6c  int has a defaul
dd10: 74 20 63 6f 6e 66 6c 69 63 74 0a 20 20 72 65 73  t conflict.  res
dd20: 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  olution algorith
dd30: 6d 2e 20 5e 50 52 49 4d 41 52 59 20 4b 45 59 2c  m. ^PRIMARY KEY,
dd40: 20 55 4e 49 51 55 45 20 61 6e 64 20 4e 4f 54 20   UNIQUE and NOT 
dd50: 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 73  NULL constraints
dd60: 20 6d 61 79 20 62 65 0a 20 20 65 78 70 6c 69 63   may be.  explic
dd70: 69 74 6c 79 20 61 73 73 69 67 6e 65 64 20 61 20  itly assigned a 
dd80: 64 65 66 61 75 6c 74 20 63 6f 6e 66 6c 69 63 74  default conflict
dd90: 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f   resolution algo
dda0: 72 69 74 68 6d 20 62 79 20 69 6e 63 6c 75 64 69  rithm by includi
ddb0: 6e 67 0a 20 20 61 20 5b 63 6f 6e 66 6c 69 63 74  ng.  a [conflict
ddc0: 2d 63 6c 61 75 73 65 5d 20 69 6e 20 74 68 65 69  -clause] in thei
ddd0: 72 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 5e  r definitions. ^
dde0: 4f 72 2c 20 69 66 20 61 20 63 6f 6e 73 74 72 61  Or, if a constra
ddf0: 69 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 0a 20  int definition. 
de00: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
de10: 65 20 61 20 5b 63 6f 6e 66 6c 69 63 74 2d 63 6c  e a [conflict-cl
de20: 61 75 73 65 5d 20 6f 72 20 69 74 20 69 73 20 61  ause] or it is a
de30: 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61 69 6e   CHECK constrain
de40: 74 2c 20 74 68 65 20 64 65 66 61 75 6c 74 0a 20  t, the default. 
de50: 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75   conflict resolu
de60: 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 69  tion algorithm i
de70: 73 20 41 42 4f 52 54 2e 20 5e 44 69 66 66 65 72  s ABORT. ^Differ
de80: 65 6e 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ent constraints 
de90: 77 69 74 68 69 6e 20 74 68 65 0a 20 20 73 61 6d  within the.  sam
dea0: 65 20 74 61 62 6c 65 20 6d 61 79 20 68 61 76 65  e table may have
deb0: 20 64 69 66 66 65 72 65 6e 74 20 64 65 66 61 75   different defau
dec0: 6c 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  lt conflict reso
ded0: 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d  lution algorithm
dee0: 73 2e 20 53 65 65 0a 20 20 74 68 65 20 73 65 63  s. See.  the sec
def0: 74 69 6f 6e 20 74 69 74 6c 65 64 20 5b 4f 4e 20  tion titled [ON 
df00: 43 4f 4e 46 4c 49 43 54 5d 20 66 6f 72 20 61 64  CONFLICT] for ad
df10: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
df20: 74 69 6f 6e 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  tion...<tcl>hd_f
df30: 72 61 67 6d 65 6e 74 20 72 6f 77 69 64 20 7b 49  ragment rowid {I
df40: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
df50: 45 59 7d 20 52 4f 57 49 44 20 72 6f 77 69 64 3c  EY} ROWID rowid<
df60: 2f 74 63 6c 3e 0a 3c 68 33 3e 52 4f 57 49 44 73  /tcl>.<h3>ROWIDs
df70: 20 61 6e 64 20 74 68 65 20 49 4e 54 45 47 45 52   and the INTEGER
df80: 20 50 52 49 4d 41 52 59 20 4b 45 59 3c 2f 68 33   PRIMARY KEY</h3
df90: 3e 0a 0a 3c 70 3e 5e 45 78 63 65 70 74 20 66 6f  >..<p>^Except fo
dfa0: 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
dfb0: 5d 20 74 61 62 6c 65 73 2c 20 61 6c 6c 20 72 6f  ] tables, all ro
dfc0: 77 73 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  ws within SQLite
dfd0: 20 74 61 62 6c 65 73 0a 68 61 76 65 20 61 20 36   tables.have a 6
dfe0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
dff0: 65 67 65 72 20 6b 65 79 20 74 68 61 74 20 75 6e  eger key that un
e000: 69 71 75 65 6c 79 20 69 64 65 6e 74 69 66 69 65  iquely identifie
e010: 73 20 74 68 65 20 72 6f 77 20 77 69 74 68 69 6e  s the row within
e020: 20 69 74 73 20 74 61 62 6c 65 2e 0a 54 68 69 73   its table..This
e030: 20 69 6e 74 65 67 65 72 20 69 73 20 75 73 75 61   integer is usua
e040: 6c 6c 79 0a 63 61 6c 6c 65 64 20 74 68 65 20 22  lly.called the "
e050: 72 6f 77 69 64 22 2e 20 5e 54 68 65 20 72 6f 77  rowid". ^The row
e060: 69 64 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20  id value can be 
e070: 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 6f  accessed using o
e080: 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  ne of the specia
e090: 6c 0a 63 61 73 65 2d 69 6e 64 65 70 65 6e 64 65  l.case-independe
e0a0: 6e 74 20 6e 61 6d 65 73 20 22 72 6f 77 69 64 22  nt names "rowid"
e0b0: 2c 20 22 6f 69 64 22 2c 20 6f 72 20 22 5f 72 6f  , "oid", or "_ro
e0c0: 77 69 64 5f 22 20 69 6e 20 70 6c 61 63 65 20 6f  wid_" in place o
e0d0: 66 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  f a column name.
e0e0: 0a 5e 49 66 20 61 20 74 61 62 6c 65 20 63 6f 6e  .^If a table con
e0f0: 74 61 69 6e 73 20 61 20 75 73 65 72 20 64 65 66  tains a user def
e100: 69 6e 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ined column name
e110: 64 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  d "rowid", "oid"
e120: 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 2c 0a 74   or "_rowid_",.t
e130: 68 65 6e 20 74 68 61 74 20 6e 61 6d 65 20 61 6c  hen that name al
e140: 77 61 79 73 20 72 65 66 65 72 73 20 74 68 65 20  ways refers the 
e150: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
e160: 72 65 64 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 63  red column and c
e170: 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 0a 74 6f  annot be used.to
e180: 20 72 65 74 72 69 65 76 65 20 74 68 65 20 69 6e   retrieve the in
e190: 74 65 67 65 72 20 72 6f 77 69 64 20 76 61 6c 75  teger rowid valu
e1a0: 65 2e 0a 0a 3c 70 3e 54 68 65 20 72 6f 77 69 64  e...<p>The rowid
e1b0: 20 28 61 6e 64 20 22 6f 69 64 22 20 61 6e 64 20   (and "oid" and 
e1c0: 22 5f 72 6f 77 69 64 5f 22 29 20 69 73 20 6f 6d  "_rowid_") is om
e1d0: 69 74 74 65 64 20 69 6e 20 5b 57 49 54 48 4f 55  itted in [WITHOU
e1e0: 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 2e  T ROWID] tables.
e1f0: 0a 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 74  .WITHOUT ROWID t
e200: 61 62 6c 65 73 20 61 72 65 20 6f 6e 6c 79 20 61  ables are only a
e210: 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69  vailable in SQLi
e220: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 38 2e  te [version 3.8.
e230: 32 5d 0a 28 5b 64 61 74 65 6f 66 3a 33 2e 38 2e  2].([dateof:3.8.
e240: 32 5d 29 20 61 6e 64 20 6c 61 74 65 72 2e 0a 41  2]) and later..A
e250: 20 74 61 62 6c 65 20 74 68 61 74 20 6c 61 63 6b   table that lack
e260: 73 20 74 68 65 20 57 49 54 48 4f 55 54 20 52 4f  s the WITHOUT RO
e270: 57 49 44 20 63 6c 61 75 73 65 20 69 73 20 63 61  WID clause is ca
e280: 6c 6c 65 64 20 61 20 22 72 6f 77 69 64 20 74 61  lled a "rowid ta
e290: 62 6c 65 22 2e 0a 0a 3c 70 3e 54 68 65 20 64 61  ble"...<p>The da
e2a0: 74 61 20 66 6f 72 20 72 6f 77 69 64 20 74 61 62  ta for rowid tab
e2b0: 6c 65 73 20 69 73 20 73 74 6f 72 65 64 20 61 73  les is stored as
e2c0: 20 61 20 42 2d 54 72 65 65 20 73 74 72 75 63 74   a B-Tree struct
e2d0: 75 72 65 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 6f  ure containing.o
e2e0: 6e 65 20 65 6e 74 72 79 20 66 6f 72 20 65 61 63  ne entry for eac
e2f0: 68 20 74 61 62 6c 65 20 72 6f 77 2c 20 75 73 69  h table row, usi
e300: 6e 67 20 74 68 65 20 72 6f 77 69 64 20 76 61 6c  ng the rowid val
e310: 75 65 20 61 73 20 74 68 65 20 6b 65 79 2e 20 54  ue as the key. T
e320: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 0a 72  his means that.r
e330: 65 74 72 69 65 76 69 6e 67 20 6f 72 20 73 6f 72  etrieving or sor
e340: 74 69 6e 67 20 72 65 63 6f 72 64 73 20 62 79 20  ting records by 
e350: 72 6f 77 69 64 20 69 73 20 66 61 73 74 2e 20 53  rowid is fast. S
e360: 65 61 72 63 68 69 6e 67 20 66 6f 72 20 61 20 72  earching for a r
e370: 65 63 6f 72 64 20 77 69 74 68 20 61 0a 73 70 65  ecord with a.spe
e380: 63 69 66 69 63 20 72 6f 77 69 64 2c 20 6f 72 20  cific rowid, or 
e390: 66 6f 72 20 61 6c 6c 20 72 65 63 6f 72 64 73 20  for all records 
e3a0: 77 69 74 68 20 72 6f 77 69 64 73 20 77 69 74 68  with rowids with
e3b0: 69 6e 20 61 20 73 70 65 63 69 66 69 65 64 20 72  in a specified r
e3c0: 61 6e 67 65 20 69 73 0a 61 72 6f 75 6e 64 20 74  ange is.around t
e3d0: 77 69 63 65 20 61 73 20 66 61 73 74 20 61 73 20  wice as fast as 
e3e0: 61 20 73 69 6d 69 6c 61 72 20 73 65 61 72 63 68  a similar search
e3f0: 20 6d 61 64 65 20 62 79 20 73 70 65 63 69 66 79   made by specify
e400: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 50 52  ing any other PR
e410: 49 4d 41 52 59 0a 4b 45 59 20 6f 72 20 69 6e 64  IMARY.KEY or ind
e420: 65 78 65 64 20 76 61 6c 75 65 2e 0a 0a 3c 70 3e  exed value...<p>
e430: 20 5e 57 69 74 68 20 6f 6e 65 20 65 78 63 65 70   ^With one excep
e440: 74 69 6f 6e 20 6e 6f 74 65 64 20 62 65 6c 6f 77  tion noted below
e450: 2c 20 69 66 20 61 20 72 6f 77 69 64 20 74 61 62  , if a rowid tab
e460: 6c 65 20 68 61 73 20 61 20 70 72 69 6d 61 72 79  le has a primary
e470: 20 6b 65 79 20 74 68 61 74 20 63 6f 6e 73 69 73   key that consis
e480: 74 73 0a 6f 66 20 61 20 73 69 6e 67 6c 65 20 63  ts.of a single c
e490: 6f 6c 75 6d 6e 20 61 6e 64 20 74 68 65 20 64 65  olumn and the de
e4a0: 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
e4b0: 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 22 49  hat column is "I
e4c0: 4e 54 45 47 45 52 22 20 69 6e 20 61 6e 79 20 6d  NTEGER" in any m
e4d0: 69 78 74 75 72 65 20 6f 66 0a 75 70 70 65 72 20  ixture of.upper 
e4e0: 61 6e 64 20 6c 6f 77 65 72 20 63 61 73 65 2c 20  and lower case, 
e4f0: 74 68 65 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  then the column 
e500: 62 65 63 6f 6d 65 73 20 61 6e 20 61 6c 69 61 73  becomes an alias
e510: 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 20   for the rowid. 
e520: 53 75 63 68 20 61 0a 63 6f 6c 75 6d 6e 20 69 73  Such a.column is
e530: 20 75 73 75 61 6c 6c 79 20 72 65 66 65 72 72 65   usually referre
e540: 64 20 74 6f 20 61 73 20 61 6e 20 22 69 6e 74 65  d to as an "inte
e550: 67 65 72 20 70 72 69 6d 61 72 79 20 6b 65 79 22  ger primary key"
e560: 2e 20 41 20 50 52 49 4d 41 52 59 20 4b 45 59 20  . A PRIMARY KEY 
e570: 63 6f 6c 75 6d 6e 0a 6f 6e 6c 79 20 62 65 63 6f  column.only beco
e580: 6d 65 73 20 61 6e 20 69 6e 74 65 67 65 72 20 70  mes an integer p
e590: 72 69 6d 61 72 79 20 6b 65 79 20 69 66 20 74 68  rimary key if th
e5a0: 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
e5b0: 6e 61 6d 65 20 69 73 20 65 78 61 63 74 6c 79 0a  name is exactly.
e5c0: 22 49 4e 54 45 47 45 52 22 2e 20 20 5e 4f 74 68  "INTEGER".  ^Oth
e5d0: 65 72 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  er integer type 
e5e0: 6e 61 6d 65 73 20 6c 69 6b 65 20 22 49 4e 54 22  names like "INT"
e5f0: 20 6f 72 20 22 42 49 47 49 4e 54 22 20 6f 72 20   or "BIGINT" or 
e600: 22 53 48 4f 52 54 20 49 4e 54 45 47 45 52 22 0a  "SHORT INTEGER".
e610: 6f 72 20 22 55 4e 53 49 47 4e 45 44 20 49 4e 54  or "UNSIGNED INT
e620: 45 47 45 52 22 20 63 61 75 73 65 73 20 74 68 65  EGER" causes the
e630: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 63 6f 6c   primary key col
e640: 75 6d 6e 20 74 6f 20 62 65 68 61 76 65 20 61 73  umn to behave as
e650: 20 61 6e 20 6f 72 64 69 6e 61 72 79 0a 74 61 62   an ordinary.tab
e660: 6c 65 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20 69  le column with i
e670: 6e 74 65 67 65 72 20 5b 61 66 66 69 6e 69 74 79  nteger [affinity
e680: 5d 20 61 6e 64 20 61 20 75 6e 69 71 75 65 20 69  ] and a unique i
e690: 6e 64 65 78 2c 20 6e 6f 74 20 61 73 20 61 6e 20  ndex, not as an 
e6a0: 61 6c 69 61 73 20 66 6f 72 0a 74 68 65 20 72 6f  alias for.the ro
e6b0: 77 69 64 2e 0a 0a 3c 70 3e 20 54 68 65 20 65 78  wid...<p> The ex
e6c0: 63 65 70 74 69 6f 6e 20 6d 65 6e 74 69 6f 6e 65  ception mentione
e6d0: 64 20 61 62 6f 76 65 20 69 73 20 74 68 61 74 20  d above is that 
e6e0: 5e 69 66 20 74 68 65 20 64 65 63 6c 61 72 61 74  ^if the declarat
e6f0: 69 6f 6e 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20  ion of a column 
e700: 77 69 74 68 0a 64 65 63 6c 61 72 65 64 20 74 79  with.declared ty
e710: 70 65 20 22 49 4e 54 45 47 45 52 22 20 69 6e 63  pe "INTEGER" inc
e720: 6c 75 64 65 73 20 61 6e 20 22 50 52 49 4d 41 52  ludes an "PRIMAR
e730: 59 20 4b 45 59 20 44 45 53 43 22 20 63 6c 61 75  Y KEY DESC" clau
e740: 73 65 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 0a  se, it does not.
e750: 62 65 63 6f 6d 65 20 61 6e 20 61 6c 69 61 73 20  become an alias 
e760: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 20 61 6e  for the rowid an
e770: 64 20 69 73 20 6e 6f 74 20 63 6c 61 73 73 69 66  d is not classif
e780: 69 65 64 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ied as an intege
e790: 72 20 70 72 69 6d 61 72 79 20 6b 65 79 2e 0a 54  r primary key..T
e7a0: 68 69 73 20 71 75 69 72 6b 20 69 73 20 6e 6f 74  his quirk is not
e7b0: 20 62 79 20 64 65 73 69 67 6e 2e 20 49 74 20 69   by design. It i
e7c0: 73 20 64 75 65 20 74 6f 20 61 20 62 75 67 20 69  s due to a bug i
e7d0: 6e 20 65 61 72 6c 79 20 76 65 72 73 69 6f 6e 73  n early versions
e7e0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 42 75 74 20   of SQLite..But 
e7f0: 66 69 78 69 6e 67 20 74 68 65 20 62 75 67 20 63  fixing the bug c
e800: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 62  ould result in b
e810: 61 63 6b 77 61 72 64 73 20 69 6e 63 6f 6d 70 61  ackwards incompa
e820: 74 69 62 69 6c 69 74 69 65 73 2e 0a 48 65 6e 63  tibilities..Henc
e830: 65 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  e, the original 
e840: 62 65 68 61 76 69 6f 72 20 68 61 73 20 62 65 65  behavior has bee
e850: 6e 20 72 65 74 61 69 6e 65 64 20 28 61 6e 64 20  n retained (and 
e860: 64 6f 63 75 6d 65 6e 74 65 64 29 20 62 65 63 61  documented) beca
e870: 75 73 65 20 6f 64 64 0a 62 65 68 61 76 69 6f 72  use odd.behavior
e880: 20 69 6e 20 61 20 63 6f 72 6e 65 72 20 63 61 73   in a corner cas
e890: 65 20 69 73 20 66 61 72 20 62 65 74 74 65 72 20  e is far better 
e8a0: 74 68 61 6e 20 61 20 63 6f 6d 70 61 74 69 62 69  than a compatibi
e8b0: 6c 69 74 79 20 62 72 65 61 6b 2e 20 20 54 68 69  lity break.  Thi
e8c0: 73 20 6d 65 61 6e 73 0a 74 68 61 74 20 5e 28 74  s means.that ^(t
e8d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
e8e0: 65 65 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  ee table declara
e8f0: 74 69 6f 6e 73 20 61 6c 6c 20 63 61 75 73 65 20  tions all cause 
e900: 74 68 65 20 63 6f 6c 75 6d 6e 20 22 78 22 20 74  the column "x" t
e910: 6f 20 62 65 20 61 6e 0a 61 6c 69 61 73 20 66 6f  o be an.alias fo
e920: 72 20 74 68 65 20 72 6f 77 69 64 20 28 61 6e 20  r the rowid (an 
e930: 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79 20  integer primary 
e940: 6b 65 79 29 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  key):..<ul>.<li>
e950: 3c 74 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45  <tt>CREATE TABLE
e960: 20 74 28 78 20 49 4e 54 45 47 45 52 20 50 52 49   t(x INTEGER PRI
e970: 4d 41 52 59 20 4b 45 59 20 41 53 43 2c 20 79 2c  MARY KEY ASC, y,
e980: 20 7a 29 3b 3c 2f 74 74 3e 0a 3c 6c 69 3e 3c 74   z);</tt>.<li><t
e990: 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  t>CREATE TABLE t
e9a0: 28 78 20 49 4e 54 45 47 45 52 2c 20 79 2c 20 7a  (x INTEGER, y, z
e9b0: 2c 20 50 52 49 4d 41 52 59 20 4b 45 59 28 78 20  , PRIMARY KEY(x 
e9c0: 41 53 43 29 29 3b 3c 2f 74 74 3e 0a 3c 6c 69 3e  ASC));</tt>.<li>
e9d0: 3c 74 74 3e 43 52 45 41 54 45 20 54 41 42 4c 45  <tt>CREATE TABLE
e9e0: 20 74 28 78 20 49 4e 54 45 47 45 52 2c 20 79 2c   t(x INTEGER, y,
e9f0: 20 7a 2c 20 50 52 49 4d 41 52 59 20 4b 45 59 28   z, PRIMARY KEY(
ea00: 78 20 44 45 53 43 29 29 3b 3c 2f 74 74 3e 0a 3c  x DESC));</tt>.<
ea10: 2f 75 6c 3e 29 5e 0a 0a 3c 70 3e 42 75 74 20 5e  /ul>)^..<p>But ^
ea20: 28 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64  (the following d
ea30: 65 63 6c 61 72 61 74 69 6f 6e 20 64 6f 65 73 20  eclaration does 
ea40: 6e 6f 74 20 72 65 73 75 6c 74 20 69 6e 20 22 78  not result in "x
ea50: 22 20 62 65 69 6e 67 20 61 6e 20 61 6c 69 61 73  " being an alias
ea60: 20 66 6f 72 0a 74 68 65 20 72 6f 77 69 64 3a 0a   for.the rowid:.
ea70: 3c 75 6c 3e 0a 3c 6c 69 3e 3c 74 74 3e 43 52 45  <ul>.<li><tt>CRE
ea80: 41 54 45 20 54 41 42 4c 45 20 74 28 78 20 49 4e  ATE TABLE t(x IN
ea90: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
eaa0: 59 20 44 45 53 43 2c 20 79 2c 20 7a 29 3b 3c 2f  Y DESC, y, z);</
eab0: 74 74 3e 0a 3c 2f 75 6c 3e 29 5e 0a 0a 3c 70 3e  tt>.</ul>)^..<p>
eac0: 5e 52 6f 77 69 64 20 76 61 6c 75 65 73 20 6d 61  ^Rowid values ma
ead0: 79 20 62 65 20 6d 6f 64 69 66 69 65 64 20 75 73  y be modified us
eae0: 69 6e 67 20 61 6e 20 55 50 44 41 54 45 20 73 74  ing an UPDATE st
eaf0: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 73  atement in the s
eb00: 61 6d 65 0a 77 61 79 20 61 73 20 61 6e 79 20 6f  ame.way as any o
eb10: 74 68 65 72 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ther column valu
eb20: 65 20 63 61 6e 2c 20 65 69 74 68 65 72 20 75 73  e can, either us
eb30: 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 62  ing one of the b
eb40: 75 69 6c 74 2d 69 6e 20 61 6c 69 61 73 65 73 0a  uilt-in aliases.
eb50: 28 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20  ("rowid", "oid" 
eb60: 6f 72 20 22 5f 72 6f 77 69 64 5f 22 29 20 6f 72  or "_rowid_") or
eb70: 20 62 79 20 75 73 69 6e 67 20 61 6e 20 61 6c 69   by using an ali
eb80: 61 73 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  as created by an
eb90: 20 69 6e 74 65 67 65 72 0a 70 72 69 6d 61 72 79   integer.primary
eba0: 20 6b 65 79 2e 20 5e 53 69 6d 69 6c 61 72 6c 79   key. ^Similarly
ebb0: 2c 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74  , an INSERT stat
ebc0: 65 6d 65 6e 74 20 6d 61 79 20 70 72 6f 76 69 64  ement may provid
ebd0: 65 20 61 20 76 61 6c 75 65 20 74 6f 20 75 73 65  e a value to use
ebe0: 20 61 73 20 74 68 65 0a 72 6f 77 69 64 20 66 6f   as the.rowid fo
ebf0: 72 20 65 61 63 68 20 72 6f 77 20 69 6e 73 65 72  r each row inser
ec00: 74 65 64 2e 20 5e 28 55 6e 6c 69 6b 65 20 6e 6f  ted. ^(Unlike no
ec10: 72 6d 61 6c 20 53 51 4c 69 74 65 20 63 6f 6c 75  rmal SQLite colu
ec20: 6d 6e 73 2c 20 61 6e 20 69 6e 74 65 67 65 72 20  mns, an integer 
ec30: 70 72 69 6d 61 72 79 0a 6b 65 79 20 6f 72 20 72  primary.key or r
ec40: 6f 77 69 64 20 63 6f 6c 75 6d 6e 20 6d 75 73 74  owid column must
ec50: 20 63 6f 6e 74 61 69 6e 20 69 6e 74 65 67 65 72   contain integer
ec60: 20 76 61 6c 75 65 73 2e 20 49 6e 74 65 67 65 72   values. Integer
ec70: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 6f 72 20   primary key or 
ec80: 72 6f 77 69 64 0a 63 6f 6c 75 6d 6e 73 20 61 72  rowid.columns ar
ec90: 65 20 6e 6f 74 20 61 62 6c 65 20 74 6f 20 68 6f  e not able to ho
eca0: 6c 64 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ld floating poin
ecb0: 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
ecc0: 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
ecd0: 4c 73 2e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 61 6e  Ls.)^..<p>^If an
ece0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
ecf0: 74 20 61 74 74 65 6d 70 74 73 20 74 6f 20 73 65  t attempts to se
ed00: 74 20 61 6e 20 69 6e 74 65 67 65 72 20 70 72 69  t an integer pri
ed10: 6d 61 72 79 20 6b 65 79 20 6f 72 20 72 6f 77 69  mary key or rowi
ed20: 64 20 63 6f 6c 75 6d 6e 0a 74 6f 20 61 20 4e 55  d column.to a NU
ed30: 4c 4c 20 6f 72 20 62 6c 6f 62 20 76 61 6c 75 65  LL or blob value
ed40: 2c 20 6f 72 20 74 6f 20 61 20 73 74 72 69 6e 67  , or to a string
ed50: 20 6f 72 20 72 65 61 6c 20 76 61 6c 75 65 20 74   or real value t
ed60: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 6c 6f  hat cannot be lo
ed70: 73 73 6c 65 73 73 6c 79 0a 63 6f 6e 76 65 72 74  sslessly.convert
ed80: 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ed to an integer
ed90: 2c 20 61 20 22 64 61 74 61 74 79 70 65 20 6d 69  , a "datatype mi
eda0: 73 6d 61 74 63 68 22 20 65 72 72 6f 72 20 6f 63  smatch" error oc
edb0: 63 75 72 73 20 61 6e 64 20 74 68 65 20 73 74 61  curs and the sta
edc0: 74 65 6d 65 6e 74 0a 69 73 20 61 62 6f 72 74 65  tement.is aborte
edd0: 64 2e 20 5e 49 66 20 61 6e 20 49 4e 53 45 52 54  d. ^If an INSERT
ede0: 20 73 74 61 74 65 6d 65 6e 74 20 61 74 74 65 6d   statement attem
edf0: 70 74 73 20 74 6f 20 69 6e 73 65 72 74 20 61 20  pts to insert a 
ee00: 62 6c 6f 62 20 76 61 6c 75 65 2c 20 6f 72 20 61  blob value, or a
ee10: 20 73 74 72 69 6e 67 0a 6f 72 20 72 65 61 6c 20   string.or real 
ee20: 76 61 6c 75 65 20 74 68 61 74 20 63 61 6e 6e 6f  value that canno
ee30: 74 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 20  t be losslessly 
ee40: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20  converted to an 
ee50: 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 61 6e 0a  integer into an.
ee60: 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72 79 20  integer primary 
ee70: 6b 65 79 20 6f 72 20 72 6f 77 69 64 20 63 6f 6c  key or rowid col
ee80: 75 6d 6e 2c 20 61 20 22 64 61 74 61 74 79 70 65  umn, a "datatype
ee90: 20 6d 69 73 6d 61 74 63 68 22 20 65 72 72 6f 72   mismatch" error
eea0: 20 6f 63 63 75 72 73 20 61 6e 64 20 74 68 65 0a   occurs and the.
eeb0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 62 6f  statement is abo
eec0: 72 74 65 64 2e 0a 0a 3c 70 3e 5e 49 66 20 61 6e  rted...<p>^If an
eed0: 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e   INSERT statemen
eee0: 74 20 61 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  t attempts to in
eef0: 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
ef00: 65 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 6f  e into a rowid o
ef10: 72 0a 69 6e 74 65 67 65 72 20 70 72 69 6d 61 72  r.integer primar
ef20: 79 20 6b 65 79 20 63 6f 6c 75 6d 6e 2c 20 74 68  y key column, th
ef30: 65 20 73 79 73 74 65 6d 20 63 68 6f 6f 73 65 73  e system chooses
ef40: 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75   an integer valu
ef50: 65 20 74 6f 20 75 73 65 20 61 73 20 74 68 65 0a  e to use as the.
ef60: 72 6f 77 69 64 20 61 75 74 6f 6d 61 74 69 63 61  rowid automatica
ef70: 6c 6c 79 2e 20 41 20 64 65 74 61 69 6c 65 64 20  lly. A detailed 
ef80: 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 68  description of h
ef90: 6f 77 20 74 68 69 73 20 69 73 20 64 6f 6e 65 20  ow this is done 
efa0: 69 73 20 70 72 6f 76 69 64 65 64 0a 3c 61 20 68  is provided.<a h
efb0: 72 65 66 3d 22 61 75 74 6f 69 6e 63 2e 68 74 6d  ref="autoinc.htm
efc0: 6c 22 3e 73 65 70 61 72 61 74 65 6c 79 3c 2f 61  l">separately</a
efd0: 3e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 28 54 68 65  >.</p>..<p>^(The
efe0: 20 5b 70 61 72 65 6e 74 20 6b 65 79 5d 20 6f 66   [parent key] of
eff0: 20 61 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20   a [foreign key 
f000: 63 6f 6e 73 74 72 61 69 6e 74 5d 20 69 73 20 6e  constraint] is n
f010: 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 75 73  ot allowed to.us
f020: 65 20 74 68 65 20 72 6f 77 69 64 2e 20 20 54 68  e the rowid.  Th
f030: 65 20 70 61 72 65 6e 74 20 6b 65 79 20 6d 75 73  e parent key mus
f040: 74 20 75 73 65 64 20 6e 61 6d 65 64 20 63 6f 6c  t used named col
f050: 75 6d 6e 73 20 6f 6e 6c 79 2e 29 5e 3c 2f 70 3e  umns only.)^</p>
f060: 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
f070: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f080: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f090: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f0a0: 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
f0b0: 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b  ######.Section {
f0c0: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 7d 20  CREATE TRIGGER} 
f0d0: 63 72 65 61 74 65 74 72 69 67 67 65 72 20 7b 7b  createtrigger {{
f0e0: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 7d 7d  CREATE TRIGGER}}
f0f0: 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  ..RecursiveBubbl
f100: 65 44 69 61 67 72 61 6d 20 63 72 65 61 74 65 2d  eDiagram create-
f110: 74 72 69 67 67 65 72 2d 73 74 6d 74 0a 3c 2f 74  trigger-stmt.</t
f120: 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 43 52 45  cl>..<p>^The CRE
f130: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
f140: 65 6d 65 6e 74 20 69 73 20 75 73 65 64 20 74 6f  ement is used to
f150: 20 61 64 64 20 74 72 69 67 67 65 72 73 20 74 6f   add triggers to
f160: 20 74 68 65 20 0a 64 61 74 61 62 61 73 65 20 73   the .database s
f170: 63 68 65 6d 61 2e 20 5e 54 72 69 67 67 65 72 73  chema. ^Triggers
f180: 20 61 72 65 20 64 61 74 61 62 61 73 65 20 6f 70   are database op
f190: 65 72 61 74 69 6f 6e 73 20 0a 74 68 61 74 20 61  erations .that a
f1a0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
f1b0: 20 70 65 72 66 6f 72 6d 65 64 20 77 68 65 6e 20   performed when 
f1c0: 61 20 73 70 65 63 69 66 69 65 64 20 64 61 74 61  a specified data
f1d0: 62 61 73 65 20 65 76 65 6e 74 0a 6f 63 63 75 72  base event.occur
f1e0: 73 2e 20 20 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41 20  s.  </p>..<p>^A 
f1f0: 74 72 69 67 67 65 72 20 6d 61 79 20 62 65 20 73  trigger may be s
f200: 70 65 63 69 66 69 65 64 20 74 6f 20 66 69 72 65  pecified to fire
f210: 20 77 68 65 6e 65 76 65 72 20 61 20 5b 44 45 4c   whenever a [DEL
f220: 45 54 45 5d 2c 20 5b 49 4e 53 45 52 54 5d 2c 0a  ETE], [INSERT],.
f230: 6f 72 20 5b 55 50 44 41 54 45 5d 20 6f 66 20 61  or [UPDATE] of a
f240: 0a 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61  .particular data
f250: 62 61 73 65 20 74 61 62 6c 65 20 6f 63 63 75 72  base table occur
f260: 73 2c 20 6f 72 20 77 68 65 6e 65 76 65 72 20 61  s, or whenever a
f270: 6e 20 5b 55 50 44 41 54 45 5d 20 6f 63 63 75 72  n [UPDATE] occur
f280: 73 20 6f 6e 0a 6f 6e 20 6f 6e 65 20 6f 72 20 6d  s on.on one or m
f290: 6f 72 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  ore specified co
f2a0: 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
f2b0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41 74 20 74 68  .</p>..<p>^At th
f2c0: 69 73 20 74 69 6d 65 20 53 51 4c 69 74 65 20 73  is time SQLite s
f2d0: 75 70 70 6f 72 74 73 20 6f 6e 6c 79 20 46 4f 52  upports only FOR
f2e0: 20 45 41 43 48 20 52 4f 57 20 74 72 69 67 67 65   EACH ROW trigge
f2f0: 72 73 2c 20 6e 6f 74 20 46 4f 52 20 45 41 43 48  rs, not FOR EACH
f300: 0a 53 54 41 54 45 4d 45 4e 54 20 74 72 69 67 67  .STATEMENT trigg
f310: 65 72 73 2e 20 5e 48 65 6e 63 65 20 65 78 70 6c  ers. ^Hence expl
f320: 69 63 69 74 6c 79 20 73 70 65 63 69 66 79 69 6e  icitly specifyin
f330: 67 20 46 4f 52 20 45 41 43 48 20 52 4f 57 20 69  g FOR EACH ROW i
f340: 73 20 6f 70 74 69 6f 6e 61 6c 2e 0a 5e 46 4f 52  s optional..^FOR
f350: 20 45 41 43 48 20 52 4f 57 20 69 6d 70 6c 69 65   EACH ROW implie
f360: 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  s that the SQL s
f370: 74 61 74 65 6d 65 6e 74 73 20 73 70 65 63 69 66  tatements specif
f380: 69 65 64 20 69 6e 20 74 68 65 20 74 72 69 67 67  ied in the trigg
f390: 65 72 0a 6d 61 79 20 62 65 20 65 78 65 63 75 74  er.may be execut
f3a0: 65 64 20 28 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ed (depending on
f3b0: 20 74 68 65 20 57 48 45 4e 20 63 6c 61 75 73 65   the WHEN clause
f3c0: 29 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  ) for each datab
f3d0: 61 73 65 20 72 6f 77 20 62 65 69 6e 67 0a 69 6e  ase row being.in
f3e0: 73 65 72 74 65 64 2c 20 75 70 64 61 74 65 64 20  serted, updated 
f3f0: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
f400: 65 20 73 74 61 74 65 6d 65 6e 74 20 63 61 75 73  e statement caus
f410: 69 6e 67 20 74 68 65 20 74 72 69 67 67 65 72 20  ing the trigger 
f420: 74 6f 20 66 69 72 65 2e 3c 2f 70 3e 0a 0a 3c 70  to fire.</p>..<p
f430: 3e 5e 28 42 6f 74 68 20 74 68 65 20 57 48 45 4e  >^(Both the WHEN
f440: 20 63 6c 61 75 73 65 20 61 6e 64 20 74 68 65 20   clause and the 
f450: 74 72 69 67 67 65 72 20 61 63 74 69 6f 6e 73 20  trigger actions 
f460: 6d 61 79 20 61 63 63 65 73 73 20 65 6c 65 6d 65  may access eleme
f470: 6e 74 73 20 6f 66 20 0a 74 68 65 20 72 6f 77 20  nts of .the row 
f480: 62 65 69 6e 67 20 69 6e 73 65 72 74 65 64 2c 20  being inserted, 
f490: 64 65 6c 65 74 65 64 20 6f 72 20 75 70 64 61 74  deleted or updat
f4a0: 65 64 20 75 73 69 6e 67 20 72 65 66 65 72 65 6e  ed using referen
f4b0: 63 65 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ces of the form 
f4c0: 0a 22 4e 45 57 2e 3c 69 3e 63 6f 6c 75 6d 6e 2d  ."NEW.<i>column-
f4d0: 6e 61 6d 65 3c 2f 69 3e 22 20 61 6e 64 20 22 4f  name</i>" and "O
f4e0: 4c 44 2e 3c 69 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d  LD.<i>column-nam
f4f0: 65 3c 2f 69 3e 22 2c 20 77 68 65 72 65 0a 3c 69  e</i>", where.<i
f500: 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 69 3e  >column-name</i>
f510: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
f520: 61 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 74 68  a column from th
f530: 65 20 74 61 62 6c 65 20 74 68 61 74 20 74 68 65  e table that the
f540: 20 74 72 69 67 67 65 72 0a 69 73 20 61 73 73 6f   trigger.is asso
f550: 63 69 61 74 65 64 20 77 69 74 68 2e 29 5e 20 5e  ciated with.)^ ^
f560: 28 4f 4c 44 20 61 6e 64 20 4e 45 57 20 72 65 66  (OLD and NEW ref
f570: 65 72 65 6e 63 65 73 20 6d 61 79 20 6f 6e 6c 79  erences may only
f580: 20 62 65 20 75 73 65 64 20 69 6e 20 74 72 69 67   be used in trig
f590: 67 65 72 73 20 6f 6e 0a 65 76 65 6e 74 73 20 66  gers on.events f
f5a0: 6f 72 20 77 68 69 63 68 20 74 68 65 79 20 61 72  or which they ar
f5b0: 65 20 72 65 6c 65 76 61 6e 74 2c 20 61 73 20 66  e relevant, as f
f5c0: 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 74 61  ollows:</p>..<ta
f5d0: 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c  ble border=0 cel
f5e0: 6c 70 61 64 64 69 6e 67 3d 31 30 3e 0a 3c 74 72  lpadding=10>.<tr
f5f0: 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  >.<td valign="to
f600: 70 22 20 61 6c 69 67 6e 3d 22 72 69 67 68 74 22  p" align="right"
f610: 20 77 69 64 74 68 3d 31 32 30 3e 3c 69 3e 49 4e   width=120><i>IN
f620: 53 45 52 54 3c 2f 69 3e 3c 2f 74 64 3e 0a 3c 74  SERT</i></td>.<t
f630: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 4e  d valign="top">N
f640: 45 57 20 72 65 66 65 72 65 6e 63 65 73 20 61 72  EW references ar
f650: 65 20 76 61 6c 69 64 3c 2f 74 64 3e 0a 3c 2f 74  e valid</td>.</t
f660: 72 3e 0a 3c 74 72 3e 0a 3c 74 64 20 76 61 6c 69  r>.<tr>.<td vali
f670: 67 6e 3d 22 74 6f 70 22 20 61 6c 69 67 6e 3d 22  gn="top" align="
f680: 72 69 67 68 74 22 20 77 69 64 74 68 3d 31 32 30  right" width=120
f690: 3e 3c 69 3e 55 50 44 41 54 45 3c 2f 69 3e 3c 2f  ><i>UPDATE</i></
f6a0: 74 64 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22  td>.<td valign="
f6b0: 74 6f 70 22 3e 4e 45 57 20 61 6e 64 20 4f 4c 44  top">NEW and OLD
f6c0: 20 72 65 66 65 72 65 6e 63 65 73 20 61 72 65 20   references are 
f6d0: 76 61 6c 69 64 3c 2f 74 64 3e 0a 3c 2f 74 72 3e  valid</td>.</tr>
f6e0: 0a 3c 74 72 3e 0a 3c 74 64 20 76 61 6c 69 67 6e  .<tr>.<td valign
f6f0: 3d 22 74 6f 70 22 20 61 6c 69 67 6e 3d 22 72 69  ="top" align="ri
f700: 67 68 74 22 20 77 69 64 74 68 3d 31 32 30 3e 3c  ght" width=120><
f710: 69 3e 44 45 4c 45 54 45 3c 2f 69 3e 3c 2f 74 64  i>DELETE</i></td
f720: 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  >.<td valign="to
f730: 70 22 3e 4f 4c 44 20 72 65 66 65 72 65 6e 63 65  p">OLD reference
f740: 73 20 61 72 65 20 76 61 6c 69 64 3c 2f 74 64 3e  s are valid</td>
f750: 0a 3c 2f 74 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a  .</tr>.</table>.
f760: 3c 2f 70 3e 29 5e 0a 0a 3c 70 3e 5e 49 66 20 61  </p>)^..<p>^If a
f770: 20 57 48 45 4e 20 63 6c 61 75 73 65 20 69 73 20   WHEN clause is 
f780: 73 75 70 70 6c 69 65 64 2c 20 74 68 65 20 53 51  supplied, the SQ
f790: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 70 65  L statements spe
f7a0: 63 69 66 69 65 64 0a 61 72 65 20 6f 6e 6c 79 20  cified.are only 
f7b0: 65 78 65 63 75 74 65 64 20 69 66 20 74 68 65 20  executed if the 
f7c0: 57 48 45 4e 20 63 6c 61 75 73 65 20 69 73 20 74  WHEN clause is t
f7d0: 72 75 65 2e 0a 5e 49 66 20 6e 6f 20 57 48 45 4e  rue..^If no WHEN
f7e0: 20 63 6c 61 75 73 65 20 69 73 20 73 75 70 70 6c   clause is suppl
f7f0: 69 65 64 2c 20 74 68 65 20 53 51 4c 20 73 74 61  ied, the SQL sta
f800: 74 65 6d 65 6e 74 73 0a 61 72 65 20 65 78 65 63  tements.are exec
f810: 75 74 65 64 20 65 76 65 72 79 20 74 69 6d 65 20  uted every time 
f820: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
f830: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20  s.</p>..<p>^The 
f840: 42 45 46 4f 52 45 20 6f 72 20 41 46 54 45 52 20  BEFORE or AFTER 
f850: 6b 65 79 77 6f 72 64 20 64 65 74 65 72 6d 69 6e  keyword determin
f860: 65 73 20 77 68 65 6e 20 74 68 65 20 74 72 69 67  es when the trig
f870: 67 65 72 20 61 63 74 69 6f 6e 73 0a 77 69 6c 6c  ger actions.will
f880: 20 62 65 20 65 78 65 63 75 74 65 64 20 72 65 6c   be executed rel
f890: 61 74 69 76 65 20 74 6f 20 74 68 65 20 69 6e 73  ative to the ins
f8a0: 65 72 74 69 6f 6e 2c 20 6d 6f 64 69 66 69 63 61  ertion, modifica
f8b0: 74 69 6f 6e 20 6f 72 20 72 65 6d 6f 76 61 6c 20  tion or removal 
f8c0: 6f 66 20 74 68 65 0a 61 73 73 6f 63 69 61 74 65  of the.associate
f8d0: 64 20 72 6f 77 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  d row.</p>..<p>^
f8e0: 41 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  An [ON CONFLICT]
f8f0: 20 63 6c 61 75 73 65 20 6d 61 79 20 62 65 20 73   clause may be s
f900: 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
f910: 20 6f 66 20 61 6e 20 5b 55 50 44 41 54 45 5d 20   of an [UPDATE] 
f920: 6f 72 20 5b 49 4e 53 45 52 54 5d 0a 61 63 74 69  or [INSERT].acti
f930: 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  on within the bo
f940: 64 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 65  dy of the trigge
f950: 72 2e 0a 5e 48 6f 77 65 76 65 72 20 69 66 20 61  r..^However if a
f960: 6e 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  n [ON CONFLICT] 
f970: 63 6c 61 75 73 65 20 69 73 20 73 70 65 63 69 66  clause is specif
f980: 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 0a  ied as part of .
f990: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 63 61  the statement ca
f9a0: 75 73 69 6e 67 20 74 68 65 20 74 72 69 67 67 65  using the trigge
f9b0: 72 20 74 6f 20 66 69 72 65 2c 20 74 68 65 6e 20  r to fire, then 
f9c0: 63 6f 6e 66 6c 69 63 74 20 68 61 6e 64 6c 69 6e  conflict handlin
f9d0: 67 0a 70 6f 6c 69 63 79 20 6f 66 20 74 68 65 20  g.policy of the 
f9e0: 6f 75 74 65 72 20 73 74 61 74 65 6d 65 6e 74 20  outer statement 
f9f0: 69 73 20 75 73 65 64 20 69 6e 73 74 65 61 64 2e  is used instead.
fa00: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 72 69 67 67 65  </p>..<p>^Trigge
fa10: 72 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  rs are automatic
fa20: 61 6c 6c 79 20 5b 44 52 4f 50 20 54 52 49 47 47  ally [DROP TRIGG
fa30: 45 52 20 7c 20 64 72 6f 70 70 65 64 5d 0a 77 68  ER | dropped].wh
fa40: 65 6e 20 74 68 65 20 74 61 62 6c 65 20 74 68 61  en the table tha
fa50: 74 20 74 68 65 79 20 61 72 65 20 0a 61 73 73 6f  t they are .asso
fa60: 63 69 61 74 65 64 20 77 69 74 68 20 28 74 68 65  ciated with (the
fa70: 20 3c 69 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f   <i>table-name</
fa80: 69 3e 20 74 61 62 6c 65 29 20 69 73 20 0a 5b 44  i> table) is .[D
fa90: 52 4f 50 20 54 41 42 4c 45 20 7c 20 64 72 6f 70  ROP TABLE | drop
faa0: 70 65 64 5d 2e 20 20 5e 48 6f 77 65 76 65 72 20  ped].  ^However 
fab0: 69 66 20 74 68 65 20 74 72 69 67 67 65 72 20 61  if the trigger a
fac0: 63 74 69 6f 6e 73 20 72 65 66 65 72 65 6e 63 65  ctions reference
fad0: 0a 6f 74 68 65 72 20 74 61 62 6c 65 73 2c 20 74  .other tables, t
fae0: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 6e 6f  he trigger is no
faf0: 74 20 64 72 6f 70 70 65 64 20 6f 72 20 6d 6f 64  t dropped or mod
fb00: 69 66 69 65 64 20 69 66 20 74 68 6f 73 65 20 6f  ified if those o
fb10: 74 68 65 72 0a 74 61 62 6c 65 73 20 61 72 65 20  ther.tables are 
fb20: 5b 44 52 4f 50 20 54 41 42 4c 45 20 7c 20 64 72  [DROP TABLE | dr
fb30: 6f 70 70 65 64 5d 20 6f 72 20 5b 41 4c 54 45 52  opped] or [ALTER
fb40: 20 54 41 42 4c 45 20 7c 20 6d 6f 64 69 66 69 65   TABLE | modifie
fb50: 64 5d 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 72 69  d].</p>..<p>^Tri
fb60: 67 67 65 72 73 20 61 72 65 20 72 65 6d 6f 76 65  ggers are remove
fb70: 64 20 75 73 69 6e 67 20 74 68 65 20 5b 44 52 4f  d using the [DRO
fb80: 50 20 54 52 49 47 47 45 52 5d 20 73 74 61 74 65  P TRIGGER] state
fb90: 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 68 33 3e 53  ment.</p>..<h3>S
fba0: 79 6e 74 61 78 20 52 65 73 74 72 69 63 74 69 6f  yntax Restrictio
fbb0: 6e 73 20 4f 6e 20 55 50 44 41 54 45 2c 20 44 45  ns On UPDATE, DE
fbc0: 4c 45 54 45 2c 20 61 6e 64 20 49 4e 53 45 52 54  LETE, and INSERT
fbd0: 20 53 74 61 74 65 6d 65 6e 74 73 20 57 69 74 68   Statements With
fbe0: 69 6e 0a 20 20 20 20 54 72 69 67 67 65 72 73 3c  in.    Triggers<
fbf0: 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65 20 5b 55  /h3>..<p>^The [U
fc00: 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
fc10: 2c 20 61 6e 64 20 5b 49 4e 53 45 52 54 5d 0a 73  , and [INSERT].s
fc20: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e  tatements within
fc30: 20 74 72 69 67 67 65 72 73 20 64 6f 20 6e 6f 74   triggers do not
fc40: 20 73 75 70 70 6f 72 74 0a 74 68 65 20 66 75 6c   support.the ful
fc50: 6c 20 73 79 6e 74 61 78 20 66 6f 72 20 5b 55 50  l syntax for [UP
fc60: 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c  DATE], [DELETE],
fc70: 20 61 6e 64 20 5b 49 4e 53 45 52 54 5d 20 73 74   and [INSERT] st
fc80: 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 66  atements.  The f
fc90: 6f 6c 6c 6f 77 69 6e 67 0a 72 65 73 74 72 69 63  ollowing.restric
fca0: 74 69 6f 6e 73 20 61 70 70 6c 79 3a 3c 2f 70 3e  tions apply:</p>
fcb0: 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 20  ..<ul>.<li><p>. 
fcc0: 20 5e 28 54 68 65 20 6e 61 6d 65 20 6f 66 20 74   ^(The name of t
fcd0: 68 65 20 74 61 62 6c 65 20 74 6f 20 62 65 20 6d  he table to be m
fce0: 6f 64 69 66 69 65 64 20 69 6e 20 61 6e 20 5b 55  odified in an [U
fcf0: 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
fd00: 2c 20 6f 72 20 5b 49 4e 53 45 52 54 5d 0a 20 20  , or [INSERT].  
fd10: 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 62  statement must b
fd20: 65 20 61 6e 20 75 6e 71 75 61 6c 69 66 69 65 64  e an unqualified
fd30: 20 74 61 62 6c 65 20 6e 61 6d 65 2e 20 20 49 6e   table name.  In
fd40: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 6f 6e   other words, on
fd50: 65 20 6d 75 73 74 0a 20 20 75 73 65 20 6a 75 73  e must.  use jus
fd60: 74 20 22 3c 69 3e 74 61 62 6c 65 6e 61 6d 65 3c  t "<i>tablename<
fd70: 2f 69 3e 22 20 6e 6f 74 20 22 3c 69 3e 64 61 74  /i>" not "<i>dat
fd80: 61 62 61 73 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62  abase</i><b>.</b
fd90: 3e 3c 69 3e 74 61 62 6c 65 6e 61 6d 65 3c 2f 69  ><i>tablename</i
fda0: 3e 22 0a 20 20 77 68 65 6e 20 73 70 65 63 69 66  >".  when specif
fdb0: 79 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 29  ying the table.)
fdc0: 5e 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69  ^ </p></li>..<li
fdd0: 3e 3c 70 3e 0a 20 5e 46 6f 72 20 6e 6f 6e 2d 54  ><p>. ^For non-T
fde0: 45 4d 50 20 74 72 69 67 67 65 72 73 2c 0a 20 20  EMP triggers,.  
fdf0: 74 68 65 20 74 61 62 6c 65 20 74 6f 20 62 65 20  the table to be 
fe00: 6d 6f 64 69 66 69 65 64 20 6f 72 20 71 75 65 72  modified or quer
fe10: 69 65 64 20 6d 75 73 74 20 65 78 69 73 74 20 69  ied must exist i
fe20: 6e 20 74 68 65 0a 20 20 73 61 6d 65 20 64 61 74  n the.  same dat
fe30: 61 62 61 73 65 20 61 73 20 74 68 65 20 74 61 62  abase as the tab
fe40: 6c 65 20 6f 72 20 76 69 65 77 20 74 6f 20 77 68  le or view to wh
fe50: 69 63 68 20 74 68 65 20 74 72 69 67 67 65 72 20  ich the trigger 
fe60: 69 73 20 61 74 74 61 63 68 65 64 2e 0a 20 20 5e  is attached..  ^
fe70: 28 54 45 4d 50 20 74 72 69 67 67 65 72 73 20 61  (TEMP triggers a
fe80: 72 65 20 6e 6f 74 20 73 75 62 6a 65 63 74 20 74  re not subject t
fe90: 6f 20 74 68 65 20 73 61 6d 65 2d 64 61 74 61 62  o the same-datab
fea0: 61 73 65 20 72 75 6c 65 2e 20 20 41 20 54 45 4d  ase rule.  A TEM
feb0: 50 0a 20 20 74 72 69 67 67 65 72 20 69 73 20 61  P.  trigger is a
fec0: 6c 6c 6f 77 65 64 20 74 6f 20 71 75 65 72 79 20  llowed to query 
fed0: 6f 72 20 6d 6f 64 69 66 79 20 61 6e 79 20 74 61  or modify any ta
fee0: 62 6c 65 20 69 6e 20 61 6e 79 20 5b 41 54 54 41  ble in any [ATTA
fef0: 43 48 5d 2d 65 64 20 64 61 74 61 62 61 73 65 2e  CH]-ed database.
ff00: 29 5e 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  )^.  </p></li>..
ff10: 3c 6c 69 3e 3c 70 3e 0a 20 20 5e 54 68 65 20 22  <li><p>.  ^The "
ff20: 49 4e 53 45 52 54 20 49 4e 54 4f 20 3c 69 3e 74  INSERT INTO <i>t
ff30: 61 62 6c 65 3c 2f 69 3e 20 44 45 46 41 55 4c 54  able</i> DEFAULT
ff40: 20 56 41 4c 55 45 53 22 20 66 6f 72 6d 20 6f 66   VALUES" form of
ff50: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 20 73 74   the [INSERT] st
ff60: 61 74 65 6d 65 6e 74 0a 20 20 69 73 20 6e 6f 74  atement.  is not
ff70: 20 73 75 70 70 6f 72 74 65 64 2e 0a 20 20 3c 2f   supported..  </
ff80: 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e  p></li>..<li><p>
ff90: 0a 20 20 5e 54 68 65 20 49 4e 44 45 58 45 44 20  .  ^The INDEXED 
ffa0: 42 59 20 61 6e 64 20 4e 4f 54 20 49 4e 44 45 58  BY and NOT INDEX
ffb0: 45 44 20 63 6c 61 75 73 65 73 20 61 72 65 20 6e  ED clauses are n
ffc0: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  ot supported for
ffd0: 20 5b 55 50 44 41 54 45 5d 20 61 6e 64 0a 20 20   [UPDATE] and.  
ffe0: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
fff0: 6e 74 73 2e 0a 20 20 3c 2f 70 3e 3c 2f 6c 69 3e  nts..  </p></li>
10000 0a 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 5e 28 54 68  ..<li><p>.  ^(Th
10010 65 20 4f 52 44 45 52 20 42 59 20 61 6e 64 20 4c  e ORDER BY and L
10020 49 4d 49 54 20 63 6c 61 75 73 65 73 20 6f 6e 20  IMIT clauses on 
10030 5b 55 50 44 41 54 45 5d 20 61 6e 64 20 5b 44 45  [UPDATE] and [DE
10040 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
10050 20 61 72 65 20 6e 6f 74 0a 20 20 73 75 70 70 6f   are not.  suppo
10060 72 74 65 64 2e 20 20 4f 52 44 45 52 20 42 59 20  rted.  ORDER BY 
10070 61 6e 64 20 4c 49 4d 49 54 20 61 72 65 20 6e 6f  and LIMIT are no
10080 74 20 6e 6f 72 6d 61 6c 6c 79 20 73 75 70 70 6f  t normally suppo
10090 72 74 65 64 20 66 6f 72 20 5b 55 50 44 41 54 45  rted for [UPDATE
100a0 5d 20 6f 72 0a 20 20 5b 44 45 4c 45 54 45 5d 20  ] or.  [DELETE] 
100b0 69 6e 20 61 6e 79 20 63 6f 6e 74 65 78 74 20 62  in any context b
100c0 75 74 20 63 61 6e 20 62 65 20 65 6e 61 62 6c 65  ut can be enable
100d0 64 20 66 6f 72 20 74 6f 70 2d 6c 65 76 65 6c 20  d for top-level 
100e0 73 74 61 74 65 6d 65 6e 74 73 0a 20 20 75 73 69  statements.  usi
100f0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  ng the [SQLITE_E
10100 4e 41 42 4c 45 5f 55 50 44 41 54 45 5f 44 45 4c  NABLE_UPDATE_DEL
10110 45 54 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  ETE_LIMIT] compi
10120 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
10130 20 48 6f 77 65 76 65 72 2c 0a 20 20 74 68 61 74   However,.  that
10140 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10150 74 69 6f 6e 20 6f 6e 6c 79 20 61 70 70 6c 69 65  tion only applie
10160 73 20 74 6f 20 74 6f 70 2d 6c 65 76 65 6c 20 5b  s to top-level [
10170 55 50 44 41 54 45 5d 20 61 6e 64 20 5b 44 45 4c  UPDATE] and [DEL
10180 45 54 45 5d 0a 20 20 73 74 61 74 65 6d 65 6e 74  ETE].  statement
10190 73 2c 20 6e 6f 74 20 5b 55 50 44 41 54 45 5d 20  s, not [UPDATE] 
101a0 61 6e 64 20 5b 44 45 4c 45 54 45 5d 20 73 74 61  and [DELETE] sta
101b0 74 65 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 74  tements within t
101c0 72 69 67 67 65 72 73 2e 29 5e 0a 20 20 3c 2f 70  riggers.)^.  </p
101d0 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a  ></li>..<li><p>.
101e0 20 20 5e 5b 63 6f 6d 6d 6f 6e 2d 74 61 62 6c 65    ^[common-table
101f0 2d 65 78 70 72 65 73 73 69 6f 6e 7c 43 6f 6d 6d  -expression|Comm
10200 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73  on table express
10210 69 6f 6e 5d 20 61 72 65 20 6e 6f 74 20 73 75 70  ion] are not sup
10220 70 6f 72 74 65 64 20 66 6f 72 0a 20 20 73 74 61  ported for.  sta
10230 74 65 6d 65 6e 74 73 20 69 6e 73 69 64 65 20 6f  tements inside o
10240 66 20 74 72 69 67 67 65 72 73 2e 0a 20 20 3c 2f  f triggers..  </
10250 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c  p></li>.</ul>..<
10260 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
10270 69 6e 73 74 65 61 64 5f 6f 66 5f 74 72 69 67 67  instead_of_trigg
10280 65 72 20 7b 49 4e 53 54 45 41 44 20 4f 46 7d 20  er {INSTEAD OF} 
10290 7b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  {INSTEAD OF trig
102a0 67 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 49  ger}</tcl>.<h3>I
102b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
102c0 72 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 72 69  rs</h3>..<p>^Tri
102d0 67 67 65 72 73 20 6d 61 79 20 62 65 20 63 72 65  ggers may be cre
102e0 61 74 65 64 20 6f 6e 20 5b 76 69 65 77 73 5d 2c  ated on [views],
102f0 20 61 73 20 77 65 6c 6c 20 61 73 20 6f 72 64 69   as well as ordi
10300 6e 61 72 79 20 74 61 62 6c 65 73 2c 20 62 79 0a  nary tables, by.
10310 73 70 65 63 69 66 79 69 6e 67 20 49 4e 53 54 45  specifying INSTE
10320 41 44 20 4f 46 20 69 6e 20 74 68 65 20 43 52 45  AD OF in the CRE
10330 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
10340 65 6d 65 6e 74 2e 20 0a 5e 49 66 20 6f 6e 65 20  ement. .^If one 
10350 6f 72 20 6d 6f 72 65 20 4f 4e 20 49 4e 53 45 52  or more ON INSER
10360 54 2c 20 4f 4e 20 44 45 4c 45 54 45 0a 6f 72 20  T, ON DELETE.or 
10370 4f 4e 20 55 50 44 41 54 45 20 74 72 69 67 67 65  ON UPDATE trigge
10380 72 73 20 61 72 65 20 64 65 66 69 6e 65 64 20 6f  rs are defined o
10390 6e 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 69  n a view, then i
103a0 74 20 69 73 20 6e 6f 74 20 61 6e 0a 65 72 72 6f  t is not an.erro
103b0 72 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 20  r to execute an 
103c0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 20 6f  INSERT, DELETE o
103d0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
103e0 6e 74 20 6f 6e 20 74 68 65 20 76 69 65 77 2c 20  nt on the view, 
103f0 0a 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20  .respectively.  
10400 5e 49 6e 73 74 65 61 64 2c 0a 65 78 65 63 75 74  ^Instead,.execut
10410 69 6e 67 20 61 6e 20 49 4e 53 45 52 54 2c 20 44  ing an INSERT, D
10420 45 4c 45 54 45 20 6f 72 20 55 50 44 41 54 45 20  ELETE or UPDATE 
10430 6f 6e 20 74 68 65 20 76 69 65 77 20 63 61 75 73  on the view caus
10440 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
10450 64 0a 74 72 69 67 67 65 72 73 20 74 6f 20 66 69  d.triggers to fi
10460 72 65 2e 20 5e 54 68 65 20 72 65 61 6c 20 74 61  re. ^The real ta
10470 62 6c 65 73 20 75 6e 64 65 72 6c 79 69 6e 67 20  bles underlying 
10480 74 68 65 20 76 69 65 77 20 61 72 65 20 6e 6f 74  the view are not
10490 20 6d 6f 64 69 66 69 65 64 0a 28 65 78 63 65 70   modified.(excep
104a0 74 20 70 6f 73 73 69 62 6c 79 20 65 78 70 6c 69  t possibly expli
104b0 63 69 74 6c 79 2c 20 62 79 20 61 20 74 72 69 67  citly, by a trig
104c0 67 65 72 20 70 72 6f 67 72 61 6d 29 2e 3c 2f 70  ger program).</p
104d0 3e 0a 0a 3c 70 3e 5e 4e 6f 74 65 20 74 68 61 74  >..<p>^Note that
104e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
104f0 61 6e 67 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  anges()] and [sq
10500 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
10510 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
10520 73 0a 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 49  s.do not count I
10530 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
10540 72 20 66 69 72 69 6e 67 73 2c 20 62 75 74 20 74  r firings, but t
10550 68 65 0a 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  he.[count_change
10560 73 20 70 72 61 67 6d 61 5d 20 64 6f 65 73 20 63  s pragma] does c
10570 6f 75 6e 74 20 49 4e 53 54 45 41 44 20 4f 46 20  ount INSTEAD OF 
10580 74 72 69 67 67 65 72 20 66 69 72 69 6e 67 2e 3c  trigger firing.<
10590 2f 70 3e 0a 0a 3c 68 33 3e 53 6f 6d 65 20 45 78  /p>..<h3>Some Ex
105a0 61 6d 70 6c 65 20 54 72 69 67 67 65 72 73 3c 2f  ample Triggers</
105b0 68 33 3e 0a 0a 3c 70 3e 5e 28 41 73 73 75 6d 69  h3>..<p>^(Assumi
105c0 6e 67 20 74 68 61 74 20 63 75 73 74 6f 6d 65 72  ng that customer
105d0 20 72 65 63 6f 72 64 73 20 61 72 65 20 73 74 6f   records are sto
105e0 72 65 64 20 69 6e 20 74 68 65 20 22 63 75 73 74  red in the "cust
105f0 6f 6d 65 72 73 22 20 74 61 62 6c 65 2c 20 61 6e  omers" table, an
10600 64 0a 74 68 61 74 20 6f 72 64 65 72 20 72 65 63  d.that order rec
10610 6f 72 64 73 20 61 72 65 20 73 74 6f 72 65 64 20  ords are stored 
10620 69 6e 20 74 68 65 20 22 6f 72 64 65 72 73 22 20  in the "orders" 
10630 74 61 62 6c 65 2c 20 74 68 65 20 66 6f 6c 6c 6f  table, the follo
10640 77 69 6e 67 0a 55 50 44 41 54 45 20 74 72 69 67  wing.UPDATE trig
10650 67 65 72 0a 65 6e 73 75 72 65 73 20 74 68 61 74  ger.ensures that
10660 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20   all associated 
10670 6f 72 64 65 72 73 20 61 72 65 20 72 65 64 69 72  orders are redir
10680 65 63 74 65 64 20 77 68 65 6e 20 61 20 63 75 73  ected when a cus
10690 74 6f 6d 65 72 20 63 68 61 6e 67 65 73 0a 68 69  tomer changes.hi
106a0 73 20 6f 72 20 68 65 72 20 61 64 64 72 65 73 73  s or her address
106b0 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 45 78 61 6d  :</p>..<tcl>Exam
106c0 70 6c 65 20 7b 0a 43 52 45 41 54 45 20 54 52 49  ple {.CREATE TRI
106d0 47 47 45 52 20 75 70 64 61 74 65 5f 63 75 73 74  GGER update_cust
106e0 6f 6d 65 72 5f 61 64 64 72 65 73 73 20 55 50 44  omer_address UPD
106f0 41 54 45 20 4f 46 20 61 64 64 72 65 73 73 20 4f  ATE OF address O
10700 4e 20 63 75 73 74 6f 6d 65 72 73 20 0a 20 20 42  N customers .  B
10710 45 47 49 4e 0a 20 20 20 20 55 50 44 41 54 45 20  EGIN.    UPDATE 
10720 6f 72 64 65 72 73 20 53 45 54 20 61 64 64 72 65  orders SET addre
10730 73 73 20 3d 20 6e 65 77 2e 61 64 64 72 65 73 73  ss = new.address
10740 20 57 48 45 52 45 20 63 75 73 74 6f 6d 65 72 5f   WHERE customer_
10750 6e 61 6d 65 20 3d 20 6f 6c 64 2e 6e 61 6d 65 3b  name = old.name;
10760 0a 20 20 45 4e 44 3b 0a 7d 3c 2f 74 63 6c 3e 0a  .  END;.}</tcl>.
10770 0a 3c 70 3e 57 69 74 68 20 74 68 69 73 20 74 72  .<p>With this tr
10780 69 67 67 65 72 20 69 6e 73 74 61 6c 6c 65 64 2c  igger installed,
10790 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 73   executing the s
107a0 74 61 74 65 6d 65 6e 74 3a 3c 2f 70 3e 0a 0a 3c  tatement:</p>..<
107b0 74 63 6c 3e 45 78 61 6d 70 6c 65 20 7b 0a 55 50  tcl>Example {.UP
107c0 44 41 54 45 20 63 75 73 74 6f 6d 65 72 73 20 53  DATE customers S
107d0 45 54 20 61 64 64 72 65 73 73 20 3d 20 27 31 20  ET address = '1 
107e0 4d 61 69 6e 20 53 74 2e 27 20 57 48 45 52 45 20  Main St.' WHERE 
107f0 6e 61 6d 65 20 3d 20 27 4a 61 63 6b 20 4a 6f 6e  name = 'Jack Jon
10800 65 73 27 3b 0a 7d 3c 2f 74 63 6c 3e 0a 0a 3c 70  es';.}</tcl>..<p
10810 3e 63 61 75 73 65 73 20 74 68 65 20 66 6f 6c 6c  >causes the foll
10820 6f 77 69 6e 67 20 74 6f 20 62 65 20 61 75 74 6f  owing to be auto
10830 6d 61 74 69 63 61 6c 6c 79 20 65 78 65 63 75 74  matically execut
10840 65 64 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 45 78  ed:</p>..<tcl>Ex
10850 61 6d 70 6c 65 20 7b 0a 55 50 44 41 54 45 20 6f  ample {.UPDATE o
10860 72 64 65 72 73 20 53 45 54 20 61 64 64 72 65 73  rders SET addres
10870 73 20 3d 20 27 31 20 4d 61 69 6e 20 53 74 2e 27  s = '1 Main St.'
10880 20 57 48 45 52 45 20 63 75 73 74 6f 6d 65 72 5f   WHERE customer_
10890 6e 61 6d 65 20 3d 20 27 4a 61 63 6b 20 4a 6f 6e  name = 'Jack Jon
108a0 65 73 27 3b 0a 7d 3c 2f 74 63 6c 3e 29 5e 0a 0a  es';.}</tcl>)^..
108b0 3c 70 3e 46 6f 72 20 61 6e 20 65 78 61 6d 70 6c  <p>For an exampl
108c0 65 20 6f 66 20 61 6e 20 49 4e 53 54 45 41 44 20  e of an INSTEAD 
108d0 4f 46 20 74 72 69 67 67 65 72 2c 20 63 6f 6e 73  OF trigger, cons
108e0 69 64 65 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ider the followi
108f0 6e 67 20 73 63 68 65 6d 61 3a 0a 0a 3c 74 63 6c  ng schema:..<tcl
10900 3e 45 78 61 6d 70 6c 65 20 7b 0a 43 52 45 41 54  >Example {.CREAT
10910 45 20 54 41 42 4c 45 20 63 75 73 74 6f 6d 65 72  E TABLE customer
10920 28 0a 20 20 63 75 73 74 5f 69 64 20 49 4e 54 45  (.  cust_id INTE
10930 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  GER PRIMARY KEY,
10940 0a 20 20 63 75 73 74 5f 6e 61 6d 65 20 54 45 58  .  cust_name TEX
10950 54 2c 0a 20 20 63 75 73 74 5f 61 64 64 72 20 54  T,.  cust_addr T
10960 45 58 54 0a 29 3b 0a 43 52 45 41 54 45 20 56 49  EXT.);.CREATE VI
10970 45 57 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72  EW customer_addr
10980 65 73 73 20 41 53 0a 20 20 20 53 45 4c 45 43 54  ess AS.   SELECT
10990 20 63 75 73 74 5f 69 64 2c 20 63 75 73 74 5f 61   cust_id, cust_a
109a0 64 64 72 20 46 52 4f 4d 20 63 75 73 74 6f 6d 65  ddr FROM custome
109b0 72 3b 0a 43 52 45 41 54 45 20 54 52 49 47 47 45  r;.CREATE TRIGGE
109c0 52 20 63 75 73 74 5f 61 64 64 72 5f 63 68 6e 67  R cust_addr_chng
109d0 0a 49 4e 53 54 45 41 44 20 4f 46 20 55 50 44 41  .INSTEAD OF UPDA
109e0 54 45 20 4f 46 20 63 75 73 74 5f 61 64 64 72 20  TE OF cust_addr 
109f0 4f 4e 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72  ON customer_addr
10a00 65 73 73 0a 42 45 47 49 4e 0a 20 20 55 50 44 41  ess.BEGIN.  UPDA
10a10 54 45 20 63 75 73 74 6f 6d 65 72 20 53 45 54 20  TE customer SET 
10a20 63 75 73 74 5f 61 64 64 72 3d 4e 45 57 2e 63 75  cust_addr=NEW.cu
10a30 73 74 5f 61 64 64 72 0a 20 20 20 57 48 45 52 45  st_addr.   WHERE
10a40 20 63 75 73 74 5f 69 64 3d 4e 45 57 2e 63 75 73   cust_id=NEW.cus
10a50 74 5f 69 64 3b 0a 45 4e 44 3b 0a 7d 3c 2f 74 63  t_id;.END;.}</tc
10a60 6c 3e 0a 0a 3c 70 3e 57 69 74 68 20 74 68 65 20  l>..<p>With the 
10a70 73 63 68 65 6d 61 20 61 62 6f 76 65 2c 20 61 20  schema above, a 
10a80 73 74 61 74 65 6d 65 6e 74 20 6f 66 20 74 68 65  statement of the
10a90 20 66 6f 72 6d 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c   form:</p>..<tcl
10aa0 3e 45 78 61 6d 70 6c 65 20 7b 0a 55 50 44 41 54  >Example {.UPDAT
10ab0 45 20 63 75 73 74 6f 6d 65 72 5f 61 64 64 72 65  E customer_addre
10ac0 73 73 20 53 45 54 20 63 75 73 74 5f 61 64 64 72  ss SET cust_addr
10ad0 3d 24 6e 65 77 5f 61 64 64 72 65 73 73 20 57 48  =$new_address WH
10ae0 45 52 45 20 63 75 73 74 5f 69 64 3d 24 63 75 73  ERE cust_id=$cus
10af0 74 5f 69 64 3b 0a 7d 3c 2f 74 63 6c 3e 0a 0a 3c  t_id;.}</tcl>..<
10b00 70 3e 43 61 75 73 65 73 20 74 68 65 20 63 75 73  p>Causes the cus
10b10 74 6f 6d 65 72 2e 63 75 73 74 5f 61 64 64 72 20  tomer.cust_addr 
10b20 66 69 65 6c 64 20 74 6f 20 62 65 20 75 70 64 61  field to be upda
10b30 74 65 64 20 66 6f 72 20 61 20 73 70 65 63 69 66  ted for a specif
10b40 69 63 0a 63 75 73 74 6f 6d 65 72 20 65 6e 74 72  ic.customer entr
10b50 79 20 74 68 61 74 20 68 61 73 20 63 75 73 74 6f  y that has custo
10b60 6d 65 72 2e 63 75 73 74 5f 69 64 20 65 71 75 61  mer.cust_id equa
10b70 6c 20 74 6f 20 74 68 65 20 24 63 75 73 74 5f 69  l to the $cust_i
10b80 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 4e 6f 74  d parameter..Not
10b90 65 20 68 6f 77 20 74 68 65 20 76 61 6c 75 65 73  e how the values
10ba0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65   assigned to the
10bb0 20 76 69 65 77 20 61 72 65 20 6d 61 64 65 20 61   view are made a
10bc0 76 61 69 6c 61 62 6c 65 20 61 73 20 66 69 65 6c  vailable as fiel
10bd0 64 0a 69 6e 20 74 68 65 20 73 70 65 63 69 61 6c  d.in the special
10be0 20 22 4e 45 57 22 20 74 61 62 6c 65 20 77 69 74   "NEW" table wit
10bf0 68 69 6e 20 74 68 65 20 74 72 69 67 67 65 72 20  hin the trigger 
10c00 62 6f 64 79 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  body.</p>..<tcl>
10c10 68 64 5f 66 72 61 67 6d 65 6e 74 20 75 6e 64 65  hd_fragment unde
10c20 66 5f 62 65 66 6f 72 65 20 7b 75 6e 64 65 66 69  f_before {undefi
10c30 6e 65 64 20 42 45 46 4f 52 45 20 74 72 69 67 67  ned BEFORE trigg
10c40 65 72 20 62 65 68 61 76 69 6f 72 7d 3c 2f 74 63  er behavior}</tc
10c50 6c 3e 0a 3c 68 33 3e 43 61 75 74 69 6f 6e 73 20  l>.<h3>Cautions 
10c60 4f 6e 20 54 68 65 20 55 73 65 20 4f 66 20 42 45  On The Use Of BE
10c70 46 4f 52 45 20 74 72 69 67 67 65 72 73 3c 2f 68  FORE triggers</h
10c80 33 3e 0a 0a 3c 70 3e 49 66 20 61 20 42 45 46 4f  3>..<p>If a BEFO
10c90 52 45 20 55 50 44 41 54 45 20 6f 72 20 42 45 46  RE UPDATE or BEF
10ca0 4f 52 45 20 44 45 4c 45 54 45 20 74 72 69 67 67  ORE DELETE trigg
10cb0 65 72 20 6d 6f 64 69 66 69 65 73 20 6f 72 20 64  er modifies or d
10cc0 65 6c 65 74 65 73 20 61 20 72 6f 77 0a 74 68 61  eletes a row.tha
10cd0 74 20 77 61 73 20 74 6f 20 68 61 76 65 20 62 65  t was to have be
10ce0 65 6e 20 75 70 64 61 74 65 64 20 6f 72 20 64 65  en updated or de
10cf0 6c 65 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  leted, then the 
10d00 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 73 75  result of the su
10d10 62 73 65 71 75 65 6e 74 0a 75 70 64 61 74 65 20  bsequent.update 
10d20 6f 72 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  or delete operat
10d30 69 6f 6e 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ion is undefined
10d40 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
10d50 69 66 20 61 20 42 45 46 4f 52 45 20 74 72 69 67  if a BEFORE trig
10d60 67 65 72 0a 6d 6f 64 69 66 69 65 73 20 6f 72 20  ger.modifies or 
10d70 64 65 6c 65 74 65 73 20 61 20 72 6f 77 2c 20 74  deletes a row, t
10d80 68 65 6e 20 69 74 20 69 73 20 75 6e 64 65 66 69  hen it is undefi
10d90 6e 65 64 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ned whether or n
10da0 6f 74 20 41 46 54 45 52 20 74 72 69 67 67 65 72  ot AFTER trigger
10db0 73 0a 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  s.that would hav
10dc0 65 20 6f 74 68 65 72 77 69 73 65 20 72 75 6e 20  e otherwise run 
10dd0 6f 6e 20 74 68 6f 73 65 20 72 6f 77 73 20 77 69  on those rows wi
10de0 6c 6c 20 69 6e 20 66 61 63 74 20 72 75 6e 2e 0a  ll in fact run..
10df0 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 76 61 6c  </p>..<p>The val
10e00 75 65 20 6f 66 20 4e 45 57 2e 72 6f 77 69 64 20  ue of NEW.rowid 
10e10 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 6e 20  is undefined in 
10e20 61 20 42 45 46 4f 52 45 20 49 4e 53 45 52 54 20  a BEFORE INSERT 
10e30 74 72 69 67 67 65 72 20 69 6e 20 77 68 69 63 68  trigger in which
10e40 0a 74 68 65 20 72 6f 77 69 64 20 69 73 20 6e 6f  .the rowid is no
10e50 74 20 65 78 70 6c 69 63 69 74 6c 79 20 73 65 74  t explicitly set
10e60 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 3c   to an integer.<
10e70 2f 70 3e 0a 0a 3c 70 3e 42 65 63 61 75 73 65 20  /p>..<p>Because 
10e80 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 73  of the behaviors
10e90 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
10ea0 2c 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 61 72  , programmers ar
10eb0 65 20 65 6e 63 6f 75 72 61 67 65 64 20 74 6f 0a  e encouraged to.
10ec0 70 72 65 66 65 72 20 41 46 54 45 52 20 74 72 69  prefer AFTER tri
10ed0 67 67 65 72 73 20 6f 76 65 72 20 42 45 46 4f 52  ggers over BEFOR
10ee0 45 20 74 72 69 67 67 65 72 73 2e 3c 2f 70 3e 0a  E triggers.</p>.
10ef0 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
10f00 74 20 72 61 69 73 65 20 7b 52 41 49 53 45 20 66  t raise {RAISE f
10f10 75 6e 63 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c  unction}</tcl>.<
10f20 68 33 3e 54 68 65 20 52 41 49 53 45 28 29 20 66  h3>The RAISE() f
10f30 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70  unction</h3>..<p
10f40 3e 5e 28 41 20 73 70 65 63 69 61 6c 20 53 51 4c  >^(A special SQL
10f50 20 66 75 6e 63 74 69 6f 6e 20 52 41 49 53 45 28   function RAISE(
10f60 29 20 6d 61 79 20 62 65 20 75 73 65 64 20 77 69  ) may be used wi
10f70 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2d 70  thin a trigger-p
10f80 72 6f 67 72 61 6d 2c 29 5e 0a 77 69 74 68 20 74  rogram,)^.with t
10f90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 79 6e  he following syn
10fa0 74 61 78 3c 2f 70 3e 20 0a 0a 3c 74 63 6c 3e 42  tax</p> ..<tcl>B
10fb0 75 62 62 6c 65 44 69 61 67 72 61 6d 20 72 61 69  ubbleDiagram rai
10fc0 73 65 2d 66 75 6e 63 74 69 6f 6e 3c 2f 74 63 6c  se-function</tcl
10fd0 3e 0a 0a 3c 70 3e 5e 28 57 68 65 6e 20 6f 6e 65  >..<p>^(When one
10fe0 20 6f 66 20 52 41 49 53 45 28 52 4f 4c 4c 42 41   of RAISE(ROLLBA
10ff0 43 4b 2c 2e 2e 2e 29 2c 20 52 41 49 53 45 28 41  CK,...), RAISE(A
11000 42 4f 52 54 2c 2e 2e 2e 29 20 6f 72 20 52 41 49  BORT,...) or RAI
11010 53 45 28 46 41 49 4c 2c 2e 2e 2e 29 0a 69 73 20  SE(FAIL,...).is 
11020 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20 74 72  called during tr
11030 69 67 67 65 72 2d 70 72 6f 67 72 61 6d 0a 65 78  igger-program.ex
11040 65 63 75 74 69 6f 6e 2c 20 74 68 65 20 73 70 65  ecution, the spe
11050 63 69 66 69 65 64 20 5b 4f 4e 20 43 4f 4e 46 4c  cified [ON CONFL
11060 49 43 54 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  ICT] processing 
11070 69 73 20 70 65 72 66 6f 72 6d 65 64 0a 74 68 65  is performed.the
11080 20 63 75 72 72 65 6e 74 20 71 75 65 72 79 20 74   current query t
11090 65 72 6d 69 6e 61 74 65 73 2e 29 5e 0a 41 6e 20  erminates.)^.An 
110a0 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
110b0 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
110c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  ] is returned to
110d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
110e0 2c 0a 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65  ,.along with the
110f0 20 73 70 65 63 69 66 69 65 64 20 65 72 72 6f 72   specified error
11100 20 6d 65 73 73 61 67 65 2e 3c 2f 70 3e 0a 0a 3c   message.</p>..<
11110 70 3e 5e 57 68 65 6e 20 52 41 49 53 45 28 49 47  p>^When RAISE(IG
11120 4e 4f 52 45 29 20 69 73 20 63 61 6c 6c 65 64 2c  NORE) is called,
11130 20 74 68 65 20 72 65 6d 61 69 6e 64 65 72 20 6f   the remainder o
11140 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  f the current tr
11150 69 67 67 65 72 20 70 72 6f 67 72 61 6d 2c 0a 74  igger program,.t
11160 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
11170 74 20 63 61 75 73 65 64 20 74 68 65 20 74 72 69  t caused the tri
11180 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 6f 20  gger program to 
11190 65 78 65 63 75 74 65 20 61 6e 64 20 61 6e 79 20  execute and any 
111a0 73 75 62 73 65 71 75 65 6e 74 0a 74 72 69 67 67  subsequent.trigg
111b0 65 72 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  er programs that
111c0 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
111d0 20 65 78 65 63 75 74 65 64 20 61 72 65 20 61 62   executed are ab
111e0 61 6e 64 6f 6e 65 64 2e 20 5e 4e 6f 20 64 61 74  andoned. ^No dat
111f0 61 62 61 73 65 0a 63 68 61 6e 67 65 73 20 61 72  abase.changes ar
11200 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20  e rolled back.  
11210 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
11220 74 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  t that caused th
11230 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
11240 6d 0a 74 6f 20 65 78 65 63 75 74 65 20 69 73 20  m.to execute is 
11250 69 74 73 65 6c 66 20 70 61 72 74 20 6f 66 20 61  itself part of a
11260 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
11270 2c 20 74 68 65 6e 20 74 68 61 74 20 74 72 69 67  , then that trig
11280 67 65 72 20 70 72 6f 67 72 61 6d 0a 72 65 73 75  ger program.resu
11290 6d 65 73 20 65 78 65 63 75 74 69 6f 6e 20 61 74  mes execution at
112a0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
112b0 66 20 74 68 65 20 6e 65 78 74 20 73 74 65 70 2e  f the next step.
112c0 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  .</p>..<tcl>hd_f
112d0 72 61 67 6d 65 6e 74 20 74 65 6d 70 74 72 69 67  ragment temptrig
112e0 20 7b 54 45 4d 50 20 74 72 69 67 67 65 72 73 20   {TEMP triggers 
112f0 6f 6e 20 6e 6f 6e 2d 54 45 4d 50 20 74 61 62 6c  on non-TEMP tabl
11300 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 45  es}</tcl>.<h3>TE
11310 4d 50 20 54 72 69 67 67 65 72 73 20 6f 6e 20 4e  MP Triggers on N
11320 6f 6e 2d 54 45 4d 50 20 54 61 62 6c 65 73 3c 2f  on-TEMP Tables</
11330 68 33 3e 0a 0a 3c 70 3e 5e 28 41 20 74 72 69 67  h3>..<p>^(A trig
11340 67 65 72 20 6e 6f 72 6d 61 6c 6c 79 20 65 78 69  ger normally exi
11350 73 74 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  sts in the same 
11360 64 61 74 61 62 61 73 65 20 61 73 20 74 68 65 20  database as the 
11370 74 61 62 6c 65 20 6e 61 6d 65 64 0a 61 66 74 65  table named.afte
11380 72 20 74 68 65 20 22 4f 4e 22 20 6b 65 79 77 6f  r the "ON" keywo
11390 72 64 20 69 6e 20 74 68 65 20 43 52 45 41 54 45  rd in the CREATE
113a0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
113b0 6e 74 2e 20 20 45 78 63 65 70 74 2c 20 69 74 20  nt.  Except, it 
113c0 69 73 0a 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  is.possible to c
113d0 72 65 61 74 65 20 61 20 54 45 4d 50 20 54 52 49  reate a TEMP TRI
113e0 47 47 45 52 20 6f 6e 20 61 20 74 61 62 6c 65 20  GGER on a table 
113f0 69 6e 20 61 6e 6f 74 68 65 72 20 64 61 74 61 62  in another datab
11400 61 73 65 2e 29 5e 20 20 0a 53 75 63 68 20 61 20  ase.)^  .Such a 
11410 74 72 69 67 67 65 72 20 77 69 6c 6c 20 6f 6e 6c  trigger will onl
11420 79 20 66 69 72 65 20 77 68 65 6e 20 63 68 61 6e  y fire when chan
11430 67 65 73 0a 61 72 65 20 6d 61 64 65 20 74 6f 20  ges.are made to 
11440 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
11450 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
11460 69 6f 6e 20 74 68 61 74 20 64 65 66 69 6e 65 64  ion that defined
11470 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 4f 74   the trigger..Ot
11480 68 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  her applications
11490 20 74 68 61 74 20 6d 6f 64 69 66 79 20 74 68 65   that modify the
114a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 6e   database will n
114b0 6f 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 65  ot be able to se
114c0 65 20 74 68 65 0a 54 45 4d 50 20 74 72 69 67 67  e the.TEMP trigg
114d0 65 72 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6e  er and hence can
114e0 6e 6f 74 20 72 75 6e 20 74 68 65 20 74 72 69 67  not run the trig
114f0 67 65 72 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65  ger.</p>..<p>Whe
11500 6e 20 64 65 66 69 6e 69 6e 67 20 61 20 54 45 4d  n defining a TEM
11510 50 20 74 72 69 67 67 65 72 20 6f 6e 20 61 20 6e  P trigger on a n
11520 6f 6e 2d 54 45 4d 50 20 74 61 62 6c 65 2c 20 69  on-TEMP table, i
11530 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74  t is important t
11540 6f 0a 73 70 65 63 69 66 79 20 74 68 65 20 64 61  o.specify the da
11550 74 61 62 61 73 65 20 68 6f 6c 64 69 6e 67 20 74  tabase holding t
11560 68 65 20 6e 6f 6e 2d 54 45 4d 50 20 74 61 62 6c  he non-TEMP tabl
11570 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  e.  For example,
11580 0a 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .in the followin
11590 67 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20  g statement, it 
115a0 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20  is important to 
115b0 73 61 79 20 22 6d 61 69 6e 2e 74 61 62 31 22 20  say "main.tab1" 
115c0 69 6e 73 74 65 61 64 0a 6f 66 20 6a 75 73 74 20  instead.of just 
115d0 22 74 61 62 31 22 3a 3c 2f 70 3e 0a 0a 3c 62 6c  "tab1":</p>..<bl
115e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43  ockquote><pre>.C
115f0 52 45 41 54 45 20 54 45 4d 50 20 54 52 49 47 47  REATE TEMP TRIGG
11600 45 52 20 65 78 31 20 41 46 54 45 52 20 49 4e 53  ER ex1 AFTER INS
11610 45 52 54 20 4f 4e 20 3c 62 3e 6d 61 69 6e 2e 3c  ERT ON <b>main.<
11620 2f 62 3e 74 61 62 31 20 42 45 47 49 4e 20 2e 2e  /b>tab1 BEGIN ..
11630 2e 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ..</pre></blockq
11640 75 6f 74 65 3e 0a 0a 3c 70 3e 46 61 69 6c 75 72  uote>..<p>Failur
11650 65 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  e to specify the
11660 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 6f 6e 20   schema name on 
11670 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
11680 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 0a 69 6e   could result.in
11690 20 74 68 65 20 54 45 4d 50 20 74 72 69 67 67 65   the TEMP trigge
116a0 72 20 62 65 69 6e 67 20 72 65 61 74 74 61 63 68  r being reattach
116b0 65 64 20 74 6f 20 61 20 74 61 62 6c 65 20 77 69  ed to a table wi
116c0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
116d0 20 69 6e 0a 61 6e 6f 74 68 65 72 20 64 61 74 61   in.another data
116e0 62 61 73 65 20 77 68 65 6e 65 76 65 72 20 61 6e  base whenever an
116f0 79 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 20  y schema change 
11700 6f 63 63 75 72 73 2e 3c 2f 70 3e 0a 0a 3c 74 63  occurs.</p>..<tc
11710 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23  l>.#############
11720 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11730 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11740 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11750 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11760 23 23 0a 53 65 63 74 69 6f 6e 20 7b 43 52 45 41  ##.Section {CREA
11770 54 45 20 56 49 45 57 7d 20 7b 63 72 65 61 74 65  TE VIEW} {create
11780 76 69 65 77 7d 20 7b 7b 43 52 45 41 54 45 20 56  view} {{CREATE V
11790 49 45 57 7d 20 76 69 65 77 20 56 49 45 57 20 2a  IEW} view VIEW *
117a0 76 69 65 77 73 7d 0a 0a 52 65 63 75 72 73 69 76  views}..Recursiv
117b0 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63  eBubbleDiagram c
117c0 72 65 61 74 65 2d 76 69 65 77 2d 73 74 6d 74 0a  reate-view-stmt.
117d0 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20  </tcl>..<p>^The 
117e0 43 52 45 41 54 45 20 56 49 45 57 20 63 6f 6d 6d  CREATE VIEW comm
117f0 61 6e 64 20 61 73 73 69 67 6e 73 20 61 20 6e 61  and assigns a na
11800 6d 65 20 74 6f 20 61 20 70 72 65 2d 70 61 63 6b  me to a pre-pack
11810 61 67 65 64 20 0a 5b 53 45 4c 45 43 54 5d 20 73  aged .[SELECT] s
11820 74 61 74 65 6d 65 6e 74 2e 20 0a 5e 4f 6e 63 65  tatement. .^Once
11830 20 74 68 65 20 76 69 65 77 20 69 73 20 63 72 65   the view is cre
11840 61 74 65 64 2c 20 69 74 20 63 61 6e 20 62 65 20  ated, it can be 
11850 75 73 65 64 20 69 6e 20 74 68 65 20 46 52 4f 4d  used in the FROM
11860 20 63 6c 61 75 73 65 0a 6f 66 20 61 6e 6f 74 68   clause.of anoth
11870 65 72 20 5b 53 45 4c 45 43 54 5d 20 69 6e 20 70  er [SELECT] in p
11880 6c 61 63 65 20 6f 66 20 61 20 74 61 62 6c 65 20  lace of a table 
11890 6e 61 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e  name..</p>..<p>^
118a0 49 66 20 74 68 65 20 22 54 45 4d 50 22 20 6f 72  If the "TEMP" or
118b0 20 22 54 45 4d 50 4f 52 41 52 59 22 20 6b 65 79   "TEMPORARY" key
118c0 77 6f 72 64 20 6f 63 63 75 72 73 20 69 6e 20 62  word occurs in b
118d0 65 74 77 65 65 6e 20 22 43 52 45 41 54 45 22 0a  etween "CREATE".
118e0 61 6e 64 20 22 56 49 45 57 22 20 74 68 65 6e 20  and "VIEW" then 
118f0 74 68 65 20 76 69 65 77 20 74 68 61 74 20 69 73  the view that is
11900 20 63 72 65 61 74 65 64 20 69 73 20 6f 6e 6c 79   created is only
11910 20 76 69 73 69 62 6c 65 20 74 6f 20 74 68 65 0a   visible to the.
11920 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11930 74 69 6f 6e 5d 20 74 68 61 74 20 63 72 65 61 74  tion] that creat
11940 65 64 20 69 74 20 61 6e 64 20 69 73 20 61 75 74  ed it and is aut
11950 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
11960 65 64 20 77 68 65 6e 0a 74 68 65 20 64 61 74 61  ed when.the data
11970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11980 69 73 20 63 6c 6f 73 65 64 2e 3c 2f 70 3e 0a 0a  is closed.</p>..
11990 3c 70 3e 20 5e 49 66 20 61 20 3c 79 79 74 65 72  <p> ^If a <yyter
119a0 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79  m>schema-name</y
119b0 79 74 65 72 6d 3e 20 69 73 20 73 70 65 63 69 66  yterm> is specif
119c0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 76 69  ied, then the vi
119d0 65 77 20 0a 69 73 20 63 72 65 61 74 65 64 20 69  ew .is created i
119e0 6e 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  n the specified 
119f0 64 61 74 61 62 61 73 65 2e 0a 5e 49 74 20 69 73  database..^It is
11a00 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
11a10 63 69 66 79 20 62 6f 74 68 20 61 20 3c 79 79 74  cify both a <yyt
11a20 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61 6d 65 3c  erm>schema-name<
11a30 2f 79 79 74 65 72 6d 3e 0a 61 6e 64 20 74 68 65  /yyterm>.and the
11a40 20 54 45 4d 50 20 6b 65 79 77 6f 72 64 20 6f 6e   TEMP keyword on
11a50 20 61 20 56 49 45 57 2c 20 75 6e 6c 65 73 73 20   a VIEW, unless 
11a60 74 68 65 20 3c 79 79 74 65 72 6d 3e 73 63 68 65  the <yyterm>sche
11a70 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  ma-name</yyterm>
11a80 20 0a 69 73 20 22 74 65 6d 70 22 2e 0a 5e 49 66   .is "temp"..^If
11a90 20 6e 6f 20 73 63 68 65 6d 61 20 6e 61 6d 65 20   no schema name 
11aa0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 61 6e  is specified, an
11ab0 64 20 74 68 65 20 54 45 4d 50 20 6b 65 79 77 6f  d the TEMP keywo
11ac0 72 64 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e  rd is not presen
11ad0 74 2c 0a 74 68 65 20 56 49 45 57 20 69 73 20 63  t,.the VIEW is c
11ae0 72 65 61 74 65 64 20 69 6e 20 74 68 65 20 6d 61  reated in the ma
11af0 69 6e 20 64 61 74 61 62 61 73 65 2e 3c 2f 70 3e  in database.</p>
11b00 0a 0a 3c 70 3e 5e 59 6f 75 20 63 61 6e 6e 6f 74  ..<p>^You cannot
11b10 20 5b 44 45 4c 45 54 45 5d 2c 20 5b 49 4e 53 45   [DELETE], [INSE
11b20 52 54 5d 2c 20 6f 72 20 5b 55 50 44 41 54 45 5d  RT], or [UPDATE]
11b30 20 61 20 76 69 65 77 2e 20 20 5e 56 69 65 77 73   a view.  ^Views
11b40 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   are read-only .
11b50 69 6e 20 53 51 4c 69 74 65 2e 20 20 5e 48 6f 77  in SQLite.  ^How
11b60 65 76 65 72 2c 20 69 6e 20 6d 61 6e 79 20 63 61  ever, in many ca
11b70 73 65 73 20 79 6f 75 20 63 61 6e 20 75 73 65 20  ses you can use 
11b80 61 6e 0a 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an.[INSTEAD OF t
11b90 72 69 67 67 65 72 5d 20 6f 6e 20 74 68 65 20 76  rigger] on the v
11ba0 69 65 77 20 74 6f 20 61 63 63 6f 6d 70 6c 69 73  iew to accomplis
11bb0 68 20 0a 74 68 65 20 73 61 6d 65 20 74 68 69 6e  h .the same thin
11bc0 67 2e 20 20 5e 56 69 65 77 73 20 61 72 65 20 72  g.  ^Views are r
11bd0 65 6d 6f 76 65 64 20 0a 77 69 74 68 20 74 68 65  emoved .with the
11be0 20 5b 44 52 4f 50 20 56 49 45 57 5d 20 63 6f 6d   [DROP VIEW] com
11bf0 6d 61 6e 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49  mand.</p>..<p>^I
11c00 66 20 61 20 3c 79 79 74 65 72 6d 3e 63 6f 6c 75  f a <yyterm>colu
11c10 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e  mn-name</yyterm>
11c20 20 6c 69 73 74 20 66 6f 6c 6c 6f 77 73 20 0a 74   list follows .t
11c30 68 65 20 3c 79 79 74 65 72 6d 3e 76 69 65 77 2d  he <yyterm>view-
11c40 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2c 20 74  name</yyterm>, t
11c50 68 65 6e 20 74 68 61 74 20 6c 69 73 74 20 64 65  hen that list de
11c60 74 65 72 6d 69 6e 65 73 0a 74 68 65 20 6e 61 6d  termines.the nam
11c70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
11c80 73 20 66 6f 72 20 74 68 65 20 76 69 65 77 2e 20  s for the view. 
11c90 20 5e 49 66 20 74 68 65 20 3c 79 79 74 65 72 6d   ^If the <yyterm
11ca0 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79  >column-name</yy
11cb0 74 65 72 6d 3e 0a 6c 69 73 74 20 69 73 20 6f 6d  term>.list is om
11cc0 69 74 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  itted, then the 
11cd0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
11ce0 75 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 65 77  umns in the view
11cf0 20 61 72 65 20 64 65 72 69 76 65 64 0a 66 72 6f   are derived.fro
11d00 6d 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  m the names of t
11d10 68 65 20 72 65 73 75 6c 74 2d 73 65 74 20 63 6f  he result-set co
11d20 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 73 65  lumns in the [se
11d30 6c 65 63 74 2d 73 74 6d 74 5d 2e 0a 54 68 65 20  lect-stmt]..The 
11d40 75 73 65 20 6f 66 20 3c 79 79 74 65 72 6d 3e 63  use of <yyterm>c
11d50 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65  olumn-name</yyte
11d60 72 6d 3e 20 6c 69 73 74 20 69 73 20 72 65 63 6f  rm> list is reco
11d70 6d 6d 65 6e 64 65 64 2e 20 20 4f 72 2c 20 69 66  mmended.  Or, if
11d80 0a 3c 79 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e 2d  .<yyterm>column-
11d90 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 6c 69  name</yyterm> li
11da0 73 74 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 74  st is omitted, t
11db0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 0a 63  hen the result.c
11dc0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 53  olumns in the [S
11dd0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
11de0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
11df0 65 20 76 69 65 77 20 73 68 6f 75 6c 64 20 68 61  e view should ha
11e00 76 65 0a 77 65 6c 6c 2d 64 65 66 69 6e 65 64 20  ve.well-defined 
11e10 6e 61 6d 65 73 20 75 73 69 6e 67 20 74 68 65 20  names using the 
11e20 0a 22 5b 72 65 73 75 6c 74 2d 63 6f 6c 75 6d 6e  ."[result-column
11e30 7c 41 53 20 63 6f 6c 75 6d 6e 2d 61 6c 69 61 73  |AS column-alias
11e40 5d 22 20 73 79 6e 74 61 78 2e 0a 53 51 4c 69 74  ]" syntax..SQLit
11e50 65 20 61 6c 6c 6f 77 73 20 79 6f 75 20 74 6f 20  e allows you to 
11e60 63 72 65 61 74 65 20 76 69 65 77 73 20 74 68 61  create views tha
11e70 74 20 64 65 70 65 6e 64 20 6f 6e 20 61 75 74 6f  t depend on auto
11e80 6d 61 74 69 63 61 6c 6c 79 20 0a 67 65 6e 65 72  matically .gener
11e90 61 74 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ated column name
11ea0 73 2c 20 62 75 74 20 79 6f 75 20 73 68 6f 75 6c  s, but you shoul
11eb0 64 20 61 76 6f 69 64 20 75 73 69 6e 67 20 74 68  d avoid using th
11ec0 65 6d 20 73 69 6e 63 65 20 74 68 65 20 0a 72 75  em since the .ru
11ed0 6c 65 73 20 75 73 65 64 20 74 6f 20 67 65 6e 65  les used to gene
11ee0 72 61 74 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  rate column name
11ef0 73 20 61 72 65 20 6e 6f 74 20 61 20 64 65 66 69  s are not a defi
11f00 6e 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 0a  ned part of the.
11f10 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 6d 69  interface and mi
11f20 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 66 75  ght change in fu
11f30 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
11f40 20 53 51 4c 69 74 65 2e 0a 0a 3c 70 3e 54 68 65   SQLite...<p>The
11f50 20 3c 79 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e 2d   <yyterm>column-
11f60 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 6c 69  name</yyterm> li
11f70 73 74 20 73 79 6e 74 61 78 20 77 61 73 20 61 64  st syntax was ad
11f80 64 65 64 20 69 6e 0a 53 51 4c 69 74 65 20 76 65  ded in.SQLite ve
11f90 72 73 69 6f 6e 73 20 33 2e 39 2e 30 20 28 5b 64  rsions 3.9.0 ([d
11fa0 61 74 65 6f 66 3a 33 2e 39 2e 30 5d 29 2e 0a 0a  ateof:3.9.0])...
11fb0 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23  <tcl>.##########
11fc0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11fd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11fe0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
11ff0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12000 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 43 52  ####.Section {CR
12010 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
12020 4c 45 7d 20 7b 63 72 65 61 74 65 76 74 61 62 7d  LE} {createvtab}
12030 20 7b 7b 43 52 45 41 54 45 20 56 49 52 54 55 41   {{CREATE VIRTUA
12040 4c 20 54 41 42 4c 45 7d 7d 0a 0a 52 65 63 75 72  L TABLE}}..Recur
12050 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61  siveBubbleDiagra
12060 6d 20 63 72 65 61 74 65 2d 76 69 72 74 75 61 6c  m create-virtual
12070 2d 74 61 62 6c 65 2d 73 74 6d 74 0a 3c 2f 74 63  -table-stmt.</tc
12080 6c 3e 0a 0a 3c 70 3e 41 20 5b 76 69 72 74 75 61  l>..<p>A [virtua
12090 6c 20 74 61 62 6c 65 5d 20 69 73 20 61 6e 20 69  l table] is an i
120a0 6e 74 65 72 66 61 63 65 20 74 6f 20 61 6e 20 65  nterface to an e
120b0 78 74 65 72 6e 61 6c 20 73 74 6f 72 61 67 65 20  xternal storage 
120c0 6f 72 20 63 6f 6d 70 75 74 61 74 69 6f 6e 0a 65  or computation.e
120d0 6e 67 69 6e 65 20 74 68 61 74 20 61 70 70 65 61  ngine that appea
120e0 72 73 20 74 6f 20 62 65 20 61 20 74 61 62 6c 65  rs to be a table
120f0 20 62 75 74 20 64 6f 65 73 20 6e 6f 74 20 61 63   but does not ac
12100 74 75 61 6c 6c 79 20 73 74 6f 72 65 20 69 6e 66  tually store inf
12110 6f 72 6d 61 74 69 6f 6e 0a 69 6e 20 74 68 65 20  ormation.in the 
12120 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 3c 2f  database file.</
12130 70 3e 0a 0a 3c 70 3e 49 6e 20 67 65 6e 65 72 61  p>..<p>In genera
12140 6c 2c 20 79 6f 75 20 63 61 6e 20 64 6f 20 61 6e  l, you can do an
12150 79 74 68 69 6e 67 20 77 69 74 68 20 61 20 5b 76  ything with a [v
12160 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 74 68  irtual table] th
12170 61 74 20 63 61 6e 20 62 65 20 64 6f 6e 65 0a 77  at can be done.w
12180 69 74 68 20 61 6e 20 6f 72 64 69 6e 61 72 79 20  ith an ordinary 
12190 74 61 62 6c 65 2c 20 65 78 63 65 70 74 20 74 68  table, except th
121a0 61 74 20 5e 79 6f 75 20 63 61 6e 6e 6f 74 20 63  at ^you cannot c
121b0 72 65 61 74 65 20 69 6e 64 69 63 65 73 20 6f 72  reate indices or
121c0 20 74 72 69 67 67 65 72 73 20 6f 6e 20 61 0a 76   triggers on a.v
121d0 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 5e  irtual table.  ^
121e0 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
121f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
12200 6e 73 20 6d 69 67 68 74 20 69 6d 70 6f 73 65 20  ns might impose 
12210 61 64 64 69 74 69 6f 6e 61 6c 0a 72 65 73 74 72  additional.restr
12220 69 63 74 69 6f 6e 73 2e 20 20 46 6f 72 20 65 78  ictions.  For ex
12230 61 6d 70 6c 65 2c 20 6d 61 6e 79 20 76 69 72 74  ample, many virt
12240 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 72  ual tables are r
12250 65 61 64 2d 6f 6e 6c 79 2e 3c 2f 70 3e 0a 0a 3c  ead-only.</p>..<
12260 70 3e 54 68 65 20 3c 79 79 74 65 72 6d 3e 6d 6f  p>The <yyterm>mo
12270 64 75 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72  dule-name</yyter
12280 6d 3e 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  m> is the name o
12290 66 20 61 6e 20 6f 62 6a 65 63 74 20 74 68 61 74  f an object that
122a0 20 69 6d 70 6c 65 6d 65 6e 74 73 0a 74 68 65 20   implements.the 
122b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
122c0 5e 54 68 65 20 3c 79 79 74 65 72 6d 3e 6d 6f 64  ^The <yyterm>mod
122d0 75 6c 65 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d  ule-name</yyterm
122e0 3e 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  > must be regist
122f0 65 72 65 64 20 77 69 74 68 0a 74 68 65 20 53 51  ered with.the SQ
12300 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 63 6f  Lite database co
12310 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 5b  nnection using.[
12320 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
12330 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
12340 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
12350 6c 65 5f 76 32 28 29 5d 0a 70 72 69 6f 72 20 74  le_v2()].prior t
12360 6f 20 69 73 73 75 69 6e 67 20 74 68 65 20 43 52  o issuing the CR
12370 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
12380 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 0a 5e 54  LE statement..^T
12390 68 65 20 6d 6f 64 75 6c 65 20 74 61 6b 65 73 20  he module takes 
123a0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6d  zero or more com
123b0 6d 61 2d 73 65 70 61 72 61 74 65 64 20 61 72 67  ma-separated arg
123c0 75 6d 65 6e 74 73 2e 0a 5e 54 68 65 20 61 72 67  uments..^The arg
123d0 75 6d 65 6e 74 73 20 63 61 6e 20 62 65 20 6a 75  uments can be ju
123e0 73 74 20 61 62 6f 75 74 20 61 6e 79 20 74 65 78  st about any tex
123f0 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 69 74 20  t as long as it 
12400 68 61 73 20 62 61 6c 61 6e 63 65 64 0a 70 61 72  has balanced.par
12410 65 6e 74 68 65 73 65 73 2e 20 20 54 68 65 20 61  entheses.  The a
12420 72 67 75 6d 65 6e 74 20 73 79 6e 74 61 78 20 69  rgument syntax i
12430 73 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 67  s sufficiently g
12440 65 6e 65 72 61 6c 20 74 68 61 74 20 74 68 65 0a  eneral that the.
12450 61 72 67 75 6d 65 6e 74 73 20 63 61 6e 20 62 65  arguments can be
12460 20 6d 61 64 65 20 74 6f 20 61 70 70 65 61 72 20   made to appear 
12470 61 73 20 5b 63 6f 6c 75 6d 6e 20 64 65 66 69 6e  as [column defin
12480 69 74 69 6f 6e 73 5d 20 69 6e 20 61 20 74 72 61  itions] in a tra
12490 64 69 74 69 6f 6e 61 6c 0a 5b 43 52 45 41 54 45  ditional.[CREATE
124a0 20 54 41 42 4c 45 5d 20 73 74 61 74 65 6d 65 6e   TABLE] statemen
124b0 74 2e 20 20 0a 5e 53 51 4c 69 74 65 20 70 61 73  t.  .^SQLite pas
124c0 73 65 73 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ses the module a
124d0 72 67 75 6d 65 6e 74 73 20 64 69 72 65 63 74 6c  rguments directl
124e0 79 0a 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74  y.to the [xCreat
124f0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
12500 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  ] methods of the
12510 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
12520 74 61 74 69 6f 6e 0a 77 69 74 68 6f 75 74 20 61  tation.without a
12530 6e 79 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ny interpretatio
12540 6e 2e 20 20 49 74 20 69 73 20 74 68 65 20 72 65  n.  It is the re
12550 73 70 6f 6e 73 69 62 69 6c 69 74 79 0a 6f 66 20  sponsibility.of 
12560 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  the module imple
12570 6d 65 6e 74 61 74 69 6f 6e 20 74 6f 20 70 61 72  mentation to par
12580 73 65 20 61 6e 64 20 69 6e 74 65 72 70 72 65 74  se and interpret
12590 20 69 74 73 20 6f 77 6e 20 61 72 67 75 6d 65 6e   its own argumen
125a0 74 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 41 20 76  ts.</p>..<p>^A v
125b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
125c0 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20  destroyed using 
125d0 74 68 65 20 6f 72 64 69 6e 61 72 79 0a 5b 44 52  the ordinary.[DR
125e0 4f 50 20 54 41 42 4c 45 5d 20 73 74 61 74 65 6d  OP TABLE] statem
125f0 65 6e 74 2e 20 20 54 68 65 72 65 20 69 73 20 6e  ent.  There is n
12600 6f 0a 44 52 4f 50 20 56 49 52 54 55 41 4c 20 54  o.DROP VIRTUAL T
12610 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 3c  ABLE statement.<
12620 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  /p>..<tcl>.#####
12630 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12640 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12650 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12660 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
12670 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
12680 6e 20 44 45 4c 45 54 45 20 64 65 6c 65 74 65 20  n DELETE delete 
12690 7b 44 45 4c 45 54 45 20 2a 44 45 4c 45 54 45 73  {DELETE *DELETEs
126a0 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
126b0 6c 65 44 69 61 67 72 61 6d 20 64 65 6c 65 74 65  leDiagram delete
126c0 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70  -stmt.</tcl>..<p
126d0 3e 54 68 65 20 44 45 4c 45 54 45 20 63 6f 6d 6d  >The DELETE comm
126e0 61 6e 64 20 72 65 6d 6f 76 65 73 20 72 65 63 6f  and removes reco
126f0 72 64 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  rds from the tab
12700 6c 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  le identified by
12710 20 74 68 65 0a 20 20 20 5b 71 75 61 6c 69 66 69   the.   [qualifi
12720 65 64 2d 74 61 62 6c 65 2d 6e 61 6d 65 5d 2e 0a  ed-table-name]..
12730 0a 3c 70 3e 5e 49 66 20 74 68 65 20 57 48 45 52  .<p>^If the WHER
12740 45 20 63 6c 61 75 73 65 20 69 73 20 6e 6f 74 20  E clause is not 
12750 70 72 65 73 65 6e 74 2c 20 61 6c 6c 20 72 65 63  present, all rec
12760 6f 72 64 73 20 69 6e 20 74 68 65 20 74 61 62 6c  ords in the tabl
12770 65 20 61 72 65 20 64 65 6c 65 74 65 64 2e 0a 20  e are deleted.. 
12780 20 20 5e 49 66 20 61 20 57 48 45 52 45 20 63 6c    ^If a WHERE cl
12790 61 75 73 65 20 69 73 20 73 75 70 70 6c 69 65 64  ause is supplied
127a0 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 6f 73  , then only thos
127b0 65 20 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68  e rows for which
127c0 20 74 68 65 0a 20 20 20 57 48 45 52 45 20 63 6c   the.   WHERE cl
127d0 61 75 73 65 20 5b 62 6f 6f 6c 65 61 6e 20 65 78  ause [boolean ex
127e0 70 72 65 73 73 69 6f 6e 5d 20 69 73 20 74 72 75  pression] is tru
127f0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2e 0a 20  e are deleted.. 
12800 20 20 5e 52 6f 77 73 20 66 6f 72 20 77 68 69 63    ^Rows for whic
12810 68 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e  h the expression
12820 20 69 73 20 66 61 6c 73 65 20 6f 72 20 4e 55 4c   is false or NUL
12830 4c 20 61 72 65 20 72 65 74 61 69 6e 65 64 2e 0a  L are retained..
12840 0a 3c 68 33 3e 52 65 73 74 72 69 63 74 69 6f 6e  .<h3>Restriction
12850 73 20 6f 6e 20 44 45 4c 45 54 45 20 53 74 61 74  s on DELETE Stat
12860 65 6d 65 6e 74 73 20 57 69 74 68 69 6e 20 43 52  ements Within CR
12870 45 41 54 45 20 54 52 49 47 47 45 52 3c 2f 68 33  EATE TRIGGER</h3
12880 3e 0a 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f 77  >..<p>The follow
12890 69 6e 67 20 72 65 73 74 72 69 63 74 69 6f 6e 73  ing restrictions
128a0 20 61 70 70 6c 79 20 74 6f 20 44 45 4c 45 54 45   apply to DELETE
128b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
128c0 20 6f 63 63 75 72 20 77 69 74 68 69 6e 20 74 68   occur within th
128d0 65 0a 20 20 20 62 6f 64 79 20 6f 66 20 61 20 5b  e.   body of a [
128e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 5d 20  CREATE TRIGGER] 
128f0 73 74 61 74 65 6d 65 6e 74 3a 0a 0a 3c 75 6c 3e  statement:..<ul>
12900 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 3c  .  <li><p>^The <
12910 79 79 74 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d  yyterm>table-nam
12920 65 3c 2f 79 79 74 65 72 6d 3e 20 73 70 65 63 69  e</yyterm> speci
12930 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
12940 61 20 0a 20 20 20 20 44 45 4c 45 54 45 20 73 74  a .    DELETE st
12950 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 0a 20  atement within. 
12960 20 20 20 61 20 74 72 69 67 67 65 72 20 62 6f 64     a trigger bod
12970 79 20 6d 75 73 74 20 62 65 20 75 6e 71 75 61 6c  y must be unqual
12980 69 66 69 65 64 2e 20 20 5e 28 49 6e 20 6f 74 68  ified.  ^(In oth
12990 65 72 20 77 6f 72 64 73 2c 20 74 68 65 0a 20 20  er words, the.  
129a0 20 20 3c 69 3e 73 63 68 65 6d 61 2d 6e 61 6d 65    <i>schema-name
129b0 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62 3e 20 70 72 65  </i><b>.</b> pre
129c0 66 69 78 20 6f 6e 20 74 68 65 20 74 61 62 6c 65  fix on the table
129d0 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 61 6c 6c   name is not all
129e0 6f 77 65 64 20 0a 20 20 20 20 77 69 74 68 69 6e  owed .    within
129f0 20 74 72 69 67 67 65 72 73 2e 29 5e 20 5e 49 66   triggers.)^ ^If
12a00 20 74 68 65 20 74 61 62 6c 65 20 74 6f 20 77 68   the table to wh
12a10 69 63 68 20 74 68 65 20 74 72 69 67 67 65 72 20  ich the trigger 
12a20 69 73 20 61 74 74 61 63 68 65 64 20 69 73 0a 20  is attached is. 
12a30 20 20 20 6e 6f 74 20 69 6e 20 74 68 65 20 74 65     not in the te
12a40 6d 70 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  mp database, the
12a50 6e 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  n DELETE stateme
12a60 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 74  nts within the t
12a70 72 69 67 67 65 72 0a 20 20 20 20 62 6f 64 79 20  rigger.    body 
12a80 6d 75 73 74 20 6f 70 65 72 61 74 65 20 6f 6e 20  must operate on 
12a90 74 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 68  tables within th
12aa0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
12ab0 61 73 20 69 74 2e 20 5e 49 66 20 74 68 65 20 74  as it. ^If the t
12ac0 61 62 6c 65 0a 20 20 20 20 74 6f 20 77 68 69 63  able.    to whic
12ad0 68 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  h the trigger is
12ae0 20 61 74 74 61 63 68 65 64 20 69 73 20 69 6e 20   attached is in 
12af0 74 68 65 20 54 45 4d 50 20 64 61 74 61 62 61 73  the TEMP databas
12b00 65 2c 20 74 68 65 6e 20 74 68 65 0a 20 20 20 20  e, then the.    
12b10 75 6e 71 75 61 6c 69 66 69 65 64 20 6e 61 6d 65  unqualified name
12b20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 62 65   of the table be
12b30 69 6e 67 20 64 65 6c 65 74 65 64 20 69 73 20 72  ing deleted is r
12b40 65 73 6f 6c 76 65 64 20 69 6e 20 74 68 65 20 73  esolved in the s
12b50 61 6d 65 20 77 61 79 20 61 73 0a 20 20 20 20 69  ame way as.    i
12b60 74 20 69 73 20 66 6f 72 20 61 20 74 6f 70 2d 6c  t is for a top-l
12b70 65 76 65 6c 20 73 74 61 74 65 6d 65 6e 74 20 28  evel statement (
12b80 62 79 20 73 65 61 72 63 68 69 6e 67 20 66 69 72  by searching fir
12b90 73 74 20 74 68 65 20 54 45 4d 50 20 64 61 74 61  st the TEMP data
12ba0 62 61 73 65 2c 20 74 68 65 6e 0a 20 20 20 20 74  base, then.    t
12bb0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
12bc0 2c 20 74 68 65 6e 20 61 6e 79 20 6f 74 68 65 72  , then any other
12bd0 20 64 61 74 61 62 61 73 65 73 20 69 6e 20 74 68   databases in th
12be0 65 20 6f 72 64 65 72 20 74 68 65 79 20 77 65 72  e order they wer
12bf0 65 0a 20 20 20 20 61 74 74 61 63 68 65 64 29 2e  e.    attached).
12c00 0a 20 20 20 20 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  .    .  <li><p>^
12c10 54 68 65 20 49 4e 44 45 58 45 44 20 42 59 20 61  The INDEXED BY a
12c20 6e 64 20 4e 4f 54 20 49 4e 44 45 58 45 44 20 63  nd NOT INDEXED c
12c30 6c 61 75 73 65 73 20 61 72 65 20 6e 6f 74 20 61  lauses are not a
12c40 6c 6c 6f 77 65 64 20 6f 6e 20 44 45 4c 45 54 45  llowed on DELETE
12c50 0a 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20  .    statements 
12c60 77 69 74 68 69 6e 20 74 72 69 67 67 65 72 73 2e  within triggers.
12c70 3c 2f 70 3e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e  </p>..  <li><p>^
12c80 54 68 65 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52  The LIMIT and OR
12c90 44 45 52 20 42 59 20 63 6c 61 75 73 65 73 20 28  DER BY clauses (
12ca0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 29  described below)
12cb0 20 61 72 65 20 75 6e 73 75 70 70 6f 72 74 65 64   are unsupported
12cc0 20 66 6f 72 0a 20 20 20 20 44 45 4c 45 54 45 20   for.    DELETE 
12cd0 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 69  statements withi
12ce0 6e 20 74 72 69 67 67 65 72 73 2e 3c 2f 70 3e 0a  n triggers.</p>.
12cf0 3c 2f 75 6c 3e 0a 0a 3c 68 33 3e 4f 70 74 69 6f  </ul>..<h3>Optio
12d00 6e 61 6c 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52  nal LIMIT and OR
12d10 44 45 52 20 42 59 20 63 6c 61 75 73 65 73 3c 2f  DER BY clauses</
12d20 68 33 3e 0a 0a 3c 70 3e 5e 28 49 66 20 53 51 4c  h3>..<p>^(If SQL
12d30 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12d40 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
12d50 5f 45 4e 41 42 4c 45 5f 55 50 44 41 54 45 5f 44  _ENABLE_UPDATE_D
12d60 45 4c 45 54 45 5f 4c 49 4d 49 54 5d 0a 63 6f 6d  ELETE_LIMIT].com
12d70 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12d80 2c 20 74 68 65 6e 20 74 68 65 20 73 79 6e 74 61  , then the synta
12d90 78 20 6f 66 20 74 68 65 20 44 45 4c 45 54 45 20  x of the DELETE 
12da0 73 74 61 74 65 6d 65 6e 74 20 69 73 0a 65 78 74  statement is.ext
12db0 65 6e 64 65 64 20 62 79 20 74 68 65 20 61 64 64  ended by the add
12dc0 69 74 69 6f 6e 20 6f 66 20 6f 70 74 69 6f 6e 61  ition of optiona
12dd0 6c 20 4f 52 44 45 52 20 42 59 20 61 6e 64 20 4c  l ORDER BY and L
12de0 49 4d 49 54 20 63 6c 61 75 73 65 73 3a 29 5e 3c  IMIT clauses:)^<
12df0 2f 70 3e 0a 0a 3c 74 63 6c 3e 42 75 62 62 6c 65  /p>..<tcl>Bubble
12e00 44 69 61 67 72 61 6d 20 64 65 6c 65 74 65 2d 73  Diagram delete-s
12e10 74 6d 74 2d 6c 69 6d 69 74 65 64 3c 2f 74 63 6c  tmt-limited</tcl
12e20 3e 0a 0a 3c 70 3e 5e 49 66 20 61 20 44 45 4c 45  >..<p>^If a DELE
12e30 54 45 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  TE statement has
12e40 20 61 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 2c   a LIMIT clause,
12e50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12e60 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74  ber of rows that
12e70 0a 77 69 6c 6c 20 62 65 20 64 65 6c 65 74 65 64  .will be deleted
12e80 20 69 73 20 66 6f 75 6e 64 20 62 79 20 65 76 61   is found by eva
12e90 6c 75 61 74 69 6e 67 20 74 68 65 20 61 63 63 6f  luating the acco
12ea0 6d 70 61 6e 79 69 6e 67 20 65 78 70 72 65 73 73  mpanying express
12eb0 69 6f 6e 20 61 6e 64 20 63 61 73 74 69 6e 67 0a  ion and casting.
12ec0 69 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  it to an integer
12ed0 20 76 61 6c 75 65 2e 20 5e 49 66 20 74 68 65 20   value. ^If the 
12ee0 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 65 76  result of the ev
12ef0 61 6c 75 61 74 69 6e 67 20 74 68 65 20 4c 49 4d  aluating the LIM
12f00 49 54 20 63 6c 61 75 73 65 0a 63 61 6e 6e 6f 74  IT clause.cannot
12f10 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 20 63   be losslessly c
12f20 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20 69  onverted to an i
12f30 6e 74 65 67 65 72 20 76 61 6c 75 65 2c 20 69 74  nteger value, it
12f40 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 41   is an error. ^A
12f50 20 0a 6e 65 67 61 74 69 76 65 20 4c 49 4d 49 54   .negative LIMIT
12f60 20 76 61 6c 75 65 20 69 73 20 69 6e 74 65 72 70   value is interp
12f70 72 65 74 65 64 20 61 73 20 22 6e 6f 20 6c 69 6d  reted as "no lim
12f80 69 74 22 2e 20 5e 28 49 66 20 74 68 65 20 44 45  it". ^(If the DE
12f90 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 0a  LETE statement .
12fa0 61 6c 73 6f 20 68 61 73 20 61 6e 20 4f 46 46 53  also has an OFFS
12fb0 45 54 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20  ET clause, then 
12fc0 69 74 20 69 73 20 73 69 6d 69 6c 61 72 6c 79 20  it is similarly 
12fd0 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 63 61  evaluated and ca
12fe0 73 74 20 74 6f 20 61 6e 0a 69 6e 74 65 67 65 72  st to an.integer
12ff0 20 76 61 6c 75 65 2e 20 41 67 61 69 6e 2c 20 69   value. Again, i
13000 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
13010 20 74 68 65 20 76 61 6c 75 65 20 63 61 6e 6e 6f   the value canno
13020 74 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 0a  t be losslessly.
13030 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20  converted to an 
13040 69 6e 74 65 67 65 72 2e 29 5e 20 5e 49 66 20 74  integer.)^ ^If t
13050 68 65 72 65 20 69 73 20 6e 6f 20 4f 46 46 53 45  here is no OFFSE
13060 54 20 63 6c 61 75 73 65 2c 20 6f 72 20 74 68 65  T clause, or the
13070 20 63 61 6c 63 75 6c 61 74 65 64 0a 69 6e 74 65   calculated.inte
13080 67 65 72 20 76 61 6c 75 65 20 69 73 20 6e 65 67  ger value is neg
13090 61 74 69 76 65 2c 20 74 68 65 20 65 66 66 65 63  ative, the effec
130a0 74 69 76 65 20 4f 46 46 53 45 54 20 76 61 6c 75  tive OFFSET valu
130b0 65 20 69 73 20 7a 65 72 6f 2e 0a 0a 3c 70 3e 5e  e is zero...<p>^
130c0 28 49 66 20 74 68 65 20 44 45 4c 45 54 45 20 73  (If the DELETE s
130d0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 61 6e 20  tatement has an 
130e0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c  ORDER BY clause,
130f0 20 74 68 65 6e 20 61 6c 6c 20 72 6f 77 73 20 74   then all rows t
13100 68 61 74 20 77 6f 75 6c 64 20 0a 62 65 20 64 65  hat would .be de
13110 6c 65 74 65 64 20 69 6e 20 74 68 65 20 61 62 73  leted in the abs
13120 65 6e 63 65 20 6f 66 20 74 68 65 20 4c 49 4d 49  ence of the LIMI
13130 54 20 63 6c 61 75 73 65 20 61 72 65 20 73 6f 72  T clause are sor
13140 74 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ted according to
13150 20 74 68 65 20 0a 4f 52 44 45 52 20 42 59 2e 20   the .ORDER BY. 
13160 54 68 65 20 66 69 72 73 74 20 3c 69 3e 4d 3c 2f  The first <i>M</
13170 69 3e 20 72 6f 77 73 2c 20 77 68 65 72 65 20 3c  i> rows, where <
13180 69 3e 4d 3c 2f 69 3e 20 69 73 20 74 68 65 20 76  i>M</i> is the v
13190 61 6c 75 65 20 66 6f 75 6e 64 20 62 79 0a 65 76  alue found by.ev
131a0 61 6c 75 61 74 69 6e 67 20 74 68 65 20 4f 46 46  aluating the OFF
131b0 53 45 54 20 63 6c 61 75 73 65 20 65 78 70 72 65  SET clause expre
131c0 73 73 69 6f 6e 2c 20 61 72 65 20 73 6b 69 70 70  ssion, are skipp
131d0 65 64 2c 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  ed, and the foll
131e0 6f 77 69 6e 67 20 0a 3c 69 3e 4e 3c 2f 69 3e 2c  owing .<i>N</i>,
131f0 20 77 68 65 72 65 20 3c 69 3e 4e 3c 2f 69 3e 20   where <i>N</i> 
13200 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
13210 74 68 65 20 4c 49 4d 49 54 20 65 78 70 72 65 73  the LIMIT expres
13220 73 69 6f 6e 2c 20 61 72 65 20 64 65 6c 65 74 65  sion, are delete
13230 64 2e 29 5e 0a 5e 49 66 20 74 68 65 72 65 20 61  d.)^.^If there a
13240 72 65 20 6c 65 73 73 20 74 68 61 6e 20 3c 69 3e  re less than <i>
13250 4e 3c 2f 69 3e 20 72 6f 77 73 20 72 65 6d 61 69  N</i> rows remai
13260 6e 69 6e 67 20 61 66 74 65 72 20 74 61 6b 69 6e  ning after takin
13270 67 20 74 68 65 20 4f 46 46 53 45 54 20 63 6c 61  g the OFFSET cla
13280 75 73 65 0a 69 6e 74 6f 20 61 63 63 6f 75 6e 74  use.into account
13290 2c 20 6f 72 20 69 66 20 74 68 65 20 4c 49 4d 49  , or if the LIMI
132a0 54 20 63 6c 61 75 73 65 20 65 76 61 6c 75 61 74  T clause evaluat
132b0 65 64 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  ed to a negative
132c0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
132d0 0a 72 65 6d 61 69 6e 69 6e 67 20 72 6f 77 73 20  .remaining rows 
132e0 61 72 65 20 64 65 6c 65 74 65 64 2e 0a 0a 3c 70  are deleted...<p
132f0 3e 5e 49 66 20 74 68 65 20 44 45 4c 45 54 45 20  >^If the DELETE 
13300 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 6e 6f  statement has no
13310 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
13320 2c 20 74 68 65 6e 20 61 6c 6c 20 72 6f 77 73 20  , then all rows 
13330 74 68 61 74 0a 77 6f 75 6c 64 20 62 65 20 64 65  that.would be de
13340 6c 65 74 65 64 20 69 6e 20 74 68 65 20 61 62 73  leted in the abs
13350 65 6e 63 65 20 6f 66 20 74 68 65 20 4c 49 4d 49  ence of the LIMI
13360 54 20 63 6c 61 75 73 65 20 61 72 65 20 61 73 73  T clause are ass
13370 65 6d 62 6c 65 64 20 69 6e 20 61 6e 0a 61 72 62  embled in an.arb
13380 69 74 72 61 72 79 20 6f 72 64 65 72 20 62 65 66  itrary order bef
13390 6f 72 65 20 61 70 70 6c 79 69 6e 67 20 74 68 65  ore applying the
133a0 20 4c 49 4d 49 54 20 61 6e 64 20 4f 46 46 53 45   LIMIT and OFFSE
133b0 54 20 63 6c 61 75 73 65 73 20 74 6f 20 64 65 74  T clauses to det
133c0 65 72 6d 69 6e 65 20 0a 74 68 65 20 73 75 62 73  ermine .the subs
133d0 65 74 20 74 68 61 74 20 61 72 65 20 61 63 74 75  et that are actu
133e0 61 6c 6c 79 20 64 65 6c 65 74 65 64 2e 0a 0a 3c  ally deleted...<
133f0 70 3e 5e 28 54 68 65 20 4f 52 44 45 52 20 42 59  p>^(The ORDER BY
13400 20 63 6c 61 75 73 65 20 6f 6e 20 61 20 44 45 4c   clause on a DEL
13410 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 69 73  ETE statement is
13420 20 75 73 65 64 20 6f 6e 6c 79 20 74 6f 20 64 65   used only to de
13430 74 65 72 6d 69 6e 65 20 77 68 69 63 68 0a 72 6f  termine which.ro
13440 77 73 20 66 61 6c 6c 20 77 69 74 68 69 6e 20 74  ws fall within t
13450 68 65 20 4c 49 4d 49 54 2e 20 54 68 65 20 6f 72  he LIMIT. The or
13460 64 65 72 20 69 6e 20 77 68 69 63 68 20 72 6f 77  der in which row
13470 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 73  s are deleted is
13480 20 61 72 62 69 74 72 61 72 79 0a 61 6e 64 20 69   arbitrary.and i
13490 73 20 6e 6f 74 20 69 6e 66 6c 75 65 6e 63 65 64  s not influenced
134a0 20 62 79 20 74 68 65 20 4f 52 44 45 52 20 42 59   by the ORDER BY
134b0 20 63 6c 61 75 73 65 2e 29 5e 0a 0a 3c 74 63 6c   clause.)^..<tcl
134c0 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 74 72 75  >hd_fragment tru
134d0 6e 63 61 74 65 6f 70 74 20 7b 74 72 75 6e 63 61  ncateopt {trunca
134e0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 7d  te optimization}
134f0 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 54  </tcl>.<h3>The T
13500 72 75 6e 63 61 74 65 20 4f 70 74 69 6d 69 7a 61  runcate Optimiza
13510 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 57  tion</h3>..<p>^W
13520 68 65 6e 20 74 68 65 20 57 48 45 52 45 20 69 73  hen the WHERE is
13530 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 20   omitted from a 
13540 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
13550 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 0a 62   and the table.b
13560 65 69 6e 67 20 64 65 6c 65 74 65 64 20 68 61 73  eing deleted has
13570 20 6e 6f 20 74 72 69 67 67 65 72 73 2c 0a 53 51   no triggers,.SQ
13580 4c 69 74 65 20 75 73 65 73 20 61 6e 20 6f 70 74  Lite uses an opt
13590 69 6d 69 7a 61 74 69 6f 6e 20 74 6f 20 65 72 61  imization to era
135a0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 74 61  se the entire ta
135b0 62 6c 65 20 63 6f 6e 74 65 6e 74 0a 77 69 74 68  ble content.with
135c0 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 76 69  out having to vi
135d0 73 69 74 20 65 61 63 68 20 72 6f 77 20 6f 66 20  sit each row of 
135e0 74 68 65 20 74 61 62 6c 65 20 69 6e 64 69 76 69  the table indivi
135f0 64 75 61 6c 6c 79 2e 0a 54 68 69 73 20 22 74 72  dually..This "tr
13600 75 6e 63 61 74 65 22 20 6f 70 74 69 6d 69 7a 61  uncate" optimiza
13610 74 69 6f 6e 20 6d 61 6b 65 73 20 74 68 65 20 64  tion makes the d
13620 65 6c 65 74 65 20 72 75 6e 20 6d 75 63 68 20 66  elete run much f
13630 61 73 74 65 72 2e 0a 50 72 69 6f 72 20 74 6f 20  aster..Prior to 
13640 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
13650 33 2e 36 2e 35 5d 20 28 5b 64 61 74 65 6f 66 3a  3.6.5] ([dateof:
13660 33 2e 36 2e 35 5d 29 2c 20 74 68 65 20 74 72 75  3.6.5]), the tru
13670 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
13680 6f 6e 0a 61 6c 73 6f 20 6d 65 61 6e 74 20 74 68  on.also meant th
13690 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
136a0 63 68 61 6e 67 65 73 28 29 5d 20 61 6e 64 0a 5b  changes()] and.[
136b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
136c0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
136d0 63 65 73 0a 61 6e 64 20 74 68 65 20 5b 63 6f 75  ces.and the [cou
136e0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
136f0 61 5d 0a 77 69 6c 6c 20 6e 6f 74 20 61 63 74 75  a].will not actu
13700 61 6c 6c 79 20 72 65 74 75 72 6e 20 74 68 65 20  ally return the 
13710 6e 75 6d 62 65 72 20 6f 66 20 64 65 6c 65 74 65  number of delete
13720 64 20 72 6f 77 73 2e 20 20 0a 54 68 61 74 20 70  d rows.  .That p
13730 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
13740 66 69 78 65 64 20 61 73 20 6f 66 20 5b 76 65 72  fixed as of [ver
13750 73 69 6f 6e 20 33 2e 36 2e 35 5d 20 28 5b 64 61  sion 3.6.5] ([da
13760 74 65 6f 66 3a 33 2e 36 2e 35 5d 29 2e 0a 0a 3c  teof:3.6.5])...<
13770 70 3e 5e 54 68 65 20 74 72 75 6e 63 61 74 65 20  p>^The truncate 
13780 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 63 61 6e  optimization can
13790 20 62 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79 20   be permanently 
137a0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6c 6c  disabled for all
137b0 20 71 75 65 72 69 65 73 0a 62 79 20 72 65 63 6f   queries.by reco
137c0 6d 70 69 6c 69 6e 67 0a 53 51 4c 69 74 65 20 77  mpiling.SQLite w
137d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
137e0 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
137f0 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
13800 69 6c 65 2d 74 69 6d 65 20 73 77 69 74 63 68 2e  ile-time switch.
13810 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 74 72 75  </p>..<p>The tru
13820 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
13830 6f 6e 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 64  on can also be d
13840 69 73 61 62 6c 65 64 20 61 74 20 72 75 6e 74 69  isabled at runti
13850 6d 65 20 75 73 69 6e 67 0a 74 68 65 20 5b 73 71  me using.the [sq
13860 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
13870 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
13880 65 2e 20 20 5e 49 66 20 61 6e 20 61 75 74 68 6f  e.  ^If an autho
13890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 72  rizer callback.r
138a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
138b0 47 4e 4f 52 45 5d 20 66 6f 72 20 61 6e 20 5b 53  GNORE] for an [S
138c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 63  QLITE_DELETE] ac
138d0 74 69 6f 6e 20 63 6f 64 65 2c 20 74 68 65 6e 0a  tion code, then.
138e0 74 68 65 20 44 45 4c 45 54 45 20 6f 70 65 72 61  the DELETE opera
138f0 74 69 6f 6e 20 77 69 6c 6c 20 70 72 6f 63 65 65  tion will procee
13900 64 20 62 75 74 20 74 68 65 20 74 72 75 6e 63 61  d but the trunca
13910 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  te optimization 
13920 77 69 6c 6c 0a 62 65 20 62 79 70 61 73 73 65 64  will.be bypassed
13930 20 61 6e 64 20 72 6f 77 73 20 77 69 6c 6c 20 62   and rows will b
13940 65 20 64 65 6c 65 74 65 64 20 6f 6e 65 20 62 79  e deleted one by
13950 20 6f 6e 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e   one.</p>..<tcl>
13960 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
13970 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13980 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13990 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
139a0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
139b0 0a 53 65 63 74 69 6f 6e 20 7b 44 45 54 41 43 48  .Section {DETACH
139c0 20 44 41 54 41 42 41 53 45 7d 20 64 65 74 61 63   DATABASE} detac
139d0 68 20 2a 44 45 54 41 43 48 0a 0a 52 65 63 75 72  h *DETACH..Recur
139e0 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61  siveBubbleDiagra
139f0 6d 20 64 65 74 61 63 68 2d 73 74 6d 74 0a 3c 2f  m detach-stmt.</
13a00 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 69 73 20 73  tcl>..<p>^This s
13a10 74 61 74 65 6d 65 6e 74 20 64 65 74 61 63 68 65  tatement detache
13a20 73 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  s an additional 
13a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a40 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 0a  ion previously .
13a50 61 74 74 61 63 68 65 64 20 75 73 69 6e 67 20 74  attached using t
13a60 68 65 20 5b 41 54 54 41 43 48 5d 20 73 74 61 74  he [ATTACH] stat
13a70 65 6d 65 6e 74 2e 20 20 0a 5e 57 68 65 6e 20 6e  ement.  .^When n
13a80 6f 74 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  ot in [shared ca
13a90 63 68 65 20 6d 6f 64 65 5d 2c 20 0a 69 74 20 69  che mode], .it i
13aa0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 68 61  s possible to ha
13ab0 76 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ve the same data
13ac0 62 61 73 65 20 66 69 6c 65 20 61 74 74 61 63 68  base file attach
13ad0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
13ae0 73 20 75 73 69 6e 67 20 0a 64 69 66 66 65 72 65  s using .differe
13af0 6e 74 20 6e 61 6d 65 73 2c 20 61 6e 64 20 64 65  nt names, and de
13b00 74 61 63 68 69 6e 67 20 6f 6e 65 20 63 6f 6e 6e  taching one conn
13b10 65 63 74 69 6f 6e 20 74 6f 20 61 20 66 69 6c 65  ection to a file
13b20 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
13b30 0a 6f 74 68 65 72 73 20 69 6e 74 61 63 74 2e 3c  .others intact.<
13b40 2f 70 3e 0a 5e 49 6e 20 5b 73 68 61 72 65 64 20  /p>.^In [shared 
13b50 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 61 74 74  cache mode], att
13b60 65 6d 70 74 69 6e 67 20 74 6f 20 61 74 74 61 63  empting to attac
13b70 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  h the same datab
13b80 61 73 65 20 66 69 6c 65 20 6d 6f 72 65 0a 74 68  ase file more.th
13b90 61 6e 20 6f 6e 63 65 20 72 65 73 75 6c 74 73 20  an once results 
13ba0 69 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 0a 0a 3c  in an error....<
13bb0 74 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23  tcl>.###########
13bc0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13bd0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13be0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13bf0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13c00 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b 44 52 4f  ###.Section {DRO
13c10 50 20 49 4e 44 45 58 7d 20 64 72 6f 70 69 6e 64  P INDEX} dropind
13c20 65 78 20 7b 7b 44 52 4f 50 20 49 4e 44 45 58 7d  ex {{DROP INDEX}
13c30 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62 62  }..RecursiveBubb
13c40 6c 65 44 69 61 67 72 61 6d 20 64 72 6f 70 2d 69  leDiagram drop-i
13c50 6e 64 65 78 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e  ndex-stmt.</tcl>
13c60 0a 0a 3c 70 3e 5e 54 68 65 20 44 52 4f 50 20 49  ..<p>^The DROP I
13c70 4e 44 45 58 20 73 74 61 74 65 6d 65 6e 74 20 72  NDEX statement r
13c80 65 6d 6f 76 65 73 20 61 6e 20 69 6e 64 65 78 20  emoves an index 
13c90 61 64 64 65 64 0a 77 69 74 68 20 74 68 65 20 5b  added.with the [
13ca0 43 52 45 41 54 45 20 49 4e 44 45 58 5d 20 73 74  CREATE INDEX] st
13cb0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 69 6e  atement.  The in
13cc0 64 65 78 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c  dex is completel
13cd0 79 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 0a 74  y removed from.t
13ce0 68 65 20 64 69 73 6b 2e 20 20 54 68 65 20 6f 6e  he disk.  The on
13cf0 6c 79 20 77 61 79 20 74 6f 20 72 65 63 6f 76 65  ly way to recove
13d00 72 20 74 68 65 20 69 6e 64 65 78 20 69 73 20 74  r the index is t
13d10 6f 20 72 65 65 6e 74 65 72 20 74 68 65 0a 61 70  o reenter the.ap
13d20 70 72 6f 70 72 69 61 74 65 20 5b 43 52 45 41 54  propriate [CREAT
13d30 45 20 49 4e 44 45 58 5d 20 63 6f 6d 6d 61 6e 64  E INDEX] command
13d40 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 23 23 23  .</p>..<tcl>.###
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 23 23 23 23 23 23 23 23 23 23 23  ################
13d80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
13d90 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
13da0 69 6f 6e 20 7b 44 52 4f 50 20 54 41 42 4c 45 7d  ion {DROP TABLE}
13db0 20 64 72 6f 70 74 61 62 6c 65 20 7b 7b 44 52 4f   droptable {{DRO
13dc0 50 20 54 41 42 4c 45 7d 7d 0a 0a 52 65 63 75 72  P TABLE}}..Recur
13dd0 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61  siveBubbleDiagra
13de0 6d 20 64 72 6f 70 2d 74 61 62 6c 65 2d 73 74 6d  m drop-table-stm
13df0 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68  t.</tcl>..<p>^Th
13e00 65 20 44 52 4f 50 20 54 41 42 4c 45 20 73 74 61  e DROP TABLE sta
13e10 74 65 6d 65 6e 74 20 72 65 6d 6f 76 65 73 20 61  tement removes a
13e20 20 74 61 62 6c 65 20 61 64 64 65 64 20 77 69 74   table added wit
13e30 68 20 74 68 65 0a 5b 43 52 45 41 54 45 20 54 41  h the.[CREATE TA
13e40 42 4c 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  BLE] statement. 
13e50 20 54 68 65 20 6e 61 6d 65 20 73 70 65 63 69 66   The name specif
13e60 69 65 64 20 69 73 20 74 68 65 0a 74 61 62 6c 65  ied is the.table
13e70 20 6e 61 6d 65 2e 20 20 5e 54 68 65 20 64 72 6f   name.  ^The dro
13e80 70 70 65 64 20 74 61 62 6c 65 20 69 73 20 63 6f  pped table is co
13e90 6d 70 6c 65 74 65 6c 79 20 72 65 6d 6f 76 65 64  mpletely removed
13ea0 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
13eb0 73 65 20 0a 73 63 68 65 6d 61 20 61 6e 64 20 74  se .schema and t
13ec0 68 65 20 64 69 73 6b 20 66 69 6c 65 2e 20 20 54  he disk file.  T
13ed0 68 65 20 74 61 62 6c 65 20 63 61 6e 20 6e 6f 74  he table can not
13ee0 20 62 65 20 72 65 63 6f 76 65 72 65 64 2e 20 20   be recovered.  
13ef0 0a 5e 41 6c 6c 20 69 6e 64 69 63 65 73 20 61 6e  .^All indices an
13f00 64 20 74 72 69 67 67 65 72 73 0a 61 73 73 6f 63  d triggers.assoc
13f10 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 74  iated with the t
13f20 61 62 6c 65 20 61 72 65 20 61 6c 73 6f 20 64 65  able are also de
13f30 6c 65 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  leted.</p>..<p>^
13f40 54 68 65 20 6f 70 74 69 6f 6e 61 6c 20 49 46 20  The optional IF 
13f50 45 58 49 53 54 53 20 63 6c 61 75 73 65 20 73 75  EXISTS clause su
13f60 70 70 72 65 73 73 65 73 20 74 68 65 20 65 72 72  ppresses the err
13f70 6f 72 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f  or that would no
13f80 72 6d 61 6c 6c 79 0a 72 65 73 75 6c 74 20 69 66  rmally.result if
13f90 20 74 68 65 20 74 61 62 6c 65 20 64 6f 65 73 20   the table does 
13fa0 6e 6f 74 20 65 78 69 73 74 2e 3c 2f 70 3e 0a 0a  not exist.</p>..
13fb0 3c 70 3e 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  <p>^If [foreign 
13fc0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
13fd0 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 61 20   are enabled, a 
13fe0 44 52 4f 50 20 54 41 42 4c 45 20 63 6f 6d 6d 61  DROP TABLE comma
13ff0 6e 64 20 70 65 72 66 6f 72 6d 73 20 61 6e 0a 69  nd performs an.i
14000 6d 70 6c 69 63 69 74 20 5b 44 45 4c 45 54 45 20  mplicit [DELETE 
14010 7c 20 44 45 4c 45 54 45 20 46 52 4f 4d 5d 20 63  | DELETE FROM] c
14020 6f 6d 6d 61 6e 64 20 62 65 66 6f 72 65 20 72 65  ommand before re
14030 6d 6f 76 69 6e 67 20 74 68 65 0a 74 61 62 6c 65  moving the.table
14040 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
14050 73 65 20 73 63 68 65 6d 61 2e 20 5e 41 6e 79 20  se schema. ^Any 
14060 74 72 69 67 67 65 72 73 20 61 74 74 61 63 68 65  triggers attache
14070 64 20 74 6f 20 74 68 65 20 74 61 62 6c 65 20 61  d to the table a
14080 72 65 0a 64 72 6f 70 70 65 64 20 66 72 6f 6d 20  re.dropped from 
14090 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
140a0 65 6d 61 20 62 65 66 6f 72 65 20 74 68 65 20 69  ema before the i
140b0 6d 70 6c 69 63 69 74 20 44 45 4c 45 54 45 20 46  mplicit DELETE F
140c0 52 4f 4d 0a 69 73 20 65 78 65 63 75 74 65 64 2c  ROM.is executed,
140d0 20 73 6f 20 74 68 69 73 20 63 61 6e 6e 6f 74 20   so this cannot 
140e0 63 61 75 73 65 20 61 6e 79 20 74 72 69 67 67 65  cause any trigge
140f0 72 73 20 74 6f 20 66 69 72 65 2e 20 42 79 20 63  rs to fire. By c
14100 6f 6e 74 72 61 73 74 2c 20 5e 61 6e 0a 69 6d 70  ontrast, ^an.imp
14110 6c 69 63 69 74 20 44 45 4c 45 54 45 20 46 52 4f  licit DELETE FRO
14120 4d 20 64 6f 65 73 20 63 61 75 73 65 20 61 6e 79  M does cause any
14130 20 63 6f 6e 66 69 67 75 72 65 64 0a 5b 66 6f 72   configured.[for
14140 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14150 5d 20 74 6f 20 74 61 6b 65 20 70 6c 61 63 65 2e  ] to take place.
14160 20 0a 5e 49 66 20 74 68 65 20 69 6d 70 6c 69 63   .^If the implic
14170 69 74 20 44 45 4c 45 54 45 20 46 52 4f 4d 20 65  it DELETE FROM e
14180 78 65 63 75 74 65 64 0a 61 73 20 70 61 72 74 20  xecuted.as part 
14190 6f 66 20 61 20 44 52 4f 50 20 54 41 42 4c 45 20  of a DROP TABLE 
141a0 63 6f 6d 6d 61 6e 64 20 76 69 6f 6c 61 74 65 73  command violates
141b0 20 61 6e 79 20 69 6d 6d 65 64 69 61 74 65 20 66   any immediate f
141c0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
141d0 72 61 69 6e 74 73 2c 0a 61 6e 20 65 72 72 6f 72  raints,.an error
141e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
141f0 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 6e 6f   the table is no
14200 74 20 64 72 6f 70 70 65 64 2e 20 5e 49 66 20 0a  t dropped. ^If .
14210 74 68 65 20 69 6d 70 6c 69 63 69 74 20 44 45 4c  the implicit DEL
14220 45 54 45 20 46 52 4f 4d 20 63 61 75 73 65 73 20  ETE FROM causes 
14230 61 6e 79 20 0a 64 65 66 65 72 72 65 64 20 66 6f  any .deferred fo
14240 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
14250 61 69 6e 74 73 20 74 6f 20 62 65 20 76 69 6f 6c  aints to be viol
14260 61 74 65 64 2c 20 61 6e 64 20 74 68 65 20 76 69  ated, and the vi
14270 6f 6c 61 74 69 6f 6e 73 20 73 74 69 6c 6c 0a 65  olations still.e
14280 78 69 73 74 20 77 68 65 6e 20 74 68 65 20 74 72  xist when the tr
14290 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
142a0 6d 69 74 74 65 64 2c 20 61 6e 20 65 72 72 6f 72  mitted, an error
142b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 74 20   is returned at 
142c0 74 68 65 20 74 69 6d 65 0a 6f 66 20 63 6f 6d 6d  the time.of comm
142d0 69 74 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  it...<tcl>.#####
142e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
142f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14300 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14310 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14320 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
14330 6e 20 7b 44 52 4f 50 20 54 52 49 47 47 45 52 7d  n {DROP TRIGGER}
14340 20 64 72 6f 70 74 72 69 67 67 65 72 20 7b 7b 44   droptrigger {{D
14350 52 4f 50 20 54 52 49 47 47 45 52 7d 7d 0a 0a 52  ROP TRIGGER}}..R
14360 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
14370 61 67 72 61 6d 20 64 72 6f 70 2d 74 72 69 67 67  agram drop-trigg
14380 65 72 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  er-stmt.</tcl>..
14390 3c 70 3e 5e 54 68 65 20 44 52 4f 50 20 54 52 49  <p>^The DROP TRI
143a0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 20 72  GGER statement r
143b0 65 6d 6f 76 65 73 20 61 20 74 72 69 67 67 65 72  emoves a trigger
143c0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 20   created by the 
143d0 0a 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52  .[CREATE TRIGGER
143e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 4f 6e  ] statement. ^On
143f0 63 65 20 72 65 6d 6f 76 65 64 2c 20 74 68 65 20  ce removed, the 
14400 74 72 69 67 67 65 72 20 64 65 66 69 6e 69 74 69  trigger definiti
14410 6f 6e 20 69 73 20 6e 6f 0a 6c 6f 6e 67 65 72 20  on is no.longer 
14420 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 73  present in the s
14430 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 28 6f 72  qlite_master (or
14440 20 73 71 6c 69 74 65 5f 74 65 6d 70 5f 6d 61 73   sqlite_temp_mas
14450 74 65 72 29 20 74 61 62 6c 65 20 61 6e 64 20 69  ter) table and i
14460 73 0a 6e 6f 74 20 66 69 72 65 64 20 62 79 20 61  s.not fired by a
14470 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 49 4e  ny subsequent IN
14480 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
14490 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
144a0 73 2e 0a 0a 3c 70 3e 5e 4e 6f 74 65 20 74 68 61  s...<p>^Note tha
144b0 74 20 74 72 69 67 67 65 72 73 20 61 72 65 20 61  t triggers are a
144c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 72 6f  utomatically dro
144d0 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 61 73  pped when the as
144e0 73 6f 63 69 61 74 65 64 20 74 61 62 6c 65 20 69  sociated table i
144f0 73 0a 64 72 6f 70 70 65 64 2e 0a 0a 3c 74 63 6c  s.dropped...<tcl
14500 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23  >.##############
14510 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14520 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14530 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14540 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14550 0a 53 65 63 74 69 6f 6e 20 7b 44 52 4f 50 20 56  .Section {DROP V
14560 49 45 57 7d 20 64 72 6f 70 76 69 65 77 20 7b 7b  IEW} dropview {{
14570 44 52 4f 50 20 56 49 45 57 7d 7d 0a 0a 52 65 63  DROP VIEW}}..Rec
14580 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67  ursiveBubbleDiag
14590 72 61 6d 20 64 72 6f 70 2d 76 69 65 77 2d 73 74  ram drop-view-st
145a0 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54  mt.</tcl>..<p>^T
145b0 68 65 20 44 52 4f 50 20 56 49 45 57 20 73 74 61  he DROP VIEW sta
145c0 74 65 6d 65 6e 74 20 72 65 6d 6f 76 65 73 20 61  tement removes a
145d0 20 76 69 65 77 20 63 72 65 61 74 65 64 20 62 79   view created by
145e0 20 74 68 65 20 5b 43 52 45 41 54 45 20 56 49 45   the [CREATE VIE
145f0 57 5d 20 0a 20 20 73 74 61 74 65 6d 65 6e 74 2e  W] .  statement.
14600 20 5e 54 68 65 20 76 69 65 77 20 64 65 66 69 6e   ^The view defin
14610 69 74 69 6f 6e 20 69 73 20 72 65 6d 6f 76 65 64  ition is removed
14620 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
14630 73 65 20 73 63 68 65 6d 61 2c 20 62 75 74 20 0a  se schema, but .
14640 20 20 6e 6f 20 61 63 74 75 61 6c 20 64 61 74 61    no actual data
14650 20 69 6e 20 74 68 65 20 75 6e 64 65 72 6c 79 69   in the underlyi
14660 6e 67 20 62 61 73 65 20 74 61 62 6c 65 73 20 69  ng base tables i
14670 73 20 6d 6f 64 69 66 69 65 64 2e 0a 0a 3c 70 3e  s modified...<p>
14680 5e 28 54 68 65 20 76 69 65 77 20 74 6f 20 64 72  ^(The view to dr
14690 6f 70 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  op is identified
146a0 20 62 79 20 74 68 65 20 76 69 65 77 2d 6e 61 6d   by the view-nam
146b0 65 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 20 0a  e and optional .
146c0 20 20 73 63 68 65 6d 61 2d 6e 61 6d 65 20 73 70    schema-name sp
146d0 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
146e0 6f 66 20 74 68 65 20 44 52 4f 50 20 56 49 45 57  of the DROP VIEW
146f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 69 73   statement. This
14700 20 0a 20 20 72 65 66 65 72 65 6e 63 65 20 69 73   .  reference is
14710 20 72 65 73 6f 6c 76 65 64 20 75 73 69 6e 67 20   resolved using 
14720 74 68 65 20 73 74 61 6e 64 61 72 64 20 70 72 6f  the standard pro
14730 63 65 64 75 72 65 20 66 6f 72 20 5b 6f 62 6a 65  cedure for [obje
14740 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 5d 2e 29  ct resolution].)
14750 5e 0a 0a 3c 70 3e 0a 20 20 5e 49 66 20 74 68 65  ^..<p>.  ^If the
14760 20 73 70 65 63 69 66 69 65 64 20 76 69 65 77 20   specified view 
14770 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 20  cannot be found 
14780 61 6e 64 20 74 68 65 20 49 46 20 45 58 49 53 54  and the IF EXIST
14790 53 20 63 6c 61 75 73 65 20 69 73 20 6e 6f 74 20  S clause is not 
147a0 0a 20 20 70 72 65 73 65 6e 74 2c 20 69 74 20 69  .  present, it i
147b0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
147c0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 76 69  the specified vi
147d0 65 77 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ew cannot be fou
147e0 6e 64 20 61 6e 64 20 61 6e 20 49 46 0a 20 20 45  nd and an IF.  E
147f0 58 49 53 54 53 20 63 6c 61 75 73 65 20 69 73 20  XISTS clause is 
14800 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 44  present in the D
14810 52 4f 50 20 56 49 45 57 20 73 74 61 74 65 6d 65  ROP VIEW stateme
14820 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61  nt, then the sta
14830 74 65 6d 65 6e 74 0a 20 20 69 73 20 61 20 6e 6f  tement.  is a no
14840 2d 6f 70 2e 0a 0a 0a 3c 74 63 6c 3e 0a 23 23 23  -op....<tcl>.###
14850 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14860 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14870 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14880 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
14890 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74  ###########.Sect
148a0 69 6f 6e 20 7b 44 61 74 61 62 61 73 65 20 4f 62  ion {Database Ob
148b0 6a 65 63 74 20 4e 61 6d 65 20 52 65 73 6f 6c 75  ject Name Resolu
148c0 74 69 6f 6e 7d 20 7b 6e 61 6d 69 6e 67 7d 20 7b  tion} {naming} {
148d0 7b 6f 62 6a 65 63 74 20 72 65 73 6f 6c 75 74 69  {object resoluti
148e0 6f 6e 7d 7d 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e  on}}.</tcl>..<p>
148f0 0a 20 20 49 6e 20 53 51 4c 69 74 65 2c 20 61 20  .  In SQLite, a 
14900 64 61 74 61 62 61 73 65 20 6f 62 6a 65 63 74 20  database object 
14910 28 61 20 74 61 62 6c 65 2c 20 69 6e 64 65 78 2c  (a table, index,
14920 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
14930 29 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 0a  ) is identified.
14940 20 20 62 79 20 74 68 65 20 6e 61 6d 65 20 6f 66    by the name of
14950 20 74 68 65 20 6f 62 6a 65 63 74 20 61 6e 64 20   the object and 
14960 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
14970 64 61 74 61 62 61 73 65 20 74 68 61 74 20 69 74  database that it
14980 20 72 65 73 69 64 65 73 20 69 6e 2e 20 0a 20 20   resides in. .  
14990 44 61 74 61 62 61 73 65 20 6f 62 6a 65 63 74 73  Database objects
149a0 20 6d 61 79 20 72 65 73 69 64 65 20 69 6e 20 74   may reside in t
149b0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
149c0 2c 20 74 68 65 20 74 65 6d 70 20 64 61 74 61 62  , the temp datab
149d0 61 73 65 2c 20 6f 72 20 69 6e 0a 20 20 61 6e 20  ase, or in.  an 
149e0 5b 41 54 54 41 43 48 7c 61 74 74 61 63 68 65 64  [ATTACH|attached
149f0 20 64 61 74 61 62 61 73 65 5d 2e 0a 0a 3c 70 3e   database]...<p>
14a00 0a 20 20 54 68 65 20 73 79 6e 74 61 78 20 6f 66  .  The syntax of
14a10 20 74 68 65 20 5b 44 52 4f 50 20 54 41 42 4c 45   the [DROP TABLE
14a20 5d 2c 20 5b 44 52 4f 50 20 49 4e 44 45 58 5d 2c  ], [DROP INDEX],
14a30 20 5b 44 52 4f 50 20 56 49 45 57 5d 2c 20 5b 44   [DROP VIEW], [D
14a40 52 4f 50 20 54 52 49 47 47 45 52 5d 2c 0a 20 20  ROP TRIGGER],.  
14a50 5b 52 45 49 4e 44 45 58 5d 2c 20 5b 41 4c 54 45  [REINDEX], [ALTE
14a60 52 20 54 41 42 4c 45 5d 20 61 6e 64 20 6d 61 6e  R TABLE] and man
14a70 79 20 6f 74 68 65 72 20 63 6f 6d 6d 61 6e 64 73  y other commands
14a80 20 61 6c 6c 20 70 65 72 6d 69 74 20 74 68 65 20   all permit the 
14a90 75 73 65 72 20 74 6f 0a 20 20 73 70 65 63 69 66  user to.  specif
14aa0 79 20 61 20 64 61 74 61 62 61 73 65 20 6f 62 6a  y a database obj
14ab0 65 63 74 20 65 69 74 68 65 72 20 62 79 20 69 74  ect either by it
14ac0 73 20 6e 61 6d 65 20 61 6c 6f 6e 65 2c 20 6f 72  s name alone, or
14ad0 20 62 79 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f   by a combinatio
14ae0 6e 20 6f 66 0a 20 20 69 74 73 20 6e 61 6d 65 20  n of.  its name 
14af0 61 6e 64 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  and the name of 
14b00 69 74 73 20 64 61 74 61 62 61 73 65 2e 20 5e 28  its database. ^(
14b10 49 66 20 6e 6f 20 64 61 74 61 62 61 73 65 20 69  If no database i
14b20 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  s specified as p
14b30 61 72 74 0a 20 20 6f 66 20 74 68 65 20 6f 62 6a  art.  of the obj
14b40 65 63 74 20 72 65 66 65 72 65 6e 63 65 2c 20 74  ect reference, t
14b50 68 65 6e 20 53 51 4c 69 74 65 20 73 65 61 72 63  hen SQLite searc
14b60 68 65 73 20 74 68 65 20 6d 61 69 6e 2c 20 74 65  hes the main, te
14b70 6d 70 20 61 6e 64 20 61 6c 6c 20 61 74 74 61 63  mp and all attac
14b80 68 65 64 0a 20 20 64 61 74 61 62 61 73 65 73 20  hed.  databases 
14b90 66 6f 72 20 61 6e 20 6f 62 6a 65 63 74 20 77 69  for an object wi
14ba0 74 68 20 61 20 6d 61 74 63 68 69 6e 67 20 6e 61  th a matching na
14bb0 6d 65 2e 20 54 68 65 20 74 65 6d 70 20 64 61 74  me. The temp dat
14bc0 61 62 61 73 65 20 69 73 20 73 65 61 72 63 68 65  abase is searche
14bd0 64 0a 20 20 66 69 72 73 74 2c 20 66 6f 6c 6c 6f  d.  first, follo
14be0 77 65 64 20 62 79 20 74 68 65 20 6d 61 69 6e 20  wed by the main 
14bf0 64 61 74 61 62 61 73 65 2c 20 66 6f 6c 6c 6f 77  database, follow
14c00 65 64 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  ed all attached 
14c10 64 61 74 61 62 61 73 65 73 20 69 6e 20 74 68 65  databases in the
14c20 0a 20 20 6f 72 64 65 72 20 74 68 61 74 20 74 68  .  order that th
14c30 65 79 20 77 65 72 65 20 61 74 74 61 63 68 65 64  ey were attached
14c40 2e 20 54 68 65 20 72 65 66 65 72 65 6e 63 65 20  . The reference 
14c50 72 65 73 6f 6c 76 65 73 20 74 6f 20 74 68 65 20  resolves to the 
14c60 66 69 72 73 74 20 6d 61 74 63 68 0a 20 20 66 6f  first match.  fo
14c70 75 6e 64 2e 29 5e 20 46 6f 72 20 65 78 61 6d 70  und.)^ For examp
14c80 6c 65 3a 0a 0a 3c 70 72 65 3e 5e 28 0a 20 20 20  le:..<pre>^(.   
14c90 20 20 20 2f 2a 20 41 64 64 20 61 20 74 61 62 6c     /* Add a tabl
14ca0 65 20 6e 61 6d 65 64 20 27 74 31 27 20 74 6f 20  e named 't1' to 
14cb0 74 68 65 20 74 65 6d 70 2c 20 6d 61 69 6e 20 61  the temp, main a
14cc0 6e 64 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  nd an attached d
14cd0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 20 20 20  atabase */.     
14ce0 20 41 54 54 41 43 48 20 27 66 69 6c 65 2e 64 62   ATTACH 'file.db
14cf0 27 20 41 53 20 61 75 78 3b 0a 20 20 20 20 20 20  ' AS aux;.      
14d00 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
14d10 78 2c 20 79 29 3b 0a 20 20 20 20 20 20 43 52 45  x, y);.      CRE
14d20 41 54 45 20 54 45 4d 50 20 54 41 42 4c 45 20 74  ATE TEMP TABLE t
14d30 31 28 78 2c 20 79 29 3b 0a 20 20 20 20 20 20 43  1(x, y);.      C
14d40 52 45 41 54 45 20 54 41 42 4c 45 20 61 75 78 2e  REATE TABLE aux.
14d50 74 31 28 78 2c 20 79 29 3b 0a 0a 20 20 20 20 20  t1(x, y);..     
14d60 20 44 52 4f 50 20 54 41 42 4c 45 20 74 31 3b 20   DROP TABLE t1; 
14d70 20 20 20 20 20 20 20 20 2f 2a 20 44 72 6f 70 20          /* Drop 
14d80 74 61 62 6c 65 20 69 6e 20 74 65 6d 70 20 64 61  table in temp da
14d90 74 61 62 61 73 65 20 2a 2f 0a 20 20 20 20 20 20  tabase */.      
14da0 44 52 4f 50 20 54 41 42 4c 45 20 74 31 3b 20 20  DROP TABLE t1;  
14db0 20 20 20 20 20 20 20 2f 2a 20 44 72 6f 70 20 74         /* Drop t
14dc0 61 62 6c 65 20 69 6e 20 6d 61 69 6e 20 64 61 74  able in main dat
14dd0 61 62 61 73 65 20 2a 2f 0a 20 20 20 20 20 20 44  abase */.      D
14de0 52 4f 50 20 54 41 42 4c 45 20 74 31 3b 20 20 20  ROP TABLE t1;   
14df0 20 20 20 20 20 20 2f 2a 20 44 72 6f 70 20 74 61        /* Drop ta
14e00 62 6c 65 20 69 6e 20 61 75 78 20 64 61 74 61 62  ble in aux datab
14e10 61 73 65 20 2a 2f 0a 29 5e 3c 2f 70 72 65 3e 0a  ase */.)^</pre>.
14e20 0a 3c 70 3e 0a 20 20 5e 49 66 20 61 20 73 63 68  .<p>.  ^If a sch
14e30 65 6d 61 20 6e 61 6d 65 20 69 73 20 73 70 65 63  ema name is spec
14e40 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
14e50 20 61 6e 20 6f 62 6a 65 63 74 20 72 65 66 65 72   an object refer
14e60 65 6e 63 65 2c 20 69 74 20 6d 75 73 74 20 62 65  ence, it must be
14e70 0a 20 20 65 69 74 68 65 72 20 22 6d 61 69 6e 22  .  either "main"
14e80 2c 20 6f 72 20 22 74 65 6d 70 22 20 6f 72 20 74  , or "temp" or t
14e90 68 65 20 73 63 68 65 6d 61 2d 6e 61 6d 65 20 6f  he schema-name o
14ea0 66 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  f an attached da
14eb0 74 61 62 61 73 65 2e 0a 20 20 5e 4c 69 6b 65 20  tabase..  ^Like 
14ec0 6f 74 68 65 72 20 53 51 4c 20 69 64 65 6e 74 69  other SQL identi
14ed0 66 69 65 72 73 2c 20 73 63 68 65 6d 61 20 6e 61  fiers, schema na
14ee0 6d 65 73 20 61 72 65 20 63 61 73 65 2d 69 6e 73  mes are case-ins
14ef0 65 6e 73 69 74 69 76 65 2e 0a 20 20 5e 49 66 20  ensitive..  ^If 
14f00 61 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 73  a schema name is
14f10 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
14f20 20 6f 6e 6c 79 20 74 68 61 74 20 6f 6e 65 20 73   only that one s
14f30 63 68 65 6d 61 20 69 73 20 73 65 61 72 63 68 65  chema is searche
14f40 64 20 66 6f 72 0a 20 20 74 68 65 20 6e 61 6d 65  d for.  the name
14f50 64 20 6f 62 6a 65 63 74 2e 0a 0a 3c 70 3e 0a 20  d object...<p>. 
14f60 20 4d 6f 73 74 20 6f 62 6a 65 63 74 20 72 65 66   Most object ref
14f70 65 72 65 6e 63 65 73 20 6d 61 79 20 6f 6e 6c 79  erences may only
14f80 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 20 73 70   resolve to a sp
14f90 65 63 69 66 69 63 20 74 79 70 65 20 6f 66 20 6f  ecific type of o
14fa0 62 6a 65 63 74 20 28 66 6f 72 0a 20 20 65 78 61  bject (for.  exa
14fb0 6d 70 6c 65 20 61 20 72 65 66 65 72 65 6e 63 65  mple a reference
14fc0 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
14fd0 20 61 20 44 52 4f 50 20 54 41 42 4c 45 20 73 74   a DROP TABLE st
14fe0 61 74 65 6d 65 6e 74 20 6d 61 79 20 6f 6e 6c 79  atement may only
14ff0 20 72 65 73 6f 6c 76 65 0a 20 20 74 6f 20 61 20   resolve.  to a 
15000 74 61 62 6c 65 20 6f 62 6a 65 63 74 2c 20 6e 6f  table object, no
15010 74 20 61 6e 20 69 6e 64 65 78 2c 20 74 72 69 67  t an index, trig
15020 67 65 72 20 6f 72 20 76 69 65 77 29 2e 20 48 6f  ger or view). Ho
15030 77 65 76 65 72 20 69 6e 20 73 6f 6d 65 20 63 6f  wever in some co
15040 6e 74 65 78 74 73 20 0a 20 20 28 65 2e 67 2e 20  ntexts .  (e.g. 
15050 5b 52 45 49 4e 44 45 58 5d 29 20 61 6e 20 6f 62  [REINDEX]) an ob
15060 6a 65 63 74 20 72 65 66 65 72 65 6e 63 65 20 6d  ject reference m
15070 61 79 20 62 65 20 72 65 73 6f 6c 76 65 20 74 6f  ay be resolve to
15080 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
15090 79 70 65 0a 20 20 6f 66 20 6f 62 6a 65 63 74 2e  ype.  of object.
150a0 20 5e 57 68 65 6e 20 73 65 61 72 63 68 69 6e 67   ^When searching
150b0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
150c0 73 20 66 6f 72 20 61 20 6e 61 6d 65 64 20 6f 62  s for a named ob
150d0 6a 65 63 74 2c 20 6f 62 6a 65 63 74 73 20 6f 66  ject, objects of
150e0 0a 20 20 74 79 70 65 73 20 74 68 61 74 20 63 61  .  types that ca
150f0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 69 6e 20  nnot be used in 
15100 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
15110 68 65 20 72 65 66 65 72 65 6e 63 65 20 61 72 65  he reference are
15120 20 61 6c 77 61 79 73 20 0a 20 20 69 67 6e 6f 72   always .  ignor
15130 65 64 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23  ed...<tcl>.#####
15140 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15150 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15160 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15170 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15180 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f  #########.Sectio
15190 6e 20 45 58 50 4c 41 49 4e 20 65 78 70 6c 61 69  n EXPLAIN explai
151a0 6e 20 45 58 50 4c 41 49 4e 0a 0a 42 75 62 62 6c  n EXPLAIN..Bubbl
151b0 65 44 69 61 67 72 61 6d 20 73 71 6c 2d 73 74 6d  eDiagram sql-stm
151c0 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 41 6e  t.</tcl>..<p>^An
151d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
151e0 61 6e 20 62 65 20 70 72 65 63 65 64 65 64 20 62  an be preceded b
151f0 79 20 74 68 65 20 6b 65 79 77 6f 72 64 20 22 45  y the keyword "E
15200 58 50 4c 41 49 4e 22 20 6f 72 0a 62 79 20 74 68  XPLAIN" or.by th
15210 65 20 70 68 72 61 73 65 20 22 45 58 50 4c 41 49  e phrase "EXPLAI
15220 4e 20 51 55 45 52 59 20 50 4c 41 4e 22 2e 20 20  N QUERY PLAN".  
15230 5e 45 69 74 68 65 72 20 6d 6f 64 69 66 69 63 61  ^Either modifica
15240 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 0a  tion causes the.
15250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
15260 20 62 65 68 61 76 65 20 61 73 20 61 20 71 75 65   behave as a que
15270 72 79 20 61 6e 64 20 74 6f 20 72 65 74 75 72 6e  ry and to return
15280 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
15290 75 74 0a 68 6f 77 20 74 68 65 20 53 51 4c 20 73  ut.how the SQL s
152a0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 20 68  tatement would h
152b0 61 76 65 20 6f 70 65 72 61 74 65 64 20 69 66 20  ave operated if 
152c0 74 68 65 20 45 58 50 4c 41 49 4e 20 6b 65 79 77  the EXPLAIN keyw
152d0 6f 72 64 20 6f 72 0a 70 68 72 61 73 65 20 68 61  ord or.phrase ha
152e0 64 20 62 65 65 6e 20 6f 6d 69 74 74 65 64 2e 3c  d been omitted.<
152f0 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 6f 75 74 70  /p>..<p>The outp
15300 75 74 20 66 72 6f 6d 20 45 58 50 4c 41 49 4e 20  ut from EXPLAIN 
15310 61 6e 64 20 45 58 50 4c 41 49 4e 20 51 55 45 52  and EXPLAIN QUER
15320 59 20 50 4c 41 4e 20 69 73 20 69 6e 74 65 6e 64  Y PLAN is intend
15330 65 64 20 66 6f 72 0a 69 6e 74 65 72 61 63 74 69  ed for.interacti
15340 76 65 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  ve analysis and 
15350 74 72 6f 75 62 6c 65 73 68 6f 6f 74 69 6e 67 20  troubleshooting 
15360 6f 6e 6c 79 2e 20 20 54 68 65 20 64 65 74 61 69  only.  The detai
15370 6c 73 20 6f 66 20 74 68 65 20 0a 6f 75 74 70 75  ls of the .outpu
15380 74 20 66 6f 72 6d 61 74 20 61 72 65 20 73 75 62  t format are sub
15390 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 66  ject to change f
153a0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
153b0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
153c0 20 6e 65 78 74 2e 0a 41 70 70 6c 69 63 61 74 69   next..Applicati
153d0 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75  ons should not u
153e0 73 65 20 45 58 50 4c 41 49 4e 20 6f 72 20 45 58  se EXPLAIN or EX
153f0 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e  PLAIN QUERY PLAN
15400 20 73 69 6e 63 65 0a 74 68 65 69 72 20 65 78 61   since.their exa
15410 63 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 76  ct behavior is v
15420 61 72 69 61 62 6c 65 20 61 6e 64 20 6f 6e 6c 79  ariable and only
15430 20 70 61 72 74 69 61 6c 6c 79 20 64 6f 63 75 6d   partially docum
15440 65 6e 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  ented.</p>..<p>^
15450 57 68 65 6e 20 74 68 65 20 45 58 50 4c 41 49 4e  When the EXPLAIN
15460 20 6b 65 79 77 6f 72 64 20 61 70 70 65 61 72 73   keyword appears
15470 20 62 79 20 69 74 73 65 6c 66 20 69 74 20 63 61   by itself it ca
15480 75 73 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  uses the stateme
15490 6e 74 0a 74 6f 20 62 65 68 61 76 65 20 61 73 20  nt.to behave as 
154a0 61 20 71 75 65 72 79 20 74 68 61 74 20 72 65 74  a query that ret
154b0 75 72 6e 73 20 74 68 65 20 73 65 71 75 65 6e 63  urns the sequenc
154c0 65 20 6f 66 20 0a 5b 76 69 72 74 75 61 6c 20 6d  e of .[virtual m
154d0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
154e0 6f 6e 73 5d 20 69 74 20 77 6f 75 6c 64 20 68 61  ons] it would ha
154f0 76 65 20 75 73 65 64 20 74 6f 20 65 78 65 63 75  ve used to execu
15500 74 65 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 68  te the command h
15510 61 64 0a 74 68 65 20 45 58 50 4c 41 49 4e 20 6b  ad.the EXPLAIN k
15520 65 79 77 6f 72 64 20 6e 6f 74 20 62 65 65 6e 20  eyword not been 
15530 70 72 65 73 65 6e 74 2e 20 5e 57 68 65 6e 20 74  present. ^When t
15540 68 65 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59  he EXPLAIN QUERY
15550 20 50 4c 41 4e 20 70 68 72 61 73 65 0a 61 70 70   PLAN phrase.app
15560 65 61 72 73 2c 20 74 68 65 20 73 74 61 74 65 6d  ears, the statem
15570 65 6e 74 20 72 65 74 75 72 6e 73 20 68 69 67 68  ent returns high
15580 2d 6c 65 76 65 6c 20 69 6e 66 6f 72 6d 61 74 69  -level informati
15590 6f 6e 20 72 65 67 61 72 64 69 6e 67 20 74 68 65  on regarding the
155a0 20 71 75 65 72 79 0a 70 6c 61 6e 20 74 68 61 74   query.plan that
155b0 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
155c0 20 75 73 65 64 2e 0a 0a 3c 70 3e 54 68 65 20 45   used...<p>The E
155d0 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
155e0 4e 20 63 6f 6d 6d 61 6e 64 20 69 73 20 64 65 73  N command is des
155f0 63 72 69 62 65 64 20 69 6e 20 0a 5b 65 78 70 6c  cribed in .[expl
15600 61 69 6e 20 71 75 65 72 79 20 70 6c 61 6e 7c 6d  ain query plan|m
15610 6f 72 65 20 64 65 74 61 69 6c 20 68 65 72 65 5d  ore detail here]
15620 2e 0a 0a 3c 68 33 3e 45 58 50 4c 41 49 4e 20 6f  ...<h3>EXPLAIN o
15630 70 65 72 61 74 65 73 20 61 74 20 72 75 6e 2d 74  perates at run-t
15640 69 6d 65 2c 20 6e 6f 74 20 61 74 20 70 72 65 70  ime, not at prep
15650 61 72 65 2d 74 69 6d 65 3c 2f 68 33 3e 0a 0a 3c  are-time</h3>..<
15660 70 3e 54 68 65 20 45 58 50 4c 41 49 4e 20 61 6e  p>The EXPLAIN an
15670 64 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20  d EXPLAIN QUERY 
15680 50 4c 41 4e 20 70 72 65 66 69 78 65 73 20 61 66  PLAN prefixes af
15690 66 65 63 74 20 74 68 65 20 62 65 68 61 76 69 6f  fect the behavio
156a0 72 20 6f 66 0a 72 75 6e 6e 69 6e 67 20 61 20 5b  r of.running a [
156b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
156c0 6e 74 5d 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  nt] using [sqlit
156d0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 54 68 65  e3_step()].  The
156e0 20 70 72 6f 63 65 73 73 20 6f 66 0a 67 65 6e 65   process of.gene
156f0 72 61 74 69 6e 67 20 61 20 6e 65 77 20 70 72 65  rating a new pre
15700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
15710 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
15720 72 65 70 61 72 65 28 29 5d 20 6f 72 20 73 69 6d  repare()] or sim
15730 69 6c 61 72 0a 69 73 20 28 6d 6f 73 74 6c 79 29  ilar.is (mostly)
15740 20 75 6e 61 66 66 65 63 74 65 64 20 62 79 20 45   unaffected by E
15750 58 50 4c 41 49 4e 2e 20 20 28 54 68 65 20 65 78  XPLAIN.  (The ex
15760 63 65 70 74 69 6f 6e 20 74 6f 20 74 68 65 20 70  ception to the p
15770 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
15780 0a 69 73 20 74 68 61 74 20 73 6f 6d 65 20 73 70  .is that some sp
15790 65 63 69 61 6c 20 6f 70 63 6f 64 65 73 20 75 73  ecial opcodes us
157a0 65 64 20 62 79 20 45 58 50 4c 41 49 4e 20 51 55  ed by EXPLAIN QU
157b0 45 52 59 20 50 4c 41 4e 20 61 72 65 20 6f 6d 69  ERY PLAN are omi
157c0 74 74 65 64 20 77 68 65 6e 0a 62 75 69 6c 64 69  tted when.buildi
157d0 6e 67 20 61 6e 20 45 58 50 4c 41 49 4e 20 51 55  ng an EXPLAIN QU
157e0 45 52 59 20 50 4c 41 4e 20 70 72 65 70 61 72 65  ERY PLAN prepare
157f0 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 73 20  d statement, as 
15800 61 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 6f 70  a performance.op
15810 74 69 6d 69 7a 61 74 69 6f 6e 2e 29 0a 0a 3c 70  timization.)..<p
15820 3e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  >This means that
15830 20 61 63 74 69 6f 6e 73 20 74 68 61 74 20 6f 63   actions that oc
15840 63 75 72 20 64 75 72 69 6e 67 20 73 71 6c 69 74  cur during sqlit
15850 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 72 65  e3_prepare() are
15860 0a 75 6e 61 66 66 65 63 74 65 64 20 62 79 20 45  .unaffected by E
15870 58 50 4c 41 49 4e 2e 0a 0a 3c 75 6c 3e 0a 3c 6c  XPLAIN...<ul>.<l
15880 69 3e 3c 70 3e 0a 53 6f 6d 65 20 5b 50 52 41 47  i><p>.Some [PRAG
15890 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 64  MA] statements d
158a0 6f 20 74 68 65 69 72 20 77 6f 72 6b 20 64 75 72  o their work dur
158b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ing sqlite3_prep
158c0 61 72 65 28 29 20 72 61 74 68 65 72 0a 74 68 61  are() rather.tha
158d0 6e 20 64 75 72 69 6e 67 20 73 71 6c 69 74 65 33  n during sqlite3
158e0 5f 73 74 65 70 28 29 2e 20 20 54 68 6f 73 65 20  _step().  Those 
158f0 50 52 41 47 4d 41 20 73 74 61 74 65 6d 65 6e 74  PRAGMA statement
15900 73 20 61 72 65 20 75 6e 61 66 66 65 63 74 65 64  s are unaffected
15910 0a 62 79 20 45 58 50 4c 41 49 4e 2e 20 20 54 68  .by EXPLAIN.  Th
15920 65 79 20 6f 70 65 72 61 74 65 20 74 68 65 20 73  ey operate the s
15930 61 6d 65 20 77 69 74 68 20 6f 72 20 77 69 74 68  ame with or with
15940 6f 75 74 20 74 68 65 20 45 58 50 4c 41 49 4e 20  out the EXPLAIN 
15950 70 72 65 66 69 78 2e 0a 54 68 65 20 73 65 74 20  prefix..The set 
15960 6f 66 20 50 52 41 47 4d 41 20 73 74 61 74 65 6d  of PRAGMA statem
15970 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 75 6e  ents that are un
15980 61 66 66 65 63 74 65 64 20 62 79 20 45 58 50 4c  affected by EXPL
15990 41 49 4e 20 63 61 6e 20 76 61 72 79 0a 66 72 6f  AIN can vary.fro
159a0 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
159b0 20 74 68 65 20 6e 65 78 74 2e 20 20 53 6f 6d 65   the next.  Some
159c0 20 50 52 41 47 4d 41 20 73 74 61 74 65 6d 65 6e   PRAGMA statemen
159d0 74 73 20 6f 70 65 72 61 74 65 20 64 75 72 69 6e  ts operate durin
159e0 67 0a 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  g.sqlite3_prepar
159f0 65 28 29 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  e() depending on
15a00 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 73   their arguments
15a10 2e 20 20 46 6f 72 20 63 6f 6e 73 69 73 74 65 6e  .  For consisten
15a20 74 0a 72 65 73 75 6c 74 73 2c 20 61 76 6f 69 64  t.results, avoid
15a30 20 75 73 69 6e 67 20 45 58 50 4c 41 49 4e 20 6f   using EXPLAIN o
15a40 6e 20 50 52 41 47 4d 41 20 73 74 61 74 65 6d 65  n PRAGMA stateme
15a50 6e 74 73 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 54 68  nts...<li><p>.Th
15a60 65 20 5b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  e [authorizer ca
15a70 6c 6c 62 61 63 6b 5d 20 69 73 20 69 6e 76 6f 6b  llback] is invok
15a80 65 64 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ed regardless of
15a90 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
15aa0 0a 45 58 50 4c 41 49 4e 20 6f 72 20 45 58 50 4c  .EXPLAIN or EXPL
15ab0 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 2e 0a  AIN QUERY PLAN..
15ac0 3c 2f 75 6c 3e 0a 3c 74 63 6c 3e 0a 23 23 23 23  </ul>.<tcl>.####
15ad0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15ae0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15af0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15b00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
15b10 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
15b20 6f 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 65 78  on expression ex
15b30 70 72 20 7b 2a 65 78 70 72 65 73 73 69 6f 6e 20  pr {*expression 
15b40 7b 65 78 70 72 65 73 73 69 6f 6e 20 73 79 6e 74  {expression synt
15b50 61 78 7d 7d 0a 0a 52 65 63 75 72 73 69 76 65 42  ax}}..RecursiveB
15b60 75 62 62 6c 65 44 69 61 67 72 61 6d 20 65 78 70  ubbleDiagram exp
15b70 72 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68 69  r.</tcl>..<p>Thi
15b80 73 20 73 65 63 74 69 6f 6e 20 69 73 20 64 69 66  s section is dif
15b90 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  ferent from the 
15ba0 6f 74 68 65 72 73 2e 20 20 4d 6f 73 74 20 6f 74  others.  Most ot
15bb0 68 65 72 20 73 65 63 74 69 6f 6e 73 20 6f 66 0a  her sections of.
15bc0 74 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 74 61  this document ta
15bd0 6c 6b 73 20 61 62 6f 75 74 20 61 20 70 61 72 74  lks about a part
15be0 69 63 75 6c 61 72 20 53 51 4c 20 63 6f 6d 6d 61  icular SQL comma
15bf0 6e 64 2e 20 20 54 68 69 73 20 73 65 63 74 69 6f  nd.  This sectio
15c00 6e 20 64 6f 65 73 0a 6e 6f 74 20 74 61 6c 6b 20  n does.not talk 
15c10 61 62 6f 75 74 20 61 20 73 74 61 6e 64 61 6c 6f  about a standalo
15c20 6e 65 20 63 6f 6d 6d 61 6e 64 20 62 75 74 20 61  ne command but a
15c30 62 6f 75 74 20 22 65 78 70 72 65 73 73 69 6f 6e  bout "expression
15c40 73 22 20 77 68 69 63 68 20 61 72 65 20 0a 73 75  s" which are .su
15c50 62 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 6d  bcomponents of m
15c60 6f 73 74 20 6f 74 68 65 72 20 63 6f 6d 6d 61 6e  ost other comman
15c70 64 73 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  ds.</p>..<tcl>hd
15c80 5f 66 72 61 67 6d 65 6e 74 20 62 69 6e 61 72 79  _fragment binary
15c90 6f 70 73 20 7b 62 69 6e 61 72 79 20 6f 70 65 72  ops {binary oper
15ca0 61 74 6f 72 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33  ators}</tcl>.<h3
15cb0 3e 4f 70 65 72 61 74 6f 72 73 3c 2f 68 33 3e 0a  >Operators</h3>.
15cc0 3c 70 3e 5e 28 53 51 4c 69 74 65 20 75 6e 64 65  <p>^(SQLite unde
15cd0 72 73 74 61 6e 64 73 20 74 68 65 20 66 6f 6c 6c  rstands the foll
15ce0 6f 77 69 6e 67 20 62 69 6e 61 72 79 20 6f 70 65  owing binary ope
15cf0 72 61 74 6f 72 73 2c 20 69 6e 20 6f 72 64 65 72  rators, in order
15d00 20 66 72 6f 6d 0a 68 69 67 68 65 73 74 20 74 6f   from.highest to
15d10 20 6c 6f 77 65 73 74 20 70 72 65 63 65 64 65 6e   lowest preceden
15d20 63 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ce:</p>..<blockq
15d30 75 6f 74 65 3e 3c 70 72 65 3e 0a 3c 66 6f 6e 74  uote><pre>.<font
15d40 20 63 6f 6c 6f 72 3d 22 23 32 63 32 63 66 30 22   color="#2c2cf0"
15d50 3e 3c 62 69 67 3e 7c 7c 0a 2a 20 20 20 20 2f 20  ><big>||.*    / 
15d60 20 20 20 25 0a 2b 20 20 20 20 2d 0a 26 6c 74 3b     %.+    -.&lt;
15d70 26 6c 74 3b 20 20 20 26 67 74 3b 26 67 74 3b 20  &lt;   &gt;&gt; 
15d80 20 20 26 61 6d 70 3b 20 20 20 20 7c 0a 26 6c 74    &amp;    |.&lt
15d90 3b 20 20 20 20 26 6c 74 3b 3d 20 20 20 26 67 74  ;    &lt;=   &gt
15da0 3b 20 20 20 20 26 67 74 3b 3d 0a 3d 20 20 20 20  ;    &gt;=.=    
15db0 3d 3d 20 20 20 21 3d 20 20 20 26 6c 74 3b 26 67  ==   !=   &lt;&g
15dc0 74 3b 20 20 20 3c 2f 62 69 67 3e 49 53 20 20 20  t;   </big>IS   
15dd0 49 53 20 4e 4f 54 20 20 20 49 4e 20 20 20 4c 49  IS NOT   IN   LI
15de0 4b 45 20 20 20 47 4c 4f 42 20 20 20 4d 41 54 43  KE   GLOB   MATC
15df0 48 20 20 20 52 45 47 45 58 50 0a 41 4e 44 20 20  H   REGEXP.AND  
15e00 20 0a 4f 52 3c 2f 66 6f 6e 74 3e 0a 3c 2f 70 72   .OR</font>.</pr
15e10 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
15e20 5e 0a 0a 3c 70 3e 5e 28 53 75 70 70 6f 72 74 65  ^..<p>^(Supporte
15e30 64 20 75 6e 61 72 79 20 70 72 65 66 69 78 20 6f  d unary prefix o
15e40 70 65 72 61 74 6f 72 73 20 61 72 65 20 74 68 65  perators are the
15e50 73 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  se:</p>..<blockq
15e60 75 6f 74 65 3e 3c 70 72 65 3e 0a 3c 66 6f 6e 74  uote><pre>.<font
15e70 20 63 6f 6c 6f 72 3d 22 23 32 63 32 63 66 30 22   color="#2c2cf0"
15e80 3e 3c 62 69 67 3e 2d 20 20 20 20 2b 20 20 20 20  ><big>-    +    
15e90 7e 20 20 20 20 4e 4f 54 3c 2f 62 69 67 3e 3c 2f  ~    NOT</big></
15ea0 66 6f 6e 74 3e 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  font>.</pre></bl
15eb0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 3c 74 63  ockquote>)^..<tc
15ec0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f  l>hd_fragment co
15ed0 6c 6c 61 74 65 6f 70 20 7b 43 4f 4c 4c 41 54 45  llateop {COLLATE
15ee0 20 6f 70 65 72 61 74 6f 72 7d 3c 2f 74 63 6c 3e   operator}</tcl>
15ef0 0a 3c 70 3e 5e 54 68 65 20 43 4f 4c 4c 41 54 45  .<p>^The COLLATE
15f00 20 6f 70 65 72 61 74 6f 72 20 69 73 20 61 20 75   operator is a u
15f10 6e 61 72 79 20 70 6f 73 74 66 69 78 0a 6f 70 65  nary postfix.ope
15f20 72 61 74 6f 72 20 74 68 61 74 20 61 73 73 69 67  rator that assig
15f30 6e 73 20 61 20 5b 63 6f 6c 6c 61 74 69 6e 67 20  ns a [collating 
15f40 73 65 71 75 65 6e 63 65 5d 20 74 6f 20 61 6e 20  sequence] to an 
15f50 65 78 70 72 65 73 73 69 6f 6e 2e 0a 5e 54 68 65  expression..^The
15f60 20 43 4f 4c 4c 41 54 45 20 6f 70 65 72 61 74 6f   COLLATE operato
15f70 72 20 68 61 73 20 61 20 68 69 67 68 65 72 20 70  r has a higher p
15f80 72 65 63 65 64 65 6e 63 65 20 28 62 69 6e 64 73  recedence (binds
15f90 20 6d 6f 72 65 20 74 69 67 68 74 6c 79 29 20 74   more tightly) t
15fa0 68 61 6e 20 61 6e 79 0a 62 69 6e 61 72 79 20 6f  han any.binary o
15fb0 70 65 72 61 74 6f 72 20 61 6e 64 20 61 6e 79 20  perator and any 
15fc0 75 6e 61 72 79 20 70 72 65 66 69 78 20 6f 70 65  unary prefix ope
15fd0 72 61 74 6f 72 20 65 78 63 65 70 74 20 22 7e 22  rator except "~"
15fe0 2e 0a 28 43 4f 4c 4c 41 54 45 20 61 6e 64 20 22  ..(COLLATE and "
15ff0 7e 22 20 61 72 65 20 61 73 73 6f 63 69 61 74 69  ~" are associati
16000 76 65 20 73 6f 20 74 68 65 69 72 20 62 69 6e 64  ve so their bind
16010 69 6e 67 20 6f 72 64 65 72 20 64 6f 65 73 20 6e  ing order does n
16020 6f 74 20 6d 61 74 74 65 72 2e 29 0a 5e 54 68 65  ot matter.).^The
16030 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
16040 6e 63 65 20 73 65 74 20 62 79 20 74 68 65 20 43  nce set by the C
16050 4f 4c 4c 41 54 45 20 6f 70 65 72 61 74 6f 72 20  OLLATE operator 
16060 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 63 6f  overrides the.co
16070 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
16080 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
16090 68 65 20 43 4f 4c 4c 41 54 45 20 63 6c 61 75 73  he COLLATE claus
160a0 65 20 69 6e 20 61 20 74 61 62 6c 65 0a 5b 63 6f  e in a table.[co
160b0 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 5d  lumn definition]
160c0 2e 0a 53 65 65 20 74 68 65 20 5b 63 6f 6c 6c 61  ..See the [colla
160d0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 7c 20 64  ting sequence| d
160e0 65 74 61 69 6c 65 64 20 64 69 73 63 75 73 73 69  etailed discussi
160f0 6f 6e 20 6f 6e 20 63 6f 6c 6c 61 74 69 6e 67 20  on on collating 
16100 73 65 71 75 65 6e 63 65 73 5d 0a 69 6e 20 74 68  sequences].in th
16110 65 20 5b 64 61 74 61 74 79 70 65 20 7c 20 44 61  e [datatype | Da
16120 74 61 74 79 70 65 20 49 6e 20 53 51 4c 69 74 65  tatype In SQLite
16130 33 5d 20 64 6f 63 75 6d 65 6e 74 20 66 6f 72 20  3] document for 
16140 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
16150 6d 61 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 74  mation..</p>..<t
16160 63 6c 3e 68 64 5f 70 75 74 73 20 22 0a 3c 70 3e  cl>hd_puts ".<p>
16170 5e 54 68 65 20 75 6e 61 72 79 20 6f 70 65 72 61  ^The unary opera
16180 74 6f 72 20 5b 4f 70 65 72 61 74 6f 72 20 2b 5d  tor [Operator +]
16190 20 69 73 20 61 20 6e 6f 2d 6f 70 2e 20 20 5e 49   is a no-op.  ^I
161a0 74 20 63 61 6e 20 62 65 20 61 70 70 6c 69 65 64  t can be applied
161b0 0a 74 6f 20 73 74 72 69 6e 67 73 2c 20 6e 75 6d  .to strings, num
161c0 62 65 72 73 2c 20 62 6c 6f 62 73 20 6f 72 20 4e  bers, blobs or N
161d0 55 4c 4c 20 61 6e 64 20 69 74 20 61 6c 77 61 79  ULL and it alway
161e0 73 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  s returns a resu
161f0 6c 74 0a 77 69 74 68 20 74 68 65 20 73 61 6d 65  lt.with the same
16200 20 76 61 6c 75 65 20 61 73 20 74 68 65 20 6f 70   value as the op
16210 65 72 61 6e 64 2e 3c 2f 70 3e 22 3c 2f 74 63 6c  erand.</p>"</tcl
16220 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20  >..<p>Note that 
16230 74 68 65 72 65 20 61 72 65 20 74 77 6f 20 76 61  there are two va
16240 72 69 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  riations of the 
16250 65 71 75 61 6c 73 20 61 6e 64 20 6e 6f 74 20 65  equals and not e
16260 71 75 61 6c 73 0a 6f 70 65 72 61 74 6f 72 73 2e  quals.operators.
16270 20 20 5e 45 71 75 61 6c 73 20 63 61 6e 20 62 65    ^Equals can be
16280 20 65 69 74 68 65 72 0a 0a 3c 74 63 6c 3e 0a 68   either..<tcl>.h
16290 64 5f 70 75 74 73 20 22 5b 4f 70 65 72 61 74 6f  d_puts "[Operato
162a0 72 20 3d 5d 20 6f 72 20 5b 4f 70 65 72 61 74 6f  r =] or [Operato
162b0 72 20 3d 3d 5d 2e 0a 5e 54 68 65 20 6e 6f 6e 2d  r ==]..^The non-
162c0 65 71 75 61 6c 73 20 6f 70 65 72 61 74 6f 72 20  equals operator 
162d0 63 61 6e 20 62 65 20 65 69 74 68 65 72 0a 5b 4f  can be either.[O
162e0 70 65 72 61 74 6f 72 20 21 3d 5d 20 6f 72 20 5b  perator !=] or [
162f0 4f 70 65 72 61 74 6f 72 20 7b 26 6c 74 3b 26 67  Operator {&lt;&g
16300 74 3b 7d 5d 2e 0a 5e 54 68 65 20 5b 4f 70 65 72  t;}]..^The [Oper
16310 61 74 6f 72 20 7c 7c 5d 20 6f 70 65 72 61 74 6f  ator ||] operato
16320 72 20 69 73 20 5c 22 63 6f 6e 63 61 74 65 6e 61  r is \"concatena
16330 74 65 5c 22 20 2d 20 69 74 20 6a 6f 69 6e 73 20  te\" - it joins 
16340 74 6f 67 65 74 68 65 72 0a 74 68 65 20 74 77 6f  together.the two
16350 20 73 74 72 69 6e 67 73 20 6f 66 20 69 74 73 20   strings of its 
16360 6f 70 65 72 61 6e 64 73 2e 0a 5e 54 68 65 20 6f  operands..^The o
16370 70 65 72 61 74 6f 72 20 5b 4f 70 65 72 61 74 6f  perator [Operato
16380 72 20 25 5d 20 6f 75 74 70 75 74 73 20 74 68 65  r %] outputs the
16390 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 6f   integer value o
163a0 66 20 69 74 73 20 6c 65 66 74 20 0a 6f 70 65 72  f its left .oper
163b0 61 6e 64 20 6d 6f 64 75 6c 6f 20 69 74 73 20 72  and modulo its r
163c0 69 67 68 74 20 6f 70 65 72 61 6e 64 2e 20 20 49  ight operand.  I
163d0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
163e0 68 65 0a 6f 70 65 72 61 74 6f 72 20 5b 4f 70 65  he.operator [Ope
163f0 72 61 74 6f 72 20 25 5d 20 77 6f 72 6b 73 20 69  rator %] works i
16400 6e 20 53 51 4c 69 74 65 20 74 68 65 20 73 61 6d  n SQLite the sam
16410 65 20 61 73 20 69 74 20 64 6f 65 73 0a 69 6e 20  e as it does.in 
16420 41 4e 53 49 2d 43 2e 3c 2f 70 3e 0a 0a 3c 70 3e  ANSI-C.</p>..<p>
16430 5e 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61  ^The result of a
16440 6e 79 20 62 69 6e 61 72 79 20 6f 70 65 72 61 74  ny binary operat
16450 6f 72 20 69 73 20 65 69 74 68 65 72 20 61 20 6e  or is either a n
16460 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 72 20  umeric value or 
16470 0a 4e 55 4c 4c 2c 20 65 78 63 65 70 74 20 66 6f  .NULL, except fo
16480 72 20 74 68 65 20 5b 4f 70 65 72 61 74 6f 72 20  r the [Operator 
16490 7c 7c 5d 20 63 6f 6e 63 61 74 65 6e 61 74 69 6f  ||] concatenatio
164a0 6e 20 6f 70 65 72 61 74 6f 72 20 77 68 69 63 68  n operator which
164b0 20 61 6c 77 61 79 73 20 0a 65 76 61 6c 75 61 74   always .evaluat
164c0 65 73 20 74 6f 20 65 69 74 68 65 72 20 4e 55 4c  es to either NUL
164d0 4c 20 6f 72 20 61 20 74 65 78 74 20 76 61 6c 75  L or a text valu
164e0 65 2e 3c 2f 70 3e 22 0a 0a 68 64 5f 66 72 61 67  e.</p>"..hd_frag
164f0 6d 65 6e 74 20 7b 69 73 69 73 6e 6f 74 7d 20 7b  ment {isisnot} {
16500 49 53 20 6f 70 65 72 61 74 6f 72 7d 20 7b 49 53  IS operator} {IS
16510 20 4e 4f 54 20 6f 70 65 72 61 74 6f 72 7d 0a 0a   NOT operator}..
16520 68 64 5f 70 75 74 73 20 22 3c 70 3e 5e 54 68 65  hd_puts "<p>^The
16530 20 5b 4f 70 65 72 61 74 6f 72 20 49 53 5d 20 61   [Operator IS] a
16540 6e 64 20 5b 4f 70 65 72 61 74 6f 72 20 7b 49 53  nd [Operator {IS
16550 20 4e 4f 54 7d 5d 20 6f 70 65 72 61 74 6f 72 73   NOT}] operators
16560 20 77 6f 72 6b 0a 6c 69 6b 65 20 5b 4f 70 65 72   work.like [Oper
16570 61 74 6f 72 20 3d 5d 20 61 6e 64 20 5b 4f 70 65  ator =] and [Ope
16580 72 61 74 6f 72 20 21 3d 5d 20 65 78 63 65 70 74  rator !=] except
16590 20 77 68 65 6e 20 6f 6e 65 20 6f 72 20 62 6f 74   when one or bot
165a0 68 20 6f 66 20 74 68 65 0a 6f 70 65 72 61 6e 64  h of the.operand
165b0 73 20 61 72 65 20 4e 55 4c 4c 2e 20 5e 49 6e 20  s are NULL. ^In 
165c0 74 68 69 73 20 63 61 73 65 2c 20 69 66 20 62 6f  this case, if bo
165d0 74 68 20 6f 70 65 72 61 6e 64 73 20 61 72 65 20  th operands are 
165e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 49  NULL, then the.I
165f0 53 20 6f 70 65 72 61 74 6f 72 20 65 76 61 6c 75  S operator evalu
16600 61 74 65 73 20 74 6f 20 31 20 28 74 72 75 65 29  ates to 1 (true)
16610 20 61 6e 64 20 74 68 65 20 49 53 20 4e 4f 54 20   and the IS NOT 
16620 6f 70 65 72 61 74 6f 72 20 65 76 61 6c 75 61 74  operator evaluat
16630 65 73 0a 74 6f 20 30 20 28 66 61 6c 73 65 29 2e  es.to 0 (false).
16640 20 5e 49 66 20 6f 6e 65 20 6f 70 65 72 61 6e 64   ^If one operand
16650 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65   is NULL and the
16660 20 6f 74 68 65 72 20 69 73 20 6e 6f 74 2c 20 74   other is not, t
16670 68 65 6e 20 74 68 65 0a 49 53 20 6f 70 65 72 61  hen the.IS opera
16680 74 6f 72 20 65 76 61 6c 75 61 74 65 73 20 74 6f  tor evaluates to
16690 20 30 20 28 66 61 6c 73 65 29 20 61 6e 64 20 74   0 (false) and t
166a0 68 65 20 49 53 20 4e 4f 54 20 6f 70 65 72 61 74  he IS NOT operat
166b0 6f 72 20 69 73 20 31 20 28 74 72 75 65 29 2e 0a  or is 1 (true)..
166c0 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
166d0 62 6c 65 20 66 6f 72 20 61 6e 20 49 53 20 6f 72  ble for an IS or
166e0 20 49 53 20 4e 4f 54 20 65 78 70 72 65 73 73 69   IS NOT expressi
166f0 6f 6e 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  on to evaluate t
16700 6f 20 4e 55 4c 4c 2e 0a 5e 4f 70 65 72 61 74 6f  o NULL..^Operato
16710 72 73 20 5b 4f 70 65 72 61 74 6f 72 20 49 53 5d  rs [Operator IS]
16720 20 61 6e 64 20 5b 4f 70 65 72 61 74 6f 72 20 7b   and [Operator {
16730 49 53 20 4e 4f 54 7d 5d 20 68 61 76 65 20 74 68  IS NOT}] have th
16740 65 20 73 61 6d 65 20 0a 70 72 65 63 65 64 65 6e  e same .preceden
16750 63 65 20 61 73 20 5b 4f 70 65 72 61 74 6f 72 20  ce as [Operator 
16760 3d 5d 2e 22 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  =]."..<tcl>hd_fr
16770 61 67 6d 65 6e 74 20 6c 69 74 76 61 6c 75 65 20  agment litvalue 
16780 7b 6c 69 74 65 72 61 6c 20 76 61 6c 75 65 7d 3c  {literal value}<
16790 2f 74 63 6c 3e 0a 3c 68 33 3e 4c 69 74 65 72 61  /tcl>.<h3>Litera
167a0 6c 20 56 61 6c 75 65 73 20 28 43 6f 6e 73 74 61  l Values (Consta
167b0 6e 74 73 29 3c 2f 68 33 3e 0a 3c 70 3e 0a 41 20  nts)</h3>.<p>.A 
167c0 6c 69 74 65 72 61 6c 20 76 61 6c 75 65 20 72 65  literal value re
167d0 70 72 65 73 65 6e 74 73 20 61 20 63 6f 6e 73 74  presents a const
167e0 61 6e 74 2e 0a 5e 4c 69 74 65 72 61 6c 20 76 61  ant..^Literal va
167f0 6c 75 65 73 20 6d 61 79 20 62 65 20 69 6e 74 65  lues may be inte
16800 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
16810 6f 69 6e 74 20 6e 75 6d 62 65 72 73 2c 20 73 74  oint numbers, st
16820 72 69 6e 67 73 2c 0a 42 4c 4f 42 73 2c 20 6f 72  rings,.BLOBs, or
16830 20 4e 55 4c 4c 73 2e 0a 3c 70 3e 0a 54 68 65 20   NULLs..<p>.The 
16840 73 79 6e 74 61 78 20 66 6f 72 20 69 6e 74 65 67  syntax for integ
16850 65 72 20 61 6e 64 20 66 6c 6f 61 74 69 6e 67 20  er and floating 
16860 70 6f 69 6e 74 20 6c 69 74 65 72 61 6c 73 20 28  point literals (
16870 63 6f 6c 6c 65 63 74 69 76 65 6c 79 0a 22 6e 75  collectively."nu
16880 6d 65 72 69 63 20 6c 69 74 65 72 61 6c 73 22 29  meric literals")
16890 20 69 73 20 73 68 6f 77 6e 20 62 79 20 74 68 65   is shown by the
168a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 69 61 67 72   following diagr
168b0 61 6d 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 42 75  am:</p>..<tcl>Bu
168c0 62 62 6c 65 44 69 61 67 72 61 6d 20 6e 75 6d 65  bbleDiagram nume
168d0 72 69 63 2d 6c 69 74 65 72 61 6c 3c 2f 74 63 6c  ric-literal</tcl
168e0 3e 0a 0a 3c 70 3e 0a 5e 28 49 66 20 61 20 6e 75  >..<p>.^(If a nu
168f0 6d 65 72 69 63 20 6c 69 74 65 72 61 6c 20 68 61  meric literal ha
16900 73 20 61 20 64 65 63 69 6d 61 6c 20 70 6f 69 6e  s a decimal poin
16910 74 20 6f 72 20 61 6e 20 65 78 70 6f 6e 65 6e 74  t or an exponent
16920 69 61 74 69 6f 6e 0a 63 6c 61 75 73 65 20 6f 72  iation.clause or
16930 20 69 66 20 69 74 73 20 6d 61 67 6e 69 74 75 64   if its magnitud
16940 65 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  e is less than -
16950 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
16960 38 30 38 20 6f 72 0a 67 72 65 61 74 65 72 20 74  808 or.greater t
16970 68 61 6e 20 39 32 32 33 33 37 32 30 33 36 38 35  han 922337203685
16980 34 37 37 35 38 30 37 2c 20 74 68 65 6e 20 69 74  4775807, then it
16990 20 69 73 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   is a floating p
169a0 6f 69 6e 74 20 6c 69 74 65 72 61 6c 2e 0a 4f 74  oint literal..Ot
169b0 68 65 72 77 69 73 65 20 69 73 20 69 74 20 69 73  herwise is it is
169c0 20 61 6e 20 20 69 6e 74 65 67 65 72 20 6c 69 74   an  integer lit
169d0 65 72 61 6c 2e 29 5e 0a 5e 54 68 65 20 22 45 22  eral.)^.^The "E"
169e0 20 63 68 61 72 61 63 74 65 72 20 74 68 61 74 20   character that 
169f0 62 65 67 69 6e 73 20 74 68 65 20 65 78 70 6f 6e  begins the expon
16a00 65 6e 74 69 61 74 69 6f 6e 0a 63 6c 61 75 73 65  entiation.clause
16a10 20 6f 66 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   of a floating p
16a20 6f 69 6e 74 20 6c 69 74 65 72 61 6c 20 63 61 6e  oint literal can
16a30 20 62 65 20 65 69 74 68 65 72 20 75 70 70 65 72   be either upper
16a40 20 6f 72 20 6c 6f 77 65 72 20 63 61 73 65 2e 0a   or lower case..
16a50 5e 28 54 68 65 20 22 2e 22 20 63 68 61 72 61 63  ^(The "." charac
16a60 74 65 72 20 69 73 20 61 6c 77 61 79 73 20 75 73  ter is always us
16a70 65 64 20 0a 61 73 20 74 68 65 20 64 65 63 69 6d  ed .as the decim
16a80 61 6c 20 70 6f 69 6e 74 20 65 76 65 6e 20 69 66  al point even if
16a90 20 74 68 65 20 6c 6f 63 61 6c 65 20 73 65 74 74   the locale sett
16aa0 69 6e 67 20 73 70 65 63 69 66 69 65 73 20 22 2c  ing specifies ",
16ab0 22 20 66 6f 72 0a 74 68 69 73 20 72 6f 6c 65 20  " for.this role 
16ac0 2d 20 74 68 65 20 75 73 65 20 6f 66 20 22 2c 22  - the use of ","
16ad0 20 66 6f 72 20 74 68 65 20 64 65 63 69 6d 61 6c   for the decimal
16ae0 20 70 6f 69 6e 74 20 77 6f 75 6c 64 20 72 65 73   point would res
16af0 75 6c 74 20 69 6e 0a 73 79 6e 74 61 63 74 69 63  ult in.syntactic
16b00 20 61 6d 62 69 67 75 69 74 79 2e 29 5e 0a 0a 3c   ambiguity.)^..<
16b10 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
16b20 68 65 78 69 6e 74 20 7b 68 65 78 61 64 65 63 69  hexint {hexadeci
16b30 6d 61 6c 20 69 6e 74 65 67 65 72 20 6c 69 74 65  mal integer lite
16b40 72 61 6c 73 7d 20 7b 68 65 78 61 64 65 63 69 6d  rals} {hexadecim
16b50 61 6c 20 69 6e 74 65 67 65 72 73 7d 3c 2f 74 63  al integers}</tc
16b60 6c 3e 0a 3c 70 3e 5e 48 65 78 61 64 65 63 69 6d  l>.<p>^Hexadecim
16b70 61 6c 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  al integer liter
16b80 61 6c 73 20 66 6f 6c 6c 6f 77 20 74 68 65 20 43  als follow the C
16b90 2d 6c 61 6e 67 75 61 67 65 20 6e 6f 74 61 74 69  -language notati
16ba0 6f 6e 20 6f 66 0a 22 30 78 22 20 6f 72 20 22 30  on of."0x" or "0
16bb0 58 22 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 68  X" followed by h
16bc0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
16bd0 73 2e 0a 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s..^For example,
16be0 20 30 78 31 32 33 34 20 6d 65 61 6e 73 20 74 68   0x1234 means th
16bf0 65 20 73 61 6d 65 20 61 73 20 34 36 36 30 0a 61  e same as 4660.a
16c00 6e 64 20 30 78 38 30 30 30 30 30 30 30 30 30 30  nd 0x80000000000
16c10 30 30 30 30 30 20 6d 65 61 6e 73 20 74 68 65 20  00000 means the 
16c20 73 61 6d 65 20 61 73 20 2d 39 32 32 33 33 37 32  same as -9223372
16c30 30 33 36 38 35 34 37 37 35 38 30 38 2e 0a 20 5e  036854775808.. ^
16c40 28 48 65 78 61 64 65 63 69 6d 61 6c 20 69 6e 74  (Hexadecimal int
16c50 65 67 65 72 20 6c 69 74 65 72 61 6c 73 20 61 72  eger literals ar
16c60 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16c70 20 36 34 2d 62 69 74 0a 74 77 6f 27 73 2d 63 6f   64-bit.two's-co
16c80 6d 70 6c 65 6d 65 6e 74 20 69 6e 74 65 67 65 72  mplement integer
16c90 73 20 61 6e 64 20 61 72 65 20 74 68 75 73 20 6c  s and are thus l
16ca0 69 6d 69 74 65 64 0a 74 6f 20 73 69 78 74 65 65  imited.to sixtee
16cb0 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 20 64 69  n significant di
16cc0 67 69 74 73 20 6f 66 20 70 72 65 63 69 73 69 6f  gits of precisio
16cd0 6e 2e 29 5e 0a 53 75 70 70 6f 72 74 20 66 6f 72  n.)^.Support for
16ce0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 69 6e 74   hexadecimal int
16cf0 65 67 65 72 73 20 77 61 73 20 61 64 64 65 64 20  egers was added 
16d00 74 6f 20 53 51 4c 69 74 65 0a 76 65 72 73 69 6f  to SQLite.versio
16d10 6e 20 33 2e 38 2e 36 20 28 5b 64 61 74 65 6f 66  n 3.8.6 ([dateof
16d20 3a 33 2e 38 2e 36 5d 29 2e 0a 5e 46 6f 72 20 62  :3.8.6])..^For b
16d30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
16d40 62 69 6c 69 74 79 2c 20 74 68 65 20 22 30 78 22  bility, the "0x"
16d50 20 68 65 78 61 64 65 63 69 6d 61 6c 20 69 6e 74   hexadecimal int
16d60 65 67 65 72 0a 6e 6f 74 61 74 69 6f 6e 20 69 73  eger.notation is
16d70 20 6f 6e 6c 79 20 75 6e 64 65 72 73 74 6f 6f 64   only understood
16d80 20 62 79 20 74 68 65 20 53 51 4c 20 6c 61 6e 67   by the SQL lang
16d90 75 61 67 65 20 70 61 72 73 65 72 2c 20 6e 6f 74  uage parser, not
16da0 20 62 79 20 74 68 65 0a 74 79 70 65 20 63 6f 6e   by the.type con
16db0 76 65 72 73 69 6f 6e 73 20 72 6f 75 74 69 6e 65  versions routine
16dc0 73 2e 0a 5e 28 53 74 72 69 6e 67 20 76 61 72 69  s..^(String vari
16dd0 61 62 6c 65 73 20 74 68 61 74 0a 63 6f 6e 74 61  ables that.conta
16de0 69 6e 20 74 65 78 74 20 66 6f 72 6d 61 74 74 65  in text formatte
16df0 64 20 6c 69 6b 65 20 68 65 78 61 64 65 63 69 6d  d like hexadecim
16e00 61 6c 20 69 6e 74 65 67 65 72 73 20 61 72 65 20  al integers are 
16e10 6e 6f 74 0a 69 6e 74 65 72 70 72 65 74 65 64 20  not.interpreted 
16e20 61 73 20 68 65 78 61 64 65 63 69 6d 61 6c 20 69  as hexadecimal i
16e30 6e 74 65 67 65 72 73 20 77 68 65 6e 20 63 6f 65  ntegers when coe
16e40 72 63 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  rcing the string
16e50 20 76 61 6c 75 65 0a 69 6e 74 6f 20 61 6e 20 69   value.into an i
16e60 6e 74 65 67 65 72 20 64 75 65 20 74 6f 20 61 20  nteger due to a 
16e70 5b 43 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e  [CAST expression
16e80 5d 20 6f 72 20 66 6f 72 20 61 20 5b 63 6f 6c 75  ] or for a [colu
16e90 6d 6e 20 61 66 66 69 6e 69 74 79 5d 0a 74 72 61  mn affinity].tra
16ea0 6e 73 66 6f 72 6d 61 74 69 6f 6e 20 6f 72 20 70  nsformation or p
16eb0 72 69 6f 72 20 74 6f 20 70 65 72 66 6f 72 6d 69  rior to performi
16ec0 6e 67 20 61 20 6e 75 6d 65 72 69 63 20 6f 70 65  ng a numeric ope
16ed0 72 61 74 69 6f 6e 20 6f 72 20 66 6f 72 0a 61 6e  ration or for.an
16ee0 79 20 6f 74 68 65 72 20 72 75 6e 2d 74 69 6d 65  y other run-time
16ef0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2e 29 5e 20   conversions.)^ 
16f00 20 5e 28 57 68 65 6e 20 63 6f 65 72 63 69 6e 67   ^(When coercing
16f10 20 61 0a 73 74 72 69 6e 67 20 76 61 6c 75 65 20   a.string value 
16f20 69 6e 20 74 68 65 20 66 6f 72 6d 61 74 20 6f 66  in the format of
16f30 20 61 20 68 65 78 61 64 65 63 69 6d 61 6c 20 69   a hexadecimal i
16f40 6e 74 65 67 65 72 20 69 6e 74 6f 20 61 6e 20 69  nteger into an i
16f50 6e 74 65 67 65 72 0a 76 61 6c 75 65 2c 20 74 68  nteger.value, th
16f60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 70 72 6f  e conversion pro
16f70 63 65 73 73 20 73 74 6f 70 73 20 77 68 65 6e 20  cess stops when 
16f80 74 68 65 20 27 78 27 20 63 68 61 72 61 63 74 65  the 'x' characte
16f90 72 20 69 73 20 73 65 65 6e 0a 73 6f 20 74 68 65  r is seen.so the
16fa0 20 72 65 73 75 6c 74 69 6e 67 20 69 6e 74 65 67   resulting integ
16fb0 65 72 20 76 61 6c 75 65 20 69 73 20 61 6c 77 61  er value is alwa
16fc0 79 73 20 7a 65 72 6f 2e 29 5e 0a 5e 28 53 51 4c  ys zero.)^.^(SQL
16fd0 69 74 65 20 6f 6e 6c 79 20 75 6e 64 65 72 73 74  ite only underst
16fe0 61 6e 64 73 20 74 68 65 20 68 65 78 61 64 65 63  ands the hexadec
16ff0 69 6d 61 6c 20 69 6e 74 65 67 65 72 20 6e 6f 74  imal integer not
17000 61 74 69 6f 6e 20 77 68 65 6e 20 69 74 0a 61 70  ation when it.ap
17010 70 65 61 72 73 20 69 6e 20 74 68 65 20 53 51 4c  pears in the SQL
17020 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 2c   statement text,
17030 20 6e 6f 74 20 77 68 65 6e 20 69 74 20 61 70 70   not when it app
17040 65 61 72 73 20 61 73 0a 70 61 72 74 20 6f 66 20  ears as.part of 
17050 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
17060 68 65 20 64 61 74 61 62 61 73 65 2e 29 5e 0a 0a  he database.)^..
17070 3c 70 3e 20 5e 41 20 73 74 72 69 6e 67 20 63 6f  <p> ^A string co
17080 6e 73 74 61 6e 74 20 69 73 20 66 6f 72 6d 65 64  nstant is formed
17090 20 62 79 20 65 6e 63 6c 6f 73 69 6e 67 20 74 68   by enclosing th
170a0 65 0a 73 74 72 69 6e 67 20 69 6e 20 73 69 6e 67  e.string in sing
170b0 6c 65 20 71 75 6f 74 65 73 20 28 27 29 2e 20 20  le quotes (').  
170c0 5e 41 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 20  ^A single quote 
170d0 77 69 74 68 69 6e 20 74 68 65 20 73 74 72 69 6e  within the strin
170e0 67 20 63 61 6e 0a 62 65 20 65 6e 63 6f 64 65 64  g can.be encoded
170f0 20 62 79 20 70 75 74 74 69 6e 67 20 74 77 6f 20   by putting two 
17100 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 69 6e  single quotes in
17110 20 61 20 72 6f 77 20 2d 20 61 73 20 69 6e 20 50   a row - as in P
17120 61 73 63 61 6c 2e 0a 43 2d 73 74 79 6c 65 20 65  ascal..C-style e
17130 73 63 61 70 65 73 20 75 73 69 6e 67 20 74 68 65  scapes using the
17140 20 62 61 63 6b 73 6c 61 73 68 20 63 68 61 72 61   backslash chara
17150 63 74 65 72 20 61 72 65 20 6e 6f 74 20 73 75 70  cter are not sup
17160 70 6f 72 74 65 64 20 62 65 63 61 75 73 65 0a 74  ported because.t
17170 68 65 79 20 61 72 65 20 6e 6f 74 20 73 74 61 6e  hey are not stan
17180 64 61 72 64 20 53 51 4c 2e 0a 0a 3c 70 3e 20 5e  dard SQL...<p> ^
17190 42 4c 4f 42 20 6c 69 74 65 72 61 6c 73 20 61 72  BLOB literals ar
171a0 65 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  e string literal
171b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 68 65 78  s containing hex
171c0 61 64 65 63 69 6d 61 6c 20 64 61 74 61 20 61 6e  adecimal data an
171d0 64 0a 70 72 65 63 65 64 65 64 20 62 79 20 61 20  d.preceded by a 
171e0 73 69 6e 67 6c 65 20 22 78 22 20 6f 72 20 22 58  single "x" or "X
171f0 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 5e 28  " character.  ^(
17200 45 78 61 6d 70 6c 65 3a 20 58 27 35 33 35 31 34  Example: X'53514
17210 43 36 39 37 34 36 35 27 29 5e 0a 0a 3c 70 3e 0a  C697465')^..<p>.
17220 5e 41 20 6c 69 74 65 72 61 6c 20 76 61 6c 75 65  ^A literal value
17230 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 74 68 65   can also be the
17240 20 74 6f 6b 65 6e 20 22 4e 55 4c 4c 22 2e 0a 3c   token "NULL"..<
17250 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  /p>..<tcl>hd_fra
17260 67 6d 65 6e 74 20 76 61 72 70 61 72 61 6d 20 70  gment varparam p
17270 61 72 61 6d 65 74 65 72 20 70 61 72 61 6d 65 74  arameter paramet
17280 65 72 73 20 7b 62 6f 75 6e 64 20 70 61 72 61 6d  ers {bound param
17290 65 74 65 72 7d 20 7b 62 6f 75 6e 64 20 70 61 72  eter} {bound par
172a0 61 6d 65 74 65 72 73 7d 3c 2f 74 63 6c 3e 0a 3c  ameters}</tcl>.<
172b0 68 33 3e 50 61 72 61 6d 65 74 65 72 73 3c 2f 68  h3>Parameters</h
172c0 33 3e 0a 3c 70 3e 0a 41 20 22 76 61 72 69 61 62  3>.<p>.A "variab
172d0 6c 65 22 20 6f 72 20 22 70 61 72 61 6d 65 74 65  le" or "paramete
172e0 72 22 20 74 6f 6b 65 6e 0a 73 70 65 63 69 66 69  r" token.specifi
172f0 65 73 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72  es a placeholder
17300 20 69 6e 20 74 68 65 20 65 78 70 72 65 73 73 69   in the expressi
17310 6f 6e 20 66 6f 72 20 61 20 0a 76 61 6c 75 65 20  on for a .value 
17320 74 68 61 74 20 69 73 20 66 69 6c 6c 65 64 20 69  that is filled i
17330 6e 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69  n at runtime usi
17340 6e 67 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f  ng the.[sqlite3_
17350 62 69 6e 64 5f 62 6c 6f 62 28 29 20 7c 20 73 71  bind_blob() | sq
17360 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 20 66 61  lite3_bind()] fa
17370 6d 69 6c 79 20 6f 66 20 43 2f 43 2b 2b 20 69 6e  mily of C/C++ in
17380 74 65 72 66 61 63 65 73 2e 0a 50 61 72 61 6d 65  terfaces..Parame
17390 74 65 72 73 20 63 61 6e 20 74 61 6b 65 20 73 65  ters can take se
173a0 76 65 72 61 6c 20 66 6f 72 6d 73 3a 0a 3c 2f 70  veral forms:.</p
173b0 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
173c0 3c 74 61 62 6c 65 3e 0a 3c 74 72 3e 0a 3c 74 64  <table>.<tr>.<td
173d0 20 61 6c 69 67 6e 3d 22 72 69 67 68 74 22 20 76   align="right" v
173e0 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c 62 3e 3f  align="top"><b>?
173f0 3c 2f 62 3e 3c 69 3e 4e 4e 4e 3c 2f 69 3e 3c 2f  </b><i>NNN</i></
17400 74 64 3e 3c 74 64 20 77 69 64 74 68 3d 22 32 30  td><td width="20
17410 22 3e 3c 2f 74 64 3e 0a 3c 74 64 3e 5e 28 41 20  "></td>.<td>^(A 
17420 71 75 65 73 74 69 6f 6e 20 6d 61 72 6b 20 66 6f  question mark fo
17430 6c 6c 6f 77 65 64 20 62 79 20 61 20 6e 75 6d 62  llowed by a numb
17440 65 72 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 68 6f  er <i>NNN</i> ho
17450 6c 64 73 20 61 20 73 70 6f 74 20 66 6f 72 20 74  lds a spot for t
17460 68 65 0a 4e 4e 4e 2d 74 68 20 70 61 72 61 6d 65  he.NNN-th parame
17470 74 65 72 2e 20 20 4e 4e 4e 20 6d 75 73 74 20 62  ter.  NNN must b
17480 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
17490 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49  [SQLITE_MAX_VARI
174a0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 2e 29 5e 0a  ABLE_NUMBER].)^.
174b0 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74 72 3e  </td>.</tr>.<tr>
174c0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69 67 68  .<td align="righ
174d0 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  t" valign="top">
174e0 3c 62 3e 3f 3c 2f 62 3e 3c 2f 74 64 3e 3c 74 64  <b>?</b></td><td
174f0 20 77 69 64 74 68 3d 22 32 30 22 3e 3c 2f 74 64   width="20"></td
17500 3e 0a 3c 74 64 3e 5e 41 20 71 75 65 73 74 69 6f  >.<td>^A questio
17510 6e 20 6d 61 72 6b 20 74 68 61 74 20 69 73 20 6e  n mark that is n
17520 6f 74 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  ot followed by a
17530 20 6e 75 6d 62 65 72 20 63 72 65 61 74 65 73 20   number creates 
17540 61 20 70 61 72 61 6d 65 74 65 72 0a 77 69 74 68  a parameter.with
17550 20 61 20 6e 75 6d 62 65 72 20 6f 6e 65 20 67 72   a number one gr
17560 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 6c  eater than the l
17570 61 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72  argest parameter
17580 20 6e 75 6d 62 65 72 20 61 6c 72 65 61 64 79 20   number already 
17590 61 73 73 69 67 6e 65 64 2e 0a 5e 49 66 20 74 68  assigned..^If th
175a0 69 73 20 6d 65 61 6e 73 20 74 68 65 20 70 61 72  is means the par
175b0 61 6d 65 74 65 72 20 6e 75 6d 62 65 72 20 69 73  ameter number is
175c0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 5b 53   greater than.[S
175d0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
175e0 4c 45 5f 4e 55 4d 42 45 52 5d 2c 20 69 74 20 69  LE_NUMBER], it i
175f0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 54 68 69 73  s an error..This
17600 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 61   parameter forma
17610 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  t is provided fo
17620 72 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  r compatibility 
17630 77 69 74 68 20 6f 74 68 65 72 20 64 61 74 61 62  with other datab
17640 61 73 65 0a 65 6e 67 69 6e 65 73 2e 20 20 42 75  ase.engines.  Bu
17650 74 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  t because it is 
17660 65 61 73 79 20 74 6f 20 6d 69 73 63 6f 75 6e 74  easy to miscount
17670 20 74 68 65 20 71 75 65 73 74 69 6f 6e 20 6d 61   the question ma
17680 72 6b 73 2c 20 74 68 65 0a 75 73 65 20 6f 66 20  rks, the.use of 
17690 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 66  this parameter f
176a0 6f 72 6d 61 74 20 69 73 20 64 69 73 63 6f 75 72  ormat is discour
176b0 61 67 65 64 2e 20 20 50 72 6f 67 72 61 6d 6d 65  aged.  Programme
176c0 72 73 20 61 72 65 20 65 6e 63 6f 75 72 61 67 65  rs are encourage
176d0 64 0a 74 6f 20 75 73 65 20 6f 6e 65 20 6f 66 20  d.to use one of 
176e0 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 66 6f 72  the symbolic for
176f0 6d 61 74 73 20 62 65 6c 6f 77 20 6f 72 20 74 68  mats below or th
17700 65 20 3f 4e 4e 4e 20 66 6f 72 6d 61 74 20 61 62  e ?NNN format ab
17710 6f 76 65 20 69 6e 73 74 65 61 64 2e 0a 3c 2f 74  ove instead..</t
17720 64 3e 0a 3c 2f 74 72 3e 0a 3c 74 72 3e 0a 3c 74  d>.</tr>.<tr>.<t
17730 64 20 61 6c 69 67 6e 3d 22 72 69 67 68 74 22 20  d align="right" 
17740 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c 62 3e  valign="top"><b>
17750 3a 3c 2f 62 3e 3c 69 3e 41 41 41 41 3c 2f 69 3e  :</b><i>AAAA</i>
17760 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74 68 3d 22  </td><td width="
17770 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74 64 3e 5e 41  20"></td>.<td>^A
17780 20 63 6f 6c 6f 6e 20 66 6f 6c 6c 6f 77 65 64 20   colon followed 
17790 62 79 20 61 6e 20 69 64 65 6e 74 69 66 69 65 72  by an identifier
177a0 20 6e 61 6d 65 20 68 6f 6c 64 73 20 61 20 73 70   name holds a sp
177b0 6f 74 20 66 6f 72 20 61 20 0a 5b 73 71 6c 69 74  ot for a .[sqlit
177c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
177d0 72 5f 6e 61 6d 65 7c 6e 61 6d 65 64 20 70 61 72  r_name|named par
177e0 61 6d 65 74 65 72 5d 20 77 69 74 68 20 74 68 65  ameter] with the
177f0 20 6e 61 6d 65 20 3a 41 41 41 41 2e 20 20 0a 5e   name :AAAA.  .^
17800 28 4e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72  (Named parameter
17810 73 20 61 72 65 20 61 6c 73 6f 20 6e 75 6d 62 65  s are also numbe
17820 72 65 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  red. The number 
17830 61 73 73 69 67 6e 65 64 20 69 73 20 6f 6e 65 20  assigned is one 
17840 67 72 65 61 74 65 72 20 74 68 61 6e 0a 74 68 65  greater than.the
17850 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74   largest paramet
17860 65 72 20 6e 75 6d 62 65 72 20 61 6c 72 65 61 64  er number alread
17870 79 20 61 73 73 69 67 6e 65 64 2e 29 5e 20 5e 49  y assigned.)^ ^I
17880 66 20 74 68 69 73 20 6d 65 61 6e 73 20 74 68 65  f this means the
17890 20 70 61 72 61 6d 65 74 65 72 0a 77 6f 75 6c 64   parameter.would
178a0 20 62 65 20 61 73 73 69 67 6e 65 64 20 61 20 6e   be assigned a n
178b0 75 6d 62 65 72 20 67 72 65 61 74 65 72 20 74 68  umber greater th
178c0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 56  an [SQLITE_MAX_V
178d0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 2c  ARIABLE_NUMBER],
178e0 20 69 74 20 69 73 0a 61 6e 20 65 72 72 6f 72 2e   it is.an error.
178f0 20 54 6f 20 61 76 6f 69 64 20 63 6f 6e 66 75 73   To avoid confus
17900 69 6f 6e 2c 20 69 74 20 69 73 20 62 65 73 74 20  ion, it is best 
17910 74 6f 20 61 76 6f 69 64 20 6d 69 78 69 6e 67 20  to avoid mixing 
17920 6e 61 6d 65 64 20 61 6e 64 20 6e 75 6d 62 65 72  named and number
17930 65 64 0a 70 61 72 61 6d 65 74 65 72 73 2e 3c 2f  ed.parameters.</
17940 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74 72 3e 0a 3c  td>.</tr>.<tr>.<
17950 74 64 20 61 6c 69 67 6e 3d 22 72 69 67 68 74 22  td align="right"
17960 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c 62   valign="top"><b
17970 3e 40 3c 2f 62 3e 3c 69 3e 41 41 41 41 3c 2f 69  >@</b><i>AAAA</i
17980 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74 68 3d  ></td><td width=
17990 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74 64 3e 5e  "20"></td>.<td>^
179a0 41 6e 20 22 61 74 22 20 73 69 67 6e 20 77 6f 72  An "at" sign wor
179b0 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
179c0 61 20 63 6f 6c 6f 6e 2c 20 65 78 63 65 70 74 20  a colon, except 
179d0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6f 66  that the name of
179e0 0a 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 63  .the parameter c
179f0 72 65 61 74 65 64 20 69 73 20 40 41 41 41 41 2e  reated is @AAAA.
17a00 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 74 72 3e  </td>.</tr>.<tr>
17a10 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 72 69 67 68  .<td align="righ
17a20 74 22 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  t" valign="top">
17a30 3c 62 3e 24 3c 2f 62 3e 3c 69 3e 41 41 41 41 3c  <b>$</b><i>AAAA<
17a40 2f 69 3e 3c 2f 74 64 3e 3c 74 64 20 77 69 64 74  /i></td><td widt
17a50 68 3d 22 32 30 22 3e 3c 2f 74 64 3e 0a 3c 74 64  h="20"></td>.<td
17a60 3e 5e 41 20 64 6f 6c 6c 61 72 2d 73 69 67 6e 20  >^A dollar-sign 
17a70 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e 20 69  followed by an i
17a80 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 20 61  dentifier name a
17a90 6c 73 6f 20 68 6f 6c 64 73 20 61 20 73 70 6f 74  lso holds a spot
17aa0 20 66 6f 72 20 61 20 6e 61 6d 65 64 0a 70 61 72   for a named.par
17ab0 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
17ac0 6e 61 6d 65 20 24 41 41 41 41 2e 20 20 5e 28 54  name $AAAA.  ^(T
17ad0 68 65 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  he identifier na
17ae0 6d 65 20 69 6e 20 74 68 69 73 20 63 61 73 65 20  me in this case 
17af0 63 61 6e 20 69 6e 63 6c 75 64 65 0a 6f 6e 65 20  can include.one 
17b00 6f 72 20 6d 6f 72 65 20 6f 63 63 75 72 72 65 6e  or more occurren
17b10 63 65 73 20 6f 66 20 22 3a 3a 22 20 61 6e 64 20  ces of "::" and 
17b20 61 20 73 75 66 66 69 78 20 65 6e 63 6c 6f 73 65  a suffix enclose
17b30 64 20 69 6e 20 22 28 2e 2e 2e 29 22 20 63 6f 6e  d in "(...)" con
17b40 74 61 69 6e 69 6e 67 0a 61 6e 79 20 74 65 78 74  taining.any text
17b50 20 61 74 20 61 6c 6c 2e 29 5e 20 20 54 68 69 73   at all.)^  This
17b60 20 73 79 6e 74 61 78 20 69 73 20 74 68 65 20 66   syntax is the f
17b70 6f 72 6d 20 6f 66 20 61 20 76 61 72 69 61 62 6c  orm of a variabl
17b80 65 20 6e 61 6d 65 20 69 6e 20 74 68 65 0a 5b 68  e name in the.[h
17b90 74 74 70 3a 2f 2f 77 77 77 2e 74 63 6c 2d 6c 61  ttp://www.tcl-la
17ba0 6e 67 2e 6f 72 67 2f 20 7c 20 54 63 6c 20 70 72  ng.org/ | Tcl pr
17bb0 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61  ogramming langua
17bc0 67 65 5d 2e 20 20 54 68 65 20 70 72 65 73 65 6e  ge].  The presen
17bd0 63 65 0a 6f 66 20 74 68 69 73 20 73 79 6e 74 61  ce.of this synta
17be0 78 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 74  x results from t
17bf0 68 65 20 66 61 63 74 20 74 68 61 74 20 53 51 4c  he fact that SQL
17c00 69 74 65 20 69 73 20 72 65 61 6c 6c 79 20 61 20  ite is really a 
17c10 0a 5b 54 63 6c 20 65 78 74 65 6e 73 69 6f 6e 5d  .[Tcl extension]
17c20 20 74 68 61 74 20 68 61 73 20 65 73 63 61 70 65   that has escape
17c30 64 20 69 6e 74 6f 20 74 68 65 20 77 69 6c 64 2e  d into the wild.
17c40 3c 2f 74 64 3e 0a 3c 2f 74 72 3e 0a 3c 2f 74 61  </td>.</tr>.</ta
17c50 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  ble>.</blockquot
17c60 65 3e 0a 0a 3c 70 3e 5e 50 61 72 61 6d 65 74 65  e>..<p>^Paramete
17c70 72 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20  rs that are not 
17c80 61 73 73 69 67 6e 65 64 20 76 61 6c 75 65 73 20  assigned values 
17c90 75 73 69 6e 67 0a 5b 73 71 6c 69 74 65 33 5f 62  using.[sqlite3_b
17ca0 69 6e 64 5f 62 6c 6f 62 28 29 20 7c 20 73 71 6c  ind_blob() | sql
17cb0 69 74 65 33 5f 62 69 6e 64 28 29 5d 20 61 72 65  ite3_bind()] are
17cc0 20 74 72 65 61 74 65 64 0a 61 73 20 4e 55 4c 4c   treated.as NULL
17cd0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
17ce0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
17cf0 6e 64 65 78 28 29 5d 20 69 6e 74 65 72 66 61 63  ndex()] interfac
17d00 65 20 63 61 6e 20 62 65 20 75 73 65 64 0a 74 6f  e can be used.to
17d10 20 74 72 61 6e 73 6c 61 74 65 20 61 20 73 79 6d   translate a sym
17d20 62 6f 6c 69 63 20 70 61 72 61 6d 65 74 65 72 20  bolic parameter 
17d30 6e 61 6d 65 20 69 6e 74 6f 20 69 74 73 20 65 71  name into its eq
17d40 75 69 76 61 6c 65 6e 74 20 6e 75 6d 65 72 69 63  uivalent numeric
17d50 20 69 6e 64 65 78 2e 3c 2f 70 3e 0a 0a 3c 70 3e   index.</p>..<p>
17d60 5e 54 68 65 20 6d 61 78 69 6d 75 6d 20 70 61 72  ^The maximum par
17d70 61 6d 65 74 65 72 20 6e 75 6d 62 65 72 20 69 73  ameter number is
17d80 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
17d90 74 69 6d 65 20 62 79 0a 74 68 65 20 5b 53 51 4c  time by.the [SQL
17da0 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
17db0 5f 4e 55 4d 42 45 52 5d 20 6d 61 63 72 6f 2e 20  _NUMBER] macro. 
17dc0 20 5e 28 41 6e 20 69 6e 64 69 76 69 64 75 61 6c   ^(An individual
17dd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17de0 63 74 69 6f 6e 5d 0a 44 20 63 61 6e 20 72 65 64  ction].D can red
17df0 75 63 65 20 69 74 73 20 6d 61 78 69 6d 75 6d 20  uce its maximum 
17e00 70 61 72 61 6d 65 74 65 72 20 6e 75 6d 62 65 72  parameter number
17e10 20 62 65 6c 6f 77 20 74 68 65 20 63 6f 6d 70 69   below the compi
17e20 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 0a  le-time maximum.
17e30 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
17e40 65 33 5f 6c 69 6d 69 74 5d 28 44 2c 20 5b 53 51  e3_limit](D, [SQ
17e50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
17e60 42 4c 45 5f 4e 55 4d 42 45 52 5d 2c 2e 2e 2e 29  BLE_NUMBER],...)
17e70 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 3c 2f   interface.)^.</
17e80 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  p>..<tcl>hd_frag
17e90 6d 65 6e 74 20 6c 69 6b 65 20 4c 49 4b 45 20 45  ment like LIKE E
17ea0 53 43 41 50 45 3c 2f 74 63 6c 3e 0a 3c 68 33 3e  SCAPE</tcl>.<h3>
17eb0 54 68 65 20 4c 49 4b 45 2c 20 47 4c 4f 42 2c 20  The LIKE, GLOB, 
17ec0 52 45 47 45 58 50 2c 20 61 6e 64 20 4d 41 54 43  REGEXP, and MATC
17ed0 48 20 6f 70 65 72 61 74 6f 72 73 3c 2f 68 33 3e  H operators</h3>
17ee0 0a 3c 70 3e 5e 54 68 65 20 4c 49 4b 45 20 6f 70  .<p>^The LIKE op
17ef0 65 72 61 74 6f 72 20 64 6f 65 73 20 61 20 70 61  erator does a pa
17f00 74 74 65 72 6e 20 6d 61 74 63 68 69 6e 67 20 63  ttern matching c
17f10 6f 6d 70 61 72 69 73 6f 6e 2e 20 5e 54 68 65 20  omparison. ^The 
17f20 6f 70 65 72 61 6e 64 0a 74 6f 20 74 68 65 20 72  operand.to the r
17f30 69 67 68 74 20 6f 66 20 74 68 65 20 4c 49 4b 45  ight of the LIKE
17f40 20 6f 70 65 72 61 74 6f 72 20 63 6f 6e 74 61 69   operator contai
17f50 6e 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  ns the pattern a
17f60 6e 64 20 74 68 65 20 6c 65 66 74 20 68 61 6e 64  nd the left hand
17f70 0a 6f 70 65 72 61 6e 64 20 63 6f 6e 74 61 69 6e  .operand contain
17f80 73 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  s the string to 
17f90 6d 61 74 63 68 20 61 67 61 69 6e 73 74 20 74 68  match against th
17fa0 65 20 70 61 74 74 65 72 6e 2e 0a 0a 3c 74 63 6c  e pattern...<tcl
17fb0 3e 68 64 5f 70 75 74 73 20 22 5e 41 20 70 65 72  >hd_puts "^A per
17fc0 63 65 6e 74 20 73 79 6d 62 6f 6c 20 28 5c 22 25  cent symbol (\"%
17fd0 5c 22 29 20 69 6e 20 74 68 65 20 4c 49 4b 45 20  \") in the LIKE 
17fe0 70 61 74 74 65 72 6e 20 6d 61 74 63 68 65 73 20  pattern matches 
17ff0 61 6e 79 0a 73 65 71 75 65 6e 63 65 20 6f 66 20  any.sequence of 
18000 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 63 68 61  zero or more cha
18010 72 61 63 74 65 72 73 20 69 6e 20 74 68 65 20 73  racters in the s
18020 74 72 69 6e 67 2e 20 20 5e 41 6e 20 75 6e 64 65  tring.  ^An unde
18030 72 73 63 6f 72 65 0a 28 5c 22 5f 5c 22 29 20 69  rscore.(\"_\") i
18040 6e 20 74 68 65 20 4c 49 4b 45 20 70 61 74 74 65  n the LIKE patte
18050 72 6e 20 6d 61 74 63 68 65 73 20 61 6e 79 20 73  rn matches any s
18060 69 6e 67 6c 65 20 63 68 61 72 61 63 74 65 72 20  ingle character 
18070 69 6e 20 74 68 65 0a 73 74 72 69 6e 67 2e 20 20  in the.string.  
18080 5e 28 41 6e 79 20 6f 74 68 65 72 20 63 68 61 72  ^(Any other char
18090 61 63 74 65 72 20 6d 61 74 63 68 65 73 20 69 74  acter matches it
180a0 73 65 6c 66 20 6f 72 20 69 74 73 20 6c 6f 77 65  self or its lowe
180b0 72 2f 75 70 70 65 72 20 63 61 73 65 0a 65 71 75  r/upper case.equ
180c0 69 76 61 6c 65 6e 74 20 28 69 2e 65 2e 20 63 61  ivalent (i.e. ca
180d0 73 65 2d 69 6e 73 65 6e 73 69 74 69 76 65 20 6d  se-insensitive m
180e0 61 74 63 68 69 6e 67 29 2e 29 5e 0a 0a 3c 75 3e  atching).)^..<u>
180f0 49 6d 70 6f 72 74 61 6e 74 20 4e 6f 74 65 3a 3c  Important Note:<
18100 2f 75 3e 20 5e 53 51 4c 69 74 65 20 6f 6e 6c 79  /u> ^SQLite only
18110 0a 75 6e 64 65 72 73 74 61 6e 64 73 20 75 70 70  .understands upp
18120 65 72 2f 6c 6f 77 65 72 20 63 61 73 65 20 66 6f  er/lower case fo
18130 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  r ASCII characte
18140 72 73 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  rs by default.  
18150 5e 54 68 65 0a 4c 49 4b 45 20 6f 70 65 72 61 74  ^The.LIKE operat
18160 6f 72 20 69 73 20 63 61 73 65 20 73 65 6e 73 69  or is case sensi
18170 74 69 76 65 20 62 79 20 64 65 66 61 75 6c 74 20  tive by default 
18180 66 6f 72 20 75 6e 69 63 6f 64 65 20 63 68 61 72  for unicode char
18190 61 63 74 65 72 73 20 74 68 61 74 20 61 72 65 0a  acters that are.
181a0 62 65 79 6f 6e 64 20 74 68 65 20 41 53 43 49 49  beyond the ASCII
181b0 20 72 61 6e 67 65 2e 20 20 46 6f 72 20 65 78 61   range.  For exa
181c0 6d 70 6c 65 2c 0a 5e 74 68 65 20 65 78 70 72 65  mple,.^the expre
181d0 73 73 69 6f 6e 20 3c 62 3e 27 61 27 26 6e 62 73  ssion <b>'a'&nbs
181e0 70 3b 4c 49 4b 45 26 6e 62 73 70 3b 27 41 27 3c  p;LIKE&nbsp;'A'<
181f0 2f 62 3e 0a 69 73 20 54 52 55 45 20 62 75 74 20  /b>.is TRUE but 
18200 3c 62 3e 27 26 61 65 6c 69 67 3b 27 26 6e 62 73  <b>'&aelig;'&nbs
18210 70 3b 4c 49 4b 45 26 6e 62 73 70 3b 27 26 41 45  p;LIKE&nbsp;'&AE
18220 6c 69 67 3b 27 3c 2f 62 3e 20 69 73 20 46 41 4c  lig;'</b> is FAL
18230 53 45 2e 22 3c 2f 74 63 6c 3e 0a 54 68 65 20 49  SE."</tcl>.The I
18240 43 55 20 65 78 74 65 6e 73 69 6f 6e 20 74 6f 20  CU extension to 
18250 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
18260 61 6e 20 65 6e 68 61 6e 63 65 64 20 76 65 72 73  an enhanced vers
18270 69 6f 6e 20 6f 66 20 74 68 65 0a 4c 49 4b 45 20  ion of the.LIKE 
18280 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 64 6f  operator that do
18290 65 73 20 63 61 73 65 20 66 6f 6c 64 69 6e 67 20  es case folding 
182a0 61 63 72 6f 73 73 20 61 6c 6c 20 75 6e 69 63 6f  across all unico
182b0 64 65 20 63 68 61 72 61 63 74 65 72 73 2e 3c 2f  de characters.</
182c0 70 3e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 6f  p>..<p>^If the o
182d0 70 74 69 6f 6e 61 6c 20 45 53 43 41 50 45 20 63  ptional ESCAPE c
182e0 6c 61 75 73 65 20 69 73 20 70 72 65 73 65 6e 74  lause is present
182f0 2c 20 74 68 65 6e 20 74 68 65 20 65 78 70 72 65  , then the expre
18300 73 73 69 6f 6e 0a 66 6f 6c 6c 6f 77 69 6e 67 20  ssion.following 
18310 74 68 65 20 45 53 43 41 50 45 20 6b 65 79 77 6f  the ESCAPE keywo
18320 72 64 20 6d 75 73 74 20 65 76 61 6c 75 61 74 65  rd must evaluate
18330 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
18340 73 69 73 74 69 6e 67 20 6f 66 0a 61 20 73 69 6e  sisting of.a sin
18350 67 6c 65 20 63 68 61 72 61 63 74 65 72 2e 20 5e  gle character. ^
18360 54 68 69 73 20 63 68 61 72 61 63 74 65 72 20 6d  This character m
18370 61 79 20 62 65 20 75 73 65 64 20 69 6e 20 74 68  ay be used in th
18380 65 20 4c 49 4b 45 20 70 61 74 74 65 72 6e 0a 74  e LIKE pattern.t
18390 6f 20 69 6e 63 6c 75 64 65 20 6c 69 74 65 72 61  o include litera
183a0 6c 20 70 65 72 63 65 6e 74 20 6f 72 20 75 6e 64  l percent or und
183b0 65 72 73 63 6f 72 65 20 63 68 61 72 61 63 74 65  erscore characte
183c0 72 73 2e 20 5e 54 68 65 20 65 73 63 61 70 65 0a  rs. ^The escape.
183d0 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
183e0 65 64 20 62 79 20 61 20 70 65 72 63 65 6e 74 20  ed by a percent 
183f0 73 79 6d 62 6f 6c 20 28 25 29 2c 20 75 6e 64 65  symbol (%), unde
18400 72 73 63 6f 72 65 20 28 5f 29 2c 20 6f 72 20 61  rscore (_), or a
18410 20 73 65 63 6f 6e 64 0a 69 6e 73 74 61 6e 63 65   second.instance
18420 20 6f 66 20 74 68 65 20 65 73 63 61 70 65 20 63   of the escape c
18430 68 61 72 61 63 74 65 72 20 69 74 73 65 6c 66 20  haracter itself 
18440 6d 61 74 63 68 65 73 20 61 0a 6c 69 74 65 72 61  matches a.litera
18450 6c 20 70 65 72 63 65 6e 74 20 73 79 6d 62 6f 6c  l percent symbol
18460 2c 20 75 6e 64 65 72 73 63 6f 72 65 2c 20 6f 72  , underscore, or
18470 20 61 20 73 69 6e 67 6c 65 20 65 73 63 61 70 65   a single escape
18480 20 63 68 61 72 61 63 74 65 72 2c 0a 72 65 73 70   character,.resp
18490 65 63 74 69 76 65 6c 79 2e 0a 0a 3c 70 3e 5e 54  ectively...<p>^T
184a0 68 65 20 69 6e 66 69 78 20 4c 49 4b 45 20 6f 70  he infix LIKE op
184b0 65 72 61 74 6f 72 20 69 73 20 69 6d 70 6c 65 6d  erator is implem
184c0 65 6e 74 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ented by calling
184d0 20 74 68 65 0a 61 70 70 6c 69 63 61 74 69 6f 6e   the.application
184e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
184f0 63 74 69 6f 6e 73 20 5b 6c 69 6b 65 28 3c 69 3e  ctions [like(<i>
18500 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f 69 3e 29 5d  Y</i>,<i>X</i>)]
18510 20 6f 72 0a 5b 6c 69 6b 65 28 3c 69 3e 59 3c 2f   or.[like(<i>Y</
18520 69 3e 2c 3c 69 3e 58 3c 2f 69 3e 2c 3c 69 3e 5a  i>,<i>X</i>,<i>Z
18530 3c 2f 69 3e 29 5d 3c 2f 61 3e 2e 3c 2f 70 3e 0a  </i>)]</a>.</p>.
18540 0a 3c 70 3e 5e 54 68 65 20 4c 49 4b 45 20 6f 70  .<p>^The LIKE op
18550 65 72 61 74 6f 72 20 63 61 6e 20 62 65 20 6d 61  erator can be ma
18560 64 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76  de case sensitiv
18570 65 20 75 73 69 6e 67 20 74 68 65 0a 5b 63 61 73  e using the.[cas
18580 65 5f 73 65 6e 73 69 74 69 76 65 5f 6c 69 6b 65  e_sensitive_like
18590 20 70 72 61 67 6d 61 5d 2e 3c 2f 70 3e 0a 0a 3c   pragma].</p>..<
185a0 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
185b0 67 6c 6f 62 20 47 4c 4f 42 3c 2f 74 63 6c 3e 0a  glob GLOB</tcl>.
185c0 3c 70 3e 5e 54 68 65 20 47 4c 4f 42 20 6f 70 65  <p>^The GLOB ope
185d0 72 61 74 6f 72 20 69 73 20 73 69 6d 69 6c 61 72  rator is similar
185e0 20 74 6f 20 4c 49 4b 45 20 62 75 74 20 75 73 65   to LIKE but use
185f0 73 20 74 68 65 20 55 6e 69 78 0a 66 69 6c 65 20  s the Unix.file 
18600 67 6c 6f 62 62 69 6e 67 20 73 79 6e 74 61 78 20  globbing syntax 
18610 66 6f 72 20 69 74 73 20 77 69 6c 64 63 61 72 64  for its wildcard
18620 73 2e 20 20 5e 41 6c 73 6f 2c 20 47 4c 4f 42 20  s.  ^Also, GLOB 
18630 69 73 20 63 61 73 65 0a 73 65 6e 73 69 74 69 76  is case.sensitiv
18640 65 2c 20 75 6e 6c 69 6b 65 20 4c 49 4b 45 2e 20  e, unlike LIKE. 
18650 20 5e 42 6f 74 68 20 47 4c 4f 42 20 61 6e 64 20   ^Both GLOB and 
18660 4c 49 4b 45 20 6d 61 79 20 62 65 20 70 72 65 63  LIKE may be prec
18670 65 64 65 64 20 62 79 0a 74 68 65 20 4e 4f 54 20  eded by.the NOT 
18680 6b 65 79 77 6f 72 64 20 74 6f 20 69 6e 76 65 72  keyword to inver
18690 74 20 74 68 65 20 73 65 6e 73 65 20 6f 66 20 74  t the sense of t
186a0 68 65 20 74 65 73 74 2e 20 20 5e 54 68 65 20 69  he test.  ^The i
186b0 6e 66 69 78 20 47 4c 4f 42 20 0a 6f 70 65 72 61  nfix GLOB .opera
186c0 74 6f 72 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  tor is implement
186d0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ed by calling th
186e0 65 20 66 75 6e 63 74 69 6f 6e 0a 5b 67 6c 6f 62  e function.[glob
186f0 28 3c 69 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f  (<i>Y</i>,<i>X</
18700 69 3e 29 5d 20 61 6e 64 20 63 61 6e 20 62 65 20  i>)] and can be 
18710 6d 6f 64 69 66 69 65 64 20 62 79 20 6f 76 65 72  modified by over
18720 72 69 64 69 6e 67 0a 74 68 61 74 20 66 75 6e 63  riding.that func
18730 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  tion.</p>..<tcl>
18740 68 64 5f 66 72 61 67 6d 65 6e 74 20 72 65 67 65  hd_fragment rege
18750 78 70 20 52 45 47 45 58 50 3c 2f 74 63 6c 3e 0a  xp REGEXP</tcl>.
18760 3c 70 3e 5e 54 68 65 20 52 45 47 45 58 50 20 6f  <p>^The REGEXP o
18770 70 65 72 61 74 6f 72 20 69 73 20 61 20 73 70 65  perator is a spe
18780 63 69 61 6c 20 73 79 6e 74 61 78 20 66 6f 72 20  cial syntax for 
18790 74 68 65 20 72 65 67 65 78 70 28 29 0a 75 73 65  the regexp().use
187a0 72 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 4e 6f  r function.  ^No
187b0 20 72 65 67 65 78 70 28 29 20 75 73 65 72 20 66   regexp() user f
187c0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 66 69 6e  unction is defin
187d0 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a 61 6e  ed by default.an
187e0 64 20 73 6f 20 75 73 65 20 6f 66 20 74 68 65 20  d so use of the 
187f0 52 45 47 45 58 50 20 6f 70 65 72 61 74 6f 72 20  REGEXP operator 
18800 77 69 6c 6c 20 6e 6f 72 6d 61 6c 6c 79 20 72 65  will normally re
18810 73 75 6c 74 20 69 6e 20 61 6e 0a 65 72 72 6f 72  sult in an.error
18820 20 6d 65 73 73 61 67 65 2e 20 20 5e 49 66 20 61   message.  ^If a
18830 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  n [application-d
18840 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
18850 69 6f 6e 5d 20 6e 61 6d 65 64 20 22 72 65 67 65  ion] named "rege
18860 78 70 22 0a 69 73 20 61 64 64 65 64 20 61 74 20  xp".is added at 
18870 72 75 6e 2d 74 69 6d 65 2c 20 74 68 65 6e 20 74  run-time, then t
18880 68 65 20 22 3c 69 3e 58 3c 2f 69 3e 20 52 45 47  he "<i>X</i> REG
18890 45 58 50 20 3c 69 3e 59 3c 2f 69 3e 22 20 6f 70  EXP <i>Y</i>" op
188a0 65 72 61 74 6f 72 20 77 69 6c 6c 0a 62 65 20 69  erator will.be i
188b0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
188c0 63 61 6c 6c 20 74 6f 20 22 72 65 67 65 78 70 28  call to "regexp(
188d0 3c 69 3e 59 3c 2f 69 3e 2c 3c 69 3e 58 3c 2f 69  <i>Y</i>,<i>X</i
188e0 3e 29 22 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  >)".</p>..<tcl>h
188f0 64 5f 66 72 61 67 6d 65 6e 74 20 6d 61 74 63 68  d_fragment match
18900 20 4d 41 54 43 48 3c 2f 74 63 6c 3e 0a 3c 70 3e   MATCH</tcl>.<p>
18910 5e 54 68 65 20 4d 41 54 43 48 20 6f 70 65 72 61  ^The MATCH opera
18920 74 6f 72 20 69 73 20 61 20 73 70 65 63 69 61 6c  tor is a special
18930 20 73 79 6e 74 61 78 20 66 6f 72 20 74 68 65 20   syntax for the 
18940 6d 61 74 63 68 28 29 0a 61 70 70 6c 69 63 61 74  match().applicat
18950 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
18960 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65 66 61  tion.  ^The defa
18970 75 6c 74 20 6d 61 74 63 68 28 29 20 66 75 6e 63  ult match() func
18980 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
18990 69 6f 6e 0a 72 61 69 73 65 73 20 61 6e 20 65 78  ion.raises an ex
189a0 63 65 70 74 69 6f 6e 20 61 6e 64 20 69 73 20 6e  ception and is n
189b0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 66 75 6c  ot really useful
189c0 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 2e 0a 5e   for anything..^
189d0 42 75 74 20 65 78 74 65 6e 73 69 6f 6e 73 20 63  But extensions c
189e0 61 6e 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  an override the 
189f0 6d 61 74 63 68 28 29 20 66 75 6e 63 74 69 6f 6e  match() function
18a00 20 77 69 74 68 20 6d 6f 72 65 0a 68 65 6c 70 66   with more.helpf
18a10 75 6c 20 6c 6f 67 69 63 2e 3c 2f 70 3e 0a 0a 3c  ul logic.</p>..<
18a20 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
18a30 62 65 74 77 65 65 6e 20 42 45 54 57 45 45 4e 3c  between BETWEEN<
18a40 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 42 45  /tcl>.<h3>The BE
18a50 54 57 45 45 4e 20 6f 70 65 72 61 74 6f 72 3c 2f  TWEEN operator</
18a60 68 33 3e 0a 3c 70 3e 5e 28 54 68 65 20 42 45 54  h3>.<p>^(The BET
18a70 57 45 45 4e 20 6f 70 65 72 61 74 6f 72 20 69 73  WEEN operator is
18a80 20 6c 6f 67 69 63 61 6c 6c 79 20 65 71 75 69 76   logically equiv
18a90 61 6c 65 6e 74 20 74 6f 20 61 20 70 61 69 72 20  alent to a pair 
18aa0 6f 66 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e 0a  of comparisons..
18ab0 22 3c 69 3e 78 3c 2f 69 3e 20 3c 62 3e 42 45 54  "<i>x</i> <b>BET
18ac0 57 45 45 4e 3c 2f 62 3e 20 3c 69 3e 79 3c 2f 69  WEEN</b> <i>y</i
18ad0 3e 20 3c 62 3e 41 4e 44 3c 2f 62 3e 20 3c 69 3e  > <b>AND</b> <i>
18ae0 7a 3c 2f 69 3e 22 20 69 73 20 0a 65 71 75 69 76  z</i>" is .equiv
18af0 61 6c 65 6e 74 20 74 6f 20 0a 22 3c 69 3e 78 3c  alent to ."<i>x<
18b00 2f 69 3e 3c 62 3e 26 67 74 3b 3d 3c 2f 62 3e 3c  /i><b>&gt;=</b><
18b10 69 3e 79 3c 2f 69 3e 20 3c 62 3e 41 4e 44 3c 2f  i>y</i> <b>AND</
18b20 62 3e 20 3c 69 3e 78 3c 2f 69 3e 3c 62 3e 26 6c  b> <i>x</i><b>&l
18b30 74 3b 3d 3c 2f 62 3e 3c 69 3e 7a 3c 2f 69 3e 22  t;=</b><i>z</i>"
18b40 20 65 78 63 65 70 74 0a 74 68 61 74 20 77 69 74   except.that wit
18b50 68 20 42 45 54 57 45 45 4e 2c 20 74 68 65 20 3c  h BETWEEN, the <
18b60 69 3e 78 3c 2f 69 3e 20 65 78 70 72 65 73 73 69  i>x</i> expressi
18b70 6f 6e 20 69 73 20 6f 6e 6c 79 20 65 76 61 6c 75  on is only evalu
18b80 61 74 65 64 20 6f 6e 63 65 2e 29 5e 0a 5e 54 68  ated once.)^.^Th
18b90 65 20 70 72 65 63 65 64 65 6e 63 65 20 6f 66 20  e precedence of 
18ba0 74 68 65 20 42 45 54 57 45 45 4e 20 6f 70 65 72  the BETWEEN oper
18bb0 61 74 6f 72 20 69 73 20 74 68 65 20 73 61 6d 65  ator is the same
18bc0 20 61 73 20 74 68 65 20 70 72 65 63 65 64 65 6e   as the preceden
18bd0 63 65 0a 61 73 20 6f 70 65 72 61 74 6f 72 73 20  ce.as operators 
18be0 3c 62 3e 3d 3d 3c 2f 62 3e 20 61 6e 64 20 3c 62  <b>==</b> and <b
18bf0 3e 21 3d 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e 4c  >!=</b> and <b>L
18c00 49 4b 45 3c 2f 62 3e 20 61 6e 64 20 67 72 6f 75  IKE</b> and grou
18c10 70 73 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74  ps left to right
18c20 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
18c30 65 6e 74 20 63 61 73 65 20 7b 43 41 53 45 20 65  ent case {CASE e
18c40 78 70 72 65 73 73 69 6f 6e 7d 3c 2f 74 63 6c 3e  xpression}</tcl>
18c50 0a 3c 68 33 3e 54 68 65 20 43 41 53 45 20 65 78  .<h3>The CASE ex
18c60 70 72 65 73 73 69 6f 6e 3c 2f 68 33 3e 0a 3c 70  pression</h3>.<p
18c70 3e 41 20 43 41 53 45 20 65 78 70 72 65 73 73 69  >A CASE expressi
18c80 6f 6e 20 73 65 72 76 65 73 20 61 20 72 6f 6c 65  on serves a role
18c90 20 73 69 6d 69 6c 61 72 20 74 6f 20 49 46 2d 54   similar to IF-T
18ca0 48 45 4e 2d 45 4c 53 45 20 69 6e 20 6f 74 68 65  HEN-ELSE in othe
18cb0 72 0a 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61  r.programming la
18cc0 6e 67 75 61 67 65 73 2e 20 20 0a 0a 3c 70 3e 54  nguages.  ..<p>T
18cd0 68 65 20 6f 70 74 69 6f 6e 61 6c 20 65 78 70 72  he optional expr
18ce0 65 73 73 69 6f 6e 20 74 68 61 74 20 6f 63 63 75  ession that occu
18cf0 72 73 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  rs in between th
18d00 65 20 43 41 53 45 20 6b 65 79 77 6f 72 64 20 61  e CASE keyword a
18d10 6e 64 20 74 68 65 0a 66 69 72 73 74 20 57 48 45  nd the.first WHE
18d20 4e 20 6b 65 79 77 6f 72 64 20 69 73 20 63 61 6c  N keyword is cal
18d30 6c 65 64 20 74 68 65 20 22 62 61 73 65 22 20 65  led the "base" e
18d40 78 70 72 65 73 73 69 6f 6e 2e 20 5e 54 68 65 72  xpression. ^Ther
18d50 65 20 61 72 65 20 74 77 6f 20 62 61 73 69 63 20  e are two basic 
18d60 66 6f 72 6d 73 0a 6f 66 20 74 68 65 20 43 41 53  forms.of the CAS
18d70 45 20 65 78 70 72 65 73 73 69 6f 6e 3a 20 74 68  E expression: th
18d80 6f 73 65 20 77 69 74 68 20 61 20 62 61 73 65 20  ose with a base 
18d90 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64 20 74  expression and t
18da0 68 6f 73 65 20 77 69 74 68 6f 75 74 2e 0a 0a 3c  hose without...<
18db0 70 3e 5e 49 6e 20 61 20 43 41 53 45 20 77 69 74  p>^In a CASE wit
18dc0 68 6f 75 74 20 61 20 62 61 73 65 20 65 78 70 72  hout a base expr
18dd0 65 73 73 69 6f 6e 2c 20 65 61 63 68 20 57 48 45  ession, each WHE
18de0 4e 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  N expression is 
18df0 65 76 61 6c 75 61 74 65 64 0a 61 6e 64 20 74 68  evaluated.and th
18e00 65 20 72 65 73 75 6c 74 20 74 72 65 61 74 65 64  e result treated
18e10 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 73   as a boolean, s
18e20 74 61 72 74 69 6e 67 20 77 69 74 68 20 74 68 65  tarting with the
18e30 20 6c 65 66 74 6d 6f 73 74 20 61 6e 64 20 63 6f   leftmost and co
18e40 6e 74 69 6e 75 69 6e 67 0a 74 6f 20 74 68 65 20  ntinuing.to the 
18e50 72 69 67 68 74 2e 20 5e 54 68 65 20 72 65 73 75  right. ^The resu
18e60 6c 74 20 6f 66 20 74 68 65 20 43 41 53 45 20 65  lt of the CASE e
18e70 78 70 72 65 73 73 69 6f 6e 20 69 73 20 74 68 65  xpression is the
18e80 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
18e90 68 65 20 54 48 45 4e 0a 65 78 70 72 65 73 73 69  he THEN.expressi
18ea0 6f 6e 20 74 68 61 74 20 63 6f 72 72 65 73 70 6f  on that correspo
18eb0 6e 64 73 20 74 6f 20 74 68 65 20 66 69 72 73 74  nds to the first
18ec0 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
18ed0 20 74 68 61 74 20 65 76 61 6c 75 61 74 65 73 20   that evaluates 
18ee0 74 6f 0a 74 72 75 65 2e 20 5e 4f 72 2c 20 69 66  to.true. ^Or, if
18ef0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 57 48 45   none of the WHE
18f00 4e 20 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76  N expressions ev
18f10 61 6c 75 61 74 65 20 74 6f 20 74 72 75 65 2c 20  aluate to true, 
18f20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 65 76  the result of.ev
18f30 61 6c 75 61 74 69 6e 67 20 74 68 65 20 45 4c 53  aluating the ELS
18f40 45 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 66  E expression, if
18f50 20 61 6e 79 2e 20 5e 49 66 20 74 68 65 72 65 20   any. ^If there 
18f60 69 73 20 6e 6f 20 45 4c 53 45 20 65 78 70 72 65  is no ELSE expre
18f70 73 73 69 6f 6e 20 61 6e 64 0a 6e 6f 6e 65 20 6f  ssion and.none o
18f80 66 20 74 68 65 20 57 48 45 4e 20 65 78 70 72 65  f the WHEN expre
18f90 73 73 69 6f 6e 73 20 61 72 65 20 74 72 75 65 2c  ssions are true,
18fa0 20 74 68 65 6e 20 74 68 65 20 6f 76 65 72 61 6c   then the overal
18fb0 6c 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  l result is NULL
18fc0 2e 0a 0a 3c 70 3e 5e 41 20 4e 55 4c 4c 20 72 65  ...<p>^A NULL re
18fd0 73 75 6c 74 20 69 73 20 63 6f 6e 73 69 64 65 72  sult is consider
18fe0 65 64 20 75 6e 74 72 75 65 20 77 68 65 6e 20 65  ed untrue when e
18ff0 76 61 6c 75 61 74 69 6e 67 20 57 48 45 4e 20 74  valuating WHEN t
19000 65 72 6d 73 2e 0a 0a 3c 70 3e 5e 49 6e 20 61 20  erms...<p>^In a 
19010 43 41 53 45 20 77 69 74 68 20 61 20 62 61 73 65  CASE with a base
19020 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 74 68 65   expression, the
19030 20 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e   base expression
19040 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 6a 75   is evaluated ju
19050 73 74 0a 6f 6e 63 65 20 61 6e 64 20 74 68 65 20  st.once and the 
19060 72 65 73 75 6c 74 20 69 73 20 63 6f 6d 70 61 72  result is compar
19070 65 64 20 61 67 61 69 6e 73 74 20 74 68 65 20 65  ed against the e
19080 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 65 61 63  valuation of eac
19090 68 20 57 48 45 4e 20 0a 65 78 70 72 65 73 73 69  h WHEN .expressi
190a0 6f 6e 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20  on from left to 
190b0 72 69 67 68 74 2e 20 5e 54 68 65 20 72 65 73 75  right. ^The resu
190c0 6c 74 20 6f 66 20 74 68 65 20 43 41 53 45 20 65  lt of the CASE e
190d0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 74 68 65  xpression is the
190e0 20 0a 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20   .evaluation of 
190f0 74 68 65 20 54 48 45 4e 20 65 78 70 72 65 73 73  the THEN express
19100 69 6f 6e 20 74 68 61 74 20 63 6f 72 72 65 73 70  ion that corresp
19110 6f 6e 64 73 20 74 6f 20 74 68 65 20 66 69 72 73  onds to the firs
19120 74 20 57 48 45 4e 0a 65 78 70 72 65 73 73 69 6f  t WHEN.expressio
19130 6e 20 66 6f 72 20 77 68 69 63 68 20 74 68 65 20  n for which the 
19140 63 6f 6d 70 61 72 69 73 6f 6e 20 69 73 20 74 72  comparison is tr
19150 75 65 2e 20 5e 4f 72 2c 20 69 66 20 6e 6f 6e 65  ue. ^Or, if none
19160 20 6f 66 20 74 68 65 20 57 48 45 4e 0a 65 78 70   of the WHEN.exp
19170 72 65 73 73 69 6f 6e 73 20 65 76 61 6c 75 61 74  ressions evaluat
19180 65 20 74 6f 20 61 20 76 61 6c 75 65 20 65 71 75  e to a value equ
19190 61 6c 20 74 6f 20 74 68 65 20 62 61 73 65 20 65  al to the base e
191a0 78 70 72 65 73 73 69 6f 6e 2c 20 74 68 65 20 72  xpression, the r
191b0 65 73 75 6c 74 0a 6f 66 20 65 76 61 6c 75 61 74  esult.of evaluat
191c0 69 6e 67 20 74 68 65 20 45 4c 53 45 20 65 78 70  ing the ELSE exp
191d0 72 65 73 73 69 6f 6e 2c 20 69 66 20 61 6e 79 2e  ression, if any.
191e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
191f0 20 45 4c 53 45 20 65 78 70 72 65 73 73 69 6f 6e   ELSE expression
19200 20 61 6e 64 0a 6e 6f 6e 65 20 6f 66 20 74 68 65   and.none of the
19210 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
19220 73 20 70 72 6f 64 75 63 65 20 61 20 72 65 73 75  s produce a resu
19230 6c 74 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  lt equal to the 
19240 62 61 73 65 20 65 78 70 72 65 73 73 69 6f 6e 2c  base expression,
19250 0a 74 68 65 20 6f 76 65 72 61 6c 6c 20 72 65 73  .the overall res
19260 75 6c 74 20 69 73 20 4e 55 4c 4c 2e 0a 0a 3c 70  ult is NULL...<p
19270 3e 5e 57 68 65 6e 20 63 6f 6d 70 61 72 69 6e 67  >^When comparing
19280 20 61 20 62 61 73 65 20 65 78 70 72 65 73 73 69   a base expressi
19290 6f 6e 20 61 67 61 69 6e 73 74 20 61 20 57 48 45  on against a WHE
192a0 4e 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 74 68  N expression, th
192b0 65 20 73 61 6d 65 0a 63 6f 6c 6c 61 74 69 6e 67  e same.collating
192c0 20 73 65 71 75 65 6e 63 65 2c 20 61 66 66 69 6e   sequence, affin
192d0 69 74 79 2c 20 61 6e 64 20 4e 55 4c 4c 2d 68 61  ity, and NULL-ha
192e0 6e 64 6c 69 6e 67 20 72 75 6c 65 73 20 61 70 70  ndling rules app
192f0 6c 79 20 61 73 20 69 66 20 74 68 65 0a 62 61 73  ly as if the.bas
19300 65 20 65 78 70 72 65 73 73 69 6f 6e 20 61 6e 64  e expression and
19310 20 57 48 45 4e 20 65 78 70 72 65 73 73 69 6f 6e   WHEN expression
19320 20 61 72 65 20 72 65 73 70 65 63 74 69 76 65 6c   are respectivel
19330 79 20 74 68 65 20 6c 65 66 74 2d 20 61 6e 64 0a  y the left- and.
19340 72 69 67 68 74 2d 68 61 6e 64 20 6f 70 65 72 61  right-hand opera
19350 6e 64 73 20 6f 66 20 61 6e 20 3c 62 69 67 3e 3c  nds of an <big><
19360 62 3e 3d 3c 2f 62 3e 3c 2f 62 69 67 3e 20 6f 70  b>=</b></big> op
19370 65 72 61 74 6f 72 2e 3c 2f 70 3e 20 5e 49 66 20  erator.</p> ^If 
19380 74 68 65 20 62 61 73 65 20 0a 65 78 70 72 65 73  the base .expres
19390 73 69 6f 6e 20 69 73 20 4e 55 4c 4c 20 74 68 65  sion is NULL the
193a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  n the result of 
193b0 74 68 65 20 43 41 53 45 20 69 73 20 61 6c 77 61  the CASE is alwa
193c0 79 73 20 74 68 65 20 72 65 73 75 6c 74 20 0a 6f  ys the result .o
193d0 66 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  f evaluating the
193e0 20 45 4c 53 45 20 65 78 70 72 65 73 73 69 6f 6e   ELSE expression
193f0 20 69 66 20 69 74 20 65 78 69 73 74 73 2c 20 6f   if it exists, o
19400 72 20 4e 55 4c 4c 20 69 66 20 69 74 20 64 6f 65  r NULL if it doe
19410 73 20 6e 6f 74 2e 0a 0a 3c 70 3e 5e 42 6f 74 68  s not...<p>^Both
19420 20 66 6f 72 6d 73 20 6f 66 20 74 68 65 20 43 41   forms of the CA
19430 53 45 20 65 78 70 72 65 73 73 69 6f 6e 20 75 73  SE expression us
19440 65 20 6c 61 7a 79 2c 20 6f 72 20 73 68 6f 72 74  e lazy, or short
19450 2d 63 69 72 63 75 69 74 2c 20 0a 65 76 61 6c 75  -circuit, .evalu
19460 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 5e 28 54 68 65  ation...<p>^(The
19470 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
19480 20 62 65 74 77 65 65 6e 20 74 68 65 20 66 6f 6c   between the fol
19490 6c 6f 77 69 6e 67 20 74 77 6f 20 43 41 53 45 20  lowing two CASE 
194a0 65 78 70 72 65 73 73 69 6f 6e 73 20 69 73 20 74  expressions is t
194b0 68 61 74 20 0a 74 68 65 20 3c 69 3e 78 3c 2f 69  hat .the <i>x</i
194c0 3e 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  > expression is 
194d0 65 76 61 6c 75 61 74 65 64 20 65 78 61 63 74 6c  evaluated exactl
194e0 79 20 6f 6e 63 65 20 69 6e 20 74 68 65 20 66 69  y once in the fi
194f0 72 73 74 20 65 78 61 6d 70 6c 65 20 62 75 74 20  rst example but 
19500 0a 6d 69 67 68 74 20 62 65 20 65 76 61 6c 75 61  .might be evalua
19510 74 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  ted multiple tim
19520 65 73 20 69 6e 20 74 68 65 20 73 65 63 6f 6e 64  es in the second
19530 3a 0a 0a 3c 75 6c 3e 3c 70 72 65 3e 0a 3c 6c 69  :..<ul><pre>.<li
19540 3e 43 41 53 45 20 78 20 57 48 45 4e 20 77 31 20  >CASE x WHEN w1 
19550 54 48 45 4e 20 72 31 20 57 48 45 4e 20 77 32 20  THEN r1 WHEN w2 
19560 54 48 45 4e 20 72 32 20 45 4c 53 45 20 72 33 20  THEN r2 ELSE r3 
19570 45 4e 44 0a 3c 6c 69 3e 43 41 53 45 20 57 48 45  END.<li>CASE WHE
19580 4e 20 78 3d 77 31 20 54 48 45 4e 20 72 31 20 57  N x=w1 THEN r1 W
19590 48 45 4e 20 78 3d 77 32 20 54 48 45 4e 20 72 32  HEN x=w2 THEN r2
195a0 20 45 4c 53 45 20 72 33 20 45 4e 44 0a 3c 2f 70   ELSE r3 END.</p
195b0 72 65 3e 3c 2f 75 6c 3e 29 5e 0a 0a 0a 3c 74 63  re></ul>)^...<tc
195c0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 69 6e  l>hd_fragment in
195d0 5f 6f 70 20 7b 49 4e 20 6f 70 65 72 61 74 6f 72  _op {IN operator
195e0 7d 20 7b 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74  } {NOT IN operat
195f0 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68  or}</tcl>.<h3>Th
19600 65 20 49 4e 20 61 6e 64 20 4e 4f 54 20 49 4e 20  e IN and NOT IN 
19610 6f 70 65 72 61 74 6f 72 73 3c 2f 68 33 3e 0a 3c  operators</h3>.<
19620 70 3e 5e 54 68 65 20 49 4e 20 61 6e 64 20 4e 4f  p>^The IN and NO
19630 54 20 49 4e 20 6f 70 65 72 61 74 6f 72 73 20 74  T IN operators t
19640 61 6b 65 20 61 6e 20 65 78 70 72 65 73 73 69 6f  ake an expressio
19650 6e 20 6f 6e 20 74 68 65 0a 6c 65 66 74 20 61 6e  n on the.left an
19660 64 20 61 20 6c 69 73 74 20 6f 66 20 76 61 6c 75  d a list of valu
19670 65 73 20 6f 72 20 61 20 73 75 62 71 75 65 72 79  es or a subquery
19680 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2e 0a 5e   on the right..^
19690 57 68 65 6e 20 74 68 65 20 72 69 67 68 74 20 6f  When the right o
196a0 70 65 72 61 6e 64 20 6f 66 20 61 6e 20 49 4e 20  perand of an IN 
196b0 6f 72 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74  or NOT IN operat
196c0 6f 72 20 69 73 20 61 20 73 75 62 71 75 65 72 79  or is a subquery
196d0 2c 20 74 68 65 0a 73 75 62 71 75 65 72 79 20 6d  , the.subquery m
196e0 75 73 74 20 68 61 76 65 20 74 68 65 20 73 61 6d  ust have the sam
196f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
19700 6d 6e 73 20 61 73 20 74 68 65 72 65 20 61 72 65  mns as there are
19710 20 63 6f 6c 75 6d 6e 73 20 69 6e 0a 74 68 65 20   columns in.the 
19720 5b 72 6f 77 20 76 61 6c 75 65 5d 20 6f 66 20 74  [row value] of t
19730 68 65 20 6c 65 66 74 20 6f 70 65 72 61 6e 64 2e  he left operand.
19740 20 20 5e 54 68 65 20 73 75 62 71 75 65 72 79 20    ^The subquery 
19750 6f 6e 20 74 68 65 0a 72 69 67 68 74 20 6f 66 20  on the.right of 
19760 61 6e 20 49 4e 20 6f 72 20 4e 4f 54 20 49 4e 20  an IN or NOT IN 
19770 6f 70 65 72 61 74 6f 72 20 6d 75 73 74 20 62 65  operator must be
19780 20 61 20 73 63 61 6c 61 72 20 73 75 62 71 75 65   a scalar subque
19790 72 79 20 69 66 20 74 68 65 20 6c 65 66 74 0a 65  ry if the left.e
197a0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 6e 6f 74  xpression is not
197b0 20 61 20 5b 72 6f 77 20 76 61 6c 75 65 5d 20 65   a [row value] e
197c0 78 70 72 65 73 73 69 6f 6e 2e 0a 5e 49 66 20 74  xpression..^If t
197d0 68 65 20 72 69 67 68 74 20 6f 70 65 72 61 6e 64  he right operand
197e0 20 6f 66 20 61 6e 20 49 4e 20 6f 72 20 4e 4f 54   of an IN or NOT
197f0 20 49 4e 20 6f 70 65 72 61 74 6f 72 20 69 73 20   IN operator is 
19800 61 20 6c 69 73 74 20 6f 66 20 76 61 6c 75 65 73  a list of values
19810 2c 0a 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  ,.each of those 
19820 76 61 6c 75 65 73 20 6d 75 73 74 20 62 65 20 73  values must be s
19830 63 61 6c 61 72 73 20 61 6e 64 20 74 68 65 20 6c  calars and the l
19840 65 66 74 20 65 78 70 72 65 73 73 69 6f 6e 20 6d  eft expression m
19850 75 73 74 20 61 6c 73 6f 0a 62 65 20 61 20 73 63  ust also.be a sc
19860 61 6c 61 72 2e 0a 5e 54 68 65 20 72 69 67 68 74  alar..^The right
19870 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 6e  -hand side of an
19880 20 49 4e 20 6f 72 20 4e 4f 54 20 49 4e 20 6f 70   IN or NOT IN op
19890 65 72 61 74 6f 72 20 63 61 6e 20 62 65 20 61 0a  erator can be a.
198a0 74 61 62 6c 65 20 3c 69 3e 6e 61 6d 65 3c 2f 69  table <i>name</i
198b0 3e 20 6f 72 20 5b 74 61 62 6c 65 2d 76 61 6c 75  > or [table-valu
198c0 65 64 20 66 75 6e 63 74 69 6f 6e 5d 20 3c 69 3e  ed function] <i>
198d0 6e 61 6d 65 3c 2f 69 3e 20 69 6e 20 77 68 69 63  name</i> in whic
198e0 68 20 0a 63 61 73 65 20 74 68 65 20 72 69 67 68  h .case the righ
198f0 74 2d 68 61 6e 64 20 73 69 64 65 20 69 73 20 75  t-hand side is u
19900 6e 64 65 72 73 74 6f 6f 64 20 74 6f 20 62 65 20  nderstood to be 
19910 73 75 62 71 75 65 72 79 20 6f 66 0a 74 68 65 20  subquery of.the 
19920 66 6f 72 6d 20 22 28 53 45 4c 45 43 54 20 2a 20  form "(SELECT * 
19930 46 52 4f 4d 20 3c 69 3e 6e 61 6d 65 3c 2f 69 3e  FROM <i>name</i>
19940 29 22 2e 0a 5e 57 68 65 6e 20 74 68 65 20 72 69  )"..^When the ri
19950 67 68 74 20 6f 70 65 72 61 6e 64 20 69 73 20 61  ght operand is a
19960 6e 20 65 6d 70 74 79 20 73 65 74 2c 20 74 68 65  n empty set, the
19970 20 72 65 73 75 6c 74 20 6f 66 20 49 4e 20 69 73   result of IN is
19980 20 66 61 6c 73 65 20 61 6e 64 20 74 68 65 0a 72   false and the.r
19990 65 73 75 6c 74 20 6f 66 20 4e 4f 54 20 49 4e 20  esult of NOT IN 
199a0 69 73 20 74 72 75 65 2c 20 72 65 67 61 72 64 6c  is true, regardl
199b0 65 73 73 20 6f 66 20 74 68 65 20 6c 65 66 74 20  ess of the left 
199c0 6f 70 65 72 61 6e 64 20 61 6e 64 20 65 76 65 6e  operand and even
199d0 20 69 66 20 74 68 65 0a 6c 65 66 74 20 6f 70 65   if the.left ope
199e0 72 61 6e 64 20 69 73 20 4e 55 4c 4c 2e 0a 3c 70  rand is NULL..<p
199f0 3e 5e 28 54 68 65 20 72 65 73 75 6c 74 20 6f 66  >^(The result of
19a00 20 61 6e 20 49 4e 20 6f 72 20 4e 4f 54 20 49 4e   an IN or NOT IN
19a10 20 6f 70 65 72 61 74 6f 72 20 69 73 20 64 65 74   operator is det
19a20 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 66  ermined by the f
19a30 6f 6c 6c 6f 77 69 6e 67 0a 6d 61 74 72 69 78 3a  ollowing.matrix:
19a40 0a 0a 3c 63 65 6e 74 65 72 3e 0a 3c 74 61 62 6c  ..<center>.<tabl
19a50 65 20 62 6f 72 64 65 72 3d 31 3e 0a 3c 74 72 3e  e border=1>.<tr>
19a60 0a 3c 74 68 3e 4c 65 66 74 20 6f 70 65 72 61 6e  .<th>Left operan
19a70 64 20 3c 62 72 3e 69 73 20 4e 55 4c 4c 0a 3c 74  d <br>is NULL.<t
19a80 68 3e 52 69 67 68 74 20 6f 70 65 72 61 6e 64 20  h>Right operand 
19a90 3c 62 72 3e 63 6f 6e 74 61 69 6e 73 20 4e 55 4c  <br>contains NUL
19aa0 4c 0a 3c 74 68 3e 52 69 67 68 74 20 6f 70 65 72  L.<th>Right oper
19ab0 61 6e 64 20 3c 62 72 3e 69 73 20 61 6e 20 65 6d  and <br>is an em
19ac0 70 74 79 20 73 65 74 0a 3c 74 68 3e 4c 65 66 74  pty set.<th>Left
19ad0 20 6f 70 65 72 61 6e 64 20 66 6f 75 6e 64 20 3c   operand found <
19ae0 62 72 3e 77 69 74 68 69 6e 20 72 69 67 68 74 20  br>within right 
19af0 6f 70 65 72 61 6e 64 0a 3c 74 68 3e 52 65 73 75  operand.<th>Resu
19b00 6c 74 20 6f 66 20 3c 62 72 3e 49 4e 20 6f 70 65  lt of <br>IN ope
19b10 72 61 74 6f 72 0a 3c 74 68 3e 52 65 73 75 6c 74  rator.<th>Result
19b20 20 6f 66 20 3c 62 72 3e 4e 4f 54 20 49 4e 20 6f   of <br>NOT IN o
19b30 70 65 72 61 74 6f 72 0a 3c 74 72 3e 0a 3c 74 64  perator.<tr>.<td
19b40 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
19b50 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65  no.<td align="ce
19b60 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69  nter">no.<td ali
19b70 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c  gn="center">no.<
19b80 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72  td align="center
19b90 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  ">no.<td align="
19ba0 63 65 6e 74 65 72 22 3e 66 61 6c 73 65 0a 3c 74  center">false.<t
19bb0 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22  d align="center"
19bc0 3e 74 72 75 65 0a 3c 74 72 3e 0a 3c 74 64 20 61  >true.<tr>.<td a
19bd0 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 64 6f  lign="center">do
19be0 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 0a 3c 74  es not matter.<t
19bf0 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22  d align="center"
19c00 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  >no.<td align="c
19c10 65 6e 74 65 72 22 3e 79 65 73 0a 3c 74 64 20 61  enter">yes.<td a
19c20 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f  lign="center">no
19c30 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
19c40 65 72 22 3e 66 61 6c 73 65 0a 3c 74 64 20 61 6c  er">false.<td al
19c50 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 74 72 75  ign="center">tru
19c60 65 0a 3c 74 72 3e 0a 3c 74 64 20 61 6c 69 67 6e  e.<tr>.<td align
19c70 3d 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64  ="center">no.<td
19c80 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
19c90 64 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 0a  does not matter.
19ca0 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
19cb0 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d  r">no.<td align=
19cc0 22 63 65 6e 74 65 72 22 3e 79 65 73 0a 3c 74 64  "center">yes.<td
19cd0 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e   align="center">
19ce0 74 72 75 65 0a 3c 74 64 20 61 6c 69 67 6e 3d 22  true.<td align="
19cf0 63 65 6e 74 65 72 22 3e 66 61 6c 73 65 0a 3c 74  center">false.<t
19d00 72 3e 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65  r>.<td align="ce
19d10 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69  nter">no.<td ali
19d20 67 6e 3d 22 63 65 6e 74 65 72 22 3e 79 65 73 0a  gn="center">yes.
19d30 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74 65  <td align="cente
19d40 72 22 3e 6e 6f 0a 3c 74 64 20 61 6c 69 67 6e 3d  r">no.<td align=
19d50 22 63 65 6e 74 65 72 22 3e 6e 6f 0a 3c 74 64 20  "center">no.<td 
19d60 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4e  align="center">N
19d70 55 4c 4c 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  ULL.<td align="c
19d80 65 6e 74 65 72 22 3e 4e 55 4c 4c 0a 3c 74 72 3e  enter">NULL.<tr>
19d90 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
19da0 65 72 22 3e 79 65 73 0a 3c 74 64 20 61 6c 69 67  er">yes.<td alig
19db0 6e 3d 22 63 65 6e 74 65 72 22 3e 64 6f 65 73 20  n="center">does 
19dc0 6e 6f 74 20 6d 61 74 74 65 72 0a 3c 74 64 20 61  not matter.<td a
19dd0 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 6e 6f  lign="center">no
19de0 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63 65 6e 74  .<td align="cent
19df0 65 72 22 3e 64 6f 65 73 20 6e 6f 74 20 6d 61 74  er">does not mat
19e00 74 65 72 0a 3c 74 64 20 61 6c 69 67 6e 3d 22 63  ter.<td align="c
19e10 65 6e 74 65 72 22 3e 4e 55 4c 4c 0a 3c 74 64 20  enter">NULL.<td 
19e20 61 6c 69 67 6e 3d 22 63 65 6e 74 65 72 22 3e 4e  align="center">N
19e30 55 4c 4c 0a 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 63  ULL.</table>.</c
19e40 65 6e 74 65 72 3e 29 5e 0a 0a 3c 70 3e 5e 4e 6f  enter>)^..<p>^No
19e50 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 61  te that SQLite a
19e60 6c 6c 6f 77 73 20 74 68 65 20 70 61 72 65 6e 74  llows the parent
19e70 68 65 73 69 7a 65 64 20 6c 69 73 74 20 6f 66 20  hesized list of 
19e80 73 63 61 6c 61 72 20 76 61 6c 75 65 73 20 6f 6e  scalar values on
19e90 0a 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20  .the right-hand 
19ea0 73 69 64 65 20 6f 66 20 61 6e 20 49 4e 20 6f 72  side of an IN or
19eb0 20 4e 4f 54 20 49 4e 20 6f 70 65 72 61 74 6f 72   NOT IN operator
19ec0 20 74 6f 20 62 65 20 61 6e 20 65 6d 70 74 79 20   to be an empty 
19ed0 6c 69 73 74 20 62 75 74 0a 6d 6f 73 74 20 6f 74  list but.most ot
19ee0 68 65 72 20 53 51 4c 20 64 61 74 61 62 61 73 65  her SQL database
19ef0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
19f00 73 20 61 6e 64 20 74 68 65 20 53 51 4c 39 32 20  s and the SQL92 
19f10 73 74 61 6e 64 61 72 64 20 72 65 71 75 69 72 65  standard require
19f20 0a 74 68 65 20 6c 69 73 74 20 74 6f 20 63 6f 6e  .the list to con
19f30 74 61 69 6e 20 61 74 20 6c 65 61 73 74 20 6f 6e  tain at least on
19f40 65 20 65 6c 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a  e element.</p>..
19f50 3c 68 33 3e 54 61 62 6c 65 20 43 6f 6c 75 6d 6e  <h3>Table Column
19f60 20 4e 61 6d 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e   Names</h3>..<p>
19f70 5e 41 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 63  ^A column name c
19f80 61 6e 20 62 65 20 61 6e 79 20 6f 66 20 74 68 65  an be any of the
19f90 20 6e 61 6d 65 73 20 64 65 66 69 6e 65 64 20 69   names defined i
19fa0 6e 20 74 68 65 20 5b 43 52 45 41 54 45 20 54 41  n the [CREATE TA
19fb0 42 4c 45 5d 0a 73 74 61 74 65 6d 65 6e 74 20 6f  BLE].statement o
19fc0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  r one of the fol
19fd0 6c 6f 77 69 6e 67 20 73 70 65 63 69 61 6c 20 69  lowing special i
19fe0 64 65 6e 74 69 66 69 65 72 73 3a 20 22 3c 62 3e  dentifiers: "<b>
19ff0 52 4f 57 49 44 3c 2f 62 3e 22 2c 0a 22 3c 62 3e  ROWID</b>",."<b>
1a000 4f 49 44 3c 2f 62 3e 22 2c 20 6f 72 20 22 3c 62  OID</b>", or "<b
1a010 3e 5f 52 4f 57 49 44 5f 3c 2f 62 3e 22 2e 0a 5e  >_ROWID_</b>"..^
1a020 54 68 65 20 74 68 72 65 65 20 73 70 65 63 69 61  The three specia
1a030 6c 20 69 64 65 6e 74 69 66 69 65 72 73 20 64 65  l identifiers de
1a040 73 63 72 69 62 65 20 74 68 65 0a 75 6e 69 71 75  scribe the.uniqu
1a050 65 20 69 6e 74 65 67 65 72 20 6b 65 79 20 28 74  e integer key (t
1a060 68 65 20 5b 72 6f 77 69 64 5d 29 20 61 73 73 6f  he [rowid]) asso
1a070 63 69 61 74 65 64 20 77 69 74 68 20 65 76 65 72  ciated with ever
1a080 79 20 0a 72 6f 77 20 6f 66 20 65 76 65 72 79 20  y .row of every 
1a090 74 61 62 6c 65 20 61 6e 64 20 73 6f 20 61 72 65  table and so are
1a0a0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 6f   not available o
1a0b0 6e 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  n [WITHOUT ROWID
1a0c0 5d 20 74 61 62 6c 65 73 2e 0a 5e 54 68 65 20 73  ] tables..^The s
1a0d0 70 65 63 69 61 6c 20 69 64 65 6e 74 69 66 69 65  pecial identifie
1a0e0 72 73 20 6f 6e 6c 79 20 72 65 66 65 72 20 74 6f  rs only refer to
1a0f0 20 74 68 65 20 72 6f 77 20 6b 65 79 20 69 66 20   the row key if 
1a100 74 68 65 20 5b 43 52 45 41 54 45 20 54 41 42 4c  the [CREATE TABL
1a110 45 5d 0a 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  E].statement doe
1a120 73 20 6e 6f 74 20 64 65 66 69 6e 65 20 61 20 72  s not define a r
1a130 65 61 6c 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20  eal column with 
1a140 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 5e  the same name..^
1a150 54 68 65 20 72 6f 77 69 64 20 63 61 6e 20 62 65  The rowid can be
1a160 20 75 73 65 64 20 61 6e 79 77 68 65 72 65 20 61   used anywhere a
1a170 20 72 65 67 75 6c 61 72 0a 63 6f 6c 75 6d 6e 20   regular.column 
1a180 63 61 6e 20 62 65 20 75 73 65 64 2e 3c 2f 70 3e  can be used.</p>
1a190 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
1a1a0 6e 74 20 65 78 69 73 74 73 5f 6f 70 20 7b 45 58  nt exists_op {EX
1a1b0 49 53 54 53 20 6f 70 65 72 61 74 6f 72 7d 20 7b  ISTS operator} {
1a1c0 4e 4f 54 20 45 58 49 53 54 53 20 6f 70 65 72 61  NOT EXISTS opera
1a1d0 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54  tor}</tcl>.<h3>T
1a1e0 68 65 20 45 58 49 53 54 53 20 6f 70 65 72 61 74  he EXISTS operat
1a1f0 6f 72 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 54 68 65  or</h3>..<p>^The
1a200 20 45 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72   EXISTS operator
1a210 20 61 6c 77 61 79 73 20 65 76 61 6c 75 61 74 65   always evaluate
1a220 73 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20  s to one of the 
1a230 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 30  integer values 0
1a240 20 0a 61 6e 64 20 31 2e 20 5e 49 66 20 65 78 65   .and 1. ^If exe
1a250 63 75 74 69 6e 67 20 74 68 65 20 53 45 4c 45 43  cuting the SELEC
1a260 54 20 73 74 61 74 65 6d 65 6e 74 20 73 70 65 63  T statement spec
1a270 69 66 69 65 64 20 61 73 20 74 68 65 20 72 69 67  ified as the rig
1a280 68 74 2d 68 61 6e 64 20 0a 6f 70 65 72 61 6e 64  ht-hand .operand
1a290 20 6f 66 20 74 68 65 20 45 58 49 53 54 53 20 6f   of the EXISTS o
1a2a0 70 65 72 61 74 6f 72 20 77 6f 75 6c 64 20 72 65  perator would re
1a2b0 74 75 72 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  turn one or more
1a2c0 20 72 6f 77 73 2c 20 74 68 65 6e 20 74 68 65 0a   rows, then the.
1a2d0 45 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72 20  EXISTS operator 
1a2e0 65 76 61 6c 75 61 74 65 73 20 74 6f 20 31 2e 20  evaluates to 1. 
1a2f0 5e 49 66 20 65 78 65 63 75 74 69 6e 67 20 74 68  ^If executing th
1a300 65 20 53 45 4c 45 43 54 20 77 6f 75 6c 64 20 72  e SELECT would r
1a310 65 74 75 72 6e 0a 6e 6f 20 72 6f 77 73 20 61 74  eturn.no rows at
1a320 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 45   all, then the E
1a330 58 49 53 54 53 20 6f 70 65 72 61 74 6f 72 20 65  XISTS operator e
1a340 76 61 6c 75 61 74 65 73 20 74 6f 20 30 2e 20 0a  valuates to 0. .
1a350 0a 3c 70 3e 5e 54 68 65 20 6e 75 6d 62 65 72 20  .<p>^The number 
1a360 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 65 61  of columns in ea
1a370 63 68 20 72 6f 77 20 72 65 74 75 72 6e 65 64 20  ch row returned 
1a380 62 79 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  by the SELECT st
1a390 61 74 65 6d 65 6e 74 0a 28 69 66 20 61 6e 79 29  atement.(if any)
1a3a0 20 61 6e 64 20 74 68 65 20 73 70 65 63 69 66 69   and the specifi
1a3b0 63 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  c values returne
1a3c0 64 20 68 61 76 65 20 6e 6f 20 65 66 66 65 63 74  d have no effect
1a3d0 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 73 0a   on the results.
1a3e0 6f 66 20 74 68 65 20 45 58 49 53 54 53 20 6f 70  of the EXISTS op
1a3f0 65 72 61 74 6f 72 2e 20 5e 49 6e 20 70 61 72 74  erator. ^In part
1a400 69 63 75 6c 61 72 2c 20 72 6f 77 73 20 63 6f 6e  icular, rows con
1a410 74 61 69 6e 69 6e 67 20 4e 55 4c 4c 20 76 61 6c  taining NULL val
1a420 75 65 73 20 61 72 65 0a 6e 6f 74 20 68 61 6e 64  ues are.not hand
1a430 6c 65 64 20 61 6e 79 20 64 69 66 66 65 72 65 6e  led any differen
1a440 74 6c 79 20 66 72 6f 6d 20 72 6f 77 73 20 77 69  tly from rows wi
1a450 74 68 6f 75 74 20 4e 55 4c 4c 20 76 61 6c 75 65  thout NULL value
1a460 73 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  s...<tcl>hd_frag
1a470 6d 65 6e 74 20 73 75 62 71 20 7b 53 75 62 71 75  ment subq {Subqu
1a480 65 72 69 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33  eries}</tcl>.<h3
1a490 3e 53 75 62 71 75 65 72 79 20 45 78 70 72 65 73  >Subquery Expres
1a4a0 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e  sions</h3>..<p>^
1a4b0 41 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  A [SELECT] state
1a4c0 6d 65 6e 74 20 65 6e 63 6c 6f 73 65 64 20 69 6e  ment enclosed in
1a4d0 20 70 61 72 65 6e 74 68 65 73 65 73 20 69 73 20   parentheses is 
1a4e0 61 20 73 75 62 71 75 65 72 79 2e 0a 5e 41 6c 6c  a subquery..^All
1a4f0 20 74 79 70 65 73 20 6f 66 20 53 45 4c 45 43 54   types of SELECT
1a500 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 63 6c   statement, incl
1a510 75 64 69 6e 67 0a 61 67 67 72 65 67 61 74 65 20  uding.aggregate 
1a520 61 6e 64 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  and compound SEL
1a530 45 43 54 20 71 75 65 72 69 65 73 20 28 71 75 65  ECT queries (que
1a540 72 69 65 73 20 77 69 74 68 20 6b 65 79 77 6f 72  ries with keywor
1a550 64 73 20 6c 69 6b 65 0a 55 4e 49 4f 4e 20 6f 72  ds like.UNION or
1a560 20 45 58 43 45 50 54 29 20 61 72 65 20 61 6c 6c   EXCEPT) are all
1a570 6f 77 65 64 20 61 73 20 73 63 61 6c 61 72 20 73  owed as scalar s
1a580 75 62 71 75 65 72 69 65 73 2e 0a 5e 54 68 65 20  ubqueries..^The 
1a590 76 61 6c 75 65 20 6f 66 20 61 20 73 75 62 71 75  value of a subqu
1a5a0 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ery expression i
1a5b0 73 20 74 68 65 20 66 69 72 73 74 20 72 6f 77 20  s the first row 
1a5c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 66 72  of the result.fr
1a5d0 6f 6d 20 74 68 65 20 65 6e 63 6c 6f 73 65 64 20  om the enclosed 
1a5e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1a5f0 6e 74 2e 0a 5e 54 68 65 20 76 61 6c 75 65 20 6f  nt..^The value o
1a600 66 20 61 20 73 75 62 71 75 65 72 79 20 65 78 70  f a subquery exp
1a610 72 65 73 73 69 6f 6e 20 69 73 20 4e 55 4c 4c 20  ression is NULL 
1a620 69 66 20 74 68 65 20 65 6e 63 6c 6f 73 65 64 0a  if the enclosed.
1a630 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1a640 6e 74 20 72 65 74 75 72 6e 73 20 6e 6f 20 72 6f  nt returns no ro
1a650 77 73 2e 0a 0a 3c 70 3e 41 20 73 75 62 71 75 65  ws...<p>A subque
1a660 72 79 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  ry that returns 
1a670 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
1a680 69 73 20 61 20 73 63 61 6c 61 72 20 73 75 62 71  is a scalar subq
1a690 75 65 72 79 20 61 6e 64 20 63 61 6e 0a 62 65 20  uery and can.be 
1a6a0 75 73 65 64 20 6d 6f 73 74 20 61 6e 79 77 68 65  used most anywhe
1a6b0 72 65 2e 0a 5e 41 20 73 75 62 71 75 65 72 79 20  re..^A subquery 
1a6c0 74 68 61 74 20 72 65 74 75 72 6e 73 20 74 77 6f  that returns two
1a6d0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 75 6d 6e 73   or more columns
1a6e0 20 69 73 20 61 20 5b 72 6f 77 20 76 61 6c 75 65   is a [row value
1a6f0 5d 0a 73 75 62 71 75 65 72 79 20 61 6e 64 20 63  ].subquery and c
1a700 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  an only be used 
1a710 61 73 20 74 68 65 20 6f 70 65 72 61 6e 64 20 6f  as the operand o
1a720 66 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 6f  f a comparison o
1a730 70 65 72 61 74 6f 72 2e 0a 0a 3c 74 63 6c 3e 68  perator...<tcl>h
1a740 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f 73 75 62  d_fragment cosub
1a750 20 7b 63 6f 72 72 65 6c 61 74 65 64 20 73 75 62   {correlated sub
1a760 71 75 65 72 69 65 73 7d 3c 2f 74 63 6c 3e 0a 3c  queries}</tcl>.<
1a770 68 33 3e 43 6f 72 72 65 6c 61 74 65 64 20 53 75  h3>Correlated Su
1a780 62 71 75 65 72 69 65 73 3c 2f 68 33 3e 0a 0a 3c  bqueries</h3>..<
1a790 70 3e 5e 41 20 5b 53 45 4c 45 43 54 5d 20 73 74  p>^A [SELECT] st
1a7a0 61 74 65 6d 65 6e 74 20 75 73 65 64 20 61 73 20  atement used as 
1a7b0 65 69 74 68 65 72 20 61 20 73 63 61 6c 61 72 20  either a scalar 
1a7c0 73 75 62 71 75 65 72 79 20 6f 72 20 61 73 20 74  subquery or as t
1a7d0 68 65 20 0a 72 69 67 68 74 2d 68 61 6e 64 20 6f  he .right-hand o
1a7e0 70 65 72 61 6e 64 20 6f 66 20 61 6e 20 49 4e 2c  perand of an IN,
1a7f0 20 4e 4f 54 20 49 4e 20 6f 72 20 45 58 49 53 54   NOT IN or EXIST
1a800 53 20 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 79  S expression may
1a810 20 63 6f 6e 74 61 69 6e 20 0a 72 65 66 65 72 65   contain .refere
1a820 6e 63 65 73 20 74 6f 20 63 6f 6c 75 6d 6e 73 20  nces to columns 
1a830 69 6e 20 74 68 65 20 6f 75 74 65 72 20 71 75 65  in the outer que
1a840 72 79 2e 20 53 75 63 68 20 61 20 73 75 62 71 75  ry. Such a subqu
1a850 65 72 79 20 69 73 20 6b 6e 6f 77 6e 20 61 73 0a  ery is known as.
1a860 61 20 63 6f 72 72 65 6c 61 74 65 64 20 73 75 62  a correlated sub
1a870 71 75 65 72 79 2e 20 5e 41 20 63 6f 72 72 65 6c  query. ^A correl
1a880 61 74 65 64 20 73 75 62 71 75 65 72 79 20 69 73  ated subquery is
1a890 20 72 65 65 76 61 6c 75 61 74 65 64 20 65 61 63   reevaluated eac
1a8a0 68 20 74 69 6d 65 0a 69 74 73 20 72 65 73 75 6c  h time.its resul
1a8b0 74 20 69 73 20 72 65 71 75 69 72 65 64 2e 20 5e  t is required. ^
1a8c0 41 6e 20 75 6e 63 6f 72 72 65 6c 61 74 65 64 20  An uncorrelated 
1a8d0 73 75 62 71 75 65 72 79 20 69 73 20 65 76 61 6c  subquery is eval
1a8e0 75 61 74 65 64 20 6f 6e 6c 79 20 6f 6e 63 65 0a  uated only once.
1a8f0 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 72  and the result r
1a900 65 75 73 65 64 20 61 73 20 6e 65 63 65 73 73 61  eused as necessa
1a910 72 79 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ry...<tcl>hd_fra
1a920 67 6d 65 6e 74 20 63 61 73 74 65 78 70 72 20 7b  gment castexpr {
1a930 43 41 53 54 20 65 78 70 72 65 73 73 69 6f 6e 7d  CAST expression}
1a940 20 7b 43 41 53 54 7d 20 7b 63 61 73 74 7d 20 7b   {CAST} {cast} {
1a950 43 41 53 54 20 6f 70 65 72 61 74 6f 72 7d 3c 2f  CAST operator}</
1a960 74 63 6c 3e 0a 3c 68 33 3e 43 41 53 54 20 65 78  tcl>.<h3>CAST ex
1a970 70 72 65 73 73 69 6f 6e 73 3c 2f 68 33 3e 0a 0a  pressions</h3>..
1a980 3c 70 3e 41 20 43 41 53 54 20 65 78 70 72 65 73  <p>A CAST expres
1a990 73 69 6f 6e 20 6f 66 20 74 68 65 20 66 6f 72 6d  sion of the form
1a9a0 20 22 43 41 53 54 28 3c 69 3e 65 78 70 72 3c 2f   "CAST(<i>expr</
1a9b0 69 3e 20 41 53 20 3c 69 3e 74 79 70 65 2d 6e 61  i> AS <i>type-na
1a9c0 6d 65 3c 2f 69 3e 29 22 0a 69 73 20 75 73 65 64  me</i>)".is used
1a9d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
1a9e0 76 61 6c 75 65 20 6f 66 20 3c 69 3e 65 78 70 72  value of <i>expr
1a9f0 3c 2f 69 3e 20 74 6f 20 0a 61 20 64 69 66 66 65  </i> to .a diffe
1aa00 72 65 6e 74 20 5b 73 74 6f 72 61 67 65 20 63 6c  rent [storage cl
1aa10 61 73 73 5d 20 73 70 65 63 69 66 69 65 64 20 62  ass] specified b
1aa20 79 20 3c 79 79 74 65 72 6d 3e 74 79 70 65 2d 6e  y <yyterm>type-n
1aa30 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2e 0a 5e 41  ame</yyterm>..^A
1aa40 20 43 41 53 54 20 63 6f 6e 76 65 72 73 69 6f 6e   CAST conversion
1aa50 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 74   is similar to t
1aa60 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 74 68  he conversion th
1aa70 61 74 20 74 61 6b 65 73 0a 70 6c 61 63 65 20 77  at takes.place w
1aa80 68 65 6e 20 61 20 5b 63 6f 6c 75 6d 6e 20 61 66  hen a [column af
1aa90 66 69 6e 69 74 79 5d 20 69 73 20 61 70 70 6c 69  finity] is appli
1aaa0 65 64 20 74 6f 20 61 20 76 61 6c 75 65 20 65 78  ed to a value ex
1aab0 63 65 70 74 20 74 68 61 74 20 77 69 74 68 0a 74  cept that with.t
1aac0 68 65 20 43 41 53 54 20 6f 70 65 72 61 74 6f 72  he CAST operator
1aad0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
1aae0 61 6c 77 61 79 73 20 74 61 6b 65 73 20 70 6c 61  always takes pla
1aaf0 63 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ce even if the c
1ab00 6f 6e 76 65 72 73 69 6f 6e 0a 6c 6f 73 73 79 20  onversion.lossy 
1ab10 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65  and irreversible
1ab20 2c 20 77 68 65 72 65 61 73 20 63 6f 6c 75 6d 6e  , whereas column
1ab30 20 61 66 66 69 6e 69 74 79 20 6f 6e 6c 79 20 63   affinity only c
1ab40 68 61 6e 67 65 73 20 74 68 65 20 64 61 74 61 20  hanges the data 
1ab50 74 79 70 65 0a 6f 66 20 61 20 76 61 6c 75 65 20  type.of a value 
1ab60 69 66 20 74 68 65 20 63 68 61 6e 67 65 20 69 73  if the change is
1ab70 20 6c 6f 73 73 6c 65 73 73 20 61 6e 64 20 72 65   lossless and re
1ab80 76 65 72 73 69 62 6c 65 2e 0a 0a 3c 70 3e 5e 49  versible...<p>^I
1ab90 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 3c  f the value of <
1aba0 69 3e 65 78 70 72 3c 2f 69 3e 20 69 73 20 4e 55  i>expr</i> is NU
1abb0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  LL, then the res
1abc0 75 6c 74 20 6f 66 20 74 68 65 20 43 41 53 54 0a  ult of the CAST.
1abd0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 6c  expression is al
1abe0 73 6f 20 4e 55 4c 4c 2e 20 5e 4f 74 68 65 72 77  so NULL. ^Otherw
1abf0 69 73 65 2c 20 74 68 65 20 73 74 6f 72 61 67 65  ise, the storage
1ac00 20 63 6c 61 73 73 20 6f 66 20 74 68 65 20 72 65   class of the re
1ac10 73 75 6c 74 0a 69 73 20 64 65 74 65 72 6d 69 6e  sult.is determin
1ac20 65 64 20 62 79 20 61 70 70 6c 79 69 6e 67 20 74  ed by applying t
1ac30 68 65 20 5b 72 75 6c 65 73 20 66 6f 72 20 64 65  he [rules for de
1ac40 74 65 72 6d 69 6e 69 6e 67 20 63 6f 6c 75 6d 6e  termining column
1ac50 20 61 66 66 69 6e 69 74 79 5d 20 74 6f 0a 74 68   affinity] to.th
1ac60 65 20 3c 79 79 74 65 72 6d 3e 74 79 70 65 2d 6e  e <yyterm>type-n
1ac70 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 2e 0a 0a 3c  ame</yyterm>...<
1ac80 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 3e 0a  table border=1>.
1ac90 3c 74 72 3e 0a 20 20 3c 74 68 3e 20 41 66 66 69  <tr>.  <th> Affi
1aca0 6e 69 74 79 20 6f 66 20 3c 79 79 74 65 72 6d 3e  nity of <yyterm>
1acb0 3c 6e 6f 62 72 3e 74 79 70 65 2d 6e 61 6d 65 3c  <nobr>type-name<
1acc0 2f 6e 6f 62 72 3e 3c 2f 79 79 74 65 72 6d 3e 0a  /nobr></yyterm>.
1acd0 20 20 3c 74 68 3e 20 43 6f 6e 76 65 72 73 69 6f    <th> Conversio
1ace0 6e 20 50 72 6f 63 65 73 73 69 6e 67 0a 3c 74 72  n Processing.<tr
1acf0 3e 0a 20 20 3c 74 64 3e 20 4e 4f 4e 45 20 0a 20  >.  <td> NONE . 
1ad00 20 3c 74 64 3e 20 5e 43 61 73 74 69 6e 67 20 61   <td> ^Casting a
1ad10 20 76 61 6c 75 65 20 74 6f 20 61 20 3c 79 79 74   value to a <yyt
1ad20 65 72 6d 3e 74 79 70 65 2d 6e 61 6d 65 3c 2f 79  erm>type-name</y
1ad30 79 74 65 72 6d 3e 20 77 69 74 68 20 6e 6f 20 61  yterm> with no a
1ad40 66 66 69 6e 69 74 79 20 0a 20 20 63 61 75 73 65  ffinity .  cause
1ad50 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 0a 20  s the value to. 
1ad60 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
1ad70 74 6f 20 61 20 42 4c 4f 42 2e 20 20 5e 43 61 73  to a BLOB.  ^Cas
1ad80 74 69 6e 67 20 74 6f 20 61 20 42 4c 4f 42 20 63  ting to a BLOB c
1ad90 6f 6e 73 69 73 74 73 20 6f 66 20 66 69 72 73 74  onsists of first
1ada0 20 63 61 73 74 69 6e 67 0a 20 20 74 68 65 20 76   casting.  the v
1adb0 61 6c 75 65 20 74 6f 20 54 45 58 54 20 69 6e 20  alue to TEXT in 
1adc0 74 68 65 20 5b 65 6e 63 6f 64 69 6e 67 5d 20 6f  the [encoding] o
1add0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1ade0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 6e 0a  onnection, then.
1adf0 20 20 69 6e 74 65 72 70 72 65 74 69 6e 67 20 74    interpreting t
1ae00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 62 79 74  he resulting byt
1ae10 65 20 73 65 71 75 65 6e 63 65 20 61 73 20 61 20  e sequence as a 
1ae20 42 4c 4f 42 20 69 6e 73 74 65 61 64 20 6f 66 20  BLOB instead of 
1ae30 61 73 20 54 45 58 54 2e 0a 0a 3c 74 72 3e 0a 20  as TEXT...<tr>. 
1ae40 20 3c 74 64 3e 20 54 45 58 54 0a 20 20 3c 74 64   <td> TEXT.  <td
1ae50 3e 20 5e 54 6f 20 63 61 73 74 20 61 20 42 4c 4f  > ^To cast a BLO
1ae60 42 20 76 61 6c 75 65 20 74 6f 20 54 45 58 54 2c  B value to TEXT,
1ae70 20 74 68 65 20 73 65 71 75 65 6e 63 65 20 6f 66   the sequence of
1ae80 20 62 79 74 65 73 20 74 68 61 74 20 6d 61 6b 65   bytes that make
1ae90 20 75 70 20 74 68 65 0a 20 20 42 4c 4f 42 20 69   up the.  BLOB i
1aea0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1aeb0 20 74 65 78 74 20 65 6e 63 6f 64 65 64 20 75 73   text encoded us
1aec0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1aed0 20 65 6e 63 6f 64 69 6e 67 2e 0a 20 20 3c 70 3e   encoding..  <p>
1aee0 0a 20 20 20 5e 43 61 73 74 69 6e 67 20 61 6e 20  .   ^Casting an 
1aef0 49 4e 54 45 47 45 52 20 6f 72 20 52 45 41 4c 20  INTEGER or REAL 
1af00 76 61 6c 75 65 20 69 6e 74 6f 20 54 45 58 54 20  value into TEXT 
1af10 72 65 6e 64 65 72 73 20 74 68 65 20 76 61 6c 75  renders the valu
1af20 65 20 61 73 20 69 66 20 76 69 61 20 0a 20 20 20  e as if via .   
1af30 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
1af40 74 66 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  tf()] except tha
1af50 74 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  t the resulting 
1af60 54 45 58 54 20 75 73 65 73 20 74 68 65 20 5b 65  TEXT uses the [e
1af70 6e 63 6f 64 69 6e 67 5d 20 6f 66 0a 20 20 20 20  ncoding] of.    
1af80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1af90 6e 65 63 74 69 6f 6e 2e 0a 0a 3c 74 72 3e 0a 20  nection...<tr>. 
1afa0 20 3c 74 64 3e 20 52 45 41 4c 0a 20 20 3c 74 64   <td> REAL.  <td
1afb0 3e 20 5e 57 68 65 6e 20 63 61 73 74 69 6e 67 20  > ^When casting 
1afc0 61 20 42 4c 4f 42 20 76 61 6c 75 65 20 74 6f 20  a BLOB value to 
1afd0 61 20 52 45 41 4c 2c 20 74 68 65 20 76 61 6c 75  a REAL, the valu
1afe0 65 20 69 73 20 66 69 72 73 74 20 63 6f 6e 76 65  e is first conve
1aff0 72 74 65 64 20 74 6f 0a 20 20 20 20 20 20 20 20  rted to.        
1b000 54 45 58 54 2e 0a 20 20 20 20 20 20 20 3c 70 3e  TEXT..       <p>
1b010 5e 57 68 65 6e 20 63 61 73 74 69 6e 67 20 61 20  ^When casting a 
1b020 54 45 58 54 20 76 61 6c 75 65 20 74 6f 20 52 45  TEXT value to RE
1b030 41 4c 2c 20 74 68 65 20 6c 6f 6e 67 65 73 74 20  AL, the longest 
1b040 70 6f 73 73 69 62 6c 65 20 70 72 65 66 69 78 20  possible prefix 
1b050 6f 66 0a 20 20 20 20 20 20 20 20 74 68 65 20 76  of.        the v
1b060 61 6c 75 65 20 74 68 61 74 20 63 61 6e 20 62 65  alue that can be
1b070 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1b080 61 20 72 65 61 6c 20 6e 75 6d 62 65 72 20 69 73  a real number is
1b090 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 0a   extracted from.
1b0a0 20 20 20 20 20 20 20 20 74 68 65 20 54 45 58 54          the TEXT
1b0b0 20 76 61 6c 75 65 20 61 6e 64 20 74 68 65 20 72   value and the r
1b0c0 65 6d 61 69 6e 64 65 72 20 69 67 6e 6f 72 65 64  emainder ignored
1b0d0 2e 20 5e 41 6e 79 20 6c 65 61 64 69 6e 67 20 73  . ^Any leading s
1b0e0 70 61 63 65 73 20 69 6e 20 74 68 65 0a 20 20 20  paces in the.   
1b0f0 20 20 20 20 20 54 45 58 54 20 76 61 6c 75 65 20       TEXT value 
1b100 61 72 65 20 69 67 6e 6f 72 65 64 20 77 68 65 6e  are ignored when
1b110 20 63 6f 6e 76 65 72 67 69 6e 67 20 66 72 6f 6d   converging from
1b120 20 54 45 58 54 20 74 6f 20 52 45 41 4c 2e 20 5e   TEXT to REAL. ^
1b130 28 49 66 20 74 68 65 72 65 20 69 73 0a 20 20 20  (If there is.   
1b140 20 20 20 20 20 6e 6f 20 70 72 65 66 69 78 20 74       no prefix t
1b150 68 61 74 20 63 61 6e 20 62 65 20 69 6e 74 65 72  hat can be inter
1b160 70 72 65 74 65 64 20 61 73 20 61 20 72 65 61 6c  preted as a real
1b170 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 72 65 73   number, the res
1b180 75 6c 74 20 6f 66 20 74 68 65 0a 20 20 20 20 20  ult of the.     
1b190 20 20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73     conversion is
1b1a0 20 30 2e 30 2e 29 5e 0a 0a 3c 74 72 3e 0a 20 20   0.0.)^..<tr>.  
1b1b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 0a 20 20 3c  <td> INTEGER.  <
1b1c0 74 64 3e 20 5e 57 68 65 6e 20 63 61 73 74 69 6e  td> ^When castin
1b1d0 67 20 61 20 42 4c 4f 42 20 76 61 6c 75 65 20 74  g a BLOB value t
1b1e0 6f 20 49 4e 54 45 47 45 52 2c 20 74 68 65 20 76  o INTEGER, the v
1b1f0 61 6c 75 65 20 69 73 20 66 69 72 73 74 20 63 6f  alue is first co
1b200 6e 76 65 72 74 65 64 20 74 6f 0a 20 20 20 20 20  nverted to.     
1b210 20 20 20 54 45 58 54 2e 0a 20 20 20 20 20 20 20     TEXT..       
1b220 3c 70 3e 5e 57 68 65 6e 20 63 61 73 74 69 6e 67  <p>^When casting
1b230 20 61 20 54 45 58 54 20 76 61 6c 75 65 20 74 6f   a TEXT value to
1b240 20 49 4e 54 45 47 45 52 2c 20 74 68 65 20 6c 6f   INTEGER, the lo
1b250 6e 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 70  ngest possible p
1b260 72 65 66 69 78 20 6f 66 0a 20 20 20 20 20 20 20  refix of.       
1b270 20 74 68 65 20 76 61 6c 75 65 20 74 68 61 74 20   the value that 
1b280 63 61 6e 20 62 65 20 69 6e 74 65 72 70 72 65 74  can be interpret
1b290 65 64 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  ed as an integer
1b2a0 20 6e 75 6d 62 65 72 20 69 73 20 65 78 74 72 61   number is extra
1b2b0 63 74 65 64 20 66 72 6f 6d 0a 20 20 20 20 20 20  cted from.      
1b2c0 20 20 74 68 65 20 54 45 58 54 20 76 61 6c 75 65    the TEXT value
1b2d0 20 61 6e 64 20 74 68 65 20 72 65 6d 61 69 6e 64   and the remaind
1b2e0 65 72 20 69 67 6e 6f 72 65 64 2e 20 5e 41 6e 79  er ignored. ^Any
1b2f0 20 6c 65 61 64 69 6e 67 20 73 70 61 63 65 73 20   leading spaces 
1b300 69 6e 20 74 68 65 0a 20 20 20 20 20 20 20 20 54  in the.        T
1b310 45 58 54 20 76 61 6c 75 65 20 77 68 65 6e 20 63  EXT value when c
1b320 6f 6e 76 65 72 74 69 6e 67 20 66 72 6f 6d 20 54  onverting from T
1b330 45 58 54 20 74 6f 20 49 4e 54 45 47 45 52 20 61  EXT to INTEGER a
1b340 72 65 20 69 67 6e 6f 72 65 64 2e 20 5e 49 66 20  re ignored. ^If 
1b350 74 68 65 72 65 0a 20 20 20 20 20 20 20 20 69 73  there.        is
1b360 20 6e 6f 20 70 72 65 66 69 78 20 74 68 61 74 20   no prefix that 
1b370 63 61 6e 20 62 65 20 69 6e 74 65 72 70 72 65 74  can be interpret
1b380 65 64 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  ed as an integer
1b390 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 72 65 73   number, the res
1b3a0 75 6c 74 0a 20 20 20 20 20 20 20 20 6f 66 20 74  ult.        of t
1b3b0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
1b3c0 20 30 2e 20 20 5e 49 66 20 74 68 65 20 70 72 65   0.  ^If the pre
1b3d0 66 69 78 20 69 6e 74 65 67 65 72 20 69 73 20 67  fix integer is g
1b3e0 72 65 61 74 65 72 20 74 68 61 6e 0a 20 20 20 20  reater than.    
1b3f0 20 20 20 20 2b 39 32 32 33 33 37 32 30 33 36 38      +92233720368
1b400 35 34 37 37 35 38 30 37 20 74 68 65 6e 20 74 68  54775807 then th
1b410 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
1b420 63 61 73 74 20 69 73 20 65 78 61 63 74 6c 79 0a  cast is exactly.
1b430 20 20 20 20 20 20 20 20 2b 39 32 32 33 33 37 32          +9223372
1b440 30 33 36 38 35 34 37 37 35 38 30 37 2e 20 20 5e  036854775807.  ^
1b450 53 69 6d 69 6c 61 72 6c 79 2c 20 69 66 20 74 68  Similarly, if th
1b460 65 20 70 72 65 66 69 78 20 69 6e 74 65 67 65 72  e prefix integer
1b470 20 69 73 0a 20 20 20 20 20 20 20 20 6c 65 73 73   is.        less
1b480 20 74 68 61 6e 20 2d 39 32 32 33 33 37 32 30 33   than -922337203
1b490 36 38 35 34 37 37 35 38 30 38 20 74 68 65 6e 20  6854775808 then 
1b4a0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
1b4b0 65 20 63 61 73 74 20 69 73 0a 20 20 20 20 20 20  e cast is.      
1b4c0 20 20 65 78 61 63 74 6c 79 20 2d 39 32 32 33 33    exactly -92233
1b4d0 37 32 30 33 36 38 35 34 37 37 35 38 30 38 2e 0a  72036854775808..
1b4e0 0a 20 20 20 20 20 20 20 20 3c 70 3e 5e 57 68 65  .        <p>^Whe
1b4f0 6e 20 63 61 73 74 69 6e 67 20 74 6f 20 49 4e 54  n casting to INT
1b500 45 47 45 52 2c 20 69 66 20 74 68 65 20 74 65 78  EGER, if the tex
1b510 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 66  t looks like a f
1b520 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 0a 20 20  loating point.  
1b530 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 74 68        value with
1b540 20 61 6e 20 65 78 70 6f 6e 65 6e 74 2c 20 74 68   an exponent, th
1b550 65 20 65 78 70 6f 6e 65 6e 74 20 77 69 6c 6c 20  e exponent will 
1b560 62 65 20 69 67 6e 6f 72 65 64 20 62 65 63 61 75  be ignored becau
1b570 73 65 20 69 74 20 69 73 0a 20 20 20 20 20 20 20  se it is.       
1b580 20 6e 6f 20 70 61 72 74 20 6f 66 20 74 68 65 20   no part of the 
1b590 69 6e 74 65 67 65 72 20 70 72 65 66 69 78 2e 20  integer prefix. 
1b5a0 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 20   ^For example,. 
1b5b0 20 20 20 20 20 20 20 22 28 43 41 53 54 20 27 31         "(CAST '1
1b5c0 32 33 65 2b 35 27 20 41 53 20 49 4e 54 45 47 45  23e+5' AS INTEGE
1b5d0 52 29 22 20 72 65 73 75 6c 74 73 20 69 6e 20 31  R)" results in 1
1b5e0 32 33 2c 20 6e 6f 74 20 69 6e 20 31 32 33 30 30  23, not in 12300
1b5f0 30 30 30 2e 0a 0a 20 20 20 20 20 20 20 20 3c 70  000...        <p
1b600 3e 20 5e 28 54 68 65 20 43 41 53 54 20 6f 70 65  > ^(The CAST ope
1b610 72 61 74 6f 72 20 75 6e 64 65 72 73 74 61 6e 64  rator understand
1b620 73 20 64 65 63 69 6d 61 6c 0a 20 20 20 20 20 20  s decimal.      
1b630 20 20 69 6e 74 65 67 65 72 73 20 6f 6e 6c 79 20    integers only 
1b640 26 6d 64 61 73 68 3b 20 63 6f 6e 76 65 72 73 69  &mdash; conversi
1b650 6f 6e 20 6f 66 20 5b 68 65 78 61 64 65 63 69 6d  on of [hexadecim
1b660 61 6c 20 69 6e 74 65 67 65 72 73 5d 20 73 74 6f  al integers] sto
1b670 70 73 20 0a 20 20 20 20 20 20 20 20 61 74 20 74  ps .        at t
1b680 68 65 20 22 78 22 20 69 6e 20 74 68 65 20 22 30  he "x" in the "0
1b690 78 22 20 70 72 65 66 69 78 20 6f 66 20 74 68 65  x" prefix of the
1b6a0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 69 6e 74   hexadecimal int
1b6b0 65 67 65 72 20 73 74 72 69 6e 67 20 0a 20 20 20  eger string .   
1b6c0 20 20 20 20 20 61 6e 64 20 74 68 75 73 20 72 65       and thus re
1b6d0 73 75 6c 74 20 6f 66 20 74 68 65 20 43 41 53 54  sult of the CAST
1b6e0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1b6f0 29 5e 0a 0a 20 20 20 20 20 20 3c 70 3e 5e 41 20  )^..      <p>^A 
1b700 63 61 73 74 20 6f 66 20 61 20 52 45 41 4c 20 76  cast of a REAL v
1b710 61 6c 75 65 20 69 6e 74 6f 20 61 6e 20 49 4e 54  alue into an INT
1b720 45 47 45 52 20 72 65 73 75 6c 74 73 20 69 6e 20  EGER results in 
1b730 74 68 65 20 69 6e 74 65 67 65 72 0a 20 20 20 20  the integer.    
1b740 20 20 62 65 74 77 65 65 6e 20 74 68 65 20 52 45    between the RE
1b750 41 4c 20 76 61 6c 75 65 20 61 6e 64 20 7a 65 72  AL value and zer
1b760 6f 20 74 68 61 74 20 69 73 20 63 6c 6f 73 65 73  o that is closes
1b770 74 20 74 6f 20 74 68 65 20 52 45 41 4c 20 76 61  t to the REAL va
1b780 6c 75 65 2e 0a 20 20 20 20 20 20 5e 49 66 20 61  lue..      ^If a
1b790 20 52 45 41 4c 20 69 73 20 67 72 65 61 74 65 72   REAL is greater
1b7a0 20 74 68 61 6e 20 74 68 65 20 67 72 65 61 74 65   than the greate
1b7b0 73 74 20 70 6f 73 73 69 62 6c 65 20 73 69 67 6e  st possible sign
1b7c0 65 64 0a 20 20 20 20 20 20 69 6e 74 65 67 65 72  ed.      integer
1b7d0 20 28 2b 39 32 32 33 33 37 32 30 33 36 38 35 34   (+9223372036854
1b7e0 37 37 35 38 30 37 29 20 74 68 65 6e 20 74 68 65  775807) then the
1b7f0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 67   result is the g
1b800 72 65 61 74 65 73 74 20 70 6f 73 73 69 62 6c 65  reatest possible
1b810 0a 20 20 20 20 20 20 73 69 67 6e 65 64 20 69 6e  .      signed in
1b820 74 65 67 65 72 20 61 6e 64 20 69 66 20 74 68 65  teger and if the
1b830 20 52 45 41 4c 20 69 73 20 6c 65 73 73 20 74 68   REAL is less th
1b840 61 6e 20 74 68 65 20 6c 65 61 73 74 20 70 6f 73  an the least pos
1b850 73 69 62 6c 65 20 73 69 67 6e 65 64 0a 20 20 20  sible signed.   
1b860 20 20 20 69 6e 74 65 67 65 72 20 28 2d 39 32 32     integer (-922
1b870 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
1b880 29 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  ) then the resul
1b890 74 20 69 73 20 74 68 65 20 6c 65 61 73 74 20 70  t is the least p
1b8a0 6f 73 73 69 62 6c 65 0a 20 20 20 20 20 20 73 69  ossible.      si
1b8b0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 0a 20  gned integer... 
1b8c0 20 20 20 20 20 3c 70 3e 50 72 69 6f 72 20 74 6f       <p>Prior to
1b8d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1b8e0 33 2e 38 2e 32 20 28 5b 64 61 74 65 6f 66 3a 33  3.8.2 ([dateof:3
1b8f0 2e 38 2e 32 5d 29 2c 0a 20 20 20 20 20 20 63 61  .8.2]),.      ca
1b900 73 74 69 6e 67 20 61 20 52 45 41 4c 20 76 61 6c  sting a REAL val
1b910 75 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  ue greater than.
1b920 20 20 20 20 20 20 2b 39 32 32 33 33 37 32 30 33        +922337203
1b930 36 38 35 34 37 37 35 38 30 37 2e 30 20 69 6e 74  6854775807.0 int
1b940 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  o an integer res
1b950 75 6c 74 65 64 20 69 6e 20 74 68 65 20 6d 6f 73  ulted in the mos
1b960 74 20 6e 65 67 61 74 69 76 65 0a 20 20 20 20 20  t negative.     
1b970 20 69 6e 74 65 67 65 72 2c 20 2d 39 32 32 33 33   integer, -92233
1b980 37 32 30 33 36 38 35 34 37 37 35 38 30 38 2e 20  72036854775808. 
1b990 20 54 68 69 73 20 62 65 68 61 76 69 6f 72 20 77   This behavior w
1b9a0 61 73 20 6d 65 61 6e 74 20 74 6f 20 65 6d 75 6c  as meant to emul
1b9b0 61 74 65 20 74 68 65 0a 20 20 20 20 20 20 62 65  ate the.      be
1b9c0 68 61 76 69 6f 72 20 6f 66 20 78 38 36 2f 78 36  havior of x86/x6
1b9d0 34 20 68 61 72 64 77 61 72 65 20 77 68 65 6e 20  4 hardware when 
1b9e0 64 6f 69 6e 67 20 74 68 65 20 65 71 75 69 76 61  doing the equiva
1b9f0 6c 65 6e 74 20 63 61 73 74 2e 0a 0a 3c 74 72 3e  lent cast...<tr>
1ba00 0a 20 20 3c 74 64 3e 20 4e 55 4d 45 52 49 43 0a  .  <td> NUMERIC.
1ba10 20 20 3c 74 64 3e 20 5e 43 61 73 74 69 6e 67 20    <td> ^Casting 
1ba20 61 20 54 45 58 54 20 6f 72 20 42 4c 4f 42 20 76  a TEXT or BLOB v
1ba30 61 6c 75 65 20 69 6e 74 6f 20 4e 55 4d 45 52 49  alue into NUMERI
1ba40 43 20 79 69 65 6c 64 73 20 65 69 74 68 65 72 20  C yields either 
1ba50 61 6e 20 49 4e 54 45 47 45 52 20 6f 72 0a 20 20  an INTEGER or.  
1ba60 20 61 20 52 45 41 4c 20 72 65 73 75 6c 74 2e 0a   a REAL result..
1ba70 20 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74     ^If the input
1ba80 20 74 65 78 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   text looks like
1ba90 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 68 65   an integer (the
1baa0 72 65 20 69 73 20 6e 6f 20 64 65 63 69 6d 61 6c  re is no decimal
1bab0 20 70 6f 69 6e 74 20 6e 6f 72 0a 20 20 20 65 78   point nor.   ex
1bac0 70 6f 6e 65 6e 74 29 20 61 6e 64 20 74 68 65 20  ponent) and the 
1bad0 76 61 6c 75 65 20 69 73 20 73 6d 61 6c 6c 20 65  value is small e
1bae0 6e 6f 75 67 68 20 74 6f 20 66 69 74 20 69 6e 20  nough to fit in 
1baf0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
1bb00 69 6e 74 65 67 65 72 2c 0a 20 20 20 74 68 65 6e  integer,.   then
1bb10 20 74 68 65 20 72 65 73 75 6c 74 20 77 69 6c 6c   the result will
1bb20 20 62 65 20 49 4e 54 45 47 45 52 2e 0a 20 20 20   be INTEGER..   
1bb30 5e 49 6e 70 75 74 20 74 65 78 74 20 74 68 61 74  ^Input text that
1bb40 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 66 6c 6f 61   looks like floa
1bb50 74 69 6e 67 20 70 6f 69 6e 74 20 28 74 68 65 72  ting point (ther
1bb60 65 20 69 73 20 61 20 64 65 63 69 6d 61 6c 20 70  e is a decimal p
1bb70 6f 69 6e 74 20 61 6e 64 2f 6f 72 0a 20 20 20 61  oint and/or.   a
1bb80 6e 20 65 78 70 6f 6e 65 6e 74 29 20 61 6e 64 20  n exponent) and 
1bb90 74 68 65 20 74 65 78 74 20 64 65 73 63 72 69 62  the text describ
1bba0 65 73 20 61 20 76 61 6c 75 65 20 74 68 61 74 20  es a value that 
1bbb0 0a 20 20 20 63 61 6e 20 62 65 20 6c 6f 73 73 6c  .   can be lossl
1bbc0 65 73 73 6c 79 20 63 6f 6e 76 65 72 74 65 64 20  essly converted 
1bbd0 62 61 63 6b 20 61 6e 64 20 66 6f 72 74 68 20 62  back and forth b
1bbe0 65 74 77 65 65 6e 20 49 45 45 45 20 37 35 34 20  etween IEEE 754 
1bbf0 36 34 2d 62 69 74 20 66 6c 6f 61 74 20 61 6e 64  64-bit float and
1bc00 20 61 0a 20 20 20 35 31 2d 62 69 74 20 73 69 67   a.   51-bit sig
1bc10 6e 65 64 20 69 6e 74 65 67 65 72 2c 20 74 68 65  ned integer, the
1bc20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  n the result is 
1bc30 49 4e 54 45 47 45 52 2e 0a 20 20 20 28 49 6e 20  INTEGER..   (In 
1bc40 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1bc50 74 65 6e 63 65 2c 20 61 20 35 31 2d 62 69 74 20  tence, a 51-bit 
1bc60 69 6e 74 65 67 65 72 20 69 73 20 73 70 65 63 69  integer is speci
1bc70 66 69 65 64 20 73 69 6e 63 65 20 74 68 61 74 20  fied since that 
1bc80 69 73 20 6f 6e 65 0a 20 20 20 62 69 74 20 6c 65  is one.   bit le
1bc90 73 73 20 74 68 61 6e 20 74 68 65 20 6c 65 6e 67  ss than the leng
1bca0 74 68 20 6f 66 20 74 68 65 20 6d 61 6e 74 69 73  th of the mantis
1bcb0 73 61 20 6f 66 20 61 6e 20 49 45 45 45 20 37 35  sa of an IEEE 75
1bcc0 34 20 36 34 2d 62 69 74 20 66 6c 6f 61 74 20 61  4 64-bit float a
1bcd0 6e 64 0a 20 20 20 74 68 75 73 20 70 72 6f 76 69  nd.   thus provi
1bce0 64 65 73 20 61 20 31 2d 62 69 74 20 6f 66 20 6d  des a 1-bit of m
1bcf0 61 72 67 69 6e 20 66 6f 72 20 74 68 65 20 74 65  argin for the te
1bd00 78 74 2d 74 6f 2d 66 6c 6f 61 74 20 63 6f 6e 76  xt-to-float conv
1bd10 65 72 73 69 6f 6e 20 6f 70 65 72 61 74 69 6f 6e  ersion operation
1bd20 2e 29 0a 20 20 20 5e 41 6e 79 20 74 65 78 74 20  .).   ^Any text 
1bd30 69 6e 70 75 74 20 74 68 61 74 20 64 65 73 63 72  input that descr
1bd40 69 62 65 73 20 61 20 76 61 6c 75 65 20 6f 75 74  ibes a value out
1bd50 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 20 6f  side the range o
1bd60 66 20 61 20 36 34 2d 62 69 74 0a 20 20 20 73 69  f a 64-bit.   si
1bd70 67 6e 65 64 20 69 6e 74 65 67 65 72 20 79 69 65  gned integer yie
1bd80 6c 64 73 20 61 20 52 45 41 4c 20 72 65 73 75 6c  lds a REAL resul
1bd90 74 2e 0a 20 20 20 3c 70 3e 20 5e 43 61 73 74 69  t..   <p> ^Casti
1bda0 6e 67 20 61 20 52 45 41 4c 20 6f 72 20 49 4e 54  ng a REAL or INT
1bdb0 45 47 45 52 20 76 61 6c 75 65 20 74 6f 20 4e 55  EGER value to NU
1bdc0 4d 45 52 49 43 20 69 73 20 61 20 6e 6f 2d 6f 70  MERIC is a no-op
1bdd0 2c 20 65 76 65 6e 20 69 66 20 61 20 72 65 61 6c  , even if a real
1bde0 0a 20 20 20 76 61 6c 75 65 20 63 6f 75 6c 64 20  .   value could 
1bdf0 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 20 63 6f  be losslessly co
1be00 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20 69 6e  nverted to an in
1be10 74 65 67 65 72 2e 0a 0a 3c 2f 74 72 3e 0a 0a 3c  teger...</tr>..<
1be20 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 5e 4e 6f 74  /table>..<p>^Not
1be30 65 20 74 68 61 74 20 74 68 65 20 72 65 73 75 6c  e that the resul
1be40 74 20 66 72 6f 6d 20 63 61 73 74 69 6e 67 20 61  t from casting a
1be50 6e 79 20 6e 6f 6e 2d 42 4c 4f 42 20 76 61 6c 75  ny non-BLOB valu
1be60 65 20 69 6e 74 6f 20 61 20 0a 42 4c 4f 42 20 61  e into a .BLOB a
1be70 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  nd the result fr
1be80 6f 6d 20 63 61 73 74 69 6e 67 20 61 6e 79 20 42  om casting any B
1be90 4c 4f 42 20 76 61 6c 75 65 20 69 6e 74 6f 20 61  LOB value into a
1bea0 20 6e 6f 6e 2d 42 4c 4f 42 20 76 61 6c 75 65 0a   non-BLOB value.
1beb0 6d 61 79 20 62 65 20 64 69 66 66 65 72 65 6e 74  may be different
1bec0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1bed0 65 74 68 65 72 20 74 68 65 20 64 61 74 61 62 61  ether the databa
1bee0 73 65 20 5b 65 6e 63 6f 64 69 6e 67 5d 20 69 73  se [encoding] is
1bef0 20 55 54 46 2d 38 2c 0a 55 54 46 2d 31 36 62 65   UTF-8,.UTF-16be
1bf00 2c 20 6f 72 20 55 54 46 2d 31 36 6c 65 2e 0a 0a  , or UTF-16le...
1bf10 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
1bf20 74 20 62 6f 6f 6c 65 61 6e 65 78 70 72 20 7b 62  t booleanexpr {b
1bf30 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f  oolean expressio
1bf40 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 42 6f 6f  n}</tcl>.<h3>Boo
1bf50 6c 65 61 6e 20 45 78 70 72 65 73 73 69 6f 6e 73  lean Expressions
1bf60 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 53 51  </h3>..<p>The SQ
1bf70 4c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74 75  L language featu
1bf80 72 65 73 20 73 65 76 65 72 61 6c 20 63 6f 6e 74  res several cont
1bf90 65 78 74 73 20 77 68 65 72 65 20 61 6e 20 65 78  exts where an ex
1bfa0 70 72 65 73 73 69 6f 6e 20 69 73 20 0a 65 76 61  pression is .eva
1bfb0 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 72  luated and the r
1bfc0 65 73 75 6c 74 20 63 6f 6e 76 65 72 74 65 64 20  esult converted 
1bfd0 74 6f 20 61 20 62 6f 6f 6c 65 61 6e 20 28 74 72  to a boolean (tr
1bfe0 75 65 20 6f 72 20 66 61 6c 73 65 29 20 76 61 6c  ue or false) val
1bff0 75 65 2e 20 54 68 65 73 65 0a 63 6f 6e 74 65 78  ue. These.contex
1c000 74 73 20 61 72 65 3a 0a 0a 20 20 3c 75 6c 3e 0a  ts are:..  <ul>.
1c010 20 20 20 20 3c 6c 69 3e 20 74 68 65 20 57 48 45      <li> the WHE
1c020 52 45 20 63 6c 61 75 73 65 20 6f 66 20 61 20 53  RE clause of a S
1c030 45 4c 45 43 54 2c 20 55 50 44 41 54 45 20 6f 72  ELECT, UPDATE or
1c040 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1c050 74 2c 0a 20 20 20 20 3c 6c 69 3e 20 74 68 65 20  t,.    <li> the 
1c060 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c 61 75  ON or USING clau
1c070 73 65 20 6f 66 20 61 20 6a 6f 69 6e 20 69 6e 20  se of a join in 
1c080 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
1c090 6e 74 2c 0a 20 20 20 20 3c 6c 69 3e 20 74 68 65  nt,.    <li> the
1c0a0 20 48 41 56 49 4e 47 20 63 6c 61 75 73 65 20 6f   HAVING clause o
1c0b0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
1c0c0 6d 65 6e 74 2c 0a 20 20 20 20 3c 6c 69 3e 20 74  ment,.    <li> t
1c0d0 68 65 20 57 48 45 4e 20 63 6c 61 75 73 65 20 6f  he WHEN clause o
1c0e0 66 20 61 6e 20 53 51 4c 20 74 72 69 67 67 65 72  f an SQL trigger
1c0f0 2c 20 61 6e 64 0a 20 20 20 20 3c 6c 69 3e 20 74  , and.    <li> t
1c100 68 65 20 57 48 45 4e 20 63 6c 61 75 73 65 20 6f  he WHEN clause o
1c110 72 20 63 6c 61 75 73 65 73 20 6f 66 20 73 6f 6d  r clauses of som
1c120 65 20 43 41 53 45 20 65 78 70 72 65 73 73 69 6f  e CASE expressio
1c130 6e 73 2e 0a 20 20 3c 2f 75 6c 3e 0a 0a 3c 70 3e  ns..  </ul>..<p>
1c140 5e 28 54 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  ^(To convert the
1c150 20 72 65 73 75 6c 74 73 20 6f 66 20 61 6e 20 53   results of an S
1c160 51 4c 20 65 78 70 72 65 73 73 69 6f 6e 20 74 6f  QL expression to
1c170 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
1c180 2c 20 53 51 4c 69 74 65 0a 66 69 72 73 74 20 63  , SQLite.first c
1c190 61 73 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  asts the result 
1c1a0 74 6f 20 61 20 4e 55 4d 45 52 49 43 20 76 61 6c  to a NUMERIC val
1c1b0 75 65 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77  ue in the same w
1c1c0 61 79 20 61 73 20 61 20 0a 5b 43 41 53 54 20 65  ay as a .[CAST e
1c1d0 78 70 72 65 73 73 69 6f 6e 5d 2e 20 41 20 6e 75  xpression]. A nu
1c1e0 6d 65 72 69 63 20 7a 65 72 6f 20 76 61 6c 75 65  meric zero value
1c1f0 20 28 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20   (integer value 
1c200 30 20 6f 72 20 72 65 61 6c 20 0a 76 61 6c 75 65  0 or real .value
1c210 20 30 2e 30 29 20 69 73 20 63 6f 6e 73 69 64 65   0.0) is conside
1c220 72 65 64 20 74 6f 20 62 65 20 66 61 6c 73 65 2e  red to be false.
1c230 20 20 41 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69    A NULL value i
1c240 73 20 73 74 69 6c 6c 20 4e 55 4c 4c 2e 0a 41 6c  s still NULL..Al
1c250 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1c260 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74 72  re considered tr
1c270 75 65 2e 29 5e 0a 0a 3c 70 3e 5e 28 46 6f 72 20  ue.)^..<p>^(For 
1c280 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 76 61 6c  example, the val
1c290 75 65 73 20 4e 55 4c 4c 2c 20 30 2e 30 2c 20 30  ues NULL, 0.0, 0
1c2a0 2c 20 27 65 6e 67 6c 69 73 68 27 20 61 6e 64 20  , 'english' and 
1c2b0 27 30 27 20 61 72 65 20 61 6c 6c 20 63 6f 6e 73  '0' are all cons
1c2c0 69 64 65 72 65 64 0a 74 6f 20 62 65 20 66 61 6c  idered.to be fal
1c2d0 73 65 2e 29 5e 20 5e 28 56 61 6c 75 65 73 20 31  se.)^ ^(Values 1
1c2e0 2c 20 31 2e 30 2c 20 30 2e 31 2c 20 2d 30 2e 31  , 1.0, 0.1, -0.1
1c2f0 20 61 6e 64 20 27 31 65 6e 67 6c 69 73 68 27 20   and '1english' 
1c300 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74  are considered t
1c310 6f 20 0a 62 65 20 74 72 75 65 2e 29 5e 0a 0a 3c  o .be true.)^..<
1c320 70 3e 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  p>Beginning with
1c330 20 53 51 4c 69 74 65 20 33 2e 32 33 2e 30 20 28   SQLite 3.23.0 (
1c340 5b 64 61 74 65 6f 66 3a 33 2e 32 33 2e 30 5d 29  [dateof:3.23.0])
1c350 2c 20 53 51 4c 69 74 65 20 72 65 63 6f 67 6e 69  , SQLite recogni
1c360 7a 65 73 20 74 68 65 0a 69 64 65 6e 74 69 66 69  zes the.identifi
1c370 65 72 73 20 22 54 52 55 45 22 20 61 6e 64 20 22  ers "TRUE" and "
1c380 46 41 4c 53 45 22 20 61 73 20 62 6f 6f 6c 65 61  FALSE" as boolea
1c390 6e 20 6c 69 74 65 72 61 6c 73 2c 20 69 66 20 61  n literals, if a
1c3a0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 6f 73 65  nd only if those
1c3b0 0a 69 64 65 6e 74 69 66 69 65 72 73 20 61 72 65  .identifiers are
1c3c0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 75 73 65   not already use
1c3d0 64 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72  d for some other
1c3e0 20 6d 65 61 6e 69 6e 67 2e 20 20 49 66 20 74 68   meaning.  If th
1c3f0 65 72 65 20 61 6c 72 65 61 64 79 0a 65 78 69 73  ere already.exis
1c400 74 73 20 63 6f 6c 75 6d 6e 73 20 6f 72 20 74 61  ts columns or ta
1c410 62 6c 65 73 20 6f 72 20 6f 74 68 65 72 20 6f 62  bles or other ob
1c420 6a 65 63 74 73 20 6e 61 6d 65 64 20 54 52 55 45  jects named TRUE
1c430 20 6f 72 20 46 41 4c 53 45 2c 20 74 68 65 6e 20   or FALSE, then 
1c440 66 6f 72 0a 74 68 65 20 73 61 6b 65 20 6f 66 20  for.the sake of 
1c450 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c460 69 62 69 6c 69 74 79 2c 20 74 68 65 20 54 52 55  ibility, the TRU
1c470 45 20 61 6e 64 20 46 41 4c 53 45 20 69 64 65 6e  E and FALSE iden
1c480 74 69 66 69 65 72 73 20 72 65 66 65 72 0a 74 6f  tifiers refer.to
1c490 20 74 68 6f 73 65 20 6f 74 68 65 72 20 6f 62 6a   those other obj
1c4a0 65 63 74 73 2c 20 6e 6f 74 20 74 6f 20 74 68 65  ects, not to the
1c4b0 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 73 2e   boolean values.
1c4c0 0a 0a 3c 70 3e 54 68 65 20 62 6f 6f 6c 65 61 6e  ..<p>The boolean
1c4d0 20 69 64 65 6e 74 69 66 69 65 72 73 20 54 52 55   identifiers TRU
1c4e0 45 20 61 6e 64 20 46 41 4c 53 45 20 61 72 65 20  E and FALSE are 
1c4f0 75 73 75 61 6c 6c 79 20 6a 75 73 74 20 61 6c 69  usually just ali
1c500 61 73 65 73 20 66 6f 72 0a 74 68 65 20 69 6e 74  ases for.the int
1c510 65 67 65 72 20 76 61 6c 75 65 73 20 31 20 61 6e  eger values 1 an
1c520 64 20 30 2c 20 72 65 73 70 65 63 74 69 76 65 6c  d 0, respectivel
1c530 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20  y.  However, if 
1c540 54 52 55 45 20 6f 72 20 46 41 4c 53 45 0a 6f 63  TRUE or FALSE.oc
1c550 63 75 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  cur on the right
1c560 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 6e  -hand side of an
1c570 20 49 53 20 6f 70 65 72 61 74 6f 72 2c 20 74 68   IS operator, th
1c580 65 6e 20 74 68 65 79 20 66 6f 72 6d 20 6e 65 77  en they form new
1c590 0a 75 6e 61 72 79 20 70 6f 73 74 66 69 78 20 6f  .unary postfix o
1c5a0 70 65 72 61 74 6f 72 73 20 22 49 53 20 54 52 55  perators "IS TRU
1c5b0 45 22 20 61 6e 64 20 22 49 53 20 46 41 4c 53 45  E" and "IS FALSE
1c5c0 22 20 77 68 69 63 68 20 74 65 73 74 20 74 68 65  " which test the
1c5d0 20 62 6f 6f 6c 65 61 6e 0a 76 61 6c 75 65 20 6f   boolean.value o
1c5e0 66 20 74 68 65 20 6f 70 65 72 61 6e 64 20 6f 6e  f the operand on
1c5f0 20 74 68 65 20 6c 65 66 74 2e 0a 0a 3c 68 33 3e   the left...<h3>
1c600 46 75 6e 63 74 69 6f 6e 73 3c 2f 68 33 3e 0a 3c  Functions</h3>.<
1c610 70 3e 53 51 4c 69 74 65 20 73 75 70 70 6f 72 74  p>SQLite support
1c620 73 20 6d 61 6e 79 20 5b 63 6f 72 65 66 75 6e 63  s many [corefunc
1c630 7c 73 69 6d 70 6c 65 5d 2c 20 5b 61 67 67 66 75  |simple], [aggfu
1c640 6e 63 7c 61 67 67 72 65 67 61 74 65 5d 2c 0a 61  nc|aggregate],.a
1c650 6e 64 20 5b 77 69 6e 64 6f 77 20 66 75 6e 63 74  nd [window funct
1c660 69 6f 6e 73 7c 77 69 6e 64 6f 77 5d 0a 53 51 4c  ions|window].SQL
1c670 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 46 6f 72   functions.  For
1c680 20 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 70 75   presentation pu
1c690 72 70 6f 73 65 73 2c 20 73 69 6d 70 6c 65 20 66  rposes, simple f
1c6a0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 66 75 72  unctions are fur
1c6b0 74 68 65 72 0a 73 75 62 64 69 76 69 64 65 64 20  ther.subdivided 
1c6c0 69 6e 74 6f 20 5b 63 6f 72 65 66 75 6e 63 20 7c  into [corefunc |
1c6d0 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73 5d   core functions]
1c6e0 2c 20 5b 64 61 74 65 66 75 6e 63 7c 64 61 74 65  , [datefunc|date
1c6f0 2d 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 5d  -time functions]
1c700 2c 0a 61 6e 64 20 5b 6a 73 6f 6e 31 7c 4a 53 4f  ,.and [json1|JSO
1c710 4e 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 41 70  N functions]..Ap
1c720 70 6c 69 63 61 74 69 6f 6e 73 20 63 61 6e 20 61  plications can a
1c730 64 64 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 73  dd new functions
1c740 2c 20 77 72 69 74 74 65 6e 20 69 6e 20 43 2f 43  , written in C/C
1c750 2b 2b 2c 20 75 73 69 6e 67 20 74 68 65 0a 5b 73  ++, using the.[s
1c760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1c770 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  nction()] interf
1c780 61 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54  ace..</p>..<p>.T
1c790 68 65 20 6d 61 69 6e 20 65 78 70 72 65 73 73 69  he main expressi
1c7a0 6f 6e 20 62 75 62 62 6c 65 20 64 69 61 67 72 61  on bubble diagra
1c7b0 6d 20 61 62 6f 76 65 20 73 68 6f 77 73 20 61 20  m above shows a 
1c7c0 73 69 6e 67 6c 65 20 73 79 6e 74 61 78 20 66 6f  single syntax fo
1c7d0 72 0a 61 6c 6c 20 66 75 6e 63 74 69 6f 6e 20 69  r.all function i
1c7e0 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 42 75 74  nvocations.  But
1c7f0 20 74 68 69 73 20 69 73 20 6d 65 72 65 6c 79 20   this is merely 
1c800 74 6f 20 73 69 6d 70 6c 69 66 79 20 74 68 65 20  to simplify the 
1c810 65 78 70 72 65 73 73 69 6f 6e 0a 62 75 62 62 6c  expression.bubbl
1c820 65 20 64 69 61 67 72 61 6d 2e 20 20 49 6e 20 72  e diagram.  In r
1c830 65 61 6c 69 74 79 2c 20 65 61 63 68 20 74 79 70  eality, each typ
1c840 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 68 61  e of function ha
1c850 73 20 61 20 73 6c 69 67 68 74 6c 79 20 64 69 66  s a slightly dif
1c860 66 65 72 65 6e 74 0a 73 79 6e 74 61 78 2c 20 73  ferent.syntax, s
1c870 68 6f 77 6e 20 62 65 6c 6f 77 2e 20 20 54 68 65  hown below.  The
1c880 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 63 61   function invoca
1c890 74 69 6f 6e 20 73 79 6e 74 61 78 20 73 68 6f 77  tion syntax show
1c8a0 6e 20 69 6e 20 74 68 65 20 6d 61 69 6e 0a 65 78  n in the main.ex
1c8b0 70 72 65 73 73 69 6f 6e 20 62 75 62 62 6c 65 20  pression bubble 
1c8c0 64 69 61 67 72 61 6d 20 69 73 20 74 68 65 20 75  diagram is the u
1c8d0 6e 69 6f 6e 20 6f 66 20 74 68 65 20 74 68 72 65  nion of the thre
1c8e0 65 20 73 79 6e 74 61 78 65 73 20 73 68 6f 77 6e  e syntaxes shown
1c8f0 20 68 65 72 65 3a 0a 0a 3c 74 63 6c 3e 0a 42 75   here:..<tcl>.Bu
1c900 62 62 6c 65 44 69 61 67 72 61 6d 20 73 69 6d 70  bbleDiagram simp
1c910 6c 65 2d 66 75 6e 63 74 69 6f 6e 2d 69 6e 76 6f  le-function-invo
1c920 63 61 74 69 6f 6e 0a 42 75 62 62 6c 65 44 69 61  cation.BubbleDia
1c930 67 72 61 6d 20 61 67 67 72 65 67 61 74 65 2d 66  gram aggregate-f
1c940 75 6e 63 74 69 6f 6e 2d 69 6e 76 6f 63 61 74 69  unction-invocati
1c950 6f 6e 0a 42 75 62 62 6c 65 44 69 61 67 72 61 6d  on.BubbleDiagram
1c960 20 77 69 6e 64 6f 77 2d 66 75 6e 63 74 69 6f 6e   window-function
1c970 2d 69 6e 76 6f 63 61 74 69 6f 6e 0a 3c 2f 74 63  -invocation.</tc
1c980 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20 4f 56 45 52  l>..<p>.The OVER
1c990 20 63 6c 61 75 73 65 20 69 73 20 72 65 71 75 69   clause is requi
1c9a0 72 65 64 20 66 6f 72 20 5b 77 69 6e 64 6f 77 20  red for [window 
1c9b0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 6e 64 20 69  functions] and i
1c9c0 73 20 70 72 6f 68 69 62 69 74 65 64 0a 6f 74 68  s prohibited.oth
1c9d0 65 72 77 69 73 65 2e 20 20 54 68 65 20 44 49 53  erwise.  The DIS
1c9e0 54 49 4e 43 54 20 6b 65 79 77 6f 72 64 20 69 73  TINCT keyword is
1c9f0 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 69 6e   only allowed in
1ca00 20 5b 61 67 67 66 75 6e 63 7c 61 67 67 72 65 67   [aggfunc|aggreg
1ca10 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ate functions]..
1ca20 54 68 65 20 46 49 4c 54 45 52 20 63 6c 61 75 73  The FILTER claus
1ca30 65 20 6d 61 79 20 6e 6f 74 20 61 70 70 65 61 72  e may not appear
1ca40 20 6f 6e 20 61 20 5b 63 6f 72 65 66 75 6e 63 7c   on a [corefunc|
1ca50 73 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f 6e 5d  simple function]
1ca60 2e 0a 0a 3c 70 3e 5e 49 74 20 69 73 20 70 6f 73  ...<p>^It is pos
1ca70 73 69 62 6c 65 20 74 6f 20 68 61 76 65 20 61 6e  sible to have an
1ca80 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
1ca90 69 6f 6e 20 77 69 74 68 20 74 68 65 20 73 61 6d  ion with the sam
1caa0 65 20 6e 61 6d 65 20 61 73 20 61 0a 73 69 6d 70  e name as a.simp
1cab0 6c 65 20 66 75 6e 63 74 69 6f 6e 2c 20 61 73 20  le function, as 
1cac0 6c 6f 6e 67 20 61 73 20 74 68 65 20 6e 75 6d 62  long as the numb
1cad0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1cae0 66 6f 72 20 74 68 65 20 74 77 6f 20 66 6f 72 6d  for the two form
1caf0 73 20 6f 66 20 74 68 65 0a 66 75 6e 63 74 69 6f  s of the.functio
1cb00 6e 20 61 72 65 20 64 69 66 66 65 72 65 6e 74 2e  n are different.
1cb10 20 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20    ^For example, 
1cb20 74 68 65 20 5b 61 67 67 5f 6d 61 78 7c 6d 61 78  the [agg_max|max
1cb30 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ()] function wit
1cb40 68 20 61 0a 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a.single argum
1cb50 65 6e 74 20 69 73 20 61 6e 20 61 67 67 72 65 67  ent is an aggreg
1cb60 61 74 65 20 61 6e 64 20 74 68 65 20 5b 6d 61 78  ate and the [max
1cb70 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ()] function wit
1cb80 68 20 74 77 6f 20 6f 72 20 6d 6f 72 65 0a 61 72  h two or more.ar
1cb90 67 75 6d 65 6e 74 73 20 69 73 20 61 20 73 69 6d  guments is a sim
1cba0 70 6c 65 20 66 75 6e 63 74 69 6f 6e 2e 20 20 41  ple function.  A
1cbb0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
1cbc0 6e 73 20 63 61 6e 20 75 73 75 61 6c 6c 79 20 61  ns can usually a
1cbd0 6c 73 6f 0a 62 65 20 75 73 65 64 20 61 73 20 77  lso.be used as w
1cbe0 69 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73 2e  indow functions.
1cbf0 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
1cc00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cc10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cc20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cc30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
1cc40 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20 7b  ######.Section {
1cc50 43 6f 72 65 20 46 75 6e 63 74 69 6f 6e 73 7d 20  Core Functions} 
1cc60 63 6f 72 65 66 75 6e 63 20 7b 2a 63 6f 72 65 66  corefunc {*coref
1cc70 75 6e 63 7d 0a 75 6e 73 65 74 20 2d 6e 6f 63 6f  unc}.unset -noco
1cc80 6d 70 6c 61 69 6e 20 63 6f 72 65 66 75 6e 63 73  mplain corefuncs
1cc90 65 74 0a 70 72 6f 63 20 66 75 6e 63 64 65 66 20  et.proc funcdef 
1cca0 7b 73 79 6e 74 61 78 20 6b 65 79 77 6f 72 64 73  {syntax keywords
1ccb0 20 64 65 73 63 7d 20 7b 0a 20 20 67 6c 6f 62 61   desc} {.  globa
1ccc0 6c 20 63 6f 72 65 66 75 6e 63 73 65 74 0a 20 20  l corefuncset.  
1ccd0 72 65 67 65 78 70 20 7b 5e 5b 61 2d 7a 5f 5d 2b  regexp {^[a-z_]+
1cce0 7d 20 24 73 79 6e 74 61 78 20 62 61 73 65 73 79  } $syntax basesy
1ccf0 6e 74 61 78 0a 20 20 73 65 74 20 63 6f 72 65 66  ntax.  set coref
1cd00 75 6e 63 73 65 74 28 24 62 61 73 65 73 79 6e 74  uncset($basesynt
1cd10 61 78 29 20 5b 6c 69 73 74 20 24 73 79 6e 74 61  ax) [list $synta
1cd20 78 20 24 6b 65 79 77 6f 72 64 73 20 24 64 65 73  x $keywords $des
1cd30 63 5d 0a 7d 0a 66 75 6e 63 64 65 66 20 7b 61 62  c].}.funcdef {ab
1cd40 73 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  s(X)} {} {.  ^Th
1cd50 65 20 61 62 73 28 58 29 20 66 75 6e 63 74 69 6f  e abs(X) functio
1cd60 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 62  n returns the ab
1cd70 73 6f 6c 75 74 65 20 76 61 6c 75 65 20 6f 66 20  solute value of 
1cd80 74 68 65 20 6e 75 6d 65 72 69 63 0a 20 20 61 72  the numeric.  ar
1cd90 67 75 6d 65 6e 74 20 58 2e 20 20 5e 41 62 73 28  gument X.  ^Abs(
1cda0 58 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  X) returns NULL 
1cdb0 69 66 20 58 20 69 73 20 4e 55 4c 4c 2e 20 0a 20  if X is NULL. . 
1cdc0 20 5e 28 41 62 73 28 58 29 20 72 65 74 75 72 6e   ^(Abs(X) return
1cdd0 73 20 30 2e 30 20 69 66 20 58 20 69 73 20 61 20  s 0.0 if X is a 
1cde0 73 74 72 69 6e 67 20 6f 72 20 62 6c 6f 62 0a 20  string or blob. 
1cdf0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1ce00 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 20 6e  converted to a n
1ce10 75 6d 65 72 69 63 20 76 61 6c 75 65 2e 29 5e 20  umeric value.)^ 
1ce20 20 5e 49 66 20 58 20 69 73 20 74 68 65 20 0a 20   ^If X is the . 
1ce30 20 69 6e 74 65 67 65 72 20 2d 39 32 32 33 33 37   integer -922337
1ce40 32 30 33 36 38 35 34 37 37 35 38 30 38 20 74 68  2036854775808 th
1ce50 65 6e 20 61 62 73 28 58 29 20 74 68 72 6f 77 73  en abs(X) throws
1ce60 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 76 65 72   an integer over
1ce70 66 6c 6f 77 0a 20 20 65 72 72 6f 72 20 73 69 6e  flow.  error sin
1ce80 63 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 65  ce there is no e
1ce90 71 75 69 76 61 6c 65 6e 74 20 70 6f 73 69 74 69  quivalent positi
1cea0 76 65 20 36 34 2d 62 69 74 20 74 77 6f 20 63 6f  ve 64-bit two co
1ceb0 6d 70 6c 65 6d 65 6e 74 20 76 61 6c 75 65 2e 0a  mplement value..
1cec0 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 63 68 61 6e  }..funcdef {chan
1ced0 67 65 73 28 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  ges()} {} {.  ^T
1cee0 68 65 20 63 68 61 6e 67 65 73 28 29 20 66 75 6e  he changes() fun
1cef0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1cf00 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
1cf10 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
1cf20 65 72 65 20 63 68 61 6e 67 65 64 0a 20 20 6f 72  ere changed.  or
1cf30 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
1cf40 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
1cf50 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
1cf60 74 65 64 20 49 4e 53 45 52 54 2c 20 44 45 4c 45  ted INSERT, DELE
1cf70 54 45 2c 0a 20 20 6f 72 20 55 50 44 41 54 45 20  TE,.  or UPDATE 
1cf80 73 74 61 74 65 6d 65 6e 74 2c 20 65 78 63 6c 75  statement, exclu
1cf90 73 69 76 65 20 6f 66 20 73 74 61 74 65 6d 65 6e  sive of statemen
1cfa0 74 73 20 69 6e 20 6c 6f 77 65 72 2d 6c 65 76 65  ts in lower-leve
1cfb0 6c 20 74 72 69 67 67 65 72 73 2e 0a 20 20 5e 54  l triggers..  ^T
1cfc0 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1cfd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 77   function is a w
1cfe0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68  rapper around th
1cff0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1d000 65 73 28 29 5d 0a 20 20 43 2f 43 2b 2b 20 66 75  es()].  C/C++ fu
1d010 6e 63 74 69 6f 6e 20 61 6e 64 20 68 65 6e 63 65  nction and hence
1d020 20 66 6f 6c 6c 6f 77 73 20 74 68 65 20 73 61 6d   follows the sam
1d030 65 20 72 75 6c 65 73 20 66 6f 72 20 63 6f 75 6e  e rules for coun
1d040 74 69 6e 67 20 63 68 61 6e 67 65 73 2e 0a 7d 0a  ting changes..}.
1d050 0a 66 75 6e 63 64 65 66 20 7b 63 68 61 72 28 58  .funcdef {char(X
1d060 31 2c 58 32 2c 2e 2e 2e 2c 58 4e 29 7d 20 7b 7d  1,X2,...,XN)} {}
1d070 20 7b 0a 20 20 5e 28 54 68 65 20 63 68 61 72 28   {.  ^(The char(
1d080 58 31 2c 58 32 2c 2e 2e 2e 2c 58 4e 29 20 66 75  X1,X2,...,XN) fu
1d090 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1d0a0 20 73 74 72 69 6e 67 20 63 6f 6d 70 6f 73 65 64   string composed
1d0b0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 68   of characters h
1d0c0 61 76 69 6e 67 20 74 68 65 0a 20 20 20 75 6e 69  aving the.   uni
1d0d0 63 6f 64 65 20 63 6f 64 65 20 70 6f 69 6e 74 20  code code point 
1d0e0 76 61 6c 75 65 73 20 6f 66 20 69 6e 74 65 67 65  values of intege
1d0f0 72 73 20 58 31 20 74 68 72 6f 75 67 68 20 58 4e  rs X1 through XN
1d100 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 29  , respectively.)
1d110 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 63 6f  ^.}..funcdef {co
1d120 61 6c 65 73 63 65 28 58 2c 59 2c 2e 2e 2e 29 7d  alesce(X,Y,...)}
1d130 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 63 6f 61   {} {.  ^The coa
1d140 6c 65 73 63 65 28 29 20 66 75 6e 63 74 69 6f 6e  lesce() function
1d150 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
1d160 6f 66 20 69 74 73 20 66 69 72 73 74 20 6e 6f 6e  of its first non
1d170 2d 4e 55 4c 4c 20 61 72 67 75 6d 65 6e 74 2c 20  -NULL argument, 
1d180 6f 72 0a 20 20 4e 55 4c 4c 20 69 66 20 61 6c 6c  or.  NULL if all
1d190 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 4e   arguments are N
1d1a0 55 4c 4c 2e 20 20 5e 43 6f 61 6c 65 73 63 65 28  ULL.  ^Coalesce(
1d1b0 29 20 6d 75 73 74 20 68 61 76 65 20 61 74 20 6c  ) must have at l
1d1c0 65 61 73 74 20 0a 20 20 32 20 61 72 67 75 6d 65  east .  2 argume
1d1d0 6e 74 73 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  nts..}..funcdef 
1d1e0 7b 67 6c 6f 62 28 58 2c 59 29 7d 20 7b 7d 20 7b  {glob(X,Y)} {} {
1d1f0 0a 20 20 5e 54 68 65 20 67 6c 6f 62 28 58 2c 59  .  ^The glob(X,Y
1d200 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 65 71  ) function is eq
1d210 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 65 0a  uivalent to the.
1d220 20 20 65 78 70 72 65 73 73 69 6f 6e 20 22 3c 62    expression "<b
1d230 3e 59 20 47 4c 4f 42 20 58 3c 2f 62 3e 22 2e 0a  >Y GLOB X</b>"..
1d240 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
1d250 58 20 61 6e 64 20 59 20 61 72 67 75 6d 65 6e 74  X and Y argument
1d260 73 20 61 72 65 20 72 65 76 65 72 73 65 64 20 69  s are reversed i
1d270 6e 20 74 68 65 20 67 6c 6f 62 28 29 20 66 75 6e  n the glob() fun
1d280 63 74 69 6f 6e 0a 20 20 72 65 6c 61 74 69 76 65  ction.  relative
1d290 20 74 6f 20 74 68 65 20 69 6e 66 69 78 20 5b 47   to the infix [G
1d2a0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 2e 20 20  LOB] operator.  
1d2b0 59 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  Y is the string 
1d2c0 61 6e 64 20 58 20 69 73 20 74 68 65 0a 20 20 70  and X is the.  p
1d2d0 61 74 74 65 72 6e 2e 20 20 53 6f 2c 20 66 6f 72  attern.  So, for
1d2e0 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66 6f   example, the fo
1d2f0 6c 6c 6f 77 69 6e 67 20 65 78 70 72 65 73 73 69  llowing expressi
1d300 6f 6e 73 20 61 72 65 20 65 71 75 69 76 61 6c 65  ons are equivale
1d310 6e 74 3a 0a 20 20 3c 62 6c 6f 63 6b 71 75 6f 74  nt:.  <blockquot
1d320 65 3e 3c 70 72 65 3e 0a 20 20 20 20 20 6e 61 6d  e><pre>.     nam
1d330 65 20 47 4c 4f 42 20 27 2a 68 65 6c 69 75 6d 2a  e GLOB '*helium*
1d340 27 0a 20 20 20 20 20 67 6c 6f 62 28 27 2a 68 65  '.     glob('*he
1d350 6c 69 75 6d 2a 27 2c 6e 61 6d 65 29 0a 20 20 3c  lium*',name).  <
1d360 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d370 65 3e 0a 20 20 3c 70 3e 5e 49 66 20 74 68 65 20  e>.  <p>^If the 
1d380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1d390 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 74 65  function()] inte
1d3a0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1d3b0 0a 20 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  .  override the 
1d3c0 67 6c 6f 62 28 58 2c 59 29 20 66 75 6e 63 74 69  glob(X,Y) functi
1d3d0 6f 6e 20 77 69 74 68 20 61 6e 20 61 6c 74 65 72  on with an alter
1d3e0 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
1d3f0 61 74 69 6f 6e 20 74 68 65 6e 0a 20 20 74 68 65  ation then.  the
1d400 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1d410 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
1d420 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
1d430 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 7d 0a 0a  lementation..}..
1d440 66 75 6e 63 64 65 66 20 7b 69 66 6e 75 6c 6c 28  funcdef {ifnull(
1d450 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  X,Y)} {} {.  ^Th
1d460 65 20 69 66 6e 75 6c 6c 28 29 20 66 75 6e 63 74  e ifnull() funct
1d470 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ion returns a co
1d480 70 79 20 6f 66 20 69 74 73 20 66 69 72 73 74 20  py of its first 
1d490 6e 6f 6e 2d 4e 55 4c 4c 20 61 72 67 75 6d 65 6e  non-NULL argumen
1d4a0 74 2c 20 6f 72 0a 20 20 4e 55 4c 4c 20 69 66 20  t, or.  NULL if 
1d4b0 62 6f 74 68 20 61 72 67 75 6d 65 6e 74 73 20 61  both arguments a
1d4c0 72 65 20 4e 55 4c 4c 2e 20 20 5e 49 66 6e 75 6c  re NULL.  ^Ifnul
1d4d0 6c 28 29 20 6d 75 73 74 20 68 61 76 65 20 65 78  l() must have ex
1d4e0 61 63 74 6c 79 20 32 20 61 72 67 75 6d 65 6e 74  actly 2 argument
1d4f0 73 2e 0a 20 20 5e 54 68 65 20 69 66 6e 75 6c 6c  s..  ^The ifnull
1d500 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 65  () function is e
1d510 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 5b 63 6f  quivalent to [co
1d520 61 6c 65 73 63 65 28 29 5d 20 77 69 74 68 20 74  alesce()] with t
1d530 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 7d 0a  wo arguments..}.
1d540 0a 66 75 6e 63 64 65 66 20 7b 69 6e 73 74 72 28  .funcdef {instr(
1d550 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  X,Y)} {} {.  ^Th
1d560 65 20 69 6e 73 74 72 28 58 2c 59 29 20 66 75 6e  e instr(X,Y) fun
1d570 63 74 69 6f 6e 20 66 69 6e 64 73 20 74 68 65 20  ction finds the 
1d580 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1d590 20 6f 66 20 73 74 72 69 6e 67 20 59 20 77 69 74   of string Y wit
1d5a0 68 69 6e 20 0a 20 20 73 74 72 69 6e 67 20 58 20  hin .  string X 
1d5b0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  and returns the 
1d5c0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20  number of prior 
1d5d0 63 68 61 72 61 63 74 65 72 73 20 70 6c 75 73 20  characters plus 
1d5e0 31 2c 20 6f 72 20 30 20 69 66 0a 20 20 59 20 69  1, or 0 if.  Y i
1d5f0 73 20 6e 6f 77 68 65 72 65 20 66 6f 75 6e 64 20  s nowhere found 
1d600 77 69 74 68 69 6e 20 58 2e 0a 20 20 5e 4f 72 2c  within X..  ^Or,
1d610 20 69 66 20 58 20 61 6e 64 20 59 20 61 72 65 20   if X and Y are 
1d620 62 6f 74 68 20 42 4c 4f 42 73 2c 20 74 68 65 6e  both BLOBs, then
1d630 20 69 6e 73 74 72 28 58 2c 59 29 20 72 65 74 75   instr(X,Y) retu
1d640 72 6e 73 20 6f 6e 65 0a 20 20 6d 6f 72 65 20 74  rns one.  more t
1d650 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 62  han the number b
1d660 79 74 65 73 20 70 72 69 6f 72 20 74 6f 20 74 68  ytes prior to th
1d670 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1d680 63 65 20 6f 66 20 59 2c 20 6f 72 20 30 20 69 66  ce of Y, or 0 if
1d690 0a 20 20 59 20 64 6f 65 73 20 6e 6f 74 20 6f 63  .  Y does not oc
1d6a0 63 75 72 20 61 6e 79 77 68 65 72 65 20 77 69 74  cur anywhere wit
1d6b0 68 69 6e 20 58 2e 0a 20 20 5e 49 66 20 62 6f 74  hin X..  ^If bot
1d6c0 68 20 61 72 67 75 6d 65 6e 74 73 20 58 20 61 6e  h arguments X an
1d6d0 64 20 59 20 74 6f 20 69 6e 73 74 72 28 58 2c 59  d Y to instr(X,Y
1d6e0 29 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 61  ) are non-NULL a
1d6f0 6e 64 20 61 72 65 20 6e 6f 74 20 42 4c 4f 42 73  nd are not BLOBs
1d700 0a 20 20 74 68 65 6e 20 62 6f 74 68 20 61 72 65  .  then both are
1d710 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1d720 73 74 72 69 6e 67 73 2e 0a 20 20 5e 49 66 20 65  strings..  ^If e
1d730 69 74 68 65 72 20 58 20 6f 72 20 59 20 61 72 65  ither X or Y are
1d740 20 4e 55 4c 4c 20 69 6e 20 69 6e 73 74 72 28 58   NULL in instr(X
1d750 2c 59 29 20 74 68 65 6e 20 74 68 65 20 72 65 73  ,Y) then the res
1d760 75 6c 74 20 69 73 20 4e 55 4c 4c 2e 0a 7d 0a 0a  ult is NULL..}..
1d770 66 75 6e 63 64 65 66 20 7b 68 65 78 28 58 29 7d  funcdef {hex(X)}
1d780 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 68 65 78   {} {.  ^The hex
1d790 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 6e 74 65  () function inte
1d7a0 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
1d7b0 65 6e 74 20 61 73 20 61 20 42 4c 4f 42 20 61 6e  ent as a BLOB an
1d7c0 64 20 72 65 74 75 72 6e 73 0a 20 20 61 20 73 74  d returns.  a st
1d7d0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 74 68  ring which is th
1d7e0 65 20 75 70 70 65 72 2d 63 61 73 65 20 68 65 78  e upper-case hex
1d7f0 61 64 65 63 69 6d 61 6c 20 72 65 6e 64 65 72 69  adecimal renderi
1d800 6e 67 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  ng of the conten
1d810 74 20 6f 66 0a 20 20 74 68 61 74 20 62 6c 6f 62  t of.  that blob
1d820 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 61  ..}..funcdef {la
1d830 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1d840 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c  )} {} {.  ^The l
1d850 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d860 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1d870 72 6e 73 20 74 68 65 20 5b 52 4f 57 49 44 5d 0a  rns the [ROWID].
1d880 20 20 6f 66 20 74 68 65 20 6c 61 73 74 20 72 6f    of the last ro
1d890 77 20 69 6e 73 65 72 74 20 66 72 6f 6d 20 74 68  w insert from th
1d8a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d8b0 63 74 69 6f 6e 20 77 68 69 63 68 20 69 6e 76 6f  ction which invo
1d8c0 6b 65 64 20 74 68 65 0a 20 20 66 75 6e 63 74 69  ked the.  functi
1d8d0 6f 6e 2e 0a 20 20 5e 54 68 65 20 6c 61 73 74 5f  on..  ^The last_
1d8e0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
1d8f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
1d900 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20   wrapper around 
1d910 74 68 65 0a 20 20 5b 73 71 6c 69 74 65 33 5f 6c  the.  [sqlite3_l
1d920 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d930 28 29 5d 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66  ()] C/C++ interf
1d940 61 63 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 7d 0a  ace function..}.
1d950 0a 66 75 6e 63 64 65 66 20 7b 6c 65 6e 67 74 68  .funcdef {length
1d960 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 46 6f 72  (X)} {} {.  ^For
1d970 20 61 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20   a string value 
1d980 58 2c 20 74 68 65 20 6c 65 6e 67 74 68 28 58 29  X, the length(X)
1d990 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1d9a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1d9b0 0a 20 20 63 68 61 72 61 63 74 65 72 73 20 28 6e  .  characters (n
1d9c0 6f 74 20 62 79 74 65 73 29 20 69 6e 20 58 20 70  ot bytes) in X p
1d9d0 72 69 6f 72 20 74 6f 20 74 68 65 20 66 69 72 73  rior to the firs
1d9e0 74 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 2e  t NUL character.
1d9f0 0a 20 20 53 69 6e 63 65 20 53 51 4c 69 74 65 20  .  Since SQLite 
1da00 73 74 72 69 6e 67 73 20 64 6f 20 6e 6f 74 20 6e  strings do not n
1da10 6f 72 6d 61 6c 6c 79 20 63 6f 6e 74 61 69 6e 20  ormally contain 
1da20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 2c 20  NUL characters, 
1da30 74 68 65 20 6c 65 6e 67 74 68 28 58 29 0a 20 20  the length(X).  
1da40 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 75 73  function will us
1da50 75 61 6c 6c 79 20 72 65 74 75 72 6e 20 74 68 65  ually return the
1da60 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1da70 20 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 74   characters in t
1da80 68 65 20 73 74 72 69 6e 67 20 58 2e 0a 20 20 5e  he string X..  ^
1da90 46 6f 72 20 61 20 62 6c 6f 62 20 76 61 6c 75 65  For a blob value
1daa0 20 58 2c 20 6c 65 6e 67 74 68 28 58 29 20 72 65   X, length(X) re
1dab0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1dac0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1dad0 20 62 6c 6f 62 2e 0a 20 20 5e 49 66 20 58 20 69   blob..  ^If X i
1dae0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6c 65 6e 67  s NULL then leng
1daf0 74 68 28 58 29 20 69 73 20 4e 55 4c 4c 2e 0a 20  th(X) is NULL.. 
1db00 20 5e 49 66 20 58 20 69 73 20 6e 75 6d 65 72 69   ^If X is numeri
1db10 63 20 74 68 65 6e 20 6c 65 6e 67 74 68 28 58 29  c then length(X)
1db20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 65 6e   returns the len
1db30 67 74 68 20 6f 66 20 61 20 73 74 72 69 6e 67 0a  gth of a string.
1db40 20 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e    representation
1db50 20 6f 66 20 58 2e 0a 7d 0a 0a 66 75 6e 63 64 65   of X..}..funcde
1db60 66 20 7b 6c 69 6b 65 28 58 2c 59 29 20 6c 69 6b  f {like(X,Y) lik
1db70 65 28 58 2c 59 2c 5a 29 7d 20 7b 7d 20 7b 0a 20  e(X,Y,Z)} {} {. 
1db80 20 5e 54 68 65 20 6c 69 6b 65 28 29 20 66 75 6e   ^The like() fun
1db90 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
1dba0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 0a 20   implement the. 
1dbb0 20 22 3c 62 3e 59 20 4c 49 4b 45 20 58 20 26 23   "<b>Y LIKE X &#
1dbc0 39 31 3b 45 53 43 41 50 45 20 5a 26 23 39 33 3b  91;ESCAPE Z&#93;
1dbd0 3c 2f 62 3e 22 20 65 78 70 72 65 73 73 69 6f 6e  </b>" expression
1dbe0 2e 20 0a 20 20 5e 49 66 20 74 68 65 20 6f 70 74  . .  ^If the opt
1dbf0 69 6f 6e 61 6c 20 45 53 43 41 50 45 20 63 6c 61  ional ESCAPE cla
1dc00 75 73 65 20 69 73 20 70 72 65 73 65 6e 74 2c 20  use is present, 
1dc10 74 68 65 6e 20 74 68 65 0a 20 20 6c 69 6b 65 28  then the.  like(
1dc20 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  ) function is in
1dc30 76 6f 6b 65 64 20 77 69 74 68 20 74 68 72 65 65  voked with three
1dc40 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 5e 4f 74   arguments.  ^Ot
1dc50 68 65 72 77 69 73 65 2c 20 69 74 20 69 73 0a 20  herwise, it is. 
1dc60 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1dc70 6f 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 6c 79  o arguments only
1dc80 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1dc90 58 20 61 6e 64 20 59 20 70 61 72 61 6d 65 74 65  X and Y paramete
1dca0 72 73 20 61 72 65 0a 20 20 72 65 76 65 72 73 65  rs are.  reverse
1dcb0 64 20 69 6e 20 74 68 65 20 6c 69 6b 65 28 29 20  d in the like() 
1dcc0 66 75 6e 63 74 69 6f 6e 20 72 65 6c 61 74 69 76  function relativ
1dcd0 65 20 74 6f 20 74 68 65 20 69 6e 66 69 78 20 5b  e to the infix [
1dce0 4c 49 4b 45 5d 20 6f 70 65 72 61 74 6f 72 2e 0a  LIKE] operator..
1dcf0 20 20 58 20 69 73 20 74 68 65 20 70 61 74 74 65    X is the patte
1dd00 72 6e 20 61 6e 64 20 59 20 69 73 20 74 68 65 20  rn and Y is the 
1dd10 73 74 72 69 6e 67 20 74 6f 20 6d 61 74 63 68 20  string to match 
1dd20 61 67 61 69 6e 73 74 20 74 68 61 74 20 70 61 74  against that pat
1dd30 74 65 72 6e 2e 0a 20 20 48 65 6e 63 65 2c 20 74  tern..  Hence, t
1dd40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 70  he following exp
1dd50 72 65 73 73 69 6f 6e 73 20 61 72 65 20 65 71 75  ressions are equ
1dd60 69 76 61 6c 65 6e 74 3a 0a 20 20 3c 62 6c 6f 63  ivalent:.  <bloc
1dd70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20  kquote><pre>.   
1dd80 20 20 6e 61 6d 65 20 4c 49 4b 45 20 27 25 6e 65    name LIKE '%ne
1dd90 6f 6e 25 27 0a 20 20 20 20 20 6c 69 6b 65 28 27  on%'.     like('
1dda0 25 6e 65 6f 6e 25 27 2c 6e 61 6d 65 29 0a 20 20  %neon%',name).  
1ddb0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ddc0 74 65 3e 0a 20 20 5e 54 68 65 20 5b 73 71 6c 69  te>.  ^The [sqli
1ddd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1dde0 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
1ddf0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1de00 6f 76 65 72 72 69 64 65 20 74 68 65 0a 20 20 6c  override the.  l
1de10 69 6b 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ike() function a
1de20 6e 64 20 74 68 65 72 65 62 79 20 63 68 61 6e 67  nd thereby chang
1de30 65 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  e the operation 
1de40 6f 66 20 74 68 65 0a 20 20 5b 4c 49 4b 45 5d 20  of the.  [LIKE] 
1de50 6f 70 65 72 61 74 6f 72 2e 20 20 57 68 65 6e 20  operator.  When 
1de60 6f 76 65 72 72 69 64 69 6e 67 20 74 68 65 20 6c  overriding the l
1de70 69 6b 65 28 29 20 66 75 6e 63 74 69 6f 6e 2c 20  ike() function, 
1de80 69 74 20 6d 61 79 20 62 65 20 69 6d 70 6f 72 74  it may be import
1de90 61 6e 74 0a 20 20 74 6f 20 6f 76 65 72 72 69 64  ant.  to overrid
1dea0 65 20 62 6f 74 68 20 74 68 65 20 74 77 6f 20 61  e both the two a
1deb0 6e 64 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  nd three argumen
1dec0 74 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  t versions of th
1ded0 65 20 6c 69 6b 65 28 29 20 0a 20 20 66 75 6e 63  e like() .  func
1dee0 74 69 6f 6e 2e 20 4f 74 68 65 72 77 69 73 65 2c  tion. Otherwise,
1def0 20 64 69 66 66 65 72 65 6e 74 20 63 6f 64 65 20   different code 
1df00 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  may be called to
1df10 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 0a 20   implement the. 
1df20 20 5b 4c 49 4b 45 5d 20 6f 70 65 72 61 74 6f 72   [LIKE] operator
1df30 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1df40 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1df50 45 53 43 41 50 45 20 63 6c 61 75 73 65 20 77 61  ESCAPE clause wa
1df60 73 20 0a 20 20 73 70 65 63 69 66 69 65 64 2e 0a  s .  specified..
1df70 7d 0a 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 69 6b  }...funcdef {lik
1df80 65 6c 69 68 6f 6f 64 28 58 2c 59 29 7d 20 7b 7d  elihood(X,Y)} {}
1df90 20 7b 0a 20 20 5e 54 68 65 20 6c 69 6b 65 6c 69   {.  ^The likeli
1dfa0 68 6f 6f 64 28 58 2c 59 29 20 66 75 6e 63 74 69  hood(X,Y) functi
1dfb0 6f 6e 20 72 65 74 75 72 6e 73 20 61 72 67 75 6d  on returns argum
1dfc0 65 6e 74 20 58 20 75 6e 63 68 61 6e 67 65 64 2e  ent X unchanged.
1dfd0 0a 20 20 5e 28 54 68 65 20 76 61 6c 75 65 20 59  .  ^(The value Y
1dfe0 20 69 6e 20 6c 69 6b 65 6c 69 68 6f 6f 64 28 58   in likelihood(X
1dff0 2c 59 29 20 6d 75 73 74 20 62 65 20 61 20 66 6c  ,Y) must be a fl
1e000 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 63 6f 6e  oating point con
1e010 73 74 61 6e 74 0a 20 20 62 65 74 77 65 65 6e 20  stant.  between 
1e020 30 2e 30 20 61 6e 64 20 31 2e 30 2c 20 69 6e 63  0.0 and 1.0, inc
1e030 6c 75 73 69 76 65 2e 29 5e 0a 20 20 5e 54 68 65  lusive.)^.  ^The
1e040 20 6c 69 6b 65 6c 69 68 6f 6f 64 28 58 29 20 66   likelihood(X) f
1e050 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d  unction is a no-
1e060 6f 70 20 74 68 61 74 20 74 68 65 20 63 6f 64 65  op that the code
1e070 20 67 65 6e 65 72 61 74 6f 72 0a 20 20 6f 70 74   generator.  opt
1e080 69 6d 69 7a 65 73 20 61 77 61 79 20 73 6f 20 74  imizes away so t
1e090 68 61 74 20 69 74 20 63 6f 6e 73 75 6d 65 73 20  hat it consumes 
1e0a0 6e 6f 20 43 50 55 20 63 79 63 6c 65 73 20 64 75  no CPU cycles du
1e0b0 72 69 6e 67 20 72 75 6e 2d 74 69 6d 65 0a 20 20  ring run-time.  
1e0c0 28 74 68 61 74 20 69 73 2c 20 64 75 72 69 6e 67  (that is, during
1e0d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1e0e0 65 33 5f 73 74 65 70 28 29 5d 29 2e 0a 20 20 5e  e3_step()])..  ^
1e0f0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
1e100 68 65 20 6c 69 6b 65 6c 69 68 6f 6f 64 28 58 2c  he likelihood(X,
1e110 59 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  Y) function is t
1e120 6f 20 70 72 6f 76 69 64 65 20 61 20 68 69 6e 74  o provide a hint
1e130 0a 20 20 74 6f 20 74 68 65 20 71 75 65 72 79 20  .  to the query 
1e140 70 6c 61 6e 6e 65 72 20 74 68 61 74 20 74 68 65  planner that the
1e150 20 61 72 67 75 6d 65 6e 74 20 58 20 69 73 20 61   argument X is a
1e160 20 62 6f 6f 6c 65 61 6e 20 74 68 61 74 20 69 73   boolean that is
1e170 0a 20 20 74 72 75 65 20 77 69 74 68 20 61 20 70  .  true with a p
1e180 72 6f 62 61 62 69 6c 69 74 79 20 6f 66 20 61 70  robability of ap
1e190 70 72 6f 78 69 6d 61 74 65 6c 79 20 59 2e 0a 20  proximately Y.. 
1e1a0 20 5e 28 54 68 65 20 5b 75 6e 6c 69 6b 65 6c 79   ^(The [unlikely
1e1b0 28 58 29 5d 20 66 75 6e 63 74 69 6f 6e 20 69 73  (X)] function is
1e1c0 20 73 68 6f 72 74 2d 68 61 6e 64 20 66 6f 72 20   short-hand for 
1e1d0 6c 69 6b 65 6c 69 68 6f 6f 64 28 58 2c 30 2e 30  likelihood(X,0.0
1e1e0 36 32 35 29 2e 29 5e 0a 20 20 5e 28 54 68 65 20  625).)^.  ^(The 
1e1f0 5b 6c 69 6b 65 6c 79 28 58 29 5d 20 66 75 6e 63  [likely(X)] func
1e200 74 69 6f 6e 20 69 73 20 73 68 6f 72 74 2d 68 61  tion is short-ha
1e210 6e 64 20 66 6f 72 20 6c 69 6b 65 6c 69 68 6f 6f  nd for likelihoo
1e220 64 28 58 2c 30 2e 39 33 37 35 29 2e 29 5e 0a 7d  d(X,0.9375).)^.}
1e230 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 69 6b 65 6c  ..funcdef {likel
1e240 79 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  y(X)} {} {.  ^Th
1e250 65 20 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e 63  e likely(X) func
1e260 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1e270 20 61 72 67 75 6d 65 6e 74 20 58 20 75 6e 63 68   argument X unch
1e280 61 6e 67 65 64 2e 0a 20 20 5e 54 68 65 20 6c 69  anged..  ^The li
1e290 6b 65 6c 79 28 58 29 20 66 75 6e 63 74 69 6f 6e  kely(X) function
1e2a0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 74 68 61 74   is a no-op that
1e2b0 20 74 68 65 20 63 6f 64 65 20 67 65 6e 65 72 61   the code genera
1e2c0 74 6f 72 0a 20 20 6f 70 74 69 6d 69 7a 65 73 20  tor.  optimizes 
1e2d0 61 77 61 79 20 73 6f 20 74 68 61 74 20 69 74 20  away so that it 
1e2e0 63 6f 6e 73 75 6d 65 73 20 6e 6f 20 43 50 55 20  consumes no CPU 
1e2f0 63 79 63 6c 65 73 20 61 74 0a 20 20 72 75 6e 2d  cycles at.  run-
1e300 74 69 6d 65 20 28 74 68 61 74 20 69 73 2c 20 64  time (that is, d
1e310 75 72 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  uring calls to [
1e320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 29  sqlite3_step()])
1e330 2e 0a 20 20 5e 54 68 65 20 70 75 72 70 6f 73 65  ..  ^The purpose
1e340 20 6f 66 20 74 68 65 20 6c 69 6b 65 6c 79 28 58   of the likely(X
1e350 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  ) function is to
1e360 20 70 72 6f 76 69 64 65 20 61 20 68 69 6e 74 0a   provide a hint.
1e370 20 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70    to the query p
1e380 6c 61 6e 6e 65 72 20 74 68 61 74 20 74 68 65 20  lanner that the 
1e390 61 72 67 75 6d 65 6e 74 20 58 20 69 73 20 61 20  argument X is a 
1e3a0 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65 0a 20 20  boolean value.  
1e3b0 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
1e3c0 74 72 75 65 2e 20 5e 28 54 68 65 20 6c 69 6b 65  true. ^(The like
1e3d0 6c 79 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 69  ly(X) function i
1e3e0 73 20 65 71 75 69 76 61 6c 65 6e 74 0a 20 20 74  s equivalent.  t
1e3f0 6f 20 5b 6c 69 6b 65 6c 69 68 6f 6f 64 5d 28 58  o [likelihood](X
1e400 2c 30 2e 39 33 37 35 29 2e 29 5e 20 53 65 65 20  ,0.9375).)^ See 
1e410 61 6c 73 6f 3a 20 5b 75 6e 6c 69 6b 65 6c 79 28  also: [unlikely(
1e420 58 29 5d 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  X)]..}..funcdef 
1e430 7b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  {load_extension(
1e440 58 29 20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  X) load_extensio
1e450 6e 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20 5e  n(X,Y)} {} {.  ^
1e460 54 68 65 20 6c 6f 61 64 5f 65 78 74 65 6e 73 69  The load_extensi
1e470 6f 6e 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e  on(X,Y) function
1e480 20 6c 6f 61 64 73 20 5b 53 51 4c 69 74 65 20 65   loads [SQLite e
1e490 78 74 65 6e 73 69 6f 6e 73 5d 20 6f 75 74 20 6f  xtensions] out o
1e4a0 66 20 74 68 65 20 73 68 61 72 65 64 0a 20 20 6c  f the shared.  l
1e4b0 69 62 72 61 72 79 20 66 69 6c 65 20 6e 61 6d 65  ibrary file name
1e4c0 64 20 58 20 75 73 69 6e 67 20 74 68 65 20 65 6e  d X using the en
1e4d0 74 72 79 20 70 6f 69 6e 74 20 59 2e 20 20 5e 54  try point Y.  ^T
1e4e0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6c 6f 61  he result of loa
1e4f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 0a 20 20  d_extension().  
1e500 69 73 20 61 6c 77 61 79 73 20 61 20 4e 55 4c 4c  is always a NULL
1e510 2e 20 20 5e 49 66 20 59 20 69 73 20 6f 6d 69 74  .  ^If Y is omit
1e520 74 65 64 20 74 68 65 6e 20 74 68 65 20 64 65 66  ted then the def
1e530 61 75 6c 74 20 65 6e 74 72 79 20 70 6f 69 6e 74  ault entry point
1e540 20 6e 61 6d 65 20 69 73 20 75 73 65 64 2e 0a 20   name is used.. 
1e550 20 5e 54 68 65 20 6c 6f 61 64 5f 65 78 74 65 6e   ^The load_exten
1e560 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
1e570 72 61 69 73 65 73 20 61 6e 20 65 78 63 65 70 74  raises an except
1e580 69 6f 6e 20 69 66 20 74 68 65 20 65 78 74 65 6e  ion if the exten
1e590 73 69 6f 6e 20 66 61 69 6c 73 20 74 6f 0a 20 20  sion fails to.  
1e5a0 6c 6f 61 64 20 6f 72 20 69 6e 69 74 69 61 6c 69  load or initiali
1e5b0 7a 65 20 63 6f 72 72 65 63 74 6c 79 2e 0a 0a 20  ze correctly... 
1e5c0 20 3c 70 3e 5e 54 68 65 20 6c 6f 61 64 5f 65 78   <p>^The load_ex
1e5d0 74 65 6e 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  tension() functi
1e5e0 6f 6e 20 77 69 6c 6c 20 66 61 69 6c 20 69 66 20  on will fail if 
1e5f0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 61 74  the extension at
1e600 74 65 6d 70 74 73 20 74 6f 20 0a 20 20 6d 6f 64  tempts to .  mod
1e610 69 66 79 20 6f 72 20 64 65 6c 65 74 65 20 61 6e  ify or delete an
1e620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
1e630 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
1e640 6e 63 65 2e 20 20 5e 54 68 65 0a 20 20 65 78 74  nce.  ^The.  ext
1e650 65 6e 73 69 6f 6e 20 63 61 6e 20 61 64 64 20 6e  ension can add n
1e660 65 77 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  ew functions or 
1e670 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
1e680 63 65 73 2c 20 62 75 74 20 63 61 6e 6e 6f 74 0a  ces, but cannot.
1e690 20 20 6d 6f 64 69 66 79 20 6f 72 20 64 65 6c 65    modify or dele
1e6a0 74 65 20 65 78 69 73 74 69 6e 67 20 66 75 6e 63  te existing func
1e6b0 74 69 6f 6e 73 20 6f 72 20 63 6f 6c 6c 61 74 69  tions or collati
1e6c0 6e 67 20 73 65 71 75 65 6e 63 65 73 20 62 65 63  ng sequences bec
1e6d0 61 75 73 65 0a 20 20 74 68 6f 73 65 20 66 75 6e  ause.  those fun
1e6e0 63 74 69 6f 6e 73 20 61 6e 64 2f 6f 72 20 63 6f  ctions and/or co
1e6f0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
1e700 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  s might be used 
1e710 65 6c 73 65 77 68 65 72 65 0a 20 20 69 6e 20 74  elsewhere.  in t
1e720 68 65 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  he currently run
1e730 6e 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ning SQL stateme
1e740 6e 74 2e 20 20 54 6f 20 6c 6f 61 64 20 61 6e 20  nt.  To load an 
1e750 65 78 74 65 6e 73 69 6f 6e 20 74 68 61 74 0a 20  extension that. 
1e760 20 63 68 61 6e 67 65 73 20 6f 72 20 64 65 6c 65   changes or dele
1e770 74 65 73 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  tes functions or
1e780 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
1e790 6e 63 65 73 2c 20 75 73 65 20 74 68 65 0a 20 20  nces, use the.  
1e7a0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
1e7b0 74 65 6e 73 69 6f 6e 28 29 5d 20 43 2d 6c 61 6e  tension()] C-lan
1e7c0 67 75 61 67 65 20 41 50 49 2e 3c 2f 70 3e 0a 0a  guage API.</p>..
1e7d0 20 20 3c 70 3e 46 6f 72 20 73 65 63 75 72 69 74    <p>For securit
1e7e0 79 20 72 65 61 73 6f 6e 73 2c 20 65 78 74 65 6e  y reasons, exten
1e7f0 73 69 6f 6e 20 6c 6f 61 64 65 64 20 69 73 20 74  sion loaded is t
1e800 75 72 6e 65 64 20 6f 66 66 20 62 79 20 64 65 66  urned off by def
1e810 61 75 6c 74 20 61 6e 64 20 6d 75 73 74 0a 20 20  ault and must.  
1e820 62 65 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20  be enabled by a 
1e830 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
1e840 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1e850 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
1e860 3c 2f 70 3e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  </p>.}..funcdef 
1e870 7b 6c 6f 77 65 72 28 58 29 7d 20 7b 7d 20 7b 0a  {lower(X)} {} {.
1e880 20 20 5e 54 68 65 20 6c 6f 77 65 72 28 58 29 20    ^The lower(X) 
1e890 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1e8a0 20 61 20 63 6f 70 79 20 6f 66 20 73 74 72 69 6e   a copy of strin
1e8b0 67 20 58 20 77 69 74 68 20 61 6c 6c 20 41 53 43  g X with all ASC
1e8c0 49 49 20 63 68 61 72 61 63 74 65 72 73 0a 20 20  II characters.  
1e8d0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 6c 6f 77  converted to low
1e8e0 65 72 20 63 61 73 65 2e 20 20 5e 54 68 65 20 64  er case.  ^The d
1e8f0 65 66 61 75 6c 74 20 62 75 69 6c 74 2d 69 6e 20  efault built-in 
1e900 6c 6f 77 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  lower() function
1e910 20 77 6f 72 6b 73 0a 20 20 66 6f 72 20 41 53 43   works.  for ASC
1e920 49 49 20 63 68 61 72 61 63 74 65 72 73 20 6f 6e  II characters on
1e930 6c 79 2e 20 20 54 6f 20 64 6f 20 63 61 73 65 20  ly.  To do case 
1e940 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 6e 20 6e  conversions on n
1e950 6f 6e 2d 41 53 43 49 49 0a 20 20 63 68 61 72 61  on-ASCII.  chara
1e960 63 74 65 72 73 2c 20 6c 6f 61 64 20 74 68 65 20  cters, load the 
1e970 49 43 55 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 7d  ICU extension..}
1e980 0a 0a 66 75 6e 63 64 65 66 20 7b 6c 74 72 69 6d  ..funcdef {ltrim
1e990 28 58 29 20 6c 74 72 69 6d 28 58 2c 59 29 7d 20  (X) ltrim(X,Y)} 
1e9a0 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 6c 74 72 69  {} {.  ^The ltri
1e9b0 6d 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20  m(X,Y) function 
1e9c0 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e 67  returns a string
1e9d0 20 66 6f 72 6d 65 64 20 62 79 20 72 65 6d 6f 76   formed by remov
1e9e0 69 6e 67 20 61 6e 79 20 61 6e 64 20 61 6c 6c 0a  ing any and all.
1e9f0 20 20 63 68 61 72 61 63 74 65 72 73 20 74 68 61    characters tha
1ea00 74 20 61 70 70 65 61 72 20 69 6e 20 59 20 66 72  t appear in Y fr
1ea10 6f 6d 20 74 68 65 20 6c 65 66 74 20 73 69 64 65  om the left side
1ea20 20 6f 66 20 58 2e 0a 20 20 5e 49 66 20 74 68 65   of X..  ^If the
1ea30 20 59 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   Y argument is o
1ea40 6d 69 74 74 65 64 2c 20 6c 74 72 69 6d 28 58 29  mitted, ltrim(X)
1ea50 20 72 65 6d 6f 76 65 73 20 73 70 61 63 65 73 20   removes spaces 
1ea60 66 72 6f 6d 20 74 68 65 20 6c 65 66 74 20 73 69  from the left si
1ea70 64 65 0a 20 20 6f 66 20 58 2e 0a 7d 0a 0a 66 75  de.  of X..}..fu
1ea80 6e 63 64 65 66 20 7b 6d 61 78 28 58 2c 59 2c 2e  ncdef {max(X,Y,.
1ea90 2e 2e 29 7d 20 7b 2a 6d 61 78 43 6f 72 65 46 75  ..)} {*maxCoreFu
1eaa0 6e 63 20 2a 6d 61 78 20 7b 6d 61 78 28 29 20 53  nc *max {max() S
1eab0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a  QL function}} {.
1eac0 20 20 5e 54 68 65 20 6d 75 6c 74 69 2d 61 72 67    ^The multi-arg
1ead0 75 6d 65 6e 74 20 6d 61 78 28 29 20 66 75 6e 63  ument max() func
1eae0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1eaf0 20 61 72 67 75 6d 65 6e 74 20 77 69 74 68 20 74   argument with t
1eb00 68 65 20 0a 20 20 6d 61 78 69 6d 75 6d 20 76 61  he .  maximum va
1eb10 6c 75 65 2c 20 6f 72 20 72 65 74 75 72 6e 20 4e  lue, or return N
1eb20 55 4c 4c 20 69 66 20 61 6e 79 20 61 72 67 75 6d  ULL if any argum
1eb30 65 6e 74 20 69 73 20 4e 55 4c 4c 2e 20 0a 20 20  ent is NULL. .  
1eb40 5e 54 68 65 20 6d 75 6c 74 69 2d 61 72 67 75 6d  ^The multi-argum
1eb50 65 6e 74 20 6d 61 78 28 29 20 66 75 6e 63 74 69  ent max() functi
1eb60 6f 6e 20 73 65 61 72 63 68 65 73 20 69 74 73 20  on searches its 
1eb70 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 6c  arguments from l
1eb80 65 66 74 20 74 6f 20 72 69 67 68 74 0a 20 20 66  eft to right.  f
1eb90 6f 72 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74  or an argument t
1eba0 68 61 74 20 64 65 66 69 6e 65 73 20 61 20 63 6f  hat defines a co
1ebb0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
1ebc0 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 63   and uses that c
1ebd0 6f 6c 6c 61 74 69 6e 67 0a 20 20 66 75 6e 63 74  ollating.  funct
1ebe0 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 73 74 72 69  ion for all stri
1ebf0 6e 67 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e 20  ng comparisons. 
1ec00 20 5e 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65   ^If none of the
1ec10 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 6d 61   arguments to ma
1ec20 78 28 29 0a 20 20 64 65 66 69 6e 65 20 61 20 63  x().  define a c
1ec30 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
1ec40 6e 2c 20 74 68 65 6e 20 74 68 65 20 42 49 4e 41  n, then the BINA
1ec50 52 59 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  RY collating fun
1ec60 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 20  ction is used.. 
1ec70 20 5e 28 4e 6f 74 65 20 74 68 61 74 20 3c 62 3e   ^(Note that <b>
1ec80 6d 61 78 28 29 3c 2f 62 3e 20 69 73 20 61 20 73  max()</b> is a s
1ec90 69 6d 70 6c 65 20 66 75 6e 63 74 69 6f 6e 20 77  imple function w
1eca0 68 65 6e 0a 20 20 69 74 20 68 61 73 20 32 20 6f  hen.  it has 2 o
1ecb0 72 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e 74 73  r more arguments
1ecc0 20 62 75 74 20 6f 70 65 72 61 74 65 73 20 61 73   but operates as
1ecd0 20 61 6e 0a 20 20 5b 6d 61 78 41 67 67 46 75 6e   an.  [maxAggFun
1ece0 63 20 7c 20 61 67 67 72 65 67 61 74 65 20 66 75  c | aggregate fu
1ecf0 6e 63 74 69 6f 6e 5d 20 69 66 20 67 69 76 65 6e  nction] if given
1ed00 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   only a single a
1ed10 72 67 75 6d 65 6e 74 2e 29 5e 0a 7d 0a 0a 66 75  rgument.)^.}..fu
1ed20 6e 63 64 65 66 20 7b 6d 69 6e 28 58 2c 59 2c 2e  ncdef {min(X,Y,.
1ed30 2e 2e 29 7d 20 7b 2a 6d 69 6e 43 6f 72 65 46 75  ..)} {*minCoreFu
1ed40 6e 63 20 2a 6d 69 6e 20 7b 6d 69 6e 28 29 20 53  nc *min {min() S
1ed50 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 7d 20 7b 0a  QL function}} {.
1ed60 20 20 5e 54 68 65 20 6d 75 6c 74 69 2d 61 72 67    ^The multi-arg
1ed70 75 6d 65 6e 74 20 6d 69 6e 28 29 20 66 75 6e 63  ument min() func
1ed80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1ed90 20 61 72 67 75 6d 65 6e 74 20 77 69 74 68 20 74   argument with t
1eda0 68 65 0a 20 20 6d 69 6e 69 6d 75 6d 20 76 61 6c  he.  minimum val
1edb0 75 65 2e 0a 20 20 5e 54 68 65 20 6d 75 6c 74 69  ue..  ^The multi
1edc0 2d 61 72 67 75 6d 65 6e 74 20 6d 69 6e 28 29 20  -argument min() 
1edd0 66 75 6e 63 74 69 6f 6e 20 73 65 61 72 63 68 65  function searche
1ede0 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 73 20  s its arguments 
1edf0 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67  from left to rig
1ee00 68 74 0a 20 20 66 6f 72 20 61 6e 20 61 72 67 75  ht.  for an argu
1ee10 6d 65 6e 74 20 74 68 61 74 20 64 65 66 69 6e 65  ment that define
1ee20 73 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  s a collating fu
1ee30 6e 63 74 69 6f 6e 20 61 6e 64 20 75 73 65 73 20  nction and uses 
1ee40 74 68 61 74 20 63 6f 6c 6c 61 74 69 6e 67 0a 20  that collating. 
1ee50 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 6c   function for al
1ee60 6c 20 73 74 72 69 6e 67 20 63 6f 6d 70 61 72 69  l string compari
1ee70 73 6f 6e 73 2e 20 20 5e 49 66 20 6e 6f 6e 65 20  sons.  ^If none 
1ee80 6f 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73  of the arguments
1ee90 20 74 6f 20 6d 69 6e 28 29 0a 20 20 64 65 66 69   to min().  defi
1eea0 6e 65 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ne a collating f
1eeb0 75 6e 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  unction, then th
1eec0 65 20 42 49 4e 41 52 59 20 63 6f 6c 6c 61 74 69  e BINARY collati
1eed0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  ng function is u
1eee0 73 65 64 2e 0a 20 20 5e 28 4e 6f 74 65 20 74 68  sed..  ^(Note th
1eef0 61 74 20 3c 62 3e 6d 69 6e 28 29 3c 2f 62 3e 20  at <b>min()</b> 
1ef00 69 73 20 61 20 73 69 6d 70 6c 65 20 66 75 6e 63  is a simple func
1ef10 74 69 6f 6e 20 77 68 65 6e 0a 20 20 69 74 20 68  tion when.  it h
1ef20 61 73 20 32 20 6f 72 20 6d 6f 72 65 20 61 72 67  as 2 or more arg
1ef30 75 6d 65 6e 74 73 20 62 75 74 20 6f 70 65 72 61  uments but opera
1ef40 74 65 73 20 61 73 20 61 6e 20 0a 20 20 5b 6d 69  tes as an .  [mi
1ef50 6e 41 67 67 46 75 6e 63 20 7c 20 61 67 67 72 65  nAggFunc | aggre
1ef60 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 5d 20 69  gate function] i
1ef70 66 20 67 69 76 65 6e 0a 20 20 6f 6e 6c 79 20 61  f given.  only a
1ef80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
1ef90 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  .)^.}..funcdef {
1efa0 6e 75 6c 6c 69 66 28 58 2c 59 29 7d 20 7b 7d 20  nullif(X,Y)} {} 
1efb0 7b 0a 20 20 5e 54 68 65 20 6e 75 6c 6c 69 66 28  {.  ^The nullif(
1efc0 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  X,Y) function re
1efd0 74 75 72 6e 73 20 69 74 73 20 66 69 72 73 74 20  turns its first 
1efe0 61 72 67 75 6d 65 6e 74 20 69 66 20 74 68 65 20  argument if the 
1eff0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 0a 20 20  arguments are.  
1f000 64 69 66 66 65 72 65 6e 74 20 61 6e 64 20 4e 55  different and NU
1f010 4c 4c 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  LL if the argume
1f020 6e 74 73 20 61 72 65 20 74 68 65 20 73 61 6d 65  nts are the same
1f030 2e 20 20 5e 54 68 65 20 6e 75 6c 6c 69 66 28 58  .  ^The nullif(X
1f040 2c 59 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20 73  ,Y) function.  s
1f050 65 61 72 63 68 65 73 20 69 74 73 20 61 72 67 75  earches its argu
1f060 6d 65 6e 74 73 20 66 72 6f 6d 20 6c 65 66 74 20  ments from left 
1f070 74 6f 20 72 69 67 68 74 20 66 6f 72 20 61 6e 20  to right for an 
1f080 61 72 67 75 6d 65 6e 74 20 74 68 61 74 20 64 65  argument that de
1f090 66 69 6e 65 73 20 61 0a 20 20 63 6f 6c 6c 61 74  fines a.  collat
1f0a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64  ing function and
1f0b0 20 75 73 65 73 20 74 68 61 74 20 63 6f 6c 6c 61   uses that colla
1f0c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ting function fo
1f0d0 72 20 61 6c 6c 20 73 74 72 69 6e 67 0a 20 20 63  r all string.  c
1f0e0 6f 6d 70 61 72 69 73 6f 6e 73 2e 20 20 5e 49 66  omparisons.  ^If
1f0f0 20 6e 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e   neither argumen
1f100 74 20 74 6f 20 6e 75 6c 6c 69 66 28 29 20 64 65  t to nullif() de
1f110 66 69 6e 65 73 20 61 20 63 6f 6c 6c 61 74 69 6e  fines a collatin
1f120 67 20 66 75 6e 63 74 69 6f 6e 0a 20 20 74 68 65  g function.  the
1f130 6e 20 74 68 65 20 42 49 4e 41 52 59 20 69 73 20  n the BINARY is 
1f140 75 73 65 64 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  used..}..funcdef
1f150 20 7b 70 72 69 6e 74 66 28 46 4f 52 4d 41 54 2c   {printf(FORMAT,
1f160 2e 2e 2e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 28 54  ...)} {} {.  ^(T
1f170 68 65 20 70 72 69 6e 74 66 28 46 4f 52 4d 41 54  he printf(FORMAT
1f180 2c 2e 2e 2e 29 20 53 51 4c 20 66 75 6e 63 74 69  ,...) SQL functi
1f190 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 74 68  on works like th
1f1a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
1f1b0 74 66 28 29 5d 20 43 2d 6c 61 6e 67 75 61 67 65  tf()] C-language
1f1c0 0a 20 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20  .  function and 
1f1d0 74 68 65 20 70 72 69 6e 74 66 28 29 20 66 75 6e  the printf() fun
1f1e0 63 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 73  ction from the s
1f1f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1f200 79 2e 29 5e 0a 20 20 54 68 65 20 66 69 72 73 74  y.)^.  The first
1f210 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 66   argument is a f
1f220 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 74 68 61  ormat string tha
1f230 74 20 73 70 65 63 69 66 69 65 73 20 68 6f 77 20  t specifies how 
1f240 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 74 68 65  to construct the
1f250 20 6f 75 74 70 75 74 0a 20 20 73 74 72 69 6e 67   output.  string
1f260 20 75 73 69 6e 67 20 76 61 6c 75 65 73 20 74 61   using values ta
1f270 6b 65 6e 20 66 72 6f 6d 20 73 75 62 73 65 71 75  ken from subsequ
1f280 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ent arguments.  
1f290 5e 49 66 20 74 68 65 20 46 4f 52 4d 41 54 20 61  ^If the FORMAT a
1f2a0 72 67 75 6d 65 6e 74 20 69 73 0a 20 20 6d 69 73  rgument is.  mis
1f2b0 73 69 6e 67 20 6f 72 20 4e 55 4c 4c 20 74 68 65  sing or NULL the
1f2c0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  n the result is 
1f2d0 4e 55 4c 4c 2e 20 20 5e 54 68 65 20 25 6e 20 66  NULL.  ^The %n f
1f2e0 6f 72 6d 61 74 20 69 73 20 73 69 6c 65 6e 74 6c  ormat is silentl
1f2f0 79 20 69 67 6e 6f 72 65 64 20 61 6e 64 0a 20 20  y ignored and.  
1f300 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 73 75 6d 65  does not consume
1f310 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   an argument.  ^
1f320 54 68 65 20 25 70 20 66 6f 72 6d 61 74 20 69 73  The %p format is
1f330 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 25 58   an alias for %X
1f340 2e 20 20 5e 54 68 65 20 25 7a 20 66 6f 72 6d 61  .  ^The %z forma
1f350 74 0a 20 20 69 73 20 69 6e 74 65 72 63 68 61 6e  t.  is interchan
1f360 67 65 61 62 6c 65 20 77 69 74 68 20 25 73 2e 20  geable with %s. 
1f370 20 5e 28 49 66 20 74 68 65 72 65 20 61 72 65 20   ^(If there are 
1f380 74 6f 6f 20 66 65 77 20 61 72 67 75 6d 65 6e 74  too few argument
1f390 73 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e  s in the argumen
1f3a0 74 20 6c 69 73 74 2c 0a 20 20 6d 69 73 73 69 6e  t list,.  missin
1f3b0 67 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  g arguments are 
1f3c0 61 73 73 75 6d 65 64 20 74 6f 20 68 61 76 65 20  assumed to have 
1f3d0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 2c 20 77 68  a NULL value, wh
1f3e0 69 63 68 20 69 73 20 74 72 61 6e 73 6c 61 74 65  ich is translate
1f3f0 64 20 69 6e 74 6f 0a 20 20 30 20 6f 72 20 30 2e  d into.  0 or 0.
1f400 30 20 66 6f 72 20 6e 75 6d 65 72 69 63 20 66 6f  0 for numeric fo
1f410 72 6d 61 74 73 20 6f 72 20 61 6e 20 65 6d 70 74  rmats or an empt
1f420 79 20 73 74 72 69 6e 67 20 66 6f 72 20 25 73 2e  y string for %s.
1f430 29 5e 20 20 53 65 65 20 74 68 65 0a 20 20 5b 62  )^  See the.  [b
1f440 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1f450 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1f460 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
1f470 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 7d 0a 20 20  nformation..}.  
1f480 0a 0a 66 75 6e 63 64 65 66 20 7b 71 75 6f 74 65  ..funcdef {quote
1f490 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65  (X)} {} {.  ^The
1f4a0 20 71 75 6f 74 65 28 58 29 20 66 75 6e 63 74 69   quote(X) functi
1f4b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1f4c0 65 78 74 20 6f 66 20 61 6e 20 53 51 4c 20 6c 69  ext of an SQL li
1f4d0 74 65 72 61 6c 20 77 68 69 63 68 0a 20 20 69 73  teral which.  is
1f4e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 69 74   the value of it
1f4f0 73 20 61 72 67 75 6d 65 6e 74 20 73 75 69 74 61  s argument suita
1f500 62 6c 65 20 66 6f 72 20 69 6e 63 6c 75 73 69 6f  ble for inclusio
1f510 6e 20 69 6e 74 6f 20 61 6e 20 53 51 4c 20 73 74  n into an SQL st
1f520 61 74 65 6d 65 6e 74 2e 0a 20 20 5e 53 74 72 69  atement..  ^Stri
1f530 6e 67 73 20 61 72 65 20 73 75 72 72 6f 75 6e 64  ngs are surround
1f540 65 64 20 62 79 20 73 69 6e 67 6c 65 2d 71 75 6f  ed by single-quo
1f550 74 65 73 20 77 69 74 68 20 65 73 63 61 70 65 73  tes with escapes
1f560 20 6f 6e 20 69 6e 74 65 72 69 6f 72 20 71 75 6f   on interior quo
1f570 74 65 73 0a 20 20 61 73 20 6e 65 65 64 65 64 2e  tes.  as needed.
1f580 20 20 5e 42 4c 4f 42 73 20 61 72 65 20 65 6e 63    ^BLOBs are enc
1f590 6f 64 65 64 20 61 73 20 68 65 78 61 64 65 63 69  oded as hexadeci
1f5a0 6d 61 6c 20 6c 69 74 65 72 61 6c 73 2e 0a 20 20  mal literals..  
1f5b0 5e 53 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d  ^Strings with em
1f5c0 62 65 64 64 65 64 20 4e 55 4c 20 63 68 61 72 61  bedded NUL chara
1f5d0 63 74 65 72 73 20 63 61 6e 6e 6f 74 20 62 65 20  cters cannot be 
1f5e0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 73  represented as s
1f5f0 74 72 69 6e 67 0a 20 20 6c 69 74 65 72 61 6c 73  tring.  literals
1f600 20 69 6e 20 53 51 4c 20 61 6e 64 20 68 65 6e 63   in SQL and henc
1f610 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 73  e the returned s
1f620 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 69 73  tring literal is
1f630 20 74 72 75 6e 63 61 74 65 64 20 70 72 69 6f 72   truncated prior
1f640 0a 20 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  .  to the first 
1f650 4e 55 4c 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20  NUL..}..funcdef 
1f660 7b 72 61 6e 64 6f 6d 28 29 7d 20 7b 7d 20 7b 0a  {random()} {} {.
1f670 20 20 5e 54 68 65 20 72 61 6e 64 6f 6d 28 29 20    ^The random() 
1f680 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1f690 20 61 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d   a pseudo-random
1f6a0 20 69 6e 74 65 67 65 72 0a 20 20 62 65 74 77 65   integer.  betwe
1f6b0 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
1f6c0 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
1f6d0 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
1f6e0 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 72 61  ..}..funcdef {ra
1f6f0 6e 64 6f 6d 62 6c 6f 62 28 4e 29 7d 20 7b 7d 20  ndomblob(N)} {} 
1f700 7b 0a 20 20 5e 54 68 65 20 72 61 6e 64 6f 6d 62  {.  ^The randomb
1f710 6c 6f 62 28 4e 29 20 66 75 6e 63 74 69 6f 6e 20  lob(N) function 
1f720 72 65 74 75 72 6e 20 61 6e 20 4e 2d 62 79 74 65  return an N-byte
1f730 20 62 6c 6f 62 20 63 6f 6e 74 61 69 6e 69 6e 67   blob containing
1f740 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 0a 20   pseudo-random. 
1f750 20 62 79 74 65 73 2e 20 5e 49 66 20 4e 20 69 73   bytes. ^If N is
1f760 20 6c 65 73 73 20 74 68 61 6e 20 31 20 74 68 65   less than 1 the
1f770 6e 20 61 20 31 2d 62 79 74 65 20 72 61 6e 64 6f  n a 1-byte rando
1f780 6d 20 62 6c 6f 62 20 69 73 20 72 65 74 75 72 6e  m blob is return
1f790 65 64 2e 0a 0a 20 20 3c 70 3e 48 69 6e 74 3a 20  ed...  <p>Hint: 
1f7a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61   applications ca
1f7b0 6e 20 67 65 6e 65 72 61 74 65 20 67 6c 6f 62 61  n generate globa
1f7c0 6c 6c 79 20 75 6e 69 71 75 65 20 69 64 65 6e 74  lly unique ident
1f7d0 69 66 69 65 72 73 0a 20 20 75 73 69 6e 67 20 74  ifiers.  using t
1f7e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 74 6f 67  his function tog
1f7f0 65 74 68 65 72 20 77 69 74 68 20 5b 68 65 78 28  ether with [hex(
1f800 29 5d 20 61 6e 64 2f 6f 72 0a 20 20 5b 6c 6f 77  )] and/or.  [low
1f810 65 72 28 29 5d 20 6c 69 6b 65 20 74 68 69 73 3a  er()] like this:
1f820 3c 2f 70 3e 0a 0a 20 20 3c 62 6c 6f 63 6b 71 75  </p>..  <blockqu
1f830 6f 74 65 3e 0a 20 20 68 65 78 28 72 61 6e 64 6f  ote>.  hex(rando
1f840 6d 62 6c 6f 62 28 31 36 29 29 3c 62 72 3e 3c 2f  mblob(16))<br></
1f850 62 72 3e 0a 20 20 6c 6f 77 65 72 28 68 65 78 28  br>.  lower(hex(
1f860 72 61 6e 64 6f 6d 62 6c 6f 62 28 31 36 29 29 29  randomblob(16)))
1f870 0a 20 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  .  </blockquote>
1f880 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 72 65 70  .}..funcdef {rep
1f890 6c 61 63 65 28 58 2c 59 2c 5a 29 7d 20 7b 7d 20  lace(X,Y,Z)} {} 
1f8a0 7b 0a 20 20 5e 54 68 65 20 72 65 70 6c 61 63 65  {.  ^The replace
1f8b0 28 58 2c 59 2c 5a 29 20 66 75 6e 63 74 69 6f 6e  (X,Y,Z) function
1f8c0 20 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e   returns a strin
1f8d0 67 20 66 6f 72 6d 65 64 20 62 79 20 73 75 62 73  g formed by subs
1f8e0 74 69 74 75 74 69 6e 67 0a 20 20 73 74 72 69 6e  tituting.  strin
1f8f0 67 20 5a 20 66 6f 72 20 65 76 65 72 79 20 6f 63  g Z for every oc
1f900 63 75 72 72 65 6e 63 65 20 6f 66 20 73 74 72 69  currence of stri
1f910 6e 67 20 59 20 69 6e 20 73 74 72 69 6e 67 20 58  ng Y in string X
1f920 2e 20 20 5e 54 68 65 20 5b 42 49 4e 41 52 59 5d  .  ^The [BINARY]
1f930 0a 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  .  collating seq
1f940 75 65 6e 63 65 20 69 73 20 75 73 65 64 20 66 6f  uence is used fo
1f950 72 20 63 6f 6d 70 61 72 69 73 6f 6e 73 2e 20 20  r comparisons.  
1f960 5e 49 66 20 59 20 69 73 20 61 6e 20 65 6d 70 74  ^If Y is an empt
1f970 79 0a 20 20 73 74 72 69 6e 67 20 74 68 65 6e 20  y.  string then 
1f980 72 65 74 75 72 6e 20 58 20 75 6e 63 68 61 6e 67  return X unchang
1f990 65 64 2e 20 20 5e 49 66 20 5a 20 69 73 20 6e 6f  ed.  ^If Z is no
1f9a0 74 20 69 6e 69 74 69 61 6c 6c 79 0a 20 20 61 20  t initially.  a 
1f9b0 73 74 72 69 6e 67 2c 20 69 74 20 69 73 20 63 61  string, it is ca
1f9c0 73 74 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  st to a UTF-8 st
1f9d0 72 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 70 72  ring prior to pr
1f9e0 6f 63 65 73 73 69 6e 67 2e 0a 7d 0a 0a 66 75 6e  ocessing..}..fun
1f9f0 63 64 65 66 20 7b 72 6f 75 6e 64 28 58 29 20 72  cdef {round(X) r
1fa00 6f 75 6e 64 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a  ound(X,Y)} {} {.
1fa10 20 20 5e 54 68 65 20 72 6f 75 6e 64 28 58 2c 59    ^The round(X,Y
1fa20 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1fa30 6e 73 20 61 20 66 6c 6f 61 74 69 6e 67 2d 70 6f  ns a floating-po
1fa40 69 6e 74 0a 20 20 76 61 6c 75 65 20 58 20 72 6f  int.  value X ro
1fa50 75 6e 64 65 64 20 74 6f 20 59 20 64 69 67 69 74  unded to Y digit
1fa60 73 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f  s to the right o
1fa70 66 20 74 68 65 20 64 65 63 69 6d 61 6c 20 70 6f  f the decimal po
1fa80 69 6e 74 2e 0a 20 20 5e 49 66 20 74 68 65 20 59  int..  ^If the Y
1fa90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6d 69   argument is omi
1faa0 74 74 65 64 2c 20 69 74 20 69 73 20 61 73 73 75  tted, it is assu
1fab0 6d 65 64 20 74 6f 20 62 65 20 30 2e 0a 7d 0a 0a  med to be 0..}..
1fac0 66 75 6e 63 64 65 66 20 7b 72 74 72 69 6d 28 58  funcdef {rtrim(X
1fad0 29 20 72 74 72 69 6d 28 58 2c 59 29 7d 20 7b 7d  ) rtrim(X,Y)} {}
1fae0 20 7b 0a 20 20 5e 54 68 65 20 72 74 72 69 6d 28   {.  ^The rtrim(
1faf0 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  X,Y) function re
1fb00 74 75 72 6e 73 20 61 20 73 74 72 69 6e 67 20 66  turns a string f
1fb10 6f 72 6d 65 64 20 62 79 20 72 65 6d 6f 76 69 6e  ormed by removin
1fb20 67 20 61 6e 79 20 61 6e 64 20 61 6c 6c 0a 20 20  g any and all.  
1fb30 63 68 61 72 61 63 74 65 72 73 20 74 68 61 74 20  characters that 
1fb40 61 70 70 65 61 72 20 69 6e 20 59 20 66 72 6f 6d  appear in Y from
1fb50 20 74 68 65 20 72 69 67 68 74 20 73 69 64 65 20   the right side 
1fb60 6f 66 20 58 2e 0a 20 20 5e 49 66 20 74 68 65 20  of X..  ^If the 
1fb70 59 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6d  Y argument is om
1fb80 69 74 74 65 64 2c 20 72 74 72 69 6d 28 58 29 20  itted, rtrim(X) 
1fb90 72 65 6d 6f 76 65 73 20 73 70 61 63 65 73 20 66  removes spaces f
1fba0 72 6f 6d 20 74 68 65 20 72 69 67 68 74 0a 20 20  rom the right.  
1fbb0 73 69 64 65 20 6f 66 20 58 2e 0a 7d 0a 0a 66 75  side of X..}..fu
1fbc0 6e 63 64 65 66 20 7b 73 6f 75 6e 64 65 78 28 58  ncdef {soundex(X
1fbd0 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 73  )} {} {.  ^The s
1fbe0 6f 75 6e 64 65 78 28 58 29 20 66 75 6e 63 74 69  oundex(X) functi
1fbf0 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 73 74 72  on returns a str
1fc00 69 6e 67 20 74 68 61 74 20 69 73 20 74 68 65 20  ing that is the 
1fc10 73 6f 75 6e 64 65 78 20 65 6e 63 6f 64 69 6e 67  soundex encoding
1fc20 20 0a 20 20 6f 66 20 74 68 65 20 73 74 72 69 6e   .  of the strin
1fc30 67 20 58 2e 0a 20 20 5e 54 68 65 20 73 74 72 69  g X..  ^The stri
1fc40 6e 67 20 22 3f 30 30 30 22 20 69 73 20 72 65 74  ng "?000" is ret
1fc50 75 72 6e 65 64 20 69 66 20 74 68 65 20 61 72 67  urned if the arg
1fc60 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 6f 72  ument is NULL or
1fc70 20 63 6f 6e 74 61 69 6e 73 0a 20 20 6e 6f 20 41   contains.  no A
1fc80 53 43 49 49 20 61 6c 70 68 61 62 65 74 69 63 20  SCII alphabetic 
1fc90 63 68 61 72 61 63 74 65 72 73 2e 0a 20 20 5e 28  characters..  ^(
1fca0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
1fcb0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 53 51   omitted from SQ
1fcc0 4c 69 74 65 20 62 79 20 64 65 66 61 75 6c 74 2e  Lite by default.
1fcd0 0a 20 20 49 74 20 69 73 20 6f 6e 6c 79 20 61 76  .  It is only av
1fce0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 5b  ailable if the [
1fcf0 53 51 4c 49 54 45 5f 53 4f 55 4e 44 45 58 5d 20  SQLITE_SOUNDEX] 
1fd00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1fd10 69 6f 6e 0a 20 20 69 73 20 75 73 65 64 20 77 68  ion.  is used wh
1fd20 65 6e 20 53 51 4c 69 74 65 20 69 73 20 62 75 69  en SQLite is bui
1fd30 6c 74 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66  lt.)^.}..funcdef
1fd40 20 7b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   {sqlite_compile
1fd50 6f 70 74 69 6f 6e 5f 67 65 74 28 4e 29 7d 20 7b  option_get(N)} {
1fd60 7d 20 7b 0a 20 20 5e 54 68 65 20 73 71 6c 69 74  } {.  ^The sqlit
1fd70 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1fd80 67 65 74 28 29 20 53 51 4c 20 66 75 6e 63 74 69  get() SQL functi
1fd90 6f 6e 20 69 73 20 61 20 77 72 61 70 70 65 72 20  on is a wrapper 
1fda0 61 72 6f 75 6e 64 20 74 68 65 0a 20 20 5b 73 71  around the.  [sq
1fdb0 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1fdc0 69 6f 6e 5f 67 65 74 28 29 5d 20 43 2f 43 2b 2b  ion_get()] C/C++
1fdd0 20 66 75 6e 63 74 69 6f 6e 2e 0a 20 20 5e 54 68   function..  ^Th
1fde0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1fdf0 6e 73 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ns the N-th comp
1fe00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1fe10 75 73 65 64 20 74 6f 20 62 75 69 6c 64 20 53 51  used to build SQ
1fe20 4c 69 74 65 0a 20 20 6f 72 20 4e 55 4c 4c 20 69  Lite.  or NULL i
1fe30 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
1fe40 6e 67 65 2e 20 20 53 65 65 20 61 6c 73 6f 20 74  nge.  See also t
1fe50 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1fe60 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 7d 0a 0a  ons pragma]..}..
1fe70 66 75 6e 63 64 65 66 20 7b 73 71 6c 69 74 65 5f  funcdef {sqlite_
1fe80 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1fe90 65 64 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  ed(X)} {} {.  ^T
1fea0 68 65 20 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  he sqlite_compil
1feb0 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 53  eoption_used() S
1fec0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
1fed0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20   wrapper around 
1fee0 74 68 65 0a 20 20 5b 73 71 6c 69 74 65 33 5f 63  the.  [sqlite3_c
1fef0 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1ff00 64 28 29 5d 20 43 2f 43 2b 2b 20 66 75 6e 63 74  d()] C/C++ funct
1ff10 69 6f 6e 2e 0a 20 20 5e 57 68 65 6e 20 74 68 65  ion..  ^When the
1ff20 20 61 72 67 75 6d 65 6e 74 20 58 20 74 6f 20 73   argument X to s
1ff30 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1ff40 69 6f 6e 5f 75 73 65 64 28 58 29 20 69 73 20 61  ion_used(X) is a
1ff50 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 20 20   string which.  
1ff60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  is the name of a
1ff70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ff80 74 69 6f 6e 2c 20 74 68 69 73 20 72 6f 75 74 69  tion, this routi
1ff90 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
1ffa0 28 31 29 20 6f 72 0a 20 20 66 61 6c 73 65 20 28  (1) or.  false (
1ffb0 30 29 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  0) depending on 
1ffc0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1ffd0 68 61 74 20 6f 70 74 69 6f 6e 20 77 61 73 20 75  hat option was u
1ffe0 73 65 64 20 64 75 72 69 6e 67 20 74 68 65 0a 20  sed during the. 
1fff0 20 62 75 69 6c 64 2e 0a 7d 0a 0a 66 75 6e 63 64   build..}..funcd
20000 65 66 20 7b 73 71 6c 69 74 65 5f 6f 66 66 73 65  ef {sqlite_offse
20010 74 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68  t(X)} {} {.  ^Th
20020 65 20 73 71 6c 69 74 65 5f 6f 66 66 73 65 74 28  e sqlite_offset(
20030 58 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  X) function retu
20040 72 6e 73 20 74 68 65 20 62 79 74 65 20 6f 66 66  rns the byte off
20050 73 65 74 20 69 6e 20 74 68 65 20 64 61 74 61 62  set in the datab
20060 61 73 65 0a 20 20 66 69 6c 65 20 66 6f 72 20 74  ase.  file for t
20070 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
20080 74 68 65 20 72 65 63 6f 72 64 20 66 72 6f 6d 20  the record from 
20090 77 68 69 63 68 20 76 61 6c 75 65 20 77 6f 75 6c  which value woul
200a0 64 20 62 65 20 72 65 61 64 2e 0a 20 20 49 66 20  d be read..  If 
200b0 58 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  X is not a colum
200c0 6e 20 69 6e 20 61 6e 20 6f 72 64 69 6e 61 72 79  n in an ordinary
200d0 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 73 71 6c   table, then sql
200e0 69 74 65 5f 6f 66 66 73 65 74 28 58 29 20 72 65  ite_offset(X) re
200f0 74 75 72 6e 73 0a 20 20 4e 55 4c 4c 2e 20 20 54  turns.  NULL.  T
20100 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
20110 64 20 62 79 20 73 71 6c 69 74 65 5f 6f 66 66 73  d by sqlite_offs
20120 65 74 28 58 29 20 6d 69 67 68 74 20 72 65 66 65  et(X) might refe
20130 72 65 6e 63 65 20 65 69 74 68 65 72 20 74 68 65  rence either the
20140 0a 20 20 6f 72 69 67 69 6e 61 6c 20 74 61 62 6c  .  original tabl
20150 65 20 6f 72 20 61 6e 20 69 6e 64 65 78 2c 20 64  e or an index, d
20160 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
20170 71 75 65 72 79 2e 20 20 49 66 20 74 68 65 20 76  query.  If the v
20180 61 6c 75 65 20 58 20 77 6f 75 6c 64 0a 20 20 6e  alue X would.  n
20190 6f 72 6d 61 6c 6c 79 20 62 65 20 65 78 74 72 61  ormally be extra
201a0 63 74 65 64 20 66 72 6f 6d 20 61 6e 20 69 6e 64  cted from an ind
201b0 65 78 2c 20 74 68 65 20 73 71 6c 69 74 65 5f 6f  ex, the sqlite_o
201c0 66 66 73 65 74 28 58 29 20 72 65 74 75 72 6e 73  ffset(X) returns
201d0 20 74 68 65 0a 20 20 6f 66 66 73 65 74 20 74 6f   the.  offset to
201e0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
201f0 6e 67 20 69 6e 64 65 78 20 72 65 63 6f 72 64 2e  ng index record.
20200 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 58    If the value X
20210 20 77 6f 75 6c 64 20 62 65 0a 20 20 65 78 74 72   would be.  extr
20220 61 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  acted from the o
20230 72 69 67 69 6e 61 6c 20 74 61 62 6c 65 2c 20 74  riginal table, t
20240 68 65 6e 20 73 71 6c 69 74 65 5f 6f 66 66 73 65  hen sqlite_offse
20250 74 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  t(X) returns the
20260 20 6f 66 66 73 65 74 0a 20 20 74 6f 20 74 68 65   offset.  to the
20270 20 74 61 62 6c 65 20 72 65 63 6f 72 64 2e 0a 0a   table record...
20280 20 20 3c 70 3e 54 68 65 20 73 71 6c 69 74 65 5f    <p>The sqlite_
20290 6f 66 66 73 65 74 28 58 29 20 53 51 4c 20 66 75  offset(X) SQL fu
202a0 6e 63 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  nction is only a
202b0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
202c0 74 65 20 69 73 20 62 75 69 6c 74 0a 20 20 75 73  te is built.  us
202d0 69 6e 67 20 74 68 65 20 5b 2d 44 53 51 4c 49 54  ing the [-DSQLIT
202e0 45 5f 45 4e 41 42 4c 45 5f 4f 46 46 53 45 54 5f  E_ENABLE_OFFSET_
202f0 53 51 4c 5f 46 55 4e 43 5d 20 63 6f 6d 70 69 6c  SQL_FUNC] compil
20300 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 7d  e-time option..}
20310 0a 0a 66 75 6e 63 64 65 66 20 7b 73 71 6c 69 74  ..funcdef {sqlit
20320 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 7d 20 7b  e_source_id()} {
20330 7d 20 7b 0a 20 20 5e 54 68 65 20 73 71 6c 69 74  } {.  ^The sqlit
20340 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 20 66 75  e_source_id() fu
20350 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
20360 20 73 74 72 69 6e 67 20 74 68 61 74 20 69 64 65   string that ide
20370 6e 74 69 66 69 65 73 20 74 68 65 0a 20 20 73 70  ntifies the.  sp
20380 65 63 69 66 69 63 20 76 65 72 73 69 6f 6e 20 6f  ecific version o
20390 66 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64  f the source cod
203a0 65 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  e that was used 
203b0 74 6f 20 62 75 69 6c 64 20 74 68 65 20 53 51 4c  to build the SQL
203c0 69 74 65 0a 20 20 6c 69 62 72 61 72 79 2e 20 20  ite.  library.  
203d0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
203e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 5f 73  rned by sqlite_s
203f0 6f 75 72 63 65 5f 69 64 28 29 20 69 73 0a 20 20  ource_id() is.  
20400 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d  the date and tim
20410 65 20 74 68 61 74 20 74 68 65 20 73 6f 75 72 63  e that the sourc
20420 65 20 63 6f 64 65 20 77 61 73 20 63 68 65 63 6b  e code was check
20430 65 64 20 69 6e 20 66 6f 6c 6c 6f 77 65 64 20 62  ed in followed b
20440 79 0a 20 20 74 68 65 20 53 48 41 31 20 68 61 73  y.  the SHA1 has
20450 68 20 66 6f 72 20 74 68 61 74 20 63 68 65 63 6b  h for that check
20460 2d 69 6e 2e 20 20 5e 54 68 69 73 20 66 75 6e 63  -in.  ^This func
20470 74 69 6f 6e 20 69 73 0a 20 20 61 6e 20 53 51 4c  tion is.  an SQL
20480 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20   wrapper around 
20490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  the [sqlite3_sou
204a0 72 63 65 69 64 28 29 5d 20 43 20 69 6e 74 65 72  rceid()] C inter
204b0 66 61 63 65 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66  face..}..funcdef
204c0 20 7b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   {sqlite_version
204d0 28 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20  ()} {} {.  ^The 
204e0 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
204f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
20500 73 20 74 68 65 20 76 65 72 73 69 6f 6e 20 73 74  s the version st
20510 72 69 6e 67 20 66 6f 72 20 74 68 65 20 53 51 4c  ring for the SQL
20520 69 74 65 0a 20 20 6c 69 62 72 61 72 79 20 74 68  ite.  library th
20530 61 74 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  at is running.  
20540 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  ^This function i
20550 73 20 61 6e 20 53 51 4c 0a 20 20 77 72 61 70 70  s an SQL.  wrapp
20560 65 72 20 61 72 6f 75 6e 64 20 74 68 65 20 5b 73  er around the [s
20570 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
20580 6e 28 29 5d 20 43 2d 69 6e 74 65 72 66 61 63 65  n()] C-interface
20590 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 73 75  ..}..funcdef {su
205a0 62 73 74 72 28 58 2c 59 2c 5a 29 20 73 75 62 73  bstr(X,Y,Z) subs
205b0 74 72 28 58 2c 59 29 7d 20 7b 7d 20 7b 0a 20 20  tr(X,Y)} {} {.  
205c0 5e 54 68 65 20 73 75 62 73 74 72 28 58 2c 59 2c  ^The substr(X,Y,
205d0 5a 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  Z) function retu
205e0 72 6e 73 20 61 20 73 75 62 73 74 72 69 6e 67 20  rns a substring 
205f0 6f 66 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  of input string 
20600 58 20 74 68 61 74 20 62 65 67 69 6e 73 0a 20 20  X that begins.  
20610 77 69 74 68 20 74 68 65 20 59 2d 74 68 20 63 68  with the Y-th ch
20620 61 72 61 63 74 65 72 20 61 6e 64 20 77 68 69 63  aracter and whic
20630 68 20 69 73 20 5a 20 63 68 61 72 61 63 74 65 72  h is Z character
20640 73 20 6c 6f 6e 67 2e 0a 20 20 5e 49 66 20 5a 20  s long..  ^If Z 
20650 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 6e 20  is omitted then 
20660 73 75 62 73 74 72 28 58 2c 59 29 20 72 65 74 75  substr(X,Y) retu
20670 72 6e 73 20 61 6c 6c 20 63 68 61 72 61 63 74 65  rns all characte
20680 72 73 20 74 68 72 6f 75 67 68 20 74 68 65 20 65  rs through the e
20690 6e 64 0a 20 20 6f 66 20 74 68 65 20 73 74 72 69  nd.  of the stri
206a0 6e 67 20 58 20 62 65 67 69 6e 6e 69 6e 67 20 77  ng X beginning w
206b0 69 74 68 20 74 68 65 20 59 2d 74 68 2e 0a 20 20  ith the Y-th..  
206c0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
206d0 68 61 72 61 63 74 65 72 20 6f 66 20 58 20 69 73  haracter of X is
206e0 20 6e 75 6d 62 65 72 20 31 2e 20 20 5e 49 66 20   number 1.  ^If 
206f0 59 20 69 73 20 6e 65 67 61 74 69 76 65 0a 20 20  Y is negative.  
20700 74 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 63  then the first c
20710 68 61 72 61 63 74 65 72 20 6f 66 20 74 68 65 20  haracter of the 
20720 73 75 62 73 74 72 69 6e 67 20 69 73 20 66 6f 75  substring is fou
20730 6e 64 20 62 79 20 63 6f 75 6e 74 69 6e 67 20 66  nd by counting f
20740 72 6f 6d 20 74 68 65 0a 20 20 72 69 67 68 74 20  rom the.  right 
20750 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 65 20  rather than the 
20760 6c 65 66 74 2e 20 20 5e 49 66 20 5a 20 69 73 20  left.  ^If Z is 
20770 6e 65 67 61 74 69 76 65 20 74 68 65 6e 0a 20 20  negative then.  
20780 74 68 65 20 61 62 73 28 5a 29 20 63 68 61 72 61  the abs(Z) chara
20790 63 74 65 72 73 20 70 72 65 63 65 64 69 6e 67 20  cters preceding 
207a0 74 68 65 20 59 2d 74 68 20 63 68 61 72 61 63 74  the Y-th charact
207b0 65 72 20 61 72 65 20 72 65 74 75 72 6e 65 64 2e  er are returned.
207c0 0a 20 20 5e 49 66 20 58 20 69 73 20 61 20 73 74  .  ^If X is a st
207d0 72 69 6e 67 20 74 68 65 6e 20 63 68 61 72 61 63  ring then charac
207e0 74 65 72 73 20 69 6e 64 69 63 65 73 20 72 65 66  ters indices ref
207f0 65 72 20 74 6f 20 61 63 74 75 61 6c 20 55 54 46  er to actual UTF
20800 2d 38 20 0a 20 20 63 68 61 72 61 63 74 65 72 73  -8 .  characters
20810 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 42 4c  .  ^If X is a BL
20820 4f 42 20 74 68 65 6e 20 74 68 65 20 69 6e 64 69  OB then the indi
20830 63 65 73 20 72 65 66 65 72 20 74 6f 20 62 79 74  ces refer to byt
20840 65 73 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b  es..}..funcdef {
20850 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 7d  total_changes()}
20860 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 74 6f 74   {} {.  ^The tot
20870 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
20880 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
20890 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
208a0 63 68 61 6e 67 65 73 0a 20 20 63 61 75 73 65 64  changes.  caused
208b0 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
208c0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 20 20 73  TE or DELETE.  s
208d0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
208e0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
208f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20900 77 61 73 20 6f 70 65 6e 65 64 2e 0a 20 20 5e 54  was opened..  ^T
20910 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
20920 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
20930 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
20940 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 20  tal_changes()]. 
20950 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65   C/C++ interface
20960 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 74 72  ..}..funcdef {tr
20970 69 6d 28 58 29 20 74 72 69 6d 28 58 2c 59 29 7d  im(X) trim(X,Y)}
20980 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 74 72 69   {} {.  ^The tri
20990 6d 28 58 2c 59 29 20 66 75 6e 63 74 69 6f 6e 20  m(X,Y) function 
209a0 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e 67  returns a string
209b0 20 66 6f 72 6d 65 64 20 62 79 20 72 65 6d 6f 76   formed by remov
209c0 69 6e 67 20 61 6e 79 20 61 6e 64 20 61 6c 6c 0a  ing any and all.
209d0 20 20 63 68 61 72 61 63 74 65 72 73 20 74 68 61    characters tha
209e0 74 20 61 70 70 65 61 72 20 69 6e 20 59 20 66 72  t appear in Y fr
209f0 6f 6d 20 62 6f 74 68 20 65 6e 64 73 20 6f 66 20  om both ends of 
20a00 58 2e 0a 20 20 5e 49 66 20 74 68 65 20 59 20 61  X..  ^If the Y a
20a10 72 67 75 6d 65 6e 74 20 69 73 20 6f 6d 69 74 74  rgument is omitt
20a20 65 64 2c 20 74 72 69 6d 28 58 29 20 72 65 6d 6f  ed, trim(X) remo
20a30 76 65 73 20 73 70 61 63 65 73 20 66 72 6f 6d 20  ves spaces from 
20a40 62 6f 74 68 20 65 6e 64 73 20 6f 66 20 58 2e 0a  both ends of X..
20a50 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 74 79 70 65  }..funcdef {type
20a60 6f 66 28 58 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54  of(X)} {} {.  ^T
20a70 68 65 20 74 79 70 65 6f 66 28 58 29 20 66 75 6e  he typeof(X) fun
20a80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
20a90 73 74 72 69 6e 67 20 74 68 61 74 20 69 6e 64 69  string that indi
20aa0 63 61 74 65 73 20 74 68 65 20 5b 64 61 74 61 74  cates the [datat
20ab0 79 70 65 5d 20 6f 66 0a 20 20 74 68 65 20 65 78  ype] of.  the ex
20ac0 70 72 65 73 73 69 6f 6e 20 58 3a 20 22 6e 75 6c  pression X: "nul
20ad0 6c 22 2c 20 22 69 6e 74 65 67 65 72 22 2c 20 22  l", "integer", "
20ae0 72 65 61 6c 22 2c 20 22 74 65 78 74 22 2c 20 6f  real", "text", o
20af0 72 20 22 62 6c 6f 62 22 2e 0a 7d 0a 0a 66 75 6e  r "blob"..}..fun
20b00 63 64 65 66 20 7b 75 6e 6c 69 6b 65 6c 79 28 58  cdef {unlikely(X
20b10 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 75  )} {} {.  ^The u
20b20 6e 6c 69 6b 65 6c 79 28 58 29 20 66 75 6e 63 74  nlikely(X) funct
20b30 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
20b40 61 72 67 75 6d 65 6e 74 20 58 20 75 6e 63 68 61  argument X uncha
20b50 6e 67 65 64 2e 0a 20 20 5e 54 68 65 20 75 6e 6c  nged..  ^The unl
20b60 69 6b 65 6c 79 28 58 29 20 66 75 6e 63 74 69 6f  ikely(X) functio
20b70 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 74 68 61  n is a no-op tha
20b80 74 20 74 68 65 20 63 6f 64 65 20 67 65 6e 65 72  t the code gener
20b90 61 74 6f 72 0a 20 20 6f 70 74 69 6d 69 7a 65 73  ator.  optimizes
20ba0 20 61 77 61 79 20 73 6f 20 74 68 61 74 20 69 74   away so that it
20bb0 20 63 6f 6e 73 75 6d 65 73 20 6e 6f 20 43 50 55   consumes no CPU
20bc0 20 63 79 63 6c 65 73 20 61 74 0a 20 20 72 75 6e   cycles at.  run
20bd0 2d 74 69 6d 65 20 28 74 68 61 74 20 69 73 2c 20  -time (that is, 
20be0 64 75 72 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  during calls to 
20bf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20c00 29 2e 0a 20 20 5e 54 68 65 20 70 75 72 70 6f 73  )..  ^The purpos
20c10 65 20 6f 66 20 74 68 65 20 75 6e 6c 69 6b 65 6c  e of the unlikel
20c20 79 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  y(X) function is
20c30 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 68 69   to provide a hi
20c40 6e 74 0a 20 20 74 6f 20 74 68 65 20 71 75 65 72  nt.  to the quer
20c50 79 20 70 6c 61 6e 6e 65 72 20 74 68 61 74 20 74  y planner that t
20c60 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 73  he argument X is
20c70 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
20c80 0a 20 20 74 68 61 74 20 69 73 20 75 73 75 61 6c  .  that is usual
20c90 6c 79 20 6e 6f 74 20 74 72 75 65 2e 20 5e 28 54  ly not true. ^(T
20ca0 68 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 66  he unlikely(X) f
20cb0 75 6e 63 74 69 6f 6e 20 69 73 20 65 71 75 69 76  unction is equiv
20cc0 61 6c 65 6e 74 0a 20 20 74 6f 20 5b 6c 69 6b 65  alent.  to [like
20cd0 6c 69 68 6f 6f 64 5d 28 58 2c 20 30 2e 30 36 32  lihood](X, 0.062
20ce0 35 29 2e 29 5e 0a 7d 0a 0a 66 75 6e 63 64 65 66  5).)^.}..funcdef
20cf0 20 7b 75 6e 69 63 6f 64 65 28 58 29 7d 20 7b 7d   {unicode(X)} {}
20d00 20 7b 0a 20 20 5e 54 68 65 20 75 6e 69 63 6f 64   {.  ^The unicod
20d10 65 28 58 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(X) function re
20d20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
20d30 63 20 75 6e 69 63 6f 64 65 20 63 6f 64 65 20 70  c unicode code p
20d40 6f 69 6e 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  oint correspondi
20d50 6e 67 20 74 6f 0a 20 20 74 68 65 20 66 69 72 73  ng to.  the firs
20d60 74 20 63 68 61 72 61 63 74 65 72 20 6f 66 20 74  t character of t
20d70 68 65 20 73 74 72 69 6e 67 20 58 2e 20 20 49 66  he string X.  If
20d80 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
20d90 20 75 6e 69 63 6f 64 65 28 58 29 20 69 73 20 6e   unicode(X) is n
20da0 6f 74 20 61 20 73 74 72 69 6e 67 0a 20 20 74 68  ot a string.  th
20db0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  en the result is
20dc0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 7d 0a 0a 66   undefined..}..f
20dd0 75 6e 63 64 65 66 20 7b 75 70 70 65 72 28 58 29  uncdef {upper(X)
20de0 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20 75 70  } {} {.  ^The up
20df0 70 65 72 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  per(X) function 
20e00 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
20e10 66 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 58  f input string X
20e20 20 69 6e 20 77 68 69 63 68 20 61 6c 6c 20 0a 20   in which all . 
20e30 20 6c 6f 77 65 72 2d 63 61 73 65 20 41 53 43 49   lower-case ASCI
20e40 49 20 63 68 61 72 61 63 74 65 72 73 20 61 72 65  I characters are
20e50 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 74 68   converted to th
20e60 65 69 72 20 75 70 70 65 72 2d 63 61 73 65 20 65  eir upper-case e
20e70 71 75 69 76 61 6c 65 6e 74 2e 0a 7d 0a 0a 66 75  quivalent..}..fu
20e80 6e 63 64 65 66 20 7b 7a 65 72 6f 62 6c 6f 62 28  ncdef {zeroblob(
20e90 4e 29 7d 20 7b 7d 20 7b 0a 20 20 5e 54 68 65 20  N)} {} {.  ^The 
20ea0 7a 65 72 6f 62 6c 6f 62 28 4e 29 20 66 75 6e 63  zeroblob(N) func
20eb0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 42  tion returns a B
20ec0 4c 4f 42 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f  LOB consisting o
20ed0 66 20 4e 20 62 79 74 65 73 20 6f 66 20 30 78 30  f N bytes of 0x0
20ee0 30 2e 0a 20 20 53 51 4c 69 74 65 20 6d 61 6e 61  0..  SQLite mana
20ef0 67 65 73 20 74 68 65 73 65 20 7a 65 72 6f 62 6c  ges these zerobl
20f00 6f 62 73 20 76 65 72 79 20 65 66 66 69 63 69 65  obs very efficie
20f10 6e 74 6c 79 2e 20 20 5a 65 72 6f 62 6c 6f 62 73  ntly.  Zeroblobs
20f20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 0a   can be used to.
20f30 20 20 72 65 73 65 72 76 65 20 73 70 61 63 65 20    reserve space 
20f40 66 6f 72 20 61 20 42 4c 4f 42 20 74 68 61 74 20  for a BLOB that 
20f50 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
20f60 20 75 73 69 6e 67 20 0a 20 20 5b 73 71 6c 69 74   using .  [sqlit
20f70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 20 7c  e3_blob_open() |
20f80 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
20f90 42 20 49 2f 4f 5d 2e 0a 20 20 5e 54 68 69 73 20  B I/O]..  ^This 
20fa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
20fb0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e  implemented usin
20fc0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  g the [sqlite3_r
20fd0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
20fe0 5d 0a 20 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  ].  routine from
20ff0 20 74 68 65 20 43 2f 43 2b 2b 20 69 6e 74 65 72   the C/C++ inter
21000 66 61 63 65 2e 0a 7d 0a 3c 2f 74 63 6c 3e 0a 0a  face..}.</tcl>..
21010 3c 70 3e 54 68 65 20 63 6f 72 65 20 66 75 6e 63  <p>The core func
21020 74 69 6f 6e 73 20 73 68 6f 77 6e 20 62 65 6c 6f  tions shown belo
21030 77 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  w are available 
21040 62 79 20 64 65 66 61 75 6c 74 2e 20 0a 5b 64 61  by default. .[da
21050 74 65 66 75 6e 63 20 7c 20 44 61 74 65 20 26 61  tefunc | Date &a
21060 6d 70 3b 20 54 69 6d 65 20 66 75 6e 63 74 69 6f  mp; Time functio
21070 6e 73 5d 2c 0a 5b 61 67 67 66 75 6e 63 20 7c 20  ns],.[aggfunc | 
21080 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
21090 6f 6e 73 5d 2c 0a 5b 62 75 69 6c 74 69 6e 20 77  ons],.[builtin w
210a0 69 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73 7c  indow functions|
210b0 77 69 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73  window functions
210c0 5d 2c 20 61 6e 64 0a 5b 6a 73 6f 6e 31 20 7c 20  ], and.[json1 | 
210d0 4a 53 4f 4e 20 66 75 6e 63 74 69 6f 6e 73 5d 20  JSON functions] 
210e0 61 72 65 20 64 6f 63 75 6d 65 6e 74 65 64 20 73  are documented s
210f0 65 70 61 72 61 74 65 6c 79 2e 20 20 41 6e 0a 61  eparately.  An.a
21100 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 64  pplication may d
21110 65 66 69 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  efine additional
21120 0a 66 75 6e 63 74 69 6f 6e 73 20 77 72 69 74 74  .functions writt
21130 65 6e 20 69 6e 20 43 20 61 6e 64 20 61 64 64 65  en in C and adde
21140 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
21150 65 20 65 6e 67 69 6e 65 20 75 73 69 6e 67 0a 74  e engine using.t
21160 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
21170 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 41  te_function()] A
21180 50 49 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 0a 73  PI.</p>..<tcl>.s
21190 65 74 20 6c 78 20 7b 7d 0a 66 6f 72 65 61 63 68  et lx {}.foreach
211a0 20 62 61 73 65 73 79 6e 74 61 78 20 5b 61 72 72   basesyntax [arr
211b0 61 79 20 6e 61 6d 65 73 20 63 6f 72 65 66 75 6e  ay names corefun
211c0 63 73 65 74 5d 20 7b 0a 20 20 66 6f 72 65 61 63  cset] {.  foreac
211d0 68 20 7b 73 79 6e 74 61 78 20 6b 65 79 77 6f 72  h {syntax keywor
211e0 64 73 20 64 65 73 63 7d 20 24 63 6f 72 65 66 75  ds desc} $corefu
211f0 6e 63 73 65 74 28 24 62 61 73 65 73 79 6e 74 61  ncset($basesynta
21200 78 29 20 62 72 65 61 6b 0a 20 20 72 65 67 65 78  x) break.  regex
21210 70 20 7b 5e 5b 61 2d 7a 5f 5d 2b 7d 20 24 62 61  p {^[a-z_]+} $ba
21220 73 65 73 79 6e 74 61 78 20 66 72 61 67 6d 65 6e  sesyntax fragmen
21230 74 0a 20 20 66 6f 72 65 61 63 68 20 63 6f 72 65  t.  foreach core
21240 73 79 6e 74 61 78 20 24 73 79 6e 74 61 78 20 7b  syntax $syntax {
21250 0a 20 20 20 20 6c 61 70 70 65 6e 64 20 6c 78 20  .    lappend lx 
21260 5b 6c 69 73 74 20 24 66 72 61 67 6d 65 6e 74 20  [list $fragment 
21270 24 63 6f 72 65 73 79 6e 74 61 78 20 30 5d 0a 20  $coresyntax 0]. 
21280 20 7d 0a 7d 0a 68 64 5f 6c 69 73 74 5f 6f 66 5f   }.}.hd_list_of_
21290 6c 69 6e 6b 73 20 7b 7d 20 32 32 35 20 5b 6c 73  links {} 225 [ls
212a0 6f 72 74 20 2d 69 6e 64 65 78 20 31 20 24 6c 78  ort -index 1 $lx
212b0 5d 0a 0a 68 64 5f 70 75 74 73 6e 6c 20 22 3c 68  ]..hd_putsnl "<h
212c0 72 20 63 6c 61 73 73 3d 27 78 68 72 27 3e 22 0a  r class='xhr'>".
212d0 68 64 5f 70 75 74 73 6e 6c 20 22 3c 64 6c 3e 22  hd_putsnl "<dl>"
212e0 0a 66 6f 72 65 61 63 68 20 62 61 73 65 73 79 6e  .foreach basesyn
212f0 74 61 78 20 5b 6c 73 6f 72 74 20 5b 61 72 72 61  tax [lsort [arra
21300 79 20 6e 61 6d 65 73 20 63 6f 72 65 66 75 6e 63  y names corefunc
21310 73 65 74 5d 5d 20 7b 0a 20 20 66 6f 72 65 61 63  set]] {.  foreac
21320 68 20 7b 73 79 6e 74 61 78 20 6b 65 79 77 6f 72  h {syntax keywor
21330 64 73 20 64 65 73 63 7d 20 24 63 6f 72 65 66 75  ds desc} $corefu
21340 6e 63 73 65 74 28 24 62 61 73 65 73 79 6e 74 61  ncset($basesynta
21350 78 29 20 62 72 65 61 6b 0a 20 20 72 65 67 73 75  x) break.  regsu
21360 62 20 2d 61 6c 6c 20 7b 5c 73 2b 7d 20 5b 73 74  b -all {\s+} [st
21370 72 69 6e 67 20 74 72 69 6d 20 24 73 79 6e 74 61  ring trim $synta
21380 78 5d 20 7b 3c 62 72 20 2f 3e 7d 20 73 79 6e 74  x] {<br />} synt
21390 61 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c 6c  ax.  regsub -all
213a0 20 7b 5c 28 28 5b 5e 2a 29 5d 2b 29 5c 29 7d 20   {\(([^*)]+)\)} 
213b0 24 73 79 6e 74 61 78 20 7b 28 3c 69 3e 5c 31 3c  $syntax {(<i>\1<
213c0 2f 69 3e 29 7d 20 73 79 6e 74 61 78 0a 20 20 72  /i>)} syntax.  r
213d0 65 67 73 75 62 20 2d 61 6c 6c 20 7b 2c 7d 20 24  egsub -all {,} $
213e0 73 79 6e 74 61 78 20 7b 3c 2f 69 3e 2c 3c 69 3e  syntax {</i>,<i>
213f0 7d 20 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75  } syntax.  regsu
21400 62 20 2d 61 6c 6c 20 7b 3c 69 3e 5c 2e 5c 2e 5c  b -all {<i>\.\.\
21410 2e 3c 2f 69 3e 7d 20 24 73 79 6e 74 61 78 20 7b  .</i>} $syntax {
21420 2e 2e 2e 7d 20 73 79 6e 74 61 78 0a 20 20 72 65  ...} syntax.  re
21430 67 65 78 70 20 7b 5e 5b 61 2d 7a 5d 2b 7d 20 24  gexp {^[a-z]+} $
21440 62 61 73 65 73 79 6e 74 61 78 20 66 72 61 67 6d  basesyntax fragm
21450 65 6e 74 0a 20 20 69 66 20 7b 5b 6c 6c 65 6e 67  ent.  if {[lleng
21460 74 68 20 24 6b 65 79 77 6f 72 64 73 5d 3d 3d 30  th $keywords]==0
21470 7d 20 7b 0a 20 20 20 20 72 65 67 65 78 70 20 7b  } {.    regexp {
21480 5b 61 2d 7a 5f 5d 2b 7d 20 24 73 79 6e 74 61 78  [a-z_]+} $syntax
21490 20 6e 61 6d 65 0a 20 20 20 20 68 64 5f 66 72 61   name.    hd_fra
214a0 67 6d 65 6e 74 20 24 6e 61 6d 65 20 2a 24 6e 61  gment $name *$na
214b0 6d 65 20 22 24 7b 6e 61 6d 65 7d 28 29 20 53 51  me "${name}() SQ
214c0 4c 20 66 75 6e 63 74 69 6f 6e 22 0a 20 20 7d 20  L function".  } 
214d0 65 6c 73 65 20 7b 0a 20 20 20 20 73 65 74 20 66  else {.    set f
214e0 72 61 67 6e 61 6d 65 20 5b 6c 69 6e 64 65 78 20  ragname [lindex 
214f0 24 6b 65 79 77 6f 72 64 73 20 30 5d 0a 20 20 20  $keywords 0].   
21500 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5b 5e   regsub -all {[^
21510 61 2d 7a 5d 7d 20 24 66 72 61 67 6e 61 6d 65 20  a-z]} $fragname 
21520 7b 7d 20 66 72 61 67 6e 61 6d 65 0a 20 20 20 20  {} fragname.    
21530 68 64 5f 66 72 61 67 6d 65 6e 74 20 24 66 72 61  hd_fragment $fra
21540 67 6e 61 6d 65 0a 20 20 20 20 65 76 61 6c 20 68  gname.    eval h
21550 64 5f 6b 65 79 77 6f 72 64 73 20 5b 73 74 72 69  d_keywords [stri
21560 6e 67 20 6d 61 70 20 7b 5c 6e 20 7b 20 7d 7d 20  ng map {\n { }} 
21570 24 6b 65 79 77 6f 72 64 73 5d 0a 20 20 7d 0a 20  $keywords].  }. 
21580 20 68 64 5f 70 75 74 73 20 22 3c 64 74 3e 3c 70   hd_puts "<dt><p
21590 3e 3c 62 3e 24 73 79 6e 74 61 78 3c 2f 62 3e 3c  ><b>$syntax</b><
215a0 2f 64 74 3e 22 0a 20 20 68 64 5f 72 65 73 6f 6c  /dt>".  hd_resol
215b0 76 65 20 22 3c 64 64 3e 3c 70 3e 24 64 65 73 63  ve "<dd><p>$desc
215c0 3c 2f 64 64 3e 5c 6e 22 0a 7d 0a 68 64 5f 70 75  </dd>\n".}.hd_pu
215d0 74 73 6e 6c 20 22 3c 2f 64 6c 3e 22 0a 0a 23 23  tsnl "</dl>"..##
215e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
215f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
21600 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
21610 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
21620 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65 63  ############.Sec
21630 74 69 6f 6e 20 7b 44 61 74 65 20 41 6e 64 20 54  tion {Date And T
21640 69 6d 65 20 46 75 6e 63 74 69 6f 6e 73 7d 20 64  ime Functions} d
21650 61 74 65 66 75 6e 63 20 7b 2a 64 61 74 65 66 75  atefunc {*datefu
21660 6e 63 20 7b 64 61 74 65 20 61 6e 64 20 74 69 6d  nc {date and tim
21670 65 20 66 75 6e 63 74 69 6f 6e 73 7d 7d 0a 68 64  e functions}}.hd
21680 5f 6b 65 79 77 6f 72 64 73 20 7b 64 61 74 65 28  _keywords {date(
21690 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 20  ) SQL function} 
216a0 7b 74 69 6d 65 28 29 20 53 51 4c 20 66 75 6e 63  {time() SQL func
216b0 74 69 6f 6e 7d 0a 68 64 5f 6b 65 79 77 6f 72 64  tion}.hd_keyword
216c0 73 20 7b 64 61 74 65 74 69 6d 65 28 29 20 53 51  s {datetime() SQ
216d0 4c 20 66 75 6e 63 74 69 6f 6e 7d 20 7b 6a 75 6c  L function} {jul
216e0 69 61 6e 64 61 79 28 29 20 53 51 4c 20 66 75 6e  ianday() SQL fun
216f0 63 74 69 6f 6e 7d 0a 68 64 5f 6b 65 79 77 6f 72  ction}.hd_keywor
21700 64 73 20 7b 73 74 72 66 74 69 6d 65 28 29 20 53  ds {strftime() S
21710 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 3c 2f 74  QL function}.</t
21720 63 6c 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20  cl>..<p>.SQLite 
21730 73 75 70 70 6f 72 74 73 20 66 69 76 65 20 64 61  supports five da
21740 74 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e 63  te and time func
21750 74 69 6f 6e 73 20 61 73 20 66 6f 6c 6c 6f 77 73  tions as follows
21760 3a 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 3c 6f 6c 3e  :.</p>..<p>.<ol>
21770 0a 3c 6c 69 3e 20 5e 28 3c 62 3e 64 61 74 65 28  .<li> ^(<b>date(
21780 3c 2f 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69 6e  </b><i>timestrin
21790 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64  g, modifier, mod
217a0 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62  ifier, ...</i><b
217b0 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c  >)</b>)^ </li>.<
217c0 6c 69 3e 20 5e 28 3c 62 3e 74 69 6d 65 28 3c 2f  li> ^(<b>time(</
217d0 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69 6e 67 2c  b><i>timestring,
217e0 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64 69 66   modifier, modif
217f0 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29  ier, ...</i><b>)
21800 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 6c 69  </b>)^ </li>.<li
21810 3e 20 5e 28 3c 62 3e 64 61 74 65 74 69 6d 65 28  > ^(<b>datetime(
21820 3c 2f 62 3e 3c 69 3e 74 69 6d 65 73 74 72 69 6e  </b><i>timestrin
21830 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64  g, modifier, mod
21840 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62  ifier, ...</i><b
21850 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c  >)</b>)^ </li>.<
21860 6c 69 3e 20 5e 28 3c 62 3e 6a 75 6c 69 61 6e 64  li> ^(<b>juliand
21870 61 79 28 3c 2f 62 3e 3c 69 3e 74 69 6d 65 73 74  ay(</b><i>timest
21880 72 69 6e 67 2c 20 6d 6f 64 69 66 69 65 72 2c 20  ring, modifier, 
21890 6d 6f 64 69 66 69 65 72 2c 20 2e 2e 2e 3c 2f 69  modifier, ...</i
218a0 3e 3c 62 3e 29 3c 2f 62 3e 29 5e 20 3c 2f 6c 69  ><b>)</b>)^ </li
218b0 3e 0a 3c 6c 69 3e 20 5e 28 3c 62 3e 73 74 72 66  >.<li> ^(<b>strf
218c0 74 69 6d 65 28 3c 2f 62 3e 3c 69 3e 66 6f 72 6d  time(</b><i>form
218d0 61 74 2c 20 74 69 6d 65 73 74 72 69 6e 67 2c 20  at, timestring, 
218e0 6d 6f 64 69 66 69 65 72 2c 20 6d 6f 64 69 66 69  modifier, modifi
218f0 65 72 2c 20 2e 2e 2e 3c 2f 69 3e 3c 62 3e 29 3c  er, ...</i><b>)<
21900 2f 62 3e 29 5e 20 3c 2f 6c 69 3e 0a 3c 2f 6f 6c  /b>)^ </li>.</ol
21910 3e 0a 0a 3c 70 3e 0a 5e 41 6c 6c 20 66 69 76 65  >..<p>.^All five
21920 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 66   date and time f
21930 75 6e 63 74 69 6f 6e 73 20 74 61 6b 65 20 61 20  unctions take a 
21940 74 69 6d 65 20 73 74 72 69 6e 67 20 61 73 20 61  time string as a
21950 6e 20 61 72 67 75 6d 65 6e 74 2e 20 0a 5e 54 68  n argument. .^Th
21960 65 20 74 69 6d 65 20 73 74 72 69 6e 67 20 69 73  e time string is
21970 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72   followed by zer
21980 6f 20 6f 72 20 6d 6f 72 65 20 6d 6f 64 69 66 69  o or more modifi
21990 65 72 73 2e 20 0a 5e 54 68 65 20 73 74 72 66 74  ers. .^The strft
219a0 69 6d 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ime() function a
219b0 6c 73 6f 20 74 61 6b 65 73 20 61 20 66 6f 72 6d  lso takes a form
219c0 61 74 20 73 74 72 69 6e 67 20 61 73 20 69 74 73  at string as its
219d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
219e0 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 64  .</p>..<p>.The d
219f0 61 74 65 20 61 6e 64 20 74 69 6d 65 20 66 75 6e  ate and time fun
21a00 63 74 69 6f 6e 73 20 75 73 65 20 61 20 73 75 62  ctions use a sub
21a10 73 65 74 20 6f 66 0a 5b 68 74 74 70 3a 2f 2f 65  set of.[http://e
21a20 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f  n.wikipedia.org/
21a30 77 69 6b 69 2f 49 53 4f 5f 38 36 30 31 20 7c 20  wiki/ISO_8601 | 
21a40 49 53 30 2d 38 36 30 31 5d 20 64 61 74 65 20 61  IS0-8601] date a
21a50 6e 64 20 74 69 6d 65 0a 66 6f 72 6d 61 74 73 2e  nd time.formats.
21a60 0a 5e 54 68 65 20 64 61 74 65 28 29 20 66 75 6e  .^The date() fun
21a70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
21a80 65 20 64 61 74 65 20 69 6e 20 74 68 69 73 20 66  e date in this f
21a90 6f 72 6d 61 74 3a 20 59 59 59 59 2d 4d 4d 2d 44  ormat: YYYY-MM-D
21aa0 44 2e 20 0a 5e 54 68 65 20 74 69 6d 65 28 29 20  D. .^The time() 
21ab0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
21ac0 20 74 68 65 20 74 69 6d 65 20 61 73 20 48 48 3a   the time as HH:
21ad0 4d 4d 3a 53 53 2e 20 0a 5e 54 68 65 20 64 61 74  MM:SS. .^The dat
21ae0 65 74 69 6d 65 28 29 20 66 75 6e 63 74 69 6f 6e  etime() function
21af0 20 72 65 74 75 72 6e 73 20 22 59 59 59 59 2d 4d   returns "YYYY-M
21b00 4d 2d 44 44 20 48 48 3a 4d 4d 3a 53 53 22 2e 20  M-DD HH:MM:SS". 
21b10 0a 5e 28 54 68 65 20 6a 75 6c 69 61 6e 64 61 79  .^(The julianday
21b20 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
21b30 72 6e 73 20 74 68 65 20 0a 5b 68 74 74 70 3a 2f  rns the .[http:/
21b40 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72  /en.wikipedia.or
21b50 67 2f 77 69 6b 69 2f 4a 75 6c 69 61 6e 5f 64 61  g/wiki/Julian_da
21b60 79 20 7c 20 4a 75 6c 69 61 6e 20 64 61 79 5d 20  y | Julian day] 
21b70 2d 20 74 68 65 0a 6e 75 6d 62 65 72 20 6f 66 20  - the.number of 
21b80 64 61 79 73 20 73 69 6e 63 65 20 6e 6f 6f 6e 20  days since noon 
21b90 69 6e 20 47 72 65 65 6e 77 69 63 68 20 6f 6e 20  in Greenwich on 
21ba0 4e 6f 76 65 6d 62 65 72 20 32 34 2c 20 34 37 31  November 24, 471
21bb0 34 20 42 2e 43 2e 20 0a 28 5b 68 74 74 70 3a 2f  4 B.C. .([http:/
21bc0 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72  /en.wikipedia.or
21bd0 67 2f 77 69 6b 69 2f 50 72 6f 6c 65 70 74 69 63  g/wiki/Proleptic
21be0 5f 47 72 65 67 6f 72 69 61 6e 5f 63 61 6c 65 6e  _Gregorian_calen
21bf0 64 61 72 20 7c 20 50 72 6f 6c 65 70 74 69 63 20  dar | Proleptic 
21c00 47 72 65 67 6f 72 69 61 6e 20 63 61 6c 65 6e 64  Gregorian calend
21c10 61 72 5d 29 2e 29 5e 0a 5e 54 68 65 20 73 74 72  ar]).)^.^The str
21c20 66 74 69 6d 65 28 29 20 72 6f 75 74 69 6e 65 20  ftime() routine 
21c30 72 65 74 75 72 6e 73 20 74 68 65 20 64 61 74 65  returns the date
21c40 20 66 6f 72 6d 61 74 74 65 64 20 61 63 63 6f 72   formatted accor
21c50 64 69 6e 67 20 74 6f 20 0a 74 68 65 20 66 6f 72  ding to .the for
21c60 6d 61 74 20 73 74 72 69 6e 67 20 73 70 65 63 69  mat string speci
21c70 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
21c80 74 20 61 72 67 75 6d 65 6e 74 2e 0a 5e 54 68 65  t argument..^The
21c90 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 73   format string s
21ca0 75 70 70 6f 72 74 73 20 74 68 65 20 6d 6f 73 74  upports the most
21cb0 20 63 6f 6d 6d 6f 6e 20 73 75 62 73 74 69 74 75   common substitu
21cc0 74 69 6f 6e 73 20 66 6f 75 6e 64 20 69 6e 20 74  tions found in t
21cd0 68 65 20 0a 5b 68 74 74 70 3a 2f 2f 6f 70 65 6e  he .[http://open
21ce0 67 72 6f 75 70 2e 6f 72 67 2f 6f 6e 6c 69 6e 65  group.org/online
21cf0 70 75 62 73 2f 30 30 37 39 30 38 37 39 39 2f 78  pubs/007908799/x
21d00 73 68 2f 73 74 72 66 74 69 6d 65 2e 68 74 6d 6c  sh/strftime.html
21d10 20 7c 20 73 74 72 66 74 69 6d 65 28 29 20 66 75   | strftime() fu
21d20 6e 63 74 69 6f 6e 5d 0a 66 72 6f 6d 20 74 68 65  nction].from the
21d30 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
21d40 61 72 79 20 70 6c 75 73 20 74 77 6f 20 6e 65 77  ary plus two new
21d50 20 73 75 62 73 74 69 74 75 74 69 6f 6e 73 2c 20   substitutions, 
21d60 25 66 20 61 6e 64 20 25 4a 2e 0a 5e 28 54 68 65  %f and %J..^(The
21d70 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 73 20 61 20   following is a 
21d80 63 6f 6d 70 6c 65 74 65 20 6c 69 73 74 20 6f 66  complete list of
21d90 20 76 61 6c 69 64 20 73 74 72 66 74 69 6d 65 28   valid strftime(
21da0 29 20 73 75 62 73 74 69 74 75 74 69 6f 6e 73 3a  ) substitutions:
21db0 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
21dc0 74 65 3e 0a 3c 74 61 62 6c 65 20 62 6f 72 64 65  te>.<table borde
21dd0 72 3d 22 30 22 20 63 65 6c 6c 70 61 64 64 69 6e  r="0" cellpaddin
21de0 67 3d 22 30 22 20 63 65 6c 6c 73 70 61 63 69 6e  g="0" cellspacin
21df0 67 3d 22 30 22 3e 0a 3c 74 72 3e 3c 74 64 3e 3c  g="0">.<tr><td><
21e00 74 64 20 77 69 64 74 68 3d 22 31 30 22 3e 3c 74  td width="10"><t
21e10 64 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c 74 64  d></tr>..<tr><td
21e20 3e 20 25 64 20 3c 74 64 3e 3c 74 64 3e 20 64 61  > %d <td><td> da
21e30 79 20 6f 66 20 6d 6f 6e 74 68 3a 20 30 30 0a 3c  y of month: 00.<
21e40 74 72 3e 3c 74 64 3e 20 25 66 20 3c 74 64 3e 3c  tr><td> %f <td><
21e50 74 64 3e 20 66 72 61 63 74 69 6f 6e 61 6c 20 73  td> fractional s
21e60 65 63 6f 6e 64 73 3a 20 53 53 2e 53 53 53 0a 3c  econds: SS.SSS.<
21e70 74 72 3e 3c 74 64 3e 20 25 48 20 3c 74 64 3e 3c  tr><td> %H <td><
21e80 74 64 3e 20 68 6f 75 72 3a 20 30 30 2d 32 34 20  td> hour: 00-24 
21e90 0a 3c 74 72 3e 3c 74 64 3e 20 25 6a 20 3c 74 64  .<tr><td> %j <td
21ea0 3e 3c 74 64 3e 20 64 61 79 20 6f 66 20 79 65 61  ><td> day of yea
21eb0 72 3a 20 30 30 31 2d 33 36 36 0a 3c 74 72 3e 3c  r: 001-366.<tr><
21ec0 74 64 3e 20 25 4a 20 3c 74 64 3e 3c 74 64 3e 20  td> %J <td><td> 
21ed0 4a 75 6c 69 61 6e 20 64 61 79 20 6e 75 6d 62 65  Julian day numbe
21ee0 72 0a 3c 74 72 3e 3c 74 64 3e 20 25 6d 20 3c 74  r.<tr><td> %m <t
21ef0 64 3e 3c 74 64 3e 20 6d 6f 6e 74 68 3a 20 30 31  d><td> month: 01
21f00 2d 31 32 0a 3c 74 72 3e 3c 74 64 3e 20 25 4d 20  -12.<tr><td> %M 
21f10 3c 74 64 3e 3c 74 64 3e 20 6d 69 6e 75 74 65 3a  <td><td> minute:
21f20 20 30 30 2d 35 39 0a 3c 74 72 3e 3c 74 64 3e 20   00-59.<tr><td> 
21f30 25 73 20 3c 74 64 3e 3c 74 64 3e 20 73 65 63 6f  %s <td><td> seco
21f40 6e 64 73 20 73 69 6e 63 65 20 31 39 37 30 2d 30  nds since 1970-0
21f50 31 2d 30 31 0a 3c 74 72 3e 3c 74 64 3e 20 25 53  1-01.<tr><td> %S
21f60 20 3c 74 64 3e 3c 74 64 3e 20 73 65 63 6f 6e 64   <td><td> second
21f70 73 3a 20 30 30 2d 35 39 0a 3c 74 72 3e 3c 74 64  s: 00-59.<tr><td
21f80 3e 20 25 77 20 3c 74 64 3e 3c 74 64 3e 20 64 61  > %w <td><td> da
21f90 79 20 6f 66 20 77 65 65 6b 20 30 2d 36 20 77 69  y of week 0-6 wi
21fa0 74 68 20 53 75 6e 64 61 79 3d 3d 30 0a 3c 74 72  th Sunday==0.<tr
21fb0 3e 3c 74 64 3e 20 25 57 20 3c 74 64 3e 3c 74 64  ><td> %W <td><td
21fc0 3e 20 77 65 65 6b 20 6f 66 20 79 65 61 72 3a 20  > week of year: 
21fd0 30 30 2d 35 33 0a 3c 74 72 3e 3c 74 64 3e 20 25  00-53.<tr><td> %
21fe0 59 20 3c 74 64 3e 3c 74 64 3e 20 79 65 61 72 3a  Y <td><td> year:
21ff0 20 30 30 30 30 2d 39 39 39 39 0a 3c 74 72 3e 3c   0000-9999.<tr><
22000 74 64 3e 20 25 25 20 3c 74 64 3e 3c 74 64 3e 20  td> %% <td><td> 
22010 25 0a 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f  %.</table>.</blo
22020 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 3c 70 3e 0a  ckquote>)^..<p>.
22030 5e 28 4e 6f 74 69 63 65 20 74 68 61 74 20 61 6c  ^(Notice that al
22040 6c 20 6f 74 68 65 72 20 64 61 74 65 20 61 6e 64  l other date and
22050 20 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20   time functions 
22060 63 61 6e 20 62 65 20 65 78 70 72 65 73 73 65 64  can be expressed
22070 0a 69 6e 20 74 65 72 6d 73 20 6f 66 20 73 74 72  .in terms of str
22080 66 74 69 6d 65 28 29 3a 0a 3c 2f 70 3e 0a 0a 3c  ftime():.</p>..<
22090 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 74 61 62  blockquote>.<tab
220a0 6c 65 20 62 6f 72 64 65 72 3d 22 30 22 20 63 65  le border="0" ce
220b0 6c 6c 70 61 64 64 69 6e 67 3d 22 30 22 20 63 65  llpadding="0" ce
220c0 6c 6c 73 70 61 63 69 6e 67 3d 22 30 22 3e 0a 3c  llspacing="0">.<
220d0 74 72 3e 3c 74 64 3e 3c 62 3e 46 75 6e 63 74 69  tr><td><b>Functi
220e0 6f 6e 3c 2f 62 3e 3c 74 64 20 77 69 64 74 68 3d  on</b><td width=
220f0 22 33 30 22 3e 3c 74 64 3e 3c 62 3e 45 71 75 69  "30"><td><b>Equi
22100 76 61 6c 65 6e 74 20 73 74 72 66 74 69 6d 65 28  valent strftime(
22110 29 3c 2f 62 3e 0a 3c 74 72 3e 3c 74 64 3e 20 20  )</b>.<tr><td>  
22120 20 64 61 74 65 28 2e 2e 2e 29 20 20 20 20 20 20   date(...)      
22130 3c 74 64 3e 3c 74 64 3e 20 20 73 74 72 66 74 69  <td><td>  strfti
22140 6d 65 28 27 25 59 2d 25 6d 2d 25 64 27 2c 20 2e  me('%Y-%m-%d', .
22150 2e 2e 29 0a 3c 74 72 3e 3c 74 64 3e 20 20 20 74  ..).<tr><td>   t
22160 69 6d 65 28 2e 2e 2e 29 20 20 20 20 20 20 3c 74  ime(...)      <t
22170 64 3e 3c 74 64 3e 20 20 73 74 72 66 74 69 6d 65  d><td>  strftime
22180 28 27 25 48 3a 25 4d 3a 25 53 27 2c 20 2e 2e 2e  ('%H:%M:%S', ...
22190 29 0a 3c 74 72 3e 3c 74 64 3e 20 20 20 64 61 74  ).<tr><td>   dat
221a0 65 74 69 6d 65 28 2e 2e 2e 29 20 20 3c 74 64 3e  etime(...)  <td>
221b0 3c 74 64 3e 20 20 73 74 72 66 74 69 6d 65 28 27  <td>  strftime('
221c0 25 59 2d 25 6d 2d 25 64 20 25 48 3a 25 4d 3a 25  %Y-%m-%d %H:%M:%
221d0 53 27 2c 20 2e 2e 2e 29 0a 3c 74 72 3e 3c 74 64  S', ...).<tr><td
221e0 3e 20 20 20 6a 75 6c 69 61 6e 64 61 79 28 2e 2e  >   julianday(..
221f0 2e 29 20 3c 74 64 3e 3c 74 64 3e 20 20 73 74 72  .) <td><td>  str
22200 66 74 69 6d 65 28 27 25 4a 27 2c 20 2e 2e 2e 29  ftime('%J', ...)
22210 0a 3c 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63  .</table>.</bloc
22220 6b 71 75 6f 74 65 3e 29 5e 0a 0a 3c 70 3e 0a 54  kquote>)^..<p>.T
22230 68 65 20 6f 6e 6c 79 20 72 65 61 73 6f 6e 73 20  he only reasons 
22240 66 6f 72 20 70 72 6f 76 69 64 69 6e 67 20 66 75  for providing fu
22250 6e 63 74 69 6f 6e 73 20 6f 74 68 65 72 20 74 68  nctions other th
22260 61 6e 20 73 74 72 66 74 69 6d 65 28 29 20 69 73  an strftime() is
22270 0a 66 6f 72 20 63 6f 6e 76 65 6e 69 65 6e 63 65  .for convenience
22280 20 61 6e 64 20 66 6f 72 20 65 66 66 69 63 69 65   and for efficie
22290 6e 63 79 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 54  ncy..</p>..<h3>T
222a0 69 6d 65 20 53 74 72 69 6e 67 73 3c 2f 68 33 3e  ime Strings</h3>
222b0 0a 0a 3c 70 3e 5e 28 41 20 74 69 6d 65 20 73 74  ..<p>^(A time st
222c0 72 69 6e 67 20 63 61 6e 20 62 65 20 69 6e 20 61  ring can be in a
222d0 6e 79 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ny of the follow
222e0 69 6e 67 20 66 6f 72 6d 61 74 73 3a 3c 2f 70 3e  ing formats:</p>
222f0 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 3c 69 3e 59  ..<ol>.<li> <i>Y
22300 59 59 59 2d 4d 4d 2d 44 44 3c 2f 69 3e 0a 3c 6c  YYY-MM-DD</i>.<l
22310 69 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44  i> <i>YYYY-MM-DD
22320 20 48 48 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e 20   HH:MM</i>.<li> 
22330 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48  <i>YYYY-MM-DD HH
22340 3a 4d 4d 3a 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20  :MM:SS</i>.<li> 
22350 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 20 48 48  <i>YYYY-MM-DD HH
22360 3a 4d 4d 3a 53 53 2e 53 53 53 3c 2f 69 3e 0a 3c  :MM:SS.SSS</i>.<
22370 6c 69 3e 20 3c 69 3e 59 59 59 59 2d 4d 4d 2d 44  li> <i>YYYY-MM-D
22380 44 3c 2f 69 3e 3c 62 3e 54 3c 2f 62 3e 3c 69 3e  D</i><b>T</b><i>
22390 48 48 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c  HH:MM</i>.<li> <
223a0 69 3e 59 59 59 59 2d 4d 4d 2d 44 44 3c 2f 69 3e  i>YYYY-MM-DD</i>
223b0 3c 62 3e 54 3c 2f 62 3e 3c 69 3e 48 48 3a 4d 4d  <b>T</b><i>HH:MM
223c0 3a 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c 69 3e  :SS</i>.<li> <i>
223d0 59 59 59 59 2d 4d 4d 2d 44 44 3c 2f 69 3e 3c 62  YYYY-MM-DD</i><b
223e0 3e 54 3c 2f 62 3e 3c 69 3e 48 48 3a 4d 4d 3a 53  >T</b><i>HH:MM:S
223f0 53 2e 53 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c  S.SSS</i>.<li> <
22400 69 3e 48 48 3a 4d 4d 3c 2f 69 3e 0a 3c 6c 69 3e  i>HH:MM</i>.<li>
22410 20 3c 69 3e 48 48 3a 4d 4d 3a 53 53 3c 2f 69 3e   <i>HH:MM:SS</i>
22420 0a 3c 6c 69 3e 20 3c 69 3e 48 48 3a 4d 4d 3a 53  .<li> <i>HH:MM:S
22430 53 2e 53 53 53 3c 2f 69 3e 0a 3c 6c 69 3e 20 3c  S.SSS</i>.<li> <
22440 62 3e 6e 6f 77 3c 2f 62 3e 0a 3c 6c 69 3e 20 3c  b>now</b>.<li> <
22450 69 3e 44 44 44 44 44 44 44 44 44 44 3c 2f 69 3e  i>DDDDDDDDDD</i>
22460 0a 3c 2f 6f 6c 3e 29 5e 0a 0a 3c 70 3e 0a 5e 49  .</ol>)^..<p>.^I
22470 6e 20 66 6f 72 6d 61 74 73 20 35 20 74 68 72 6f  n formats 5 thro
22480 75 67 68 20 37 2c 20 74 68 65 20 22 54 22 20 69  ugh 7, the "T" i
22490 73 20 61 20 6c 69 74 65 72 61 6c 20 63 68 61 72  s a literal char
224a0 61 63 74 65 72 20 73 65 70 61 72 61 74 69 6e 67  acter separating
224b0 20 0a 74 68 65 20 64 61 74 65 20 61 6e 64 20 74   .the date and t
224c0 68 65 20 74 69 6d 65 2c 20 61 73 20 72 65 71 75  he time, as requ
224d0 69 72 65 64 20 62 79 20 0a 5b 68 74 74 70 3a 2f  ired by .[http:/
224e0 2f 77 77 77 2e 77 33 63 2e 6f 72 67 2f 54 52 2f  /www.w3c.org/TR/
224f0 4e 4f 54 45 2d 64 61 74 65 74 69 6d 65 20 7c 20  NOTE-datetime | 
22500 49 53 4f 2d 38 36 30 31 5d 2e 20 0a 5e 46 6f 72  ISO-8601]. .^For
22510 6d 61 74 73 20 38 20 74 68 72 6f 75 67 68 20 31  mats 8 through 1
22520 30 20 74 68 61 74 20 73 70 65 63 69 66 79 20 6f  0 that specify o
22530 6e 6c 79 20 61 20 74 69 6d 65 20 61 73 73 75 6d  nly a time assum
22540 65 20 61 20 64 61 74 65 20 6f 66 20 0a 32 30 30  e a date of .200
22550 30 2d 30 31 2d 30 31 2e 20 46 6f 72 6d 61 74 20  0-01-01. Format 
22560 31 31 2c 20 74 68 65 20 73 74 72 69 6e 67 20 27  11, the string '
22570 6e 6f 77 27 2c 20 69 73 20 63 6f 6e 76 65 72 74  now', is convert
22580 65 64 20 69 6e 74 6f 20 74 68 65 20 0a 63 75 72  ed into the .cur
22590 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
225a0 6d 65 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  me as obtained f
225b0 72 6f 6d 20 74 68 65 20 78 43 75 72 72 65 6e 74  rom the xCurrent
225c0 54 69 6d 65 20 6d 65 74 68 6f 64 0a 6f 66 20 74  Time method.of t
225d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
225e0 20 6f 62 6a 65 63 74 20 69 6e 20 75 73 65 2e 0a   object in use..
225f0 5e 54 68 65 20 27 6e 6f 77 27 20 61 72 67 75 6d  ^The 'now' argum
22600 65 6e 74 20 74 6f 20 64 61 74 65 20 61 6e 64 20  ent to date and 
22610 74 69 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  time functions a
22620 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 65 78  lways returns ex
22630 61 63 74 6c 79 20 74 68 65 0a 73 61 6d 65 20 76  actly the.same v
22640 61 6c 75 65 20 66 6f 72 20 6d 75 6c 74 69 70 6c  alue for multipl
22650 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 77 69  e invocations wi
22660 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  thin the same [s
22670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
22680 61 6c 6c 2e 0a 5e 5b 68 74 74 70 3a 2f 2f 65 6e  all..^[http://en
22690 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f 77  .wikipedia.org/w
226a0 69 6b 69 2f 43 6f 6f 72 64 69 6e 61 74 65 64 5f  iki/Coordinated_
226b0 55 6e 69 76 65 72 73 61 6c 5f 54 69 6d 65 20 7c  Universal_Time |
226c0 20 55 6e 69 76 65 72 73 61 6c 20 43 6f 6f 72 64   Universal Coord
226d0 69 6e 61 74 65 64 20 54 69 6d 65 20 28 55 54 43  inated Time (UTC
226e0 29 5d 20 69 73 20 75 73 65 64 2e 20 0a 5e 46 6f  )] is used. .^Fo
226f0 72 6d 61 74 20 31 32 20 69 73 20 74 68 65 20 0a  rmat 12 is the .
22700 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70  [http://en.wikip
22710 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4a 75  edia.org/wiki/Ju
22720 6c 69 61 6e 5f 64 61 79 20 7c 20 4a 75 6c 69 61  lian_day | Julia
22730 6e 20 64 61 79 20 6e 75 6d 62 65 72 5d 0a 65 78  n day number].ex
22740 70 72 65 73 73 65 64 20 61 73 20 61 20 66 6c 6f  pressed as a flo
22750 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
22760 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 46 6f 72  e..</p>..<p>.For
22770 6d 61 74 73 20 32 20 74 68 72 6f 75 67 68 20 31  mats 2 through 1
22780 30 20 6d 61 79 20 62 65 20 6f 70 74 69 6f 6e 61  0 may be optiona
22790 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  lly followed by 
227a0 61 20 74 69 6d 65 7a 6f 6e 65 20 69 6e 64 69 63  a timezone indic
227b0 61 74 6f 72 20 6f 66 20 74 68 65 20 66 6f 72 6d  ator of the form
227c0 0a 22 3c 69 3e 26 23 39 31 3b 2b 2d 26 23 39 33  ."<i>&#91;+-&#93
227d0 3b 48 48 3a 4d 4d 3c 2f 69 3e 22 20 6f 72 20 6a  ;HH:MM</i>" or j
227e0 75 73 74 20 22 3c 69 3e 5a 3c 2f 69 3e 22 2e 20  ust "<i>Z</i>". 
227f0 20 54 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   The date and ti
22800 6d 65 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  me functions use
22810 20 55 54 43 20 6f 72 20 22 7a 75 6c 75 22 0a 74   UTC or "zulu".t
22820 69 6d 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  ime internally, 
22830 61 6e 64 20 73 6f 20 74 68 65 20 22 5a 22 20 73  and so the "Z" s
22840 75 66 66 69 78 20 69 73 20 61 20 6e 6f 2d 6f 70  uffix is a no-op
22850 2e 20 20 41 6e 79 20 6e 6f 6e 2d 7a 65 72 6f 20  .  Any non-zero 
22860 22 48 48 3a 4d 4d 22 20 73 75 66 66 69 78 20 69  "HH:MM" suffix i
22870 73 0a 73 75 62 74 72 61 63 74 65 64 20 66 72 6f  s.subtracted fro
22880 6d 20 74 68 65 20 69 6e 64 69 63 61 74 65 64 20  m the indicated 
22890 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 6e  date and time in
228a0 20 6f 72 64 65 72 20 74 6f 20 63 6f 6d 70 75 74   order to comput
228b0 65 20 7a 75 6c 75 20 74 69 6d 65 2e 0a 46 6f 72  e zulu time..For
228c0 20 65 78 61 6d 70 6c 65 2c 20 61 6c 6c 20 6f 66   example, all of
228d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
228e0 69 6d 65 20 73 74 72 69 6e 67 73 20 61 72 65 20  ime strings are 
228f0 65 71 75 69 76 61 6c 65 6e 74 3a 0a 3c 2f 70 3e  equivalent:.</p>
22900 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 32  ..<blockquote>.2
22910 30 31 33 2d 31 30 2d 30 37 20 30 38 3a 32 33 3a  013-10-07 08:23:
22920 31 39 2e 31 32 30 3c 62 72 3e 0a 32 30 31 33 2d  19.120<br>.2013-
22930 31 30 2d 30 37 54 30 38 3a 32 33 3a 31 39 2e 31  10-07T08:23:19.1
22940 32 30 5a 3c 62 72 3e 0a 32 30 31 33 2d 31 30 2d  20Z<br>.2013-10-
22950 30 37 20 30 34 3a 32 33 3a 31 39 2e 31 32 30 2d  07 04:23:19.120-
22960 30 34 3a 30 30 3c 62 72 3e 0a 32 34 35 36 35 37  04:00<br>.245657
22970 32 2e 38 34 39 35 32 36 38 35 0a 3c 2f 62 6c 6f  2.84952685.</blo
22980 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 5e 28  ckquote>..<p>.^(
22990 49 6e 20 66 6f 72 6d 61 74 73 20 34 2c 20 37 2c  In formats 4, 7,
229a0 20 61 6e 64 20 31 30 2c 20 74 68 65 20 66 72 61   and 10, the fra
229b0 63 74 69 6f 6e 61 6c 20 73 65 63 6f 6e 64 73 20  ctional seconds 
229c0 76 61 6c 75 65 20 53 53 2e 53 53 53 20 63 61 6e  value SS.SSS can
229d0 20 68 61 76 65 0a 6f 6e 65 20 6f 72 20 6d 6f 72   have.one or mor
229e0 65 20 64 69 67 69 74 73 20 66 6f 6c 6c 6f 77 69  e digits followi
229f0 6e 67 20 74 68 65 20 64 65 63 69 6d 61 6c 20 70  ng the decimal p
22a00 6f 69 6e 74 2e 20 20 45 78 61 63 74 6c 79 20 74  oint.  Exactly t
22a10 68 72 65 65 20 64 69 67 69 74 73 20 61 72 65 0a  hree digits are.
22a20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 65 78 61  shown in the exa
22a30 6d 70 6c 65 73 20 62 65 63 61 75 73 65 20 6f 6e  mples because on
22a40 6c 79 20 74 68 65 20 66 69 72 73 74 20 74 68 72  ly the first thr
22a50 65 65 20 64 69 67 69 74 73 20 61 72 65 20 73 69  ee digits are si
22a60 67 6e 69 66 69 63 61 6e 74 0a 74 6f 20 74 68 65  gnificant.to the
22a70 20 72 65 73 75 6c 74 2c 20 62 75 74 20 74 68 65   result, but the
22a80 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63 61   input string ca
22a90 6e 20 68 61 76 65 20 66 65 77 65 72 20 6f 72 20  n have fewer or 
22aa0 6d 6f 72 65 20 74 68 61 6e 20 74 68 72 65 65 20  more than three 
22ab0 64 69 67 69 74 73 0a 61 6e 64 20 74 68 65 20 64  digits.and the d
22ac0 61 74 65 2f 74 69 6d 65 20 66 75 6e 63 74 69 6f  ate/time functio
22ad0 6e 73 20 77 69 6c 6c 20 73 74 69 6c 6c 20 6f 70  ns will still op
22ae0 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 2e  erate correctly.
22af0 29 5e 0a 53 69 6d 69 6c 61 72 6c 79 2c 20 66 6f  )^.Similarly, fo
22b00 72 6d 61 74 20 31 32 20 69 73 20 73 68 6f 77 6e  rmat 12 is shown
22b10 20 77 69 74 68 20 31 30 20 73 69 67 6e 69 66 69   with 10 signifi
22b20 63 61 6e 74 20 64 69 67 69 74 73 2c 20 62 75 74  cant digits, but
22b30 20 74 68 65 20 64 61 74 65 2f 74 69 6d 65 0a 66   the date/time.f
22b40 75 6e 63 74 69 6f 6e 73 20 77 69 6c 6c 20 72 65  unctions will re
22b50 61 6c 6c 79 20 61 63 63 65 70 74 20 61 73 20 6d  ally accept as m
22b60 61 6e 79 20 6f 72 20 61 73 20 66 65 77 20 64 69  any or as few di
22b70 67 69 74 73 20 61 73 20 61 72 65 20 6e 65 63 65  gits as are nece
22b80 73 73 61 72 79 20 74 6f 0a 72 65 70 72 65 73 65  ssary to.represe
22b90 6e 74 20 74 68 65 20 4a 75 6c 69 61 6e 20 64 61  nt the Julian da
22ba0 79 20 6e 75 6d 62 65 72 2e 0a 3c 2f 70 3e 0a 0a  y number..</p>..
22bb0 3c 68 33 3e 4d 6f 64 69 66 69 65 72 73 3c 2f 68  <h3>Modifiers</h
22bc0 33 3e 0a 0a 3c 70 3e 5e 54 68 65 20 74 69 6d 65  3>..<p>^The time
22bd0 20 73 74 72 69 6e 67 20 63 61 6e 20 62 65 20 66   string can be f
22be0 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72 6f 20  ollowed by zero 
22bf0 6f 72 20 6d 6f 72 65 20 6d 6f 64 69 66 69 65 72  or more modifier
22c00 73 20 74 68 61 74 20 0a 61 6c 74 65 72 20 64 61  s that .alter da
22c10 74 65 20 61 6e 64 2f 6f 72 20 74 69 6d 65 2e 20  te and/or time. 
22c20 5e 45 61 63 68 20 6d 6f 64 69 66 69 65 72 0a 69  ^Each modifier.i
22c30 73 20 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  s a transformati
22c40 6f 6e 20 74 68 61 74 20 69 73 20 61 70 70 6c 69  on that is appli
22c50 65 64 20 74 6f 20 74 68 65 20 74 69 6d 65 20 76  ed to the time v
22c60 61 6c 75 65 20 74 6f 20 69 74 73 20 6c 65 66 74  alue to its left
22c70 2e 0a 5e 4d 6f 64 69 66 69 65 72 73 20 61 72 65  ..^Modifiers are
22c80 20 61 70 70 6c 69 65 64 20 66 72 6f 6d 20 6c 65   applied from le
22c90 66 74 20 74 6f 20 72 69 67 68 74 3b 20 6f 72 64  ft to right; ord
22ca0 65 72 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  er is important.
22cb0 0a 5e 28 54 68 65 20 61 76 61 69 6c 61 62 6c 65  .^(The available
22cc0 20 6d 6f 64 69 66 69 65 72 73 20 61 72 65 20 61   modifiers are a
22cd0 73 20 66 6f 6c 6c 6f 77 73 2e 3c 2f 70 3e 0a 0a  s follows.</p>..
22ce0 3c 6f 6c 3e 0a 3c 6c 69 3e 20 4e 4e 4e 20 64 61  <ol>.<li> NNN da
22cf0 79 73 0a 3c 6c 69 3e 20 4e 4e 4e 20 68 6f 75 72  ys.<li> NNN hour
22d00 73 0a 3c 6c 69 3e 20 4e 4e 4e 20 6d 69 6e 75 74  s.<li> NNN minut
22d10 65 73 0a 3c 6c 69 3e 20 4e 4e 4e 2e 4e 4e 4e 4e  es.<li> NNN.NNNN
22d20 20 73 65 63 6f 6e 64 73 0a 3c 6c 69 3e 20 4e 4e   seconds.<li> NN
22d30 4e 20 6d 6f 6e 74 68 73 0a 3c 6c 69 3e 20 4e 4e  N months.<li> NN
22d40 4e 20 79 65 61 72 73 0a 3c 6c 69 3e 20 73 74 61  N years.<li> sta
22d50 72 74 20 6f 66 20 6d 6f 6e 74 68 0a 3c 6c 69 3e  rt of month.<li>
22d60 20 73 74 61 72 74 20 6f 66 20 79 65 61 72 0a 3c   start of year.<
22d70 6c 69 3e 20 73 74 61 72 74 20 6f 66 20 64 61 79  li> start of day
22d80 0a 3c 6c 69 3e 20 77 65 65 6b 64 61 79 20 4e 0a  .<li> weekday N.
22d90 3c 6c 69 3e 20 75 6e 69 78 65 70 6f 63 68 0a 3c  <li> unixepoch.<
22da0 6c 69 3e 20 6c 6f 63 61 6c 74 69 6d 65 0a 3c 6c  li> localtime.<l
22db0 69 3e 20 75 74 63 20 0a 3c 2f 6f 6c 3e 29 5e 0a  i> utc .</ol>)^.
22dc0 0a 3c 70 3e 5e 54 68 65 20 66 69 72 73 74 20 73  .<p>^The first s
22dd0 69 78 20 6d 6f 64 69 66 69 65 72 73 20 28 31 20  ix modifiers (1 
22de0 74 68 72 6f 75 67 68 20 36 29 20 0a 73 69 6d 70  through 6) .simp
22df0 6c 79 20 61 64 64 20 74 68 65 20 73 70 65 63 69  ly add the speci
22e00 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
22e10 69 6d 65 20 74 6f 20 74 68 65 20 64 61 74 65 20  ime to the date 
22e20 61 6e 64 20 74 69 6d 65 20 0a 73 70 65 63 69 66  and time .specif
22e30 69 65 64 20 62 79 20 74 68 65 20 70 72 65 63 65  ied by the prece
22e40 64 69 6e 67 20 74 69 6d 65 73 74 72 69 6e 67 20  ding timestring 
22e50 61 6e 64 20 6d 6f 64 69 66 69 65 72 73 2e 0a 5e  and modifiers..^
22e60 54 68 65 20 27 73 27 20 63 68 61 72 61 63 74 65  The 's' characte
22e70 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20  r at the end of 
22e80 74 68 65 20 6d 6f 64 69 66 69 65 72 20 6e 61 6d  the modifier nam
22e90 65 73 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 0a  es is optional..
22ea0 5e 4e 6f 74 65 20 74 68 61 74 20 22 26 70 6c 75  ^Note that "&plu
22eb0 73 6d 6e 3b 4e 4e 4e 20 6d 6f 6e 74 68 73 22 20  smn;NNN months" 
22ec0 77 6f 72 6b 73 20 62 79 20 72 65 6e 64 65 72 69  works by renderi
22ed0 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
22ee0 64 61 74 65 20 69 6e 74 6f 0a 74 68 65 20 59 59  date into.the YY
22ef0 59 59 2d 4d 4d 2d 44 44 20 66 6f 72 6d 61 74 2c  YY-MM-DD format,
22f00 20 61 64 64 69 6e 67 20 74 68 65 20 26 70 6c 75   adding the &plu
22f10 73 6d 6e 3b 4e 4e 4e 20 74 6f 20 74 68 65 20 4d  smn;NNN to the M
22f20 4d 20 6d 6f 6e 74 68 20 76 61 6c 75 65 2c 20 74  M month value, t
22f30 68 65 6e 0a 6e 6f 72 6d 61 6c 69 7a 69 6e 67 20  hen.normalizing 
22f40 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
22f50 75 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  us, for example,
22f60 20 74 68 65 20 64 61 74 61 20 32 30 30 31 2d 30   the data 2001-0
22f70 33 2d 33 31 20 6d 6f 64 69 66 69 65 64 0a 62 79  3-31 modified.by
22f80 20 27 2b 31 20 6d 6f 6e 74 68 27 20 69 6e 69 74   '+1 month' init
22f90 69 61 6c 6c 79 20 79 69 65 6c 64 73 20 32 30 30  ially yields 200
22fa0 31 2d 30 34 2d 33 31 2c 20 62 75 74 20 41 70 72  1-04-31, but Apr
22fb0 69 6c 20 6f 6e 6c 79 20 68 61 73 20 33 30 20 64  il only has 30 d
22fc0 61 79 73 0a 73 6f 20 74 68 65 20 64 61 74 65 20  ays.so the date 
22fd0 69 73 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 74 6f  is normalized to
22fe0 20 32 30 30 31 2d 30 35 2d 30 31 2e 20 20 5e 41   2001-05-01.  ^A
22ff0 20 73 69 6d 69 6c 61 72 20 65 66 66 65 63 74 20   similar effect 
23000 6f 63 63 75 72 73 20 77 68 65 6e 0a 74 68 65 20  occurs when.the 
23010 6f 72 69 67 69 6e 61 6c 20 64 61 74 65 20 69 73  original date is
23020 20 46 65 62 72 75 61 72 79 20 32 39 20 6f 66 20   February 29 of 
23030 61 20 6c 65 61 70 79 65 61 72 20 61 6e 64 20 74  a leapyear and t
23040 68 65 20 6d 6f 64 69 66 69 65 72 20 69 73 0a 26  he modifier is.&
23050 70 6c 75 73 6d 6e 3b 4e 20 79 65 61 72 73 20 77  plusmn;N years w
23060 68 65 72 65 20 4e 20 69 73 20 6e 6f 74 20 61 20  here N is not a 
23070 6d 75 6c 74 69 70 6c 65 20 6f 66 20 66 6f 75 72  multiple of four
23080 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 54 68 65 20 22  .</p>..<p>^The "
23090 73 74 61 72 74 20 6f 66 22 20 6d 6f 64 69 66 69  start of" modifi
230a0 65 72 73 20 28 37 20 74 68 72 6f 75 67 68 20 39  ers (7 through 9
230b0 29 20 73 68 69 66 74 20 74 68 65 20 64 61 74 65  ) shift the date
230c0 20 62 61 63 6b 77 61 72 64 73 20 0a 74 6f 20 74   backwards .to t
230d0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
230e0 74 68 65 20 63 75 72 72 65 6e 74 20 6d 6f 6e 74  the current mont
230f0 68 2c 20 79 65 61 72 20 6f 72 20 64 61 79 2e 3c  h, year or day.<
23100 2f 70 3e 0a 0a 3c 70 3e 5e 28 54 68 65 20 22 77  /p>..<p>^(The "w
23110 65 65 6b 64 61 79 22 20 6d 6f 64 69 66 69 65 72  eekday" modifier
23120 20 61 64 76 61 6e 63 65 73 20 74 68 65 20 64 61   advances the da
23130 74 65 20 66 6f 72 77 61 72 64 2c 20 69 66 20 6e  te forward, if n
23140 65 63 65 73 73 61 72 79 2c 0a 74 6f 20 74 68 65  ecessary,.to the
23150 20 6e 65 78 74 20 64 61 74 65 20 77 68 65 72 65   next date where
23160 20 74 68 65 20 77 65 65 6b 64 61 79 20 6e 75 6d   the weekday num
23170 62 65 72 20 69 73 20 4e 2e 20 53 75 6e 64 61 79  ber is N. Sunday
23180 20 69 73 20 30 2c 20 4d 6f 6e 64 61 79 20 69 73   is 0, Monday is
23190 20 31 2c 0a 61 6e 64 20 73 6f 20 66 6f 72 74 68   1,.and so forth
231a0 2e 29 5e 0a 5e 49 66 20 74 68 65 20 64 61 74 65  .)^.^If the date
231b0 20 69 73 20 61 6c 72 65 61 64 79 20 6f 6e 20 74   is already on t
231c0 68 65 20 64 65 73 69 72 65 64 20 77 65 65 6b 64  he desired weekd
231d0 61 79 2c 20 74 68 65 20 22 77 65 65 6b 64 61 79  ay, the "weekday
231e0 22 20 6d 6f 64 69 66 69 65 72 0a 6c 65 61 76 65  " modifier.leave
231f0 73 20 74 68 65 20 64 61 74 65 20 75 6e 63 68 61  s the date uncha
23200 6e 67 65 64 2e 20 20 3c 2f 70 3e 0a 0a 3c 70 3e  nged.  </p>..<p>
23210 5e 54 68 65 20 22 75 6e 69 78 65 70 6f 63 68 22  ^The "unixepoch"
23220 20 6d 6f 64 69 66 69 65 72 20 28 31 31 29 20 6f   modifier (11) o
23230 6e 6c 79 20 77 6f 72 6b 73 20 69 66 20 69 74 20  nly works if it 
23240 69 6d 6d 65 64 69 61 74 65 6c 79 20 66 6f 6c 6c  immediately foll
23250 6f 77 73 20 0a 61 20 74 69 6d 65 73 74 72 69 6e  ows .a timestrin
23260 67 20 69 6e 20 74 68 65 20 44 44 44 44 44 44 44  g in the DDDDDDD
23270 44 44 44 20 66 6f 72 6d 61 74 2e 20 0a 5e 54 68  DDD format. .^Th
23280 69 73 20 6d 6f 64 69 66 69 65 72 20 63 61 75 73  is modifier caus
23290 65 73 20 74 68 65 20 44 44 44 44 44 44 44 44 44  es the DDDDDDDDD
232a0 44 20 74 6f 20 62 65 20 69 6e 74 65 72 70 72 65  D to be interpre
232b0 74 65 64 20 6e 6f 74 20 0a 61 73 20 61 20 4a 75  ted not .as a Ju
232c0 6c 69 61 6e 20 64 61 79 20 6e 75 6d 62 65 72 20  lian day number 
232d0 61 73 20 69 74 20 6e 6f 72 6d 61 6c 6c 79 20 77  as it normally w
232e0 6f 75 6c 64 20 62 65 2c 20 62 75 74 20 61 73 0a  ould be, but as.
232f0 5b 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70  [http://en.wikip
23300 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 55 6e  edia.org/wiki/Un
23310 69 78 5f 74 69 6d 65 20 7c 20 55 6e 69 78 20 54  ix_time | Unix T
23320 69 6d 65 5d 20 2d 20 74 68 65 20 0a 6e 75 6d 62  ime] - the .numb
23330 65 72 20 6f 66 20 73 65 63 6f 6e 64 73 20 73 69  er of seconds si
23340 6e 63 65 20 31 39 37 30 2e 20 20 49 66 20 74 68  nce 1970.  If th
23350 65 20 22 75 6e 69 78 65 70 6f 63 68 22 20 6d 6f  e "unixepoch" mo
23360 64 69 66 69 65 72 20 64 6f 65 73 20 6e 6f 74 0a  difier does not.
23370 66 6f 6c 6c 6f 77 20 61 20 74 69 6d 65 73 74 72  follow a timestr
23380 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
23390 44 44 44 44 44 44 44 44 44 44 20 77 68 69 63 68  DDDDDDDDDD which
233a0 20 65 78 70 72 65 73 73 65 73 20 74 68 65 20 6e   expresses the n
233b0 75 6d 62 65 72 0a 6f 66 20 73 65 63 6f 6e 64 73  umber.of seconds
233c0 20 73 69 6e 63 65 20 31 39 37 30 20 6f 72 20 69   since 1970 or i
233d0 66 20 6f 74 68 65 72 20 6d 6f 64 69 66 69 65 72  f other modifier
233e0 73 0a 73 65 70 61 72 61 74 65 20 74 68 65 20 22  s.separate the "
233f0 75 6e 69 78 65 70 6f 63 68 22 20 6d 6f 64 69 66  unixepoch" modif
23400 69 65 72 20 66 72 6f 6d 20 70 72 69 6f 72 20 44  ier from prior D
23410 44 44 44 44 44 44 44 44 44 20 74 68 65 6e 20 74  DDDDDDDDD then t
23420 68 65 0a 62 65 68 61 76 69 6f 72 20 69 73 20 75  he.behavior is u
23430 6e 64 65 66 69 6e 65 64 2e 0a 46 6f 72 20 53 51  ndefined..For SQ
23440 4c 69 74 65 20 76 65 72 73 69 6f 6e 73 20 62 65  Lite versions be
23450 66 6f 72 65 20 33 2e 31 36 2e 30 20 28 5b 64 61  fore 3.16.0 ([da
23460 74 65 6f 66 3a 33 2e 31 36 2e 30 5d 29 2c 20 0a  teof:3.16.0]), .
23470 74 68 65 20 22 75 6e 69 78 65 70 6f 63 68 22 20  the "unixepoch" 
23480 6d 6f 64 69 66 69 65 72 20 6f 6e 6c 79 20 77 6f  modifier only wo
23490 72 6b 73 20 66 6f 72 0a 64 61 74 65 73 20 62 65  rks for.dates be
234a0 74 77 65 65 6e 20 30 30 30 30 2d 30 31 2d 30 31  tween 0000-01-01
234b0 20 30 30 3a 30 30 3a 30 30 20 61 6e 64 20 35 33   00:00:00 and 53
234c0 35 32 2d 31 31 2d 30 31 20 31 30 3a 35 32 3a 34  52-11-01 10:52:4
234d0 37 20 28 75 6e 69 78 20 74 69 6d 65 73 0a 6f 66  7 (unix times.of
234e0 20 2d 36 32 31 36 37 32 31 39 32 30 30 20 74 68   -62167219200 th
234f0 72 6f 75 67 68 20 31 30 36 37 35 31 39 39 31 31  rough 1067519911
23500 36 37 29 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  67).</p>..<tcl>h
23510 64 5f 66 72 61 67 6d 65 6e 74 20 6c 6f 63 61 6c  d_fragment local
23520 74 69 6d 65 20 7b 6c 6f 63 61 6c 74 69 6d 65 20  time {localtime 
23530 6d 6f 64 69 66 69 65 72 7d 20 7b 27 75 74 63 27  modifier} {'utc'
23540 20 6d 6f 64 69 66 69 65 72 7d 3c 2f 74 63 6c 3e   modifier}</tcl>
23550 0a 3c 70 3e 5e 54 68 65 20 22 6c 6f 63 61 6c 74  .<p>^The "localt
23560 69 6d 65 22 20 6d 6f 64 69 66 69 65 72 20 28 31  ime" modifier (1
23570 32 29 20 61 73 73 75 6d 65 73 20 74 68 65 20 74  2) assumes the t
23580 69 6d 65 20 73 74 72 69 6e 67 20 74 6f 20 69 74  ime string to it
23590 73 20 6c 65 66 74 20 69 73 20 69 6e 0a 55 6e 69  s left is in.Uni
235a0 76 65 72 73 61 6c 20 43 6f 6f 72 64 69 6e 61 74  versal Coordinat
235b0 65 64 20 54 69 6d 65 20 28 55 54 43 29 20 61 6e  ed Time (UTC) an
235c0 64 20 61 64 6a 75 73 74 73 20 74 68 65 20 74 69  d adjusts the ti
235d0 6d 65 0a 73 74 72 69 6e 67 20 73 6f 20 74 68 61  me.string so tha
235e0 74 20 69 74 20 64 69 73 70 6c 61 79 73 20 6c 6f  t it displays lo
235f0 63 61 6c 74 69 6d 65 2e 20 20 49 66 20 22 6c 6f  caltime.  If "lo
23600 63 61 6c 74 69 6d 65 22 0a 66 6f 6c 6c 6f 77 73  caltime".follows
23610 20 61 20 74 69 6d 65 20 74 68 61 74 20 69 73 20   a time that is 
23620 6e 6f 74 20 55 54 43 2c 20 74 68 65 6e 20 74 68  not UTC, then th
23630 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
23640 64 65 66 69 6e 65 64 2e 0a 5e 28 54 68 65 20 22  defined..^(The "
23650 75 74 63 22 20 6d 6f 64 69 66 69 65 72 20 69 73  utc" modifier is
23660 20 74 68 65 20 6f 70 70 6f 73 69 74 65 20 6f 66   the opposite of
23670 20 22 6c 6f 63 61 6c 74 69 6d 65 22 2e 20 20 0a   "localtime".  .
23680 22 75 74 63 22 20 61 73 73 75 6d 65 73 20 74 68  "utc" assumes th
23690 61 74 20 74 68 65 20 73 74 72 69 6e 67 0a 74 6f  at the string.to
236a0 20 69 74 73 20 6c 65 66 74 20 69 73 20 69 6e 20   its left is in 
236b0 74 68 65 20 6c 6f 63 61 6c 20 74 69 6d 65 7a 6f  the local timezo
236c0 6e 65 20 61 6e 64 20 61 64 6a 75 73 74 73 20 74  ne and adjusts t
236d0 68 61 74 20 73 74 72 69 6e 67 20 74 6f 20 62 65  hat string to be
236e0 20 69 6e 20 55 54 43 2e 29 5e 0a 49 66 20 74 68   in UTC.)^.If th
236f0 65 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69  e prior string i
23700 73 20 6e 6f 74 20 69 6e 20 6c 6f 63 61 6c 74 69  s not in localti
23710 6d 65 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  me, then the res
23720 75 6c 74 20 6f 66 20 22 75 74 63 22 20 69 73 0a  ult of "utc" is.
23730 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 70 3e 0a 0a  undefined.</p>..
23740 3c 68 33 3e 45 78 61 6d 70 6c 65 73 3c 2f 68 33  <h3>Examples</h3
23750 3e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75 74 65 20  >..^(<p>Compute 
23760 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
23770 2e 3c 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  .<p>..<blockquot
23780 65 3e 53 45 4c 45 43 54 20 64 61 74 65 28 27 6e  e>SELECT date('n
23790 6f 77 27 29 3b 3c 2f 62 6c 6f 63 6b 71 75 6f 74  ow');</blockquot
237a0 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75  e>)^..^(<p>Compu
237b0 74 65 20 74 68 65 20 6c 61 73 74 20 64 61 79 20  te the last day 
237c0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  of the current m
237d0 6f 6e 74 68 2e 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  onth.</p>..<bloc
237e0 6b 71 75 6f 74 65 3e 53 45 4c 45 43 54 20 64 61  kquote>SELECT da
237f0 74 65 28 27 6e 6f 77 27 2c 27 73 74 61 72 74 20  te('now','start 
23800 6f 66 20 6d 6f 6e 74 68 27 2c 27 2b 31 20 6d 6f  of month','+1 mo
23810 6e 74 68 27 2c 27 2d 31 20 64 61 79 27 29 3b 0a  nth','-1 day');.
23820 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
23830 0a 5e 28 3c 70 3e 43 6f 6d 70 75 74 65 20 74 68  .^(<p>Compute th
23840 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  e date and time 
23850 67 69 76 65 6e 20 61 20 75 6e 69 78 20 74 69 6d  given a unix tim
23860 65 73 74 61 6d 70 20 31 30 39 32 39 34 31 34 36  estamp 109294146
23870 36 2e 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  6.</p>..<blockqu
23880 6f 74 65 3e 0a 20 20 20 20 53 45 4c 45 43 54 20  ote>.    SELECT 
23890 64 61 74 65 74 69 6d 65 28 31 30 39 32 39 34 31  datetime(1092941
238a0 34 36 36 2c 20 27 75 6e 69 78 65 70 6f 63 68 27  466, 'unixepoch'
238b0 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  );.</blockquote>
238c0 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75 74 65  )^..^(<p>Compute
238d0 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
238e0 6d 65 20 67 69 76 65 6e 20 61 20 75 6e 69 78 20  me given a unix 
238f0 74 69 6d 65 73 74 61 6d 70 20 31 30 39 32 39 34  timestamp 109294
23900 31 34 36 36 2c 20 61 6e 64 20 0a 63 6f 6d 70 65  1466, and .compe
23910 6e 73 61 74 65 20 66 6f 72 20 79 6f 75 72 20 6c  nsate for your l
23920 6f 63 61 6c 20 74 69 6d 65 7a 6f 6e 65 2e 3c 2f  ocal timezone.</
23930 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
23940 0a 20 20 53 45 4c 45 43 54 20 64 61 74 65 74 69  .  SELECT dateti
23950 6d 65 28 31 30 39 32 39 34 31 34 36 36 2c 20 27  me(1092941466, '
23960 75 6e 69 78 65 70 6f 63 68 27 2c 20 27 6c 6f 63  unixepoch', 'loc
23970 61 6c 74 69 6d 65 27 29 3b 0a 3c 2f 62 6c 6f 63  altime');.</bloc
23980 6b 71 75 6f 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e  kquote>)^..^(<p>
23990 43 6f 6d 70 75 74 65 20 74 68 65 20 63 75 72 72  Compute the curr
239a0 65 6e 74 20 75 6e 69 78 20 74 69 6d 65 73 74 61  ent unix timesta
239b0 6d 70 2e 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  mp.</p>..<blockq
239c0 75 6f 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 73  uote>.  SELECT s
239d0 74 72 66 74 69 6d 65 28 27 25 73 27 2c 27 6e 6f  trftime('%s','no
239e0 77 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  w');.</blockquot
239f0 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75  e>)^..^(<p>Compu
23a00 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
23a10 20 64 61 79 73 20 73 69 6e 63 65 20 74 68 65 20   days since the 
23a20 73 69 67 6e 69 6e 67 20 6f 66 20 74 68 65 20 55  signing of the U
23a30 53 20 44 65 63 6c 61 72 61 74 69 6f 6e 0a 6f 66  S Declaration.of
23a40 20 49 6e 64 65 70 65 6e 64 65 6e 63 65 2e 3c 2f   Independence.</
23a50 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
23a60 0a 20 20 53 45 4c 45 43 54 20 6a 75 6c 69 61 6e  .  SELECT julian
23a70 64 61 79 28 27 6e 6f 77 27 29 20 2d 20 6a 75 6c  day('now') - jul
23a80 69 61 6e 64 61 79 28 27 31 37 37 36 2d 30 37 2d  ianday('1776-07-
23a90 30 34 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  04');.</blockquo
23aa0 74 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70  te>)^..^(<p>Comp
23ab0 75 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ute the number o
23ac0 66 20 73 65 63 6f 6e 64 73 20 73 69 6e 63 65 20  f seconds since 
23ad0 61 20 70 61 72 74 69 63 75 6c 61 72 20 6d 6f 6d  a particular mom
23ae0 65 6e 74 20 69 6e 20 32 30 30 34 3a 3c 2f 70 3e  ent in 2004:</p>
23af0 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20  ..<blockquote>. 
23b00 20 53 45 4c 45 43 54 20 73 74 72 66 74 69 6d 65   SELECT strftime
23b10 28 27 25 73 27 2c 27 6e 6f 77 27 29 20 2d 20 73  ('%s','now') - s
23b20 74 72 66 74 69 6d 65 28 27 25 73 27 2c 27 32 30  trftime('%s','20
23b30 30 34 2d 30 31 2d 30 31 20 30 32 3a 33 34 3a 35  04-01-01 02:34:5
23b40 36 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74  6');.</blockquot
23b50 65 3e 29 5e 0a 0a 5e 28 3c 70 3e 0a 43 6f 6d 70  e>)^..^(<p>.Comp
23b60 75 74 65 20 74 68 65 20 64 61 74 65 20 6f 66 20  ute the date of 
23b70 74 68 65 20 66 69 72 73 74 20 54 75 65 73 64 61  the first Tuesda
23b80 79 20 69 6e 20 4f 63 74 6f 62 65 72 0a 66 6f 72  y in October.for
23b90 20 74 68 65 20 63 75 72 72 65 6e 74 20 79 65 61   the current yea
23ba0 72 2e 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  r..</p>..<blockq
23bb0 75 6f 74 65 3e 0a 20 20 53 45 4c 45 43 54 20 64  uote>.  SELECT d
23bc0 61 74 65 28 27 6e 6f 77 27 2c 27 73 74 61 72 74  ate('now','start
23bd0 20 6f 66 20 79 65 61 72 27 2c 27 2b 39 20 6d 6f   of year','+9 mo
23be0 6e 74 68 73 27 2c 27 77 65 65 6b 64 61 79 20 32  nths','weekday 2
23bf0 27 29 3b 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  ');.</blockquote
23c00 3e 29 5e 0a 0a 5e 28 3c 70 3e 43 6f 6d 70 75 74  >)^..^(<p>Comput
23c10 65 20 74 68 65 20 74 69 6d 65 20 73 69 6e 63 65  e the time since
23c20 20 74 68 65 20 75 6e 69 78 20 65 70 6f 63 68 20   the unix epoch 
23c30 69 6e 20 73 65 63 6f 6e 64 73 20 0a 28 6c 69 6b  in seconds .(lik
23c40 65 20 73 74 72 66 74 69 6d 65 28 27 25 73 27 2c  e strftime('%s',
23c50 27 6e 6f 77 27 29 20 65 78 63 65 70 74 20 69 6e  'now') except in
23c60 63 6c 75 64 65 73 20 66 72 61 63 74 69 6f 6e 61  cludes fractiona
23c70 6c 20 70 61 72 74 29 3a 3c 2f 70 3e 0a 0a 3c 62  l part):</p>..<b
23c80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 53 45 4c  lockquote>.  SEL
23c90 45 43 54 20 28 6a 75 6c 69 61 6e 64 61 79 28 27  ECT (julianday('
23ca0 6e 6f 77 27 29 20 2d 20 32 34 34 30 35 38 37 2e  now') - 2440587.
23cb0 35 29 2a 38 36 34 30 30 2e 30 3b 0a 3c 2f 62 6c  5)*86400.0;.</bl
23cc0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 0a 3c 68 33  ockquote>)^..<h3
23cd0 3e 43 61 76 65 61 74 73 20 41 6e 64 20 42 75 67  >Caveats And Bug
23ce0 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 63  s</h3>..<p>The c
23cf0 6f 6d 70 75 74 61 74 69 6f 6e 20 6f 66 20 6c 6f  omputation of lo
23d00 63 61 6c 20 74 69 6d 65 20 64 65 70 65 6e 64 73  cal time depends
23d10 20 68 65 61 76 69 6c 79 20 6f 6e 20 74 68 65 20   heavily on the 
23d20 77 68 69 6d 20 0a 6f 66 20 70 6f 6c 69 74 69 63  whim .of politic
23d30 69 61 6e 73 20 61 6e 64 20 69 73 20 74 68 75 73  ians and is thus
23d40 20 64 69 66 66 69 63 75 6c 74 20 74 6f 20 67 65   difficult to ge
23d50 74 20 63 6f 72 72 65 63 74 20 66 6f 72 20 0a 61  t correct for .a
23d60 6c 6c 20 6c 6f 63 61 6c 65 73 2e 20 5e 49 6e 20  ll locales. ^In 
23d70 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
23d80 69 6f 6e 2c 20 74 68 65 20 73 74 61 6e 64 61 72  ion, the standar
23d90 64 20 43 20 6c 69 62 72 61 72 79 20 0a 66 75 6e  d C library .fun
23da0 63 74 69 6f 6e 20 6c 6f 63 61 6c 74 69 6d 65 5f  ction localtime_
23db0 72 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 61  r() is used to a
23dc0 73 73 69 73 74 20 69 6e 20 74 68 65 20 63 61 6c  ssist in the cal
23dd0 63 75 6c 61 74 69 6f 6e 20 6f 66 20 0a 6c 6f 63  culation of .loc
23de0 61 6c 20 74 69 6d 65 2e 20 20 5e 28 54 68 65 20  al time.  ^(The 
23df0 0a 6c 6f 63 61 6c 74 69 6d 65 5f 72 28 29 20 43  .localtime_r() C
23e00 20 66 75 6e 63 74 69 6f 6e 20 6e 6f 72 6d 61 6c   function normal
23e10 6c 79 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 66 6f  ly only works fo
23e20 72 20 79 65 61 72 73 0a 62 65 74 77 65 65 6e 20  r years.between 
23e30 31 39 37 30 20 61 6e 64 20 32 30 33 37 2e 20 46  1970 and 2037. F
23e40 6f 72 20 64 61 74 65 73 20 6f 75 74 73 69 64 65  or dates outside
23e50 20 74 68 69 73 20 72 61 6e 67 65 2c 20 53 51 4c   this range, SQL
23e60 69 74 65 20 0a 61 74 74 65 6d 70 74 73 20 74 6f  ite .attempts to
23e70 20 6d 61 70 20 74 68 65 20 79 65 61 72 20 69 6e   map the year in
23e80 74 6f 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  to an equivalent
23e90 20 79 65 61 72 20 77 69 74 68 69 6e 20 0a 74 68   year within .th
23ea0 69 73 20 72 61 6e 67 65 2c 20 64 6f 20 74 68 65  is range, do the
23eb0 20 63 61 6c 63 75 6c 61 74 69 6f 6e 2c 20 74 68   calculation, th
23ec0 65 6e 20 6d 61 70 20 74 68 65 20 79 65 61 72 20  en map the year 
23ed0 62 61 63 6b 2e 29 5e 3c 2f 70 3e 0a 0a 0a 3c 70  back.)^</p>...<p
23ee0 3e 5e 28 54 68 65 73 65 20 66 75 6e 63 74 69 6f  >^(These functio
23ef0 6e 73 20 6f 6e 6c 79 20 77 6f 72 6b 20 66 6f 72  ns only work for
23f00 20 64 61 74 65 73 20 62 65 74 77 65 65 6e 20 30   dates between 0
23f10 30 30 30 2d 30 31 2d 30 31 20 30 30 3a 30 30 3a  000-01-01 00:00:
23f20 30 30 0a 61 6e 64 20 39 39 39 39 2d 31 32 2d 33  00.and 9999-12-3
23f30 31 20 32 33 3a 35 39 3a 35 39 20 28 6a 75 6c 69  1 23:59:59 (juli
23f40 61 6e 20 64 61 79 20 6e 75 6d 62 65 72 73 20 31  an day numbers 1
23f50 37 32 31 30 35 39 2e 35 20 74 68 72 6f 75 67 68  721059.5 through
23f60 20 35 33 37 33 34 38 34 2e 35 29 2e 29 5e 0a 46   5373484.5).)^.F
23f70 6f 72 20 64 61 74 65 73 20 6f 75 74 73 69 64 65  or dates outside
23f80 20 74 68 61 74 20 72 61 6e 67 65 2c 20 74 68 65   that range, the
23f90 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 73   results of thes
23fa0 65 0a 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e.functions are 
23fb0 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 70 3e 0a 0a  undefined.</p>..
23fc0 3c 70 3e 4e 6f 6e 2d 56 69 73 74 61 20 57 69 6e  <p>Non-Vista Win
23fd0 64 6f 77 73 20 70 6c 61 74 66 6f 72 6d 73 20 6f  dows platforms o
23fe0 6e 6c 79 20 73 75 70 70 6f 72 74 20 6f 6e 65 20  nly support one 
23ff0 73 65 74 20 6f 66 20 44 53 54 20 72 75 6c 65 73  set of DST rules
24000 2e 20 0a 56 69 73 74 61 20 6f 6e 6c 79 20 73 75  . .Vista only su
24010 70 70 6f 72 74 73 20 74 77 6f 2e 20 54 68 65 72  pports two. Ther
24020 65 66 6f 72 65 2c 20 6f 6e 20 74 68 65 73 65 20  efore, on these 
24030 70 6c 61 74 66 6f 72 6d 73 2c 20 0a 68 69 73 74  platforms, .hist
24040 6f 72 69 63 61 6c 20 44 53 54 20 63 61 6c 63 75  orical DST calcu
24050 6c 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  lations will be 
24060 69 6e 63 6f 72 72 65 63 74 2e 20 0a 46 6f 72 20  incorrect. .For 
24070 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20  example, in the 
24080 55 53 2c 20 69 6e 20 32 30 30 37 20 74 68 65 20  US, in 2007 the 
24090 44 53 54 20 72 75 6c 65 73 20 63 68 61 6e 67 65  DST rules change
240a0 64 2e 20 0a 4e 6f 6e 2d 56 69 73 74 61 20 57 69  d. .Non-Vista Wi
240b0 6e 64 6f 77 73 20 70 6c 61 74 66 6f 72 6d 73 20  ndows platforms 
240c0 61 70 70 6c 79 20 74 68 65 20 6e 65 77 20 32 30  apply the new 20
240d0 30 37 20 44 53 54 20 72 75 6c 65 73 20 0a 74 6f  07 DST rules .to
240e0 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 20 79 65   all previous ye
240f0 61 72 73 20 61 73 20 77 65 6c 6c 2e 20 56 69 73  ars as well. Vis
24100 74 61 20 64 6f 65 73 20 73 6f 6d 65 77 68 61 74  ta does somewhat
24110 20 62 65 74 74 65 72 0a 67 65 74 74 69 6e 67 20   better.getting 
24120 72 65 73 75 6c 74 73 20 63 6f 72 72 65 63 74 20  results correct 
24130 62 61 63 6b 20 74 6f 20 31 39 38 36 2c 20 77 68  back to 1986, wh
24140 65 6e 20 74 68 65 20 72 75 6c 65 73 20 77 65 72  en the rules wer
24150 65 20 61 6c 73 6f 20 63 68 61 6e 67 65 64 2e 3c  e also changed.<
24160 2f 70 3e 0a 0a 3c 70 3e 41 6c 6c 20 69 6e 74 65  /p>..<p>All inte
24170 72 6e 61 6c 20 63 6f 6d 70 75 74 61 74 69 6f 6e  rnal computation
24180 73 20 61 73 73 75 6d 65 20 74 68 65 20 0a 5b 68  s assume the .[h
24190 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
241a0 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 47 72 65 67  ia.org/wiki/Greg
241b0 6f 72 69 61 6e 5f 63 61 6c 65 6e 64 61 72 20 7c  orian_calendar |
241c0 20 47 72 65 67 6f 72 69 61 6e 20 63 61 6c 65 6e   Gregorian calen
241d0 64 61 72 5d 0a 73 79 73 74 65 6d 2e 20 20 49 74  dar].system.  It
241e0 20 69 73 20 61 6c 73 6f 20 61 73 73 75 6d 65 64   is also assumed
241f0 20 74 68 61 74 20 65 76 65 72 79 0a 64 61 79 20   that every.day 
24200 69 73 20 65 78 61 63 74 6c 79 20 38 36 34 30 30  is exactly 86400
24210 20 73 65 63 6f 6e 64 73 20 69 6e 20 64 75 72 61   seconds in dura
24220 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  tion.</p>..<tcl>
24230 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
24240 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24250 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24260 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
24270 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 0a  ###############.
24280 53 65 63 74 69 6f 6e 20 7b 41 67 67 72 65 67 61  Section {Aggrega
24290 74 65 20 46 75 6e 63 74 69 6f 6e 73 7d 20 61 67  te Functions} ag
242a0 67 66 75 6e 63 20 7b 2a 61 67 67 66 75 6e 63 7d  gfunc {*aggfunc}
242b0 0a 75 6e 73 65 74 20 2d 6e 6f 63 6f 6d 70 6c 61  .unset -nocompla
242c0 69 6e 20 63 6f 72 65 66 75 6e 63 73 65 74 0a 0a  in corefuncset..
242d0 66 75 6e 63 64 65 66 20 7b 61 76 67 28 58 29 7d  funcdef {avg(X)}
242e0 20 7b 2a 61 76 67 20 7b 61 76 67 28 29 20 61 67   {*avg {avg() ag
242f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
24300 7d 7d 20 7b 0a 20 20 5e 54 68 65 20 61 76 67 28  }} {.  ^The avg(
24310 29 20 66 75 6e 63 74 69 6f 6e 0a 20 20 72 65 74  ) function.  ret
24320 75 72 6e 73 20 74 68 65 20 61 76 65 72 61 67 65  urns the average
24330 20 76 61 6c 75 65 20 6f 66 20 61 6c 6c 20 6e 6f   value of all no
24340 6e 2d 4e 55 4c 4c 20 3c 69 3e 58 3c 2f 69 3e 20  n-NULL <i>X</i> 
24350 77 69 74 68 69 6e 20 61 0a 20 20 67 72 6f 75 70  within a.  group
24360 2e 20 20 5e 53 74 72 69 6e 67 20 61 6e 64 20 42  .  ^String and B
24370 4c 4f 42 20 76 61 6c 75 65 73 20 74 68 61 74 20  LOB values that 
24380 64 6f 20 6e 6f 74 20 6c 6f 6f 6b 20 6c 69 6b 65  do not look like
24390 20 6e 75 6d 62 65 72 73 20 61 72 65 0a 20 20 69   numbers are.  i
243a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 30 2e  nterpreted as 0.
243b0 0a 20 20 5e 54 68 65 20 72 65 73 75 6c 74 20 6f  .  ^The result o
243c0 66 20 61 76 67 28 29 20 69 73 20 61 6c 77 61 79  f avg() is alway
243d0 73 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  s a floating poi
243e0 6e 74 20 76 61 6c 75 65 20 61 73 20 6c 6f 6e 67  nt value as long
243f0 20 61 73 0a 20 20 61 74 20 74 68 65 72 65 20 69   as.  at there i
24400 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 6e  s at least one n
24410 6f 6e 2d 4e 55 4c 4c 20 69 6e 70 75 74 20 65 76  on-NULL input ev
24420 65 6e 20 69 66 20 61 6c 6c 0a 20 20 69 6e 70 75  en if all.  inpu
24430 74 73 20 61 72 65 20 69 6e 74 65 67 65 72 73 2e  ts are integers.
24440 20 20 5e 54 68 65 20 72 65 73 75 6c 74 20 6f 66    ^The result of
24450 20 61 76 67 28 29 20 69 73 20 4e 55 4c 4c 20 69   avg() is NULL i
24460 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 20 20  f and only if.  
24470 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6e 6f 6e  there are no non
24480 2d 4e 55 4c 4c 20 69 6e 70 75 74 73 2e 20 20 0a  -NULL inputs.  .
24490 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 63 6f 75 6e  }..funcdef {coun
244a0 74 28 58 29 20 63 6f 75 6e 74 28 2a 29 7d 20 7b  t(X) count(*)} {
244b0 2a 63 6f 75 6e 74 20 7b 63 6f 75 6e 74 28 29 20  *count {count() 
244c0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
244d0 6f 6e 7d 7d 20 7b 0a 20 20 5e 54 68 65 20 63 6f  on}} {.  ^The co
244e0 75 6e 74 28 58 29 20 66 75 6e 63 74 69 6f 6e 20  unt(X) function 
244f0 72 65 74 75 72 6e 73 0a 20 20 61 20 63 6f 75 6e  returns.  a coun
24500 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
24510 6f 66 20 74 69 6d 65 73 0a 20 20 74 68 61 74 20  of times.  that 
24520 3c 69 3e 58 3c 2f 69 3e 20 69 73 20 6e 6f 74 20  <i>X</i> is not 
24530 4e 55 4c 4c 20 69 6e 20 61 20 67 72 6f 75 70 2e  NULL in a group.
24540 20 20 5e 54 68 65 20 63 6f 75 6e 74 28 2a 29 20    ^The count(*) 
24550 66 75 6e 63 74 69 6f 6e 0a 20 20 28 77 69 74 68  function.  (with
24560 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 29 20 72   no arguments) r
24570 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
24580 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
24590 69 6e 20 74 68 65 20 67 72 6f 75 70 2e 0a 7d 0a  in the group..}.
245a0 0a 66 75 6e 63 64 65 66 20 7b 67 72 6f 75 70 5f  .funcdef {group_
245b0 63 6f 6e 63 61 74 28 58 29 20 67 72 6f 75 70 5f  concat(X) group_
245c0 63 6f 6e 63 61 74 28 58 2c 59 29 7d 20 7b 0a 20  concat(X,Y)} {. 
245d0 20 2a 67 72 6f 75 70 5f 63 6f 6e 63 61 74 20 7b   *group_concat {
245e0 67 72 6f 75 70 5f 63 6f 6e 63 61 74 28 29 20 61  group_concat() a
245f0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
24600 6e 7d 0a 7d 20 7b 0a 20 20 5e 54 68 65 20 67 72  n}.} {.  ^The gr
24610 6f 75 70 5f 63 6f 6e 63 61 74 28 29 20 66 75 6e  oup_concat() fun
24620 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 20 20  ction returns.  
24630 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
24640 73 20 74 68 65 20 63 6f 6e 63 61 74 65 6e 61 74  s the concatenat
24650 69 6f 6e 20 6f 66 0a 20 20 61 6c 6c 20 6e 6f 6e  ion of.  all non
24660 2d 4e 55 4c 4c 20 76 61 6c 75 65 73 20 6f 66 20  -NULL values of 
24670 3c 69 3e 58 3c 2f 69 3e 2e 20 20 5e 49 66 20 70  <i>X</i>.  ^If p
24680 61 72 61 6d 65 74 65 72 20 3c 69 3e 59 3c 2f 69  arameter <i>Y</i
24690 3e 20 69 73 20 70 72 65 73 65 6e 74 20 74 68 65  > is present the
246a0 6e 0a 20 20 69 74 20 69 73 20 75 73 65 64 20 61  n.  it is used a
246b0 73 20 74 68 65 20 73 65 70 61 72 61 74 6f 72 0a  s the separator.
246c0 20 20 62 65 74 77 65 65 6e 20 69 6e 73 74 61 6e    between instan
246d0 63 65 73 20 6f 66 20 3c 69 3e 58 3c 2f 69 3e 2e  ces of <i>X</i>.
246e0 20 20 5e 41 20 63 6f 6d 6d 61 20 28 22 2c 22 29    ^A comma (",")
246f0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
24700 73 65 70 61 72 61 74 6f 72 0a 20 20 69 66 20 3c  separator.  if <
24710 69 3e 59 3c 2f 69 3e 20 69 73 20 6f 6d 69 74 74  i>Y</i> is omitt
24720 65 64 2e 20 20 54 68 65 20 6f 72 64 65 72 20 6f  ed.  The order o
24730 66 20 74 68 65 20 63 6f 6e 63 61 74 65 6e 61 74  f the concatenat
24740 65 64 20 65 6c 65 6d 65 6e 74 73 20 69 73 0a 20  ed elements is. 
24750 20 61 72 62 69 74 72 61 72 79 2e 0a 7d 0a 0a 66   arbitrary..}..f
24760 75 6e 63 64 65 66 20 7b 6d 61 78 28 58 29 7d 20  uncdef {max(X)} 
24770 7b 2a 6d 61 78 41 67 67 46 75 6e 63 20 2a 61 67  {*maxAggFunc *ag
24780 67 5f 6d 61 78 20 7b 6d 61 78 28 29 20 61 67 67  g_max {max() agg
24790 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 7d  regate function}
247a0 7d 20 7b 0a 20 20 5e 54 68 65 20 6d 61 78 28 29  } {.  ^The max()
247b0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
247c0 69 6f 6e 0a 20 20 72 65 74 75 72 6e 73 20 74 68  ion.  returns th
247d0 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
247e0 6f 66 20 61 6c 6c 20 76 61 6c 75 65 73 20 69 6e  of all values in
247f0 20 74 68 65 20 67 72 6f 75 70 2e 0a 20 20 5e 54   the group..  ^T
24800 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65  he maximum value
24810 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 68   is the value th
24820 61 74 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  at would be retu
24830 72 6e 65 64 20 6c 61 73 74 20 69 6e 20 61 6e 0a  rned last in an.
24840 20 20 4f 52 44 45 52 20 42 59 20 6f 6e 20 74 68    ORDER BY on th
24850 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 20 20  e same column.  
24860 5e 41 67 67 72 65 67 61 74 65 20 6d 61 78 28 29  ^Aggregate max()
24870 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 0a 20   returns NULL . 
24880 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
24890 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6e 6f 6e  there are no non
248a0 2d 4e 55 4c 4c 20 76 61 6c 75 65 73 20 69 6e 20  -NULL values in 
248b0 74 68 65 20 67 72 6f 75 70 2e 0a 7d 0a 0a 66 75  the group..}..fu
248c0 6e 63 64 65 66 20 7b 6d 69 6e 28 58 29 7d 20 7b  ncdef {min(X)} {
248d0 2a 6d 69 6e 41 67 67 46 75 6e 63 20 2a 61 67 67  *minAggFunc *agg
248e0 5f 6d 69 6e 20 7b 6d 69 6e 28 29 20 61 67 67 72  _min {min() aggr
248f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 7d 7d  egate function}}
24900 20 7b 0a 20 20 5e 54 68 65 20 6d 69 6e 28 29 20   {.  ^The min() 
24910 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
24920 6f 6e 0a 20 20 72 65 74 75 72 6e 73 20 74 68 65  on.  returns the
24930 20 6d 69 6e 69 6d 75 6d 20 6e 6f 6e 2d 4e 55 4c   minimum non-NUL
24940 4c 20 76 61 6c 75 65 20 6f 66 20 61 6c 6c 20 76  L value of all v
24950 61 6c 75 65 73 20 69 6e 20 74 68 65 20 67 72 6f  alues in the gro
24960 75 70 2e 0a 20 20 5e 54 68 65 20 6d 69 6e 69 6d  up..  ^The minim
24970 75 6d 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  um value is the 
24980 66 69 72 73 74 20 6e 6f 6e 2d 4e 55 4c 4c 20 76  first non-NULL v
24990 61 6c 75 65 20 74 68 61 74 20 77 6f 75 6c 64 20  alue that would 
249a0 61 70 70 65 61 72 0a 20 20 69 6e 20 61 6e 20 4f  appear.  in an O
249b0 52 44 45 52 20 42 59 20 6f 66 20 74 68 65 20 63  RDER BY of the c
249c0 6f 6c 75 6d 6e 2e 0a 20 20 5e 41 67 67 72 65 67  olumn..  ^Aggreg
249d0 61 74 65 20 6d 69 6e 28 29 20 72 65 74 75 72 6e  ate min() return
249e0 73 20 4e 55 4c 4c 20 69 66 20 61 6e 64 20 6f 6e  s NULL if and on
249f0 6c 79 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ly if there are 
24a00 6e 6f 20 6e 6f 6e 2d 4e 55 4c 4c 0a 20 20 76 61  no non-NULL.  va
24a10 6c 75 65 73 20 69 6e 20 74 68 65 20 67 72 6f 75  lues in the grou
24a20 70 2e 0a 7d 0a 0a 66 75 6e 63 64 65 66 20 7b 73  p..}..funcdef {s
24a30 75 6d 28 58 29 20 74 6f 74 61 6c 28 58 29 7d 20  um(X) total(X)} 
24a40 7b 0a 20 20 2a 73 75 6d 46 75 6e 63 20 2a 73 75  {.  *sumFunc *su
24a50 6d 20 2a 74 6f 74 61 6c 0a 20 20 7b 73 75 6d 28  m *total.  {sum(
24a60 29 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  ) aggregate func
24a70 74 69 6f 6e 7d 0a 20 20 7b 74 6f 74 61 6c 28 29  tion}.  {total()
24a80 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
24a90 69 6f 6e 7d 0a 7d 20 7b 0a 20 20 5e 54 68 65 20  ion}.} {.  ^The 
24aa0 73 75 6d 28 29 20 61 6e 64 20 74 6f 74 61 6c 28  sum() and total(
24ab0 29 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  ) aggregate func
24ac0 74 69 6f 6e 73 0a 20 20 72 65 74 75 72 6e 20 73  tions.  return s
24ad0 75 6d 20 6f 66 20 61 6c 6c 20 6e 6f 6e 2d 4e 55  um of all non-NU
24ae0 4c 4c 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  LL values in the
24af0 20 67 72 6f 75 70 2e 0a 20 20 5e 49 66 20 74 68   group..  ^If th
24b00 65 72 65 20 61 72 65 20 6e 6f 20 6e 6f 6e 2d 4e  ere are no non-N
24b10 55 4c 4c 20 69 6e 70 75 74 20 72 6f 77 73 20 74  ULL input rows t
24b20 68 65 6e 20 73 75 6d 28 29 20 72 65 74 75 72 6e  hen sum() return
24b30 73 0a 20 20 4e 55 4c 4c 20 62 75 74 20 74 6f 74  s.  NULL but tot
24b40 61 6c 28 29 20 72 65 74 75 72 6e 73 20 30 2e 30  al() returns 0.0
24b50 2e 0a 20 20 4e 55 4c 4c 20 69 73 20 6e 6f 74 20  ..  NULL is not 
24b60 6e 6f 72 6d 61 6c 6c 79 20 61 20 68 65 6c 70 66  normally a helpf
24b70 75 6c 20 72 65 73 75 6c 74 20 66 6f 72 20 74 68  ul result for th
24b80 65 20 73 75 6d 20 6f 66 20 6e 6f 20 72 6f 77 73  e sum of no rows
24b90 0a 20 20 62 75 74 20 74 68 65 20 53 51 4c 20 73  .  but the SQL s
24ba0 74 61 6e 64 61 72 64 20 72 65 71 75 69 72 65 73  tandard requires
24bb0 20 69 74 20 61 6e 64 20 6d 6f 73 74 20 6f 74 68   it and most oth
24bc0 65 72 0a 20 20 53 51 4c 20 64 61 74 61 62 61 73  er.  SQL databas
24bd0 65 20 65 6e 67 69 6e 65 73 20 69 6d 70 6c 65 6d  e engines implem
24be0 65 6e 74 20 73 75 6d 28 29 20 74 68 61 74 20 77  ent sum() that w
24bf0 61 79 20 73 6f 20 53 51 4c 69 74 65 20 64 6f 65  ay so SQLite doe
24c00 73 20 69 74 20 69 6e 20 74 68 65 0a 20 20 73 61  s it in the.  sa
24c10 6d 65 20 77 61 79 20 69 6e 20 6f 72 64 65 72 20  me way in order 
24c20 74 6f 20 62 65 20 63 6f 6d 70 61 74 69 62 6c 65  to be compatible
24c30 2e 20 20 20 54 68 65 20 6e 6f 6e 2d 73 74 61 6e  .   The non-stan
24c40 64 61 72 64 20 74 6f 74 61 6c 28 29 20 66 75 6e  dard total() fun
24c50 63 74 69 6f 6e 0a 20 20 69 73 20 70 72 6f 76 69  ction.  is provi
24c60 64 65 64 20 61 73 20 61 20 63 6f 6e 76 65 6e 69  ded as a conveni
24c70 65 6e 74 20 77 61 79 20 74 6f 20 77 6f 72 6b 20  ent way to work 
24c80 61 72 6f 75 6e 64 20 74 68 69 73 20 64 65 73 69  around this desi
24c90 67 6e 20 70 72 6f 62 6c 65 6d 0a 20 20 69 6e 20  gn problem.  in 
24ca0 74 68 65 20 53 51 4c 20 6c 61 6e 67 75 61 67 65  the SQL language
24cb0 2e 3c 2f 70 3e 0a 0a 20 20 3c 70 3e 5e 54 68 65  .</p>..  <p>^The
24cc0 20 72 65 73 75 6c 74 20 6f 66 20 74 6f 74 61 6c   result of total
24cd0 28 29 20 69 73 20 61 6c 77 61 79 73 20 61 20 66  () is always a f
24ce0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
24cf0 6c 75 65 2e 0a 20 20 5e 54 68 65 20 72 65 73 75  lue..  ^The resu
24d00 6c 74 20 6f 66 20 73 75 6d 28 29 20 69 73 20 61  lt of sum() is a
24d10 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  n integer value 
24d20 69 66 20 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20  if all non-NULL 
24d30 69 6e 70 75 74 73 20 61 72 65 20 69 6e 74 65 67  inputs are integ
24d40 65 72 73 2e 0a 20 20 5e 49 66 20 61 6e 79 20 69  ers..  ^If any i
24d50 6e 70 75 74 20 74 6f 20 73 75 6d 28 29 20 69 73  nput to sum() is
24d60 20 6e 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65   neither an inte
24d70 67 65 72 20 6f 72 20 61 20 4e 55 4c 4c 0a 20 20  ger or a NULL.  
24d80 74 68 65 6e 20 73 75 6d 28 29 20 72 65 74 75 72  then sum() retur
24d90 6e 73 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ns a floating po
24da0 69 6e 74 20 76 61 6c 75 65 0a 20 20 77 68 69 63  int value.  whic
24db0 68 20 6d 69 67 68 74 20 62 65 20 61 6e 20 61 70  h might be an ap
24dc0 70 72 6f 78 69 6d 61 74 69 6f 6e 20 74 6f 20 74  proximation to t
24dd0 68 65 20 74 72 75 65 20 73 75 6d 2e 3c 2f 70 3e  he true sum.</p>
24de0 0a 0a 20 20 3c 70 3e 5e 53 75 6d 28 29 20 77 69  ..  <p>^Sum() wi
24df0 6c 6c 20 74 68 72 6f 77 20 61 6e 20 22 69 6e 74  ll throw an "int
24e00 65 67 65 72 20 6f 76 65 72 66 6c 6f 77 22 20 65  eger overflow" e
24e10 78 63 65 70 74 69 6f 6e 20 69 66 20 61 6c 6c 20  xception if all 
24e20 69 6e 70 75 74 73 0a 20 20 61 72 65 20 69 6e 74  inputs.  are int
24e30 65 67 65 72 73 20 6f 72 20 4e 55 4c 4c 0a 20 20  egers or NULL.  
24e40 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 6f  and an integer o
24e50 76 65 72 66 6c 6f 77 20 6f 63 63 75 72 73 20 61  verflow occurs a
24e60 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
24e70 6e 67 20 74 68 65 20 63 6f 6d 70 75 74 61 74 69  ng the computati
24e80 6f 6e 2e 0a 20 20 5e 54 6f 74 61 6c 28 29 20 6e  on..  ^Total() n
24e90 65 76 65 72 20 74 68 72 6f 77 73 20 61 6e 20 69  ever throws an i
24ea0 6e 74 65 67 65 72 20 6f 76 65 72 66 6c 6f 77 2e  nteger overflow.
24eb0 0a 7d 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c 74 63 6c  .}.</tcl>...<tcl
24ec0 3e 0a 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  >.RecursiveBubbl
24ed0 65 44 69 61 67 72 61 6d 20 61 67 67 72 65 67 61  eDiagram aggrega
24ee0 74 65 2d 66 75 6e 63 74 69 6f 6e 2d 69 6e 76 6f  te-function-invo
24ef0 63 61 74 69 6f 6e 0a 3c 2f 74 63 6c 3e 0a 0a 3c  cation.</tcl>..<
24f00 70 3e 0a 54 68 65 20 61 67 67 72 65 67 61 74 65  p>.The aggregate
24f10 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 6f 77 6e   functions shown
24f20 20 62 65 6c 6f 77 20 61 72 65 20 61 76 61 69 6c   below are avail
24f30 61 62 6c 65 20 62 79 20 64 65 66 61 75 6c 74 2e  able by default.
24f40 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 61 67 67    Additional.agg
24f50 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73  regate functions
24f60 20 77 72 69 74 74 65 6e 20 69 6e 20 43 20 6d 61   written in C ma
24f70 79 20 62 65 20 61 64 64 65 64 20 75 73 69 6e 67  y be added using
24f80 20 74 68 65 20 0a 5b 73 71 6c 69 74 65 33 5f 63   the .[sqlite3_c
24f90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
24fa0 5d 3c 2f 61 3e 0a 41 50 49 2e 3c 2f 70 3e 0a 0a  ]</a>.API.</p>..
24fb0 3c 70 3e 0a 5e 49 6e 20 61 6e 79 20 61 67 67 72  <p>.^In any aggr
24fc0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 74  egate function t
24fd0 68 61 74 20 74 61 6b 65 73 20 61 20 73 69 6e 67  hat takes a sing
24fe0 6c 65 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 61  le argument, tha
24ff0 74 20 61 72 67 75 6d 65 6e 74 0a 63 61 6e 20 62  t argument.can b
25000 65 20 70 72 65 63 65 64 65 64 20 62 79 20 74 68  e preceded by th
25010 65 20 6b 65 79 77 6f 72 64 20 44 49 53 54 49 4e  e keyword DISTIN
25020 43 54 2e 20 20 5e 49 6e 20 73 75 63 68 20 63 61  CT.  ^In such ca
25030 73 65 73 2c 20 64 75 70 6c 69 63 61 74 65 0a 65  ses, duplicate.e
25040 6c 65 6d 65 6e 74 73 20 61 72 65 20 66 69 6c 74  lements are filt
25050 65 72 65 64 20 62 65 66 6f 72 65 20 62 65 69 6e  ered before bein
25060 67 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  g passed into th
25070 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
25080 74 69 6f 6e 2e 0a 5e 46 6f 72 20 65 78 61 6d 70  tion..^For examp
25090 6c 65 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  le, the function
250a0 20 22 63 6f 75 6e 74 28 64 69 73 74 69 6e 63 74   "count(distinct
250b0 20 58 29 22 20 77 69 6c 6c 20 72 65 74 75 72 6e   X)" will return
250c0 20 74 68 65 20 6e 75 6d 62 65 72 0a 6f 66 20 64   the number.of d
250d0 69 73 74 69 6e 63 74 20 76 61 6c 75 65 73 20 6f  istinct values o
250e0 66 20 63 6f 6c 75 6d 6e 20 58 20 69 6e 73 74 65  f column X inste
250f0 61 64 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  ad of the total 
25100 6e 75 6d 62 65 72 20 6f 66 20 6e 6f 6e 2d 6e 75  number of non-nu
25110 6c 6c 0a 76 61 6c 75 65 73 20 69 6e 20 63 6f 6c  ll.values in col
25120 75 6d 6e 20 58 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63  umn X..</p>..<tc
25130 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 61 67  l>hd_fragment ag
25140 67 66 69 6c 74 65 72 20 7b 46 49 4c 54 45 52 20  gfilter {FILTER 
25150 63 6c 61 75 73 65 20 6f 6e 20 61 67 67 72 65 67  clause on aggreg
25160 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 7d 3c 2f  ate functions}</
25170 74 63 6c 3e 0a 3c 70 3e 0a 49 66 20 61 20 46 49  tcl>.<p>.If a FI
25180 4c 54 45 52 20 63 6c 61 75 73 65 20 69 73 20 70  LTER clause is p
25190 72 6f 76 69 64 65 64 2c 20 74 68 65 6e 20 6f 6e  rovided, then on
251a0 6c 79 20 72 6f 77 73 20 66 6f 72 20 77 68 69 63  ly rows for whic
251b0 68 20 74 68 65 20 3c 69 3e 65 78 70 72 3c 2f 69  h the <i>expr</i
251c0 3e 20 69 73 0a 74 72 75 65 20 61 72 65 20 69 6e  > is.true are in
251d0 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 61 67  cluded in the ag
251e0 67 72 65 67 61 74 65 2e 0a 3c 2f 70 3e 0a 0a 3c  gregate..</p>..<
251f0 74 63 6c 3e 0a 73 65 74 20 6c 78 20 7b 7d 0a 66  tcl>.set lx {}.f
25200 6f 72 65 61 63 68 20 62 61 73 65 73 79 6e 74 61  oreach basesynta
25210 78 20 5b 61 72 72 61 79 20 6e 61 6d 65 73 20 63  x [array names c
25220 6f 72 65 66 75 6e 63 73 65 74 5d 20 7b 0a 20 20  orefuncset] {.  
25230 66 6f 72 65 61 63 68 20 7b 73 79 6e 74 61 78 20  foreach {syntax 
25240 6b 65 79 77 6f 72 64 73 20 64 65 73 63 7d 20 24  keywords desc} $
25250 63 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61 73  corefuncset($bas
25260 65 73 79 6e 74 61 78 29 20 62 72 65 61 6b 0a 20  esyntax) break. 
25270 20 72 65 67 65 78 70 20 7b 5e 5b 61 2d 7a 5f 5d   regexp {^[a-z_]
25280 2b 7d 20 24 62 61 73 65 73 79 6e 74 61 78 20 66  +} $basesyntax f
25290 72 61 67 6d 65 6e 74 0a 20 20 66 6f 72 65 61 63  ragment.  foreac
252a0 68 20 63 6f 72 65 73 79 6e 74 61 78 20 24 73 79  h coresyntax $sy
252b0 6e 74 61 78 20 7b 0a 20 20 20 20 6c 61 70 70 65  ntax {.    lappe
252c0 6e 64 20 6c 78 20 5b 6c 69 73 74 20 24 66 72 61  nd lx [list $fra
252d0 67 6d 65 6e 74 20 24 63 6f 72 65 73 79 6e 74 61  gment $coresynta
252e0 78 20 30 5d 0a 20 20 7d 0a 7d 0a 68 64 5f 6c 69  x 0].  }.}.hd_li
252f0 73 74 5f 6f 66 5f 6c 69 6e 6b 73 20 7b 7d 20 32  st_of_links {} 2
25300 32 35 20 5b 6c 73 6f 72 74 20 2d 69 6e 64 65 78  25 [lsort -index
25310 20 31 20 24 6c 78 5d 0a 0a 68 64 5f 70 75 74 73   1 $lx]..hd_puts
25320 6e 6c 20 22 3c 68 72 20 63 6c 61 73 73 3d 27 78  nl "<hr class='x
25330 68 72 27 3e 22 0a 68 64 5f 70 75 74 73 6e 6c 20  hr'>".hd_putsnl 
25340 22 3c 64 6c 3e 22 0a 66 6f 72 65 61 63 68 20 62  "<dl>".foreach b
25350 61 73 65 73 79 6e 74 61 78 20 5b 6c 73 6f 72 74  asesyntax [lsort
25360 20 5b 61 72 72 61 79 20 6e 61 6d 65 73 20 63 6f   [array names co
25370 72 65 66 75 6e 63 73 65 74 5d 5d 20 7b 0a 20 20  refuncset]] {.  
25380 66 6f 72 65 61 63 68 20 7b 73 79 6e 74 61 78 20  foreach {syntax 
25390 6b 65 79 77 6f 72 64 73 20 64 65 73 63 7d 20 24  keywords desc} $
253a0 63 6f 72 65 66 75 6e 63 73 65 74 28 24 62 61 73  corefuncset($bas
253b0 65 73 79 6e 74 61 78 29 20 62 72 65 61 6b 0a 20  esyntax) break. 
253c0 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 5c 73   regsub -all {\s
253d0 2b 7d 20 5b 73 74 72 69 6e 67 20 74 72 69 6d 20  +} [string trim 
253e0 24 73 79 6e 74 61 78 5d 20 7b 3c 62 72 20 2f 3e  $syntax] {<br />
253f0 7d 20 73 79 6e 74 61 78 0a 20 20 72 65 67 73 75  } syntax.  regsu
25400 62 20 2d 61 6c 6c 20 7b 5c 28 28 5b 5e 2a 29 5d  b -all {\(([^*)]
25410 2b 29 5c 29 7d 20 24 73 79 6e 74 61 78 20 7b 28  +)\)} $syntax {(
25420 3c 69 3e 5c 31 3c 2f 69 3e 29 7d 20 73 79 6e 74  <i>\1</i>)} synt
25430 61 78 0a 20 20 72 65 67 73 75 62 20 2d 61 6c 6c  ax.  regsub -all
25440 20 7b 2c 7d 20 24 73 79 6e 74 61 78 20 7b 3c 2f   {,} $syntax {</
25450 69 3e 2c 3c 69 3e 7d 20 73 79 6e 74 61 78 0a 20  i>,<i>} syntax. 
25460 20 72 65 67 73 75 62 20 2d 61 6c 6c 20 7b 3c 69   regsub -all {<i
25470 3e 5c 2e 5c 2e 5c 2e 3c 2f 69 3e 7d 20 24 73 79  >\.\.\.</i>} $sy
25480 6e 74 61 78 20 7b 2e 2e 2e 7d 20 73 79 6e 74 61  ntax {...} synta
25490 78 0a 20 20 72 65 67 65 78 70 20 7b 5e 5b 61 2d  x.  regexp {^[a-
254a0 7a 5d 2b 7d 20 24 62 61 73 65 73 79 6e 74 61 78  z]+} $basesyntax
254b0 20 66 72 61 67 6d 65 6e 74 0a 20 20 69 66 20 7b   fragment.  if {
254c0 5b 6c 6c 65 6e 67 74 68 20 24 6b 65 79 77 6f 72  [llength $keywor
254d0 64 73 5d 3d 3d 30 7d 20 7b 0a 20 20 20 20 72 65  ds]==0} {.    re
254e0 67 65 78 70 20 7b 5b 61 2d 7a 5f 5d 2b 7d 20 24  gexp {[a-z_]+} $
254f0 73 79 6e 74 61 78 20 6e 61 6d 65 0a 20 20 20 20  syntax name.    
25500 68 64 5f 66 72 61 67 6d 65 6e 74 20 24 6e 61 6d  hd_fragment $nam
25510 65 20 2a 24 6e 61 6d 65 20 22 24 7b 6e 61 6d 65  e *$name "${name
25520 7d 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  }() SQL function
25530 22 0a 20 20 7d 20 65 6c 73 65 20 7b 0a 20 20 20  ".  } else {.   
25540 20 73 65 74 20 66 72 61 67 6e 61 6d 65 20 5b 6c   set fragname [l
25550 69 6e 64 65 78 20 24 6b 65 79 77 6f 72 64 73 20  index $keywords 
25560 30 5d 0a 20 20 20 20 72 65 67 73 75 62 20 2d 61  0].    regsub -a
25570 6c 6c 20 7b 5b 5e 61 2d 7a 5d 7d 20 24 66 72 61  ll {[^a-z]} $fra
25580 67 6e 61 6d 65 20 7b 7d 20 66 72 61 67 6e 61 6d  gname {} fragnam
25590 65 0a 20 20 20 20 68 64 5f 66 72 61 67 6d 65 6e  e.    hd_fragmen
255a0 74 20 24 66 72 61 67 6e 61 6d 65 0a 20 20 20 20  t $fragname.    
255b0 65 76 61 6c 20 68 64 5f 6b 65 79 77 6f 72 64 73  eval hd_keywords
255c0 20 5b 73 74 72 69 6e 67 20 6d 61 70 20 7b 5c 6e   [string map {\n
255d0 20 7b 20 7d 7d 20 24 6b 65 79 77 6f 72 64 73 5d   { }} $keywords]
255e0 0a 20 20 7d 0a 20 20 68 64 5f 70 75 74 73 20 22  .  }.  hd_puts "
255f0 3c 64 74 3e 3c 70 3e 3c 62 3e 24 73 79 6e 74 61  <dt><p><b>$synta
25600 78 3c 2f 62 3e 3c 2f 64 74 3e 22 0a 20 20 68 64  x</b></dt>".  hd
25610 5f 72 65 73 6f 6c 76 65 20 22 3c 64 64 3e 3c 70  _resolve "<dd><p
25620 3e 24 64 65 73 63 3c 2f 64 64 3e 5c 6e 22 0a 7d  >$desc</dd>\n".}
25630 0a 68 64 5f 70 75 74 73 6e 6c 20 22 3c 2f 64 6c  .hd_putsnl "</dl
25640 3e 22 0a 0a 23 23 23 23 23 23 23 23 23 23 23 23  >"..############
25650 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25660 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25670 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25680 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
25690 23 23 0a 53 65 63 74 69 6f 6e 20 49 4e 53 45 52  ##.Section INSER
256a0 54 20 69 6e 73 65 72 74 20 7b 49 4e 53 45 52 54  T insert {INSERT
256b0 20 2a 49 4e 53 45 52 54 73 7d 0a 0a 52 65 63 75   *INSERTs}..Recu
256c0 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72  rsiveBubbleDiagr
256d0 61 6d 20 69 6e 73 65 72 74 2d 73 74 6d 74 0a 3c  am insert-stmt.<
256e0 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68 65 20 49 4e  /tcl>..<p>The IN
256f0 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20 63  SERT statement c
25700 6f 6d 65 73 20 69 6e 20 74 68 72 65 65 20 62 61  omes in three ba
25710 73 69 63 20 66 6f 72 6d 73 2e 20 20 0a 3c 6f 6c  sic forms.  .<ol
25720 3e 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 49 4e 53 45  >.<li><p><b>INSE
25730 52 54 20 49 4e 54 4f 20 3c 2f 62 3e 3c 69 3e 74  RT INTO </b><i>t
25740 61 62 6c 65 3c 2f 69 3e 3c 62 3e 20 56 41 4c 55  able</i><b> VALU
25750 45 53 28 2e 2e 2e 29 3b 3c 2f 62 3e 0a 3c 70 3e  ES(...);</b>.<p>
25760 5e 54 68 65 20 66 69 72 73 74 20 66 6f 72 6d 20  ^The first form 
25770 28 77 69 74 68 20 74 68 65 20 22 56 41 4c 55 45  (with the "VALUE
25780 53 22 20 6b 65 79 77 6f 72 64 29 20 63 72 65 61  S" keyword) crea
25790 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
257a0 6e 65 77 20 72 6f 77 73 20 69 6e 0a 61 6e 20 65  new rows in.an e
257b0 78 69 73 74 69 6e 67 20 74 61 62 6c 65 2e 20 5e  xisting table. ^
257c0 49 66 20 74 68 65 20 3c 79 79 74 65 72 6d 3e 63  If the <yyterm>c
257d0 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f 79 79 74 65  olumn-name</yyte
257e0 72 6d 3e 20 6c 69 73 74 20 61 66 74 65 72 0a 3c  rm> list after.<
257f0 79 79 74 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d  yyterm>table-nam
25800 65 3c 2f 79 79 74 65 72 6d 3e 20 69 73 20 6f 6d  e</yyterm> is om
25810 69 74 74 65 64 20 74 68 65 6e 20 74 68 65 20 6e  itted then the n
25820 75 6d 62 65 72 0a 6f 66 20 76 61 6c 75 65 73 20  umber.of values 
25830 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 65 61  inserted into ea
25840 63 68 20 72 6f 77 0a 6d 75 73 74 20 62 65 20 74  ch row.must be t
25850 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 6e  he same as the n
25860 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
25870 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 5e   in the table. ^
25880 49 6e 20 74 68 69 73 20 63 61 73 65 0a 74 68 65  In this case.the
25890 20 72 65 73 75 6c 74 20 6f 66 20 65 76 61 6c 75   result of evalu
258a0 61 74 69 6e 67 20 74 68 65 20 6c 65 66 74 2d 6d  ating the left-m
258b0 6f 73 74 20 65 78 70 72 65 73 73 69 6f 6e 20 66  ost expression f
258c0 72 6f 6d 20 65 61 63 68 20 74 65 72 6d 20 6f 66  rom each term of
258d0 0a 74 68 65 20 56 41 4c 55 45 53 20 6c 69 73 74  .the VALUES list
258e0 20 69 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74   is inserted int
258f0 6f 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20  o the left-most 
25900 63 6f 6c 75 6d 6e 20 6f 66 20 65 61 63 68 20 6e  column of each n
25910 65 77 20 72 6f 77 2c 0a 61 6e 64 20 73 6f 20 66  ew row,.and so f
25920 6f 72 74 68 20 66 6f 72 20 65 61 63 68 20 73 75  orth for each su
25930 62 73 65 71 75 65 6e 74 20 65 78 70 72 65 73 73  bsequent express
25940 69 6f 6e 2e 20 5e 49 66 20 61 20 3c 79 79 74 65  ion. ^If a <yyte
25950 72 6d 3e 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 3c 2f  rm>column-name</
25960 79 79 74 65 72 6d 3e 0a 6c 69 73 74 20 69 73 20  yyterm>.list is 
25970 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
25980 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
25990 6c 75 65 73 20 69 6e 20 65 61 63 68 20 74 65 72  lues in each ter
259a0 6d 20 6f 66 20 74 68 65 0a 56 41 4c 55 45 20 6c  m of the.VALUE l
259b0 69 73 74 20 6d 75 73 74 20 6d 61 74 63 68 20 74  ist must match t
259c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 73 70 65  he number of.spe
259d0 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  cified columns. 
259e0 5e 45 61 63 68 20 6f 66 20 74 68 65 20 6e 61 6d  ^Each of the nam
259f0 65 64 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68  ed columns of th
25a00 65 20 6e 65 77 20 72 6f 77 20 69 73 20 70 6f 70  e new row is pop
25a10 75 6c 61 74 65 64 0a 77 69 74 68 20 74 68 65 20  ulated.with the 
25a20 72 65 73 75 6c 74 73 20 6f 66 20 65 76 61 6c 75  results of evalu
25a30 61 74 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73  ating the corres
25a40 70 6f 6e 64 69 6e 67 20 56 41 4c 55 45 53 20 65  ponding VALUES e
25a50 78 70 72 65 73 73 69 6f 6e 2e 20 5e 54 61 62 6c  xpression. ^Tabl
25a60 65 0a 63 6f 6c 75 6d 6e 73 20 74 68 61 74 20 64  e.columns that d
25a70 6f 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20  o not appear in 
25a80 74 68 65 20 63 6f 6c 75 6d 6e 20 6c 69 73 74 20  the column list 
25a90 61 72 65 20 70 6f 70 75 6c 61 74 65 64 20 77 69  are populated wi
25aa0 74 68 20 74 68 65 20 0a 5b 64 65 66 61 75 6c 74  th the .[default
25ab0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 5d 20 28   column value] (
25ac0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
25ad0 74 20 6f 66 20 74 68 65 20 5b 43 52 45 41 54 45  t of the [CREATE
25ae0 20 54 41 42 4c 45 5d 20 73 74 61 74 65 6d 65 6e   TABLE] statemen
25af0 74 29 2c 20 6f 72 0a 77 69 74 68 20 4e 55 4c 4c  t), or.with NULL
25b00 20 69 66 20 6e 6f 20 5b 64 65 66 61 75 6c 74 20   if no [default 
25b10 76 61 6c 75 65 5d 20 69 73 20 73 70 65 63 69 66  value] is specif
25b20 69 65 64 2e 0a 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e  ied...<li><p><b>
25b30 49 4e 53 45 52 54 20 49 4e 54 4f 20 3c 2f 62 3e  INSERT INTO </b>
25b40 3c 69 3e 74 61 62 6c 65 3c 2f 69 3e 3c 62 3e 20  <i>table</i><b> 
25b50 53 45 4c 45 43 54 20 2e 2e 2e 3b 3c 2f 62 3e 0a  SELECT ...;</b>.
25b60 3c 70 3e 54 68 65 20 73 65 63 6f 6e 64 20 66 6f  <p>The second fo
25b70 72 6d 20 6f 66 20 74 68 65 20 49 4e 53 45 52 54  rm of the INSERT
25b80 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61   statement conta
25b90 69 6e 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73  ins a [SELECT] s
25ba0 74 61 74 65 6d 65 6e 74 0a 69 6e 73 74 65 61 64  tatement.instead
25bb0 20 6f 66 20 61 20 56 41 4c 55 45 53 20 63 6c 61   of a VALUES cla
25bc0 75 73 65 2e 20 5e 41 20 6e 65 77 20 65 6e 74 72  use. ^A new entr
25bd0 79 20 69 73 20 69 6e 73 65 72 74 65 64 20 69 6e  y is inserted in
25be0 74 6f 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  to the table for
25bf0 20 65 61 63 68 0a 72 6f 77 20 6f 66 20 64 61 74   each.row of dat
25c00 61 20 72 65 74 75 72 6e 65 64 20 62 79 20 65 78  a returned by ex
25c10 65 63 75 74 69 6e 67 20 74 68 65 20 53 45 4c 45  ecuting the SELE
25c20 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 49  CT statement. ^I
25c30 66 20 61 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 20  f a column-list 
25c40 69 73 0a 73 70 65 63 69 66 69 65 64 2c 20 74 68  is.specified, th
25c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
25c60 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
25c70 74 20 6f 66 20 74 68 65 20 53 45 4c 45 43 54 20  t of the SELECT 
25c80 6d 75 73 74 20 62 65 20 74 68 65 20 73 61 6d 65  must be the same
25c90 0a 61 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .as the number o
25ca0 66 20 69 74 65 6d 73 20 69 6e 20 74 68 65 20 63  f items in the c
25cb0 6f 6c 75 6d 6e 2d 6c 69 73 74 2e 20 5e 4f 74 68  olumn-list. ^Oth
25cc0 65 72 77 69 73 65 2c 20 69 66 20 6e 6f 20 63 6f  erwise, if no co
25cd0 6c 75 6d 6e 2d 6c 69 73 74 20 69 73 0a 73 70 65  lumn-list is.spe
25ce0 63 69 66 69 65 64 2c 20 74 68 65 20 6e 75 6d 62  cified, the numb
25cf0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25d00 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
25d10 68 65 20 53 45 4c 45 43 54 20 6d 75 73 74 20 62  he SELECT must b
25d20 65 20 74 68 65 20 73 61 6d 65 0a 61 73 20 74 68  e the same.as th
25d30 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
25d40 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65  mns in the table
25d50 2e 20 5e 41 6e 79 20 53 45 4c 45 43 54 20 73 74  . ^Any SELECT st
25d60 61 74 65 6d 65 6e 74 2c 20 69 6e 63 6c 75 64 69  atement, includi
25d70 6e 67 0a 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  ng.[compound SEL
25d80 45 43 54 73 5d 20 61 6e 64 20 53 45 4c 45 43 54  ECTs] and SELECT
25d90 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68   statements with
25da0 20 5b 4f 52 44 45 52 20 42 59 5d 20 61 6e 64 2f   [ORDER BY] and/
25db0 6f 72 20 5b 4c 49 4d 49 54 5d 20 63 6c 61 75 73  or [LIMIT] claus
25dc0 65 73 2c 20 0a 6d 61 79 20 62 65 20 75 73 65 64  es, .may be used
25dd0 20 69 6e 20 61 6e 20 49 4e 53 45 52 54 20 73 74   in an INSERT st
25de0 61 74 65 6d 65 6e 74 20 6f 66 20 74 68 69 73 20  atement of this 
25df0 66 6f 72 6d 2e 0a 0a 3c 70 3e 54 6f 20 61 76 6f  form...<p>To avo
25e00 69 64 20 61 20 70 61 72 73 69 6e 67 20 61 6d 62  id a parsing amb
25e10 69 67 75 69 74 79 2c 20 74 68 65 20 53 45 4c 45  iguity, the SELE
25e20 43 54 20 73 74 61 74 65 6d 65 6e 74 20 73 68 6f  CT statement sho
25e30 75 6c 64 20 61 6c 77 61 79 73 0a 63 6f 6e 74 61  uld always.conta
25e40 69 6e 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  in a WHERE claus
25e50 65 2c 20 65 76 65 6e 20 69 66 20 74 68 61 74 20  e, even if that 
25e60 63 6c 61 75 73 65 20 69 73 20 73 69 6d 70 6c 79  clause is simply
25e70 20 22 57 48 45 52 45 20 74 72 75 65 22 2c 0a 69   "WHERE true",.i
25e80 66 20 74 68 65 20 5b 75 70 73 65 72 74 2d 63 6c  f the [upsert-cl
25e90 61 75 73 65 5d 20 69 73 20 70 72 65 73 65 6e 74  ause] is present
25ea0 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 57  .  Without the W
25eb0 48 45 52 45 20 63 6c 61 75 73 65 2c 20 74 68 65  HERE clause, the
25ec0 0a 70 61 72 73 65 72 20 64 6f 65 73 20 6e 6f 74  .parser does not
25ed0 20 6b 6e 6f 77 20 69 66 20 74 68 65 20 74 6f 6b   know if the tok
25ee0 65 6e 20 22 4f 4e 22 20 69 73 20 70 61 72 74 20  en "ON" is part 
25ef0 6f 66 20 61 20 6a 6f 69 6e 20 63 6f 6e 73 74 72  of a join constr
25f00 61 69 6e 74 0a 6f 6e 20 74 68 65 20 53 45 4c 45  aint.on the SELE
25f10 43 54 2c 20 6f 72 20 74 68 65 20 62 65 67 69 6e  CT, or the begin
25f20 6e 69 6e 67 20 6f 66 20 74 68 65 20 5b 75 70 73  ning of the [ups
25f30 65 72 74 2d 63 6c 61 75 73 65 5d 2e 0a 0a 3c 6c  ert-clause]...<l
25f40 69 3e 3c 70 3e 3c 62 3e 49 4e 53 45 52 54 20 49  i><p><b>INSERT I
25f50 4e 54 4f 20 3c 2f 62 3e 3c 69 3e 74 61 62 6c 65  NTO </b><i>table
25f60 3c 2f 69 3e 3c 62 3e 20 44 45 46 41 55 4c 54 20  </i><b> DEFAULT 
25f70 56 41 4c 55 45 53 3b 3c 2f 62 3e 0a 3c 70 3e 54  VALUES;</b>.<p>T
25f80 68 65 20 74 68 69 72 64 20 66 6f 72 6d 20 6f 66  he third form of
25f90 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74 65   an INSERT state
25fa0 6d 65 6e 74 20 69 73 20 77 69 74 68 20 44 45 46  ment is with DEF
25fb0 41 55 4c 54 20 56 41 4c 55 45 53 2e 0a 5e 28 54  AULT VALUES..^(T
25fc0 68 65 20 49 4e 53 45 52 54 20 2e 2e 2e 20 44 45  he INSERT ... DE
25fd0 46 41 55 4c 54 20 56 41 4c 55 45 53 20 73 74 61  FAULT VALUES sta
25fe0 74 65 6d 65 6e 74 20 69 6e 73 65 72 74 73 20 61  tement inserts a
25ff0 20 73 69 6e 67 6c 65 20 6e 65 77 20 72 6f 77 20   single new row 
26000 69 6e 74 6f 20 74 68 65 0a 6e 61 6d 65 64 20 74  into the.named t
26010 61 62 6c 65 2e 29 5e 20 5e 45 61 63 68 20 63 6f  able.)^ ^Each co
26020 6c 75 6d 6e 20 6f 66 20 74 68 65 20 6e 65 77 20  lumn of the new 
26030 72 6f 77 20 69 73 20 70 6f 70 75 6c 61 74 65 64  row is populated
26040 20 77 69 74 68 20 69 74 73 20 0a 5b 64 65 66 61   with its .[defa
26050 75 6c 74 20 76 61 6c 75 65 5d 2c 20 6f 72 20 77  ult value], or w
26060 69 74 68 20 61 20 4e 55 4c 4c 20 69 66 20 6e 6f  ith a NULL if no
26070 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
26080 73 20 73 70 65 63 69 66 69 65 64 20 0a 61 73 20  s specified .as 
26090 70 61 72 74 20 6f 66 20 74 68 65 20 63 6f 6c 75  part of the colu
260a0 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20 69 6e  mn definition in
260b0 20 74 68 65 20 5b 43 52 45 41 54 45 20 54 41 42   the [CREATE TAB
260c0 4c 45 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54  LE] statement..T
260d0 68 65 20 5b 75 70 73 65 72 74 2d 63 6c 61 75 73  he [upsert-claus
260e0 65 5d 20 69 73 20 6e 6f 74 20 73 75 70 70 6f 72  e] is not suppor
260f0 74 65 64 20 61 66 74 65 72 20 44 45 46 41 55 4c  ted after DEFAUL
26100 54 20 56 41 4c 55 45 53 2e 0a 0a 3c 2f 6f 6c 3e  T VALUES...</ol>
26110 0a 0a 3c 70 3e 0a 5e 54 68 65 20 69 6e 69 74 69  ..<p>.^The initi
26120 61 6c 20 22 49 4e 53 45 52 54 22 20 6b 65 79 77  al "INSERT" keyw
26130 6f 72 64 20 63 61 6e 20 62 65 20 72 65 70 6c 61  ord can be repla
26140 63 65 64 20 62 79 0a 22 52 45 50 4c 41 43 45 22  ced by."REPLACE"
26150 20 6f 72 20 22 49 4e 53 45 52 54 20 4f 52 20 3c   or "INSERT OR <
26160 69 3e 61 63 74 69 6f 6e 3c 2f 69 3e 22 20 74 6f  i>action</i>" to
26170 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
26180 72 6e 61 74 69 76 65 0a 63 6f 6e 73 74 72 61 69  rnative.constrai
26190 6e 74 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 7c  nt [ON CONFLICT|
261a0 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
261b0 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 5d 20 74  ion algorithm] t
261c0 6f 20 75 73 65 20 64 75 72 69 6e 67 20 0a 74 68  o use during .th
261d0 61 74 20 6f 6e 65 20 49 4e 53 45 52 54 20 63 6f  at one INSERT co
261e0 6d 6d 61 6e 64 2e 0a 46 6f 72 20 63 6f 6d 70 61  mmand..For compa
261f0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 4d 79  tibility with My
26200 53 51 4c 2c 20 5e 74 68 65 20 70 61 72 73 65 72  SQL, ^the parser
26210 20 61 6c 6c 6f 77 73 20 74 68 65 20 75 73 65 20   allows the use 
26220 6f 66 20 74 68 65 0a 73 69 6e 67 6c 65 20 6b 65  of the.single ke
26230 79 77 6f 72 64 20 3c 61 20 68 72 65 66 3d 22 6c  yword <a href="l
26240 61 6e 67 5f 72 65 70 6c 61 63 65 2e 68 74 6d 6c  ang_replace.html
26250 22 3e 52 45 50 4c 41 43 45 3c 2f 61 3e 20 61 73  ">REPLACE</a> as
26260 20 61 6e 20 0a 61 6c 69 61 73 20 66 6f 72 20 22   an .alias for "
26270 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
26280 45 22 2e 0a 0a 3c 70 3e 5e 28 54 68 65 20 6f 70  E"...<p>^(The op
26290 74 69 6f 6e 61 6c 20 22 3c 69 3e 73 63 68 65 6d  tional "<i>schem
262a0 61 2d 6e 61 6d 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f  a-name</i><b>.</
262b0 62 3e 22 20 70 72 65 66 69 78 20 6f 6e 20 74 68  b>" prefix on th
262c0 65 20 0a 3c 79 79 74 65 72 6d 3e 74 61 62 6c 65  e .<yyterm>table
262d0 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 0a 69  -name</yyterm>.i
262e0 73 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  s supported for 
262f0 74 6f 70 2d 6c 65 76 65 6c 20 49 4e 53 45 52 54  top-level INSERT
26300 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 6c 79   statements only
26310 2e 29 5e 20 20 5e 54 68 65 20 74 61 62 6c 65 20  .)^  ^The table 
26320 6e 61 6d 65 20 6d 75 73 74 20 62 65 0a 75 6e 71  name must be.unq
26330 75 61 6c 69 66 69 65 64 20 66 6f 72 20 49 4e 53  ualified for INS
26340 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ERT statements t
26350 68 61 74 20 6f 63 63 75 72 20 77 69 74 68 69 6e  hat occur within
26360 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
26370 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 5e 53  ] statements..^S
26380 69 6d 69 6c 61 72 6c 79 2c 20 74 68 65 20 22 44  imilarly, the "D
26390 45 46 41 55 4c 54 20 56 41 4c 55 45 53 22 20 66  EFAULT VALUES" f
263a0 6f 72 6d 20 6f 66 20 74 68 65 20 49 4e 53 45 52  orm of the INSER
263b0 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 73  T statement is s
263c0 75 70 70 6f 72 74 65 64 20 66 6f 72 0a 74 6f 70  upported for.top
263d0 2d 6c 65 76 65 6c 20 49 4e 53 45 52 54 20 73 74  -level INSERT st
263e0 61 74 65 6d 65 6e 74 73 20 6f 6e 6c 79 20 61 6e  atements only an
263f0 64 20 6e 6f 74 20 66 6f 72 20 49 4e 53 45 52 54  d not for INSERT
26400 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68   statements with
26410 69 6e 0a 74 72 69 67 67 65 72 73 2e 0a 3c 70 3e  in.triggers..<p>
26420 0a 0a 3c 70 3e 54 68 65 20 6f 70 74 69 6f 6e 61  ..<p>The optiona
26430 6c 20 22 41 53 20 3c 79 79 74 65 72 6d 3e 61 6c  l "AS <yyterm>al
26440 69 61 73 3c 2f 79 79 74 65 72 6d 3e 22 20 70 68  ias</yyterm>" ph
26450 72 61 73 65 20 70 72 6f 76 69 64 65 73 20 61 6e  rase provides an
26460 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 6e 61 6d   alternative.nam
26470 65 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  e for the table 
26480 69 6e 74 6f 20 77 68 69 63 68 20 63 6f 6e 74 65  into which conte
26490 6e 74 20 69 73 20 62 65 69 6e 67 20 69 6e 73 65  nt is being inse
264a0 72 74 65 64 2e 20 20 54 68 65 20 61 6c 69 61 73  rted.  The alias
264b0 20 6e 61 6d 65 0a 63 61 6e 20 62 65 20 75 73 65   name.can be use
264c0 64 20 77 69 74 68 69 6e 20 57 48 45 52 45 20 61  d within WHERE a
264d0 6e 64 20 53 45 54 20 63 6c 61 75 73 65 73 20 6f  nd SET clauses o
264e0 66 20 74 68 65 20 5b 55 50 53 45 52 54 5d 2e 20  f the [UPSERT]. 
264f0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a   If there is no.
26500 5b 75 70 73 65 72 74 2d 63 6c 61 75 73 65 5d 2c  [upsert-clause],
26510 20 74 68 65 6e 20 74 68 65 20 3c 79 79 74 65 72   then the <yyter
26520 6d 3e 61 6c 69 61 73 3c 2f 79 79 74 65 72 6d 3e  m>alias</yyterm>
26530 20 69 73 20 70 6f 69 6e 74 6c 65 73 73 2c 20 62   is pointless, b
26540 75 74 20 61 6c 73 6f 0a 68 61 72 6d 6c 65 73 73  ut also.harmless
26550 2e 0a 0a 3c 70 3e 53 65 65 20 74 68 65 20 73 65  ...<p>See the se
26560 70 61 72 61 74 65 20 5b 55 50 53 45 52 54 5d 20  parate [UPSERT] 
26570 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
26580 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
26590 20 74 72 61 69 6c 69 6e 67 0a 73 79 6e 74 61 78   trailing.syntax
265a0 20 74 68 61 74 20 63 61 6e 20 63 61 75 73 65 20   that can cause 
265b0 61 6e 20 49 4e 53 45 52 54 20 74 6f 20 62 65 68  an INSERT to beh
265c0 61 76 65 20 61 73 20 61 6e 20 55 50 44 41 54 45  ave as an UPDATE
265d0 20 69 66 20 74 68 65 20 49 4e 53 45 52 54 20 77   if the INSERT w
265e0 6f 75 6c 64 0a 6f 74 68 65 72 77 69 73 65 20 76  ould.otherwise v
265f0 69 6f 6c 61 74 65 20 61 20 75 6e 69 71 75 65 6e  iolate a uniquen
26600 65 73 73 20 63 6f 6e 73 74 72 61 69 6e 74 2e 20  ess constraint. 
26610 20 54 68 65 20 5b 75 70 73 65 72 74 20 63 6c 61   The [upsert cla
26620 75 73 65 5d 20 69 73 20 6e 6f 74 0a 61 6c 6c 6f  use] is not.allo
26630 77 65 64 20 6f 6e 20 61 6e 20 22 49 4e 53 45 52  wed on an "INSER
26640 54 20 2e 2e 2e 20 44 45 46 41 55 4c 54 20 56 41  T ... DEFAULT VA
26650 4c 55 45 53 22 2e 0a 0a 0a 3c 74 63 6c 3e 0a 23  LUES"....<tcl>.#
26660 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26670 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26680 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
26690 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
266a0 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
266b0 63 74 69 6f 6e 20 75 70 73 65 72 74 20 55 50 53  ction upsert UPS
266c0 45 52 54 20 7b 55 50 53 45 52 54 20 7b 75 70 73  ERT {UPSERT {ups
266d0 65 72 74 20 63 6c 61 75 73 65 7d 7d 0a 0a 52 65  ert clause}}..Re
266e0 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
266f0 67 72 61 6d 20 75 70 73 65 72 74 2d 63 6c 61 75  gram upsert-clau
26700 73 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 55 50  se.</tcl>..<p>UP
26710 53 45 52 54 20 69 73 20 61 20 73 70 65 63 69 61  SERT is a specia
26720 6c 20 73 79 6e 74 61 78 20 61 64 64 69 74 69 6f  l syntax additio
26730 6e 20 74 6f 20 5b 49 4e 53 45 52 54 5d 20 74 68  n to [INSERT] th
26740 61 74 20 63 61 75 73 65 73 20 74 68 65 0a 49 4e  at causes the.IN
26750 53 45 52 54 20 74 6f 20 62 65 68 61 76 65 20 61  SERT to behave a
26760 73 20 61 6e 20 5b 55 50 44 41 54 45 5d 20 6f 72  s an [UPDATE] or
26770 20 61 20 6e 6f 2d 6f 70 20 69 66 20 74 68 65 20   a no-op if the 
26780 49 4e 53 45 52 54 20 77 6f 75 6c 64 20 76 69 6f  INSERT would vio
26790 6c 61 74 65 0a 61 20 75 6e 69 71 75 65 6e 65 73  late.a uniquenes
267a0 73 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0a 55 50  s constraint..UP
267b0 53 45 52 54 20 69 73 20 6e 6f 74 20 73 74 61 6e  SERT is not stan
267c0 64 61 72 64 20 53 51 4c 2e 20 20 55 50 53 45 52  dard SQL.  UPSER
267d0 54 20 69 6e 20 53 51 4c 69 74 65 20 66 6f 6c 6c  T in SQLite foll
267e0 6f 77 73 20 74 68 65 0a 73 79 6e 74 61 78 20 65  ows the.syntax e
267f0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 50 6f  stablished by Po
26800 73 74 67 72 65 53 51 4c 2e 0a 55 50 53 45 52 54  stgreSQL..UPSERT
26810 20 73 79 6e 74 61 78 20 77 61 73 20 61 64 64 65   syntax was adde
26820 64 20 74 6f 20 53 51 4c 69 74 65 20 77 69 74 68  d to SQLite with
26830 20 76 65 72 73 69 6f 6e 20 33 2e 32 34 2e 30 20   version 3.24.0 
26840 28 5b 64 61 74 65 6f 66 3a 33 2e 32 34 2e 30 5d  ([dateof:3.24.0]
26850 29 2e 0a 0a 3c 70 3e 41 6e 20 55 50 53 45 52 54  )...<p>An UPSERT
26860 20 69 73 20 61 6e 20 6f 72 64 69 6e 61 72 79 20   is an ordinary 
26870 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d 65  [INSERT] stateme
26880 6e 74 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  nt that is follo
26890 77 65 64 20 62 79 0a 74 68 65 20 73 70 65 63 69  wed by.the speci
268a0 61 6c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63  al ON CONFLICT c
268b0 6c 61 75 73 65 20 73 68 6f 77 6e 20 61 62 6f 76  lause shown abov
268c0 65 2e 0a 0a 3c 70 3e 54 68 65 20 73 79 6e 74 61  e...<p>The synta
268d0 78 20 74 68 61 74 20 6f 63 63 75 72 73 20 69 6e  x that occurs in
268e0 20 62 65 74 77 65 65 6e 20 74 68 65 20 22 4f 4e   between the "ON
268f0 20 43 4f 4e 46 4c 49 43 54 22 20 61 6e 64 20 22   CONFLICT" and "
26900 44 4f 22 20 6b 65 79 77 6f 72 64 73 0a 69 73 20  DO" keywords.is 
26910 63 61 6c 6c 65 64 20 74 68 65 20 22 63 6f 6e 66  called the "conf
26920 6c 69 63 74 20 74 61 72 67 65 74 22 2e 20 20 54  lict target".  T
26930 68 65 20 63 6f 6e 66 6c 69 63 74 20 74 61 72 67  he conflict targ
26940 65 74 20 73 70 65 63 69 66 69 65 73 20 61 20 73  et specifies a s
26950 70 65 63 69 66 69 63 0a 75 6e 69 71 75 65 6e 65  pecific.uniquene
26960 73 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 68  ss constraint th
26970 61 74 20 77 69 6c 6c 20 74 72 69 67 67 65 72 20  at will trigger 
26980 74 68 65 20 75 70 73 65 72 74 2e 20 20 54 68 65  the upsert.  The
26990 20 63 6f 6e 66 6c 69 63 74 20 74 61 72 67 65 74   conflict target
269a0 0a 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72  .is required for
269b0 20 44 4f 20 55 50 44 41 54 45 20 75 70 73 65 72   DO UPDATE upser
269c0 74 73 2c 20 62 75 74 20 69 73 20 6f 70 74 69 6f  ts, but is optio
269d0 6e 61 6c 20 66 6f 72 20 44 4f 20 4e 4f 54 48 49  nal for DO NOTHI
269e0 4e 47 2e 20 20 57 68 65 6e 0a 74 68 65 20 63 6f  NG.  When.the co
269f0 6e 66 6c 69 63 74 20 74 61 72 67 65 74 20 69 73  nflict target is
26a00 20 6f 6d 69 74 74 65 64 2c 20 74 68 65 20 75 70   omitted, the up
26a10 73 65 72 74 20 62 65 68 61 76 69 6f 72 20 69 73  sert behavior is
26a20 20 74 72 69 67 67 65 72 65 64 20 62 79 20 61 0a   triggered by a.
26a30 76 69 6f 6c 61 74 69 6f 6e 20 6f 66 20 61 6e 79  violation of any
26a40 20 75 6e 69 71 75 65 6e 65 73 73 20 63 6f 6e 73   uniqueness cons
26a50 74 72 61 69 6e 74 20 6f 6e 20 74 68 65 20 74 61  traint on the ta
26a60 62 6c 65 20 6f 66 20 74 68 65 20 49 4e 53 45 52  ble of the INSER
26a70 54 2e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 69 6e  T...<p>If the in
26a80 73 65 72 74 20 6f 70 65 72 61 74 69 6f 6e 20 77  sert operation w
26a90 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 75  ould cause the u
26aa0 6e 69 71 75 65 6e 65 73 73 20 63 6f 6e 73 74 72  niqueness constr
26ab0 61 69 6e 74 20 69 64 65 6e 74 69 66 69 65 64 0a  aint identified.
26ac0 62 79 20 74 68 65 20 63 6f 6e 66 6c 69 63 74 2d  by the conflict-
26ad0 74 61 72 67 65 74 20 63 6c 61 75 73 65 20 74 6f  target clause to
26ae0 20 66 61 69 6c 2c 20 74 68 65 6e 20 74 68 65 20   fail, then the 
26af0 69 6e 73 65 72 74 20 69 73 20 6f 6d 69 74 74 65  insert is omitte
26b00 64 20 61 6e 64 0a 65 69 74 68 65 72 20 74 68 65  d and.either the
26b10 20 44 4f 20 4e 4f 54 48 49 4e 47 20 6f 72 20 44   DO NOTHING or D
26b20 4f 20 55 50 44 41 54 45 20 6f 70 65 72 61 74 69  O UPDATE operati
26b30 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 20  on is performed 
26b40 69 6e 73 74 65 61 64 2e 0a 49 6e 20 74 68 65 20  instead..In the 
26b50 63 61 73 65 20 6f 66 20 61 20 6d 75 6c 74 69 2d  case of a multi-
26b60 72 6f 77 20 69 6e 73 65 72 74 2c 20 74 68 69 73  row insert, this
26b70 20 64 65 63 69 73 69 6f 6e 20 69 73 20 6d 61 64   decision is mad
26b80 65 20 73 65 70 61 72 61 74 65 6c 79 0a 66 6f 72  e separately.for
26b90 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
26ba0 20 69 6e 73 65 72 74 2e 0a 0a 3c 70 3e 54 68 65   insert...<p>The
26bb0 20 73 70 65 63 69 61 6c 20 55 50 53 45 52 54 20   special UPSERT 
26bc0 70 72 6f 63 65 73 73 69 6e 67 20 68 61 70 70 65  processing happe
26bd0 6e 73 20 6f 6e 6c 79 20 66 6f 72 20 75 6e 69 71  ns only for uniq
26be0 75 65 6e 65 73 73 20 63 6f 6e 73 74 72 61 69 6e  ueness constrain
26bf0 74 20 6f 6e 0a 74 68 65 20 74 61 62 6c 65 20 74  t on.the table t
26c00 68 61 74 20 69 73 20 72 65 63 65 69 76 69 6e 67  hat is receiving
26c10 20 74 68 65 20 49 4e 53 45 52 54 2e 20 41 20 22   the INSERT. A "
26c20 75 6e 69 71 75 65 6e 65 73 73 20 63 6f 6e 73 74  uniqueness const
26c30 72 61 69 6e 74 22 0a 69 73 20 61 6e 20 65 78 70  raint".is an exp
26c40 6c 69 63 69 74 20 55 4e 49 51 55 45 20 6f 72 20  licit UNIQUE or 
26c50 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6e 73  PRIMARY KEY cons
26c60 74 72 61 69 6e 74 20 77 69 74 68 69 6e 0a 74 68  traint within.th
26c70 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73  e CREATE TABLE s
26c80 74 61 74 65 6d 65 6e 74 2c 20 6f 72 20 61 20 5b  tatement, or a [
26c90 75 6e 69 71 75 65 20 69 6e 64 65 78 5d 2e 0a 55  unique index]..U
26ca0 50 53 45 52 54 20 64 6f 65 73 20 6e 6f 74 20 69  PSERT does not i
26cb0 6e 74 65 72 76 65 6e 65 20 66 6f 72 20 66 61 69  ntervene for fai
26cc0 6c 65 64 20 4e 4f 54 20 4e 55 4c 4c 20 6f 72 20  led NOT NULL or 
26cd0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
26ce0 74 72 61 69 6e 74 73 0a 6f 72 20 66 6f 72 20 63  traints.or for c
26cf0 6f 6e 73 74 72 61 69 6e 74 73 20 74 68 61 74 20  onstraints that 
26d00 61 72 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  are implemented 
26d10 75 73 69 6e 67 20 74 72 69 67 67 65 72 73 2e 0a  using triggers..
26d20 0a 3c 70 3e 43 6f 6c 75 6d 6e 20 6e 61 6d 65 73  .<p>Column names
26d30 20 69 6e 20 74 68 65 20 65 78 70 72 65 73 73 69   in the expressi
26d40 6f 6e 73 20 6f 66 20 61 20 44 4f 20 55 50 44 41  ons of a DO UPDA
26d50 54 45 20 72 65 66 65 72 20 74 6f 20 74 68 65 20  TE refer to the 
26d60 6f 72 69 67 69 6e 61 6c 0a 75 6e 63 68 61 6e 67  original.unchang
26d70 65 64 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  ed value of the 
26d80 63 6f 6c 75 6d 6e 2c 20 62 65 66 6f 72 65 20 74  column, before t
26d90 68 65 20 61 74 74 65 6d 70 74 65 64 20 49 4e 53  he attempted INS
26da0 45 52 54 2e 20 20 54 6f 20 75 73 65 20 74 68 65  ERT.  To use the
26db0 0a 76 61 6c 75 65 20 74 68 61 74 20 77 6f 75 6c  .value that woul
26dc0 64 20 68 61 76 65 20 62 65 65 6e 20 69 6e 73 65  d have been inse
26dd0 72 74 65 64 20 68 61 64 20 74 68 65 20 63 6f 6e  rted had the con
26de0 73 74 72 61 69 6e 74 20 6e 6f 74 20 66 61 69 6c  straint not fail
26df0 65 64 2c 0a 61 64 64 20 74 68 65 20 73 70 65 63  ed,.add the spec
26e00 69 61 6c 20 22 65 78 63 6c 75 64 65 64 2e 22 20  ial "excluded." 
26e10 74 61 62 6c 65 20 71 75 61 6c 69 66 69 65 72 20  table qualifier 
26e20 74 6f 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  to the column na
26e30 6d 65 2e 0a 0a 3c 70 3e 53 6f 6d 65 20 65 78 61  me...<p>Some exa
26e40 6d 70 6c 65 73 20 77 69 6c 6c 20 68 65 6c 70 20  mples will help 
26e50 69 6c 6c 75 73 74 72 61 74 65 20 74 68 65 20 64  illustrate the d
26e60 69 66 66 65 72 65 6e 63 65 3a 0a 0a 3c 62 6c 6f  ifference:..<blo
26e70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43 52  ckquote><pre>.CR
26e80 45 41 54 45 20 54 41 42 4c 45 20 76 6f 63 61 62  EATE TABLE vocab
26e90 75 6c 61 72 79 28 77 6f 72 64 20 54 45 58 54 20  ulary(word TEXT 
26ea0 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 63 6f 75  PRIMARY KEY, cou
26eb0 6e 74 20 49 4e 54 20 44 45 46 41 55 4c 54 20 31  nt INT DEFAULT 1
26ec0 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 76  );.INSERT INTO v
26ed0 6f 63 61 62 75 6c 61 72 79 28 77 6f 72 64 29 20  ocabulary(word) 
26ee0 56 41 4c 55 45 53 28 27 6a 6f 76 69 61 6c 27 29  VALUES('jovial')
26ef0 0a 20 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 28 77  .  ON CONFLICT(w
26f00 6f 72 64 29 20 44 4f 20 55 50 44 41 54 45 20 53  ord) DO UPDATE S
26f10 45 54 20 63 6f 75 6e 74 3d 63 6f 75 6e 74 2b 31  ET count=count+1
26f20 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
26f30 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 75 70  uote>..<p>The up
26f40 73 65 72 74 20 61 62 6f 76 65 20 69 6e 73 65 72  sert above inser
26f50 74 73 20 74 68 65 20 6e 65 77 20 76 6f 63 61 62  ts the new vocab
26f60 75 6c 61 72 79 20 77 6f 72 64 20 22 6a 6f 76 69  ulary word "jovi
26f70 61 6c 22 20 69 66 20 74 68 61 74 0a 77 6f 72 64  al" if that.word
26f80 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20   is not already 
26f90 69 6e 20 74 68 65 20 64 69 63 74 69 6f 6e 61 72  in the dictionar
26fa0 79 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 61  y, or if it is a
26fb0 6c 72 65 61 64 79 20 69 6e 20 74 68 65 0a 64 69  lready in the.di
26fc0 63 74 69 6f 6e 61 72 79 2c 20 69 74 20 69 6e 63  ctionary, it inc
26fd0 72 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 75 6e  rements the coun
26fe0 74 65 72 2e 20 20 54 68 65 20 22 63 6f 75 6e 74  ter.  The "count
26ff0 2b 31 22 20 65 78 70 72 65 73 73 69 6f 6e 0a 63  +1" expression.c
27000 6f 75 6c 64 20 61 6c 73 6f 20 62 65 20 77 72 69  ould also be wri
27010 74 74 65 6e 20 61 73 20 22 76 6f 63 61 62 75 6c  tten as "vocabul
27020 61 72 79 2e 63 6f 75 6e 74 22 2e 20 20 50 6f 73  ary.count".  Pos
27030 74 67 72 65 53 51 4c 20 72 65 71 75 69 72 65 73  tgreSQL requires
27040 20 74 68 65 0a 73 65 63 6f 6e 64 20 66 6f 72 6d   the.second form
27050 2c 20 62 75 74 20 53 51 4c 69 74 65 20 61 63 63  , but SQLite acc
27060 65 70 74 73 20 65 69 74 68 65 72 2e 0a 0a 3c 62  epts either...<b
27070 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
27080 43 52 45 41 54 45 20 54 41 42 4c 45 20 70 68 6f  CREATE TABLE pho
27090 6e 65 62 6f 6f 6b 28 6e 61 6d 65 20 54 45 58 54  nebook(name TEXT
270a0 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 70 68   PRIMARY KEY, ph
270b0 6f 6e 65 6e 75 6d 62 65 72 20 54 45 58 54 29 3b  onenumber TEXT);
270c0 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 70 68 6f  .INSERT INTO pho
270d0 6e 65 62 6f 6f 6b 28 6e 61 6d 65 2c 70 68 6f 6e  nebook(name,phon
270e0 65 6e 75 6d 62 65 72 29 20 56 41 4c 55 45 53 28  enumber) VALUES(
270f0 27 41 6c 69 63 65 27 2c 27 37 30 34 2d 35 35 35  'Alice','704-555
27100 2d 31 32 31 32 27 29 0a 20 20 4f 4e 20 43 4f 4e  -1212').  ON CON
27110 46 4c 49 43 54 28 6e 61 6d 65 29 20 44 4f 20 55  FLICT(name) DO U
27120 50 44 41 54 45 20 53 45 54 20 70 68 6f 6e 65 6e  PDATE SET phonen
27130 75 6d 62 65 72 3d 65 78 63 6c 75 64 65 64 2e 70  umber=excluded.p
27140 68 6f 6e 65 6e 75 6d 62 65 72 3b 0a 3c 2f 70 72  honenumber;.</pr
27150 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
27160 0a 3c 70 3e 49 6e 20 74 68 65 20 73 65 63 6f 6e  .<p>In the secon
27170 64 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 65  d example, the e
27180 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74 68 65  xpression in the
27190 20 44 4f 20 55 50 44 41 54 45 20 63 6c 61 75 73   DO UPDATE claus
271a0 65 20 69 73 0a 6f 66 20 74 68 65 20 66 6f 72 6d  e is.of the form
271b0 20 22 65 78 63 6c 75 64 65 64 2e 70 68 6f 6e 65   "excluded.phone
271c0 6e 75 6d 62 65 72 22 2e 20 20 54 68 65 20 22 65  number".  The "e
271d0 78 63 6c 75 64 65 64 2e 22 20 70 72 65 66 69 78  xcluded." prefix
271e0 20 63 61 75 73 65 73 20 74 68 65 0a 22 70 68 6f   causes the."pho
271f0 6e 65 6e 75 6d 62 65 72 22 20 74 6f 20 72 65 66  nenumber" to ref
27200 65 72 20 74 6f 20 74 68 65 20 76 61 6c 75 65 20  er to the value 
27210 66 6f 72 20 70 68 6f 6e 65 6e 75 6d 62 65 72 20  for phonenumber 
27220 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
27230 62 65 65 6e 0a 69 6e 73 65 72 74 65 64 20 68 61  been.inserted ha
27240 64 20 74 68 65 72 65 20 62 65 65 6e 20 6e 6f 20  d there been no 
27250 63 6f 6e 66 6c 69 63 74 2e 20 20 48 65 6e 63 65  conflict.  Hence
27260 2c 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  , the effect of 
27270 74 68 65 20 75 70 73 65 72 74 0a 69 73 20 74 6f  the upsert.is to
27280 20 69 6e 73 65 72 74 20 61 20 70 68 6f 6e 65 6e   insert a phonen
27290 75 6d 62 65 72 20 6f 66 20 41 6c 69 63 65 20 69  umber of Alice i
272a0 66 20 6e 6f 6e 65 20 65 78 69 73 74 73 2c 20 6f  f none exists, o
272b0 72 20 74 6f 20 6f 76 65 72 77 72 69 74 65 0a 61  r to overwrite.a
272c0 6e 79 20 70 72 69 6f 72 20 70 68 6f 6e 65 6e 75  ny prior phonenu
272d0 6d 62 65 72 20 66 6f 72 20 41 6c 69 63 65 20 77  mber for Alice w
272e0 69 74 68 20 74 68 65 20 6e 65 77 20 6f 6e 65 2e  ith the new one.
272f0 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20 74  ..<p>Note that t
27300 68 65 20 44 4f 20 55 50 44 41 54 45 20 63 6c 61  he DO UPDATE cla
27310 75 73 65 20 61 63 74 73 20 6f 6e 6c 79 20 6f 6e  use acts only on
27320 20 74 68 65 20 73 69 6e 67 6c 65 20 72 6f 77 0a   the single row.
27330 74 68 61 74 20 65 78 70 65 72 69 65 6e 63 65 64  that experienced
27340 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
27350 65 72 72 6f 72 20 64 75 72 69 6e 67 20 49 4e 53  error during INS
27360 45 52 54 2e 20 20 49 74 20 69 73 20 6e 6f 74 0a  ERT.  It is not.
27370 6e 65 63 65 73 73 61 72 79 20 74 6f 20 69 6e 63  necessary to inc
27380 6c 75 64 65 20 61 20 57 48 45 52 45 20 63 6c 61  lude a WHERE cla
27390 75 73 65 20 74 68 61 74 20 72 65 73 74 72 69 63  use that restric
273a0 74 69 6f 6e 73 20 74 68 65 20 61 63 74 69 6f 6e  tions the action
273b0 0a 74 6f 20 74 68 61 74 20 6f 6e 65 20 72 6f 77  .to that one row
273c0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 75 73 65 20  .  The only use 
273d0 66 6f 72 20 74 68 65 20 57 48 45 52 45 20 63 6c  for the WHERE cl
273e0 61 75 73 65 20 61 74 0a 74 68 65 20 65 6e 64 20  ause at.the end 
273f0 6f 66 20 74 68 65 20 44 4f 20 55 50 44 41 54 45  of the DO UPDATE
27400 20 69 73 20 74 6f 20 6f 70 74 69 6f 6e 61 6c 6c   is to optionall
27410 79 20 63 68 61 6e 67 65 20 74 68 65 20 44 4f 20  y change the DO 
27420 55 50 44 41 54 45 0a 69 6e 74 6f 20 61 20 6e 6f  UPDATE.into a no
27430 2d 6f 70 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  -op depending on
27440 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 61 6e   the original an
27450 64 2f 6f 72 20 6e 65 77 20 76 61 6c 75 65 73 2e  d/or new values.
27460 0a 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c  .For example:..<
27470 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
27480 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20 70 68  .CREATE TABLE ph
27490 6f 6e 65 62 6f 6f 6b 32 28 0a 20 20 6e 61 6d 65  onebook2(.  name
274a0 20 54 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45   TEXT PRIMARY KE
274b0 59 2c 0a 20 20 70 68 6f 6e 65 6e 75 6d 62 65 72  Y,.  phonenumber
274c0 20 54 45 58 54 2c 0a 20 20 76 61 6c 69 64 44 61   TEXT,.  validDa
274d0 74 65 20 44 41 54 45 0a 29 3b 0a 49 4e 53 45 52  te DATE.);.INSER
274e0 54 20 49 4e 54 4f 20 70 68 6f 6e 65 62 6f 6f 6b  T INTO phonebook
274f0 32 28 6e 61 6d 65 2c 70 68 6f 6e 65 6e 75 6d 62  2(name,phonenumb
27500 65 72 2c 76 61 6c 69 64 44 61 74 65 29 0a 20 20  er,validDate).  
27510 56 41 4c 55 45 53 28 27 41 6c 69 63 65 27 2c 27  VALUES('Alice','
27520 37 30 34 2d 35 35 35 2d 31 32 31 32 27 2c 27 32  704-555-1212','2
27530 30 31 38 2d 30 35 2d 30 38 27 29 0a 20 20 4f 4e  018-05-08').  ON
27540 20 43 4f 4e 46 4c 49 43 54 28 6e 61 6d 65 29 20   CONFLICT(name) 
27550 44 4f 20 55 50 44 41 54 45 20 53 45 54 0a 20 20  DO UPDATE SET.  
27560 20 20 70 68 6f 6e 65 6e 75 6d 62 65 72 3d 65 78    phonenumber=ex
27570 63 6c 75 64 65 64 2e 70 68 6f 6e 65 6e 75 6d 62  cluded.phonenumb
27580 65 72 2c 0a 20 20 20 20 76 61 6c 69 64 44 61 74  er,.    validDat
27590 65 3d 65 78 63 6c 75 64 65 64 2e 76 61 6c 69 64  e=excluded.valid
275a0 44 61 74 65 0a 20 20 57 48 45 52 45 20 65 78 63  Date.  WHERE exc
275b0 6c 75 64 65 64 2e 76 61 6c 69 64 44 61 74 65 3e  luded.validDate>
275c0 70 68 6f 6e 65 62 6f 6f 6b 32 2e 76 61 6c 69 64  phonebook2.valid
275d0 44 61 74 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  Date;.</pre></bl
275e0 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 49 6e  ockquote>..<p>In
275f0 20 74 68 69 73 20 6c 61 73 74 20 65 78 61 6d 70   this last examp
27600 6c 65 2c 20 74 68 65 20 70 68 6f 6e 65 62 6f 6f  le, the phoneboo
27610 6b 32 20 65 6e 74 72 79 20 69 73 20 6f 6e 6c 79  k2 entry is only
27620 0a 75 70 64 61 74 65 64 20 69 66 20 74 68 65 20  .updated if the 
27630 76 61 6c 69 64 44 61 74 65 20 66 6f 72 20 74 68  validDate for th
27640 65 20 6e 65 77 6c 79 20 69 6e 73 65 72 74 65 64  e newly inserted
27650 20 76 61 6c 75 65 20 69 73 0a 6e 65 77 65 72 20   value is.newer 
27660 74 68 61 6e 20 74 68 65 20 65 6e 74 72 79 20 61  than the entry a
27670 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 74 61  lready in the ta
27680 62 6c 65 2e 20 20 49 66 20 74 68 65 20 74 61 62  ble.  If the tab
27690 6c 65 20 61 6c 72 65 61 64 79 0a 63 6f 6e 74 61  le already.conta
276a0 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 77 69 74  ins an entry wit
276b0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
276c0 61 6e 64 20 61 20 63 75 72 72 65 6e 74 20 76 61  and a current va
276d0 6c 69 64 44 61 74 65 2c 0a 74 68 65 6e 20 74 68  lidDate,.then th
276e0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  e WHERE clause c
276f0 61 75 73 65 73 20 74 68 65 20 44 4f 20 55 50 44  auses the DO UPD
27700 41 54 45 20 74 6f 20 62 65 63 6f 6d 65 20 61 20  ATE to become a 
27710 6e 6f 2d 6f 70 2e 0a 0a 3c 74 63 6c 3e 68 64 5f  no-op...<tcl>hd_
27720 66 72 61 67 6d 65 6e 74 20 70 61 72 73 65 61 6d  fragment parseam
27730 62 69 67 20 7b 55 50 53 45 52 54 20 70 61 72 73  big {UPSERT pars
27740 69 6e 67 20 61 6d 62 69 67 75 69 74 79 7d 3c 2f  ing ambiguity}</
27750 74 63 6c 3e 0a 3c 68 33 3e 50 61 72 73 69 6e 67  tcl>.<h3>Parsing
27760 20 41 6d 62 69 67 75 69 74 79 3c 2f 68 33 3e 0a   Ambiguity</h3>.
27770 0a 3c 70 3e 57 68 65 6e 20 74 68 65 20 5b 49 4e  .<p>When the [IN
27780 53 45 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  SERT] statement 
27790 74 6f 20 77 68 69 63 68 20 74 68 65 20 55 50 53  to which the UPS
277a0 45 52 54 20 69 73 20 61 74 74 61 63 68 65 64 0a  ERT is attached.
277b0 74 61 6b 65 73 20 69 74 73 20 76 61 6c 75 65 73  takes its values
277c0 20 66 72 6f 6d 20 61 20 5b 53 45 4c 45 43 54 5d   from a [SELECT]
277d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 72   statement, ther
277e0 65 20 69 73 20 61 20 70 6f 74 65 6e 74 69 61 6c  e is a potential
277f0 0a 70 61 72 73 69 6e 67 20 61 6d 62 69 67 75 69  .parsing ambigui
27800 74 79 2e 20 20 54 68 65 20 70 61 72 73 65 72 20  ty.  The parser 
27810 6d 69 67 68 74 20 6e 6f 74 20 62 65 20 61 62 6c  might not be abl
27820 65 20 74 6f 20 74 65 6c 6c 20 69 66 20 74 68 65  e to tell if the
27830 0a 22 4f 4e 22 20 6b 65 79 77 6f 72 64 20 69 73  ."ON" keyword is
27840 20 69 6e 74 72 6f 64 75 63 69 6e 67 20 74 68 65   introducing the
27850 20 55 50 53 45 52 54 20 6f 72 20 69 66 20 69 74   UPSERT or if it
27860 20 69 73 20 74 68 65 20 4f 4e 20 63 6c 61 75 73   is the ON claus
27870 65 0a 6f 66 20 61 20 6a 6f 69 6e 2e 20 20 54 6f  e.of a join.  To
27880 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 74 68 69   work around thi
27890 73 2c 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  s, the SELECT st
278a0 61 74 65 6d 65 6e 74 20 73 68 6f 75 6c 64 20 61  atement should a
278b0 6c 77 61 79 73 0a 69 6e 63 6c 75 64 65 20 61 20  lways.include a 
278c0 57 48 45 52 45 20 63 6c 61 75 73 65 2c 20 65 76  WHERE clause, ev
278d0 65 6e 20 69 66 20 74 68 61 74 20 57 48 45 52 45  en if that WHERE
278e0 20 63 6c 61 75 73 65 20 69 73 20 6a 75 73 74 0a   clause is just.
278f0 22 57 48 45 52 45 20 74 72 75 65 22 2e 0a 0a 3c  "WHERE true"...<
27900 70 3e 41 6d 62 69 67 75 6f 75 73 20 75 73 65 20  p>Ambiguous use 
27910 6f 66 20 4f 4e 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  of ON:..<blockqu
27920 6f 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54  ote><pre>.INSERT
27930 20 49 4e 54 4f 20 74 31 20 53 45 4c 45 43 54 20   INTO t1 SELECT 
27940 2a 20 46 52 4f 4d 20 74 32 0a 4f 4e 20 43 4f 4e  * FROM t2.ON CON
27950 46 4c 49 43 54 28 78 29 20 44 4f 20 55 50 44 41  FLICT(x) DO UPDA
27960 54 45 20 53 45 54 20 79 3d 65 78 63 6c 75 64 65  TE SET y=exclude
27970 64 2e 79 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  d.y;.</pre></blo
27980 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 6d 62  ckquote>..<p>Amb
27990 69 67 75 69 74 79 20 72 65 73 6f 6c 76 65 64 20  iguity resolved 
279a0 75 73 69 6e 67 20 61 20 57 48 45 52 45 20 63 6c  using a WHERE cl
279b0 61 75 73 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  ause:..<blockquo
279c0 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20  te><pre>.INSERT 
279d0 49 4e 54 4f 20 74 31 20 53 45 4c 45 43 54 20 2a  INTO t1 SELECT *
279e0 20 46 52 4f 4d 20 74 32 20 3c 66 6f 6e 74 20 63   FROM t2 <font c
279f0 6f 6c 6f 72 3d 22 62 6c 75 65 22 3e 57 48 45 52  olor="blue">WHER
27a00 45 20 74 72 75 65 3c 2f 66 6f 6e 74 3e 0a 4f 4e  E true</font>.ON
27a10 20 43 4f 4e 46 4c 49 43 54 28 78 29 20 44 4f 20   CONFLICT(x) DO 
27a20 55 50 44 41 54 45 20 53 45 54 20 79 3d 65 78 63  UPDATE SET y=exc
27a30 6c 75 64 65 64 2e 79 3b 0a 3c 2f 70 72 65 3e 3c  luded.y;.</pre><
27a40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68  /blockquote>..<h
27a50 33 3e 4c 69 6d 69 74 61 74 69 6f 6e 73 3c 2f 68  3>Limitations</h
27a60 33 3e 0a 0a 3c 70 3e 55 50 53 45 52 54 20 64 6f  3>..<p>UPSERT do
27a70 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
27a80 20 77 6f 72 6b 20 66 6f 72 20 5b 76 69 72 74 75   work for [virtu
27a90 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 0a 0a 3c 74  al tables]....<t
27aa0 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23  cl>.############
27ab0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27ac0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27ad0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27ae0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
27af0 23 23 0a 53 65 63 74 69 6f 6e 20 7b 4f 4e 20 43  ##.Section {ON C
27b00 4f 4e 46 4c 49 43 54 20 63 6c 61 75 73 65 7d 20  ONFLICT clause} 
27b10 63 6f 6e 66 6c 69 63 74 20 7b 7b 63 6f 6e 66 6c  conflict {{confl
27b20 69 63 74 20 63 6c 61 75 73 65 7d 20 7b 4f 4e 20  ict clause} {ON 
27b30 43 4f 4e 46 4c 49 43 54 7d 7d 0a 0a 52 65 63 75  CONFLICT}}..Recu
27b40 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72  rsiveBubbleDiagr
27b50 61 6d 20 63 6f 6e 66 6c 69 63 74 2d 63 6c 61 75  am conflict-clau
27b60 73 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 54 68  se.</tcl>..<p>Th
27b70 65 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63 6c  e ON CONFLICT cl
27b80 61 75 73 65 20 69 73 20 61 0a 6e 6f 6e 2d 73 74  ause is a.non-st
27b90 61 6e 64 61 72 64 20 65 78 74 65 6e 73 69 6f 6e  andard extension
27ba0 20 73 70 65 63 69 66 69 63 20 74 6f 20 53 51 4c   specific to SQL
27bb0 69 74 65 20 0a 74 68 61 74 20 63 61 6e 20 61 70  ite .that can ap
27bc0 70 65 61 72 20 69 6e 20 6d 61 6e 79 20 6f 74 68  pear in many oth
27bd0 65 72 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 73 2e  er SQL commands.
27be0 0a 49 74 20 69 73 20 67 69 76 65 6e 20 69 74 73  .It is given its
27bf0 20 6f 77 6e 20 73 65 63 74 69 6f 6e 20 69 6e 20   own section in 
27c00 74 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 62 65  this document be
27c10 63 61 75 73 65 20 69 74 20 69 73 20 6e 6f 74 0a  cause it is not.
27c20 70 61 72 74 20 6f 66 20 73 74 61 6e 64 61 72 64  part of standard
27c30 20 53 51 4c 20 61 6e 64 20 74 68 65 72 65 66 6f   SQL and therefo
27c40 72 65 20 6d 69 67 68 74 20 6e 6f 74 20 62 65 20  re might not be 
27c50 66 61 6d 69 6c 69 61 72 2e 3c 2f 70 3e 0a 0a 3c  familiar.</p>..<
27c60 70 3e 54 68 65 20 4f 4e 20 43 4f 4e 46 4c 49 43  p>The ON CONFLIC
27c70 54 20 63 6c 61 75 73 65 20 64 65 73 63 72 69 62  T clause describ
27c80 65 64 20 68 65 72 65 20 68 61 73 20 62 65 65 6e  ed here has been
27c90 20 61 20 70 61 72 74 20 6f 66 0a 53 51 4c 69 74   a part of.SQLit
27ca0 65 20 73 69 6e 63 65 20 62 65 66 6f 72 65 20 76  e since before v
27cb0 65 72 73 69 6f 6e 20 33 2e 30 2e 30 20 28 5b 64  ersion 3.0.0 ([d
27cc0 61 74 65 6f 66 3a 33 2e 30 2e 30 5d 29 2e 20 20  ateof:3.0.0]).  
27cd0 54 68 65 20 70 68 72 61 73 65 0a 22 4f 4e 26 6e  The phrase."ON&n
27ce0 62 73 70 3b 43 4f 4e 46 4c 49 43 54 22 20 69 73  bsp;CONFLICT" is
27cf0 20 61 6c 73 6f 20 70 61 72 74 20 6f 66 20 5b 55   also part of [U
27d00 50 53 45 52 54 5d 2c 20 77 68 69 63 68 20 69 73  PSERT], which is
27d10 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 0a 74 6f   an extension.to
27d20 20 5b 49 4e 53 45 52 54 5d 20 61 64 64 65 64 20   [INSERT] added 
27d30 69 6e 20 76 65 72 73 69 6f 6e 20 33 2e 32 34 2e  in version 3.24.
27d40 30 20 28 5b 64 61 74 65 6f 66 3a 33 2e 32 34 2e  0 ([dateof:3.24.
27d50 30 5d 29 2e 20 20 44 6f 20 6e 6f 74 0a 63 6f 6e  0]).  Do not.con
27d60 66 75 73 65 20 74 68 65 73 65 20 74 77 6f 20 73  fuse these two s
27d70 65 70 61 72 61 74 65 20 75 73 65 73 20 6f 66 20  eparate uses of 
27d80 74 68 65 20 22 4f 4e 26 6e 62 73 70 3b 43 4f 4e  the "ON&nbsp;CON
27d90 46 4c 49 43 54 22 20 70 68 72 61 73 65 2e 0a 0a  FLICT" phrase...
27da0 3c 70 3e 5e 54 68 65 20 73 79 6e 74 61 78 20 66  <p>^The syntax f
27db0 6f 72 20 74 68 65 20 4f 4e 20 43 4f 4e 46 4c 49  or the ON CONFLI
27dc0 43 54 20 63 6c 61 75 73 65 20 69 73 20 61 73 20  CT clause is as 
27dd0 73 68 6f 77 6e 20 61 62 6f 76 65 20 66 6f 72 0a  shown above for.
27de0 74 68 65 20 43 52 45 41 54 45 20 54 41 42 4c 45  the CREATE TABLE
27df0 20 63 6f 6d 6d 61 6e 64 2e 20 20 5e 46 6f 72 20   command.  ^For 
27e00 74 68 65 20 49 4e 53 45 52 54 20 61 6e 64 0a 55  the INSERT and.U
27e10 50 44 41 54 45 20 63 6f 6d 6d 61 6e 64 73 2c 20  PDATE commands, 
27e20 74 68 65 20 6b 65 79 77 6f 72 64 73 20 22 4f 4e  the keywords "ON
27e30 20 43 4f 4e 46 4c 49 43 54 22 20 61 72 65 20 72   CONFLICT" are r
27e40 65 70 6c 61 63 65 64 20 62 79 20 22 4f 52 22 20  eplaced by "OR" 
27e50 73 6f 20 74 68 61 74 0a 74 68 65 20 73 79 6e 74  so that.the synt
27e60 61 78 20 72 65 61 64 73 20 6d 6f 72 65 20 6e 61  ax reads more na
27e70 74 75 72 61 6c 6c 79 2e 20 20 46 6f 72 20 65 78  turally.  For ex
27e80 61 6d 70 6c 65 2c 20 69 6e 73 74 65 61 64 20 6f  ample, instead o
27e90 66 0a 22 49 4e 53 45 52 54 20 4f 4e 20 43 4f 4e  f."INSERT ON CON
27ea0 46 4c 49 43 54 20 49 47 4e 4f 52 45 22 20 77 65  FLICT IGNORE" we
27eb0 20 68 61 76 65 20 22 49 4e 53 45 52 54 20 4f 52   have "INSERT OR
27ec0 20 49 47 4e 4f 52 45 22 2e 0a 54 68 65 20 6b 65   IGNORE"..The ke
27ed0 79 77 6f 72 64 73 20 63 68 61 6e 67 65 20 62 75  ywords change bu
27ee0 74 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  t the meaning of
27ef0 20 74 68 65 20 63 6c 61 75 73 65 20 69 73 20 74   the clause is t
27f00 68 65 20 73 61 6d 65 0a 65 69 74 68 65 72 20 77  he same.either w
27f10 61 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ay.</p>..<p>The 
27f20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 63 6c 61 75  ON CONFLICT clau
27f30 73 65 20 61 70 70 6c 69 65 73 20 74 6f 20 5b 55  se applies to [U
27f40 4e 49 51 55 45 5d 2c 20 5b 4e 4f 54 20 4e 55 4c  NIQUE], [NOT NUL
27f50 4c 5d 2c 0a 5b 43 48 45 43 4b 5d 2c 20 61 6e 64  L],.[CHECK], and
27f60 20 5b 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63   [PRIMARY KEY] c
27f70 6f 6e 73 74 72 61 69 6e 74 73 2e 0a 54 68 65 20  onstraints..The 
27f80 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 61 6c 67 6f  ON CONFLICT algo
27f90 72 69 74 68 6d 20 64 6f 65 73 20 6e 6f 74 0a 61  rithm does not.a
27fa0 70 70 6c 79 20 74 6f 20 5b 46 4f 52 45 49 47 4e  pply to [FOREIGN
27fb0 20 4b 45 59 20 63 6f 6e 73 74 72 61 69 6e 74 73   KEY constraints
27fc0 5d 2e 0a 54 68 65 72 65 20 61 72 65 20 66 69 76  ]..There are fiv
27fd0 65 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  e conflict resol
27fe0 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20  ution algorithm 
27ff0 63 68 6f 69 63 65 73 3a 0a 52 4f 4c 4c 42 41 43  choices:.ROLLBAC
28000 4b 2c 20 41 42 4f 52 54 2c 20 46 41 49 4c 2c 20  K, ABORT, FAIL, 
28010 49 47 4e 4f 52 45 2c 20 61 6e 64 20 52 45 50 4c  IGNORE, and REPL
28020 41 43 45 2e 0a 5e 54 68 65 20 64 65 66 61 75 6c  ACE..^The defaul
28030 74 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  t conflict resol
28040 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20  ution algorithm 
28050 69 73 20 41 42 4f 52 54 2e 20 20 54 68 69 73 0a  is ABORT.  This.
28060 69 73 20 77 68 61 74 20 74 68 65 79 20 6d 65 61  is what they mea
28070 6e 3a 3c 2f 70 3e 0a 0a 3c 64 6c 3e 0a 3c 64 74  n:</p>..<dl>.<dt
28080 3e 3c 62 3e 52 4f 4c 4c 42 41 43 4b 3c 2f 62 3e  ><b>ROLLBACK</b>
28090 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20 5e 57  </dt>.<dd><p> ^W
280a0 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61 62 6c  hen an applicabl
280b0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  e constraint vio
280c0 6c 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74  lation occurs, t
280d0 68 65 20 52 4f 4c 4c 42 41 43 4b 0a 72 65 73 6f  he ROLLBACK.reso
280e0 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d  lution algorithm
280f0 20 61 62 6f 72 74 73 20 74 68 65 20 63 75 72 72   aborts the curr
28100 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ent SQL statemen
28110 74 20 77 69 74 68 0a 61 6e 20 53 51 4c 49 54 45  t with.an SQLITE
28120 5f 43 4f 4e 53 54 52 41 49 4e 54 20 65 72 72 6f  _CONSTRAINT erro
28130 72 20 61 6e 64 20 72 6f 6c 6c 73 20 62 61 63 6b  r and rolls back
28140 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61   the current tra
28150 6e 73 61 63 74 69 6f 6e 2e 0a 5e 49 66 20 6e 6f  nsaction..^If no
28160 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
28170 61 63 74 69 76 65 20 28 6f 74 68 65 72 20 74 68  active (other th
28180 61 6e 20 74 68 65 20 69 6d 70 6c 69 65 64 20 74  an the implied t
28190 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 61 74 20  ransaction that 
281a0 69 73 20 63 72 65 61 74 65 64 20 6f 6e 20 65 76  is created on ev
281b0 65 72 79 0a 63 6f 6d 6d 61 6e 64 29 20 74 68 65  ery.command) the
281c0 6e 20 74 68 65 20 52 4f 4c 4c 42 41 43 4b 20 72  n the ROLLBACK r
281d0 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69  esolution algori
281e0 74 68 6d 20 77 6f 72 6b 73 20 74 68 65 20 73 61  thm works the sa
281f0 6d 65 20 61 73 20 74 68 65 0a 41 42 4f 52 54 20  me as the.ABORT 
28200 61 6c 67 6f 72 69 74 68 6d 2e 3c 2f 70 3e 3c 2f  algorithm.</p></
28210 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 41 42 4f 52  dd>..<dt><b>ABOR
28220 54 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  T</b></dt>.<dd><
28230 70 3e 20 5e 57 68 65 6e 20 61 6e 20 61 70 70 6c  p> ^When an appl
28240 69 63 61 62 6c 65 20 63 6f 6e 73 74 72 61 69 6e  icable constrain
28250 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63 75  t violation occu
28260 72 73 2c 20 74 68 65 20 41 42 4f 52 54 0a 72 65  rs, the ABORT.re
28270 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74  solution algorit
28280 68 6d 20 61 62 6f 72 74 73 20 74 68 65 20 63 75  hm aborts the cu
28290 72 72 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  rrent SQL statem
282a0 65 6e 74 0a 77 69 74 68 20 61 6e 20 53 51 4c 49  ent.with an SQLI
282b0 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 65 72  TE_CONSTRAINT er
282c0 72 6f 72 20 61 6e 64 20 62 61 63 6b 73 20 6f 75  ror and backs ou
282d0 74 20 61 6e 79 20 63 68 61 6e 67 65 73 0a 6d 61  t any changes.ma
282e0 64 65 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  de by the curren
282f0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 3b  t SQL statement;
28300 20 62 75 74 20 63 68 61 6e 67 65 73 20 63 61 75   but changes cau
28310 73 65 64 0a 62 79 20 70 72 69 6f 72 20 53 51 4c  sed.by prior SQL
28320 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68   statements with
28330 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 61 6e  in the same tran
28340 73 61 63 74 69 6f 6e 20 61 72 65 20 70 72 65 73  saction are pres
28350 65 72 76 65 64 20 61 6e 64 20 74 68 65 0a 74 72  erved and the.tr
28360 61 6e 73 61 63 74 69 6f 6e 20 72 65 6d 61 69 6e  ansaction remain
28370 73 20 61 63 74 69 76 65 2e 0a 54 68 69 73 20 69  s active..This i
28380 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  s the default be
28390 68 61 76 69 6f 72 20 61 6e 64 20 74 68 65 20 62  havior and the b
283a0 65 68 61 76 69 6f 72 20 73 70 65 63 69 66 69 65  ehavior specifie
283b0 64 20 62 79 20 74 68 65 20 53 51 4c 0a 73 74 61  d by the SQL.sta
283c0 6e 64 61 72 64 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a  ndard.</p></dd>.
283d0 0a 3c 64 74 3e 3c 62 3e 46 41 49 4c 3c 2f 62 3e  .<dt><b>FAIL</b>
283e0 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20 5e 57  </dt>.<dd><p> ^W
283f0 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61 62 6c  hen an applicabl
28400 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  e constraint vio
28410 6c 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74  lation occurs, t
28420 68 65 20 46 41 49 4c 0a 72 65 73 6f 6c 75 74 69  he FAIL.resoluti
28430 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 61 62 6f  on algorithm abo
28440 72 74 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  rts the current 
28450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
28460 74 68 20 61 6e 0a 53 51 4c 49 54 45 5f 43 4f 4e  th an.SQLITE_CON
28470 53 54 52 41 49 4e 54 20 65 72 72 6f 72 2e 20 20  STRAINT error.  
28480 5e 42 75 74 20 74 68 65 20 46 41 49 4c 20 72 65  ^But the FAIL re
28490 73 6f 6c 75 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  solution does no
284a0 74 0a 62 61 63 6b 20 6f 75 74 20 70 72 69 6f 72  t.back out prior
284b0 20 63 68 61 6e 67 65 73 20 6f 66 20 74 68 65 20   changes of the 
284c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
284d0 61 74 20 66 61 69 6c 65 64 20 6e 6f 72 20 64 6f  at failed nor do
284e0 65 73 0a 69 74 20 65 6e 64 20 74 68 65 20 74 72  es.it end the tr
284f0 61 6e 73 61 63 74 69 6f 6e 2e 0a 5e 46 6f 72 20  ansaction..^For 
28500 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 55  example, if an U
28510 50 44 41 54 45 0a 73 74 61 74 65 6d 65 6e 74 20  PDATE.statement 
28520 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 20 63 6f  encountered a co
28530 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
28540 6f 6e 20 6f 6e 20 74 68 65 20 31 30 30 74 68 20  on on the 100th 
28550 72 6f 77 20 74 68 61 74 0a 69 74 20 61 74 74 65  row that.it atte
28560 6d 70 74 73 20 74 6f 20 75 70 64 61 74 65 2c 20  mpts to update, 
28570 74 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 39  then the first 9
28580 39 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 72  9 row changes ar
28590 65 20 70 72 65 73 65 72 76 65 64 0a 62 75 74 20  e preserved.but 
285a0 63 68 61 6e 67 65 73 20 74 6f 20 72 6f 77 73 20  changes to rows 
285b0 31 30 30 20 61 6e 64 20 62 65 79 6f 6e 64 20 6e  100 and beyond n
285c0 65 76 65 72 20 6f 63 63 75 72 2e 3c 2f 70 3e 0a  ever occur.</p>.
285d0 0a 3c 70 3e 54 68 65 20 46 41 49 4c 20 62 65 68  .<p>The FAIL beh
285e0 61 76 69 6f 72 20 6f 6e 6c 79 20 77 6f 72 6b 73  avior only works
285f0 20 66 6f 72 20 75 6e 69 71 75 65 6e 65 73 73 2c   for uniqueness,
28600 20 4e 4f 54 20 4e 55 4c 4c 2c 20 61 6e 64 20 43   NOT NULL, and C
28610 48 45 43 4b 20 0a 63 6f 6e 73 74 72 61 69 6e 74  HECK .constraint
28620 73 2e 20 20 41 20 5b 66 6f 72 65 69 67 6e 20 6b  s.  A [foreign k
28630 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 5d 20 76  ey constraint] v
28640 69 6f 6c 61 74 69 6f 6e 20 63 61 75 73 65 73 20  iolation causes 
28650 61 6e 20 41 42 4f 52 54 2e 0a 3c 2f 70 3e 3c 2f  an ABORT..</p></
28660 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 49 47 4e 4f  dd>..<dt><b>IGNO
28670 52 45 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e  RE</b></dt>.<dd>
28680 3c 70 3e 20 5e 57 68 65 6e 20 61 6e 20 61 70 70  <p> ^When an app
28690 6c 69 63 61 62 6c 65 20 63 6f 6e 73 74 72 61 69  licable constrai
286a0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63  nt violation occ
286b0 75 72 73 2c 20 0a 74 68 65 20 49 47 4e 4f 52 45  urs, .the IGNORE
286c0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f   resolution algo
286d0 72 69 74 68 6d 20 73 6b 69 70 73 20 74 68 65 20  rithm skips the 
286e0 6f 6e 65 20 72 6f 77 20 74 68 61 74 20 63 6f 6e  one row that con
286f0 74 61 69 6e 73 0a 74 68 65 20 63 6f 6e 73 74 72  tains.the constr
28700 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 61  aint violation a
28710 6e 64 20 63 6f 6e 74 69 6e 75 65 73 20 70 72 6f  nd continues pro
28720 63 65 73 73 69 6e 67 20 73 75 62 73 65 71 75 65  cessing subseque
28730 6e 74 20 72 6f 77 73 0a 6f 66 20 74 68 65 20 53  nt rows.of the S
28740 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
28750 69 66 20 6e 6f 74 68 69 6e 67 20 77 65 6e 74 20  if nothing went 
28760 77 72 6f 6e 67 2e 0a 4f 74 68 65 72 20 72 6f 77  wrong..Other row
28770 73 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  s before and aft
28780 65 72 20 74 68 65 20 72 6f 77 20 74 68 61 74 0a  er the row that.
28790 63 6f 6e 74 61 69 6e 65 64 20 74 68 65 20 63 6f  contained the co
287a0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
287b0 6f 6e 20 61 72 65 20 69 6e 73 65 72 74 65 64 20  on are inserted 
287c0 6f 72 20 75 70 64 61 74 65 64 0a 6e 6f 72 6d 61  or updated.norma
287d0 6c 6c 79 2e 20 5e 4e 6f 20 65 72 72 6f 72 20 69  lly. ^No error i
287e0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 75  s returned for u
287f0 6e 69 71 75 65 6e 65 73 73 2c 20 4e 4f 54 20 4e  niqueness, NOT N
28800 55 4c 4c 2c 20 61 6e 64 0a 55 4e 49 51 55 45 20  ULL, and.UNIQUE 
28810 63 6f 6e 73 74 72 61 69 6e 74 20 65 72 72 6f 72  constraint error
28820 73 20 77 68 65 6e 20 74 68 65 20 49 47 4e 4f 52  s when the IGNOR
28830 45 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  E conflict resol
28840 75 74 69 6f 6e 0a 61 6c 67 6f 72 69 74 68 6d 20  ution.algorithm 
28850 69 73 20 75 73 65 64 2e 20 20 5e 48 6f 77 65 76  is used.  ^Howev
28860 65 72 2c 20 74 68 65 20 49 47 4e 4f 52 45 20 63  er, the IGNORE c
28870 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69  onflict resoluti
28880 6f 6e 0a 61 6c 67 6f 72 69 74 68 6d 20 77 6f 72  on.algorithm wor
28890 6b 73 20 6c 69 6b 65 20 41 42 4f 52 54 20 66 6f  ks like ABORT fo
288a0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  r [foreign key c
288b0 6f 6e 73 74 72 61 69 6e 74 5d 20 65 72 72 6f 72  onstraint] error
288c0 73 2e 0a 3c 2f 70 3e 0a 3c 2f 64 64 3e 0a 0a 3c  s..</p>.</dd>..<
288d0 64 74 3e 3c 62 3e 52 45 50 4c 41 43 45 3c 2f 62  dt><b>REPLACE</b
288e0 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 20 5e  ></dt>.<dd><p> ^
288f0 57 68 65 6e 20 61 20 5b 55 4e 49 51 55 45 5d 20  When a [UNIQUE] 
28900 6f 72 20 5b 50 52 49 4d 41 52 59 20 4b 45 59 5d  or [PRIMARY KEY]
28910 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
28920 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20 0a 74  ation occurs, .t
28930 68 65 20 52 45 50 4c 41 43 45 20 61 6c 67 6f 72  he REPLACE algor
28940 69 74 68 6d 0a 64 65 6c 65 74 65 73 20 70 72 65  ithm.deletes pre
28950 2d 65 78 69 73 74 69 6e 67 20 72 6f 77 73 20 74  -existing rows t
28960 68 61 74 20 61 72 65 20 63 61 75 73 69 6e 67 20  hat are causing 
28970 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  the constraint v
28980 69 6f 6c 61 74 69 6f 6e 0a 70 72 69 6f 72 20 74  iolation.prior t
28990 6f 20 69 6e 73 65 72 74 69 6e 67 20 6f 72 20 75  o inserting or u
289a0 70 64 61 74 69 6e 67 20 74 68 65 20 63 75 72 72  pdating the curr
289b0 65 6e 74 20 72 6f 77 20 61 6e 64 20 74 68 65 20  ent row and the 
289c0 63 6f 6d 6d 61 6e 64 20 63 6f 6e 74 69 6e 75 65  command continue
289d0 73 20 0a 65 78 65 63 75 74 69 6e 67 20 6e 6f 72  s .executing nor
289e0 6d 61 6c 6c 79 2e 0a 5e 49 66 20 61 20 5b 4e 4f  mally..^If a [NO
289f0 54 20 4e 55 4c 4c 5d 20 63 6f 6e 73 74 72 61 69  T NULL] constrai
28a00 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63  nt violation occ
28a10 75 72 73 2c 20 74 68 65 20 52 45 50 4c 41 43 45  urs, the REPLACE
28a20 20 63 6f 6e 66 6c 69 63 74 0a 72 65 73 6f 6c 75   conflict.resolu
28a30 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
28a40 65 20 4e 55 4c 4c 20 76 61 6c 75 65 20 77 69 74  e NULL value wit
28a50 68 0a 74 68 65 20 64 65 66 61 75 6c 74 20 76 61  h.the default va
28a60 6c 75 65 20 66 6f 72 20 74 68 61 74 20 63 6f 6c  lue for that col
28a70 75 6d 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  umn, or if the c
28a80 6f 6c 75 6d 6e 20 68 61 73 20 6e 6f 20 64 65 66  olumn has no def
28a90 61 75 6c 74 0a 76 61 6c 75 65 2c 20 74 68 65 6e  ault.value, then
28aa0 20 74 68 65 20 41 42 4f 52 54 20 61 6c 67 6f 72   the ABORT algor
28ab0 69 74 68 6d 20 69 73 20 75 73 65 64 2e 0a 5e 49  ithm is used..^I
28ac0 66 20 61 20 5b 43 48 45 43 4b 20 63 6f 6e 73 74  f a [CHECK const
28ad0 72 61 69 6e 74 5d 20 6f 72 20 5b 66 6f 72 65 69  raint] or [forei
28ae0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
28af0 74 5d 20 76 69 6f 6c 61 74 69 6f 6e 20 6f 63 63  t] violation occ
28b00 75 72 73 2c 20 0a 74 68 65 20 52 45 50 4c 41 43  urs, .the REPLAC
28b10 45 20 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c  E conflict resol
28b20 75 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20  ution algorithm 
28b30 77 6f 72 6b 73 20 6c 69 6b 65 20 41 42 4f 52 54  works like ABORT
28b40 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 57 68 65 6e 20  .</p>..<p>^When 
28b50 74 68 65 20 52 45 50 4c 41 43 45 20 63 6f 6e 66  the REPLACE conf
28b60 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
28b70 73 74 72 61 74 65 67 79 20 64 65 6c 65 74 65 73  strategy deletes
28b80 20 72 6f 77 73 20 69 6e 20 6f 72 64 65 72 20 74   rows in order t
28b90 6f 0a 73 61 74 69 73 66 79 20 61 20 63 6f 6e 73  o.satisfy a cons
28ba0 74 72 61 69 6e 74 2c 20 5b 43 52 45 41 54 45 20  traint, [CREATE 
28bb0 54 52 49 47 47 45 52 20 7c 20 64 65 6c 65 74 65  TRIGGER | delete
28bc0 20 74 72 69 67 67 65 72 73 5d 20 66 69 72 65 20   triggers] fire 
28bd0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 5b  if and only if.[
28be0 72 65 63 75 72 73 69 76 65 5f 74 72 69 67 67 65  recursive_trigge
28bf0 72 73 20 70 72 61 67 6d 61 20 7c 20 72 65 63 75  rs pragma | recu
28c00 72 73 69 76 65 20 74 72 69 67 67 65 72 73 5d 20  rsive triggers] 
28c10 61 72 65 20 65 6e 61 62 6c 65 64 2e 3c 2f 70 3e  are enabled.</p>
28c20 0a 0a 3c 70 3e 5e 54 68 65 20 5b 73 71 6c 69 74  ..<p>^The [sqlit
28c30 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 20 7c  e3_update_hook |
28c40 20 75 70 64 61 74 65 20 68 6f 6f 6b 5d 20 69 73   update hook] is
28c50 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 66 6f 72   not invoked for
28c60 20 72 6f 77 73 20 74 68 61 74 0a 61 72 65 20 64   rows that.are d
28c70 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 52 45  eleted by the RE
28c80 50 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 20 72  PLACE conflict r
28c90 65 73 6f 6c 75 74 69 6f 6e 20 73 74 72 61 74 65  esolution strate
28ca0 67 79 2e 20 20 5e 4e 6f 72 20 64 6f 65 73 0a 52  gy.  ^Nor does.R
28cb0 45 50 4c 41 43 45 20 69 6e 63 72 65 6d 65 6e 74  EPLACE increment
28cc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
28cd0 61 6e 67 65 73 20 7c 20 63 68 61 6e 67 65 20 63  anges | change c
28ce0 6f 75 6e 74 65 72 5d 2e 0a 54 68 65 20 65 78 63  ounter]..The exc
28cf0 65 70 74 69 6f 6e 61 6c 20 62 65 68 61 76 69 6f  eptional behavio
28d00 72 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  rs defined in th
28d10 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
28d20 68 74 20 63 68 61 6e 67 65 20 0a 69 6e 20 61 20  ht change .in a 
28d30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 3c  future release.<
28d40 2f 70 3e 0a 3c 2f 64 6c 3e 0a 0a 3c 70 3e 5e 54  /p>.</dl>..<p>^T
28d50 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 73 70 65  he algorithm spe
28d60 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 4f 52  cified in the OR
28d70 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20 49 4e   clause of an IN
28d80 53 45 52 54 20 6f 72 20 55 50 44 41 54 45 0a 6f  SERT or UPDATE.o
28d90 76 65 72 72 69 64 65 73 20 61 6e 79 20 61 6c 67  verrides any alg
28da0 6f 72 69 74 68 6d 20 73 70 65 63 69 66 69 65 64  orithm specified
28db0 20 69 6e 20 61 20 43 52 45 41 54 45 20 54 41 42   in a CREATE TAB
28dc0 4c 45 2e 0a 5e 49 66 20 6e 6f 20 61 6c 67 6f 72  LE..^If no algor
28dd0 69 74 68 6d 20 69 73 20 73 70 65 63 69 66 69 65  ithm is specifie
28de0 64 20 61 6e 79 77 68 65 72 65 2c 20 74 68 65 20  d anywhere, the 
28df0 41 42 4f 52 54 20 61 6c 67 6f 72 69 74 68 6d 20  ABORT algorithm 
28e00 69 73 20 75 73 65 64 2e 3c 2f 70 3e 0a 0a 3c 74  is used.</p>..<t
28e10 63 6c 3e 0a 23 23 23 23 23 23 23 23 23 23 23 23  cl>.############
28e20 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28e30 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28e40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28e50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
28e60 23 23 0a 53 65 63 74 69 6f 6e 20 52 45 49 4e 44  ##.Section REIND
28e70 45 58 20 72 65 69 6e 64 65 78 20 52 45 49 4e 44  EX reindex REIND
28e80 45 58 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  EX..RecursiveBub
28e90 62 6c 65 44 69 61 67 72 61 6d 20 72 65 69 6e 64  bleDiagram reind
28ea0 65 78 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a  ex-stmt.</tcl>..
28eb0 3c 70 3e 5e 54 68 65 20 52 45 49 4e 44 45 58 20  <p>^The REINDEX 
28ec0 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65 64 20  command is used 
28ed0 74 6f 20 64 65 6c 65 74 65 20 61 6e 64 20 72 65  to delete and re
28ee0 63 72 65 61 74 65 20 69 6e 64 69 63 65 73 20 66  create indices f
28ef0 72 6f 6d 20 73 63 72 61 74 63 68 2e 0a 54 68 69  rom scratch..Thi
28f00 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
28f10 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
28f20 6f 66 20 61 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  of a collation s
28f30 65 71 75 65 6e 63 65 20 68 61 73 20 63 68 61 6e  equence has chan
28f40 67 65 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49  ged..</p>..<p>^I
28f50 66 20 74 68 65 20 52 45 49 4e 44 45 58 20 6b 65  f the REINDEX ke
28f60 79 77 6f 72 64 20 69 73 20 6e 6f 74 20 66 6f 6c  yword is not fol
28f70 6c 6f 77 65 64 20 62 79 20 61 20 63 6f 6c 6c 61  lowed by a colla
28f80 74 69 6f 6e 2d 73 65 71 75 65 6e 63 65 20 6f 72  tion-sequence or
28f90 20 64 61 74 61 62 61 73 65 20 0a 6f 62 6a 65 63   database .objec
28fa0 74 20 69 64 65 6e 74 69 66 69 65 72 2c 20 74 68  t identifier, th
28fb0 65 6e 20 61 6c 6c 20 69 6e 64 69 63 65 73 20 69  en all indices i
28fc0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
28fd0 61 74 61 62 61 73 65 73 20 61 72 65 20 72 65 62  atabases are reb
28fe0 75 69 6c 74 2e 0a 0a 3c 70 3e 5e 49 66 20 74 68  uilt...<p>^If th
28ff0 65 20 52 45 49 4e 44 45 58 20 6b 65 79 77 6f 72  e REINDEX keywor
29000 64 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 62 79  d is followed by
29010 20 61 20 63 6f 6c 6c 61 74 69 6f 6e 2d 73 65 71   a collation-seq
29020 75 65 6e 63 65 20 6e 61 6d 65 2c 20 74 68 65 6e  uence name, then
29030 0a 61 6c 6c 20 69 6e 64 69 63 65 73 20 69 6e 20  .all indices in 
29040 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
29050 61 62 61 73 65 73 20 74 68 61 74 20 75 73 65 20  abases that use 
29060 74 68 65 20 6e 61 6d 65 64 20 63 6f 6c 6c 61 74  the named collat
29070 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 0a 61 72  ion sequences.ar
29080 65 20 72 65 63 72 65 61 74 65 64 2e 20 0a 0a 3c  e recreated. ..<
29090 70 3e 5e 4f 72 2c 20 69 66 20 74 68 65 20 61 72  p>^Or, if the ar
290a0 67 75 6d 65 6e 74 20 61 74 74 61 63 68 65 64 20  gument attached 
290b0 74 6f 20 74 68 65 20 52 45 49 4e 44 45 58 20 69  to the REINDEX i
290c0 64 65 6e 74 69 66 69 65 73 20 61 20 73 70 65 63  dentifies a spec
290d0 69 66 69 63 20 0a 64 61 74 61 62 61 73 65 20 74  ific .database t
290e0 61 62 6c 65 2c 20 74 68 65 6e 20 61 6c 6c 20 69  able, then all i
290f0 6e 64 69 63 65 73 20 61 74 74 61 63 68 65 64 20  ndices attached 
29100 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
29110 74 61 62 6c 65 20 61 72 65 20 72 65 62 75 69 6c  table are rebuil
29120 74 2e 20 0a 5e 49 66 20 69 74 20 69 64 65 6e 74  t. .^If it ident
29130 69 66 69 65 73 20 61 20 73 70 65 63 69 66 69 63  ifies a specific
29140 20 64 61 74 61 62 61 73 65 20 69 6e 64 65 78 2c   database index,
29150 20 74 68 65 6e 20 6a 75 73 74 20 74 68 61 74 20   then just that 
29160 69 6e 64 65 78 20 69 73 20 72 65 63 72 65 61 74  index is recreat
29170 65 64 2e 0a 0a 3c 70 3e 5e 46 6f 72 20 61 20 63  ed...<p>^For a c
29180 6f 6d 6d 61 6e 64 20 6f 66 20 74 68 65 20 66 6f  ommand of the fo
29190 72 6d 20 22 52 45 49 4e 44 45 58 20 3c 69 3e 6e  rm "REINDEX <i>n
291a0 61 6d 65 3c 2f 69 3e 22 2c 20 61 20 6d 61 74 63  ame</i>", a matc
291b0 68 0a 61 67 61 69 6e 73 74 20 3c 79 79 74 65 72  h.against <yyter
291c0 6d 3e 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 61 6d 65  m>collation-name
291d0 3c 2f 79 79 74 65 72 6d 3e 20 74 61 6b 65 73 20  </yyterm> takes 
291e0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 20  precedence over 
291f0 61 20 6d 61 74 63 68 0a 61 67 61 69 6e 73 74 20  a match.against 
29200 3c 79 79 74 65 72 6d 3e 69 6e 64 65 78 2d 6e 61  <yyterm>index-na
29210 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 6f 72 20 3c  me</yyterm> or <
29220 79 79 74 65 72 6d 3e 74 61 62 6c 65 2d 6e 61 6d  yyterm>table-nam
29230 65 3c 2f 79 79 74 65 72 6d 3e 2e 0a 54 68 69 73  e</yyterm>..This
29240 20 61 6d 62 69 67 75 69 74 79 20 69 6e 20 74 68   ambiguity in th
29250 65 20 73 79 6e 74 61 78 20 6d 61 79 20 62 65 20  e syntax may be 
29260 61 76 6f 69 64 65 64 20 62 79 20 61 6c 77 61 79  avoided by alway
29270 73 20 73 70 65 63 69 66 79 69 6e 67 20 61 0a 3c  s specifying a.<
29280 79 79 74 65 72 6d 3e 73 63 68 65 6d 61 2d 6e 61  yyterm>schema-na
29290 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 77 68 65 6e  me</yyterm> when
292a0 20 72 65 69 6e 64 65 78 69 6e 67 20 61 20 73 70   reindexing a sp
292b0 65 63 69 66 69 63 20 74 61 62 6c 65 20 6f 72 20  ecific table or 
292c0 69 6e 64 65 78 2e 0a 0a 3c 74 63 6c 3e 0a 23 23  index...<tcl>.##
292d0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
292e0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
292f0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29300 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29310 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
29320 63 74 69 6f 6e 20 52 45 50 4c 41 43 45 20 72 65  ction REPLACE re
29330 70 6c 61 63 65 20 52 45 50 4c 41 43 45 0a 0a 3c  place REPLACE..<
29340 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 54 68 65 20 52  /tcl>..<p>^The R
29350 45 50 4c 41 43 45 20 63 6f 6d 6d 61 6e 64 20 69  EPLACE command i
29360 73 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74  s an alias for t
29370 68 65 20 22 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  he "[ON CONFLICT
29380 20 7c 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50   | INSERT OR REP
29390 4c 41 43 45 5d 22 0a 76 61 72 69 61 6e 74 20 6f  LACE]".variant o
293a0 66 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 20 63  f the [INSERT] c
293b0 6f 6d 6d 61 6e 64 2e 20 20 0a 54 68 69 73 20 61  ommand.  .This a
293c0 6c 69 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  lias is provided
293d0 20 66 6f 72 20 63 6f 6d 70 61 74 69 62 69 6c 69   for compatibili
293e0 74 79 20 6f 74 68 65 72 20 53 51 4c 20 64 61 74  ty other SQL dat
293f0 61 62 61 73 65 20 65 6e 67 69 6e 65 73 2e 20 20  abase engines.  
29400 53 65 65 20 74 68 65 20 0a 5b 49 4e 53 45 52 54  See the .[INSERT
29410 5d 20 63 6f 6d 6d 61 6e 64 20 64 6f 63 75 6d 65  ] command docume
29420 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
29430 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
29440 6f 6e 2e 3c 2f 70 3e 20 20 0a 0a 3c 74 63 6c 3e  on.</p>  ..<tcl>
29450 0a 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  .###############
29460 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29470 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29480 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
29490 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
294a0 0a 53 65 63 74 69 6f 6e 20 7b 57 49 54 48 20 63  .Section {WITH c
294b0 6c 61 75 73 65 7d 20 77 69 74 68 20 7b 7b 63 6f  lause} with {{co
294c0 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65  mmon table expre
294d0 73 73 69 6f 6e 73 7d 20 57 49 54 48 7d 0a 0a 52  ssions} WITH}..R
294e0 65 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69  ecursiveBubbleDi
294f0 61 67 72 61 6d 20 77 69 74 68 2d 63 6c 61 75 73  agram with-claus
29500 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 43 6f 6d  e.</tcl>..<p>Com
29510 6d 6f 6e 20 54 61 62 6c 65 20 45 78 70 72 65 73  mon Table Expres
29520 73 69 6f 6e 73 20 6f 72 20 43 54 45 73 20 61 63  sions or CTEs ac
29530 74 20 6c 69 6b 65 20 74 65 6d 70 6f 72 61 72 79  t like temporary
29540 20 5b 76 69 65 77 73 5d 20 74 68 61 74 20 65 78   [views] that ex
29550 69 73 74 0a 6f 6e 6c 79 20 66 6f 72 20 74 68 65  ist.only for the
29560 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 73   duration of a s
29570 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
29580 65 6e 74 2e 20 20 54 68 65 72 65 20 61 72 65 20  ent.  There are 
29590 74 77 6f 20 6b 69 6e 64 73 20 6f 66 0a 63 6f 6d  two kinds of.com
295a0 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
295b0 73 69 6f 6e 73 3a 20 22 6f 72 64 69 6e 61 72 79  sions: "ordinary
295c0 22 20 61 6e 64 20 22 72 65 63 75 72 73 69 76 65  " and "recursive
295d0 22 2e 20 4f 72 64 69 6e 61 72 79 20 0a 63 6f 6d  ". Ordinary .com
295e0 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
295f0 73 69 6f 6e 73 20 61 72 65 20 68 65 6c 70 66 75  sions are helpfu
29600 6c 20 66 6f 72 20 6d 61 6b 69 6e 67 0a 71 75 65  l for making.que
29610 72 69 65 73 20 65 61 73 69 65 72 20 74 6f 20 75  ries easier to u
29620 6e 64 65 72 73 74 61 6e 64 20 62 79 20 66 61 63  nderstand by fac
29630 74 6f 72 69 6e 67 0a 73 75 62 71 75 65 72 69 65  toring.subquerie
29640 73 20 6f 75 74 20 6f 66 20 74 68 65 20 6d 61 69  s out of the mai
29650 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
29660 0a 52 65 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f  .Recursive commo
29670 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69  n table expressi
29680 6f 6e 73 0a 70 72 6f 76 69 64 65 20 74 68 65 20  ons.provide the 
29690 61 62 69 6c 69 74 79 20 74 6f 20 64 6f 20 68 69  ability to do hi
296a0 65 72 61 72 63 68 69 63 61 6c 20 6f 72 0a 72 65  erarchical or.re
296b0 63 75 72 73 69 76 65 20 71 75 65 72 69 65 73 20  cursive queries 
296c0 6f 66 20 74 72 65 65 73 20 61 6e 64 20 67 72 61  of trees and gra
296d0 70 68 73 2c 20 61 20 63 61 70 61 62 69 6c 69 74  phs, a capabilit
296e0 79 0a 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 74  y.that is not ot
296f0 68 65 72 77 69 73 65 20 61 76 61 69 6c 61 62 6c  herwise availabl
29700 65 20 69 6e 20 74 68 65 20 53 51 4c 20 6c 61 6e  e in the SQL lan
29710 67 75 61 67 65 2e 0a 0a 3c 70 3e 41 6c 6c 20 63  guage...<p>All c
29720 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72  ommon table expr
29730 65 73 73 69 6f 6e 73 20 28 6f 72 64 69 6e 61 72  essions (ordinar
29740 79 20 61 6e 64 20 72 65 63 75 72 73 69 76 65 29  y and recursive)
29750 20 61 72 65 20 0a 63 72 65 61 74 65 64 20 62 79   are .created by
29760 20 70 72 65 70 65 6e 64 69 6e 67 20 61 20 57 49   prepending a WI
29770 54 48 20 63 6c 61 75 73 65 20 69 6e 20 66 72 6f  TH clause in fro
29780 6e 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  nt of a [SELECT]
29790 2c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 44 45 4c  , [INSERT], [DEL
297a0 45 54 45 5d 2c 0a 6f 72 20 5b 55 50 44 41 54 45  ETE],.or [UPDATE
297b0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20  ] statement.  A 
297c0 73 69 6e 67 6c 65 20 57 49 54 48 20 63 6c 61 75  single WITH clau
297d0 73 65 20 63 61 6e 20 73 70 65 63 69 66 79 20 6f  se can specify o
297e0 6e 65 20 6f 72 20 6d 6f 72 65 0a 63 6f 6d 6d 6f  ne or more.commo
297f0 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73 69  n table expressi
29800 6f 6e 73 2c 20 73 6f 6d 65 20 6f 66 20 77 68 69  ons, some of whi
29810 63 68 20 61 72 65 20 6f 72 64 69 6e 61 72 79 20  ch are ordinary 
29820 61 6e 64 20 73 6f 6d 65 20 6f 66 20 77 68 69 63  and some of whic
29830 68 0a 61 72 65 20 72 65 63 75 72 73 69 76 65 2e  h.are recursive.
29840 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
29850 6e 74 20 6f 72 64 69 6e 61 72 79 63 74 65 20 7b  nt ordinarycte {
29860 6f 72 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20  ordinary common 
29870 74 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e  table expression
29880 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 4f 72 64  s}</tcl>.<h3>Ord
29890 69 6e 61 72 79 20 43 6f 6d 6d 6f 6e 20 54 61 62  inary Common Tab
298a0 6c 65 20 45 78 70 72 65 73 73 69 6f 6e 73 3c 2f  le Expressions</
298b0 68 33 3e 0a 0a 3c 70 3e 41 6e 20 6f 72 64 69 6e  h3>..<p>An ordin
298c0 61 72 79 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65  ary common table
298d0 20 65 78 70 72 65 73 73 69 6f 6e 20 77 6f 72 6b   expression work
298e0 73 20 61 73 20 69 66 20 69 74 20 77 65 72 65 20  s as if it were 
298f0 61 20 5b 76 69 65 77 5d 20 74 68 61 74 0a 65 78  a [view] that.ex
29900 69 73 74 73 20 66 6f 72 20 74 68 65 20 64 75 72  ists for the dur
29910 61 74 69 6f 6e 20 6f 66 20 61 20 73 69 6e 67 6c  ation of a singl
29920 65 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 72  e statement.  Or
29930 64 69 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20 74 61  dinary common ta
29940 62 6c 65 0a 65 78 70 72 65 73 73 69 6f 6e 73 20  ble.expressions 
29950 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 66  are useful for f
29960 61 63 74 6f 72 69 6e 67 20 6f 75 74 20 73 75 62  actoring out sub
29970 71 75 65 72 69 65 73 20 61 6e 64 20 6d 61 6b 69  queries and maki
29980 6e 67 20 74 68 65 20 6f 76 65 72 61 6c 6c 0a 53  ng the overall.S
29990 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 65 61 73  QL statement eas
299a0 69 65 72 20 74 6f 20 72 65 61 64 20 61 6e 64 20  ier to read and 
299b0 75 6e 64 65 72 73 74 61 6e 64 2e 0a 0a 3c 70 3e  understand...<p>
299c0 41 20 57 49 54 48 20 63 6c 61 75 73 65 20 63 61  A WITH clause ca
299d0 6e 20 63 6f 6e 74 61 69 6e 20 6f 72 64 69 6e 61  n contain ordina
299e0 72 79 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20  ry common table 
299f0 65 78 70 72 65 73 73 69 6f 6e 73 20 65 76 65 6e  expressions even
29a00 20 69 66 0a 69 74 20 69 6e 63 6c 75 64 65 73 20   if.it includes 
29a10 74 68 65 20 52 45 43 55 52 53 49 56 45 20 6b 65  the RECURSIVE ke
29a20 79 77 6f 72 64 2e 20 20 54 68 65 20 75 73 65 20  yword.  The use 
29a30 6f 66 20 52 45 43 55 52 53 49 56 45 20 64 6f 65  of RECURSIVE doe
29a40 73 20 6e 6f 74 20 66 6f 72 63 65 0a 63 6f 6d 6d  s not force.comm
29a50 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73 73  on table express
29a60 69 6f 6e 73 20 74 6f 20 62 65 20 72 65 63 75 72  ions to be recur
29a70 73 69 76 65 2e 0a 0a 3c 74 63 6c 3e 0a 68 64 5f  sive...<tcl>.hd_
29a80 66 72 61 67 6d 65 6e 74 20 72 65 63 75 72 73 69  fragment recursi
29a90 76 65 63 74 65 20 7b 72 65 63 75 72 73 69 76 65  vecte {recursive
29aa0 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78   common table ex
29ab0 70 72 65 73 73 69 6f 6e 73 7d 20 5c 0a 7b 72 65  pressions} \.{re
29ac0 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74  cursive common t
29ad0 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 7d  able expression}
29ae0 20 7b 72 65 63 75 72 73 69 76 65 20 71 75 65 72   {recursive quer
29af0 79 7d 0a 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 52 65  y}.</tcl>.<h3>Re
29b00 63 75 72 73 69 76 65 20 43 6f 6d 6d 6f 6e 20 54  cursive Common T
29b10 61 62 6c 65 20 45 78 70 72 65 73 73 69 6f 6e 73  able Expressions
29b20 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 20 72 65 63 75  </h3>..<p>A recu
29b30 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74 61 62  rsive common tab
29b40 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  le expression ca
29b50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 77 72 69  n be used to wri
29b60 74 65 20 61 20 71 75 65 72 79 20 74 68 61 74 0a  te a query that.
29b70 77 61 6c 6b 73 20 61 20 74 72 65 65 20 6f 72 20  walks a tree or 
29b80 67 72 61 70 68 2e 20 20 41 20 72 65 63 75 72 73  graph.  A recurs
29b90 69 76 65 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c 65  ive common table
29ba0 20 65 78 70 72 65 73 73 69 6f 6e 20 68 61 73 20   expression has 
29bb0 74 68 65 20 73 61 6d 65 0a 62 61 73 69 63 20 73  the same.basic s
29bc0 79 6e 74 61 78 20 61 73 20 61 6e 20 6f 72 64 69  yntax as an ordi
29bd0 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c  nary common tabl
29be0 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 62 75  e expression, bu
29bf0 74 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  t with the follo
29c00 77 69 6e 67 0a 61 64 64 69 74 69 6f 6e 61 6c 20  wing.additional 
29c10 66 65 61 74 75 72 65 73 3a 0a 0a 3c 6f 6c 3e 0a  features:..<ol>.
29c20 3c 6c 69 3e 20 54 68 65 20 22 5b 73 65 6c 65 63  <li> The "[selec
29c30 74 2d 73 74 6d 74 5d 22 0a 20 20 20 20 20 6d 75  t-stmt]".     mu
29c40 73 74 20 62 65 20 61 20 5b 63 6f 6d 70 6f 75 6e  st be a [compoun
29c50 64 20 73 65 6c 65 63 74 5d 20 77 68 65 72 65 20  d select] where 
29c60 74 68 65 20 72 69 67 68 74 2d 6d 6f 73 74 20 5b  the right-most [
29c70 63 6f 6d 70 6f 75 6e 64 2d 6f 70 65 72 61 74 6f  compound-operato
29c80 72 5d 20 69 73 0a 20 20 20 20 20 65 69 74 68 65  r] is.     eithe
29c90 72 20 55 4e 49 4f 4e 20 6f 72 20 55 4e 49 4f 4e  r UNION or UNION
29ca0 20 41 4c 4c 2e 0a 3c 6c 69 3e 20 54 68 65 20 74   ALL..<li> The t
29cb0 61 62 6c 65 20 6e 61 6d 65 64 20 6f 6e 20 74 68  able named on th
29cc0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
29cd0 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f   of the AS keywo
29ce0 72 64 20 6d 75 73 74 20 61 70 70 65 61 72 0a 20  rd must appear. 
29cf0 20 20 20 20 65 78 61 63 74 6c 79 20 6f 6e 63 65      exactly once
29d00 20 69 6e 20 74 68 65 20 46 52 4f 4d 20 63 6c 61   in the FROM cla
29d10 75 73 65 20 6f 66 20 74 68 65 20 72 69 67 68 74  use of the right
29d20 2d 6d 6f 73 74 20 53 45 4c 45 43 54 20 73 74 61  -most SELECT sta
29d30 74 65 6d 65 6e 74 0a 20 20 20 20 20 6f 66 20 74  tement.     of t
29d40 68 65 20 63 6f 6d 70 6f 75 6e 64 20 73 65 6c 65  he compound sele
29d50 63 74 2c 20 61 6e 64 20 6e 6f 77 68 65 72 65 20  ct, and nowhere 
29d60 65 6c 73 65 2e 0a 3c 6c 69 3e 20 54 68 65 20 72  else..<li> The r
29d70 69 67 68 74 2d 6d 6f 73 74 20 53 45 4c 45 43 54  ight-most SELECT
29d80 20 6f 66 20 74 68 65 20 63 6f 6d 70 6f 75 6e 64   of the compound
29d90 20 73 65 6c 65 63 74 20 6d 75 73 74 20 6e 6f 74   select must not
29da0 20 6d 61 6b 65 20 75 73 65 20 6f 66 0a 20 20 20   make use of.   
29db0 20 20 5b 41 67 67 72 65 67 61 74 65 20 46 75 6e    [Aggregate Fun
29dc0 63 74 69 6f 6e 73 7c 61 67 67 72 65 67 61 74 65  ctions|aggregate
29dd0 5d 20 6f 72 20 5b 77 69 6e 64 6f 77 20 66 75 6e  ] or [window fun
29de0 63 74 69 6f 6e 73 5d 2e 0a 3c 2f 6f 6c 3e 0a 0a  ctions]..</ol>..
29df0 3c 70 3e 54 6f 20 70 75 74 20 69 74 20 61 6e 6f  <p>To put it ano
29e00 74 68 65 72 20 77 61 79 2c 20 61 20 72 65 63 75  ther way, a recu
29e10 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74 61 62  rsive common tab
29e20 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 20 6d 75  le expression mu
29e30 73 74 0a 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 65  st.look like the
29e40 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 0a 3c 74 63   following:..<tc
29e50 6c 3e 52 65 63 75 72 73 69 76 65 42 75 62 62 6c  l>RecursiveBubbl
29e60 65 44 69 61 67 72 61 6d 20 72 65 63 75 72 73 69  eDiagram recursi
29e70 76 65 2d 63 74 65 3c 2f 74 63 6c 3e 0a 0a 3c 70  ve-cte</tcl>..<p
29e80 3e 43 61 6c 6c 20 74 68 65 20 74 61 62 6c 65 20  >Call the table 
29e90 6e 61 6d 65 64 20 62 79 20 74 68 65 20 5b 63 74  named by the [ct
29ea0 65 2d 74 61 62 6c 65 2d 6e 61 6d 65 5d 20 69 6e  e-table-name] in
29eb0 20 61 20 72 65 63 75 72 73 69 76 65 0a 63 6f 6d   a recursive.com
29ec0 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65 73  mon table expres
29ed0 73 69 6f 6e 20 74 68 65 20 22 72 65 63 75 72 73  sion the "recurs
29ee0 69 76 65 20 74 61 62 6c 65 22 2e 0a 49 6e 20 74  ive table"..In t
29ef0 68 65 20 5b 72 65 63 75 72 73 69 76 65 2d 63 74  he [recursive-ct
29f00 65 5d 20 62 75 62 62 6c 65 20 64 69 61 67 72 61  e] bubble diagra
29f10 6d 20 61 62 6f 76 65 2c 20 74 68 65 20 72 65 63  m above, the rec
29f20 75 72 73 69 76 65 0a 74 61 62 6c 65 20 6d 75 73  ursive.table mus
29f30 74 20 61 70 70 65 61 72 20 65 78 61 63 74 6c 79  t appear exactly
29f40 20 6f 6e 63 65 20 69 6e 20 74 68 65 20 46 52 4f   once in the FRO
29f50 4d 20 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20  M clause of the 
29f60 0a 3c 79 79 74 65 72 6d 3e 72 65 63 75 72 73 69  .<yyterm>recursi
29f70 76 65 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72  ve-select</yyter
29f80 6d 3e 0a 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  m>.and must not 
29f90 61 70 70 65 61 72 20 61 6e 79 77 68 65 72 65 20  appear anywhere 
29fa0 65 6c 73 65 20 69 6e 20 65 69 74 68 65 72 20 74  else in either t
29fb0 68 65 0a 3c 79 79 74 65 72 6d 3e 69 6e 69 74 69  he.<yyterm>initi
29fc0 61 6c 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72  al-select</yyter
29fd0 6d 3e 20 6f 72 20 74 68 65 0a 3c 79 79 74 65 72  m> or the.<yyter
29fe0 6d 3e 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65  m>recursive-sele
29ff0 63 74 3c 2f 79 79 74 65 72 6d 3e 2c 20 69 6e 63  ct</yyterm>, inc
2a000 6c 75 64 69 6e 67 20 73 75 62 71 75 65 72 69 65  luding subquerie
2a010 73 2e 0a 54 68 65 20 3c 79 79 74 65 72 6d 3e 69  s..The <yyterm>i
2a020 6e 69 74 69 61 6c 2d 73 65 6c 65 63 74 3c 2f 79  nitial-select</y
2a030 79 74 65 72 6d 3e 20 6d 61 79 20 62 65 0a 61 20  yterm> may be.a 
2a040 5b 63 6f 6d 70 6f 75 6e 64 20 73 65 6c 65 63 74  [compound select
2a050 5d 2c 20 62 75 74 20 69 74 20 6d 61 79 20 6e 6f  ], but it may no
2a060 74 20 69 6e 63 6c 75 64 65 20 61 6e 20 4f 52 44  t include an ORD
2a070 45 52 20 42 59 2c 20 4c 49 4d 49 54 2c 20 6f 72  ER BY, LIMIT, or
2a080 20 4f 46 46 53 45 54 2e 0a 54 68 65 20 72 65 63   OFFSET..The rec
2a090 75 72 73 69 76 65 2d 73 65 6c 65 63 74 20 6d 75  ursive-select mu
2a0a0 73 74 20 62 65 20 61 20 73 69 6d 70 6c 65 20 73  st be a simple s
2a0b0 65 6c 65 63 74 2c 20 6e 6f 74 20 61 20 63 6f 6d  elect, not a com
2a0c0 70 6f 75 6e 64 2e 20 20 54 68 65 0a 72 65 63 75  pound.  The.recu
2a0d0 72 73 69 76 65 2d 73 65 6c 65 63 74 20 69 73 20  rsive-select is 
2a0e0 61 6c 6c 6f 77 65 64 20 74 6f 20 69 6e 63 6c 75  allowed to inclu
2a0f0 64 65 20 61 6e 20 4f 52 44 45 52 20 42 59 2c 20  de an ORDER BY, 
2a100 4c 49 4d 49 54 2c 20 61 6e 64 2f 6f 72 20 4f 46  LIMIT, and/or OF
2a110 46 53 45 54 2e 0a 0a 3c 70 3e 54 68 65 20 62 61  FSET...<p>The ba
2a120 73 69 63 20 61 6c 67 6f 72 69 74 68 6d 20 66 6f  sic algorithm fo
2a130 72 20 63 6f 6d 70 75 74 69 6e 67 20 74 68 65 20  r computing the 
2a140 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 72  content of the r
2a150 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 0a 69  ecursive table.i
2a160 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c  s as follows:..<
2a170 6f 6c 3e 0a 3c 6c 69 3e 20 52 75 6e 20 74 68 65  ol>.<li> Run the
2a180 20 3c 79 79 74 65 72 6d 3e 69 6e 69 74 69 61 6c   <yyterm>initial
2a190 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72 6d 3e  -select</yyterm>
2a1a0 20 61 6e 64 20 61 64 64 20 74 68 65 20 72 65 73   and add the res
2a1b0 75 6c 74 73 20 74 6f 20 61 20 71 75 65 75 65 2e  ults to a queue.
2a1c0 0a 3c 6c 69 3e 20 57 68 69 6c 65 20 74 68 65 20  .<li> While the 
2a1d0 71 75 65 75 65 20 69 73 20 6e 6f 74 20 65 6d 70  queue is not emp
2a1e0 74 79 3a 0a 3c 6f 6c 20 74 79 70 65 3d 22 61 22  ty:.<ol type="a"
2a1f0 3e 0a 3c 6c 69 3e 20 45 78 74 72 61 63 74 20 61  >.<li> Extract a
2a200 20 73 69 6e 67 6c 65 20 72 6f 77 20 66 72 6f 6d   single row from
2a210 20 74 68 65 20 71 75 65 75 65 2e 0a 3c 6c 69 3e   the queue..<li>
2a220 20 49 6e 73 65 72 74 20 74 68 61 74 20 73 69 6e   Insert that sin
2a230 67 6c 65 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  gle row into the
2a240 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65   recursive table
2a250 0a 3c 6c 69 3e 20 50 72 65 74 65 6e 64 20 74 68  .<li> Pretend th
2a260 61 74 20 74 68 65 20 73 69 6e 67 6c 65 20 72 6f  at the single ro
2a270 77 20 6a 75 73 74 20 65 78 74 72 61 63 74 65 64  w just extracted
2a280 20 69 73 20 74 68 65 20 6f 6e 6c 79 0a 20 20 20   is the only.   
2a290 20 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65 63    row in the rec
2a2a0 75 72 73 69 76 65 20 74 61 62 6c 65 20 61 6e 64  ursive table and
2a2b0 20 72 75 6e 20 74 68 65 20 72 65 63 75 72 73 69   run the recursi
2a2c0 76 65 2d 73 65 6c 65 63 74 2c 0a 20 20 20 20 20  ve-select,.     
2a2d0 61 64 64 69 6e 67 20 61 6c 6c 20 72 65 73 75 6c  adding all resul
2a2e0 74 73 20 74 6f 20 74 68 65 20 71 75 65 75 65 2e  ts to the queue.
2a2f0 0a 3c 2f 6f 6c 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70  .</ol>.</ol>..<p
2a300 3e 54 68 65 20 62 61 73 69 63 20 70 72 6f 63 65  >The basic proce
2a310 64 75 72 65 20 61 62 6f 76 65 20 6d 61 79 20 6d  dure above may m
2a320 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 66  odified by the f
2a330 6f 6c 6c 6f 77 69 6e 67 20 61 64 64 69 74 69 6f  ollowing additio
2a340 6e 61 6c 20 72 75 6c 65 73 3a 0a 0a 3c 75 6c 3e  nal rules:..<ul>
2a350 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 49 66 20 61 20  .<li><p>.  If a 
2a360 55 4e 49 4f 4e 20 6f 70 65 72 61 74 6f 72 20 63  UNION operator c
2a370 6f 6e 6e 65 63 74 73 20 74 68 65 20 3c 79 79 74  onnects the <yyt
2a380 65 72 6d 3e 69 6e 69 74 69 61 6c 2d 73 65 6c 65  erm>initial-sele
2a390 63 74 3c 2f 79 79 74 65 72 6d 3e 20 77 69 74 68  ct</yyterm> with
2a3a0 20 74 68 65 0a 20 20 3c 79 79 74 65 72 6d 3e 72   the.  <yyterm>r
2a3b0 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 3c  ecursive-select<
2a3c0 2f 79 79 74 65 72 6d 3e 2c 20 74 68 65 6e 20 6f  /yyterm>, then o
2a3d0 6e 6c 79 20 61 64 64 20 72 6f 77 73 20 74 6f 20  nly add rows to 
2a3e0 74 68 65 20 71 75 65 75 65 20 69 66 20 0a 20 20  the queue if .  
2a3f0 6e 6f 20 69 64 65 6e 74 69 63 61 6c 20 72 6f 77  no identical row
2a400 20 68 61 73 0a 20 20 62 65 65 6e 20 70 72 65 76   has.  been prev
2a410 69 6f 75 73 6c 79 20 61 64 64 65 64 20 74 6f 20  iously added to 
2a420 74 68 65 20 71 75 65 75 65 2e 20 20 52 65 70 65  the queue.  Repe
2a430 61 74 65 64 20 72 6f 77 73 20 61 72 65 20 64 69  ated rows are di
2a440 73 63 61 72 64 65 64 20 62 65 66 6f 72 65 20 62  scarded before b
2a450 65 69 6e 67 0a 20 20 61 64 64 65 64 20 74 6f 20  eing.  added to 
2a460 74 68 65 20 71 75 65 75 65 20 65 76 65 6e 20 69  the queue even i
2a470 66 20 74 68 65 20 72 65 70 65 61 74 65 64 20 72  f the repeated r
2a480 6f 77 73 20 68 61 76 65 20 61 6c 72 65 61 64 79  ows have already
2a490 20 62 65 65 6e 20 65 78 74 72 61 63 74 65 64 0a   been extracted.
2a4a0 20 20 66 72 6f 6d 20 74 68 65 20 71 75 65 75 65    from the queue
2a4b0 20 62 79 20 74 68 65 20 72 65 63 75 72 73 69 6f   by the recursio
2a4c0 6e 20 73 74 65 70 2e 20 20 49 66 20 74 68 65 20  n step.  If the 
2a4d0 6f 70 65 72 61 74 6f 72 20 69 73 20 55 4e 49 4f  operator is UNIO
2a4e0 4e 20 41 4c 4c 2c 0a 20 20 74 68 65 6e 20 61 6c  N ALL,.  then al
2a4f0 6c 20 72 6f 77 73 20 67 65 6e 65 72 61 74 65 64  l rows generated
2a500 20 62 79 20 62 6f 74 68 20 74 68 65 20 3c 79 79   by both the <yy
2a510 74 65 72 6d 3e 69 6e 69 74 69 61 6c 2d 73 65 6c  term>initial-sel
2a520 65 63 74 3c 2f 79 79 74 65 72 6d 3e 20 61 6e 64  ect</yyterm> and
2a530 20 74 68 65 0a 20 20 3c 79 79 74 65 72 6d 3e 72   the.  <yyterm>r
2a540 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63 74 3c  ecursive-select<
2a550 2f 79 79 74 65 72 6d 3e 20 61 72 65 20 61 6c 77  /yyterm> are alw
2a560 61 79 73 20 61 64 64 65 64 20 74 6f 20 74 68 65  ays added to the
2a570 20 71 75 65 75 65 20 65 76 65 6e 20 69 66 0a 20   queue even if. 
2a580 20 74 68 65 79 20 61 72 65 20 72 65 70 65 61 74   they are repeat
2a590 73 2e 0a 20 20 57 68 65 6e 20 64 65 74 65 72 6d  s..  When determ
2a5a0 69 6e 69 6e 67 20 69 66 20 61 20 72 6f 77 20 69  ining if a row i
2a5b0 73 20 72 65 70 65 61 74 65 64 2c 20 4e 55 4c 4c  s repeated, NULL
2a5c0 20 76 61 6c 75 65 73 20 63 6f 6d 70 61 72 65 0a   values compare.
2a5d0 20 20 65 71 75 61 6c 20 74 6f 20 6f 6e 65 20 61    equal to one a
2a5e0 6e 6f 74 68 65 72 20 61 6e 64 20 6e 6f 74 20 65  nother and not e
2a5f0 71 75 61 6c 20 74 6f 20 61 6e 79 20 6f 74 68 65  qual to any othe
2a600 72 20 76 61 6c 75 65 2e 0a 3c 6c 69 3e 3c 70 3e  r value..<li><p>
2a610 0a 20 20 54 68 65 20 4c 49 4d 49 54 20 63 6c 61  .  The LIMIT cla
2a620 75 73 65 2c 20 69 66 20 70 72 65 73 65 6e 74 2c  use, if present,
2a630 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
2a640 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a650 66 20 72 6f 77 73 20 74 68 61 74 0a 20 20 77 69  f rows that.  wi
2a660 6c 6c 20 65 76 65 72 20 62 65 20 61 64 64 65 64  ll ever be added
2a670 20 74 6f 20 74 68 65 20 72 65 63 75 72 73 69 76   to the recursiv
2a680 65 20 74 61 62 6c 65 20 69 6e 20 73 74 65 70 20  e table in step 
2a690 32 62 2e 0a 20 20 4f 6e 63 65 20 74 68 65 20 6c  2b..  Once the l
2a6a0 69 6d 69 74 20 69 73 20 72 65 61 63 68 65 64 2c  imit is reached,
2a6b0 20 74 68 65 20 72 65 63 75 72 73 69 6f 6e 20 73   the recursion s
2a6c0 74 6f 70 73 2e 0a 20 20 41 20 6c 69 6d 69 74 20  tops..  A limit 
2a6d0 6f 66 20 7a 65 72 6f 20 6d 65 61 6e 73 20 74 68  of zero means th
2a6e0 61 74 20 6e 6f 20 72 6f 77 73 20 61 72 65 20 65  at no rows are e
2a6f0 76 65 72 20 61 64 64 65 64 20 74 6f 20 74 68 65  ver added to the
2a700 0a 20 20 72 65 63 75 72 73 69 76 65 20 74 61 62  .  recursive tab
2a710 6c 65 2c 20 61 6e 64 20 61 20 6e 65 67 61 74 69  le, and a negati
2a720 76 65 20 6c 69 6d 69 74 20 6d 65 61 6e 73 20 61  ve limit means a
2a730 6e 20 75 6e 6c 69 6d 69 74 65 64 20 6e 75 6d 62  n unlimited numb
2a740 65 72 20 6f 66 20 72 6f 77 73 0a 20 20 6d 61 79  er of rows.  may
2a750 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2a760 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65   recursive table
2a770 2e 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 54 68 65 20  ..<li><p>.  The 
2a780 4f 46 46 53 45 54 20 63 6c 61 75 73 65 2c 20 69  OFFSET clause, i
2a790 66 20 69 74 20 69 73 20 70 72 65 73 65 6e 74 20  f it is present 
2a7a0 61 6e 64 20 68 61 73 20 61 20 70 6f 73 69 74 69  and has a positi
2a7b0 76 65 20 76 61 6c 75 65 20 4e 2c 20 70 72 65 76  ve value N, prev
2a7c0 65 6e 74 73 20 74 68 65 0a 20 20 66 69 72 73 74  ents the.  first
2a7d0 20 4e 20 72 6f 77 73 20 66 72 6f 6d 20 62 65 69   N rows from bei
2a7e0 6e 67 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  ng added to the 
2a7f0 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65 2e  recursive table.
2a800 0a 20 20 54 68 65 20 66 69 72 73 74 20 4e 20 72  .  The first N r
2a810 6f 77 73 20 61 72 65 20 73 74 69 6c 6c 20 70 72  ows are still pr
2a820 6f 63 65 73 73 65 64 0a 20 20 62 79 20 74 68 65  ocessed.  by the
2a830 20 3c 79 79 74 65 72 6d 3e 72 65 63 75 72 73 69   <yyterm>recursi
2a840 76 65 2d 73 65 6c 65 63 74 3c 2f 79 79 74 65 72  ve-select</yyter
2a850 6d 3e 20 26 6d 64 61 73 68 3b 20 74 68 65 79 0a  m> &mdash; they.
2a860 20 20 6a 75 73 74 20 61 72 65 20 6e 6f 74 20 61    just are not a
2a870 64 64 65 64 20 74 6f 20 74 68 65 20 72 65 63 75  dded to the recu
2a880 72 73 69 76 65 20 74 61 62 6c 65 2e 20 20 52 6f  rsive table.  Ro
2a890 77 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ws are not count
2a8a0 65 64 20 74 6f 77 61 72 64 0a 20 20 66 75 6c 66  ed toward.  fulf
2a8b0 69 6c 6c 69 6e 67 20 74 68 65 20 4c 49 4d 49 54  illing the LIMIT
2a8c0 20 75 6e 74 69 6c 20 61 6c 6c 20 4f 46 46 53 45   until all OFFSE
2a8d0 54 20 72 6f 77 73 20 68 61 76 65 20 62 65 65 6e  T rows have been
2a8e0 20 73 6b 69 70 70 65 64 2e 0a 3c 6c 69 3e 3c 70   skipped..<li><p
2a8f0 3e 0a 20 20 49 66 20 61 6e 20 4f 52 44 45 52 20  >.  If an ORDER 
2a900 42 59 20 63 6c 61 75 73 65 20 69 73 20 70 72 65  BY clause is pre
2a910 73 65 6e 74 2c 20 69 74 20 64 65 74 65 72 6d 69  sent, it determi
2a920 6e 65 73 20 74 68 65 20 6f 72 64 65 72 20 69 6e  nes the order in
2a930 20 77 68 69 63 68 20 72 6f 77 73 0a 20 20 61 72   which rows.  ar
2a940 65 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  e extracted from
2a950 20 74 68 65 20 71 75 65 75 65 20 69 6e 20 73 74   the queue in st
2a960 65 70 20 32 61 2e 20 20 49 66 20 74 68 65 72 65  ep 2a.  If there
2a970 20 69 73 20 6e 6f 20 4f 52 44 45 52 20 42 59 20   is no ORDER BY 
2a980 63 6c 61 75 73 65 2c 0a 20 20 74 68 65 6e 20 74  clause,.  then t
2a990 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2a9a0 68 20 72 6f 77 73 20 61 72 65 20 65 78 74 72 61  h rows are extra
2a9b0 63 74 65 64 20 69 73 20 75 6e 64 65 66 69 6e 65  cted is undefine
2a9c0 64 2e 20 20 28 49 6e 20 74 68 65 20 63 75 72 72  d.  (In the curr
2a9d0 65 6e 74 0a 20 20 69 6d 70 6c 65 6d 65 6e 74 61  ent.  implementa
2a9e0 74 69 6f 6e 2c 20 74 68 65 20 71 75 65 75 65 20  tion, the queue 
2a9f0 62 65 63 6f 6d 65 73 20 61 20 46 49 46 4f 20 69  becomes a FIFO i
2aa00 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
2aa10 6c 61 75 73 65 20 69 73 20 6f 6d 69 74 74 65 64  lause is omitted
2aa20 2c 0a 20 20 62 75 74 20 61 70 70 6c 69 63 61 74  ,.  but applicat
2aa30 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
2aa40 64 65 70 65 6e 64 20 6f 6e 20 74 68 61 74 20 66  depend on that f
2aa50 61 63 74 20 73 69 6e 63 65 20 69 74 20 6d 69 67  act since it mig
2aa60 68 74 20 63 68 61 6e 67 65 2e 29 0a 3c 2f 75 6c  ht change.).</ul
2aa70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  >..<tcl>hd_fragm
2aa80 65 6e 74 20 72 63 65 78 31 3c 2f 74 63 6c 3e 0a  ent rcex1</tcl>.
2aa90 3c 68 34 3e 52 65 63 75 72 73 69 76 65 20 51 75  <h4>Recursive Qu
2aaa0 65 72 79 20 45 78 61 6d 70 6c 65 73 3c 2f 68 34  ery Examples</h4
2aab0 3e 0a 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f 77  >..<p>The follow
2aac0 69 6e 67 20 71 75 65 72 79 20 72 65 74 75 72 6e  ing query return
2aad0 73 20 61 6c 6c 20 69 6e 74 65 67 65 72 73 20 62  s all integers b
2aae0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 31 30 30  etween 1 and 100
2aaf0 30 30 30 30 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  0000:..<blockquo
2ab00 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45  te><pre>.WITH RE
2ab10 43 55 52 53 49 56 45 0a 20 20 63 6e 74 28 78 29  CURSIVE.  cnt(x)
2ab20 20 41 53 20 28 56 41 4c 55 45 53 28 31 29 20 55   AS (VALUES(1) U
2ab30 4e 49 4f 4e 20 41 4c 4c 20 53 45 4c 45 43 54 20  NION ALL SELECT 
2ab40 78 2b 31 20 46 52 4f 4d 20 63 6e 74 20 57 48 45  x+1 FROM cnt WHE
2ab50 52 45 20 78 3c 31 30 30 30 30 30 30 29 0a 53 45  RE x<1000000).SE
2ab60 4c 45 43 54 20 78 20 46 52 4f 4d 20 63 6e 74 3b  LECT x FROM cnt;
2ab70 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
2ab80 6f 74 65 3e 0a 0a 3c 70 3e 43 6f 6e 73 69 64 65  ote>..<p>Conside
2ab90 72 20 68 6f 77 20 74 68 69 73 20 71 75 65 72 79  r how this query
2aba0 20 77 6f 72 6b 73 2e 20 20 54 68 65 20 69 6e 69   works.  The ini
2abb0 74 69 61 6c 2d 73 65 6c 65 63 74 0a 72 75 6e 73  tial-select.runs
2abc0 20 66 69 72 73 74 20 61 6e 64 20 72 65 74 75 72   first and retur
2abd0 6e 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 0a  ns a single row.
2abe0 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 63 6f  with a single co
2abf0 6c 75 6d 6e 20 22 31 22 2e 20 20 54 68 69 73 20  lumn "1".  This 
2ac00 6f 6e 65 20 72 6f 77 20 69 73 20 61 64 64 65 64  one row is added
2ac10 20 74 6f 20 74 68 65 20 71 75 65 75 65 2e 20 20   to the queue.  
2ac20 49 6e 0a 73 74 65 70 20 32 61 2c 20 74 68 61 74  In.step 2a, that
2ac30 20 6f 6e 65 20 72 6f 77 20 69 73 20 65 78 74 72   one row is extr
2ac40 61 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 71  acted from the q
2ac50 75 65 75 65 20 61 6e 64 20 61 64 64 65 64 20 74  ueue and added t
2ac60 6f 20 22 63 6e 74 22 2e 0a 54 68 65 6e 20 74 68  o "cnt"..Then th
2ac70 65 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65  e recursive-sele
2ac80 63 74 20 69 73 20 72 75 6e 20 69 6e 20 61 63 63  ct is run in acc
2ac90 6f 72 64 61 6e 63 65 20 77 69 74 68 20 73 74 65  ordance with ste
2aca0 70 20 32 63 20 67 65 6e 65 72 61 74 69 6e 67 0a  p 2c generating.
2acb0 61 20 73 69 6e 67 6c 65 20 6e 65 77 20 72 6f 77  a single new row
2acc0 20 77 69 74 68 20 76 61 6c 75 65 20 22 32 22 20   with value "2" 
2acd0 74 6f 20 61 64 64 20 74 6f 20 74 68 65 20 71 75  to add to the qu
2ace0 65 75 65 2e 20 20 54 68 65 20 71 75 65 75 65 20  eue.  The queue 
2acf0 73 74 69 6c 6c 0a 68 61 73 20 6f 6e 65 20 72 6f  still.has one ro
2ad00 77 2c 20 73 6f 20 73 74 65 70 20 32 20 72 65 70  w, so step 2 rep
2ad10 65 61 74 73 2e 20 20 54 68 65 20 22 32 22 20 72  eats.  The "2" r
2ad20 6f 77 20 69 73 20 65 78 74 72 61 63 74 65 64 20  ow is extracted 
2ad30 61 6e 64 20 61 64 64 65 64 20 74 6f 20 74 68 65  and added to the
2ad40 0a 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65  .recursive table
2ad50 20 62 79 20 73 74 65 70 73 20 32 61 20 61 6e 64   by steps 2a and
2ad60 20 32 62 2e 20 20 54 68 65 6e 20 74 68 65 20 72   2b.  Then the r
2ad70 6f 77 20 63 6f 6e 74 61 69 6e 69 6e 67 20 32 20  ow containing 2 
2ad80 69 73 20 75 73 65 64 20 0a 61 73 20 69 66 20 69  is used .as if i
2ad90 74 20 77 65 72 65 20 74 68 65 20 63 6f 6d 70 6c  t were the compl
2ada0 65 74 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  ete content of t
2adb0 68 65 20 72 65 63 75 72 73 69 76 65 20 74 61 62  he recursive tab
2adc0 6c 65 20 61 6e 64 20 74 68 65 20 0a 72 65 63 75  le and the .recu
2add0 72 73 69 76 65 2d 73 65 6c 65 63 74 20 69 73 20  rsive-select is 
2ade0 72 75 6e 20 61 67 61 69 6e 2c 20 72 65 73 75 6c  run again, resul
2adf0 74 69 6e 67 20 69 6e 20 61 20 72 6f 77 20 77 69  ting in a row wi
2ae00 74 68 20 76 61 6c 75 65 20 22 33 22 20 62 65 69  th value "3" bei
2ae10 6e 67 20 61 64 64 65 64 0a 74 6f 20 74 68 65 20  ng added.to the 
2ae20 71 75 65 75 65 2e 20 20 54 68 69 73 20 72 65 70  queue.  This rep
2ae30 65 61 74 73 20 39 39 39 39 39 39 20 74 69 6d 65  eats 999999 time
2ae40 73 20 75 6e 74 69 6c 20 66 69 6e 61 6c 6c 79 20  s until finally 
2ae50 61 74 20 73 74 65 70 20 32 61 20 74 68 65 0a 6f  at step 2a the.o
2ae60 6e 6c 79 20 76 61 6c 75 65 20 6f 6e 20 74 68 65  nly value on the
2ae70 20 71 75 65 75 65 20 69 73 20 61 20 72 6f 77 20   queue is a row 
2ae80 63 6f 6e 74 61 69 6e 69 6e 67 20 31 30 30 30 30  containing 10000
2ae90 30 30 2e 20 20 54 68 61 74 20 72 6f 77 20 69 73  00.  That row is
2aea0 0a 65 78 74 72 61 63 74 65 64 20 61 6e 64 20 61  .extracted and a
2aeb0 64 64 65 64 20 74 6f 20 74 68 65 20 72 65 63 75  dded to the recu
2aec0 72 73 69 76 65 20 74 61 62 6c 65 2e 20 20 42 75  rsive table.  Bu
2aed0 74 20 74 68 69 73 20 74 69 6d 65 2c 20 74 68 65  t this time, the
2aee0 0a 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 61  .WHERE clause ca
2aef0 75 73 65 73 20 74 68 65 20 72 65 63 75 72 73 69  uses the recursi
2af00 76 65 2d 73 65 6c 65 63 74 20 74 6f 20 72 65 74  ve-select to ret
2af10 75 72 6e 20 6e 6f 20 72 6f 77 73 2c 20 73 6f 20  urn no rows, so 
2af20 74 68 65 0a 71 75 65 75 65 20 72 65 6d 61 69 6e  the.queue remain
2af30 73 20 65 6d 70 74 79 20 61 6e 64 20 74 68 65 20  s empty and the 
2af40 72 65 63 75 72 73 69 6f 6e 20 73 74 6f 70 73 2e  recursion stops.
2af50 0a 0a 3c 70 3e 3c 62 3e 4f 70 74 69 6d 69 7a 61  ..<p><b>Optimiza
2af60 74 69 6f 6e 20 6e 6f 74 65 3a 3c 2f 62 3e 0a 49  tion note:</b>.I
2af70 6e 20 74 68 65 20 64 69 73 63 75 73 73 69 6f 6e  n the discussion
2af80 20 61 62 6f 76 65 2c 20 73 74 61 74 65 6d 65 6e   above, statemen
2af90 74 73 20 6c 69 6b 65 20 22 69 6e 73 65 72 74 20  ts like "insert 
2afa0 74 68 65 20 72 6f 77 20 69 6e 74 6f 0a 74 68 65  the row into.the
2afb0 20 72 65 63 75 72 73 69 76 65 20 74 61 62 6c 65   recursive table
2afc0 22 20 73 68 6f 75 6c 64 20 62 65 20 75 6e 64 65  " should be unde
2afd0 72 73 74 6f 6f 64 20 63 6f 6e 63 65 70 74 75 61  rstood conceptua
2afe0 6c 6c 79 2c 20 6e 6f 74 20 6c 69 74 65 72 61 6c  lly, not literal
2aff0 6c 79 2e 0a 49 74 20 73 6f 75 6e 64 73 20 61 73  ly..It sounds as
2b000 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 61 63   if SQLite is ac
2b010 63 75 6d 75 6c 61 74 69 6e 67 20 61 20 68 75 67  cumulating a hug
2b020 65 20 74 61 62 6c 65 0a 63 6f 6e 74 61 69 6e 69  e table.containi
2b030 6e 67 20 6f 6e 65 20 6d 69 6c 6c 69 6f 6e 20 72  ng one million r
2b040 6f 77 73 2c 20 74 68 65 6e 20 67 6f 69 6e 67 20  ows, then going 
2b050 62 61 63 6b 20 61 6e 64 20 73 63 61 6e 6e 69 6e  back and scannin
2b060 67 20 74 68 61 74 20 74 61 62 6c 65 0a 66 72 6f  g that table.fro
2b070 6d 20 74 6f 70 20 74 6f 20 62 6f 74 74 6f 6d 20  m top to bottom 
2b080 74 6f 20 67 65 6e 65 72 61 74 65 20 74 68 65 20  to generate the 
2b090 72 65 73 75 6c 74 2e 20 20 57 68 61 74 20 72 65  result.  What re
2b0a0 61 6c 6c 79 20 68 61 70 70 65 6e 73 0a 69 73 20  ally happens.is 
2b0b0 74 68 61 74 20 74 68 65 20 71 75 65 72 79 20 6f  that the query o
2b0c0 70 74 69 6d 69 7a 65 72 20 73 65 65 73 20 74 68  ptimizer sees th
2b0d0 61 74 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  at values in the
2b0e0 0a 22 63 6e 74 22 20 72 65 63 75 72 73 69 76 65  ."cnt" recursive
2b0f0 20 74 61 62 6c 65 20 61 72 65 20 6f 6e 6c 79 20   table are only 
2b100 75 73 65 64 20 6f 6e 63 65 2e 20 20 53 6f 20 61  used once.  So a
2b110 73 20 65 61 63 68 20 72 6f 77 20 69 73 20 61 64  s each row is ad
2b120 64 65 64 20 74 6f 0a 74 68 65 20 72 65 63 75 72  ded to.the recur
2b130 73 69 76 65 20 74 61 62 6c 65 2c 20 74 68 61 74  sive table, that
2b140 20 72 6f 77 20 69 73 20 69 6d 6d 65 64 69 61 74   row is immediat
2b150 65 6c 79 20 72 65 74 75 72 6e 65 64 20 61 73 20  ely returned as 
2b160 61 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  a result of the 
2b170 6d 61 69 6e 0a 53 45 4c 45 43 54 20 73 74 61 74  main.SELECT stat
2b180 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 6e 20 64  ement and then d
2b190 69 73 63 61 72 64 65 64 2e 20 20 53 51 4c 69 74  iscarded.  SQLit
2b1a0 65 20 64 6f 65 73 20 3c 65 6d 3e 6e 6f 74 3c 2f  e does <em>not</
2b1b0 65 6d 3e 20 61 63 63 75 6d 75 6c 61 74 65 0a 61  em> accumulate.a
2b1c0 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65   temporary table
2b1d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 6d 69   containing a mi
2b1e0 6c 6c 69 6f 6e 20 72 6f 77 73 2e 20 20 56 65 72  llion rows.  Ver
2b1f0 79 20 6c 69 74 74 6c 65 20 6d 65 6d 6f 72 79 20  y little memory 
2b200 69 73 0a 6e 65 65 64 65 64 20 74 6f 20 72 75 6e  is.needed to run
2b210 20 74 68 65 20 61 62 6f 76 65 20 65 78 61 6d 70   the above examp
2b220 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  le.  However, if
2b230 20 74 68 65 20 65 78 61 6d 70 6c 65 20 68 61 64   the example had
2b240 20 75 73 65 64 0a 55 4e 49 4f 4e 20 69 6e 73 74   used.UNION inst
2b250 65 61 64 20 6f 66 20 55 4e 49 4f 4e 20 41 4c 4c  ead of UNION ALL
2b260 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 77 6f  , then SQLite wo
2b270 75 6c 64 20 68 61 76 65 20 68 61 64 20 74 6f 20  uld have had to 
2b280 6b 65 65 70 20 61 72 6f 75 6e 64 0a 61 6c 6c 20  keep around.all 
2b290 70 72 65 76 69 6f 75 73 6c 79 20 67 65 6e 65 72  previously gener
2b2a0 61 74 65 64 20 63 6f 6e 74 65 6e 74 20 69 6e 20  ated content in 
2b2b0 6f 72 64 65 72 20 74 6f 20 63 68 65 63 6b 20 66  order to check f
2b2c0 6f 72 20 64 75 70 6c 69 63 61 74 65 73 2e 0a 46  or duplicates..F
2b2d0 6f 72 20 74 68 69 73 20 72 65 61 73 6f 6e 2c 20  or this reason, 
2b2e0 70 72 6f 67 72 61 6d 6d 65 72 73 20 73 68 6f 75  programmers shou
2b2f0 6c 64 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ld strive to use
2b300 20 55 4e 49 4f 4e 20 41 4c 4c 20 69 6e 73 74 65   UNION ALL inste
2b310 61 64 0a 6f 66 20 55 4e 49 4f 4e 20 77 68 65 6e  ad.of UNION when
2b320 20 66 65 61 73 69 62 6c 65 2e 0a 0a 3c 70 3e 48   feasible...<p>H
2b330 65 72 65 20 69 73 20 61 20 76 61 72 69 61 74 69  ere is a variati
2b340 6f 6e 20 6f 6e 20 74 68 65 20 70 72 65 76 69 6f  on on the previo
2b350 75 73 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 62 6c  us example:..<bl
2b360 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 57  ockquote><pre>.W
2b370 49 54 48 20 52 45 43 55 52 53 49 56 45 0a 20 20  ITH RECURSIVE.  
2b380 63 6e 74 28 78 29 20 41 53 20 28 0a 20 20 20 20  cnt(x) AS (.    
2b390 20 53 45 4c 45 43 54 20 31 0a 20 20 20 20 20 55   SELECT 1.     U
2b3a0 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20 20 53 45  NION ALL.     SE
2b3b0 4c 45 43 54 20 78 2b 31 20 46 52 4f 4d 20 63 6e  LECT x+1 FROM cn
2b3c0 74 0a 20 20 20 20 20 20 4c 49 4d 49 54 20 31 30  t.      LIMIT 10
2b3d0 30 30 30 30 30 0a 20 20 29 0a 53 45 4c 45 43 54  00000.  ).SELECT
2b3e0 20 78 20 46 52 4f 4d 20 63 6e 74 3b 0a 3c 2f 70   x FROM cnt;.</p
2b3f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2b400 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20 74  ..<p>There are t
2b410 77 6f 20 64 69 66 66 65 72 65 6e 63 65 73 20 69  wo differences i
2b420 6e 20 74 68 69 73 20 76 61 72 69 61 74 69 6f 6e  n this variation
2b430 2e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 2d 73  .  The initial-s
2b440 65 6c 65 63 74 20 69 73 0a 22 53 45 4c 45 43 54  elect is."SELECT
2b450 20 31 22 20 69 6e 73 74 65 61 64 20 6f 66 20 22   1" instead of "
2b460 56 41 4c 55 45 53 28 31 29 22 2e 20 20 42 75 74  VALUES(1)".  But
2b470 20 74 68 6f 73 65 20 61 72 65 20 6a 75 73 74 20   those are just 
2b480 64 69 66 66 65 72 65 6e 74 0a 73 79 6e 74 61 78  different.syntax
2b490 65 73 20 66 6f 72 20 73 61 79 69 6e 67 20 65 78  es for saying ex
2b4a0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 74  actly the same t
2b4b0 68 69 6e 67 2e 20 20 54 68 65 20 6f 74 68 65 72  hing.  The other
2b4c0 20 63 68 61 6e 67 65 20 69 73 20 74 68 61 74 20   change is that 
2b4d0 74 68 65 0a 72 65 63 75 72 73 69 6f 6e 20 69 73  the.recursion is
2b4e0 20 73 74 6f 70 70 65 64 20 62 79 20 61 20 4c 49   stopped by a LI
2b4f0 4d 49 54 20 72 61 74 68 65 72 20 74 68 61 6e 20  MIT rather than 
2b500 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 2e 20  a WHERE clause. 
2b510 20 54 68 65 20 75 73 65 20 6f 66 0a 4c 49 4d 49   The use of.LIMI
2b520 54 20 6d 65 61 6e 73 20 74 68 61 74 20 77 68 65  T means that whe
2b530 6e 20 74 68 65 20 6f 6e 65 2d 6d 69 6c 6c 69 6f  n the one-millio
2b540 6e 74 68 20 72 6f 77 20 69 73 20 61 64 64 65 64  nth row is added
2b550 20 74 6f 20 74 68 65 20 22 63 6e 74 22 20 74 61   to the "cnt" ta
2b560 62 6c 65 0a 28 61 6e 64 20 72 65 74 75 72 6e 65  ble.(and returne
2b570 64 20 62 79 20 74 68 65 20 6d 61 69 6e 20 53 45  d by the main SE
2b580 4c 45 43 54 2c 20 74 68 61 6e 6b 73 20 74 6f 20  LECT, thanks to 
2b590 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
2b5a0 7a 65 72 29 0a 74 68 65 6e 20 74 68 65 20 72 65  zer).then the re
2b5b0 63 75 72 73 69 6f 6e 20 73 74 6f 70 73 20 69 6d  cursion stops im
2b5c0 6d 65 64 69 61 74 65 6c 79 20 72 65 67 61 72 64  mediately regard
2b5d0 6c 65 73 73 20 6f 66 20 68 6f 77 20 6d 61 6e 79  less of how many
2b5e0 20 72 6f 77 73 20 6d 69 67 68 74 20 62 65 0a 6c   rows might be.l
2b5f0 65 66 74 20 69 6e 20 74 68 65 20 71 75 65 75 65  eft in the queue
2b600 2e 20 20 4f 6e 20 6d 6f 72 65 20 63 6f 6d 70 6c  .  On more compl
2b610 65 78 20 71 75 65 72 69 65 73 2c 20 69 74 20 63  ex queries, it c
2b620 61 6e 20 73 6f 6d 65 74 69 6d 65 73 20 62 65 0a  an sometimes be.
2b630 64 69 66 66 69 63 75 6c 74 20 74 6f 20 65 6e 73  difficult to ens
2b640 75 72 65 20 74 68 61 74 20 74 68 65 20 57 48 45  ure that the WHE
2b650 52 45 20 63 6c 61 75 73 65 20 77 69 6c 6c 20 65  RE clause will e
2b660 76 65 6e 74 75 61 6c 6c 79 20 63 61 75 73 65 20  ventually cause 
2b670 74 68 65 0a 71 75 65 75 65 20 74 6f 20 64 72 61  the.queue to dra
2b680 69 6e 20 61 6e 64 20 74 68 65 20 72 65 63 75 72  in and the recur
2b690 73 69 6f 6e 20 74 6f 20 74 65 72 6d 69 6e 61 74  sion to terminat
2b6a0 65 2e 20 20 42 75 74 20 74 68 65 20 4c 49 4d 49  e.  But the LIMI
2b6b0 54 20 63 6c 61 75 73 65 20 77 69 6c 6c 0a 61 6c  T clause will.al
2b6c0 77 61 79 73 20 73 74 6f 70 20 74 68 65 20 72 65  ways stop the re
2b6d0 63 75 72 73 69 6f 6e 2e 20 20 53 6f 20 69 74 20  cursion.  So it 
2b6e0 69 73 20 67 6f 6f 64 20 70 72 61 63 74 69 63 65  is good practice
2b6f0 20 74 6f 20 61 6c 77 61 79 73 20 69 6e 63 6c 75   to always inclu
2b700 64 65 20 61 0a 4c 49 4d 49 54 20 63 6c 61 75 73  de a.LIMIT claus
2b710 65 20 61 73 20 61 20 73 61 66 65 74 79 20 69 66  e as a safety if
2b720 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2b730 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  on the size of t
2b740 68 65 20 72 65 63 75 72 73 69 6f 6e 20 0a 69 73  he recursion .is
2b750 20 6b 6e 6f 77 6e 2e 0a 0a 3c 74 63 6c 3e 68 64   known...<tcl>hd
2b760 5f 66 72 61 67 6d 65 6e 74 20 72 63 65 78 32 3c  _fragment rcex2<
2b770 2f 74 63 6c 3e 0a 3c 68 34 3e 48 69 65 72 61 72  /tcl>.<h4>Hierar
2b780 63 68 69 63 61 6c 20 51 75 65 72 79 20 45 78 61  chical Query Exa
2b790 6d 70 6c 65 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 43  mples</h4>..<p>C
2b7a0 6f 6e 73 69 64 65 72 20 61 20 74 61 62 6c 65 20  onsider a table 
2b7b0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
2b7c0 68 65 20 6d 65 6d 62 65 72 73 20 6f 66 20 61 6e  he members of an
2b7d0 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 61 73   organization as
2b7e0 0a 77 65 6c 6c 20 61 73 20 74 68 65 20 63 68 61  .well as the cha
2b7f0 69 6e 2d 6f 66 2d 63 6f 6d 6d 61 6e 64 20 77 69  in-of-command wi
2b800 74 68 69 6e 20 74 68 61 74 20 6f 72 67 61 6e 69  thin that organi
2b810 7a 61 74 69 6f 6e 3a 0a 0a 3c 62 6c 6f 63 6b 71  zation:..<blockq
2b820 75 6f 74 65 3e 3c 70 72 65 3e 0a 43 52 45 41 54  uote><pre>.CREAT
2b830 45 20 54 41 42 4c 45 20 6f 72 67 28 0a 20 20 6e  E TABLE org(.  n
2b840 61 6d 65 20 54 45 58 54 20 50 52 49 4d 41 52 59  ame TEXT PRIMARY
2b850 20 4b 45 59 2c 0a 20 20 62 6f 73 73 20 54 45 58   KEY,.  boss TEX
2b860 54 20 52 45 46 45 52 45 4e 43 45 53 20 6f 72 67  T REFERENCES org
2b870 2c 0a 20 20 68 65 69 67 68 74 20 49 4e 54 2c 0a  ,.  height INT,.
2b880 20 20 2d 2d 20 6f 74 68 65 72 20 63 6f 6e 74 65    -- other conte
2b890 6e 74 20 6f 6d 69 74 74 65 64 0a 29 3b 0a 3c 2f  nt omitted.);.</
2b8a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2b8b0 3e 0a 0a 3c 70 3e 45 76 65 72 79 20 6d 65 6d 62  >..<p>Every memb
2b8c0 65 72 20 69 6e 20 74 68 65 20 6f 72 67 61 6e 69  er in the organi
2b8d0 7a 61 74 69 6f 6e 20 68 61 73 20 61 20 6e 61 6d  zation has a nam
2b8e0 65 2c 20 61 6e 64 20 6d 6f 73 74 20 6d 65 6d 62  e, and most memb
2b8f0 65 72 73 20 68 61 76 65 0a 61 20 73 69 6e 67 6c  ers have.a singl
2b900 65 20 62 6f 73 73 2e 20 20 28 54 68 65 20 68 65  e boss.  (The he
2b910 61 64 20 6f 66 20 74 68 65 20 77 68 6f 6c 65 20  ad of the whole 
2b920 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 68 61 73  organization has
2b930 20 61 20 4e 55 4c 4c 0a 22 62 6f 73 73 22 20 66   a NULL."boss" f
2b940 69 65 6c 64 2e 29 20 54 68 65 20 72 6f 77 73 20  ield.) The rows 
2b950 6f 66 20 74 68 65 20 22 6f 72 67 22 20 74 61 62  of the "org" tab
2b960 6c 65 20 66 6f 72 6d 20 61 20 74 72 65 65 2e 0a  le form a tree..
2b970 0a 3c 70 3e 48 65 72 65 20 69 73 20 61 20 71 75  .<p>Here is a qu
2b980 65 72 79 20 74 68 61 74 20 63 6f 6d 70 75 74 65  ery that compute
2b990 73 20 74 68 65 20 61 76 65 72 61 67 65 20 68 65  s the average he
2b9a0 69 67 68 74 20 6f 76 65 72 20 65 76 65 72 79 6f  ight over everyo
2b9b0 6e 65 0a 69 6e 20 41 6c 69 63 65 27 73 20 6f 72  ne.in Alice's or
2b9c0 67 61 6e 69 7a 61 74 69 6f 6e 2c 20 69 6e 63 6c  ganization, incl
2b9d0 75 64 69 6e 67 20 41 6c 69 63 65 3a 0a 0a 3c 62  uding Alice:..<b
2b9e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2b9f0 57 49 54 48 20 52 45 43 55 52 53 49 56 45 0a 20  WITH RECURSIVE. 
2ba00 20 77 6f 72 6b 73 5f 66 6f 72 5f 61 6c 69 63 65   works_for_alice
2ba10 28 6e 29 20 41 53 20 28 0a 20 20 20 20 56 41 4c  (n) AS (.    VAL
2ba20 55 45 53 28 27 41 6c 69 63 65 27 29 0a 20 20 20  UES('Alice').   
2ba30 20 55 4e 49 4f 4e 0a 20 20 20 20 53 45 4c 45 43   UNION.    SELEC
2ba40 54 20 6e 61 6d 65 20 46 52 4f 4d 20 6f 72 67 2c  T name FROM org,
2ba50 20 77 6f 72 6b 73 5f 66 6f 72 5f 61 6c 69 63 65   works_for_alice
2ba60 0a 20 20 20 20 20 57 48 45 52 45 20 6f 72 67 2e  .     WHERE org.
2ba70 62 6f 73 73 3d 77 6f 72 6b 73 5f 66 6f 72 5f 61  boss=works_for_a
2ba80 6c 69 63 65 2e 6e 0a 20 20 29 0a 53 45 4c 45 43  lice.n.  ).SELEC
2ba90 54 20 61 76 67 28 68 65 69 67 68 74 29 20 46 52  T avg(height) FR
2baa0 4f 4d 20 6f 72 67 0a 20 57 48 45 52 45 20 6f 72  OM org. WHERE or
2bab0 67 2e 6e 61 6d 65 20 49 4e 20 77 6f 72 6b 73 5f  g.name IN works_
2bac0 66 6f 72 5f 61 6c 69 63 65 3b 0a 3c 2f 70 72 65  for_alice;.</pre
2bad0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2bae0 3c 70 3e 54 68 65 20 6e 65 78 74 20 65 78 61 6d  <p>The next exam
2baf0 70 6c 65 20 75 73 65 73 20 74 77 6f 20 0a 63 6f  ple uses two .co
2bb00 6d 6d 6f 6e 20 74 61 62 6c 65 20 65 78 70 72 65  mmon table expre
2bb10 73 73 69 6f 6e 73 20 69 6e 20 61 20 73 69 6e 67  ssions in a sing
2bb20 6c 65 20 57 49 54 48 20 63 6c 61 75 73 65 2e 20  le WITH clause. 
2bb30 20 0a 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20   .The following 
2bb40 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 61 20  table records a 
2bb50 66 61 6d 69 6c 79 20 74 72 65 65 3a 0a 0a 3c 62  family tree:..<b
2bb60 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2bb70 43 52 45 41 54 45 20 54 41 42 4c 45 20 66 61 6d  CREATE TABLE fam
2bb80 69 6c 79 28 0a 20 20 6e 61 6d 65 20 54 45 58 54  ily(.  name TEXT
2bb90 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 0a 20 20   PRIMARY KEY,.  
2bba0 6d 6f 6d 20 54 45 58 54 20 52 45 46 45 52 45 4e  mom TEXT REFEREN
2bbb0 43 45 53 20 66 61 6d 69 6c 79 2c 0a 20 20 64 61  CES family,.  da
2bbc0 64 20 54 45 58 54 20 52 45 46 45 52 45 4e 43 45  d TEXT REFERENCE
2bbd0 53 20 66 61 6d 69 6c 79 2c 0a 20 20 62 6f 72 6e  S family,.  born
2bbe0 20 44 41 54 45 54 49 4d 45 2c 0a 20 20 64 69 65   DATETIME,.  die
2bbf0 64 20 44 41 54 45 54 49 4d 45 2c 20 2d 2d 20 4e  d DATETIME, -- N
2bc00 55 4c 4c 20 69 66 20 73 74 69 6c 6c 20 61 6c 69  ULL if still ali
2bc10 76 65 0a 20 20 2d 2d 20 6f 74 68 65 72 20 63 6f  ve.  -- other co
2bc20 6e 74 65 6e 74 0a 29 3b 0a 3c 2f 70 72 65 3e 3c  ntent.);.</pre><
2bc30 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
2bc40 3e 54 68 65 20 22 66 61 6d 69 6c 79 22 20 74 61  >The "family" ta
2bc50 62 6c 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ble is similar t
2bc60 6f 20 74 68 65 20 65 61 72 6c 69 65 72 20 22 6f  o the earlier "o
2bc70 72 67 22 20 74 61 62 6c 65 20 65 78 63 65 70 74  rg" table except
2bc80 20 74 68 61 74 20 0a 6e 6f 77 20 74 68 65 72 65   that .now there
2bc90 20 61 72 65 20 74 77 6f 20 70 61 72 65 6e 74 73   are two parents
2bca0 20 74 6f 20 65 61 63 68 20 6d 65 6d 62 65 72 2e   to each member.
2bcb0 0a 57 65 20 77 61 6e 74 20 74 6f 20 6b 6e 6f 77  .We want to know
2bcc0 20 61 6c 6c 20 6c 69 76 69 6e 67 20 61 6e 63 65   all living ance
2bcd0 73 74 6f 72 73 20 6f 66 20 41 6c 69 63 65 2c 20  stors of Alice, 
2bce0 66 72 6f 6d 20 6f 6c 64 65 73 74 20 74 6f 20 79  from oldest to y
2bcf0 6f 75 6e 67 65 73 74 2e 0a 41 6e 20 6f 72 64 69  oungest..An ordi
2bd00 6e 61 72 79 20 63 6f 6d 6d 6f 6e 20 74 61 62 6c  nary common tabl
2bd10 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 22 70  e expression, "p
2bd20 61 72 65 6e 74 5f 6f 66 22 2c 20 69 73 20 64 65  arent_of", is de
2bd30 66 69 6e 65 64 20 66 69 72 73 74 2e 20 20 54 68  fined first.  Th
2bd40 61 74 0a 6f 72 64 69 6e 61 72 79 20 43 54 45 20  at.ordinary CTE 
2bd50 69 73 20 61 20 76 69 65 77 20 74 68 61 74 20 63  is a view that c
2bd60 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2bd70 6e 64 20 61 6c 6c 20 70 61 72 65 6e 74 73 20 6f  nd all parents o
2bd80 66 20 61 6e 79 0a 69 6e 64 69 76 69 64 75 61 6c  f any.individual
2bd90 2e 20 20 54 68 61 74 20 6f 72 64 69 6e 61 72 79  .  That ordinary
2bda0 20 43 54 45 20 69 73 20 74 68 65 6e 20 75 73 65   CTE is then use
2bdb0 64 20 69 6e 20 74 68 65 20 22 61 6e 63 65 73 74  d in the "ancest
2bdc0 6f 72 5f 6f 66 5f 61 6c 69 63 65 22 0a 72 65 63  or_of_alice".rec
2bdd0 75 72 73 69 76 65 20 43 54 45 2e 20 20 54 68 65  ursive CTE.  The
2bde0 20 72 65 63 75 72 73 69 76 65 20 43 54 45 20 69   recursive CTE i
2bdf0 73 20 74 68 65 6e 20 75 73 65 64 20 69 6e 20 74  s then used in t
2be00 68 65 20 66 69 6e 61 6c 20 71 75 65 72 79 3a 0a  he final query:.
2be10 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
2be20 65 3e 0a 57 49 54 48 20 52 45 43 55 52 53 49 56  e>.WITH RECURSIV
2be30 45 0a 20 20 70 61 72 65 6e 74 5f 6f 66 28 6e 61  E.  parent_of(na
2be40 6d 65 2c 20 70 61 72 65 6e 74 29 20 41 53 0a 20  me, parent) AS. 
2be50 20 20 20 28 53 45 4c 45 43 54 20 6e 61 6d 65 2c     (SELECT name,
2be60 20 6d 6f 6d 20 46 52 4f 4d 20 66 61 6d 69 6c 79   mom FROM family
2be70 20 55 4e 49 4f 4e 20 53 45 4c 45 43 54 20 6e 61   UNION SELECT na
2be80 6d 65 2c 20 64 61 64 20 46 52 4f 4d 20 66 61 6d  me, dad FROM fam
2be90 69 6c 79 29 2c 0a 20 20 61 6e 63 65 73 74 6f 72  ily),.  ancestor
2bea0 5f 6f 66 5f 61 6c 69 63 65 28 6e 61 6d 65 29 20  _of_alice(name) 
2beb0 41 53 0a 20 20 20 20 28 53 45 4c 45 43 54 20 70  AS.    (SELECT p
2bec0 61 72 65 6e 74 20 46 52 4f 4d 20 70 61 72 65 6e  arent FROM paren
2bed0 74 5f 6f 66 20 57 48 45 52 45 20 6e 61 6d 65 3d  t_of WHERE name=
2bee0 27 41 6c 69 63 65 27 0a 20 20 20 20 20 55 4e 49  'Alice'.     UNI
2bef0 4f 4e 20 41 4c 4c 0a 20 20 20 20 20 53 45 4c 45  ON ALL.     SELE
2bf00 43 54 20 70 61 72 65 6e 74 20 46 52 4f 4d 20 70  CT parent FROM p
2bf10 61 72 65 6e 74 5f 6f 66 20 4a 4f 49 4e 20 61 6e  arent_of JOIN an
2bf20 63 65 73 74 6f 72 5f 6f 66 5f 61 6c 69 63 65 20  cestor_of_alice 
2bf30 55 53 49 4e 47 28 6e 61 6d 65 29 29 0a 53 45 4c  USING(name)).SEL
2bf40 45 43 54 20 66 61 6d 69 6c 79 2e 6e 61 6d 65 20  ECT family.name 
2bf50 46 52 4f 4d 20 61 6e 63 65 73 74 6f 72 5f 6f 66  FROM ancestor_of
2bf60 5f 61 6c 69 63 65 2c 20 66 61 6d 69 6c 79 0a 20  _alice, family. 
2bf70 57 48 45 52 45 20 61 6e 63 65 73 74 6f 72 5f 6f  WHERE ancestor_o
2bf80 66 5f 61 6c 69 63 65 2e 6e 61 6d 65 3d 66 61 6d  f_alice.name=fam
2bf90 69 6c 79 2e 6e 61 6d 65 0a 20 20 20 41 4e 44 20  ily.name.   AND 
2bfa0 64 69 65 64 20 49 53 20 4e 55 4c 4c 0a 20 4f 52  died IS NULL. OR
2bfb0 44 45 52 20 42 59 20 62 6f 72 6e 3b 0a 3c 2f 70  DER BY born;.</p
2bfc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2bfd0 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
2bfe0 6e 74 20 72 63 65 78 33 3c 2f 74 63 6c 3e 0a 3c  nt rcex3</tcl>.<
2bff0 68 34 3e 51 75 65 72 69 65 73 20 41 67 61 69 6e  h4>Queries Again
2c000 73 74 20 41 20 47 72 61 70 68 3c 2f 68 34 3e 0a  st A Graph</h4>.
2c010 0a 3c 70 3e 41 20 76 65 72 73 69 6f 6e 20 63 6f  .<p>A version co
2c020 6e 74 72 6f 6c 20 73 79 73 74 65 6d 20 28 56 43  ntrol system (VC
2c030 53 29 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  S) will typicall
2c040 79 20 73 74 6f 72 65 20 74 68 65 20 65 76 6f 6c  y store the evol
2c050 76 69 6e 67 0a 76 65 72 73 69 6f 6e 73 20 6f 66  ving.versions of
2c060 20 61 20 70 72 6f 6a 65 63 74 20 61 73 20 61 20   a project as a 
2c070 64 69 72 65 63 74 65 64 20 61 63 79 63 6c 69 63  directed acyclic
2c080 20 67 72 61 70 68 20 28 44 41 47 29 2e 20 20 43   graph (DAG).  C
2c090 61 6c 6c 20 65 61 63 68 0a 76 65 72 73 69 6f 6e  all each.version
2c0a0 20 6f 66 20 74 68 65 20 70 72 6f 6a 65 63 74 20   of the project 
2c0b0 61 20 22 63 68 65 63 6b 69 6e 22 2e 20 20 41 20  a "checkin".  A 
2c0c0 73 69 6e 67 6c 65 0a 63 68 65 63 6b 69 6e 20 63  single.checkin c
2c0d0 61 6e 20 68 61 76 65 20 7a 65 72 6f 20 6f 72 20  an have zero or 
2c0e0 6d 6f 72 65 20 70 61 72 65 6e 74 73 2e 20 20 4d  more parents.  M
2c0f0 6f 73 74 20 63 68 65 63 6b 69 6e 73 20 28 65 78  ost checkins (ex
2c100 63 65 70 74 20 74 68 65 0a 66 69 72 73 74 29 20  cept the.first) 
2c110 68 61 76 65 20 61 20 73 69 6e 67 6c 65 20 70 61  have a single pa
2c120 72 65 6e 74 2c 20 62 75 74 20 69 6e 20 74 68 65  rent, but in the
2c130 20 63 61 73 65 20 6f 66 20 61 20 6d 65 72 67 65   case of a merge
2c140 2c 20 61 20 63 68 65 63 6b 69 6e 0a 6d 69 67 68  , a checkin.migh
2c150 74 20 68 61 76 65 20 74 77 6f 20 6f 72 20 74 68  t have two or th
2c160 72 65 65 20 6f 72 20 6d 6f 72 65 20 70 61 72 65  ree or more pare
2c170 6e 74 73 2e 20 20 41 20 73 63 68 65 6d 61 20 74  nts.  A schema t
2c180 6f 20 6b 65 65 70 20 74 72 61 63 6b 20 6f 66 0a  o keep track of.
2c190 63 68 65 63 6b 69 6e 73 20 61 6e 64 20 74 68 65  checkins and the
2c1a0 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 20   order in which 
2c1b0 74 68 65 79 20 6f 63 63 75 72 20 6d 69 67 68 74  they occur might
2c1c0 20 6c 6f 6f 6b 20 73 6f 6d 65 74 68 69 6e 67 20   look something 
2c1d0 6c 69 6b 65 0a 74 68 69 73 3a 0a 0a 3c 62 6c 6f  like.this:..<blo
2c1e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43 52  ckquote><pre>.CR
2c1f0 45 41 54 45 20 54 41 42 4c 45 20 63 68 65 63 6b  EATE TABLE check
2c200 69 6e 28 0a 20 20 69 64 20 49 4e 54 45 47 45 52  in(.  id INTEGER
2c210 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 0a 20 20   PRIMARY KEY,.  
2c220 6d 74 69 6d 65 20 49 4e 54 45 47 45 52 20 2d 2d  mtime INTEGER --
2c230 20 74 69 6d 65 73 74 61 6d 70 20 77 68 65 6e 20   timestamp when 
2c240 74 68 69 73 20 63 68 65 63 6b 69 6e 20 6f 63 63  this checkin occ
2c250 75 72 72 65 64 0a 29 3b 0a 43 52 45 41 54 45 20  urred.);.CREATE 
2c260 54 41 42 4c 45 20 64 65 72 69 76 65 64 66 72 6f  TABLE derivedfro
2c270 6d 28 0a 20 20 78 66 72 6f 6d 20 49 4e 54 45 47  m(.  xfrom INTEG
2c280 45 52 20 4e 4f 54 20 4e 55 4c 4c 20 52 45 46 45  ER NOT NULL REFE
2c290 52 45 4e 43 45 53 20 63 68 65 63 6b 69 6e 2c 20  RENCES checkin, 
2c2a0 2d 2d 20 70 61 72 65 6e 74 20 63 68 65 63 6b 69  -- parent checki
2c2b0 6e 0a 20 20 78 74 6f 20 49 4e 54 45 47 45 52 20  n.  xto INTEGER 
2c2c0 4e 4f 54 20 4e 55 4c 4c 20 52 45 46 45 52 45 4e  NOT NULL REFEREN
2c2d0 43 45 53 20 63 68 65 63 6b 69 6e 2c 20 20 20 2d  CES checkin,   -
2c2e0 2d 20 64 65 72 69 76 65 64 20 63 68 65 63 6b 69  - derived checki
2c2f0 6e 0a 20 20 50 52 49 4d 41 52 59 20 4b 45 59 28  n.  PRIMARY KEY(
2c300 78 66 72 6f 6d 2c 78 74 6f 29 0a 29 3b 0a 43 52  xfrom,xto).);.CR
2c310 45 41 54 45 20 49 4e 44 45 58 20 64 65 72 69 76  EATE INDEX deriv
2c320 65 64 66 72 6f 6d 5f 62 61 63 6b 20 4f 4e 20 64  edfrom_back ON d
2c330 65 72 69 76 65 64 66 72 6f 6d 28 78 74 6f 2c 78  erivedfrom(xto,x
2c340 66 72 6f 6d 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  from);.</pre></b
2c350 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
2c360 68 69 73 20 67 72 61 70 68 20 69 73 20 61 63 79  his graph is acy
2c370 63 6c 69 63 2e 20 20 41 6e 64 20 77 65 20 61 73  clic.  And we as
2c380 73 75 6d 65 20 74 68 61 74 20 74 68 65 20 6d 74  sume that the mt
2c390 69 6d 65 20 6f 66 20 65 76 65 72 79 0a 63 68 69  ime of every.chi
2c3a0 6c 64 20 63 68 65 63 6b 69 6e 20 69 73 20 6e 6f  ld checkin is no
2c3b0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 6d   less than the m
2c3c0 74 69 6d 65 20 6f 66 20 61 6c 6c 20 69 74 73 20  time of all its 
2c3d0 70 61 72 65 6e 74 73 2e 20 20 42 75 74 0a 75 6e  parents.  But.un
2c3e0 6c 69 6b 65 20 74 68 65 20 65 61 72 6c 69 65 72  like the earlier
2c3f0 20 65 78 61 6d 70 6c 65 73 2c 20 74 68 69 73 20   examples, this 
2c400 67 72 61 70 68 20 6d 69 67 68 74 20 68 61 76 65  graph might have
2c410 20 6d 75 6c 74 69 70 6c 65 20 70 61 74 68 73 20   multiple paths 
2c420 6f 66 0a 64 69 66 66 65 72 69 6e 67 20 6c 65 6e  of.differing len
2c430 67 74 68 73 20 62 65 74 77 65 65 6e 20 61 6e 79  gths between any
2c440 20 74 77 6f 20 63 68 65 63 6b 69 6e 73 2e 0a 0a   two checkins...
2c450 3c 70 3e 57 65 20 77 61 6e 74 20 74 6f 20 6b 6e  <p>We want to kn
2c460 6f 77 20 74 68 65 20 74 77 65 6e 74 79 20 6d 6f  ow the twenty mo
2c470 73 74 20 72 65 63 65 6e 74 20 61 6e 63 65 73 74  st recent ancest
2c480 6f 72 73 20 69 6e 20 74 69 6d 65 20 28 6f 75 74  ors in time (out
2c490 20 6f 66 0a 74 68 65 20 74 68 6f 75 73 61 6e 64   of.the thousand
2c4a0 73 20 61 6e 64 20 74 68 6f 75 73 61 6e 64 73 20  s and thousands 
2c4b0 6f 66 20 61 6e 63 65 73 74 6f 72 73 20 69 6e 20  of ancestors in 
2c4c0 74 68 65 20 77 68 6f 6c 65 20 44 41 47 29 20 66  the whole DAG) f
2c4d0 6f 72 0a 63 68 65 63 6b 69 6e 20 22 40 42 41 53  or.checkin "@BAS
2c4e0 45 4c 49 4e 45 22 2e 20 20 28 41 20 71 75 65 72  ELINE".  (A quer
2c4f0 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
2c500 73 20 69 73 20 75 73 65 64 0a 62 79 20 74 68 65  s is used.by the
2c510 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
2c520 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e  /www.fossil-scm.
2c530 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 3c 2f 61 3e  org/">Fossil</a>
2c540 20 56 43 53 20 74 6f 0a 73 68 6f 77 20 74 68 65   VCS to.show the
2c550 20 4e 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 61   N most recent a
2c560 6e 63 65 73 74 6f 72 73 20 6f 66 20 61 20 63 68  ncestors of a ch
2c570 65 63 6b 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  eck.  For exampl
2c580 65 3a 0a 3c 61 20 68 72 65 66 3d 22 68 74 74 70  e:.<a href="http
2c590 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
2c5a0 67 2f 73 72 63 2f 74 69 6d 65 6c 69 6e 65 3f 70  g/src/timeline?p
2c5b0 3d 74 72 75 6e 6b 26 6e 3d 33 30 22 3e 68 74 74  =trunk&n=30">htt
2c5c0 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f  p://www.sqlite.o
2c5d0 72 67 2f 73 72 63 2f 74 69 6d 65 6c 69 6e 65 3f  rg/src/timeline?
2c5e0 70 3d 74 72 75 6e 6b 26 6e 3d 33 30 3c 2f 61 3e  p=trunk&n=30</a>
2c5f0 2e 29 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .)..<blockquote>
2c600 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55 52  <pre>.WITH RECUR
2c610 53 49 56 45 0a 20 20 61 6e 63 65 73 74 6f 72 28  SIVE.  ancestor(
2c620 69 64 2c 6d 74 69 6d 65 29 20 41 53 20 28 0a 20  id,mtime) AS (. 
2c630 20 20 20 53 45 4c 45 43 54 20 69 64 2c 20 6d 74     SELECT id, mt
2c640 69 6d 65 20 46 52 4f 4d 20 63 68 65 63 6b 69 6e  ime FROM checkin
2c650 20 57 48 45 52 45 20 69 64 3d 40 42 41 53 45 4c   WHERE id=@BASEL
2c660 49 4e 45 0a 20 20 20 20 55 4e 49 4f 4e 0a 20 20  INE.    UNION.  
2c670 20 20 53 45 4c 45 43 54 20 64 65 72 69 76 65 64    SELECT derived
2c680 66 72 6f 6d 2e 78 66 72 6f 6d 2c 20 63 68 65 63  from.xfrom, chec
2c690 6b 69 6e 2e 6d 74 69 6d 65 0a 20 20 20 20 20 20  kin.mtime.      
2c6a0 46 52 4f 4d 20 61 6e 63 65 73 74 6f 72 2c 20 64  FROM ancestor, d
2c6b0 65 72 69 76 65 64 66 72 6f 6d 2c 20 63 68 65 63  erivedfrom, chec
2c6c0 6b 69 6e 0a 20 20 20 20 20 57 48 45 52 45 20 61  kin.     WHERE a
2c6d0 6e 63 65 73 74 6f 72 2e 69 64 3d 64 65 72 69 76  ncestor.id=deriv
2c6e0 65 64 66 72 6f 6d 2e 78 74 6f 0a 20 20 20 20 20  edfrom.xto.     
2c6f0 20 20 41 4e 44 20 63 68 65 63 6b 69 6e 2e 69 64    AND checkin.id
2c700 3d 64 65 72 69 76 65 64 66 72 6f 6d 2e 78 66 72  =derivedfrom.xfr
2c710 6f 6d 0a 20 20 20 20 20 4f 52 44 45 52 20 42 59  om.     ORDER BY
2c720 20 63 68 65 63 6b 69 6e 2e 6d 74 69 6d 65 20 44   checkin.mtime D
2c730 45 53 43 0a 20 20 20 20 20 4c 49 4d 49 54 20 32  ESC.     LIMIT 2
2c740 30 0a 20 20 29 0a 53 45 4c 45 43 54 20 2a 20 46  0.  ).SELECT * F
2c750 52 4f 4d 20 63 68 65 63 6b 69 6e 20 4a 4f 49 4e  ROM checkin JOIN
2c760 20 61 6e 63 65 73 74 6f 72 20 55 53 49 4e 47 28   ancestor USING(
2c770 69 64 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  id);.</pre></blo
2c780 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68  ckquote>..<p>.Th
2c790 65 20 22 4f 52 44 45 52 20 42 59 20 63 68 65 63  e "ORDER BY chec
2c7a0 6b 69 6e 2e 6d 74 69 6d 65 20 44 45 53 43 22 20  kin.mtime DESC" 
2c7b0 74 65 72 6d 20 69 6e 20 74 68 65 20 72 65 63 75  term in the recu
2c7c0 72 73 69 76 65 2d 73 65 6c 65 63 74 20 6d 61 6b  rsive-select mak
2c7d0 65 73 0a 74 68 65 20 71 75 65 72 79 20 72 75 6e  es.the query run
2c7e0 20 6d 75 63 68 20 66 61 73 74 65 72 20 62 79 20   much faster by 
2c7f0 70 72 65 76 65 6e 74 69 6e 67 20 69 74 20 66 72  preventing it fr
2c800 6f 6d 20 66 6f 6c 6c 6f 77 69 6e 67 0a 62 72 61  om following.bra
2c810 6e 63 68 65 73 20 74 68 61 74 20 6d 65 72 67 65  nches that merge
2c820 20 63 68 65 63 6b 69 6e 73 0a 66 72 6f 6d 20 6c   checkins.from l
2c830 6f 6e 67 20 61 67 6f 2e 20 20 54 68 65 20 4f 52  ong ago.  The OR
2c840 44 45 52 20 42 59 20 66 6f 72 63 65 73 20 74 68  DER BY forces th
2c850 65 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65  e recursive-sele
2c860 63 74 20 74 6f 20 66 6f 63 75 73 0a 6f 6e 20 74  ct to focus.on t
2c870 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2c880 68 65 63 6b 69 6e 73 2c 20 74 68 65 20 6f 6e 65  heckins, the one
2c890 73 20 77 65 20 77 61 6e 74 2e 20 20 57 69 74 68  s we want.  With
2c8a0 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
2c8b0 0a 6f 6e 20 74 68 65 20 72 65 63 75 72 73 69 76  .on the recursiv
2c8c0 65 2d 73 65 6c 65 63 74 2c 20 6f 6e 65 20 77 6f  e-select, one wo
2c8d0 75 6c 64 20 62 65 20 66 6f 72 63 65 64 20 74 6f  uld be forced to
2c8e0 20 63 6f 6d 70 75 74 65 20 74 68 65 20 63 6f 6d   compute the com
2c8f0 70 6c 65 74 65 20 73 65 74 20 6f 66 0a 74 68 6f  plete set of.tho
2c900 75 73 61 6e 64 73 20 6f 66 20 61 6e 63 65 73 74  usands of ancest
2c910 6f 72 73 2c 20 73 6f 72 74 20 74 68 65 6d 20 61  ors, sort them a
2c920 6c 6c 20 62 79 20 6d 74 69 6d 65 2c 20 74 68 65  ll by mtime, the
2c930 6e 20 74 61 6b 65 20 74 68 65 20 74 6f 70 20 74  n take the top t
2c940 77 65 6e 74 79 2e 0a 54 68 65 20 4f 52 44 45 52  wenty..The ORDER
2c950 20 42 59 20 65 73 73 65 6e 74 69 61 6c 6c 79 20   BY essentially 
2c960 73 65 74 73 20 75 70 20 61 20 70 72 69 6f 72 69  sets up a priori
2c970 74 79 20 71 75 65 75 65 20 74 68 61 74 0a 66 6f  ty queue that.fo
2c980 72 63 65 73 20 74 68 65 20 72 65 63 75 72 73 69  rces the recursi
2c990 76 65 20 71 75 65 72 79 20 74 6f 20 6c 6f 6f 6b  ve query to look
2c9a0 20 61 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63   at the most rec
2c9b0 65 6e 74 20 61 6e 63 65 73 74 6f 72 73 20 66 69  ent ancestors fi
2c9c0 72 73 74 2c 0a 61 6c 6c 6f 77 69 6e 67 20 74 68  rst,.allowing th
2c9d0 65 20 75 73 65 20 6f 66 20 61 20 4c 49 4d 49 54  e use of a LIMIT
2c9e0 20 63 6c 61 75 73 65 20 74 6f 20 72 65 73 74 72   clause to restr
2c9f0 69 63 74 20 74 68 65 20 73 63 6f 70 65 20 6f 66  ict the scope of
2ca00 20 74 68 65 0a 71 75 65 72 79 20 74 6f 20 6a 75   the.query to ju
2ca10 73 74 20 74 68 65 20 63 68 65 63 6b 69 6e 73 20  st the checkins 
2ca20 6f 66 20 69 6e 74 65 72 65 73 74 2e 0a 0a 3c 74  of interest...<t
2ca30 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 77  cl>hd_fragment w
2ca40 69 74 68 6f 72 64 65 72 62 79 3c 2f 74 63 6c 3e  ithorderby</tcl>
2ca50 0a 3c 68 34 3e 43 6f 6e 74 72 6f 6c 6c 69 6e 67  .<h4>Controlling
2ca60 20 44 65 70 74 68 2d 46 69 72 73 74 20 56 65 72   Depth-First Ver
2ca70 73 75 73 20 42 72 65 61 64 74 68 2d 46 69 72 73  sus Breadth-Firs
2ca80 74 20 53 65 61 72 63 68 20 4f 66 20 61 20 54 72  t Search Of a Tr
2ca90 65 65 0a 55 73 69 6e 67 20 4f 52 44 45 52 20 42  ee.Using ORDER B
2caa0 59 3c 2f 68 34 3e 0a 0a 3c 70 3e 41 6e 20 4f 52  Y</h4>..<p>An OR
2cab0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 6f 6e  DER BY clause on
2cac0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 2d 73   the recursive-s
2cad0 65 6c 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  elect can be use
2cae0 64 20 74 6f 20 63 6f 6e 74 72 6f 6c 0a 77 68 65  d to control.whe
2caf0 74 68 65 72 20 74 68 65 20 73 65 61 72 63 68 20  ther the search 
2cb00 6f 66 20 61 20 74 72 65 65 20 69 73 20 64 65 70  of a tree is dep
2cb10 74 68 2d 66 69 72 73 74 20 6f 72 20 62 72 65 61  th-first or brea
2cb20 64 74 68 2d 66 69 72 73 74 2e 20 20 54 6f 0a 69  dth-first.  To.i
2cb30 6c 6c 75 73 74 72 61 74 65 2c 20 77 65 20 77 69  llustrate, we wi
2cb40 6c 6c 20 75 73 65 20 61 20 76 61 72 69 61 74 69  ll use a variati
2cb50 6f 6e 20 6f 6e 20 74 68 65 20 22 6f 72 67 22 20  on on the "org" 
2cb60 74 61 62 6c 65 20 66 72 6f 6d 20 61 6e 20 65 78  table from an ex
2cb70 61 6d 70 6c 65 0a 61 62 6f 76 65 2c 20 77 69 74  ample.above, wit
2cb80 68 6f 75 74 20 74 68 65 20 22 68 65 69 67 68 74  hout the "height
2cb90 22 20 63 6f 6c 75 6d 6e 2c 20 61 6e 64 20 77 69  " column, and wi
2cba0 74 68 20 73 6f 6d 65 20 72 65 61 6c 20 64 61 74  th some real dat
2cbb0 61 20 69 6e 73 65 72 74 65 64 3a 0a 0a 3c 62 6c  a inserted:..<bl
2cbc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43  ockquote><pre>.C
2cbd0 52 45 41 54 45 20 54 41 42 4c 45 20 6f 72 67 28  REATE TABLE org(
2cbe0 0a 20 20 6e 61 6d 65 20 54 45 58 54 20 50 52 49  .  name TEXT PRI
2cbf0 4d 41 52 59 20 4b 45 59 2c 0a 20 20 62 6f 73 73  MARY KEY,.  boss
2cc00 20 54 45 58 54 20 52 45 46 45 52 45 4e 43 45 53   TEXT REFERENCES
2cc10 20 6f 72 67 0a 29 20 57 49 54 48 4f 55 54 20 52   org.) WITHOUT R
2cc20 4f 57 49 44 3b 0a 49 4e 53 45 52 54 20 49 4e 54  OWID;.INSERT INT
2cc30 4f 20 6f 72 67 20 56 41 4c 55 45 53 28 27 41 6c  O org VALUES('Al
2cc40 69 63 65 27 2c 4e 55 4c 4c 29 3b 0a 49 4e 53 45  ice',NULL);.INSE
2cc50 52 54 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c 55  RT INTO org VALU
2cc60 45 53 28 27 42 6f 62 27 2c 27 41 6c 69 63 65 27  ES('Bob','Alice'
2cc70 29 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f  );.INSERT INTO o
2cc80 72 67 20 56 41 4c 55 45 53 28 27 43 69 6e 64 79  rg VALUES('Cindy
2cc90 27 2c 27 41 6c 69 63 65 27 29 3b 0a 49 4e 53 45  ','Alice');.INSE
2cca0 52 54 20 49 4e 54 4f 20 6f 72 67 20 56 41 4c 55  RT INTO org VALU
2ccb0 45 53 28 27 44 61 76 65 27 2c 27 42 6f 62 27 29  ES('Dave','Bob')
2ccc0 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f 72  ;.INSERT INTO or
2ccd0 67 20 56 41 4c 55 45 53 28 27 45 6d 6d 61 27 2c  g VALUES('Emma',
2cce0 27 42 6f 62 27 29 3b 0a 49 4e 53 45 52 54 20 49  'Bob');.INSERT I
2ccf0 4e 54 4f 20 6f 72 67 20 56 41 4c 55 45 53 28 27  NTO org VALUES('
2cd00 46 72 65 64 27 2c 27 43 69 6e 64 79 27 29 3b 0a  Fred','Cindy');.
2cd10 49 4e 53 45 52 54 20 49 4e 54 4f 20 6f 72 67 20  INSERT INTO org 
2cd20 56 41 4c 55 45 53 28 27 47 61 69 6c 27 2c 27 43  VALUES('Gail','C
2cd30 69 6e 64 79 27 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  indy');.</pre></
2cd40 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
2cd50 48 65 72 65 20 69 73 20 61 20 71 75 65 72 79 20  Here is a query 
2cd60 74 6f 20 73 68 6f 77 20 74 68 65 20 74 72 65 65  to show the tree
2cd70 20 73 74 72 75 63 74 75 72 65 20 69 6e 20 61 20   structure in a 
2cd80 62 72 65 61 64 74 68 2d 66 69 72 73 74 20 70 61  breadth-first pa
2cd90 74 74 65 72 6e 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  ttern:..<blockqu
2cda0 6f 74 65 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52  ote><pre>.WITH R
2cdb0 45 43 55 52 53 49 56 45 0a 20 20 75 6e 64 65 72  ECURSIVE.  under
2cdc0 5f 61 6c 69 63 65 28 6e 61 6d 65 2c 6c 65 76 65  _alice(name,leve
2cdd0 6c 29 20 41 53 20 28 0a 20 20 20 20 56 41 4c 55  l) AS (.    VALU
2cde0 45 53 28 27 41 6c 69 63 65 27 2c 30 29 0a 20 20  ES('Alice',0).  
2cdf0 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20    UNION ALL.    
2ce00 53 45 4c 45 43 54 20 6f 72 67 2e 6e 61 6d 65 2c  SELECT org.name,
2ce10 20 75 6e 64 65 72 5f 61 6c 69 63 65 2e 6c 65 76   under_alice.lev
2ce20 65 6c 2b 31 0a 20 20 20 20 20 20 46 52 4f 4d 20  el+1.      FROM 
2ce30 6f 72 67 20 4a 4f 49 4e 20 75 6e 64 65 72 5f 61  org JOIN under_a
2ce40 6c 69 63 65 20 4f 4e 20 6f 72 67 2e 62 6f 73 73  lice ON org.boss
2ce50 3d 75 6e 64 65 72 5f 61 6c 69 63 65 2e 6e 61 6d  =under_alice.nam
2ce60 65 0a 20 20 20 20 20 4f 52 44 45 52 20 42 59 20  e.     ORDER BY 
2ce70 32 0a 20 20 29 0a 53 45 4c 45 43 54 20 73 75 62  2.  ).SELECT sub
2ce80 73 74 72 28 27 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 27  str('..........'
2ce90 2c 31 2c 6c 65 76 65 6c 2a 33 29 20 7c 7c 20 6e  ,1,level*3) || n
2cea0 61 6d 65 20 46 52 4f 4d 20 75 6e 64 65 72 5f 61  ame FROM under_a
2ceb0 6c 69 63 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  lice;.</pre></bl
2cec0 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
2ced0 65 20 22 4f 52 44 45 52 20 42 59 20 32 22 20 28  e "ORDER BY 2" (
2cee0 77 68 69 63 68 20 6d 65 61 6e 73 20 74 68 65 20  which means the 
2cef0 73 61 6d 65 20 61 73 20 22 4f 52 44 45 52 20 42  same as "ORDER B
2cf00 59 20 75 6e 64 65 72 5f 61 6c 69 63 65 2e 6c 65  Y under_alice.le
2cf10 76 65 6c 2b 31 22 29 0a 63 61 75 73 65 73 20 68  vel+1").causes h
2cf20 69 67 68 65 72 20 6c 65 76 65 6c 73 20 69 6e 20  igher levels in 
2cf30 74 68 65 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e  the organization
2cf40 20 63 68 61 72 74 20 28 77 69 74 68 20 73 6d 61   chart (with sma
2cf50 6c 6c 65 72 20 22 6c 65 76 65 6c 22 20 76 61 6c  ller "level" val
2cf60 75 65 73 29 0a 74 6f 20 62 65 20 70 72 6f 63 65  ues).to be proce
2cf70 73 73 65 64 20 66 69 72 73 74 2c 20 72 65 73 75  ssed first, resu
2cf80 6c 74 69 6e 67 20 69 6e 20 61 20 62 72 65 61 64  lting in a bread
2cf90 74 68 2d 66 69 72 73 74 20 73 65 61 72 63 68 2e  th-first search.
2cfa0 20 20 54 68 65 20 6f 75 74 70 75 74 20 69 73 3a    The output is:
2cfb0 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
2cfc0 72 65 3e 0a 41 6c 69 63 65 0a 2e 2e 2e 42 6f 62  re>.Alice....Bob
2cfd0 0a 2e 2e 2e 43 69 6e 64 79 0a 2e 2e 2e 2e 2e 2e  ....Cindy.......
2cfe0 44 61 76 65 0a 2e 2e 2e 2e 2e 2e 45 6d 6d 61 0a  Dave.......Emma.
2cff0 2e 2e 2e 2e 2e 2e 46 72 65 64 0a 2e 2e 2e 2e 2e  ......Fred......
2d000 2e 47 61 69 6c 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  .Gail.</pre></bl
2d010 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 42 75  ockquote>..<p>Bu
2d020 74 20 69 66 20 77 65 20 63 68 61 6e 67 65 20 74  t if we change t
2d030 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
2d040 73 65 20 74 6f 20 61 64 64 20 74 68 65 20 22 44  se to add the "D
2d050 45 53 43 22 20 6d 6f 64 69 66 69 65 72 2c 20 74  ESC" modifier, t
2d060 68 61 74 20 77 69 6c 6c 0a 63 61 75 73 65 20 6c  hat will.cause l
2d070 6f 77 65 72 20 6c 65 76 65 6c 73 20 69 6e 20 74  ower levels in t
2d080 68 65 20 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20  he organization 
2d090 28 77 69 74 68 20 6c 61 72 67 65 72 20 22 6c 65  (with larger "le
2d0a0 76 65 6c 22 20 76 61 6c 75 65 73 29 20 74 6f 20  vel" values) to 
2d0b0 62 65 0a 70 72 6f 63 65 73 73 65 64 20 66 69 72  be.processed fir
2d0c0 73 74 20 62 79 20 74 68 65 20 72 65 63 75 72 73  st by the recurs
2d0d0 69 76 65 2d 73 65 6c 65 63 74 2c 20 72 65 73 75  ive-select, resu
2d0e0 6c 74 69 6e 67 20 69 6e 20 61 20 64 65 70 74 68  lting in a depth
2d0f0 2d 66 69 72 73 74 20 73 65 61 72 63 68 3a 0a 0a  -first search:..
2d100 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2d110 3e 0a 57 49 54 48 20 52 45 43 55 52 53 49 56 45  >.WITH RECURSIVE
2d120 0a 20 20 75 6e 64 65 72 5f 61 6c 69 63 65 28 6e  .  under_alice(n
2d130 61 6d 65 2c 6c 65 76 65 6c 29 20 41 53 20 28 0a  ame,level) AS (.
2d140 20 20 20 20 56 41 4c 55 45 53 28 27 41 6c 69 63      VALUES('Alic
2d150 65 27 2c 30 29 0a 20 20 20 20 55 4e 49 4f 4e 20  e',0).    UNION 
2d160 41 4c 4c 0a 20 20 20 20 53 45 4c 45 43 54 20 6f  ALL.    SELECT o
2d170 72 67 2e 6e 61 6d 65 2c 20 75 6e 64 65 72 5f 61  rg.name, under_a
2d180 6c 69 63 65 2e 6c 65 76 65 6c 2b 31 0a 20 20 20  lice.level+1.   
2d190 20 20 20 46 52 4f 4d 20 6f 72 67 20 4a 4f 49 4e     FROM org JOIN
2d1a0 20 75 6e 64 65 72 5f 61 6c 69 63 65 20 4f 4e 20   under_alice ON 
2d1b0 6f 72 67 2e 62 6f 73 73 3d 75 6e 64 65 72 5f 61  org.boss=under_a
2d1c0 6c 69 63 65 2e 6e 61 6d 65 0a 20 20 20 20 20 4f  lice.name.     O
2d1d0 52 44 45 52 20 42 59 20 32 20 3c 62 3e 44 45 53  RDER BY 2 <b>DES
2d1e0 43 3c 2f 62 3e 0a 20 20 29 0a 53 45 4c 45 43 54  C</b>.  ).SELECT
2d1f0 20 73 75 62 73 74 72 28 27 2e 2e 2e 2e 2e 2e 2e   substr('.......
2d200 2e 2e 2e 27 2c 31 2c 6c 65 76 65 6c 2a 33 29 20  ...',1,level*3) 
2d210 7c 7c 20 6e 61 6d 65 20 46 52 4f 4d 20 75 6e 64  || name FROM und
2d220 65 72 5f 61 6c 69 63 65 3b 0a 3c 2f 70 72 65 3e  er_alice;.</pre>
2d230 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
2d240 70 3e 54 68 65 20 6f 75 74 70 75 74 20 6f 66 20  p>The output of 
2d250 74 68 69 73 20 72 65 76 69 73 65 64 20 71 75 65  this revised que
2d260 72 79 20 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  ry is:..<blockqu
2d270 6f 74 65 3e 3c 70 72 65 3e 0a 41 6c 69 63 65 0a  ote><pre>.Alice.
2d280 2e 2e 2e 42 6f 62 0a 2e 2e 2e 2e 2e 2e 44 61 76  ...Bob.......Dav
2d290 65 0a 2e 2e 2e 2e 2e 2e 45 6d 6d 61 0a 2e 2e 2e  e.......Emma....
2d2a0 43 69 6e 64 79 0a 2e 2e 2e 2e 2e 2e 46 72 65 64  Cindy.......Fred
2d2b0 0a 2e 2e 2e 2e 2e 2e 47 61 69 6c 0a 3c 2f 70 72  .......Gail.</pr
2d2c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2d2d0 0a 3c 70 3e 57 68 65 6e 20 74 68 65 20 4f 52 44  .<p>When the ORD
2d2e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
2d2f0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
2d300 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65 63   recursive-selec
2d310 74 2c 20 74 68 65 0a 71 75 65 75 65 20 62 65 68  t, the.queue beh
2d320 61 76 65 73 20 61 73 20 61 20 46 49 46 4f 2c 20  aves as a FIFO, 
2d330 77 68 69 63 68 20 72 65 73 75 6c 74 73 20 69 6e  which results in
2d340 20 61 20 62 72 65 61 64 74 68 2d 66 69 72 73 74   a breadth-first
2d350 20 73 65 61 72 63 68 2e 0a 0a 0a 3c 74 63 6c 3e   search....<tcl>
2d360 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d 61 6e 64  hd_fragment mand
2d370 65 6c 62 72 6f 74 20 7b 63 6f 6d 70 75 74 65 20  elbrot {compute 
2d380 74 68 65 20 4d 61 6e 64 65 6c 62 72 6f 74 20 73  the Mandelbrot s
2d390 65 74 7d 3c 2f 74 63 6c 3e 0a 3c 68 34 3e 4f 75  et}</tcl>.<h4>Ou
2d3a0 74 6c 61 6e 64 69 73 68 20 52 65 63 75 72 73 69  tlandish Recursi
2d3b0 76 65 20 51 75 65 72 79 20 45 78 61 6d 70 6c 65  ve Query Example
2d3c0 73 3c 2f 68 34 3e 0a 0a 3c 70 3e 54 68 65 20 66  s</h4>..<p>The f
2d3d0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 63  ollowing query c
2d3e0 6f 6d 70 75 74 65 73 20 61 6e 20 61 70 70 72 6f  omputes an appro
2d3f0 78 69 6d 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  ximation of the 
2d400 4d 61 6e 64 65 6c 62 72 6f 74 20 53 65 74 0a 61  Mandelbrot Set.a
2d410 6e 64 20 6f 75 74 70 75 74 73 20 74 68 65 20 72  nd outputs the r
2d420 65 73 75 6c 74 20 61 73 20 41 53 43 49 49 2d 61  esult as ASCII-a
2d430 72 74 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  rt:..<blockquote
2d440 3e 3c 70 72 65 3e 0a 57 49 54 48 20 52 45 43 55  ><pre>.WITH RECU
2d450 52 53 49 56 45 0a 20 20 78 61 78 69 73 28 78 29  RSIVE.  xaxis(x)
2d460 20 41 53 20 28 56 41 4c 55 45 53 28 2d 32 2e 30   AS (VALUES(-2.0
2d470 29 20 55 4e 49 4f 4e 20 41 4c 4c 20 53 45 4c 45  ) UNION ALL SELE
2d480 43 54 20 78 2b 30 2e 30 35 20 46 52 4f 4d 20 78  CT x+0.05 FROM x
2d490 61 78 69 73 20 57 48 45 52 45 20 78 26 6c 74 3b  axis WHERE x&lt;
2d4a0 31 2e 32 29 2c 0a 20 20 79 61 78 69 73 28 79 29  1.2),.  yaxis(y)
2d4b0 20 41 53 20 28 56 41 4c 55 45 53 28 2d 31 2e 30   AS (VALUES(-1.0
2d4c0 29 20 55 4e 49 4f 4e 20 41 4c 4c 20 53 45 4c 45  ) UNION ALL SELE
2d4d0 43 54 20 79 2b 30 2e 31 20 46 52 4f 4d 20 79 61  CT y+0.1 FROM ya
2d4e0 78 69 73 20 57 48 45 52 45 20 79 26 6c 74 3b 31  xis WHERE y&lt;1
2d4f0 2e 30 29 2c 0a 20 20 6d 28 69 74 65 72 2c 20 63  .0),.  m(iter, c
2d500 78 2c 20 63 79 2c 20 78 2c 20 79 29 20 41 53 20  x, cy, x, y) AS 
2d510 28 0a 20 20 20 20 53 45 4c 45 43 54 20 30 2c 20  (.    SELECT 0, 
2d520 78 2c 20 79 2c 20 30 2e 30 2c 20 30 2e 30 20 46  x, y, 0.0, 0.0 F
2d530 52 4f 4d 20 78 61 78 69 73 2c 20 79 61 78 69 73  ROM xaxis, yaxis
2d540 0a 20 20 20 20 55 4e 49 4f 4e 20 41 4c 4c 0a 20  .    UNION ALL. 
2d550 20 20 20 53 45 4c 45 43 54 20 69 74 65 72 2b 31     SELECT iter+1
2d560 2c 20 63 78 2c 20 63 79 2c 20 78 2a 78 2d 79 2a  , cx, cy, x*x-y*
2d570 79 20 2b 20 63 78 2c 20 32 2e 30 2a 78 2a 79 20  y + cx, 2.0*x*y 
2d580 2b 20 63 79 20 46 52 4f 4d 20 6d 20 0a 20 20 20  + cy FROM m .   
2d590 20 20 57 48 45 52 45 20 28 78 2a 78 20 2b 20 79    WHERE (x*x + y
2d5a0 2a 79 29 20 26 6c 74 3b 20 34 2e 30 20 41 4e 44  *y) &lt; 4.0 AND
2d5b0 20 69 74 65 72 26 6c 74 3b 32 38 0a 20 20 29 2c   iter&lt;28.  ),
2d5c0 0a 20 20 6d 32 28 69 74 65 72 2c 20 63 78 2c 20  .  m2(iter, cx, 
2d5d0 63 79 29 20 41 53 20 28 0a 20 20 20 20 53 45 4c  cy) AS (.    SEL
2d5e0 45 43 54 20 6d 61 78 28 69 74 65 72 29 2c 20 63  ECT max(iter), c
2d5f0 78 2c 20 63 79 20 46 52 4f 4d 20 6d 20 47 52 4f  x, cy FROM m GRO
2d600 55 50 20 42 59 20 63 78 2c 20 63 79 0a 20 20 29  UP BY cx, cy.  )
2d610 2c 0a 20 20 61 28 74 29 20 41 53 20 28 0a 20 20  ,.  a(t) AS (.  
2d620 20 20 53 45 4c 45 43 54 20 67 72 6f 75 70 5f 63    SELECT group_c
2d630 6f 6e 63 61 74 28 20 73 75 62 73 74 72 28 27 20  oncat( substr(' 
2d640 2e 2b 2a 23 27 2c 20 31 2b 6d 69 6e 28 69 74 65  .+*#', 1+min(ite
2d650 72 2f 37 2c 34 29 2c 20 31 29 2c 20 27 27 29 20  r/7,4), 1), '') 
2d660 0a 20 20 20 20 46 52 4f 4d 20 6d 32 20 47 52 4f  .    FROM m2 GRO
2d670 55 50 20 42 59 20 63 79 0a 20 20 29 0a 53 45 4c  UP BY cy.  ).SEL
2d680 45 43 54 20 67 72 6f 75 70 5f 63 6f 6e 63 61 74  ECT group_concat
2d690 28 72 74 72 69 6d 28 74 29 2c 78 27 30 61 27 29  (rtrim(t),x'0a')
2d6a0 20 46 52 4f 4d 20 61 3b 0a 3c 2f 70 72 65 3e 3c   FROM a;.</pre><
2d6b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
2d6c0 3e 49 6e 20 74 68 69 73 20 71 75 65 72 79 2c 20  >In this query, 
2d6d0 74 68 65 20 22 78 61 78 69 73 22 20 61 6e 64 20  the "xaxis" and 
2d6e0 22 79 61 78 69 73 22 20 43 54 45 73 20 64 65 66  "yaxis" CTEs def
2d6f0 69 6e 65 20 74 68 65 20 67 72 69 64 20 6f 66 20  ine the grid of 
2d700 70 6f 69 6e 74 73 20 66 6f 72 0a 77 68 69 63 68  points for.which
2d710 20 74 68 65 20 4d 61 6e 64 65 6c 62 72 6f 74 20   the Mandelbrot 
2d720 53 65 74 20 77 69 6c 6c 20 62 65 20 61 70 70 72  Set will be appr
2d730 6f 78 69 6d 61 74 65 64 2e 20 20 45 61 63 68 20  oximated.  Each 
2d740 72 6f 77 20 69 6e 20 74 68 65 0a 22 6d 28 69 74  row in the."m(it
2d750 65 72 2c 63 78 2c 63 79 2c 78 2c 79 29 22 20 43  er,cx,cy,x,y)" C
2d760 54 45 20 6d 65 61 6e 73 20 74 68 61 74 20 61 66  TE means that af
2d770 74 65 72 20 22 69 74 65 72 22 20 69 74 65 72 61  ter "iter" itera
2d780 74 69 6f 6e 73 2c 20 74 68 65 20 4d 61 6e 64 65  tions, the Mande
2d790 6c 62 72 6f 74 0a 69 74 65 72 61 74 69 6f 6e 20  lbrot.iteration 
2d7a0 73 74 61 72 74 69 6e 67 20 61 74 20 63 78 2c 63  starting at cx,c
2d7b0 79 20 68 61 73 20 72 65 61 63 68 65 64 20 70 6f  y has reached po
2d7c0 69 6e 74 20 78 2c 79 2e 20 20 54 68 65 20 6e 75  int x,y.  The nu
2d7d0 6d 62 65 72 20 6f 66 20 69 74 65 72 61 74 69 6f  mber of iteratio
2d7e0 6e 73 0a 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ns.in this examp
2d7f0 6c 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  le is limited to
2d800 20 32 38 20 28 77 68 69 63 68 20 73 65 76 65 72   28 (which sever
2d810 65 6c 79 20 6c 69 6d 69 74 73 20 74 68 65 20 72  ely limits the r
2d820 65 73 6f 6c 75 74 69 6f 6e 20 6f 66 0a 74 68 65  esolution of.the
2d830 20 63 6f 6d 70 75 74 61 74 69 6f 6e 2c 20 62 75   computation, bu
2d840 74 20 69 73 20 73 75 66 66 69 63 69 65 6e 74 20  t is sufficient 
2d850 66 6f 72 20 6c 6f 77 2d 72 65 73 6f 6c 75 74 69  for low-resoluti
2d860 6f 6e 20 41 53 43 49 49 2d 61 72 74 20 6f 75 74  on ASCII-art out
2d870 70 75 74 29 2e 0a 54 68 65 20 22 6d 32 28 69 74  put)..The "m2(it
2d880 65 72 2c 63 78 2c 63 79 29 22 20 43 54 45 20 68  er,cx,cy)" CTE h
2d890 6f 6c 64 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  olds the maximum
2d8a0 20 6e 75 6d 62 65 72 20 6f 66 20 69 74 65 72 61   number of itera
2d8b0 74 69 6f 6e 73 20 72 65 61 63 68 65 64 20 77 68  tions reached wh
2d8c0 65 6e 0a 73 74 61 72 74 69 6e 67 20 61 74 20 70  en.starting at p
2d8d0 6f 69 6e 74 20 63 78 2c 63 79 2e 0a 46 69 6e 61  oint cx,cy..Fina
2d8e0 6c 6c 79 2c 20 65 61 63 68 20 72 6f 77 20 69 6e  lly, each row in
2d8f0 20 74 68 65 20 22 61 28 74 29 22 20 43 54 45 20   the "a(t)" CTE 
2d900 68 6f 6c 64 73 20 61 20 73 74 72 69 6e 67 20 0a  holds a string .
2d910 77 68 69 63 68 20 69 73 20 61 20 73 69 6e 67 6c  which is a singl
2d920 65 20 6c 69 6e 65 20 6f 66 20 74 68 65 20 6f 75  e line of the ou
2d930 74 70 75 74 20 41 53 43 49 49 2d 61 72 74 2e 0a  tput ASCII-art..
2d940 54 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  The SELECT state
2d950 6d 65 6e 74 20 61 74 20 74 68 65 20 65 6e 64 20  ment at the end 
2d960 6a 75 73 74 20 71 75 65 72 69 65 73 20 74 68 65  just queries the
2d970 20 22 61 22 20 43 54 45 20 74 6f 0a 72 65 74 72   "a" CTE to.retr
2d980 69 65 76 65 20 61 6c 6c 20 6c 69 6e 65 73 20 6f  ieve all lines o
2d990 66 20 41 53 43 49 49 2d 61 72 74 2c 20 6f 6e 65  f ASCII-art, one
2d9a0 20 62 79 20 6f 6e 65 2e 0a 0a 3c 70 3e 52 75 6e   by one...<p>Run
2d9b0 6e 69 6e 67 20 74 68 65 20 71 75 65 72 79 20 61  ning the query a
2d9c0 62 6f 76 65 20 69 6e 20 61 6e 20 53 51 4c 69 74  bove in an SQLit
2d9d0 65 20 5b 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  e [command-line 
2d9e0 73 68 65 6c 6c 5d 20 72 65 73 75 6c 74 73 0a 69  shell] results.i
2d9f0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2da00 6f 75 74 70 75 74 3a 0a 0a 3c 62 6c 6f 63 6b 71  output:..<blockq
2da10 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 20 20  uote><pre>.     
2da20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e                 .
2da40 2e 2e 2e 23 0a 20 20 20 20 20 20 20 20 20 20 20  ...#.           
2da50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da60 20 20 20 20 20 20 20 20 2e 2e 23 2a 2e 2e 0a 20          ..#*... 
2da70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da90 2e 2e 2b 23 23 23 23 2b 2e 0a 20 20 20 20 20 20  ..+####+..      
2daa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dab0 20 20 20 20 20 20 2e 2e 2e 2e 2e 2e 2e 2b 23 23        .......+##
2dac0 23 23 2e 2e 2e 2e 20 20 20 2b 0a 20 20 20 20 20  ##....   +.     
2dad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dae0 20 20 20 20 20 20 2e 2e 23 23 2b 2a 23 23 23 23        ..##+*####
2daf0 23 23 23 23 23 23 2b 2e 2b 2b 2b 2b 0a 20 20 20  ######+.++++.   
2db00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2db10 20 20 20 20 20 20 20 2e 2b 2e 23 23 23 23 23 23         .+.######
2db20 23 23 23 23 23 23 23 23 23 23 23 23 2b 2e 0a 20  ############+.. 
2db30 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e               ...
2db40 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2b 23 23 23 23 23  ..........+#####
2db50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 2b 2e  ##############+.
2db60 2b 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  +.              
2db70 2e 2e 2b 2b 2e 2e 23 2e 2e 2e 2e 2e 2a 23 23 23  ..++..#.....*###
2db80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2db90 23 23 2b 2e 0a 20 20 20 20 20 20 20 20 20 20 20  ##+..           
2dba0 20 20 2e 2e 2e 2b 23 23 23 23 23 23 23 2b 2b 23    ...+#######++#
2dbb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dbc0 23 23 23 23 23 23 2e 0a 20 20 20 20 20 20 20 20  ######..        
2dbd0 20 20 2e 2e 2e 2e 2b 2a 23 23 23 23 23 23 23 23    ....+*########
2dbe0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dbf0 23 23 23 23 23 23 23 23 2e 0a 20 23 23 23 23 23  ########.. #####
2dc00 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dc10 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dc20 23 23 23 23 23 23 23 23 2e 2e 2e 0a 20 20 20 20  ########....    
2dc30 20 20 20 20 20 20 2e 2e 2e 2e 2b 2a 23 23 23 23        ....+*####
2dc40 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dc50 23 23 23 23 23 23 23 23 23 23 23 23 2e 0a 20 20  ############..  
2dc60 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2e 2b 23             ...+#
2dc70 23 23 23 23 23 23 2b 2b 23 23 23 23 23 23 23 23  ######++########
2dc80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 2e  ###############.
2dc90 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2e  .              .
2dca0 2e 2b 2b 2e 2e 23 2e 2e 2e 2e 2e 2a 23 23 23 23  .++..#.....*####
2dcb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dcc0 23 2b 2e 0a 20 20 20 20 20 20 20 20 20 20 20 20  #+..            
2dcd0 20 20 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2e 2b    .............+
2dce0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2dcf0 23 23 23 2b 2e 2b 0a 20 20 20 20 20 20 20 20 20  ###+.+.         
2dd00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd10 20 2e 2b 2e 23 23 23 23 23 23 23 23 23 23 23 23   .+.############
2dd20 23 23 23 23 23 23 2b 2e 0a 20 20 20 20 20 20 20  ######+..       
2dd30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd40 20 20 20 20 2e 2e 23 23 2b 2a 23 23 23 23 23 23      ..##+*######
2dd50 23 23 23 23 2b 2e 2b 2b 2b 2b 0a 20 20 20 20 20  ####+.++++.     
2dd60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd70 20 20 20 20 20 20 20 2e 2e 2e 2e 2e 2e 2e 2b 23         .......+#
2dd80 23 23 23 2e 2e 2e 2e 20 20 20 2b 0a 20 20 20 20  ###....   +.    
2dd90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dda0 20 20 20 20 20 20 20 20 20 20 20 20 20 2e 2e 2b               ..+
2ddb0 23 23 23 23 2b 2e 0a 20 20 20 20 20 20 20 20 20  ####+..         
2ddc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ddd0 20 20 20 20 20 20 20 20 20 20 2e 2e 23 2a 2e 2e            ..#*..
2dde0 0a 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 20 2e 2e 2e 2e 23 0a 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 20 20 2b                 +
2de30 2e 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ..</pre></blockq
2de40 75 6f 74 65 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  uote>..<tcl>hd_f
2de50 72 61 67 6d 65 6e 74 20 73 75 64 6f 6b 75 20 7b  ragment sudoku {
2de60 73 6f 6c 76 65 20 53 75 64 6f 6b 75 20 70 75 7a  solve Sudoku puz
2de70 7a 6c 65 73 7d 20 3c 2f 74 63 6c 3e 0a 3c 70 3e  zles} </tcl>.<p>
2de80 54 68 69 73 20 6e 65 78 74 20 71 75 65 72 79 20  This next query 
2de90 73 6f 6c 76 65 73 20 61 20 53 75 64 6f 6b 75 20  solves a Sudoku 
2dea0 70 75 7a 7a 6c 65 2e 20 20 54 68 65 20 73 74 61  puzzle.  The sta
2deb0 74 65 20 6f 66 20 74 68 65 20 70 75 7a 7a 6c 65  te of the puzzle
2dec0 20 69 73 0a 64 65 66 69 6e 65 64 20 62 79 20 61   is.defined by a
2ded0 6e 20 38 31 2d 63 68 61 72 61 63 74 65 72 20 73  n 81-character s
2dee0 74 72 69 6e 67 20 66 6f 72 6d 65 64 20 62 79 20  tring formed by 
2def0 72 65 61 64 69 6e 67 20 65 6e 74 72 69 65 73 20  reading entries 
2df00 66 72 6f 6d 20 74 68 65 0a 70 75 7a 7a 6c 65 20  from the.puzzle 
2df10 62 6f 78 20 72 6f 77 20 62 79 20 72 6f 77 20 66  box row by row f
2df20 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68  rom left to righ
2df30 74 20 61 6e 64 20 74 68 65 6e 20 66 72 6f 6d 20  t and then from 
2df40 74 6f 70 20 74 6f 20 62 6f 74 74 6f 6d 2e 0a 42  top to bottom..B
2df50 6c 61 6e 6b 20 73 71 75 61 72 65 73 20 69 6e 20  lank squares in 
2df60 74 68 65 20 70 75 7a 7a 6c 65 20 61 72 65 20 64  the puzzle are d
2df70 65 6e 6f 74 65 64 20 62 79 20 61 20 22 2e 22 20  enoted by a "." 
2df80 63 68 61 72 61 63 74 65 72 2e 20 20 0a 54 68 75  character.  .Thu
2df90 73 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  s the input stri
2dfa0 6e 67 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  ng:..<blockquote
2dfb0 3e 0a 35 33 2e 2e 37 2e 2e 2e 2e 36 2e 2e 31 39  >.53..7....6..19
2dfc0 35 2e 2e 2e 2e 39 38 2e 2e 2e 2e 36 2e 38 2e 2e  5....98....6.8..
2dfd0 2e 36 2e 2e 2e 33 34 2e 2e 38 2e 33 2e 2e 31 37  .6...34..8.3..17
2dfe0 2e 2e 2e 32 2e 2e 2e 36 2e 36 2e 2e 2e 2e 32 38  ...2...6.6....28
2dff0 2e 2e 2e 2e 34 31 39 2e 2e 35 2e 2e 2e 2e 38 2e  ....419..5....8.
2e000 2e 37 39 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .79.</blockquote
2e010 3e 0a 0a 3c 70 3e 43 6f 72 72 65 73 70 6f 6e 64  >..<p>Correspond
2e020 73 20 74 6f 20 61 20 70 75 7a 7a 6c 65 20 6c 69  s to a puzzle li
2e030 6b 65 20 74 68 69 73 3a 0a 0a 3c 62 6c 6f 63 6b  ke this:..<block
2e040 71 75 6f 74 65 3e 0a 3c 74 61 62 6c 65 20 62 6f  quote>.<table bo
2e050 72 64 65 72 3d 22 31 22 20 63 65 6c 6c 70 61 64  rder="1" cellpad
2e060 64 69 6e 67 3d 22 35 22 3e 0a 3c 74 72 3e 3c 74  ding="5">.<tr><t
2e070 64 3e 35 3c 74 64 3e 33 3c 74 64 3e 20 3c 74 64  d>5<td>3<td> <td
2e080 3e 20 3c 74 64 3e 37 3c 74 64 3e 20 3c 74 64 3e  > <td>7<td> <td>
2e090 20 3c 74 64 3e 20 3c 74 64 3e 0a 3c 74 72 3e 3c   <td> <td>.<tr><
2e0a0 74 64 3e 36 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td>6<td> <td> <t
2e0b0 64 3e 31 3c 74 64 3e 39 3c 74 64 3e 35 3c 74 64  d>1<td>9<td>5<td
2e0c0 3e 20 3c 74 64 3e 20 3c 74 64 3e 0a 3c 74 72 3e  > <td> <td>.<tr>
2e0d0 3c 74 64 3e 20 3c 74 64 3e 39 3c 74 64 3e 38 3c  <td> <td>9<td>8<
2e0e0 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
2e0f0 64 3e 20 3c 74 64 3e 36 3c 74 64 3e 0a 3c 74 72  d> <td>6<td>.<tr
2e100 3e 3c 74 64 3e 38 3c 74 64 3e 20 3c 74 64 3e 20  ><td>8<td> <td> 
2e110 3c 74 64 3e 20 3c 74 64 3e 36 3c 74 64 3e 20 3c  <td> <td>6<td> <
2e120 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 33 0a 3c  td> <td> <td>3.<
2e130 74 72 3e 3c 74 64 3e 34 3c 74 64 3e 20 3c 74 64  tr><td>4<td> <td
2e140 3e 20 3c 74 64 3e 38 3c 74 64 3e 20 3c 74 64 3e  > <td>8<td> <td>
2e150 33 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 31  3<td> <td> <td>1
2e160 0a 3c 74 72 3e 3c 74 64 3e 37 3c 74 64 3e 20 3c  .<tr><td>7<td> <
2e170 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 32 3c 74  td> <td> <td>2<t
2e180 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64  d> <td> <td> <td
2e190 3e 36 0a 3c 74 72 3e 3c 74 64 3e 20 3c 74 64 3e  >6.<tr><td> <td>
2e1a0 36 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20  6<td> <td> <td> 
2e1b0 3c 74 64 3e 20 3c 74 64 3e 32 3c 74 64 3e 38 3c  <td> <td>2<td>8<
2e1c0 74 64 3e 0a 3c 74 72 3e 3c 74 64 3e 20 3c 74 64  td>.<tr><td> <td
2e1d0 3e 20 3c 74 64 3e 20 3c 74 64 3e 34 3c 74 64 3e  > <td> <td>4<td>
2e1e0 31 3c 74 64 3e 39 3c 74 64 3e 20 3c 74 64 3e 20  1<td>9<td> <td> 
2e1f0 3c 74 64 3e 35 0a 3c 74 72 3e 3c 74 64 3e 20 3c  <td>5.<tr><td> <
2e200 74 64 3e 20 3c 74 64 3e 20 3c 74 64 3e 20 3c 74  td> <td> <td> <t
2e210 64 3e 38 3c 74 64 3e 20 3c 74 64 3e 20 3c 74 64  d>8<td> <td> <td
2e220 3e 37 3c 74 64 3e 39 0a 3c 2f 74 61 62 6c 65 3e  >7<td>9.</table>
2e230 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  .</blockquote>..
2e240 3c 70 3e 54 68 69 73 20 69 73 20 74 68 65 20 71  <p>This is the q
2e250 75 65 72 79 20 74 68 61 74 20 73 6f 6c 76 65 73  uery that solves
2e260 20 74 68 65 20 70 75 7a 7a 6c 65 3a 0a 0a 3c 62   the puzzle:..<b
2e270 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2e280 57 49 54 48 20 52 45 43 55 52 53 49 56 45 0a 20  WITH RECURSIVE. 
2e290 20 69 6e 70 75 74 28 73 75 64 29 20 41 53 20 28   input(sud) AS (
2e2a0 0a 20 20 20 20 56 41 4c 55 45 53 28 27 35 33 2e  .    VALUES('53.
2e2b0 2e 37 2e 2e 2e 2e 36 2e 2e 31 39 35 2e 2e 2e 2e  .7....6..195....
2e2c0 39 38 2e 2e 2e 2e 36 2e 38 2e 2e 2e 36 2e 2e 2e  98....6.8...6...
2e2d0 33 34 2e 2e 38 2e 33 2e 2e 31 37 2e 2e 2e 32 2e  34..8.3..17...2.
2e2e0 2e 2e 36 2e 36 2e 2e 2e 2e 32 38 2e 2e 2e 2e 34  ..6.6....28....4
2e2f0 31 39 2e 2e 35 2e 2e 2e 2e 38 2e 2e 37 39 27 29  19..5....8..79')
2e300 0a 20 20 29 2c 0a 20 20 64 69 67 69 74 73 28 7a  .  ),.  digits(z
2e310 2c 20 6c 70 29 20 41 53 20 28 0a 20 20 20 20 56  , lp) AS (.    V
2e320 41 4c 55 45 53 28 27 31 27 2c 20 31 29 0a 20 20  ALUES('1', 1).  
2e330 20 20 55 4e 49 4f 4e 20 41 4c 4c 20 53 45 4c 45    UNION ALL SELE
2e340 43 54 0a 20 20 20 20 43 41 53 54 28 6c 70 2b 31  CT.    CAST(lp+1
2e350 20 41 53 20 54 45 58 54 29 2c 20 6c 70 2b 31 20   AS TEXT), lp+1 
2e360 46 52 4f 4d 20 64 69 67 69 74 73 20 57 48 45 52  FROM digits WHER
2e370 45 20 6c 70 26 6c 74 3b 39 0a 20 20 29 2c 0a 20  E lp&lt;9.  ),. 
2e380 20 78 28 73 2c 20 69 6e 64 29 20 41 53 20 28 0a   x(s, ind) AS (.
2e390 20 20 20 20 53 45 4c 45 43 54 20 73 75 64 2c 20      SELECT sud, 
2e3a0 69 6e 73 74 72 28 73 75 64 2c 20 27 2e 27 29 20  instr(sud, '.') 
2e3b0 46 52 4f 4d 20 69 6e 70 75 74 0a 20 20 20 20 55  FROM input.    U
2e3c0 4e 49 4f 4e 20 41 4c 4c 0a 20 20 20 20 53 45 4c  NION ALL.    SEL
2e3d0 45 43 54 0a 20 20 20 20 20 20 73 75 62 73 74 72  ECT.      substr
2e3e0 28 73 2c 20 31 2c 20 69 6e 64 2d 31 29 20 7c 7c  (s, 1, ind-1) ||
2e3f0 20 7a 20 7c 7c 20 73 75 62 73 74 72 28 73 2c 20   z || substr(s, 
2e400 69 6e 64 2b 31 29 2c 0a 20 20 20 20 20 20 69 6e  ind+1),.      in
2e410 73 74 72 28 20 73 75 62 73 74 72 28 73 2c 20 31  str( substr(s, 1
2e420 2c 20 69 6e 64 2d 31 29 20 7c 7c 20 7a 20 7c 7c  , ind-1) || z ||
2e430 20 73 75 62 73 74 72 28 73 2c 20 69 6e 64 2b 31   substr(s, ind+1
2e440 29 2c 20 27 2e 27 20 29 0a 20 20 20 20 20 46 52  ), '.' ).     FR
2e450 4f 4d 20 78 2c 20 64 69 67 69 74 73 20 41 53 20  OM x, digits AS 
2e460 7a 0a 20 20 20 20 57 48 45 52 45 20 69 6e 64 3e  z.    WHERE ind>
2e470 30 0a 20 20 20 20 20 20 41 4e 44 20 4e 4f 54 20  0.      AND NOT 
2e480 45 58 49 53 54 53 20 28 0a 20 20 20 20 20 20 20  EXISTS (.       
2e490 20 20 20 20 20 53 45 4c 45 43 54 20 31 0a 20 20       SELECT 1.  
2e4a0 20 20 20 20 20 20 20 20 20 20 20 20 46 52 4f 4d              FROM
2e4b0 20 64 69 67 69 74 73 20 41 53 20 6c 70 0a 20 20   digits AS lp.  
2e4c0 20 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45             WHERE
2e4d0 20 7a 2e 7a 20 3d 20 73 75 62 73 74 72 28 73 2c   z.z = substr(s,
2e4e0 20 28 28 69 6e 64 2d 31 29 2f 39 29 2a 39 20 2b   ((ind-1)/9)*9 +
2e4f0 20 6c 70 2c 20 31 29 0a 20 20 20 20 20 20 20 20   lp, 1).        
2e500 20 20 20 20 20 20 20 20 4f 52 20 7a 2e 7a 20 3d          OR z.z =
2e510 20 73 75 62 73 74 72 28 73 2c 20 28 28 69 6e 64   substr(s, ((ind
2e520 2d 31 29 25 39 29 20 2b 20 28 6c 70 2d 31 29 2a  -1)%9) + (lp-1)*
2e530 39 20 2b 20 31 2c 20 31 29 0a 20 20 20 20 20 20  9 + 1, 1).      
2e540 20 20 20 20 20 20 20 20 20 20 4f 52 20 7a 2e 7a            OR z.z
2e550 20 3d 20 73 75 62 73 74 72 28 73 2c 20 28 28 28   = substr(s, (((
2e560 69 6e 64 2d 31 29 2f 33 29 20 25 20 33 29 20 2a  ind-1)/3) % 3) *
2e570 20 33 0a 20 20 20 20 20 20 20 20 20 20 20 20 20   3.             
2e580 20 20 20 20 20 20 20 20 20 20 20 2b 20 28 28 69             + ((i
2e590 6e 64 2d 31 29 2f 32 37 29 20 2a 20 32 37 20 2b  nd-1)/27) * 27 +
2e5a0 20 6c 70 0a 20 20 20 20 20 20 20 20 20 20 20 20   lp.            
2e5b0 20 20 20 20 20 20 20 20 20 20 20 20 2b 20 28 28              + ((
2e5c0 6c 70 2d 31 29 20 2f 20 33 29 20 2a 20 36 2c 20  lp-1) / 3) * 6, 
2e5d0 31 29 0a 20 20 20 20 20 20 20 20 20 29 0a 20 20  1).         ).  
2e5e0 29 0a 53 45 4c 45 43 54 20 73 20 46 52 4f 4d 20  ).SELECT s FROM 
2e5f0 78 20 57 48 45 52 45 20 69 6e 64 3d 30 3b 0a 3c  x WHERE ind=0;.<
2e600 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2e610 65 3e 0a 0a 3c 70 3e 54 68 65 20 22 69 6e 70 75  e>..<p>The "inpu
2e620 74 22 20 43 54 45 20 64 65 66 69 6e 65 73 20 74  t" CTE defines t
2e630 68 65 20 69 6e 70 75 74 20 70 75 7a 7a 6c 65 2e  he input puzzle.
2e640 0a 54 68 65 20 22 64 69 67 69 74 73 22 20 43 54  .The "digits" CT
2e650 45 20 64 65 66 69 6e 65 73 20 61 20 74 61 62 6c  E defines a tabl
2e660 65 20 74 68 61 74 20 68 6f 6c 64 73 20 61 6c 6c  e that holds all
2e670 20 64 69 67 69 74 73 20 62 65 74 77 65 65 6e 20   digits between 
2e680 31 20 61 6e 64 20 39 2e 0a 54 68 65 20 77 6f 72  1 and 9..The wor
2e690 6b 20 6f 66 20 73 6f 6c 76 69 6e 67 20 74 68 65  k of solving the
2e6a0 20 70 75 7a 7a 6c 65 20 69 73 20 75 6e 64 65 72   puzzle is under
2e6b0 74 61 6b 65 6e 20 62 79 20 74 68 65 20 22 78 22  taken by the "x"
2e6c0 20 43 54 45 2e 0a 41 6e 20 65 6e 74 72 79 20 69   CTE..An entry i
2e6d0 6e 20 78 28 73 2c 69 6e 64 29 20 6d 65 61 6e 73  n x(s,ind) means
2e6e0 20 74 68 61 74 20 74 68 65 20 38 31 2d 63 68 61   that the 81-cha
2e6f0 72 61 63 74 65 72 20 73 74 72 69 6e 67 20 22 73  racter string "s
2e700 22 20 69 73 20 61 20 76 61 6c 69 64 0a 73 75 64  " is a valid.sud
2e710 6f 6b 75 20 70 75 7a 7a 6c 65 20 28 69 74 20 68  oku puzzle (it h
2e720 61 73 20 6e 6f 20 63 6f 6e 66 6c 69 63 74 73 29  as no conflicts)
2e730 20 61 6e 64 20 74 68 61 74 20 74 68 65 20 66 69   and that the fi
2e740 72 73 74 20 75 6e 6b 6e 6f 77 6e 20 63 68 61 72  rst unknown char
2e750 61 63 74 65 72 0a 69 73 20 61 74 20 70 6f 73 69  acter.is at posi
2e760 74 69 6f 6e 20 22 69 6e 64 22 2c 20 6f 72 20 69  tion "ind", or i
2e770 6e 64 3d 3d 30 20 69 66 20 61 6c 6c 20 63 68 61  nd==0 if all cha
2e780 72 61 63 74 65 72 20 70 6f 73 69 74 69 6f 6e 73  racter positions
2e790 20 61 72 65 20 66 69 6c 6c 65 64 20 69 6e 2e 0a   are filled in..
2e7a0 54 68 65 20 67 6f 61 6c 2c 20 74 68 65 6e 2c 20  The goal, then, 
2e7b0 69 73 20 74 6f 20 63 6f 6d 70 75 74 65 20 65 6e  is to compute en
2e7c0 74 72 69 65 73 20 66 6f 72 20 22 78 22 20 77 69  tries for "x" wi
2e7d0 74 68 20 61 6e 20 22 69 6e 64 22 20 6f 66 20 30  th an "ind" of 0
2e7e0 2e 0a 0a 3c 70 3e 54 68 65 20 73 6f 6c 76 65 72  ...<p>The solver
2e7f0 20 77 6f 72 6b 73 20 62 79 20 61 64 64 69 6e 67   works by adding
2e800 20 6e 65 77 20 65 6e 74 72 69 65 73 20 74 6f 20   new entries to 
2e810 74 68 65 20 22 78 22 20 72 65 63 75 72 73 69 76  the "x" recursiv
2e820 65 20 74 61 62 6c 65 2e 0a 47 69 76 65 6e 20 70  e table..Given p
2e830 72 69 6f 72 20 65 6e 74 72 69 65 73 2c 20 74 68  rior entries, th
2e840 65 20 72 65 63 75 72 73 69 76 65 2d 73 65 6c 65  e recursive-sele
2e850 63 74 20 74 72 69 65 73 20 74 6f 20 66 69 6c 6c  ct tries to fill
2e860 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 6e 65 77   in a single new
2e870 0a 70 6f 73 69 74 69 6f 6e 20 77 69 74 68 20 61  .position with a
2e880 6c 6c 20 76 61 6c 75 65 73 20 62 65 74 77 65 65  ll values betwee
2e890 6e 20 31 20 61 6e 64 20 39 20 74 68 61 74 20 61  n 1 and 9 that a
2e8a0 63 74 75 61 6c 6c 79 20 77 6f 72 6b 20 69 6e 20  ctually work in 
2e8b0 74 68 61 74 0a 70 6f 73 69 74 69 6f 6e 2e 20 20  that.position.  
2e8c0 54 68 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  The complicated 
2e8d0 22 4e 4f 54 20 45 58 49 53 54 53 22 20 73 75 62  "NOT EXISTS" sub
2e8e0 71 75 65 72 79 20 69 73 20 74 68 65 20 6d 61 67  query is the mag
2e8f0 69 63 20 74 68 61 74 0a 66 69 67 75 72 65 73 20  ic that.figures 
2e900 6f 75 74 20 77 68 65 74 68 65 72 20 6f 72 20 6e  out whether or n
2e910 6f 74 20 65 61 63 68 20 63 61 6e 64 69 64 61 74  ot each candidat
2e920 65 20 22 73 22 20 73 74 72 69 6e 67 20 69 73 20  e "s" string is 
2e930 61 20 76 61 6c 69 64 0a 73 75 64 6f 6b 75 20 70  a valid.sudoku p
2e940 75 7a 7a 6c 65 20 6f 72 20 6e 6f 74 2e 0a 0a 3c  uzzle or not...<
2e950 70 3e 54 68 65 20 66 69 6e 61 6c 20 61 6e 73 77  p>The final answ
2e960 65 72 20 69 73 20 66 6f 75 6e 64 20 62 79 20 6c  er is found by l
2e970 6f 6f 6b 69 6e 67 20 66 6f 72 20 61 20 73 74 72  ooking for a str
2e980 69 6e 67 20 77 69 74 68 20 69 6e 64 3d 3d 30 2e  ing with ind==0.
2e990 0a 49 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .If the original
2e9a0 20 73 75 64 6f 6b 75 20 70 72 6f 62 6c 65 6d 20   sudoku problem 
2e9b0 64 69 64 20 6e 6f 74 20 68 61 76 65 20 61 20 75  did not have a u
2e9c0 6e 69 71 75 65 20 73 6f 6c 75 74 69 6f 6e 2c 20  nique solution, 
2e9d0 74 68 65 6e 0a 74 68 65 20 71 75 65 72 79 20 77  then.the query w
2e9e0 69 6c 6c 20 72 65 74 75 72 6e 20 61 6c 6c 20 70  ill return all p
2e9f0 6f 73 73 69 62 6c 65 20 73 6f 6c 75 74 69 6f 6e  ossible solution
2ea00 73 2e 20 20 49 66 20 74 68 65 20 6f 72 69 67 69  s.  If the origi
2ea10 6e 61 6c 20 70 72 6f 62 6c 65 6d 0a 77 61 73 20  nal problem.was 
2ea20 75 6e 73 6f 6c 76 61 62 6c 65 2c 20 74 68 65 6e  unsolvable, then
2ea30 20 6e 6f 20 72 6f 77 73 20 77 69 6c 6c 20 62 65   no rows will be
2ea40 20 72 65 74 75 72 6e 65 64 2e 20 20 49 6e 20 74   returned.  In t
2ea50 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 6e  his case, the un
2ea60 69 71 75 65 0a 61 6e 73 77 65 72 20 69 73 3a 0a  ique.answer is:.
2ea70 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 35 33  .<blockquote>.53
2ea80 34 36 37 38 39 31 32 36 37 32 31 39 35 33 34 38  4678912672195348
2ea90 31 39 38 33 34 32 35 36 37 38 35 39 37 36 31 34  1983425678597614
2eaa0 32 33 34 32 36 38 35 33 37 39 31 37 31 33 39 32  2342685379171392
2eab0 34 38 35 36 39 36 31 35 33 37 32 38 34 32 38 37  4856961537284287
2eac0 34 31 39 36 33 35 33 34 35 32 38 36 31 37 39 0a  419635345286179.
2ead0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
2eae0 70 3e 54 68 65 20 73 6f 6c 75 74 69 6f 6e 20 77  p>The solution w
2eaf0 61 73 20 63 6f 6d 70 75 74 65 64 20 69 6e 20 6c  as computed in l
2eb00 65 73 73 20 74 68 61 6e 20 33 30 30 20 6d 69 6c  ess than 300 mil
2eb10 6c 69 73 65 63 6f 6e 64 73 20 6f 6e 20 61 20 6d  liseconds on a m
2eb20 6f 64 65 72 6e 0a 77 6f 72 6b 73 74 61 74 69 6f  odern.workstatio
2eb30 6e 2e 0a 0a 3c 68 33 3e 4c 69 6d 69 74 61 74 69  n...<h3>Limitati
2eb40 6f 6e 73 20 41 6e 64 20 43 61 76 65 61 74 73 3c  ons And Caveats<
2eb50 2f 68 33 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c  /h3>..<ul>.<li><
2eb60 70 3e 0a 54 68 65 20 57 49 54 48 20 63 6c 61 75  p>.The WITH clau
2eb70 73 65 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  se cannot be use
2eb80 64 20 77 69 74 68 69 6e 20 61 20 5b 43 52 45 41  d within a [CREA
2eb90 54 45 20 54 52 49 47 47 45 52 5d 2e 0a 3c 6c 69  TE TRIGGER]..<li
2eba0 3e 3c 70 3e 0a 54 68 65 20 57 49 54 48 20 63 6c  ><p>.The WITH cl
2ebb0 61 75 73 65 20 6d 75 73 74 20 61 70 70 65 61 72  ause must appear
2ebc0 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
2ebd0 67 20 6f 66 20 61 20 74 6f 70 2d 6c 65 76 65 6c  g of a top-level
2ebe0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ebf0 65 6e 74 0a 6f 72 20 61 74 20 74 68 65 20 62 65  ent.or at the be
2ec00 67 69 6e 6e 69 6e 67 20 6f 66 20 61 20 73 75 62  ginning of a sub
2ec10 71 75 65 72 79 2e 20 20 54 68 65 20 57 49 54 48  query.  The WITH
2ec20 20 63 6c 61 75 73 65 20 63 61 6e 6e 6f 74 20 62   clause cannot b
2ec30 65 20 70 72 65 70 65 6e 64 65 64 20 74 6f 0a 74  e prepended to.t
2ec40 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
2ec50 73 65 71 75 65 6e 74 20 53 45 4c 45 43 54 20 73  sequent SELECT s
2ec60 74 61 74 65 6d 65 6e 74 20 6f 66 20 61 20 5b 63  tatement of a [c
2ec70 6f 6d 70 6f 75 6e 64 20 73 65 6c 65 63 74 5d 2e  ompound select].
2ec80 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20 53 51 4c  .<li><p>.The SQL
2ec90 3a 31 39 39 39 20 73 70 65 63 20 72 65 71 75 69  :1999 spec requi
2eca0 72 65 73 20 74 68 61 74 20 74 68 65 20 52 45 43  res that the REC
2ecb0 55 52 53 49 56 45 20 6b 65 79 77 6f 72 64 20 66  URSIVE keyword f
2ecc0 6f 6c 6c 6f 77 20 57 49 54 48 20 69 6e 20 61 6e  ollow WITH in an
2ecd0 79 0a 57 49 54 48 20 63 6c 61 75 73 65 20 74 68  y.WITH clause th
2ece0 61 74 20 69 6e 63 6c 75 64 65 73 20 61 20 72 65  at includes a re
2ecf0 63 75 72 73 69 76 65 20 63 6f 6d 6d 6f 6e 20 74  cursive common t
2ed00 61 62 6c 65 20 65 78 70 72 65 73 73 69 6f 6e 2e  able expression.
2ed10 20 20 48 6f 77 65 76 65 72 2c 20 66 6f 72 0a 63    However, for.c
2ed20 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2ed30 68 20 53 71 6c 53 65 72 76 65 72 20 61 6e 64 20  h SqlServer and 
2ed40 4f 72 61 63 6c 65 2c 20 53 51 4c 69 74 65 20 64  Oracle, SQLite d
2ed50 6f 65 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 20  oes not enforce 
2ed60 74 68 69 73 20 72 75 6c 65 2e 0a 3c 2f 75 6c 3e  this rule..</ul>
2ed70 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23 23 23 23 23  ..<tcl>.########
2ed80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2ed90 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2eda0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2edb0 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
2edc0 23 23 23 23 23 23 23 0a 53 65 63 74 69 6f 6e 20  #######.Section 
2edd0 53 45 4c 45 43 54 20 73 65 6c 65 63 74 20 7b 53  SELECT select {S
2ede0 45 4c 45 43 54 20 71 75 65 72 79 7d 0a 0a 52 65  ELECT query}..Re
2edf0 63 75 72 73 69 76 65 42 75 62 62 6c 65 44 69 61  cursiveBubbleDia
2ee00 67 72 61 6d 20 73 65 6c 65 63 74 2d 73 74 6d 74  gram select-stmt
2ee10 0a 3c 2f 74 63 6c 3e 0a 0a 0a 3c 70 3e 54 68 65  .</tcl>...<p>The
2ee20 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2ee30 74 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  t is used to que
2ee40 72 79 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ry the database.
2ee50 20 20 54 68 65 0a 72 65 73 75 6c 74 20 6f 66 20    The.result of 
2ee60 61 20 53 45 4c 45 43 54 20 69 73 20 7a 65 72 6f  a SELECT is zero
2ee70 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66   or more rows of
2ee80 20 64 61 74 61 20 77 68 65 72 65 20 65 61 63 68   data where each
2ee90 20 72 6f 77 0a 68 61 73 20 61 20 66 69 78 65 64   row.has a fixed
2eea0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2eeb0 6e 73 2e 20 20 41 20 53 45 4c 45 43 54 20 73 74  ns.  A SELECT st
2eec0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2eed0 20 6d 61 6b 65 0a 61 6e 79 20 63 68 61 6e 67 65   make.any change
2eee0 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
2eef0 65 2e 0a 0a 3c 70 3e 54 68 65 20 22 5b 73 65 6c  e...<p>The "[sel
2ef00 65 63 74 2d 73 74 6d 74 5d 22 20 73 79 6e 74 61  ect-stmt]" synta
2ef10 78 20 64 69 61 67 72 61 6d 20 61 62 6f 76 65 20  x diagram above 
2ef20 61 74 74 65 6d 70 74 73 20 74 6f 20 73 68 6f 77  attempts to show
2ef30 20 61 73 20 6d 75 63 68 20 6f 66 20 74 68 65 0a   as much of the.
2ef40 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
2ef50 20 73 79 6e 74 61 78 20 61 73 20 70 6f 73 73 69   syntax as possi
2ef60 62 6c 65 20 69 6e 20 61 20 73 69 6e 67 6c 65 20  ble in a single 
2ef70 64 69 61 67 72 61 6d 2c 20 62 65 63 61 75 73 65  diagram, because
2ef80 20 73 6f 6d 65 20 72 65 61 64 65 72 73 0a 66 69   some readers.fi
2ef90 6e 64 20 74 68 61 74 20 68 65 6c 70 66 75 6c 2e  nd that helpful.
2efa0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
2efb0 22 5b 66 61 63 74 6f 72 65 64 2d 73 65 6c 65 63  "[factored-selec
2efc0 74 2d 73 74 6d 74 5d 22 20 69 73 20 61 6e 20 61  t-stmt]" is an a
2efd0 6c 74 65 72 6e 61 74 69 76 65 0a 73 79 6e 74 61  lternative.synta
2efe0 78 20 64 69 61 67 72 61 6d 73 20 74 68 61 74 20  x diagrams that 
2eff0 65 78 70 72 65 73 73 65 73 20 74 68 65 20 73 61  expresses the sa
2f000 6d 65 20 73 79 6e 74 61 78 20 62 75 74 20 74 72  me syntax but tr
2f010 69 65 73 20 74 6f 20 62 72 65 61 6b 20 74 68 65  ies to break the
2f020 20 73 79 6e 74 61 78 20 0a 64 6f 77 6e 20 69 6e   syntax .down in
2f030 74 6f 20 73 6d 61 6c 6c 65 72 20 63 68 75 6e 6b  to smaller chunk
2f040 73 2e 0a 0a 3c 74 63 6c 3e 0a 52 65 63 75 72 73  s...<tcl>.Recurs
2f050 69 76 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d  iveBubbleDiagram
2f060 20 2d 2d 69 6e 69 74 69 61 6c 6c 79 2d 68 69 64   --initially-hid
2f070 64 65 6e 20 66 61 63 74 6f 72 65 64 2d 73 65 6c  den factored-sel
2f080 65 63 74 2d 73 74 6d 74 20 73 65 6c 65 63 74 2d  ect-stmt select-
2f090 63 6f 72 65 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e  core.</tcl>..<p>
2f0a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 72 65 20  Note that there 
2f0b0 61 72 65 20 70 61 74 68 73 20 74 68 72 6f 75 67  are paths throug
2f0c0 68 20 74 68 65 20 73 79 6e 74 61 78 20 64 69 61  h the syntax dia
2f0d0 67 72 61 6d 73 20 74 68 61 74 0a 61 72 65 20 6e  grams that.are n
2f0e0 6f 74 20 61 6c 6c 6f 77 65 64 20 69 6e 20 70 72  ot allowed in pr
2f0f0 61 63 74 69 63 65 2e 20 20 53 6f 6d 65 20 65 78  actice.  Some ex
2f100 61 6d 70 6c 65 73 3a 0a 3c 75 6c 3e 0a 3c 6c 69  amples:.<ul>.<li
2f110 3e 41 20 5b 56 41 4c 55 45 53 5d 20 63 6c 61 75  >A [VALUES] clau
2f120 73 65 20 63 61 6e 20 62 65 20 74 68 65 20 66 69  se can be the fi
2f130 72 73 74 20 65 6c 65 6d 65 6e 74 20 69 6e 20 61  rst element in a
2f140 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43   [compound SELEC
2f150 54 5d 0a 20 20 20 20 74 68 61 74 20 75 73 65 73  T].    that uses
2f160 20 61 20 5b 57 49 54 48 5d 20 63 6c 61 75 73 65   a [WITH] clause
2f170 2c 20 62 75 74 20 61 20 5b 73 69 6d 70 6c 65 20  , but a [simple 
2f180 53 45 4c 45 43 54 5d 20 74 68 61 74 20 63 6f 6e  SELECT] that con
2f190 73 69 73 74 73 20 6f 66 0a 20 20 20 20 6a 75 73  sists of.    jus
2f1a0 74 20 61 20 5b 56 41 4c 55 45 53 5d 20 63 6c 61  t a [VALUES] cla
2f1b0 75 73 65 20 63 61 6e 6e 6f 74 20 62 65 20 70 72  use cannot be pr
2f1c0 65 63 65 64 65 64 20 62 79 20 61 20 5b 57 49 54  eceded by a [WIT
2f1d0 48 5d 20 63 6c 61 75 73 65 2e 0a 3c 6c 69 3e 54  H] clause..<li>T
2f1e0 68 65 20 5b 57 49 54 48 5d 20 63 6c 61 75 73 65  he [WITH] clause
2f1f0 20 6d 75 73 74 20 6f 63 63 75 72 20 6f 6e 20 74   must occur on t
2f200 68 65 20 66 69 72 73 74 20 53 45 4c 45 43 54 20  he first SELECT 
2f210 6f 66 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 53  of a [compound S
2f220 45 4c 45 43 54 5d 2e 0a 20 20 20 20 49 74 20 63  ELECT]..    It c
2f230 61 6e 6e 6f 74 20 66 6f 6c 6c 6f 77 20 61 20 5b  annot follow a [
2f240 63 6f 6d 70 6f 75 6e 64 2d 6f 70 65 72 61 74 6f  compound-operato
2f250 72 5d 2e 0a 3c 2f 75 6c 3e 0a 54 68 65 73 65 20  r]..</ul>.These 
2f260 61 6e 64 20 6f 74 68 65 72 20 73 69 6d 69 6c 61  and other simila
2f270 72 20 73 79 6e 74 61 78 20 72 65 73 74 72 69 63  r syntax restric
2f280 74 69 6f 6e 73 20 61 72 65 20 64 65 73 63 72 69  tions are descri
2f290 62 65 64 20 69 6e 20 74 68 65 20 74 65 78 74 2e  bed in the text.
2f2a0 0a 0a 3c 70 3e 54 68 65 20 53 45 4c 45 43 54 20  ..<p>The SELECT 
2f2b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 74 68 65  statement is the
2f2c0 20 6d 6f 73 74 20 63 6f 6d 70 6c 69 63 61 74 65   most complicate
2f2d0 64 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 74 68 65  d command in the
2f2e0 20 53 51 4c 20 6c 61 6e 67 75 61 67 65 2e 0a 54   SQL language..T
2f2f0 6f 20 6d 61 6b 65 20 74 68 65 20 64 65 73 63 72  o make the descr
2f300 69 70 74 69 6f 6e 20 65 61 73 69 65 72 20 74 6f  iption easier to
2f310 20 66 6f 6c 6c 6f 77 2c 20 73 6f 6d 65 20 6f 66   follow, some of
2f320 20 74 68 65 20 70 61 73 73 61 67 65 73 20 62 65   the passages be
2f330 6c 6f 77 20 64 65 73 63 72 69 62 65 0a 74 68 65  low describe.the
2f340 20 77 61 79 20 74 68 65 20 64 61 74 61 20 72 65   way the data re
2f350 74 75 72 6e 65 64 20 62 79 20 61 20 53 45 4c 45  turned by a SELE
2f360 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  CT statement is 
2f370 64 65 74 65 72 6d 69 6e 65 64 20 61 73 20 61 20  determined as a 
2f380 73 65 72 69 65 73 20 6f 66 0a 73 74 65 70 73 2e  series of.steps.
2f390 20 49 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74   It is important
2f3a0 20 74 6f 20 6b 65 65 70 20 69 6e 20 6d 69 6e 64   to keep in mind
2f3b0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 70 75   that this is pu
2f3c0 72 65 6c 79 20 69 6c 6c 75 73 74 72 61 74 69 76  rely illustrativ
2f3d0 65 20 2d 0a 69 6e 20 70 72 61 63 74 69 63 65 20  e -.in practice 
2f3e0 6e 65 69 74 68 65 72 20 53 51 4c 69 74 65 20 6e  neither SQLite n
2f3f0 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  or any other SQL
2f400 20 65 6e 67 69 6e 65 20 69 73 20 72 65 71 75 69   engine is requi
2f410 72 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 0a 74  red to follow .t
2f420 68 69 73 20 6f 72 20 61 6e 79 20 6f 74 68 65 72  his or any other
2f430 20 73 70 65 63 69 66 69 63 20 70 72 6f 63 65 73   specific proces
2f440 73 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  s...<tcl>hd_frag
2f450 6d 65 6e 74 20 73 69 6d 70 6c 65 73 65 6c 65 63  ment simpleselec
2f460 74 20 7b 73 69 6d 70 6c 65 20 53 45 4c 45 43 54  t {simple SELECT
2f470 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 53 69 6d 70  }</tcl>.<h3>Simp
2f480 6c 65 20 53 65 6c 65 63 74 20 50 72 6f 63 65 73  le Select Proces
2f490 73 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68  sing</h3>..<p>Th
2f4a0 65 20 63 6f 72 65 20 6f 66 20 61 20 53 45 4c 45  e core of a SELE
2f4b0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  CT statement is 
2f4c0 61 20 22 73 69 6d 70 6c 65 20 53 45 4c 45 43 54  a "simple SELECT
2f4d0 22 20 73 68 6f 77 6e 20 62 79 20 74 68 65 0a 5b  " shown by the.[
2f4e0 73 65 6c 65 63 74 2d 63 6f 72 65 5d 20 61 6e 64  select-core] and
2f4f0 20 5b 73 69 6d 70 6c 65 2d 73 65 6c 65 63 74 2d   [simple-select-
2f500 73 74 6d 74 5d 20 73 79 6e 74 61 78 20 64 69 61  stmt] syntax dia
2f510 67 72 61 6d 73 20 62 65 6c 6f 77 2e 20 20 0a 49  grams below.  .I
2f520 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 6f 73 74  n practice, most
2f530 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2f540 74 73 20 61 72 65 20 73 69 6d 70 6c 65 20 53 45  ts are simple SE
2f550 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e  LECT statements.
2f560 0a 0a 3c 74 63 6c 3e 0a 52 65 63 75 72 73 69 76  ..<tcl>.Recursiv
2f570 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 73  eBubbleDiagram s
2f580 69 6d 70 6c 65 2d 73 65 6c 65 63 74 2d 73 74 6d  imple-select-stm
2f590 74 20 73 65 6c 65 63 74 2d 63 6f 72 65 0a 3c 2f  t select-core.</
2f5a0 74 63 6c 3e 0a 0a 3c 70 3e 47 65 6e 65 72 61 74  tcl>..<p>Generat
2f5b0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 73 20  ing the results 
2f5c0 6f 66 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45  of a simple SELE
2f5d0 43 54 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20  CT.statement is 
2f5e0 70 72 65 73 65 6e 74 65 64 20 61 73 20 61 20 66  presented as a f
2f5f0 6f 75 72 20 73 74 65 70 20 70 72 6f 63 65 73 73  our step process
2f600 20 69 6e 20 74 68 65 20 64 65 73 63 72 69 70 74   in the descript
2f610 69 6f 6e 20 62 65 6c 6f 77 3a 0a 0a 3c 6f 6c 3e  ion below:..<ol>
2f620 0a 20 20 3c 6c 69 3e 20 3c 70 3e 5b 46 52 4f 4d  .  <li> <p>[FROM
2f630 20 63 6c 61 75 73 65 5d 20 70 72 6f 63 65 73 73   clause] process
2f640 69 6e 67 3a 20 54 68 65 20 69 6e 70 75 74 20 64  ing: The input d
2f650 61 74 61 20 66 6f 72 20 74 68 65 20 73 69 6d 70  ata for the simp
2f660 6c 65 20 53 45 4c 45 43 54 20 69 73 0a 20 20 20  le SELECT is.   
2f670 20 20 20 20 64 65 74 65 72 6d 69 6e 65 64 2e 20      determined. 
2f680 54 68 65 20 69 6e 70 75 74 20 64 61 74 61 20 69  The input data i
2f690 73 20 65 69 74 68 65 72 20 69 6d 70 6c 69 63 69  s either implici
2f6a0 74 6c 79 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tly a single row
2f6b0 20 77 69 74 68 20 30 0a 20 20 20 20 20 20 20 63   with 0.       c
2f6c0 6f 6c 75 6d 6e 73 20 28 69 66 20 74 68 65 72 65  olumns (if there
2f6d0 20 69 73 20 6e 6f 20 46 52 4f 4d 20 63 6c 61 75   is no FROM clau
2f6e0 73 65 29 20 6f 72 20 69 73 20 64 65 74 65 72 6d  se) or is determ
2f6f0 69 6e 65 64 20 62 79 20 74 68 65 20 46 52 4f 4d  ined by the FROM
2f700 0a 20 20 20 20 20 20 20 63 6c 61 75 73 65 2e 0a  .       clause..
2f710 20 20 3c 6c 69 3e 20 3c 70 3e 5b 57 48 45 52 45    <li> <p>[WHERE
2f720 20 63 6c 61 75 73 65 5d 20 70 72 6f 63 65 73 73   clause] process
2f730 69 6e 67 3a 20 54 68 65 20 69 6e 70 75 74 20 64  ing: The input d
2f740 61 74 61 20 69 73 20 66 69 6c 74 65 72 65 64 20  ata is filtered 
2f750 75 73 69 6e 67 20 74 68 65 20 57 48 45 52 45 0a  using the WHERE.
2f760 20 20 20 20 20 20 20 63 6c 61 75 73 65 20 65 78         clause ex
2f770 70 72 65 73 73 69 6f 6e 2e 20 20 0a 20 20 3c 6c  pression.  .  <l
2f780 69 3e 20 3c 70 3e 5b 47 52 4f 55 50 20 42 59 7c  i> <p>[GROUP BY|
2f790 47 52 4f 55 50 20 42 59 2c 20 48 41 56 49 4e 47  GROUP BY, HAVING
2f7a0 20 61 6e 64 20 72 65 73 75 6c 74 2d 63 6f 6c 75   and result-colu
2f7b0 6d 6e 20 65 78 70 72 65 73 73 69 6f 6e 5d 20 70  mn expression] p
2f7c0 72 6f 63 65 73 73 69 6e 67 3a 20 0a 20 20 20 20  rocessing: .    
2f7d0 20 20 20 54 68 65 20 73 65 74 20 6f 66 20 72 65     The set of re
2f7e0 73 75 6c 74 20 72 6f 77 73 20 69 73 20 63 6f 6d  sult rows is com
2f7f0 70 75 74 65 64 20 62 79 20 61 67 67 72 65 67 61  puted by aggrega
2f800 74 69 6e 67 20 74 68 65 20 64 61 74 61 20 61 63  ting the data ac
2f810 63 6f 72 64 69 6e 67 20 74 6f 0a 20 20 20 20 20  cording to.     
2f820 20 20 61 6e 79 20 47 52 4f 55 50 20 42 59 20 63    any GROUP BY c
2f830 6c 61 75 73 65 20 61 6e 64 20 63 61 6c 63 75 6c  lause and calcul
2f840 61 74 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  ating the result
2f850 2d 73 65 74 20 65 78 70 72 65 73 73 69 6f 6e 73  -set expressions
2f860 20 66 6f 72 20 74 68 65 0a 20 20 20 20 20 20 20   for the.       
2f870 72 6f 77 73 20 6f 66 20 74 68 65 20 66 69 6c 74  rows of the filt
2f880 65 72 65 64 20 69 6e 70 75 74 20 64 61 74 61 73  ered input datas
2f890 65 74 2e 20 20 0a 20 20 3c 6c 69 3e 20 3c 70 3e  et.  .  <li> <p>
2f8a0 5b 44 49 53 54 49 4e 43 54 7c 44 49 53 54 49 4e  [DISTINCT|DISTIN
2f8b0 43 54 2f 41 4c 4c 20 6b 65 79 77 6f 72 64 5d 20  CT/ALL keyword] 
2f8c0 70 72 6f 63 65 73 73 69 6e 67 3a 20 49 66 20 74  processing: If t
2f8d0 68 65 20 71 75 65 72 79 20 69 73 20 61 20 22 53  he query is a "S
2f8e0 45 4c 45 43 54 0a 20 20 20 20 20 20 20 44 49 53  ELECT.       DIS
2f8f0 54 49 4e 43 54 22 20 71 75 65 72 79 2c 20 64 75  TINCT" query, du
2f900 70 6c 69 63 61 74 65 20 72 6f 77 73 20 61 72 65  plicate rows are
2f910 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74 68   removed from th
2f920 65 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20  e set of result 
2f930 72 6f 77 73 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e  rows..</ol>..<p>
2f940 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 74 79  There are two ty
2f950 70 65 73 20 6f 66 20 73 69 6d 70 6c 65 20 53 45  pes of simple SE
2f960 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 2d  LECT statement -
2f970 20 61 67 67 72 65 67 61 74 65 20 61 6e 64 20 0a   aggregate and .
2f980 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 20 71 75  non-aggregate qu
2f990 65 72 69 65 73 2e 20 5e 41 20 73 69 6d 70 6c 65  eries. ^A simple
2f9a0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2f9b0 74 20 69 73 20 61 6e 20 61 67 67 72 65 67 61 74  t is an aggregat
2f9c0 65 20 71 75 65 72 79 20 69 66 0a 69 74 20 63 6f  e query if.it co
2f9d0 6e 74 61 69 6e 73 20 65 69 74 68 65 72 20 61 20  ntains either a 
2f9e0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 20  GROUP BY clause 
2f9f0 6f 72 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  or one or more a
2fa00 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2fa10 6e 73 0a 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns.in the result
2fa20 2d 73 65 74 2e 20 5e 4f 74 68 65 72 77 69 73 65  -set. ^Otherwise
2fa30 2c 20 69 66 20 61 20 73 69 6d 70 6c 65 20 53 45  , if a simple SE
2fa40 4c 45 43 54 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  LECT contains no
2fa50 20 61 67 67 72 65 67 61 74 65 0a 66 75 6e 63 74   aggregate.funct
2fa60 69 6f 6e 73 20 6f 72 20 61 20 47 52 4f 55 50 20  ions or a GROUP 
2fa70 42 59 20 63 6c 61 75 73 65 2c 20 69 74 20 69 73  BY clause, it is
2fa80 20 61 20 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65   a non-aggregate
2fa90 20 71 75 65 72 79 2e 0a 0a 3c 70 3e 3c 62 3e 31   query...<p><b>1
2faa0 2e 20 44 65 74 65 72 6d 69 6e 61 74 69 6f 6e 20  . Determination 
2fab0 6f 66 20 69 6e 70 75 74 20 64 61 74 61 20 28 46  of input data (F
2fac0 52 4f 4d 20 63 6c 61 75 73 65 20 70 72 6f 63 65  ROM clause proce
2fad0 73 73 69 6e 67 29 2e 3c 2f 62 3e 0a 3c 74 63 6c  ssing).</b>.<tcl
2fae0 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 66 72 6f  >hd_fragment fro
2faf0 6d 63 6c 61 75 73 65 3c 2f 74 63 6c 3e 0a 3c 74  mclause</tcl>.<t
2fb00 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b  cl>hd_keywords {
2fb10 46 52 4f 4d 20 63 6c 61 75 73 65 7d 3c 2f 74 63  FROM clause}</tc
2fb20 6c 3e 0a 0a 3c 70 3e 54 68 65 20 69 6e 70 75 74  l>..<p>The input
2fb30 20 64 61 74 61 20 75 73 65 64 20 62 79 20 61 20   data used by a 
2fb40 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20 71 75  simple SELECT qu
2fb50 65 72 79 20 69 73 20 61 20 73 65 74 20 6f 66 20  ery is a set of 
2fb60 3c 69 3e 4e 3c 2f 69 3e 20 72 6f 77 73 20 0a 65  <i>N</i> rows .e
2fb70 61 63 68 20 3c 69 3e 4d 3c 2f 69 3e 20 63 6f 6c  ach <i>M</i> col
2fb80 75 6d 6e 73 20 77 69 64 65 2e 0a 0a 3c 70 3e 5e  umns wide...<p>^
2fb90 28 49 66 20 74 68 65 20 46 52 4f 4d 20 63 6c 61  (If the FROM cla
2fba0 75 73 65 20 69 73 20 6f 6d 69 74 74 65 64 20 66  use is omitted f
2fbb0 72 6f 6d 20 61 20 73 69 6d 70 6c 65 20 53 45 4c  rom a simple SEL
2fbc0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  ECT statement, t
2fbd0 68 65 6e 20 74 68 65 20 0a 69 6e 70 75 74 20 64  hen the .input d
2fbe0 61 74 61 20 69 73 20 69 6d 70 6c 69 63 69 74 6c  ata is implicitl
2fbf0 79 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 7a  y a single row z
2fc00 65 72 6f 20 63 6f 6c 75 6d 6e 73 20 77 69 64 65  ero columns wide
2fc10 29 5e 20 28 69 2e 65 2e 20 3c 69 3e 4e 3c 2f 69  )^ (i.e. <i>N</i
2fc20 3e 3d 31 20 61 6e 64 0a 3c 69 3e 4d 3c 2f 69 3e  >=1 and.<i>M</i>
2fc30 3d 30 29 2e 0a 0a 3c 70 3e 49 66 20 61 20 46 52  =0)...<p>If a FR
2fc40 4f 4d 20 63 6c 61 75 73 65 20 69 73 20 73 70 65  OM clause is spe
2fc50 63 69 66 69 65 64 2c 20 74 68 65 20 64 61 74 61  cified, the data
2fc60 20 6f 6e 20 77 68 69 63 68 20 61 20 73 69 6d 70   on which a simp
2fc70 6c 65 20 53 45 4c 45 43 54 20 71 75 65 72 79 0a  le SELECT query.
2fc80 6f 70 65 72 61 74 65 73 20 63 6f 6d 65 73 20 66  operates comes f
2fc90 72 6f 6d 20 74 68 65 20 6f 6e 65 20 6f 72 20 6d  rom the one or m
2fca0 6f 72 65 20 74 61 62 6c 65 73 20 6f 72 20 73 75  ore tables or su
2fcb0 62 71 75 65 72 69 65 73 20 28 53 45 4c 45 43 54  bqueries (SELECT
2fcc0 20 73 74 61 74 65 6d 65 6e 74 73 0a 69 6e 20 70   statements.in p
2fcd0 61 72 65 6e 74 68 65 73 65 73 29 20 73 70 65 63  arentheses) spec
2fce0 69 66 69 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  ified following 
2fcf0 74 68 65 20 46 52 4f 4d 20 6b 65 79 77 6f 72 64  the FROM keyword
2fd00 2e 20 5e 41 20 73 75 62 71 75 65 72 79 20 73 70  . ^A subquery sp
2fd10 65 63 69 66 69 65 64 0a 69 6e 20 74 68 65 20 3c  ecified.in the <
2fd20 79 79 74 65 72 6d 3e 74 61 62 6c 65 2d 6f 72 2d  yyterm>table-or-
2fd30 73 75 62 71 75 65 72 79 3c 2f 79 79 74 65 72 6d  subquery</yyterm
2fd40 3e 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20  > following the 
2fd50 46 52 4f 4d 20 63 6c 61 75 73 65 20 69 6e 20 61  FROM clause in a
2fd60 20 0a 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20   .simple SELECT 
2fd70 73 74 61 74 65 6d 65 6e 74 20 69 73 0a 68 61 6e  statement is.han
2fd80 64 6c 65 64 20 61 73 20 69 66 20 69 74 20 77 61  dled as if it wa
2fd90 73 20 61 20 74 61 62 6c 65 20 63 6f 6e 74 61 69  s a table contai
2fda0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 20 72 65  ning the data re
2fdb0 74 75 72 6e 65 64 20 62 79 20 65 78 65 63 75 74  turned by execut
2fdc0 69 6e 67 20 74 68 65 0a 73 75 62 71 75 65 72 79  ing the.subquery
2fdd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 45 61 63   statement. ^Eac
2fde0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2fdf0 73 75 62 71 75 65 72 79 20 68 61 73 20 74 68 65  subquery has the
2fe00 0a 5b 63 6f 6c 6c 61 74 69 6f 6e 7c 63 6f 6c 6c  .[collation|coll
2fe10 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 5d 20  ation sequence] 
2fe20 61 6e 64 20 5b 61 66 66 69 6e 69 74 79 5d 20 6f  and [affinity] o
2fe30 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2fe40 69 6e 67 20 65 78 70 72 65 73 73 69 6f 6e 0a 69  ing expression.i
2fe50 6e 20 74 68 65 20 73 75 62 71 75 65 72 79 20 73  n the subquery s
2fe60 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 5e 49  tatement...<p>^I
2fe70 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2fe80 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 20 6f  a single table o
2fe90 72 20 73 75 62 71 75 65 72 79 20 69 6e 20 74 68  r subquery in th
2fea0 65 20 46 52 4f 4d 0a 63 6c 61 75 73 65 2c 20 74  e FROM.clause, t
2feb0 68 65 6e 20 74 68 65 20 69 6e 70 75 74 20 64 61  hen the input da
2fec0 74 61 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ta used by the S
2fed0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
2fee0 69 73 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  is the contents 
2fef0 6f 66 20 74 68 65 0a 6e 61 6d 65 64 20 74 61 62  of the.named tab
2ff00 6c 65 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  le. ^If there is
2ff10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
2ff20 61 62 6c 65 20 6f 72 20 73 75 62 71 75 65 72 79  able or subquery
2ff30 20 69 6e 20 46 52 4f 4d 20 63 6c 61 75 73 65 0a   in FROM clause.
2ff40 74 68 65 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  then the content
2ff50 73 20 6f 66 20 61 6c 6c 20 74 61 62 6c 65 73 20  s of all tables 
2ff60 61 6e 64 2f 6f 72 20 73 75 62 71 75 65 72 69 65  and/or subquerie
2ff70 73 0a 61 72 65 20 6a 6f 69 6e 65 64 20 69 6e 74  s.are joined int
2ff80 6f 20 61 20 73 69 6e 67 6c 65 20 64 61 74 61 73  o a single datas
2ff90 65 74 20 66 6f 72 20 74 68 65 20 73 69 6d 70 6c  et for the simpl
2ffa0 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
2ffb0 6e 74 20 74 6f 20 6f 70 65 72 61 74 65 20 6f 6e  nt to operate on
2ffc0 2e 0a 45 78 61 63 74 6c 79 20 68 6f 77 20 74 68  ..Exactly how th
2ffd0 65 20 64 61 74 61 20 69 73 20 63 6f 6d 62 69 6e  e data is combin
2ffe0 65 64 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68  ed depends on th
2fff0 65 20 73 70 65 63 69 66 69 63 20 5b 6a 6f 69 6e  e specific [join
30000 2d 6f 70 65 72 61 74 6f 72 5d 20 61 6e 64 0a 5b  -operator] and.[
30010 6a 6f 69 6e 2d 63 6f 6e 73 74 72 61 69 6e 74 5d  join-constraint]
30020 20 75 73 65 64 20 74 6f 20 63 6f 6e 6e 65 63 74   used to connect
30030 20 74 68 65 20 74 61 62 6c 65 73 20 6f 72 20 73   the tables or s
30040 75 62 71 75 65 72 69 65 73 20 74 6f 67 65 74 68  ubqueries togeth
30050 65 72 2e 0a 0a 3c 70 3e 41 6c 6c 20 6a 6f 69 6e  er...<p>All join
30060 73 20 69 6e 20 53 51 4c 69 74 65 20 61 72 65 20  s in SQLite are 
30070 62 61 73 65 64 20 6f 6e 20 74 68 65 20 63 61 72  based on the car
30080 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20 6f  tesian product o
30090 66 20 74 68 65 20 6c 65 66 74 20 61 6e 64 0a 72  f the left and.r
300a0 69 67 68 74 2d 68 61 6e 64 20 64 61 74 61 73 65  ight-hand datase
300b0 74 73 2e 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 73  ts. ^The columns
300c0 20 6f 66 20 74 68 65 20 63 61 72 74 65 73 69 61   of the cartesia
300d0 6e 20 70 72 6f 64 75 63 74 20 64 61 74 61 73 65  n product datase
300e0 74 20 61 72 65 2c 20 69 6e 20 0a 6f 72 64 65 72  t are, in .order
300f0 2c 20 61 6c 6c 20 74 68 65 20 63 6f 6c 75 6d 6e  , all the column
30100 73 20 6f 66 20 74 68 65 20 6c 65 66 74 2d 68 61  s of the left-ha
30110 6e 64 20 64 61 74 61 73 65 74 20 66 6f 6c 6c 6f  nd dataset follo
30120 77 65 64 20 62 79 20 61 6c 6c 20 74 68 65 20 63  wed by all the c
30130 6f 6c 75 6d 6e 73 0a 6f 66 20 74 68 65 20 72 69  olumns.of the ri
30140 67 68 74 2d 68 61 6e 64 20 64 61 74 61 73 65 74  ght-hand dataset
30150 2e 20 5e 54 68 65 72 65 20 69 73 20 61 20 72 6f  . ^There is a ro
30160 77 20 69 6e 20 74 68 65 20 63 61 72 74 65 73 69  w in the cartesi
30170 61 6e 20 70 72 6f 64 75 63 74 20 64 61 74 61 73  an product datas
30180 65 74 0a 66 6f 72 6d 65 64 20 62 79 20 63 6f 6d  et.formed by com
30190 62 69 6e 69 6e 67 20 65 61 63 68 20 75 6e 69 71  bining each uniq
301a0 75 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ue combination o
301b0 66 20 61 20 72 6f 77 20 66 72 6f 6d 20 74 68 65  f a row from the
301c0 20 6c 65 66 74 2d 68 61 6e 64 20 0a 61 6e 64 20   left-hand .and 
301d0 72 69 67 68 74 2d 68 61 6e 64 20 64 61 74 61 73  right-hand datas
301e0 65 74 73 2e 20 5e 28 49 6e 20 6f 74 68 65 72 20  ets. ^(In other 
301f0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 6c 65  words, if the le
30200 66 74 2d 68 61 6e 64 20 64 61 74 61 73 65 74 20  ft-hand dataset 
30210 63 6f 6e 73 69 73 74 73 20 6f 66 0a 3c 69 3e 4e  consists of.<i>N
30220 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 6c 65 66 74  <sub><small>left
30230 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 3c 2f  </small></sub></
30240 69 3e 20 72 6f 77 73 20 6f 66 20 0a 3c 69 3e 4d  i> rows of .<i>M
30250 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 6c 65 66 74  <sub><small>left
30260 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 3c 2f  </small></sub></
30270 69 3e 20 63 6f 6c 75 6d 6e 73 2c 20 61 6e 64 20  i> columns, and 
30280 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 64  the right-hand d
30290 61 74 61 73 65 74 20 6f 66 0a 3c 69 3e 4e 3c 73  ataset of.<i>N<s
302a0 75 62 3e 3c 73 6d 61 6c 6c 3e 72 69 67 68 74 3c  ub><small>right<
302b0 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 3c 2f 69  /small></sub></i
302c0 3e 20 72 6f 77 73 20 6f 66 0a 3c 69 3e 4d 3c 73  > rows of.<i>M<s
302d0 75 62 3e 3c 73 6d 61 6c 6c 3e 72 69 67 68 74 3c  ub><small>right<
302e0 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 3c 2f 69  /small></sub></i
302f0 3e 20 63 6f 6c 75 6d 6e 73 2c 20 74 68 65 6e 20  > columns, then 
30300 74 68 65 20 63 61 72 74 65 73 69 61 6e 20 70 72  the cartesian pr
30310 6f 64 75 63 74 20 69 73 20 61 0a 64 61 74 61 73  oduct is a.datas
30320 65 74 20 6f 66 20 0a 3c 69 3e 4e 3c 73 75 62 3e  et of .<i>N<sub>
30330 3c 73 6d 61 6c 6c 3e 6c 65 66 74 3c 2f 73 6d 61  <small>left</sma
30340 6c 6c 3e 3c 2f 73 75 62 3e 26 74 69 6d 65 73 3b  ll></sub>&times;
30350 4e 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 72 69 67  N<sub><small>rig
30360 68 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e  ht</small></sub>
30370 3c 2f 69 3e 0a 72 6f 77 73 2c 20 65 61 63 68 20  </i>.rows, each 
30380 63 6f 6e 74 61 69 6e 69 6e 67 20 0a 3c 69 3e 4d  containing .<i>M
30390 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 6c 65 66 74  <sub><small>left
303a0 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 2b 4d  </small></sub>+M
303b0 3c 73 75 62 3e 3c 73 6d 61 6c 6c 3e 72 69 67 68  <sub><small>righ
303c0 74 3c 2f 73 6d 61 6c 6c 3e 3c 2f 73 75 62 3e 3c  t</small></sub><
303d0 2f 69 3e 20 63 6f 6c 75 6d 6e 73 2e 29 5e 0a 0a  /i> columns.)^..
303e0 3c 70 3e 5e 49 66 20 74 68 65 20 6a 6f 69 6e 2d  <p>^If the join-
303f0 6f 70 65 72 61 74 6f 72 20 69 73 20 22 43 52 4f  operator is "CRO
30400 53 53 20 4a 4f 49 4e 22 2c 20 22 49 4e 4e 45 52  SS JOIN", "INNER
30410 20 4a 4f 49 4e 22 2c 20 22 4a 4f 49 4e 22 20 6f   JOIN", "JOIN" o
30420 72 20 61 20 63 6f 6d 6d 61 0a 28 22 2c 22 29 20  r a comma.(",") 
30430 61 6e 64 20 74 68 65 72 65 20 69 73 20 6e 6f 20  and there is no 
30440 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c 61 75  ON or USING clau
30450 73 65 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  se, then the res
30460 75 6c 74 20 6f 66 20 74 68 65 20 6a 6f 69 6e 20  ult of the join 
30470 69 73 0a 73 69 6d 70 6c 79 20 74 68 65 20 63 61  is.simply the ca
30480 72 74 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20  rtesian product 
30490 6f 66 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20  of the left and 
304a0 72 69 67 68 74 2d 68 61 6e 64 20 64 61 74 61 73  right-hand datas
304b0 65 74 73 2e 20 0a 49 66 20 6a 6f 69 6e 2d 6f 70  ets. .If join-op
304c0 65 72 61 74 6f 72 20 64 6f 65 73 20 68 61 76 65  erator does have
304d0 20 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c 61   ON or USING cla
304e0 75 73 65 73 2c 20 74 68 6f 73 65 20 61 72 65 20  uses, those are 
304f0 68 61 6e 64 6c 65 64 20 61 63 63 6f 72 64 69 6e  handled accordin
30500 67 20 74 6f 0a 74 68 65 20 66 6f 6c 6c 6f 77 69  g to.the followi
30510 6e 67 20 62 75 6c 6c 65 74 20 70 6f 69 6e 74 73  ng bullet points
30520 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c  :..<ul>.  <li> <
30530 70 3e 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  p>^(If there is 
30540 61 6e 20 4f 4e 20 63 6c 61 75 73 65 20 74 68 65  an ON clause the
30550 6e 20 74 68 65 20 4f 4e 20 65 78 70 72 65 73 73  n the ON express
30560 69 6f 6e 20 69 73 0a 20 20 20 20 20 20 20 65 76  ion is.       ev
30570 61 6c 75 61 74 65 64 20 66 6f 72 20 65 61 63 68  aluated for each
30580 20 72 6f 77 20 6f 66 20 74 68 65 20 63 61 72 74   row of the cart
30590 65 73 69 61 6e 20 70 72 6f 64 75 63 74 20 61 73  esian product as
305a0 20 61 20 0a 20 20 20 20 20 20 20 5b 62 6f 6f 6c   a .       [bool
305b0 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 5d 2e  ean expression].
305c0 20 4f 6e 6c 79 20 72 6f 77 73 20 66 6f 72 20 77   Only rows for w
305d0 68 69 63 68 20 74 68 65 20 65 78 70 72 65 73 73  hich the express
305e0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 74 6f  ion evaluates to
305f0 20 0a 20 20 20 20 20 20 20 74 72 75 65 20 61 72   .       true ar
30600 65 20 69 6e 63 6c 75 64 65 64 20 66 72 6f 6d 20  e included from 
30610 74 68 65 20 64 61 74 61 73 65 74 2e 29 5e 0a 0a  the dataset.)^..
30620 20 20 3c 6c 69 3e 20 3c 70 3e 5e 49 66 20 74 68    <li> <p>^If th
30630 65 72 65 20 69 73 20 61 20 55 53 49 4e 47 20 63  ere is a USING c
30640 6c 61 75 73 65 0a 20 20 20 20 20 20 20 74 68 65  lause.       the
30650 6e 20 65 61 63 68 20 6f 66 20 74 68 65 20 63 6f  n each of the co
30660 6c 75 6d 6e 20 6e 61 6d 65 73 20 73 70 65 63 69  lumn names speci
30670 66 69 65 64 20 6d 75 73 74 20 65 78 69 73 74 20  fied must exist 
30680 69 6e 20 74 68 65 20 64 61 74 61 73 65 74 73 20  in the datasets 
30690 74 6f 20 0a 20 20 20 20 20 20 20 62 6f 74 68 20  to .       both 
306a0 74 68 65 20 6c 65 66 74 20 61 6e 64 20 72 69 67  the left and rig
306b0 68 74 20 6f 66 20 74 68 65 20 6a 6f 69 6e 2d 6f  ht of the join-o
306c0 70 65 72 61 74 6f 72 2e 20 5e 28 46 6f 72 20 65  perator. ^(For e
306d0 61 63 68 20 70 61 69 72 20 6f 66 20 6e 61 6d 65  ach pair of name
306e0 64 0a 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73  d.       columns
306f0 2c 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e  , the expression
30700 20 22 6c 68 73 2e 58 20 3d 20 72 68 73 2e 58 22   "lhs.X = rhs.X"
30710 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 66 6f   is evaluated fo
30720 72 20 65 61 63 68 20 72 6f 77 20 6f 66 0a 20 20  r each row of.  
30730 20 20 20 20 20 74 68 65 20 63 61 72 74 65 73 69       the cartesi
30740 61 6e 20 70 72 6f 64 75 63 74 20 61 73 20 61 20  an product as a 
30750 5b 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73  [boolean express
30760 69 6f 6e 5d 2e 20 4f 6e 6c 79 20 72 6f 77 73 20  ion]. Only rows 
30770 66 6f 72 20 77 68 69 63 68 0a 20 20 20 20 20 20  for which.      
30780 20 61 6c 6c 20 73 75 63 68 20 65 78 70 72 65 73   all such expres
30790 73 69 6f 6e 73 20 65 76 61 6c 75 61 74 65 73 20  sions evaluates 
307a0 74 6f 20 74 72 75 65 20 61 72 65 20 69 6e 63 6c  to true are incl
307b0 75 64 65 64 20 66 72 6f 6d 20 74 68 65 0a 20 20  uded from the.  
307c0 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2e       result set.
307d0 29 5e 20 5e 57 68 65 6e 20 63 6f 6d 70 61 72 69  )^ ^When compari
307e0 6e 67 20 76 61 6c 75 65 73 20 61 73 20 61 20 72  ng values as a r
307f0 65 73 75 6c 74 20 6f 66 20 61 20 55 53 49 4e 47  esult of a USING
30800 20 63 6c 61 75 73 65 2c 20 74 68 65 0a 20 20 20   clause, the.   
30810 20 20 20 20 6e 6f 72 6d 61 6c 20 72 75 6c 65 73      normal rules
30820 20 66 6f 72 20 68 61 6e 64 6c 69 6e 67 20 61 66   for handling af
30830 66 69 6e 69 74 69 65 73 2c 20 63 6f 6c 6c 61 74  finities, collat
30840 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 6e  ion sequences an
30850 64 20 4e 55 4c 4c 0a 20 20 20 20 20 20 20 76 61  d NULL.       va
30860 6c 75 65 73 20 69 6e 20 63 6f 6d 70 61 72 69 73  lues in comparis
30870 6f 6e 73 20 61 70 70 6c 79 2e 20 5e 54 68 65 20  ons apply. ^The 
30880 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 74 68 65 20  column from the 
30890 64 61 74 61 73 65 74 20 6f 6e 20 74 68 65 0a 20  dataset on the. 
308a0 20 20 20 20 20 20 6c 65 66 74 2d 68 61 6e 64 20        left-hand 
308b0 73 69 64 65 20 6f 66 20 74 68 65 20 6a 6f 69 6e  side of the join
308c0 2d 6f 70 65 72 61 74 6f 72 20 69 73 20 63 6f 6e  -operator is con
308d0 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 6f 6e  sidered to be on
308e0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 0a 20   the left-hand. 
308f0 20 20 20 20 20 20 73 69 64 65 20 6f 66 20 74 68        side of th
30900 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 6f 70 65  e comparison ope
30910 72 61 74 6f 72 20 28 3d 29 20 66 6f 72 20 74 68  rator (=) for th
30920 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 63 6f  e purposes of co
30930 6c 6c 61 74 69 6f 6e 20 0a 20 20 20 20 20 20 20  llation .       
30940 73 65 71 75 65 6e 63 65 20 61 6e 64 20 61 66 66  sequence and aff
30950 69 6e 69 74 79 20 70 72 65 63 65 64 65 6e 63 65  inity precedence
30960 2e 0a 0a 20 20 20 20 20 20 20 3c 70 3e 5e 46 6f  ...       <p>^Fo
30970 72 20 65 61 63 68 20 70 61 69 72 20 6f 66 20 63  r each pair of c
30980 6f 6c 75 6d 6e 73 20 69 64 65 6e 74 69 66 69 65  olumns identifie
30990 64 20 62 79 20 61 20 55 53 49 4e 47 20 63 6c 61  d by a USING cla
309a0 75 73 65 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 0a  use, the column.
309b0 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20         from the 
309c0 72 69 67 68 74 2d 68 61 6e 64 20 64 61 74 61 73  right-hand datas
309d0 65 74 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  et is omitted fr
309e0 6f 6d 20 74 68 65 20 6a 6f 69 6e 65 64 20 64 61  om the joined da
309f0 74 61 73 65 74 2e 20 5e 54 68 69 73 20 0a 20 20  taset. ^This .  
30a00 20 20 20 20 20 69 73 20 74 68 65 20 6f 6e 6c 79       is the only
30a10 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
30a20 65 65 6e 20 61 20 55 53 49 4e 47 20 63 6c 61 75  een a USING clau
30a30 73 65 20 61 6e 64 20 69 74 73 20 65 71 75 69 76  se and its equiv
30a40 61 6c 65 6e 74 20 4f 4e 0a 20 20 20 20 20 20 20  alent ON.       
30a50 63 6f 6e 73 74 72 61 69 6e 74 2e 0a 0a 20 20 3c  constraint...  <
30a60 6c 69 3e 20 3c 70 3e 5e 28 49 66 20 74 68 65 20  li> <p>^(If the 
30a70 4e 41 54 55 52 41 4c 20 6b 65 79 77 6f 72 64 20  NATURAL keyword 
30a80 69 73 20 69 6e 20 74 68 65 20 6a 6f 69 6e 2d 6f  is in the join-o
30a90 70 65 72 61 74 6f 72 20 74 68 65 6e 20 61 6e 0a  perator then an.
30aa0 20 20 20 20 20 20 20 69 6d 70 6c 69 63 69 74 20         implicit 
30ab0 55 53 49 4e 47 20 63 6c 61 75 73 65 20 69 73 20  USING clause is 
30ac0 61 64 64 65 64 20 74 6f 20 74 68 65 20 6a 6f 69  added to the joi
30ad0 6e 2d 63 6f 6e 73 74 72 61 69 6e 74 73 2e 20 54  n-constraints. T
30ae0 68 65 20 69 6d 70 6c 69 63 69 74 0a 20 20 20 20  he implicit.    
30af0 20 20 20 55 53 49 4e 47 20 63 6c 61 75 73 65 20     USING clause 
30b00 63 6f 6e 74 61 69 6e 73 20 65 61 63 68 20 6f 66  contains each of
30b10 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
30b20 73 20 74 68 61 74 20 61 70 70 65 61 72 20 69 6e  s that appear in
30b30 20 62 6f 74 68 0a 20 20 20 20 20 20 20 74 68 65   both.       the
30b40 20 6c 65 66 74 20 61 6e 64 20 72 69 67 68 74 2d   left and right-
30b50 68 61 6e 64 20 69 6e 70 75 74 20 64 61 74 61 73  hand input datas
30b60 65 74 73 2e 29 5e 20 5e 49 66 20 74 68 65 20 6c  ets.)^ ^If the l
30b70 65 66 74 20 61 6e 64 20 72 69 67 68 74 2d 68 61  eft and right-ha
30b80 6e 64 0a 20 20 20 20 20 20 20 69 6e 70 75 74 20  nd.       input 
30b90 64 61 74 61 73 65 74 73 20 66 65 61 74 75 72 65  datasets feature
30ba0 20 6e 6f 20 63 6f 6d 6d 6f 6e 20 63 6f 6c 75 6d   no common colum
30bb0 6e 20 6e 61 6d 65 73 2c 20 74 68 65 6e 20 74 68  n names, then th
30bc0 65 20 4e 41 54 55 52 41 4c 20 6b 65 79 77 6f 72  e NATURAL keywor
30bd0 64 0a 20 20 20 20 20 20 20 68 61 73 20 6e 6f 20  d.       has no 
30be0 65 66 66 65 63 74 20 6f 6e 20 74 68 65 20 72 65  effect on the re
30bf0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 6a 6f 69  sults of the joi
30c00 6e 2e 20 5e 41 20 55 53 49 4e 47 20 6f 72 20 4f  n. ^A USING or O
30c10 4e 20 63 6c 61 75 73 65 20 6d 61 79 0a 20 20 20  N clause may.   
30c20 20 20 20 20 6e 6f 74 20 62 65 20 61 64 64 65 64      not be added
30c30 20 74 6f 20 61 20 6a 6f 69 6e 20 74 68 61 74 20   to a join that 
30c40 73 70 65 63 69 66 69 65 73 20 74 68 65 20 4e 41  specifies the NA
30c50 54 55 52 41 4c 20 6b 65 79 77 6f 72 64 2e 0a 0a  TURAL keyword...
30c60 20 20 3c 6c 69 3e 20 3c 70 3e 5e 28 49 66 20 74    <li> <p>^(If t
30c70 68 65 20 6a 6f 69 6e 2d 6f 70 65 72 61 74 6f 72  he join-operator
30c80 20 69 73 20 61 20 22 4c 45 46 54 20 4a 4f 49 4e   is a "LEFT JOIN
30c90 22 20 6f 72 20 22 4c 45 46 54 20 4f 55 54 45 52  " or "LEFT OUTER
30ca0 20 4a 4f 49 4e 22 2c 20 74 68 65 6e 0a 20 20 20   JOIN", then.   
30cb0 20 20 20 20 61 66 74 65 72 0a 20 20 20 20 20 20      after.      
30cc0 20 74 68 65 20 4f 4e 20 6f 72 20 55 53 49 4e 47   the ON or USING
30cd0 20 66 69 6c 74 65 72 69 6e 67 20 63 6c 61 75 73   filtering claus
30ce0 65 73 20 68 61 76 65 20 62 65 65 6e 20 61 70 70  es have been app
30cf0 6c 69 65 64 2c 20 61 6e 20 65 78 74 72 61 20 72  lied, an extra r
30d00 6f 77 20 69 73 20 0a 20 20 20 20 20 20 20 61 64  ow is .       ad
30d10 64 65 64 20 74 6f 20 74 68 65 20 6f 75 74 70 75  ded to the outpu
30d20 74 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 69  t for each row i
30d30 6e 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 6c  n the original l
30d40 65 66 74 2d 68 61 6e 64 20 69 6e 70 75 74 20 0a  eft-hand input .
30d50 20 20 20 20 20 20 20 64 61 74 61 73 65 74 20 74         dataset t
30d60 68 61 74 20 63 6f 72 72 65 73 70 6f 6e 64 73 20  hat corresponds 
30d70 74 6f 20 6e 6f 20 72 6f 77 73 20 61 74 20 61 6c  to no rows at al
30d80 6c 20 69 6e 20 74 68 65 20 63 6f 6d 70 6f 73 69  l in the composi
30d90 74 65 0a 20 20 20 20 20 20 20 64 61 74 61 73 65  te.       datase
30da0 74 20 28 69 66 20 61 6e 79 29 2e 29 5e 20 5e 54  t (if any).)^ ^T
30db0 68 65 20 61 64 64 65 64 20 72 6f 77 73 20 63 6f  he added rows co
30dc0 6e 74 61 69 6e 20 4e 55 4c 4c 20 76 61 6c 75 65  ntain NULL value
30dd0 73 20 69 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s in the columns
30de0 0a 20 20 20 20 20 20 20 74 68 61 74 20 77 6f 75  .       that wou
30df0 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 63 6f 6e 74  ld normally cont
30e00 61 69 6e 20 76 61 6c 75 65 73 20 63 6f 70 69 65  ain values copie
30e10 64 20 66 72 6f 6d 20 74 68 65 20 72 69 67 68 74  d from the right
30e20 2d 68 61 6e 64 20 69 6e 70 75 74 0a 20 20 20 20  -hand input.    
30e30 20 20 20 64 61 74 61 73 65 74 2e 20 20 0a 3c 2f     dataset.  .</
30e40 75 6c 3e 0a 0a 3c 70 3e 5e 28 57 68 65 6e 20 6d  ul>..<p>^(When m
30e50 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 74 61 62  ore than two tab
30e60 6c 65 73 20 61 72 65 20 6a 6f 69 6e 65 64 20 74  les are joined t
30e70 6f 67 65 74 68 65 72 20 61 73 20 70 61 72 74 20  ogether as part 
30e80 6f 66 20 61 20 46 52 4f 4d 20 63 6c 61 75 73 65  of a FROM clause
30e90 2c 0a 74 68 65 20 6a 6f 69 6e 20 6f 70 65 72 61  ,.the join opera
30ea0 74 69 6f 6e 73 20 61 72 65 20 70 72 6f 63 65 73  tions are proces
30eb0 73 65 64 20 69 6e 20 6f 72 64 65 72 20 66 72 6f  sed in order fro
30ec0 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74 2e  m left to right.
30ed0 20 49 6e 20 6f 74 68 65 72 20 0a 77 6f 72 64 73   In other .words
30ee0 2c 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73  , the FROM claus
30ef0 65 20 28 41 20 6a 6f 69 6e 2d 6f 70 2d 31 20 42  e (A join-op-1 B
30f00 20 6a 6f 69 6e 2d 6f 70 2d 32 20 43 29 20 69 73   join-op-2 C) is
30f10 20 63 6f 6d 70 75 74 65 64 20 61 73 20 0a 28 28   computed as .((
30f20 41 20 6a 6f 69 6e 2d 6f 70 2d 31 20 42 29 20 6a  A join-op-1 B) j
30f30 6f 69 6e 2d 6f 70 2d 32 20 43 29 2e 29 5e 0a 0a  oin-op-2 C).)^..
30f40 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
30f50 20 63 72 6f 73 73 6a 6f 69 6e 20 7b 74 72 65 61   crossjoin {trea
30f60 74 73 20 74 68 65 20 43 52 4f 53 53 20 4a 4f 49  ts the CROSS JOI
30f70 4e 20 6f 70 65 72 61 74 6f 72 20 73 70 65 63 69  N operator speci
30f80 61 6c 6c 79 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 3c  ally}</tcl>.<p><
30f90 62 3e 53 69 64 65 20 6e 6f 74 65 3a 20 53 70 65  b>Side note: Spe
30fa0 63 69 61 6c 20 68 61 6e 64 6c 69 6e 67 20 6f 66  cial handling of
30fb0 20 43 52 4f 53 53 20 4a 4f 49 4e 2e 3c 2f 62 3e   CROSS JOIN.</b>
30fc0 0a 5e 54 68 65 72 65 20 69 73 20 6e 6f 20 64 69  .^There is no di
30fd0 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e  fference between
30fe0 20 74 68 65 20 22 49 4e 4e 45 52 20 4a 4f 49 4e   the "INNER JOIN
30ff0 22 2c 20 22 4a 4f 49 4e 22 20 61 6e 64 20 22 2c  ", "JOIN" and ",
31000 22 20 6a 6f 69 6e 0a 6f 70 65 72 61 74 6f 72 73  " join.operators
31010 2e 20 54 68 65 79 20 61 72 65 20 63 6f 6d 70 6c  . They are compl
31020 65 74 65 6c 79 20 69 6e 74 65 72 63 68 61 6e 67  etely interchang
31030 65 61 62 6c 65 20 69 6e 20 53 51 4c 69 74 65 2e  eable in SQLite.
31040 0a 5e 28 54 68 65 20 22 43 52 4f 53 53 20 4a 4f  .^(The "CROSS JO
31050 49 4e 22 20 6a 6f 69 6e 20 6f 70 65 72 61 74 6f  IN" join operato
31060 72 20 70 72 6f 64 75 63 65 73 20 74 68 65 20 73  r produces the s
31070 61 6d 65 20 72 65 73 75 6c 74 20 61 73 20 74 68  ame result as th
31080 65 20 0a 22 49 4e 4e 45 52 20 4a 4f 49 4e 22 2c  e ."INNER JOIN",
31090 20 22 4a 4f 49 4e 22 20 61 6e 64 20 22 2c 22 20   "JOIN" and "," 
310a0 6f 70 65 72 61 74 6f 72 73 29 5e 2c 20 62 75 74  operators)^, but
310b0 20 69 73 20 0a 5b 43 52 4f 53 53 20 4a 4f 49 4e   is .[CROSS JOIN
310c0 7c 68 61 6e 64 6c 65 64 20 64 69 66 66 65 72 65  |handled differe
310d0 6e 74 6c 79 20 62 79 20 74 68 65 20 71 75 65 72  ntly by the quer
310e0 79 20 6f 70 74 69 6d 69 7a 65 72 5d 0a 69 6e 20  y optimizer].in 
310f0 74 68 61 74 20 69 74 20 70 72 65 76 65 6e 74 73  that it prevents
31100 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
31110 69 7a 65 72 20 66 72 6f 6d 20 72 65 6f 72 64 65  izer from reorde
31120 72 69 6e 67 0a 74 68 65 20 74 61 62 6c 65 73 20  ring.the tables 
31130 69 6e 20 74 68 65 20 6a 6f 69 6e 2e 20 20 41 6e  in the join.  An
31140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
31150 67 72 61 6d 6d 65 72 20 63 61 6e 20 75 73 65 20  grammer can use 
31160 74 68 65 20 43 52 4f 53 53 20 4a 4f 49 4e 20 0a  the CROSS JOIN .
31170 6f 70 65 72 61 74 6f 72 20 74 6f 20 64 69 72 65  operator to dire
31180 63 74 6c 79 20 69 6e 66 6c 75 65 6e 63 65 20 74  ctly influence t
31190 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61  he algorithm tha
311a0 74 20 69 73 20 63 68 6f 73 65 6e 20 74 6f 20 69  t is chosen to i
311b0 6d 70 6c 65 6d 65 6e 74 0a 74 68 65 20 53 45 4c  mplement.the SEL
311c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
311d0 41 76 6f 69 64 20 75 73 69 6e 67 20 43 52 4f 53  Avoid using CROS
311e0 53 20 4a 4f 49 4e 20 65 78 63 65 70 74 20 69 6e  S JOIN except in
311f0 20 73 70 65 63 69 66 69 63 20 73 69 74 75 61 74   specific situat
31200 69 6f 6e 73 20 0a 77 68 65 72 65 20 6d 61 6e 75  ions .where manu
31210 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f 66 20 74 68  al control of th
31220 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
31230 72 20 69 73 20 64 65 73 69 72 65 64 2e 20 20 41  r is desired.  A
31240 76 6f 69 64 20 75 73 69 6e 67 0a 43 52 4f 53 53  void using.CROSS
31250 20 4a 4f 49 4e 20 65 61 72 6c 79 20 69 6e 20 74   JOIN early in t
31260 68 65 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 6f  he development o
31270 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
31280 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 69 73 0a   as doing so is.
31290 61 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  a <a href="http:
312a0 2f 2f 63 32 2e 63 6f 6d 2f 63 67 69 2f 77 69 6b  //c2.com/cgi/wik
312b0 69 3f 50 72 65 6d 61 74 75 72 65 4f 70 74 69 6d  i?PrematureOptim
312c0 69 7a 61 74 69 6f 6e 22 3e 70 72 65 6d 61 74 75  ization">prematu
312d0 72 65 0a 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 3c  re.optimization<
312e0 2f 61 3e 2e 20 20 54 68 65 20 73 70 65 63 69 61  /a>.  The specia
312f0 6c 20 68 61 6e 64 6c 69 6e 67 20 6f 66 20 43 52  l handling of CR
31300 4f 53 53 20 4a 4f 49 4e 20 69 73 20 61 6e 20 53  OSS JOIN is an S
31310 51 4c 69 74 65 2d 73 70 65 63 69 66 69 63 0a 66  QLite-specific.f
31320 65 61 74 75 72 65 20 61 6e 64 20 69 73 20 6e 6f  eature and is no
31330 74 20 61 20 70 61 72 74 20 6f 66 20 73 74 61 6e  t a part of stan
31340 64 61 72 64 20 53 51 4c 2e 0a 20 20 20 20 20 20  dard SQL..      
31350 20 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d   ..<tcl>hd_fragm
31360 65 6e 74 20 77 68 65 72 65 63 6c 61 75 73 65 3c  ent whereclause<
31370 2f 74 63 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65  /tcl>.<tcl>hd_ke
31380 79 77 6f 72 64 73 20 7b 57 48 45 52 45 20 63 6c  ywords {WHERE cl
31390 61 75 73 65 7d 3c 2f 74 63 6c 3e 0a 3c 70 3e 3c  ause}</tcl>.<p><
313a0 62 3e 32 2e 20 57 48 45 52 45 20 63 6c 61 75 73  b>2. WHERE claus
313b0 65 20 66 69 6c 74 65 72 69 6e 67 2e 3c 2f 62 3e  e filtering.</b>
313c0 0a 0a 3c 70 3e 5e 28 49 66 20 61 20 57 48 45 52  ..<p>^(If a WHER
313d0 45 20 63 6c 61 75 73 65 20 69 73 20 73 70 65 63  E clause is spec
313e0 69 66 69 65 64 2c 20 74 68 65 20 57 48 45 52 45  ified, the WHERE
313f0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 65   expression is e
31400 76 61 6c 75 61 74 65 64 20 66 6f 72 20 0a 65 61  valuated for .ea
31410 63 68 20 72 6f 77 20 69 6e 20 74 68 65 20 69 6e  ch row in the in
31420 70 75 74 20 64 61 74 61 20 61 73 20 61 20 5b 62  put data as a [b
31430 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f  oolean expressio
31440 6e 5d 2e 20 4f 6e 6c 79 20 72 6f 77 73 20 66 6f  n]. Only rows fo
31450 72 20 77 68 69 63 68 20 74 68 65 0a 57 48 45 52  r which the.WHER
31460 45 20 63 6c 61 75 73 65 20 65 78 70 72 65 73 73  E clause express
31470 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 74 6f  ion evaluates to
31480 20 74 72 75 65 20 61 72 65 20 69 6e 63 6c 75 64   true are includ
31490 65 64 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61  ed from the data
314a0 73 65 74 20 62 65 66 6f 72 65 0a 63 6f 6e 74 69  set before.conti
314b0 6e 75 69 6e 67 2e 29 5e 20 20 52 6f 77 73 20 61  nuing.)^  Rows a
314c0 72 65 20 65 78 63 6c 75 64 65 64 20 66 72 6f 6d  re excluded from
314d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 66 20 74   the result if t
314e0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a  he WHERE clause.
314f0 65 76 61 6c 75 61 74 65 73 20 74 6f 20 65 69 74  evaluates to eit
31500 68 65 72 20 66 61 6c 73 65 20 6f 72 20 4e 55 4c  her false or NUL
31510 4c 2e 0a 0a 3c 70 3e 46 6f 72 20 61 20 4a 4f 49  L...<p>For a JOI
31520 4e 20 6f 72 20 49 4e 4e 45 52 20 4a 4f 49 4e 20  N or INNER JOIN 
31530 6f 72 20 43 52 4f 53 53 20 4a 4f 49 4e 2c 20 74  or CROSS JOIN, t
31540 68 65 72 65 20 69 73 20 6e 6f 20 64 69 66 66 65  here is no diffe
31550 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 0a 61  rence between .a
31560 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 70 72   constraint expr
31570 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20 57 48  ession in the WH
31580 45 52 45 20 63 6c 61 75 73 65 20 61 6e 64 20 6f  ERE clause and o
31590 6e 65 20 69 6e 20 74 68 65 20 4f 4e 20 63 6c 61  ne in the ON cla
315a0 75 73 65 2e 20 20 48 6f 77 65 76 65 72 2c 0a 66  use.  However,.f
315b0 6f 72 20 61 20 4c 45 46 54 20 4a 4f 49 4e 20 6f  or a LEFT JOIN o
315c0 72 20 4c 45 46 54 20 4f 55 54 45 52 20 4a 4f 49  r LEFT OUTER JOI
315d0 4e 2c 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  N, the differenc
315e0 65 20 69 73 20 76 65 72 79 20 69 6d 70 6f 72 74  e is very import
315f0 61 6e 74 2e 20 20 0a 49 6e 20 61 20 4c 45 46 54  ant.  .In a LEFT
31600 20 4a 4f 49 4e 2c 0a 74 68 65 20 65 78 74 72 61   JOIN,.the extra
31610 20 4e 55 4c 4c 20 72 6f 77 20 66 6f 72 20 74 68   NULL row for th
31620 65 20 72 69 67 68 74 2d 68 61 6e 64 20 74 61 62  e right-hand tab
31630 6c 65 20 69 73 20 61 64 64 65 64 20 61 66 74 65  le is added afte
31640 72 20 4f 4e 20 63 6c 61 75 73 65 20 70 72 6f 63  r ON clause proc
31650 65 73 73 69 6e 67 0a 62 75 74 20 62 65 66 6f 72  essing.but befor
31660 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 70  e WHERE clause p
31670 72 6f 63 65 73 73 69 6e 67 2e 20 20 41 20 63 6f  rocessing.  A co
31680 6e 73 74 72 61 69 6e 74 20 6f 66 20 74 68 65 20  nstraint of the 
31690 66 6f 72 6d 20 22 6c 65 66 74 2e 78 3d 72 69 67  form "left.x=rig
316a0 68 74 2e 79 22 0a 69 6e 20 61 6e 20 4f 4e 20 63  ht.y".in an ON c
316b0 6c 61 75 73 65 20 77 69 6c 6c 20 74 68 65 72 65  lause will there
316c0 66 6f 72 65 20 61 6c 6c 6f 77 20 74 68 72 6f 75  fore allow throu
316d0 67 68 20 74 68 65 20 61 64 64 65 64 20 61 6c 6c  gh the added all
316e0 2d 4e 55 4c 4c 20 72 6f 77 73 20 6f 66 20 74 68  -NULL rows of th
316f0 65 0a 72 69 67 68 74 20 74 61 62 6c 65 2e 20 20  e.right table.  
31700 42 75 74 20 69 66 20 74 68 61 74 20 73 61 6d 65  But if that same
31710 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 69   constraint is i
31720 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  n the WHERE clau
31730 73 65 20 61 20 4e 55 4c 4c 20 69 6e 0a 22 72 69  se a NULL in."ri
31740 67 68 74 2e 79 22 20 77 69 6c 6c 20 70 72 65 76  ght.y" will prev
31750 65 6e 74 20 74 68 65 20 65 78 70 72 65 73 73 69  ent the expressi
31760 6f 6e 20 22 6c 65 66 74 2e 78 3d 72 69 67 68 74  on "left.x=right
31770 2e 79 22 20 66 72 6f 6d 20 62 65 69 6e 67 20 74  .y" from being t
31780 72 75 65 2c 20 61 6e 64 0a 74 68 75 73 20 65 78  rue, and.thus ex
31790 63 6c 75 64 65 20 74 68 61 74 20 72 6f 77 20 66  clude that row f
317a0 72 6f 6d 20 74 68 65 20 6f 75 74 70 75 74 2e 0a  rom the output..
317b0 0a 3c 70 3e 3c 62 3e 33 2e 20 47 65 6e 65 72 61  .<p><b>3. Genera
317c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 65 74 20  tion of the set 
317d0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 2e 3c  of result rows.<
317e0 2f 62 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  /b>.<tcl>hd_frag
317f0 6d 65 6e 74 20 72 65 73 75 6c 74 73 65 74 3c 2f  ment resultset</
31800 74 63 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79  tcl>.<tcl>hd_key
31810 77 6f 72 64 73 20 7b 72 65 73 75 6c 74 2d 73 65  words {result-se
31820 74 20 65 78 70 72 65 73 73 69 6f 6e 73 7d 20 7b  t expressions} {
31830 47 52 4f 55 50 20 42 59 7d 3c 2f 74 63 6c 3e 0a  GROUP BY}</tcl>.
31840 0a 3c 70 3e 4f 6e 63 65 20 74 68 65 20 69 6e 70  .<p>Once the inp
31850 75 74 20 64 61 74 61 20 66 72 6f 6d 20 74 68 65  ut data from the
31860 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 68 61 73   FROM clause has
31870 20 62 65 65 6e 20 66 69 6c 74 65 72 65 64 20 62   been filtered b
31880 79 20 74 68 65 0a 57 48 45 52 45 20 63 6c 61 75  y the.WHERE clau
31890 73 65 20 65 78 70 72 65 73 73 69 6f 6e 20 28 69  se expression (i
318a0 66 20 61 6e 79 29 2c 20 74 68 65 20 73 65 74 20  f any), the set 
318b0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 66  of result rows f
318c0 6f 72 20 74 68 65 20 73 69 6d 70 6c 65 20 0a 53  or the simple .S
318d0 45 4c 45 43 54 20 61 72 65 20 63 61 6c 63 75 6c  ELECT are calcul
318e0 61 74 65 64 2e 20 45 78 61 63 74 6c 79 20 68 6f  ated. Exactly ho
318f0 77 20 74 68 69 73 20 69 73 20 64 6f 6e 65 20 64  w this is done d
31900 65 70 65 6e 64 73 20 6f 6e 20 77 68 65 74 68 65  epends on whethe
31910 72 20 74 68 65 20 73 69 6d 70 6c 65 20 0a 53 45  r the simple .SE
31920 4c 45 43 54 20 69 73 20 61 6e 20 61 67 67 72 65  LECT is an aggre
31930 67 61 74 65 20 6f 72 20 6e 6f 6e 2d 61 67 67 72  gate or non-aggr
31940 65 67 61 74 65 20 71 75 65 72 79 2c 20 61 6e 64  egate query, and
31950 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
31960 61 20 47 52 4f 55 50 0a 42 59 20 63 6c 61 75 73  a GROUP.BY claus
31970 65 20 77 61 73 20 73 70 65 63 69 66 69 65 64 2e  e was specified.
31980 0a 0a 3c 70 3e 20 54 68 65 20 6c 69 73 74 20 6f  ..<p> The list o
31990 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 62 65  f expressions be
319a0 74 77 65 65 6e 20 74 68 65 20 53 45 4c 45 43 54  tween the SELECT
319b0 20 61 6e 64 20 46 52 4f 4d 20 6b 65 79 77 6f 72   and FROM keywor
319c0 64 73 20 69 73 20 6b 6e 6f 77 6e 20 61 73 0a 74  ds is known as.t
319d0 68 65 20 72 65 73 75 6c 74 20 65 78 70 72 65 73  he result expres
319e0 73 69 6f 6e 20 6c 69 73 74 2e 20 20 5e 49 66 20  sion list.  ^If 
319f0 61 20 72 65 73 75 6c 74 20 65 78 70 72 65 73 73  a result express
31a00 69 6f 6e 20 69 73 20 74 68 65 20 73 70 65 63 69  ion is the speci
31a10 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 22 2a  al expression."*
31a20 22 20 74 68 65 6e 20 61 6c 6c 20 63 6f 6c 75 6d  " then all colum
31a30 6e 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  ns in the input 
31a40 64 61 74 61 20 61 72 65 20 73 75 62 73 74 69 74  data are substit
31a50 75 74 65 64 20 66 6f 72 20 74 68 61 74 20 6f 6e  uted for that on
31a60 65 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 5e 28  e expression..^(
31a70 49 66 20 74 68 65 20 65 78 70 72 65 73 73 69 6f  If the expressio
31a80 6e 20 69 73 20 74 68 65 20 61 6c 69 61 73 20 6f  n is the alias o
31a90 66 20 61 20 74 61 62 6c 65 20 6f 72 20 73 75 62  f a table or sub
31aa0 71 75 65 72 79 20 69 6e 20 74 68 65 20 46 52 4f  query in the FRO
31ab0 4d 20 63 6c 61 75 73 65 0a 66 6f 6c 6c 6f 77 65  M clause.followe
31ac0 64 20 62 79 20 22 2e 2a 22 20 74 68 65 6e 20 61  d by ".*" then a
31ad0 6c 6c 20 63 6f 6c 75 6d 6e 73 20 66 72 6f 6d 20  ll columns from 
31ae0 74 68 65 20 6e 61 6d 65 64 20 74 61 62 6c 65 20  the named table 
31af0 6f 72 20 73 75 62 71 75 65 72 79 20 61 72 65 0a  or subquery are.
31b00 73 75 62 73 74 69 74 75 74 65 64 20 66 6f 72 20  substituted for 
31b10 74 68 65 20 73 69 6e 67 6c 65 20 65 78 70 72 65  the single expre
31b20 73 73 69 6f 6e 2e 29 5e 20 5e 28 49 74 20 69 73  ssion.)^ ^(It is
31b30 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 75 73 65   an error to use
31b40 20 61 20 22 2a 22 20 6f 72 0a 22 61 6c 69 61 73   a "*" or."alias
31b50 2e 2a 22 20 65 78 70 72 65 73 73 69 6f 6e 20 69  .*" expression i
31b60 6e 20 61 6e 79 20 63 6f 6e 74 65 78 74 20 6f 74  n any context ot
31b70 68 65 72 20 74 68 61 6e 20 61 20 72 65 73 75 6c  her than a resul
31b80 74 20 65 78 70 72 65 73 73 69 6f 6e 20 6c 69 73  t expression lis
31b90 74 2e 29 5e 0a 5e 28 49 74 20 69 73 20 61 6c 73  t.)^.^(It is als
31ba0 6f 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 75 73  o an error to us
31bb0 65 20 61 20 22 2a 22 20 6f 72 20 22 61 6c 69 61  e a "*" or "alia
31bc0 73 2e 2a 22 20 65 78 70 72 65 73 73 69 6f 6e 20  s.*" expression 
31bd0 69 6e 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45  in a simple SELE
31be0 43 54 0a 71 75 65 72 79 20 74 68 61 74 20 64 6f  CT.query that do
31bf0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 20 46 52  es not have a FR
31c00 4f 4d 20 63 6c 61 75 73 65 2e 29 5e 0a 0a 3c 70  OM clause.)^..<p
31c10 3e 20 5e 28 54 68 65 20 6e 75 6d 62 65 72 20 6f  > ^(The number o
31c20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
31c30 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62   rows returned b
31c40 79 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45 43  y a simple SELEC
31c50 54 20 73 74 61 74 65 6d 65 6e 74 0a 69 73 20 65  T statement.is e
31c60 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
31c70 65 72 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  er of expression
31c80 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
31c90 65 78 70 72 65 73 73 69 6f 6e 20 6c 69 73 74 20  expression list 
31ca0 61 66 74 65 72 0a 73 75 62 73 74 69 74 75 74 69  after.substituti
31cb0 6f 6e 20 6f 66 20 2a 20 61 6e 64 20 61 6c 69 61  on of * and alia
31cc0 73 2e 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 2e  s.* expressions.
31cd0 29 5e 20 45 61 63 68 20 72 65 73 75 6c 74 20 72  )^ Each result r
31ce0 6f 77 20 69 73 20 63 61 6c 63 75 6c 61 74 65 64  ow is calculated
31cf0 20 62 79 0a 65 76 61 6c 75 61 74 69 6e 67 20 74   by.evaluating t
31d00 68 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  he expressions i
31d10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 65 78 70  n the result exp
31d20 72 65 73 73 69 6f 6e 20 6c 69 73 74 20 77 69 74  ression list wit
31d30 68 20 72 65 73 70 65 63 74 20 74 6f 20 61 0a 73  h respect to a.s
31d40 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 69 6e 70  ingle row of inp
31d50 75 74 20 64 61 74 61 20 6f 72 2c 20 66 6f 72 20  ut data or, for 
31d60 61 67 67 72 65 67 61 74 65 20 71 75 65 72 69 65  aggregate querie
31d70 73 2c 20 77 69 74 68 20 72 65 73 70 65 63 74 20  s, with respect 
31d80 74 6f 20 61 20 67 72 6f 75 70 0a 6f 66 20 72 6f  to a group.of ro
31d90 77 73 2e 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e  ws...<ul>.  <li>
31da0 3c 70 3e 5e 49 66 20 74 68 65 20 53 45 4c 45 43  <p>^If the SELEC
31db0 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 3c  T statement is <
31dc0 62 3e 61 20 6e 6f 6e 2d 61 67 67 72 65 67 61 74  b>a non-aggregat
31dd0 65 20 71 75 65 72 79 3c 2f 62 3e 2c 20 74 68 65  e query</b>, the
31de0 6e 20 0a 20 20 20 20 65 61 63 68 20 65 78 70 72  n .    each expr
31df0 65 73 73 69 6f 6e 20 69 6e 20 74 68 65 20 72 65  ession in the re
31e00 73 75 6c 74 20 65 78 70 72 65 73 73 69 6f 6e 20  sult expression 
31e10 6c 69 73 74 20 69 73 20 65 76 61 6c 75 61 74 65  list is evaluate
31e20 64 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 69  d for each row i
31e30 6e 0a 20 20 20 20 74 68 65 20 64 61 74 61 73 65  n.    the datase
31e40 74 20 66 69 6c 74 65 72 65 64 20 62 79 20 74 68  t filtered by th
31e50 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 2e 0a  e WHERE clause..
31e60 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74 68  .  <li><p>^If th
31e70 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
31e80 6e 74 20 69 73 20 3c 62 3e 61 6e 20 61 67 67 72  nt is <b>an aggr
31e90 65 67 61 74 65 20 71 75 65 72 79 20 77 69 74 68  egate query with
31ea0 6f 75 74 20 61 20 47 52 4f 55 50 0a 20 20 20 20  out a GROUP.    
31eb0 42 59 3c 2f 62 3e 20 63 6c 61 75 73 65 2c 20 74  BY</b> clause, t
31ec0 68 65 6e 20 65 61 63 68 20 61 67 67 72 65 67 61  hen each aggrega
31ed0 74 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e  te expression in
31ee0 20 74 68 65 20 72 65 73 75 6c 74 2d 73 65 74 20   the result-set 
31ef0 69 73 20 0a 20 20 20 20 65 76 61 6c 75 61 74 65  is .    evaluate
31f00 64 20 6f 6e 63 65 20 61 63 72 6f 73 73 20 74 68  d once across th
31f10 65 20 65 6e 74 69 72 65 20 64 61 74 61 73 65 74  e entire dataset
31f20 2e 20 5e 45 61 63 68 20 6e 6f 6e 2d 61 67 67 72  . ^Each non-aggr
31f30 65 67 61 74 65 20 65 78 70 72 65 73 73 69 6f 6e  egate expression
31f40 0a 20 20 20 20 69 6e 20 74 68 65 20 72 65 73 75  .    in the resu
31f50 6c 74 2d 73 65 74 20 69 73 20 65 76 61 6c 75 61  lt-set is evalua
31f60 74 65 64 20 6f 6e 63 65 20 66 6f 72 20 61 6e 20  ted once for an 
31f70 61 72 62 69 74 72 61 72 69 6c 79 20 73 65 6c 65  arbitrarily sele
31f80 63 74 65 64 20 72 6f 77 20 6f 66 0a 20 20 20 20  cted row of.    
31f90 74 68 65 20 64 61 74 61 73 65 74 2e 20 5e 54 68  the dataset. ^Th
31fa0 65 20 73 61 6d 65 20 61 72 62 69 74 72 61 72 69  e same arbitrari
31fb0 6c 79 20 73 65 6c 65 63 74 65 64 20 72 6f 77 20  ly selected row 
31fc0 69 73 20 75 73 65 64 20 66 6f 72 20 65 61 63 68  is used for each
31fd0 0a 20 20 20 20 6e 6f 6e 2d 61 67 67 72 65 67 61  .    non-aggrega
31fe0 74 65 20 65 78 70 72 65 73 73 69 6f 6e 2e 20 5e  te expression. ^
31ff0 4f 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 73  Or, if the datas
32000 65 74 20 63 6f 6e 74 61 69 6e 73 20 7a 65 72 6f  et contains zero
32010 20 72 6f 77 73 2c 20 74 68 65 6e 20 0a 20 20 20   rows, then .   
32020 20 65 61 63 68 20 6e 6f 6e 2d 61 67 67 72 65 67   each non-aggreg
32030 61 74 65 20 65 78 70 72 65 73 73 69 6f 6e 20 69  ate expression i
32040 73 20 65 76 61 6c 75 61 74 65 64 20 61 67 61 69  s evaluated agai
32050 6e 73 74 20 61 20 72 6f 77 20 63 6f 6e 73 69 73  nst a row consis
32060 74 69 6e 67 0a 20 20 20 20 65 6e 74 69 72 65 6c  ting.    entirel
32070 79 20 6f 66 20 4e 55 4c 4c 20 76 61 6c 75 65 73  y of NULL values
32080 2e 0a 0a 20 20 20 3c 70 3e 5e 54 68 65 20 73 69  ...   <p>^The si
32090 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75  ngle row of resu
320a0 6c 74 2d 73 65 74 20 64 61 74 61 20 63 72 65 61  lt-set data crea
320b0 74 65 64 20 62 79 20 65 76 61 6c 75 61 74 69 6e  ted by evaluatin
320c0 67 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  g the aggregate.
320d0 20 20 20 20 61 6e 64 20 6e 6f 6e 2d 61 67 67 72      and non-aggr
320e0 65 67 61 74 65 20 65 78 70 72 65 73 73 69 6f 6e  egate expression
320f0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2d  s in the result-
32100 73 65 74 20 66 6f 72 6d 73 20 74 68 65 20 72 65  set forms the re
32110 73 75 6c 74 20 6f 66 20 61 6e 0a 20 20 20 20 61  sult of an.    a
32120 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 77  ggregate query w
32130 69 74 68 6f 75 74 20 61 20 47 52 4f 55 50 20 42  ithout a GROUP B
32140 59 20 63 6c 61 75 73 65 2e 20 5e 41 6e 20 61 67  Y clause. ^An ag
32150 67 72 65 67 61 74 65 20 71 75 65 72 79 20 77 69  gregate query wi
32160 74 68 6f 75 74 20 61 0a 20 20 20 20 47 52 4f 55  thout a.    GROU
32170 50 20 42 59 20 63 6c 61 75 73 65 20 61 6c 77 61  P BY clause alwa
32180 79 73 20 72 65 74 75 72 6e 73 20 65 78 61 63 74  ys returns exact
32190 6c 79 20 6f 6e 65 20 72 6f 77 20 6f 66 20 64 61  ly one row of da
321a0 74 61 2c 20 65 76 65 6e 20 69 66 20 74 68 65 72  ta, even if ther
321b0 65 20 61 72 65 0a 20 20 20 20 7a 65 72 6f 20 72  e are.    zero r
321c0 6f 77 73 20 6f 66 20 69 6e 70 75 74 20 64 61 74  ows of input dat
321d0 61 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 28 49  a...  <li><p>^(I
321e0 66 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  f the SELECT sta
321f0 74 65 6d 65 6e 74 20 69 73 20 3c 62 3e 61 6e 20  tement is <b>an 
32200 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
32210 77 69 74 68 20 61 20 47 52 4f 55 50 0a 20 20 20  with a GROUP.   
32220 20 42 59 3c 2f 62 3e 20 63 6c 61 75 73 65 2c 20   BY</b> clause, 
32230 74 68 65 6e 20 65 61 63 68 20 6f 66 20 74 68 65  then each of the
32240 20 65 78 70 72 65 73 73 69 6f 6e 73 20 73 70 65   expressions spe
32250 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
32260 66 20 74 68 65 0a 20 20 20 20 47 52 4f 55 50 20  f the.    GROUP 
32270 42 59 20 63 6c 61 75 73 65 20 69 73 20 65 76 61  BY clause is eva
32280 6c 75 61 74 65 64 20 66 6f 72 20 65 61 63 68 20  luated for each 
32290 72 6f 77 20 6f 66 20 74 68 65 20 64 61 74 61 73  row of the datas
322a0 65 74 2e 20 45 61 63 68 20 72 6f 77 0a 20 20 20  et. Each row.   
322b0 20 69 73 20 74 68 65 6e 20 61 73 73 69 67 6e 65   is then assigne
322c0 64 20 74 6f 20 61 20 22 67 72 6f 75 70 22 20 62  d to a "group" b
322d0 61 73 65 64 20 6f 6e 20 74 68 65 20 72 65 73 75  ased on the resu
322e0 6c 74 73 3b 20 72 6f 77 73 20 66 6f 72 20 77 68  lts; rows for wh
322f0 69 63 68 0a 20 20 20 20 74 68 65 20 72 65 73 75  ich.    the resu
32300 6c 74 73 20 6f 66 20 65 76 61 6c 75 61 74 69 6e  lts of evaluatin
32310 67 20 74 68 65 20 47 52 4f 55 50 20 42 59 20 65  g the GROUP BY e
32320 78 70 72 65 73 73 69 6f 6e 73 20 61 72 65 20 74  xpressions are t
32330 68 65 20 73 61 6d 65 20 67 65 74 0a 20 20 20 20  he same get.    
32340 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20  assigned to the 
32350 73 61 6d 65 20 67 72 6f 75 70 2e 29 5e 20 5e 46  same group.)^ ^F
32360 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
32370 6f 66 20 67 72 6f 75 70 69 6e 67 20 72 6f 77 73  of grouping rows
32380 2c 20 4e 55 4c 4c 20 0a 20 20 20 20 76 61 6c 75  , NULL .    valu
32390 65 73 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65  es are considere
323a0 64 20 65 71 75 61 6c 2e 20 5e 54 68 65 20 75 73  d equal. ^The us
323b0 75 61 6c 20 72 75 6c 65 73 20 66 6f 72 20 5b 63  ual rules for [c
323c0 6f 6c 6c 61 74 69 6f 6e 7c 73 65 6c 65 63 74 69  ollation|selecti
323d0 6e 67 20 61 0a 20 20 20 20 63 6f 6c 6c 61 74 69  ng a.    collati
323e0 6f 6e 20 73 65 71 75 65 6e 63 65 5d 20 77 69 74  on sequence] wit
323f0 68 20 77 68 69 63 68 20 74 6f 20 63 6f 6d 70 61  h which to compa
32400 72 65 20 74 65 78 74 20 76 61 6c 75 65 73 20 61  re text values a
32410 70 70 6c 79 20 77 68 65 6e 20 65 76 61 6c 75 61  pply when evalua
32420 74 69 6e 67 0a 20 20 20 20 65 78 70 72 65 73 73  ting.    express
32430 69 6f 6e 73 20 69 6e 20 61 20 47 52 4f 55 50 20  ions in a GROUP 
32440 42 59 20 63 6c 61 75 73 65 2e 20 20 5e 54 68 65  BY clause.  ^The
32450 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20   expressions in 
32460 74 68 65 20 47 52 4f 55 50 20 42 59 20 63 6c 61  the GROUP BY cla
32470 75 73 65 0a 20 20 20 20 64 6f 20 3c 65 6d 3e 6e  use.    do <em>n
32480 6f 74 3c 2f 65 6d 3e 20 68 61 76 65 20 74 6f 20  ot</em> have to 
32490 62 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  be expressions t
324a0 68 61 74 20 61 70 70 65 61 72 20 69 6e 20 74 68  hat appear in th
324b0 65 20 72 65 73 75 6c 74 2e 20 5e 54 68 65 0a 20  e result. ^The. 
324c0 20 20 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69     expressions i
324d0 6e 20 61 20 47 52 4f 55 50 20 42 59 20 63 6c 61  n a GROUP BY cla
324e0 75 73 65 20 6d 61 79 20 6e 6f 74 20 62 65 20 61  use may not be a
324f0 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73 73  ggregate express
32500 69 6f 6e 73 2e 0a 0a 20 20 20 20 3c 70 3e 5e 28  ions...    <p>^(
32510 49 66 20 61 20 48 41 56 49 4e 47 20 63 6c 61 75  If a HAVING clau
32520 73 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  se is specified,
32530 20 69 74 20 69 73 20 65 76 61 6c 75 61 74 65 64   it is evaluated
32540 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 67   once for each g
32550 72 6f 75 70 20 0a 20 20 20 20 6f 66 20 72 6f 77  roup .    of row
32560 73 20 61 73 20 61 20 5b 62 6f 6f 6c 65 61 6e 20  s as a [boolean 
32570 65 78 70 72 65 73 73 69 6f 6e 5d 2e 20 49 66 20  expression]. If 
32580 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 76  the result of ev
32590 61 6c 75 61 74 69 6e 67 20 74 68 65 0a 20 20 20  aluating the.   
325a0 20 48 41 56 49 4e 47 20 63 6c 61 75 73 65 20 69   HAVING clause i
325b0 73 20 66 61 6c 73 65 2c 20 74 68 65 20 67 72 6f  s false, the gro
325c0 75 70 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  up is discarded.
325d0 29 5e 20 5e 49 66 20 74 68 65 20 48 41 56 49 4e  )^ ^If the HAVIN
325e0 47 20 63 6c 61 75 73 65 20 69 73 0a 20 20 20 20  G clause is.    
325f0 61 6e 20 61 67 67 72 65 67 61 74 65 20 65 78 70  an aggregate exp
32600 72 65 73 73 69 6f 6e 2c 20 69 74 20 69 73 20 65  ression, it is e
32610 76 61 6c 75 61 74 65 64 20 61 63 72 6f 73 73 20  valuated across 
32620 61 6c 6c 20 72 6f 77 73 20 69 6e 20 74 68 65 20  all rows in the 
32630 67 72 6f 75 70 2e 20 5e 49 66 0a 20 20 20 20 61  group. ^If.    a
32640 20 48 41 56 49 4e 47 20 63 6c 61 75 73 65 20 69   HAVING clause i
32650 73 20 61 20 6e 6f 6e 2d 61 67 67 72 65 67 61 74  s a non-aggregat
32660 65 20 65 78 70 72 65 73 73 69 6f 6e 2c 20 69 74  e expression, it
32670 20 69 73 20 65 76 61 6c 75 61 74 65 64 20 77 69   is evaluated wi
32680 74 68 20 72 65 73 70 65 63 74 0a 20 20 20 20 74  th respect.    t
32690 6f 20 61 6e 20 61 72 62 69 74 72 61 72 69 6c 79  o an arbitrarily
326a0 20 73 65 6c 65 63 74 65 64 20 72 6f 77 20 66 72   selected row fr
326b0 6f 6d 20 74 68 65 20 67 72 6f 75 70 2e 20 20 5e  om the group.  ^
326c0 54 68 65 20 48 41 56 49 4e 47 20 65 78 70 72 65  The HAVING expre
326d0 73 73 69 6f 6e 20 6d 61 79 0a 20 20 20 20 72 65  ssion may.    re
326e0 66 65 72 20 74 6f 20 76 61 6c 75 65 73 2c 20 65  fer to values, e
326f0 76 65 6e 20 61 67 67 72 65 67 61 74 65 20 66 75  ven aggregate fu
32700 6e 63 74 69 6f 6e 73 2c 20 74 68 61 74 20 61 72  nctions, that ar
32710 65 20 6e 6f 74 20 69 6e 20 74 68 65 20 72 65 73  e not in the res
32720 75 6c 74 2e 3c 2f 70 3e 0a 0a 20 20 20 20 3c 70  ult.</p>..    <p
32730 3e 5e 45 61 63 68 20 65 78 70 72 65 73 73 69 6f  >^Each expressio
32740 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2d  n in the result-
32750 73 65 74 20 69 73 20 74 68 65 6e 20 65 76 61 6c  set is then eval
32760 75 61 74 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  uated once for e
32770 61 63 68 0a 20 20 20 20 67 72 6f 75 70 20 6f 66  ach.    group of
32780 20 72 6f 77 73 2e 20 5e 49 66 20 74 68 65 20 65   rows. ^If the e
32790 78 70 72 65 73 73 69 6f 6e 20 69 73 20 61 6e 20  xpression is an 
327a0 61 67 67 72 65 67 61 74 65 20 65 78 70 72 65 73  aggregate expres
327b0 73 69 6f 6e 2c 20 69 74 20 69 73 20 0a 20 20 20  sion, it is .   
327c0 20 65 76 61 6c 75 61 74 65 64 20 61 63 72 6f 73   evaluated acros
327d0 73 20 61 6c 6c 20 72 6f 77 73 20 69 6e 20 74 68  s all rows in th
327e0 65 20 67 72 6f 75 70 2e 20 5e 4f 74 68 65 72 77  e group. ^Otherw
327f0 69 73 65 2c 20 69 74 20 69 73 20 65 76 61 6c 75  ise, it is evalu
32800 61 74 65 64 20 61 67 61 69 6e 73 74 0a 20 20 20  ated against.   
32810 20 61 20 73 69 6e 67 6c 65 20 61 72 62 69 74 72   a single arbitr
32820 61 72 69 6c 79 20 63 68 6f 73 65 6e 20 72 6f 77  arily chosen row
32830 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
32840 20 67 72 6f 75 70 2e 20 5e 49 66 20 74 68 65 72   group. ^If ther
32850 65 20 69 73 20 6d 6f 72 65 0a 20 20 20 20 74 68  e is more.    th
32860 61 6e 20 6f 6e 65 20 6e 6f 6e 2d 61 67 67 72 65  an one non-aggre
32870 67 61 74 65 20 65 78 70 72 65 73 73 69 6f 6e 20  gate expression 
32880 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2d 73 65  in the result-se
32890 74 2c 20 74 68 65 6e 20 61 6c 6c 20 73 75 63 68  t, then all such
328a0 0a 20 20 20 20 65 78 70 72 65 73 73 69 6f 6e 73  .    expressions
328b0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 66   are evaluated f
328c0 6f 72 20 74 68 65 20 73 61 6d 65 20 72 6f 77 2e  or the same row.
328d0 0a 0a 20 20 20 20 3c 70 3e 5e 45 61 63 68 20 67  ..    <p>^Each g
328e0 72 6f 75 70 20 6f 66 20 69 6e 70 75 74 20 64 61  roup of input da
328f0 74 61 73 65 74 20 72 6f 77 73 20 63 6f 6e 74 72  taset rows contr
32900 69 62 75 74 65 73 20 61 20 73 69 6e 67 6c 65 20  ibutes a single 
32910 72 6f 77 20 74 6f 20 74 68 65 20 0a 20 20 20 20  row to the .    
32920 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  set of result ro
32930 77 73 2e 20 5e 53 75 62 6a 65 63 74 20 74 6f 20  ws. ^Subject to 
32940 66 69 6c 74 65 72 69 6e 67 20 61 73 73 6f 63 69  filtering associ
32950 61 74 65 64 20 77 69 74 68 20 74 68 65 20 44 49  ated with the DI
32960 53 54 49 4e 43 54 0a 20 20 20 20 6b 65 79 77 6f  STINCT.    keywo
32970 72 64 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rd, the number o
32980 66 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20  f rows returned 
32990 62 79 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  by an aggregate 
329a0 71 75 65 72 79 20 77 69 74 68 20 61 20 47 52 4f  query with a GRO
329b0 55 50 0a 20 20 20 20 42 59 20 63 6c 61 75 73 65  UP.    BY clause
329c0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
329d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 67 72  the number of gr
329e0 6f 75 70 73 20 6f 66 20 72 6f 77 73 20 70 72 6f  oups of rows pro
329f0 64 75 63 65 64 20 62 79 20 61 70 70 6c 79 69 6e  duced by applyin
32a00 67 0a 20 20 20 20 74 68 65 20 47 52 4f 55 50 20  g.    the GROUP 
32a10 42 59 20 61 6e 64 20 48 41 56 49 4e 47 20 63 6c  BY and HAVING cl
32a20 61 75 73 65 73 20 74 6f 20 74 68 65 20 66 69 6c  auses to the fil
32a30 74 65 72 65 64 20 69 6e 70 75 74 20 64 61 74 61  tered input data
32a40 73 65 74 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c  set..</ul>..<tcl
32a50 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 62 61 72  >hd_fragment bar
32a60 65 61 67 67 20 7b 62 61 72 65 20 61 67 67 72 65  eagg {bare aggre
32a70 67 61 74 65 20 74 65 72 6d 73 7d 3c 2f 74 63 6c  gate terms}</tcl
32a80 3e 0a 3c 70 3e 3c 62 3e 53 69 64 65 20 6e 6f 74  >.<p><b>Side not
32a90 65 3a 20 42 61 72 65 20 63 6f 6c 75 6d 6e 73 20  e: Bare columns 
32aa0 69 6e 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  in an aggregate 
32ab0 71 75 65 72 69 65 73 2e 3c 2f 62 3e 0a 54 68 65  queries.</b>.The
32ac0 20 75 73 75 61 6c 20 63 61 73 65 20 69 73 20 74   usual case is t
32ad0 68 61 74 20 61 6c 6c 20 63 6f 6c 75 6d 6e 20 6e  hat all column n
32ae0 61 6d 65 73 20 69 6e 20 61 6e 20 61 67 67 72 65  ames in an aggre
32af0 67 61 74 65 20 71 75 65 72 79 20 61 72 65 20 65  gate query are e
32b00 69 74 68 65 72 0a 61 72 67 75 6d 65 6e 74 73 20  ither.arguments 
32b10 74 6f 20 5b 61 67 67 66 75 6e 63 7c 61 67 67 72  to [aggfunc|aggr
32b20 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 73 5d  egate functions]
32b30 20 6f 72 20 65 6c 73 65 20 61 70 70 65 61 72 20   or else appear 
32b40 69 6e 20 74 68 65 20 47 52 4f 55 50 20 42 59 20  in the GROUP BY 
32b50 63 6c 61 75 73 65 2e 0a 41 20 72 65 73 75 6c 74  clause..A result
32b60 20 63 6f 6c 75 6d 6e 20 77 68 69 63 68 20 63 6f   column which co
32b70 6e 74 61 69 6e 73 20 61 20 63 6f 6c 75 6d 6e 20  ntains a column 
32b80 6e 61 6d 65 20 74 68 61 74 20 69 73 20 6e 6f 74  name that is not
32b90 20 77 69 74 68 69 6e 20 61 6e 0a 61 67 67 72 65   within an.aggre
32ba0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 6e  gate function an
32bb0 64 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  d that does not 
32bc0 61 70 70 65 61 72 20 69 6e 20 74 68 65 20 47 52  appear in the GR
32bd0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 20 28 69  OUP BY clause (i
32be0 66 0a 6f 6e 65 20 65 78 69 73 74 73 29 20 69 73  f.one exists) is
32bf0 20 63 61 6c 6c 65 64 20 61 20 22 62 61 72 65 22   called a "bare"
32c00 20 63 6f 6c 75 6d 6e 2e 0a 45 78 61 6d 70 6c 65   column..Example
32c10 3a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  :.<blockquote><p
32c20 72 65 3e 0a 53 45 4c 45 43 54 20 61 2c 20 62 2c  re>.SELECT a, b,
32c30 20 73 75 6d 28 63 29 20 46 52 4f 4d 20 74 61 62   sum(c) FROM tab
32c40 31 20 47 52 4f 55 50 20 42 59 20 61 3b 0a 3c 2f  1 GROUP BY a;.</
32c50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
32c60 3e 0a 3c 70 3e 49 6e 20 74 68 65 20 71 75 65 72  >.<p>In the quer
32c70 79 20 61 62 6f 76 65 2c 20 74 68 65 20 22 61 22  y above, the "a"
32c80 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
32c90 6f 66 20 74 68 65 20 47 52 4f 55 50 20 42 59 20  of the GROUP BY 
32ca0 63 6c 61 75 73 65 0a 61 6e 64 20 73 6f 20 65 61  clause.and so ea
32cb0 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 6f 75  ch row of the ou
32cc0 74 70 75 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  tput contains on
32cd0 65 20 6f 66 20 74 68 65 20 64 69 73 74 69 6e 63  e of the distinc
32ce0 74 20 76 61 6c 75 65 73 20 66 6f 72 0a 22 61 22  t values for."a"
32cf0 2e 20 20 54 68 65 20 22 63 22 20 63 6f 6c 75 6d  .  The "c" colum
32d00 6e 20 69 73 20 63 6f 6e 74 61 69 6e 65 64 20 77  n is contained w
32d10 69 74 68 69 6e 20 74 68 65 20 5b 73 75 6d 28 29  ithin the [sum()
32d20 5d 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  ] aggregate func
32d30 74 69 6f 6e 0a 61 6e 64 20 73 6f 20 74 68 61 74  tion.and so that
32d40 20 6f 75 74 70 75 74 20 63 6f 6c 75 6d 6e 20 69   output column i
32d50 73 20 74 68 65 20 73 75 6d 20 6f 66 20 61 6c 6c  s the sum of all
32d60 20 22 63 22 20 76 61 6c 75 65 73 20 69 6e 20 72   "c" values in r
32d70 6f 77 73 20 74 68 61 74 0a 68 61 76 65 20 74 68  ows that.have th
32d80 65 20 73 61 6d 65 20 76 61 6c 75 65 20 66 6f 72  e same value for
32d90 20 22 61 22 2e 20 20 42 75 74 20 77 68 61 74 20   "a".  But what 
32da0 69 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  is the result of
32db0 20 74 68 65 20 62 61 72 65 20 0a 63 6f 6c 75 6d   the bare .colum
32dc0 6e 20 22 62 22 3f 20 54 68 65 20 61 6e 73 77 65  n "b"? The answe
32dd0 72 20 69 73 20 74 68 61 74 20 74 68 65 20 22 62  r is that the "b
32de0 22 20 72 65 73 75 6c 74 20 77 69 6c 6c 20 62 65  " result will be
32df0 20 74 68 65 0a 76 61 6c 75 65 20 66 6f 72 20 22   the.value for "
32e00 62 22 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  b" in one of the
32e10 20 69 6e 70 75 74 20 72 6f 77 73 20 74 68 61 74   input rows that
32e20 20 66 6f 72 6d 20 74 68 65 20 61 67 67 72 65 67   form the aggreg
32e30 61 74 65 2e 0a 54 68 65 20 70 72 6f 62 6c 65 6d  ate..The problem
32e40 20 69 73 20 74 68 61 74 20 79 6f 75 20 75 73 75   is that you usu
32e50 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6b 6e 6f 77  ally do not know
32e60 20 77 68 69 63 68 20 69 6e 70 75 74 20 72 6f 77   which input row
32e70 20 69 73 20 75 73 65 64 0a 74 6f 20 63 6f 6d 70   is used.to comp
32e80 75 74 65 20 22 62 22 2c 20 61 6e 64 20 73 6f 20  ute "b", and so 
32e90 69 6e 20 6d 61 6e 79 20 63 61 73 65 73 20 74 68  in many cases th
32ea0 65 20 76 61 6c 75 65 20 66 6f 72 20 22 62 22 20  e value for "b" 
32eb0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 3c 2f  is undefined..</
32ec0 70 3e 0a 3c 70 3e 0a 53 70 65 63 69 61 6c 20 70  p>.<p>.Special p
32ed0 72 6f 63 65 73 73 69 6e 67 20 6f 63 63 75 72 73  rocessing occurs
32ee0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
32ef0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ate function is 
32f00 0a 65 69 74 68 65 72 20 5b 6d 61 78 41 67 67 46  .either [maxAggF
32f10 75 6e 63 7c 6d 69 6e 28 29 5d 20 6f 72 20 5b 6d  unc|min()] or [m
32f20 69 6e 41 67 67 46 75 6e 63 7c 6d 61 78 28 29 5d  inAggFunc|max()]
32f30 2e 20 20 45 78 61 6d 70 6c 65 3a 0a 3c 62 6c 6f  .  Example:.<blo
32f40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53 45  ckquote><pre>.SE
32f50 4c 45 43 54 20 61 2c 20 62 2c 20 6d 61 78 28 63  LECT a, b, max(c
32f60 29 20 46 52 4f 4d 20 74 61 62 31 20 47 52 4f 55  ) FROM tab1 GROU
32f70 50 20 42 59 20 61 3b 0a 3c 2f 70 72 65 3e 3c 2f  P BY a;.</pre></
32f80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 57 68 65 6e  blockquote>.When
32f90 20 74 68 65 20 5b 6d 61 78 41 67 67 46 75 6e 63   the [maxAggFunc
32fa0 7c 6d 69 6e 28 29 5d 20 6f 72 20 5b 6d 69 6e 41  |min()] or [minA
32fb0 67 67 46 75 6e 63 7c 6d 61 78 28 29 5d 20 61 67  ggFunc|max()] ag
32fc0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32fd0 73 20 0a 61 72 65 20 75 73 65 64 20 69 6e 20 61  s .are used in a
32fe0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
32ff0 79 2c 20 61 6c 6c 20 62 61 72 65 20 63 6f 6c 75  y, all bare colu
33000 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
33010 74 20 73 65 74 20 0a 74 61 6b 65 20 76 61 6c 75  t set .take valu
33020 65 73 20 66 72 6f 6d 20 74 68 65 20 69 6e 70 75  es from the inpu
33030 74 0a 72 6f 77 20 77 68 69 63 68 20 61 6c 73 6f  t.row which also
33040 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 6d 69   contains the mi
33050 6e 69 6d 75 6d 20 6f 72 20 6d 61 78 69 6d 75 6d  nimum or maximum
33060 2e 20 20 53 6f 20 69 6e 20 74 68 65 20 71 75 65  .  So in the que
33070 72 79 0a 61 62 6f 76 65 2c 20 74 68 65 20 76 61  ry.above, the va
33080 6c 75 65 20 6f 66 20 74 68 65 20 22 62 22 20 63  lue of the "b" c
33090 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 6f 75 74  olumn in the out
330a0 70 75 74 20 77 69 6c 6c 20 62 65 20 74 68 65 20  put will be the 
330b0 76 61 6c 75 65 20 6f 66 0a 74 68 65 20 22 62 22  value of.the "b"
330c0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 69   column in the i
330d0 6e 70 75 74 20 72 6f 77 20 74 68 61 74 20 68 61  nput row that ha
330e0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 22 63  s the largest "c
330f0 22 20 76 61 6c 75 65 2e 0a 54 68 65 72 65 20 69  " value..There i
33100 73 20 73 74 69 6c 6c 20 61 6e 20 61 6d 62 69 67  s still an ambig
33110 75 69 74 79 20 69 66 20 74 77 6f 20 6f 72 20 6d  uity if two or m
33120 6f 72 65 20 6f 66 20 74 68 65 20 69 6e 70 75 74  ore of the input
33130 20 72 6f 77 73 20 68 61 76 65 20 74 68 65 0a 73   rows have the.s
33140 61 6d 65 20 6d 69 6e 69 6d 75 6d 20 6f 72 20 6d  ame minimum or m
33150 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 72 20  aximum value or 
33160 69 66 20 74 68 65 20 71 75 65 72 79 20 63 6f 6e  if the query con
33170 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20  tains more than 
33180 6f 6e 65 0a 6d 69 6e 28 29 20 61 6e 64 2f 6f 72  one.min() and/or
33190 20 6d 61 78 28 29 20 61 67 67 72 65 67 61 74 65   max() aggregate
331a0 20 66 75 6e 63 74 69 6f 6e 2e 20 4f 6e 6c 79 20   function. Only 
331b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 6d 69  the built-in [mi
331c0 6e 41 67 67 46 75 6e 63 7c 6d 69 6e 28 29 5d 20  nAggFunc|min()] 
331d0 0a 61 6e 64 20 5b 6d 61 78 41 67 67 46 75 6e 63  .and [maxAggFunc
331e0 7c 6d 61 78 28 29 5d 20 66 75 6e 63 74 69 6f 6e  |max()] function
331f0 73 20 77 6f 72 6b 20 74 68 69 73 20 77 61 79 2e  s work this way.
33200 0a 3c 2f 70 3e 0a 0a 3c 70 3e 3c 62 3e 34 2e 20  .</p>..<p><b>4. 
33210 52 65 6d 6f 76 61 6c 20 6f 66 20 64 75 70 6c 69  Removal of dupli
33220 63 61 74 65 20 72 6f 77 73 20 28 44 49 53 54 49  cate rows (DISTI
33230 4e 43 54 20 70 72 6f 63 65 73 73 69 6e 67 29 2e  NCT processing).
33240 3c 2f 62 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  </b>.<tcl>hd_fra
33250 67 6d 65 6e 74 20 64 69 73 74 69 6e 63 74 3c 2f  gment distinct</
33260 74 63 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79  tcl>.<tcl>hd_key
33270 77 6f 72 64 73 20 7b 44 49 53 54 49 4e 43 54 7d  words {DISTINCT}
33280 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e 4f 6e 65 20  </tcl>..<p>^One 
33290 6f 66 20 74 68 65 20 41 4c 4c 20 6f 72 20 44 49  of the ALL or DI
332a0 53 54 49 4e 43 54 20 6b 65 79 77 6f 72 64 73 20  STINCT keywords 
332b0 6d 61 79 20 66 6f 6c 6c 6f 77 20 74 68 65 20 53  may follow the S
332c0 45 4c 45 43 54 20 6b 65 79 77 6f 72 64 20 69 6e  ELECT keyword in
332d0 20 61 20 0a 73 69 6d 70 6c 65 20 53 45 4c 45 43   a .simple SELEC
332e0 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 49 66  T statement. ^If
332f0 20 74 68 65 20 73 69 6d 70 6c 65 20 53 45 4c 45   the simple SELE
33300 43 54 20 69 73 20 61 20 53 45 4c 45 43 54 20 41  CT is a SELECT A
33310 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 65 6e 74  LL, then the.ent
33320 69 72 65 20 73 65 74 20 6f 66 20 72 65 73 75 6c  ire set of resul
33330 74 20 72 6f 77 73 20 61 72 65 20 72 65 74 75 72  t rows are retur
33340 6e 65 64 20 62 79 20 74 68 65 20 53 45 4c 45 43  ned by the SELEC
33350 54 2e 20 5e 49 66 20 6e 65 69 74 68 65 72 20 41  T. ^If neither A
33360 4c 4c 20 6f 72 0a 44 49 53 54 49 4e 43 54 20 61  LL or.DISTINCT a
33370 72 65 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e  re present, then
33380 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
33390 20 61 73 20 69 66 20 41 4c 4c 20 77 65 72 65 20   as if ALL were 
333a0 73 70 65 63 69 66 69 65 64 2e 20 0a 5e 49 66 20  specified. .^If 
333b0 74 68 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43  the simple SELEC
333c0 54 20 69 73 20 61 20 53 45 4c 45 43 54 20 44 49  T is a SELECT DI
333d0 53 54 49 4e 43 54 2c 20 74 68 65 6e 20 64 75 70  STINCT, then dup
333e0 6c 69 63 61 74 65 20 72 6f 77 73 20 61 72 65 20  licate rows are 
333f0 72 65 6d 6f 76 65 64 0a 66 72 6f 6d 20 74 68 65  removed.from the
33400 20 73 65 74 20 6f 66 20 72 65 73 75 6c 74 20 72   set of result r
33410 6f 77 73 20 62 65 66 6f 72 65 20 69 74 20 69 73  ows before it is
33420 20 72 65 74 75 72 6e 65 64 2e 20 5e 46 6f 72 20   returned. ^For 
33430 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 0a  the purposes of.
33440 64 65 74 65 63 74 69 6e 67 20 64 75 70 6c 69 63  detecting duplic
33450 61 74 65 20 72 6f 77 73 2c 20 74 77 6f 20 4e 55  ate rows, two NU
33460 4c 4c 20 76 61 6c 75 65 73 20 61 72 65 20 63 6f  LL values are co
33470 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 65  nsidered to be e
33480 71 75 61 6c 2e 20 5e 54 68 65 0a 5b 68 6f 77 20  qual. ^The.[how 
33490 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 64 65 74  collation is det
334a0 65 72 6d 69 6e 65 64 7c 75 73 75 61 6c 20 72 75  ermined|usual ru
334b0 6c 65 73 5d 20 61 70 70 6c 79 20 66 6f 72 20 73  les] apply for s
334c0 65 6c 65 63 74 69 6e 67 20 61 20 63 6f 6c 6c 61  electing a colla
334d0 74 69 6f 6e 0a 73 65 71 75 65 6e 63 65 20 74 6f  tion.sequence to
334e0 20 63 6f 6d 70 61 72 65 20 74 65 78 74 20 76 61   compare text va
334f0 6c 75 65 73 2e 0a 0a 3c 74 63 6c 3e 0a 68 64 5f  lues...<tcl>.hd_
33500 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 75 6e  fragment compoun
33510 64 20 7b 63 6f 6d 70 6f 75 6e 64 20 73 65 6c 65  d {compound sele
33520 63 74 7d 20 7b 63 6f 6d 70 6f 75 6e 64 20 71 75  ct} {compound qu
33530 65 72 79 7d 20 7b 63 6f 6d 70 6f 75 6e 64 20 53  ery} {compound S
33540 45 4c 45 43 54 7d 20 7b 63 6f 6d 70 6f 75 6e 64  ELECT} {compound
33550 20 53 45 4c 45 43 54 73 7d 0a 3c 2f 74 63 6c 3e   SELECTs}.</tcl>
33560 0a 3c 68 33 3e 43 6f 6d 70 6f 75 6e 64 20 53 65  .<h3>Compound Se
33570 6c 65 63 74 20 53 74 61 74 65 6d 65 6e 74 73 3c  lect Statements<
33580 2f 68 33 3e 0a 0a 3c 70 3e 54 77 6f 20 6f 72 20  /h3>..<p>Two or 
33590 6d 6f 72 65 20 5b 73 69 6d 70 6c 65 20 53 45 4c  more [simple SEL
335a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ECT] statements 
335b0 6d 61 79 20 62 65 20 63 6f 6e 6e 65 63 74 65 64  may be connected
335c0 20 74 6f 67 65 74 68 65 72 20 74 6f 20 66 6f 72   together to for
335d0 6d 0a 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  m.a compound SEL
335e0 45 43 54 20 75 73 69 6e 67 20 74 68 65 20 55 4e  ECT using the UN
335f0 49 4f 4e 2c 20 55 4e 49 4f 4e 20 41 4c 4c 2c 20  ION, UNION ALL, 
33600 49 4e 54 45 52 53 45 43 54 20 6f 72 20 45 58 43  INTERSECT or EXC
33610 45 50 54 20 6f 70 65 72 61 74 6f 72 2c 0a 61 73  EPT operator,.as
33620 20 73 68 6f 77 6e 20 62 79 20 74 68 65 20 66 6f   shown by the fo
33630 6c 6c 6f 77 69 6e 67 20 64 69 61 67 72 61 6d 3a  llowing diagram:
33640 0a 0a 3c 74 63 6c 3e 0a 52 65 63 75 72 73 69 76  ..<tcl>.Recursiv
33650 65 42 75 62 62 6c 65 44 69 61 67 72 61 6d 20 63  eBubbleDiagram c
33660 6f 6d 70 6f 75 6e 64 2d 73 65 6c 65 63 74 2d 73  ompound-select-s
33670 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c 70 3e 5e  tmt.</tcl>..<p>^
33680 49 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  In a compound SE
33690 4c 45 43 54 2c 20 61 6c 6c 20 74 68 65 20 63 6f  LECT, all the co
336a0 6e 73 74 69 74 75 65 6e 74 20 53 45 4c 45 43 54  nstituent SELECT
336b0 73 20 6d 75 73 74 20 72 65 74 75 72 6e 20 74 68  s must return th
336c0 65 20 73 61 6d 65 20 0a 6e 75 6d 62 65 72 20 6f  e same .number o
336d0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
336e0 2e 20 5e 41 73 20 74 68 65 20 63 6f 6d 70 6f 6e  . ^As the compon
336f0 65 6e 74 73 20 6f 66 20 61 20 63 6f 6d 70 6f 75  ents of a compou
33700 6e 64 20 53 45 4c 45 43 54 20 6d 75 73 74 0a 62  nd SELECT must.b
33710 65 20 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 20  e simple SELECT 
33720 73 74 61 74 65 6d 65 6e 74 73 2c 20 74 68 65 79  statements, they
33730 20 6d 61 79 20 6e 6f 74 20 63 6f 6e 74 61 69 6e   may not contain
33740 20 5b 4f 52 44 45 52 20 42 59 5d 20 6f 72 20 5b   [ORDER BY] or [
33750 4c 49 4d 49 54 5d 20 63 6c 61 75 73 65 73 2e 0a  LIMIT] clauses..
33760 5e 5b 4f 52 44 45 52 20 42 59 5d 20 61 6e 64 20  ^[ORDER BY] and 
33770 5b 4c 49 4d 49 54 5d 20 63 6c 61 75 73 65 73 20  [LIMIT] clauses 
33780 6d 61 79 20 6f 6e 6c 79 20 6f 63 63 75 72 20 61  may only occur a
33790 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
337a0 20 65 6e 74 69 72 65 20 63 6f 6d 70 6f 75 6e 64   entire compound
337b0 0a 53 45 4c 45 43 54 2c 20 61 6e 64 20 74 68 65  .SELECT, and the
337c0 6e 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  n only if the fi
337d0 6e 61 6c 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  nal element of t
337e0 68 65 20 63 6f 6d 70 6f 75 6e 64 20 69 73 20 6e  he compound is n
337f0 6f 74 20 61 20 5b 56 41 4c 55 45 53 5d 20 63 6c  ot a [VALUES] cl
33800 61 75 73 65 2e 0a 0a 3c 70 3e 5e 41 20 63 6f 6d  ause...<p>^A com
33810 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 63 72 65  pound SELECT cre
33820 61 74 65 64 20 75 73 69 6e 67 20 55 4e 49 4f 4e  ated using UNION
33830 20 41 4c 4c 20 6f 70 65 72 61 74 6f 72 20 72 65   ALL operator re
33840 74 75 72 6e 73 20 61 6c 6c 20 74 68 65 20 72 6f  turns all the ro
33850 77 73 0a 66 72 6f 6d 20 74 68 65 20 53 45 4c 45  ws.from the SELE
33860 43 54 20 74 6f 20 74 68 65 20 6c 65 66 74 20 6f  CT to the left o
33870 66 20 74 68 65 20 55 4e 49 4f 4e 20 41 4c 4c 20  f the UNION ALL 
33880 6f 70 65 72 61 74 6f 72 2c 20 61 6e 64 20 61 6c  operator, and al
33890 6c 20 74 68 65 20 72 6f 77 73 0a 66 72 6f 6d 20  l the rows.from 
338a0 74 68 65 20 53 45 4c 45 43 54 20 74 6f 20 74 68  the SELECT to th
338b0 65 20 72 69 67 68 74 20 6f 66 20 69 74 2e 20 5e  e right of it. ^
338c0 54 68 65 20 55 4e 49 4f 4e 20 6f 70 65 72 61 74  The UNION operat
338d0 6f 72 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  or works the sam
338e0 65 20 77 61 79 20 61 73 0a 55 4e 49 4f 4e 20 41  e way as.UNION A
338f0 4c 4c 2c 20 65 78 63 65 70 74 20 74 68 61 74 20  LL, except that 
33900 64 75 70 6c 69 63 61 74 65 20 72 6f 77 73 20 61  duplicate rows a
33910 72 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20  re removed from 
33920 74 68 65 20 66 69 6e 61 6c 20 72 65 73 75 6c 74  the final result
33930 20 73 65 74 2e 0a 5e 54 68 65 20 49 4e 54 45 52   set..^The INTER
33940 53 45 43 54 20 6f 70 65 72 61 74 6f 72 20 72 65  SECT operator re
33950 74 75 72 6e 73 20 74 68 65 20 69 6e 74 65 72 73  turns the inters
33960 65 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ection of the re
33970 73 75 6c 74 73 20 6f 66 20 74 68 65 20 6c 65 66  sults of the lef
33980 74 20 61 6e 64 0a 72 69 67 68 74 20 53 45 4c 45  t and.right SELE
33990 43 54 73 2e 20 20 5e 54 68 65 20 45 58 43 45 50  CTs.  ^The EXCEP
339a0 54 20 6f 70 65 72 61 74 6f 72 20 72 65 74 75 72  T operator retur
339b0 6e 73 20 74 68 65 20 73 75 62 73 65 74 20 6f 66  ns the subset of
339c0 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62   rows returned b
339d0 79 20 74 68 65 0a 6c 65 66 74 20 53 45 4c 45 43  y the.left SELEC
339e0 54 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61  T that are not a
339f0 6c 73 6f 20 72 65 74 75 72 6e 65 64 20 62 79 20  lso returned by 
33a00 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 53  the right-hand S
33a10 45 4c 45 43 54 2e 20 5e 44 75 70 6c 69 63 61 74  ELECT. ^Duplicat
33a20 65 0a 72 6f 77 73 20 61 72 65 20 72 65 6d 6f 76  e.rows are remov
33a30 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ed from the resu
33a40 6c 74 73 20 6f 66 20 49 4e 54 45 52 53 45 43 54  lts of INTERSECT
33a50 20 61 6e 64 20 45 58 43 45 50 54 20 6f 70 65 72   and EXCEPT oper
33a60 61 74 6f 72 73 20 62 65 66 6f 72 65 20 74 68 65  ators before the
33a70 0a 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 72  .result set is r
33a80 65 74 75 72 6e 65 64 2e 0a 0a 3c 70 3e 5e 46 6f  eturned...<p>^Fo
33a90 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
33aa0 66 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 64 75  f determining du
33ab0 70 6c 69 63 61 74 65 20 72 6f 77 73 20 66 6f 72  plicate rows for
33ac0 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
33ad0 63 6f 6d 70 6f 75 6e 64 0a 53 45 4c 45 43 54 20  compound.SELECT 
33ae0 6f 70 65 72 61 74 6f 72 73 2c 20 4e 55 4c 4c 20  operators, NULL 
33af0 76 61 6c 75 65 73 20 61 72 65 20 63 6f 6e 73 69  values are consi
33b00 64 65 72 65 64 20 65 71 75 61 6c 20 74 6f 20 6f  dered equal to o
33b10 74 68 65 72 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ther NULL values
33b20 20 61 6e 64 0a 64 69 73 74 69 6e 63 74 20 66 72   and.distinct fr
33b30 6f 6d 20 61 6c 6c 20 6e 6f 6e 2d 4e 55 4c 4c 20  om all non-NULL 
33b40 76 61 6c 75 65 73 2e 20 5e 54 68 65 20 63 6f 6c  values. ^The col
33b50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
33b60 75 73 65 64 20 74 6f 20 63 6f 6d 70 61 72 65 20  used to compare 
33b70 0a 74 77 6f 20 74 65 78 74 20 76 61 6c 75 65 73  .two text values
33b80 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 20 61   is determined a
33b90 73 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s if the columns
33ba0 20 6f 66 20 74 68 65 20 6c 65 66 74 20 61 6e 64   of the left and
33bb0 20 72 69 67 68 74 2d 68 61 6e 64 0a 53 45 4c 45   right-hand.SELE
33bc0 43 54 20 73 74 61 74 65 6d 65 6e 74 73 20 77 65  CT statements we
33bd0 72 65 20 74 68 65 20 6c 65 66 74 20 61 6e 64 20  re the left and 
33be0 72 69 67 68 74 2d 68 61 6e 64 20 6f 70 65 72 61  right-hand opera
33bf0 6e 64 73 20 6f 66 20 74 68 65 20 65 71 75 61 6c  nds of the equal
33c00 73 20 28 3d 29 0a 6f 70 65 72 61 74 6f 72 2c 20  s (=).operator, 
33c10 65 78 63 65 70 74 20 74 68 61 74 20 67 72 65 61  except that grea
33c20 74 65 72 20 70 72 65 63 65 64 65 6e 63 65 20 69  ter precedence i
33c30 73 20 6e 6f 74 20 61 73 73 69 67 6e 65 64 20 74  s not assigned t
33c40 6f 20 61 20 63 6f 6c 6c 61 74 69 6f 6e 20 0a 73  o a collation .s
33c50 65 71 75 65 6e 63 65 20 73 70 65 63 69 66 69 65  equence specifie
33c60 64 20 77 69 74 68 20 74 68 65 20 70 6f 73 74 66  d with the postf
33c70 69 78 20 43 4f 4c 4c 41 54 45 20 6f 70 65 72 61  ix COLLATE opera
33c80 74 6f 72 2e 20 5e 4e 6f 20 61 66 66 69 6e 69 74  tor. ^No affinit
33c90 79 0a 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  y.transformation
33ca0 73 20 61 72 65 20 61 70 70 6c 69 65 64 20 74 6f  s are applied to
33cb0 20 61 6e 79 20 76 61 6c 75 65 73 20 77 68 65 6e   any values when
33cc0 20 63 6f 6d 70 61 72 69 6e 67 20 72 6f 77 73 20   comparing rows 
33cd0 61 73 20 70 61 72 74 20 6f 66 20 61 0a 63 6f 6d  as part of a.com
33ce0 70 6f 75 6e 64 20 53 45 4c 45 43 54 2e 20 0a 0a  pound SELECT. ..
33cf0 3c 70 3e 5e 28 57 68 65 6e 20 74 68 72 65 65 20  <p>^(When three 
33d00 6f 72 20 6d 6f 72 65 20 73 69 6d 70 6c 65 20 53  or more simple S
33d10 45 4c 45 43 54 73 20 61 72 65 20 63 6f 6e 6e 65  ELECTs are conne
33d20 63 74 65 64 20 69 6e 74 6f 20 61 20 63 6f 6d 70  cted into a comp
33d30 6f 75 6e 64 20 53 45 4c 45 43 54 2c 0a 74 68 65  ound SELECT,.the
33d40 79 20 67 72 6f 75 70 20 66 72 6f 6d 20 6c 65 66  y group from lef
33d50 74 20 74 6f 20 72 69 67 68 74 2e 20 49 6e 20 6f  t to right. In o
33d60 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 22  ther words, if "
33d70 41 22 2c 20 22 42 22 20 61 6e 64 20 22 43 22 20  A", "B" and "C" 
33d80 61 72 65 20 61 6c 6c 0a 73 69 6d 70 6c 65 20 53  are all.simple S
33d90 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
33da0 2c 20 28 41 20 6f 70 20 42 20 6f 70 20 43 29 20  , (A op B op C) 
33db0 69 73 20 70 72 6f 63 65 73 73 65 64 20 61 73 20  is processed as 
33dc0 28 28 41 20 6f 70 20 42 29 20 6f 70 20 43 29 2e  ((A op B) op C).
33dd0 29 5e 0a 0a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  )^..</p>..<tcl>h
33de0 64 5f 66 72 61 67 6d 65 6e 74 20 6f 72 64 65 72  d_fragment order
33df0 62 79 20 7b 6f 72 64 65 72 20 62 79 7d 20 7b 4f  by {order by} {O
33e00 52 44 45 52 20 42 59 7d 3c 2f 74 63 6c 3e 0a 3c  RDER BY}</tcl>.<
33e10 68 33 3e 54 68 65 20 4f 52 44 45 52 20 42 59 20  h3>The ORDER BY 
33e20 63 6c 61 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e  clause</h3>..<p>
33e30 49 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  If a SELECT stat
33e40 65 6d 65 6e 74 20 74 68 61 74 20 72 65 74 75 72  ement that retur
33e50 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  ns more than one
33e60 20 72 6f 77 20 64 6f 65 73 20 6e 6f 74 20 68 61   row does not ha
33e70 76 65 20 61 6e 0a 4f 52 44 45 52 20 42 59 20 63  ve an.ORDER BY c
33e80 6c 61 75 73 65 2c 20 74 68 65 20 6f 72 64 65 72  lause, the order
33e90 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 72 6f   in which the ro
33ea0 77 73 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  ws are returned 
33eb0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 4f 72  is undefined..Or
33ec0 2c 20 69 66 20 61 20 53 45 4c 45 43 54 20 73 74  , if a SELECT st
33ed0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 68 61 76  atement does hav
33ee0 65 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c  e an ORDER BY cl
33ef0 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  ause, then the l
33f00 69 73 74 20 6f 66 0a 65 78 70 72 65 73 73 69 6f  ist of.expressio
33f10 6e 73 20 61 74 74 61 63 68 65 64 20 74 6f 20 74  ns attached to t
33f20 68 65 20 4f 52 44 45 52 20 42 59 20 64 65 74 65  he ORDER BY dete
33f30 72 6d 69 6e 65 20 74 68 65 20 6f 72 64 65 72 20  rmine the order 
33f40 69 6e 20 77 68 69 63 68 20 72 6f 77 73 0a 61 72  in which rows.ar
33f50 65 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  e returned to th
33f60 65 20 75 73 65 72 2e 0a 0a 3c 70 3e 0a 5e 49 6e  e user...<p>.^In
33f70 20 61 20 5b 63 6f 6d 70 6f 75 6e 64 20 53 45 4c   a [compound SEL
33f80 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2c 20  ECT] statement, 
33f90 6f 6e 6c 79 20 74 68 65 20 6c 61 73 74 20 6f 72  only the last or
33fa0 20 72 69 67 68 74 2d 6d 6f 73 74 20 5b 73 69 6d   right-most [sim
33fb0 70 6c 65 20 53 45 4c 45 43 54 5d 0a 6d 61 79 20  ple SELECT].may 
33fc0 68 61 76 65 20 61 6e 20 4f 52 44 45 52 20 42 59  have an ORDER BY
33fd0 20 63 6c 61 75 73 65 2e 20 5e 54 68 61 74 20 4f   clause. ^That O
33fe0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 77  RDER BY clause w
33ff0 69 6c 6c 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ill apply across
34000 20 61 6c 6c 20 65 6c 65 6d 65 6e 74 73 20 6f 66   all elements of
34010 0a 74 68 65 20 63 6f 6d 70 6f 75 6e 64 2e 20 5e  .the compound. ^
34020 49 66 20 74 68 65 20 72 69 67 68 74 2d 6d 6f 73  If the right-mos
34030 74 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 20 5b  t element of a [
34040 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d  compound SELECT]
34050 20 69 73 20 61 20 5b 56 41 4c 55 45 53 5d 20 63   is a [VALUES] c
34060 6c 61 75 73 65 2c 0a 74 68 65 6e 20 6e 6f 20 4f  lause,.then no O
34070 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
34080 73 20 61 6c 6c 6f 77 65 64 20 6f 6e 20 74 68 61  s allowed on tha
34090 74 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 0a 3c  t statement....<
340a0 70 3e 5e 52 6f 77 73 20 61 72 65 20 66 69 72 73  p>^Rows are firs
340b0 74 20 73 6f 72 74 65 64 20 62 61 73 65 64 20 6f  t sorted based o
340c0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66  n the results of
340d0 0a 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20  .evaluating the 
340e0 6c 65 66 74 2d 6d 6f 73 74 20 65 78 70 72 65 73  left-most expres
340f0 73 69 6f 6e 20 69 6e 20 74 68 65 20 4f 52 44 45  sion in the ORDE
34100 52 20 42 59 20 6c 69 73 74 2c 20 74 68 65 6e 20  R BY list, then 
34110 74 69 65 73 20 61 72 65 20 62 72 6f 6b 65 6e 0a  ties are broken.
34120 62 79 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  by evaluating th
34130 65 20 73 65 63 6f 6e 64 20 6c 65 66 74 2d 6d 6f  e second left-mo
34140 73 74 20 65 78 70 72 65 73 73 69 6f 6e 20 61 6e  st expression an
34150 64 20 73 6f 20 6f 6e 2e 20 54 68 65 20 6f 72 64  d so on. The ord
34160 65 72 20 69 6e 20 77 68 69 63 68 0a 74 77 6f 20  er in which.two 
34170 72 6f 77 73 20 66 6f 72 20 77 68 69 63 68 20 61  rows for which a
34180 6c 6c 20 4f 52 44 45 52 20 42 59 20 65 78 70 72  ll ORDER BY expr
34190 65 73 73 69 6f 6e 73 20 65 76 61 6c 75 61 74 65  essions evaluate
341a0 20 74 6f 20 65 71 75 61 6c 20 76 61 6c 75 65 73   to equal values
341b0 20 61 72 65 0a 72 65 74 75 72 6e 65 64 20 69 73   are.returned is
341c0 20 75 6e 64 65 66 69 6e 65 64 2e 20 5e 45 61 63   undefined. ^Eac
341d0 68 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65  h ORDER BY expre
341e0 73 73 69 6f 6e 20 6d 61 79 20 62 65 20 6f 70 74  ssion may be opt
341f0 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64  ionally followed
34200 0a 62 79 20 6f 6e 65 20 6f 66 20 74 68 65 20 6b  .by one of the k
34210 65 79 77 6f 72 64 73 20 41 53 43 20 28 73 6d 61  eywords ASC (sma
34220 6c 6c 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ller values are 
34230 72 65 74 75 72 6e 65 64 20 66 69 72 73 74 29 20  returned first) 
34240 6f 72 20 44 45 53 43 20 28 6c 61 72 67 65 72 0a  or DESC (larger.
34250 76 61 6c 75 65 73 20 61 72 65 20 72 65 74 75 72  values are retur
34260 6e 65 64 20 66 69 72 73 74 29 2e 20 5e 49 66 20  ned first). ^If 
34270 6e 65 69 74 68 65 72 20 41 53 43 20 6f 72 20 44  neither ASC or D
34280 45 53 43 20 61 72 65 20 73 70 65 63 69 66 69 65  ESC are specifie
34290 64 2c 20 72 6f 77 73 0a 61 72 65 20 73 6f 72 74  d, rows.are sort
342a0 65 64 20 69 6e 20 61 73 63 65 6e 64 69 6e 67 20  ed in ascending 
342b0 28 73 6d 61 6c 6c 65 72 20 76 61 6c 75 65 73 20  (smaller values 
342c0 66 69 72 73 74 29 20 6f 72 64 65 72 20 62 79 20  first) order by 
342d0 64 65 66 61 75 6c 74 2e 0a 0a 3c 74 63 6c 3e 68  default...<tcl>h
342e0 64 5f 66 72 61 67 6d 65 6e 74 20 6e 75 6c 6c 73  d_fragment nulls
342f0 6c 61 73 74 20 7b 4e 55 4c 4c 53 20 46 49 52 53  last {NULLS FIRS
34300 54 7d 20 7b 4e 55 4c 4c 53 20 4c 41 53 54 7d 3c  T} {NULLS LAST}<
34310 2f 74 63 6c 3e 0a 3c 70 3e 53 51 4c 69 74 65 20  /tcl>.<p>SQLite 
34320 63 6f 6e 73 69 64 65 72 73 20 4e 55 4c 4c 20 76  considers NULL v
34330 61 6c 75 65 73 20 74 6f 20 62 65 20 73 6d 61 6c  alues to be smal
34340 6c 65 72 20 74 68 61 6e 20 61 6e 79 20 6f 74 68  ler than any oth
34350 65 72 20 76 61 6c 75 65 73 0a 66 6f 72 20 73 6f  er values.for so
34360 72 74 69 6e 67 20 70 75 72 70 6f 73 65 73 2e 20  rting purposes. 
34370 20 48 65 6e 63 65 2c 20 4e 55 4c 4c 73 20 6e 61   Hence, NULLs na
34380 74 75 72 61 6c 6c 79 20 61 70 70 65 61 72 20 61  turally appear a
34390 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  t the beginning.
343a0 6f 66 20 61 6e 20 41 53 43 20 6f 72 64 65 72 2d  of an ASC order-
343b0 62 79 20 61 6e 64 20 61 74 20 74 68 65 20 65 6e  by and at the en
343c0 64 20 6f 66 20 61 20 44 45 53 43 20 6f 72 64 65  d of a DESC orde
343d0 72 2d 62 79 2e 20 20 54 68 69 73 20 63 61 6e 20  r-by.  This can 
343e0 62 65 20 63 68 61 6e 67 65 64 0a 75 73 69 6e 67  be changed.using
343f0 20 74 68 65 20 22 41 53 43 20 4e 55 4c 4c 53 20   the "ASC NULLS 
34400 4c 41 53 54 22 20 6f 72 20 22 44 45 53 43 20 4e  LAST" or "DESC N
34410 55 4c 4c 53 20 46 49 52 53 54 22 20 73 79 6e 74  ULLS FIRST" synt
34420 61 78 2e 0a 0a 3c 70 3e 45 61 63 68 20 4f 52 44  ax...<p>Each ORD
34430 45 52 20 42 59 20 65 78 70 72 65 73 73 69 6f 6e  ER BY expression
34440 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 61 73   is processed as
34450 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c   follows:</p>..<
34460 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 5e 49 66 20 74  ol>.<li><p>^If t
34470 68 65 20 4f 52 44 45 52 20 42 59 20 65 78 70 72  he ORDER BY expr
34480 65 73 73 69 6f 6e 20 69 73 20 61 20 63 6f 6e 73  ession is a cons
34490 74 61 6e 74 20 69 6e 74 65 67 65 72 20 4b 20 74  tant integer K t
344a0 68 65 6e 20 74 68 65 0a 65 78 70 72 65 73 73 69  hen the.expressi
344b0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
344c0 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68   an alias for th
344d0 65 20 4b 2d 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  e K-th column of
344e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a   the result set.
344f0 28 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 75 6d  (columns are num
34500 62 65 72 65 64 20 66 72 6f 6d 20 6c 65 66 74 20  bered from left 
34510 74 6f 20 72 69 67 68 74 20 73 74 61 72 74 69 6e  to right startin
34520 67 20 77 69 74 68 20 31 29 2e 0a 0a 3c 6c 69 3e  g with 1)...<li>
34530 3c 70 3e 5e 49 66 20 74 68 65 20 4f 52 44 45 52  <p>^If the ORDER
34540 20 42 59 20 65 78 70 72 65 73 73 69 6f 6e 20 69   BY expression i
34550 73 20 61 6e 20 69 64 65 6e 74 69 66 69 65 72 20  s an identifier 
34560 74 68 61 74 20 63 6f 72 72 65 73 70 6f 6e 64 73  that corresponds
34570 20 74 6f 0a 74 68 65 20 61 6c 69 61 73 20 6f 66   to.the alias of
34580 20 6f 6e 65 20 6f 66 20 74 68 65 20 6f 75 74 70   one of the outp
34590 75 74 20 63 6f 6c 75 6d 6e 73 2c 20 74 68 65 6e  ut columns, then
345a0 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20   the expression 
345b0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 61 6e  is considered.an
345c0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 61 74 20   alias for that 
345d0 63 6f 6c 75 6d 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e  column...<li><p>
345e0 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 74  ^Otherwise, if t
345f0 68 65 20 4f 52 44 45 52 20 42 59 20 65 78 70 72  he ORDER BY expr
34600 65 73 73 69 6f 6e 20 69 73 20 61 6e 79 20 6f 74  ession is any ot
34610 68 65 72 20 65 78 70 72 65 73 73 69 6f 6e 2c 20  her expression, 
34620 69 74 20 0a 69 73 20 65 76 61 6c 75 61 74 65 64  it .is evaluated
34630 20 61 6e 64 20 74 68 65 20 72 65 74 75 72 6e 65   and the returne
34640 64 20 76 61 6c 75 65 20 75 73 65 64 20 74 6f 20  d value used to 
34650 6f 72 64 65 72 20 74 68 65 20 6f 75 74 70 75 74  order the output
34660 20 72 6f 77 73 2e 20 5e 49 66 0a 74 68 65 20 53   rows. ^If.the S
34670 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
34680 69 73 20 61 20 73 69 6d 70 6c 65 20 53 45 4c 45  is a simple SELE
34690 43 54 2c 20 74 68 65 6e 20 61 6e 20 4f 52 44 45  CT, then an ORDE
346a0 52 20 42 59 20 6d 61 79 20 63 6f 6e 74 61 69 6e  R BY may contain
346b0 20 61 6e 79 0a 61 72 62 69 74 72 61 72 79 20 65   any.arbitrary e
346c0 78 70 72 65 73 73 69 6f 6e 73 2e 20 5e 48 6f 77  xpressions. ^How
346d0 65 76 65 72 2c 20 69 66 20 74 68 65 20 53 45 4c  ever, if the SEL
346e0 45 43 54 20 69 73 20 61 20 63 6f 6d 70 6f 75 6e  ECT is a compoun
346f0 64 20 53 45 4c 45 43 54 2c 20 74 68 65 6e 0a 4f  d SELECT, then.O
34700 52 44 45 52 20 42 59 20 65 78 70 72 65 73 73 69  RDER BY expressi
34710 6f 6e 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74  ons that are not
34720 20 61 6c 69 61 73 65 73 20 74 6f 20 6f 75 74 70   aliases to outp
34730 75 74 20 63 6f 6c 75 6d 6e 73 20 6d 75 73 74 20  ut columns must 
34740 62 65 20 65 78 61 63 74 6c 79 0a 74 68 65 20 73  be exactly.the s
34750 61 6d 65 20 61 73 20 61 6e 20 65 78 70 72 65 73  ame as an expres
34760 73 69 6f 6e 20 75 73 65 64 20 61 73 20 61 6e 20  sion used as an 
34770 6f 75 74 70 75 74 20 63 6f 6c 75 6d 6e 2e 0a 3c  output column..<
34780 2f 6f 6c 3e 0a 0a 3c 70 3e 5e 46 6f 72 20 74 68  /ol>..<p>^For th
34790 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 73 6f  e purposes of so
347a0 72 74 69 6e 67 20 72 6f 77 73 2c 20 76 61 6c 75  rting rows, valu
347b0 65 73 20 61 72 65 20 63 6f 6d 70 61 72 65 64 20  es are compared 
347c0 69 6e 20 74 68 65 20 73 61 6d 65 20 77 61 79 0a  in the same way.
347d0 61 73 20 66 6f 72 20 5b 63 6f 6d 70 61 72 69 73  as for [comparis
347e0 6f 6e 20 65 78 70 72 65 73 73 69 6f 6e 73 5d 2e  on expressions].
347f0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   The collation s
34800 65 71 75 65 6e 63 65 20 75 73 65 64 20 74 6f 20  equence used to 
34810 63 6f 6d 70 61 72 65 0a 74 77 6f 20 74 65 78 74  compare.two text
34820 20 76 61 6c 75 65 73 20 69 73 20 64 65 74 65 72   values is deter
34830 6d 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73  mined as follows
34840 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 3c 70  :..<ol>.  <li><p
34850 3e 5e 49 66 20 74 68 65 20 4f 52 44 45 52 20 42  >^If the ORDER B
34860 59 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  Y expression is 
34870 61 73 73 69 67 6e 65 64 20 61 20 63 6f 6c 6c 61  assigned a colla
34880 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 75 73  tion sequence us
34890 69 6e 67 0a 20 20 74 68 65 20 70 6f 73 74 66 69  ing.  the postfi
348a0 78 20 5b 43 4f 4c 4c 41 54 45 20 6f 70 65 72 61  x [COLLATE opera
348b0 74 6f 72 5d 2c 20 74 68 65 6e 20 74 68 65 20 73  tor], then the s
348c0 70 65 63 69 66 69 65 64 20 63 6f 6c 6c 61 74 69  pecified collati
348d0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 20  on sequence is. 
348e0 20 75 73 65 64 2e 0a 20 20 3c 6c 69 3e 3c 70 3e   used..  <li><p>
348f0 5e 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 74  ^Otherwise, if t
34900 68 65 20 4f 52 44 45 52 20 42 59 20 65 78 70 72  he ORDER BY expr
34910 65 73 73 69 6f 6e 20 69 73 20 61 6e 20 61 6c 69  ession is an ali
34920 61 73 20 74 6f 20 61 6e 20 65 78 70 72 65 73 73  as to an express
34930 69 6f 6e 0a 20 20 74 68 61 74 20 68 61 73 20 62  ion.  that has b
34940 65 65 6e 20 61 73 73 69 67 6e 65 64 20 61 20 63  een assigned a c
34950 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
34960 65 20 75 73 69 6e 67 20 74 68 65 20 70 6f 73 74  e using the post
34970 66 69 78 20 0a 20 20 5b 43 4f 4c 4c 41 54 45 20  fix .  [COLLATE 
34980 6f 70 65 72 61 74 6f 72 5d 2c 20 74 68 65 6e 20  operator], then 
34990 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
349a0 71 75 65 6e 63 65 20 61 73 73 69 67 6e 65 64 20  quence assigned 
349b0 74 6f 20 74 68 65 20 61 6c 69 61 73 65 64 0a 20  to the aliased. 
349c0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 75   expression is u
349d0 73 65 64 2e 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 4f  sed..  <li><p>^O
349e0 74 68 65 72 77 69 73 65 2c 20 69 66 20 74 68 65  therwise, if the
349f0 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65 73   ORDER BY expres
34a00 73 69 6f 6e 20 69 73 20 61 20 63 6f 6c 75 6d 6e  sion is a column
34a10 20 6f 72 20 61 6e 20 61 6c 69 61 73 20 6f 66 0a   or an alias of.
34a20 20 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20    an expression 
34a30 74 68 61 74 20 69 73 20 61 20 63 6f 6c 75 6d 6e  that is a column
34a40 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
34a50 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
34a60 75 65 6e 63 65 20 66 6f 72 0a 20 20 74 68 65 20  uence for.  the 
34a70 63 6f 6c 75 6d 6e 20 69 73 20 75 73 65 64 2e 20  column is used. 
34a80 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 4f 74 68 65 72  .  <li><p>^Other
34a90 77 69 73 65 2c 20 74 68 65 20 5b 42 49 4e 41 52  wise, the [BINAR
34aa0 59 5d 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  Y] collation seq
34ab0 75 65 6e 63 65 20 69 73 20 75 73 65 64 2e 0a 3c  uence is used..<
34ac0 2f 6f 6c 3e 0a 0a 3c 70 3e 49 6e 20 61 20 5b 63  /ol>..<p>In a [c
34ad0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d 20  ompound SELECT] 
34ae0 73 74 61 74 65 6d 65 6e 74 2c 20 61 6c 6c 20 4f  statement, all O
34af0 52 44 45 52 20 42 59 20 65 78 70 72 65 73 73 69  RDER BY expressi
34b00 6f 6e 73 20 61 72 65 20 68 61 6e 64 6c 65 64 0a  ons are handled.
34b10 61 73 20 61 6c 69 61 73 65 73 20 66 6f 72 20 6f  as aliases for o
34b20 6e 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ne of the result
34b30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20   columns of the 
34b40 63 6f 6d 70 6f 75 6e 64 2e 0a 5e 28 49 66 20 61  compound..^(If a
34b50 6e 20 4f 52 44 45 52 20 42 59 20 65 78 70 72 65  n ORDER BY expre
34b60 73 73 69 6f 6e 20 69 73 20 6e 6f 74 20 61 6e 20  ssion is not an 
34b70 69 6e 74 65 67 65 72 20 61 6c 69 61 73 2c 20 74  integer alias, t
34b80 68 65 6e 20 53 51 4c 69 74 65 20 73 65 61 72 63  hen SQLite searc
34b90 68 65 73 0a 74 68 65 20 6c 65 66 74 2d 6d 6f 73  hes.the left-mos
34ba0 74 20 53 45 4c 45 43 54 20 69 6e 20 74 68 65 20  t SELECT in the 
34bb0 63 6f 6d 70 6f 75 6e 64 20 66 6f 72 20 61 20 72  compound for a r
34bc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 74 68 61  esult column tha
34bd0 74 20 6d 61 74 63 68 65 73 20 65 69 74 68 65 72  t matches either
34be0 0a 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 74  .the second or t
34bf0 68 69 72 64 20 72 75 6c 65 73 20 61 62 6f 76 65  hird rules above
34c00 2e 20 49 66 20 61 20 6d 61 74 63 68 20 69 73 20  . If a match is 
34c10 66 6f 75 6e 64 2c 20 74 68 65 20 73 65 61 72 63  found, the searc
34c20 68 20 73 74 6f 70 73 20 61 6e 64 0a 74 68 65 20  h stops and.the 
34c30 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 68 61  expression is ha
34c40 6e 64 6c 65 64 20 61 73 20 61 6e 20 61 6c 69 61  ndled as an alia
34c50 73 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  s for the result
34c60 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 20   column that it 
34c70 68 61 73 20 62 65 65 6e 0a 6d 61 74 63 68 65 64  has been.matched
34c80 20 61 67 61 69 6e 73 74 2e 20 4f 74 68 65 72 77   against. Otherw
34c90 69 73 65 2c 20 74 68 65 20 6e 65 78 74 20 53 45  ise, the next SE
34ca0 4c 45 43 54 20 74 6f 20 74 68 65 20 72 69 67 68  LECT to the righ
34cb0 74 20 69 73 20 74 72 69 65 64 2c 20 61 6e 64 20  t is tried, and 
34cc0 73 6f 20 6f 6e 2e 29 5e 0a 5e 49 66 20 6e 6f 20  so on.)^.^If no 
34cd0 6d 61 74 63 68 69 6e 67 20 65 78 70 72 65 73 73  matching express
34ce0 69 6f 6e 20 63 61 6e 20 62 65 20 66 6f 75 6e 64  ion can be found
34cf0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
34d00 6f 6c 75 6d 6e 73 20 6f 66 20 61 6e 79 0a 63 6f  olumns of any.co
34d10 6e 73 74 69 74 75 65 6e 74 20 53 45 4c 45 43 54  nstituent SELECT
34d20 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  , it is an error
34d30 2e 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20  . ^Each term of 
34d40 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
34d50 75 73 65 20 69 73 0a 70 72 6f 63 65 73 73 65 64  use is.processed
34d60 20 73 65 70 61 72 61 74 65 6c 79 20 61 6e 64 20   separately and 
34d70 6d 61 79 20 62 65 20 6d 61 74 63 68 65 64 20 61  may be matched a
34d80 67 61 69 6e 73 74 20 72 65 73 75 6c 74 20 63 6f  gainst result co
34d90 6c 75 6d 6e 73 20 66 72 6f 6d 20 64 69 66 66 65  lumns from diffe
34da0 72 65 6e 74 0a 53 45 4c 45 43 54 20 73 74 61 74  rent.SELECT stat
34db0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 63 6f  ements in the co
34dc0 6d 70 6f 75 6e 64 2e 3c 2f 70 3e 0a 0a 3c 74 63  mpound.</p>..<tc
34dd0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6c 69  l>hd_fragment li
34de0 6d 69 74 6f 66 66 73 65 74 20 7b 4c 49 4d 49 54  mitoffset {LIMIT
34df0 7d 20 7b 4f 46 46 53 45 54 7d 3c 2f 74 63 6c 3e  } {OFFSET}</tcl>
34e00 0a 3c 68 33 3e 54 68 65 20 4c 49 4d 49 54 20 63  .<h3>The LIMIT c
34e10 6c 61 75 73 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e  lause</h3>..<p>^
34e20 54 68 65 20 4c 49 4d 49 54 20 63 6c 61 75 73 65  The LIMIT clause
34e30 20 69 73 20 75 73 65 64 20 74 6f 20 70 6c 61 63   is used to plac
34e40 65 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  e an upper bound
34e50 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   on the number o
34e60 66 20 72 6f 77 73 0a 72 65 74 75 72 6e 65 64 20  f rows.returned 
34e70 62 79 20 74 68 65 20 65 6e 74 69 72 65 20 53 45  by the entire SE
34e80 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
34e90 0a 3c 70 3e 5e 49 6e 20 61 20 5b 63 6f 6d 70 6f  .<p>^In a [compo
34ea0 75 6e 64 20 53 45 4c 45 43 54 5d 2c 20 6f 6e 6c  und SELECT], onl
34eb0 79 20 74 68 65 0a 6c 61 73 74 20 6f 72 20 72 69  y the.last or ri
34ec0 67 68 74 2d 6d 6f 73 74 20 5b 73 69 6d 70 6c 65  ght-most [simple
34ed0 20 53 45 4c 45 43 54 5d 20 6d 61 79 20 63 6f 6e   SELECT] may con
34ee0 74 61 69 6e 20 61 20 4c 49 4d 49 54 20 63 6c 61  tain a LIMIT cla
34ef0 75 73 65 2e 20 20 0a 5e 49 6e 20 61 20 5b 63 6f  use.  .^In a [co
34f00 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 5d 2c 20  mpound SELECT], 
34f10 0a 74 68 65 20 4c 49 4d 49 54 20 63 6c 61 75 73  .the LIMIT claus
34f20 65 20 61 70 70 6c 69 65 73 20 74 6f 20 74 68 65  e applies to the
34f30 20 65 6e 74 69 72 65 20 63 6f 6d 70 6f 75 6e 64   entire compound
34f40 2c 20 6e 6f 74 20 6a 75 73 74 20 74 68 65 20 66  , not just the f
34f50 69 6e 61 6c 20 53 45 4c 45 43 54 2e 0a 5e 49 66  inal SELECT..^If
34f60 20 74 68 65 20 72 69 67 68 74 2d 6d 6f 73 74 20   the right-most 
34f70 5b 73 69 6d 70 6c 65 20 53 45 4c 45 43 54 5d 20  [simple SELECT] 
34f80 69 73 20 61 20 5b 56 41 4c 55 45 53 20 63 6c 61  is a [VALUES cla
34f90 75 73 65 5d 20 74 68 65 6e 20 6e 6f 20 4c 49 4d  use] then no LIM
34fa0 49 54 20 63 6c 61 75 73 65 0a 69 73 20 61 6c 6c  IT clause.is all
34fb0 6f 77 65 64 2e 0a 0a 3c 70 3e 5e 41 6e 79 20 73  owed...<p>^Any s
34fc0 63 61 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  calar expression
34fd0 20 6d 61 79 20 62 65 20 75 73 65 64 20 69 6e 20   may be used in 
34fe0 74 68 65 20 0a 4c 49 4d 49 54 20 63 6c 61 75 73  the .LIMIT claus
34ff0 65 2c 20 73 6f 20 6c 6f 6e 67 20 61 73 20 69 74  e, so long as it
35000 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 6e   evaluates to an
35010 20 69 6e 74 65 67 65 72 20 6f 72 20 61 20 76 61   integer or a va
35020 6c 75 65 20 74 68 61 74 20 63 61 6e 20 62 65 0a  lue that can be.
35030 6c 6f 73 73 6c 65 73 73 6c 79 20 63 6f 6e 76 65  losslessly conve
35040 72 74 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 67  rted to an integ
35050 65 72 2e 20 5e 49 66 20 74 68 65 20 65 78 70 72  er. ^If the expr
35060 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  ession evaluates
35070 20 74 6f 20 61 20 4e 55 4c 4c 20 0a 76 61 6c 75   to a NULL .valu
35080 65 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 76  e or any other v
35090 61 6c 75 65 20 74 68 61 74 20 63 61 6e 6e 6f 74  alue that cannot
350a0 20 62 65 20 6c 6f 73 73 6c 65 73 73 6c 79 20 63   be losslessly c
350b0 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 6e 20 69  onverted to an i
350c0 6e 74 65 67 65 72 2c 20 61 6e 0a 65 72 72 6f 72  nteger, an.error
350d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49   is returned. ^I
350e0 66 20 74 68 65 20 4c 49 4d 49 54 20 65 78 70 72  f the LIMIT expr
350f0 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  ession evaluates
35100 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 76   to a negative v
35110 61 6c 75 65 2c 0a 74 68 65 6e 20 74 68 65 72 65  alue,.then there
35120 20 69 73 20 6e 6f 20 75 70 70 65 72 20 62 6f 75   is no upper bou
35130 6e 64 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72  nd on the number
35140 20 6f 66 20 72 6f 77 73 20 72 65 74 75 72 6e 65   of rows returne
35150 64 2e 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  d. ^Otherwise, t
35160 68 65 0a 53 45 4c 45 43 54 20 72 65 74 75 72 6e  he.SELECT return
35170 73 20 74 68 65 20 66 69 72 73 74 20 4e 20 72 6f  s the first N ro
35180 77 73 20 6f 66 20 69 74 73 20 72 65 73 75 6c 74  ws of its result
35190 20 73 65 74 20 6f 6e 6c 79 2c 20 77 68 65 72 65   set only, where
351a0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 0a   N is the value.
351b0 74 68 61 74 20 74 68 65 20 4c 49 4d 49 54 20 65  that the LIMIT e
351c0 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61  xpression evalua
351d0 74 65 73 20 74 6f 2e 20 5e 4f 72 2c 20 69 66 20  tes to. ^Or, if 
351e0 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
351f0 6d 65 6e 74 20 77 6f 75 6c 64 0a 72 65 74 75 72  ment would.retur
35200 6e 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 72 6f  n less than N ro
35210 77 73 20 77 69 74 68 6f 75 74 20 61 20 4c 49 4d  ws without a LIM
35220 49 54 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20  IT clause, then 
35230 74 68 65 20 65 6e 74 69 72 65 20 72 65 73 75 6c  the entire resul
35240 74 20 73 65 74 20 69 73 0a 72 65 74 75 72 6e 65  t set is.returne
35250 64 2e 20 0a 0a 3c 70 3e 5e 54 68 65 20 65 78 70  d. ..<p>^The exp
35260 72 65 73 73 69 6f 6e 20 61 74 74 61 63 68 65 64  ression attached
35270 20 74 6f 20 74 68 65 20 6f 70 74 69 6f 6e 61 6c   to the optional
35280 20 4f 46 46 53 45 54 20 63 6c 61 75 73 65 20 74   OFFSET clause t
35290 68 61 74 20 6d 61 79 20 66 6f 6c 6c 6f 77 20 61  hat may follow a
352a0 0a 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 6d 75  .LIMIT clause mu
352b0 73 74 20 61 6c 73 6f 20 65 76 61 6c 75 61 74 65  st also evaluate
352c0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   to an integer, 
352d0 6f 72 20 61 20 76 61 6c 75 65 20 74 68 61 74 20  or a value that 
352e0 63 61 6e 20 62 65 0a 6c 6f 73 73 6c 65 73 73 6c  can be.losslessl
352f0 79 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61  y converted to a
35300 6e 20 69 6e 74 65 67 65 72 2e 20 5e 49 66 20 61  n integer. ^If a
35310 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 68 61 73  n expression has
35320 20 61 6e 20 4f 46 46 53 45 54 20 63 6c 61 75 73   an OFFSET claus
35330 65 2c 0a 74 68 65 6e 20 74 68 65 20 66 69 72 73  e,.then the firs
35340 74 20 4d 20 72 6f 77 73 20 61 72 65 20 6f 6d 69  t M rows are omi
35350 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  tted from the re
35360 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
35370 64 20 62 79 20 74 68 65 20 53 45 4c 45 43 54 0a  d by the SELECT.
35380 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
35390 65 20 6e 65 78 74 20 4e 20 72 6f 77 73 20 61 72  e next N rows ar
353a0 65 20 72 65 74 75 72 6e 65 64 2c 20 77 68 65 72  e returned, wher
353b0 65 20 4d 20 61 6e 64 20 4e 20 61 72 65 20 74 68  e M and N are th
353c0 65 20 76 61 6c 75 65 73 20 74 68 61 74 0a 74 68  e values that.th
353d0 65 20 4f 46 46 53 45 54 20 61 6e 64 20 4c 49 4d  e OFFSET and LIM
353e0 49 54 20 63 6c 61 75 73 65 73 20 65 76 61 6c 75  IT clauses evalu
353f0 61 74 65 20 74 6f 2c 20 72 65 73 70 65 63 74 69  ate to, respecti
35400 76 65 6c 79 2e 20 5e 4f 72 2c 20 69 66 20 74 68  vely. ^Or, if th
35410 65 20 53 45 4c 45 43 54 0a 77 6f 75 6c 64 20 72  e SELECT.would r
35420 65 74 75 72 6e 20 6c 65 73 73 20 74 68 61 6e 20  eturn less than 
35430 4d 2b 4e 20 72 6f 77 73 20 69 66 20 69 74 20 64  M+N rows if it d
35440 69 64 20 6e 6f 74 20 68 61 76 65 20 61 20 4c 49  id not have a LI
35450 4d 49 54 20 63 6c 61 75 73 65 2c 20 74 68 65 6e  MIT clause, then
35460 20 74 68 65 0a 66 69 72 73 74 20 4d 20 72 6f 77   the.first M row
35470 73 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e  s are skipped an
35480 64 20 74 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  d the remaining 
35490 72 6f 77 73 20 28 69 66 20 61 6e 79 29 20 61 72  rows (if any) ar
354a0 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20  e returned. ^If 
354b0 74 68 65 0a 4f 46 46 53 45 54 20 63 6c 61 75 73  the.OFFSET claus
354c0 65 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  e evaluates to a
354d0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 2c   negative value,
354e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
354f0 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20   the same as if 
35500 69 74 0a 68 61 64 20 65 76 61 6c 75 61 74 65 64  it.had evaluated
35510 20 74 6f 20 7a 65 72 6f 2e 0a 0a 3c 70 3e 5e 49   to zero...<p>^I
35520 6e 73 74 65 61 64 20 6f 66 20 61 20 73 65 70 61  nstead of a sepa
35530 72 61 74 65 20 4f 46 46 53 45 54 20 63 6c 61 75  rate OFFSET clau
35540 73 65 2c 20 74 68 65 20 4c 49 4d 49 54 20 63 6c  se, the LIMIT cl
35550 61 75 73 65 20 6d 61 79 20 73 70 65 63 69 66 79  ause may specify
35560 20 74 77 6f 0a 73 63 61 6c 61 72 20 65 78 70 72   two.scalar expr
35570 65 73 73 69 6f 6e 73 20 73 65 70 61 72 61 74 65  essions separate
35580 64 20 62 79 20 61 20 63 6f 6d 6d 61 2e 20 5e 49  d by a comma. ^I
35590 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  n this case, the
355a0 20 66 69 72 73 74 20 65 78 70 72 65 73 73 69 6f   first expressio
355b0 6e 0a 69 73 20 75 73 65 64 20 61 73 20 74 68 65  n.is used as the
355c0 20 4f 46 46 53 45 54 20 65 78 70 72 65 73 73 69   OFFSET expressi
355d0 6f 6e 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  on and the secon
355e0 64 20 61 73 20 74 68 65 20 4c 49 4d 49 54 20 65  d as the LIMIT e
355f0 78 70 72 65 73 73 69 6f 6e 2e 0a 54 68 69 73 20  xpression..This 
35600 69 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  is counter-intui
35610 74 69 76 65 2c 20 61 73 20 77 68 65 6e 20 75 73  tive, as when us
35620 69 6e 67 20 74 68 65 20 4f 46 46 53 45 54 20 63  ing the OFFSET c
35630 6c 61 75 73 65 20 74 68 65 20 73 65 63 6f 6e 64  lause the second
35640 20 6f 66 0a 74 68 65 20 74 77 6f 20 65 78 70 72   of.the two expr
35650 65 73 73 69 6f 6e 73 20 69 73 20 74 68 65 20 4f  essions is the O
35660 46 46 53 45 54 20 61 6e 64 20 74 68 65 20 66 69  FFSET and the fi
35670 72 73 74 20 74 68 65 20 4c 49 4d 49 54 2e 20 0a  rst the LIMIT. .
35680 54 68 69 73 20 72 65 76 65 72 73 61 6c 20 6f 66  This reversal of
35690 20 74 68 65 20 6f 66 66 73 65 74 20 61 6e 64 20   the offset and 
356a0 6c 69 6d 69 74 20 69 73 20 69 6e 74 65 6e 74 69  limit is intenti
356b0 6f 6e 61 6c 0a 2d 20 69 74 20 6d 61 78 69 6d 69  onal.- it maximi
356c0 7a 65 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  zes compatibilit
356d0 79 20 77 69 74 68 20 6f 74 68 65 72 20 53 51 4c  y with other SQL
356e0 20 64 61 74 61 62 61 73 65 20 73 79 73 74 65 6d   database system
356f0 73 2e 0a 48 6f 77 65 76 65 72 2c 20 74 6f 20 61  s..However, to a
35700 76 6f 69 64 20 63 6f 6e 66 75 73 69 6f 6e 2c 20  void confusion, 
35710 70 72 6f 67 72 61 6d 6d 65 72 73 20 61 72 65 20  programmers are 
35720 73 74 72 6f 6e 67 6c 79 20 65 6e 63 6f 75 72 61  strongly encoura
35730 67 65 64 20 74 6f 20 75 73 65 0a 74 68 65 20 66  ged to use.the f
35740 6f 72 6d 20 6f 66 20 74 68 65 20 4c 49 4d 49 54  orm of the LIMIT
35750 20 63 6c 61 75 73 65 20 74 68 61 74 20 75 73 65   clause that use
35760 73 20 74 68 65 20 22 4f 46 46 53 45 54 22 20 6b  s the "OFFSET" k
35770 65 79 77 6f 72 64 20 61 6e 64 20 61 76 6f 69 64  eyword and avoid
35780 0a 75 73 69 6e 67 20 61 20 4c 49 4d 49 54 20 63  .using a LIMIT c
35790 6c 61 75 73 65 20 77 69 74 68 20 61 20 63 6f 6d  lause with a com
357a0 6d 61 2d 73 65 70 61 72 61 74 65 64 20 6f 66 66  ma-separated off
357b0 73 65 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  set...<tcl>hd_fr
357c0 61 67 6d 65 6e 74 20 76 61 6c 75 65 73 20 7b 56  agment values {V
357d0 41 4c 55 45 53 20 63 6c 61 75 73 65 7d 20 56 41  ALUES clause} VA
357e0 4c 55 45 53 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54  LUES</tcl>.<h3>T
357f0 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75 73 65  he VALUES clause
35800 3c 2f 68 33 3e 0a 0a 3c 70 3e 5e 28 54 68 65 20  </h3>..<p>^(The 
35810 70 68 72 61 73 65 20 22 56 41 4c 55 45 53 28 3c  phrase "VALUES(<
35820 69 3e 65 78 70 72 2d 6c 69 73 74 3c 2f 69 3e 29  i>expr-list</i>)
35830 22 20 6d 65 61 6e 73 20 74 68 65 20 73 61 6d 65  " means the same
35840 20 74 68 69 6e 67 0a 61 73 20 22 53 45 4c 45 43   thing.as "SELEC
35850 54 20 3c 69 3e 65 78 70 72 2d 6c 69 73 74 3c 2f  T <i>expr-list</
35860 69 3e 22 2e 29 5e 20 20 5e 28 54 68 65 20 70 68  i>".)^  ^(The ph
35870 72 61 73 65 0a 22 56 41 4c 55 45 53 28 3c 69 3e  rase."VALUES(<i>
35880 65 78 70 72 2d 6c 69 73 74 2d 31 3c 2f 69 3e 29  expr-list-1</i>)
35890 2c 2e 2e 2e 2c 28 3c 69 3e 65 78 70 72 2d 6c 69  ,...,(<i>expr-li
358a0 73 74 2d 4e 3c 2f 69 3e 29 22 20 6d 65 61 6e 73  st-N</i>)" means
358b0 20 74 68 65 20 73 61 6d 65 0a 74 68 69 6e 67 20   the same.thing 
358c0 61 73 20 22 53 45 4c 45 43 54 20 3c 69 3e 65 78  as "SELECT <i>ex
358d0 70 72 2d 6c 69 73 74 2d 31 3c 2f 69 3e 20 55 4e  pr-list-1</i> UN
358e0 49 4f 4e 20 41 4c 4c 20 2e 2e 2e 20 55 4e 49 4f  ION ALL ... UNIO
358f0 4e 20 41 4c 4c 0a 53 45 4c 45 43 54 20 3c 69 3e  N ALL.SELECT <i>
35900 65 78 70 72 2d 6c 69 73 74 2d 4e 3c 2f 69 3e 22  expr-list-N</i>"
35910 2e 29 5e 20 20 42 6f 74 68 20 66 6f 72 6d 73 20  .)^  Both forms 
35920 61 72 65 20 74 68 65 20 73 61 6d 65 2c 20 65 78  are the same, ex
35930 63 65 70 74 20 74 68 61 74 0a 74 68 65 20 6e 75  cept that.the nu
35940 6d 62 65 72 20 6f 66 20 53 45 4c 45 43 54 20 73  mber of SELECT s
35950 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 61 20 63  tatements in a c
35960 6f 6d 70 6f 75 6e 64 20 69 73 20 6c 69 6d 69 74  ompound is limit
35970 65 64 20 62 79 0a 5b 53 51 4c 49 54 45 5f 4c 49  ed by.[SQLITE_LI
35980 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
35990 45 43 54 5d 20 77 68 65 72 65 61 73 20 74 68 65  ECT] whereas the
359a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
359b0 69 6e 20 61 0a 56 41 4c 55 45 53 20 63 6c 61 75  in a.VALUES clau
359c0 73 65 20 68 61 73 20 6e 6f 20 61 72 62 69 74 72  se has no arbitr
359d0 61 72 79 20 6c 69 6d 69 74 2e 0a 0a 3c 70 3e 54  ary limit...<p>T
359e0 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20 72 65  here are some re
359f0 73 74 72 69 63 74 69 6f 6e 73 20 6f 6e 20 74 68  strictions on th
35a00 65 20 75 73 65 20 6f 66 20 61 20 56 41 4c 55 45  e use of a VALUE
35a10 53 20 63 6c 61 75 73 65 20 74 68 61 74 20 61 72  S clause that ar
35a20 65 0a 6e 6f 74 20 73 68 6f 77 6e 20 6f 6e 20 74  e.not shown on t
35a30 68 65 20 73 79 6e 74 61 78 20 64 69 61 67 72 61  he syntax diagra
35a40 6d 73 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70  ms:..<ul>.<li><p
35a50 3e 0a 5e 41 20 56 41 4c 55 45 53 20 63 6c 61 75  >.^A VALUES clau
35a60 73 65 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 6c  se cannot be fol
35a70 6c 6f 77 65 64 20 62 79 20 5b 4f 52 44 45 52 20  lowed by [ORDER 
35a80 42 59 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 5e 41  BY]...<li><p>.^A
35a90 20 56 41 4c 55 45 53 20 63 6c 61 75 73 65 20 63   VALUES clause c
35aa0 61 6e 6e 6f 74 20 62 65 20 66 6f 6c 6c 6f 77 65  annot be followe
35ab0 64 20 62 79 20 5b 4c 49 4d 49 54 5d 2e 0a 3c 2f  d by [LIMIT]..</
35ac0 75 6c 3e 0a 0a 0a 3c 68 33 3e 54 68 65 20 57 49  ul>...<h3>The WI
35ad0 54 48 20 43 6c 61 75 73 65 3c 2f 68 33 3e 0a 0a  TH Clause</h3>..
35ae0 3c 70 3e 5e 53 45 4c 45 43 54 20 73 74 61 74 65  <p>^SELECT state
35af0 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 6f 70 74  ments may be opt
35b00 69 6f 6e 61 6c 6c 79 20 70 72 65 63 65 64 65 64  ionally preceded
35b10 20 62 79 20 61 20 73 69 6e 67 6c 65 0a 5b 57 49   by a single.[WI
35b20 54 48 20 63 6c 61 75 73 65 5d 20 74 68 61 74 20  TH clause] that 
35b30 64 65 66 69 6e 65 73 20 6f 6e 65 20 6f 72 20 6d  defines one or m
35b40 6f 72 65 20 5b 63 6f 6d 6d 6f 6e 20 74 61 62 6c  ore [common tabl
35b50 65 20 65 78 70 72 65 73 73 69 6f 6e 73 5d 0a 66  e expressions].f
35b60 6f 72 20 75 73 65 20 77 69 74 68 69 6e 20 74 68  or use within th
35b70 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
35b80 6e 74 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  nt...<tcl>hd_fra
35b90 67 6d 65 6e 74 20 74 61 62 66 75 6e 63 31 20 7b  gment tabfunc1 {
35ba0 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
35bb0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 46 52  ctions in the FR
35bc0 4f 4d 20 63 6c 61 75 73 65 7d 3c 2f 74 63 6c 3e  OM clause}</tcl>
35bd0 0a 3c 68 33 3e 54 61 62 6c 65 2d 76 61 6c 75 65  .<h3>Table-value
35be0 64 20 46 75 6e 63 74 69 6f 6e 73 20 49 6e 20 54  d Functions In T
35bf0 68 65 20 46 52 4f 4d 20 43 6c 61 75 73 65 3c 2f  he FROM Clause</
35c00 68 33 3e 0a 0a 3c 70 3e 41 20 5b 76 69 72 74 75  h3>..<p>A [virtu
35c10 61 6c 20 74 61 62 6c 65 5d 20 74 68 61 74 20 63  al table] that c
35c20 6f 6e 74 61 69 6e 73 20 5b 68 69 64 64 65 6e 20  ontains [hidden 
35c30 63 6f 6c 75 6d 6e 73 5d 20 63 61 6e 20 62 65 20  columns] can be 
35c40 75 73 65 64 20 6c 69 6b 65 0a 61 20 5b 74 61 62  used like.a [tab
35c50 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74 69  le-valued functi
35c60 6f 6e 5d 20 69 6e 20 74 68 65 20 46 52 4f 4d 20  on] in the FROM 
35c70 63 6c 61 75 73 65 2e 20 20 54 68 65 20 61 72 67  clause.  The arg
35c80 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 0a 74 61  uments to the.ta
35c90 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74  ble-valued funct
35ca0 69 6f 6e 20 62 65 63 6f 6d 65 20 63 6f 6e 73 74  ion become const
35cb0 72 61 69 6e 74 73 20 6f 6e 20 74 68 65 20 48 49  raints on the HI
35cc0 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 20 6f 66 0a  DDEN columns of.
35cd0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
35ce0 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  e.  Additional i
35cf0 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62  nformation can b
35d00 65 20 66 6f 75 6e 64 20 69 6e 20 74 68 65 0a 5b  e found in the.[
35d10 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
35d20 63 74 69 6f 6e 73 7c 76 69 72 74 75 61 6c 20 74  ctions|virtual t
35d30 61 62 6c 65 20 64 6f 63 75 6d 65 6e 74 61 74 69  able documentati
35d40 6f 6e 5d 2e 0a 0a 3c 74 63 6c 3e 0a 23 23 23 23  on]...<tcl>.####
35d50 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
35d60 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
35d70 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
35d80 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
35d90 23 23 23 23 23 23 23 23 23 23 0a 53 65 63 74 69  ##########.Secti
35da0 6f 6e 20 55 50 44 41 54 45 20 75 70 64 61 74 65  on UPDATE update
35db0 20 7b 55 50 44 41 54 45 20 2a 55 50 44 41 54 45   {UPDATE *UPDATE
35dc0 73 7d 0a 0a 52 65 63 75 72 73 69 76 65 42 75 62  s}..RecursiveBub
35dd0 62 6c 65 44 69 61 67 72 61 6d 20 75 70 64 61 74  bleDiagram updat
35de0 65 2d 73 74 6d 74 0a 3c 2f 74 63 6c 3e 0a 0a 3c  e-stmt.</tcl>..<
35df0 70 3e 5e 41 6e 20 55 50 44 41 54 45 20 73 74 61  p>^An UPDATE sta
35e00 74 65 6d 65 6e 74 20 69 73 20 75 73 65 64 20 74  tement is used t
35e10 6f 20 6d 6f 64 69 66 79 20 61 20 73 75 62 73 65  o modify a subse
35e20 74 20 6f 66 20 74 68 65 20 76 61 6c 75 65 73 20  t of the values 
35e30 73 74 6f 72 65 64 20 69 6e 20 0a 7a 65 72 6f 20  stored in .zero 
35e40 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
35e50 74 68 65 20 64 61 74 61 62 61 73 65 20 74 61 62  the database tab
35e60 6c 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  le identified by
35e70 20 74 68 65 20 0a 5b 71 75 61 6c 69 66 69 65 64   the .[qualified
35e80 2d 74 61 62 6c 65 2d 6e 61 6d 65 5d 20 73 70 65  -table-name] spe
35e90 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
35ea0 66 20 74 68 65 20 55 50 44 41 54 45 20 73 74 61  f the UPDATE sta
35eb0 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 5e 49 66 20  tement...<p>^If 
35ec0 74 68 65 20 55 50 44 41 54 45 20 73 74 61 74 65  the UPDATE state
35ed0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 68 61  ment does not ha
35ee0 76 65 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  ve a WHERE claus
35ef0 65 2c 20 61 6c 6c 20 72 6f 77 73 20 69 6e 20 74  e, all rows in t
35f00 68 65 0a 74 61 62 6c 65 20 61 72 65 20 6d 6f 64  he.table are mod
35f10 69 66 69 65 64 20 62 79 20 74 68 65 20 55 50 44  ified by the UPD
35f20 41 54 45 2e 20 5e 4f 74 68 65 72 77 69 73 65 2c  ATE. ^Otherwise,
35f30 20 74 68 65 20 55 50 44 41 54 45 20 61 66 66 65   the UPDATE affe
35f40 63 74 73 20 6f 6e 6c 79 20 74 68 6f 73 65 0a 72  cts only those.r
35f50 6f 77 73 20 66 6f 72 20 77 68 69 63 68 20 74 68  ows for which th
35f60 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 5b  e WHERE clause.[
35f70 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69  boolean expressi
35f80 6f 6e 7c 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65  on|boolean expre
35f90 73 73 69 6f 6e 20 69 73 20 74 72 75 65 5d 2e 20  ssion is true]. 
35fa0 5e 49 74 20 69 73 20 6e 6f 74 20 61 6e 20 65 72  ^It is not an er
35fb0 72 6f 72 20 69 66 20 74 68 65 0a 57 48 45 52 45  ror if the.WHERE
35fc0 20 63 6c 61 75 73 65 20 64 6f 65 73 20 6e 6f 74   clause does not
35fd0 20 65 76 61 6c 75 61 74 65 20 74 6f 20 74 72 75   evaluate to tru
35fe0 65 20 66 6f 72 20 61 6e 79 20 72 6f 77 20 69 6e  e for any row in
35ff0 20 74 68 65 20 74 61 62 6c 65 20 2d 20 74 68 69   the table - thi
36000 73 20 6a 75 73 74 0a 6d 65 61 6e 73 20 74 68 61  s just.means tha
36010 74 20 74 68 65 20 55 50 44 41 54 45 20 73 74 61  t the UPDATE sta
36020 74 65 6d 65 6e 74 20 61 66 66 65 63 74 73 20 7a  tement affects z
36030 65 72 6f 20 72 6f 77 73 2e 0a 0a 3c 70 3e 54 68  ero rows...<p>Th
36040 65 20 6d 6f 64 69 66 69 63 61 74 69 6f 6e 73 20  e modifications 
36050 6d 61 64 65 20 74 6f 20 65 61 63 68 20 72 6f 77  made to each row
36060 20 61 66 66 65 63 74 65 64 20 62 79 20 61 6e 20   affected by an 
36070 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
36080 20 61 72 65 0a 64 65 74 65 72 6d 69 6e 65 64 20   are.determined 
36090 62 79 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  by the list of a
360a0 73 73 69 67 6e 6d 65 6e 74 73 20 66 6f 6c 6c 6f  ssignments follo
360b0 77 69 6e 67 20 74 68 65 20 53 45 54 20 6b 65 79  wing the SET key
360c0 77 6f 72 64 2e 20 45 61 63 68 0a 61 73 73 69 67  word. Each.assig
360d0 6e 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  nment specifies 
360e0 61 20 3c 79 79 74 65 72 6d 3e 63 6f 6c 75 6d 6e  a <yyterm>column
360f0 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 74  -name</yyterm> t
36100 6f 20 74 68 65 20 6c 65 66 74 20 6f 66 20 74 68  o the left of th
36110 65 20 0a 65 71 75 61 6c 73 20 73 69 67 6e 20 61  e .equals sign a
36120 6e 64 20 61 20 73 63 61 6c 61 72 20 65 78 70 72  nd a scalar expr
36130 65 73 73 69 6f 6e 20 74 6f 20 74 68 65 20 72 69  ession to the ri
36140 67 68 74 2e 20 0a 5e 46 6f 72 20 65 61 63 68 20  ght. .^For each 
36150 61 66 66 65 63 74 65 64 20 72 6f 77 2c 20 74 68  affected row, th
36160 65 20 6e 61 6d 65 64 20 63 6f 6c 75 6d 6e 73 0a  e named columns.
36170 61 72 65 20 73 65 74 20 74 6f 20 74 68 65 20 76  are set to the v
36180 61 6c 75 65 73 20 66 6f 75 6e 64 20 62 79 20 65  alues found by e
36190 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 63 6f  valuating the co
361a0 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 63 61 6c  rresponding scal
361b0 61 72 20 0a 65 78 70 72 65 73 73 69 6f 6e 73 2e  ar .expressions.
361c0 20 5e 49 66 20 61 20 73 69 6e 67 6c 65 20 63 6f   ^If a single co
361d0 6c 75 6d 6e 2d 6e 61 6d 65 20 61 70 70 65 61 72  lumn-name appear
361e0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  s more than once
361f0 20 69 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 0a   in the list of.
36200 61 73 73 69 67 6e 6d 65 6e 74 20 65 78 70 72 65  assignment expre
36210 73 73 69 6f 6e 73 2c 20 61 6c 6c 20 62 75 74 20  ssions, all but 
36220 74 68 65 20 72 69 67 68 74 6d 6f 73 74 20 6f 63  the rightmost oc
36230 63 75 72 72 65 6e 63 65 20 69 73 20 69 67 6e 6f  currence is igno
36240 72 65 64 2e 20 5e 43 6f 6c 75 6d 6e 73 0a 74 68  red. ^Columns.th
36250 61 74 20 64 6f 20 6e 6f 74 20 61 70 70 65 61 72  at do not appear
36260 20 69 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20   in the list of 
36270 61 73 73 69 67 6e 6d 65 6e 74 73 20 61 72 65 20  assignments are 
36280 6c 65 66 74 20 75 6e 6d 6f 64 69 66 69 65 64 2e  left unmodified.
36290 20 5e 54 68 65 20 73 63 61 6c 61 72 0a 65 78 70   ^The scalar.exp
362a0 72 65 73 73 69 6f 6e 73 20 6d 61 79 20 72 65 66  ressions may ref
362b0 65 72 20 74 6f 20 63 6f 6c 75 6d 6e 73 20 6f 66  er to columns of
362c0 20 74 68 65 20 72 6f 77 20 62 65 69 6e 67 20 75   the row being u
362d0 70 64 61 74 65 64 2e 20 5e 49 6e 20 74 68 69 73  pdated. ^In this
362e0 20 63 61 73 65 20 61 6c 6c 0a 73 63 61 6c 61 72   case all.scalar
362f0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 61 72 65   expressions are
36300 20 65 76 61 6c 75 61 74 65 64 20 62 65 66 6f 72   evaluated befor
36310 65 20 61 6e 79 20 61 73 73 69 67 6e 6d 65 6e 74  e any assignment
36320 73 20 61 72 65 20 6d 61 64 65 2e 0a 0a 3c 70 3e  s are made...<p>
36330 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c  Beginning in SQL
36340 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 31  ite [version 3.1
36350 35 2e 30 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  5.0] ([dateof:3.
36360 31 35 2e 30 5d 29 2c 20 61 6e 20 61 73 73 69 67  15.0]), an assig
36370 6e 6d 65 6e 74 20 69 6e 0a 74 68 65 20 53 45 54  nment in.the SET
36380 20 63 6c 61 75 73 65 20 63 61 6e 20 62 65 20 61   clause can be a
36390 20 0a 5b 63 6f 6c 75 6d 6e 2d 6e 61 6d 65 2d 6c   .[column-name-l
363a0 69 73 74 7c 70 61 72 65 6e 74 68 65 73 69 7a 65  ist|parenthesize
363b0 64 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e  d list of column
363c0 20 6e 61 6d 65 73 5d 20 6f 6e 20 74 68 65 20 6c   names] on the l
363d0 65 66 74 20 61 6e 64 20 61 0a 5b 72 6f 77 20 76  eft and a.[row v
363e0 61 6c 75 65 5d 20 6f 66 20 74 68 65 20 73 61 6d  alue] of the sam
363f0 65 20 73 69 7a 65 20 6f 6e 20 74 68 65 20 72 69  e size on the ri
36400 67 68 74 2e 0a 0a 0a 3c 70 3e 5e 54 68 65 20 6f  ght....<p>^The o
36410 70 74 69 6f 6e 61 6c 20 22 4f 52 20 3c 69 3e 61  ptional "OR <i>a
36420 63 74 69 6f 6e 3c 2f 69 3e 22 20 63 6f 6e 66 6c  ction</i>" confl
36430 69 63 74 20 63 6c 61 75 73 65 20 74 68 61 74 20  ict clause that 
36440 66 6f 6c 6c 6f 77 73 20 74 68 65 0a 55 50 44 41  follows the.UPDA
36450 54 45 20 6b 65 79 77 6f 72 64 20 61 6c 6c 6f 77  TE keyword allow
36460 73 20 74 68 65 20 75 73 65 72 20 74 6f 20 6e 6f  s the user to no
36470 6d 69 6e 61 74 65 20 61 20 73 70 65 63 69 66 69  minate a specifi
36480 63 0a 63 6f 6e 73 74 72 61 69 6e 74 20 63 6f 6e  c.constraint con
36490 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
364a0 20 61 6c 67 6f 72 69 74 68 6d 20 74 6f 20 75 73   algorithm to us
364b0 65 20 64 75 72 69 6e 67 20 74 68 69 73 20 6f 6e  e during this on
364c0 65 20 55 50 44 41 54 45 20 63 6f 6d 6d 61 6e 64  e UPDATE command
364d0 2e 0a 52 65 66 65 72 20 74 6f 20 74 68 65 20 73  ..Refer to the s
364e0 65 63 74 69 6f 6e 20 65 6e 74 69 74 6c 65 64 20  ection entitled 
364f0 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 66 6f  [ON CONFLICT] fo
36500 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
36510 6f 72 6d 61 74 69 6f 6e 2e 0a 0a 3c 68 33 3e 52  ormation...<h3>R
36520 65 73 74 72 69 63 74 69 6f 6e 73 20 6f 6e 20 55  estrictions on U
36530 50 44 41 54 45 20 53 74 61 74 65 6d 65 6e 74 73  PDATE Statements
36540 20 57 69 74 68 69 6e 20 43 52 45 41 54 45 20 54   Within CREATE T
36550 52 49 47 47 45 52 3c 2f 68 33 3e 0a 0a 3c 70 3e  RIGGER</h3>..<p>
36560 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 64  The following ad
36570 64 69 74 69 6f 6e 61 6c 20 73 79 6e 74 61 78 20  ditional syntax 
36580 72 65 73 74 72 69 63 74 69 6f 6e 73 20 61 70 70  restrictions app
36590 6c 79 20 74 6f 20 55 50 44 41 54 45 20 73 74 61  ly to UPDATE sta
365a0 74 65 6d 65 6e 74 73 20 74 68 61 74 0a 6f 63 63  tements that.occ
365b0 75 72 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  ur within the bo
365c0 64 79 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  dy of a [CREATE 
365d0 54 52 49 47 47 45 52 5d 20 73 74 61 74 65 6d 65  TRIGGER] stateme
365e0 6e 74 2e 20 20 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  nt.  ..<ul>.  <l
365f0 69 3e 3c 70 3e 5e 54 68 65 20 3c 79 79 74 65 72  i><p>^The <yyter
36600 6d 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 79 79  m>table-name</yy
36610 74 65 72 6d 3e 20 73 70 65 63 69 66 69 65 64 20  term> specified 
36620 61 73 20 70 61 72 74 20 6f 66 20 61 6e 20 55 50  as part of an UP
36630 44 41 54 45 20 0a 20 20 20 20 20 20 73 74 61 74  DATE .      stat
36640 65 6d 65 6e 74 20 77 69 74 68 69 6e 0a 20 20 20  ement within.   
36650 20 20 20 61 20 74 72 69 67 67 65 72 20 62 6f 64     a trigger bod
36660 79 20 6d 75 73 74 20 62 65 20 75 6e 71 75 61 6c  y must be unqual
36670 69 66 69 65 64 2e 20 5e 28 49 6e 20 6f 74 68 65  ified. ^(In othe
36680 72 20 77 6f 72 64 73 2c 20 74 68 65 0a 20 20 20  r words, the.   
36690 20 20 20 3c 69 3e 73 63 68 65 6d 61 2d 6e 61 6d     <i>schema-nam
366a0 65 3c 2f 69 3e 3c 62 3e 2e 3c 2f 62 3e 20 70 72  e</i><b>.</b> pr
366b0 65 66 69 78 20 6f 6e 20 74 68 65 20 74 61 62 6c  efix on the tabl
366c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 55 50  e name of the UP
366d0 44 41 54 45 20 69 73 0a 20 20 20 20 20 20 6e 6f  DATE is.      no
366e0 74 20 61 6c 6c 6f 77 65 64 20 77 69 74 68 69 6e  t allowed within
366f0 20 74 72 69 67 67 65 72 73 2e 29 5e 20 5e 55 6e   triggers.)^ ^Un
36700 6c 65 73 73 20 74 68 65 20 74 61 62 6c 65 20 74  less the table t
36710 6f 20 77 68 69 63 68 20 74 68 65 20 74 72 69 67  o which the trig
36720 67 65 72 0a 20 20 20 20 20 20 69 73 20 61 74 74  ger.      is att
36730 61 63 68 65 64 20 69 73 20 69 6e 20 74 68 65 20  ached is in the 
36740 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 74  TEMP database, t
36750 68 65 20 74 61 62 6c 65 20 62 65 69 6e 67 20 75  he table being u
36760 70 64 61 74 65 64 20 62 79 20 74 68 65 0a 20 20  pdated by the.  
36770 20 20 20 20 74 72 69 67 67 65 72 20 70 72 6f 67      trigger prog
36780 72 61 6d 20 6d 75 73 74 20 72 65 73 69 64 65 20  ram must reside 
36790 69 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  in the same data
367a0 62 61 73 65 20 61 73 20 69 74 2e 20 5e 49 66 20  base as it. ^If 
367b0 74 68 65 20 74 61 62 6c 65 0a 20 20 20 20 20 20  the table.      
367c0 74 6f 20 77 68 69 63 68 20 74 68 65 20 74 72 69  to which the tri
367d0 67 67 65 72 20 69 73 20 61 74 74 61 63 68 65 64  gger is attached
367e0 20 69 73 20 69 6e 20 74 68 65 20 54 45 4d 50 20   is in the TEMP 
367f0 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 20 74  database, then t
36800 68 65 0a 20 20 20 20 20 20 75 6e 71 75 61 6c 69  he.      unquali
36810 66 69 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  fied name of the
36820 20 74 61 62 6c 65 20 62 65 69 6e 67 20 75 70 64   table being upd
36830 61 74 65 64 20 69 73 20 72 65 73 6f 6c 76 65 64  ated is resolved
36840 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77 61 79   in the same way
36850 0a 20 20 20 20 20 20 61 73 20 69 74 20 69 73 20  .      as it is 
36860 66 6f 72 20 61 20 74 6f 70 2d 6c 65 76 65 6c 20  for a top-level 
36870 73 74 61 74 65 6d 65 6e 74 20 28 62 79 20 73 65  statement (by se
36880 61 72 63 68 69 6e 67 20 66 69 72 73 74 20 74 68  arching first th
36890 65 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c  e TEMP database,
368a0 0a 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20  .      then the 
368b0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 74  main database, t
368c0 68 65 6e 20 61 6e 79 20 6f 74 68 65 72 20 64 61  hen any other da
368d0 74 61 62 61 73 65 73 20 69 6e 20 74 68 65 20 6f  tabases in the o
368e0 72 64 65 72 20 74 68 65 79 20 77 65 72 65 0a 20  rder they were. 
368f0 20 20 20 20 20 61 74 74 61 63 68 65 64 29 2e 0a       attached)..
36900 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65 20 49  .  <li><p>^The I
36910 4e 44 45 58 45 44 20 42 59 20 61 6e 64 20 4e 4f  NDEXED BY and NO
36920 54 20 49 4e 44 45 58 45 44 20 63 6c 61 75 73 65  T INDEXED clause
36930 73 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  s are not allowe
36940 64 20 6f 6e 20 55 50 44 41 54 45 0a 20 20 20 20  d on UPDATE.    
36950 20 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74    statements wit
36960 68 69 6e 20 74 72 69 67 67 65 72 73 2e 3c 2f 70  hin triggers.</p
36970 3e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 5e 54 68 65  >..  <li><p>^The
36980 20 4c 49 4d 49 54 20 61 6e 64 20 4f 52 44 45 52   LIMIT and ORDER
36990 20 42 59 20 63 6c 61 75 73 65 73 20 66 6f 72 20   BY clauses for 
369a0 55 50 44 41 54 45 20 61 72 65 20 75 6e 73 75 70  UPDATE are unsup
369b0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 0a 20 20  ported within.  
369c0 20 20 20 20 74 72 69 67 67 65 72 73 2c 20 72 65      triggers, re
369d0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
369e0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 70 74 69  compilation opti
369f0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 75 69 6c  ons used to buil
36a00 64 20 53 51 4c 69 74 65 2e 0a 3c 2f 75 6c 3e 0a  d SQLite..</ul>.
36a10 0a 3c 68 33 3e 4f 70 74 69 6f 6e 61 6c 20 4c 49  .<h3>Optional LI
36a20 4d 49 54 20 61 6e 64 20 4f 52 44 45 52 20 42 59  MIT and ORDER BY
36a30 20 43 6c 61 75 73 65 73 3c 2f 68 33 3e 0a 0a 3c   Clauses</h3>..<
36a40 70 3e 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73  p>^(If SQLite is
36a50 20 62 75 69 6c 74 20 77 69 74 68 20 74 68 65 20   built with the 
36a60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 55  [SQLITE_ENABLE_U
36a70 50 44 41 54 45 5f 44 45 4c 45 54 45 5f 4c 49 4d  PDATE_DELETE_LIM
36a80 49 54 5d 0a 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT].compile-time
36a90 20 6f 70 74 69 6f 6e 20 74 68 65 6e 20 74 68 65   option then the
36aa0 20 73 79 6e 74 61 78 20 6f 66 20 74 68 65 20 55   syntax of the U
36ab0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20  PDATE statement 
36ac0 69 73 20 65 78 74 65 6e 64 65 64 0a 77 69 74 68  is extended.with
36ad0 20 6f 70 74 69 6f 6e 61 6c 20 4f 52 44 45 52 20   optional ORDER 
36ae0 42 59 20 61 6e 64 20 4c 49 4d 49 54 20 63 6c 61  BY and LIMIT cla
36af0 75 73 65 73 29 5e 20 61 73 20 66 6f 6c 6c 6f 77  uses)^ as follow
36b00 73 3a 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 42 75 62  s:</p>..<tcl>Bub
36b10 62 6c 65 44 69 61 67 72 61 6d 20 75 70 64 61 74  bleDiagram updat
36b20 65 2d 73 74 6d 74 2d 6c 69 6d 69 74 65 64 3c 2f  e-stmt-limited</
36b30 74 63 6c 3e 0a 0a 3c 70 3e 5e 49 66 20 61 6e 20  tcl>..<p>^If an 
36b40 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
36b50 20 68 61 73 20 61 20 4c 49 4d 49 54 20 63 6c 61   has a LIMIT cla
36b60 75 73 65 2c 20 74 68 65 20 6d 61 78 69 6d 75 6d  use, the maximum
36b70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
36b80 74 68 61 74 0a 77 69 6c 6c 20 62 65 20 75 70 64  that.will be upd
36b90 61 74 65 64 20 69 73 20 66 6f 75 6e 64 20 62 79  ated is found by
36ba0 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
36bb0 61 63 63 6f 6d 70 61 6e 79 69 6e 67 20 65 78 70  accompanying exp
36bc0 72 65 73 73 69 6f 6e 20 61 6e 64 20 63 61 73 74  ression and cast
36bd0 69 6e 67 0a 69 74 20 74 6f 20 61 6e 20 69 6e 74  ing.it to an int
36be0 65 67 65 72 20 76 61 6c 75 65 2e 20 5e 41 20 6e  eger value. ^A n
36bf0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 69 73  egative value is
36c00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
36c10 22 6e 6f 20 6c 69 6d 69 74 22 2e 0a 0a 3c 70 3e  "no limit"...<p>
36c20 5e 49 66 20 74 68 65 20 4c 49 4d 49 54 20 65 78  ^If the LIMIT ex
36c30 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61 74  pression evaluat
36c40 65 73 20 74 6f 20 6e 6f 6e 2d 6e 65 67 61 74 69  es to non-negati
36c50 76 65 20 76 61 6c 75 65 20 3c 69 3e 4e 3c 2f 69  ve value <i>N</i
36c60 3e 20 61 6e 64 20 74 68 65 0a 55 50 44 41 54 45  > and the.UPDATE
36c70 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 61   statement has a
36c80 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  n ORDER BY claus
36c90 65 2c 20 74 68 65 6e 20 61 6c 6c 20 72 6f 77 73  e, then all rows
36ca0 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 75   that would be u
36cb0 70 64 61 74 65 64 20 69 6e 0a 74 68 65 20 61 62  pdated in.the ab
36cc0 73 65 6e 63 65 20 6f 66 20 74 68 65 20 4c 49 4d  sence of the LIM
36cd0 49 54 20 63 6c 61 75 73 65 20 61 72 65 20 73 6f  IT clause are so
36ce0 72 74 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rted according t
36cf0 6f 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 61  o the ORDER BY a
36d00 6e 64 20 74 68 65 0a 66 69 72 73 74 20 3c 69 3e  nd the.first <i>
36d10 4e 3c 2f 69 3e 20 75 70 64 61 74 65 64 2e 20 5e  N</i> updated. ^
36d20 28 49 66 20 74 68 65 20 55 50 44 41 54 45 20 73  (If the UPDATE s
36d30 74 61 74 65 6d 65 6e 74 20 61 6c 73 6f 20 68 61  tatement also ha
36d40 73 20 61 6e 20 4f 46 46 53 45 54 20 63 6c 61 75  s an OFFSET clau
36d50 73 65 2c 0a 74 68 65 6e 20 69 74 20 69 73 20 73  se,.then it is s
36d60 69 6d 69 6c 61 72 6c 79 20 65 76 61 6c 75 61 74  imilarly evaluat
36d70 65 64 20 61 6e 64 20 63 61 73 74 20 74 6f 20 61  ed and cast to a
36d80 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 2e  n integer value.
36d90 20 49 66 20 74 68 65 20 4f 46 46 53 45 54 0a 65   If the OFFSET.e
36da0 78 70 72 65 73 73 69 6f 6e 20 65 76 61 6c 75 61  xpression evalua
36db0 74 65 73 20 74 6f 20 61 20 6e 6f 6e 2d 6e 65 67  tes to a non-neg
36dc0 61 74 69 76 65 20 76 61 6c 75 65 20 3c 69 3e 4d  ative value <i>M
36dd0 3c 2f 69 3e 2c 20 74 68 65 6e 20 74 68 65 20 66  </i>, then the f
36de0 69 72 73 74 20 3c 69 3e 4d 3c 2f 69 3e 0a 72 6f  irst <i>M</i>.ro
36df0 77 73 20 61 72 65 20 73 6b 69 70 70 65 64 20 61  ws are skipped a
36e00 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
36e10 20 3c 69 3e 4e 3c 2f 69 3e 20 72 6f 77 73 20 75   <i>N</i> rows u
36e20 70 64 61 74 65 64 20 69 6e 73 74 65 61 64 2e 29  pdated instead.)
36e30 5e 0a 0a 3c 70 3e 5e 49 66 20 74 68 65 20 55 50  ^..<p>^If the UP
36e40 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20 68  DATE statement h
36e50 61 73 20 6e 6f 20 4f 52 44 45 52 20 42 59 20 63  as no ORDER BY c
36e60 6c 61 75 73 65 2c 20 74 68 65 6e 20 61 6c 6c 20  lause, then all 
36e70 72 6f 77 73 20 74 68 61 74 0a 77 6f 75 6c 64 20  rows that.would 
36e80 62 65 20 75 70 64 61 74 65 64 20 69 6e 20 74 68  be updated in th
36e90 65 20 61 62 73 65 6e 63 65 20 6f 66 20 74 68 65  e absence of the
36ea0 20 4c 49 4d 49 54 20 63 6c 61 75 73 65 20 61 72   LIMIT clause ar
36eb0 65 20 61 73 73 65 6d 62 6c 65 64 20 69 6e 20 61  e assembled in a
36ec0 6e 0a 61 72 62 69 74 72 61 72 79 20 6f 72 64 65  n.arbitrary orde
36ed0 72 20 62 65 66 6f 72 65 20 61 70 70 6c 79 69 6e  r before applyin
36ee0 67 20 74 68 65 20 4c 49 4d 49 54 20 61 6e 64 20  g the LIMIT and 
36ef0 4f 46 46 53 45 54 20 63 6c 61 75 73 65 73 20 74  OFFSET clauses t
36f00 6f 20 64 65 74 65 72 6d 69 6e 65 20 0a 77 68 69  o determine .whi
36f10 63 68 20 61 72 65 20 61 63 74 75 61 6c 6c 79 20  ch are actually 
36f20 75 70 64 61 74 65 64 2e 0a 0a 3c 70 3e 5e 28 54  updated...<p>^(T
36f30 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
36f40 73 65 20 6f 6e 20 61 6e 20 55 50 44 41 54 45 20  se on an UPDATE 
36f50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 75 73 65  statement is use
36f60 64 20 6f 6e 6c 79 20 74 6f 20 64 65 74 65 72 6d  d only to determ
36f70 69 6e 65 20 77 68 69 63 68 0a 72 6f 77 73 20 66  ine which.rows f
36f80 61 6c 6c 20 77 69 74 68 69 6e 20 74 68 65 20 4c  all within the L
36f90 49 4d 49 54 2e 20 54 68 65 20 6f 72 64 65 72 20  IMIT. The order 
36fa0 69 6e 20 77 68 69 63 68 20 72 6f 77 73 20 61 72  in which rows ar
36fb0 65 20 6d 6f 64 69 66 69 65 64 20 69 73 20 61 72  e modified is ar
36fc0 62 69 74 72 61 72 79 0a 61 6e 64 20 69 73 20 6e  bitrary.and is n
36fd0 6f 74 20 69 6e 66 6c 75 65 6e 63 65 64 20 62 79  ot influenced by
36fe0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
36ff0 61 75 73 65 2e 29 5e 0a 0a 3c 74 63 6c 3e 0a 23  ause.)^..<tcl>.#
37000 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37010 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37020 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37030 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23  ################
37040 23 23 23 23 23 23 23 23 23 23 23 23 23 0a 53 65  #############.Se
37050 63 74 69 6f 6e 20 56 41 43 55 55 4d 20 76 61 63  ction VACUUM vac
37060 75 75 6d 20 56 41 43 55 55 4d 0a 0a 52 65 63 75  uum VACUUM..Recu
37070 72 73 69 76 65 42 75 62 62 6c 65 44 69 61 67 72  rsiveBubbleDiagr
37080 61 6d 20 76 61 63 75 75 6d 2d 73 74 6d 74 0a 3c  am vacuum-stmt.<
37090 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65  /tcl>..<p>.  The
370a0 20 56 41 43 55 55 4d 20 63 6f 6d 6d 61 6e 64 20   VACUUM command 
370b0 72 65 62 75 69 6c 64 73 20 74 68 65 20 64 61 74  rebuilds the dat
370c0 61 62 61 73 65 20 66 69 6c 65 2c 20 72 65 70 61  abase file, repa
370d0 63 6b 69 6e 67 20 69 74 20 69 6e 74 6f 20 61 20  cking it into a 
370e0 6d 69 6e 69 6d 61 6c 0a 20 20 61 6d 6f 75 6e 74  minimal.  amount
370f0 20 6f 66 20 64 69 73 6b 20 73 70 61 63 65 2e 20   of disk space. 
37100 54 68 65 72 65 20 61 72 65 20 73 65 76 65 72 61  There are severa
37110 6c 20 0a 20 20 72 65 61 73 6f 6e 73 20 61 6e 20  l .  reasons an 
37120 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
37130 74 20 64 6f 20 74 68 69 73 3a 0a 0a 3c 75 6c 3e  t do this:..<ul>
37140 0a 20 20 3c 6c 69 3e 20 3c 70 3e 20 5e 55 6e 6c  .  <li> <p> ^Unl
37150 65 73 73 20 53 51 4c 69 74 65 20 69 73 20 72 75  ess SQLite is ru
37160 6e 6e 69 6e 67 20 69 6e 20 22 61 75 74 6f 5f 76  nning in "auto_v
37170 61 63 75 75 6d 3d 46 55 4c 4c 22 20 6d 6f 64 65  acuum=FULL" mode
37180 2c 20 77 68 65 6e 20 61 20 6c 61 72 67 65 0a 20  , when a large. 
37190 20 20 20 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61      amount of da
371a0 74 61 20 69 73 20 64 65 6c 65 74 65 64 20 66 72  ta is deleted fr
371b0 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
371c0 66 69 6c 65 20 69 74 20 6c 65 61 76 65 73 20 62  file it leaves b
371d0 65 68 69 6e 64 20 65 6d 70 74 79 0a 20 20 20 20  ehind empty.    
371e0 20 73 70 61 63 65 2c 20 6f 72 20 22 66 72 65 65   space, or "free
371f0 22 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  " database pages
37200 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 65  . This means the
37210 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6d   database file m
37220 69 67 68 74 0a 20 20 20 20 20 62 65 20 6c 61 72  ight.     be lar
37230 67 65 72 20 74 68 61 6e 20 73 74 72 69 63 74 6c  ger than strictl
37240 79 20 6e 65 63 65 73 73 61 72 79 2e 20 5e 52 75  y necessary. ^Ru
37250 6e 6e 69 6e 67 20 56 41 43 55 55 4d 20 74 6f 20  nning VACUUM to 
37260 72 65 62 75 69 6c 64 20 74 68 65 20 0a 20 20 20  rebuild the .   
37270 20 20 64 61 74 61 62 61 73 65 20 72 65 63 6c 61    database recla
37280 69 6d 73 20 74 68 69 73 20 73 70 61 63 65 20 61  ims this space a
37290 6e 64 20 72 65 64 75 63 65 73 20 74 68 65 20 73  nd reduces the s
372a0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
372b0 61 73 65 20 66 69 6c 65 2e 0a 0a 20 20 3c 6c 69  ase file...  <li
372c0 3e 20 3c 70 3e 20 5e 46 72 65 71 75 65 6e 74 20  > <p> ^Frequent 
372d0 69 6e 73 65 72 74 73 2c 20 75 70 64 61 74 65 73  inserts, updates
372e0 2c 20 61 6e 64 20 64 65 6c 65 74 65 73 20 63 61  , and deletes ca
372f0 6e 20 63 61 75 73 65 20 74 68 65 20 64 61 74 61  n cause the data
37300 62 61 73 65 20 66 69 6c 65 0a 20 20 20 20 20 74  base file.     t
37310 6f 20 62 65 63 6f 6d 65 20 66 72 61 67 6d 65 6e  o become fragmen
37320 74 65 64 20 2d 20 77 68 65 72 65 20 64 61 74 61  ted - where data
37330 20 66 6f 72 20 61 20 73 69 6e 67 6c 65 20 74 61   for a single ta
37340 62 6c 65 20 6f 72 20 69 6e 64 65 78 20 69 73 20  ble or index is 
37350 73 63 61 74 74 65 72 65 64 20 0a 20 20 20 20 20  scattered .     
37360 61 72 6f 75 6e 64 20 74 68 65 20 64 61 74 61 62  around the datab
37370 61 73 65 20 66 69 6c 65 2e 20 5e 52 75 6e 6e 69  ase file. ^Runni
37380 6e 67 20 56 41 43 55 55 4d 20 65 6e 73 75 72 65  ng VACUUM ensure
37390 73 20 74 68 61 74 20 65 61 63 68 20 74 61 62 6c  s that each tabl
373a0 65 20 61 6e 64 0a 20 20 20 20 20 69 6e 64 65 78  e and.     index
373b0 20 69 73 20 6c 61 72 67 65 6c 79 20 73 74 6f 72   is largely stor
373c0 65 64 20 63 6f 6e 74 69 67 75 6f 75 73 6c 79 20  ed contiguously 
373d0 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61 62  within the datab
373e0 61 73 65 20 66 69 6c 65 2e 20 5e 49 6e 20 73 6f  ase file. ^In so
373f0 6d 65 0a 20 20 20 20 20 63 61 73 65 73 2c 20 56  me.     cases, V
37400 41 43 55 55 4d 20 6d 61 79 20 61 6c 73 6f 20 72  ACUUM may also r
37410 65 64 75 63 65 20 74 68 65 20 6e 75 6d 62 65 72  educe the number
37420 20 6f 66 20 70 61 72 74 69 61 6c 6c 79 20 66 69   of partially fi
37430 6c 6c 65 64 20 70 61 67 65 73 20 69 6e 0a 20 20  lled pages in.  
37440 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 2c     the database,
37450 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 73 69   reducing the si
37460 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
37470 73 65 20 66 69 6c 65 20 66 75 72 74 68 65 72 2e  se file further.
37480 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 20 57 68 65  ..  <li> <p> Whe
37490 6e 20 63 6f 6e 74 65 6e 74 20 69 73 20 64 65 6c  n content is del
374a0 65 74 65 64 20 66 72 6f 6d 20 61 6e 20 53 51 4c  eted from an SQL
374b0 69 74 65 20 64 61 74 61 62 61 73 65 2c 20 74 68  ite database, th
374c0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 6e 6f 74  e content is not
374d0 0a 20 20 20 20 20 75 73 75 61 6c 6c 79 20 65 72  .     usually er
374e0 61 73 65 64 20 62 75 74 20 72 61 74 68 65 72 20  ased but rather 
374f0 74 68 65 20 73 70 61 63 65 20 75 73 65 64 20 74  the space used t
37500 6f 20 68 6f 6c 64 20 74 68 65 20 63 6f 6e 74 65  o hold the conte
37510 6e 74 20 69 73 20 6d 61 72 6b 65 64 20 61 73 0a  nt is marked as.
37520 20 20 20 20 20 62 65 69 6e 67 20 61 76 61 69 6c       being avail
37530 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 20  able for reuse. 
37540 20 54 68 69 73 20 63 61 6e 20 61 6c 6c 6f 77 20   This can allow 
37550 64 65 6c 65 74 65 64 20 63 6f 6e 74 65 6e 74 20  deleted content 
37560 74 6f 20 62 65 20 72 65 63 6f 76 65 72 65 64 0a  to be recovered.
37570 20 20 20 20 20 62 79 20 61 20 68 61 63 6b 65 72       by a hacker
37580 20 6f 72 20 62 79 20 66 6f 72 65 6e 73 69 63 20   or by forensic 
37590 61 6e 61 6c 79 73 69 73 2e 20 20 52 75 6e 6e 69  analysis.  Runni
375a0 6e 67 20 56 41 43 55 55 4d 20 77 69 6c 6c 20 63  ng VACUUM will c
375b0 6c 65 61 6e 20 74 68 65 20 64 61 74 61 62 61 73  lean the databas
375c0 65 0a 20 20 20 20 20 6f 66 20 61 6c 6c 20 74 72  e.     of all tr
375d0 61 63 65 73 20 6f 66 20 64 65 6c 65 74 65 64 20  aces of deleted 
375e0 63 6f 6e 74 65 6e 74 2c 20 74 68 75 73 20 70 72  content, thus pr
375f0 65 76 65 6e 74 69 6e 67 20 61 6e 20 61 64 76 65  eventing an adve
37600 72 73 61 72 79 20 66 72 6f 6d 20 72 65 63 6f 76  rsary from recov
37610 65 72 69 6e 67 0a 20 20 20 20 20 64 65 6c 65 74  ering.     delet
37620 65 64 20 63 6f 6e 74 65 6e 74 2e 20 20 55 73 69  ed content.  Usi
37630 6e 67 20 56 41 43 55 55 4d 20 69 6e 20 74 68 69  ng VACUUM in thi
37640 73 20 77 61 79 20 69 73 20 61 6e 20 61 6c 74 65  s way is an alte
37650 72 6e 61 74 69 76 65 20 74 6f 20 73 65 74 74 69  rnative to setti
37660 6e 67 0a 20 20 20 20 20 5b 50 52 41 47 4d 41 20  ng.     [PRAGMA 
37670 73 65 63 75 72 65 5f 64 65 6c 65 74 65 3d 4f 4e  secure_delete=ON
37680 5d 2e 20 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 20  ]. ..  <li> <p> 
37690 5e 4e 6f 72 6d 61 6c 6c 79 2c 20 74 68 65 20 64  ^Normally, the d
376a0 61 74 61 62 61 73 65 20 5b 70 61 67 65 5f 73 69  atabase [page_si
376b0 7a 65 5d 20 61 6e 64 20 77 68 65 74 68 65 72 20  ze] and whether 
376c0 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62  or not the datab
376d0 61 73 65 0a 20 20 20 20 20 73 75 70 70 6f 72 74  ase.     support
376e0 73 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20  s [auto_vacuum] 
376f0 6d 75 73 74 20 62 65 20 63 6f 6e 66 69 67 75 72  must be configur
37700 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ed before the da
37710 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 0a 20  tabase file is. 
37720 20 20 20 20 61 63 74 75 61 6c 6c 79 20 63 72 65      actually cre
37730 61 74 65 64 2e 20 5e 48 6f 77 65 76 65 72 2c 20  ated. ^However, 
37740 77 68 65 6e 20 6e 6f 74 20 69 6e 20 5b 77 72 69  when not in [wri
37750 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 20 6d 6f  te-ahead log] mo
37760 64 65 2c 20 74 68 65 20 0a 20 20 20 20 20 5b 70  de, the .     [p
37770 61 67 65 5f 73 69 7a 65 5d 20 61 6e 64 2f 6f 72  age_size] and/or
37780 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20 70   [auto_vacuum] p
37790 72 6f 70 65 72 74 69 65 73 20 6f 66 20 61 6e 20  roperties of an 
377a0 65 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  existing databas
377b0 65 20 6d 61 79 20 62 65 0a 20 20 20 20 20 63 68  e may be.     ch
377c0 61 6e 67 65 64 20 62 79 20 75 73 69 6e 67 20 74  anged by using t
377d0 68 65 20 5b 70 61 67 65 5f 73 69 7a 65 20 70 72  he [page_size pr
377e0 61 67 6d 61 7c 70 61 67 65 5f 73 69 7a 65 5d 20  agma|page_size] 
377f0 20 61 6e 64 2f 6f 72 20 0a 20 20 20 20 20 5b 61   and/or .     [a
37800 75 74 6f 5f 76 61 63 75 75 6d 7c 70 72 61 67 6d  uto_vacuum|pragm
37810 61 20 61 75 74 6f 5f 76 61 63 75 75 6d 5d 20 70  a auto_vacuum] p
37820 72 61 67 6d 61 73 20 61 6e 64 20 74 68 65 6e 20  ragmas and then 
37830 69 6d 6d 65 64 69 61 74 65 6c 79 20 56 41 43 55  immediately VACU
37840 55 4d 69 6e 67 0a 20 20 20 20 20 74 68 65 20 64  UMing.     the d
37850 61 74 61 62 61 73 65 2e 20 5e 57 68 65 6e 20 69  atabase. ^When i
37860 6e 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c  n [write-ahead l
37870 6f 67 5d 20 6d 6f 64 65 2c 20 6f 6e 6c 79 20 74  og] mode, only t
37880 68 65 20 5b 61 75 74 6f 5f 76 61 63 75 75 6d 5d  he [auto_vacuum]
37890 0a 20 20 20 20 20 73 75 70 70 6f 72 74 20 70 72  .     support pr
378a0 6f 70 65 72 74 79 20 63 61 6e 20 62 65 20 63 68  operty can be ch
378b0 61 6e 67 65 64 20 75 73 69 6e 67 20 56 41 43 55  anged using VACU
378c0 55 4d 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e 42  UM..</ul>..<p>^B
378d0 79 20 64 65 66 61 75 6c 74 2c 20 56 41 43 55 55  y default, VACUU
378e0 4d 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 6c  M only works onl
378f0 79 20 6f 6e 20 74 68 65 20 6d 61 69 6e 20 64 61  y on the main da
37900 74 61 62 61 73 65 2e 0a 5e 5b 41 54 54 41 43 48  tabase..^[ATTACH
37910 7c 41 74 74 61 63 68 65 64 20 64 61 74 61 62 61  |Attached databa
37920 73 65 73 5d 20 63 61 6e 20 62 65 20 76 61 63 75  ses] can be vacu
37930 75 6d 65 64 20 62 79 20 61 70 70 65 6e 64 69 6e  umed by appendin
37940 67 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  g the appropriat
37950 65 0a 3c 79 79 74 65 72 6d 3e 73 63 68 65 6d 61  e.<yyterm>schema
37960 2d 6e 61 6d 65 3c 2f 79 79 74 65 72 6d 3e 20 74  -name</yyterm> t
37970 6f 20 74 68 65 20 56 41 43 55 55 4d 20 73 74 61  o the VACUUM sta
37980 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 3c 62 3e 43  tement...<p><b>C
37990 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 57 61 72  ompatibility War
379a0 6e 69 6e 67 3a 3c 2f 62 3e 20 54 68 65 20 61 62  ning:</b> The ab
379b0 69 6c 69 74 79 20 74 6f 20 76 61 63 75 75 6d 20  ility to vacuum 
379c0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
379d0 65 73 20 77 61 73 0a 61 64 64 65 64 20 69 6e 20  es was.added in 
379e0 5b 76 65 72 73 69 6f 6e 20 33 2e 31 35 2e 30 5d  [version 3.15.0]
379f0 20 28 5b 64 61 74 65 6f 66 3a 33 2e 31 35 2e 30   ([dateof:3.15.0
37a00 5d 29 2e 20 20 50 72 69 6f 72 20 74 6f 20 74 68  ]).  Prior to th
37a10 61 74 2c 20 61 20 0a 3c 79 79 74 65 72 6d 3e 73  at, a .<yyterm>s
37a20 63 68 65 6d 61 2d 6e 61 6d 65 3c 2f 79 79 74 65  chema-name</yyte
37a30 72 6d 3e 20 61 64 64 65 64 20 74 6f 20 74 68 65  rm> added to the
37a40 0a 56 41 43 55 55 4d 20 73 74 61 74 65 6d 65 6e  .VACUUM statemen
37a50 74 20 77 6f 75 6c 64 20 62 65 20 73 69 6c 65 6e  t would be silen
37a60 74 6c 79 20 69 67 6e 6f 72 65 64 20 61 6e 64 20  tly ignored and 
37a70 74 68 65 20 22 6d 61 69 6e 22 20 73 63 68 65 6d  the "main" schem
37a80 61 20 77 6f 75 6c 64 20 62 65 0a 76 61 63 75 75  a would be.vacuu
37a90 6d 65 64 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68  med.</p>..<tcl>h
37aa0 64 5f 66 72 61 67 6d 65 6e 74 20 76 61 63 75 75  d_fragment vacuu
37ab0 6d 69 6e 74 6f 20 7b 56 41 43 55 55 4d 20 49 4e  minto {VACUUM IN
37ac0