Documentation Source Text

Hex Artifact Content
Login

Artifact 1ec0cb808ed82e16de7ca94c0678e9b93a0f03d2:


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: 31 3e 4f 76 65 72 76 69 65 77 20 6f 66 20 46 54  1>Overview of FT
0070: 53 35 3c 2f 68 31 3e 0a 0a 3c 70 3e 46 54 53 35  S5</h1>..<p>FTS5
0080: 20 69 73 20 61 6e 20 53 51 4c 69 74 65 20 5b 76   is an SQLite [v
0090: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
00a0: 75 6c 65 5d 20 74 68 61 74 20 70 72 6f 76 69 64  ule] that provid
00b0: 65 73 20 0a 3c 61 20 68 72 65 66 3d 68 74 74 70  es .<a href=http
00c0: 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e  ://en.wikipedia.
00d0: 6f 72 67 2f 77 69 6b 69 2f 46 75 6c 6c 5f 74 65  org/wiki/Full_te
00e0: 78 74 5f 73 65 61 72 63 68 3e 66 75 6c 6c 2d 74  xt_search>full-t
00f0: 65 78 74 20 73 65 61 72 63 68 3c 2f 61 3e 0a 66  ext search</a>.f
0100: 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 74 6f 20  unctionality to 
0110: 64 61 74 61 62 61 73 65 20 61 70 70 6c 69 63 61  database applica
0120: 74 69 6f 6e 73 2e 20 49 6e 20 74 68 65 69 72 20  tions. In their 
0130: 6d 6f 73 74 20 65 6c 65 6d 65 6e 74 61 72 79 20  most elementary 
0140: 66 6f 72 6d 2c 20 0a 66 75 6c 6c 2d 74 65 78 74  form, .full-text
0150: 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 73 20   search engines 
0160: 61 6c 6c 6f 77 20 74 68 65 20 75 73 65 72 20 74  allow the user t
0170: 6f 20 65 66 66 69 63 69 65 6e 74 6c 79 20 73 65  o efficiently se
0180: 61 72 63 68 20 61 20 6c 61 72 67 65 20 0a 63 6f  arch a large .co
0190: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 64 6f 63 75  llection of docu
01a0: 6d 65 6e 74 73 20 66 6f 72 20 74 68 65 20 73 75  ments for the su
01b0: 62 73 65 74 20 74 68 61 74 20 63 6f 6e 74 61 69  bset that contai
01c0: 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 69 6e  n one or more in
01d0: 73 74 61 6e 63 65 73 20 6f 66 20 61 0a 73 65 61  stances of a.sea
01e0: 72 63 68 20 74 65 72 6d 2e 20 54 68 65 20 73 65  rch term. The se
01f0: 61 72 63 68 20 66 75 6e 63 74 69 6f 6e 61 6c 69  arch functionali
0200: 74 79 20 70 72 6f 76 69 64 65 64 20 74 6f 20 77  ty provided to w
0210: 6f 72 6c 64 20 77 69 64 65 20 77 65 62 20 75 73  orld wide web us
0220: 65 72 73 20 62 79 0a 3c 61 20 68 72 65 66 3d 77  ers by.<a href=w
0230: 77 77 2e 67 6f 6f 67 6c 65 2e 63 6f 6d 3e 47 6f  ww.google.com>Go
0240: 6f 67 6c 65 3c 2f 61 3e 20 69 73 2c 20 61 6d 6f  ogle</a> is, amo
0250: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
0260: 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61   a full-text sea
0270: 72 63 68 0a 65 6e 67 69 6e 65 2c 20 61 73 20 69  rch.engine, as i
0280: 74 20 61 6c 6c 6f 77 73 20 75 73 65 72 73 20 74  t allows users t
0290: 6f 20 73 65 61 72 63 68 20 66 6f 72 20 61 6c 6c  o search for all
02a0: 20 64 6f 63 75 6d 65 6e 74 73 20 6f 6e 20 74 68   documents on th
02b0: 65 20 77 65 62 20 74 68 61 74 20 63 6f 6e 74 61  e web that conta
02c0: 69 6e 2c 0a 66 6f 72 20 65 78 61 6d 70 6c 65 2c  in,.for example,
02d0: 20 74 68 65 20 74 65 72 6d 20 22 66 74 73 35 22   the term "fts5"
02e0: 2e 0a 0a 3c 70 3e 54 6f 20 75 73 65 20 46 54 53  ...<p>To use FTS
02f0: 35 2c 20 74 68 65 20 75 73 65 72 20 63 72 65 61  5, the user crea
0300: 74 65 73 20 61 6e 20 46 54 53 35 20 76 69 72 74  tes an FTS5 virt
0310: 75 61 6c 20 74 61 62 6c 65 20 77 69 74 68 20 6f  ual table with o
0320: 6e 65 20 6f 72 20 6d 6f 72 65 0a 63 6f 6c 75 6d  ne or more.colum
0330: 6e 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  ns. For example:
0340: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
0350: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
0360: 41 42 4c 45 20 65 6d 61 69 6c 20 55 53 49 4e 47  ABLE email USING
0370: 20 66 74 73 35 28 73 65 6e 64 65 72 2c 20 74 69   fts5(sender, ti
0380: 74 6c 65 2c 20 62 6f 64 79 29 3b 0a 3c 2f 63 6f  tle, body);.</co
0390: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 74 20  deblock>..<p>It 
03a0: 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 61  is an error to a
03b0: 64 64 20 74 79 70 65 73 2c 20 63 6f 6e 73 74 72  dd types, constr
03c0: 61 69 6e 74 73 20 6f 72 20 5b 50 52 49 4d 41 52  aints or [PRIMAR
03d0: 59 20 4b 45 59 5d 20 64 65 63 6c 61 72 61 74 69  Y KEY] declarati
03e0: 6f 6e 73 20 74 6f 20 0a 61 20 43 52 45 41 54 45  ons to .a CREATE
03f0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73   VIRTUAL TABLE s
0400: 74 61 74 65 6d 65 6e 74 20 75 73 65 64 20 74 6f  tatement used to
0410: 20 63 72 65 61 74 65 20 61 6e 20 46 54 53 35 20   create an FTS5 
0420: 74 61 62 6c 65 2e 20 4f 6e 63 65 20 63 72 65 61  table. Once crea
0430: 74 65 64 2c 0a 61 6e 20 46 54 53 35 20 74 61 62  ted,.an FTS5 tab
0440: 6c 65 20 6d 61 79 20 62 65 20 70 6f 70 75 6c 61  le may be popula
0450: 74 65 64 20 75 73 69 6e 67 20 5b 49 4e 53 45 52  ted using [INSER
0460: 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
0470: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
0480: 6e 74 73 0a 6c 69 6b 65 20 61 6e 79 20 6f 74 68  nts.like any oth
0490: 65 72 20 74 61 62 6c 65 2e 20 4c 69 6b 65 20 61  er table. Like a
04a0: 6e 79 20 6f 74 68 65 72 20 74 61 62 6c 65 20 77  ny other table w
04b0: 69 74 68 20 6e 6f 20 50 52 49 4d 41 52 59 20 4b  ith no PRIMARY K
04c0: 45 59 20 64 65 63 6c 61 72 61 74 69 6f 6e 2c 20  EY declaration, 
04d0: 61 6e 0a 46 54 53 35 20 74 61 62 6c 65 20 68 61  an.FTS5 table ha
04e0: 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 49 4e  s an implicit IN
04f0: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
0500: 59 20 66 69 65 6c 64 20 6e 61 6d 65 64 20 72 6f  Y field named ro
0510: 77 69 64 2e 20 0a 0a 3c 70 3e 4e 6f 74 20 73 68  wid. ..<p>Not sh
0520: 6f 77 6e 20 69 6e 20 74 68 65 20 65 78 61 6d 70  own in the examp
0530: 6c 65 20 61 62 6f 76 65 20 69 73 20 74 68 61 74  le above is that
0540: 20 74 68 65 72 65 20 61 72 65 20 61 6c 73 6f 20   there are also 
0550: 0a 5b 46 54 53 35 20 43 52 45 41 54 45 20 54 41  .[FTS5 CREATE TA
0560: 42 4c 45 20 4f 70 74 69 6f 6e 73 20 7c 20 76 61  BLE Options | va
0570: 72 69 6f 75 73 20 6f 70 74 69 6f 6e 73 5d 20 74  rious options] t
0580: 68 61 74 20 6d 61 79 20 62 65 20 70 72 6f 76 69  hat may be provi
0590: 64 65 64 20 74 6f 20 46 54 53 35 20 61 73 0a 70  ded to FTS5 as.p
05a0: 61 72 74 20 6f 66 20 74 68 65 20 43 52 45 41 54  art of the CREAT
05b0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
05c0: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
05d0: 66 69 67 75 72 65 20 76 61 72 69 6f 75 73 20 61  figure various a
05e0: 73 70 65 63 74 73 20 6f 66 20 74 68 65 0a 6e 65  spects of the.ne
05f0: 77 20 74 61 62 6c 65 2e 20 54 68 65 73 65 20 6d  w table. These m
0600: 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 6d 6f  ay be used to mo
0610: 64 69 66 79 20 74 68 65 20 77 61 79 20 69 6e 20  dify the way in 
0620: 77 68 69 63 68 20 74 68 65 20 46 54 53 35 20 74  which the FTS5 t
0630: 61 62 6c 65 20 65 78 74 72 61 63 74 73 0a 74 65  able extracts.te
0640: 72 6d 73 20 66 72 6f 6d 20 64 6f 63 75 6d 65 6e  rms from documen
0650: 74 73 20 61 6e 64 20 71 75 65 72 69 65 73 2c 20  ts and queries, 
0660: 74 6f 20 63 72 65 61 74 65 20 65 78 74 72 61 20  to create extra 
0670: 69 6e 64 65 78 65 73 20 6f 6e 20 64 69 73 6b 20  indexes on disk 
0680: 74 6f 20 73 70 65 65 64 20 75 70 0a 70 72 65 66  to speed up.pref
0690: 69 78 20 71 75 65 72 69 65 73 2c 20 6f 72 20 74  ix queries, or t
06a0: 6f 20 63 72 65 61 74 65 20 61 6e 20 46 54 53 35  o create an FTS5
06b0: 20 74 61 62 6c 65 20 74 68 61 74 20 61 63 74 73   table that acts
06c0: 20 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 6e 20   as an index on 
06d0: 63 6f 6e 74 65 6e 74 0a 73 74 6f 72 65 64 20 65  content.stored e
06e0: 6c 73 65 77 68 65 72 65 2e 0a 0a 3c 70 3e 4f 6e  lsewhere...<p>On
06f0: 63 65 20 70 6f 70 75 6c 61 74 65 64 2c 20 74 68  ce populated, th
0700: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 77 61  ere are three wa
0710: 79 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 20  ys to execute a 
0720: 66 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 20  full-text query 
0730: 61 67 61 69 6e 73 74 0a 74 68 65 20 63 6f 6e 74  against.the cont
0740: 65 6e 74 73 20 6f 66 20 61 6e 20 46 54 53 35 20  ents of an FTS5 
0750: 74 61 62 6c 65 3a 0a 0a 3c 75 6c 3e 3c 6c 69 3e  table:..<ul><li>
0760: 20 55 73 69 6e 67 20 61 20 4d 41 54 43 48 20 6f   Using a MATCH o
0770: 70 65 72 61 74 6f 72 20 69 6e 20 74 68 65 20 57  perator in the W
0780: 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 20 61  HERE clause of a
0790: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
07a0: 74 2c 20 6f 72 0a 20 20 20 20 3c 6c 69 3e 20 55  t, or.    <li> U
07b0: 73 69 6e 67 20 61 6e 20 65 71 75 61 6c 73 20 28  sing an equals (
07c0: 22 3d 22 29 20 6f 70 65 72 61 74 6f 72 20 69 6e  "=") operator in
07d0: 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
07e0: 65 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  e of a SELECT st
07f0: 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 20 20 20 20  atement, or.    
0800: 3c 6c 69 3e 20 75 73 69 6e 67 20 74 68 65 20 5b  <li> using the [
0810: 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
0820: 63 74 69 6f 6e 5d 20 73 79 6e 74 61 78 2e 0a 3c  ction] syntax..<
0830: 2f 75 6c 3e 0a 0a 3c 70 3e 49 66 20 75 73 69 6e  /ul>..<p>If usin
0840: 67 20 74 68 65 20 4d 41 54 43 48 20 6f 72 20 3d  g the MATCH or =
0850: 20 6f 70 65 72 61 74 6f 72 73 2c 20 74 68 65 20   operators, the 
0860: 65 78 70 72 65 73 73 69 6f 6e 20 74 6f 20 74 68  expression to th
0870: 65 20 6c 65 66 74 20 6f 66 20 74 68 65 20 4d 41  e left of the MA
0880: 54 43 48 0a 20 20 20 6f 70 65 72 61 74 6f 72 20  TCH.   operator 
0890: 6d 75 73 74 20 62 65 20 74 68 65 20 6e 61 6d 65  must be the name
08a0: 20 6f 66 20 74 68 65 20 46 54 53 35 20 74 61 62   of the FTS5 tab
08b0: 6c 65 2e 20 54 68 65 20 65 78 70 72 65 73 73 69  le. The expressi
08c0: 6f 6e 20 6f 6e 20 74 68 65 20 72 69 67 68 74 0a  on on the right.
08d0: 20 20 20 6d 75 73 74 20 62 65 20 61 20 74 65 78     must be a tex
08e0: 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 79 69  t value specifyi
08f0: 6e 67 20 74 68 65 20 74 65 72 6d 20 74 6f 20 73  ng the term to s
0900: 65 61 72 63 68 20 66 6f 72 2e 20 46 6f 72 20 74  earch for. For t
0910: 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 0a  he table-valued.
0920: 20 20 20 66 75 6e 63 74 69 6f 6e 20 73 79 6e 74     function synt
0930: 61 78 2c 20 74 68 65 20 74 65 72 6d 20 74 6f 20  ax, the term to 
0940: 73 65 61 72 63 68 20 66 6f 72 20 69 73 20 73 70  search for is sp
0950: 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
0960: 69 72 73 74 20 74 61 62 6c 65 20 61 72 67 75 6d  irst table argum
0970: 65 6e 74 2e 0a 20 20 20 46 6f 72 20 65 78 61 6d  ent..   For exam
0980: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
0990: 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20  >.  <i>-- Query 
09a0: 66 6f 72 20 61 6c 6c 20 72 6f 77 73 20 74 68 61  for all rows tha
09b0: 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61  t contain at lea
09c0: 73 74 20 6f 6e 63 65 20 69 6e 73 74 61 6e 63 65  st once instance
09d0: 20 6f 66 20 74 68 65 20 74 65 72 6d 3c 2f 69 3e   of the term</i>
09e0: 0a 20 20 3c 69 3e 2d 2d 20 22 66 74 73 35 22 20  .  <i>-- "fts5" 
09f0: 28 69 6e 20 61 6e 79 20 63 6f 6c 75 6d 6e 29 2e  (in any column).
0a00: 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
0a10: 68 72 65 65 20 71 75 65 72 69 65 73 20 61 72 65  hree queries are
0a20: 20 65 71 75 69 76 61 6c 65 6e 74 2e 3c 2f 69 3e   equivalent.</i>
0a30: 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d  .  SELECT * FROM
0a40: 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65 6d 61   email WHERE ema
0a50: 69 6c 20 4d 41 54 43 48 20 27 66 74 73 35 27 3b  il MATCH 'fts5';
0a60: 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d  .  SELECT * FROM
0a70: 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65 6d 61   email WHERE ema
0a80: 69 6c 20 3d 20 27 66 74 73 35 27 3b 0a 20 20 53  il = 'fts5';.  S
0a90: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 65 6d 61  ELECT * FROM ema
0aa0: 69 6c 28 27 66 74 73 35 27 29 3b 0a 3c 2f 63 6f  il('fts5');.</co
0ab0: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 42 79  deblock>..<p> By
0ac0: 20 64 65 66 61 75 6c 74 2c 20 46 54 53 35 20 66   default, FTS5 f
0ad0: 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 65  ull-text searche
0ae0: 73 20 61 72 65 20 63 61 73 65 2d 69 6e 64 65 70  s are case-indep
0af0: 65 6e 64 65 6e 74 2e 20 4c 69 6b 65 20 61 6e 79  endent. Like any
0b00: 20 6f 74 68 65 72 0a 53 51 4c 20 71 75 65 72 79   other.SQL query
0b10: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
0b20: 6f 6e 74 61 69 6e 20 61 6e 20 4f 52 44 45 52 20  ontain an ORDER 
0b30: 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 20 65  BY clause, the e
0b40: 78 61 6d 70 6c 65 20 61 62 6f 76 65 20 72 65 74  xample above ret
0b50: 75 72 6e 73 0a 72 65 73 75 6c 74 73 20 69 6e 20  urns.results in 
0b60: 61 6e 20 61 72 62 69 74 72 61 72 79 20 6f 72 64  an arbitrary ord
0b70: 65 72 2e 20 54 6f 20 73 6f 72 74 20 72 65 73 75  er. To sort resu
0b80: 6c 74 73 20 62 79 20 72 65 6c 65 76 61 6e 63 65  lts by relevance
0b90: 20 28 6d 6f 73 74 20 74 6f 20 6c 65 61 73 74 0a   (most to least.
0ba0: 72 65 6c 65 76 61 6e 74 29 2c 20 61 6e 20 4f 52  relevant), an OR
0bb0: 44 45 52 20 42 59 20 6d 61 79 20 62 65 20 61 64  DER BY may be ad
0bc0: 64 65 64 20 74 6f 20 61 20 66 75 6c 6c 2d 74 65  ded to a full-te
0bd0: 78 74 20 71 75 65 72 79 20 61 73 20 66 6f 6c 6c  xt query as foll
0be0: 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ows:..<codeblock
0bf0: 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20  >.  <i>-- Query 
0c00: 66 6f 72 20 61 6c 6c 20 72 6f 77 73 20 74 68 61  for all rows tha
0c10: 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65 61  t contain at lea
0c20: 73 74 20 6f 6e 63 65 20 69 6e 73 74 61 6e 63 65  st once instance
0c30: 20 6f 66 20 74 68 65 20 74 65 72 6d 3c 2f 69 3e   of the term</i>
0c40: 0a 20 20 3c 69 3e 2d 2d 20 22 66 74 73 35 22 20  .  <i>-- "fts5" 
0c50: 28 69 6e 20 61 6e 79 20 63 6f 6c 75 6d 6e 29 2e  (in any column).
0c60: 20 52 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   Return results 
0c70: 69 6e 20 6f 72 64 65 72 20 66 72 6f 6d 20 62 65  in order from be
0c80: 73 74 20 74 6f 20 77 6f 72 73 74 3c 2f 69 3e 0a  st to worst</i>.
0c90: 20 20 3c 69 3e 2d 2d 20 6d 61 74 63 68 2e 20 20    <i>-- match.  
0ca0: 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20  </i>.  SELECT * 
0cb0: 46 52 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52 45  FROM email WHERE
0cc0: 20 65 6d 61 69 6c 20 4d 41 54 43 48 20 27 66 74   email MATCH 'ft
0cd0: 73 35 27 20 4f 52 44 45 52 20 42 59 20 72 61 6e  s5' ORDER BY ran
0ce0: 6b 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  k;.</codeblock>.
0cf0: 0a 3c 70 3e 20 41 73 20 77 65 6c 6c 20 61 73 20  .<p> As well as 
0d00: 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  the column value
0d10: 73 20 61 6e 64 20 72 6f 77 69 64 20 6f 66 20 61  s and rowid of a
0d20: 20 6d 61 74 63 68 69 6e 67 20 72 6f 77 2c 20 61   matching row, a
0d30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 6d 61  n application.ma
0d40: 79 20 75 73 65 20 5b 46 54 53 35 20 61 75 78 69  y use [FTS5 auxi
0d50: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 5d  liary functions]
0d60: 20 74 6f 20 72 65 74 72 69 65 76 65 20 65 78 74   to retrieve ext
0d70: 72 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 72  ra information r
0d80: 65 67 61 72 64 69 6e 67 0a 74 68 65 20 6d 61 74  egarding.the mat
0d90: 63 68 65 64 20 72 6f 77 2e 20 46 6f 72 20 65 78  ched row. For ex
0da0: 61 6d 70 6c 65 2c 20 61 6e 20 61 75 78 69 6c 69  ample, an auxili
0db0: 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ary function may
0dc0: 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
0dd0: 69 65 76 65 0a 61 20 63 6f 70 79 20 6f 66 20 61  ieve.a copy of a
0de0: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 66 6f   column value fo
0df0: 72 20 61 20 6d 61 74 63 68 65 64 20 72 6f 77 20  r a matched row 
0e00: 77 69 74 68 20 61 6c 6c 20 69 6e 73 74 61 6e 63  with all instanc
0e10: 65 73 20 6f 66 20 74 68 65 20 6d 61 74 63 68 65  es of the matche
0e20: 64 0a 74 65 72 6d 20 73 75 72 72 6f 75 6e 64 65  d.term surrounde
0e30: 64 20 62 79 20 68 74 6d 6c 20 26 6c 74 3b 62 26  d by html &lt;b&
0e40: 67 74 3b 26 6c 74 3b 2f 62 26 67 74 3b 20 74 61  gt;&lt;/b&gt; ta
0e50: 67 73 2e 20 41 75 78 69 6c 69 61 72 79 20 66 75  gs. Auxiliary fu
0e60: 6e 63 74 69 6f 6e 73 20 61 72 65 0a 69 6e 76 6f  nctions are.invo
0e70: 6b 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ked in the same 
0e80: 77 61 79 20 61 73 20 53 51 4c 69 74 65 20 5b 63  way as SQLite [c
0e90: 6f 72 65 66 75 6e 63 20 7c 20 73 63 61 6c 61 72  orefunc | scalar
0ea0: 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 20 65 78 63   functions], exc
0eb0: 65 70 74 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ept that the nam
0ec0: 65 0a 6f 66 20 74 68 65 20 46 54 53 35 20 74 61  e.of the FTS5 ta
0ed0: 62 6c 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ble is specified
0ee0: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
0ef0: 67 75 6d 65 6e 74 2e 20 46 6f 72 20 65 78 61 6d  gument. For exam
0f00: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
0f10: 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 20  >.  <i>-- Query 
0f20: 66 6f 72 20 72 6f 77 73 20 74 68 61 74 20 6d 61  for rows that ma
0f30: 74 63 68 20 22 66 74 73 35 22 2e 20 52 65 74 75  tch "fts5". Retu
0f40: 72 6e 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  rn a copy of the
0f50: 20 22 62 6f 64 79 22 20 63 6f 6c 75 6d 6e 3c 2f   "body" column</
0f60: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 66 20 65 61  i>.  <i>-- of ea
0f70: 63 68 20 72 6f 77 20 77 69 74 68 20 74 68 65 20  ch row with the 
0f80: 6d 61 74 63 68 65 73 20 73 75 72 72 6f 75 6e 64  matches surround
0f90: 65 64 20 62 79 20 26 6c 74 3b 62 26 67 74 3b 26  ed by &lt;b&gt;&
0fa0: 6c 74 3b 2f 62 26 67 74 3b 20 74 61 67 73 2e 3c  lt;/b&gt; tags.<
0fb0: 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 68 69 67  /i>.  SELECT hig
0fc0: 68 6c 69 67 68 74 28 65 6d 61 69 6c 2c 20 32 2c  hlight(email, 2,
0fd0: 20 27 26 6c 74 3b 62 26 67 74 3b 27 2c 20 27 26   '&lt;b&gt;', '&
0fe0: 6c 74 3b 2f 62 26 67 74 3b 27 29 20 46 52 4f 4d  lt;/b&gt;') FROM
0ff0: 20 65 6d 61 69 6c 28 27 66 74 73 35 27 29 3b 0a   email('fts5');.
1000: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
1010: 3e 41 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  >A description o
1020: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
1030: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
1040: 6f 6e 73 2c 20 61 6e 64 20 6d 6f 72 65 20 64 65  ons, and more de
1050: 74 61 69 6c 73 0a 72 65 67 61 72 64 69 6e 67 20  tails.regarding 
1060: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
1070: 20 74 68 65 20 73 70 65 63 69 61 6c 20 22 72 61   the special "ra
1080: 6e 6b 22 20 63 6f 6c 75 6d 6e 2c 20 61 72 65 20  nk" column, are 
1090: 0a 5b 46 54 53 35 20 61 75 78 69 6c 69 61 72 79  .[FTS5 auxiliary
10a0: 20 66 75 6e 63 74 69 6f 6e 73 20 7c 20 61 76 61   functions | ava
10b0: 69 6c 61 62 6c 65 20 62 65 6c 6f 77 5d 2e 20 5b  ilable below]. [
10c0: 46 54 53 35 20 63 75 73 74 6f 6d 20 61 75 78 69  FTS5 custom auxi
10d0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 7c  liary functions|
10e0: 0a 43 75 73 74 6f 6d 20 61 75 78 69 6c 69 61 72  .Custom auxiliar
10f0: 79 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6d 61 79  y functions] may
1100: 20 61 6c 73 6f 20 62 65 20 69 6d 70 6c 65 6d 65   also be impleme
1110: 6e 74 65 64 20 69 6e 20 43 20 61 6e 64 20 72 65  nted in C and re
1120: 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 46 54  gistered with.FT
1130: 53 35 2c 20 6a 75 73 74 20 61 73 20 63 75 73 74  S5, just as cust
1140: 6f 6d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  om SQL functions
1150: 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
1160: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 69  ed with the SQLi
1170: 74 65 20 63 6f 72 65 2e 0a 0a 3c 70 3e 20 41 73  te core...<p> As
1180: 20 77 65 6c 6c 20 61 73 20 73 65 61 72 63 68 69   well as searchi
1190: 6e 67 20 66 6f 72 20 61 6c 6c 20 72 6f 77 73 20  ng for all rows 
11a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 20 74  that contain a t
11b0: 65 72 6d 2c 20 46 54 53 35 20 61 6c 6c 6f 77 73  erm, FTS5 allows
11c0: 20 0a 74 68 65 20 75 73 65 72 20 74 6f 20 73 65   .the user to se
11d0: 61 72 63 68 20 66 6f 72 20 72 6f 77 73 20 74 68  arch for rows th
11e0: 61 74 20 63 6f 6e 74 61 69 6e 3a 0a 0a 3c 75 6c  at contain:..<ul
11f0: 3e 0a 20 20 3c 6c 69 3e 20 61 6e 79 20 74 65 72  >.  <li> any ter
1200: 6d 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  ms that begin wi
1210: 74 68 20 61 20 73 70 65 63 69 66 69 65 64 20 70  th a specified p
1220: 72 65 66 69 78 2c 0a 20 20 3c 6c 69 3e 20 22 70  refix,.  <li> "p
1230: 68 72 61 73 65 73 22 20 2d 20 73 65 71 75 65 6e  hrases" - sequen
1240: 63 65 73 20 6f 66 20 74 65 72 6d 73 20 6f 72 20  ces of terms or 
1250: 70 72 65 66 69 78 20 74 65 72 6d 73 20 74 68 61  prefix terms tha
1260: 74 20 6d 75 73 74 20 66 65 61 74 75 72 65 20 69  t must feature i
1270: 6e 20 61 0a 20 20 20 20 20 20 20 64 6f 63 75 6d  n a.       docum
1280: 65 6e 74 20 66 6f 72 20 69 74 20 74 6f 20 6d 61  ent for it to ma
1290: 74 63 68 20 74 68 65 20 71 75 65 72 79 2c 20 0a  tch the query, .
12a0: 20 20 3c 6c 69 3e 20 73 65 74 73 20 6f 66 20 74    <li> sets of t
12b0: 65 72 6d 73 2c 20 70 72 65 66 69 78 20 74 65 72  erms, prefix ter
12c0: 6d 73 20 6f 72 20 70 68 72 61 73 65 73 20 74 68  ms or phrases th
12d0: 61 74 20 61 70 70 65 61 72 20 77 69 74 68 69 6e  at appear within
12e0: 20 61 20 73 70 65 63 69 66 69 65 64 0a 20 20 20   a specified.   
12f0: 20 20 20 20 70 72 6f 78 69 6d 69 74 79 20 6f 66      proximity of
1300: 20 65 61 63 68 20 6f 74 68 65 72 20 28 74 68 65   each other (the
1310: 73 65 20 61 72 65 20 63 61 6c 6c 65 64 20 22 4e  se are called "N
1320: 45 41 52 20 71 75 65 72 69 65 73 22 29 2c 20 6f  EAR queries"), o
1330: 72 0a 20 20 3c 6c 69 3e 20 62 6f 6f 6c 65 61 6e  r.  <li> boolean
1340: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
1350: 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
1360: 65 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 53 75  e..</ul>..<p> Su
1370: 63 68 20 61 64 76 61 6e 63 65 64 20 73 65 61 72  ch advanced sear
1380: 63 68 65 73 20 61 72 65 20 72 65 71 75 65 73 74  ches are request
1390: 65 64 20 62 79 20 70 72 6f 76 69 64 69 6e 67 20  ed by providing 
13a0: 61 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  a more complicat
13b0: 65 64 20 0a 46 54 53 35 20 71 75 65 72 79 20 73  ed .FTS5 query s
13c0: 74 72 69 6e 67 20 61 73 20 74 68 65 20 74 65 78  tring as the tex
13d0: 74 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f  t to the right o
13e0: 66 20 74 68 65 20 4d 41 54 43 48 20 6f 70 65 72  f the MATCH oper
13f0: 61 74 6f 72 20 28 6f 72 20 3d 0a 6f 70 65 72 61  ator (or =.opera
1400: 74 6f 72 2c 20 6f 72 20 61 73 20 74 68 65 20 66  tor, or as the f
1410: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1420: 20 61 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20   a table-valued 
1430: 66 75 6e 63 74 69 6f 6e 20 73 79 6e 74 61 78 29  function syntax)
1440: 2e 20 54 68 65 20 0a 66 75 6c 6c 20 71 75 65 72  . The .full quer
1450: 79 20 73 79 6e 74 61 78 20 69 73 20 5b 46 54 53  y syntax is [FTS
1460: 35 20 71 75 65 72 79 20 73 79 6e 74 61 78 20 7c  5 query syntax |
1470: 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 5d   described here]
1480: 2e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46 54 53  ...<h1 tags="FTS
1490: 35 20 62 75 69 6c 64 69 6e 67 22 3e 43 6f 6d 70  5 building">Comp
14a0: 69 6c 69 6e 67 20 61 6e 64 20 55 73 69 6e 67 20  iling and Using 
14b0: 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 68 32 3e 42  FTS5</h1>..<h2>B
14c0: 75 69 6c 64 69 6e 67 20 46 54 53 35 20 61 73 20  uilding FTS5 as 
14d0: 70 61 72 74 20 6f 66 20 53 51 4c 69 74 65 3c 2f  part of SQLite</
14e0: 68 32 3e 0a 0a 3c 70 3e 41 73 20 6f 66 20 5b 76  h2>..<p>As of [v
14f0: 65 72 73 69 6f 6e 20 33 2e 39 2e 30 5d 20 28 5b  ersion 3.9.0] ([
1500: 64 61 74 65 6f 66 3a 33 2e 39 2e 30 5d 29 2c 20  dateof:3.9.0]), 
1510: 0a 46 54 53 35 20 69 73 20 69 6e 63 6c 75 64 65  .FTS5 is include
1520: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1530: 20 53 51 4c 69 74 65 20 5b 61 6d 61 6c 67 61 6d   SQLite [amalgam
1540: 61 74 69 6f 6e 5d 2e 0a 49 74 20 69 73 20 64 69  ation]..It is di
1550: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1560: 74 2e 20 49 66 20 75 73 69 6e 67 20 74 68 65 20  t. If using the 
1570: 74 77 6f 20 61 75 74 6f 63 6f 6e 66 20 62 75 69  two autoconf bui
1580: 6c 64 20 73 79 73 74 65 6d 2c 20 69 74 20 69 73  ld system, it is
1590: 0a 65 6e 61 62 6c 65 64 20 62 79 20 73 70 65 63  .enabled by spec
15a0: 69 66 79 69 6e 67 20 74 68 65 20 22 2d 2d 65 6e  ifying the "--en
15b0: 61 62 6c 65 2d 66 74 73 35 22 20 6f 70 74 69 6f  able-fts5" optio
15c0: 6e 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67 20 74  n when running t
15d0: 68 65 20 63 6f 6e 66 69 67 75 72 65 0a 73 63 72  he configure.scr
15e0: 69 70 74 2e 20 0a 0a 3c 70 3e 4f 72 2c 20 69 66  ipt. ..<p>Or, if
15f0: 20 73 71 6c 69 74 65 33 2e 63 20 69 73 20 63 6f   sqlite3.c is co
1600: 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 73 6f 6d  mpiled using som
1610: 65 20 6f 74 68 65 72 20 62 75 69 6c 64 20 73 79  e other build sy
1620: 73 74 65 6d 2c 20 62 79 20 61 72 72 61 6e 67 69  stem, by arrangi
1630: 6e 67 20 66 6f 72 0a 74 68 65 20 53 51 4c 49 54  ng for.the SQLIT
1640: 45 5f 45 4e 41 42 4c 45 5f 46 54 53 35 20 70 72  E_ENABLE_FTS5 pr
1650: 65 2d 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  e-processor symb
1660: 6f 6c 20 74 6f 20 62 65 20 64 65 66 69 6e 65 64  ol to be defined
1670: 2e 0a 0a 3c 68 32 3e 42 75 69 6c 64 69 6e 67 20  ...<h2>Building 
1680: 61 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e  a Loadable Exten
1690: 73 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 41 6c  sion</h2>..<p>Al
16a0: 74 65 72 6e 61 74 69 76 65 6c 79 2c 20 46 54 53  ternatively, FTS
16b0: 35 20 6d 61 79 20 62 65 20 62 75 69 6c 74 20 61  5 may be built a
16c0: 73 20 61 20 6c 6f 61 64 61 62 6c 65 20 65 78 74  s a loadable ext
16d0: 65 6e 73 69 6f 6e 2e 0a 0a 3c 70 3e 54 68 65 20  ension...<p>The 
16e0: 63 61 6e 6f 6e 69 63 61 6c 20 46 54 53 35 20 73  canonical FTS5 s
16f0: 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 73 69  ource code consi
1700: 73 74 73 20 6f 66 20 61 20 73 65 72 69 65 73 20  sts of a series 
1710: 6f 66 20 2a 2e 63 20 61 6e 64 20 6f 74 68 65 72  of *.c and other
1720: 20 66 69 6c 65 73 0a 69 6e 20 74 68 65 20 22 65   files.in the "e
1730: 78 74 2f 66 74 73 35 22 20 64 69 72 65 63 74 6f  xt/fts5" directo
1740: 72 79 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  ry of the SQLite
1750: 20 73 6f 75 72 63 65 20 74 72 65 65 2e 20 41 20   source tree. A 
1760: 62 75 69 6c 64 20 70 72 6f 63 65 73 73 20 72 65  build process re
1770: 64 75 63 65 73 0a 74 68 69 73 20 74 6f 20 6a 75  duces.this to ju
1780: 73 74 20 74 77 6f 20 66 69 6c 65 73 20 2d 20 22  st two files - "
1790: 66 74 73 35 2e 63 22 20 61 6e 64 20 22 66 74 73  fts5.c" and "fts
17a0: 35 2e 68 22 20 2d 20 77 68 69 63 68 20 6d 61 79  5.h" - which may
17b0: 20 62 65 20 75 73 65 64 20 74 6f 20 62 75 69 6c   be used to buil
17c0: 64 20 61 6e 0a 53 51 4c 69 74 65 20 6c 6f 61 64  d an.SQLite load
17d0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  able extension..
17e0: 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 4f 62 74  .<ol>.  <li> Obt
17f0: 61 69 6e 20 74 68 65 20 6c 61 74 65 73 74 20 53  ain the latest S
1800: 51 4c 69 74 65 20 63 6f 64 65 20 66 72 6f 6d 20  QLite code from 
1810: 66 6f 73 73 69 6c 2e 0a 20 20 3c 6c 69 3e 20 43  fossil..  <li> C
1820: 72 65 61 74 65 20 61 20 4d 61 6b 65 66 69 6c 65  reate a Makefile
1830: 20 61 73 20 64 65 73 63 72 69 62 65 64 20 69 6e   as described in
1840: 20 5b 48 6f 77 20 54 6f 20 43 6f 6d 70 69 6c 65   [How To Compile
1850: 20 53 51 4c 69 74 65 5d 2e 0a 20 20 3c 6c 69 3e   SQLite]..  <li>
1860: 20 42 75 69 6c 64 20 74 68 65 20 22 66 74 73 35   Build the "fts5
1870: 2e 63 22 20 74 61 72 67 65 74 2e 20 57 68 69 63  .c" target. Whic
1880: 68 20 61 6c 73 6f 20 63 72 65 61 74 65 73 20 66  h also creates f
1890: 74 73 35 2e 68 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 63  ts5.h..</ol>..<c
18a0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 24 20 77 67  odeblock>.  $ wg
18b0: 65 74 20 2d 63 20 68 74 74 70 3a 2f 2f 77 77 77  et -c http://www
18c0: 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f  .sqlite.org/src/
18d0: 74 61 72 62 61 6c 6c 2f 53 51 4c 69 74 65 2d 74  tarball/SQLite-t
18e0: 72 75 6e 6b 2e 74 67 7a 3f 75 75 69 64 3d 74 72  runk.tgz?uuid=tr
18f0: 75 6e 6b 20 2d 4f 20 53 51 4c 69 74 65 2d 74 72  unk -O SQLite-tr
1900: 75 6e 6b 2e 74 67 7a 0a 20 20 2e 2e 2e 2e 20 6f  unk.tgz.  .... o
1910: 75 74 70 75 74 20 2e 2e 2e 0a 20 20 24 20 74 61  utput ....  $ ta
1920: 72 20 2d 78 7a 66 20 53 51 4c 69 74 65 2d 74 72  r -xzf SQLite-tr
1930: 75 6e 6b 2e 74 67 7a 0a 20 20 24 20 63 64 20 53  unk.tgz.  $ cd S
1940: 51 4c 69 74 65 2d 74 72 75 6e 6b 0a 20 20 24 20  QLite-trunk.  $ 
1950: 2e 2f 63 6f 6e 66 69 67 75 72 65 20 26 26 20 6d  ./configure && m
1960: 61 6b 65 20 66 74 73 35 2e 63 0a 20 20 2e 2e 2e  ake fts5.c.  ...
1970: 20 6c 6f 74 73 20 6f 66 20 6f 75 74 70 75 74 20   lots of output 
1980: 2e 2e 2e 0a 20 20 24 20 6c 73 20 66 74 73 35 2e  ....  $ ls fts5.
1990: 26 23 39 31 3b 63 68 5d 0a 20 20 66 74 73 35 2e  &#91;ch].  fts5.
19a0: 63 20 20 20 20 20 20 20 20 66 74 73 35 2e 68 0a  c        fts5.h.
19b0: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
19c0: 3e 0a 20 20 54 68 65 20 63 6f 64 65 20 69 6e 20  >.  The code in 
19d0: 22 66 74 73 35 2e 63 22 20 6d 61 79 20 74 68 65  "fts5.c" may the
19e0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  n be compiled in
19f0: 74 6f 20 61 20 6c 6f 61 64 61 62 6c 65 20 65 78  to a loadable ex
1a00: 74 65 6e 73 69 6f 6e 20 6f 72 0a 20 20 73 74 61  tension or.  sta
1a10: 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 69  tically linked i
1a20: 6e 74 6f 20 61 6e 20 61 70 70 6c 69 63 61 74 69  nto an applicati
1a30: 6f 6e 20 61 73 20 64 65 73 63 72 69 62 65 64 20  on as described 
1a40: 69 6e 20 0a 20 20 5b 43 6f 6d 70 69 6c 69 6e 67  in .  [Compiling
1a50: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
1a60: 69 6f 6e 73 5d 2e 20 54 68 65 72 65 20 61 72 65  ions]. There are
1a70: 20 74 77 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74   two entry point
1a80: 73 20 64 65 66 69 6e 65 64 2c 20 62 6f 74 68 0a  s defined, both.
1a90: 20 20 6f 66 20 77 68 69 63 68 20 64 6f 20 74 68    of which do th
1aa0: 65 20 73 61 6d 65 20 74 68 69 6e 67 3a 0a 0a 3c  e same thing:..<
1ab0: 75 6c 3e 0a 20 20 3c 6c 69 3e 20 73 71 6c 69 74  ul>.  <li> sqlit
1ac0: 65 33 5f 66 74 73 5f 69 6e 69 74 0a 20 20 3c 6c  e3_fts_init.  <l
1ad0: 69 3e 20 73 71 6c 69 74 65 33 5f 66 74 73 35 5f  i> sqlite3_fts5_
1ae0: 69 6e 69 74 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 0a  init.</ul>..<p>.
1af0: 20 20 54 68 65 20 6f 74 68 65 72 20 66 69 6c 65    The other file
1b00: 2c 20 22 66 74 73 35 2e 68 22 2c 20 69 73 20 6e  , "fts5.h", is n
1b10: 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 63  ot required to c
1b20: 6f 6d 70 69 6c 65 20 74 68 65 20 46 54 53 35 20  ompile the FTS5 
1b30: 65 78 74 65 6e 73 69 6f 6e 2e 20 0a 20 20 49 74  extension. .  It
1b40: 20 69 73 20 75 73 65 64 20 62 79 20 61 70 70 6c   is used by appl
1b50: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  ications that im
1b60: 70 6c 65 6d 65 6e 74 20 5b 45 78 74 65 6e 64 69  plement [Extendi
1b70: 6e 67 20 46 54 53 35 20 7c 20 63 75 73 74 6f 6d  ng FTS5 | custom
1b80: 20 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65 72 73   FTS5 tokenizers
1b90: 20 6f 72 20 61 75 78 69 6c 69 61 72 79 20 66 75   or auxiliary fu
1ba0: 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 68 31 20 74  nctions]...<h1 t
1bb0: 61 67 73 3d 22 46 54 53 35 20 71 75 65 72 79 20  ags="FTS5 query 
1bc0: 73 79 6e 74 61 78 22 3e 46 75 6c 6c 2d 74 65 78  syntax">Full-tex
1bd0: 74 20 51 75 65 72 79 20 53 79 6e 74 61 78 3c 2f  t Query Syntax</
1be0: 68 31 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c  h1>..<p>.The fol
1bf0: 6c 6f 77 69 6e 67 20 62 6c 6f 63 6b 20 63 6f 6e  lowing block con
1c00: 74 61 69 6e 73 20 61 20 73 75 6d 6d 61 72 79 20  tains a summary 
1c10: 6f 66 20 74 68 65 20 46 54 53 20 71 75 65 72 79  of the FTS query
1c20: 20 73 79 6e 74 61 78 20 69 6e 20 42 4e 46 20 66   syntax in BNF f
1c30: 6f 72 6d 2e 0a 41 20 64 65 74 61 69 6c 65 64 20  orm..A detailed 
1c40: 65 78 70 6c 61 6e 61 74 69 6f 6e 20 66 6f 6c 6c  explanation foll
1c50: 6f 77 73 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ows...<codeblock
1c60: 3e 0a 26 6c 74 3b 70 68 72 61 73 65 26 67 74 3b  >.&lt;phrase&gt;
1c70: 20 20 20 20 3a 3d 20 73 74 72 69 6e 67 20 26 23      := string &#
1c80: 39 31 3b 2a 5d 0a 26 6c 74 3b 70 68 72 61 73 65  91;*].&lt;phrase
1c90: 26 67 74 3b 20 20 20 20 3a 3d 20 26 6c 74 3b 70  &gt;    := &lt;p
1ca0: 68 72 61 73 65 26 67 74 3b 20 2b 20 26 6c 74 3b  hrase&gt; + &lt;
1cb0: 70 68 72 61 73 65 26 67 74 3b 0a 26 6c 74 3b 6e  phrase&gt;.&lt;n
1cc0: 65 61 72 67 72 6f 75 70 26 67 74 3b 20 3a 3d 20  eargroup&gt; := 
1cd0: 4e 45 41 52 20 28 20 26 6c 74 3b 70 68 72 61 73  NEAR ( &lt;phras
1ce0: 65 26 67 74 3b 20 26 6c 74 3b 70 68 72 61 73 65  e&gt; &lt;phrase
1cf0: 26 67 74 3b 20 2e 2e 2e 20 26 23 39 31 3b 2c 20  &gt; ... &#91;, 
1d00: 4e 5d 20 29 0a 26 6c 74 3b 71 75 65 72 79 26 67  N] ).&lt;query&g
1d10: 74 3b 20 20 20 20 20 3a 3d 20 26 23 39 31 3b 20  t;     := &#91; 
1d20: 26 23 39 31 3b 2d 5d 20 26 6c 74 3b 63 6f 6c 73  &#91;-] &lt;cols
1d30: 70 65 63 26 67 74 3b 20 3a 5d 20 26 6c 74 3b 70  pec&gt; :] &lt;p
1d40: 68 72 61 73 65 26 67 74 3b 0a 26 6c 74 3b 71 75  hrase&gt;.&lt;qu
1d50: 65 72 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26  ery&gt;     := &
1d60: 23 39 31 3b 20 26 23 39 31 3b 2d 5d 20 26 6c 74  #91; &#91;-] &lt
1d70: 3b 63 6f 6c 73 70 65 63 26 67 74 3b 20 3a 5d 20  ;colspec&gt; :] 
1d80: 26 6c 74 3b 6e 65 61 72 67 72 6f 75 70 26 67 74  &lt;neargroup&gt
1d90: 3b 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20  ;.&lt;query&gt; 
1da0: 20 20 20 20 3a 3d 20 28 20 26 6c 74 3b 71 75 65      := ( &lt;que
1db0: 72 79 26 67 74 3b 20 29 0a 26 6c 74 3b 71 75 65  ry&gt; ).&lt;que
1dc0: 72 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 6c  ry&gt;     := &l
1dd0: 74 3b 71 75 65 72 79 26 67 74 3b 20 41 4e 44 20  t;query&gt; AND 
1de0: 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 0a 26 6c  &lt;query&gt;.&l
1df0: 74 3b 71 75 65 72 79 26 67 74 3b 20 20 20 20 20  t;query&gt;     
1e00: 3a 3d 20 26 6c 74 3b 71 75 65 72 79 26 67 74 3b  := &lt;query&gt;
1e10: 20 4f 52 20 26 6c 74 3b 71 75 65 72 79 26 67 74   OR &lt;query&gt
1e20: 3b 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20  ;.&lt;query&gt; 
1e30: 20 20 20 20 3a 3d 20 26 6c 74 3b 71 75 65 72 79      := &lt;query
1e40: 26 67 74 3b 20 4e 4f 54 20 26 6c 74 3b 71 75 65  &gt; NOT &lt;que
1e50: 72 79 26 67 74 3b 0a 26 6c 74 3b 63 6f 6c 73 70  ry&gt;.&lt;colsp
1e60: 65 63 26 67 74 3b 20 20 20 3a 3d 20 63 6f 6c 6e  ec&gt;   := coln
1e70: 61 6d 65 0a 26 6c 74 3b 63 6f 6c 73 70 65 63 26  ame.&lt;colspec&
1e80: 67 74 3b 20 20 20 3a 3d 20 7b 20 63 6f 6c 6e 61  gt;   := { colna
1e90: 6d 65 31 20 63 6f 6c 6e 61 6d 65 32 20 2e 2e 2e  me1 colname2 ...
1ea0: 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a   }.</codeblock>.
1eb0: 0a 3c 70 3e 0a 57 69 74 68 69 6e 20 61 6e 20 46  .<p>.Within an F
1ec0: 54 53 20 65 78 70 72 65 73 73 69 6f 6e 20 61 20  TS expression a 
1ed0: 3c 62 3e 73 74 72 69 6e 67 3c 2f 62 3e 20 6d 61  <b>string</b> ma
1ee0: 79 20 62 65 20 73 70 65 63 69 66 69 65 64 20 69  y be specified i
1ef0: 6e 20 6f 6e 65 20 6f 66 20 74 77 6f 20 77 61 79  n one of two way
1f00: 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20  s:..<ul>.  <li> 
1f10: 3c 70 3e 42 79 20 65 6e 63 6c 6f 73 69 6e 67 20  <p>By enclosing 
1f20: 69 74 20 69 6e 20 64 6f 75 62 6c 65 20 71 75 6f  it in double quo
1f30: 74 65 73 20 28 22 29 2e 20 57 69 74 68 69 6e 20  tes ("). Within 
1f40: 61 20 73 74 72 69 6e 67 2c 20 61 6e 79 20 65 6d  a string, any em
1f50: 62 65 64 64 65 64 0a 20 20 20 20 20 20 20 64 6f  bedded.       do
1f60: 75 62 6c 65 20 71 75 6f 74 65 20 63 68 61 72 61  uble quote chara
1f70: 63 74 65 72 73 20 6d 61 79 20 62 65 20 65 73 63  cters may be esc
1f80: 61 70 65 64 20 53 51 4c 2d 73 74 79 6c 65 20 2d  aped SQL-style -
1f90: 20 62 79 20 61 64 64 69 6e 67 20 61 20 73 65 63   by adding a sec
1fa0: 6f 6e 64 0a 20 20 20 20 20 20 20 64 6f 75 62 6c  ond.       doubl
1fb0: 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1fc0: 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 41 73  r...  <li> <p>As
1fd0: 20 61 6e 20 46 54 53 35 20 62 61 72 65 77 6f 72   an FTS5 barewor
1fe0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 22 41  d that is not "A
1ff0: 4e 44 22 2c 20 22 4f 52 22 20 6f 72 20 22 4e 4f  ND", "OR" or "NO
2000: 54 22 20 28 63 61 73 65 20 73 65 6e 73 69 74 69  T" (case sensiti
2010: 76 65 29 2e 20 0a 20 20 20 20 20 20 20 41 6e 20  ve). .       An 
2020: 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 69 73  FTS5 bareword is
2030: 20 61 20 73 74 72 69 6e 67 20 6f 66 20 6f 6e 65   a string of one
2040: 20 6f 72 20 6d 6f 72 65 20 63 6f 6e 73 65 63 75   or more consecu
2050: 74 69 76 65 20 63 68 61 72 61 63 74 65 72 73 20  tive characters 
2060: 74 68 61 74 0a 20 20 20 20 20 20 20 61 72 65 20  that.       are 
2070: 61 6c 6c 20 65 69 74 68 65 72 3a 0a 20 20 20 20  all either:.    
2080: 20 20 20 0a 20 20 20 20 20 20 20 3c 75 6c 3e 0a     .       <ul>.
2090: 20 20 20 20 20 20 20 20 20 3c 6c 69 3e 20 4e 6f           <li> No
20a0: 6e 2d 41 53 43 49 49 20 72 61 6e 67 65 20 63 68  n-ASCII range ch
20b0: 61 72 61 63 74 65 72 73 20 28 69 2e 65 2e 20 75  aracters (i.e. u
20c0: 6e 69 63 6f 64 65 20 63 6f 64 65 70 6f 69 6e 74  nicode codepoint
20d0: 73 20 67 72 65 61 74 65 72 20 0a 20 20 20 20 20  s greater .     
20e0: 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 31 32           than 12
20f0: 37 29 2c 20 6f 72 20 0a 20 20 20 20 20 20 20 20  7), or .        
2100: 20 3c 6c 69 3e 20 4f 6e 65 20 6f 66 20 74 68 65   <li> One of the
2110: 20 35 32 20 75 70 70 65 72 20 61 6e 64 20 6c 6f   52 upper and lo
2120: 77 65 72 20 63 61 73 65 20 41 53 43 49 49 20 63  wer case ASCII c
2130: 68 61 72 61 63 74 65 72 73 2c 20 6f 72 0a 20 20  haracters, or.  
2140: 20 20 20 20 20 20 20 3c 6c 69 3e 20 4f 6e 65 20         <li> One 
2150: 6f 66 20 74 68 65 20 31 30 20 64 65 63 69 6d 61  of the 10 decima
2160: 6c 20 64 69 67 69 74 20 41 53 43 49 49 20 63 68  l digit ASCII ch
2170: 61 72 61 63 74 65 72 73 2c 20 6f 72 0a 20 20 20  aracters, or.   
2180: 20 20 20 20 20 20 3c 6c 69 3e 20 54 68 65 20 75        <li> The u
2190: 6e 64 65 72 73 63 6f 72 65 20 63 68 61 72 61 63  nderscore charac
21a0: 74 65 72 20 28 75 6e 69 63 6f 64 65 20 63 6f 64  ter (unicode cod
21b0: 65 70 6f 69 6e 74 20 39 36 29 2e 0a 20 20 20 20  epoint 96)..    
21c0: 20 20 20 20 20 3c 6c 69 3e 20 54 68 65 20 73 75       <li> The su
21d0: 62 73 74 69 74 75 74 65 20 63 68 61 72 61 63 74  bstitute charact
21e0: 65 72 20 28 75 6e 69 63 6f 64 65 20 63 6f 64 65  er (unicode code
21f0: 70 6f 69 6e 74 20 32 36 29 2e 0a 20 20 20 20 20  point 26)..     
2200: 20 20 3c 2f 75 6c 3e 0a 0a 20 20 20 20 20 20 20    </ul>..       
2210: 53 74 72 69 6e 67 73 20 74 68 61 74 20 69 6e 63  Strings that inc
2220: 6c 75 64 65 20 61 6e 79 20 6f 74 68 65 72 20 63  lude any other c
2230: 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
2240: 65 20 71 75 6f 74 65 64 2e 20 43 68 61 72 61 63  e quoted. Charac
2250: 74 65 72 73 0a 20 20 20 20 20 20 20 74 68 61 74  ters.       that
2260: 20 61 72 65 20 6e 6f 74 20 63 75 72 72 65 6e 74   are not current
2270: 6c 79 20 61 6c 6c 6f 77 65 64 20 69 6e 20 62 61  ly allowed in ba
2280: 72 65 77 6f 72 64 73 2c 20 61 72 65 20 6e 6f 74  rewords, are not
2290: 20 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72   quote character
22a0: 73 20 61 6e 64 0a 20 20 20 20 20 20 20 64 6f 20  s and.       do 
22b0: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 73 65  not currently se
22c0: 72 76 65 20 61 6e 79 20 73 70 65 63 69 61 6c 20  rve any special 
22d0: 70 75 72 70 6f 73 65 20 69 6e 20 46 54 53 35 20  purpose in FTS5 
22e0: 71 75 65 72 79 20 65 78 70 72 65 73 73 69 6f 6e  query expression
22f0: 73 20 6d 61 79 0a 20 20 20 20 20 20 20 61 74 20  s may.       at 
2300: 73 6f 6d 65 20 70 6f 69 6e 74 20 69 6e 20 74 68  some point in th
2310: 65 20 66 75 74 75 72 65 20 62 65 20 61 6c 6c 6f  e future be allo
2320: 77 65 64 20 69 6e 20 62 61 72 65 77 6f 72 64 73  wed in barewords
2330: 20 6f 72 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   or used to impl
2340: 65 6d 65 6e 74 0a 20 20 20 20 20 20 20 6e 65 77  ement.       new
2350: 20 71 75 65 72 79 20 66 75 6e 63 74 69 6f 6e 61   query functiona
2360: 6c 69 74 79 2e 20 54 68 69 73 20 6d 65 61 6e 73  lity. This means
2370: 20 74 68 61 74 20 71 75 65 72 69 65 73 20 74 68   that queries th
2380: 61 74 20 61 72 65 20 63 75 72 72 65 6e 74 6c 79  at are currently
2390: 0a 20 20 20 20 20 20 20 73 79 6e 74 61 78 20 65  .       syntax e
23a0: 72 72 6f 72 73 20 62 65 63 61 75 73 65 20 74 68  rrors because th
23b0: 65 79 20 69 6e 63 6c 75 64 65 20 73 75 63 68 20  ey include such 
23c0: 61 20 63 68 61 72 61 63 74 65 72 20 6f 75 74 73  a character outs
23d0: 69 64 65 20 6f 66 20 61 20 71 75 6f 74 65 64 0a  ide of a quoted.
23e0: 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 6d 61         string ma
23f0: 79 20 62 65 20 69 6e 74 65 72 70 72 65 74 65 64  y be interpreted
2400: 20 64 69 66 66 65 72 65 6e 74 6c 79 20 62 79 20   differently by 
2410: 73 6f 6d 65 20 66 75 74 75 72 65 20 76 65 72 73  some future vers
2420: 69 6f 6e 20 6f 66 20 46 54 53 35 2e 0a 3c 2f 75  ion of FTS5..</u
2430: 6c 3e 0a 0a 3c 70 3e 0a 46 54 53 20 71 75 65 72  l>..<p>.FTS quer
2440: 69 65 73 20 61 72 65 20 6d 61 64 65 20 75 70 20  ies are made up 
2450: 6f 66 20 3c 62 3e 70 68 72 61 73 65 73 3c 2f 62  of <b>phrases</b
2460: 3e 2e 20 41 20 70 68 72 61 73 65 20 69 73 20 61  >. A phrase is a
2470: 6e 20 6f 72 64 65 72 65 64 20 6c 69 73 74 20 6f  n ordered list o
2480: 66 20 0a 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  f .one or more t
2490: 6f 6b 65 6e 73 2e 20 41 20 73 74 72 69 6e 67 20  okens. A string 
24a0: 69 73 20 74 72 61 6e 73 66 6f 72 6d 65 64 20 69  is transformed i
24b0: 6e 74 6f 20 61 20 70 68 72 61 73 65 20 62 79 20  nto a phrase by 
24c0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 74 68  passing it to.th
24d0: 65 20 46 54 53 20 74 61 62 6c 65 20 74 6f 6b 65  e FTS table toke
24e0: 6e 69 7a 65 72 2e 20 54 77 6f 20 70 68 72 61 73  nizer. Two phras
24f0: 65 73 20 63 61 6e 20 62 65 20 63 6f 6e 63 61 74  es can be concat
2500: 65 6e 61 74 65 64 20 69 6e 74 6f 20 61 20 73 69  enated into a si
2510: 6e 67 6c 65 20 0a 6c 61 72 67 65 20 70 68 72 61  ngle .large phra
2520: 73 65 20 75 73 69 6e 67 20 74 68 65 20 22 2b 22  se using the "+"
2530: 20 6f 70 65 72 61 74 6f 72 2e 20 46 6f 72 20 65   operator. For e
2540: 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 69 6e 67  xample, assuming
2550: 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 0a 6d   the tokenizer.m
2560: 6f 64 75 6c 65 20 62 65 69 6e 67 20 75 73 65 64  odule being used
2570: 20 74 6f 6b 65 6e 69 7a 65 73 20 74 68 65 20 69   tokenizes the i
2580: 6e 70 75 74 20 22 6f 6e 65 2e 74 77 6f 2e 74 68  nput "one.two.th
2590: 72 65 65 22 20 74 6f 20 74 68 72 65 65 20 73 65  ree" to three se
25a0: 70 61 72 61 74 65 0a 74 6f 6b 65 6e 73 2c 20 74  parate.tokens, t
25b0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
25c0: 65 65 20 71 75 65 72 69 65 73 20 61 6c 6c 20 73  ee queries all s
25d0: 70 65 63 69 66 79 20 74 68 65 20 73 61 6d 65 20  pecify the same 
25e0: 70 68 72 61 73 65 3a 0a 0a 3c 63 6f 64 65 62 6c  phrase:..<codebl
25f0: 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48  ock>.  ... MATCH
2600: 20 27 22 6f 6e 65 20 74 77 6f 20 74 68 72 65 65   '"one two three
2610: 22 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  "'.  ... MATCH '
2620: 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68 72 65  one + two + thre
2630: 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  e'.  ... MATCH '
2640: 22 6f 6e 65 20 74 77 6f 22 20 2b 20 74 68 72 65  "one two" + thre
2650: 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  e'.  ... MATCH '
2660: 6f 6e 65 2e 74 77 6f 2e 74 68 72 65 65 27 0a 3c  one.two.three'.<
2670: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
2680: 0a 41 20 70 68 72 61 73 65 20 6d 61 74 63 68 65  .A phrase matche
2690: 73 20 61 20 64 6f 63 75 6d 65 6e 74 20 69 66 20  s a document if 
26a0: 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 63 6f 6e  the document con
26b0: 74 61 69 6e 73 20 61 74 20 6c 65 61 73 74 20 6f  tains at least o
26c0: 6e 65 20 73 75 62 2d 73 65 71 75 65 6e 63 65 0a  ne sub-sequence.
26d0: 6f 66 20 74 6f 6b 65 6e 73 20 74 68 61 74 20 6d  of tokens that m
26e0: 61 74 63 68 65 73 20 74 68 65 20 73 65 71 75 65  atches the seque
26f0: 6e 63 65 20 6f 66 20 74 6f 6b 65 6e 73 20 74 68  nce of tokens th
2700: 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65 20 70  at make up the p
2710: 68 72 61 73 65 2e 0a 0a 3c 70 3e 0a 49 66 20 61  hrase...<p>.If a
2720: 20 22 2a 22 20 63 68 61 72 61 63 74 65 72 20 66   "*" character f
2730: 6f 6c 6c 6f 77 73 20 61 20 73 74 72 69 6e 67 20  ollows a string 
2740: 77 69 74 68 69 6e 20 61 6e 20 46 54 53 20 65 78  within an FTS ex
2750: 70 72 65 73 73 69 6f 6e 2c 20 74 68 65 6e 20 74  pression, then t
2760: 68 65 20 66 69 6e 61 6c 0a 74 6f 6b 65 6e 20 65  he final.token e
2770: 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68  xtracted from th
2780: 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 72 6b  e string is mark
2790: 65 64 20 61 73 20 61 20 3c 62 3e 70 72 65 66 69  ed as a <b>prefi
27a0: 78 20 74 6f 6b 65 6e 3c 2f 62 3e 2e 20 41 73 20  x token</b>. As 
27b0: 79 6f 75 0a 6d 69 67 68 74 20 65 78 70 65 63 74  you.might expect
27c0: 2c 20 61 20 70 72 65 66 69 78 20 74 6f 6b 65 6e  , a prefix token
27d0: 20 6d 61 74 63 68 65 73 20 61 6e 79 20 64 6f 63   matches any doc
27e0: 75 6d 65 6e 74 20 74 6f 6b 65 6e 20 6f 66 20 77  ument token of w
27f0: 68 69 63 68 20 69 74 20 69 73 20 61 20 0a 70 72  hich it is a .pr
2800: 65 66 69 78 2e 20 46 6f 72 20 65 78 61 6d 70 6c  efix. For exampl
2810: 65 2c 20 74 68 65 20 66 69 72 73 74 20 74 77 6f  e, the first two
2820: 20 71 75 65 72 69 65 73 20 69 6e 20 74 68 65 20   queries in the 
2830: 66 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f 63 6b 20  following block 
2840: 77 69 6c 6c 20 6d 61 74 63 68 0a 61 6e 79 20 64  will match.any d
2850: 6f 63 75 6d 65 6e 74 20 74 68 61 74 20 63 6f 6e  ocument that con
2860: 74 61 69 6e 73 20 74 68 65 20 74 6f 6b 65 6e 20  tains the token 
2870: 22 6f 6e 65 22 20 69 6d 6d 65 64 69 61 74 65 6c  "one" immediatel
2880: 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74 68  y followed by th
2890: 65 20 74 6f 6b 65 6e 0a 22 74 77 6f 22 20 61 6e  e token."two" an
28a0: 64 20 74 68 65 6e 20 61 6e 79 20 74 6f 6b 65 6e  d then any token
28b0: 20 74 68 61 74 20 62 65 67 69 6e 73 20 77 69 74   that begins wit
28c0: 68 20 22 74 68 72 22 2e 0a 0a 3c 63 6f 64 65 62  h "thr"...<codeb
28d0: 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  lock>.  ... MATC
28e0: 48 20 27 22 6f 6e 65 20 74 77 6f 20 74 68 72 22  H '"one two thr"
28f0: 20 2a 20 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48   * '.  ... MATCH
2900: 20 27 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68   'one + two + th
2910: 72 2a 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  r*'.  ... MATCH 
2920: 27 22 6f 6e 65 20 74 77 6f 20 74 68 72 2a 22 27  '"one two thr*"'
2930: 20 20 20 20 20 20 3c 62 3e 2d 2d 20 4d 61 79 20        <b>-- May 
2940: 6e 6f 74 20 77 6f 72 6b 20 61 73 20 65 78 70 65  not work as expe
2950: 63 74 65 64 21 3c 2f 62 3e 0a 3c 2f 63 6f 64 65  cted!</b>.</code
2960: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 66  block>..<p>The f
2970: 69 6e 61 6c 20 71 75 65 72 79 20 69 6e 20 74 68  inal query in th
2980: 65 20 62 6c 6f 63 6b 20 61 62 6f 76 65 20 6d 61  e block above ma
2990: 79 20 6e 6f 74 20 77 6f 72 6b 20 61 73 20 65 78  y not work as ex
29a0: 70 65 63 74 65 64 2e 20 42 65 63 61 75 73 65 20  pected. Because 
29b0: 74 68 65 0a 22 2a 22 20 63 68 61 72 61 63 74 65  the."*" characte
29c0: 72 20 69 73 20 69 6e 73 69 64 65 20 74 68 65 20  r is inside the 
29d0: 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 2c 20 69  double-quotes, i
29e0: 74 20 77 69 6c 6c 20 62 65 20 70 61 73 73 65 64  t will be passed
29f0: 20 74 6f 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65   to the tokenize
2a00: 72 2c 0a 77 68 69 63 68 20 77 69 6c 6c 20 6c 69  r,.which will li
2a10: 6b 65 6c 79 20 64 69 73 63 61 72 64 20 69 74 20  kely discard it 
2a20: 28 6f 72 20 70 65 72 68 61 70 73 2c 20 64 65 70  (or perhaps, dep
2a30: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 73 70  ending on the sp
2a40: 65 63 69 66 69 63 20 74 6f 6b 65 6e 69 7a 65 72  ecific tokenizer
2a50: 0a 69 6e 20 75 73 65 2c 20 69 6e 63 6c 75 64 65  .in use, include
2a60: 20 69 74 20 61 73 20 70 61 72 74 20 6f 66 20 74   it as part of t
2a70: 68 65 20 66 69 6e 61 6c 20 74 6f 6b 65 6e 29 20  he final token) 
2a80: 69 6e 73 74 65 61 64 20 6f 66 20 72 65 63 6f 67  instead of recog
2a90: 6e 69 7a 69 6e 67 20 69 74 20 61 73 0a 61 20 73  nizing it as.a s
2aa0: 70 65 63 69 61 6c 20 46 54 53 20 63 68 61 72 61  pecial FTS chara
2ab0: 63 74 65 72 2e 0a 0a 3c 70 3e 54 77 6f 20 6f 72  cter...<p>Two or
2ac0: 20 6d 6f 72 65 20 70 68 72 61 73 65 73 20 6d 61   more phrases ma
2ad0: 79 20 62 65 20 67 72 6f 75 70 65 64 20 69 6e 74  y be grouped int
2ae0: 6f 20 61 20 3c 62 3e 4e 45 41 52 20 67 72 6f 75  o a <b>NEAR grou
2af0: 70 3c 2f 62 3e 2e 20 41 20 4e 45 41 52 20 67 72  p</b>. A NEAR gr
2b00: 6f 75 70 0a 69 73 20 73 70 65 63 69 66 69 65 64  oup.is specified
2b10: 20 62 79 20 74 68 65 20 74 6f 6b 65 6e 20 22 4e   by the token "N
2b20: 45 41 52 22 20 28 63 61 73 65 20 73 65 6e 73 69  EAR" (case sensi
2b30: 74 69 76 65 29 20 66 6f 6c 6c 6f 77 65 64 20 62  tive) followed b
2b40: 79 20 61 6e 20 6f 70 65 6e 0a 70 61 72 65 6e 74  y an open.parent
2b50: 68 65 73 69 73 20 63 68 61 72 61 63 74 65 72 2c  hesis character,
2b60: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74 77 6f   followed by two
2b70: 20 6f 72 20 6d 6f 72 65 20 77 68 69 74 65 73 70   or more whitesp
2b80: 61 63 65 20 73 65 70 61 72 61 74 65 64 20 70 68  ace separated ph
2b90: 72 61 73 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  rases, optionall
2ba0: 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  y followed by a 
2bb0: 63 6f 6d 6d 61 20 61 6e 64 20 74 68 65 20 6e 75  comma and the nu
2bc0: 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20  meric parameter 
2bd0: 3c 69 3e 4e 3c 2f 69 3e 2c 20 66 6f 6c 6c 6f 77  <i>N</i>, follow
2be0: 65 64 20 62 79 0a 61 20 63 6c 6f 73 65 20 70 61  ed by.a close pa
2bf0: 72 65 6e 74 68 65 73 69 73 2e 20 46 6f 72 20 65  renthesis. For e
2c00: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
2c10: 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48  ock>.  ... MATCH
2c20: 20 27 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22   'NEAR("one two"
2c30: 20 22 74 68 72 65 65 20 66 6f 75 72 22 2c 20 31   "three four", 1
2c40: 30 29 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  0)'.  ... MATCH 
2c50: 27 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22 20  'NEAR("one two" 
2c60: 74 68 72 2a 20 2b 20 66 6f 75 72 29 27 0a 3c 2f  thr* + four)'.</
2c70: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49  codeblock>..<p>I
2c80: 66 20 6e 6f 20 3c 69 3e 4e 3c 2f 69 3e 20 70 61  f no <i>N</i> pa
2c90: 72 61 6d 65 74 65 72 20 69 73 20 73 75 70 70 6c  rameter is suppl
2ca0: 69 65 64 2c 20 69 74 20 64 65 66 61 75 6c 74 73  ied, it defaults
2cb0: 20 74 6f 20 31 30 2e 20 41 20 4e 45 41 52 20 67   to 10. A NEAR g
2cc0: 72 6f 75 70 0a 6d 61 74 63 68 65 73 20 61 20 64  roup.matches a d
2cd0: 6f 63 75 6d 65 6e 74 20 69 66 20 74 68 65 20 64  ocument if the d
2ce0: 6f 63 75 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  ocument contains
2cf0: 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 63 6c   at least one cl
2d00: 75 6d 70 20 6f 66 20 74 6f 6b 65 6e 73 20 74 68  ump of tokens th
2d10: 61 74 3a 20 0a 0a 3c 6f 6c 3e 20 0a 20 20 3c 6c  at: ..<ol> .  <l
2d20: 69 3e 20 63 6f 6e 74 61 69 6e 73 20 61 74 20 6c  i> contains at l
2d30: 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63  east one instanc
2d40: 65 20 6f 66 20 65 61 63 68 20 70 68 72 61 73 65  e of each phrase
2d50: 2c 20 61 6e 64 20 0a 20 20 3c 6c 69 3e 20 66 6f  , and .  <li> fo
2d60: 72 20 77 68 69 63 68 20 74 68 65 20 6e 75 6d 62  r which the numb
2d70: 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 62 65 74  er of tokens bet
2d80: 77 65 65 6e 20 74 68 65 20 65 6e 64 20 6f 66 20  ween the end of 
2d90: 74 68 65 20 66 69 72 73 74 20 70 68 72 61 73 65  the first phrase
2da0: 20 0a 20 20 20 20 20 20 20 61 6e 64 20 74 68 65   .       and the
2db0: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68   beginning of th
2dc0: 65 20 6c 61 73 74 20 70 68 72 61 73 65 20 69 6e  e last phrase in
2dd0: 20 74 68 65 20 63 6c 75 6d 70 20 69 73 20 6c 65   the clump is le
2de0: 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2df0: 20 74 6f 20 3c 69 3e 4e 3c 2f 69 3e 2e 0a 3c 2f   to <i>N</i>..</
2e00: 6f 6c 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d  ol>..<p>For exam
2e10: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
2e20: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
2e30: 41 4c 20 54 41 42 4c 45 20 66 20 55 53 49 4e 47  AL TABLE f USING
2e40: 20 66 74 73 35 28 78 29 3b 0a 20 20 49 4e 53 45   fts5(x);.  INSE
2e50: 52 54 20 49 4e 54 4f 20 66 28 72 6f 77 69 64 2c  RT INTO f(rowid,
2e60: 20 78 29 20 56 41 4c 55 45 53 28 31 2c 20 27 41   x) VALUES(1, 'A
2e70: 20 42 20 43 20 44 20 78 20 78 20 78 20 45 20 46   B C D x x x E F
2e80: 20 78 27 29 3b 0a 0a 20 20 2e 2e 2e 20 4d 41 54   x');..  ... MAT
2e90: 43 48 20 27 4e 45 41 52 28 65 20 64 2c 20 34 29  CH 'NEAR(e d, 4)
2ea0: 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ';              
2eb0: 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 4d 61          <i>-- Ma
2ec0: 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e 2e  tches!</i>.  ...
2ed0: 20 4d 41 54 43 48 20 27 4e 45 41 52 28 65 20 64   MATCH 'NEAR(e d
2ee0: 2c 20 33 29 27 3b 20 20 20 20 20 20 20 20 20 20  , 3)';          
2ef0: 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2d              <i>-
2f00: 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20  - Matches!</i>. 
2f10: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
2f20: 28 65 20 64 2c 20 32 29 27 3b 20 20 20 20 20 20  (e d, 2)';      
2f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f40: 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d  <i>-- Does not m
2f50: 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e  atch!</i>..  ...
2f60: 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 63 20   MATCH 'NEAR("c 
2f70: 64 22 20 22 65 20 66 22 2c 20 33 29 27 3b 20 20  d" "e f", 3)';  
2f80: 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2d              <i>-
2f90: 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20  - Matches!</i>. 
2fa0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
2fb0: 28 22 63 22 20 20 20 22 65 20 66 22 2c 20 33 29  ("c"   "e f", 3)
2fc0: 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ';              
2fd0: 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d  <i>-- Does not m
2fe0: 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e  atch!</i>..  ...
2ff0: 20 4d 41 54 43 48 20 27 4e 45 41 52 28 61 20 64   MATCH 'NEAR(a d
3000: 20 65 2c 20 36 29 27 3b 20 20 20 20 20 20 20 20   e, 6)';        
3010: 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2d              <i>-
3020: 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20  - Matches!</i>. 
3030: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
3040: 28 61 20 64 20 65 2c 20 35 29 27 3b 20 20 20 20  (a d e, 5)';    
3050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3060: 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d  <i>-- Does not m
3070: 61 74 63 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e  atch!</i>..  ...
3080: 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 61 20   MATCH 'NEAR("a 
3090: 62 20 63 20 64 22 20 22 62 20 63 22 20 22 65 20  b c d" "b c" "e 
30a0: 66 22 2c 20 34 29 27 3b 20 20 20 20 3c 69 3e 2d  f", 4)';    <i>-
30b0: 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20  - Matches!</i>. 
30c0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
30d0: 28 22 61 20 62 20 63 20 64 22 20 22 62 20 63 22  ("a b c d" "b c"
30e0: 20 22 65 20 66 22 2c 20 33 29 27 3b 20 20 20 20   "e f", 3)';    
30f0: 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d  <i>-- Does not m
3100: 61 74 63 68 21 3c 2f 69 3e 0a 0a 3c 2f 63 6f 64  atch!</i>..</cod
3110: 65 62 6c 6f 63 6b 3e 0a 0a 0a 3c 70 3e 0a 41 20  eblock>...<p>.A 
3120: 73 69 6e 67 6c 65 20 70 68 72 61 73 65 20 6f 72  single phrase or
3130: 20 4e 45 41 52 20 67 72 6f 75 70 20 6d 61 79 20   NEAR group may 
3140: 62 65 20 72 65 73 74 72 69 63 74 65 64 20 74 6f  be restricted to
3150: 20 6d 61 74 63 68 69 6e 67 20 74 65 78 74 20 77   matching text w
3160: 69 74 68 69 6e 20 61 0a 73 70 65 63 69 66 69 65  ithin a.specifie
3170: 64 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  d column of the 
3180: 46 54 53 20 74 61 62 6c 65 20 62 79 20 70 72 65  FTS table by pre
3190: 66 69 78 69 6e 67 20 69 74 20 77 69 74 68 20 74  fixing it with t
31a0: 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 0a  he column name .
31b0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 63 6f  followed by a co
31c0: 6c 6f 6e 20 63 68 61 72 61 63 74 65 72 2e 20 4f  lon character. O
31d0: 72 20 74 6f 20 61 20 73 65 74 20 6f 66 20 63 6f  r to a set of co
31e0: 6c 75 6d 6e 73 20 62 79 20 70 72 65 66 69 78 69  lumns by prefixi
31f0: 6e 67 20 69 74 0a 77 69 74 68 20 61 20 77 68 69  ng it.with a whi
3200: 74 65 73 70 61 63 65 20 73 65 70 61 72 61 74 65  tespace separate
3210: 64 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e  d list of column
3220: 20 6e 61 6d 65 73 20 65 6e 63 6c 6f 73 65 64 20   names enclosed 
3230: 69 6e 20 70 61 72 65 6e 74 68 65 73 69 73 0a 28  in parenthesis.(
3240: 22 63 75 72 6c 79 20 62 72 61 63 6b 65 74 73 22  "curly brackets"
3250: 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20  ) followed by a 
3260: 63 6f 6c 6f 6e 20 63 68 61 72 61 63 74 65 72 2e  colon character.
3270: 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 6d 61   Column names ma
3280: 79 20 62 65 20 73 70 65 63 69 66 69 65 64 0a 75  y be specified.u
3290: 73 69 6e 67 20 65 69 74 68 65 72 20 6f 66 20 74  sing either of t
32a0: 68 65 20 74 77 6f 20 66 6f 72 6d 73 20 64 65 73  he two forms des
32b0: 63 72 69 62 65 64 20 66 6f 72 20 73 74 72 69 6e  cribed for strin
32c0: 67 73 20 61 62 6f 76 65 2e 20 55 6e 6c 69 6b 65  gs above. Unlike
32d0: 20 73 74 72 69 6e 67 73 20 74 68 61 74 0a 61 72   strings that.ar
32e0: 65 20 70 61 72 74 20 6f 66 20 70 68 72 61 73 65  e part of phrase
32f0: 73 2c 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  s, column names 
3300: 61 72 65 20 6e 6f 74 20 70 61 73 73 65 64 20 74  are not passed t
3310: 6f 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65 72 20  o the tokenizer 
3320: 6d 6f 64 75 6c 65 2e 0a 43 6f 6c 75 6d 6e 20 6e  module..Column n
3330: 61 6d 65 73 20 61 72 65 20 63 61 73 65 2d 69 6e  ames are case-in
3340: 73 65 6e 73 69 74 69 76 65 20 69 6e 20 74 68 65  sensitive in the
3350: 20 75 73 75 61 6c 20 77 61 79 20 66 6f 72 20 53   usual way for S
3360: 51 4c 69 74 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  QLite column nam
3370: 65 73 20 2d 0a 75 70 70 65 72 2f 6c 6f 77 65 72  es -.upper/lower
3380: 20 63 61 73 65 20 65 71 75 69 76 61 6c 65 6e 63   case equivalenc
3390: 65 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  e is understood 
33a0: 66 6f 72 20 41 53 43 49 49 2d 72 61 6e 67 65 20  for ASCII-range 
33b0: 63 68 61 72 61 63 74 65 72 73 20 6f 6e 6c 79 2e  characters only.
33c0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
33d0: 2e 2e 2e 20 4d 41 54 43 48 20 27 63 6f 6c 6e 61  ... MATCH 'colna
33e0: 6d 65 20 3a 20 4e 45 41 52 28 22 6f 6e 65 20 74  me : NEAR("one t
33f0: 77 6f 22 20 22 74 68 72 65 65 20 66 6f 75 72 22  wo" "three four"
3400: 2c 20 31 30 29 27 0a 20 20 2e 2e 2e 20 4d 41 54  , 10)'.  ... MAT
3410: 43 48 20 27 22 63 6f 6c 6e 61 6d 65 22 20 3a 20  CH '"colname" : 
3420: 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68 72 65  one + two + thre
3430: 65 27 0a 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  e'..  ... MATCH 
3440: 27 7b 63 6f 6c 31 20 63 6f 6c 32 7d 20 3a 20 4e  '{col1 col2} : N
3450: 45 41 52 28 22 6f 6e 65 20 74 77 6f 22 20 22 74  EAR("one two" "t
3460: 68 72 65 65 20 66 6f 75 72 22 2c 20 31 30 29 27  hree four", 10)'
3470: 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 7b 63  .  ... MATCH '{c
3480: 6f 6c 32 20 63 6f 6c 31 20 63 6f 6c 33 7d 20 3a  ol2 col1 col3} :
3490: 20 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74 68 72   one + two + thr
34a0: 65 65 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  ee'.</codeblock>
34b0: 0a 0a 3c 70 3e 0a 49 66 20 61 20 63 6f 6c 75 6d  ..<p>.If a colum
34c0: 6e 20 66 69 6c 74 65 72 20 73 70 65 63 69 66 69  n filter specifi
34d0: 63 61 74 69 6f 6e 20 69 73 20 70 72 65 63 65 64  cation is preced
34e0: 65 64 20 62 79 20 61 20 22 2d 22 20 63 68 61 72  ed by a "-" char
34f0: 61 63 74 65 72 2c 20 74 68 65 6e 0a 69 74 20 69  acter, then.it i
3500: 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
3510: 20 61 20 6c 69 73 74 20 6f 66 20 63 6f 6c 75 6d   a list of colum
3520: 6e 20 6e 6f 74 20 74 6f 20 6d 61 74 63 68 20 61  n not to match a
3530: 67 61 69 6e 73 74 2e 20 46 6f 72 20 65 78 61 6d  gainst. For exam
3540: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
3550: 3e 0a 20 20 3c 69 3e 2d 2d 20 53 65 61 72 63 68  >.  <i>-- Search
3560: 20 66 6f 72 20 6d 61 74 63 68 65 73 20 69 6e 20   for matches in 
3570: 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20 65 78 63 65  all columns exce
3580: 70 74 20 22 63 6f 6c 6e 61 6d 65 22 3c 2f 69 3e  pt "colname"</i>
3590: 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 2d 20  .  ... MATCH '- 
35a0: 63 6f 6c 6e 61 6d 65 20 3a 20 4e 45 41 52 28 22  colname : NEAR("
35b0: 6f 6e 65 20 74 77 6f 22 20 22 74 68 72 65 65 20  one two" "three 
35c0: 66 6f 75 72 22 2c 20 31 30 29 27 0a 0a 20 20 3c  four", 10)'..  <
35d0: 69 3e 2d 2d 20 53 65 61 72 63 68 20 66 6f 72 20  i>-- Search for 
35e0: 6d 61 74 63 68 65 73 20 69 6e 20 61 6c 6c 20 63  matches in all c
35f0: 6f 6c 75 6d 6e 73 20 65 78 63 65 70 74 20 22 63  olumns except "c
3600: 6f 6c 31 22 2c 20 22 63 6f 6c 32 22 20 61 6e 64  ol1", "col2" and
3610: 20 22 63 6f 6c 33 22 3c 2f 69 3e 0a 20 20 2e 2e   "col3"</i>.  ..
3620: 2e 20 4d 41 54 43 48 20 27 2d 20 7b 63 6f 6c 32  . MATCH '- {col2
3630: 20 63 6f 6c 31 20 63 6f 6c 33 7d 20 3a 20 6f 6e   col1 col3} : on
3640: 65 20 2b 20 74 77 6f 20 2b 20 74 68 72 65 65 27  e + two + three'
3650: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
3660: 70 3e 0a 50 68 72 61 73 65 73 20 61 6e 64 20 4e  p>.Phrases and N
3670: 45 41 52 20 67 72 6f 75 70 73 20 6d 61 79 20 62  EAR groups may b
3680: 65 20 61 72 72 61 6e 67 65 64 20 69 6e 74 6f 20  e arranged into 
3690: 65 78 70 72 65 73 73 69 6f 6e 73 20 75 73 69 6e  expressions usin
36a0: 67 20 3c 62 3e 62 6f 6f 6c 65 61 6e 0a 6f 70 65  g <b>boolean.ope
36b0: 72 61 74 6f 72 73 3c 2f 62 3e 2e 20 49 6e 20 6f  rators</b>. In o
36c0: 72 64 65 72 20 6f 66 20 70 72 65 63 65 64 65 6e  rder of preceden
36d0: 63 65 2c 20 66 72 6f 6d 20 68 69 67 68 65 73 74  ce, from highest
36e0: 20 28 74 69 67 68 74 65 73 74 20 67 72 6f 75 70   (tightest group
36f0: 69 6e 67 29 20 74 6f 0a 6c 6f 77 65 73 74 20 28  ing) to.lowest (
3700: 6c 6f 6f 73 65 73 74 20 67 72 6f 75 70 69 6e 67  loosest grouping
3710: 29 2c 20 74 68 65 20 6f 70 65 72 61 74 6f 72 73  ), the operators
3720: 20 61 72 65 3a 0a 0a 3c 74 61 62 6c 65 20 73 74   are:..<table st
3730: 72 69 70 65 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c  riped=1>.  <tr><
3740: 74 68 3e 4f 70 65 72 61 74 6f 72 20 3c 74 68 3e  th>Operator <th>
3750: 46 75 6e 63 74 69 6f 6e 0a 0a 20 20 3c 74 72 3e  Function..  <tr>
3760: 3c 74 64 3e 3c 63 6f 64 65 3e 26 6c 74 3b 71 75  <td><code>&lt;qu
3770: 65 72 79 31 26 67 74 3b 20 4e 4f 54 20 26 6c 74  ery1&gt; NOT &lt
3780: 3b 71 75 65 72 79 32 26 67 74 3b 3c 2f 63 6f 64  ;query2&gt;</cod
3790: 65 3e 20 0a 20 20 20 20 20 20 3c 74 64 3e 4d 61  e> .      <td>Ma
37a0: 74 63 68 65 73 20 69 66 20 71 75 65 72 79 31 20  tches if query1 
37b0: 6d 61 74 63 68 65 73 20 61 6e 64 20 71 75 65 72  matches and quer
37c0: 79 32 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  y2 does not matc
37d0: 68 2e 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e 3c 63  h...  <tr><td><c
37e0: 6f 64 65 3e 26 6c 74 3b 71 75 65 72 79 31 26 67  ode>&lt;query1&g
37f0: 74 3b 20 41 4e 44 20 26 6c 74 3b 71 75 65 72 79  t; AND &lt;query
3800: 32 26 67 74 3b 3c 2f 63 6f 64 65 3e 20 0a 20 20  2&gt;</code> .  
3810: 20 20 20 20 3c 74 64 3e 4d 61 74 63 68 65 73 20      <td>Matches 
3820: 69 66 20 62 6f 74 68 20 71 75 65 72 79 31 20 61  if both query1 a
3830: 6e 64 20 71 75 65 72 79 32 20 6d 61 74 63 68 2e  nd query2 match.
3840: 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e 3c 63 6f 64  ..  <tr><td><cod
3850: 65 3e 26 6c 74 3b 71 75 65 72 79 31 26 67 74 3b  e>&lt;query1&gt;
3860: 20 4f 52 20 26 6c 74 3b 71 75 65 72 79 32 26 67   OR &lt;query2&g
3870: 74 3b 3c 2f 63 6f 64 65 3e 20 0a 20 20 20 20 20  t;</code> .     
3880: 20 3c 74 64 3e 4d 61 74 63 68 65 73 20 69 66 20   <td>Matches if 
3890: 65 69 74 68 65 72 20 71 75 65 72 79 31 20 6f 72  either query1 or
38a0: 20 71 75 65 72 79 32 20 6d 61 74 63 68 2e 0a 0a   query2 match...
38b0: 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 0a 50 61  </table>..<p>.Pa
38c0: 72 65 6e 74 68 65 73 69 73 20 6d 61 79 20 62 65  renthesis may be
38d0: 20 75 73 65 64 20 74 6f 20 67 72 6f 75 70 20 65   used to group e
38e0: 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 20 6f 72  xpressions in or
38f0: 64 65 72 20 74 6f 20 6d 6f 64 69 66 79 20 6f 70  der to modify op
3900: 65 72 61 74 6f 72 0a 70 72 65 63 65 64 65 6e 63  erator.precedenc
3910: 65 20 69 6e 20 74 68 65 20 75 73 75 61 6c 20 77  e in the usual w
3920: 61 79 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ays. For example
3930: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
3940: 20 3c 69 3e 2d 2d 20 4d 61 74 63 68 65 73 20 64   <i>-- Matches d
3950: 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f  ocuments that co
3960: 6e 74 61 69 6e 20 61 74 20 6c 65 61 73 74 20 6f  ntain at least o
3970: 6e 65 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 65  ne instance of e
3980: 69 74 68 65 72 20 22 6f 6e 65 22 3c 2f 69 3e 0a  ither "one"</i>.
3990: 20 20 3c 69 3e 2d 2d 20 6f 72 20 22 74 77 6f 22    <i>-- or "two"
39a0: 2c 20 62 75 74 20 64 6f 20 6e 6f 74 20 63 6f 6e  , but do not con
39b0: 74 61 69 6e 20 61 6e 79 20 69 6e 73 74 61 6e 63  tain any instanc
39c0: 65 73 20 6f 66 20 74 6f 6b 65 6e 20 22 74 68 72  es of token "thr
39d0: 65 65 22 2e 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d  ee".</i>.  ... M
39e0: 41 54 43 48 20 27 6f 6e 65 20 4f 52 20 74 77 6f  ATCH 'one OR two
39f0: 20 4e 4f 54 20 74 68 72 65 65 27 0a 0a 20 20 3c   NOT three'..  <
3a00: 69 3e 2d 2d 20 4d 61 74 63 68 20 61 6c 6c 20 64  i>-- Match all d
3a10: 6f 63 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f  ocuments that co
3a20: 6e 74 61 69 6e 20 74 68 65 20 74 6f 6b 65 6e 20  ntain the token 
3a30: 22 74 77 6f 22 20 62 75 74 20 6e 6f 74 20 22 74  "two" but not "t
3a40: 68 72 65 65 22 2c 20 6f 72 3c 2f 69 3e 0a 20 20  hree", or</i>.  
3a50: 3c 69 3e 2d 2d 20 63 6f 6e 74 61 69 6e 20 74 68  <i>-- contain th
3a60: 65 20 74 6f 6b 65 6e 20 22 6f 6e 65 22 2e 3c 2f  e token "one".</
3a70: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
3a80: 6f 6e 65 20 4f 52 20 28 74 77 6f 20 4e 4f 54 20  one OR (two NOT 
3a90: 74 68 72 65 65 29 27 0a 3c 2f 63 6f 64 65 62 6c  three)'.</codebl
3aa0: 6f 63 6b 3e 0a 0a 3c 70 3e 0a 50 68 72 61 73 65  ock>..<p>.Phrase
3ab0: 73 20 61 6e 64 20 4e 45 41 52 20 67 72 6f 75 70  s and NEAR group
3ac0: 73 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 63 6f  s may also be co
3ad0: 6e 6e 65 63 74 65 64 20 62 79 20 3c 62 3e 69 6d  nnected by <b>im
3ae0: 70 6c 69 63 69 74 20 41 4e 44 20 6f 70 65 72 61  plicit AND opera
3af0: 74 6f 72 73 3c 2f 62 3e 2e 0a 46 6f 72 20 73 69  tors</b>..For si
3b00: 6d 70 6c 69 63 69 74 79 2c 20 74 68 65 73 65 20  mplicity, these 
3b10: 61 72 65 20 6e 6f 74 20 73 68 6f 77 6e 20 69 6e  are not shown in
3b20: 20 74 68 65 20 42 4e 46 20 67 72 61 6d 6d 61 72   the BNF grammar
3b30: 20 61 62 6f 76 65 2e 20 45 73 73 65 6e 74 69 61   above. Essentia
3b40: 6c 6c 79 2c 20 61 6e 79 0a 73 65 71 75 65 6e 63  lly, any.sequenc
3b50: 65 20 6f 66 20 70 68 72 61 73 65 73 20 6f 72 20  e of phrases or 
3b60: 4e 45 41 52 20 67 72 6f 75 70 73 20 28 69 6e 63  NEAR groups (inc
3b70: 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 72 65 73  luding those res
3b80: 74 72 69 63 74 65 64 20 74 6f 20 6d 61 74 63 68  tricted to match
3b90: 69 6e 67 0a 73 70 65 63 69 66 69 65 64 20 63 6f  ing.specified co
3ba0: 6c 75 6d 6e 73 29 20 73 65 70 61 72 61 74 65 64  lumns) separated
3bb0: 20 6f 6e 6c 79 20 62 79 20 77 68 69 74 65 73 70   only by whitesp
3bc0: 61 63 65 20 61 72 65 20 68 61 6e 64 6c 65 64 20  ace are handled 
3bd0: 61 73 20 69 66 20 74 68 65 72 65 20 77 65 72 65  as if there were
3be0: 20 61 6e 0a 69 6d 70 6c 69 63 69 74 20 41 4e 44   an.implicit AND
3bf0: 20 6f 70 65 72 61 74 6f 72 20 62 65 74 77 65 65   operator betwee
3c00: 6e 20 65 61 63 68 20 70 61 69 72 20 6f 66 20 70  n each pair of p
3c10: 68 72 61 73 65 73 20 6f 72 20 4e 45 41 52 20 67  hrases or NEAR g
3c20: 72 6f 75 70 73 2e 20 49 6d 70 6c 69 63 69 74 0a  roups. Implicit.
3c30: 41 4e 44 20 6f 70 65 72 61 74 6f 72 73 20 61 72  AND operators ar
3c40: 65 20 6e 65 76 65 72 20 69 6e 73 65 72 74 65 64  e never inserted
3c50: 20 61 66 74 65 72 20 6f 72 20 62 65 66 6f 72 65   after or before
3c60: 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 65   an expression e
3c70: 6e 63 6c 6f 73 65 64 20 69 6e 0a 70 61 72 65 6e  nclosed in.paren
3c80: 74 68 65 73 69 73 2e 20 46 6f 72 20 65 78 61 6d  thesis. For exam
3c90: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
3ca0: 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 6f  >.  ... MATCH 'o
3cb0: 6e 65 20 74 77 6f 20 74 68 72 65 65 27 20 20 20  ne two three'   
3cc0: 20 20 20 20 20 20 3c 69 3e 2d 2d 20 27 6f 6e 65        <i>-- 'one
3cd0: 20 41 4e 44 20 74 77 6f 20 41 4e 44 20 74 68 72   AND two AND thr
3ce0: 65 65 27 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41  ee'</i>.  ... MA
3cf0: 54 43 48 20 27 74 68 72 65 65 20 22 6f 6e 65 20  TCH 'three "one 
3d00: 74 77 6f 22 27 20 20 20 20 20 20 20 3c 69 3e 2d  two"'       <i>-
3d10: 2d 20 27 74 68 72 65 65 20 41 4e 44 20 22 6f 6e  - 'three AND "on
3d20: 65 20 74 77 6f 22 27 3c 2f 69 3e 0a 20 20 2e 2e  e two"'</i>.  ..
3d30: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 6f 6e  . MATCH 'NEAR(on
3d40: 65 20 74 77 6f 29 20 74 68 72 65 65 27 20 20 20  e two) three'   
3d50: 3c 69 3e 2d 2d 20 27 4e 45 41 52 28 6f 6e 65 20  <i>-- 'NEAR(one 
3d60: 74 77 6f 29 20 41 4e 44 20 74 68 72 65 65 27 3c  two) AND three'<
3d70: 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  /i>.  ... MATCH 
3d80: 27 6f 6e 65 20 4f 52 20 74 77 6f 20 74 68 72 65  'one OR two thre
3d90: 65 27 20 20 20 20 20 20 3c 69 3e 2d 2d 20 27 6f  e'      <i>-- 'o
3da0: 6e 65 20 4f 52 20 74 77 6f 20 41 4e 44 20 74 68  ne OR two AND th
3db0: 72 65 65 27 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e 20  ree'</i>..  ... 
3dc0: 4d 41 54 43 48 20 27 28 6f 6e 65 20 4f 52 20 74  MATCH '(one OR t
3dd0: 77 6f 29 20 74 68 72 65 65 27 20 20 20 20 3c 69  wo) three'    <i
3de0: 3e 2d 2d 20 53 79 6e 74 61 78 20 65 72 72 6f 72  >-- Syntax error
3df0: 21 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  !</i>.  ... MATC
3e00: 48 20 27 66 75 6e 63 28 6f 6e 65 20 74 77 6f 29  H 'func(one two)
3e10: 27 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20  '         <i>-- 
3e20: 53 79 6e 74 61 78 20 65 72 72 6f 72 21 3c 2f 69  Syntax error!</i
3e30: 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  >.</codeblock>..
3e40: 3c 68 31 20 74 61 67 73 3d 22 46 54 53 35 20 43  <h1 tags="FTS5 C
3e50: 52 45 41 54 45 20 54 41 42 4c 45 20 4f 70 74 69  REATE TABLE Opti
3e60: 6f 6e 73 22 3e 46 54 53 35 20 54 61 62 6c 65 20  ons">FTS5 Table 
3e70: 43 72 65 61 74 69 6f 6e 20 61 6e 64 20 49 6e 69  Creation and Ini
3e80: 74 69 61 6c 69 7a 61 74 69 6f 6e 3c 2f 68 31 3e  tialization</h1>
3e90: 0a 0a 3c 70 3e 45 61 63 68 20 61 72 67 75 6d 65  ..<p>Each argume
3ea0: 6e 74 20 73 70 65 63 69 66 69 65 64 20 61 73 20  nt specified as 
3eb0: 70 61 72 74 20 6f 66 20 61 20 22 43 52 45 41 54  part of a "CREAT
3ec0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
3ed0: 2e 2e 2e 20 55 53 49 4e 47 20 66 74 73 35 20 0a  ... USING fts5 .
3ee0: 2e 2e 2e 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ..." statement i
3ef0: 73 20 65 69 74 68 65 72 20 61 20 63 6f 6c 75 6d  s either a colum
3f00: 6e 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 6f 72  n declaration or
3f10: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
3f20: 20 6f 70 74 69 6f 6e 2e 20 41 0a 3c 62 3e 63 6f   option. A.<b>co
3f30: 6c 75 6d 6e 20 64 65 63 6c 61 72 61 74 69 6f 6e  lumn declaration
3f40: 3c 2f 62 3e 20 63 6f 6e 73 69 73 74 73 20 6f 66  </b> consists of
3f50: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 77 68 69   one or more whi
3f60: 74 65 73 70 61 63 65 20 73 65 70 61 72 61 74 65  tespace separate
3f70: 64 20 46 54 53 35 0a 62 61 72 65 77 6f 72 64 73  d FTS5.barewords
3f80: 20 6f 72 20 73 74 72 69 6e 67 20 6c 69 74 65 72   or string liter
3f90: 61 6c 73 20 71 75 6f 74 65 64 20 69 6e 20 61 6e  als quoted in an
3fa0: 79 20 6d 61 6e 6e 65 72 20 61 63 63 65 70 74 61  y manner accepta
3fb0: 62 6c 65 20 74 6f 20 53 51 4c 69 74 65 2e 0a 0a  ble to SQLite...
3fc0: 3c 70 3e 54 68 65 20 66 69 72 73 74 20 73 74 72  <p>The first str
3fd0: 69 6e 67 20 6f 72 20 62 61 72 65 77 6f 72 64 20  ing or bareword 
3fe0: 69 6e 20 61 20 63 6f 6c 75 6d 6e 20 64 65 63 6c  in a column decl
3ff0: 61 72 61 74 69 6f 6e 20 69 73 20 74 68 65 20 63  aration is the c
4000: 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 20 49 74 0a 69  olumn name. It.i
4010: 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 61 74  s an error to at
4020: 74 65 6d 70 74 20 74 6f 20 6e 61 6d 65 20 61 6e  tempt to name an
4030: 20 66 74 73 35 20 74 61 62 6c 65 20 63 6f 6c 75   fts5 table colu
4040: 6d 6e 20 22 72 6f 77 69 64 22 20 6f 72 20 22 72  mn "rowid" or "r
4050: 61 6e 6b 22 2c 20 6f 72 20 74 6f 0a 61 73 73 69  ank", or to.assi
4060: 67 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  gn the same name
4070: 20 74 6f 20 61 20 63 6f 6c 75 6d 6e 20 61 73 20   to a column as 
4080: 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 74  is used by the t
4090: 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 54 68 69  able itself. Thi
40a0: 73 20 69 73 20 6e 6f 74 0a 73 75 70 70 6f 72 74  s is not.support
40b0: 65 64 2e 0a 0a 3c 70 3e 45 61 63 68 20 73 75 62  ed...<p>Each sub
40c0: 73 65 71 75 65 6e 74 20 73 74 72 69 6e 67 20 6f  sequent string o
40d0: 72 20 62 61 72 65 77 6f 72 64 20 69 6e 20 61 20  r bareword in a 
40e0: 63 6f 6c 75 6d 6e 20 64 65 63 6c 61 72 61 74 69  column declarati
40f0: 6f 6e 20 69 73 20 61 20 63 6f 6c 75 6d 6e 0a 6f  on is a column.o
4100: 70 74 69 6f 6e 20 74 68 61 74 20 6d 6f 64 69 66  ption that modif
4110: 69 65 73 20 74 68 65 20 62 65 68 61 76 69 6f 75  ies the behaviou
4120: 72 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r of that column
4130: 2e 20 43 6f 6c 75 6d 6e 20 6f 70 74 69 6f 6e 73  . Column options
4140: 20 61 72 65 0a 63 61 73 65 2d 69 6e 64 65 70 65   are.case-indepe
4150: 6e 64 65 6e 74 2e 20 55 6e 6c 69 6b 65 20 74 68  ndent. Unlike th
4160: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2c 20 46  e SQLite core, F
4170: 54 53 35 20 63 6f 6e 73 69 64 65 72 73 20 75 6e  TS5 considers un
4180: 72 65 63 6f 67 6e 69 7a 65 64 20 63 6f 6c 75 6d  recognized colum
4190: 6e 0a 6f 70 74 69 6f 6e 73 20 74 6f 20 62 65 20  n.options to be 
41a0: 65 72 72 6f 72 73 2e 20 43 75 72 72 65 6e 74 6c  errors. Currentl
41b0: 79 2c 20 74 68 65 20 6f 6e 6c 79 20 6f 70 74 69  y, the only opti
41c0: 6f 6e 20 72 65 63 6f 67 6e 69 7a 65 64 20 69 73  on recognized is
41d0: 20 0a 5b 75 6e 69 6e 64 65 78 65 64 20 7c 20 22   .[unindexed | "
41e0: 55 4e 49 4e 44 45 58 45 44 22 20 28 73 65 65 20  UNINDEXED" (see 
41f0: 62 65 6c 6f 77 29 5d 2e 0a 0a 3c 70 3e 41 20 3c  below)]...<p>A <
4200: 62 3e 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  b>configuration 
4210: 6f 70 74 69 6f 6e 3c 2f 62 3e 20 63 6f 6e 73 69  option</b> consi
4220: 73 74 73 20 6f 66 20 61 6e 20 46 54 53 35 20 62  sts of an FTS5 b
4230: 61 72 65 77 6f 72 64 20 2d 20 74 68 65 20 6f 70  areword - the op
4240: 74 69 6f 6e 20 6e 61 6d 65 20 2d 0a 66 6f 6c 6c  tion name -.foll
4250: 6f 77 65 64 20 62 79 20 61 6e 20 22 3d 22 20 63  owed by an "=" c
4260: 68 61 72 61 63 74 65 72 2c 20 66 6f 6c 6c 6f 77  haracter, follow
4270: 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
4280: 20 76 61 6c 75 65 2e 20 54 68 65 20 6f 70 74 69   value. The opti
4290: 6f 6e 20 76 61 6c 75 65 20 69 73 0a 73 70 65 63  on value is.spec
42a0: 69 66 69 65 64 20 75 73 69 6e 67 20 65 69 74 68  ified using eith
42b0: 65 72 20 61 20 73 69 6e 67 6c 65 20 46 54 53 35  er a single FTS5
42c0: 20 62 61 72 65 77 6f 72 64 20 6f 72 20 61 20 73   bareword or a s
42d0: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2c 20 61  tring literal, a
42e0: 67 61 69 6e 20 71 75 6f 74 65 64 0a 69 6e 20 61  gain quoted.in a
42f0: 6e 79 20 6d 61 6e 6e 65 72 20 61 63 63 65 70 74  ny manner accept
4300: 61 62 6c 65 20 74 6f 20 74 68 65 20 53 51 4c 69  able to the SQLi
4310: 74 65 20 63 6f 72 65 2e 20 46 6f 72 20 65 78 61  te core. For exa
4320: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
4330: 6b 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  k>.  CREATE VIRT
4340: 55 41 4c 20 54 41 42 4c 45 20 6d 61 69 6c 20 55  UAL TABLE mail U
4350: 53 49 4e 47 20 66 74 73 35 28 73 65 6e 64 65 72  SING fts5(sender
4360: 2c 20 74 69 74 6c 65 2c 20 62 6f 64 79 2c 20 74  , title, body, t
4370: 6f 6b 65 6e 69 7a 65 20 3d 20 27 70 6f 72 74 65  okenize = 'porte
4380: 72 20 61 73 63 69 69 27 29 3b 0a 3c 2f 63 6f 64  r ascii');.</cod
4390: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65  eblock>..<p> The
43a0: 72 65 20 61 72 65 20 63 75 72 72 65 6e 74 6c 79  re are currently
43b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
43c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
43d0: 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  ions:..<ul>.  <l
43e0: 69 3e 20 54 68 65 20 22 74 6f 6b 65 6e 69 7a 65  i> The "tokenize
43f0: 22 20 6f 70 74 69 6f 6e 2c 20 75 73 65 64 20 74  " option, used t
4400: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 20 5b 46  o configure a [F
4410: 54 53 35 20 74 6f 6b 65 6e 69 7a 65 72 73 20 7c  TS5 tokenizers |
4420: 20 63 75 73 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65   custom tokenize
4430: 72 5d 2e 0a 20 20 3c 6c 69 3e 20 54 68 65 20 22  r]..  <li> The "
4440: 70 72 65 66 69 78 22 20 6f 70 74 69 6f 6e 2c 20  prefix" option, 
4450: 75 73 65 64 20 74 6f 20 61 64 64 20 5b 46 54 53  used to add [FTS
4460: 35 20 70 72 65 66 69 78 20 69 6e 64 65 78 65 73  5 prefix indexes
4470: 20 7c 20 70 72 65 66 69 78 20 69 6e 64 65 78 65   | prefix indexe
4480: 73 5d 0a 20 20 20 20 20 20 20 74 6f 20 61 6e 20  s].       to an 
4490: 46 54 53 35 20 74 61 62 6c 65 2e 0a 20 20 3c 6c  FTS5 table..  <l
44a0: 69 3e 20 54 68 65 20 22 63 6f 6e 74 65 6e 74 22  i> The "content"
44b0: 20 6f 70 74 69 6f 6e 2c 20 75 73 65 64 20 74 6f   option, used to
44c0: 20 6d 61 6b 65 20 74 68 65 20 46 54 53 35 20 74   make the FTS5 t
44d0: 61 62 6c 65 20 61 6e 20 0a 20 20 20 20 20 20 20  able an .       
44e0: 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 20 6f 70  [FTS5 content op
44f0: 74 69 6f 6e 20 7c 20 65 78 74 65 72 6e 61 6c 20  tion | external 
4500: 63 6f 6e 74 65 6e 74 20 6f 72 20 63 6f 6e 74 65  content or conte
4510: 6e 74 6c 65 73 73 20 74 61 62 6c 65 5d 2e 0a 20  ntless table].. 
4520: 20 3c 6c 69 3e 20 54 68 65 20 22 63 6f 6e 74 65   <li> The "conte
4530: 6e 74 5f 72 6f 77 69 64 22 20 6f 70 74 69 6f 6e  nt_rowid" option
4540: 2c 20 75 73 65 64 20 74 6f 20 73 65 74 20 74 68  , used to set th
4550: 65 20 72 6f 77 69 64 20 66 69 65 6c 64 20 6f 66  e rowid field of
4560: 20 61 6e 20 0a 20 20 20 20 20 20 20 5b 46 54 53   an .       [FTS
4570: 35 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  5 external conte
4580: 6e 74 20 74 61 62 6c 65 73 20 7c 20 65 78 74 65  nt tables | exte
4590: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62  rnal content tab
45a0: 6c 65 5d 2e 0a 20 20 3c 6c 69 3e 20 54 68 65 20  le]..  <li> The 
45b0: 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 73 69 7a 65  [FTS5 columnsize
45c0: 20 6f 70 74 69 6f 6e 20 7c 20 22 63 6f 6c 75 6d   option | "colum
45d0: 6e 73 69 7a 65 22 20 6f 70 74 69 6f 6e 5d 2c 20  nsize" option], 
45e0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
45f0: 65 0a 20 20 20 20 20 20 20 77 68 65 74 68 65 72  e.       whether
4600: 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 69 7a 65   or not the size
4610: 20 69 6e 20 74 6f 6b 65 6e 73 20 6f 66 20 65 61   in tokens of ea
4620: 63 68 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20  ch value in the 
4630: 46 54 53 35 20 74 61 62 6c 65 20 69 73 0a 20 20  FTS5 table is.  
4640: 20 20 20 20 20 73 74 6f 72 65 64 20 73 65 70 61       stored sepa
4650: 72 61 74 65 6c 79 20 77 69 74 68 69 6e 20 74 68  rately within th
4660: 65 20 64 61 74 61 62 61 73 65 2e 0a 20 20 3c 6c  e database..  <l
4670: 69 3e 20 54 68 65 20 5b 46 54 53 35 20 64 65 74  i> The [FTS5 det
4680: 61 69 6c 20 6f 70 74 69 6f 6e 20 7c 20 22 64 65  ail option | "de
4690: 74 61 69 6c 22 20 6f 70 74 69 6f 6e 5d 2e 20 54  tail" option]. T
46a0: 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  his option may b
46b0: 65 20 75 73 65 64 20 0a 20 20 20 20 20 20 20 74  e used .       t
46c0: 6f 20 72 65 64 75 63 65 20 74 68 65 20 73 69 7a  o reduce the siz
46d0: 65 20 6f 66 20 74 68 65 20 46 54 53 20 69 6e 64  e of the FTS ind
46e0: 65 78 20 6f 6e 20 64 69 73 6b 20 62 79 20 6f 6d  ex on disk by om
46f0: 69 74 74 69 6e 67 20 73 6f 6d 65 20 69 6e 66 6f  itting some info
4700: 72 6d 61 74 69 6f 6e 0a 20 20 20 20 20 20 20 66  rmation.       f
4710: 72 6f 6d 20 69 74 2e 20 20 0a 3c 2f 75 6c 3e 0a  rom it.  .</ul>.
4720: 0a 3c 68 32 20 74 61 67 73 3d 22 75 6e 69 6e 64  .<h2 tags="unind
4730: 65 78 65 64 22 3e 54 68 65 20 55 4e 49 4e 44 45  exed">The UNINDE
4740: 58 45 44 20 63 6f 6c 75 6d 6e 20 6f 70 74 69 6f  XED column optio
4750: 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 63  n</h2>..<p>The c
4760: 6f 6e 74 65 6e 74 73 20 6f 66 20 63 6f 6c 75 6d  ontents of colum
4770: 6e 73 20 71 75 61 6c 69 66 69 65 64 20 77 69 74  ns qualified wit
4780: 68 20 74 68 65 20 55 4e 49 4e 44 45 58 45 44 20  h the UNINDEXED 
4790: 63 6f 6c 75 6d 6e 20 6f 70 74 69 6f 6e 20 61 72  column option ar
47a0: 65 20 6e 6f 74 0a 61 64 64 65 64 20 74 6f 20 74  e not.added to t
47b0: 68 65 20 46 54 53 20 69 6e 64 65 78 2e 20 54 68  he FTS index. Th
47c0: 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 66 6f  is means that fo
47d0: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
47e0: 66 20 4d 41 54 43 48 20 71 75 65 72 69 65 73 20  f MATCH queries 
47f0: 61 6e 64 0a 5b 46 54 53 35 20 61 75 78 69 6c 69  and.[FTS5 auxili
4800: 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 20  ary functions], 
4810: 74 68 65 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61  the column conta
4820: 69 6e 73 20 6e 6f 20 6d 61 74 63 68 61 62 6c 65  ins no matchable
4830: 20 74 6f 6b 65 6e 73 2e 20 0a 0a 3c 70 3e 46 6f   tokens. ..<p>Fo
4840: 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 76  r example, to av
4850: 6f 69 64 20 61 64 64 69 6e 67 20 74 68 65 20 63  oid adding the c
4860: 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 22  ontents of the "
4870: 75 75 69 64 22 20 66 69 65 6c 64 20 74 6f 20 74  uuid" field to t
4880: 68 65 20 46 54 53 0a 69 6e 64 65 78 3a 0a 3c 63  he FTS.index:.<c
4890: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 43 52 45 41  odeblock>.  CREA
48a0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
48b0: 20 63 75 73 74 6f 6d 65 72 73 20 55 53 49 4e 47   customers USING
48c0: 20 66 74 73 35 28 6e 61 6d 65 2c 20 61 64 64 72   fts5(name, addr
48d0: 2c 20 75 75 69 64 20 55 4e 49 4e 44 45 58 45 44  , uuid UNINDEXED
48e0: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
48f0: 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20  .<h2 tags="FTS5 
4900: 70 72 65 66 69 78 20 69 6e 64 65 78 65 73 22 3e  prefix indexes">
4910: 50 72 65 66 69 78 20 49 6e 64 65 78 65 73 3c 2f  Prefix Indexes</
4920: 68 32 3e 0a 0a 3c 70 3e 20 42 79 20 64 65 66 61  h2>..<p> By defa
4930: 75 6c 74 2c 20 46 54 53 35 20 6d 61 69 6e 74 61  ult, FTS5 mainta
4940: 69 6e 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 64  ins a single ind
4950: 65 78 20 72 65 63 6f 72 64 69 6e 67 20 74 68 65  ex recording the
4960: 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 65 61 63   location of eac
4970: 68 0a 74 6f 6b 65 6e 20 69 6e 73 74 61 6e 63 65  h.token instance
4980: 20 77 69 74 68 69 6e 20 74 68 65 20 64 6f 63 75   within the docu
4990: 6d 65 6e 74 20 73 65 74 2e 20 54 68 69 73 20 6d  ment set. This m
49a0: 65 61 6e 73 20 74 68 61 74 20 71 75 65 72 79 69  eans that queryi
49b0: 6e 67 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 0a  ng for complete.
49c0: 74 6f 6b 65 6e 73 20 69 73 20 66 61 73 74 2c 20  tokens is fast, 
49d0: 61 73 20 69 74 20 72 65 71 75 69 72 65 73 20 61  as it requires a
49e0: 20 73 69 6e 67 6c 65 20 6c 6f 6f 6b 75 70 2c 20   single lookup, 
49f0: 62 75 74 20 71 75 65 72 79 69 6e 67 20 66 6f 72  but querying for
4a00: 20 61 20 70 72 65 66 69 78 20 0a 74 6f 6b 65 6e   a prefix .token
4a10: 20 63 61 6e 20 62 65 20 73 6c 6f 77 2c 20 61 73   can be slow, as
4a20: 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 72   it requires a r
4a30: 61 6e 67 65 20 73 63 61 6e 2e 20 46 6f 72 20 65  ange scan. For e
4a40: 78 61 6d 70 6c 65 2c 20 74 6f 20 71 75 65 72 79  xample, to query
4a50: 20 66 6f 72 0a 74 68 65 20 70 72 65 66 69 78 20   for.the prefix 
4a60: 74 6f 6b 65 6e 20 22 61 62 63 2a 22 20 72 65 71  token "abc*" req
4a70: 75 69 72 65 73 20 61 20 72 61 6e 67 65 20 73 63  uires a range sc
4a80: 61 6e 20 6f 66 20 61 6c 6c 20 74 6f 6b 65 6e 73  an of all tokens
4a90: 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 6f 72   greater than.or
4aa0: 20 65 71 75 61 6c 20 74 6f 20 22 61 62 63 22 20   equal to "abc" 
4ab0: 61 6e 64 20 6c 65 73 73 20 74 68 61 6e 20 22 61  and less than "a
4ac0: 62 64 22 2e 0a 0a 3c 70 3e 20 41 20 70 72 65 66  bd"...<p> A pref
4ad0: 69 78 20 69 6e 64 65 78 20 69 73 20 61 20 73 65  ix index is a se
4ae0: 70 61 72 61 74 65 20 69 6e 64 65 78 20 74 68 61  parate index tha
4af0: 74 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 6f  t records the lo
4b00: 63 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 0a 69 6e  cation of all.in
4b10: 73 74 61 6e 63 65 73 20 6f 66 20 70 72 65 66 69  stances of prefi
4b20: 78 20 74 6f 6b 65 6e 73 20 6f 66 20 61 20 63 65  x tokens of a ce
4b30: 72 74 61 69 6e 20 6c 65 6e 67 74 68 20 69 6e 20  rtain length in 
4b40: 63 68 61 72 61 63 74 65 72 73 20 75 73 65 64 20  characters used 
4b50: 74 6f 20 73 70 65 65 64 0a 75 70 20 71 75 65 72  to speed.up quer
4b60: 69 65 73 20 66 6f 72 20 70 72 65 66 69 78 20 74  ies for prefix t
4b70: 6f 6b 65 6e 73 2e 20 46 6f 72 20 65 78 61 6d 70  okens. For examp
4b80: 6c 65 2c 20 6f 70 74 69 6d 69 7a 69 6e 67 20 61  le, optimizing a
4b90: 20 71 75 65 72 79 20 66 6f 72 20 70 72 65 66 69   query for prefi
4ba0: 78 0a 74 6f 6b 65 6e 20 22 61 62 63 2a 22 20 72  x.token "abc*" r
4bb0: 65 71 75 69 72 65 73 20 61 20 70 72 65 66 69 78  equires a prefix
4bc0: 20 69 6e 64 65 78 20 6f 66 20 74 68 72 65 65 2d   index of three-
4bd0: 63 68 61 72 61 63 74 65 72 20 70 72 65 66 69 78  character prefix
4be0: 65 73 2e 0a 0a 3c 70 3e 20 54 6f 20 61 64 64 20  es...<p> To add 
4bf0: 70 72 65 66 69 78 20 69 6e 64 65 78 65 73 20 74  prefix indexes t
4c00: 6f 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65 2c  o an FTS5 table,
4c10: 20 74 68 65 20 22 70 72 65 66 69 78 22 20 6f 70   the "prefix" op
4c20: 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 65  tion is set to.e
4c30: 69 74 68 65 72 20 61 20 73 69 6e 67 6c 65 20 70  ither a single p
4c40: 6f 73 69 74 69 76 65 20 69 6e 74 65 67 65 72 20  ositive integer 
4c50: 6f 72 20 61 20 74 65 78 74 20 76 61 6c 75 65 20  or a text value 
4c60: 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 77 68 69  containing a whi
4c70: 74 65 2d 73 70 61 63 65 0a 73 65 70 61 72 61 74  te-space.separat
4c80: 65 64 20 6c 69 73 74 20 6f 66 20 6f 6e 65 20 6f  ed list of one o
4c90: 72 20 6d 6f 72 65 20 70 6f 73 69 74 69 76 65 20  r more positive 
4ca0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 2e 20  integer values. 
4cb0: 41 20 70 72 65 66 69 78 20 69 6e 64 65 78 20 69  A prefix index i
4cc0: 73 0a 63 72 65 61 74 65 64 20 66 6f 72 20 65 61  s.created for ea
4cd0: 63 68 20 69 6e 74 65 67 65 72 20 73 70 65 63 69  ch integer speci
4ce0: 66 69 65 64 2e 20 49 66 20 6d 6f 72 65 20 74 68  fied. If more th
4cf0: 61 6e 20 6f 6e 65 20 22 70 72 65 66 69 78 22 20  an one "prefix" 
4d00: 6f 70 74 69 6f 6e 20 69 73 0a 73 70 65 63 69 66  option is.specif
4d10: 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 61  ied as part of a
4d20: 20 73 69 6e 67 6c 65 20 43 52 45 41 54 45 20 56   single CREATE V
4d30: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61  IRTUAL TABLE sta
4d40: 74 65 6d 65 6e 74 2c 20 61 6c 6c 20 61 70 70 6c  tement, all appl
4d50: 79 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  y...<codeblock>.
4d60: 20 20 3c 69 3e 2d 2d 20 54 77 6f 20 77 61 79 73    <i>-- Two ways
4d70: 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 46 54   to create an FT
4d80: 53 35 20 74 61 62 6c 65 20 74 68 61 74 20 6d 61  S5 table that ma
4d90: 69 6e 74 61 69 6e 73 20 70 72 65 66 69 78 20 69  intains prefix i
4da0: 6e 64 65 78 65 73 20 66 6f 72 0a 20 20 2d 2d 20  ndexes for.  -- 
4db0: 74 77 6f 20 61 6e 64 20 74 68 72 65 65 20 63 68  two and three ch
4dc0: 61 72 61 63 74 65 72 20 70 72 65 66 69 78 20 74  aracter prefix t
4dd0: 6f 6b 65 6e 73 2e 3c 2f 69 3e 0a 20 20 43 52 45  okens.</i>.  CRE
4de0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
4df0: 45 20 66 74 20 55 53 49 4e 47 20 66 74 73 35 28  E ft USING fts5(
4e00: 61 2c 20 62 2c 20 70 72 65 66 69 78 3d 27 32 20  a, b, prefix='2 
4e10: 33 27 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49  3');.  CREATE VI
4e20: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
4e30: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
4e40: 70 72 65 66 69 78 3d 32 2c 20 70 72 65 66 69 78  prefix=2, prefix
4e50: 3d 33 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  =3);.</codeblock
4e60: 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53  >..<h2 tags="FTS
4e70: 35 20 74 6f 6b 65 6e 69 7a 65 72 73 22 3e 54 6f  5 tokenizers">To
4e80: 6b 65 6e 69 7a 65 72 73 3c 2f 68 32 3e 0a 0a 3c  kenizers</h2>..<
4e90: 70 3e 20 54 68 65 20 43 52 45 41 54 45 20 56 49  p> The CREATE VI
4ea0: 52 54 55 41 4c 20 54 41 42 4c 45 20 22 74 6f 6b  RTUAL TABLE "tok
4eb0: 65 6e 69 7a 65 22 20 6f 70 74 69 6f 6e 20 69 73  enize" option is
4ec0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
4ed0: 72 65 20 74 68 65 0a 73 70 65 63 69 66 69 63 20  re the.specific 
4ee0: 74 6f 6b 65 6e 69 7a 65 72 20 75 73 65 64 20 62  tokenizer used b
4ef0: 79 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65  y the FTS5 table
4f00: 2e 20 54 68 65 20 6f 70 74 69 6f 6e 20 61 72 67  . The option arg
4f10: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
4f20: 74 68 65 72 0a 61 6e 20 46 54 53 35 20 62 61 72  ther.an FTS5 bar
4f30: 65 77 6f 72 64 2c 20 6f 72 20 61 6e 20 53 51 4c  eword, or an SQL
4f40: 20 74 65 78 74 20 6c 69 74 65 72 61 6c 2e 20 54   text literal. T
4f50: 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 61  he text of the a
4f60: 72 67 75 6d 65 6e 74 20 69 73 20 69 74 73 65 6c  rgument is itsel
4f70: 66 0a 74 72 65 61 74 65 64 20 61 73 20 61 20 77  f.treated as a w
4f80: 68 69 74 65 2d 73 70 61 63 65 20 73 65 72 69 65  hite-space serie
4f90: 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  s of one or more
4fa0: 20 46 54 53 35 20 62 61 72 65 77 6f 72 64 73 20   FTS5 barewords 
4fb0: 6f 72 20 53 51 4c 20 74 65 78 74 0a 6c 69 74 65  or SQL text.lite
4fc0: 72 61 6c 73 2e 20 54 68 65 20 66 69 72 73 74 20  rals. The first 
4fd0: 6f 66 20 74 68 65 73 65 20 69 73 20 74 68 65 20  of these is the 
4fe0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 6f 6b 65  name of the toke
4ff0: 6e 69 7a 65 72 20 74 6f 20 75 73 65 2e 20 54 68  nizer to use. Th
5000: 65 20 73 65 63 6f 6e 64 0a 61 6e 64 20 73 75 62  e second.and sub
5010: 73 65 71 75 65 6e 74 20 6c 69 73 74 20 65 6c 65  sequent list ele
5020: 6d 65 6e 74 73 2c 20 69 66 20 74 68 65 79 20 65  ments, if they e
5030: 78 69 73 74 2c 20 61 72 65 20 61 72 67 75 6d 65  xist, are argume
5040: 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 74 68  nts passed to th
5050: 65 0a 74 6f 6b 65 6e 69 7a 65 72 20 69 6d 70 6c  e.tokenizer impl
5060: 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c 70 3e  ementation...<p>
5070: 20 55 6e 6c 69 6b 65 20 6f 70 74 69 6f 6e 20 76   Unlike option v
5080: 61 6c 75 65 73 20 61 6e 64 20 63 6f 6c 75 6d 6e  alues and column
5090: 20 6e 61 6d 65 73 2c 20 53 51 4c 20 74 65 78 74   names, SQL text
50a0: 20 6c 69 74 65 72 61 6c 73 20 69 6e 74 65 6e 64   literals intend
50b0: 65 64 20 61 73 0a 74 6f 6b 65 6e 69 7a 65 72 73  ed as.tokenizers
50c0: 20 6d 75 73 74 20 62 65 20 71 75 6f 74 65 64 20   must be quoted 
50d0: 75 73 69 6e 67 20 73 69 6e 67 6c 65 20 71 75 6f  using single quo
50e0: 74 65 20 63 68 61 72 61 63 74 65 72 73 2e 20 46  te characters. F
50f0: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
5100: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
5110: 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61   The following a
5120: 72 65 20 61 6c 6c 20 65 71 75 69 76 61 6c 65 6e  re all equivalen
5130: 74 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  t</i>.  CREATE V
5140: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20  IRTUAL TABLE t1 
5150: 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20 74 6f  USING fts5(x, to
5160: 6b 65 6e 69 7a 65 20 3d 20 27 70 6f 72 74 65 72  kenize = 'porter
5170: 20 61 73 63 69 69 27 29 3b 0a 20 20 43 52 45 41   ascii');.  CREA
5180: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
5190: 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78   t1 USING fts5(x
51a0: 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 22 70 6f  , tokenize = "po
51b0: 72 74 65 72 20 61 73 63 69 69 22 29 3b 0a 20 20  rter ascii");.  
51c0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
51d0: 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74  ABLE t1 USING ft
51e0: 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d  s5(x, tokenize =
51f0: 20 22 27 70 6f 72 74 65 72 27 20 27 61 73 63 69   "'porter' 'asci
5200: 69 27 22 29 3b 0a 20 20 43 52 45 41 54 45 20 56  i'");.  CREATE V
5210: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20  IRTUAL TABLE t1 
5220: 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20 74 6f  USING fts5(x, to
5230: 6b 65 6e 69 7a 65 20 3d 20 27 27 27 70 6f 72 74  kenize = '''port
5240: 65 72 27 27 20 27 27 61 73 63 69 69 27 27 27 29  er'' ''ascii''')
5250: 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 42 75 74 20 74  ;..  <i>-- But t
5260: 68 69 73 20 77 69 6c 6c 20 66 61 69 6c 3a 3c 2f  his will fail:</
5270: 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
5280: 55 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49  UAL TABLE t1 USI
5290: 4e 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e  NG fts5(x, token
52a0: 69 7a 65 20 3d 20 27 22 70 6f 72 74 65 72 22 20  ize = '"porter" 
52b0: 22 61 73 63 69 69 22 27 29 3b 0a 0a 20 20 3c 69  "ascii"');..  <i
52c0: 3e 2d 2d 20 54 68 69 73 20 77 69 6c 6c 20 66 61  >-- This will fa
52d0: 69 6c 20 74 6f 6f 3a 3c 2f 69 3e 0a 20 20 43 52  il too:</i>.  CR
52e0: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
52f0: 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35  LE t1 USING fts5
5300: 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  (x, tokenize = '
5310: 70 6f 72 74 65 72 27 20 27 61 73 63 69 69 27 29  porter' 'ascii')
5320: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
5330: 0a 3c 70 3e 0a 46 54 53 35 20 66 65 61 74 75 72  .<p>.FTS5 featur
5340: 65 73 20 74 68 72 65 65 20 62 75 69 6c 74 2d 69  es three built-i
5350: 6e 20 74 6f 6b 65 6e 69 7a 65 72 20 6d 6f 64 75  n tokenizer modu
5360: 6c 65 73 2c 20 64 65 73 63 72 69 62 65 64 20 69  les, described i
5370: 6e 20 73 75 62 73 65 71 75 65 6e 74 0a 73 65 63  n subsequent.sec
5380: 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c  tions:..<ul>.  <
5390: 6c 69 3e 20 54 68 65 20 3c 62 3e 75 6e 69 63 6f  li> The <b>unico
53a0: 64 65 36 31 3c 2f 62 3e 20 74 6f 6b 65 6e 69 7a  de61</b> tokeniz
53b0: 65 72 2c 20 62 61 73 65 64 20 6f 6e 20 74 68 65  er, based on the
53c0: 20 55 6e 69 63 6f 64 65 20 36 2e 31 20 73 74 61   Unicode 6.1 sta
53d0: 6e 64 61 72 64 2e 20 54 68 69 73 0a 20 20 20 20  ndard. This.    
53e0: 20 20 20 69 73 20 74 68 65 20 64 65 66 61 75 6c     is the defaul
53f0: 74 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c  t...  <li> The <
5400: 62 3e 61 73 63 69 69 3c 2f 62 3e 20 74 6f 6b 65  b>ascii</b> toke
5410: 6e 69 7a 65 72 2c 20 77 68 69 63 68 20 61 73 73  nizer, which ass
5420: 75 6d 65 73 20 61 6c 6c 20 63 68 61 72 61 63 74  umes all charact
5430: 65 72 73 20 6f 75 74 73 69 64 65 20 6f 66 0a 20  ers outside of. 
5440: 20 74 68 65 20 41 53 43 49 49 20 63 6f 64 65 70   the ASCII codep
5450: 6f 69 6e 74 20 72 61 6e 67 65 20 28 30 2d 31 32  oint range (0-12
5460: 37 29 20 61 72 65 20 74 6f 20 62 65 20 74 72 65  7) are to be tre
5470: 61 74 65 64 20 61 73 20 74 6f 6b 65 6e 20 63 68  ated as token ch
5480: 61 72 61 63 74 65 72 73 2e 0a 0a 20 20 3c 6c 69  aracters...  <li
5490: 3e 20 54 68 65 20 3c 62 3e 70 6f 72 74 65 72 3c  > The <b>porter<
54a0: 2f 62 3e 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 77  /b> tokenizer, w
54b0: 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 73 20  hich implements 
54c0: 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 68 74 74  the .<a href=htt
54d0: 70 3a 2f 2f 74 61 72 74 61 72 75 73 2e 6f 72 67  p://tartarus.org
54e0: 2f 6d 61 72 74 69 6e 2f 50 6f 72 74 65 72 53 74  /martin/PorterSt
54f0: 65 6d 6d 65 72 2f 3e 70 6f 72 74 65 72 20 73 74  emmer/>porter st
5500: 65 6d 6d 69 6e 67 20 61 6c 67 6f 72 69 74 68 6d  emming algorithm
5510: 3c 2f 61 3e 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  </a>..</ul>..<p>
5520: 20 49 74 20 69 73 20 61 6c 73 6f 20 70 6f 73 73   It is also poss
5530: 69 62 6c 65 20 74 6f 20 63 72 65 61 74 65 20 63  ible to create c
5540: 75 73 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 73  ustom tokenizers
5550: 20 66 6f 72 20 46 54 53 35 2e 20 54 68 65 20 41   for FTS5. The A
5560: 50 49 20 66 6f 72 20 64 6f 69 6e 67 20 73 6f 20  PI for doing so 
5570: 69 73 20 5b 63 75 73 74 6f 6d 20 74 6f 6b 65 6e  is [custom token
5580: 69 7a 65 72 73 20 7c 20 64 65 73 63 72 69 62 65  izers | describe
5590: 64 20 68 65 72 65 5d 2e 0a 0a 3c 68 33 3e 55 6e  d here]...<h3>Un
55a0: 69 63 6f 64 65 36 31 20 54 6f 6b 65 6e 69 7a 65  icode61 Tokenize
55b0: 72 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20  r</h3>..<p> The 
55c0: 75 6e 69 63 6f 64 65 20 74 6f 6b 65 6e 69 7a 65  unicode tokenize
55d0: 72 20 63 6c 61 73 73 69 66 69 65 73 20 61 6c 6c  r classifies all
55e0: 20 75 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74   unicode charact
55f0: 65 72 73 20 61 73 20 65 69 74 68 65 72 20 0a 22  ers as either ."
5600: 73 65 70 61 72 61 74 6f 72 22 20 6f 72 20 22 74  separator" or "t
5610: 6f 6b 65 6e 22 20 63 68 61 72 61 63 74 65 72 73  oken" characters
5620: 2e 20 42 79 20 64 65 66 61 75 6c 74 20 61 6c 6c  . By default all
5630: 20 73 70 61 63 65 20 61 6e 64 20 70 75 6e 63 74   space and punct
5640: 75 61 74 69 6f 6e 0a 63 68 61 72 61 63 74 65 72  uation.character
5650: 73 2c 20 61 73 20 64 65 66 69 6e 65 64 20 62 79  s, as defined by
5660: 20 55 6e 69 63 6f 64 65 20 36 2e 31 2c 20 61 72   Unicode 6.1, ar
5670: 65 20 63 6f 6e 73 69 64 65 72 65 64 20 73 65 70  e considered sep
5680: 61 72 61 74 6f 72 73 2c 20 61 6e 64 20 61 6c 6c  arators, and all
5690: 20 0a 6f 74 68 65 72 20 63 68 61 72 61 63 74 65   .other characte
56a0: 72 73 20 61 73 20 74 6f 6b 65 6e 20 63 68 61 72  rs as token char
56b0: 61 63 74 65 72 73 2e 20 45 61 63 68 20 63 6f 6e  acters. Each con
56c0: 74 69 67 75 6f 75 73 20 72 75 6e 20 6f 66 20 6f  tiguous run of o
56d0: 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 74 6f 6b 65  ne or more .toke
56e0: 6e 20 63 68 61 72 61 63 74 65 72 73 20 69 73 20  n characters is 
56f0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
5700: 20 61 20 74 6f 6b 65 6e 2e 20 54 68 65 20 74 6f   a token. The to
5710: 6b 65 6e 69 7a 65 72 20 69 73 20 63 61 73 65 2d  kenizer is case-
5720: 69 6e 73 65 6e 73 69 74 69 76 65 0a 61 63 63 6f  insensitive.acco
5730: 72 64 69 6e 67 20 74 6f 20 74 68 65 20 72 75 6c  rding to the rul
5740: 65 73 20 64 65 66 69 6e 65 64 20 62 79 20 55 6e  es defined by Un
5750: 69 63 6f 64 65 20 36 2e 31 2e 0a 0a 3c 70 3e 20  icode 6.1...<p> 
5760: 42 79 20 64 65 66 61 75 6c 74 2c 20 64 69 61 63  By default, diac
5770: 72 69 74 69 63 73 20 61 72 65 20 72 65 6d 6f 76  ritics are remov
5780: 65 64 20 66 72 6f 6d 20 61 6c 6c 20 4c 61 74 69  ed from all Lati
5790: 6e 20 73 63 72 69 70 74 20 63 68 61 72 61 63 74  n script charact
57a0: 65 72 73 2e 20 54 68 69 73 0a 6d 65 61 6e 73 2c  ers. This.means,
57b0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68   for example, th
57c0: 61 74 20 22 41 22 2c 20 22 61 22 2c 20 22 26 23  at "A", "a", "&#
57d0: 31 39 32 3b 22 2c 20 22 26 23 32 32 34 3b 22 2c  192;", "&#224;",
57e0: 20 22 26 23 31 39 34 3b 22 20 61 6e 64 20 22 26   "&#194;" and "&
57f0: 23 32 32 36 3b 22 0a 61 72 65 20 61 6c 6c 20 63  #226;".are all c
5800: 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
5810: 65 71 75 69 76 61 6c 65 6e 74 2e 0a 0a 3c 70 3e  equivalent...<p>
5820: 20 41 6e 79 20 61 72 67 75 6d 65 6e 74 73 20 66   Any arguments f
5830: 6f 6c 6c 6f 77 69 6e 67 20 22 75 6e 69 63 6f 64  ollowing "unicod
5840: 65 36 31 22 20 69 6e 20 74 68 65 20 74 6f 6b 65  e61" in the toke
5850: 6e 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  n specification 
5860: 61 72 65 20 74 72 65 61 74 65 64 0a 61 73 20 61  are treated.as a
5870: 20 6c 69 73 74 20 6f 66 20 61 6c 74 65 72 6e 61   list of alterna
5880: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 6e 61 6d 65  ting option name
5890: 73 20 61 6e 64 20 76 61 6c 75 65 73 2e 20 55 6e  s and values. Un
58a0: 69 63 6f 64 65 36 31 20 73 75 70 70 6f 72 74 73  icode61 supports
58b0: 20 74 68 65 0a 66 6f 6c 6c 6f 77 69 6e 67 20 6f   the.following o
58c0: 70 74 69 6f 6e 73 3a 0a 0a 3c 74 61 62 6c 65 20  ptions:..<table 
58d0: 73 74 72 69 70 65 64 3d 31 3e 0a 20 20 3c 74 72  striped=1>.  <tr
58e0: 3e 3c 74 68 3e 20 4f 70 74 69 6f 6e 20 3c 74 68  ><th> Option <th
58f0: 3e 20 55 73 61 67 65 0a 20 20 3c 74 72 3e 3c 74  > Usage.  <tr><t
5900: 64 3e 20 72 65 6d 6f 76 65 5f 64 69 61 63 72 69  d> remove_diacri
5910: 74 69 63 73 0a 20 20 3c 74 64 3e 54 68 69 73 20  tics.  <td>This 
5920: 6f 70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  option should be
5930: 20 73 65 74 20 74 6f 20 22 30 22 20 6f 72 20 22   set to "0" or "
5940: 31 22 2e 20 49 66 20 69 74 20 69 73 20 73 65 74  1". If it is set
5950: 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 2c 0a   (the default),.
5960: 20 20 64 69 61 63 72 69 74 69 63 73 20 61 72 65    diacritics are
5970: 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 61 6c   removed from al
5980: 6c 20 6c 61 74 69 6e 20 73 63 72 69 70 74 20 63  l latin script c
5990: 68 61 72 61 63 74 65 72 73 20 61 73 20 64 65 73  haracters as des
59a0: 63 72 69 62 65 64 20 61 62 6f 76 65 2e 0a 20 20  cribed above..  
59b0: 49 66 20 69 74 20 69 73 20 63 6c 65 61 72 2c 20  If it is clear, 
59c0: 74 68 65 79 20 61 72 65 20 6e 6f 74 2e 20 0a 0a  they are not. ..
59d0: 20 20 3c 74 72 3e 3c 74 64 3e 20 74 6f 6b 65 6e    <tr><td> token
59e0: 63 68 61 72 73 0a 20 20 3c 74 64 3e 20 54 68 69  chars.  <td> Thi
59f0: 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
5a00: 20 74 6f 20 73 70 65 63 69 66 79 20 61 64 64 69   to specify addi
5a10: 74 69 6f 6e 61 6c 20 75 6e 69 63 6f 64 65 20 63  tional unicode c
5a20: 68 61 72 61 63 74 65 72 73 20 74 68 61 74 20 0a  haracters that .
5a30: 20 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73    should be cons
5a40: 69 64 65 72 65 64 20 74 6f 6b 65 6e 20 63 68 61  idered token cha
5a50: 72 61 63 74 65 72 73 2c 20 65 76 65 6e 20 69 66  racters, even if
5a60: 20 74 68 65 79 20 61 72 65 20 77 68 69 74 65 2d   they are white-
5a70: 73 70 61 63 65 20 6f 72 0a 20 20 70 75 6e 63 74  space or.  punct
5a80: 75 61 74 69 6f 6e 20 63 68 61 72 61 63 74 65 72  uation character
5a90: 73 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 55  s according to U
5aa0: 6e 69 63 6f 64 65 20 36 2e 31 2e 20 41 6c 6c 20  nicode 6.1. All 
5ab0: 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 74 68  characters in th
5ac0: 65 0a 20 20 73 74 72 69 6e 67 20 74 68 61 74 20  e.  string that 
5ad0: 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
5ae0: 65 74 20 74 6f 20 61 72 65 20 63 6f 6e 73 69 64  et to are consid
5af0: 65 72 65 64 20 74 6f 6b 65 6e 20 63 68 61 72 61  ered token chara
5b00: 63 74 65 72 73 2e 0a 0a 20 20 3c 74 72 3e 3c 74  cters...  <tr><t
5b10: 64 3e 20 73 65 70 61 72 61 74 6f 72 73 0a 20 20  d> separators.  
5b20: 3c 74 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <td> This option
5b30: 20 69 73 20 75 73 65 64 20 74 6f 20 73 70 65 63   is used to spec
5b40: 69 66 79 20 61 64 64 69 74 69 6f 6e 61 6c 20 75  ify additional u
5b50: 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 65 72  nicode character
5b60: 73 20 74 68 61 74 20 0a 20 20 73 68 6f 75 6c 64  s that .  should
5b70: 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 61   be considered a
5b80: 73 20 73 65 70 61 72 61 74 6f 72 20 63 68 61 72  s separator char
5b90: 61 63 74 65 72 73 2c 20 65 76 65 6e 20 69 66 20  acters, even if 
5ba0: 74 68 65 79 20 61 72 65 20 74 6f 6b 65 6e 0a 20  they are token. 
5bb0: 20 63 68 61 72 61 63 74 65 72 73 20 61 63 63 6f   characters acco
5bc0: 72 64 69 6e 67 20 74 6f 20 55 6e 69 63 6f 64 65  rding to Unicode
5bd0: 20 36 2e 31 2e 20 41 6c 6c 20 63 68 61 72 61 63   6.1. All charac
5be0: 74 65 72 73 20 69 6e 20 74 68 65 20 73 74 72 69  ters in the stri
5bf0: 6e 67 20 74 68 61 74 20 0a 20 20 74 68 69 73 20  ng that .  this 
5c00: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
5c10: 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20   are considered 
5c20: 73 65 70 61 72 61 74 6f 72 73 2e 0a 3c 2f 74 61  separators..</ta
5c30: 62 6c 65 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65 78  ble>..<p> For ex
5c40: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
5c50: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61  ck>.  <i>-- Crea
5c60: 74 65 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65  te an FTS5 table
5c70: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
5c80: 65 6d 6f 76 65 20 64 69 61 63 72 69 74 69 63 73  emove diacritics
5c90: 20 66 72 6f 6d 20 4c 61 74 69 6e 0a 20 20 2d 2d   from Latin.  --
5ca0: 20 73 63 72 69 70 74 20 63 68 61 72 61 63 74 65   script characte
5cb0: 72 73 2c 20 61 6e 64 20 74 68 61 74 20 63 6f 6e  rs, and that con
5cc0: 73 69 64 65 72 73 20 68 79 70 68 65 6e 73 20 61  siders hyphens a
5cd0: 6e 64 20 75 6e 64 65 72 73 63 6f 72 65 20 63 68  nd underscore ch
5ce0: 61 72 61 63 74 65 72 73 0a 20 20 2d 2d 20 74 6f  aracters.  -- to
5cf0: 20 62 65 20 70 61 72 74 20 6f 66 20 74 6f 6b 65   be part of toke
5d00: 6e 73 2e 20 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ns. </i>.  CREAT
5d10: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
5d20: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
5d30: 20 62 2c 20 0a 20 20 20 20 20 20 74 6f 6b 65 6e   b, .      token
5d40: 69 7a 65 20 3d 20 22 75 6e 69 63 6f 64 65 36 31  ize = "unicode61
5d50: 20 72 65 6d 6f 76 65 5f 64 69 61 63 72 69 74 69   remove_diacriti
5d60: 63 73 20 30 20 74 6f 6b 65 6e 63 68 61 72 73 20  cs 0 tokenchars 
5d70: 27 2d 5f 27 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64  '-_'".  );.</cod
5d80: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65  eblock>..<p> The
5d90: 20 66 74 73 35 20 75 6e 69 63 6f 64 65 36 31 20   fts5 unicode61 
5da0: 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 62 79 74  tokenizer is byt
5db0: 65 2d 66 6f 72 2d 62 79 74 65 20 63 6f 6d 70 61  e-for-byte compa
5dc0: 74 69 62 6c 65 20 77 69 74 68 20 74 68 65 20 66  tible with the f
5dd0: 74 73 33 2f 34 0a 75 6e 69 63 6f 64 65 36 31 20  ts3/4.unicode61 
5de0: 74 6f 6b 65 6e 69 7a 65 72 2e 0a 0a 3c 68 33 3e  tokenizer...<h3>
5df0: 41 73 63 69 69 20 54 6f 6b 65 6e 69 7a 65 72 3c  Ascii Tokenizer<
5e00: 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20 41 73  /h3>..<p> The As
5e10: 63 69 69 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73  cii tokenizer is
5e20: 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 20   similar to the 
5e30: 55 6e 69 63 6f 64 65 36 31 20 74 6f 6b 65 6e 69  Unicode61 tokeni
5e40: 7a 65 72 2c 20 65 78 63 65 70 74 20 74 68 61 74  zer, except that
5e50: 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 41  :..<ul>.  <li> A
5e60: 6c 6c 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  ll non-ASCII cha
5e70: 72 61 63 74 65 72 73 20 28 74 68 6f 73 65 20 77  racters (those w
5e80: 69 74 68 20 63 6f 64 65 70 6f 69 6e 74 73 20 67  ith codepoints g
5e90: 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 29  reater than 127)
5ea0: 20 61 72 65 0a 20 20 61 6c 77 61 79 73 20 63 6f   are.  always co
5eb0: 6e 73 69 64 65 72 65 64 20 74 6f 6b 65 6e 20 63  nsidered token c
5ec0: 68 61 72 61 63 74 65 72 73 2e 20 49 66 20 61 6e  haracters. If an
5ed0: 79 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72  y non-ASCII char
5ee0: 61 63 74 65 72 73 20 61 72 65 20 73 70 65 63 69  acters are speci
5ef0: 66 69 65 64 0a 20 20 61 73 20 70 61 72 74 20 6f  fied.  as part o
5f00: 66 20 74 68 65 20 73 65 70 61 72 61 74 6f 72 73  f the separators
5f10: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 79 20 61 72   option, they ar
5f20: 65 20 69 67 6e 6f 72 65 64 2e 20 20 0a 0a 20 20  e ignored.  ..  
5f30: 3c 6c 69 3e 20 43 61 73 65 2d 66 6f 6c 64 69 6e  <li> Case-foldin
5f40: 67 20 69 73 20 6f 6e 6c 79 20 70 65 72 66 6f 72  g is only perfor
5f50: 6d 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68  med for ASCII ch
5f60: 61 72 61 63 74 65 72 73 2e 20 53 6f 20 77 68 69  aracters. So whi
5f70: 6c 65 20 22 41 22 20 61 6e 64 0a 20 20 22 61 22  le "A" and.  "a"
5f80: 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20   are considered 
5f90: 74 6f 20 62 65 20 65 71 75 69 76 61 6c 65 6e 74  to be equivalent
5fa0: 2c 20 22 26 23 31 39 35 22 20 61 6e 64 20 22 26  , "&#195" and "&
5fb0: 23 32 32 37 3b 22 20 61 72 65 20 64 69 73 74 69  #227;" are disti
5fc0: 6e 63 74 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65  nct...  <li> The
5fd0: 20 72 65 6d 6f 76 65 5f 64 69 61 63 72 69 74 69   remove_diacriti
5fe0: 63 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74  cs option is not
5ff0: 20 73 75 70 70 6f 72 74 65 64 2e 0a 3c 2f 75 6c   supported..</ul
6000: 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65 78 61 6d 70  >..<p> For examp
6010: 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  le:..<codeblock>
6020: 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20  .  <i>-- Create 
6030: 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68  an FTS5 table th
6040: 61 74 20 75 73 65 73 20 74 68 65 20 61 73 63 69  at uses the asci
6050: 69 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 62 75 74  i tokenizer, but
6060: 20 64 6f 65 73 20 6e 6f 74 0a 20 20 2d 2d 20 63   does not.  -- c
6070: 6f 6e 73 69 64 65 72 20 6e 75 6d 65 72 69 63 20  onsider numeric 
6080: 63 68 61 72 61 63 74 65 72 73 20 74 6f 20 62 65  characters to be
6090: 20 70 61 72 74 20 6f 66 20 74 6f 6b 65 6e 73 2e   part of tokens.
60a0: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
60b0: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
60c0: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
60d0: 0a 20 20 20 20 20 20 74 6f 6b 65 6e 69 7a 65 20  .      tokenize 
60e0: 3d 20 22 61 73 63 69 69 20 73 65 70 61 72 61 74  = "ascii separat
60f0: 6f 72 73 20 27 30 31 32 33 34 35 36 37 38 39 27  ors '0123456789'
6100: 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ".  );.</codeblo
6110: 63 6b 3e 0a 0a 3c 68 33 3e 50 6f 72 74 65 72 20  ck>..<h3>Porter 
6120: 54 6f 6b 65 6e 69 7a 65 72 3c 2f 68 33 3e 0a 0a  Tokenizer</h3>..
6130: 3c 70 3e 20 54 68 65 20 70 6f 72 74 65 72 20 74  <p> The porter t
6140: 6f 6b 65 6e 69 7a 65 72 20 69 73 20 61 20 77 72  okenizer is a wr
6150: 61 70 70 65 72 20 74 6f 6b 65 6e 69 7a 65 72 2e  apper tokenizer.
6160: 20 49 74 20 74 61 6b 65 73 20 74 68 65 20 6f 75   It takes the ou
6170: 74 70 75 74 20 6f 66 20 73 6f 6d 65 0a 6f 74 68  tput of some.oth
6180: 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20 61 6e 64  er tokenizer and
6190: 20 61 70 70 6c 69 65 73 20 74 68 65 20 0a 3c 61   applies the .<a
61a0: 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f 74 61 72   href=http://tar
61b0: 74 61 72 75 73 2e 6f 72 67 2f 6d 61 72 74 69 6e  tarus.org/martin
61c0: 2f 50 6f 72 74 65 72 53 74 65 6d 6d 65 72 2f 3e  /PorterStemmer/>
61d0: 70 6f 72 74 65 72 20 73 74 65 6d 6d 69 6e 67 20  porter stemming 
61e0: 61 6c 67 6f 72 69 74 68 6d 3c 2f 61 3e 0a 74 6f  algorithm</a>.to
61f0: 20 65 61 63 68 20 74 6f 6b 65 6e 20 62 65 66 6f   each token befo
6200: 72 65 20 69 74 20 72 65 74 75 72 6e 73 20 69 74  re it returns it
6210: 20 74 6f 20 46 54 53 35 2e 20 54 68 69 73 20 61   to FTS5. This a
6220: 6c 6c 6f 77 73 20 73 65 61 72 63 68 20 74 65 72  llows search ter
6230: 6d 73 20 6c 69 6b 65 0a 22 63 6f 72 72 65 63 74  ms like."correct
6240: 69 6f 6e 22 20 74 6f 20 6d 61 74 63 68 20 73 69  ion" to match si
6250: 6d 69 6c 61 72 20 77 6f 72 64 73 20 73 75 63 68  milar words such
6260: 20 61 73 20 22 63 6f 72 72 65 63 74 65 64 22 20   as "corrected" 
6270: 6f 72 20 22 63 6f 72 72 65 63 74 69 6e 67 22 2e  or "correcting".
6280: 20 54 68 65 0a 70 6f 72 74 65 72 20 73 74 65 6d   The.porter stem
6290: 6d 65 72 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  mer algorithm is
62a0: 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
62b0: 65 20 77 69 74 68 20 45 6e 67 6c 69 73 68 20 6c  e with English l
62c0: 61 6e 67 75 61 67 65 20 74 65 72 6d 73 20 0a 6f  anguage terms .o
62d0: 6e 6c 79 20 2d 20 75 73 69 6e 67 20 69 74 20 77  nly - using it w
62e0: 69 74 68 20 6f 74 68 65 72 20 6c 61 6e 67 75 61  ith other langua
62f0: 67 65 73 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  ges may or may n
6300: 6f 74 20 69 6d 70 72 6f 76 65 20 73 65 61 72 63  ot improve searc
6310: 68 20 75 74 69 6c 69 74 79 2e 0a 0a 3c 70 3e 20  h utility...<p> 
6320: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
6330: 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72  porter tokenizer
6340: 20 6f 70 65 72 61 74 65 73 20 61 73 20 61 20 77   operates as a w
6350: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68  rapper around th
6360: 65 20 64 65 66 61 75 6c 74 0a 74 6f 6b 65 6e 69  e default.tokeni
6370: 7a 65 72 20 28 75 6e 69 63 6f 64 65 36 31 29 2e  zer (unicode61).
6380: 20 4f 72 2c 20 69 66 20 6f 6e 65 20 6f 72 20 6d   Or, if one or m
6390: 6f 72 65 20 65 78 74 72 61 20 61 72 67 75 6d 65  ore extra argume
63a0: 6e 74 73 20 61 72 65 20 61 64 64 65 64 20 74 6f  nts are added to
63b0: 20 74 68 65 0a 22 74 6f 6b 65 6e 69 7a 65 22 20   the."tokenize" 
63c0: 6f 70 74 69 6f 6e 20 66 6f 6c 6c 6f 77 69 6e 67  option following
63d0: 20 22 70 6f 72 74 65 72 22 2c 20 74 68 65 79 20   "porter", they 
63e0: 61 72 65 20 74 72 65 61 74 65 64 20 61 73 20 61  are treated as a
63f0: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 66   specification f
6400: 6f 72 0a 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  or.the underlyin
6410: 67 20 74 6f 6b 65 6e 69 7a 65 72 20 74 68 61 74  g tokenizer that
6420: 20 74 68 65 20 70 6f 72 74 65 72 20 73 74 65 6d   the porter stem
6430: 6d 65 72 20 75 73 65 73 2e 20 46 6f 72 20 65 78  mer uses. For ex
6440: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
6450: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 77 6f 20  ck>.  <i>-- Two 
6460: 77 61 79 73 20 74 6f 20 63 72 65 61 74 65 20 61  ways to create a
6470: 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68 61  n FTS5 table tha
6480: 74 20 75 73 65 73 20 74 68 65 20 70 6f 72 74 65  t uses the porte
6490: 72 20 74 6f 6b 65 6e 69 7a 65 72 20 74 6f 0a 20  r tokenizer to. 
64a0: 20 2d 2d 20 73 74 65 6d 20 74 68 65 20 6f 75 74   -- stem the out
64b0: 70 75 74 20 6f 66 20 74 68 65 20 64 65 66 61 75  put of the defau
64c0: 6c 74 20 74 6f 6b 65 6e 69 7a 65 72 20 28 75 6e  lt tokenizer (un
64d0: 69 63 6f 64 65 36 31 29 2e 20 3c 2f 69 3e 0a 20  icode61). </i>. 
64e0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
64f0: 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66  TABLE t1 USING f
6500: 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20  ts5(x, tokenize 
6510: 3d 20 70 6f 72 74 65 72 29 3b 20 0a 20 20 43 52  = porter); .  CR
6520: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
6530: 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35  LE t1 USING fts5
6540: 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  (x, tokenize = '
6550: 70 6f 72 74 65 72 20 75 6e 69 63 6f 64 65 36 31  porter unicode61
6560: 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 41 20 70  ');..  <i>-- A p
6570: 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20  orter tokenizer 
6580: 75 73 65 64 20 74 6f 20 73 74 65 6d 20 74 68 65  used to stem the
6590: 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 20 75   output of the u
65a0: 6e 69 63 6f 64 65 36 31 20 74 6f 6b 65 6e 69 7a  nicode61 tokeniz
65b0: 65 72 2c 0a 20 20 2d 2d 20 77 69 74 68 20 64 69  er,.  -- with di
65c0: 61 63 72 69 74 69 63 73 20 72 65 6d 6f 76 65 64  acritics removed
65d0: 20 62 65 66 6f 72 65 20 73 74 65 6d 6d 69 6e 67   before stemming
65e0: 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  .</i>.  CREATE V
65f0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20  IRTUAL TABLE t1 
6600: 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20 74 6f  USING fts5(x, to
6610: 6b 65 6e 69 7a 65 20 3d 20 27 70 6f 72 74 65 72  kenize = 'porter
6620: 20 75 6e 69 63 6f 64 65 36 31 20 72 65 6d 6f 76   unicode61 remov
6630: 65 5f 64 69 61 63 72 69 74 69 63 73 20 31 27 29  e_diacritics 1')
6640: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
6650: 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 63  <h2 tags="FTS5 c
6660: 6f 6e 74 65 6e 74 20 6f 70 74 69 6f 6e 22 3e 45  ontent option">E
6670: 78 74 65 72 6e 61 6c 20 43 6f 6e 74 65 6e 74 20  xternal Content 
6680: 61 6e 64 20 43 6f 6e 74 65 6e 74 6c 65 73 73 20  and Contentless 
6690: 54 61 62 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  Tables</h2>..<p>
66a0: 0a 4e 6f 72 6d 61 6c 6c 79 2c 20 77 68 65 6e 20  .Normally, when 
66b0: 61 20 72 6f 77 20 69 73 20 69 6e 73 65 72 74 65  a row is inserte
66c0: 64 20 69 6e 74 6f 20 61 6e 20 46 54 53 35 20 74  d into an FTS5 t
66d0: 61 62 6c 65 2c 20 61 73 20 77 65 6c 6c 20 61 73  able, as well as
66e0: 20 74 68 65 20 76 61 72 69 6f 75 73 0a 66 75 6c   the various.ful
66f0: 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 65 6e 74  l-text index ent
6700: 72 69 65 73 20 61 6e 64 20 6f 74 68 65 72 20 64  ries and other d
6710: 61 74 61 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ata a copy of th
6720: 65 20 72 6f 77 20 69 73 20 73 74 6f 72 65 64 20  e row is stored 
6730: 69 6e 20 61 20 70 72 69 76 61 74 65 0a 74 61 62  in a private.tab
6740: 6c 65 20 6d 61 6e 61 67 65 64 20 62 79 20 74 68  le managed by th
6750: 65 20 46 54 53 35 20 6d 6f 64 75 6c 65 2e 20 57  e FTS5 module. W
6760: 68 65 6e 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  hen column value
6770: 73 20 61 72 65 20 72 65 71 75 65 73 74 65 64 20  s are requested 
6780: 66 72 6f 6d 20 74 68 65 0a 46 54 53 35 20 74 61  from the.FTS5 ta
6790: 62 6c 65 20 62 79 20 74 68 65 20 75 73 65 72 20  ble by the user 
67a0: 6f 72 20 62 79 20 61 6e 20 61 75 78 69 6c 69 61  or by an auxilia
67b0: 72 79 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ry function impl
67c0: 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 79  ementation, they
67d0: 20 61 72 65 0a 72 65 61 64 20 66 72 6f 6d 20 74   are.read from t
67e0: 68 69 73 20 70 72 69 76 61 74 65 20 74 61 62 6c  his private tabl
67f0: 65 2e 20 54 68 65 20 22 63 6f 6e 74 65 6e 74 22  e. The "content"
6800: 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
6810: 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 6e  sed to create an
6820: 0a 46 54 53 35 20 74 61 62 6c 65 20 74 68 61 74  .FTS5 table that
6830: 20 73 74 6f 72 65 73 20 6f 6e 6c 79 20 46 54 53   stores only FTS
6840: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
6850: 20 65 6e 74 72 69 65 73 2e 20 42 65 63 61 75 73   entries. Becaus
6860: 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 76 61 6c  e the column.val
6870: 75 65 73 20 74 68 65 6d 73 65 6c 76 65 73 20 61  ues themselves a
6880: 72 65 20 75 73 75 61 6c 6c 79 20 6d 75 63 68 20  re usually much 
6890: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
68a0: 61 73 73 6f 63 69 61 74 65 64 20 66 75 6c 6c 2d  associated full-
68b0: 74 65 78 74 20 69 6e 64 65 78 0a 65 6e 74 72 69  text index.entri
68c0: 65 73 2c 20 74 68 69 73 20 63 61 6e 20 73 61 76  es, this can sav
68d0: 65 20 73 69 67 6e 69 66 69 63 61 6e 74 20 64 61  e significant da
68e0: 74 61 62 61 73 65 20 73 70 61 63 65 2e 0a 0a 3c  tabase space...<
68f0: 70 3e 0a 54 68 65 72 65 20 61 72 65 20 74 77 6f  p>.There are two
6900: 20 77 61 79 73 20 74 6f 20 75 73 65 20 74 68 65   ways to use the
6910: 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70 74 69 6f   "content" optio
6920: 6e 3a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 42  n:.<ul>.  <li> B
6930: 79 20 73 65 74 74 69 6e 67 20 69 74 20 74 6f 20  y setting it to 
6940: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
6950: 74 6f 20 63 72 65 61 74 65 20 61 20 63 6f 6e 74  to create a cont
6960: 65 6e 74 6c 65 73 73 20 46 54 53 35 20 74 61 62  entless FTS5 tab
6970: 6c 65 2e 20 49 6e 0a 20 20 20 20 20 20 20 74 68  le. In.       th
6980: 69 73 20 63 61 73 65 20 46 54 53 35 20 61 73 73  is case FTS5 ass
6990: 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 6f 72  umes that the or
69a0: 69 67 69 6e 61 6c 20 63 6f 6c 75 6d 6e 20 76 61  iginal column va
69b0: 6c 75 65 73 20 61 72 65 20 75 6e 61 76 61 69 6c  lues are unavail
69c0: 61 62 6c 65 0a 20 20 20 20 20 20 20 74 6f 20 69  able.       to i
69d0: 74 20 77 68 65 6e 20 70 72 6f 63 65 73 73 69 6e  t when processin
69e0: 67 20 71 75 65 72 69 65 73 2e 20 46 75 6c 6c 2d  g queries. Full-
69f0: 74 65 78 74 20 71 75 65 72 69 65 73 20 61 6e 64  text queries and
6a00: 20 73 6f 6d 65 20 61 75 78 69 6c 69 61 72 79 0a   some auxiliary.
6a10: 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 73         functions
6a20: 20 63 61 6e 20 73 74 69 6c 6c 20 62 65 20 75 73   can still be us
6a30: 65 64 2c 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  ed, but no colum
6a40: 6e 20 76 61 6c 75 65 73 20 61 70 61 72 74 20 66  n values apart f
6a50: 72 6f 6d 20 74 68 65 20 72 6f 77 69 64 0a 20 20  rom the rowid.  
6a60: 20 20 20 20 20 6d 61 79 20 62 65 20 72 65 61 64       may be read
6a70: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
6a80: 0a 0a 20 20 3c 6c 69 3e 20 42 79 20 73 65 74 74  ..  <li> By sett
6a90: 69 6e 67 20 69 74 20 74 6f 20 74 68 65 20 6e 61  ing it to the na
6aa0: 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
6ab0: 20 6f 62 6a 65 63 74 20 28 74 61 62 6c 65 2c 20   object (table, 
6ac0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72  virtual table or
6ad0: 0a 20 20 20 20 20 20 20 76 69 65 77 29 20 74 68  .       view) th
6ae0: 61 74 20 6d 61 79 20 62 65 20 71 75 65 72 69 65  at may be querie
6af0: 64 20 62 79 20 46 54 53 35 20 61 74 20 61 6e 79  d by FTS5 at any
6b00: 20 74 69 6d 65 20 74 6f 20 72 65 74 72 69 65 76   time to retriev
6b10: 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 20 20 20  e the column.   
6b20: 20 20 20 20 76 61 6c 75 65 73 2e 20 54 68 69 73      values. This
6b30: 20 69 73 20 6b 6e 6f 77 6e 20 61 73 20 61 6e 20   is known as an 
6b40: 22 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e  "external conten
6b50: 74 22 20 74 61 62 6c 65 2e 20 49 6e 20 74 68 69  t" table. In thi
6b60: 73 20 63 61 73 65 20 61 6c 6c 0a 20 20 20 20 20  s case all.     
6b70: 20 20 46 54 53 35 20 66 75 6e 63 74 69 6f 6e 61    FTS5 functiona
6b80: 6c 69 74 79 20 6d 61 79 20 62 65 20 75 73 65 64  lity may be used
6b90: 2c 20 62 75 74 20 69 74 20 69 73 20 74 68 65 20  , but it is the 
6ba0: 72 65 73 70 6f 6e 73 69 62 69 6c 69 74 79 20 6f  responsibility o
6bb0: 66 20 74 68 65 20 75 73 65 72 0a 20 20 20 20 20  f the user.     
6bc0: 20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74    to ensure that
6bd0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
6be0: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
6bf0: 6e 64 65 78 20 61 72 65 20 63 6f 6e 73 69 73 74  ndex are consist
6c00: 65 6e 74 20 77 69 74 68 0a 20 20 20 20 20 20 20  ent with.       
6c10: 74 68 65 20 6e 61 6d 65 64 20 64 61 74 61 62 61  the named databa
6c20: 73 65 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68  se object. If th
6c30: 65 79 20 61 72 65 20 6e 6f 74 2c 20 71 75 65 72  ey are not, quer
6c40: 79 20 72 65 73 75 6c 74 73 20 6d 61 79 20 62 65  y results may be
6c50: 0a 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63  .       unpredic
6c60: 74 61 62 6c 65 2e 20 20 0a 3c 2f 75 6c 3e 0a 0a  table.  .</ul>..
6c70: 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 63  <h3 tags="FTS5 c
6c80: 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
6c90: 73 22 3e 43 6f 6e 74 65 6e 74 6c 65 73 73 20 54  s">Contentless T
6ca0: 61 62 6c 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20  ables</h3>..<p> 
6cb0: 41 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54  A contentless FT
6cc0: 53 35 20 74 61 62 6c 65 20 69 73 20 63 72 65 61  S5 table is crea
6cd0: 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 74  ted by setting t
6ce0: 68 65 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70 74  he "content" opt
6cf0: 69 6f 6e 20 74 6f 0a 61 6e 20 65 6d 70 74 79 20  ion to.an empty 
6d00: 73 74 72 69 6e 67 2e 20 46 6f 72 20 65 78 61 6d  string. For exam
6d10: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
6d20: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
6d30: 41 4c 20 54 41 42 4c 45 20 66 31 20 55 53 49 4e  AL TABLE f1 USIN
6d40: 47 20 66 74 73 35 28 61 2c 20 62 2c 20 63 2c 20  G fts5(a, b, c, 
6d50: 63 6f 6e 74 65 6e 74 3d 27 27 29 3b 0a 3c 2f 63  content='');.</c
6d60: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 43  odeblock>..<p> C
6d70: 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54 53 35 20  ontentless FTS5 
6d80: 74 61 62 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75  tables do not su
6d90: 70 70 6f 72 74 20 55 50 44 41 54 45 20 6f 72 20  pport UPDATE or 
6da0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
6db0: 73 2c 20 6f 72 0a 49 4e 53 45 52 54 20 73 74 61  s, or.INSERT sta
6dc0: 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 6f 20  tements that do 
6dd0: 6e 6f 74 20 73 75 70 70 6c 79 20 61 20 6e 6f 6e  not supply a non
6de0: 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 66 6f 72 20  -NULL value for 
6df0: 74 68 65 20 72 6f 77 69 64 20 66 69 65 6c 64 2e  the rowid field.
6e00: 0a 43 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62  .Contentless tab
6e10: 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  les do not suppo
6e20: 72 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 66 6c  rt REPLACE confl
6e30: 69 63 74 20 68 61 6e 64 6c 69 6e 67 2e 20 52 45  ict handling. RE
6e40: 50 4c 41 43 45 20 0a 61 6e 64 20 49 4e 53 45 52  PLACE .and INSER
6e50: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 73 74 61  T OR REPLACE sta
6e60: 74 65 6d 65 6e 74 73 20 61 72 65 20 74 72 65 61  tements are trea
6e70: 74 65 64 20 61 73 20 72 65 67 75 6c 61 72 20 49  ted as regular I
6e80: 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73  NSERT statements
6e90: 2e 0a 52 6f 77 73 20 6d 61 79 20 62 65 20 64 65  ..Rows may be de
6ea0: 6c 65 74 65 64 20 66 72 6f 6d 20 61 20 63 6f 6e  leted from a con
6eb0: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 20 75  tentless table u
6ec0: 73 69 6e 67 20 61 6e 20 5b 46 54 53 35 20 64 65  sing an [FTS5 de
6ed0: 6c 65 74 65 20 63 6f 6d 6d 61 6e 64 5d 2e 0a 0a  lete command]...
6ee0: 3c 70 3e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  <p> Attempting t
6ef0: 6f 20 72 65 61 64 20 61 6e 79 20 63 6f 6c 75 6d  o read any colum
6f00: 6e 20 76 61 6c 75 65 20 65 78 63 65 70 74 20 74  n value except t
6f10: 68 65 20 72 6f 77 69 64 20 66 72 6f 6d 20 61 20  he rowid from a 
6f20: 63 6f 6e 74 65 6e 74 6c 65 73 73 0a 46 54 53 35  contentless.FTS5
6f30: 20 74 61 62 6c 65 20 72 65 74 75 72 6e 73 20 61   table returns a
6f40: 6e 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65  n SQL NULL value
6f50: 2e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46 54 53  ...<h3 tags="FTS
6f60: 35 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  5 external conte
6f70: 6e 74 20 74 61 62 6c 65 73 22 3e 45 78 74 65 72  nt tables">Exter
6f80: 6e 61 6c 20 43 6f 6e 74 65 6e 74 20 54 61 62 6c  nal Content Tabl
6f90: 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 41 6e 20  es</h3>..<p> An 
6fa0: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
6fb0: 20 46 54 53 35 20 74 61 62 6c 65 20 69 73 20 63   FTS5 table is c
6fc0: 72 65 61 74 65 64 20 62 79 20 73 65 74 74 69 6e  reated by settin
6fd0: 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 0a 6f  g the content .o
6fe0: 70 74 69 6f 6e 20 74 6f 20 74 68 65 20 6e 61 6d  ption to the nam
6ff0: 65 20 6f 66 20 61 20 74 61 62 6c 65 2c 20 76 69  e of a table, vi
7000: 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72 20 76  rtual table or v
7010: 69 65 77 20 28 68 65 72 65 61 66 74 65 72 20 74  iew (hereafter t
7020: 68 65 20 22 63 6f 6e 74 65 6e 74 0a 74 61 62 6c  he "content.tabl
7030: 65 22 29 20 77 69 74 68 69 6e 20 74 68 65 20 73  e") within the s
7040: 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 57 68  ame database. Wh
7050: 65 6e 65 76 65 72 20 63 6f 6c 75 6d 6e 20 76 61  enever column va
7060: 6c 75 65 73 20 61 72 65 20 72 65 71 75 69 72 65  lues are require
7070: 64 20 62 79 0a 46 54 53 35 2c 20 69 74 20 71 75  d by.FTS5, it qu
7080: 65 72 69 65 73 20 74 68 65 20 63 6f 6e 74 65 6e  eries the conten
7090: 74 20 74 61 62 6c 65 20 61 73 20 66 6f 6c 6c 6f  t table as follo
70a0: 77 73 2c 20 77 69 74 68 20 74 68 65 20 72 6f 77  ws, with the row
70b0: 69 64 20 6f 66 20 74 68 65 20 72 6f 77 0a 66 6f  id of the row.fo
70c0: 72 20 77 68 69 63 68 20 76 61 6c 75 65 73 20 61  r which values a
70d0: 72 65 20 72 65 71 75 69 72 65 64 20 62 6f 75 6e  re required boun
70e0: 64 20 74 6f 20 74 68 65 20 53 51 4c 20 76 61 72  d to the SQL var
70f0: 69 61 62 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  iable:..<codeblo
7100: 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20 26 6c 74  ck>.  SELECT &lt
7110: 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67  ;content_rowid&g
7120: 74 3b 2c 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b  t;, &lt;cols&gt;
7130: 20 46 52 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e   FROM &lt;conten
7140: 74 26 67 74 3b 20 57 48 45 52 45 20 26 6c 74 3b  t&gt; WHERE &lt;
7150: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74  content_rowid&gt
7160: 3b 20 3d 20 3f 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ; = ?;.</codeblo
7170: 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20 74 68 65 20  ck>..<p> In the 
7180: 61 62 6f 76 65 2c 20 26 6c 74 3b 63 6f 6e 74 65  above, &lt;conte
7190: 6e 74 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  nt&gt; is replac
71a0: 65 64 20 62 79 20 74 68 65 20 6e 61 6d 65 20 6f  ed by the name o
71b0: 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61  f the content ta
71c0: 62 6c 65 2e 0a 42 79 20 64 65 66 61 75 6c 74 2c  ble..By default,
71d0: 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77   &lt;content_row
71e0: 69 64 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  id&gt; is replac
71f0: 65 64 20 62 79 20 74 68 65 20 6c 69 74 65 72 61  ed by the litera
7200: 6c 20 74 65 78 74 20 22 72 6f 77 69 64 22 2e 20  l text "rowid". 
7210: 4f 72 2c 0a 69 66 20 74 68 65 20 22 63 6f 6e 74  Or,.if the "cont
7220: 65 6e 74 5f 72 6f 77 69 64 22 20 6f 70 74 69 6f  ent_rowid" optio
7230: 6e 20 69 73 20 73 65 74 20 77 69 74 68 69 6e 20  n is set within 
7240: 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55  the CREATE VIRTU
7250: 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  AL TABLE stateme
7260: 6e 74 2c 0a 62 79 20 74 68 65 20 76 61 6c 75 65  nt,.by the value
7270: 20 6f 66 20 74 68 61 74 20 6f 70 74 69 6f 6e 2e   of that option.
7280: 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b 20 69 73   &lt;cols&gt; is
7290: 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 63   replaced by a c
72a0: 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64 20 6c  omma-separated l
72b0: 69 73 74 0a 6f 66 20 74 68 65 20 46 54 53 35 20  ist.of the FTS5 
72c0: 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  table column nam
72d0: 65 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  es. For example:
72e0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
72f0: 3c 69 3e 2d 2d 20 49 66 20 74 68 65 20 64 61 74  <i>-- If the dat
7300: 61 62 61 73 65 20 73 63 68 65 6d 61 20 69 73 3a  abase schema is:
7310: 20 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 54   </i>.  CREATE T
7320: 41 42 4c 45 20 74 62 6c 20 28 61 2c 20 62 2c 20  ABLE tbl (a, b, 
7330: 63 2c 20 64 20 49 4e 54 45 47 45 52 20 50 52 49  c, d INTEGER PRI
7340: 4d 41 52 59 20 4b 45 59 29 3b 0a 20 20 43 52 45  MARY KEY);.  CRE
7350: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
7360: 45 20 66 74 73 20 55 53 49 4e 47 20 66 74 73 35  E fts USING fts5
7370: 28 61 2c 20 63 2c 20 63 6f 6e 74 65 6e 74 3d 74  (a, c, content=t
7380: 62 6c 2c 20 63 6f 6e 74 65 6e 74 5f 72 6f 77 69  bl, content_rowi
7390: 64 3d 64 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 46  d=d);..  <i>-- F
73a0: 74 73 35 20 6d 61 79 20 69 73 73 75 65 20 71 75  ts5 may issue qu
73b0: 65 72 69 65 73 20 73 75 63 68 20 61 73 3a 3c 2f  eries such as:</
73c0: 69 3e 0a 20 20 53 45 4c 45 43 54 20 64 2c 20 61  i>.  SELECT d, a
73d0: 2c 20 63 20 46 52 4f 4d 20 74 62 6c 20 57 48 45  , c FROM tbl WHE
73e0: 52 45 20 64 20 3d 20 3f 3b 0a 3c 2f 63 6f 64 65  RE d = ?;.</code
73f0: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20  block>..<p> The 
7400: 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 20 6d 61  content table ma
7410: 79 20 61 6c 73 6f 20 62 65 20 71 75 65 72 69 65  y also be querie
7420: 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c  d as follows:..<
7430: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c  codeblock>.  SEL
7440: 45 43 54 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f  ECT &lt;content_
7450: 72 6f 77 69 64 26 67 74 3b 2c 20 26 6c 74 3b 63  rowid&gt;, &lt;c
7460: 6f 6c 73 26 67 74 3b 20 46 52 4f 4d 20 26 6c 74  ols&gt; FROM &lt
7470: 3b 63 6f 6e 74 65 6e 74 26 67 74 3b 20 4f 52 44  ;content&gt; ORD
7480: 45 52 20 42 59 20 26 6c 74 3b 63 6f 6e 74 65 6e  ER BY &lt;conten
7490: 74 5f 72 6f 77 69 64 26 67 74 3b 20 41 53 43 3b  t_rowid&gt; ASC;
74a0: 0a 20 20 53 45 4c 45 43 54 20 26 6c 74 3b 63 6f  .  SELECT &lt;co
74b0: 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74 3b 2c  ntent_rowid&gt;,
74c0: 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b 20 46 52   &lt;cols&gt; FR
74d0: 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 26 67  OM &lt;content&g
74e0: 74 3b 20 4f 52 44 45 52 20 42 59 20 26 6c 74 3b  t; ORDER BY &lt;
74f0: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74  content_rowid&gt
7500: 3b 20 44 45 53 43 3b 0a 3c 2f 63 6f 64 65 62 6c  ; DESC;.</codebl
7510: 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 74 20 69 73 20  ock>..<p> It is 
7520: 73 74 69 6c 6c 20 74 68 65 20 72 65 73 70 6f 6e  still the respon
7530: 73 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20  sibility of the 
7540: 75 73 65 72 20 74 6f 20 65 6e 73 75 72 65 20 74  user to ensure t
7550: 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  hat the contents
7560: 20 6f 66 0a 61 6e 20 65 78 74 65 72 6e 61 6c 20   of.an external 
7570: 63 6f 6e 74 65 6e 74 20 46 54 53 35 20 74 61 62  content FTS5 tab
7580: 6c 65 20 61 72 65 20 6b 65 70 74 20 75 70 20 74  le are kept up t
7590: 6f 20 64 61 74 65 20 77 69 74 68 20 74 68 65 20  o date with the 
75a0: 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e 20 0a  content table. .
75b0: 4f 6e 65 20 77 61 79 20 74 6f 20 64 6f 20 74 68  One way to do th
75c0: 69 73 20 69 73 20 77 69 74 68 20 74 72 69 67 67  is is with trigg
75d0: 65 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ers. For example
75e0: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
75f0: 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 20   <i>-- Create a 
7600: 74 61 62 6c 65 2e 20 41 6e 64 20 61 6e 20 65 78  table. And an ex
7610: 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 66  ternal content f
7620: 74 73 35 20 74 61 62 6c 65 20 74 6f 20 69 6e 64  ts5 table to ind
7630: 65 78 20 69 74 2e 3c 2f 69 3e 0a 20 20 43 52 45  ex it.</i>.  CRE
7640: 41 54 45 20 54 41 42 4c 45 20 74 62 6c 28 61 20  ATE TABLE tbl(a 
7650: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
7660: 4b 45 59 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52  KEY, b, c);.  CR
7670: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
7680: 4c 45 20 66 74 73 5f 69 64 78 20 55 53 49 4e 47  LE fts_idx USING
7690: 20 66 74 73 35 28 62 2c 20 63 2c 20 63 6f 6e 74   fts5(b, c, cont
76a0: 65 6e 74 3d 27 74 62 6c 27 2c 20 63 6f 6e 74 65  ent='tbl', conte
76b0: 6e 74 5f 72 6f 77 69 64 3d 27 61 27 29 3b 0a 0a  nt_rowid='a');..
76c0: 20 20 3c 69 3e 2d 2d 20 54 72 69 67 67 65 72 73    <i>-- Triggers
76d0: 20 74 6f 20 6b 65 65 70 20 74 68 65 20 46 54 53   to keep the FTS
76e0: 20 69 6e 64 65 78 20 75 70 20 74 6f 20 64 61 74   index up to dat
76f0: 65 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  e.</i>.  CREATE 
7700: 54 52 49 47 47 45 52 20 74 62 6c 5f 61 69 20 41  TRIGGER tbl_ai A
7710: 46 54 45 52 20 49 4e 53 45 52 54 20 4f 4e 20 74  FTER INSERT ON t
7720: 62 6c 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53  bl BEGIN.    INS
7730: 45 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78  ERT INTO fts_idx
7740: 28 72 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41  (rowid, b, c) VA
7750: 4c 55 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77  LUES (new.a, new
7760: 2e 62 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e  .b, new.c);.  EN
7770: 44 3b 0a 20 20 43 52 45 41 54 45 20 54 52 49 47  D;.  CREATE TRIG
7780: 47 45 52 20 74 62 6c 5f 61 64 20 41 46 54 45 52  GER tbl_ad AFTER
7790: 20 44 45 4c 45 54 45 20 4f 4e 20 74 62 6c 20 42   DELETE ON tbl B
77a0: 45 47 49 4e 0a 20 20 20 20 49 4e 53 45 52 54 20  EGIN.    INSERT 
77b0: 49 4e 54 4f 20 66 74 73 5f 69 64 78 28 66 74 73  INTO fts_idx(fts
77c0: 5f 69 64 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20  _idx, rowid, b, 
77d0: 63 29 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74  c) VALUES('delet
77e0: 65 27 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62  e', old.a, old.b
77f0: 2c 20 6f 6c 64 2e 63 29 3b 0a 20 20 45 4e 44 3b  , old.c);.  END;
7800: 0a 20 20 43 52 45 41 54 45 20 54 52 49 47 47 45  .  CREATE TRIGGE
7810: 52 20 74 62 6c 5f 61 75 20 41 46 54 45 52 20 55  R tbl_au AFTER U
7820: 50 44 41 54 45 20 4f 4e 20 74 62 6c 20 42 45 47  PDATE ON tbl BEG
7830: 49 4e 0a 20 20 20 20 49 4e 53 45 52 54 20 49 4e  IN.    INSERT IN
7840: 54 4f 20 66 74 73 5f 69 64 78 28 66 74 73 5f 69  TO fts_idx(fts_i
7850: 64 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20 63 29  dx, rowid, b, c)
7860: 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74 65 27   VALUES('delete'
7870: 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62 2c 20  , old.a, old.b, 
7880: 6f 6c 64 2e 63 29 3b 0a 20 20 20 20 49 4e 53 45  old.c);.    INSE
7890: 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78 28  RT INTO fts_idx(
78a0: 72 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41 4c  rowid, b, c) VAL
78b0: 55 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77 2e  UES (new.a, new.
78c0: 62 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e 44  b, new.c);.  END
78d0: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
78e0: 3c 70 3e 20 4c 69 6b 65 20 63 6f 6e 74 65 6e 74  <p> Like content
78f0: 6c 65 73 73 20 74 61 62 6c 65 73 2c 20 65 78 74  less tables, ext
7900: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61  ernal content ta
7910: 62 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  bles do not supp
7920: 6f 72 74 20 52 45 50 4c 41 43 45 0a 63 6f 6e 66  ort REPLACE.conf
7930: 6c 69 63 74 20 68 61 6e 64 6c 69 6e 67 2e 20 41  lict handling. A
7940: 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68  ny operations th
7950: 61 74 20 73 70 65 63 69 66 79 20 52 45 50 4c 41  at specify REPLA
7960: 43 45 20 63 6f 6e 66 6c 69 63 74 20 68 61 6e 64  CE conflict hand
7970: 6c 69 6e 67 20 61 72 65 0a 68 61 6e 64 6c 65 64  ling are.handled
7980: 20 75 73 69 6e 67 20 41 42 4f 52 54 2e 0a 0a 3c   using ABORT...<
7990: 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 63 6f  h2 tags="FTS5 co
79a0: 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 22  lumnsize option"
79b0: 3e 54 68 65 20 43 6f 6c 75 6d 6e 73 69 7a 65 20  >The Columnsize 
79c0: 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  Option</h2>..<p>
79d0: 4e 6f 72 6d 61 6c 6c 79 2c 20 46 54 53 35 20 6d  Normally, FTS5 m
79e0: 61 69 6e 74 61 69 6e 73 20 61 20 73 70 65 63 69  aintains a speci
79f0: 61 6c 20 62 61 63 6b 69 6e 67 20 74 61 62 6c 65  al backing table
7a00: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
7a10: 62 61 73 65 20 74 68 61 74 0a 73 74 6f 72 65 73  base that.stores
7a20: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
7a30: 68 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69  h column value i
7a40: 6e 20 74 6f 6b 65 6e 73 20 69 6e 73 65 72 74 65  n tokens inserte
7a50: 64 20 69 6e 74 6f 20 74 68 65 20 6d 61 69 6e 20  d into the main 
7a60: 46 54 53 35 0a 74 61 62 6c 65 20 69 6e 20 61 20  FTS5.table in a 
7a70: 73 65 70 61 72 61 74 65 20 74 61 62 6c 65 2e 20  separate table. 
7a80: 54 68 69 73 20 62 61 63 6b 69 6e 67 20 74 61 62  This backing tab
7a90: 6c 65 20 69 73 20 75 73 65 64 20 62 79 20 74 68  le is used by th
7aa0: 65 0a 3c 61 20 68 72 65 66 3d 23 78 43 6f 6c 75  e.<a href=#xColu
7ab0: 6d 6e 53 69 7a 65 3e 78 43 6f 6c 75 6d 6e 53 69  mnSize>xColumnSi
7ac0: 7a 65 3c 61 3e 20 41 50 49 20 66 75 6e 63 74 69  ze<a> API functi
7ad0: 6f 6e 2c 20 77 68 69 63 68 20 69 73 20 69 6e 20  on, which is in 
7ae0: 74 75 72 6e 20 75 73 65 64 20 62 79 0a 74 68 65  turn used by.the
7af0: 20 62 75 69 6c 74 2d 69 6e 20 5b 46 54 53 35 20   built-in [FTS5 
7b00: 62 6d 32 35 20 7c 20 62 6d 32 35 20 72 61 6e 6b  bm25 | bm25 rank
7b10: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 5d 20 28 61  ing function] (a
7b20: 6e 64 20 69 73 20 6c 69 6b 65 6c 79 20 74 6f 20  nd is likely to 
7b30: 62 65 20 75 73 65 66 75 6c 20 0a 74 6f 20 6f 74  be useful .to ot
7b40: 68 65 72 20 72 61 6e 6b 69 6e 67 20 66 75 6e 63  her ranking func
7b50: 74 69 6f 6e 73 20 61 73 20 77 65 6c 6c 29 2e 0a  tions as well)..
7b60: 0a 3c 70 3e 49 6e 20 6f 72 64 65 72 20 74 6f 20  .<p>In order to 
7b70: 73 61 76 65 20 73 70 61 63 65 2c 20 74 68 69 73  save space, this
7b80: 20 62 61 63 6b 69 6e 67 20 74 61 62 6c 65 20 6d   backing table m
7b90: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
7ba0: 20 73 65 74 74 69 6e 67 20 74 68 65 0a 63 6f 6c   setting the.col
7bb0: 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 20 74  umnsize option t
7bc0: 6f 20 7a 65 72 6f 2e 20 46 6f 72 20 65 78 61 6d  o zero. For exam
7bd0: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
7be0: 3e 0a 20 20 3c 69 3e 2d 2d 20 41 20 74 61 62 6c  >.  <i>-- A tabl
7bf0: 65 20 77 69 74 68 6f 75 74 20 74 68 65 20 78 43  e without the xC
7c00: 6f 6c 75 6d 6e 53 69 7a 65 28 29 20 76 61 6c 75  olumnSize() valu
7c10: 65 73 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 73  es stored on dis
7c20: 6b 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  k:</i>.  CREATE 
7c30: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
7c40: 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62   USING fts5(a, b
7c50: 2c 20 63 2c 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  , c, columnsize=
7c60: 30 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 72  0);..  <i>-- Thr
7c70: 65 65 20 65 71 75 69 76 61 6c 65 6e 74 20 77 61  ee equivalent wa
7c80: 79 73 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61  ys of creating a
7c90: 20 74 61 62 6c 65 20 74 68 61 74 20 64 6f 65 73   table that does
7ca0: 20 73 74 6f 72 65 20 74 68 65 3c 2f 69 3e 0a 20   store the</i>. 
7cb0: 20 3c 69 3e 2d 2d 20 78 43 6f 6c 75 6d 6e 53 69   <i>-- xColumnSi
7cc0: 7a 65 28 29 20 76 61 6c 75 65 73 20 6f 6e 20 64  ze() values on d
7cd0: 69 73 6b 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  isk:</i>.  CREAT
7ce0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
7cf0: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
7d00: 20 62 2c 20 63 29 3b 0a 20 20 43 52 45 41 54 45   b, c);.  CREATE
7d10: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
7d20: 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20  t USING fts5(a, 
7d30: 62 2c 20 63 2c 20 63 6f 6c 75 6d 6e 73 69 7a 65  b, c, columnsize
7d40: 3d 31 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49  =1);.  CREATE VI
7d50: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
7d60: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
7d70: 63 6f 6c 75 6d 6e 73 69 7a 65 3d 27 31 27 2c 20  columnsize='1', 
7d80: 63 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  c);.</codeblock>
7d90: 0a 0a 3c 70 3e 20 49 74 20 69 73 20 61 6e 20 65  ..<p> It is an e
7da0: 72 72 6f 72 20 74 6f 20 73 65 74 20 74 68 65 20  rror to set the 
7db0: 63 6f 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f  columnsize optio
7dc0: 6e 20 74 6f 20 61 6e 79 20 76 61 6c 75 65 20 6f  n to any value o
7dd0: 74 68 65 72 20 74 68 61 6e 0a 30 20 6f 72 20 31  ther than.0 or 1
7de0: 2e 0a 0a 3c 70 3e 20 49 66 20 61 6e 20 46 54 53  ...<p> If an FTS
7df0: 35 20 74 61 62 6c 65 20 69 73 20 63 6f 6e 66 69  5 table is confi
7e00: 67 75 72 65 64 20 77 69 74 68 20 63 6f 6c 75 6d  gured with colum
7e10: 6e 73 69 7a 65 3d 30 20 62 75 74 20 69 73 20 6e  nsize=0 but is n
7e20: 6f 74 20 61 0a 5b 46 54 53 35 20 63 6f 6e 74 65  ot a.[FTS5 conte
7e30: 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c 20  ntless tables | 
7e40: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
7e50: 65 5d 2c 20 74 68 65 20 78 43 6f 6c 75 6d 6e 53  e], the xColumnS
7e60: 69 7a 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ize API function
7e70: 0a 73 74 69 6c 6c 20 77 6f 72 6b 73 2c 20 62 75  .still works, bu
7e80: 74 20 72 75 6e 73 20 6d 75 63 68 20 6d 6f 72 65  t runs much more
7e90: 20 73 6c 6f 77 6c 79 2e 20 49 6e 20 74 68 69 73   slowly. In this
7ea0: 20 63 61 73 65 2c 20 69 6e 73 74 65 61 64 20 6f   case, instead o
7eb0: 66 20 72 65 61 64 69 6e 67 0a 74 68 65 20 76 61  f reading.the va
7ec0: 6c 75 65 20 74 6f 20 72 65 74 75 72 6e 20 64 69  lue to return di
7ed0: 72 65 63 74 6c 79 20 66 72 6f 6d 20 74 68 65 20  rectly from the 
7ee0: 64 61 74 61 62 61 73 65 2c 20 69 74 20 72 65 61  database, it rea
7ef0: 64 73 20 74 68 65 20 74 65 78 74 20 76 61 6c 75  ds the text valu
7f00: 65 0a 69 74 73 65 6c 66 20 61 6e 64 20 63 6f 75  e.itself and cou
7f10: 6e 74 20 74 68 65 20 74 6f 6b 65 6e 73 20 77 69  nt the tokens wi
7f20: 74 68 69 6e 20 69 74 20 6f 6e 20 64 65 6d 61 6e  thin it on deman
7f30: 64 2e 0a 0a 3c 70 3e 4f 72 2c 20 69 66 20 74 68  d...<p>Or, if th
7f40: 65 20 74 61 62 6c 65 20 69 73 20 61 6c 73 6f 20  e table is also 
7f50: 61 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c  a [FTS5 contentl
7f60: 65 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e  ess tables | con
7f70: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 5d 2c  tentless table],
7f80: 0a 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  .then the follow
7f90: 69 6e 67 20 61 70 70 6c 79 3a 0a 0a 3c 75 6c 3e  ing apply:..<ul>
7fa0: 0a 20 20 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 78  .  <li> <p>The x
7fb0: 43 6f 6c 75 6d 6e 53 69 7a 65 20 41 50 49 20 61  ColumnSize API a
7fc0: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 2d 31  lways returns -1
7fd0: 2e 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61  . There is no wa
7fe0: 79 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 0a  y to determine .
7ff0: 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
8000: 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 61  r of tokens in a
8010: 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 77 69   value stored wi
8020: 74 68 69 6e 20 61 20 63 6f 6e 74 65 6e 74 6c 65  thin a contentle
8030: 73 73 20 46 54 53 35 20 74 61 62 6c 65 0a 20 20  ss FTS5 table.  
8040: 20 20 20 20 20 63 6f 6e 66 69 67 75 72 65 64 20       configured 
8050: 77 69 74 68 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  with columnsize=
8060: 30 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 45 61  0...  <li> <p>Ea
8070: 63 68 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ch inserted row 
8080: 6d 75 73 74 20 62 65 20 61 63 63 6f 6d 70 61 6e  must be accompan
8090: 69 65 64 20 62 79 20 61 6e 20 65 78 70 6c 69 63  ied by an explic
80a0: 69 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 72  itly specified r
80b0: 6f 77 69 64 0a 20 20 20 20 20 20 20 76 61 6c 75  owid.       valu
80c0: 65 2e 20 49 66 20 61 20 63 6f 6e 74 65 6e 74 6c  e. If a contentl
80d0: 65 73 73 20 74 61 62 6c 65 20 69 73 20 63 6f 6e  ess table is con
80e0: 66 69 67 75 72 65 64 20 77 69 74 68 20 63 6f 6c  figured with col
80f0: 75 6d 6e 73 69 7a 65 3d 30 2c 0a 20 20 20 20 20  umnsize=0,.     
8100: 20 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20    attempting to 
8110: 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
8120: 6c 75 65 20 69 6e 74 6f 20 74 68 65 20 72 6f 77  lue into the row
8130: 69 64 20 69 73 20 61 6e 20 53 51 4c 49 54 45 5f  id is an SQLITE_
8140: 4d 49 53 4d 41 54 43 48 0a 20 20 20 20 20 20 20  MISMATCH.       
8150: 65 72 72 6f 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c  error...  <li> <
8160: 70 3e 41 6c 6c 20 71 75 65 72 69 65 73 20 6f 6e  p>All queries on
8170: 20 74 68 65 20 74 61 62 6c 65 20 6d 75 73 74 20   the table must 
8180: 62 65 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  be full-text que
8190: 72 69 65 73 2e 20 49 6e 20 6f 74 68 65 72 20 77  ries. In other w
81a0: 6f 72 64 73 2c 0a 20 20 20 20 20 20 20 74 68 65  ords,.       the
81b0: 79 20 6d 75 73 74 20 75 73 65 20 74 68 65 20 4d  y must use the M
81c0: 41 54 43 48 20 6f 72 20 3d 20 6f 70 65 72 61 74  ATCH or = operat
81d0: 6f 72 20 77 69 74 68 20 74 68 65 20 74 61 62 6c  or with the tabl
81e0: 65 2d 6e 61 6d 65 20 63 6f 6c 75 6d 6e 20 61 73  e-name column as
81f0: 20 74 68 65 0a 20 20 20 20 20 20 20 6c 65 66 74   the.       left
8200: 2d 68 61 6e 64 20 6f 70 65 72 61 6e 64 2c 20 6f  -hand operand, o
8210: 72 20 65 6c 73 65 20 75 73 65 20 74 68 65 20 74  r else use the t
8220: 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63  able-valued func
8230: 74 69 6f 6e 20 73 79 6e 74 61 78 2e 20 41 6e 79  tion syntax. Any
8240: 0a 20 20 20 20 20 20 20 71 75 65 72 79 20 74 68  .       query th
8250: 61 74 20 69 73 20 6e 6f 74 20 61 20 66 75 6c 6c  at is not a full
8260: 2d 74 65 78 74 20 71 75 65 72 79 20 72 65 73 75  -text query resu
8270: 6c 74 73 20 69 6e 20 61 6e 20 65 72 72 6f 72 2e  lts in an error.
8280: 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 54 68 65 20  .</ul>..<p> The 
8290: 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
82a0: 65 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 78  e in which the x
82b0: 43 6f 6c 75 6d 6e 53 69 7a 65 20 76 61 6c 75 65  ColumnSize value
82c0: 73 20 61 72 65 20 73 74 6f 72 65 64 0a 28 75 6e  s are stored.(un
82d0: 6c 65 73 73 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  less columnsize=
82e0: 30 20 69 73 20 73 70 65 63 69 66 69 65 64 29 20  0 is specified) 
82f0: 69 73 20 22 26 6c 74 3b 6e 61 6d 65 26 67 74 3b  is "&lt;name&gt;
8300: 5f 64 6f 63 73 69 7a 65 22 2c 20 77 68 65 72 65  _docsize", where
8310: 20 0a 26 6c 74 3b 6e 61 6d 65 26 67 74 3b 20 69   .&lt;name&gt; i
8320: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
8330: 65 20 46 54 53 35 20 74 61 62 6c 65 20 69 74 73  e FTS5 table its
8340: 65 6c 66 2e 20 54 68 65 20 0a 3c 61 20 68 72 65  elf. The .<a hre
8350: 66 3d 68 74 74 70 73 3a 2f 2f 77 77 77 2e 73 71  f=https://www.sq
8360: 6c 69 74 65 2e 6f 72 67 2f 64 6f 77 6e 6c 6f 61  lite.org/downloa
8370: 64 2e 68 74 6d 6c 3e 73 71 6c 69 74 65 33 5f 61  d.html>sqlite3_a
8380: 6e 61 6c 79 7a 65 72 3c 2f 61 3e 0a 74 6f 6f 6c  nalyzer</a>.tool
8390: 20 6d 61 79 20 62 65 20 75 73 65 64 20 6f 6e 20   may be used on 
83a0: 61 6e 20 65 78 69 73 74 69 6e 67 20 64 61 74 61  an existing data
83b0: 62 61 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  base in order to
83c0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 20 6d   determine how m
83d0: 75 63 68 0a 73 70 61 63 65 20 6d 69 67 68 74 20  uch.space might 
83e0: 62 65 20 73 61 76 65 64 20 62 79 20 72 65 63 72  be saved by recr
83f0: 65 61 74 69 6e 67 20 61 6e 20 46 54 53 35 20 74  eating an FTS5 t
8400: 61 62 6c 65 20 75 73 69 6e 67 20 63 6f 6c 75 6d  able using colum
8410: 6e 73 69 7a 65 3d 30 2e 0a 0a 3c 68 32 20 74 61  nsize=0...<h2 ta
8420: 67 73 3d 22 46 54 53 35 20 64 65 74 61 69 6c 20  gs="FTS5 detail 
8430: 6f 70 74 69 6f 6e 22 3e 54 68 65 20 44 65 74 61  option">The Deta
8440: 69 6c 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a  il Option</h2>..
8450: 3c 70 3e 20 46 6f 72 20 65 61 63 68 20 74 65 72  <p> For each ter
8460: 6d 20 69 6e 20 61 20 64 6f 63 75 6d 65 6e 74 2c  m in a document,
8470: 20 74 68 65 20 46 54 53 20 69 6e 64 65 78 20 6d   the FTS index m
8480: 61 69 6e 74 61 69 6e 65 64 20 62 79 20 46 54 53  aintained by FTS
8490: 35 20 0a 73 74 6f 72 65 73 20 74 68 65 20 72 6f  5 .stores the ro
84a0: 77 69 64 20 6f 66 20 74 68 65 20 64 6f 63 75 6d  wid of the docum
84b0: 65 6e 74 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ent, the column 
84c0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 65 20 63 6f  number of the co
84d0: 6c 75 6d 6e 20 74 68 61 74 20 63 6f 6e 74 61 69  lumn that contai
84e0: 6e 73 0a 74 68 65 20 74 65 72 6d 20 61 6e 64 20  ns.the term and 
84f0: 74 68 65 20 6f 66 66 73 65 74 20 6f 66 20 74 68  the offset of th
8500: 65 20 74 65 72 6d 20 77 69 74 68 69 6e 20 74 68  e term within th
8510: 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 20  e column value. 
8520: 54 68 65 20 22 64 65 74 61 69 6c 22 0a 6f 70 74  The "detail".opt
8530: 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
8540: 74 6f 20 6f 6d 69 74 20 73 6f 6d 65 20 6f 66 20  to omit some of 
8550: 74 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  this information
8560: 2e 20 54 68 69 73 20 72 65 64 75 63 65 73 20 74  . This reduces t
8570: 68 65 20 73 70 61 63 65 0a 74 68 61 74 20 74 68  he space.that th
8580: 65 20 69 6e 64 65 78 20 63 6f 6e 73 75 6d 65 73  e index consumes
8590: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
85a0: 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 61  base file, but a
85b0: 6c 73 6f 20 72 65 64 75 63 65 73 20 74 68 65 0a  lso reduces the.
85c0: 63 61 70 61 62 69 6c 69 74 79 20 61 6e 64 20 65  capability and e
85d0: 66 66 69 63 69 65 6e 63 79 20 6f 66 20 74 68 65  fficiency of the
85e0: 20 73 79 73 74 65 6d 2e 0a 0a 3c 70 3e 20 54 68   system...<p> Th
85f0: 65 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e 20  e detail option 
8600: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 22 66  may be set to "f
8610: 75 6c 6c 22 20 28 74 68 65 20 64 65 66 61 75 6c  ull" (the defaul
8620: 74 20 76 61 6c 75 65 29 2c 20 22 63 6f 6c 75 6d  t value), "colum
8630: 6e 22 20 6f 72 0a 22 6e 6f 6e 65 22 2e 20 46 6f  n" or."none". Fo
8640: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
8650: 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
8660: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
8670: 6f 20 6c 69 6e 65 73 20 61 72 65 20 65 71 75 69  o lines are equi
8680: 76 61 6c 65 6e 74 20 28 62 65 63 61 75 73 65 20  valent (because 
8690: 74 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  the default valu
86a0: 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 66  e</i>.  <i>-- of
86b0: 20 22 64 65 74 61 69 6c 22 20 69 73 20 22 66 75   "detail" is "fu
86c0: 6c 6c 22 2e 20 3c 2f 69 3e 0a 20 20 43 52 45 41  ll". </i>.  CREA
86d0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
86e0: 20 66 74 31 20 55 53 49 4e 47 20 66 74 73 35 28   ft1 USING fts5(
86f0: 61 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52 45 41  a, b, c);.  CREA
8700: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
8710: 20 66 74 31 20 55 53 49 4e 47 20 66 74 73 35 28   ft1 USING fts5(
8720: 61 2c 20 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d  a, b, c, detail=
8730: 66 75 6c 6c 29 3b 0a 0a 20 20 43 52 45 41 54 45  full);..  CREATE
8740: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
8750: 74 32 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  t2 USING fts5(a,
8760: 20 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d 63 6f   b, c, detail=co
8770: 6c 75 6d 6e 29 3b 0a 20 20 43 52 45 41 54 45 20  lumn);.  CREATE 
8780: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
8790: 33 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20  3 USING fts5(a, 
87a0: 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d 6e 6f 6e  b, c, detail=non
87b0: 65 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  e);.</codeblock>
87c0: 0a 0a 3c 70 3e 49 66 20 74 68 65 20 64 65 74 61  ..<p>If the deta
87d0: 69 6c 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  il option is set
87e0: 20 74 6f 20 3c 62 3e 63 6f 6c 75 6d 6e 3c 2f 62   to <b>column</b
87f0: 3e 2c 20 74 68 65 6e 20 66 6f 72 20 65 61 63 68  >, then for each
8800: 20 74 65 72 6d 20 74 68 65 20 46 54 53 0a 69 6e   term the FTS.in
8810: 64 65 78 20 72 65 63 6f 72 64 73 20 74 68 65 20  dex records the 
8820: 72 6f 77 69 64 20 61 6e 64 20 63 6f 6c 75 6d 6e  rowid and column
8830: 20 6e 75 6d 62 65 72 20 6f 6e 6c 79 2c 20 6f 6d   number only, om
8840: 69 74 74 69 6e 67 20 74 68 65 20 74 65 72 6d 20  itting the term 
8850: 6f 66 66 73 65 74 0a 69 6e 66 6f 72 6d 61 74 69  offset.informati
8860: 6f 6e 2e 20 54 68 69 73 20 72 65 73 75 6c 74 73  on. This results
8870: 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
8880: 67 20 72 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  g restrictions:.
8890: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 4e 45 41  .<ul>.  <li> NEA
88a0: 52 20 71 75 65 72 69 65 73 20 61 72 65 20 6e 6f  R queries are no
88b0: 74 20 61 76 61 69 6c 61 62 6c 65 2e 0a 20 20 3c  t available..  <
88c0: 6c 69 3e 20 50 68 72 61 73 65 20 71 75 65 72 69  li> Phrase queri
88d0: 65 73 20 61 72 65 20 6e 6f 74 20 61 76 61 69 6c  es are not avail
88e0: 61 62 6c 65 2e 0a 20 20 3c 6c 69 3e 20 41 73 73  able..  <li> Ass
88f0: 75 6d 69 6e 67 20 74 68 65 20 74 61 62 6c 65 20  uming the table 
8900: 69 73 20 6e 6f 74 20 61 6c 73 6f 20 61 20 0a 20  is not also a . 
8910: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
8920: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
8930: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 5d 2c 20  entless table], 
8940: 74 68 65 20 0a 20 20 3c 61 20 68 72 65 66 3d 23  the .  <a href=#
8950: 78 49 6e 73 74 43 6f 75 6e 74 3e 78 49 6e 73 74  xInstCount>xInst
8960: 43 6f 75 6e 74 3c 2f 61 3e 2c 20 3c 61 20 68 72  Count</a>, <a hr
8970: 65 66 3d 23 78 49 6e 73 74 3e 78 49 6e 73 74 3c  ef=#xInst>xInst<
8980: 2f 61 3e 2c 20 0a 20 20 3c 61 20 68 72 65 66 3d  /a>, .  <a href=
8990: 23 78 50 68 72 61 73 65 46 69 72 73 74 3e 78 50  #xPhraseFirst>xP
89a0: 68 72 61 73 65 46 69 72 73 74 3c 2f 61 3e 20 61  hraseFirst</a> a
89b0: 6e 64 20 3c 61 20 68 72 65 66 3d 23 78 50 68 72  nd <a href=#xPhr
89c0: 61 73 65 4e 65 78 74 3e 78 50 68 72 61 73 65 4e  aseNext>xPhraseN
89d0: 65 78 74 3c 2f 61 3e 0a 20 20 61 72 65 20 73 6c  ext</a>.  are sl
89e0: 6f 77 65 72 20 74 68 61 6e 20 75 73 75 61 6c 2e  ower than usual.
89f0: 20 54 68 69 73 20 69 73 20 62 65 63 61 75 73 65   This is because
8a00: 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 61 64   instead of read
8a10: 69 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 64  ing the required
8a20: 20 64 61 74 61 0a 20 20 64 69 72 65 63 74 6c 79   data.  directly
8a30: 20 66 72 6f 6d 20 74 68 65 20 46 54 53 20 69 6e   from the FTS in
8a40: 64 65 78 20 74 68 65 79 20 68 61 76 65 20 74 6f  dex they have to
8a50: 20 6c 6f 61 64 20 61 6e 64 20 74 6f 6b 65 6e 69   load and tokeni
8a60: 7a 65 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20  ze the document 
8a70: 74 65 78 74 20 0a 20 20 6f 6e 20 64 65 6d 61 6e  text .  on deman
8a80: 64 2e 0a 20 20 3c 6c 69 3e 20 49 66 20 74 68 65  d..  <li> If the
8a90: 20 74 61 62 6c 65 20 69 73 20 61 6c 73 6f 20 61   table is also a
8aa0: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62   contentless tab
8ab0: 6c 65 2c 20 74 68 65 20 78 49 6e 73 74 43 6f 75  le, the xInstCou
8ac0: 6e 74 2c 20 78 49 6e 73 74 2c 20 0a 20 20 78 50  nt, xInst, .  xP
8ad0: 68 72 61 73 65 46 69 72 73 74 20 61 6e 64 20 78  hraseFirst and x
8ae0: 50 68 72 61 73 65 4e 65 78 74 20 41 50 49 73 20  PhraseNext APIs 
8af0: 62 65 68 61 76 65 20 61 73 20 69 66 20 74 68 65  behave as if the
8b00: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 63 6f 6e   current row con
8b10: 74 61 69 6e 73 20 6e 6f 0a 20 20 70 68 72 61 73  tains no.  phras
8b20: 65 20 6d 61 74 63 68 65 73 20 61 74 20 61 6c 6c  e matches at all
8b30: 20 28 69 2e 65 2e 20 78 49 6e 73 74 43 6f 75 6e   (i.e. xInstCoun
8b40: 74 28 29 20 72 65 74 75 72 6e 73 20 30 29 2e 0a  t() returns 0)..
8b50: 3c 2f 75 6c 3e 0a 20 20 0a 3c 70 3e 49 66 20 74  </ul>.  .<p>If t
8b60: 68 65 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e  he detail option
8b70: 20 69 73 20 73 65 74 20 74 6f 20 3c 62 3e 6e 6f   is set to <b>no
8b80: 6e 65 3c 2f 62 3e 2c 20 74 68 65 6e 20 66 6f 72  ne</b>, then for
8b90: 20 65 61 63 68 20 74 65 72 6d 20 74 68 65 20 46   each term the F
8ba0: 54 53 0a 69 6e 64 65 78 20 72 65 63 6f 72 64 73  TS.index records
8bb0: 20 6a 75 73 74 20 74 68 65 20 72 6f 77 69 64 20   just the rowid 
8bc0: 69 73 20 73 74 6f 72 65 64 2e 20 42 6f 74 68 20  is stored. Both 
8bd0: 63 6f 6c 75 6d 6e 20 61 6e 64 20 6f 66 66 73 65  column and offse
8be0: 74 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61 72  t information.ar
8bf0: 65 20 6f 6d 69 74 74 65 64 2e 20 41 73 20 77 65  e omitted. As we
8c00: 6c 6c 20 61 73 20 74 68 65 20 72 65 73 74 72 69  ll as the restri
8c10: 63 74 69 6f 6e 73 20 69 74 65 6d 69 7a 65 64 20  ctions itemized 
8c20: 61 62 6f 76 65 20 66 6f 72 20 64 65 74 61 69 6c  above for detail
8c30: 3d 63 6f 6c 75 6d 6e 0a 6d 6f 64 65 2c 20 74 68  =column.mode, th
8c40: 69 73 20 69 6d 70 6f 73 65 73 20 74 68 65 20 66  is imposes the f
8c50: 6f 6c 6c 6f 77 69 6e 67 20 65 78 74 72 61 20 6c  ollowing extra l
8c60: 69 6d 69 74 61 74 69 6f 6e 73 3a 0a 0a 3c 75 6c  imitations:..<ul
8c70: 3e 0a 20 20 3c 6c 69 3e 20 43 6f 6c 75 6d 6e 20  >.  <li> Column 
8c80: 66 69 6c 74 65 72 20 71 75 65 72 69 65 73 20 61  filter queries a
8c90: 72 65 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  re not available
8ca0: 2e 0a 20 20 3c 6c 69 3e 20 41 73 73 75 6d 69 6e  ..  <li> Assumin
8cb0: 67 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 6e  g the table is n
8cc0: 6f 74 20 61 6c 73 6f 20 61 20 63 6f 6e 74 65 6e  ot also a conten
8cd0: 74 6c 65 73 73 20 74 61 62 6c 65 2c 20 74 68 65  tless table, the
8ce0: 20 0a 20 20 3c 61 20 68 72 65 66 3d 23 78 50 68   .  <a href=#xPh
8cf0: 72 61 73 65 46 69 72 73 74 43 6f 6c 75 6d 6e 3e  raseFirstColumn>
8d00: 78 50 68 72 61 73 65 46 69 72 73 74 43 6f 6c 75  xPhraseFirstColu
8d10: 6d 6e 3c 2f 61 3e 20 61 6e 64 20 0a 20 20 3c 61  mn</a> and .  <a
8d20: 20 68 72 65 66 3d 23 78 50 68 72 61 73 65 4e 65   href=#xPhraseNe
8d30: 78 74 43 6f 6c 75 6d 6e 3e 78 50 68 72 61 73 65  xtColumn>xPhrase
8d40: 4e 65 78 74 43 6f 6c 75 6d 6e 3c 2f 61 3e 20 61  NextColumn</a> a
8d50: 72 65 20 73 6c 6f 77 65 72 20 74 68 61 6e 20 75  re slower than u
8d60: 73 75 61 6c 2e 20 0a 0a 20 20 3c 6c 69 3e 20 49  sual. ..  <li> I
8d70: 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61  f the table is a
8d80: 6c 73 6f 20 61 20 63 6f 6e 74 65 6e 74 6c 65 73  lso a contentles
8d90: 73 20 74 61 62 6c 65 2c 20 74 68 65 20 78 50 68  s table, the xPh
8da0: 72 61 73 65 46 69 72 73 74 43 6f 6c 75 6d 6e 20  raseFirstColumn 
8db0: 61 6e 64 0a 20 20 78 50 68 72 61 73 65 4e 65 78  and.  xPhraseNex
8dc0: 74 43 6f 6c 75 6d 6e 20 41 50 49 73 20 62 65 68  tColumn APIs beh
8dd0: 61 76 65 20 61 73 20 69 66 20 74 68 65 20 63 75  ave as if the cu
8de0: 72 72 65 6e 74 20 72 6f 77 20 63 6f 6e 74 61 69  rrent row contai
8df0: 6e 73 20 6e 6f 20 70 68 72 61 73 65 0a 20 20 6d  ns no phrase.  m
8e00: 61 74 63 68 65 73 20 61 74 20 61 6c 6c 20 28 69  atches at all (i
8e10: 2e 65 2e 20 78 50 68 72 61 73 65 46 69 72 73 74  .e. xPhraseFirst
8e20: 43 6f 6c 75 6d 6e 28 29 20 73 65 74 73 20 74 68  Column() sets th
8e30: 65 20 69 74 65 72 61 74 6f 72 20 74 6f 20 45 4f  e iterator to EO
8e40: 46 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 49  F)..</ul>..<p> I
8e50: 6e 20 6f 6e 65 20 74 65 73 74 20 74 68 61 74 20  n one test that 
8e60: 69 6e 64 65 78 65 64 20 61 20 6c 61 72 67 65 20  indexed a large 
8e70: 73 65 74 20 6f 66 20 65 6d 61 69 6c 73 20 28 31  set of emails (1
8e80: 36 33 36 20 4d 69 42 20 6f 6e 20 64 69 73 6b 29  636 MiB on disk)
8e90: 2c 20 74 68 65 20 46 54 53 0a 69 6e 64 65 78 20  , the FTS.index 
8ea0: 77 61 73 20 37 34 33 20 4d 69 42 20 6f 6e 20 64  was 743 MiB on d
8eb0: 69 73 6b 20 77 69 74 68 20 64 65 74 61 69 6c 3d  isk with detail=
8ec0: 66 75 6c 6c 2c 20 33 34 30 20 4d 69 42 20 77 69  full, 340 MiB wi
8ed0: 74 68 20 64 65 74 61 69 6c 3d 63 6f 6c 75 6d 6e  th detail=column
8ee0: 20 61 6e 64 20 31 33 34 0a 4d 69 42 20 77 69 74   and 134.MiB wit
8ef0: 68 20 64 65 74 61 69 6c 3d 6e 6f 6e 65 2e 0a 0a  h detail=none...
8f00: 3c 68 31 20 74 61 67 73 3d 22 46 54 53 35 20 61  <h1 tags="FTS5 a
8f10: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
8f20: 6e 73 22 3e 20 41 75 78 69 6c 69 61 72 79 20 46  ns"> Auxiliary F
8f30: 75 6e 63 74 69 6f 6e 73 20 3c 2f 68 31 3e 0a 0a  unctions </h1>..
8f40: 3c 70 3e 20 41 75 78 69 6c 69 61 72 79 20 66 75  <p> Auxiliary fu
8f50: 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 69 6d 69  nctions are simi
8f60: 6c 61 72 20 74 6f 20 5b 63 6f 72 65 66 75 6e 63  lar to [corefunc
8f70: 20 7c 20 53 51 4c 20 73 63 61 6c 61 72 20 66 75   | SQL scalar fu
8f80: 6e 63 74 69 6f 6e 73 5d 2c 0a 65 78 63 65 70 74  nctions],.except
8f90: 20 74 68 61 74 20 74 68 65 79 20 6d 61 79 20 6f   that they may o
8fa0: 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
8fb0: 69 6e 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  in full-text que
8fc0: 72 69 65 73 20 28 74 68 6f 73 65 20 74 68 61 74  ries (those that
8fd0: 20 75 73 65 0a 74 68 65 20 4d 41 54 43 48 20 6f   use.the MATCH o
8fe0: 70 65 72 61 74 6f 72 29 20 6f 6e 20 61 6e 20 46  perator) on an F
8ff0: 54 53 35 20 74 61 62 6c 65 2e 20 54 68 65 69 72  TS5 table. Their
9000: 20 72 65 73 75 6c 74 73 20 61 72 65 20 63 61 6c   results are cal
9010: 63 75 6c 61 74 65 64 20 62 61 73 65 64 20 6e 6f  culated based no
9020: 74 0a 6f 6e 6c 79 20 6f 6e 20 74 68 65 20 61 72  t.only on the ar
9030: 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74  guments passed t
9040: 6f 20 74 68 65 6d 2c 20 62 75 74 20 61 6c 73 6f  o them, but also
9050: 20 6f 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   on the current 
9060: 6d 61 74 63 68 20 61 6e 64 20 0a 6d 61 74 63 68  match and .match
9070: 65 64 20 72 6f 77 2e 20 46 6f 72 20 65 78 61 6d  ed row. For exam
9080: 70 6c 65 2c 20 61 6e 20 61 75 78 69 6c 69 61 72  ple, an auxiliar
9090: 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 72  y function may r
90a0: 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
90b0: 76 61 6c 75 65 0a 69 6e 64 69 63 61 74 69 6e 67  value.indicating
90c0: 20 74 68 65 20 61 63 63 75 72 61 63 79 20 6f 66   the accuracy of
90d0: 20 74 68 65 20 6d 61 74 63 68 20 28 73 65 65 20   the match (see 
90e0: 74 68 65 20 5b 46 54 53 35 20 62 6d 32 35 7c 20  the [FTS5 bm25| 
90f0: 62 6d 32 35 28 29 5d 20 66 75 6e 63 74 69 6f 6e  bm25()] function
9100: 29 2c 20 0a 6f 72 20 61 20 66 72 61 67 6d 65 6e  ), .or a fragmen
9110: 74 20 6f 66 20 74 65 78 74 20 66 72 6f 6d 20 74  t of text from t
9120: 68 65 20 6d 61 74 63 68 65 64 20 72 6f 77 20 74  he matched row t
9130: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  hat contains one
9140: 20 6f 72 20 6d 6f 72 65 20 0a 69 6e 73 74 61 6e   or more .instan
9150: 63 65 73 20 6f 66 20 74 68 65 20 73 65 61 72 63  ces of the searc
9160: 68 20 74 65 72 6d 73 20 28 73 65 65 20 74 68 65  h terms (see the
9170: 20 5b 46 54 53 35 20 73 6e 69 70 70 65 74 20 7c   [FTS5 snippet |
9180: 20 73 6e 69 70 70 65 74 28 29 5d 20 66 75 6e 63   snippet()] func
9190: 74 69 6f 6e 29 2e 0a 0a 3c 70 3e 54 6f 20 69 6e  tion)...<p>To in
91a0: 76 6f 6b 65 20 61 6e 20 61 75 78 69 6c 69 61 72  voke an auxiliar
91b0: 79 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 20  y function, the 
91c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 46 54 53 35  name of the FTS5
91d0: 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
91e0: 0a 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68  .specified as th
91f0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
9200: 2e 20 4f 74 68 65 72 20 61 72 67 75 6d 65 6e 74  . Other argument
9210: 73 20 6d 61 79 20 66 6f 6c 6c 6f 77 20 74 68 65  s may follow the
9220: 20 66 69 72 73 74 2c 0a 64 65 70 65 6e 64 69 6e   first,.dependin
9230: 67 20 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69  g on the specifi
9240: 63 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  c auxiliary func
9250: 74 69 6f 6e 20 62 65 69 6e 67 20 69 6e 76 6f 6b  tion being invok
9260: 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ed. For example,
9270: 20 74 6f 0a 69 6e 76 6f 6b 65 20 74 68 65 20 22   to.invoke the "
9280: 68 69 67 68 6c 69 67 68 74 22 20 66 75 6e 63 74  highlight" funct
9290: 69 6f 6e 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ion:..<codeblock
92a0: 3e 0a 20 20 53 45 4c 45 43 54 20 68 69 67 68 6c  >.  SELECT highl
92b0: 69 67 68 74 28 65 6d 61 69 6c 2c 20 32 2c 20 27  ight(email, 2, '
92c0: 26 6c 74 3b 62 26 67 74 3b 27 2c 20 27 26 6c 74  &lt;b&gt;', '&lt
92d0: 3b 2f 62 26 67 74 3b 27 29 20 46 52 4f 4d 20 65  ;/b&gt;') FROM e
92e0: 6d 61 69 6c 20 57 48 45 52 45 20 65 6d 61 69 6c  mail WHERE email
92f0: 20 4d 41 54 43 48 20 27 66 74 73 35 27 0a 3c 2f   MATCH 'fts5'.</
9300: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54  codeblock>..<p>T
9310: 68 65 20 62 75 69 6c 74 2d 69 6e 20 61 75 78 69  he built-in auxi
9320: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  liary functions 
9330: 70 72 6f 76 69 64 65 64 20 61 73 20 70 61 72 74  provided as part
9340: 20 6f 66 20 46 54 53 35 20 61 72 65 20 64 65 73   of FTS5 are des
9350: 63 72 69 62 65 64 20 69 6e 0a 74 68 65 20 66 6f  cribed in.the fo
9360: 6c 6c 6f 77 69 6e 67 20 73 65 63 74 69 6f 6e 2e  llowing section.
9370: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   Applications ma
9380: 79 20 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e 74  y also implement
9390: 20 0a 5b 46 54 53 35 20 63 75 73 74 6f 6d 20 61   .[FTS5 custom a
93a0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
93b0: 6e 73 20 7c 20 63 75 73 74 6f 6d 20 61 75 78 69  ns | custom auxi
93c0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  liary functions 
93d0: 69 6e 20 43 5d 2e 0a 0a 3c 68 32 3e 42 75 69 6c  in C]...<h2>Buil
93e0: 74 2d 69 6e 20 41 75 78 69 6c 69 61 72 79 20 46  t-in Auxiliary F
93f0: 75 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c  unctions</h2>..<
9400: 70 3e 20 46 54 53 35 20 70 72 6f 76 69 64 65 73  p> FTS5 provides
9410: 20 74 68 72 65 65 20 62 75 69 6c 74 2d 69 6e 20   three built-in 
9420: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
9430: 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  ons:..<ul>.  <li
9440: 3e 20 54 68 65 20 5b 46 54 53 35 20 62 6d 32 35  > The [FTS5 bm25
9450: 20 7c 20 62 6d 32 35 28 29 20 61 75 78 69 6c 69   | bm25() auxili
9460: 61 72 79 20 66 75 6e 63 74 69 6f 6e 5d 20 72 65  ary function] re
9470: 74 75 72 6e 73 20 61 20 72 65 61 6c 20 76 61 6c  turns a real val
9480: 75 65 0a 20 20 20 20 20 20 20 72 65 66 6c 65 63  ue.       reflec
9490: 74 69 6e 67 20 74 68 65 20 61 63 63 75 72 61 63  ting the accurac
94a0: 79 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  y of the current
94b0: 20 6d 61 74 63 68 2e 20 42 65 74 74 65 72 20 6d   match. Better m
94c0: 61 74 63 68 65 73 20 61 72 65 0a 20 20 20 20 20  atches are.     
94d0: 20 20 61 73 73 69 67 6e 65 64 20 6e 75 6d 65 72    assigned numer
94e0: 69 63 61 6c 6c 79 20 6c 6f 77 65 72 20 76 61 6c  ically lower val
94f0: 75 65 73 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65  ues...  <li> The
9500: 20 5b 46 54 53 35 20 68 69 67 68 6c 69 67 68 74   [FTS5 highlight
9510: 20 7c 20 68 69 67 68 6c 69 67 68 74 28 29 20 61   | highlight() a
9520: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
9530: 6e 5d 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  n] returns a cop
9540: 79 0a 20 20 20 20 20 20 20 6f 66 20 74 68 65 20  y.       of the 
9550: 74 65 78 74 20 66 72 6f 6d 20 6f 6e 65 20 6f 66  text from one of
9560: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66 20   the columns of 
9570: 74 68 65 20 63 75 72 72 65 6e 74 20 6d 61 74 63  the current matc
9580: 68 20 77 69 74 68 20 65 61 63 68 0a 20 20 20 20  h with each.    
9590: 20 20 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61     instance of a
95a0: 20 71 75 65 72 69 65 64 20 74 65 72 6d 20 77 69   queried term wi
95b0: 74 68 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  thin the result 
95c0: 73 75 72 72 6f 75 6e 64 65 64 20 62 79 20 73 70  surrounded by sp
95d0: 65 63 69 66 69 65 64 0a 20 20 20 20 20 20 20 6d  ecified.       m
95e0: 61 72 6b 75 70 20 28 66 6f 72 20 65 78 61 6d 70  arkup (for examp
95f0: 6c 65 20 22 26 6c 74 3b 62 26 67 74 3b 22 20 61  le "&lt;b&gt;" a
9600: 6e 64 20 22 26 6c 74 3b 2f 62 26 67 74 3b 22 29  nd "&lt;/b&gt;")
9610: 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 5b 46  ...  <li> The [F
9620: 54 53 35 20 73 6e 69 70 70 65 74 20 7c 20 73 6e  TS5 snippet | sn
9630: 69 70 70 65 74 28 29 20 61 75 78 69 6c 69 61 72  ippet() auxiliar
9640: 79 20 66 75 6e 63 74 69 6f 6e 5d 20 73 65 6c 65  y function] sele
9650: 63 74 73 20 61 20 73 68 6f 72 74 0a 20 20 20 20  cts a short.    
9660: 20 20 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 74     fragment of t
9670: 65 78 74 20 66 72 6f 6d 20 6f 6e 65 20 6f 66 20  ext from one of 
9680: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74  the columns of t
9690: 68 65 20 6d 61 74 63 68 65 64 20 72 6f 77 20 61  he matched row a
96a0: 6e 64 20 72 65 74 75 72 6e 73 0a 20 20 20 20 20  nd returns.     
96b0: 20 20 69 74 20 77 69 74 68 20 65 61 63 68 20 69    it with each i
96c0: 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 71 75 65  nstance of a que
96d0: 72 69 65 64 20 74 65 72 6d 20 73 75 72 72 6f 75  ried term surrou
96e0: 6e 64 65 64 20 62 79 20 6d 61 72 6b 75 70 20 69  nded by markup i
96f0: 6e 0a 20 20 20 20 20 20 20 74 68 65 20 73 61 6d  n.       the sam
9700: 65 20 6d 61 6e 6e 65 72 20 61 73 20 74 68 65 20  e manner as the 
9710: 68 69 67 68 6c 69 67 68 74 28 29 20 66 75 6e 63  highlight() func
9720: 74 69 6f 6e 2e 20 54 68 65 20 66 72 61 67 6d 65  tion. The fragme
9730: 6e 74 20 6f 66 20 74 65 78 74 20 69 73 0a 20 20  nt of text is.  
9740: 20 20 20 20 20 73 65 6c 65 63 74 65 64 20 73 6f       selected so
9750: 20 61 73 20 74 6f 20 6d 61 78 69 6d 69 7a 65 20   as to maximize 
9760: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 71 75  the number of qu
9770: 65 72 69 65 64 20 74 65 72 6d 73 20 69 74 20 63  eried terms it c
9780: 6f 6e 74 61 69 6e 73 2e 0a 3c 2f 75 6c 3e 0a 0a  ontains..</ul>..
9790: 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 62  <h3 tags="FTS5 b
97a0: 6d 32 35 22 3e 54 68 65 20 62 6d 32 35 28 29 20  m25">The bm25() 
97b0: 66 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c  function</h3>..<
97c0: 70 3e 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  p> The built-in 
97d0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
97e0: 6f 6e 20 62 6d 32 35 28 29 20 72 65 74 75 72 6e  on bm25() return
97f0: 73 20 61 20 72 65 61 6c 20 76 61 6c 75 65 20 69  s a real value i
9800: 6e 64 69 63 61 74 69 6e 67 0a 68 6f 77 20 77 65  ndicating.how we
9810: 6c 6c 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ll the current r
9820: 6f 77 20 6d 61 74 63 68 65 73 20 74 68 65 20 66  ow matches the f
9830: 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 2e 20  ull-text query. 
9840: 54 68 65 20 62 65 74 74 65 72 20 74 68 65 20 6d  The better the m
9850: 61 74 63 68 2c 0a 74 68 65 20 6e 75 6d 65 72 69  atch,.the numeri
9860: 63 61 6c 6c 79 20 73 6d 61 6c 6c 65 72 20 74 68  cally smaller th
9870: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
9880: 2e 20 41 20 71 75 65 72 79 20 73 75 63 68 20 61  . A query such a
9890: 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
98a0: 6d 61 79 0a 62 65 20 75 73 65 64 20 74 6f 20 72  may.be used to r
98b0: 65 74 75 72 6e 20 6d 61 74 63 68 65 73 20 69 6e  eturn matches in
98c0: 20 6f 72 64 65 72 20 66 72 6f 6d 20 62 65 73 74   order from best
98d0: 20 74 6f 20 77 6f 72 73 74 20 6d 61 74 63 68 3a   to worst match:
98e0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
98f0: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
9900: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
9910: 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62 6d 32  H ? ORDER BY bm2
9920: 35 28 66 74 73 29 0a 3c 2f 63 6f 64 65 62 6c 6f  5(fts).</codeblo
9930: 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65  ck>..<p> In orde
9940: 72 20 74 6f 20 63 61 6c 63 75 6c 61 74 65 20 61  r to calculate a
9950: 20 64 6f 63 75 6d 65 6e 74 73 20 73 63 6f 72 65   documents score
9960: 2c 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  , the full-text 
9970: 71 75 65 72 79 20 69 73 20 73 65 70 61 72 61 74  query is separat
9980: 65 64 0a 20 20 20 20 69 6e 74 6f 20 69 74 73 20  ed.    into its 
9990: 63 6f 6d 70 6f 6e 65 6e 74 20 70 68 72 61 73 65  component phrase
99a0: 73 2e 20 54 68 65 20 62 6d 32 35 20 73 63 6f 72  s. The bm25 scor
99b0: 65 20 66 6f 72 20 64 6f 63 75 6d 65 6e 74 20 3c  e for document <
99c0: 69 3e 44 3c 2f 69 3e 20 61 6e 64 20 0a 20 20 20  i>D</i> and .   
99d0: 20 71 75 65 72 79 20 3c 69 3e 51 3c 2f 69 3e 20   query <i>Q</i> 
99e0: 69 73 20 74 68 65 6e 20 63 61 6c 63 75 6c 61 74  is then calculat
99f0: 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a  ed as follows:..
9a00: 3c 70 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d  <p> <img src="im
9a10: 61 67 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c  ages/fts5_formul
9a20: 61 31 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77  a1.png" style="w
9a30: 69 64 74 68 3a 37 35 65 78 3b 6d 61 72 67 69 6e  idth:75ex;margin
9a40: 2d 6c 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e  -left:5ex">..<p>
9a50: 20 49 6e 20 74 68 65 20 61 62 6f 76 65 2c 20 3c   In the above, <
9a60: 69 3e 6e 50 68 72 61 73 65 3c 2f 69 3e 20 69 73  i>nPhrase</i> is
9a70: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
9a80: 68 72 61 73 65 73 20 69 6e 20 74 68 65 20 71 75  hrases in the qu
9a90: 65 72 79 2e 0a 20 20 20 20 3c 69 3e 7c 44 7c 3c  ery..    <i>|D|<
9aa0: 2f 69 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  /i> is the numbe
9ab0: 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 74  r of tokens in t
9ac0: 68 65 20 63 75 72 72 65 6e 74 20 64 6f 63 75 6d  he current docum
9ad0: 65 6e 74 2c 20 61 6e 64 0a 20 20 20 20 3c 69 3e  ent, and.    <i>
9ae0: 61 76 67 64 6c 3c 2f 69 3e 20 69 73 20 74 68 65  avgdl</i> is the
9af0: 20 61 76 65 72 61 67 65 20 6e 75 6d 62 65 72 20   average number 
9b00: 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 61 6c 6c  of tokens in all
9b10: 20 64 6f 63 75 6d 65 6e 74 73 20 77 69 74 68 69   documents withi
9b20: 6e 20 74 68 65 0a 20 20 20 20 46 54 53 35 20 74  n the.    FTS5 t
9b30: 61 62 6c 65 2e 20 20 3c 69 3e 6b 3c 73 75 62 3e  able.  <i>k<sub>
9b40: 31 3c 2f 73 75 62 3e 3c 2f 69 3e 20 61 6e 64 20  1</sub></i> and 
9b50: 3c 69 3e 62 3c 2f 69 3e 20 61 72 65 20 62 6f 74  <i>b</i> are bot
9b60: 68 20 63 6f 6e 73 74 61 6e 74 73 2c 0a 20 20 20  h constants,.   
9b70: 20 68 61 72 64 2d 63 6f 64 65 64 20 61 74 20 31   hard-coded at 1
9b80: 2e 32 20 61 6e 64 20 30 2e 37 35 20 72 65 73 70  .2 and 0.75 resp
9b90: 65 63 74 69 76 65 6c 79 2e 0a 0a 3c 70 3e 20 54  ectively...<p> T
9ba0: 68 65 20 22 2d 31 22 20 74 65 72 6d 20 61 74 20  he "-1" term at 
9bb0: 74 68 65 20 73 74 61 72 74 20 6f 66 20 74 68 65  the start of the
9bc0: 20 66 6f 72 6d 75 6c 61 20 69 73 20 6e 6f 74 20   formula is not 
9bd0: 66 6f 75 6e 64 20 69 6e 20 6d 6f 73 74 0a 69 6d  found in most.im
9be0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
9bf0: 20 74 68 65 20 42 4d 32 35 20 61 6c 67 6f 72 69   the BM25 algori
9c00: 74 68 6d 2e 20 57 69 74 68 6f 75 74 20 69 74 2c  thm. Without it,
9c10: 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
9c20: 69 73 20 61 73 73 69 67 6e 65 64 0a 61 20 6e 75  is assigned.a nu
9c30: 6d 65 72 69 63 61 6c 6c 79 20 68 69 67 68 65 72  merically higher
9c40: 20 42 4d 32 35 20 73 63 6f 72 65 2e 20 53 69 6e   BM25 score. Sin
9c50: 63 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ce the default s
9c60: 6f 72 74 69 6e 67 20 6f 72 64 65 72 20 69 73 0a  orting order is.
9c70: 22 61 73 63 65 6e 64 69 6e 67 22 2c 20 74 68 69  "ascending", thi
9c80: 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 70 70  s means that app
9c90: 65 6e 64 69 6e 67 20 22 4f 52 44 45 52 20 42 59  ending "ORDER BY
9ca0: 20 62 6d 32 35 28 66 74 73 29 22 20 74 6f 20 61   bm25(fts)" to a
9cb0: 20 71 75 65 72 79 20 77 6f 75 6c 64 0a 63 61 75   query would.cau
9cc0: 73 65 20 72 65 73 75 6c 74 73 20 74 6f 20 62 65  se results to be
9cd0: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 6f 72 64   returned in ord
9ce0: 65 72 20 66 72 6f 6d 20 77 6f 72 73 74 20 74 6f  er from worst to
9cf0: 20 62 65 73 74 2e 20 54 68 65 20 22 44 45 53 43   best. The "DESC
9d00: 22 20 6b 65 79 77 6f 72 64 0a 77 6f 75 6c 64 20  " keyword.would 
9d10: 62 65 20 72 65 71 75 69 72 65 64 20 69 6e 20 6f  be required in o
9d20: 72 64 65 72 20 74 6f 20 72 65 74 75 72 6e 20 74  rder to return t
9d30: 68 65 20 62 65 73 74 20 6d 61 74 63 68 65 73 20  he best matches 
9d40: 66 69 72 73 74 2e 20 49 6e 20 6f 72 64 65 72 20  first. In order 
9d50: 74 6f 0a 61 76 6f 69 64 20 74 68 69 73 20 70 69  to.avoid this pi
9d60: 74 66 61 6c 6c 2c 20 74 68 65 20 46 54 53 35 20  tfall, the FTS5 
9d70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
9d80: 66 20 42 4d 32 35 20 6d 75 6c 74 69 70 6c 69 65  f BM25 multiplie
9d90: 73 20 74 68 65 20 72 65 73 75 6c 74 0a 62 79 20  s the result.by 
9da0: 2d 31 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  -1 before return
9db0: 69 6e 67 20 69 74 2c 20 65 6e 73 75 72 69 6e 67  ing it, ensuring
9dc0: 20 74 68 61 74 20 62 65 74 74 65 72 20 6d 61 74   that better mat
9dd0: 63 68 65 73 20 61 72 65 20 61 73 73 69 67 6e 65  ches are assigne
9de0: 64 0a 6e 75 6d 65 72 69 63 61 6c 6c 79 20 6c 6f  d.numerically lo
9df0: 77 65 72 20 73 63 6f 72 65 73 2e 0a 0a 3c 70 3e  wer scores...<p>
9e00: 20 3c 69 3e 49 44 46 28 71 3c 73 75 62 3e 69 3c   <i>IDF(q<sub>i<
9e10: 2f 73 75 62 3e 29 3c 2f 69 3e 20 69 73 20 74 68  /sub>)</i> is th
9e20: 65 20 69 6e 76 65 72 73 65 2d 64 6f 63 75 6d 65  e inverse-docume
9e30: 6e 74 2d 66 72 65 71 75 65 6e 63 79 20 6f 66 20  nt-frequency of 
9e40: 71 75 65 72 79 20 0a 20 20 20 20 70 68 72 61 73  query .    phras
9e50: 65 20 3c 69 3e 69 3c 2f 69 3e 2e 20 49 74 20 69  e <i>i</i>. It i
9e60: 73 20 63 61 6c 63 75 6c 61 74 65 64 20 61 73 20  s calculated as 
9e70: 66 6f 6c 6c 6f 77 73 2c 20 77 68 65 72 65 20 3c  follows, where <
9e80: 69 3e 4e 3c 2f 69 3e 20 69 73 20 74 68 65 20 74  i>N</i> is the t
9e90: 6f 74 61 6c 0a 20 20 20 20 6e 75 6d 62 65 72 20  otal.    number 
9ea0: 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 20 46  of rows in the F
9eb0: 54 53 35 20 74 61 62 6c 65 20 61 6e 64 20 3c 69  TS5 table and <i
9ec0: 3e 6e 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62 3e  >n(q<sub>i</sub>
9ed0: 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 74 6f 74  )</i> is the tot
9ee0: 61 6c 0a 20 20 20 20 6e 75 6d 62 65 72 20 6f 66  al.    number of
9ef0: 20 72 6f 77 73 20 74 68 61 74 20 63 6f 6e 74 61   rows that conta
9f00: 69 6e 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20  in at least one 
9f10: 69 6e 73 74 61 6e 63 65 20 6f 66 20 70 68 72 61  instance of phra
9f20: 73 65 20 3c 69 3e 69 3c 2f 69 3e 3a 0a 0a 3c 70  se <i>i</i>:..<p
9f30: 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d 61 67  > <img src="imag
9f40: 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c 61 32  es/fts5_formula2
9f50: 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77 69 64  .png" style="wid
9f60: 74 68 3a 37 35 65 78 3b 6d 61 72 67 69 6e 2d 6c  th:75ex;margin-l
9f70: 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e 20 46  eft:5ex">..<p> F
9f80: 69 6e 61 6c 6c 79 2c 20 3c 69 3e 66 28 71 3c 73  inally, <i>f(q<s
9f90: 75 62 3e 69 3c 2f 73 75 62 3e 2c 44 29 3c 2f 69  ub>i</sub>,D)</i
9fa0: 3e 20 69 73 20 74 68 65 20 70 68 72 61 73 65 20  > is the phrase 
9fb0: 66 72 65 71 75 65 6e 63 79 20 6f 66 20 70 68 72  frequency of phr
9fc0: 61 73 65 20 0a 3c 69 3e 69 3c 2f 69 3e 2e 20 42  ase .<i>i</i>. B
9fd0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 69 73 20  y default, this 
9fe0: 69 73 20 73 69 6d 70 6c 79 20 74 68 65 20 6e 75  is simply the nu
9ff0: 6d 62 65 72 20 6f 66 20 6f 63 63 75 72 72 65 6e  mber of occurren
a000: 63 65 73 20 6f 66 20 74 68 65 20 70 68 72 61 73  ces of the phras
a010: 65 0a 77 69 74 68 69 6e 20 74 68 65 20 63 75 72  e.within the cur
a020: 72 65 6e 74 20 72 6f 77 2e 20 48 6f 77 65 76 65  rent row. Howeve
a030: 72 2c 20 62 79 20 70 61 73 73 69 6e 67 20 65 78  r, by passing ex
a040: 74 72 61 20 72 65 61 6c 20 76 61 6c 75 65 20 61  tra real value a
a050: 72 67 75 6d 65 6e 74 73 20 74 6f 20 0a 74 68 65  rguments to .the
a060: 20 62 6d 32 35 28 29 20 53 51 4c 20 66 75 6e 63   bm25() SQL func
a070: 74 69 6f 6e 2c 20 65 61 63 68 20 63 6f 6c 75 6d  tion, each colum
a080: 6e 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 6d  n of the table m
a090: 61 79 20 62 65 20 61 73 73 69 67 6e 65 64 20 61  ay be assigned a
a0a0: 20 64 69 66 66 65 72 65 6e 74 0a 77 65 69 67 68   different.weigh
a0b0: 74 20 61 6e 64 20 74 68 65 20 70 68 72 61 73 65  t and the phrase
a0c0: 20 66 72 65 71 75 65 6e 63 79 20 63 61 6c 63 75   frequency calcu
a0d0: 6c 61 74 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73  lated as follows
a0e0: 3a 0a 0a 3c 70 3e 20 3c 69 6d 67 20 73 72 63 3d  :..<p> <img src=
a0f0: 22 69 6d 61 67 65 73 2f 66 74 73 35 5f 66 6f 72  "images/fts5_for
a100: 6d 75 6c 61 33 2e 70 6e 67 22 20 73 74 79 6c 65  mula3.png" style
a110: 3d 22 77 69 64 74 68 3a 37 35 65 78 3b 6d 61 72  ="width:75ex;mar
a120: 67 69 6e 2d 6c 65 66 74 3a 35 65 78 22 3e 0a 0a  gin-left:5ex">..
a130: 3c 70 3e 20 77 68 65 72 65 20 3c 69 3e 77 3c 73  <p> where <i>w<s
a140: 75 62 3e 63 3c 2f 73 75 62 3e 3c 2f 69 3e 20 69  ub>c</sub></i> i
a150: 73 20 74 68 65 20 77 65 69 67 68 74 20 61 73 73  s the weight ass
a160: 69 67 6e 65 64 20 74 6f 20 63 6f 6c 75 6d 6e 20  igned to column 
a170: 3c 69 3e 63 3c 2f 69 3e 20 61 6e 64 0a 3c 69 3e  <i>c</i> and.<i>
a180: 6e 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62 3e 2c  n(q<sub>i</sub>,
a190: 63 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e 75  c)</i> is the nu
a1a0: 6d 62 65 72 20 6f 66 20 6f 63 63 75 72 72 65 6e  mber of occurren
a1b0: 63 65 73 20 6f 66 20 70 68 72 61 73 65 20 3c 69  ces of phrase <i
a1c0: 3e 69 3c 2f 69 3e 20 69 6e 0a 63 6f 6c 75 6d 6e  >i</i> in.column
a1d0: 20 3c 69 3e 63 3c 2f 69 3e 20 6f 66 20 74 68 65   <i>c</i> of the
a1e0: 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 54 68   current row. Th
a1f0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
a200: 20 70 61 73 73 65 64 20 74 6f 20 62 6d 32 35 28   passed to bm25(
a210: 29 0a 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20  ).following the 
a220: 74 61 62 6c 65 20 6e 61 6d 65 20 69 73 20 74 68  table name is th
a230: 65 20 77 65 69 67 68 74 20 61 73 73 69 67 6e 65  e weight assigne
a240: 64 20 74 6f 20 74 68 65 20 6c 65 66 74 6d 6f 73  d to the leftmos
a250: 74 20 63 6f 6c 75 6d 6e 20 6f 66 0a 74 68 65 20  t column of.the 
a260: 46 54 53 35 20 74 61 62 6c 65 2e 20 54 68 65 20  FTS5 table. The 
a270: 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 77 65  second is the we
a280: 69 67 68 74 20 61 73 73 69 67 6e 65 64 20 74 6f  ight assigned to
a290: 20 74 68 65 20 73 65 63 6f 6e 64 20 6c 65 66 74   the second left
a2a0: 6d 6f 73 74 0a 63 6f 6c 75 6d 6e 2c 20 61 6e 64  most.column, and
a2b0: 20 73 6f 20 6f 6e 2e 20 49 66 20 74 68 65 72 65   so on. If there
a2c0: 20 61 72 65 20 6e 6f 74 20 65 6e 6f 75 67 68 20   are not enough 
a2d0: 61 72 67 75 6d 65 6e 74 73 20 66 6f 72 20 61 6c  arguments for al
a2e0: 6c 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 73 2c  l table columns,
a2f0: 0a 72 65 6d 61 69 6e 69 6e 67 20 63 6f 6c 75 6d  .remaining colum
a300: 6e 73 20 61 72 65 20 61 73 73 69 67 6e 65 64 20  ns are assigned 
a310: 61 20 77 65 69 67 68 74 20 6f 66 20 31 2e 30 2e  a weight of 1.0.
a320: 20 49 66 20 74 68 65 72 65 20 61 72 65 20 74 6f   If there are to
a330: 6f 20 6d 61 6e 79 20 0a 74 72 61 69 6c 69 6e 67  o many .trailing
a340: 20 61 72 67 75 6d 65 6e 74 73 2c 20 74 68 65 20   arguments, the 
a350: 65 78 74 72 61 73 20 61 72 65 20 69 67 6e 6f 72  extras are ignor
a360: 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  ed. For example:
a370: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
a380: 3c 69 3e 2d 2d 20 41 73 73 75 6d 69 6e 67 20 74  <i>-- Assuming t
a390: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 63 68  he following sch
a3a0: 65 6d 61 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ema:</i>.  CREAT
a3b0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
a3c0: 65 6d 61 69 6c 20 55 53 49 4e 47 20 66 74 73 35  email USING fts5
a3d0: 28 73 65 6e 64 65 72 2c 20 74 69 74 6c 65 2c 20  (sender, title, 
a3e0: 62 6f 64 79 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  body);..  <i>-- 
a3f0: 52 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 69  Return results i
a400: 6e 20 62 6d 32 35 20 6f 72 64 65 72 2c 20 77 69  n bm25 order, wi
a410: 74 68 20 65 61 63 68 20 70 68 72 61 73 65 20 68  th each phrase h
a420: 69 74 20 69 6e 20 74 68 65 20 22 73 65 6e 64 65  it in the "sende
a430: 72 22 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63  r"</i>.  <i>-- c
a440: 6f 6c 75 6d 6e 20 63 6f 6e 73 69 64 65 72 65 64  olumn considered
a450: 20 74 68 65 20 65 71 75 61 6c 20 6f 66 20 31 30   the equal of 10
a460: 20 68 69 74 73 20 69 6e 20 74 68 65 20 22 62 6f   hits in the "bo
a470: 64 79 22 20 63 6f 6c 75 6d 6e 2c 20 61 6e 64 3c  dy" column, and<
a480: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 65 61 63 68  /i>.  <i>-- each
a490: 20 68 69 74 20 69 6e 20 74 68 65 20 22 74 69 74   hit in the "tit
a4a0: 6c 65 22 20 63 6f 6c 75 6d 6e 20 63 6f 6e 73 69  le" column consi
a4b0: 64 65 72 65 64 20 61 73 20 76 61 6c 75 61 62 6c  dered as valuabl
a4c0: 65 20 61 73 20 35 20 68 69 74 73 20 69 6e 3c 2f  e as 5 hits in</
a4d0: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20 22  i>.  <i>-- the "
a4e0: 62 6f 64 79 22 20 63 6f 6c 75 6d 6e 2e 3c 2f 69  body" column.</i
a4f0: 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  >.  SELECT * FRO
a500: 4d 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65 6d  M email WHERE em
a510: 61 69 6c 20 4d 41 54 43 48 20 3f 20 4f 52 44 45  ail MATCH ? ORDE
a520: 52 20 42 59 20 62 6d 32 35 28 65 6d 61 69 6c 2c  R BY bm25(email,
a530: 20 31 30 2e 30 2c 20 35 2e 30 29 3b 0a 3c 2f 63   10.0, 5.0);.</c
a540: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 52 65  odeblock>..<p>Re
a550: 66 65 72 20 74 6f 20 77 69 6b 69 70 65 64 69 61  fer to wikipedia
a560: 20 66 6f 72 20 0a 3c 61 20 68 72 65 66 3d 22 68   for .<a href="h
a570: 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
a580: 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4f 6b 61 70  ia.org/wiki/Okap
a590: 69 5f 42 4d 32 35 22 3e 6d 6f 72 65 20 69 6e 66  i_BM25">more inf
a5a0: 6f 72 6d 61 74 69 6f 6e 20 72 65 67 61 72 64 69  ormation regardi
a5b0: 6e 67 0a 42 4d 32 35 3c 2f 61 3e 20 61 6e 64 20  ng.BM25</a> and 
a5c0: 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 0a 3c  its variants...<
a5d0: 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 68 69  h3 tags="FTS5 hi
a5e0: 67 68 6c 69 67 68 74 22 3e 54 68 65 20 68 69 67  ghlight">The hig
a5f0: 68 6c 69 67 68 74 28 29 20 66 75 6e 63 74 69 6f  hlight() functio
a600: 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20  n</h3>..<p> The 
a610: 68 69 67 68 6c 69 67 68 74 28 29 20 66 75 6e 63  highlight() func
a620: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63  tion returns a c
a630: 6f 70 79 20 6f 66 20 74 68 65 20 74 65 78 74 20  opy of the text 
a640: 66 72 6f 6d 20 61 20 73 70 65 63 69 66 69 65 64  from a specified
a650: 20 0a 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20   .column of the 
a660: 63 75 72 72 65 6e 74 20 72 6f 77 20 77 69 74 68  current row with
a670: 20 65 78 74 72 61 20 6d 61 72 6b 75 70 20 74 65   extra markup te
a680: 78 74 20 69 6e 73 65 72 74 65 64 20 74 6f 20 6d  xt inserted to m
a690: 61 72 6b 20 74 68 65 20 73 74 61 72 74 20 0a 61  ark the start .a
a6a0: 6e 64 20 65 6e 64 20 6f 66 20 70 68 72 61 73 65  nd end of phrase
a6b0: 20 6d 61 74 63 68 65 73 2e 20 0a 0a 3c 70 3e 54   matches. ..<p>T
a6c0: 68 65 20 68 69 67 68 6c 69 67 68 74 28 29 20 6d  he highlight() m
a6d0: 75 73 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ust be invoked w
a6e0: 69 74 68 20 65 78 61 63 74 6c 79 20 74 68 72 65  ith exactly thre
a6f0: 65 20 61 72 67 75 6d 65 6e 74 73 20 66 6f 6c 6c  e arguments foll
a700: 6f 77 69 6e 67 20 0a 74 68 65 20 74 61 62 6c 65  owing .the table
a710: 20 6e 61 6d 65 2e 20 54 6f 20 62 65 20 69 6e 74   name. To be int
a720: 65 72 70 72 65 74 65 64 20 61 73 20 66 6f 6c 6c  erpreted as foll
a730: 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69  ows:..<ol>.  <li
a740: 3e 20 41 6e 20 69 6e 74 65 67 65 72 20 69 6e 64  > An integer ind
a750: 69 63 61 74 69 6e 67 20 74 68 65 20 69 6e 64 65  icating the inde
a760: 78 20 6f 66 20 74 68 65 20 46 54 53 20 74 61 62  x of the FTS tab
a770: 6c 65 20 63 6f 6c 75 6d 6e 20 74 6f 20 72 65 61  le column to rea
a780: 64 20 74 68 65 20 0a 20 20 20 20 20 20 20 74 65  d the .       te
a790: 78 74 20 66 72 6f 6d 2e 20 43 6f 6c 75 6d 6e 73  xt from. Columns
a7a0: 20 61 72 65 20 6e 75 6d 62 65 72 65 64 20 66 72   are numbered fr
a7b0: 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74  om left to right
a7c0: 20 73 74 61 72 74 69 6e 67 20 61 74 20 7a 65 72   starting at zer
a7d0: 6f 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74  o...  <li> The t
a7e0: 65 78 74 20 74 6f 20 69 6e 73 65 72 74 20 62 65  ext to insert be
a7f0: 66 6f 72 65 20 65 61 63 68 20 70 68 72 61 73 65  fore each phrase
a800: 20 6d 61 74 63 68 2e 0a 0a 20 20 3c 6c 69 3e 20   match...  <li> 
a810: 54 68 65 20 74 65 78 74 20 74 6f 20 69 6e 73 65  The text to inse
a820: 72 74 20 61 66 74 65 72 20 65 61 63 68 20 70 68  rt after each ph
a830: 72 61 73 65 20 6d 61 74 63 68 2e 0a 3c 2f 6f 6c  rase match..</ol
a840: 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c  >..<p>For exampl
a850: 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
a860: 20 20 3c 69 3e 2d 2d 20 52 65 74 75 72 6e 20 61    <i>-- Return a
a870: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 65 78   copy of the tex
a880: 74 20 66 72 6f 6d 20 74 68 65 20 6c 65 66 74 6d  t from the leftm
a890: 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
a8a0: 65 20 63 75 72 72 65 6e 74 3c 2f 69 3e 0a 20 20  e current</i>.  
a8b0: 3c 69 3e 2d 2d 20 72 6f 77 2c 20 77 69 74 68 20  <i>-- row, with 
a8c0: 70 68 72 61 73 65 20 6d 61 74 63 68 65 73 20 6d  phrase matches m
a8d0: 61 72 6b 65 64 20 75 73 69 6e 67 20 68 74 6d 6c  arked using html
a8e0: 20 22 62 22 20 74 61 67 73 2e 3c 2f 69 3e 0a 20   "b" tags.</i>. 
a8f0: 20 53 45 4c 45 43 54 20 68 69 67 68 6c 69 67 68   SELECT highligh
a900: 74 28 66 74 73 2c 20 30 2c 20 27 26 6c 74 3b 62  t(fts, 0, '&lt;b
a910: 26 67 74 3b 27 2c 20 27 26 6c 74 3b 2f 62 26 67  &gt;', '&lt;/b&g
a920: 74 3b 27 29 20 46 52 4f 4d 20 66 74 73 20 57 48  t;') FROM fts WH
a930: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 0a  ERE fts MATCH ?.
a940: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
a950: 3e 49 6e 20 63 61 73 65 73 20 77 68 65 72 65 20  >In cases where 
a960: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 70 68 72 61  two or more phra
a970: 73 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 76 65  se instances ove
a980: 72 6c 61 70 20 28 73 68 61 72 65 20 6f 6e 65 20  rlap (share one 
a990: 6f 72 20 6d 6f 72 65 0a 74 6f 6b 65 6e 73 20 69  or more.tokens i
a9a0: 6e 20 63 6f 6d 6d 6f 6e 29 2c 20 61 20 73 69 6e  n common), a sin
a9b0: 67 6c 65 20 6f 70 65 6e 20 61 6e 64 20 63 6c 6f  gle open and clo
a9c0: 73 65 20 6d 61 72 6b 65 72 20 69 73 20 69 6e 73  se marker is ins
a9d0: 65 72 74 65 64 20 66 6f 72 20 65 61 63 68 20 73  erted for each s
a9e0: 65 74 0a 6f 66 20 6f 76 65 72 6c 61 70 70 69 6e  et.of overlappin
a9f0: 67 20 70 68 72 61 73 65 73 2e 20 46 6f 72 20 65  g phrases. For e
aa00: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
aa10: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 41 73 73  ock>.  <i>-- Ass
aa20: 75 6d 69 6e 67 20 74 68 69 73 3a 3c 2f 69 3e 0a  uming this:</i>.
aa30: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
aa40: 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20   TABLE ft USING 
aa50: 66 74 73 35 28 61 29 3b 0a 20 20 49 4e 53 45 52  fts5(a);.  INSER
aa60: 54 20 49 4e 54 4f 20 66 74 20 56 41 4c 55 45 53  T INTO ft VALUES
aa70: 28 27 61 20 62 20 63 20 78 20 63 20 64 20 65 27  ('a b c x c d e'
aa80: 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
aa90: 20 66 74 20 56 41 4c 55 45 53 28 27 61 20 62 20   ft VALUES('a b 
aaa0: 63 20 63 20 64 20 65 27 29 3b 0a 20 20 49 4e 53  c c d e');.  INS
aab0: 45 52 54 20 49 4e 54 4f 20 66 74 20 56 41 4c 55  ERT INTO ft VALU
aac0: 45 53 28 27 61 20 62 20 63 20 64 20 65 27 29 3b  ES('a b c d e');
aad0: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f  ..  <i>-- The fo
aae0: 6c 6c 6f 77 69 6e 67 20 53 45 4c 45 43 54 20 73  llowing SELECT s
aaf0: 74 61 74 65 6d 65 6e 74 20 72 65 74 75 72 6e 73  tatement returns
ab00: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 77   these three row
ab10: 73 3a 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20  s:</i>.  <i>--  
ab20: 20 27 26 23 39 31 3b 61 20 62 20 63 26 23 39 33   '&#91;a b c&#93
ab30: 3b 20 78 20 26 23 39 31 3b 63 20 64 20 65 26 23  ; x &#91;c d e&#
ab40: 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  93;'</i>.  <i>--
ab50: 20 20 20 27 26 23 39 31 3b 61 20 62 20 63 26 23     '&#91;a b c&#
ab60: 39 33 3b 20 26 23 39 31 3b 63 20 64 20 65 26 23  93; &#91;c d e&#
ab70: 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  93;'</i>.  <i>--
ab80: 20 20 20 27 26 23 39 31 3b 61 20 62 20 63 20 64     '&#91;a b c d
ab90: 20 65 26 23 39 33 3b 27 3c 2f 69 3e 0a 20 20 53   e&#93;'</i>.  S
aba0: 45 4c 45 43 54 20 68 69 67 68 6c 69 67 68 74 28  ELECT highlight(
abb0: 66 74 2c 20 30 2c 20 27 26 23 39 31 3b 27 2c 20  ft, 0, '&#91;', 
abc0: 27 26 23 39 33 3b 27 29 20 46 52 4f 4d 20 66 74  '&#93;') FROM ft
abd0: 20 57 48 45 52 45 20 66 74 20 4d 41 54 43 48 20   WHERE ft MATCH 
abe0: 27 61 2b 62 2b 63 20 41 4e 44 20 63 2b 64 2b 65  'a+b+c AND c+d+e
abf0: 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ';.</codeblock>.
ac00: 0a 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20  .<h3 tags="FTS5 
ac10: 73 6e 69 70 70 65 74 22 3e 54 68 65 20 73 6e 69  snippet">The sni
ac20: 70 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 3c  ppet() function<
ac30: 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 73 6e 69  /h3>..<p>The sni
ac40: 70 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  ppet() function 
ac50: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 68 69  is similar to hi
ac60: 67 68 6c 69 67 68 74 28 29 2c 20 65 78 63 65 70  ghlight(), excep
ac70: 74 20 74 68 61 74 20 69 6e 73 74 65 61 64 20 6f  t that instead o
ac80: 66 0a 72 65 74 75 72 6e 69 6e 67 20 65 6e 74 69  f.returning enti
ac90: 72 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  re column values
aca0: 2c 20 69 74 20 61 75 74 6f 6d 61 74 69 63 61 6c  , it automatical
acb0: 6c 79 20 73 65 6c 65 63 74 73 20 61 6e 64 20 65  ly selects and e
acc0: 78 74 72 61 63 74 73 20 61 0a 73 68 6f 72 74 20  xtracts a.short 
acd0: 66 72 61 67 6d 65 6e 74 20 6f 66 20 64 6f 63 75  fragment of docu
ace0: 6d 65 6e 74 20 74 65 78 74 20 74 6f 20 70 72 6f  ment text to pro
acf0: 63 65 73 73 20 61 6e 64 20 72 65 74 75 72 6e 2e  cess and return.
ad00: 20 54 68 65 20 73 6e 69 70 70 65 74 28 29 20 66   The snippet() f
ad10: 75 6e 63 74 69 6f 6e 0a 6d 75 73 74 20 62 65 20  unction.must be 
ad20: 70 61 73 73 65 64 20 66 69 76 65 20 70 61 72 61  passed five para
ad30: 6d 65 74 65 72 73 20 66 6f 6c 6c 6f 77 69 6e 67  meters following
ad40: 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 20   the table name 
ad50: 61 72 67 75 6d 65 6e 74 3a 0a 0a 3c 6f 6c 3e 0a  argument:..<ol>.
ad60: 20 20 3c 6c 69 3e 20 41 6e 20 69 6e 74 65 67 65    <li> An intege
ad70: 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  r indicating the
ad80: 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 46 54   index of the FT
ad90: 53 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  S table column t
ada0: 6f 20 73 65 6c 65 63 74 0a 20 20 20 20 20 20 20  o select.       
adb0: 74 68 65 20 72 65 74 75 72 6e 65 64 20 74 65 78  the returned tex
adc0: 74 20 66 72 6f 6d 2e 20 43 6f 6c 75 6d 6e 73 20  t from. Columns 
add0: 61 72 65 20 6e 75 6d 62 65 72 65 64 20 66 72 6f  are numbered fro
ade0: 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74 20  m left to right 
adf0: 0a 20 20 20 20 20 20 20 73 74 61 72 74 69 6e 67  .       starting
ae00: 20 61 74 20 7a 65 72 6f 2e 20 41 20 6e 65 67 61   at zero. A nega
ae10: 74 69 76 65 20 76 61 6c 75 65 20 69 6e 64 69 63  tive value indic
ae20: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 63 6f  ates that the co
ae30: 6c 75 6d 6e 20 73 68 6f 75 6c 64 0a 20 20 20 20  lumn should.    
ae40: 20 20 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61     be automatica
ae50: 6c 6c 79 20 73 65 6c 65 63 74 65 64 2e 0a 0a 20  lly selected... 
ae60: 20 3c 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74   <li> The text t
ae70: 6f 20 69 6e 73 65 72 74 20 62 65 66 6f 72 65 20  o insert before 
ae80: 65 61 63 68 20 70 68 72 61 73 65 20 6d 61 74 63  each phrase matc
ae90: 68 20 77 69 74 68 69 6e 20 74 68 65 20 72 65 74  h within the ret
aea0: 75 72 6e 65 64 20 74 65 78 74 2e 0a 0a 20 20 3c  urned text...  <
aeb0: 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74 6f 20  li> The text to 
aec0: 69 6e 73 65 72 74 20 61 66 74 65 72 20 65 61 63  insert after eac
aed0: 68 20 70 68 72 61 73 65 20 6d 61 74 63 68 20 77  h phrase match w
aee0: 69 74 68 69 6e 20 74 68 65 20 72 65 74 75 72 6e  ithin the return
aef0: 65 64 20 74 65 78 74 2e 0a 0a 20 20 3c 6c 69 3e  ed text...  <li>
af00: 20 54 68 65 20 74 65 78 74 20 74 6f 20 61 64 64   The text to add
af10: 20 74 6f 20 74 68 65 20 73 74 61 72 74 20 6f 72   to the start or
af20: 20 65 6e 64 20 6f 66 20 74 68 65 20 73 65 6c 65   end of the sele
af30: 63 74 65 64 20 74 65 78 74 20 74 6f 20 69 6e 64  cted text to ind
af40: 69 63 61 74 65 0a 20 20 20 20 20 20 20 74 68 61  icate.       tha
af50: 74 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 74  t the returned t
af60: 65 78 74 20 64 6f 65 73 20 6e 6f 74 20 6f 63 63  ext does not occ
af70: 75 72 20 61 74 20 74 68 65 20 73 74 61 72 74 20  ur at the start 
af80: 6f 72 20 65 6e 64 20 6f 66 20 69 74 73 20 63 6f  or end of its co
af90: 6c 75 6d 6e 2c 0a 20 20 20 20 20 20 20 72 65 73  lumn,.       res
afa0: 70 65 63 74 69 76 65 6c 79 2e 0a 0a 20 20 3c 6c  pectively...  <l
afb0: 69 3e 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  i> The maximum n
afc0: 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20  umber of tokens 
afd0: 69 6e 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  in the returned 
afe0: 74 65 78 74 2e 20 54 68 69 73 20 6d 75 73 74 20  text. This must 
aff0: 62 65 20 67 72 65 61 74 65 72 0a 20 20 20 20 20  be greater.     
b000: 20 20 74 68 61 6e 20 7a 65 72 6f 20 61 6e 64 20    than zero and 
b010: 65 71 75 61 6c 20 74 6f 20 6f 72 20 6c 65 73 73  equal to or less
b020: 20 74 68 61 6e 20 36 34 2e 20 0a 3c 2f 6f 6c 3e   than 64. .</ol>
b030: 0a 0a 3c 68 32 20 74 61 67 73 3d 22 61 75 78 69  ..<h2 tags="auxi
b040: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d  liary function m
b050: 61 70 70 69 6e 67 22 3e 53 6f 72 74 69 6e 67 20  apping">Sorting 
b060: 62 79 20 41 75 78 69 6c 69 61 72 79 20 46 75 6e  by Auxiliary Fun
b070: 63 74 69 6f 6e 20 52 65 73 75 6c 74 73 3c 2f 68  ction Results</h
b080: 32 3e 0a 0a 3c 70 3e 20 41 6c 6c 20 46 54 53 35  2>..<p> All FTS5
b090: 20 74 61 62 6c 65 73 20 66 65 61 74 75 72 65 20   tables feature 
b0a0: 61 20 73 70 65 63 69 61 6c 20 68 69 64 64 65 6e  a special hidden
b0b0: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 22 72   column named "r
b0c0: 61 6e 6b 22 2e 20 49 66 20 74 68 65 0a 63 75 72  ank". If the.cur
b0d0: 72 65 6e 74 20 71 75 65 72 79 20 69 73 20 6e 6f  rent query is no
b0e0: 74 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 71 75  t a full-text qu
b0f0: 65 72 79 20 28 69 2e 65 2e 20 69 66 20 69 74 20  ery (i.e. if it 
b100: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
b110: 20 61 20 4d 41 54 43 48 0a 6f 70 65 72 61 74 6f   a MATCH.operato
b120: 72 29 2c 20 74 68 65 20 76 61 6c 75 65 20 6f 66  r), the value of
b130: 20 74 68 65 20 22 72 61 6e 6b 22 20 63 6f 6c 75   the "rank" colu
b140: 6d 6e 20 69 73 20 61 6c 77 61 79 73 20 4e 55 4c  mn is always NUL
b150: 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e  L. Otherwise, in
b160: 20 61 0a 66 75 6c 6c 2d 74 65 78 74 20 71 75 65   a.full-text que
b170: 72 79 2c 20 63 6f 6c 75 6d 6e 20 72 61 6e 6b 20  ry, column rank 
b180: 63 6f 6e 74 61 69 6e 73 20 62 79 20 64 65 66 61  contains by defa
b190: 75 6c 74 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ult the same val
b1a0: 75 65 20 61 73 20 77 6f 75 6c 64 20 62 65 0a 72  ue as would be.r
b1b0: 65 74 75 72 6e 65 64 20 62 79 20 65 78 65 63 75  eturned by execu
b1c0: 74 69 6e 67 20 74 68 65 20 62 6d 32 35 28 29 20  ting the bm25() 
b1d0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
b1e0: 6f 6e 20 77 69 74 68 20 6e 6f 20 74 72 61 69 6c  on with no trail
b1f0: 69 6e 67 20 0a 61 72 67 75 6d 65 6e 74 73 2e 0a  ing .arguments..
b200: 0a 3c 70 3e 20 54 68 65 20 64 69 66 66 65 72 65  .<p> The differe
b210: 6e 63 65 20 62 65 74 77 65 65 6e 20 72 65 61 64  nce between read
b220: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 72 61 6e  ing from the ran
b230: 6b 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 75 73 69  k column and usi
b240: 6e 67 20 74 68 65 20 62 6d 32 35 28 29 0a 66 75  ng the bm25().fu
b250: 6e 63 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 20  nction directly 
b260: 77 69 74 68 69 6e 20 74 68 65 20 71 75 65 72 79  within the query
b270: 20 69 73 20 6f 6e 6c 79 20 73 69 67 6e 69 66 69   is only signifi
b280: 63 61 6e 74 20 77 68 65 6e 20 73 6f 72 74 69 6e  cant when sortin
b290: 67 20 62 79 20 74 68 65 0a 72 65 74 75 72 6e 65  g by the.returne
b2a0: 64 20 76 61 6c 75 65 2e 20 49 6e 20 74 68 69 73  d value. In this
b2b0: 20 63 61 73 65 2c 20 75 73 69 6e 67 20 22 72 61   case, using "ra
b2c0: 6e 6b 22 20 69 73 20 66 61 73 74 65 72 20 74 68  nk" is faster th
b2d0: 61 6e 20 75 73 69 6e 67 20 62 6d 32 35 28 29 2e  an using bm25().
b2e0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
b2f0: 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77  <i>-- The follow
b300: 69 6e 67 20 71 75 65 72 69 65 73 20 61 72 65 20  ing queries are 
b310: 6c 6f 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61  logically equiva
b320: 6c 65 6e 74 2e 20 42 75 74 20 74 68 65 20 73 65  lent. But the se
b330: 63 6f 6e 64 20 6d 61 79 3c 2f 69 3e 0a 20 20 3c  cond may</i>.  <
b340: 69 3e 2d 2d 20 62 65 20 66 61 73 74 65 72 2c 20  i>-- be faster, 
b350: 70 61 72 74 69 63 75 6c 61 72 6c 79 20 69 66 20  particularly if 
b360: 74 68 65 20 63 61 6c 6c 65 72 20 61 62 61 6e 64  the caller aband
b370: 6f 6e 73 20 74 68 65 20 71 75 65 72 79 20 62 65  ons the query be
b380: 66 6f 72 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  fore</i>.  <i>--
b390: 20 61 6c 6c 20 72 6f 77 73 20 68 61 76 65 20 62   all rows have b
b3a0: 65 65 6e 20 72 65 74 75 72 6e 65 64 20 28 6f 72  een returned (or
b3b0: 20 69 66 20 74 68 65 20 71 75 65 72 69 65 73 20   if the queries 
b3c0: 77 65 72 65 20 6d 6f 64 69 66 69 65 64 20 74 6f  were modified to
b3d0: 20 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e   </i>.  <i>-- in
b3e0: 63 6c 75 64 65 20 4c 49 4d 49 54 20 63 6c 61 75  clude LIMIT clau
b3f0: 73 65 73 29 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45  ses).</i>.  SELE
b400: 43 54 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48  CT * FROM fts WH
b410: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20  ERE fts MATCH ? 
b420: 4f 52 44 45 52 20 42 59 20 62 6d 32 35 28 66 74  ORDER BY bm25(ft
b430: 73 29 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  s);.  SELECT * F
b440: 52 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74  ROM fts WHERE ft
b450: 73 20 4d 41 54 43 48 20 3f 20 4f 52 44 45 52 20  s MATCH ? ORDER 
b460: 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62  BY rank;.</codeb
b470: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 73 74 65  lock>..<p> Inste
b480: 61 64 20 6f 66 20 75 73 69 6e 67 20 62 6d 32 35  ad of using bm25
b490: 28 29 20 77 69 74 68 20 6e 6f 20 74 72 61 69 6c  () with no trail
b4a0: 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 2c 20 74  ing arguments, t
b4b0: 68 65 20 73 70 65 63 69 66 69 63 20 61 75 78 69  he specific auxi
b4c0: 6c 69 61 72 79 0a 66 75 6e 63 74 69 6f 6e 20 6d  liary.function m
b4d0: 61 70 70 65 64 20 74 6f 20 74 68 65 20 72 61 6e  apped to the ran
b4e0: 6b 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 62 65 20  k column may be 
b4f0: 63 6f 6e 66 69 67 75 72 65 64 20 65 69 74 68 65  configured eithe
b500: 72 20 6f 6e 20 61 20 70 65 72 2d 71 75 65 72 79  r on a per-query
b510: 0a 62 61 73 69 73 2c 20 6f 72 20 62 79 20 73 65  .basis, or by se
b520: 74 74 69 6e 67 20 61 20 64 69 66 66 65 72 65 6e  tting a differen
b530: 74 20 70 65 72 73 69 73 74 65 6e 74 20 64 65 66  t persistent def
b540: 61 75 6c 74 20 66 6f 72 20 74 68 65 20 46 54 53  ault for the FTS
b550: 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 49 6e 20   table...<p> In 
b560: 6f 72 64 65 72 20 74 6f 20 63 68 61 6e 67 65 20  order to change 
b570: 74 68 65 20 6d 61 70 70 69 6e 67 20 6f 66 20 74  the mapping of t
b580: 68 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 66  he rank column f
b590: 6f 72 20 61 20 73 69 6e 67 6c 65 20 71 75 65 72  or a single quer
b5a0: 79 2c 20 0a 61 20 74 65 72 6d 20 73 69 6d 69 6c  y, .a term simil
b5b0: 61 72 20 74 6f 20 65 69 74 68 65 72 20 6f 66 20  ar to either of 
b5c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 73  the following is
b5d0: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 57 48   added to the WH
b5e0: 45 52 45 20 63 6c 61 75 73 65 20 6f 66 20 61 20  ERE clause of a 
b5f0: 0a 71 75 65 72 79 3a 0a 0a 3c 63 6f 64 65 62 6c  .query:..<codebl
b600: 6f 63 6b 3e 0a 20 20 72 61 6e 6b 20 4d 41 54 43  ock>.  rank MATC
b610: 48 20 27 61 75 78 69 6c 69 61 72 79 2d 66 75 6e  H 'auxiliary-fun
b620: 63 74 69 6f 6e 2d 6e 61 6d 65 28 61 72 67 31 2c  ction-name(arg1,
b630: 20 61 72 67 32 2c 20 2e 2e 2e 29 27 0a 20 20 72   arg2, ...)'.  r
b640: 61 6e 6b 20 3d 20 27 61 75 78 69 6c 69 61 72 79  ank = 'auxiliary
b650: 2d 66 75 6e 63 74 69 6f 6e 2d 6e 61 6d 65 28 61  -function-name(a
b660: 72 67 31 2c 20 61 72 67 32 2c 20 2e 2e 2e 29 27  rg1, arg2, ...)'
b670: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
b680: 70 3e 20 54 68 65 20 72 69 67 68 74 2d 68 61 6e  p> The right-han
b690: 64 2d 73 69 64 65 20 6f 66 20 74 68 65 20 4d 41  d-side of the MA
b6a0: 54 43 48 20 6f 72 20 3d 20 6f 70 65 72 61 74 6f  TCH or = operato
b6b0: 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 6e 73  r must be a cons
b6c0: 74 61 6e 74 0a 65 78 70 72 65 73 73 69 6f 6e 20  tant.expression 
b6d0: 74 68 61 74 20 65 76 61 6c 75 61 74 65 73 20 74  that evaluates t
b6e0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 69  o a string consi
b6f0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 61 75 78  sting of the aux
b700: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20  iliary function 
b710: 74 6f 0a 69 6e 76 6f 6b 65 2c 20 66 6f 6c 6c 6f  to.invoke, follo
b720: 77 65 64 20 62 79 20 7a 65 72 6f 20 6f 72 20 6d  wed by zero or m
b730: 6f 72 65 20 63 6f 6d 6d 61 20 73 65 70 61 72 61  ore comma separa
b740: 74 65 64 20 61 72 67 75 6d 65 6e 74 73 20 77 69  ted arguments wi
b750: 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 69 73  thin parenthesis
b760: 2e 0a 41 72 67 75 6d 65 6e 74 73 20 6d 75 73 74  ..Arguments must
b770: 20 62 65 20 53 51 4c 20 6c 69 74 65 72 61 6c 73   be SQL literals
b780: 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  . For example:..
b790: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
b7a0: 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  >-- The followin
b7b0: 67 20 71 75 65 72 69 65 73 20 61 72 65 20 6c 6f  g queries are lo
b7c0: 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65  gically equivale
b7d0: 6e 74 2e 20 42 75 74 20 74 68 65 20 73 65 63 6f  nt. But the seco
b7e0: 6e 64 20 6d 61 79 3c 2f 69 3e 0a 20 20 3c 69 3e  nd may</i>.  <i>
b7f0: 2d 2d 20 62 65 20 66 61 73 74 65 72 2e 20 53 65  -- be faster. Se
b800: 65 20 61 62 6f 76 65 2e 20 3c 2f 69 3e 0a 20 20  e above. </i>.  
b810: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
b820: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
b830: 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62 6d 32  H ? ORDER BY bm2
b840: 35 28 66 74 73 2c 20 31 30 2e 30 2c 20 35 2e 30  5(fts, 10.0, 5.0
b850: 29 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  );.  SELECT * FR
b860: 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73  OM fts WHERE fts
b870: 20 4d 41 54 43 48 20 3f 20 41 4e 44 20 72 61 6e   MATCH ? AND ran
b880: 6b 20 4d 41 54 43 48 20 27 62 6d 32 35 28 31 30  k MATCH 'bm25(10
b890: 2e 30 2c 20 35 2e 30 29 27 20 4f 52 44 45 52 20  .0, 5.0)' ORDER 
b8a0: 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62  BY rank;.</codeb
b8b0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 74  lock>..<p> The t
b8c0: 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63  able-valued func
b8d0: 74 69 6f 6e 20 73 79 6e 74 61 78 20 6d 61 79 20  tion syntax may 
b8e0: 61 6c 73 6f 20 62 65 20 75 73 65 64 20 74 6f 20  also be used to 
b8f0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
b900: 6e 61 74 69 76 65 0a 72 61 6e 6b 69 6e 67 20 66  native.ranking f
b910: 75 6e 63 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  unction. In this
b920: 20 63 61 73 65 20 74 68 65 20 74 65 78 74 20 64   case the text d
b930: 65 73 63 72 69 62 69 6e 67 20 74 68 65 20 72 61  escribing the ra
b940: 6e 6b 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  nking function s
b950: 68 6f 75 6c 64 0a 62 65 20 73 70 65 63 69 66 69  hould.be specifi
b960: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
b970: 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75   table-valued fu
b980: 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
b990: 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
b9a0: 68 72 65 65 0a 71 75 65 72 69 65 73 20 61 72 65  hree.queries are
b9b0: 20 65 71 75 69 76 61 6c 65 6e 74 3a 0a 0a 3c 63   equivalent:..<c
b9c0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45  odeblock>.  SELE
b9d0: 43 54 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48  CT * FROM fts WH
b9e0: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20  ERE fts MATCH ? 
b9f0: 41 4e 44 20 72 61 6e 6b 20 4d 41 54 43 48 20 27  AND rank MATCH '
ba00: 62 6d 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27  bm25(10.0, 5.0)'
ba10: 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a   ORDER BY rank;.
ba20: 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20    SELECT * FROM 
ba30: 66 74 73 20 57 48 45 52 45 20 66 74 73 20 3d 20  fts WHERE fts = 
ba40: 3f 20 41 4e 44 20 72 61 6e 6b 20 3d 20 27 62 6d  ? AND rank = 'bm
ba50: 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27 20 4f  25(10.0, 5.0)' O
ba60: 52 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a 20 20  RDER BY rank;.  
ba70: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
ba80: 73 20 57 48 45 52 45 20 66 74 73 28 3f 2c 20 27  s WHERE fts(?, '
ba90: 62 6d 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27  bm25(10.0, 5.0)'
baa0: 29 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 3b  ) ORDER BY rank;
bab0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
bac0: 70 3e 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d  p> The default m
bad0: 61 70 70 69 6e 67 20 6f 66 20 74 68 65 20 72 61  apping of the ra
bae0: 6e 6b 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 61 20  nk column for a 
baf0: 74 61 62 6c 65 20 6d 61 79 20 62 65 20 6d 6f 64  table may be mod
bb00: 69 66 69 65 64 20 0a 75 73 69 6e 67 20 74 68 65  ified .using the
bb10: 20 5b 46 54 53 35 20 72 61 6e 6b 20 63 6f 6e 66   [FTS5 rank conf
bb20: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bb30: 5d 2e 0a 0a 3c 68 31 3e 53 70 65 63 69 61 6c 20  ]...<h1>Special 
bb40: 49 4e 53 45 52 54 20 43 6f 6d 6d 61 6e 64 73 3c  INSERT Commands<
bb50: 2f 68 31 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  /h1>..<h2 tags="
bb60: 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65 20 6f  FTS5 automerge o
bb70: 70 74 69 6f 6e 22 3e 54 68 65 20 27 61 75 74 6f  ption">The 'auto
bb80: 6d 65 72 67 65 27 20 43 6f 6e 66 69 67 75 72 61  merge' Configura
bb90: 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e  tion Option</h2>
bba0: 0a 0a 3c 70 3e 0a 20 20 49 6e 73 74 65 61 64 20  ..<p>.  Instead 
bbb0: 6f 66 20 75 73 69 6e 67 20 61 20 73 69 6e 67 6c  of using a singl
bbc0: 65 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  e data structure
bbd0: 20 6f 6e 20 64 69 73 6b 20 74 6f 20 73 74 6f 72   on disk to stor
bbe0: 65 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 0a  e the full-text.
bbf0: 20 20 69 6e 64 65 78 2c 20 46 54 53 35 20 75 73    index, FTS5 us
bc00: 65 73 20 61 20 73 65 72 69 65 73 20 6f 66 20 62  es a series of b
bc10: 2d 74 72 65 65 73 2e 20 45 61 63 68 20 74 69 6d  -trees. Each tim
bc20: 65 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63 74  e a new transact
bc30: 69 6f 6e 20 69 73 0a 20 20 63 6f 6d 6d 69 74 74  ion is.  committ
bc40: 65 64 2c 20 61 20 6e 65 77 20 62 2d 74 72 65 65  ed, a new b-tree
bc50: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
bc60: 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
bc70: 63 6f 6d 6d 69 74 74 65 64 20 74 72 61 6e 73 61  committed transa
bc80: 63 74 69 6f 6e 0a 20 20 69 73 20 77 72 69 74 74  ction.  is writt
bc90: 65 6e 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  en into the data
bca0: 62 61 73 65 20 66 69 6c 65 2e 20 57 68 65 6e 20  base file. When 
bcb0: 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  the full-text in
bcc0: 64 65 78 20 69 73 20 71 75 65 72 69 65 64 2c 20  dex is queried, 
bcd0: 65 61 63 68 0a 20 20 62 2d 74 72 65 65 20 6d 75  each.  b-tree mu
bce0: 73 74 20 62 65 20 71 75 65 72 69 65 64 20 69 6e  st be queried in
bcf0: 64 69 76 69 64 75 61 6c 6c 79 20 61 6e 64 20 74  dividually and t
bd00: 68 65 20 72 65 73 75 6c 74 73 20 6d 65 72 67 65  he results merge
bd10: 64 20 62 65 66 6f 72 65 20 62 65 69 6e 67 0a 20  d before being. 
bd20: 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
bd30: 20 75 73 65 72 2e 0a 0a 3c 70 3e 0a 20 20 49 6e   user...<p>.  In
bd40: 20 6f 72 64 65 72 20 74 6f 20 70 72 65 76 65 6e   order to preven
bd50: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
bd60: 62 2d 74 72 65 65 73 20 69 6e 20 74 68 65 20 64  b-trees in the d
bd70: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 62 65 63  atabase from bec
bd80: 6f 6d 69 6e 67 20 74 6f 6f 0a 20 20 6c 61 72 67  oming too.  larg
bd90: 65 20 28 73 6c 6f 77 69 6e 67 20 64 6f 77 6e 20  e (slowing down 
bda0: 71 75 65 72 69 65 73 29 2c 20 73 6d 61 6c 6c 65  queries), smalle
bdb0: 72 20 62 2d 74 72 65 65 73 20 61 72 65 20 70 65  r b-trees are pe
bdc0: 72 69 6f 64 69 63 61 6c 6c 79 20 6d 65 72 67 65  riodically merge
bdd0: 64 20 69 6e 74 6f 0a 20 20 73 69 6e 67 6c 65 20  d into.  single 
bde0: 6c 61 72 67 65 72 20 62 2d 74 72 65 65 73 20 63  larger b-trees c
bdf0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 61  ontaining the sa
be00: 6d 65 20 64 61 74 61 2e 20 42 79 20 64 65 66 61  me data. By defa
be10: 75 6c 74 2c 20 74 68 69 73 20 68 61 70 70 65 6e  ult, this happen
be20: 73 0a 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  s.  automaticall
be30: 79 20 77 69 74 68 69 6e 20 49 4e 53 45 52 54 2c  y within INSERT,
be40: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
be50: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  E statements tha
be60: 74 20 6d 6f 64 69 66 79 20 74 68 65 0a 20 20 66  t modify the.  f
be70: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e 20  ull-text index. 
be80: 54 68 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20  The 'automerge' 
be90: 70 61 72 61 6d 65 74 65 72 20 64 65 74 65 72 6d  parameter determ
bea0: 69 6e 65 73 20 68 6f 77 20 6d 61 6e 79 20 73 6d  ines how many sm
beb0: 61 6c 6c 65 72 0a 20 20 62 2d 74 72 65 65 73 20  aller.  b-trees 
bec0: 61 72 65 20 6d 65 72 67 65 64 20 74 6f 67 65 74  are merged toget
bed0: 68 65 72 20 61 74 20 61 20 74 69 6d 65 2e 20 53  her at a time. S
bee0: 65 74 74 69 6e 67 20 69 74 20 74 6f 20 61 20 73  etting it to a s
bef0: 6d 61 6c 6c 20 76 61 6c 75 65 20 63 61 6e 0a 20  mall value can. 
bf00: 20 73 70 65 65 64 20 75 70 20 71 75 65 72 69 65   speed up querie
bf10: 73 20 28 61 73 20 74 68 65 79 20 68 61 76 65 20  s (as they have 
bf20: 74 6f 20 71 75 65 72 79 20 61 6e 64 20 6d 65 72  to query and mer
bf30: 67 65 20 74 68 65 20 72 65 73 75 6c 74 73 20 66  ge the results f
bf40: 72 6f 6d 20 66 65 77 65 72 20 0a 20 20 62 2d 74  rom fewer .  b-t
bf50: 72 65 65 73 29 2c 20 62 75 74 20 63 61 6e 20 61  rees), but can a
bf60: 6c 73 6f 20 73 6c 6f 77 20 64 6f 77 6e 20 77 72  lso slow down wr
bf70: 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  iting to the dat
bf80: 61 62 61 73 65 20 28 61 73 20 65 61 63 68 20 49  abase (as each I
bf90: 4e 53 45 52 54 2c 0a 20 20 55 50 44 41 54 45 20  NSERT,.  UPDATE 
bfa0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
bfb0: 65 6e 74 20 68 61 73 20 74 6f 20 64 6f 20 6d 6f  ent has to do mo
bfc0: 72 65 20 77 6f 72 6b 20 61 73 20 70 61 72 74 20  re work as part 
bfd0: 6f 66 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  of the automatic
bfe0: 0a 20 20 6d 65 72 67 69 6e 67 20 70 72 6f 63 65  .  merging proce
bff0: 73 73 29 2e 0a 0a 3c 70 3e 0a 20 20 45 61 63 68  ss)...<p>.  Each
c000: 20 6f 66 20 74 68 65 20 62 2d 74 72 65 65 73 20   of the b-trees 
c010: 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65  that make up the
c020: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
c030: 20 69 73 20 61 73 73 69 67 6e 65 64 20 74 6f 20   is assigned to 
c040: 61 20 22 6c 65 76 65 6c 22 0a 20 20 62 61 73 65  a "level".  base
c050: 64 20 6f 6e 20 69 74 73 20 73 69 7a 65 2e 20 4c  d on its size. L
c060: 65 76 65 6c 2d 30 20 62 2d 74 72 65 65 73 20 61  evel-0 b-trees a
c070: 72 65 20 74 68 65 20 73 6d 61 6c 6c 65 73 74 2c  re the smallest,
c080: 20 61 73 20 74 68 65 79 20 63 6f 6e 74 61 69 6e   as they contain
c090: 20 74 68 65 0a 20 20 63 6f 6e 74 65 6e 74 73 20   the.  contents 
c0a0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  of a single tran
c0b0: 73 61 63 74 69 6f 6e 2e 20 48 69 67 68 65 72 20  saction. Higher 
c0c0: 6c 65 76 65 6c 20 62 2d 74 72 65 65 73 20 61 72  level b-trees ar
c0d0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  e the result of.
c0e0: 20 20 6d 65 72 67 69 6e 67 20 74 77 6f 20 6f 72    merging two or
c0f0: 20 6d 6f 72 65 20 6c 65 76 65 6c 2d 30 20 62 2d   more level-0 b-
c100: 74 72 65 65 73 20 74 6f 67 65 74 68 65 72 20 61  trees together a
c110: 6e 64 20 73 6f 20 74 68 65 79 20 61 72 65 20 6c  nd so they are l
c120: 61 72 67 65 72 2e 20 46 54 53 35 0a 20 20 62 65  arger. FTS5.  be
c130: 67 69 6e 73 20 74 6f 20 6d 65 72 67 65 20 62 2d  gins to merge b-
c140: 74 72 65 65 73 20 74 6f 67 65 74 68 65 72 20 6f  trees together o
c150: 6e 63 65 20 74 68 65 72 65 20 65 78 69 73 74 20  nce there exist 
c160: 3c 69 3e 4d 3c 2f 69 3e 20 6f 72 20 6d 6f 72 65  <i>M</i> or more
c170: 20 62 2d 74 72 65 65 73 20 0a 20 20 77 69 74 68   b-trees .  with
c180: 20 74 68 65 20 73 61 6d 65 20 6c 65 76 65 6c 2c   the same level,
c190: 20 77 68 65 72 65 20 3c 69 3e 4d 3c 2f 69 3e 20   where <i>M</i> 
c1a0: 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
c1b0: 74 68 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20  the 'automerge' 
c1c0: 0a 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 0a 3c  .  parameter...<
c1d0: 70 3e 0a 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  p>.  The maximum
c1e0: 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 20 66   allowed value f
c1f0: 6f 72 20 74 68 65 20 27 61 75 74 6f 6d 65 72 67  or the 'automerg
c200: 65 27 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e' parameter is 
c210: 31 36 2e 20 54 68 65 20 64 65 66 61 75 6c 74 0a  16. The default.
c220: 20 20 76 61 6c 75 65 20 69 73 20 34 2e 20 53 65    value is 4. Se
c230: 74 74 69 6e 67 20 74 68 65 20 27 61 75 74 6f 6d  tting the 'autom
c240: 65 72 67 65 27 20 70 61 72 61 6d 65 74 65 72 20  erge' parameter 
c250: 74 6f 20 30 20 64 69 73 61 62 6c 65 73 20 74 68  to 0 disables th
c260: 65 20 61 75 74 6f 6d 61 74 69 63 20 0a 20 20 69  e automatic .  i
c270: 6e 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 69  ncremental mergi
c280: 6e 67 20 6f 66 20 62 2d 74 72 65 65 73 20 61 6c  ng of b-trees al
c290: 74 6f 67 65 74 68 65 72 2e 0a 0a 3c 63 6f 64 65  together...<code
c2a0: 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20  block>.  INSERT 
c2b0: 49 4e 54 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b  INTO ft(ft, rank
c2c0: 29 20 56 41 4c 55 45 53 28 27 61 75 74 6f 6d 65  ) VALUES('autome
c2d0: 72 67 65 27 2c 20 38 29 3b 0a 3c 2f 63 6f 64 65  rge', 8);.</code
c2e0: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 3e 54 68 65 20  block>..<h2>The 
c2f0: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 43 6f  'crisismerge' Co
c300: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
c310: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  on</h2>..<p>The 
c320: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 6f 70  'crisismerge' op
c330: 74 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72 20  tion is similar 
c340: 74 6f 20 27 61 75 74 6f 6d 65 72 67 65 27 2c 20  to 'automerge', 
c350: 69 6e 20 74 68 61 74 20 69 74 20 64 65 74 65 72  in that it deter
c360: 6d 69 6e 65 73 0a 68 6f 77 20 61 6e 64 20 68 6f  mines.how and ho
c370: 77 20 6f 66 74 65 6e 20 74 68 65 20 63 6f 6d 70  w often the comp
c380: 6f 6e 65 6e 74 20 62 2d 74 72 65 65 73 20 74 68  onent b-trees th
c390: 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65 20 66  at make up the f
c3a0: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 61  ull-text index a
c3b0: 72 65 0a 6d 65 72 67 65 64 20 74 6f 67 65 74 68  re.merged togeth
c3c0: 65 72 2e 20 4f 6e 63 65 20 74 68 65 72 65 20 65  er. Once there e
c3d0: 78 69 73 74 20 3c 69 3e 43 3c 2f 69 3e 20 6f 72  xist <i>C</i> or
c3e0: 20 6d 6f 72 65 20 62 2d 74 72 65 65 73 20 6f 6e   more b-trees on
c3f0: 20 61 20 73 69 6e 67 6c 65 20 6c 65 76 65 6c 0a   a single level.
c400: 77 69 74 68 69 6e 20 74 68 65 20 66 75 6c 6c 2d  within the full-
c410: 74 65 78 74 20 69 6e 64 65 78 2c 20 77 68 65 72  text index, wher
c420: 65 20 3c 69 3e 43 3c 2f 69 3e 20 69 73 20 74 68  e <i>C</i> is th
c430: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 27  e value of the '
c440: 63 72 69 73 69 73 6d 65 72 67 65 27 0a 6f 70 74  crisismerge'.opt
c450: 69 6f 6e 2c 20 61 6c 6c 20 62 2d 74 72 65 65 73  ion, all b-trees
c460: 20 6f 6e 20 74 68 65 20 6c 65 76 65 6c 20 61 72   on the level ar
c470: 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 6d 65  e immediately me
c480: 72 67 65 64 20 69 6e 74 6f 20 61 20 73 69 6e 67  rged into a sing
c490: 6c 65 20 62 2d 74 72 65 65 2e 0a 0a 3c 70 3e 54  le b-tree...<p>T
c4a0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  he difference be
c4b0: 74 77 65 65 6e 20 74 68 69 73 20 6f 70 74 69 6f  tween this optio
c4c0: 6e 20 61 6e 64 20 74 68 65 20 27 61 75 74 6f 6d  n and the 'autom
c4d0: 65 72 67 65 27 20 6f 70 74 69 6f 6e 20 69 73 20  erge' option is 
c4e0: 74 68 61 74 20 77 68 65 6e 0a 74 68 65 20 27 61  that when.the 'a
c4f0: 75 74 6f 6d 65 72 67 65 27 20 6c 69 6d 69 74 20  utomerge' limit 
c500: 69 73 20 72 65 61 63 68 65 64 20 46 54 53 35 20  is reached FTS5 
c510: 6f 6e 6c 79 20 62 65 67 69 6e 73 20 74 6f 20 6d  only begins to m
c520: 65 72 67 65 20 74 68 65 20 62 2d 74 72 65 65 73  erge the b-trees
c530: 0a 74 6f 67 65 74 68 65 72 2e 20 4d 6f 73 74 20  .together. Most 
c540: 6f 66 20 74 68 65 20 77 6f 72 6b 20 69 73 20 70  of the work is p
c550: 65 72 66 6f 72 6d 65 64 20 61 73 20 70 61 72 74  erformed as part
c560: 20 6f 66 20 73 75 62 73 65 71 75 65 6e 74 20 49   of subsequent I
c570: 4e 53 45 52 54 2c 20 0a 55 50 44 41 54 45 20 6f  NSERT, .UPDATE o
c580: 72 20 44 45 4c 45 54 45 20 6f 70 65 72 61 74 69  r DELETE operati
c590: 6f 6e 73 2e 20 57 68 65 72 65 61 73 20 77 68 65  ons. Whereas whe
c5a0: 6e 20 74 68 65 20 27 63 72 69 73 69 73 6d 65 72  n the 'crisismer
c5b0: 67 65 27 20 6c 69 6d 69 74 20 69 73 20 72 65 61  ge' limit is rea
c5c0: 63 68 65 64 2c 0a 74 68 65 20 6f 66 66 65 6e 64  ched,.the offend
c5d0: 69 6e 67 20 62 2d 74 72 65 65 73 20 61 72 65 20  ing b-trees are 
c5e0: 61 6c 6c 20 6d 65 72 67 65 64 20 69 6d 6d 65 64  all merged immed
c5f0: 69 61 74 65 6c 79 2e 20 54 68 69 73 20 6d 65 61  iately. This mea
c600: 6e 73 20 74 68 61 74 20 61 6e 20 49 4e 53 45 52  ns that an INSER
c610: 54 2c 0a 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T,.UPDATE or DEL
c620: 45 54 45 20 74 68 61 74 20 74 72 69 67 67 65 72  ETE that trigger
c630: 73 20 61 20 63 72 69 73 69 73 2d 6d 65 72 67 65  s a crisis-merge
c640: 20 6d 61 79 20 74 61 6b 65 20 61 20 6c 6f 6e 67   may take a long
c650: 20 74 69 6d 65 20 74 6f 20 0a 63 6f 6d 70 6c 65   time to .comple
c660: 74 65 2e 0a 0a 3c 70 3e 54 68 65 20 64 65 66 61  te...<p>The defa
c670: 75 6c 74 20 27 63 72 69 73 69 73 6d 65 72 67 65  ult 'crisismerge
c680: 27 20 76 61 6c 75 65 20 69 73 20 31 36 2e 20 54  ' value is 16. T
c690: 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 78 69 6d  here is no maxim
c6a0: 75 6d 20 6c 69 6d 69 74 2e 20 41 74 74 65 6d 70  um limit. Attemp
c6b0: 74 69 6e 67 0a 74 6f 20 73 65 74 20 74 68 65 20  ting.to set the 
c6c0: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 70 61  'crisismerge' pa
c6d0: 72 61 6d 65 74 65 72 20 74 6f 20 61 20 76 61 6c  rameter to a val
c6e0: 75 65 20 6f 66 20 30 20 6f 72 20 31 20 69 73 20  ue of 0 or 1 is 
c6f0: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 73 65  equivalent to.se
c700: 74 74 69 6e 67 20 69 74 20 74 6f 20 74 68 65 20  tting it to the 
c710: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 28 31  default value (1
c720: 36 29 2e 20 49 74 20 69 73 20 61 6e 20 65 72 72  6). It is an err
c730: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 20 74 6f  or to attempt to
c740: 20 73 65 74 20 74 68 65 0a 27 63 72 69 73 69 73   set the.'crisis
c750: 6d 65 72 67 65 27 20 6f 70 74 69 6f 6e 20 74 6f  merge' option to
c760: 20 61 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   a negative valu
c770: 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e...<codeblock>.
c780: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74    INSERT INTO ft
c790: 28 66 74 2c 20 72 61 6e 6b 29 20 56 41 4c 55 45  (ft, rank) VALUE
c7a0: 53 28 27 63 72 69 73 69 73 6d 65 72 67 65 27 2c  S('crisismerge',
c7b0: 20 31 36 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63   16);.</codebloc
c7c0: 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  k>..<h2 tags="FT
c7d0: 53 35 20 64 65 6c 65 74 65 20 63 6f 6d 6d 61 6e  S5 delete comman
c7e0: 64 22 3e 54 68 65 20 27 64 65 6c 65 74 65 27 20  d">The 'delete' 
c7f0: 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70  Command</h2>..<p
c800: 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69  > This command i
c810: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
c820: 20 77 69 74 68 20 5b 46 54 53 35 20 65 78 74 65   with [FTS5 exte
c830: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62  rnal content tab
c840: 6c 65 73 20 7c 0a 65 78 74 65 72 6e 61 6c 20 63  les |.external c
c850: 6f 6e 74 65 6e 74 5d 20 61 6e 64 20 5b 46 54 53  ontent] and [FTS
c860: 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61  5 contentless ta
c870: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 6c 65  bles | contentle
c880: 73 73 5d 20 74 61 62 6c 65 73 2e 20 49 74 0a 69  ss] tables. It.i
c890: 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65  s used to delete
c8a0: 20 74 68 65 20 69 6e 64 65 78 20 65 6e 74 72 69   the index entri
c8b0: 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  es associated wi
c8c0: 74 68 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  th a single row 
c8d0: 66 72 6f 6d 20 74 68 65 0a 66 75 6c 6c 2d 74 65  from the.full-te
c8e0: 78 74 20 69 6e 64 65 78 2e 20 54 68 69 73 20 63  xt index. This c
c8f0: 6f 6d 6d 61 6e 64 20 61 6e 64 20 74 68 65 20 5b  ommand and the [
c900: 46 54 53 35 20 64 65 6c 65 74 65 2d 61 6c 6c 20  FTS5 delete-all 
c910: 63 6f 6d 6d 61 6e 64 20 7c 20 64 65 6c 65 74 65  command | delete
c920: 2d 61 6c 6c 5d 0a 63 6f 6d 6d 61 6e 64 20 61 72  -all].command ar
c930: 65 20 74 68 65 20 6f 6e 6c 79 20 77 61 79 73 20  e the only ways 
c940: 74 6f 20 72 65 6d 6f 76 65 20 65 6e 74 72 69 65  to remove entrie
c950: 73 20 66 72 6f 6d 20 74 68 65 20 66 75 6c 6c 2d  s from the full-
c960: 74 65 78 74 20 69 6e 64 65 78 20 6f 66 20 61 0a  text index of a.
c970: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
c980: 65 2e 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65 72  e...<p> In order
c990: 20 74 6f 20 75 73 65 20 74 68 69 73 20 63 6f 6d   to use this com
c9a0: 6d 61 6e 64 20 74 6f 20 64 65 6c 65 74 65 20 61  mand to delete a
c9b0: 20 72 6f 77 2c 20 74 68 65 20 74 65 78 74 20 76   row, the text v
c9c0: 61 6c 75 65 20 27 64 65 6c 65 74 65 27 20 0a 6d  alue 'delete' .m
c9d0: 75 73 74 20 62 65 20 69 6e 73 65 72 74 65 64 20  ust be inserted 
c9e0: 69 6e 74 6f 20 74 68 65 20 73 70 65 63 69 61 6c  into the special
c9f0: 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20 74 68 65   column with the
ca00: 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 74 68   same name as th
ca10: 65 20 74 61 62 6c 65 2e 0a 54 68 65 20 72 6f 77  e table..The row
ca20: 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 74 6f  id of the row to
ca30: 20 64 65 6c 65 74 65 20 69 73 20 69 6e 73 65 72   delete is inser
ca40: 74 65 64 20 69 6e 74 6f 20 74 68 65 20 72 6f 77  ted into the row
ca50: 69 64 20 63 6f 6c 75 6d 6e 2e 20 54 68 65 0a 76  id column. The.v
ca60: 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69  alues inserted i
ca70: 6e 74 6f 20 74 68 65 20 6f 74 68 65 72 20 63 6f  nto the other co
ca80: 6c 75 6d 6e 73 20 6d 75 73 74 20 6d 61 74 63 68  lumns must match
ca90: 20 74 68 65 20 76 61 6c 75 65 73 20 63 75 72 72   the values curr
caa0: 65 6e 74 6c 79 0a 73 74 6f 72 65 64 20 69 6e 20  ently.stored in 
cab0: 74 68 65 20 74 61 62 6c 65 2e 20 46 6f 72 20 65  the table. For e
cac0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
cad0: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 49 6e 73  ock>.  <i>-- Ins
cae0: 65 72 74 20 61 20 72 6f 77 20 77 69 74 68 20 72  ert a row with r
caf0: 6f 77 69 64 3d 31 34 20 69 6e 74 6f 20 74 68 65  owid=14 into the
cb00: 20 66 74 73 35 20 74 61 62 6c 65 2e 3c 2f 69 3e   fts5 table.</i>
cb10: 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66  .  INSERT INTO f
cb20: 74 28 72 6f 77 69 64 2c 20 61 2c 20 62 2c 20 63  t(rowid, a, b, c
cb30: 29 20 56 41 4c 55 45 53 28 31 34 2c 20 24 61 2c  ) VALUES(14, $a,
cb40: 20 24 62 2c 20 24 63 29 3b 0a 20 20 0a 20 20 3c   $b, $c);.  .  <
cb50: 69 3e 2d 2d 20 52 65 6d 6f 76 65 20 74 68 65 20  i>-- Remove the 
cb60: 73 61 6d 65 20 72 6f 77 20 66 72 6f 6d 20 74 68  same row from th
cb70: 65 20 66 74 73 35 20 74 61 62 6c 65 2e 3c 2f 69  e fts5 table.</i
cb80: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
cb90: 66 74 28 66 74 2c 20 72 6f 77 69 64 2c 20 61 2c  ft(ft, rowid, a,
cba0: 20 62 2c 20 63 29 20 56 41 4c 55 45 53 28 27 64   b, c) VALUES('d
cbb0: 65 6c 65 74 65 27 2c 20 31 34 2c 20 24 61 2c 20  elete', 14, $a, 
cbc0: 24 62 2c 20 24 63 29 3b 0a 3c 2f 63 6f 64 65 62  $b, $c);.</codeb
cbd0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 66 20 74 68  lock>..<p> If th
cbe0: 65 20 76 61 6c 75 65 73 20 22 69 6e 73 65 72 74  e values "insert
cbf0: 65 64 22 20 69 6e 74 6f 20 74 68 65 20 74 65 78  ed" into the tex
cc00: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 70 61 72  t columns as par
cc10: 74 20 6f 66 20 61 20 27 64 65 6c 65 74 65 27 0a  t of a 'delete'.
cc20: 63 6f 6d 6d 61 6e 64 20 61 72 65 20 6e 6f 74 20  command are not 
cc30: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 6f 73  the same as thos
cc40: 65 20 63 75 72 72 65 6e 74 6c 79 20 73 74 6f 72  e currently stor
cc50: 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 74 61  ed within the ta
cc60: 62 6c 65 2c 20 74 68 65 0a 72 65 73 75 6c 74 73  ble, the.results
cc70: 20 6d 61 79 20 62 65 20 75 6e 70 72 65 64 69 63   may be unpredic
cc80: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 54 68 65 20  table...<p> The 
cc90: 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 69 73 20  reason for this 
cca0: 69 73 20 65 61 73 79 20 74 6f 20 75 6e 64 65 72  is easy to under
ccb0: 73 74 61 6e 64 3a 20 57 68 65 6e 20 61 20 64 6f  stand: When a do
ccc0: 63 75 6d 65 6e 74 20 69 73 20 69 6e 73 65 72 74  cument is insert
ccd0: 65 64 0a 69 6e 74 6f 20 74 68 65 20 46 54 53 35  ed.into the FTS5
cce0: 20 74 61 62 6c 65 2c 20 61 6e 20 65 6e 74 72 79   table, an entry
ccf0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
cd00: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
cd10: 20 74 6f 20 72 65 63 6f 72 64 20 74 68 65 0a 70   to record the.p
cd20: 6f 73 69 74 69 6f 6e 20 6f 66 20 65 61 63 68 20  osition of each 
cd30: 74 6f 6b 65 6e 20 77 69 74 68 69 6e 20 74 68 65  token within the
cd40: 20 6e 65 77 20 64 6f 63 75 6d 65 6e 74 2e 20 57   new document. W
cd50: 68 65 6e 20 61 20 64 6f 63 75 6d 65 6e 74 20 69  hen a document i
cd60: 73 20 72 65 6d 6f 76 65 64 2c 0a 74 68 65 20 6f  s removed,.the o
cd70: 72 69 67 69 6e 61 6c 20 64 61 74 61 20 69 73 20  riginal data is 
cd80: 72 65 71 75 69 72 65 64 20 69 6e 20 6f 72 64 65  required in orde
cd90: 72 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  r to determine t
cda0: 68 65 20 73 65 74 20 6f 66 20 65 6e 74 72 69 65  he set of entrie
cdb0: 73 20 74 68 61 74 0a 6e 65 65 64 20 74 6f 20 62  s that.need to b
cdc0: 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74  e removed from t
cdd0: 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he full-text ind
cde0: 65 78 2e 20 53 6f 20 69 66 20 74 68 65 20 64 61  ex. So if the da
cdf0: 74 61 20 73 75 70 70 6c 69 65 64 20 74 6f 20 46  ta supplied to F
ce00: 54 53 35 0a 77 68 65 6e 20 61 20 72 6f 77 20 69  TS5.when a row i
ce10: 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
ce20: 74 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20  this command is 
ce30: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
ce40: 68 61 74 20 75 73 65 64 20 74 6f 0a 64 65 74 65  hat used to.dete
ce50: 72 6d 69 6e 65 20 74 68 65 20 73 65 74 20 6f 66  rmine the set of
ce60: 20 74 6f 6b 65 6e 20 69 6e 73 74 61 6e 63 65 73   token instances
ce70: 20 77 68 65 6e 20 69 74 20 77 61 73 20 69 6e 73   when it was ins
ce80: 65 72 74 65 64 2c 20 73 6f 6d 65 20 66 75 6c 6c  erted, some full
ce90: 2d 74 65 78 74 20 0a 69 6e 64 65 78 20 65 6e 74  -text .index ent
cea0: 72 69 65 73 20 6d 61 79 20 6e 6f 74 20 62 65 20  ries may not be 
ceb0: 63 6f 72 72 65 63 74 6c 79 20 64 65 6c 65 74 65  correctly delete
cec0: 64 2c 20 6f 72 20 46 54 53 35 20 6d 61 79 20 74  d, or FTS5 may t
ced0: 72 79 20 74 6f 20 72 65 6d 6f 76 65 20 69 6e 64  ry to remove ind
cee0: 65 78 20 0a 65 6e 74 72 69 65 73 20 74 68 61 74  ex .entries that
cef0: 20 64 6f 20 6e 6f 74 20 65 78 69 73 74 2e 20 54   do not exist. T
cf00: 68 69 73 20 63 61 6e 20 6c 65 61 76 65 20 74 68  his can leave th
cf10: 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65  e full-text inde
cf20: 78 20 69 6e 20 61 6e 0a 75 6e 70 72 65 64 69 63  x in an.unpredic
cf30: 74 61 62 6c 65 20 73 74 61 74 65 2c 20 6d 61 6b  table state, mak
cf40: 69 6e 67 20 66 75 74 75 72 65 20 71 75 65 72 79  ing future query
cf50: 20 72 65 73 75 6c 74 73 20 75 6e 72 65 6c 69 61   results unrelia
cf60: 62 6c 65 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ble...<h2 tags="
cf70: 46 54 53 35 20 64 65 6c 65 74 65 2d 61 6c 6c 20  FTS5 delete-all 
cf80: 63 6f 6d 6d 61 6e 64 22 3e 54 68 65 20 27 64 65  command">The 'de
cf90: 6c 65 74 65 2d 61 6c 6c 27 20 43 6f 6d 6d 61 6e  lete-all' Comman
cfa0: 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73  d</h2>..<p> This
cfb0: 20 63 6f 6d 6d 61 6e 64 20 69 73 20 6f 6e 6c 79   command is only
cfc0: 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68 20   available with 
cfd0: 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c 20 63  [FTS5 external c
cfe0: 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20 7c 0a  ontent tables |.
cff0: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
d000: 5d 20 61 6e 64 20 5b 46 54 53 35 20 63 6f 6e 74  ] and [FTS5 cont
d010: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c  entless tables |
d020: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 5d 20 74 61   contentless] ta
d030: 62 6c 65 73 2e 20 49 74 0a 64 65 6c 65 74 65 73  bles. It.deletes
d040: 20 61 6c 6c 20 65 6e 74 72 69 65 73 20 66 72 6f   all entries fro
d050: 6d 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  m the full-text 
d060: 69 6e 64 65 78 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  index...<codeblo
d070: 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  ck>.  INSERT INT
d080: 4f 20 66 74 28 66 74 29 20 56 41 4c 55 45 53 28  O ft(ft) VALUES(
d090: 27 64 65 6c 65 74 65 2d 61 6c 6c 27 29 3b 0a 3c  'delete-all');.<
d0a0: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32  /codeblock>..<h2
d0b0: 3e 54 68 65 20 27 69 6e 74 65 67 72 69 74 79 2d  >The 'integrity-
d0c0: 63 68 65 63 6b 27 20 43 6f 6d 6d 61 6e 64 3c 2f  check' Command</
d0d0: 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f  h2>..<p> This co
d0e0: 6d 6d 61 6e 64 20 69 73 20 75 73 65 64 20 74 6f  mmand is used to
d0f0: 20 76 65 72 69 66 79 20 74 68 61 74 20 74 68 65   verify that the
d100: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
d110: 20 69 73 20 63 6f 6e 73 69 73 74 65 6e 74 20 0a   is consistent .
d120: 77 69 74 68 20 74 68 65 20 63 6f 6e 74 65 6e 74  with the content
d130: 73 20 6f 66 20 74 68 65 20 46 54 53 35 20 74 61  s of the FTS5 ta
d140: 62 6c 65 20 6f 72 20 5b 46 54 53 35 20 65 78 74  ble or [FTS5 ext
d150: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61  ernal content ta
d160: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 20 0a  bles | content .
d170: 74 61 62 6c 65 5d 2e 20 49 74 20 69 73 20 6e 6f  table]. It is no
d180: 74 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68  t available with
d190: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
d1a0: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
d1b0: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 5d 2e  entless tables].
d1c0: 0a 0a 3c 70 3e 54 68 65 20 69 6e 74 65 67 72 69  ..<p>The integri
d1d0: 74 79 2d 63 68 65 63 6b 20 63 6f 6d 6d 61 6e 64  ty-check command
d1e0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 69   is invoked by i
d1f0: 6e 73 65 72 74 69 6e 67 20 74 68 65 20 74 65 78  nserting the tex
d200: 74 20 76 61 6c 75 65 0a 27 69 6e 74 65 67 72 69  t value.'integri
d210: 74 79 2d 63 68 65 63 6b 27 20 69 6e 74 6f 20 74  ty-check' into t
d220: 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6c 75 6d  he special colum
d230: 6e 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  n with the same 
d240: 6e 61 6d 65 20 61 73 20 74 68 65 20 46 54 53 35  name as the FTS5
d250: 0a 74 61 62 6c 65 2e 20 46 6f 72 20 65 78 61 6d  .table. For exam
d260: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
d270: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
d280: 66 74 28 66 74 29 20 56 41 4c 55 45 53 28 27 69  ft(ft) VALUES('i
d290: 6e 74 65 67 72 69 74 79 2d 63 68 65 63 6b 27 29  ntegrity-check')
d2a0: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
d2b0: 3c 70 3e 49 66 20 74 68 65 20 66 75 6c 6c 2d 74  <p>If the full-t
d2c0: 65 78 74 20 69 6e 64 65 78 20 69 73 20 63 6f 6e  ext index is con
d2d0: 73 69 73 74 65 6e 74 20 77 69 74 68 20 74 68 65  sistent with the
d2e0: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
d2f0: 20 74 61 62 6c 65 2c 20 74 68 65 0a 49 4e 53 45   table, the.INSE
d300: 52 54 20 75 73 65 64 20 74 6f 20 69 6e 76 6f 6b  RT used to invok
d310: 65 20 74 68 65 20 69 6e 74 65 67 72 69 74 79 2d  e the integrity-
d320: 63 68 65 63 6b 20 63 6f 6d 6d 61 6e 64 20 73 75  check command su
d330: 63 63 65 65 64 73 2e 20 4f 72 2c 20 69 66 20 61  cceeds. Or, if a
d340: 6e 79 0a 64 69 73 63 72 65 70 61 6e 63 79 20 69  ny.discrepancy i
d350: 73 20 66 6f 75 6e 64 2c 20 69 74 20 66 61 69 6c  s found, it fail
d360: 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54  s with an [SQLIT
d370: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 5d 20  E_CORRUPT_VTAB] 
d380: 65 72 72 6f 72 2e 0a 0a 3c 68 32 20 74 61 67 73  error...<h2 tags
d390: 3d 22 46 54 53 35 20 6d 65 72 67 65 20 63 6f 6d  ="FTS5 merge com
d3a0: 6d 61 6e 64 22 3e 54 68 65 20 27 6d 65 72 67 65  mand">The 'merge
d3b0: 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a  ' Command</h2>..
d3c0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e  <codeblock>.  IN
d3d0: 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c  SERT INTO ft(ft,
d3e0: 20 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 6d   rank) VALUES('m
d3f0: 65 72 67 65 27 2c 20 35 30 30 29 3b 0a 3c 2f 63  erge', 500);.</c
d400: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
d410: 68 69 73 20 63 6f 6d 6d 61 6e 64 20 6d 65 72 67  his command merg
d420: 65 73 20 62 2d 74 72 65 65 20 73 74 72 75 63 74  es b-tree struct
d430: 75 72 65 73 20 74 6f 67 65 74 68 65 72 20 75 6e  ures together un
d440: 74 69 6c 20 72 6f 75 67 68 6c 79 20 4e 20 70 61  til roughly N pa
d450: 67 65 73 0a 6f 66 20 6d 65 72 67 65 64 20 64 61  ges.of merged da
d460: 74 61 20 68 61 76 65 20 62 65 65 6e 20 77 72 69  ta have been wri
d470: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
d480: 62 61 73 65 2c 20 77 68 65 72 65 20 4e 20 69 73  base, where N is
d490: 20 74 68 65 20 61 62 73 6f 6c 75 74 65 0a 76 61   the absolute.va
d4a0: 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d  lue of the param
d4b0: 65 74 65 72 20 73 70 65 63 69 66 69 65 64 20 61  eter specified a
d4c0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 27 6d  s part of the 'm
d4d0: 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 2e 20 54  erge' command. T
d4e0: 68 65 20 73 69 7a 65 20 6f 66 0a 65 61 63 68 20  he size of.each 
d4f0: 70 61 67 65 20 69 73 20 61 73 20 63 6f 6e 66 69  page is as confi
d500: 67 75 72 65 64 20 62 79 20 74 68 65 20 5b 46 54  gured by the [FT
d510: 53 35 20 70 67 73 7a 20 6f 70 74 69 6f 6e 5d 2e  S5 pgsz option].
d520: 0a 0a 3c 70 3e 20 49 66 20 74 68 65 20 70 61 72  ..<p> If the par
d530: 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 73 74  ameter is a post
d540: 69 76 65 20 76 61 6c 75 65 2c 20 42 2d 74 72 65  ive value, B-tre
d550: 65 20 73 74 72 75 63 74 75 72 65 73 20 61 72 65  e structures are
d560: 20 6f 6e 6c 79 20 65 6c 69 67 69 62 6c 65 0a 66   only eligible.f
d570: 6f 72 20 6d 65 72 67 69 6e 67 20 69 66 20 6f 6e  or merging if on
d580: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d590: 6e 67 20 69 73 20 74 72 75 65 3a 0a 0a 3c 75 6c  ng is true:..<ul
d5a0: 3e 0a 20 20 3c 6c 69 3e 20 54 68 65 72 65 20 61  >.  <li> There a
d5b0: 72 65 20 55 20 6f 72 20 6d 6f 72 65 20 73 75 63  re U or more suc
d5c0: 68 20 62 2d 74 72 65 65 73 20 6f 6e 20 61 0a 20  h b-trees on a. 
d5d0: 20 20 20 20 20 20 73 69 6e 67 6c 65 20 6c 65 76        single lev
d5e0: 65 6c 20 28 73 65 65 20 74 68 65 20 64 6f 63 75  el (see the docu
d5f0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68  mentation for th
d600: 65 20 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67  e [FTS5 automerg
d610: 65 20 6f 70 74 69 6f 6e 5d 0a 20 20 20 20 20 20  e option].      
d620: 20 66 6f 72 20 61 6e 20 65 78 70 6c 61 6e 61 74   for an explanat
d630: 69 6f 6e 20 6f 66 20 62 2d 74 72 65 65 20 6c 65  ion of b-tree le
d640: 76 65 6c 73 29 2c 20 77 68 65 72 65 20 55 20 69  vels), where U i
d650: 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 73 69  s the value assi
d660: 67 6e 65 64 0a 20 20 20 20 20 20 20 74 6f 20 74  gned.       to t
d670: 68 65 20 5b 46 54 53 35 20 75 73 65 72 6d 65 72  he [FTS5 usermer
d680: 67 65 20 6f 70 74 69 6f 6e 5d 20 6f 70 74 69 6f  ge option] optio
d690: 6e 2e 0a 20 20 3c 6c 69 3e 20 41 20 6d 65 72 67  n..  <li> A merg
d6a0: 65 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  e has already be
d6b0: 65 6e 20 73 74 61 72 74 65 64 20 28 70 65 72 68  en started (perh
d6c0: 61 70 73 20 62 79 20 61 20 27 6d 65 72 67 65 27  aps by a 'merge'
d6d0: 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 0a 20 20   command that.  
d6e0: 20 20 20 20 20 73 70 65 63 69 66 69 65 64 20 61       specified a
d6f0: 20 6e 65 67 61 74 69 76 65 20 70 61 72 61 6d 65   negative parame
d700: 74 65 72 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  ter)..</ul>..<p>
d710: 20 49 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20   It is possible 
d720: 74 6f 20 74 65 6c 6c 20 77 68 65 74 68 65 72 20  to tell whether 
d730: 6f 72 20 6e 6f 74 20 74 68 65 20 27 6d 65 72 67  or not the 'merg
d740: 65 27 20 63 6f 6d 6d 61 6e 64 20 66 6f 75 6e 64  e' command found
d750: 20 61 6e 79 20 0a 62 2d 74 72 65 65 73 20 74 6f   any .b-trees to
d760: 20 6d 65 72 67 65 20 74 6f 67 65 74 68 65 72 20   merge together 
d770: 62 79 20 63 68 65 63 6b 69 6e 67 20 74 68 65 20  by checking the 
d780: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
d790: 79 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f 74  y the.[sqlite3_t
d7a0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
d7b0: 41 50 49 20 62 65 66 6f 72 65 20 61 6e 64 20 61  API before and a
d7c0: 66 74 65 72 20 74 68 65 20 63 6f 6d 6d 61 6e 64  fter the command
d7d0: 20 69 73 20 65 78 65 63 75 74 65 64 2e 20 49 66   is executed. If
d7e0: 0a 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 20  .the difference 
d7f0: 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
d800: 76 61 6c 75 65 73 20 69 73 20 32 20 6f 72 20 67  values is 2 or g
d810: 72 65 61 74 65 72 2c 20 74 68 65 6e 20 77 6f 72  reater, then wor
d820: 6b 20 77 61 73 20 70 65 72 66 6f 72 6d 65 64 2e  k was performed.
d830: 0a 49 66 20 74 68 65 20 64 69 66 66 65 72 65 6e  .If the differen
d840: 63 65 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ce is less than 
d850: 32 2c 20 74 68 65 6e 20 74 68 65 20 27 6d 65 72  2, then the 'mer
d860: 67 65 27 20 63 6f 6d 6d 61 6e 64 20 77 61 73 20  ge' command was 
d870: 61 20 6e 6f 2d 6f 70 2e 20 49 6e 20 74 68 69 73  a no-op. In this
d880: 0a 63 61 73 65 20 74 68 65 72 65 20 69 73 20 6e  .case there is n
d890: 6f 20 72 65 61 73 6f 6e 20 74 6f 20 65 78 65 63  o reason to exec
d8a0: 75 74 65 20 74 68 65 20 73 61 6d 65 20 27 6d 65  ute the same 'me
d8b0: 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 61 67 61  rge' command aga
d8c0: 69 6e 2c 20 61 74 20 6c 65 61 73 74 0a 75 6e 74  in, at least.unt
d8d0: 69 6c 20 61 66 74 65 72 20 74 68 65 20 46 54 53  il after the FTS
d8e0: 20 74 61 62 6c 65 20 69 73 20 6e 65 78 74 20 75   table is next u
d8f0: 70 64 61 74 65 64 2e 0a 0a 3c 70 3e 20 49 66 20  pdated...<p> If 
d900: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
d910: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 74   negative, and t
d920: 68 65 72 65 20 61 72 65 20 42 2d 74 72 65 65 20  here are B-tree 
d930: 73 74 72 75 63 74 75 72 65 73 20 6f 6e 20 6d 6f  structures on mo
d940: 72 65 20 74 68 61 6e 0a 6f 6e 65 20 6c 65 76 65  re than.one leve
d950: 6c 20 77 69 74 68 69 6e 20 74 68 65 20 46 54 53  l within the FTS
d960: 20 69 6e 64 65 78 2c 20 61 6c 6c 20 42 2d 74 72   index, all B-tr
d970: 65 65 20 73 74 72 75 63 74 75 72 65 73 20 61 72  ee structures ar
d980: 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68  e assigned to th
d990: 65 20 73 61 6d 65 0a 6c 65 76 65 6c 20 62 65 66  e same.level bef
d9a0: 6f 72 65 20 74 68 65 20 6d 65 72 67 65 20 6f 70  ore the merge op
d9b0: 65 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 65  eration is comme
d9c0: 6e 63 65 64 2e 20 41 64 64 69 74 69 6f 6e 61 6c  nced. Additional
d9d0: 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
d9e0: 65 74 65 72 0a 69 73 20 6e 65 67 61 74 69 76 65  eter.is negative
d9f0: 2c 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  , the value of t
da00: 68 65 20 75 73 65 72 6d 65 72 67 65 20 63 6f 6e  he usermerge con
da10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
da20: 6e 20 69 73 20 6e 6f 74 20 0a 72 65 73 70 65 63  n is not .respec
da30: 74 65 64 20 2d 20 61 73 20 66 65 77 20 61 73 20  ted - as few as 
da40: 74 77 6f 20 62 2d 74 72 65 65 73 20 66 72 6f 6d  two b-trees from
da50: 20 74 68 65 20 73 61 6d 65 20 6c 65 76 65 6c 20   the same level 
da60: 6d 61 79 20 62 65 20 6d 65 72 67 65 64 20 74 6f  may be merged to
da70: 67 65 74 68 65 72 2e 0a 0a 3c 70 3e 20 54 68 65  gether...<p> The
da80: 20 61 62 6f 76 65 20 6d 65 61 6e 73 20 74 68 61   above means tha
da90: 74 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20  t executing the 
daa0: 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20  'merge' command 
dab0: 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 0a  with a negative.
dac0: 70 61 72 61 6d 65 74 65 72 20 75 6e 74 69 6c 20  parameter until 
dad0: 74 68 65 20 62 65 66 6f 72 65 20 61 6e 64 20 61  the before and a
dae0: 66 74 65 72 20 64 69 66 66 65 72 65 6e 63 65 20  fter difference 
daf0: 69 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  in the return va
db00: 6c 75 65 20 6f 66 0a 5b 73 71 6c 69 74 65 33 5f  lue of.[sqlite3_
db10: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
db20: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 77   is less than tw
db30: 6f 20 6f 70 74 69 6d 69 7a 65 73 20 74 68 65 20  o optimizes the 
db40: 46 54 53 20 69 6e 64 65 78 20 69 6e 20 74 68 65  FTS index in the
db50: 0a 73 61 6d 65 20 77 61 79 20 61 73 20 74 68 65  .same way as the
db60: 20 5b 46 54 53 35 20 6f 70 74 69 6d 69 7a 65 20   [FTS5 optimize 
db70: 63 6f 6d 6d 61 6e 64 5d 2e 20 48 6f 77 65 76 65  command]. Howeve
db80: 72 2c 20 69 66 20 61 20 6e 65 77 20 62 2d 74 72  r, if a new b-tr
db90: 65 65 20 69 73 20 61 64 64 65 64 0a 74 6f 20 74  ee is added.to t
dba0: 68 65 20 46 54 53 20 69 6e 64 65 78 20 77 68 69  he FTS index whi
dbb0: 6c 65 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  le this process 
dbc0: 69 73 20 6f 6e 67 6f 69 6e 67 2c 20 46 54 53 35  is ongoing, FTS5
dbd0: 20 77 69 6c 6c 20 6d 6f 76 65 20 74 68 65 20 6e   will move the n
dbe0: 65 77 20 0a 62 2d 74 72 65 65 20 74 6f 20 74 68  ew .b-tree to th
dbf0: 65 20 73 61 6d 65 20 6c 65 76 65 6c 20 61 73 20  e same level as 
dc00: 74 68 65 20 65 78 69 73 74 69 6e 67 20 62 2d 74  the existing b-t
dc10: 72 65 65 73 20 61 6e 64 20 72 65 73 74 61 72 74  rees and restart
dc20: 20 74 68 65 20 6d 65 72 67 65 2e 20 54 6f 0a 61   the merge. To.a
dc30: 76 6f 69 64 20 74 68 69 73 2c 20 6f 6e 6c 79 20  void this, only 
dc40: 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
dc50: 6f 20 27 6d 65 72 67 65 27 20 73 68 6f 75 6c 64  o 'merge' should
dc60: 20 73 70 65 63 69 66 79 20 61 20 6e 65 67 61 74   specify a negat
dc70: 69 76 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 45  ive parameter..E
dc80: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 63  ach subsequent c
dc90: 61 6c 6c 20 74 6f 20 27 6d 65 72 67 65 27 20 73  all to 'merge' s
dca0: 68 6f 75 6c 64 20 73 70 65 63 69 66 79 20 61 20  hould specify a 
dcb0: 70 6f 73 74 69 76 65 20 76 61 6c 75 65 20 73 6f  postive value so
dcc0: 20 74 68 61 74 20 74 68 65 0a 6d 65 72 67 65 20   that the.merge 
dcd0: 73 74 61 72 74 65 64 20 62 79 20 74 68 65 20 66  started by the f
dce0: 69 72 73 74 20 63 61 6c 6c 20 69 73 20 72 75 6e  irst call is run
dcf0: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 65   to completion e
dd00: 76 65 6e 20 69 66 20 6e 65 77 20 62 2d 74 72 65  ven if new b-tre
dd10: 65 73 20 61 72 65 0a 61 64 64 65 64 20 74 6f 20  es are.added to 
dd20: 74 68 65 20 46 54 53 20 69 6e 64 65 78 2e 0a 0a  the FTS index...
dd30: 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 6f  <h2 tags="FTS5 o
dd40: 70 74 69 6d 69 7a 65 20 63 6f 6d 6d 61 6e 64 22  ptimize command"
dd50: 3e 54 68 65 20 27 6f 70 74 69 6d 69 7a 65 27 20  >The 'optimize' 
dd60: 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70  Command</h2>..<p
dd70: 3e 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 6d 65  >This command me
dd80: 72 67 65 73 20 61 6c 6c 20 69 6e 64 69 76 69 64  rges all individ
dd90: 75 61 6c 20 62 2d 74 72 65 65 73 20 74 68 61 74  ual b-trees that
dda0: 20 63 75 72 72 65 6e 74 6c 79 20 6d 61 6b 65 20   currently make 
ddb0: 75 70 20 74 68 65 0a 66 75 6c 6c 2d 74 65 78 74  up the.full-text
ddc0: 20 69 6e 64 65 78 20 69 6e 74 6f 20 61 20 73 69   index into a si
ddd0: 6e 67 6c 65 20 6c 61 72 67 65 20 62 2d 74 72 65  ngle large b-tre
dde0: 65 20 73 74 72 75 63 74 75 72 65 2e 20 54 68 69  e structure. Thi
ddf0: 73 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 74  s ensures that t
de00: 68 65 0a 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he.full-text ind
de10: 65 78 20 63 6f 6e 73 75 6d 65 73 20 74 68 65 20  ex consumes the 
de20: 6d 69 6e 69 6d 75 6d 20 73 70 61 63 65 20 77 69  minimum space wi
de30: 74 68 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  thin the databas
de40: 65 20 61 6e 64 20 69 73 20 69 6e 20 74 68 65 0a  e and is in the.
de50: 66 61 73 74 65 73 74 20 66 6f 72 6d 20 74 6f 20  fastest form to 
de60: 71 75 65 72 79 2e 0a 0a 3c 70 3e 52 65 66 65 72  query...<p>Refer
de70: 20 74 6f 20 74 68 65 20 64 6f 63 75 6d 65 6e 74   to the document
de80: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 46  ation for the [F
de90: 54 53 35 20 61 75 74 6f 6d 65 72 67 65 20 6f 70  TS5 automerge op
dea0: 74 69 6f 6e 5d 20 66 6f 72 20 6d 6f 72 65 20 64  tion] for more d
deb0: 65 74 61 69 6c 73 0a 72 65 67 61 72 64 69 6e 67  etails.regarding
dec0: 20 74 68 65 20 72 65 6c 61 74 69 6f 6e 73 68 69   the relationshi
ded0: 70 20 62 65 74 77 65 65 6e 20 74 68 65 20 66 75  p between the fu
dee0: 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 61 6e  ll-text index an
def0: 64 20 69 74 73 20 63 6f 6d 70 6f 6e 65 6e 74 0a  d its component.
df00: 62 2d 74 72 65 65 73 2e 0a 0a 3c 63 6f 64 65 62  b-trees...<codeb
df10: 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49  lock>.  INSERT I
df20: 4e 54 4f 20 66 74 28 66 74 29 20 56 41 4c 55 45  NTO ft(ft) VALUE
df30: 53 28 27 6f 70 74 69 6d 69 7a 65 27 29 3b 0a 3c  S('optimize');.<
df40: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
df50: 42 65 63 61 75 73 65 20 69 74 20 72 65 6f 72 67  Because it reorg
df60: 61 6e 69 7a 65 73 20 74 68 65 20 65 6e 74 69 72  anizes the entir
df70: 65 20 46 54 53 20 69 6e 64 65 78 2c 20 74 68 65  e FTS index, the
df80: 20 6f 70 74 69 6d 69 7a 65 20 63 6f 6d 6d 61 6e   optimize comman
df90: 64 20 63 61 6e 20 0a 74 61 6b 65 20 61 20 6c 6f  d can .take a lo
dfa0: 6e 67 20 74 69 6d 65 20 74 6f 20 72 75 6e 2e 20  ng time to run. 
dfb0: 54 68 65 20 5b 46 54 53 35 20 6d 65 72 67 65 20  The [FTS5 merge 
dfc0: 63 6f 6d 6d 61 6e 64 5d 20 63 61 6e 20 62 65 20  command] can be 
dfd0: 75 73 65 64 20 74 6f 20 64 69 76 69 64 65 0a 74  used to divide.t
dfe0: 68 65 20 77 6f 72 6b 20 6f 66 20 6f 70 74 69 6d  he work of optim
dff0: 69 7a 69 6e 67 20 74 68 65 20 46 54 53 20 69 6e  izing the FTS in
e000: 64 65 78 20 69 6e 74 6f 20 6d 75 6c 74 69 70 6c  dex into multipl
e010: 65 20 73 74 65 70 73 2e 20 54 6f 20 64 6f 20 74  e steps. To do t
e020: 68 69 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  his:..<ul>.  <li
e030: 3e 20 49 6e 76 6f 6b 65 20 74 68 65 20 27 6d 65  > Invoke the 'me
e040: 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 6f 6e 63  rge' command onc
e050: 65 20 77 69 74 68 20 74 68 65 20 70 61 72 61 6d  e with the param
e060: 65 74 65 72 20 73 65 74 20 74 6f 20 2d 4e 2c 20  eter set to -N, 
e070: 74 68 65 6e 0a 20 20 3c 6c 69 3e 20 49 6e 76 6f  then.  <li> Invo
e080: 6b 65 20 74 68 65 20 27 6d 65 72 67 65 27 20 63  ke the 'merge' c
e090: 6f 6d 6d 61 6e 64 20 7a 65 72 6f 20 6f 72 20 6d  ommand zero or m
e0a0: 6f 72 65 20 74 69 6d 65 73 20 77 69 74 68 20 74  ore times with t
e0b0: 68 65 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  he parameter set
e0c0: 20 74 6f 20 4e 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70   to N..</ul>..<p
e0d0: 3e 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20  >where N is the 
e0e0: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
e0f0: 6f 66 20 64 61 74 61 20 74 6f 20 6d 65 72 67 65  of data to merge
e100: 20 77 69 74 68 69 6e 20 65 61 63 68 20 69 6e 76   within each inv
e110: 6f 63 61 74 69 6f 6e 20 6f 66 0a 74 68 65 20 6d  ocation of.the m
e120: 65 72 67 65 20 63 6f 6d 6d 61 6e 64 2e 20 54 68  erge command. Th
e130: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
e140: 6f 75 6c 64 20 73 74 6f 70 20 69 6e 76 6f 6b 69  ould stop invoki
e150: 6e 67 20 6d 65 72 67 65 20 77 68 65 6e 20 74 68  ng merge when th
e160: 65 0a 64 69 66 66 65 72 65 6e 63 65 20 69 6e 20  e.difference in 
e170: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
e180: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
e190: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e1a0: 29 20 66 75 6e 63 74 69 6f 6e 20 62 65 66 6f 72  ) function befor
e1b0: 65 0a 61 6e 64 20 61 66 74 65 72 20 74 68 65 20  e.and after the 
e1c0: 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64 20 64 72  merge command dr
e1d0: 6f 70 73 20 74 6f 20 62 65 6c 6f 77 20 74 77 6f  ops to below two
e1e0: 2e 20 54 68 65 20 6d 65 72 67 65 20 63 6f 6d 6d  . The merge comm
e1f0: 61 6e 64 73 20 6d 61 79 20 62 65 0a 69 73 73 75  ands may be.issu
e200: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e210: 65 20 73 61 6d 65 20 6f 72 20 73 65 70 61 72 61  e same or separa
e220: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2c  te transactions,
e230: 20 61 6e 64 20 62 79 20 74 68 65 20 73 61 6d 65   and by the same
e240: 20 6f 72 0a 64 69 66 66 65 72 65 6e 74 20 64 61   or.different da
e250: 74 61 62 61 73 65 20 63 6c 69 65 6e 74 73 2e 20  tabase clients. 
e260: 52 65 66 65 72 20 74 6f 20 74 68 65 20 64 6f 63  Refer to the doc
e270: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74  umentation for t
e280: 68 65 20 0a 5b 46 54 53 35 20 6d 65 72 67 65 20  he .[FTS5 merge 
e290: 63 6f 6d 6d 61 6e 64 20 7c 20 6d 65 72 67 65 20  command | merge 
e2a0: 63 6f 6d 6d 61 6e 64 5d 20 66 6f 72 20 66 75 72  command] for fur
e2b0: 74 68 65 72 20 64 65 74 61 69 6c 73 2e 0a 0a 3c  ther details...<
e2c0: 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 70 67  h2 tags="FTS5 pg
e2d0: 73 7a 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20 27  sz option">The '
e2e0: 70 67 73 7a 27 20 43 6f 6e 66 69 67 75 72 61 74  pgsz' Configurat
e2f0: 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a  ion Option</h2>.
e300: 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e  .<p> This comman
e310: 64 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  d is used to set
e320: 20 74 68 65 20 70 65 72 73 69 73 74 65 6e 74 20   the persistent 
e330: 22 70 67 73 7a 22 20 6f 70 74 69 6f 6e 2e 0a 0a  "pgsz" option...
e340: 3c 70 3e 20 54 68 65 20 66 75 6c 6c 2d 74 65 78  <p> The full-tex
e350: 74 20 69 6e 64 65 78 20 6d 61 69 6e 74 61 69 6e  t index maintain
e360: 65 64 20 62 79 20 46 54 53 35 20 69 73 20 73 74  ed by FTS5 is st
e370: 6f 72 65 64 20 61 73 20 61 20 73 65 72 69 65 73  ored as a series
e380: 20 6f 66 20 66 69 78 65 64 2d 73 69 7a 65 0a 62   of fixed-size.b
e390: 6c 6f 62 73 20 69 6e 20 61 20 64 61 74 61 62 61  lobs in a databa
e3a0: 73 65 20 74 61 62 6c 65 2e 20 49 74 20 69 73 20  se table. It is 
e3b0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 6e 65 63  not strictly nec
e3c0: 65 73 73 61 72 79 20 66 6f 72 20 61 6c 6c 20 62  essary for all b
e3d0: 6c 6f 62 73 20 74 68 61 74 20 6d 61 6b 65 0a 75  lobs that make.u
e3e0: 70 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  p a full-text in
e3f0: 64 65 78 20 74 6f 20 62 65 20 74 68 65 20 73 61  dex to be the sa
e400: 6d 65 20 73 69 7a 65 2e 20 54 68 65 20 70 67 73  me size. The pgs
e410: 7a 20 6f 70 74 69 6f 6e 20 64 65 74 65 72 6d 69  z option determi
e420: 6e 65 73 20 74 68 65 20 73 69 7a 65 0a 6f 66 20  nes the size.of 
e430: 61 6c 6c 20 62 6c 6f 62 73 20 63 72 65 61 74 65  all blobs create
e440: 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20  d by subsequent 
e450: 69 6e 64 65 78 20 77 72 69 74 65 72 73 2e 20 54  index writers. T
e460: 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
e470: 20 69 73 20 31 30 30 30 2e 0a 0a 3c 63 6f 64 65   is 1000...<code
e480: 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20  block>.  INSERT 
e490: 49 4e 54 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b  INTO ft(ft, rank
e4a0: 29 20 56 41 4c 55 45 53 28 27 70 67 73 7a 27 2c  ) VALUES('pgsz',
e4b0: 20 34 30 37 32 29 3b 0a 3c 2f 63 6f 64 65 62 6c   4072);.</codebl
e4c0: 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ock>..<h2 tags="
e4d0: 46 54 53 35 20 72 61 6e 6b 20 63 6f 6e 66 69 67  FTS5 rank config
e4e0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 22 3e  uration option">
e4f0: 54 68 65 20 27 72 61 6e 6b 27 20 43 6f 6e 66 69  The 'rank' Confi
e500: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c  guration Option<
e510: 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63  /h2>..<p> This c
e520: 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65 64 20 74  ommand is used t
e530: 6f 20 73 65 74 20 74 68 65 20 70 65 72 73 69 73  o set the persis
e540: 74 65 6e 74 20 22 72 61 6e 6b 22 20 6f 70 74 69  tent "rank" opti
e550: 6f 6e 2e 0a 0a 3c 70 3e 20 54 68 65 20 72 61 6e  on...<p> The ran
e560: 6b 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  k option is used
e570: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 64   to change the d
e580: 65 66 61 75 6c 74 20 61 75 78 69 6c 69 61 72 79  efault auxiliary
e590: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 70 70 69 6e   function mappin
e5a0: 67 0a 66 6f 72 20 74 68 65 20 72 61 6e 6b 20 63  g.for the rank c
e5b0: 6f 6c 75 6d 6e 2e 20 54 68 65 20 6f 70 74 69 6f  olumn. The optio
e5c0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  n should be set 
e5d0: 74 6f 20 61 20 74 65 78 74 20 76 61 6c 75 65 20  to a text value 
e5e0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 66 6f 72 6d  in the same.form
e5f0: 61 74 20 61 73 20 64 65 73 63 72 69 62 65 64 20  at as described 
e600: 66 6f 72 20 5b 61 75 78 69 6c 69 61 72 79 20 66  for [auxiliary f
e610: 75 6e 63 74 69 6f 6e 20 6d 61 70 70 69 6e 67 20  unction mapping 
e620: 7c 20 22 72 61 6e 6b 20 4d 41 54 43 48 20 3f 22  | "rank MATCH ?"
e630: 5d 20 74 65 72 6d 73 20 0a 61 62 6f 76 65 2e 20  ] terms .above. 
e640: 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63  For example:..<c
e650: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45  odeblock>.  INSE
e660: 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c 20 72  RT INTO ft(ft, r
e670: 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 72 61 6e  ank) VALUES('ran
e680: 6b 27 2c 20 27 62 6d 32 35 28 31 30 2e 30 2c 20  k', 'bm25(10.0, 
e690: 35 2e 30 29 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c  5.0)');.</codebl
e6a0: 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ock>..<h2 tags="
e6b0: 46 54 53 35 20 72 65 62 75 69 6c 64 20 63 6f 6d  FTS5 rebuild com
e6c0: 6d 61 6e 64 22 3e 54 68 65 20 27 72 65 62 75 69  mand">The 'rebui
e6d0: 6c 64 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e  ld' Command</h2>
e6e0: 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61  ..<p> This comma
e6f0: 6e 64 20 66 69 72 73 74 20 64 65 6c 65 74 65 73  nd first deletes
e700: 20 74 68 65 20 65 6e 74 69 72 65 20 66 75 6c 6c   the entire full
e710: 2d 74 65 78 74 20 69 6e 64 65 78 2c 20 74 68 65  -text index, the
e720: 6e 20 72 65 62 75 69 6c 64 73 20 69 74 0a 62 61  n rebuilds it.ba
e730: 73 65 64 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  sed on the conte
e740: 6e 74 73 20 6f 66 20 74 68 65 20 74 61 62 6c 65  nts of the table
e750: 20 6f 72 20 5b 46 54 53 35 20 65 78 74 65 72 6e   or [FTS5 extern
e760: 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  al content table
e770: 73 20 7c 20 63 6f 6e 74 65 6e 74 0a 74 61 62 6c  s | content.tabl
e780: 65 5d 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 61  e].  It is not a
e790: 76 61 69 6c 61 62 6c 65 20 77 69 74 68 20 5b 46  vailable with [F
e7a0: 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20  TS5 contentless 
e7b0: 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74  tables | content
e7c0: 6c 65 73 73 0a 74 61 62 6c 65 73 5d 2e 0a 0a 3c  less.tables]...<
e7d0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53  codeblock>.  INS
e7e0: 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 29 20  ERT INTO ft(ft) 
e7f0: 56 41 4c 55 45 53 28 27 72 65 62 75 69 6c 64 27  VALUES('rebuild'
e800: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
e810: 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20  .<h2 tags="FTS5 
e820: 75 73 65 72 6d 65 72 67 65 20 6f 70 74 69 6f 6e  usermerge option
e830: 22 3e 54 68 65 20 27 75 73 65 72 6d 65 72 67 65  ">The 'usermerge
e840: 27 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ' Configuration 
e850: 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  Option</h2>..<p>
e860: 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73   This command is
e870: 20 75 73 65 64 20 74 6f 20 73 65 74 20 74 68 65   used to set the
e880: 20 70 65 72 73 69 73 74 65 6e 74 20 22 75 73 65   persistent "use
e890: 72 6d 65 72 67 65 22 20 6f 70 74 69 6f 6e 2e 0a  rmerge" option..
e8a0: 0a 3c 70 3e 20 54 68 65 20 75 73 65 72 6d 65 72  .<p> The usermer
e8b0: 67 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 69 6d  ge option is sim
e8c0: 69 6c 61 72 20 74 6f 20 74 68 65 20 61 75 74 6f  ilar to the auto
e8d0: 6d 65 72 67 65 20 61 6e 64 20 63 72 69 73 69 73  merge and crisis
e8e0: 6d 65 72 67 65 20 6f 70 74 69 6f 6e 73 2e 0a 49  merge options..I
e8f0: 74 20 69 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  t is the minimum
e900: 20 6e 75 6d 62 65 72 20 6f 66 20 62 2d 74 72 65   number of b-tre
e910: 65 20 73 65 67 6d 65 6e 74 73 20 74 68 61 74 20  e segments that 
e920: 77 69 6c 6c 20 62 65 20 6d 65 72 67 65 64 20 74  will be merged t
e930: 6f 67 65 74 68 65 72 20 62 79 0a 61 20 27 6d 65  ogether by.a 'me
e940: 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 77 69 74  rge' command wit
e950: 68 20 61 20 70 6f 73 69 74 69 76 65 20 70 61 72  h a positive par
e960: 61 6d 65 74 65 72 2e 20 46 6f 72 20 65 78 61 6d  ameter. For exam
e970: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
e980: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
e990: 66 74 28 66 74 2c 20 72 61 6e 6b 29 20 56 41 4c  ft(ft, rank) VAL
e9a0: 55 45 53 28 27 75 73 65 72 6d 65 72 67 65 27 2c  UES('usermerge',
e9b0: 20 34 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b   4);.</codeblock
e9c0: 3e 0a 0a 3c 70 3e 20 54 68 65 20 64 65 66 61 75  >..<p> The defau
e9d0: 6c 74 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  lt value of the 
e9e0: 75 73 65 72 6d 65 72 67 65 20 6f 70 74 69 6f 6e  usermerge option
e9f0: 20 69 73 20 34 2e 20 54 68 65 20 6d 69 6e 69 6d   is 4. The minim
ea00: 75 6d 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  um allowed value
ea10: 0a 69 73 20 32 2c 20 61 6e 64 20 74 68 65 20 6d  .is 2, and the m
ea20: 61 78 69 6d 75 6d 20 31 36 2e 0a 0a 3c 68 31 20  aximum 16...<h1 
ea30: 74 61 67 73 3d 22 45 78 74 65 6e 64 69 6e 67 20  tags="Extending 
ea40: 46 54 53 35 22 3e 45 78 74 65 6e 64 69 6e 67 20  FTS5">Extending 
ea50: 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 70 3e 46 54  FTS5</h1>..<p>FT
ea60: 53 35 20 66 65 61 74 75 72 65 73 20 41 50 49 73  S5 features APIs
ea70: 20 61 6c 6c 6f 77 69 6e 67 20 69 74 20 74 6f 20   allowing it to 
ea80: 62 65 20 65 78 74 65 6e 64 65 64 20 62 79 3a 0a  be extended by:.
ea90: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 41 64 64  .<ul>.  <li> Add
eaa0: 69 6e 67 20 6e 65 77 20 61 75 78 69 6c 69 61 72  ing new auxiliar
eab0: 79 20 66 75 6e 63 74 69 6f 6e 73 20 69 6d 70 6c  y functions impl
eac0: 65 6d 65 6e 74 65 64 20 69 6e 20 43 2c 20 61 6e  emented in C, an
ead0: 64 0a 20 20 3c 6c 69 3e 20 41 64 64 69 6e 67 20  d.  <li> Adding 
eae0: 6e 65 77 20 74 6f 6b 65 6e 69 7a 65 72 73 2c 20  new tokenizers, 
eaf0: 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e 74 65 64  also implemented
eb00: 20 69 6e 20 43 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70   in C..</ul>..<p
eb10: 3e 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 74  > The built-in t
eb20: 6f 6b 65 6e 69 7a 65 72 73 20 61 6e 64 20 61 75  okenizers and au
eb30: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
eb40: 73 20 64 65 73 63 72 69 62 65 64 20 69 6e 20 74  s described in t
eb50: 68 69 73 0a 64 6f 63 75 6d 65 6e 74 20 61 72 65  his.document are
eb60: 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 65 64   all implemented
eb70: 20 75 73 69 6e 67 20 74 68 65 20 70 75 62 6c 69   using the publi
eb80: 63 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 41 50  cly available AP
eb90: 49 20 64 65 73 63 72 69 62 65 64 0a 62 65 6c 6f  I described.belo
eba0: 77 2e 0a 0a 3c 70 3e 20 42 65 66 6f 72 65 20 61  w...<p> Before a
ebb0: 20 6e 65 77 20 61 75 78 69 6c 69 61 72 79 20 66   new auxiliary f
ebc0: 75 6e 63 74 69 6f 6e 20 6f 72 20 74 6f 6b 65 6e  unction or token
ebd0: 69 7a 65 72 20 69 6d 70 6c 65 6d 65 6e 74 61 74  izer implementat
ebe0: 69 6f 6e 20 6d 61 79 20 62 65 20 0a 72 65 67 69  ion may be .regi
ebf0: 73 74 65 72 65 64 20 77 69 74 68 20 46 54 53 35  stered with FTS5
ec00: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
ec10: 20 6d 75 73 74 20 6f 62 74 61 69 6e 20 61 20 70   must obtain a p
ec20: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 22 66  ointer to the "f
ec30: 74 73 35 5f 61 70 69 22 0a 73 74 72 75 63 74 75  ts5_api".structu
ec40: 72 65 2e 20 54 68 65 72 65 20 69 73 20 6f 6e 65  re. There is one
ec50: 20 66 74 73 35 5f 61 70 69 20 73 74 72 75 63 74   fts5_api struct
ec60: 75 72 65 20 66 6f 72 20 65 61 63 68 20 64 61 74  ure for each dat
ec70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ec80: 20 77 69 74 68 0a 77 68 69 63 68 20 74 68 65 20   with.which the 
ec90: 46 54 53 35 20 65 78 74 65 6e 73 69 6f 6e 20 69  FTS5 extension i
eca0: 73 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 6f  s registered. To
ecb0: 20 6f 62 74 61 69 6e 20 74 68 65 20 70 6f 69 6e   obtain the poin
ecc0: 74 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ter, the applica
ecd0: 74 69 6f 6e 0a 69 6e 76 6f 6b 65 73 20 74 68 65  tion.invokes the
ece0: 20 53 51 4c 20 75 73 65 72 2d 64 65 66 69 6e 65   SQL user-define
ecf0: 64 20 66 75 6e 63 74 69 6f 6e 20 66 74 73 35 28  d function fts5(
ed00: 29 2c 20 77 68 69 63 68 20 72 65 74 75 72 6e 73  ), which returns
ed10: 20 61 20 62 6c 6f 62 20 76 61 6c 75 65 0a 63 6f   a blob value.co
ed20: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 70 6f 69  ntaining the poi
ed30: 6e 74 65 72 20 74 6f 20 74 68 65 20 66 74 73 35  nter to the fts5
ed40: 5f 61 70 69 20 73 74 72 75 63 74 75 72 65 20 66  _api structure f
ed50: 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
ed60: 6e 2e 20 54 68 65 0a 66 6f 6c 6c 6f 77 69 6e 67  n. The.following
ed70: 20 65 78 61 6d 70 6c 65 20 63 6f 64 65 20 64 65   example code de
ed80: 6d 6f 6e 73 74 72 61 74 65 73 20 74 68 65 20 74  monstrates the t
ed90: 65 63 68 6e 69 71 75 65 3a 0a 0a 3c 63 6f 64 65  echnique:..<code
eda0: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2f 2a 0a 20  block>.  <i>/*. 
edb0: 20 2a 2a 20 52 65 74 75 72 6e 20 61 20 70 6f 69   ** Return a poi
edc0: 6e 74 65 72 20 74 6f 20 74 68 65 20 66 74 73 35  nter to the fts5
edd0: 5f 61 70 69 20 70 6f 69 6e 74 65 72 20 66 6f 72  _api pointer for
ede0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
edf0: 74 69 6f 6e 20 64 62 2e 0a 20 20 2a 2a 20 49 66  tion db..  ** If
ee00: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
ee10: 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 61 6e  , return NULL an
ee20: 64 20 6c 65 61 76 65 20 61 6e 20 65 72 72 6f 72  d leave an error
ee30: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
ee40: 20 0a 20 20 2a 2a 20 68 61 6e 64 6c 65 20 28 61   .  ** handle (a
ee50: 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
ee60: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
ee70: 29 2f 65 72 72 6d 73 67 28 29 29 2e 0a 20 20 2a  )/errmsg())..  *
ee80: 2f 3c 2f 69 3e 0a 20 20 66 74 73 35 5f 61 70 69  /</i>.  fts5_api
ee90: 20 2a 66 74 73 35 5f 61 70 69 5f 66 72 6f 6d 5f   *fts5_api_from_
eea0: 64 62 28 73 71 6c 69 74 65 33 20 2a 64 62 29 7b  db(sqlite3 *db){
eeb0: 0a 20 20 20 20 66 74 73 35 5f 61 70 69 20 2a 70  .    fts5_api *p
eec0: 52 65 74 20 3d 20 30 3b 0a 20 20 20 20 73 71 6c  Ret = 0;.    sql
eed0: 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
eee0: 20 3d 20 30 3b 0a 0a 20 20 20 20 69 66 28 20 53   = 0;..    if( S
eef0: 51 4c 49 54 45 5f 4f 4b 3d 3d 73 71 6c 69 74 65  QLITE_OK==sqlite
ef00: 33 5f 70 72 65 70 61 72 65 28 64 62 2c 20 22 53  3_prepare(db, "S
ef10: 45 4c 45 43 54 20 66 74 73 35 28 29 22 2c 20 2d  ELECT fts5()", -
ef20: 31 2c 20 26 70 53 74 6d 74 2c 20 30 29 0a 20 20  1, &pStmt, 0).  
ef30: 20 20 20 26 26 20 53 51 4c 49 54 45 5f 52 4f 57     && SQLITE_ROW
ef40: 3d 3d 73 71 6c 69 74 65 33 5f 73 74 65 70 28 70  ==sqlite3_step(p
ef50: 53 74 6d 74 29 20 0a 20 20 20 20 20 26 26 20 73  Stmt) .     && s
ef60: 69 7a 65 6f 66 28 70 52 65 74 29 3d 3d 73 71 6c  izeof(pRet)==sql
ef70: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
ef80: 73 28 70 53 74 6d 74 2c 20 30 29 0a 20 20 20 20  s(pStmt, 0).    
ef90: 29 7b 0a 20 20 20 20 20 20 6d 65 6d 63 70 79 28  ){.      memcpy(
efa0: 26 70 52 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  &pRet, sqlite3_c
efb0: 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 70 53 74 6d 74  olumn_blob(pStmt
efc0: 2c 20 30 29 2c 20 73 69 7a 65 6f 66 28 70 52 65  , 0), sizeof(pRe
efd0: 74 29 29 3b 0a 20 20 20 20 7d 0a 20 20 20 20 73  t));.    }.    s
efe0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
eff0: 70 53 74 6d 74 29 3b 0a 20 20 20 20 72 65 74 75  pStmt);.    retu
f000: 72 6e 20 70 52 65 74 3b 0a 20 20 7d 0a 3c 2f 63  rn pRet;.  }.</c
f010: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
f020: 68 65 20 66 74 73 35 5f 61 70 69 20 73 74 72 75  he fts5_api stru
f030: 63 74 75 72 65 20 69 73 20 64 65 66 69 6e 65 64  cture is defined
f040: 20 61 73 20 66 6f 6c 6c 6f 77 73 2e 20 49 74 20   as follows. It 
f050: 65 78 70 6f 73 65 73 20 74 68 72 65 65 20 6d 65  exposes three me
f060: 74 68 6f 64 73 2c 20 0a 6f 6e 65 20 65 61 63 68  thods, .one each
f070: 20 66 6f 72 20 72 65 67 69 73 74 65 72 69 6e 67   for registering
f080: 20 6e 65 77 20 61 75 78 69 6c 69 61 72 79 20 66   new auxiliary f
f090: 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 74 6f 6b  unctions and tok
f0a0: 65 6e 69 7a 65 72 73 2c 20 61 6e 64 20 6f 6e 65  enizers, and one
f0b0: 20 66 6f 72 0a 72 65 74 72 69 65 76 69 6e 67 20   for.retrieving 
f0c0: 65 78 69 73 74 69 6e 67 20 74 6f 6b 65 6e 69 7a  existing tokeniz
f0d0: 65 72 2e 20 54 68 65 20 6c 61 74 74 65 72 20 69  er. The latter i
f0e0: 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 66 61  s intended to fa
f0f0: 63 69 6c 69 74 61 74 65 20 74 68 65 0a 69 6d 70  cilitate the.imp
f100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 22  lementation of "
f110: 74 6f 6b 65 6e 69 7a 65 72 20 77 72 61 70 70 65  tokenizer wrappe
f120: 72 73 22 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  rs" similar to t
f130: 68 65 20 62 75 69 6c 74 2d 69 6e 0a 70 6f 72 74  he built-in.port
f140: 65 72 20 74 6f 6b 65 6e 69 7a 65 72 2e 0a 0a 3c  er tokenizer...<
f150: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 3c 74 63 6c 73  codeblock>.<tcls
f160: 63 72 69 70 74 3e 0a 20 20 73 65 74 20 72 65 73  cript>.  set res
f170: 20 22 22 0a 20 20 73 65 74 20 3a 3a 65 78 74 72   "".  set ::extr
f180: 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64  act_api_docs_mod
f190: 65 20 66 74 73 35 5f 61 70 69 0a 20 20 63 61 74  e fts5_api.  cat
f1a0: 63 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73 6f  ch { set res [so
f1b0: 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e 20  urce [file join 
f1c0: 24 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35 2f  $::SRC ext/fts5/
f1d0: 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73  extract_api_docs
f1e0: 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20 72  .tcl]] }.  set r
f1f0: 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e 0a  es.</tclscript>.
f200: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
f210: 3e 20 54 6f 20 69 6e 76 6f 6b 65 20 61 20 6d 65  > To invoke a me
f220: 74 68 6f 64 20 6f 66 20 74 68 65 20 66 74 73 35  thod of the fts5
f230: 5f 61 70 69 20 6f 62 6a 65 63 74 2c 20 74 68 65  _api object, the
f240: 20 66 74 73 35 5f 61 70 69 20 70 6f 69 6e 74 65   fts5_api pointe
f250: 72 20 69 74 73 65 6c 66 0a 73 68 6f 75 6c 64 20  r itself.should 
f260: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
f270: 20 6d 65 74 68 6f 64 73 20 66 69 72 73 74 20 61   methods first a
f280: 72 67 75 6d 65 6e 74 20 66 6f 6c 6c 6f 77 65 64  rgument followed
f290: 20 62 79 20 74 68 65 20 6f 74 68 65 72 2c 20 6d   by the other, m
f2a0: 65 74 68 6f 64 0a 73 70 65 63 69 66 69 63 2c 20  ethod.specific, 
f2b0: 61 72 67 75 6d 65 6e 74 73 2e 20 46 6f 72 20 65  arguments. For e
f2c0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
f2d0: 6f 63 6b 3e 0a 20 20 20 20 72 63 20 3d 20 70 46  ock>.    rc = pF
f2e0: 74 73 35 41 70 69 2d 3e 78 43 72 65 61 74 65 54  ts5Api->xCreateT
f2f0: 6f 6b 65 6e 69 7a 65 72 28 70 46 74 73 35 41 70  okenizer(pFts5Ap
f300: 69 2c 20 2e 2e 2e 20 6f 74 68 65 72 20 61 72 67  i, ... other arg
f310: 73 20 2e 2e 2e 29 3b 0a 3c 2f 63 6f 64 65 62 6c  s ...);.</codebl
f320: 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 66 74  ock>..<p> The ft
f330: 73 35 5f 61 70 69 20 73 74 72 75 63 74 75 72 65  s5_api structure
f340: 20 6d 65 74 68 6f 64 73 20 61 72 65 20 64 65 73   methods are des
f350: 63 72 69 62 65 64 20 69 6e 64 69 76 69 64 75 61  cribed individua
f360: 6c 6c 79 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  lly in the follo
f370: 77 69 6e 67 0a 73 65 63 74 69 6f 6e 73 2e 0a 0a  wing.sections...
f380: 3c 68 32 20 74 61 67 73 3d 22 63 75 73 74 6f 6d  <h2 tags="custom
f390: 20 74 6f 6b 65 6e 69 7a 65 72 73 22 3e 43 75 73   tokenizers">Cus
f3a0: 74 6f 6d 20 54 6f 6b 65 6e 69 7a 65 72 73 3c 2f  tom Tokenizers</
f3b0: 68 32 3e 0a 0a 3c 70 3e 20 54 6f 20 63 72 65 61  h2>..<p> To crea
f3c0: 74 65 20 61 20 63 75 73 74 6f 6d 20 74 6f 6b 65  te a custom toke
f3d0: 6e 69 7a 65 72 2c 20 61 6e 20 61 70 70 6c 69 63  nizer, an applic
f3e0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6d 70 6c 65  ation must imple
f3f0: 6d 65 6e 74 20 74 68 72 65 65 0a 66 75 6e 63 74  ment three.funct
f400: 69 6f 6e 73 3a 20 61 20 74 6f 6b 65 6e 69 7a 65  ions: a tokenize
f410: 72 20 63 6f 6e 73 74 72 75 63 74 6f 72 20 28 78  r constructor (x
f420: 43 72 65 61 74 65 29 2c 20 61 20 64 65 73 74 72  Create), a destr
f430: 75 63 74 6f 72 20 28 78 44 65 6c 65 74 65 29 20  uctor (xDelete) 
f440: 61 6e 64 20 61 0a 66 75 6e 63 74 69 6f 6e 20 74  and a.function t
f450: 6f 20 64 6f 20 74 68 65 20 61 63 74 75 61 6c 20  o do the actual 
f460: 74 6f 6b 65 6e 69 7a 61 74 69 6f 6e 20 28 78 54  tokenization (xT
f470: 6f 6b 65 6e 69 7a 65 29 2e 20 54 68 65 20 74 79  okenize). The ty
f480: 70 65 20 6f 66 20 65 61 63 68 0a 66 75 6e 63 74  pe of each.funct
f490: 69 6f 6e 20 69 73 20 61 73 20 66 6f 72 20 74 68  ion is as for th
f4a0: 65 20 6d 65 6d 62 65 72 20 76 61 72 69 61 62 6c  e member variabl
f4b0: 65 73 20 6f 66 20 74 68 65 20 66 74 73 35 5f 74  es of the fts5_t
f4c0: 6f 6b 65 6e 69 7a 65 72 20 73 74 72 75 63 74 3a  okenizer struct:
f4d0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 3c 74  ..<codeblock>.<t
f4e0: 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74 20  clscript>.  set 
f4f0: 72 65 73 20 22 22 0a 20 20 73 65 74 20 3a 3a 65  res "".  set ::e
f500: 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f  xtract_api_docs_
f510: 6d 6f 64 65 20 66 74 73 35 5f 74 6f 6b 65 6e 69  mode fts5_tokeni
f520: 7a 65 72 0a 20 20 63 61 74 63 68 20 7b 20 73 65  zer.  catch { se
f530: 74 20 72 65 73 20 5b 73 6f 75 72 63 65 20 5b 66  t res [source [f
f540: 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43 20  ile join $::SRC 
f550: 65 78 74 2f 66 74 73 35 2f 65 78 74 72 61 63 74  ext/fts5/extract
f560: 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d 20  _api_docs.tcl]] 
f570: 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f 74 63  }.  set res.</tc
f580: 6c 73 63 72 69 70 74 3e 0a 3c 2f 63 6f 64 65 62  lscript>.</codeb
f590: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 57 68 65 6e 20  lock>..<p> When 
f5a0: 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 75 73  an FTS5 table us
f5b0: 65 73 20 74 68 65 20 63 75 73 74 6f 6d 20 74 6f  es the custom to
f5c0: 6b 65 6e 69 7a 65 72 2c 20 74 68 65 20 46 54 53  kenizer, the FTS
f5d0: 35 20 63 6f 72 65 20 63 61 6c 6c 73 20 78 43 72  5 core calls xCr
f5e0: 65 61 74 65 28 29 0a 6f 6e 63 65 20 74 6f 20 63  eate().once to c
f5f0: 72 65 61 74 65 20 61 20 74 6f 6b 65 6e 69 7a 65  reate a tokenize
f600: 72 2c 20 74 68 65 6e 20 78 54 6f 6b 65 6e 69 7a  r, then xTokeniz
f610: 65 28 29 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  e() zero or more
f620: 20 74 69 6d 65 73 20 74 6f 20 74 6f 6b 65 6e 69   times to tokeni
f630: 7a 65 0a 73 74 72 69 6e 67 73 2c 20 74 68 65 6e  ze.strings, then
f640: 20 78 44 65 6c 65 74 65 28 29 20 74 6f 20 66 72   xDelete() to fr
f650: 65 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  ee any resources
f660: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 78 43   allocated by xC
f670: 72 65 61 74 65 28 29 2e 20 4d 6f 72 65 0a 73 70  reate(). More.sp
f680: 65 63 69 66 69 63 61 6c 6c 79 3a 0a 0a 3c 74 63  ecifically:..<tc
f690: 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74 20 72  lscript>.  set r
f6a0: 65 73 20 22 22 0a 20 20 73 65 74 20 3a 3a 65 78  es "".  set ::ex
f6b0: 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f 6d  tract_api_docs_m
f6c0: 6f 64 65 20 74 6f 6b 65 6e 69 7a 65 72 5f 61 70  ode tokenizer_ap
f6d0: 69 0a 20 20 63 61 74 63 68 20 7b 20 73 65 74 20  i.  catch { set 
f6e0: 72 65 73 20 5b 73 6f 75 72 63 65 20 5b 66 69 6c  res [source [fil
f6f0: 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43 20 65 78  e join $::SRC ex
f700: 74 2f 66 74 73 35 2f 65 78 74 72 61 63 74 5f 61  t/fts5/extract_a
f710: 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a  pi_docs.tcl]] }.
f720: 20 20 73 65 74 20 72 65 73 0a 3c 2f 74 63 6c 73    set res.</tcls
f730: 63 72 69 70 74 3e 0a 0a 3c 68 32 20 74 61 67 73  cript>..<h2 tags
f740: 3d 22 46 54 53 35 20 63 75 73 74 6f 6d 20 61 75  ="FTS5 custom au
f750: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
f760: 73 22 3e 43 75 73 74 6f 6d 20 41 75 78 69 6c 69  s">Custom Auxili
f770: 61 72 79 20 46 75 6e 63 74 69 6f 6e 73 3c 2f 68  ary Functions</h
f780: 32 3e 0a 0a 3c 70 3e 20 49 6d 70 6c 65 6d 65 6e  2>..<p> Implemen
f790: 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 20 61 75  ting a custom au
f7a0: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
f7b0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 69   is similar to i
f7c0: 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61 0a 5b 61  mplementing a.[a
f7d0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
f7e0: 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
f7f0: 7c 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  | scalar SQL fun
f800: 63 74 69 6f 6e 5d 2e 20 54 68 65 20 69 6d 70 6c  ction]. The impl
f810: 65 6d 65 6e 74 61 74 69 6f 6e 0a 73 68 6f 75 6c  ementation.shoul
f820: 64 20 62 65 20 61 20 43 20 66 75 6e 63 74 69 6f  d be a C functio
f830: 6e 20 6f 66 20 74 79 70 65 20 66 74 73 35 5f 65  n of type fts5_e
f840: 78 74 65 6e 73 69 6f 6e 5f 66 75 6e 63 74 69 6f  xtension_functio
f850: 6e 2c 20 64 65 66 69 6e 65 64 20 61 73 20 66 6f  n, defined as fo
f860: 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  llows:..<codeblo
f870: 63 6b 3e 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a  ck>.<tclscript>.
f880: 20 20 73 65 74 20 72 65 73 20 22 22 0a 20 20 73    set res "".  s
f890: 65 74 20 3a 3a 65 78 74 72 61 63 74 5f 61 70 69  et ::extract_api
f8a0: 5f 64 6f 63 73 5f 6d 6f 64 65 20 66 74 73 35 5f  _docs_mode fts5_
f8b0: 65 78 74 65 6e 73 69 6f 6e 0a 20 20 63 61 74 63  extension.  catc
f8c0: 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73 6f 75  h { set res [sou
f8d0: 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24  rce [file join $
f8e0: 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35 2f 65  ::SRC ext/fts5/e
f8f0: 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e  xtract_api_docs.
f900: 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65  tcl]] }.  set re
f910: 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e 0a 3c  s.</tclscript>.<
f920: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
f930: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
f940: 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
f950: 64 20 77 69 74 68 20 74 68 65 20 46 54 53 35 20  d with the FTS5 
f960: 6d 6f 64 75 6c 65 20 62 79 20 63 61 6c 6c 69 6e  module by callin
f970: 67 20 74 68 65 0a 78 43 72 65 61 74 65 46 75 6e  g the.xCreateFun
f980: 63 74 69 6f 6e 28 29 20 6d 65 74 68 6f 64 20 6f  ction() method o
f990: 66 20 74 68 65 20 66 74 73 35 5f 61 70 69 20 6f  f the fts5_api o
f9a0: 62 6a 65 63 74 2e 20 49 66 20 74 68 65 72 65 20  bject. If there 
f9b0: 69 73 20 61 6c 72 65 61 64 79 20 61 6e 0a 61 75  is already an.au
f9c0: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
f9d0: 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
f9e0: 61 6d 65 2c 20 69 74 20 69 73 20 72 65 70 6c 61  ame, it is repla
f9f0: 63 65 64 20 62 79 20 74 68 65 20 6e 65 77 20 66  ced by the new f
fa00: 75 6e 63 74 69 6f 6e 2e 0a 49 66 20 61 20 6e 6f  unction..If a no
fa10: 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
fa20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
fa30: 73 65 64 20 74 6f 20 78 43 72 65 61 74 65 46 75  sed to xCreateFu
fa40: 6e 63 74 69 6f 6e 28 29 2c 20 69 74 20 69 73 20  nction(), it is 
fa50: 69 6e 76 6f 6b 65 64 0a 77 69 74 68 20 61 20 63  invoked.with a c
fa60: 6f 70 79 20 6f 66 20 74 68 65 20 70 43 6f 6e 74  opy of the pCont
fa70: 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
fa80: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ed as the only a
fa90: 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
faa0: 0a 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65  .database handle
fab0: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 77 68   is closed or wh
fac0: 65 6e 20 74 68 65 20 72 65 67 69 73 74 65 72 65  en the registere
fad0: 64 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  d auxiliary func
fae0: 74 69 6f 6e 20 69 73 0a 72 65 70 6c 61 63 65 64  tion is.replaced
faf0: 2e 0a 0a 3c 70 3e 20 54 68 65 20 66 69 6e 61 6c  ...<p> The final
fb00: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
fb10: 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 61   passed to the a
fb20: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
fb30: 6e 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 73  n callback are.s
fb40: 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 20 74 68  imilar to the th
fb50: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 70 61  ree arguments pa
fb60: 73 73 65 64 20 74 6f 20 74 68 65 20 69 6d 70 6c  ssed to the impl
fb70: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
fb80: 73 63 61 6c 61 72 20 53 51 4c 0a 66 75 6e 63 74  scalar SQL.funct
fb90: 69 6f 6e 2e 20 41 6c 6c 20 61 72 67 75 6d 65 6e  ion. All argumen
fba0: 74 73 20 65 78 63 65 70 74 20 74 68 65 20 66 69  ts except the fi
fbb0: 72 73 74 20 70 61 73 73 65 64 20 74 6f 20 74 68  rst passed to th
fbc0: 65 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  e auxiliary func
fbd0: 74 69 6f 6e 20 61 72 65 0a 61 76 61 69 6c 61 62  tion are.availab
fbe0: 6c 65 20 74 6f 20 74 68 65 20 69 6d 70 6c 65 6d  le to the implem
fbf0: 65 6e 74 61 74 69 6f 6e 20 69 6e 20 74 68 65 20  entation in the 
fc00: 61 70 56 61 6c 26 23 39 31 3b 26 23 39 33 3b 20  apVal&#91;&#93; 
fc10: 61 72 72 61 79 2e 20 54 68 65 0a 69 6d 70 6c 65  array. The.imple
fc20: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
fc30: 20 72 65 74 75 72 6e 20 61 20 72 65 73 75 6c 74   return a result
fc40: 20 6f 72 20 65 72 72 6f 72 20 76 69 61 20 74 68   or error via th
fc50: 65 20 63 6f 6e 74 65 6e 74 20 68 61 6e 64 6c 65  e content handle
fc60: 20 70 43 74 78 2e 0a 0a 3c 70 3e 20 54 68 65 20   pCtx...<p> The 
fc70: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
fc80: 61 73 73 65 64 20 74 6f 20 61 6e 20 61 75 78 69  assed to an auxi
fc90: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 63  liary function c
fca0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 70 6f 69  allback is a poi
fcb0: 6e 74 65 72 0a 74 6f 20 61 20 73 74 72 75 63 74  nter.to a struct
fcc0: 75 72 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6d  ure containing m
fcd0: 65 74 68 6f 64 73 20 74 68 61 74 20 6d 61 79 20  ethods that may 
fce0: 62 65 20 69 6e 76 6f 6b 65 64 20 69 6e 20 6f 72  be invoked in or
fcf0: 64 65 72 20 74 6f 20 6f 62 74 61 69 6e 0a 69 6e  der to obtain.in
fd00: 66 6f 72 6d 61 74 69 6f 6e 20 72 65 67 61 72 64  formation regard
fd10: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
fd20: 71 75 65 72 79 20 6f 72 20 72 6f 77 2e 20 54 68  query or row. Th
fd30: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fd40: 74 20 69 73 20 61 6e 0a 6f 70 61 71 75 65 20 68  t is an.opaque h
fd50: 61 6e 64 6c 65 20 74 68 61 74 20 73 68 6f 75 6c  andle that shoul
fd60: 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
fd70: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fd80: 74 20 74 6f 20 61 6e 79 20 73 75 63 68 20 6d 65  t to any such me
fd90: 74 68 6f 64 20 0a 69 6e 76 6f 63 61 74 69 6f 6e  thod .invocation
fda0: 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  . For example, t
fdb0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 75 78  he following aux
fdc0: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20  iliary function 
fdd0: 64 65 66 69 6e 69 74 69 6f 6e 20 72 65 74 75 72  definition retur
fde0: 6e 73 0a 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns.the total num
fdf0: 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e  ber of tokens in
fe00: 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20 6f 66 20   all columns of 
fe10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 3a  the current row:
fe20: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 3c 69  ..<codeblock>.<i
fe30: 3e 2f 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  >/*.** Implement
fe40: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 75 78 69  ation of an auxi
fe50: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 74  liary function t
fe60: 68 61 74 20 72 65 74 75 72 6e 73 20 74 68 65 20  hat returns the 
fe70: 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 6f 6b  number.** of tok
fe80: 65 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ens in the curre
fe90: 6e 74 20 72 6f 77 20 28 69 6e 63 6c 75 64 69 6e  nt row (includin
fea0: 67 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 29 2e 0a  g all columns)..
feb0: 2a 2f 3c 2f 69 3e 0a 73 74 61 74 69 63 20 76 6f  */</i>.static vo
fec0: 69 64 20 63 6f 6c 75 6d 6e 5f 73 69 7a 65 5f 69  id column_size_i
fed0: 6d 70 28 0a 20 20 63 6f 6e 73 74 20 46 74 73 35  mp(.  const Fts5
fee0: 45 78 74 65 6e 73 69 6f 6e 41 70 69 20 2a 70 41  ExtensionApi *pA
fef0: 70 69 2c 0a 20 20 46 74 73 35 43 6f 6e 74 65 78  pi,.  Fts5Contex
ff00: 74 20 2a 70 46 74 73 2c 0a 20 20 73 71 6c 69 74  t *pFts,.  sqlit
ff10: 65 33 5f 63 6f 6e 74 65 78 74 20 2a 70 43 74 78  e3_context *pCtx
ff20: 2c 0a 20 20 69 6e 74 20 6e 56 61 6c 2c 0a 20 20  ,.  int nVal,.  
ff30: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
ff40: 61 70 56 61 6c 0a 29 7b 0a 20 20 69 6e 74 20 72  apVal.){.  int r
ff50: 63 3b 0a 20 20 69 6e 74 20 6e 54 6f 6b 65 6e 3b  c;.  int nToken;
ff60: 0a 20 20 72 63 20 3d 20 70 41 70 69 2d 3e 78 43  .  rc = pApi->xC
ff70: 6f 6c 75 6d 6e 53 69 7a 65 28 70 46 74 73 2c 20  olumnSize(pFts, 
ff80: 2d 31 2c 20 26 6e 54 6f 6b 65 6e 29 3b 0a 20 20  -1, &nToken);.  
ff90: 69 66 28 20 72 63 3d 3d 53 51 4c 49 54 45 5f 4f  if( rc==SQLITE_O
ffa0: 4b 20 29 7b 0a 20 20 20 20 73 71 6c 69 74 65 33  K ){.    sqlite3
ffb0: 5f 72 65 73 75 6c 74 5f 69 6e 74 28 70 43 74 78  _result_int(pCtx
ffc0: 2c 20 6e 54 6f 6b 65 6e 29 3b 0a 20 20 7d 65 6c  , nToken);.  }el
ffd0: 73 65 7b 0a 20 20 20 20 73 71 6c 69 74 65 33 5f  se{.    sqlite3_
ffe0: 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
fff0: 65 28 70 43 74 78 2c 20 72 63 29 3b 0a 20 20 7d  e(pCtx, rc);.  }
10000 0a 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  .}.</codeblock>.
10010 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .<p>The followin
10020 67 20 73 65 63 74 69 6f 6e 20 64 65 73 63 72 69  g section descri
10030 62 65 73 20 74 68 65 20 41 50 49 20 6f 66 66 65  bes the API offe
10040 72 65 64 20 74 6f 20 61 75 78 69 6c 69 61 72 79  red to auxiliary
10050 20 66 75 6e 63 74 69 6f 6e 0a 69 6d 70 6c 65 6d   function.implem
10060 65 6e 74 61 74 69 6f 6e 73 20 69 6e 20 64 65 74  entations in det
10070 61 69 6c 2e 20 46 75 72 74 68 65 72 20 65 78 61  ail. Further exa
10080 6d 70 6c 65 73 20 6d 61 79 20 62 65 20 66 6f 75  mples may be fou
10090 6e 64 20 69 6e 20 74 68 65 20 22 66 74 73 35 5f  nd in the "fts5_
100a0 61 75 78 2e 63 22 0a 66 69 6c 65 20 6f 66 20 74  aux.c".file of t
100b0 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 0a  he source code..
100c0 0a 3c 68 33 20 74 61 67 73 3d 22 63 75 73 74 6f  .<h3 tags="custo
100d0 6d 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  m auxiliary func
100e0 74 69 6f 6e 73 22 3e 0a 20 20 43 75 73 74 6f 6d  tions">.  Custom
100f0 20 41 75 78 69 6c 69 61 72 79 20 46 75 6e 63 74   Auxiliary Funct
10100 69 6f 6e 73 20 41 50 49 20 52 65 66 65 72 65 6e  ions API Referen
10110 63 65 0a 3c 2f 68 33 3e 0a 0a 3c 63 6f 64 65 62  ce.</h3>..<codeb
10120 6c 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72 69 70 74  lock>.<tclscript
10130 3e 0a 20 20 73 65 74 20 72 65 73 20 22 22 0a 20  >.  set res "". 
10140 20 73 65 74 20 3a 3a 65 78 74 72 61 63 74 5f 61   set ::extract_a
10150 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 46 74 73  pi_docs_mode Fts
10160 35 45 78 74 65 6e 73 69 6f 6e 41 70 69 0a 20 20  5ExtensionApi.  
10170 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20  catch { set res 
10180 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f  [source [file jo
10190 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74  in $::SRC ext/ft
101a0 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64  s5/extract_api_d
101b0 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65  ocs.tcl]] }.  se
101c0 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70  t res.</tclscrip
101d0 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t>.</codeblock>.
101e0 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73  .<tclscript>.  s
101f0 65 74 20 72 65 73 20 22 22 0a 20 20 75 6e 73 65  et res "".  unse
10200 74 20 2d 6e 6f 63 6f 6d 70 6c 61 69 6e 20 3a 3a  t -nocomplain ::
10210 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73  extract_api_docs
10220 5f 6d 6f 64 65 20 0a 20 20 63 61 74 63 68 20 7b  _mode .  catch {
10230 20 73 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65   set res [source
10240 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53   [file join $::S
10250 52 43 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72  RC ext/fts5/extr
10260 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c  act_api_docs.tcl
10270 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c  ]] }.  set res.<
10280 2f 74 63 6c 73 63 72 69 70 74 3e 0a 0a 3c 68 31  /tclscript>..<h1
10290 20 74 61 67 73 3d 22 66 74 73 35 76 6f 63 61 62   tags="fts5vocab
102a0 22 3e 54 68 65 20 66 74 73 35 76 6f 63 61 62 20  ">The fts5vocab 
102b0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4d 6f  Virtual Table Mo
102c0 64 75 6c 65 3c 2f 68 31 3e 0a 0a 3c 70 3e 20 54  dule</h1>..<p> T
102d0 68 65 20 66 74 73 35 76 6f 63 61 62 20 76 69 72  he fts5vocab vir
102e0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
102f0 65 20 61 6c 6c 6f 77 73 20 75 73 65 72 73 20 74  e allows users t
10300 6f 20 65 78 74 72 61 63 74 20 69 6e 66 6f 72 6d  o extract inform
10310 61 74 69 6f 6e 20 66 72 6f 6d 0a 61 6e 20 46 54  ation from.an FT
10320 53 35 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  S5 full-text ind
10330 65 78 20 64 69 72 65 63 74 6c 79 2e 20 54 68 65  ex directly. The
10340 20 66 74 73 35 76 6f 63 61 62 20 6d 6f 64 75 6c   fts5vocab modul
10350 65 20 69 73 20 61 20 70 61 72 74 20 6f 66 20 46  e is a part of F
10360 54 53 35 20 2d 20 69 74 20 0a 69 73 20 61 76 61  TS5 - it .is ava
10370 69 6c 61 62 6c 65 20 77 68 65 6e 65 76 65 72 20  ilable whenever 
10380 46 54 53 35 20 69 73 2e 0a 0a 3c 70 3e 20 45 61  FTS5 is...<p> Ea
10390 63 68 20 66 74 73 35 76 6f 63 61 62 20 74 61 62  ch fts5vocab tab
103a0 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
103b0 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 46   with a single F
103c0 54 53 35 20 74 61 62 6c 65 2e 20 41 6e 20 66 74  TS5 table. An ft
103d0 73 35 76 6f 63 61 62 0a 74 61 62 6c 65 20 69 73  s5vocab.table is
103e0 20 75 73 75 61 6c 6c 79 20 63 72 65 61 74 65 64   usually created
103f0 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
10400 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 69 6e 20  wo arguments in 
10410 70 6c 61 63 65 20 6f 66 20 63 6f 6c 75 6d 6e 20  place of column 
10420 6e 61 6d 65 73 0a 69 6e 20 74 68 65 20 43 52 45  names.in the CRE
10430 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
10440 45 20 73 74 61 74 65 6d 65 6e 74 20 2d 20 74 68  E statement - th
10450 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 73  e name of the as
10460 73 6f 63 69 61 74 65 64 20 46 54 53 35 20 74 61  sociated FTS5 ta
10470 62 6c 65 0a 61 6e 64 20 74 68 65 20 74 79 70 65  ble.and the type
10480 20 6f 66 20 66 74 73 35 76 6f 63 61 62 20 74 61   of fts5vocab ta
10490 62 6c 65 2e 20 43 75 72 72 65 6e 74 6c 79 20 74  ble. Currently t
104a0 68 65 72 65 20 61 72 65 20 74 77 6f 20 74 79 70  here are two typ
104b0 65 73 20 6f 66 20 66 74 73 35 76 6f 63 61 62 0a  es of fts5vocab.
104c0 74 61 62 6c 65 2c 20 22 72 6f 77 22 20 61 6e 64  table, "row" and
104d0 20 22 63 6f 6c 22 2e 20 55 6e 6c 65 73 73 20 74   "col". Unless t
104e0 68 65 20 66 74 73 35 76 6f 63 61 62 20 74 61 62  he fts5vocab tab
104f0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 77 69  le is created wi
10500 74 68 69 6e 20 74 68 65 20 22 74 65 6d 70 22 0a  thin the "temp".
10510 64 61 74 61 62 61 73 65 2c 20 69 74 20 6d 75 73  database, it mus
10520 74 20 62 65 20 70 61 72 74 20 6f 66 20 74 68 65  t be part of the
10530 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
10540 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
10550 20 46 54 53 35 20 74 61 62 6c 65 2e 0a 0a 3c 63   FTS5 table...<c
10560 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d  odeblock>.  <i>-
10570 2d 20 43 72 65 61 74 65 20 61 6e 20 66 74 73 35  - Create an fts5
10580 76 6f 63 61 62 20 22 72 6f 77 22 20 74 61 62 6c  vocab "row" tabl
10590 65 20 74 6f 20 71 75 65 72 79 20 74 68 65 20 66  e to query the f
105a0 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 62  ull-text index b
105b0 65 6c 6f 6e 67 69 6e 67 0a 20 20 2d 2d 20 74 6f  elonging.  -- to
105c0 20 46 54 53 35 20 74 61 62 6c 65 20 22 66 74 31   FTS5 table "ft1
105d0 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  ".</i>.  CREATE 
105e0 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
105f0 31 5f 76 20 55 53 49 4e 47 20 66 74 73 35 76 6f  1_v USING fts5vo
10600 63 61 62 28 27 66 74 31 27 2c 20 27 72 6f 77 27  cab('ft1', 'row'
10610 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61  );..  <i>-- Crea
10620 74 65 20 61 6e 20 66 74 73 35 76 6f 63 61 62 20  te an fts5vocab 
10630 22 63 6f 6c 22 20 74 61 62 6c 65 20 74 6f 20 71  "col" table to q
10640 75 65 72 79 20 74 68 65 20 66 75 6c 6c 2d 74 65  uery the full-te
10650 78 74 20 69 6e 64 65 78 20 62 65 6c 6f 6e 67 69  xt index belongi
10660 6e 67 0a 20 20 2d 2d 20 74 6f 20 46 54 53 35 20  ng.  -- to FTS5 
10670 74 61 62 6c 65 20 22 66 74 32 22 2e 3c 2f 69 3e  table "ft2".</i>
10680 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
10690 4c 20 54 41 42 4c 45 20 66 74 32 5f 76 20 55 53  L TABLE ft2_v US
106a0 49 4e 47 20 66 74 73 35 76 6f 63 61 62 28 66 74  ING fts5vocab(ft
106b0 32 2c 20 63 6f 6c 29 3b 0a 3c 2f 63 6f 64 65 62  2, col);.</codeb
106c0 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 66 20 61 6e  lock>..<p> If an
106d0 20 66 74 73 35 76 6f 63 61 62 20 74 61 62 6c 65   fts5vocab table
106e0 20 69 73 20 63 72 65 61 74 65 64 20 69 6e 20 74   is created in t
106f0 68 65 20 74 65 6d 70 20 64 61 74 61 62 61 73 65  he temp database
10700 2c 20 69 74 20 6d 61 79 20 62 65 20 61 73 73 6f  , it may be asso
10710 63 69 61 74 65 64 0a 77 69 74 68 20 61 6e 20 46  ciated.with an F
10720 54 53 35 20 74 61 62 6c 65 20 69 6e 20 61 6e 79  TS5 table in any
10730 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
10740 73 65 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  se. In order to 
10750 61 74 74 61 63 68 20 74 68 65 20 66 74 73 35 76  attach the fts5v
10760 6f 63 61 62 0a 74 61 62 6c 65 20 74 6f 20 61 6e  ocab.table to an
10770 20 46 54 53 35 20 74 61 62 6c 65 20 6c 6f 63 61   FTS5 table loca
10780 74 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  ted in a databas
10790 65 20 6f 74 68 65 72 20 74 68 61 6e 20 22 74 65  e other than "te
107a0 6d 70 22 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  mp", the name of
107b0 20 74 68 65 0a 64 61 74 61 62 61 73 65 20 69 73   the.database is
107c0 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
107d0 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20   the FTS5 table 
107e0 6e 61 6d 65 20 69 6e 20 74 68 65 20 43 52 45 41  name in the CREA
107f0 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
10800 20 0a 61 72 67 75 6d 65 6e 74 73 2e 20 46 6f 72   .arguments. For
10810 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
10820 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43  block>.  <i>-- C
10830 72 65 61 74 65 20 61 6e 20 66 74 73 35 76 6f 63  reate an fts5voc
10840 61 62 20 22 72 6f 77 22 20 74 61 62 6c 65 20 74  ab "row" table t
10850 6f 20 71 75 65 72 79 20 74 68 65 20 66 75 6c 6c  o query the full
10860 2d 74 65 78 74 20 69 6e 64 65 78 20 62 65 6c 6f  -text index belo
10870 6e 67 69 6e 67 0a 20 20 2d 2d 20 74 6f 20 46 54  nging.  -- to FT
10880 53 35 20 74 61 62 6c 65 20 22 66 74 31 22 20 69  S5 table "ft1" i
10890 6e 20 64 61 74 61 62 61 73 65 20 22 6d 61 69 6e  n database "main
108a0 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  ".</i>.  CREATE 
108b0 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 65  VIRTUAL TABLE te
108c0 6d 70 2e 66 74 31 5f 76 20 55 53 49 4e 47 20 66  mp.ft1_v USING f
108d0 74 73 35 76 6f 63 61 62 28 6d 61 69 6e 2c 20 27  ts5vocab(main, '
108e0 66 74 31 27 2c 20 27 72 6f 77 27 29 3b 0a 0a 20  ft1', 'row');.. 
108f0 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e   <i>-- Create an
10900 20 66 74 73 35 76 6f 63 61 62 20 22 63 6f 6c 22   fts5vocab "col"
10910 20 74 61 62 6c 65 20 74 6f 20 71 75 65 72 79 20   table to query 
10920 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  the full-text in
10930 64 65 78 20 62 65 6c 6f 6e 67 69 6e 67 0a 20 20  dex belonging.  
10940 2d 2d 20 74 6f 20 46 54 53 35 20 74 61 62 6c 65  -- to FTS5 table
10950 20 22 66 74 32 22 20 69 6e 20 61 74 74 61 63 68   "ft2" in attach
10960 65 64 20 64 61 74 61 62 61 73 65 20 22 61 75 78  ed database "aux
10970 22 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  ".</i>.  CREATE 
10980 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 65  VIRTUAL TABLE te
10990 6d 70 2e 66 74 32 5f 76 20 55 53 49 4e 47 20 66  mp.ft2_v USING f
109a0 74 73 35 76 6f 63 61 62 28 27 61 75 78 27 2c 20  ts5vocab('aux', 
109b0 66 74 32 2c 20 63 6f 6c 29 3b 0a 3c 2f 63 6f 64  ft2, col);.</cod
109c0 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 53 70 65  eblock>..<p> Spe
109d0 63 69 66 79 69 6e 67 20 74 68 72 65 65 20 61 72  cifying three ar
109e0 67 75 6d 65 6e 74 73 20 77 68 65 6e 20 63 72 65  guments when cre
109f0 61 74 69 6e 67 20 61 6e 20 66 74 73 35 76 6f 63  ating an fts5voc
10a00 61 62 20 74 61 62 6c 65 20 69 6e 20 61 6e 79 20  ab table in any 
10a10 64 61 74 61 62 61 73 65 0a 6f 74 68 65 72 20 74  database.other t
10a20 68 61 6e 20 22 74 65 6d 70 22 20 72 65 73 75 6c  han "temp" resul
10a30 74 73 20 69 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  ts in an error..
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 72 6f 77 22 20 63 6f 6e 74 61 69 6e 73 20 6f  "row" 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 0a 69 6e  distinct term.in
10a90 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
10aa0 46 54 53 35 20 74 61 62 6c 65 2e 20 54 68 65 20  FTS5 table. The 
10ab0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 73 20 61 72  table columns ar
10ac0 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c  e as follows:..<
10ad0 74 61 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e  table striped=1>
10ae0 0a 20 20 3c 74 72 3e 3c 74 68 3e 43 6f 6c 75 6d  .  <tr><th>Colum
10af0 6e 3c 74 68 3e 43 6f 6e 74 65 6e 74 73 0a 20 20  n<th>Contents.  
10b00 3c 74 72 3e 3c 74 64 3e 74 65 72 6d 3c 74 64 3e  <tr><td>term<td>
10b10 20 54 68 65 20 74 65 72 6d 2c 20 61 73 20 73 74   The term, as st
10b20 6f 72 65 64 20 69 6e 20 74 68 65 20 46 54 53 35  ored in the FTS5
10b30 20 69 6e 64 65 78 2e 0a 20 20 3c 74 72 3e 3c 74   index..  <tr><t
10b40 64 3e 64 6f 63 3c 74 64 3e 20 20 54 68 65 20 6e  d>doc<td>  The n
10b50 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 74 68  umber of rows th
10b60 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65  at contain at le
10b70 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63 65  ast one instance
10b80 20 6f 66 20 74 68 65 20 74 65 72 6d 2e 0a 20 20   of the term..  
10b90 3c 74 72 3e 3c 74 64 3e 63 6e 74 3c 74 64 3e 20  <tr><td>cnt<td> 
10ba0 20 54 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   The total numbe
10bb0 72 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20 6f  r of instances o
10bc0 66 20 74 68 65 20 74 65 72 6d 20 69 6e 20 74 68  f the term in th
10bd0 65 20 65 6e 74 69 72 65 20 46 54 53 35 20 74 61  e entire FTS5 ta
10be0 62 6c 65 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c  ble..</table>..<
10bf0 70 3e 20 41 6e 20 66 74 73 35 76 6f 63 61 62 20  p> An fts5vocab 
10c00 74 61 62 6c 65 20 6f 66 20 74 79 70 65 20 22 63  table of type "c
10c10 6f 6c 22 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  ol" contains one
10c20 20 72 6f 77 20 66 6f 72 20 65 61 63 68 20 64 69   row for each di
10c30 73 74 69 6e 63 74 20 74 65 72 6d 2f 63 6f 6c 75  stinct term/colu
10c40 6d 6e 0a 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 69  mn.combination i
10c50 6e 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  n the associated
10c60 20 46 54 53 35 20 74 61 62 6c 65 2e 20 54 61 62   FTS5 table. Tab
10c70 6c 65 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 61  le columns are a
10c80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 74 61 62  s follows:..<tab
10c90 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20  le striped=1>.  
10ca0 3c 74 72 3e 3c 74 68 3e 43 6f 6c 75 6d 6e 3c 74  <tr><th>Column<t
10cb0 68 3e 43 6f 6e 74 65 6e 74 73 0a 20 20 3c 74 72  h>Contents.  <tr
10cc0 3e 3c 74 64 3e 74 65 72 6d 3c 74 64 3e 20 54 68  ><td>term<td> Th
10cd0 65 20 74 65 72 6d 2c 20 61 73 20 73 74 6f 72 65  e term, as store
10ce0 64 20 69 6e 20 74 68 65 20 46 54 53 35 20 69 6e  d in the FTS5 in
10cf0 64 65 78 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 63  dex..  <tr><td>c
10d00 6f 6c 3c 74 64 3e 20 20 54 68 65 20 6e 61 6d 65  ol<td>  The name
10d10 20 6f 66 20 74 68 65 20 46 54 53 35 20 74 61 62   of the FTS5 tab
10d20 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 63  le column that c
10d30 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 72 6d  ontains the term
10d40 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 64 6f 63 3c  ..  <tr><td>doc<
10d50 74 64 3e 20 20 54 68 65 20 6e 75 6d 62 65 72 20  td>  The number 
10d60 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 20 46  of rows in the F
10d70 54 53 35 20 74 61 62 6c 65 20 66 6f 72 20 77 68  TS5 table for wh
10d80 69 63 68 20 63 6f 6c 75 6d 6e 20 24 63 6f 6c 0a  ich column $col.
10d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
10da0 20 20 20 63 6f 6e 74 61 69 6e 73 20 61 74 20 6c     contains at l
10db0 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63  east one instanc
10dc0 65 20 6f 66 20 74 68 65 20 74 65 72 6d 2e 0a 20  e of the term.. 
10dd0 20 3c 74 72 3e 3c 74 64 3e 63 6e 74 3c 74 64 3e   <tr><td>cnt<td>
10de0 20 20 54 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62    The total numb
10df0 65 72 20 6f 66 20 69 6e 73 74 61 6e 63 65 73 20  er of instances 
10e00 6f 66 20 74 68 65 20 74 65 72 6d 20 74 68 61 74  of the term that
10e10 20 61 70 70 65 61 72 20 69 6e 0a 20 20 20 20 20   appear in.     
10e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 6f                co
10e30 6c 75 6d 6e 20 24 63 6f 6c 20 6f 66 20 74 68 65  lumn $col of the
10e40 20 46 54 53 35 20 74 61 62 6c 65 20 28 63 6f 6e   FTS5 table (con
10e50 73 69 64 65 72 69 6e 67 20 61 6c 6c 20 72 6f 77  sidering all row
10e60 73 29 2e 20 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c  s). .</table>..<
10e70 70 3e 45 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  p>Example:..<cod
10e80 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
10e90 41 73 73 75 6d 69 6e 67 20 61 20 64 61 74 61 62  Assuming a datab
10ea0 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
10eb0 67 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  g:</i>.  CREATE 
10ec0 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
10ed0 31 20 55 53 49 4e 47 20 66 74 73 35 28 63 31 2c  1 USING fts5(c1,
10ee0 20 63 32 29 3b 0a 20 20 49 4e 53 45 52 54 20 49   c2);.  INSERT I
10ef0 4e 54 4f 20 66 74 31 20 56 41 4c 55 45 53 28 27  NTO ft1 VALUES('
10f00 61 70 70 6c 65 20 62 61 6e 61 6e 61 20 63 68 65  apple banana che
10f10 72 72 79 27 2c 20 27 62 61 6e 61 6e 61 20 62 61  rry', 'banana ba
10f20 6e 61 6e 61 20 63 68 65 72 72 79 27 29 3b 0a 20  nana cherry');. 
10f30 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 31   INSERT INTO ft1
10f40 20 56 41 4c 55 45 53 28 27 63 68 65 72 72 79 20   VALUES('cherry 
10f50 63 68 65 72 72 79 20 63 68 65 72 72 79 27 2c 20  cherry cherry', 
10f60 27 64 61 74 65 20 64 61 74 65 20 64 61 74 65 27  'date date date'
10f70 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 6e  );..  <i>-- Then
10f80 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 66 6f   querying the fo
10f90 6c 6c 6f 77 69 6e 67 20 66 74 73 35 76 6f 63 61  llowing fts5voca
10fa0 62 20 74 61 62 6c 65 20 28 74 79 70 65 20 22 63  b table (type "c
10fb0 6f 6c 22 29 20 72 65 74 75 72 6e 73 3a 0a 20 20  ol") returns:.  
10fc0 2d 2d 0a 20 20 2d 2d 20 20 20 20 61 70 70 6c 65  --.  --    apple
10fd0 20 20 7c 20 63 31 20 7c 20 31 20 7c 20 31 0a 20    | c1 | 1 | 1. 
10fe0 20 2d 2d 20 20 20 20 62 61 6e 61 6e 61 20 7c 20   --    banana | 
10ff0 63 31 20 7c 20 31 20 7c 20 31 0a 20 20 2d 2d 20  c1 | 1 | 1.  -- 
11000 20 20 20 62 61 6e 61 6e 61 20 7c 20 63 32 20 7c     banana | c2 |
11010 20 31 20 7c 20 32 0a 20 20 2d 2d 20 20 20 20 63   1 | 2.  --    c
11020 68 65 72 72 79 20 7c 20 63 31 20 7c 20 32 20 7c  herry | c1 | 2 |
11030 20 34 0a 20 20 2d 2d 20 20 20 20 63 68 65 72 72   4.  --    cherr
11040 79 20 7c 20 63 32 20 7c 20 31 20 7c 20 31 0a 20  y | c2 | 1 | 1. 
11050 20 2d 2d 20 20 20 20 64 61 74 65 20 20 20 7c 20   --    date   | 
11060 63 33 20 7c 20 31 20 7c 20 33 0a 20 20 2d 2d 3c  c3 | 1 | 3.  --<
11070 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52  /i>.  CREATE VIR
11080 54 55 41 4c 20 54 41 42 4c 45 20 66 74 31 5f 76  TUAL TABLE ft1_v
11090 5f 63 6f 6c 20 55 53 49 4e 47 20 66 74 73 35 76  _col USING fts5v
110a0 6f 63 61 62 28 66 74 31 2c 20 63 6f 6c 29 3b 0a  ocab(ft1, col);.
110b0 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72 79 69 6e  .  <i>-- Queryin
110c0 67 20 61 6e 20 66 74 73 35 76 6f 63 61 62 20 74  g an fts5vocab t
110d0 61 62 6c 65 20 6f 66 20 74 79 70 65 20 22 72 6f  able of type "ro
110e0 77 22 20 72 65 74 75 72 6e 73 3a 0a 20 20 2d 2d  w" returns:.  --
110f0 0a 20 20 2d 2d 20 20 20 20 61 70 70 6c 65 20 20  .  --    apple  
11100 7c 20 31 20 7c 20 31 0a 20 20 2d 2d 20 20 20 20  | 1 | 1.  --    
11110 62 61 6e 61 6e 61 20 7c 20 31 20 7c 20 33 0a 20  banana | 1 | 3. 
11120 20 2d 2d 20 20 20 20 63 68 65 72 72 79 20 7c 20   --    cherry | 
11130 32 20 7c 20 35 0a 20 20 2d 2d 20 20 20 20 64 61  2 | 5.  --    da
11140 74 65 20 20 20 7c 20 31 20 7c 20 33 0a 20 20 2d  te   | 1 | 3.  -
11150 2d 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  -</i>.  CREATE V
11160 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 31  IRTUAL TABLE ft1
11170 5f 76 5f 72 6f 77 20 55 53 49 4e 47 20 66 74 73  _v_row USING fts
11180 35 76 6f 63 61 62 28 66 74 31 2c 20 72 6f 77 29  5vocab(ft1, row)
11190 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
111a0 0a 3c 68 31 20 69 64 3d 61 70 70 65 6e 64 69 78  .<h1 id=appendix
111b0 5f 61 20 6e 6f 6e 75 6d 62 65 72 20 74 61 67 73  _a nonumber tags
111c0 3d 22 63 6f 6d 70 61 72 69 73 6f 6e 20 77 69 74  ="comparison wit
111d0 68 20 66 74 73 34 22 3e 0a 20 20 41 70 70 65 6e  h fts4">.  Appen
111e0 64 69 78 20 41 3a 20 43 6f 6d 70 61 72 69 73 6f  dix A: Compariso
111f0 6e 20 77 69 74 68 20 46 54 53 33 2f 34 0a 3c 2f  n with FTS3/4.</
11200 68 31 3e 0a 0a 3c 70 3e 20 41 6c 73 6f 20 61 76  h1>..<p> Also av
11210 61 69 6c 61 62 6c 65 20 69 73 20 74 68 65 20 73  ailable is the s
11220 69 6d 69 6c 61 72 20 62 75 74 20 6d 6f 72 65 20  imilar but more 
11230 6d 61 74 75 72 65 20 5b 66 74 73 33 20 7c 20 46  mature [fts3 | F
11240 54 53 33 2f 34 5d 20 6d 6f 64 75 6c 65 2e 20 0a  TS3/4] module. .
11250 46 54 53 35 20 69 73 20 61 20 6e 65 77 20 76 65  FTS5 is a new ve
11260 72 73 69 6f 6e 20 6f 66 20 46 54 53 34 20 74 68  rsion of FTS4 th
11270 61 74 20 69 6e 63 6c 75 64 65 73 20 76 61 72 69  at includes vari
11280 6f 75 73 20 66 69 78 65 73 20 61 6e 64 20 73 6f  ous fixes and so
11290 6c 75 74 69 6f 6e 73 20 66 6f 72 20 0a 70 72 6f  lutions for .pro
112a0 62 6c 65 6d 73 20 74 68 61 74 20 63 6f 75 6c 64  blems that could
112b0 20 6e 6f 74 20 62 65 20 66 69 78 65 64 20 69 6e   not be fixed in
112c0 20 46 54 53 34 20 77 69 74 68 6f 75 74 20 73 61   FTS4 without sa
112d0 63 72 69 66 69 63 69 6e 67 20 62 61 63 6b 77 61  crificing backwa
112e0 72 64 73 20 0a 63 6f 6d 70 61 74 69 62 69 6c 69  rds .compatibili
112f0 74 79 2e 20 53 6f 6d 65 20 6f 66 20 74 68 65 73  ty. Some of thes
11300 65 20 70 72 6f 62 6c 65 6d 73 20 61 72 65 20 0a  e problems are .
11310 5b 66 74 73 35 20 74 65 63 68 6e 69 63 61 6c 20  [fts5 technical 
11320 64 69 66 66 65 72 65 6e 63 65 73 20 7c 20 64 65  differences | de
11330 73 63 72 69 62 65 64 20 62 65 6c 6f 77 5d 2e 0a  scribed below]..
11340 0a 3c 68 32 20 6e 6f 6e 75 6d 62 65 72 3e 20 41  .<h2 nonumber> A
11350 70 70 6c 69 63 61 74 69 6f 6e 20 50 6f 72 74 69  pplication Porti
11360 6e 67 20 47 75 69 64 65 20 3c 2f 68 32 3e 0a 0a  ng Guide </h2>..
11370 3c 70 3e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  <p> In order to 
11380 75 73 65 20 46 54 53 35 20 69 6e 73 74 65 61 64  use FTS5 instead
11390 20 6f 66 20 46 54 53 33 20 6f 72 20 46 54 53 34   of FTS3 or FTS4
113a0 2c 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  , applications u
113b0 73 75 61 6c 6c 79 20 72 65 71 75 69 72 65 0a 6d  sually require.m
113c0 69 6e 69 6d 61 6c 20 6d 6f 64 69 66 69 63 61 74  inimal modificat
113d0 69 6f 6e 73 2e 20 4d 6f 73 74 20 6f 66 20 74 68  ions. Most of th
113e0 65 73 65 20 66 61 6c 6c 20 69 6e 74 6f 20 74 68  ese fall into th
113f0 72 65 65 20 63 61 74 65 67 6f 72 69 65 73 20 2d  ree categories -
11400 20 63 68 61 6e 67 65 73 0a 72 65 71 75 69 72 65   changes.require
11410 64 20 74 6f 20 74 68 65 20 43 52 45 41 54 45 20  d to the CREATE 
11420 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
11430 61 74 65 6d 65 6e 74 20 75 73 65 64 20 74 6f 20  atement used to 
11440 63 72 65 61 74 65 20 74 68 65 20 46 54 53 20 74  create the FTS t
11450 61 62 6c 65 2c 0a 63 68 61 6e 67 65 73 20 72 65  able,.changes re
11460 71 75 69 72 65 64 20 74 6f 20 53 45 4c 45 43 54  quired to SELECT
11470 20 71 75 65 72 69 65 73 20 75 73 65 64 20 74 6f   queries used to
11480 20 65 78 65 63 75 74 65 20 71 75 65 72 69 65 73   execute queries
11490 20 61 67 61 69 6e 73 74 20 74 68 65 20 74 61 62   against the tab
114a0 6c 65 2c 0a 61 6e 64 20 63 68 61 6e 67 65 73 20  le,.and changes 
114b0 72 65 71 75 69 72 65 64 20 74 6f 20 61 70 70 6c  required to appl
114c0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
114d0 65 20 5b 46 54 53 20 61 75 78 69 6c 69 61 72 79  e [FTS auxiliary
114e0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 68   functions]...<h
114f0 33 20 6e 6f 6e 75 6d 62 65 72 3e 20 43 68 61 6e  3 nonumber> Chan
11500 67 65 73 20 74 6f 20 43 52 45 41 54 45 20 56 49  ges to CREATE VI
11510 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74  RTUAL TABLE stat
11520 65 6d 65 6e 74 73 20 3c 2f 68 33 3e 0a 0a 3c 6f  ements </h3>..<o
11530 6c 3e 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 6d  l>.<li> <p>The m
11540 6f 64 75 6c 65 20 6e 61 6d 65 20 6d 75 73 74 20  odule name must 
11550 62 65 20 63 68 61 6e 67 65 64 20 66 72 6f 6d 20  be changed from 
11560 22 66 74 73 33 22 20 6f 72 20 22 66 74 73 34 22  "fts3" or "fts4"
11570 20 74 6f 20 22 66 74 73 35 22 2e 0a 0a 3c 6c 69   to "fts5"...<li
11580 3e 20 3c 70 3e 41 6c 6c 20 74 79 70 65 20 69 6e  > <p>All type in
11590 66 6f 72 6d 61 74 69 6f 6e 20 6f 72 20 63 6f 6e  formation or con
115a0 73 74 72 61 69 6e 74 20 73 70 65 63 69 66 69 63  straint specific
115b0 61 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 72  ations must be r
115c0 65 6d 6f 76 65 64 20 66 72 6f 6d 0a 20 20 20 20  emoved from.    
115d0 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69   column definiti
115e0 6f 6e 73 2e 20 46 54 53 33 2f 34 20 69 67 6e 6f  ons. FTS3/4 igno
115f0 72 65 73 20 65 76 65 72 79 74 68 69 6e 67 20 66  res everything f
11600 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 6f 6c  ollowing the col
11610 75 6d 6e 20 6e 61 6d 65 20 69 6e 0a 20 20 20 20  umn name in.    
11620 20 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69   a column defini
11630 74 69 6f 6e 2c 20 46 54 53 35 20 61 74 74 65 6d  tion, FTS5 attem
11640 70 74 73 20 74 6f 20 70 61 72 73 65 20 69 74 20  pts to parse it 
11650 28 61 6e 64 20 77 69 6c 6c 20 72 65 70 6f 72 74  (and will report
11660 20 61 6e 20 65 72 72 6f 72 0a 20 20 20 20 20 69   an error.     i
11670 66 20 69 74 20 66 61 69 6c 73 20 74 6f 29 2e 0a  f it fails to)..
11680 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 22 6d 61  .<li> <p>The "ma
11690 74 63 68 69 6e 66 6f 3d 66 74 73 33 22 20 6f 70  tchinfo=fts3" op
116a0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 76 61 69  tion is not avai
116b0 6c 61 62 6c 65 2e 20 54 68 65 20 0a 20 20 20 20  lable. The .    
116c0 20 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 73 69 7a   [FTS5 columnsiz
116d0 65 20 6f 70 74 69 6f 6e 20 7c 20 22 63 6f 6c 75  e option | "colu
116e0 6d 6e 73 69 7a 65 3d 30 22 5d 20 6f 70 74 69 6f  mnsize=0"] optio
116f0 6e 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 2e  n is equivalent.
11700 0a 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 6e 6f  ..<li> <p>The no
11710 74 69 6e 64 65 78 65 64 3d 20 6f 70 74 69 6f 6e  tindexed= option
11720 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
11730 65 2e 20 41 64 64 69 6e 67 20 5b 75 6e 69 6e 64  e. Adding [unind
11740 65 78 65 64 20 7c 20 55 4e 49 4e 44 45 58 45 44  exed | UNINDEXED
11750 5d 0a 20 20 20 20 20 74 6f 20 74 68 65 20 63 6f  ].     to the co
11760 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20  lumn definition 
11770 69 73 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 0a  is equivalent...
11780 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 49 43 55 20  <li> <p>The ICU 
11790 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 6e 6f 74  tokenizer is not
117a0 20 61 76 61 69 6c 61 62 6c 65 2e 0a 0a 3c 6c 69   available...<li
117b0 3e 20 3c 70 3e 54 68 65 20 63 6f 6d 70 72 65 73  > <p>The compres
117c0 73 3d 2c 20 75 6e 63 6f 6d 70 72 65 73 73 3d 20  s=, uncompress= 
117d0 61 6e 64 20 6c 61 6e 67 75 61 67 65 69 64 3d 20  and languageid= 
117e0 6f 70 74 69 6f 6e 73 20 61 72 65 20 6e 6f 74 20  options are not 
117f0 61 76 61 69 6c 61 62 6c 65 2e 0a 20 20 20 20 20  available..     
11800 54 68 65 72 65 20 69 73 20 61 73 20 6f 66 20 79  There is as of y
11810 65 74 20 6e 6f 20 65 71 75 69 76 61 6c 65 6e 74  et no equivalent
11820 20 66 6f 72 20 74 68 65 69 72 20 66 75 6e 63 74   for their funct
11830 69 6f 6e 61 6c 69 74 79 2e 0a 3c 2f 6f 6c 3e 0a  ionality..</ol>.
11840 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c  .<codeblock>.  <
11850 69 3e 20 2d 2d 20 46 54 53 33 2f 34 20 73 74 61  i> -- FTS3/4 sta
11860 74 65 6d 65 6e 74 20 3c 2f 69 3e 0a 20 20 43 52  tement </i>.  CR
11870 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
11880 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 34  LE t1 USING fts4
11890 28 0a 20 20 20 20 6c 69 6e 6b 69 64 20 49 4e 54  (.    linkid INT
118a0 45 47 45 52 2c 0a 20 20 20 20 68 65 61 64 65 72  EGER,.    header
118b0 20 43 48 41 52 28 32 30 29 2c 0a 20 20 20 20 74   CHAR(20),.    t
118c0 65 78 74 20 56 41 52 43 48 41 52 2c 0a 20 20 20  ext VARCHAR,.   
118d0 20 6e 6f 74 69 6e 64 65 78 65 64 3d 6c 69 6e 6b   notindexed=link
118e0 69 64 2c 0a 20 20 20 20 6d 61 74 63 68 69 6e 66  id,.    matchinf
118f0 6f 3d 66 74 73 33 2c 0a 20 20 20 20 74 6f 6b 65  o=fts3,.    toke
11900 6e 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36 31 0a  nizer=unicode61.
11910 20 20 29 3b 0a 0a 20 20 3c 69 3e 20 2d 2d 20 46    );..  <i> -- F
11920 54 53 35 20 65 71 75 69 76 61 6c 65 6e 74 20 28  TS5 equivalent (
11930 6e 6f 74 65 20 2d 20 74 68 65 20 22 74 6f 6b 65  note - the "toke
11940 6e 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36 31 22  nizer=unicode61"
11950 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 3c 2f   option is not</
11960 69 3e 0a 20 20 3c 69 3e 20 2d 2d 20 72 65 71 75  i>.  <i> -- requ
11970 69 72 65 64 20 61 73 20 74 68 69 73 20 69 73 20  ired as this is 
11980 74 68 65 20 64 65 66 61 75 6c 74 20 66 6f 72 20  the default for 
11990 46 54 53 35 20 61 6e 79 77 61 79 29 3c 2f 69 3e  FTS5 anyway)</i>
119a0 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
119b0 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47  L TABLE t1 USING
119c0 20 66 74 73 35 28 0a 20 20 20 20 6c 69 6e 6b 69   fts5(.    linki
119d0 64 20 55 4e 49 4e 44 45 58 45 44 2c 0a 20 20 20  d UNINDEXED,.   
119e0 20 68 65 61 64 65 72 2c 0a 20 20 20 20 74 65 78   header,.    tex
119f0 74 2c 0a 20 20 20 20 63 6f 6c 75 6d 6e 73 69 7a  t,.    columnsiz
11a00 65 3d 30 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62  e=0.  );.</codeb
11a10 6c 6f 63 6b 3e 0a 0a 3c 68 33 20 6e 6f 6e 75 6d  lock>..<h3 nonum
11a20 62 65 72 3e 20 43 68 61 6e 67 65 73 20 74 6f 20  ber> Changes to 
11a30 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
11a40 73 20 3c 2f 68 33 3e 0a 0a 3c 6f 6c 3e 0a 20 20  s </h3>..<ol>.  
11a50 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 22 64 6f 63  <li> <p>The "doc
11a60 69 64 22 20 61 6c 69 61 73 20 64 6f 65 73 20 6e  id" alias does n
11a70 6f 74 20 65 78 69 73 74 2e 20 41 70 70 6c 69 63  ot exist. Applic
11a80 61 74 69 6f 6e 73 20 6d 75 73 74 20 75 73 65 20  ations must use 
11a90 22 72 6f 77 69 64 22 0a 20 20 20 20 20 20 20 20  "rowid".        
11aa0 20 20 69 6e 73 74 65 61 64 2e 0a 0a 20 20 3c 6c    instead...  <l
11ab0 69 3e 20 3c 70 3e 54 68 65 20 6c 65 66 74 20 68  i> <p>The left h
11ac0 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
11ad0 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 20 69  MATCH operator i
11ae0 6e 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 71 75  n a full-text qu
11af0 65 72 79 20 6d 75 73 74 20 62 65 0a 20 20 20 20  ery must be.    
11b00 20 20 20 20 20 20 74 68 65 20 74 61 62 6c 65 20        the table 
11b10 6e 61 6d 65 20 2d 20 6e 6f 74 20 61 6e 79 20 63  name - not any c
11b20 6f 6c 75 6d 6e 20 6e 61 6d 65 20 61 73 20 69 6e  olumn name as in
11b30 20 46 54 53 34 2e 0a 0a 20 20 3c 6c 69 3e 20 3c   FTS4...  <li> <
11b40 70 3e 54 68 65 20 46 54 53 20 71 75 65 72 79 20  p>The FTS query 
11b50 73 79 6e 74 61 78 20 28 72 69 67 68 74 20 68 61  syntax (right ha
11b60 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 4d  nd side of the M
11b70 41 54 43 48 20 6f 70 65 72 61 74 6f 72 29 20 68  ATCH operator) h
11b80 61 73 0a 20 20 20 20 20 20 20 20 20 20 63 68 61  as.          cha
11b90 6e 67 65 64 20 69 6e 20 73 6f 6d 65 20 77 61 79  nged in some way
11ba0 73 2e 20 54 68 65 20 46 54 53 35 20 73 79 6e 74  s. The FTS5 synt
11bb0 61 78 20 69 73 20 71 75 69 74 65 20 63 6c 6f 73  ax is quite clos
11bc0 65 20 74 6f 20 74 68 65 20 46 54 53 34 0a 20 20  e to the FTS4.  
11bd0 20 20 20 20 20 20 20 20 22 65 6e 68 61 6e 63 65          "enhance
11be0 64 20 73 79 6e 74 61 78 22 2e 20 54 68 65 20 6d  d syntax". The m
11bf0 61 69 6e 20 64 69 66 66 65 72 65 6e 63 65 20 69  ain difference i
11c00 73 20 74 68 61 74 20 46 54 53 35 20 69 73 20 66  s that FTS5 is f
11c10 75 73 73 69 65 72 20 0a 20 20 20 20 20 20 20 20  ussier .        
11c20 20 20 61 62 6f 75 74 20 75 6e 72 65 63 6f 67 6e    about unrecogn
11c30 69 7a 65 64 20 70 75 6e 63 74 75 61 74 69 6f 6e  ized punctuation
11c40 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 20   characters and 
11c50 73 69 6d 69 6c 61 72 20 77 69 74 68 69 6e 20 71  similar within q
11c60 75 65 72 79 0a 20 20 20 20 20 20 20 20 20 20 73  uery.          s
11c70 74 72 69 6e 67 73 2e 20 4d 6f 73 74 20 71 75 65  trings. Most que
11c80 72 69 65 73 20 74 68 61 74 20 77 6f 72 6b 20 77  ries that work w
11c90 69 74 68 20 46 54 53 33 2f 34 20 73 68 6f 75 6c  ith FTS3/4 shoul
11ca0 64 20 61 6c 73 6f 20 77 6f 72 6b 20 77 69 74 68  d also work with
11cb0 0a 20 20 20 20 20 20 20 20 20 20 46 54 53 35 2c  .          FTS5,
11cc0 20 61 6e 64 20 74 68 6f 73 65 20 74 68 61 74 20   and those that 
11cd0 64 6f 20 6e 6f 74 20 73 68 6f 75 6c 64 20 72 65  do not should re
11ce0 74 75 72 6e 20 70 61 72 73 65 20 65 72 72 6f 72  turn parse error
11cf0 73 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 63 6f 64 65 62  s..</ol>..<codeb
11d00 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 46 54  lock>.  <i>-- FT
11d10 53 33 2f 34 20 71 75 65 72 79 20 3c 2f 69 3e 0a  S3/4 query </i>.
11d20 20 20 53 45 4c 45 43 54 20 64 6f 63 69 64 20 46    SELECT docid F
11d30 52 4f 4d 20 74 31 20 57 48 45 52 45 20 74 65 78  ROM t1 WHERE tex
11d40 74 20 4d 41 54 43 48 20 27 74 6f 6b 65 6e 27 3b  t MATCH 'token';
11d50 0a 0a 20 20 3c 69 3e 2d 2d 20 46 54 53 35 20 65  ..  <i>-- FTS5 e
11d60 71 75 69 76 61 6c 65 6e 74 20 3c 2f 69 3e 0a 20  quivalent </i>. 
11d70 20 53 45 4c 45 43 54 20 72 6f 77 69 64 20 46 52   SELECT rowid FR
11d80 4f 4d 20 74 31 20 57 48 45 52 45 20 74 31 20 4d  OM t1 WHERE t1 M
11d90 41 54 43 48 20 27 74 65 78 74 3a 74 6f 6b 65 6e  ATCH 'text:token
11da0 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ';.</codeblock>.
11db0 0a 3c 68 33 20 6e 6f 6e 75 6d 62 65 72 3e 20 41  .<h3 nonumber> A
11dc0 75 78 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f  uxiliary Functio
11dd0 6e 20 43 68 61 6e 67 65 73 20 3c 2f 68 33 3e 0a  n Changes </h3>.
11de0 0a 3c 70 3e 20 46 54 53 35 20 68 61 73 20 6e 6f  .<p> FTS5 has no
11df0 20 6d 61 74 63 68 69 6e 66 6f 28 29 20 6f 72 20   matchinfo() or 
11e00 6f 66 66 73 65 74 73 28 29 20 66 75 6e 63 74 69  offsets() functi
11e10 6f 6e 2c 20 61 6e 64 20 74 68 65 20 73 6e 69 70  on, and the snip
11e20 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 0a 69  pet() function.i
11e30 73 20 6e 6f 74 20 61 73 20 66 75 6c 6c 79 2d 66  s not as fully-f
11e40 65 61 74 75 72 65 64 20 61 73 20 69 6e 20 46 54  eatured as in FT
11e50 53 33 2f 34 2e 20 48 6f 77 65 76 65 72 2c 20 73  S3/4. However, s
11e60 69 6e 63 65 20 46 54 53 35 20 64 6f 65 73 20 70  ince FTS5 does p
11e70 72 6f 76 69 64 65 20 0a 61 6e 20 41 50 49 20 61  rovide .an API a
11e80 6c 6c 6f 77 69 6e 67 20 61 70 70 6c 69 63 61 74  llowing applicat
11e90 69 6f 6e 73 20 74 6f 20 63 72 65 61 74 65 20 5b  ions to create [
11ea0 63 75 73 74 6f 6d 20 61 75 78 69 6c 69 61 72 79  custom auxiliary
11eb0 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 20 61 6e 79   functions], any
11ec0 0a 72 65 71 75 69 72 65 64 20 66 75 6e 63 74 69  .required functi
11ed0 6f 6e 61 6c 69 74 79 20 6d 61 79 20 62 65 20 69  onality may be i
11ee0 6d 70 6c 65 6d 65 6e 74 65 64 20 77 69 74 68 69  mplemented withi
11ef0 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
11f00 6e 20 63 6f 64 65 2e 0a 0a 3c 70 3e 20 54 68 65  n code...<p> The
11f10 20 73 65 74 20 6f 66 20 62 75 69 6c 74 2d 69 6e   set of built-in
11f20 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
11f30 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79  ions provided by
11f40 20 46 54 53 35 20 6d 61 79 20 62 65 20 0a 69 6d   FTS5 may be .im
11f50 70 72 6f 76 65 64 20 75 70 6f 6e 20 69 6e 20 74  proved upon in t
11f60 68 65 20 66 75 74 75 72 65 2e 0a 0a 3c 68 33 20  he future...<h3 
11f70 6e 6f 6e 75 6d 62 65 72 3e 20 4f 74 68 65 72 20  nonumber> Other 
11f80 49 73 73 75 65 73 3c 2f 68 33 3e 0a 0a 3c 6f 6c  Issues</h3>..<ol
11f90 3e 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20  >.  <li><p> The 
11fa0 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 70 72  functionality pr
11fb0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 74  ovided by the ft
11fc0 73 34 61 75 78 20 6d 6f 64 75 6c 65 20 69 73 20  s4aux module is 
11fd0 6e 6f 77 20 70 72 6f 76 69 64 65 64 0a 20 20 20  now provided.   
11fe0 20 20 20 20 20 20 20 62 79 20 5b 66 74 73 35 76         by [fts5v
11ff0 6f 63 61 62 5d 2e 20 54 68 65 20 73 63 68 65 6d  ocab]. The schem
12000 61 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 74  a of these two t
12010 61 62 6c 65 73 20 69 73 20 73 6c 69 67 68 74 6c  ables is slightl
12020 79 20 64 69 66 66 65 72 65 6e 74 2e 0a 0a 20 20  y different...  
12030 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 46 54 53 33  <li><p> The FTS3
12040 2f 34 20 22 6d 65 72 67 65 3d 58 2c 59 22 20 63  /4 "merge=X,Y" c
12050 6f 6d 6d 61 6e 64 20 68 61 73 20 62 65 65 6e 20  ommand has been 
12060 72 65 70 6c 61 63 65 64 20 62 79 20 74 68 65 20  replaced by the 
12070 0a 20 20 20 20 20 20 20 20 20 20 5b 46 54 53 35  .          [FTS5
12080 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64 5d 2e   merge command].
12090 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20  ..  <li><p> The 
120a0 46 54 53 33 2f 34 20 22 61 75 74 6f 6d 65 72 67  FTS3/4 "automerg
120b0 65 3d 58 22 20 63 6f 6d 6d 61 6e 64 20 68 61 73  e=X" command has
120c0 20 62 65 65 6e 20 72 65 70 6c 61 63 65 64 20 62   been replaced b
120d0 79 20 74 68 65 20 0a 20 20 20 20 20 20 20 20 20  y the .         
120e0 20 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65   [FTS5 automerge
120f0 20 6f 70 74 69 6f 6e 5d 2e 0a 3c 2f 6f 6c 3e 0a   option]..</ol>.
12100 0a 3c 68 32 20 6e 6f 6e 75 6d 62 65 72 20 74 61  .<h2 nonumber ta
12110 67 73 3d 22 66 74 73 35 20 74 65 63 68 6e 69 63  gs="fts5 technic
12120 61 6c 20 64 69 66 66 65 72 65 6e 63 65 73 22 3e  al differences">
12130 20 0a 20 20 53 75 6d 6d 61 72 79 20 6f 66 20 54   .  Summary of T
12140 65 63 68 6e 69 63 61 6c 20 44 69 66 66 65 72 65  echnical Differe
12150 6e 63 65 73 20 0a 3c 2f 68 32 3e 0a 0a 3c 70 3e  nces .</h2>..<p>
12160 46 54 53 35 20 69 73 20 73 69 6d 69 6c 61 72 20  FTS5 is similar 
12170 74 6f 20 46 54 53 33 2f 34 20 69 6e 20 74 68 61  to FTS3/4 in tha
12180 74 20 74 68 65 20 70 72 69 6d 61 72 79 20 74 61  t the primary ta
12190 73 6b 20 6f 66 20 65 61 63 68 20 69 73 20 74 6f  sk of each is to
121a0 20 6d 61 69 6e 74 61 69 6e 0a 61 6e 20 69 6e 64   maintain.an ind
121b0 65 78 20 6d 61 70 70 69 6e 67 20 66 72 6f 6d 20  ex mapping from 
121c0 65 61 63 68 20 75 6e 69 71 75 65 20 74 6f 6b 65  each unique toke
121d0 6e 20 74 6f 20 61 20 6c 69 73 74 20 6f 66 20 69  n to a list of i
121e0 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 61 74  nstances of that
121f0 20 74 6f 6b 65 6e 20 0a 77 69 74 68 69 6e 20 61   token .within a
12200 20 73 65 74 20 6f 66 20 64 6f 63 75 6d 65 6e 74   set of document
12210 73 2c 20 77 68 65 72 65 20 65 61 63 68 20 69 6e  s, where each in
12220 73 74 61 6e 63 65 20 69 73 20 69 64 65 6e 74 69  stance is identi
12230 66 69 65 64 20 62 79 20 74 68 65 20 64 6f 63 75  fied by the docu
12240 6d 65 6e 74 20 0a 69 6e 20 77 68 69 63 68 20 69  ment .in which i
12250 74 20 61 70 70 65 61 72 73 20 61 6e 64 20 69 74  t appears and it
12260 73 20 70 6f 73 69 74 69 6f 6e 20 77 69 74 68 69  s position withi
12270 6e 20 74 68 61 74 20 64 6f 63 75 6d 65 6e 74 2e  n that document.
12280 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c   For example:..<
12290 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e  codeblock>.  <i>
122a0 2d 2d 20 47 69 76 65 6e 20 74 68 65 20 66 6f 6c  -- Given the fol
122b0 6c 6f 77 69 6e 67 20 53 51 4c 3a 3c 2f 69 3e 0a  lowing SQL:</i>.
122c0 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
122d0 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20   TABLE ft USING 
122e0 66 74 73 35 28 61 2c 20 62 29 3b 0a 20 20 49 4e  fts5(a, b);.  IN
122f0 53 45 52 54 20 49 4e 54 4f 20 66 74 28 72 6f 77  SERT INTO ft(row
12300 69 64 2c 20 61 2c 20 62 29 20 56 41 4c 55 45 53  id, a, b) VALUES
12310 28 31 2c 20 27 58 20 59 27 2c 20 27 59 20 5a 27  (1, 'X Y', 'Y Z'
12320 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
12330 20 66 74 28 72 6f 77 69 64 2c 20 61 2c 20 62 29   ft(rowid, a, b)
12340 20 56 41 4c 55 45 53 28 32 2c 20 27 41 20 5a 27   VALUES(2, 'A Z'
12350 2c 20 27 59 20 59 27 29 3b 0a 0a 20 20 3c 69 3e  , 'Y Y');..  <i>
12360 2d 2d 20 54 68 65 20 46 54 53 35 20 6d 6f 64 75  -- The FTS5 modu
12370 6c 65 20 63 72 65 61 74 65 73 20 74 68 65 20 66  le creates the f
12380 6f 6c 6c 6f 77 69 6e 67 20 6d 61 70 70 69 6e 67  ollowing mapping
12390 20 6f 6e 20 64 69 73 6b 3a 3c 2f 69 3e 0a 20 20   on disk:</i>.  
123a0 41 20 2d 2d 26 67 74 3b 20 28 32 2c 20 30 2c 20  A --&gt; (2, 0, 
123b0 30 29 0a 20 20 58 20 2d 2d 26 67 74 3b 20 28 31  0).  X --&gt; (1
123c0 2c 20 30 2c 20 30 29 0a 20 20 59 20 2d 2d 26 67  , 0, 0).  Y --&g
123d0 74 3b 20 28 31 2c 20 30 2c 20 31 29 20 28 31 2c  t; (1, 0, 1) (1,
123e0 20 31 2c 20 30 29 20 28 32 2c 20 31 2c 20 30 29   1, 0) (2, 1, 0)
123f0 20 28 32 2c 20 31 2c 20 31 29 0a 20 20 5a 20 2d   (2, 1, 1).  Z -
12400 2d 26 67 74 3b 20 28 31 2c 20 31 2c 20 31 29 20  -&gt; (1, 1, 1) 
12410 28 32 2c 20 30 2c 20 31 29 0a 3c 2f 63 6f 64 65  (2, 0, 1).</code
12420 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 6e 20 74 68  block>..<p>In th
12430 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 2c  e example above,
12440 20 65 61 63 68 20 74 72 69 70 6c 65 20 69 64 65   each triple ide
12450 6e 74 69 66 69 65 73 20 74 68 65 20 6c 6f 63 61  ntifies the loca
12460 74 69 6f 6e 20 6f 66 20 61 20 74 6f 6b 65 6e 0a  tion of a token.
12470 69 6e 73 74 61 6e 63 65 20 62 79 20 72 6f 77 69  instance by rowi
12480 64 2c 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  d, column number
12490 20 28 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 75   (columns are nu
124a0 6d 62 65 72 65 64 20 73 65 71 75 65 6e 74 69 61  mbered sequentia
124b0 6c 6c 79 0a 73 74 61 72 74 69 6e 67 20 61 74 20  lly.starting at 
124c0 30 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72  0 from left to r
124d0 69 67 68 74 29 20 61 6e 64 20 70 6f 73 69 74 69  ight) and positi
124e0 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f  on within the co
124f0 6c 75 6d 6e 20 76 61 6c 75 65 20 28 74 68 65 0a  lumn value (the.
12500 66 69 72 73 74 20 74 6f 6b 65 6e 20 69 6e 20 61  first token in a
12510 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69 73   column value is
12520 20 30 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 69   0, the second i
12530 73 20 31 2c 20 61 6e 64 20 73 6f 20 6f 6e 29 2e  s 1, and so on).
12540 20 55 73 69 6e 67 20 74 68 69 73 0a 69 6e 64 65   Using this.inde
12550 78 2c 20 46 54 53 35 20 69 73 20 61 62 6c 65 20  x, FTS5 is able 
12560 74 6f 20 70 72 6f 76 69 64 65 20 74 69 6d 65 6c  to provide timel
12570 79 20 61 6e 73 77 65 72 73 20 74 6f 20 71 75 65  y answers to que
12580 72 69 65 73 20 73 75 63 68 20 61 73 20 22 74 68  ries such as "th
12590 65 20 73 65 74 0a 6f 66 20 61 6c 6c 20 64 6f 63  e set.of all doc
125a0 75 6d 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74  uments that cont
125b0 61 69 6e 20 74 68 65 20 74 6f 6b 65 6e 20 27 41  ain the token 'A
125c0 27 22 2c 20 6f 72 20 22 74 68 65 20 73 65 74 20  '", or "the set 
125d0 6f 66 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73  of all documents
125e0 0a 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 68  .that contain th
125f0 65 20 73 65 71 75 65 6e 63 65 20 27 59 20 5a 27  e sequence 'Y Z'
12600 22 2e 20 54 68 65 20 6c 69 73 74 20 6f 66 20 69  ". The list of i
12610 6e 73 74 61 6e 63 65 73 20 61 73 73 6f 63 69 61  nstances associa
12620 74 65 64 20 77 69 74 68 20 61 0a 73 69 6e 67 6c  ted with a.singl
12630 65 20 74 6f 6b 65 6e 20 69 73 20 63 61 6c 6c 65  e token is calle
12640 64 20 61 6e 20 22 69 6e 73 74 61 6e 63 65 2d 6c  d an "instance-l
12650 69 73 74 22 2e 0a 0a 3c 70 3e 54 68 65 20 70 72  ist"...<p>The pr
12660 69 6e 63 69 70 6c 65 20 64 69 66 66 65 72 65 6e  inciple differen
12670 63 65 20 62 65 74 77 65 65 6e 20 46 54 53 33 2f  ce between FTS3/
12680 34 20 61 6e 64 20 46 54 53 35 20 69 73 20 74 68  4 and FTS5 is th
12690 61 74 20 69 6e 20 46 54 53 33 2f 34 2c 0a 65 61  at in FTS3/4,.ea
126a0 63 68 20 69 6e 73 74 61 6e 63 65 2d 6c 69 73 74  ch instance-list
126b0 20 69 73 20 73 74 6f 72 65 64 20 61 73 20 61 20   is stored as a 
126c0 73 69 6e 67 6c 65 20 6c 61 72 67 65 20 64 61 74  single large dat
126d0 61 62 61 73 65 20 72 65 63 6f 72 64 2c 20 77 68  abase record, wh
126e0 65 72 65 61 73 0a 69 6e 20 46 54 53 35 20 6c 61  ereas.in FTS5 la
126f0 72 67 65 20 69 6e 73 74 61 6e 63 65 2d 6c 69 73  rge instance-lis
12700 74 73 20 61 72 65 20 64 69 76 69 64 65 64 20 62  ts are divided b
12710 65 74 77 65 65 6e 20 6d 75 6c 74 69 70 6c 65 20  etween multiple 
12720 64 61 74 61 62 61 73 65 20 72 65 63 6f 72 64 73  database records
12730 2e 0a 54 68 69 73 20 68 61 73 20 74 68 65 20 66  ..This has the f
12740 6f 6c 6c 6f 77 69 6e 67 20 69 6d 70 6c 69 63 61  ollowing implica
12750 74 69 6f 6e 73 20 66 6f 72 20 64 65 61 6c 69 6e  tions for dealin
12760 67 20 77 69 74 68 20 6c 61 72 67 65 20 64 61 74  g with large dat
12770 61 62 61 73 65 73 20 74 68 61 74 0a 63 6f 6e 74  abases that.cont
12780 61 69 6e 20 6c 61 72 67 65 20 6c 69 73 74 73 3a  ain large lists:
12790 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70  ..<ul>.  <li> <p
127a0 3e 46 54 53 35 20 69 73 20 61 62 6c 65 20 74 6f  >FTS5 is able to
127b0 20 6c 6f 61 64 20 69 6e 73 74 61 6e 63 65 2d 6c   load instance-l
127c0 69 73 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ists into memory
127d0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 69   incrementally i
127e0 6e 0a 20 20 20 20 20 20 20 6f 72 64 65 72 20 74  n.       order t
127f0 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20  o reduce memory 
12800 75 73 61 67 65 20 61 6e 64 20 70 65 61 6b 20 61  usage and peak a
12810 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20  llocation size. 
12820 46 54 53 33 2f 34 20 76 65 72 79 0a 20 20 20 20  FTS3/4 very.    
12830 20 20 20 6f 66 74 65 6e 20 6c 6f 61 64 73 20 65     often loads e
12840 6e 74 69 72 65 20 69 6e 73 74 61 6e 63 65 2d 6c  ntire instance-l
12850 69 73 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ists into memory
12860 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 57 68 65  ...  <li> <p>Whe
12870 6e 20 70 72 6f 63 65 73 73 69 6e 67 20 71 75 65  n processing que
12880 72 69 65 73 20 74 68 61 74 20 66 65 61 74 75 72  ries that featur
12890 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
128a0 74 6f 6b 65 6e 2c 20 46 54 53 35 20 69 73 0a 20  token, FTS5 is. 
128b0 20 20 20 20 20 20 73 6f 6d 65 74 69 6d 65 73 20        sometimes 
128c0 61 62 6c 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  able to determin
128d0 65 20 74 68 61 74 20 74 68 65 20 71 75 65 72 79  e that the query
128e0 20 63 61 6e 20 62 65 20 61 6e 73 77 65 72 65 64   can be answered
128f0 20 62 79 0a 20 20 20 20 20 20 20 69 6e 73 70 65   by.       inspe
12900 63 74 69 6e 67 20 61 20 73 75 62 73 65 74 20 6f  cting a subset o
12910 66 20 61 20 6c 61 72 67 65 20 69 6e 73 74 61 6e  f a large instan
12920 63 65 2d 6c 69 73 74 2e 20 46 54 53 33 2f 34 20  ce-list. FTS3/4 
12930 61 6c 6d 6f 73 74 20 61 6c 77 61 79 73 0a 20 20  almost always.  
12940 20 20 20 20 20 68 61 73 20 74 6f 20 74 72 61 76       has to trav
12950 65 72 73 65 20 65 6e 74 69 72 65 20 69 6e 73 74  erse entire inst
12960 61 6e 63 65 2d 6c 69 73 74 73 2e 0a 0a 20 20 3c  ance-lists...  <
12970 6c 69 3e 20 49 66 20 61 6e 20 69 6e 73 74 61 6e  li> If an instan
12980 63 65 2d 6c 69 73 74 20 67 72 6f 77 73 20 73 6f  ce-list grows so
12990 20 6c 61 72 67 65 20 74 68 61 74 20 69 74 20 65   large that it e
129a0 78 63 65 65 64 73 0a 20 20 20 20 20 20 20 74 68  xceeds.       th
129b0 65 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  e [SQLITE_MAX_LE
129c0 4e 47 54 48 5d 20 6c 69 6d 69 74 2c 20 46 54 53  NGTH] limit, FTS
129d0 33 2f 34 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  3/4 is unable to
129e0 20 68 61 6e 64 6c 65 20 69 74 2e 20 46 54 53 35   handle it. FTS5
129f0 0a 20 20 20 20 20 20 20 64 6f 65 73 20 6e 6f 74  .       does not
12a00 20 68 61 76 65 20 74 68 69 73 20 70 72 6f 62 6c   have this probl
12a10 65 6d 2e 20 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 46  em. .</ul>..<p>F
12a20 6f 72 20 74 68 65 73 65 20 72 65 61 73 6f 6e 73  or these reasons
12a30 2c 20 6d 61 6e 79 20 63 6f 6d 70 6c 65 78 20 71  , many complex q
12a40 75 65 72 69 65 73 20 6d 61 79 20 75 73 65 20 6c  ueries may use l
12a50 65 73 73 20 6d 65 6d 6f 72 79 20 61 6e 64 20 72  ess memory and r
12a60 75 6e 20 66 61 73 74 65 72 20 0a 75 73 69 6e 67  un faster .using
12a70 20 46 54 53 35 2e 0a 0a 3c 70 3e 53 6f 6d 65 20   FTS5...<p>Some 
12a80 6f 74 68 65 72 20 77 61 79 73 20 69 6e 20 77 68  other ways in wh
12a90 69 63 68 20 46 54 53 35 20 64 69 66 66 65 72 73  ich FTS5 differs
12aa0 20 66 72 6f 6d 20 46 54 53 33 2f 34 20 61 72 65   from FTS3/4 are
12ab0 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c  :..<ul>.  <li> <
12ac0 70 3e 46 54 53 35 20 73 75 70 70 6f 72 74 73 20  p>FTS5 supports 
12ad0 22 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 22 20  "ORDER BY rank" 
12ae0 66 6f 72 20 72 65 74 75 72 6e 69 6e 67 20 72 65  for returning re
12af0 73 75 6c 74 73 20 69 6e 20 6f 72 64 65 72 20 6f  sults in order o
12b00 66 0a 20 20 20 20 20 20 20 64 65 63 72 65 61 73  f.       decreas
12b10 69 6e 67 20 72 65 6c 65 76 61 6e 63 79 2e 0a 0a  ing relevancy...
12b20 20 20 3c 6c 69 3e 20 3c 70 3e 46 54 53 35 20 66    <li> <p>FTS5 f
12b30 65 61 74 75 72 65 73 20 61 6e 20 41 50 49 20 61  eatures an API a
12b40 6c 6c 6f 77 69 6e 67 20 75 73 65 72 73 20 74 6f  llowing users to
12b50 20 63 72 65 61 74 65 20 63 75 73 74 6f 6d 20 61   create custom a
12b60 75 78 69 6c 69 61 72 79 20 0a 20 20 20 20 20 20  uxiliary .      
12b70 20 66 75 6e 63 74 69 6f 6e 73 20 66 6f 72 20 61   functions for a
12b80 64 76 61 6e 63 65 64 20 72 61 6e 6b 69 6e 67 20  dvanced ranking 
12b90 61 6e 64 20 74 65 78 74 20 70 72 6f 63 65 73 73  and text process
12ba0 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ing applications
12bb0 2e 20 54 68 65 0a 20 20 20 20 20 20 20 73 70 65  . The.       spe
12bc0 63 69 61 6c 20 22 72 61 6e 6b 22 20 63 6f 6c 75  cial "rank" colu
12bd0 6d 6e 20 6d 61 79 20 62 65 20 6d 61 70 70 65 64  mn may be mapped
12be0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 61 75 78   to a custom aux
12bf0 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 0a  iliary function.
12c00 20 20 20 20 20 20 20 73 6f 20 74 68 61 74 20 61         so that a
12c10 64 64 69 6e 67 20 22 4f 52 44 45 52 20 42 59 20  dding "ORDER BY 
12c20 72 61 6e 6b 22 20 74 6f 20 61 20 71 75 65 72 79  rank" to a query
12c30 20 77 6f 72 6b 73 20 61 73 20 65 78 70 65 63 74   works as expect
12c40 65 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 46  ed...  <li> <p>F
12c50 54 53 35 20 72 65 63 6f 67 6e 69 7a 65 73 20 75  TS5 recognizes u
12c60 6e 69 63 6f 64 65 20 73 65 70 61 72 61 74 6f 72  nicode separator
12c70 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 20   characters and 
12c80 63 61 73 65 20 65 71 75 69 76 61 6c 65 6e 63 65  case equivalence
12c90 20 62 79 0a 20 20 20 20 20 20 20 64 65 66 61 75   by.       defau
12ca0 6c 74 2e 20 54 68 69 73 20 69 73 20 61 6c 73 6f  lt. This is also
12cb0 20 70 6f 73 73 69 62 6c 65 20 75 73 69 6e 67 20   possible using 
12cc0 46 54 53 33 2f 34 2c 20 62 75 74 20 6d 75 73 74  FTS3/4, but must
12cd0 20 62 65 20 65 78 70 6c 69 63 69 74 6c 79 0a 20   be explicitly. 
12ce0 20 20 20 20 20 20 65 6e 61 62 6c 65 64 2e 0a 0a        enabled...
12cf0 20 20 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 71 75    <li> <p>The qu
12d00 65 72 79 20 73 79 6e 74 61 78 20 68 61 73 20 62  ery syntax has b
12d10 65 65 6e 20 72 65 76 69 73 65 64 20 77 68 65 72  een revised wher
12d20 65 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 72  e necessary to r
12d30 65 6d 6f 76 65 0a 20 20 20 20 20 20 20 61 6d 62  emove.       amb
12d40 69 67 75 69 74 69 65 73 20 61 6e 64 20 74 6f 20  iguities and to 
12d50 6d 61 6b 65 20 69 74 20 70 6f 73 73 69 62 6c 65  make it possible
12d60 20 74 6f 20 65 73 63 61 70 65 20 73 70 65 63 69   to escape speci
12d70 61 6c 20 63 68 61 72 61 63 74 65 72 73 0a 20 20  al characters.  
12d80 20 20 20 20 20 69 6e 20 71 75 65 72 79 20 74 65       in query te
12d90 72 6d 73 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e  rms...  <li> <p>
12da0 42 79 20 64 65 66 61 75 6c 74 2c 20 46 54 53 33  By default, FTS3
12db0 2f 34 20 6f 63 63 61 73 69 6f 6e 61 6c 6c 79 20  /4 occasionally 
12dc0 6d 65 72 67 65 73 20 74 6f 67 65 74 68 65 72 20  merges together 
12dd0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  two or more of t
12de0 68 65 0a 20 20 20 20 20 20 20 62 2d 74 72 65 65  he.       b-tree
12df0 73 20 74 68 61 74 20 6d 61 6b 65 20 75 70 20 69  s that make up i
12e00 74 73 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  ts full-text ind
12e10 65 78 20 77 69 74 68 69 6e 20 61 6e 20 49 4e 53  ex within an INS
12e20 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 0a 20  ERT, UPDATE or. 
12e30 20 20 20 20 20 20 44 45 4c 45 54 45 20 73 74 61        DELETE sta
12e40 74 65 6d 65 6e 74 20 65 78 65 63 75 74 65 64 20  tement executed 
12e50 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 69  by the user. Thi
12e60 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 79  s means that any
12e70 20 6f 70 65 72 61 74 69 6f 6e 0a 20 20 20 20 20   operation.     
12e80 20 20 6f 6e 20 61 6e 20 46 54 53 33 2f 34 20 74    on an FTS3/4 t
12e90 61 62 6c 65 20 6d 61 79 20 74 75 72 6e 20 6f 75  able may turn ou
12ea0 74 20 74 6f 20 62 65 20 73 75 72 70 72 69 73 69  t to be surprisi
12eb0 6e 67 6c 79 20 73 6c 6f 77 2c 20 61 73 20 46 54  ngly slow, as FT
12ec0 53 33 2f 34 20 0a 20 20 20 20 20 20 20 6d 61 79  S3/4 .       may
12ed0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 79 20 63   unpredictably c
12ee0 68 6f 6f 73 65 20 74 6f 20 6d 65 72 67 65 20 74  hoose to merge t
12ef0 6f 67 65 74 68 65 72 20 74 77 6f 20 6f 72 20 6d  ogether two or m
12f00 6f 72 65 20 6c 61 72 67 65 20 62 2d 74 72 65 65  ore large b-tree
12f10 73 0a 20 20 20 20 20 20 20 77 69 74 68 69 6e 20  s.       within 
12f20 69 74 2e 20 46 54 53 35 20 75 73 65 73 20 69 6e  it. FTS5 uses in
12f30 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 69 6e  cremental mergin
12f40 67 20 62 79 20 64 65 66 61 75 6c 74 2c 20 77 68  g by default, wh
12f50 69 63 68 20 6c 69 6d 69 74 73 0a 20 20 20 20 20  ich limits.     
12f60 20 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20    the amount of 
12f70 70 72 6f 63 65 73 73 69 6e 67 20 74 68 61 74 20  processing that 
12f80 6d 61 79 20 74 61 6b 65 20 70 6c 61 63 65 20 77  may take place w
12f90 69 74 68 69 6e 20 61 6e 79 20 67 69 76 65 6e 20  ithin any given 
12fa0 0a 20 20 20 20 20 20 20 49 4e 53 45 52 54 2c 20  .       INSERT, 
12fb0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
12fc0 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 3c 2f 75 6c   operation..</ul
12fd0 3e 0a                                            >.