Documentation Source Text

Hex Artifact Content
Login

Artifact 5a73a5fe9f3b1e561c6e12dd277ac579730524c9:


0000: 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64  .<tcl>hd_keyword
0010: 73 20 2a 66 74 73 33 20 46 54 53 33 20 7b 66 75  s *fts3 FTS3 {fu
0020: 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 7d 3c  ll-text search}<
0030: 2f 74 63 6c 3e 0a 3c 74 69 74 6c 65 3e 53 51 4c  /tcl>.<title>SQL
0040: 69 74 65 20 46 54 53 33 20 61 6e 64 20 46 54 53  ite FTS3 and FTS
0050: 34 20 45 78 74 65 6e 73 69 6f 6e 73 3c 2f 74 69  4 Extensions</ti
0060: 74 6c 65 3e 0a 0a 3c 74 61 62 6c 65 5f 6f 66 5f  tle>..<table_of_
0070: 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 68 32 20 73  contents>..<h2 s
0080: 74 79 6c 65 3d 22 6d 61 72 67 69 6e 2d 6c 65 66  tyle="margin-lef
0090: 74 3a 31 2e 30 65 6d 22 20 6e 6f 74 6f 63 3e 20  t:1.0em" notoc> 
00a0: 4f 76 65 72 76 69 65 77 3c 2f 68 32 3e 0a 0a 3c  Overview</h2>..<
00b0: 70 3e 0a 20 20 46 54 53 33 20 61 6e 64 20 46 54  p>.  FTS3 and FT
00c0: 53 34 20 61 72 65 20 53 51 4c 69 74 65 20 76 69  S4 are SQLite vi
00d0: 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
00e0: 6c 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  les that allows 
00f0: 75 73 65 72 73 20 74 6f 20 70 65 72 66 6f 72 6d  users to perform
0100: 20 0a 20 20 66 75 6c 6c 2d 74 65 78 74 20 73 65   .  full-text se
0110: 61 72 63 68 65 73 20 6f 6e 20 61 20 73 65 74 20  arches on a set 
0120: 6f 66 20 64 6f 63 75 6d 65 6e 74 73 2e 20 54 68  of documents. Th
0130: 65 20 6d 6f 73 74 20 63 6f 6d 6d 6f 6e 20 28 61  e most common (a
0140: 6e 64 20 65 66 66 65 63 74 69 76 65 29 20 0a 20  nd effective) . 
0150: 20 77 61 79 20 74 6f 20 64 65 73 63 72 69 62 65   way to describe
0160: 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
0170: 68 65 73 20 69 73 20 22 77 68 61 74 20 47 6f 6f  hes is "what Goo
0180: 67 6c 65 2c 20 59 61 68 6f 6f 2c 20 61 6e 64 20  gle, Yahoo, and 
0190: 42 69 6e 67 20 64 6f 0a 20 20 77 69 74 68 20 64  Bing do.  with d
01a0: 6f 63 75 6d 65 6e 74 73 20 70 6c 61 63 65 64 20  ocuments placed 
01b0: 6f 6e 20 74 68 65 20 57 6f 72 6c 64 20 57 69 64  on the World Wid
01c0: 65 20 57 65 62 22 2e 20 55 73 65 72 73 20 69 6e  e Web". Users in
01d0: 70 75 74 20 61 20 74 65 72 6d 2c 20 6f 72 20 73  put a term, or s
01e0: 65 72 69 65 73 20 0a 20 20 6f 66 20 74 65 72 6d  eries .  of term
01f0: 73 2c 20 70 65 72 68 61 70 73 20 63 6f 6e 6e 65  s, perhaps conne
0200: 63 74 65 64 20 62 79 20 61 20 62 69 6e 61 72 79  cted by a binary
0210: 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 67 72 6f   operator or gro
0220: 75 70 65 64 20 74 6f 67 65 74 68 65 72 20 69 6e  uped together in
0230: 74 6f 20 61 20 0a 20 20 70 68 72 61 73 65 2c 20  to a .  phrase, 
0240: 61 6e 64 20 74 68 65 20 66 75 6c 6c 2d 74 65 78  and the full-tex
0250: 74 20 71 75 65 72 79 20 73 79 73 74 65 6d 20 66  t query system f
0260: 69 6e 64 73 20 74 68 65 20 73 65 74 20 6f 66 20  inds the set of 
0270: 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 62  documents that b
0280: 65 73 74 20 0a 20 20 6d 61 74 63 68 65 73 20 74  est .  matches t
0290: 68 6f 73 65 20 74 65 72 6d 73 20 63 6f 6e 73 69  hose terms consi
02a0: 64 65 72 69 6e 67 20 74 68 65 20 6f 70 65 72 61  dering the opera
02b0: 74 6f 72 73 20 61 6e 64 20 67 72 6f 75 70 69 6e  tors and groupin
02c0: 67 73 20 74 68 65 20 75 73 65 72 20 68 61 73 20  gs the user has 
02d0: 0a 20 20 73 70 65 63 69 66 69 65 64 2e 20 54 68  .  specified. Th
02e0: 69 73 20 61 72 74 69 63 6c 65 20 64 65 73 63 72  is article descr
02f0: 69 62 65 73 20 74 68 65 20 64 65 70 6c 6f 79 6d  ibes the deploym
0300: 65 6e 74 20 61 6e 64 20 75 73 61 67 65 20 6f 66  ent and usage of
0310: 20 46 54 53 33 20 61 6e 64 20 46 54 53 34 2e 0a   FTS3 and FTS4..
0320: 0a 3c 70 3e 0a 20 20 46 54 53 31 20 61 6e 64 20  .<p>.  FTS1 and 
0330: 46 54 53 32 20 61 72 65 20 6f 62 73 6f 6c 65 74  FTS2 are obsolet
0340: 65 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  e full-text sear
0350: 63 68 20 6d 6f 64 75 6c 65 73 20 66 6f 72 20 53  ch modules for S
0360: 51 4c 69 74 65 2e 20 20 54 68 65 72 65 20 61 72  QLite.  There ar
0370: 65 20 6b 6e 6f 77 6e 0a 20 20 69 73 73 75 65 73  e known.  issues
0380: 20 77 69 74 68 20 74 68 65 73 65 20 6f 6c 64 65   with these olde
0390: 72 20 6d 6f 64 75 6c 65 73 20 61 6e 64 20 74 68  r modules and th
03a0: 65 69 72 20 75 73 65 20 73 68 6f 75 6c 64 20 62  eir use should b
03b0: 65 20 61 76 6f 69 64 65 64 2e 0a 20 20 50 6f 72  e avoided..  Por
03c0: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6f 72 69  tions of the ori
03d0: 67 69 6e 61 6c 20 46 54 53 33 20 63 6f 64 65 20  ginal FTS3 code 
03e0: 77 65 72 65 20 63 6f 6e 74 72 69 62 75 74 65 64  were contributed
03f0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 70   to the SQLite p
0400: 72 6f 6a 65 63 74 20 0a 20 20 62 79 20 53 63 6f  roject .  by Sco
0410: 74 74 20 48 65 73 73 20 6f 66 20 3c 61 20 68 72  tt Hess of <a hr
0420: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 67  ef="http://www.g
0430: 6f 6f 67 6c 65 2e 63 6f 6d 22 3e 47 6f 6f 67 6c  oogle.com">Googl
0440: 65 3c 2f 61 3e 2e 20 49 74 20 69 73 20 6e 6f 77  e</a>. It is now
0450: 20 0a 20 20 64 65 76 65 6c 6f 70 65 64 20 61 6e   .  developed an
0460: 64 20 6d 61 69 6e 74 61 69 6e 65 64 20 61 73 20  d maintained as 
0470: 70 61 72 74 20 6f 66 20 53 51 4c 69 74 65 2e 0a  part of SQLite..
0480: 0a 3c 68 31 3e 49 6e 74 72 6f 64 75 63 74 69 6f  .<h1>Introductio
0490: 6e 20 74 6f 20 46 54 53 33 20 61 6e 64 20 46 54  n to FTS3 and FT
04a0: 53 34 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20 54  S4</h1>..<p>.  T
04b0: 68 65 20 46 54 53 33 20 61 6e 64 20 46 54 53 34  he FTS3 and FTS4
04c0: 20 65 78 74 65 6e 73 69 6f 6e 20 6d 6f 64 75 6c   extension modul
04d0: 65 73 20 61 6c 6c 6f 77 73 20 75 73 65 72 73 20  es allows users 
04e0: 74 6f 20 63 72 65 61 74 65 20 73 70 65 63 69 61  to create specia
04f0: 6c 20 74 61 62 6c 65 73 20 77 69 74 68 20 61 20  l tables with a 
0500: 0a 20 20 62 75 69 6c 74 2d 69 6e 20 66 75 6c 6c  .  built-in full
0510: 2d 74 65 78 74 20 69 6e 64 65 78 20 28 68 65 72  -text index (her
0520: 65 61 66 74 65 72 20 22 46 54 53 20 74 61 62 6c  eafter "FTS tabl
0530: 65 73 22 29 2e 20 54 68 65 20 66 75 6c 6c 2d 74  es"). The full-t
0540: 65 78 74 20 69 6e 64 65 78 0a 20 20 61 6c 6c 6f  ext index.  allo
0550: 77 73 20 74 68 65 20 75 73 65 72 20 74 6f 20 65  ws the user to e
0560: 66 66 69 63 69 65 6e 74 6c 79 20 71 75 65 72 79  fficiently query
0570: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
0580: 72 20 61 6c 6c 20 72 6f 77 73 20 74 68 61 74 20  r all rows that 
0590: 63 6f 6e 74 61 69 6e 0a 20 20 6f 6e 65 20 6f 72  contain.  one or
05a0: 20 6d 6f 72 65 20 77 6f 72 64 73 20 28 68 65 72   more words (her
05b0: 65 61 66 74 65 72 20 22 74 6f 6b 65 6e 73 22 29  eafter "tokens")
05c0: 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 74 61  , even if the ta
05d0: 62 6c 65 0a 20 20 63 6f 6e 74 61 69 6e 73 20 6d  ble.  contains m
05e0: 61 6e 79 20 6c 61 72 67 65 20 64 6f 63 75 6d 65  any large docume
05f0: 6e 74 73 2e 0a 0a 3c 70 3e 0a 20 20 46 6f 72 20  nts...<p>.  For 
0600: 65 78 61 6d 70 6c 65 2c 20 69 66 20 65 61 63 68  example, if each
0610: 20 6f 66 20 74 68 65 20 35 31 37 34 33 30 20 64   of the 517430 d
0620: 6f 63 75 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  ocuments in the 
0630: 0a 20 20 22 3c 61 20 68 72 65 66 3d 22 68 74 74  .  "<a href="htt
0640: 70 3a 2f 2f 77 77 77 2e 63 73 2e 63 6d 75 2e 65  p://www.cs.cmu.e
0650: 64 75 2f 7e 65 6e 72 6f 6e 2f 22 3e 45 6e 72 6f  du/~enron/">Enro
0660: 6e 20 45 2d 4d 61 69 6c 20 44 61 74 61 73 65 74  n E-Mail Dataset
0670: 3c 2f 61 3e 22 0a 20 20 69 73 20 69 6e 73 65 72  </a>".  is inser
0680: 74 65 64 20 69 6e 74 6f 20 62 6f 74 68 20 61 6e  ted into both an
0690: 20 46 54 53 20 74 61 62 6c 65 20 61 6e 64 20 61   FTS table and a
06a0: 6e 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 69 74  n ordinary SQLit
06b0: 65 20 74 61 62 6c 65 0a 20 20 63 72 65 61 74 65  e table.  create
06c0: 64 20 75 73 69 6e 67 20 74 68 65 20 66 6f 6c 6c  d using the foll
06d0: 6f 77 69 6e 67 20 53 51 4c 20 73 63 72 69 70 74  owing SQL script
06e0: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
06f0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
0700: 54 41 42 4c 45 20 65 6e 72 6f 6e 64 61 74 61 31  TABLE enrondata1
0710: 20 55 53 49 4e 47 20 66 74 73 33 28 63 6f 6e 74   USING fts3(cont
0720: 65 6e 74 20 54 45 58 54 29 3b 20 20 20 20 20 2f  ent TEXT);     /
0730: 2a 20 46 54 53 33 20 74 61 62 6c 65 20 2a 2f 0a  * FTS3 table */.
0740: 20 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 65    CREATE TABLE e
0750: 6e 72 6f 6e 64 61 74 61 32 28 63 6f 6e 74 65 6e  nrondata2(conten
0760: 74 20 54 45 58 54 29 3b 20 20 20 20 20 20 20 20  t TEXT);        
0770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0780: 2f 2a 20 4f 72 64 69 6e 61 72 79 20 74 61 62 6c  /* Ordinary tabl
0790: 65 20 2a 2f 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  e */.</codeblock
07a0: 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 6e 20 65 69  >..<p>.  Then ei
07b0: 74 68 65 72 20 6f 66 20 74 68 65 20 74 77 6f 20  ther of the two 
07c0: 71 75 65 72 69 65 73 20 62 65 6c 6f 77 20 6d 61  queries below ma
07d0: 79 20 62 65 20 65 78 65 63 75 74 65 64 20 74 6f  y be executed to
07e0: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
07f0: 20 6f 66 0a 20 20 64 6f 63 75 6d 65 6e 74 73 20   of.  documents 
0800: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
0810: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65  that contain the
0820: 20 77 6f 72 64 20 22 6c 69 6e 75 78 22 20 28 33   word "linux" (3
0830: 35 31 29 2e 20 55 73 69 6e 67 20 6f 6e 65 0a 20  51). Using one. 
0840: 20 64 65 73 6b 74 6f 70 20 50 43 20 68 61 72 64   desktop PC hard
0850: 77 61 72 65 20 63 6f 6e 66 69 67 75 72 61 74 69  ware configurati
0860: 6f 6e 2c 20 74 68 65 20 71 75 65 72 79 20 6f 6e  on, the query on
0870: 20 74 68 65 20 46 54 53 33 20 74 61 62 6c 65 20   the FTS3 table 
0880: 72 65 74 75 72 6e 73 20 69 6e 0a 20 20 61 70 70  returns in.  app
0890: 72 6f 78 69 6d 61 74 65 6c 79 20 30 2e 30 33 20  roximately 0.03 
08a0: 73 65 63 6f 6e 64 73 2c 20 76 65 72 73 75 73 20  seconds, versus 
08b0: 32 32 2e 35 20 66 6f 72 20 71 75 65 72 79 69 6e  22.5 for queryin
08c0: 67 20 74 68 65 20 6f 72 64 69 6e 61 72 79 20 74  g the ordinary t
08d0: 61 62 6c 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63  able...<codebloc
08e0: 6b 3e 0a 20 20 53 45 4c 45 43 54 20 63 6f 75 6e  k>.  SELECT coun
08f0: 74 28 2a 29 20 46 52 4f 4d 20 65 6e 72 6f 6e 64  t(*) FROM enrond
0900: 61 74 61 31 20 57 48 45 52 45 20 63 6f 6e 74 65  ata1 WHERE conte
0910: 6e 74 20 4d 41 54 43 48 20 27 6c 69 6e 75 78 27  nt MATCH 'linux'
0920: 3b 20 20 2f 2a 20 30 2e 30 33 20 73 65 63 6f 6e  ;  /* 0.03 secon
0930: 64 73 20 2a 2f 0a 20 20 53 45 4c 45 43 54 20 63  ds */.  SELECT c
0940: 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 65 6e 72  ount(*) FROM enr
0950: 6f 6e 64 61 74 61 32 20 57 48 45 52 45 20 63 6f  ondata2 WHERE co
0960: 6e 74 65 6e 74 20 4c 49 4b 45 20 27 25 6c 69 6e  ntent LIKE '%lin
0970: 75 78 25 27 3b 20 2f 2a 20 32 32 2e 35 20 73 65  ux%'; /* 22.5 se
0980: 63 6f 6e 64 73 20 2a 2f 0a 3c 2f 63 6f 64 65 62  conds */.</codeb
0990: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 4f 66 20  lock>..<p>.  Of 
09a0: 63 6f 75 72 73 65 2c 20 74 68 65 20 74 77 6f 20  course, the two 
09b0: 71 75 65 72 69 65 73 20 61 62 6f 76 65 20 61 72  queries above ar
09c0: 65 20 6e 6f 74 20 65 6e 74 69 72 65 6c 79 20 65  e not entirely e
09d0: 71 75 69 76 61 6c 65 6e 74 2e 20 46 6f 72 20 65  quivalent. For e
09e0: 78 61 6d 70 6c 65 0a 20 20 74 68 65 20 4c 49 4b  xample.  the LIK
09f0: 45 20 71 75 65 72 79 20 6d 61 74 63 68 65 73 20  E query matches 
0a00: 72 6f 77 73 20 74 68 61 74 20 63 6f 6e 74 61 69  rows that contai
0a10: 6e 20 74 65 72 6d 73 20 73 75 63 68 20 61 73 20  n terms such as 
0a20: 22 6c 69 6e 75 78 6f 70 68 6f 62 65 22 0a 20 20  "linuxophobe".  
0a30: 6f 72 20 22 45 6e 74 65 72 70 72 69 73 65 4c 69  or "EnterpriseLi
0a40: 6e 75 78 22 20 28 61 73 20 69 74 20 68 61 70 70  nux" (as it happ
0a50: 65 6e 73 2c 20 74 68 65 20 45 6e 72 6f 6e 20 45  ens, the Enron E
0a60: 2d 4d 61 69 6c 20 44 61 74 61 73 65 74 20 64 6f  -Mail Dataset do
0a70: 65 73 20 6e 6f 74 0a 20 20 61 63 74 75 61 6c 6c  es not.  actuall
0a80: 79 20 63 6f 6e 74 61 69 6e 20 61 6e 79 20 73 75  y contain any su
0a90: 63 68 20 74 65 72 6d 73 29 2c 20 77 68 65 72 65  ch terms), where
0aa0: 61 73 20 74 68 65 20 4d 41 54 43 48 20 71 75 65  as the MATCH que
0ab0: 72 79 20 6f 6e 20 74 68 65 20 46 54 53 33 20 74  ry on the FTS3 t
0ac0: 61 62 6c 65 0a 20 20 73 65 6c 65 63 74 73 20 6f  able.  selects o
0ad0: 6e 6c 79 20 74 68 6f 73 65 20 72 6f 77 73 20 74  nly those rows t
0ae0: 68 61 74 20 63 6f 6e 74 61 69 6e 20 22 6c 69 6e  hat contain "lin
0af0: 75 78 22 20 61 73 20 61 20 64 69 73 63 72 65 74  ux" as a discret
0b00: 65 20 74 6f 6b 65 6e 2e 20 42 6f 74 68 20 0a 20  e token. Both . 
0b10: 20 73 65 61 72 63 68 65 73 20 61 72 65 20 63 61   searches are ca
0b20: 73 65 2d 69 6e 73 65 6e 73 69 74 69 76 65 2e 20  se-insensitive. 
0b30: 54 68 65 20 46 54 53 33 20 74 61 62 6c 65 20 63  The FTS3 table c
0b40: 6f 6e 73 75 6d 65 73 20 61 72 6f 75 6e 64 20 32  onsumes around 2
0b50: 30 30 36 20 4d 42 20 6f 6e 0a 20 20 64 69 73 6b  006 MB on.  disk
0b60: 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 6a 75 73   compared to jus
0b70: 74 20 31 34 35 33 20 4d 42 20 66 6f 72 20 74 68  t 1453 MB for th
0b80: 65 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  e ordinary table
0b90: 2e 20 55 73 69 6e 67 20 74 68 65 20 73 61 6d 65  . Using the same
0ba0: 0a 20 20 68 61 72 64 77 61 72 65 20 63 6f 6e 66  .  hardware conf
0bb0: 69 67 75 72 61 74 69 6f 6e 20 75 73 65 64 20 74  iguration used t
0bc0: 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 20 53 45  o perform the SE
0bd0: 4c 45 43 54 20 71 75 65 72 69 65 73 20 61 62 6f  LECT queries abo
0be0: 76 65 2c 20 74 68 65 20 46 54 53 33 0a 20 20 74  ve, the FTS3.  t
0bf0: 61 62 6c 65 20 74 6f 6f 6b 20 6a 75 73 74 20 75  able took just u
0c00: 6e 64 65 72 20 33 31 20 6d 69 6e 75 74 65 73 20  nder 31 minutes 
0c10: 74 6f 20 70 6f 70 75 6c 61 74 65 2c 20 76 65 72  to populate, ver
0c20: 73 75 73 20 32 35 20 66 6f 72 20 74 68 65 20 6f  sus 25 for the o
0c30: 72 64 69 6e 61 72 79 0a 20 20 74 61 62 6c 65 2e  rdinary.  table.
0c40: 0a 0a 3c 68 32 3e 44 69 66 66 65 72 65 6e 63 65  ..<h2>Difference
0c50: 73 20 62 65 74 77 65 65 6e 20 46 54 53 33 20 61  s between FTS3 a
0c60: 6e 64 20 46 54 53 34 3c 2f 68 32 3e 0a 3c 74 63  nd FTS4</h2>.<tc
0c70: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 66 74  l>hd_fragment ft
0c80: 73 34 20 46 54 53 34 3c 2f 74 63 6c 3e 0a 0a 3c  s4 FTS4</tcl>..<
0c90: 70 3e 0a 20 20 46 54 53 33 20 61 6e 64 20 46 54  p>.  FTS3 and FT
0ca0: 53 34 20 61 72 65 20 6e 65 61 72 6c 79 20 69 64  S4 are nearly id
0cb0: 65 6e 74 69 63 61 6c 2e 20 54 68 65 79 20 73 68  entical. They sh
0cc0: 61 72 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 69  are most of thei
0cd0: 72 20 63 6f 64 65 20 69 6e 20 63 6f 6d 6d 6f 6e  r code in common
0ce0: 2c 0a 20 20 61 6e 64 20 74 68 65 69 72 20 69 6e  ,.  and their in
0cf0: 74 65 72 66 61 63 65 73 20 61 72 65 20 74 68 65  terfaces are the
0d00: 20 73 61 6d 65 2e 20 54 68 65 20 64 69 66 66 65   same. The diffe
0d10: 72 65 6e 63 65 73 20 61 72 65 3a 0a 0a 3c 75 6c  rences are:..<ul
0d20: 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 46 54 53 34  >.  <li> <p>FTS4
0d30: 20 63 6f 6e 74 61 69 6e 73 20 71 75 65 72 79 20   contains query 
0d40: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 70 74 69  performance opti
0d50: 6d 69 7a 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  mizations that m
0d60: 61 79 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79  ay significantly
0d70: 0a 20 20 20 20 20 20 20 69 6d 70 72 6f 76 65 20  .       improve 
0d80: 74 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  the performance 
0d90: 6f 66 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  of full-text que
0da0: 72 69 65 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ries that contai
0db0: 6e 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65  n terms that are
0dc0: 0a 20 20 20 20 20 20 20 76 65 72 79 20 63 6f 6d  .       very com
0dd0: 6d 6f 6e 20 28 70 72 65 73 65 6e 74 20 69 6e 20  mon (present in 
0de0: 61 20 6c 61 72 67 65 20 70 65 72 63 65 6e 74 61  a large percenta
0df0: 67 65 20 6f 66 20 74 61 62 6c 65 20 72 6f 77 73  ge of table rows
0e00: 29 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 46 54  )...  <li> <p>FT
0e10: 53 34 20 73 75 70 70 6f 72 74 73 20 73 6f 6d 65  S4 supports some
0e20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
0e30: 6f 6e 73 20 74 68 61 74 20 6d 61 79 20 75 73 65  ons that may use
0e40: 64 20 77 69 74 68 20 74 68 65 20 5b 6d 61 74 63  d with the [matc
0e50: 68 69 6e 66 6f 28 29 5d 0a 20 20 20 20 20 20 20  hinfo()].       
0e60: 66 75 6e 63 74 69 6f 6e 2e 20 0a 0a 20 20 3c 6c  function. ..  <l
0e70: 69 3e 20 3c 70 3e 42 65 63 61 75 73 65 20 69 74  i> <p>Because it
0e80: 20 73 74 6f 72 65 73 20 65 78 74 72 61 20 69 6e   stores extra in
0e90: 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 64 69 73  formation on dis
0ea0: 6b 20 69 6e 20 74 77 6f 20 6e 65 77 20 0a 20 20  k in two new .  
0eb0: 20 20 20 20 20 5b 46 54 53 20 73 68 61 64 6f 77       [FTS shadow
0ec0: 20 74 61 62 6c 65 73 7c 73 68 61 64 6f 77 20 74   tables|shadow t
0ed0: 61 62 6c 65 73 5d 20 69 6e 20 6f 72 64 65 72 20  ables] in order 
0ee0: 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65 20 70  to support the p
0ef0: 65 72 66 6f 72 6d 61 6e 63 65 0a 20 20 20 20 20  erformance.     
0f00: 20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20    optimizations 
0f10: 61 6e 64 20 65 78 74 72 61 20 6d 61 74 63 68 69  and extra matchi
0f20: 6e 66 6f 28 29 20 6f 70 74 69 6f 6e 73 2c 20 46  nfo() options, F
0f30: 54 53 34 20 74 61 62 6c 65 73 20 6d 61 79 20 63  TS4 tables may c
0f40: 6f 6e 73 75 6d 65 20 6d 6f 72 65 0a 20 20 20 20  onsume more.    
0f50: 20 20 20 64 69 73 6b 20 73 70 61 63 65 20 74 68     disk space th
0f60: 61 6e 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  an the equivalen
0f70: 74 20 74 61 62 6c 65 20 63 72 65 61 74 65 64 20  t table created 
0f80: 75 73 69 6e 67 20 46 54 53 33 2e 20 55 73 75 61  using FTS3. Usua
0f90: 6c 6c 79 20 74 68 65 20 6f 76 65 72 68 65 61 64  lly the overhead
0fa0: 0a 20 20 20 20 20 20 20 69 73 20 31 2d 32 25 20  .       is 1-2% 
0fb0: 6f 72 20 6c 65 73 73 2c 20 62 75 74 20 6d 61 79  or less, but may
0fc0: 20 62 65 20 61 73 20 68 69 67 68 20 61 73 20 31   be as high as 1
0fd0: 30 25 20 69 66 20 74 68 65 20 64 6f 63 75 6d 65  0% if the docume
0fe0: 6e 74 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68  nts stored in th
0ff0: 65 0a 20 20 20 20 20 20 20 46 54 53 20 74 61 62  e.       FTS tab
1000: 6c 65 20 61 72 65 20 76 65 72 79 20 73 6d 61 6c  le are very smal
1010: 6c 2e 20 54 68 65 20 6f 76 65 72 68 65 61 64 20  l. The overhead 
1020: 6d 61 79 20 62 65 20 72 65 64 75 63 65 64 20 62  may be reduced b
1030: 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65  y specifying the
1040: 0a 20 20 20 20 20 20 20 64 69 72 65 63 74 69 76  .       directiv
1050: 65 20 5b 46 54 53 34 20 6d 61 74 63 68 69 6e 66  e [FTS4 matchinf
1060: 6f 20 6f 70 74 69 6f 6e 7c 22 6d 61 74 63 68 69  o option|"matchi
1070: 6e 66 6f 3d 66 74 73 33 22 5d 20 61 73 20 70 61  nfo=fts3"] as pa
1080: 72 74 20 6f 66 20 74 68 65 20 46 54 53 34 20 74  rt of the FTS4 t
1090: 61 62 6c 65 0a 20 20 20 20 20 20 20 64 65 63 6c  able.       decl
10a0: 61 72 61 74 69 6f 6e 2c 20 62 75 74 20 74 68 69  aration, but thi
10b0: 73 20 63 6f 6d 65 73 20 61 74 20 74 68 65 20 65  s comes at the e
10c0: 78 70 65 6e 73 65 20 6f 66 20 73 61 63 72 69 66  xpense of sacrif
10d0: 69 63 69 6e 67 20 73 6f 6d 65 20 6f 66 20 74 68  icing some of th
10e0: 65 0a 20 20 20 20 20 20 20 65 78 74 72 61 20 73  e.       extra s
10f0: 75 70 70 6f 72 74 65 64 20 6d 61 74 63 68 69 6e  upported matchin
1100: 66 6f 28 29 20 6f 70 74 69 6f 6e 73 2e 0a 0a 20  fo() options... 
1110: 20 3c 6c 69 3e 20 3c 70 3e 46 54 53 34 20 70 72   <li> <p>FTS4 pr
1120: 6f 76 69 64 65 73 20 68 6f 6f 6b 73 20 28 74 68  ovides hooks (th
1130: 65 20 63 6f 6d 70 72 65 73 73 20 61 6e 64 20 75  e compress and u
1140: 6e 63 6f 6d 70 72 65 73 73 20 0a 20 20 20 20 20  ncompress .     
1150: 20 20 5b 46 54 53 34 20 6f 70 74 69 6f 6e 73 7c    [FTS4 options|
1160: 6f 70 74 69 6f 6e 73 5d 29 20 61 6c 6c 6f 77 69  options]) allowi
1170: 6e 67 20 64 61 74 61 20 74 6f 20 62 65 20 73 74  ng data to be st
1180: 6f 72 65 64 20 69 6e 20 61 20 63 6f 6d 70 72 65  ored in a compre
1190: 73 73 65 64 20 0a 20 20 20 20 20 20 20 66 6f 72  ssed .       for
11a0: 6d 2c 20 72 65 64 75 63 69 6e 67 20 64 69 73 6b  m, reducing disk
11b0: 20 75 73 61 67 65 20 61 6e 64 20 49 4f 2e 0a 3c   usage and IO..<
11c0: 2f 75 6c 3e 0a 0a 3c 70 3e 0a 20 20 46 54 53 34  /ul>..<p>.  FTS4
11d0: 20 69 73 20 61 6e 20 65 6e 68 61 6e 63 65 6d 65   is an enhanceme
11e0: 6e 74 20 74 6f 20 46 54 53 33 2e 20 20 46 54 53  nt to FTS3.  FTS
11f0: 33 20 68 61 73 20 62 65 65 6e 20 61 76 61 69 6c  3 has been avail
1200: 61 62 6c 65 20 73 69 6e 63 65 20 53 51 4c 69 74  able since SQLit
1210: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  e [version 3.5.0
1220: 5d 20 69 6e 0a 20 20 32 30 30 37 2d 30 39 2d 30  ] in.  2007-09-0
1230: 34 2e 20 20 54 68 65 20 65 6e 68 61 6e 63 65 6d  4.  The enhancem
1240: 65 6e 74 73 20 66 6f 72 20 46 54 53 34 20 77 65  ents for FTS4 we
1250: 72 65 20 61 64 64 65 64 20 77 69 74 68 20 53 51  re added with SQ
1260: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
1270: 37 2e 34 5d 20 6f 6e 20 32 30 31 30 2d 31 32 2d  7.4] on 2010-12-
1280: 30 38 2e 0a 0a 3c 70 3e 0a 20 20 57 68 69 63 68  08...<p>.  Which
1290: 20 6d 6f 64 75 6c 65 2c 20 46 54 53 33 20 6f 72   module, FTS3 or
12a0: 20 46 54 53 34 2c 20 73 68 6f 75 6c 64 20 79 6f   FTS4, should yo
12b0: 75 20 75 73 65 20 69 6e 20 79 6f 75 72 20 61 70  u use in your ap
12c0: 70 6c 69 63 61 74 69 6f 6e 3f 20 20 46 54 53 34  plication?  FTS4
12d0: 20 69 73 0a 20 20 73 6f 6d 65 74 69 6d 65 73 20   is.  sometimes 
12e0: 73 69 67 6e 69 66 69 63 61 6e 74 6c 79 20 66 61  significantly fa
12f0: 73 74 65 72 20 74 68 61 6e 20 46 54 53 33 2c 20  ster than FTS3, 
1300: 65 76 65 6e 20 6f 72 64 65 72 73 20 6f 66 20 6d  even orders of m
1310: 61 67 6e 69 74 75 64 65 20 66 61 73 74 65 72 0a  agnitude faster.
1320: 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74    depending on t
1330: 68 65 20 71 75 65 72 79 2c 20 74 68 6f 75 67 68  he query, though
1340: 20 69 6e 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 63   in the common c
1350: 61 73 65 20 74 68 65 20 70 65 72 66 6f 72 6d 61  ase the performa
1360: 6e 63 65 20 6f 66 20 74 68 65 20 74 77 6f 0a 20  nce of the two. 
1370: 20 6d 6f 64 75 6c 65 73 20 69 73 20 73 69 6d 69   modules is simi
1380: 6c 61 72 2e 20 46 54 53 34 20 61 6c 73 6f 20 6f  lar. FTS4 also o
1390: 66 66 65 72 73 20 74 68 65 20 65 6e 68 61 6e 63  ffers the enhanc
13a0: 65 64 20 5b 6d 61 74 63 68 69 6e 66 6f 28 29 5d  ed [matchinfo()]
13b0: 20 6f 75 74 70 75 74 73 20 77 68 69 63 68 0a 20   outputs which. 
13c0: 20 63 61 6e 20 62 65 20 75 73 65 66 75 6c 20 69   can be useful i
13d0: 6e 20 72 61 6e 6b 69 6e 67 20 74 68 65 20 72 65  n ranking the re
13e0: 73 75 6c 74 73 20 6f 66 20 61 20 5b 46 54 53 20  sults of a [FTS 
13f0: 4d 41 54 43 48 7c 4d 41 54 43 48 5d 20 6f 70 65  MATCH|MATCH] ope
1400: 72 61 74 69 6f 6e 2e 20 20 4f 6e 20 74 68 65 0a  ration.  On the.
1410: 20 20 6f 74 68 65 72 20 68 61 6e 64 2c 20 69 6e    other hand, in
1420: 20 74 68 65 20 61 62 73 65 6e 63 65 20 6f 66 20   the absence of 
1430: 61 20 5b 46 54 53 34 20 6d 61 74 63 68 69 6e 66  a [FTS4 matchinf
1440: 6f 20 6f 70 74 69 6f 6e 7c 6d 61 74 63 68 69 6e  o option|matchin
1450: 66 6f 3d 66 74 73 33 5d 20 64 69 72 65 63 74 69  fo=fts3] directi
1460: 76 65 20 46 54 53 34 20 72 65 71 75 69 72 65 73  ve FTS4 requires
1470: 20 61 20 6c 69 74 74 6c 65 0a 20 20 6d 6f 72 65   a little.  more
1480: 20 64 69 73 6b 20 73 70 61 63 65 20 74 68 61 6e   disk space than
1490: 20 46 54 53 33 2c 20 74 68 6f 75 67 68 20 6f 6e   FTS3, though on
14a0: 6c 79 20 61 20 70 65 72 63 65 6e 74 20 6f 66 20  ly a percent of 
14b0: 74 77 6f 20 69 6e 20 6d 6f 73 74 20 63 61 73 65  two in most case
14c0: 73 2e 0a 0a 3c 70 3e 0a 20 20 46 6f 72 20 6e 65  s...<p>.  For ne
14d0: 77 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  wer applications
14e0: 2c 20 46 54 53 34 20 69 73 20 72 65 63 6f 6d 6d  , FTS4 is recomm
14f0: 65 6e 64 65 64 3b 20 74 68 6f 75 67 68 20 69 66  ended; though if
1500: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
1510: 69 74 68 20 6f 6c 64 65 72 20 0a 20 20 76 65 72  ith older .  ver
1520: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1530: 69 73 20 69 6d 70 6f 72 74 61 6e 74 2c 20 74 68  is important, th
1540: 65 6e 20 46 54 53 33 20 77 69 6c 6c 20 75 73 75  en FTS3 will usu
1550: 61 6c 6c 79 20 73 65 72 76 65 20 6a 75 73 74 20  ally serve just 
1560: 61 73 20 77 65 6c 6c 2e 20 20 0a 0a 3c 68 32 3e  as well.  ..<h2>
1570: 43 72 65 61 74 69 6e 67 20 61 6e 64 20 44 65 73  Creating and Des
1580: 74 72 6f 79 69 6e 67 20 46 54 53 20 54 61 62 6c  troying FTS Tabl
1590: 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 4c  es</h2>..<p>.  L
15a0: 69 6b 65 20 6f 74 68 65 72 20 76 69 72 74 75 61  ike other virtua
15b0: 6c 20 74 61 62 6c 65 20 74 79 70 65 73 2c 20 6e  l table types, n
15c0: 65 77 20 46 54 53 20 74 61 62 6c 65 73 20 61 72  ew FTS tables ar
15d0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
15e0: 61 20 0a 20 20 5b 43 52 45 41 54 45 20 56 49 52  a .  [CREATE VIR
15f0: 54 55 41 4c 20 54 41 42 4c 45 5d 20 73 74 61 74  TUAL TABLE] stat
1600: 65 6d 65 6e 74 2e 20 54 68 65 20 6d 6f 64 75 6c  ement. The modul
1610: 65 20 6e 61 6d 65 2c 20 77 68 69 63 68 20 66 6f  e name, which fo
1620: 6c 6c 6f 77 73 0a 20 20 74 68 65 20 55 53 49 4e  llows.  the USIN
1630: 47 20 6b 65 79 77 6f 72 64 2c 20 69 73 20 65 69  G keyword, is ei
1640: 74 68 65 72 20 22 66 74 73 33 22 20 6f 72 20 22  ther "fts3" or "
1650: 66 74 73 34 22 2e 20 54 68 65 20 76 69 72 74 75  fts4". The virtu
1660: 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20  al table module 
1670: 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 0a 20 20  arguments may.  
1680: 62 65 20 6c 65 66 74 20 65 6d 70 74 79 2c 20 69  be left empty, i
1690: 6e 20 77 68 69 63 68 20 63 61 73 65 20 61 6e 20  n which case an 
16a0: 46 54 53 20 74 61 62 6c 65 20 77 69 74 68 20 61  FTS table with a
16b0: 20 73 69 6e 67 6c 65 20 75 73 65 72 2d 64 65 66   single user-def
16c0: 69 6e 65 64 20 0a 20 20 63 6f 6c 75 6d 6e 20 6e  ined .  column n
16d0: 61 6d 65 64 20 22 63 6f 6e 74 65 6e 74 22 20 69  amed "content" i
16e0: 73 20 63 72 65 61 74 65 64 2e 20 41 6c 74 65 72  s created. Alter
16f0: 6e 61 74 69 76 65 6c 79 2c 20 74 68 65 20 6d 6f  natively, the mo
1700: 64 75 6c 65 20 61 72 67 75 6d 65 6e 74 73 0a 20  dule arguments. 
1710: 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 20 61   may be passed a
1720: 20 6c 69 73 74 20 6f 66 20 63 6f 6d 6d 61 20 73   list of comma s
1730: 65 70 61 72 61 74 65 64 20 63 6f 6c 75 6d 6e 20  eparated column 
1740: 6e 61 6d 65 73 2e 20 0a 0a 3c 70 3e 0a 20 20 49  names. ..<p>.  I
1750: 66 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  f column names a
1760: 72 65 20 65 78 70 6c 69 63 69 74 6c 79 20 70 72  re explicitly pr
1770: 6f 76 69 64 65 64 20 66 6f 72 20 74 68 65 20 46  ovided for the F
1780: 54 53 20 74 61 62 6c 65 20 61 73 20 70 61 72 74  TS table as part
1790: 20 6f 66 0a 20 20 74 68 65 20 43 52 45 41 54 45   of.  the CREATE
17a0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73   VIRTUAL TABLE s
17b0: 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 61  tatement, then a
17c0: 20 64 61 74 61 74 79 70 65 20 6e 61 6d 65 20 6d   datatype name m
17d0: 61 79 20 62 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  ay be optionally
17e0: 20 0a 20 20 73 70 65 63 69 66 69 65 64 20 66 6f   .  specified fo
17f0: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 54  r each column. T
1800: 68 69 73 20 69 73 20 70 75 72 65 20 73 79 6e 74  his is pure synt
1810: 61 63 74 69 63 20 73 75 67 61 72 2c 20 74 68 65  actic sugar, the
1820: 0a 20 20 73 75 70 70 6c 69 65 64 20 74 79 70 65  .  supplied type
1830: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 75 73  names are not us
1840: 65 64 20 62 79 20 46 54 53 20 6f 72 20 74 68 65  ed by FTS or the
1850: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 66 6f 72   SQLite core for
1860: 20 61 6e 79 0a 20 20 70 75 72 70 6f 73 65 2e 20   any.  purpose. 
1870: 54 68 65 20 73 61 6d 65 20 61 70 70 6c 69 65 73  The same applies
1880: 20 74 6f 20 61 6e 79 20 63 6f 6e 73 74 72 61 69   to any constrai
1890: 6e 74 73 20 73 70 65 63 69 66 69 65 64 20 61 6c  nts specified al
18a0: 6f 6e 67 20 77 69 74 68 20 61 6e 0a 20 20 46 54  ong with an.  FT
18b0: 53 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2d 20  S column name - 
18c0: 74 68 65 79 20 61 72 65 20 70 61 72 73 65 64 20  they are parsed 
18d0: 62 75 74 20 6e 6f 74 20 75 73 65 64 20 6f 72 20  but not used or 
18e0: 72 65 63 6f 72 64 65 64 20 62 79 20 74 68 65 20  recorded by the 
18f0: 73 79 73 74 65 6d 0a 20 20 69 6e 20 61 6e 79 20  system.  in any 
1900: 77 61 79 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  way...<codeblock
1910: 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65  >.  <i>-- Create
1920: 20 61 6e 20 46 54 53 20 74 61 62 6c 65 20 6e 61   an FTS table na
1930: 6d 65 64 20 22 64 61 74 61 22 20 77 69 74 68 20  med "data" with 
1940: 6f 6e 65 20 63 6f 6c 75 6d 6e 20 2d 20 22 63 6f  one column - "co
1950: 6e 74 65 6e 74 22 3a 3c 2f 69 3e 0a 20 20 43 52  ntent":</i>.  CR
1960: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
1970: 4c 45 20 64 61 74 61 20 55 53 49 4e 47 20 66 74  LE data USING ft
1980: 73 33 28 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43  s3();..  <i>-- C
1990: 72 65 61 74 65 20 61 6e 20 46 54 53 20 74 61 62  reate an FTS tab
19a0: 6c 65 20 6e 61 6d 65 64 20 22 70 61 67 65 73 22  le named "pages"
19b0: 20 77 69 74 68 20 74 68 72 65 65 20 63 6f 6c 75   with three colu
19c0: 6d 6e 73 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  mns:</i>.  CREAT
19d0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
19e0: 70 61 67 65 73 20 55 53 49 4e 47 20 66 74 73 34  pages USING fts4
19f0: 28 74 69 74 6c 65 2c 20 6b 65 79 77 6f 72 64 73  (title, keywords
1a00: 2c 20 62 6f 64 79 29 3b 0a 0a 20 20 3c 69 3e 2d  , body);..  <i>-
1a10: 2d 20 43 72 65 61 74 65 20 61 6e 20 46 54 53 20  - Create an FTS 
1a20: 74 61 62 6c 65 20 6e 61 6d 65 64 20 22 6d 61 69  table named "mai
1a30: 6c 22 20 77 69 74 68 20 74 77 6f 20 63 6f 6c 75  l" with two colu
1a40: 6d 6e 73 2e 20 44 61 74 61 74 79 70 65 73 0a 20  mns. Datatypes. 
1a50: 20 2d 2d 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 63   -- and column c
1a60: 6f 6e 73 74 72 61 69 6e 74 73 20 61 72 65 20 73  onstraints are s
1a70: 70 65 63 69 66 69 65 64 20 61 6c 6f 6e 67 20 77  pecified along w
1a80: 69 74 68 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  ith each column.
1a90: 20 54 68 65 73 65 0a 20 20 2d 2d 20 61 72 65 20   These.  -- are 
1aa0: 63 6f 6d 70 6c 65 74 65 6c 79 20 69 67 6e 6f 72  completely ignor
1ab0: 65 64 20 62 79 20 46 54 53 20 61 6e 64 20 53 51  ed by FTS and SQ
1ac0: 4c 69 74 65 2e 20 3c 2f 69 3e 0a 20 20 43 52 45  Lite. </i>.  CRE
1ad0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
1ae0: 45 20 6d 61 69 6c 20 55 53 49 4e 47 20 66 74 73  E mail USING fts
1af0: 33 28 0a 20 20 20 20 73 75 62 6a 65 63 74 20 56  3(.    subject V
1b00: 41 52 43 48 41 52 28 32 35 36 29 20 4e 4f 54 20  ARCHAR(256) NOT 
1b10: 4e 55 4c 4c 2c 0a 20 20 20 20 62 6f 64 79 20 54  NULL,.    body T
1b20: 45 58 54 20 43 48 45 43 4b 28 6c 65 6e 67 74 68  EXT CHECK(length
1b30: 28 62 6f 64 79 29 26 6c 74 3b 31 30 32 34 30 29  (body)&lt;10240)
1b40: 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  .  );.</codebloc
1b50: 6b 3e 0a 0a 3c 70 3e 0a 20 20 41 73 20 77 65 6c  k>..<p>.  As wel
1b60: 6c 20 61 73 20 61 20 6c 69 73 74 20 6f 66 20 63  l as a list of c
1b70: 6f 6c 75 6d 6e 73 2c 20 74 68 65 20 6d 6f 64 75  olumns, the modu
1b80: 6c 65 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73  le arguments pas
1b90: 73 65 64 20 74 6f 20 61 20 43 52 45 41 54 45 0a  sed to a CREATE.
1ba0: 20 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20    VIRTUAL TABLE 
1bb0: 73 74 61 74 65 6d 65 6e 74 20 75 73 65 64 20 74  statement used t
1bc0: 6f 20 63 72 65 61 74 65 20 61 6e 20 46 54 53 20  o create an FTS 
1bd0: 74 61 62 6c 65 20 6d 61 79 20 62 65 20 75 73 65  table may be use
1be0: 64 20 74 6f 20 73 70 65 63 69 66 79 0a 20 20 61  d to specify.  a
1bf0: 20 5b 74 6f 6b 65 6e 69 7a 65 72 5d 2e 20 54 68   [tokenizer]. Th
1c00: 69 73 20 69 73 20 64 6f 6e 65 20 62 79 20 73 70  is is done by sp
1c10: 65 63 69 66 79 69 6e 67 20 61 20 73 74 72 69 6e  ecifying a strin
1c20: 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 0a 20 20  g of the form.  
1c30: 22 74 6f 6b 65 6e 69 7a 65 3d 26 6c 74 3b 74 6f  "tokenize=&lt;to
1c40: 6b 65 6e 69 7a 65 72 20 6e 61 6d 65 26 67 74 3b  kenizer name&gt;
1c50: 20 26 6c 74 3b 74 6f 6b 65 6e 69 7a 65 72 20 61   &lt;tokenizer a
1c60: 72 67 73 26 67 74 3b 22 20 69 6e 20 70 6c 61 63  rgs&gt;" in plac
1c70: 65 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 0a 20 20  e of a column.  
1c80: 6e 61 6d 65 2c 20 77 68 65 72 65 20 26 6c 74 3b  name, where &lt;
1c90: 74 6f 6b 65 6e 69 7a 65 72 20 6e 61 6d 65 26 67  tokenizer name&g
1ca0: 74 3b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  t; is the name o
1cb0: 66 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 20  f the tokenizer 
1cc0: 74 6f 20 75 73 65 20 61 6e 64 0a 20 20 26 6c 74  to use and.  &lt
1cd0: 3b 74 6f 6b 65 6e 69 7a 65 72 20 61 72 67 73 26  ;tokenizer args&
1ce0: 67 74 3b 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  gt; is an option
1cf0: 61 6c 20 6c 69 73 74 20 6f 66 20 77 68 69 74 65  al list of white
1d00: 73 70 61 63 65 20 73 65 70 61 72 61 74 65 64 20  space separated 
1d10: 71 75 61 6c 69 66 69 65 72 73 0a 20 20 74 6f 20  qualifiers.  to 
1d20: 70 61 73 73 20 74 6f 20 74 68 65 20 74 6f 6b 65  pass to the toke
1d30: 6e 69 7a 65 72 20 69 6d 70 6c 65 6d 65 6e 74 61  nizer implementa
1d40: 74 69 6f 6e 2e 20 41 20 74 6f 6b 65 6e 69 7a 65  tion. A tokenize
1d50: 72 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  r specification 
1d60: 6d 61 79 20 62 65 0a 20 20 70 6c 61 63 65 64 20  may be.  placed 
1d70: 61 6e 79 77 68 65 72 65 20 69 6e 20 74 68 65 20  anywhere in the 
1d80: 63 6f 6c 75 6d 6e 20 6c 69 73 74 2c 20 62 75 74  column list, but
1d90: 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 74 6f 6b   at most one tok
1da0: 65 6e 69 7a 65 72 20 64 65 63 6c 61 72 61 74 69  enizer declarati
1db0: 6f 6e 20 69 73 0a 20 20 61 6c 6c 6f 77 65 64 20  on is.  allowed 
1dc0: 66 6f 72 20 65 61 63 68 20 43 52 45 41 54 45 20  for each CREATE 
1dd0: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
1de0: 61 74 65 6d 65 6e 74 2e 20 5b 74 6f 6b 65 6e 69  atement. [tokeni
1df0: 7a 65 72 7c 53 65 65 20 62 65 6c 6f 77 5d 20 66  zer|See below] f
1e00: 6f 72 20 61 20 0a 20 20 64 65 74 61 69 6c 65 64  or a .  detailed
1e10: 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1e20: 75 73 69 6e 67 20 28 61 6e 64 2c 20 69 66 20 6e  using (and, if n
1e30: 65 63 65 73 73 61 72 79 2c 20 69 6d 70 6c 65 6d  ecessary, implem
1e40: 65 6e 74 69 6e 67 29 20 61 20 74 6f 6b 65 6e 69  enting) a tokeni
1e50: 7a 65 72 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  zer...<codeblock
1e60: 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65  >.  <i>-- Create
1e70: 20 61 6e 20 46 54 53 20 74 61 62 6c 65 20 6e 61   an FTS table na
1e80: 6d 65 64 20 22 70 61 70 65 72 73 22 20 77 69 74  med "papers" wit
1e90: 68 20 74 77 6f 20 63 6f 6c 75 6d 6e 73 20 74 68  h two columns th
1ea0: 61 74 20 75 73 65 73 3c 2f 69 3e 0a 20 20 3c 69  at uses</i>.  <i
1eb0: 3e 2d 2d 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65  >-- the tokenize
1ec0: 72 20 22 70 6f 72 74 65 72 22 2e 3c 2f 69 3e 0a  r "porter".</i>.
1ed0: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
1ee0: 20 54 41 42 4c 45 20 70 61 70 65 72 73 20 55 53   TABLE papers US
1ef0: 49 4e 47 20 66 74 73 33 28 61 75 74 68 6f 72 2c  ING fts3(author,
1f00: 20 64 6f 63 75 6d 65 6e 74 2c 20 74 6f 6b 65 6e   document, token
1f10: 69 7a 65 3d 70 6f 72 74 65 72 29 3b 0a 0a 20 20  ize=porter);..  
1f20: 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20  <i>-- Create an 
1f30: 46 54 53 20 74 61 62 6c 65 20 77 69 74 68 20 61  FTS table with a
1f40: 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 2d   single column -
1f50: 20 22 63 6f 6e 74 65 6e 74 22 20 2d 20 74 68 61   "content" - tha
1f60: 74 20 75 73 65 73 3c 2f 69 3e 0a 20 20 3c 69 3e  t uses</i>.  <i>
1f70: 2d 2d 20 74 68 65 20 22 73 69 6d 70 6c 65 22 20  -- the "simple" 
1f80: 74 6f 6b 65 6e 69 7a 65 72 2e 3c 2f 69 3e 0a 20  tokenizer.</i>. 
1f90: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
1fa0: 54 41 42 4c 45 20 64 61 74 61 20 55 53 49 4e 47  TABLE data USING
1fb0: 20 66 74 73 34 28 74 6f 6b 65 6e 69 7a 65 3d 73   fts4(tokenize=s
1fc0: 69 6d 70 6c 65 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  imple);..  <i>--
1fd0: 20 43 72 65 61 74 65 20 61 6e 20 46 54 53 20 74   Create an FTS t
1fe0: 61 62 6c 65 20 77 69 74 68 20 74 77 6f 20 63 6f  able with two co
1ff0: 6c 75 6d 6e 73 20 74 68 61 74 20 75 73 65 73 20  lumns that uses 
2000: 74 68 65 20 22 69 63 75 22 20 74 6f 6b 65 6e 69  the "icu" tokeni
2010: 7a 65 72 2e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  zer.</i>.  <i>--
2020: 20 54 68 65 20 71 75 61 6c 69 66 69 65 72 20 22   The qualifier "
2030: 65 6e 5f 41 55 22 20 69 73 20 70 61 73 73 65 64  en_AU" is passed
2040: 20 74 6f 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65   to the tokenize
2050: 72 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  r implementation
2060: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
2070: 52 54 55 41 4c 20 54 41 42 4c 45 20 6e 61 6d 65  RTUAL TABLE name
2080: 73 20 55 53 49 4e 47 20 66 74 73 33 28 61 2c 20  s USING fts3(a, 
2090: 62 2c 20 74 6f 6b 65 6e 69 7a 65 3d 69 63 75 20  b, tokenize=icu 
20a0: 65 6e 5f 41 55 29 3b 0a 3c 2f 63 6f 64 65 62 6c  en_AU);.</codebl
20b0: 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 46 54 53 20  ock>..<p>.  FTS 
20c0: 74 61 62 6c 65 73 20 6d 61 79 20 62 65 20 64 72  tables may be dr
20d0: 6f 70 70 65 64 20 66 72 6f 6d 20 74 68 65 20 64  opped from the d
20e0: 61 74 61 62 61 73 65 20 75 73 69 6e 67 20 61 6e  atabase using an
20f0: 20 6f 72 64 69 6e 61 72 79 20 5b 44 52 4f 50 20   ordinary [DROP 
2100: 54 41 42 4c 45 5d 0a 20 20 73 74 61 74 65 6d 65  TABLE].  stateme
2110: 6e 74 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  nt. For example:
2120: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
2130: 3c 69 3e 2d 2d 20 43 72 65 61 74 65 2c 20 74 68  <i>-- Create, th
2140: 65 6e 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 64  en immediately d
2150: 72 6f 70 2c 20 61 6e 20 46 54 53 34 20 74 61 62  rop, an FTS4 tab
2160: 6c 65 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45  le.</i>.  CREATE
2170: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 64   VIRTUAL TABLE d
2180: 61 74 61 20 55 53 49 4e 47 20 66 74 73 34 28 29  ata USING fts4()
2190: 3b 0a 20 20 44 52 4f 50 20 54 41 42 4c 45 20 64  ;.  DROP TABLE d
21a0: 61 74 61 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ata;.</codeblock
21b0: 3e 0a 0a 3c 68 32 3e 50 6f 70 75 6c 61 74 69 6e  >..<h2>Populatin
21c0: 67 20 46 54 53 20 54 61 62 6c 65 73 3c 2f 68 32  g FTS Tables</h2
21d0: 3e 0a 0a 20 20 3c 70 3e 0a 20 20 20 20 46 54 53  >..  <p>.    FTS
21e0: 20 74 61 62 6c 65 73 20 61 72 65 20 70 6f 70 75   tables are popu
21f0: 6c 61 74 65 64 20 75 73 69 6e 67 20 5b 49 4e 53  lated using [INS
2200: 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 61  ERT], [UPDATE] a
2210: 6e 64 20 5b 44 45 4c 45 54 45 5d 0a 20 20 20 20  nd [DELETE].    
2220: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
2230: 65 20 73 61 6d 65 20 77 61 79 20 61 73 20 6f 72  e same way as or
2240: 64 69 6e 61 72 79 20 53 51 4c 69 74 65 20 74 61  dinary SQLite ta
2250: 62 6c 65 73 20 61 72 65 2e 0a 0a 20 20 3c 70 3e  bles are...  <p>
2260: 0a 20 20 20 20 41 73 20 77 65 6c 6c 20 61 73 20  .    As well as 
2270: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6e 61 6d 65  the columns name
2280: 64 20 62 79 20 74 68 65 20 75 73 65 72 20 28 6f  d by the user (o
2290: 72 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 22 20  r the "content" 
22a0: 63 6f 6c 75 6d 6e 20 69 66 20 6e 6f 0a 20 20 20  column if no.   
22b0: 20 6d 6f 64 75 6c 65 20 61 72 67 75 6d 65 6e 74   module argument
22c0: 73 20 77 65 72 65 20 73 70 65 63 69 66 69 65 64  s were specified
22d0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
22e0: 5b 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20  [CREATE VIRTUAL 
22f0: 54 41 42 4c 45 5d 20 0a 20 20 20 20 73 74 61 74  TABLE] .    stat
2300: 65 6d 65 6e 74 29 2c 20 65 61 63 68 20 46 54 53  ement), each FTS
2310: 20 74 61 62 6c 65 20 68 61 73 20 61 20 22 72 6f   table has a "ro
2320: 77 69 64 22 20 63 6f 6c 75 6d 6e 2e 20 54 68 65  wid" column. The
2330: 20 72 6f 77 69 64 20 6f 66 20 61 6e 20 46 54 53   rowid of an FTS
2340: 0a 20 20 20 20 74 61 62 6c 65 20 62 65 68 61 76  .    table behav
2350: 65 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 77  es in the same w
2360: 61 79 20 61 73 20 74 68 65 20 72 6f 77 69 64 20  ay as the rowid 
2370: 63 6f 6c 75 6d 6e 20 6f 66 20 61 6e 20 6f 72 64  column of an ord
2380: 69 6e 61 72 79 20 53 51 4c 69 74 65 20 0a 20 20  inary SQLite .  
2390: 20 20 74 61 62 6c 65 2c 20 65 78 63 65 70 74 20    table, except 
23a0: 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  that the values 
23b0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 72 6f  stored in the ro
23c0: 77 69 64 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 6e  wid column of an
23d0: 20 46 54 53 20 74 61 62 6c 65 20 0a 20 20 20 20   FTS table .    
23e0: 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
23f0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
2400: 20 69 73 20 72 65 62 75 69 6c 74 20 75 73 69 6e   is rebuilt usin
2410: 67 20 74 68 65 20 5b 56 41 43 55 55 4d 5d 20 63  g the [VACUUM] c
2420: 6f 6d 6d 61 6e 64 2e 20 0a 20 20 20 20 46 6f 72  ommand. .    For
2430: 20 46 54 53 20 74 61 62 6c 65 73 2c 20 22 64 6f   FTS tables, "do
2440: 63 69 64 22 20 69 73 20 61 6c 6c 6f 77 65 64 20  cid" is allowed 
2450: 61 73 20 61 6e 20 61 6c 69 61 73 20 61 6c 6f 6e  as an alias alon
2460: 67 20 77 69 74 68 20 74 68 65 20 75 73 75 61 6c  g with the usual
2470: 20 22 72 6f 77 69 64 22 2c 0a 20 20 20 20 22 6f   "rowid",.    "o
2480: 69 64 22 20 61 6e 64 20 22 5f 6f 69 64 5f 22 20  id" and "_oid_" 
2490: 69 64 65 6e 74 69 66 69 65 72 73 2e 20 41 74 74  identifiers. Att
24a0: 65 6d 70 74 69 6e 67 20 74 6f 20 69 6e 73 65 72  empting to inser
24b0: 74 20 6f 72 20 75 70 64 61 74 65 20 61 20 72 6f  t or update a ro
24c0: 77 20 77 69 74 68 20 61 20 0a 20 20 20 20 64 6f  w with a .    do
24d0: 63 69 64 20 76 61 6c 75 65 20 74 68 61 74 20 61  cid value that a
24e0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 20 69 6e  lready exists in
24f0: 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61 6e   the table is an
2500: 20 65 72 72 6f 72 2c 20 6a 75 73 74 20 61 73 20   error, just as 
2510: 69 74 20 77 6f 75 6c 64 20 0a 20 20 20 20 62 65  it would .    be
2520: 20 77 69 74 68 20 61 6e 20 6f 72 64 69 6e 61 72   with an ordinar
2530: 79 20 53 51 4c 69 74 65 20 74 61 62 6c 65 2e 0a  y SQLite table..
2540: 0a 20 20 3c 70 3e 0a 20 20 20 20 54 68 65 72 65  .  <p>.    There
2550: 20 69 73 20 6f 6e 65 20 6f 74 68 65 72 20 73 75   is one other su
2560: 62 74 6c 65 20 64 69 66 66 65 72 65 6e 63 65 20  btle difference 
2570: 62 65 74 77 65 65 6e 20 22 64 6f 63 69 64 22 20  between "docid" 
2580: 61 6e 64 20 74 68 65 20 6e 6f 72 6d 61 6c 20 53  and the normal S
2590: 51 4c 69 74 65 0a 20 20 20 20 61 6c 69 61 73 65  QLite.    aliase
25a0: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 20  s for the rowid 
25b0: 63 6f 6c 75 6d 6e 2e 20 4e 6f 72 6d 61 6c 6c 79  column. Normally
25c0: 2c 20 69 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  , if an INSERT o
25d0: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
25e0: 6e 74 20 0a 20 20 20 20 61 73 73 69 67 6e 73 20  nt .    assigns 
25f0: 64 69 73 63 72 65 74 65 20 76 61 6c 75 65 73 20  discrete values 
2600: 74 6f 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 61  to two or more a
2610: 6c 69 61 73 65 73 20 6f 66 20 74 68 65 20 72 6f  liases of the ro
2620: 77 69 64 20 63 6f 6c 75 6d 6e 2c 20 53 51 4c 69  wid column, SQLi
2630: 74 65 20 0a 20 20 20 20 77 72 69 74 65 73 20 74  te .    writes t
2640: 68 65 20 72 69 67 68 74 6d 6f 73 74 20 6f 66 20  he rightmost of 
2650: 73 75 63 68 20 76 61 6c 75 65 73 20 73 70 65 63  such values spec
2660: 69 66 69 65 64 20 69 6e 20 74 68 65 20 49 4e 53  ified in the INS
2670: 45 52 54 20 6f 72 20 55 50 44 41 54 45 0a 20 20  ERT or UPDATE.  
2680: 20 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 74    statement to t
2690: 68 65 20 64 61 74 61 62 61 73 65 2e 20 48 6f 77  he database. How
26a0: 65 76 65 72 2c 20 61 73 73 69 67 6e 69 6e 67 20  ever, assigning 
26b0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65  a non-NULL value
26c0: 20 74 6f 20 62 6f 74 68 0a 20 20 20 20 74 68 65   to both.    the
26d0: 20 22 64 6f 63 69 64 22 20 61 6e 64 20 6f 6e 65   "docid" and one
26e0: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
26f0: 53 51 4c 69 74 65 20 72 6f 77 69 64 20 61 6c 69  SQLite rowid ali
2700: 61 73 65 73 20 77 68 65 6e 20 69 6e 73 65 72 74  ases when insert
2710: 69 6e 67 20 6f 72 0a 20 20 20 20 75 70 64 61 74  ing or.    updat
2720: 69 6e 67 20 61 6e 20 46 54 53 20 74 61 62 6c 65  ing an FTS table
2730: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 61   is considered a
2740: 6e 20 65 72 72 6f 72 2e 20 53 65 65 20 62 65 6c  n error. See bel
2750: 6f 77 20 66 6f 72 20 61 6e 20 65 78 61 6d 70 6c  ow for an exampl
2760: 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e...<codeblock>.
2770: 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61    <i>-- Create a
2780: 6e 20 46 54 53 20 74 61 62 6c 65 3c 2f 69 3e 0a  n FTS table</i>.
2790: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
27a0: 20 54 41 42 4c 45 20 70 61 67 65 73 20 55 53 49   TABLE pages USI
27b0: 4e 47 20 66 74 73 34 28 74 69 74 6c 65 2c 20 62  NG fts4(title, b
27c0: 6f 64 79 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 49  ody);..  <i>-- I
27d0: 6e 73 65 72 74 20 61 20 72 6f 77 20 77 69 74 68  nsert a row with
27e0: 20 61 20 73 70 65 63 69 66 69 63 20 64 6f 63 69   a specific doci
27f0: 64 20 76 61 6c 75 65 2e 3c 2f 69 3e 0a 20 20 49  d value.</i>.  I
2800: 4e 53 45 52 54 20 49 4e 54 4f 20 70 61 67 65 73  NSERT INTO pages
2810: 28 64 6f 63 69 64 2c 20 74 69 74 6c 65 2c 20 62  (docid, title, b
2820: 6f 64 79 29 20 56 41 4c 55 45 53 28 35 33 2c 20  ody) VALUES(53, 
2830: 27 48 6f 6d 65 20 50 61 67 65 27 2c 20 27 53 51  'Home Page', 'SQ
2840: 4c 69 74 65 20 69 73 20 61 20 73 6f 66 74 77 61  Lite is a softwa
2850: 72 65 2e 2e 2e 27 29 3b 0a 0a 20 20 3c 69 3e 2d  re...');..  <i>-
2860: 2d 20 49 6e 73 65 72 74 20 61 20 72 6f 77 20 61  - Insert a row a
2870: 6e 64 20 61 6c 6c 6f 77 20 46 54 53 20 74 6f 20  nd allow FTS to 
2880: 61 73 73 69 67 6e 20 61 20 64 6f 63 69 64 20 76  assign a docid v
2890: 61 6c 75 65 20 75 73 69 6e 67 20 74 68 65 20 73  alue using the s
28a0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73  ame algorithm as
28b0: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 53 51 4c  </i>.  <i>-- SQL
28c0: 69 74 65 20 75 73 65 73 20 66 6f 72 20 6f 72 64  ite uses for ord
28d0: 69 6e 61 72 79 20 74 61 62 6c 65 73 2e 20 49 6e  inary tables. In
28e0: 20 74 68 69 73 20 63 61 73 65 20 74 68 65 20 6e   this case the n
28f0: 65 77 20 64 6f 63 69 64 20 77 69 6c 6c 20 62 65  ew docid will be
2900: 20 35 34 2c 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d   54,</i>.  <i>--
2910: 20 6f 6e 65 20 67 72 65 61 74 65 72 20 74 68 61   one greater tha
2920: 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 6f  n the largest do
2930: 63 69 64 20 63 75 72 72 65 6e 74 6c 79 20 70 72  cid currently pr
2940: 65 73 65 6e 74 20 69 6e 20 74 68 65 20 74 61 62  esent in the tab
2950: 6c 65 2e 3c 2f 69 3e 0a 20 20 49 4e 53 45 52 54  le.</i>.  INSERT
2960: 20 49 4e 54 4f 20 70 61 67 65 73 28 74 69 74 6c   INTO pages(titl
2970: 65 2c 20 62 6f 64 79 29 20 56 41 4c 55 45 53 28  e, body) VALUES(
2980: 27 44 6f 77 6e 6c 6f 61 64 27 2c 20 27 41 6c 6c  'Download', 'All
2990: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
29a0: 6f 64 65 2e 2e 2e 27 29 3b 0a 0a 20 20 3c 69 3e  ode...');..  <i>
29b0: 2d 2d 20 43 68 61 6e 67 65 20 74 68 65 20 74 69  -- Change the ti
29c0: 74 6c 65 20 6f 66 20 74 68 65 20 72 6f 77 20 6a  tle of the row j
29d0: 75 73 74 20 69 6e 73 65 72 74 65 64 2e 3c 2f 69  ust inserted.</i
29e0: 3e 0a 20 20 55 50 44 41 54 45 20 70 61 67 65 73  >.  UPDATE pages
29f0: 20 53 45 54 20 74 69 74 6c 65 20 3d 20 27 44 6f   SET title = 'Do
2a00: 77 6e 6c 6f 61 64 20 53 51 4c 69 74 65 27 20 57  wnload SQLite' W
2a10: 48 45 52 45 20 72 6f 77 69 64 20 3d 20 35 34 3b  HERE rowid = 54;
2a20: 0a 0a 20 20 3c 69 3e 2d 2d 20 44 65 6c 65 74 65  ..  <i>-- Delete
2a30: 20 74 68 65 20 65 6e 74 69 72 65 20 74 61 62 6c   the entire tabl
2a40: 65 20 63 6f 6e 74 65 6e 74 73 2e 3c 2f 69 3e 0a  e contents.</i>.
2a50: 20 20 44 45 4c 45 54 45 20 46 52 4f 4d 20 70 61    DELETE FROM pa
2a60: 67 65 73 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68  ges;..  <i>-- Th
2a70: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 73 20 61  e following is a
2a80: 6e 20 65 72 72 6f 72 2e 20 49 74 20 69 73 20 6e  n error. It is n
2a90: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 61  ot possible to a
2aa0: 73 73 69 67 6e 20 6e 6f 6e 2d 4e 55 4c 4c 20 76  ssign non-NULL v
2ab0: 61 6c 75 65 73 20 74 6f 20 62 6f 74 68 3c 2f 69  alues to both</i
2ac0: 3e 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20 72 6f  >.  <i>-- the ro
2ad0: 77 69 64 20 61 6e 64 20 64 6f 63 69 64 20 63 6f  wid and docid co
2ae0: 6c 75 6d 6e 73 20 6f 66 20 61 6e 20 46 54 53 20  lumns of an FTS 
2af0: 74 61 62 6c 65 2e 3c 2f 69 3e 0a 20 20 49 4e 53  table.</i>.  INS
2b00: 45 52 54 20 49 4e 54 4f 20 70 61 67 65 73 28 72  ERT INTO pages(r
2b10: 6f 77 69 64 2c 20 64 6f 63 69 64 2c 20 74 69 74  owid, docid, tit
2b20: 6c 65 2c 20 62 6f 64 79 29 20 56 41 4c 55 45 53  le, body) VALUES
2b30: 28 31 2c 20 32 2c 20 27 41 20 74 69 74 6c 65 27  (1, 2, 'A title'
2b40: 2c 20 27 41 20 64 6f 63 75 6d 65 6e 74 20 62 6f  , 'A document bo
2b50: 64 79 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  dy');.</codebloc
2b60: 6b 3e 0a 0a 20 20 3c 70 3e 0a 20 20 20 20 54 6f  k>..  <p>.    To
2b70: 20 73 75 70 70 6f 72 74 20 66 75 6c 6c 2d 74 65   support full-te
2b80: 78 74 20 71 75 65 72 69 65 73 2c 20 46 54 53 20  xt queries, FTS 
2b90: 6d 61 69 6e 74 61 69 6e 73 20 61 6e 20 69 6e 76  maintains an inv
2ba0: 65 72 74 65 64 20 69 6e 64 65 78 20 74 68 61 74  erted index that
2bb0: 20 6d 61 70 73 0a 20 20 20 20 66 72 6f 6d 20 65   maps.    from e
2bc0: 61 63 68 20 75 6e 69 71 75 65 20 74 65 72 6d 20  ach unique term 
2bd0: 6f 72 20 77 6f 72 64 20 74 68 61 74 20 61 70 70  or word that app
2be0: 65 61 72 73 20 69 6e 20 74 68 65 20 64 61 74 61  ears in the data
2bf0: 73 65 74 20 74 6f 20 74 68 65 20 6c 6f 63 61 74  set to the locat
2c00: 69 6f 6e 73 0a 20 20 20 20 69 6e 20 77 68 69 63  ions.    in whic
2c10: 68 20 69 74 20 61 70 70 65 61 72 73 20 77 69 74  h it appears wit
2c20: 68 69 6e 20 74 68 65 20 74 61 62 6c 65 20 63 6f  hin the table co
2c30: 6e 74 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 20  ntents. For the 
2c40: 63 75 72 69 6f 75 73 2c 20 61 20 0a 20 20 20 20  curious, a .    
2c50: 63 6f 6d 70 6c 65 74 65 20 64 65 73 63 72 69 70  complete descrip
2c60: 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 65 67  tion of the [seg
2c70: 6d 65 6e 74 20 62 74 72 65 65 7c 64 61 74 61 20  ment btree|data 
2c80: 73 74 72 75 63 74 75 72 65 5d 20 75 73 65 64 20  structure] used 
2c90: 74 6f 20 73 74 6f 72 65 0a 20 20 20 20 74 68 69  to store.    thi
2ca0: 73 20 69 6e 64 65 78 20 77 69 74 68 69 6e 20 74  s index within t
2cb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2cc0: 20 61 70 70 65 61 72 73 20 62 65 6c 6f 77 2e 20   appears below. 
2cd0: 41 20 66 65 61 74 75 72 65 20 6f 66 0a 20 20 20  A feature of.   
2ce0: 20 74 68 69 73 20 64 61 74 61 20 73 74 72 75 63   this data struc
2cf0: 74 75 72 65 20 69 73 20 74 68 61 74 20 61 74 20  ture is that at 
2d00: 61 6e 79 20 74 69 6d 65 20 74 68 65 20 64 61 74  any time the dat
2d10: 61 62 61 73 65 20 6d 61 79 20 63 6f 6e 74 61 69  abase may contai
2d20: 6e 20 6e 6f 74 0a 20 20 20 20 6f 6e 65 20 69 6e  n not.    one in
2d30: 64 65 78 20 62 2d 74 72 65 65 2c 20 62 75 74 20  dex b-tree, but 
2d40: 73 65 76 65 72 61 6c 20 64 69 66 66 65 72 65 6e  several differen
2d50: 74 20 62 2d 74 72 65 65 73 20 74 68 61 74 20 61  t b-trees that a
2d60: 72 65 20 69 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  re incrementally
2d70: 0a 20 20 20 20 6d 65 72 67 65 64 20 61 73 20 72  .    merged as r
2d80: 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64  ows are inserted
2d90: 2c 20 75 70 64 61 74 65 64 20 61 6e 64 20 64 65  , updated and de
2da0: 6c 65 74 65 64 2e 20 54 68 69 73 20 74 65 63 68  leted. This tech
2db0: 6e 69 71 75 65 20 69 6d 70 72 6f 76 65 73 20 0a  nique improves .
2dc0: 20 20 20 20 70 65 72 66 6f 72 6d 61 6e 63 65 20      performance 
2dd0: 77 68 65 6e 20 77 72 69 74 69 6e 67 20 74 6f 20  when writing to 
2de0: 61 6e 20 46 54 53 20 74 61 62 6c 65 2c 20 62 75  an FTS table, bu
2df0: 74 20 63 61 75 73 65 73 20 73 6f 6d 65 20 6f 76  t causes some ov
2e00: 65 72 68 65 61 64 20 66 6f 72 0a 20 20 20 20 66  erhead for.    f
2e10: 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 69 65 73  ull-text queries
2e20: 20 74 68 61 74 20 75 73 65 20 74 68 65 20 69 6e   that use the in
2e30: 64 65 78 2e 20 45 76 61 6c 75 61 74 69 6e 67 20  dex. Evaluating 
2e40: 74 68 65 20 73 70 65 63 69 61 6c 20 5b 22 6f 70  the special ["op
2e50: 74 69 6d 69 7a 65 22 20 63 6f 6d 6d 61 6e 64 5d  timize" command]
2e60: 2c 20 0a 20 20 20 20 61 6e 20 53 51 4c 20 73 74  , .    an SQL st
2e70: 61 74 65 6d 65 6e 74 20 6f 66 20 74 68 65 0a 20  atement of the. 
2e80: 20 20 20 66 6f 72 6d 20 22 49 4e 53 45 52 54 20     form "INSERT 
2e90: 49 4e 54 4f 20 26 6c 74 3b 66 74 73 2d 74 61 62  INTO &lt;fts-tab
2ea0: 6c 65 26 67 74 3b 28 26 6c 74 3b 66 74 73 2d 74  le&gt;(&lt;fts-t
2eb0: 61 62 6c 65 26 67 74 3b 29 20 56 41 4c 55 45 53  able&gt;) VALUES
2ec0: 28 27 6f 70 74 69 6d 69 7a 65 27 29 22 2c 0a 20  ('optimize')",. 
2ed0: 20 20 20 63 61 75 73 65 73 20 46 54 53 20 74 6f     causes FTS to
2ee0: 20 6d 65 72 67 65 20 61 6c 6c 20 65 78 69 73 74   merge all exist
2ef0: 69 6e 67 20 69 6e 64 65 78 20 62 2d 74 72 65 65  ing index b-tree
2f00: 73 20 69 6e 74 6f 20 61 20 73 69 6e 67 6c 65 20  s into a single 
2f10: 6c 61 72 67 65 0a 20 20 20 20 62 2d 74 72 65 65  large.    b-tree
2f20: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2f30: 65 6e 74 69 72 65 20 69 6e 64 65 78 2e 20 54 68  entire index. Th
2f40: 69 73 20 63 61 6e 20 62 65 20 61 6e 20 65 78 70  is can be an exp
2f50: 65 6e 73 69 76 65 20 6f 70 65 72 61 74 69 6f 6e  ensive operation
2f60: 2c 0a 20 20 20 20 62 75 74 20 6d 61 79 20 73 70  ,.    but may sp
2f70: 65 65 64 20 75 70 20 66 75 74 75 72 65 20 71 75  eed up future qu
2f80: 65 72 69 65 73 2e 20 0a 0a 20 20 3c 70 3e 0a 20  eries. ..  <p>. 
2f90: 20 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20     For example, 
2fa0: 74 6f 20 6f 70 74 69 6d 69 7a 65 20 74 68 65 20  to optimize the 
2fb0: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
2fc0: 66 6f 72 20 61 6e 20 46 54 53 20 74 61 62 6c 65  for an FTS table
2fd0: 20 6e 61 6d 65 64 0a 20 20 20 20 22 64 6f 63 73   named.    "docs
2fe0: 22 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ":..<codeblock>.
2ff0: 20 20 3c 69 3e 2d 2d 20 4f 70 74 69 6d 69 7a 65    <i>-- Optimize
3000: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 73 74   the internal st
3010: 72 75 63 74 75 72 65 20 6f 66 20 46 54 53 20 74  ructure of FTS t
3020: 61 62 6c 65 20 22 64 6f 63 73 22 2e 3c 2f 69 3e  able "docs".</i>
3030: 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 64  .  INSERT INTO d
3040: 6f 63 73 28 64 6f 63 73 29 20 56 41 4c 55 45 53  ocs(docs) VALUES
3050: 28 27 6f 70 74 69 6d 69 7a 65 27 29 3b 0a 3c 2f  ('optimize');.</
3060: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 20 20 3c 70  codeblock>..  <p
3070: 3e 0a 20 20 20 20 54 68 65 20 73 74 61 74 65 6d  >.    The statem
3080: 65 6e 74 20 61 62 6f 76 65 20 6d 61 79 20 61 70  ent above may ap
3090: 70 65 61 72 20 73 79 6e 74 61 63 74 69 63 61 6c  pear syntactical
30a0: 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 74 6f 20  ly incorrect to 
30b0: 73 6f 6d 65 2e 20 52 65 66 65 72 20 74 6f 0a 20  some. Refer to. 
30c0: 20 20 20 74 68 65 20 73 65 63 74 69 6f 6e 20 64     the section d
30d0: 65 73 63 72 69 62 69 6e 67 20 74 68 65 20 5b 73  escribing the [s
30e0: 69 6d 70 6c 65 20 66 74 73 20 71 75 65 72 69 65  imple fts querie
30f0: 73 5d 20 66 6f 72 20 61 6e 20 65 78 70 6c 61 6e  s] for an explan
3100: 61 74 69 6f 6e 2e 0a 0a 20 20 3c 70 3e 0a 20 20  ation...  <p>.  
3110: 20 20 54 68 65 72 65 20 69 73 20 61 6e 6f 74 68    There is anoth
3120: 65 72 2c 20 64 65 70 72 65 63 61 74 65 64 2c 20  er, deprecated, 
3130: 6d 65 74 68 6f 64 20 66 6f 72 20 69 6e 76 6f 6b  method for invok
3140: 69 6e 67 20 74 68 65 20 6f 70 74 69 6d 69 7a 65  ing the optimize
3150: 20 0a 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 20   .    operation 
3160: 75 73 69 6e 67 20 61 20 53 45 4c 45 43 54 20 73  using a SELECT s
3170: 74 61 74 65 6d 65 6e 74 2e 20 4e 65 77 20 63 6f  tatement. New co
3180: 64 65 20 73 68 6f 75 6c 64 20 75 73 65 20 73 74  de should use st
3190: 61 74 65 6d 65 6e 74 73 0a 20 20 20 20 73 69 6d  atements.    sim
31a0: 69 6c 61 72 20 74 6f 20 74 68 65 20 49 4e 53 45  ilar to the INSE
31b0: 52 54 20 61 62 6f 76 65 20 74 6f 20 6f 70 74 69  RT above to opti
31c0: 6d 69 7a 65 20 46 54 53 20 73 74 72 75 63 74 75  mize FTS structu
31d0: 72 65 73 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  res...<h2 tags="
31e0: 73 69 6d 70 6c 65 20 66 74 73 20 71 75 65 72 69  simple fts queri
31f0: 65 73 22 3e 53 69 6d 70 6c 65 20 46 54 53 20 51  es">Simple FTS Q
3200: 75 65 72 69 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  ueries</h2>..<p>
3210: 0a 20 20 41 73 20 66 6f 72 20 61 6c 6c 20 6f 74  .  As for all ot
3220: 68 65 72 20 53 51 4c 69 74 65 20 74 61 62 6c 65  her SQLite table
3230: 73 2c 20 76 69 72 74 75 61 6c 20 6f 72 20 6f 74  s, virtual or ot
3240: 68 65 72 77 69 73 65 2c 20 64 61 74 61 20 69 73  herwise, data is
3250: 20 72 65 74 72 69 65 76 65 64 0a 20 20 66 72 6f   retrieved.  fro
3260: 6d 20 46 54 53 20 74 61 62 6c 65 73 20 75 73 69  m FTS tables usi
3270: 6e 67 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  ng a [SELECT] st
3280: 61 74 65 6d 65 6e 74 2e 0a 0a 3c 70 3e 0a 20 20  atement...<p>.  
3290: 46 54 53 20 74 61 62 6c 65 73 20 63 61 6e 20 62  FTS tables can b
32a0: 65 20 71 75 65 72 69 65 64 20 65 66 66 69 63 69  e queried effici
32b0: 65 6e 74 6c 79 20 75 73 69 6e 67 20 53 45 4c 45  ently using SELE
32c0: 43 54 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  CT statements of
32d0: 20 74 77 6f 0a 20 20 64 69 66 66 65 72 65 6e 74   two.  different
32e0: 20 66 6f 72 6d 73 3a 0a 0a 3c 75 6c 3e 0a 20 20   forms:..<ul>.  
32f0: 3c 6c 69 3e 3c 70 3e 0a 20 20 20 20 3c 62 3e 51  <li><p>.    <b>Q
3300: 75 65 72 79 20 62 79 20 72 6f 77 69 64 3c 2f 62  uery by rowid</b
3310: 3e 2e 20 49 66 20 74 68 65 20 57 48 45 52 45 20  >. If the WHERE 
3320: 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20 53 45  clause of the SE
3330: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 20  LECT statement. 
3340: 20 20 20 63 6f 6e 74 61 69 6e 73 20 61 20 73 75     contains a su
3350: 62 2d 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20  b-clause of the 
3360: 66 6f 72 6d 20 22 72 6f 77 69 64 20 3d 20 3f 22  form "rowid = ?"
3370: 2c 20 77 68 65 72 65 20 3f 20 69 73 20 61 6e 20  , where ? is an 
3380: 53 51 4c 20 65 78 70 72 65 73 73 69 6f 6e 2c 0a  SQL expression,.
3390: 20 20 20 20 46 54 53 20 69 73 20 61 62 6c 65 20      FTS is able 
33a0: 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
33b0: 72 65 71 75 65 73 74 65 64 20 72 6f 77 20 64 69  requested row di
33c0: 72 65 63 74 6c 79 20 75 73 69 6e 67 20 74 68 65  rectly using the
33d0: 20 65 71 75 69 76 61 6c 65 6e 74 20 0a 20 20 20   equivalent .   
33e0: 20 6f 66 20 61 6e 20 53 51 4c 69 74 65 20 5b 49   of an SQLite [I
33f0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
3400: 45 59 5d 20 69 6e 64 65 78 2e 0a 0a 20 20 3c 6c  EY] index...  <l
3410: 69 3e 3c 70 3e 0a 20 20 20 20 3c 62 3e 46 75 6c  i><p>.    <b>Ful
3420: 6c 2d 74 65 78 74 20 71 75 65 72 79 3c 2f 62 3e  l-text query</b>
3430: 2e 20 49 66 20 74 68 65 20 57 48 45 52 45 20 63  . If the WHERE c
3440: 6c 61 75 73 65 20 6f 66 20 74 68 65 20 53 45 4c  lause of the SEL
3450: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
3460: 6e 74 61 69 6e 73 0a 20 20 20 20 61 20 73 75 62  ntains.    a sub
3470: 2d 63 6c 61 75 73 65 20 6f 66 20 74 68 65 20 66  -clause of the f
3480: 6f 72 6d 20 22 26 6c 74 3b 63 6f 6c 75 6d 6e 26  orm "&lt;column&
3490: 67 74 3b 20 4d 41 54 43 48 20 3f 22 2c 20 46 54  gt; MATCH ?", FT
34a0: 53 20 69 73 20 61 62 6c 65 20 74 6f 20 75 73 65  S is able to use
34b0: 20 0a 20 20 20 20 74 68 65 20 62 75 69 6c 74 2d   .    the built-
34c0: 69 6e 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  in full-text ind
34d0: 65 78 20 74 6f 20 72 65 73 74 72 69 63 74 20 74  ex to restrict t
34e0: 68 65 20 73 65 61 72 63 68 20 74 6f 20 74 68 6f  he search to tho
34f0: 73 65 20 64 6f 63 75 6d 65 6e 74 73 20 0a 20 20  se documents .  
3500: 20 20 74 68 61 74 20 6d 61 74 63 68 20 74 68 65    that match the
3510: 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79   full-text query
3520: 20 73 74 72 69 6e 67 20 73 70 65 63 69 66 69 65   string specifie
3530: 64 20 61 73 20 74 68 65 20 72 69 67 68 74 2d 68  d as the right-h
3540: 61 6e 64 20 6f 70 65 72 61 6e 64 0a 20 20 20 20  and operand.    
3550: 6f 66 20 74 68 65 20 4d 41 54 43 48 20 63 6c 61  of the MATCH cla
3560: 75 73 65 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 0a  use..</ul>..<p>.
3570: 20 20 49 66 20 6e 65 69 74 68 65 72 20 6f 66 20    If neither of 
3580: 74 68 65 73 65 20 74 77 6f 20 71 75 65 72 79 20  these two query 
3590: 73 74 72 61 74 65 67 69 65 73 20 63 61 6e 20 62  strategies can b
35a0: 65 20 75 73 65 64 2c 20 61 6c 6c 0a 20 20 71 75  e used, all.  qu
35b0: 65 72 69 65 73 20 6f 6e 20 46 54 53 20 74 61 62  eries on FTS tab
35c0: 6c 65 73 20 61 72 65 20 69 6d 70 6c 65 6d 65 6e  les are implemen
35d0: 74 65 64 20 75 73 69 6e 67 20 61 20 6c 69 6e 65  ted using a line
35e0: 61 72 20 73 63 61 6e 20 6f 66 20 74 68 65 20 65  ar scan of the e
35f0: 6e 74 69 72 65 0a 20 20 74 61 62 6c 65 2e 20 49  ntire.  table. I
3600: 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74  f the table cont
3610: 61 69 6e 73 20 6c 61 72 67 65 20 61 6d 6f 75 6e  ains large amoun
3620: 74 73 20 6f 66 20 64 61 74 61 2c 20 74 68 69 73  ts of data, this
3630: 20 6d 61 79 20 62 65 20 61 6e 20 0a 20 20 69 6d   may be an .  im
3640: 70 72 61 63 74 69 63 61 6c 20 61 70 70 72 6f 61  practical approa
3650: 63 68 20 28 74 68 65 20 66 69 72 73 74 20 65 78  ch (the first ex
3660: 61 6d 70 6c 65 20 6f 6e 20 74 68 69 73 20 70 61  ample on this pa
3670: 67 65 20 73 68 6f 77 73 20 74 68 61 74 20 61 20  ge shows that a 
3680: 6c 69 6e 65 61 72 0a 20 20 73 63 61 6e 20 6f 66  linear.  scan of
3690: 20 31 2e 35 20 47 42 20 6f 66 20 64 61 74 61 20   1.5 GB of data 
36a0: 74 61 6b 65 73 20 61 72 6f 75 6e 64 20 33 30 20  takes around 30 
36b0: 73 65 63 6f 6e 64 73 20 75 73 69 6e 67 20 61 20  seconds using a 
36c0: 6d 6f 64 65 72 6e 20 50 43 29 2e 0a 0a 3c 63 6f  modern PC)...<co
36d0: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
36e0: 20 54 68 65 20 65 78 61 6d 70 6c 65 73 20 69 6e   The examples in
36f0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 61 73 73 75   this block assu
3700: 6d 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  me the following
3710: 20 46 54 53 20 74 61 62 6c 65 3a 3c 2f 69 3e 0a   FTS table:</i>.
3720: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
3730: 20 54 41 42 4c 45 20 6d 61 69 6c 20 55 53 49 4e   TABLE mail USIN
3740: 47 20 66 74 73 33 28 73 75 62 6a 65 63 74 2c 20  G fts3(subject, 
3750: 62 6f 64 79 29 3b 0a 0a 20 20 53 45 4c 45 43 54  body);..  SELECT
3760: 20 2a 20 46 52 4f 4d 20 6d 61 69 6c 20 57 48 45   * FROM mail WHE
3770: 52 45 20 72 6f 77 69 64 20 3d 20 31 35 3b 20 20  RE rowid = 15;  
3780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69                <i
3790: 3e 2d 2d 20 46 61 73 74 2e 20 52 6f 77 69 64 20  >-- Fast. Rowid 
37a0: 6c 6f 6f 6b 75 70 2e 3c 2f 69 3e 0a 20 20 53 45  lookup.</i>.  SE
37b0: 4c 45 43 54 20 2a 20 46 52 4f 4d 20 6d 61 69 6c  LECT * FROM mail
37c0: 20 57 48 45 52 45 20 62 6f 64 79 20 4d 41 54 43   WHERE body MATC
37d0: 48 20 27 73 71 6c 69 74 65 27 3b 20 20 20 20 20  H 'sqlite';     
37e0: 20 20 3c 69 3e 2d 2d 20 46 61 73 74 2e 20 46 75    <i>-- Fast. Fu
37f0: 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 2e 3c 2f  ll-text query.</
3800: 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  i>.  SELECT * FR
3810: 4f 4d 20 6d 61 69 6c 20 57 48 45 52 45 20 6d 61  OM mail WHERE ma
3820: 69 6c 20 4d 41 54 43 48 20 27 73 65 61 72 63 68  il MATCH 'search
3830: 27 3b 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 46  ';       <i>-- F
3840: 61 73 74 2e 20 46 75 6c 6c 2d 74 65 78 74 20 71  ast. Full-text q
3850: 75 65 72 79 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45  uery.</i>.  SELE
3860: 43 54 20 2a 20 46 52 4f 4d 20 6d 61 69 6c 20 57  CT * FROM mail W
3870: 48 45 52 45 20 72 6f 77 69 64 20 42 45 54 57 45  HERE rowid BETWE
3880: 45 4e 20 31 35 20 41 4e 44 20 32 30 3b 20 20 20  EN 15 AND 20;   
3890: 3c 69 3e 2d 2d 20 53 6c 6f 77 2e 20 4c 69 6e 65  <i>-- Slow. Line
38a0: 61 72 20 73 63 61 6e 2e 3c 2f 69 3e 0a 20 20 53  ar scan.</i>.  S
38b0: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 6d 61 69  ELECT * FROM mai
38c0: 6c 20 57 48 45 52 45 20 73 75 62 6a 65 63 74 20  l WHERE subject 
38d0: 3d 20 27 64 61 74 61 62 61 73 65 27 3b 20 20 20  = 'database';   
38e0: 20 20 20 3c 69 3e 2d 2d 20 53 6c 6f 77 2e 20 4c     <i>-- Slow. L
38f0: 69 6e 65 61 72 20 73 63 61 6e 2e 3c 2f 69 3e 0a  inear scan.</i>.
3900: 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20    SELECT * FROM 
3910: 6d 61 69 6c 20 57 48 45 52 45 20 73 75 62 6a 65  mail WHERE subje
3920: 63 74 20 4d 41 54 43 48 20 27 64 61 74 61 62 61  ct MATCH 'databa
3930: 73 65 27 3b 20 20 3c 69 3e 2d 2d 20 46 61 73 74  se';  <i>-- Fast
3940: 2e 20 46 75 6c 6c 2d 74 65 78 74 20 71 75 65 72  . Full-text quer
3950: 79 2e 3c 2f 69 3e 0a 3c 2f 63 6f 64 65 62 6c 6f  y.</i>.</codeblo
3960: 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 49 6e 20 61 6c  ck>..<p>.  In al
3970: 6c 20 6f 66 20 74 68 65 20 66 75 6c 6c 2d 74 65  l of the full-te
3980: 78 74 20 71 75 65 72 69 65 73 20 61 62 6f 76 65  xt queries above
3990: 2c 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  , the right-hand
39a0: 20 6f 70 65 72 61 6e 64 20 6f 66 20 74 68 65 20   operand of the 
39b0: 4d 41 54 43 48 0a 20 20 6f 70 65 72 61 74 6f 72  MATCH.  operator
39c0: 20 69 73 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   is a string con
39d0: 73 69 73 74 69 6e 67 20 6f 66 20 61 20 73 69 6e  sisting of a sin
39e0: 67 6c 65 20 74 65 72 6d 2e 20 49 6e 20 74 68 69  gle term. In thi
39f0: 73 20 63 61 73 65 2c 20 74 68 65 20 4d 41 54 43  s case, the MATC
3a00: 48 0a 20 20 65 78 70 72 65 73 73 69 6f 6e 20 65  H.  expression e
3a10: 76 61 6c 75 61 74 65 73 20 74 6f 20 74 72 75 65  valuates to true
3a20: 20 66 6f 72 20 61 6c 6c 20 64 6f 63 75 6d 65 6e   for all documen
3a30: 74 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ts that contain 
3a40: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 20 20 69  one or more .  i
3a50: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 65 20  nstances of the 
3a60: 73 70 65 63 69 66 69 65 64 20 77 6f 72 64 20 28  specified word (
3a70: 22 73 71 6c 69 74 65 22 2c 20 22 73 65 61 72 63  "sqlite", "searc
3a80: 68 22 20 6f 72 20 22 64 61 74 61 62 61 73 65 22  h" or "database"
3a90: 2c 20 64 65 70 65 6e 64 69 6e 67 20 0a 20 20 6f  , depending .  o
3aa0: 6e 20 77 68 69 63 68 20 65 78 61 6d 70 6c 65 20  n which example 
3ab0: 79 6f 75 20 6c 6f 6f 6b 20 61 74 29 2e 20 53 70  you look at). Sp
3ac0: 65 63 69 66 79 69 6e 67 20 61 20 73 69 6e 67 6c  ecifying a singl
3ad0: 65 20 74 65 72 6d 20 61 73 20 74 68 65 20 72 69  e term as the ri
3ae0: 67 68 74 2d 68 61 6e 64 0a 20 20 6f 70 65 72 61  ght-hand.  opera
3af0: 6e 64 20 6f 66 20 74 68 65 20 4d 41 54 43 48 20  nd of the MATCH 
3b00: 6f 70 65 72 61 74 6f 72 20 72 65 73 75 6c 74 73  operator results
3b10: 20 69 6e 20 74 68 65 20 73 69 6d 70 6c 65 73 74   in the simplest
3b20: 20 61 6e 64 20 6d 6f 73 74 20 63 6f 6d 6d 6f 6e   and most common
3b30: 20 74 79 70 65 20 0a 20 20 6f 66 20 66 75 6c 6c   type .  of full
3b40: 2d 74 65 78 74 20 71 75 65 72 79 20 70 6f 73 73  -text query poss
3b50: 69 62 6c 65 2e 20 48 6f 77 65 76 65 72 20 6d 6f  ible. However mo
3b60: 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 71  re complicated q
3b70: 75 65 72 69 65 73 20 61 72 65 20 70 6f 73 73 69  ueries are possi
3b80: 62 6c 65 2c 0a 20 20 69 6e 63 6c 75 64 69 6e 67  ble,.  including
3b90: 20 70 68 72 61 73 65 20 73 65 61 72 63 68 65 73   phrase searches
3ba0: 2c 20 74 65 72 6d 2d 70 72 65 66 69 78 20 73 65  , term-prefix se
3bb0: 61 72 63 68 65 73 20 61 6e 64 20 73 65 61 72 63  arches and searc
3bc0: 68 65 73 20 66 6f 72 20 64 6f 63 75 6d 65 6e 74  hes for document
3bd0: 73 20 0a 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20  s .  containing 
3be0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
3bf0: 74 65 72 6d 73 20 6f 63 63 75 72 72 69 6e 67 20  terms occurring 
3c00: 77 69 74 68 69 6e 20 61 20 64 65 66 69 6e 65 64  within a defined
3c10: 20 70 72 6f 78 69 6d 69 74 79 20 6f 66 20 65 61   proximity of ea
3c20: 63 68 0a 20 20 6f 74 68 65 72 2e 20 54 68 65 20  ch.  other. The 
3c30: 76 61 72 69 6f 75 73 20 77 61 79 73 20 69 6e 20  various ways in 
3c40: 77 68 69 63 68 20 74 68 65 20 66 75 6c 6c 2d 74  which the full-t
3c50: 65 78 74 20 69 6e 64 65 78 20 6d 61 79 20 62 65  ext index may be
3c60: 20 71 75 65 72 69 65 64 20 61 72 65 0a 20 20 5b   queried are.  [
3c70: 46 54 53 20 4d 41 54 43 48 7c 64 65 73 63 72 69  FTS MATCH|descri
3c80: 62 65 64 20 62 65 6c 6f 77 5d 2e 0a 0a 3c 70 3e  bed below]...<p>
3c90: 0a 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20 66 75 6c  .  Normally, ful
3ca0: 6c 2d 74 65 78 74 20 71 75 65 72 69 65 73 20 61  l-text queries a
3cb0: 72 65 20 63 61 73 65 2d 69 6e 73 65 6e 73 69 74  re case-insensit
3cc0: 69 76 65 2e 20 48 6f 77 65 76 65 72 2c 20 74 68  ive. However, th
3cd0: 69 73 0a 20 20 69 73 20 64 65 70 65 6e 64 65 6e  is.  is dependen
3ce0: 74 20 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69  t on the specifi
3cf0: 63 20 5b 74 6f 6b 65 6e 69 7a 65 72 5d 20 75 73  c [tokenizer] us
3d00: 65 64 20 62 79 20 74 68 65 20 46 54 53 20 74 61  ed by the FTS ta
3d10: 62 6c 65 0a 20 20 62 65 69 6e 67 20 71 75 65 72  ble.  being quer
3d20: 69 65 64 2e 20 52 65 66 65 72 20 74 6f 20 74 68  ied. Refer to th
3d30: 65 20 73 65 63 74 69 6f 6e 20 6f 6e 20 5b 74 6f  e section on [to
3d40: 6b 65 6e 69 7a 65 72 7c 74 6f 6b 65 6e 69 7a 65  kenizer|tokenize
3d50: 72 73 5d 20 66 6f 72 20 64 65 74 61 69 6c 73 2e  rs] for details.
3d60: 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 70 61 72 61  ..<p>.  The para
3d70: 67 72 61 70 68 20 61 62 6f 76 65 20 6e 6f 74 65  graph above note
3d80: 73 20 74 68 61 74 20 61 20 4d 41 54 43 48 20 6f  s that a MATCH o
3d90: 70 65 72 61 74 6f 72 20 77 69 74 68 20 61 20 73  perator with a s
3da0: 69 6d 70 6c 65 20 74 65 72 6d 20 61 73 20 74 68  imple term as th
3db0: 65 0a 20 20 72 69 67 68 74 2d 68 61 6e 64 20 6f  e.  right-hand o
3dc0: 70 65 72 61 6e 64 20 65 76 61 6c 75 61 74 65 73  perand evaluates
3dd0: 20 74 6f 20 74 72 75 65 20 66 6f 72 20 61 6c 6c   to true for all
3de0: 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20   documents that 
3df0: 63 6f 6e 74 61 69 6e 20 74 68 65 0a 20 20 73 70  contain the.  sp
3e00: 65 63 69 66 69 65 64 20 74 65 72 6d 2e 20 49 6e  ecified term. In
3e10: 20 74 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 74   this context, t
3e20: 68 65 20 22 64 6f 63 75 6d 65 6e 74 22 20 6d 61  he "document" ma
3e30: 79 20 72 65 66 65 72 20 74 6f 20 65 69 74 68 65  y refer to eithe
3e40: 72 20 74 68 65 20 0a 20 20 64 61 74 61 20 73 74  r the .  data st
3e50: 6f 72 65 64 20 69 6e 20 61 20 73 69 6e 67 6c 65  ored in a single
3e60: 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 72 6f 77   column of a row
3e70: 20 6f 66 20 61 6e 20 46 54 53 20 74 61 62 6c 65   of an FTS table
3e80: 2c 20 6f 72 20 74 6f 20 74 68 65 20 63 6f 6e 74  , or to the cont
3e90: 65 6e 74 73 0a 20 20 6f 66 20 61 6c 6c 20 63 6f  ents.  of all co
3ea0: 6c 75 6d 6e 73 20 69 6e 20 61 20 73 69 6e 67 6c  lumns in a singl
3eb0: 65 20 72 6f 77 2c 20 64 65 70 65 6e 64 69 6e 67  e row, depending
3ec0: 20 6f 6e 20 74 68 65 20 69 64 65 6e 74 69 66 69   on the identifi
3ed0: 65 72 20 75 73 65 64 20 61 73 20 74 68 65 0a 20  er used as the. 
3ee0: 20 6c 65 66 74 2d 68 61 6e 64 20 6f 70 65 72 61   left-hand opera
3ef0: 6e 64 20 74 6f 20 74 68 65 20 4d 41 54 43 48 20  nd to the MATCH 
3f00: 6f 70 65 72 61 74 6f 72 2e 20 49 66 20 74 68 65  operator. If the
3f10: 20 69 64 65 6e 74 69 66 69 65 72 20 73 70 65 63   identifier spec
3f20: 69 66 69 65 64 20 61 73 0a 20 20 74 68 65 20 6c  ified as.  the l
3f30: 65 66 74 2d 68 61 6e 64 20 6f 70 65 72 61 6e 64  eft-hand operand
3f40: 20 6f 66 20 74 68 65 20 4d 41 54 43 48 20 6f 70   of the MATCH op
3f50: 65 72 61 74 6f 72 20 69 73 20 61 6e 20 46 54 53  erator is an FTS
3f60: 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6e 61   table column na
3f70: 6d 65 2c 0a 20 20 74 68 65 6e 20 74 68 65 20 64  me,.  then the d
3f80: 6f 63 75 6d 65 6e 74 20 74 68 61 74 20 74 68 65  ocument that the
3f90: 20 73 65 61 72 63 68 20 74 65 72 6d 20 6d 75 73   search term mus
3fa0: 74 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 69  t be contained i
3fb0: 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 0a 20  n is the value. 
3fc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 73   stored in the s
3fd0: 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 2e  pecified column.
3fe0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
3ff0: 20 69 64 65 6e 74 69 66 69 65 72 20 69 73 20 74   identifier is t
4000: 68 65 20 6e 61 6d 65 0a 20 20 6f 66 20 74 68 65  he name.  of the
4010: 20 46 54 53 20 3c 69 3e 74 61 62 6c 65 3c 2f 69   FTS <i>table</i
4020: 3e 20 69 74 73 65 6c 66 2c 20 74 68 65 6e 20 74  > itself, then t
4030: 68 65 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f  he MATCH operato
4040: 72 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 74  r evaluates to t
4050: 72 75 65 0a 20 20 66 6f 72 20 65 61 63 68 20 72  rue.  for each r
4060: 6f 77 20 6f 66 20 74 68 65 20 46 54 53 20 74 61  ow of the FTS ta
4070: 62 6c 65 20 66 6f 72 20 77 68 69 63 68 20 61 6e  ble for which an
4080: 79 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e  y column contain
4090: 73 20 74 68 65 20 73 65 61 72 63 68 20 0a 20 20  s the search .  
40a0: 74 65 72 6d 2e 20 54 68 65 20 66 6f 6c 6c 6f 77  term. The follow
40b0: 69 6e 67 20 65 78 61 6d 70 6c 65 20 64 65 6d 6f  ing example demo
40c0: 6e 73 74 72 61 74 65 73 20 74 68 69 73 3a 0a 0a  nstrates this:..
40d0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
40e0: 3e 2d 2d 20 45 78 61 6d 70 6c 65 20 73 63 68 65  >-- Example sche
40f0: 6d 61 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  ma</i>.  CREATE 
4100: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 6d 61  VIRTUAL TABLE ma
4110: 69 6c 20 55 53 49 4e 47 20 66 74 73 33 28 73 75  il USING fts3(su
4120: 62 6a 65 63 74 2c 20 62 6f 64 79 29 3b 0a 0a 20  bject, body);.. 
4130: 20 3c 69 3e 2d 2d 20 45 78 61 6d 70 6c 65 20 74   <i>-- Example t
4140: 61 62 6c 65 20 70 6f 70 75 6c 61 74 69 6f 6e 3c  able population<
4150: 2f 69 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  /i>.  INSERT INT
4160: 4f 20 6d 61 69 6c 28 64 6f 63 69 64 2c 20 73 75  O mail(docid, su
4170: 62 6a 65 63 74 2c 20 62 6f 64 79 29 20 56 41 4c  bject, body) VAL
4180: 55 45 53 28 31 2c 20 27 73 6f 66 74 77 61 72 65  UES(1, 'software
4190: 20 66 65 65 64 62 61 63 6b 27 2c 20 27 66 6f 75   feedback', 'fou
41a0: 6e 64 20 69 74 20 74 6f 6f 20 73 6c 6f 77 27 29  nd it too slow')
41b0: 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
41c0: 6d 61 69 6c 28 64 6f 63 69 64 2c 20 73 75 62 6a  mail(docid, subj
41d0: 65 63 74 2c 20 62 6f 64 79 29 20 56 41 4c 55 45  ect, body) VALUE
41e0: 53 28 32 2c 20 27 73 6f 66 74 77 61 72 65 20 66  S(2, 'software f
41f0: 65 65 64 62 61 63 6b 27 2c 20 27 6e 6f 20 66 65  eedback', 'no fe
4200: 65 64 62 61 63 6b 27 29 3b 0a 20 20 49 4e 53 45  edback');.  INSE
4210: 52 54 20 49 4e 54 4f 20 6d 61 69 6c 28 64 6f 63  RT INTO mail(doc
4220: 69 64 2c 20 73 75 62 6a 65 63 74 2c 20 62 6f 64  id, subject, bod
4230: 79 29 20 56 41 4c 55 45 53 28 33 2c 20 27 73 6c  y) VALUES(3, 'sl
4240: 6f 77 20 6c 75 6e 63 68 20 6f 72 64 65 72 27 2c  ow lunch order',
4250: 20 20 27 77 61 73 20 61 20 73 6f 66 74 77 61 72    'was a softwar
4260: 65 20 70 72 6f 62 6c 65 6d 27 29 3b 0a 0a 20 20  e problem');..  
4270: 3c 69 3e 2d 2d 20 45 78 61 6d 70 6c 65 20 71 75  <i>-- Example qu
4280: 65 72 69 65 73 3c 2f 69 3e 0a 20 20 53 45 4c 45  eries</i>.  SELE
4290: 43 54 20 2a 20 46 52 4f 4d 20 6d 61 69 6c 20 57  CT * FROM mail W
42a0: 48 45 52 45 20 73 75 62 6a 65 63 74 20 4d 41 54  HERE subject MAT
42b0: 43 48 20 27 73 6f 66 74 77 61 72 65 27 3b 20 20  CH 'software';  
42c0: 20 20 3c 69 3e 2d 2d 20 53 65 6c 65 63 74 73 20    <i>-- Selects 
42d0: 72 6f 77 73 20 31 20 61 6e 64 20 32 3c 2f 69 3e  rows 1 and 2</i>
42e0: 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d  .  SELECT * FROM
42f0: 20 6d 61 69 6c 20 57 48 45 52 45 20 62 6f 64 79   mail WHERE body
4300: 20 20 20 20 4d 41 54 43 48 20 27 66 65 65 64 62      MATCH 'feedb
4310: 61 63 6b 27 3b 20 20 20 20 3c 69 3e 2d 2d 20 53  ack';    <i>-- S
4320: 65 6c 65 63 74 73 20 72 6f 77 20 32 3c 2f 69 3e  elects row 2</i>
4330: 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d  .  SELECT * FROM
4340: 20 6d 61 69 6c 20 57 48 45 52 45 20 6d 61 69 6c   mail WHERE mail
4350: 20 20 20 20 4d 41 54 43 48 20 27 73 6f 66 74 77      MATCH 'softw
4360: 61 72 65 27 3b 20 20 20 20 3c 69 3e 2d 2d 20 53  are';    <i>-- S
4370: 65 6c 65 63 74 73 20 72 6f 77 73 20 31 2c 20 32  elects rows 1, 2
4380: 20 61 6e 64 20 33 3c 2f 69 3e 0a 20 20 53 45 4c   and 3</i>.  SEL
4390: 45 43 54 20 2a 20 46 52 4f 4d 20 6d 61 69 6c 20  ECT * FROM mail 
43a0: 57 48 45 52 45 20 6d 61 69 6c 20 20 20 20 4d 41  WHERE mail    MA
43b0: 54 43 48 20 27 73 6c 6f 77 27 3b 20 20 20 20 20  TCH 'slow';     
43c0: 20 20 20 3c 69 3e 2d 2d 20 53 65 6c 65 63 74 73     <i>-- Selects
43d0: 20 72 6f 77 73 20 31 20 61 6e 64 20 33 3c 2f 69   rows 1 and 3</i
43e0: 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  >.</codeblock>. 
43f0: 20 0a 3c 70 3e 0a 20 20 41 74 20 66 69 72 73 74   .<p>.  At first
4400: 20 67 6c 61 6e 63 65 2c 20 74 68 65 20 66 69 6e   glance, the fin
4410: 61 6c 20 74 77 6f 20 66 75 6c 6c 2d 74 65 78 74  al two full-text
4420: 20 71 75 65 72 69 65 73 20 69 6e 20 74 68 65 20   queries in the 
4430: 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 20 73 65  example above se
4440: 65 6d 0a 20 20 74 6f 20 62 65 20 73 79 6e 74 61  em.  to be synta
4450: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
4460: 63 74 2c 20 61 73 20 74 68 65 72 65 20 69 73 20  ct, as there is 
4470: 61 20 74 61 62 6c 65 20 6e 61 6d 65 20 28 22 6d  a table name ("m
4480: 61 69 6c 22 29 20 75 73 65 64 20 61 73 0a 20 20  ail") used as.  
4490: 61 6e 20 53 51 4c 20 65 78 70 72 65 73 73 69 6f  an SQL expressio
44a0: 6e 2e 20 54 68 65 20 72 65 61 73 6f 6e 20 74 68  n. The reason th
44b0: 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
44c0: 20 69 73 20 74 68 61 74 20 65 61 63 68 20 46 54   is that each FT
44d0: 53 20 74 61 62 6c 65 0a 20 20 61 63 74 75 61 6c  S table.  actual
44e0: 6c 79 20 68 61 73 20 61 20 5b 73 71 6c 69 74 65  ly has a [sqlite
44f0: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 7c 48  3_declare_vtab|H
4500: 49 44 44 45 4e 5d 20 63 6f 6c 75 6d 6e 20 77 69  IDDEN] column wi
4510: 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
4520: 0a 20 20 61 73 20 74 68 65 20 74 61 62 6c 65 20  .  as the table 
4530: 69 74 73 65 6c 66 20 28 69 6e 20 74 68 69 73 20  itself (in this 
4540: 63 61 73 65 2c 20 22 6d 61 69 6c 22 29 2e 20 54  case, "mail"). T
4550: 68 65 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20  he value stored 
4560: 69 6e 20 74 68 69 73 0a 20 20 63 6f 6c 75 6d 6e  in this.  column
4570: 20 69 73 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66   is not meaningf
4580: 75 6c 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ul to the applic
4590: 61 74 69 6f 6e 2c 20 62 75 74 20 63 61 6e 20 62  ation, but can b
45a0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 0a 20  e used as the . 
45b0: 20 6c 65 66 74 2d 68 61 6e 64 20 6f 70 65 72 61   left-hand opera
45c0: 6e 64 20 74 6f 20 61 20 4d 41 54 43 48 20 6f 70  nd to a MATCH op
45d0: 65 72 61 74 6f 72 2e 20 54 68 69 73 20 73 70 65  erator. This spe
45e0: 63 69 61 6c 20 63 6f 6c 75 6d 6e 20 6d 61 79 20  cial column may 
45f0: 61 6c 73 6f 20 62 65 0a 20 20 70 61 73 73 65 64  also be.  passed
4600: 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 20   as an argument 
4610: 74 6f 20 74 68 65 20 5b 73 6e 69 70 70 65 74 28  to the [snippet(
4620: 29 7c 46 54 53 20 61 75 78 69 6c 69 61 72 79 20  )|FTS auxiliary 
4630: 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 70 3e  functions]...<p>
4640: 0a 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
4650: 20 65 78 61 6d 70 6c 65 20 69 6c 6c 75 73 74 72   example illustr
4660: 61 74 65 73 20 74 68 65 20 61 62 6f 76 65 2e 20  ates the above. 
4670: 54 68 65 20 65 78 70 72 65 73 73 69 6f 6e 73 20  The expressions 
4680: 22 64 6f 63 73 22 2c 20 0a 20 20 22 64 6f 63 73  "docs", .  "docs
4690: 2e 64 6f 63 73 22 20 61 6e 64 20 22 6d 61 69 6e  .docs" and "main
46a0: 2e 64 6f 63 73 2e 64 6f 63 73 22 20 61 6c 6c 20  .docs.docs" all 
46b0: 72 65 66 65 72 20 74 6f 20 63 6f 6c 75 6d 6e 20  refer to column 
46c0: 22 64 6f 63 73 22 2e 20 48 6f 77 65 76 65 72 2c  "docs". However,
46d0: 20 74 68 65 20 0a 20 20 65 78 70 72 65 73 73 69   the .  expressi
46e0: 6f 6e 20 22 6d 61 69 6e 2e 64 6f 63 73 22 20 64  on "main.docs" d
46f0: 6f 65 73 20 6e 6f 74 20 72 65 66 65 72 20 74 6f  oes not refer to
4700: 20 61 6e 79 20 63 6f 6c 75 6d 6e 2e 20 49 74 20   any column. It 
4710: 63 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f  could be used to
4720: 20 0a 20 20 72 65 66 65 72 20 74 6f 20 61 20 74   .  refer to a t
4730: 61 62 6c 65 2c 20 62 75 74 20 61 20 74 61 62 6c  able, but a tabl
4740: 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 61 6c  e name is not al
4750: 6c 6f 77 65 64 20 69 6e 20 74 68 65 20 63 6f 6e  lowed in the con
4760: 74 65 78 74 20 69 6e 20 77 68 69 63 68 0a 20 20  text in which.  
4770: 69 74 20 69 73 20 75 73 65 64 20 62 65 6c 6f 77  it is used below
4780: 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
4790: 20 3c 69 3e 2d 2d 20 45 78 61 6d 70 6c 65 20 73   <i>-- Example s
47a0: 63 68 65 6d 61 3c 2f 69 3e 0a 20 20 43 52 45 41  chema</i>.  CREA
47b0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
47c0: 20 64 6f 63 73 20 55 53 49 4e 47 20 66 74 73 34   docs USING fts4
47d0: 28 63 6f 6e 74 65 6e 74 29 3b 0a 0a 20 20 3c 69  (content);..  <i
47e0: 3e 2d 2d 20 45 78 61 6d 70 6c 65 20 71 75 65 72  >-- Example quer
47f0: 69 65 73 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  ies</i>.  SELECT
4800: 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45   * FROM docs WHE
4810: 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 73  RE docs MATCH 's
4820: 71 6c 69 74 65 27 3b 20 20 20 20 20 20 20 20 20  qlite';         
4830: 20 20 20 20 20 3c 69 3e 2d 2d 20 4f 4b 2e 3c 2f       <i>-- OK.</
4840: 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  i>.  SELECT * FR
4850: 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64 6f  OM docs WHERE do
4860: 63 73 2e 64 6f 63 73 20 4d 41 54 43 48 20 27 73  cs.docs MATCH 's
4870: 71 6c 69 74 65 27 3b 20 20 20 20 20 20 20 20 20  qlite';         
4880: 3c 69 3e 2d 2d 20 4f 4b 2e 3c 2f 69 3e 0a 20 20  <i>-- OK.</i>.  
4890: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64 6f  SELECT * FROM do
48a0: 63 73 20 57 48 45 52 45 20 6d 61 69 6e 2e 64 6f  cs WHERE main.do
48b0: 63 73 2e 64 6f 63 73 20 4d 41 54 43 48 20 27 73  cs.docs MATCH 's
48c0: 71 6c 69 74 65 27 3b 20 20 20 20 3c 69 3e 2d 2d  qlite';    <i>--
48d0: 20 4f 4b 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43   OK.</i>.  SELEC
48e0: 54 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48  T * FROM docs WH
48f0: 45 52 45 20 6d 61 69 6e 2e 64 6f 63 73 20 4d 41  ERE main.docs MA
4900: 54 43 48 20 27 73 71 6c 69 74 65 27 3b 20 20 20  TCH 'sqlite';   
4910: 20 20 20 20 20 20 3c 69 3e 2d 2d 20 45 72 72 6f        <i>-- Erro
4920: 72 2e 3c 2f 69 3e 0a 3c 2f 63 6f 64 65 62 6c 6f  r.</i>.</codeblo
4930: 63 6b 3e 0a 20 0a 3c 68 32 3e 53 75 6d 6d 61 72  ck>. .<h2>Summar
4940: 79 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 46 72  y</h2>..<p>.  Fr
4950: 6f 6d 20 74 68 65 20 75 73 65 72 73 20 70 6f 69  om the users poi
4960: 6e 74 20 6f 66 20 76 69 65 77 2c 20 46 54 53 20  nt of view, FTS 
4970: 74 61 62 6c 65 73 20 61 72 65 20 73 69 6d 69 6c  tables are simil
4980: 61 72 20 74 6f 20 6f 72 64 69 6e 61 72 79 20 53  ar to ordinary S
4990: 51 4c 69 74 65 0a 20 20 74 61 62 6c 65 73 20 69  QLite.  tables i
49a0: 6e 20 6d 61 6e 79 20 77 61 79 73 2e 20 44 61 74  n many ways. Dat
49b0: 61 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 74  a may be added t
49c0: 6f 2c 20 6d 6f 64 69 66 69 65 64 20 77 69 74 68  o, modified with
49d0: 69 6e 20 61 6e 64 20 72 65 6d 6f 76 65 64 20 0a  in and removed .
49e0: 20 20 66 72 6f 6d 20 46 54 53 20 74 61 62 6c 65    from FTS table
49f0: 73 20 75 73 69 6e 67 20 74 68 65 20 49 4e 53 45  s using the INSE
4a00: 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
4a10: 45 4c 45 54 45 20 63 6f 6d 6d 61 6e 64 73 20 6a  ELETE commands j
4a20: 75 73 74 20 61 73 20 0a 20 20 69 74 20 6d 61 79  ust as .  it may
4a30: 20 62 65 20 77 69 74 68 20 6f 72 64 69 6e 61 72   be with ordinar
4a40: 79 20 74 61 62 6c 65 73 2e 20 53 69 6d 69 6c 61  y tables. Simila
4a50: 72 6c 79 2c 20 74 68 65 20 53 45 4c 45 43 54 20  rly, the SELECT 
4a60: 63 6f 6d 6d 61 6e 64 20 6d 61 79 20 62 65 20 75  command may be u
4a70: 73 65 64 20 0a 20 20 74 6f 20 71 75 65 72 79 20  sed .  to query 
4a80: 64 61 74 61 2e 20 54 68 65 20 66 6f 6c 6c 6f 77  data. The follow
4a90: 69 6e 67 20 6c 69 73 74 20 73 75 6d 6d 61 72 69  ing list summari
4aa0: 7a 65 73 20 74 68 65 20 64 69 66 66 65 72 65 6e  zes the differen
4ab0: 63 65 73 20 62 65 74 77 65 65 6e 20 46 54 53 0a  ces between FTS.
4ac0: 20 20 61 6e 64 20 6f 72 64 69 6e 61 72 79 20 74    and ordinary t
4ad0: 61 62 6c 65 73 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c  ables:..<ol>.  <
4ae0: 6c 69 3e 3c 70 3e 20 0a 20 20 20 20 41 73 20 77  li><p> .    As w
4af0: 69 74 68 20 61 6c 6c 20 76 69 72 74 75 61 6c 20  ith all virtual 
4b00: 74 61 62 6c 65 20 74 79 70 65 73 2c 20 69 74 20  table types, it 
4b10: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
4b20: 74 6f 20 63 72 65 61 74 65 20 69 6e 64 69 63 65  to create indice
4b30: 73 20 6f 72 0a 20 20 20 20 74 72 69 67 67 65 72  s or.    trigger
4b40: 73 20 61 74 74 61 63 68 65 64 20 74 6f 20 46 54  s attached to FT
4b50: 53 20 74 61 62 6c 65 73 2e 20 4e 6f 72 20 69 73  S tables. Nor is
4b60: 20 69 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20   it possible to 
4b70: 75 73 65 20 74 68 65 20 41 4c 54 45 52 20 54 41  use the ALTER TA
4b80: 42 4c 45 0a 20 20 20 20 63 6f 6d 6d 61 6e 64 20  BLE.    command 
4b90: 74 6f 20 61 64 64 20 65 78 74 72 61 20 63 6f 6c  to add extra col
4ba0: 75 6d 6e 73 20 74 6f 20 46 54 53 20 74 61 62 6c  umns to FTS tabl
4bb0: 65 73 20 28 61 6c 74 68 6f 75 67 68 20 69 74 20  es (although it 
4bc0: 69 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 75  is possible to u
4bd0: 73 65 0a 20 20 20 20 41 4c 54 45 52 20 54 41 42  se.    ALTER TAB
4be0: 4c 45 20 74 6f 20 72 65 6e 61 6d 65 20 61 6e 20  LE to rename an 
4bf0: 46 54 53 20 74 61 62 6c 65 29 2e 0a 0a 20 20 3c  FTS table)...  <
4c00: 6c 69 3e 3c 70 3e 20 0a 20 20 20 20 44 61 74 61  li><p> .    Data
4c10: 2d 74 79 70 65 73 20 73 70 65 63 69 66 69 65 64  -types specified
4c20: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
4c30: 22 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20  "CREATE VIRTUAL 
4c40: 54 41 42 4c 45 22 20 73 74 61 74 65 6d 65 6e 74  TABLE" statement
4c50: 0a 20 20 20 20 75 73 65 64 20 74 6f 20 63 72 65  .    used to cre
4c60: 61 74 65 20 61 6e 20 46 54 53 20 74 61 62 6c 65  ate an FTS table
4c70: 20 61 72 65 20 69 67 6e 6f 72 65 64 20 63 6f 6d   are ignored com
4c80: 70 6c 65 74 65 6c 79 2e 20 49 6e 73 74 65 61 64  pletely. Instead
4c90: 20 6f 66 20 74 68 65 0a 20 20 20 20 6e 6f 72 6d   of the.    norm
4ca0: 61 6c 20 72 75 6c 65 73 20 66 6f 72 20 61 70 70  al rules for app
4cb0: 6c 79 69 6e 67 20 74 79 70 65 20 5b 61 66 66 69  lying type [affi
4cc0: 6e 69 74 79 5d 20 74 6f 20 69 6e 73 65 72 74 65  nity] to inserte
4cd0: 64 20 76 61 6c 75 65 73 2c 20 61 6c 6c 0a 20 20  d values, all.  
4ce0: 20 20 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65    values inserte
4cf0: 64 20 69 6e 74 6f 20 46 54 53 20 74 61 62 6c 65  d into FTS table
4d00: 20 63 6f 6c 75 6d 6e 73 20 28 65 78 63 65 70 74   columns (except
4d10: 20 74 68 65 20 73 70 65 63 69 61 6c 20 72 6f 77   the special row
4d20: 69 64 0a 20 20 20 20 63 6f 6c 75 6d 6e 29 20 61  id.    column) a
4d30: 72 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  re converted to 
4d40: 74 79 70 65 20 54 45 58 54 20 62 65 66 6f 72 65  type TEXT before
4d50: 20 62 65 69 6e 67 20 73 74 6f 72 65 64 2e 0a 0a   being stored...
4d60: 20 20 3c 6c 69 3e 3c 70 3e 20 0a 20 20 20 20 46    <li><p> .    F
4d70: 54 53 20 74 61 62 6c 65 73 20 70 65 72 6d 69 74  TS tables permit
4d80: 20 74 68 65 20 73 70 65 63 69 61 6c 20 61 6c 69   the special ali
4d90: 61 73 20 22 64 6f 63 69 64 22 20 74 6f 20 62 65  as "docid" to be
4da0: 20 75 73 65 64 20 74 6f 20 72 65 66 65 72 20 74   used to refer t
4db0: 6f 20 74 68 65 0a 20 20 20 20 72 6f 77 69 64 20  o the.    rowid 
4dc0: 63 6f 6c 75 6d 6e 20 73 75 70 70 6f 72 74 65 64  column supported
4dd0: 20 62 79 20 61 6c 6c 20 5b 76 69 72 74 75 61 6c   by all [virtual
4de0: 20 74 61 62 6c 65 73 5d 2e 0a 0a 20 20 3c 6c 69   tables]...  <li
4df0: 3e 3c 70 3e 20 0a 20 20 20 20 54 68 65 20 5b 46  ><p> .    The [F
4e00: 54 53 20 4d 41 54 43 48 5d 20 6f 70 65 72 61 74  TS MATCH] operat
4e10: 6f 72 20 69 73 20 73 75 70 70 6f 72 74 65 64 20  or is supported 
4e20: 66 6f 72 20 71 75 65 72 69 65 73 20 62 61 73 65  for queries base
4e30: 64 20 6f 6e 20 74 68 65 20 62 75 69 6c 74 2d 69  d on the built-i
4e40: 6e 0a 20 20 20 20 66 75 6c 6c 2d 74 65 78 74 20  n.    full-text 
4e50: 69 6e 64 65 78 2e 20 0a 0a 20 20 3c 6c 69 3e 3c  index. ..  <li><
4e60: 70 3e 20 0a 20 20 20 20 54 68 65 20 5b 46 54 53  p> .    The [FTS
4e70: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
4e80: 69 6f 6e 73 5d 2c 20 5b 73 6e 69 70 70 65 74 28  ions], [snippet(
4e90: 29 5d 2c 20 5b 6f 66 66 73 65 74 73 28 29 5d 2c  )], [offsets()],
4ea0: 20 61 6e 64 20 5b 6d 61 74 63 68 69 6e 66 6f 28   and [matchinfo(
4eb0: 29 5d 20 61 72 65 20 0a 20 20 20 20 61 76 61 69  )] are .    avai
4ec0: 6c 61 62 6c 65 20 74 6f 20 73 75 70 70 6f 72 74  lable to support
4ed0: 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 69   full-text queri
4ee0: 65 73 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 0a 20  es...  <li><p>. 
4ef0: 20 20 20 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d     <tcl>hd_fragm
4f00: 65 6e 74 20 68 69 64 64 65 6e 63 6f 6c 20 7b 46  ent hiddencol {F
4f10: 54 53 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  TS hidden column
4f20: 7d 3c 2f 74 63 6c 3e 0a 20 20 20 20 45 76 65 72  }</tcl>.    Ever
4f30: 79 20 46 54 53 20 74 61 62 6c 65 20 68 61 73 20  y FTS table has 
4f40: 61 20 5b 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  a [hidden column
4f50: 5d 20 77 69 74 68 20 74 68 65 20 0a 20 20 20 20  ] with the .    
4f60: 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 74 68 65  same name as the
4f70: 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 54   table itself. T
4f80: 68 65 20 76 61 6c 75 65 20 63 6f 6e 74 61 69 6e  he value contain
4f90: 65 64 20 69 6e 20 65 61 63 68 20 72 6f 77 20 66  ed in each row f
4fa0: 6f 72 20 74 68 65 0a 20 20 20 20 68 69 64 64 65  or the.    hidde
4fb0: 6e 20 63 6f 6c 75 6d 6e 20 69 73 20 61 20 62 6c  n column is a bl
4fc0: 6f 62 20 74 68 61 74 20 69 73 20 6f 6e 6c 79 20  ob that is only 
4fd0: 75 73 65 66 75 6c 20 61 73 20 74 68 65 20 6c 65  useful as the le
4fe0: 66 74 20 6f 70 65 72 61 6e 64 20 6f 66 20 61 0a  ft operand of a.
4ff0: 20 20 20 20 5b 46 54 53 20 4d 41 54 43 48 7c 4d      [FTS MATCH|M
5000: 41 54 43 48 5d 20 6f 70 65 72 61 74 6f 72 2c 20  ATCH] operator, 
5010: 6f 72 20 61 73 20 74 68 65 20 6c 65 66 74 2d 6d  or as the left-m
5020: 6f 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ost argument to 
5030: 6f 6e 65 0a 20 20 20 20 6f 66 20 74 68 65 20 5b  one.    of the [
5040: 46 54 53 20 61 75 78 69 6c 69 61 72 79 20 66 75  FTS auxiliary fu
5050: 6e 63 74 69 6f 6e 73 5d 2e 0a 20 20 20 20 0a 0a  nctions]..    ..
5060: 3c 2f 6f 6c 3e 0a 0a 0a 3c 68 31 20 74 61 67 73  </ol>...<h1 tags
5070: 3d 22 63 6f 6d 70 69 6c 65 20 66 74 73 22 3e 43  ="compile fts">C
5080: 6f 6d 70 69 6c 69 6e 67 20 61 6e 64 20 45 6e 61  ompiling and Ena
5090: 62 6c 69 6e 67 20 46 54 53 33 20 61 6e 64 20 46  bling FTS3 and F
50a0: 54 53 34 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20  TS4</h1>..<p>.  
50b0: 41 6c 74 68 6f 75 67 68 20 46 54 53 33 20 61 6e  Although FTS3 an
50c0: 64 20 46 54 53 34 20 61 72 65 20 69 6e 63 6c 75  d FTS4 are inclu
50d0: 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ded with the SQL
50e0: 69 74 65 20 63 6f 72 65 20 73 6f 75 72 63 65 20  ite core source 
50f0: 63 6f 64 65 2c 20 74 68 65 79 20 61 72 65 20 6e  code, they are n
5100: 6f 74 0a 20 20 65 6e 61 62 6c 65 64 20 62 79 20  ot.  enabled by 
5110: 64 65 66 61 75 6c 74 2e 20 54 6f 20 62 75 69 6c  default. To buil
5120: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 46 54  d SQLite with FT
5130: 53 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20  S functionality 
5140: 65 6e 61 62 6c 65 64 2c 20 64 65 66 69 6e 65 0a  enabled, define.
5150: 20 20 74 68 65 20 70 72 65 70 72 6f 63 65 73 73    the preprocess
5160: 6f 72 20 6d 61 63 72 6f 20 5b 53 51 4c 49 54 45  or macro [SQLITE
5170: 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5d 20 77 68  _ENABLE_FTS3] wh
5180: 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 2e 20 4e 65  en compiling. Ne
5190: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 20  w applications. 
51a0: 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 64 65 66   should also def
51b0: 69 6e 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ine the [SQLITE_
51c0: 45 4e 41 42 4c 45 5f 46 54 53 33 5f 50 41 52 45  ENABLE_FTS3_PARE
51d0: 4e 54 48 45 53 49 53 5d 20 6d 61 63 72 6f 20 74  NTHESIS] macro t
51e0: 6f 20 65 6e 61 62 6c 65 20 74 68 65 0a 20 20 5b  o enable the.  [
51f0: 65 6e 68 61 6e 63 65 64 20 71 75 65 72 79 20 73  enhanced query s
5200: 79 6e 74 61 78 5d 20 28 73 65 65 20 62 65 6c 6f  yntax] (see belo
5210: 77 29 2e 20 55 73 75 61 6c 6c 79 2c 20 74 68 69  w). Usually, thi
5220: 73 20 69 73 20 64 6f 6e 65 20 62 79 20 61 64 64  s is done by add
5230: 69 6e 67 20 74 68 65 20 0a 20 20 66 6f 6c 6c 6f  ing the .  follo
5240: 77 69 6e 67 20 74 77 6f 20 73 77 69 74 63 68 65  wing two switche
5250: 73 20 74 6f 20 74 68 65 20 63 6f 6d 70 69 6c 65  s to the compile
5260: 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 3a 0a  r command line:.
5270: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 2d  .<codeblock>.  -
5280: 44 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 46  DSQLITE_ENABLE_F
5290: 54 53 33 0a 20 20 2d 44 53 51 4c 49 54 45 5f 45  TS3.  -DSQLITE_E
52a0: 4e 41 42 4c 45 5f 46 54 53 33 5f 50 41 52 45 4e  NABLE_FTS3_PAREN
52b0: 54 48 45 53 49 53 0a 3c 2f 63 6f 64 65 62 6c 6f  THESIS.</codeblo
52c0: 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 4e 6f 74 65 20  ck>..<p>.  Note 
52d0: 74 68 61 74 20 65 6e 61 62 6c 69 6e 67 20 46 54  that enabling FT
52e0: 53 33 20 61 6c 73 6f 20 6d 61 6b 65 73 20 46 54  S3 also makes FT
52f0: 53 34 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  S4 available.  T
5300: 68 65 72 65 20 69 73 20 6e 6f 74 20 61 20 73 65  here is not a se
5310: 70 61 72 61 74 65 0a 20 20 53 51 4c 49 54 45 5f  parate.  SQLITE_
5320: 45 4e 41 42 4c 45 5f 46 54 53 34 20 63 6f 6d 70  ENABLE_FTS4 comp
5330: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
5340: 20 20 41 20 62 75 69 6c 64 20 6f 66 20 53 51 4c    A build of SQL
5350: 69 74 65 20 65 69 74 68 65 72 20 73 75 70 70 6f  ite either suppo
5360: 72 74 73 0a 20 20 62 6f 74 68 20 46 54 53 33 20  rts.  both FTS3 
5370: 61 6e 64 20 46 54 53 34 20 6f 72 20 69 74 20 73  and FTS4 or it s
5380: 75 70 70 6f 72 74 73 20 6e 65 69 74 68 65 72 2e  upports neither.
5390: 0a 0a 3c 70 3e 0a 20 20 49 66 20 75 73 69 6e 67  ..<p>.  If using
53a0: 20 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f   the amalgamatio
53b0: 6e 20 61 75 74 6f 63 6f 6e 66 20 62 61 73 65 64  n autoconf based
53c0: 20 62 75 69 6c 64 20 73 79 73 74 65 6d 2c 20 73   build system, s
53d0: 65 74 74 69 6e 67 20 74 68 65 20 43 50 50 46 4c  etting the CPPFL
53e0: 41 47 53 0a 20 20 65 6e 76 69 72 6f 6e 6d 65 6e  AGS.  environmen
53f0: 74 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65  t variable while
5400: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 27 63 6f   running the 'co
5410: 6e 66 69 67 75 72 65 27 20 73 63 72 69 70 74 20  nfigure' script 
5420: 69 73 20 61 6e 20 65 61 73 79 0a 20 20 77 61 79  is an easy.  way
5430: 20 74 6f 20 73 65 74 20 74 68 65 73 65 20 6d 61   to set these ma
5440: 63 72 6f 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c  cros. For exampl
5450: 65 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  e, the following
5460: 20 63 6f 6d 6d 61 6e 64 3a 0a 0a 3c 63 6f 64 65   command:..<code
5470: 62 6c 6f 63 6b 3e 0a 20 20 43 50 50 46 4c 41 47  block>.  CPPFLAG
5480: 53 3d 22 2d 44 53 51 4c 49 54 45 5f 45 4e 41 42  S="-DSQLITE_ENAB
5490: 4c 45 5f 46 54 53 33 20 2d 44 53 51 4c 49 54 45  LE_FTS3 -DSQLITE
54a0: 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 50 41 52  _ENABLE_FTS3_PAR
54b0: 45 4e 54 48 45 53 49 53 22 20 2e 2f 63 6f 6e 66  ENTHESIS" ./conf
54c0: 69 67 75 72 65 20 26 6c 74 3b 63 6f 6e 66 69 67  igure &lt;config
54d0: 75 72 65 20 6f 70 74 69 6f 6e 73 26 67 74 3b 0a  ure options&gt;.
54e0: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
54f0: 3e 0a 20 20 77 68 65 72 65 20 3c 69 3e 26 6c 74  >.  where <i>&lt
5500: 3b 63 6f 6e 66 69 67 75 72 65 20 6f 70 74 69 6f  ;configure optio
5510: 6e 73 26 67 74 3b 3c 2f 69 3e 20 61 72 65 20 74  ns&gt;</i> are t
5520: 68 6f 73 65 20 6f 70 74 69 6f 6e 73 20 6e 6f 72  hose options nor
5530: 6d 61 6c 6c 79 20 70 61 73 73 65 64 20 74 6f 0a  mally passed to.
5540: 20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 20    the configure 
5550: 73 63 72 69 70 74 2c 20 69 66 20 61 6e 79 2e 0a  script, if any..
5560: 0a 3c 70 3e 0a 20 20 42 65 63 61 75 73 65 20 46  .<p>.  Because F
5570: 54 53 33 20 61 6e 64 20 46 54 53 34 20 61 72 65  TS3 and FTS4 are
5580: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2c   virtual tables,
5590: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   The [SQLITE_ENA
55a0: 42 4c 45 5f 46 54 53 33 5d 20 63 6f 6d 70 69 6c  BLE_FTS3] compil
55b0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 20 20  e-time option.  
55c0: 69 73 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  is incompatible 
55d0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
55e0: 5f 4f 4d 49 54 5f 56 49 52 54 55 41 4c 54 41 42  _OMIT_VIRTUALTAB
55f0: 4c 45 5d 20 6f 70 74 69 6f 6e 2e 0a 0a 3c 70 3e  LE] option...<p>
5600: 0a 20 20 49 66 20 61 20 62 75 69 6c 64 20 6f 66  .  If a build of
5610: 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
5620: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 46 54 53   include the FTS
5630: 20 6d 6f 64 75 6c 65 73 2c 20 74 68 65 6e 20 61   modules, then a
5640: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 70 72  ny attempt to pr
5650: 65 70 61 72 65 20 61 6e 0a 20 20 53 51 4c 20 73  epare an.  SQL s
5660: 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 72 65 61  tatement to crea
5670: 74 65 20 61 6e 20 46 54 53 33 20 6f 72 20 46 54  te an FTS3 or FT
5680: 53 34 20 74 61 62 6c 65 20 6f 72 20 74 6f 20 64  S4 table or to d
5690: 72 6f 70 20 6f 72 20 61 63 63 65 73 73 20 61 6e  rop or access an
56a0: 20 65 78 69 73 74 69 6e 67 20 0a 20 20 46 54 53   existing .  FTS
56b0: 20 74 61 62 6c 65 20 69 6e 20 61 6e 79 20 77 61   table in any wa
56c0: 79 20 77 69 6c 6c 20 66 61 69 6c 2e 20 54 68 65  y will fail. The
56d0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 72   error message r
56e0: 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
56f0: 73 69 6d 69 6c 61 72 20 0a 20 20 74 6f 20 22 6e  similar .  to "n
5700: 6f 20 73 75 63 68 20 6d 6f 64 75 6c 65 3a 20 66  o such module: f
5710: 74 73 4e 22 20 28 77 68 65 72 65 20 4e 20 69 73  tsN" (where N is
5720: 20 65 69 74 68 65 72 20 33 20 6f 72 20 34 29 2e   either 3 or 4).
5730: 0a 0a 3c 70 3e 0a 20 20 49 66 20 74 68 65 20 43  ..<p>.  If the C
5740: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
5750: 3c 61 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f 73  <a href=http://s
5760: 69 74 65 2e 69 63 75 2d 70 72 6f 6a 65 63 74 2e  ite.icu-project.
5770: 6f 72 67 2f 3e 49 43 55 20 6c 69 62 72 61 72 79  org/>ICU library
5780: 3c 2f 61 3e 0a 20 20 69 73 20 61 76 61 69 6c 61  </a>.  is availa
5790: 62 6c 65 2c 20 74 68 65 6e 20 46 54 53 20 6d 61  ble, then FTS ma
57a0: 79 20 61 6c 73 6f 20 62 65 20 63 6f 6d 70 69 6c  y also be compil
57b0: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
57c0: 54 45 5f 45 4e 41 42 4c 45 5f 49 43 55 0a 20 20  TE_ENABLE_ICU.  
57d0: 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
57e0: 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 43 6f 6d  cro defined. Com
57f0: 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 69 73  piling with this
5800: 20 6d 61 63 72 6f 20 65 6e 61 62 6c 65 73 20 61   macro enables a
5810: 6e 20 46 54 53 0a 20 20 5b 74 6f 6b 65 6e 69 7a  n FTS.  [tokeniz
5820: 65 72 5d 20 74 68 61 74 20 75 73 65 73 20 74 68  er] that uses th
5830: 65 20 49 43 55 20 6c 69 62 72 61 72 79 20 74 6f  e ICU library to
5840: 20 73 70 6c 69 74 20 61 20 64 6f 63 75 6d 65 6e   split a documen
5850: 74 20 69 6e 74 6f 20 74 65 72 6d 73 0a 20 20 28  t into terms.  (
5860: 77 6f 72 64 73 29 20 75 73 69 6e 67 20 74 68 65  words) using the
5870: 20 63 6f 6e 76 65 6e 74 69 6f 6e 73 20 66 6f 72   conventions for
5880: 20 61 20 73 70 65 63 69 66 69 65 64 20 6c 61 6e   a specified lan
5890: 67 75 61 67 65 20 61 6e 64 20 6c 6f 63 61 6c 65  guage and locale
58a0: 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
58b0: 20 2d 44 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45   -DSQLITE_ENABLE
58c0: 5f 49 43 55 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  _ICU.</codeblock
58d0: 3e 0a 20 20 0a 0a 3c 68 31 20 74 61 67 73 3d 22  >.  ..<h1 tags="
58e0: 46 54 53 20 4d 41 54 43 48 22 3e 46 75 6c 6c 2d  FTS MATCH">Full-
58f0: 74 65 78 74 20 49 6e 64 65 78 20 51 75 65 72 69  text Index Queri
5900: 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20 54  es</h1>..<p>.  T
5910: 68 65 20 6d 6f 73 74 20 75 73 65 66 75 6c 20 74  he most useful t
5920: 68 69 6e 67 20 61 62 6f 75 74 20 46 54 53 20 74  hing about FTS t
5930: 61 62 6c 65 73 20 69 73 20 74 68 65 20 71 75 65  ables is the que
5940: 72 69 65 73 20 74 68 61 74 20 6d 61 79 20 62 65  ries that may be
5950: 20 0a 20 20 70 65 72 66 6f 72 6d 65 64 20 75 73   .  performed us
5960: 69 6e 67 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  ing the built-in
5970: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
5980: 2e 20 46 75 6c 6c 2d 74 65 78 74 20 71 75 65 72  . Full-text quer
5990: 69 65 73 20 61 72 65 20 0a 20 20 70 65 72 66 6f  ies are .  perfo
59a0: 72 6d 65 64 20 62 79 20 73 70 65 63 69 66 79 69  rmed by specifyi
59b0: 6e 67 20 61 20 63 6c 61 75 73 65 20 6f 66 20 74  ng a clause of t
59c0: 68 65 20 66 6f 72 6d 20 0a 20 20 22 26 6c 74 3b  he form .  "&lt;
59d0: 63 6f 6c 75 6d 6e 26 67 74 3b 20 4d 41 54 43 48  column&gt; MATCH
59e0: 20 26 6c 74 3b 66 75 6c 6c 2d 74 65 78 74 20 71   &lt;full-text q
59f0: 75 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e 26  uery expression&
5a00: 67 74 3b 22 20 61 73 20 70 61 72 74 20 6f 66 20  gt;" as part of 
5a10: 74 68 65 20 57 48 45 52 45 20 0a 20 20 63 6c 61  the WHERE .  cla
5a20: 75 73 65 20 6f 66 20 61 20 53 45 4c 45 43 54 20  use of a SELECT 
5a30: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 72  statement that r
5a40: 65 61 64 73 20 64 61 74 61 20 66 72 6f 6d 20 61  eads data from a
5a50: 6e 20 46 54 53 20 74 61 62 6c 65 2e 20 0a 20 20  n FTS table. .  
5a60: 5b 73 69 6d 70 6c 65 20 66 74 73 20 71 75 65 72  [simple fts quer
5a70: 69 65 73 7c 53 69 6d 70 6c 65 20 46 54 53 20 71  ies|Simple FTS q
5a80: 75 65 72 69 65 73 5d 20 74 68 61 74 20 72 65 74  ueries] that ret
5a90: 75 72 6e 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74  urn all document
5aa0: 73 20 74 68 61 74 20 0a 20 20 63 6f 6e 74 61 69  s that .  contai
5ab0: 6e 20 61 20 67 69 76 65 6e 20 74 65 72 6d 20 61  n a given term a
5ac0: 72 65 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  re described abo
5ad0: 76 65 2e 20 49 6e 20 74 68 61 74 20 64 69 73 63  ve. In that disc
5ae0: 75 73 73 69 6f 6e 20 74 68 65 20 72 69 67 68 74  ussion the right
5af0: 2d 68 61 6e 64 0a 20 20 6f 70 65 72 61 6e 64 20  -hand.  operand 
5b00: 6f 66 20 74 68 65 20 4d 41 54 43 48 20 6f 70 65  of the MATCH ope
5b10: 72 61 74 6f 72 20 77 61 73 20 61 73 73 75 6d 65  rator was assume
5b20: 64 20 74 6f 20 62 65 20 61 20 73 74 72 69 6e 67  d to be a string
5b30: 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 61   consisting of a
5b40: 0a 20 20 73 69 6e 67 6c 65 20 74 65 72 6d 2e 20  .  single term. 
5b50: 54 68 69 73 20 73 65 63 74 69 6f 6e 20 64 65 73  This section des
5b60: 63 72 69 62 65 73 20 74 68 65 20 6d 6f 72 65 20  cribes the more 
5b70: 63 6f 6d 70 6c 65 78 20 71 75 65 72 79 20 74 79  complex query ty
5b80: 70 65 73 20 73 75 70 70 6f 72 74 65 64 20 0a 20  pes supported . 
5b90: 20 62 79 20 46 54 53 20 74 61 62 6c 65 73 2c 20   by FTS tables, 
5ba0: 61 6e 64 20 68 6f 77 20 74 68 65 79 20 6d 61 79  and how they may
5bb0: 20 62 65 20 75 74 69 6c 69 7a 65 64 20 62 79 20   be utilized by 
5bc0: 73 70 65 63 69 66 79 69 6e 67 20 61 20 6d 6f 72  specifying a mor
5bd0: 65 0a 20 20 63 6f 6d 70 6c 65 78 20 71 75 65 72  e.  complex quer
5be0: 79 20 65 78 70 72 65 73 73 69 6f 6e 20 61 73 20  y expression as 
5bf0: 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 6f  the right-hand o
5c00: 70 65 72 61 6e 64 20 6f 66 20 61 20 4d 41 54 43  perand of a MATC
5c10: 48 20 6f 70 65 72 61 74 6f 72 2e 0a 0a 3c 70 3e  H operator...<p>
5c20: 0a 20 20 46 54 53 20 74 61 62 6c 65 73 20 73 75  .  FTS tables su
5c30: 70 70 6f 72 74 20 74 68 72 65 65 20 62 61 73 69  pport three basi
5c40: 63 20 71 75 65 72 79 20 74 79 70 65 73 3a 0a 0a  c query types:..
5c50: 3c 75 6c 3e 0a 20 20 3c 74 63 6c 3e 68 64 5f 66  <ul>.  <tcl>hd_f
5c60: 72 61 67 6d 65 6e 74 20 74 65 72 6d 70 72 65 66  ragment termpref
5c70: 69 78 20 7b 70 72 65 66 69 78 20 71 75 65 72 79  ix {prefix query
5c80: 7d 20 7b 70 72 65 66 69 78 20 71 75 65 72 69 65  } {prefix querie
5c90: 73 7d 3c 2f 74 63 6c 3e 0a 20 20 3c 6c 69 3e 3c  s}</tcl>.  <li><
5ca0: 70 3e 3c 62 3e 54 6f 6b 65 6e 20 6f 72 20 74 6f  p><b>Token or to
5cb0: 6b 65 6e 20 70 72 65 66 69 78 20 71 75 65 72 69  ken prefix queri
5cc0: 65 73 3c 2f 62 3e 2e 20 0a 20 20 20 20 41 6e 20  es</b>. .    An 
5cd0: 46 54 53 20 74 61 62 6c 65 20 6d 61 79 20 62 65  FTS table may be
5ce0: 20 71 75 65 72 69 65 64 20 66 6f 72 20 61 6c 6c   queried for all
5cf0: 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20   documents that 
5d00: 63 6f 6e 74 61 69 6e 20 61 20 73 70 65 63 69 66  contain a specif
5d10: 69 65 64 0a 20 20 20 20 74 65 72 6d 20 28 74 68  ied.    term (th
5d20: 65 20 5b 73 69 6d 70 6c 65 20 66 74 73 20 71 75  e [simple fts qu
5d30: 65 72 69 65 73 7c 73 69 6d 70 6c 65 20 63 61 73  eries|simple cas
5d40: 65 5d 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  e] described abo
5d50: 76 65 29 2c 20 6f 72 20 66 6f 72 0a 20 20 20 20  ve), or for.    
5d60: 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68  all documents th
5d70: 61 74 20 63 6f 6e 74 61 69 6e 20 61 20 74 65 72  at contain a ter
5d80: 6d 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  m with a specifi
5d90: 65 64 20 70 72 65 66 69 78 2e 20 41 73 20 77 65  ed prefix. As we
5da0: 20 68 61 76 65 0a 20 20 20 20 73 65 65 6e 2c 20   have.    seen, 
5db0: 74 68 65 20 71 75 65 72 79 20 65 78 70 72 65 73  the query expres
5dc0: 73 69 6f 6e 20 66 6f 72 20 61 20 73 70 65 63 69  sion for a speci
5dd0: 66 69 63 20 74 65 72 6d 20 69 73 20 73 69 6d 70  fic term is simp
5de0: 6c 79 20 74 68 65 20 74 65 72 6d 20 69 74 73 65  ly the term itse
5df0: 6c 66 2e 0a 20 20 20 20 54 68 65 20 71 75 65 72  lf..    The quer
5e00: 79 20 65 78 70 72 65 73 73 69 6f 6e 20 75 73 65  y expression use
5e10: 64 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  d to search for 
5e20: 61 20 74 65 72 6d 20 70 72 65 66 69 78 20 69 73  a term prefix is
5e30: 20 74 68 65 20 70 72 65 66 69 78 0a 20 20 20 20   the prefix.    
5e40: 69 74 73 65 6c 66 20 77 69 74 68 20 61 20 27 2a  itself with a '*
5e50: 27 20 63 68 61 72 61 63 74 65 72 20 61 70 70 65  ' character appe
5e60: 6e 64 65 64 20 74 6f 20 69 74 2e 20 46 6f 72 20  nded to it. For 
5e70: 65 78 61 6d 70 6c 65 3a 0a 3c 2f 75 6c 3e 0a 0a  example:.</ul>..
5e80: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
5e90: 3e 2d 2d 20 56 69 72 74 75 61 6c 20 74 61 62 6c  >-- Virtual tabl
5ea0: 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 3c 2f 69  e declaration</i
5eb0: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
5ec0: 41 4c 20 54 41 42 4c 45 20 64 6f 63 73 20 55 53  AL TABLE docs US
5ed0: 49 4e 47 20 66 74 73 33 28 74 69 74 6c 65 2c 20  ING fts3(title, 
5ee0: 62 6f 64 79 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  body);..  <i>-- 
5ef0: 51 75 65 72 79 20 66 6f 72 20 61 6c 6c 20 64 6f  Query for all do
5f00: 63 75 6d 65 6e 74 73 20 63 6f 6e 74 61 69 6e 69  cuments containi
5f10: 6e 67 20 74 68 65 20 74 65 72 6d 20 22 6c 69 6e  ng the term "lin
5f20: 75 78 22 3a 3c 2f 69 3e 0a 20 20 53 45 4c 45 43  ux":</i>.  SELEC
5f30: 54 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48  T * FROM docs WH
5f40: 45 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27  ERE docs MATCH '
5f50: 6c 69 6e 75 78 27 3b 0a 0a 20 20 3c 69 3e 2d 2d  linux';..  <i>--
5f60: 20 51 75 65 72 79 20 66 6f 72 20 61 6c 6c 20 64   Query for all d
5f70: 6f 63 75 6d 65 6e 74 73 20 63 6f 6e 74 61 69 6e  ocuments contain
5f80: 69 6e 67 20 61 20 74 65 72 6d 20 77 69 74 68 20  ing a term with 
5f90: 74 68 65 20 70 72 65 66 69 78 20 22 6c 69 6e 22  the prefix "lin"
5fa0: 2e 20 54 68 69 73 20 77 69 6c 6c 20 6d 61 74 63  . This will matc
5fb0: 68 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 61 6c  h</i>.  <i>-- al
5fc0: 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74  l documents that
5fd0: 20 63 6f 6e 74 61 69 6e 20 22 6c 69 6e 75 78 22   contain "linux"
5fe0: 2c 20 62 75 74 20 61 6c 73 6f 20 74 68 6f 73 65  , but also those
5ff0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 65   that contain te
6000: 72 6d 73 20 22 6c 69 6e 65 61 72 22 2c 3c 2f 69  rms "linear",</i
6010: 3e 0a 20 20 3c 69 3e 2d 2d 22 6c 69 6e 6b 65 72  >.  <i>--"linker
6020: 22 2c 20 22 6c 69 6e 67 75 69 73 74 69 63 22 20  ", "linguistic" 
6030: 61 6e 64 20 73 6f 20 6f 6e 2e 3c 2f 69 3e 0a 20  and so on.</i>. 
6040: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64   SELECT * FROM d
6050: 6f 63 73 20 57 48 45 52 45 20 64 6f 63 73 20 4d  ocs WHERE docs M
6060: 41 54 43 48 20 27 6c 69 6e 2a 27 3b 0a 3c 2f 63  ATCH 'lin*';.</c
6070: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 75 6c 3e 0a  odeblock>..<ul>.
6080: 20 20 3c 6c 69 20 73 74 79 6c 65 3d 22 6c 69 73    <li style="lis
6090: 74 2d 73 74 79 6c 65 3a 6e 6f 6e 65 22 3e 3c 70  t-style:none"><p
60a0: 3e 0a 20 20 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20  >.    Normally, 
60b0: 61 20 74 6f 6b 65 6e 20 6f 72 20 74 6f 6b 65 6e  a token or token
60c0: 20 70 72 65 66 69 78 20 71 75 65 72 79 20 69 73   prefix query is
60d0: 20 6d 61 74 63 68 65 64 20 61 67 61 69 6e 73 74   matched against
60e0: 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 20 0a   the FTS table .
60f0: 20 20 20 20 63 6f 6c 75 6d 6e 20 73 70 65 63 69      column speci
6100: 66 69 65 64 20 61 73 20 74 68 65 20 72 69 67 68  fied as the righ
6110: 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
6120: 68 65 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f  he MATCH operato
6130: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 0a 20 20  r. Or, if the.  
6140: 20 20 73 70 65 63 69 61 6c 20 63 6f 6c 75 6d 6e    special column
6150: 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
6160: 61 6d 65 20 61 73 20 74 68 65 20 46 54 53 20 74  ame as the FTS t
6170: 61 62 6c 65 20 69 74 73 65 6c 66 20 69 73 20 73  able itself is s
6180: 70 65 63 69 66 69 65 64 2c 0a 20 20 20 20 61 67  pecified,.    ag
6190: 61 69 6e 73 74 20 61 6c 6c 20 63 6f 6c 75 6d 6e  ainst all column
61a0: 73 2e 20 54 68 69 73 20 6d 61 79 20 62 65 20 6f  s. This may be o
61b0: 76 65 72 72 69 64 64 65 6e 20 62 79 20 73 70 65  verridden by spe
61c0: 63 69 66 79 69 6e 67 20 61 20 63 6f 6c 75 6d 6e  cifying a column
61d0: 2d 6e 61 6d 65 0a 20 20 20 20 66 6f 6c 6c 6f 77  -name.    follow
61e0: 65 64 20 62 79 20 61 20 22 3a 22 20 63 68 61 72  ed by a ":" char
61f0: 61 63 74 65 72 20 62 65 66 6f 72 65 20 61 20 62  acter before a b
6200: 61 73 69 63 20 74 65 72 6d 20 71 75 65 72 79 2e  asic term query.
6210: 20 54 68 65 72 65 20 6d 61 79 20 62 65 20 73 70   There may be sp
6220: 61 63 65 0a 20 20 20 20 62 65 74 77 65 65 6e 20  ace.    between 
6230: 74 68 65 20 22 3a 22 20 61 6e 64 20 74 68 65 20  the ":" and the 
6240: 74 65 72 6d 20 74 6f 20 71 75 65 72 79 20 66 6f  term to query fo
6250: 72 2c 20 62 75 74 20 6e 6f 74 20 62 65 74 77 65  r, but not betwe
6260: 65 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 2d 6e 61  en the column-na
6270: 6d 65 0a 20 20 20 20 61 6e 64 20 74 68 65 20 22  me.    and the "
6280: 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 46 6f  :" character. Fo
6290: 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f 75 6c 3e  r example:.</ul>
62a0: 0a 20 20 20 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  .   .<codeblock>
62b0: 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20 74  .  <i>-- Query t
62c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
62d0: 64 6f 63 75 6d 65 6e 74 73 20 66 6f 72 20 77 68  documents for wh
62e0: 69 63 68 20 74 68 65 20 74 65 72 6d 20 22 6c 69  ich the term "li
62f0: 6e 75 78 22 20 61 70 70 65 61 72 73 20 69 6e 3c  nux" appears in<
6300: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20  /i>.  <i>-- the 
6310: 64 6f 63 75 6d 65 6e 74 20 74 69 74 6c 65 2c 20  document title, 
6320: 61 6e 64 20 74 68 65 20 74 65 72 6d 20 22 70 72  and the term "pr
6330: 6f 62 6c 65 6d 73 22 20 61 70 70 65 61 72 73 20  oblems" appears 
6340: 69 6e 20 65 69 74 68 65 72 20 74 68 65 20 74 69  in either the ti
6350: 74 6c 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  tle</i>.  <i>-- 
6360: 6f 72 20 62 6f 64 79 20 6f 66 20 74 68 65 20 64  or body of the d
6370: 6f 63 75 6d 65 6e 74 2e 3c 2f 69 3e 0a 20 20 53  ocument.</i>.  S
6380: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64 6f 63  ELECT * FROM doc
6390: 73 20 57 48 45 52 45 20 64 6f 63 73 20 4d 41 54  s WHERE docs MAT
63a0: 43 48 20 27 74 69 74 6c 65 3a 6c 69 6e 75 78 20  CH 'title:linux 
63b0: 70 72 6f 62 6c 65 6d 73 27 3b 0a 0a 20 20 3c 69  problems';..  <i
63c0: 3e 2d 2d 20 51 75 65 72 79 20 74 68 65 20 64 61  >-- Query the da
63d0: 74 61 62 61 73 65 20 66 6f 72 20 64 6f 63 75 6d  tabase for docum
63e0: 65 6e 74 73 20 66 6f 72 20 77 68 69 63 68 20 74  ents for which t
63f0: 68 65 20 74 65 72 6d 20 22 6c 69 6e 75 78 22 20  he term "linux" 
6400: 61 70 70 65 61 72 73 20 69 6e 3c 2f 69 3e 0a 20  appears in</i>. 
6410: 20 3c 69 3e 2d 2d 20 74 68 65 20 64 6f 63 75 6d   <i>-- the docum
6420: 65 6e 74 20 74 69 74 6c 65 2c 20 61 6e 64 20 74  ent title, and t
6430: 68 65 20 74 65 72 6d 20 22 64 72 69 76 65 72 22  he term "driver"
6440: 20 61 70 70 65 61 72 73 20 69 6e 20 74 68 65 20   appears in the 
6450: 62 6f 64 79 20 6f 66 20 74 68 65 20 64 6f 63 75  body of the docu
6460: 6d 65 6e 74 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  ment</i>.  <i>--
6470: 20 28 22 64 72 69 76 65 72 22 20 6d 61 79 20 61   ("driver" may a
6480: 6c 73 6f 20 61 70 70 65 61 72 20 69 6e 20 74 68  lso appear in th
6490: 65 20 74 69 74 6c 65 2c 20 62 75 74 20 74 68 69  e title, but thi
64a0: 73 20 61 6c 6f 6e 65 20 77 69 6c 6c 20 6e 6f 74  s alone will not
64b0: 20 73 61 74 69 73 66 79 20 74 68 65 3c 2f 69 3e   satisfy the</i>
64c0: 2e 0a 20 20 3c 69 3e 2d 2d 20 71 75 65 72 79 20  ..  <i>-- query 
64d0: 63 72 69 74 65 72 69 61 29 2e 3c 2f 69 3e 0a 20  criteria).</i>. 
64e0: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64   SELECT * FROM d
64f0: 6f 63 73 20 57 48 45 52 45 20 62 6f 64 79 20 4d  ocs WHERE body M
6500: 41 54 43 48 20 27 74 69 74 6c 65 3a 6c 69 6e 75  ATCH 'title:linu
6510: 78 20 64 72 69 76 65 72 27 3b 0a 3c 2f 63 6f 64  x driver';.</cod
6520: 65 62 6c 6f 63 6b 3e 0a 0a 3c 75 6c 3e 0a 20 20  eblock>..<ul>.  
6530: 3c 6c 69 3e 3c 70 3e 3c 62 3e 50 68 72 61 73 65  <li><p><b>Phrase
6540: 20 71 75 65 72 69 65 73 3c 2f 62 3e 2e 0a 20 20   queries</b>..  
6550: 20 20 41 20 70 68 72 61 73 65 20 71 75 65 72 79    A phrase query
6560: 20 69 73 20 61 20 71 75 65 72 79 20 74 68 61 74   is a query that
6570: 20 72 65 74 72 69 65 76 65 73 20 61 6c 6c 20 64   retrieves all d
6580: 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f  ocuments that co
6590: 6e 74 61 69 6e 20 61 0a 20 20 20 20 6e 6f 6d 69  ntain a.    nomi
65a0: 6e 61 74 65 64 20 73 65 74 20 6f 66 20 74 65 72  nated set of ter
65b0: 6d 73 20 6f 72 20 74 65 72 6d 20 70 72 65 66 69  ms or term prefi
65c0: 78 65 73 20 69 6e 20 61 20 73 70 65 63 69 66 69  xes in a specifi
65d0: 65 64 20 6f 72 64 65 72 20 77 69 74 68 20 6e 6f  ed order with no
65e0: 0a 20 20 20 20 69 6e 74 65 72 76 65 6e 69 6e 67  .    intervening
65f0: 20 74 6f 6b 65 6e 73 2e 20 50 68 72 61 73 65 20   tokens. Phrase 
6600: 71 75 65 72 69 65 73 20 61 72 65 20 73 70 65 63  queries are spec
6610: 69 66 69 65 64 20 62 79 20 65 6e 63 6c 6f 73 69  ified by enclosi
6620: 6e 67 20 61 20 73 70 61 63 65 0a 20 20 20 20 73  ng a space.    s
6630: 65 70 61 72 61 74 65 64 20 73 65 71 75 65 6e 63  eparated sequenc
6640: 65 20 6f 66 20 74 65 72 6d 73 20 6f 72 20 74 65  e of terms or te
6650: 72 6d 20 70 72 65 66 69 78 65 73 20 69 6e 20 64  rm prefixes in d
6660: 6f 75 62 6c 65 20 71 75 6f 74 65 73 20 28 22 29  ouble quotes (")
6670: 2e 0a 20 20 20 20 46 6f 72 20 65 78 61 6d 70 6c  ..    For exampl
6680: 65 3a 0a 3c 2f 75 6c 3e 0a 0a 3c 63 6f 64 65 62  e:.</ul>..<codeb
6690: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75  lock>.  <i>-- Qu
66a0: 65 72 79 20 66 6f 72 20 61 6c 6c 20 64 6f 63 75  ery for all docu
66b0: 6d 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61  ments that conta
66c0: 69 6e 20 74 68 65 20 70 68 72 61 73 65 20 22 6c  in the phrase "l
66d0: 69 6e 75 78 20 61 70 70 6c 69 63 61 74 69 6f 6e  inux application
66e0: 73 22 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  s".</i>.  SELECT
66f0: 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45   * FROM docs WHE
6700: 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 22  RE docs MATCH '"
6710: 6c 69 6e 75 78 20 61 70 70 6c 69 63 61 74 69 6f  linux applicatio
6720: 6e 73 22 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 51  ns"';..  <i>-- Q
6730: 75 65 72 79 20 66 6f 72 20 61 6c 6c 20 64 6f 63  uery for all doc
6740: 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74  uments that cont
6750: 61 69 6e 20 61 20 70 68 72 61 73 65 20 74 68 61  ain a phrase tha
6760: 74 20 6d 61 74 63 68 65 73 20 22 6c 69 6e 2a 20  t matches "lin* 
6770: 61 70 70 2a 22 2e 20 41 73 20 77 65 6c 6c 20 61  app*". As well a
6780: 73 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 6c  s</i>.  <i>-- "l
6790: 69 6e 75 78 20 61 70 70 6c 69 63 61 74 69 6f 6e  inux application
67a0: 73 22 2c 20 74 68 69 73 20 77 69 6c 6c 20 6d 61  s", this will ma
67b0: 74 63 68 20 63 6f 6d 6d 6f 6e 20 70 68 72 61 73  tch common phras
67c0: 65 73 20 73 75 63 68 20 61 73 20 22 6c 69 6e 6f  es such as "lino
67d0: 6c 65 75 6d 20 61 70 70 6c 69 61 6e 63 65 73 22  leum appliances"
67e0: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 72 20  </i>.  <i>-- or 
67f0: 22 6c 69 6e 6b 20 61 70 70 72 65 6e 74 69 63 65  "link apprentice
6800: 22 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  ".</i>.  SELECT 
6810: 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45 52  * FROM docs WHER
6820: 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 22 6c  E docs MATCH '"l
6830: 69 6e 2a 20 61 70 70 2a 22 27 3b 0a 3c 2f 63 6f  in* app*"';.</co
6840: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 75 6c 3e 0a 20  deblock>..<ul>. 
6850: 20 3c 6c 69 3e 3c 70 3e 3c 62 3e 4e 45 41 52 20   <li><p><b>NEAR 
6860: 71 75 65 72 69 65 73 3c 2f 62 3e 2e 20 0a 20 20  queries</b>. .  
6870: 20 20 41 20 4e 45 41 52 20 71 75 65 72 79 20 69    A NEAR query i
6880: 73 20 61 20 71 75 65 72 79 20 74 68 61 74 20 72  s a query that r
6890: 65 74 75 72 6e 73 20 64 6f 63 75 6d 65 6e 74 73  eturns documents
68a0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 20   that contain a 
68b0: 74 77 6f 20 6f 72 0a 20 20 20 20 6d 6f 72 65 20  two or.    more 
68c0: 6e 6f 6d 69 6e 61 74 65 64 20 74 65 72 6d 73 20  nominated terms 
68d0: 6f 72 20 70 68 72 61 73 65 73 20 77 69 74 68 69  or phrases withi
68e0: 6e 20 61 20 73 70 65 63 69 66 69 65 64 20 70 72  n a specified pr
68f0: 6f 78 69 6d 69 74 79 20 6f 66 20 65 61 63 68 20  oximity of each 
6900: 0a 20 20 20 20 6f 74 68 65 72 20 28 62 79 20 64  .    other (by d
6910: 65 66 61 75 6c 74 20 77 69 74 68 20 31 30 20 6f  efault with 10 o
6920: 72 20 6c 65 73 73 20 69 6e 74 65 72 76 65 6e 69  r less interveni
6930: 6e 67 20 74 65 72 6d 73 29 2e 20 41 20 4e 45 41  ng terms). A NEA
6940: 52 20 71 75 65 72 79 20 69 73 20 0a 20 20 20 20  R query is .    
6950: 73 70 65 63 69 66 69 65 64 20 62 79 20 70 75 74  specified by put
6960: 74 69 6e 67 20 74 68 65 20 6b 65 79 77 6f 72 64  ting the keyword
6970: 20 22 4e 45 41 52 22 20 62 65 74 77 65 65 6e 20   "NEAR" between 
6980: 74 77 6f 20 70 68 72 61 73 65 2c 20 74 65 72 6d  two phrase, term
6990: 20 6f 72 20 0a 20 20 20 20 5b 70 72 65 66 69 78   or .    [prefix
69a0: 20 71 75 65 72 69 65 73 5d 2e 20 54 6f 20 73 70   queries]. To sp
69b0: 65 63 69 66 79 20 61 20 70 72 6f 78 69 6d 69 74  ecify a proximit
69c0: 79 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65  y other than the
69d0: 20 64 65 66 61 75 6c 74 2c 0a 20 20 20 20 61 6e   default,.    an
69e0: 20 6f 70 65 72 61 74 6f 72 20 6f 66 20 74 68 65   operator of the
69f0: 20 66 6f 72 6d 20 22 4e 45 41 52 2f 3c 69 3e 26   form "NEAR/<i>&
6a00: 6c 74 3b 4e 26 67 74 3b 3c 2f 69 3e 22 20 6d 61  lt;N&gt;</i>" ma
6a10: 79 20 62 65 20 75 73 65 64 2c 20 77 68 65 72 65  y be used, where
6a20: 0a 20 20 20 20 3c 69 3e 26 6c 74 3b 4e 26 67 74  .    <i>&lt;N&gt
6a30: 3b 3c 2f 69 3e 20 69 73 20 74 68 65 20 6d 61 78  ;</i> is the max
6a40: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
6a50: 6e 74 65 72 76 65 6e 69 6e 67 20 74 65 72 6d 73  ntervening terms
6a60: 20 61 6c 6c 6f 77 65 64 2e 0a 20 20 20 20 46 6f   allowed..    Fo
6a70: 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f 75 6c 3e  r example:.</ul>
6a80: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
6a90: 3c 69 3e 2d 2d 20 56 69 72 74 75 61 6c 20 74 61  <i>-- Virtual ta
6aa0: 62 6c 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 2e  ble declaration.
6ab0: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
6ac0: 52 54 55 41 4c 20 54 41 42 4c 45 20 64 6f 63 73  RTUAL TABLE docs
6ad0: 20 55 53 49 4e 47 20 66 74 73 34 28 29 3b 0a 0a   USING fts4();..
6ae0: 20 20 3c 69 3e 2d 2d 20 56 69 72 74 75 61 6c 20    <i>-- Virtual 
6af0: 74 61 62 6c 65 20 64 61 74 61 2e 3c 2f 69 3e 0a  table data.</i>.
6b00: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 64 6f    INSERT INTO do
6b10: 63 73 20 56 41 4c 55 45 53 28 27 53 51 4c 69 74  cs VALUES('SQLit
6b20: 65 20 69 73 20 61 6e 20 41 43 49 44 20 63 6f 6d  e is an ACID com
6b30: 70 6c 69 61 6e 74 20 65 6d 62 65 64 64 65 64 20  pliant embedded 
6b40: 72 65 6c 61 74 69 6f 6e 61 6c 20 64 61 74 61 62  relational datab
6b50: 61 73 65 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ase management s
6b60: 79 73 74 65 6d 27 29 3b 0a 0a 20 20 3c 69 3e 2d  ystem');..  <i>-
6b70: 2d 20 53 65 61 72 63 68 20 66 6f 72 20 61 20 64  - Search for a d
6b80: 6f 63 75 6d 65 6e 74 20 74 68 61 74 20 63 6f 6e  ocument that con
6b90: 74 61 69 6e 73 20 74 68 65 20 74 65 72 6d 73 20  tains the terms 
6ba0: 22 73 71 6c 69 74 65 22 20 61 6e 64 20 22 64 61  "sqlite" and "da
6bb0: 74 61 62 61 73 65 22 20 77 69 74 68 3c 2f 69 3e  tabase" with</i>
6bc0: 0a 20 20 3c 69 3e 2d 2d 20 6e 6f 74 20 6d 6f 72  .  <i>-- not mor
6bd0: 65 20 74 68 61 6e 20 31 30 20 69 6e 74 65 72 76  e than 10 interv
6be0: 65 6e 69 6e 67 20 74 65 72 6d 73 2e 20 54 68 69  ening terms. Thi
6bf0: 73 20 6d 61 74 63 68 65 73 20 74 68 65 20 6f 6e  s matches the on
6c00: 6c 79 20 64 6f 63 75 6d 65 6e 74 20 69 6e 3c 2f  ly document in</
6c10: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 61 62 6c 65  i>.  <i>-- table
6c20: 20 64 6f 63 73 20 28 73 69 6e 63 65 20 74 68 65   docs (since the
6c30: 72 65 20 61 72 65 20 6f 6e 6c 79 20 73 69 78 20  re are only six 
6c40: 74 65 72 6d 73 20 62 65 74 77 65 65 6e 20 22 53  terms between "S
6c50: 51 4c 69 74 65 22 20 61 6e 64 20 22 64 61 74 61  QLite" and "data
6c60: 62 61 73 65 22 3c 2f 69 3e 20 0a 20 20 3c 69 3e  base"</i> .  <i>
6c70: 2d 2d 20 69 6e 20 74 68 65 20 64 6f 63 75 6d 65  -- in the docume
6c80: 6e 74 29 3c 2f 69 3e 2e 0a 20 20 53 45 4c 45 43  nt)</i>..  SELEC
6c90: 54 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48  T * FROM docs WH
6ca0: 45 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27  ERE docs MATCH '
6cb0: 73 71 6c 69 74 65 20 4e 45 41 52 20 64 61 74 61  sqlite NEAR data
6cc0: 62 61 73 65 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  base';..  <i>-- 
6cd0: 53 65 61 72 63 68 20 66 6f 72 20 61 20 64 6f 63  Search for a doc
6ce0: 75 6d 65 6e 74 20 74 68 61 74 20 63 6f 6e 74 61  ument that conta
6cf0: 69 6e 73 20 74 68 65 20 74 65 72 6d 73 20 22 73  ins the terms "s
6d00: 71 6c 69 74 65 22 20 61 6e 64 20 22 64 61 74 61  qlite" and "data
6d10: 62 61 73 65 22 20 77 69 74 68 3c 2f 69 3e 0a 20  base" with</i>. 
6d20: 20 3c 69 3e 2d 2d 20 6e 6f 74 20 6d 6f 72 65 20   <i>-- not more 
6d30: 74 68 61 6e 20 36 20 69 6e 74 65 72 76 65 6e 69  than 6 interveni
6d40: 6e 67 20 74 65 72 6d 73 2e 20 54 68 69 73 20 61  ng terms. This a
6d50: 6c 73 6f 20 6d 61 74 63 68 65 73 20 74 68 65 20  lso matches the 
6d60: 6f 6e 6c 79 20 64 6f 63 75 6d 65 6e 74 20 69 6e  only document in
6d70: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 61 62  </i>.  <i>-- tab
6d80: 6c 65 20 64 6f 63 73 2e 20 4e 6f 74 65 20 74 68  le docs. Note th
6d90: 61 74 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  at the order in 
6da0: 77 68 69 63 68 20 74 68 65 20 74 65 72 6d 73 20  which the terms 
6db0: 61 70 70 65 61 72 20 69 6e 20 74 68 65 20 64 6f  appear in the do
6dc0: 63 75 6d 65 6e 74 3c 2f 69 3e 0a 20 20 3c 69 3e  cument</i>.  <i>
6dd0: 2d 2d 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  -- does not have
6de0: 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
6df0: 61 73 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  as the order in 
6e00: 77 68 69 63 68 20 74 68 65 79 20 61 70 70 65 61  which they appea
6e10: 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 2e 3c  r in the query.<
6e20: 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  /i>.  SELECT * F
6e30: 52 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64  ROM docs WHERE d
6e40: 6f 63 73 20 4d 41 54 43 48 20 27 64 61 74 61 62  ocs MATCH 'datab
6e50: 61 73 65 20 4e 45 41 52 2f 36 20 73 71 6c 69 74  ase NEAR/6 sqlit
6e60: 65 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 53 65 61  e';..  <i>-- Sea
6e70: 72 63 68 20 66 6f 72 20 61 20 64 6f 63 75 6d 65  rch for a docume
6e80: 6e 74 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  nt that contains
6e90: 20 74 68 65 20 74 65 72 6d 73 20 22 73 71 6c 69   the terms "sqli
6ea0: 74 65 22 20 61 6e 64 20 22 64 61 74 61 62 61 73  te" and "databas
6eb0: 65 22 20 77 69 74 68 3c 2f 69 3e 0a 20 20 3c 69  e" with</i>.  <i
6ec0: 3e 2d 2d 20 6e 6f 74 20 6d 6f 72 65 20 74 68 61  >-- not more tha
6ed0: 6e 20 35 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  n 5 intervening 
6ee0: 74 65 72 6d 73 2e 20 54 68 69 73 20 71 75 65 72  terms. This quer
6ef0: 79 20 6d 61 74 63 68 65 73 20 6e 6f 20 64 6f 63  y matches no doc
6f00: 75 6d 65 6e 74 73 2e 3c 2f 69 3e 0a 20 20 53 45  uments.</i>.  SE
6f10: 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64 6f 63 73  LECT * FROM docs
6f20: 20 57 48 45 52 45 20 64 6f 63 73 20 4d 41 54 43   WHERE docs MATC
6f30: 48 20 27 64 61 74 61 62 61 73 65 20 4e 45 41 52  H 'database NEAR
6f40: 2f 35 20 73 71 6c 69 74 65 27 3b 0a 0a 20 20 3c  /5 sqlite';..  <
6f50: 69 3e 2d 2d 20 53 65 61 72 63 68 20 66 6f 72 20  i>-- Search for 
6f60: 61 20 64 6f 63 75 6d 65 6e 74 20 74 68 61 74 20  a document that 
6f70: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 70 68 72  contains the phr
6f80: 61 73 65 20 22 41 43 49 44 20 63 6f 6d 70 6c 69  ase "ACID compli
6f90: 61 6e 74 22 20 61 6e 64 20 74 68 65 20 74 65 72  ant" and the ter
6fa0: 6d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 64  m</i>.  <i>-- "d
6fb0: 61 74 61 62 61 73 65 22 20 77 69 74 68 20 6e 6f  atabase" with no
6fc0: 74 20 6d 6f 72 65 20 74 68 61 6e 20 32 20 74 65  t more than 2 te
6fd0: 72 6d 73 20 73 65 70 61 72 61 74 69 6e 67 20 74  rms separating t
6fe0: 68 65 20 74 77 6f 2e 20 54 68 69 73 20 6d 61 74  he two. This mat
6ff0: 63 68 65 73 20 74 68 65 3c 2f 69 3e 0a 20 20 3c  ches the</i>.  <
7000: 69 3e 2d 2d 20 64 6f 63 75 6d 65 6e 74 20 73 74  i>-- document st
7010: 6f 72 65 64 20 69 6e 20 74 61 62 6c 65 20 64 6f  ored in table do
7020: 63 73 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  cs.</i>.  SELECT
7030: 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45   * FROM docs WHE
7040: 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 64  RE docs MATCH 'd
7050: 61 74 61 62 61 73 65 20 4e 45 41 52 2f 32 20 22  atabase NEAR/2 "
7060: 41 43 49 44 20 63 6f 6d 70 6c 69 61 6e 74 22 27  ACID compliant"'
7070: 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 53 65 61 72 63  ;..  <i>-- Searc
7080: 68 20 66 6f 72 20 61 20 64 6f 63 75 6d 65 6e 74  h for a document
7090: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74   that contains t
70a0: 68 65 20 70 68 72 61 73 65 20 22 41 43 49 44 20  he phrase "ACID 
70b0: 63 6f 6d 70 6c 69 61 6e 74 22 20 61 6e 64 20 74  compliant" and t
70c0: 68 65 20 74 65 72 6d 3c 2f 69 3e 0a 20 20 3c 69  he term</i>.  <i
70d0: 3e 2d 2d 20 22 73 71 6c 69 74 65 22 20 77 69 74  >-- "sqlite" wit
70e0: 68 20 6e 6f 74 20 6d 6f 72 65 20 74 68 61 6e 20  h not more than 
70f0: 32 20 74 65 72 6d 73 20 73 65 70 61 72 61 74 69  2 terms separati
7100: 6e 67 20 74 68 65 20 74 77 6f 2e 20 54 68 69 73  ng the two. This
7110: 20 61 6c 73 6f 20 6d 61 74 63 68 65 73 3c 2f 69   also matches</i
7120: 3e 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20 6f 6e  >.  <i>-- the on
7130: 6c 79 20 64 6f 63 75 6d 65 6e 74 20 73 74 6f 72  ly document stor
7140: 65 64 20 69 6e 20 74 61 62 6c 65 20 64 6f 63 73  ed in table docs
7150: 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a  .</i>.  SELECT *
7160: 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45 52 45   FROM docs WHERE
7170: 20 64 6f 63 73 20 4d 41 54 43 48 20 27 22 41 43   docs MATCH '"AC
7180: 49 44 20 63 6f 6d 70 6c 69 61 6e 74 22 20 4e 45  ID compliant" NE
7190: 41 52 2f 32 20 73 71 6c 69 74 65 27 3b 0a 3c 2f  AR/2 sqlite';.</
71a0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 75 6c 3e  codeblock>..<ul>
71b0: 0a 20 20 3c 6c 69 20 73 74 79 6c 65 3d 22 6c 69  .  <li style="li
71c0: 73 74 2d 73 74 79 6c 65 3a 20 6e 6f 6e 65 22 3e  st-style: none">
71d0: 3c 70 3e 0a 20 20 20 20 4d 6f 72 65 20 74 68 61  <p>.    More tha
71e0: 6e 20 6f 6e 65 20 4e 45 41 52 20 6f 70 65 72 61  n one NEAR opera
71f0: 74 6f 72 20 6d 61 79 20 61 70 70 65 61 72 20 69  tor may appear i
7200: 6e 20 61 20 73 69 6e 67 6c 65 20 71 75 65 72 79  n a single query
7210: 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 65  . In this case e
7220: 61 63 68 0a 20 20 20 20 70 61 69 72 20 6f 66 20  ach.    pair of 
7230: 74 65 72 6d 73 20 6f 72 20 70 68 72 61 73 65 73  terms or phrases
7240: 20 73 65 70 61 72 61 74 65 64 20 62 79 20 61 20   separated by a 
7250: 4e 45 41 52 20 6f 70 65 72 61 74 6f 72 20 6d 75  NEAR operator mu
7260: 73 74 20 61 70 70 65 61 72 20 77 69 74 68 69 6e  st appear within
7270: 20 74 68 65 0a 20 20 20 20 73 70 65 63 69 66 69   the.    specifi
7280: 65 64 20 70 72 6f 78 69 6d 69 74 79 20 6f 66 20  ed proximity of 
7290: 65 61 63 68 20 6f 74 68 65 72 20 69 6e 20 74 68  each other in th
72a0: 65 20 64 6f 63 75 6d 65 6e 74 2e 20 55 73 69 6e  e document. Usin
72b0: 67 20 74 68 65 20 73 61 6d 65 20 74 61 62 6c 65  g the same table
72c0: 20 61 6e 64 0a 20 20 20 20 64 61 74 61 20 61 73   and.    data as
72d0: 20 69 6e 20 74 68 65 20 62 6c 6f 63 6b 20 6f 66   in the block of
72e0: 20 65 78 61 6d 70 6c 65 73 20 61 62 6f 76 65 3a   examples above:
72f0: 0a 3c 2f 75 6c 3e 0a 0a 3c 63 6f 64 65 62 6c 6f  .</ul>..<codeblo
7300: 63 6b 3e 20 0a 20 3c 69 3e 2d 2d 20 54 68 65 20  ck> . <i>-- The 
7310: 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
7320: 73 65 6c 65 63 74 73 20 64 6f 63 75 6d 65 6e 74  selects document
7330: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  s that contains 
7340: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
7350: 68 65 20 74 65 72 6d 20 3c 2f 69 3e 0a 20 20 3c  he term </i>.  <
7360: 69 3e 2d 2d 20 22 73 71 6c 69 74 65 22 20 73 65  i>-- "sqlite" se
7370: 70 61 72 61 74 65 64 20 62 79 20 74 77 6f 20 6f  parated by two o
7380: 72 20 66 65 77 65 72 20 74 65 72 6d 73 20 66 72  r fewer terms fr
7390: 6f 6d 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  om an instance o
73a0: 66 20 74 68 65 20 74 65 72 6d 20 22 61 63 69 64  f the term "acid
73b0: 22 2c 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 77  ",</i>.  <i>-- w
73c0: 68 69 63 68 20 69 73 20 69 6e 20 74 75 72 6e 20  hich is in turn 
73d0: 73 65 70 61 72 61 74 65 64 20 62 79 20 74 77 6f  separated by two
73e0: 20 6f 72 20 66 65 77 65 72 20 74 65 72 6d 73 20   or fewer terms 
73f0: 66 72 6f 6d 20 61 6e 20 69 6e 73 74 61 6e 63 65  from an instance
7400: 20 6f 66 20 74 68 65 20 74 65 72 6d 3c 2f 69 3e   of the term</i>
7410: 0a 20 20 3c 69 3e 2d 2d 20 22 72 65 6c 61 74 69  .  <i>-- "relati
7420: 6f 6e 61 6c 22 2e 20 41 73 20 69 74 20 68 61 70  onal". As it hap
7430: 70 65 6e 73 2c 20 74 68 65 20 6f 6e 6c 79 20 64  pens, the only d
7440: 6f 63 75 6d 65 6e 74 20 69 6e 20 74 61 62 6c 65  ocument in table
7450: 20 64 6f 63 73 20 73 61 74 69 73 66 69 65 73 20   docs satisfies 
7460: 74 68 69 73 20 63 72 69 74 65 72 69 61 2e 3c 2f  this criteria.</
7470: 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  i>.  SELECT * FR
7480: 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64 6f  OM docs WHERE do
7490: 63 73 20 4d 41 54 43 48 20 27 73 71 6c 69 74 65  cs MATCH 'sqlite
74a0: 20 4e 45 41 52 2f 32 20 61 63 69 64 20 4e 45 41   NEAR/2 acid NEA
74b0: 52 2f 32 20 72 65 6c 61 74 69 6f 6e 61 6c 27 3b  R/2 relational';
74c0: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 71  ..  <i>-- This q
74d0: 75 65 72 79 20 6d 61 74 63 68 65 73 20 6e 6f 20  uery matches no 
74e0: 64 6f 63 75 6d 65 6e 74 73 2e 20 54 68 65 72 65  documents. There
74f0: 20 69 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   is an instance 
7500: 6f 66 20 74 68 65 20 74 65 72 6d 20 22 73 71 6c  of the term "sql
7510: 69 74 65 22 20 77 69 74 68 3c 2f 69 3e 0a 20 20  ite" with</i>.  
7520: 3c 69 3e 2d 2d 20 73 75 66 66 69 63 69 65 6e 74  <i>-- sufficient
7530: 20 70 72 6f 78 69 6d 69 74 79 20 74 6f 20 61 6e   proximity to an
7540: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 22 61 63   instance of "ac
7550: 69 64 22 20 62 75 74 20 69 74 20 69 73 20 6e 6f  id" but it is no
7560: 74 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 63  t sufficiently c
7570: 6c 6f 73 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  lose</i>.  <i>--
7580: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7590: 6f 66 20 74 68 65 20 74 65 72 6d 20 22 72 65 6c  of the term "rel
75a0: 61 74 69 6f 6e 61 6c 22 2e 3c 2f 69 3e 0a 20 20  ational".</i>.  
75b0: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64 6f  SELECT * FROM do
75c0: 63 73 20 57 48 45 52 45 20 64 6f 63 73 20 4d 41  cs WHERE docs MA
75d0: 54 43 48 20 27 61 63 69 64 20 4e 45 41 52 2f 32  TCH 'acid NEAR/2
75e0: 20 73 71 6c 69 74 65 20 4e 45 41 52 2f 32 20 72   sqlite NEAR/2 r
75f0: 65 6c 61 74 69 6f 6e 61 6c 27 3b 0a 3c 2f 63 6f  elational';.</co
7600: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20  deblock>..<p>.  
7610: 50 68 72 61 73 65 20 61 6e 64 20 4e 45 41 52 20  Phrase and NEAR 
7620: 71 75 65 72 69 65 73 20 6d 61 79 20 6e 6f 74 20  queries may not 
7630: 73 70 61 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f  span multiple co
7640: 6c 75 6d 6e 73 20 77 69 74 68 69 6e 20 61 20 72  lumns within a r
7650: 6f 77 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 74  ow...<p>.  The t
7660: 68 72 65 65 20 62 61 73 69 63 20 71 75 65 72 79  hree basic query
7670: 20 74 79 70 65 73 20 64 65 73 63 72 69 62 65 64   types described
7680: 20 61 62 6f 76 65 20 6d 61 79 20 62 65 20 75 73   above may be us
7690: 65 64 20 74 6f 20 71 75 65 72 79 20 74 68 65 20  ed to query the 
76a0: 66 75 6c 6c 2d 74 65 78 74 0a 20 20 69 6e 64 65  full-text.  inde
76b0: 78 20 66 6f 72 20 74 68 65 20 73 65 74 20 6f 66  x for the set of
76c0: 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20   documents that 
76d0: 6d 61 74 63 68 20 74 68 65 20 73 70 65 63 69 66  match the specif
76e0: 69 65 64 20 63 72 69 74 65 72 69 61 2e 20 55 73  ied criteria. Us
76f0: 69 6e 67 20 74 68 65 0a 20 20 46 54 53 20 71 75  ing the.  FTS qu
7700: 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e 20 6c  ery expression l
7710: 61 6e 67 75 61 67 65 20 69 74 20 69 73 20 70 6f  anguage it is po
7720: 73 73 69 62 6c 65 20 74 6f 20 70 65 72 66 6f 72  ssible to perfor
7730: 6d 20 76 61 72 69 6f 75 73 20 73 65 74 20 0a 20  m various set . 
7740: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7750: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 62 61  he results of ba
7760: 73 69 63 20 71 75 65 72 69 65 73 2e 20 54 68 65  sic queries. The
7770: 72 65 20 61 72 65 20 63 75 72 72 65 6e 74 6c 79  re are currently
7780: 20 74 68 72 65 65 20 0a 20 20 73 75 70 70 6f 72   three .  suppor
7790: 74 65 64 20 6f 70 65 72 61 74 69 6f 6e 73 3a 0a  ted operations:.
77a0: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 54 68 65  .<ul>.  <li> The
77b0: 20 41 4e 44 20 6f 70 65 72 61 74 6f 72 20 64 65   AND operator de
77c0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 3c 62 3e  termines the <b>
77d0: 69 6e 74 65 72 73 65 63 74 69 6f 6e 3c 2f 62 3e  intersection</b>
77e0: 20 6f 66 20 74 77 6f 20 73 65 74 73 20 6f 66 20   of two sets of 
77f0: 64 6f 63 75 6d 65 6e 74 73 2e 0a 0a 20 20 3c 6c  documents...  <l
7800: 69 3e 20 54 68 65 20 4f 52 20 6f 70 65 72 61 74  i> The OR operat
7810: 6f 72 20 63 61 6c 63 75 6c 61 74 65 73 20 74 68  or calculates th
7820: 65 20 3c 62 3e 75 6e 69 6f 6e 3c 2f 62 3e 20 6f  e <b>union</b> o
7830: 66 20 74 77 6f 20 73 65 74 73 20 6f 66 20 64 6f  f two sets of do
7840: 63 75 6d 65 6e 74 73 2e 0a 0a 20 20 3c 6c 69 3e  cuments...  <li>
7850: 20 54 68 65 20 4e 4f 54 20 6f 70 65 72 61 74 6f   The NOT operato
7860: 72 20 28 6f 72 2c 20 69 66 20 75 73 69 6e 67 20  r (or, if using 
7870: 74 68 65 20 73 74 61 6e 64 61 72 64 20 73 79 6e  the standard syn
7880: 74 61 78 2c 20 61 20 75 6e 61 72 79 20 22 2d 22  tax, a unary "-"
7890: 20 6f 70 65 72 61 74 6f 72 29 0a 20 20 20 20 20   operator).     
78a0: 20 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f    may be used to
78b0: 20 63 6f 6d 70 75 74 65 20 74 68 65 20 3c 62 3e   compute the <b>
78c0: 72 65 6c 61 74 69 76 65 20 63 6f 6d 70 6c 65 6d  relative complem
78d0: 65 6e 74 3c 2f 62 3e 20 6f 66 20 6f 6e 65 20 73  ent</b> of one s
78e0: 65 74 20 6f 66 0a 20 20 20 20 20 20 20 64 6f 63  et of.       doc
78f0: 75 6d 65 6e 74 73 20 77 69 74 68 20 72 65 73 70  uments with resp
7900: 65 63 74 20 74 6f 20 61 6e 6f 74 68 65 72 2e 0a  ect to another..
7910: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65  </ul>..<p>.  The
7920: 20 46 54 53 20 6d 6f 64 75 6c 65 73 20 6d 61 79   FTS modules may
7930: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   be compiled to 
7940: 75 73 65 20 6f 6e 65 20 6f 66 20 74 77 6f 20 73  use one of two s
7950: 6c 69 67 68 74 6c 79 20 64 69 66 66 65 72 65 6e  lightly differen
7960: 74 20 76 65 72 73 69 6f 6e 73 0a 20 20 6f 66 20  t versions.  of 
7970: 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 71 75  the full-text qu
7980: 65 72 79 20 73 79 6e 74 61 78 2c 20 74 68 65 20  ery syntax, the 
7990: 22 73 74 61 6e 64 61 72 64 22 20 71 75 65 72 79  "standard" query
79a0: 20 73 79 6e 74 61 78 20 61 6e 64 20 74 68 65 20   syntax and the 
79b0: 22 65 6e 68 61 6e 63 65 64 22 20 0a 20 20 71 75  "enhanced" .  qu
79c0: 65 72 79 20 73 79 6e 74 61 78 2e 20 54 68 65 20  ery syntax. The 
79d0: 62 61 73 69 63 20 74 65 72 6d 2c 20 74 65 72 6d  basic term, term
79e0: 2d 70 72 65 66 69 78 2c 20 70 68 72 61 73 65 20  -prefix, phrase 
79f0: 61 6e 64 20 4e 45 41 52 20 71 75 65 72 69 65 73  and NEAR queries
7a00: 20 64 65 73 63 72 69 62 65 64 20 0a 20 20 61 62   described .  ab
7a10: 6f 76 65 20 61 72 65 20 74 68 65 20 73 61 6d 65  ove are the same
7a20: 20 69 6e 20 62 6f 74 68 20 76 65 72 73 69 6f 6e   in both version
7a30: 73 20 6f 66 20 74 68 65 20 73 79 6e 74 61 78 2e  s of the syntax.
7a40: 20 54 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   The way in whic
7a50: 68 20 73 65 74 20 0a 20 20 6f 70 65 72 61 74 69  h set .  operati
7a60: 6f 6e 73 20 61 72 65 20 73 70 65 63 69 66 69 65  ons are specifie
7a70: 64 20 69 73 20 73 6c 69 67 68 74 6c 79 20 64 69  d is slightly di
7a80: 66 66 65 72 65 6e 74 2e 20 54 68 65 20 66 6f 6c  fferent. The fol
7a90: 6c 6f 77 69 6e 67 20 74 77 6f 20 73 75 62 2d 73  lowing two sub-s
7aa0: 65 63 74 69 6f 6e 73 20 0a 20 20 64 65 73 63 72  ections .  descr
7ab0: 69 62 65 20 74 68 65 20 70 61 72 74 20 6f 66 20  ibe the part of 
7ac0: 74 68 65 20 74 77 6f 20 71 75 65 72 79 20 73 79  the two query sy
7ad0: 6e 74 61 78 65 73 20 74 68 61 74 20 70 65 72 74  ntaxes that pert
7ae0: 61 69 6e 73 20 74 6f 20 73 65 74 20 6f 70 65 72  ains to set oper
7af0: 61 74 69 6f 6e 73 2e 20 0a 20 20 52 65 66 65 72  ations. .  Refer
7b00: 20 74 6f 20 74 68 65 20 64 65 73 63 72 69 70 74   to the descript
7b10: 69 6f 6e 20 6f 66 20 68 6f 77 20 74 6f 20 5b 63  ion of how to [c
7b20: 6f 6d 70 69 6c 65 20 66 74 73 5d 20 66 6f 72 20  ompile fts] for 
7b30: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6e 6f 74 65  compilation note
7b40: 73 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 65 6e  s...<h2 tags="en
7b50: 68 61 6e 63 65 64 20 71 75 65 72 79 20 73 79 6e  hanced query syn
7b60: 74 61 78 22 3e 0a 20 20 53 65 74 20 4f 70 65 72  tax">.  Set Oper
7b70: 61 74 69 6f 6e 73 20 55 73 69 6e 67 20 54 68 65  ations Using The
7b80: 20 45 6e 68 61 6e 63 65 64 20 51 75 65 72 79 20   Enhanced Query 
7b90: 53 79 6e 74 61 78 3c 2f 68 32 3e 0a 0a 3c 70 3e  Syntax</h2>..<p>
7ba0: 0a 20 20 54 68 65 20 65 6e 68 61 6e 63 65 64 20  .  The enhanced 
7bb0: 71 75 65 72 79 20 73 79 6e 74 61 78 20 73 75 70  query syntax sup
7bc0: 70 6f 72 74 73 20 74 68 65 20 41 4e 44 2c 20 4f  ports the AND, O
7bd0: 52 20 61 6e 64 20 4e 4f 54 20 62 69 6e 61 72 79  R and NOT binary
7be0: 20 73 65 74 20 6f 70 65 72 61 74 6f 72 73 2e 0a   set operators..
7bf0: 20 20 45 61 63 68 20 6f 66 20 74 68 65 20 74 77    Each of the tw
7c00: 6f 20 6f 70 65 72 61 6e 64 73 20 74 6f 20 61 6e  o operands to an
7c10: 20 6f 70 65 72 61 74 6f 72 20 6d 61 79 20 62 65   operator may be
7c20: 20 61 20 62 61 73 69 63 20 46 54 53 20 71 75 65   a basic FTS que
7c30: 72 79 2c 20 6f 72 20 74 68 65 0a 20 20 72 65 73  ry, or the.  res
7c40: 75 6c 74 20 6f 66 20 61 6e 6f 74 68 65 72 20 41  ult of another A
7c50: 4e 44 2c 20 4f 52 20 6f 72 20 4e 4f 54 20 73 65  ND, OR or NOT se
7c60: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f 70 65  t operation. Ope
7c70: 72 61 74 6f 72 73 20 6d 75 73 74 20 62 65 20 65  rators must be e
7c80: 6e 74 65 72 65 64 0a 20 20 75 73 69 6e 67 20 63  ntered.  using c
7c90: 61 70 69 74 61 6c 20 6c 65 74 74 65 72 73 2e 20  apital letters. 
7ca0: 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
7cb0: 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
7cc0: 61 73 20 62 61 73 69 63 20 74 65 72 6d 20 71 75  as basic term qu
7cd0: 65 72 69 65 73 0a 20 20 69 6e 73 74 65 61 64 20  eries.  instead 
7ce0: 6f 66 20 73 65 74 20 6f 70 65 72 61 74 6f 72 73  of set operators
7cf0: 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 41 4e 44  ...<p>.  The AND
7d00: 20 6f 70 65 72 61 74 6f 72 20 6d 61 79 20 62 65   operator may be
7d10: 20 69 6d 70 6c 69 63 69 74 6c 79 20 73 70 65 63   implicitly spec
7d20: 69 66 69 65 64 2e 20 49 66 20 74 77 6f 20 62 61  ified. If two ba
7d30: 73 69 63 20 71 75 65 72 69 65 73 20 61 70 70 65  sic queries appe
7d40: 61 72 20 0a 20 20 77 69 74 68 20 6e 6f 20 6f 70  ar .  with no op
7d50: 65 72 61 74 6f 72 20 73 65 70 61 72 61 74 69 6e  erator separatin
7d60: 67 20 74 68 65 6d 20 69 6e 20 61 6e 20 46 54 53  g them in an FTS
7d70: 20 71 75 65 72 79 20 73 74 72 69 6e 67 2c 20 74   query string, t
7d80: 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 20  he results are. 
7d90: 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20   the same as if 
7da0: 74 68 65 20 74 77 6f 20 62 61 73 69 63 20 71 75  the two basic qu
7db0: 65 72 69 65 73 20 77 65 72 65 20 73 65 70 61 72  eries were separ
7dc0: 61 74 65 64 20 62 79 20 61 6e 20 41 4e 44 20 6f  ated by an AND o
7dd0: 70 65 72 61 74 6f 72 2e 0a 20 20 46 6f 72 20 65  perator..  For e
7de0: 78 61 6d 70 6c 65 2c 20 74 68 65 20 71 75 65 72  xample, the quer
7df0: 79 20 65 78 70 72 65 73 73 69 6f 6e 20 22 69 6d  y expression "im
7e00: 70 6c 69 63 69 74 20 6f 70 65 72 61 74 6f 72 22  plicit operator"
7e10: 20 69 73 20 61 20 6d 6f 72 65 20 73 75 63 63 69   is a more succi
7e20: 6e 63 74 0a 20 20 76 65 72 73 69 6f 6e 20 6f 66  nct.  version of
7e30: 20 22 69 6d 70 6c 69 63 69 74 20 41 4e 44 20 6f   "implicit AND o
7e40: 70 65 72 61 74 6f 72 22 2e 0a 0a 3c 63 6f 64 65  perator"...<code
7e50: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 56  block>.  <i>-- V
7e60: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 64 65 63  irtual table dec
7e70: 6c 61 72 61 74 69 6f 6e 3c 2f 69 3e 0a 20 20 43  laration</i>.  C
7e80: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
7e90: 42 4c 45 20 64 6f 63 73 20 55 53 49 4e 47 20 66  BLE docs USING f
7ea0: 74 73 33 28 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  ts3();..  <i>-- 
7eb0: 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 64 61  Virtual table da
7ec0: 74 61 3c 2f 69 3e 0a 20 20 49 4e 53 45 52 54 20  ta</i>.  INSERT 
7ed0: 49 4e 54 4f 20 64 6f 63 73 28 64 6f 63 69 64 2c  INTO docs(docid,
7ee0: 20 63 6f 6e 74 65 6e 74 29 20 56 41 4c 55 45 53   content) VALUES
7ef0: 28 31 2c 20 27 61 20 64 61 74 61 62 61 73 65 20  (1, 'a database 
7f00: 69 73 20 61 20 73 6f 66 74 77 61 72 65 20 73 79  is a software sy
7f10: 73 74 65 6d 27 29 3b 0a 20 20 49 4e 53 45 52 54  stem');.  INSERT
7f20: 20 49 4e 54 4f 20 64 6f 63 73 28 64 6f 63 69 64   INTO docs(docid
7f30: 2c 20 63 6f 6e 74 65 6e 74 29 20 56 41 4c 55 45  , content) VALUE
7f40: 53 28 32 2c 20 27 73 71 6c 69 74 65 20 69 73 20  S(2, 'sqlite is 
7f50: 61 20 73 6f 66 74 77 61 72 65 20 73 79 73 74 65  a software syste
7f60: 6d 27 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e  m');.  INSERT IN
7f70: 54 4f 20 64 6f 63 73 28 64 6f 63 69 64 2c 20 63  TO docs(docid, c
7f80: 6f 6e 74 65 6e 74 29 20 56 41 4c 55 45 53 28 33  ontent) VALUES(3
7f90: 2c 20 27 73 71 6c 69 74 65 20 69 73 20 61 20 64  , 'sqlite is a d
7fa0: 61 74 61 62 61 73 65 27 29 3b 0a 0a 20 20 3c 69  atabase');..  <i
7fb0: 3e 2d 2d 20 52 65 74 75 72 6e 20 74 68 65 20 73  >-- Return the s
7fc0: 65 74 20 6f 66 20 64 6f 63 75 6d 65 6e 74 73 20  et of documents 
7fd0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65  that contain the
7fe0: 20 74 65 72 6d 20 22 73 71 6c 69 74 65 22 2c 20   term "sqlite", 
7ff0: 61 6e 64 20 74 68 65 3c 2f 69 3e 0a 20 20 3c 69  and the</i>.  <i
8000: 3e 2d 2d 20 74 65 72 6d 20 22 64 61 74 61 62 61  >-- term "databa
8010: 73 65 22 2e 20 54 68 69 73 20 71 75 65 72 79 20  se". This query 
8020: 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
8030: 64 6f 63 75 6d 65 6e 74 20 77 69 74 68 20 64 6f  document with do
8040: 63 69 64 20 33 20 6f 6e 6c 79 2e 3c 2f 69 3e 0a  cid 3 only.</i>.
8050: 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20    SELECT * FROM 
8060: 64 6f 63 73 20 57 48 45 52 45 20 64 6f 63 73 20  docs WHERE docs 
8070: 4d 41 54 43 48 20 27 73 71 6c 69 74 65 20 41 4e  MATCH 'sqlite AN
8080: 44 20 64 61 74 61 62 61 73 65 27 3b 0a 0a 20 20  D database';..  
8090: 3c 69 3e 2d 2d 20 41 67 61 69 6e 2c 20 72 65 74  <i>-- Again, ret
80a0: 75 72 6e 20 74 68 65 20 73 65 74 20 6f 66 20 64  urn the set of d
80b0: 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f  ocuments that co
80c0: 6e 74 61 69 6e 20 62 6f 74 68 20 22 73 71 6c 69  ntain both "sqli
80d0: 74 65 22 20 61 6e 64 3c 2f 69 3e 0a 20 20 3c 69  te" and</i>.  <i
80e0: 3e 2d 2d 20 22 64 61 74 61 62 61 73 65 22 2e 20  >-- "database". 
80f0: 54 68 69 73 20 74 69 6d 65 2c 20 75 73 65 20 61  This time, use a
8100: 6e 20 69 6d 70 6c 69 63 69 74 20 41 4e 44 20 6f  n implicit AND o
8110: 70 65 72 61 74 6f 72 2e 20 41 67 61 69 6e 2c 20  perator. Again, 
8120: 64 6f 63 75 6d 65 6e 74 3c 2f 69 3e 0a 20 20 3c  document</i>.  <
8130: 69 3e 2d 2d 20 33 20 69 73 20 74 68 65 20 6f 6e  i>-- 3 is the on
8140: 6c 79 20 64 6f 63 75 6d 65 6e 74 20 6d 61 74 63  ly document matc
8150: 68 65 64 20 62 79 20 74 68 69 73 20 71 75 65 72  hed by this quer
8160: 79 2e 20 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  y. </i>.  SELECT
8170: 20 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45   * FROM docs WHE
8180: 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 64  RE docs MATCH 'd
8190: 61 74 61 62 61 73 65 20 73 71 6c 69 74 65 27 3b  atabase sqlite';
81a0: 0a 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20  ..  <i>-- Query 
81b0: 66 6f 72 20 74 68 65 20 73 65 74 20 6f 66 20 64  for the set of d
81c0: 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f  ocuments that co
81d0: 6e 74 61 69 6e 73 20 65 69 74 68 65 72 20 22 73  ntains either "s
81e0: 71 6c 69 74 65 22 20 6f 72 20 22 64 61 74 61 62  qlite" or "datab
81f0: 61 73 65 22 2e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  ase".</i>.  <i>-
8200: 2d 20 41 6c 6c 20 74 68 72 65 65 20 64 6f 63 75  - All three docu
8210: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 64 61 74  ments in the dat
8220: 61 62 61 73 65 20 61 72 65 20 6d 61 74 63 68 65  abase are matche
8230: 64 20 62 79 20 74 68 69 73 20 71 75 65 72 79 2e  d by this query.
8240: 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20  </i>.  SELECT * 
8250: 46 52 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20  FROM docs WHERE 
8260: 64 6f 63 73 20 4d 41 54 43 48 20 27 73 71 6c 69  docs MATCH 'sqli
8270: 74 65 20 4f 52 20 64 61 74 61 62 61 73 65 27 3b  te OR database';
8280: 0a 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20  ..  <i>-- Query 
8290: 66 6f 72 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74  for all document
82a0: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74  s that contain t
82b0: 68 65 20 74 65 72 6d 20 22 64 61 74 61 62 61 73  he term "databas
82c0: 65 22 2c 20 62 75 74 20 64 6f 20 6e 6f 74 20 63  e", but do not c
82d0: 6f 6e 74 61 69 6e 3c 2f 69 3e 0a 20 20 3c 69 3e  ontain</i>.  <i>
82e0: 2d 2d 20 74 68 65 20 74 65 72 6d 20 22 73 71 6c  -- the term "sql
82f0: 69 74 65 22 2e 20 44 6f 63 75 6d 65 6e 74 20 31  ite". Document 1
8300: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 64 6f 63   is the only doc
8310: 75 6d 65 6e 74 20 74 68 61 74 20 6d 61 74 63 68  ument that match
8320: 65 73 20 74 68 69 73 20 63 72 69 74 65 72 69 61  es this criteria
8330: 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a  .</i>.  SELECT *
8340: 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45 52 45   FROM docs WHERE
8350: 20 64 6f 63 73 20 4d 41 54 43 48 20 27 64 61 74   docs MATCH 'dat
8360: 61 62 61 73 65 20 4e 4f 54 20 73 71 6c 69 74 65  abase NOT sqlite
8370: 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20  ';..  <i>-- The 
8380: 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
8390: 6d 61 74 63 68 65 73 20 6e 6f 20 64 6f 63 75 6d  matches no docum
83a0: 65 6e 74 73 2e 20 42 65 63 61 75 73 65 20 22 61  ents. Because "a
83b0: 6e 64 22 20 69 73 20 69 6e 20 6c 6f 77 65 72 63  nd" is in lowerc
83c0: 61 73 65 20 6c 65 74 74 65 72 73 2c 3c 2f 69 3e  ase letters,</i>
83d0: 0a 20 20 3c 69 3e 2d 2d 20 69 74 20 69 73 20 69  .  <i>-- it is i
83e0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
83f0: 62 61 73 69 63 20 74 65 72 6d 20 71 75 65 72 79  basic term query
8400: 20 69 6e 73 74 65 61 64 20 6f 66 20 61 6e 20 6f   instead of an o
8410: 70 65 72 61 74 6f 72 2e 20 4f 70 65 72 61 74 6f  perator. Operato
8420: 72 73 20 6d 75 73 74 3c 2f 69 3e 0a 20 20 3c 69  rs must</i>.  <i
8430: 3e 2d 2d 20 62 65 20 73 70 65 63 69 66 69 65 64  >-- be specified
8440: 20 75 73 69 6e 67 20 63 61 70 69 74 61 6c 20 6c   using capital l
8450: 65 74 74 65 72 73 2e 20 49 6e 20 70 72 61 63 74  etters. In pract
8460: 69 63 65 2c 20 74 68 69 73 20 71 75 65 72 79 20  ice, this query 
8470: 77 69 6c 6c 20 6d 61 74 63 68 20 61 6e 79 20 64  will match any d
8480: 6f 63 75 6d 65 6e 74 73 3c 2f 69 3e 0a 20 20 3c  ocuments</i>.  <
8490: 69 3e 2d 2d 20 74 68 61 74 20 63 6f 6e 74 61 69  i>-- that contai
84a0: 6e 20 65 61 63 68 20 6f 66 20 74 68 65 20 74 68  n each of the th
84b0: 72 65 65 20 74 65 72 6d 73 20 22 64 61 74 61 62  ree terms "datab
84c0: 61 73 65 22 2c 20 22 61 6e 64 22 20 61 6e 64 20  ase", "and" and 
84d0: 22 73 71 6c 69 74 65 22 20 61 74 20 6c 65 61 73  "sqlite" at leas
84e0: 74 20 6f 6e 63 65 2e 3c 2f 69 3e 0a 20 20 3c 69  t once.</i>.  <i
84f0: 3e 2d 2d 20 4e 6f 20 64 6f 63 75 6d 65 6e 74 73  >-- No documents
8500: 20 69 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20   in the example 
8510: 64 61 74 61 20 61 62 6f 76 65 20 6d 61 74 63 68  data above match
8520: 20 74 68 69 73 20 63 72 69 74 65 72 69 61 2e 3c   this criteria.<
8530: 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  /i>.  SELECT * F
8540: 52 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64  ROM docs WHERE d
8550: 6f 63 73 20 4d 41 54 43 48 20 27 64 61 74 61 62  ocs MATCH 'datab
8560: 61 73 65 20 61 6e 64 20 73 71 6c 69 74 65 27 3b  ase and sqlite';
8570: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
8580: 70 3e 0a 20 20 54 68 65 20 65 78 61 6d 70 6c 65  p>.  The example
8590: 73 20 61 62 6f 76 65 20 61 6c 6c 20 75 73 65 20  s above all use 
85a0: 62 61 73 69 63 20 66 75 6c 6c 2d 74 65 78 74 20  basic full-text 
85b0: 74 65 72 6d 20 71 75 65 72 69 65 73 20 61 73 20  term queries as 
85c0: 62 6f 74 68 20 6f 70 65 72 61 6e 64 73 20 6f 66  both operands of
85d0: 20 0a 20 20 74 68 65 20 73 65 74 20 6f 70 65 72   .  the set oper
85e0: 61 74 69 6f 6e 73 20 64 65 6d 6f 6e 73 74 72 61  ations demonstra
85f0: 74 65 64 2e 20 50 68 72 61 73 65 20 61 6e 64 20  ted. Phrase and 
8600: 4e 45 41 52 20 71 75 65 72 69 65 73 20 6d 61 79  NEAR queries may
8610: 20 61 6c 73 6f 20 62 65 20 75 73 65 64 2c 0a 20   also be used,. 
8620: 20 61 73 20 6d 61 79 20 74 68 65 20 72 65 73 75   as may the resu
8630: 6c 74 73 20 6f 66 20 6f 74 68 65 72 20 73 65 74  lts of other set
8640: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 57 68 65   operations. Whe
8650: 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  n more than one 
8660: 73 65 74 20 6f 70 65 72 61 74 69 6f 6e 0a 20 20  set operation.  
8670: 69 73 20 70 72 65 73 65 6e 74 20 69 6e 20 61 6e  is present in an
8680: 20 46 54 53 20 71 75 65 72 79 2c 20 74 68 65 20   FTS query, the 
8690: 70 72 65 63 65 64 65 6e 63 65 20 6f 66 20 6f 70  precedence of op
86a0: 65 72 61 74 6f 72 73 20 69 73 20 61 73 20 66 6f  erators is as fo
86b0: 6c 6c 6f 77 73 3a 0a 0a 3c 74 61 62 6c 65 20 73  llows:..<table s
86c0: 74 72 69 70 65 64 3d 31 3e 0a 20 20 3c 74 72 3e  triped=1>.  <tr>
86d0: 3c 74 68 3e 4f 70 65 72 61 74 6f 72 3c 74 68 3e  <th>Operator<th>
86e0: 45 6e 68 61 6e 63 65 64 20 51 75 65 72 79 20 53  Enhanced Query S
86f0: 79 6e 74 61 78 20 50 72 65 63 65 64 65 6e 63 65  yntax Precedence
8700: 0a 20 20 3c 74 72 3e 3c 74 64 3e 4e 4f 54 20 3c  .  <tr><td>NOT <
8710: 74 64 3e 20 48 69 67 68 65 73 74 20 70 72 65 63  td> Highest prec
8720: 65 64 65 6e 63 65 20 28 74 69 67 68 74 65 73 74  edence (tightest
8730: 20 67 72 6f 75 70 69 6e 67 29 2e 0a 20 20 3c 74   grouping)..  <t
8740: 72 3e 3c 74 64 3e 41 4e 44 20 3c 74 64 3e 0a 20  r><td>AND <td>. 
8750: 20 3c 74 72 3e 3c 74 64 3e 4f 52 20 20 3c 74 64   <tr><td>OR  <td
8760: 3e 20 4c 6f 77 65 73 74 20 70 72 65 63 65 64 65  > Lowest precede
8770: 6e 63 65 20 28 6c 6f 6f 73 65 73 74 20 67 72 6f  nce (loosest gro
8780: 75 70 69 6e 67 29 2e 0a 3c 2f 74 61 62 6c 65 3e  uping)..</table>
8790: 0a 0a 3c 70 3e 0a 20 20 57 68 65 6e 20 75 73 69  ..<p>.  When usi
87a0: 6e 67 20 74 68 65 20 65 6e 68 61 6e 63 65 64 20  ng the enhanced 
87b0: 71 75 65 72 79 20 73 79 6e 74 61 78 2c 20 70 61  query syntax, pa
87c0: 72 65 6e 74 68 65 73 69 73 20 6d 61 79 20 62 65  renthesis may be
87d0: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 72 69 64   used to overrid
87e0: 65 0a 20 20 74 68 65 20 64 65 66 61 75 6c 74 20  e.  the default 
87f0: 70 72 65 63 65 64 65 6e 63 65 20 6f 66 20 74 68  precedence of th
8800: 65 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  e various operat
8810: 6f 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ors. For example
8820: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  :..<codeblock>..
8830: 20 20 3c 69 3e 2d 2d 20 52 65 74 75 72 6e 20 74    <i>-- Return t
8840: 68 65 20 64 6f 63 69 64 20 76 61 6c 75 65 73 20  he docid values 
8850: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
8860: 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68  all documents th
8870: 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 3c 2f  at contain the</
8880: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 77 6f 20 74  i>.  <i>-- two t
8890: 65 72 6d 73 20 22 73 71 6c 69 74 65 22 20 61 6e  erms "sqlite" an
88a0: 64 20 22 64 61 74 61 62 61 73 65 22 2c 20 61 6e  d "database", an
88b0: 64 2f 6f 72 20 63 6f 6e 74 61 69 6e 20 74 68 65  d/or contain the
88c0: 20 74 65 72 6d 20 22 6c 69 62 72 61 72 79 22 2e   term "library".
88d0: 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 64 6f  </i>.  SELECT do
88e0: 63 69 64 20 46 52 4f 4d 20 64 6f 63 73 20 57 48  cid FROM docs WH
88f0: 45 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27  ERE docs MATCH '
8900: 73 71 6c 69 74 65 20 41 4e 44 20 64 61 74 61 62  sqlite AND datab
8910: 61 73 65 20 4f 52 20 6c 69 62 72 61 72 79 27 3b  ase OR library';
8920: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 71  ..  <i>-- This q
8930: 75 65 72 79 20 69 73 20 65 71 75 69 76 61 6c 65  uery is equivale
8940: 6e 74 20 74 6f 20 74 68 65 20 61 62 6f 76 65 2e  nt to the above.
8950: 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 64 6f  </i>.  SELECT do
8960: 63 69 64 20 46 52 4f 4d 20 64 6f 63 73 20 57 48  cid FROM docs WH
8970: 45 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27  ERE docs MATCH '
8980: 73 71 6c 69 74 65 20 41 4e 44 20 64 61 74 61 62  sqlite AND datab
8990: 61 73 65 27 0a 20 20 20 20 55 4e 49 4f 4e 0a 20  ase'.    UNION. 
89a0: 20 53 45 4c 45 43 54 20 64 6f 63 69 64 20 46 52   SELECT docid FR
89b0: 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64 6f  OM docs WHERE do
89c0: 63 73 20 4d 41 54 43 48 20 27 6c 69 62 72 61 72  cs MATCH 'librar
89d0: 79 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 51 75 65  y';..  <i>-- Que
89e0: 72 79 20 66 6f 72 20 74 68 65 20 73 65 74 20 6f  ry for the set o
89f0: 66 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74  f documents that
8a00: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
8a10: 72 6d 20 22 6c 69 6e 75 78 22 2c 20 61 6e 64 20  rm "linux", and 
8a20: 61 74 20 6c 65 61 73 74 3c 2f 69 3e 0a 20 20 3c  at least</i>.  <
8a30: 69 3e 2d 2d 20 6f 6e 65 20 6f 66 20 74 68 65 20  i>-- one of the 
8a40: 70 68 72 61 73 65 73 20 22 73 71 6c 69 74 65 20  phrases "sqlite 
8a50: 64 61 74 61 62 61 73 65 22 20 61 6e 64 20 22 73  database" and "s
8a60: 71 6c 69 74 65 20 6c 69 62 72 61 72 79 22 2e 3c  qlite library".<
8a70: 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 64 6f 63  /i>.  SELECT doc
8a80: 69 64 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45  id FROM docs WHE
8a90: 52 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 28  RE docs MATCH '(
8aa0: 22 73 71 6c 69 74 65 20 64 61 74 61 62 61 73 65  "sqlite database
8ab0: 22 20 4f 52 20 22 73 71 6c 69 74 65 20 6c 69 62  " OR "sqlite lib
8ac0: 72 61 72 79 22 29 20 41 4e 44 20 6c 69 6e 75 78  rary") AND linux
8ad0: 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73  ';..  <i>-- This
8ae0: 20 71 75 65 72 79 20 69 73 20 65 71 75 69 76 61   query is equiva
8af0: 6c 65 6e 74 20 74 6f 20 74 68 65 20 61 62 6f 76  lent to the abov
8b00: 65 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  e.</i>.  SELECT 
8b10: 64 6f 63 69 64 20 46 52 4f 4d 20 64 6f 63 73 20  docid FROM docs 
8b20: 57 48 45 52 45 20 64 6f 63 73 20 4d 41 54 43 48  WHERE docs MATCH
8b30: 20 27 6c 69 6e 75 78 27 0a 20 20 20 20 49 4e 54   'linux'.    INT
8b40: 45 52 53 45 43 54 0a 20 20 53 45 4c 45 43 54 20  ERSECT.  SELECT 
8b50: 64 6f 63 69 64 20 46 52 4f 4d 20 28 0a 20 20 20  docid FROM (.   
8b60: 20 53 45 4c 45 43 54 20 64 6f 63 69 64 20 46 52   SELECT docid FR
8b70: 4f 4d 20 64 6f 63 73 20 57 48 45 52 45 20 64 6f  OM docs WHERE do
8b80: 63 73 20 4d 41 54 43 48 20 27 22 73 71 6c 69 74  cs MATCH '"sqlit
8b90: 65 20 6c 69 62 72 61 72 79 22 27 0a 20 20 20 20  e library"'.    
8ba0: 20 20 55 4e 49 4f 4e 0a 20 20 20 20 53 45 4c 45    UNION.    SELE
8bb0: 43 54 20 64 6f 63 69 64 20 46 52 4f 4d 20 64 6f  CT docid FROM do
8bc0: 63 73 20 57 48 45 52 45 20 64 6f 63 73 20 4d 41  cs WHERE docs MA
8bd0: 54 43 48 20 27 22 73 71 6c 69 74 65 20 64 61 74  TCH '"sqlite dat
8be0: 61 62 61 73 65 22 27 0a 20 20 29 3b 0a 3c 2f 63  abase"'.  );.</c
8bf0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 0a 3c 68 32 3e  odeblock>...<h2>
8c00: 53 65 74 20 4f 70 65 72 61 74 69 6f 6e 73 20 55  Set Operations U
8c10: 73 69 6e 67 20 54 68 65 20 53 74 61 6e 64 61 72  sing The Standar
8c20: 64 20 51 75 65 72 79 20 53 79 6e 74 61 78 3c 2f  d Query Syntax</
8c30: 68 32 3e 0a 0a 3c 70 3e 0a 20 20 46 54 53 20 71  h2>..<p>.  FTS q
8c40: 75 65 72 79 20 73 65 74 20 6f 70 65 72 61 74 69  uery set operati
8c50: 6f 6e 73 20 75 73 69 6e 67 20 74 68 65 20 73 74  ons using the st
8c60: 61 6e 64 61 72 64 20 71 75 65 72 79 20 73 79 6e  andard query syn
8c70: 74 61 78 20 61 72 65 20 73 69 6d 69 6c 61 72 2c  tax are similar,
8c80: 20 62 75 74 0a 20 20 6e 6f 74 20 69 64 65 6e 74   but.  not ident
8c90: 69 63 61 6c 2c 20 74 6f 20 73 65 74 20 6f 70 65  ical, to set ope
8ca0: 72 61 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  rations with the
8cb0: 20 65 6e 68 61 6e 63 65 64 20 71 75 65 72 79 20   enhanced query 
8cc0: 73 79 6e 74 61 78 2e 20 54 68 65 72 65 0a 20 20  syntax. There.  
8cd0: 61 72 65 20 66 6f 75 72 20 64 69 66 66 65 72 65  are four differe
8ce0: 6e 63 65 73 2c 20 61 73 20 66 6f 6c 6c 6f 77 73  nces, as follows
8cf0: 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 20 76 61  :..<ol>.  <li va
8d00: 6c 75 65 3d 31 3e 3c 70 3e 20 4f 6e 6c 79 20 74  lue=1><p> Only t
8d10: 68 65 20 69 6d 70 6c 69 63 69 74 20 76 65 72 73  he implicit vers
8d20: 69 6f 6e 20 6f 66 20 74 68 65 20 41 4e 44 20 6f  ion of the AND o
8d30: 70 65 72 61 74 6f 72 20 69 73 20 73 75 70 70 6f  perator is suppo
8d40: 72 74 65 64 2e 0a 20 20 20 20 53 70 65 63 69 66  rted..    Specif
8d50: 79 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ying the string 
8d60: 22 41 4e 44 22 20 61 73 20 70 61 72 74 20 6f 66  "AND" as part of
8d70: 20 61 20 73 74 61 6e 64 61 72 64 20 71 75 65 72   a standard quer
8d80: 79 20 73 79 6e 74 61 78 20 71 75 65 72 79 20 69  y syntax query i
8d90: 73 0a 20 20 20 20 69 6e 74 65 72 70 72 65 74 65  s.    interprete
8da0: 64 20 61 73 20 61 20 74 65 72 6d 20 71 75 65 72  d as a term quer
8db0: 79 20 66 6f 72 20 74 68 65 20 73 65 74 20 6f 66  y for the set of
8dc0: 20 64 6f 63 75 6d 65 6e 74 73 20 63 6f 6e 74 61   documents conta
8dd0: 69 6e 69 6e 67 20 74 68 65 20 74 65 72 6d 20 0a  ining the term .
8de0: 20 20 20 20 22 61 6e 64 22 2e 0a 3c 2f 6f 6c 3e      "and"..</ol>
8df0: 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 20 76 61 6c  ..<ol>.  <li val
8e00: 75 65 3d 32 3e 3c 70 3e 20 50 61 72 65 6e 74 68  ue=2><p> Parenth
8e10: 65 73 69 73 20 61 72 65 20 6e 6f 74 20 73 75 70  esis are not sup
8e20: 70 6f 72 74 65 64 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c  ported..</ol>..<
8e30: 6f 6c 3e 0a 20 20 3c 6c 69 20 76 61 6c 75 65 3d  ol>.  <li value=
8e40: 33 3e 3c 70 3e 20 54 68 65 20 4e 4f 54 20 6f 70  3><p> The NOT op
8e50: 65 72 61 74 6f 72 20 69 73 20 6e 6f 74 20 73 75  erator is not su
8e60: 70 70 6f 72 74 65 64 2e 20 49 6e 73 74 65 61 64  pported. Instead
8e70: 20 6f 66 20 74 68 65 20 4e 4f 54 20 0a 20 20 20   of the NOT .   
8e80: 20 6f 70 65 72 61 74 6f 72 2c 20 74 68 65 20 73   operator, the s
8e90: 74 61 6e 64 61 72 64 20 71 75 65 72 79 20 73 79  tandard query sy
8ea0: 6e 74 61 78 20 73 75 70 70 6f 72 74 73 20 61 20  ntax supports a 
8eb0: 75 6e 61 72 79 20 22 2d 22 20 6f 70 65 72 61 74  unary "-" operat
8ec0: 6f 72 20 74 68 61 74 0a 20 20 20 20 6d 61 79 20  or that.    may 
8ed0: 62 65 20 61 70 70 6c 69 65 64 20 74 6f 20 62 61  be applied to ba
8ee0: 73 69 63 20 74 65 72 6d 20 61 6e 64 20 74 65 72  sic term and ter
8ef0: 6d 2d 70 72 65 66 69 78 20 71 75 65 72 69 65 73  m-prefix queries
8f00: 20 28 62 75 74 20 6e 6f 74 20 74 6f 20 70 68 72   (but not to phr
8f10: 61 73 65 0a 20 20 20 20 6f 72 20 4e 45 41 52 20  ase.    or NEAR 
8f20: 71 75 65 72 69 65 73 29 2e 20 41 20 74 65 72 6d  queries). A term
8f30: 20 6f 72 20 74 65 72 6d 2d 70 72 65 66 69 78 20   or term-prefix 
8f40: 74 68 61 74 20 68 61 73 20 61 20 75 6e 61 72 79  that has a unary
8f50: 20 22 2d 22 20 6f 70 65 72 61 74 6f 72 0a 20 20   "-" operator.  
8f60: 20 20 61 74 74 61 63 68 65 64 20 74 6f 20 69 74    attached to it
8f70: 20 6d 61 79 20 6e 6f 74 20 61 70 70 65 61 72 20   may not appear 
8f80: 61 73 20 61 6e 20 6f 70 65 72 61 6e 64 20 74 6f  as an operand to
8f90: 20 61 6e 20 4f 52 20 6f 70 65 72 61 74 6f 72 2e   an OR operator.
8fa0: 20 41 6e 20 46 54 53 0a 20 20 20 20 71 75 65 72   An FTS.    quer
8fb0: 79 20 6d 61 79 20 6e 6f 74 20 63 6f 6e 73 69 73  y may not consis
8fc0: 74 20 65 6e 74 69 72 65 6c 79 20 6f 66 20 74 65  t entirely of te
8fd0: 72 6d 73 20 6f 72 20 74 65 72 6d 2d 70 72 65 66  rms or term-pref
8fe0: 69 78 20 71 75 65 72 69 65 73 20 77 69 74 68 20  ix queries with 
8ff0: 75 6e 61 72 79 0a 20 20 20 20 22 2d 22 20 6f 70  unary.    "-" op
9000: 65 72 61 74 6f 72 73 20 61 74 74 61 63 68 65 64  erators attached
9010: 20 74 6f 20 74 68 65 6d 2e 0a 3c 2f 6f 6c 3e 0a   to them..</ol>.
9020: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c  .<codeblock>.  <
9030: 69 3e 2d 2d 20 53 65 61 72 63 68 20 66 6f 72 20  i>-- Search for 
9040: 74 68 65 20 73 65 74 20 6f 66 20 64 6f 63 75 6d  the set of docum
9050: 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ents that contai
9060: 6e 20 74 68 65 20 74 65 72 6d 20 22 73 71 6c 69  n the term "sqli
9070: 74 65 22 20 62 75 74 20 64 6f 3c 2f 69 3e 0a 20  te" but do</i>. 
9080: 20 3c 69 3e 2d 2d 20 6e 6f 74 20 63 6f 6e 74 61   <i>-- not conta
9090: 69 6e 20 74 68 65 20 74 65 72 6d 20 22 64 61 74  in the term "dat
90a0: 61 62 61 73 65 22 2e 3c 2f 69 3e 0a 20 20 53 45  abase".</i>.  SE
90b0: 4c 45 43 54 20 2a 20 46 52 4f 4d 20 64 6f 63 73  LECT * FROM docs
90c0: 20 57 48 45 52 45 20 64 6f 63 73 20 4d 41 54 43   WHERE docs MATC
90d0: 48 20 27 73 71 6c 69 74 65 20 2d 64 61 74 61 62  H 'sqlite -datab
90e0: 61 73 65 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ase';.</codebloc
90f0: 6b 3e 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 20 76  k>..<ol>.  <li v
9100: 61 6c 75 65 3d 34 3e 3c 70 3e 20 54 68 65 20 72  alue=4><p> The r
9110: 65 6c 61 74 69 76 65 20 70 72 65 63 65 64 65 6e  elative preceden
9120: 63 65 20 6f 66 20 74 68 65 20 73 65 74 20 6f 70  ce of the set op
9130: 65 72 61 74 69 6f 6e 73 20 69 73 20 64 69 66 66  erations is diff
9140: 65 72 65 6e 74 2e 20 0a 20 20 20 49 6e 20 70 61  erent. .   In pa
9150: 72 74 69 63 75 6c 61 72 2c 20 75 73 69 6e 67 20  rticular, using 
9160: 74 68 65 20 73 74 61 6e 64 61 72 64 20 71 75 65  the standard que
9170: 72 79 20 73 79 6e 74 61 78 20 74 68 65 20 22 4f  ry syntax the "O
9180: 52 22 20 6f 70 65 72 61 74 6f 72 20 68 61 73 20  R" operator has 
9190: 61 0a 20 20 20 68 69 67 68 65 72 20 70 72 65 63  a.   higher prec
91a0: 65 64 65 6e 63 65 20 74 68 61 6e 20 22 41 4e 44  edence than "AND
91b0: 22 2e 20 54 68 65 20 70 72 65 63 65 64 65 6e 63  ". The precedenc
91c0: 65 20 6f 66 20 6f 70 65 72 61 74 6f 72 73 20 77  e of operators w
91d0: 68 65 6e 20 75 73 69 6e 67 20 74 68 65 0a 20 20  hen using the.  
91e0: 20 73 74 61 6e 64 61 72 64 20 71 75 65 72 79 20   standard query 
91f0: 73 79 6e 74 61 78 20 69 73 3a 20 0a 3c 2f 6f 6c  syntax is: .</ol
9200: 3e 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65  >..<table stripe
9210: 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 4f  d=1>.  <tr><th>O
9220: 70 65 72 61 74 6f 72 3c 74 68 3e 53 74 61 6e 64  perator<th>Stand
9230: 61 72 64 20 51 75 65 72 79 20 53 79 6e 74 61 78  ard Query Syntax
9240: 20 50 72 65 63 65 64 65 6e 63 65 0a 20 20 3c 74   Precedence.  <t
9250: 72 3e 3c 74 64 3e 55 6e 61 72 79 20 22 2d 22 20  r><td>Unary "-" 
9260: 3c 74 64 3e 20 48 69 67 68 65 73 74 20 70 72 65  <td> Highest pre
9270: 63 65 64 65 6e 63 65 20 28 74 69 67 68 74 65 73  cedence (tightes
9280: 74 20 67 72 6f 75 70 69 6e 67 29 2e 0a 20 20 3c  t grouping)..  <
9290: 74 72 3e 3c 74 64 3e 4f 52 20 20 3c 74 64 3e 0a  tr><td>OR  <td>.
92a0: 20 20 3c 74 72 3e 3c 74 64 3e 41 4e 44 20 3c 74    <tr><td>AND <t
92b0: 64 3e 20 4c 6f 77 65 73 74 20 70 72 65 63 65 64  d> Lowest preced
92c0: 65 6e 63 65 20 28 6c 6f 6f 73 65 73 74 20 67 72  ence (loosest gr
92d0: 6f 75 70 69 6e 67 29 2e 0a 3c 2f 74 61 62 6c 65  ouping)..</table
92e0: 3e 0a 0a 3c 6f 6c 3e 3c 6c 69 20 73 74 79 6c 65  >..<ol><li style
92f0: 3d 22 6c 69 73 74 2d 73 74 79 6c 65 3a 6e 6f 6e  ="list-style:non
9300: 65 22 3e 0a 20 20 54 68 65 20 66 6f 6c 6c 6f 77  e">.  The follow
9310: 69 6e 67 20 65 78 61 6d 70 6c 65 20 69 6c 6c 75  ing example illu
9320: 73 74 72 61 74 65 73 20 70 72 65 63 65 64 65 6e  strates preceden
9330: 63 65 20 6f 66 20 6f 70 65 72 61 74 6f 72 73 20  ce of operators 
9340: 75 73 69 6e 67 20 74 68 65 20 73 74 61 6e 64 61  using the standa
9350: 72 64 20 0a 20 20 71 75 65 72 79 20 73 79 6e 74  rd .  query synt
9360: 61 78 3a 0a 3c 2f 6f 6c 3e 0a 0a 3c 63 6f 64 65  ax:.</ol>..<code
9370: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 53  block>.  <i>-- S
9380: 65 61 72 63 68 20 66 6f 72 20 64 6f 63 75 6d 65  earch for docume
9390: 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  nts that contain
93a0: 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 6f 66   at least one of
93b0: 20 74 68 65 20 74 65 72 6d 73 20 22 64 61 74 61   the terms "data
93c0: 62 61 73 65 22 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  base"</i>.  <i>-
93d0: 2d 20 61 6e 64 20 22 73 71 6c 69 74 65 22 2c 20  - and "sqlite", 
93e0: 61 6e 64 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e  and also contain
93f0: 20 74 68 65 20 74 65 72 6d 20 22 6c 69 62 72 61   the term "libra
9400: 72 79 22 2e 20 42 65 63 61 75 73 65 20 6f 66 20  ry". Because of 
9410: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 73 3c  the differences<
9420: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e 20 6f  /i>.  <i>-- in o
9430: 70 65 72 61 74 6f 72 20 70 72 65 63 65 64 65 6e  perator preceden
9440: 63 65 73 2c 20 74 68 69 73 20 71 75 65 72 79 20  ces, this query 
9450: 77 6f 75 6c 64 20 68 61 76 65 20 61 20 64 69 66  would have a dif
9460: 66 65 72 65 6e 74 20 69 6e 74 65 72 70 72 65 74  ferent interpret
9470: 61 74 69 6f 6e 20 75 73 69 6e 67 3c 2f 69 3e 0a  ation using</i>.
9480: 20 20 3c 69 3e 2d 2d 20 74 68 65 20 65 6e 68 61    <i>-- the enha
9490: 6e 63 65 64 20 71 75 65 72 79 20 73 79 6e 74 61  nced query synta
94a0: 78 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  x.</i>.  SELECT 
94b0: 2a 20 46 52 4f 4d 20 64 6f 63 73 20 57 48 45 52  * FROM docs WHER
94c0: 45 20 64 6f 63 73 20 4d 41 54 43 48 20 27 73 71  E docs MATCH 'sq
94d0: 6c 69 74 65 20 4f 52 20 64 61 74 61 62 61 73 65  lite OR database
94e0: 20 6c 69 62 72 61 72 79 27 3b 0a 3c 2f 63 6f 64   library';.</cod
94f0: 65 62 6c 6f 63 6b 3e 0a 0a 3c 74 63 6c 3e 68 64  eblock>..<tcl>hd
9500: 5f 66 72 61 67 6d 65 6e 74 20 73 6e 69 70 70 65  _fragment snippe
9510: 74 20 7b 46 54 53 20 61 75 78 69 6c 69 61 72 79  t {FTS auxiliary
9520: 20 66 75 6e 63 74 69 6f 6e 73 7d 3c 2f 74 63 6c   functions}</tcl
9530: 3e 0a 3c 68 31 3e 41 75 78 69 6c 69 61 72 79 20  >.<h1>Auxiliary 
9540: 46 75 6e 63 74 69 6f 6e 73 20 2d 20 53 6e 69 70  Functions - Snip
9550: 70 65 74 2c 20 4f 66 66 73 65 74 73 20 61 6e 64  pet, Offsets and
9560: 20 4d 61 74 63 68 69 6e 66 6f 3c 2f 68 31 3e 0a   Matchinfo</h1>.
9570: 0a 3c 70 3e 0a 20 20 54 68 65 20 46 54 53 33 20  .<p>.  The FTS3 
9580: 61 6e 64 20 46 54 53 34 20 6d 6f 64 75 6c 65 73  and FTS4 modules
9590: 20 70 72 6f 76 69 64 65 20 74 68 72 65 65 20 73   provide three s
95a0: 70 65 63 69 61 6c 20 53 51 4c 20 73 63 61 6c 61  pecial SQL scala
95b0: 72 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  r functions that
95c0: 20 6d 61 79 20 62 65 20 75 73 65 66 75 6c 0a 20   may be useful. 
95d0: 20 74 6f 20 74 68 65 20 64 65 76 65 6c 6f 70 65   to the develope
95e0: 72 73 20 6f 66 20 66 75 6c 6c 2d 74 65 78 74 20  rs of full-text 
95f0: 71 75 65 72 79 20 73 79 73 74 65 6d 73 3a 20 22  query systems: "
9600: 73 6e 69 70 70 65 74 22 2c 20 22 6f 66 66 73 65  snippet", "offse
9610: 74 73 22 20 61 6e 64 0a 20 20 22 6d 61 74 63 68  ts" and.  "match
9620: 69 6e 66 6f 22 2e 20 54 68 65 20 70 75 72 70 6f  info". The purpo
9630: 73 65 20 6f 66 20 74 68 65 20 22 73 6e 69 70 70  se of the "snipp
9640: 65 74 22 20 61 6e 64 20 22 6f 66 66 73 65 74 73  et" and "offsets
9650: 22 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 74  " functions is t
9660: 6f 20 61 6c 6c 6f 77 0a 20 20 74 68 65 20 75 73  o allow.  the us
9670: 65 72 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  er to identify t
9680: 68 65 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 71  he location of q
9690: 75 65 72 69 65 64 20 74 65 72 6d 73 20 69 6e 20  ueried terms in 
96a0: 74 68 65 20 72 65 74 75 72 6e 65 64 20 64 6f 63  the returned doc
96b0: 75 6d 65 6e 74 73 2e 0a 20 20 54 68 65 20 22 6d  uments..  The "m
96c0: 61 74 63 68 69 6e 66 6f 22 20 66 75 6e 63 74 69  atchinfo" functi
96d0: 6f 6e 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  on provides the 
96e0: 75 73 65 72 20 77 69 74 68 20 6d 65 74 72 69 63  user with metric
96f0: 73 20 74 68 61 74 20 6d 61 79 20 62 65 20 75 73  s that may be us
9700: 65 66 75 6c 0a 20 20 66 6f 72 20 66 69 6c 74 65  eful.  for filte
9710: 72 69 6e 67 20 6f 72 20 73 6f 72 74 69 6e 67 20  ring or sorting 
9720: 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 63  query results ac
9730: 63 6f 72 64 69 6e 67 20 74 6f 20 72 65 6c 65 76  cording to relev
9740: 61 6e 63 65 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65  ance...<p>.  The
9750: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
9760: 74 6f 20 61 6c 6c 20 74 68 72 65 65 20 73 70 65  to all three spe
9770: 63 69 61 6c 20 53 51 4c 20 73 63 61 6c 61 72 20  cial SQL scalar 
9780: 66 75 6e 63 74 69 6f 6e 73 0a 20 20 6d 75 73 74  functions.  must
9790: 20 62 65 20 74 68 65 20 5b 46 54 53 20 68 69 64   be the [FTS hid
97a0: 64 65 6e 20 63 6f 6c 75 6d 6e 5d 20 6f 66 20 74  den column] of t
97b0: 68 65 20 46 54 53 20 74 61 62 6c 65 20 74 68 61  he FTS table tha
97c0: 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  t the function i
97d0: 73 0a 20 20 61 70 70 6c 69 65 64 20 74 6f 2e 20  s.  applied to. 
97e0: 20 54 68 65 20 5b 46 54 53 20 68 69 64 64 65 6e   The [FTS hidden
97f0: 20 63 6f 6c 75 6d 6e 5d 20 69 73 20 61 6e 20 61   column] is an a
9800: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2d 67 65 6e  utomatically-gen
9810: 65 72 61 74 65 64 20 63 6f 6c 75 6d 6e 20 66 6f  erated column fo
9820: 75 6e 64 20 6f 6e 0a 20 20 61 6c 6c 20 46 54 53  und on.  all FTS
9830: 20 74 61 62 6c 65 73 20 74 68 61 74 20 68 61 73   tables that has
9840: 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
9850: 73 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 20  s the FTS table 
9860: 69 74 73 65 6c 66 2e 0a 20 20 46 6f 72 20 65 78  itself..  For ex
9870: 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 61 6e 20  ample, given an 
9880: 46 54 53 20 74 61 62 6c 65 20 6e 61 6d 65 64 20  FTS table named 
9890: 22 6d 61 69 6c 22 3a 0a 0a 3c 63 6f 64 65 62 6c  "mail":..<codebl
98a0: 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20 6f 66  ock>.  SELECT of
98b0: 66 73 65 74 73 28 6d 61 69 6c 29 20 46 52 4f 4d  fsets(mail) FROM
98c0: 20 6d 61 69 6c 20 57 48 45 52 45 20 6d 61 69 6c   mail WHERE mail
98d0: 20 4d 41 54 43 48 20 26 6c 74 3b 66 75 6c 6c 2d   MATCH &lt;full-
98e0: 74 65 78 74 20 71 75 65 72 79 20 65 78 70 72 65  text query expre
98f0: 73 73 69 6f 6e 26 67 74 3b 3b 0a 20 20 53 45 4c  ssion&gt;;.  SEL
9900: 45 43 54 20 73 6e 69 70 70 65 74 28 6d 61 69 6c  ECT snippet(mail
9910: 29 20 46 52 4f 4d 20 6d 61 69 6c 20 57 48 45 52  ) FROM mail WHER
9920: 45 20 6d 61 69 6c 20 4d 41 54 43 48 20 26 6c 74  E mail MATCH &lt
9930: 3b 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79  ;full-text query
9940: 20 65 78 70 72 65 73 73 69 6f 6e 26 67 74 3b 3b   expression&gt;;
9950: 0a 20 20 53 45 4c 45 43 54 20 6d 61 74 63 68 69  .  SELECT matchi
9960: 6e 66 6f 28 6d 61 69 6c 29 20 46 52 4f 4d 20 6d  nfo(mail) FROM m
9970: 61 69 6c 20 57 48 45 52 45 20 6d 61 69 6c 20 4d  ail WHERE mail M
9980: 41 54 43 48 20 26 6c 74 3b 66 75 6c 6c 2d 74 65  ATCH &lt;full-te
9990: 78 74 20 71 75 65 72 79 20 65 78 70 72 65 73 73  xt query express
99a0: 69 6f 6e 26 67 74 3b 3b 0a 3c 2f 63 6f 64 65 62  ion&gt;;.</codeb
99b0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65  lock>..<p>.  The
99c0: 20 74 68 72 65 65 20 61 75 78 69 6c 69 61 72 79   three auxiliary
99d0: 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 6f   functions are o
99e0: 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68 69  nly useful withi
99f0: 6e 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  n a SELECT state
9a00: 6d 65 6e 74 20 74 68 61 74 0a 20 20 75 73 65 73  ment that.  uses
9a10: 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 27 73   the FTS table's
9a20: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
9a30: 2e 20 5e 49 66 20 75 73 65 64 20 77 69 74 68 69  . ^If used withi
9a40: 6e 20 61 20 53 45 4c 45 43 54 20 74 68 61 74 20  n a SELECT that 
9a50: 75 73 65 73 0a 20 20 74 68 65 20 22 71 75 65 72  uses.  the "quer
9a60: 79 20 62 79 20 72 6f 77 69 64 22 20 6f 72 20 22  y by rowid" or "
9a70: 6c 69 6e 65 61 72 20 73 63 61 6e 22 20 73 74 72  linear scan" str
9a80: 61 74 65 67 69 65 73 2c 20 74 68 65 6e 20 74 68  ategies, then th
9a90: 65 20 73 6e 69 70 70 65 74 20 61 6e 64 0a 20 20  e snippet and.  
9aa0: 6f 66 66 73 65 74 73 20 62 6f 74 68 20 72 65 74  offsets both ret
9ab0: 75 72 6e 20 61 6e 20 65 6d 70 74 79 20 73 74 72  urn an empty str
9ac0: 69 6e 67 2c 20 61 6e 64 20 74 68 65 20 6d 61 74  ing, and the mat
9ad0: 63 68 69 6e 66 6f 20 66 75 6e 63 74 69 6f 6e 20  chinfo function 
9ae0: 72 65 74 75 72 6e 73 0a 20 20 61 20 62 6c 6f 62  returns.  a blob
9af0: 20 76 61 6c 75 65 20 7a 65 72 6f 20 62 79 74 65   value zero byte
9b00: 73 20 69 6e 20 73 69 7a 65 2e 0a 0a 3c 70 20 69  s in size...<p i
9b10: 64 3d 6d 61 74 63 68 61 62 6c 65 3e 0a 20 20 41  d=matchable>.  A
9b20: 6c 6c 20 74 68 72 65 65 20 61 75 78 69 6c 69 61  ll three auxilia
9b30: 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 65 78 74  ry functions ext
9b40: 72 61 63 74 20 61 20 73 65 74 20 6f 66 20 22 6d  ract a set of "m
9b50: 61 74 63 68 61 62 6c 65 20 70 68 72 61 73 65 73  atchable phrases
9b60: 22 20 66 72 6f 6d 0a 20 20 74 68 65 20 46 54 53  " from.  the FTS
9b70: 20 71 75 65 72 79 20 65 78 70 72 65 73 73 69 6f   query expressio
9b80: 6e 20 74 6f 20 77 6f 72 6b 20 77 69 74 68 2e 20  n to work with. 
9b90: 54 68 65 20 73 65 74 20 6f 66 20 6d 61 74 63 68  The set of match
9ba0: 61 62 6c 65 20 70 68 72 61 73 65 73 20 66 6f 72  able phrases for
9bb0: 0a 20 20 61 20 67 69 76 65 6e 20 71 75 65 72 79  .  a given query
9bc0: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 6c 6c   consists of all
9bd0: 20 70 68 72 61 73 65 73 20 28 69 6e 63 6c 75 64   phrases (includ
9be0: 69 6e 67 20 75 6e 71 75 6f 74 65 64 20 74 6f 6b  ing unquoted tok
9bf0: 65 6e 73 20 61 6e 64 0a 20 20 74 6f 6b 65 6e 20  ens and.  token 
9c00: 70 72 65 66 69 78 65 73 29 20 69 6e 20 74 68 65  prefixes) in the
9c10: 20 65 78 70 72 65 73 73 69 6f 6e 20 65 78 63 65   expression exce
9c20: 70 74 20 74 68 6f 73 65 20 74 68 61 74 20 61 72  pt those that ar
9c30: 65 20 70 72 65 66 69 78 65 64 20 77 69 74 68 0a  e prefixed with.
9c40: 20 20 61 20 75 6e 61 72 79 20 22 2d 22 20 6f 70    a unary "-" op
9c50: 65 72 61 74 6f 72 20 28 73 74 61 6e 64 61 72 64  erator (standard
9c60: 20 73 79 6e 74 61 78 29 20 6f 72 20 61 72 65 20   syntax) or are 
9c70: 70 61 72 74 20 6f 66 20 61 20 73 75 62 2d 65 78  part of a sub-ex
9c80: 70 72 65 73 73 69 6f 6e 20 0a 20 20 74 68 61 74  pression .  that
9c90: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
9ca0: 72 69 67 68 74 2d 68 61 6e 64 20 6f 70 65 72 61  right-hand opera
9cb0: 6e 64 20 6f 66 20 61 20 4e 4f 54 20 6f 70 65 72  nd of a NOT oper
9cc0: 61 74 6f 72 2e 0a 0a 3c 70 3e 0a 20 20 57 69 74  ator...<p>.  Wit
9cd0: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
9ce0: 70 72 6f 76 69 73 6f 73 2c 20 65 61 63 68 20 73  provisos, each s
9cf0: 65 72 69 65 73 20 6f 66 20 74 6f 6b 65 6e 73 20  eries of tokens 
9d00: 69 6e 20 74 68 65 20 46 54 53 20 74 61 62 6c 65  in the FTS table
9d10: 20 74 68 61 74 0a 20 20 6d 61 74 63 68 65 73 20   that.  matches 
9d20: 6f 6e 65 20 6f 66 20 74 68 65 20 6d 61 74 63 68  one of the match
9d30: 61 62 6c 65 20 70 68 72 61 73 65 73 20 69 6e 20  able phrases in 
9d40: 74 68 65 20 71 75 65 72 79 20 65 78 70 72 65 73  the query expres
9d50: 73 69 6f 6e 20 69 73 20 6b 6e 6f 77 6e 20 61 73  sion is known as
9d60: 20 61 0a 20 20 22 70 68 72 61 73 65 20 6d 61 74   a.  "phrase mat
9d70: 63 68 22 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69  ch":..<ol>.  <li
9d80: 3e 20 49 66 20 61 20 6d 61 74 63 68 61 62 6c 65  > If a matchable
9d90: 20 70 68 72 61 73 65 20 69 73 20 70 61 72 74 20   phrase is part 
9da0: 6f 66 20 61 20 73 65 72 69 65 73 20 6f 66 20 70  of a series of p
9db0: 68 72 61 73 65 73 20 63 6f 6e 6e 65 63 74 65 64  hrases connected
9dc0: 20 62 79 0a 20 20 20 20 20 20 20 4e 45 41 52 20   by.       NEAR 
9dd0: 6f 70 65 72 61 74 6f 72 73 20 69 6e 20 74 68 65  operators in the
9de0: 20 46 54 53 20 71 75 65 72 79 20 65 78 70 72 65   FTS query expre
9df0: 73 73 69 6f 6e 2c 20 74 68 65 6e 20 65 61 63 68  ssion, then each
9e00: 20 70 68 72 61 73 65 20 6d 61 74 63 68 0a 20 20   phrase match.  
9e10: 20 20 20 20 20 6d 75 73 74 20 62 65 20 73 75 66       must be suf
9e20: 66 69 63 69 65 6e 74 6c 79 20 63 6c 6f 73 65 20  ficiently close 
9e30: 74 6f 20 6f 74 68 65 72 20 70 68 72 61 73 65 20  to other phrase 
9e40: 6d 61 74 63 68 65 73 20 6f 66 20 74 68 65 20 72  matches of the r
9e50: 65 6c 65 76 61 6e 74 0a 20 20 20 20 20 20 20 74  elevant.       t
9e60: 79 70 65 73 20 74 6f 20 73 61 74 69 73 66 79 20  ypes to satisfy 
9e70: 74 68 65 20 4e 45 41 52 20 63 6f 6e 64 69 74 69  the NEAR conditi
9e80: 6f 6e 2e 0a 0a 20 20 3c 6c 69 3e 20 49 66 20 74  on...  <li> If t
9e90: 68 65 20 6d 61 74 63 68 61 62 6c 65 20 70 68 72  he matchable phr
9ea0: 61 73 65 20 69 6e 20 74 68 65 20 46 54 53 20 71  ase in the FTS q
9eb0: 75 65 72 79 20 69 73 20 72 65 73 74 72 69 63 74  uery is restrict
9ec0: 65 64 20 74 6f 20 6d 61 74 63 68 69 6e 67 0a 20  ed to matching. 
9ed0: 20 20 20 20 20 20 64 61 74 61 20 69 6e 20 61 20        data in a 
9ee0: 73 70 65 63 69 66 69 65 64 20 46 54 53 20 74 61  specified FTS ta
9ef0: 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  ble column, then
9f00: 20 6f 6e 6c 79 20 70 68 72 61 73 65 20 6d 61 74   only phrase mat
9f10: 63 68 65 73 20 74 68 61 74 20 0a 20 20 20 20 20  ches that .     
9f20: 20 20 6f 63 63 75 72 20 77 69 74 68 69 6e 20 74    occur within t
9f30: 68 61 74 20 63 6f 6c 75 6d 6e 20 61 72 65 20 63  hat column are c
9f40: 6f 6e 73 69 64 65 72 65 64 2e 0a 3c 2f 6f 6c 3e  onsidered..</ol>
9f50: 0a 20 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  . .<tcl>hd_fragm
9f60: 65 6e 74 20 6f 66 66 73 65 74 73 20 6f 66 66 73  ent offsets offs
9f70: 65 74 73 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 54 68  ets</tcl>.<h2>Th
9f80: 65 20 4f 66 66 73 65 74 73 20 46 75 6e 63 74 69  e Offsets Functi
9f90: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 46  on</h2>..<p>.  F
9fa0: 6f 72 20 61 20 53 45 4c 45 43 54 20 71 75 65 72  or a SELECT quer
9fb0: 79 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20  y that uses the 
9fc0: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2c  full-text index,
9fd0: 20 74 68 65 20 6f 66 66 73 65 74 73 28 29 20 66   the offsets() f
9fe0: 75 6e 63 74 69 6f 6e 20 0a 20 20 72 65 74 75 72  unction .  retur
9ff0: 6e 73 20 61 20 74 65 78 74 20 76 61 6c 75 65 20  ns a text value 
a000: 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 73 65 72  containing a ser
a010: 69 65 73 20 6f 66 20 73 70 61 63 65 2d 73 65 70  ies of space-sep
a020: 61 72 61 74 65 64 20 69 6e 74 65 67 65 72 73 2e  arated integers.
a030: 20 46 6f 72 0a 20 20 65 61 63 68 20 74 65 72 6d   For.  each term
a040: 20 69 6e 20 65 61 63 68 20 3c 61 20 68 72 65 66   in each <a href
a050: 3d 23 6d 61 74 63 68 61 62 6c 65 3e 70 68 72 61  =#matchable>phra
a060: 73 65 20 6d 61 74 63 68 3c 2f 61 3e 20 6f 66 20  se match</a> of 
a070: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 2c  the current row,
a080: 20 0a 20 20 74 68 65 72 65 20 61 72 65 20 66 6f   .  there are fo
a090: 75 72 20 69 6e 74 65 67 65 72 73 20 69 6e 20 74  ur integers in t
a0a0: 68 65 20 72 65 74 75 72 6e 65 64 20 6c 69 73 74  he returned list
a0b0: 2e 20 45 61 63 68 20 73 65 74 20 6f 66 20 66 6f  . Each set of fo
a0c0: 75 72 20 69 6e 74 65 67 65 72 73 20 69 73 20 0a  ur integers is .
a0d0: 20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73    interpreted as
a0e0: 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 74 61 62 6c   follows:..<tabl
a0f0: 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20 3c  e striped=1>.  <
a100: 74 72 3e 3c 74 68 3e 49 6e 74 65 67 65 72 20 3c  tr><th>Integer <
a110: 74 68 3e 49 6e 74 65 72 70 72 65 74 61 74 69 6f  th>Interpretatio
a120: 6e 0a 20 20 3c 74 72 3e 3c 74 64 3e 30 20 0a 20  n.  <tr><td>0 . 
a130: 20 20 20 20 20 3c 74 64 3e 54 68 65 20 63 6f 6c       <td>The col
a140: 75 6d 6e 20 6e 75 6d 62 65 72 20 74 68 61 74 20  umn number that 
a150: 74 68 65 20 74 65 72 6d 20 69 6e 73 74 61 6e 63  the term instanc
a160: 65 20 6f 63 63 75 72 73 20 69 6e 20 28 30 20 66  e occurs in (0 f
a170: 6f 72 20 74 68 65 0a 20 20 20 20 20 20 20 20 20  or the.         
a180: 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
a190: 20 6f 66 20 74 68 65 20 46 54 53 20 74 61 62 6c   of the FTS tabl
a1a0: 65 2c 20 31 20 66 6f 72 20 74 68 65 20 6e 65 78  e, 1 for the nex
a1b0: 74 20 6c 65 66 74 6d 6f 73 74 2c 20 65 74 63 2e  t leftmost, etc.
a1c0: 29 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 31 0a 20  )..  <tr><td>1. 
a1d0: 20 20 20 20 20 3c 74 64 3e 54 68 65 20 74 65 72       <td>The ter
a1e0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 65 20  m number of the 
a1f0: 6d 61 74 63 68 69 6e 67 20 74 65 72 6d 20 77 69  matching term wi
a200: 74 68 69 6e 20 74 68 65 20 66 75 6c 6c 2d 74 65  thin the full-te
a210: 78 74 20 71 75 65 72 79 0a 20 20 20 20 20 20 20  xt query.       
a220: 20 20 20 65 78 70 72 65 73 73 69 6f 6e 2e 20 54     expression. T
a230: 65 72 6d 73 20 77 69 74 68 69 6e 20 61 20 71 75  erms within a qu
a240: 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e 20 61  ery expression a
a250: 72 65 20 6e 75 6d 62 65 72 65 64 20 73 74 61 72  re numbered star
a260: 74 69 6e 67 0a 20 20 20 20 20 20 20 20 20 20 66  ting.          f
a270: 72 6f 6d 20 30 20 69 6e 20 74 68 65 20 6f 72 64  rom 0 in the ord
a280: 65 72 20 74 68 61 74 20 74 68 65 79 20 6f 63 63  er that they occ
a290: 75 72 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 32 0a  ur..  <tr><td>2.
a2a0: 20 20 20 20 20 20 3c 74 64 3e 54 68 65 20 62 79        <td>The by
a2b0: 74 65 20 6f 66 66 73 65 74 20 6f 66 20 74 68 65  te offset of the
a2c0: 20 6d 61 74 63 68 69 6e 67 20 74 65 72 6d 20 77   matching term w
a2d0: 69 74 68 69 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  ithin the column
a2e0: 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 33 0a 20 20  ..  <tr><td>3.  
a2f0: 20 20 20 20 3c 74 64 3e 54 68 65 20 73 69 7a 65      <td>The size
a300: 20 6f 66 20 74 68 65 20 6d 61 74 63 68 69 6e 67   of the matching
a310: 20 74 65 72 6d 20 69 6e 20 62 79 74 65 73 2e 0a   term in bytes..
a320: 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 0a 20 20  </table>..<p>.  
a330: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c  The following bl
a340: 6f 63 6b 20 63 6f 6e 74 61 69 6e 73 20 65 78 61  ock contains exa
a350: 6d 70 6c 65 73 20 74 68 61 74 20 75 73 65 20 74  mples that use t
a360: 68 65 20 6f 66 66 73 65 74 73 20 66 75 6e 63 74  he offsets funct
a370: 69 6f 6e 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ion...<codeblock
a380: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
a390: 41 4c 20 54 41 42 4c 45 20 6d 61 69 6c 20 55 53  AL TABLE mail US
a3a0: 49 4e 47 20 66 74 73 33 28 73 75 62 6a 65 63 74  ING fts3(subject
a3b0: 2c 20 62 6f 64 79 29 3b 0a 20 20 49 4e 53 45 52  , body);.  INSER
a3c0: 54 20 49 4e 54 4f 20 6d 61 69 6c 20 56 41 4c 55  T INTO mail VALU
a3d0: 45 53 28 27 68 65 6c 6c 6f 20 77 6f 72 6c 64 27  ES('hello world'
a3e0: 2c 20 27 54 68 69 73 20 6d 65 73 73 61 67 65 20  , 'This message 
a3f0: 69 73 20 61 20 68 65 6c 6c 6f 20 77 6f 72 6c 64  is a hello world
a400: 20 6d 65 73 73 61 67 65 2e 27 29 3b 0a 20 20 49   message.');.  I
a410: 4e 53 45 52 54 20 49 4e 54 4f 20 6d 61 69 6c 20  NSERT INTO mail 
a420: 56 41 4c 55 45 53 28 27 75 72 67 65 6e 74 3a 20  VALUES('urgent: 
a430: 73 65 72 69 6f 75 73 27 2c 20 27 54 68 69 73 20  serious', 'This 
a440: 6d 61 69 6c 20 69 73 20 73 65 65 6e 20 61 73 20  mail is seen as 
a450: 61 20 6d 6f 72 65 20 73 65 72 69 6f 75 73 20 6d  a more serious m
a460: 61 69 6c 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  ail');..  <i>-- 
a470: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  The following qu
a480: 65 72 79 20 72 65 74 75 72 6e 73 20 61 20 73 69  ery returns a si
a490: 6e 67 6c 65 20 72 6f 77 20 28 61 73 20 69 74 20  ngle row (as it 
a4a0: 6d 61 74 63 68 65 73 20 6f 6e 6c 79 20 74 68 65  matches only the
a4b0: 20 66 69 72 73 74 3c 2f 69 3e 0a 20 20 3c 69 3e   first</i>.  <i>
a4c0: 2d 2d 20 65 6e 74 72 79 20 69 6e 20 74 61 62 6c  -- entry in tabl
a4d0: 65 20 22 6d 61 69 6c 22 2e 20 54 68 65 20 74 65  e "mail". The te
a4e0: 78 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  xt returned by t
a4f0: 68 65 20 6f 66 66 73 65 74 73 20 66 75 6e 63 74  he offsets funct
a500: 69 6f 6e 20 69 73 3c 2f 69 3e 0a 20 20 3c 69 3e  ion is</i>.  <i>
a510: 2d 2d 20 22 30 20 30 20 36 20 35 20 31 20 30 20  -- "0 0 6 5 1 0 
a520: 32 34 20 35 22 2e 3c 2f 69 3e 0a 20 20 3c 69 3e  24 5".</i>.  <i>
a530: 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 54  --</i>.  <i>-- T
a540: 68 65 20 66 69 72 73 74 20 73 65 74 20 6f 66 20  he first set of 
a550: 66 6f 75 72 20 69 6e 74 65 67 65 72 73 20 69 6e  four integers in
a560: 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 64 69   the result indi
a570: 63 61 74 65 20 74 68 61 74 20 63 6f 6c 75 6d 6e  cate that column
a580: 20 30 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63   0</i>.  <i>-- c
a590: 6f 6e 74 61 69 6e 73 20 61 6e 20 69 6e 73 74 61  ontains an insta
a5a0: 6e 63 65 20 6f 66 20 74 65 72 6d 20 30 20 28 22  nce of term 0 ("
a5b0: 77 6f 72 6c 64 22 29 20 61 74 20 62 79 74 65 20  world") at byte 
a5c0: 6f 66 66 73 65 74 20 36 2e 20 54 68 65 20 74 65  offset 6. The te
a5d0: 72 6d 20 69 6e 73 74 61 6e 63 65 3c 2f 69 3e 0a  rm instance</i>.
a5e0: 20 20 3c 69 3e 2d 2d 20 69 73 20 35 20 62 79 74    <i>-- is 5 byt
a5f0: 65 73 20 69 6e 20 73 69 7a 65 2e 20 54 68 65 20  es in size. The 
a600: 73 65 63 6f 6e 64 20 73 65 74 20 6f 66 20 66 6f  second set of fo
a610: 75 72 20 69 6e 74 65 67 65 72 73 20 73 68 6f 77  ur integers show
a620: 73 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 31 3c  s that column 1<
a630: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 66 20 74  /i>.  <i>-- of t
a640: 68 65 20 6d 61 74 63 68 65 64 20 72 6f 77 20 63  he matched row c
a650: 6f 6e 74 61 69 6e 73 20 61 6e 20 69 6e 73 74 61  ontains an insta
a660: 6e 63 65 20 6f 66 20 74 65 72 6d 20 30 20 28 22  nce of term 0 ("
a670: 77 6f 72 6c 64 22 29 20 61 74 20 62 79 74 65 20  world") at byte 
a680: 6f 66 66 73 65 74 3c 2f 69 3e 0a 20 20 3c 69 3e  offset</i>.  <i>
a690: 2d 2d 20 32 34 2e 20 41 67 61 69 6e 2c 20 74 68  -- 24. Again, th
a6a0: 65 20 74 65 72 6d 20 69 6e 73 74 61 6e 63 65 20  e term instance 
a6b0: 69 73 20 35 20 62 79 74 65 73 20 69 6e 20 73 69  is 5 bytes in si
a6c0: 7a 65 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  ze.</i>.  SELECT
a6d0: 20 6f 66 66 73 65 74 73 28 6d 61 69 6c 29 20 46   offsets(mail) F
a6e0: 52 4f 4d 20 6d 61 69 6c 20 57 48 45 52 45 20 6d  ROM mail WHERE m
a6f0: 61 69 6c 20 4d 41 54 43 48 20 27 77 6f 72 6c 64  ail MATCH 'world
a700: 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20  ';..  <i>-- The 
a710: 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
a720: 72 65 74 75 72 6e 73 20 61 6c 73 6f 20 6d 61 74  returns also mat
a730: 63 68 65 73 20 6f 6e 6c 79 20 74 68 65 20 66 69  ches only the fi
a740: 72 73 74 20 72 6f 77 20 69 6e 20 74 61 62 6c 65  rst row in table
a750: 20 22 6d 61 69 6c 22 2e 3c 2f 69 3e 0a 20 20 3c   "mail".</i>.  <
a760: 69 3e 2d 2d 20 49 6e 20 74 68 69 73 20 63 61 73  i>-- In this cas
a770: 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 74  e the returned t
a780: 65 78 74 20 69 73 20 22 31 20 30 20 35 20 37 20  ext is "1 0 5 7 
a790: 31 20 30 20 33 30 20 37 22 2e 3c 2f 69 3e 0a 20  1 0 30 7".</i>. 
a7a0: 20 53 45 4c 45 43 54 20 6f 66 66 73 65 74 73 28   SELECT offsets(
a7b0: 6d 61 69 6c 29 20 46 52 4f 4d 20 6d 61 69 6c 20  mail) FROM mail 
a7c0: 57 48 45 52 45 20 6d 61 69 6c 20 4d 41 54 43 48  WHERE mail MATCH
a7d0: 20 27 6d 65 73 73 61 67 65 27 3b 0a 0a 20 20 3c   'message';..  <
a7e0: 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69  i>-- The followi
a7f0: 6e 67 20 71 75 65 72 79 20 6d 61 74 63 68 65 73  ng query matches
a800: 20 74 68 65 20 73 65 63 6f 6e 64 20 72 6f 77 20   the second row 
a810: 69 6e 20 74 61 62 6c 65 20 22 6d 61 69 6c 22 2e  in table "mail".
a820: 20 49 74 20 72 65 74 75 72 6e 73 20 74 68 65 3c   It returns the<
a830: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 65 78 74  /i>.  <i>-- text
a840: 20 22 31 20 30 20 32 38 20 37 20 31 20 31 20 33   "1 0 28 7 1 1 3
a850: 36 20 34 22 2e 20 4f 6e 6c 79 20 74 68 6f 73 65  6 4". Only those
a860: 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
a870: 74 65 72 6d 73 20 22 73 65 72 69 6f 75 73 22 20  terms "serious" 
a880: 61 6e 64 20 22 6d 61 69 6c 22 3c 2f 69 3e 0a 20  and "mail"</i>. 
a890: 20 3c 69 3e 2d 2d 20 74 68 61 74 20 61 72 65 20   <i>-- that are 
a8a0: 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 73 74 61  part of an insta
a8b0: 6e 63 65 20 6f 66 20 74 68 65 20 70 68 72 61 73  nce of the phras
a8c0: 65 20 22 73 65 72 69 6f 75 73 20 6d 61 69 6c 22  e "serious mail"
a8d0: 20 61 72 65 20 69 64 65 6e 74 69 66 69 65 64 3b   are identified;
a8e0: 20 74 68 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d   the</i>.  <i>--
a8f0: 20 6f 74 68 65 72 20 6f 63 63 75 72 72 65 6e 63   other occurrenc
a900: 65 73 20 6f 66 20 22 73 65 72 69 6f 75 73 22 20  es of "serious" 
a910: 61 6e 64 20 22 6d 61 69 6c 22 20 61 72 65 20 69  and "mail" are i
a920: 67 6e 6f 72 65 64 2e 3c 2f 69 3e 0a 20 20 53 45  gnored.</i>.  SE
a930: 4c 45 43 54 20 6f 66 66 73 65 74 73 28 6d 61 69  LECT offsets(mai
a940: 6c 29 20 46 52 4f 4d 20 6d 61 69 6c 20 57 48 45  l) FROM mail WHE
a950: 52 45 20 6d 61 69 6c 20 4d 41 54 43 48 20 27 22  RE mail MATCH '"
a960: 73 65 72 69 6f 75 73 20 6d 61 69 6c 22 27 3b 0a  serious mail"';.
a970: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 74  </codeblock>..<t
a980: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 73  cl>hd_fragment s
a990: 6e 69 70 70 65 74 20 73 6e 69 70 70 65 74 3c 2f  nippet snippet</
a9a0: 74 63 6c 3e 0a 3c 68 32 3e 54 68 65 20 53 6e 69  tcl>.<h2>The Sni
a9b0: 70 70 65 74 20 46 75 6e 63 74 69 6f 6e 3c 2f 68  ppet Function</h
a9c0: 32 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 73 6e  2>..<p>.  The sn
a9d0: 69 70 70 65 74 20 66 75 6e 63 74 69 6f 6e 20 69  ippet function i
a9e0: 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
a9f0: 20 66 6f 72 6d 61 74 74 65 64 20 66 72 61 67 6d   formatted fragm
aa00: 65 6e 74 73 20 6f 66 20 64 6f 63 75 6d 65 6e 74  ents of document
aa10: 20 74 65 78 74 0a 20 20 66 6f 72 20 64 69 73 70   text.  for disp
aa20: 6c 61 79 20 61 73 20 70 61 72 74 20 6f 66 20 61  lay as part of a
aa30: 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79   full-text query
aa40: 20 72 65 73 75 6c 74 73 20 72 65 70 6f 72 74 2e   results report.
aa50: 20 54 68 65 20 73 6e 69 70 70 65 74 20 66 75 6e   The snippet fun
aa60: 63 74 69 6f 6e 20 0a 20 20 6d 61 79 20 62 65 20  ction .  may be 
aa70: 70 61 73 73 65 64 20 62 65 74 77 65 65 6e 20 6f  passed between o
aa80: 6e 65 20 61 6e 64 20 73 69 78 20 61 72 67 75 6d  ne and six argum
aa90: 65 6e 74 73 2c 20 61 73 20 66 6f 6c 6c 6f 77 73  ents, as follows
aaa0: 3a 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65  :..<table stripe
aab0: 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 41  d=1>.  <tr><th>A
aac0: 72 67 75 6d 65 6e 74 20 3c 74 68 3e 44 65 66 61  rgument <th>Defa
aad0: 75 6c 74 20 56 61 6c 75 65 20 3c 74 68 3e 44 65  ult Value <th>De
aae0: 73 63 72 69 70 74 69 6f 6e 0a 20 20 3c 74 72 3e  scription.  <tr>
aaf0: 3c 74 64 3e 30 20 3c 74 64 3e 4e 2f 41 0a 20 20  <td>0 <td>N/A.  
ab00: 20 20 20 20 3c 74 64 3e 20 54 68 65 20 66 69 72      <td> The fir
ab10: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
ab20: 68 65 20 73 6e 69 70 70 65 74 20 66 75 6e 63 74  he snippet funct
ab30: 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
ab40: 62 65 20 74 68 65 20 5b 46 54 53 20 68 69 64 64  be the [FTS hidd
ab50: 65 6e 20 63 6f 6c 75 6d 6e 5d 0a 20 20 20 20 20  en column].     
ab60: 20 20 20 20 20 20 6f 66 20 74 68 65 20 46 54 53        of the FTS
ab70: 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
ab80: 72 69 65 64 20 61 6e 64 20 66 72 6f 6d 20 77 68  ried and from wh
ab90: 69 63 68 20 74 68 65 20 73 6e 69 70 70 65 74 20  ich the snippet 
aba0: 69 73 20 74 6f 20 62 65 20 74 61 6b 65 6e 2e 20  is to be taken. 
abb0: 20 54 68 65 0a 20 20 20 20 20 20 20 20 20 20 20   The.           
abc0: 5b 46 54 53 20 68 69 64 64 65 6e 20 63 6f 6c 75  [FTS hidden colu
abd0: 6d 6e 5d 20 69 73 20 61 6e 20 61 75 74 6f 6d 61  mn] is an automa
abe0: 74 69 63 61 6c 6c 79 20 67 65 6e 65 72 61 74 65  tically generate
abf0: 64 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20 74 68  d column with th
ac00: 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 74  e same name as t
ac10: 68 65 0a 20 20 20 20 20 20 20 20 20 20 20 46 54  he.           FT
ac20: 53 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 0a  S table itself..
ac30: 20 20 3c 74 72 3e 3c 74 64 3e 31 20 3c 74 64 3e    <tr><td>1 <td>
ac40: 22 26 6c 74 3b 62 26 67 74 3b 22 0a 20 20 20 20  "&lt;b&gt;".    
ac50: 20 20 3c 74 64 3e 20 54 68 65 20 22 73 74 61 72    <td> The "star
ac60: 74 20 6d 61 74 63 68 22 20 74 65 78 74 2e 0a 20  t match" text.. 
ac70: 20 3c 74 72 3e 3c 74 64 3e 32 20 3c 74 64 3e 22   <tr><td>2 <td>"
ac80: 26 6c 74 3b 2f 62 26 67 74 3b 22 0a 20 20 20 20  &lt;/b&gt;".    
ac90: 20 20 3c 74 64 3e 20 54 68 65 20 22 65 6e 64 20    <td> The "end 
aca0: 6d 61 74 63 68 22 20 74 65 78 74 2e 0a 20 20 3c  match" text..  <
acb0: 74 72 3e 3c 74 64 3e 33 20 3c 74 64 3e 22 26 6c  tr><td>3 <td>"&l
acc0: 74 3b 62 26 67 74 3b 2e 2e 2e 26 6c 74 3b 2f 62  t;b&gt;...&lt;/b
acd0: 26 67 74 3b 22 0a 20 20 20 20 20 20 3c 74 64 3e  &gt;".      <td>
ace0: 20 54 68 65 20 22 65 6c 6c 69 70 73 65 73 22 20   The "ellipses" 
acf0: 74 65 78 74 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e  text..  <tr><td>
ad00: 34 20 3c 74 64 3e 2d 31 0a 20 20 20 20 20 20 3c  4 <td>-1.      <
ad10: 74 64 3e 20 54 68 65 20 46 54 53 20 74 61 62 6c  td> The FTS tabl
ad20: 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  e column number 
ad30: 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 72  to extract the r
ad40: 65 74 75 72 6e 65 64 20 66 72 61 67 6d 65 6e 74  eturned fragment
ad50: 73 20 6f 66 0a 20 20 20 20 20 20 20 20 20 20 20  s of.           
ad60: 74 65 78 74 20 66 72 6f 6d 2e 20 43 6f 6c 75 6d  text from. Colum
ad70: 6e 73 20 61 72 65 20 6e 75 6d 62 65 72 65 64 20  ns are numbered 
ad80: 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67  from left to rig
ad90: 68 74 20 73 74 61 72 74 69 6e 67 20 77 69 74 68  ht starting with
ada0: 0a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  .           zero
adb0: 2e 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c  . A negative val
adc0: 75 65 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ue indicates tha
add0: 74 20 74 68 65 20 74 65 78 74 20 6d 61 79 20 62  t the text may b
ade0: 65 20 65 78 74 72 61 63 74 65 64 0a 20 20 20 20  e extracted.    
adf0: 20 20 20 20 20 20 20 66 72 6f 6d 20 61 6e 79 20         from any 
ae00: 63 6f 6c 75 6d 6e 2e 0a 20 20 3c 74 72 3e 3c 74  column..  <tr><t
ae10: 64 3e 35 20 3c 74 64 3e 2d 31 35 0a 20 20 20 20  d>5 <td>-15.    
ae20: 20 20 3c 74 64 3e 20 54 68 65 20 61 62 73 6f 6c    <td> The absol
ae30: 75 74 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69  ute value of thi
ae40: 73 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  s integer argume
ae50: 6e 74 20 69 73 20 75 73 65 64 20 61 73 20 74 68  nt is used as th
ae60: 65 20 0a 20 20 20 20 20 20 20 20 20 20 20 28 61  e .           (a
ae70: 70 70 72 6f 78 69 6d 61 74 65 29 20 6e 75 6d 62  pproximate) numb
ae80: 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 74 6f 20  er of tokens to 
ae90: 69 6e 63 6c 75 64 65 20 69 6e 20 74 68 65 20 72  include in the r
aea0: 65 74 75 72 6e 65 64 20 74 65 78 74 20 0a 20 20  eturned text .  
aeb0: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 2e 20           value. 
aec0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
aed0: 77 61 62 6c 65 20 61 62 73 6f 6c 75 74 65 20 76  wable absolute v
aee0: 61 6c 75 65 20 69 73 20 36 34 2e 20 54 68 65 20  alue is 64. The 
aef0: 76 61 6c 75 65 20 6f 66 0a 20 20 20 20 20 20 20  value of.       
af00: 20 20 20 20 74 68 69 73 20 61 72 67 75 6d 65 6e      this argumen
af10: 74 20 69 73 20 72 65 66 65 72 72 65 64 20 74 6f  t is referred to
af20: 20 61 73 20 3c 69 3e 4e 3c 2f 69 3e 20 69 6e 20   as <i>N</i> in 
af30: 74 68 65 20 64 69 73 63 75 73 73 69 6f 6e 20 62  the discussion b
af40: 65 6c 6f 77 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a  elow..</table>..
af50: 3c 70 3e 0a 20 20 54 68 65 20 73 6e 69 70 70 65  <p>.  The snippe
af60: 74 20 66 75 6e 63 74 69 6f 6e 20 66 69 72 73 74  t function first
af70: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 69 6e   attempts to fin
af80: 64 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20  d a fragment of 
af90: 74 65 78 74 20 63 6f 6e 73 69 73 74 69 6e 67 0a  text consisting.
afa0: 20 20 6f 66 20 3c 69 3e 7c 4e 7c 3c 2f 69 3e 20    of <i>|N|</i> 
afb0: 74 6f 6b 65 6e 73 20 77 69 74 68 69 6e 20 74 68  tokens within th
afc0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 74 68  e current row th
afd0: 61 74 20 63 6f 6e 74 61 69 6e 73 20 61 74 20 6c  at contains at l
afe0: 65 61 73 74 20 6f 6e 65 20 70 68 72 61 73 65 20  east one phrase 
aff0: 0a 20 20 6d 61 74 63 68 20 66 6f 72 20 65 61 63  .  match for eac
b000: 68 20 6d 61 74 63 68 61 62 6c 65 20 70 68 72 61  h matchable phra
b010: 73 65 20 6d 61 74 63 68 65 64 20 73 6f 6d 65 77  se matched somew
b020: 68 65 72 65 20 69 6e 20 74 68 65 20 63 75 72 72  here in the curr
b030: 65 6e 74 20 72 6f 77 2c 20 0a 20 20 77 68 65 72  ent row, .  wher
b040: 65 20 3c 69 3e 7c 4e 7c 3c 2f 69 3e 20 69 73 20  e <i>|N|</i> is 
b050: 74 68 65 20 61 62 73 6f 6c 75 74 65 20 76 61 6c  the absolute val
b060: 75 65 20 6f 66 20 74 68 65 20 73 69 78 74 68 20  ue of the sixth 
b070: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
b080: 74 6f 20 74 68 65 0a 20 20 73 6e 69 70 70 65 74  to the.  snippet
b090: 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 74 68   function. If th
b0a0: 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
b0b0: 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
b0c0: 20 63 6f 6e 74 61 69 6e 73 20 6c 65 73 73 20 74   contains less t
b0d0: 68 61 6e 0a 20 20 3c 69 3e 7c 4e 7c 3c 2f 69 3e  han.  <i>|N|</i>
b0e0: 20 74 6f 6b 65 6e 73 2c 20 74 68 65 6e 20 74 68   tokens, then th
b0f0: 65 20 65 6e 74 69 72 65 20 63 6f 6c 75 6d 6e 20  e entire column 
b100: 76 61 6c 75 65 20 69 73 20 63 6f 6e 73 69 64 65  value is conside
b110: 72 65 64 2e 20 54 65 78 74 20 66 72 61 67 6d 65  red. Text fragme
b120: 6e 74 73 20 0a 20 20 6d 61 79 20 6e 6f 74 20 73  nts .  may not s
b130: 70 61 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6c  pan multiple col
b140: 75 6d 6e 73 2e 0a 0a 3c 70 3e 0a 20 20 49 66 20  umns...<p>.  If 
b150: 73 75 63 68 20 61 20 74 65 78 74 20 66 72 61 67  such a text frag
b160: 6d 65 6e 74 20 63 61 6e 20 62 65 20 66 6f 75 6e  ment can be foun
b170: 64 2c 20 69 74 20 69 73 20 72 65 74 75 72 6e 65  d, it is returne
b180: 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  d with the follo
b190: 77 69 6e 67 0a 20 20 6d 6f 64 69 66 69 63 61 74  wing.  modificat
b1a0: 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  ions:..<ul>.  <l
b1b0: 69 3e 20 49 66 20 74 68 65 20 74 65 78 74 20 66  i> If the text f
b1c0: 72 61 67 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  ragment does not
b1d0: 20 62 65 67 69 6e 20 61 74 20 74 68 65 20 73 74   begin at the st
b1e0: 61 72 74 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20  art of a column 
b1f0: 76 61 6c 75 65 2c 0a 20 20 20 20 20 20 20 74 68  value,.       th
b200: 65 20 22 65 6c 6c 69 70 73 65 73 22 20 74 65 78  e "ellipses" tex
b210: 74 20 69 73 20 70 72 65 70 65 6e 64 65 64 20 74  t is prepended t
b220: 6f 20 69 74 2e 0a 20 20 3c 6c 69 3e 20 49 66 20  o it..  <li> If 
b230: 74 68 65 20 74 65 78 74 20 66 72 61 67 6d 65 6e  the text fragmen
b240: 74 20 64 6f 65 73 20 6e 6f 74 20 66 69 6e 69 73  t does not finis
b250: 68 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20  h at the end of 
b260: 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 0a  a column value,.
b270: 20 20 20 20 20 20 20 74 68 65 20 22 65 6c 6c 69         the "elli
b280: 70 73 65 73 22 20 74 65 78 74 20 69 73 20 61 70  pses" text is ap
b290: 70 65 6e 64 65 64 20 74 6f 20 69 74 2e 0a 20 20  pended to it..  
b2a0: 3c 6c 69 3e 20 46 6f 72 20 65 61 63 68 20 74 6f  <li> For each to
b2b0: 6b 65 6e 20 69 6e 20 74 68 65 20 74 65 78 74 20  ken in the text 
b2c0: 66 72 61 67 6d 65 6e 74 20 74 68 61 74 20 69 73  fragment that is
b2d0: 20 70 61 72 74 20 6f 66 20 61 20 70 68 72 61 73   part of a phras
b2e0: 65 20 6d 61 74 63 68 2c 0a 20 20 20 20 20 20 20  e match,.       
b2f0: 74 68 65 20 22 73 74 61 72 74 20 6d 61 74 63 68  the "start match
b300: 22 20 74 65 78 74 20 69 73 20 69 6e 73 65 72 74  " text is insert
b310: 65 64 20 69 6e 74 6f 20 74 68 65 20 66 72 61 67  ed into the frag
b320: 6d 65 6e 74 20 62 65 66 6f 72 65 20 74 68 65 20  ment before the 
b330: 74 6f 6b 65 6e 2c 0a 20 20 20 20 20 20 20 61 6e  token,.       an
b340: 64 20 74 68 65 20 22 65 6e 64 20 6d 61 74 63 68  d the "end match
b350: 22 20 74 65 78 74 20 69 73 20 69 6e 73 65 72 74  " text is insert
b360: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
b370: 66 74 65 72 20 69 74 2e 0a 3c 2f 75 6c 3e 0a 0a  fter it..</ul>..
b380: 3c 70 3e 0a 20 20 49 66 20 6d 6f 72 65 20 74 68  <p>.  If more th
b390: 61 6e 20 6f 6e 65 20 73 75 63 68 20 66 72 61 67  an one such frag
b3a0: 6d 65 6e 74 20 63 61 6e 20 62 65 20 66 6f 75 6e  ment can be foun
b3b0: 64 2c 20 74 68 65 6e 20 66 72 61 67 6d 65 6e 74  d, then fragment
b3c0: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 20  s that contain. 
b3d0: 20 61 20 6c 61 72 67 65 72 20 6e 75 6d 62 65 72   a larger number
b3e0: 20 6f 66 20 22 65 78 74 72 61 22 20 70 68 72 61   of "extra" phra
b3f0: 73 65 20 6d 61 74 63 68 65 73 20 61 72 65 20 66  se matches are f
b400: 61 76 6f 72 65 64 2e 20 54 68 65 20 73 74 61 72  avored. The star
b410: 74 20 6f 66 0a 20 20 74 68 65 20 73 65 6c 65 63  t of.  the selec
b420: 74 65 64 20 74 65 78 74 20 66 72 61 67 6d 65 6e  ted text fragmen
b430: 74 20 6d 61 79 20 62 65 20 6d 6f 76 65 64 20 61  t may be moved a
b440: 20 66 65 77 20 74 6f 6b 65 6e 73 20 66 6f 72 77   few tokens forw
b450: 61 72 64 20 6f 72 20 62 61 63 6b 77 61 72 64 0a  ard or backward.
b460: 20 20 74 6f 20 61 74 74 65 6d 70 74 20 74 6f 20    to attempt to 
b470: 63 6f 6e 63 65 6e 74 72 61 74 65 20 74 68 65 20  concentrate the 
b480: 70 68 72 61 73 65 20 6d 61 74 63 68 65 73 20 74  phrase matches t
b490: 6f 77 61 72 64 20 74 68 65 20 63 65 6e 74 65 72  oward the center
b4a0: 20 6f 66 20 74 68 65 0a 20 20 66 72 61 67 6d 65   of the.  fragme
b4b0: 6e 74 2e 0a 0a 3c 70 3e 0a 20 20 41 73 73 75 6d  nt...<p>.  Assum
b4c0: 69 6e 67 20 3c 69 3e 4e 3c 2f 69 3e 20 69 73 20  ing <i>N</i> is 
b4d0: 61 20 70 6f 73 69 74 69 76 65 20 76 61 6c 75 65  a positive value
b4e0: 2c 20 69 66 20 6e 6f 20 66 72 61 67 6d 65 6e 74  , if no fragment
b4f0: 73 20 63 61 6e 20 62 65 20 66 6f 75 6e 64 20 74  s can be found t
b500: 68 61 74 0a 20 20 63 6f 6e 74 61 69 6e 20 61 20  hat.  contain a 
b510: 70 68 72 61 73 65 20 6d 61 74 63 68 20 63 6f 72  phrase match cor
b520: 72 65 73 70 6f 6e 64 69 6e 67 20 74 6f 20 65 61  responding to ea
b530: 63 68 20 6d 61 74 63 68 61 62 6c 65 20 70 68 72  ch matchable phr
b540: 61 73 65 2c 20 74 68 65 20 73 6e 69 70 70 65 74  ase, the snippet
b550: 0a 20 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  .  function atte
b560: 6d 70 74 73 20 74 6f 20 66 69 6e 64 20 74 77 6f  mpts to find two
b570: 20 66 72 61 67 6d 65 6e 74 73 20 6f 66 20 61 70   fragments of ap
b580: 70 72 6f 78 69 6d 61 74 65 6c 79 20 3c 69 3e 4e  proximately <i>N
b590: 3c 2f 69 3e 2f 32 20 74 6f 6b 65 6e 73 0a 20 20  </i>/2 tokens.  
b5a0: 74 68 61 74 20 62 65 74 77 65 65 6e 20 74 68 65  that between the
b5b0: 6d 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61  m contain at lea
b5c0: 73 74 20 6f 6e 65 20 70 68 72 61 73 65 20 6d 61  st one phrase ma
b5d0: 74 63 68 20 66 6f 72 20 65 61 63 68 20 6d 61 74  tch for each mat
b5e0: 63 68 61 62 6c 65 20 70 68 72 61 73 65 0a 20 20  chable phrase.  
b5f0: 6d 61 74 63 68 65 64 20 62 79 20 74 68 65 20 63  matched by the c
b600: 75 72 72 65 6e 74 20 72 6f 77 2e 20 49 66 20 74  urrent row. If t
b610: 68 69 73 20 66 61 69 6c 73 2c 20 61 74 74 65 6d  his fails, attem
b620: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20  pts are made to 
b630: 66 69 6e 64 20 74 68 72 65 65 0a 20 20 66 72 61  find three.  fra
b640: 67 6d 65 6e 74 73 20 6f 66 20 3c 69 3e 4e 3c 2f  gments of <i>N</
b650: 69 3e 2f 33 20 74 6f 6b 65 6e 73 20 65 61 63 68  i>/3 tokens each
b660: 20 61 6e 64 20 66 69 6e 61 6c 6c 79 20 66 6f 75   and finally fou
b670: 72 20 3c 69 3e 4e 3c 2f 69 3e 2f 34 20 74 6f 6b  r <i>N</i>/4 tok
b680: 65 6e 0a 20 20 66 72 61 67 6d 65 6e 74 73 2e 20  en.  fragments. 
b690: 49 66 20 61 20 73 65 74 20 6f 66 20 66 6f 75 72  If a set of four
b6a0: 20 66 72 61 67 6d 65 6e 74 73 20 63 61 6e 6e 6f   fragments canno
b6b0: 74 20 62 65 20 66 6f 75 6e 64 20 74 68 61 74 20  t be found that 
b6c0: 65 6e 63 6f 6d 70 61 73 73 65 73 20 74 68 65 0a  encompasses the.
b6d0: 20 20 72 65 71 75 69 72 65 64 20 70 68 72 61 73    required phras
b6e0: 65 20 6d 61 74 63 68 65 73 2c 20 74 68 65 20 66  e matches, the f
b6f0: 6f 75 72 20 66 72 61 67 6d 65 6e 74 73 20 6f 66  our fragments of
b700: 20 3c 69 3e 4e 3c 2f 69 3e 2f 34 20 74 6f 6b 65   <i>N</i>/4 toke
b710: 6e 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 0a  ns that provide.
b720: 20 20 74 68 65 20 62 65 73 74 20 63 6f 76 65 72    the best cover
b730: 61 67 65 20 61 72 65 20 73 65 6c 65 63 74 65 64  age are selected
b740: 2e 0a 0a 3c 70 3e 0a 20 20 49 66 20 3c 69 3e 4e  ...<p>.  If <i>N
b750: 3c 2f 69 3e 20 69 73 20 61 20 6e 65 67 61 74 69  </i> is a negati
b760: 76 65 20 76 61 6c 75 65 2c 20 61 6e 64 20 6e 6f  ve value, and no
b770: 20 73 69 6e 67 6c 65 20 66 72 61 67 6d 65 6e 74   single fragment
b780: 20 63 61 6e 20 62 65 20 66 6f 75 6e 64 20 0a 20   can be found . 
b790: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
b7a0: 72 65 71 75 69 72 65 64 20 70 68 72 61 73 65 20  required phrase 
b7b0: 6d 61 74 63 68 65 73 2c 20 74 68 65 20 73 6e 69  matches, the sni
b7c0: 70 70 65 74 20 66 75 6e 63 74 69 6f 6e 20 73 65  ppet function se
b7d0: 61 72 63 68 65 73 0a 20 20 66 6f 72 20 74 77 6f  arches.  for two
b7e0: 20 66 72 61 67 6d 65 6e 74 73 20 6f 66 20 3c 69   fragments of <i
b7f0: 3e 7c 4e 7c 3c 2f 69 3e 20 74 6f 6b 65 6e 73 20  >|N|</i> tokens 
b800: 65 61 63 68 2c 20 74 68 65 6e 20 74 68 72 65 65  each, then three
b810: 2c 20 74 68 65 6e 20 66 6f 75 72 2e 20 49 6e 0a  , then four. In.
b820: 20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69    other words, i
b830: 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
b840: 76 61 6c 75 65 20 6f 66 20 3c 69 3e 4e 3c 2f 69  value of <i>N</i
b850: 3e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  > is negative, t
b860: 68 65 20 73 69 7a 65 73 0a 20 20 6f 66 20 74 68  he sizes.  of th
b870: 65 20 66 72 61 67 6d 65 6e 74 73 20 69 73 20 6e  e fragments is n
b880: 6f 74 20 64 65 63 72 65 61 73 65 64 20 69 66 20  ot decreased if 
b890: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 66 72  more than one fr
b8a0: 61 67 6d 65 6e 74 20 69 73 20 72 65 71 75 69 72  agment is requir
b8b0: 65 64 0a 20 20 74 6f 20 70 72 6f 76 69 64 65 20  ed.  to provide 
b8c0: 74 68 65 20 64 65 73 69 72 65 64 20 70 68 72 61  the desired phra
b8d0: 73 65 20 6d 61 74 63 68 20 63 6f 76 65 72 61 67  se match coverag
b8e0: 65 2e 0a 0a 3c 70 3e 0a 20 20 41 66 74 65 72 20  e...<p>.  After 
b8f0: 74 68 65 20 3c 69 3e 4d 3c 2f 69 3e 20 66 72 61  the <i>M</i> fra
b900: 67 6d 65 6e 74 73 20 68 61 76 65 20 62 65 65 6e  gments have been
b910: 20 6c 6f 63 61 74 65 64 2c 20 77 68 65 72 65 20   located, where 
b920: 3c 69 3e 4d 3c 2f 69 3e 20 69 73 20 62 65 74 77  <i>M</i> is betw
b930: 65 65 6e 0a 20 20 74 77 6f 20 61 6e 64 20 66 6f  een.  two and fo
b940: 75 72 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ur as described 
b950: 69 6e 20 74 68 65 20 70 61 72 61 67 72 61 70 68  in the paragraph
b960: 73 20 61 62 6f 76 65 2c 20 74 68 65 79 20 61 72  s above, they ar
b970: 65 20 6a 6f 69 6e 65 64 20 74 6f 67 65 74 68 65  e joined togethe
b980: 72 0a 20 20 69 6e 20 73 6f 72 74 65 64 20 6f 72  r.  in sorted or
b990: 64 65 72 20 77 69 74 68 20 74 68 65 20 22 65 6c  der with the "el
b9a0: 6c 69 70 73 65 73 22 20 74 65 78 74 20 73 65 70  lipses" text sep
b9b0: 61 72 61 74 69 6e 67 20 74 68 65 6d 2e 20 54 68  arating them. Th
b9c0: 65 20 74 68 72 65 65 20 0a 20 20 6d 6f 64 69 66  e three .  modif
b9d0: 69 63 61 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  ications enumera
b9e0: 74 65 64 20 65 61 72 6c 69 65 72 20 61 72 65 20  ted earlier are 
b9f0: 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65  performed on the
ba00: 20 74 65 78 74 20 62 65 66 6f 72 65 20 69 74 20   text before it 
ba10: 69 73 20 0a 20 20 72 65 74 75 72 6e 65 64 2e 0a  is .  returned..
ba20: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c  .<codeblock>.  <
ba30: 62 3e 4e 6f 74 65 3a 20 49 6e 20 74 68 69 73 20  b>Note: In this 
ba40: 62 6c 6f 63 6b 20 6f 66 20 65 78 61 6d 70 6c 65  block of example
ba50: 73 2c 20 6e 65 77 6c 69 6e 65 73 20 61 6e 64 20  s, newlines and 
ba60: 77 68 69 74 65 73 70 61 63 65 20 63 68 61 72 61  whitespace chara
ba70: 63 74 65 72 73 20 68 61 76 65 0a 20 20 62 65 65  cters have.  bee
ba80: 6e 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  n inserted into 
ba90: 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 69 6e 73  the document ins
baa0: 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65 20 46  erted into the F
bab0: 54 53 20 74 61 62 6c 65 2c 20 61 6e 64 20 74 68  TS table, and th
bac0: 65 20 65 78 70 65 63 74 65 64 0a 20 20 72 65 73  e expected.  res
bad0: 75 6c 74 73 20 64 65 73 63 72 69 62 65 64 20 69  ults described i
bae0: 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2e 20  n SQL comments. 
baf0: 54 68 69 73 20 69 73 20 64 6f 6e 65 20 74 6f 20  This is done to 
bb00: 65 6e 68 61 6e 63 65 20 72 65 61 64 61 62 69 6c  enhance readabil
bb10: 69 74 79 20 6f 6e 6c 79 2c 0a 20 20 74 68 65 79  ity only,.  they
bb20: 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 20 70 72   would not be pr
bb30: 65 73 65 6e 74 20 69 6e 20 61 63 74 75 61 6c 20  esent in actual 
bb40: 53 51 4c 69 74 65 20 63 6f 6d 6d 61 6e 64 73 20  SQLite commands 
bb50: 6f 72 20 6f 75 74 70 75 74 2e 3c 2f 62 3e 0a 0a  or output.</b>..
bb60: 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61    <i>-- Create a
bb70: 6e 64 20 70 6f 70 75 6c 61 74 65 20 61 6e 20 46  nd populate an F
bb80: 54 53 20 74 61 62 6c 65 2e 3c 2f 69 3e 0a 20 20  TS table.</i>.  
bb90: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
bba0: 41 42 4c 45 20 74 65 78 74 20 55 53 49 4e 47 20  ABLE text USING 
bbb0: 66 74 73 34 28 29 3b 0a 20 20 49 4e 53 45 52 54  fts4();.  INSERT
bbc0: 20 49 4e 54 4f 20 74 65 78 74 20 56 41 4c 55 45   INTO text VALUE
bbd0: 53 28 27 0a 20 20 20 20 44 75 72 69 6e 67 20 33  S('.    During 3
bbe0: 30 20 4e 6f 76 2d 31 20 44 65 63 2c 20 32 2d 33  0 Nov-1 Dec, 2-3
bbf0: 6f 43 20 64 72 6f 70 73 2e 20 43 6f 6f 6c 20 69  oC drops. Cool i
bc00: 6e 20 74 68 65 20 75 70 70 65 72 20 70 6f 72 74  n the upper port
bc10: 69 6f 6e 2c 20 6d 69 6e 69 6d 75 6d 20 74 65 6d  ion, minimum tem
bc20: 70 65 72 61 74 75 72 65 20 31 34 2d 31 36 6f 43  perature 14-16oC
bc30: 20 0a 20 20 20 20 61 6e 64 20 63 6f 6f 6c 20 65   .    and cool e
bc40: 6c 73 65 77 68 65 72 65 2c 20 6d 69 6e 69 6d 75  lsewhere, minimu
bc50: 6d 20 74 65 6d 70 65 72 61 74 75 72 65 20 31 37  m temperature 17
bc60: 2d 32 30 6f 43 2e 20 43 6f 6c 64 20 74 6f 20 76  -20oC. Cold to v
bc70: 65 72 79 20 63 6f 6c 64 20 6f 6e 20 6d 6f 75 6e  ery cold on moun
bc80: 74 61 69 6e 74 6f 70 73 2c 20 0a 20 20 20 20 6d  taintops, .    m
bc90: 69 6e 69 6d 75 6d 20 74 65 6d 70 65 72 61 74 75  inimum temperatu
bca0: 72 65 20 36 2d 31 32 6f 43 2e 20 4e 6f 72 74 68  re 6-12oC. North
bcb0: 65 61 73 74 65 72 6c 79 20 77 69 6e 64 73 20 31  easterly winds 1
bcc0: 35 2d 33 30 20 6b 6d 2f 68 72 2e 20 41 66 74 65  5-30 km/hr. Afte
bcd0: 72 20 74 68 61 74 2c 20 74 65 6d 70 65 72 61 74  r that, temperat
bce0: 75 72 65 20 0a 20 20 20 20 69 6e 63 72 65 61 73  ure .    increas
bcf0: 65 73 2e 20 4e 6f 72 74 68 65 61 73 74 65 72 6c  es. Northeasterl
bd00: 79 20 77 69 6e 64 73 20 31 35 2d 33 30 20 6b 6d  y winds 15-30 km
bd10: 2f 68 72 2e 20 20 20 20 20 0a 20 20 27 29 3b 0a  /hr.     .  ');.
bd20: 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c  .  <i>-- The fol
bd30: 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 72 65 74  lowing query ret
bd40: 75 72 6e 73 20 74 68 65 20 74 65 78 74 20 76 61  urns the text va
bd50: 6c 75 65 3a 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  lue:</i>.  <i>--
bd60: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 22  </i>.  <i>--   "
bd70: 26 6c 74 3b 62 26 67 74 3b 2e 2e 2e 26 6c 74 3b  &lt;b&gt;...&lt;
bd80: 2f 62 26 67 74 3b 63 6f 6f 6c 20 65 6c 73 65 77  /b&gt;cool elsew
bd90: 68 65 72 65 2c 20 6d 69 6e 69 6d 75 6d 20 74 65  here, minimum te
bda0: 6d 70 65 72 61 74 75 72 65 20 31 37 2d 32 30 6f  mperature 17-20o
bdb0: 43 2e 20 26 6c 74 3b 62 26 67 74 3b 43 6f 6c 64  C. &lt;b&gt;Cold
bdc0: 26 6c 74 3b 2f 62 26 67 74 3b 20 74 6f 20 76 65  &lt;/b&gt; to ve
bdd0: 72 79 20 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  ry </i>.  <i>-- 
bde0: 20 20 20 26 6c 74 3b 62 26 67 74 3b 63 6f 6c 64     &lt;b&gt;cold
bdf0: 26 6c 74 3b 2f 62 26 67 74 3b 20 6f 6e 20 6d 6f  &lt;/b&gt; on mo
be00: 75 6e 74 61 69 6e 74 6f 70 73 2c 20 6d 69 6e 69  untaintops, mini
be10: 6d 75 6d 20 74 65 6d 70 65 72 61 74 75 72 65 20  mum temperature 
be20: 36 26 6c 74 3b 62 26 67 74 3b 2e 2e 2e 26 6c 74  6&lt;b&gt;...&lt
be30: 3b 2f 62 26 67 74 3b 22 2e 3c 2f 69 3e 0a 20 20  ;/b&gt;".</i>.  
be40: 3c 69 3e 2d 2d 3c 2f 69 3e 0a 20 20 53 45 4c 45  <i>--</i>.  SELE
be50: 43 54 20 73 6e 69 70 70 65 74 28 74 65 78 74 29  CT snippet(text)
be60: 20 46 52 4f 4d 20 74 65 78 74 20 57 48 45 52 45   FROM text WHERE
be70: 20 74 65 78 74 20 4d 41 54 43 48 20 27 63 6f 6c   text MATCH 'col
be80: 64 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65  d';..  <i>-- The
be90: 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
bea0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 65 78   returns the tex
beb0: 74 20 76 61 6c 75 65 3a 3c 2f 69 3e 0a 20 20 3c  t value:</i>.  <
bec0: 69 3e 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  i>--</i>.  <i>--
bed0: 20 20 20 22 2e 2e 2e 74 68 65 20 75 70 70 65 72     "...the upper
bee0: 20 70 6f 72 74 69 6f 6e 2c 20 26 23 39 31 3b 6d   portion, &#91;m
bef0: 69 6e 69 6d 75 6d 26 23 39 33 3b 20 26 23 39 31  inimum&#93; &#91
bf00: 3b 74 65 6d 70 65 72 61 74 75 72 65 26 23 39 33  ;temperature&#93
bf10: 3b 20 31 34 2d 31 36 6f 43 20 61 6e 64 20 63 6f  ; 14-16oC and co
bf20: 6f 6c 20 65 6c 73 65 77 68 65 72 65 2c 3c 2f 69  ol elsewhere,</i
bf30: 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 20 26 23 39  >.  <i>--    &#9
bf40: 31 3b 6d 69 6e 69 6d 75 6d 26 23 39 33 3b 20 26  1;minimum&#93; &
bf50: 23 39 31 3b 74 65 6d 70 65 72 61 74 75 72 65 26  #91;temperature&
bf60: 23 39 33 3b 20 31 37 2d 32 30 6f 43 2e 20 43 6f  #93; 17-20oC. Co
bf70: 6c 64 2e 2e 2e 22 3c 2f 69 3e 0a 20 20 3c 69 3e  ld..."</i>.  <i>
bf80: 2d 2d 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  --</i>.  SELECT 
bf90: 73 6e 69 70 70 65 74 28 74 65 78 74 2c 20 27 26  snippet(text, '&
bfa0: 23 39 31 3b 20 27 26 23 39 33 3b 27 2c 20 27 2e  #91; '&#93;', '.
bfb0: 2e 2e 27 29 20 46 52 4f 4d 20 74 65 78 74 20 57  ..') FROM text W
bfc0: 48 45 52 45 20 74 65 78 74 20 4d 41 54 43 48 20  HERE text MATCH 
bfd0: 27 22 6d 69 6e 2a 20 74 65 6d 2a 22 27 0a 3c 2f  '"min* tem*"'.</
bfe0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20  codeblock>..<h2 
bff0: 69 64 3d 6d 61 74 63 68 69 6e 66 6f 20 74 61 67  id=matchinfo tag
c000: 73 3d 6d 61 74 63 68 69 6e 66 6f 3e 54 68 65 20  s=matchinfo>The 
c010: 4d 61 74 63 68 69 6e 66 6f 20 46 75 6e 63 74 69  Matchinfo Functi
c020: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 54  on</h2>..<p>.  T
c030: 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 66 75 6e  he matchinfo fun
c040: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
c050: 62 6c 6f 62 20 76 61 6c 75 65 2e 20 49 66 20 69  blob value. If i
c060: 74 20 69 73 20 75 73 65 64 20 77 69 74 68 69 6e  t is used within
c070: 20 61 20 71 75 65 72 79 0a 20 20 74 68 61 74 20   a query.  that 
c080: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 74 68 65  does not use the
c090: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
c0a0: 20 28 61 20 22 71 75 65 72 79 20 62 79 20 72 6f   (a "query by ro
c0b0: 77 69 64 22 20 6f 72 20 22 6c 69 6e 65 61 72 20  wid" or "linear 
c0c0: 73 63 61 6e 22 29 2c 0a 20 20 74 68 65 6e 20 74  scan"),.  then t
c0d0: 68 65 20 62 6c 6f 62 20 69 73 20 7a 65 72 6f 20  he blob is zero 
c0e0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e 20 4f  bytes in size. O
c0f0: 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 62 6c  therwise, the bl
c100: 6f 62 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 7a  ob consists of z
c110: 65 72 6f 0a 20 20 6f 72 20 6d 6f 72 65 20 33 32  ero.  or more 32
c120: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
c130: 74 65 67 65 72 73 20 69 6e 20 6d 61 63 68 69 6e  tegers in machin
c140: 65 20 62 79 74 65 2d 6f 72 64 65 72 2e 20 54 68  e byte-order. Th
c150: 65 20 65 78 61 63 74 20 6e 75 6d 62 65 72 0a 20  e exact number. 
c160: 20 6f 66 20 69 6e 74 65 67 65 72 73 20 69 6e 20   of integers in 
c170: 74 68 65 20 72 65 74 75 72 6e 65 64 20 61 72 72  the returned arr
c180: 61 79 20 64 65 70 65 6e 64 73 20 6f 6e 20 62 6f  ay depends on bo
c190: 74 68 20 74 68 65 20 71 75 65 72 79 20 61 6e 64  th the query and
c1a0: 20 74 68 65 20 76 61 6c 75 65 0a 20 20 6f 66 20   the value.  of 
c1b0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
c1c0: 65 6e 74 20 28 69 66 20 61 6e 79 29 20 70 61 73  ent (if any) pas
c1d0: 73 65 64 20 74 6f 20 74 68 65 20 6d 61 74 63 68  sed to the match
c1e0: 69 6e 66 6f 20 66 75 6e 63 74 69 6f 6e 2e 0a 0a  info function...
c1f0: 3c 70 3e 0a 20 20 54 68 65 20 6d 61 74 63 68 69  <p>.  The matchi
c200: 6e 66 6f 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  nfo function is 
c210: 63 61 6c 6c 65 64 20 77 69 74 68 20 65 69 74 68  called with eith
c220: 65 72 20 6f 6e 65 20 6f 72 20 74 77 6f 20 61 72  er one or two ar
c230: 67 75 6d 65 6e 74 73 2e 20 41 73 20 66 6f 72 0a  guments. As for.
c240: 20 20 61 6c 6c 20 61 75 78 69 6c 69 61 72 79 20    all auxiliary 
c250: 66 75 6e 63 74 69 6f 6e 73 2c 20 74 68 65 20 66  functions, the f
c260: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
c270: 73 74 20 62 65 20 74 68 65 20 73 70 65 63 69 61  st be the specia
c280: 6c 20 0a 20 20 5b 46 54 53 20 68 69 64 64 65 6e  l .  [FTS hidden
c290: 20 63 6f 6c 75 6d 6e 5d 2e 20 54 68 65 20 73 65   column]. The se
c2a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 69  cond argument, i
c2b0: 66 20 69 74 20 69 73 20 73 70 65 63 69 66 69 65  f it is specifie
c2c0: 64 2c 20 6d 75 73 74 20 62 65 20 61 20 74 65 78  d, must be a tex
c2d0: 74 20 76 61 6c 75 65 0a 20 20 63 6f 6d 70 72 69  t value.  compri
c2e0: 73 65 64 20 6f 6e 6c 79 20 6f 66 20 74 68 65 20  sed only of the 
c2f0: 63 68 61 72 61 63 74 65 72 73 20 27 70 27 2c 20  characters 'p', 
c300: 27 63 27 2c 20 27 6e 27 2c 20 27 61 27 2c 20 27  'c', 'n', 'a', '
c310: 6c 27 2c 20 27 73 27 20 61 6e 64 20 27 78 27 2e  l', 's' and 'x'.
c320: 0a 20 20 49 66 20 6e 6f 20 73 65 63 6f 6e 64 20  .  If no second 
c330: 61 72 67 75 6d 65 6e 74 20 69 73 20 65 78 70 6c  argument is expl
c340: 69 63 69 74 6c 79 20 73 75 70 70 6c 69 65 64 2c  icitly supplied,
c350: 20 69 74 20 64 65 66 61 75 6c 74 73 20 74 6f 20   it defaults to 
c360: 22 70 63 78 22 2e 20 54 68 65 0a 20 20 73 65 63  "pcx". The.  sec
c370: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
c380: 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 74  referred to as t
c390: 68 65 20 22 66 6f 72 6d 61 74 20 73 74 72 69 6e  he "format strin
c3a0: 67 22 20 62 65 6c 6f 77 2e 0a 0a 3c 70 3e 0a 20  g" below...<p>. 
c3b0: 20 43 68 61 72 61 63 74 65 72 73 20 69 6e 20 74   Characters in t
c3c0: 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 66 6f 72  he matchinfo for
c3d0: 6d 61 74 20 73 74 72 69 6e 67 20 61 72 65 20 70  mat string are p
c3e0: 72 6f 63 65 73 73 65 64 20 66 72 6f 6d 20 6c 65  rocessed from le
c3f0: 66 74 20 74 6f 20 72 69 67 68 74 2e 20 0a 20 20  ft to right. .  
c400: 45 61 63 68 20 63 68 61 72 61 63 74 65 72 20 69  Each character i
c410: 6e 20 74 68 65 20 66 6f 72 6d 61 74 20 73 74 72  n the format str
c420: 69 6e 67 20 63 61 75 73 65 73 20 6f 6e 65 20 6f  ing causes one o
c430: 72 20 6d 6f 72 65 20 33 32 2d 62 69 74 20 75 6e  r more 32-bit un
c440: 73 69 67 6e 65 64 0a 20 20 69 6e 74 65 67 65 72  signed.  integer
c450: 20 76 61 6c 75 65 73 20 74 6f 20 62 65 20 61 64   values to be ad
c460: 64 65 64 20 74 6f 20 74 68 65 20 72 65 74 75 72  ded to the retur
c470: 6e 65 64 20 61 72 72 61 79 2e 20 54 68 65 20 22  ned array. The "
c480: 76 61 6c 75 65 73 22 20 63 6f 6c 75 6d 6e 20 69  values" column i
c490: 6e 0a 20 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  n.  the followin
c4a0: 67 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73  g table contains
c4b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 69   the number of i
c4c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 70  nteger values ap
c4d0: 70 65 6e 64 65 64 20 74 6f 20 74 68 65 0a 20 20  pended to the.  
c4e0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 66 6f  output buffer fo
c4f0: 72 20 65 61 63 68 20 73 75 70 70 6f 72 74 65 64  r each supported
c500: 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 63   format string c
c510: 68 61 72 61 63 74 65 72 2e 20 49 6e 20 74 68 65  haracter. In the
c520: 20 66 6f 72 6d 75 6c 61 0a 20 20 67 69 76 65 6e   formula.  given
c530: 2c 20 3c 69 3e 63 6f 6c 73 3c 2f 69 3e 20 69 73  , <i>cols</i> is
c540: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
c550: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 46 54  olumns in the FT
c560: 53 20 74 61 62 6c 65 2c 20 61 6e 64 20 0a 20 20  S table, and .  
c570: 3c 69 3e 70 68 72 61 73 65 73 3c 2f 69 3e 20 69  <i>phrases</i> i
c580: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
c590: 3c 61 20 68 72 65 66 3d 23 6d 61 74 63 68 61 62  <a href=#matchab
c5a0: 6c 65 3e 6d 61 74 63 68 61 62 6c 65 20 70 68 72  le>matchable phr
c5b0: 61 73 65 73 3c 2f 61 3e 20 69 6e 20 0a 20 20 74  ases</a> in .  t
c5c0: 68 65 20 71 75 65 72 79 2e 20 0a 0a 3c 74 61 62  he query. ..<tab
c5d0: 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20  le striped=1>.  
c5e0: 3c 74 72 3e 3c 74 68 3e 43 68 61 72 61 63 74 65  <tr><th>Characte
c5f0: 72 3c 74 68 3e 56 61 6c 75 65 73 3c 74 68 3e 44  r<th>Values<th>D
c600: 65 73 63 72 69 70 74 69 6f 6e 0a 20 20 3c 74 72  escription.  <tr
c610: 3e 3c 74 64 3e 70 20 3c 74 64 3e 31 20 3c 74 64  ><td>p <td>1 <td
c620: 3e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  >The number of m
c630: 61 74 63 68 61 62 6c 65 20 70 68 72 61 73 65 73  atchable phrases
c640: 20 69 6e 20 74 68 65 20 71 75 65 72 79 2e 0a 20   in the query.. 
c650: 20 3c 74 72 3e 3c 74 64 3e 63 20 3c 74 64 3e 31   <tr><td>c <td>1
c660: 20 3c 74 64 3e 54 68 65 20 6e 75 6d 62 65 72 20   <td>The number 
c670: 6f 66 20 75 73 65 72 20 64 65 66 69 6e 65 64 20  of user defined 
c680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 46  columns in the F
c690: 54 53 0a 20 20 20 20 74 61 62 6c 65 20 28 69 2e  TS.    table (i.
c6a0: 65 2e 20 6e 6f 74 20 69 6e 63 6c 75 64 69 6e 67  e. not including
c6b0: 20 74 68 65 20 64 6f 63 69 64 20 6f 72 20 74 68   the docid or th
c6c0: 65 20 5b 46 54 53 20 68 69 64 64 65 6e 20 63 6f  e [FTS hidden co
c6d0: 6c 75 6d 6e 5d 29 2e 0a 20 20 3c 74 72 3e 3c 74  lumn])..  <tr><t
c6e0: 64 3e 78 20 3c 74 64 20 73 74 79 6c 65 3d 22 77  d>x <td style="w
c6f0: 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
c700: 70 22 3e 33 20 2a 20 3c 69 3e 63 6f 6c 73 3c 2f  p">3 * <i>cols</
c710: 69 3e 20 2a 20 3c 69 3e 70 68 72 61 73 65 73 3c  i> * <i>phrases<
c720: 2f 69 3e 20 0a 20 20 20 20 3c 74 64 3e 0a 20 20  /i> .    <td>.  
c730: 20 20 20 20 46 6f 72 20 65 61 63 68 20 64 69 73      For each dis
c740: 74 69 6e 63 74 20 63 6f 6d 62 69 6e 61 74 69 6f  tinct combinatio
c750: 6e 20 6f 66 20 61 20 70 68 72 61 73 65 20 61 6e  n of a phrase an
c760: 64 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20  d table column, 
c770: 74 68 65 0a 20 20 20 20 20 20 66 6f 6c 6c 6f 77  the.      follow
c780: 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
c790: 3a 0a 20 20 20 20 20 20 3c 75 6c 3e 0a 20 20 20  :.      <ul>.   
c7a0: 20 20 20 20 20 3c 6c 69 3e 20 49 6e 20 74 68 65       <li> In the
c7b0: 20 63 75 72 72 65 6e 74 20 72 6f 77 2c 20 74 68   current row, th
c7c0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
c7d0: 73 20 74 68 65 20 70 68 72 61 73 65 20 61 70 70  s the phrase app
c7e0: 65 61 72 73 20 69 6e 20 0a 20 20 20 20 20 20 20  ears in .       
c7f0: 20 20 20 20 20 20 74 68 65 20 63 6f 6c 75 6d 6e        the column
c800: 2e 0a 20 20 20 20 20 20 20 20 3c 6c 69 3e 20 54  ..        <li> T
c810: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
c820: 6f 66 20 74 69 6d 65 73 20 74 68 65 20 70 68 72  of times the phr
c830: 61 73 65 20 61 70 70 65 61 72 73 20 69 6e 20 74  ase appears in t
c840: 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 0a 20 20 20  he column in.   
c850: 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 72 6f            all ro
c860: 77 73 20 69 6e 20 74 68 65 20 46 54 53 20 74 61  ws in the FTS ta
c870: 62 6c 65 2e 0a 20 20 20 20 20 20 20 20 3c 6c 69  ble..        <li
c880: 3e 20 54 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  > The total numb
c890: 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68  er of rows in th
c8a0: 65 20 46 54 53 20 74 61 62 6c 65 20 66 6f 72 20  e FTS table for 
c8b0: 77 68 69 63 68 20 74 68 65 20 0a 20 20 20 20 20  which the .     
c8c0: 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 63          column c
c8d0: 6f 6e 74 61 69 6e 73 20 61 74 20 6c 65 61 73 74  ontains at least
c8e0: 20 6f 6e 65 20 69 6e 73 74 61 6e 63 65 20 6f 66   one instance of
c8f0: 20 74 68 65 20 70 68 72 61 73 65 2e 0a 20 20 20   the phrase..   
c900: 20 20 20 3c 2f 75 6c 3e 0a 20 20 20 20 20 20 54     </ul>.      T
c910: 68 65 20 66 69 72 73 74 20 73 65 74 20 6f 66 20  he first set of 
c920: 74 68 72 65 65 20 76 61 6c 75 65 73 20 63 6f 72  three values cor
c930: 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20  responds to the 
c940: 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
c950: 0a 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61  .      of the ta
c960: 62 6c 65 20 28 63 6f 6c 75 6d 6e 20 30 29 20 61  ble (column 0) a
c970: 6e 64 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74  nd the left-most
c980: 20 6d 61 74 63 68 61 62 6c 65 20 70 68 72 61 73   matchable phras
c990: 65 20 69 6e 20 74 68 65 0a 20 20 20 20 20 20 71  e in the.      q
c9a0: 75 65 72 79 20 28 70 68 72 61 73 65 20 30 29 2e  uery (phrase 0).
c9b0: 20 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61   If the table ha
c9c0: 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
c9d0: 63 6f 6c 75 6d 6e 2c 20 74 68 65 20 73 65 63 6f  column, the seco
c9e0: 6e 64 0a 20 20 20 20 20 20 73 65 74 20 6f 66 20  nd.      set of 
c9f0: 74 68 72 65 65 20 76 61 6c 75 65 73 20 69 6e 20  three values in 
ca00: 74 68 65 20 6f 75 74 70 75 74 20 61 72 72 61 79  the output array
ca10: 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 70   correspond to p
ca20: 68 72 61 73 65 20 30 20 61 6e 64 0a 20 20 20 20  hrase 0 and.    
ca30: 20 20 63 6f 6c 75 6d 6e 20 31 2e 20 46 6f 6c 6c    column 1. Foll
ca40: 6f 77 65 64 20 62 79 20 70 68 72 61 73 65 20 30  owed by phrase 0
ca50: 2c 20 63 6f 6c 75 6d 6e 20 32 20 61 6e 64 20 73  , column 2 and s
ca60: 6f 20 6f 6e 20 66 6f 72 20 61 6c 6c 20 63 6f 6c  o on for all col
ca70: 75 6d 6e 73 20 6f 66 0a 20 20 20 20 20 20 74 68  umns of.      th
ca80: 65 20 74 61 62 6c 65 2e 20 41 6e 64 20 73 6f 20  e table. And so 
ca90: 6f 6e 20 66 6f 72 20 70 68 72 61 73 65 20 31 2c  on for phrase 1,
caa0: 20 63 6f 6c 75 6d 6e 20 30 2c 20 74 68 65 6e 20   column 0, then 
cab0: 70 68 72 61 73 65 20 31 2c 20 63 6f 6c 75 6d 6e  phrase 1, column
cac0: 20 31 0a 20 20 20 20 20 20 65 74 63 2e 20 49 6e   1.      etc. In
cad0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
cae0: 65 20 64 61 74 61 20 66 6f 72 20 6f 63 63 75 72  e data for occur
caf0: 72 65 6e 63 65 73 20 6f 66 20 70 68 72 61 73 65  rences of phrase
cb00: 20 3c 69 3e 70 3c 2f 69 3e 20 69 6e 0a 20 20 20   <i>p</i> in.   
cb10: 20 20 20 63 6f 6c 75 6d 6e 20 3c 69 3e 63 3c 2f     column <i>c</
cb20: 69 3e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  i> may be found 
cb30: 75 73 69 6e 67 20 74 68 65 20 66 6f 6c 6c 6f 77  using the follow
cb40: 69 6e 67 20 66 6f 72 6d 75 6c 61 3a 0a 3c 70 72  ing formula:.<pr
cb50: 65 3e 0a 20 20 20 20 20 20 20 20 20 20 68 69 74  e>.          hit
cb60: 73 5f 74 68 69 73 5f 72 6f 77 20 20 3d 20 61 72  s_this_row  = ar
cb70: 72 61 79 26 23 39 31 3b 33 20 2a 20 28 63 20 2b  ray&#91;3 * (c +
cb80: 20 70 2a 63 6f 6c 73 29 20 2b 20 30 26 23 39 33   p*cols) + 0&#93
cb90: 3b 0a 20 20 20 20 20 20 20 20 20 20 68 69 74 73  ;.          hits
cba0: 5f 61 6c 6c 5f 72 6f 77 73 20 20 3d 20 61 72 72  _all_rows  = arr
cbb0: 61 79 26 23 39 31 3b 33 20 2a 20 28 63 20 2b 20  ay&#91;3 * (c + 
cbc0: 70 2a 63 6f 6c 73 29 20 2b 20 31 26 23 39 33 3b  p*cols) + 1&#93;
cbd0: 0a 20 20 20 20 20 20 20 20 20 20 64 6f 63 73 5f  .          docs_
cbe0: 77 69 74 68 5f 68 69 74 73 20 3d 20 61 72 72 61  with_hits = arra
cbf0: 79 26 23 39 31 3b 33 20 2a 20 28 63 20 2b 20 70  y&#91;3 * (c + p
cc00: 2a 63 6f 6c 73 29 20 2b 20 32 26 23 39 33 3b 0a  *cols) + 2&#93;.
cc10: 3c 2f 70 72 65 3e 0a 0a 20 20 3c 74 72 3e 3c 74  </pre>..  <tr><t
cc20: 64 3e 6e 20 3c 74 64 3e 31 20 3c 74 64 3e 54 68  d>n <td>1 <td>Th
cc30: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
cc40: 20 69 6e 20 74 68 65 20 46 54 53 34 20 74 61 62   in the FTS4 tab
cc50: 6c 65 2e 20 54 68 69 73 20 76 61 6c 75 65 20 69  le. This value i
cc60: 73 0a 20 20 20 20 6f 6e 6c 79 20 61 76 61 69 6c  s.    only avail
cc70: 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
cc80: 6e 67 20 46 54 53 34 20 74 61 62 6c 65 73 2c 20  ng FTS4 tables, 
cc90: 6e 6f 74 20 46 54 53 33 2e 0a 20 20 3c 74 72 3e  not FTS3..  <tr>
cca0: 3c 74 64 3e 61 20 3c 74 64 3e 3c 69 3e 63 6f 6c  <td>a <td><i>col
ccb0: 73 3c 2f 69 3e 20 3c 74 64 3e 46 6f 72 20 65 61  s</i> <td>For ea
ccc0: 63 68 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 20 61  ch column, the a
ccd0: 76 65 72 61 67 65 20 6e 75 6d 62 65 72 20 6f 66  verage number of
cce0: 0a 20 20 20 20 74 6f 6b 65 6e 73 20 69 6e 20 74  .    tokens in t
ccf0: 68 65 20 74 65 78 74 20 76 61 6c 75 65 73 20 73  he text values s
cd00: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 6f 6c  tored in the col
cd10: 75 6d 6e 20 28 63 6f 6e 73 69 64 65 72 69 6e 67  umn (considering
cd20: 20 61 6c 6c 20 72 6f 77 73 20 69 6e 0a 20 20 20   all rows in.   
cd30: 20 74 68 65 20 46 54 53 34 20 74 61 62 6c 65 29   the FTS4 table)
cd40: 2e 20 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  . This value is 
cd50: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
cd60: 68 65 6e 20 71 75 65 72 79 69 6e 67 20 46 54 53  hen querying FTS
cd70: 34 20 74 61 62 6c 65 73 2c 0a 20 20 20 20 6e 6f  4 tables,.    no
cd80: 74 20 46 54 53 33 2e 20 20 0a 20 20 3c 74 72 3e  t FTS3.  .  <tr>
cd90: 3c 74 64 3e 6c 20 3c 74 64 3e 3c 69 3e 63 6f 6c  <td>l <td><i>col
cda0: 73 3c 2f 69 3e 20 3c 74 64 3e 0a 20 20 20 20 46  s</i> <td>.    F
cdb0: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2c 20  or each column, 
cdc0: 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
cdd0: 65 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 69  e value stored i
cde0: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
cdf0: 77 20 6f 66 20 74 68 65 0a 20 20 20 20 46 54 53  w of the.    FTS
ce00: 34 20 74 61 62 6c 65 2c 20 69 6e 20 74 6f 6b 65  4 table, in toke
ce10: 6e 73 2e 20 20 54 68 69 73 20 76 61 6c 75 65 20  ns.  This value 
ce20: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
ce30: 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 0a  e when querying.
ce40: 20 20 20 20 46 54 53 34 20 74 61 62 6c 65 73 2c      FTS4 tables,
ce50: 20 6e 6f 74 20 46 54 53 33 2e 20 41 6e 64 20 6f   not FTS3. And o
ce60: 6e 6c 79 20 69 66 20 74 68 65 20 22 6d 61 74 63  nly if the "matc
ce70: 68 69 6e 66 6f 3d 66 74 73 33 22 20 64 69 72 65  hinfo=fts3" dire
ce80: 63 74 69 76 65 20 77 61 73 20 6e 6f 74 0a 20 20  ctive was not.  
ce90: 20 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70    specified as p
cea0: 61 72 74 20 6f 66 20 74 68 65 20 22 43 52 45 41  art of the "CREA
ceb0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
cec0: 22 20 73 74 61 74 65 6d 65 6e 74 20 75 73 65 64  " statement used
ced0: 20 74 6f 20 63 72 65 61 74 65 0a 20 20 20 20 74   to create.    t
cee0: 68 65 20 46 54 53 34 20 74 61 62 6c 65 2e 0a 20  he FTS4 table.. 
cef0: 20 3c 74 72 3e 3c 74 64 3e 73 20 3c 74 64 3e 3c   <tr><td>s <td><
cf00: 69 3e 63 6f 6c 73 3c 2f 69 3e 20 3c 74 64 3e 46  i>cols</i> <td>F
cf10: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2c 20  or each column, 
cf20: 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
cf30: 65 20 6c 6f 6e 67 65 73 74 20 0a 20 20 20 20 73  e longest .    s
cf40: 75 62 73 65 71 75 65 6e 63 65 20 6f 66 20 70 68  ubsequence of ph
cf50: 72 61 73 65 20 6d 61 74 63 68 65 73 20 74 68 61  rase matches tha
cf60: 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
cf70: 75 65 20 68 61 73 20 69 6e 20 63 6f 6d 6d 6f 6e  ue has in common
cf80: 0a 20 20 20 20 77 69 74 68 20 74 68 65 20 71 75  .    with the qu
cf90: 65 72 79 20 74 65 78 74 2e 20 46 6f 72 20 65 78  ery text. For ex
cfa0: 61 6d 70 6c 65 2c 20 69 66 20 61 20 74 61 62 6c  ample, if a tabl
cfb0: 65 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e  e column contain
cfc0: 73 20 74 68 65 20 74 65 78 74 0a 20 20 20 20 27  s the text.    '
cfd0: 61 20 62 20 63 20 64 20 65 27 20 61 6e 64 20 74  a b c d e' and t
cfe0: 68 65 20 71 75 65 72 79 20 69 73 20 27 61 20 63  he query is 'a c
cff0: 20 22 64 20 65 22 27 2c 20 74 68 65 6e 20 74 68   "d e"', then th
d000: 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
d010: 6c 6f 6e 67 65 73 74 0a 20 20 20 20 63 6f 6d 6d  longest.    comm
d020: 6f 6e 20 73 75 62 73 65 71 75 65 6e 63 65 20 69  on subsequence i
d030: 73 20 32 20 28 70 68 72 61 73 65 20 22 63 22 20  s 2 (phrase "c" 
d040: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 70 68 72 61  followed by phra
d050: 73 65 20 22 64 20 65 22 29 2e 0a 20 20 20 20 0a  se "d e")..    .
d060: 20 20 20 20 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c      .</table>..<
d070: 70 3e 0a 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  p>.  For example
d080: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
d090: 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e   <i>-- Create an
d0a0: 64 20 70 6f 70 75 6c 61 74 65 20 61 6e 20 46 54  d populate an FT
d0b0: 53 34 20 74 61 62 6c 65 20 77 69 74 68 20 74 77  S4 table with tw
d0c0: 6f 20 63 6f 6c 75 6d 6e 73 3a 3c 2f 69 3e 0a 20  o columns:</i>. 
d0d0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
d0e0: 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66  TABLE t1 USING f
d0f0: 74 73 34 28 61 2c 20 62 29 3b 0a 20 20 49 4e 53  ts4(a, b);.  INS
d100: 45 52 54 20 49 4e 54 4f 20 74 31 20 56 41 4c 55  ERT INTO t1 VALU
d110: 45 53 28 27 74 72 61 6e 73 61 63 74 69 6f 6e 20  ES('transaction 
d120: 64 65 66 61 75 6c 74 20 6d 6f 64 65 6c 73 20 64  default models d
d130: 65 66 61 75 6c 74 27 2c 20 27 4e 6f 6e 20 74 72  efault', 'Non tr
d140: 61 6e 73 61 63 74 69 6f 6e 20 72 65 61 64 73 27  ansaction reads'
d150: 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
d160: 20 74 31 20 56 41 4c 55 45 53 28 27 74 68 65 20   t1 VALUES('the 
d170: 64 65 66 61 75 6c 74 20 74 72 61 6e 73 61 63 74  default transact
d180: 69 6f 6e 27 2c 20 27 74 68 65 73 65 20 73 65 6d  ion', 'these sem
d190: 61 6e 74 69 63 73 20 70 72 65 73 65 6e 74 27 29  antics present')
d1a0: 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
d1b0: 74 31 20 56 41 4c 55 45 53 28 27 73 69 6e 67 6c  t1 VALUES('singl
d1c0: 65 20 72 65 71 75 65 73 74 27 2c 20 27 64 65 66  e request', 'def
d1d0: 61 75 6c 74 20 64 61 74 61 27 29 3b 0a 0a 20 20  ault data');..  
d1e0: 3c 69 3e 2d 2d 20 49 6e 20 74 68 65 20 66 6f 6c  <i>-- In the fol
d1f0: 6c 6f 77 69 6e 67 20 71 75 65 72 79 2c 20 6e 6f  lowing query, no
d200: 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
d210: 73 20 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  s specified and 
d220: 73 6f 20 69 74 20 64 65 66 61 75 6c 74 73 3c 2f  so it defaults</
d230: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 6f 20 22 70  i>.  <i>-- to "p
d240: 63 78 22 2e 20 49 74 20 74 68 65 72 65 66 6f 72  cx". It therefor
d250: 65 20 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67  e returns a sing
d260: 6c 65 20 72 6f 77 20 63 6f 6e 73 69 73 74 69 6e  le row consistin
d270: 67 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 62 6c  g of a single bl
d280: 6f 62 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 76  ob</i>.  <i>-- v
d290: 61 6c 75 65 20 38 30 20 62 79 74 65 73 20 69 6e  alue 80 bytes in
d2a0: 20 73 69 7a 65 20 28 32 30 20 33 32 2d 62 69 74   size (20 32-bit
d2b0: 20 69 6e 74 65 67 65 72 73 20 2d 20 31 20 66 6f   integers - 1 fo
d2c0: 72 20 22 70 22 2c 20 31 20 66 6f 72 20 22 63 22  r "p", 1 for "c"
d2d0: 20 61 6e 64 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d   and</i>.  <i>--
d2e0: 20 33 2a 32 2a 33 20 66 6f 72 20 22 78 22 29 2e   3*2*3 for "x").
d2f0: 20 49 66 20 65 61 63 68 20 62 6c 6f 63 6b 20 6f   If each block o
d300: 66 20 34 20 62 79 74 65 73 20 69 6e 3c 2f 69 3e  f 4 bytes in</i>
d310: 20 74 68 65 20 62 6c 6f 62 20 69 73 20 69 6e 74   the blob is int
d320: 65 72 70 72 65 74 65 64 3c 2f 69 3e 20 0a 20 20  erpreted</i> .  
d330: 3c 69 3e 2d 2d 20 61 73 20 61 6e 20 75 6e 73 69  <i>-- as an unsi
d340: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 20  gned integer in 
d350: 6d 61 63 68 69 6e 65 20 62 79 74 65 2d 6f 72 64  machine byte-ord
d360: 65 72 2c 20 74 68 65 20 76 61 6c 75 65 73 20 77  er, the values w
d370: 69 6c 6c 20 62 65 3a 3c 2f 69 3e 0a 20 20 3c 69  ill be:</i>.  <i
d380: 3e 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  >--</i>.  <i>-- 
d390: 20 20 20 20 33 20 32 20 20 31 20 33 20 32 20 20      3 2  1 3 2  
d3a0: 30 20 31 20 31 20 20 31 20 32 20 32 20 20 30 20  0 1 1  1 2 2  0 
d3b0: 31 20 31 20 20 30 20 30 20 30 20 20 31 20 31 20  1 1  0 0 0  1 1 
d3c0: 31 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 3c 2f 69  1</i>.  <i>--</i
d3d0: 3e 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 72 6f  >.  <i>-- The ro
d3e0: 77 20 72 65 74 75 72 6e 65 64 20 63 6f 72 72 65  w returned corre
d3f0: 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20 73 65  sponds to the se
d400: 63 6f 6e 64 20 65 6e 74 72 79 20 69 6e 73 65 72  cond entry inser
d410: 74 65 64 20 69 6e 74 6f 20 74 61 62 6c 65 20 74  ted into table t
d420: 31 2e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 54  1.</i>.  <i>-- T
d430: 68 65 20 66 69 72 73 74 20 74 77 6f 20 69 6e 74  he first two int
d440: 65 67 65 72 73 20 69 6e 20 74 68 65 20 62 6c 6f  egers in the blo
d450: 62 20 73 68 6f 77 20 74 68 61 74 20 74 68 65 20  b show that the 
d460: 71 75 65 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  query contained 
d470: 74 68 72 65 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  three</i>.  <i>-
d480: 2d 20 70 68 72 61 73 65 73 20 61 6e 64 20 74 68  - phrases and th
d490: 65 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  e table being qu
d4a0: 65 72 69 65 64 20 68 61 73 20 74 77 6f 20 63 6f  eried has two co
d4b0: 6c 75 6d 6e 73 2e 20 54 68 65 20 6e 65 78 74 20  lumns. The next 
d4c0: 62 6c 6f 63 6b 20 6f 66 3c 2f 69 3e 0a 20 20 3c  block of</i>.  <
d4d0: 69 3e 2d 2d 20 74 68 72 65 65 20 69 6e 74 65 67  i>-- three integ
d4e0: 65 72 73 20 64 65 73 63 72 69 62 65 73 20 63 6f  ers describes co
d4f0: 6c 75 6d 6e 20 30 20 28 69 6e 20 74 68 69 73 20  lumn 0 (in this 
d500: 63 61 73 65 20 63 6f 6c 75 6d 6e 20 22 61 22 29  case column "a")
d510: 20 61 6e 64 20 70 68 72 61 73 65 3c 2f 69 3e 0a   and phrase</i>.
d520: 20 20 3c 69 3e 2d 2d 20 30 20 28 69 6e 20 74 68    <i>-- 0 (in th
d530: 69 73 20 63 61 73 65 20 22 64 65 66 61 75 6c 74  is case "default
d540: 22 29 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20  "). The current 
d550: 72 6f 77 20 63 6f 6e 74 61 69 6e 73 20 31 20 68  row contains 1 h
d560: 69 74 20 66 6f 72 20 22 64 65 66 61 75 6c 74 22  it for "default"
d570: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e 20  </i>.  <i>-- in 
d580: 63 6f 6c 75 6d 6e 20 30 2c 20 6f 66 20 61 20 74  column 0, of a t
d590: 6f 74 61 6c 20 6f 66 20 33 20 68 69 74 73 20 66  otal of 3 hits f
d5a0: 6f 72 20 22 64 65 66 61 75 6c 74 22 20 74 68 61  or "default" tha
d5b0: 74 20 6f 63 63 75 72 20 69 6e 20 63 6f 6c 75 6d  t occur in colum
d5c0: 6e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 30 20  n</i>.  <i>-- 0 
d5d0: 6f 66 20 61 6e 79 20 74 61 62 6c 65 20 72 6f 77  of any table row
d5e0: 2e 20 54 68 65 20 33 20 68 69 74 73 20 61 72 65  . The 3 hits are
d5f0: 20 73 70 72 65 61 64 20 61 63 72 6f 73 73 20 32   spread across 2
d600: 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77 73 2e   different rows.
d610: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 3c 2f 69 3e  </i>.  <i>--</i>
d620: 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 6e 65 78  .  <i>-- The nex
d630: 74 20 73 65 74 20 6f 66 20 74 68 72 65 65 20 69  t set of three i
d640: 6e 74 65 67 65 72 73 20 28 30 20 31 20 31 29 20  ntegers (0 1 1) 
d650: 70 65 72 74 61 69 6e 20 74 6f 20 74 68 65 20 68  pertain to the h
d660: 69 74 73 20 66 6f 72 20 22 64 65 66 61 75 6c 74  its for "default
d670: 22 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e  "</i>.  <i>-- in
d680: 20 63 6f 6c 75 6d 6e 20 31 20 6f 66 20 74 68 65   column 1 of the
d690: 20 74 61 62 6c 65 20 28 30 20 69 6e 20 74 68 69   table (0 in thi
d6a0: 73 20 72 6f 77 2c 20 31 20 69 6e 20 61 6c 6c 20  s row, 1 in all 
d6b0: 72 6f 77 73 2c 20 73 70 72 65 61 64 20 61 63 72  rows, spread acr
d6c0: 6f 73 73 20 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  oss </i>.  <i>--
d6d0: 20 31 20 72 6f 77 73 29 2e 3c 2f 69 3e 0a 20 20   1 rows).</i>.  
d6e0: 3c 69 3e 2d 2d 3c 2f 69 3e 0a 20 20 53 45 4c 45  <i>--</i>.  SELE
d6f0: 43 54 20 6d 61 74 63 68 69 6e 66 6f 28 74 31 29  CT matchinfo(t1)
d700: 20 46 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74   FROM t1 WHERE t
d710: 31 20 4d 41 54 43 48 20 27 64 65 66 61 75 6c 74  1 MATCH 'default
d720: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 22 74 68   transaction "th
d730: 65 73 65 20 73 65 6d 61 6e 74 69 63 73 22 27 3b  ese semantics"';
d740: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f  ..  <i>-- The fo
d750: 72 6d 61 74 20 73 74 72 69 6e 67 20 66 6f 72 20  rmat string for 
d760: 74 68 69 73 20 71 75 65 72 79 20 69 73 20 22 6e  this query is "n
d770: 73 22 2e 20 54 68 65 20 6f 75 74 70 75 74 20 61  s". The output a
d780: 72 72 61 79 20 77 69 6c 6c 20 74 68 65 72 65 66  rray will theref
d790: 6f 72 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  ore</i>.  <i>-- 
d7a0: 63 6f 6e 74 61 69 6e 20 33 20 69 6e 74 65 67 65  contain 3 intege
d7b0: 72 20 76 61 6c 75 65 73 20 2d 20 31 20 66 6f 72  r values - 1 for
d7c0: 20 22 6e 22 20 61 6e 64 20 32 20 66 6f 72 20 22   "n" and 2 for "
d7d0: 73 22 2e 20 54 68 65 20 71 75 65 72 79 20 72 65  s". The query re
d7e0: 74 75 72 6e 73 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  turns</i>.  <i>-
d7f0: 2d 20 74 77 6f 20 72 6f 77 73 20 28 74 68 65 20  - two rows (the 
d800: 66 69 72 73 74 20 74 77 6f 20 72 6f 77 73 20 69  first two rows i
d810: 6e 20 74 68 65 20 74 61 62 6c 65 20 6d 61 74 63  n the table matc
d820: 68 29 2e 20 54 68 65 20 76 61 6c 75 65 73 20 72  h). The values r
d830: 65 74 75 72 6e 65 64 20 61 72 65 3a 3c 2f 69 3e  eturned are:</i>
d840: 0a 20 20 3c 69 3e 2d 2d 3c 2f 69 3e 0a 20 20 3c  .  <i>--</i>.  <
d850: 69 3e 2d 2d 20 20 20 20 20 33 20 20 31 20 31 3c  i>--     3  1 1<
d860: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 20 20  /i>.  <i>--     
d870: 33 20 20 32 20 30 3c 2f 69 3e 0a 20 20 3c 69 3e  3  2 0</i>.  <i>
d880: 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 54  --</i>.  <i>-- T
d890: 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 69  he first value i
d8a0: 6e 20 74 68 65 20 6d 61 74 63 68 69 6e 66 6f 20  n the matchinfo 
d8b0: 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 66  array returned f
d8c0: 6f 72 20 62 6f 74 68 20 72 6f 77 73 20 69 73 20  or both rows is 
d8d0: 33 20 28 74 68 65 20 3c 2f 69 3e 0a 20 20 3c 69  3 (the </i>.  <i
d8e0: 3e 2d 2d 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  >-- number of ro
d8f0: 77 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 29  ws in the table)
d900: 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  . The following 
d910: 74 77 6f 20 76 61 6c 75 65 73 20 61 72 65 20 74  two values are t
d920: 68 65 20 6c 65 6e 67 74 68 73 20 3c 2f 69 3e 0a  he lengths </i>.
d930: 20 20 3c 69 3e 2d 2d 20 6f 66 20 74 68 65 20 6c    <i>-- of the l
d940: 6f 6e 67 65 73 74 20 63 6f 6d 6d 6f 6e 20 73 75  ongest common su
d950: 62 73 65 71 75 65 6e 63 65 20 6f 66 20 70 68 72  bsequence of phr
d960: 61 73 65 20 6d 61 74 63 68 65 73 20 69 6e 20 65  ase matches in e
d970: 61 63 68 20 63 6f 6c 75 6d 6e 2e 3c 2f 69 3e 0a  ach column.</i>.
d980: 20 20 53 45 4c 45 43 54 20 6d 61 74 63 68 69 6e    SELECT matchin
d990: 66 6f 28 74 31 2c 20 27 6e 73 27 29 20 46 52 4f  fo(t1, 'ns') FRO
d9a0: 4d 20 74 31 20 57 48 45 52 45 20 74 31 20 4d 41  M t1 WHERE t1 MA
d9b0: 54 43 48 20 27 64 65 66 61 75 6c 74 20 74 72 61  TCH 'default tra
d9c0: 6e 73 61 63 74 69 6f 6e 27 3b 0a 3c 2f 63 6f 64  nsaction';.</cod
d9d0: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54  eblock>..<p>.  T
d9e0: 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 66 75 6e  he matchinfo fun
d9f0: 63 74 69 6f 6e 20 69 73 20 6d 75 63 68 20 66 61  ction is much fa
da00: 73 74 65 72 20 74 68 61 6e 20 65 69 74 68 65 72  ster than either
da10: 20 74 68 65 20 73 6e 69 70 70 65 74 20 6f 72 20   the snippet or 
da20: 6f 66 66 73 65 74 73 0a 20 20 66 75 6e 63 74 69  offsets.  functi
da30: 6f 6e 73 2e 20 54 68 69 73 20 69 73 20 62 65 63  ons. This is bec
da40: 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
da50: 6e 74 61 74 69 6f 6e 20 6f 66 20 62 6f 74 68 20  ntation of both 
da60: 73 6e 69 70 70 65 74 20 61 6e 64 20 6f 66 66 73  snippet and offs
da70: 65 74 73 0a 20 20 69 73 20 72 65 71 75 69 72 65  ets.  is require
da80: 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  d to retrieve th
da90: 65 20 64 6f 63 75 6d 65 6e 74 73 20 62 65 69 6e  e documents bein
daa0: 67 20 61 6e 61 6c 79 7a 65 64 20 66 72 6f 6d 20  g analyzed from 
dab0: 64 69 73 6b 2c 20 77 68 65 72 65 61 73 0a 20 20  disk, whereas.  
dac0: 61 6c 6c 20 64 61 74 61 20 72 65 71 75 69 72 65  all data require
dad0: 64 20 62 79 20 6d 61 74 63 68 69 6e 66 6f 20 69  d by matchinfo i
dae0: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 70  s available as p
daf0: 61 72 74 20 6f 66 20 74 68 65 20 73 61 6d 65 20  art of the same 
db00: 70 6f 72 74 69 6f 6e 73 0a 20 20 6f 66 20 74 68  portions.  of th
db10: 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65  e full-text inde
db20: 78 20 74 68 61 74 20 61 72 65 20 72 65 71 75 69  x that are requi
db30: 72 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  red to implement
db40: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 71   the full-text q
db50: 75 65 72 79 0a 20 20 69 74 73 65 6c 66 2e 20 54  uery.  itself. T
db60: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  his means that o
db70: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
db80: 74 77 6f 20 71 75 65 72 69 65 73 2c 20 74 68 65  two queries, the
db90: 20 66 69 72 73 74 20 6d 61 79 20 62 65 0a 20 20   first may be.  
dba0: 61 6e 20 6f 72 64 65 72 20 6f 66 20 6d 61 67 6e  an order of magn
dbb0: 69 74 75 64 65 20 66 61 73 74 65 72 20 74 68 61  itude faster tha
dbc0: 6e 20 74 68 65 20 73 65 63 6f 6e 64 3a 0a 0a 3c  n the second:..<
dbd0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c  codeblock>.  SEL
dbe0: 45 43 54 20 64 6f 63 69 64 2c 20 6d 61 74 63 68  ECT docid, match
dbf0: 69 6e 66 6f 28 74 62 6c 29 20 46 52 4f 4d 20 74  info(tbl) FROM t
dc00: 62 6c 20 57 48 45 52 45 20 74 62 6c 20 4d 41 54  bl WHERE tbl MAT
dc10: 43 48 20 26 6c 74 3b 71 75 65 72 79 20 65 78 70  CH &lt;query exp
dc20: 72 65 73 73 69 6f 6e 26 67 74 3b 3b 0a 20 20 53  ression&gt;;.  S
dc30: 45 4c 45 43 54 20 64 6f 63 69 64 2c 20 6f 66 66  ELECT docid, off
dc40: 73 65 74 73 28 74 62 6c 29 20 46 52 4f 4d 20 74  sets(tbl) FROM t
dc50: 62 6c 20 57 48 45 52 45 20 74 62 6c 20 4d 41 54  bl WHERE tbl MAT
dc60: 43 48 20 26 6c 74 3b 71 75 65 72 79 20 65 78 70  CH &lt;query exp
dc70: 72 65 73 73 69 6f 6e 26 67 74 3b 3b 0a 3c 2f 63  ression&gt;;.</c
dc80: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20  odeblock>..<p>. 
dc90: 20 54 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 66   The matchinfo f
dca0: 75 6e 63 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  unction provides
dcb0: 20 61 6c 6c 20 74 68 65 20 69 6e 66 6f 72 6d 61   all the informa
dcc0: 74 69 6f 6e 20 72 65 71 75 69 72 65 64 20 74 6f  tion required to
dcd0: 20 63 61 6c 63 75 6c 61 74 65 0a 20 20 70 72 6f   calculate.  pro
dce0: 62 61 62 69 6c 69 73 74 69 63 20 22 62 61 67 2d  babilistic "bag-
dcf0: 6f 66 2d 77 6f 72 64 73 22 20 72 65 6c 65 76 61  of-words" releva
dd00: 6e 63 79 20 73 63 6f 72 65 73 20 73 75 63 68 20  ncy scores such 
dd10: 61 73 20 0a 20 20 3c 61 20 68 72 65 66 3d 68 74  as .  <a href=ht
dd20: 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69  tp://en.wikipedi
dd30: 61 2e 6f 72 67 2f 77 69 6b 69 2f 4f 6b 61 70 69  a.org/wiki/Okapi
dd40: 5f 42 4d 32 35 3e 4f 6b 61 70 69 20 42 4d 32 35  _BM25>Okapi BM25
dd50: 2f 42 4d 32 35 46 3c 2f 61 3e 20 74 68 61 74 20  /BM25F</a> that 
dd60: 6d 61 79 0a 20 20 62 65 20 75 73 65 64 20 74 6f  may.  be used to
dd70: 20 6f 72 64 65 72 20 72 65 73 75 6c 74 73 20 69   order results i
dd80: 6e 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  n a full-text se
dd90: 61 72 63 68 20 61 70 70 6c 69 63 61 74 69 6f 6e  arch application
dda0: 2e 20 41 70 70 65 6e 64 69 78 20 41 20 6f 66 20  . Appendix A of 
ddb0: 74 68 69 73 20 0a 20 20 64 6f 63 75 6d 65 6e 74  this .  document
ddc0: 2c 20 22 5b 73 65 61 72 63 68 20 61 70 70 6c 69  , "[search appli
ddd0: 63 61 74 69 6f 6e 20 74 69 70 73 5d 22 2c 20 63  cation tips]", c
dde0: 6f 6e 74 61 69 6e 73 20 61 6e 20 65 78 61 6d 70  ontains an examp
ddf0: 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 65 0a  le of using the.
de00: 20 20 6d 61 74 63 68 69 6e 66 6f 28 29 20 66 75    matchinfo() fu
de10: 6e 63 74 69 6f 6e 20 65 66 66 69 63 69 65 6e 74  nction efficient
de20: 6c 79 2e 0a 0a 3c 68 31 20 69 64 3d 66 74 73 34  ly...<h1 id=fts4
de30: 61 75 78 20 74 61 67 73 3d 22 66 74 73 34 61 75  aux tags="fts4au
de40: 78 22 3e 46 74 73 34 61 75 78 20 2d 20 44 69 72  x">Fts4aux - Dir
de50: 65 63 74 20 41 63 63 65 73 73 20 74 6f 20 74 68  ect Access to th
de60: 65 20 46 75 6c 6c 2d 54 65 78 74 20 49 6e 64 65  e Full-Text Inde
de70: 78 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20 41 73  x</h1>..<p>.  As
de80: 20 6f 66 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e   of version 3.7.
de90: 36 2c 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  6, SQLite includ
dea0: 65 73 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c  es a new virtual
deb0: 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 63 61   table module ca
dec0: 6c 6c 65 64 20 0a 20 20 22 66 74 73 34 61 75 78  lled .  "fts4aux
ded0: 22 2c 20 77 68 69 63 68 20 63 61 6e 20 62 65 20  ", which can be 
dee0: 75 73 65 64 20 74 6f 20 69 6e 73 70 65 63 74 20  used to inspect 
def0: 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  the full-text in
df00: 64 65 78 20 6f 66 20 61 6e 20 65 78 69 73 74 69  dex of an existi
df10: 6e 67 0a 20 20 46 54 53 20 74 61 62 6c 65 20 64  ng.  FTS table d
df20: 69 72 65 63 74 6c 79 2e 20 44 65 73 70 69 74 65  irectly. Despite
df30: 20 69 74 73 20 6e 61 6d 65 2c 20 66 74 73 34 61   its name, fts4a
df40: 75 78 20 77 6f 72 6b 73 20 6a 75 73 74 20 61 73  ux works just as
df50: 20 77 65 6c 6c 20 77 69 74 68 20 46 54 53 33 0a   well with FTS3.
df60: 20 20 74 61 62 6c 65 73 20 61 73 20 69 74 20 64    tables as it d
df70: 6f 65 73 20 77 69 74 68 20 46 54 53 34 20 74 61  oes with FTS4 ta
df80: 62 6c 65 73 2e 20 46 74 73 34 61 75 78 20 74 61  bles. Fts4aux ta
df90: 62 6c 65 73 20 61 72 65 20 72 65 61 64 2d 6f 6e  bles are read-on
dfa0: 6c 79 2e 20 54 68 65 20 6f 6e 6c 79 0a 20 20 77  ly. The only.  w
dfb0: 61 79 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ay to modify the
dfc0: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 61 6e 20   contents of an 
dfd0: 66 74 73 34 61 75 78 20 74 61 62 6c 65 20 69 73  fts4aux table is
dfe0: 20 62 79 20 6d 6f 64 69 66 79 69 6e 67 20 74 68   by modifying th
dff0: 65 0a 20 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  e.  contents of 
e000: 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 46  the associated F
e010: 54 53 20 74 61 62 6c 65 2e 20 54 68 65 20 66 74  TS table. The ft
e020: 73 34 61 75 78 20 6d 6f 64 75 6c 65 20 69 73 20  s4aux module is 
e030: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 20 20  automatically.  
e040: 69 6e 63 6c 75 64 65 64 20 69 6e 20 61 6c 6c 20  included in all 
e050: 5b 63 6f 6d 70 69 6c 65 20 66 74 73 7c 62 75 69  [compile fts|bui
e060: 6c 64 73 20 74 68 61 74 20 69 6e 63 6c 75 64 65  lds that include
e070: 20 46 54 53 5d 2e 0a 0a 3c 70 3e 0a 20 20 41 6e   FTS]...<p>.  An
e080: 20 66 74 73 34 61 75 78 20 76 69 72 74 75 61 6c   fts4aux virtual
e090: 20 74 61 62 6c 65 20 69 73 20 63 6f 6e 73 74 72   table is constr
e0a0: 75 63 74 65 64 20 77 69 74 68 20 6f 6e 65 20 6f  ucted with one o
e0b0: 72 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  r two arguments.
e0c0: 20 20 57 68 65 6e 0a 20 20 75 73 65 64 20 77 69    When.  used wi
e0d0: 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  th a single argu
e0e0: 6d 65 6e 74 2c 20 74 68 61 74 20 61 72 67 75 6d  ment, that argum
e0f0: 65 6e 74 20 69 73 20 74 68 65 20 75 6e 71 75 61  ent is the unqua
e100: 6c 69 66 69 65 64 20 6e 61 6d 65 20 6f 66 20 74  lified name of t
e110: 68 65 0a 20 20 46 54 53 20 74 61 62 6c 65 20 74  he.  FTS table t
e120: 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 75  hat it will be u
e130: 73 65 64 20 74 6f 20 61 63 63 65 73 73 2e 20 20  sed to access.  
e140: 54 6f 20 61 63 63 65 73 73 20 61 20 74 61 62 6c  To access a tabl
e150: 65 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  e in a different
e160: 0a 20 20 64 61 74 61 62 61 73 65 20 28 66 6f 72  .  database (for
e170: 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 63 72 65   example, to cre
e180: 61 74 65 20 61 20 54 45 4d 50 20 66 74 73 34 61  ate a TEMP fts4a
e190: 75 78 20 74 61 62 6c 65 20 74 68 61 74 20 77 69  ux table that wi
e1a0: 6c 6c 20 61 63 63 65 73 73 20 61 6e 0a 20 20 46  ll access an.  F
e1b0: 54 53 33 20 74 61 62 6c 65 20 69 6e 20 74 68 65  TS3 table in the
e1c0: 20 4d 41 49 4e 20 64 61 74 61 62 61 73 65 29 20   MAIN database) 
e1d0: 75 73 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  use the two-argu
e1e0: 6d 65 6e 74 20 66 6f 72 6d 20 61 6e 64 20 67 69  ment form and gi
e1f0: 76 65 20 74 68 65 0a 20 20 6e 61 6d 65 20 6f 66  ve the.  name of
e200: 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61   the target data
e210: 62 61 73 65 20 28 65 78 3a 20 22 6d 61 69 6e 22  base (ex: "main"
e220: 29 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  ) in the first a
e230: 72 67 75 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  rgument and the 
e240: 6e 61 6d 65 0a 20 20 6f 66 20 74 68 65 20 46 54  name.  of the FT
e250: 53 33 2f 34 20 74 61 62 6c 65 20 61 73 20 74 68  S3/4 table as th
e260: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
e270: 74 2e 20 20 28 54 68 65 20 74 77 6f 2d 61 72 67  t.  (The two-arg
e280: 75 6d 65 6e 74 20 66 6f 72 6d 20 6f 66 20 0a 20  ument form of . 
e290: 20 66 74 73 34 61 75 78 20 77 61 73 20 61 64 64   fts4aux was add
e2a0: 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 76 65  ed for SQLite ve
e2b0: 72 73 69 6f 6e 20 33 2e 37 2e 31 37 20 61 6e 64  rsion 3.7.17 and
e2c0: 20 77 69 6c 6c 20 74 68 72 6f 77 20 61 6e 20 65   will throw an e
e2d0: 72 72 6f 72 20 69 6e 0a 20 20 70 72 69 6f 72 20  rror in.  prior 
e2e0: 72 65 6c 65 61 73 65 73 2e 29 0a 20 20 46 6f 72  releases.).  For
e2f0: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
e300: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43  block>.  <i>-- C
e310: 72 65 61 74 65 20 61 6e 20 46 54 53 34 20 74 61  reate an FTS4 ta
e320: 62 6c 65 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45  ble</i>.  CREATE
e330: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
e340: 74 20 55 53 49 4e 47 20 66 74 73 34 28 78 2c 20  t USING fts4(x, 
e350: 79 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 72 65  y);..  <i>-- Cre
e360: 61 74 65 20 61 6e 20 66 74 73 34 61 75 78 20 74  ate an fts4aux t
e370: 61 62 6c 65 20 74 6f 20 61 63 63 65 73 73 20 74  able to access t
e380: 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he full-text ind
e390: 65 78 20 66 6f 72 20 74 61 62 6c 65 20 22 66 74  ex for table "ft
e3a0: 22 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  "</i>.  CREATE V
e3b0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 5f  IRTUAL TABLE ft_
e3c0: 74 65 72 6d 73 20 55 53 49 4e 47 20 66 74 73 34  terms USING fts4
e3d0: 61 75 78 28 66 74 29 3b 0a 0a 20 20 3c 69 3e 2d  aux(ft);..  <i>-
e3e0: 2d 20 43 72 65 61 74 65 20 61 20 54 45 4d 50 20  - Create a TEMP 
e3f0: 66 74 73 34 61 75 78 20 74 61 62 6c 65 20 61 63  fts4aux table ac
e400: 63 65 73 73 69 6e 67 20 74 68 65 20 22 66 74 22  cessing the "ft"
e410: 20 74 61 62 6c 65 20 69 6e 20 22 6d 61 69 6e 22   table in "main"
e420: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
e430: 52 54 55 41 4c 20 54 41 42 4c 45 20 74 65 6d 70  RTUAL TABLE temp
e440: 2e 66 74 5f 74 65 72 6d 73 5f 32 20 55 53 49 4e  .ft_terms_2 USIN
e450: 47 20 66 74 73 34 61 75 78 28 6d 61 69 6e 2c 66  G fts4aux(main,f
e460: 74 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  t);.</codeblock>
e470: 0a 0a 3c 70 3e 0a 20 20 46 6f 72 20 65 61 63 68  ..<p>.  For each
e480: 20 74 65 72 6d 20 70 72 65 73 65 6e 74 20 69 6e   term present in
e490: 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 2c 20   the FTS table, 
e4a0: 74 68 65 72 65 20 61 72 65 20 62 65 74 77 65 65  there are betwee
e4b0: 6e 20 32 20 61 6e 64 20 4e 2b 31 20 72 6f 77 73  n 2 and N+1 rows
e4c0: 0a 20 20 69 6e 20 74 68 65 20 66 74 73 34 61 75  .  in the fts4au
e4d0: 78 20 74 61 62 6c 65 2c 20 77 68 65 72 65 20 4e  x table, where N
e4e0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e4f0: 66 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 63  f user-defined c
e500: 6f 6c 75 6d 6e 73 20 69 6e 0a 20 20 74 68 65 20  olumns in.  the 
e510: 61 73 73 6f 63 69 61 74 65 64 20 46 54 53 20 74  associated FTS t
e520: 61 62 6c 65 2e 20 41 6e 20 66 74 73 34 61 75 78  able. An fts4aux
e530: 20 74 61 62 6c 65 20 61 6c 77 61 79 73 20 68 61   table always ha
e540: 73 20 74 68 65 20 73 61 6d 65 20 66 6f 75 72 20  s the same four 
e550: 63 6f 6c 75 6d 6e 73 2c 20 0a 20 20 61 73 20 66  columns, .  as f
e560: 6f 6c 6c 6f 77 73 2c 20 66 72 6f 6d 20 6c 65 66  ollows, from lef
e570: 74 20 74 6f 20 72 69 67 68 74 3a 0a 0a 3c 74 61  t to right:..<ta
e580: 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20  ble striped=1>. 
e590: 20 3c 74 72 3e 3c 74 68 3e 43 6f 6c 75 6d 6e 20   <tr><th>Column 
e5a0: 4e 61 6d 65 3c 74 68 3e 43 6f 6c 75 6d 6e 20 43  Name<th>Column C
e5b0: 6f 6e 74 65 6e 74 73 0a 20 20 3c 74 72 3e 3c 74  ontents.  <tr><t
e5c0: 64 3e 74 65 72 6d 3c 74 64 3e 20 0a 20 20 20 20  d>term<td> .    
e5d0: 43 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  Contains the tex
e5e0: 74 20 6f 66 20 74 68 65 20 74 65 72 6d 20 66 6f  t of the term fo
e5f0: 72 20 74 68 69 73 20 72 6f 77 2e 0a 20 20 3c 74  r this row..  <t
e600: 72 3e 3c 74 64 3e 63 6f 6c 3c 74 64 3e 20 0a 20  r><td>col<td> . 
e610: 20 20 20 54 68 69 73 20 63 6f 6c 75 6d 6e 20 6d     This column m
e620: 61 79 20 63 6f 6e 74 61 69 6e 20 65 69 74 68 65  ay contain eithe
e630: 72 20 74 68 65 20 74 65 78 74 20 76 61 6c 75 65  r the text value
e640: 20 27 2a 27 20 28 69 2e 65 2e 20 61 20 73 69 6e   '*' (i.e. a sin
e650: 67 6c 65 20 0a 20 20 20 20 63 68 61 72 61 63 74  gle .    charact
e660: 65 72 2c 20 55 2b 30 30 32 61 29 20 6f 72 20 61  er, U+002a) or a
e670: 6e 20 69 6e 74 65 67 65 72 20 62 65 74 77 65 65  n integer betwee
e680: 6e 20 30 20 61 6e 64 20 4e 2d 31 2c 20 77 68 65  n 0 and N-1, whe
e690: 72 65 20 4e 20 69 73 0a 20 20 20 20 61 67 61 69  re N is.    agai
e6a0: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
e6b0: 75 73 65 72 2d 64 65 66 69 6e 65 64 20 63 6f 6c  user-defined col
e6c0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 6f 72 72  umns in the corr
e6d0: 65 73 70 6f 6e 64 69 6e 67 20 46 54 53 20 74 61  esponding FTS ta
e6e0: 62 6c 65 2e 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e  ble...  <tr><td>
e6f0: 64 6f 63 75 6d 65 6e 74 73 3c 74 64 3e 0a 20 20  documents<td>.  
e700: 20 20 54 68 69 73 20 63 6f 6c 75 6d 6e 20 61 6c    This column al
e710: 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 6e  ways contains an
e720: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 67   integer value g
e730: 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
e740: 2e 0a 20 20 20 20 3c 62 72 3e 3c 62 72 3e 0a 20  ..    <br><br>. 
e750: 20 20 20 49 66 20 74 68 65 20 22 63 6f 6c 22 20     If the "col" 
e760: 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e 73 20  column contains 
e770: 74 68 65 20 76 61 6c 75 65 20 27 2a 27 2c 20 74  the value '*', t
e780: 68 65 6e 20 74 68 69 73 20 63 6f 6c 75 6d 6e 0a  hen this column.
e790: 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 74 68 65      contains the
e7a0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
e7b0: 6f 66 20 74 68 65 20 46 54 53 20 74 61 62 6c 65  of the FTS table
e7c0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 74   that contain at
e7d0: 20 6c 65 61 73 74 20 6f 6e 65 0a 20 20 20 20 69   least one.    i
e7e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74  nstance of the t
e7f0: 65 72 6d 20 28 69 6e 20 61 6e 79 20 63 6f 6c 75  erm (in any colu
e800: 6d 6e 29 2e 20 49 66 20 63 6f 6c 20 63 6f 6e 74  mn). If col cont
e810: 61 69 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ains an integer.
e820: 20 20 20 20 76 61 6c 75 65 2c 20 74 68 65 6e 20      value, then 
e830: 74 68 69 73 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74  this column cont
e840: 61 69 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ains the number 
e850: 6f 66 20 72 6f 77 73 20 6f 66 20 74 68 65 20 46  of rows of the F
e860: 54 53 20 74 61 62 6c 65 20 74 68 61 74 0a 20 20  TS table that.  
e870: 20 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61    contain at lea
e880: 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63 65 20  st one instance 
e890: 6f 66 20 74 68 65 20 74 65 72 6d 20 69 6e 20 74  of the term in t
e8a0: 68 65 20 63 6f 6c 75 6d 6e 20 69 64 65 6e 74 69  he column identi
e8b0: 66 69 65 64 20 62 79 0a 20 20 20 20 74 68 65 20  fied by.    the 
e8c0: 63 6f 6c 20 76 61 6c 75 65 2e 20 41 73 20 75 73  col value. As us
e8d0: 75 61 6c 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 73  ual, the columns
e8e0: 20 6f 66 20 74 68 65 20 46 54 53 20 74 61 62 6c   of the FTS tabl
e8f0: 65 20 61 72 65 20 6e 75 6d 62 65 72 65 64 0a 20  e are numbered. 
e900: 20 20 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20     from left to 
e910: 72 69 67 68 74 2c 20 73 74 61 72 74 69 6e 67 20  right, starting 
e920: 77 69 74 68 20 7a 65 72 6f 2e 0a 0a 20 20 3c 74  with zero...  <t
e930: 72 3e 3c 74 64 3e 6f 63 63 75 72 72 65 6e 63 65  r><td>occurrence
e940: 73 3c 74 64 3e 0a 20 20 20 20 54 68 69 73 20 63  s<td>.    This c
e950: 6f 6c 75 6d 6e 20 61 6c 73 6f 20 61 6c 77 61 79  olumn also alway
e960: 73 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 69 6e  s contains an in
e970: 74 65 67 65 72 20 76 61 6c 75 65 20 67 72 65 61  teger value grea
e980: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 20  ter than zero.. 
e990: 20 20 20 3c 62 72 3e 3c 62 72 3e 0a 20 20 20 20     <br><br>.    
e9a0: 49 66 20 74 68 65 20 22 63 6f 6c 22 20 63 6f 6c  If the "col" col
e9b0: 75 6d 6e 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  umn contains the
e9c0: 20 76 61 6c 75 65 20 27 2a 27 2c 20 74 68 65 6e   value '*', then
e9d0: 20 74 68 69 73 20 63 6f 6c 75 6d 6e 0a 20 20 20   this column.   
e9e0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 6f   contains the to
e9f0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  tal number of in
ea00: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 65 20 74  stances of the t
ea10: 65 72 6d 20 69 6e 20 61 6c 6c 20 72 6f 77 73 20  erm in all rows 
ea20: 6f 66 20 74 68 65 20 0a 20 20 20 20 46 54 53 20  of the .    FTS 
ea30: 74 61 62 6c 65 20 28 69 6e 20 61 6e 79 20 63 6f  table (in any co
ea40: 6c 75 6d 6e 29 2e 20 4f 74 68 65 72 77 69 73 65  lumn). Otherwise
ea50: 2c 20 69 66 20 63 6f 6c 20 63 6f 6e 74 61 69 6e  , if col contain
ea60: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 20 20 20  s an integer.   
ea70: 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 74 68 69   value, then thi
ea80: 73 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e  s column contain
ea90: 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
eaa0: 65 72 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20  er of instances 
eab0: 6f 66 20 74 68 65 0a 20 20 20 20 74 65 72 6d 20  of the.    term 
eac0: 74 68 61 74 20 61 70 70 65 61 72 20 69 6e 20 74  that appear in t
ead0: 68 65 20 46 54 53 20 74 61 62 6c 65 20 63 6f 6c  he FTS table col
eae0: 75 6d 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  umn identified b
eaf0: 79 20 74 68 65 20 63 6f 6c 0a 20 20 20 20 76 61  y the col.    va
eb00: 6c 75 65 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c  lue..</table>..<
eb10: 70 3e 0a 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  p>.  For example
eb20: 2c 20 75 73 69 6e 67 20 74 68 65 20 74 61 62 6c  , using the tabl
eb30: 65 73 20 63 72 65 61 74 65 64 20 61 62 6f 76 65  es created above
eb40: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
eb50: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28   INSERT INTO ft(
eb60: 78 2c 20 79 29 20 56 41 4c 55 45 53 28 27 41 70  x, y) VALUES('Ap
eb70: 70 6c 65 20 62 61 6e 61 6e 61 27 2c 20 27 43 68  ple banana', 'Ch
eb80: 65 72 72 79 27 29 3b 0a 20 20 49 4e 53 45 52 54  erry');.  INSERT
eb90: 20 49 4e 54 4f 20 66 74 28 78 2c 20 79 29 20 56   INTO ft(x, y) V
eba0: 41 4c 55 45 53 28 27 42 61 6e 61 6e 61 20 44 61  ALUES('Banana Da
ebb0: 74 65 20 44 61 74 65 27 2c 20 27 63 68 65 72 72  te Date', 'cherr
ebc0: 79 27 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e  y');.  INSERT IN
ebd0: 54 4f 20 66 74 28 78 2c 20 79 29 20 56 41 4c 55  TO ft(x, y) VALU
ebe0: 45 53 28 27 43 68 65 72 72 79 20 45 6c 64 65 72  ES('Cherry Elder
ebf0: 62 65 72 72 79 27 2c 20 27 45 6c 64 65 72 62 65  berry', 'Elderbe
ec00: 72 72 79 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  rry');..  <i>-- 
ec10: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  The following qu
ec20: 65 72 79 20 72 65 74 75 72 6e 73 20 74 68 69 73  ery returns this
ec30: 20 64 61 74 61 3a 3c 2f 69 3e 0a 20 20 3c 69 3e   data:</i>.  <i>
ec40: 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20  --</i>.  <i>--  
ec50: 20 20 20 61 70 70 6c 65 20 20 20 20 20 20 20 7c     apple       |
ec60: 20 20 2a 20 20 7c 20 20 31 20 20 7c 20 20 31 3c    *  |  1  |  1<
ec70: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 20 20  /i>.  <i>--     
ec80: 61 70 70 6c 65 20 20 20 20 20 20 20 7c 20 20 30  apple       |  0
ec90: 20 20 7c 20 20 31 20 20 7c 20 20 31 3c 2f 69 3e    |  1  |  1</i>
eca0: 0a 20 20 3c 69 3e 2d 2d 20 20 20 20 20 62 61 6e  .  <i>--     ban
ecb0: 61 6e 61 20 20 20 20 20 20 7c 20 20 2a 20 20 7c  ana      |  *  |
ecc0: 20 20 32 20 20 7c 20 20 32 3c 2f 69 3e 0a 20 20    2  |  2</i>.  
ecd0: 3c 69 3e 2d 2d 20 20 20 20 20 62 61 6e 61 6e 61  <i>--     banana
ece0: 20 20 20 20 20 20 7c 20 20 30 20 20 7c 20 20 32        |  0  |  2
ecf0: 20 20 7c 20 20 32 3c 2f 69 3e 0a 20 20 3c 69 3e    |  2</i>.  <i>
ed00: 2d 2d 20 20 20 20 20 63 68 65 72 72 79 20 20 20  --     cherry   
ed10: 20 20 20 7c 20 20 2a 20 20 7c 20 20 33 20 20 7c     |  *  |  3  |
ed20: 20 20 33 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20    3</i>.  <i>-- 
ed30: 20 20 20 20 63 68 65 72 72 79 20 20 20 20 20 20      cherry      
ed40: 7c 20 20 30 20 20 7c 20 20 31 20 20 7c 20 20 31  |  0  |  1  |  1
ed50: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 20  </i>.  <i>--    
ed60: 20 63 68 65 72 72 79 20 20 20 20 20 20 7c 20 20   cherry      |  
ed70: 31 20 20 7c 20 20 32 20 20 7c 20 20 32 3c 2f 69  1  |  2  |  2</i
ed80: 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 20 20 64 61  >.  <i>--     da
ed90: 74 65 20 20 20 20 20 20 20 20 7c 20 20 2a 20 20  te        |  *  
eda0: 7c 20 20 31 20 20 7c 20 20 32 3c 2f 69 3e 0a 20  |  1  |  2</i>. 
edb0: 20 3c 69 3e 2d 2d 20 20 20 20 20 64 61 74 65 20   <i>--     date 
edc0: 20 20 20 20 20 20 20 7c 20 20 30 20 20 7c 20 20         |  0  |  
edd0: 31 20 20 7c 20 20 32 3c 2f 69 3e 0a 20 20 3c 69  1  |  2</i>.  <i
ede0: 3e 2d 2d 20 20 20 20 20 65 6c 64 65 72 62 65 72  >--     elderber
edf0: 72 79 20 20 7c 20 20 2a 20 20 7c 20 20 31 20 20  ry  |  *  |  1  
ee00: 7c 20 20 32 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  |  2</i>.  <i>--
ee10: 20 20 20 20 20 65 6c 64 65 72 62 65 72 72 79 20       elderberry 
ee20: 20 7c 20 20 31 20 20 7c 20 20 31 20 20 7c 20 20   |  1  |  1  |  
ee30: 31 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20  1</i>.  <i>--   
ee40: 20 20 65 6c 64 65 72 62 65 72 72 79 20 20 7c 20    elderberry  | 
ee50: 20 31 20 20 7c 20 20 31 20 20 7c 20 20 31 3c 2f   1  |  1  |  1</
ee60: 69 3e 0a 20 20 3c 69 3e 2d 2d 3c 2f 69 3e 0a 20  i>.  <i>--</i>. 
ee70: 20 53 45 4c 45 43 54 20 74 65 72 6d 2c 20 63 6f   SELECT term, co
ee80: 6c 2c 20 64 6f 63 75 6d 65 6e 74 73 2c 20 6f 63  l, documents, oc
ee90: 63 75 72 72 65 6e 63 65 73 20 46 52 4f 4d 20 66  currences FROM f
eea0: 74 5f 74 65 72 6d 73 3b 0a 3c 2f 63 6f 64 65 62  t_terms;.</codeb
eeb0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 49 6e 20  lock>..<p>.  In 
eec0: 74 68 65 20 65 78 61 6d 70 6c 65 2c 20 74 68 65  the example, the
eed0: 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 22   values in the "
eee0: 74 65 72 6d 22 20 63 6f 6c 75 6d 6e 20 61 72 65  term" column are
eef0: 20 61 6c 6c 20 6c 6f 77 65 72 20 63 61 73 65 2c   all lower case,
ef00: 20 0a 20 20 65 76 65 6e 20 74 68 6f 75 67 68 20   .  even though 
ef10: 74 68 65 79 20 77 65 72 65 20 69 6e 73 65 72 74  they were insert
ef20: 65 64 20 69 6e 74 6f 20 74 61 62 6c 65 20 22 66  ed into table "f
ef30: 74 22 20 69 6e 20 6d 69 78 65 64 20 63 61 73 65  t" in mixed case
ef40: 2e 20 54 68 69 73 20 69 73 20 62 65 63 61 75 73  . This is becaus
ef50: 65 0a 20 20 61 6e 20 66 74 73 34 61 75 78 20 74  e.  an fts4aux t
ef60: 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 68  able contains th
ef70: 65 20 74 65 72 6d 73 20 61 73 20 65 78 74 72 61  e terms as extra
ef80: 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 64 6f  cted from the do
ef90: 63 75 6d 65 6e 74 20 74 65 78 74 0a 20 20 62 79  cument text.  by
efa0: 20 74 68 65 20 5b 74 6f 6b 65 6e 69 7a 65 72 5d   the [tokenizer]
efb0: 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20  . In this case, 
efc0: 73 69 6e 63 65 20 74 61 62 6c 65 20 22 66 74 22  since table "ft"
efd0: 20 75 73 65 73 20 74 68 65 20 0a 20 20 5b 74 6f   uses the .  [to
efe0: 6b 65 6e 69 7a 65 72 7c 73 69 6d 70 6c 65 20 74  kenizer|simple t
eff0: 6f 6b 65 6e 69 7a 65 72 5d 2c 20 74 68 69 73 20  okenizer], this 
f000: 6d 65 61 6e 73 20 61 6c 6c 20 74 65 72 6d 73 20  means all terms 
f010: 68 61 76 65 20 62 65 65 6e 20 66 6f 6c 64 65 64  have been folded
f020: 20 74 6f 0a 20 20 6c 6f 77 65 72 20 63 61 73 65   to.  lower case
f030: 2e 20 41 6c 73 6f 2c 20 74 68 65 72 65 20 69 73  . Also, there is
f040: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 29 20 6e   (for example) n
f050: 6f 20 72 6f 77 20 77 69 74 68 20 63 6f 6c 75 6d  o row with colum
f060: 6e 20 22 74 65 72 6d 22 0a 20 20 73 65 74 20 74  n "term".  set t
f070: 6f 20 22 61 70 70 6c 65 22 20 61 6e 64 20 63 6f  o "apple" and co
f080: 6c 75 6d 6e 20 22 63 6f 6c 22 20 73 65 74 20 74  lumn "col" set t
f090: 6f 20 31 2e 20 53 69 6e 63 65 20 74 68 65 72 65  o 1. Since there
f0a0: 20 61 72 65 20 6e 6f 20 69 6e 73 74 61 6e 63 65   are no instance
f0b0: 73 0a 20 20 6f 66 20 74 68 65 20 74 65 72 6d 20  s.  of the term 
f0c0: 22 61 70 70 6c 65 22 20 69 6e 20 63 6f 6c 75 6d  "apple" in colum
f0d0: 6e 20 31 2c 20 6e 6f 20 72 6f 77 20 69 73 20 70  n 1, no row is p
f0e0: 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 66 74  resent in the ft
f0f0: 73 34 61 75 78 20 74 61 62 6c 65 2e 0a 0a 3c 70  s4aux table...<p
f100: 3e 0a 20 20 44 75 72 69 6e 67 20 61 20 74 72 61  >.  During a tra
f110: 6e 73 61 63 74 69 6f 6e 2c 20 73 6f 6d 65 20 6f  nsaction, some o
f120: 66 20 74 68 65 20 64 61 74 61 20 77 72 69 74 74  f the data writt
f130: 65 6e 20 74 6f 20 61 6e 20 46 54 53 20 74 61 62  en to an FTS tab
f140: 6c 65 20 6d 61 79 20 62 65 20 0a 20 20 63 61 63  le may be .  cac
f150: 68 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 61 6e  hed in memory an
f160: 64 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65  d written to the
f170: 20 64 61 74 61 62 61 73 65 20 6f 6e 6c 79 20 77   database only w
f180: 68 65 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74  hen the transact
f190: 69 6f 6e 20 69 73 20 0a 20 20 63 6f 6d 6d 69 74  ion is .  commit
f1a0: 74 65 64 2e 20 48 6f 77 65 76 65 72 20 74 68 65  ted. However the
f1b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f1c0: 6f 66 20 74 68 65 20 66 74 73 34 61 75 78 20 6d  of the fts4aux m
f1d0: 6f 64 75 6c 65 20 69 73 20 6f 6e 6c 79 20 61 62  odule is only ab
f1e0: 6c 65 20 0a 20 20 74 6f 20 72 65 61 64 20 64 61  le .  to read da
f1f0: 74 61 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61  ta from the data
f200: 62 61 73 65 2e 20 49 6e 20 70 72 61 63 74 69 63  base. In practic
f210: 65 20 74 68 69 73 20 6d 65 61 6e 73 20 74 68 61  e this means tha
f220: 74 20 69 66 20 61 6e 20 66 74 73 34 61 75 78 20  t if an fts4aux 
f230: 0a 20 20 74 61 62 6c 65 20 69 73 20 71 75 65 72  .  table is quer
f240: 69 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ied from within 
f250: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 6e  a transaction in
f260: 20 77 68 69 63 68 20 74 68 65 20 61 73 73 6f 63   which the assoc
f270: 69 61 74 65 64 20 0a 20 20 46 54 53 20 74 61 62  iated .  FTS tab
f280: 6c 65 20 68 61 73 20 62 65 65 6e 20 6d 6f 64 69  le has been modi
f290: 66 69 65 64 2c 20 74 68 65 20 72 65 73 75 6c 74  fied, the result
f2a0: 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 61  s of the query a
f2b0: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 72 65 66  re likely to ref
f2c0: 6c 65 63 74 20 0a 20 20 6f 6e 6c 79 20 61 20 28  lect .  only a (
f2d0: 70 6f 73 73 69 62 6c 79 20 65 6d 70 74 79 29 20  possibly empty) 
f2e0: 73 75 62 73 65 74 20 6f 66 20 74 68 65 20 63 68  subset of the ch
f2f0: 61 6e 67 65 73 20 6d 61 64 65 2e 0a 0a 3c 68 31  anges made...<h1
f300: 20 69 64 3d 66 74 73 34 5f 6f 70 74 69 6f 6e 73   id=fts4_options
f310: 20 74 61 67 73 3d 22 46 54 53 34 20 6f 70 74 69   tags="FTS4 opti
f320: 6f 6e 73 22 3e 46 54 53 34 20 4f 70 74 69 6f 6e  ons">FTS4 Option
f330: 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20 49 66  s</h1>..<p>.  If
f340: 20 74 68 65 20 22 43 52 45 41 54 45 20 56 49 52   the "CREATE VIR
f350: 54 55 41 4c 20 54 41 42 4c 45 22 20 73 74 61 74  TUAL TABLE" stat
f360: 65 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ement specifies 
f370: 6d 6f 64 75 6c 65 20 46 54 53 34 20 28 6e 6f 74  module FTS4 (not
f380: 20 46 54 53 33 29 2c 20 0a 20 20 74 68 65 6e 20   FTS3), .  then 
f390: 73 70 65 63 69 61 6c 20 64 69 72 65 63 74 69 76  special directiv
f3a0: 65 73 20 2d 20 46 54 53 34 20 6f 70 74 69 6f 6e  es - FTS4 option
f3b0: 73 20 2d 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  s - similar to t
f3c0: 68 65 20 22 74 6f 6b 65 6e 69 7a 65 3d 2a 22 20  he "tokenize=*" 
f3d0: 6f 70 74 69 6f 6e 0a 20 20 6d 61 79 20 61 6c 73  option.  may als
f3e0: 6f 20 61 70 70 65 61 72 20 69 6e 20 70 6c 61 63  o appear in plac
f3f0: 65 20 6f 66 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  e of column name
f400: 73 2e 20 41 6e 20 46 54 53 34 20 6f 70 74 69 6f  s. An FTS4 optio
f410: 6e 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74 68  n consists of th
f420: 65 0a 20 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 2c  e.  option name,
f430: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e 20   followed by an 
f440: 22 3d 22 20 63 68 61 72 61 63 74 65 72 2c 20 66  "=" character, f
f450: 6f 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 6f  ollowed by the o
f460: 70 74 69 6f 6e 20 76 61 6c 75 65 2e 0a 20 20 54  ption value..  T
f470: 68 65 20 6f 70 74 69 6f 6e 20 76 61 6c 75 65 20  he option value 
f480: 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
f490: 65 20 65 6e 63 6c 6f 73 65 64 20 69 6e 20 73 69  e enclosed in si
f4a0: 6e 67 6c 65 20 6f 72 20 64 6f 75 62 6c 65 20 71  ngle or double q
f4b0: 75 6f 74 65 73 2c 20 77 69 74 68 0a 20 20 65 6d  uotes, with.  em
f4c0: 62 65 64 64 65 64 20 71 75 6f 74 65 20 63 68 61  bedded quote cha
f4d0: 72 61 63 74 65 72 73 20 65 73 63 61 70 65 64 20  racters escaped 
f4e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 77 61 79 20  in the same way 
f4f0: 61 73 20 66 6f 72 20 53 51 4c 20 6c 69 74 65 72  as for SQL liter
f500: 61 6c 73 2e 20 54 68 65 72 65 0a 20 20 6d 61 79  als. There.  may
f510: 20 6e 6f 74 20 62 65 20 77 68 69 74 65 73 70 61   not be whitespa
f520: 63 65 20 6f 6e 20 65 69 74 68 65 72 20 73 69 64  ce on either sid
f530: 65 20 6f 66 20 74 68 65 20 22 3d 22 20 63 68 61  e of the "=" cha
f540: 72 61 63 74 65 72 2e 20 46 6f 72 20 65 78 61 6d  racter. For exam
f550: 70 6c 65 2c 0a 20 20 74 6f 20 63 72 65 61 74 65  ple,.  to create
f560: 20 61 6e 20 46 54 53 34 20 74 61 62 6c 65 20 77   an FTS4 table w
f570: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ith the value of
f580: 20 6f 70 74 69 6f 6e 20 22 6d 61 74 63 68 69 6e   option "matchin
f590: 66 6f 22 20 73 65 74 20 74 6f 20 22 66 74 73 33  fo" set to "fts3
f5a0: 22 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ":..<codeblock>.
f5b0: 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61    <i>-- Create a
f5c0: 20 72 65 64 75 63 65 64 2d 66 6f 6f 74 70 72 69   reduced-footpri
f5d0: 6e 74 20 46 54 53 34 20 74 61 62 6c 65 2e 3c 2f  nt FTS4 table.</
f5e0: 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
f5f0: 55 41 4c 20 54 41 42 4c 45 20 70 61 70 65 72 73  UAL TABLE papers
f600: 20 55 53 49 4e 47 20 66 74 73 34 28 61 75 74 68   USING fts4(auth
f610: 6f 72 2c 20 64 6f 63 75 6d 65 6e 74 2c 20 6d 61  or, document, ma
f620: 74 63 68 69 6e 66 6f 3d 66 74 73 33 29 3b 0a 3c  tchinfo=fts3);.<
f630: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
f640: 0a 20 20 46 54 53 34 20 63 75 72 72 65 6e 74 6c  .  FTS4 currentl
f650: 79 20 73 75 70 70 6f 72 74 73 20 74 68 65 20 66  y supports the f
f660: 6f 6c 6c 6f 77 69 6e 67 20 6f 70 74 69 6f 6e 73  ollowing options
f670: 3a 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65  :..<table stripe
f680: 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 4f  d=1>.  <tr><th>O
f690: 70 74 69 6f 6e 3c 74 68 3e 49 6e 74 65 72 70 72  ption<th>Interpr
f6a0: 65 74 61 74 69 6f 6e 0a 20 20 3c 74 72 3e 3c 74  etation.  <tr><t
f6b0: 64 3e 63 6f 6d 70 72 65 73 73 3c 74 64 3e 0a 20  d>compress<td>. 
f6c0: 20 20 20 5e 54 68 65 20 63 6f 6d 70 72 65 73 73     ^The compress
f6d0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
f6e0: 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 63  to specify the c
f6f0: 6f 6d 70 72 65 73 73 20 66 75 6e 63 74 69 6f 6e  ompress function
f700: 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
f710: 72 20 74 6f 0a 20 20 20 20 73 70 65 63 69 66 79  r to.    specify
f720: 20 61 20 63 6f 6d 70 72 65 73 73 20 66 75 6e 63   a compress func
f730: 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 61 6c 73  tion without als
f740: 6f 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  o specifying an 
f750: 75 6e 63 6f 6d 70 72 65 73 73 0a 20 20 20 20 66  uncompress.    f
f760: 75 6e 63 74 69 6f 6e 2e 20 5b 66 74 73 34 20 63  unction. [fts4 c
f770: 6f 6d 70 72 65 73 73 20 6f 70 74 69 6f 6e 7c 53  ompress option|S
f780: 65 65 20 62 65 6c 6f 77 5d 20 66 6f 72 20 64 65  ee below] for de
f790: 74 61 69 6c 73 2e 0a 0a 20 20 3c 74 72 3e 3c 74  tails...  <tr><t
f7a0: 64 3e 63 6f 6e 74 65 6e 74 3c 74 64 3e 0a 20 20  d>content<td>.  
f7b0: 20 20 5e 54 68 65 20 63 6f 6e 74 65 6e 74 20 61    ^The content a
f7c0: 6c 6c 6f 77 73 20 74 68 65 20 74 65 78 74 20 62  llows the text b
f7d0: 65 69 6e 67 20 69 6e 64 65 78 65 64 20 74 6f 20  eing indexed to 
f7e0: 62 65 0a 20 20 20 20 73 74 6f 72 65 64 20 69 6e  be.    stored in
f7f0: 20 61 20 73 65 70 61 72 61 74 65 20 74 61 62 6c   a separate tabl
f800: 65 20 64 69 73 74 69 6e 63 74 20 66 72 6f 6d 20  e distinct from 
f810: 74 68 65 20 46 54 53 34 20 74 61 62 6c 65 2c 0a  the FTS4 table,.
f820: 20 20 20 20 6f 72 20 65 76 65 6e 20 6f 75 74 73      or even outs
f830: 69 64 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 0a  ide of SQLite...
f840: 20 20 3c 74 72 3e 3c 74 64 3e 6c 61 6e 67 75 61    <tr><td>langua
f850: 67 65 69 64 3c 74 64 3e 0a 20 20 20 20 5e 54 68  geid<td>.    ^Th
f860: 65 20 6c 61 6e 67 75 61 67 65 69 64 20 6f 70 74  e languageid opt
f870: 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 46  ion causes the F
f880: 54 53 34 20 74 61 62 6c 65 20 74 6f 20 68 61 76  TS4 table to hav
f890: 65 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  e an additional 
f8a0: 68 69 64 64 65 6e 0a 20 20 20 20 69 6e 74 65 67  hidden.    integ
f8b0: 65 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  er column that i
f8c0: 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 6c 61  dentifies the la
f8d0: 6e 67 75 61 67 65 20 6f 66 20 74 68 65 20 74 65  nguage of the te
f8e0: 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 0a  xt contained in.
f8f0: 20 20 20 20 65 61 63 68 20 72 6f 77 2e 20 20 54      each row.  T
f900: 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 6c 61  he use of the la
f910: 6e 67 75 61 67 65 69 64 20 6f 70 74 69 6f 6e 20  nguageid option 
f920: 61 6c 6c 6f 77 73 20 74 68 65 20 73 61 6d 65 20  allows the same 
f930: 46 54 53 34 20 74 61 62 6c 65 0a 20 20 20 20 74  FTS4 table.    t
f940: 6f 20 68 6f 6c 64 20 74 65 78 74 20 69 6e 20 6d  o hold text in m
f950: 75 6c 74 69 70 6c 65 20 6c 61 6e 67 75 61 67 65  ultiple language
f960: 73 20 6f 72 20 73 63 72 69 70 74 73 2c 20 65 61  s or scripts, ea
f970: 63 68 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ch with differen
f980: 74 20 74 6f 6b 65 6e 69 7a 65 72 0a 20 20 20 20  t tokenizer.    
f990: 72 75 6c 65 73 2c 20 61 6e 64 20 74 6f 20 71 75  rules, and to qu
f9a0: 65 72 79 20 65 61 63 68 20 6c 61 6e 67 75 61 67  ery each languag
f9b0: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
f9c0: 6f 66 20 74 68 65 20 6f 74 68 65 72 73 2e 0a 20  of the others.. 
f9d0: 20 20 20 0a 20 20 3c 74 72 3e 3c 74 64 3e 6d 61     .  <tr><td>ma
f9e0: 74 63 68 69 6e 66 6f 3c 74 64 3e 20 0a 20 20 20  tchinfo<td> .   
f9f0: 20 57 68 65 6e 20 73 65 74 20 74 6f 20 74 68 65   When set to the
fa00: 20 76 61 6c 75 65 20 22 66 74 73 33 22 2c 20 74   value "fts3", t
fa10: 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 6f 70 74  he matchinfo opt
fa20: 69 6f 6e 20 72 65 64 75 63 65 73 20 74 68 65 20  ion reduces the 
fa30: 61 6d 6f 75 6e 74 20 6f 66 0a 20 20 20 20 69 6e  amount of.    in
fa40: 66 6f 72 6d 61 74 69 6f 6e 20 73 74 6f 72 65 64  formation stored
fa50: 20 62 79 20 46 54 53 34 20 77 69 74 68 20 74 68   by FTS4 with th
fa60: 65 20 63 6f 6e 73 65 71 75 65 6e 63 65 20 74 68  e consequence th
fa70: 61 74 20 74 68 65 20 22 6c 22 20 6f 70 74 69 6f  at the "l" optio
fa80: 6e 20 6f 66 0a 20 20 20 20 5b 6d 61 74 63 68 69  n of.    [matchi
fa90: 6e 66 6f 28 29 5d 20 69 73 20 6e 6f 20 6c 6f 6e  nfo()] is no lon
faa0: 67 65 72 20 61 76 61 69 6c 61 62 6c 65 2e 0a 0a  ger available...
fab0: 20 20 3c 74 72 3e 3c 74 64 3e 6f 72 64 65 72 3c    <tr><td>order<
fac0: 74 64 3e 0a 20 20 20 20 3c 74 63 6c 3e 68 64 5f  td>.    <tcl>hd_
fad0: 66 72 61 67 6d 65 6e 74 20 66 74 73 34 6f 72 64  fragment fts4ord
fae0: 65 72 20 7b 46 54 53 34 20 6f 72 64 65 72 20 6f  er {FTS4 order o
faf0: 70 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 20 20 20  ption}</tcl>.   
fb00: 20 5e 54 68 65 20 22 6f 72 64 65 72 22 20 6f 70   ^The "order" op
fb10: 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
fb20: 74 6f 20 65 69 74 68 65 72 20 22 44 45 53 43 22  to either "DESC"
fb30: 20 6f 72 20 22 41 53 43 22 20 28 69 6e 20 75 70   or "ASC" (in up
fb40: 70 65 72 20 6f 72 0a 20 20 20 20 6c 6f 77 65 72  per or.    lower
fb50: 20 63 61 73 65 29 2e 20 5e 49 66 20 69 74 20 69   case). ^If it i
fb60: 73 20 73 65 74 20 74 6f 20 22 44 45 53 43 22 2c  s set to "DESC",
fb70: 20 74 68 65 6e 20 46 54 53 34 20 73 74 6f 72 65   then FTS4 store
fb80: 73 20 69 74 73 20 64 61 74 61 20 69 6e 20 73 75  s its data in su
fb90: 63 68 0a 20 20 20 20 61 20 77 61 79 20 61 73 20  ch.    a way as 
fba0: 74 6f 20 6f 70 74 69 6d 69 7a 65 20 72 65 74 75  to optimize retu
fbb0: 72 6e 69 6e 67 20 72 65 73 75 6c 74 73 20 69 6e  rning results in
fbc0: 20 64 65 73 63 65 6e 64 69 6e 67 20 6f 72 64 65   descending orde
fbd0: 72 20 62 79 20 64 6f 63 69 64 2e 0a 20 20 20 20  r by docid..    
fbe0: 5e 49 66 20 69 74 20 69 73 20 73 65 74 20 74 6f  ^If it is set to
fbf0: 20 22 41 53 43 22 20 28 74 68 65 20 64 65 66 61   "ASC" (the defa
fc00: 75 6c 74 29 2c 20 74 68 65 6e 20 74 68 65 20 64  ult), then the d
fc10: 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 61  ata structures a
fc20: 72 65 20 0a 20 20 20 20 6f 70 74 69 6d 69 7a 65  re .    optimize
fc30: 64 20 66 6f 72 20 72 65 74 75 72 6e 69 6e 67 20  d for returning 
fc40: 72 65 73 75 6c 74 73 20 69 6e 20 61 73 63 65 6e  results in ascen
fc50: 64 69 6e 67 20 6f 72 64 65 72 20 62 79 20 64 6f  ding order by do
fc60: 63 69 64 2e 20 20 5e 49 6e 20 6f 74 68 65 72 0a  cid.  ^In other.
fc70: 20 20 20 20 77 6f 72 64 73 2c 20 69 66 20 6d 61      words, if ma
fc80: 6e 79 20 6f 66 20 74 68 65 20 71 75 65 72 69 65  ny of the querie
fc90: 73 20 72 75 6e 20 61 67 61 69 6e 73 74 20 74 68  s run against th
fca0: 65 20 46 54 53 34 20 74 61 62 6c 65 20 75 73 65  e FTS4 table use
fcb0: 20 22 4f 52 44 45 52 20 42 59 0a 20 20 20 20 64   "ORDER BY.    d
fcc0: 6f 63 69 64 20 44 45 53 43 22 2c 20 74 68 65 6e  ocid DESC", then
fcd0: 20 69 74 20 6d 61 79 20 69 6d 70 72 6f 76 65 20   it may improve 
fce0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 6f 20 61  performance to a
fcf0: 64 64 20 74 68 65 20 22 6f 72 64 65 72 3d 64 65  dd the "order=de
fd00: 73 63 22 20 0a 20 20 20 20 6f 70 74 69 6f 6e 20  sc" .    option 
fd10: 74 6f 20 74 68 65 20 43 52 45 41 54 45 20 56 49  to the CREATE VI
fd20: 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74  RTUAL TABLE stat
fd30: 65 6d 65 6e 74 2e 0a 0a 20 20 3c 74 72 3e 3c 74  ement...  <tr><t
fd40: 64 3e 70 72 65 66 69 78 3c 74 64 3e 0a 20 20 20  d>prefix<td>.   
fd50: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79   This option may
fd60: 20 62 65 20 73 65 74 20 74 6f 20 61 20 63 6f 6d   be set to a com
fd70: 6d 61 2d 73 65 70 61 72 61 74 65 64 20 6c 69 73  ma-separated lis
fd80: 74 20 6f 66 20 70 6f 73 69 74 69 76 65 20 6e 6f  t of positive no
fd90: 6e 2d 7a 65 72 6f 20 0a 20 20 20 20 69 6e 74 65  n-zero .    inte
fda0: 67 65 72 73 2e 20 46 6f 72 20 65 61 63 68 20 69  gers. For each i
fdb0: 6e 74 65 67 65 72 20 4e 20 69 6e 20 74 68 65 20  nteger N in the 
fdc0: 6c 69 73 74 2c 20 61 20 73 65 70 61 72 61 74 65  list, a separate
fdd0: 20 69 6e 64 65 78 20 69 73 20 63 72 65 61 74 65   index is create
fde0: 64 0a 20 20 20 20 69 6e 20 74 68 65 20 64 61 74  d.    in the dat
fdf0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 6f 70  abase file to op
fe00: 74 69 6d 69 7a 65 20 5b 70 72 65 66 69 78 20 71  timize [prefix q
fe10: 75 65 72 69 65 73 5d 20 77 68 65 72 65 0a 20 20  ueries] where.  
fe20: 20 20 74 68 65 20 71 75 65 72 79 20 74 65 72 6d    the query term
fe30: 20 69 73 20 4e 20 62 79 74 65 73 20 69 6e 20 6c   is N bytes in l
fe40: 65 6e 67 74 68 2c 20 6e 6f 74 20 69 6e 63 6c 75  ength, not inclu
fe50: 64 69 6e 67 20 74 68 65 20 27 2a 27 20 63 68 61  ding the '*' cha
fe60: 72 61 63 74 65 72 2c 0a 20 20 20 20 77 68 65 6e  racter,.    when
fe70: 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
fe80: 54 46 2d 38 2e 20 5b 66 74 73 34 20 70 72 65 66  TF-8. [fts4 pref
fe90: 69 78 20 6f 70 74 69 6f 6e 7c 53 65 65 20 62 65  ix option|See be
fea0: 6c 6f 77 5d 20 66 6f 72 20 64 65 74 61 69 6c 73  low] for details
feb0: 2e 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e 75 6e 63  ...  <tr><td>unc
fec0: 6f 6d 70 72 65 73 73 3c 74 64 3e 0a 20 20 20 20  ompress<td>.    
fed0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
fee0: 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
fef0: 68 65 20 75 6e 63 6f 6d 70 72 65 73 73 20 66 75  he uncompress fu
ff00: 6e 63 74 69 6f 6e 2e 20 49 74 20 69 73 20 61 6e  nction. It is an
ff10: 20 65 72 72 6f 72 20 74 6f 0a 20 20 20 20 73 70   error to.    sp
ff20: 65 63 69 66 79 20 61 6e 20 75 6e 63 6f 6d 70 72  ecify an uncompr
ff30: 65 73 73 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ess function wit
ff40: 68 6f 75 74 20 61 6c 73 6f 20 73 70 65 63 69 66  hout also specif
ff50: 79 69 6e 67 20 61 20 63 6f 6d 70 72 65 73 73 0a  ying a compress.
ff60: 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 20 5b 66      function. [f
ff70: 74 73 34 20 63 6f 6d 70 72 65 73 73 20 6f 70 74  ts4 compress opt
ff80: 69 6f 6e 7c 53 65 65 20 62 65 6c 6f 77 5d 20 66  ion|See below] f
ff90: 6f 72 20 64 65 74 61 69 6c 73 2e 0a 3c 2f 74 61  or details..</ta
ffa0: 62 6c 65 3e 0a 0a 3c 70 3e 0a 20 20 57 68 65 6e  ble>..<p>.  When
ffb0: 20 75 73 69 6e 67 20 46 54 53 34 2c 20 73 70 65   using FTS4, spe
ffc0: 63 69 66 79 69 6e 67 20 61 20 63 6f 6c 75 6d 6e  cifying a column
ffd0: 20 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61   name that conta
ffe0: 69 6e 73 20 61 6e 20 22 3d 22 20 63 68 61 72 61  ins an "=" chara
fff0: 63 74 65 72 0a 20 20 61 6e 64 20 69 73 20 6e 6f  cter.  and is no
10000 74 20 65 69 74 68 65 72 20 61 20 22 74 6f 6b 65  t either a "toke
10010 6e 69 7a 65 3d 2a 22 20 73 70 65 63 69 66 69 63  nize=*" specific
10020 61 74 69 6f 6e 20 6f 72 20 61 20 72 65 63 6f 67  ation or a recog
10030 6e 69 7a 65 64 20 46 54 53 34 20 6f 70 74 69 6f  nized FTS4 optio
10040 6e 0a 20 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  n.  is an error.
10050 20 57 69 74 68 20 46 54 53 33 2c 20 74 68 65 20   With FTS3, the 
10060 66 69 72 73 74 20 74 6f 6b 65 6e 20 69 6e 20 74  first token in t
10070 68 65 20 75 6e 72 65 63 6f 67 6e 69 7a 65 64 20  he unrecognized 
10080 64 69 72 65 63 74 69 76 65 20 69 73 20 0a 20 20  directive is .  
10090 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
100a0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 20 53 69   column name. Si
100b0 6d 69 6c 61 72 6c 79 2c 20 73 70 65 63 69 66 79  milarly, specify
100c0 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 22 74 6f  ing multiple "to
100d0 6b 65 6e 69 7a 65 3d 2a 22 0a 20 20 64 69 72 65  kenize=*".  dire
100e0 63 74 69 76 65 73 20 69 6e 20 61 20 73 69 6e 67  ctives in a sing
100f0 6c 65 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  le table declara
10100 74 69 6f 6e 20 69 73 20 61 6e 20 65 72 72 6f 72  tion is an error
10110 20 77 68 65 6e 20 75 73 69 6e 67 20 46 54 53 34   when using FTS4
10120 2c 20 77 68 65 72 65 61 73 0a 20 20 74 68 65 20  , whereas.  the 
10130 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
10140 71 75 65 6e 74 20 22 74 6f 6b 65 6e 69 7a 65 3d  quent "tokenize=
10150 2a 22 20 64 69 72 65 63 74 69 76 65 73 20 61 72  *" directives ar
10160 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
10170 20 63 6f 6c 75 6d 6e 0a 20 20 6e 61 6d 65 73 20   column.  names 
10180 62 79 20 46 54 53 33 2e 20 46 6f 72 20 65 78 61  by FTS3. For exa
10190 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
101a0 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 41 6e 20 65 72  k>.  <i>-- An er
101b0 72 6f 72 2e 20 46 54 53 34 20 64 6f 65 73 20 6e  ror. FTS4 does n
101c0 6f 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 65  ot recognize the
101d0 20 64 69 72 65 63 74 69 76 65 20 22 78 79 7a 3d   directive "xyz=
101e0 61 62 63 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41  abc".</i>.  CREA
101f0 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
10200 20 70 61 70 65 72 73 20 55 53 49 4e 47 20 66 74   papers USING ft
10210 73 34 28 61 75 74 68 6f 72 2c 20 64 6f 63 75 6d  s4(author, docum
10220 65 6e 74 2c 20 78 79 7a 3d 61 62 63 29 3b 0a 0a  ent, xyz=abc);..
10230 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61    <i>-- Create a
10240 6e 20 46 54 53 33 20 74 61 62 6c 65 20 77 69 74  n FTS3 table wit
10250 68 20 74 68 72 65 65 20 63 6f 6c 75 6d 6e 73 20  h three columns 
10260 2d 20 22 61 75 74 68 6f 72 22 2c 20 22 64 6f 63  - "author", "doc
10270 75 6d 65 6e 74 22 3c 2f 69 3e 0a 20 20 3c 69 3e  ument"</i>.  <i>
10280 2d 2d 20 61 6e 64 20 22 78 79 7a 22 2e 3c 2f 69  -- and "xyz".</i
10290 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
102a0 41 4c 20 54 41 42 4c 45 20 70 61 70 65 72 73 20  AL TABLE papers 
102b0 55 53 49 4e 47 20 66 74 73 33 28 61 75 74 68 6f  USING fts3(autho
102c0 72 2c 20 64 6f 63 75 6d 65 6e 74 2c 20 78 79 7a  r, document, xyz
102d0 3d 61 62 63 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  =abc);..  <i>-- 
102e0 41 6e 20 65 72 72 6f 72 2e 20 46 54 53 34 20 64  An error. FTS4 d
102f0 6f 65 73 20 6e 6f 74 20 61 6c 6c 6f 77 20 6d 75  oes not allow mu
10300 6c 74 69 70 6c 65 20 74 6f 6b 65 6e 69 7a 65 3d  ltiple tokenize=
10310 2a 20 64 69 72 65 63 74 69 76 65 73 3c 2f 69 3e  * directives</i>
10320 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
10330 4c 20 54 41 42 4c 45 20 70 61 70 65 72 73 20 55  L TABLE papers U
10340 53 49 4e 47 20 66 74 73 34 28 74 6f 6b 65 6e 69  SING fts4(tokeni
10350 7a 65 3d 70 6f 72 74 65 72 2c 20 74 6f 6b 65 6e  ze=porter, token
10360 69 7a 65 3d 73 69 6d 70 6c 65 29 3b 0a 0a 20 20  ize=simple);..  
10370 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20  <i>-- Create an 
10380 46 54 53 33 20 74 61 62 6c 65 20 77 69 74 68 20  FTS3 table with 
10390 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
103a0 6e 61 6d 65 64 20 22 74 6f 6b 65 6e 69 7a 65 22  named "tokenize"
103b0 2e 20 54 68 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  . The</i>.  <i>-
103c0 2d 20 74 61 62 6c 65 20 75 73 65 73 20 74 68 65  - table uses the
103d0 20 22 70 6f 72 74 65 72 22 20 74 6f 6b 65 6e 69   "porter" tokeni
103e0 7a 65 72 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  zer.</i>.  CREAT
103f0 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
10400 70 61 70 65 72 73 20 55 53 49 4e 47 20 66 74 73  papers USING fts
10410 33 28 74 6f 6b 65 6e 69 7a 65 3d 70 6f 72 74 65  3(tokenize=porte
10420 72 2c 20 74 6f 6b 65 6e 69 7a 65 3d 73 69 6d 70  r, tokenize=simp
10430 6c 65 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 41 6e  le);..  <i>-- An
10440 20 65 72 72 6f 72 2e 20 43 61 6e 6e 6f 74 20 63   error. Cannot c
10450 72 65 61 74 65 20 61 20 74 61 62 6c 65 20 77 69  reate a table wi
10460 74 68 20 74 77 6f 20 63 6f 6c 75 6d 6e 73 20 6e  th two columns n
10470 61 6d 65 64 20 22 74 6f 6b 65 6e 69 7a 65 22 2e  amed "tokenize".
10480 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
10490 52 54 55 41 4c 20 54 41 42 4c 45 20 70 61 70 65  RTUAL TABLE pape
104a0 72 73 20 55 53 49 4e 47 20 66 74 73 33 28 74 6f  rs USING fts3(to
104b0 6b 65 6e 69 7a 65 3d 70 6f 72 74 65 72 2c 20 74  kenize=porter, t
104c0 6f 6b 65 6e 69 7a 65 3d 73 69 6d 70 6c 65 2c 20  okenize=simple, 
104d0 74 6f 6b 65 6e 69 7a 65 3d 69 63 75 29 3b 0a 3c  tokenize=icu);.<
104e0 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 74 63  /codeblock>..<tc
104f0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 2a 66  l>hd_fragment *f
10500 74 73 34 63 6f 6d 70 72 65 73 73 69 6f 6e 20 7b  ts4compression {
10510 63 6f 6d 70 72 65 73 73 65 64 20 46 54 53 34 20  compressed FTS4 
10520 63 6f 6e 74 65 6e 74 7d 3c 2f 74 63 6c 3e 0a 3c  content}</tcl>.<
10530 68 32 20 74 61 67 73 3d 22 66 74 73 34 20 63 6f  h2 tags="fts4 co
10540 6d 70 72 65 73 73 20 6f 70 74 69 6f 6e 22 3e 54  mpress option">T
10550 68 65 20 63 6f 6d 70 72 65 73 73 3d 20 61 6e 64  he compress= and
10560 20 75 6e 63 6f 6d 70 72 65 73 73 3d 20 6f 70 74   uncompress= opt
10570 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20  ions</h2>..<p>. 
10580 20 54 68 65 20 63 6f 6d 70 72 65 73 73 20 61 6e   The compress an
10590 64 20 75 6e 63 6f 6d 70 72 65 73 73 20 6f 70 74  d uncompress opt
105a0 69 6f 6e 73 20 61 6c 6c 6f 77 20 46 54 53 34 20  ions allow FTS4 
105b0 63 6f 6e 74 65 6e 74 20 74 6f 20 62 65 20 73 74  content to be st
105c0 6f 72 65 64 20 69 6e 0a 20 20 74 68 65 20 64 61  ored in.  the da
105d0 74 61 62 61 73 65 20 69 6e 20 61 20 63 6f 6d 70  tabase in a comp
105e0 72 65 73 73 65 64 20 66 6f 72 6d 2e 20 42 6f 74  ressed form. Bot
105f0 68 20 6f 70 74 69 6f 6e 73 20 73 68 6f 75 6c 64  h options should
10600 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 6e   be set to the n
10610 61 6d 65 0a 20 20 6f 66 20 61 6e 20 53 51 4c 20  ame.  of an SQL 
10620 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 20  scalar function 
10630 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
10640 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
10650 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 20 20 74  _function()].  t
10660 68 61 74 20 61 63 63 65 70 74 73 20 61 20 73 69  hat accepts a si
10670 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 2e 20 0a  ngle argument. .
10680 0a 3c 70 3e 0a 20 20 54 68 65 20 63 6f 6d 70 72  .<p>.  The compr
10690 65 73 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ess function sho
106a0 75 6c 64 20 72 65 74 75 72 6e 20 61 20 63 6f 6d  uld return a com
106b0 70 72 65 73 73 65 64 20 76 65 72 73 69 6f 6e 20  pressed version 
106c0 6f 66 20 74 68 65 20 76 61 6c 75 65 20 0a 20 20  of the value .  
106d0 70 61 73 73 65 64 20 74 6f 20 69 74 20 61 73 20  passed to it as 
106e0 61 6e 20 61 72 67 75 6d 65 6e 74 2e 20 45 61 63  an argument. Eac
106f0 68 20 74 69 6d 65 20 64 61 74 61 20 69 73 20 77  h time data is w
10700 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20 46 54  ritten to the FT
10710 53 34 20 74 61 62 6c 65 2c 20 0a 20 20 65 61 63  S4 table, .  eac
10720 68 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69  h column value i
10730 73 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  s passed to the 
10740 63 6f 6d 70 72 65 73 73 20 66 75 6e 63 74 69 6f  compress functio
10750 6e 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  n and the result
10760 20 76 61 6c 75 65 20 0a 20 20 73 74 6f 72 65 64   value .  stored
10770 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
10780 2e 20 54 68 65 20 63 6f 6d 70 72 65 73 73 20 66  . The compress f
10790 75 6e 63 74 69 6f 6e 20 6d 61 79 20 72 65 74 75  unction may retu
107a0 72 6e 20 61 6e 79 20 74 79 70 65 20 6f 66 20 53  rn any type of S
107b0 51 4c 69 74 65 20 0a 20 20 76 61 6c 75 65 20 28  QLite .  value (
107c0 62 6c 6f 62 2c 20 74 65 78 74 2c 20 72 65 61 6c  blob, text, real
107d0 2c 20 69 6e 74 65 67 65 72 20 6f 72 20 6e 75 6c  , integer or nul
107e0 6c 29 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 75  l)...<p>.  The u
107f0 6e 63 6f 6d 70 72 65 73 73 20 66 75 6e 63 74 69  ncompress functi
10800 6f 6e 20 73 68 6f 75 6c 64 20 75 6e 63 6f 6d 70  on should uncomp
10810 72 65 73 73 20 64 61 74 61 20 70 72 65 76 69 6f  ress data previo
10820 75 73 6c 79 20 63 6f 6d 70 72 65 73 73 65 64 20  usly compressed 
10830 62 79 0a 20 20 74 68 65 20 63 6f 6d 70 72 65 73  by.  the compres
10840 73 20 66 75 6e 63 74 69 6f 6e 2e 20 49 6e 20 6f  s function. In o
10850 74 68 65 72 20 77 6f 72 64 73 2c 20 66 6f 72 20  ther words, for 
10860 61 6c 6c 20 53 51 4c 69 74 65 20 76 61 6c 75 65  all SQLite value
10870 73 20 58 2c 20 69 74 20 73 68 6f 75 6c 64 0a 20  s X, it should. 
10880 20 62 65 20 74 72 75 65 20 74 68 61 74 20 75 6e   be true that un
10890 63 6f 6d 70 72 65 73 73 28 63 6f 6d 70 72 65 73  compress(compres
108a0 73 28 58 29 29 20 65 71 75 61 6c 73 20 58 2e 20  s(X)) equals X. 
108b0 57 68 65 6e 20 64 61 74 61 20 74 68 61 74 20 68  When data that h
108c0 61 73 20 62 65 65 6e 0a 20 20 63 6f 6d 70 72 65  as been.  compre
108d0 73 73 65 64 20 62 79 20 74 68 65 20 63 6f 6d 70  ssed by the comp
108e0 72 65 73 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  ress function is
108f0 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 64   read from the d
10900 61 74 61 62 61 73 65 20 62 79 20 46 54 53 34 2c  atabase by FTS4,
10910 20 69 74 0a 20 20 69 73 20 70 61 73 73 65 64 20   it.  is passed 
10920 74 6f 20 74 68 65 20 75 6e 63 6f 6d 70 72 65 73  to the uncompres
10930 73 20 66 75 6e 63 74 69 6f 6e 20 62 65 66 6f 72  s function befor
10940 65 20 69 74 20 69 73 20 75 73 65 64 2e 0a 0a 3c  e it is used...<
10950 70 3e 0a 20 20 49 66 20 74 68 65 20 73 70 65 63  p>.  If the spec
10960 69 66 69 65 64 20 63 6f 6d 70 72 65 73 73 20 6f  ified compress o
10970 72 20 75 6e 63 6f 6d 70 72 65 73 73 20 66 75 6e  r uncompress fun
10980 63 74 69 6f 6e 73 20 64 6f 20 6e 6f 74 20 65 78  ctions do not ex
10990 69 73 74 2c 20 74 68 65 20 74 61 62 6c 65 0a 20  ist, the table. 
109a0 20 6d 61 79 20 73 74 69 6c 6c 20 62 65 20 63 72   may still be cr
109b0 65 61 74 65 64 2e 20 41 6e 20 65 72 72 6f 72 20  eated. An error 
109c0 69 73 20 6e 6f 74 20 72 65 74 75 72 6e 65 64 20  is not returned 
109d0 75 6e 74 69 6c 20 74 68 65 20 46 54 53 34 20 74  until the FTS4 t
109e0 61 62 6c 65 20 69 73 0a 20 20 72 65 61 64 20 28  able is.  read (
109f0 69 66 20 74 68 65 20 75 6e 63 6f 6d 70 72 65 73  if the uncompres
10a00 73 20 66 75 6e 63 74 69 6f 6e 20 64 6f 65 73 20  s function does 
10a10 6e 6f 74 20 65 78 69 73 74 29 20 6f 72 20 77 72  not exist) or wr
10a20 69 74 74 65 6e 20 28 69 66 20 69 74 20 69 73 20  itten (if it is 
10a30 74 68 65 20 0a 20 20 63 6f 6d 70 72 65 73 73 20  the .  compress 
10a40 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 64 6f  function that do
10a50 65 73 20 6e 6f 74 20 65 78 69 73 74 29 2e 0a 0a  es not exist)...
10a60 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
10a70 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20 46 54  >-- Create an FT
10a80 53 34 20 74 61 62 6c 65 20 74 68 61 74 20 73 74  S4 table that st
10a90 6f 72 65 73 20 64 61 74 61 20 69 6e 20 63 6f 6d  ores data in com
10aa0 70 72 65 73 73 65 64 20 66 6f 72 6d 2e 20 54 68  pressed form. Th
10ab0 69 73 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 61  is</i>.  <i>-- a
10ac0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
10ad0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
10ae0 20 7a 69 70 28 29 20 61 6e 64 20 75 6e 7a 69 70   zip() and unzip
10af0 28 29 20 68 61 76 65 20 62 65 65 6e 20 28 6f 72  () have been (or
10b00 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 77 69 6c  </i>.  <i>-- wil
10b10 6c 20 62 65 29 20 61 64 64 65 64 20 74 6f 20 74  l be) added to t
10b20 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
10b30 6c 65 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45  le.</i>.  CREATE
10b40 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 70   VIRTUAL TABLE p
10b50 61 70 65 72 73 20 55 53 49 4e 47 20 66 74 73 34  apers USING fts4
10b60 28 61 75 74 68 6f 72 2c 20 64 6f 63 75 6d 65 6e  (author, documen
10b70 74 2c 20 63 6f 6d 70 72 65 73 73 3d 7a 69 70 2c  t, compress=zip,
10b80 20 75 6e 63 6f 6d 70 72 65 73 73 3d 75 6e 7a 69   uncompress=unzi
10b90 70 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  p);.</codeblock>
10ba0 0a 0a 3c 70 3e 0a 20 20 57 68 65 6e 20 69 6d 70  ..<p>.  When imp
10bb0 6c 65 6d 65 6e 74 69 6e 67 20 74 68 65 20 63 6f  lementing the co
10bc0 6d 70 72 65 73 73 20 61 6e 64 20 75 6e 63 6f 6d  mpress and uncom
10bd0 70 72 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 20  press functions 
10be0 69 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 20  it is important 
10bf0 74 6f 0a 20 20 70 61 79 20 61 74 74 65 6e 74 69  to.  pay attenti
10c00 6f 6e 20 74 6f 20 64 61 74 61 20 74 79 70 65 73  on to data types
10c10 2e 20 53 70 65 63 69 66 69 63 61 6c 6c 79 2c 20  . Specifically, 
10c20 77 68 65 6e 20 61 20 75 73 65 72 20 72 65 61 64  when a user read
10c30 73 20 61 20 76 61 6c 75 65 20 66 72 6f 6d 0a 20  s a value from. 
10c40 20 61 20 63 6f 6d 70 72 65 73 73 65 64 20 46 54   a compressed FT
10c50 53 20 74 61 62 6c 65 2c 20 74 68 65 20 76 61 6c  S table, the val
10c60 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 46  ue returned by F
10c70 54 53 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  TS is exactly th
10c80 65 20 73 61 6d 65 0a 20 20 61 73 20 74 68 65 20  e same.  as the 
10c90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10ca0 79 20 74 68 65 20 75 6e 63 6f 6d 70 72 65 73 73  y the uncompress
10cb0 20 66 75 6e 63 74 69 6f 6e 2c 20 69 6e 63 6c 75   function, inclu
10cc0 64 69 6e 67 20 74 68 65 20 64 61 74 61 20 74 79  ding the data ty
10cd0 70 65 2e 0a 20 20 49 66 20 74 68 61 74 20 64 61  pe..  If that da
10ce0 74 61 20 74 79 70 65 20 69 73 20 6e 6f 74 20 74  ta type is not t
10cf0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 64  he same as the d
10d00 61 74 61 20 74 79 70 65 20 6f 66 20 74 68 65 20  ata type of the 
10d10 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 61  original value a
10d20 73 0a 20 20 70 61 73 73 65 64 20 74 6f 20 74 68  s.  passed to th
10d30 65 20 63 6f 6d 70 72 65 73 73 20 66 75 6e 63 74  e compress funct
10d40 69 6f 6e 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ion (for example
10d50 20 69 66 20 74 68 65 20 75 6e 63 6f 6d 70 72 65   if the uncompre
10d60 73 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 20  ss function is. 
10d70 20 72 65 74 75 72 6e 69 6e 67 20 42 4c 4f 42 20   returning BLOB 
10d80 77 68 65 6e 20 63 6f 6d 70 72 65 73 73 20 77 61  when compress wa
10d90 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 61 73  s originally pas
10da0 73 65 64 20 54 45 58 54 29 2c 20 74 68 65 6e 20  sed TEXT), then 
10db0 74 68 65 20 75 73 65 72 73 0a 20 20 71 75 65 72  the users.  quer
10dc0 79 20 6d 61 79 20 6e 6f 74 20 66 75 6e 63 74 69  y may not functi
10dd0 6f 6e 20 61 73 20 65 78 70 65 63 74 65 64 2e 0a  on as expected..
10de0 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
10df0 74 20 2a 66 74 73 34 63 6f 6e 74 65 6e 74 20 7b  t *fts4content {
10e00 46 54 53 34 20 63 6f 6e 74 65 6e 74 20 6f 70 74  FTS4 content opt
10e10 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 20 74  ion}</tcl>.<h2 t
10e20 61 67 73 3d 22 66 74 73 34 20 63 6f 6e 74 65 6e  ags="fts4 conten
10e30 74 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20 63 6f  t option">The co
10e40 6e 74 65 6e 74 3d 20 6f 70 74 69 6f 6e 20 3c 2f  ntent= option </
10e50 68 32 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 63  h2>..<p>.  The c
10e60 6f 6e 74 65 6e 74 20 6f 70 74 69 6f 6e 20 61 6c  ontent option al
10e70 6c 6f 77 73 20 46 54 53 34 20 74 6f 20 66 6f 72  lows FTS4 to for
10e80 65 67 6f 20 73 74 6f 72 69 6e 67 20 74 68 65 20  ego storing the 
10e90 74 65 78 74 20 62 65 69 6e 67 20 69 6e 64 65 78  text being index
10ea0 65 64 2e 0a 20 20 54 68 65 20 63 6f 6e 74 65 6e  ed..  The conten
10eb0 74 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  t option can be 
10ec0 75 73 65 64 20 69 6e 20 74 77 6f 20 77 61 79 73  used in two ways
10ed0 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 20  :..<ul>.<li><p> 
10ee0 54 68 65 20 69 6e 64 65 78 65 64 20 64 6f 63 75  The indexed docu
10ef0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 20 73 74  ments are not st
10f00 6f 72 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  ored within the 
10f10 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
10f20 0a 20 20 20 20 20 20 20 20 61 74 20 61 6c 6c 20  .        at all 
10f30 28 61 20 22 63 6f 6e 74 65 6e 74 6c 65 73 73 22  (a "contentless"
10f40 20 46 54 53 34 20 74 61 62 6c 65 29 2c 20 6f 72   FTS4 table), or
10f50 0a 0a 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 69 6e  ..<li><p> The in
10f60 64 65 78 65 64 20 64 6f 63 75 6d 65 6e 74 73 20  dexed documents 
10f70 61 72 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20  are stored in a 
10f80 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 63  database table c
10f90 72 65 61 74 65 64 20 61 6e 64 0a 20 20 20 20 20  reated and.     
10fa0 20 20 20 6d 61 6e 61 67 65 64 20 62 79 20 74 68     managed by th
10fb0 65 20 75 73 65 72 20 28 61 6e 20 22 65 78 74 65  e user (an "exte
10fc0 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 22 20 46 54  rnal content" FT
10fd0 53 34 20 74 61 62 6c 65 29 2e 0a 3c 2f 75 6c 3e  S4 table)..</ul>
10fe0 0a 0a 3c 70 3e 0a 20 20 42 65 63 61 75 73 65 20  ..<p>.  Because 
10ff0 74 68 65 20 69 6e 64 65 78 65 64 20 64 6f 63 75  the indexed docu
11000 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
11010 20 61 72 65 20 75 73 75 61 6c 6c 79 20 6d 75 63   are usually muc
11020 68 20 6c 61 72 67 65 72 20 74 68 61 6e 20 0a 20  h larger than . 
11030 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
11040 6e 64 65 78 2c 20 74 68 65 20 63 6f 6e 74 65 6e  ndex, the conten
11050 74 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  t option can be 
11060 75 73 65 64 20 74 6f 20 61 63 68 69 65 76 65 20  used to achieve 
11070 0a 20 20 73 69 67 6e 69 66 69 63 61 6e 74 20 73  .  significant s
11080 70 61 63 65 20 73 61 76 69 6e 67 73 2e 0a 0a 3c  pace savings...<
11090 68 33 3e 20 43 6f 6e 74 65 6e 74 6c 65 73 73 20  h3> Contentless 
110a0 46 54 53 34 20 54 61 62 6c 65 73 20 3c 2f 68 33  FTS4 Tables </h3
110b0 3e 0a 0a 3c 70 3e 0a 20 20 49 6e 20 6f 72 64 65  >..<p>.  In orde
110c0 72 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 46  r to create an F
110d0 54 53 34 20 74 61 62 6c 65 20 74 68 61 74 20 64  TS4 table that d
110e0 6f 65 73 20 6e 6f 74 20 73 74 6f 72 65 20 61 20  oes not store a 
110f0 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 64 65  copy of the inde
11100 78 65 64 0a 20 20 64 6f 63 75 6d 65 6e 74 73 20  xed.  documents 
11110 61 74 20 61 6c 6c 2c 20 74 68 65 20 63 6f 6e 74  at all, the cont
11120 65 6e 74 20 6f 70 74 69 6f 6e 20 73 68 6f 75 6c  ent option shoul
11130 64 20 62 65 20 73 65 74 20 74 6f 20 61 6e 20 65  d be set to an e
11140 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 20 20 46  mpty string..  F
11150 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20  or example, the 
11160 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 63 72  following SQL cr
11170 65 61 74 65 73 20 73 75 63 68 20 61 6e 20 46 54  eates such an FT
11180 53 34 20 74 61 62 6c 65 20 77 69 74 68 20 74 68  S4 table with th
11190 72 65 65 0a 20 20 63 6f 6c 75 6d 6e 73 20 2d 20  ree.  columns - 
111a0 22 61 22 2c 20 22 62 22 2c 20 61 6e 64 20 22 63  "a", "b", and "c
111b0 22 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ":..<codeblock>.
111c0 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
111d0 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20   TABLE t1 USING 
111e0 66 74 73 34 28 63 6f 6e 74 65 6e 74 3d 22 22 2c  fts4(content="",
111f0 20 61 2c 20 62 2c 20 63 29 3b 0a 3c 2f 63 6f 64   a, b, c);.</cod
11200 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 44  eblock>..<p>.  D
11210 61 74 61 20 63 61 6e 20 62 65 20 69 6e 73 65 72  ata can be inser
11220 74 65 64 20 69 6e 74 6f 20 73 75 63 68 20 61 6e  ted into such an
11230 20 46 54 53 34 20 74 61 62 6c 65 20 75 73 69 6e   FTS4 table usin
11240 67 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61 74  g an INSERT stat
11250 65 6d 65 6e 74 73 2e 0a 20 20 48 6f 77 65 76 65  ements..  Howeve
11260 72 2c 20 75 6e 6c 69 6b 65 20 6f 72 64 69 6e 61  r, unlike ordina
11270 72 79 20 46 54 53 34 20 74 61 62 6c 65 73 2c 20  ry FTS4 tables, 
11280 74 68 65 20 75 73 65 72 20 6d 75 73 74 20 73 75  the user must su
11290 70 70 6c 79 20 61 6e 20 65 78 70 6c 69 63 69 74  pply an explicit
112a0 0a 20 20 69 6e 74 65 67 65 72 20 64 6f 63 69 64  .  integer docid
112b0 20 76 61 6c 75 65 2e 20 46 6f 72 20 65 78 61 6d   value. For exam
112c0 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
112d0 3e 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 73  >.  <i>-- This s
112e0 74 61 74 65 6d 65 6e 74 20 69 73 20 4f 6b 3a 3c  tatement is Ok:<
112f0 2f 69 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  /i>.  INSERT INT
11300 4f 20 74 31 28 64 6f 63 69 64 2c 20 61 2c 20 62  O t1(docid, a, b
11310 2c 20 63 29 20 56 41 4c 55 45 53 28 31 2c 20 27  , c) VALUES(1, '
11320 61 20 62 20 63 27 2c 20 27 64 20 65 20 66 27 2c  a b c', 'd e f',
11330 20 27 67 20 68 20 69 27 29 3b 0a 0a 20 20 3c 69   'g h i');..  <i
11340 3e 2d 2d 20 54 68 69 73 20 73 74 61 74 65 6d 65  >-- This stateme
11350 6e 74 20 63 61 75 73 65 73 20 61 6e 20 65 72 72  nt causes an err
11360 6f 72 2c 20 61 73 20 6e 6f 20 64 6f 63 69 64 20  or, as no docid 
11370 76 61 6c 75 65 20 68 61 73 20 62 65 65 6e 20 70  value has been p
11380 72 6f 76 69 64 65 64 3a 3c 2f 69 3e 0a 20 20 49  rovided:</i>.  I
11390 4e 53 45 52 54 20 49 4e 54 4f 20 74 31 28 61 2c  NSERT INTO t1(a,
113a0 20 62 2c 20 63 29 20 56 41 4c 55 45 53 28 27 6a   b, c) VALUES('j
113b0 20 6b 20 6c 27 2c 20 27 6d 20 6e 20 6f 27 2c 20   k l', 'm n o', 
113c0 27 70 20 71 20 72 27 29 3b 0a 3c 2f 63 6f 64 65  'p q r');.</code
113d0 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 49 74  block>..<p>.  It
113e0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
113f0 20 74 6f 20 55 50 44 41 54 45 20 6f 72 20 44 45   to UPDATE or DE
11400 4c 45 54 45 20 61 20 72 6f 77 20 73 74 6f 72 65  LETE a row store
11410 64 20 69 6e 20 61 20 63 6f 6e 74 65 6e 74 6c 65  d in a contentle
11420 73 73 20 46 54 53 34 0a 20 20 74 61 62 6c 65 2e  ss FTS4.  table.
11430 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
11440 6f 20 73 6f 20 69 73 20 61 6e 20 65 72 72 6f 72  o so is an error
11450 2e 0a 0a 3c 70 3e 0a 20 20 43 6f 6e 74 65 6e 74  ...<p>.  Content
11460 6c 65 73 73 20 46 54 53 34 20 74 61 62 6c 65 73  less FTS4 tables
11470 20 61 6c 73 6f 20 73 75 70 70 6f 72 74 20 53 45   also support SE
11480 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e  LECT statements.
11490 20 48 6f 77 65 76 65 72 2c 20 69 74 20 69 73 0a   However, it is.
114a0 20 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 61 74    an error to at
114b0 74 65 6d 70 74 20 74 6f 20 72 65 74 72 69 65 76  tempt to retriev
114c0 65 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  e the value of a
114d0 6e 79 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ny table column 
114e0 6f 74 68 65 72 20 74 68 61 6e 0a 20 20 74 68 65  other than.  the
114f0 20 64 6f 63 69 64 20 63 6f 6c 75 6d 6e 2e 20 54   docid column. T
11500 68 65 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  he auxiliary fun
11510 63 74 69 6f 6e 20 6d 61 74 63 68 69 6e 66 6f 28  ction matchinfo(
11520 29 20 6d 61 79 20 62 65 20 75 73 65 64 2c 20 62  ) may be used, b
11530 75 74 0a 20 20 73 6e 69 70 70 65 74 28 29 20 61  ut.  snippet() a
11540 6e 64 20 6f 66 66 73 65 74 73 28 29 20 6d 61 79  nd offsets() may
11550 20 6e 6f 74 2e 20 46 6f 72 20 65 78 61 6d 70 6c   not. For exampl
11560 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
11570 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c    <i>-- The foll
11580 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  owing statements
11590 20 61 72 65 20 4f 6b 3a 3c 2f 69 3e 0a 20 20 53   are Ok:</i>.  S
115a0 45 4c 45 43 54 20 64 6f 63 69 64 20 46 52 4f 4d  ELECT docid FROM
115b0 20 74 31 20 57 48 45 52 45 20 74 31 20 4d 41 54   t1 WHERE t1 MAT
115c0 43 48 20 27 78 78 78 27 3b 0a 20 20 53 45 4c 45  CH 'xxx';.  SELE
115d0 43 54 20 64 6f 63 69 64 20 46 52 4f 4d 20 74 31  CT docid FROM t1
115e0 20 57 48 45 52 45 20 61 20 4d 41 54 43 48 20 27   WHERE a MATCH '
115f0 78 78 78 27 3b 0a 20 20 53 45 4c 45 43 54 20 6d  xxx';.  SELECT m
11600 61 74 63 68 69 6e 66 6f 28 74 31 29 20 46 52 4f  atchinfo(t1) FRO
11610 4d 20 74 31 20 57 48 45 52 45 20 74 31 20 4d 41  M t1 WHERE t1 MA
11620 54 43 48 20 27 78 78 78 27 3b 0a 0a 20 20 3c 69  TCH 'xxx';..  <i
11630 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  >-- The followin
11640 67 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 6c  g statements all
11650 20 63 61 75 73 65 20 65 72 72 6f 72 73 2c 20 61   cause errors, a
11660 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 63  s the value of c
11670 6f 6c 75 6d 6e 73 3c 2f 69 3e 0a 20 20 3c 69 3e  olumns</i>.  <i>
11680 2d 2d 20 6f 74 68 65 72 20 74 68 61 6e 20 64 6f  -- other than do
11690 63 69 64 20 61 72 65 20 72 65 71 75 69 72 65 64  cid are required
116a0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
116b0 6d 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  m.</i>.  SELECT 
116c0 2a 20 46 52 4f 4d 20 74 31 3b 0a 20 20 53 45 4c  * FROM t1;.  SEL
116d0 45 43 54 20 61 2c 20 62 20 46 52 4f 4d 20 74 31  ECT a, b FROM t1
116e0 20 57 48 45 52 45 20 74 31 20 4d 41 54 43 48 20   WHERE t1 MATCH 
116f0 27 78 78 78 27 3b 0a 20 20 53 45 4c 45 43 54 20  'xxx';.  SELECT 
11700 64 6f 63 69 64 20 46 52 4f 4d 20 74 31 20 57 48  docid FROM t1 WH
11710 45 52 45 20 61 20 4c 49 4b 45 20 27 78 78 78 25  ERE a LIKE 'xxx%
11720 27 3b 0a 20 20 53 45 4c 45 43 54 20 73 6e 69 70  ';.  SELECT snip
11730 70 65 74 28 74 31 29 20 46 52 4f 4d 20 74 31 20  pet(t1) FROM t1 
11740 57 48 45 52 45 20 74 31 20 4d 41 54 43 48 20 27  WHERE t1 MATCH '
11750 78 78 78 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  xxx';.</codebloc
11760 6b 3e 0a 0a 3c 70 3e 0a 20 20 45 72 72 6f 72 73  k>..<p>.  Errors
11770 20 72 65 6c 61 74 65 64 20 74 6f 20 61 74 74 65   related to atte
11780 6d 70 74 69 6e 67 20 74 6f 20 72 65 74 72 69 65  mpting to retrie
11790 76 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  ve column values
117a0 20 6f 74 68 65 72 20 74 68 61 6e 20 64 6f 63 69   other than doci
117b0 64 0a 20 20 61 72 65 20 72 75 6e 74 69 6d 65 20  d.  are runtime 
117c0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
117d0 72 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  r within sqlite3
117e0 5f 73 74 65 70 28 29 2e 20 49 6e 20 73 6f 6d 65  _step(). In some
117f0 20 63 61 73 65 73 2c 20 66 6f 72 0a 20 20 65 78   cases, for.  ex
11800 61 6d 70 6c 65 20 69 66 20 74 68 65 20 4d 41 54  ample if the MAT
11810 43 48 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e  CH expression in
11820 20 61 20 53 45 4c 45 43 54 20 71 75 65 72 79 20   a SELECT query 
11830 6d 61 74 63 68 65 73 20 7a 65 72 6f 20 72 6f 77  matches zero row
11840 73 2c 20 74 68 65 72 65 0a 20 20 6d 61 79 20 62  s, there.  may b
11850 65 20 6e 6f 20 65 72 72 6f 72 20 61 74 20 61 6c  e no error at al
11860 6c 20 65 76 65 6e 20 69 66 20 61 20 73 74 61 74  l even if a stat
11870 65 6d 65 6e 74 20 64 6f 65 73 20 72 65 66 65 72  ement does refer
11880 20 74 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65   to column value
11890 73 20 0a 20 20 6f 74 68 65 72 20 74 68 61 6e 20  s .  other than 
118a0 64 6f 63 69 64 2e 0a 0a 3c 68 33 3e 20 45 78 74  docid...<h3> Ext
118b0 65 72 6e 61 6c 20 43 6f 6e 74 65 6e 74 20 46 54  ernal Content FT
118c0 53 34 20 54 61 62 6c 65 73 20 3c 2f 68 33 3e 0a  S4 Tables </h3>.
118d0 0a 3c 70 3e 0a 20 20 41 6e 20 22 65 78 74 65 72  .<p>.  An "exter
118e0 6e 61 6c 20 63 6f 6e 74 65 6e 74 22 20 46 54 53  nal content" FTS
118f0 34 20 74 61 62 6c 65 20 69 73 20 73 69 6d 69 6c  4 table is simil
11900 61 72 20 74 6f 20 61 20 63 6f 6e 74 65 6e 74 6c  ar to a contentl
11910 65 73 73 20 74 61 62 6c 65 2c 20 65 78 63 65 70  ess table, excep
11920 74 0a 20 20 74 68 61 74 20 69 66 20 65 76 61 6c  t.  that if eval
11930 75 61 74 69 6f 6e 20 6f 66 20 61 20 71 75 65 72  uation of a quer
11940 79 20 72 65 71 75 69 72 65 73 20 74 68 65 20 76  y requires the v
11950 61 6c 75 65 20 6f 66 20 61 20 63 6f 6c 75 6d 6e  alue of a column
11960 20 6f 74 68 65 72 20 74 68 61 6e 20 0a 20 20 64   other than .  d
11970 6f 63 69 64 2c 20 46 54 53 34 20 61 74 74 65 6d  ocid, FTS4 attem
11980 70 74 73 20 74 6f 20 72 65 74 72 69 65 76 65 20  pts to retrieve 
11990 74 68 61 74 20 76 61 6c 75 65 20 66 72 6f 6d 20  that value from 
119a0 61 20 74 61 62 6c 65 20 28 6f 72 20 76 69 65 77  a table (or view
119b0 2c 20 6f 72 20 0a 20 20 76 69 72 74 75 61 6c 20  , or .  virtual 
119c0 74 61 62 6c 65 29 20 6e 6f 6d 69 6e 61 74 65 64  table) nominated
119d0 20 62 79 20 74 68 65 20 75 73 65 72 20 28 68 65   by the user (he
119e0 72 65 61 66 74 65 72 20 72 65 66 65 72 72 65 64  reafter referred
119f0 20 74 6f 20 61 73 20 74 68 65 20 22 63 6f 6e 74   to as the "cont
11a00 65 6e 74 0a 20 20 74 61 62 6c 65 22 29 2e 20 54  ent.  table"). T
11a10 68 65 20 46 54 53 34 20 6d 6f 64 75 6c 65 20 6e  he FTS4 module n
11a20 65 76 65 72 20 77 72 69 74 65 73 20 74 6f 20 74  ever writes to t
11a30 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  he content table
11a40 2c 20 61 6e 64 20 77 72 69 74 69 6e 67 0a 20 20  , and writing.  
11a50 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74  to the content t
11a60 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 61 66  able does not af
11a70 66 65 63 74 20 74 68 65 20 66 75 6c 6c 2d 74 65  fect the full-te
11a80 78 74 20 69 6e 64 65 78 2e 20 49 74 20 69 73 20  xt index. It is 
11a90 74 68 65 0a 20 20 72 65 73 70 6f 6e 73 69 62 69  the.  responsibi
11aa0 6c 69 74 79 20 6f 66 20 74 68 65 20 75 73 65 72  lity of the user
11ab0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
11ac0 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  the content tabl
11ad0 65 20 61 6e 64 20 74 68 65 20 0a 20 20 66 75 6c  e and the .  ful
11ae0 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 61 72 65  l-text index are
11af0 20 63 6f 6e 73 69 73 74 65 6e 74 2e 0a 0a 3c 70   consistent...<p
11b00 3e 0a 20 20 41 6e 20 65 78 74 65 72 6e 61 6c 20  >.  An external 
11b10 63 6f 6e 74 65 6e 74 20 46 54 53 34 20 74 61 62  content FTS4 tab
11b20 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
11b30 20 73 65 74 74 69 6e 67 20 74 68 65 20 63 6f 6e   setting the con
11b40 74 65 6e 74 20 6f 70 74 69 6f 6e 0a 20 20 74 6f  tent option.  to
11b50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 74   the name of a t
11b60 61 62 6c 65 20 28 6f 72 20 76 69 65 77 2c 20 6f  able (or view, o
11b70 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 29  r virtual table)
11b80 20 74 68 61 74 20 6d 61 79 20 62 65 20 71 75 65   that may be que
11b90 72 69 65 64 20 62 79 0a 20 20 46 54 53 34 20 74  ried by.  FTS4 t
11ba0 6f 20 72 65 74 72 69 65 76 65 20 63 6f 6c 75 6d  o retrieve colum
11bb0 6e 20 76 61 6c 75 65 73 20 77 68 65 6e 20 72 65  n values when re
11bc0 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 6e  quired. If the n
11bd0 6f 6d 69 6e 61 74 65 64 20 74 61 62 6c 65 20 64  ominated table d
11be0 6f 65 73 0a 20 20 6e 6f 74 20 65 78 69 73 74 2c  oes.  not exist,
11bf0 20 74 68 65 6e 20 61 6e 20 65 78 74 65 72 6e 61   then an externa
11c00 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 20  l content table 
11c10 62 65 68 61 76 65 73 20 69 6e 20 74 68 65 20 73  behaves in the s
11c20 61 6d 65 20 77 61 79 20 61 73 0a 20 20 61 20 63  ame way as.  a c
11c30 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
11c40 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  . For example:..
11c50 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 43 52  <codeblock>.  CR
11c60 45 41 54 45 20 54 41 42 4c 45 20 74 32 28 69 64  EATE TABLE t2(id
11c70 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
11c80 20 4b 45 59 2c 20 61 2c 20 62 2c 20 63 29 3b 0a   KEY, a, b, c);.
11c90 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
11ca0 20 54 41 42 4c 45 20 74 33 20 55 53 49 4e 47 20   TABLE t3 USING 
11cb0 66 74 73 34 28 63 6f 6e 74 65 6e 74 3d 22 74 32  fts4(content="t2
11cc0 22 2c 20 61 2c 20 63 29 3b 0a 3c 2f 63 6f 64 65  ", a, c);.</code
11cd0 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 41 73  block>..<p>.  As
11ce0 73 75 6d 69 6e 67 20 74 68 65 20 6e 6f 6d 69 6e  suming the nomin
11cf0 61 74 65 64 20 74 61 62 6c 65 20 64 6f 65 73 20  ated table does 
11d00 65 78 69 73 74 2c 20 74 68 65 6e 20 69 74 73 20  exist, then its 
11d10 63 6f 6c 75 6d 6e 73 20 6d 75 73 74 20 62 65 20  columns must be 
11d20 74 68 65 20 73 61 6d 65 20 0a 20 20 61 73 20 6f  the same .  as o
11d30 72 20 61 20 73 75 70 65 72 73 65 74 20 6f 66 20  r a superset of 
11d40 74 68 6f 73 65 20 64 65 66 69 6e 65 64 20 66 6f  those defined fo
11d50 72 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 2e  r the FTS table.
11d60 20 20 54 68 65 20 65 78 74 65 72 6e 61 6c 20 74    The external t
11d70 61 62 6c 65 0a 20 20 6d 75 73 74 20 61 6c 73 6f  able.  must also
11d80 20 62 65 20 69 6e 20 74 68 65 20 73 61 6d 65 20   be in the same 
11d90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
11da0 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 2e 20   the FTS table. 
11db0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11dc0 0a 20 20 54 68 65 20 65 78 74 65 72 6e 61 6c 20  .  The external 
11dd0 74 61 62 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20  table cannot be 
11de0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 64  in a different d
11df0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 6f 6e  atabase file con
11e00 6e 65 63 74 65 64 20 75 73 69 6e 67 0a 20 20 5b  nected using.  [
11e10 41 54 54 41 43 48 5d 20 6e 6f 72 20 6d 61 79 20  ATTACH] nor may 
11e20 6f 6e 65 20 6f 66 20 74 68 65 20 46 54 53 20 74  one of the FTS t
11e30 61 62 6c 65 20 61 6e 64 20 74 68 65 20 65 78 74  able and the ext
11e40 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 62 65  ernal content be
11e50 20 69 6e 20 74 68 65 0a 20 20 54 45 4d 50 20 64   in the.  TEMP d
11e60 61 74 61 62 61 73 65 20 77 68 65 6e 20 74 68 65  atabase when the
11e70 20 6f 74 68 65 72 20 69 73 20 69 6e 20 61 20 70   other is in a p
11e80 65 72 73 69 73 74 65 6e 74 20 64 61 74 61 62 61  ersistent databa
11e90 73 65 20 66 69 6c 65 20 73 75 63 68 20 61 73 20  se file such as 
11ea0 4d 41 49 4e 2e 0a 0a 3c 70 3e 0a 20 20 57 68 65  MAIN...<p>.  Whe
11eb0 6e 20 61 20 75 73 65 72 73 20 71 75 65 72 79 20  n a users query 
11ec0 6f 6e 20 74 68 65 20 46 54 53 20 74 61 62 6c 65  on the FTS table
11ed0 20 72 65 71 75 69 72 65 73 20 61 20 63 6f 6c 75   requires a colu
11ee0 6d 6e 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  mn value other t
11ef0 68 61 6e 0a 20 20 64 6f 63 69 64 2c 20 46 54 53  han.  docid, FTS
11f00 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 61   attempts to rea
11f10 64 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  d the requested 
11f20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
11f30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6c  orresponding col
11f40 75 6d 6e 20 6f 66 0a 20 20 74 68 65 20 72 6f 77  umn of.  the row
11f50 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   in the content 
11f60 74 61 62 6c 65 20 77 69 74 68 20 61 20 72 6f 77  table with a row
11f70 69 64 20 76 61 6c 75 65 20 65 71 75 61 6c 20 74  id value equal t
11f80 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 46 54  o the current FT
11f90 53 0a 20 20 64 6f 63 69 64 2e 20 4f 72 2c 20 69  S.  docid. Or, i
11fa0 66 20 73 75 63 68 20 61 20 72 6f 77 20 63 61 6e  f such a row can
11fb0 6e 6f 74 20 62 65 20 66 6f 75 6e 64 20 69 6e 20  not be found in 
11fc0 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  the content tabl
11fd0 65 2c 20 61 20 4e 55 4c 4c 0a 20 20 76 61 6c 75  e, a NULL.  valu
11fe0 65 20 69 73 20 75 73 65 64 20 69 6e 73 74 65 61  e is used instea
11ff0 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a  d. For example:.
12000 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 43  .<codeblock>.  C
12010 52 45 41 54 45 20 54 41 42 4c 45 20 74 32 28 69  REATE TABLE t2(i
12020 64 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  d INTEGER PRIMAR
12030 59 20 4b 45 59 2c 20 61 2c 20 62 2c 20 63 2c 20  Y KEY, a, b, c, 
12040 64 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49 52  d);.  CREATE VIR
12050 54 55 41 4c 20 54 41 42 4c 45 20 74 33 20 55 53  TUAL TABLE t3 US
12060 49 4e 47 20 66 74 73 34 28 63 6f 6e 74 65 6e 74  ING fts4(content
12070 3d 22 74 32 22 2c 20 62 2c 20 63 29 3b 0a 20 20  ="t2", b, c);.  
12080 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  .  INSERT INTO t
12090 32 20 56 41 4c 55 45 53 28 32 2c 20 27 61 20 62  2 VALUES(2, 'a b
120a0 27 2c 20 27 63 20 64 27 2c 20 27 65 20 66 27 29  ', 'c d', 'e f')
120b0 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
120c0 74 32 20 56 41 4c 55 45 53 28 33 2c 20 27 67 20  t2 VALUES(3, 'g 
120d0 68 27 2c 20 27 69 20 6a 27 2c 20 27 6b 20 6c 27  h', 'i j', 'k l'
120e0 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
120f0 20 74 33 28 64 6f 63 69 64 2c 20 62 2c 20 63 29   t3(docid, b, c)
12100 20 53 45 4c 45 43 54 20 69 64 2c 20 62 2c 20 63   SELECT id, b, c
12110 20 46 52 4f 4d 20 74 32 3b 0a 20 20 3c 69 3e 2d   FROM t2;.  <i>-
12120 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  - The following 
12130 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 20  query returns a 
12140 73 69 6e 67 6c 65 20 72 6f 77 20 77 69 74 68 20  single row with 
12150 74 77 6f 20 63 6f 6c 75 6d 6e 73 20 63 6f 6e 74  two columns cont
12160 61 69 6e 69 6e 67 0a 20 20 2d 2d 20 74 68 65 20  aining.  -- the 
12170 74 65 78 74 20 76 61 6c 75 65 73 20 22 69 20 6a  text values "i j
12180 22 20 61 6e 64 20 22 6b 20 6c 22 2e 0a 20 20 2d  " and "k l"..  -
12190 2d 0a 20 20 2d 2d 20 54 68 65 20 71 75 65 72 79  -.  -- The query
121a0 20 75 73 65 73 20 74 68 65 20 66 75 6c 6c 2d 74   uses the full-t
121b0 65 78 74 20 69 6e 64 65 78 20 74 6f 20 64 69 73  ext index to dis
121c0 63 6f 76 65 72 20 74 68 61 74 20 74 68 65 20 4d  cover that the M
121d0 41 54 43 48 20 0a 20 20 2d 2d 20 74 65 72 6d 20  ATCH .  -- term 
121e0 6d 61 74 63 68 65 73 20 74 68 65 20 72 6f 77 20  matches the row 
121f0 77 69 74 68 20 64 6f 63 69 64 3d 33 2e 20 49 74  with docid=3. It
12200 20 74 68 65 6e 20 72 65 74 72 69 65 76 65 73 20   then retrieves 
12210 74 68 65 20 76 61 6c 75 65 73 0a 20 20 2d 2d 20  the values.  -- 
12220 6f 66 20 63 6f 6c 75 6d 6e 73 20 62 20 61 6e 64  of columns b and
12230 20 63 20 66 72 6f 6d 20 74 68 65 20 72 6f 77 20   c from the row 
12240 77 69 74 68 20 72 6f 77 69 64 3d 33 20 69 6e 20  with rowid=3 in 
12250 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  the content tabl
12260 65 0a 20 20 2d 2d 20 74 6f 20 72 65 74 75 72 6e  e.  -- to return
12270 2e 0a 20 20 2d 2d 3c 2f 69 3e 0a 20 20 53 45 4c  ..  --</i>.  SEL
12280 45 43 54 20 2a 20 46 52 4f 4d 20 74 33 20 57 48  ECT * FROM t3 WH
12290 45 52 45 20 74 33 20 4d 41 54 43 48 20 27 6b 27  ERE t3 MATCH 'k'
122a0 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 46 6f 6c 6c 6f  ;..  <i>-- Follo
122b0 77 69 6e 67 20 74 68 65 20 55 50 44 41 54 45 2c  wing the UPDATE,
122c0 20 74 68 65 20 71 75 65 72 79 20 73 74 69 6c 6c   the query still
122d0 20 72 65 74 75 72 6e 73 20 61 20 73 69 6e 67 6c   returns a singl
122e0 65 20 72 6f 77 2c 20 74 68 69 73 0a 20 20 2d 2d  e row, this.  --
122f0 20 74 69 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   time containing
12300 20 74 68 65 20 74 65 78 74 20 76 61 6c 75 65 73   the text values
12310 20 22 78 78 78 22 20 61 6e 64 20 22 79 79 79 22   "xxx" and "yyy"
12320 2e 20 54 68 69 73 20 69 73 20 62 65 63 61 75 73  . This is becaus
12330 65 20 74 68 65 0a 20 20 2d 2d 20 66 75 6c 6c 2d  e the.  -- full-
12340 74 65 78 74 20 69 6e 64 65 78 20 73 74 69 6c 6c  text index still
12350 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
12360 74 68 65 20 72 6f 77 20 77 69 74 68 20 64 6f 63  the row with doc
12370 69 64 3d 33 20 6d 61 74 63 68 65 73 0a 20 20 2d  id=3 matches.  -
12380 2d 20 74 68 65 20 46 54 53 34 20 71 75 65 72 79  - the FTS4 query
12390 20 27 6b 27 2c 20 65 76 65 6e 20 74 68 6f 75 67   'k', even thoug
123a0 68 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 73 20  h the documents 
123b0 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 6f  stored in the co
123c0 6e 74 65 6e 74 0a 20 20 2d 2d 20 74 61 62 6c 65  ntent.  -- table
123d0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
123e0 69 65 64 2e 0a 20 20 2d 2d 3c 2f 69 3e 0a 20 20  ied..  --</i>.  
123f0 55 50 44 41 54 45 20 74 32 20 53 45 54 20 62 20  UPDATE t2 SET b 
12400 3d 20 27 78 78 78 27 2c 20 63 20 3d 20 27 79 79  = 'xxx', c = 'yy
12410 79 27 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  y' WHERE rowid =
12420 20 33 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46   3;.  SELECT * F
12430 52 4f 4d 20 74 33 20 57 48 45 52 45 20 74 33 20  ROM t3 WHERE t3 
12440 4d 41 54 43 48 20 27 6b 27 3b 0a 0a 20 20 3c 69  MATCH 'k';..  <i
12450 3e 2d 2d 20 46 6f 6c 6c 6f 77 69 6e 67 20 74 68  >-- Following th
12460 65 20 44 45 4c 45 54 45 20 62 65 6c 6f 77 2c 20  e DELETE below, 
12470 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e  the query return
12480 73 20 6f 6e 65 20 72 6f 77 20 63 6f 6e 74 61 69  s one row contai
12490 6e 69 6e 67 20 74 77 6f 0a 20 20 2d 2d 20 4e 55  ning two.  -- NU
124a0 4c 4c 20 76 61 6c 75 65 73 2e 20 4e 55 4c 4c 20  LL values. NULL 
124b0 76 61 6c 75 65 73 20 61 72 65 20 72 65 74 75 72  values are retur
124c0 6e 65 64 20 62 65 63 61 75 73 65 20 46 54 53 20  ned because FTS 
124d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 66 69 6e  is unable to fin
124e0 64 0a 20 20 2d 2d 20 61 20 72 6f 77 20 77 69 74  d.  -- a row wit
124f0 68 20 72 6f 77 69 64 3d 33 20 77 69 74 68 69 6e  h rowid=3 within
12500 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62   the content tab
12510 6c 65 2e 0a 20 20 2d 2d 3c 2f 69 3e 0a 20 20 44  le..  --</i>.  D
12520 45 4c 45 54 45 20 46 52 4f 4d 20 74 32 3b 0a 20  ELETE FROM t2;. 
12530 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74   SELECT * FROM t
12540 33 20 57 48 45 52 45 20 74 33 20 4d 41 54 43 48  3 WHERE t3 MATCH
12550 20 27 6b 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63   'k';.</codebloc
12560 6b 3e 0a 0a 3c 70 3e 0a 20 20 57 68 65 6e 20 61  k>..<p>.  When a
12570 20 72 6f 77 20 69 73 20 64 65 6c 65 74 65 64 20   row is deleted 
12580 66 72 6f 6d 20 61 6e 20 65 78 74 65 72 6e 61 6c  from an external
12590 20 63 6f 6e 74 65 6e 74 20 46 54 53 34 20 74 61   content FTS4 ta
125a0 62 6c 65 2c 20 46 54 53 34 20 6e 65 65 64 73 20  ble, FTS4 needs 
125b0 74 6f 0a 20 20 72 65 74 72 69 65 76 65 20 74 68  to.  retrieve th
125c0 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  e column values 
125d0 6f 66 20 74 68 65 20 72 6f 77 20 62 65 69 6e 67  of the row being
125e0 20 64 65 6c 65 74 65 64 20 66 72 6f 6d 20 74 68   deleted from th
125f0 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e  e content table.
12600 0a 20 20 54 68 69 73 20 69 73 20 73 6f 20 74 68  .  This is so th
12610 61 74 20 46 54 53 34 20 63 61 6e 20 75 70 64 61  at FTS4 can upda
12620 74 65 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74  te the full-text
12630 20 69 6e 64 65 78 20 65 6e 74 72 69 65 73 20 66   index entries f
12640 6f 72 20 65 61 63 68 20 74 6f 6b 65 6e 0a 20 20  or each token.  
12650 74 68 61 74 20 6f 63 63 75 72 73 20 77 69 74 68  that occurs with
12660 69 6e 20 74 68 65 20 64 65 6c 65 74 65 64 20 72  in the deleted r
12670 6f 77 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ow to indicate t
12680 68 61 74 20 72 6f 77 20 68 61 73 20 62 65 65 6e  hat row has been
12690 20 0a 20 20 64 65 6c 65 74 65 64 2e 20 49 66 20   .  deleted. If 
126a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  the content tabl
126b0 65 20 72 6f 77 20 63 61 6e 6e 6f 74 20 62 65 20  e row cannot be 
126c0 66 6f 75 6e 64 2c 20 6f 72 20 69 66 20 69 74 20  found, or if it 
126d0 63 6f 6e 74 61 69 6e 73 20 76 61 6c 75 65 73 0a  contains values.
126e0 20 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 77    inconsistent w
126f0 69 74 68 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ith the contents
12700 20 6f 66 20 74 68 65 20 46 54 53 20 69 6e 64 65   of the FTS inde
12710 78 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 63  x, the results c
12720 61 6e 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  an be difficult.
12730 20 20 74 6f 20 70 72 65 64 69 63 74 2e 20 54 68    to predict. Th
12740 65 20 46 54 53 20 69 6e 64 65 78 20 6d 61 79 20  e FTS index may 
12750 62 65 20 6c 65 66 74 20 63 6f 6e 74 61 69 6e 69  be left containi
12760 6e 67 20 65 6e 74 72 69 65 73 20 63 6f 72 72 65  ng entries corre
12770 73 70 6f 6e 64 69 6e 67 20 74 6f 20 74 68 65 0a  sponding to the.
12780 20 20 64 65 6c 65 74 65 64 20 72 6f 77 2c 20 77    deleted row, w
12790 68 69 63 68 20 63 61 6e 20 6c 65 61 64 20 74 6f  hich can lead to
127a0 20 73 65 65 6d 69 6e 67 6c 79 20 6e 6f 6e 73 65   seemingly nonse
127b0 6e 73 69 63 61 6c 20 72 65 73 75 6c 74 73 20 62  nsical results b
127c0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 0a 20 20  eing returned.  
127d0 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 45  by subsequent SE
127e0 4c 45 43 54 20 71 75 65 72 69 65 73 2e 20 54 68  LECT queries. Th
127f0 65 20 73 61 6d 65 20 61 70 70 6c 69 65 73 20 77  e same applies w
12800 68 65 6e 20 61 20 72 6f 77 20 69 73 20 75 70 64  hen a row is upd
12810 61 74 65 64 2c 20 61 73 0a 20 20 69 6e 74 65 72  ated, as.  inter
12820 6e 61 6c 6c 79 20 61 6e 20 55 50 44 41 54 45 20  nally an UPDATE 
12830 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 61  is the same as a
12840 20 44 45 4c 45 54 45 20 66 6f 6c 6c 6f 77 65 64   DELETE followed
12850 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2e 0a 0a   by an INSERT...
12860 3c 70 3e 20 20 0a 20 20 49 6e 73 74 65 61 64 20  <p>  .  Instead 
12870 6f 66 20 77 72 69 74 69 6e 67 20 73 65 70 61 72  of writing separ
12880 61 74 65 6c 79 20 74 6f 20 74 68 65 20 66 75 6c  ately to the ful
12890 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 61 6e 64  l-text index and
128a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62   the content tab
128b0 6c 65 2c 0a 20 20 73 6f 6d 65 20 75 73 65 72 73  le,.  some users
128c0 20 6d 61 79 20 77 69 73 68 20 74 6f 20 75 73 65   may wish to use
128d0 20 64 61 74 61 62 61 73 65 20 74 72 69 67 67 65   database trigge
128e0 72 73 20 74 6f 20 6b 65 65 70 20 74 68 65 20 66  rs to keep the f
128f0 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 0a 20  ull-text index. 
12900 20 75 70 20 74 6f 20 64 61 74 65 20 77 69 74 68   up to date with
12910 20 72 65 73 70 65 63 74 20 74 6f 20 74 68 65 20   respect to the 
12920 73 65 74 20 6f 66 20 64 6f 63 75 6d 65 6e 74 73  set of documents
12930 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
12940 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e 0a 20 20  ontent table..  
12950 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 75 73 69  For example, usi
12960 6e 67 20 74 68 65 20 74 61 62 6c 65 73 20 66 72  ng the tables fr
12970 6f 6d 20 65 61 72 6c 69 65 72 20 65 78 61 6d 70  om earlier examp
12980 6c 65 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  les:..<codeblock
12990 3e 0a 20 20 43 52 45 41 54 45 20 54 52 49 47 47  >.  CREATE TRIGG
129a0 45 52 20 74 32 5f 62 75 20 42 45 46 4f 52 45 20  ER t2_bu BEFORE 
129b0 55 50 44 41 54 45 20 4f 4e 20 74 32 20 42 45 47  UPDATE ON t2 BEG
129c0 49 4e 0a 20 20 20 20 44 45 4c 45 54 45 20 46 52  IN.    DELETE FR
129d0 4f 4d 20 74 33 20 57 48 45 52 45 20 64 6f 63 69  OM t3 WHERE doci
129e0 64 3d 6f 6c 64 2e 72 6f 77 69 64 3b 0a 20 20 45  d=old.rowid;.  E
129f0 4e 44 3b 0a 20 20 43 52 45 41 54 45 20 54 52 49  ND;.  CREATE TRI
12a00 47 47 45 52 20 74 32 5f 62 64 20 42 45 46 4f 52  GGER t2_bd BEFOR
12a10 45 20 44 45 4c 45 54 45 20 4f 4e 20 74 32 20 42  E DELETE ON t2 B
12a20 45 47 49 4e 0a 20 20 20 20 44 45 4c 45 54 45 20  EGIN.    DELETE 
12a30 46 52 4f 4d 20 74 33 20 57 48 45 52 45 20 64 6f  FROM t3 WHERE do
12a40 63 69 64 3d 6f 6c 64 2e 72 6f 77 69 64 3b 0a 20  cid=old.rowid;. 
12a50 20 45 4e 44 3b 0a 0a 20 20 43 52 45 41 54 45 20   END;..  CREATE 
12a60 54 52 49 47 47 45 52 20 74 32 5f 61 75 20 41 46  TRIGGER t2_au AF
12a70 54 45 52 20 55 50 44 41 54 45 20 4f 4e 20 74 32  TER UPDATE ON t2
12a80 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53 45 52   BEGIN.    INSER
12a90 54 20 49 4e 54 4f 20 74 33 28 64 6f 63 69 64 2c  T INTO t3(docid,
12aa0 20 62 2c 20 63 29 20 56 41 4c 55 45 53 28 6e 65   b, c) VALUES(ne
12ab0 77 2e 72 6f 77 69 64 2c 20 6e 65 77 2e 62 2c 20  w.rowid, new.b, 
12ac0 6e 65 77 2e 63 29 3b 0a 20 20 45 4e 44 3b 0a 20  new.c);.  END;. 
12ad0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12ae0 74 32 5f 61 69 20 41 46 54 45 52 20 49 4e 53 45  t2_ai AFTER INSE
12af0 52 54 20 4f 4e 20 74 32 20 42 45 47 49 4e 0a 20  RT ON t2 BEGIN. 
12b00 20 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74     INSERT INTO t
12b10 33 28 64 6f 63 69 64 2c 20 62 2c 20 63 29 20 56  3(docid, b, c) V
12b20 41 4c 55 45 53 28 6e 65 77 2e 72 6f 77 69 64 2c  ALUES(new.rowid,
12b30 20 6e 65 77 2e 62 2c 20 6e 65 77 2e 63 29 3b 0a   new.b, new.c);.
12b40 20 20 45 4e 44 3b 0a 3c 2f 63 6f 64 65 62 6c 6f    END;.</codeblo
12b50 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 44  ck>..<p>.  The D
12b60 45 4c 45 54 45 20 74 72 69 67 67 65 72 20 6d 75  ELETE trigger mu
12b70 73 74 20 62 65 20 66 69 72 65 64 20 62 65 66 6f  st be fired befo
12b80 72 65 20 74 68 65 20 61 63 74 75 61 6c 20 64 65  re the actual de
12b90 6c 65 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  lete takes place
12ba0 0a 20 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  .  on the conten
12bb0 74 20 74 61 62 6c 65 2e 20 54 68 69 73 20 69 73  t table. This is
12bc0 20 73 6f 20 74 68 61 74 20 46 54 53 34 20 63 61   so that FTS4 ca
12bd0 6e 20 73 74 69 6c 6c 20 72 65 74 72 69 65 76 65  n still retrieve
12be0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 20 20   the original.  
12bf0 76 61 6c 75 65 73 20 69 6e 20 6f 72 64 65 72 20  values in order 
12c00 74 6f 20 75 70 64 61 74 65 20 74 68 65 20 66 75  to update the fu
12c10 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e 20 41  ll-text index. A
12c20 6e 64 20 74 68 65 20 49 4e 53 45 52 54 20 74 72  nd the INSERT tr
12c30 69 67 67 65 72 20 6d 75 73 74 0a 20 20 62 65 20  igger must.  be 
12c40 66 69 72 65 64 20 61 66 74 65 72 20 74 68 65 20  fired after the 
12c50 6e 65 77 20 72 6f 77 20 69 73 20 69 6e 73 65 72  new row is inser
12c60 74 65 64 2c 20 73 6f 20 61 73 20 74 6f 20 68 61  ted, so as to ha
12c70 6e 64 6c 65 20 74 68 65 20 63 61 73 65 20 77 68  ndle the case wh
12c80 65 72 65 20 74 68 65 0a 20 20 72 6f 77 69 64 20  ere the.  rowid 
12c90 69 73 20 61 73 73 69 67 6e 65 64 20 61 75 74 6f  is assigned auto
12ca0 6d 61 74 69 63 61 6c 6c 79 20 77 69 74 68 69 6e  matically within
12cb0 20 74 68 65 20 73 79 73 74 65 6d 2e 20 54 68 65   the system. The
12cc0 20 55 50 44 41 54 45 20 74 72 69 67 67 65 72 20   UPDATE trigger 
12cd0 6d 75 73 74 0a 20 20 62 65 20 73 70 6c 69 74 20  must.  be split 
12ce0 69 6e 74 6f 20 74 77 6f 20 70 61 72 74 73 2c 20  into two parts, 
12cf0 6f 6e 65 20 66 69 72 65 64 20 62 65 66 6f 72 65  one fired before
12d00 20 61 6e 64 20 6f 6e 65 20 61 66 74 65 72 20 74   and one after t
12d10 68 65 20 75 70 64 61 74 65 20 6f 66 20 74 68 65  he update of the
12d20 0a 20 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  .  content table
12d30 2c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 72  , for the same r
12d40 65 61 73 6f 6e 73 2e 0a 0a 3c 70 3e 0a 20 20 54  easons...<p>.  T
12d50 68 65 20 5b 46 54 53 34 20 22 72 65 62 75 69 6c  he [FTS4 "rebuil
12d60 64 22 20 63 6f 6d 6d 61 6e 64 5d 0a 20 20 64 65  d" command].  de
12d70 6c 65 74 65 73 20 74 68 65 20 65 6e 74 69 72 65  letes the entire
12d80 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
12d90 20 61 6e 64 20 72 65 62 75 69 6c 64 73 20 69 74   and rebuilds it
12da0 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 63 75   based on the cu
12db0 72 72 65 6e 74 0a 20 20 73 65 74 20 6f 66 20 64  rrent.  set of d
12dc0 6f 63 75 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  ocuments in the 
12dd0 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e 20 41  content table. A
12de0 73 73 75 6d 69 6e 67 20 61 67 61 69 6e 20 74 68  ssuming again th
12df0 61 74 20 22 74 33 22 20 69 73 20 74 68 65 0a 20  at "t3" is the. 
12e00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 78 74   name of the ext
12e10 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 46 54  ernal content FT
12e20 53 34 20 74 61 62 6c 65 2c 20 74 68 65 20 72 65  S4 table, the re
12e30 62 75 69 6c 64 20 63 6f 6d 6d 61 6e 64 20 6c 6f  build command lo
12e40 6f 6b 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a  oks like this:..
12e50 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e  <codeblock>.  IN
12e60 53 45 52 54 20 49 4e 54 4f 20 74 33 28 74 33 29  SERT INTO t3(t3)
12e70 20 56 41 4c 55 45 53 28 27 72 65 62 75 69 6c 64   VALUES('rebuild
12e80 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  ');.</codeblock>
12e90 0a 0a 3c 70 3e 0a 20 20 54 68 69 73 20 63 6f 6d  ..<p>.  This com
12ea0 6d 61 6e 64 20 6d 61 79 20 61 6c 73 6f 20 62 65  mand may also be
12eb0 20 75 73 65 64 20 77 69 74 68 20 6f 72 64 69 6e   used with ordin
12ec0 61 72 79 20 46 54 53 34 20 74 61 62 6c 65 73 2c  ary FTS4 tables,
12ed0 20 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 66 0a   for example if.
12ee0 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    the implementa
12ef0 74 69 6f 6e 20 6f 66 20 74 68 65 20 74 6f 6b 65  tion of the toke
12f00 6e 69 7a 65 72 20 63 68 61 6e 67 65 73 2e 20 20  nizer changes.  
12f10 49 74 20 69 73 20 61 6e 0a 20 20 65 72 72 6f 72  It is an.  error
12f20 20 74 6f 20 61 74 74 65 6d 70 74 20 74 6f 20 72   to attempt to r
12f30 65 62 75 69 6c 64 20 74 68 65 20 66 75 6c 6c 2d  ebuild the full-
12f40 74 65 78 74 20 69 6e 64 65 78 20 6d 61 69 6e 74  text index maint
12f50 61 69 6e 65 64 20 62 79 20 61 20 63 6f 6e 74 65  ained by a conte
12f60 6e 74 6c 65 73 73 0a 20 20 46 54 53 34 20 74 61  ntless.  FTS4 ta
12f70 62 6c 65 2c 20 73 69 6e 63 65 20 6e 6f 20 63 6f  ble, since no co
12f80 6e 74 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 76  ntent will be av
12f90 61 69 6c 61 62 6c 65 20 74 6f 20 64 6f 20 74 68  ailable to do th
12fa0 65 20 72 65 62 75 69 6c 64 69 6e 67 2e 0a 0a 0a  e rebuilding....
12fb0 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
12fc0 20 2a 66 74 73 34 6c 61 6e 67 75 61 67 65 69 64   *fts4languageid
12fd0 20 7b 46 54 53 34 20 6c 61 6e 67 75 61 67 65 69   {FTS4 languagei
12fe0 64 20 6f 70 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a  d option}</tcl>.
12ff0 3c 68 32 20 74 61 67 73 3d 22 66 74 73 34 20 6c  <h2 tags="fts4 l
13000 61 6e 67 75 61 67 65 69 64 20 6f 70 74 69 6f 6e  anguageid option
13010 22 3e 54 68 65 20 6c 61 6e 67 75 61 67 65 69 64  ">The languageid
13020 3d 20 6f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c  = option</h2>..<
13030 70 3e 0a 20 20 57 68 65 6e 20 74 68 65 20 6c 61  p>.  When the la
13040 6e 67 75 61 67 65 69 64 20 6f 70 74 69 6f 6e 20  nguageid option 
13050 69 73 20 70 72 65 73 65 6e 74 2c 20 69 74 20 73  is present, it s
13060 70 65 63 69 66 69 65 73 20 74 68 65 20 6e 61 6d  pecifies the nam
13070 65 20 6f 66 0a 20 20 61 6e 6f 74 68 65 72 20 5b  e of.  another [
13080 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 5d 20 74  hidden column] t
13090 68 61 74 20 69 73 20 61 64 64 65 64 20 74 6f 20  hat is added to 
130a0 74 68 65 20 46 54 53 34 0a 20 20 74 61 62 6c 65  the FTS4.  table
130b0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 75 73   and which is us
130c0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
130d0 65 20 6c 61 6e 67 75 61 67 65 20 73 74 6f 72 65  e language store
130e0 64 20 69 6e 20 65 61 63 68 20 72 6f 77 0a 20 20  d in each row.  
130f0 6f 66 20 74 68 65 20 46 54 53 34 20 74 61 62 6c  of the FTS4 tabl
13100 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  e.  The name of 
13110 74 68 65 20 6c 61 6e 67 75 61 67 65 69 64 20 68  the languageid h
13120 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 6d 75 73  idden column mus
13130 74 0a 20 20 62 65 20 64 69 73 74 69 6e 63 74 20  t.  be distinct 
13140 66 72 6f 6d 20 61 6c 6c 20 6f 74 68 65 72 20 63  from all other c
13150 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 20 74  olumn names in t
13160 68 65 20 46 54 53 34 20 74 61 62 6c 65 2e 20 20  he FTS4 table.  
13170 45 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  Example:..<codeb
13180 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20 56  lock>.  CREATE V
13190 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20  IRTUAL TABLE t1 
131a0 55 53 49 4e 47 20 66 74 73 34 28 78 2c 20 79 2c  USING fts4(x, y,
131b0 20 6c 61 6e 67 75 61 67 65 69 64 3d 22 6c 69 64   languageid="lid
131c0 22 29 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ").</codeblock>.
131d0 0a 3c 70 3e 0a 20 20 54 68 65 20 64 65 66 61 75  .<p>.  The defau
131e0 6c 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 61  lt value of a la
131f0 6e 67 75 61 67 65 69 64 20 63 6f 6c 75 6d 6e 20  nguageid column 
13200 69 73 20 30 2e 20 41 6e 79 20 76 61 6c 75 65 20  is 0. Any value 
13210 69 6e 73 65 72 74 65 64 0a 20 20 69 6e 74 6f 20  inserted.  into 
13220 61 20 6c 61 6e 67 75 61 67 65 69 64 20 63 6f 6c  a languageid col
13230 75 6d 6e 20 69 73 20 63 6f 6e 76 65 72 74 65 64  umn is converted
13240 20 74 6f 20 61 20 33 32 2d 62 69 74 20 28 6e 6f   to a 32-bit (no
13250 74 20 36 34 29 20 73 69 67 6e 65 64 0a 20 20 69  t 64) signed.  i
13260 6e 74 65 67 65 72 2e 0a 0a 3c 70 3e 0a 20 20 42  nteger...<p>.  B
13270 79 20 64 65 66 61 75 6c 74 2c 20 46 54 53 20 71  y default, FTS q
13280 75 65 72 69 65 73 20 28 74 68 6f 73 65 20 74 68  ueries (those th
13290 61 74 20 75 73 65 20 74 68 65 20 4d 41 54 43 48  at use the MATCH
132a0 20 6f 70 65 72 61 74 6f 72 29 0a 20 20 63 6f 6e   operator).  con
132b0 73 69 64 65 72 20 6f 6e 6c 79 20 74 68 6f 73 65  sider only those
132c0 20 72 6f 77 73 20 77 69 74 68 20 74 68 65 20 6c   rows with the l
132d0 61 6e 67 75 61 67 65 69 64 20 63 6f 6c 75 6d 6e  anguageid column
132e0 20 73 65 74 20 74 6f 20 30 2e 20 54 6f 0a 20 20   set to 0. To.  
132f0 71 75 65 72 79 20 66 6f 72 20 72 6f 77 73 20 77  query for rows w
13300 69 74 68 20 6f 74 68 65 72 20 6c 61 6e 67 75 61  ith other langua
13310 67 65 69 64 20 76 61 6c 75 65 73 2c 20 61 20 63  geid values, a c
13320 6f 6e 73 74 72 61 69 6e 74 20 6f 66 20 74 68 65  onstraint of the
13330 0a 20 20 66 6f 72 6d 20 22 3c 6c 61 6e 67 75 61  .  form "<langua
13340 67 65 2d 69 64 3e 20 3d 20 3c 69 6e 74 65 67 65  ge-id> = <intege
13350 72 3e 22 20 6d 75 73 74 20 62 65 20 61 64 64 65  r>" must be adde
13360 64 20 74 6f 20 74 68 65 20 71 75 65 72 69 65 73  d to the queries
13370 0a 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 2e  .  WHERE clause.
13380 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c   For example:..<
13390 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c  codeblock>.  SEL
133a0 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 57 48  ECT * FROM t1 WH
133b0 45 52 45 20 74 31 20 4d 41 54 43 48 20 27 61 62  ERE t1 MATCH 'ab
133c0 63 27 20 41 4e 44 20 6c 69 64 3d 35 3b 0a 3c 2f  c' AND lid=5;.</
133d0 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
133e0 20 20 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73    It is not poss
133f0 69 62 6c 65 20 66 6f 72 20 61 20 73 69 6e 67 6c  ible for a singl
13400 65 20 46 54 53 20 71 75 65 72 79 20 74 6f 20 72  e FTS query to r
13410 65 74 75 72 6e 20 72 6f 77 73 20 77 69 74 68 0a  eturn rows with.
13420 20 20 64 69 66 66 65 72 65 6e 74 20 6c 61 6e 67    different lang
13430 75 61 67 65 69 64 20 76 61 6c 75 65 73 2e 20 54  uageid values. T
13440 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 61 64  he results of ad
13450 64 69 6e 67 20 57 48 45 52 45 20 63 6c 61 75 73  ding WHERE claus
13460 65 73 0a 20 20 74 68 61 74 20 75 73 65 20 6f 74  es.  that use ot
13470 68 65 72 20 6f 70 65 72 61 74 6f 72 73 20 28 65  her operators (e
13480 2e 67 2e 20 20 6c 69 64 21 3d 35 2c 20 6f 72 20  .g.  lid!=5, or 
13490 6c 69 64 26 6c 74 3b 3d 35 29 20 61 72 65 20 75  lid&lt;=5) are u
134a0 6e 64 65 66 69 6e 65 64 2e 0a 0a 3c 70 3e 0a 20  ndefined...<p>. 
134b0 20 49 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   If the content 
134c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 61  option is used a
134d0 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 6c 61  long with the la
134e0 6e 67 75 61 67 65 69 64 20 6f 70 74 69 6f 6e 2c  nguageid option,
134f0 0a 20 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  .  then the name
13500 64 20 6c 61 6e 67 75 61 67 65 69 64 20 63 6f 6c  d languageid col
13510 75 6d 6e 20 6d 75 73 74 20 65 78 69 73 74 20 69  umn must exist i
13520 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 3d 20 74  n the content= t
13530 61 62 6c 65 0a 20 20 28 73 75 62 6a 65 63 74 20  able.  (subject 
13540 74 6f 20 74 68 65 20 75 73 75 61 6c 20 72 75 6c  to the usual rul
13550 65 73 20 2d 20 69 66 20 61 20 71 75 65 72 79 20  es - if a query 
13560 6e 65 76 65 72 20 6e 65 65 64 73 20 74 6f 20 72  never needs to r
13570 65 61 64 20 74 68 65 0a 20 20 63 6f 6e 74 65 6e  ead the.  conten
13580 74 20 74 61 62 6c 65 20 74 68 65 6e 20 74 68 69  t table then thi
13590 73 20 72 65 73 74 72 69 63 74 69 6f 6e 20 64 6f  s restriction do
135a0 65 73 20 6e 6f 74 20 61 70 70 6c 79 29 2e 0a 0a  es not apply)...
135b0 3c 70 3e 0a 20 20 57 68 65 6e 20 74 68 65 20 6c  <p>.  When the l
135c0 61 6e 67 75 61 67 65 69 64 20 6f 70 74 69 6f 6e  anguageid option
135d0 20 69 73 20 75 73 65 64 2c 20 53 51 4c 69 74 65   is used, SQLite
135e0 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 4c 61   invokes the xLa
135f0 6e 67 75 61 67 65 69 64 28 29 0a 20 20 6f 6e 20  nguageid().  on 
13600 74 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 6b 65  the sqlite3_toke
13610 6e 69 7a 65 72 5f 6d 6f 64 75 6c 65 20 6f 62 6a  nizer_module obj
13620 65 63 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ect immediately 
13630 61 66 74 65 72 20 74 68 65 20 6f 62 6a 65 63 74  after the object
13640 0a 20 20 69 73 20 63 72 65 61 74 65 64 20 69 6e  .  is created in
13650 20 6f 72 64 65 72 20 74 6f 20 70 61 73 73 20 69   order to pass i
13660 6e 20 74 68 65 20 6c 61 6e 67 75 61 67 65 20 69  n the language i
13670 64 20 74 68 61 74 20 70 61 72 74 69 63 75 6c 61  d that particula
13680 72 0a 20 20 74 6f 6b 65 6e 69 7a 65 72 20 73 68  r.  tokenizer sh
13690 6f 75 6c 64 20 75 73 65 2e 20 20 54 68 65 20 78  ould use.  The x
136a0 4c 61 6e 67 75 61 67 65 69 64 28 29 20 6d 65 74  Languageid() met
136b0 68 6f 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  hod will never b
136c0 65 20 63 61 6c 6c 65 64 0a 20 20 6d 6f 72 65 20  e called.  more 
136d0 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 61 6e  than once for an
136e0 79 20 73 69 6e 67 6c 65 20 74 6f 6b 65 6e 69 7a  y single tokeniz
136f0 65 72 20 6f 62 6a 65 63 74 2e 0a 20 20 0a 0a 0a  er object..  ...
13700 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
13710 20 66 74 73 34 6d 61 74 63 68 69 6e 66 6f 20 7b   fts4matchinfo {
13720 46 54 53 34 20 6d 61 74 63 68 69 6e 66 6f 20 6f  FTS4 matchinfo o
13730 70 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  ption}</tcl>.<h2
13740 20 74 61 67 73 3d 22 66 74 73 34 20 6d 61 74 63   tags="fts4 matc
13750 68 69 6e 66 6f 20 6f 70 74 69 6f 6e 22 3e 54 68  hinfo option">Th
13760 65 20 6d 61 74 63 68 69 6e 66 6f 3d 20 6f 70 74  e matchinfo= opt
13770 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20  ion</h2>..<p>.  
13780 54 68 65 20 6d 61 74 63 68 69 6e 66 6f 20 6f 70  The matchinfo op
13790 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 62 65  tion may only be
137a0 20 73 65 74 20 74 6f 20 74 68 65 20 76 61 6c 75   set to the valu
137b0 65 20 22 66 74 73 33 22 2e 20 0a 20 20 41 74 74  e "fts3". .  Att
137c0 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 6d  empting to set m
137d0 61 74 63 68 69 6e 66 6f 20 74 6f 20 61 6e 79 74  atchinfo to anyt
137e0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
137f0 22 66 74 73 33 22 20 69 73 20 61 6e 20 65 72 72  "fts3" is an err
13800 6f 72 2e 0a 20 20 49 66 20 74 68 69 73 20 6f 70  or..  If this op
13810 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
13820 64 2c 20 74 68 65 6e 20 73 6f 6d 65 20 6f 66 20  d, then some of 
13830 74 68 65 20 65 78 74 72 61 20 69 6e 66 6f 72 6d  the extra inform
13840 61 74 69 6f 6e 20 73 74 6f 72 65 64 20 62 79 0a  ation stored by.
13850 20 20 46 54 53 34 20 69 73 20 6f 6d 69 74 74 65    FTS4 is omitte
13860 64 2e 20 54 68 69 73 20 72 65 64 75 63 65 73 20  d. This reduces 
13870 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 64 69  the amount of di
13880 73 6b 20 73 70 61 63 65 20 63 6f 6e 73 75 6d 65  sk space consume
13890 64 20 62 79 0a 20 20 61 6e 20 46 54 53 34 20 74  d by.  an FTS4 t
138a0 61 62 6c 65 20 75 6e 74 69 6c 20 69 74 20 69 73  able until it is
138b0 20 61 6c 6d 6f 73 74 20 74 68 65 20 73 61 6d 65   almost the same
138c0 20 61 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 74   as the amount t
138d0 68 61 74 20 77 6f 75 6c 64 0a 20 20 62 65 20 75  hat would.  be u
138e0 73 65 64 20 62 79 20 74 68 65 20 65 71 75 69 76  sed by the equiv
138f0 61 6c 65 6e 74 20 46 54 53 33 20 74 61 62 6c 65  alent FTS3 table
13900 2c 20 62 75 74 20 61 6c 73 6f 20 6d 65 61 6e 73  , but also means
13910 20 74 68 61 74 20 74 68 65 20 64 61 74 61 0a 20   that the data. 
13920 20 61 63 63 65 73 73 65 64 20 62 79 20 70 61 73   accessed by pas
13930 73 69 6e 67 20 74 68 65 20 27 6c 27 20 66 6c 61  sing the 'l' fla
13940 67 20 74 6f 20 74 68 65 20 5b 6d 61 74 63 68 69  g to the [matchi
13950 6e 66 6f 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  nfo()] function 
13960 69 73 0a 20 20 6e 6f 74 20 61 76 61 69 6c 61 62  is.  not availab
13970 6c 65 2e 20 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  le. ..<tcl>hd_fr
13980 61 67 6d 65 6e 74 20 66 74 73 34 70 72 65 66 69  agment fts4prefi
13990 78 20 7b 46 54 53 34 20 70 72 65 66 69 78 20 6f  x {FTS4 prefix o
139a0 70 74 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  ption}</tcl>.<h2
139b0 20 74 61 67 73 3d 22 66 74 73 34 20 70 72 65 66   tags="fts4 pref
139c0 69 78 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20 70  ix option">The p
139d0 72 65 66 69 78 3d 20 6f 70 74 69 6f 6e 3c 2f 68  refix= option</h
139e0 32 3e 0a 0a 3c 70 3e 0a 20 20 5e 54 68 65 20 46  2>..<p>.  ^The F
139f0 54 53 34 20 70 72 65 66 69 78 20 6f 70 74 69 6f  TS4 prefix optio
13a00 6e 20 63 61 75 73 65 73 20 46 54 53 20 74 6f 20  n causes FTS to 
13a10 69 6e 64 65 78 20 74 65 72 6d 20 70 72 65 66 69  index term prefi
13a20 78 65 73 20 6f 66 20 73 70 65 63 69 66 69 65 64  xes of specified
13a30 20 6c 65 6e 67 74 68 73 0a 20 20 69 6e 20 74 68   lengths.  in th
13a40 65 20 73 61 6d 65 20 77 61 79 20 74 68 61 74 20  e same way that 
13a50 69 74 20 61 6c 77 61 79 73 20 69 6e 64 65 78 65  it always indexe
13a60 73 20 63 6f 6d 70 6c 65 74 65 20 74 65 72 6d 73  s complete terms
13a70 2e 20 20 5e 54 68 65 20 70 72 65 66 69 78 20 6f  .  ^The prefix o
13a80 70 74 69 6f 6e 0a 20 20 6d 75 73 74 20 62 65 20  ption.  must be 
13a90 73 65 74 20 74 6f 20 61 20 63 6f 6d 6d 61 20 73  set to a comma s
13aa0 65 70 61 72 61 74 65 64 20 6c 69 73 74 20 6f 66  eparated list of
13ab0 20 70 6f 73 69 74 69 76 65 20 6e 6f 6e 2d 7a 65   positive non-ze
13ac0 72 6f 20 69 6e 74 65 67 65 72 73 2e 20 0a 20 20  ro integers. .  
13ad0 5e 46 6f 72 20 65 61 63 68 20 76 61 6c 75 65 20  ^For each value 
13ae0 4e 20 69 6e 20 74 68 65 20 6c 69 73 74 2c 20 70  N in the list, p
13af0 72 65 66 69 78 65 73 20 6f 66 20 6c 65 6e 67 74  refixes of lengt
13b00 68 20 4e 20 62 79 74 65 73 20 28 77 68 65 6e 20  h N bytes (when 
13b10 65 6e 63 6f 64 65 64 20 0a 20 20 75 73 69 6e 67  encoded .  using
13b20 20 55 54 46 2d 38 29 20 61 72 65 20 69 6e 64 65   UTF-8) are inde
13b30 78 65 64 2e 20 20 5e 46 54 53 34 20 75 73 65 73  xed.  ^FTS4 uses
13b40 20 74 65 72 6d 20 70 72 65 66 69 78 20 69 6e 64   term prefix ind
13b50 65 78 65 73 20 74 6f 20 73 70 65 65 64 20 75 70  exes to speed up
13b60 0a 20 20 5b 70 72 65 66 69 78 20 71 75 65 72 69  .  [prefix queri
13b70 65 73 5d 2e 20 54 68 65 20 63 6f 73 74 2c 20 6f  es]. The cost, o
13b80 66 20 63 6f 75 72 73 65 2c 20 69 73 20 74 68 61  f course, is tha
13b90 74 20 69 6e 64 65 78 69 6e 67 20 74 65 72 6d 20  t indexing term 
13ba0 70 72 65 66 69 78 65 73 20 61 73 0a 20 20 77 65  prefixes as.  we
13bb0 6c 6c 20 61 73 20 63 6f 6d 70 6c 65 74 65 20 74  ll as complete t
13bc0 65 72 6d 73 20 69 6e 63 72 65 61 73 65 73 20 74  erms increases t
13bd0 68 65 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  he database size
13be0 20 61 6e 64 20 73 6c 6f 77 73 20 64 6f 77 6e 20   and slows down 
13bf0 77 72 69 74 65 20 0a 20 20 6f 70 65 72 61 74 69  write .  operati
13c00 6f 6e 73 20 6f 6e 20 74 68 65 20 46 54 53 34 20  ons on the FTS4 
13c10 74 61 62 6c 65 2e 0a 0a 3c 70 3e 0a 20 20 50 72  table...<p>.  Pr
13c20 65 66 69 78 20 69 6e 64 65 78 65 73 20 6d 61 79  efix indexes may
13c30 20 62 65 20 75 73 65 64 20 74 6f 20 6f 70 74 69   be used to opti
13c40 6d 69 7a 65 20 5b 70 72 65 66 69 78 20 71 75 65  mize [prefix que
13c50 72 69 65 73 5d 20 69 6e 20 74 77 6f 20 63 61 73  ries] in two cas
13c60 65 73 2e 0a 20 20 49 66 20 74 68 65 20 71 75 65  es..  If the que
13c70 72 79 20 69 73 20 66 6f 72 20 61 20 70 72 65 66  ry is for a pref
13c80 69 78 20 6f 66 20 4e 20 62 79 74 65 73 2c 20 74  ix of N bytes, t
13c90 68 65 6e 20 61 20 70 72 65 66 69 78 20 69 6e 64  hen a prefix ind
13ca0 65 78 20 63 72 65 61 74 65 64 0a 20 20 77 69 74  ex created.  wit
13cb0 68 20 22 70 72 65 66 69 78 3d 4e 22 20 70 72 6f  h "prefix=N" pro
13cc0 76 69 64 65 73 20 74 68 65 20 62 65 73 74 20 6f  vides the best o
13cd0 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 4f 72 2c  ptimization. Or,
13ce0 20 69 66 20 6e 6f 20 22 70 72 65 66 69 78 3d 4e   if no "prefix=N
13cf0 22 0a 20 20 69 6e 64 65 78 20 69 73 20 61 76 61  ".  index is ava
13d00 69 6c 61 62 6c 65 2c 20 61 20 22 70 72 65 66 69  ilable, a "prefi
13d10 78 3d 4e 2b 31 22 20 69 6e 64 65 78 20 6d 61 79  x=N+1" index may
13d20 20 62 65 20 75 73 65 64 20 69 6e 73 74 65 61 64   be used instead
13d30 2e 20 0a 20 20 55 73 69 6e 67 20 61 20 22 70 72  . .  Using a "pr
13d40 65 66 69 78 3d 4e 2b 31 22 20 69 6e 64 65 78 20  efix=N+1" index 
13d50 69 73 20 6c 65 73 73 0a 20 20 65 66 66 69 63 69  is less.  effici
13d60 65 6e 74 20 74 68 61 6e 20 61 20 22 70 72 65 66  ent than a "pref
13d70 69 78 3d 4e 22 20 69 6e 64 65 78 2c 20 62 75 74  ix=N" index, but
13d80 20 69 73 20 62 65 74 74 65 72 20 74 68 61 6e 20   is better than 
13d90 6e 6f 20 70 72 65 66 69 78 20 69 6e 64 65 78 20  no prefix index 
13da0 61 74 20 61 6c 6c 2e 0a 0a 3c 63 6f 64 65 62 6c  at all...<codebl
13db0 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65  ock>.  <i>-- Cre
13dc0 61 74 65 20 61 6e 20 46 54 53 34 20 74 61 62 6c  ate an FTS4 tabl
13dd0 65 20 77 69 74 68 20 69 6e 64 65 78 65 73 20 74  e with indexes t
13de0 6f 20 6f 70 74 69 6d 69 7a 65 20 32 20 61 6e 64  o optimize 2 and
13df0 20 34 20 62 79 74 65 20 70 72 65 66 69 78 20 71   4 byte prefix q
13e00 75 65 72 69 65 73 2e 3c 2f 69 3e 0a 20 20 43 52  ueries.</i>.  CR
13e10 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
13e20 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 34  LE t1 USING fts4
13e30 28 63 31 2c 20 63 32 2c 20 70 72 65 66 69 78 3d  (c1, c2, prefix=
13e40 22 32 2c 34 22 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  "2,4");..  <i>--
13e50 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
13e60 77 6f 20 71 75 65 72 69 65 73 20 61 72 65 20 62  wo queries are b
13e70 6f 74 68 20 6f 70 74 69 6d 69 7a 65 64 20 75 73  oth optimized us
13e80 69 6e 67 20 74 68 65 20 70 72 65 66 69 78 20 69  ing the prefix i
13e90 6e 64 65 78 65 73 2e 3c 2f 69 3e 0a 20 20 53 45  ndexes.</i>.  SE
13ea0 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 57  LECT * FROM t1 W
13eb0 48 45 52 45 20 74 31 20 4d 41 54 43 48 20 27 61  HERE t1 MATCH 'a
13ec0 62 2a 27 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20  b*';.  SELECT * 
13ed0 46 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74 31  FROM t1 WHERE t1
13ee0 20 4d 41 54 43 48 20 27 61 62 63 64 2a 27 3b 0a   MATCH 'abcd*';.
13ef0 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c  .  <i>-- The fol
13f00 6c 6f 77 69 6e 67 20 74 77 6f 20 71 75 65 72 69  lowing two queri
13f10 65 73 20 61 72 65 20 62 6f 74 68 20 70 61 72 74  es are both part
13f20 69 61 6c 6c 79 20 6f 70 74 69 6d 69 7a 65 64 20  ially optimized 
13f30 75 73 69 6e 67 20 74 68 65 20 70 72 65 66 69 78  using the prefix
13f40 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e 64  </i>.  <i>-- ind
13f50 65 78 65 73 2e 20 54 68 65 20 6f 70 74 69 6d 69  exes. The optimi
13f60 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 73  zation is not as
13f70 20 70 72 6f 6e 6f 75 6e 63 65 64 20 61 73 20 69   pronounced as i
13f80 74 20 69 73 20 66 6f 72 20 74 68 65 20 71 75 65  t is for the que
13f90 72 69 65 73 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  ries</i>.  <i>--
13fa0 20 61 62 6f 76 65 2c 20 62 75 74 20 73 74 69 6c   above, but stil
13fb0 6c 20 61 6e 20 69 6d 70 72 6f 76 65 6d 65 6e 74  l an improvement
13fc0 20 6f 76 65 72 20 6e 6f 20 70 72 65 66 69 78 20   over no prefix 
13fd0 69 6e 64 65 78 65 73 20 61 74 20 61 6c 6c 2e 3c  indexes at all.<
13fe0 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  /i>.  SELECT * F
13ff0 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74 31 20  ROM t1 WHERE t1 
14000 4d 41 54 43 48 20 27 61 2a 27 3b 0a 20 20 53 45  MATCH 'a*';.  SE
14010 4c 45 43 54 20 2a 20 46 52 4f 4d 20 74 31 20 57  LECT * FROM t1 W
14020 48 45 52 45 20 74 31 20 4d 41 54 43 48 20 27 61  HERE t1 MATCH 'a
14030 62 63 2a 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  bc*';.</codebloc
14040 6b 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  k>..<tcl>hd_frag
14050 6d 65 6e 74 20 2a 63 6d 64 73 20 7b 46 54 53 34  ment *cmds {FTS4
14060 20 63 6f 6d 6d 61 6e 64 73 7d 3c 2f 74 63 6c 3e   commands}</tcl>
14070 0a 3c 68 31 20 69 64 3d 63 6f 6d 6d 61 6e 64 73  .<h1 id=commands
14080 20 74 61 67 73 3d 22 63 6f 6d 6d 61 6e 64 73 22   tags="commands"
14090 3e 53 70 65 63 69 61 6c 20 43 6f 6d 6d 61 6e 64  >Special Command
140a0 73 20 46 6f 72 20 46 54 53 33 20 61 6e 64 20 46  s For FTS3 and F
140b0 54 53 34 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20 20  TS4</h1>..<p>.  
140c0 53 70 65 63 69 61 6c 20 49 4e 53 45 52 54 20 6f  Special INSERT o
140d0 70 65 72 61 74 65 73 20 63 61 6e 20 62 65 20 75  perates can be u
140e0 73 65 64 20 74 6f 20 69 73 73 75 65 20 63 6f 6d  sed to issue com
140f0 6d 61 6e 64 73 20 74 6f 20 46 54 53 33 20 61 6e  mands to FTS3 an
14100 64 20 46 54 53 34 20 74 61 62 6c 65 73 2e 0a 20  d FTS4 tables.. 
14110 20 45 76 65 72 79 20 46 54 53 33 20 61 6e 64 20   Every FTS3 and 
14120 46 54 53 34 20 68 61 73 20 61 20 68 69 64 64 65  FTS4 has a hidde
14130 6e 2c 20 72 65 61 64 2d 6f 6e 6c 79 20 63 6f 6c  n, read-only col
14140 75 6d 6e 20 77 68 69 63 68 20 69 73 20 74 68 65  umn which is the
14150 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 0a 20 20   same name as.  
14160 74 68 65 20 74 61 62 6c 65 20 69 74 73 65 6c 66  the table itself
14170 2e 20 20 49 4e 53 45 52 54 73 20 69 6e 74 6f 20  .  INSERTs into 
14180 74 68 69 73 20 68 69 64 64 65 6e 20 63 6f 6c 75  this hidden colu
14190 6d 6e 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  mn are interpret
141a0 65 64 20 61 73 20 63 6f 6d 6d 61 6e 64 73 0a 20  ed as commands. 
141b0 20 74 6f 20 74 68 65 20 46 54 53 33 2f 34 20 74   to the FTS3/4 t
141c0 61 62 6c 65 2e 20 20 46 6f 72 20 61 20 74 61 62  able.  For a tab
141d0 6c 65 20 77 69 74 68 20 74 68 65 20 6e 61 6d 65  le with the name
141e0 20 22 78 79 7a 22 20 74 68 65 20 66 6f 6c 6c 6f   "xyz" the follo
141f0 77 69 6e 67 20 63 6f 6d 6d 61 6e 64 73 0a 20 20  wing commands.  
14200 61 72 65 20 73 75 70 70 6f 72 74 65 64 3a 0a 0a  are supported:..
14210 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 49 4e 53 45  <ul>.<li><p>INSE
14220 52 54 20 49 4e 54 4f 20 78 79 7a 28 78 79 7a 29  RT INTO xyz(xyz)
14230 20 56 41 4c 55 45 53 28 27 6f 70 74 69 6d 69 7a   VALUES('optimiz
14240 65 27 29 3b 3c 2f 70 3e 0a 3c 6c 69 3e 3c 70 3e  e');</p>.<li><p>
14250 49 4e 53 45 52 54 20 49 4e 54 4f 20 78 79 7a 28  INSERT INTO xyz(
14260 78 79 7a 29 20 56 41 4c 55 45 53 28 27 72 65 62  xyz) VALUES('reb
14270 75 69 6c 64 27 29 3b 3c 2f 70 3e 0a 3c 6c 69 3e  uild');</p>.<li>
14280 3c 70 3e 49 4e 53 45 52 54 20 49 4e 54 4f 20 78  <p>INSERT INTO x
14290 79 7a 28 78 79 7a 29 20 56 41 4c 55 45 53 28 27  yz(xyz) VALUES('
142a0 69 6e 74 65 67 72 69 74 79 2d 63 68 65 63 6b 27  integrity-check'
142b0 29 3b 3c 2f 70 3e 0a 3c 6c 69 3e 3c 70 3e 49 4e  );</p>.<li><p>IN
142c0 53 45 52 54 20 49 4e 54 4f 20 78 79 7a 28 78 79  SERT INTO xyz(xy
142d0 7a 29 20 56 41 4c 55 45 53 28 27 6d 65 72 67 65  z) VALUES('merge
142e0 3d 58 2c 59 27 29 3b 3c 2f 70 3e 0a 3c 6c 69 3e  =X,Y');</p>.<li>
142f0 3c 70 3e 49 4e 53 45 52 54 20 49 4e 54 4f 20 78  <p>INSERT INTO x
14300 79 7a 28 78 79 7a 29 20 56 41 4c 55 45 53 28 27  yz(xyz) VALUES('
14310 61 75 74 6f 6d 65 72 67 65 3d 42 27 29 3b 3c 2f  automerge=B');</
14320 70 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 68  p>.</ul>..<tcl>h
14330 64 5f 66 72 61 67 6d 65 6e 74 20 2a 66 74 73 34  d_fragment *fts4
14340 6f 70 74 63 6d 64 20 7b 46 54 53 34 20 22 6f 70  optcmd {FTS4 "op
14350 74 69 6d 69 7a 65 22 20 63 6f 6d 6d 61 6e 64 7d  timize" command}
14360 20 5c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20   \.             
14370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
14380 7b 22 6f 70 74 69 6d 69 7a 65 22 20 63 6f 6d 6d  {"optimize" comm
14390 61 6e 64 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 20 69  and}</tcl>.<h2 i
143a0 64 3d 6f 70 74 69 6d 69 7a 65 3e 54 68 65 20 22  d=optimize>The "
143b0 6f 70 74 69 6d 69 7a 65 22 20 63 6f 6d 6d 61 6e  optimize" comman
143c0 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 54 68  d</h2>..<p>.  Th
143d0 65 20 22 6f 70 74 69 6d 69 7a 65 22 20 63 6f 6d  e "optimize" com
143e0 6d 61 6e 64 20 63 61 75 73 65 73 20 46 54 53 33  mand causes FTS3
143f0 2f 34 20 74 6f 20 6d 65 72 67 65 20 74 6f 67 65  /4 to merge toge
14400 74 68 65 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a  ther all of its.
14410 20 20 69 6e 76 65 72 74 65 64 20 69 6e 64 65 78    inverted index
14420 20 62 2d 74 72 65 65 73 20 69 6e 74 6f 20 6f 6e   b-trees into on
14430 65 20 6c 61 72 67 65 20 61 6e 64 20 63 6f 6d 70  e large and comp
14440 6c 65 74 65 20 62 2d 74 72 65 65 2e 20 20 44 6f  lete b-tree.  Do
14450 69 6e 67 0a 20 20 61 6e 20 6f 70 74 69 6d 69 7a  ing.  an optimiz
14460 65 20 77 69 6c 6c 20 6d 61 6b 65 20 73 75 62 73  e will make subs
14470 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 20 72  equent queries r
14480 75 6e 20 66 61 73 74 65 72 20 73 69 6e 63 65 20  un faster since 
14490 74 68 65 72 65 20 61 72 65 0a 20 20 66 65 77 65  there are.  fewe
144a0 72 20 62 2d 74 72 65 65 73 20 74 6f 20 73 65 61  r b-trees to sea
144b0 72 63 68 2c 20 61 6e 64 20 69 74 20 6d 61 79 20  rch, and it may 
144c0 72 65 64 75 63 65 20 64 69 73 6b 20 75 73 61 67  reduce disk usag
144d0 65 20 62 79 20 63 6f 61 6c 65 73 63 69 6e 67 0a  e by coalescing.
144e0 20 20 72 65 64 75 6e 64 61 6e 74 20 65 6e 74 72    redundant entr
144f0 69 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 66  ies.  However, f
14500 6f 72 20 61 20 6c 61 72 67 65 20 46 54 53 20 74  or a large FTS t
14510 61 62 6c 65 2c 20 72 75 6e 6e 69 6e 67 20 6f 70  able, running op
14520 74 69 6d 69 7a 65 0a 20 20 63 61 6e 20 62 65 20  timize.  can be 
14530 61 73 20 65 78 70 65 6e 73 69 76 65 20 61 73 20  as expensive as 
14540 72 75 6e 6e 69 6e 67 20 5b 56 41 43 55 55 4d 5d  running [VACUUM]
14550 2e 20 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 20  .  The optimize 
14560 63 6f 6d 6d 61 6e 64 0a 20 20 65 73 73 65 6e 74  command.  essent
14570 69 61 6c 6c 79 20 68 61 73 20 74 6f 20 72 65 61  ially has to rea
14580 64 20 61 6e 64 20 77 72 69 74 65 20 74 68 65 20  d and write the 
14590 65 6e 74 69 72 65 20 46 54 53 20 74 61 62 6c 65  entire FTS table
145a0 2c 20 72 65 73 75 6c 74 69 6e 67 0a 20 20 69 6e  , resulting.  in
145b0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
145c0 74 69 6f 6e 2e 0a 0a 3c 70 3e 0a 20 20 49 6e 20  tion...<p>.  In 
145d0 62 61 74 63 68 2d 6d 6f 64 65 20 6f 70 65 72 61  batch-mode opera
145e0 74 69 6f 6e 2c 20 77 68 65 72 65 20 61 6e 20 46  tion, where an F
145f0 54 53 20 74 61 62 6c 65 20 69 73 20 69 6e 69 74  TS table is init
14600 69 61 6c 6c 79 20 62 75 69 6c 74 20 75 70 0a 20  ially built up. 
14610 20 75 73 69 6e 67 20 61 20 6c 61 72 67 65 20 6e   using a large n
14620 75 6d 62 65 72 20 6f 66 20 49 4e 53 45 52 54 20  umber of INSERT 
14630 6f 70 65 72 61 74 69 6f 6e 73 2c 20 74 68 65 6e  operations, then
14640 20 71 75 65 72 69 65 64 20 72 65 70 65 61 74 65   queried repeate
14650 64 6c 79 0a 20 20 77 69 74 68 6f 75 74 20 66 75  dly.  without fu
14660 72 74 68 65 72 20 63 68 61 6e 67 65 73 2c 20 69  rther changes, i
14670 74 20 69 73 20 6f 66 74 65 6e 20 61 20 67 6f 6f  t is often a goo
14680 64 20 69 64 65 61 0a 20 20 74 6f 20 72 75 6e 20  d idea.  to run 
14690 22 6f 70 74 69 6d 69 7a 65 22 20 61 66 74 65 72  "optimize" after
146a0 20 74 68 65 20 6c 61 73 74 20 49 4e 53 45 52 54   the last INSERT
146b0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
146c0 66 69 72 73 74 20 71 75 65 72 79 2e 0a 0a 3c 74  first query...<t
146d0 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 2a  cl>hd_fragment *
146e0 66 74 73 34 72 65 62 75 69 64 63 6d 64 20 7b 46  fts4rebuidcmd {F
146f0 54 53 34 20 22 72 65 62 75 69 6c 64 22 20 63 6f  TS4 "rebuild" co
14700 6d 6d 61 6e 64 7d 20 5c 0a 20 20 20 20 20 20 20  mmand} \.       
14710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
14720 20 20 20 20 20 20 20 20 20 7b 22 72 65 62 75 69           {"rebui
14730 6c 64 22 20 63 6f 6d 6d 61 6e 64 7d 3c 2f 74 63  ld" command}</tc
14740 6c 3e 0a 3c 68 32 20 69 64 3d 72 65 62 75 69 6c  l>.<h2 id=rebuil
14750 64 3e 54 68 65 20 22 72 65 62 75 69 6c 64 22 20  d>The "rebuild" 
14760 63 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70  command</h2>..<p
14770 3e 0a 20 20 54 68 65 20 22 72 65 62 75 69 6c 64  >.  The "rebuild
14780 22 20 63 6f 6d 6d 61 6e 64 20 63 61 75 73 65 73  " command causes
14790 20 53 51 4c 69 74 65 20 74 6f 20 64 69 73 63 61   SQLite to disca
147a0 72 64 20 74 68 65 20 65 6e 74 69 72 65 20 46 54  rd the entire FT
147b0 53 33 2f 34 0a 20 20 74 61 62 6c 65 20 61 6e 64  S3/4.  table and
147c0 20 74 68 65 6e 20 72 65 62 75 69 6c 64 20 69 74   then rebuild it
147d0 20 61 67 61 69 6e 20 66 72 6f 6d 20 6f 72 69 67   again from orig
147e0 69 6e 61 6c 20 74 65 78 74 2e 20 20 54 68 65 20  inal text.  The 
147f0 63 6f 6e 63 65 70 74 0a 20 20 69 73 20 73 69 6d  concept.  is sim
14800 69 6c 61 72 20 74 6f 20 5b 52 45 49 4e 44 45 58  ilar to [REINDEX
14810 5d 2c 20 6f 6e 6c 79 20 74 68 61 74 20 69 74 20  ], only that it 
14820 61 70 70 6c 69 65 73 20 74 6f 20 61 6e 0a 20 20  applies to an.  
14830 46 54 53 33 2f 34 20 74 61 62 6c 65 20 69 6e 73  FTS3/4 table ins
14840 74 65 61 64 20 6f 66 20 61 6e 20 6f 72 64 69 6e  tead of an ordin
14850 61 72 79 20 69 6e 64 65 78 2e 0a 0a 3c 70 3e 0a  ary index...<p>.
14860 20 20 54 68 65 20 22 72 65 62 75 69 6c 64 22 20    The "rebuild" 
14870 63 6f 6d 6d 61 6e 64 20 73 68 6f 75 6c 64 20 62  command should b
14880 65 20 72 75 6e 20 77 68 65 6e 65 76 65 72 20 74  e run whenever t
14890 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
148a0 6e 0a 20 20 6f 66 20 61 20 63 75 73 74 6f 6d 20  n.  of a custom 
148b0 74 6f 6b 65 6e 69 7a 65 72 20 63 68 61 6e 67 65  tokenizer change
148c0 73 2c 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 63  s, so that all c
148d0 6f 6e 74 65 6e 74 20 63 61 6e 20 62 65 20 72 65  ontent can be re
148e0 74 6f 6b 65 6e 69 7a 65 64 2e 0a 20 20 54 68 65  tokenized..  The
148f0 20 22 72 65 62 75 69 6c 64 22 20 63 6f 6d 6d 61   "rebuild" comma
14900 6e 64 20 69 73 20 61 6c 73 6f 20 75 73 65 66 75  nd is also usefu
14910 6c 20 77 68 65 6e 20 75 73 69 6e 67 20 74 68 65  l when using the
14920 0a 20 20 5b 46 54 53 34 20 63 6f 6e 74 65 6e 74  .  [FTS4 content
14930 20 6f 70 74 69 6f 6e 5d 20 61 66 74 65 72 20 63   option] after c
14940 68 61 6e 67 65 73 20 68 61 76 65 20 62 65 65 6e  hanges have been
14950 20 6d 61 64 65 20 74 6f 20 74 68 65 20 6f 72 69   made to the ori
14960 67 69 6e 61 6c 0a 20 20 63 6f 6e 74 65 6e 74 20  ginal.  content 
14970 74 61 62 6c 65 2e 0a 0a 3c 74 63 6c 3e 68 64 5f  table...<tcl>hd_
14980 66 72 61 67 6d 65 6e 74 20 2a 66 74 73 34 69 63  fragment *fts4ic
14990 6b 63 6d 64 20 7b 46 54 53 34 20 22 69 6e 74 65  kcmd {FTS4 "inte
149a0 67 72 69 74 79 2d 63 68 65 63 6b 22 20 63 6f 6d  grity-check" com
149b0 6d 61 6e 64 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 20  mand}</tcl>.<h2 
149c0 69 64 3d 69 6e 74 65 67 63 68 65 63 6b 3e 54 68  id=integcheck>Th
149d0 65 20 22 69 6e 74 65 67 72 69 74 79 2d 63 68 65  e "integrity-che
149e0 63 6b 22 20 63 6f 6d 6d 61 6e 64 3c 2f 68 32 3e  ck" command</h2>
149f0 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 22 69 6e 74  ..<p>.  The "int
14a00 65 67 72 69 74 79 2d 63 68 65 63 6b 22 20 63 6f  egrity-check" co
14a10 6d 6d 61 6e 64 20 63 61 75 73 65 73 20 53 51 4c  mmand causes SQL
14a20 69 74 65 20 74 6f 20 72 65 61 64 20 61 6e 64 20  ite to read and 
14a30 76 65 72 69 66 79 0a 20 20 74 68 65 20 61 63 63  verify.  the acc
14a40 75 72 61 63 79 20 6f 66 20 61 6c 6c 20 69 6e 76  uracy of all inv
14a50 65 72 74 65 64 20 69 6e 64 69 63 65 73 20 69 6e  erted indices in
14a60 20 61 6e 20 46 54 53 33 2f 34 20 74 61 62 6c 65   an FTS3/4 table
14a70 20 62 79 20 63 6f 6d 70 61 72 69 6e 67 0a 20 20   by comparing.  
14a80 74 68 6f 73 65 20 69 6e 76 65 72 74 65 64 20 69  those inverted i
14a90 6e 64 69 63 65 73 20 61 67 61 69 6e 73 74 20 74  ndices against t
14aa0 68 65 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6e 74  he original cont
14ab0 65 6e 74 2e 20 54 68 65 20 0a 20 20 22 69 6e 74  ent. The .  "int
14ac0 65 67 72 69 74 79 2d 63 68 65 63 6b 22 20 63 6f  egrity-check" co
14ad0 6d 6d 61 6e 64 20 73 69 6c 65 6e 74 6c 79 20 73  mmand silently s
14ae0 75 63 63 65 65 64 73 20 69 66 20 74 68 65 20 69  ucceeds if the i
14af0 6e 76 65 72 74 65 64 0a 20 20 69 6e 64 69 63 65  nverted.  indice
14b00 73 20 61 72 65 20 61 6c 6c 20 6f 6b 2c 20 62 75  s are all ok, bu
14b10 74 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  t will fail with
14b20 20 61 6e 20 53 51 4c 49 54 45 5f 43 4f 52 52 55   an SQLITE_CORRU
14b30 50 54 20 65 72 72 6f 72 0a 20 20 69 66 20 61 6e  PT error.  if an
14b40 79 20 70 72 6f 62 6c 65 6d 73 20 61 72 65 20 66  y problems are f
14b50 6f 75 6e 64 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65  ound...<p>.  The
14b60 20 22 69 6e 74 65 67 72 69 74 79 2d 63 68 65 63   "integrity-chec
14b70 6b 22 20 63 6f 6d 6d 61 6e 64 20 69 73 20 73 69  k" command is si
14b80 6d 69 6c 61 72 20 69 6e 20 63 6f 6e 63 65 70 74  milar in concept
14b90 20 74 6f 0a 20 5b 50 52 41 47 4d 41 20 69 6e 74   to. [PRAGMA int
14ba0 65 67 72 69 74 79 5f 63 68 65 63 6b 5d 2e 20 20  egrity_check].  
14bb0 49 6e 20 61 20 77 6f 72 6b 69 6e 67 20 73 79 73  In a working sys
14bc0 74 65 6d 2c 20 74 68 65 20 22 69 6e 74 65 67 72  tem, the "integr
14bd0 69 74 79 2d 63 6f 6d 6d 61 6e 64 22 0a 20 73 68  ity-command". sh
14be0 6f 75 6c 64 20 61 77 61 79 73 20 62 65 20 73 75  ould aways be su
14bf0 63 63 65 73 73 66 75 6c 2e 20 20 50 6f 73 73 69  ccessful.  Possi
14c00 62 6c 65 20 63 61 75 73 65 73 20 6f 66 20 69 6e  ble causes of in
14c10 74 65 67 72 69 74 79 2d 63 68 65 63 6b 0a 20 66  tegrity-check. f
14c20 61 69 6c 75 72 65 73 20 69 6e 63 6c 75 64 65 3a  ailures include:
14c30 0a 20 20 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 54  .  <ul>.  <li> T
14c40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
14c50 61 73 20 6d 61 64 65 20 63 68 61 6e 67 65 73 20  as made changes 
14c60 74 6f 20 74 68 65 20 5b 46 54 53 20 73 68 61 64  to the [FTS shad
14c70 6f 77 20 74 61 62 6c 65 73 5d 0a 20 20 20 20 20  ow tables].     
14c80 20 20 64 69 72 65 63 74 6c 79 2c 20 77 69 74 68    directly, with
14c90 6f 75 74 20 75 73 69 6e 67 20 74 68 65 20 46 54  out using the FT
14ca0 53 33 2f 34 20 76 69 72 74 75 61 6c 20 74 61 62  S3/4 virtual tab
14cb0 6c 65 2c 20 63 61 75 73 69 6e 67 0a 20 20 20 20  le, causing.    
14cc0 20 20 20 74 68 65 20 73 68 61 64 6f 77 20 74 61     the shadow ta
14cd0 62 6c 65 73 20 74 6f 20 62 65 63 6f 6d 65 20 6f  bles to become o
14ce0 75 74 20 6f 66 20 73 79 6e 63 20 77 69 74 68 20  ut of sync with 
14cf0 65 61 63 68 20 6f 74 68 65 72 2e 0a 20 20 3c 6c  each other..  <l
14d00 69 3e 20 55 73 69 6e 67 20 74 68 65 20 5b 46 54  i> Using the [FT
14d10 53 34 20 63 6f 6e 74 65 6e 74 20 6f 70 74 69 6f  S4 content optio
14d20 6e 5d 20 61 6e 64 20 66 61 69 6c 69 6e 67 20 74  n] and failing t
14d30 6f 20 6d 61 6e 75 61 6c 6c 79 20 6b 65 65 70 0a  o manually keep.
14d40 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 74 65         the conte
14d50 6e 74 20 69 6e 20 73 79 6e 63 20 77 69 74 68 20  nt in sync with 
14d60 74 68 65 20 46 54 53 34 20 69 6e 76 65 72 74 65  the FTS4 inverte
14d70 64 20 69 6e 64 69 63 65 73 2e 0a 20 20 3c 6c 69  d indices..  <li
14d80 3e 20 42 75 67 73 20 69 6e 20 74 68 65 20 46 54  > Bugs in the FT
14d90 53 33 2f 34 20 76 69 72 74 75 61 6c 20 74 61 62  S3/4 virtual tab
14da0 6c 65 2e 20 20 28 54 68 65 20 22 69 6e 74 65 67  le.  (The "integ
14db0 72 69 74 79 2d 63 68 65 63 6b 22 0a 20 20 20 20  rity-check".    
14dc0 20 20 20 63 6f 6d 6d 61 6e 64 20 77 61 73 20 6f     command was o
14dd0 72 69 67 69 6e 61 6c 20 63 6f 6e 63 65 69 76 65  riginal conceive
14de0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
14df0 20 74 65 73 74 20 73 75 69 74 65 0a 20 20 20 20   test suite.    
14e00 20 20 20 66 6f 72 20 46 54 53 33 2f 34 2e 29 0a     for FTS3/4.).
14e10 20 20 3c 6c 69 3e 20 43 6f 72 72 75 70 74 69 6f    <li> Corruptio
14e20 6e 20 74 6f 20 74 68 65 20 75 6e 64 65 72 6c 79  n to the underly
14e30 69 6e 67 20 53 51 4c 69 74 65 20 64 61 74 61 62  ing SQLite datab
14e40 61 73 65 20 66 69 6c 65 2e 20 20 28 53 65 65 0a  ase file.  (See.
14e50 20 20 20 20 20 20 20 64 6f 63 75 6d 65 6e 74 61         documenta
14e60 74 69 6f 6e 20 6f 6e 20 5b 68 6f 77 20 74 6f 20  tion on [how to 
14e70 63 6f 72 72 75 70 74 5d 20 61 6e 64 20 53 51 4c  corrupt] and SQL
14e80 69 74 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  ite database for
14e90 0a 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e  .       addition
14ea0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 29  al information.)
14eb0 0a 20 20 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e 68  .  </ul>..<tcl>h
14ec0 64 5f 66 72 61 67 6d 65 6e 74 20 2a 66 74 73 34  d_fragment *fts4
14ed0 6d 65 72 67 65 63 6d 64 20 7b 46 54 53 34 20 22  mergecmd {FTS4 "
14ee0 6d 65 72 67 65 22 20 63 6f 6d 6d 61 6e 64 7d 20  merge" command} 
14ef0 7b 22 6d 65 72 67 65 22 20 63 6f 6d 6d 61 6e 64  {"merge" command
14f00 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 20 69 64 3d 22  }</tcl>.<h2 id="
14f10 6d 65 72 67 65 63 6d 64 22 3e 54 68 65 20 22 6d  mergecmd">The "m
14f20 65 72 67 65 3d 58 2c 59 22 20 63 6f 6d 6d 61 6e  erge=X,Y" comman
14f30 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 54 68  d</h2>..<p>.  Th
14f40 65 20 22 6d 65 72 67 65 3d 58 2c 59 22 20 63 6f  e "merge=X,Y" co
14f50 6d 6d 61 6e 64 20 28 77 68 65 72 65 20 58 20 61  mmand (where X a
14f60 6e 64 20 59 20 61 72 65 20 69 6e 74 65 67 65 72  nd Y are integer
14f70 73 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  s) causes SQLite
14f80 0a 20 20 74 6f 20 64 6f 20 61 20 6c 69 6d 69 74  .  to do a limit
14f90 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 77 6f 72  ed amount of wor
14fa0 6b 20 74 6f 77 61 72 64 20 6d 65 72 67 69 6e 67  k toward merging
14fb0 20 74 68 65 20 76 61 72 69 6f 75 73 20 69 6e 76   the various inv
14fc0 65 72 74 65 64 0a 20 20 69 6e 64 65 78 20 62 2d  erted.  index b-
14fd0 74 72 65 65 73 20 6f 66 20 61 6e 20 46 54 53 33  trees of an FTS3
14fe0 2f 34 20 74 61 62 6c 65 20 74 6f 67 65 74 68 65  /4 table togethe
14ff0 72 20 69 6e 74 6f 20 6f 6e 65 20 6c 61 72 67 65  r into one large
15000 20 62 2d 74 72 65 65 2e 0a 20 20 54 68 65 20 58   b-tree..  The X
15010 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 74 61   value is the ta
15020 72 67 65 74 20 6e 75 6d 62 65 72 20 6f 66 20 22  rget number of "
15030 62 6c 6f 63 6b 73 22 20 74 6f 20 62 65 20 6d 65  blocks" to be me
15040 72 67 65 64 2c 20 61 6e 64 20 59 20 69 73 0a 20  rged, and Y is. 
15050 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6e 75 6d   the minimum num
15060 62 65 72 20 6f 66 20 62 2d 74 72 65 65 20 73 65  ber of b-tree se
15070 67 6d 65 6e 74 73 20 6f 6e 20 61 20 6c 65 76 65  gments on a leve
15080 6c 20 72 65 71 75 69 72 65 64 20 62 65 66 6f 72  l required befor
15090 65 0a 20 20 6d 65 72 67 69 6e 67 20 77 69 6c 6c  e.  merging will
150a0 20 62 65 20 61 70 70 6c 69 65 64 20 74 6f 20 74   be applied to t
150b0 68 61 74 20 6c 65 76 65 6c 2e 20 20 54 68 65 20  hat level.  The 
150c0 76 61 6c 75 65 20 6f 66 20 59 20 73 68 6f 75 6c  value of Y shoul
150d0 64 0a 20 20 62 65 20 62 65 74 77 65 65 6e 20 32  d.  be between 2
150e0 20 61 6e 64 20 31 36 20 77 69 74 68 20 61 20 72   and 16 with a r
150f0 65 63 6f 6d 6d 65 6e 64 65 64 20 76 61 6c 75 65  ecommended value
15100 20 6f 66 20 38 2e 20 20 54 68 65 20 76 61 6c 75   of 8.  The valu
15110 65 20 6f 66 20 58 0a 20 20 63 61 6e 20 62 65 20  e of X.  can be 
15120 61 6e 79 20 70 6f 73 69 74 69 76 65 20 69 6e 74  any positive int
15130 65 67 65 72 20 62 75 74 20 76 61 6c 75 65 73 20  eger but values 
15140 6f 6e 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  on the order of 
15150 31 30 30 20 74 6f 20 33 30 30 0a 20 20 61 72 65  100 to 300.  are
15160 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 0a 3c   recommended...<
15170 70 3e 0a 20 20 57 68 65 6e 20 61 6e 20 46 54 53  p>.  When an FTS
15180 20 74 61 62 6c 65 20 61 63 63 75 6d 75 6c 61 74   table accumulat
15190 65 73 20 31 36 20 62 2d 74 72 65 65 20 73 65 67  es 16 b-tree seg
151a0 6d 65 6e 74 73 20 61 74 20 74 68 65 20 73 61 6d  ments at the sam
151b0 65 20 6c 65 76 65 6c 2c 0a 20 20 74 68 65 20 6e  e level,.  the n
151c0 65 78 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 20  ext INSERT into 
151d0 74 68 61 74 20 74 61 62 6c 65 20 77 69 6c 6c 20  that table will 
151e0 63 61 75 73 65 20 61 6c 6c 20 31 36 20 73 65 67  cause all 16 seg
151f0 6d 65 6e 74 73 20 74 6f 20 62 65 0a 20 20 6d 65  ments to be.  me
15200 72 67 65 64 20 69 6e 74 6f 20 61 20 73 69 6e 67  rged into a sing
15210 6c 65 20 62 2d 74 72 65 65 20 73 65 67 6d 65 6e  le b-tree segmen
15220 74 20 61 74 20 74 68 65 20 6e 65 78 74 20 68 69  t at the next hi
15230 67 68 65 72 20 6c 65 76 65 6c 2e 20 20 54 68 65  gher level.  The
15240 0a 20 20 65 66 66 65 63 74 20 6f 66 20 74 68 65  .  effect of the
15250 73 65 20 6c 65 76 65 6c 20 6d 65 72 67 65 73 20  se level merges 
15260 69 73 20 74 68 61 74 20 6d 6f 73 74 20 49 4e 53  is that most INS
15270 45 52 54 73 20 69 6e 74 6f 20 61 6e 20 46 54 53  ERTs into an FTS
15280 20 74 61 62 6c 65 0a 20 20 61 72 65 20 76 65 72   table.  are ver
15290 79 20 66 61 73 74 20 61 6e 64 20 74 61 6b 65 20  y fast and take 
152a0 6d 69 6e 69 6d 61 6c 20 6d 65 6d 6f 72 79 2c 20  minimal memory, 
152b0 62 75 74 20 61 6e 20 6f 63 63 61 73 69 6f 6e 61  but an occasiona
152c0 6c 20 49 4e 53 45 52 54 20 69 73 0a 20 20 73 6c  l INSERT is.  sl
152d0 6f 77 20 61 6e 64 20 67 65 6e 65 72 61 74 65 73  ow and generates
152e0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
152f0 74 69 6f 6e 20 62 65 63 61 75 73 65 20 6f 66 20  tion because of 
15300 74 68 65 20 6e 65 65 64 20 74 6f 0a 20 20 64 6f  the need to.  do
15310 20 6d 65 72 67 69 6e 67 2e 20 54 68 69 73 20 72   merging. This r
15320 65 73 75 6c 74 73 20 69 6e 20 22 73 70 69 6b 79  esults in "spiky
15330 22 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 66  " performance of
15340 20 49 4e 53 45 52 54 73 2e 0a 0a 3c 70 3e 0a 20   INSERTs...<p>. 
15350 20 54 6f 20 61 76 6f 69 64 20 73 70 69 6b 79 20   To avoid spiky 
15360 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 61 6e  INSERT performan
15370 63 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ce, an applicati
15380 6f 6e 20 63 61 6e 20 72 75 6e 20 74 68 65 0a 20  on can run the. 
15390 20 22 6d 65 72 67 65 3d 58 2c 59 22 20 63 6f 6d   "merge=X,Y" com
153a0 6d 61 6e 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  mand periodicall
153b0 79 2c 20 70 6f 73 73 69 62 6c 79 20 69 6e 20 61  y, possibly in a
153c0 6e 20 69 64 6c 65 20 74 68 72 65 61 64 20 6f 72  n idle thread or
153d0 0a 20 20 69 64 6c 65 20 70 72 6f 63 65 73 73 2c  .  idle process,
153e0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
153f0 74 68 65 20 46 54 53 20 74 61 62 6c 65 20 6e 65  the FTS table ne
15400 76 65 72 20 61 63 63 75 6d 75 6c 61 74 65 73 0a  ver accumulates.
15410 20 20 74 6f 6f 20 6d 61 6e 79 20 62 2d 74 72 65    too many b-tre
15420 65 20 73 65 67 6d 65 6e 74 73 20 61 74 20 74 68  e segments at th
15430 65 20 73 61 6d 65 20 6c 65 76 65 6c 2e 20 20 49  e same level.  I
15440 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 61 6e 63  NSERT performanc
15450 65 0a 20 20 73 70 69 6b 65 73 20 63 61 6e 20 67  e.  spikes can g
15460 65 6e 65 72 61 6c 6c 79 20 62 65 20 61 76 6f 69  enerally be avoi
15470 64 65 64 2c 20 61 6e 64 20 70 65 72 66 6f 72 6d  ded, and perform
15480 61 6e 63 65 20 6f 66 20 46 54 53 33 2f 34 20 63  ance of FTS3/4 c
15490 61 6e 20 62 65 0a 20 20 6d 61 78 69 6d 69 7a 65  an be.  maximize
154a0 64 2c 20 62 79 20 72 75 6e 6e 69 6e 67 20 22 6d  d, by running "m
154b0 65 72 67 65 3d 58 2c 59 22 20 61 66 74 65 72 20  erge=X,Y" after 
154c0 65 76 65 72 79 20 66 65 77 20 74 68 6f 75 73 61  every few thousa
154d0 6e 64 0a 20 20 64 6f 63 75 6d 65 6e 74 20 69 6e  nd.  document in
154e0 73 65 72 74 73 2e 20 20 45 61 63 68 20 22 6d 65  serts.  Each "me
154f0 72 67 65 3d 58 2c 59 22 20 63 6f 6d 6d 61 6e 64  rge=X,Y" command
15500 20 77 69 6c 6c 20 72 75 6e 20 69 6e 20 61 20 73   will run in a s
15510 65 70 61 72 61 74 65 0a 20 20 74 72 61 6e 73 61  eparate.  transa
15520 63 74 69 6f 6e 20 28 75 6e 6c 65 73 73 20 74 68  ction (unless th
15530 65 79 20 61 72 65 20 67 72 6f 75 70 65 64 20 74  ey are grouped t
15540 6f 67 65 74 68 65 72 20 75 73 69 6e 67 20 5b 42  ogether using [B
15550 45 47 49 4e 5d 2e 2e 2e 5b 43 4f 4d 4d 49 54 5d  EGIN]...[COMMIT]
15560 2c 0a 20 20 6f 66 20 63 6f 75 72 73 65 29 2e 20  ,.  of course). 
15570 20 54 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   The transaction
15580 73 20 63 61 6e 20 62 65 20 6b 65 70 74 20 73 6d  s can be kept sm
15590 61 6c 6c 20 62 79 20 63 68 6f 6f 73 69 6e 67 20  all by choosing 
155a0 61 20 76 61 6c 75 65 0a 20 20 66 6f 72 20 58 20  a value.  for X 
155b0 69 6e 20 74 68 65 20 72 61 6e 67 65 20 6f 66 20  in the range of 
155c0 31 30 30 20 74 6f 20 33 30 30 2e 20 20 54 68 65  100 to 300.  The
155d0 20 69 64 6c 65 20 74 68 72 65 61 64 20 74 68 61   idle thread tha
155e0 74 20 69 73 20 72 75 6e 6e 69 6e 67 0a 20 20 74  t is running.  t
155f0 68 65 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64  he merge command
15600 73 20 63 61 6e 20 6b 6e 6f 77 20 77 68 65 6e 20  s can know when 
15610 69 74 20 69 73 20 64 6f 6e 65 20 62 79 20 63 68  it is done by ch
15620 65 63 6b 69 6e 67 20 74 68 65 20 64 69 66 66 65  ecking the diffe
15630 72 65 6e 63 65 0a 20 20 69 6e 20 5b 73 71 6c 69  rence.  in [sqli
15640 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
15650 73 28 29 5d 20 62 65 66 6f 72 65 20 61 6e 64 20  s()] before and 
15660 61 66 74 65 72 20 65 61 63 68 20 22 6d 65 72 67  after each "merg
15670 65 3d 58 2c 59 22 0a 20 20 63 6f 6d 6d 61 6e 64  e=X,Y".  command
15680 20 61 6e 64 20 73 74 6f 70 70 69 6e 67 20 74 68   and stopping th
15690 65 20 6c 6f 6f 70 20 77 68 65 6e 20 74 68 65 20  e loop when the 
156a0 64 69 66 66 65 72 65 6e 63 65 20 64 72 6f 70 73  difference drops
156b0 20 62 65 6c 6f 77 20 74 77 6f 2e 0a 0a 3c 74 63   below two...<tc
156c0 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 2a 66  l>hd_fragment *f
156d0 74 73 34 61 75 74 6f 6d 65 72 67 65 63 6d 64 20  ts4automergecmd 
156e0 7b 46 54 53 34 20 22 61 75 74 6f 6d 65 72 67 65  {FTS4 "automerge
156f0 22 20 63 6f 6d 6d 61 6e 64 7d 20 5c 0a 20 20 20  " command} \.   
15700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15720 7b 22 61 75 74 6f 6d 65 72 67 65 22 20 63 6f 6d  {"automerge" com
15730 6d 61 6e 64 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 20  mand}</tcl>.<h2 
15740 69 64 3d 61 75 74 6f 6d 65 72 67 65 22 3e 54 68  id=automerge">Th
15750 65 20 22 61 75 74 6f 6d 65 72 67 65 3d 42 22 20  e "automerge=B" 
15760 63 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70  command</h2>..<p
15770 3e 0a 20 20 54 68 65 20 22 61 75 74 6f 6d 65 72  >.  The "automer
15780 67 65 3d 42 22 20 63 6f 6d 6d 61 6e 64 20 28 77  ge=B" command (w
15790 68 65 72 65 20 42 20 69 73 20 65 69 74 68 65 72  here B is either
157a0 20 22 31 22 20 6f 72 20 22 30 22 29 20 64 69 73   "1" or "0") dis
157b0 61 62 6c 65 73 0a 20 20 6f 72 20 65 6e 61 62 6c  ables.  or enabl
157c0 65 73 20 61 75 74 6f 6d 61 74 69 63 20 69 6e 63  es automatic inc
157d0 72 65 6d 65 6e 74 61 6c 20 69 6e 76 65 72 74 65  remental inverte
157e0 64 20 69 6e 64 65 78 20 6d 65 72 67 69 6e 67 20  d index merging 
157f0 66 6f 72 20 61 6e 0a 20 20 46 54 53 33 2f 34 20  for an.  FTS3/4 
15800 74 61 62 6c 65 2e 20 20 54 68 65 20 64 65 66 61  table.  The defa
15810 75 6c 74 20 66 6f 72 20 6e 65 77 20 74 61 62 6c  ult for new tabl
15820 65 73 20 69 73 20 66 6f 72 20 61 75 74 6f 6d 61  es is for automa
15830 74 69 63 20 69 6e 63 72 65 6d 65 6e 74 61 6c 0a  tic incremental.
15840 20 20 6d 65 72 67 69 6e 67 20 74 6f 20 62 65 20    merging to be 
15850 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 22  disabled.  The "
15860 61 75 74 6f 6d 65 72 67 65 3d 42 22 20 63 6f 6d  automerge=B" com
15870 6d 61 6e 64 20 63 68 61 6e 67 65 73 20 74 68 69  mand changes thi
15880 73 0a 20 20 73 65 74 74 69 6e 67 2e 20 20 54 68  s.  setting.  Th
15890 65 20 63 68 61 6e 67 65 20 69 73 20 70 65 72 73  e change is pers
158a0 69 73 74 65 6e 74 20 61 6e 64 20 63 6f 6e 74 69  istent and conti
158b0 6e 75 65 73 20 74 6f 20 62 65 20 69 6e 20 65 66  nues to be in ef
158c0 66 65 63 74 0a 20 20 66 6f 72 20 61 6c 6c 20 73  fect.  for all s
158d0 75 62 73 65 71 75 65 6e 74 20 64 61 74 61 62 61  ubsequent databa
158e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74  se connections t
158f0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
15900 61 73 65 2e 0a 0a 3c 70 3e 0a 20 20 45 6e 61 62  ase...<p>.  Enab
15910 6c 69 6e 67 20 61 75 74 6f 6d 61 74 69 63 20 69  ling automatic i
15920 6e 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 65  ncremental merge
15930 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
15940 6f 20 64 6f 20 61 20 73 6d 61 6c 6c 0a 20 20 61  o do a small.  a
15950 6d 6f 75 6e 74 20 6f 66 20 69 6e 76 65 72 74 65  mount of inverte
15960 64 20 69 6e 64 65 78 20 6d 65 72 67 69 6e 67 20  d index merging 
15970 61 66 74 65 72 20 65 76 65 72 79 20 49 4e 53 45  after every INSE
15980 52 54 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 20 20  RT operation..  
15990 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  The amount of me
159a0 72 67 69 6e 67 20 70 65 72 66 6f 72 6d 65 64 20  rging performed 
159b0 69 73 20 64 65 73 69 67 6e 65 64 20 73 6f 20 74  is designed so t
159c0 68 61 74 20 74 68 65 20 46 54 53 33 2f 34 0a 20  hat the FTS3/4. 
159d0 20 74 61 62 6c 65 20 6e 65 76 65 72 20 72 65 61   table never rea
159e0 63 68 65 73 20 61 20 70 6f 69 6e 74 20 77 68 65  ches a point whe
159f0 72 65 20 69 74 20 68 61 73 20 31 36 20 73 65 67  re it has 16 seg
15a00 6d 65 6e 74 73 20 61 74 20 74 68 65 20 73 61 6d  ments at the sam
15a10 65 0a 20 20 6c 65 76 65 6c 20 61 6e 64 20 68 65  e.  level and he
15a20 6e 63 65 20 68 61 73 20 74 6f 20 64 6f 20 61 20  nce has to do a 
15a30 6c 61 72 67 65 20 6d 65 72 67 65 20 69 6e 20 6f  large merge in o
15a40 72 64 65 72 20 74 6f 20 63 6f 6d 70 6c 65 74 65  rder to complete
15a50 20 61 6e 0a 20 20 69 6e 73 65 72 74 2e 20 20 49   an.  insert.  I
15a60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 61  n other words, a
15a70 75 74 6f 6d 61 74 69 63 20 69 6e 63 72 65 6d 65  utomatic increme
15a80 6e 74 61 6c 20 6d 65 72 67 69 6e 67 20 69 73 20  ntal merging is 
15a90 64 65 73 69 67 6e 65 64 0a 20 20 74 6f 20 70 72  designed.  to pr
15aa0 65 76 65 6e 74 20 73 70 69 6b 79 20 49 4e 53 45  event spiky INSE
15ab0 52 54 20 70 65 72 66 6f 72 6d 61 6e 63 65 2e 0a  RT performance..
15ac0 0a 3c 70 3e 0a 20 20 54 68 65 20 64 6f 77 6e 73  .<p>.  The downs
15ad0 69 64 65 20 6f 66 20 61 75 74 6f 6d 61 74 69 63  ide of automatic
15ae0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72   incremental mer
15af0 67 69 6e 67 20 69 73 20 74 68 61 74 20 69 74 20  ging is that it 
15b00 6d 61 6b 65 73 0a 20 20 65 76 65 72 79 20 49 4e  makes.  every IN
15b10 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
15b20 64 20 44 45 4c 45 54 45 20 6f 70 65 72 61 74 69  d DELETE operati
15b30 6f 6e 20 6f 6e 20 61 6e 20 46 54 53 33 2f 34 20  on on an FTS3/4 
15b40 74 61 62 6c 65 20 72 75 6e 0a 20 20 61 20 6c 69  table run.  a li
15b50 74 74 6c 65 20 73 6c 6f 77 65 72 2c 20 73 69 6e  ttle slower, sin
15b60 63 65 20 65 78 74 72 61 20 74 69 6d 65 20 6d 75  ce extra time mu
15b70 73 74 20 62 65 20 75 73 65 64 20 74 6f 20 64 6f  st be used to do
15b80 20 74 68 65 20 69 6e 63 72 65 6d 65 6e 74 61 6c   the incremental
15b90 0a 20 20 6d 65 72 67 65 2e 20 20 46 6f 72 20 6d  .  merge.  For m
15ba0 61 78 69 6d 75 6d 20 70 65 72 66 6f 72 6d 61 6e  aximum performan
15bb0 63 65 2c 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ce, it is recomm
15bc0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
15bd0 63 61 74 69 6f 6e 73 0a 20 20 64 69 73 61 62 6c  cations.  disabl
15be0 65 20 61 75 74 6f 6d 61 74 69 63 20 69 6e 63 72  e automatic incr
15bf0 65 6d 65 6e 74 61 6c 20 6d 65 72 67 65 20 61 6e  emental merge an
15c00 64 20 69 6e 73 74 65 61 64 20 75 73 65 20 74 68  d instead use th
15c10 65 20 0a 20 20 5b 22 6d 65 72 67 65 22 20 63 6f  e .  ["merge" co
15c20 6d 6d 61 6e 64 5d 20 69 6e 20 61 6e 20 69 64 6c  mmand] in an idl
15c30 65 20 70 72 6f 63 65 73 73 20 74 6f 20 6b 65 65  e process to kee
15c40 70 20 74 68 65 20 69 6e 76 65 72 74 65 64 20 69  p the inverted i
15c50 6e 64 69 63 65 73 0a 20 20 77 65 6c 6c 20 6d 65  ndices.  well me
15c60 72 67 65 64 2e 20 20 42 75 74 20 69 66 20 74 68  rged.  But if th
15c70 65 20 73 74 72 75 63 74 75 72 65 20 6f 66 20 61  e structure of a
15c80 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  n application do
15c90 65 73 20 6e 6f 74 20 65 61 73 69 6c 79 0a 20 20  es not easily.  
15ca0 61 6c 6c 6f 77 20 66 6f 72 20 69 64 6c 65 20 70  allow for idle p
15cb0 72 6f 63 65 73 73 65 73 2c 20 74 68 65 20 75 73  rocesses, the us
15cc0 65 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 69  e of automatic i
15cd0 6e 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 65  ncremental merge
15ce0 20 69 73 0a 20 20 61 20 76 65 72 79 20 72 65 61   is.  a very rea
15cf0 73 6f 6e 61 62 6c 65 20 66 61 6c 6c 62 61 63 6b  sonable fallback
15d00 20 73 6f 6c 75 74 69 6f 6e 2e 0a 0a 0a 3c 68 31   solution....<h1
15d10 20 69 64 3d 74 6f 6b 65 6e 69 7a 65 72 20 74 61   id=tokenizer ta
15d20 67 73 3d 22 74 6f 6b 65 6e 69 7a 65 72 22 3e 54  gs="tokenizer">T
15d30 6f 6b 65 6e 69 7a 65 72 73 3c 2f 68 31 3e 0a 0a  okenizers</h1>..
15d40 3c 70 3e 0a 20 20 41 6e 20 46 54 53 20 74 6f 6b  <p>.  An FTS tok
15d50 65 6e 69 7a 65 72 20 69 73 20 61 20 73 65 74 20  enizer is a set 
15d60 6f 66 20 72 75 6c 65 73 20 66 6f 72 20 65 78 74  of rules for ext
15d70 72 61 63 74 69 6e 67 20 74 65 72 6d 73 20 66 72  racting terms fr
15d80 6f 6d 20 61 20 64 6f 63 75 6d 65 6e 74 20 0a 20  om a document . 
15d90 20 6f 72 20 62 61 73 69 63 20 46 54 53 20 66 75   or basic FTS fu
15da0 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 2e 20 0a  ll-text query. .
15db0 0a 3c 70 3e 0a 20 20 55 6e 6c 65 73 73 20 61 20  .<p>.  Unless a 
15dc0 73 70 65 63 69 66 69 63 20 74 6f 6b 65 6e 69 7a  specific tokeniz
15dd0 65 72 20 69 73 20 73 70 65 63 69 66 69 65 64 20  er is specified 
15de0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 43  as part of the C
15df0 52 45 41 54 45 20 0a 20 20 56 49 52 54 55 41 4c  REATE .  VIRTUAL
15e00 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
15e10 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
15e20 74 68 65 20 46 54 53 20 74 61 62 6c 65 2c 20 74  the FTS table, t
15e30 68 65 20 64 65 66 61 75 6c 74 20 0a 20 20 74 6f  he default .  to
15e40 6b 65 6e 69 7a 65 72 2c 20 22 73 69 6d 70 6c 65  kenizer, "simple
15e50 22 2c 20 69 73 20 75 73 65 64 2e 20 54 68 65 20  ", is used. The 
15e60 73 69 6d 70 6c 65 20 74 6f 6b 65 6e 69 7a 65 72  simple tokenizer
15e70 20 65 78 74 72 61 63 74 73 20 74 6f 6b 65 6e 73   extracts tokens
15e80 20 66 72 6f 6d 0a 20 20 61 20 64 6f 63 75 6d 65   from.  a docume
15e90 6e 74 20 6f 72 20 62 61 73 69 63 20 46 54 53 20  nt or basic FTS 
15ea0 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 20  full-text query 
15eb0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
15ec0 20 66 6f 6c 6c 6f 77 69 6e 67 20 0a 20 20 72 75   following .  ru
15ed0 6c 65 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  les:..<ul>.  <li
15ee0 3e 3c 70 3e 20 41 20 74 65 72 6d 20 69 73 20 61  ><p> A term is a
15ef0 20 63 6f 6e 74 69 67 75 6f 75 73 20 73 65 71 75   contiguous sequ
15f00 65 6e 63 65 20 6f 66 20 65 6c 69 67 69 62 6c 65  ence of eligible
15f10 20 63 68 61 72 61 63 74 65 72 73 2c 20 77 68 65   characters, whe
15f20 72 65 20 0a 20 20 20 20 65 6c 69 67 69 62 6c 65  re .    eligible
15f30 20 63 68 61 72 61 63 74 65 72 73 20 61 72 65 20   characters are 
15f40 61 6c 6c 20 61 6c 70 68 61 6e 75 6d 65 72 69 63  all alphanumeric
15f50 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 20   characters and 
15f60 61 6c 6c 20 63 68 61 72 61 63 74 65 72 73 20 77  all characters w
15f70 69 74 68 0a 20 20 20 20 55 6e 69 63 6f 64 65 20  ith.    Unicode 
15f80 63 6f 64 65 70 6f 69 6e 74 20 76 61 6c 75 65 73  codepoint values
15f90 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
15fa0 20 65 71 75 61 6c 20 74 6f 20 31 32 38 2e 0a 20   equal to 128.. 
15fb0 20 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 68 61     All other cha
15fc0 72 61 63 74 65 72 73 20 61 72 65 0a 20 20 20 20  racters are.    
15fd0 64 69 73 63 61 72 64 65 64 20 77 68 65 6e 20 73  discarded when s
15fe0 70 6c 69 74 74 69 6e 67 20 61 20 64 6f 63 75 6d  plitting a docum
15ff0 65 6e 74 20 69 6e 74 6f 20 74 65 72 6d 73 2e 20  ent into terms. 
16000 54 68 65 69 72 20 6f 6e 6c 79 20 63 6f 6e 74 72  Their only contr
16010 69 62 75 74 69 6f 6e 20 69 73 0a 20 20 20 20 74  ibution is.    t
16020 6f 20 73 65 70 61 72 61 74 65 20 61 64 6a 61 63  o separate adjac
16030 65 6e 74 20 74 65 72 6d 73 2e 0a 0a 20 20 3c 6c  ent terms...  <l
16040 69 3e 3c 70 3e 20 41 6c 6c 20 75 70 70 65 72 63  i><p> All upperc
16050 61 73 65 20 63 68 61 72 61 63 74 65 72 73 20 77  ase characters w
16060 69 74 68 69 6e 20 74 68 65 20 41 53 43 49 49 20  ithin the ASCII 
16070 72 61 6e 67 65 20 28 55 6e 69 63 6f 64 65 20 63  range (Unicode c
16080 6f 64 65 70 6f 69 6e 74 73 0a 20 20 20 20 6c 65  odepoints.    le
16090 73 73 20 74 68 61 6e 20 31 32 38 29 2c 20 61 72  ss than 128), ar
160a0 65 20 74 72 61 6e 73 66 6f 72 6d 65 64 20 74 6f  e transformed to
160b0 20 74 68 65 69 72 20 6c 6f 77 65 72 63 61 73 65   their lowercase
160c0 20 65 71 75 69 76 61 6c 65 6e 74 73 20 61 73 20   equivalents as 
160d0 70 61 72 74 0a 20 20 20 20 6f 66 20 74 68 65 20  part.    of the 
160e0 74 6f 6b 65 6e 69 7a 61 74 69 6f 6e 20 70 72 6f  tokenization pro
160f0 63 65 73 73 2e 20 54 68 75 73 2c 20 66 75 6c 6c  cess. Thus, full
16100 2d 74 65 78 74 20 71 75 65 72 69 65 73 20 61 72  -text queries ar
16110 65 0a 20 20 20 20 63 61 73 65 2d 69 6e 73 65 6e  e.    case-insen
16120 73 69 74 69 76 65 20 77 68 65 6e 20 75 73 69 6e  sitive when usin
16130 67 20 74 68 65 20 73 69 6d 70 6c 65 20 74 6f 6b  g the simple tok
16140 65 6e 69 7a 65 72 2e 0a 3c 2f 75 6c 3e 0a 0a 3c  enizer..</ul>..<
16150 70 3e 0a 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  p>.  For example
16160 2c 20 77 68 65 6e 20 61 20 64 6f 63 75 6d 65 6e  , when a documen
16170 74 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  t containing the
16180 20 74 65 78 74 20 22 52 69 67 68 74 20 6e 6f 77   text "Right now
16190 2c 20 74 68 65 79 27 72 65 20 76 65 72 79 0a 20  , they're very. 
161a0 20 66 72 75 73 74 72 61 74 65 64 2e 22 2c 20 74   frustrated.", t
161b0 68 65 20 74 65 72 6d 73 20 65 78 74 72 61 63 74  he terms extract
161c0 65 64 20 66 72 6f 6d 20 74 68 65 20 64 6f 63 75  ed from the docu
161d0 6d 65 6e 74 20 61 6e 64 20 61 64 64 65 64 20 74  ment and added t
161e0 6f 20 74 68 65 20 0a 20 20 66 75 6c 6c 2d 74 65  o the .  full-te
161f0 78 74 20 69 6e 64 65 78 20 61 72 65 2c 20 69 6e  xt index are, in
16200 20 6f 72 64 65 72 2c 20 22 72 69 67 68 74 20 6e   order, "right n
16210 6f 77 20 74 68 65 79 20 72 65 20 76 65 72 79 20  ow they re very 
16220 66 72 75 73 74 72 61 74 65 64 22 2e 20 53 75 63  frustrated". Suc
16230 68 0a 20 20 61 20 64 6f 63 75 6d 65 6e 74 20 77  h.  a document w
16240 6f 75 6c 64 20 6d 61 74 63 68 20 61 20 66 75 6c  ould match a ful
16250 6c 2d 74 65 78 74 20 71 75 65 72 79 20 73 75 63  l-text query suc
16260 68 20 61 73 20 22 4d 41 54 43 48 20 27 46 72 75  h as "MATCH 'Fru
16270 73 74 72 61 74 65 64 27 22 2c 20 0a 20 20 61 73  strated'", .  as
16280 20 74 68 65 20 73 69 6d 70 6c 65 20 74 6f 6b 65   the simple toke
16290 6e 69 7a 65 72 20 74 72 61 6e 73 66 6f 72 6d 73  nizer transforms
162a0 20 74 68 65 20 74 65 72 6d 20 69 6e 20 74 68 65   the term in the
162b0 20 71 75 65 72 79 20 74 6f 20 6c 6f 77 65 72 63   query to lowerc
162c0 61 73 65 0a 20 20 62 65 66 6f 72 65 20 73 65 61  ase.  before sea
162d0 72 63 68 69 6e 67 20 74 68 65 20 66 75 6c 6c 2d  rching the full-
162e0 74 65 78 74 20 69 6e 64 65 78 2e 0a 0a 3c 70 3e  text index...<p>
162f0 0a 20 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68  .  As well as th
16300 65 20 22 73 69 6d 70 6c 65 22 20 74 6f 6b 65 6e  e "simple" token
16310 69 7a 65 72 2c 20 74 68 65 20 46 54 53 20 73 6f  izer, the FTS so
16320 75 72 63 65 20 63 6f 64 65 20 66 65 61 74 75 72  urce code featur
16330 65 73 20 61 20 74 6f 6b 65 6e 69 7a 65 72 20 0a  es a tokenizer .
16340 20 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20    that uses the 
16350 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f  <a href="http://
16360 74 61 72 74 61 72 75 73 2e 6f 72 67 2f 7e 6d 61  tartarus.org/~ma
16370 72 74 69 6e 2f 50 6f 72 74 65 72 53 74 65 6d 6d  rtin/PorterStemm
16380 65 72 2f 22 3e 50 6f 72 74 65 72 20 0a 20 20 53  er/">Porter .  S
16390 74 65 6d 6d 69 6e 67 20 61 6c 67 6f 72 69 74 68  temming algorith
163a0 6d 3c 2f 61 3e 2e 20 54 68 69 73 20 74 6f 6b 65  m</a>. This toke
163b0 6e 69 7a 65 72 20 75 73 65 73 20 74 68 65 20 73  nizer uses the s
163c0 61 6d 65 20 72 75 6c 65 73 20 74 6f 20 73 65 70  ame rules to sep
163d0 61 72 61 74 65 0a 20 20 74 68 65 20 69 6e 70 75  arate.  the inpu
163e0 74 20 64 6f 63 75 6d 65 6e 74 20 69 6e 74 6f 20  t document into 
163f0 74 65 72 6d 73 20 69 6e 63 6c 75 64 69 6e 67 20  terms including 
16400 66 6f 6c 64 69 6e 67 20 61 6c 6c 20 74 65 72 6d  folding all term
16410 73 20 69 6e 74 6f 20 6c 6f 77 65 72 20 63 61 73  s into lower cas
16420 65 2c 0a 20 20 62 75 74 20 61 6c 73 6f 20 75 73  e,.  but also us
16430 65 73 20 74 68 65 20 50 6f 72 74 65 72 20 53 74  es the Porter St
16440 65 6d 6d 69 6e 67 20 61 6c 67 6f 72 69 74 68 6d  emming algorithm
16450 20 74 6f 20 72 65 64 75 63 65 20 72 65 6c 61 74   to reduce relat
16460 65 64 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  ed English langu
16470 61 67 65 0a 20 20 77 6f 72 64 73 20 74 6f 20 61  age.  words to a
16480 20 63 6f 6d 6d 6f 6e 20 72 6f 6f 74 2e 20 46 6f   common root. Fo
16490 72 20 65 78 61 6d 70 6c 65 2c 20 75 73 69 6e 67  r example, using
164a0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 20   the same input 
164b0 64 6f 63 75 6d 65 6e 74 20 61 73 20 69 6e 20 74  document as in t
164c0 68 65 0a 20 20 70 61 72 61 67 72 61 70 68 20 61  he.  paragraph a
164d0 62 6f 76 65 2c 20 74 68 65 20 70 6f 72 74 65 72  bove, the porter
164e0 20 74 6f 6b 65 6e 69 7a 65 72 20 65 78 74 72 61   tokenizer extra
164f0 63 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  cts the followin
16500 67 20 74 6f 6b 65 6e 73 3a 0a 20 20 22 72 69 67  g tokens:.  "rig
16510 68 74 20 6e 6f 77 20 74 68 65 69 20 76 65 72 69  ht now thei veri
16520 20 66 72 75 73 74 72 61 74 22 2e 20 45 76 65 6e   frustrat". Even
16530 20 74 68 6f 75 67 68 20 73 6f 6d 65 20 6f 66 20   though some of 
16540 74 68 65 73 65 20 74 65 72 6d 73 20 61 72 65 20  these terms are 
16550 6e 6f 74 20 65 76 65 6e 0a 20 20 45 6e 67 6c 69  not even.  Engli
16560 73 68 20 77 6f 72 64 73 2c 20 69 6e 20 73 6f 6d  sh words, in som
16570 65 20 63 61 73 65 73 20 75 73 69 6e 67 20 74 68  e cases using th
16580 65 6d 20 74 6f 20 62 75 69 6c 64 20 74 68 65 20  em to build the 
16590 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
165a0 69 73 20 6d 6f 72 65 0a 20 20 75 73 65 66 75 6c  is more.  useful
165b0 20 74 68 61 6e 20 74 68 65 20 6d 6f 72 65 20 69   than the more i
165c0 6e 74 65 6c 6c 69 67 69 62 6c 65 20 6f 75 74 70  ntelligible outp
165d0 75 74 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ut produced by t
165e0 68 65 20 73 69 6d 70 6c 65 20 74 6f 6b 65 6e 69  he simple tokeni
165f0 7a 65 72 2e 0a 20 20 55 73 69 6e 67 20 74 68 65  zer..  Using the
16600 20 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65   porter tokenize
16610 72 2c 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20  r, the document 
16620 6e 6f 74 20 6f 6e 6c 79 20 6d 61 74 63 68 65 73  not only matches
16630 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 69   full-text queri
16640 65 73 0a 20 20 73 75 63 68 20 61 73 20 22 4d 41  es.  such as "MA
16650 54 43 48 20 27 46 72 75 73 74 72 61 74 65 64 27  TCH 'Frustrated'
16660 22 2c 20 62 75 74 20 61 6c 73 6f 20 71 75 65 72  ", but also quer
16670 69 65 73 20 73 75 63 68 20 61 73 20 22 4d 41 54  ies such as "MAT
16680 43 48 20 27 46 72 75 73 74 72 61 74 69 6f 6e 27  CH 'Frustration'
16690 22 2c 0a 20 20 61 73 20 74 68 65 20 74 65 72 6d  ",.  as the term
166a0 20 22 46 72 75 73 74 72 61 74 69 6f 6e 22 20 69   "Frustration" i
166b0 73 20 72 65 64 75 63 65 64 20 62 79 20 74 68 65  s reduced by the
166c0 20 50 6f 72 74 65 72 20 73 74 65 6d 6d 65 72 20   Porter stemmer 
166d0 61 6c 67 6f 72 69 74 68 6d 20 74 6f 20 0a 20 20  algorithm to .  
166e0 22 66 72 75 73 74 72 61 74 22 20 2d 20 6a 75 73  "frustrat" - jus
166f0 74 20 61 73 20 22 46 72 75 73 74 72 61 74 65 64  t as "Frustrated
16700 22 20 69 73 2e 20 53 6f 2c 20 77 68 65 6e 20 75  " is. So, when u
16710 73 69 6e 67 20 74 68 65 20 70 6f 72 74 65 72 20  sing the porter 
16720 74 6f 6b 65 6e 69 7a 65 72 2c 0a 20 20 46 54 53  tokenizer,.  FTS
16730 20 69 73 20 61 62 6c 65 20 74 6f 20 66 69 6e 64   is able to find
16740 20 6e 6f 74 20 6a 75 73 74 20 65 78 61 63 74 20   not just exact 
16750 6d 61 74 63 68 65 73 20 66 6f 72 20 71 75 65 72  matches for quer
16760 69 65 64 20 74 65 72 6d 73 2c 20 62 75 74 20 6d  ied terms, but m
16770 61 74 63 68 65 73 0a 20 20 61 67 61 69 6e 73 74  atches.  against
16780 20 73 69 6d 69 6c 61 72 20 45 6e 67 6c 69 73 68   similar English
16790 20 6c 61 6e 67 75 61 67 65 20 74 65 72 6d 73 2e   language terms.
167a0 20 46 6f 72 20 6d 6f 72 65 20 69 6e 66 6f 72 6d   For more inform
167b0 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 0a 20 20  ation on the .  
167c0 50 6f 72 74 65 72 20 53 74 65 6d 6d 65 72 20 61  Porter Stemmer a
167d0 6c 67 6f 72 69 74 68 6d 2c 20 70 6c 65 61 73 65  lgorithm, please
167e0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
167f0 67 65 20 6c 69 6e 6b 65 64 20 61 62 6f 76 65 2e  ge linked above.
16800 0a 0a 3c 70 3e 0a 20 20 45 78 61 6d 70 6c 65 20  ..<p>.  Example 
16810 69 6c 6c 75 73 74 72 61 74 69 6e 67 20 74 68 65  illustrating the
16820 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
16830 65 65 6e 20 74 68 65 20 22 73 69 6d 70 6c 65 22  een the "simple"
16840 20 61 6e 64 20 22 70 6f 72 74 65 72 22 0a 20 20   and "porter".  
16850 74 6f 6b 65 6e 69 7a 65 72 73 3a 0a 0a 3c 63 6f  tokenizers:..<co
16860 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
16870 20 43 72 65 61 74 65 20 61 20 74 61 62 6c 65 20   Create a table 
16880 75 73 69 6e 67 20 74 68 65 20 73 69 6d 70 6c 65  using the simple
16890 20 74 6f 6b 65 6e 69 7a 65 72 2e 20 49 6e 73 65   tokenizer. Inse
168a0 72 74 20 61 20 64 6f 63 75 6d 65 6e 74 20 69 6e  rt a document in
168b0 74 6f 20 69 74 2e 3c 2f 69 3e 0a 20 20 43 52 45  to it.</i>.  CRE
168c0 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
168d0 45 20 73 69 6d 70 6c 65 20 55 53 49 4e 47 20 66  E simple USING f
168e0 74 73 33 28 74 6f 6b 65 6e 69 7a 65 3d 73 69 6d  ts3(tokenize=sim
168f0 70 6c 65 29 3b 0a 20 20 49 4e 53 45 52 54 20 49  ple);.  INSERT I
16900 4e 54 4f 20 73 69 6d 70 6c 65 20 56 41 4c 55 45  NTO simple VALUE
16910 53 28 27 52 69 67 68 74 20 6e 6f 77 20 74 68 65  S('Right now the
16920 79 27 27 72 65 20 76 65 72 79 20 66 72 75 73 74  y''re very frust
16930 72 61 74 65 64 27 29 3b 0a 0a 20 20 3c 69 3e 2d  rated');..  <i>-
16940 2d 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 74  - The first of t
16950 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
16960 20 71 75 65 72 69 65 73 20 6d 61 74 63 68 65 73   queries matches
16970 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 73 74   the document st
16980 6f 72 65 64 20 69 6e 3c 2f 69 3e 0a 20 20 3c 69  ored in</i>.  <i
16990 3e 2d 2d 20 74 61 62 6c 65 20 22 73 69 6d 70 6c  >-- table "simpl
169a0 65 22 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 64  e". The second d
169b0 6f 65 73 20 6e 6f 74 2e 3c 2f 69 3e 0a 20 20 53  oes not.</i>.  S
169c0 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 73 69 6d  ELECT * FROM sim
169d0 70 6c 65 20 57 48 45 52 45 20 73 69 6d 70 6c 65  ple WHERE simple
169e0 20 4d 41 54 43 48 20 27 46 72 75 73 74 72 61 74   MATCH 'Frustrat
169f0 65 64 27 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20  ed';.  SELECT * 
16a00 46 52 4f 4d 20 73 69 6d 70 6c 65 20 57 48 45 52  FROM simple WHER
16a10 45 20 73 69 6d 70 6c 65 20 4d 41 54 43 48 20 27  E simple MATCH '
16a20 46 72 75 73 74 72 61 74 69 6f 6e 27 3b 0a 0a 20  Frustration';.. 
16a30 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 20   <i>-- Create a 
16a40 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
16a50 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72  porter tokenizer
16a60 2e 20 49 6e 73 65 72 74 20 74 68 65 20 73 61 6d  . Insert the sam
16a70 65 20 64 6f 63 75 6d 65 6e 74 20 69 6e 74 6f 20  e document into 
16a80 69 74 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  it</i>.  CREATE 
16a90 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 70 6f  VIRTUAL TABLE po
16aa0 72 74 65 72 20 55 53 49 4e 47 20 66 74 73 33 28  rter USING fts3(
16ab0 74 6f 6b 65 6e 69 7a 65 3d 70 6f 72 74 65 72 29  tokenize=porter)
16ac0 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
16ad0 70 6f 72 74 65 72 20 56 41 4c 55 45 53 28 27 52  porter VALUES('R
16ae0 69 67 68 74 20 6e 6f 77 20 74 68 65 79 27 27 72  ight now they''r
16af0 65 20 76 65 72 79 20 66 72 75 73 74 72 61 74 65  e very frustrate
16b00 64 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 42 6f  d');..  <i>-- Bo
16b10 74 68 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  th of the follow
16b20 69 6e 67 20 71 75 65 72 69 65 73 20 6d 61 74 63  ing queries matc
16b30 68 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 73  h the document s
16b40 74 6f 72 65 64 20 69 6e 20 74 61 62 6c 65 20 22  tored in table "
16b50 70 6f 72 74 65 72 22 2e 3c 2f 69 3e 0a 20 20 53  porter".</i>.  S
16b60 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 70 6f 72  ELECT * FROM por
16b70 74 65 72 20 57 48 45 52 45 20 70 6f 72 74 65 72  ter WHERE porter
16b80 20 4d 41 54 43 48 20 27 46 72 75 73 74 72 61 74   MATCH 'Frustrat
16b90 65 64 27 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20  ed';.  SELECT * 
16ba0 46 52 4f 4d 20 70 6f 72 74 65 72 20 57 48 45 52  FROM porter WHER
16bb0 45 20 70 6f 72 74 65 72 20 4d 41 54 43 48 20 27  E porter MATCH '
16bc0 46 72 75 73 74 72 61 74 69 6f 6e 27 3b 0a 3c 2f  Frustration';.</
16bd0 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
16be0 20 20 49 66 20 74 68 69 73 20 65 78 74 65 6e 73    If this extens
16bf0 69 6f 6e 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ion is compiled 
16c00 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
16c10 45 4e 41 42 4c 45 5f 49 43 55 20 70 72 65 2d 70  ENABLE_ICU pre-p
16c20 72 6f 63 65 73 73 6f 72 0a 20 20 73 79 6d 62 6f  rocessor.  symbo
16c30 6c 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  l defined, then 
16c40 74 68 65 72 65 20 65 78 69 73 74 73 20 61 20 62  there exists a b
16c50 75 69 6c 74 2d 69 6e 20 74 6f 6b 65 6e 69 7a 65  uilt-in tokenize
16c60 72 20 6e 61 6d 65 64 20 22 69 63 75 22 0a 20 20  r named "icu".  
16c70 69 6d 70 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e  implemented usin
16c80 67 20 74 68 65 20 49 43 55 20 6c 69 62 72 61 72  g the ICU librar
16c90 79 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  y. The first arg
16ca0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20  ument passed to 
16cb0 74 68 65 0a 20 20 78 43 72 65 61 74 65 28 29 20  the.  xCreate() 
16cc0 6d 65 74 68 6f 64 20 28 73 65 65 20 66 74 73 33  method (see fts3
16cd0 5f 74 6f 6b 65 6e 69 7a 65 72 2e 68 29 20 6f 66  _tokenizer.h) of
16ce0 20 74 68 69 73 20 74 6f 6b 65 6e 69 7a 65 72 20   this tokenizer 
16cf0 6d 61 79 20 62 65 0a 20 20 61 6e 20 49 43 55 20  may be.  an ICU 
16d00 6c 6f 63 61 6c 65 20 69 64 65 6e 74 69 66 69 65  locale identifie
16d10 72 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22  r. For example "
16d20 74 72 5f 54 52 22 20 66 6f 72 20 54 75 72 6b 69  tr_TR" for Turki
16d30 73 68 20 61 73 20 75 73 65 64 0a 20 20 69 6e 20  sh as used.  in 
16d40 54 75 72 6b 65 79 2c 20 6f 72 20 22 65 6e 5f 41  Turkey, or "en_A
16d50 55 22 20 66 6f 72 20 45 6e 67 6c 69 73 68 20 61  U" for English a
16d60 73 20 75 73 65 64 20 69 6e 20 41 75 73 74 72 61  s used in Austra
16d70 6c 69 61 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  lia. For example
16d80 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
16d90 20 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41     CREATE VIRTUA
16da0 4c 20 54 41 42 4c 45 20 74 68 61 69 5f 74 65 78  L TABLE thai_tex
16db0 74 20 55 53 49 4e 47 20 66 74 73 33 28 74 65 78  t USING fts3(tex
16dc0 74 2c 20 74 6f 6b 65 6e 69 7a 65 3d 69 63 75 20  t, tokenize=icu 
16dd0 74 68 5f 54 48 29 0a 3c 2f 63 6f 64 65 62 6c 6f  th_TH).</codeblo
16de0 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 49  ck>..<p>.  The I
16df0 43 55 20 74 6f 6b 65 6e 69 7a 65 72 20 69 6d 70  CU tokenizer imp
16e00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 76  lementation is v
16e10 65 72 79 20 73 69 6d 70 6c 65 2e 20 49 74 20 73  ery simple. It s
16e20 70 6c 69 74 73 20 74 68 65 20 69 6e 70 75 74 0a  plits the input.
16e30 20 20 74 65 78 74 20 61 63 63 6f 72 64 69 6e 67    text according
16e40 20 74 6f 20 74 68 65 20 49 43 55 20 72 75 6c 65   to the ICU rule
16e50 73 20 66 6f 72 20 66 69 6e 64 69 6e 67 20 77 6f  s for finding wo
16e60 72 64 20 62 6f 75 6e 64 61 72 69 65 73 20 61 6e  rd boundaries an
16e70 64 20 64 69 73 63 61 72 64 73 0a 20 20 61 6e 79  d discards.  any
16e80 20 74 6f 6b 65 6e 73 20 74 68 61 74 20 63 6f 6e   tokens that con
16e90 73 69 73 74 20 65 6e 74 69 72 65 6c 79 20 6f 66  sist entirely of
16ea0 20 77 68 69 74 65 2d 73 70 61 63 65 2e 20 54 68   white-space. Th
16eb0 69 73 20 6d 61 79 20 62 65 20 73 75 69 74 61 62  is may be suitab
16ec0 6c 65 0a 20 20 66 6f 72 20 73 6f 6d 65 20 61 70  le.  for some ap
16ed0 70 6c 69 63 61 74 69 6f 6e 73 20 69 6e 20 73 6f  plications in so
16ee0 6d 65 20 6c 6f 63 61 6c 65 73 2c 20 62 75 74 20  me locales, but 
16ef0 6e 6f 74 20 61 6c 6c 2e 20 49 66 20 6d 6f 72 65  not all. If more
16f00 20 63 6f 6d 70 6c 65 78 0a 20 20 70 72 6f 63 65   complex.  proce
16f10 73 73 69 6e 67 20 69 73 20 72 65 71 75 69 72 65  ssing is require
16f20 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  d, for example t
16f30 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 73 74 65 6d  o implement stem
16f40 6d 69 6e 67 20 6f 72 0a 20 20 64 69 73 63 61 72  ming or.  discar
16f50 64 20 70 75 6e 63 74 75 61 74 69 6f 6e 2c 20 74  d punctuation, t
16f60 68 69 73 20 63 61 6e 20 62 65 20 64 6f 6e 65 20  his can be done 
16f70 62 79 20 63 72 65 61 74 69 6e 67 20 61 20 74 6f  by creating a to
16f80 6b 65 6e 69 7a 65 72 0a 20 20 69 6d 70 6c 65 6d  kenizer.  implem
16f90 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 75 73  entation that us
16fa0 65 73 20 74 68 65 20 49 43 55 20 74 6f 6b 65 6e  es the ICU token
16fb0 69 7a 65 72 20 61 73 20 70 61 72 74 20 6f 66 20  izer as part of 
16fc0 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
16fd0 6f 6e 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  on...<tcl>hd_fra
16fe0 67 6d 65 6e 74 20 75 6e 69 63 6f 64 65 36 31 20  gment unicode61 
16ff0 75 6e 69 63 6f 64 65 36 31 3c 2f 74 63 6c 3e 0a  unicode61</tcl>.
17000 3c 70 3e 0a 20 20 54 68 65 20 22 75 6e 69 63 6f  <p>.  The "unico
17010 64 65 36 31 22 20 74 6f 6b 65 6e 69 7a 65 72 20  de61" tokenizer 
17020 69 73 20 61 76 61 69 6c 61 62 6c 65 20 62 65 67  is available beg
17030 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
17040 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e  te [version 3.7.
17050 31 33 5d 2e 0a 20 20 55 6e 69 63 6f 64 65 36 31  13]..  Unicode61
17060 20 77 6f 72 6b 73 20 76 65 72 79 20 6d 75 63 68   works very much
17070 20 6c 69 6b 65 20 22 73 69 6d 70 6c 65 22 20 65   like "simple" e
17080 78 63 65 70 74 20 74 68 61 74 20 69 74 20 64 6f  xcept that it do
17090 65 73 20 66 75 6c 6c 20 75 6e 69 63 6f 64 65 0a  es full unicode.
170a0 20 20 63 61 73 65 20 66 6f 6c 64 69 6e 67 20 61    case folding a
170b0 63 63 6f 72 64 69 6e 67 20 74 6f 20 72 75 6c 65  ccording to rule
170c0 73 20 69 6e 20 55 6e 69 63 6f 64 65 20 56 65 72  s in Unicode Ver
170d0 73 69 6f 6e 20 36 2e 31 20 61 6e 64 20 69 74 20  sion 6.1 and it 
170e0 72 65 63 6f 67 6e 69 7a 65 73 0a 20 20 75 6e 69  recognizes.  uni
170f0 63 6f 64 65 20 73 70 61 63 65 20 61 6e 64 20 70  code space and p
17100 75 6e 63 74 75 61 74 69 6f 6e 20 63 68 61 72 61  unctuation chara
17110 63 74 65 72 73 20 61 6e 64 20 75 73 65 73 20 74  cters and uses t
17120 68 6f 73 65 20 74 6f 20 73 65 70 61 72 61 74 65  hose to separate
17130 20 74 6f 6b 65 6e 73 2e 0a 20 20 54 68 65 20 73   tokens..  The s
17140 69 6d 70 6c 65 20 74 6f 6b 65 6e 69 7a 65 72 20  imple tokenizer 
17150 6f 6e 6c 79 20 64 6f 65 73 20 63 61 73 65 20 66  only does case f
17160 6f 6c 64 69 6e 67 20 6f 66 20 41 53 43 49 49 20  olding of ASCII 
17170 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 20 6f  characters and o
17180 6e 6c 79 0a 20 20 72 65 63 6f 67 6e 69 7a 65 73  nly.  recognizes
17190 20 41 53 43 49 49 20 73 70 61 63 65 20 61 6e 64   ASCII space and
171a0 20 70 75 6e 63 74 75 61 74 69 6f 6e 20 63 68 61   punctuation cha
171b0 72 61 63 74 65 72 73 20 61 73 20 74 6f 6b 65 6e  racters as token
171c0 20 73 65 70 61 72 61 74 6f 72 73 2e 0a 0a 3c 68   separators...<h
171d0 32 3e 43 75 73 74 6f 6d 20 28 55 73 65 72 20 49  2>Custom (User I
171e0 6d 70 6c 65 6d 65 6e 74 65 64 29 20 54 6f 6b 65  mplemented) Toke
171f0 6e 69 7a 65 72 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  nizers</h2>..<p>
17200 0a 20 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68  .  As well as th
17210 65 20 62 75 69 6c 74 2d 69 6e 20 22 73 69 6d 70  e built-in "simp
17220 6c 65 22 2c 20 22 70 6f 72 74 65 72 22 20 61 6e  le", "porter" an
17230 64 20 28 70 6f 73 73 69 62 6c 79 29 20 22 69 63  d (possibly) "ic
17240 75 22 20 61 6e 64 0a 20 20 22 75 6e 69 63 6f 64  u" and.  "unicod
17250 65 36 31 22 20 74 6f 6b 65 6e 69 7a 65 72 73 2c  e61" tokenizers,
17260 0a 20 20 46 54 53 20 65 78 70 6f 72 74 73 20 61  .  FTS exports a
17270 6e 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  n interface that
17280 20 61 6c 6c 6f 77 73 20 75 73 65 72 73 20 74 6f   allows users to
17290 20 69 6d 70 6c 65 6d 65 6e 74 20 63 75 73 74 6f   implement custo
172a0 6d 20 74 6f 6b 65 6e 69 7a 65 72 73 0a 20 20 75  m tokenizers.  u
172b0 73 69 6e 67 20 43 2e 20 54 68 65 20 69 6e 74 65  sing C. The inte
172c0 72 66 61 63 65 20 75 73 65 64 20 74 6f 20 63 72  rface used to cr
172d0 65 61 74 65 20 61 20 6e 65 77 20 74 6f 6b 65 6e  eate a new token
172e0 69 7a 65 72 20 69 73 20 64 65 66 69 6e 65 64 20  izer is defined 
172f0 61 6e 64 20 0a 20 20 64 65 73 63 72 69 62 65 64  and .  described
17300 20 69 6e 20 74 68 65 20 66 74 73 33 5f 74 6f 6b   in the fts3_tok
17310 65 6e 69 7a 65 72 2e 68 20 73 6f 75 72 63 65 20  enizer.h source 
17320 66 69 6c 65 2e 0a 0a 3c 70 3e 0a 20 20 52 65 67  file...<p>.  Reg
17330 69 73 74 65 72 69 6e 67 20 61 20 6e 65 77 20 46  istering a new F
17340 54 53 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  TS tokenizer is 
17350 73 69 6d 69 6c 61 72 20 74 6f 20 72 65 67 69 73  similar to regis
17360 74 65 72 69 6e 67 20 61 20 6e 65 77 0a 20 20 76  tering a new.  v
17370 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
17380 75 6c 65 20 77 69 74 68 20 53 51 4c 69 74 65 2e  ule with SQLite.
17390 20 54 68 65 20 75 73 65 72 20 70 61 73 73 65 73   The user passes
173a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
173b0 20 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 74    structure cont
173c0 61 69 6e 69 6e 67 20 70 6f 69 6e 74 65 72 73 20  aining pointers 
173d0 74 6f 20 76 61 72 69 6f 75 73 20 63 61 6c 6c 62  to various callb
173e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
173f0 61 74 0a 20 20 6d 61 6b 65 20 75 70 20 74 68 65  at.  make up the
17400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
17410 6f 66 20 74 68 65 20 6e 65 77 20 74 6f 6b 65 6e  of the new token
17420 69 7a 65 72 20 74 79 70 65 2e 20 46 6f 72 20 74  izer type. For t
17430 6f 6b 65 6e 69 7a 65 72 73 2c 0a 20 20 74 68 65  okenizers,.  the
17440 20 73 74 72 75 63 74 75 72 65 20 28 64 65 66 69   structure (defi
17450 6e 65 64 20 69 6e 20 66 74 73 33 5f 74 6f 6b 65  ned in fts3_toke
17460 6e 69 7a 65 72 2e 68 29 20 69 73 20 63 61 6c 6c  nizer.h) is call
17470 65 64 0a 20 20 22 73 71 6c 69 74 65 33 5f 74 6f  ed.  "sqlite3_to
17480 6b 65 6e 69 7a 65 72 5f 6d 6f 64 75 6c 65 22 2e  kenizer_module".
17490 0a 0a 3c 70 3e 0a 20 20 46 54 53 20 64 6f 65 73  ..<p>.  FTS does
174a0 20 6e 6f 74 20 65 78 70 6f 73 65 20 61 20 43 2d   not expose a C-
174b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 75 73  function that us
174c0 65 72 73 20 63 61 6c 6c 20 74 6f 20 72 65 67 69  ers call to regi
174d0 73 74 65 72 20 6e 65 77 0a 20 20 74 6f 6b 65 6e  ster new.  token
174e0 69 7a 65 72 20 74 79 70 65 73 20 77 69 74 68 20  izer types with 
174f0 61 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  a database handl
17500 65 2e 20 49 6e 73 74 65 61 64 2c 20 74 68 65 20  e. Instead, the 
17510 70 6f 69 6e 74 65 72 20 6d 75 73 74 0a 20 20 62  pointer must.  b
17520 65 20 65 6e 63 6f 64 65 64 20 61 73 20 61 6e 20  e encoded as an 
17530 53 51 4c 20 62 6c 6f 62 20 76 61 6c 75 65 20 61  SQL blob value a
17540 6e 64 20 70 61 73 73 65 64 20 74 6f 20 46 54 53  nd passed to FTS
17550 20 74 68 72 6f 75 67 68 20 74 68 65 20 53 51 4c   through the SQL
17560 0a 20 20 65 6e 67 69 6e 65 20 62 79 20 65 76 61  .  engine by eva
17570 6c 75 61 74 69 6e 67 20 61 20 73 70 65 63 69 61  luating a specia
17580 6c 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  l scalar functio
17590 6e 2c 20 22 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  n, "fts3_tokeniz
175a0 65 72 28 29 22 2e 0a 20 20 54 68 65 20 66 74 73  er()"..  The fts
175b0 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 66 75  3_tokenizer() fu
175c0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 63 61  nction may be ca
175d0 6c 6c 65 64 20 77 69 74 68 20 6f 6e 65 20 6f 72  lled with one or
175e0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2c 0a   two arguments,.
175f0 20 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c    as follows:..<
17600 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 20 20 53  codeblock>.    S
17610 45 4c 45 43 54 20 66 74 73 33 5f 74 6f 6b 65 6e  ELECT fts3_token
17620 69 7a 65 72 28 26 6c 74 3b 74 6f 6b 65 6e 69 7a  izer(&lt;tokeniz
17630 65 72 2d 6e 61 6d 65 26 67 74 3b 29 3b 0a 20 20  er-name&gt;);.  
17640 20 20 53 45 4c 45 43 54 20 66 74 73 33 5f 74 6f    SELECT fts3_to
17650 6b 65 6e 69 7a 65 72 28 26 6c 74 3b 74 6f 6b 65  kenizer(&lt;toke
17660 6e 69 7a 65 72 2d 6e 61 6d 65 26 67 74 3b 2c 20  nizer-name&gt;, 
17670 26 6c 74 3b 73 71 6c 69 74 65 33 5f 74 6f 6b 65  &lt;sqlite3_toke
17680 6e 69 7a 65 72 5f 6d 6f 64 75 6c 65 20 70 74 72  nizer_module ptr
17690 26 67 74 3b 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  &gt;);.</codeblo
176a0 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 57 68 65 72 65  ck>..<p>.  Where
176b0 20 26 6c 74 3b 74 6f 6b 65 6e 69 7a 65 72 2d 6e   &lt;tokenizer-n
176c0 61 6d 65 26 67 74 3b 20 69 73 20 61 20 73 74 72  ame&gt; is a str
176d0 69 6e 67 20 69 64 65 6e 74 69 66 79 69 6e 67 20  ing identifying 
176e0 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 20 61 6e  the tokenizer an
176f0 64 0a 20 20 26 6c 74 3b 73 71 6c 69 74 65 33 5f  d.  &lt;sqlite3_
17700 74 6f 6b 65 6e 69 7a 65 72 5f 6d 6f 64 75 6c 65  tokenizer_module
17710 20 70 74 72 26 67 74 3b 20 69 73 20 61 20 70 6f   ptr&gt; is a po
17720 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
17730 74 65 33 5f 74 6f 6b 65 6e 69 7a 65 72 5f 6d 6f  te3_tokenizer_mo
17740 64 75 6c 65 0a 20 20 73 74 72 75 63 74 75 72 65  dule.  structure
17750 20 65 6e 63 6f 64 65 64 20 61 73 20 61 6e 20 53   encoded as an S
17760 51 4c 20 62 6c 6f 62 2e 20 49 66 20 74 68 65 20  QL blob. If the 
17770 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17780 69 73 20 70 72 65 73 65 6e 74 2c 0a 20 20 69 74  is present,.  it
17790 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 61   is registered a
177a0 73 20 74 6f 6b 65 6e 69 7a 65 72 20 26 6c 74 3b  s tokenizer &lt;
177b0 74 6f 6b 65 6e 69 7a 65 72 2d 6e 61 6d 65 26 67  tokenizer-name&g
177c0 74 3b 20 61 6e 64 20 61 20 63 6f 70 79 20 6f 66  t; and a copy of
177d0 20 69 74 0a 20 20 72 65 74 75 72 6e 65 64 2e 20   it.  returned. 
177e0 49 66 20 6f 6e 6c 79 20 6f 6e 65 20 61 72 67 75  If only one argu
177f0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 2c 20  ment is passed, 
17800 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
17810 20 74 6f 6b 65 6e 69 7a 65 72 0a 20 20 69 6d 70   tokenizer.  imp
17820 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 75 72 72  lementation curr
17830 65 6e 74 6c 79 20 72 65 67 69 73 74 65 72 65 64  ently registered
17840 20 61 73 20 26 6c 74 3b 74 6f 6b 65 6e 69 7a 65   as &lt;tokenize
17850 72 2d 6e 61 6d 65 26 67 74 3b 20 69 73 20 72 65  r-name&gt; is re
17860 74 75 72 6e 65 64 2c 0a 20 20 65 6e 63 6f 64 65  turned,.  encode
17870 64 20 61 73 20 61 20 62 6c 6f 62 2e 20 4f 72 2c  d as a blob. Or,
17880 20 69 66 20 6e 6f 20 73 75 63 68 20 74 6f 6b 65   if no such toke
17890 6e 69 7a 65 72 20 65 78 69 73 74 73 2c 20 61 6e  nizer exists, an
178a0 20 53 51 4c 20 65 78 63 65 70 74 69 6f 6e 0a 20   SQL exception. 
178b0 20 28 65 72 72 6f 72 29 20 69 73 20 72 61 69 73   (error) is rais
178c0 65 64 2e 0a 0a 3c 70 3e 0a 20 20 3c 62 3e 53 45  ed...<p>.  <b>SE
178d0 43 55 52 49 54 59 20 57 41 52 4e 49 4e 47 3c 2f  CURITY WARNING</
178e0 62 3e 3a 20 49 66 20 74 68 65 20 66 74 73 33 2f  b>: If the fts3/
178f0 34 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 75  4 extension is u
17900 73 65 64 20 69 6e 20 61 6e 20 65 6e 76 69 72 6f  sed in an enviro
17910 6e 6d 65 6e 74 0a 20 20 77 68 65 72 65 20 70 6f  nment.  where po
17920 74 65 6e 74 69 61 6c 6c 79 20 6d 61 6c 69 63 69  tentially malici
17930 6f 75 73 20 75 73 65 72 73 20 6d 61 79 20 65 78  ous users may ex
17940 65 63 75 74 65 20 61 72 62 69 74 72 61 72 79 20  ecute arbitrary 
17950 53 51 4c 2c 20 74 68 65 79 20 73 68 6f 75 6c 64  SQL, they should
17960 20 0a 20 20 62 65 20 70 72 65 76 65 6e 74 65 64   .  be prevented
17970 20 66 72 6f 6d 20 69 6e 76 6f 6b 69 6e 67 20 74   from invoking t
17980 68 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  he fts3_tokenize
17990 72 28 29 20 66 75 6e 63 74 69 6f 6e 2c 20 70 6f  r() function, po
179a0 73 73 69 62 6c 79 20 75 73 69 6e 67 20 0a 20 20  ssibly using .  
179b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
179c0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 7c 61 75  _authorizer()|au
179d0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
179e0 62 61 63 6b 5d 2e 0a 0a 3c 70 3e 0a 20 20 54 68  back]...<p>.  Th
179f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f 63  e following bloc
17a00 6b 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 78  k contains an ex
17a10 61 6d 70 6c 65 20 6f 66 20 63 61 6c 6c 69 6e 67  ample of calling
17a20 20 74 68 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69   the fts3_tokeni
17a30 7a 65 72 28 29 0a 20 20 66 75 6e 63 74 69 6f 6e  zer().  function
17a40 20 66 72 6f 6d 20 43 20 63 6f 64 65 3a 0a 0a 3c   from C code:..<
17a50 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e  codeblock>.  <i>
17a60 2f 2a 0a 20 20 2a 2a 20 52 65 67 69 73 74 65 72  /*.  ** Register
17a70 20 61 20 74 6f 6b 65 6e 69 7a 65 72 20 69 6d 70   a tokenizer imp
17a80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
17a90 20 46 54 53 33 20 6f 72 20 46 54 53 34 2e 0a 20   FTS3 or FTS4.. 
17aa0 20 2a 2f 3c 2f 69 3e 0a 20 20 69 6e 74 20 72 65   */</i>.  int re
17ab0 67 69 73 74 65 72 54 6f 6b 65 6e 69 7a 65 72 28  gisterTokenizer(
17ac0 0a 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62  .    sqlite3 *db
17ad0 2c 0a 20 20 20 20 63 68 61 72 20 2a 7a 4e 61 6d  ,.    char *zNam
17ae0 65 2c 0a 20 20 20 20 63 6f 6e 73 74 20 73 71 6c  e,.    const sql
17af0 69 74 65 33 5f 74 6f 6b 65 6e 69 7a 65 72 5f 6d  ite3_tokenizer_m
17b00 6f 64 75 6c 65 20 2a 70 0a 20 20 29 7b 0a 20 20  odule *p.  ){.  
17b10 20 20 69 6e 74 20 72 63 3b 0a 20 20 20 20 73 71    int rc;.    sq
17b20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
17b30 74 3b 0a 20 20 20 20 63 6f 6e 73 74 20 63 68 61  t;.    const cha
17b40 72 20 2a 7a 53 71 6c 20 3d 20 22 53 45 4c 45 43  r *zSql = "SELEC
17b50 54 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  T fts3_tokenizer
17b60 28 3f 2c 20 3f 29 22 3b 0a 0a 20 20 20 20 72 63  (?, ?)";..    rc
17b70 20 3d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61   = sqlite3_prepa
17b80 72 65 5f 76 32 28 64 62 2c 20 7a 53 71 6c 2c 20  re_v2(db, zSql, 
17b90 2d 31 2c 20 26 70 53 74 6d 74 2c 20 30 29 3b 0a  -1, &pStmt, 0);.
17ba0 20 20 20 20 69 66 28 20 72 63 21 3d 53 51 4c 49      if( rc!=SQLI
17bb0 54 45 5f 4f 4b 20 29 7b 0a 20 20 20 20 20 20 72  TE_OK ){.      r
17bc0 65 74 75 72 6e 20 72 63 3b 0a 20 20 20 20 7d 0a  eturn rc;.    }.
17bd0 0a 20 20 20 20 73 71 6c 69 74 65 33 5f 62 69 6e  .    sqlite3_bin
17be0 64 5f 74 65 78 74 28 70 53 74 6d 74 2c 20 31 2c  d_text(pStmt, 1,
17bf0 20 7a 4e 61 6d 65 2c 20 2d 31 2c 20 53 51 4c 49   zName, -1, SQLI
17c00 54 45 5f 53 54 41 54 49 43 29 3b 0a 20 20 20 20  TE_STATIC);.    
17c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
17c20 62 28 70 53 74 6d 74 2c 20 32 2c 20 26 70 2c 20  b(pStmt, 2, &p, 
17c30 73 69 7a 65 6f 66 28 70 29 2c 20 53 51 4c 49 54  sizeof(p), SQLIT
17c40 45 5f 53 54 41 54 49 43 29 3b 0a 20 20 20 20 73  E_STATIC);.    s
17c50 71 6c 69 74 65 33 5f 73 74 65 70 28 70 53 74 6d  qlite3_step(pStm
17c60 74 29 3b 0a 0a 20 20 20 20 72 65 74 75 72 6e 20  t);..    return 
17c70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
17c80 28 70 53 74 6d 74 29 3b 0a 20 20 7d 0a 0a 20 20  (pStmt);.  }..  
17c90 3c 69 3e 2f 2a 0a 20 20 2a 2a 20 51 75 65 72 79  <i>/*.  ** Query
17ca0 20 46 54 53 20 66 6f 72 20 74 68 65 20 74 6f 6b   FTS for the tok
17cb0 65 6e 69 7a 65 72 20 69 6d 70 6c 65 6d 65 6e 74  enizer implement
17cc0 61 74 69 6f 6e 20 6e 61 6d 65 64 20 7a 4e 61 6d  ation named zNam
17cd0 65 2e 0a 20 20 2a 2f 3c 2f 69 3e 0a 20 20 69 6e  e..  */</i>.  in
17ce0 74 20 71 75 65 72 79 54 6f 6b 65 6e 69 7a 65 72  t queryTokenizer
17cf0 28 0a 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64  (.    sqlite3 *d
17d00 62 2c 0a 20 20 20 20 63 68 61 72 20 2a 7a 4e 61  b,.    char *zNa
17d10 6d 65 2c 0a 20 20 20 20 63 6f 6e 73 74 20 73 71  me,.    const sq
17d20 6c 69 74 65 33 5f 74 6f 6b 65 6e 69 7a 65 72 5f  lite3_tokenizer_
17d30 6d 6f 64 75 6c 65 20 2a 2a 70 70 0a 20 20 29 7b  module **pp.  ){
17d40 0a 20 20 20 20 69 6e 74 20 72 63 3b 0a 20 20 20  .    int rc;.   
17d50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
17d60 53 74 6d 74 3b 0a 20 20 20 20 63 6f 6e 73 74 20  Stmt;.    const 
17d70 63 68 61 72 20 2a 7a 53 71 6c 20 3d 20 22 53 45  char *zSql = "SE
17d80 4c 45 43 54 20 66 74 73 33 5f 74 6f 6b 65 6e 69  LECT fts3_tokeni
17d90 7a 65 72 28 3f 29 22 3b 0a 0a 20 20 20 20 2a 70  zer(?)";..    *p
17da0 70 20 3d 20 30 3b 0a 20 20 20 20 72 63 20 3d 20  p = 0;.    rc = 
17db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17dc0 76 32 28 64 62 2c 20 7a 53 71 6c 2c 20 2d 31 2c  v2(db, zSql, -1,
17dd0 20 26 70 53 74 6d 74 2c 20 30 29 3b 0a 20 20 20   &pStmt, 0);.   
17de0 20 69 66 28 20 72 63 21 3d 53 51 4c 49 54 45 5f   if( rc!=SQLITE_
17df0 4f 4b 20 29 7b 0a 20 20 20 20 20 20 72 65 74 75  OK ){.      retu
17e00 72 6e 20 72 63 3b 0a 20 20 20 20 7d 0a 0a 20 20  rn rc;.    }..  
17e10 20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74    sqlite3_bind_t
17e20 65 78 74 28 70 53 74 6d 74 2c 20 31 2c 20 7a 4e  ext(pStmt, 1, zN
17e30 61 6d 65 2c 20 2d 31 2c 20 53 51 4c 49 54 45 5f  ame, -1, SQLITE_
17e40 53 54 41 54 49 43 29 3b 0a 20 20 20 20 69 66 28  STATIC);.    if(
17e50 20 53 51 4c 49 54 45 5f 52 4f 57 3d 3d 73 71 6c   SQLITE_ROW==sql
17e60 69 74 65 33 5f 73 74 65 70 28 70 53 74 6d 74 29  ite3_step(pStmt)
17e70 20 29 7b 0a 20 20 20 20 20 20 69 66 28 20 73 71   ){.      if( sq
17e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
17e90 65 28 70 53 74 6d 74 2c 20 30 29 3d 3d 53 51 4c  e(pStmt, 0)==SQL
17ea0 49 54 45 5f 42 4c 4f 42 20 29 7b 0a 20 20 20 20  ITE_BLOB ){.    
17eb0 20 20 20 20 6d 65 6d 63 70 79 28 70 70 2c 20 73      memcpy(pp, s
17ec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
17ed0 6f 62 28 70 53 74 6d 74 2c 20 30 29 2c 20 73 69  ob(pStmt, 0), si
17ee0 7a 65 6f 66 28 2a 70 70 29 29 3b 0a 20 20 20 20  zeof(*pp));.    
17ef0 20 20 7d 0a 20 20 20 20 7d 0a 0a 20 20 20 20 72    }.    }..    r
17f00 65 74 75 72 6e 20 73 71 6c 69 74 65 33 5f 66 69  eturn sqlite3_fi
17f10 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a 20  nalize(pStmt);. 
17f20 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a   }.</codeblock>.
17f30 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
17f40 6e 74 20 66 74 73 33 74 6f 6b 20 7b 66 74 73 33  nt fts3tok {fts3
17f50 74 6f 6b 65 6e 69 7a 65 7d 20 7b 66 74 73 33 74  tokenize} {fts3t
17f60 6f 6b 65 6e 69 7a 65 20 76 69 72 74 75 61 6c 20  okenize virtual 
17f70 74 61 62 6c 65 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  table}</tcl>.<h2
17f80 3e 51 75 65 72 79 69 6e 67 20 54 6f 6b 65 6e 69  >Querying Tokeni
17f90 7a 65 72 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68  zers</h2>..<p>Th
17fa0 65 20 22 66 74 73 33 74 6f 6b 65 6e 69 7a 65 22  e "fts3tokenize"
17fb0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63   virtual table c
17fc0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 69  an be used to di
17fd0 72 65 63 74 6c 79 20 61 63 63 65 73 73 20 61 6e  rectly access an
17fe0 79 0a 20 20 20 74 6f 6b 65 6e 69 7a 65 72 2e 20  y.   tokenizer. 
17ff0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   The following S
18000 51 4c 20 64 65 6d 6f 6e 73 74 72 61 74 65 73 20  QL demonstrates 
18010 68 6f 77 20 74 6f 20 63 72 65 61 74 65 20 61 6e  how to create an
18020 20 69 6e 73 74 61 6e 63 65 20 0a 20 20 20 6f 66   instance .   of
18030 20 74 68 65 20 66 74 73 33 74 6f 6b 65 6e 69 7a   the fts3tokeniz
18040 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3a  e virtual table:
18050 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 43 52  ..<codeblock>.CR
18060 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
18070 4c 45 20 74 6f 6b 31 20 55 53 49 4e 47 20 66 74  LE tok1 USING ft
18080 73 33 74 6f 6b 65 6e 69 7a 65 28 27 70 6f 72 74  s3tokenize('port
18090 65 72 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  er');.</codebloc
180a0 6b 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61 6d 65 20  k>..<p>The name 
180b0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 74  of the desired t
180c0 6f 6b 65 6e 69 7a 65 72 20 73 68 6f 75 6c 64 20  okenizer should 
180d0 62 65 20 73 75 62 73 74 69 74 75 65 64 20 69 6e  be substitued in
180e0 20 70 6c 61 63 65 20 6f 66 0a 20 20 20 27 70 6f   place of.   'po
180f0 72 74 65 72 27 20 69 6e 20 74 68 65 20 65 78 61  rter' in the exa
18100 6d 70 6c 65 2c 20 6f 66 20 63 6f 75 72 73 65 2e  mple, of course.
18110 20 20 4f 6e 63 65 20 74 68 65 20 76 69 72 74 75    Once the virtu
18120 61 6c 20 74 61 62 6c 65 20 69 73 20 63 72 65 61  al table is crea
18130 74 65 64 2c 0a 20 20 20 69 74 20 63 61 6e 20 62  ted,.   it can b
18140 65 20 71 75 65 72 69 65 64 20 61 73 20 66 6f 6c  e queried as fol
18150 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  lows:..<codebloc
18160 6b 3e 0a 53 45 4c 45 43 54 20 74 6f 6b 65 6e 2c  k>.SELECT token,
18170 20 73 74 61 72 74 2c 20 65 6e 64 2c 20 70 6f 73   start, end, pos
18180 69 74 69 6f 6e 20 0a 20 20 46 52 4f 4d 20 74 6f  ition .  FROM to
18190 6b 31 0a 20 57 48 45 52 45 20 69 6e 70 75 74 3d  k1. WHERE input=
181a0 27 54 68 69 73 20 69 73 20 61 20 74 65 73 74 20  'This is a test 
181b0 73 65 6e 74 65 6e 63 65 2e 27 3b 0a 3c 2f 63 6f  sentence.';.</co
181c0 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65  deblock>..<p>The
181d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
181e0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 72  ill return one r
181f0 6f 77 20 6f 66 20 6f 75 74 70 75 74 20 66 6f 72  ow of output for
18200 20 65 61 63 68 20 74 6f 6b 65 6e 20 69 6e 20 74   each token in t
18210 68 65 0a 20 20 20 69 6e 70 75 74 20 73 74 72 69  he.   input stri
18220 6e 67 2e 20 20 54 68 65 20 22 74 6f 6b 65 6e 22  ng.  The "token"
18230 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 74   column is the t
18240 65 78 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  ext of the token
18250 2e 20 20 54 68 65 20 22 73 74 61 72 74 22 0a 20  .  The "start". 
18260 20 20 61 6e 64 20 22 65 6e 64 22 20 63 6f 6c 75    and "end" colu
18270 6d 6e 73 20 61 72 65 20 74 68 65 20 62 79 74 65  mns are the byte
18280 20 6f 66 66 73 65 74 20 74 6f 20 74 68 65 20 62   offset to the b
18290 65 67 69 6e 6e 69 6e 67 20 61 6e 64 20 65 6e 64  eginning and end
182a0 20 6f 66 20 74 68 65 0a 20 20 20 74 6f 6b 65 6e   of the.   token
182b0 20 69 6e 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   in the original
182c0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 20   input string.  
182d0 54 68 65 20 22 70 6f 73 22 20 63 6f 6c 75 6d 6e  The "pos" column
182e0 20 69 73 20 74 68 65 20 73 65 71 75 65 6e 63 65   is the sequence
182f0 20 6e 75 6d 62 65 72 0a 20 20 20 6f 66 20 74 68   number.   of th
18300 65 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 20 6f  e token in the o
18310 72 69 67 69 6e 61 6c 20 69 6e 70 75 74 20 73 74  riginal input st
18320 72 69 6e 67 2e 20 20 54 68 65 20 65 78 61 6d 70  ring.  The examp
18330 6c 65 20 61 62 6f 76 65 20 67 65 6e 65 72 61 74  le above generat
18340 65 73 0a 20 20 20 74 68 65 20 66 6f 6c 6c 6f 77  es.   the follow
18350 69 6e 67 20 6f 75 74 70 75 74 3a 0a 0a 3c 63 6f  ing output:..<co
18360 64 65 62 6c 6f 63 6b 3e 0a 74 68 69 7c 30 7c 34  deblock>.thi|0|4
18370 7c 30 0a 69 73 7c 35 7c 37 7c 31 0a 61 7c 38 7c  |0.is|5|7|1.a|8|
18380 39 7c 32 0a 74 65 73 74 7c 31 30 7c 31 34 7c 33  9|2.test|10|14|3
18390 0a 73 65 6e 74 65 6e 63 7c 31 35 7c 32 33 7c 34  .sentenc|15|23|4
183a0 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
183b0 70 3e 4e 6f 74 69 63 65 20 74 68 61 74 20 74 68  p>Notice that th
183c0 65 20 74 6f 6b 65 6e 73 20 69 6e 20 74 68 65 20  e tokens in the 
183d0 72 65 73 75 6c 74 20 73 65 74 20 66 72 6f 6d 20  result set from 
183e0 74 68 65 20 66 74 73 33 74 6f 6b 65 6e 69 7a 65  the fts3tokenize
183f0 20 76 69 72 74 75 61 6c 0a 20 20 20 74 61 62 6c   virtual.   tabl
18400 65 20 68 61 76 65 20 62 65 65 6e 20 74 72 61 6e  e have been tran
18410 73 66 6f 72 6d 65 64 20 61 63 63 6f 72 64 69 6e  sformed accordin
18420 67 20 74 6f 20 74 68 65 20 72 75 6c 65 73 20 6f  g to the rules o
18430 66 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 2e  f the tokenizer.
18440 0a 20 20 20 53 69 6e 63 65 20 74 68 69 73 20 65  .   Since this e
18450 78 61 6d 70 6c 65 20 75 73 65 64 20 74 68 65 20  xample used the 
18460 22 70 6f 72 74 65 72 22 20 74 6f 6b 65 6e 69 7a  "porter" tokeniz
18470 65 72 2c 20 74 68 65 20 22 54 68 69 73 22 20 74  er, the "This" t
18480 6f 6b 65 6e 20 77 61 73 0a 20 20 20 63 6f 6e 76  oken was.   conv
18490 65 72 74 65 64 20 69 6e 74 6f 20 22 74 68 69 22  erted into "thi"
184a0 2e 20 20 49 66 20 74 68 65 20 6f 72 69 67 69 6e  .  If the origin
184b0 61 6c 20 74 65 78 74 20 6f 66 20 74 68 65 20 74  al text of the t
184c0 6f 6b 65 6e 20 69 73 20 64 65 73 69 72 65 64 2c  oken is desired,
184d0 0a 20 20 20 69 74 20 63 61 6e 20 62 65 20 72 65  .   it can be re
184e0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 74 68  trieved using th
184f0 65 20 22 73 74 61 72 74 22 20 61 6e 64 20 22 65  e "start" and "e
18500 6e 64 22 20 63 6f 6c 75 6d 6e 73 20 77 69 74 68  nd" columns with
18510 20 74 68 65 0a 20 20 20 5b 73 75 62 73 74 72 28   the.   [substr(
18520 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 20 20 46 6f  )] function.  Fo
18530 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
18540 65 62 6c 6f 63 6b 3e 0a 53 45 4c 45 43 54 20 73  eblock>.SELECT s
18550 75 62 73 74 72 28 69 6e 70 75 74 2c 20 73 74 61  ubstr(input, sta
18560 72 74 2b 31 2c 20 65 6e 64 2d 73 74 61 72 74 29  rt+1, end-start)
18570 2c 20 74 6f 6b 65 6e 2c 20 70 6f 73 69 74 69 6f  , token, positio
18580 6e 0a 20 20 46 52 4f 4d 20 74 6f 6b 31 0a 20 57  n.  FROM tok1. W
18590 48 45 52 45 20 69 6e 70 75 74 3d 27 54 68 69 73  HERE input='This
185a0 20 69 73 20 61 20 74 65 73 74 20 73 65 6e 74 65   is a test sente
185b0 6e 63 65 2e 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  nce.';.</codeblo
185c0 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 66 74 73 33  ck>..<p>The fts3
185d0 74 6f 6b 65 6e 69 7a 65 20 76 69 72 74 75 61 6c  tokenize virtual
185e0 20 74 61 62 6c 65 20 63 61 6e 20 62 65 20 75 73   table can be us
185f0 65 64 20 6f 6e 20 61 6e 79 20 74 6f 6b 65 6e 69  ed on any tokeni
18600 7a 65 72 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  zer, regardless.
18610 20 20 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72     of whether or
18620 20 6e 6f 74 20 74 68 65 72 65 20 65 78 69 73 74   not there exist
18630 73 20 61 6e 20 46 54 53 33 20 6f 72 20 46 54 53  s an FTS3 or FTS
18640 34 20 74 61 62 6c 65 20 74 68 61 74 20 61 63 74  4 table that act
18650 75 61 6c 6c 79 20 75 73 65 73 0a 20 20 20 74 68  ually uses.   th
18660 61 74 20 74 6f 6b 65 6e 69 7a 65 72 2e 0a 0a 20  at tokenizer... 
18670 0a 3c 68 31 20 74 61 67 73 3d 22 73 65 67 6d 65  .<h1 tags="segme
18680 6e 74 20 62 74 72 65 65 22 3e 44 61 74 61 20 53  nt btree">Data S
18690 74 72 75 63 74 75 72 65 73 3c 2f 68 31 3e 0a 0a  tructures</h1>..
186a0 3c 70 3e 0a 20 20 54 68 69 73 20 73 65 63 74 69  <p>.  This secti
186b0 6f 6e 20 64 65 73 63 72 69 62 65 73 20 61 74 20  on describes at 
186c0 61 20 68 69 67 68 2d 6c 65 76 65 6c 20 74 68 65  a high-level the
186d0 20 77 61 79 20 74 68 65 20 46 54 53 20 6d 6f 64   way the FTS mod
186e0 75 6c 65 20 73 74 6f 72 65 73 20 69 74 73 0a 20  ule stores its. 
186f0 20 69 6e 64 65 78 20 61 6e 64 20 63 6f 6e 74 65   index and conte
18700 6e 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  nt in the databa
18710 73 65 2e 20 49 74 20 69 73 20 3c 62 3e 6e 6f 74  se. It is <b>not
18720 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 72 65   necessary to re
18730 61 64 20 6f 72 20 0a 20 20 75 6e 64 65 72 73 74  ad or .  underst
18740 61 6e 64 20 74 68 65 20 6d 61 74 65 72 69 61 6c  and the material
18750 20 69 6e 20 74 68 69 73 20 73 65 63 74 69 6f 6e   in this section
18760 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 75 73 65   in order to use
18770 20 46 54 53 3c 2f 62 3e 20 69 6e 20 61 6e 20 0a   FTS</b> in an .
18780 20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 48    application. H
18790 6f 77 65 76 65 72 2c 20 69 74 20 6d 61 79 20 62  owever, it may b
187a0 65 20 75 73 65 66 75 6c 20 74 6f 20 61 70 70 6c  e useful to appl
187b0 69 63 61 74 69 6f 6e 20 64 65 76 65 6c 6f 70 65  ication develope
187c0 72 73 20 61 74 74 65 6d 70 74 69 6e 67 20 0a 20  rs attempting . 
187d0 20 74 6f 20 61 6e 61 6c 79 7a 65 20 61 6e 64 20   to analyze and 
187e0 75 6e 64 65 72 73 74 61 6e 64 20 46 54 53 20 70  understand FTS p
187f0 65 72 66 6f 72 6d 61 6e 63 65 20 63 68 61 72 61  erformance chara
18800 63 74 65 72 69 73 74 69 63 73 2c 20 6f 72 20 74  cteristics, or t
18810 6f 20 64 65 76 65 6c 6f 70 65 72 73 20 0a 20 20  o developers .  
18820 63 6f 6e 74 65 6d 70 6c 61 74 69 6e 67 20 65 6e  contemplating en
18830 68 61 6e 63 65 6d 65 6e 74 73 20 74 6f 20 74 68  hancements to th
18840 65 20 65 78 69 73 74 69 6e 67 20 46 54 53 20 66  e existing FTS f
18850 65 61 74 75 72 65 20 73 65 74 2e 0a 0a 3c 74 63  eature set...<tc
18860 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 2a 73  l>hd_fragment *s
18870 68 61 64 6f 77 74 61 62 20 7b 46 54 53 20 73 68  hadowtab {FTS sh
18880 61 64 6f 77 20 74 61 62 6c 65 73 7d 20 7b 73 68  adow tables} {sh
18890 61 64 6f 77 20 74 61 62 6c 65 73 7d 3c 2f 74 63  adow tables}</tc
188a0 6c 3e 0a 3c 68 32 20 74 61 67 73 3d 22 73 68 61  l>.<h2 tags="sha
188b0 64 6f 77 74 61 62 73 22 3e 53 68 61 64 6f 77 20  dowtabs">Shadow 
188c0 54 61 62 6c 65 73 3c 2f 68 32 3e 0a 3c 70 3e 0a  Tables</h2>.<p>.
188d0 20 20 46 6f 72 20 65 61 63 68 20 46 54 53 20 76    For each FTS v
188e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 20  irtual table in 
188f0 61 20 64 61 74 61 62 61 73 65 2c 20 74 68 72 65  a database, thre
18900 65 20 74 6f 20 66 69 76 65 20 72 65 61 6c 20 28  e to five real (
18910 6e 6f 6e 2d 76 69 72 74 75 61 6c 29 20 74 61 62  non-virtual) tab
18920 6c 65 73 0a 20 20 61 72 65 20 63 72 65 61 74 65  les.  are create
18930 64 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 75  d to store the u
18940 6e 64 65 72 6c 79 69 6e 67 20 64 61 74 61 2e 20  nderlying data. 
18950 20 54 68 65 73 65 20 72 65 61 6c 20 74 61 62 6c   These real tabl
18960 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 22 73  es are called "s
18970 68 61 64 6f 77 20 74 61 62 6c 65 73 22 2e 0a 20  hadow tables".. 
18980 20 54 68 65 20 72 65 61 6c 20 74 61 62 6c 65 73   The real tables
18990 20 61 72 65 20 6e 61 6d 65 64 20 22 25 5f 63 6f   are named "%_co
189a0 6e 74 65 6e 74 22 2c 0a 20 20 22 25 5f 73 65 67  ntent",.  "%_seg
189b0 64 69 72 22 2c 20 22 25 5f 73 65 67 6d 65 6e 74  dir", "%_segment
189c0 73 22 2c 20 22 25 5f 73 74 61 74 22 2c 20 61 6e  s", "%_stat", an
189d0 64 20 22 25 5f 64 6f 63 73 69 7a 65 22 2c 20 77  d "%_docsize", w
189e0 68 65 72 65 20 22 25 22 20 69 73 20 72 65 70 6c  here "%" is repl
189f0 61 63 65 64 20 62 79 20 74 68 65 20 6e 61 6d 65  aced by the name
18a00 0a 20 20 6f 66 20 74 68 65 20 46 54 53 20 76 69  .  of the FTS vi
18a10 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 0a 3c 70  rtual table...<p
18a20 3e 0a 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  >.  The leftmost
18a30 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 22   column of the "
18a40 25 5f 63 6f 6e 74 65 6e 74 22 20 74 61 62 6c 65  %_content" table
18a50 20 69 73 20 61 6e 20 49 4e 54 45 47 45 52 20 50   is an INTEGER P
18a60 52 49 4d 41 52 59 20 4b 45 59 20 66 69 65 6c 64  RIMARY KEY field
18a70 0a 20 20 6e 61 6d 65 64 20 22 64 6f 63 69 64 22  .  named "docid"
18a80 2e 20 46 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  . Following this
18a90 20 69 73 20 6f 6e 65 20 63 6f 6c 75 6d 6e 20 66   is one column f
18aa0 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f  or each column o
18ab0 66 20 74 68 65 20 46 54 53 0a 20 20 76 69 72 74  f the FTS.  virt
18ac0 75 61 6c 20 74 61 62 6c 65 20 61 73 20 64 65 63  ual table as dec
18ad0 6c 61 72 65 64 20 62 79 20 74 68 65 20 75 73 65  lared by the use
18ae0 72 2c 20 6e 61 6d 65 64 20 62 79 20 70 72 65 70  r, named by prep
18af0 65 6e 64 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d  ending the colum
18b00 6e 20 6e 61 6d 65 0a 20 20 73 75 70 70 6c 69 65  n name.  supplie
18b10 64 20 62 79 20 74 68 65 20 75 73 65 72 20 77 69  d by the user wi
18b20 74 68 20 22 63 3c 69 3e 4e 3c 2f 69 3e 22 2c 20  th "c<i>N</i>", 
18b30 77 68 65 72 65 20 3c 69 3e 4e 3c 2f 69 3e 20 69  where <i>N</i> i
18b40 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
18b50 68 65 20 0a 20 20 63 6f 6c 75 6d 6e 20 77 69 74  he .  column wit
18b60 68 69 6e 20 74 68 65 20 74 61 62 6c 65 2c 20 6e  hin the table, n
18b70 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 6c 65 66  umbered from lef
18b80 74 20 74 6f 20 72 69 67 68 74 20 73 74 61 72 74  t to right start
18b90 69 6e 67 20 77 69 74 68 20 30 2e 20 44 61 74 61  ing with 0. Data
18ba0 0a 20 20 74 79 70 65 73 20 73 75 70 70 6c 69 65  .  types supplie
18bb0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
18bc0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 64   virtual table d
18bd0 65 63 6c 61 72 61 74 69 6f 6e 20 61 72 65 20 6e  eclaration are n
18be0 6f 74 20 75 73 65 64 20 61 73 0a 20 20 70 61 72  ot used as.  par
18bf0 74 20 6f 66 20 74 68 65 20 25 5f 63 6f 6e 74 65  t of the %_conte
18c00 6e 74 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  nt table declara
18c10 74 69 6f 6e 2e 20 46 6f 72 20 65 78 61 6d 70 6c  tion. For exampl
18c20 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
18c30 20 20 3c 69 3e 2d 2d 20 56 69 72 74 75 61 6c 20    <i>-- Virtual 
18c40 74 61 62 6c 65 20 64 65 63 6c 61 72 61 74 69 6f  table declaratio
18c50 6e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  n</i>.  CREATE V
18c60 49 52 54 55 41 4c 20 54 41 42 4c 45 20 61 62 63  IRTUAL TABLE abc
18c70 20 55 53 49 4e 47 20 66 74 73 34 28 61 20 4e 55   USING fts4(a NU
18c80 4d 42 45 52 2c 20 62 20 54 45 58 54 2c 20 63 29  MBER, b TEXT, c)
18c90 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 6f 72 72 65  ;..  <i>-- Corre
18ca0 73 70 6f 6e 64 69 6e 67 20 25 5f 63 6f 6e 74 65  sponding %_conte
18cb0 6e 74 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  nt table declara
18cc0 74 69 6f 6e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  tion</i>.  CREAT
18cd0 45 20 54 41 42 4c 45 20 61 62 63 5f 63 6f 6e 74  E TABLE abc_cont
18ce0 65 6e 74 28 64 6f 63 69 64 20 49 4e 54 45 47 45  ent(docid INTEGE
18cf0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 63  R PRIMARY KEY, c
18d00 30 61 2c 20 63 31 62 2c 20 63 32 63 29 3b 0a 3c  0a, c1b, c2c);.<
18d10 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
18d20 0a 20 20 54 68 65 20 25 5f 63 6f 6e 74 65 6e 74  .  The %_content
18d30 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20   table contains 
18d40 74 68 65 20 75 6e 61 64 75 6c 74 65 72 61 74 65  the unadulterate
18d50 64 20 64 61 74 61 20 69 6e 73 65 72 74 65 64 20  d data inserted 
18d60 62 79 20 74 68 65 20 75 73 65 72 20 0a 20 20 69  by the user .  i
18d70 6e 74 6f 20 74 68 65 20 46 54 53 20 76 69 72 74  nto the FTS virt
18d80 75 61 6c 20 74 61 62 6c 65 20 62 79 20 74 68 65  ual table by the
18d90 20 75 73 65 72 2e 20 49 66 20 74 68 65 20 75 73   user. If the us
18da0 65 72 20 64 6f 65 73 20 6e 6f 74 20 65 78 70 6c  er does not expl
18db0 69 63 69 74 6c 79 0a 20 20 73 75 70 70 6c 79 20  icitly.  supply 
18dc0 61 20 22 64 6f 63 69 64 22 20 76 61 6c 75 65 20  a "docid" value 
18dd0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 72  when inserting r
18de0 65 63 6f 72 64 73 2c 20 6f 6e 65 20 69 73 20 73  ecords, one is s
18df0 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69  elected automati
18e00 63 61 6c 6c 79 0a 20 20 62 79 20 74 68 65 20 73  cally.  by the s
18e10 79 73 74 65 6d 2e 0a 0a 3c 70 3e 0a 20 20 54 68  ystem...<p>.  Th
18e20 65 20 25 5f 73 74 61 74 20 61 6e 64 20 25 5f 64  e %_stat and %_d
18e30 6f 63 73 69 7a 65 20 74 61 62 6c 65 73 20 61 72  ocsize tables ar
18e40 65 20 6f 6e 6c 79 20 63 72 65 61 74 65 64 20 69  e only created i
18e50 66 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 20  f the FTS table 
18e60 75 73 65 73 20 74 68 65 0a 20 20 46 54 53 34 20  uses the.  FTS4 
18e70 6d 6f 64 75 6c 65 2c 20 6e 6f 74 20 46 54 53 33  module, not FTS3
18e80 2e 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 74  . Furthermore, t
18e90 68 65 20 25 5f 64 6f 63 73 69 7a 65 20 74 61 62  he %_docsize tab
18ea0 6c 65 20 69 73 20 6f 6d 69 74 74 65 64 20 69 66  le is omitted if
18eb0 20 74 68 65 0a 20 20 46 54 53 34 20 74 61 62 6c   the.  FTS4 tabl
18ec0 65 20 69 73 20 63 72 65 61 74 65 64 20 77 69 74  e is created wit
18ed0 68 20 74 68 65 20 5b 46 54 53 34 20 6d 61 74 63  h the [FTS4 matc
18ee0 68 69 6e 66 6f 20 6f 70 74 69 6f 6e 7c 22 6d 61  hinfo option|"ma
18ef0 74 63 68 69 6e 66 6f 3d 66 74 73 33 22 5d 20 64  tchinfo=fts3"] d
18f00 69 72 65 63 74 69 76 65 0a 20 20 73 70 65 63 69  irective.  speci
18f10 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
18f20 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55  the CREATE VIRTU
18f30 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  AL TABLE stateme
18f40 6e 74 2e 20 49 66 20 74 68 65 79 20 61 72 65 20  nt. If they are 
18f50 63 72 65 61 74 65 64 2c 0a 20 20 74 68 65 20 73  created,.  the s
18f60 63 68 65 6d 61 20 6f 66 20 74 68 65 20 74 77 6f  chema of the two
18f70 20 74 61 62 6c 65 73 20 69 73 20 61 73 20 66 6f   tables is as fo
18f80 6c 6c 6f 77 73 3a 0a 3c 63 6f 64 65 62 6c 6f 63  llows:.<codebloc
18f90 6b 3e 0a 20 20 43 52 45 41 54 45 20 54 41 42 4c  k>.  CREATE TABL
18fa0 45 20 25 5f 73 74 61 74 28 0a 20 20 20 20 69 64  E %_stat(.    id
18fb0 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
18fc0 20 4b 45 59 2c 20 0a 20 20 20 20 76 61 6c 75 65   KEY, .    value
18fd0 20 42 4c 4f 42 0a 20 20 29 3b 0a 0a 20 20 43 52   BLOB.  );..  CR
18fe0 45 41 54 45 20 54 41 42 4c 45 20 25 5f 64 6f 63  EATE TABLE %_doc
18ff0 73 69 7a 65 28 0a 20 20 20 20 64 6f 63 69 64 20  size(.    docid 
19000 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19010 4b 45 59 2c 0a 20 20 20 20 73 69 7a 65 20 42 4c  KEY,.    size BL
19020 4f 42 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62 6c  OB.  );.</codebl
19030 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 46 6f 72 20  ock>..<p>.  For 
19040 65 61 63 68 20 72 6f 77 20 69 6e 20 74 68 65 20  each row in the 
19050 46 54 53 20 74 61 62 6c 65 2c 20 74 68 65 20 25  FTS table, the %
19060 5f 64 6f 63 73 69 7a 65 20 74 61 62 6c 65 20 63  _docsize table c
19070 6f 6e 74 61 69 6e 73 20 61 20 63 6f 72 72 65 73  ontains a corres
19080 70 6f 6e 64 69 6e 67 0a 20 20 72 6f 77 20 77 69  ponding.  row wi
19090 74 68 20 74 68 65 20 73 61 6d 65 20 22 64 6f 63  th the same "doc
190a0 69 64 22 20 76 61 6c 75 65 2e 20 54 68 65 20 22  id" value. The "
190b0 73 69 7a 65 22 20 66 69 65 6c 64 20 63 6f 6e 74  size" field cont
190c0 61 69 6e 73 20 61 20 62 6c 6f 62 20 63 6f 6e 73  ains a blob cons
190d0 69 73 74 69 6e 67 0a 20 20 6f 66 20 3c 69 3e 4e  isting.  of <i>N
190e0 3c 2f 69 3e 20 46 54 53 20 76 61 72 69 6e 74 73  </i> FTS varints
190f0 2c 20 77 68 65 72 65 20 3c 69 3e 4e 3c 2f 69 3e  , where <i>N</i>
19100 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19110 66 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 63  f user-defined c
19120 6f 6c 75 6d 6e 73 0a 20 20 69 6e 20 74 68 65 20  olumns.  in the 
19130 74 61 62 6c 65 2e 20 45 61 63 68 20 76 61 72 69  table. Each vari
19140 6e 74 20 69 6e 20 74 68 65 20 22 73 69 7a 65 22  nt in the "size"
19150 20 62 6c 6f 62 20 69 73 20 74 68 65 20 6e 75 6d   blob is the num
19160 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e  ber of tokens in
19170 20 74 68 65 0a 20 20 63 6f 72 72 65 73 70 6f 6e   the.  correspon
19180 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ding column of t
19190 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 72 6f  he associated ro
191a0 77 20 69 6e 20 74 68 65 20 46 54 53 20 74 61 62  w in the FTS tab
191b0 6c 65 2e 20 54 68 65 20 25 5f 73 74 61 74 20 74  le. The %_stat t
191c0 61 62 6c 65 0a 20 20 61 6c 77 61 79 73 20 63 6f  able.  always co
191d0 6e 74 61 69 6e 73 20 61 20 73 69 6e 67 6c 65 20  ntains a single 
191e0 72 6f 77 20 77 69 74 68 20 74 68 65 20 22 69 64  row with the "id
191f0 22 20 63 6f 6c 75 6d 6e 20 73 65 74 20 74 6f 20  " column set to 
19200 30 2e 20 54 68 65 20 22 76 61 6c 75 65 22 20 0a  0. The "value" .
19210 20 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e    column contain
19220 73 20 61 20 62 6c 6f 62 20 63 6f 6e 73 69 73 74  s a blob consist
19230 69 6e 67 20 6f 66 20 3c 69 3e 4e 2b 31 3c 2f 69  ing of <i>N+1</i
19240 3e 20 46 54 53 20 76 61 72 69 6e 74 73 2c 20 77  > FTS varints, w
19250 68 65 72 65 20 3c 69 3e 4e 3c 2f 69 3e 0a 20 20  here <i>N</i>.  
19260 69 73 20 61 67 61 69 6e 20 74 68 65 20 6e 75 6d  is again the num
19270 62 65 72 20 6f 66 20 75 73 65 72 2d 64 65 66 69  ber of user-defi
19280 6e 65 64 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  ned columns in t
19290 68 65 20 46 54 53 20 74 61 62 6c 65 2e 20 54 68  he FTS table. Th
192a0 65 20 66 69 72 73 74 0a 20 20 76 61 72 69 6e 74  e first.  varint
192b0 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 69 73 20   in the blob is 
192c0 73 65 74 20 74 6f 20 74 68 65 20 74 6f 74 61 6c  set to the total
192d0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
192e0 69 6e 20 74 68 65 20 46 54 53 20 74 61 62 6c 65  in the FTS table
192f0 2e 20 54 68 65 0a 20 20 73 65 63 6f 6e 64 20 61  . The.  second a
19300 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 76 61  nd subsequent va
19310 72 69 6e 74 73 20 63 6f 6e 74 61 69 6e 20 74 68  rints contain th
19320 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
19330 66 20 74 6f 6b 65 6e 73 20 73 74 6f 72 65 64 20  f tokens stored 
19340 69 6e 0a 20 20 74 68 65 20 63 6f 72 72 65 73 70  in.  the corresp
19350 6f 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 66 6f  onding column fo
19360 72 20 61 6c 6c 20 72 6f 77 73 20 6f 66 20 74 68  r all rows of th
19370 65 20 46 54 53 20 74 61 62 6c 65 2e 0a 0a 3c 70  e FTS table...<p
19380 3e 0a 20 20 54 68 65 20 74 77 6f 20 72 65 6d 61  >.  The two rema
19390 69 6e 69 6e 67 20 74 61 62 6c 65 73 2c 20 25 5f  ining tables, %_
193a0 73 65 67 6d 65 6e 74 73 20 61 6e 64 20 25 5f 73  segments and %_s
193b0 65 67 64 69 72 2c 20 61 72 65 20 75 73 65 64 20  egdir, are used 
193c0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 0a 20 20  to store the .  
193d0 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e  full-text index.
193e0 20 43 6f 6e 63 65 70 74 75 61 6c 6c 79 2c 20 74   Conceptually, t
193f0 68 69 73 20 69 6e 64 65 78 20 69 73 20 61 20 6c  his index is a l
19400 6f 6f 6b 75 70 20 74 61 62 6c 65 20 74 68 61 74  ookup table that
19410 20 6d 61 70 73 20 65 61 63 68 20 0a 20 20 74 65   maps each .  te
19420 72 6d 20 28 77 6f 72 64 29 20 74 6f 20 74 68 65  rm (word) to the
19430 20 73 65 74 20 6f 66 20 64 6f 63 69 64 20 76 61   set of docid va
19440 6c 75 65 73 20 63 6f 72 72 65 73 70 6f 6e 64 69  lues correspondi
19450 6e 67 20 74 6f 20 72 65 63 6f 72 64 73 20 69 6e  ng to records in
19460 20 74 68 65 20 0a 20 20 25 5f 63 6f 6e 74 65 6e   the .  %_conten
19470 74 20 74 61 62 6c 65 20 74 68 61 74 20 63 6f 6e  t table that con
19480 74 61 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  tain one or more
19490 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
194a0 74 68 65 20 74 65 72 6d 2e 20 54 6f 0a 20 20 72  the term. To.  r
194b0 65 74 72 69 65 76 65 20 61 6c 6c 20 64 6f 63 75  etrieve all docu
194c0 6d 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61  ments that conta
194d0 69 6e 20 61 20 73 70 65 63 69 66 69 65 64 20 74  in a specified t
194e0 65 72 6d 2c 20 74 68 65 20 46 54 53 20 6d 6f 64  erm, the FTS mod
194f0 75 6c 65 0a 20 20 71 75 65 72 69 65 73 20 74 68  ule.  queries th
19500 69 73 20 69 6e 64 65 78 20 74 6f 20 64 65 74 65  is index to dete
19510 72 6d 69 6e 65 20 74 68 65 20 73 65 74 20 6f 66  rmine the set of
19520 20 64 6f 63 69 64 20 76 61 6c 75 65 73 20 66 6f   docid values fo
19530 72 20 72 65 63 6f 72 64 73 20 74 68 61 74 0a 20  r records that. 
19540 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 74 65 72   contain the ter
19550 6d 2c 20 74 68 65 6e 20 72 65 74 72 69 65 76 65  m, then retrieve
19560 73 20 74 68 65 20 72 65 71 75 69 72 65 64 20 64  s the required d
19570 6f 63 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  ocuments from th
19580 65 20 25 5f 63 6f 6e 74 65 6e 74 0a 20 20 74 61  e %_content.  ta
19590 62 6c 65 2e 20 52 65 67 61 72 64 6c 65 73 73 20  ble. Regardless 
195a0 6f 66 20 74 68 65 20 73 63 68 65 6d 61 20 6f 66  of the schema of
195b0 20 74 68 65 20 46 54 53 20 76 69 72 74 75 61 6c   the FTS virtual
195c0 20 74 61 62 6c 65 2c 20 74 68 65 20 25 5f 73 65   table, the %_se
195d0 67 6d 65 6e 74 73 0a 20 20 61 6e 64 20 25 5f 73  gments.  and %_s
195e0 65 67 64 69 72 20 74 61 62 6c 65 73 20 61 72 65  egdir tables are
195f0 20 61 6c 77 61 79 73 20 63 72 65 61 74 65 64 20   always created 
19600 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f  as follows:..<co
19610 64 65 62 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54  deblock>.  CREAT
19620 45 20 54 41 42 4c 45 20 25 5f 73 65 67 6d 65 6e  E TABLE %_segmen
19630 74 73 28 0a 20 20 20 20 62 6c 6f 63 6b 69 64 20  ts(.    blockid 
19640 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19650 4b 45 59 2c 20 20 20 20 20 20 20 3c 69 3e 2d 2d  KEY,       <i>--
19660 20 42 2d 74 72 65 65 20 6e 6f 64 65 20 69 64 3c   B-tree node id<
19670 2f 69 3e 0a 20 20 20 20 62 6c 6f 63 6b 20 62 6c  /i>.    block bl
19680 6f 62 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ob              
19690 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d             <i>--
196a0 20 42 2d 74 72 65 65 20 6e 6f 64 65 20 64 61 74   B-tree node dat
196b0 61 3c 2f 69 3e 0a 20 20 29 3b 0a 0a 20 20 43 52  a</i>.  );..  CR
196c0 45 41 54 45 20 54 41 42 4c 45 20 25 5f 73 65 67  EATE TABLE %_seg
196d0 64 69 72 28 0a 20 20 20 20 6c 65 76 65 6c 20 49  dir(.    level I
196e0 4e 54 45 47 45 52 2c 0a 20 20 20 20 69 64 78 20  NTEGER,.    idx 
196f0 49 4e 54 45 47 45 52 2c 0a 20 20 20 20 73 74 61  INTEGER,.    sta
19700 72 74 5f 62 6c 6f 63 6b 20 49 4e 54 45 47 45 52  rt_block INTEGER
19710 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
19720 3c 69 3e 2d 2d 20 42 6c 6f 63 6b 69 64 20 6f 66  <i>-- Blockid of
19730 20 66 69 72 73 74 20 6e 6f 64 65 20 69 6e 20 25   first node in %
19740 5f 73 65 67 6d 65 6e 74 73 3c 2f 69 3e 0a 20 20  _segments</i>.  
19750 20 20 6c 65 61 76 65 73 5f 65 6e 64 5f 62 6c 6f    leaves_end_blo
19760 63 6b 20 49 4e 54 45 47 45 52 2c 20 20 20 20 20  ck INTEGER,     
19770 20 20 20 20 20 3c 69 3e 2d 2d 20 42 6c 6f 63 6b       <i>-- Block
19780 69 64 20 6f 66 20 6c 61 73 74 20 6c 65 61 66 20  id of last leaf 
19790 6e 6f 64 65 20 69 6e 20 25 5f 73 65 67 6d 65 6e  node in %_segmen
197a0 74 73 3c 2f 69 3e 0a 20 20 20 20 65 6e 64 5f 62  ts</i>.    end_b
197b0 6c 6f 63 6b 20 49 4e 54 45 47 45 52 2c 20 20 20  lock INTEGER,   
197c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69                <i
197d0 3e 2d 2d 20 42 6c 6f 63 6b 69 64 20 6f 66 20 6c  >-- Blockid of l
197e0 61 73 74 20 6e 6f 64 65 20 69 6e 20 25 5f 73 65  ast node in %_se
197f0 67 6d 65 6e 74 73 3c 2f 69 3e 0a 20 20 20 20 72  gments</i>.    r
19800 6f 6f 74 20 42 4c 4f 42 2c 20 20 20 20 20 20 20  oot BLOB,       
19810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19820 20 20 3c 69 3e 2d 2d 20 42 2d 74 72 65 65 20 72    <i>-- B-tree r
19830 6f 6f 74 20 6e 6f 64 65 3c 2f 69 3e 0a 20 20 20  oot node</i>.   
19840 20 50 52 49 4d 41 52 59 20 4b 45 59 28 6c 65 76   PRIMARY KEY(lev
19850 65 6c 2c 20 69 64 78 29 0a 20 20 29 3b 0a 3c 2f  el, idx).  );.</
19860 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
19870 20 20 54 68 65 20 73 63 68 65 6d 61 20 64 65 70    The schema dep
19880 69 63 74 65 64 20 61 62 6f 76 65 20 69 73 20 6e  icted above is n
19890 6f 74 20 64 65 73 69 67 6e 65 64 20 74 6f 20 73  ot designed to s
198a0 74 6f 72 65 20 74 68 65 20 66 75 6c 6c 2d 74 65  tore the full-te
198b0 78 74 20 69 6e 64 65 78 20 0a 20 20 64 69 72 65  xt index .  dire
198c0 63 74 6c 79 2e 20 49 6e 73 74 65 61 64 2c 20 69  ctly. Instead, i
198d0 74 20 69 73 20 75 73 65 64 20 74 6f 20 6f 6e 65  t is used to one
198e0 20 6f 72 20 6d 6f 72 65 20 62 2d 74 72 65 65 20   or more b-tree 
198f0 73 74 72 75 63 74 75 72 65 73 2e 20 54 68 65 72  structures. Ther
19900 65 0a 20 20 69 73 20 6f 6e 65 20 62 2d 74 72 65  e.  is one b-tre
19910 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 69  e for each row i
19920 6e 20 74 68 65 20 25 5f 73 65 67 64 69 72 20 74  n the %_segdir t
19930 61 62 6c 65 2e 20 54 68 65 20 25 5f 73 65 67 64  able. The %_segd
19940 69 72 20 74 61 62 6c 65 0a 20 20 72 6f 77 20 63  ir table.  row c
19950 6f 6e 74 61 69 6e 73 20 74 68 65 20 72 6f 6f 74  ontains the root
19960 20 6e 6f 64 65 20 61 6e 64 20 76 61 72 69 6f 75   node and variou
19970 73 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f  s meta-data asso
19980 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a  ciated with the.
19990 20 20 62 2d 74 72 65 65 20 73 74 72 75 63 74 75    b-tree structu
199a0 72 65 2c 20 61 6e 64 20 74 68 65 20 25 5f 73 65  re, and the %_se
199b0 67 6d 65 6e 74 73 20 74 61 62 6c 65 20 63 6f 6e  gments table con
199c0 74 61 69 6e 73 20 61 6c 6c 20 6f 74 68 65 72 20  tains all other 
199d0 28 6e 6f 6e 2d 72 6f 6f 74 29 0a 20 20 62 2d 74  (non-root).  b-t
199e0 72 65 65 20 6e 6f 64 65 73 2e 20 45 61 63 68 20  ree nodes. Each 
199f0 62 2d 74 72 65 65 20 69 73 20 72 65 66 65 72 72  b-tree is referr
19a00 65 64 20 74 6f 20 61 73 20 61 20 22 73 65 67 6d  ed to as a "segm
19a10 65 6e 74 22 2e 20 4f 6e 63 65 20 69 74 20 68 61  ent". Once it ha
19a20 73 0a 20 20 62 65 65 6e 20 63 72 65 61 74 65 64  s.  been created
19a30 2c 20 61 20 73 65 67 6d 65 6e 74 20 62 2d 74 72  , a segment b-tr
19a40 65 65 20 69 73 20 6e 65 76 65 72 20 75 70 64 61  ee is never upda
19a50 74 65 64 20 28 61 6c 74 68 6f 75 67 68 20 69 74  ted (although it
19a60 20 6d 61 79 20 62 65 0a 20 20 64 65 6c 65 74 65   may be.  delete
19a70 64 20 61 6c 74 6f 67 65 74 68 65 72 29 2e 0a 0a  d altogether)...
19a80 3c 70 3e 0a 20 20 54 68 65 20 6b 65 79 73 20 75  <p>.  The keys u
19a90 73 65 64 20 62 79 20 65 61 63 68 20 73 65 67 6d  sed by each segm
19aa0 65 6e 74 20 62 2d 74 72 65 65 20 61 72 65 20 74  ent b-tree are t
19ab0 65 72 6d 73 20 28 77 6f 72 64 73 29 2e 20 41 73  erms (words). As
19ac0 20 77 65 6c 6c 20 61 73 20 74 68 65 0a 20 20 6b   well as the.  k
19ad0 65 79 2c 20 65 61 63 68 20 73 65 67 6d 65 6e 74  ey, each segment
19ae0 20 62 2d 74 72 65 65 20 65 6e 74 72 79 20 68 61   b-tree entry ha
19af0 73 20 61 6e 20 61 73 73 6f 63 69 61 74 65 64 20  s an associated 
19b00 22 64 6f 63 6c 69 73 74 22 20 28 64 6f 63 75 6d  "doclist" (docum
19b10 65 6e 74 20 6c 69 73 74 29 2e 0a 20 20 41 20 64  ent list)..  A d
19b20 6f 63 6c 69 73 74 20 63 6f 6e 73 69 73 74 73 20  oclist consists 
19b30 6f 66 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  of zero or more 
19b40 65 6e 74 72 69 65 73 2c 20 77 68 65 72 65 20 65  entries, where e
19b50 61 63 68 20 65 6e 74 72 79 20 63 6f 6e 73 69 73  ach entry consis
19b60 74 73 20 6f 66 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c  ts of:..<ul>.  <
19b70 6c 69 3e 20 41 20 64 6f 63 69 64 20 28 64 6f 63  li> A docid (doc
19b80 75 6d 65 6e 74 20 69 64 29 2c 20 61 6e 64 0a 20  ument id), and. 
19b90 20 3c 6c 69 3e 20 41 20 6c 69 73 74 20 6f 66 20   <li> A list of 
19ba0 74 65 72 6d 20 6f 66 66 73 65 74 73 2c 20 6f 6e  term offsets, on
19bb0 65 20 66 6f 72 20 65 61 63 68 20 6f 63 63 75 72  e for each occur
19bc0 72 65 6e 63 65 20 6f 66 20 74 68 65 20 74 65 72  rence of the ter
19bd0 6d 20 77 69 74 68 69 6e 0a 20 20 20 20 20 20 20  m within.       
19be0 74 68 65 20 64 6f 63 75 6d 65 6e 74 2e 20 41 20  the document. A 
19bf0 74 65 72 6d 20 6f 66 66 73 65 74 20 69 6e 64 69  term offset indi
19c00 63 61 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72  cates the number
19c10 20 6f 66 20 74 6f 6b 65 6e 73 20 28 77 6f 72 64   of tokens (word
19c20 73 29 0a 20 20 20 20 20 20 20 74 68 61 74 20 6f  s).       that o
19c30 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 65 20  ccur before the 
19c40 74 65 72 6d 20 69 6e 20 71 75 65 73 74 69 6f 6e  term in question
19c50 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
19c60 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 0a 20   of characters. 
19c70 20 20 20 20 20 20 6f 72 20 62 79 74 65 73 2e 20        or bytes. 
19c80 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65  For example, the
19c90 20 74 65 72 6d 20 6f 66 66 73 65 74 20 6f 66 20   term offset of 
19ca0 74 68 65 20 74 65 72 6d 20 22 77 61 72 22 20 69  the term "war" i
19cb0 6e 20 74 68 65 0a 20 20 20 20 20 20 20 70 68 72  n the.       phr
19cc0 61 73 65 20 22 41 6e 63 65 73 74 72 61 6c 20 76  ase "Ancestral v
19cd0 6f 69 63 65 73 20 70 72 6f 70 68 65 73 79 69 6e  oices prophesyin
19ce0 67 20 77 61 72 21 22 20 69 73 20 33 2e 0a 3c 2f  g war!" is 3..</
19cf0 75 6c 3e 0a 0a 3c 70 3e 0a 20 20 45 6e 74 72 69  ul>..<p>.  Entri
19d00 65 73 20 77 69 74 68 69 6e 20 61 20 64 6f 63 6c  es within a docl
19d10 69 73 74 20 61 72 65 20 73 6f 72 74 65 64 20 62  ist are sorted b
19d20 79 20 64 6f 63 69 64 2e 20 50 6f 73 69 74 69 6f  y docid. Positio
19d30 6e 73 20 77 69 74 68 69 6e 20 61 20 64 6f 63 6c  ns within a docl
19d40 69 73 74 0a 20 20 65 6e 74 72 79 20 61 72 65 20  ist.  entry are 
19d50 73 74 6f 72 65 64 20 69 6e 20 61 73 63 65 6e 64  stored in ascend
19d60 69 6e 67 20 6f 72 64 65 72 2e 0a 0a 3c 70 3e 0a  ing order...<p>.
19d70 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f    The contents o
19d80 66 20 74 68 65 20 6c 6f 67 69 63 61 6c 20 66 75  f the logical fu
19d90 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 69 73  ll-text index is
19da0 20 66 6f 75 6e 64 20 62 79 20 6d 65 72 67 69 6e   found by mergin
19db0 67 20 74 68 65 0a 20 20 63 6f 6e 74 65 6e 74 73  g the.  contents
19dc0 20 6f 66 20 61 6c 6c 20 73 65 67 6d 65 6e 74 20   of all segment 
19dd0 62 2d 74 72 65 65 73 2e 20 49 66 20 61 20 74 65  b-trees. If a te
19de0 72 6d 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  rm is present in
19df0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 20   more than one. 
19e00 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 2c   segment b-tree,
19e10 20 74 68 65 6e 20 69 74 20 6d 61 70 73 20 74 6f   then it maps to
19e20 20 74 68 65 20 75 6e 69 6f 6e 20 6f 66 20 65 61   the union of ea
19e30 63 68 20 69 6e 64 69 76 69 64 75 61 6c 20 64 6f  ch individual do
19e40 63 6c 69 73 74 2e 20 49 66 2c 0a 20 20 66 6f 72  clist. If,.  for
19e50 20 61 20 73 69 6e 67 6c 65 20 74 65 72 6d 2c 20   a single term, 
19e60 74 68 65 20 73 61 6d 65 20 64 6f 63 69 64 20 6f  the same docid o
19e70 63 63 75 72 73 20 69 6e 20 6d 6f 72 65 20 74 68  ccurs in more th
19e80 61 6e 20 6f 6e 65 20 64 6f 63 6c 69 73 74 2c 20  an one doclist, 
19e90 74 68 65 6e 20 6f 6e 6c 79 0a 20 20 74 68 65 20  then only.  the 
19ea0 64 6f 63 6c 69 73 74 20 74 68 61 74 20 69 73 20  doclist that is 
19eb0 70 61 72 74 20 6f 66 20 74 68 65 20 6d 6f 73 74  part of the most
19ec0 20 72 65 63 65 6e 74 6c 79 20 63 72 65 61 74 65   recently create
19ed0 64 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65 65  d segment b-tree
19ee0 20 69 73 20 0a 20 20 63 6f 6e 73 69 64 65 72 65   is .  considere
19ef0 64 20 76 61 6c 69 64 2e 20 0a 0a 3c 70 3e 0a 20  d valid. ..<p>. 
19f00 20 4d 75 6c 74 69 70 6c 65 20 62 2d 74 72 65 65   Multiple b-tree
19f10 20 73 74 72 75 63 74 75 72 65 73 20 61 72 65 20   structures are 
19f20 75 73 65 64 20 69 6e 73 74 65 61 64 20 6f 66 20  used instead of 
19f30 61 20 73 69 6e 67 6c 65 20 62 2d 74 72 65 65 20  a single b-tree 
19f40 74 6f 20 72 65 64 75 63 65 0a 20 20 74 68 65 20  to reduce.  the 
19f50 63 6f 73 74 20 6f 66 20 69 6e 73 65 72 74 69 6e  cost of insertin
19f60 67 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 46  g records into F
19f70 54 53 20 74 61 62 6c 65 73 2e 20 57 68 65 6e 20  TS tables. When 
19f80 61 20 6e 65 77 20 72 65 63 6f 72 64 20 69 73 20  a new record is 
19f90 0a 20 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  .  inserted into
19fa0 20 61 6e 20 46 54 53 20 74 61 62 6c 65 20 74 68   an FTS table th
19fb0 61 74 20 61 6c 72 65 61 64 79 20 63 6f 6e 74 61  at already conta
19fc0 69 6e 73 20 61 20 6c 6f 74 20 6f 66 20 64 61 74  ins a lot of dat
19fd0 61 2c 20 69 74 20 69 73 0a 20 20 6c 69 6b 65 6c  a, it is.  likel
19fe0 79 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 20 74  y that many of t
19ff0 68 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  he terms in the 
1a000 6e 65 77 20 72 65 63 6f 72 64 20 61 72 65 20 61  new record are a
1a010 6c 72 65 61 64 79 20 70 72 65 73 65 6e 74 20 69  lready present i
1a020 6e 0a 20 20 61 20 6c 61 72 67 65 20 6e 75 6d 62  n.  a large numb
1a030 65 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 72  er of existing r
1a040 65 63 6f 72 64 73 2e 20 49 66 20 61 20 73 69 6e  ecords. If a sin
1a050 67 6c 65 20 62 2d 74 72 65 65 20 77 65 72 65 20  gle b-tree were 
1a060 75 73 65 64 2c 20 74 68 65 6e 0a 20 20 6c 61 72  used, then.  lar
1a070 67 65 20 64 6f 63 6c 69 73 74 20 73 74 72 75 63  ge doclist struc
1a080 74 75 72 65 73 20 77 6f 75 6c 64 20 68 61 76 65  tures would have
1a090 20 74 6f 20 62 65 20 6c 6f 61 64 65 64 20 66 72   to be loaded fr
1a0a0 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  om the database,
1a0b0 0a 20 20 61 6d 65 6e 64 65 64 20 74 6f 20 69 6e  .  amended to in
1a0c0 63 6c 75 64 65 20 74 68 65 20 6e 65 77 20 64 6f  clude the new do
1a0d0 63 69 64 20 61 6e 64 20 74 65 72 6d 2d 6f 66 66  cid and term-off
1a0e0 73 65 74 20 6c 69 73 74 2c 20 74 68 65 6e 20 77  set list, then w
1a0f0 72 69 74 74 65 6e 20 62 61 63 6b 0a 20 20 74 6f  ritten back.  to
1a100 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 55   the database. U
1a110 73 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 62 2d  sing multiple b-
1a120 74 72 65 65 20 74 61 62 6c 65 73 20 61 6c 6c 6f  tree tables allo
1a130 77 73 20 74 68 69 73 20 74 6f 20 62 65 20 61 76  ws this to be av
1a140 6f 69 64 65 64 0a 20 20 62 79 20 63 72 65 61 74  oided.  by creat
1a150 69 6e 67 20 61 20 6e 65 77 20 62 2d 74 72 65 65  ing a new b-tree
1a160 20 77 68 69 63 68 20 63 61 6e 20 62 65 20 6d 65   which can be me
1a170 72 67 65 64 20 77 69 74 68 20 74 68 65 20 65 78  rged with the ex
1a180 69 73 74 69 6e 67 20 62 2d 74 72 65 65 0a 20 20  isting b-tree.  
1a190 28 6f 72 20 62 2d 74 72 65 65 73 29 20 6c 61 74  (or b-trees) lat
1a1a0 65 72 20 6f 6e 2e 20 4d 65 72 67 69 6e 67 20 6f  er on. Merging o
1a1b0 66 20 62 2d 74 72 65 65 20 73 74 72 75 63 74 75  f b-tree structu
1a1c0 72 65 73 20 63 61 6e 20 62 65 20 70 65 72 66 6f  res can be perfo
1a1d0 72 6d 65 64 20 61 73 0a 20 20 61 20 62 61 63 6b  rmed as.  a back
1a1e0 67 72 6f 75 6e 64 20 74 61 73 6b 2c 20 6f 72 20  ground task, or 
1a1f0 6f 6e 63 65 20 61 20 63 65 72 74 61 69 6e 20 6e  once a certain n
1a200 75 6d 62 65 72 20 6f 66 20 73 65 70 61 72 61 74  umber of separat
1a210 65 20 62 2d 74 72 65 65 20 73 74 72 75 63 74 75  e b-tree structu
1a220 72 65 73 0a 20 20 68 61 76 65 20 62 65 65 6e 20  res.  have been 
1a230 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 4f 66 20  accumulated. Of 
1a240 63 6f 75 72 73 65 2c 20 74 68 69 73 20 73 63 68  course, this sch
1a250 65 6d 65 20 6d 61 6b 65 73 20 71 75 65 72 69 65  eme makes querie
1a260 73 20 6d 6f 72 65 20 65 78 70 65 6e 73 69 76 65  s more expensive
1a270 0a 20 20 28 61 73 20 74 68 65 20 46 54 53 20 63  .  (as the FTS c
1a280 6f 64 65 20 6d 61 79 20 68 61 76 65 20 74 6f 20  ode may have to 
1a290 6c 6f 6f 6b 20 75 70 20 69 6e 64 69 76 69 64 75  look up individu
1a2a0 61 6c 20 74 65 72 6d 73 20 69 6e 20 6d 6f 72 65  al terms in more
1a2b0 20 74 68 61 6e 20 6f 6e 65 0a 20 20 62 2d 74 72   than one.  b-tr
1a2c0 65 65 20 61 6e 64 20 6d 65 72 67 65 20 74 68 65  ee and merge the
1a2d0 20 72 65 73 75 6c 74 73 29 2c 20 62 75 74 20 69   results), but i
1a2e0 74 20 68 61 73 20 62 65 65 6e 20 66 6f 75 6e 64  t has been found
1a2f0 20 74 68 61 74 20 69 6e 20 70 72 61 63 74 69 63   that in practic
1a300 65 20 74 68 69 73 0a 20 20 6f 76 65 72 68 65 61  e this.  overhea
1a310 64 20 69 73 20 6f 66 74 65 6e 20 6e 65 67 6c 69  d is often negli
1a320 67 69 62 6c 65 2e 0a 20 20 0a 3c 68 32 3e 56 61  gible..  .<h2>Va
1a330 72 69 61 62 6c 65 20 4c 65 6e 67 74 68 20 49 6e  riable Length In
1a340 74 65 67 65 72 20 28 76 61 72 69 6e 74 29 20 46  teger (varint) F
1a350 6f 72 6d 61 74 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a  ormat</h2>..<p>.
1a360 20 20 49 6e 74 65 67 65 72 20 76 61 6c 75 65 73    Integer values
1a370 20 73 74 6f 72 65 64 20 61 73 20 70 61 72 74 20   stored as part 
1a380 6f 66 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65  of segment b-tre
1a390 65 20 6e 6f 64 65 73 20 61 72 65 20 65 6e 63 6f  e nodes are enco
1a3a0 64 65 64 20 75 73 69 6e 67 20 74 68 65 0a 20 20  ded using the.  
1a3b0 46 54 53 20 76 61 72 69 6e 74 20 66 6f 72 6d 61  FTS varint forma
1a3c0 74 2e 20 54 68 69 73 20 65 6e 63 6f 64 69 6e 67  t. This encoding
1a3d0 20 69 73 20 73 69 6d 69 6c 61 72 2c 20 62 75 74   is similar, but
1a3e0 20 3c 62 3e 6e 6f 74 20 69 64 65 6e 74 69 63 61   <b>not identica
1a3f0 6c 3c 2f 62 3e 2c 20 74 6f 0a 20 20 74 68 65 20  l</b>, to.  the 
1a400 3c 61 20 68 72 65 66 3d 22 66 69 6c 65 66 6f 72  <a href="filefor
1a410 6d 61 74 2e 68 74 6d 6c 23 76 61 72 69 6e 74 5f  mat.html#varint_
1a420 66 6f 72 6d 61 74 22 3e 53 51 4c 69 74 65 20 76  format">SQLite v
1a430 61 72 69 6e 74 20 66 6f 72 6d 61 74 3c 2f 61 3e  arint format</a>
1a440 2e 0a 0a 3c 70 3e 0a 20 20 41 6e 20 65 6e 63 6f  ...<p>.  An enco
1a450 64 65 64 20 46 54 53 20 76 61 72 69 6e 74 20 63  ded FTS varint c
1a460 6f 6e 73 75 6d 65 73 20 62 65 74 77 65 65 6e 20  onsumes between 
1a470 6f 6e 65 20 61 6e 64 20 74 65 6e 20 62 79 74 65  one and ten byte
1a480 73 20 6f 66 20 73 70 61 63 65 2e 20 54 68 65 0a  s of space. The.
1a490 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
1a4a0 73 20 72 65 71 75 69 72 65 64 20 69 73 20 64 65  s required is de
1a4b0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
1a4c0 73 69 67 6e 20 61 6e 64 20 6d 61 67 6e 69 74 75  sign and magnitu
1a4d0 64 65 20 6f 66 20 74 68 65 0a 20 20 69 6e 74 65  de of the.  inte
1a4e0 67 65 72 20 76 61 6c 75 65 20 65 6e 63 6f 64 65  ger value encode
1a4f0 64 2e 20 4d 6f 72 65 20 61 63 63 75 72 61 74 65  d. More accurate
1a500 6c 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ly, the number o
1a510 66 20 62 79 74 65 73 20 75 73 65 64 20 74 6f 20  f bytes used to 
1a520 73 74 6f 72 65 0a 20 20 74 68 65 20 65 6e 63 6f  store.  the enco
1a530 64 65 64 20 69 6e 74 65 67 65 72 20 64 65 70 65  ded integer depe
1a540 6e 64 73 20 6f 6e 20 74 68 65 20 70 6f 73 69 74  nds on the posit
1a550 69 6f 6e 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  ion of the most 
1a560 73 69 67 6e 69 66 69 63 61 6e 74 20 73 65 74 20  significant set 
1a570 62 69 74 0a 20 20 69 6e 20 74 68 65 20 36 34 2d  bit.  in the 64-
1a580 62 69 74 20 74 77 6f 73 2d 63 6f 6d 70 6c 65 6d  bit twos-complem
1a590 65 6e 74 20 72 65 70 72 65 73 65 6e 74 61 74 69  ent representati
1a5a0 6f 6e 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  on of the intege
1a5b0 72 20 76 61 6c 75 65 2e 20 4e 65 67 61 74 69 76  r value. Negativ
1a5c0 65 0a 20 20 76 61 6c 75 65 73 20 61 6c 77 61 79  e.  values alway
1a5d0 73 20 68 61 76 65 20 74 68 65 20 6d 6f 73 74 20  s have the most 
1a5e0 73 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74 20  significant bit 
1a5f0 73 65 74 20 28 74 68 65 20 73 69 67 6e 20 62 69  set (the sign bi
1a600 74 29 2c 20 61 6e 64 20 73 6f 20 61 72 65 0a 20  t), and so are. 
1a610 20 61 6c 77 61 79 73 20 73 74 6f 72 65 64 20 75   always stored u
1a620 73 69 6e 67 20 74 68 65 20 66 75 6c 6c 20 74 65  sing the full te
1a630 6e 20 62 79 74 65 73 2e 20 50 6f 73 69 74 69 76  n bytes. Positiv
1a640 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
1a650 20 6d 61 79 20 62 65 0a 20 20 73 74 6f 72 65 64   may be.  stored
1a660 20 75 73 69 6e 67 20 6c 65 73 73 20 73 70 61 63   using less spac
1a670 65 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 66 69  e...<p>.  The fi
1a680 6e 61 6c 20 62 79 74 65 20 6f 66 20 61 6e 20 65  nal byte of an e
1a690 6e 63 6f 64 65 64 20 46 54 53 20 76 61 72 69 6e  ncoded FTS varin
1a6a0 74 20 68 61 73 20 69 74 73 20 6d 6f 73 74 20 73  t has its most s
1a6b0 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74 20 0a  ignificant bit .
1a6c0 20 20 63 6c 65 61 72 65 64 2e 20 41 6c 6c 20 70    cleared. All p
1a6d0 72 65 63 65 64 69 6e 67 20 62 79 74 65 73 20 68  receding bytes h
1a6e0 61 76 65 20 74 68 65 20 6d 6f 73 74 20 73 69 67  ave the most sig
1a6f0 6e 69 66 69 63 61 6e 74 20 62 69 74 20 73 65 74  nificant bit set
1a700 2e 20 44 61 74 61 0a 20 20 69 73 20 73 74 6f 72  . Data.  is stor
1a710 65 64 20 69 6e 20 74 68 65 20 72 65 6d 61 69 6e  ed in the remain
1a720 69 6e 67 20 73 65 76 65 6e 20 6c 65 61 73 74 20  ing seven least 
1a730 73 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74 73  significant bits
1a740 20 6f 66 20 65 61 63 68 20 62 79 74 65 2e 0a 20   of each byte.. 
1a750 20 54 68 65 20 66 69 72 73 74 20 62 79 74 65 20   The first byte 
1a760 6f 66 20 74 68 65 20 65 6e 63 6f 64 65 64 20 72  of the encoded r
1a770 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 63 6f  epresentation co
1a780 6e 74 61 69 6e 73 20 74 68 65 20 6c 65 61 73 74  ntains the least
1a790 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 20 20 73   significant.  s
1a7a0 65 76 65 6e 20 62 69 74 73 20 6f 66 20 74 68 65  even bits of the
1a7b0 20 65 6e 63 6f 64 65 64 20 69 6e 74 65 67 65 72   encoded integer
1a7c0 20 76 61 6c 75 65 2e 20 54 68 65 20 73 65 63 6f   value. The seco
1a7d0 6e 64 20 62 79 74 65 20 6f 66 20 74 68 65 20 65  nd byte of the e
1a7e0 6e 63 6f 64 65 64 0a 20 20 72 65 70 72 65 73 65  ncoded.  represe
1a7f0 6e 74 61 74 69 6f 6e 2c 20 69 66 20 69 74 20 69  ntation, if it i
1a800 73 20 70 72 65 73 65 6e 74 2c 20 63 6f 6e 74 61  s present, conta
1a810 69 6e 73 20 74 68 65 20 73 65 76 65 6e 20 6e 65  ins the seven ne
1a820 78 74 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  xt least signifi
1a830 63 61 6e 74 0a 20 20 62 69 74 73 20 6f 66 20 74  cant.  bits of t
1a840 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
1a850 2c 20 61 6e 64 20 73 6f 20 6f 6e 2e 20 54 68 65  , and so on. The
1a860 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
1a870 20 63 6f 6e 74 61 69 6e 73 20 65 78 61 6d 70 6c   contains exampl
1a880 65 73 0a 20 20 6f 66 20 65 6e 63 6f 64 65 64 20  es.  of encoded 
1a890 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 3a 0a  integer values:.
1a8a0 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65 64 3d  .<table striped=
1a8b0 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 44 65 63  1>.  <tr><th>Dec
1a8c0 69 6d 61 6c 3c 74 68 3e 48 65 78 61 64 65 63 69  imal<th>Hexadeci
1a8d0 6d 61 6c 3c 74 68 20 77 69 64 74 68 3d 31 30 30  mal<th width=100
1a8e0 25 3e 45 6e 63 6f 64 65 64 20 52 65 70 72 65 73  %>Encoded Repres
1a8f0 65 6e 74 61 74 69 6f 6e 0a 20 20 3c 74 72 3e 3c  entation.  <tr><
1a900 74 64 3e 34 33 3c 74 64 3e 30 78 30 30 30 30 30  td>43<td>0x00000
1a910 30 30 30 30 30 30 30 30 30 32 42 3c 74 64 3e 30  0000000002B<td>0
1a920 78 32 42 20 0a 20 20 3c 74 72 3e 3c 74 64 3e 32  x2B .  <tr><td>2
1a930 30 30 38 31 35 3c 74 64 3e 30 78 30 30 30 30 30  00815<td>0x00000
1a940 30 30 30 30 30 30 33 31 30 36 46 3c 74 64 3e 30  0000003106F<td>0
1a950 78 39 43 20 30 78 41 30 20 30 78 30 43 0a 20 20  x9C 0xA0 0x0C.  
1a960 3c 74 72 3e 3c 74 64 3e 2d 31 3c 74 64 3e 30 78  <tr><td>-1<td>0x
1a970 46 46 46 46 46 46 46 46 46 46 46 46 46 46 46 46  FFFFFFFFFFFFFFFF
1a980 3c 74 64 3e 30 78 46 46 20 30 78 46 46 20 30 78  <td>0xFF 0xFF 0x
1a990 46 46 20 30 78 46 46 20 30 78 46 46 20 30 78 46  FF 0xFF 0xFF 0xF
1a9a0 46 20 30 78 46 46 20 30 78 46 46 20 30 78 46 46  F 0xFF 0xFF 0xFF
1a9b0 20 30 78 30 31 0a 3c 2f 74 61 62 6c 65 3e 0a 20   0x01.</table>. 
1a9c0 20 0a 0a 3c 68 32 3e 53 65 67 6d 65 6e 74 20 42   ..<h2>Segment B
1a9d0 2d 54 72 65 65 20 46 6f 72 6d 61 74 3c 2f 68 32  -Tree Format</h2
1a9e0 3e 0a 0a 3c 70 3e 0a 20 20 53 65 67 6d 65 6e 74  >..<p>.  Segment
1a9f0 20 62 2d 74 72 65 65 73 20 61 72 65 20 70 72 65   b-trees are pre
1aa00 66 69 78 2d 63 6f 6d 70 72 65 73 73 65 64 20 62  fix-compressed b
1aa10 2b 2d 74 72 65 65 73 2e 20 54 68 65 72 65 20 69  +-trees. There i
1aa20 73 20 6f 6e 65 20 73 65 67 6d 65 6e 74 20 62 2d  s one segment b-
1aa30 74 72 65 65 0a 20 20 66 6f 72 20 65 61 63 68 20  tree.  for each 
1aa40 72 6f 77 20 69 6e 20 74 68 65 20 25 5f 73 65 67  row in the %_seg
1aa50 64 69 72 20 74 61 62 6c 65 20 28 73 65 65 20 61  dir table (see a
1aa60 62 6f 76 65 29 2e 20 54 68 65 20 72 6f 6f 74 20  bove). The root 
1aa70 6e 6f 64 65 20 6f 66 20 74 68 65 20 73 65 67 6d  node of the segm
1aa80 65 6e 74 0a 20 20 62 2d 74 72 65 65 20 69 73 20  ent.  b-tree is 
1aa90 73 74 6f 72 65 64 20 61 73 20 61 20 62 6c 6f 62  stored as a blob
1aaa0 20 69 6e 20 74 68 65 20 22 72 6f 6f 74 22 20 66   in the "root" f
1aab0 69 65 6c 64 20 6f 66 20 74 68 65 20 63 6f 72 72  ield of the corr
1aac0 65 73 70 6f 6e 64 69 6e 67 20 72 6f 77 0a 20 20  esponding row.  
1aad0 6f 66 20 74 68 65 20 25 5f 73 65 67 64 69 72 20  of the %_segdir 
1aae0 74 61 62 6c 65 2e 20 41 6c 6c 20 6f 74 68 65 72  table. All other
1aaf0 20 6e 6f 64 65 73 20 28 69 66 20 61 6e 79 20 65   nodes (if any e
1ab00 78 69 73 74 29 20 61 72 65 20 73 74 6f 72 65 64  xist) are stored
1ab10 20 69 6e 20 74 68 65 20 0a 20 20 22 62 6c 6f 62   in the .  "blob
1ab20 22 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  " column of the 
1ab30 25 5f 73 65 67 6d 65 6e 74 73 20 74 61 62 6c 65  %_segments table
1ab40 2e 20 4e 6f 64 65 73 20 77 69 74 68 69 6e 20 74  . Nodes within t
1ab50 68 65 20 25 5f 73 65 67 6d 65 6e 74 73 20 74 61  he %_segments ta
1ab60 62 6c 65 20 61 72 65 0a 20 20 69 64 65 6e 74 69  ble are.  identi
1ab70 66 69 65 64 20 62 79 20 74 68 65 20 69 6e 74 65  fied by the inte
1ab80 67 65 72 20 76 61 6c 75 65 20 69 6e 20 74 68 65  ger value in the
1ab90 20 62 6c 6f 63 6b 69 64 20 66 69 65 6c 64 20 6f   blockid field o
1aba0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
1abb0 69 6e 67 0a 20 20 72 6f 77 2e 20 54 68 65 20 66  ing.  row. The f
1abc0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
1abd0 65 73 63 72 69 62 65 73 20 74 68 65 20 66 69 65  escribes the fie
1abe0 6c 64 73 20 6f 66 20 74 68 65 20 25 5f 73 65 67  lds of the %_seg
1abf0 64 69 72 20 74 61 62 6c 65 3a 0a 0a 3c 74 61 62  dir table:..<tab
1ac00 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20  le striped=1>.  
1ac10 3c 74 72 3e 3c 74 68 3e 43 6f 6c 75 6d 6e 20 20  <tr><th>Column  
1ac20 20 20 20 20 20 20 20 20 20 3c 74 68 20 77 69 64           <th wid
1ac30 74 68 3d 31 30 30 25 3e 49 6e 74 65 72 70 72 65  th=100%>Interpre
1ac40 74 61 74 69 6f 6e 0a 20 20 3c 74 72 3e 3c 74 64  tation.  <tr><td
1ac50 3e 6c 65 76 65 6c 20 20 20 20 20 20 20 20 20 20  >level          
1ac60 20 20 3c 74 64 3e 20 0a 20 20 20 20 42 65 74 77    <td> .    Betw
1ac70 65 65 6e 20 74 68 65 6d 2c 20 74 68 65 20 63 6f  een them, the co
1ac80 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 22 6c  ntents of the "l
1ac90 65 76 65 6c 22 20 61 6e 64 20 22 69 64 78 22 20  evel" and "idx" 
1aca0 66 69 65 6c 64 73 20 64 65 66 69 6e 65 20 74 68  fields define th
1acb0 65 0a 20 20 20 20 72 65 6c 61 74 69 76 65 20 61  e.    relative a
1acc0 67 65 20 6f 66 20 74 68 65 20 73 65 67 6d 65 6e  ge of the segmen
1acd0 74 20 62 2d 74 72 65 65 2e 20 54 68 65 20 73 6d  t b-tree. The sm
1ace0 61 6c 6c 65 72 20 74 68 65 20 76 61 6c 75 65 20  aller the value 
1acf0 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 20 20  stored in the.  
1ad00 20 20 22 6c 65 76 65 6c 22 20 66 69 65 6c 64 2c    "level" field,
1ad10 20 74 68 65 20 6d 6f 72 65 20 72 65 63 65 6e 74   the more recent
1ad20 6c 79 20 74 68 65 20 73 65 67 6d 65 6e 74 20 62  ly the segment b
1ad30 2d 74 72 65 65 20 77 61 73 20 63 72 65 61 74 65  -tree was create
1ad40 64 2e 20 49 66 20 74 77 6f 0a 20 20 20 20 73 65  d. If two.    se
1ad50 67 6d 65 6e 74 20 62 2d 74 72 65 65 73 20 61 72  gment b-trees ar
1ad60 65 20 6f 66 20 74 68 65 20 73 61 6d 65 20 22 6c  e of the same "l
1ad70 65 76 65 6c 22 2c 20 74 68 65 20 73 65 67 6d 65  evel", the segme
1ad80 6e 74 20 77 69 74 68 20 74 68 65 20 6c 61 72 67  nt with the larg
1ad90 65 72 0a 20 20 20 20 76 61 6c 75 65 20 73 74 6f  er.    value sto
1ada0 72 65 64 20 69 6e 20 74 68 65 20 22 69 64 78 22  red in the "idx"
1adb0 20 63 6f 6c 75 6d 6e 20 69 73 20 6d 6f 72 65 20   column is more 
1adc0 72 65 63 65 6e 74 2e 20 54 68 65 20 50 52 49 4d  recent. The PRIM
1add0 41 52 59 20 4b 45 59 20 63 6f 6e 73 74 72 61 69  ARY KEY constrai
1ade0 6e 74 0a 20 20 20 20 6f 6e 20 74 68 65 20 25 5f  nt.    on the %_
1adf0 73 65 67 64 69 72 20 74 61 62 6c 65 20 70 72 65  segdir table pre
1ae00 76 65 6e 74 73 20 61 6e 79 20 74 77 6f 20 73 65  vents any two se
1ae10 67 6d 65 6e 74 73 20 66 72 6f 6d 20 68 61 76 69  gments from havi
1ae20 6e 67 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  ng the same valu
1ae30 65 0a 20 20 20 20 66 6f 72 20 62 6f 74 68 20 74  e.    for both t
1ae40 68 65 20 22 6c 65 76 65 6c 22 20 61 6e 64 20 22  he "level" and "
1ae50 69 64 78 22 20 66 69 65 6c 64 73 2e 0a 20 20 3c  idx" fields..  <
1ae60 74 72 3e 3c 74 64 3e 69 64 78 20 20 20 20 20 20  tr><td>idx      
1ae70 20 20 20 20 20 20 20 20 3c 74 64 3e 20 53 65 65          <td> See
1ae80 20 61 62 6f 76 65 2e 0a 20 20 3c 74 72 3e 3c 74   above..  <tr><t
1ae90 64 3e 73 74 61 72 74 5f 62 6c 6f 63 6b 20 20 20  d>start_block   
1aea0 20 20 20 3c 74 64 3e 0a 20 20 20 20 54 68 65 20     <td>.    The 
1aeb0 62 6c 6f 63 6b 69 64 20 74 68 61 74 20 63 6f 72  blockid that cor
1aec0 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20  responds to the 
1aed0 6e 6f 64 65 20 77 69 74 68 20 74 68 65 20 73 6d  node with the sm
1aee0 61 6c 6c 65 73 74 20 62 6c 6f 63 6b 69 64 20 74  allest blockid t
1aef0 68 61 74 20 0a 20 20 20 20 62 65 6c 6f 6e 67 73  hat .    belongs
1af00 20 74 6f 20 74 68 69 73 20 73 65 67 6d 65 6e 74   to this segment
1af10 20 62 2d 74 72 65 65 2e 20 4f 72 20 7a 65 72 6f   b-tree. Or zero
1af20 20 69 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   if the entire s
1af30 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 0a 20 20  egment b-tree.  
1af40 20 20 66 69 74 73 20 6f 6e 20 74 68 65 20 72 6f    fits on the ro
1af50 6f 74 20 6e 6f 64 65 2e 20 49 66 20 69 74 20 65  ot node. If it e
1af60 78 69 73 74 73 2c 20 74 68 69 73 20 6e 6f 64 65  xists, this node
1af70 20 69 73 20 61 6c 77 61 79 73 20 61 20 6c 65 61   is always a lea
1af80 66 20 6e 6f 64 65 2e 0a 20 20 3c 74 72 3e 3c 74  f node..  <tr><t
1af90 64 3e 6c 65 61 76 65 73 5f 65 6e 64 5f 62 6c 6f  d>leaves_end_blo
1afa0 63 6b 20 3c 74 64 3e 0a 20 20 20 20 54 68 65 20  ck <td>.    The 
1afb0 62 6c 6f 63 6b 69 64 20 74 68 61 74 20 63 6f 72  blockid that cor
1afc0 72 65 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20  responds to the 
1afd0 6c 65 61 66 20 6e 6f 64 65 20 77 69 74 68 20 74  leaf node with t
1afe0 68 65 20 6c 61 72 67 65 73 74 20 62 6c 6f 63 6b  he largest block
1aff0 69 64 20 0a 20 20 20 20 74 68 61 74 20 62 65 6c  id .    that bel
1b000 6f 6e 67 73 20 74 6f 20 74 68 69 73 20 73 65 67  ongs to this seg
1b010 6d 65 6e 74 20 62 2d 74 72 65 65 2e 20 4f 72 20  ment b-tree. Or 
1b020 7a 65 72 6f 20 69 66 20 74 68 65 20 65 6e 74 69  zero if the enti
1b030 72 65 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65  re segment b-tre
1b040 65 0a 20 20 20 20 66 69 74 73 20 6f 6e 20 74 68  e.    fits on th
1b050 65 20 72 6f 6f 74 20 6e 6f 64 65 2e 0a 20 20 3c  e root node..  <
1b060 74 72 3e 3c 74 64 3e 65 6e 64 5f 62 6c 6f 63 6b  tr><td>end_block
1b070 20 3c 74 64 3e 0a 20 20 20 20 54 68 65 20 62 6c   <td>.    The bl
1b080 6f 63 6b 69 64 20 74 68 61 74 20 63 6f 72 72 65  ockid that corre
1b090 73 70 6f 6e 64 73 20 74 6f 20 74 68 65 20 69 6e  sponds to the in
1b0a0 74 65 72 69 6f 72 20 6e 6f 64 65 20 77 69 74 68  terior node with
1b0b0 20 74 68 65 20 6c 61 72 67 65 73 74 20 0a 20 20   the largest .  
1b0c0 20 20 62 6c 6f 63 6b 69 64 20 74 68 61 74 20 62    blockid that b
1b0d0 65 6c 6f 6e 67 73 20 74 6f 20 74 68 69 73 20 73  elongs to this s
1b0e0 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 2e 20 20  egment b-tree.  
1b0f0 4f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 20 65  Or zero if the e
1b100 6e 74 69 72 65 20 73 65 67 6d 65 6e 74 0a 20 20  ntire segment.  
1b110 20 20 62 2d 74 72 65 65 20 66 69 74 73 20 6f 6e    b-tree fits on
1b120 20 74 68 65 20 72 6f 6f 74 20 6e 6f 64 65 2e 20   the root node. 
1b130 49 66 20 69 74 20 65 78 69 73 74 73 2c 20 74 68  If it exists, th
1b140 69 73 20 6e 6f 64 65 20 69 73 20 61 6c 77 61 79  is node is alway
1b150 73 20 61 6e 0a 20 20 20 20 69 6e 74 65 72 69 6f  s an.    interio
1b160 72 20 6e 6f 64 65 2e 0a 20 20 3c 74 72 3e 3c 74  r node..  <tr><t
1b170 64 3e 72 6f 6f 74 20 20 20 20 20 20 20 20 20 20  d>root          
1b180 20 20 20 3c 74 64 3e 0a 20 20 20 20 42 6c 6f 62     <td>.    Blob
1b190 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
1b1a0 72 6f 6f 74 20 6e 6f 64 65 20 6f 66 20 74 68 65  root node of the
1b1b0 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 2e   segment b-tree.
1b1c0 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 0a 20  .</table>..<p>. 
1b1d0 20 41 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   Apart from the 
1b1e0 72 6f 6f 74 20 6e 6f 64 65 2c 20 74 68 65 20 6e  root node, the n
1b1f0 6f 64 65 73 20 74 68 61 74 20 6d 61 6b 65 20 75  odes that make u
1b200 70 20 61 20 73 69 6e 67 6c 65 20 73 65 67 6d 65  p a single segme
1b210 6e 74 20 62 2d 74 72 65 65 20 61 72 65 0a 20 20  nt b-tree are.  
1b220 61 6c 77 61 79 73 20 73 74 6f 72 65 64 20 75 73  always stored us
1b230 69 6e 67 20 61 20 63 6f 6e 74 69 67 75 6f 75 73  ing a contiguous
1b240 20 73 65 71 75 65 6e 63 65 20 6f 66 20 62 6c 6f   sequence of blo
1b250 63 6b 69 64 73 2e 20 46 75 72 74 68 65 72 6d 6f  ckids. Furthermo
1b260 72 65 2c 20 74 68 65 0a 20 20 6e 6f 64 65 73 20  re, the.  nodes 
1b270 74 68 61 74 20 6d 61 6b 65 20 75 70 20 61 20 73  that make up a s
1b280 69 6e 67 6c 65 20 6c 65 76 65 6c 20 6f 66 20 74  ingle level of t
1b290 68 65 20 62 2d 74 72 65 65 20 61 72 65 20 74 68  he b-tree are th
1b2a0 65 6d 73 65 6c 76 65 73 20 73 74 6f 72 65 64 20  emselves stored 
1b2b0 61 73 0a 20 20 61 20 63 6f 6e 74 69 67 75 6f 75  as.  a contiguou
1b2c0 73 20 62 6c 6f 63 6b 2c 20 69 6e 20 62 2d 74 72  s block, in b-tr
1b2d0 65 65 20 6f 72 64 65 72 2e 20 54 68 65 20 63 6f  ee order. The co
1b2e0 6e 74 69 67 75 6f 75 73 20 73 65 71 75 65 6e 63  ntiguous sequenc
1b2f0 65 20 6f 66 20 62 6c 6f 63 6b 69 64 73 0a 20 20  e of blockids.  
1b300 75 73 65 64 20 74 6f 20 73 74 6f 72 65 20 74 68  used to store th
1b310 65 20 62 2d 74 72 65 65 20 6c 65 61 76 65 73 20  e b-tree leaves 
1b320 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 74  are allocated st
1b330 61 72 74 69 6e 67 20 77 69 74 68 20 74 68 65 20  arting with the 
1b340 62 6c 6f 63 6b 69 64 0a 20 20 76 61 6c 75 65 20  blockid.  value 
1b350 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 22 73  stored in the "s
1b360 74 61 72 74 5f 62 6c 6f 63 6b 22 20 63 6f 6c 75  tart_block" colu
1b370 6d 6e 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  mn of the corres
1b380 70 6f 6e 64 69 6e 67 20 25 5f 73 65 67 64 69 72  ponding %_segdir
1b390 20 72 6f 77 2c 0a 20 20 61 6e 64 20 66 69 6e 69   row,.  and fini
1b3a0 73 68 69 6e 67 20 61 74 20 74 68 65 20 62 6c 6f  shing at the blo
1b3b0 63 6b 69 64 20 76 61 6c 75 65 20 73 74 6f 72 65  ckid value store
1b3c0 64 20 69 6e 20 74 68 65 20 22 6c 65 61 76 65 73  d in the "leaves
1b3d0 5f 65 6e 64 5f 62 6c 6f 63 6b 22 0a 20 20 66 69  _end_block".  fi
1b3e0 65 6c 64 20 6f 66 20 74 68 65 20 73 61 6d 65 20  eld of the same 
1b3f0 72 6f 77 2e 20 49 74 20 69 73 20 74 68 65 72 65  row. It is there
1b400 66 6f 72 65 20 70 6f 73 73 69 62 6c 65 20 74 6f  fore possible to
1b410 20 69 74 65 72 61 74 65 20 74 68 72 6f 75 67 68   iterate through
1b420 20 61 6c 6c 20 74 68 65 0a 20 20 6c 65 61 76 65   all the.  leave
1b430 73 20 6f 66 20 61 20 73 65 67 6d 65 6e 74 20 62  s of a segment b
1b440 2d 74 72 65 65 2c 20 69 6e 20 6b 65 79 20 6f 72  -tree, in key or
1b450 64 65 72 2c 20 62 79 20 74 72 61 76 65 72 73 69  der, by traversi
1b460 6e 67 20 74 68 65 20 25 5f 73 65 67 6d 65 6e 74  ng the %_segment
1b470 73 20 0a 20 20 74 61 62 6c 65 20 69 6e 20 62 6c  s .  table in bl
1b480 6f 63 6b 69 64 20 6f 72 64 65 72 20 66 72 6f 6d  ockid order from
1b490 20 22 73 74 61 72 74 5f 62 6c 6f 63 6b 22 20 74   "start_block" t
1b4a0 6f 20 22 6c 65 61 76 65 73 5f 65 6e 64 5f 62 6c  o "leaves_end_bl
1b4b0 6f 63 6b 22 2e 20 20 0a 0a 3c 68 33 3e 53 65 67  ock".  ..<h3>Seg
1b4c0 6d 65 6e 74 20 42 2d 54 72 65 65 20 4c 65 61 66  ment B-Tree Leaf
1b4d0 20 4e 6f 64 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e   Nodes</h3>..<p>
1b4e0 0a 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
1b4f0 20 64 69 61 67 72 61 6d 20 64 65 70 69 63 74 73   diagram depicts
1b500 20 74 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 61   the format of a
1b510 20 73 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 20   segment b-tree 
1b520 6c 65 61 66 20 6e 6f 64 65 2e 0a 0a 3c 63 65 6e  leaf node...<cen
1b530 74 65 72 3e 0a 20 20 3c 69 6d 67 20 73 72 63 3d  ter>.  <img src=
1b540 69 6d 61 67 65 73 2f 66 74 73 33 5f 6c 65 61 66  images/fts3_leaf
1b550 5f 6e 6f 64 65 2e 70 6e 67 3e 0a 20 20 3c 70 3e  _node.png>.  <p>
1b560 20 53 65 67 6d 65 6e 74 20 42 2d 54 72 65 65 20   Segment B-Tree 
1b570 4c 65 61 66 20 4e 6f 64 65 20 46 6f 72 6d 61 74  Leaf Node Format
1b580 0a 3c 2f 63 65 6e 74 65 72 3e 0a 0a 3c 70 3e 0a  .</center>..<p>.
1b590 20 20 54 68 65 20 66 69 72 73 74 20 74 65 72 6d    The first term
1b5a0 20 73 74 6f 72 65 64 20 6f 6e 20 65 61 63 68 20   stored on each 
1b5b0 6e 6f 64 65 20 28 22 54 65 72 6d 20 31 22 20 69  node ("Term 1" i
1b5c0 6e 20 74 68 65 20 66 69 67 75 72 65 20 61 62 6f  n the figure abo
1b5d0 76 65 29 20 69 73 0a 20 20 73 74 6f 72 65 64 20  ve) is.  stored 
1b5e0 76 65 72 62 61 74 69 6d 2e 20 45 61 63 68 20 73  verbatim. Each s
1b5f0 75 62 73 65 71 75 65 6e 74 20 74 65 72 6d 20 69  ubsequent term i
1b600 73 20 70 72 65 66 69 78 2d 63 6f 6d 70 72 65 73  s prefix-compres
1b610 73 65 64 20 77 69 74 68 20 72 65 73 70 65 63 74  sed with respect
1b620 0a 20 20 74 6f 20 69 74 73 20 70 72 65 64 65 63  .  to its predec
1b630 65 73 73 6f 72 2e 20 54 65 72 6d 73 20 61 72 65  essor. Terms are
1b640 20 73 74 6f 72 65 64 20 77 69 74 68 69 6e 20 61   stored within a
1b650 20 70 61 67 65 20 69 6e 20 73 6f 72 74 65 64 20   page in sorted 
1b660 28 6d 65 6d 63 6d 70 29 0a 20 20 6f 72 64 65 72  (memcmp).  order
1b670 2e 0a 0a 3c 68 33 3e 53 65 67 6d 65 6e 74 20 42  ...<h3>Segment B
1b680 2d 54 72 65 65 20 49 6e 74 65 72 69 6f 72 20 4e  -Tree Interior N
1b690 6f 64 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a 20  odes</h3>..<p>. 
1b6a0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   The following d
1b6b0 69 61 67 72 61 6d 20 64 65 70 69 63 74 73 20 74  iagram depicts t
1b6c0 68 65 20 66 6f 72 6d 61 74 20 6f 66 20 61 20 73  he format of a s
1b6d0 65 67 6d 65 6e 74 20 62 2d 74 72 65 65 20 69 6e  egment b-tree in
1b6e0 74 65 72 69 6f 72 20 0a 20 20 28 6e 6f 6e 2d 6c  terior .  (non-l
1b6f0 65 61 66 29 20 6e 6f 64 65 2e 0a 0a 3c 63 65 6e  eaf) node...<cen
1b700 74 65 72 3e 0a 20 20 3c 69 6d 67 20 73 72 63 3d  ter>.  <img src=
1b710 69 6d 61 67 65 73 2f 66 74 73 33 5f 69 6e 74 65  images/fts3_inte
1b720 72 69 6f 72 5f 6e 6f 64 65 2e 70 6e 67 3e 0a 20  rior_node.png>. 
1b730 20 3c 70 3e 20 53 65 67 6d 65 6e 74 20 42 2d 54   <p> Segment B-T
1b740 72 65 65 20 49 6e 74 65 72 69 6f 72 20 4e 6f 64  ree Interior Nod
1b750 65 20 46 6f 72 6d 61 74 0a 3c 2f 63 65 6e 74 65  e Format.</cente
1b760 72 3e 0a 0a 0a 3c 68 32 3e 44 6f 63 6c 69 73 74  r>...<h2>Doclist
1b770 20 46 6f 72 6d 61 74 3c 2f 68 32 3e 0a 0a 3c 70   Format</h2>..<p
1b780 3e 0a 20 20 41 20 64 6f 63 6c 69 73 74 20 63 6f  >.  A doclist co
1b790 6e 73 69 73 74 73 20 6f 66 20 61 6e 20 61 72 72  nsists of an arr
1b7a0 61 79 20 6f 66 20 36 34 2d 62 69 74 20 73 69 67  ay of 64-bit sig
1b7b0 6e 65 64 20 69 6e 74 65 67 65 72 73 2c 20 73 65  ned integers, se
1b7c0 72 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 0a 20  rialized using. 
1b7d0 20 74 68 65 20 46 54 53 20 76 61 72 69 6e 74 20   the FTS varint 
1b7e0 66 6f 72 6d 61 74 2e 20 45 61 63 68 20 64 6f 63  format. Each doc
1b7f0 6c 69 73 74 20 65 6e 74 72 79 20 69 73 20 6d 61  list entry is ma
1b800 64 65 20 75 70 20 6f 66 20 61 20 73 65 72 69 65  de up of a serie
1b810 73 20 6f 66 20 74 77 6f 20 0a 20 20 6f 72 20 6d  s of two .  or m
1b820 6f 72 65 20 69 6e 74 65 67 65 72 73 2c 20 61 73  ore integers, as
1b830 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a   follows:..<ol>.
1b840 20 20 3c 6c 69 3e 20 54 68 65 20 64 6f 63 69 64    <li> The docid
1b850 20 76 61 6c 75 65 2e 20 54 68 65 20 66 69 72 73   value. The firs
1b860 74 20 65 6e 74 72 79 20 69 6e 20 61 20 64 6f 63  t entry in a doc
1b870 6c 69 73 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  list contains th
1b880 65 20 6c 69 74 65 72 61 6c 20 64 6f 63 69 64 0a  e literal docid.
1b890 20 20 20 20 20 20 20 76 61 6c 75 65 2e 20 54 68         value. Th
1b8a0 65 20 66 69 72 73 74 20 66 69 65 6c 64 20 6f 66  e first field of
1b8b0 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
1b8c0 20 64 6f 63 6c 69 73 74 20 65 6e 74 72 79 20 63   doclist entry c
1b8d0 6f 6e 74 61 69 6e 73 20 74 68 65 20 0a 20 20 20  ontains the .   
1b8e0 20 20 20 20 64 69 66 66 65 72 65 6e 63 65 20 62      difference b
1b8f0 65 74 77 65 65 6e 20 74 68 65 20 6e 65 77 20 64  etween the new d
1b900 6f 63 69 64 20 61 6e 64 20 74 68 65 20 70 72 65  ocid and the pre
1b910 76 69 6f 75 73 20 6f 6e 65 20 28 61 6c 77 61 79  vious one (alway
1b920 73 20 61 20 70 6f 73 69 74 69 76 65 20 0a 20 20  s a positive .  
1b930 20 20 20 20 20 6e 75 6d 62 65 72 29 2e 0a 20 20       number)..  
1b940 3c 6c 69 3e 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  <li> Zero or mor
1b950 65 20 74 65 72 6d 2d 6f 66 66 73 65 74 20 6c 69  e term-offset li
1b960 73 74 73 2e 20 41 20 74 65 72 6d 2d 6f 66 66 73  sts. A term-offs
1b970 65 74 20 6c 69 73 74 20 69 73 20 70 72 65 73 65  et list is prese
1b980 6e 74 20 66 6f 72 20 65 61 63 68 0a 20 20 20 20  nt for each.    
1b990 20 20 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65     column of the
1b9a0 20 46 54 53 20 76 69 72 74 75 61 6c 20 74 61 62   FTS virtual tab
1b9b0 6c 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  le that contains
1b9c0 20 74 68 65 20 74 65 72 6d 2e 20 41 20 74 65 72   the term. A ter
1b9d0 6d 2d 6f 66 66 73 65 74 0a 20 20 20 20 20 20 20  m-offset.       
1b9e0 6c 69 73 74 20 63 6f 6e 73 69 73 74 73 20 6f 66  list consists of
1b9f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
1ba00 20 20 20 20 20 3c 6f 6c 3e 0a 20 20 20 20 20 20       <ol>.      
1ba10 20 3c 6c 69 3e 20 43 6f 6e 73 74 61 6e 74 20 76   <li> Constant v
1ba20 61 6c 75 65 20 31 2e 20 54 68 69 73 20 66 69 65  alue 1. This fie
1ba30 6c 64 20 69 73 20 6f 6d 69 74 74 65 64 20 66 6f  ld is omitted fo
1ba40 72 20 61 6e 79 20 74 65 72 6d 2d 6f 66 66 73 65  r any term-offse
1ba50 74 20 6c 69 73 74 0a 20 20 20 20 20 20 20 20 20  t list.         
1ba60 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69     associated wi
1ba70 74 68 20 63 6f 6c 75 6d 6e 20 30 2e 0a 20 20 20  th column 0..   
1ba80 20 20 20 20 3c 6c 69 3e 20 54 68 65 20 63 6f 6c      <li> The col
1ba90 75 6d 6e 20 6e 75 6d 62 65 72 20 28 31 20 66 6f  umn number (1 fo
1baa0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 6c 65 66  r the second lef
1bab0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 2c 20 65 74  tmost column, et
1bac0 63 2e 29 2e 20 54 68 69 73 0a 20 20 20 20 20 20  c.). This.      
1bad0 20 20 20 20 20 20 66 69 65 6c 64 20 69 73 20 6f        field is o
1bae0 6d 69 74 74 65 64 20 66 6f 72 20 61 6e 79 20 74  mitted for any t
1baf0 65 72 6d 2d 6f 66 66 73 65 74 20 6c 69 73 74 20  erm-offset list 
1bb00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1bb10 63 6f 6c 75 6d 6e 20 30 2e 0a 20 20 20 20 20 20  column 0..      
1bb20 20 3c 6c 69 3e 20 41 20 6c 69 73 74 20 6f 66 20   <li> A list of 
1bb30 74 65 72 6d 2d 6f 66 66 73 65 74 73 2c 20 73 6f  term-offsets, so
1bb40 72 74 65 64 20 66 72 6f 6d 20 73 6d 61 6c 6c 65  rted from smalle
1bb50 73 74 20 74 6f 20 6c 61 72 67 65 73 74 2e 20 49  st to largest. I
1bb60 6e 73 74 65 61 64 0a 20 20 20 20 20 20 20 20 20  nstead.         
1bb70 20 20 20 6f 66 20 73 74 6f 72 69 6e 67 20 74 68     of storing th
1bb80 65 20 74 65 72 6d 2d 6f 66 66 73 65 74 20 76 61  e term-offset va
1bb90 6c 75 65 20 6c 69 74 65 72 61 6c 6c 79 2c 20 65  lue literally, e
1bba0 61 63 68 20 69 6e 74 65 67 65 72 20 73 74 6f 72  ach integer stor
1bbb0 65 64 20 0a 20 20 20 20 20 20 20 20 20 20 20 20  ed .            
1bbc0 69 73 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  is the differenc
1bbd0 65 20 62 65 74 77 65 65 6e 20 74 68 65 20 63 75  e between the cu
1bbe0 72 72 65 6e 74 20 74 65 72 6d 2d 6f 66 66 73 65  rrent term-offse
1bbf0 74 20 61 6e 64 20 74 68 65 20 70 72 65 76 69 6f  t and the previo
1bc00 75 73 20 0a 20 20 20 20 20 20 20 20 20 20 20 20  us .            
1bc10 6f 6e 65 20 28 6f 72 20 7a 65 72 6f 20 69 66 20  one (or zero if 
1bc20 74 68 65 20 63 75 72 72 65 6e 74 20 74 65 72 6d  the current term
1bc30 2d 6f 66 66 73 65 74 20 69 73 20 74 68 65 20 66  -offset is the f
1bc40 69 72 73 74 29 2c 20 70 6c 75 73 20 32 2e 0a 20  irst), plus 2.. 
1bc50 20 20 20 20 3c 2f 6f 6c 3e 0a 20 20 3c 6c 69 3e      </ol>.  <li>
1bc60 20 43 6f 6e 73 74 61 6e 74 20 76 61 6c 75 65 20   Constant value 
1bc70 30 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 63 65 6e 74 65  0..</ol>..<cente
1bc80 72 3e 0a 20 20 3c 69 6d 67 20 73 72 63 3d 69 6d  r>.  <img src=im
1bc90 61 67 65 73 2f 66 74 73 33 5f 64 6f 63 6c 69 73  ages/fts3_doclis
1bca0 74 32 2e 70 6e 67 3e 0a 20 20 3c 70 3e 20 46 54  t2.png>.  <p> FT
1bcb0 53 33 20 44 6f 63 6c 69 73 74 20 46 6f 72 6d 61  S3 Doclist Forma
1bcc0 74 0a 3c 2f 63 65 6e 74 65 72 3e 0a 0a 3c 63 65  t.</center>..<ce
1bcd0 6e 74 65 72 3e 0a 20 20 3c 69 6d 67 20 73 72 63  nter>.  <img src
1bce0 3d 69 6d 61 67 65 73 2f 66 74 73 33 5f 64 6f 63  =images/fts3_doc
1bcf0 6c 69 73 74 2e 70 6e 67 3e 0a 20 20 3c 70 3e 20  list.png>.  <p> 
1bd00 46 54 53 20 44 6f 63 6c 69 73 74 20 45 6e 74 72  FTS Doclist Entr
1bd10 79 20 46 6f 72 6d 61 74 0a 3c 2f 63 65 6e 74 65  y Format.</cente
1bd20 72 3e 0a 0a 3c 70 3e 0a 20 20 46 6f 72 20 64 6f  r>..<p>.  For do
1bd30 63 6c 69 73 74 73 20 66 6f 72 20 77 68 69 63 68  clists for which
1bd40 20 74 68 65 20 74 65 72 6d 20 61 70 70 65 61 72   the term appear
1bd50 73 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  s in more than o
1bd60 6e 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  ne column of the
1bd70 20 46 54 53 0a 20 20 76 69 72 74 75 61 6c 20 74   FTS.  virtual t
1bd80 61 62 6c 65 2c 20 74 65 72 6d 2d 6f 66 66 73 65  able, term-offse
1bd90 74 20 6c 69 73 74 73 20 77 69 74 68 69 6e 20 74  t lists within t
1bda0 68 65 20 64 6f 63 6c 69 73 74 20 61 72 65 20 73  he doclist are s
1bdb0 74 6f 72 65 64 20 69 6e 20 63 6f 6c 75 6d 6e 20  tored in column 
1bdc0 0a 20 20 6e 75 6d 62 65 72 20 6f 72 64 65 72 2e  .  number order.
1bdd0 20 54 68 69 73 20 65 6e 73 75 72 65 73 20 74 68   This ensures th
1bde0 61 74 20 74 68 65 20 74 65 72 6d 2d 6f 66 66 73  at the term-offs
1bdf0 65 74 20 6c 69 73 74 20 61 73 73 6f 63 69 61 74  et list associat
1be00 65 64 20 77 69 74 68 20 0a 20 20 63 6f 6c 75 6d  ed with .  colum
1be10 6e 20 30 20 28 69 66 20 61 6e 79 29 20 69 73 20  n 0 (if any) is 
1be20 61 6c 77 61 79 73 20 66 69 72 73 74 2c 20 61 6c  always first, al
1be30 6c 6f 77 69 6e 67 20 74 68 65 20 66 69 72 73 74  lowing the first
1be40 20 74 77 6f 20 66 69 65 6c 64 73 20 6f 66 20 74   two fields of t
1be50 68 65 0a 20 20 74 65 72 6d 2d 6f 66 66 73 65 74  he.  term-offset
1be60 20 6c 69 73 74 20 74 6f 20 62 65 20 6f 6d 69 74   list to be omit
1be70 74 65 64 20 69 6e 20 74 68 69 73 20 63 61 73 65  ted in this case
1be80 2e 0a 0a 3c 68 31 20 69 64 3d 61 70 70 65 6e 64  ...<h1 id=append
1be90 69 78 5f 61 20 6e 6f 6e 75 6d 62 65 72 20 74 61  ix_a nonumber ta
1bea0 67 73 3d 22 73 65 61 72 63 68 20 61 70 70 6c 69  gs="search appli
1beb0 63 61 74 69 6f 6e 20 74 69 70 73 22 3e 0a 20 20  cation tips">.  
1bec0 41 70 70 65 6e 64 69 78 20 41 3a 20 53 65 61 72  Appendix A: Sear
1bed0 63 68 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 54  ch Application T
1bee0 69 70 73 0a 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 20  ips.</h1>..<p>. 
1bef0 20 46 54 53 20 69 73 20 70 72 69 6d 61 72 69 6c   FTS is primaril
1bf00 79 20 64 65 73 69 67 6e 65 64 20 74 6f 20 73 75  y designed to su
1bf10 70 70 6f 72 74 20 42 6f 6f 6c 65 61 6e 20 66 75  pport Boolean fu
1bf20 6c 6c 2d 74 65 78 74 20 71 75 65 72 69 65 73 20  ll-text queries 
1bf30 2d 20 71 75 65 72 69 65 73 0a 20 20 74 6f 20 66  - queries.  to f
1bf40 69 6e 64 20 74 68 65 20 73 65 74 20 6f 66 20 64  ind the set of d
1bf50 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 6d 61  ocuments that ma
1bf60 74 63 68 20 61 20 73 70 65 63 69 66 69 65 64 20  tch a specified 
1bf70 63 72 69 74 65 72 69 61 2e 20 48 6f 77 65 76 65  criteria. Howeve
1bf80 72 2c 20 6d 61 6e 79 20 0a 20 20 28 6d 6f 73 74  r, many .  (most
1bf90 3f 29 20 73 65 61 72 63 68 20 61 70 70 6c 69 63  ?) search applic
1bfa0 61 74 69 6f 6e 73 20 72 65 71 75 69 72 65 20 74  ations require t
1bfb0 68 61 74 20 72 65 73 75 6c 74 73 20 61 72 65 20  hat results are 
1bfc0 73 6f 6d 65 68 6f 77 20 72 61 6e 6b 65 64 20 69  somehow ranked i
1bfd0 6e 20 6f 72 64 65 72 0a 20 20 6f 66 20 22 72 65  n order.  of "re
1bfe0 6c 65 76 61 6e 63 65 22 2c 20 77 68 65 72 65 20  levance", where 
1bff0 22 72 65 6c 65 76 61 6e 63 65 22 20 69 73 20 64  "relevance" is d
1c000 65 66 69 6e 65 64 20 61 73 20 74 68 65 20 6c 69  efined as the li
1c010 6b 65 6c 69 68 6f 6f 64 20 74 68 61 74 20 74 68  kelihood that th
1c020 65 20 75 73 65 72 0a 20 20 77 68 6f 20 70 65 72  e user.  who per
1c030 66 6f 72 6d 65 64 20 74 68 65 20 73 65 61 72 63  formed the searc
1c040 68 20 69 73 20 69 6e 74 65 72 65 73 74 65 64 20  h is interested 
1c050 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 65 6c  in a specific el
1c060 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 72 65 74  ement of the ret
1c070 75 72 6e 65 64 0a 20 20 73 65 74 20 6f 66 20 64  urned.  set of d
1c080 6f 63 75 6d 65 6e 74 73 2e 20 57 68 65 6e 20 75  ocuments. When u
1c090 73 69 6e 67 20 61 20 73 65 61 72 63 68 20 65 6e  sing a search en
1c0a0 67 69 6e 65 20 74 6f 20 66 69 6e 64 20 64 6f 63  gine to find doc
1c0b0 75 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 77 6f  uments on the wo
1c0c0 72 6c 64 0a 20 20 77 69 64 65 20 77 65 62 2c 20  rld.  wide web, 
1c0d0 74 68 65 20 75 73 65 72 20 65 78 70 65 63 74 73  the user expects
1c0e0 20 74 68 61 74 20 74 68 65 20 6d 6f 73 74 20 75   that the most u
1c0f0 73 65 66 75 6c 2c 20 6f 72 20 22 72 65 6c 65 76  seful, or "relev
1c100 61 6e 74 22 2c 20 64 6f 63 75 6d 65 6e 74 73 20  ant", documents 
1c110 0a 20 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  .  will be retur
1c120 6e 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ned as the first
1c130 20 70 61 67 65 20 6f 66 20 72 65 73 75 6c 74 73   page of results
1c140 2c 20 61 6e 64 20 74 68 61 74 20 65 61 63 68 20  , and that each 
1c150 73 75 62 73 65 71 75 65 6e 74 20 70 61 67 65 20  subsequent page 
1c160 0a 20 20 63 6f 6e 74 61 69 6e 73 20 70 72 6f 67  .  contains prog
1c170 72 65 73 73 69 76 65 6c 79 20 6c 65 73 73 20 72  ressively less r
1c180 65 6c 65 76 61 6e 74 20 72 65 73 75 6c 74 73 2e  elevant results.
1c190 20 45 78 61 63 74 6c 79 20 68 6f 77 20 61 20 6d   Exactly how a m
1c1a0 61 63 68 69 6e 65 20 63 61 6e 20 0a 20 20 64 65  achine can .  de
1c1b0 74 65 72 6d 69 6e 65 20 64 6f 63 75 6d 65 6e 74  termine document
1c1c0 20 72 65 6c 65 76 61 6e 63 65 20 62 61 73 65 64   relevance based
1c1d0 20 6f 6e 20 61 20 75 73 65 72 73 20 71 75 65 72   on a users quer
1c1e0 79 20 69 73 20 61 20 63 6f 6d 70 6c 69 63 61 74  y is a complicat
1c1f0 65 64 20 70 72 6f 62 6c 65 6d 0a 20 20 61 6e 64  ed problem.  and
1c200 20 74 68 65 20 73 75 62 6a 65 63 74 20 6f 66 20   the subject of 
1c210 6d 75 63 68 20 6f 6e 67 6f 69 6e 67 20 72 65 73  much ongoing res
1c220 65 61 72 63 68 2e 0a 0a 3c 70 3e 0a 20 20 4f 6e  earch...<p>.  On
1c230 65 20 76 65 72 79 20 73 69 6d 70 6c 65 20 73 63  e very simple sc
1c240 68 65 6d 65 20 6d 69 67 68 74 20 62 65 20 74 6f  heme might be to
1c250 20 63 6f 75 6e 74 20 74 68 65 20 6e 75 6d 62 65   count the numbe
1c260 72 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20 6f  r of instances o
1c270 66 20 74 68 65 20 0a 20 20 75 73 65 72 73 20 73  f the .  users s
1c280 65 61 72 63 68 20 74 65 72 6d 73 20 69 6e 20 65  earch terms in e
1c290 61 63 68 20 72 65 73 75 6c 74 20 64 6f 63 75 6d  ach result docum
1c2a0 65 6e 74 2e 20 54 68 6f 73 65 20 64 6f 63 75 6d  ent. Those docum
1c2b0 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ents that contai
1c2c0 6e 0a 20 20 6d 61 6e 79 20 69 6e 73 74 61 6e 63  n.  many instanc
1c2d0 65 73 20 6f 66 20 74 68 65 20 74 65 72 6d 73 20  es of the terms 
1c2e0 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 6d  are considered m
1c2f0 6f 72 65 20 72 65 6c 65 76 61 6e 74 20 74 68 61  ore relevant tha
1c300 6e 20 74 68 6f 73 65 20 77 69 74 68 0a 20 20 61  n those with.  a
1c310 20 73 6d 61 6c 6c 20 6e 75 6d 62 65 72 20 6f 66   small number of
1c320 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 65 61   instances of ea
1c330 63 68 20 74 65 72 6d 2e 20 49 6e 20 61 6e 20 46  ch term. In an F
1c340 54 53 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  TS application, 
1c350 74 68 65 20 0a 20 20 6e 75 6d 62 65 72 20 6f 66  the .  number of
1c360 20 74 65 72 6d 20 69 6e 73 74 61 6e 63 65 73 20   term instances 
1c370 69 6e 20 65 61 63 68 20 72 65 73 75 6c 74 20 63  in each result c
1c380 6f 75 6c 64 20 62 65 20 64 65 74 65 72 6d 69 6e  ould be determin
1c390 65 64 20 62 79 20 63 6f 75 6e 74 69 6e 67 0a 20  ed by counting. 
1c3a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 69   the number of i
1c3b0 6e 74 65 67 65 72 73 20 69 6e 20 74 68 65 20 72  ntegers in the r
1c3c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1c3d0 68 65 20 5b 6f 66 66 73 65 74 73 5d 20 66 75 6e  he [offsets] fun
1c3e0 63 74 69 6f 6e 2e 0a 20 20 54 68 65 20 66 6f 6c  ction..  The fol
1c3f0 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65 20 73  lowing example s
1c400 68 6f 77 73 20 61 20 71 75 65 72 79 20 74 68 61  hows a query tha
1c410 74 20 63 6f 75 6c 64 20 62 65 20 75 73 65 64 20  t could be used 
1c420 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 20 20  to obtain the.  
1c430 74 65 6e 20 6d 6f 73 74 20 72 65 6c 65 76 61 6e  ten most relevan
1c440 74 20 72 65 73 75 6c 74 73 20 66 6f 72 20 61 20  t results for a 
1c450 71 75 65 72 79 20 65 6e 74 65 72 65 64 20 62 79  query entered by
1c460 20 74 68 65 20 75 73 65 72 3a 0a 0a 3c 63 6f 64   the user:..<cod
1c470 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
1c480 54 68 69 73 20 65 78 61 6d 70 6c 65 20 28 61 6e  This example (an
1c490 64 20 61 6c 6c 20 6f 74 68 65 72 73 20 69 6e 20  d all others in 
1c4a0 74 68 69 73 20 73 65 63 74 69 6f 6e 29 20 61 73  this section) as
1c4b0 73 75 6d 65 73 20 74 68 65 20 66 6f 6c 6c 6f 77  sumes the follow
1c4c0 69 6e 67 20 73 63 68 65 6d 61 3c 2f 69 3e 0a 20  ing schema</i>. 
1c4d0 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
1c4e0 54 41 42 4c 45 20 64 6f 63 75 6d 65 6e 74 73 20  TABLE documents 
1c4f0 55 53 49 4e 47 20 66 74 73 33 28 74 69 74 6c 65  USING fts3(title
1c500 2c 20 63 6f 6e 74 65 6e 74 29 3b 0a 0a 20 20 3c  , content);..  <
1c510 69 3e 2d 2d 20 41 73 73 75 6d 69 6e 67 20 74 68  i>-- Assuming th
1c520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1c530 73 20 73 75 70 70 6c 69 65 64 20 61 6e 20 53 51  s supplied an SQ
1c540 4c 69 74 65 20 75 73 65 72 20 66 75 6e 63 74 69  Lite user functi
1c550 6f 6e 20 6e 61 6d 65 64 20 22 63 6f 75 6e 74 69  on named "counti
1c560 6e 74 65 67 65 72 73 22 3c 2f 69 3e 0a 20 20 3c  ntegers"</i>.  <
1c570 69 3e 2d 2d 20 74 68 61 74 20 72 65 74 75 72 6e  i>-- that return
1c580 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1c590 73 70 61 63 65 2d 73 65 70 61 72 61 74 65 64 20  space-separated 
1c5a0 69 6e 74 65 67 65 72 73 20 63 6f 6e 74 61 69 6e  integers contain
1c5b0 65 64 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61  ed in its only a
1c5c0 72 67 75 6d 65 6e 74 2c 3c 2f 69 3e 0a 20 20 3c  rgument,</i>.  <
1c5d0 69 3e 2d 2d 20 74 68 65 20 66 6f 6c 6c 6f 77 69  i>-- the followi
1c5e0 6e 67 20 71 75 65 72 79 20 63 6f 75 6c 64 20 62  ng query could b
1c5f0 65 20 75 73 65 64 20 74 6f 20 72 65 74 75 72 6e  e used to return
1c600 20 74 68 65 20 74 69 74 6c 65 73 20 6f 66 20 74   the titles of t
1c610 68 65 20 31 30 20 64 6f 63 75 6d 65 6e 74 73 20  he 10 documents 
1c620 74 68 61 74 20 63 6f 6e 74 61 69 6e 3c 2f 69 3e  that contain</i>
1c630 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20 67 72 65  .  <i>-- the gre
1c640 61 74 65 73 74 20 6e 75 6d 62 65 72 20 6f 66 20  atest number of 
1c650 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 65  instances of the
1c660 20 75 73 65 72 73 20 71 75 65 72 79 20 74 65 72   users query ter
1c670 6d 73 2e 20 48 6f 70 65 66 75 6c 6c 79 2c 20 74  ms. Hopefully, t
1c680 68 65 73 65 20 31 30 3c 2f 69 3e 0a 20 20 3c 69  hese 10</i>.  <i
1c690 3e 2d 2d 20 64 6f 63 75 6d 65 6e 74 73 20 77 69  >-- documents wi
1c6a0 6c 6c 20 62 65 20 74 68 6f 73 65 20 74 68 61 74  ll be those that
1c6b0 20 74 68 65 20 75 73 65 72 73 20 63 6f 6e 73 69   the users consi
1c6c0 64 65 72 73 20 6d 6f 72 65 20 6f 72 20 6c 65 73  ders more or les
1c6d0 73 20 74 68 65 20 6d 6f 73 74 20 22 72 65 6c 65  s the most "rele
1c6e0 76 61 6e 74 22 2e 3c 2f 69 3e 0a 20 20 53 45 4c  vant".</i>.  SEL
1c6f0 45 43 54 20 74 69 74 6c 65 20 46 52 4f 4d 20 64  ECT title FROM d
1c700 6f 63 75 6d 65 6e 74 73 20 0a 20 20 20 20 57 48  ocuments .    WH
1c710 45 52 45 20 64 6f 63 75 6d 65 6e 74 73 20 4d 41  ERE documents MA
1c720 54 43 48 20 26 6c 74 3b 71 75 65 72 79 26 67 74  TCH &lt;query&gt
1c730 3b 0a 20 20 20 20 4f 52 44 45 52 20 42 59 20 63  ;.    ORDER BY c
1c740 6f 75 6e 74 69 6e 74 65 67 65 72 73 28 6f 66 66  ountintegers(off
1c750 73 65 74 73 28 64 6f 63 75 6d 65 6e 74 73 29 29  sets(documents))
1c760 20 44 45 53 43 0a 20 20 20 20 4c 49 4d 49 54 20   DESC.    LIMIT 
1c770 31 30 20 4f 46 46 53 45 54 20 30 0a 3c 2f 63 6f  10 OFFSET 0.</co
1c780 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20  deblock>..<p>.  
1c790 54 68 65 20 71 75 65 72 79 20 61 62 6f 76 65 20  The query above 
1c7a0 63 6f 75 6c 64 20 62 65 20 6d 61 64 65 20 74 6f  could be made to
1c7b0 20 72 75 6e 20 66 61 73 74 65 72 20 62 79 20 75   run faster by u
1c7c0 73 69 6e 67 20 74 68 65 20 46 54 53 20 5b 6d 61  sing the FTS [ma
1c7d0 74 63 68 69 6e 66 6f 5d 0a 20 20 66 75 6e 63 74  tchinfo].  funct
1c7e0 69 6f 6e 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ion to determine
1c7f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 71   the number of q
1c800 75 65 72 79 20 74 65 72 6d 20 69 6e 73 74 61 6e  uery term instan
1c810 63 65 73 20 74 68 61 74 20 61 70 70 65 61 72 20  ces that appear 
1c820 69 6e 20 65 61 63 68 0a 20 20 72 65 73 75 6c 74  in each.  result
1c830 2e 20 54 68 65 20 6d 61 74 63 68 69 6e 66 6f 20  . The matchinfo 
1c840 66 75 6e 63 74 69 6f 6e 20 69 73 20 6d 75 63 68  function is much
1c850 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
1c860 74 68 61 6e 20 74 68 65 20 6f 66 66 73 65 74 73  than the offsets
1c870 20 0a 20 20 66 75 6e 63 74 69 6f 6e 2e 20 46 75   .  function. Fu
1c880 72 74 68 65 72 6d 6f 72 65 2c 20 74 68 65 20 6d  rthermore, the m
1c890 61 74 63 68 69 6e 66 6f 20 66 75 6e 63 74 69 6f  atchinfo functio
1c8a0 6e 20 70 72 6f 76 69 64 65 73 20 65 78 74 72 61  n provides extra
1c8b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 20 72   information.  r
1c8c0 65 67 61 72 64 69 6e 67 20 74 68 65 20 6f 76 65  egarding the ove
1c8d0 72 61 6c 6c 20 6e 75 6d 62 65 72 20 6f 66 20 6f  rall number of o
1c8e0 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 65 61  ccurrences of ea
1c8f0 63 68 20 71 75 65 72 79 20 74 65 72 6d 20 69 6e  ch query term in
1c900 20 74 68 65 20 65 6e 74 69 72 65 0a 20 20 64 6f   the entire.  do
1c910 63 75 6d 65 6e 74 20 73 65 74 20 28 6e 6f 74 20  cument set (not 
1c920 6a 75 73 74 20 74 68 65 20 63 75 72 72 65 6e 74  just the current
1c930 20 72 6f 77 29 20 61 6e 64 20 74 68 65 20 6e 75   row) and the nu
1c940 6d 62 65 72 20 6f 66 20 64 6f 63 75 6d 65 6e 74  mber of document
1c950 73 20 69 6e 20 77 68 69 63 68 20 0a 20 20 65 61  s in which .  ea
1c960 63 68 20 71 75 65 72 79 20 74 65 72 6d 20 61 70  ch query term ap
1c970 70 65 61 72 73 2e 20 54 68 69 73 20 6d 61 79 20  pears. This may 
1c980 62 65 20 75 73 65 64 20 28 66 6f 72 20 65 78 61  be used (for exa
1c990 6d 70 6c 65 29 20 74 6f 20 61 74 74 61 63 68 20  mple) to attach 
1c9a0 61 20 68 69 67 68 65 72 0a 20 20 77 65 69 67 68  a higher.  weigh
1c9b0 74 20 74 6f 20 6c 65 73 73 20 63 6f 6d 6d 6f 6e  t to less common
1c9c0 20 74 65 72 6d 73 20 77 68 69 63 68 20 6d 61 79   terms which may
1c9d0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 6f 76   increase the ov
1c9e0 65 72 61 6c 6c 20 63 6f 6d 70 75 74 65 64 20 72  erall computed r
1c9f0 65 6c 65 76 61 6e 63 79 20 0a 20 20 6f 66 20 74  elevancy .  of t
1ca00 68 6f 73 65 20 72 65 73 75 6c 74 73 20 74 68 65  hose results the
1ca10 20 75 73 65 72 20 63 6f 6e 73 69 64 65 72 73 20   user considers 
1ca20 6d 6f 72 65 20 69 6e 74 65 72 65 73 74 69 6e 67  more interesting
1ca30 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
1ca40 20 3c 69 3e 2d 2d 20 49 66 20 74 68 65 20 61 70   <i>-- If the ap
1ca50 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
1ca60 65 73 20 61 6e 20 53 51 4c 69 74 65 20 75 73 65  es an SQLite use
1ca70 72 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 65  r function calle
1ca80 64 20 22 72 61 6e 6b 22 20 74 68 61 74 3c 2f 69  d "rank" that</i
1ca90 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e 74 65 72 70  >.  <i>-- interp
1caa0 72 65 74 73 20 74 68 65 20 62 6c 6f 62 20 6f 66  rets the blob of
1cab0 20 64 61 74 61 20 72 65 74 75 72 6e 65 64 20 62   data returned b
1cac0 79 20 6d 61 74 63 68 69 6e 66 6f 20 61 6e 64 20  y matchinfo and 
1cad0 72 65 74 75 72 6e 73 20 61 20 6e 75 6d 65 72 69  returns a numeri
1cae0 63 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 72 65  c</i>.  <i>-- re
1caf0 6c 65 76 61 6e 63 79 20 62 61 73 65 64 20 6f 6e  levancy based on
1cb00 20 69 74 2c 20 74 68 65 6e 20 74 68 65 20 66 6f   it, then the fo
1cb10 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 6d 61 79 20  llowing SQL may 
1cb20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 75 72  be used to retur
1cb30 6e 20 74 68 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  n the</i>.  <i>-
1cb40 2d 20 74 69 74 6c 65 73 20 6f 66 20 74 68 65 20  - titles of the 
1cb50 31 30 20 6d 6f 73 74 20 72 65 6c 65 76 61 6e 74  10 most relevant
1cb60 20 64 6f 63 75 6d 65 6e 74 73 20 69 6e 20 74 68   documents in th
1cb70 65 20 64 61 74 61 73 65 74 20 66 6f 72 20 61 20  e dataset for a 
1cb80 75 73 65 72 73 20 71 75 65 72 79 2e 3c 2f 69 3e  users query.</i>
1cb90 0a 20 20 53 45 4c 45 43 54 20 74 69 74 6c 65 20  .  SELECT title 
1cba0 46 52 4f 4d 20 64 6f 63 75 6d 65 6e 74 73 20 0a  FROM documents .
1cbb0 20 20 20 20 57 48 45 52 45 20 64 6f 63 75 6d 65      WHERE docume
1cbc0 6e 74 73 20 4d 41 54 43 48 20 26 6c 74 3b 71 75  nts MATCH &lt;qu
1cbd0 65 72 79 26 67 74 3b 0a 20 20 20 20 4f 52 44 45  ery&gt;.    ORDE
1cbe0 52 20 42 59 20 72 61 6e 6b 28 6d 61 74 63 68 69  R BY rank(matchi
1cbf0 6e 66 6f 28 64 6f 63 75 6d 65 6e 74 73 29 29 20  nfo(documents)) 
1cc00 44 45 53 43 0a 20 20 20 20 4c 49 4d 49 54 20 31  DESC.    LIMIT 1
1cc10 30 20 4f 46 46 53 45 54 20 30 0a 3c 2f 63 6f 64  0 OFFSET 0.</cod
1cc20 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54  eblock>..<p>.  T
1cc30 68 65 20 53 51 4c 20 71 75 65 72 79 20 69 6e 20  he SQL query in 
1cc40 74 68 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76  the example abov
1cc50 65 20 75 73 65 73 20 6c 65 73 73 20 43 50 55 20  e uses less CPU 
1cc60 74 68 61 6e 20 74 68 65 20 66 69 72 73 74 20 65  than the first e
1cc70 78 61 6d 70 6c 65 0a 20 20 69 6e 20 74 68 69 73  xample.  in this
1cc80 20 73 65 63 74 69 6f 6e 2c 20 62 75 74 20 73 74   section, but st
1cc90 69 6c 6c 20 68 61 73 20 61 20 6e 6f 6e 2d 6f 62  ill has a non-ob
1cca0 76 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  vious performanc
1ccb0 65 20 70 72 6f 62 6c 65 6d 2e 20 53 51 4c 69 74  e problem. SQLit
1ccc0 65 0a 20 20 73 61 74 69 73 66 69 65 73 20 74 68  e.  satisfies th
1ccd0 69 73 20 71 75 65 72 79 20 62 79 20 72 65 74 72  is query by retr
1cce0 69 65 76 69 6e 67 20 74 68 65 20 76 61 6c 75 65  ieving the value
1ccf0 20 6f 66 20 74 68 65 20 22 74 69 74 6c 65 22 20   of the "title" 
1cd00 63 6f 6c 75 6d 6e 20 61 6e 64 0a 20 20 6d 61 74  column and.  mat
1cd10 63 68 69 6e 66 6f 20 64 61 74 61 20 66 72 6f 6d  chinfo data from
1cd20 20 74 68 65 20 46 54 53 20 6d 6f 64 75 6c 65 20   the FTS module 
1cd30 66 6f 72 20 65 76 65 72 79 20 72 6f 77 20 6d 61  for every row ma
1cd40 74 63 68 65 64 20 62 79 20 74 68 65 20 75 73 65  tched by the use
1cd50 72 73 0a 20 20 71 75 65 72 79 20 62 65 66 6f 72  rs.  query befor
1cd60 65 20 69 74 20 73 6f 72 74 73 20 61 6e 64 20 6c  e it sorts and l
1cd70 69 6d 69 74 73 20 74 68 65 20 72 65 73 75 6c 74  imits the result
1cd80 73 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  s. Because of th
1cd90 65 20 77 61 79 20 53 51 4c 69 74 65 27 73 0a 20  e way SQLite's. 
1cda0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1cdb0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 2c 20  nterface works, 
1cdc0 72 65 74 72 69 65 76 69 6e 67 20 74 68 65 20 76  retrieving the v
1cdd0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 74 69 74  alue of the "tit
1cde0 6c 65 22 20 63 6f 6c 75 6d 6e 0a 20 20 72 65 71  le" column.  req
1cdf0 75 69 72 65 73 20 6c 6f 61 64 69 6e 67 20 74 68  uires loading th
1ce00 65 20 65 6e 74 69 72 65 20 72 6f 77 20 66 72 6f  e entire row fro
1ce10 6d 20 64 69 73 6b 20 28 69 6e 63 6c 75 64 69 6e  m disk (includin
1ce20 67 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 22 20  g the "content" 
1ce30 66 69 65 6c 64 2c 0a 20 20 77 68 69 63 68 20 6d  field,.  which m
1ce40 61 79 20 62 65 20 71 75 69 74 65 20 6c 61 72 67  ay be quite larg
1ce50 65 29 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e). This means t
1ce60 68 61 74 20 69 66 20 74 68 65 20 75 73 65 72 73  hat if the users
1ce70 20 71 75 65 72 79 20 6d 61 74 63 68 65 73 0a 20   query matches. 
1ce80 20 73 65 76 65 72 61 6c 20 74 68 6f 75 73 61 6e   several thousan
1ce90 64 20 64 6f 63 75 6d 65 6e 74 73 2c 20 6d 61 6e  d documents, man
1cea0 79 20 6d 65 67 61 62 79 74 65 73 20 6f 66 20 22  y megabytes of "
1ceb0 74 69 74 6c 65 22 20 61 6e 64 20 22 63 6f 6e 74  title" and "cont
1cec0 65 6e 74 22 20 64 61 74 61 0a 20 20 6d 61 79 20  ent" data.  may 
1ced0 62 65 20 6c 6f 61 64 65 64 20 66 72 6f 6d 20 64  be loaded from d
1cee0 69 73 6b 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  isk into memory 
1cef0 65 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 79  even though they
1cf00 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 75   will never be u
1cf10 73 65 64 0a 20 20 66 6f 72 20 61 6e 79 20 70 75  sed.  for any pu
1cf20 72 70 6f 73 65 2e 20 0a 0a 3c 70 3e 0a 20 20 54  rpose. ..<p>.  T
1cf30 68 65 20 53 51 4c 20 71 75 65 72 79 20 69 6e 20  he SQL query in 
1cf40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78  the following ex
1cf50 61 6d 70 6c 65 20 62 6c 6f 63 6b 20 69 73 20 6f  ample block is o
1cf60 6e 65 20 73 6f 6c 75 74 69 6f 6e 20 74 6f 20 74  ne solution to t
1cf70 68 69 73 20 0a 20 20 70 72 6f 62 6c 65 6d 2e 20  his .  problem. 
1cf80 49 6e 20 53 51 4c 69 74 65 2c 20 77 68 65 6e 20  In SQLite, when 
1cf90 61 20 3c 61 20 68 72 65 66 3d 22 6f 70 74 6f 76  a <a href="optov
1cfa0 65 72 76 69 65 77 2e 68 74 6d 6c 23 66 6c 61 74  erview.html#flat
1cfb0 74 65 6e 69 6e 67 22 3e 73 75 62 2d 71 75 65 72  tening">sub-quer
1cfc0 79 20 0a 20 20 75 73 65 64 20 69 6e 20 61 20 6a  y .  used in a j
1cfd0 6f 69 6e 20 63 6f 6e 74 61 69 6e 73 20 61 20 4c  oin contains a L
1cfe0 49 4d 49 54 20 63 6c 61 75 73 65 3c 2f 61 3e 2c  IMIT clause</a>,
1cff0 20 74 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20   the results of 
1d000 74 68 65 20 73 75 62 2d 71 75 65 72 79 20 61 72  the sub-query ar
1d010 65 0a 20 20 63 61 6c 63 75 6c 61 74 65 64 20 61  e.  calculated a
1d020 6e 64 20 73 74 6f 72 65 64 20 69 6e 20 74 65 6d  nd stored in tem
1d030 70 6f 72 61 72 79 20 74 61 62 6c 65 20 62 65 66  porary table bef
1d040 6f 72 65 20 74 68 65 20 6d 61 69 6e 20 71 75 65  ore the main que
1d050 72 79 20 69 73 20 65 78 65 63 75 74 65 64 2e 0a  ry is executed..
1d060 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
1d070 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6c 6f  t SQLite will lo
1d080 61 64 20 6f 6e 6c 79 20 74 68 65 20 64 6f 63 69  ad only the doci
1d090 64 20 61 6e 64 20 6d 61 74 63 68 69 6e 66 6f 20  d and matchinfo 
1d0a0 64 61 74 61 20 66 6f 72 20 65 61 63 68 0a 20 20  data for each.  
1d0b0 72 6f 77 20 6d 61 74 63 68 69 6e 67 20 74 68 65  row matching the
1d0c0 20 75 73 65 72 73 20 71 75 65 72 79 20 69 6e 74   users query int
1d0d0 6f 20 6d 65 6d 6f 72 79 2c 20 64 65 74 65 72 6d  o memory, determ
1d0e0 69 6e 65 20 74 68 65 20 64 6f 63 69 64 20 76 61  ine the docid va
1d0f0 6c 75 65 73 0a 20 20 63 6f 72 72 65 73 70 6f 6e  lues.  correspon
1d100 64 69 6e 67 20 74 6f 20 74 68 65 20 74 65 6e 20  ding to the ten 
1d110 6d 6f 73 74 20 72 65 6c 65 76 61 6e 74 20 64 6f  most relevant do
1d120 63 75 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6c 6f  cuments, then lo
1d130 61 64 20 6f 6e 6c 79 20 74 68 65 20 74 69 74 6c  ad only the titl
1d140 65 0a 20 20 61 6e 64 20 63 6f 6e 74 65 6e 74 20  e.  and content 
1d150 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 66 6f 72 20  information for 
1d160 74 68 6f 73 65 20 31 30 20 64 6f 63 75 6d 65 6e  those 10 documen
1d170 74 73 20 6f 6e 6c 79 2e 20 42 65 63 61 75 73 65  ts only. Because
1d180 20 62 6f 74 68 20 74 68 65 20 6d 61 74 63 68 69   both the matchi
1d190 6e 66 6f 0a 20 20 61 6e 64 20 64 6f 63 69 64 20  nfo.  and docid 
1d1a0 76 61 6c 75 65 73 20 61 72 65 20 67 6c 65 61 6e  values are glean
1d1b0 65 64 20 65 6e 74 69 72 65 6c 79 20 66 72 6f 6d  ed entirely from
1d1c0 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
1d1d0 6e 64 65 78 2c 20 74 68 69 73 20 72 65 73 75 6c  ndex, this resul
1d1e0 74 73 0a 20 20 69 6e 20 64 72 61 6d 61 74 69 63  ts.  in dramatic
1d1f0 61 6c 6c 79 20 6c 65 73 73 20 64 61 74 61 20 62  ally less data b
1d200 65 69 6e 67 20 6c 6f 61 64 65 64 20 66 72 6f 6d  eing loaded from
1d210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1d220 74 6f 20 6d 65 6d 6f 72 79 2e 0a 0a 3c 63 6f 64  to memory...<cod
1d230 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54  eblock>.  SELECT
1d240 20 74 69 74 6c 65 20 46 52 4f 4d 20 64 6f 63 75   title FROM docu
1d250 6d 65 6e 74 73 20 4a 4f 49 4e 20 28 20 0a 20 20  ments JOIN ( .  
1d260 20 20 20 20 53 45 4c 45 43 54 20 64 6f 63 69 64      SELECT docid
1d270 2c 20 72 61 6e 6b 28 6d 61 74 63 68 69 6e 66 6f  , rank(matchinfo
1d280 28 64 6f 63 75 6d 65 6e 74 73 29 29 20 41 53 20  (documents)) AS 
1d290 72 61 6e 6b 20 0a 20 20 20 20 20 20 46 52 4f 4d  rank .      FROM
1d2a0 20 64 6f 63 75 6d 65 6e 74 73 0a 20 20 20 20 20   documents.     
1d2b0 20 57 48 45 52 45 20 64 6f 63 75 6d 65 6e 74 73   WHERE documents
1d2c0 20 4d 41 54 43 48 20 26 6c 74 3b 71 75 65 72 79   MATCH &lt;query
1d2d0 26 67 74 3b 0a 20 20 20 20 20 20 4f 52 44 45 52  &gt;.      ORDER
1d2e0 20 42 59 20 72 61 6e 6b 20 44 45 53 43 20 0a 20   BY rank DESC . 
1d2f0 20 20 20 20 20 4c 49 4d 49 54 20 31 30 20 4f 46       LIMIT 10 OF
1d300 46 53 45 54 20 30 0a 20 20 29 20 41 53 20 72 61  FSET 0.  ) AS ra
1d310 6e 6b 74 61 62 6c 65 20 55 53 49 4e 47 28 64 6f  nktable USING(do
1d320 63 69 64 29 0a 20 20 4f 52 44 45 52 20 42 59 20  cid).  ORDER BY 
1d330 72 61 6e 6b 74 61 62 6c 65 2e 72 61 6e 6b 20 44  ranktable.rank D
1d340 45 53 43 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  ESC.</codeblock>
1d350 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 6e 65 78 74  ..<p>.  The next
1d360 20 62 6c 6f 63 6b 20 6f 66 20 53 51 4c 20 65 6e   block of SQL en
1d370 68 61 6e 63 65 73 20 74 68 65 20 71 75 65 72 79  hances the query
1d380 20 77 69 74 68 20 73 6f 6c 75 74 69 6f 6e 73 20   with solutions 
1d390 74 6f 20 74 77 6f 20 6f 74 68 65 72 20 70 72 6f  to two other pro
1d3a0 62 6c 65 6d 73 0a 20 20 74 68 61 74 20 6d 61 79  blems.  that may
1d3b0 20 61 72 69 73 65 20 69 6e 20 64 65 76 65 6c 6f   arise in develo
1d3c0 70 69 6e 67 20 73 65 61 72 63 68 20 61 70 70 6c  ping search appl
1d3d0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 20 46  ications using F
1d3e0 54 53 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e  TS:..<ol>.  <li>
1d3f0 20 3c 70 3e 0a 20 20 20 20 20 20 20 54 68 65 20   <p>.       The 
1d400 5b 73 6e 69 70 70 65 74 5d 20 66 75 6e 63 74 69  [snippet] functi
1d410 6f 6e 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  on cannot be use
1d420 64 20 77 69 74 68 20 74 68 65 20 61 62 6f 76 65  d with the above
1d430 20 71 75 65 72 79 2e 20 42 65 63 61 75 73 65 0a   query. Because.
1d440 20 20 20 20 20 20 20 74 68 65 20 6f 75 74 65 72         the outer
1d450 20 71 75 65 72 79 20 64 6f 65 73 20 6e 6f 74 20   query does not 
1d460 69 6e 63 6c 75 64 65 20 61 20 22 57 48 45 52 45  include a "WHERE
1d470 20 2e 2e 2e 20 4d 41 54 43 48 22 20 63 6c 61 75   ... MATCH" clau
1d480 73 65 2c 20 74 68 65 20 73 6e 69 70 70 65 74 20  se, the snippet 
1d490 0a 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  .       function
1d4a0 20 6d 61 79 20 6e 6f 74 20 62 65 20 75 73 65 64   may not be used
1d4b0 20 77 69 74 68 20 69 74 2e 20 4f 6e 65 20 73 6f   with it. One so
1d4c0 6c 75 74 69 6f 6e 20 69 73 20 74 6f 20 64 75 70  lution is to dup
1d4d0 6c 69 63 61 74 65 20 74 68 65 20 57 48 45 52 45  licate the WHERE
1d4e0 0a 20 20 20 20 20 20 20 63 6c 61 75 73 65 20 75  .       clause u
1d4f0 73 65 64 20 62 79 20 74 68 65 20 73 75 62 2d 71  sed by the sub-q
1d500 75 65 72 79 20 69 6e 20 74 68 65 20 6f 75 74 65  uery in the oute
1d510 72 20 71 75 65 72 79 2e 20 54 68 65 20 6f 76 65  r query. The ove
1d520 72 68 65 61 64 20 61 73 73 6f 63 69 61 74 65 64  rhead associated
1d530 0a 20 20 20 20 20 20 20 77 69 74 68 20 74 68 69  .       with thi
1d540 73 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 65 67  s is usually neg
1d550 6c 69 67 69 62 6c 65 2e 0a 20 20 3c 6c 69 3e 20  ligible..  <li> 
1d560 3c 70 3e 0a 20 20 20 20 20 20 20 54 68 65 20 72  <p>.       The r
1d570 65 6c 65 76 61 6e 63 79 20 6f 66 20 61 20 64 6f  elevancy of a do
1d580 63 75 6d 65 6e 74 20 6d 61 79 20 64 65 70 65 6e  cument may depen
1d590 64 20 6f 6e 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d on something o
1d5a0 74 68 65 72 20 74 68 61 6e 20 6a 75 73 74 0a 20  ther than just. 
1d5b0 20 20 20 20 20 20 74 68 65 20 64 61 74 61 20 61        the data a
1d5c0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1d5d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1d5e0 6d 61 74 63 68 69 6e 66 6f 2e 20 46 6f 72 20 65  matchinfo. For e
1d5f0 78 61 6d 70 6c 65 0a 20 20 20 20 20 20 20 65 61  xample.       ea
1d600 63 68 20 64 6f 63 75 6d 65 6e 74 20 69 6e 20 74  ch document in t
1d610 68 65 20 64 61 74 61 62 61 73 65 20 6d 61 79 20  he database may 
1d620 62 65 20 61 73 73 69 67 6e 65 64 20 61 20 73 74  be assigned a st
1d630 61 74 69 63 20 77 65 69 67 68 74 20 62 61 73 65  atic weight base
1d640 64 0a 20 20 20 20 20 20 20 6f 6e 20 66 61 63 74  d.       on fact
1d650 6f 72 73 20 75 6e 72 65 6c 61 74 65 64 20 74 6f  ors unrelated to
1d660 20 69 74 73 20 63 6f 6e 74 65 6e 74 20 28 6f 72   its content (or
1d670 69 67 69 6e 2c 20 61 75 74 68 6f 72 2c 20 61 67  igin, author, ag
1d680 65 2c 20 6e 75 6d 62 65 72 0a 20 20 20 20 20 20  e, number.      
1d690 20 6f 66 20 72 65 66 65 72 65 6e 63 65 73 20 65   of references e
1d6a0 74 63 2e 29 2e 20 54 68 65 73 65 20 76 61 6c 75  tc.). These valu
1d6b0 65 73 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  es can be stored
1d6c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
1d6d0 69 6f 6e 0a 20 20 20 20 20 20 20 69 6e 20 61 20  ion.       in a 
1d6e0 73 65 70 61 72 61 74 65 20 74 61 62 6c 65 20 74  separate table t
1d6f0 68 61 74 20 63 61 6e 20 62 65 20 6a 6f 69 6e 65  hat can be joine
1d700 64 20 61 67 61 69 6e 73 74 20 74 68 65 20 64 6f  d against the do
1d710 63 75 6d 65 6e 74 73 20 74 61 62 6c 65 0a 20 20  cuments table.  
1d720 20 20 20 20 20 69 6e 20 74 68 65 20 73 75 62 2d       in the sub-
1d730 71 75 65 72 79 20 73 6f 20 74 68 61 74 20 74 68  query so that th
1d740 65 20 72 61 6e 6b 20 66 75 6e 63 74 69 6f 6e 20  e rank function 
1d750 6d 61 79 20 61 63 63 65 73 73 20 74 68 65 6d 2e  may access them.
1d760 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68  .</ol>..<p>.  Th
1d770 69 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  is version of th
1d780 65 20 71 75 65 72 79 20 69 73 20 76 65 72 79 20  e query is very 
1d790 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 61 74 20  similar to that 
1d7a0 75 73 65 64 20 62 79 20 74 68 65 20 0a 20 20 3c  used by the .  <
1d7b0 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
1d7c0 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 65  ww.sqlite.org/se
1d7d0 61 72 63 68 3f 71 3d 66 74 73 33 22 3e 73 71 6c  arch?q=fts3">sql
1d7e0 69 74 65 2e 6f 72 67 20 64 6f 63 75 6d 65 6e 74  ite.org document
1d7f0 61 74 69 6f 6e 20 73 65 61 72 63 68 3c 2f 61 3e  ation search</a>
1d800 20 0a 20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e   .  application.
1d810 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
1d820 3c 69 3e 2d 2d 20 54 68 69 73 20 74 61 62 6c 65  <i>-- This table
1d830 20 73 74 6f 72 65 73 20 74 68 65 20 73 74 61 74   stores the stat
1d840 69 63 20 77 65 69 67 68 74 20 61 73 73 69 67 6e  ic weight assign
1d850 65 64 20 74 6f 20 65 61 63 68 20 64 6f 63 75 6d  ed to each docum
1d860 65 6e 74 20 69 6e 20 46 54 53 20 74 61 62 6c 65  ent in FTS table
1d870 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 64 6f  </i>.  <i>-- "do
1d880 63 75 6d 65 6e 74 73 22 2e 20 46 6f 72 20 65 61  cuments". For ea
1d890 63 68 20 72 6f 77 20 69 6e 20 74 68 65 20 64 6f  ch row in the do
1d8a0 63 75 6d 65 6e 74 73 20 74 61 62 6c 65 20 74 68  cuments table th
1d8b0 65 72 65 20 69 73 20 61 20 63 6f 72 72 65 73 70  ere is a corresp
1d8c0 6f 6e 64 69 6e 67 20 72 6f 77 3c 2f 69 3e 0a 20  onding row</i>. 
1d8d0 20 3c 69 3e 2d 2d 20 77 69 74 68 20 74 68 65 20   <i>-- with the 
1d8e0 73 61 6d 65 20 64 6f 63 69 64 20 76 61 6c 75 65  same docid value
1d8f0 20 69 6e 20 74 68 69 73 20 74 61 62 6c 65 2e 3c   in this table.<
1d900 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 54 41 42  /i>.  CREATE TAB
1d910 4c 45 20 64 6f 63 75 6d 65 6e 74 73 5f 64 61 74  LE documents_dat
1d920 61 28 64 6f 63 69 64 20 49 4e 54 45 47 45 52 20  a(docid INTEGER 
1d930 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 77 65 69  PRIMARY KEY, wei
1d940 67 68 74 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54  ght);..  <i>-- T
1d950 68 69 73 20 71 75 65 72 79 20 69 73 20 73 69 6d  his query is sim
1d960 69 6c 61 72 20 74 6f 20 74 68 65 20 6f 6e 65 20  ilar to the one 
1d970 69 6e 20 74 68 65 20 62 6c 6f 63 6b 20 61 62 6f  in the block abo
1d980 76 65 2c 20 65 78 63 65 70 74 20 74 68 61 74 3a  ve, except that:
1d990 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 3c 2f 69 3e  </i>.  <i>--</i>
1d9a0 0a 20 20 3c 69 3e 2d 2d 20 20 20 31 2e 20 49 74  .  <i>--   1. It
1d9b0 20 72 65 74 75 72 6e 73 20 61 20 22 73 6e 69 70   returns a "snip
1d9c0 70 65 74 22 20 6f 66 20 74 65 78 74 20 61 6c 6f  pet" of text alo
1d9d0 6e 67 20 77 69 74 68 20 74 68 65 20 64 6f 63 75  ng with the docu
1d9e0 6d 65 6e 74 20 74 69 74 6c 65 20 66 6f 72 20 64  ment title for d
1d9f0 69 73 70 6c 61 79 2e 20 53 6f 3c 2f 69 3e 0a 20  isplay. So</i>. 
1da00 20 3c 69 3e 2d 2d 20 20 20 20 20 20 74 68 61 74   <i>--      that
1da10 20 74 68 65 20 73 6e 69 70 70 65 74 20 66 75 6e   the snippet fun
1da20 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65  ction may be use
1da30 64 2c 20 74 68 65 20 22 57 48 45 52 45 20 2e 2e  d, the "WHERE ..
1da40 2e 20 4d 41 54 43 48 20 2e 2e 2e 22 20 63 6c 61  . MATCH ..." cla
1da50 75 73 65 20 66 72 6f 6d 3c 2f 69 3e 0a 20 20 3c  use from</i>.  <
1da60 69 3e 2d 2d 20 20 20 20 20 20 74 68 65 20 73 75  i>--      the su
1da70 62 2d 71 75 65 72 79 20 69 73 20 64 75 70 6c 69  b-query is dupli
1da80 63 61 74 65 64 20 69 6e 20 74 68 65 20 6f 75 74  cated in the out
1da90 65 72 20 71 75 65 72 79 2e 3c 2f 69 3e 0a 20 20  er query.</i>.  
1daa0 3c 69 3e 2d 2d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  <i>--</i>.  <i>-
1dab0 2d 20 20 20 32 2e 20 54 68 65 20 73 75 62 2d 71  -   2. The sub-q
1dac0 75 65 72 79 20 6a 6f 69 6e 73 20 74 68 65 20 64  uery joins the d
1dad0 6f 63 75 6d 65 6e 74 73 20 74 61 62 6c 65 20 77  ocuments table w
1dae0 69 74 68 20 74 68 65 20 64 6f 63 75 6d 65 6e 74  ith the document
1daf0 5f 64 61 74 61 20 74 61 62 6c 65 2c 20 73 6f 20  _data table, so 
1db00 74 68 61 74 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  that</i>.  <i>--
1db10 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 61        implementa
1db20 74 69 6f 6e 20 6f 66 20 74 68 65 20 72 61 6e 6b  tion of the rank
1db30 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 61 63   function has ac
1db40 63 65 73 73 20 74 6f 20 74 68 65 20 73 74 61 74  cess to the stat
1db50 69 63 20 77 65 69 67 68 74 20 61 73 73 69 67 6e  ic weight assign
1db60 65 64 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20  ed</i>.  <i>--  
1db70 20 20 20 20 74 6f 20 65 61 63 68 20 64 6f 63 75      to each docu
1db80 6d 65 6e 74 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45  ment.</i>.  SELE
1db90 43 54 20 74 69 74 6c 65 2c 20 73 6e 69 70 70 65  CT title, snippe
1dba0 74 28 64 6f 63 75 6d 65 6e 74 73 29 20 46 52 4f  t(documents) FRO
1dbb0 4d 20 64 6f 63 75 6d 65 6e 74 73 20 4a 4f 49 4e  M documents JOIN
1dbc0 20 28 20 0a 20 20 20 20 20 20 53 45 4c 45 43 54   ( .      SELECT
1dbd0 20 64 6f 63 69 64 2c 20 72 61 6e 6b 28 6d 61 74   docid, rank(mat
1dbe0 63 68 69 6e 66 6f 28 64 6f 63 75 6d 65 6e 74 73  chinfo(documents
1dbf0 29 2c 20 64 6f 63 75 6d 65 6e 74 73 5f 64 61 74  ), documents_dat
1dc00 61 2e 77 65 69 67 68 74 29 20 41 53 20 72 61 6e  a.weight) AS ran
1dc10 6b 0a 20 20 20 20 20 20 46 52 4f 4d 20 64 6f 63  k.      FROM doc
1dc20 75 6d 65 6e 74 73 20 4a 4f 49 4e 20 64 6f 63 75  uments JOIN docu
1dc30 6d 65 6e 74 73 5f 64 61 74 61 20 55 53 49 4e 47  ments_data USING
1dc40 28 64 6f 63 69 64 29 0a 20 20 20 20 20 20 57 48  (docid).      WH
1dc50 45 52 45 20 64 6f 63 75 6d 65 6e 74 73 20 4d 41  ERE documents MA
1dc60 54 43 48 20 26 6c 74 3b 71 75 65 72 79 26 67 74  TCH &lt;query&gt
1dc70 3b 0a 20 20 20 20 20 20 4f 52 44 45 52 20 42 59  ;.      ORDER BY
1dc80 20 72 61 6e 6b 20 44 45 53 43 20 0a 20 20 20 20   rank DESC .    
1dc90 20 20 4c 49 4d 49 54 20 31 30 20 4f 46 46 53 45    LIMIT 10 OFFSE
1dca0 54 20 30 0a 20 20 29 20 41 53 20 72 61 6e 6b 74  T 0.  ) AS rankt
1dcb0 61 62 6c 65 20 55 53 49 4e 47 28 64 6f 63 69 64  able USING(docid
1dcc0 29 0a 20 20 57 48 45 52 45 20 64 6f 63 75 6d 65  ).  WHERE docume
1dcd0 6e 74 73 20 4d 41 54 43 48 20 26 6c 74 3b 71 75  nts MATCH &lt;qu
1dce0 65 72 79 26 67 74 3b 0a 20 20 4f 52 44 45 52 20  ery&gt;.  ORDER 
1dcf0 42 59 20 72 61 6e 6b 74 61 62 6c 65 2e 72 61 6e  BY ranktable.ran
1dd00 6b 20 44 45 53 43 0a 3c 2f 63 6f 64 65 62 6c 6f  k DESC.</codeblo
1dd10 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 41 6c 6c 20 74  ck>..<p>.  All t
1dd20 68 65 20 65 78 61 6d 70 6c 65 20 71 75 65 72 69  he example queri
1dd30 65 73 20 61 62 6f 76 65 20 72 65 74 75 72 6e 20  es above return 
1dd40 74 68 65 20 74 65 6e 20 6d 6f 73 74 20 72 65 6c  the ten most rel
1dd50 65 76 61 6e 74 20 71 75 65 72 79 20 72 65 73 75  evant query resu
1dd60 6c 74 73 2e 0a 20 20 42 79 20 6d 6f 64 69 66 79  lts..  By modify
1dd70 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20 75  ing the values u
1dd80 73 65 64 20 77 69 74 68 20 74 68 65 20 4f 46 46  sed with the OFF
1dd90 53 45 54 20 61 6e 64 20 4c 49 4d 49 54 20 63 6c  SET and LIMIT cl
1dda0 61 75 73 65 73 2c 20 61 20 71 75 65 72 79 20 0a  auses, a query .
1ddb0 20 20 74 6f 20 72 65 74 75 72 6e 20 28 73 61 79    to return (say
1ddc0 29 20 74 68 65 20 6e 65 78 74 20 74 65 6e 20 6d  ) the next ten m
1ddd0 6f 73 74 20 72 65 6c 65 76 61 6e 74 20 72 65 73  ost relevant res
1dde0 75 6c 74 73 20 69 73 20 65 61 73 79 20 74 6f 20  ults is easy to 
1ddf0 63 6f 6e 73 74 72 75 63 74 2e 20 0a 20 20 54 68  construct. .  Th
1de00 69 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  is may be used t
1de10 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 64 61 74  o obtain the dat
1de20 61 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 61  a required for a
1de30 20 73 65 61 72 63 68 20 61 70 70 6c 69 63 61 74   search applicat
1de40 69 6f 6e 73 20 73 65 63 6f 6e 64 0a 20 20 61 6e  ions second.  an
1de50 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 67  d subsequent pag
1de60 65 73 20 6f 66 20 72 65 73 75 6c 74 73 2e 0a 0a  es of results...
1de70 3c 70 3e 0a 20 20 54 68 65 20 6e 65 78 74 20 62  <p>.  The next b
1de80 6c 6f 63 6b 20 63 6f 6e 74 61 69 6e 73 20 61 6e  lock contains an
1de90 20 65 78 61 6d 70 6c 65 20 72 61 6e 6b 20 66 75   example rank fu
1dea0 6e 63 74 69 6f 6e 20 74 68 61 74 20 75 73 65 73  nction that uses
1deb0 20 6d 61 74 63 68 69 6e 66 6f 20 64 61 74 61 20   matchinfo data 
1dec0 0a 20 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  .  implemented i
1ded0 6e 20 43 2e 20 49 6e 73 74 65 61 64 20 6f 66 20  n C. Instead of 
1dee0 61 20 73 69 6e 67 6c 65 20 77 65 69 67 68 74 2c  a single weight,
1def0 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 77 65 69   it allows a wei
1df00 67 68 74 20 74 6f 20 62 65 20 0a 20 20 65 78 74  ght to be .  ext
1df10 65 72 6e 61 6c 6c 79 20 61 73 73 69 67 6e 65 64  ernally assigned
1df20 20 74 6f 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20   to each column 
1df30 6f 66 20 65 61 63 68 20 64 6f 63 75 6d 65 6e 74  of each document
1df40 2e 20 49 74 20 6d 61 79 20 62 65 20 72 65 67 69  . It may be regi
1df50 73 74 65 72 65 64 0a 20 20 77 69 74 68 20 53 51  stered.  with SQ
1df60 4c 69 74 65 20 6c 69 6b 65 20 61 6e 79 20 6f 74  Lite like any ot
1df70 68 65 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f  her user functio
1df80 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
1df90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1dfa0 5d 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ]...<codeblock>.
1dfb0 3c 69 3e 2f 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20  <i>/*</i>.<i>** 
1dfc0 53 51 4c 69 74 65 20 75 73 65 72 20 64 65 66 69  SQLite user defi
1dfd0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
1dfe0 75 73 65 20 77 69 74 68 20 6d 61 74 63 68 69 6e  use with matchin
1dff0 66 6f 28 29 20 74 6f 20 63 61 6c 63 75 6c 61 74  fo() to calculat
1e000 65 20 74 68 65 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20  e the</i>.<i>** 
1e010 72 65 6c 65 76 61 6e 63 79 20 6f 66 20 61 6e 20  relevancy of an 
1e020 46 54 53 20 6d 61 74 63 68 2e 20 54 68 65 20 76  FTS match. The v
1e030 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
1e040 20 74 68 65 20 72 65 6c 65 76 61 6e 63 79 20 73   the relevancy s
1e050 63 6f 72 65 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 28  core</i>.<i>** (
1e060 61 20 72 65 61 6c 20 76 61 6c 75 65 20 67 72 65  a real value gre
1e070 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
1e080 61 6c 20 74 6f 20 7a 65 72 6f 29 2e 20 41 20 6c  al to zero). A l
1e090 61 72 67 65 72 20 76 61 6c 75 65 20 69 6e 64 69  arger value indi
1e0a0 63 61 74 65 73 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a  cates </i>.<i>**
1e0b0 20 61 20 6d 6f 72 65 20 72 65 6c 65 76 61 6e 74   a more relevant
1e0c0 20 64 6f 63 75 6d 65 6e 74 2e 3c 2f 69 3e 0a 3c   document.</i>.<
1e0d0 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 54  i>**</i>.<i>** T
1e0e0 68 65 20 6f 76 65 72 61 6c 6c 20 72 65 6c 65 76  he overall relev
1e0f0 61 6e 63 79 20 72 65 74 75 72 6e 65 64 20 69 73  ancy returned is
1e100 20 74 68 65 20 73 75 6d 20 6f 66 20 74 68 65 20   the sum of the 
1e110 72 65 6c 65 76 61 6e 63 69 65 73 20 6f 66 20 65  relevancies of e
1e120 61 63 68 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 63  ach </i>.<i>** c
1e130 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69 6e 20 74  olumn value in t
1e140 68 65 20 46 54 53 20 74 61 62 6c 65 2e 20 54 68  he FTS table. Th
1e150 65 20 72 65 6c 65 76 61 6e 63 79 20 6f 66 20 61  e relevancy of a
1e160 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69 73   column value is
1e170 20 74 68 65 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 73   the</i>.<i>** s
1e180 75 6d 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  um of the follow
1e190 69 6e 67 20 66 6f 72 20 65 61 63 68 20 72 65 70  ing for each rep
1e1a0 6f 72 74 61 62 6c 65 20 70 68 72 61 73 65 20 69  ortable phrase i
1e1b0 6e 20 74 68 65 20 46 54 53 20 71 75 65 72 79 3a  n the FTS query:
1e1c0 3c 2f 69 3e 0a 3c 69 3e 2a 2a 3c 2f 69 3e 0a 3c  </i>.<i>**</i>.<
1e1d0 69 3e 2a 2a 20 20 20 28 26 6c 74 3b 68 69 74 20  i>**   (&lt;hit 
1e1e0 63 6f 75 6e 74 26 67 74 3b 20 2f 20 26 6c 74 3b  count&gt; / &lt;
1e1f0 67 6c 6f 62 61 6c 20 68 69 74 20 63 6f 75 6e 74  global hit count
1e200 26 67 74 29 20 2a 20 26 6c 74 3b 63 6f 6c 75 6d  &gt) * &lt;colum
1e210 6e 20 77 65 69 67 68 74 26 67 74 3b 3c 2f 69 3e  n weight&gt;</i>
1e220 0a 3c 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a  .<i>**</i>.<i>**
1e230 20 77 68 65 72 65 20 26 6c 74 3b 68 69 74 20 63   where &lt;hit c
1e240 6f 75 6e 74 26 67 74 3b 20 69 73 20 74 68 65 20  ount&gt; is the 
1e250 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 61 6e  number of instan
1e260 63 65 73 20 6f 66 20 74 68 65 20 70 68 72 61 73  ces of the phras
1e270 65 20 69 6e 20 74 68 65 3c 2f 69 3e 0a 3c 69 3e  e in the</i>.<i>
1e280 2a 2a 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20  ** column value 
1e290 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  of the current r
1e2a0 6f 77 20 61 6e 64 20 26 6c 74 3b 67 6c 6f 62 61  ow and &lt;globa
1e2b0 6c 20 68 69 74 20 63 6f 75 6e 74 26 67 74 3b 20  l hit count&gt; 
1e2c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 3c 2f 69  is the number</i
1e2d0 3e 0a 3c 69 3e 2a 2a 20 6f 66 20 69 6e 73 74 61  >.<i>** of insta
1e2e0 6e 63 65 73 20 6f 66 20 74 68 65 20 70 68 72 61  nces of the phra
1e2f0 73 65 20 69 6e 20 74 68 65 20 73 61 6d 65 20 63  se in the same c
1e300 6f 6c 75 6d 6e 20 6f 66 20 61 6c 6c 20 72 6f 77  olumn of all row
1e310 73 20 69 6e 20 74 68 65 20 46 54 53 3c 2f 69 3e  s in the FTS</i>
1e320 0a 3c 69 3e 2a 2a 20 74 61 62 6c 65 2e 20 54 68  .<i>** table. Th
1e330 65 20 26 6c 74 3b 63 6f 6c 75 6d 6e 20 77 65 69  e &lt;column wei
1e340 67 68 74 26 67 74 3b 20 69 73 20 61 20 77 65 69  ght&gt; is a wei
1e350 67 68 74 69 6e 67 20 66 61 63 74 6f 72 20 61 73  ghting factor as
1e360 73 69 67 6e 65 64 20 74 6f 20 65 61 63 68 3c 2f  signed to each</
1e370 69 3e 0a 3c 69 3e 2a 2a 20 63 6f 6c 75 6d 6e 20  i>.<i>** column 
1e380 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 28 73  by the caller (s
1e390 65 65 20 62 65 6c 6f 77 29 2e 3c 2f 69 3e 0a 3c  ee below).</i>.<
1e3a0 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 54  i>**</i>.<i>** T
1e3b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1e3c0 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
1e3d0 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 65 20 72  on must be the r
1e3e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1e3f0 68 65 20 46 54 53 20 3c 2f 69 3e 0a 3c 69 3e 2a  he FTS </i>.<i>*
1e400 2a 20 6d 61 74 63 68 69 6e 66 6f 28 29 20 66 75  * matchinfo() fu
1e410 6e 63 74 69 6f 6e 2e 20 46 6f 6c 6c 6f 77 69 6e  nction. Followin
1e420 67 20 74 68 69 73 20 6d 75 73 74 20 62 65 20 6f  g this must be o
1e430 6e 65 20 61 72 67 75 6d 65 6e 74 20 66 6f 72 20  ne argument for 
1e440 65 61 63 68 20 63 6f 6c 75 6d 6e 20 3c 2f 69 3e  each column </i>
1e450 0a 3c 69 3e 2a 2a 20 6f 66 20 74 68 65 20 46 54  .<i>** of the FT
1e460 53 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 69  S table containi
1e470 6e 67 20 61 20 6e 75 6d 65 72 69 63 20 77 65 69  ng a numeric wei
1e480 67 68 74 20 66 61 63 74 6f 72 20 66 6f 72 20 74  ght factor for t
1e490 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1e4a0 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 63 6f 6c 75   </i>.<i>** colu
1e4b0 6d 6e 2e 20 45 78 61 6d 70 6c 65 3a 3c 2f 69 3e  mn. Example:</i>
1e4c0 0a 3c 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a  .<i>**</i>.<i>**
1e4d0 20 20 20 20 20 43 52 45 41 54 45 20 56 49 52 54       CREATE VIRT
1e4e0 55 41 4c 20 54 41 42 4c 45 20 64 6f 63 75 6d 65  UAL TABLE docume
1e4f0 6e 74 73 20 55 53 49 4e 47 20 66 74 73 33 28 74  nts USING fts3(t
1e500 69 74 6c 65 2c 20 63 6f 6e 74 65 6e 74 29 3c 2f  itle, content)</
1e510 69 3e 0a 3c 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e  i>.<i>**</i>.<i>
1e520 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
1e530 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 74   query returns t
1e540 68 65 20 64 6f 63 69 64 73 20 6f 66 20 64 6f 63  he docids of doc
1e550 75 6d 65 6e 74 73 20 74 68 61 74 20 6d 61 74 63  uments that matc
1e560 68 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 3c  h the full-text<
1e570 2f 69 3e 0a 3c 69 3e 2a 2a 20 71 75 65 72 79 20  /i>.<i>** query 
1e580 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 73 6f  &lt;query&gt; so
1e590 72 74 65 64 20 66 72 6f 6d 20 6d 6f 73 74 20 74  rted from most t
1e5a0 6f 20 6c 65 61 73 74 20 72 65 6c 65 76 61 6e 74  o least relevant
1e5b0 2e 20 57 68 65 6e 20 63 61 6c 63 75 6c 61 74 69  . When calculati
1e5c0 6e 67 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 72 65 6c  ng</i>.<i>** rel
1e5d0 65 76 61 6e 63 65 2c 20 71 75 65 72 79 20 74 65  evance, query te
1e5e0 72 6d 20 69 6e 73 74 61 6e 63 65 73 20 69 6e 20  rm instances in 
1e5f0 74 68 65 20 27 74 69 74 6c 65 27 20 63 6f 6c 75  the 'title' colu
1e600 6d 6e 20 61 72 65 20 67 69 76 65 6e 20 74 77 69  mn are given twi
1e610 63 65 20 74 68 65 3c 2f 69 3e 0a 3c 69 3e 2a 2a  ce the</i>.<i>**
1e620 20 77 65 69 67 68 74 69 6e 67 20 6f 66 20 74 68   weighting of th
1e630 6f 73 65 20 69 6e 20 74 68 65 20 27 63 6f 6e 74  ose in the 'cont
1e640 65 6e 74 27 20 63 6f 6c 75 6d 6e 2e 3c 2f 69 3e  ent' column.</i>
1e650 0a 3c 69 3e 2a 2a 3c 2f 69 3e 0a 3c 69 3e 2a 2a  .<i>**</i>.<i>**
1e660 20 20 20 20 20 53 45 4c 45 43 54 20 64 6f 63 69       SELECT doci
1e670 64 20 46 52 4f 4d 20 64 6f 63 75 6d 65 6e 74 73  d FROM documents
1e680 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 20 20 20 20   </i>.<i>**     
1e690 57 48 45 52 45 20 64 6f 63 75 6d 65 6e 74 73 20  WHERE documents 
1e6a0 4d 41 54 43 48 20 26 6c 74 3b 71 75 65 72 79 26  MATCH &lt;query&
1e6b0 67 74 3b 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20 20  gt; </i>.<i>**  
1e6c0 20 20 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b     ORDER BY rank
1e6d0 28 6d 61 74 63 68 69 6e 66 6f 28 64 6f 63 75 6d  (matchinfo(docum
1e6e0 65 6e 74 73 29 2c 20 31 2e 30 2c 20 30 2e 35 29  ents), 1.0, 0.5)
1e6f0 20 44 45 53 43 3c 2f 69 3e 0a 3c 69 3e 2a 2f 3c   DESC</i>.<i>*/<
1e700 2f 69 3e 0a 73 74 61 74 69 63 20 76 6f 69 64 20  /i>.static void 
1e710 72 61 6e 6b 66 75 6e 63 28 73 71 6c 69 74 65 33  rankfunc(sqlite3
1e720 5f 63 6f 6e 74 65 78 74 20 2a 70 43 74 78 2c 20  _context *pCtx, 
1e730 69 6e 74 20 6e 56 61 6c 2c 20 73 71 6c 69 74 65  int nVal, sqlite
1e740 33 5f 76 61 6c 75 65 20 2a 2a 61 70 56 61 6c 29  3_value **apVal)
1e750 7b 0a 20 20 69 6e 74 20 2a 61 4d 61 74 63 68 69  {.  int *aMatchi
1e760 6e 66 6f 3b 20 20 20 20 20 20 20 20 20 20 20 20  nfo;            
1e770 20 20 20 20 3c 69 3e 2f 2a 20 52 65 74 75 72 6e      <i>/* Return
1e780 20 76 61 6c 75 65 20 6f 66 20 6d 61 74 63 68 69   value of matchi
1e790 6e 66 6f 28 29 20 2a 2f 3c 2f 69 3e 0a 20 20 69  nfo() */</i>.  i
1e7a0 6e 74 20 6e 43 6f 6c 3b 20 20 20 20 20 20 20 20  nt nCol;        
1e7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c                 <
1e7c0 69 3e 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 63  i>/* Number of c
1e7d0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61  olumns in the ta
1e7e0 62 6c 65 20 2a 2f 3c 2f 69 3e 0a 20 20 69 6e 74  ble */</i>.  int
1e7f0 20 6e 50 68 72 61 73 65 3b 20 20 20 20 20 20 20   nPhrase;       
1e800 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
1e810 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 70 68 72  /* Number of phr
1e820 61 73 65 73 20 69 6e 20 74 68 65 20 71 75 65 72  ases in the quer
1e830 79 20 2a 2f 3c 2f 69 3e 0a 20 20 69 6e 74 20 69  y */</i>.  int i
1e840 50 68 72 61 73 65 3b 20 20 20 20 20 20 20 20 20  Phrase;         
1e850 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2f 2a             <i>/*
1e860 20 43 75 72 72 65 6e 74 20 70 68 72 61 73 65 20   Current phrase 
1e870 2a 2f 3c 2f 69 3e 0a 20 20 64 6f 75 62 6c 65 20  */</i>.  double 
1e880 73 63 6f 72 65 20 3d 20 30 2e 30 3b 20 20 20 20  score = 0.0;    
1e890 20 20 20 20 20 20 20 20 20 3c 69 3e 2f 2a 20 56           <i>/* V
1e8a0 61 6c 75 65 20 74 6f 20 72 65 74 75 72 6e 20 2a  alue to return *
1e8b0 2f 3c 2f 69 3e 0a 0a 20 20 61 73 73 65 72 74 28  /</i>..  assert(
1e8c0 20 73 69 7a 65 6f 66 28 69 6e 74 29 3d 3d 34 20   sizeof(int)==4 
1e8d0 29 3b 0a 0a 3c 69 3e 20 20 2f 2a 20 43 68 65 63  );..<i>  /* Chec
1e8e0 6b 20 74 68 61 74 20 74 68 65 20 6e 75 6d 62 65  k that the numbe
1e8f0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 70  r of arguments p
1e900 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 66 75  assed to this fu
1e910 6e 63 74 69 6f 6e 20 69 73 20 63 6f 72 72 65 63  nction is correc
1e920 74 2e 3c 2f 69 3e 0a 3c 69 3e 20 20 2a 2a 20 49  t.</i>.<i>  ** I
1e930 66 20 6e 6f 74 2c 20 6a 75 6d 70 20 74 6f 20 77  f not, jump to w
1e940 72 6f 6e 67 5f 6e 75 6d 62 65 72 5f 61 72 67 73  rong_number_args
1e950 2e 20 53 65 74 20 61 4d 61 74 63 68 69 6e 66 6f  . Set aMatchinfo
1e960 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1e970 20 61 72 72 61 79 3c 2f 69 3e 0a 3c 69 3e 20 20   array</i>.<i>  
1e980 2a 2a 20 6f 66 20 75 6e 73 69 67 6e 65 64 20 69  ** of unsigned i
1e990 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 72 65  nteger values re
1e9a0 74 75 72 6e 65 64 20 62 79 20 46 54 53 20 66 75  turned by FTS fu
1e9b0 6e 63 74 69 6f 6e 20 6d 61 74 63 68 69 6e 66 6f  nction matchinfo
1e9c0 2e 20 53 65 74 3c 2f 69 3e 0a 3c 69 3e 20 20 2a  . Set</i>.<i>  *
1e9d0 2a 20 6e 50 68 72 61 73 65 20 74 6f 20 63 6f 6e  * nPhrase to con
1e9e0 74 61 69 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  tain the number 
1e9f0 6f 66 20 72 65 70 6f 72 74 61 62 6c 65 20 70 68  of reportable ph
1ea00 72 61 73 65 73 20 69 6e 20 74 68 65 20 75 73 65  rases in the use
1ea10 72 73 20 66 75 6c 6c 2d 74 65 78 74 3c 2f 69 3e  rs full-text</i>
1ea20 0a 3c 69 3e 20 20 2a 2a 20 71 75 65 72 79 2c 20  .<i>  ** query, 
1ea30 61 6e 64 20 6e 43 6f 6c 20 74 6f 20 74 68 65 20  and nCol to the 
1ea40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1ea50 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 3c  s in the table.<
1ea60 2f 69 3e 0a 3c 69 3e 20 20 2a 2f 3c 2f 69 3e 0a  /i>.<i>  */</i>.
1ea70 20 20 69 66 28 20 6e 56 61 6c 26 6c 74 3b 31 20    if( nVal&lt;1 
1ea80 29 20 67 6f 74 6f 20 77 72 6f 6e 67 5f 6e 75 6d  ) goto wrong_num
1ea90 62 65 72 5f 61 72 67 73 3b 0a 20 20 61 4d 61 74  ber_args;.  aMat
1eaa0 63 68 69 6e 66 6f 20 3d 20 28 75 6e 73 69 67 6e  chinfo = (unsign
1eab0 65 64 20 69 6e 74 20 2a 29 73 71 6c 69 74 65 33  ed int *)sqlite3
1eac0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 61 70 56 61  _value_blob(apVa
1ead0 6c 26 23 78 35 42 3b 30 26 23 78 35 44 3b 29 3b  l&#x5B;0&#x5D;);
1eae0 0a 20 20 6e 50 68 72 61 73 65 20 3d 20 61 4d 61  .  nPhrase = aMa
1eaf0 74 63 68 69 6e 66 6f 26 23 78 35 42 3b 30 26 23  tchinfo&#x5B;0&#
1eb00 78 35 44 3b 3b 0a 20 20 6e 43 6f 6c 20 3d 20 61  x5D;;.  nCol = a
1eb10 4d 61 74 63 68 69 6e 66 6f 26 23 78 35 42 3b 31  Matchinfo&#x5B;1
1eb20 26 23 78 35 44 3b 3b 0a 20 20 69 66 28 20 6e 56  &#x5D;;.  if( nV
1eb30 61 6c 21 3d 28 31 2b 6e 43 6f 6c 29 20 29 20 67  al!=(1+nCol) ) g
1eb40 6f 74 6f 20 77 72 6f 6e 67 5f 6e 75 6d 62 65 72  oto wrong_number
1eb50 5f 61 72 67 73 3b 0a 0a 3c 69 3e 20 20 2f 2a 20  _args;..<i>  /* 
1eb60 49 74 65 72 61 74 65 20 74 68 72 6f 75 67 68 20  Iterate through 
1eb70 65 61 63 68 20 70 68 72 61 73 65 20 69 6e 20 74  each phrase in t
1eb80 68 65 20 75 73 65 72 73 20 71 75 65 72 79 2e 20  he users query. 
1eb90 2a 2f 3c 2f 69 3e 0a 20 20 66 6f 72 28 69 50 68  */</i>.  for(iPh
1eba0 72 61 73 65 3d 30 3b 20 69 50 68 72 61 73 65 26  rase=0; iPhrase&
1ebb0 6c 74 3b 6e 50 68 72 61 73 65 3b 20 69 50 68 72  lt;nPhrase; iPhr
1ebc0 61 73 65 2b 2b 29 7b 0a 20 20 20 20 69 6e 74 20  ase++){.    int 
1ebd0 69 43 6f 6c 3b 20 20 20 20 20 20 20 20 20 20 20  iCol;           
1ebe0 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2f 2a 20            <i>/* 
1ebf0 43 75 72 72 65 6e 74 20 63 6f 6c 75 6d 6e 20 2a  Current column *
1ec00 2f 3c 2f 69 3e 0a 0a 3c 69 3e 20 20 20 20 2f 2a  /</i>..<i>    /*
1ec10 20 4e 6f 77 20 69 74 65 72 61 74 65 20 74 68 72   Now iterate thr
1ec20 6f 75 67 68 20 65 61 63 68 20 63 6f 6c 75 6d 6e  ough each column
1ec30 20 69 6e 20 74 68 65 20 75 73 65 72 73 20 71 75   in the users qu
1ec40 65 72 79 2e 20 46 6f 72 20 65 61 63 68 20 63 6f  ery. For each co
1ec50 6c 75 6d 6e 2c 3c 2f 69 3e 0a 3c 69 3e 20 20 20  lumn,</i>.<i>   
1ec60 20 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 20 74 68   ** increment th
1ec70 65 20 72 65 6c 65 76 61 6e 63 79 20 73 63 6f 72  e relevancy scor
1ec80 65 20 62 79 3a 3c 2f 69 3e 0a 3c 69 3e 20 20 20  e by:</i>.<i>   
1ec90 20 2a 2a 3c 2f 69 3e 0a 3c 69 3e 20 20 20 20 2a   **</i>.<i>    *
1eca0 2a 20 20 20 28 26 6c 74 3b 68 69 74 20 63 6f 75  *   (&lt;hit cou
1ecb0 6e 74 26 67 74 3b 20 2f 20 26 6c 74 3b 67 6c 6f  nt&gt; / &lt;glo
1ecc0 62 61 6c 20 68 69 74 20 63 6f 75 6e 74 26 67 74  bal hit count&gt
1ecd0 29 20 2a 20 26 6c 74 3b 63 6f 6c 75 6d 6e 20 77  ) * &lt;column w
1ece0 65 69 67 68 74 26 67 74 3b 3c 2f 69 3e 0a 3c 69  eight&gt;</i>.<i
1ecf0 3e 20 20 20 20 2a 2a 3c 2f 69 3e 0a 3c 69 3e 20  >    **</i>.<i> 
1ed00 20 20 20 2a 2a 20 61 50 68 72 61 73 65 69 6e 66     ** aPhraseinf
1ed10 6f 26 23 78 35 42 3b 26 23 78 35 44 3b 20 70 6f  o&#x5B;&#x5D; po
1ed20 69 6e 74 73 20 74 6f 20 74 68 65 20 73 74 61 72  ints to the star
1ed30 74 20 6f 66 20 74 68 65 20 64 61 74 61 20 66 6f  t of the data fo
1ed40 72 20 70 68 72 61 73 65 20 69 50 68 72 61 73 65  r phrase iPhrase
1ed50 2e 20 53 6f 3c 2f 69 3e 0a 3c 69 3e 20 20 20 20  . So</i>.<i>    
1ed60 2a 2a 20 74 68 65 20 68 69 74 20 63 6f 75 6e 74  ** the hit count
1ed70 20 61 6e 64 20 67 6c 6f 62 61 6c 20 68 69 74 20   and global hit 
1ed80 63 6f 75 6e 74 73 20 66 6f 72 20 65 61 63 68 20  counts for each 
1ed90 63 6f 6c 75 6d 6e 20 61 72 65 20 66 6f 75 6e 64  column are found
1eda0 20 69 6e 20 3c 2f 69 3e 0a 3c 69 3e 20 20 20 20   in </i>.<i>    
1edb0 2a 2a 20 61 50 68 72 61 73 65 69 6e 66 6f 26 23  ** aPhraseinfo&#
1edc0 78 35 42 3b 69 43 6f 6c 2a 33 26 23 78 35 44 3b  x5B;iCol*3&#x5D;
1edd0 20 61 6e 64 20 61 50 68 72 61 73 65 69 6e 66 6f   and aPhraseinfo
1ede0 26 23 78 35 42 3b 69 43 6f 6c 2a 33 2b 31 26 23  &#x5B;iCol*3+1&#
1edf0 78 35 44 3b 2c 20 72 65 73 70 65 63 74 69 76 65  x5D;, respective
1ee00 6c 79 2e 3c 2f 69 3e 0a 3c 69 3e 20 20 20 20 2a  ly.</i>.<i>    *
1ee10 2f 3c 2f 69 3e 0a 20 20 20 20 69 6e 74 20 2a 61  /</i>.    int *a
1ee20 50 68 72 61 73 65 69 6e 66 6f 20 3d 20 26 61 4d  Phraseinfo = &aM
1ee30 61 74 63 68 69 6e 66 6f 26 23 78 35 42 3b 32 20  atchinfo&#x5B;2 
1ee40 2b 20 69 50 68 72 61 73 65 2a 6e 43 6f 6c 2a 33  + iPhrase*nCol*3
1ee50 26 23 78 35 44 3b 3b 0a 20 20 20 20 66 6f 72 28  &#x5D;;.    for(
1ee60 69 43 6f 6c 3d 30 3b 20 69 43 6f 6c 26 6c 74 3b  iCol=0; iCol&lt;
1ee70 6e 43 6f 6c 3b 20 69 43 6f 6c 2b 2b 29 7b 0a 20  nCol; iCol++){. 
1ee80 20 20 20 20 20 69 6e 74 20 6e 48 69 74 43 6f 75       int nHitCou
1ee90 6e 74 20 3d 20 61 50 68 72 61 73 65 69 6e 66 6f  nt = aPhraseinfo
1eea0 26 23 78 35 42 3b 33 2a 69 43 6f 6c 26 23 78 35  &#x5B;3*iCol&#x5
1eeb0 44 3b 3b 0a 20 20 20 20 20 20 69 6e 74 20 6e 47  D;;.      int nG
1eec0 6c 6f 62 61 6c 48 69 74 43 6f 75 6e 74 20 3d 20  lobalHitCount = 
1eed0 61 50 68 72 61 73 65 69 6e 66 6f 26 23 78 35 42  aPhraseinfo&#x5B
1eee0 3b 33 2a 69 43 6f 6c 2b 31 26 23 78 35 44 3b 3b  ;3*iCol+1&#x5D;;
1eef0 0a 20 20 20 20 20 20 64 6f 75 62 6c 65 20 77 65  .      double we
1ef00 69 67 68 74 20 3d 20 73 71 6c 69 74 65 33 5f 76  ight = sqlite3_v
1ef10 61 6c 75 65 5f 64 6f 75 62 6c 65 28 61 70 56 61  alue_double(apVa
1ef20 6c 26 23 78 35 42 3b 69 43 6f 6c 2b 31 26 23 78  l&#x5B;iCol+1&#x
1ef30 35 44 3b 29 3b 0a 20 20 20 20 20 20 69 66 28 20  5D;);.      if( 
1ef40 6e 48 69 74 43 6f 75 6e 74 3e 30 20 29 7b 0a 20  nHitCount>0 ){. 
1ef50 20 20 20 20 20 20 20 73 63 6f 72 65 20 2b 3d 20         score += 
1ef60 28 28 64 6f 75 62 6c 65 29 6e 48 69 74 43 6f 75  ((double)nHitCou
1ef70 6e 74 20 2f 20 28 64 6f 75 62 6c 65 29 6e 47 6c  nt / (double)nGl
1ef80 6f 62 61 6c 48 69 74 43 6f 75 6e 74 29 20 2a 20  obalHitCount) * 
1ef90 77 65 69 67 68 74 3b 0a 20 20 20 20 20 20 7d 0a  weight;.      }.
1efa0 20 20 20 20 7d 0a 20 20 7d 0a 0a 20 20 73 71 6c      }.  }..  sql
1efb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
1efc0 6c 65 28 70 43 74 78 2c 20 73 63 6f 72 65 29 3b  le(pCtx, score);
1efd0 0a 20 20 72 65 74 75 72 6e 3b 0a 0a 3c 69 3e 20  .  return;..<i> 
1efe0 20 2f 2a 20 4a 75 6d 70 20 68 65 72 65 20 69 66   /* Jump here if
1eff0 20 74 68 65 20 77 72 6f 6e 67 20 6e 75 6d 62 65   the wrong numbe
1f000 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 61  r of arguments a
1f010 72 65 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  re passed to thi
1f020 73 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 3c 2f 69  s function */</i
1f030 3e 0a 77 72 6f 6e 67 5f 6e 75 6d 62 65 72 5f 61  >.wrong_number_a
1f040 72 67 73 3a 0a 20 20 73 71 6c 69 74 65 33 5f 72  rgs:.  sqlite3_r
1f050 65 73 75 6c 74 5f 65 72 72 6f 72 28 70 43 74 78  esult_error(pCtx
1f060 2c 20 22 77 72 6f 6e 67 20 6e 75 6d 62 65 72 20  , "wrong number 
1f070 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
1f080 66 75 6e 63 74 69 6f 6e 20 72 61 6e 6b 28 29 22  function rank()"
1f090 2c 20 2d 31 29 3b 0a 7d 0a 3c 2f 63 6f 64 65 62  , -1);.}.</codeb
1f0a0 6c 6f 63 6b 3e 0a                                lock>.