Documentation Source Text

Hex Artifact Content
Login

Artifact bf358389c337c8b1757f7aecae7403266de77b07:


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 35 20 46 54 53 35 3c 2f 74 63  s *fts5 FTS5</tc
0020: 6c 3e 0a 3c 74 69 74 6c 65 3e 53 51 4c 69 74 65  l>.<title>SQLite
0030: 20 46 54 53 35 20 45 78 74 65 6e 73 69 6f 6e 3c   FTS5 Extension<
0040: 2f 74 69 74 6c 65 3e 0a 0a 3c 74 61 62 6c 65 5f  /title>..<table_
0050: 6f 66 5f 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 68  of_contents>..<h
0060: 32 20 73 74 79 6c 65 3d 22 6d 61 72 67 69 6e 2d  2 style="margin-
0070: 6c 65 66 74 3a 31 2e 30 65 6d 22 20 6e 6f 74 6f  left:1.0em" noto
0080: 63 3e 20 4f 76 65 72 76 69 65 77 3c 2f 68 32 3e  c> Overview</h2>
0090: 20 0a 0a 3c 68 31 3e 4f 76 65 72 76 69 65 77 20   ..<h1>Overview 
00a0: 6f 66 20 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 70  of FTS5</h1>..<p
00b0: 3e 46 54 53 35 20 69 73 20 61 6e 20 53 51 4c 69  >FTS5 is an SQLi
00c0: 74 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  te [virtual tabl
00d0: 65 20 6d 6f 64 75 6c 65 5d 20 74 68 61 74 20 70  e module] that p
00e0: 72 6f 76 69 64 65 73 20 0a 3c 61 20 68 72 65 66  rovides .<a href
00f0: 3d 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70  =http://en.wikip
0100: 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 46 75  edia.org/wiki/Fu
0110: 6c 6c 5f 74 65 78 74 5f 73 65 61 72 63 68 3e 66  ll_text_search>f
0120: 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 3c  ull-text search<
0130: 2f 61 3e 0a 66 75 6e 63 74 69 6f 6e 61 6c 69 74  /a>.functionalit
0140: 79 20 74 6f 20 64 61 74 61 62 61 73 65 20 61 70  y to database ap
0150: 70 6c 69 63 61 74 69 6f 6e 73 2e 20 49 6e 20 74  plications. In t
0160: 68 65 69 72 20 6d 6f 73 74 20 65 6c 65 6d 65 6e  heir most elemen
0170: 74 61 72 79 20 66 6f 72 6d 2c 20 0a 66 75 6c 6c  tary form, .full
0180: 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
0190: 69 6e 65 73 20 61 6c 6c 6f 77 20 74 68 65 20 75  ines allow the u
01a0: 73 65 72 20 74 6f 20 65 66 66 69 63 69 65 6e 74  ser to efficient
01b0: 6c 79 20 73 65 61 72 63 68 20 61 20 6c 61 72 67  ly search a larg
01c0: 65 20 0a 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  e .collection of
01d0: 20 64 6f 63 75 6d 65 6e 74 73 20 66 6f 72 20 74   documents for t
01e0: 68 65 20 73 75 62 73 65 74 20 74 68 61 74 20 63  he subset that c
01f0: 6f 6e 74 61 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f  ontain one or mo
0200: 72 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  re instances of 
0210: 61 0a 73 65 61 72 63 68 20 74 65 72 6d 2e 20 54  a.search term. T
0220: 68 65 20 73 65 61 72 63 68 20 66 75 6e 63 74 69  he search functi
0230: 6f 6e 61 6c 69 74 79 20 70 72 6f 76 69 64 65 64  onality provided
0240: 20 74 6f 20 77 6f 72 6c 64 20 77 69 64 65 20 77   to world wide w
0250: 65 62 20 75 73 65 72 73 20 62 79 0a 3c 61 20 68  eb users by.<a h
0260: 72 65 66 3d 77 77 77 2e 67 6f 6f 67 6c 65 2e 63  ref=www.google.c
0270: 6f 6d 3e 47 6f 6f 67 6c 65 3c 2f 61 3e 20 69 73  om>Google</a> is
0280: 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  , among other th
0290: 69 6e 67 73 2c 20 61 20 66 75 6c 6c 2d 74 65 78  ings, a full-tex
02a0: 74 20 73 65 61 72 63 68 0a 65 6e 67 69 6e 65 2c  t search.engine,
02b0: 20 61 73 20 69 74 20 61 6c 6c 6f 77 73 20 75 73   as it allows us
02c0: 65 72 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  ers to search fo
02d0: 72 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20  r all documents 
02e0: 6f 6e 20 74 68 65 20 77 65 62 20 74 68 61 74 20  on the web that 
02f0: 63 6f 6e 74 61 69 6e 2c 0a 66 6f 72 20 65 78 61  contain,.for exa
0300: 6d 70 6c 65 2c 20 74 68 65 20 74 65 72 6d 20 22  mple, the term "
0310: 66 74 73 35 22 2e 0a 0a 3c 70 3e 54 6f 20 75 73  fts5"...<p>To us
0320: 65 20 46 54 53 35 2c 20 74 68 65 20 75 73 65 72  e FTS5, the user
0330: 20 63 72 65 61 74 65 73 20 61 6e 20 46 54 53 35   creates an FTS5
0340: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
0350: 69 74 68 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  ith one or more.
0360: 63 6f 6c 75 6d 6e 73 2e 20 46 6f 72 20 65 78 61  columns. For exa
0370: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
0380: 6b 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  k>.  CREATE VIRT
0390: 55 41 4c 20 54 41 42 4c 45 20 65 6d 61 69 6c 20  UAL TABLE email 
03a0: 55 53 49 4e 47 20 66 74 73 35 28 73 65 6e 64 65  USING fts5(sende
03b0: 72 2c 20 74 69 74 6c 65 2c 20 62 6f 64 79 29 3b  r, title, body);
03c0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
03d0: 70 3e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72  p>It is an error
03e0: 20 74 6f 20 61 64 64 20 74 79 70 65 73 2c 20 63   to add types, c
03f0: 6f 6e 73 74 72 61 69 6e 74 73 20 6f 72 20 5b 50  onstraints or [P
0400: 52 49 4d 41 52 59 20 4b 45 59 5d 20 64 65 63 6c  RIMARY KEY] decl
0410: 61 72 61 74 69 6f 6e 73 20 74 6f 20 0a 61 20 43  arations to .a C
0420: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
0430: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 75 73  BLE statement us
0440: 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ed to create an 
0450: 46 54 53 35 20 74 61 62 6c 65 2e 20 4f 6e 63 65  FTS5 table. Once
0460: 20 63 72 65 61 74 65 64 2c 0a 61 6e 20 46 54 53   created,.an FTS
0470: 35 20 74 61 62 6c 65 20 6d 61 79 20 62 65 20 70  5 table may be p
0480: 6f 70 75 6c 61 74 65 64 20 75 73 69 6e 67 20 5b  opulated using [
0490: 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
04a0: 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
04b0: 61 74 65 6d 65 6e 74 73 0a 6c 69 6b 65 20 61 6e  atements.like an
04c0: 79 20 6f 74 68 65 72 20 74 61 62 6c 65 2e 20 4c  y other table. L
04d0: 69 6b 65 20 61 6e 79 20 6f 74 68 65 72 20 74 61  ike any other ta
04e0: 62 6c 65 20 77 69 74 68 20 6e 6f 20 50 52 49 4d  ble with no PRIM
04f0: 41 52 59 20 4b 45 59 20 64 65 63 6c 61 72 61 74  ARY KEY declarat
0500: 69 6f 6e 2c 20 61 6e 0a 46 54 53 35 20 74 61 62  ion, an.FTS5 tab
0510: 6c 65 20 68 61 73 20 61 6e 20 69 6d 70 6c 69 63  le has an implic
0520: 69 74 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  it INTEGER PRIMA
0530: 52 59 20 4b 45 59 20 66 69 65 6c 64 20 6e 61 6d  RY KEY field nam
0540: 65 64 20 72 6f 77 69 64 2e 20 0a 0a 3c 70 3e 4e  ed rowid. ..<p>N
0550: 6f 74 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20  ot shown in the 
0560: 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 20 69 73  example above is
0570: 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
0580: 61 6c 73 6f 20 0a 5b 46 54 53 35 20 43 52 45 41  also .[FTS5 CREA
0590: 54 45 20 54 41 42 4c 45 20 4f 70 74 69 6f 6e 73  TE TABLE Options
05a0: 20 7c 20 76 61 72 69 6f 75 73 20 6f 70 74 69 6f   | various optio
05b0: 6e 73 5d 20 74 68 61 74 20 6d 61 79 20 62 65 20  ns] that may be 
05c0: 70 72 6f 76 69 64 65 64 20 74 6f 20 46 54 53 35  provided to FTS5
05d0: 20 61 73 0a 70 61 72 74 20 6f 66 20 74 68 65 20   as.part of the 
05e0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
05f0: 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 74  ABLE statement t
0600: 6f 20 63 6f 6e 66 69 67 75 72 65 20 76 61 72 69  o configure vari
0610: 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 74  ous aspects of t
0620: 68 65 0a 6e 65 77 20 74 61 62 6c 65 2e 20 54 68  he.new table. Th
0630: 65 73 65 20 6d 61 79 20 62 65 20 75 73 65 64 20  ese may be used 
0640: 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 77 61  to modify the wa
0650: 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 46  y in which the F
0660: 54 53 35 20 74 61 62 6c 65 20 65 78 74 72 61 63  TS5 table extrac
0670: 74 73 0a 74 65 72 6d 73 20 66 72 6f 6d 20 64 6f  ts.terms from do
0680: 63 75 6d 65 6e 74 73 20 61 6e 64 20 71 75 65 72  cuments and quer
0690: 69 65 73 2c 20 74 6f 20 63 72 65 61 74 65 20 65  ies, to create e
06a0: 78 74 72 61 20 69 6e 64 65 78 65 73 20 6f 6e 20  xtra indexes on 
06b0: 64 69 73 6b 20 74 6f 20 73 70 65 65 64 20 75 70  disk to speed up
06c0: 0a 70 72 65 66 69 78 20 71 75 65 72 69 65 73 2c  .prefix queries,
06d0: 20 6f 72 20 74 6f 20 63 72 65 61 74 65 20 61 6e   or to create an
06e0: 20 46 54 53 35 20 74 61 62 6c 65 20 74 68 61 74   FTS5 table that
06f0: 20 61 63 74 73 20 61 73 20 61 6e 20 69 6e 64 65   acts as an inde
0700: 78 20 6f 6e 20 63 6f 6e 74 65 6e 74 0a 73 74 6f  x on content.sto
0710: 72 65 64 20 65 6c 73 65 77 68 65 72 65 2e 0a 0a  red elsewhere...
0720: 3c 70 3e 4f 6e 63 65 20 70 6f 70 75 6c 61 74 65  <p>Once populate
0730: 64 2c 20 74 68 65 72 65 20 61 72 65 20 74 68 72  d, there are thr
0740: 65 65 20 77 61 79 73 20 74 6f 20 65 78 65 63 75  ee ways to execu
0750: 74 65 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 71  te a full-text q
0760: 75 65 72 79 20 61 67 61 69 6e 73 74 0a 74 68 65  uery against.the
0770: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 61 6e 20   contents of an 
0780: 46 54 53 35 20 74 61 62 6c 65 3a 0a 0a 3c 75 6c  FTS5 table:..<ul
0790: 3e 3c 6c 69 3e 20 55 73 69 6e 67 20 61 20 4d 41  ><li> Using a MA
07a0: 54 43 48 20 6f 70 65 72 61 74 6f 72 20 69 6e 20  TCH operator in 
07b0: 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
07c0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
07d0: 74 65 6d 65 6e 74 2c 20 6f 72 0a 20 20 20 20 3c  tement, or.    <
07e0: 6c 69 3e 20 55 73 69 6e 67 20 61 6e 20 65 71 75  li> Using an equ
07f0: 61 6c 73 20 28 22 3d 22 29 20 6f 70 65 72 61 74  als ("=") operat
0800: 6f 72 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  or in the WHERE 
0810: 63 6c 61 75 73 65 20 6f 66 20 61 20 53 45 4c 45  clause of a SELE
0820: 43 54 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  CT statement, or
0830: 0a 20 20 20 20 3c 6c 69 3e 20 75 73 69 6e 67 20  .    <li> using 
0840: 74 68 65 20 5b 74 61 62 6c 65 2d 76 61 6c 75 65  the [table-value
0850: 64 20 66 75 6e 63 74 69 6f 6e 5d 20 73 79 6e 74  d function] synt
0860: 61 78 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 49 66  ax..</ul>..<p>If
0870: 20 75 73 69 6e 67 20 74 68 65 20 4d 41 54 43 48   using the MATCH
0880: 20 6f 72 20 3d 20 6f 70 65 72 61 74 6f 72 73 2c   or = operators,
0890: 20 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 20   the expression 
08a0: 74 6f 20 74 68 65 20 6c 65 66 74 20 6f 66 20 74  to the left of t
08b0: 68 65 20 4d 41 54 43 48 0a 20 20 20 6f 70 65 72  he MATCH.   oper
08c0: 61 74 6f 72 20 6d 75 73 74 20 62 65 20 74 68 65  ator must be the
08d0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 46 54 53   name of the FTS
08e0: 35 20 74 61 62 6c 65 2e 20 54 68 65 20 65 78 70  5 table. The exp
08f0: 72 65 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 72  ression on the r
0900: 69 67 68 74 0a 20 20 20 6d 75 73 74 20 62 65 20  ight.   must be 
0910: 61 20 74 65 78 74 20 76 61 6c 75 65 20 73 70 65  a text value spe
0920: 63 69 66 79 69 6e 67 20 74 68 65 20 74 65 72 6d  cifying the term
0930: 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 2e 20   to search for. 
0940: 46 6f 72 20 74 68 65 20 74 61 62 6c 65 2d 76 61  For the table-va
0950: 6c 75 65 64 0a 20 20 20 66 75 6e 63 74 69 6f 6e  lued.   function
0960: 20 73 79 6e 74 61 78 2c 20 74 68 65 20 74 65 72   syntax, the ter
0970: 6d 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  m to search for 
0980: 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
0990: 74 68 65 20 66 69 72 73 74 20 74 61 62 6c 65 20  the first table 
09a0: 61 72 67 75 6d 65 6e 74 2e 0a 20 20 20 46 6f 72  argument..   For
09b0: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
09c0: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51  block>.  <i>-- Q
09d0: 75 65 72 79 20 66 6f 72 20 61 6c 6c 20 72 6f 77  uery for all row
09e0: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
09f0: 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 69 6e 73  t least once ins
0a00: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 65 72  tance of the ter
0a10: 6d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 66  m</i>.  <i>-- "f
0a20: 74 73 35 22 20 28 69 6e 20 61 6e 79 20 63 6f 6c  ts5" (in any col
0a30: 75 6d 6e 29 2e 20 54 68 65 20 66 6f 6c 6c 6f 77  umn). The follow
0a40: 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 69 65  ing three querie
0a50: 73 20 61 72 65 20 65 71 75 69 76 61 6c 65 6e 74  s are equivalent
0a60: 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a  .</i>.  SELECT *
0a70: 20 46 52 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52   FROM email WHER
0a80: 45 20 65 6d 61 69 6c 20 4d 41 54 43 48 20 27 66  E email MATCH 'f
0a90: 74 73 35 27 3b 0a 20 20 53 45 4c 45 43 54 20 2a  ts5';.  SELECT *
0aa0: 20 46 52 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52   FROM email WHER
0ab0: 45 20 65 6d 61 69 6c 20 3d 20 27 66 74 73 35 27  E email = 'fts5'
0ac0: 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  ;.  SELECT * FRO
0ad0: 4d 20 65 6d 61 69 6c 28 27 66 74 73 35 27 29 3b  M email('fts5');
0ae0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
0af0: 70 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 46  p> By default, F
0b00: 54 53 35 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  TS5 full-text se
0b10: 61 72 63 68 65 73 20 61 72 65 20 63 61 73 65 2d  arches are case-
0b20: 69 6e 64 65 70 65 6e 64 65 6e 74 2e 20 4c 69 6b  independent. Lik
0b30: 65 20 61 6e 79 20 6f 74 68 65 72 0a 53 51 4c 20  e any other.SQL 
0b40: 71 75 65 72 79 20 74 68 61 74 20 64 6f 65 73 20  query that does 
0b50: 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 6e 20 4f  not contain an O
0b60: 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
0b70: 74 68 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76  the example abov
0b80: 65 20 72 65 74 75 72 6e 73 0a 72 65 73 75 6c 74  e returns.result
0b90: 73 20 69 6e 20 61 6e 20 61 72 62 69 74 72 61 72  s in an arbitrar
0ba0: 79 20 6f 72 64 65 72 2e 20 54 6f 20 73 6f 72 74  y order. To sort
0bb0: 20 72 65 73 75 6c 74 73 20 62 79 20 72 65 6c 65   results by rele
0bc0: 76 61 6e 63 65 20 28 6d 6f 73 74 20 74 6f 20 6c  vance (most to l
0bd0: 65 61 73 74 0a 72 65 6c 65 76 61 6e 74 29 2c 20  east.relevant), 
0be0: 61 6e 20 4f 52 44 45 52 20 42 59 20 6d 61 79 20  an ORDER BY may 
0bf0: 62 65 20 61 64 64 65 64 20 74 6f 20 61 20 66 75  be added to a fu
0c00: 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 20 61 73  ll-text query as
0c10: 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65   follows:..<code
0c20: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51  block>.  <i>-- Q
0c30: 75 65 72 79 20 66 6f 72 20 61 6c 6c 20 72 6f 77  uery for all row
0c40: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
0c50: 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 69 6e 73  t least once ins
0c60: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 65 72  tance of the ter
0c70: 6d 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 66  m</i>.  <i>-- "f
0c80: 74 73 35 22 20 28 69 6e 20 61 6e 79 20 63 6f 6c  ts5" (in any col
0c90: 75 6d 6e 29 2e 20 52 65 74 75 72 6e 20 72 65 73  umn). Return res
0ca0: 75 6c 74 73 20 69 6e 20 6f 72 64 65 72 20 66 72  ults in order fr
0cb0: 6f 6d 20 62 65 73 74 20 74 6f 20 77 6f 72 73 74  om best to worst
0cc0: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6d 61 74  </i>.  <i>-- mat
0cd0: 63 68 2e 20 20 3c 2f 69 3e 0a 20 20 53 45 4c 45  ch.  </i>.  SELE
0ce0: 43 54 20 2a 20 46 52 4f 4d 20 65 6d 61 69 6c 20  CT * FROM email 
0cf0: 57 48 45 52 45 20 65 6d 61 69 6c 20 4d 41 54 43  WHERE email MATC
0d00: 48 20 27 66 74 73 35 27 20 4f 52 44 45 52 20 42  H 'fts5' ORDER B
0d10: 59 20 72 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62 6c  Y rank;.</codebl
0d20: 6f 63 6b 3e 0a 0a 3c 70 3e 20 41 73 20 77 65 6c  ock>..<p> As wel
0d30: 6c 20 61 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20  l as the column 
0d40: 76 61 6c 75 65 73 20 61 6e 64 20 72 6f 77 69 64  values and rowid
0d50: 20 6f 66 20 61 20 6d 61 74 63 68 69 6e 67 20 72   of a matching r
0d60: 6f 77 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ow, an applicati
0d70: 6f 6e 0a 6d 61 79 20 75 73 65 20 5b 46 54 53 35  on.may use [FTS5
0d80: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
0d90: 69 6f 6e 73 5d 20 74 6f 20 72 65 74 72 69 65 76  ions] to retriev
0da0: 65 20 65 78 74 72 61 20 69 6e 66 6f 72 6d 61 74  e extra informat
0db0: 69 6f 6e 20 72 65 67 61 72 64 69 6e 67 0a 74 68  ion regarding.th
0dc0: 65 20 6d 61 74 63 68 65 64 20 72 6f 77 2e 20 46  e matched row. F
0dd0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
0de0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
0df0: 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
0e00: 20 72 65 74 72 69 65 76 65 0a 61 20 63 6f 70 79   retrieve.a copy
0e10: 20 6f 66 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c   of a column val
0e20: 75 65 20 66 6f 72 20 61 20 6d 61 74 63 68 65 64  ue for a matched
0e30: 20 72 6f 77 20 77 69 74 68 20 61 6c 6c 20 69 6e   row with all in
0e40: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 65 20 6d  stances of the m
0e50: 61 74 63 68 65 64 0a 74 65 72 6d 20 73 75 72 72  atched.term surr
0e60: 6f 75 6e 64 65 64 20 62 79 20 68 74 6d 6c 20 26  ounded by html &
0e70: 6c 74 3b 62 26 67 74 3b 26 6c 74 3b 2f 62 26 67  lt;b&gt;&lt;/b&g
0e80: 74 3b 20 74 61 67 73 2e 20 41 75 78 69 6c 69 61  t; tags. Auxilia
0e90: 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ry functions are
0ea0: 0a 69 6e 76 6f 6b 65 64 20 69 6e 20 74 68 65 20  .invoked in the 
0eb0: 73 61 6d 65 20 77 61 79 20 61 73 20 53 51 4c 69  same way as SQLi
0ec0: 74 65 20 5b 63 6f 72 65 66 75 6e 63 20 7c 20 73  te [corefunc | s
0ed0: 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 5d  calar functions]
0ee0: 2c 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  , except that th
0ef0: 65 20 6e 61 6d 65 0a 6f 66 20 74 68 65 20 46 54  e name.of the FT
0f00: 53 35 20 74 61 62 6c 65 20 69 73 20 73 70 65 63  S5 table is spec
0f10: 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
0f20: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 46 6f 72  st argument. For
0f30: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
0f40: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51  block>.  <i>-- Q
0f50: 75 65 72 79 20 66 6f 72 20 72 6f 77 73 20 74 68  uery for rows th
0f60: 61 74 20 6d 61 74 63 68 20 22 66 74 73 35 22 2e  at match "fts5".
0f70: 20 52 65 74 75 72 6e 20 61 20 63 6f 70 79 20 6f   Return a copy o
0f80: 66 20 74 68 65 20 22 62 6f 64 79 22 20 63 6f 6c  f the "body" col
0f90: 75 6d 6e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  umn</i>.  <i>-- 
0fa0: 6f 66 20 65 61 63 68 20 72 6f 77 20 77 69 74 68  of each row with
0fb0: 20 74 68 65 20 6d 61 74 63 68 65 73 20 73 75 72   the matches sur
0fc0: 72 6f 75 6e 64 65 64 20 62 79 20 26 6c 74 3b 62  rounded by &lt;b
0fd0: 26 67 74 3b 26 6c 74 3b 2f 62 26 67 74 3b 20 74  &gt;&lt;/b&gt; t
0fe0: 61 67 73 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43  ags.</i>.  SELEC
0ff0: 54 20 68 69 67 68 6c 69 67 68 74 28 65 6d 61 69  T highlight(emai
1000: 6c 2c 20 32 2c 20 27 26 6c 74 3b 62 26 67 74 3b  l, 2, '&lt;b&gt;
1010: 27 2c 20 27 26 6c 74 3b 2f 62 26 67 74 3b 27 29  ', '&lt;/b&gt;')
1020: 20 46 52 4f 4d 20 65 6d 61 69 6c 28 27 66 74 73   FROM email('fts
1030: 35 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  5');.</codeblock
1040: 3e 0a 0a 3c 70 3e 41 20 64 65 73 63 72 69 70 74  >..<p>A descript
1050: 69 6f 6e 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ion of the avail
1060: 61 62 6c 65 20 61 75 78 69 6c 69 61 72 79 20 66  able auxiliary f
1070: 75 6e 63 74 69 6f 6e 73 2c 20 61 6e 64 20 6d 6f  unctions, and mo
1080: 72 65 20 64 65 74 61 69 6c 73 0a 72 65 67 61 72  re details.regar
1090: 64 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ding configurati
10a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
10b0: 6c 20 22 72 61 6e 6b 22 20 63 6f 6c 75 6d 6e 2c  l "rank" column,
10c0: 20 61 72 65 20 0a 5b 46 54 53 35 20 61 75 78 69   are .[FTS5 auxi
10d0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  liary functions 
10e0: 7c 20 61 76 61 69 6c 61 62 6c 65 20 62 65 6c 6f  | available belo
10f0: 77 5d 2e 20 5b 46 54 53 35 20 63 75 73 74 6f 6d  w]. [FTS5 custom
1100: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
1110: 69 6f 6e 73 7c 0a 43 75 73 74 6f 6d 20 61 75 78  ions|.Custom aux
1120: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  iliary functions
1130: 5d 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 69 6d  ] may also be im
1140: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 20 61  plemented in C a
1150: 6e 64 20 72 65 67 69 73 74 65 72 65 64 20 77 69  nd registered wi
1160: 74 68 0a 46 54 53 35 2c 20 6a 75 73 74 20 61 73  th.FTS5, just as
1170: 20 63 75 73 74 6f 6d 20 53 51 4c 20 66 75 6e 63   custom SQL func
1180: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 72 65 67  tions may be reg
1190: 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
11a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a 0a 3c   SQLite core...<
11b0: 70 3e 20 41 73 20 77 65 6c 6c 20 61 73 20 73 65  p> As well as se
11c0: 61 72 63 68 69 6e 67 20 66 6f 72 20 61 6c 6c 20  arching for all 
11d0: 72 6f 77 73 20 74 68 61 74 20 63 6f 6e 74 61 69  rows that contai
11e0: 6e 20 61 20 74 65 72 6d 2c 20 46 54 53 35 20 61  n a term, FTS5 a
11f0: 6c 6c 6f 77 73 20 0a 74 68 65 20 75 73 65 72 20  llows .the user 
1200: 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 72 6f  to search for ro
1210: 77 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 3a  ws that contain:
1220: 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 61 6e  ..<ul>.  <li> an
1230: 79 20 74 65 72 6d 73 20 74 68 61 74 20 62 65 67  y terms that beg
1240: 69 6e 20 77 69 74 68 20 61 20 73 70 65 63 69 66  in with a specif
1250: 69 65 64 20 70 72 65 66 69 78 2c 0a 20 20 3c 6c  ied prefix,.  <l
1260: 69 3e 20 22 70 68 72 61 73 65 73 22 20 2d 20 73  i> "phrases" - s
1270: 65 71 75 65 6e 63 65 73 20 6f 66 20 74 65 72 6d  equences of term
1280: 73 20 6f 72 20 70 72 65 66 69 78 20 74 65 72 6d  s or prefix term
1290: 73 20 74 68 61 74 20 6d 75 73 74 20 66 65 61 74  s that must feat
12a0: 75 72 65 20 69 6e 20 61 0a 20 20 20 20 20 20 20  ure in a.       
12b0: 64 6f 63 75 6d 65 6e 74 20 66 6f 72 20 69 74 20  document for it 
12c0: 74 6f 20 6d 61 74 63 68 20 74 68 65 20 71 75 65  to match the que
12d0: 72 79 2c 20 0a 20 20 3c 6c 69 3e 20 73 65 74 73  ry, .  <li> sets
12e0: 20 6f 66 20 74 65 72 6d 73 2c 20 70 72 65 66 69   of terms, prefi
12f0: 78 20 74 65 72 6d 73 20 6f 72 20 70 68 72 61 73  x terms or phras
1300: 65 73 20 74 68 61 74 20 61 70 70 65 61 72 20 77  es that appear w
1310: 69 74 68 69 6e 20 61 20 73 70 65 63 69 66 69 65  ithin a specifie
1320: 64 0a 20 20 20 20 20 20 20 70 72 6f 78 69 6d 69  d.       proximi
1330: 74 79 20 6f 66 20 65 61 63 68 20 6f 74 68 65 72  ty of each other
1340: 20 28 74 68 65 73 65 20 61 72 65 20 63 61 6c 6c   (these are call
1350: 65 64 20 22 4e 45 41 52 20 71 75 65 72 69 65 73  ed "NEAR queries
1360: 22 29 2c 20 6f 72 0a 20 20 3c 6c 69 3e 20 62 6f  "), or.  <li> bo
1370: 6f 6c 65 61 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  olean combinatio
1380: 6e 73 20 6f 66 20 61 6e 79 20 6f 66 20 74 68 65  ns of any of the
1390: 20 61 62 6f 76 65 2e 0a 3c 2f 75 6c 3e 0a 0a 3c   above..</ul>..<
13a0: 70 3e 20 53 75 63 68 20 61 64 76 61 6e 63 65 64  p> Such advanced
13b0: 20 73 65 61 72 63 68 65 73 20 61 72 65 20 72 65   searches are re
13c0: 71 75 65 73 74 65 64 20 62 79 20 70 72 6f 76 69  quested by provi
13d0: 64 69 6e 67 20 61 20 6d 6f 72 65 20 63 6f 6d 70  ding a more comp
13e0: 6c 69 63 61 74 65 64 20 0a 46 54 53 35 20 71 75  licated .FTS5 qu
13f0: 65 72 79 20 73 74 72 69 6e 67 20 61 73 20 74 68  ery string as th
1400: 65 20 74 65 78 74 20 74 6f 20 74 68 65 20 72 69  e text to the ri
1410: 67 68 74 20 6f 66 20 74 68 65 20 4d 41 54 43 48  ght of the MATCH
1420: 20 6f 70 65 72 61 74 6f 72 20 28 6f 72 20 3d 0a   operator (or =.
1430: 6f 70 65 72 61 74 6f 72 2c 20 6f 72 20 61 73 20  operator, or as 
1440: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1450: 6e 74 20 74 6f 20 61 20 74 61 62 6c 65 2d 76 61  nt to a table-va
1460: 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 20 73 79  lued function sy
1470: 6e 74 61 78 29 2e 20 54 68 65 20 0a 66 75 6c 6c  ntax). The .full
1480: 20 71 75 65 72 79 20 73 79 6e 74 61 78 20 69 73   query syntax is
1490: 20 5b 46 54 53 35 20 71 75 65 72 79 20 73 79 6e   [FTS5 query syn
14a0: 74 61 78 20 7c 20 64 65 73 63 72 69 62 65 64 20  tax | described 
14b0: 68 65 72 65 5d 2e 0a 0a 3c 68 31 20 74 61 67 73  here]...<h1 tags
14c0: 3d 22 46 54 53 35 20 62 75 69 6c 64 69 6e 67 22  ="FTS5 building"
14d0: 3e 43 6f 6d 70 69 6c 69 6e 67 20 61 6e 64 20 55  >Compiling and U
14e0: 73 69 6e 67 20 46 54 53 35 3c 2f 68 31 3e 0a 0a  sing FTS5</h1>..
14f0: 3c 68 32 3e 42 75 69 6c 64 69 6e 67 20 46 54 53  <h2>Building FTS
1500: 35 20 61 73 20 70 61 72 74 20 6f 66 20 53 51 4c  5 as part of SQL
1510: 69 74 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 41 73 20  ite</h2>..<p>As 
1520: 6f 66 20 5b 76 65 72 73 69 6f 6e 20 33 2e 39 2e  of [version 3.9.
1530: 30 5d 2c 20 46 54 53 35 20 69 73 20 69 6e 63 6c  0], FTS5 is incl
1540: 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
1550: 74 68 65 20 53 51 4c 69 74 65 20 5b 61 6d 61 6c  the SQLite [amal
1560: 67 61 6d 61 74 69 6f 6e 5d 2e 0a 49 74 20 69 73  gamation]..It is
1570: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1580: 61 75 6c 74 2e 20 49 66 20 75 73 69 6e 67 20 74  ault. If using t
1590: 68 65 20 74 77 6f 20 61 75 74 6f 63 6f 6e 66 20  he two autoconf 
15a0: 62 75 69 6c 64 20 73 79 73 74 65 6d 2c 20 69 74  build system, it
15b0: 20 69 73 0a 65 6e 61 62 6c 65 64 20 62 79 20 73   is.enabled by s
15c0: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 22 2d  pecifying the "-
15d0: 2d 65 6e 61 62 6c 65 2d 66 74 73 35 22 20 6f 70  -enable-fts5" op
15e0: 74 69 6f 6e 20 77 68 65 6e 20 72 75 6e 6e 69 6e  tion when runnin
15f0: 67 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 0a  g the configure.
1600: 73 63 72 69 70 74 2e 20 0a 0a 3c 70 3e 4f 72 2c  script. ..<p>Or,
1610: 20 69 66 20 73 71 6c 69 74 65 33 2e 63 20 69 73   if sqlite3.c is
1620: 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1630: 73 6f 6d 65 20 6f 74 68 65 72 20 62 75 69 6c 64  some other build
1640: 20 73 79 73 74 65 6d 2c 20 62 79 20 61 72 72 61   system, by arra
1650: 6e 67 69 6e 67 20 66 6f 72 0a 74 68 65 20 53 51  nging for.the SQ
1660: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 46 54 53 35  LITE_ENABLE_FTS5
1670: 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 73   pre-processor s
1680: 79 6d 62 6f 6c 20 74 6f 20 62 65 20 64 65 66 69  ymbol to be defi
1690: 6e 65 64 2e 0a 0a 3c 68 32 3e 42 75 69 6c 64 69  ned...<h2>Buildi
16a0: 6e 67 20 61 20 4c 6f 61 64 61 62 6c 65 20 45 78  ng a Loadable Ex
16b0: 74 65 6e 73 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70  tension</h2>..<p
16c0: 3e 41 6c 74 65 72 6e 61 74 69 76 65 6c 79 2c 20  >Alternatively, 
16d0: 46 54 53 35 20 6d 61 79 20 62 65 20 62 75 69 6c  FTS5 may be buil
16e0: 74 20 61 73 20 61 20 6c 6f 61 64 61 62 6c 65 20  t as a loadable 
16f0: 65 78 74 65 6e 73 69 6f 6e 2e 0a 0a 3c 70 3e 54  extension...<p>T
1700: 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 46 54 53  he canonical FTS
1710: 35 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  5 source code co
1720: 6e 73 69 73 74 73 20 6f 66 20 61 20 73 65 72 69  nsists of a seri
1730: 65 73 20 6f 66 20 2a 2e 63 20 61 6e 64 20 6f 74  es of *.c and ot
1740: 68 65 72 20 66 69 6c 65 73 0a 69 6e 20 74 68 65  her files.in the
1750: 20 22 65 78 74 2f 66 74 73 35 22 20 64 69 72 65   "ext/fts5" dire
1760: 63 74 6f 72 79 20 6f 66 20 74 68 65 20 53 51 4c  ctory of the SQL
1770: 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
1780: 20 41 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73   A build process
1790: 20 72 65 64 75 63 65 73 0a 74 68 69 73 20 74 6f   reduces.this to
17a0: 20 6a 75 73 74 20 74 77 6f 20 66 69 6c 65 73 20   just two files 
17b0: 2d 20 22 66 74 73 35 2e 63 22 20 61 6e 64 20 22  - "fts5.c" and "
17c0: 66 74 73 35 2e 68 22 20 2d 20 77 68 69 63 68 20  fts5.h" - which 
17d0: 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 62  may be used to b
17e0: 75 69 6c 64 20 61 6e 0a 53 51 4c 69 74 65 20 6c  uild an.SQLite l
17f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
1800: 6e 2e 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20  n...<ol>.  <li> 
1810: 4f 62 74 61 69 6e 20 74 68 65 20 6c 61 74 65 73  Obtain the lates
1820: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 20 66 72  t SQLite code fr
1830: 6f 6d 20 66 6f 73 73 69 6c 2e 0a 20 20 3c 6c 69  om fossil..  <li
1840: 3e 20 43 72 65 61 74 65 20 61 20 4d 61 6b 65 66  > Create a Makef
1850: 69 6c 65 20 61 73 20 64 65 73 63 72 69 62 65 64  ile as described
1860: 20 69 6e 20 5b 48 6f 77 20 54 6f 20 43 6f 6d 70   in [How To Comp
1870: 69 6c 65 20 53 51 4c 69 74 65 5d 2e 0a 20 20 3c  ile SQLite]..  <
1880: 6c 69 3e 20 42 75 69 6c 64 20 74 68 65 20 22 66  li> Build the "f
1890: 74 73 35 2e 63 22 20 74 61 72 67 65 74 2e 20 57  ts5.c" target. W
18a0: 68 69 63 68 20 61 6c 73 6f 20 63 72 65 61 74 65  hich also create
18b0: 73 20 66 74 73 35 2e 68 2e 0a 3c 2f 6f 6c 3e 0a  s fts5.h..</ol>.
18c0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 24  .<codeblock>.  $
18d0: 20 77 67 65 74 20 2d 63 20 68 74 74 70 3a 2f 2f   wget -c http://
18e0: 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73  www.sqlite.org/s
18f0: 72 63 2f 74 61 72 62 61 6c 6c 2f 53 51 4c 69 74  rc/tarball/SQLit
1900: 65 2d 74 72 75 6e 6b 2e 74 67 7a 3f 75 75 69 64  e-trunk.tgz?uuid
1910: 3d 74 72 75 6e 6b 20 2d 4f 20 53 51 4c 69 74 65  =trunk -O SQLite
1920: 2d 74 72 75 6e 6b 2e 74 67 7a 0a 20 20 2e 2e 2e  -trunk.tgz.  ...
1930: 2e 20 6f 75 74 70 75 74 20 2e 2e 2e 0a 20 20 24  . output ....  $
1940: 20 74 61 72 20 2d 78 7a 66 20 53 51 4c 69 74 65   tar -xzf SQLite
1950: 2d 74 72 75 6e 6b 2e 74 67 7a 0a 20 20 24 20 63  -trunk.tgz.  $ c
1960: 64 20 53 51 4c 69 74 65 2d 74 72 75 6e 6b 0a 20  d SQLite-trunk. 
1970: 20 24 20 2e 2f 63 6f 6e 66 69 67 75 72 65 20 26   $ ./configure &
1980: 26 20 6d 61 6b 65 20 66 74 73 35 2e 63 0a 20 20  & make fts5.c.  
1990: 2e 2e 2e 20 6c 6f 74 73 20 6f 66 20 6f 75 74 70  ... lots of outp
19a0: 75 74 20 2e 2e 2e 0a 20 20 24 20 6c 73 20 66 74  ut ....  $ ls ft
19b0: 73 35 2e 26 23 39 31 3b 63 68 5d 0a 20 20 66 74  s5.&#91;ch].  ft
19c0: 73 35 2e 63 20 20 20 20 20 20 20 20 66 74 73 35  s5.c        fts5
19d0: 2e 68 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  .h.</codeblock>.
19e0: 0a 3c 70 3e 0a 20 20 54 68 65 20 63 6f 64 65 20  .<p>.  The code 
19f0: 69 6e 20 22 66 74 73 35 2e 63 22 20 6d 61 79 20  in "fts5.c" may 
1a00: 74 68 65 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64  then be compiled
1a10: 20 69 6e 74 6f 20 61 20 6c 6f 61 64 61 62 6c 65   into a loadable
1a20: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 72 0a 20 20   extension or.  
1a30: 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
1a40: 64 20 69 6e 74 6f 20 61 6e 20 61 70 70 6c 69 63  d into an applic
1a50: 61 74 69 6f 6e 20 61 73 20 64 65 73 63 72 69 62  ation as describ
1a60: 65 64 20 69 6e 20 0a 20 20 5b 43 6f 6d 70 69 6c  ed in .  [Compil
1a70: 69 6e 67 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  ing Loadable Ext
1a80: 65 6e 73 69 6f 6e 73 5d 2e 20 54 68 65 72 65 20  ensions]. There 
1a90: 61 72 65 20 74 77 6f 20 65 6e 74 72 79 20 70 6f  are two entry po
1aa0: 69 6e 74 73 20 64 65 66 69 6e 65 64 2c 20 62 6f  ints defined, bo
1ab0: 74 68 0a 20 20 6f 66 20 77 68 69 63 68 20 64 6f  th.  of which do
1ac0: 20 74 68 65 20 73 61 6d 65 20 74 68 69 6e 67 3a   the same thing:
1ad0: 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 73 71  ..<ul>.  <li> sq
1ae0: 6c 69 74 65 33 5f 66 74 73 5f 69 6e 69 74 0a 20  lite3_fts_init. 
1af0: 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 66 74   <li> sqlite3_ft
1b00: 73 35 5f 69 6e 69 74 0a 3c 2f 75 6c 3e 0a 0a 3c  s5_init.</ul>..<
1b10: 70 3e 0a 20 20 54 68 65 20 6f 74 68 65 72 20 66  p>.  The other f
1b20: 69 6c 65 2c 20 22 66 74 73 35 2e 68 22 2c 20 69  ile, "fts5.h", i
1b30: 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
1b40: 6f 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 46 54  o compile the FT
1b50: 53 35 20 65 78 74 65 6e 73 69 6f 6e 2e 20 0a 20  S5 extension. . 
1b60: 20 49 74 20 69 73 20 75 73 65 64 20 62 79 20 61   It is used by a
1b70: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1b80: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 45 78 74 65   implement [Exte
1b90: 6e 64 69 6e 67 20 46 54 53 35 20 7c 20 63 75 73  nding FTS5 | cus
1ba0: 74 6f 6d 20 46 54 53 35 20 74 6f 6b 65 6e 69 7a  tom FTS5 tokeniz
1bb0: 65 72 73 20 6f 72 20 61 75 78 69 6c 69 61 72 79  ers or auxiliary
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 68   functions]...<h
1bd0: 31 20 74 61 67 73 3d 22 46 54 53 35 20 71 75 65  1 tags="FTS5 que
1be0: 72 79 20 73 79 6e 74 61 78 22 3e 46 75 6c 6c 2d  ry syntax">Full-
1bf0: 74 65 78 74 20 51 75 65 72 79 20 53 79 6e 74 61  text Query Synta
1c00: 78 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 54 68 65 20  x</h1>..<p>.The 
1c10: 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f 63 6b 20  following block 
1c20: 63 6f 6e 74 61 69 6e 73 20 61 20 73 75 6d 6d 61  contains a summa
1c30: 72 79 20 6f 66 20 74 68 65 20 46 54 53 20 71 75  ry of the FTS qu
1c40: 65 72 79 20 73 79 6e 74 61 78 20 69 6e 20 42 4e  ery syntax in BN
1c50: 46 20 66 6f 72 6d 2e 0a 41 20 64 65 74 61 69 6c  F form..A detail
1c60: 65 64 20 65 78 70 6c 61 6e 61 74 69 6f 6e 20 66  ed explanation f
1c70: 6f 6c 6c 6f 77 73 2e 0a 0a 3c 63 6f 64 65 62 6c  ollows...<codebl
1c80: 6f 63 6b 3e 0a 26 6c 74 3b 70 68 72 61 73 65 26  ock>.&lt;phrase&
1c90: 67 74 3b 20 20 20 20 3a 3d 20 73 74 72 69 6e 67  gt;    := string
1ca0: 20 26 23 39 31 3b 2a 5d 0a 26 6c 74 3b 70 68 72   &#91;*].&lt;phr
1cb0: 61 73 65 26 67 74 3b 20 20 20 20 3a 3d 20 26 6c  ase&gt;    := &l
1cc0: 74 3b 70 68 72 61 73 65 26 67 74 3b 20 2b 20 26  t;phrase&gt; + &
1cd0: 6c 74 3b 70 68 72 61 73 65 26 67 74 3b 0a 26 6c  lt;phrase&gt;.&l
1ce0: 74 3b 6e 65 61 72 67 72 6f 75 70 26 67 74 3b 20  t;neargroup&gt; 
1cf0: 3a 3d 20 4e 45 41 52 20 28 20 26 6c 74 3b 70 68  := NEAR ( &lt;ph
1d00: 72 61 73 65 26 67 74 3b 20 26 6c 74 3b 70 68 72  rase&gt; &lt;phr
1d10: 61 73 65 26 67 74 3b 20 2e 2e 2e 20 26 23 39 31  ase&gt; ... &#91
1d20: 3b 2c 20 4e 5d 20 29 0a 26 6c 74 3b 71 75 65 72  ;, N] ).&lt;quer
1d30: 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 23 39  y&gt;     := &#9
1d40: 31 3b 26 6c 74 3b 63 6f 6c 73 70 65 63 26 67 74  1;&lt;colspec&gt
1d50: 3b 20 3a 5d 20 26 6c 74 3b 70 68 72 61 73 65 26  ; :] &lt;phrase&
1d60: 67 74 3b 0a 26 6c 74 3b 71 75 65 72 79 26 67 74  gt;.&lt;query&gt
1d70: 3b 20 20 20 20 20 3a 3d 20 26 23 39 31 3b 26 6c  ;     := &#91;&l
1d80: 74 3b 63 6f 6c 73 70 65 63 26 67 74 3b 20 3a 5d  t;colspec&gt; :]
1d90: 20 26 6c 74 3b 6e 65 61 72 67 72 6f 75 70 26 67   &lt;neargroup&g
1da0: 74 3b 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b  t;.&lt;query&gt;
1db0: 20 20 20 20 20 3a 3d 20 28 20 26 6c 74 3b 71 75       := ( &lt;qu
1dc0: 65 72 79 26 67 74 3b 20 29 0a 26 6c 74 3b 71 75  ery&gt; ).&lt;qu
1dd0: 65 72 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26  ery&gt;     := &
1de0: 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 41 4e 44  lt;query&gt; AND
1df0: 20 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 0a 26   &lt;query&gt;.&
1e00: 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 20 20 20  lt;query&gt;    
1e10: 20 3a 3d 20 26 6c 74 3b 71 75 65 72 79 26 67 74   := &lt;query&gt
1e20: 3b 20 4f 52 20 26 6c 74 3b 71 75 65 72 79 26 67  ; OR &lt;query&g
1e30: 74 3b 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b  t;.&lt;query&gt;
1e40: 20 20 20 20 20 3a 3d 20 26 6c 74 3b 71 75 65 72       := &lt;quer
1e50: 79 26 67 74 3b 20 4e 4f 54 20 26 6c 74 3b 71 75  y&gt; NOT &lt;qu
1e60: 65 72 79 26 67 74 3b 0a 26 6c 74 3b 63 6f 6c 73  ery&gt;.&lt;cols
1e70: 70 65 63 26 67 74 3b 20 20 20 3a 3d 20 63 6f 6c  pec&gt;   := col
1e80: 6e 61 6d 65 0a 26 6c 74 3b 63 6f 6c 73 70 65 63  name.&lt;colspec
1e90: 26 67 74 3b 20 20 20 3a 3d 20 7b 20 63 6f 6c 6e  &gt;   := { coln
1ea0: 61 6d 65 31 20 63 6f 6c 6e 61 6d 65 32 20 2e 2e  ame1 colname2 ..
1eb0: 2e 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  . }.</codeblock>
1ec0: 0a 0a 3c 70 3e 0a 57 69 74 68 69 6e 20 61 6e 20  ..<p>.Within an 
1ed0: 46 54 53 20 65 78 70 72 65 73 73 69 6f 6e 20 61  FTS expression a
1ee0: 20 3c 62 3e 73 74 72 69 6e 67 3c 2f 62 3e 20 6d   <b>string</b> m
1ef0: 61 79 20 62 65 20 73 70 65 63 69 66 69 65 64 20  ay be specified 
1f00: 69 6e 20 6f 6e 65 20 6f 66 20 74 77 6f 20 77 61  in one of two wa
1f10: 79 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e  ys:..<ul>.  <li>
1f20: 20 3c 70 3e 42 79 20 65 6e 63 6c 6f 73 69 6e 67   <p>By enclosing
1f30: 20 69 74 20 69 6e 20 64 6f 75 62 6c 65 20 71 75   it in double qu
1f40: 6f 74 65 73 20 28 22 29 2e 20 57 69 74 68 69 6e  otes ("). Within
1f50: 20 61 20 73 74 72 69 6e 67 2c 20 61 6e 79 20 65   a string, any e
1f60: 6d 62 65 64 64 65 64 0a 20 20 20 20 20 20 20 64  mbedded.       d
1f70: 6f 75 62 6c 65 20 71 75 6f 74 65 20 63 68 61 72  ouble quote char
1f80: 61 63 74 65 72 73 20 6d 61 79 20 62 65 20 65 73  acters may be es
1f90: 63 61 70 65 64 20 53 51 4c 2d 73 74 79 6c 65 20  caped SQL-style 
1fa0: 2d 20 62 79 20 61 64 64 69 6e 67 20 61 20 73 65  - by adding a se
1fb0: 63 6f 6e 64 0a 20 20 20 20 20 20 20 64 6f 75 62  cond.       doub
1fc0: 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1fd0: 65 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 41  er...  <li> <p>A
1fe0: 73 20 61 6e 20 46 54 53 35 20 62 61 72 65 77 6f  s an FTS5 barewo
1ff0: 72 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 22  rd that is not "
2000: 41 4e 44 22 2c 20 22 4f 52 22 20 6f 72 20 22 4e  AND", "OR" or "N
2010: 4f 54 22 20 28 63 61 73 65 20 73 65 6e 73 69 74  OT" (case sensit
2020: 69 76 65 29 2e 20 0a 20 20 20 20 20 20 20 41 6e  ive). .       An
2030: 20 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 69   FTS5 bareword i
2040: 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 6f 6e  s a string of on
2050: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6e 73 65 63  e or more consec
2060: 75 74 69 76 65 20 63 68 61 72 61 63 74 65 72 73  utive characters
2070: 20 74 68 61 74 0a 20 20 20 20 20 20 20 61 72 65   that.       are
2080: 20 61 6c 6c 20 65 69 74 68 65 72 3a 0a 20 20 20   all either:.   
2090: 20 20 20 20 0a 20 20 20 20 20 20 20 3c 75 6c 3e      .       <ul>
20a0: 0a 20 20 20 20 20 20 20 20 20 3c 6c 69 3e 20 4e  .         <li> N
20b0: 6f 6e 2d 41 53 43 49 49 20 72 61 6e 67 65 20 63  on-ASCII range c
20c0: 68 61 72 61 63 74 65 72 73 20 28 69 2e 65 2e 20  haracters (i.e. 
20d0: 75 6e 69 63 6f 64 65 20 63 6f 64 65 70 6f 69 6e  unicode codepoin
20e0: 74 73 20 67 72 65 61 74 65 72 20 0a 20 20 20 20  ts greater .    
20f0: 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 31            than 1
2100: 32 37 29 2c 20 6f 72 20 0a 20 20 20 20 20 20 20  27), or .       
2110: 20 20 3c 6c 69 3e 20 4f 6e 65 20 6f 66 20 74 68    <li> One of th
2120: 65 20 35 32 20 75 70 70 65 72 20 61 6e 64 20 6c  e 52 upper and l
2130: 6f 77 65 72 20 63 61 73 65 20 41 53 43 49 49 20  ower case ASCII 
2140: 63 68 61 72 61 63 74 65 72 73 2c 20 6f 72 0a 20  characters, or. 
2150: 20 20 20 20 20 20 20 20 3c 6c 69 3e 20 4f 6e 65          <li> One
2160: 20 6f 66 20 74 68 65 20 31 30 20 64 65 63 69 6d   of the 10 decim
2170: 61 6c 20 64 69 67 69 74 20 41 53 43 49 49 20 63  al digit ASCII c
2180: 68 61 72 61 63 74 65 72 73 2c 20 6f 72 0a 20 20  haracters, or.  
2190: 20 20 20 20 20 20 20 3c 6c 69 3e 20 54 68 65 20         <li> The 
21a0: 75 6e 64 65 72 73 63 6f 72 65 20 63 68 61 72 61  underscore chara
21b0: 63 74 65 72 20 28 75 6e 69 63 6f 64 65 20 63 6f  cter (unicode co
21c0: 64 65 70 6f 69 6e 74 20 39 36 29 2e 0a 20 20 20  depoint 96)..   
21d0: 20 20 20 20 20 20 3c 6c 69 3e 20 54 68 65 20 73        <li> The s
21e0: 75 62 73 74 69 74 75 74 65 20 63 68 61 72 61 63  ubstitute charac
21f0: 74 65 72 20 28 75 6e 69 63 6f 64 65 20 63 6f 64  ter (unicode cod
2200: 65 70 6f 69 6e 74 20 32 36 29 2e 0a 20 20 20 20  epoint 26)..    
2210: 20 20 20 3c 2f 75 6c 3e 0a 0a 20 20 20 20 20 20     </ul>..      
2220: 20 53 74 72 69 6e 67 73 20 74 68 61 74 20 69 6e   Strings that in
2230: 63 6c 75 64 65 20 61 6e 79 20 6f 74 68 65 72 20  clude any other 
2240: 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
2250: 62 65 20 71 75 6f 74 65 64 2e 20 43 68 61 72 61  be quoted. Chara
2260: 63 74 65 72 73 0a 20 20 20 20 20 20 20 74 68 61  cters.       tha
2270: 74 20 61 72 65 20 6e 6f 74 20 63 75 72 72 65 6e  t are not curren
2280: 74 6c 79 20 61 6c 6c 6f 77 65 64 20 69 6e 20 62  tly allowed in b
2290: 61 72 65 77 6f 72 64 73 2c 20 61 72 65 20 6e 6f  arewords, are no
22a0: 74 20 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  t quote characte
22b0: 72 73 20 61 6e 64 0a 20 20 20 20 20 20 20 64 6f  rs and.       do
22c0: 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 73   not currently s
22d0: 65 72 76 65 20 61 6e 79 20 73 70 65 63 69 61 6c  erve any special
22e0: 20 70 75 72 70 6f 73 65 20 69 6e 20 46 54 53 35   purpose in FTS5
22f0: 20 71 75 65 72 79 20 65 78 70 72 65 73 73 69 6f   query expressio
2300: 6e 73 20 6d 61 79 0a 20 20 20 20 20 20 20 61 74  ns may.       at
2310: 20 73 6f 6d 65 20 70 6f 69 6e 74 20 69 6e 20 74   some point in t
2320: 68 65 20 66 75 74 75 72 65 20 62 65 20 61 6c 6c  he future be all
2330: 6f 77 65 64 20 69 6e 20 62 61 72 65 77 6f 72 64  owed in bareword
2340: 73 20 6f 72 20 75 73 65 64 20 74 6f 20 69 6d 70  s or used to imp
2350: 6c 65 6d 65 6e 74 0a 20 20 20 20 20 20 20 6e 65  lement.       ne
2360: 77 20 71 75 65 72 79 20 66 75 6e 63 74 69 6f 6e  w query function
2370: 61 6c 69 74 79 2e 20 54 68 69 73 20 6d 65 61 6e  ality. This mean
2380: 73 20 74 68 61 74 20 71 75 65 72 69 65 73 20 74  s that queries t
2390: 68 61 74 20 61 72 65 20 63 75 72 72 65 6e 74 6c  hat are currentl
23a0: 79 0a 20 20 20 20 20 20 20 73 79 6e 74 61 78 20  y.       syntax 
23b0: 65 72 72 6f 72 73 20 62 65 63 61 75 73 65 20 74  errors because t
23c0: 68 65 79 20 69 6e 63 6c 75 64 65 20 73 75 63 68  hey include such
23d0: 20 61 20 63 68 61 72 61 63 74 65 72 20 6f 75 74   a character out
23e0: 73 69 64 65 20 6f 66 20 61 20 71 75 6f 74 65 64  side of a quoted
23f0: 0a 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 6d  .       string m
2400: 61 79 20 62 65 20 69 6e 74 65 72 70 72 65 74 65  ay be interprete
2410: 64 20 64 69 66 66 65 72 65 6e 74 6c 79 20 62 79  d differently by
2420: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 76 65 72   some future ver
2430: 73 69 6f 6e 20 6f 66 20 46 54 53 35 2e 0a 3c 2f  sion of FTS5..</
2440: 75 6c 3e 0a 0a 3c 70 3e 0a 46 54 53 20 71 75 65  ul>..<p>.FTS que
2450: 72 69 65 73 20 61 72 65 20 6d 61 64 65 20 75 70  ries are made up
2460: 20 6f 66 20 3c 62 3e 70 68 72 61 73 65 73 3c 2f   of <b>phrases</
2470: 62 3e 2e 20 41 20 70 68 72 61 73 65 20 69 73 20  b>. A phrase is 
2480: 61 6e 20 6f 72 64 65 72 65 64 20 6c 69 73 74 20  an ordered list 
2490: 6f 66 20 0a 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  of .one or more 
24a0: 74 6f 6b 65 6e 73 2e 20 41 20 73 74 72 69 6e 67  tokens. A string
24b0: 20 69 73 20 74 72 61 6e 73 66 6f 72 6d 65 64 20   is transformed 
24c0: 69 6e 74 6f 20 61 20 70 68 72 61 73 65 20 62 79  into a phrase by
24d0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 74   passing it to.t
24e0: 68 65 20 46 54 53 20 74 61 62 6c 65 20 74 6f 6b  he FTS table tok
24f0: 65 6e 69 7a 65 72 2e 20 54 77 6f 20 70 68 72 61  enizer. Two phra
2500: 73 65 73 20 63 61 6e 20 62 65 20 63 6f 6e 63 61  ses can be conca
2510: 74 65 6e 61 74 65 64 20 69 6e 74 6f 20 61 20 73  tenated into a s
2520: 69 6e 67 6c 65 20 0a 6c 61 72 67 65 20 70 68 72  ingle .large phr
2530: 61 73 65 20 75 73 69 6e 67 20 74 68 65 20 22 2b  ase using the "+
2540: 22 20 6f 70 65 72 61 74 6f 72 2e 20 46 6f 72 20  " operator. For 
2550: 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 69 6e  example, assumin
2560: 67 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 0a  g the tokenizer.
2570: 6d 6f 64 75 6c 65 20 62 65 69 6e 67 20 75 73 65  module being use
2580: 64 20 74 6f 6b 65 6e 69 7a 65 73 20 74 68 65 20  d tokenizes the 
2590: 69 6e 70 75 74 20 22 6f 6e 65 2e 74 77 6f 2e 74  input "one.two.t
25a0: 68 72 65 65 22 20 74 6f 20 74 68 72 65 65 20 73  hree" to three s
25b0: 65 70 61 72 61 74 65 0a 74 6f 6b 65 6e 73 2c 20  eparate.tokens, 
25c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
25d0: 72 65 65 20 71 75 65 72 69 65 73 20 61 6c 6c 20  ree queries all 
25e0: 73 70 65 63 69 66 79 20 74 68 65 20 73 61 6d 65  specify the same
25f0: 20 70 68 72 61 73 65 3a 0a 0a 3c 63 6f 64 65 62   phrase:..<codeb
2600: 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  lock>.  ... MATC
2610: 48 20 27 22 6f 6e 65 20 74 77 6f 20 74 68 72 65  H '"one two thre
2620: 65 22 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  e"'.  ... MATCH 
2630: 27 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68 72  'one + two + thr
2640: 65 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  ee'.  ... MATCH 
2650: 27 22 6f 6e 65 20 74 77 6f 22 20 2b 20 74 68 72  '"one two" + thr
2660: 65 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  ee'.  ... MATCH 
2670: 27 6f 6e 65 2e 74 77 6f 2e 74 68 72 65 65 27 0a  'one.two.three'.
2680: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
2690: 3e 0a 41 20 70 68 72 61 73 65 20 6d 61 74 63 68  >.A phrase match
26a0: 65 73 20 61 20 64 6f 63 75 6d 65 6e 74 20 69 66  es a document if
26b0: 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 63 6f   the document co
26c0: 6e 74 61 69 6e 73 20 61 74 20 6c 65 61 73 74 20  ntains at least 
26d0: 6f 6e 65 20 73 75 62 2d 73 65 71 75 65 6e 63 65  one sub-sequence
26e0: 0a 6f 66 20 74 6f 6b 65 6e 73 20 74 68 61 74 20  .of tokens that 
26f0: 6d 61 74 63 68 65 73 20 74 68 65 20 73 65 71 75  matches the sequ
2700: 65 6e 63 65 20 6f 66 20 74 6f 6b 65 6e 73 20 74  ence of tokens t
2710: 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65 20  hat make up the 
2720: 70 68 72 61 73 65 2e 0a 0a 3c 70 3e 0a 49 66 20  phrase...<p>.If 
2730: 61 20 22 2a 22 20 63 68 61 72 61 63 74 65 72 20  a "*" character 
2740: 66 6f 6c 6c 6f 77 73 20 61 20 73 74 72 69 6e 67  follows a string
2750: 20 77 69 74 68 69 6e 20 61 6e 20 46 54 53 20 65   within an FTS e
2760: 78 70 72 65 73 73 69 6f 6e 2c 20 74 68 65 6e 20  xpression, then 
2770: 74 68 65 20 66 69 6e 61 6c 0a 74 6f 6b 65 6e 20  the final.token 
2780: 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
2790: 68 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 72  he string is mar
27a0: 6b 65 64 20 61 73 20 61 20 3c 62 3e 70 72 65 66  ked as a <b>pref
27b0: 69 78 20 74 6f 6b 65 6e 3c 2f 62 3e 2e 20 41 73  ix token</b>. As
27c0: 20 79 6f 75 0a 6d 69 67 68 74 20 65 78 70 65 63   you.might expec
27d0: 74 2c 20 61 20 70 72 65 66 69 78 20 74 6f 6b 65  t, a prefix toke
27e0: 6e 20 6d 61 74 63 68 65 73 20 61 6e 79 20 64 6f  n matches any do
27f0: 63 75 6d 65 6e 74 20 74 6f 6b 65 6e 20 6f 66 20  cument token of 
2800: 77 68 69 63 68 20 69 74 20 69 73 20 61 20 0a 70  which it is a .p
2810: 72 65 66 69 78 2e 20 46 6f 72 20 65 78 61 6d 70  refix. For examp
2820: 6c 65 2c 20 74 68 65 20 66 69 72 73 74 20 74 77  le, the first tw
2830: 6f 20 71 75 65 72 69 65 73 20 69 6e 20 74 68 65  o queries in the
2840: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f 63 6b   following block
2850: 20 77 69 6c 6c 20 6d 61 74 63 68 0a 61 6e 79 20   will match.any 
2860: 64 6f 63 75 6d 65 6e 74 20 74 68 61 74 20 63 6f  document that co
2870: 6e 74 61 69 6e 73 20 74 68 65 20 74 6f 6b 65 6e  ntains the token
2880: 20 22 6f 6e 65 22 20 69 6d 6d 65 64 69 61 74 65   "one" immediate
2890: 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74  ly followed by t
28a0: 68 65 20 74 6f 6b 65 6e 0a 22 74 77 6f 22 20 61  he token."two" a
28b0: 6e 64 20 74 68 65 6e 20 61 6e 79 20 74 6f 6b 65  nd then any toke
28c0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 77 69  n that begins wi
28d0: 74 68 20 22 74 68 72 22 2e 0a 0a 3c 63 6f 64 65  th "thr"...<code
28e0: 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54  block>.  ... MAT
28f0: 43 48 20 27 22 6f 6e 65 20 74 77 6f 20 74 68 72  CH '"one two thr
2900: 22 20 2a 20 27 0a 20 20 2e 2e 2e 20 4d 41 54 43  " * '.  ... MATC
2910: 48 20 27 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74  H 'one + two + t
2920: 68 72 2a 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48  hr*'.  ... MATCH
2930: 20 27 22 6f 6e 65 20 74 77 6f 20 74 68 72 2a 22   '"one two thr*"
2940: 27 20 20 20 20 20 20 3c 62 3e 2d 2d 20 4d 61 79  '      <b>-- May
2950: 20 6e 6f 74 20 77 6f 72 6b 20 61 73 20 65 78 70   not work as exp
2960: 65 63 74 65 64 21 3c 2f 62 3e 0a 3c 2f 63 6f 64  ected!</b>.</cod
2970: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20  eblock>..<p>The 
2980: 66 69 6e 61 6c 20 71 75 65 72 79 20 69 6e 20 74  final query in t
2990: 68 65 20 62 6c 6f 63 6b 20 61 62 6f 76 65 20 6d  he block above m
29a0: 61 79 20 6e 6f 74 20 77 6f 72 6b 20 61 73 20 65  ay not work as e
29b0: 78 70 65 63 74 65 64 2e 20 42 65 63 61 75 73 65  xpected. Because
29c0: 20 74 68 65 0a 22 2a 22 20 63 68 61 72 61 63 74   the."*" charact
29d0: 65 72 20 69 73 20 69 6e 73 69 64 65 20 74 68 65  er is inside the
29e0: 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 2c 20   double-quotes, 
29f0: 69 74 20 77 69 6c 6c 20 62 65 20 70 61 73 73 65  it will be passe
2a00: 64 20 74 6f 20 74 68 65 20 74 6f 6b 65 6e 69 7a  d to the tokeniz
2a10: 65 72 2c 0a 77 68 69 63 68 20 77 69 6c 6c 20 6c  er,.which will l
2a20: 69 6b 65 6c 79 20 64 69 73 63 61 72 64 20 69 74  ikely discard it
2a30: 20 28 6f 72 20 70 65 72 68 61 70 73 2c 20 64 65   (or perhaps, de
2a40: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 73  pending on the s
2a50: 70 65 63 69 66 69 63 20 74 6f 6b 65 6e 69 7a 65  pecific tokenize
2a60: 72 0a 69 6e 20 75 73 65 2c 20 69 6e 63 6c 75 64  r.in use, includ
2a70: 65 20 69 74 20 61 73 20 70 61 72 74 20 6f 66 20  e it as part of 
2a80: 74 68 65 20 66 69 6e 61 6c 20 74 6f 6b 65 6e 29  the final token)
2a90: 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 63 6f   instead of reco
2aa0: 67 6e 69 7a 69 6e 67 20 69 74 20 61 73 0a 61 20  gnizing it as.a 
2ab0: 73 70 65 63 69 61 6c 20 46 54 53 20 63 68 61 72  special FTS char
2ac0: 61 63 74 65 72 2e 0a 0a 3c 70 3e 54 77 6f 20 6f  acter...<p>Two o
2ad0: 72 20 6d 6f 72 65 20 70 68 72 61 73 65 73 20 6d  r more phrases m
2ae0: 61 79 20 62 65 20 67 72 6f 75 70 65 64 20 69 6e  ay be grouped in
2af0: 74 6f 20 61 20 3c 62 3e 4e 45 41 52 20 67 72 6f  to a <b>NEAR gro
2b00: 75 70 3c 2f 62 3e 2e 20 41 20 4e 45 41 52 20 67  up</b>. A NEAR g
2b10: 72 6f 75 70 0a 69 73 20 73 70 65 63 69 66 69 65  roup.is specifie
2b20: 64 20 62 79 20 74 68 65 20 74 6f 6b 65 6e 20 22  d by the token "
2b30: 4e 45 41 52 22 20 28 63 61 73 65 20 73 65 6e 73  NEAR" (case sens
2b40: 69 74 69 76 65 29 20 66 6f 6c 6c 6f 77 65 64 20  itive) followed 
2b50: 62 79 20 61 6e 20 6f 70 65 6e 0a 70 61 72 65 6e  by an open.paren
2b60: 74 68 65 73 69 73 20 63 68 61 72 61 63 74 65 72  thesis character
2b70: 2c 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74 77  , followed by tw
2b80: 6f 20 6f 72 20 6d 6f 72 65 20 77 68 69 74 65 73  o or more whites
2b90: 70 61 63 65 20 73 65 70 61 72 61 74 65 64 20 70  pace separated p
2ba0: 68 72 61 73 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  hrases, optional
2bb0: 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  ly followed by a
2bc0: 20 63 6f 6d 6d 61 20 61 6e 64 20 74 68 65 20 6e   comma and the n
2bd0: 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
2be0: 20 3c 69 3e 4e 3c 2f 69 3e 2c 20 66 6f 6c 6c 6f   <i>N</i>, follo
2bf0: 77 65 64 20 62 79 0a 61 20 63 6c 6f 73 65 20 70  wed by.a close p
2c00: 61 72 65 6e 74 68 65 73 69 73 2e 20 46 6f 72 20  arenthesis. For 
2c10: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
2c20: 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  lock>.  ... MATC
2c30: 48 20 27 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f  H 'NEAR("one two
2c40: 22 20 22 74 68 72 65 65 20 66 6f 75 72 22 2c 20  " "three four", 
2c50: 31 30 29 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48  10)'.  ... MATCH
2c60: 20 27 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22   'NEAR("one two"
2c70: 20 74 68 72 2a 20 2b 20 66 6f 75 72 29 27 0a 3c   thr* + four)'.<
2c80: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
2c90: 49 66 20 6e 6f 20 3c 69 3e 4e 3c 2f 69 3e 20 70  If no <i>N</i> p
2ca0: 61 72 61 6d 65 74 65 72 20 69 73 20 73 75 70 70  arameter is supp
2cb0: 6c 69 65 64 2c 20 69 74 20 64 65 66 61 75 6c 74  lied, it default
2cc0: 73 20 74 6f 20 31 30 2e 20 41 20 4e 45 41 52 20  s to 10. A NEAR 
2cd0: 67 72 6f 75 70 0a 6d 61 74 63 68 65 73 20 61 20  group.matches a 
2ce0: 64 6f 63 75 6d 65 6e 74 20 69 66 20 74 68 65 20  document if the 
2cf0: 64 6f 63 75 6d 65 6e 74 20 63 6f 6e 74 61 69 6e  document contain
2d00: 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 63  s at least one c
2d10: 6c 75 6d 70 20 6f 66 20 74 6f 6b 65 6e 73 20 74  lump of tokens t
2d20: 68 61 74 3a 20 0a 0a 3c 6f 6c 3e 20 0a 20 20 3c  hat: ..<ol> .  <
2d30: 6c 69 3e 20 63 6f 6e 74 61 69 6e 73 20 61 74 20  li> contains at 
2d40: 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e  least one instan
2d50: 63 65 20 6f 66 20 65 61 63 68 20 70 68 72 61 73  ce of each phras
2d60: 65 2c 20 61 6e 64 20 0a 20 20 3c 6c 69 3e 20 66  e, and .  <li> f
2d70: 6f 72 20 77 68 69 63 68 20 74 68 65 20 6e 75 6d  or which the num
2d80: 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 62 65  ber of tokens be
2d90: 74 77 65 65 6e 20 74 68 65 20 65 6e 64 20 6f 66  tween the end of
2da0: 20 74 68 65 20 66 69 72 73 74 20 70 68 72 61 73   the first phras
2db0: 65 20 0a 20 20 20 20 20 20 20 61 6e 64 20 74 68  e .       and th
2dc0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74  e beginning of t
2dd0: 68 65 20 6c 61 73 74 20 70 68 72 61 73 65 20 69  he last phrase i
2de0: 6e 20 74 68 65 20 63 6c 75 6d 70 20 69 73 20 6c  n the clump is l
2df0: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
2e00: 6c 20 74 6f 20 3c 69 3e 4e 3c 2f 69 3e 2e 0a 3c  l to <i>N</i>..<
2e10: 2f 6f 6c 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61  /ol>..<p>For exa
2e20: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
2e30: 6b 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  k>.  CREATE VIRT
2e40: 55 41 4c 20 54 41 42 4c 45 20 66 20 55 53 49 4e  UAL TABLE f USIN
2e50: 47 20 66 74 73 35 28 78 29 3b 0a 20 20 49 4e 53  G fts5(x);.  INS
2e60: 45 52 54 20 49 4e 54 4f 20 66 28 72 6f 77 69 64  ERT INTO f(rowid
2e70: 2c 20 78 29 20 56 41 4c 55 45 53 28 31 2c 20 27  , x) VALUES(1, '
2e80: 41 20 42 20 43 20 44 20 78 20 78 20 78 20 45 20  A B C D x x x E 
2e90: 46 20 78 27 29 3b 0a 0a 20 20 2e 2e 2e 20 4d 41  F x');..  ... MA
2ea0: 54 43 48 20 27 4e 45 41 52 28 65 20 64 2c 20 34  TCH 'NEAR(e d, 4
2eb0: 29 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  )';             
2ec0: 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 4d           <i>-- M
2ed0: 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e  atches!</i>.  ..
2ee0: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 65 20  . MATCH 'NEAR(e 
2ef0: 64 2c 20 33 29 27 3b 20 20 20 20 20 20 20 20 20  d, 3)';         
2f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
2f10: 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a  -- Matches!</i>.
2f20: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41    ... MATCH 'NEA
2f30: 52 28 65 20 64 2c 20 32 29 27 3b 20 20 20 20 20  R(e d, 2)';     
2f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f50: 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20   <i>-- Does not 
2f60: 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e  match!</i>..  ..
2f70: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 63  . MATCH 'NEAR("c
2f80: 20 64 22 20 22 65 20 66 22 2c 20 33 29 27 3b 20   d" "e f", 3)'; 
2f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
2fa0: 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a  -- Matches!</i>.
2fb0: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41    ... MATCH 'NEA
2fc0: 52 28 22 63 22 20 20 20 22 65 20 66 22 2c 20 33  R("c"   "e f", 3
2fd0: 29 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  )';             
2fe0: 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20   <i>-- Does not 
2ff0: 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e  match!</i>..  ..
3000: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 61 20  . MATCH 'NEAR(a 
3010: 64 20 65 2c 20 36 29 27 3b 20 20 20 20 20 20 20  d e, 6)';       
3020: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
3030: 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a  -- Matches!</i>.
3040: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41    ... MATCH 'NEA
3050: 52 28 61 20 64 20 65 2c 20 35 29 27 3b 20 20 20  R(a d e, 5)';   
3060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3070: 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20   <i>-- Does not 
3080: 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e  match!</i>..  ..
3090: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 61  . MATCH 'NEAR("a
30a0: 20 62 20 63 20 64 22 20 22 62 20 63 22 20 22 65   b c d" "b c" "e
30b0: 20 66 22 2c 20 34 29 27 3b 20 20 20 20 3c 69 3e   f", 4)';    <i>
30c0: 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a  -- Matches!</i>.
30d0: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41    ... MATCH 'NEA
30e0: 52 28 22 61 20 62 20 63 20 64 22 20 22 62 20 63  R("a b c d" "b c
30f0: 22 20 22 65 20 66 22 2c 20 33 29 27 3b 20 20 20  " "e f", 3)';   
3100: 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20   <i>-- Does not 
3110: 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 3c 2f 63 6f  match!</i>..</co
3120: 64 65 62 6c 6f 63 6b 3e 0a 0a 0a 3c 70 3e 0a 41  deblock>...<p>.A
3130: 20 73 69 6e 67 6c 65 20 70 68 72 61 73 65 20 6f   single phrase o
3140: 72 20 4e 45 41 52 20 67 72 6f 75 70 20 6d 61 79  r NEAR group may
3150: 20 62 65 20 72 65 73 74 72 69 63 74 65 64 20 74   be restricted t
3160: 6f 20 6d 61 74 63 68 69 6e 67 20 74 65 78 74 20  o matching text 
3170: 77 69 74 68 69 6e 20 61 0a 73 70 65 63 69 66 69  within a.specifi
3180: 65 64 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  ed column of the
3190: 20 46 54 53 20 74 61 62 6c 65 20 62 79 20 70 72   FTS table by pr
31a0: 65 66 69 78 69 6e 67 20 69 74 20 77 69 74 68 20  efixing it with 
31b0: 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20  the column name 
31c0: 0a 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 63  .followed by a c
31d0: 6f 6c 6f 6e 20 63 68 61 72 61 63 74 65 72 2e 20  olon character. 
31e0: 4f 72 20 74 6f 20 61 20 73 65 74 20 6f 66 20 63  Or to a set of c
31f0: 6f 6c 75 6d 6e 73 20 62 79 20 70 72 65 66 69 78  olumns by prefix
3200: 69 6e 67 20 69 74 0a 77 69 74 68 20 61 20 77 68  ing it.with a wh
3210: 69 74 65 73 70 61 63 65 20 73 65 70 61 72 61 74  itespace separat
3220: 65 64 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d  ed list of colum
3230: 6e 20 6e 61 6d 65 73 20 65 6e 63 6c 6f 73 65 64  n names enclosed
3240: 20 69 6e 20 70 61 72 65 6e 74 68 65 73 69 73 0a   in parenthesis.
3250: 28 22 63 75 72 6c 79 20 62 72 61 63 6b 65 74 73  ("curly brackets
3260: 22 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  ") followed by a
3270: 20 63 6f 6c 6f 6e 20 63 68 61 72 61 63 74 65 72   colon character
3280: 2e 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 6d  . Column names m
3290: 61 79 20 62 65 20 73 70 65 63 69 66 69 65 64 0a  ay be specified.
32a0: 75 73 69 6e 67 20 65 69 74 68 65 72 20 6f 66 20  using either of 
32b0: 74 68 65 20 74 77 6f 20 66 6f 72 6d 73 20 64 65  the two forms de
32c0: 73 63 72 69 62 65 64 20 66 6f 72 20 73 74 72 69  scribed for stri
32d0: 6e 67 73 20 61 62 6f 76 65 2e 20 55 6e 6c 69 6b  ngs above. Unlik
32e0: 65 20 73 74 72 69 6e 67 73 20 74 68 61 74 0a 61  e strings that.a
32f0: 72 65 20 70 61 72 74 20 6f 66 20 70 68 72 61 73  re part of phras
3300: 65 73 2c 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  es, column names
3310: 20 61 72 65 20 6e 6f 74 20 70 61 73 73 65 64 20   are not passed 
3320: 74 6f 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72  to the tokenizer
3330: 20 6d 6f 64 75 6c 65 2e 0a 43 6f 6c 75 6d 6e 20   module..Column 
3340: 6e 61 6d 65 73 20 61 72 65 20 63 61 73 65 2d 69  names are case-i
3350: 6e 73 65 6e 73 69 74 69 76 65 20 69 6e 20 74 68  nsensitive in th
3360: 65 20 75 73 75 61 6c 20 77 61 79 20 66 6f 72 20  e usual way for 
3370: 53 51 4c 69 74 65 20 63 6f 6c 75 6d 6e 20 6e 61  SQLite column na
3380: 6d 65 73 20 2d 0a 75 70 70 65 72 2f 6c 6f 77 65  mes -.upper/lowe
3390: 72 20 63 61 73 65 20 65 71 75 69 76 61 6c 65 6e  r case equivalen
33a0: 63 65 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64  ce is understood
33b0: 20 66 6f 72 20 41 53 43 49 49 2d 72 61 6e 67 65   for ASCII-range
33c0: 20 63 68 61 72 61 63 74 65 72 73 20 6f 6e 6c 79   characters only
33d0: 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
33e0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 63 6f 6c 6e   ... MATCH 'coln
33f0: 61 6d 65 20 3a 20 4e 45 41 52 28 22 6f 6e 65 20  ame : NEAR("one 
3400: 74 77 6f 22 20 22 74 68 72 65 65 20 66 6f 75 72  two" "three four
3410: 22 2c 20 31 30 29 27 0a 20 20 2e 2e 2e 20 4d 41  ", 10)'.  ... MA
3420: 54 43 48 20 27 22 63 6f 6c 6e 61 6d 65 22 20 3a  TCH '"colname" :
3430: 20 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68 72   one + two + thr
3440: 65 65 27 0a 0a 20 20 2e 2e 2e 20 4d 41 54 43 48  ee'..  ... MATCH
3450: 20 27 7b 63 6f 6c 31 20 63 6f 6c 32 7d 20 3a 20   '{col1 col2} : 
3460: 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22 20 22  NEAR("one two" "
3470: 74 68 72 65 65 20 66 6f 75 72 22 2c 20 31 30 29  three four", 10)
3480: 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 7b  '.  ... MATCH '{
3490: 63 6f 6c 32 20 63 6f 6c 31 20 63 6f 6c 33 7d 20  col2 col1 col3} 
34a0: 3a 20 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68  : one + two + th
34b0: 72 65 65 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ree'.</codeblock
34c0: 3e 0a 0a 3c 70 3e 0a 50 68 72 61 73 65 73 20 61  >..<p>.Phrases a
34d0: 6e 64 20 4e 45 41 52 20 67 72 6f 75 70 73 20 6d  nd NEAR groups m
34e0: 61 79 20 62 65 20 61 72 72 61 6e 67 65 64 20 69  ay be arranged i
34f0: 6e 74 6f 20 65 78 70 72 65 73 73 69 6f 6e 73 20  nto expressions 
3500: 75 73 69 6e 67 20 3c 62 3e 62 6f 6f 6c 65 61 6e  using <b>boolean
3510: 0a 6f 70 65 72 61 74 6f 72 73 3c 2f 62 3e 2e 20  .operators</b>. 
3520: 49 6e 20 6f 72 64 65 72 20 6f 66 20 70 72 65 63  In order of prec
3530: 65 64 65 6e 63 65 2c 20 66 72 6f 6d 20 68 69 67  edence, from hig
3540: 68 65 73 74 20 28 74 69 67 68 74 65 73 74 20 67  hest (tightest g
3550: 72 6f 75 70 69 6e 67 29 20 74 6f 0a 6c 6f 77 65  rouping) to.lowe
3560: 73 74 20 28 6c 6f 6f 73 65 73 74 20 67 72 6f 75  st (loosest grou
3570: 70 69 6e 67 29 2c 20 74 68 65 20 6f 70 65 72 61  ping), the opera
3580: 74 6f 72 73 20 61 72 65 3a 0a 0a 3c 74 61 62 6c  tors are:..<tabl
3590: 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20 3c  e striped=1>.  <
35a0: 74 72 3e 3c 74 68 3e 4f 70 65 72 61 74 6f 72 20  tr><th>Operator 
35b0: 3c 74 68 3e 46 75 6e 63 74 69 6f 6e 0a 0a 20 20  <th>Function..  
35c0: 3c 74 72 3e 3c 74 64 3e 3c 63 6f 64 65 3e 26 6c  <tr><td><code>&l
35d0: 74 3b 71 75 65 72 79 31 26 67 74 3b 20 4e 4f 54  t;query1&gt; NOT
35e0: 20 26 6c 74 3b 71 75 65 72 79 32 26 67 74 3b 3c   &lt;query2&gt;<
35f0: 2f 63 6f 64 65 3e 20 0a 20 20 20 20 20 20 3c 74  /code> .      <t
3600: 64 3e 4d 61 74 63 68 65 73 20 69 66 20 71 75 65  d>Matches if que
3610: 72 79 31 20 6d 61 74 63 68 65 73 20 61 6e 64 20  ry1 matches and 
3620: 71 75 65 72 79 32 20 64 6f 65 73 20 6e 6f 74 20  query2 does not 
3630: 6d 61 74 63 68 2e 0a 0a 20 20 3c 74 72 3e 3c 74  match...  <tr><t
3640: 64 3e 3c 63 6f 64 65 3e 26 6c 74 3b 71 75 65 72  d><code>&lt;quer
3650: 79 31 26 67 74 3b 20 41 4e 44 20 26 6c 74 3b 71  y1&gt; AND &lt;q
3660: 75 65 72 79 32 26 67 74 3b 3c 2f 63 6f 64 65 3e  uery2&gt;</code>
3670: 20 0a 20 20 20 20 20 20 3c 74 64 3e 4d 61 74 63   .      <td>Matc
3680: 68 65 73 20 69 66 20 62 6f 74 68 20 71 75 65 72  hes if both quer
3690: 79 31 20 61 6e 64 20 71 75 65 72 79 32 20 6d 61  y1 and query2 ma
36a0: 74 63 68 2e 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e  tch...  <tr><td>
36b0: 3c 63 6f 64 65 3e 26 6c 74 3b 71 75 65 72 79 31  <code>&lt;query1
36c0: 26 67 74 3b 20 4f 52 20 26 6c 74 3b 71 75 65 72  &gt; OR &lt;quer
36d0: 79 32 26 67 74 3b 3c 2f 63 6f 64 65 3e 20 0a 20  y2&gt;</code> . 
36e0: 20 20 20 20 20 3c 74 64 3e 4d 61 74 63 68 65 73       <td>Matches
36f0: 20 69 66 20 65 69 74 68 65 72 20 71 75 65 72 79   if either query
3700: 31 20 6f 72 20 71 75 65 72 79 32 20 6d 61 74 63  1 or query2 matc
3710: 68 2e 0a 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70  h...</table>..<p
3720: 3e 0a 50 61 72 65 6e 74 68 65 73 69 73 20 6d 61  >.Parenthesis ma
3730: 79 20 62 65 20 75 73 65 64 20 74 6f 20 67 72 6f  y be used to gro
3740: 75 70 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  up expressions i
3750: 6e 20 6f 72 64 65 72 20 74 6f 20 6d 6f 64 69 66  n order to modif
3760: 79 20 6f 70 65 72 61 74 6f 72 0a 70 72 65 63 65  y operator.prece
3770: 64 65 6e 63 65 20 69 6e 20 74 68 65 20 75 73 75  dence in the usu
3780: 61 6c 20 77 61 79 73 2e 20 46 6f 72 20 65 78 61  al ways. For exa
3790: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
37a0: 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 4d 61 74 63 68  k>.  <i>-- Match
37b0: 65 73 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61  es documents tha
37c0: 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61  t contain at lea
37d0: 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63 65 20  st one instance 
37e0: 6f 66 20 65 69 74 68 65 72 20 22 6f 6e 65 22 3c  of either "one"<
37f0: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 72 20 22  /i>.  <i>-- or "
3800: 74 77 6f 22 2c 20 62 75 74 20 64 6f 20 6e 6f 74  two", but do not
3810: 20 63 6f 6e 74 61 69 6e 20 61 6e 79 20 69 6e 73   contain any ins
3820: 74 61 6e 63 65 73 20 6f 66 20 74 6f 6b 65 6e 20  tances of token 
3830: 22 74 68 72 65 65 22 2e 3c 2f 69 3e 0a 20 20 2e  "three".</i>.  .
3840: 2e 2e 20 4d 41 54 43 48 20 27 6f 6e 65 20 4f 52  .. MATCH 'one OR
3850: 20 74 77 6f 20 4e 4f 54 20 74 68 72 65 65 27 0a   two NOT three'.
3860: 0a 20 20 3c 69 3e 2d 2d 20 4d 61 74 63 68 20 61  .  <i>-- Match a
3870: 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61  ll documents tha
3880: 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 74 6f  t contain the to
3890: 6b 65 6e 20 22 74 77 6f 22 20 62 75 74 20 6e 6f  ken "two" but no
38a0: 74 20 22 74 68 72 65 65 22 2c 20 6f 72 3c 2f 69  t "three", or</i
38b0: 3e 0a 20 20 3c 69 3e 2d 2d 20 63 6f 6e 74 61 69  >.  <i>-- contai
38c0: 6e 20 74 68 65 20 74 6f 6b 65 6e 20 22 6f 6e 65  n the token "one
38d0: 22 2e 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54  ".</i>.  ... MAT
38e0: 43 48 20 27 6f 6e 65 20 4f 52 20 28 74 77 6f 20  CH 'one OR (two 
38f0: 4e 4f 54 20 74 68 72 65 65 29 27 0a 3c 2f 63 6f  NOT three)'.</co
3900: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 50 68  deblock>..<p>.Ph
3910: 72 61 73 65 73 20 61 6e 64 20 4e 45 41 52 20 67  rases and NEAR g
3920: 72 6f 75 70 73 20 6d 61 79 20 61 6c 73 6f 20 62  roups may also b
3930: 65 20 63 6f 6e 6e 65 63 74 65 64 20 62 79 20 3c  e connected by <
3940: 62 3e 69 6d 70 6c 69 63 69 74 20 41 4e 44 20 6f  b>implicit AND o
3950: 70 65 72 61 74 6f 72 73 3c 2f 62 3e 2e 0a 46 6f  perators</b>..Fo
3960: 72 20 73 69 6d 70 6c 69 63 69 74 79 2c 20 74 68  r simplicity, th
3970: 65 73 65 20 61 72 65 20 6e 6f 74 20 73 68 6f 77  ese are not show
3980: 6e 20 69 6e 20 74 68 65 20 42 4e 46 20 67 72 61  n in the BNF gra
3990: 6d 6d 61 72 20 61 62 6f 76 65 2e 20 45 73 73 65  mmar above. Esse
39a0: 6e 74 69 61 6c 6c 79 2c 20 61 6e 79 0a 73 65 71  ntially, any.seq
39b0: 75 65 6e 63 65 20 6f 66 20 70 68 72 61 73 65 73  uence of phrases
39c0: 20 6f 72 20 4e 45 41 52 20 67 72 6f 75 70 73 20   or NEAR groups 
39d0: 28 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65  (including those
39e0: 20 72 65 73 74 72 69 63 74 65 64 20 74 6f 20 6d   restricted to m
39f0: 61 74 63 68 69 6e 67 0a 73 70 65 63 69 66 69 65  atching.specifie
3a00: 64 20 63 6f 6c 75 6d 6e 73 29 20 73 65 70 61 72  d columns) separ
3a10: 61 74 65 64 20 6f 6e 6c 79 20 62 79 20 77 68 69  ated only by whi
3a20: 74 65 73 70 61 63 65 20 61 72 65 20 68 61 6e 64  tespace are hand
3a30: 6c 65 64 20 61 73 20 69 66 20 74 68 65 72 65 20  led as if there 
3a40: 77 65 72 65 20 61 6e 0a 69 6d 70 6c 69 63 69 74  were an.implicit
3a50: 20 41 4e 44 20 6f 70 65 72 61 74 6f 72 20 62 65   AND operator be
3a60: 74 77 65 65 6e 20 65 61 63 68 20 70 61 69 72 20  tween each pair 
3a70: 6f 66 20 70 68 72 61 73 65 73 20 6f 72 20 4e 45  of phrases or NE
3a80: 41 52 20 67 72 6f 75 70 73 2e 20 49 6d 70 6c 69  AR groups. Impli
3a90: 63 69 74 0a 41 4e 44 20 6f 70 65 72 61 74 6f 72  cit.AND operator
3aa0: 73 20 61 72 65 20 6e 65 76 65 72 20 69 6e 73 65  s are never inse
3ab0: 72 74 65 64 20 61 66 74 65 72 20 6f 72 20 62 65  rted after or be
3ac0: 66 6f 72 65 20 61 6e 20 65 78 70 72 65 73 73 69  fore an expressi
3ad0: 6f 6e 20 65 6e 63 6c 6f 73 65 64 20 69 6e 0a 70  on enclosed in.p
3ae0: 61 72 65 6e 74 68 65 73 69 73 2e 20 46 6f 72 20  arenthesis. For 
3af0: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
3b00: 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  lock>.  ... MATC
3b10: 48 20 27 6f 6e 65 20 74 77 6f 20 74 68 72 65 65  H 'one two three
3b20: 27 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20  '         <i>-- 
3b30: 27 6f 6e 65 20 41 4e 44 20 74 77 6f 20 41 4e 44  'one AND two AND
3b40: 20 74 68 72 65 65 27 3c 2f 69 3e 0a 20 20 2e 2e   three'</i>.  ..
3b50: 2e 20 4d 41 54 43 48 20 27 74 68 72 65 65 20 22  . MATCH 'three "
3b60: 6f 6e 65 20 74 77 6f 22 27 20 20 20 20 20 20 20  one two"'       
3b70: 3c 69 3e 2d 2d 20 27 74 68 72 65 65 20 41 4e 44  <i>-- 'three AND
3b80: 20 22 6f 6e 65 20 74 77 6f 22 27 3c 2f 69 3e 0a   "one two"'</i>.
3b90: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41    ... MATCH 'NEA
3ba0: 52 28 6f 6e 65 20 74 77 6f 29 20 74 68 72 65 65  R(one two) three
3bb0: 27 20 20 20 3c 69 3e 2d 2d 20 27 4e 45 41 52 28  '   <i>-- 'NEAR(
3bc0: 6f 6e 65 20 74 77 6f 29 20 41 4e 44 20 74 68 72  one two) AND thr
3bd0: 65 65 27 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41  ee'</i>.  ... MA
3be0: 54 43 48 20 27 6f 6e 65 20 4f 52 20 74 77 6f 20  TCH 'one OR two 
3bf0: 74 68 72 65 65 27 20 20 20 20 20 20 3c 69 3e 2d  three'      <i>-
3c00: 2d 20 27 6f 6e 65 20 4f 52 20 74 77 6f 20 41 4e  - 'one OR two AN
3c10: 44 20 74 68 72 65 65 27 3c 2f 69 3e 0a 0a 20 20  D three'</i>..  
3c20: 2e 2e 2e 20 4d 41 54 43 48 20 27 28 6f 6e 65 20  ... MATCH '(one 
3c30: 4f 52 20 74 77 6f 29 20 74 68 72 65 65 27 20 20  OR two) three'  
3c40: 20 20 3c 69 3e 2d 2d 20 53 79 6e 74 61 78 20 65    <i>-- Syntax e
3c50: 72 72 6f 72 21 3c 2f 69 3e 0a 20 20 2e 2e 2e 20  rror!</i>.  ... 
3c60: 4d 41 54 43 48 20 27 66 75 6e 63 28 6f 6e 65 20  MATCH 'func(one 
3c70: 74 77 6f 29 27 20 20 20 20 20 20 20 20 20 3c 69  two)'         <i
3c80: 3e 2d 2d 20 53 79 6e 74 61 78 20 65 72 72 6f 72  >-- Syntax error
3c90: 21 3c 2f 69 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63  !</i>.</codebloc
3ca0: 6b 3e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46 54  k>..<h1 tags="FT
3cb0: 53 35 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  S5 CREATE TABLE 
3cc0: 4f 70 74 69 6f 6e 73 22 3e 46 54 53 35 20 54 61  Options">FTS5 Ta
3cd0: 62 6c 65 20 43 72 65 61 74 69 6f 6e 20 61 6e 64  ble Creation and
3ce0: 20 49 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 3c   Initialization<
3cf0: 2f 68 31 3e 0a 0a 3c 70 3e 45 61 63 68 20 61 72  /h1>..<p>Each ar
3d00: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 64  gument specified
3d10: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 22 43   as part of a "C
3d20: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
3d30: 42 4c 45 20 2e 2e 2e 20 55 53 49 4e 47 20 66 74  BLE ... USING ft
3d40: 73 35 20 0a 2e 2e 2e 22 20 73 74 61 74 65 6d 65  s5 ...." stateme
3d50: 6e 74 20 69 73 20 65 69 74 68 65 72 20 61 20 63  nt is either a c
3d60: 6f 6c 75 6d 6e 20 64 65 63 6c 61 72 61 74 69 6f  olumn declaratio
3d70: 6e 20 6f 72 20 61 20 63 6f 6e 66 69 67 75 72 61  n or a configura
3d80: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 20 41 0a 3c  tion option. A.<
3d90: 62 3e 63 6f 6c 75 6d 6e 20 64 65 63 6c 61 72 61  b>column declara
3da0: 74 69 6f 6e 3c 2f 62 3e 20 63 6f 6e 73 69 73 74  tion</b> consist
3db0: 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s of one or more
3dc0: 20 77 68 69 74 65 73 70 61 63 65 20 73 65 70 61   whitespace sepa
3dd0: 72 61 74 65 64 20 46 54 53 35 0a 62 61 72 65 77  rated FTS5.barew
3de0: 6f 72 64 73 20 6f 72 20 73 74 72 69 6e 67 20 6c  ords or string l
3df0: 69 74 65 72 61 6c 73 20 71 75 6f 74 65 64 20 69  iterals quoted i
3e00: 6e 20 61 6e 79 20 6d 61 6e 6e 65 72 20 61 63 63  n any manner acc
3e10: 65 70 74 61 62 6c 65 20 74 6f 20 53 51 4c 69 74  eptable to SQLit
3e20: 65 2e 0a 0a 3c 70 3e 54 68 65 20 66 69 72 73 74  e...<p>The first
3e30: 20 73 74 72 69 6e 67 20 6f 72 20 62 61 72 65 77   string or barew
3e40: 6f 72 64 20 69 6e 20 61 20 63 6f 6c 75 6d 6e 20  ord in a column 
3e50: 64 65 63 6c 61 72 61 74 69 6f 6e 20 69 73 20 74  declaration is t
3e60: 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 20  he column name. 
3e70: 49 74 0a 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It.is an error t
3e80: 6f 20 61 74 74 65 6d 70 74 20 74 6f 20 6e 61 6d  o attempt to nam
3e90: 65 20 61 6e 20 66 74 73 35 20 74 61 62 6c 65 20  e an fts5 table 
3ea0: 63 6f 6c 75 6d 6e 20 22 72 6f 77 69 64 22 20 6f  column "rowid" o
3eb0: 72 20 22 72 61 6e 6b 22 2c 20 6f 72 20 74 6f 0a  r "rank", or to.
3ec0: 61 73 73 69 67 6e 20 74 68 65 20 73 61 6d 65 20  assign the same 
3ed0: 6e 61 6d 65 20 74 6f 20 61 20 63 6f 6c 75 6d 6e  name to a column
3ee0: 20 61 73 20 69 73 20 75 73 65 64 20 62 79 20 74   as is used by t
3ef0: 68 65 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  he table itself.
3f00: 20 54 68 69 73 20 69 73 20 6e 6f 74 0a 73 75 70   This is not.sup
3f10: 70 6f 72 74 65 64 2e 0a 0a 3c 70 3e 45 61 63 68  ported...<p>Each
3f20: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 72 69   subsequent stri
3f30: 6e 67 20 6f 72 20 62 61 72 65 77 6f 72 64 20 69  ng or bareword i
3f40: 6e 20 61 20 63 6f 6c 75 6d 6e 20 64 65 63 6c 61  n a column decla
3f50: 72 61 74 69 6f 6e 20 69 73 20 61 20 63 6f 6c 75  ration is a colu
3f60: 6d 6e 0a 6f 70 74 69 6f 6e 20 74 68 61 74 20 6d  mn.option that m
3f70: 6f 64 69 66 69 65 73 20 74 68 65 20 62 65 68 61  odifies the beha
3f80: 76 69 6f 75 72 20 6f 66 20 74 68 61 74 20 63 6f  viour of that co
3f90: 6c 75 6d 6e 2e 20 43 6f 6c 75 6d 6e 20 6f 70 74  lumn. Column opt
3fa0: 69 6f 6e 73 20 61 72 65 0a 63 61 73 65 2d 69 6e  ions are.case-in
3fb0: 64 65 70 65 6e 64 65 6e 74 2e 20 55 6e 6c 69 6b  dependent. Unlik
3fc0: 65 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  e the SQLite cor
3fd0: 65 2c 20 46 54 53 35 20 63 6f 6e 73 69 64 65 72  e, FTS5 consider
3fe0: 73 20 75 6e 72 65 63 6f 67 6e 69 7a 65 64 20 63  s unrecognized c
3ff0: 6f 6c 75 6d 6e 0a 6f 70 74 69 6f 6e 73 20 74 6f  olumn.options to
4000: 20 62 65 20 65 72 72 6f 72 73 2e 20 43 75 72 72   be errors. Curr
4010: 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79 20  ently, the only 
4020: 6f 70 74 69 6f 6e 20 72 65 63 6f 67 6e 69 7a 65  option recognize
4030: 64 20 69 73 20 0a 5b 75 6e 69 6e 64 65 78 65 64  d is .[unindexed
4040: 20 7c 20 22 55 4e 49 4e 44 45 58 45 44 22 20 28   | "UNINDEXED" (
4050: 73 65 65 20 62 65 6c 6f 77 29 5d 2e 0a 0a 3c 70  see below)]...<p
4060: 3e 41 20 3c 62 3e 63 6f 6e 66 69 67 75 72 61 74  >A <b>configurat
4070: 69 6f 6e 20 6f 70 74 69 6f 6e 3c 2f 62 3e 20 63  ion option</b> c
4080: 6f 6e 73 69 73 74 73 20 6f 66 20 61 6e 20 46 54  onsists of an FT
4090: 53 35 20 62 61 72 65 77 6f 72 64 20 2d 20 74 68  S5 bareword - th
40a0: 65 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 2d 0a  e option name -.
40b0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e 20 22  followed by an "
40c0: 3d 22 20 63 68 61 72 61 63 74 65 72 2c 20 66 6f  =" character, fo
40d0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 6f 70  llowed by the op
40e0: 74 69 6f 6e 20 76 61 6c 75 65 2e 20 54 68 65 20  tion value. The 
40f0: 6f 70 74 69 6f 6e 20 76 61 6c 75 65 20 69 73 0a  option value is.
4100: 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 20  specified using 
4110: 65 69 74 68 65 72 20 61 20 73 69 6e 67 6c 65 20  either a single 
4120: 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 6f 72  FTS5 bareword or
4130: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
4140: 6c 2c 20 61 67 61 69 6e 20 71 75 6f 74 65 64 0a  l, again quoted.
4150: 69 6e 20 61 6e 79 20 6d 61 6e 6e 65 72 20 61 63  in any manner ac
4160: 63 65 70 74 61 62 6c 65 20 74 6f 20 74 68 65 20  ceptable to the 
4170: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 46 6f 72  SQLite core. For
4180: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
4190: 62 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20  block>.  CREATE 
41a0: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 6d 61  VIRTUAL TABLE ma
41b0: 69 6c 20 55 53 49 4e 47 20 66 74 73 35 28 73 65  il USING fts5(se
41c0: 6e 64 65 72 2c 20 74 69 74 6c 65 2c 20 62 6f 64  nder, title, bod
41d0: 79 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 70  y, tokenize = 'p
41e0: 6f 72 74 65 72 20 61 73 63 69 69 27 29 3b 0a 3c  orter ascii');.<
41f0: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
4200: 20 54 68 65 72 65 20 61 72 65 20 63 75 72 72 65   There are curre
4210: 6e 74 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ntly the followi
4220: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
4230: 20 6f 70 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a   options:..<ul>.
4240: 20 20 3c 6c 69 3e 20 54 68 65 20 22 74 6f 6b 65    <li> The "toke
4250: 6e 69 7a 65 22 20 6f 70 74 69 6f 6e 2c 20 75 73  nize" option, us
4260: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
4270: 61 20 5b 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65  a [FTS5 tokenize
4280: 72 73 20 7c 20 63 75 73 74 6f 6d 20 74 6f 6b 65  rs | custom toke
4290: 6e 69 7a 65 72 5d 2e 0a 20 20 3c 6c 69 3e 20 54  nizer]..  <li> T
42a0: 68 65 20 22 70 72 65 66 69 78 22 20 6f 70 74 69  he "prefix" opti
42b0: 6f 6e 2c 20 75 73 65 64 20 74 6f 20 61 64 64 20  on, used to add 
42c0: 5b 46 54 53 35 20 70 72 65 66 69 78 20 69 6e 64  [FTS5 prefix ind
42d0: 65 78 65 73 20 7c 20 70 72 65 66 69 78 20 69 6e  exes | prefix in
42e0: 64 65 78 65 73 5d 0a 20 20 20 20 20 20 20 74 6f  dexes].       to
42f0: 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65 2e 0a   an FTS5 table..
4300: 20 20 3c 6c 69 3e 20 54 68 65 20 22 63 6f 6e 74    <li> The "cont
4310: 65 6e 74 22 20 6f 70 74 69 6f 6e 2c 20 75 73 65  ent" option, use
4320: 64 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 46 54  d to make the FT
4330: 53 35 20 74 61 62 6c 65 20 61 6e 20 0a 20 20 20  S5 table an .   
4340: 20 20 20 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e      [FTS5 conten
4350: 74 20 6f 70 74 69 6f 6e 20 7c 20 65 78 74 65 72  t option | exter
4360: 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 6f 72 20 63  nal content or c
4370: 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
4380: 5d 2e 0a 20 20 3c 6c 69 3e 20 54 68 65 20 22 63  ]..  <li> The "c
4390: 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 22 20 6f 70  ontent_rowid" op
43a0: 74 69 6f 6e 2c 20 75 73 65 64 20 74 6f 20 73 65  tion, used to se
43b0: 74 20 74 68 65 20 72 6f 77 69 64 20 66 69 65 6c  t the rowid fiel
43c0: 64 20 6f 66 20 61 6e 20 0a 20 20 20 20 20 20 20  d of an .       
43d0: 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c 20 63  [FTS5 external c
43e0: 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20 7c 20  ontent tables | 
43f0: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
4400: 20 74 61 62 6c 65 5d 2e 0a 20 20 3c 6c 69 3e 20   table]..  <li> 
4410: 54 68 65 20 5b 46 54 53 35 20 63 6f 6c 75 6d 6e  The [FTS5 column
4420: 73 69 7a 65 20 6f 70 74 69 6f 6e 20 7c 20 22 63  size option | "c
4430: 6f 6c 75 6d 6e 73 69 7a 65 22 20 6f 70 74 69 6f  olumnsize" optio
4440: 6e 5d 2c 20 75 73 65 64 20 74 6f 20 63 6f 6e 66  n], used to conf
4450: 69 67 75 72 65 0a 20 20 20 20 20 20 20 77 68 65  igure.       whe
4460: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
4470: 73 69 7a 65 20 69 6e 20 74 6f 6b 65 6e 73 20 6f  size in tokens o
4480: 66 20 65 61 63 68 20 76 61 6c 75 65 20 69 6e 20  f each value in 
4490: 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20 69  the FTS5 table i
44a0: 73 0a 20 20 20 20 20 20 20 73 74 6f 72 65 64 20  s.       stored 
44b0: 73 65 70 61 72 61 74 65 6c 79 20 77 69 74 68 69  separately withi
44c0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  n the database..
44d0: 20 20 3c 6c 69 3e 20 54 68 65 20 5b 46 54 53 35    <li> The [FTS5
44e0: 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e 20 7c   detail option |
44f0: 20 22 64 65 74 61 69 6c 22 20 6f 70 74 69 6f 6e   "detail" option
4500: 5d 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  ]. This option m
4510: 61 79 20 62 65 20 75 73 65 64 20 0a 20 20 20 20  ay be used .    
4520: 20 20 20 74 6f 20 72 65 64 75 63 65 20 74 68 65     to reduce the
4530: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 46 54 53   size of the FTS
4540: 20 69 6e 64 65 78 20 6f 6e 20 64 69 73 6b 20 62   index on disk b
4550: 79 20 6f 6d 69 74 74 69 6e 67 20 73 6f 6d 65 20  y omitting some 
4560: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 20 20 20  information.    
4570: 20 20 20 66 72 6f 6d 20 69 74 2e 20 20 0a 3c 2f     from it.  .</
4580: 75 6c 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 75  ul>..<h2 tags="u
4590: 6e 69 6e 64 65 78 65 64 22 3e 54 68 65 20 55 4e  nindexed">The UN
45a0: 49 4e 44 45 58 45 44 20 63 6f 6c 75 6d 6e 20 6f  INDEXED column o
45b0: 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  ption</h2>..<p>T
45c0: 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 63  he contents of c
45d0: 6f 6c 75 6d 6e 73 20 71 75 61 6c 69 66 69 65 64  olumns qualified
45e0: 20 77 69 74 68 20 74 68 65 20 55 4e 49 4e 44 45   with the UNINDE
45f0: 58 45 44 20 63 6f 6c 75 6d 6e 20 6f 70 74 69 6f  XED column optio
4600: 6e 20 61 72 65 20 6e 6f 74 0a 61 64 64 65 64 20  n are not.added 
4610: 74 6f 20 74 68 65 20 46 54 53 20 69 6e 64 65 78  to the FTS index
4620: 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61  . This means tha
4630: 74 20 66 6f 72 20 74 68 65 20 70 75 72 70 6f 73  t for the purpos
4640: 65 73 20 6f 66 20 4d 41 54 43 48 20 71 75 65 72  es of MATCH quer
4650: 69 65 73 20 61 6e 64 0a 5b 46 54 53 35 20 61 75  ies and.[FTS5 au
4660: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
4670: 73 5d 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 20 63  s], the column c
4680: 6f 6e 74 61 69 6e 73 20 6e 6f 20 6d 61 74 63 68  ontains no match
4690: 61 62 6c 65 20 74 6f 6b 65 6e 73 2e 20 0a 0a 3c  able tokens. ..<
46a0: 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  p>For example, t
46b0: 6f 20 61 76 6f 69 64 20 61 64 64 69 6e 67 20 74  o avoid adding t
46c0: 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
46d0: 68 65 20 22 75 75 69 64 22 20 66 69 65 6c 64 20  he "uuid" field 
46e0: 74 6f 20 74 68 65 20 46 54 53 0a 69 6e 64 65 78  to the FTS.index
46f0: 3a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  :.<codeblock>.  
4700: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
4710: 41 42 4c 45 20 63 75 73 74 6f 6d 65 72 73 20 55  ABLE customers U
4720: 53 49 4e 47 20 66 74 73 35 28 6e 61 6d 65 2c 20  SING fts5(name, 
4730: 61 64 64 72 2c 20 75 75 69 64 20 55 4e 49 4e 44  addr, uuid UNIND
4740: 45 58 45 44 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  EXED);.</codeblo
4750: 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46  ck>..<h2 tags="F
4760: 54 53 35 20 70 72 65 66 69 78 20 69 6e 64 65 78  TS5 prefix index
4770: 65 73 22 3e 50 72 65 66 69 78 20 49 6e 64 65 78  es">Prefix Index
4780: 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 42 79 20  es</h2>..<p> By 
4790: 64 65 66 61 75 6c 74 2c 20 46 54 53 35 20 6d 61  default, FTS5 ma
47a0: 69 6e 74 61 69 6e 73 20 61 20 73 69 6e 67 6c 65  intains a single
47b0: 20 69 6e 64 65 78 20 72 65 63 6f 72 64 69 6e 67   index recording
47c0: 20 74 68 65 20 6c 6f 63 61 74 69 6f 6e 20 6f 66   the location of
47d0: 20 65 61 63 68 0a 74 6f 6b 65 6e 20 69 6e 73 74   each.token inst
47e0: 61 6e 63 65 20 77 69 74 68 69 6e 20 74 68 65 20  ance within the 
47f0: 64 6f 63 75 6d 65 6e 74 20 73 65 74 2e 20 54 68  document set. Th
4800: 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 71 75  is means that qu
4810: 65 72 79 69 6e 67 20 66 6f 72 20 63 6f 6d 70 6c  erying for compl
4820: 65 74 65 0a 74 6f 6b 65 6e 73 20 69 73 20 66 61  ete.tokens is fa
4830: 73 74 2c 20 61 73 20 69 74 20 72 65 71 75 69 72  st, as it requir
4840: 65 73 20 61 20 73 69 6e 67 6c 65 20 6c 6f 6f 6b  es a single look
4850: 75 70 2c 20 62 75 74 20 71 75 65 72 79 69 6e 67  up, but querying
4860: 20 66 6f 72 20 61 20 70 72 65 66 69 78 20 0a 74   for a prefix .t
4870: 6f 6b 65 6e 20 63 61 6e 20 62 65 20 73 6c 6f 77  oken can be slow
4880: 2c 20 61 73 20 69 74 20 72 65 71 75 69 72 65 73  , as it requires
4890: 20 61 20 72 61 6e 67 65 20 73 63 61 6e 2e 20 46   a range scan. F
48a0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 71  or example, to q
48b0: 75 65 72 79 20 66 6f 72 0a 74 68 65 20 70 72 65  uery for.the pre
48c0: 66 69 78 20 74 6f 6b 65 6e 20 22 61 62 63 2a 22  fix token "abc*"
48d0: 20 72 65 71 75 69 72 65 73 20 61 20 72 61 6e 67   requires a rang
48e0: 65 20 73 63 61 6e 20 6f 66 20 61 6c 6c 20 74 6f  e scan of all to
48f0: 6b 65 6e 73 20 67 72 65 61 74 65 72 20 74 68 61  kens greater tha
4900: 6e 0a 6f 72 20 65 71 75 61 6c 20 74 6f 20 22 61  n.or equal to "a
4910: 62 63 22 20 61 6e 64 20 6c 65 73 73 20 74 68 61  bc" and less tha
4920: 6e 20 22 61 62 64 22 2e 0a 0a 3c 70 3e 20 41 20  n "abd"...<p> A 
4930: 70 72 65 66 69 78 20 69 6e 64 65 78 20 69 73 20  prefix index is 
4940: 61 20 73 65 70 61 72 61 74 65 20 69 6e 64 65 78  a separate index
4950: 20 74 68 61 74 20 72 65 63 6f 72 64 73 20 74 68   that records th
4960: 65 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 6c  e location of al
4970: 6c 0a 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 70  l.instances of p
4980: 72 65 66 69 78 20 74 6f 6b 65 6e 73 20 6f 66 20  refix tokens of 
4990: 61 20 63 65 72 74 61 69 6e 20 6c 65 6e 67 74 68  a certain length
49a0: 20 69 6e 20 63 68 61 72 61 63 74 65 72 73 20 75   in characters u
49b0: 73 65 64 20 74 6f 20 73 70 65 65 64 0a 75 70 20  sed to speed.up 
49c0: 71 75 65 72 69 65 73 20 66 6f 72 20 70 72 65 66  queries for pref
49d0: 69 78 20 74 6f 6b 65 6e 73 2e 20 46 6f 72 20 65  ix tokens. For e
49e0: 78 61 6d 70 6c 65 2c 20 6f 70 74 69 6d 69 7a 69  xample, optimizi
49f0: 6e 67 20 61 20 71 75 65 72 79 20 66 6f 72 20 70  ng a query for p
4a00: 72 65 66 69 78 0a 74 6f 6b 65 6e 20 22 61 62 63  refix.token "abc
4a10: 2a 22 20 72 65 71 75 69 72 65 73 20 61 20 70 72  *" requires a pr
4a20: 65 66 69 78 20 69 6e 64 65 78 20 6f 66 20 74 68  efix index of th
4a30: 72 65 65 2d 63 68 61 72 61 63 74 65 72 20 70 72  ree-character pr
4a40: 65 66 69 78 65 73 2e 0a 0a 3c 70 3e 20 54 6f 20  efixes...<p> To 
4a50: 61 64 64 20 70 72 65 66 69 78 20 69 6e 64 65 78  add prefix index
4a60: 65 73 20 74 6f 20 61 6e 20 46 54 53 35 20 74 61  es to an FTS5 ta
4a70: 62 6c 65 2c 20 74 68 65 20 22 70 72 65 66 69 78  ble, the "prefix
4a80: 22 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  " option is set 
4a90: 74 6f 0a 65 69 74 68 65 72 20 61 20 73 69 6e 67  to.either a sing
4aa0: 6c 65 20 70 6f 73 69 74 69 76 65 20 69 6e 74 65  le positive inte
4ab0: 67 65 72 20 6f 72 20 61 20 74 65 78 74 20 76 61  ger or a text va
4ac0: 6c 75 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  lue containing a
4ad0: 20 77 68 69 74 65 2d 73 70 61 63 65 0a 73 65 70   white-space.sep
4ae0: 61 72 61 74 65 64 20 6c 69 73 74 20 6f 66 20 6f  arated list of o
4af0: 6e 65 20 6f 72 20 6d 6f 72 65 20 70 6f 73 69 74  ne or more posit
4b00: 69 76 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ive integer valu
4b10: 65 73 2e 20 41 20 70 72 65 66 69 78 20 69 6e 64  es. A prefix ind
4b20: 65 78 20 69 73 0a 63 72 65 61 74 65 64 20 66 6f  ex is.created fo
4b30: 72 20 65 61 63 68 20 69 6e 74 65 67 65 72 20 73  r each integer s
4b40: 70 65 63 69 66 69 65 64 2e 20 49 66 20 6d 6f 72  pecified. If mor
4b50: 65 20 74 68 61 6e 20 6f 6e 65 20 22 70 72 65 66  e than one "pref
4b60: 69 78 22 20 6f 70 74 69 6f 6e 20 69 73 0a 73 70  ix" option is.sp
4b70: 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
4b80: 6f 66 20 61 20 73 69 6e 67 6c 65 20 43 52 45 41  of a single CREA
4b90: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
4ba0: 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6c 6c 20   statement, all 
4bb0: 61 70 70 6c 79 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  apply...<codeblo
4bc0: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 77 6f 20  ck>.  <i>-- Two 
4bd0: 77 61 79 73 20 74 6f 20 63 72 65 61 74 65 20 61  ways to create a
4be0: 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68 61  n FTS5 table tha
4bf0: 74 20 6d 61 69 6e 74 61 69 6e 73 20 70 72 65 66  t maintains pref
4c00: 69 78 20 69 6e 64 65 78 65 73 20 66 6f 72 0a 20  ix indexes for. 
4c10: 20 2d 2d 20 74 77 6f 20 61 6e 64 20 74 68 72 65   -- two and thre
4c20: 65 20 63 68 61 72 61 63 74 65 72 20 70 72 65 66  e character pref
4c30: 69 78 20 74 6f 6b 65 6e 73 2e 3c 2f 69 3e 0a 20  ix tokens.</i>. 
4c40: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
4c50: 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20 66  TABLE ft USING f
4c60: 74 73 35 28 61 2c 20 62 2c 20 70 72 65 66 69 78  ts5(a, b, prefix
4c70: 3d 27 32 20 33 27 29 3b 0a 20 20 43 52 45 41 54  ='2 3');.  CREAT
4c80: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
4c90: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
4ca0: 20 62 2c 20 70 72 65 66 69 78 3d 32 2c 20 70 72   b, prefix=2, pr
4cb0: 65 66 69 78 3d 33 29 3b 0a 3c 2f 63 6f 64 65 62  efix=3);.</codeb
4cc0: 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d  lock>..<h2 tags=
4cd0: 22 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65 72 73  "FTS5 tokenizers
4ce0: 22 3e 54 6f 6b 65 6e 69 7a 65 72 73 3c 2f 68 32  ">Tokenizers</h2
4cf0: 3e 0a 0a 3c 70 3e 20 54 68 65 20 43 52 45 41 54  >..<p> The CREAT
4d00: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
4d10: 22 74 6f 6b 65 6e 69 7a 65 22 20 6f 70 74 69 6f  "tokenize" optio
4d20: 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
4d30: 66 69 67 75 72 65 20 74 68 65 0a 73 70 65 63 69  figure the.speci
4d40: 66 69 63 20 74 6f 6b 65 6e 69 7a 65 72 20 75 73  fic tokenizer us
4d50: 65 64 20 62 79 20 74 68 65 20 46 54 53 35 20 74  ed by the FTS5 t
4d60: 61 62 6c 65 2e 20 54 68 65 20 6f 70 74 69 6f 6e  able. The option
4d70: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
4d80: 65 20 65 69 74 68 65 72 0a 61 6e 20 46 54 53 35  e either.an FTS5
4d90: 20 62 61 72 65 77 6f 72 64 2c 20 6f 72 20 61 6e   bareword, or an
4da0: 20 53 51 4c 20 74 65 78 74 20 6c 69 74 65 72 61   SQL text litera
4db0: 6c 2e 20 54 68 65 20 74 65 78 74 20 6f 66 20 74  l. The text of t
4dc0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  he argument is i
4dd0: 74 73 65 6c 66 0a 74 72 65 61 74 65 64 20 61 73  tself.treated as
4de0: 20 61 20 77 68 69 74 65 2d 73 70 61 63 65 20 73   a white-space s
4df0: 65 72 69 65 73 20 6f 66 20 6f 6e 65 20 6f 72 20  eries of one or 
4e00: 6d 6f 72 65 20 46 54 53 35 20 62 61 72 65 77 6f  more FTS5 barewo
4e10: 72 64 73 20 6f 72 20 53 51 4c 20 74 65 78 74 0a  rds or SQL text.
4e20: 6c 69 74 65 72 61 6c 73 2e 20 54 68 65 20 66 69  literals. The fi
4e30: 72 73 74 20 6f 66 20 74 68 65 73 65 20 69 73 20  rst of these is 
4e40: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
4e50: 74 6f 6b 65 6e 69 7a 65 72 20 74 6f 20 75 73 65  tokenizer to use
4e60: 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 61 6e 64  . The second.and
4e70: 20 73 75 62 73 65 71 75 65 6e 74 20 6c 69 73 74   subsequent list
4e80: 20 65 6c 65 6d 65 6e 74 73 2c 20 69 66 20 74 68   elements, if th
4e90: 65 79 20 65 78 69 73 74 2c 20 61 72 65 20 61 72  ey exist, are ar
4ea0: 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74  guments passed t
4eb0: 6f 20 74 68 65 0a 74 6f 6b 65 6e 69 7a 65 72 20  o the.tokenizer 
4ec0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
4ed0: 0a 3c 70 3e 20 55 6e 6c 69 6b 65 20 6f 70 74 69  .<p> Unlike opti
4ee0: 6f 6e 20 76 61 6c 75 65 73 20 61 6e 64 20 63 6f  on values and co
4ef0: 6c 75 6d 6e 20 6e 61 6d 65 73 2c 20 53 51 4c 20  lumn names, SQL 
4f00: 74 65 78 74 20 6c 69 74 65 72 61 6c 73 20 69 6e  text literals in
4f10: 74 65 6e 64 65 64 20 61 73 0a 74 6f 6b 65 6e 69  tended as.tokeni
4f20: 7a 65 72 73 20 6d 75 73 74 20 62 65 20 71 75 6f  zers must be quo
4f30: 74 65 64 20 75 73 69 6e 67 20 73 69 6e 67 6c 65  ted using single
4f40: 20 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72   quote character
4f50: 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a  s. For example:.
4f60: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c  .<codeblock>.  <
4f70: 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69  i>-- The followi
4f80: 6e 67 20 61 72 65 20 61 6c 6c 20 65 71 75 69 76  ng are all equiv
4f90: 61 6c 65 6e 74 3c 2f 69 3e 0a 20 20 43 52 45 41  alent</i>.  CREA
4fa0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
4fb0: 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78   t1 USING fts5(x
4fc0: 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 70 6f  , tokenize = 'po
4fd0: 72 74 65 72 20 61 73 63 69 69 27 29 3b 0a 20 20  rter ascii');.  
4fe0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
4ff0: 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74  ABLE t1 USING ft
5000: 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d  s5(x, tokenize =
5010: 20 22 70 6f 72 74 65 72 20 61 73 63 69 69 22 29   "porter ascii")
5020: 3b 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  ;.  CREATE VIRTU
5030: 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e  AL TABLE t1 USIN
5040: 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69  G fts5(x, tokeni
5050: 7a 65 20 3d 20 22 27 70 6f 72 74 65 72 27 20 27  ze = "'porter' '
5060: 61 73 63 69 69 27 22 29 3b 0a 20 20 43 52 45 41  ascii'");.  CREA
5070: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
5080: 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78   t1 USING fts5(x
5090: 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 27 27  , tokenize = '''
50a0: 70 6f 72 74 65 72 27 27 20 27 27 61 73 63 69 69  porter'' ''ascii
50b0: 27 27 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 42  ''');..  <i>-- B
50c0: 75 74 20 74 68 69 73 20 77 69 6c 6c 20 66 61 69  ut this will fai
50d0: 6c 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  l:</i>.  CREATE 
50e0: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31  VIRTUAL TABLE t1
50f0: 20 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20 74   USING fts5(x, t
5100: 6f 6b 65 6e 69 7a 65 20 3d 20 27 22 70 6f 72 74  okenize = '"port
5110: 65 72 22 20 22 61 73 63 69 69 22 27 29 3b 0a 0a  er" "ascii"');..
5120: 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 77 69 6c    <i>-- This wil
5130: 6c 20 66 61 69 6c 20 74 6f 6f 3a 3c 2f 69 3e 0a  l fail too:</i>.
5140: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
5150: 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20   TABLE t1 USING 
5160: 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65  fts5(x, tokenize
5170: 20 3d 20 27 70 6f 72 74 65 72 27 20 27 61 73 63   = 'porter' 'asc
5180: 69 69 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ii');.</codebloc
5190: 6b 3e 0a 0a 0a 3c 70 3e 0a 46 54 53 35 20 66 65  k>...<p>.FTS5 fe
51a0: 61 74 75 72 65 73 20 74 68 72 65 65 20 62 75 69  atures three bui
51b0: 6c 74 2d 69 6e 20 74 6f 6b 65 6e 69 7a 65 72 20  lt-in tokenizer 
51c0: 6d 6f 64 75 6c 65 73 2c 20 64 65 73 63 72 69 62  modules, describ
51d0: 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
51e0: 0a 73 65 63 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e  .sections:..<ul>
51f0: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e 75  .  <li> The <b>u
5200: 6e 69 63 6f 64 65 36 31 3c 2f 62 3e 20 74 6f 6b  nicode61</b> tok
5210: 65 6e 69 7a 65 72 2c 20 62 61 73 65 64 20 6f 6e  enizer, based on
5220: 20 74 68 65 20 55 6e 69 63 6f 64 65 20 36 2e 31   the Unicode 6.1
5230: 20 73 74 61 6e 64 61 72 64 2e 20 54 68 69 73 0a   standard. This.
5240: 20 20 20 20 20 20 20 69 73 20 74 68 65 20 64 65         is the de
5250: 66 61 75 6c 74 2e 0a 0a 20 20 3c 6c 69 3e 20 54  fault...  <li> T
5260: 68 65 20 3c 62 3e 61 73 63 69 69 3c 2f 62 3e 20  he <b>ascii</b> 
5270: 74 6f 6b 65 6e 69 7a 65 72 2c 20 77 68 69 63 68  tokenizer, which
5280: 20 61 73 73 75 6d 65 73 20 61 6c 6c 20 63 68 61   assumes all cha
5290: 72 61 63 74 65 72 73 20 6f 75 74 73 69 64 65 20  racters outside 
52a0: 6f 66 0a 20 20 74 68 65 20 41 53 43 49 49 20 63  of.  the ASCII c
52b0: 6f 64 65 70 6f 69 6e 74 20 72 61 6e 67 65 20 28  odepoint range (
52c0: 30 2d 31 32 37 29 20 61 72 65 20 74 6f 20 62 65  0-127) are to be
52d0: 20 74 72 65 61 74 65 64 20 61 73 20 74 6f 6b 65   treated as toke
52e0: 6e 20 63 68 61 72 61 63 74 65 72 73 2e 0a 0a 20  n characters... 
52f0: 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e 70 6f 72   <li> The <b>por
5300: 74 65 72 3c 2f 62 3e 20 74 6f 6b 65 6e 69 7a 65  ter</b> tokenize
5310: 72 2c 20 77 68 69 63 68 20 69 6d 70 6c 65 6d 65  r, which impleme
5320: 6e 74 73 20 74 68 65 20 0a 3c 61 20 68 72 65 66  nts the .<a href
5330: 3d 68 74 74 70 3a 2f 2f 74 61 72 74 61 72 75 73  =http://tartarus
5340: 2e 6f 72 67 2f 6d 61 72 74 69 6e 2f 50 6f 72 74  .org/martin/Port
5350: 65 72 53 74 65 6d 6d 65 72 2f 3e 70 6f 72 74 65  erStemmer/>porte
5360: 72 20 73 74 65 6d 6d 69 6e 67 20 61 6c 67 6f 72  r stemming algor
5370: 69 74 68 6d 3c 2f 61 3e 2e 0a 3c 2f 75 6c 3e 0a  ithm</a>..</ul>.
5380: 0a 3c 70 3e 20 49 74 20 69 73 20 61 6c 73 6f 20  .<p> It is also 
5390: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 72 65 61  possible to crea
53a0: 74 65 20 63 75 73 74 6f 6d 20 74 6f 6b 65 6e 69  te custom tokeni
53b0: 7a 65 72 73 20 66 6f 72 20 46 54 53 35 2e 20 54  zers for FTS5. T
53c0: 68 65 20 41 50 49 20 66 6f 72 20 64 6f 69 6e 67  he API for doing
53d0: 20 73 6f 20 69 73 20 5b 63 75 73 74 6f 6d 20 74   so is [custom t
53e0: 6f 6b 65 6e 69 7a 65 72 73 20 7c 20 64 65 73 63  okenizers | desc
53f0: 72 69 62 65 64 20 68 65 72 65 5d 2e 0a 0a 3c 68  ribed here]...<h
5400: 33 3e 55 6e 69 63 6f 64 65 36 31 20 54 6f 6b 65  3>Unicode61 Toke
5410: 6e 69 7a 65 72 3c 2f 68 33 3e 0a 0a 3c 70 3e 20  nizer</h3>..<p> 
5420: 54 68 65 20 75 6e 69 63 6f 64 65 20 74 6f 6b 65  The unicode toke
5430: 6e 69 7a 65 72 20 63 6c 61 73 73 69 66 69 65 73  nizer classifies
5440: 20 61 6c 6c 20 75 6e 69 63 6f 64 65 20 63 68 61   all unicode cha
5450: 72 61 63 74 65 72 73 20 61 73 20 65 69 74 68 65  racters as eithe
5460: 72 20 0a 22 73 65 70 61 72 61 74 6f 72 22 20 6f  r ."separator" o
5470: 72 20 22 74 6f 6b 65 6e 22 20 63 68 61 72 61 63  r "token" charac
5480: 74 65 72 73 2e 20 42 79 20 64 65 66 61 75 6c 74  ters. By default
5490: 20 61 6c 6c 20 73 70 61 63 65 20 61 6e 64 20 70   all space and p
54a0: 75 6e 63 74 75 61 74 69 6f 6e 0a 63 68 61 72 61  unctuation.chara
54b0: 63 74 65 72 73 2c 20 61 73 20 64 65 66 69 6e 65  cters, as define
54c0: 64 20 62 79 20 55 6e 69 63 6f 64 65 20 36 2e 31  d by Unicode 6.1
54d0: 2c 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64  , are considered
54e0: 20 73 65 70 61 72 61 74 6f 72 73 2c 20 61 6e 64   separators, and
54f0: 20 61 6c 6c 20 0a 6f 74 68 65 72 20 63 68 61 72   all .other char
5500: 61 63 74 65 72 73 20 61 73 20 74 6f 6b 65 6e 20  acters as token 
5510: 63 68 61 72 61 63 74 65 72 73 2e 20 45 61 63 68  characters. Each
5520: 20 63 6f 6e 74 69 67 75 6f 75 73 20 72 75 6e 20   contiguous run 
5530: 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a  of one or more .
5540: 74 6f 6b 65 6e 20 63 68 61 72 61 63 74 65 72 73  token characters
5550: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
5560: 6f 20 62 65 20 61 20 74 6f 6b 65 6e 2e 20 54 68  o be a token. Th
5570: 65 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 63  e tokenizer is c
5580: 61 73 65 2d 69 6e 73 65 6e 73 69 74 69 76 65 0a  ase-insensitive.
5590: 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
55a0: 20 72 75 6c 65 73 20 64 65 66 69 6e 65 64 20 62   rules defined b
55b0: 79 20 55 6e 69 63 6f 64 65 20 36 2e 31 2e 0a 0a  y Unicode 6.1...
55c0: 3c 70 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  <p> By default, 
55d0: 64 69 61 63 72 69 74 69 63 73 20 61 72 65 20 72  diacritics are r
55e0: 65 6d 6f 76 65 64 20 66 72 6f 6d 20 61 6c 6c 20  emoved from all 
55f0: 4c 61 74 69 6e 20 73 63 72 69 70 74 20 63 68 61  Latin script cha
5600: 72 61 63 74 65 72 73 2e 20 54 68 69 73 0a 6d 65  racters. This.me
5610: 61 6e 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ans, for example
5620: 2c 20 74 68 61 74 20 22 41 22 2c 20 22 61 22 2c  , that "A", "a",
5630: 20 22 26 23 31 39 32 3b 22 2c 20 22 26 23 32 32   "&#192;", "&#22
5640: 34 3b 22 2c 20 22 26 23 31 39 34 3b 22 20 61 6e  4;", "&#194;" an
5650: 64 20 22 26 23 32 32 36 3b 22 0a 61 72 65 20 61  d "&#226;".are a
5660: 6c 6c 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ll considered to
5670: 20 62 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a   be equivalent..
5680: 0a 3c 70 3e 20 41 6e 79 20 61 72 67 75 6d 65 6e  .<p> Any argumen
5690: 74 73 20 66 6f 6c 6c 6f 77 69 6e 67 20 22 75 6e  ts following "un
56a0: 69 63 6f 64 65 36 31 22 20 69 6e 20 74 68 65 20  icode61" in the 
56b0: 74 6f 6b 65 6e 20 73 70 65 63 69 66 69 63 61 74  token specificat
56c0: 69 6f 6e 20 61 72 65 20 74 72 65 61 74 65 64 0a  ion are treated.
56d0: 61 73 20 61 20 6c 69 73 74 20 6f 66 20 61 6c 74  as a list of alt
56e0: 65 72 6e 61 74 69 6e 67 20 6f 70 74 69 6f 6e 20  ernating option 
56f0: 6e 61 6d 65 73 20 61 6e 64 20 76 61 6c 75 65 73  names and values
5700: 2e 20 55 6e 69 63 6f 64 65 36 31 20 73 75 70 70  . Unicode61 supp
5710: 6f 72 74 73 20 74 68 65 0a 66 6f 6c 6c 6f 77 69  orts the.followi
5720: 6e 67 20 6f 70 74 69 6f 6e 73 3a 0a 0a 3c 74 61  ng options:..<ta
5730: 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20  ble striped=1>. 
5740: 20 3c 74 72 3e 3c 74 68 3e 20 4f 70 74 69 6f 6e   <tr><th> Option
5750: 20 3c 74 68 3e 20 55 73 61 67 65 0a 20 20 3c 74   <th> Usage.  <t
5760: 72 3e 3c 74 64 3e 20 72 65 6d 6f 76 65 5f 64 69  r><td> remove_di
5770: 61 63 72 69 74 69 63 73 0a 20 20 3c 74 64 3e 54  acritics.  <td>T
5780: 68 69 73 20 6f 70 74 69 6f 6e 20 73 68 6f 75 6c  his option shoul
5790: 64 20 62 65 20 73 65 74 20 74 6f 20 22 30 22 20  d be set to "0" 
57a0: 6f 72 20 22 31 22 2e 20 49 66 20 69 74 20 69 73  or "1". If it is
57b0: 20 73 65 74 20 28 74 68 65 20 64 65 66 61 75 6c   set (the defaul
57c0: 74 29 2c 0a 20 20 64 69 61 63 72 69 74 69 63 73  t),.  diacritics
57d0: 20 61 72 65 20 72 65 6d 6f 76 65 64 20 66 72 6f   are removed fro
57e0: 6d 20 61 6c 6c 20 6c 61 74 69 6e 20 73 63 72 69  m all latin scri
57f0: 70 74 20 63 68 61 72 61 63 74 65 72 73 20 61 73  pt characters as
5800: 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
5810: 2e 0a 20 20 49 66 20 69 74 20 69 73 20 63 6c 65  ..  If it is cle
5820: 61 72 2c 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ar, they are not
5830: 2e 20 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e 20 74  . ..  <tr><td> t
5840: 6f 6b 65 6e 63 68 61 72 73 0a 20 20 3c 74 64 3e  okenchars.  <td>
5850: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   This option is 
5860: 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
5870: 61 64 64 69 74 69 6f 6e 61 6c 20 75 6e 69 63 6f  additional unico
5880: 64 65 20 63 68 61 72 61 63 74 65 72 73 20 74 68  de characters th
5890: 61 74 20 0a 20 20 73 68 6f 75 6c 64 20 62 65 20  at .  should be 
58a0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b 65 6e  considered token
58b0: 20 63 68 61 72 61 63 74 65 72 73 2c 20 65 76 65   characters, eve
58c0: 6e 20 69 66 20 74 68 65 79 20 61 72 65 20 77 68  n if they are wh
58d0: 69 74 65 2d 73 70 61 63 65 20 6f 72 0a 20 20 70  ite-space or.  p
58e0: 75 6e 63 74 75 61 74 69 6f 6e 20 63 68 61 72 61  unctuation chara
58f0: 63 74 65 72 73 20 61 63 63 6f 72 64 69 6e 67 20  cters according 
5900: 74 6f 20 55 6e 69 63 6f 64 65 20 36 2e 31 2e 20  to Unicode 6.1. 
5910: 41 6c 6c 20 63 68 61 72 61 63 74 65 72 73 20 69  All characters i
5920: 6e 20 74 68 65 0a 20 20 73 74 72 69 6e 67 20 74  n the.  string t
5930: 68 61 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  hat this option 
5940: 69 73 20 73 65 74 20 74 6f 20 61 72 65 20 63 6f  is set to are co
5950: 6e 73 69 64 65 72 65 64 20 74 6f 6b 65 6e 20 63  nsidered token c
5960: 68 61 72 61 63 74 65 72 73 2e 0a 0a 20 20 3c 74  haracters...  <t
5970: 72 3e 3c 74 64 3e 20 73 65 70 61 72 61 74 6f 72  r><td> separator
5980: 73 0a 20 20 3c 74 64 3e 20 54 68 69 73 20 6f 70  s.  <td> This op
5990: 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
59a0: 73 70 65 63 69 66 79 20 61 64 64 69 74 69 6f 6e  specify addition
59b0: 61 6c 20 75 6e 69 63 6f 64 65 20 63 68 61 72 61  al unicode chara
59c0: 63 74 65 72 73 20 74 68 61 74 20 0a 20 20 73 68  cters that .  sh
59d0: 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72  ould be consider
59e0: 65 64 20 61 73 20 73 65 70 61 72 61 74 6f 72 20  ed as separator 
59f0: 63 68 61 72 61 63 74 65 72 73 2c 20 65 76 65 6e  characters, even
5a00: 20 69 66 20 74 68 65 79 20 61 72 65 20 74 6f 6b   if they are tok
5a10: 65 6e 0a 20 20 63 68 61 72 61 63 74 65 72 73 20  en.  characters 
5a20: 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 55 6e 69  according to Uni
5a30: 63 6f 64 65 20 36 2e 31 2e 20 41 6c 6c 20 63 68  code 6.1. All ch
5a40: 61 72 61 63 74 65 72 73 20 69 6e 20 74 68 65 20  aracters in the 
5a50: 73 74 72 69 6e 67 20 74 68 61 74 20 0a 20 20 74  string that .  t
5a60: 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
5a70: 74 20 74 6f 20 61 72 65 20 63 6f 6e 73 69 64 65  t to are conside
5a80: 72 65 64 20 73 65 70 61 72 61 74 6f 72 73 2e 0a  red separators..
5a90: 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 20 46 6f  </table>..<p> Fo
5aa0: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
5ab0: 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
5ac0: 43 72 65 61 74 65 20 61 6e 20 46 54 53 35 20 74  Create an FTS5 t
5ad0: 61 62 6c 65 20 74 68 61 74 20 64 6f 65 73 20 6e  able that does n
5ae0: 6f 74 20 72 65 6d 6f 76 65 20 64 69 61 63 72 69  ot remove diacri
5af0: 74 69 63 73 20 66 72 6f 6d 20 4c 61 74 69 6e 0a  tics from Latin.
5b00: 20 20 2d 2d 20 73 63 72 69 70 74 20 63 68 61 72    -- script char
5b10: 61 63 74 65 72 73 2c 20 61 6e 64 20 74 68 61 74  acters, and that
5b20: 20 63 6f 6e 73 69 64 65 72 73 20 68 79 70 68 65   considers hyphe
5b30: 6e 73 20 61 6e 64 20 75 6e 64 65 72 73 63 6f 72  ns and underscor
5b40: 65 20 63 68 61 72 61 63 74 65 72 73 0a 20 20 2d  e characters.  -
5b50: 2d 20 74 6f 20 62 65 20 70 61 72 74 20 6f 66 20  - to be part of 
5b60: 74 6f 6b 65 6e 73 2e 20 3c 2f 69 3e 0a 20 20 43  tokens. </i>.  C
5b70: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
5b80: 42 4c 45 20 66 74 20 55 53 49 4e 47 20 66 74 73  BLE ft USING fts
5b90: 35 28 61 2c 20 62 2c 20 0a 20 20 20 20 20 20 74  5(a, b, .      t
5ba0: 6f 6b 65 6e 69 7a 65 20 3d 20 22 75 6e 69 63 6f  okenize = "unico
5bb0: 64 65 36 31 20 72 65 6d 6f 76 65 5f 64 69 61 63  de61 remove_diac
5bc0: 72 69 74 69 63 73 20 30 20 74 6f 6b 65 6e 63 68  ritics 0 tokench
5bd0: 61 72 73 20 27 2d 5f 27 22 0a 20 20 29 3b 0a 3c  ars '-_'".  );.<
5be0: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
5bf0: 20 54 68 65 20 66 74 73 35 20 75 6e 69 63 6f 64   The fts5 unicod
5c00: 65 36 31 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73  e61 tokenizer is
5c10: 20 62 79 74 65 2d 66 6f 72 2d 62 79 74 65 20 63   byte-for-byte c
5c20: 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68 20 74  ompatible with t
5c30: 68 65 20 66 74 73 33 2f 34 0a 75 6e 69 63 6f 64  he fts3/4.unicod
5c40: 65 36 31 20 74 6f 6b 65 6e 69 7a 65 72 2e 0a 0a  e61 tokenizer...
5c50: 3c 68 33 3e 41 73 63 69 69 20 54 6f 6b 65 6e 69  <h3>Ascii Tokeni
5c60: 7a 65 72 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68  zer</h3>..<p> Th
5c70: 65 20 41 73 63 69 69 20 74 6f 6b 65 6e 69 7a 65  e Ascii tokenize
5c80: 72 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  r is similar to 
5c90: 74 68 65 20 55 6e 69 63 6f 64 65 36 31 20 74 6f  the Unicode61 to
5ca0: 6b 65 6e 69 7a 65 72 2c 20 65 78 63 65 70 74 20  kenizer, except 
5cb0: 74 68 61 74 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  that:..<ul>.  <l
5cc0: 69 3e 20 41 6c 6c 20 6e 6f 6e 2d 41 53 43 49 49  i> All non-ASCII
5cd0: 20 63 68 61 72 61 63 74 65 72 73 20 28 74 68 6f   characters (tho
5ce0: 73 65 20 77 69 74 68 20 63 6f 64 65 70 6f 69 6e  se with codepoin
5cf0: 74 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ts greater than 
5d00: 31 32 37 29 20 61 72 65 0a 20 20 61 6c 77 61 79  127) are.  alway
5d10: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b  s considered tok
5d20: 65 6e 20 63 68 61 72 61 63 74 65 72 73 2e 20 49  en characters. I
5d30: 66 20 61 6e 79 20 6e 6f 6e 2d 41 53 43 49 49 20  f any non-ASCII 
5d40: 63 68 61 72 61 63 74 65 72 73 20 61 72 65 20 73  characters are s
5d50: 70 65 63 69 66 69 65 64 0a 20 20 61 73 20 70 61  pecified.  as pa
5d60: 72 74 20 6f 66 20 74 68 65 20 73 65 70 61 72 61  rt of the separa
5d70: 74 6f 72 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tors option, the
5d80: 79 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 20 20  y are ignored.  
5d90: 0a 0a 20 20 3c 6c 69 3e 20 43 61 73 65 2d 66 6f  ..  <li> Case-fo
5da0: 6c 64 69 6e 67 20 69 73 20 6f 6e 6c 79 20 70 65  lding is only pe
5db0: 72 66 6f 72 6d 65 64 20 66 6f 72 20 41 53 43 49  rformed for ASCI
5dc0: 49 20 63 68 61 72 61 63 74 65 72 73 2e 20 53 6f  I characters. So
5dd0: 20 77 68 69 6c 65 20 22 41 22 20 61 6e 64 0a 20   while "A" and. 
5de0: 20 22 61 22 20 61 72 65 20 63 6f 6e 73 69 64 65   "a" are conside
5df0: 72 65 64 20 74 6f 20 62 65 20 65 71 75 69 76 61  red to be equiva
5e00: 6c 65 6e 74 2c 20 22 26 23 31 39 35 22 20 61 6e  lent, "&#195" an
5e10: 64 20 22 26 23 32 32 37 3b 22 20 61 72 65 20 64  d "&#227;" are d
5e20: 69 73 74 69 6e 63 74 2e 0a 0a 20 20 3c 6c 69 3e  istinct...  <li>
5e30: 20 54 68 65 20 72 65 6d 6f 76 65 5f 64 69 61 63   The remove_diac
5e40: 72 69 74 69 63 73 20 6f 70 74 69 6f 6e 20 69 73  ritics option is
5e50: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 2e 0a   not supported..
5e60: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65  </ul>..<p> For e
5e70: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
5e80: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65  ock>.  <i>-- Cre
5e90: 61 74 65 20 61 6e 20 46 54 53 35 20 74 61 62 6c  ate an FTS5 tabl
5ea0: 65 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20  e that uses the 
5eb0: 61 73 63 69 69 20 74 6f 6b 65 6e 69 7a 65 72 2c  ascii tokenizer,
5ec0: 20 62 75 74 20 64 6f 65 73 20 6e 6f 74 0a 20 20   but does not.  
5ed0: 2d 2d 20 63 6f 6e 73 69 64 65 72 20 6e 75 6d 65  -- consider nume
5ee0: 72 69 63 20 63 68 61 72 61 63 74 65 72 73 20 74  ric characters t
5ef0: 6f 20 62 65 20 70 61 72 74 20 6f 66 20 74 6f 6b  o be part of tok
5f00: 65 6e 73 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ens.</i>.  CREAT
5f10: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
5f20: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
5f30: 20 62 2c 20 0a 20 20 20 20 20 20 74 6f 6b 65 6e   b, .      token
5f40: 69 7a 65 20 3d 20 22 61 73 63 69 69 20 73 65 70  ize = "ascii sep
5f50: 61 72 61 74 6f 72 73 20 27 30 31 32 33 34 35 36  arators '0123456
5f60: 37 38 39 27 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64  789'".  );.</cod
5f70: 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 33 3e 50 6f 72  eblock>..<h3>Por
5f80: 74 65 72 20 54 6f 6b 65 6e 69 7a 65 72 3c 2f 68  ter Tokenizer</h
5f90: 33 3e 0a 0a 3c 70 3e 20 54 68 65 20 70 6f 72 74  3>..<p> The port
5fa0: 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  er tokenizer is 
5fb0: 61 20 77 72 61 70 70 65 72 20 74 6f 6b 65 6e 69  a wrapper tokeni
5fc0: 7a 65 72 2e 20 49 74 20 74 61 6b 65 73 20 74 68  zer. It takes th
5fd0: 65 20 6f 75 74 70 75 74 20 6f 66 20 73 6f 6d 65  e output of some
5fe0: 0a 6f 74 68 65 72 20 74 6f 6b 65 6e 69 7a 65 72  .other tokenizer
5ff0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 74 68 65   and applies the
6000: 20 0a 3c 61 20 68 72 65 66 3d 68 74 74 70 3a 2f   .<a href=http:/
6010: 2f 74 61 72 74 61 72 75 73 2e 6f 72 67 2f 6d 61  /tartarus.org/ma
6020: 72 74 69 6e 2f 50 6f 72 74 65 72 53 74 65 6d 6d  rtin/PorterStemm
6030: 65 72 2f 3e 70 6f 72 74 65 72 20 73 74 65 6d 6d  er/>porter stemm
6040: 69 6e 67 20 61 6c 67 6f 72 69 74 68 6d 3c 2f 61  ing algorithm</a
6050: 3e 0a 74 6f 20 65 61 63 68 20 74 6f 6b 65 6e 20  >.to each token 
6060: 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
6070: 73 20 69 74 20 74 6f 20 46 54 53 35 2e 20 54 68  s it to FTS5. Th
6080: 69 73 20 61 6c 6c 6f 77 73 20 73 65 61 72 63 68  is allows search
6090: 20 74 65 72 6d 73 20 6c 69 6b 65 0a 22 63 6f 72   terms like."cor
60a0: 72 65 63 74 69 6f 6e 22 20 74 6f 20 6d 61 74 63  rection" to matc
60b0: 68 20 73 69 6d 69 6c 61 72 20 77 6f 72 64 73 20  h similar words 
60c0: 73 75 63 68 20 61 73 20 22 63 6f 72 72 65 63 74  such as "correct
60d0: 65 64 22 20 6f 72 20 22 63 6f 72 72 65 63 74 69  ed" or "correcti
60e0: 6e 67 22 2e 20 54 68 65 0a 70 6f 72 74 65 72 20  ng". The.porter 
60f0: 73 74 65 6d 6d 65 72 20 61 6c 67 6f 72 69 74 68  stemmer algorith
6100: 6d 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  m is designed fo
6110: 72 20 75 73 65 20 77 69 74 68 20 45 6e 67 6c 69  r use with Engli
6120: 73 68 20 6c 61 6e 67 75 61 67 65 20 74 65 72 6d  sh language term
6130: 73 20 0a 6f 6e 6c 79 20 2d 20 75 73 69 6e 67 20  s .only - using 
6140: 69 74 20 77 69 74 68 20 6f 74 68 65 72 20 6c 61  it with other la
6150: 6e 67 75 61 67 65 73 20 6d 61 79 20 6f 72 20 6d  nguages may or m
6160: 61 79 20 6e 6f 74 20 69 6d 70 72 6f 76 65 20 73  ay not improve s
6170: 65 61 72 63 68 20 75 74 69 6c 69 74 79 2e 0a 0a  earch utility...
6180: 3c 70 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  <p> By default, 
6190: 74 68 65 20 70 6f 72 74 65 72 20 74 6f 6b 65 6e  the porter token
61a0: 69 7a 65 72 20 6f 70 65 72 61 74 65 73 20 61 73  izer operates as
61b0: 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
61c0: 64 20 74 68 65 20 64 65 66 61 75 6c 74 0a 74 6f  d the default.to
61d0: 6b 65 6e 69 7a 65 72 20 28 75 6e 69 63 6f 64 65  kenizer (unicode
61e0: 36 31 29 2e 20 4f 72 2c 20 69 66 20 6f 6e 65 20  61). Or, if one 
61f0: 6f 72 20 6d 6f 72 65 20 65 78 74 72 61 20 61 72  or more extra ar
6200: 67 75 6d 65 6e 74 73 20 61 72 65 20 61 64 64 65  guments are adde
6210: 64 20 74 6f 20 74 68 65 0a 22 74 6f 6b 65 6e 69  d to the."tokeni
6220: 7a 65 22 20 6f 70 74 69 6f 6e 20 66 6f 6c 6c 6f  ze" option follo
6230: 77 69 6e 67 20 22 70 6f 72 74 65 72 22 2c 20 74  wing "porter", t
6240: 68 65 79 20 61 72 65 20 74 72 65 61 74 65 64 20  hey are treated 
6250: 61 73 20 61 20 73 70 65 63 69 66 69 63 61 74 69  as a specificati
6260: 6f 6e 20 66 6f 72 0a 74 68 65 20 75 6e 64 65 72  on for.the under
6270: 6c 79 69 6e 67 20 74 6f 6b 65 6e 69 7a 65 72 20  lying tokenizer 
6280: 74 68 61 74 20 74 68 65 20 70 6f 72 74 65 72 20  that the porter 
6290: 73 74 65 6d 6d 65 72 20 75 73 65 73 2e 20 46 6f  stemmer uses. Fo
62a0: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
62b0: 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
62c0: 54 77 6f 20 77 61 79 73 20 74 6f 20 63 72 65 61  Two ways to crea
62d0: 74 65 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65  te an FTS5 table
62e0: 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20 70   that uses the p
62f0: 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20  orter tokenizer 
6300: 74 6f 0a 20 20 2d 2d 20 73 74 65 6d 20 74 68 65  to.  -- stem the
6310: 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 20 64   output of the d
6320: 65 66 61 75 6c 74 20 74 6f 6b 65 6e 69 7a 65 72  efault tokenizer
6330: 20 28 75 6e 69 63 6f 64 65 36 31 29 2e 20 3c 2f   (unicode61). </
6340: 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
6350: 55 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49  UAL TABLE t1 USI
6360: 4e 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e  NG fts5(x, token
6370: 69 7a 65 20 3d 20 70 6f 72 74 65 72 29 3b 20 0a  ize = porter); .
6380: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
6390: 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20   TABLE t1 USING 
63a0: 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65  fts5(x, tokenize
63b0: 20 3d 20 27 70 6f 72 74 65 72 20 75 6e 69 63 6f   = 'porter unico
63c0: 64 65 36 31 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  de61');..  <i>--
63d0: 20 41 20 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69   A porter tokeni
63e0: 7a 65 72 20 75 73 65 64 20 74 6f 20 73 74 65 6d  zer used to stem
63f0: 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
6400: 68 65 20 75 6e 69 63 6f 64 65 36 31 20 74 6f 6b  he unicode61 tok
6410: 65 6e 69 7a 65 72 2c 0a 20 20 2d 2d 20 77 69 74  enizer,.  -- wit
6420: 68 20 64 69 61 63 72 69 74 69 63 73 20 72 65 6d  h diacritics rem
6430: 6f 76 65 64 20 62 65 66 6f 72 65 20 73 74 65 6d  oved before stem
6440: 6d 69 6e 67 2e 3c 2f 69 3e 0a 20 20 43 52 45 41  ming.</i>.  CREA
6450: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
6460: 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78   t1 USING fts5(x
6470: 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 70 6f  , tokenize = 'po
6480: 72 74 65 72 20 75 6e 69 63 6f 64 65 36 31 20 72  rter unicode61 r
6490: 65 6d 6f 76 65 5f 64 69 61 63 72 69 74 69 63 73  emove_diacritics
64a0: 20 31 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63   1');.</codebloc
64b0: 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  k>..<h2 tags="FT
64c0: 53 35 20 63 6f 6e 74 65 6e 74 20 6f 70 74 69 6f  S5 content optio
64d0: 6e 22 3e 45 78 74 65 72 6e 61 6c 20 43 6f 6e 74  n">External Cont
64e0: 65 6e 74 20 61 6e 64 20 43 6f 6e 74 65 6e 74 6c  ent and Contentl
64f0: 65 73 73 20 54 61 62 6c 65 73 3c 2f 68 32 3e 0a  ess Tables</h2>.
6500: 0a 3c 70 3e 0a 4e 6f 72 6d 61 6c 6c 79 2c 20 77  .<p>.Normally, w
6510: 68 65 6e 20 61 20 72 6f 77 20 69 73 20 69 6e 73  hen a row is ins
6520: 65 72 74 65 64 20 69 6e 74 6f 20 61 6e 20 46 54  erted into an FT
6530: 53 35 20 74 61 62 6c 65 2c 20 61 73 20 77 65 6c  S5 table, as wel
6540: 6c 20 61 73 20 74 68 65 20 76 61 72 69 6f 75 73  l as the various
6550: 0a 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78  .full-text index
6560: 20 65 6e 74 72 69 65 73 20 61 6e 64 20 6f 74 68   entries and oth
6570: 65 72 20 64 61 74 61 20 61 20 63 6f 70 79 20 6f  er data a copy o
6580: 66 20 74 68 65 20 72 6f 77 20 69 73 20 73 74 6f  f the row is sto
6590: 72 65 64 20 69 6e 20 61 20 70 72 69 76 61 74 65  red in a private
65a0: 0a 74 61 62 6c 65 20 6d 61 6e 61 67 65 64 20 62  .table managed b
65b0: 79 20 74 68 65 20 46 54 53 35 20 6d 6f 64 75 6c  y the FTS5 modul
65c0: 65 2e 20 57 68 65 6e 20 63 6f 6c 75 6d 6e 20 76  e. When column v
65d0: 61 6c 75 65 73 20 61 72 65 20 72 65 71 75 65 73  alues are reques
65e0: 74 65 64 20 66 72 6f 6d 20 74 68 65 0a 46 54 53  ted from the.FTS
65f0: 35 20 74 61 62 6c 65 20 62 79 20 74 68 65 20 75  5 table by the u
6600: 73 65 72 20 6f 72 20 62 79 20 61 6e 20 61 75 78  ser or by an aux
6610: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20  iliary function 
6620: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
6630: 74 68 65 79 20 61 72 65 0a 72 65 61 64 20 66 72  they are.read fr
6640: 6f 6d 20 74 68 69 73 20 70 72 69 76 61 74 65 20  om this private 
6650: 74 61 62 6c 65 2e 20 54 68 65 20 22 63 6f 6e 74  table. The "cont
6660: 65 6e 74 22 20 6f 70 74 69 6f 6e 20 6d 61 79 20  ent" option may 
6670: 62 65 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  be used to creat
6680: 65 20 61 6e 0a 46 54 53 35 20 74 61 62 6c 65 20  e an.FTS5 table 
6690: 74 68 61 74 20 73 74 6f 72 65 73 20 6f 6e 6c 79  that stores only
66a0: 20 46 54 53 20 66 75 6c 6c 2d 74 65 78 74 20 69   FTS full-text i
66b0: 6e 64 65 78 20 65 6e 74 72 69 65 73 2e 20 42 65  ndex entries. Be
66c0: 63 61 75 73 65 20 74 68 65 20 63 6f 6c 75 6d 6e  cause the column
66d0: 0a 76 61 6c 75 65 73 20 74 68 65 6d 73 65 6c 76  .values themselv
66e0: 65 73 20 61 72 65 20 75 73 75 61 6c 6c 79 20 6d  es are usually m
66f0: 75 63 68 20 6c 61 72 67 65 72 20 74 68 61 6e 20  uch larger than 
6700: 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 66  the associated f
6710: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 0a 65  ull-text index.e
6720: 6e 74 72 69 65 73 2c 20 74 68 69 73 20 63 61 6e  ntries, this can
6730: 20 73 61 76 65 20 73 69 67 6e 69 66 69 63 61 6e   save significan
6740: 74 20 64 61 74 61 62 61 73 65 20 73 70 61 63 65  t database space
6750: 2e 0a 0a 3c 70 3e 0a 54 68 65 72 65 20 61 72 65  ...<p>.There are
6760: 20 74 77 6f 20 77 61 79 73 20 74 6f 20 75 73 65   two ways to use
6770: 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 22 20 6f   the "content" o
6780: 70 74 69 6f 6e 3a 0a 3c 75 6c 3e 0a 20 20 3c 6c  ption:.<ul>.  <l
6790: 69 3e 20 42 79 20 73 65 74 74 69 6e 67 20 69 74  i> By setting it
67a0: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
67b0: 69 6e 67 20 74 6f 20 63 72 65 61 74 65 20 61 20  ing to create a 
67c0: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54 53 35  contentless FTS5
67d0: 20 74 61 62 6c 65 2e 20 49 6e 0a 20 20 20 20 20   table. In.     
67e0: 20 20 74 68 69 73 20 63 61 73 65 20 46 54 53 35    this case FTS5
67f0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
6800: 65 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6c 75 6d  e original colum
6810: 6e 20 76 61 6c 75 65 73 20 61 72 65 20 75 6e 61  n values are una
6820: 76 61 69 6c 61 62 6c 65 0a 20 20 20 20 20 20 20  vailable.       
6830: 74 6f 20 69 74 20 77 68 65 6e 20 70 72 6f 63 65  to it when proce
6840: 73 73 69 6e 67 20 71 75 65 72 69 65 73 2e 20 46  ssing queries. F
6850: 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 69 65 73  ull-text queries
6860: 20 61 6e 64 20 73 6f 6d 65 20 61 75 78 69 6c 69   and some auxili
6870: 61 72 79 0a 20 20 20 20 20 20 20 66 75 6e 63 74  ary.       funct
6880: 69 6f 6e 73 20 63 61 6e 20 73 74 69 6c 6c 20 62  ions can still b
6890: 65 20 75 73 65 64 2c 20 62 75 74 20 6e 6f 20 63  e used, but no c
68a0: 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 70 61  olumn values apa
68b0: 72 74 20 66 72 6f 6d 20 74 68 65 20 72 6f 77 69  rt from the rowi
68c0: 64 0a 20 20 20 20 20 20 20 6d 61 79 20 62 65 20  d.       may be 
68d0: 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 74 61  read from the ta
68e0: 62 6c 65 2e 0a 0a 20 20 3c 6c 69 3e 20 42 79 20  ble...  <li> By 
68f0: 73 65 74 74 69 6e 67 20 69 74 20 74 6f 20 74 68  setting it to th
6900: 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61  e name of a data
6910: 62 61 73 65 20 6f 62 6a 65 63 74 20 28 74 61 62  base object (tab
6920: 6c 65 2c 20 76 69 72 74 75 61 6c 20 74 61 62 6c  le, virtual tabl
6930: 65 20 6f 72 0a 20 20 20 20 20 20 20 76 69 65 77  e or.       view
6940: 29 20 74 68 61 74 20 6d 61 79 20 62 65 20 71 75  ) that may be qu
6950: 65 72 69 65 64 20 62 79 20 46 54 53 35 20 61 74  eried by FTS5 at
6960: 20 61 6e 79 20 74 69 6d 65 20 74 6f 20 72 65 74   any time to ret
6970: 72 69 65 76 65 20 74 68 65 20 63 6f 6c 75 6d 6e  rieve the column
6980: 0a 20 20 20 20 20 20 20 76 61 6c 75 65 73 2e 20  .       values. 
6990: 54 68 69 73 20 69 73 20 6b 6e 6f 77 6e 20 61 73  This is known as
69a0: 20 61 6e 20 22 65 78 74 65 72 6e 61 6c 20 63 6f   an "external co
69b0: 6e 74 65 6e 74 22 20 74 61 62 6c 65 2e 20 49 6e  ntent" table. In
69c0: 20 74 68 69 73 20 63 61 73 65 20 61 6c 6c 0a 20   this case all. 
69d0: 20 20 20 20 20 20 46 54 53 35 20 66 75 6e 63 74        FTS5 funct
69e0: 69 6f 6e 61 6c 69 74 79 20 6d 61 79 20 62 65 20  ionality may be 
69f0: 75 73 65 64 2c 20 62 75 74 20 69 74 20 69 73 20  used, but it is 
6a00: 74 68 65 20 72 65 73 70 6f 6e 73 69 62 69 6c 69  the responsibili
6a10: 74 79 20 6f 66 20 74 68 65 20 75 73 65 72 0a 20  ty of the user. 
6a20: 20 20 20 20 20 20 74 6f 20 65 6e 73 75 72 65 20        to ensure 
6a30: 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
6a40: 73 20 6f 66 20 74 68 65 20 66 75 6c 6c 2d 74 65  s of the full-te
6a50: 78 74 20 69 6e 64 65 78 20 61 72 65 20 63 6f 6e  xt index are con
6a60: 73 69 73 74 65 6e 74 20 77 69 74 68 0a 20 20 20  sistent with.   
6a70: 20 20 20 20 74 68 65 20 6e 61 6d 65 64 20 64 61      the named da
6a80: 74 61 62 61 73 65 20 6f 62 6a 65 63 74 2e 20 49  tabase object. I
6a90: 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 2c 20  f they are not, 
6aa0: 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 6d 61  query results ma
6ab0: 79 20 62 65 0a 20 20 20 20 20 20 20 75 6e 70 72  y be.       unpr
6ac0: 65 64 69 63 74 61 62 6c 65 2e 20 20 0a 3c 2f 75  edictable.  .</u
6ad0: 6c 3e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46 54  l>..<h3 tags="FT
6ae0: 53 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74  S5 contentless t
6af0: 61 62 6c 65 73 22 3e 43 6f 6e 74 65 6e 74 6c 65  ables">Contentle
6b00: 73 73 20 54 61 62 6c 65 73 3c 2f 68 33 3e 0a 0a  ss Tables</h3>..
6b10: 3c 70 3e 20 41 20 63 6f 6e 74 65 6e 74 6c 65 73  <p> A contentles
6b20: 73 20 46 54 53 35 20 74 61 62 6c 65 20 69 73 20  s FTS5 table is 
6b30: 63 72 65 61 74 65 64 20 62 79 20 73 65 74 74 69  created by setti
6b40: 6e 67 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 22  ng the "content"
6b50: 20 6f 70 74 69 6f 6e 20 74 6f 0a 61 6e 20 65 6d   option to.an em
6b60: 70 74 79 20 73 74 72 69 6e 67 2e 20 46 6f 72 20  pty string. For 
6b70: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
6b80: 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20 56  lock>.  CREATE V
6b90: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 31 20  IRTUAL TABLE f1 
6ba0: 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c  USING fts5(a, b,
6bb0: 20 63 2c 20 63 6f 6e 74 65 6e 74 3d 27 27 29 3b   c, content='');
6bc0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
6bd0: 70 3e 20 43 6f 6e 74 65 6e 74 6c 65 73 73 20 46  p> Contentless F
6be0: 54 53 35 20 74 61 62 6c 65 73 20 64 6f 20 6e 6f  TS5 tables do no
6bf0: 74 20 73 75 70 70 6f 72 74 20 55 50 44 41 54 45  t support UPDATE
6c00: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
6c10: 6d 65 6e 74 73 2c 20 6f 72 0a 49 4e 53 45 52 54  ments, or.INSERT
6c20: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
6c30: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6c 79 20 61   do not supply a
6c40: 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20   non-NULL value 
6c50: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 20 66 69  for the rowid fi
6c60: 65 6c 64 2e 0a 43 6f 6e 74 65 6e 74 6c 65 73 73  eld..Contentless
6c70: 20 74 61 62 6c 65 73 20 64 6f 20 6e 6f 74 20 73   tables do not s
6c80: 75 70 70 6f 72 74 20 52 45 50 4c 41 43 45 20 63  upport REPLACE c
6c90: 6f 6e 66 6c 69 63 74 20 68 61 6e 64 6c 69 6e 67  onflict handling
6ca0: 2e 20 52 45 50 4c 41 43 45 20 0a 61 6e 64 20 49  . REPLACE .and I
6cb0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
6cc0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
6cd0: 74 72 65 61 74 65 64 20 61 73 20 72 65 67 75 6c  treated as regul
6ce0: 61 72 20 49 4e 53 45 52 54 20 73 74 61 74 65 6d  ar INSERT statem
6cf0: 65 6e 74 73 2e 0a 52 6f 77 73 20 6d 61 79 20 62  ents..Rows may b
6d00: 65 20 64 65 6c 65 74 65 64 20 66 72 6f 6d 20 61  e deleted from a
6d10: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62   contentless tab
6d20: 6c 65 20 75 73 69 6e 67 20 61 6e 20 5b 46 54 53  le using an [FTS
6d30: 35 20 64 65 6c 65 74 65 20 63 6f 6d 6d 61 6e 64  5 delete command
6d40: 5d 2e 0a 0a 3c 70 3e 20 41 74 74 65 6d 70 74 69  ]...<p> Attempti
6d50: 6e 67 20 74 6f 20 72 65 61 64 20 61 6e 79 20 63  ng to read any c
6d60: 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 65 78 63 65  olumn value exce
6d70: 70 74 20 74 68 65 20 72 6f 77 69 64 20 66 72 6f  pt the rowid fro
6d80: 6d 20 61 20 63 6f 6e 74 65 6e 74 6c 65 73 73 0a  m a contentless.
6d90: 46 54 53 35 20 74 61 62 6c 65 20 72 65 74 75 72  FTS5 table retur
6da0: 6e 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 20 76  ns an SQL NULL v
6db0: 61 6c 75 65 2e 0a 0a 3c 68 33 20 74 61 67 73 3d  alue...<h3 tags=
6dc0: 22 46 54 53 35 20 65 78 74 65 72 6e 61 6c 20 63  "FTS5 external c
6dd0: 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 22 3e 45  ontent tables">E
6de0: 78 74 65 72 6e 61 6c 20 43 6f 6e 74 65 6e 74 20  xternal Content 
6df0: 54 61 62 6c 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e  Tables</h3>..<p>
6e00: 20 41 6e 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e   An external con
6e10: 74 65 6e 74 20 46 54 53 35 20 74 61 62 6c 65 20  tent FTS5 table 
6e20: 69 73 20 63 72 65 61 74 65 64 20 62 79 20 73 65  is created by se
6e30: 74 74 69 6e 67 20 74 68 65 20 63 6f 6e 74 65 6e  tting the conten
6e40: 74 20 0a 6f 70 74 69 6f 6e 20 74 6f 20 74 68 65  t .option to the
6e50: 20 6e 61 6d 65 20 6f 66 20 61 20 74 61 62 6c 65   name of a table
6e60: 2c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  , virtual table 
6e70: 6f 72 20 76 69 65 77 20 28 68 65 72 65 61 66 74  or view (hereaft
6e80: 65 72 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 0a  er the "content.
6e90: 74 61 62 6c 65 22 29 20 77 69 74 68 69 6e 20 74  table") within t
6ea0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
6eb0: 2e 20 57 68 65 6e 65 76 65 72 20 63 6f 6c 75 6d  . Whenever colum
6ec0: 6e 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 71  n values are req
6ed0: 75 69 72 65 64 20 62 79 0a 46 54 53 35 2c 20 69  uired by.FTS5, i
6ee0: 74 20 71 75 65 72 69 65 73 20 74 68 65 20 63 6f  t queries the co
6ef0: 6e 74 65 6e 74 20 74 61 62 6c 65 20 61 73 20 66  ntent table as f
6f00: 6f 6c 6c 6f 77 73 2c 20 77 69 74 68 20 74 68 65  ollows, with the
6f10: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
6f20: 77 0a 66 6f 72 20 77 68 69 63 68 20 76 61 6c 75  w.for which valu
6f30: 65 73 20 61 72 65 20 72 65 71 75 69 72 65 64 20  es are required 
6f40: 62 6f 75 6e 64 20 74 6f 20 74 68 65 20 53 51 4c  bound to the SQL
6f50: 20 76 61 72 69 61 62 6c 65 3a 0a 0a 3c 63 6f 64   variable:..<cod
6f60: 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54  eblock>.  SELECT
6f70: 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77   &lt;content_row
6f80: 69 64 26 67 74 3b 2c 20 26 6c 74 3b 63 6f 6c 73  id&gt;, &lt;cols
6f90: 26 67 74 3b 20 46 52 4f 4d 20 26 6c 74 3b 63 6f  &gt; FROM &lt;co
6fa0: 6e 74 65 6e 74 26 67 74 3b 20 57 48 45 52 45 20  ntent&gt; WHERE 
6fb0: 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77 69  &lt;content_rowi
6fc0: 64 26 67 74 3b 20 3d 20 3f 3b 0a 3c 2f 63 6f 64  d&gt; = ?;.</cod
6fd0: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20  eblock>..<p> In 
6fe0: 74 68 65 20 61 62 6f 76 65 2c 20 26 6c 74 3b 63  the above, &lt;c
6ff0: 6f 6e 74 65 6e 74 26 67 74 3b 20 69 73 20 72 65  ontent&gt; is re
7000: 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 6e 61  placed by the na
7010: 6d 65 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  me of the conten
7020: 74 20 74 61 62 6c 65 2e 0a 42 79 20 64 65 66 61  t table..By defa
7030: 75 6c 74 2c 20 26 6c 74 3b 63 6f 6e 74 65 6e 74  ult, &lt;content
7040: 5f 72 6f 77 69 64 26 67 74 3b 20 69 73 20 72 65  _rowid&gt; is re
7050: 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 6c 69  placed by the li
7060: 74 65 72 61 6c 20 74 65 78 74 20 22 72 6f 77 69  teral text "rowi
7070: 64 22 2e 20 4f 72 2c 0a 69 66 20 74 68 65 20 22  d". Or,.if the "
7080: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 22 20 6f  content_rowid" o
7090: 70 74 69 6f 6e 20 69 73 20 73 65 74 20 77 69 74  ption is set wit
70a0: 68 69 6e 20 74 68 65 20 43 52 45 41 54 45 20 56  hin the CREATE V
70b0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61  IRTUAL TABLE sta
70c0: 74 65 6d 65 6e 74 2c 0a 62 79 20 74 68 65 20 76  tement,.by the v
70d0: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 6f 70 74  alue of that opt
70e0: 69 6f 6e 2e 20 26 6c 74 3b 63 6f 6c 73 26 67 74  ion. &lt;cols&gt
70f0: 3b 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79  ; is replaced by
7100: 20 61 20 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74   a comma-separat
7110: 65 64 20 6c 69 73 74 0a 6f 66 20 74 68 65 20 46  ed list.of the F
7120: 54 53 35 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  TS5 table column
7130: 20 6e 61 6d 65 73 2e 20 46 6f 72 20 65 78 61 6d   names. For exam
7140: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
7150: 3e 0a 20 20 3c 69 3e 2d 2d 20 49 66 20 74 68 65  >.  <i>-- If the
7160: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
7170: 20 69 73 3a 20 3c 2f 69 3e 0a 20 20 43 52 45 41   is: </i>.  CREA
7180: 54 45 20 54 41 42 4c 45 20 74 62 6c 20 28 61 2c  TE TABLE tbl (a,
7190: 20 62 2c 20 63 2c 20 64 20 49 4e 54 45 47 45 52   b, c, d INTEGER
71a0: 20 50 52 49 4d 41 52 59 20 4b 45 59 29 3b 0a 20   PRIMARY KEY);. 
71b0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
71c0: 54 41 42 4c 45 20 66 74 73 20 55 53 49 4e 47 20  TABLE fts USING 
71d0: 66 74 73 35 28 61 2c 20 63 2c 20 63 6f 6e 74 65  fts5(a, c, conte
71e0: 6e 74 3d 74 62 6c 2c 20 63 6f 6e 74 65 6e 74 5f  nt=tbl, content_
71f0: 72 6f 77 69 64 3d 64 29 3b 0a 0a 20 20 3c 69 3e  rowid=d);..  <i>
7200: 2d 2d 20 46 74 73 35 20 6d 61 79 20 69 73 73 75  -- Fts5 may issu
7210: 65 20 71 75 65 72 69 65 73 20 73 75 63 68 20 61  e queries such a
7220: 73 3a 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  s:</i>.  SELECT 
7230: 64 2c 20 61 2c 20 63 20 46 52 4f 4d 20 74 62 6c  d, a, c FROM tbl
7240: 20 57 48 45 52 45 20 64 20 3d 20 3f 3b 0a 3c 2f   WHERE d = ?;.</
7250: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20  codeblock>..<p> 
7260: 54 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  The content tabl
7270: 65 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 71 75  e may also be qu
7280: 65 72 69 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73  eried as follows
7290: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
72a0: 20 53 45 4c 45 43 54 20 26 6c 74 3b 63 6f 6e 74   SELECT &lt;cont
72b0: 65 6e 74 5f 72 6f 77 69 64 26 67 74 3b 2c 20 26  ent_rowid&gt;, &
72c0: 6c 74 3b 63 6f 6c 73 26 67 74 3b 20 46 52 4f 4d  lt;cols&gt; FROM
72d0: 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 26 67 74 3b   &lt;content&gt;
72e0: 20 4f 52 44 45 52 20 42 59 20 26 6c 74 3b 63 6f   ORDER BY &lt;co
72f0: 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74 3b 20  ntent_rowid&gt; 
7300: 41 53 43 3b 0a 20 20 53 45 4c 45 43 54 20 26 6c  ASC;.  SELECT &l
7310: 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26  t;content_rowid&
7320: 67 74 3b 2c 20 26 6c 74 3b 63 6f 6c 73 26 67 74  gt;, &lt;cols&gt
7330: 3b 20 46 52 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65  ; FROM &lt;conte
7340: 6e 74 26 67 74 3b 20 4f 52 44 45 52 20 42 59 20  nt&gt; ORDER BY 
7350: 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77 69  &lt;content_rowi
7360: 64 26 67 74 3b 20 44 45 53 43 3b 0a 3c 2f 63 6f  d&gt; DESC;.</co
7370: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 74  deblock>..<p> It
7380: 20 69 73 20 73 74 69 6c 6c 20 74 68 65 20 72 65   is still the re
7390: 73 70 6f 6e 73 69 62 69 6c 69 74 79 20 6f 66 20  sponsibility of 
73a0: 74 68 65 20 75 73 65 72 20 74 6f 20 65 6e 73 75  the user to ensu
73b0: 72 65 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  re that the cont
73c0: 65 6e 74 73 20 6f 66 0a 61 6e 20 65 78 74 65 72  ents of.an exter
73d0: 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 46 54 53 35  nal content FTS5
73e0: 20 74 61 62 6c 65 20 61 72 65 20 6b 65 70 74 20   table are kept 
73f0: 75 70 20 74 6f 20 64 61 74 65 20 77 69 74 68 20  up to date with 
7400: 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c  the content tabl
7410: 65 2e 20 0a 4f 6e 65 20 77 61 79 20 74 6f 20 64  e. .One way to d
7420: 6f 20 74 68 69 73 20 69 73 20 77 69 74 68 20 74  o this is with t
7430: 72 69 67 67 65 72 73 2e 20 46 6f 72 20 65 78 61  riggers. For exa
7440: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
7450: 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74  k>.  <i>-- Creat
7460: 65 20 61 20 74 61 62 6c 65 2e 20 41 6e 64 20 61  e a table. And a
7470: 6e 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  n external conte
7480: 6e 74 20 66 74 73 35 20 74 61 62 6c 65 20 74 6f  nt fts5 table to
7490: 20 69 6e 64 65 78 20 69 74 2e 3c 2f 69 3e 0a 20   index it.</i>. 
74a0: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 62   CREATE TABLE tb
74b0: 6c 28 61 20 49 4e 54 45 47 45 52 20 50 52 49 4d  l(a INTEGER PRIM
74c0: 41 52 59 20 4b 45 59 2c 20 62 2c 20 63 29 3b 0a  ARY KEY, b, c);.
74d0: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
74e0: 20 54 41 42 4c 45 20 66 74 73 5f 69 64 78 20 55   TABLE fts_idx U
74f0: 53 49 4e 47 20 66 74 73 35 28 62 2c 20 63 2c 20  SING fts5(b, c, 
7500: 63 6f 6e 74 65 6e 74 3d 27 74 62 6c 27 2c 20 63  content='tbl', c
7510: 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 3d 27 61 27  ontent_rowid='a'
7520: 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 72 69 67  );..  <i>-- Trig
7530: 67 65 72 73 20 74 6f 20 6b 65 65 70 20 74 68 65  gers to keep the
7540: 20 46 54 53 20 69 6e 64 65 78 20 75 70 20 74 6f   FTS index up to
7550: 20 64 61 74 65 2e 3c 2f 69 3e 0a 20 20 43 52 45   date.</i>.  CRE
7560: 41 54 45 20 54 52 49 47 47 45 52 20 74 62 6c 5f  ATE TRIGGER tbl_
7570: 61 69 20 41 46 54 45 52 20 49 4e 53 45 52 54 20  ai AFTER INSERT 
7580: 4f 4e 20 74 62 6c 20 42 45 47 49 4e 0a 20 20 20  ON tbl BEGIN.   
7590: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 73   INSERT INTO fts
75a0: 5f 69 64 78 28 72 6f 77 69 64 2c 20 62 2c 20 63  _idx(rowid, b, c
75b0: 29 20 56 41 4c 55 45 53 20 28 6e 65 77 2e 61 2c  ) VALUES (new.a,
75c0: 20 6e 65 77 2e 62 2c 20 6e 65 77 2e 63 29 3b 0a   new.b, new.c);.
75d0: 20 20 45 4e 44 3b 0a 20 20 43 52 45 41 54 45 20    END;.  CREATE 
75e0: 54 52 49 47 47 45 52 20 74 62 6c 5f 61 64 20 41  TRIGGER tbl_ad A
75f0: 46 54 45 52 20 44 45 4c 45 54 45 20 4f 4e 20 74  FTER DELETE ON t
7600: 62 6c 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53  bl BEGIN.    INS
7610: 45 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78  ERT INTO fts_idx
7620: 28 66 74 73 5f 69 64 78 2c 20 72 6f 77 69 64 2c  (fts_idx, rowid,
7630: 20 62 2c 20 63 29 20 56 41 4c 55 45 53 28 27 64   b, c) VALUES('d
7640: 65 6c 65 74 65 27 2c 20 6f 6c 64 2e 61 2c 20 6f  elete', old.a, o
7650: 6c 64 2e 62 2c 20 6f 6c 64 2e 63 29 3b 0a 20 20  ld.b, old.c);.  
7660: 45 4e 44 3b 0a 20 20 43 52 45 41 54 45 20 54 52  END;.  CREATE TR
7670: 49 47 47 45 52 20 74 62 6c 5f 61 75 20 41 46 54  IGGER tbl_au AFT
7680: 45 52 20 55 50 44 41 54 45 20 4f 4e 20 74 62 6c  ER UPDATE ON tbl
7690: 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53 45 52   BEGIN.    INSER
76a0: 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78 28 66  T INTO fts_idx(f
76b0: 74 73 5f 69 64 78 2c 20 72 6f 77 69 64 2c 20 62  ts_idx, rowid, b
76c0: 2c 20 63 29 20 56 41 4c 55 45 53 28 27 64 65 6c  , c) VALUES('del
76d0: 65 74 65 27 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64  ete', old.a, old
76e0: 2e 62 2c 20 6f 6c 64 2e 63 29 3b 0a 20 20 20 20  .b, old.c);.    
76f0: 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 73 5f  INSERT INTO fts_
7700: 69 64 78 28 72 6f 77 69 64 2c 20 62 2c 20 63 29  idx(rowid, b, c)
7710: 20 56 41 4c 55 45 53 20 28 6e 65 77 2e 61 2c 20   VALUES (new.a, 
7720: 6e 65 77 2e 62 2c 20 6e 65 77 2e 63 29 3b 0a 20  new.b, new.c);. 
7730: 20 45 4e 44 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63   END;.</codebloc
7740: 6b 3e 0a 0a 3c 70 3e 20 4c 69 6b 65 20 63 6f 6e  k>..<p> Like con
7750: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 2c  tentless tables,
7760: 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e   external conten
7770: 74 20 74 61 62 6c 65 73 20 64 6f 20 6e 6f 74 20  t tables do not 
7780: 73 75 70 70 6f 72 74 20 52 45 50 4c 41 43 45 0a  support REPLACE.
7790: 63 6f 6e 66 6c 69 63 74 20 68 61 6e 64 6c 69 6e  conflict handlin
77a0: 67 2e 20 41 6e 79 20 6f 70 65 72 61 74 69 6f 6e  g. Any operation
77b0: 73 20 74 68 61 74 20 73 70 65 63 69 66 79 20 52  s that specify R
77c0: 45 50 4c 41 43 45 20 63 6f 6e 66 6c 69 63 74 20  EPLACE conflict 
77d0: 68 61 6e 64 6c 69 6e 67 20 61 72 65 0a 68 61 6e  handling are.han
77e0: 64 6c 65 64 20 75 73 69 6e 67 20 41 42 4f 52 54  dled using ABORT
77f0: 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53  ...<h2 tags="FTS
7800: 35 20 63 6f 6c 75 6d 6e 73 69 7a 65 20 6f 70 74  5 columnsize opt
7810: 69 6f 6e 22 3e 54 68 65 20 43 6f 6c 75 6d 6e 73  ion">The Columns
7820: 69 7a 65 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a  ize Option</h2>.
7830: 0a 3c 70 3e 4e 6f 72 6d 61 6c 6c 79 2c 20 46 54  .<p>Normally, FT
7840: 53 35 20 6d 61 69 6e 74 61 69 6e 73 20 61 20 73  S5 maintains a s
7850: 70 65 63 69 61 6c 20 62 61 63 6b 69 6e 67 20 74  pecial backing t
7860: 61 62 6c 65 20 77 69 74 68 69 6e 20 74 68 65 20  able within the 
7870: 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 73 74  database that.st
7880: 6f 72 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66  ores the size of
7890: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 76 61 6c   each column val
78a0: 75 65 20 69 6e 20 74 6f 6b 65 6e 73 20 69 6e 73  ue in tokens ins
78b0: 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65 20 6d  erted into the m
78c0: 61 69 6e 20 46 54 53 35 0a 74 61 62 6c 65 20 69  ain FTS5.table i
78d0: 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 61 62  n a separate tab
78e0: 6c 65 2e 20 54 68 69 73 20 62 61 63 6b 69 6e 67  le. This backing
78f0: 20 74 61 62 6c 65 20 69 73 20 75 73 65 64 20 62   table is used b
7900: 79 20 74 68 65 0a 3c 61 20 68 72 65 66 3d 23 78  y the.<a href=#x
7910: 43 6f 6c 75 6d 6e 53 69 7a 65 3e 78 43 6f 6c 75  ColumnSize>xColu
7920: 6d 6e 53 69 7a 65 3c 61 3e 20 41 50 49 20 66 75  mnSize<a> API fu
7930: 6e 63 74 69 6f 6e 2c 20 77 68 69 63 68 20 69 73  nction, which is
7940: 20 69 6e 20 74 75 72 6e 20 75 73 65 64 20 62 79   in turn used by
7950: 0a 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 46  .the built-in [F
7960: 54 53 35 20 62 6d 32 35 20 7c 20 62 6d 32 35 20  TS5 bm25 | bm25 
7970: 72 61 6e 6b 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ranking function
7980: 5d 20 28 61 6e 64 20 69 73 20 6c 69 6b 65 6c 79  ] (and is likely
7990: 20 74 6f 20 62 65 20 75 73 65 66 75 6c 20 0a 74   to be useful .t
79a0: 6f 20 6f 74 68 65 72 20 72 61 6e 6b 69 6e 67 20  o other ranking 
79b0: 66 75 6e 63 74 69 6f 6e 73 20 61 73 20 77 65 6c  functions as wel
79c0: 6c 29 2e 0a 0a 3c 70 3e 49 6e 20 6f 72 64 65 72  l)...<p>In order
79d0: 20 74 6f 20 73 61 76 65 20 73 70 61 63 65 2c 20   to save space, 
79e0: 74 68 69 73 20 62 61 63 6b 69 6e 67 20 74 61 62  this backing tab
79f0: 6c 65 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  le may be omitte
7a00: 64 20 62 79 20 73 65 74 74 69 6e 67 20 74 68 65  d by setting the
7a10: 0a 63 6f 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69  .columnsize opti
7a20: 6f 6e 20 74 6f 20 7a 65 72 6f 2e 20 46 6f 72 20  on to zero. For 
7a30: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
7a40: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 41 20  lock>.  <i>-- A 
7a50: 74 61 62 6c 65 20 77 69 74 68 6f 75 74 20 74 68  table without th
7a60: 65 20 78 43 6f 6c 75 6d 6e 53 69 7a 65 28 29 20  e xColumnSize() 
7a70: 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20 6f 6e  values stored on
7a80: 20 64 69 73 6b 3a 3c 2f 69 3e 0a 20 20 43 52 45   disk:</i>.  CRE
7a90: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
7aa0: 45 20 66 74 20 55 53 49 4e 47 20 66 74 73 35 28  E ft USING fts5(
7ab0: 61 2c 20 62 2c 20 63 2c 20 63 6f 6c 75 6d 6e 73  a, b, c, columns
7ac0: 69 7a 65 3d 30 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  ize=0);..  <i>--
7ad0: 20 54 68 72 65 65 20 65 71 75 69 76 61 6c 65 6e   Three equivalen
7ae0: 74 20 77 61 79 73 20 6f 66 20 63 72 65 61 74 69  t ways of creati
7af0: 6e 67 20 61 20 74 61 62 6c 65 20 74 68 61 74 20  ng a table that 
7b00: 64 6f 65 73 20 73 74 6f 72 65 20 74 68 65 3c 2f  does store the</
7b10: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 78 43 6f 6c 75  i>.  <i>-- xColu
7b20: 6d 6e 53 69 7a 65 28 29 20 76 61 6c 75 65 73 20  mnSize() values 
7b30: 6f 6e 20 64 69 73 6b 3a 3c 2f 69 3e 0a 20 20 43  on disk:</i>.  C
7b40: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
7b50: 42 4c 45 20 66 74 20 55 53 49 4e 47 20 66 74 73  BLE ft USING fts
7b60: 35 28 61 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52  5(a, b, c);.  CR
7b70: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
7b80: 4c 45 20 66 74 20 55 53 49 4e 47 20 66 74 73 35  LE ft USING fts5
7b90: 28 61 2c 20 62 2c 20 63 2c 20 63 6f 6c 75 6d 6e  (a, b, c, column
7ba0: 73 69 7a 65 3d 31 29 3b 0a 20 20 43 52 45 41 54  size=1);.  CREAT
7bb0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
7bc0: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
7bd0: 20 62 2c 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d 27   b, columnsize='
7be0: 31 27 2c 20 63 29 3b 0a 3c 2f 63 6f 64 65 62 6c  1', c);.</codebl
7bf0: 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 74 20 69 73 20  ock>..<p> It is 
7c00: 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 65 74 20  an error to set 
7c10: 74 68 65 20 63 6f 6c 75 6d 6e 73 69 7a 65 20 6f  the columnsize o
7c20: 70 74 69 6f 6e 20 74 6f 20 61 6e 79 20 76 61 6c  ption to any val
7c30: 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 30 20  ue other than.0 
7c40: 6f 72 20 31 2e 0a 0a 3c 70 3e 20 49 66 20 61 6e  or 1...<p> If an
7c50: 20 46 54 53 35 20 74 61 62 6c 65 20 69 73 20 63   FTS5 table is c
7c60: 6f 6e 66 69 67 75 72 65 64 20 77 69 74 68 20 63  onfigured with c
7c70: 6f 6c 75 6d 6e 73 69 7a 65 3d 30 20 62 75 74 20  olumnsize=0 but 
7c80: 69 73 20 6e 6f 74 20 61 0a 5b 46 54 53 35 20 63  is not a.[FTS5 c
7c90: 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
7ca0: 73 20 7c 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20  s | contentless 
7cb0: 74 61 62 6c 65 5d 2c 20 74 68 65 20 78 43 6f 6c  table], the xCol
7cc0: 75 6d 6e 53 69 7a 65 20 41 50 49 20 66 75 6e 63  umnSize API func
7cd0: 74 69 6f 6e 0a 73 74 69 6c 6c 20 77 6f 72 6b 73  tion.still works
7ce0: 2c 20 62 75 74 20 72 75 6e 73 20 6d 75 63 68 20  , but runs much 
7cf0: 6d 6f 72 65 20 73 6c 6f 77 6c 79 2e 20 49 6e 20  more slowly. In 
7d00: 74 68 69 73 20 63 61 73 65 2c 20 69 6e 73 74 65  this case, inste
7d10: 61 64 20 6f 66 20 72 65 61 64 69 6e 67 0a 74 68  ad of reading.th
7d20: 65 20 76 61 6c 75 65 20 74 6f 20 72 65 74 75 72  e value to retur
7d30: 6e 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  n directly from 
7d40: 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 69 74  the database, it
7d50: 20 72 65 61 64 73 20 74 68 65 20 74 65 78 74 20   reads the text 
7d60: 76 61 6c 75 65 0a 69 74 73 65 6c 66 20 61 6e 64  value.itself and
7d70: 20 63 6f 75 6e 74 20 74 68 65 20 74 6f 6b 65 6e   count the token
7d80: 73 20 77 69 74 68 69 6e 20 69 74 20 6f 6e 20 64  s within it on d
7d90: 65 6d 61 6e 64 2e 0a 0a 3c 70 3e 4f 72 2c 20 69  emand...<p>Or, i
7da0: 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61  f the table is a
7db0: 6c 73 6f 20 61 20 5b 46 54 53 35 20 63 6f 6e 74  lso a [FTS5 cont
7dc0: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c  entless tables |
7dd0: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62   contentless tab
7de0: 6c 65 5d 2c 0a 74 68 65 6e 20 74 68 65 20 66 6f  le],.then the fo
7df0: 6c 6c 6f 77 69 6e 67 20 61 70 70 6c 79 3a 0a 0a  llowing apply:..
7e00: 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 54  <ul>.  <li> <p>T
7e10: 68 65 20 78 43 6f 6c 75 6d 6e 53 69 7a 65 20 41  he xColumnSize A
7e20: 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
7e30: 73 20 2d 31 2e 20 54 68 65 72 65 20 69 73 20 6e  s -1. There is n
7e40: 6f 20 77 61 79 20 74 6f 20 64 65 74 65 72 6d 69  o way to determi
7e50: 6e 65 20 0a 20 20 20 20 20 20 20 74 68 65 20 6e  ne .       the n
7e60: 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20  umber of tokens 
7e70: 69 6e 20 61 20 76 61 6c 75 65 20 73 74 6f 72 65  in a value store
7e80: 64 20 77 69 74 68 69 6e 20 61 20 63 6f 6e 74 65  d within a conte
7e90: 6e 74 6c 65 73 73 20 46 54 53 35 20 74 61 62 6c  ntless FTS5 tabl
7ea0: 65 0a 20 20 20 20 20 20 20 63 6f 6e 66 69 67 75  e.       configu
7eb0: 72 65 64 20 77 69 74 68 20 63 6f 6c 75 6d 6e 73  red with columns
7ec0: 69 7a 65 3d 30 2e 0a 0a 20 20 3c 6c 69 3e 20 3c  ize=0...  <li> <
7ed0: 70 3e 45 61 63 68 20 69 6e 73 65 72 74 65 64 20  p>Each inserted 
7ee0: 72 6f 77 20 6d 75 73 74 20 62 65 20 61 63 63 6f  row must be acco
7ef0: 6d 70 61 6e 69 65 64 20 62 79 20 61 6e 20 65 78  mpanied by an ex
7f00: 70 6c 69 63 69 74 6c 79 20 73 70 65 63 69 66 69  plicitly specifi
7f10: 65 64 20 72 6f 77 69 64 0a 20 20 20 20 20 20 20  ed rowid.       
7f20: 76 61 6c 75 65 2e 20 49 66 20 61 20 63 6f 6e 74  value. If a cont
7f30: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 20 69 73  entless table is
7f40: 20 63 6f 6e 66 69 67 75 72 65 64 20 77 69 74 68   configured with
7f50: 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d 30 2c 0a 20   columnsize=0,. 
7f60: 20 20 20 20 20 20 61 74 74 65 6d 70 74 69 6e 67        attempting
7f70: 20 74 6f 20 69 6e 73 65 72 74 20 61 20 4e 55 4c   to insert a NUL
7f80: 4c 20 76 61 6c 75 65 20 69 6e 74 6f 20 74 68 65  L value into the
7f90: 20 72 6f 77 69 64 20 69 73 20 61 6e 20 53 51 4c   rowid is an SQL
7fa0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 0a 20 20 20  ITE_MISMATCH.   
7fb0: 20 20 20 20 65 72 72 6f 72 2e 0a 0a 20 20 3c 6c      error...  <l
7fc0: 69 3e 20 3c 70 3e 41 6c 6c 20 71 75 65 72 69 65  i> <p>All querie
7fd0: 73 20 6f 6e 20 74 68 65 20 74 61 62 6c 65 20 6d  s on the table m
7fe0: 75 73 74 20 62 65 20 66 75 6c 6c 2d 74 65 78 74  ust be full-text
7ff0: 20 71 75 65 72 69 65 73 2e 20 49 6e 20 6f 74 68   queries. In oth
8000: 65 72 20 77 6f 72 64 73 2c 0a 20 20 20 20 20 20  er words,.      
8010: 20 74 68 65 79 20 6d 75 73 74 20 75 73 65 20 74   they must use t
8020: 68 65 20 4d 41 54 43 48 20 6f 72 20 3d 20 6f 70  he MATCH or = op
8030: 65 72 61 74 6f 72 20 77 69 74 68 20 74 68 65 20  erator with the 
8040: 74 61 62 6c 65 2d 6e 61 6d 65 20 63 6f 6c 75 6d  table-name colum
8050: 6e 20 61 73 20 74 68 65 0a 20 20 20 20 20 20 20  n as the.       
8060: 6c 65 66 74 2d 68 61 6e 64 20 6f 70 65 72 61 6e  left-hand operan
8070: 64 2c 20 6f 72 20 65 6c 73 65 20 75 73 65 20 74  d, or else use t
8080: 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  he table-valued 
8090: 66 75 6e 63 74 69 6f 6e 20 73 79 6e 74 61 78 2e  function syntax.
80a0: 20 41 6e 79 0a 20 20 20 20 20 20 20 71 75 65 72   Any.       quer
80b0: 79 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  y that is not a 
80c0: 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 20  full-text query 
80d0: 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 65 72  results in an er
80e0: 72 6f 72 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20  ror..</ul>..<p> 
80f0: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
8100: 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 74  table in which t
8110: 68 65 20 78 43 6f 6c 75 6d 6e 53 69 7a 65 20 76  he xColumnSize v
8120: 61 6c 75 65 73 20 61 72 65 20 73 74 6f 72 65 64  alues are stored
8130: 0a 28 75 6e 6c 65 73 73 20 63 6f 6c 75 6d 6e 73  .(unless columns
8140: 69 7a 65 3d 30 20 69 73 20 73 70 65 63 69 66 69  ize=0 is specifi
8150: 65 64 29 20 69 73 20 22 26 6c 74 3b 6e 61 6d 65  ed) is "&lt;name
8160: 26 67 74 3b 5f 64 6f 63 73 69 7a 65 22 2c 20 77  &gt;_docsize", w
8170: 68 65 72 65 20 0a 26 6c 74 3b 6e 61 6d 65 26 67  here .&lt;name&g
8180: 74 3b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  t; is the name o
8190: 66 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65  f the FTS5 table
81a0: 20 69 74 73 65 6c 66 2e 20 54 68 65 20 0a 3c 61   itself. The .<a
81b0: 20 68 72 65 66 3d 68 74 74 70 73 3a 2f 2f 77 77   href=https://ww
81c0: 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 64 6f 77  w.sqlite.org/dow
81d0: 6e 6c 6f 61 64 2e 68 74 6d 6c 3e 73 71 6c 69 74  nload.html>sqlit
81e0: 65 33 5f 61 6e 61 6c 79 7a 65 72 3c 2f 61 3e 0a  e3_analyzer</a>.
81f0: 74 6f 6f 6c 20 6d 61 79 20 62 65 20 75 73 65 64  tool may be used
8200: 20 6f 6e 20 61 6e 20 65 78 69 73 74 69 6e 67 20   on an existing 
8210: 64 61 74 61 62 61 73 65 20 69 6e 20 6f 72 64 65  database in orde
8220: 72 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 68  r to determine h
8230: 6f 77 20 6d 75 63 68 0a 73 70 61 63 65 20 6d 69  ow much.space mi
8240: 67 68 74 20 62 65 20 73 61 76 65 64 20 62 79 20  ght be saved by 
8250: 72 65 63 72 65 61 74 69 6e 67 20 61 6e 20 46 54  recreating an FT
8260: 53 35 20 74 61 62 6c 65 20 75 73 69 6e 67 20 63  S5 table using c
8270: 6f 6c 75 6d 6e 73 69 7a 65 3d 30 2e 0a 0a 3c 68  olumnsize=0...<h
8280: 32 20 74 61 67 73 3d 22 46 54 53 35 20 64 65 74  2 tags="FTS5 det
8290: 61 69 6c 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20  ail option">The 
82a0: 44 65 74 61 69 6c 20 4f 70 74 69 6f 6e 3c 2f 68  Detail Option</h
82b0: 32 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65 61 63 68  2>..<p> For each
82c0: 20 74 65 72 6d 20 69 6e 20 61 20 64 6f 63 75 6d   term in a docum
82d0: 65 6e 74 2c 20 74 68 65 20 46 54 53 20 69 6e 64  ent, the FTS ind
82e0: 65 78 20 6d 61 69 6e 74 61 69 6e 65 64 20 62 79  ex maintained by
82f0: 20 46 54 53 35 20 0a 73 74 6f 72 65 73 20 74 68   FTS5 .stores th
8300: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 64  e rowid of the d
8310: 6f 63 75 6d 65 6e 74 2c 20 74 68 65 20 63 6f 6c  ocument, the col
8320: 75 6d 6e 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  umn number of th
8330: 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 63 6f  e column that co
8340: 6e 74 61 69 6e 73 0a 74 68 65 20 74 65 72 6d 20  ntains.the term 
8350: 61 6e 64 20 74 68 65 20 6f 66 66 73 65 74 20 6f  and the offset o
8360: 66 20 74 68 65 20 74 65 72 6d 20 77 69 74 68 69  f the term withi
8370: 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  n the column val
8380: 75 65 2e 20 54 68 65 20 22 64 65 74 61 69 6c 22  ue. The "detail"
8390: 0a 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75  .option may be u
83a0: 73 65 64 20 74 6f 20 6f 6d 69 74 20 73 6f 6d 65  sed to omit some
83b0: 20 6f 66 20 74 68 69 73 20 69 6e 66 6f 72 6d 61   of this informa
83c0: 74 69 6f 6e 2e 20 54 68 69 73 20 72 65 64 75 63  tion. This reduc
83d0: 65 73 20 74 68 65 20 73 70 61 63 65 0a 74 68 61  es the space.tha
83e0: 74 20 74 68 65 20 69 6e 64 65 78 20 63 6f 6e 73  t the index cons
83f0: 75 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  umes within the 
8400: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
8410: 75 74 20 61 6c 73 6f 20 72 65 64 75 63 65 73 20  ut also reduces 
8420: 74 68 65 0a 63 61 70 61 62 69 6c 69 74 79 20 61  the.capability a
8430: 6e 64 20 65 66 66 69 63 69 65 6e 63 79 20 6f 66  nd efficiency of
8440: 20 74 68 65 20 73 79 73 74 65 6d 2e 0a 0a 3c 70   the system...<p
8450: 3e 20 54 68 65 20 64 65 74 61 69 6c 20 6f 70 74  > The detail opt
8460: 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 74  ion may be set t
8470: 6f 20 22 66 75 6c 6c 22 20 28 74 68 65 20 64 65  o "full" (the de
8480: 66 61 75 6c 74 20 76 61 6c 75 65 29 2c 20 22 63  fault value), "c
8490: 6f 6c 75 6d 6e 22 20 6f 72 0a 22 6e 6f 6e 65 22  olumn" or."none"
84a0: 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  . For example:..
84b0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
84c0: 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  >-- The followin
84d0: 67 20 74 77 6f 20 6c 69 6e 65 73 20 61 72 65 20  g two lines are 
84e0: 65 71 75 69 76 61 6c 65 6e 74 20 28 62 65 63 61  equivalent (beca
84f0: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
8500: 76 61 6c 75 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  value</i>.  <i>-
8510: 2d 20 6f 66 20 22 64 65 74 61 69 6c 22 20 69 73  - of "detail" is
8520: 20 22 66 75 6c 6c 22 2e 20 3c 2f 69 3e 0a 20 20   "full". </i>.  
8530: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
8540: 41 42 4c 45 20 66 74 31 20 55 53 49 4e 47 20 66  ABLE ft1 USING f
8550: 74 73 35 28 61 2c 20 62 2c 20 63 29 3b 0a 20 20  ts5(a, b, c);.  
8560: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
8570: 41 42 4c 45 20 66 74 31 20 55 53 49 4e 47 20 66  ABLE ft1 USING f
8580: 74 73 35 28 61 2c 20 62 2c 20 63 2c 20 64 65 74  ts5(a, b, c, det
8590: 61 69 6c 3d 66 75 6c 6c 29 3b 0a 0a 20 20 43 52  ail=full);..  CR
85a0: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
85b0: 4c 45 20 66 74 32 20 55 53 49 4e 47 20 66 74 73  LE ft2 USING fts
85c0: 35 28 61 2c 20 62 2c 20 63 2c 20 64 65 74 61 69  5(a, b, c, detai
85d0: 6c 3d 63 6f 6c 75 6d 6e 29 3b 0a 20 20 43 52 45  l=column);.  CRE
85e0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
85f0: 45 20 66 74 33 20 55 53 49 4e 47 20 66 74 73 35  E ft3 USING fts5
8600: 28 61 2c 20 62 2c 20 63 2c 20 64 65 74 61 69 6c  (a, b, c, detail
8610: 3d 6e 6f 6e 65 29 3b 0a 3c 2f 63 6f 64 65 62 6c  =none);.</codebl
8620: 6f 63 6b 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20  ock>..<p>If the 
8630: 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e 20 69 73  detail option is
8640: 20 73 65 74 20 74 6f 20 3c 62 3e 63 6f 6c 75 6d   set to <b>colum
8650: 6e 3c 2f 62 3e 2c 20 74 68 65 6e 20 66 6f 72 20  n</b>, then for 
8660: 65 61 63 68 20 74 65 72 6d 20 74 68 65 20 46 54  each term the FT
8670: 53 0a 69 6e 64 65 78 20 72 65 63 6f 72 64 73 20  S.index records 
8680: 74 68 65 20 72 6f 77 69 64 20 61 6e 64 20 63 6f  the rowid and co
8690: 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 6f 6e 6c 79  lumn number only
86a0: 2c 20 6f 6d 69 74 74 69 6e 67 20 74 68 65 20 74  , omitting the t
86b0: 65 72 6d 20 6f 66 66 73 65 74 0a 69 6e 66 6f 72  erm offset.infor
86c0: 6d 61 74 69 6f 6e 2e 20 54 68 69 73 20 72 65 73  mation. This res
86d0: 75 6c 74 73 20 69 6e 20 74 68 65 20 66 6f 6c 6c  ults in the foll
86e0: 6f 77 69 6e 67 20 72 65 73 74 72 69 63 74 69 6f  owing restrictio
86f0: 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e  ns:..<ul>.  <li>
8700: 20 4e 45 41 52 20 71 75 65 72 69 65 73 20 61 72   NEAR queries ar
8710: 65 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 2e  e not available.
8720: 0a 20 20 3c 6c 69 3e 20 50 68 72 61 73 65 20 71  .  <li> Phrase q
8730: 75 65 72 69 65 73 20 61 72 65 20 6e 6f 74 20 61  ueries are not a
8740: 76 61 69 6c 61 62 6c 65 2e 0a 20 20 3c 6c 69 3e  vailable..  <li>
8750: 20 41 73 73 75 6d 69 6e 67 20 74 68 65 20 74 61   Assuming the ta
8760: 62 6c 65 20 69 73 20 6e 6f 74 20 61 6c 73 6f 20  ble is not also 
8770: 61 20 0a 20 20 5b 46 54 53 35 20 63 6f 6e 74 65  a .  [FTS5 conte
8780: 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c 20  ntless tables | 
8790: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
87a0: 65 5d 2c 20 74 68 65 20 0a 20 20 3c 61 20 68 72  e], the .  <a hr
87b0: 65 66 3d 23 78 49 6e 73 74 43 6f 75 6e 74 3e 78  ef=#xInstCount>x
87c0: 49 6e 73 74 43 6f 75 6e 74 3c 2f 61 3e 2c 20 3c  InstCount</a>, <
87d0: 61 20 68 72 65 66 3d 23 78 49 6e 73 74 3e 78 49  a href=#xInst>xI
87e0: 6e 73 74 3c 2f 61 3e 2c 20 0a 20 20 3c 61 20 68  nst</a>, .  <a h
87f0: 72 65 66 3d 23 78 50 68 72 61 73 65 46 69 72 73  ref=#xPhraseFirs
8800: 74 3e 78 50 68 72 61 73 65 46 69 72 73 74 3c 2f  t>xPhraseFirst</
8810: 61 3e 20 61 6e 64 20 3c 61 20 68 72 65 66 3d 23  a> and <a href=#
8820: 78 50 68 72 61 73 65 4e 65 78 74 3e 78 50 68 72  xPhraseNext>xPhr
8830: 61 73 65 4e 65 78 74 3c 2f 61 3e 0a 20 20 61 72  aseNext</a>.  ar
8840: 65 20 73 6c 6f 77 65 72 20 74 68 61 6e 20 75 73  e slower than us
8850: 75 61 6c 2e 20 54 68 69 73 20 69 73 20 62 65 63  ual. This is bec
8860: 61 75 73 65 20 69 6e 73 74 65 61 64 20 6f 66 20  ause instead of 
8870: 72 65 61 64 69 6e 67 20 74 68 65 20 72 65 71 75  reading the requ
8880: 69 72 65 64 20 64 61 74 61 0a 20 20 64 69 72 65  ired data.  dire
8890: 63 74 6c 79 20 66 72 6f 6d 20 74 68 65 20 46 54  ctly from the FT
88a0: 53 20 69 6e 64 65 78 20 74 68 65 79 20 68 61 76  S index they hav
88b0: 65 20 74 6f 20 6c 6f 61 64 20 61 6e 64 20 74 6f  e to load and to
88c0: 6b 65 6e 69 7a 65 20 74 68 65 20 64 6f 63 75 6d  kenize the docum
88d0: 65 6e 74 20 74 65 78 74 20 0a 20 20 6f 6e 20 64  ent text .  on d
88e0: 65 6d 61 6e 64 2e 0a 20 20 3c 6c 69 3e 20 49 66  emand..  <li> If
88f0: 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61 6c   the table is al
8900: 73 6f 20 61 20 63 6f 6e 74 65 6e 74 6c 65 73 73  so a contentless
8910: 20 74 61 62 6c 65 2c 20 74 68 65 20 78 49 6e 73   table, the xIns
8920: 74 43 6f 75 6e 74 2c 20 78 49 6e 73 74 2c 20 0a  tCount, xInst, .
8930: 20 20 78 50 68 72 61 73 65 46 69 72 73 74 20 61    xPhraseFirst a
8940: 6e 64 20 78 50 68 72 61 73 65 4e 65 78 74 20 41  nd xPhraseNext A
8950: 50 49 73 20 62 65 68 61 76 65 20 61 73 20 69 66  PIs behave as if
8960: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
8970: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 0a 20 20 70   contains no.  p
8980: 68 72 61 73 65 20 6d 61 74 63 68 65 73 20 61 74  hrase matches at
8990: 20 61 6c 6c 20 28 69 2e 65 2e 20 78 49 6e 73 74   all (i.e. xInst
89a0: 43 6f 75 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Count() returns 
89b0: 30 29 2e 0a 3c 2f 75 6c 3e 0a 20 20 0a 3c 70 3e  0)..</ul>.  .<p>
89c0: 49 66 20 74 68 65 20 64 65 74 61 69 6c 20 6f 70  If the detail op
89d0: 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 3c  tion is set to <
89e0: 62 3e 6e 6f 6e 65 3c 2f 62 3e 2c 20 74 68 65 6e  b>none</b>, then
89f0: 20 66 6f 72 20 65 61 63 68 20 74 65 72 6d 20 74   for each term t
8a00: 68 65 20 46 54 53 0a 69 6e 64 65 78 20 72 65 63  he FTS.index rec
8a10: 6f 72 64 73 20 6a 75 73 74 20 74 68 65 20 72 6f  ords just the ro
8a20: 77 69 64 20 69 73 20 73 74 6f 72 65 64 2e 20 42  wid is stored. B
8a30: 6f 74 68 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 6f  oth column and o
8a40: 66 66 73 65 74 20 69 6e 66 6f 72 6d 61 74 69 6f  ffset informatio
8a50: 6e 0a 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 41  n.are omitted. A
8a60: 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 72 65  s well as the re
8a70: 73 74 72 69 63 74 69 6f 6e 73 20 69 74 65 6d 69  strictions itemi
8a80: 7a 65 64 20 61 62 6f 76 65 20 66 6f 72 20 64 65  zed above for de
8a90: 74 61 69 6c 3d 63 6f 6c 75 6d 6e 0a 6d 6f 64 65  tail=column.mode
8aa0: 2c 20 74 68 69 73 20 69 6d 70 6f 73 65 73 20 74  , this imposes t
8ab0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 74  he following ext
8ac0: 72 61 20 6c 69 6d 69 74 61 74 69 6f 6e 73 3a 0a  ra limitations:.
8ad0: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 43 6f 6c  .<ul>.  <li> Col
8ae0: 75 6d 6e 20 66 69 6c 74 65 72 20 71 75 65 72 69  umn filter queri
8af0: 65 73 20 61 72 65 20 6e 6f 74 20 61 76 61 69 6c  es are not avail
8b00: 61 62 6c 65 2e 0a 20 20 3c 6c 69 3e 20 41 73 73  able..  <li> Ass
8b10: 75 6d 69 6e 67 20 74 68 65 20 74 61 62 6c 65 20  uming the table 
8b20: 69 73 20 6e 6f 74 20 61 6c 73 6f 20 61 20 63 6f  is not also a co
8b30: 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 2c  ntentless table,
8b40: 20 74 68 65 20 0a 20 20 3c 61 20 68 72 65 66 3d   the .  <a href=
8b50: 23 78 50 68 72 61 73 65 46 69 72 73 74 43 6f 6c  #xPhraseFirstCol
8b60: 75 6d 6e 3e 78 50 68 72 61 73 65 46 69 72 73 74  umn>xPhraseFirst
8b70: 43 6f 6c 75 6d 6e 3c 2f 61 3e 20 61 6e 64 20 0a  Column</a> and .
8b80: 20 20 3c 61 20 68 72 65 66 3d 23 78 50 68 72 61    <a href=#xPhra
8b90: 73 65 4e 65 78 74 43 6f 6c 75 6d 6e 3e 78 50 68  seNextColumn>xPh
8ba0: 72 61 73 65 4e 65 78 74 43 6f 6c 75 6d 6e 3c 2f  raseNextColumn</
8bb0: 61 3e 20 61 72 65 20 73 6c 6f 77 65 72 20 74 68  a> are slower th
8bc0: 61 6e 20 75 73 75 61 6c 2e 20 0a 0a 20 20 3c 6c  an usual. ..  <l
8bd0: 69 3e 20 49 66 20 74 68 65 20 74 61 62 6c 65 20  i> If the table 
8be0: 69 73 20 61 6c 73 6f 20 61 20 63 6f 6e 74 65 6e  is also a conten
8bf0: 74 6c 65 73 73 20 74 61 62 6c 65 2c 20 74 68 65  tless table, the
8c00: 20 78 50 68 72 61 73 65 46 69 72 73 74 43 6f 6c   xPhraseFirstCol
8c10: 75 6d 6e 20 61 6e 64 0a 20 20 78 50 68 72 61 73  umn and.  xPhras
8c20: 65 4e 65 78 74 43 6f 6c 75 6d 6e 20 41 50 49 73  eNextColumn APIs
8c30: 20 62 65 68 61 76 65 20 61 73 20 69 66 20 74 68   behave as if th
8c40: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 63 6f  e current row co
8c50: 6e 74 61 69 6e 73 20 6e 6f 20 70 68 72 61 73 65  ntains no phrase
8c60: 0a 20 20 6d 61 74 63 68 65 73 20 61 74 20 61 6c  .  matches at al
8c70: 6c 20 28 69 2e 65 2e 20 78 50 68 72 61 73 65 46  l (i.e. xPhraseF
8c80: 69 72 73 74 43 6f 6c 75 6d 6e 28 29 20 73 65 74  irstColumn() set
8c90: 73 20 74 68 65 20 69 74 65 72 61 74 6f 72 20 74  s the iterator t
8ca0: 6f 20 45 4f 46 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c  o EOF)..</ul>..<
8cb0: 70 3e 20 49 6e 20 6f 6e 65 20 74 65 73 74 20 74  p> In one test t
8cc0: 68 61 74 20 69 6e 64 65 78 65 64 20 61 20 6c 61  hat indexed a la
8cd0: 72 67 65 20 73 65 74 20 6f 66 20 65 6d 61 69 6c  rge set of email
8ce0: 73 20 28 31 36 33 36 20 4d 69 42 20 6f 6e 20 64  s (1636 MiB on d
8cf0: 69 73 6b 29 2c 20 74 68 65 20 46 54 53 0a 69 6e  isk), the FTS.in
8d00: 64 65 78 20 77 61 73 20 37 34 33 20 4d 69 42 20  dex was 743 MiB 
8d10: 6f 6e 20 64 69 73 6b 20 77 69 74 68 20 64 65 74  on disk with det
8d20: 61 69 6c 3d 66 75 6c 6c 2c 20 33 34 30 20 4d 69  ail=full, 340 Mi
8d30: 42 20 77 69 74 68 20 64 65 74 61 69 6c 3d 63 6f  B with detail=co
8d40: 6c 75 6d 6e 20 61 6e 64 20 31 33 34 0a 4d 69 42  lumn and 134.MiB
8d50: 20 77 69 74 68 20 64 65 74 61 69 6c 3d 6e 6f 6e   with detail=non
8d60: 65 2e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46 54  e...<h1 tags="FT
8d70: 53 35 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  S5 auxiliary fun
8d80: 63 74 69 6f 6e 73 22 3e 20 41 75 78 69 6c 69 61  ctions"> Auxilia
8d90: 72 79 20 46 75 6e 63 74 69 6f 6e 73 20 3c 2f 68  ry Functions </h
8da0: 31 3e 0a 0a 3c 70 3e 20 41 75 78 69 6c 69 61 72  1>..<p> Auxiliar
8db0: 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  y functions are 
8dc0: 73 69 6d 69 6c 61 72 20 74 6f 20 5b 63 6f 72 65  similar to [core
8dd0: 66 75 6e 63 20 7c 20 53 51 4c 20 73 63 61 6c 61  func | SQL scala
8de0: 72 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 0a 65 78  r functions],.ex
8df0: 63 65 70 74 20 74 68 61 74 20 74 68 65 79 20 6d  cept that they m
8e00: 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
8e10: 77 69 74 68 69 6e 20 66 75 6c 6c 2d 74 65 78 74  within full-text
8e20: 20 71 75 65 72 69 65 73 20 28 74 68 6f 73 65 20   queries (those 
8e30: 74 68 61 74 20 75 73 65 0a 74 68 65 20 4d 41 54  that use.the MAT
8e40: 43 48 20 6f 70 65 72 61 74 6f 72 29 20 6f 6e 20  CH operator) on 
8e50: 61 6e 20 46 54 53 35 20 74 61 62 6c 65 2e 20 54  an FTS5 table. T
8e60: 68 65 69 72 20 72 65 73 75 6c 74 73 20 61 72 65  heir results are
8e70: 20 63 61 6c 63 75 6c 61 74 65 64 20 62 61 73 65   calculated base
8e80: 64 20 6e 6f 74 0a 6f 6e 6c 79 20 6f 6e 20 74 68  d not.only on th
8e90: 65 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73  e arguments pass
8ea0: 65 64 20 74 6f 20 74 68 65 6d 2c 20 62 75 74 20  ed to them, but 
8eb0: 61 6c 73 6f 20 6f 6e 20 74 68 65 20 63 75 72 72  also on the curr
8ec0: 65 6e 74 20 6d 61 74 63 68 20 61 6e 64 20 0a 6d  ent match and .m
8ed0: 61 74 63 68 65 64 20 72 6f 77 2e 20 46 6f 72 20  atched row. For 
8ee0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 75 78 69  example, an auxi
8ef0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d  liary function m
8f00: 61 79 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65  ay return a nume
8f10: 72 69 63 20 76 61 6c 75 65 0a 69 6e 64 69 63 61  ric value.indica
8f20: 74 69 6e 67 20 74 68 65 20 61 63 63 75 72 61 63  ting the accurac
8f30: 79 20 6f 66 20 74 68 65 20 6d 61 74 63 68 20 28  y of the match (
8f40: 73 65 65 20 74 68 65 20 5b 46 54 53 35 20 62 6d  see the [FTS5 bm
8f50: 32 35 7c 20 62 6d 32 35 28 29 5d 20 66 75 6e 63  25| bm25()] func
8f60: 74 69 6f 6e 29 2c 20 0a 6f 72 20 61 20 66 72 61  tion), .or a fra
8f70: 67 6d 65 6e 74 20 6f 66 20 74 65 78 74 20 66 72  gment of text fr
8f80: 6f 6d 20 74 68 65 20 6d 61 74 63 68 65 64 20 72  om the matched r
8f90: 6f 77 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  ow that contains
8fa0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 69 6e   one or more .in
8fb0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 65 20 73  stances of the s
8fc0: 65 61 72 63 68 20 74 65 72 6d 73 20 28 73 65 65  earch terms (see
8fd0: 20 74 68 65 20 5b 46 54 53 35 20 73 6e 69 70 70   the [FTS5 snipp
8fe0: 65 74 20 7c 20 73 6e 69 70 70 65 74 28 29 5d 20  et | snippet()] 
8ff0: 66 75 6e 63 74 69 6f 6e 29 2e 0a 0a 3c 70 3e 54  function)...<p>T
9000: 6f 20 69 6e 76 6f 6b 65 20 61 6e 20 61 75 78 69  o invoke an auxi
9010: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 2c 20  liary function, 
9020: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
9030: 46 54 53 35 20 74 61 62 6c 65 20 73 68 6f 75 6c  FTS5 table shoul
9040: 64 20 62 65 0a 73 70 65 63 69 66 69 65 64 20 61  d be.specified a
9050: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
9060: 6d 65 6e 74 2e 20 4f 74 68 65 72 20 61 72 67 75  ment. Other argu
9070: 6d 65 6e 74 73 20 6d 61 79 20 66 6f 6c 6c 6f 77  ments may follow
9080: 20 74 68 65 20 66 69 72 73 74 2c 0a 64 65 70 65   the first,.depe
9090: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 73 70 65  nding on the spe
90a0: 63 69 66 69 63 20 61 75 78 69 6c 69 61 72 79 20  cific auxiliary 
90b0: 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 69  function being i
90c0: 6e 76 6f 6b 65 64 2e 20 46 6f 72 20 65 78 61 6d  nvoked. For exam
90d0: 70 6c 65 2c 20 74 6f 0a 69 6e 76 6f 6b 65 20 74  ple, to.invoke t
90e0: 68 65 20 22 68 69 67 68 6c 69 67 68 74 22 20 66  he "highlight" f
90f0: 75 6e 63 74 69 6f 6e 3a 0a 0a 3c 63 6f 64 65 62  unction:..<codeb
9100: 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20 68  lock>.  SELECT h
9110: 69 67 68 6c 69 67 68 74 28 65 6d 61 69 6c 2c 20  ighlight(email, 
9120: 32 2c 20 27 26 6c 74 3b 62 26 67 74 3b 27 2c 20  2, '&lt;b&gt;', 
9130: 27 26 6c 74 3b 2f 62 26 67 74 3b 27 29 20 46 52  '&lt;/b&gt;') FR
9140: 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65  OM email WHERE e
9150: 6d 61 69 6c 20 4d 41 54 43 48 20 27 66 74 73 35  mail MATCH 'fts5
9160: 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  '.</codeblock>..
9170: 3c 70 3e 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  <p>The built-in 
9180: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
9190: 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 61 73 20  ons provided as 
91a0: 70 61 72 74 20 6f 66 20 46 54 53 35 20 61 72 65  part of FTS5 are
91b0: 20 64 65 73 63 72 69 62 65 64 20 69 6e 0a 74 68   described in.th
91c0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 63 74  e following sect
91d0: 69 6f 6e 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ion. Application
91e0: 73 20 6d 61 79 20 61 6c 73 6f 20 69 6d 70 6c 65  s may also imple
91f0: 6d 65 6e 74 20 0a 5b 46 54 53 35 20 63 75 73 74  ment .[FTS5 cust
9200: 6f 6d 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  om auxiliary fun
9210: 63 74 69 6f 6e 73 20 7c 20 63 75 73 74 6f 6d 20  ctions | custom 
9220: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
9230: 6f 6e 73 20 69 6e 20 43 5d 2e 0a 0a 3c 68 32 3e  ons in C]...<h2>
9240: 42 75 69 6c 74 2d 69 6e 20 41 75 78 69 6c 69 61  Built-in Auxilia
9250: 72 79 20 46 75 6e 63 74 69 6f 6e 73 3c 2f 68 32  ry Functions</h2
9260: 3e 0a 0a 3c 70 3e 20 46 54 53 35 20 70 72 6f 76  >..<p> FTS5 prov
9270: 69 64 65 73 20 74 68 72 65 65 20 62 75 69 6c 74  ides three built
9280: 2d 69 6e 20 61 75 78 69 6c 69 61 72 79 20 66 75  -in auxiliary fu
9290: 6e 63 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20  nctions:..<ul>. 
92a0: 20 3c 6c 69 3e 20 54 68 65 20 5b 46 54 53 35 20   <li> The [FTS5 
92b0: 62 6d 32 35 20 7c 20 62 6d 32 35 28 29 20 61 75  bm25 | bm25() au
92c0: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
92d0: 5d 20 72 65 74 75 72 6e 73 20 61 20 72 65 61 6c  ] returns a real
92e0: 20 76 61 6c 75 65 0a 20 20 20 20 20 20 20 72 65   value.       re
92f0: 66 6c 65 63 74 69 6e 67 20 74 68 65 20 61 63 63  flecting the acc
9300: 75 72 61 63 79 20 6f 66 20 74 68 65 20 63 75 72  uracy of the cur
9310: 72 65 6e 74 20 6d 61 74 63 68 2e 20 42 65 74 74  rent match. Bett
9320: 65 72 20 6d 61 74 63 68 65 73 20 61 72 65 0a 20  er matches are. 
9330: 20 20 20 20 20 20 61 73 73 69 67 6e 65 64 20 6e        assigned n
9340: 75 6d 65 72 69 63 61 6c 6c 79 20 6c 6f 77 65 72  umerically lower
9350: 20 76 61 6c 75 65 73 2e 0a 0a 20 20 3c 6c 69 3e   values...  <li>
9360: 20 54 68 65 20 5b 46 54 53 35 20 68 69 67 68 6c   The [FTS5 highl
9370: 69 67 68 74 20 7c 20 68 69 67 68 6c 69 67 68 74  ight | highlight
9380: 28 29 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  () auxiliary fun
9390: 63 74 69 6f 6e 5d 20 72 65 74 75 72 6e 73 20 61  ction] returns a
93a0: 20 63 6f 70 79 0a 20 20 20 20 20 20 20 6f 66 20   copy.       of 
93b0: 74 68 65 20 74 65 78 74 20 66 72 6f 6d 20 6f 6e  the text from on
93c0: 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  e of the columns
93d0: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
93e0: 6d 61 74 63 68 20 77 69 74 68 20 65 61 63 68 0a  match with each.
93f0: 20 20 20 20 20 20 20 69 6e 73 74 61 6e 63 65 20         instance 
9400: 6f 66 20 61 20 71 75 65 72 69 65 64 20 74 65 72  of a queried ter
9410: 6d 20 77 69 74 68 69 6e 20 74 68 65 20 72 65 73  m within the res
9420: 75 6c 74 20 73 75 72 72 6f 75 6e 64 65 64 20 62  ult surrounded b
9430: 79 20 73 70 65 63 69 66 69 65 64 0a 20 20 20 20  y specified.    
9440: 20 20 20 6d 61 72 6b 75 70 20 28 66 6f 72 20 65     markup (for e
9450: 78 61 6d 70 6c 65 20 22 26 6c 74 3b 62 26 67 74  xample "&lt;b&gt
9460: 3b 22 20 61 6e 64 20 22 26 6c 74 3b 2f 62 26 67  ;" and "&lt;/b&g
9470: 74 3b 22 29 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68  t;")...  <li> Th
9480: 65 20 5b 46 54 53 35 20 73 6e 69 70 70 65 74 20  e [FTS5 snippet 
9490: 7c 20 73 6e 69 70 70 65 74 28 29 20 61 75 78 69  | snippet() auxi
94a0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 5d 20  liary function] 
94b0: 73 65 6c 65 63 74 73 20 61 20 73 68 6f 72 74 0a  selects a short.
94c0: 20 20 20 20 20 20 20 66 72 61 67 6d 65 6e 74 20         fragment 
94d0: 6f 66 20 74 65 78 74 20 66 72 6f 6d 20 6f 6e 65  of text from one
94e0: 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20   of the columns 
94f0: 6f 66 20 74 68 65 20 6d 61 74 63 68 65 64 20 72  of the matched r
9500: 6f 77 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 20  ow and returns. 
9510: 20 20 20 20 20 20 69 74 20 77 69 74 68 20 65 61        it with ea
9520: 63 68 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ch instance of a
9530: 20 71 75 65 72 69 65 64 20 74 65 72 6d 20 73 75   queried term su
9540: 72 72 6f 75 6e 64 65 64 20 62 79 20 6d 61 72 6b  rrounded by mark
9550: 75 70 20 69 6e 0a 20 20 20 20 20 20 20 74 68 65  up in.       the
9560: 20 73 61 6d 65 20 6d 61 6e 6e 65 72 20 61 73 20   same manner as 
9570: 74 68 65 20 68 69 67 68 6c 69 67 68 74 28 29 20  the highlight() 
9580: 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 72  function. The fr
9590: 61 67 6d 65 6e 74 20 6f 66 20 74 65 78 74 20 69  agment of text i
95a0: 73 0a 20 20 20 20 20 20 20 73 65 6c 65 63 74 65  s.       selecte
95b0: 64 20 73 6f 20 61 73 20 74 6f 20 6d 61 78 69 6d  d so as to maxim
95c0: 69 7a 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ize the number o
95d0: 66 20 71 75 65 72 69 65 64 20 74 65 72 6d 73 20  f queried terms 
95e0: 69 74 20 63 6f 6e 74 61 69 6e 73 2e 0a 3c 2f 75  it contains..</u
95f0: 6c 3e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46 54  l>..<h3 tags="FT
9600: 53 35 20 62 6d 32 35 22 3e 54 68 65 20 62 6d 32  S5 bm25">The bm2
9610: 35 28 29 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 33  5() function</h3
9620: 3e 0a 0a 3c 70 3e 20 54 68 65 20 62 75 69 6c 74  >..<p> The built
9630: 2d 69 6e 20 61 75 78 69 6c 69 61 72 79 20 66 75  -in auxiliary fu
9640: 6e 63 74 69 6f 6e 20 62 6d 32 35 28 29 20 72 65  nction bm25() re
9650: 74 75 72 6e 73 20 61 20 72 65 61 6c 20 76 61 6c  turns a real val
9660: 75 65 20 69 6e 64 69 63 61 74 69 6e 67 0a 68 6f  ue indicating.ho
9670: 77 20 77 65 6c 6c 20 74 68 65 20 63 75 72 72 65  w well the curre
9680: 6e 74 20 72 6f 77 20 6d 61 74 63 68 65 73 20 74  nt row matches t
9690: 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  he full-text que
96a0: 72 79 2e 20 54 68 65 20 62 65 74 74 65 72 20 74  ry. The better t
96b0: 68 65 20 6d 61 74 63 68 2c 0a 74 68 65 20 6e 75  he match,.the nu
96c0: 6d 65 72 69 63 61 6c 6c 79 20 73 6d 61 6c 6c 65  merically smalle
96d0: 72 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  r the value retu
96e0: 72 6e 65 64 2e 20 41 20 71 75 65 72 79 20 73 75  rned. A query su
96f0: 63 68 20 61 73 20 74 68 65 20 66 6f 6c 6c 6f 77  ch as the follow
9700: 69 6e 67 20 6d 61 79 0a 62 65 20 75 73 65 64 20  ing may.be used 
9710: 74 6f 20 72 65 74 75 72 6e 20 6d 61 74 63 68 65  to return matche
9720: 73 20 69 6e 20 6f 72 64 65 72 20 66 72 6f 6d 20  s in order from 
9730: 62 65 73 74 20 74 6f 20 77 6f 72 73 74 20 6d 61  best to worst ma
9740: 74 63 68 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  tch:..<codeblock
9750: 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  >.  SELECT * FRO
9760: 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73 20  M fts WHERE fts 
9770: 4d 41 54 43 48 20 3f 20 4f 52 44 45 52 20 42 59  MATCH ? ORDER BY
9780: 20 62 6d 32 35 28 66 74 73 29 0a 3c 2f 63 6f 64   bm25(fts).</cod
9790: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20  eblock>..<p> In 
97a0: 6f 72 64 65 72 20 74 6f 20 63 61 6c 63 75 6c 61  order to calcula
97b0: 74 65 20 61 20 64 6f 63 75 6d 65 6e 74 73 20 73  te a documents s
97c0: 63 6f 72 65 2c 20 74 68 65 20 66 75 6c 6c 2d 74  core, the full-t
97d0: 65 78 74 20 71 75 65 72 79 20 69 73 20 73 65 70  ext query is sep
97e0: 61 72 61 74 65 64 0a 20 20 20 20 69 6e 74 6f 20  arated.    into 
97f0: 69 74 73 20 63 6f 6d 70 6f 6e 65 6e 74 20 70 68  its component ph
9800: 72 61 73 65 73 2e 20 54 68 65 20 62 6d 32 35 20  rases. The bm25 
9810: 73 63 6f 72 65 20 66 6f 72 20 64 6f 63 75 6d 65  score for docume
9820: 6e 74 20 3c 69 3e 44 3c 2f 69 3e 20 61 6e 64 20  nt <i>D</i> and 
9830: 0a 20 20 20 20 71 75 65 72 79 20 3c 69 3e 51 3c  .    query <i>Q<
9840: 2f 69 3e 20 69 73 20 74 68 65 6e 20 63 61 6c 63  /i> is then calc
9850: 75 6c 61 74 65 64 20 61 73 20 66 6f 6c 6c 6f 77  ulated as follow
9860: 73 3a 0a 0a 3c 70 3e 20 3c 69 6d 67 20 73 72 63  s:..<p> <img src
9870: 3d 22 69 6d 61 67 65 73 2f 66 74 73 35 5f 66 6f  ="images/fts5_fo
9880: 72 6d 75 6c 61 31 2e 70 6e 67 22 20 73 74 79 6c  rmula1.png" styl
9890: 65 3d 22 77 69 64 74 68 3a 37 35 65 78 3b 6d 61  e="width:75ex;ma
98a0: 72 67 69 6e 2d 6c 65 66 74 3a 35 65 78 22 3e 0a  rgin-left:5ex">.
98b0: 0a 3c 70 3e 20 49 6e 20 74 68 65 20 61 62 6f 76  .<p> In the abov
98c0: 65 2c 20 3c 69 3e 6e 50 68 72 61 73 65 3c 2f 69  e, <i>nPhrase</i
98d0: 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  > is the number 
98e0: 6f 66 20 70 68 72 61 73 65 73 20 69 6e 20 74 68  of phrases in th
98f0: 65 20 71 75 65 72 79 2e 0a 20 20 20 20 3c 69 3e  e query..    <i>
9900: 7c 44 7c 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e  |D|</i> is the n
9910: 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20  umber of tokens 
9920: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
9930: 6f 63 75 6d 65 6e 74 2c 20 61 6e 64 0a 20 20 20  ocument, and.   
9940: 20 3c 69 3e 61 76 67 64 6c 3c 2f 69 3e 20 69 73   <i>avgdl</i> is
9950: 20 74 68 65 20 61 76 65 72 61 67 65 20 6e 75 6d   the average num
9960: 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e  ber of tokens in
9970: 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20 77   all documents w
9980: 69 74 68 69 6e 20 74 68 65 0a 20 20 20 20 46 54  ithin the.    FT
9990: 53 35 20 74 61 62 6c 65 2e 20 20 3c 69 3e 6b 3c  S5 table.  <i>k<
99a0: 73 75 62 3e 31 3c 2f 73 75 62 3e 3c 2f 69 3e 20  sub>1</sub></i> 
99b0: 61 6e 64 20 3c 69 3e 62 3c 2f 69 3e 20 61 72 65  and <i>b</i> are
99c0: 20 62 6f 74 68 20 63 6f 6e 73 74 61 6e 74 73 2c   both constants,
99d0: 0a 20 20 20 20 68 61 72 64 2d 63 6f 64 65 64 20  .    hard-coded 
99e0: 61 74 20 31 2e 32 20 61 6e 64 20 30 2e 37 35 20  at 1.2 and 0.75 
99f0: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 0a 3c  respectively...<
9a00: 70 3e 20 54 68 65 20 22 2d 31 22 20 74 65 72 6d  p> The "-1" term
9a10: 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
9a20: 20 74 68 65 20 66 6f 72 6d 75 6c 61 20 69 73 20   the formula is 
9a30: 6e 6f 74 20 66 6f 75 6e 64 20 69 6e 20 6d 6f 73  not found in mos
9a40: 74 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t.implementation
9a50: 73 20 6f 66 20 74 68 65 20 42 4d 32 35 20 61 6c  s of the BM25 al
9a60: 67 6f 72 69 74 68 6d 2e 20 57 69 74 68 6f 75 74  gorithm. Without
9a70: 20 69 74 2c 20 61 20 62 65 74 74 65 72 20 6d 61   it, a better ma
9a80: 74 63 68 20 69 73 20 61 73 73 69 67 6e 65 64 0a  tch is assigned.
9a90: 61 20 6e 75 6d 65 72 69 63 61 6c 6c 79 20 68 69  a numerically hi
9aa0: 67 68 65 72 20 42 4d 32 35 20 73 63 6f 72 65 2e  gher BM25 score.
9ab0: 20 53 69 6e 63 65 20 74 68 65 20 64 65 66 61 75   Since the defau
9ac0: 6c 74 20 73 6f 72 74 69 6e 67 20 6f 72 64 65 72  lt sorting order
9ad0: 20 69 73 0a 22 61 73 63 65 6e 64 69 6e 67 22 2c   is."ascending",
9ae0: 20 74 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   this means that
9af0: 20 61 70 70 65 6e 64 69 6e 67 20 22 4f 52 44 45   appending "ORDE
9b00: 52 20 42 59 20 62 6d 32 35 28 66 74 73 29 22 20  R BY bm25(fts)" 
9b10: 74 6f 20 61 20 71 75 65 72 79 20 77 6f 75 6c 64  to a query would
9b20: 0a 63 61 75 73 65 20 72 65 73 75 6c 74 73 20 74  .cause results t
9b30: 6f 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 6e  o be returned in
9b40: 20 6f 72 64 65 72 20 66 72 6f 6d 20 77 6f 72 73   order from wors
9b50: 74 20 74 6f 20 62 65 73 74 2e 20 54 68 65 20 22  t to best. The "
9b60: 44 45 53 43 22 20 6b 65 79 77 6f 72 64 0a 77 6f  DESC" keyword.wo
9b70: 75 6c 64 20 62 65 20 72 65 71 75 69 72 65 64 20  uld be required 
9b80: 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 74 75  in order to retu
9b90: 72 6e 20 74 68 65 20 62 65 73 74 20 6d 61 74 63  rn the best matc
9ba0: 68 65 73 20 66 69 72 73 74 2e 20 49 6e 20 6f 72  hes first. In or
9bb0: 64 65 72 20 74 6f 0a 61 76 6f 69 64 20 74 68 69  der to.avoid thi
9bc0: 73 20 70 69 74 66 61 6c 6c 2c 20 74 68 65 20 46  s pitfall, the F
9bd0: 54 53 35 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  TS5 implementati
9be0: 6f 6e 20 6f 66 20 42 4d 32 35 20 6d 75 6c 74 69  on of BM25 multi
9bf0: 70 6c 69 65 73 20 74 68 65 20 72 65 73 75 6c 74  plies the result
9c00: 0a 62 79 20 2d 31 20 62 65 66 6f 72 65 20 72 65  .by -1 before re
9c10: 74 75 72 6e 69 6e 67 20 69 74 2c 20 65 6e 73 75  turning it, ensu
9c20: 72 69 6e 67 20 74 68 61 74 20 62 65 74 74 65 72  ring that better
9c30: 20 6d 61 74 63 68 65 73 20 61 72 65 20 61 73 73   matches are ass
9c40: 69 67 6e 65 64 0a 6e 75 6d 65 72 69 63 61 6c 6c  igned.numericall
9c50: 79 20 6c 6f 77 65 72 20 73 63 6f 72 65 73 2e 0a  y lower scores..
9c60: 0a 3c 70 3e 20 3c 69 3e 49 44 46 28 71 3c 73 75  .<p> <i>IDF(q<su
9c70: 62 3e 69 3c 2f 73 75 62 3e 29 3c 2f 69 3e 20 69  b>i</sub>)</i> i
9c80: 73 20 74 68 65 20 69 6e 76 65 72 73 65 2d 64 6f  s the inverse-do
9c90: 63 75 6d 65 6e 74 2d 66 72 65 71 75 65 6e 63 79  cument-frequency
9ca0: 20 6f 66 20 71 75 65 72 79 20 0a 20 20 20 20 70   of query .    p
9cb0: 68 72 61 73 65 20 3c 69 3e 69 3c 2f 69 3e 2e 20  hrase <i>i</i>. 
9cc0: 49 74 20 69 73 20 63 61 6c 63 75 6c 61 74 65 64  It is calculated
9cd0: 20 61 73 20 66 6f 6c 6c 6f 77 73 2c 20 77 68 65   as follows, whe
9ce0: 72 65 20 3c 69 3e 4e 3c 2f 69 3e 20 69 73 20 74  re <i>N</i> is t
9cf0: 68 65 20 74 6f 74 61 6c 0a 20 20 20 20 6e 75 6d  he total.    num
9d00: 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74  ber of rows in t
9d10: 68 65 20 46 54 53 35 20 74 61 62 6c 65 20 61 6e  he FTS5 table an
9d20: 64 20 3c 69 3e 6e 28 71 3c 73 75 62 3e 69 3c 2f  d <i>n(q<sub>i</
9d30: 73 75 62 3e 29 3c 2f 69 3e 20 69 73 20 74 68 65  sub>)</i> is the
9d40: 20 74 6f 74 61 6c 0a 20 20 20 20 6e 75 6d 62 65   total.    numbe
9d50: 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63  r of rows that c
9d60: 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61 73 74 20  ontain at least 
9d70: 6f 6e 65 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  one instance of 
9d80: 70 68 72 61 73 65 20 3c 69 3e 69 3c 2f 69 3e 3a  phrase <i>i</i>:
9d90: 0a 0a 3c 70 3e 20 3c 69 6d 67 20 73 72 63 3d 22  ..<p> <img src="
9da0: 69 6d 61 67 65 73 2f 66 74 73 35 5f 66 6f 72 6d  images/fts5_form
9db0: 75 6c 61 32 2e 70 6e 67 22 20 73 74 79 6c 65 3d  ula2.png" style=
9dc0: 22 77 69 64 74 68 3a 37 35 65 78 3b 6d 61 72 67  "width:75ex;marg
9dd0: 69 6e 2d 6c 65 66 74 3a 35 65 78 22 3e 0a 0a 3c  in-left:5ex">..<
9de0: 70 3e 20 46 69 6e 61 6c 6c 79 2c 20 3c 69 3e 66  p> Finally, <i>f
9df0: 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62 3e 2c 44  (q<sub>i</sub>,D
9e00: 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 70 68 72  )</i> is the phr
9e10: 61 73 65 20 66 72 65 71 75 65 6e 63 79 20 6f 66  ase frequency of
9e20: 20 70 68 72 61 73 65 20 0a 3c 69 3e 69 3c 2f 69   phrase .<i>i</i
9e30: 3e 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  >. By default, t
9e40: 68 69 73 20 69 73 20 73 69 6d 70 6c 79 20 74 68  his is simply th
9e50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6f 63 63 75  e number of occu
9e60: 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 70  rrences of the p
9e70: 68 72 61 73 65 0a 77 69 74 68 69 6e 20 74 68 65  hrase.within the
9e80: 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 48 6f   current row. Ho
9e90: 77 65 76 65 72 2c 20 62 79 20 70 61 73 73 69 6e  wever, by passin
9ea0: 67 20 65 78 74 72 61 20 72 65 61 6c 20 76 61 6c  g extra real val
9eb0: 75 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ue arguments to 
9ec0: 0a 74 68 65 20 62 6d 32 35 28 29 20 53 51 4c 20  .the bm25() SQL 
9ed0: 66 75 6e 63 74 69 6f 6e 2c 20 65 61 63 68 20 63  function, each c
9ee0: 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 74 61 62  olumn of the tab
9ef0: 6c 65 20 6d 61 79 20 62 65 20 61 73 73 69 67 6e  le may be assign
9f00: 65 64 20 61 20 64 69 66 66 65 72 65 6e 74 0a 77  ed a different.w
9f10: 65 69 67 68 74 20 61 6e 64 20 74 68 65 20 70 68  eight and the ph
9f20: 72 61 73 65 20 66 72 65 71 75 65 6e 63 79 20 63  rase frequency c
9f30: 61 6c 63 75 6c 61 74 65 64 20 61 73 20 66 6f 6c  alculated as fol
9f40: 6c 6f 77 73 3a 0a 0a 3c 70 3e 20 3c 69 6d 67 20  lows:..<p> <img 
9f50: 73 72 63 3d 22 69 6d 61 67 65 73 2f 66 74 73 35  src="images/fts5
9f60: 5f 66 6f 72 6d 75 6c 61 33 2e 70 6e 67 22 20 73  _formula3.png" s
9f70: 74 79 6c 65 3d 22 77 69 64 74 68 3a 37 35 65 78  tyle="width:75ex
9f80: 3b 6d 61 72 67 69 6e 2d 6c 65 66 74 3a 35 65 78  ;margin-left:5ex
9f90: 22 3e 0a 0a 3c 70 3e 20 77 68 65 72 65 20 3c 69  ">..<p> where <i
9fa0: 3e 77 3c 73 75 62 3e 63 3c 2f 73 75 62 3e 3c 2f  >w<sub>c</sub></
9fb0: 69 3e 20 69 73 20 74 68 65 20 77 65 69 67 68 74  i> is the weight
9fc0: 20 61 73 73 69 67 6e 65 64 20 74 6f 20 63 6f 6c   assigned to col
9fd0: 75 6d 6e 20 3c 69 3e 63 3c 2f 69 3e 20 61 6e 64  umn <i>c</i> and
9fe0: 0a 3c 69 3e 6e 28 71 3c 73 75 62 3e 69 3c 2f 73  .<i>n(q<sub>i</s
9ff0: 75 62 3e 2c 63 29 3c 2f 69 3e 20 69 73 20 74 68  ub>,c)</i> is th
a000: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6f 63 63 75  e number of occu
a010: 72 72 65 6e 63 65 73 20 6f 66 20 70 68 72 61 73  rrences of phras
a020: 65 20 3c 69 3e 69 3c 2f 69 3e 20 69 6e 0a 63 6f  e <i>i</i> in.co
a030: 6c 75 6d 6e 20 3c 69 3e 63 3c 2f 69 3e 20 6f 66  lumn <i>c</i> of
a040: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
a050: 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
a060: 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20 62  ment passed to b
a070: 6d 32 35 28 29 0a 66 6f 6c 6c 6f 77 69 6e 67 20  m25().following 
a080: 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 20 69  the table name i
a090: 73 20 74 68 65 20 77 65 69 67 68 74 20 61 73 73  s the weight ass
a0a0: 69 67 6e 65 64 20 74 6f 20 74 68 65 20 6c 65 66  igned to the lef
a0b0: 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 0a  tmost column of.
a0c0: 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 2e 20  the FTS5 table. 
a0d0: 54 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  The second is th
a0e0: 65 20 77 65 69 67 68 74 20 61 73 73 69 67 6e 65  e weight assigne
a0f0: 64 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20  d to the second 
a100: 6c 65 66 74 6d 6f 73 74 0a 63 6f 6c 75 6d 6e 2c  leftmost.column,
a110: 20 61 6e 64 20 73 6f 20 6f 6e 2e 20 49 66 20 74   and so on. If t
a120: 68 65 72 65 20 61 72 65 20 6e 6f 74 20 65 6e 6f  here are not eno
a130: 75 67 68 20 61 72 67 75 6d 65 6e 74 73 20 66 6f  ugh arguments fo
a140: 72 20 61 6c 6c 20 74 61 62 6c 65 20 63 6f 6c 75  r all table colu
a150: 6d 6e 73 2c 0a 72 65 6d 61 69 6e 69 6e 67 20 63  mns,.remaining c
a160: 6f 6c 75 6d 6e 73 20 61 72 65 20 61 73 73 69 67  olumns are assig
a170: 6e 65 64 20 61 20 77 65 69 67 68 74 20 6f 66 20  ned a weight of 
a180: 31 2e 30 2e 20 49 66 20 74 68 65 72 65 20 61 72  1.0. If there ar
a190: 65 20 74 6f 6f 20 6d 61 6e 79 20 0a 74 72 61 69  e too many .trai
a1a0: 6c 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 2c 20  ling arguments, 
a1b0: 74 68 65 20 65 78 74 72 61 73 20 61 72 65 20 69  the extras are i
a1c0: 67 6e 6f 72 65 64 2e 20 46 6f 72 20 65 78 61 6d  gnored. For exam
a1d0: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
a1e0: 3e 0a 20 20 3c 69 3e 2d 2d 20 41 73 73 75 6d 69  >.  <i>-- Assumi
a1f0: 6e 67 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ng the following
a200: 20 73 63 68 65 6d 61 3a 3c 2f 69 3e 0a 20 20 43   schema:</i>.  C
a210: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
a220: 42 4c 45 20 65 6d 61 69 6c 20 55 53 49 4e 47 20  BLE email USING 
a230: 66 74 73 35 28 73 65 6e 64 65 72 2c 20 74 69 74  fts5(sender, tit
a240: 6c 65 2c 20 62 6f 64 79 29 3b 0a 0a 20 20 3c 69  le, body);..  <i
a250: 3e 2d 2d 20 52 65 74 75 72 6e 20 72 65 73 75 6c  >-- Return resul
a260: 74 73 20 69 6e 20 62 6d 32 35 20 6f 72 64 65 72  ts in bm25 order
a270: 2c 20 77 69 74 68 20 65 61 63 68 20 70 68 72 61  , with each phra
a280: 73 65 20 68 69 74 20 69 6e 20 74 68 65 20 22 73  se hit in the "s
a290: 65 6e 64 65 72 22 3c 2f 69 3e 0a 20 20 3c 69 3e  ender"</i>.  <i>
a2a0: 2d 2d 20 63 6f 6c 75 6d 6e 20 63 6f 6e 73 69 64  -- column consid
a2b0: 65 72 65 64 20 74 68 65 20 65 71 75 61 6c 20 6f  ered the equal o
a2c0: 66 20 31 30 20 68 69 74 73 20 69 6e 20 74 68 65  f 10 hits in the
a2d0: 20 22 62 6f 64 79 22 20 63 6f 6c 75 6d 6e 2c 20   "body" column, 
a2e0: 61 6e 64 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20  and</i>.  <i>-- 
a2f0: 65 61 63 68 20 68 69 74 20 69 6e 20 74 68 65 20  each hit in the 
a300: 22 74 69 74 6c 65 22 20 63 6f 6c 75 6d 6e 20 63  "title" column c
a310: 6f 6e 73 69 64 65 72 65 64 20 61 73 20 76 61 6c  onsidered as val
a320: 75 61 62 6c 65 20 61 73 20 35 20 68 69 74 73 20  uable as 5 hits 
a330: 69 6e 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74  in</i>.  <i>-- t
a340: 68 65 20 22 62 6f 64 79 22 20 63 6f 6c 75 6d 6e  he "body" column
a350: 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a  .</i>.  SELECT *
a360: 20 46 52 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52   FROM email WHER
a370: 45 20 65 6d 61 69 6c 20 4d 41 54 43 48 20 3f 20  E email MATCH ? 
a380: 4f 52 44 45 52 20 42 59 20 62 6d 32 35 28 65 6d  ORDER BY bm25(em
a390: 61 69 6c 2c 20 31 30 2e 30 2c 20 35 2e 30 29 3b  ail, 10.0, 5.0);
a3a0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
a3b0: 70 3e 52 65 66 65 72 20 74 6f 20 77 69 6b 69 70  p>Refer to wikip
a3c0: 65 64 69 61 20 66 6f 72 20 0a 3c 61 20 68 72 65  edia for .<a hre
a3d0: 66 3d 22 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b  f="http://en.wik
a3e0: 69 70 65 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f  ipedia.org/wiki/
a3f0: 4f 6b 61 70 69 5f 42 4d 32 35 22 3e 6d 6f 72 65  Okapi_BM25">more
a400: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 72 65 67   information reg
a410: 61 72 64 69 6e 67 0a 42 4d 32 35 3c 2f 61 3e 20  arding.BM25</a> 
a420: 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
a430: 2e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46 54 53  ...<h3 tags="FTS
a440: 35 20 68 69 67 68 6c 69 67 68 74 22 3e 54 68 65  5 highlight">The
a450: 20 68 69 67 68 6c 69 67 68 74 28 29 20 66 75 6e   highlight() fun
a460: 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 20  ction</h3>..<p> 
a470: 54 68 65 20 68 69 67 68 6c 69 67 68 74 28 29 20  The highlight() 
a480: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
a490: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
a4a0: 65 78 74 20 66 72 6f 6d 20 61 20 73 70 65 63 69  ext from a speci
a4b0: 66 69 65 64 20 0a 63 6f 6c 75 6d 6e 20 6f 66 20  fied .column of 
a4c0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
a4d0: 77 69 74 68 20 65 78 74 72 61 20 6d 61 72 6b 75  with extra marku
a4e0: 70 20 74 65 78 74 20 69 6e 73 65 72 74 65 64 20  p text inserted 
a4f0: 74 6f 20 6d 61 72 6b 20 74 68 65 20 73 74 61 72  to mark the star
a500: 74 20 0a 61 6e 64 20 65 6e 64 20 6f 66 20 70 68  t .and end of ph
a510: 72 61 73 65 20 6d 61 74 63 68 65 73 2e 20 0a 0a  rase matches. ..
a520: 3c 70 3e 54 68 65 20 68 69 67 68 6c 69 67 68 74  <p>The highlight
a530: 28 29 20 6d 75 73 74 20 62 65 20 69 6e 76 6f 6b  () must be invok
a540: 65 64 20 77 69 74 68 20 65 78 61 63 74 6c 79 20  ed with exactly 
a550: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
a560: 66 6f 6c 6c 6f 77 69 6e 67 20 0a 74 68 65 20 74  following .the t
a570: 61 62 6c 65 20 6e 61 6d 65 2e 20 54 6f 20 62 65  able name. To be
a580: 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
a590: 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 20  follows:..<ol>. 
a5a0: 20 3c 6c 69 3e 20 41 6e 20 69 6e 74 65 67 65 72   <li> An integer
a5b0: 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
a5c0: 69 6e 64 65 78 20 6f 66 20 74 68 65 20 46 54 53  index of the FTS
a5d0: 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 6f   table column to
a5e0: 20 72 65 61 64 20 74 68 65 20 0a 20 20 20 20 20   read the .     
a5f0: 20 20 74 65 78 74 20 66 72 6f 6d 2e 20 43 6f 6c    text from. Col
a600: 75 6d 6e 73 20 61 72 65 20 6e 75 6d 62 65 72 65  umns are numbere
a610: 64 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72  d from left to r
a620: 69 67 68 74 20 73 74 61 72 74 69 6e 67 20 61 74  ight starting at
a630: 20 7a 65 72 6f 2e 0a 0a 20 20 3c 6c 69 3e 20 54   zero...  <li> T
a640: 68 65 20 74 65 78 74 20 74 6f 20 69 6e 73 65 72  he text to inser
a650: 74 20 62 65 66 6f 72 65 20 65 61 63 68 20 70 68  t before each ph
a660: 72 61 73 65 20 6d 61 74 63 68 2e 0a 0a 20 20 3c  rase match...  <
a670: 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74 6f 20  li> The text to 
a680: 69 6e 73 65 72 74 20 61 66 74 65 72 20 65 61 63  insert after eac
a690: 68 20 70 68 72 61 73 65 20 6d 61 74 63 68 2e 0a  h phrase match..
a6a0: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78  </ol>..<p>For ex
a6b0: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
a6c0: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 52 65 74 75  ck>.  <i>-- Retu
a6d0: 72 6e 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  rn a copy of the
a6e0: 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 6c   text from the l
a6f0: 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
a700: 66 20 74 68 65 20 63 75 72 72 65 6e 74 3c 2f 69  f the current</i
a710: 3e 0a 20 20 3c 69 3e 2d 2d 20 72 6f 77 2c 20 77  >.  <i>-- row, w
a720: 69 74 68 20 70 68 72 61 73 65 20 6d 61 74 63 68  ith phrase match
a730: 65 73 20 6d 61 72 6b 65 64 20 75 73 69 6e 67 20  es marked using 
a740: 68 74 6d 6c 20 22 62 22 20 74 61 67 73 2e 3c 2f  html "b" tags.</
a750: 69 3e 0a 20 20 53 45 4c 45 43 54 20 68 69 67 68  i>.  SELECT high
a760: 6c 69 67 68 74 28 66 74 73 2c 20 30 2c 20 27 26  light(fts, 0, '&
a770: 6c 74 3b 62 26 67 74 3b 27 2c 20 27 26 6c 74 3b  lt;b&gt;', '&lt;
a780: 2f 62 26 67 74 3b 27 29 20 46 52 4f 4d 20 66 74  /b&gt;') FROM ft
a790: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
a7a0: 48 20 3f 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  H ?.</codeblock>
a7b0: 0a 0a 3c 70 3e 49 6e 20 63 61 73 65 73 20 77 68  ..<p>In cases wh
a7c0: 65 72 65 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  ere two or more 
a7d0: 70 68 72 61 73 65 20 69 6e 73 74 61 6e 63 65 73  phrase instances
a7e0: 20 6f 76 65 72 6c 61 70 20 28 73 68 61 72 65 20   overlap (share 
a7f0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 74 6f 6b 65  one or more.toke
a800: 6e 73 20 69 6e 20 63 6f 6d 6d 6f 6e 29 2c 20 61  ns in common), a
a810: 20 73 69 6e 67 6c 65 20 6f 70 65 6e 20 61 6e 64   single open and
a820: 20 63 6c 6f 73 65 20 6d 61 72 6b 65 72 20 69 73   close marker is
a830: 20 69 6e 73 65 72 74 65 64 20 66 6f 72 20 65 61   inserted for ea
a840: 63 68 20 73 65 74 0a 6f 66 20 6f 76 65 72 6c 61  ch set.of overla
a850: 70 70 69 6e 67 20 70 68 72 61 73 65 73 2e 20 46  pping phrases. F
a860: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
a870: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
a880: 20 41 73 73 75 6d 69 6e 67 20 74 68 69 73 3a 3c   Assuming this:<
a890: 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52  /i>.  CREATE VIR
a8a0: 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55 53  TUAL TABLE ft US
a8b0: 49 4e 47 20 66 74 73 35 28 61 29 3b 0a 20 20 49  ING fts5(a);.  I
a8c0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 20 56 41  NSERT INTO ft VA
a8d0: 4c 55 45 53 28 27 61 20 62 20 63 20 78 20 63 20  LUES('a b c x c 
a8e0: 64 20 65 27 29 3b 0a 20 20 49 4e 53 45 52 54 20  d e');.  INSERT 
a8f0: 49 4e 54 4f 20 66 74 20 56 41 4c 55 45 53 28 27  INTO ft VALUES('
a900: 61 20 62 20 63 20 63 20 64 20 65 27 29 3b 0a 20  a b c c d e');. 
a910: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 20   INSERT INTO ft 
a920: 56 41 4c 55 45 53 28 27 61 20 62 20 63 20 64 20  VALUES('a b c d 
a930: 65 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68  e');..  <i>-- Th
a940: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 45 4c 45  e following SELE
a950: 43 54 20 73 74 61 74 65 6d 65 6e 74 20 72 65 74  CT statement ret
a960: 75 72 6e 73 20 74 68 65 73 65 20 74 68 72 65 65  urns these three
a970: 20 72 6f 77 73 3a 3c 2f 69 3e 0a 20 20 3c 69 3e   rows:</i>.  <i>
a980: 2d 2d 20 20 20 27 26 23 39 31 3b 61 20 62 20 63  --   '&#91;a b c
a990: 26 23 39 33 3b 20 78 20 26 23 39 31 3b 63 20 64  &#93; x &#91;c d
a9a0: 20 65 26 23 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c   e&#93;'</i>.  <
a9b0: 69 3e 2d 2d 20 20 20 27 26 23 39 31 3b 61 20 62  i>--   '&#91;a b
a9c0: 20 63 26 23 39 33 3b 20 26 23 39 31 3b 63 20 64   c&#93; &#91;c d
a9d0: 20 65 26 23 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c   e&#93;'</i>.  <
a9e0: 69 3e 2d 2d 20 20 20 27 26 23 39 31 3b 61 20 62  i>--   '&#91;a b
a9f0: 20 63 20 64 20 65 26 23 39 33 3b 27 3c 2f 69 3e   c d e&#93;'</i>
aa00: 0a 20 20 53 45 4c 45 43 54 20 68 69 67 68 6c 69  .  SELECT highli
aa10: 67 68 74 28 66 74 2c 20 30 2c 20 27 26 23 39 31  ght(ft, 0, '&#91
aa20: 3b 27 2c 20 27 26 23 39 33 3b 27 29 20 46 52 4f  ;', '&#93;') FRO
aa30: 4d 20 66 74 20 57 48 45 52 45 20 66 74 20 4d 41  M ft WHERE ft MA
aa40: 54 43 48 20 27 61 2b 62 2b 63 20 41 4e 44 20 63  TCH 'a+b+c AND c
aa50: 2b 64 2b 65 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  +d+e';.</codeblo
aa60: 63 6b 3e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46  ck>..<h3 tags="F
aa70: 54 53 35 20 73 6e 69 70 70 65 74 22 3e 54 68 65  TS5 snippet">The
aa80: 20 73 6e 69 70 70 65 74 28 29 20 66 75 6e 63 74   snippet() funct
aa90: 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65  ion</h3>..<p>The
aaa0: 20 73 6e 69 70 70 65 74 28 29 20 66 75 6e 63 74   snippet() funct
aab0: 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ion is similar t
aac0: 6f 20 68 69 67 68 6c 69 67 68 74 28 29 2c 20 65  o highlight(), e
aad0: 78 63 65 70 74 20 74 68 61 74 20 69 6e 73 74 65  xcept that inste
aae0: 61 64 20 6f 66 0a 72 65 74 75 72 6e 69 6e 67 20  ad of.returning 
aaf0: 65 6e 74 69 72 65 20 63 6f 6c 75 6d 6e 20 76 61  entire column va
ab00: 6c 75 65 73 2c 20 69 74 20 61 75 74 6f 6d 61 74  lues, it automat
ab10: 69 63 61 6c 6c 79 20 73 65 6c 65 63 74 73 20 61  ically selects a
ab20: 6e 64 20 65 78 74 72 61 63 74 73 20 61 0a 73 68  nd extracts a.sh
ab30: 6f 72 74 20 66 72 61 67 6d 65 6e 74 20 6f 66 20  ort fragment of 
ab40: 64 6f 63 75 6d 65 6e 74 20 74 65 78 74 20 74 6f  document text to
ab50: 20 70 72 6f 63 65 73 73 20 61 6e 64 20 72 65 74   process and ret
ab60: 75 72 6e 2e 20 54 68 65 20 73 6e 69 70 70 65 74  urn. The snippet
ab70: 28 29 20 66 75 6e 63 74 69 6f 6e 0a 6d 75 73 74  () function.must
ab80: 20 62 65 20 70 61 73 73 65 64 20 66 69 76 65 20   be passed five 
ab90: 70 61 72 61 6d 65 74 65 72 73 20 66 6f 6c 6c 6f  parameters follo
aba0: 77 69 6e 67 20 74 68 65 20 74 61 62 6c 65 20 6e  wing the table n
abb0: 61 6d 65 20 61 72 67 75 6d 65 6e 74 3a 0a 0a 3c  ame argument:..<
abc0: 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 41 6e 20 69 6e  ol>.  <li> An in
abd0: 74 65 67 65 72 20 69 6e 64 69 63 61 74 69 6e 67  teger indicating
abe0: 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
abf0: 65 20 46 54 53 20 74 61 62 6c 65 20 63 6f 6c 75  e FTS table colu
ac00: 6d 6e 20 74 6f 20 73 65 6c 65 63 74 0a 20 20 20  mn to select.   
ac10: 20 20 20 20 74 68 65 20 72 65 74 75 72 6e 65 64      the returned
ac20: 20 74 65 78 74 20 66 72 6f 6d 2e 20 43 6f 6c 75   text from. Colu
ac30: 6d 6e 73 20 61 72 65 20 6e 75 6d 62 65 72 65 64  mns are numbered
ac40: 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69   from left to ri
ac50: 67 68 74 20 0a 20 20 20 20 20 20 20 73 74 61 72  ght .       star
ac60: 74 69 6e 67 20 61 74 20 7a 65 72 6f 2e 20 41 20  ting at zero. A 
ac70: 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 69  negative value i
ac80: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
ac90: 65 20 63 6f 6c 75 6d 6e 20 73 68 6f 75 6c 64 0a  e column should.
aca0: 20 20 20 20 20 20 20 62 65 20 61 75 74 6f 6d 61         be automa
acb0: 74 69 63 61 6c 6c 79 20 73 65 6c 65 63 74 65 64  tically selected
acc0: 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74 65  ...  <li> The te
acd0: 78 74 20 74 6f 20 69 6e 73 65 72 74 20 62 65 66  xt to insert bef
ace0: 6f 72 65 20 65 61 63 68 20 70 68 72 61 73 65 20  ore each phrase 
acf0: 6d 61 74 63 68 20 77 69 74 68 69 6e 20 74 68 65  match within the
ad00: 20 72 65 74 75 72 6e 65 64 20 74 65 78 74 2e 0a   returned text..
ad10: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74 65 78 74  .  <li> The text
ad20: 20 74 6f 20 69 6e 73 65 72 74 20 61 66 74 65 72   to insert after
ad30: 20 65 61 63 68 20 70 68 72 61 73 65 20 6d 61 74   each phrase mat
ad40: 63 68 20 77 69 74 68 69 6e 20 74 68 65 20 72 65  ch within the re
ad50: 74 75 72 6e 65 64 20 74 65 78 74 2e 0a 0a 20 20  turned text...  
ad60: 3c 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74 6f  <li> The text to
ad70: 20 61 64 64 20 74 6f 20 74 68 65 20 73 74 61 72   add to the star
ad80: 74 20 6f 72 20 65 6e 64 20 6f 66 20 74 68 65 20  t or end of the 
ad90: 73 65 6c 65 63 74 65 64 20 74 65 78 74 20 74 6f  selected text to
ada0: 20 69 6e 64 69 63 61 74 65 0a 20 20 20 20 20 20   indicate.      
adb0: 20 74 68 61 74 20 74 68 65 20 72 65 74 75 72 6e   that the return
adc0: 65 64 20 74 65 78 74 20 64 6f 65 73 20 6e 6f 74  ed text does not
add0: 20 6f 63 63 75 72 20 61 74 20 74 68 65 20 73 74   occur at the st
ade0: 61 72 74 20 6f 72 20 65 6e 64 20 6f 66 20 69 74  art or end of it
adf0: 73 20 63 6f 6c 75 6d 6e 2c 0a 20 20 20 20 20 20  s column,.      
ae00: 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 0a   respectively...
ae10: 20 20 3c 6c 69 3e 20 54 68 65 20 6d 61 78 69 6d    <li> The maxim
ae20: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 6f 6b  um number of tok
ae30: 65 6e 73 20 69 6e 20 74 68 65 20 72 65 74 75 72  ens in the retur
ae40: 6e 65 64 20 74 65 78 74 2e 20 54 68 69 73 20 6d  ned text. This m
ae50: 75 73 74 20 62 65 20 67 72 65 61 74 65 72 0a 20  ust be greater. 
ae60: 20 20 20 20 20 20 74 68 61 6e 20 7a 65 72 6f 20        than zero 
ae70: 61 6e 64 20 65 71 75 61 6c 20 74 6f 20 6f 72 20  and equal to or 
ae80: 6c 65 73 73 20 74 68 61 6e 20 36 34 2e 20 0a 3c  less than 64. .<
ae90: 2f 6f 6c 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  /ol>..<h2 tags="
aea0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
aeb0: 6f 6e 20 6d 61 70 70 69 6e 67 22 3e 53 6f 72 74  on mapping">Sort
aec0: 69 6e 67 20 62 79 20 41 75 78 69 6c 69 61 72 79  ing by Auxiliary
aed0: 20 46 75 6e 63 74 69 6f 6e 20 52 65 73 75 6c 74   Function Result
aee0: 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 41 6c 6c 20  s</h2>..<p> All 
aef0: 46 54 53 35 20 74 61 62 6c 65 73 20 66 65 61 74  FTS5 tables feat
af00: 75 72 65 20 61 20 73 70 65 63 69 61 6c 20 68 69  ure a special hi
af10: 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  dden column name
af20: 64 20 22 72 61 6e 6b 22 2e 20 49 66 20 74 68 65  d "rank". If the
af30: 0a 63 75 72 72 65 6e 74 20 71 75 65 72 79 20 69  .current query i
af40: 73 20 6e 6f 74 20 61 20 66 75 6c 6c 2d 74 65 78  s not a full-tex
af50: 74 20 71 75 65 72 79 20 28 69 2e 65 2e 20 69 66  t query (i.e. if
af60: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63   it does not inc
af70: 6c 75 64 65 20 61 20 4d 41 54 43 48 0a 6f 70 65  lude a MATCH.ope
af80: 72 61 74 6f 72 29 2c 20 74 68 65 20 76 61 6c 75  rator), the valu
af90: 65 20 6f 66 20 74 68 65 20 22 72 61 6e 6b 22 20  e of the "rank" 
afa0: 63 6f 6c 75 6d 6e 20 69 73 20 61 6c 77 61 79 73  column is always
afb0: 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65   NULL. Otherwise
afc0: 2c 20 69 6e 20 61 0a 66 75 6c 6c 2d 74 65 78 74  , in a.full-text
afd0: 20 71 75 65 72 79 2c 20 63 6f 6c 75 6d 6e 20 72   query, column r
afe0: 61 6e 6b 20 63 6f 6e 74 61 69 6e 73 20 62 79 20  ank contains by 
aff0: 64 65 66 61 75 6c 74 20 74 68 65 20 73 61 6d 65  default the same
b000: 20 76 61 6c 75 65 20 61 73 20 77 6f 75 6c 64 20   value as would 
b010: 62 65 0a 72 65 74 75 72 6e 65 64 20 62 79 20 65  be.returned by e
b020: 78 65 63 75 74 69 6e 67 20 74 68 65 20 62 6d 32  xecuting the bm2
b030: 35 28 29 20 61 75 78 69 6c 69 61 72 79 20 66 75  5() auxiliary fu
b040: 6e 63 74 69 6f 6e 20 77 69 74 68 20 6e 6f 20 74  nction with no t
b050: 72 61 69 6c 69 6e 67 20 0a 61 72 67 75 6d 65 6e  railing .argumen
b060: 74 73 2e 0a 0a 3c 70 3e 20 54 68 65 20 64 69 66  ts...<p> The dif
b070: 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
b080: 72 65 61 64 69 6e 67 20 66 72 6f 6d 20 74 68 65  reading from the
b090: 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 61 6e 64   rank column and
b0a0: 20 75 73 69 6e 67 20 74 68 65 20 62 6d 32 35 28   using the bm25(
b0b0: 29 0a 66 75 6e 63 74 69 6f 6e 20 64 69 72 65 63  ).function direc
b0c0: 74 6c 79 20 77 69 74 68 69 6e 20 74 68 65 20 71  tly within the q
b0d0: 75 65 72 79 20 69 73 20 6f 6e 6c 79 20 73 69 67  uery is only sig
b0e0: 6e 69 66 69 63 61 6e 74 20 77 68 65 6e 20 73 6f  nificant when so
b0f0: 72 74 69 6e 67 20 62 79 20 74 68 65 0a 72 65 74  rting by the.ret
b100: 75 72 6e 65 64 20 76 61 6c 75 65 2e 20 49 6e 20  urned value. In 
b110: 74 68 69 73 20 63 61 73 65 2c 20 75 73 69 6e 67  this case, using
b120: 20 22 72 61 6e 6b 22 20 69 73 20 66 61 73 74 65   "rank" is faste
b130: 72 20 74 68 61 6e 20 75 73 69 6e 67 20 62 6d 32  r than using bm2
b140: 35 28 29 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  5()...<codeblock
b150: 3e 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f  >.  <i>-- The fo
b160: 6c 6c 6f 77 69 6e 67 20 71 75 65 72 69 65 73 20  llowing queries 
b170: 61 72 65 20 6c 6f 67 69 63 61 6c 6c 79 20 65 71  are logically eq
b180: 75 69 76 61 6c 65 6e 74 2e 20 42 75 74 20 74 68  uivalent. But th
b190: 65 20 73 65 63 6f 6e 64 20 6d 61 79 3c 2f 69 3e  e second may</i>
b1a0: 0a 20 20 3c 69 3e 2d 2d 20 62 65 20 66 61 73 74  .  <i>-- be fast
b1b0: 65 72 2c 20 70 61 72 74 69 63 75 6c 61 72 6c 79  er, particularly
b1c0: 20 69 66 20 74 68 65 20 63 61 6c 6c 65 72 20 61   if the caller a
b1d0: 62 61 6e 64 6f 6e 73 20 74 68 65 20 71 75 65 72  bandons the quer
b1e0: 79 20 62 65 66 6f 72 65 3c 2f 69 3e 0a 20 20 3c  y before</i>.  <
b1f0: 69 3e 2d 2d 20 61 6c 6c 20 72 6f 77 73 20 68 61  i>-- all rows ha
b200: 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ve been returned
b210: 20 28 6f 72 20 69 66 20 74 68 65 20 71 75 65 72   (or if the quer
b220: 69 65 73 20 77 65 72 65 20 6d 6f 64 69 66 69 65  ies were modifie
b230: 64 20 74 6f 20 3c 2f 69 3e 0a 20 20 3c 69 3e 2d  d to </i>.  <i>-
b240: 2d 20 69 6e 63 6c 75 64 65 20 4c 49 4d 49 54 20  - include LIMIT 
b250: 63 6c 61 75 73 65 73 29 2e 3c 2f 69 3e 0a 20 20  clauses).</i>.  
b260: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
b270: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
b280: 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62 6d 32  H ? ORDER BY bm2
b290: 35 28 66 74 73 29 3b 0a 20 20 53 45 4c 45 43 54  5(fts);.  SELECT
b2a0: 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48 45 52   * FROM fts WHER
b2b0: 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20 4f 52  E fts MATCH ? OR
b2c0: 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63  DER BY rank;.</c
b2d0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49  odeblock>..<p> I
b2e0: 6e 73 74 65 61 64 20 6f 66 20 75 73 69 6e 67 20  nstead of using 
b2f0: 62 6d 32 35 28 29 20 77 69 74 68 20 6e 6f 20 74  bm25() with no t
b300: 72 61 69 6c 69 6e 67 20 61 72 67 75 6d 65 6e 74  railing argument
b310: 73 2c 20 74 68 65 20 73 70 65 63 69 66 69 63 20  s, the specific 
b320: 61 75 78 69 6c 69 61 72 79 0a 66 75 6e 63 74 69  auxiliary.functi
b330: 6f 6e 20 6d 61 70 70 65 64 20 74 6f 20 74 68 65  on mapped to the
b340: 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 6d 61 79   rank column may
b350: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 20 65   be configured e
b360: 69 74 68 65 72 20 6f 6e 20 61 20 70 65 72 2d 71  ither on a per-q
b370: 75 65 72 79 0a 62 61 73 69 73 2c 20 6f 72 20 62  uery.basis, or b
b380: 79 20 73 65 74 74 69 6e 67 20 61 20 64 69 66 66  y setting a diff
b390: 65 72 65 6e 74 20 70 65 72 73 69 73 74 65 6e 74  erent persistent
b3a0: 20 64 65 66 61 75 6c 74 20 66 6f 72 20 74 68 65   default for the
b3b0: 20 46 54 53 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e   FTS table...<p>
b3c0: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 63 68 61   In order to cha
b3d0: 6e 67 65 20 74 68 65 20 6d 61 70 70 69 6e 67 20  nge the mapping 
b3e0: 6f 66 20 74 68 65 20 72 61 6e 6b 20 63 6f 6c 75  of the rank colu
b3f0: 6d 6e 20 66 6f 72 20 61 20 73 69 6e 67 6c 65 20  mn for a single 
b400: 71 75 65 72 79 2c 20 0a 61 20 74 65 72 6d 20 73  query, .a term s
b410: 69 6d 69 6c 61 72 20 74 6f 20 65 69 74 68 65 72  imilar to either
b420: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
b430: 67 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  g is added to th
b440: 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e WHERE clause o
b450: 66 20 61 20 0a 71 75 65 72 79 3a 0a 0a 3c 63 6f  f a .query:..<co
b460: 64 65 62 6c 6f 63 6b 3e 0a 20 20 72 61 6e 6b 20  deblock>.  rank 
b470: 4d 41 54 43 48 20 27 61 75 78 69 6c 69 61 72 79  MATCH 'auxiliary
b480: 2d 66 75 6e 63 74 69 6f 6e 2d 6e 61 6d 65 28 61  -function-name(a
b490: 72 67 31 2c 20 61 72 67 32 2c 20 2e 2e 2e 29 27  rg1, arg2, ...)'
b4a0: 0a 20 20 72 61 6e 6b 20 3d 20 27 61 75 78 69 6c  .  rank = 'auxil
b4b0: 69 61 72 79 2d 66 75 6e 63 74 69 6f 6e 2d 6e 61  iary-function-na
b4c0: 6d 65 28 61 72 67 31 2c 20 61 72 67 32 2c 20 2e  me(arg1, arg2, .
b4d0: 2e 2e 29 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ..)'.</codeblock
b4e0: 3e 0a 0a 3c 70 3e 20 54 68 65 20 72 69 67 68 74  >..<p> The right
b4f0: 2d 68 61 6e 64 2d 73 69 64 65 20 6f 66 20 74 68  -hand-side of th
b500: 65 20 4d 41 54 43 48 20 6f 72 20 3d 20 6f 70 65  e MATCH or = ope
b510: 72 61 74 6f 72 20 6d 75 73 74 20 62 65 20 61 20  rator must be a 
b520: 63 6f 6e 73 74 61 6e 74 0a 65 78 70 72 65 73 73  constant.express
b530: 69 6f 6e 20 74 68 61 74 20 65 76 61 6c 75 61 74  ion that evaluat
b540: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  es to a string c
b550: 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 74 68 65  onsisting of the
b560: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
b570: 69 6f 6e 20 74 6f 0a 69 6e 76 6f 6b 65 2c 20 66  ion to.invoke, f
b580: 6f 6c 6c 6f 77 65 64 20 62 79 20 7a 65 72 6f 20  ollowed by zero 
b590: 6f 72 20 6d 6f 72 65 20 63 6f 6d 6d 61 20 73 65  or more comma se
b5a0: 70 61 72 61 74 65 64 20 61 72 67 75 6d 65 6e 74  parated argument
b5b0: 73 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68  s within parenth
b5c0: 65 73 69 73 2e 0a 41 72 67 75 6d 65 6e 74 73 20  esis..Arguments 
b5d0: 6d 75 73 74 20 62 65 20 53 51 4c 20 6c 69 74 65  must be SQL lite
b5e0: 72 61 6c 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c  rals. For exampl
b5f0: 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
b600: 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c    <i>-- The foll
b610: 6f 77 69 6e 67 20 71 75 65 72 69 65 73 20 61 72  owing queries ar
b620: 65 20 6c 6f 67 69 63 61 6c 6c 79 20 65 71 75 69  e logically equi
b630: 76 61 6c 65 6e 74 2e 20 42 75 74 20 74 68 65 20  valent. But the 
b640: 73 65 63 6f 6e 64 20 6d 61 79 3c 2f 69 3e 0a 20  second may</i>. 
b650: 20 3c 69 3e 2d 2d 20 62 65 20 66 61 73 74 65 72   <i>-- be faster
b660: 2e 20 53 65 65 20 61 62 6f 76 65 2e 20 3c 2f 69  . See above. </i
b670: 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  >.  SELECT * FRO
b680: 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73 20  M fts WHERE fts 
b690: 4d 41 54 43 48 20 3f 20 4f 52 44 45 52 20 42 59  MATCH ? ORDER BY
b6a0: 20 62 6d 32 35 28 66 74 73 2c 20 31 30 2e 30 2c   bm25(fts, 10.0,
b6b0: 20 35 2e 30 29 3b 0a 20 20 53 45 4c 45 43 54 20   5.0);.  SELECT 
b6c0: 2a 20 46 52 4f 4d 20 66 74 73 20 57 48 45 52 45  * FROM fts WHERE
b6d0: 20 66 74 73 20 4d 41 54 43 48 20 3f 20 41 4e 44   fts MATCH ? AND
b6e0: 20 72 61 6e 6b 20 4d 41 54 43 48 20 27 62 6d 32   rank MATCH 'bm2
b6f0: 35 28 31 30 2e 30 2c 20 35 2e 30 29 27 20 4f 52  5(10.0, 5.0)' OR
b700: 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63  DER BY rank;.</c
b710: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
b720: 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20  he table-valued 
b730: 66 75 6e 63 74 69 6f 6e 20 73 79 6e 74 61 78 20  function syntax 
b740: 6d 61 79 20 61 6c 73 6f 20 62 65 20 75 73 65 64  may also be used
b750: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
b760: 6c 74 65 72 6e 61 74 69 76 65 0a 72 61 6e 6b 69  lternative.ranki
b770: 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 20 49 6e 20  ng function. In 
b780: 74 68 69 73 20 63 61 73 65 20 74 68 65 20 74 65  this case the te
b790: 78 74 20 64 65 73 63 72 69 62 69 6e 67 20 74 68  xt describing th
b7a0: 65 20 72 61 6e 6b 69 6e 67 20 66 75 6e 63 74 69  e ranking functi
b7b0: 6f 6e 20 73 68 6f 75 6c 64 0a 62 65 20 73 70 65  on should.be spe
b7c0: 63 69 66 69 65 64 20 61 73 20 74 68 65 20 73 65  cified as the se
b7d0: 63 6f 6e 64 20 74 61 62 6c 65 2d 76 61 6c 75 65  cond table-value
b7e0: 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
b7f0: 65 6e 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ent. The followi
b800: 6e 67 20 74 68 72 65 65 0a 71 75 65 72 69 65 73  ng three.queries
b810: 20 61 72 65 20 65 71 75 69 76 61 6c 65 6e 74 3a   are equivalent:
b820: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
b830: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
b840: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
b850: 48 20 3f 20 41 4e 44 20 72 61 6e 6b 20 4d 41 54  H ? AND rank MAT
b860: 43 48 20 27 62 6d 32 35 28 31 30 2e 30 2c 20 35  CH 'bm25(10.0, 5
b870: 2e 30 29 27 20 4f 52 44 45 52 20 42 59 20 72 61  .0)' ORDER BY ra
b880: 6e 6b 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  nk;.  SELECT * F
b890: 52 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74  ROM fts WHERE ft
b8a0: 73 20 3d 20 3f 20 41 4e 44 20 72 61 6e 6b 20 3d  s = ? AND rank =
b8b0: 20 27 62 6d 32 35 28 31 30 2e 30 2c 20 35 2e 30   'bm25(10.0, 5.0
b8c0: 29 27 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b  )' ORDER BY rank
b8d0: 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  ;.  SELECT * FRO
b8e0: 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73 28  M fts WHERE fts(
b8f0: 3f 2c 20 27 62 6d 32 35 28 31 30 2e 30 2c 20 35  ?, 'bm25(10.0, 5
b900: 2e 30 29 27 29 20 4f 52 44 45 52 20 42 59 20 72  .0)') ORDER BY r
b910: 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ank;.</codeblock
b920: 3e 0a 0a 3c 70 3e 20 54 68 65 20 64 65 66 61 75  >..<p> The defau
b930: 6c 74 20 6d 61 70 70 69 6e 67 20 6f 66 20 74 68  lt mapping of th
b940: 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 66 6f  e rank column fo
b950: 72 20 61 20 74 61 62 6c 65 20 6d 61 79 20 62 65  r a table may be
b960: 20 6d 6f 64 69 66 69 65 64 20 0a 75 73 69 6e 67   modified .using
b970: 20 74 68 65 20 5b 46 54 53 35 20 72 61 6e 6b 20   the [FTS5 rank 
b980: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b990: 74 69 6f 6e 5d 2e 0a 0a 3c 68 31 3e 53 70 65 63  tion]...<h1>Spec
b9a0: 69 61 6c 20 49 4e 53 45 52 54 20 43 6f 6d 6d 61  ial INSERT Comma
b9b0: 6e 64 73 3c 2f 68 31 3e 0a 0a 3c 68 32 20 74 61  nds</h1>..<h2 ta
b9c0: 67 73 3d 22 46 54 53 35 20 61 75 74 6f 6d 65 72  gs="FTS5 automer
b9d0: 67 65 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20 27  ge option">The '
b9e0: 61 75 74 6f 6d 65 72 67 65 27 20 43 6f 6e 66 69  automerge' Confi
b9f0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c  guration Option<
ba00: 2f 68 32 3e 0a 0a 3c 70 3e 0a 20 20 49 6e 73 74  /h2>..<p>.  Inst
ba10: 65 61 64 20 6f 66 20 75 73 69 6e 67 20 61 20 73  ead of using a s
ba20: 69 6e 67 6c 65 20 64 61 74 61 20 73 74 72 75 63  ingle data struc
ba30: 74 75 72 65 20 6f 6e 20 64 69 73 6b 20 74 6f 20  ture on disk to 
ba40: 73 74 6f 72 65 20 74 68 65 20 66 75 6c 6c 2d 74  store the full-t
ba50: 65 78 74 0a 20 20 69 6e 64 65 78 2c 20 46 54 53  ext.  index, FTS
ba60: 35 20 75 73 65 73 20 61 20 73 65 72 69 65 73 20  5 uses a series 
ba70: 6f 66 20 62 2d 74 72 65 65 73 2e 20 45 61 63 68  of b-trees. Each
ba80: 20 74 69 6d 65 20 61 20 6e 65 77 20 74 72 61 6e   time a new tran
ba90: 73 61 63 74 69 6f 6e 20 69 73 0a 20 20 63 6f 6d  saction is.  com
baa0: 6d 69 74 74 65 64 2c 20 61 20 6e 65 77 20 62 2d  mitted, a new b-
bab0: 74 72 65 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tree containing 
bac0: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
bad0: 74 68 65 20 63 6f 6d 6d 69 74 74 65 64 20 74 72  the committed tr
bae0: 61 6e 73 61 63 74 69 6f 6e 0a 20 20 69 73 20 77  ansaction.  is w
baf0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
bb00: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 57  database file. W
bb10: 68 65 6e 20 74 68 65 20 66 75 6c 6c 2d 74 65 78  hen the full-tex
bb20: 74 20 69 6e 64 65 78 20 69 73 20 71 75 65 72 69  t index is queri
bb30: 65 64 2c 20 65 61 63 68 0a 20 20 62 2d 74 72 65  ed, each.  b-tre
bb40: 65 20 6d 75 73 74 20 62 65 20 71 75 65 72 69 65  e must be querie
bb50: 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 61  d individually a
bb60: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 73 20 6d  nd the results m
bb70: 65 72 67 65 64 20 62 65 66 6f 72 65 20 62 65 69  erged before bei
bb80: 6e 67 0a 20 20 72 65 74 75 72 6e 65 64 20 74 6f  ng.  returned to
bb90: 20 74 68 65 20 75 73 65 72 2e 0a 0a 3c 70 3e 0a   the user...<p>.
bba0: 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 70 72    In order to pr
bbb0: 65 76 65 6e 74 20 74 68 65 20 6e 75 6d 62 65 72  event the number
bbc0: 20 6f 66 20 62 2d 74 72 65 65 73 20 69 6e 20 74   of b-trees in t
bbd0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
bbe0: 20 62 65 63 6f 6d 69 6e 67 20 74 6f 6f 0a 20 20   becoming too.  
bbf0: 6c 61 72 67 65 20 28 73 6c 6f 77 69 6e 67 20 64  large (slowing d
bc00: 6f 77 6e 20 71 75 65 72 69 65 73 29 2c 20 73 6d  own queries), sm
bc10: 61 6c 6c 65 72 20 62 2d 74 72 65 65 73 20 61 72  aller b-trees ar
bc20: 65 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 6d  e periodically m
bc30: 65 72 67 65 64 20 69 6e 74 6f 0a 20 20 73 69 6e  erged into.  sin
bc40: 67 6c 65 20 6c 61 72 67 65 72 20 62 2d 74 72 65  gle larger b-tre
bc50: 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  es containing th
bc60: 65 20 73 61 6d 65 20 64 61 74 61 2e 20 42 79 20  e same data. By 
bc70: 64 65 66 61 75 6c 74 2c 20 74 68 69 73 20 68 61  default, this ha
bc80: 70 70 65 6e 73 0a 20 20 61 75 74 6f 6d 61 74 69  ppens.  automati
bc90: 63 61 6c 6c 79 20 77 69 74 68 69 6e 20 49 4e 53  cally within INS
bca0: 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
bcb0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
bcc0: 20 74 68 61 74 20 6d 6f 64 69 66 79 20 74 68 65   that modify the
bcd0: 0a 20 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  .  full-text ind
bce0: 65 78 2e 20 54 68 65 20 27 61 75 74 6f 6d 65 72  ex. The 'automer
bcf0: 67 65 27 20 70 61 72 61 6d 65 74 65 72 20 64 65  ge' parameter de
bd00: 74 65 72 6d 69 6e 65 73 20 68 6f 77 20 6d 61 6e  termines how man
bd10: 79 20 73 6d 61 6c 6c 65 72 0a 20 20 62 2d 74 72  y smaller.  b-tr
bd20: 65 65 73 20 61 72 65 20 6d 65 72 67 65 64 20 74  ees are merged t
bd30: 6f 67 65 74 68 65 72 20 61 74 20 61 20 74 69 6d  ogether at a tim
bd40: 65 2e 20 53 65 74 74 69 6e 67 20 69 74 20 74 6f  e. Setting it to
bd50: 20 61 20 73 6d 61 6c 6c 20 76 61 6c 75 65 20 63   a small value c
bd60: 61 6e 0a 20 20 73 70 65 65 64 20 75 70 20 71 75  an.  speed up qu
bd70: 65 72 69 65 73 20 28 61 73 20 74 68 65 79 20 68  eries (as they h
bd80: 61 76 65 20 74 6f 20 71 75 65 72 79 20 61 6e 64  ave to query and
bd90: 20 6d 65 72 67 65 20 74 68 65 20 72 65 73 75 6c   merge the resul
bda0: 74 73 20 66 72 6f 6d 20 66 65 77 65 72 20 0a 20  ts from fewer . 
bdb0: 20 62 2d 74 72 65 65 73 29 2c 20 62 75 74 20 63   b-trees), but c
bdc0: 61 6e 20 61 6c 73 6f 20 73 6c 6f 77 20 64 6f 77  an also slow dow
bdd0: 6e 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  n writing to the
bde0: 20 64 61 74 61 62 61 73 65 20 28 61 73 20 65 61   database (as ea
bdf0: 63 68 20 49 4e 53 45 52 54 2c 0a 20 20 55 50 44  ch INSERT,.  UPD
be00: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
be10: 61 74 65 6d 65 6e 74 20 68 61 73 20 74 6f 20 64  atement has to d
be20: 6f 20 6d 6f 72 65 20 77 6f 72 6b 20 61 73 20 70  o more work as p
be30: 61 72 74 20 6f 66 20 74 68 65 20 61 75 74 6f 6d  art of the autom
be40: 61 74 69 63 0a 20 20 6d 65 72 67 69 6e 67 20 70  atic.  merging p
be50: 72 6f 63 65 73 73 29 2e 0a 0a 3c 70 3e 0a 20 20  rocess)...<p>.  
be60: 45 61 63 68 20 6f 66 20 74 68 65 20 62 2d 74 72  Each of the b-tr
be70: 65 65 73 20 74 68 61 74 20 6d 61 6b 65 20 75 70  ees that make up
be80: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
be90: 6e 64 65 78 20 69 73 20 61 73 73 69 67 6e 65 64  ndex is assigned
bea0: 20 74 6f 20 61 20 22 6c 65 76 65 6c 22 0a 20 20   to a "level".  
beb0: 62 61 73 65 64 20 6f 6e 20 69 74 73 20 73 69 7a  based on its siz
bec0: 65 2e 20 4c 65 76 65 6c 2d 30 20 62 2d 74 72 65  e. Level-0 b-tre
bed0: 65 73 20 61 72 65 20 74 68 65 20 73 6d 61 6c 6c  es are the small
bee0: 65 73 74 2c 20 61 73 20 74 68 65 79 20 63 6f 6e  est, as they con
bef0: 74 61 69 6e 20 74 68 65 0a 20 20 63 6f 6e 74 65  tain the.  conte
bf00: 6e 74 73 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  nts of a single 
bf10: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 48 69 67  transaction. Hig
bf20: 68 65 72 20 6c 65 76 65 6c 20 62 2d 74 72 65 65  her level b-tree
bf30: 73 20 61 72 65 20 74 68 65 20 72 65 73 75 6c 74  s are the result
bf40: 20 6f 66 0a 20 20 6d 65 72 67 69 6e 67 20 74 77   of.  merging tw
bf50: 6f 20 6f 72 20 6d 6f 72 65 20 6c 65 76 65 6c 2d  o or more level-
bf60: 30 20 62 2d 74 72 65 65 73 20 74 6f 67 65 74 68  0 b-trees togeth
bf70: 65 72 20 61 6e 64 20 73 6f 20 74 68 65 79 20 61  er and so they a
bf80: 72 65 20 6c 61 72 67 65 72 2e 20 46 54 53 35 0a  re larger. FTS5.
bf90: 20 20 62 65 67 69 6e 73 20 74 6f 20 6d 65 72 67    begins to merg
bfa0: 65 20 62 2d 74 72 65 65 73 20 74 6f 67 65 74 68  e b-trees togeth
bfb0: 65 72 20 6f 6e 63 65 20 74 68 65 72 65 20 65 78  er once there ex
bfc0: 69 73 74 20 3c 69 3e 4d 3c 2f 69 3e 20 6f 72 20  ist <i>M</i> or 
bfd0: 6d 6f 72 65 20 62 2d 74 72 65 65 73 20 0a 20 20  more b-trees .  
bfe0: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6c 65  with the same le
bff0: 76 65 6c 2c 20 77 68 65 72 65 20 3c 69 3e 4d 3c  vel, where <i>M<
c000: 2f 69 3e 20 69 73 20 74 68 65 20 76 61 6c 75 65  /i> is the value
c010: 20 6f 66 20 74 68 65 20 27 61 75 74 6f 6d 65 72   of the 'automer
c020: 67 65 27 20 0a 20 20 70 61 72 61 6d 65 74 65 72  ge' .  parameter
c030: 2e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 6d 61 78  ...<p>.  The max
c040: 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 76 61 6c  imum allowed val
c050: 75 65 20 66 6f 72 20 74 68 65 20 27 61 75 74 6f  ue for the 'auto
c060: 6d 65 72 67 65 27 20 70 61 72 61 6d 65 74 65 72  merge' parameter
c070: 20 69 73 20 31 36 2e 20 54 68 65 20 64 65 66 61   is 16. The defa
c080: 75 6c 74 0a 20 20 76 61 6c 75 65 20 69 73 20 34  ult.  value is 4
c090: 2e 20 53 65 74 74 69 6e 67 20 74 68 65 20 27 61  . Setting the 'a
c0a0: 75 74 6f 6d 65 72 67 65 27 20 70 61 72 61 6d 65  utomerge' parame
c0b0: 74 65 72 20 74 6f 20 30 20 64 69 73 61 62 6c 65  ter to 0 disable
c0c0: 73 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  s the automatic 
c0d0: 0a 20 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 6d  .  incremental m
c0e0: 65 72 67 69 6e 67 20 6f 66 20 62 2d 74 72 65 65  erging of b-tree
c0f0: 73 20 61 6c 74 6f 67 65 74 68 65 72 2e 0a 0a 3c  s altogether...<
c100: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53  codeblock>.  INS
c110: 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c 20  ERT INTO ft(ft, 
c120: 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 61 75  rank) VALUES('au
c130: 74 6f 6d 65 72 67 65 27 2c 20 38 29 3b 0a 3c 2f  tomerge', 8);.</
c140: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 3e  codeblock>..<h2>
c150: 54 68 65 20 27 63 72 69 73 69 73 6d 65 72 67 65  The 'crisismerge
c160: 27 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ' Configuration 
c170: 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  Option</h2>..<p>
c180: 54 68 65 20 27 63 72 69 73 69 73 6d 65 72 67 65  The 'crisismerge
c190: 27 20 6f 70 74 69 6f 6e 20 69 73 20 73 69 6d 69  ' option is simi
c1a0: 6c 61 72 20 74 6f 20 27 61 75 74 6f 6d 65 72 67  lar to 'automerg
c1b0: 65 27 2c 20 69 6e 20 74 68 61 74 20 69 74 20 64  e', in that it d
c1c0: 65 74 65 72 6d 69 6e 65 73 0a 68 6f 77 20 61 6e  etermines.how an
c1d0: 64 20 68 6f 77 20 6f 66 74 65 6e 20 74 68 65 20  d how often the 
c1e0: 63 6f 6d 70 6f 6e 65 6e 74 20 62 2d 74 72 65 65  component b-tree
c1f0: 73 20 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74  s that make up t
c200: 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he full-text ind
c210: 65 78 20 61 72 65 0a 6d 65 72 67 65 64 20 74 6f  ex are.merged to
c220: 67 65 74 68 65 72 2e 20 4f 6e 63 65 20 74 68 65  gether. Once the
c230: 72 65 20 65 78 69 73 74 20 3c 69 3e 43 3c 2f 69  re exist <i>C</i
c240: 3e 20 6f 72 20 6d 6f 72 65 20 62 2d 74 72 65 65  > or more b-tree
c250: 73 20 6f 6e 20 61 20 73 69 6e 67 6c 65 20 6c 65  s on a single le
c260: 76 65 6c 0a 77 69 74 68 69 6e 20 74 68 65 20 66  vel.within the f
c270: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2c 20  ull-text index, 
c280: 77 68 65 72 65 20 3c 69 3e 43 3c 2f 69 3e 20 69  where <i>C</i> i
c290: 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
c2a0: 68 65 20 27 63 72 69 73 69 73 6d 65 72 67 65 27  he 'crisismerge'
c2b0: 0a 6f 70 74 69 6f 6e 2c 20 61 6c 6c 20 62 2d 74  .option, all b-t
c2c0: 72 65 65 73 20 6f 6e 20 74 68 65 20 6c 65 76 65  rees on the leve
c2d0: 6c 20 61 72 65 20 69 6d 6d 65 64 69 61 74 65 6c  l are immediatel
c2e0: 79 20 6d 65 72 67 65 64 20 69 6e 74 6f 20 61 20  y merged into a 
c2f0: 73 69 6e 67 6c 65 20 62 2d 74 72 65 65 2e 0a 0a  single b-tree...
c300: 3c 70 3e 54 68 65 20 64 69 66 66 65 72 65 6e 63  <p>The differenc
c310: 65 20 62 65 74 77 65 65 6e 20 74 68 69 73 20 6f  e between this o
c320: 70 74 69 6f 6e 20 61 6e 64 20 74 68 65 20 27 61  ption and the 'a
c330: 75 74 6f 6d 65 72 67 65 27 20 6f 70 74 69 6f 6e  utomerge' option
c340: 20 69 73 20 74 68 61 74 20 77 68 65 6e 0a 74 68   is that when.th
c350: 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20 6c 69  e 'automerge' li
c360: 6d 69 74 20 69 73 20 72 65 61 63 68 65 64 20 46  mit is reached F
c370: 54 53 35 20 6f 6e 6c 79 20 62 65 67 69 6e 73 20  TS5 only begins 
c380: 74 6f 20 6d 65 72 67 65 20 74 68 65 20 62 2d 74  to merge the b-t
c390: 72 65 65 73 0a 74 6f 67 65 74 68 65 72 2e 20 4d  rees.together. M
c3a0: 6f 73 74 20 6f 66 20 74 68 65 20 77 6f 72 6b 20  ost of the work 
c3b0: 69 73 20 70 65 72 66 6f 72 6d 65 64 20 61 73 20  is performed as 
c3c0: 70 61 72 74 20 6f 66 20 73 75 62 73 65 71 75 65  part of subseque
c3d0: 6e 74 20 49 4e 53 45 52 54 2c 20 0a 55 50 44 41  nt INSERT, .UPDA
c3e0: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 6f 70 65  TE or DELETE ope
c3f0: 72 61 74 69 6f 6e 73 2e 20 57 68 65 72 65 61 73  rations. Whereas
c400: 20 77 68 65 6e 20 74 68 65 20 27 63 72 69 73 69   when the 'crisi
c410: 73 6d 65 72 67 65 27 20 6c 69 6d 69 74 20 69 73  smerge' limit is
c420: 20 72 65 61 63 68 65 64 2c 0a 74 68 65 20 6f 66   reached,.the of
c430: 66 65 6e 64 69 6e 67 20 62 2d 74 72 65 65 73 20  fending b-trees 
c440: 61 72 65 20 61 6c 6c 20 6d 65 72 67 65 64 20 69  are all merged i
c450: 6d 6d 65 64 69 61 74 65 6c 79 2e 20 54 68 69 73  mmediately. This
c460: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 49   means that an I
c470: 4e 53 45 52 54 2c 0a 55 50 44 41 54 45 20 6f 72  NSERT,.UPDATE or
c480: 20 44 45 4c 45 54 45 20 74 68 61 74 20 74 72 69   DELETE that tri
c490: 67 67 65 72 73 20 61 20 63 72 69 73 69 73 2d 6d  ggers a crisis-m
c4a0: 65 72 67 65 20 6d 61 79 20 74 61 6b 65 20 61 20  erge may take a 
c4b0: 6c 6f 6e 67 20 74 69 6d 65 20 74 6f 20 0a 63 6f  long time to .co
c4c0: 6d 70 6c 65 74 65 2e 0a 0a 3c 70 3e 54 68 65 20  mplete...<p>The 
c4d0: 64 65 66 61 75 6c 74 20 27 63 72 69 73 69 73 6d  default 'crisism
c4e0: 65 72 67 65 27 20 76 61 6c 75 65 20 69 73 20 31  erge' value is 1
c4f0: 36 2e 20 54 68 65 72 65 20 69 73 20 6e 6f 20 6d  6. There is no m
c500: 61 78 69 6d 75 6d 20 6c 69 6d 69 74 2e 20 41 74  aximum limit. At
c510: 74 65 6d 70 74 69 6e 67 0a 74 6f 20 73 65 74 20  tempting.to set 
c520: 74 68 65 20 27 63 72 69 73 69 73 6d 65 72 67 65  the 'crisismerge
c530: 27 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  ' parameter to a
c540: 20 76 61 6c 75 65 20 6f 66 20 30 20 6f 72 20 31   value of 0 or 1
c550: 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
c560: 6f 0a 73 65 74 74 69 6e 67 20 69 74 20 74 6f 20  o.setting it to 
c570: 74 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  the default valu
c580: 65 20 28 31 36 29 2e 20 49 74 20 69 73 20 61 6e  e (16). It is an
c590: 20 65 72 72 6f 72 20 74 6f 20 61 74 74 65 6d 70   error to attemp
c5a0: 74 20 74 6f 20 73 65 74 20 74 68 65 0a 27 63 72  t to set the.'cr
c5b0: 69 73 69 73 6d 65 72 67 65 27 20 6f 70 74 69 6f  isismerge' optio
c5c0: 6e 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  n to a negative 
c5d0: 76 61 6c 75 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  value...<codeblo
c5e0: 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  ck>.  INSERT INT
c5f0: 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b 29 20 56  O ft(ft, rank) V
c600: 41 4c 55 45 53 28 27 63 72 69 73 69 73 6d 65 72  ALUES('crisismer
c610: 67 65 27 2c 20 31 36 29 3b 0a 3c 2f 63 6f 64 65  ge', 16);.</code
c620: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73  block>..<h2 tags
c630: 3d 22 46 54 53 35 20 64 65 6c 65 74 65 20 63 6f  ="FTS5 delete co
c640: 6d 6d 61 6e 64 22 3e 54 68 65 20 27 64 65 6c 65  mmand">The 'dele
c650: 74 65 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e  te' Command</h2>
c660: 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61  ..<p> This comma
c670: 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  nd is only avail
c680: 61 62 6c 65 20 77 69 74 68 20 5b 46 54 53 35 20  able with [FTS5 
c690: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
c6a0: 20 74 61 62 6c 65 73 20 7c 0a 65 78 74 65 72 6e   tables |.extern
c6b0: 61 6c 20 63 6f 6e 74 65 6e 74 5d 20 61 6e 64 20  al content] and 
c6c0: 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65 73  [FTS5 contentles
c6d0: 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74 65  s tables | conte
c6e0: 6e 74 6c 65 73 73 5d 20 74 61 62 6c 65 73 2e 20  ntless] tables. 
c6f0: 49 74 0a 69 73 20 75 73 65 64 20 74 6f 20 64 65  It.is used to de
c700: 6c 65 74 65 20 74 68 65 20 69 6e 64 65 78 20 65  lete the index e
c710: 6e 74 72 69 65 73 20 61 73 73 6f 63 69 61 74 65  ntries associate
c720: 64 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20  d with a single 
c730: 72 6f 77 20 66 72 6f 6d 20 74 68 65 0a 66 75 6c  row from the.ful
c740: 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e 20 54 68  l-text index. Th
c750: 69 73 20 63 6f 6d 6d 61 6e 64 20 61 6e 64 20 74  is command and t
c760: 68 65 20 5b 46 54 53 35 20 64 65 6c 65 74 65 2d  he [FTS5 delete-
c770: 61 6c 6c 20 63 6f 6d 6d 61 6e 64 20 7c 20 64 65  all command | de
c780: 6c 65 74 65 2d 61 6c 6c 5d 0a 63 6f 6d 6d 61 6e  lete-all].comman
c790: 64 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 77  d are the only w
c7a0: 61 79 73 20 74 6f 20 72 65 6d 6f 76 65 20 65 6e  ays to remove en
c7b0: 74 72 69 65 73 20 66 72 6f 6d 20 74 68 65 20 66  tries from the f
c7c0: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 6f  ull-text index o
c7d0: 66 20 61 0a 63 6f 6e 74 65 6e 74 6c 65 73 73 20  f a.contentless 
c7e0: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 49 6e 20 6f  table...<p> In o
c7f0: 72 64 65 72 20 74 6f 20 75 73 65 20 74 68 69 73  rder to use this
c800: 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 64 65 6c 65   command to dele
c810: 74 65 20 61 20 72 6f 77 2c 20 74 68 65 20 74 65  te a row, the te
c820: 78 74 20 76 61 6c 75 65 20 27 64 65 6c 65 74 65  xt value 'delete
c830: 27 20 0a 6d 75 73 74 20 62 65 20 69 6e 73 65 72  ' .must be inser
c840: 74 65 64 20 69 6e 74 6f 20 74 68 65 20 73 70 65  ted into the spe
c850: 63 69 61 6c 20 63 6f 6c 75 6d 6e 20 77 69 74 68  cial column with
c860: 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
c870: 73 20 74 68 65 20 74 61 62 6c 65 2e 0a 54 68 65  s the table..The
c880: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
c890: 77 20 74 6f 20 64 65 6c 65 74 65 20 69 73 20 69  w to delete is i
c8a0: 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65  nserted into the
c8b0: 20 72 6f 77 69 64 20 63 6f 6c 75 6d 6e 2e 20 54   rowid column. T
c8c0: 68 65 0a 76 61 6c 75 65 73 20 69 6e 73 65 72 74  he.values insert
c8d0: 65 64 20 69 6e 74 6f 20 74 68 65 20 6f 74 68 65  ed into the othe
c8e0: 72 20 63 6f 6c 75 6d 6e 73 20 6d 75 73 74 20 6d  r columns must m
c8f0: 61 74 63 68 20 74 68 65 20 76 61 6c 75 65 73 20  atch the values 
c900: 63 75 72 72 65 6e 74 6c 79 0a 73 74 6f 72 65 64  currently.stored
c910: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 46   in the table. F
c920: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
c930: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
c940: 20 49 6e 73 65 72 74 20 61 20 72 6f 77 20 77 69   Insert a row wi
c950: 74 68 20 72 6f 77 69 64 3d 31 34 20 69 6e 74 6f  th rowid=14 into
c960: 20 74 68 65 20 66 74 73 35 20 74 61 62 6c 65 2e   the fts5 table.
c970: 3c 2f 69 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e  </i>.  INSERT IN
c980: 54 4f 20 66 74 28 72 6f 77 69 64 2c 20 61 2c 20  TO ft(rowid, a, 
c990: 62 2c 20 63 29 20 56 41 4c 55 45 53 28 31 34 2c  b, c) VALUES(14,
c9a0: 20 24 61 2c 20 24 62 2c 20 24 63 29 3b 0a 20 20   $a, $b, $c);.  
c9b0: 0a 20 20 3c 69 3e 2d 2d 20 52 65 6d 6f 76 65 20  .  <i>-- Remove 
c9c0: 74 68 65 20 73 61 6d 65 20 72 6f 77 20 66 72 6f  the same row fro
c9d0: 6d 20 74 68 65 20 66 74 73 35 20 74 61 62 6c 65  m the fts5 table
c9e0: 2e 3c 2f 69 3e 0a 20 20 49 4e 53 45 52 54 20 49  .</i>.  INSERT I
c9f0: 4e 54 4f 20 66 74 28 66 74 2c 20 72 6f 77 69 64  NTO ft(ft, rowid
ca00: 2c 20 61 2c 20 62 2c 20 63 29 20 56 41 4c 55 45  , a, b, c) VALUE
ca10: 53 28 27 64 65 6c 65 74 65 27 2c 20 31 34 2c 20  S('delete', 14, 
ca20: 24 61 2c 20 24 62 2c 20 24 63 29 3b 0a 3c 2f 63  $a, $b, $c);.</c
ca30: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49  odeblock>..<p> I
ca40: 66 20 74 68 65 20 76 61 6c 75 65 73 20 22 69 6e  f the values "in
ca50: 73 65 72 74 65 64 22 20 69 6e 74 6f 20 74 68 65  serted" into the
ca60: 20 74 65 78 74 20 63 6f 6c 75 6d 6e 73 20 61 73   text columns as
ca70: 20 70 61 72 74 20 6f 66 20 61 20 27 64 65 6c 65   part of a 'dele
ca80: 74 65 27 0a 63 6f 6d 6d 61 6e 64 20 61 72 65 20  te'.command are 
ca90: 6e 6f 74 20 74 68 65 20 73 61 6d 65 20 61 73 20  not the same as 
caa0: 74 68 6f 73 65 20 63 75 72 72 65 6e 74 6c 79 20  those currently 
cab0: 73 74 6f 72 65 64 20 77 69 74 68 69 6e 20 74 68  stored within th
cac0: 65 20 74 61 62 6c 65 2c 20 74 68 65 0a 72 65 73  e table, the.res
cad0: 75 6c 74 73 20 6d 61 79 20 62 65 20 75 6e 70 72  ults may be unpr
cae0: 65 64 69 63 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20  edictable...<p> 
caf0: 54 68 65 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  The reason for t
cb00: 68 69 73 20 69 73 20 65 61 73 79 20 74 6f 20 75  his is easy to u
cb10: 6e 64 65 72 73 74 61 6e 64 3a 20 57 68 65 6e 20  nderstand: When 
cb20: 61 20 64 6f 63 75 6d 65 6e 74 20 69 73 20 69 6e  a document is in
cb30: 73 65 72 74 65 64 0a 69 6e 74 6f 20 74 68 65 20  serted.into the 
cb40: 46 54 53 35 20 74 61 62 6c 65 2c 20 61 6e 20 65  FTS5 table, an e
cb50: 6e 74 72 79 20 69 73 20 61 64 64 65 64 20 74 6f  ntry is added to
cb60: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
cb70: 6e 64 65 78 20 74 6f 20 72 65 63 6f 72 64 20 74  ndex to record t
cb80: 68 65 0a 70 6f 73 69 74 69 6f 6e 20 6f 66 20 65  he.position of e
cb90: 61 63 68 20 74 6f 6b 65 6e 20 77 69 74 68 69 6e  ach token within
cba0: 20 74 68 65 20 6e 65 77 20 64 6f 63 75 6d 65 6e   the new documen
cbb0: 74 2e 20 57 68 65 6e 20 61 20 64 6f 63 75 6d 65  t. When a docume
cbc0: 6e 74 20 69 73 20 72 65 6d 6f 76 65 64 2c 0a 74  nt is removed,.t
cbd0: 68 65 20 6f 72 69 67 69 6e 61 6c 20 64 61 74 61  he original data
cbe0: 20 69 73 20 72 65 71 75 69 72 65 64 20 69 6e 20   is required in 
cbf0: 6f 72 64 65 72 20 74 6f 20 64 65 74 65 72 6d 69  order to determi
cc00: 6e 65 20 74 68 65 20 73 65 74 20 6f 66 20 65 6e  ne the set of en
cc10: 74 72 69 65 73 20 74 68 61 74 0a 6e 65 65 64 20  tries that.need 
cc20: 74 6f 20 62 65 20 72 65 6d 6f 76 65 64 20 66 72  to be removed fr
cc30: 6f 6d 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74  om the full-text
cc40: 20 69 6e 64 65 78 2e 20 53 6f 20 69 66 20 74 68   index. So if th
cc50: 65 20 64 61 74 61 20 73 75 70 70 6c 69 65 64 20  e data supplied 
cc60: 74 6f 20 46 54 53 35 0a 77 68 65 6e 20 61 20 72  to FTS5.when a r
cc70: 6f 77 20 69 73 20 64 65 6c 65 74 65 64 20 75 73  ow is deleted us
cc80: 69 6e 67 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64  ing this command
cc90: 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
cca0: 6f 6d 20 74 68 61 74 20 75 73 65 64 20 74 6f 0a  om that used to.
ccb0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 65  determine the se
ccc0: 74 20 6f 66 20 74 6f 6b 65 6e 20 69 6e 73 74 61  t of token insta
ccd0: 6e 63 65 73 20 77 68 65 6e 20 69 74 20 77 61 73  nces when it was
cce0: 20 69 6e 73 65 72 74 65 64 2c 20 73 6f 6d 65 20   inserted, some 
ccf0: 66 75 6c 6c 2d 74 65 78 74 20 0a 69 6e 64 65 78  full-text .index
cd00: 20 65 6e 74 72 69 65 73 20 6d 61 79 20 6e 6f 74   entries may not
cd10: 20 62 65 20 63 6f 72 72 65 63 74 6c 79 20 64 65   be correctly de
cd20: 6c 65 74 65 64 2c 20 6f 72 20 46 54 53 35 20 6d  leted, or FTS5 m
cd30: 61 79 20 74 72 79 20 74 6f 20 72 65 6d 6f 76 65  ay try to remove
cd40: 20 69 6e 64 65 78 20 0a 65 6e 74 72 69 65 73 20   index .entries 
cd50: 74 68 61 74 20 64 6f 20 6e 6f 74 20 65 78 69 73  that do not exis
cd60: 74 2e 20 54 68 69 73 20 63 61 6e 20 6c 65 61 76  t. This can leav
cd70: 65 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  e the full-text 
cd80: 69 6e 64 65 78 20 69 6e 20 61 6e 0a 75 6e 70 72  index in an.unpr
cd90: 65 64 69 63 74 61 62 6c 65 20 73 74 61 74 65 2c  edictable state,
cda0: 20 6d 61 6b 69 6e 67 20 66 75 74 75 72 65 20 71   making future q
cdb0: 75 65 72 79 20 72 65 73 75 6c 74 73 20 75 6e 72  uery results unr
cdc0: 65 6c 69 61 62 6c 65 2e 0a 0a 3c 68 32 20 74 61  eliable...<h2 ta
cdd0: 67 73 3d 22 46 54 53 35 20 64 65 6c 65 74 65 2d  gs="FTS5 delete-
cde0: 61 6c 6c 20 63 6f 6d 6d 61 6e 64 22 3e 54 68 65  all command">The
cdf0: 20 27 64 65 6c 65 74 65 2d 61 6c 6c 27 20 43 6f   'delete-all' Co
ce00: 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20  mmand</h2>..<p> 
ce10: 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20  This command is 
ce20: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
ce30: 69 74 68 20 5b 46 54 53 35 20 65 78 74 65 72 6e  ith [FTS5 extern
ce40: 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  al content table
ce50: 73 20 7c 0a 65 78 74 65 72 6e 61 6c 20 63 6f 6e  s |.external con
ce60: 74 65 6e 74 5d 20 61 6e 64 20 5b 46 54 53 35 20  tent] and [FTS5 
ce70: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
ce80: 65 73 20 7c 20 63 6f 6e 74 65 6e 74 6c 65 73 73  es | contentless
ce90: 5d 20 74 61 62 6c 65 73 2e 20 49 74 0a 64 65 6c  ] tables. It.del
cea0: 65 74 65 73 20 61 6c 6c 20 65 6e 74 72 69 65 73  etes all entries
ceb0: 20 66 72 6f 6d 20 74 68 65 20 66 75 6c 6c 2d 74   from the full-t
cec0: 65 78 74 20 69 6e 64 65 78 2e 0a 0a 3c 63 6f 64  ext index...<cod
ced0: 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54  eblock>.  INSERT
cee0: 20 49 4e 54 4f 20 66 74 28 66 74 29 20 56 41 4c   INTO ft(ft) VAL
cef0: 55 45 53 28 27 64 65 6c 65 74 65 2d 61 6c 6c 27  UES('delete-all'
cf00: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
cf10: 0a 3c 68 32 3e 54 68 65 20 27 69 6e 74 65 67 72  .<h2>The 'integr
cf20: 69 74 79 2d 63 68 65 63 6b 27 20 43 6f 6d 6d 61  ity-check' Comma
cf30: 6e 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69  nd</h2>..<p> Thi
cf40: 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65  s command is use
cf50: 64 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  d to verify that
cf60: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
cf70: 6e 64 65 78 20 69 73 20 63 6f 6e 73 69 73 74 65  ndex is consiste
cf80: 6e 74 20 0a 77 69 74 68 20 74 68 65 20 63 6f 6e  nt .with the con
cf90: 74 65 6e 74 73 20 6f 66 20 74 68 65 20 46 54 53  tents of the FTS
cfa0: 35 20 74 61 62 6c 65 20 6f 72 20 5b 46 54 53 35  5 table or [FTS5
cfb0: 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e   external conten
cfc0: 74 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74 65  t tables | conte
cfd0: 6e 74 20 0a 74 61 62 6c 65 5d 2e 20 49 74 20 69  nt .table]. It i
cfe0: 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
cff0: 77 69 74 68 20 5b 46 54 53 35 20 63 6f 6e 74 65  with [FTS5 conte
d000: 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c 20  ntless tables | 
d010: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
d020: 65 73 5d 2e 0a 0a 3c 70 3e 54 68 65 20 69 6e 74  es]...<p>The int
d030: 65 67 72 69 74 79 2d 63 68 65 63 6b 20 63 6f 6d  egrity-check com
d040: 6d 61 6e 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  mand is invoked 
d050: 62 79 20 69 6e 73 65 72 74 69 6e 67 20 74 68 65  by inserting the
d060: 20 74 65 78 74 20 76 61 6c 75 65 0a 27 69 6e 74   text value.'int
d070: 65 67 72 69 74 79 2d 63 68 65 63 6b 27 20 69 6e  egrity-check' in
d080: 74 6f 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  to the special c
d090: 6f 6c 75 6d 6e 20 77 69 74 68 20 74 68 65 20 73  olumn with the s
d0a0: 61 6d 65 20 6e 61 6d 65 20 61 73 20 74 68 65 20  ame name as the 
d0b0: 46 54 53 35 0a 74 61 62 6c 65 2e 20 46 6f 72 20  FTS5.table. For 
d0c0: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
d0d0: 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49  lock>.  INSERT I
d0e0: 4e 54 4f 20 66 74 28 66 74 29 20 56 41 4c 55 45  NTO ft(ft) VALUE
d0f0: 53 28 27 69 6e 74 65 67 72 69 74 79 2d 63 68 65  S('integrity-che
d100: 63 6b 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ck');.</codebloc
d110: 6b 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 66 75  k>..<p>If the fu
d120: 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 69 73  ll-text index is
d130: 20 63 6f 6e 73 69 73 74 65 6e 74 20 77 69 74 68   consistent with
d140: 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
d150: 20 74 68 65 20 74 61 62 6c 65 2c 20 74 68 65 0a   the table, the.
d160: 49 4e 53 45 52 54 20 75 73 65 64 20 74 6f 20 69  INSERT used to i
d170: 6e 76 6f 6b 65 20 74 68 65 20 69 6e 74 65 67 72  nvoke the integr
d180: 69 74 79 2d 63 68 65 63 6b 20 63 6f 6d 6d 61 6e  ity-check comman
d190: 64 20 73 75 63 63 65 65 64 73 2e 20 4f 72 2c 20  d succeeds. Or, 
d1a0: 69 66 20 61 6e 79 0a 64 69 73 63 72 65 70 61 6e  if any.discrepan
d1b0: 63 79 20 69 73 20 66 6f 75 6e 64 2c 20 69 74 20  cy is found, it 
d1c0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53  fails with an [S
d1d0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
d1e0: 41 42 5d 20 65 72 72 6f 72 2e 0a 0a 3c 68 32 20  AB] error...<h2 
d1f0: 74 61 67 73 3d 22 46 54 53 35 20 6d 65 72 67 65  tags="FTS5 merge
d200: 20 63 6f 6d 6d 61 6e 64 22 3e 54 68 65 20 27 6d   command">The 'm
d210: 65 72 67 65 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68  erge' Command</h
d220: 32 3e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  2>..<codeblock>.
d230: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74    INSERT INTO ft
d240: 28 66 74 2c 20 72 61 6e 6b 29 20 56 41 4c 55 45  (ft, rank) VALUE
d250: 53 28 27 6d 65 72 67 65 27 2c 20 35 30 30 29 3b  S('merge', 500);
d260: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
d270: 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20  p> This command 
d280: 6d 65 72 67 65 73 20 62 2d 74 72 65 65 20 73 74  merges b-tree st
d290: 72 75 63 74 75 72 65 73 20 74 6f 67 65 74 68 65  ructures togethe
d2a0: 72 20 75 6e 74 69 6c 20 72 6f 75 67 68 6c 79 20  r until roughly 
d2b0: 4e 20 70 61 67 65 73 0a 6f 66 20 6d 65 72 67 65  N pages.of merge
d2c0: 64 20 64 61 74 61 20 68 61 76 65 20 62 65 65 6e  d data have been
d2d0: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
d2e0: 64 61 74 61 62 61 73 65 2c 20 77 68 65 72 65 20  database, where 
d2f0: 4e 20 69 73 20 74 68 65 20 61 62 73 6f 6c 75 74  N is the absolut
d300: 65 0a 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70  e.value of the p
d310: 61 72 61 6d 65 74 65 72 20 73 70 65 63 69 66 69  arameter specifi
d320: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
d330: 65 20 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e  e 'merge' comman
d340: 64 2e 20 54 68 65 20 73 69 7a 65 20 6f 66 0a 65  d. The size of.e
d350: 61 63 68 20 70 61 67 65 20 69 73 20 61 73 20 63  ach page is as c
d360: 6f 6e 66 69 67 75 72 65 64 20 62 79 20 74 68 65  onfigured by the
d370: 20 5b 46 54 53 35 20 70 67 73 7a 20 6f 70 74 69   [FTS5 pgsz opti
d380: 6f 6e 5d 2e 0a 0a 3c 70 3e 20 49 66 20 74 68 65  on]...<p> If the
d390: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
d3a0: 70 6f 73 74 69 76 65 20 76 61 6c 75 65 2c 20 42  postive value, B
d3b0: 2d 74 72 65 65 20 73 74 72 75 63 74 75 72 65 73  -tree structures
d3c0: 20 61 72 65 20 6f 6e 6c 79 20 65 6c 69 67 69 62   are only eligib
d3d0: 6c 65 0a 66 6f 72 20 6d 65 72 67 69 6e 67 20 69  le.for merging i
d3e0: 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  f one of the fol
d3f0: 6c 6f 77 69 6e 67 20 69 73 20 74 72 75 65 3a 0a  lowing is true:.
d400: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 54 68 65  .<ul>.  <li> The
d410: 72 65 20 61 72 65 20 55 20 6f 72 20 6d 6f 72 65  re are U or more
d420: 20 73 75 63 68 20 62 2d 74 72 65 65 73 20 6f 6e   such b-trees on
d430: 20 61 0a 20 20 20 20 20 20 20 73 69 6e 67 6c 65   a.       single
d440: 20 6c 65 76 65 6c 20 28 73 65 65 20 74 68 65 20   level (see the 
d450: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
d460: 72 20 74 68 65 20 5b 46 54 53 35 20 61 75 74 6f  r the [FTS5 auto
d470: 6d 65 72 67 65 20 6f 70 74 69 6f 6e 5d 0a 20 20  merge option].  
d480: 20 20 20 20 20 66 6f 72 20 61 6e 20 65 78 70 6c       for an expl
d490: 61 6e 61 74 69 6f 6e 20 6f 66 20 62 2d 74 72 65  anation of b-tre
d4a0: 65 20 6c 65 76 65 6c 73 29 2c 20 77 68 65 72 65  e levels), where
d4b0: 20 55 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   U is the value 
d4c0: 61 73 73 69 67 6e 65 64 0a 20 20 20 20 20 20 20  assigned.       
d4d0: 74 6f 20 74 68 65 20 5b 46 54 53 35 20 75 73 65  to the [FTS5 use
d4e0: 72 6d 65 72 67 65 20 6f 70 74 69 6f 6e 5d 20 6f  rmerge option] o
d4f0: 70 74 69 6f 6e 2e 0a 20 20 3c 6c 69 3e 20 41 20  ption..  <li> A 
d500: 6d 65 72 67 65 20 68 61 73 20 61 6c 72 65 61 64  merge has alread
d510: 79 20 62 65 65 6e 20 73 74 61 72 74 65 64 20 28  y been started (
d520: 70 65 72 68 61 70 73 20 62 79 20 61 20 27 6d 65  perhaps by a 'me
d530: 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 74 68 61  rge' command tha
d540: 74 0a 20 20 20 20 20 20 20 73 70 65 63 69 66 69  t.       specifi
d550: 65 64 20 61 20 6e 65 67 61 74 69 76 65 20 70 61  ed a negative pa
d560: 72 61 6d 65 74 65 72 29 2e 0a 3c 2f 75 6c 3e 0a  rameter)..</ul>.
d570: 0a 3c 70 3e 20 49 74 20 69 73 20 70 6f 73 73 69  .<p> It is possi
d580: 62 6c 65 20 74 6f 20 74 65 6c 6c 20 77 68 65 74  ble to tell whet
d590: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 27  her or not the '
d5a0: 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 66  merge' command f
d5b0: 6f 75 6e 64 20 61 6e 79 20 0a 62 2d 74 72 65 65  ound any .b-tree
d5c0: 73 20 74 6f 20 6d 65 72 67 65 20 74 6f 67 65 74  s to merge toget
d5d0: 68 65 72 20 62 79 20 63 68 65 63 6b 69 6e 67 20  her by checking 
d5e0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
d5f0: 65 64 20 62 79 20 74 68 65 0a 5b 73 71 6c 69 74  ed by the.[sqlit
d600: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
d610: 28 29 5d 20 41 50 49 20 62 65 66 6f 72 65 20 61  ()] API before a
d620: 6e 64 20 61 66 74 65 72 20 74 68 65 20 63 6f 6d  nd after the com
d630: 6d 61 6e 64 20 69 73 20 65 78 65 63 75 74 65 64  mand is executed
d640: 2e 20 49 66 0a 74 68 65 20 64 69 66 66 65 72 65  . If.the differe
d650: 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 20  nce between the 
d660: 74 77 6f 20 76 61 6c 75 65 73 20 69 73 20 32 20  two values is 2 
d670: 6f 72 20 67 72 65 61 74 65 72 2c 20 74 68 65 6e  or greater, then
d680: 20 77 6f 72 6b 20 77 61 73 20 70 65 72 66 6f 72   work was perfor
d690: 6d 65 64 2e 0a 49 66 20 74 68 65 20 64 69 66 66  med..If the diff
d6a0: 65 72 65 6e 63 65 20 69 73 20 6c 65 73 73 20 74  erence is less t
d6b0: 68 61 6e 20 32 2c 20 74 68 65 6e 20 74 68 65 20  han 2, then the 
d6c0: 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20  'merge' command 
d6d0: 77 61 73 20 61 20 6e 6f 2d 6f 70 2e 20 49 6e 20  was a no-op. In 
d6e0: 74 68 69 73 0a 63 61 73 65 20 74 68 65 72 65 20  this.case there 
d6f0: 69 73 20 6e 6f 20 72 65 61 73 6f 6e 20 74 6f 20  is no reason to 
d700: 65 78 65 63 75 74 65 20 74 68 65 20 73 61 6d 65  execute the same
d710: 20 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64   'merge' command
d720: 20 61 67 61 69 6e 2c 20 61 74 20 6c 65 61 73 74   again, at least
d730: 0a 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65  .until after the
d740: 20 46 54 53 20 74 61 62 6c 65 20 69 73 20 6e 65   FTS table is ne
d750: 78 74 20 75 70 64 61 74 65 64 2e 0a 0a 3c 70 3e  xt updated...<p>
d760: 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
d770: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  r is negative, a
d780: 6e 64 20 74 68 65 72 65 20 61 72 65 20 42 2d 74  nd there are B-t
d790: 72 65 65 20 73 74 72 75 63 74 75 72 65 73 20 6f  ree structures o
d7a0: 6e 20 6d 6f 72 65 20 74 68 61 6e 0a 6f 6e 65 20  n more than.one 
d7b0: 6c 65 76 65 6c 20 77 69 74 68 69 6e 20 74 68 65  level within the
d7c0: 20 46 54 53 20 69 6e 64 65 78 2c 20 61 6c 6c 20   FTS index, all 
d7d0: 42 2d 74 72 65 65 20 73 74 72 75 63 74 75 72 65  B-tree structure
d7e0: 73 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 74  s are assigned t
d7f0: 6f 20 74 68 65 20 73 61 6d 65 0a 6c 65 76 65 6c  o the same.level
d800: 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 72 67   before the merg
d810: 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 63  e operation is c
d820: 6f 6d 6d 65 6e 63 65 64 2e 20 41 64 64 69 74 69  ommenced. Additi
d830: 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
d840: 61 72 61 6d 65 74 65 72 0a 69 73 20 6e 65 67 61  arameter.is nega
d850: 74 69 76 65 2c 20 74 68 65 20 76 61 6c 75 65 20  tive, the value 
d860: 6f 66 20 74 68 65 20 75 73 65 72 6d 65 72 67 65  of the usermerge
d870: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d880: 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 0a 72 65  ption is not .re
d890: 73 70 65 63 74 65 64 20 2d 20 61 73 20 66 65 77  spected - as few
d8a0: 20 61 73 20 74 77 6f 20 62 2d 74 72 65 65 73 20   as two b-trees 
d8b0: 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 6c 65  from the same le
d8c0: 76 65 6c 20 6d 61 79 20 62 65 20 6d 65 72 67 65  vel may be merge
d8d0: 64 20 74 6f 67 65 74 68 65 72 2e 0a 0a 3c 70 3e  d together...<p>
d8e0: 20 54 68 65 20 61 62 6f 76 65 20 6d 65 61 6e 73   The above means
d8f0: 20 74 68 61 74 20 65 78 65 63 75 74 69 6e 67 20   that executing 
d900: 74 68 65 20 27 6d 65 72 67 65 27 20 63 6f 6d 6d  the 'merge' comm
d910: 61 6e 64 20 77 69 74 68 20 61 20 6e 65 67 61 74  and with a negat
d920: 69 76 65 0a 70 61 72 61 6d 65 74 65 72 20 75 6e  ive.parameter un
d930: 74 69 6c 20 74 68 65 20 62 65 66 6f 72 65 20 61  til the before a
d940: 6e 64 20 61 66 74 65 72 20 64 69 66 66 65 72 65  nd after differe
d950: 6e 63 65 20 69 6e 20 74 68 65 20 72 65 74 75 72  nce in the retur
d960: 6e 20 76 61 6c 75 65 20 6f 66 0a 5b 73 71 6c 69  n value of.[sqli
d970: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d980: 73 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61  s()] is less tha
d990: 6e 20 74 77 6f 20 6f 70 74 69 6d 69 7a 65 73 20  n two optimizes 
d9a0: 74 68 65 20 46 54 53 20 69 6e 64 65 78 20 69 6e  the FTS index in
d9b0: 20 74 68 65 0a 73 61 6d 65 20 77 61 79 20 61 73   the.same way as
d9c0: 20 74 68 65 20 5b 46 54 53 35 20 6f 70 74 69 6d   the [FTS5 optim
d9d0: 69 7a 65 20 63 6f 6d 6d 61 6e 64 5d 2e 20 48 6f  ize command]. Ho
d9e0: 77 65 76 65 72 2c 20 69 66 20 61 20 6e 65 77 20  wever, if a new 
d9f0: 62 2d 74 72 65 65 20 69 73 20 61 64 64 65 64 0a  b-tree is added.
da00: 74 6f 20 74 68 65 20 46 54 53 20 69 6e 64 65 78  to the FTS index
da10: 20 77 68 69 6c 65 20 74 68 69 73 20 70 72 6f 63   while this proc
da20: 65 73 73 20 69 73 20 6f 6e 67 6f 69 6e 67 2c 20  ess is ongoing, 
da30: 46 54 53 35 20 77 69 6c 6c 20 6d 6f 76 65 20 74  FTS5 will move t
da40: 68 65 20 6e 65 77 20 0a 62 2d 74 72 65 65 20 74  he new .b-tree t
da50: 6f 20 74 68 65 20 73 61 6d 65 20 6c 65 76 65 6c  o the same level
da60: 20 61 73 20 74 68 65 20 65 78 69 73 74 69 6e 67   as the existing
da70: 20 62 2d 74 72 65 65 73 20 61 6e 64 20 72 65 73   b-trees and res
da80: 74 61 72 74 20 74 68 65 20 6d 65 72 67 65 2e 20  tart the merge. 
da90: 54 6f 0a 61 76 6f 69 64 20 74 68 69 73 2c 20 6f  To.avoid this, o
daa0: 6e 6c 79 20 74 68 65 20 66 69 72 73 74 20 63 61  nly the first ca
dab0: 6c 6c 20 74 6f 20 27 6d 65 72 67 65 27 20 73 68  ll to 'merge' sh
dac0: 6f 75 6c 64 20 73 70 65 63 69 66 79 20 61 20 6e  ould specify a n
dad0: 65 67 61 74 69 76 65 20 70 61 72 61 6d 65 74 65  egative paramete
dae0: 72 2e 0a 45 61 63 68 20 73 75 62 73 65 71 75 65  r..Each subseque
daf0: 6e 74 20 63 61 6c 6c 20 74 6f 20 27 6d 65 72 67  nt call to 'merg
db00: 65 27 20 73 68 6f 75 6c 64 20 73 70 65 63 69 66  e' should specif
db10: 79 20 61 20 70 6f 73 74 69 76 65 20 76 61 6c 75  y a postive valu
db20: 65 20 73 6f 20 74 68 61 74 20 74 68 65 0a 6d 65  e so that the.me
db30: 72 67 65 20 73 74 61 72 74 65 64 20 62 79 20 74  rge started by t
db40: 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 69 73  he first call is
db50: 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
db60: 6f 6e 20 65 76 65 6e 20 69 66 20 6e 65 77 20 62  on even if new b
db70: 2d 74 72 65 65 73 20 61 72 65 0a 61 64 64 65 64  -trees are.added
db80: 20 74 6f 20 74 68 65 20 46 54 53 20 69 6e 64 65   to the FTS inde
db90: 78 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  x...<h2 tags="FT
dba0: 53 35 20 6f 70 74 69 6d 69 7a 65 20 63 6f 6d 6d  S5 optimize comm
dbb0: 61 6e 64 22 3e 54 68 65 20 27 6f 70 74 69 6d 69  and">The 'optimi
dbc0: 7a 65 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e  ze' Command</h2>
dbd0: 0a 0a 3c 70 3e 54 68 69 73 20 63 6f 6d 6d 61 6e  ..<p>This comman
dbe0: 64 20 6d 65 72 67 65 73 20 61 6c 6c 20 69 6e 64  d merges all ind
dbf0: 69 76 69 64 75 61 6c 20 62 2d 74 72 65 65 73 20  ividual b-trees 
dc00: 74 68 61 74 20 63 75 72 72 65 6e 74 6c 79 20 6d  that currently m
dc10: 61 6b 65 20 75 70 20 74 68 65 0a 66 75 6c 6c 2d  ake up the.full-
dc20: 74 65 78 74 20 69 6e 64 65 78 20 69 6e 74 6f 20  text index into 
dc30: 61 20 73 69 6e 67 6c 65 20 6c 61 72 67 65 20 62  a single large b
dc40: 2d 74 72 65 65 20 73 74 72 75 63 74 75 72 65 2e  -tree structure.
dc50: 20 54 68 69 73 20 65 6e 73 75 72 65 73 20 74 68   This ensures th
dc60: 61 74 20 74 68 65 0a 66 75 6c 6c 2d 74 65 78 74  at the.full-text
dc70: 20 69 6e 64 65 78 20 63 6f 6e 73 75 6d 65 73 20   index consumes 
dc80: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 73 70 61 63  the minimum spac
dc90: 65 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74  e within the dat
dca0: 61 62 61 73 65 20 61 6e 64 20 69 73 20 69 6e 20  abase and is in 
dcb0: 74 68 65 0a 66 61 73 74 65 73 74 20 66 6f 72 6d  the.fastest form
dcc0: 20 74 6f 20 71 75 65 72 79 2e 0a 0a 3c 70 3e 52   to query...<p>R
dcd0: 65 66 65 72 20 74 6f 20 74 68 65 20 64 6f 63 75  efer to the docu
dce0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68  mentation for th
dcf0: 65 20 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67  e [FTS5 automerg
dd00: 65 20 6f 70 74 69 6f 6e 5d 20 66 6f 72 20 6d 6f  e option] for mo
dd10: 72 65 20 64 65 74 61 69 6c 73 0a 72 65 67 61 72  re details.regar
dd20: 64 69 6e 67 20 74 68 65 20 72 65 6c 61 74 69 6f  ding the relatio
dd30: 6e 73 68 69 70 20 62 65 74 77 65 65 6e 20 74 68  nship between th
dd40: 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65  e full-text inde
dd50: 78 20 61 6e 64 20 69 74 73 20 63 6f 6d 70 6f 6e  x and its compon
dd60: 65 6e 74 0a 62 2d 74 72 65 65 73 2e 0a 0a 3c 63  ent.b-trees...<c
dd70: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45  odeblock>.  INSE
dd80: 52 54 20 49 4e 54 4f 20 66 74 28 66 74 29 20 56  RT INTO ft(ft) V
dd90: 41 4c 55 45 53 28 27 6f 70 74 69 6d 69 7a 65 27  ALUES('optimize'
dda0: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
ddb0: 0a 3c 70 3e 42 65 63 61 75 73 65 20 69 74 20 72  .<p>Because it r
ddc0: 65 6f 72 67 61 6e 69 7a 65 73 20 74 68 65 20 65  eorganizes the e
ddd0: 6e 74 69 72 65 20 46 54 53 20 69 6e 64 65 78 2c  ntire FTS index,
dde0: 20 74 68 65 20 6f 70 74 69 6d 69 7a 65 20 63 6f   the optimize co
ddf0: 6d 6d 61 6e 64 20 63 61 6e 20 0a 74 61 6b 65 20  mmand can .take 
de00: 61 20 6c 6f 6e 67 20 74 69 6d 65 20 74 6f 20 72  a long time to r
de10: 75 6e 2e 20 54 68 65 20 5b 46 54 53 35 20 6d 65  un. The [FTS5 me
de20: 72 67 65 20 63 6f 6d 6d 61 6e 64 5d 20 63 61 6e  rge command] can
de30: 20 62 65 20 75 73 65 64 20 74 6f 20 64 69 76 69   be used to divi
de40: 64 65 0a 74 68 65 20 77 6f 72 6b 20 6f 66 20 6f  de.the work of o
de50: 70 74 69 6d 69 7a 69 6e 67 20 74 68 65 20 46 54  ptimizing the FT
de60: 53 20 69 6e 64 65 78 20 69 6e 74 6f 20 6d 75 6c  S index into mul
de70: 74 69 70 6c 65 20 73 74 65 70 73 2e 20 54 6f 20  tiple steps. To 
de80: 64 6f 20 74 68 69 73 3a 0a 0a 3c 75 6c 3e 0a 20  do this:..<ul>. 
de90: 20 3c 6c 69 3e 20 49 6e 76 6f 6b 65 20 74 68 65   <li> Invoke the
dea0: 20 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64   'merge' command
deb0: 20 6f 6e 63 65 20 77 69 74 68 20 74 68 65 20 70   once with the p
dec0: 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
ded0: 2d 4e 2c 20 74 68 65 6e 0a 20 20 3c 6c 69 3e 20  -N, then.  <li> 
dee0: 49 6e 76 6f 6b 65 20 74 68 65 20 27 6d 65 72 67  Invoke the 'merg
def0: 65 27 20 63 6f 6d 6d 61 6e 64 20 7a 65 72 6f 20  e' command zero 
df00: 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 77 69  or more times wi
df10: 74 68 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  th the parameter
df20: 20 73 65 74 20 74 6f 20 4e 2e 0a 3c 2f 75 6c 3e   set to N..</ul>
df30: 0a 0a 3c 70 3e 77 68 65 72 65 20 4e 20 69 73 20  ..<p>where N is 
df40: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
df50: 67 65 73 20 6f 66 20 64 61 74 61 20 74 6f 20 6d  ges of data to m
df60: 65 72 67 65 20 77 69 74 68 69 6e 20 65 61 63 68  erge within each
df70: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 74   invocation of.t
df80: 68 65 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64  he merge command
df90: 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
dfa0: 6e 20 73 68 6f 75 6c 64 20 73 74 6f 70 20 69 6e  n should stop in
dfb0: 76 6f 6b 69 6e 67 20 6d 65 72 67 65 20 77 68 65  voking merge whe
dfc0: 6e 20 74 68 65 0a 64 69 66 66 65 72 65 6e 63 65  n the.difference
dfd0: 20 69 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65   in the value re
dfe0: 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 71  turned by the sq
dff0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
e000: 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 62  ges() function b
e010: 65 66 6f 72 65 0a 61 6e 64 20 61 66 74 65 72 20  efore.and after 
e020: 74 68 65 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e  the merge comman
e030: 64 20 64 72 6f 70 73 20 74 6f 20 62 65 6c 6f 77  d drops to below
e040: 20 74 77 6f 2e 20 54 68 65 20 6d 65 72 67 65 20   two. The merge 
e050: 63 6f 6d 6d 61 6e 64 73 20 6d 61 79 20 62 65 0a  commands may be.
e060: 69 73 73 75 65 64 20 61 73 20 70 61 72 74 20 6f  issued as part o
e070: 66 20 74 68 65 20 73 61 6d 65 20 6f 72 20 73 65  f the same or se
e080: 70 61 72 61 74 65 20 74 72 61 6e 73 61 63 74 69  parate transacti
e090: 6f 6e 73 2c 20 61 6e 64 20 62 79 20 74 68 65 20  ons, and by the 
e0a0: 73 61 6d 65 20 6f 72 0a 64 69 66 66 65 72 65 6e  same or.differen
e0b0: 74 20 64 61 74 61 62 61 73 65 20 63 6c 69 65 6e  t database clien
e0c0: 74 73 2e 20 52 65 66 65 72 20 74 6f 20 74 68 65  ts. Refer to the
e0d0: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
e0e0: 6f 72 20 74 68 65 20 5b 46 54 53 35 20 6d 65 72  or the [FTS5 mer
e0f0: 67 65 0a 63 6f 6d 6d 61 6e 64 20 7c 20 6d 65 72  ge.command | mer
e100: 67 65 20 63 6f 6d 6d 61 6e 64 5d 20 66 6f 72 20  ge command] for 
e110: 66 75 72 74 68 65 72 20 64 65 74 61 69 6c 73 2e  further details.
e120: 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35  ..<h2 tags="FTS5
e130: 20 70 67 73 7a 20 6f 70 74 69 6f 6e 22 3e 54 68   pgsz option">Th
e140: 65 20 27 70 67 73 7a 27 20 43 6f 6e 66 69 67 75  e 'pgsz' Configu
e150: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68  ration Option</h
e160: 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d  2>..<p> This com
e170: 6d 61 6e 64 20 69 73 20 75 73 65 64 20 74 6f 20  mand is used to 
e180: 73 65 74 20 74 68 65 20 70 65 72 73 69 73 74 65  set the persiste
e190: 6e 74 20 22 70 67 73 7a 22 20 6f 70 74 69 6f 6e  nt "pgsz" option
e1a0: 2e 0a 0a 3c 70 3e 20 54 68 65 20 66 75 6c 6c 2d  ...<p> The full-
e1b0: 74 65 78 74 20 69 6e 64 65 78 20 6d 61 69 6e 74  text index maint
e1c0: 61 69 6e 65 64 20 62 79 20 46 54 53 35 20 69 73  ained by FTS5 is
e1d0: 20 73 74 6f 72 65 64 20 61 73 20 61 20 73 65 72   stored as a ser
e1e0: 69 65 73 20 6f 66 20 66 69 78 65 64 2d 73 69 7a  ies of fixed-siz
e1f0: 65 0a 62 6c 6f 62 73 20 69 6e 20 61 20 64 61 74  e.blobs in a dat
e200: 61 62 61 73 65 20 74 61 62 6c 65 2e 20 49 74 20  abase table. It 
e210: 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
e220: 6e 65 63 65 73 73 61 72 79 20 66 6f 72 20 61 6c  necessary for al
e230: 6c 20 62 6c 6f 62 73 20 74 68 61 74 20 6d 61 6b  l blobs that mak
e240: 65 0a 75 70 20 61 20 66 75 6c 6c 2d 74 65 78 74  e.up a full-text
e250: 20 69 6e 64 65 78 20 74 6f 20 62 65 20 74 68 65   index to be the
e260: 20 73 61 6d 65 20 73 69 7a 65 2e 20 54 68 65 20   same size. The 
e270: 70 67 73 7a 20 6f 70 74 69 6f 6e 20 64 65 74 65  pgsz option dete
e280: 72 6d 69 6e 65 73 20 74 68 65 20 73 69 7a 65 0a  rmines the size.
e290: 6f 66 20 61 6c 6c 20 62 6c 6f 62 73 20 63 72 65  of all blobs cre
e2a0: 61 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65  ated by subseque
e2b0: 6e 74 20 69 6e 64 65 78 20 77 72 69 74 65 72 73  nt index writers
e2c0: 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
e2d0: 6c 75 65 20 69 73 20 31 30 30 30 2e 0a 0a 3c 63  lue is 1000...<c
e2e0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45  odeblock>.  INSE
e2f0: 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c 20 72  RT INTO ft(ft, r
e300: 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 70 67 73  ank) VALUES('pgs
e310: 7a 27 2c 20 34 30 37 32 29 3b 0a 3c 2f 63 6f 64  z', 4072);.</cod
e320: 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67  eblock>..<h2 tag
e330: 73 3d 22 46 54 53 35 20 72 61 6e 6b 20 63 6f 6e  s="FTS5 rank con
e340: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e350: 6e 22 3e 54 68 65 20 27 72 61 6e 6b 27 20 43 6f  n">The 'rank' Co
e360: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
e370: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69  on</h2>..<p> Thi
e380: 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65  s command is use
e390: 64 20 74 6f 20 73 65 74 20 74 68 65 20 70 65 72  d to set the per
e3a0: 73 69 73 74 65 6e 74 20 22 72 61 6e 6b 22 20 6f  sistent "rank" o
e3b0: 70 74 69 6f 6e 2e 0a 0a 3c 70 3e 20 54 68 65 20  ption...<p> The 
e3c0: 72 61 6e 6b 20 6f 70 74 69 6f 6e 20 69 73 20 75  rank option is u
e3d0: 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
e3e0: 65 20 64 65 66 61 75 6c 74 20 61 75 78 69 6c 69  e default auxili
e3f0: 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 70  ary function map
e400: 70 69 6e 67 0a 66 6f 72 20 74 68 65 20 72 61 6e  ping.for the ran
e410: 6b 20 63 6f 6c 75 6d 6e 2e 20 54 68 65 20 6f 70  k column. The op
e420: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 73  tion should be s
e430: 65 74 20 74 6f 20 61 20 74 65 78 74 20 76 61 6c  et to a text val
e440: 75 65 20 69 6e 20 74 68 65 20 73 61 6d 65 0a 66  ue in the same.f
e450: 6f 72 6d 61 74 20 61 73 20 64 65 73 63 72 69 62  ormat as describ
e460: 65 64 20 66 6f 72 20 5b 61 75 78 69 6c 69 61 72  ed for [auxiliar
e470: 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 70 70 69  y function mappi
e480: 6e 67 20 7c 20 22 72 61 6e 6b 20 4d 41 54 43 48  ng | "rank MATCH
e490: 20 3f 22 5d 20 74 65 72 6d 73 20 0a 61 62 6f 76   ?"] terms .abov
e4a0: 65 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a  e. For example:.
e4b0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49  .<codeblock>.  I
e4c0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74  NSERT INTO ft(ft
e4d0: 2c 20 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27  , rank) VALUES('
e4e0: 72 61 6e 6b 27 2c 20 27 62 6d 32 35 28 31 30 2e  rank', 'bm25(10.
e4f0: 30 2c 20 35 2e 30 29 27 29 3b 0a 3c 2f 63 6f 64  0, 5.0)');.</cod
e500: 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67  eblock>..<h2 tag
e510: 73 3d 22 46 54 53 35 20 72 65 62 75 69 6c 64 20  s="FTS5 rebuild 
e520: 63 6f 6d 6d 61 6e 64 22 3e 54 68 65 20 27 72 65  command">The 're
e530: 62 75 69 6c 64 27 20 43 6f 6d 6d 61 6e 64 3c 2f  build' Command</
e540: 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f  h2>..<p> This co
e550: 6d 6d 61 6e 64 20 66 69 72 73 74 20 64 65 6c 65  mmand first dele
e560: 74 65 73 20 74 68 65 20 65 6e 74 69 72 65 20 66  tes the entire f
e570: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2c 20  ull-text index, 
e580: 74 68 65 6e 20 72 65 62 75 69 6c 64 73 20 69 74  then rebuilds it
e590: 0a 62 61 73 65 64 20 6f 6e 20 74 68 65 20 63 6f  .based on the co
e5a0: 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 74 61  ntents of the ta
e5b0: 62 6c 65 20 6f 72 20 5b 46 54 53 35 20 65 78 74  ble or [FTS5 ext
e5c0: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61  ernal content ta
e5d0: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 0a 74  bles | content.t
e5e0: 61 62 6c 65 5d 2e 20 20 49 74 20 69 73 20 6e 6f  able].  It is no
e5f0: 74 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68  t available with
e600: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
e610: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
e620: 65 6e 74 6c 65 73 73 0a 74 61 62 6c 65 73 5d 2e  entless.tables].
e630: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
e640: 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66  INSERT INTO ft(f
e650: 74 29 20 56 41 4c 55 45 53 28 27 72 65 62 75 69  t) VALUES('rebui
e660: 6c 64 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ld');.</codebloc
e670: 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  k>..<h2 tags="FT
e680: 53 35 20 75 73 65 72 6d 65 72 67 65 20 6f 70 74  S5 usermerge opt
e690: 69 6f 6e 22 3e 54 68 65 20 27 75 73 65 72 6d 65  ion">The 'userme
e6a0: 72 67 65 27 20 43 6f 6e 66 69 67 75 72 61 74 69  rge' Configurati
e6b0: 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a  on Option</h2>..
e6c0: 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64  <p> This command
e6d0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
e6e0: 74 68 65 20 70 65 72 73 69 73 74 65 6e 74 20 22  the persistent "
e6f0: 75 73 65 72 6d 65 72 67 65 22 20 6f 70 74 69 6f  usermerge" optio
e700: 6e 2e 0a 0a 3c 70 3e 20 54 68 65 20 75 73 65 72  n...<p> The user
e710: 6d 65 72 67 65 20 6f 70 74 69 6f 6e 20 69 73 20  merge option is 
e720: 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 20 61  similar to the a
e730: 75 74 6f 6d 65 72 67 65 20 61 6e 64 20 63 72 69  utomerge and cri
e740: 73 69 73 6d 65 72 67 65 20 6f 70 74 69 6f 6e 73  sismerge options
e750: 2e 0a 49 74 20 69 73 20 74 68 65 20 6d 69 6e 69  ..It is the mini
e760: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 2d  mum number of b-
e770: 74 72 65 65 20 73 65 67 6d 65 6e 74 73 20 74 68  tree segments th
e780: 61 74 20 77 69 6c 6c 20 62 65 20 6d 65 72 67 65  at will be merge
e790: 64 20 74 6f 67 65 74 68 65 72 20 62 79 0a 61 20  d together by.a 
e7a0: 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20  'merge' command 
e7b0: 77 69 74 68 20 61 20 70 6f 73 69 74 69 76 65 20  with a positive 
e7c0: 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 65  parameter. For e
e7d0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
e7e0: 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e  ock>.  INSERT IN
e7f0: 54 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b 29 20  TO ft(ft, rank) 
e800: 56 41 4c 55 45 53 28 27 75 73 65 72 6d 65 72 67  VALUES('usermerg
e810: 65 27 2c 20 34 29 3b 0a 3c 2f 63 6f 64 65 62 6c  e', 4);.</codebl
e820: 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 64 65  ock>..<p> The de
e830: 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74  fault value of t
e840: 68 65 20 75 73 65 72 6d 65 72 67 65 20 6f 70 74  he usermerge opt
e850: 69 6f 6e 20 69 73 20 34 2e 20 54 68 65 20 6d 69  ion is 4. The mi
e860: 6e 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 76 61  nimum allowed va
e870: 6c 75 65 0a 69 73 20 32 2c 20 61 6e 64 20 74 68  lue.is 2, and th
e880: 65 20 6d 61 78 69 6d 75 6d 20 31 36 2e 0a 0a 3c  e maximum 16...<
e890: 68 31 20 74 61 67 73 3d 22 45 78 74 65 6e 64 69  h1 tags="Extendi
e8a0: 6e 67 20 46 54 53 35 22 3e 45 78 74 65 6e 64 69  ng FTS5">Extendi
e8b0: 6e 67 20 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 70  ng FTS5</h1>..<p
e8c0: 3e 46 54 53 35 20 66 65 61 74 75 72 65 73 20 41  >FTS5 features A
e8d0: 50 49 73 20 61 6c 6c 6f 77 69 6e 67 20 69 74 20  PIs allowing it 
e8e0: 74 6f 20 62 65 20 65 78 74 65 6e 64 65 64 20 62  to be extended b
e8f0: 79 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20  y:..<ul>.  <li> 
e900: 41 64 64 69 6e 67 20 6e 65 77 20 61 75 78 69 6c  Adding new auxil
e910: 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 69  iary functions i
e920: 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 2c  mplemented in C,
e930: 20 61 6e 64 0a 20 20 3c 6c 69 3e 20 41 64 64 69   and.  <li> Addi
e940: 6e 67 20 6e 65 77 20 74 6f 6b 65 6e 69 7a 65 72  ng new tokenizer
e950: 73 2c 20 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e  s, also implemen
e960: 74 65 64 20 69 6e 20 43 2e 0a 3c 2f 75 6c 3e 0a  ted in C..</ul>.
e970: 0a 3c 70 3e 20 54 68 65 20 62 75 69 6c 74 2d 69  .<p> The built-i
e980: 6e 20 74 6f 6b 65 6e 69 7a 65 72 73 20 61 6e 64  n tokenizers and
e990: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
e9a0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 69  ions described i
e9b0: 6e 20 74 68 69 73 0a 64 6f 63 75 6d 65 6e 74 20  n this.document 
e9c0: 61 72 65 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  are all implemen
e9d0: 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 70 75  ted using the pu
e9e0: 62 6c 69 63 6c 79 20 61 76 61 69 6c 61 62 6c 65  blicly available
e9f0: 20 41 50 49 20 64 65 73 63 72 69 62 65 64 0a 62   API described.b
ea00: 65 6c 6f 77 2e 0a 0a 3c 70 3e 20 42 65 66 6f 72  elow...<p> Befor
ea10: 65 20 61 20 6e 65 77 20 61 75 78 69 6c 69 61 72  e a new auxiliar
ea20: 79 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 74 6f  y function or to
ea30: 6b 65 6e 69 7a 65 72 20 69 6d 70 6c 65 6d 65 6e  kenizer implemen
ea40: 74 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 0a 72  tation may be .r
ea50: 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 46  egistered with F
ea60: 54 53 35 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  TS5, an applicat
ea70: 69 6f 6e 20 6d 75 73 74 20 6f 62 74 61 69 6e 20  ion must obtain 
ea80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ea90: 20 22 66 74 73 35 5f 61 70 69 22 0a 73 74 72 75   "fts5_api".stru
eaa0: 63 74 75 72 65 2e 20 54 68 65 72 65 20 69 73 20  cture. There is 
eab0: 6f 6e 65 20 66 74 73 35 5f 61 70 69 20 73 74 72  one fts5_api str
eac0: 75 63 74 75 72 65 20 66 6f 72 20 65 61 63 68 20  ucture for each 
ead0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
eae0: 69 6f 6e 20 77 69 74 68 0a 77 68 69 63 68 20 74  ion with.which t
eaf0: 68 65 20 46 54 53 35 20 65 78 74 65 6e 73 69 6f  he FTS5 extensio
eb00: 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 2e  n is registered.
eb10: 20 54 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 70   To obtain the p
eb20: 6f 69 6e 74 65 72 2c 20 74 68 65 20 61 70 70 6c  ointer, the appl
eb30: 69 63 61 74 69 6f 6e 0a 69 6e 76 6f 6b 65 73 20  ication.invokes 
eb40: 74 68 65 20 53 51 4c 20 75 73 65 72 2d 64 65 66  the SQL user-def
eb50: 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 66 74  ined function ft
eb60: 73 35 28 29 2c 20 77 68 69 63 68 20 72 65 74 75  s5(), which retu
eb70: 72 6e 73 20 61 20 62 6c 6f 62 20 76 61 6c 75 65  rns a blob value
eb80: 0a 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20  .containing the 
eb90: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
eba0: 74 73 35 5f 61 70 69 20 73 74 72 75 63 74 75 72  ts5_api structur
ebb0: 65 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  e for the connec
ebc0: 74 69 6f 6e 2e 20 54 68 65 0a 66 6f 6c 6c 6f 77  tion. The.follow
ebd0: 69 6e 67 20 65 78 61 6d 70 6c 65 20 63 6f 64 65  ing example code
ebe0: 20 64 65 6d 6f 6e 73 74 72 61 74 65 73 20 74 68   demonstrates th
ebf0: 65 20 74 65 63 68 6e 69 71 75 65 3a 0a 0a 3c 63  e technique:..<c
ec00: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2f  odeblock>.  <i>/
ec10: 2a 0a 20 20 2a 2a 20 52 65 74 75 72 6e 20 61 20  *.  ** Return a 
ec20: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
ec30: 74 73 35 5f 61 70 69 20 70 6f 69 6e 74 65 72 20  ts5_api pointer 
ec40: 66 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  for database con
ec50: 6e 65 63 74 69 6f 6e 20 64 62 2e 0a 20 20 2a 2a  nection db..  **
ec60: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
ec70: 75 72 73 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c  urs, return NULL
ec80: 20 61 6e 64 20 6c 65 61 76 65 20 61 6e 20 65 72   and leave an er
ec90: 72 6f 72 20 69 6e 20 74 68 65 20 64 61 74 61 62  ror in the datab
eca0: 61 73 65 20 0a 20 20 2a 2a 20 68 61 6e 64 6c 65  ase .  ** handle
ecb0: 20 28 61 63 63 65 73 73 69 62 6c 65 20 75 73 69   (accessible usi
ecc0: 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ng sqlite3_errco
ecd0: 64 65 28 29 2f 65 72 72 6d 73 67 28 29 29 2e 0a  de()/errmsg())..
ece0: 20 20 2a 2f 3c 2f 69 3e 0a 20 20 66 74 73 35 5f    */</i>.  fts5_
ecf0: 61 70 69 20 2a 66 74 73 35 5f 61 70 69 5f 66 72  api *fts5_api_fr
ed00: 6f 6d 5f 64 62 28 73 71 6c 69 74 65 33 20 2a 64  om_db(sqlite3 *d
ed10: 62 29 7b 0a 20 20 20 20 66 74 73 35 5f 61 70 69  b){.    fts5_api
ed20: 20 2a 70 52 65 74 20 3d 20 30 3b 0a 20 20 20 20   *pRet = 0;.    
ed30: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
ed40: 74 6d 74 20 3d 20 30 3b 0a 0a 20 20 20 20 69 66  tmt = 0;..    if
ed50: 28 20 53 51 4c 49 54 45 5f 4f 4b 3d 3d 73 71 6c  ( SQLITE_OK==sql
ed60: 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
ed70: 20 22 53 45 4c 45 43 54 20 66 74 73 35 28 29 22   "SELECT fts5()"
ed80: 2c 20 2d 31 2c 20 26 70 53 74 6d 74 2c 20 30 29  , -1, &pStmt, 0)
ed90: 0a 20 20 20 20 20 26 26 20 53 51 4c 49 54 45 5f  .     && SQLITE_
eda0: 52 4f 57 3d 3d 73 71 6c 69 74 65 33 5f 73 74 65  ROW==sqlite3_ste
edb0: 70 28 70 53 74 6d 74 29 20 0a 20 20 20 20 20 26  p(pStmt) .     &
edc0: 26 20 73 69 7a 65 6f 66 28 70 52 65 74 29 3d 3d  & sizeof(pRet)==
edd0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
ede0: 79 74 65 73 28 70 53 74 6d 74 2c 20 30 29 0a 20  ytes(pStmt, 0). 
edf0: 20 20 20 29 7b 0a 20 20 20 20 20 20 6d 65 6d 63     ){.      memc
ee00: 70 79 28 26 70 52 65 74 2c 20 73 71 6c 69 74 65  py(&pRet, sqlite
ee10: 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 70 53  3_column_blob(pS
ee20: 74 6d 74 2c 20 30 29 2c 20 73 69 7a 65 6f 66 28  tmt, 0), sizeof(
ee30: 70 52 65 74 29 29 3b 0a 20 20 20 20 7d 0a 20 20  pRet));.    }.  
ee40: 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69    sqlite3_finali
ee50: 7a 65 28 70 53 74 6d 74 29 3b 0a 20 20 20 20 72  ze(pStmt);.    r
ee60: 65 74 75 72 6e 20 70 52 65 74 3b 0a 20 20 7d 0a  eturn pRet;.  }.
ee70: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
ee80: 3e 20 54 68 65 20 66 74 73 35 5f 61 70 69 20 73  > The fts5_api s
ee90: 74 72 75 63 74 75 72 65 20 69 73 20 64 65 66 69  tructure is defi
eea0: 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 2e 20  ned as follows. 
eeb0: 49 74 20 65 78 70 6f 73 65 73 20 74 68 72 65 65  It exposes three
eec0: 20 6d 65 74 68 6f 64 73 2c 20 0a 6f 6e 65 20 65   methods, .one e
eed0: 61 63 68 20 66 6f 72 20 72 65 67 69 73 74 65 72  ach for register
eee0: 69 6e 67 20 6e 65 77 20 61 75 78 69 6c 69 61 72  ing new auxiliar
eef0: 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  y functions and 
ef00: 74 6f 6b 65 6e 69 7a 65 72 73 2c 20 61 6e 64 20  tokenizers, and 
ef10: 6f 6e 65 20 66 6f 72 0a 72 65 74 72 69 65 76 69  one for.retrievi
ef20: 6e 67 20 65 78 69 73 74 69 6e 67 20 74 6f 6b 65  ng existing toke
ef30: 6e 69 7a 65 72 2e 20 54 68 65 20 6c 61 74 74 65  nizer. The latte
ef40: 72 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  r is intended to
ef50: 20 66 61 63 69 6c 69 74 61 74 65 20 74 68 65 0a   facilitate the.
ef60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
ef70: 66 20 22 74 6f 6b 65 6e 69 7a 65 72 20 77 72 61  f "tokenizer wra
ef80: 70 70 65 72 73 22 20 73 69 6d 69 6c 61 72 20 74  ppers" similar t
ef90: 6f 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 70  o the built-in.p
efa0: 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72 2e  orter tokenizer.
efb0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 3c 74  ..<codeblock>.<t
efc0: 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74 20  clscript>.  set 
efd0: 72 65 73 20 22 22 0a 20 20 73 65 74 20 3a 3a 65  res "".  set ::e
efe0: 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f  xtract_api_docs_
eff0: 6d 6f 64 65 20 66 74 73 35 5f 61 70 69 0a 20 20  mode fts5_api.  
f000: 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20  catch { set res 
f010: 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f  [source [file jo
f020: 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74  in $::SRC ext/ft
f030: 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64  s5/extract_api_d
f040: 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65  ocs.tcl]] }.  se
f050: 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70  t res.</tclscrip
f060: 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t>.</codeblock>.
f070: 0a 3c 70 3e 20 54 6f 20 69 6e 76 6f 6b 65 20 61  .<p> To invoke a
f080: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 66   method of the f
f090: 74 73 35 5f 61 70 69 20 6f 62 6a 65 63 74 2c 20  ts5_api object, 
f0a0: 74 68 65 20 66 74 73 35 5f 61 70 69 20 70 6f 69  the fts5_api poi
f0b0: 6e 74 65 72 20 69 74 73 65 6c 66 0a 73 68 6f 75  nter itself.shou
f0c0: 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
f0d0: 74 68 65 20 6d 65 74 68 6f 64 73 20 66 69 72 73  the methods firs
f0e0: 74 20 61 72 67 75 6d 65 6e 74 20 66 6f 6c 6c 6f  t argument follo
f0f0: 77 65 64 20 62 79 20 74 68 65 20 6f 74 68 65 72  wed by the other
f100: 2c 20 6d 65 74 68 6f 64 0a 73 70 65 63 69 66 69  , method.specifi
f110: 63 2c 20 61 72 67 75 6d 65 6e 74 73 2e 20 46 6f  c, arguments. Fo
f120: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
f130: 65 62 6c 6f 63 6b 3e 0a 20 20 20 20 72 63 20 3d  eblock>.    rc =
f140: 20 70 46 74 73 35 41 70 69 2d 3e 78 43 72 65 61   pFts5Api->xCrea
f150: 74 65 54 6f 6b 65 6e 69 7a 65 72 28 70 46 74 73  teTokenizer(pFts
f160: 35 41 70 69 2c 20 2e 2e 2e 20 6f 74 68 65 72 20  5Api, ... other 
f170: 61 72 67 73 20 2e 2e 2e 29 3b 0a 3c 2f 63 6f 64  args ...);.</cod
f180: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65  eblock>..<p> The
f190: 20 66 74 73 35 5f 61 70 69 20 73 74 72 75 63 74   fts5_api struct
f1a0: 75 72 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  ure methods are 
f1b0: 64 65 73 63 72 69 62 65 64 20 69 6e 64 69 76 69  described indivi
f1c0: 64 75 61 6c 6c 79 20 69 6e 20 74 68 65 20 66 6f  dually in the fo
f1d0: 6c 6c 6f 77 69 6e 67 0a 73 65 63 74 69 6f 6e 73  llowing.sections
f1e0: 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 63 75 73  ...<h2 tags="cus
f1f0: 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 73 22 3e  tom tokenizers">
f200: 43 75 73 74 6f 6d 20 54 6f 6b 65 6e 69 7a 65 72  Custom Tokenizer
f210: 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 6f 20 63  s</h2>..<p> To c
f220: 72 65 61 74 65 20 61 20 63 75 73 74 6f 6d 20 74  reate a custom t
f230: 6f 6b 65 6e 69 7a 65 72 2c 20 61 6e 20 61 70 70  okenizer, an app
f240: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6d  lication must im
f250: 70 6c 65 6d 65 6e 74 20 74 68 72 65 65 0a 66 75  plement three.fu
f260: 6e 63 74 69 6f 6e 73 3a 20 61 20 74 6f 6b 65 6e  nctions: a token
f270: 69 7a 65 72 20 63 6f 6e 73 74 72 75 63 74 6f 72  izer constructor
f280: 20 28 78 43 72 65 61 74 65 29 2c 20 61 20 64 65   (xCreate), a de
f290: 73 74 72 75 63 74 6f 72 20 28 78 44 65 6c 65 74  structor (xDelet
f2a0: 65 29 20 61 6e 64 20 61 0a 66 75 6e 63 74 69 6f  e) and a.functio
f2b0: 6e 20 74 6f 20 64 6f 20 74 68 65 20 61 63 74 75  n to do the actu
f2c0: 61 6c 20 74 6f 6b 65 6e 69 7a 61 74 69 6f 6e 20  al tokenization 
f2d0: 28 78 54 6f 6b 65 6e 69 7a 65 29 2e 20 54 68 65  (xTokenize). The
f2e0: 20 74 79 70 65 20 6f 66 20 65 61 63 68 0a 66 75   type of each.fu
f2f0: 6e 63 74 69 6f 6e 20 69 73 20 61 73 20 66 6f 72  nction is as for
f300: 20 74 68 65 20 6d 65 6d 62 65 72 20 76 61 72 69   the member vari
f310: 61 62 6c 65 73 20 6f 66 20 74 68 65 20 66 74 73  ables of the fts
f320: 35 5f 74 6f 6b 65 6e 69 7a 65 72 20 73 74 72 75  5_tokenizer stru
f330: 63 74 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  ct:..<codeblock>
f340: 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73  .<tclscript>.  s
f350: 65 74 20 72 65 73 20 22 22 0a 20 20 73 65 74 20  et res "".  set 
f360: 3a 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f  ::extract_api_do
f370: 63 73 5f 6d 6f 64 65 20 66 74 73 35 5f 74 6f 6b  cs_mode fts5_tok
f380: 65 6e 69 7a 65 72 0a 20 20 63 61 74 63 68 20 7b  enizer.  catch {
f390: 20 73 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65   set res [source
f3a0: 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53   [file join $::S
f3b0: 52 43 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72  RC ext/fts5/extr
f3c0: 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c  act_api_docs.tcl
f3d0: 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c  ]] }.  set res.<
f3e0: 2f 74 63 6c 73 63 72 69 70 74 3e 0a 3c 2f 63 6f  /tclscript>.</co
f3f0: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 57 68  deblock>..<p> Wh
f400: 65 6e 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65  en an FTS5 table
f410: 20 75 73 65 73 20 74 68 65 20 63 75 73 74 6f 6d   uses the custom
f420: 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 74 68 65 20   tokenizer, the 
f430: 46 54 53 35 20 63 6f 72 65 20 63 61 6c 6c 73 20  FTS5 core calls 
f440: 78 43 72 65 61 74 65 28 29 0a 6f 6e 63 65 20 74  xCreate().once t
f450: 6f 20 63 72 65 61 74 65 20 61 20 74 6f 6b 65 6e  o create a token
f460: 69 7a 65 72 2c 20 74 68 65 6e 20 78 54 6f 6b 65  izer, then xToke
f470: 6e 69 7a 65 28 29 20 7a 65 72 6f 20 6f 72 20 6d  nize() zero or m
f480: 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 74 6f 6b  ore times to tok
f490: 65 6e 69 7a 65 0a 73 74 72 69 6e 67 73 2c 20 74  enize.strings, t
f4a0: 68 65 6e 20 78 44 65 6c 65 74 65 28 29 20 74 6f  hen xDelete() to
f4b0: 20 66 72 65 65 20 61 6e 79 20 72 65 73 6f 75 72   free any resour
f4c0: 63 65 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ces allocated by
f4d0: 20 78 43 72 65 61 74 65 28 29 2e 20 4d 6f 72 65   xCreate(). More
f4e0: 0a 73 70 65 63 69 66 69 63 61 6c 6c 79 3a 0a 0a  .specifically:..
f4f0: 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65  <tclscript>.  se
f500: 74 20 72 65 73 20 22 22 0a 20 20 73 65 74 20 3a  t res "".  set :
f510: 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63  :extract_api_doc
f520: 73 5f 6d 6f 64 65 20 74 6f 6b 65 6e 69 7a 65 72  s_mode tokenizer
f530: 5f 61 70 69 0a 20 20 63 61 74 63 68 20 7b 20 73  _api.  catch { s
f540: 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65 20 5b  et res [source [
f550: 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43  file join $::SRC
f560: 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72 61 63   ext/fts5/extrac
f570: 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d  t_api_docs.tcl]]
f580: 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f 74   }.  set res.</t
f590: 63 6c 73 63 72 69 70 74 3e 0a 0a 3c 68 32 20 74  clscript>..<h2 t
f5a0: 61 67 73 3d 22 46 54 53 35 20 63 75 73 74 6f 6d  ags="FTS5 custom
f5b0: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
f5c0: 69 6f 6e 73 22 3e 43 75 73 74 6f 6d 20 41 75 78  ions">Custom Aux
f5d0: 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f 6e 73  iliary Functions
f5e0: 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 49 6d 70 6c 65  </h2>..<p> Imple
f5f0: 6d 65 6e 74 69 6e 67 20 61 20 63 75 73 74 6f 6d  menting a custom
f600: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
f610: 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ion is similar t
f620: 6f 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61  o implementing a
f630: 0a 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  .[application-de
f640: 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
f650: 6f 6e 20 7c 20 73 63 61 6c 61 72 20 53 51 4c 20  on | scalar SQL 
f660: 66 75 6e 63 74 69 6f 6e 5d 2e 20 54 68 65 20 69  function]. The i
f670: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 73 68  mplementation.sh
f680: 6f 75 6c 64 20 62 65 20 61 20 43 20 66 75 6e 63  ould be a C func
f690: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 66 74 73  tion of type fts
f6a0: 35 5f 65 78 74 65 6e 73 69 6f 6e 5f 66 75 6e 63  5_extension_func
f6b0: 74 69 6f 6e 2c 20 64 65 66 69 6e 65 64 20 61 73  tion, defined as
f6c0: 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65   follows:..<code
f6d0: 62 6c 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72 69 70  block>.<tclscrip
f6e0: 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22 22 0a  t>.  set res "".
f6f0: 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63 74 5f    set ::extract_
f700: 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 66 74  api_docs_mode ft
f710: 73 35 5f 65 78 74 65 6e 73 69 6f 6e 0a 20 20 63  s5_extension.  c
f720: 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20 5b  atch { set res [
f730: 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69  source [file joi
f740: 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74 73  n $::SRC ext/fts
f750: 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f  5/extract_api_do
f760: 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74  cs.tcl]] }.  set
f770: 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74   res.</tclscript
f780: 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  >.</codeblock>..
f790: 3c 70 3e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  <p> The implemen
f7a0: 74 61 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  tation is regist
f7b0: 65 72 65 64 20 77 69 74 68 20 74 68 65 20 46 54  ered with the FT
f7c0: 53 35 20 6d 6f 64 75 6c 65 20 62 79 20 63 61 6c  S5 module by cal
f7d0: 6c 69 6e 67 20 74 68 65 0a 78 43 72 65 61 74 65  ling the.xCreate
f7e0: 46 75 6e 63 74 69 6f 6e 28 29 20 6d 65 74 68 6f  Function() metho
f7f0: 64 20 6f 66 20 74 68 65 20 66 74 73 35 5f 61 70  d of the fts5_ap
f800: 69 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  i object. If the
f810: 72 65 20 69 73 20 61 6c 72 65 61 64 79 20 61 6e  re is already an
f820: 0a 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74  .auxiliary funct
f830: 69 6f 6e 20 77 69 74 68 20 74 68 65 20 73 61 6d  ion with the sam
f840: 65 20 6e 61 6d 65 2c 20 69 74 20 69 73 20 72 65  e name, it is re
f850: 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 6e 65  placed by the ne
f860: 77 20 66 75 6e 63 74 69 6f 6e 2e 0a 49 66 20 61  w function..If a
f870: 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
f880: 6f 79 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  oy parameter is 
f890: 70 61 73 73 65 64 20 74 6f 20 78 43 72 65 61 74  passed to xCreat
f8a0: 65 46 75 6e 63 74 69 6f 6e 28 29 2c 20 69 74 20  eFunction(), it 
f8b0: 69 73 20 69 6e 76 6f 6b 65 64 0a 77 69 74 68 20  is invoked.with 
f8c0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 43  a copy of the pC
f8d0: 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
f8e0: 61 73 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c  assed as the onl
f8f0: 79 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  y argument when 
f900: 74 68 65 0a 64 61 74 61 62 61 73 65 20 68 61 6e  the.database han
f910: 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  dle is closed or
f920: 20 77 68 65 6e 20 74 68 65 20 72 65 67 69 73 74   when the regist
f930: 65 72 65 64 20 61 75 78 69 6c 69 61 72 79 20 66  ered auxiliary f
f940: 75 6e 63 74 69 6f 6e 20 69 73 0a 72 65 70 6c 61  unction is.repla
f950: 63 65 64 2e 0a 0a 3c 70 3e 20 54 68 65 20 66 69  ced...<p> The fi
f960: 6e 61 6c 20 74 68 72 65 65 20 61 72 67 75 6d 65  nal three argume
f970: 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 74 68  nts passed to th
f980: 65 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  e auxiliary func
f990: 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 61 72  tion callback ar
f9a0: 65 0a 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 65  e.similar to the
f9b0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
f9c0: 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 69   passed to the i
f9d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
f9e0: 20 61 20 73 63 61 6c 61 72 20 53 51 4c 0a 66 75   a scalar SQL.fu
f9f0: 6e 63 74 69 6f 6e 2e 20 41 6c 6c 20 61 72 67 75  nction. All argu
fa00: 6d 65 6e 74 73 20 65 78 63 65 70 74 20 74 68 65  ments except the
fa10: 20 66 69 72 73 74 20 70 61 73 73 65 64 20 74 6f   first passed to
fa20: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 20 66   the auxiliary f
fa30: 75 6e 63 74 69 6f 6e 20 61 72 65 0a 61 76 61 69  unction are.avai
fa40: 6c 61 62 6c 65 20 74 6f 20 74 68 65 20 69 6d 70  lable to the imp
fa50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 74  lementation in t
fa60: 68 65 20 61 70 56 61 6c 26 23 39 31 3b 26 23 39  he apVal&#91;&#9
fa70: 33 3b 20 61 72 72 61 79 2e 20 54 68 65 0a 69 6d  3; array. The.im
fa80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
fa90: 75 6c 64 20 72 65 74 75 72 6e 20 61 20 72 65 73  uld return a res
faa0: 75 6c 74 20 6f 72 20 65 72 72 6f 72 20 76 69 61  ult or error via
fab0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 68 61 6e   the content han
fac0: 64 6c 65 20 70 43 74 78 2e 0a 0a 3c 70 3e 20 54  dle pCtx...<p> T
fad0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fae0: 74 20 70 61 73 73 65 64 20 74 6f 20 61 6e 20 61  t passed to an a
faf0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
fb00: 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  n callback is a 
fb10: 70 6f 69 6e 74 65 72 0a 74 6f 20 61 20 73 74 72  pointer.to a str
fb20: 75 63 74 75 72 65 20 63 6f 6e 74 61 69 6e 69 6e  ucture containin
fb30: 67 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20 6d  g methods that m
fb40: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 6e  ay be invoked in
fb50: 20 6f 72 64 65 72 20 74 6f 20 6f 62 74 61 69 6e   order to obtain
fb60: 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 72 65 67  .information reg
fb70: 61 72 64 69 6e 67 20 74 68 65 20 63 75 72 72 65  arding the curre
fb80: 6e 74 20 71 75 65 72 79 20 6f 72 20 72 6f 77 2e  nt query or row.
fb90: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
fba0: 6d 65 6e 74 20 69 73 20 61 6e 0a 6f 70 61 71 75  ment is an.opaqu
fbb0: 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 73 68  e handle that sh
fbc0: 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61  ould be passed a
fbd0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
fbe0: 6d 65 6e 74 20 74 6f 20 61 6e 79 20 73 75 63 68  ment to any such
fbf0: 20 6d 65 74 68 6f 64 20 0a 69 6e 76 6f 63 61 74   method .invocat
fc00: 69 6f 6e 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ion. For example
fc10: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
fc20: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
fc30: 6f 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20 72 65  on definition re
fc40: 74 75 72 6e 73 0a 74 68 65 20 74 6f 74 61 6c 20  turns.the total 
fc50: 6e 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73  number of tokens
fc60: 20 69 6e 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20   in all columns 
fc70: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  of the current r
fc80: 6f 77 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  ow:..<codeblock>
fc90: 0a 3c 69 3e 2f 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  .<i>/*.** Implem
fca0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
fcb0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
fcc0: 6e 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 74  n that returns t
fcd0: 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
fce0: 74 6f 6b 65 6e 73 20 69 6e 20 74 68 65 20 63 75  tokens in the cu
fcf0: 72 72 65 6e 74 20 72 6f 77 20 28 69 6e 63 6c 75  rrent row (inclu
fd00: 64 69 6e 67 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73  ding all columns
fd10: 29 2e 0a 2a 2f 3c 2f 69 3e 0a 73 74 61 74 69 63  )..*/</i>.static
fd20: 20 76 6f 69 64 20 63 6f 6c 75 6d 6e 5f 73 69 7a   void column_siz
fd30: 65 5f 69 6d 70 28 0a 20 20 63 6f 6e 73 74 20 46  e_imp(.  const F
fd40: 74 73 35 45 78 74 65 6e 73 69 6f 6e 41 70 69 20  ts5ExtensionApi 
fd50: 2a 70 41 70 69 2c 0a 20 20 46 74 73 35 43 6f 6e  *pApi,.  Fts5Con
fd60: 74 65 78 74 20 2a 70 46 74 73 2c 0a 20 20 73 71  text *pFts,.  sq
fd70: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 2a 70  lite3_context *p
fd80: 43 74 78 2c 0a 20 20 69 6e 74 20 6e 56 61 6c 2c  Ctx,.  int nVal,
fd90: 0a 20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  .  sqlite3_value
fda0: 20 2a 2a 61 70 56 61 6c 0a 29 7b 0a 20 20 69 6e   **apVal.){.  in
fdb0: 74 20 72 63 3b 0a 20 20 69 6e 74 20 6e 54 6f 6b  t rc;.  int nTok
fdc0: 65 6e 3b 0a 20 20 72 63 20 3d 20 70 41 70 69 2d  en;.  rc = pApi-
fdd0: 3e 78 43 6f 6c 75 6d 6e 53 69 7a 65 28 70 46 74  >xColumnSize(pFt
fde0: 73 2c 20 2d 31 2c 20 26 6e 54 6f 6b 65 6e 29 3b  s, -1, &nToken);
fdf0: 0a 20 20 69 66 28 20 72 63 3d 3d 53 51 4c 49 54  .  if( rc==SQLIT
fe00: 45 5f 4f 4b 20 29 7b 0a 20 20 20 20 73 71 6c 69  E_OK ){.    sqli
fe10: 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 70  te3_result_int(p
fe20: 43 74 78 2c 20 6e 54 6f 6b 65 6e 29 3b 0a 20 20  Ctx, nToken);.  
fe30: 7d 65 6c 73 65 7b 0a 20 20 20 20 73 71 6c 69 74  }else{.    sqlit
fe40: 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
fe50: 63 6f 64 65 28 70 43 74 78 2c 20 72 63 29 3b 0a  code(pCtx, rc);.
fe60: 20 20 7d 0a 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63    }.}.</codebloc
fe70: 6b 3e 0a 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f  k>..<p>The follo
fe80: 77 69 6e 67 20 73 65 63 74 69 6f 6e 20 64 65 73  wing section des
fe90: 63 72 69 62 65 73 20 74 68 65 20 41 50 49 20 6f  cribes the API o
fea0: 66 66 65 72 65 64 20 74 6f 20 61 75 78 69 6c 69  ffered to auxili
feb0: 61 72 79 20 66 75 6e 63 74 69 6f 6e 0a 69 6d 70  ary function.imp
fec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 69 6e 20  lementations in 
fed0: 64 65 74 61 69 6c 2e 20 46 75 72 74 68 65 72 20  detail. Further 
fee0: 65 78 61 6d 70 6c 65 73 20 6d 61 79 20 62 65 20  examples may be 
fef0: 66 6f 75 6e 64 20 69 6e 20 74 68 65 20 22 66 74  found in the "ft
ff00: 73 35 5f 61 75 78 2e 63 22 0a 66 69 6c 65 20 6f  s5_aux.c".file o
ff10: 66 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64  f the source cod
ff20: 65 2e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 63 75  e...<h3 tags="cu
ff30: 73 74 6f 6d 20 61 75 78 69 6c 69 61 72 79 20 66  stom auxiliary f
ff40: 75 6e 63 74 69 6f 6e 73 22 3e 0a 20 20 43 75 73  unctions">.  Cus
ff50: 74 6f 6d 20 41 75 78 69 6c 69 61 72 79 20 46 75  tom Auxiliary Fu
ff60: 6e 63 74 69 6f 6e 73 20 41 50 49 20 52 65 66 65  nctions API Refe
ff70: 72 65 6e 63 65 0a 3c 2f 68 33 3e 0a 0a 3c 63 6f  rence.</h3>..<co
ff80: 64 65 62 6c 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72  deblock>.<tclscr
ff90: 69 70 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22  ipt>.  set res "
ffa0: 22 0a 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63  ".  set ::extrac
ffb0: 74 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20  t_api_docs_mode 
ffc0: 46 74 73 35 45 78 74 65 6e 73 69 6f 6e 41 70 69  Fts5ExtensionApi
ffd0: 0a 20 20 63 61 74 63 68 20 7b 20 73 65 74 20 72  .  catch { set r
ffe0: 65 73 20 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65  es [source [file
fff0: 20 6a 6f 69 6e 20 24 3a 3a 53 52 43 20 65 78 74   join $::SRC ext
10000 2f 66 74 73 35 2f 65 78 74 72 61 63 74 5f 61 70  /fts5/extract_ap
10010 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20  i_docs.tcl]] }. 
10020 20 73 65 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63   set res.</tclsc
10030 72 69 70 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ript>.</codebloc
10040 6b 3e 0a 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a  k>..<tclscript>.
10050 20 20 73 65 74 20 72 65 73 20 22 22 0a 20 20 75    set res "".  u
10060 6e 73 65 74 20 2d 6e 6f 63 6f 6d 70 6c 61 69 6e  nset -nocomplain
10070 20 3a 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64   ::extract_api_d
10080 6f 63 73 5f 6d 6f 64 65 20 0a 20 20 63 61 74 63  ocs_mode .  catc
10090 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73 6f 75  h { set res [sou
100a0 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24  rce [file join $
100b0 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35 2f 65  ::SRC ext/fts5/e
100c0 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e  xtract_api_docs.
100d0 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65  tcl]] }.  set re
100e0 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e 0a 0a  s.</tclscript>..
100f0 3c 68 31 3e 54 68 65 20 66 74 73 35 76 6f 63 61  <h1>The fts5voca
10100 62 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  b Virtual Table 
10110 4d 6f 64 75 6c 65 3c 2f 68 31 3e 0a 0a 3c 70 3e  Module</h1>..<p>
10120 20 54 68 65 20 66 74 73 35 76 6f 63 61 62 20 76   The fts5vocab v
10130 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
10140 75 6c 65 20 61 6c 6c 6f 77 73 20 75 73 65 72 73  ule allows users
10150 20 74 6f 20 65 78 74 72 61 63 74 20 69 6e 66 6f   to extract info
10160 72 6d 61 74 69 6f 6e 20 66 72 6f 6d 0a 61 6e 20  rmation from.an 
10170 46 54 53 35 20 66 75 6c 6c 2d 74 65 78 74 20 69  FTS5 full-text i
10180 6e 64 65 78 20 64 69 72 65 63 74 6c 79 2e 20 54  ndex directly. T
10190 68 65 20 66 74 73 35 76 6f 63 61 62 20 6d 6f 64  he fts5vocab mod
101a0 75 6c 65 20 69 73 20 61 20 70 61 72 74 20 6f 66  ule is a part of
101b0 20 46 54 53 35 20 2d 20 69 74 20 0a 69 73 20 61   FTS5 - it .is a
101c0 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 65 76 65  vailable wheneve
101d0 72 20 46 54 53 35 20 69 73 2e 0a 0a 3c 70 3e 20  r FTS5 is...<p> 
101e0 45 61 63 68 20 66 74 73 35 76 6f 63 61 62 20 74  Each fts5vocab t
101f0 61 62 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74  able is associat
10200 65 64 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65  ed with a single
10210 20 46 54 53 35 20 74 61 62 6c 65 2e 20 41 6e 20   FTS5 table. An 
10220 66 74 73 35 76 6f 63 61 62 0a 74 61 62 6c 65 20  fts5vocab.table 
10230 69 73 20 75 73 75 61 6c 6c 79 20 63 72 65 61 74  is usually creat
10240 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
10250 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 69   two arguments i
10260 6e 20 70 6c 61 63 65 20 6f 66 20 63 6f 6c 75 6d  n place of colum
10270 6e 20 6e 61 6d 65 73 0a 69 6e 20 74 68 65 20 43  n names.in the C
10280 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
10290 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 2d 20  BLE statement - 
102a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
102b0 61 73 73 6f 63 69 61 74 65 64 20 46 54 53 35 20  associated FTS5 
102c0 74 61 62 6c 65 0a 61 6e 64 20 74 68 65 20 74 79  table.and the ty
102d0 70 65 20 6f 66 20 66 74 73 35 76 6f 63 61 62 20  pe of fts5vocab 
102e0 74 61 62 6c 65 2e 20 43 75 72 72 65 6e 74 6c 79  table. Currently
102f0 20 74 68 65 72 65 20 61 72 65 20 74 77 6f 20 74   there are two t
10300 79 70 65 73 20 6f 66 20 66 74 73 35 76 6f 63 61  ypes of fts5voca
10310 62 0a 74 61 62 6c 65 2c 20 22 72 6f 77 22 20 61  b.table, "row" a
10320 6e 64 20 22 63 6f 6c 22 2e 20 55 6e 6c 65 73 73  nd "col". Unless
10330 20 74 68 65 20 66 74 73 35 76 6f 63 61 62 20 74   the fts5vocab t
10340 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  able is created 
10350 77 69 74 68 69 6e 20 74 68 65 20 22 74 65 6d 70  within the "temp
10360 22 0a 64 61 74 61 62 61 73 65 2c 20 69 74 20 6d  ".database, it m
10370 75 73 74 20 62 65 20 70 61 72 74 20 6f 66 20 74  ust be part of t
10380 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
10390 20 61 73 20 74 68 65 20 61 73 73 6f 63 69 61 74   as the associat
103a0 65 64 20 46 54 53 35 20 74 61 62 6c 65 2e 0a 0a  ed FTS5 table...
103b0 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
103c0 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20 66 74  >-- Create an ft
103d0 73 35 76 6f 63 61 62 20 22 72 6f 77 22 20 74 61  s5vocab "row" ta
103e0 62 6c 65 20 74 6f 20 71 75 65 72 79 20 74 68 65  ble to query the
103f0 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
10400 20 62 65 6c 6f 6e 67 69 6e 67 0a 20 20 2d 2d 20   belonging.  -- 
10410 74 6f 20 46 54 53 35 20 74 61 62 6c 65 20 22 66  to FTS5 table "f
10420 74 31 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  t1".</i>.  CREAT
10430 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
10440 66 74 31 5f 76 20 55 53 49 4e 47 20 66 74 73 35  ft1_v USING fts5
10450 76 6f 63 61 62 28 27 66 74 31 27 2c 20 27 72 6f  vocab('ft1', 'ro
10460 77 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 72  w');..  <i>-- Cr
10470 65 61 74 65 20 61 6e 20 66 74 73 35 76 6f 63 61  eate an fts5voca
10480 62 20 22 63 6f 6c 22 20 74 61 62 6c 65 20 74 6f  b "col" table to
10490 20 71 75 65 72 79 20 74 68 65 20 66 75 6c 6c 2d   query the full-
104a0 74 65 78 74 20 69 6e 64 65 78 20 62 65 6c 6f 6e  text index belon
104b0 67 69 6e 67 0a 20 20 2d 2d 20 74 6f 20 46 54 53  ging.  -- to FTS
104c0 35 20 74 61 62 6c 65 20 22 66 74 32 22 2e 3c 2f  5 table "ft2".</
104d0 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
104e0 55 41 4c 20 54 41 42 4c 45 20 66 74 32 5f 76 20  UAL TABLE ft2_v 
104f0 55 53 49 4e 47 20 66 74 73 35 76 6f 63 61 62 28  USING fts5vocab(
10500 66 74 32 2c 20 63 6f 6c 29 3b 0a 3c 2f 63 6f 64  ft2, col);.</cod
10510 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 66 20  eblock>..<p> If 
10520 61 6e 20 66 74 73 35 76 6f 63 61 62 20 74 61 62  an fts5vocab tab
10530 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 69 6e  le is created in
10540 20 74 68 65 20 74 65 6d 70 20 64 61 74 61 62 61   the temp databa
10550 73 65 2c 20 69 74 20 6d 61 79 20 62 65 20 61 73  se, it may be as
10560 73 6f 63 69 61 74 65 64 0a 77 69 74 68 20 61 6e  sociated.with an
10570 20 46 54 53 35 20 74 61 62 6c 65 20 69 6e 20 61   FTS5 table in a
10580 6e 79 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ny attached data
10590 62 61 73 65 2e 20 49 6e 20 6f 72 64 65 72 20 74  base. In order t
105a0 6f 20 61 74 74 61 63 68 20 74 68 65 20 66 74 73  o attach the fts
105b0 35 76 6f 63 61 62 0a 74 61 62 6c 65 20 74 6f 20  5vocab.table to 
105c0 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 6c 6f  an FTS5 table lo
105d0 63 61 74 65 64 20 69 6e 20 61 20 64 61 74 61 62  cated in a datab
105e0 61 73 65 20 6f 74 68 65 72 20 74 68 61 6e 20 22  ase other than "
105f0 74 65 6d 70 22 2c 20 74 68 65 20 6e 61 6d 65 20  temp", the name 
10600 6f 66 20 74 68 65 0a 64 61 74 61 62 61 73 65 20  of the.database 
10610 69 73 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  is inserted befo
10620 72 65 20 74 68 65 20 46 54 53 35 20 74 61 62 6c  re the FTS5 tabl
10630 65 20 6e 61 6d 65 20 69 6e 20 74 68 65 20 43 52  e name in the CR
10640 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
10650 4c 45 20 0a 61 72 67 75 6d 65 6e 74 73 2e 20 46  LE .arguments. F
10660 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
10670 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
10680 20 43 72 65 61 74 65 20 61 6e 20 66 74 73 35 76   Create an fts5v
10690 6f 63 61 62 20 22 72 6f 77 22 20 74 61 62 6c 65  ocab "row" table
106a0 20 74 6f 20 71 75 65 72 79 20 74 68 65 20 66 75   to query the fu
106b0 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 62 65  ll-text index be
106c0 6c 6f 6e 67 69 6e 67 0a 20 20 2d 2d 20 74 6f 20  longing.  -- to 
106d0 46 54 53 35 20 74 61 62 6c 65 20 22 66 74 31 22  FTS5 table "ft1"
106e0 20 69 6e 20 64 61 74 61 62 61 73 65 20 22 6d 61   in database "ma
106f0 69 6e 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  in".</i>.  CREAT
10700 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
10710 74 65 6d 70 2e 66 74 31 5f 76 20 55 53 49 4e 47  temp.ft1_v USING
10720 20 66 74 73 35 76 6f 63 61 62 28 6d 61 69 6e 2c   fts5vocab(main,
10730 20 27 66 74 31 27 2c 20 27 72 6f 77 27 29 3b 0a   'ft1', 'row');.
10740 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20  .  <i>-- Create 
10750 61 6e 20 66 74 73 35 76 6f 63 61 62 20 22 63 6f  an fts5vocab "co
10760 6c 22 20 74 61 62 6c 65 20 74 6f 20 71 75 65 72  l" table to quer
10770 79 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  y the full-text 
10780 69 6e 64 65 78 20 62 65 6c 6f 6e 67 69 6e 67 0a  index belonging.
10790 20 20 2d 2d 20 74 6f 20 46 54 53 35 20 74 61 62    -- to FTS5 tab
107a0 6c 65 20 22 66 74 32 22 20 69 6e 20 61 74 74 61  le "ft2" in atta
107b0 63 68 65 64 20 64 61 74 61 62 61 73 65 20 22 61  ched database "a
107c0 75 78 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ux".</i>.  CREAT
107d0 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
107e0 74 65 6d 70 2e 66 74 32 5f 76 20 55 53 49 4e 47  temp.ft2_v USING
107f0 20 66 74 73 35 76 6f 63 61 62 28 27 61 75 78 27   fts5vocab('aux'
10800 2c 20 66 74 32 2c 20 63 6f 6c 29 3b 0a 3c 2f 63  , ft2, col);.</c
10810 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 53  odeblock>..<p> S
10820 70 65 63 69 66 79 69 6e 67 20 74 68 72 65 65 20  pecifying three 
10830 61 72 67 75 6d 65 6e 74 73 20 77 68 65 6e 20 63  arguments when c
10840 72 65 61 74 69 6e 67 20 61 6e 20 66 74 73 35 76  reating an fts5v
10850 6f 63 61 62 20 74 61 62 6c 65 20 69 6e 20 61 6e  ocab table in an
10860 79 20 64 61 74 61 62 61 73 65 0a 6f 74 68 65 72  y database.other
10870 20 74 68 61 6e 20 22 74 65 6d 70 22 20 72 65 73   than "temp" res
10880 75 6c 74 73 20 69 6e 20 61 6e 20 65 72 72 6f 72  ults in an error
10890 2e 0a 0a 3c 70 3e 20 41 6e 20 66 74 73 35 76 6f  ...<p> An fts5vo
108a0 63 61 62 20 74 61 62 6c 65 20 6f 66 20 74 79 70  cab table of typ
108b0 65 20 22 72 6f 77 22 20 63 6f 6e 74 61 69 6e 73  e "row" contains
108c0 20 6f 6e 65 20 72 6f 77 20 66 6f 72 20 65 61 63   one row for eac
108d0 68 20 64 69 73 74 69 6e 63 74 20 74 65 72 6d 0a  h distinct term.
108e0 69 6e 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  in the associate
108f0 64 20 46 54 53 35 20 74 61 62 6c 65 2e 20 54 68  d FTS5 table. Th
10900 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 73 20  e table columns 
10910 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
10920 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65 64 3d  .<table striped=
10930 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 43 6f 6c  1>.  <tr><th>Col
10940 75 6d 6e 3c 74 68 3e 43 6f 6e 74 65 6e 74 73 0a  umn<th>Contents.
10950 20 20 3c 74 72 3e 3c 74 64 3e 74 65 72 6d 3c 74    <tr><td>term<t
10960 64 3e 20 54 68 65 20 74 65 72 6d 2c 20 61 73 20  d> The term, as 
10970 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 46 54  stored in the FT
10980 53 35 20 69 6e 64 65 78 2e 0a 20 20 3c 74 72 3e  S5 index..  <tr>
10990 3c 74 64 3e 64 6f 63 3c 74 64 3e 20 20 54 68 65  <td>doc<td>  The
109a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
109b0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20  that contain at 
109c0 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e  least one instan
109d0 63 65 20 6f 66 20 74 68 65 20 74 65 72 6d 2e 0a  ce of the term..
109e0 20 20 3c 74 72 3e 3c 74 64 3e 63 6e 74 3c 74 64    <tr><td>cnt<td
109f0 3e 20 20 54 68 65 20 74 6f 74 61 6c 20 6e 75 6d  >  The total num
10a00 62 65 72 20 6f 66 20 69 6e 73 74 61 6e 63 65 73  ber of instances
10a10 20 6f 66 20 74 68 65 20 74 65 72 6d 20 69 6e 20   of the term in 
10a20 74 68 65 20 65 6e 74 69 72 65 20 46 54 53 35 20  the entire FTS5 
10a30 74 61 62 6c 65 2e 0a 3c 2f 74 61 62 6c 65 3e 0a  table..</table>.
10a40 0a 3c 70 3e 20 41 6e 20 66 74 73 35 76 6f 63 61  .<p> An fts5voca
10a50 62 20 74 61 62 6c 65 20 6f 66 20 74 79 70 65 20  b table of type 
10a60 22 63 6f 6c 22 20 63 6f 6e 74 61 69 6e 73 20 6f  "col" contains o
10a70 6e 65 20 72 6f 77 20 66 6f 72 20 65 61 63 68 20  ne row for each 
10a80 64 69 73 74 69 6e 63 74 20 74 65 72 6d 2f 63 6f  distinct term/co
10a90 6c 75 6d 6e 0a 63 6f 6d 62 69 6e 61 74 69 6f 6e  lumn.combination
10aa0 20 69 6e 20 74 68 65 20 61 73 73 6f 63 69 61 74   in the associat
10ab0 65 64 20 46 54 53 35 20 74 61 62 6c 65 2e 20 54  ed FTS5 table. T
10ac0 61 62 6c 65 20 63 6f 6c 75 6d 6e 73 20 61 72 65  able columns are
10ad0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 74   as follows:..<t
10ae0 61 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a  able striped=1>.
10af0 20 20 3c 74 72 3e 3c 74 68 3e 43 6f 6c 75 6d 6e    <tr><th>Column
10b00 3c 74 68 3e 43 6f 6e 74 65 6e 74 73 0a 20 20 3c  <th>Contents.  <
10b10 74 72 3e 3c 74 64 3e 74 65 72 6d 3c 74 64 3e 20  tr><td>term<td> 
10b20 54 68 65 20 74 65 72 6d 2c 20 61 73 20 73 74 6f  The term, as sto
10b30 72 65 64 20 69 6e 20 74 68 65 20 46 54 53 35 20  red in the FTS5 
10b40 69 6e 64 65 78 2e 0a 20 20 3c 74 72 3e 3c 74 64  index..  <tr><td
10b50 3e 63 6f 6c 3c 74 64 3e 20 20 54 68 65 20 6e 61  >col<td>  The na
10b60 6d 65 20 6f 66 20 74 68 65 20 46 54 53 35 20 74  me of the FTS5 t
10b70 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
10b80 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
10b90 72 6d 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 64 6f  rm..  <tr><td>do
10ba0 63 3c 74 64 3e 20 20 54 68 65 20 6e 75 6d 62 65  c<td>  The numbe
10bb0 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
10bc0 20 46 54 53 35 20 74 61 62 6c 65 20 66 6f 72 20   FTS5 table for 
10bd0 77 68 69 63 68 20 63 6f 6c 75 6d 6e 20 24 63 6f  which column $co
10be0 6c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l.              
10bf0 20 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 61 74       contains at
10c00 20 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61   least one insta
10c10 6e 63 65 20 6f 66 20 74 68 65 20 74 65 72 6d 2e  nce of the term.
10c20 0a 20 20 3c 74 72 3e 3c 74 64 3e 63 6e 74 3c 74  .  <tr><td>cnt<t
10c30 64 3e 20 20 54 68 65 20 74 6f 74 61 6c 20 6e 75  d>  The total nu
10c40 6d 62 65 72 20 6f 66 20 69 6e 73 74 61 6e 63 65  mber of instance
10c50 73 20 6f 66 20 74 68 65 20 74 65 72 6d 20 74 68  s of the term th
10c60 61 74 20 61 70 70 65 61 72 20 69 6e 0a 20 20 20  at appear in.   
10c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
10c80 63 6f 6c 75 6d 6e 20 24 63 6f 6c 20 6f 66 20 74  column $col of t
10c90 68 65 20 46 54 53 35 20 74 61 62 6c 65 20 28 63  he FTS5 table (c
10ca0 6f 6e 73 69 64 65 72 69 6e 67 20 61 6c 6c 20 72  onsidering all r
10cb0 6f 77 73 29 2e 20 0a 3c 2f 74 61 62 6c 65 3e 0a  ows). .</table>.
10cc0 0a 3c 70 3e 45 78 61 6d 70 6c 65 3a 0a 0a 3c 63  .<p>Example:..<c
10cd0 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d  odeblock>.  <i>-
10ce0 2d 20 41 73 73 75 6d 69 6e 67 20 61 20 64 61 74  - Assuming a dat
10cf0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
10d00 69 6e 67 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ing:</i>.  CREAT
10d10 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
10d20 66 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 63  ft1 USING fts5(c
10d30 31 2c 20 63 32 29 3b 0a 20 20 49 4e 53 45 52 54  1, c2);.  INSERT
10d40 20 49 4e 54 4f 20 66 74 31 20 56 41 4c 55 45 53   INTO ft1 VALUES
10d50 28 27 61 70 70 6c 65 20 62 61 6e 61 6e 61 20 63  ('apple banana c
10d60 68 65 72 72 79 27 2c 20 27 62 61 6e 61 6e 61 20  herry', 'banana 
10d70 62 61 6e 61 6e 61 20 63 68 65 72 72 79 27 29 3b  banana cherry');
10d80 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66  .  INSERT INTO f
10d90 74 31 20 56 41 4c 55 45 53 28 27 63 68 65 72 72  t1 VALUES('cherr
10da0 79 20 63 68 65 72 72 79 20 63 68 65 72 72 79 27  y cherry cherry'
10db0 2c 20 27 64 61 74 65 20 64 61 74 65 20 64 61 74  , 'date date dat
10dc0 65 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68  e');..  <i>-- Th
10dd0 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20  en querying the 
10de0 66 6f 6c 6c 6f 77 69 6e 67 20 66 74 73 35 76 6f  following fts5vo
10df0 63 61 62 20 74 61 62 6c 65 20 28 74 79 70 65 20  cab table (type 
10e00 22 63 6f 6c 22 29 20 72 65 74 75 72 6e 73 3a 0a  "col") returns:.
10e10 20 20 2d 2d 0a 20 20 2d 2d 20 20 20 20 61 70 70    --.  --    app
10e20 6c 65 20 20 7c 20 63 31 20 7c 20 31 20 7c 20 31  le  | c1 | 1 | 1
10e30 0a 20 20 2d 2d 20 20 20 20 62 61 6e 61 6e 61 20  .  --    banana 
10e40 7c 20 63 31 20 7c 20 31 20 7c 20 31 0a 20 20 2d  | c1 | 1 | 1.  -
10e50 2d 20 20 20 20 62 61 6e 61 6e 61 20 7c 20 63 32  -    banana | c2
10e60 20 7c 20 31 20 7c 20 32 0a 20 20 2d 2d 20 20 20   | 1 | 2.  --   
10e70 20 63 68 65 72 72 79 20 7c 20 63 31 20 7c 20 32   cherry | c1 | 2
10e80 20 7c 20 34 0a 20 20 2d 2d 20 20 20 20 63 68 65   | 4.  --    che
10e90 72 72 79 20 7c 20 63 32 20 7c 20 31 20 7c 20 31  rry | c2 | 1 | 1
10ea0 0a 20 20 2d 2d 20 20 20 20 64 61 74 65 20 20 20  .  --    date   
10eb0 7c 20 63 33 20 7c 20 31 20 7c 20 33 0a 20 20 2d  | c3 | 1 | 3.  -
10ec0 2d 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  -</i>.  CREATE V
10ed0 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 31  IRTUAL TABLE ft1
10ee0 5f 76 5f 63 6f 6c 20 55 53 49 4e 47 20 66 74 73  _v_col USING fts
10ef0 35 76 6f 63 61 62 28 66 74 31 2c 20 63 6f 6c 29  5vocab(ft1, col)
10f00 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79  ;..  <i>-- Query
10f10 69 6e 67 20 61 6e 20 66 74 73 35 76 6f 63 61 62  ing an fts5vocab
10f20 20 74 61 62 6c 65 20 6f 66 20 74 79 70 65 20 22   table of type "
10f30 72 6f 77 22 20 72 65 74 75 72 6e 73 3a 0a 20 20  row" returns:.  
10f40 2d 2d 0a 20 20 2d 2d 20 20 20 20 61 70 70 6c 65  --.  --    apple
10f50 20 20 7c 20 31 20 7c 20 31 0a 20 20 2d 2d 20 20    | 1 | 1.  --  
10f60 20 20 62 61 6e 61 6e 61 20 7c 20 31 20 7c 20 33    banana | 1 | 3
10f70 0a 20 20 2d 2d 20 20 20 20 63 68 65 72 72 79 20  .  --    cherry 
10f80 7c 20 32 20 7c 20 35 0a 20 20 2d 2d 20 20 20 20  | 2 | 5.  --    
10f90 64 61 74 65 20 20 20 7c 20 31 20 7c 20 33 0a 20  date   | 1 | 3. 
10fa0 20 2d 2d 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45   --</i>.  CREATE
10fb0 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
10fc0 74 31 5f 76 5f 72 6f 77 20 55 53 49 4e 47 20 66  t1_v_row USING f
10fd0 74 73 35 76 6f 63 61 62 28 66 74 31 2c 20 72 6f  ts5vocab(ft1, ro
10fe0 77 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  w);.</codeblock>
10ff0 0a 0a 0a 3c 68 31 20 69 64 3d 61 70 70 65 6e 64  ...<h1 id=append
11000 69 78 5f 61 20 6e 6f 6e 75 6d 62 65 72 20 74 61  ix_a nonumber ta
11010 67 73 3d 22 63 6f 6d 70 61 72 69 73 6f 6e 20 77  gs="comparison w
11020 69 74 68 20 66 74 73 34 22 3e 0a 20 20 41 70 70  ith fts4">.  App
11030 65 6e 64 69 78 20 41 3a 20 43 6f 6d 70 61 72 69  endix A: Compari
11040 73 6f 6e 20 77 69 74 68 20 46 54 53 33 2f 34 0a  son with FTS3/4.
11050 3c 2f 68 31 3e 0a 0a 3c 70 3e 20 41 6c 73 6f 20  </h1>..<p> Also 
11060 61 76 61 69 6c 61 62 6c 65 20 69 73 20 74 68 65  available is the
11070 20 73 69 6d 69 6c 61 72 20 62 75 74 20 6d 6f 72   similar but mor
11080 65 20 6d 61 74 75 72 65 20 5b 66 74 73 33 20 7c  e mature [fts3 |
11090 20 46 54 53 33 2f 34 5d 20 6d 6f 64 75 6c 65 2e   FTS3/4] module.
110a0 20 0a 46 54 53 35 20 69 73 20 61 20 6e 65 77 20   .FTS5 is a new 
110b0 76 65 72 73 69 6f 6e 20 6f 66 20 46 54 53 34 20  version of FTS4 
110c0 74 68 61 74 20 69 6e 63 6c 75 64 65 73 20 76 61  that includes va
110d0 72 69 6f 75 73 20 66 69 78 65 73 20 61 6e 64 20  rious fixes and 
110e0 73 6f 6c 75 74 69 6f 6e 73 20 66 6f 72 20 0a 70  solutions for .p
110f0 72 6f 62 6c 65 6d 73 20 74 68 61 74 20 63 6f 75  roblems that cou
11100 6c 64 20 6e 6f 74 20 62 65 20 66 69 78 65 64 20  ld not be fixed 
11110 69 6e 20 46 54 53 34 20 77 69 74 68 6f 75 74 20  in FTS4 without 
11120 73 61 63 72 69 66 69 63 69 6e 67 20 62 61 63 6b  sacrificing back
11130 77 61 72 64 73 20 0a 63 6f 6d 70 61 74 69 62 69  wards .compatibi
11140 6c 69 74 79 2e 20 53 6f 6d 65 20 6f 66 20 74 68  lity. Some of th
11150 65 73 65 20 70 72 6f 62 6c 65 6d 73 20 61 72 65  ese problems are
11160 20 0a 5b 66 74 73 35 20 74 65 63 68 6e 69 63 61   .[fts5 technica
11170 6c 20 64 69 66 66 65 72 65 6e 63 65 73 20 7c 20  l differences | 
11180 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 5d  described below]
11190 2e 0a 0a 3c 68 32 20 6e 6f 6e 75 6d 62 65 72 3e  ...<h2 nonumber>
111a0 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 50 6f 72   Application Por
111b0 74 69 6e 67 20 47 75 69 64 65 20 3c 2f 68 32 3e  ting Guide </h2>
111c0 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65 72 20 74  ..<p> In order t
111d0 6f 20 75 73 65 20 46 54 53 35 20 69 6e 73 74 65  o use FTS5 inste
111e0 61 64 20 6f 66 20 46 54 53 33 20 6f 72 20 46 54  ad of FTS3 or FT
111f0 53 34 2c 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  S4, applications
11200 20 75 73 75 61 6c 6c 79 20 72 65 71 75 69 72 65   usually require
11210 0a 6d 69 6e 69 6d 61 6c 20 6d 6f 64 69 66 69 63  .minimal modific
11220 61 74 69 6f 6e 73 2e 20 4d 6f 73 74 20 6f 66 20  ations. Most of 
11230 74 68 65 73 65 20 66 61 6c 6c 20 69 6e 74 6f 20  these fall into 
11240 74 68 72 65 65 20 63 61 74 65 67 6f 72 69 65 73  three categories
11250 20 2d 20 63 68 61 6e 67 65 73 0a 72 65 71 75 69   - changes.requi
11260 72 65 64 20 74 6f 20 74 68 65 20 43 52 45 41 54  red to the CREAT
11270 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
11280 73 74 61 74 65 6d 65 6e 74 20 75 73 65 64 20 74  statement used t
11290 6f 20 63 72 65 61 74 65 20 74 68 65 20 46 54 53  o create the FTS
112a0 20 74 61 62 6c 65 2c 0a 63 68 61 6e 67 65 73 20   table,.changes 
112b0 72 65 71 75 69 72 65 64 20 74 6f 20 53 45 4c 45  required to SELE
112c0 43 54 20 71 75 65 72 69 65 73 20 75 73 65 64 20  CT queries used 
112d0 74 6f 20 65 78 65 63 75 74 65 20 71 75 65 72 69  to execute queri
112e0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 74  es against the t
112f0 61 62 6c 65 2c 0a 61 6e 64 20 63 68 61 6e 67 65  able,.and change
11300 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 61 70  s required to ap
11310 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
11320 75 73 65 20 5b 46 54 53 20 61 75 78 69 6c 69 61  use [FTS auxilia
11330 72 79 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a  ry functions]...
11340 3c 68 33 20 6e 6f 6e 75 6d 62 65 72 3e 20 43 68  <h3 nonumber> Ch
11350 61 6e 67 65 73 20 74 6f 20 43 52 45 41 54 45 20  anges to CREATE 
11360 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
11370 61 74 65 6d 65 6e 74 73 20 3c 2f 68 33 3e 0a 0a  atements </h3>..
11380 3c 6f 6c 3e 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65  <ol>.<li> <p>The
11390 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 6d 75 73   module name mus
113a0 74 20 62 65 20 63 68 61 6e 67 65 64 20 66 72 6f  t be changed fro
113b0 6d 20 22 66 74 73 33 22 20 6f 72 20 22 66 74 73  m "fts3" or "fts
113c0 34 22 20 74 6f 20 22 66 74 73 35 22 2e 0a 0a 3c  4" to "fts5"...<
113d0 6c 69 3e 20 3c 70 3e 41 6c 6c 20 74 79 70 65 20  li> <p>All type 
113e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 72 20 63  information or c
113f0 6f 6e 73 74 72 61 69 6e 74 20 73 70 65 63 69 66  onstraint specif
11400 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  ications must be
11410 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 0a 20 20   removed from.  
11420 20 20 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69     column defini
11430 74 69 6f 6e 73 2e 20 46 54 53 33 2f 34 20 69 67  tions. FTS3/4 ig
11440 6e 6f 72 65 73 20 65 76 65 72 79 74 68 69 6e 67  nores everything
11450 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63   following the c
11460 6f 6c 75 6d 6e 20 6e 61 6d 65 20 69 6e 0a 20 20  olumn name in.  
11470 20 20 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69     a column defi
11480 6e 69 74 69 6f 6e 2c 20 46 54 53 35 20 61 74 74  nition, FTS5 att
11490 65 6d 70 74 73 20 74 6f 20 70 61 72 73 65 20 69  empts to parse i
114a0 74 20 28 61 6e 64 20 77 69 6c 6c 20 72 65 70 6f  t (and will repo
114b0 72 74 20 61 6e 20 65 72 72 6f 72 0a 20 20 20 20  rt an error.    
114c0 20 69 66 20 69 74 20 66 61 69 6c 73 20 74 6f 29   if it fails to)
114d0 2e 0a 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 22  ...<li> <p>The "
114e0 6d 61 74 63 68 69 6e 66 6f 3d 66 74 73 33 22 20  matchinfo=fts3" 
114f0 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 76  option is not av
11500 61 69 6c 61 62 6c 65 2e 20 54 68 65 20 0a 20 20  ailable. The .  
11510 20 20 20 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 73     [FTS5 columns
11520 69 7a 65 20 6f 70 74 69 6f 6e 20 7c 20 22 63 6f  ize option | "co
11530 6c 75 6d 6e 73 69 7a 65 3d 30 22 5d 20 6f 70 74  lumnsize=0"] opt
11540 69 6f 6e 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ion is equivalen
11550 74 2e 0a 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20  t...<li> <p>The 
11560 6e 6f 74 69 6e 64 65 78 65 64 3d 20 6f 70 74 69  notindexed= opti
11570 6f 6e 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  on is not availa
11580 62 6c 65 2e 20 41 64 64 69 6e 67 20 5b 75 6e 69  ble. Adding [uni
11590 6e 64 65 78 65 64 20 7c 20 55 4e 49 4e 44 45 58  ndexed | UNINDEX
115a0 45 44 5d 0a 20 20 20 20 20 74 6f 20 74 68 65 20  ED].     to the 
115b0 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f  column definitio
115c0 6e 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 2e  n is equivalent.
115d0 0a 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 49 43  ..<li> <p>The IC
115e0 55 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 6e  U tokenizer is n
115f0 6f 74 20 61 76 61 69 6c 61 62 6c 65 2e 0a 0a 3c  ot available...<
11600 6c 69 3e 20 3c 70 3e 54 68 65 20 63 6f 6d 70 72  li> <p>The compr
11610 65 73 73 3d 2c 20 75 6e 63 6f 6d 70 72 65 73 73  ess=, uncompress
11620 3d 20 61 6e 64 20 6c 61 6e 67 75 61 67 65 69 64  = and languageid
11630 3d 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6e 6f  = options are no
11640 74 20 61 76 61 69 6c 61 62 6c 65 2e 0a 20 20 20  t available..   
11650 20 20 54 68 65 72 65 20 69 73 20 61 73 20 6f 66    There is as of
11660 20 79 65 74 20 6e 6f 20 65 71 75 69 76 61 6c 65   yet no equivale
11670 6e 74 20 66 6f 72 20 74 68 65 69 72 20 66 75 6e  nt for their fun
11680 63 74 69 6f 6e 61 6c 69 74 79 2e 0a 3c 2f 6f 6c  ctionality..</ol
11690 3e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  >..<codeblock>. 
116a0 20 3c 69 3e 20 2d 2d 20 46 54 53 33 2f 34 20 73   <i> -- FTS3/4 s
116b0 74 61 74 65 6d 65 6e 74 20 3c 2f 69 3e 0a 20 20  tatement </i>.  
116c0 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
116d0 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74  ABLE t1 USING ft
116e0 73 34 28 0a 20 20 20 20 6c 69 6e 6b 69 64 20 49  s4(.    linkid I
116f0 4e 54 45 47 45 52 2c 0a 20 20 20 20 68 65 61 64  NTEGER,.    head
11700 65 72 20 43 48 41 52 28 32 30 29 2c 0a 20 20 20  er CHAR(20),.   
11710 20 74 65 78 74 20 56 41 52 43 48 41 52 2c 0a 20   text VARCHAR,. 
11720 20 20 20 6e 6f 74 69 6e 64 65 78 65 64 3d 6c 69     notindexed=li
11730 6e 6b 69 64 2c 0a 20 20 20 20 6d 61 74 63 68 69  nkid,.    matchi
11740 6e 66 6f 3d 66 74 73 33 2c 0a 20 20 20 20 74 6f  nfo=fts3,.    to
11750 6b 65 6e 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36  kenizer=unicode6
11760 31 0a 20 20 29 3b 0a 0a 20 20 3c 69 3e 20 2d 2d  1.  );..  <i> --
11770 20 46 54 53 35 20 65 71 75 69 76 61 6c 65 6e 74   FTS5 equivalent
11780 20 28 6e 6f 74 65 20 2d 20 74 68 65 20 22 74 6f   (note - the "to
11790 6b 65 6e 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36  kenizer=unicode6
117a0 31 22 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74  1" option is not
117b0 3c 2f 69 3e 0a 20 20 3c 69 3e 20 2d 2d 20 72 65  </i>.  <i> -- re
117c0 71 75 69 72 65 64 20 61 73 20 74 68 69 73 20 69  quired as this i
117d0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 66 6f  s the default fo
117e0 72 20 46 54 53 35 20 61 6e 79 77 61 79 29 3c 2f  r FTS5 anyway)</
117f0 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
11800 55 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49  UAL TABLE t1 USI
11810 4e 47 20 66 74 73 35 28 0a 20 20 20 20 6c 69 6e  NG fts5(.    lin
11820 6b 69 64 20 55 4e 49 4e 44 45 58 45 44 2c 0a 20  kid UNINDEXED,. 
11830 20 20 20 68 65 61 64 65 72 2c 0a 20 20 20 20 74     header,.    t
11840 65 78 74 2c 0a 20 20 20 20 63 6f 6c 75 6d 6e 73  ext,.    columns
11850 69 7a 65 3d 30 0a 20 20 29 3b 0a 3c 2f 63 6f 64  ize=0.  );.</cod
11860 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 33 20 6e 6f 6e  eblock>..<h3 non
11870 75 6d 62 65 72 3e 20 43 68 61 6e 67 65 73 20 74  umber> Changes t
11880 6f 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  o SELECT stateme
11890 6e 74 73 20 3c 2f 68 33 3e 0a 0a 3c 6f 6c 3e 0a  nts </h3>..<ol>.
118a0 20 20 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 22 64    <li> <p>The "d
118b0 6f 63 69 64 22 20 61 6c 69 61 73 20 64 6f 65 73  ocid" alias does
118c0 20 6e 6f 74 20 65 78 69 73 74 2e 20 41 70 70 6c   not exist. Appl
118d0 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 75 73  ications must us
118e0 65 20 22 72 6f 77 69 64 22 0a 20 20 20 20 20 20  e "rowid".      
118f0 20 20 20 20 69 6e 73 74 65 61 64 2e 0a 0a 20 20      instead...  
11900 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 6c 65 66 74  <li> <p>The left
11910 20 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68   hand side of th
11920 65 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72  e MATCH operator
11930 20 69 6e 20 61 20 66 75 6c 6c 2d 74 65 78 74 20   in a full-text 
11940 71 75 65 72 79 20 6d 75 73 74 20 62 65 0a 20 20  query must be.  
11950 20 20 20 20 20 20 20 20 74 68 65 20 74 61 62 6c          the tabl
11960 65 20 6e 61 6d 65 20 2d 20 6e 6f 74 20 61 6e 79  e name - not any
11970 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 61 73 20   column name as 
11980 69 6e 20 46 54 53 34 2e 0a 0a 20 20 3c 6c 69 3e  in FTS4...  <li>
11990 20 3c 70 3e 54 68 65 20 46 54 53 20 71 75 65 72   <p>The FTS quer
119a0 79 20 73 79 6e 74 61 78 20 28 72 69 67 68 74 20  y syntax (right 
119b0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
119c0 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 29   MATCH operator)
119d0 20 68 61 73 0a 20 20 20 20 20 20 20 20 20 20 63   has.          c
119e0 68 61 6e 67 65 64 20 69 6e 20 73 6f 6d 65 20 77  hanged in some w
119f0 61 79 73 2e 20 54 68 65 20 46 54 53 35 20 73 79  ays. The FTS5 sy
11a00 6e 74 61 78 20 69 73 20 71 75 69 74 65 20 63 6c  ntax is quite cl
11a10 6f 73 65 20 74 6f 20 74 68 65 20 46 54 53 34 0a  ose to the FTS4.
11a20 20 20 20 20 20 20 20 20 20 20 22 65 6e 68 61 6e            "enhan
11a30 63 65 64 20 73 79 6e 74 61 78 22 2e 20 54 68 65  ced syntax". The
11a40 20 6d 61 69 6e 20 64 69 66 66 65 72 65 6e 63 65   main difference
11a50 20 69 73 20 74 68 61 74 20 46 54 53 35 20 69 73   is that FTS5 is
11a60 20 66 75 73 73 69 65 72 20 0a 20 20 20 20 20 20   fussier .      
11a70 20 20 20 20 61 62 6f 75 74 20 75 6e 72 65 63 6f      about unreco
11a80 67 6e 69 7a 65 64 20 70 75 6e 63 74 75 61 74 69  gnized punctuati
11a90 6f 6e 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  on characters an
11aa0 64 20 73 69 6d 69 6c 61 72 20 77 69 74 68 69 6e  d similar within
11ab0 20 71 75 65 72 79 0a 20 20 20 20 20 20 20 20 20   query.         
11ac0 20 73 74 72 69 6e 67 73 2e 20 4d 6f 73 74 20 71   strings. Most q
11ad0 75 65 72 69 65 73 20 74 68 61 74 20 77 6f 72 6b  ueries that work
11ae0 20 77 69 74 68 20 46 54 53 33 2f 34 20 73 68 6f   with FTS3/4 sho
11af0 75 6c 64 20 61 6c 73 6f 20 77 6f 72 6b 20 77 69  uld also work wi
11b00 74 68 0a 20 20 20 20 20 20 20 20 20 20 46 54 53  th.          FTS
11b10 35 2c 20 61 6e 64 20 74 68 6f 73 65 20 74 68 61  5, and those tha
11b20 74 20 64 6f 20 6e 6f 74 20 73 68 6f 75 6c 64 20  t do not should 
11b30 72 65 74 75 72 6e 20 70 61 72 73 65 20 65 72 72  return parse err
11b40 6f 72 73 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 63 6f 64  ors..</ol>..<cod
11b50 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
11b60 46 54 53 33 2f 34 20 71 75 65 72 79 20 3c 2f 69  FTS3/4 query </i
11b70 3e 0a 20 20 53 45 4c 45 43 54 20 64 6f 63 69 64  >.  SELECT docid
11b80 20 46 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74   FROM t1 WHERE t
11b90 65 78 74 20 4d 41 54 43 48 20 27 74 6f 6b 65 6e  ext MATCH 'token
11ba0 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 46 54 53 35  ';..  <i>-- FTS5
11bb0 20 65 71 75 69 76 61 6c 65 6e 74 20 3c 2f 69 3e   equivalent </i>
11bc0 0a 20 20 53 45 4c 45 43 54 20 72 6f 77 69 64 20  .  SELECT rowid 
11bd0 46 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74 31  FROM t1 WHERE t1
11be0 20 4d 41 54 43 48 20 27 74 65 78 74 3a 74 6f 6b   MATCH 'text:tok
11bf0 65 6e 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  en';.</codeblock
11c00 3e 0a 0a 3c 68 33 20 6e 6f 6e 75 6d 62 65 72 3e  >..<h3 nonumber>
11c10 20 41 75 78 69 6c 69 61 72 79 20 46 75 6e 63 74   Auxiliary Funct
11c20 69 6f 6e 20 43 68 61 6e 67 65 73 20 3c 2f 68 33  ion Changes </h3
11c30 3e 0a 0a 3c 70 3e 20 46 54 53 35 20 68 61 73 20  >..<p> FTS5 has 
11c40 6e 6f 20 6d 61 74 63 68 69 6e 66 6f 28 29 20 6f  no matchinfo() o
11c50 72 20 6f 66 66 73 65 74 73 28 29 20 66 75 6e 63  r offsets() func
11c60 74 69 6f 6e 2c 20 61 6e 64 20 74 68 65 20 73 6e  tion, and the sn
11c70 69 70 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  ippet() function
11c80 0a 69 73 20 6e 6f 74 20 61 73 20 66 75 6c 6c 79  .is not as fully
11c90 2d 66 65 61 74 75 72 65 64 20 61 73 20 69 6e 20  -featured as in 
11ca0 46 54 53 33 2f 34 2e 20 48 6f 77 65 76 65 72 2c  FTS3/4. However,
11cb0 20 73 69 6e 63 65 20 46 54 53 35 20 64 6f 65 73   since FTS5 does
11cc0 20 70 72 6f 76 69 64 65 20 0a 61 6e 20 41 50 49   provide .an API
11cd0 20 61 6c 6c 6f 77 69 6e 67 20 61 70 70 6c 69 63   allowing applic
11ce0 61 74 69 6f 6e 73 20 74 6f 20 63 72 65 61 74 65  ations to create
11cf0 20 5b 63 75 73 74 6f 6d 20 61 75 78 69 6c 69 61   [custom auxilia
11d00 72 79 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 20 61  ry functions], a
11d10 6e 79 0a 72 65 71 75 69 72 65 64 20 66 75 6e 63  ny.required func
11d20 74 69 6f 6e 61 6c 69 74 79 20 6d 61 79 20 62 65  tionality may be
11d30 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 77 69 74   implemented wit
11d40 68 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hin the applicat
11d50 69 6f 6e 20 63 6f 64 65 2e 0a 0a 3c 70 3e 20 54  ion code...<p> T
11d60 68 65 20 73 65 74 20 6f 66 20 62 75 69 6c 74 2d  he set of built-
11d70 69 6e 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  in auxiliary fun
11d80 63 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20  ctions provided 
11d90 62 79 20 46 54 53 35 20 6d 61 79 20 62 65 20 0a  by FTS5 may be .
11da0 69 6d 70 72 6f 76 65 64 20 75 70 6f 6e 20 69 6e  improved upon in
11db0 20 74 68 65 20 66 75 74 75 72 65 2e 0a 0a 3c 68   the future...<h
11dc0 33 20 6e 6f 6e 75 6d 62 65 72 3e 20 4f 74 68 65  3 nonumber> Othe
11dd0 72 20 49 73 73 75 65 73 3c 2f 68 33 3e 0a 0a 3c  r Issues</h3>..<
11de0 6f 6c 3e 0a 20 20 3c 6c 69 3e 3c 70 3e 20 46 54  ol>.  <li><p> FT
11df0 53 35 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  S5 does not curr
11e00 65 6e 74 6c 79 20 70 72 6f 76 69 64 65 20 61 6e  ently provide an
11e10 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74   equivalent to t
11e20 68 65 20 66 74 73 34 61 75 78 20 74 61 62 6c 65  he fts4aux table
11e30 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65  ...  <li><p> The
11e40 20 46 54 53 33 2f 34 20 22 6d 65 72 67 65 3d 58   FTS3/4 "merge=X
11e50 2c 59 22 20 63 6f 6d 6d 61 6e 64 20 68 61 73 20  ,Y" command has 
11e60 62 65 65 6e 20 72 65 70 6c 61 63 65 64 20 62 79  been replaced by
11e70 20 74 68 65 20 0a 20 20 20 20 20 20 20 20 20 20   the .          
11e80 5b 46 54 53 35 20 6d 65 72 67 65 20 63 6f 6d 6d  [FTS5 merge comm
11e90 61 6e 64 5d 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e  and]...  <li><p>
11ea0 20 54 68 65 20 46 54 53 33 2f 34 20 22 61 75 74   The FTS3/4 "aut
11eb0 6f 6d 65 72 67 65 3d 58 22 20 63 6f 6d 6d 61 6e  omerge=X" comman
11ec0 64 20 68 61 73 20 62 65 65 6e 20 72 65 70 6c 61  d has been repla
11ed0 63 65 64 20 62 79 20 74 68 65 20 0a 20 20 20 20  ced by the .    
11ee0 20 20 20 20 20 20 5b 46 54 53 35 20 61 75 74 6f        [FTS5 auto
11ef0 6d 65 72 67 65 20 6f 70 74 69 6f 6e 5d 2e 0a 3c  merge option]..<
11f00 2f 6f 6c 3e 0a 0a 3c 68 32 20 6e 6f 6e 75 6d 62  /ol>..<h2 nonumb
11f10 65 72 20 74 61 67 73 3d 22 66 74 73 35 20 74 65  er tags="fts5 te
11f20 63 68 6e 69 63 61 6c 20 64 69 66 66 65 72 65 6e  chnical differen
11f30 63 65 73 22 3e 20 0a 20 20 53 75 6d 6d 61 72 79  ces"> .  Summary
11f40 20 6f 66 20 54 65 63 68 6e 69 63 61 6c 20 44 69   of Technical Di
11f50 66 66 65 72 65 6e 63 65 73 20 0a 3c 2f 68 32 3e  fferences .</h2>
11f60 0a 0a 3c 70 3e 46 54 53 35 20 69 73 20 73 69 6d  ..<p>FTS5 is sim
11f70 69 6c 61 72 20 74 6f 20 46 54 53 33 2f 34 20 69  ilar to FTS3/4 i
11f80 6e 20 74 68 61 74 20 74 68 65 20 70 72 69 6d 61  n that the prima
11f90 72 79 20 74 61 73 6b 20 6f 66 20 65 61 63 68 20  ry task of each 
11fa0 69 73 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 61  is to maintain.a
11fb0 6e 20 69 6e 64 65 78 20 6d 61 70 70 69 6e 67 20  n index mapping 
11fc0 66 72 6f 6d 20 65 61 63 68 20 75 6e 69 71 75 65  from each unique
11fd0 20 74 6f 6b 65 6e 20 74 6f 20 61 20 6c 69 73 74   token to a list
11fe0 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20 6f 66   of instances of
11ff0 20 74 68 61 74 20 74 6f 6b 65 6e 20 0a 77 69 74   that token .wit
12000 68 69 6e 20 61 20 73 65 74 20 6f 66 20 64 6f 63  hin a set of doc
12010 75 6d 65 6e 74 73 2c 20 77 68 65 72 65 20 65 61  uments, where ea
12020 63 68 20 69 6e 73 74 61 6e 63 65 20 69 73 20 69  ch instance is i
12030 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
12040 20 64 6f 63 75 6d 65 6e 74 20 0a 69 6e 20 77 68   document .in wh
12050 69 63 68 20 69 74 20 61 70 70 65 61 72 73 20 61  ich it appears a
12060 6e 64 20 69 74 73 20 70 6f 73 69 74 69 6f 6e 20  nd its position 
12070 77 69 74 68 69 6e 20 74 68 61 74 20 64 6f 63 75  within that docu
12080 6d 65 6e 74 2e 20 46 6f 72 20 65 78 61 6d 70 6c  ment. For exampl
12090 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
120a0 20 20 3c 69 3e 2d 2d 20 47 69 76 65 6e 20 74 68    <i>-- Given th
120b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 3a  e following SQL:
120c0 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
120d0 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
120e0 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 29 3b  SING fts5(a, b);
120f0 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66  .  INSERT INTO f
12100 74 28 72 6f 77 69 64 2c 20 61 2c 20 62 29 20 56  t(rowid, a, b) V
12110 41 4c 55 45 53 28 31 2c 20 27 58 20 59 27 2c 20  ALUES(1, 'X Y', 
12120 27 59 20 5a 27 29 3b 0a 20 20 49 4e 53 45 52 54  'Y Z');.  INSERT
12130 20 49 4e 54 4f 20 66 74 28 72 6f 77 69 64 2c 20   INTO ft(rowid, 
12140 61 2c 20 62 29 20 56 41 4c 55 45 53 28 32 2c 20  a, b) VALUES(2, 
12150 27 41 20 5a 27 2c 20 27 59 20 59 27 29 3b 0a 0a  'A Z', 'Y Y');..
12160 20 20 3c 69 3e 2d 2d 20 54 68 65 20 46 54 53 35    <i>-- The FTS5
12170 20 6d 6f 64 75 6c 65 20 63 72 65 61 74 65 73 20   module creates 
12180 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61  the following ma
12190 70 70 69 6e 67 20 6f 6e 20 64 69 73 6b 3a 3c 2f  pping on disk:</
121a0 69 3e 0a 20 20 41 20 2d 2d 26 67 74 3b 20 28 32  i>.  A --&gt; (2
121b0 2c 20 30 2c 20 30 29 0a 20 20 58 20 2d 2d 26 67  , 0, 0).  X --&g
121c0 74 3b 20 28 31 2c 20 30 2c 20 30 29 0a 20 20 59  t; (1, 0, 0).  Y
121d0 20 2d 2d 26 67 74 3b 20 28 31 2c 20 30 2c 20 31   --&gt; (1, 0, 1
121e0 29 20 28 31 2c 20 31 2c 20 30 29 20 28 32 2c 20  ) (1, 1, 0) (2, 
121f0 31 2c 20 30 29 20 28 32 2c 20 31 2c 20 31 29 0a  1, 0) (2, 1, 1).
12200 20 20 5a 20 2d 2d 26 67 74 3b 20 28 31 2c 20 31    Z --&gt; (1, 1
12210 2c 20 31 29 20 28 32 2c 20 30 2c 20 31 29 0a 3c  , 1) (2, 0, 1).<
12220 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
12230 49 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20 61  In the example a
12240 62 6f 76 65 2c 20 65 61 63 68 20 74 72 69 70 6c  bove, each tripl
12250 65 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  e identifies the
12260 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74   location of a t
12270 6f 6b 65 6e 0a 69 6e 73 74 61 6e 63 65 20 62 79  oken.instance by
12280 20 72 6f 77 69 64 2c 20 63 6f 6c 75 6d 6e 20 6e   rowid, column n
12290 75 6d 62 65 72 20 28 63 6f 6c 75 6d 6e 73 20 61  umber (columns a
122a0 72 65 20 6e 75 6d 62 65 72 65 64 20 73 65 71 75  re numbered sequ
122b0 65 6e 74 69 61 6c 6c 79 0a 73 74 61 72 74 69 6e  entially.startin
122c0 67 20 61 74 20 30 20 66 72 6f 6d 20 6c 65 66 74  g at 0 from left
122d0 20 74 6f 20 72 69 67 68 74 29 20 61 6e 64 20 70   to right) and p
122e0 6f 73 69 74 69 6f 6e 20 77 69 74 68 69 6e 20 74  osition within t
122f0 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20  he column value 
12300 28 74 68 65 0a 66 69 72 73 74 20 74 6f 6b 65 6e  (the.first token
12310 20 69 6e 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c   in a column val
12320 75 65 20 69 73 20 30 2c 20 74 68 65 20 73 65 63  ue is 0, the sec
12330 6f 6e 64 20 69 73 20 31 2c 20 61 6e 64 20 73 6f  ond is 1, and so
12340 20 6f 6e 29 2e 20 55 73 69 6e 67 20 74 68 69 73   on). Using this
12350 0a 69 6e 64 65 78 2c 20 46 54 53 35 20 69 73 20  .index, FTS5 is 
12360 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20  able to provide 
12370 74 69 6d 65 6c 79 20 61 6e 73 77 65 72 73 20 74  timely answers t
12380 6f 20 71 75 65 72 69 65 73 20 73 75 63 68 20 61  o queries such a
12390 73 20 22 74 68 65 20 73 65 74 0a 6f 66 20 61 6c  s "the set.of al
123a0 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68 61 74  l documents that
123b0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 74 6f 6b   contain the tok
123c0 65 6e 20 27 41 27 22 2c 20 6f 72 20 22 74 68 65  en 'A'", or "the
123d0 20 73 65 74 20 6f 66 20 61 6c 6c 20 64 6f 63 75   set of all docu
123e0 6d 65 6e 74 73 0a 74 68 61 74 20 63 6f 6e 74 61  ments.that conta
123f0 69 6e 20 74 68 65 20 73 65 71 75 65 6e 63 65 20  in the sequence 
12400 27 59 20 5a 27 22 2e 20 54 68 65 20 6c 69 73 74  'Y Z'". The list
12410 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20 61 73   of instances as
12420 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 0a  sociated with a.
12430 73 69 6e 67 6c 65 20 74 6f 6b 65 6e 20 69 73 20  single token is 
12440 63 61 6c 6c 65 64 20 61 6e 20 22 69 6e 73 74 61  called an "insta
12450 6e 63 65 2d 6c 69 73 74 22 2e 0a 0a 3c 70 3e 54  nce-list"...<p>T
12460 68 65 20 70 72 69 6e 63 69 70 6c 65 20 64 69 66  he principle dif
12470 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
12480 46 54 53 33 2f 34 20 61 6e 64 20 46 54 53 35 20  FTS3/4 and FTS5 
12490 69 73 20 74 68 61 74 20 69 6e 20 46 54 53 33 2f  is that in FTS3/
124a0 34 2c 0a 65 61 63 68 20 69 6e 73 74 61 6e 63 65  4,.each instance
124b0 2d 6c 69 73 74 20 69 73 20 73 74 6f 72 65 64 20  -list is stored 
124c0 61 73 20 61 20 73 69 6e 67 6c 65 20 6c 61 72 67  as a single larg
124d0 65 20 64 61 74 61 62 61 73 65 20 72 65 63 6f 72  e database recor
124e0 64 2c 20 77 68 65 72 65 61 73 0a 69 6e 20 46 54  d, whereas.in FT
124f0 53 35 20 6c 61 72 67 65 20 69 6e 73 74 61 6e 63  S5 large instanc
12500 65 2d 6c 69 73 74 73 20 61 72 65 20 64 69 76 69  e-lists are divi
12510 64 65 64 20 62 65 74 77 65 65 6e 20 6d 75 6c 74  ded between mult
12520 69 70 6c 65 20 64 61 74 61 62 61 73 65 20 72 65  iple database re
12530 63 6f 72 64 73 2e 0a 54 68 69 73 20 68 61 73 20  cords..This has 
12540 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6d  the following im
12550 70 6c 69 63 61 74 69 6f 6e 73 20 66 6f 72 20 64  plications for d
12560 65 61 6c 69 6e 67 20 77 69 74 68 20 6c 61 72 67  ealing with larg
12570 65 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  e databases that
12580 0a 63 6f 6e 74 61 69 6e 20 6c 61 72 67 65 20 6c  .contain large l
12590 69 73 74 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  ists:..<ul>.  <l
125a0 69 3e 20 3c 70 3e 46 54 53 35 20 69 73 20 61 62  i> <p>FTS5 is ab
125b0 6c 65 20 74 6f 20 6c 6f 61 64 20 69 6e 73 74 61  le to load insta
125c0 6e 63 65 2d 6c 69 73 74 73 20 69 6e 74 6f 20 6d  nce-lists into m
125d0 65 6d 6f 72 79 20 69 6e 63 72 65 6d 65 6e 74 61  emory incrementa
125e0 6c 6c 79 20 69 6e 0a 20 20 20 20 20 20 20 6f 72  lly in.       or
125f0 64 65 72 20 74 6f 20 72 65 64 75 63 65 20 6d 65  der to reduce me
12600 6d 6f 72 79 20 75 73 61 67 65 20 61 6e 64 20 70  mory usage and p
12610 65 61 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  eak allocation s
12620 69 7a 65 2e 20 46 54 53 33 2f 34 20 76 65 72 79  ize. FTS3/4 very
12630 0a 20 20 20 20 20 20 20 6f 66 74 65 6e 20 6c 6f  .       often lo
12640 61 64 73 20 65 6e 74 69 72 65 20 69 6e 73 74 61  ads entire insta
12650 6e 63 65 2d 6c 69 73 74 73 20 69 6e 74 6f 20 6d  nce-lists into m
12660 65 6d 6f 72 79 2e 0a 0a 20 20 3c 6c 69 3e 20 3c  emory...  <li> <
12670 70 3e 57 68 65 6e 20 70 72 6f 63 65 73 73 69 6e  p>When processin
12680 67 20 71 75 65 72 69 65 73 20 74 68 61 74 20 66  g queries that f
12690 65 61 74 75 72 65 20 6d 6f 72 65 20 74 68 61 6e  eature more than
126a0 20 6f 6e 65 20 74 6f 6b 65 6e 2c 20 46 54 53 35   one token, FTS5
126b0 20 69 73 0a 20 20 20 20 20 20 20 73 6f 6d 65 74   is.       somet
126c0 69 6d 65 73 20 61 62 6c 65 20 74 6f 20 64 65 74  imes able to det
126d0 65 72 6d 69 6e 65 20 74 68 61 74 20 74 68 65 20  ermine that the 
126e0 71 75 65 72 79 20 63 61 6e 20 62 65 20 61 6e 73  query can be ans
126f0 77 65 72 65 64 20 62 79 0a 20 20 20 20 20 20 20  wered by.       
12700 69 6e 73 70 65 63 74 69 6e 67 20 61 20 73 75 62  inspecting a sub
12710 73 65 74 20 6f 66 20 61 20 6c 61 72 67 65 20 69  set of a large i
12720 6e 73 74 61 6e 63 65 2d 6c 69 73 74 2e 20 46 54  nstance-list. FT
12730 53 33 2f 34 20 61 6c 6d 6f 73 74 20 61 6c 77 61  S3/4 almost alwa
12740 79 73 0a 20 20 20 20 20 20 20 68 61 73 20 74 6f  ys.       has to
12750 20 74 72 61 76 65 72 73 65 20 65 6e 74 69 72 65   traverse entire
12760 20 69 6e 73 74 61 6e 63 65 2d 6c 69 73 74 73 2e   instance-lists.
12770 0a 0a 20 20 3c 6c 69 3e 20 49 66 20 61 6e 20 69  ..  <li> If an i
12780 6e 73 74 61 6e 63 65 2d 6c 69 73 74 20 67 72 6f  nstance-list gro
12790 77 73 20 73 6f 20 6c 61 72 67 65 20 74 68 61 74  ws so large that
127a0 20 69 74 20 65 78 63 65 65 64 73 0a 20 20 20 20   it exceeds.    
127b0 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d     the [SQLITE_M
127c0 41 58 5f 4c 45 4e 47 54 48 5d 20 6c 69 6d 69 74  AX_LENGTH] limit
127d0 2c 20 46 54 53 33 2f 34 20 69 73 20 75 6e 61 62  , FTS3/4 is unab
127e0 6c 65 20 74 6f 20 68 61 6e 64 6c 65 20 69 74 2e  le to handle it.
127f0 20 46 54 53 35 0a 20 20 20 20 20 20 20 64 6f 65   FTS5.       doe
12800 73 20 6e 6f 74 20 68 61 76 65 20 74 68 69 73 20  s not have this 
12810 70 72 6f 62 6c 65 6d 2e 20 0a 3c 2f 75 6c 3e 0a  problem. .</ul>.
12820 0a 3c 70 3e 46 6f 72 20 74 68 65 73 65 20 72 65  .<p>For these re
12830 61 73 6f 6e 73 2c 20 6d 61 6e 79 20 63 6f 6d 70  asons, many comp
12840 6c 65 78 20 71 75 65 72 69 65 73 20 6d 61 79 20  lex queries may 
12850 75 73 65 20 6c 65 73 73 20 6d 65 6d 6f 72 79 20  use less memory 
12860 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 0a  and run faster .
12870 75 73 69 6e 67 20 46 54 53 35 2e 0a 0a 3c 70 3e  using FTS5...<p>
12880 53 6f 6d 65 20 6f 74 68 65 72 20 77 61 79 73 20  Some other ways 
12890 69 6e 20 77 68 69 63 68 20 46 54 53 35 20 64 69  in which FTS5 di
128a0 66 66 65 72 73 20 66 72 6f 6d 20 46 54 53 33 2f  ffers from FTS3/
128b0 34 20 61 72 65 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c  4 are:..<ul>.  <
128c0 6c 69 3e 20 3c 70 3e 46 54 53 35 20 73 75 70 70  li> <p>FTS5 supp
128d0 6f 72 74 73 20 22 4f 52 44 45 52 20 42 59 20 72  orts "ORDER BY r
128e0 61 6e 6b 22 20 66 6f 72 20 72 65 74 75 72 6e 69  ank" for returni
128f0 6e 67 20 72 65 73 75 6c 74 73 20 69 6e 20 6f 72  ng results in or
12900 64 65 72 20 6f 66 0a 20 20 20 20 20 20 20 64 65  der of.       de
12910 63 72 65 61 73 69 6e 67 20 72 65 6c 65 76 61 6e  creasing relevan
12920 63 79 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 46  cy...  <li> <p>F
12930 54 53 35 20 66 65 61 74 75 72 65 73 20 61 6e 20  TS5 features an 
12940 41 50 49 20 61 6c 6c 6f 77 69 6e 67 20 75 73 65  API allowing use
12950 72 73 20 74 6f 20 63 72 65 61 74 65 20 63 75 73  rs to create cus
12960 74 6f 6d 20 61 75 78 69 6c 69 61 72 79 20 0a 20  tom auxiliary . 
12970 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 73 20        functions 
12980 66 6f 72 20 61 64 76 61 6e 63 65 64 20 72 61 6e  for advanced ran
12990 6b 69 6e 67 20 61 6e 64 20 74 65 78 74 20 70 72  king and text pr
129a0 6f 63 65 73 73 69 6e 67 20 61 70 70 6c 69 63 61  ocessing applica
129b0 74 69 6f 6e 73 2e 20 54 68 65 0a 20 20 20 20 20  tions. The.     
129c0 20 20 73 70 65 63 69 61 6c 20 22 72 61 6e 6b 22    special "rank"
129d0 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 62 65 20 6d   column may be m
129e0 61 70 70 65 64 20 74 6f 20 61 20 63 75 73 74 6f  apped to a custo
129f0 6d 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  m auxiliary func
12a00 74 69 6f 6e 0a 20 20 20 20 20 20 20 73 6f 20 74  tion.       so t
12a10 68 61 74 20 61 64 64 69 6e 67 20 22 4f 52 44 45  hat adding "ORDE
12a20 52 20 42 59 20 72 61 6e 6b 22 20 74 6f 20 61 20  R BY rank" to a 
12a30 71 75 65 72 79 20 77 6f 72 6b 73 20 61 73 20 65  query works as e
12a40 78 70 65 63 74 65 64 2e 0a 0a 20 20 3c 6c 69 3e  xpected...  <li>
12a50 20 3c 70 3e 46 54 53 35 20 72 65 63 6f 67 6e 69   <p>FTS5 recogni
12a60 7a 65 73 20 75 6e 69 63 6f 64 65 20 73 65 70 61  zes unicode sepa
12a70 72 61 74 6f 72 20 63 68 61 72 61 63 74 65 72 73  rator characters
12a80 20 61 6e 64 20 63 61 73 65 20 65 71 75 69 76 61   and case equiva
12a90 6c 65 6e 63 65 20 62 79 0a 20 20 20 20 20 20 20  lence by.       
12aa0 64 65 66 61 75 6c 74 2e 20 54 68 69 73 20 69 73  default. This is
12ab0 20 61 6c 73 6f 20 70 6f 73 73 69 62 6c 65 20 75   also possible u
12ac0 73 69 6e 67 20 46 54 53 33 2f 34 2c 20 62 75 74  sing FTS3/4, but
12ad0 20 6d 75 73 74 20 62 65 20 65 78 70 6c 69 63 69   must be explici
12ae0 74 6c 79 0a 20 20 20 20 20 20 20 65 6e 61 62 6c  tly.       enabl
12af0 65 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 54  ed...  <li> <p>T
12b00 68 65 20 71 75 65 72 79 20 73 79 6e 74 61 78 20  he query syntax 
12b10 68 61 73 20 62 65 65 6e 20 72 65 76 69 73 65 64  has been revised
12b20 20 77 68 65 72 65 20 6e 65 63 65 73 73 61 72 79   where necessary
12b30 20 74 6f 20 72 65 6d 6f 76 65 0a 20 20 20 20 20   to remove.     
12b40 20 20 61 6d 62 69 67 75 69 74 69 65 73 20 61 6e    ambiguities an
12b50 64 20 74 6f 20 6d 61 6b 65 20 69 74 20 70 6f 73  d to make it pos
12b60 73 69 62 6c 65 20 74 6f 20 65 73 63 61 70 65 20  sible to escape 
12b70 73 70 65 63 69 61 6c 20 63 68 61 72 61 63 74 65  special characte
12b80 72 73 0a 20 20 20 20 20 20 20 69 6e 20 71 75 65  rs.       in que
12b90 72 79 20 74 65 72 6d 73 2e 0a 0a 20 20 3c 6c 69  ry terms...  <li
12ba0 3e 20 3c 70 3e 42 79 20 64 65 66 61 75 6c 74 2c  > <p>By default,
12bb0 20 46 54 53 33 2f 34 20 6f 63 63 61 73 69 6f 6e   FTS3/4 occasion
12bc0 61 6c 6c 79 20 6d 65 72 67 65 73 20 74 6f 67 65  ally merges toge
12bd0 74 68 65 72 20 74 77 6f 20 6f 72 20 6d 6f 72 65  ther two or more
12be0 20 6f 66 20 74 68 65 0a 20 20 20 20 20 20 20 62   of the.       b
12bf0 2d 74 72 65 65 73 20 74 68 61 74 20 6d 61 6b 65  -trees that make
12c00 20 75 70 20 69 74 73 20 66 75 6c 6c 2d 74 65 78   up its full-tex
12c10 74 20 69 6e 64 65 78 20 77 69 74 68 69 6e 20 61  t index within a
12c20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
12c30 20 6f 72 0a 20 20 20 20 20 20 20 44 45 4c 45 54   or.       DELET
12c40 45 20 73 74 61 74 65 6d 65 6e 74 20 65 78 65 63  E statement exec
12c50 75 74 65 64 20 62 79 20 74 68 65 20 75 73 65 72  uted by the user
12c60 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61  . This means tha
12c70 74 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 0a  t any operation.
12c80 20 20 20 20 20 20 20 6f 6e 20 61 6e 20 46 54 53         on an FTS
12c90 33 2f 34 20 74 61 62 6c 65 20 6d 61 79 20 74 75  3/4 table may tu
12ca0 72 6e 20 6f 75 74 20 74 6f 20 62 65 20 73 75 72  rn out to be sur
12cb0 70 72 69 73 69 6e 67 6c 79 20 73 6c 6f 77 2c 20  prisingly slow, 
12cc0 61 73 20 46 54 53 33 2f 34 20 0a 20 20 20 20 20  as FTS3/4 .     
12cd0 20 20 6d 61 79 20 75 6e 70 72 65 64 69 63 74 61    may unpredicta
12ce0 62 6c 79 20 63 68 6f 6f 73 65 20 74 6f 20 6d 65  bly choose to me
12cf0 72 67 65 20 74 6f 67 65 74 68 65 72 20 74 77 6f  rge together two
12d00 20 6f 72 20 6d 6f 72 65 20 6c 61 72 67 65 20 62   or more large b
12d10 2d 74 72 65 65 73 0a 20 20 20 20 20 20 20 77 69  -trees.       wi
12d20 74 68 69 6e 20 69 74 2e 20 46 54 53 35 20 75 73  thin it. FTS5 us
12d30 65 73 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 6d  es incremental m
12d40 65 72 67 69 6e 67 20 62 79 20 64 65 66 61 75 6c  erging by defaul
12d50 74 2c 20 77 68 69 63 68 20 6c 69 6d 69 74 73 0a  t, which limits.
12d60 20 20 20 20 20 20 20 74 68 65 20 61 6d 6f 75 6e         the amoun
12d70 74 20 6f 66 20 70 72 6f 63 65 73 73 69 6e 67 20  t of processing 
12d80 74 68 61 74 20 6d 61 79 20 74 61 6b 65 20 70 6c  that may take pl
12d90 61 63 65 20 77 69 74 68 69 6e 20 61 6e 79 20 67  ace within any g
12da0 69 76 65 6e 20 0a 20 20 20 20 20 20 20 49 4e 53  iven .       INS
12db0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
12dc0 45 4c 45 54 45 20 6f 70 65 72 61 74 69 6f 6e 2e  ELETE operation.
12dd0 0a 3c 2f 75 6c 3e 0a                             .</ul>.