Documentation Source Text

Hex Artifact Content
Login

Artifact 79ad85863f8932f46f5c8ee79a2fb7498b314f97167bddf3518e02596904f4f3:


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: 69 73 20 75 73 75 61 6c 6c 79 20 74 68 65 20 6e  is usually the n
08a0: 61 6d 65 20 6f 66 20 74 68 65 20 46 54 53 35 20  ame of the FTS5 
08b0: 74 61 62 6c 65 20 28 74 68 65 20 65 78 63 65 70  table (the excep
08c0: 74 69 6f 6e 20 69 73 20 77 68 65 6e 20 0a 20 20  tion is when .  
08d0: 20 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 20 66 69   [FTS5 column fi
08e0: 6c 74 65 72 73 20 7c 20 73 70 65 63 69 66 79 69  lters | specifyi
08f0: 6e 67 20 61 20 63 6f 6c 75 6d 6e 2d 66 69 6c 74  ng a column-filt
0900: 65 72 5d 29 2e 20 54 68 65 20 65 78 70 72 65 73  er]). The expres
0910: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 72 69 67 68  sion on the righ
0920: 74 0a 20 20 20 6d 75 73 74 20 62 65 20 61 20 74  t.   must be a t
0930: 65 78 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  ext value specif
0940: 79 69 6e 67 20 74 68 65 20 74 65 72 6d 20 74 6f  ying the term to
0950: 20 73 65 61 72 63 68 20 66 6f 72 2e 20 46 6f 72   search for. For
0960: 20 74 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65   the table-value
0970: 64 0a 20 20 20 66 75 6e 63 74 69 6f 6e 20 73 79  d.   function sy
0980: 6e 74 61 78 2c 20 74 68 65 20 74 65 72 6d 20 74  ntax, the term t
0990: 6f 20 73 65 61 72 63 68 20 66 6f 72 20 69 73 20  o search for is 
09a0: 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
09b0: 20 66 69 72 73 74 20 74 61 62 6c 65 20 61 72 67   first table arg
09c0: 75 6d 65 6e 74 2e 0a 20 20 20 46 6f 72 20 65 78  ument..   For ex
09d0: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
09e0: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72  ck>.  <i>-- Quer
09f0: 79 20 66 6f 72 20 61 6c 6c 20 72 6f 77 73 20 74  y for all rows t
0a00: 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c  hat contain at l
0a10: 65 61 73 74 20 6f 6e 63 65 20 69 6e 73 74 61 6e  east once instan
0a20: 63 65 20 6f 66 20 74 68 65 20 74 65 72 6d 3c 2f  ce of the term</
0a30: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 66 74 73 35  i>.  <i>-- "fts5
0a40: 22 20 28 69 6e 20 61 6e 79 20 63 6f 6c 75 6d 6e  " (in any column
0a50: 29 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ). The following
0a60: 20 74 68 72 65 65 20 71 75 65 72 69 65 73 20 61   three queries a
0a70: 72 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 3c 2f  re equivalent.</
0a80: 69 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  i>.  SELECT * FR
0a90: 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65  OM email WHERE e
0aa0: 6d 61 69 6c 20 4d 41 54 43 48 20 27 66 74 73 35  mail MATCH 'fts5
0ab0: 27 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  ';.  SELECT * FR
0ac0: 4f 4d 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65  OM email WHERE e
0ad0: 6d 61 69 6c 20 3d 20 27 66 74 73 35 27 3b 0a 20  mail = 'fts5';. 
0ae0: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 65   SELECT * FROM e
0af0: 6d 61 69 6c 28 27 66 74 73 35 27 29 3b 0a 3c 2f  mail('fts5');.</
0b00: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20  codeblock>..<p> 
0b10: 42 79 20 64 65 66 61 75 6c 74 2c 20 46 54 53 35  By default, FTS5
0b20: 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
0b30: 68 65 73 20 61 72 65 20 63 61 73 65 2d 69 6e 64  hes are case-ind
0b40: 65 70 65 6e 64 65 6e 74 2e 20 4c 69 6b 65 20 61  ependent. Like a
0b50: 6e 79 20 6f 74 68 65 72 0a 53 51 4c 20 71 75 65  ny other.SQL que
0b60: 72 79 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ry that does not
0b70: 20 63 6f 6e 74 61 69 6e 20 61 6e 20 4f 52 44 45   contain an ORDE
0b80: 52 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65  R BY clause, the
0b90: 20 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 20 72   example above r
0ba0: 65 74 75 72 6e 73 0a 72 65 73 75 6c 74 73 20 69  eturns.results i
0bb0: 6e 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 6f  n an arbitrary o
0bc0: 72 64 65 72 2e 20 54 6f 20 73 6f 72 74 20 72 65  rder. To sort re
0bd0: 73 75 6c 74 73 20 62 79 20 72 65 6c 65 76 61 6e  sults by relevan
0be0: 63 65 20 28 6d 6f 73 74 20 74 6f 20 6c 65 61 73  ce (most to leas
0bf0: 74 0a 72 65 6c 65 76 61 6e 74 29 2c 20 61 6e 20  t.relevant), an 
0c00: 4f 52 44 45 52 20 42 59 20 6d 61 79 20 62 65 20  ORDER BY may be 
0c10: 61 64 64 65 64 20 74 6f 20 61 20 66 75 6c 6c 2d  added to a full-
0c20: 74 65 78 74 20 71 75 65 72 79 20 61 73 20 66 6f  text query as fo
0c30: 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  llows:..<codeblo
0c40: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72  ck>.  <i>-- Quer
0c50: 79 20 66 6f 72 20 61 6c 6c 20 72 6f 77 73 20 74  y for all rows t
0c60: 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c  hat contain at l
0c70: 65 61 73 74 20 6f 6e 63 65 20 69 6e 73 74 61 6e  east once instan
0c80: 63 65 20 6f 66 20 74 68 65 20 74 65 72 6d 3c 2f  ce of the term</
0c90: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 22 66 74 73 35  i>.  <i>-- "fts5
0ca0: 22 20 28 69 6e 20 61 6e 79 20 63 6f 6c 75 6d 6e  " (in any column
0cb0: 29 2e 20 52 65 74 75 72 6e 20 72 65 73 75 6c 74  ). Return result
0cc0: 73 20 69 6e 20 6f 72 64 65 72 20 66 72 6f 6d 20  s in order from 
0cd0: 62 65 73 74 20 74 6f 20 77 6f 72 73 74 3c 2f 69  best to worst</i
0ce0: 3e 0a 20 20 3c 69 3e 2d 2d 20 6d 61 74 63 68 2e  >.  <i>-- match.
0cf0: 20 20 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20    </i>.  SELECT 
0d00: 2a 20 46 52 4f 4d 20 65 6d 61 69 6c 20 57 48 45  * FROM email WHE
0d10: 52 45 20 65 6d 61 69 6c 20 4d 41 54 43 48 20 27  RE email MATCH '
0d20: 66 74 73 35 27 20 4f 52 44 45 52 20 42 59 20 72  fts5' ORDER BY r
0d30: 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ank;.</codeblock
0d40: 3e 0a 0a 3c 70 3e 20 41 73 20 77 65 6c 6c 20 61  >..<p> As well a
0d50: 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  s the column val
0d60: 75 65 73 20 61 6e 64 20 72 6f 77 69 64 20 6f 66  ues and rowid of
0d70: 20 61 20 6d 61 74 63 68 69 6e 67 20 72 6f 77 2c   a matching row,
0d80: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
0d90: 6d 61 79 20 75 73 65 20 5b 46 54 53 35 20 61 75  may use [FTS5 au
0da0: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
0db0: 73 5d 20 74 6f 20 72 65 74 72 69 65 76 65 20 65  s] to retrieve e
0dc0: 78 74 72 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  xtra information
0dd0: 20 72 65 67 61 72 64 69 6e 67 0a 74 68 65 20 6d   regarding.the m
0de0: 61 74 63 68 65 64 20 72 6f 77 2e 20 46 6f 72 20  atched row. For 
0df0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 75 78 69  example, an auxi
0e00: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d  liary function m
0e10: 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  ay be used to re
0e20: 74 72 69 65 76 65 0a 61 20 63 6f 70 79 20 6f 66  trieve.a copy of
0e30: 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20   a column value 
0e40: 66 6f 72 20 61 20 6d 61 74 63 68 65 64 20 72 6f  for a matched ro
0e50: 77 20 77 69 74 68 20 61 6c 6c 20 69 6e 73 74 61  w with all insta
0e60: 6e 63 65 73 20 6f 66 20 74 68 65 20 6d 61 74 63  nces of the matc
0e70: 68 65 64 0a 74 65 72 6d 20 73 75 72 72 6f 75 6e  hed.term surroun
0e80: 64 65 64 20 62 79 20 68 74 6d 6c 20 26 6c 74 3b  ded by html &lt;
0e90: 62 26 67 74 3b 26 6c 74 3b 2f 62 26 67 74 3b 20  b&gt;&lt;/b&gt; 
0ea0: 74 61 67 73 2e 20 41 75 78 69 6c 69 61 72 79 20  tags. Auxiliary 
0eb0: 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 69 6e  functions are.in
0ec0: 76 6f 6b 65 64 20 69 6e 20 74 68 65 20 73 61 6d  voked in the sam
0ed0: 65 20 77 61 79 20 61 73 20 53 51 4c 69 74 65 20  e way as SQLite 
0ee0: 5b 63 6f 72 65 66 75 6e 63 20 7c 20 73 63 61 6c  [corefunc | scal
0ef0: 61 72 20 66 75 6e 63 74 69 6f 6e 73 5d 2c 20 65  ar functions], e
0f00: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 6e  xcept that the n
0f10: 61 6d 65 0a 6f 66 20 74 68 65 20 46 54 53 35 20  ame.of the FTS5 
0f20: 74 61 62 6c 65 20 69 73 20 73 70 65 63 69 66 69  table is specifi
0f30: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
0f40: 61 72 67 75 6d 65 6e 74 2e 20 46 6f 72 20 65 78  argument. For ex
0f50: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
0f60: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 51 75 65 72  ck>.  <i>-- Quer
0f70: 79 20 66 6f 72 20 72 6f 77 73 20 74 68 61 74 20  y for rows that 
0f80: 6d 61 74 63 68 20 22 66 74 73 35 22 2e 20 52 65  match "fts5". Re
0f90: 74 75 72 6e 20 61 20 63 6f 70 79 20 6f 66 20 74  turn a copy of t
0fa0: 68 65 20 22 62 6f 64 79 22 20 63 6f 6c 75 6d 6e  he "body" column
0fb0: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 66 20  </i>.  <i>-- of 
0fc0: 65 61 63 68 20 72 6f 77 20 77 69 74 68 20 74 68  each row with th
0fd0: 65 20 6d 61 74 63 68 65 73 20 73 75 72 72 6f 75  e matches surrou
0fe0: 6e 64 65 64 20 62 79 20 26 6c 74 3b 62 26 67 74  nded by &lt;b&gt
0ff0: 3b 26 6c 74 3b 2f 62 26 67 74 3b 20 74 61 67 73  ;&lt;/b&gt; tags
1000: 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20 68  .</i>.  SELECT h
1010: 69 67 68 6c 69 67 68 74 28 65 6d 61 69 6c 2c 20  ighlight(email, 
1020: 32 2c 20 27 26 6c 74 3b 62 26 67 74 3b 27 2c 20  2, '&lt;b&gt;', 
1030: 27 26 6c 74 3b 2f 62 26 67 74 3b 27 29 20 46 52  '&lt;/b&gt;') FR
1040: 4f 4d 20 65 6d 61 69 6c 28 27 66 74 73 35 27 29  OM email('fts5')
1050: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
1060: 3c 70 3e 41 20 64 65 73 63 72 69 70 74 69 6f 6e  <p>A description
1070: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
1080: 65 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  e auxiliary func
1090: 74 69 6f 6e 73 2c 20 61 6e 64 20 6d 6f 72 65 20  tions, and more 
10a0: 64 65 74 61 69 6c 73 0a 72 65 67 61 72 64 69 6e  details.regardin
10b0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
10c0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 20 22  of the special "
10d0: 72 61 6e 6b 22 20 63 6f 6c 75 6d 6e 2c 20 61 72  rank" column, ar
10e0: 65 20 0a 5b 46 54 53 35 20 61 75 78 69 6c 69 61  e .[FTS5 auxilia
10f0: 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 7c 20 61  ry functions | a
1100: 76 61 69 6c 61 62 6c 65 20 62 65 6c 6f 77 5d 2e  vailable below].
1110: 20 5b 46 54 53 35 20 63 75 73 74 6f 6d 20 61 75   [FTS5 custom au
1120: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
1130: 73 7c 0a 43 75 73 74 6f 6d 20 61 75 78 69 6c 69  s|.Custom auxili
1140: 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6d  ary functions] m
1150: 61 79 20 61 6c 73 6f 20 62 65 20 69 6d 70 6c 65  ay also be imple
1160: 6d 65 6e 74 65 64 20 69 6e 20 43 20 61 6e 64 20  mented in C and 
1170: 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a  registered with.
1180: 46 54 53 35 2c 20 6a 75 73 74 20 61 73 20 63 75  FTS5, just as cu
1190: 73 74 6f 6d 20 53 51 4c 20 66 75 6e 63 74 69 6f  stom SQL functio
11a0: 6e 73 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  ns may be regist
11b0: 65 72 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ered with the SQ
11c0: 4c 69 74 65 20 63 6f 72 65 2e 0a 0a 3c 70 3e 20  Lite core...<p> 
11d0: 41 73 20 77 65 6c 6c 20 61 73 20 73 65 61 72 63  As well as searc
11e0: 68 69 6e 67 20 66 6f 72 20 61 6c 6c 20 72 6f 77  hing for all row
11f0: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1200: 20 74 65 72 6d 2c 20 46 54 53 35 20 61 6c 6c 6f   term, FTS5 allo
1210: 77 73 20 0a 74 68 65 20 75 73 65 72 20 74 6f 20  ws .the user to 
1220: 73 65 61 72 63 68 20 66 6f 72 20 72 6f 77 73 20  search for rows 
1230: 74 68 61 74 20 63 6f 6e 74 61 69 6e 3a 0a 0a 3c  that contain:..<
1240: 75 6c 3e 0a 20 20 3c 6c 69 3e 20 61 6e 79 20 74  ul>.  <li> any t
1250: 65 72 6d 73 20 74 68 61 74 20 62 65 67 69 6e 20  erms that begin 
1260: 77 69 74 68 20 61 20 73 70 65 63 69 66 69 65 64  with a specified
1270: 20 70 72 65 66 69 78 2c 0a 20 20 3c 6c 69 3e 20   prefix,.  <li> 
1280: 22 70 68 72 61 73 65 73 22 20 2d 20 73 65 71 75  "phrases" - sequ
1290: 65 6e 63 65 73 20 6f 66 20 74 65 72 6d 73 20 6f  ences of terms o
12a0: 72 20 70 72 65 66 69 78 20 74 65 72 6d 73 20 74  r prefix terms t
12b0: 68 61 74 20 6d 75 73 74 20 66 65 61 74 75 72 65  hat must feature
12c0: 20 69 6e 20 61 0a 20 20 20 20 20 20 20 64 6f 63   in a.       doc
12d0: 75 6d 65 6e 74 20 66 6f 72 20 69 74 20 74 6f 20  ument for it to 
12e0: 6d 61 74 63 68 20 74 68 65 20 71 75 65 72 79 2c  match the query,
12f0: 20 0a 20 20 3c 6c 69 3e 20 73 65 74 73 20 6f 66   .  <li> sets of
1300: 20 74 65 72 6d 73 2c 20 70 72 65 66 69 78 20 74   terms, prefix t
1310: 65 72 6d 73 20 6f 72 20 70 68 72 61 73 65 73 20  erms or phrases 
1320: 74 68 61 74 20 61 70 70 65 61 72 20 77 69 74 68  that appear with
1330: 69 6e 20 61 20 73 70 65 63 69 66 69 65 64 0a 20  in a specified. 
1340: 20 20 20 20 20 20 70 72 6f 78 69 6d 69 74 79 20        proximity 
1350: 6f 66 20 65 61 63 68 20 6f 74 68 65 72 20 28 74  of each other (t
1360: 68 65 73 65 20 61 72 65 20 63 61 6c 6c 65 64 20  hese are called 
1370: 22 4e 45 41 52 20 71 75 65 72 69 65 73 22 29 2c  "NEAR queries"),
1380: 20 6f 72 0a 20 20 3c 6c 69 3e 20 62 6f 6f 6c 65   or.  <li> boole
1390: 61 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  an combinations 
13a0: 6f 66 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  of any of the ab
13b0: 6f 76 65 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20  ove..</ul>..<p> 
13c0: 53 75 63 68 20 61 64 76 61 6e 63 65 64 20 73 65  Such advanced se
13d0: 61 72 63 68 65 73 20 61 72 65 20 72 65 71 75 65  arches are reque
13e0: 73 74 65 64 20 62 79 20 70 72 6f 76 69 64 69 6e  sted by providin
13f0: 67 20 61 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  g a more complic
1400: 61 74 65 64 20 0a 46 54 53 35 20 71 75 65 72 79  ated .FTS5 query
1410: 20 73 74 72 69 6e 67 20 61 73 20 74 68 65 20 74   string as the t
1420: 65 78 74 20 74 6f 20 74 68 65 20 72 69 67 68 74  ext to the right
1430: 20 6f 66 20 74 68 65 20 4d 41 54 43 48 20 6f 70   of the MATCH op
1440: 65 72 61 74 6f 72 20 28 6f 72 20 3d 0a 6f 70 65  erator (or =.ope
1450: 72 61 74 6f 72 2c 20 6f 72 20 61 73 20 74 68 65  rator, or as the
1460: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1470: 74 6f 20 61 20 74 61 62 6c 65 2d 76 61 6c 75 65  to a table-value
1480: 64 20 66 75 6e 63 74 69 6f 6e 20 73 79 6e 74 61  d function synta
1490: 78 29 2e 20 54 68 65 20 0a 66 75 6c 6c 20 71 75  x). The .full qu
14a0: 65 72 79 20 73 79 6e 74 61 78 20 69 73 20 5b 46  ery syntax is [F
14b0: 54 53 35 20 71 75 65 72 79 20 73 79 6e 74 61 78  TS5 query syntax
14c0: 20 7c 20 64 65 73 63 72 69 62 65 64 20 68 65 72   | described her
14d0: 65 5d 2e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46  e]...<h1 tags="F
14e0: 54 53 35 20 62 75 69 6c 64 69 6e 67 22 3e 43 6f  TS5 building">Co
14f0: 6d 70 69 6c 69 6e 67 20 61 6e 64 20 55 73 69 6e  mpiling and Usin
1500: 67 20 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 68 32  g FTS5</h1>..<h2
1510: 3e 42 75 69 6c 64 69 6e 67 20 46 54 53 35 20 61  >Building FTS5 a
1520: 73 20 70 61 72 74 20 6f 66 20 53 51 4c 69 74 65  s part of SQLite
1530: 3c 2f 68 32 3e 0a 0a 3c 70 3e 41 73 20 6f 66 20  </h2>..<p>As of 
1540: 5b 76 65 72 73 69 6f 6e 20 33 2e 39 2e 30 5d 20  [version 3.9.0] 
1550: 28 5b 64 61 74 65 6f 66 3a 33 2e 39 2e 30 5d 29  ([dateof:3.9.0])
1560: 2c 20 0a 46 54 53 35 20 69 73 20 69 6e 63 6c 75  , .FTS5 is inclu
1570: 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
1580: 68 65 20 53 51 4c 69 74 65 20 5b 61 6d 61 6c 67  he SQLite [amalg
1590: 61 6d 61 74 69 6f 6e 5d 2e 0a 49 74 20 69 73 20  amation]..It is 
15a0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
15b0: 75 6c 74 2e 20 49 66 20 75 73 69 6e 67 20 74 68  ult. If using th
15c0: 65 20 74 77 6f 20 61 75 74 6f 63 6f 6e 66 20 62  e two autoconf b
15d0: 75 69 6c 64 20 73 79 73 74 65 6d 2c 20 69 74 20  uild system, it 
15e0: 69 73 0a 65 6e 61 62 6c 65 64 20 62 79 20 73 70  is.enabled by sp
15f0: 65 63 69 66 79 69 6e 67 20 74 68 65 20 22 2d 2d  ecifying the "--
1600: 65 6e 61 62 6c 65 2d 66 74 73 35 22 20 6f 70 74  enable-fts5" opt
1610: 69 6f 6e 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67  ion when running
1620: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 0a 73   the configure.s
1630: 63 72 69 70 74 2e 20 0a 0a 3c 70 3e 4f 72 2c 20  cript. ..<p>Or, 
1640: 69 66 20 73 71 6c 69 74 65 33 2e 63 20 69 73 20  if sqlite3.c is 
1650: 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 73  compiled using s
1660: 6f 6d 65 20 6f 74 68 65 72 20 62 75 69 6c 64 20  ome other build 
1670: 73 79 73 74 65 6d 2c 20 62 79 20 61 72 72 61 6e  system, by arran
1680: 67 69 6e 67 20 66 6f 72 0a 74 68 65 20 53 51 4c  ging for.the SQL
1690: 49 54 45 5f 45 4e 41 42 4c 45 5f 46 54 53 35 20  ITE_ENABLE_FTS5 
16a0: 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 73 79  pre-processor sy
16b0: 6d 62 6f 6c 20 74 6f 20 62 65 20 64 65 66 69 6e  mbol to be defin
16c0: 65 64 2e 0a 0a 3c 68 32 3e 42 75 69 6c 64 69 6e  ed...<h2>Buildin
16d0: 67 20 61 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  g a Loadable Ext
16e0: 65 6e 73 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  ension</h2>..<p>
16f0: 41 6c 74 65 72 6e 61 74 69 76 65 6c 79 2c 20 46  Alternatively, F
1700: 54 53 35 20 6d 61 79 20 62 65 20 62 75 69 6c 74  TS5 may be built
1710: 20 61 73 20 61 20 6c 6f 61 64 61 62 6c 65 20 65   as a loadable e
1720: 78 74 65 6e 73 69 6f 6e 2e 0a 0a 3c 70 3e 54 68  xtension...<p>Th
1730: 65 20 63 61 6e 6f 6e 69 63 61 6c 20 46 54 53 35  e canonical FTS5
1740: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
1750: 73 69 73 74 73 20 6f 66 20 61 20 73 65 72 69 65  sists of a serie
1760: 73 20 6f 66 20 2a 2e 63 20 61 6e 64 20 6f 74 68  s of *.c and oth
1770: 65 72 20 66 69 6c 65 73 0a 69 6e 20 74 68 65 20  er files.in the 
1780: 22 65 78 74 2f 66 74 73 35 22 20 64 69 72 65 63  "ext/fts5" direc
1790: 74 6f 72 79 20 6f 66 20 74 68 65 20 53 51 4c 69  tory of the SQLi
17a0: 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 20  te source tree. 
17b0: 41 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 20  A build process 
17c0: 72 65 64 75 63 65 73 0a 74 68 69 73 20 74 6f 20  reduces.this to 
17d0: 6a 75 73 74 20 74 77 6f 20 66 69 6c 65 73 20 2d  just two files -
17e0: 20 22 66 74 73 35 2e 63 22 20 61 6e 64 20 22 66   "fts5.c" and "f
17f0: 74 73 35 2e 68 22 20 2d 20 77 68 69 63 68 20 6d  ts5.h" - which m
1800: 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 62 75  ay be used to bu
1810: 69 6c 64 20 61 6e 0a 53 51 4c 69 74 65 20 6c 6f  ild an.SQLite lo
1820: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
1830: 2e 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 4f  ...<ol>.  <li> O
1840: 62 74 61 69 6e 20 74 68 65 20 6c 61 74 65 73 74  btain the latest
1850: 20 53 51 4c 69 74 65 20 63 6f 64 65 20 66 72 6f   SQLite code fro
1860: 6d 20 66 6f 73 73 69 6c 2e 0a 20 20 3c 6c 69 3e  m fossil..  <li>
1870: 20 43 72 65 61 74 65 20 61 20 4d 61 6b 65 66 69   Create a Makefi
1880: 6c 65 20 61 73 20 64 65 73 63 72 69 62 65 64 20  le as described 
1890: 69 6e 20 5b 48 6f 77 20 54 6f 20 43 6f 6d 70 69  in [How To Compi
18a0: 6c 65 20 53 51 4c 69 74 65 5d 2e 0a 20 20 3c 6c  le SQLite]..  <l
18b0: 69 3e 20 42 75 69 6c 64 20 74 68 65 20 22 66 74  i> Build the "ft
18c0: 73 35 2e 63 22 20 74 61 72 67 65 74 2e 20 57 68  s5.c" target. Wh
18d0: 69 63 68 20 61 6c 73 6f 20 63 72 65 61 74 65 73  ich also creates
18e0: 20 66 74 73 35 2e 68 2e 0a 3c 2f 6f 6c 3e 0a 0a   fts5.h..</ol>..
18f0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 24 20  <codeblock>.  $ 
1900: 77 67 65 74 20 2d 63 20 68 74 74 70 3a 2f 2f 77  wget -c http://w
1910: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72  ww.sqlite.org/sr
1920: 63 2f 74 61 72 62 61 6c 6c 2f 53 51 4c 69 74 65  c/tarball/SQLite
1930: 2d 74 72 75 6e 6b 2e 74 67 7a 3f 75 75 69 64 3d  -trunk.tgz?uuid=
1940: 74 72 75 6e 6b 20 2d 4f 20 53 51 4c 69 74 65 2d  trunk -O SQLite-
1950: 74 72 75 6e 6b 2e 74 67 7a 0a 20 20 2e 2e 2e 2e  trunk.tgz.  ....
1960: 20 6f 75 74 70 75 74 20 2e 2e 2e 0a 20 20 24 20   output ....  $ 
1970: 74 61 72 20 2d 78 7a 66 20 53 51 4c 69 74 65 2d  tar -xzf SQLite-
1980: 74 72 75 6e 6b 2e 74 67 7a 0a 20 20 24 20 63 64  trunk.tgz.  $ cd
1990: 20 53 51 4c 69 74 65 2d 74 72 75 6e 6b 0a 20 20   SQLite-trunk.  
19a0: 24 20 2e 2f 63 6f 6e 66 69 67 75 72 65 20 26 26  $ ./configure &&
19b0: 20 6d 61 6b 65 20 66 74 73 35 2e 63 0a 20 20 2e   make fts5.c.  .
19c0: 2e 2e 20 6c 6f 74 73 20 6f 66 20 6f 75 74 70 75  .. lots of outpu
19d0: 74 20 2e 2e 2e 0a 20 20 24 20 6c 73 20 66 74 73  t ....  $ ls fts
19e0: 35 2e 26 23 39 31 3b 63 68 5d 0a 20 20 66 74 73  5.&#91;ch].  fts
19f0: 35 2e 63 20 20 20 20 20 20 20 20 66 74 73 35 2e  5.c        fts5.
1a00: 68 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  h.</codeblock>..
1a10: 3c 70 3e 0a 20 20 54 68 65 20 63 6f 64 65 20 69  <p>.  The code i
1a20: 6e 20 22 66 74 73 35 2e 63 22 20 6d 61 79 20 74  n "fts5.c" may t
1a30: 68 65 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  hen be compiled 
1a40: 69 6e 74 6f 20 61 20 6c 6f 61 64 61 62 6c 65 20  into a loadable 
1a50: 65 78 74 65 6e 73 69 6f 6e 20 6f 72 0a 20 20 73  extension or.  s
1a60: 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
1a70: 20 69 6e 74 6f 20 61 6e 20 61 70 70 6c 69 63 61   into an applica
1a80: 74 69 6f 6e 20 61 73 20 64 65 73 63 72 69 62 65  tion as describe
1a90: 64 20 69 6e 20 0a 20 20 5b 43 6f 6d 70 69 6c 69  d in .  [Compili
1aa0: 6e 67 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  ng Loadable Exte
1ab0: 6e 73 69 6f 6e 73 5d 2e 20 54 68 65 72 65 20 61  nsions]. There a
1ac0: 72 65 20 74 77 6f 20 65 6e 74 72 79 20 70 6f 69  re two entry poi
1ad0: 6e 74 73 20 64 65 66 69 6e 65 64 2c 20 62 6f 74  nts defined, bot
1ae0: 68 0a 20 20 6f 66 20 77 68 69 63 68 20 64 6f 20  h.  of which do 
1af0: 74 68 65 20 73 61 6d 65 20 74 68 69 6e 67 3a 0a  the same thing:.
1b00: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 73 71 6c  .<ul>.  <li> sql
1b10: 69 74 65 33 5f 66 74 73 5f 69 6e 69 74 0a 20 20  ite3_fts_init.  
1b20: 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 66 74 73  <li> sqlite3_fts
1b30: 35 5f 69 6e 69 74 0a 3c 2f 75 6c 3e 0a 0a 3c 70  5_init.</ul>..<p
1b40: 3e 0a 20 20 54 68 65 20 6f 74 68 65 72 20 66 69  >.  The other fi
1b50: 6c 65 2c 20 22 66 74 73 35 2e 68 22 2c 20 69 73  le, "fts5.h", is
1b60: 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
1b70: 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 46 54 53   compile the FTS
1b80: 35 20 65 78 74 65 6e 73 69 6f 6e 2e 20 0a 20 20  5 extension. .  
1b90: 49 74 20 69 73 20 75 73 65 64 20 62 79 20 61 70  It is used by ap
1ba0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1bb0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 45 78 74 65 6e  implement [Exten
1bc0: 64 69 6e 67 20 46 54 53 35 20 7c 20 63 75 73 74  ding FTS5 | cust
1bd0: 6f 6d 20 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65  om FTS5 tokenize
1be0: 72 73 20 6f 72 20 61 75 78 69 6c 69 61 72 79 20  rs or auxiliary 
1bf0: 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 68 31  functions]...<h1
1c00: 20 74 61 67 73 3d 22 46 54 53 35 20 71 75 65 72   tags="FTS5 quer
1c10: 79 20 73 79 6e 74 61 78 22 3e 46 75 6c 6c 2d 74  y syntax">Full-t
1c20: 65 78 74 20 51 75 65 72 79 20 53 79 6e 74 61 78  ext Query Syntax
1c30: 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66  </h1>..<p>.The f
1c40: 6f 6c 6c 6f 77 69 6e 67 20 62 6c 6f 63 6b 20 63  ollowing block c
1c50: 6f 6e 74 61 69 6e 73 20 61 20 73 75 6d 6d 61 72  ontains a summar
1c60: 79 20 6f 66 20 74 68 65 20 46 54 53 20 71 75 65  y of the FTS que
1c70: 72 79 20 73 79 6e 74 61 78 20 69 6e 20 42 4e 46  ry syntax in BNF
1c80: 20 66 6f 72 6d 2e 0a 41 20 64 65 74 61 69 6c 65   form..A detaile
1c90: 64 20 65 78 70 6c 61 6e 61 74 69 6f 6e 20 66 6f  d explanation fo
1ca0: 6c 6c 6f 77 73 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  llows...<codeblo
1cb0: 63 6b 3e 0a 26 6c 74 3b 70 68 72 61 73 65 26 67  ck>.&lt;phrase&g
1cc0: 74 3b 20 20 20 20 3a 3d 20 73 74 72 69 6e 67 20  t;    := string 
1cd0: 26 23 39 31 3b 2a 5d 0a 26 6c 74 3b 70 68 72 61  &#91;*].&lt;phra
1ce0: 73 65 26 67 74 3b 20 20 20 20 3a 3d 20 26 6c 74  se&gt;    := &lt
1cf0: 3b 70 68 72 61 73 65 26 67 74 3b 20 2b 20 26 6c  ;phrase&gt; + &l
1d00: 74 3b 70 68 72 61 73 65 26 67 74 3b 0a 26 6c 74  t;phrase&gt;.&lt
1d10: 3b 6e 65 61 72 67 72 6f 75 70 26 67 74 3b 20 3a  ;neargroup&gt; :
1d20: 3d 20 4e 45 41 52 20 28 20 26 6c 74 3b 70 68 72  = NEAR ( &lt;phr
1d30: 61 73 65 26 67 74 3b 20 26 6c 74 3b 70 68 72 61  ase&gt; &lt;phra
1d40: 73 65 26 67 74 3b 20 2e 2e 2e 20 26 23 39 31 3b  se&gt; ... &#91;
1d50: 2c 20 4e 5d 20 29 0a 26 6c 74 3b 71 75 65 72 79  , N] ).&lt;query
1d60: 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 23 39 31  &gt;     := &#91
1d70: 3b 20 26 23 39 31 3b 2d 5d 20 26 6c 74 3b 63 6f  ; &#91;-] &lt;co
1d80: 6c 73 70 65 63 26 67 74 3b 20 3a 5d 20 26 23 39  lspec&gt; :] &#9
1d90: 31 3b 26 23 39 34 3b 5d 20 26 6c 74 3b 70 68 72  1;&#94;] &lt;phr
1da0: 61 73 65 26 67 74 3b 0a 26 6c 74 3b 71 75 65 72  ase&gt;.&lt;quer
1db0: 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 23 39  y&gt;     := &#9
1dc0: 31 3b 20 26 23 39 31 3b 2d 5d 20 26 6c 74 3b 63  1; &#91;-] &lt;c
1dd0: 6f 6c 73 70 65 63 26 67 74 3b 20 3a 5d 20 26 6c  olspec&gt; :] &l
1de0: 74 3b 6e 65 61 72 67 72 6f 75 70 26 67 74 3b 0a  t;neargroup&gt;.
1df0: 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 20 20  &lt;query&gt;   
1e00: 20 20 3a 3d 20 26 23 39 31 3b 20 26 23 39 31 3b    := &#91; &#91;
1e10: 2d 5d 20 26 6c 74 3b 63 6f 6c 73 70 65 63 26 67  -] &lt;colspec&g
1e20: 74 3b 20 3a 5d 20 28 20 26 6c 74 3b 71 75 65 72  t; :] ( &lt;quer
1e30: 79 26 67 74 3b 20 29 0a 26 6c 74 3b 71 75 65 72  y&gt; ).&lt;quer
1e40: 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 6c 74  y&gt;     := &lt
1e50: 3b 71 75 65 72 79 26 67 74 3b 20 41 4e 44 20 26  ;query&gt; AND &
1e60: 6c 74 3b 71 75 65 72 79 26 67 74 3b 0a 26 6c 74  lt;query&gt;.&lt
1e70: 3b 71 75 65 72 79 26 67 74 3b 20 20 20 20 20 3a  ;query&gt;     :
1e80: 3d 20 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20  = &lt;query&gt; 
1e90: 4f 52 20 26 6c 74 3b 71 75 65 72 79 26 67 74 3b  OR &lt;query&gt;
1ea0: 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 20  .&lt;query&gt;  
1eb0: 20 20 20 3a 3d 20 26 6c 74 3b 71 75 65 72 79 26     := &lt;query&
1ec0: 67 74 3b 20 4e 4f 54 20 26 6c 74 3b 71 75 65 72  gt; NOT &lt;quer
1ed0: 79 26 67 74 3b 0a 26 6c 74 3b 63 6f 6c 73 70 65  y&gt;.&lt;colspe
1ee0: 63 26 67 74 3b 20 20 20 3a 3d 20 63 6f 6c 6e 61  c&gt;   := colna
1ef0: 6d 65 0a 26 6c 74 3b 63 6f 6c 73 70 65 63 26 67  me.&lt;colspec&g
1f00: 74 3b 20 20 20 3a 3d 20 7b 20 63 6f 6c 6e 61 6d  t;   := { colnam
1f10: 65 31 20 63 6f 6c 6e 61 6d 65 32 20 2e 2e 2e 20  e1 colname2 ... 
1f20: 7d 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  }.</codeblock>..
1f30: 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 53  <h2 tags="FTS5 S
1f40: 74 72 69 6e 67 73 22 3e 46 54 53 35 20 53 74 72  trings">FTS5 Str
1f50: 69 6e 67 73 3c 2f 68 32 3e 0a 3c 70 3e 0a 57 69  ings</h2>.<p>.Wi
1f60: 74 68 69 6e 20 61 6e 20 46 54 53 20 65 78 70 72  thin an FTS expr
1f70: 65 73 73 69 6f 6e 20 61 20 3c 62 3e 73 74 72 69  ession a <b>stri
1f80: 6e 67 3c 2f 62 3e 20 6d 61 79 20 62 65 20 73 70  ng</b> may be sp
1f90: 65 63 69 66 69 65 64 20 69 6e 20 6f 6e 65 20 6f  ecified in one o
1fa0: 66 20 74 77 6f 20 77 61 79 73 3a 0a 0a 3c 75 6c  f two ways:..<ul
1fb0: 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 42 79 20 65  >.  <li> <p>By e
1fc0: 6e 63 6c 6f 73 69 6e 67 20 69 74 20 69 6e 20 64  nclosing it in d
1fd0: 6f 75 62 6c 65 20 71 75 6f 74 65 73 20 28 22 29  ouble quotes (")
1fe0: 2e 20 57 69 74 68 69 6e 20 61 20 73 74 72 69 6e  . Within a strin
1ff0: 67 2c 20 61 6e 79 20 65 6d 62 65 64 64 65 64 0a  g, any embedded.
2000: 20 20 20 20 20 20 20 64 6f 75 62 6c 65 20 71 75         double qu
2010: 6f 74 65 20 63 68 61 72 61 63 74 65 72 73 20 6d  ote characters m
2020: 61 79 20 62 65 20 65 73 63 61 70 65 64 20 53 51  ay be escaped SQ
2030: 4c 2d 73 74 79 6c 65 20 2d 20 62 79 20 61 64 64  L-style - by add
2040: 69 6e 67 20 61 20 73 65 63 6f 6e 64 0a 20 20 20  ing a second.   
2050: 20 20 20 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65      double-quote
2060: 20 63 68 61 72 61 63 74 65 72 2e 0a 0a 20 20 3c   character...  <
2070: 6c 69 3e 20 3c 70 3e 41 73 20 61 6e 20 46 54 53  li> <p>As an FTS
2080: 35 20 62 61 72 65 77 6f 72 64 20 74 68 61 74 20  5 bareword that 
2090: 69 73 20 6e 6f 74 20 22 41 4e 44 22 2c 20 22 4f  is not "AND", "O
20a0: 52 22 20 6f 72 20 22 4e 4f 54 22 20 28 63 61 73  R" or "NOT" (cas
20b0: 65 20 73 65 6e 73 69 74 69 76 65 29 2e 20 0a 20  e sensitive). . 
20c0: 20 20 20 20 20 20 41 6e 20 46 54 53 35 20 62 61        An FTS5 ba
20d0: 72 65 77 6f 72 64 20 69 73 20 61 20 73 74 72 69  reword is a stri
20e0: 6e 67 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ng of one or mor
20f0: 65 20 63 6f 6e 73 65 63 75 74 69 76 65 20 63 68  e consecutive ch
2100: 61 72 61 63 74 65 72 73 20 74 68 61 74 0a 20 20  aracters that.  
2110: 20 20 20 20 20 61 72 65 20 61 6c 6c 20 65 69 74       are all eit
2120: 68 65 72 3a 0a 20 20 20 20 20 20 20 0a 20 20 20  her:.       .   
2130: 20 20 20 20 3c 75 6c 3e 0a 20 20 20 20 20 20 20      <ul>.       
2140: 20 20 3c 6c 69 3e 20 4e 6f 6e 2d 41 53 43 49 49    <li> Non-ASCII
2150: 20 72 61 6e 67 65 20 63 68 61 72 61 63 74 65 72   range character
2160: 73 20 28 69 2e 65 2e 20 75 6e 69 63 6f 64 65 20  s (i.e. unicode 
2170: 63 6f 64 65 70 6f 69 6e 74 73 20 67 72 65 61 74  codepoints great
2180: 65 72 20 0a 20 20 20 20 20 20 20 20 20 20 20 20  er .            
2190: 20 20 74 68 61 6e 20 31 32 37 29 2c 20 6f 72 20    than 127), or 
21a0: 0a 20 20 20 20 20 20 20 20 20 3c 6c 69 3e 20 4f  .         <li> O
21b0: 6e 65 20 6f 66 20 74 68 65 20 35 32 20 75 70 70  ne of the 52 upp
21c0: 65 72 20 61 6e 64 20 6c 6f 77 65 72 20 63 61 73  er and lower cas
21d0: 65 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  e ASCII characte
21e0: 72 73 2c 20 6f 72 0a 20 20 20 20 20 20 20 20 20  rs, or.         
21f0: 3c 6c 69 3e 20 4f 6e 65 20 6f 66 20 74 68 65 20  <li> One of the 
2200: 31 30 20 64 65 63 69 6d 61 6c 20 64 69 67 69 74  10 decimal digit
2210: 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
2220: 73 2c 20 6f 72 0a 20 20 20 20 20 20 20 20 20 3c  s, or.         <
2230: 6c 69 3e 20 54 68 65 20 75 6e 64 65 72 73 63 6f  li> The undersco
2240: 72 65 20 63 68 61 72 61 63 74 65 72 20 28 75 6e  re character (un
2250: 69 63 6f 64 65 20 63 6f 64 65 70 6f 69 6e 74 20  icode codepoint 
2260: 39 36 29 2e 0a 20 20 20 20 20 20 20 20 20 3c 6c  96)..         <l
2270: 69 3e 20 54 68 65 20 73 75 62 73 74 69 74 75 74  i> The substitut
2280: 65 20 63 68 61 72 61 63 74 65 72 20 28 75 6e 69  e character (uni
2290: 63 6f 64 65 20 63 6f 64 65 70 6f 69 6e 74 20 32  code codepoint 2
22a0: 36 29 2e 0a 20 20 20 20 20 20 20 3c 2f 75 6c 3e  6)..       </ul>
22b0: 0a 0a 20 20 20 20 20 20 20 53 74 72 69 6e 67 73  ..       Strings
22c0: 20 74 68 61 74 20 69 6e 63 6c 75 64 65 20 61 6e   that include an
22d0: 79 20 6f 74 68 65 72 20 63 68 61 72 61 63 74 65  y other characte
22e0: 72 73 20 6d 75 73 74 20 62 65 20 71 75 6f 74 65  rs must be quote
22f0: 64 2e 20 43 68 61 72 61 63 74 65 72 73 0a 20 20  d. Characters.  
2300: 20 20 20 20 20 74 68 61 74 20 61 72 65 20 6e 6f       that are no
2310: 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
2320: 77 65 64 20 69 6e 20 62 61 72 65 77 6f 72 64 73  wed in barewords
2330: 2c 20 61 72 65 20 6e 6f 74 20 71 75 6f 74 65 20  , are not quote 
2340: 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 20  characters and. 
2350: 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 75 72        do not cur
2360: 72 65 6e 74 6c 79 20 73 65 72 76 65 20 61 6e 79  rently serve any
2370: 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65   special purpose
2380: 20 69 6e 20 46 54 53 35 20 71 75 65 72 79 20 65   in FTS5 query e
2390: 78 70 72 65 73 73 69 6f 6e 73 20 6d 61 79 0a 20  xpressions may. 
23a0: 20 20 20 20 20 20 61 74 20 73 6f 6d 65 20 70 6f        at some po
23b0: 69 6e 74 20 69 6e 20 74 68 65 20 66 75 74 75 72  int in the futur
23c0: 65 20 62 65 20 61 6c 6c 6f 77 65 64 20 69 6e 20  e be allowed in 
23d0: 62 61 72 65 77 6f 72 64 73 20 6f 72 20 75 73 65  barewords or use
23e0: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 20  d to implement. 
23f0: 20 20 20 20 20 20 6e 65 77 20 71 75 65 72 79 20        new query 
2400: 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 2e 20 54  functionality. T
2410: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 71  his means that q
2420: 75 65 72 69 65 73 20 74 68 61 74 20 61 72 65 20  ueries that are 
2430: 63 75 72 72 65 6e 74 6c 79 0a 20 20 20 20 20 20  currently.      
2440: 20 73 79 6e 74 61 78 20 65 72 72 6f 72 73 20 62   syntax errors b
2450: 65 63 61 75 73 65 20 74 68 65 79 20 69 6e 63 6c  ecause they incl
2460: 75 64 65 20 73 75 63 68 20 61 20 63 68 61 72 61  ude such a chara
2470: 63 74 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  cter outside of 
2480: 61 20 71 75 6f 74 65 64 0a 20 20 20 20 20 20 20  a quoted.       
2490: 73 74 72 69 6e 67 20 6d 61 79 20 62 65 20 69 6e  string may be in
24a0: 74 65 72 70 72 65 74 65 64 20 64 69 66 66 65 72  terpreted differ
24b0: 65 6e 74 6c 79 20 62 79 20 73 6f 6d 65 20 66 75  ently by some fu
24c0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6f 66 20  ture version of 
24d0: 46 54 53 35 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 68 32  FTS5..</ul>..<h2
24e0: 20 74 61 67 73 3d 22 46 54 53 35 20 50 68 72 61   tags="FTS5 Phra
24f0: 73 65 73 22 3e 46 54 53 35 20 50 68 72 61 73 65  ses">FTS5 Phrase
2500: 73 3c 2f 68 32 3e 0a 3c 70 3e 0a 46 54 53 20 71  s</h2>.<p>.FTS q
2510: 75 65 72 69 65 73 20 61 72 65 20 6d 61 64 65 20  ueries are made 
2520: 75 70 20 6f 66 20 3c 62 3e 70 68 72 61 73 65 73  up of <b>phrases
2530: 3c 2f 62 3e 2e 20 41 20 70 68 72 61 73 65 20 69  </b>. A phrase i
2540: 73 20 61 6e 20 6f 72 64 65 72 65 64 20 6c 69 73  s an ordered lis
2550: 74 20 6f 66 20 0a 6f 6e 65 20 6f 72 20 6d 6f 72  t of .one or mor
2560: 65 20 74 6f 6b 65 6e 73 2e 20 41 20 73 74 72 69  e tokens. A stri
2570: 6e 67 20 69 73 20 74 72 61 6e 73 66 6f 72 6d 65  ng is transforme
2580: 64 20 69 6e 74 6f 20 61 20 70 68 72 61 73 65 20  d into a phrase 
2590: 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
25a0: 0a 74 68 65 20 46 54 53 20 74 61 62 6c 65 20 74  .the FTS table t
25b0: 6f 6b 65 6e 69 7a 65 72 2e 20 54 77 6f 20 70 68  okenizer. Two ph
25c0: 72 61 73 65 73 20 63 61 6e 20 62 65 20 63 6f 6e  rases can be con
25d0: 63 61 74 65 6e 61 74 65 64 20 69 6e 74 6f 20 61  catenated into a
25e0: 20 73 69 6e 67 6c 65 20 0a 6c 61 72 67 65 20 70   single .large p
25f0: 68 72 61 73 65 20 75 73 69 6e 67 20 74 68 65 20  hrase using the 
2600: 22 2b 22 20 6f 70 65 72 61 74 6f 72 2e 20 46 6f  "+" operator. Fo
2610: 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
2620: 69 6e 67 20 74 68 65 20 74 6f 6b 65 6e 69 7a 65  ing the tokenize
2630: 72 0a 6d 6f 64 75 6c 65 20 62 65 69 6e 67 20 75  r.module being u
2640: 73 65 64 20 74 6f 6b 65 6e 69 7a 65 73 20 74 68  sed tokenizes th
2650: 65 20 69 6e 70 75 74 20 22 6f 6e 65 2e 74 77 6f  e input "one.two
2660: 2e 74 68 72 65 65 22 20 74 6f 20 74 68 72 65 65  .three" to three
2670: 20 73 65 70 61 72 61 74 65 0a 74 6f 6b 65 6e 73   separate.tokens
2680: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
2690: 74 68 72 65 65 20 71 75 65 72 69 65 73 20 61 6c  three queries al
26a0: 6c 20 73 70 65 63 69 66 79 20 74 68 65 20 73 61  l specify the sa
26b0: 6d 65 20 70 68 72 61 73 65 3a 0a 0a 3c 63 6f 64  me phrase:..<cod
26c0: 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41  eblock>.  ... MA
26d0: 54 43 48 20 27 22 6f 6e 65 20 74 77 6f 20 74 68  TCH '"one two th
26e0: 72 65 65 22 27 0a 20 20 2e 2e 2e 20 4d 41 54 43  ree"'.  ... MATC
26f0: 48 20 27 6f 6e 65 20 2b 20 74 77 6f 20 2b 20 74  H 'one + two + t
2700: 68 72 65 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43  hree'.  ... MATC
2710: 48 20 27 22 6f 6e 65 20 74 77 6f 22 20 2b 20 74  H '"one two" + t
2720: 68 72 65 65 27 0a 20 20 2e 2e 2e 20 4d 41 54 43  hree'.  ... MATC
2730: 48 20 27 6f 6e 65 2e 74 77 6f 2e 74 68 72 65 65  H 'one.two.three
2740: 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  '.</codeblock>..
2750: 3c 70 3e 0a 41 20 70 68 72 61 73 65 20 6d 61 74  <p>.A phrase mat
2760: 63 68 65 73 20 61 20 64 6f 63 75 6d 65 6e 74 20  ches a document 
2770: 69 66 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20  if the document 
2780: 63 6f 6e 74 61 69 6e 73 20 61 74 20 6c 65 61 73  contains at leas
2790: 74 20 6f 6e 65 20 73 75 62 2d 73 65 71 75 65 6e  t one sub-sequen
27a0: 63 65 0a 6f 66 20 74 6f 6b 65 6e 73 20 74 68 61  ce.of tokens tha
27b0: 74 20 6d 61 74 63 68 65 73 20 74 68 65 20 73 65  t matches the se
27c0: 71 75 65 6e 63 65 20 6f 66 20 74 6f 6b 65 6e 73  quence of tokens
27d0: 20 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68   that make up th
27e0: 65 20 70 68 72 61 73 65 2e 0a 0a 3c 68 32 20 74  e phrase...<h2 t
27f0: 61 67 73 3d 22 46 54 53 35 20 70 72 65 66 69 78  ags="FTS5 prefix
2800: 20 71 75 65 72 69 65 73 22 3e 46 54 53 35 20 50   queries">FTS5 P
2810: 72 65 66 69 78 20 51 75 65 72 69 65 73 3c 2f 68  refix Queries</h
2820: 32 3e 0a 3c 70 3e 0a 49 66 20 61 20 22 2a 22 20  2>.<p>.If a "*" 
2830: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
2840: 73 20 61 20 73 74 72 69 6e 67 20 77 69 74 68 69  s a string withi
2850: 6e 20 61 6e 20 46 54 53 20 65 78 70 72 65 73 73  n an FTS express
2860: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 66 69  ion, then the fi
2870: 6e 61 6c 0a 74 6f 6b 65 6e 20 65 78 74 72 61 63  nal.token extrac
2880: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 73 74 72  ted from the str
2890: 69 6e 67 20 69 73 20 6d 61 72 6b 65 64 20 61 73  ing is marked as
28a0: 20 61 20 3c 62 3e 70 72 65 66 69 78 20 74 6f 6b   a <b>prefix tok
28b0: 65 6e 3c 2f 62 3e 2e 20 41 73 20 79 6f 75 0a 6d  en</b>. As you.m
28c0: 69 67 68 74 20 65 78 70 65 63 74 2c 20 61 20 70  ight expect, a p
28d0: 72 65 66 69 78 20 74 6f 6b 65 6e 20 6d 61 74 63  refix token matc
28e0: 68 65 73 20 61 6e 79 20 64 6f 63 75 6d 65 6e 74  hes any document
28f0: 20 74 6f 6b 65 6e 20 6f 66 20 77 68 69 63 68 20   token of which 
2900: 69 74 20 69 73 20 61 20 0a 70 72 65 66 69 78 2e  it is a .prefix.
2910: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68   For example, th
2920: 65 20 66 69 72 73 74 20 74 77 6f 20 71 75 65 72  e first two quer
2930: 69 65 73 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  ies in the follo
2940: 77 69 6e 67 20 62 6c 6f 63 6b 20 77 69 6c 6c 20  wing block will 
2950: 6d 61 74 63 68 0a 61 6e 79 20 64 6f 63 75 6d 65  match.any docume
2960: 6e 74 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  nt that contains
2970: 20 74 68 65 20 74 6f 6b 65 6e 20 22 6f 6e 65 22   the token "one"
2980: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 66 6f 6c   immediately fol
2990: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 74 6f 6b  lowed by the tok
29a0: 65 6e 0a 22 74 77 6f 22 20 61 6e 64 20 74 68 65  en."two" and the
29b0: 6e 20 61 6e 79 20 74 6f 6b 65 6e 20 74 68 61 74  n any token that
29c0: 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 74 68   begins with "th
29d0: 72 22 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  r"...<codeblock>
29e0: 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 22 6f  .  ... MATCH '"o
29f0: 6e 65 20 74 77 6f 20 74 68 72 22 20 2a 20 27 0a  ne two thr" * '.
2a00: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 6f 6e 65    ... MATCH 'one
2a10: 20 2b 20 74 77 6f 20 2b 20 74 68 72 2a 27 0a 20   + two + thr*'. 
2a20: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 22 6f 6e 65   ... MATCH '"one
2a30: 20 74 77 6f 20 74 68 72 2a 22 27 20 20 20 20 20   two thr*"'     
2a40: 20 3c 62 3e 2d 2d 20 4d 61 79 20 6e 6f 74 20 77   <b>-- May not w
2a50: 6f 72 6b 20 61 73 20 65 78 70 65 63 74 65 64 21  ork as expected!
2a60: 3c 2f 62 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  </b>.</codeblock
2a70: 3e 0a 0a 3c 70 3e 54 68 65 20 66 69 6e 61 6c 20  >..<p>The final 
2a80: 71 75 65 72 79 20 69 6e 20 74 68 65 20 62 6c 6f  query in the blo
2a90: 63 6b 20 61 62 6f 76 65 20 6d 61 79 20 6e 6f 74  ck above may not
2aa0: 20 77 6f 72 6b 20 61 73 20 65 78 70 65 63 74 65   work as expecte
2ab0: 64 2e 20 42 65 63 61 75 73 65 20 74 68 65 0a 22  d. Because the."
2ac0: 2a 22 20 63 68 61 72 61 63 74 65 72 20 69 73 20  *" character is 
2ad0: 69 6e 73 69 64 65 20 74 68 65 20 64 6f 75 62 6c  inside the doubl
2ae0: 65 2d 71 75 6f 74 65 73 2c 20 69 74 20 77 69 6c  e-quotes, it wil
2af0: 6c 20 62 65 20 70 61 73 73 65 64 20 74 6f 20 74  l be passed to t
2b00: 68 65 20 74 6f 6b 65 6e 69 7a 65 72 2c 0a 77 68  he tokenizer,.wh
2b10: 69 63 68 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ich will likely 
2b20: 64 69 73 63 61 72 64 20 69 74 20 28 6f 72 20 70  discard it (or p
2b30: 65 72 68 61 70 73 2c 20 64 65 70 65 6e 64 69 6e  erhaps, dependin
2b40: 67 20 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69  g on the specifi
2b50: 63 20 74 6f 6b 65 6e 69 7a 65 72 0a 69 6e 20 75  c tokenizer.in u
2b60: 73 65 2c 20 69 6e 63 6c 75 64 65 20 69 74 20 61  se, include it a
2b70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  s part of the fi
2b80: 6e 61 6c 20 74 6f 6b 65 6e 29 20 69 6e 73 74 65  nal token) inste
2b90: 61 64 20 6f 66 20 72 65 63 6f 67 6e 69 7a 69 6e  ad of recognizin
2ba0: 67 20 69 74 20 61 73 0a 61 20 73 70 65 63 69 61  g it as.a specia
2bb0: 6c 20 46 54 53 20 63 68 61 72 61 63 74 65 72 2e  l FTS character.
2bc0: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
2bd0: 6e 74 20 63 61 72 72 6f 74 71 20 7b 46 54 53 35  nt carrotq {FTS5
2be0: 20 69 6e 69 74 69 61 6c 20 74 6f 6b 65 6e 7d 3c   initial token}<
2bf0: 2f 74 63 6c 3e 0a 3c 68 32 20 74 61 67 73 3d 22  /tcl>.<h2 tags="
2c00: 46 54 53 35 20 69 6e 69 74 69 61 6c 20 74 6f 6b  FTS5 initial tok
2c10: 65 6e 20 71 75 65 72 69 65 73 22 3e 46 54 53 35  en queries">FTS5
2c20: 20 49 6e 69 74 69 61 6c 20 54 6f 6b 65 6e 20 51   Initial Token Q
2c30: 75 65 72 69 65 73 3c 2f 68 32 3e 0a 3c 70 3e 0a  ueries</h2>.<p>.
2c40: 49 66 20 61 20 22 26 23 39 34 3b 22 20 63 68 61  If a "&#94;" cha
2c50: 72 61 63 74 65 72 20 61 70 70 65 61 72 73 20 69  racter appears i
2c60: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
2c70: 65 20 61 20 70 68 72 61 73 65 20 74 68 61 74 20  e a phrase that 
2c80: 69 73 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 61  is not part of a
2c90: 0a 4e 45 41 52 20 71 75 65 72 79 2c 20 74 68 65  .NEAR query, the
2ca0: 6e 20 74 68 61 74 20 70 68 72 61 73 65 20 6f 6e  n that phrase on
2cb0: 6c 79 20 6d 61 74 63 68 65 73 20 61 20 64 6f 63  ly matches a doc
2cc0: 75 6d 65 6e 74 20 6f 6e 6c 79 20 69 66 20 69 74  ument only if it
2cd0: 20 73 74 61 72 74 73 20 61 74 20 74 68 65 0a 66   starts at the.f
2ce0: 69 72 73 74 20 74 6f 6b 65 6e 20 69 6e 20 61 20  irst token in a 
2cf0: 63 6f 6c 75 6d 6e 2e 20 54 68 65 20 22 26 23 39  column. The "&#9
2d00: 34 3b 22 20 73 79 6e 74 61 78 20 6d 61 79 20 62  4;" syntax may b
2d10: 65 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  e combined with 
2d20: 61 20 0a 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 20  a .[FTS5 column 
2d30: 66 69 6c 74 65 72 73 7c 63 6f 6c 75 6d 6e 20 66  filters|column f
2d40: 69 6c 74 65 72 5d 2c 20 62 75 74 20 6d 61 79 20  ilter], but may 
2d50: 6e 6f 74 20 62 65 20 69 6e 73 65 72 74 65 64 20  not be inserted 
2d60: 69 6e 74 6f 20 74 68 65 20 6d 69 64 64 6c 65 20  into the middle 
2d70: 6f 66 0a 61 20 70 68 72 61 73 65 2e 0a 0a 3c 63  of.a phrase...<c
2d80: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20  odeblock>.  ... 
2d90: 4d 41 54 43 48 20 27 26 23 39 34 3b 6f 6e 65 27  MATCH '&#94;one'
2da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69                <i
2db0: 3e 2d 2d 20 66 69 72 73 74 20 74 6f 6b 65 6e 20  >-- first token 
2dc0: 69 6e 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6d 75  in any column mu
2dd0: 73 74 20 62 65 20 22 6f 6e 65 22 3c 2f 69 3e 0a  st be "one"</i>.
2de0: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 26 23 39    ... MATCH '&#9
2df0: 34 3b 20 6f 6e 65 20 2b 20 74 77 6f 27 20 20 20  4; one + two'   
2e00: 20 20 20 20 3c 69 3e 2d 2d 20 70 68 72 61 73 65      <i>-- phrase
2e10: 20 22 6f 6e 65 20 74 77 6f 22 20 6d 75 73 74 20   "one two" must 
2e20: 61 70 70 65 61 72 20 61 74 20 73 74 61 72 74 20  appear at start 
2e30: 6f 66 20 61 20 63 6f 6c 75 6d 6e 3c 2f 69 3e 0a  of a column</i>.
2e40: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 26 23 39    ... MATCH '&#9
2e50: 34 3b 20 22 6f 6e 65 20 74 77 6f 22 27 20 20 20  4; "one two"'   
2e60: 20 20 20 20 3c 69 3e 2d 2d 20 73 61 6d 65 20 61      <i>-- same a
2e70: 73 20 70 72 65 76 69 6f 75 73 20 3c 2f 69 3e 0a  s previous </i>.
2e80: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 61 20 3a    ... MATCH 'a :
2e90: 20 26 23 39 34 3b 74 77 6f 27 20 20 20 20 20 20   &#94;two'      
2ea0: 20 20 20 20 3c 69 3e 2d 2d 20 66 69 72 73 74 20      <i>-- first 
2eb0: 74 6f 6b 65 6e 20 6f 66 20 63 6f 6c 75 6d 6e 20  token of column 
2ec0: 22 61 22 20 6d 75 73 74 20 62 65 20 22 74 77 6f  "a" must be "two
2ed0: 22 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43  "</i>.  ... MATC
2ee0: 48 20 27 4e 45 41 52 28 26 23 39 34 3b 6f 6e 65  H 'NEAR(&#94;one
2ef0: 2c 20 74 77 6f 29 27 20 20 20 3c 62 3e 2d 2d 20  , two)'   <b>-- 
2f00: 73 79 6e 74 61 78 20 65 72 72 6f 72 21 20 3c 2f  syntax error! </
2f10: 62 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  b>.  ... MATCH '
2f20: 6f 6e 65 20 2b 20 26 23 39 34 3b 74 77 6f 27 20  one + &#94;two' 
2f30: 20 20 20 20 20 20 20 3c 62 3e 2d 2d 20 73 79 6e         <b>-- syn
2f40: 74 61 78 20 65 72 72 6f 72 21 20 3c 2f 62 3e 0a  tax error! </b>.
2f50: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 22 26 23    ... MATCH '"&#
2f60: 39 34 3b 6f 6e 65 20 74 77 6f 22 27 20 20 20 20  94;one two"'    
2f70: 20 20 20 20 3c 62 3e 2d 2d 20 4d 61 79 20 6e 6f      <b>-- May no
2f80: 74 20 77 6f 72 6b 20 61 73 20 65 78 70 65 63 74  t work as expect
2f90: 65 64 21 3c 2f 62 3e 0a 3c 2f 63 6f 64 65 62 6c  ed!</b>.</codebl
2fa0: 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ock>..<h2 tags="
2fb0: 46 54 53 35 20 4e 45 41 52 20 71 75 65 72 69 65  FTS5 NEAR querie
2fc0: 73 22 3e 46 54 53 35 20 4e 45 41 52 20 51 75 65  s">FTS5 NEAR Que
2fd0: 72 69 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 77  ries</h2>..<p>Tw
2fe0: 6f 20 6f 72 20 6d 6f 72 65 20 70 68 72 61 73 65  o or more phrase
2ff0: 73 20 6d 61 79 20 62 65 20 67 72 6f 75 70 65 64  s may be grouped
3000: 20 69 6e 74 6f 20 61 20 3c 62 3e 4e 45 41 52 20   into a <b>NEAR 
3010: 67 72 6f 75 70 3c 2f 62 3e 2e 20 41 20 4e 45 41  group</b>. A NEA
3020: 52 20 67 72 6f 75 70 0a 69 73 20 73 70 65 63 69  R group.is speci
3030: 66 69 65 64 20 62 79 20 74 68 65 20 74 6f 6b 65  fied by the toke
3040: 6e 20 22 4e 45 41 52 22 20 28 63 61 73 65 20 73  n "NEAR" (case s
3050: 65 6e 73 69 74 69 76 65 29 20 66 6f 6c 6c 6f 77  ensitive) follow
3060: 65 64 20 62 79 20 61 6e 20 6f 70 65 6e 0a 70 61  ed by an open.pa
3070: 72 65 6e 74 68 65 73 69 73 20 63 68 61 72 61 63  renthesis charac
3080: 74 65 72 2c 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ter, followed by
3090: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 77 68 69   two or more whi
30a0: 74 65 73 70 61 63 65 20 73 65 70 61 72 61 74 65  tespace separate
30b0: 64 20 70 68 72 61 73 65 73 2c 20 6f 70 74 69 6f  d phrases, optio
30c0: 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
30d0: 79 20 61 20 63 6f 6d 6d 61 20 61 6e 64 20 74 68  y a comma and th
30e0: 65 20 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65  e numeric parame
30f0: 74 65 72 20 3c 69 3e 4e 3c 2f 69 3e 2c 20 66 6f  ter <i>N</i>, fo
3100: 6c 6c 6f 77 65 64 20 62 79 0a 61 20 63 6c 6f 73  llowed by.a clos
3110: 65 20 70 61 72 65 6e 74 68 65 73 69 73 2e 20 46  e parenthesis. F
3120: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
3130: 64 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d  deblock>.  ... M
3140: 41 54 43 48 20 27 4e 45 41 52 28 22 6f 6e 65 20  ATCH 'NEAR("one 
3150: 74 77 6f 22 20 22 74 68 72 65 65 20 66 6f 75 72  two" "three four
3160: 22 2c 20 31 30 29 27 0a 20 20 2e 2e 2e 20 4d 41  ", 10)'.  ... MA
3170: 54 43 48 20 27 4e 45 41 52 28 22 6f 6e 65 20 74  TCH 'NEAR("one t
3180: 77 6f 22 20 74 68 72 2a 20 2b 20 66 6f 75 72 29  wo" thr* + four)
3190: 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  '.</codeblock>..
31a0: 3c 70 3e 49 66 20 6e 6f 20 3c 69 3e 4e 3c 2f 69  <p>If no <i>N</i
31b0: 3e 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 73  > parameter is s
31c0: 75 70 70 6c 69 65 64 2c 20 69 74 20 64 65 66 61  upplied, it defa
31d0: 75 6c 74 73 20 74 6f 20 31 30 2e 20 41 20 4e 45  ults to 10. A NE
31e0: 41 52 20 67 72 6f 75 70 0a 6d 61 74 63 68 65 73  AR group.matches
31f0: 20 61 20 64 6f 63 75 6d 65 6e 74 20 69 66 20 74   a document if t
3200: 68 65 20 64 6f 63 75 6d 65 6e 74 20 63 6f 6e 74  he document cont
3210: 61 69 6e 73 20 61 74 20 6c 65 61 73 74 20 6f 6e  ains at least on
3220: 65 20 63 6c 75 6d 70 20 6f 66 20 74 6f 6b 65 6e  e clump of token
3230: 73 20 74 68 61 74 3a 20 0a 0a 3c 6f 6c 3e 20 0a  s that: ..<ol> .
3240: 20 20 3c 6c 69 3e 20 63 6f 6e 74 61 69 6e 73 20    <li> contains 
3250: 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73  at least one ins
3260: 74 61 6e 63 65 20 6f 66 20 65 61 63 68 20 70 68  tance of each ph
3270: 72 61 73 65 2c 20 61 6e 64 20 0a 20 20 3c 6c 69  rase, and .  <li
3280: 3e 20 66 6f 72 20 77 68 69 63 68 20 74 68 65 20  > for which the 
3290: 6e 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73  number of tokens
32a0: 20 62 65 74 77 65 65 6e 20 74 68 65 20 65 6e 64   between the end
32b0: 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 68   of the first ph
32c0: 72 61 73 65 20 0a 20 20 20 20 20 20 20 61 6e 64  rase .       and
32d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
32e0: 66 20 74 68 65 20 6c 61 73 74 20 70 68 72 61 73  f the last phras
32f0: 65 20 69 6e 20 74 68 65 20 63 6c 75 6d 70 20 69  e in the clump i
3300: 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
3310: 71 75 61 6c 20 74 6f 20 3c 69 3e 4e 3c 2f 69 3e  qual to <i>N</i>
3320: 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 46 6f 72 20  ..</ol>..<p>For 
3330: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
3340: 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20 56  lock>.  CREATE V
3350: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 20 55  IRTUAL TABLE f U
3360: 53 49 4e 47 20 66 74 73 35 28 78 29 3b 0a 20 20  SING fts5(x);.  
3370: 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 28 72 6f  INSERT INTO f(ro
3380: 77 69 64 2c 20 78 29 20 56 41 4c 55 45 53 28 31  wid, x) VALUES(1
3390: 2c 20 27 41 20 42 20 43 20 44 20 78 20 78 20 78  , 'A B C D x x x
33a0: 20 45 20 46 20 78 27 29 3b 0a 0a 20 20 2e 2e 2e   E F x');..  ...
33b0: 20 4d 41 54 43 48 20 27 4e 45 41 52 28 65 20 64   MATCH 'NEAR(e d
33c0: 2c 20 34 29 27 3b 20 20 20 20 20 20 20 20 20 20  , 4)';          
33d0: 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e 2d              <i>-
33e0: 2d 20 4d 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20  - Matches!</i>. 
33f0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
3400: 28 65 20 64 2c 20 33 29 27 3b 20 20 20 20 20 20  (e d, 3)';      
3410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3420: 3c 69 3e 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f  <i>-- Matches!</
3430: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
3440: 4e 45 41 52 28 65 20 64 2c 20 32 29 27 3b 20 20  NEAR(e d, 2)';  
3450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3460: 20 20 20 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e      <i>-- Does n
3470: 6f 74 20 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20  ot match!</i>.. 
3480: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
3490: 28 22 63 20 64 22 20 22 65 20 66 22 2c 20 33 29  ("c d" "e f", 3)
34a0: 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ';              
34b0: 3c 69 3e 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f  <i>-- Matches!</
34c0: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
34d0: 4e 45 41 52 28 22 63 22 20 20 20 22 65 20 66 22  NEAR("c"   "e f"
34e0: 2c 20 33 29 27 3b 20 20 20 20 20 20 20 20 20 20  , 3)';          
34f0: 20 20 20 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e      <i>-- Does n
3500: 6f 74 20 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20  ot match!</i>.. 
3510: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
3520: 28 61 20 64 20 65 2c 20 36 29 27 3b 20 20 20 20  (a d e, 6)';    
3530: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3540: 3c 69 3e 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f  <i>-- Matches!</
3550: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
3560: 4e 45 41 52 28 61 20 64 20 65 2c 20 35 29 27 3b  NEAR(a d e, 5)';
3570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3580: 20 20 20 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e      <i>-- Does n
3590: 6f 74 20 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 20  ot match!</i>.. 
35a0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52   ... MATCH 'NEAR
35b0: 28 22 61 20 62 20 63 20 64 22 20 22 62 20 63 22  ("a b c d" "b c"
35c0: 20 22 65 20 66 22 2c 20 34 29 27 3b 20 20 20 20   "e f", 4)';    
35d0: 3c 69 3e 2d 2d 20 4d 61 74 63 68 65 73 21 3c 2f  <i>-- Matches!</
35e0: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
35f0: 4e 45 41 52 28 22 61 20 62 20 63 20 64 22 20 22  NEAR("a b c d" "
3600: 62 20 63 22 20 22 65 20 66 22 2c 20 33 29 27 3b  b c" "e f", 3)';
3610: 20 20 20 20 3c 69 3e 2d 2d 20 44 6f 65 73 20 6e      <i>-- Does n
3620: 6f 74 20 6d 61 74 63 68 21 3c 2f 69 3e 0a 0a 3c  ot match!</i>..<
3630: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32  /codeblock>..<h2
3640: 20 74 61 67 73 3d 22 46 54 53 35 20 63 6f 6c 75   tags="FTS5 colu
3650: 6d 6e 20 66 69 6c 74 65 72 73 22 3e 46 54 53 35  mn filters">FTS5
3660: 20 43 6f 6c 75 6d 6e 20 46 69 6c 74 65 72 73 3c   Column Filters<
3670: 2f 68 32 3e 0a 0a 3c 70 3e 0a 41 20 73 69 6e 67  /h2>..<p>.A sing
3680: 6c 65 20 70 68 72 61 73 65 20 6f 72 20 4e 45 41  le phrase or NEA
3690: 52 20 67 72 6f 75 70 20 6d 61 79 20 62 65 20 72  R group may be r
36a0: 65 73 74 72 69 63 74 65 64 20 74 6f 20 6d 61 74  estricted to mat
36b0: 63 68 69 6e 67 20 74 65 78 74 20 77 69 74 68 69  ching text withi
36c0: 6e 20 61 0a 73 70 65 63 69 66 69 65 64 20 63 6f  n a.specified co
36d0: 6c 75 6d 6e 20 6f 66 20 74 68 65 20 46 54 53 20  lumn of the FTS 
36e0: 74 61 62 6c 65 20 62 79 20 70 72 65 66 69 78 69  table by prefixi
36f0: 6e 67 20 69 74 20 77 69 74 68 20 74 68 65 20 63  ng it with the c
3700: 6f 6c 75 6d 6e 20 6e 61 6d 65 20 0a 66 6f 6c 6c  olumn name .foll
3710: 6f 77 65 64 20 62 79 20 61 20 63 6f 6c 6f 6e 20  owed by a colon 
3720: 63 68 61 72 61 63 74 65 72 2e 20 4f 72 20 74 6f  character. Or to
3730: 20 61 20 73 65 74 20 6f 66 20 63 6f 6c 75 6d 6e   a set of column
3740: 73 20 62 79 20 70 72 65 66 69 78 69 6e 67 20 69  s by prefixing i
3750: 74 0a 77 69 74 68 20 61 20 77 68 69 74 65 73 70  t.with a whitesp
3760: 61 63 65 20 73 65 70 61 72 61 74 65 64 20 6c 69  ace separated li
3770: 73 74 20 6f 66 20 63 6f 6c 75 6d 6e 20 6e 61 6d  st of column nam
3780: 65 73 20 65 6e 63 6c 6f 73 65 64 20 69 6e 20 70  es enclosed in p
3790: 61 72 65 6e 74 68 65 73 69 73 0a 28 22 63 75 72  arenthesis.("cur
37a0: 6c 79 20 62 72 61 63 6b 65 74 73 22 29 20 66 6f  ly brackets") fo
37b0: 6c 6c 6f 77 65 64 20 62 79 20 61 20 63 6f 6c 6f  llowed by a colo
37c0: 6e 20 63 68 61 72 61 63 74 65 72 2e 20 43 6f 6c  n character. Col
37d0: 75 6d 6e 20 6e 61 6d 65 73 20 6d 61 79 20 62 65  umn names may be
37e0: 20 73 70 65 63 69 66 69 65 64 0a 75 73 69 6e 67   specified.using
37f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 20 74   either of the t
3800: 77 6f 20 66 6f 72 6d 73 20 64 65 73 63 72 69 62  wo forms describ
3810: 65 64 20 66 6f 72 20 73 74 72 69 6e 67 73 20 61  ed for strings a
3820: 62 6f 76 65 2e 20 55 6e 6c 69 6b 65 20 73 74 72  bove. Unlike str
3830: 69 6e 67 73 20 74 68 61 74 0a 61 72 65 20 70 61  ings that.are pa
3840: 72 74 20 6f 66 20 70 68 72 61 73 65 73 2c 20 63  rt of phrases, c
3850: 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 72 65 20  olumn names are 
3860: 6e 6f 74 20 70 61 73 73 65 64 20 74 6f 20 74 68  not passed to th
3870: 65 20 74 6f 6b 65 6e 69 7a 65 72 20 6d 6f 64 75  e tokenizer modu
3880: 6c 65 2e 0a 43 6f 6c 75 6d 6e 20 6e 61 6d 65 73  le..Column names
3890: 20 61 72 65 20 63 61 73 65 2d 69 6e 73 65 6e 73   are case-insens
38a0: 69 74 69 76 65 20 69 6e 20 74 68 65 20 75 73 75  itive in the usu
38b0: 61 6c 20 77 61 79 20 66 6f 72 20 53 51 4c 69 74  al way for SQLit
38c0: 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 2d  e column names -
38d0: 0a 75 70 70 65 72 2f 6c 6f 77 65 72 20 63 61 73  .upper/lower cas
38e0: 65 20 65 71 75 69 76 61 6c 65 6e 63 65 20 69 73  e equivalence is
38f0: 20 75 6e 64 65 72 73 74 6f 6f 64 20 66 6f 72 20   understood for 
3900: 41 53 43 49 49 2d 72 61 6e 67 65 20 63 68 61 72  ASCII-range char
3910: 61 63 74 65 72 73 20 6f 6e 6c 79 2e 0a 0a 3c 63  acters only...<c
3920: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20  odeblock>.  ... 
3930: 4d 41 54 43 48 20 27 63 6f 6c 6e 61 6d 65 20 3a  MATCH 'colname :
3940: 20 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22 20   NEAR("one two" 
3950: 22 74 68 72 65 65 20 66 6f 75 72 22 2c 20 31 30  "three four", 10
3960: 29 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  )'.  ... MATCH '
3970: 22 63 6f 6c 6e 61 6d 65 22 20 3a 20 6f 6e 65 20  "colname" : one 
3980: 2b 20 74 77 6f 20 2b 20 74 68 72 65 65 27 0a 0a  + two + three'..
3990: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 7b 63 6f    ... MATCH '{co
39a0: 6c 31 20 63 6f 6c 32 7d 20 3a 20 4e 45 41 52 28  l1 col2} : NEAR(
39b0: 22 6f 6e 65 20 74 77 6f 22 20 22 74 68 72 65 65  "one two" "three
39c0: 20 66 6f 75 72 22 2c 20 31 30 29 27 0a 20 20 2e   four", 10)'.  .
39d0: 2e 2e 20 4d 41 54 43 48 20 27 7b 63 6f 6c 32 20  .. MATCH '{col2 
39e0: 63 6f 6c 31 20 63 6f 6c 33 7d 20 3a 20 6f 6e 65  col1 col3} : one
39f0: 20 2b 20 74 77 6f 20 2b 20 74 68 72 65 65 27 0a   + two + three'.
3a00: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
3a10: 3e 0a 49 66 20 61 20 63 6f 6c 75 6d 6e 20 66 69  >.If a column fi
3a20: 6c 74 65 72 20 73 70 65 63 69 66 69 63 61 74 69  lter specificati
3a30: 6f 6e 20 69 73 20 70 72 65 63 65 64 65 64 20 62  on is preceded b
3a40: 79 20 61 20 22 2d 22 20 63 68 61 72 61 63 74 65  y a "-" characte
3a50: 72 2c 20 74 68 65 6e 0a 69 74 20 69 73 20 69 6e  r, then.it is in
3a60: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 6c  terpreted as a l
3a70: 69 73 74 20 6f 66 20 63 6f 6c 75 6d 6e 20 6e 6f  ist of column no
3a80: 74 20 74 6f 20 6d 61 74 63 68 20 61 67 61 69 6e  t to match again
3a90: 73 74 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  st. For example:
3aa0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
3ab0: 3c 69 3e 2d 2d 20 53 65 61 72 63 68 20 66 6f 72  <i>-- Search for
3ac0: 20 6d 61 74 63 68 65 73 20 69 6e 20 61 6c 6c 20   matches in all 
3ad0: 63 6f 6c 75 6d 6e 73 20 65 78 63 65 70 74 20 22  columns except "
3ae0: 63 6f 6c 6e 61 6d 65 22 3c 2f 69 3e 0a 20 20 2e  colname"</i>.  .
3af0: 2e 2e 20 4d 41 54 43 48 20 27 2d 20 63 6f 6c 6e  .. MATCH '- coln
3b00: 61 6d 65 20 3a 20 4e 45 41 52 28 22 6f 6e 65 20  ame : NEAR("one 
3b10: 74 77 6f 22 20 22 74 68 72 65 65 20 66 6f 75 72  two" "three four
3b20: 22 2c 20 31 30 29 27 0a 0a 20 20 3c 69 3e 2d 2d  ", 10)'..  <i>--
3b30: 20 53 65 61 72 63 68 20 66 6f 72 20 6d 61 74 63   Search for matc
3b40: 68 65 73 20 69 6e 20 61 6c 6c 20 63 6f 6c 75 6d  hes in all colum
3b50: 6e 73 20 65 78 63 65 70 74 20 22 63 6f 6c 31 22  ns except "col1"
3b60: 2c 20 22 63 6f 6c 32 22 20 61 6e 64 20 22 63 6f  , "col2" and "co
3b70: 6c 33 22 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41  l3"</i>.  ... MA
3b80: 54 43 48 20 27 2d 20 7b 63 6f 6c 32 20 63 6f 6c  TCH '- {col2 col
3b90: 31 20 63 6f 6c 33 7d 20 3a 20 6f 6e 65 20 2b 20  1 col3} : one + 
3ba0: 74 77 6f 20 2b 20 74 68 72 65 65 27 0a 3c 2f 63  two + three'.</c
3bb0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 43  odeblock>..<p>.C
3bc0: 6f 6c 75 6d 6e 20 66 69 6c 74 65 72 20 73 70 65  olumn filter spe
3bd0: 63 69 66 69 63 61 74 69 6f 6e 73 20 6d 61 79 20  cifications may 
3be0: 61 6c 73 6f 20 62 65 20 61 70 70 6c 69 65 64 20  also be applied 
3bf0: 74 6f 20 61 72 62 69 74 72 61 72 79 20 65 78 70  to arbitrary exp
3c00: 72 65 73 73 69 6f 6e 73 0a 65 6e 63 6c 6f 73 65  ressions.enclose
3c10: 64 20 69 6e 20 70 61 72 65 6e 74 68 65 73 69 73  d in parenthesis
3c20: 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74  . In this case t
3c30: 68 65 20 63 6f 6c 75 6d 6e 20 66 69 6c 74 65 72  he column filter
3c40: 20 61 70 70 6c 69 65 73 20 74 6f 20 61 6c 6c 20   applies to all 
3c50: 0a 70 68 72 61 73 65 73 20 77 69 74 68 69 6e 20  .phrases within 
3c60: 74 68 65 20 65 78 70 72 65 73 73 69 6f 6e 2e 20  the expression. 
3c70: 4e 65 73 74 65 64 20 63 6f 6c 75 6d 6e 20 66 69  Nested column fi
3c80: 6c 74 65 72 20 6f 70 65 72 61 74 69 6f 6e 73 20  lter operations 
3c90: 6d 61 79 20 6f 6e 6c 79 20 0a 66 75 72 74 68 65  may only .furthe
3ca0: 72 20 72 65 73 74 72 69 63 74 20 74 68 65 20 73  r restrict the s
3cb0: 75 62 73 65 74 20 6f 66 20 63 6f 6c 75 6d 6e 73  ubset of columns
3cc0: 20 6d 61 74 63 68 65 64 2c 20 74 68 65 79 20 63   matched, they c
3cd0: 61 6e 20 6e 6f 74 20 62 65 20 75 73 65 64 20 74  an not be used t
3ce0: 6f 20 0a 72 65 2d 65 6e 61 62 6c 65 20 66 69 6c  o .re-enable fil
3cf0: 74 65 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 46  tered columns. F
3d00: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
3d10: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d  deblock>.  <i>--
3d20: 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61   The following a
3d30: 72 65 20 65 71 75 69 76 61 6c 65 6e 74 3a 3c 2f  re equivalent:</
3d40: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
3d50: 7b 61 20 62 7d 20 3a 20 28 20 7b 62 20 63 7d 20  {a b} : ( {b c} 
3d60: 3a 20 22 68 65 6c 6c 6f 22 20 41 4e 44 20 22 77  : "hello" AND "w
3d70: 6f 72 6c 64 22 20 29 27 0a 20 20 2e 2e 2e 20 4d  orld" )'.  ... M
3d80: 41 54 43 48 20 27 28 62 20 3a 20 22 68 65 6c 6c  ATCH '(b : "hell
3d90: 6f 22 29 20 41 4e 44 20 28 7b 61 20 62 7d 20 3a  o") AND ({a b} :
3da0: 20 22 77 6f 72 6c 64 22 29 27 0a 3c 2f 63 6f 64   "world")'.</cod
3db0: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 46 69 6e  eblock>..<p>.Fin
3dc0: 61 6c 6c 79 2c 20 61 20 63 6f 6c 75 6d 6e 20 66  ally, a column f
3dd0: 69 6c 74 65 72 20 66 6f 72 20 61 20 73 69 6e 67  ilter for a sing
3de0: 6c 65 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 62 65  le column may be
3df0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 75 73   specified by us
3e00: 69 6e 67 0a 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  ing.the column n
3e10: 61 6d 65 20 61 73 20 74 68 65 20 4c 48 53 20 6f  ame as the LHS o
3e20: 66 20 61 20 4d 41 54 43 48 20 6f 70 65 72 61 74  f a MATCH operat
3e30: 6f 72 20 28 69 6e 73 74 65 61 64 20 6f 66 20 74  or (instead of t
3e40: 68 65 20 75 73 75 61 6c 0a 74 61 62 6c 65 20 6e  he usual.table n
3e50: 61 6d 65 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c  ame). For exampl
3e60: 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
3e70: 20 20 3c 69 3e 2d 2d 20 47 69 76 65 6e 20 74 68    <i>-- Given th
3e80: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
3e90: 65 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  e</i>.  CREATE V
3ea0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20  IRTUAL TABLE ft 
3eb0: 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c  USING fts5(a, b,
3ec0: 20 63 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68   c);..  <i>-- Th
3ed0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  e following are 
3ee0: 65 71 75 69 76 61 6c 65 6e 74 3c 2f 69 3e 0a 20  equivalent</i>. 
3ef0: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66   SELECT * FROM f
3f00: 74 20 57 48 45 52 45 20 62 20 4d 41 54 43 48 20  t WHERE b MATCH 
3f10: 27 75 76 77 20 41 4e 44 20 78 79 7a 27 3b 0a 20  'uvw AND xyz';. 
3f20: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66   SELECT * FROM f
3f30: 74 20 57 48 45 52 45 20 66 74 20 4d 41 54 43 48  t WHERE ft MATCH
3f40: 20 27 62 20 3a 20 28 75 76 77 20 41 4e 44 20 78   'b : (uvw AND x
3f50: 79 7a 29 27 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54  yz)';..  <i>-- T
3f60: 68 69 73 20 71 75 65 72 79 20 63 61 6e 6e 6f 74  his query cannot
3f70: 20 6d 61 74 63 68 20 61 6e 79 20 72 6f 77 73 20   match any rows 
3f80: 28 73 69 6e 63 65 20 61 6c 6c 20 63 6f 6c 75 6d  (since all colum
3f90: 6e 73 20 61 72 65 20 66 69 6c 74 65 72 65 64 20  ns are filtered 
3fa0: 6f 75 74 29 3a 20 3c 2f 69 3e 0a 20 20 53 45 4c  out): </i>.  SEL
3fb0: 45 43 54 20 2a 20 46 52 4f 4d 20 66 74 20 57 48  ECT * FROM ft WH
3fc0: 45 52 45 20 62 20 4d 41 54 43 48 20 27 61 20 3a  ERE b MATCH 'a :
3fd0: 20 78 79 7a 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f   xyz';.</codeblo
3fe0: 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46  ck>..<h2 tags="F
3ff0: 54 53 35 20 62 6f 6f 6c 65 61 6e 20 6f 70 65 72  TS5 boolean oper
4000: 61 74 6f 72 73 22 3e 46 54 53 35 20 42 6f 6f 6c  ators">FTS5 Bool
4010: 65 61 6e 20 4f 70 65 72 61 74 6f 72 73 3c 2f 68  ean Operators</h
4020: 32 3e 0a 0a 3c 70 3e 0a 50 68 72 61 73 65 73 20  2>..<p>.Phrases 
4030: 61 6e 64 20 4e 45 41 52 20 67 72 6f 75 70 73 20  and NEAR groups 
4040: 6d 61 79 20 62 65 20 61 72 72 61 6e 67 65 64 20  may be arranged 
4050: 69 6e 74 6f 20 65 78 70 72 65 73 73 69 6f 6e 73  into expressions
4060: 20 75 73 69 6e 67 20 3c 62 3e 62 6f 6f 6c 65 61   using <b>boolea
4070: 6e 0a 6f 70 65 72 61 74 6f 72 73 3c 2f 62 3e 2e  n.operators</b>.
4080: 20 49 6e 20 6f 72 64 65 72 20 6f 66 20 70 72 65   In order of pre
4090: 63 65 64 65 6e 63 65 2c 20 66 72 6f 6d 20 68 69  cedence, from hi
40a0: 67 68 65 73 74 20 28 74 69 67 68 74 65 73 74 20  ghest (tightest 
40b0: 67 72 6f 75 70 69 6e 67 29 20 74 6f 0a 6c 6f 77  grouping) to.low
40c0: 65 73 74 20 28 6c 6f 6f 73 65 73 74 20 67 72 6f  est (loosest gro
40d0: 75 70 69 6e 67 29 2c 20 74 68 65 20 6f 70 65 72  uping), the oper
40e0: 61 74 6f 72 73 20 61 72 65 3a 0a 0a 3c 74 61 62  ators are:..<tab
40f0: 6c 65 20 73 74 72 69 70 65 64 3d 31 3e 0a 20 20  le striped=1>.  
4100: 3c 74 72 3e 3c 74 68 3e 4f 70 65 72 61 74 6f 72  <tr><th>Operator
4110: 20 3c 74 68 3e 46 75 6e 63 74 69 6f 6e 0a 0a 20   <th>Function.. 
4120: 20 3c 74 72 3e 3c 74 64 3e 3c 63 6f 64 65 3e 26   <tr><td><code>&
4130: 6c 74 3b 71 75 65 72 79 31 26 67 74 3b 20 4e 4f  lt;query1&gt; NO
4140: 54 20 26 6c 74 3b 71 75 65 72 79 32 26 67 74 3b  T &lt;query2&gt;
4150: 3c 2f 63 6f 64 65 3e 20 0a 20 20 20 20 20 20 3c  </code> .      <
4160: 74 64 3e 4d 61 74 63 68 65 73 20 69 66 20 71 75  td>Matches if qu
4170: 65 72 79 31 20 6d 61 74 63 68 65 73 20 61 6e 64  ery1 matches and
4180: 20 71 75 65 72 79 32 20 64 6f 65 73 20 6e 6f 74   query2 does not
4190: 20 6d 61 74 63 68 2e 0a 0a 20 20 3c 74 72 3e 3c   match...  <tr><
41a0: 74 64 3e 3c 63 6f 64 65 3e 26 6c 74 3b 71 75 65  td><code>&lt;que
41b0: 72 79 31 26 67 74 3b 20 41 4e 44 20 26 6c 74 3b  ry1&gt; AND &lt;
41c0: 71 75 65 72 79 32 26 67 74 3b 3c 2f 63 6f 64 65  query2&gt;</code
41d0: 3e 20 0a 20 20 20 20 20 20 3c 74 64 3e 4d 61 74  > .      <td>Mat
41e0: 63 68 65 73 20 69 66 20 62 6f 74 68 20 71 75 65  ches if both que
41f0: 72 79 31 20 61 6e 64 20 71 75 65 72 79 32 20 6d  ry1 and query2 m
4200: 61 74 63 68 2e 0a 0a 20 20 3c 74 72 3e 3c 74 64  atch...  <tr><td
4210: 3e 3c 63 6f 64 65 3e 26 6c 74 3b 71 75 65 72 79  ><code>&lt;query
4220: 31 26 67 74 3b 20 4f 52 20 26 6c 74 3b 71 75 65  1&gt; OR &lt;que
4230: 72 79 32 26 67 74 3b 3c 2f 63 6f 64 65 3e 20 0a  ry2&gt;</code> .
4240: 20 20 20 20 20 20 3c 74 64 3e 4d 61 74 63 68 65        <td>Matche
4250: 73 20 69 66 20 65 69 74 68 65 72 20 71 75 65 72  s if either quer
4260: 79 31 20 6f 72 20 71 75 65 72 79 32 20 6d 61 74  y1 or query2 mat
4270: 63 68 2e 0a 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c  ch...</table>..<
4280: 70 3e 0a 50 61 72 65 6e 74 68 65 73 69 73 20 6d  p>.Parenthesis m
4290: 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 67 72  ay be used to gr
42a0: 6f 75 70 20 65 78 70 72 65 73 73 69 6f 6e 73 20  oup expressions 
42b0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6d 6f 64 69  in order to modi
42c0: 66 79 20 6f 70 65 72 61 74 6f 72 0a 70 72 65 63  fy operator.prec
42d0: 65 64 65 6e 63 65 20 69 6e 20 74 68 65 20 75 73  edence in the us
42e0: 75 61 6c 20 77 61 79 73 2e 20 46 6f 72 20 65 78  ual ways. For ex
42f0: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
4300: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 4d 61 74 63  ck>.  <i>-- Matc
4310: 68 65 73 20 64 6f 63 75 6d 65 6e 74 73 20 74 68  hes documents th
4320: 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20 6c 65  at contain at le
4330: 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e 63 65  ast one instance
4340: 20 6f 66 20 65 69 74 68 65 72 20 22 6f 6e 65 22   of either "one"
4350: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 72 20  </i>.  <i>-- or 
4360: 22 74 77 6f 22 2c 20 62 75 74 20 64 6f 20 6e 6f  "two", but do no
4370: 74 20 63 6f 6e 74 61 69 6e 20 61 6e 79 20 69 6e  t contain any in
4380: 73 74 61 6e 63 65 73 20 6f 66 20 74 6f 6b 65 6e  stances of token
4390: 20 22 74 68 72 65 65 22 2e 3c 2f 69 3e 0a 20 20   "three".</i>.  
43a0: 2e 2e 2e 20 4d 41 54 43 48 20 27 6f 6e 65 20 4f  ... MATCH 'one O
43b0: 52 20 74 77 6f 20 4e 4f 54 20 74 68 72 65 65 27  R two NOT three'
43c0: 0a 0a 20 20 3c 69 3e 2d 2d 20 4d 61 74 63 68 20  ..  <i>-- Match 
43d0: 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20 74 68  all documents th
43e0: 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 74  at contain the t
43f0: 6f 6b 65 6e 20 22 74 77 6f 22 20 62 75 74 20 6e  oken "two" but n
4400: 6f 74 20 22 74 68 72 65 65 22 2c 20 6f 72 3c 2f  ot "three", or</
4410: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63 6f 6e 74 61  i>.  <i>-- conta
4420: 69 6e 20 74 68 65 20 74 6f 6b 65 6e 20 22 6f 6e  in the token "on
4430: 65 22 2e 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41  e".</i>.  ... MA
4440: 54 43 48 20 27 6f 6e 65 20 4f 52 20 28 74 77 6f  TCH 'one OR (two
4450: 20 4e 4f 54 20 74 68 72 65 65 29 27 0a 3c 2f 63   NOT three)'.</c
4460: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 50  odeblock>..<p>.P
4470: 68 72 61 73 65 73 20 61 6e 64 20 4e 45 41 52 20  hrases and NEAR 
4480: 67 72 6f 75 70 73 20 6d 61 79 20 61 6c 73 6f 20  groups may also 
4490: 62 65 20 63 6f 6e 6e 65 63 74 65 64 20 62 79 20  be connected by 
44a0: 3c 62 3e 69 6d 70 6c 69 63 69 74 20 41 4e 44 20  <b>implicit AND 
44b0: 6f 70 65 72 61 74 6f 72 73 3c 2f 62 3e 2e 0a 46  operators</b>..F
44c0: 6f 72 20 73 69 6d 70 6c 69 63 69 74 79 2c 20 74  or simplicity, t
44d0: 68 65 73 65 20 61 72 65 20 6e 6f 74 20 73 68 6f  hese are not sho
44e0: 77 6e 20 69 6e 20 74 68 65 20 42 4e 46 20 67 72  wn in the BNF gr
44f0: 61 6d 6d 61 72 20 61 62 6f 76 65 2e 20 45 73 73  ammar above. Ess
4500: 65 6e 74 69 61 6c 6c 79 2c 20 61 6e 79 0a 73 65  entially, any.se
4510: 71 75 65 6e 63 65 20 6f 66 20 70 68 72 61 73 65  quence of phrase
4520: 73 20 6f 72 20 4e 45 41 52 20 67 72 6f 75 70 73  s or NEAR groups
4530: 20 28 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73   (including thos
4540: 65 20 72 65 73 74 72 69 63 74 65 64 20 74 6f 20  e restricted to 
4550: 6d 61 74 63 68 69 6e 67 0a 73 70 65 63 69 66 69  matching.specifi
4560: 65 64 20 63 6f 6c 75 6d 6e 73 29 20 73 65 70 61  ed columns) sepa
4570: 72 61 74 65 64 20 6f 6e 6c 79 20 62 79 20 77 68  rated only by wh
4580: 69 74 65 73 70 61 63 65 20 61 72 65 20 68 61 6e  itespace are han
4590: 64 6c 65 64 20 61 73 20 69 66 20 74 68 65 72 65  dled as if there
45a0: 20 77 65 72 65 20 61 6e 0a 69 6d 70 6c 69 63 69   were an.implici
45b0: 74 20 41 4e 44 20 6f 70 65 72 61 74 6f 72 20 62  t AND operator b
45c0: 65 74 77 65 65 6e 20 65 61 63 68 20 70 61 69 72  etween each pair
45d0: 20 6f 66 20 70 68 72 61 73 65 73 20 6f 72 20 4e   of phrases or N
45e0: 45 41 52 20 67 72 6f 75 70 73 2e 20 49 6d 70 6c  EAR groups. Impl
45f0: 69 63 69 74 0a 41 4e 44 20 6f 70 65 72 61 74 6f  icit.AND operato
4600: 72 73 20 61 72 65 20 6e 65 76 65 72 20 69 6e 73  rs are never ins
4610: 65 72 74 65 64 20 61 66 74 65 72 20 6f 72 20 62  erted after or b
4620: 65 66 6f 72 65 20 61 6e 20 65 78 70 72 65 73 73  efore an express
4630: 69 6f 6e 20 65 6e 63 6c 6f 73 65 64 20 69 6e 0a  ion enclosed in.
4640: 70 61 72 65 6e 74 68 65 73 69 73 2e 20 46 6f 72  parenthesis. For
4650: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
4660: 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d 41 54  block>.  ... MAT
4670: 43 48 20 27 6f 6e 65 20 74 77 6f 20 74 68 72 65  CH 'one two thre
4680: 65 27 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d  e'         <i>--
4690: 20 27 6f 6e 65 20 41 4e 44 20 74 77 6f 20 41 4e   'one AND two AN
46a0: 44 20 74 68 72 65 65 27 3c 2f 69 3e 0a 20 20 2e  D three'</i>.  .
46b0: 2e 2e 20 4d 41 54 43 48 20 27 74 68 72 65 65 20  .. MATCH 'three 
46c0: 22 6f 6e 65 20 74 77 6f 22 27 20 20 20 20 20 20  "one two"'      
46d0: 20 3c 69 3e 2d 2d 20 27 74 68 72 65 65 20 41 4e   <i>-- 'three AN
46e0: 44 20 22 6f 6e 65 20 74 77 6f 22 27 3c 2f 69 3e  D "one two"'</i>
46f0: 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45  .  ... MATCH 'NE
4700: 41 52 28 6f 6e 65 20 74 77 6f 29 20 74 68 72 65  AR(one two) thre
4710: 65 27 20 20 20 3c 69 3e 2d 2d 20 27 4e 45 41 52  e'   <i>-- 'NEAR
4720: 28 6f 6e 65 20 74 77 6f 29 20 41 4e 44 20 74 68  (one two) AND th
4730: 72 65 65 27 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d  ree'</i>.  ... M
4740: 41 54 43 48 20 27 6f 6e 65 20 4f 52 20 74 77 6f  ATCH 'one OR two
4750: 20 74 68 72 65 65 27 20 20 20 20 20 20 3c 69 3e   three'      <i>
4760: 2d 2d 20 27 6f 6e 65 20 4f 52 20 74 77 6f 20 41  -- 'one OR two A
4770: 4e 44 20 74 68 72 65 65 27 3c 2f 69 3e 0a 0a 20  ND three'</i>.. 
4780: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 28 6f 6e 65   ... MATCH '(one
4790: 20 4f 52 20 74 77 6f 29 20 74 68 72 65 65 27 20   OR two) three' 
47a0: 20 20 20 3c 69 3e 2d 2d 20 53 79 6e 74 61 78 20     <i>-- Syntax 
47b0: 65 72 72 6f 72 21 3c 2f 69 3e 0a 20 20 2e 2e 2e  error!</i>.  ...
47c0: 20 4d 41 54 43 48 20 27 66 75 6e 63 28 6f 6e 65   MATCH 'func(one
47d0: 20 74 77 6f 29 27 20 20 20 20 20 20 20 20 20 3c   two)'         <
47e0: 69 3e 2d 2d 20 53 79 6e 74 61 78 20 65 72 72 6f  i>-- Syntax erro
47f0: 72 21 3c 2f 69 3e 0a 3c 2f 63 6f 64 65 62 6c 6f  r!</i>.</codeblo
4800: 63 6b 3e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46  ck>..<h1 tags="F
4810: 54 53 35 20 43 52 45 41 54 45 20 54 41 42 4c 45  TS5 CREATE TABLE
4820: 20 4f 70 74 69 6f 6e 73 22 3e 46 54 53 35 20 54   Options">FTS5 T
4830: 61 62 6c 65 20 43 72 65 61 74 69 6f 6e 20 61 6e  able Creation an
4840: 64 20 49 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  d Initialization
4850: 3c 2f 68 31 3e 0a 0a 3c 70 3e 45 61 63 68 20 61  </h1>..<p>Each a
4860: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
4870: 64 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 22  d as part of a "
4880: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
4890: 41 42 4c 45 20 2e 2e 2e 20 55 53 49 4e 47 20 66  ABLE ... USING f
48a0: 74 73 35 20 0a 2e 2e 2e 22 20 73 74 61 74 65 6d  ts5 ...." statem
48b0: 65 6e 74 20 69 73 20 65 69 74 68 65 72 20 61 20  ent is either a 
48c0: 63 6f 6c 75 6d 6e 20 64 65 63 6c 61 72 61 74 69  column declarati
48d0: 6f 6e 20 6f 72 20 61 20 63 6f 6e 66 69 67 75 72  on or a configur
48e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 20 41 0a  ation option. A.
48f0: 3c 62 3e 63 6f 6c 75 6d 6e 20 64 65 63 6c 61 72  <b>column declar
4900: 61 74 69 6f 6e 3c 2f 62 3e 20 63 6f 6e 73 69 73  ation</b> consis
4910: 74 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ts of one or mor
4920: 65 20 77 68 69 74 65 73 70 61 63 65 20 73 65 70  e whitespace sep
4930: 61 72 61 74 65 64 20 46 54 53 35 0a 62 61 72 65  arated FTS5.bare
4940: 77 6f 72 64 73 20 6f 72 20 73 74 72 69 6e 67 20  words or string 
4950: 6c 69 74 65 72 61 6c 73 20 71 75 6f 74 65 64 20  literals quoted 
4960: 69 6e 20 61 6e 79 20 6d 61 6e 6e 65 72 20 61 63  in any manner ac
4970: 63 65 70 74 61 62 6c 65 20 74 6f 20 53 51 4c 69  ceptable to SQLi
4980: 74 65 2e 0a 0a 3c 70 3e 54 68 65 20 66 69 72 73  te...<p>The firs
4990: 74 20 73 74 72 69 6e 67 20 6f 72 20 62 61 72 65  t string or bare
49a0: 77 6f 72 64 20 69 6e 20 61 20 63 6f 6c 75 6d 6e  word in a column
49b0: 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 69 73 20   declaration is 
49c0: 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
49d0: 20 49 74 0a 69 73 20 61 6e 20 65 72 72 6f 72 20   It.is an error 
49e0: 74 6f 20 61 74 74 65 6d 70 74 20 74 6f 20 6e 61  to attempt to na
49f0: 6d 65 20 61 6e 20 66 74 73 35 20 74 61 62 6c 65  me an fts5 table
4a00: 20 63 6f 6c 75 6d 6e 20 22 72 6f 77 69 64 22 20   column "rowid" 
4a10: 6f 72 20 22 72 61 6e 6b 22 2c 20 6f 72 20 74 6f  or "rank", or to
4a20: 0a 61 73 73 69 67 6e 20 74 68 65 20 73 61 6d 65  .assign the same
4a30: 20 6e 61 6d 65 20 74 6f 20 61 20 63 6f 6c 75 6d   name to a colum
4a40: 6e 20 61 73 20 69 73 20 75 73 65 64 20 62 79 20  n as is used by 
4a50: 74 68 65 20 74 61 62 6c 65 20 69 74 73 65 6c 66  the table itself
4a60: 2e 20 54 68 69 73 20 69 73 20 6e 6f 74 0a 73 75  . This is not.su
4a70: 70 70 6f 72 74 65 64 2e 0a 0a 3c 70 3e 45 61 63  pported...<p>Eac
4a80: 68 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 72  h subsequent str
4a90: 69 6e 67 20 6f 72 20 62 61 72 65 77 6f 72 64 20  ing or bareword 
4aa0: 69 6e 20 61 20 63 6f 6c 75 6d 6e 20 64 65 63 6c  in a column decl
4ab0: 61 72 61 74 69 6f 6e 20 69 73 20 61 20 63 6f 6c  aration is a col
4ac0: 75 6d 6e 0a 6f 70 74 69 6f 6e 20 74 68 61 74 20  umn.option that 
4ad0: 6d 6f 64 69 66 69 65 73 20 74 68 65 20 62 65 68  modifies the beh
4ae0: 61 76 69 6f 75 72 20 6f 66 20 74 68 61 74 20 63  aviour of that c
4af0: 6f 6c 75 6d 6e 2e 20 43 6f 6c 75 6d 6e 20 6f 70  olumn. Column op
4b00: 74 69 6f 6e 73 20 61 72 65 0a 63 61 73 65 2d 69  tions are.case-i
4b10: 6e 64 65 70 65 6e 64 65 6e 74 2e 20 55 6e 6c 69  ndependent. Unli
4b20: 6b 65 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ke the SQLite co
4b30: 72 65 2c 20 46 54 53 35 20 63 6f 6e 73 69 64 65  re, FTS5 conside
4b40: 72 73 20 75 6e 72 65 63 6f 67 6e 69 7a 65 64 20  rs unrecognized 
4b50: 63 6f 6c 75 6d 6e 0a 6f 70 74 69 6f 6e 73 20 74  column.options t
4b60: 6f 20 62 65 20 65 72 72 6f 72 73 2e 20 43 75 72  o be errors. Cur
4b70: 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e 6c 79  rently, the only
4b80: 20 6f 70 74 69 6f 6e 20 72 65 63 6f 67 6e 69 7a   option recogniz
4b90: 65 64 20 69 73 20 0a 5b 75 6e 69 6e 64 65 78 65  ed is .[unindexe
4ba0: 64 20 7c 20 22 55 4e 49 4e 44 45 58 45 44 22 20  d | "UNINDEXED" 
4bb0: 28 73 65 65 20 62 65 6c 6f 77 29 5d 2e 0a 0a 3c  (see below)]...<
4bc0: 70 3e 41 20 3c 62 3e 63 6f 6e 66 69 67 75 72 61  p>A <b>configura
4bd0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 3c 2f 62 3e 20  tion option</b> 
4be0: 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 6e 20 46  consists of an F
4bf0: 54 53 35 20 62 61 72 65 77 6f 72 64 20 2d 20 74  TS5 bareword - t
4c00: 68 65 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 2d  he option name -
4c10: 0a 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e 20  .followed by an 
4c20: 22 3d 22 20 63 68 61 72 61 63 74 65 72 2c 20 66  "=" character, f
4c30: 6f 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 6f  ollowed by the o
4c40: 70 74 69 6f 6e 20 76 61 6c 75 65 2e 20 54 68 65  ption value. The
4c50: 20 6f 70 74 69 6f 6e 20 76 61 6c 75 65 20 69 73   option value is
4c60: 0a 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67  .specified using
4c70: 20 65 69 74 68 65 72 20 61 20 73 69 6e 67 6c 65   either a single
4c80: 20 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 6f   FTS5 bareword o
4c90: 72 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  r a string liter
4ca0: 61 6c 2c 20 61 67 61 69 6e 20 71 75 6f 74 65 64  al, again quoted
4cb0: 0a 69 6e 20 61 6e 79 20 6d 61 6e 6e 65 72 20 61  .in any manner a
4cc0: 63 63 65 70 74 61 62 6c 65 20 74 6f 20 74 68 65  cceptable to the
4cd0: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 46 6f   SQLite core. Fo
4ce0: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
4cf0: 65 62 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45  eblock>.  CREATE
4d00: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 6d   VIRTUAL TABLE m
4d10: 61 69 6c 20 55 53 49 4e 47 20 66 74 73 35 28 73  ail USING fts5(s
4d20: 65 6e 64 65 72 2c 20 74 69 74 6c 65 2c 20 62 6f  ender, title, bo
4d30: 64 79 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  dy, tokenize = '
4d40: 70 6f 72 74 65 72 20 61 73 63 69 69 27 29 3b 0a  porter ascii');.
4d50: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
4d60: 3e 20 54 68 65 72 65 20 61 72 65 20 63 75 72 72  > There are curr
4d70: 65 6e 74 6c 79 20 74 68 65 20 66 6f 6c 6c 6f 77  ently the follow
4d80: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
4d90: 6e 20 6f 70 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e  n options:..<ul>
4da0: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 22 74 6f 6b  .  <li> The "tok
4db0: 65 6e 69 7a 65 22 20 6f 70 74 69 6f 6e 2c 20 75  enize" option, u
4dc0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
4dd0: 20 61 20 5b 46 54 53 35 20 74 6f 6b 65 6e 69 7a   a [FTS5 tokeniz
4de0: 65 72 73 20 7c 20 63 75 73 74 6f 6d 20 74 6f 6b  ers | custom tok
4df0: 65 6e 69 7a 65 72 5d 2e 0a 20 20 3c 6c 69 3e 20  enizer]..  <li> 
4e00: 54 68 65 20 22 70 72 65 66 69 78 22 20 6f 70 74  The "prefix" opt
4e10: 69 6f 6e 2c 20 75 73 65 64 20 74 6f 20 61 64 64  ion, used to add
4e20: 20 5b 46 54 53 35 20 70 72 65 66 69 78 20 69 6e   [FTS5 prefix in
4e30: 64 65 78 65 73 20 7c 20 70 72 65 66 69 78 20 69  dexes | prefix i
4e40: 6e 64 65 78 65 73 5d 0a 20 20 20 20 20 20 20 74  ndexes].       t
4e50: 6f 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65 2e  o an FTS5 table.
4e60: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 22 63 6f 6e  .  <li> The "con
4e70: 74 65 6e 74 22 20 6f 70 74 69 6f 6e 2c 20 75 73  tent" option, us
4e80: 65 64 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 46  ed to make the F
4e90: 54 53 35 20 74 61 62 6c 65 20 61 6e 20 0a 20 20  TS5 table an .  
4ea0: 20 20 20 20 20 5b 46 54 53 35 20 63 6f 6e 74 65       [FTS5 conte
4eb0: 6e 74 20 6f 70 74 69 6f 6e 20 7c 20 65 78 74 65  nt option | exte
4ec0: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 6f 72 20  rnal content or 
4ed0: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
4ee0: 65 5d 2e 0a 20 20 3c 6c 69 3e 20 54 68 65 20 22  e]..  <li> The "
4ef0: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 22 20 6f  content_rowid" o
4f00: 70 74 69 6f 6e 2c 20 75 73 65 64 20 74 6f 20 73  ption, used to s
4f10: 65 74 20 74 68 65 20 72 6f 77 69 64 20 66 69 65  et the rowid fie
4f20: 6c 64 20 6f 66 20 61 6e 20 0a 20 20 20 20 20 20  ld of an .      
4f30: 20 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c 20   [FTS5 external 
4f40: 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20 7c  content tables |
4f50: 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e   external conten
4f60: 74 20 74 61 62 6c 65 5d 2e 0a 20 20 3c 6c 69 3e  t table]..  <li>
4f70: 20 54 68 65 20 5b 46 54 53 35 20 63 6f 6c 75 6d   The [FTS5 colum
4f80: 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 20 7c 20 22  nsize option | "
4f90: 63 6f 6c 75 6d 6e 73 69 7a 65 22 20 6f 70 74 69  columnsize" opti
4fa0: 6f 6e 5d 2c 20 75 73 65 64 20 74 6f 20 63 6f 6e  on], used to con
4fb0: 66 69 67 75 72 65 0a 20 20 20 20 20 20 20 77 68  figure.       wh
4fc0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
4fd0: 20 73 69 7a 65 20 69 6e 20 74 6f 6b 65 6e 73 20   size in tokens 
4fe0: 6f 66 20 65 61 63 68 20 76 61 6c 75 65 20 69 6e  of each value in
4ff0: 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20   the FTS5 table 
5000: 69 73 0a 20 20 20 20 20 20 20 73 74 6f 72 65 64  is.       stored
5010: 20 73 65 70 61 72 61 74 65 6c 79 20 77 69 74 68   separately with
5020: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  in the database.
5030: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 5b 46 54 53  .  <li> The [FTS
5040: 35 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e 20  5 detail option 
5050: 7c 20 22 64 65 74 61 69 6c 22 20 6f 70 74 69 6f  | "detail" optio
5060: 6e 5d 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n]. This option 
5070: 6d 61 79 20 62 65 20 75 73 65 64 20 0a 20 20 20  may be used .   
5080: 20 20 20 20 74 6f 20 72 65 64 75 63 65 20 74 68      to reduce th
5090: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 46 54  e size of the FT
50a0: 53 20 69 6e 64 65 78 20 6f 6e 20 64 69 73 6b 20  S index on disk 
50b0: 62 79 20 6f 6d 69 74 74 69 6e 67 20 73 6f 6d 65  by omitting some
50c0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 20 20   information.   
50d0: 20 20 20 20 66 72 6f 6d 20 69 74 2e 20 20 0a 3c      from it.  .<
50e0: 2f 75 6c 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  /ul>..<h2 tags="
50f0: 75 6e 69 6e 64 65 78 65 64 22 3e 54 68 65 20 55  unindexed">The U
5100: 4e 49 4e 44 45 58 45 44 20 63 6f 6c 75 6d 6e 20  NINDEXED column 
5110: 6f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  option</h2>..<p>
5120: 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  The contents of 
5130: 63 6f 6c 75 6d 6e 73 20 71 75 61 6c 69 66 69 65  columns qualifie
5140: 64 20 77 69 74 68 20 74 68 65 20 55 4e 49 4e 44  d with the UNIND
5150: 45 58 45 44 20 63 6f 6c 75 6d 6e 20 6f 70 74 69  EXED column opti
5160: 6f 6e 20 61 72 65 20 6e 6f 74 0a 61 64 64 65 64  on are not.added
5170: 20 74 6f 20 74 68 65 20 46 54 53 20 69 6e 64 65   to the FTS inde
5180: 78 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  x. This means th
5190: 61 74 20 66 6f 72 20 74 68 65 20 70 75 72 70 6f  at for the purpo
51a0: 73 65 73 20 6f 66 20 4d 41 54 43 48 20 71 75 65  ses of MATCH que
51b0: 72 69 65 73 20 61 6e 64 0a 5b 46 54 53 35 20 61  ries and.[FTS5 a
51c0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
51d0: 6e 73 5d 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ns], the column 
51e0: 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 6d 61 74 63  contains no matc
51f0: 68 61 62 6c 65 20 74 6f 6b 65 6e 73 2e 20 0a 0a  hable tokens. ..
5200: 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  <p>For example, 
5210: 74 6f 20 61 76 6f 69 64 20 61 64 64 69 6e 67 20  to avoid adding 
5220: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
5230: 74 68 65 20 22 75 75 69 64 22 20 66 69 65 6c 64  the "uuid" field
5240: 20 74 6f 20 74 68 65 20 46 54 53 0a 69 6e 64 65   to the FTS.inde
5250: 78 3a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  x:.<codeblock>. 
5260: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
5270: 54 41 42 4c 45 20 63 75 73 74 6f 6d 65 72 73 20  TABLE customers 
5280: 55 53 49 4e 47 20 66 74 73 35 28 6e 61 6d 65 2c  USING fts5(name,
5290: 20 61 64 64 72 2c 20 75 75 69 64 20 55 4e 49 4e   addr, uuid UNIN
52a0: 44 45 58 45 44 29 3b 0a 3c 2f 63 6f 64 65 62 6c  DEXED);.</codebl
52b0: 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ock>..<h2 tags="
52c0: 46 54 53 35 20 70 72 65 66 69 78 20 69 6e 64 65  FTS5 prefix inde
52d0: 78 65 73 22 3e 50 72 65 66 69 78 20 49 6e 64 65  xes">Prefix Inde
52e0: 78 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 42 79  xes</h2>..<p> By
52f0: 20 64 65 66 61 75 6c 74 2c 20 46 54 53 35 20 6d   default, FTS5 m
5300: 61 69 6e 74 61 69 6e 73 20 61 20 73 69 6e 67 6c  aintains a singl
5310: 65 20 69 6e 64 65 78 20 72 65 63 6f 72 64 69 6e  e index recordin
5320: 67 20 74 68 65 20 6c 6f 63 61 74 69 6f 6e 20 6f  g the location o
5330: 66 20 65 61 63 68 0a 74 6f 6b 65 6e 20 69 6e 73  f each.token ins
5340: 74 61 6e 63 65 20 77 69 74 68 69 6e 20 74 68 65  tance within the
5350: 20 64 6f 63 75 6d 65 6e 74 20 73 65 74 2e 20 54   document set. T
5360: 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 71  his means that q
5370: 75 65 72 79 69 6e 67 20 66 6f 72 20 63 6f 6d 70  uerying for comp
5380: 6c 65 74 65 0a 74 6f 6b 65 6e 73 20 69 73 20 66  lete.tokens is f
5390: 61 73 74 2c 20 61 73 20 69 74 20 72 65 71 75 69  ast, as it requi
53a0: 72 65 73 20 61 20 73 69 6e 67 6c 65 20 6c 6f 6f  res a single loo
53b0: 6b 75 70 2c 20 62 75 74 20 71 75 65 72 79 69 6e  kup, but queryin
53c0: 67 20 66 6f 72 20 61 20 70 72 65 66 69 78 20 0a  g for a prefix .
53d0: 74 6f 6b 65 6e 20 63 61 6e 20 62 65 20 73 6c 6f  token can be slo
53e0: 77 2c 20 61 73 20 69 74 20 72 65 71 75 69 72 65  w, as it require
53f0: 73 20 61 20 72 61 6e 67 65 20 73 63 61 6e 2e 20  s a range scan. 
5400: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  For example, to 
5410: 71 75 65 72 79 20 66 6f 72 0a 74 68 65 20 70 72  query for.the pr
5420: 65 66 69 78 20 74 6f 6b 65 6e 20 22 61 62 63 2a  efix token "abc*
5430: 22 20 72 65 71 75 69 72 65 73 20 61 20 72 61 6e  " requires a ran
5440: 67 65 20 73 63 61 6e 20 6f 66 20 61 6c 6c 20 74  ge scan of all t
5450: 6f 6b 65 6e 73 20 67 72 65 61 74 65 72 20 74 68  okens greater th
5460: 61 6e 0a 6f 72 20 65 71 75 61 6c 20 74 6f 20 22  an.or equal to "
5470: 61 62 63 22 20 61 6e 64 20 6c 65 73 73 20 74 68  abc" and less th
5480: 61 6e 20 22 61 62 64 22 2e 0a 0a 3c 70 3e 20 41  an "abd"...<p> A
5490: 20 70 72 65 66 69 78 20 69 6e 64 65 78 20 69 73   prefix index is
54a0: 20 61 20 73 65 70 61 72 61 74 65 20 69 6e 64 65   a separate inde
54b0: 78 20 74 68 61 74 20 72 65 63 6f 72 64 73 20 74  x that records t
54c0: 68 65 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61  he location of a
54d0: 6c 6c 0a 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  ll.instances of 
54e0: 70 72 65 66 69 78 20 74 6f 6b 65 6e 73 20 6f 66  prefix tokens of
54f0: 20 61 20 63 65 72 74 61 69 6e 20 6c 65 6e 67 74   a certain lengt
5500: 68 20 69 6e 20 63 68 61 72 61 63 74 65 72 73 20  h in characters 
5510: 75 73 65 64 20 74 6f 20 73 70 65 65 64 0a 75 70  used to speed.up
5520: 20 71 75 65 72 69 65 73 20 66 6f 72 20 70 72 65   queries for pre
5530: 66 69 78 20 74 6f 6b 65 6e 73 2e 20 46 6f 72 20  fix tokens. For 
5540: 65 78 61 6d 70 6c 65 2c 20 6f 70 74 69 6d 69 7a  example, optimiz
5550: 69 6e 67 20 61 20 71 75 65 72 79 20 66 6f 72 20  ing a query for 
5560: 70 72 65 66 69 78 0a 74 6f 6b 65 6e 20 22 61 62  prefix.token "ab
5570: 63 2a 22 20 72 65 71 75 69 72 65 73 20 61 20 70  c*" requires a p
5580: 72 65 66 69 78 20 69 6e 64 65 78 20 6f 66 20 74  refix index of t
5590: 68 72 65 65 2d 63 68 61 72 61 63 74 65 72 20 70  hree-character p
55a0: 72 65 66 69 78 65 73 2e 0a 0a 3c 70 3e 20 54 6f  refixes...<p> To
55b0: 20 61 64 64 20 70 72 65 66 69 78 20 69 6e 64 65   add prefix inde
55c0: 78 65 73 20 74 6f 20 61 6e 20 46 54 53 35 20 74  xes to an FTS5 t
55d0: 61 62 6c 65 2c 20 74 68 65 20 22 70 72 65 66 69  able, the "prefi
55e0: 78 22 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  x" option is set
55f0: 20 74 6f 0a 65 69 74 68 65 72 20 61 20 73 69 6e   to.either a sin
5600: 67 6c 65 20 70 6f 73 69 74 69 76 65 20 69 6e 74  gle positive int
5610: 65 67 65 72 20 6f 72 20 61 20 74 65 78 74 20 76  eger or a text v
5620: 61 6c 75 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  alue containing 
5630: 61 20 77 68 69 74 65 2d 73 70 61 63 65 0a 73 65  a white-space.se
5640: 70 61 72 61 74 65 64 20 6c 69 73 74 20 6f 66 20  parated list of 
5650: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 70 6f 73 69  one or more posi
5660: 74 69 76 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tive integer val
5670: 75 65 73 2e 20 41 20 70 72 65 66 69 78 20 69 6e  ues. A prefix in
5680: 64 65 78 20 69 73 0a 63 72 65 61 74 65 64 20 66  dex is.created f
5690: 6f 72 20 65 61 63 68 20 69 6e 74 65 67 65 72 20  or each integer 
56a0: 73 70 65 63 69 66 69 65 64 2e 20 49 66 20 6d 6f  specified. If mo
56b0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 22 70 72 65  re than one "pre
56c0: 66 69 78 22 20 6f 70 74 69 6f 6e 20 69 73 0a 73  fix" option is.s
56d0: 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
56e0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 43 52 45   of a single CRE
56f0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
5700: 45 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6c 6c  E statement, all
5710: 20 61 70 70 6c 79 2e 0a 0a 3c 63 6f 64 65 62 6c   apply...<codebl
5720: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 77 6f  ock>.  <i>-- Two
5730: 20 77 61 79 73 20 74 6f 20 63 72 65 61 74 65 20   ways to create 
5740: 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68  an FTS5 table th
5750: 61 74 20 6d 61 69 6e 74 61 69 6e 73 20 70 72 65  at maintains pre
5760: 66 69 78 20 69 6e 64 65 78 65 73 20 66 6f 72 0a  fix indexes for.
5770: 20 20 2d 2d 20 74 77 6f 20 61 6e 64 20 74 68 72    -- two and thr
5780: 65 65 20 63 68 61 72 61 63 74 65 72 20 70 72 65  ee character pre
5790: 66 69 78 20 74 6f 6b 65 6e 73 2e 3c 2f 69 3e 0a  fix tokens.</i>.
57a0: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
57b0: 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20   TABLE ft USING 
57c0: 66 74 73 35 28 61 2c 20 62 2c 20 70 72 65 66 69  fts5(a, b, prefi
57d0: 78 3d 27 32 20 33 27 29 3b 0a 20 20 43 52 45 41  x='2 3');.  CREA
57e0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
57f0: 20 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61   ft USING fts5(a
5800: 2c 20 62 2c 20 70 72 65 66 69 78 3d 32 2c 20 70  , b, prefix=2, p
5810: 72 65 66 69 78 3d 33 29 3b 0a 3c 2f 63 6f 64 65  refix=3);.</code
5820: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73  block>..<h2 tags
5830: 3d 22 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65 72  ="FTS5 tokenizer
5840: 73 22 3e 54 6f 6b 65 6e 69 7a 65 72 73 3c 2f 68  s">Tokenizers</h
5850: 32 3e 0a 0a 3c 70 3e 20 54 68 65 20 43 52 45 41  2>..<p> The CREA
5860: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
5870: 20 22 74 6f 6b 65 6e 69 7a 65 22 20 6f 70 74 69   "tokenize" opti
5880: 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
5890: 6e 66 69 67 75 72 65 20 74 68 65 0a 73 70 65 63  nfigure the.spec
58a0: 69 66 69 63 20 74 6f 6b 65 6e 69 7a 65 72 20 75  ific tokenizer u
58b0: 73 65 64 20 62 79 20 74 68 65 20 46 54 53 35 20  sed by the FTS5 
58c0: 74 61 62 6c 65 2e 20 54 68 65 20 6f 70 74 69 6f  table. The optio
58d0: 6e 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  n argument must 
58e0: 62 65 20 65 69 74 68 65 72 0a 61 6e 20 46 54 53  be either.an FTS
58f0: 35 20 62 61 72 65 77 6f 72 64 2c 20 6f 72 20 61  5 bareword, or a
5900: 6e 20 53 51 4c 20 74 65 78 74 20 6c 69 74 65 72  n SQL text liter
5910: 61 6c 2e 20 54 68 65 20 74 65 78 74 20 6f 66 20  al. The text of 
5920: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
5930: 69 74 73 65 6c 66 0a 74 72 65 61 74 65 64 20 61  itself.treated a
5940: 73 20 61 20 77 68 69 74 65 2d 73 70 61 63 65 20  s a white-space 
5950: 73 65 72 69 65 73 20 6f 66 20 6f 6e 65 20 6f 72  series of one or
5960: 20 6d 6f 72 65 20 46 54 53 35 20 62 61 72 65 77   more FTS5 barew
5970: 6f 72 64 73 20 6f 72 20 53 51 4c 20 74 65 78 74  ords or SQL text
5980: 0a 6c 69 74 65 72 61 6c 73 2e 20 54 68 65 20 66  .literals. The f
5990: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 69 73  irst of these is
59a0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
59b0: 20 74 6f 6b 65 6e 69 7a 65 72 20 74 6f 20 75 73   tokenizer to us
59c0: 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 61 6e  e. The second.an
59d0: 64 20 73 75 62 73 65 71 75 65 6e 74 20 6c 69 73  d subsequent lis
59e0: 74 20 65 6c 65 6d 65 6e 74 73 2c 20 69 66 20 74  t elements, if t
59f0: 68 65 79 20 65 78 69 73 74 2c 20 61 72 65 20 61  hey exist, are a
5a00: 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20  rguments passed 
5a10: 74 6f 20 74 68 65 0a 74 6f 6b 65 6e 69 7a 65 72  to the.tokenizer
5a20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
5a30: 0a 0a 3c 70 3e 20 55 6e 6c 69 6b 65 20 6f 70 74  ..<p> Unlike opt
5a40: 69 6f 6e 20 76 61 6c 75 65 73 20 61 6e 64 20 63  ion values and c
5a50: 6f 6c 75 6d 6e 20 6e 61 6d 65 73 2c 20 53 51 4c  olumn names, SQL
5a60: 20 74 65 78 74 20 6c 69 74 65 72 61 6c 73 20 69   text literals i
5a70: 6e 74 65 6e 64 65 64 20 61 73 0a 74 6f 6b 65 6e  ntended as.token
5a80: 69 7a 65 72 73 20 6d 75 73 74 20 62 65 20 71 75  izers must be qu
5a90: 6f 74 65 64 20 75 73 69 6e 67 20 73 69 6e 67 6c  oted using singl
5aa0: 65 20 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e quote characte
5ab0: 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  rs. For example:
5ac0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
5ad0: 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77  <i>-- The follow
5ae0: 69 6e 67 20 61 72 65 20 61 6c 6c 20 65 71 75 69  ing are all equi
5af0: 76 61 6c 65 6e 74 3c 2f 69 3e 0a 20 20 43 52 45  valent</i>.  CRE
5b00: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
5b10: 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28  E t1 USING fts5(
5b20: 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 70  x, tokenize = 'p
5b30: 6f 72 74 65 72 20 61 73 63 69 69 27 29 3b 0a 20  orter ascii');. 
5b40: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
5b50: 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66  TABLE t1 USING f
5b60: 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20  ts5(x, tokenize 
5b70: 3d 20 22 70 6f 72 74 65 72 20 61 73 63 69 69 22  = "porter ascii"
5b80: 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  );.  CREATE VIRT
5b90: 55 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49  UAL TABLE t1 USI
5ba0: 4e 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e  NG fts5(x, token
5bb0: 69 7a 65 20 3d 20 22 27 70 6f 72 74 65 72 27 20  ize = "'porter' 
5bc0: 27 61 73 63 69 69 27 22 29 3b 0a 20 20 43 52 45  'ascii'");.  CRE
5bd0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
5be0: 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35 28  E t1 USING fts5(
5bf0: 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 27  x, tokenize = ''
5c00: 27 70 6f 72 74 65 72 27 27 20 27 27 61 73 63 69  'porter'' ''asci
5c10: 69 27 27 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  i''');..  <i>-- 
5c20: 42 75 74 20 74 68 69 73 20 77 69 6c 6c 20 66 61  But this will fa
5c30: 69 6c 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45  il:</i>.  CREATE
5c40: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74   VIRTUAL TABLE t
5c50: 31 20 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20  1 USING fts5(x, 
5c60: 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 22 70 6f 72  tokenize = '"por
5c70: 74 65 72 22 20 22 61 73 63 69 69 22 27 29 3b 0a  ter" "ascii"');.
5c80: 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 77 69  .  <i>-- This wi
5c90: 6c 6c 20 66 61 69 6c 20 74 6f 6f 3a 3c 2f 69 3e  ll fail too:</i>
5ca0: 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
5cb0: 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47  L TABLE t1 USING
5cc0: 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a   fts5(x, tokeniz
5cd0: 65 20 3d 20 27 70 6f 72 74 65 72 27 20 27 61 73  e = 'porter' 'as
5ce0: 63 69 69 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  cii');.</codeblo
5cf0: 63 6b 3e 0a 0a 0a 3c 70 3e 0a 46 54 53 35 20 66  ck>...<p>.FTS5 f
5d00: 65 61 74 75 72 65 73 20 74 68 72 65 65 20 62 75  eatures three bu
5d10: 69 6c 74 2d 69 6e 20 74 6f 6b 65 6e 69 7a 65 72  ilt-in tokenizer
5d20: 20 6d 6f 64 75 6c 65 73 2c 20 64 65 73 63 72 69   modules, descri
5d30: 62 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  bed in subsequen
5d40: 74 0a 73 65 63 74 69 6f 6e 73 3a 0a 0a 3c 75 6c  t.sections:..<ul
5d50: 3e 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e  >.  <li> The <b>
5d60: 75 6e 69 63 6f 64 65 36 31 3c 2f 62 3e 20 74 6f  unicode61</b> to
5d70: 6b 65 6e 69 7a 65 72 2c 20 62 61 73 65 64 20 6f  kenizer, based o
5d80: 6e 20 74 68 65 20 55 6e 69 63 6f 64 65 20 36 2e  n the Unicode 6.
5d90: 31 20 73 74 61 6e 64 61 72 64 2e 20 54 68 69 73  1 standard. This
5da0: 0a 20 20 20 20 20 20 20 69 73 20 74 68 65 20 64  .       is the d
5db0: 65 66 61 75 6c 74 2e 0a 0a 20 20 3c 6c 69 3e 20  efault...  <li> 
5dc0: 54 68 65 20 3c 62 3e 61 73 63 69 69 3c 2f 62 3e  The <b>ascii</b>
5dd0: 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 77 68 69 63   tokenizer, whic
5de0: 68 20 61 73 73 75 6d 65 73 20 61 6c 6c 20 63 68  h assumes all ch
5df0: 61 72 61 63 74 65 72 73 20 6f 75 74 73 69 64 65  aracters outside
5e00: 20 6f 66 0a 20 20 74 68 65 20 41 53 43 49 49 20   of.  the ASCII 
5e10: 63 6f 64 65 70 6f 69 6e 74 20 72 61 6e 67 65 20  codepoint range 
5e20: 28 30 2d 31 32 37 29 20 61 72 65 20 74 6f 20 62  (0-127) are to b
5e30: 65 20 74 72 65 61 74 65 64 20 61 73 20 74 6f 6b  e treated as tok
5e40: 65 6e 20 63 68 61 72 61 63 74 65 72 73 2e 0a 0a  en characters...
5e50: 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e 70 6f    <li> The <b>po
5e60: 72 74 65 72 3c 2f 62 3e 20 74 6f 6b 65 6e 69 7a  rter</b> tokeniz
5e70: 65 72 2c 20 77 68 69 63 68 20 69 6d 70 6c 65 6d  er, which implem
5e80: 65 6e 74 73 20 74 68 65 20 0a 3c 61 20 68 72 65  ents the .<a hre
5e90: 66 3d 68 74 74 70 3a 2f 2f 74 61 72 74 61 72 75  f=http://tartaru
5ea0: 73 2e 6f 72 67 2f 6d 61 72 74 69 6e 2f 50 6f 72  s.org/martin/Por
5eb0: 74 65 72 53 74 65 6d 6d 65 72 2f 3e 70 6f 72 74  terStemmer/>port
5ec0: 65 72 20 73 74 65 6d 6d 69 6e 67 20 61 6c 67 6f  er stemming algo
5ed0: 72 69 74 68 6d 3c 2f 61 3e 2e 0a 3c 2f 75 6c 3e  rithm</a>..</ul>
5ee0: 0a 0a 3c 70 3e 20 49 74 20 69 73 20 61 6c 73 6f  ..<p> It is also
5ef0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 72 65   possible to cre
5f00: 61 74 65 20 63 75 73 74 6f 6d 20 74 6f 6b 65 6e  ate custom token
5f10: 69 7a 65 72 73 20 66 6f 72 20 46 54 53 35 2e 20  izers for FTS5. 
5f20: 54 68 65 20 41 50 49 20 66 6f 72 20 64 6f 69 6e  The API for doin
5f30: 67 20 73 6f 20 69 73 20 5b 63 75 73 74 6f 6d 20  g so is [custom 
5f40: 74 6f 6b 65 6e 69 7a 65 72 73 20 7c 20 64 65 73  tokenizers | des
5f50: 63 72 69 62 65 64 20 68 65 72 65 5d 2e 0a 0a 3c  cribed here]...<
5f60: 68 33 3e 55 6e 69 63 6f 64 65 36 31 20 54 6f 6b  h3>Unicode61 Tok
5f70: 65 6e 69 7a 65 72 3c 2f 68 33 3e 0a 0a 3c 70 3e  enizer</h3>..<p>
5f80: 20 54 68 65 20 75 6e 69 63 6f 64 65 20 74 6f 6b   The unicode tok
5f90: 65 6e 69 7a 65 72 20 63 6c 61 73 73 69 66 69 65  enizer classifie
5fa0: 73 20 61 6c 6c 20 75 6e 69 63 6f 64 65 20 63 68  s all unicode ch
5fb0: 61 72 61 63 74 65 72 73 20 61 73 20 65 69 74 68  aracters as eith
5fc0: 65 72 20 0a 22 73 65 70 61 72 61 74 6f 72 22 20  er ."separator" 
5fd0: 6f 72 20 22 74 6f 6b 65 6e 22 20 63 68 61 72 61  or "token" chara
5fe0: 63 74 65 72 73 2e 20 42 79 20 64 65 66 61 75 6c  cters. By defaul
5ff0: 74 20 61 6c 6c 20 73 70 61 63 65 20 61 6e 64 20  t all space and 
6000: 70 75 6e 63 74 75 61 74 69 6f 6e 0a 63 68 61 72  punctuation.char
6010: 61 63 74 65 72 73 2c 20 61 73 20 64 65 66 69 6e  acters, as defin
6020: 65 64 20 62 79 20 55 6e 69 63 6f 64 65 20 36 2e  ed by Unicode 6.
6030: 31 2c 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65  1, are considere
6040: 64 20 73 65 70 61 72 61 74 6f 72 73 2c 20 61 6e  d separators, an
6050: 64 20 61 6c 6c 20 0a 6f 74 68 65 72 20 63 68 61  d all .other cha
6060: 72 61 63 74 65 72 73 20 61 73 20 74 6f 6b 65 6e  racters as token
6070: 20 63 68 61 72 61 63 74 65 72 73 2e 20 4d 6f 72   characters. Mor
6080: 65 20 73 70 65 63 69 66 69 63 61 6c 6c 79 2c 20  e specifically, 
6090: 61 6c 6c 20 75 6e 69 63 6f 64 65 20 0a 63 68 61  all unicode .cha
60a0: 72 61 63 74 65 72 73 20 61 73 73 69 67 6e 65 64  racters assigned
60b0: 20 74 6f 20 61 20 0a 3c 61 20 68 72 65 66 3d 68   to a .<a href=h
60c0: 74 74 70 73 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65  ttps://en.wikipe
60d0: 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 55 6e 69  dia.org/wiki/Uni
60e0: 63 6f 64 65 5f 63 68 61 72 61 63 74 65 72 5f 70  code_character_p
60f0: 72 6f 70 65 72 74 79 23 47 65 6e 65 72 61 6c 5f  roperty#General_
6100: 43 61 74 65 67 6f 72 79 3e 0a 67 65 6e 65 72 61  Category>.genera
6110: 6c 20 63 61 74 65 67 6f 72 79 3c 2f 61 3e 20 62  l category</a> b
6120: 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 22 4c  eginning with "L
6130: 22 20 6f 72 20 22 4e 22 20 28 6c 65 74 74 65 72  " or "N" (letter
6140: 73 20 61 6e 64 20 6e 75 6d 62 65 72 73 2c 0a 73  s and numbers,.s
6150: 70 65 63 69 66 69 63 61 6c 6c 79 29 20 6f 72 20  pecifically) or 
6160: 74 6f 20 63 61 74 65 67 6f 72 79 20 22 43 6f 22  to category "Co"
6170: 20 28 22 6f 74 68 65 72 2c 20 70 72 69 76 61 74   ("other, privat
6180: 65 20 75 73 65 22 29 20 61 72 65 20 63 6f 6e 73  e use") are cons
6190: 69 64 65 72 65 64 20 74 6f 6b 65 6e 73 2e 0a 41  idered tokens..A
61a0: 6c 6c 20 6f 74 68 65 72 20 63 68 61 72 61 63 74  ll other charact
61b0: 65 72 73 20 61 72 65 20 73 65 70 61 72 61 74 6f  ers are separato
61c0: 72 73 2e 0a 20 0a 3c 70 3e 45 61 63 68 20 63 6f  rs.. .<p>Each co
61d0: 6e 74 69 67 75 6f 75 73 20 72 75 6e 20 6f 66 20  ntiguous run of 
61e0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 6f 6b 65  one or more toke
61f0: 6e 20 63 68 61 72 61 63 74 65 72 73 20 69 73 20  n characters is 
6200: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
6210: 20 61 0a 74 6f 6b 65 6e 2e 20 54 68 65 20 74 6f   a.token. The to
6220: 6b 65 6e 69 7a 65 72 20 69 73 20 63 61 73 65 2d  kenizer is case-
6230: 69 6e 73 65 6e 73 69 74 69 76 65 20 61 63 63 6f  insensitive acco
6240: 72 64 69 6e 67 20 74 6f 20 74 68 65 20 72 75 6c  rding to the rul
6250: 65 73 20 64 65 66 69 6e 65 64 20 62 79 0a 55 6e  es defined by.Un
6260: 69 63 6f 64 65 20 36 2e 31 2e 0a 0a 3c 70 3e 20  icode 6.1...<p> 
6270: 42 79 20 64 65 66 61 75 6c 74 2c 20 64 69 61 63  By default, diac
6280: 72 69 74 69 63 73 20 61 72 65 20 72 65 6d 6f 76  ritics are remov
6290: 65 64 20 66 72 6f 6d 20 61 6c 6c 20 4c 61 74 69  ed from all Lati
62a0: 6e 20 73 63 72 69 70 74 20 63 68 61 72 61 63 74  n script charact
62b0: 65 72 73 2e 20 54 68 69 73 0a 6d 65 61 6e 73 2c  ers. This.means,
62c0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68   for example, th
62d0: 61 74 20 22 41 22 2c 20 22 61 22 2c 20 22 26 23  at "A", "a", "&#
62e0: 31 39 32 3b 22 2c 20 22 26 23 32 32 34 3b 22 2c  192;", "&#224;",
62f0: 20 22 26 23 31 39 34 3b 22 20 61 6e 64 20 22 26   "&#194;" and "&
6300: 23 32 32 36 3b 22 0a 61 72 65 20 61 6c 6c 20 63  #226;".are all c
6310: 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
6320: 65 71 75 69 76 61 6c 65 6e 74 2e 0a 0a 3c 70 3e  equivalent...<p>
6330: 20 41 6e 79 20 61 72 67 75 6d 65 6e 74 73 20 66   Any arguments f
6340: 6f 6c 6c 6f 77 69 6e 67 20 22 75 6e 69 63 6f 64  ollowing "unicod
6350: 65 36 31 22 20 69 6e 20 74 68 65 20 74 6f 6b 65  e61" in the toke
6360: 6e 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  n specification 
6370: 61 72 65 20 74 72 65 61 74 65 64 0a 61 73 20 61  are treated.as a
6380: 20 6c 69 73 74 20 6f 66 20 61 6c 74 65 72 6e 61   list of alterna
6390: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 6e 61 6d 65  ting option name
63a0: 73 20 61 6e 64 20 76 61 6c 75 65 73 2e 20 55 6e  s and values. Un
63b0: 69 63 6f 64 65 36 31 20 73 75 70 70 6f 72 74 73  icode61 supports
63c0: 20 74 68 65 0a 66 6f 6c 6c 6f 77 69 6e 67 20 6f   the.following o
63d0: 70 74 69 6f 6e 73 3a 0a 0a 3c 74 61 62 6c 65 20  ptions:..<table 
63e0: 73 74 72 69 70 65 64 3d 31 3e 0a 20 20 3c 74 72  striped=1>.  <tr
63f0: 3e 3c 74 68 3e 20 4f 70 74 69 6f 6e 20 3c 74 68  ><th> Option <th
6400: 3e 20 55 73 61 67 65 0a 20 20 3c 74 72 3e 3c 74  > Usage.  <tr><t
6410: 64 3e 20 72 65 6d 6f 76 65 5f 64 69 61 63 72 69  d> remove_diacri
6420: 74 69 63 73 0a 20 20 3c 74 64 3e 54 68 69 73 20  tics.  <td>This 
6430: 6f 70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  option should be
6440: 20 73 65 74 20 74 6f 20 22 30 22 20 6f 72 20 22   set to "0" or "
6450: 31 22 2e 20 49 66 20 69 74 20 69 73 20 73 65 74  1". If it is set
6460: 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 2c 0a   (the default),.
6470: 20 20 64 69 61 63 72 69 74 69 63 73 20 61 72 65    diacritics are
6480: 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 61 6c   removed from al
6490: 6c 20 6c 61 74 69 6e 20 73 63 72 69 70 74 20 63  l latin script c
64a0: 68 61 72 61 63 74 65 72 73 20 61 73 20 64 65 73  haracters as des
64b0: 63 72 69 62 65 64 20 61 62 6f 76 65 2e 0a 20 20  cribed above..  
64c0: 49 66 20 69 74 20 69 73 20 63 6c 65 61 72 2c 20  If it is clear, 
64d0: 74 68 65 79 20 61 72 65 20 6e 6f 74 2e 20 0a 0a  they are not. ..
64e0: 20 20 3c 74 72 3e 3c 74 64 3e 20 63 61 74 65 67    <tr><td> categ
64f0: 6f 72 69 65 73 0a 20 20 3c 74 64 3e 54 68 69 73  ories.  <td>This
6500: 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
6510: 73 65 64 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  sed to modify th
6520: 65 20 73 65 74 20 6f 66 20 55 6e 69 63 6f 64 65  e set of Unicode
6530: 20 67 65 6e 65 72 61 6c 20 63 61 74 65 67 6f 72   general categor
6540: 69 65 73 0a 20 20 74 68 61 74 20 61 72 65 20 63  ies.  that are c
6550: 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 63 6f 72  onsidered to cor
6560: 72 65 73 70 6f 6e 64 20 74 6f 20 74 6f 6b 65 6e  respond to token
6570: 20 63 68 61 72 61 63 74 65 72 73 2e 20 54 68 65   characters. The
6580: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 20   argument must. 
6590: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 70   consist of a sp
65a0: 61 63 65 20 73 65 70 61 72 61 74 65 64 20 6c 69  ace separated li
65b0: 73 74 20 6f 66 20 74 77 6f 2d 63 68 61 72 61 63  st of two-charac
65c0: 74 65 72 20 67 65 6e 65 72 61 6c 20 63 61 74 65  ter general cate
65d0: 67 6f 72 79 0a 20 20 61 62 62 72 65 76 69 61 74  gory.  abbreviat
65e0: 69 6f 6e 73 20 28 65 2e 67 2e 20 22 4c 75 22 20  ions (e.g. "Lu" 
65f0: 6f 72 20 22 4e 64 22 29 2c 20 6f 72 20 6f 66 20  or "Nd"), or of 
6600: 74 68 65 20 73 61 6d 65 20 77 69 74 68 20 74 68  the same with th
6610: 65 20 73 65 63 6f 6e 64 20 63 68 61 72 61 63 74  e second charact
6620: 65 72 0a 20 20 72 65 70 6c 61 63 65 64 20 77 69  er.  replaced wi
6630: 74 68 20 61 6e 20 61 73 74 65 72 69 78 20 28 22  th an asterix ("
6640: 2a 22 29 2c 20 69 6e 74 65 72 70 72 65 74 65 64  *"), interpreted
6650: 20 61 73 20 61 20 67 6c 6f 62 20 70 61 74 74 65   as a glob patte
6660: 72 6e 2e 20 54 68 65 20 64 65 66 61 75 6c 74 0a  rn. The default.
6670: 20 20 76 61 6c 75 65 20 69 73 20 22 4c 2a 20 4e    value is "L* N
6680: 2a 20 43 6f 22 2e 0a 0a 20 20 3c 74 72 3e 3c 74  * Co"...  <tr><t
6690: 64 3e 20 74 6f 6b 65 6e 63 68 61 72 73 0a 20 20  d> tokenchars.  
66a0: 3c 74 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <td> This option
66b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 70 65 63   is used to spec
66c0: 69 66 79 20 61 64 64 69 74 69 6f 6e 61 6c 20 75  ify additional u
66d0: 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 65 72  nicode character
66e0: 73 20 74 68 61 74 20 0a 20 20 73 68 6f 75 6c 64  s that .  should
66f0: 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74   be considered t
6700: 6f 6b 65 6e 20 63 68 61 72 61 63 74 65 72 73 2c  oken characters,
6710: 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 61 72   even if they ar
6720: 65 20 77 68 69 74 65 2d 73 70 61 63 65 20 6f 72  e white-space or
6730: 0a 20 20 70 75 6e 63 74 75 61 74 69 6f 6e 20 63  .  punctuation c
6740: 68 61 72 61 63 74 65 72 73 20 61 63 63 6f 72 64  haracters accord
6750: 69 6e 67 20 74 6f 20 55 6e 69 63 6f 64 65 20 36  ing to Unicode 6
6760: 2e 31 2e 20 41 6c 6c 20 63 68 61 72 61 63 74 65  .1. All characte
6770: 72 73 20 69 6e 20 74 68 65 0a 20 20 73 74 72 69  rs in the.  stri
6780: 6e 67 20 74 68 61 74 20 74 68 69 73 20 6f 70 74  ng that this opt
6790: 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 61 72  ion is set to ar
67a0: 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b  e considered tok
67b0: 65 6e 20 63 68 61 72 61 63 74 65 72 73 2e 0a 0a  en characters...
67c0: 20 20 3c 74 72 3e 3c 74 64 3e 20 73 65 70 61 72    <tr><td> separ
67d0: 61 74 6f 72 73 0a 20 20 3c 74 64 3e 20 54 68 69  ators.  <td> Thi
67e0: 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
67f0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 64 64 69   to specify addi
6800: 74 69 6f 6e 61 6c 20 75 6e 69 63 6f 64 65 20 63  tional unicode c
6810: 68 61 72 61 63 74 65 72 73 20 74 68 61 74 20 0a  haracters that .
6820: 20 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73    should be cons
6830: 69 64 65 72 65 64 20 61 73 20 73 65 70 61 72 61  idered as separa
6840: 74 6f 72 20 63 68 61 72 61 63 74 65 72 73 2c 20  tor characters, 
6850: 65 76 65 6e 20 69 66 20 74 68 65 79 20 61 72 65  even if they are
6860: 20 74 6f 6b 65 6e 0a 20 20 63 68 61 72 61 63 74   token.  charact
6870: 65 72 73 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ers according to
6880: 20 55 6e 69 63 6f 64 65 20 36 2e 31 2e 20 41 6c   Unicode 6.1. Al
6890: 6c 20 63 68 61 72 61 63 74 65 72 73 20 69 6e 20  l characters in 
68a0: 74 68 65 20 73 74 72 69 6e 67 20 74 68 61 74 20  the string that 
68b0: 0a 20 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  .  this option i
68c0: 73 20 73 65 74 20 74 6f 20 61 72 65 20 63 6f 6e  s set to are con
68d0: 73 69 64 65 72 65 64 20 73 65 70 61 72 61 74 6f  sidered separato
68e0: 72 73 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70  rs..</table>..<p
68f0: 3e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  > For example:..
6900: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
6910: 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20 46 54  >-- Create an FT
6920: 53 35 20 74 61 62 6c 65 20 74 68 61 74 20 64 6f  S5 table that do
6930: 65 73 20 6e 6f 74 20 72 65 6d 6f 76 65 20 64 69  es not remove di
6940: 61 63 72 69 74 69 63 73 20 66 72 6f 6d 20 4c 61  acritics from La
6950: 74 69 6e 0a 20 20 2d 2d 20 73 63 72 69 70 74 20  tin.  -- script 
6960: 63 68 61 72 61 63 74 65 72 73 2c 20 61 6e 64 20  characters, and 
6970: 74 68 61 74 20 63 6f 6e 73 69 64 65 72 73 20 68  that considers h
6980: 79 70 68 65 6e 73 20 61 6e 64 20 75 6e 64 65 72  yphens and under
6990: 73 63 6f 72 65 20 63 68 61 72 61 63 74 65 72 73  score characters
69a0: 0a 20 20 2d 2d 20 74 6f 20 62 65 20 70 61 72 74  .  -- to be part
69b0: 20 6f 66 20 74 6f 6b 65 6e 73 2e 20 3c 2f 69 3e   of tokens. </i>
69c0: 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
69d0: 4c 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47  L TABLE ft USING
69e0: 20 66 74 73 35 28 61 2c 20 62 2c 20 0a 20 20 20   fts5(a, b, .   
69f0: 20 20 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 22 75     tokenize = "u
6a00: 6e 69 63 6f 64 65 36 31 20 72 65 6d 6f 76 65 5f  nicode61 remove_
6a10: 64 69 61 63 72 69 74 69 63 73 20 30 20 74 6f 6b  diacritics 0 tok
6a20: 65 6e 63 68 61 72 73 20 27 2d 5f 27 22 0a 20 20  enchars '-_'".  
6a30: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
6a40: 0a 3c 70 3e 20 6f 72 3a 0a 0a 3c 63 6f 64 65 62  .<p> or:..<codeb
6a50: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72  lock>.  <i>-- Cr
6a60: 65 61 74 65 20 61 6e 20 46 54 53 35 20 74 61 62  eate an FTS5 tab
6a70: 6c 65 20 74 68 61 74 2c 20 61 73 20 77 65 6c 6c  le that, as well
6a80: 20 61 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   as the default 
6a90: 74 6f 6b 65 6e 20 63 68 61 72 61 63 74 65 72 20  token character 
6aa0: 63 6c 61 73 73 65 73 2c 3c 2f 69 3e 0a 20 20 3c  classes,</i>.  <
6ab0: 69 3e 2d 2d 20 63 6f 6e 73 69 64 65 72 73 20 63  i>-- considers c
6ac0: 68 61 72 61 63 74 65 72 73 20 69 6e 20 63 6c 61  haracters in cla
6ad0: 73 73 20 22 4d 6e 22 20 74 6f 20 62 65 20 74 6f  ss "Mn" to be to
6ae0: 6b 65 6e 20 63 68 61 72 61 63 74 65 72 73 2e 3c  ken characters.<
6af0: 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52  /i>.  CREATE VIR
6b00: 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55 53  TUAL TABLE ft US
6b10: 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20 0a  ING fts5(a, b, .
6b20: 20 20 20 20 20 20 74 6f 6b 65 6e 69 7a 65 20 3d        tokenize =
6b30: 20 22 75 6e 69 63 6f 64 65 36 31 20 63 61 74 65   "unicode61 cate
6b40: 67 6f 72 69 65 73 20 27 4c 2a 20 4e 2a 20 43 6f  gories 'L* N* Co
6b50: 20 4d 6e 27 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64   Mn'".  );.</cod
6b60: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65  eblock>..<p> The
6b70: 20 66 74 73 35 20 75 6e 69 63 6f 64 65 36 31 20   fts5 unicode61 
6b80: 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 62 79 74  tokenizer is byt
6b90: 65 2d 66 6f 72 2d 62 79 74 65 20 63 6f 6d 70 61  e-for-byte compa
6ba0: 74 69 62 6c 65 20 77 69 74 68 20 74 68 65 20 66  tible with the f
6bb0: 74 73 33 2f 34 0a 75 6e 69 63 6f 64 65 36 31 20  ts3/4.unicode61 
6bc0: 74 6f 6b 65 6e 69 7a 65 72 2e 0a 0a 3c 68 33 3e  tokenizer...<h3>
6bd0: 41 73 63 69 69 20 54 6f 6b 65 6e 69 7a 65 72 3c  Ascii Tokenizer<
6be0: 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20 41 73  /h3>..<p> The As
6bf0: 63 69 69 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73  cii tokenizer is
6c00: 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 20   similar to the 
6c10: 55 6e 69 63 6f 64 65 36 31 20 74 6f 6b 65 6e 69  Unicode61 tokeni
6c20: 7a 65 72 2c 20 65 78 63 65 70 74 20 74 68 61 74  zer, except that
6c30: 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 41  :..<ul>.  <li> A
6c40: 6c 6c 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  ll non-ASCII cha
6c50: 72 61 63 74 65 72 73 20 28 74 68 6f 73 65 20 77  racters (those w
6c60: 69 74 68 20 63 6f 64 65 70 6f 69 6e 74 73 20 67  ith codepoints g
6c70: 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 29  reater than 127)
6c80: 20 61 72 65 0a 20 20 61 6c 77 61 79 73 20 63 6f   are.  always co
6c90: 6e 73 69 64 65 72 65 64 20 74 6f 6b 65 6e 20 63  nsidered token c
6ca0: 68 61 72 61 63 74 65 72 73 2e 20 49 66 20 61 6e  haracters. If an
6cb0: 79 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72  y non-ASCII char
6cc0: 61 63 74 65 72 73 20 61 72 65 20 73 70 65 63 69  acters are speci
6cd0: 66 69 65 64 0a 20 20 61 73 20 70 61 72 74 20 6f  fied.  as part o
6ce0: 66 20 74 68 65 20 73 65 70 61 72 61 74 6f 72 73  f the separators
6cf0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 79 20 61 72   option, they ar
6d00: 65 20 69 67 6e 6f 72 65 64 2e 20 20 0a 0a 20 20  e ignored.  ..  
6d10: 3c 6c 69 3e 20 43 61 73 65 2d 66 6f 6c 64 69 6e  <li> Case-foldin
6d20: 67 20 69 73 20 6f 6e 6c 79 20 70 65 72 66 6f 72  g is only perfor
6d30: 6d 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68  med for ASCII ch
6d40: 61 72 61 63 74 65 72 73 2e 20 53 6f 20 77 68 69  aracters. So whi
6d50: 6c 65 20 22 41 22 20 61 6e 64 0a 20 20 22 61 22  le "A" and.  "a"
6d60: 20 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20   are considered 
6d70: 74 6f 20 62 65 20 65 71 75 69 76 61 6c 65 6e 74  to be equivalent
6d80: 2c 20 22 26 23 31 39 35 22 20 61 6e 64 20 22 26  , "&#195" and "&
6d90: 23 32 32 37 3b 22 20 61 72 65 20 64 69 73 74 69  #227;" are disti
6da0: 6e 63 74 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65  nct...  <li> The
6db0: 20 72 65 6d 6f 76 65 5f 64 69 61 63 72 69 74 69   remove_diacriti
6dc0: 63 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74  cs option is not
6dd0: 20 73 75 70 70 6f 72 74 65 64 2e 0a 3c 2f 75 6c   supported..</ul
6de0: 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65 78 61 6d 70  >..<p> For examp
6df0: 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  le:..<codeblock>
6e00: 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20  .  <i>-- Create 
6e10: 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68  an FTS5 table th
6e20: 61 74 20 75 73 65 73 20 74 68 65 20 61 73 63 69  at uses the asci
6e30: 69 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 62 75 74  i tokenizer, but
6e40: 20 64 6f 65 73 20 6e 6f 74 0a 20 20 2d 2d 20 63   does not.  -- c
6e50: 6f 6e 73 69 64 65 72 20 6e 75 6d 65 72 69 63 20  onsider numeric 
6e60: 63 68 61 72 61 63 74 65 72 73 20 74 6f 20 62 65  characters to be
6e70: 20 70 61 72 74 20 6f 66 20 74 6f 6b 65 6e 73 2e   part of tokens.
6e80: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
6e90: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
6ea0: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
6eb0: 0a 20 20 20 20 20 20 74 6f 6b 65 6e 69 7a 65 20  .      tokenize 
6ec0: 3d 20 22 61 73 63 69 69 20 73 65 70 61 72 61 74  = "ascii separat
6ed0: 6f 72 73 20 27 30 31 32 33 34 35 36 37 38 39 27  ors '0123456789'
6ee0: 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ".  );.</codeblo
6ef0: 63 6b 3e 0a 0a 3c 68 33 3e 50 6f 72 74 65 72 20  ck>..<h3>Porter 
6f00: 54 6f 6b 65 6e 69 7a 65 72 3c 2f 68 33 3e 0a 0a  Tokenizer</h3>..
6f10: 3c 70 3e 20 54 68 65 20 70 6f 72 74 65 72 20 74  <p> The porter t
6f20: 6f 6b 65 6e 69 7a 65 72 20 69 73 20 61 20 77 72  okenizer is a wr
6f30: 61 70 70 65 72 20 74 6f 6b 65 6e 69 7a 65 72 2e  apper tokenizer.
6f40: 20 49 74 20 74 61 6b 65 73 20 74 68 65 20 6f 75   It takes the ou
6f50: 74 70 75 74 20 6f 66 20 73 6f 6d 65 0a 6f 74 68  tput of some.oth
6f60: 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20 61 6e 64  er tokenizer and
6f70: 20 61 70 70 6c 69 65 73 20 74 68 65 20 0a 3c 61   applies the .<a
6f80: 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f 74 61 72   href=http://tar
6f90: 74 61 72 75 73 2e 6f 72 67 2f 6d 61 72 74 69 6e  tarus.org/martin
6fa0: 2f 50 6f 72 74 65 72 53 74 65 6d 6d 65 72 2f 3e  /PorterStemmer/>
6fb0: 70 6f 72 74 65 72 20 73 74 65 6d 6d 69 6e 67 20  porter stemming 
6fc0: 61 6c 67 6f 72 69 74 68 6d 3c 2f 61 3e 0a 74 6f  algorithm</a>.to
6fd0: 20 65 61 63 68 20 74 6f 6b 65 6e 20 62 65 66 6f   each token befo
6fe0: 72 65 20 69 74 20 72 65 74 75 72 6e 73 20 69 74  re it returns it
6ff0: 20 74 6f 20 46 54 53 35 2e 20 54 68 69 73 20 61   to FTS5. This a
7000: 6c 6c 6f 77 73 20 73 65 61 72 63 68 20 74 65 72  llows search ter
7010: 6d 73 20 6c 69 6b 65 0a 22 63 6f 72 72 65 63 74  ms like."correct
7020: 69 6f 6e 22 20 74 6f 20 6d 61 74 63 68 20 73 69  ion" to match si
7030: 6d 69 6c 61 72 20 77 6f 72 64 73 20 73 75 63 68  milar words such
7040: 20 61 73 20 22 63 6f 72 72 65 63 74 65 64 22 20   as "corrected" 
7050: 6f 72 20 22 63 6f 72 72 65 63 74 69 6e 67 22 2e  or "correcting".
7060: 20 54 68 65 0a 70 6f 72 74 65 72 20 73 74 65 6d   The.porter stem
7070: 6d 65 72 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  mer algorithm is
7080: 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
7090: 65 20 77 69 74 68 20 45 6e 67 6c 69 73 68 20 6c  e with English l
70a0: 61 6e 67 75 61 67 65 20 74 65 72 6d 73 20 0a 6f  anguage terms .o
70b0: 6e 6c 79 20 2d 20 75 73 69 6e 67 20 69 74 20 77  nly - using it w
70c0: 69 74 68 20 6f 74 68 65 72 20 6c 61 6e 67 75 61  ith other langua
70d0: 67 65 73 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  ges may or may n
70e0: 6f 74 20 69 6d 70 72 6f 76 65 20 73 65 61 72 63  ot improve searc
70f0: 68 20 75 74 69 6c 69 74 79 2e 0a 0a 3c 70 3e 20  h utility...<p> 
7100: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
7110: 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72  porter tokenizer
7120: 20 6f 70 65 72 61 74 65 73 20 61 73 20 61 20 77   operates as a w
7130: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68  rapper around th
7140: 65 20 64 65 66 61 75 6c 74 0a 74 6f 6b 65 6e 69  e default.tokeni
7150: 7a 65 72 20 28 75 6e 69 63 6f 64 65 36 31 29 2e  zer (unicode61).
7160: 20 4f 72 2c 20 69 66 20 6f 6e 65 20 6f 72 20 6d   Or, if one or m
7170: 6f 72 65 20 65 78 74 72 61 20 61 72 67 75 6d 65  ore extra argume
7180: 6e 74 73 20 61 72 65 20 61 64 64 65 64 20 74 6f  nts are added to
7190: 20 74 68 65 0a 22 74 6f 6b 65 6e 69 7a 65 22 20   the."tokenize" 
71a0: 6f 70 74 69 6f 6e 20 66 6f 6c 6c 6f 77 69 6e 67  option following
71b0: 20 22 70 6f 72 74 65 72 22 2c 20 74 68 65 79 20   "porter", they 
71c0: 61 72 65 20 74 72 65 61 74 65 64 20 61 73 20 61  are treated as a
71d0: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 66   specification f
71e0: 6f 72 0a 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  or.the underlyin
71f0: 67 20 74 6f 6b 65 6e 69 7a 65 72 20 74 68 61 74  g tokenizer that
7200: 20 74 68 65 20 70 6f 72 74 65 72 20 73 74 65 6d   the porter stem
7210: 6d 65 72 20 75 73 65 73 2e 20 46 6f 72 20 65 78  mer uses. For ex
7220: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
7230: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 77 6f 20  ck>.  <i>-- Two 
7240: 77 61 79 73 20 74 6f 20 63 72 65 61 74 65 20 61  ways to create a
7250: 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74 68 61  n FTS5 table tha
7260: 74 20 75 73 65 73 20 74 68 65 20 70 6f 72 74 65  t uses the porte
7270: 72 20 74 6f 6b 65 6e 69 7a 65 72 20 74 6f 0a 20  r tokenizer to. 
7280: 20 2d 2d 20 73 74 65 6d 20 74 68 65 20 6f 75 74   -- stem the out
7290: 70 75 74 20 6f 66 20 74 68 65 20 64 65 66 61 75  put of the defau
72a0: 6c 74 20 74 6f 6b 65 6e 69 7a 65 72 20 28 75 6e  lt tokenizer (un
72b0: 69 63 6f 64 65 36 31 29 2e 20 3c 2f 69 3e 0a 20  icode61). </i>. 
72c0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
72d0: 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66  TABLE t1 USING f
72e0: 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20  ts5(x, tokenize 
72f0: 3d 20 70 6f 72 74 65 72 29 3b 20 0a 20 20 43 52  = porter); .  CR
7300: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
7310: 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35  LE t1 USING fts5
7320: 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  (x, tokenize = '
7330: 70 6f 72 74 65 72 20 75 6e 69 63 6f 64 65 36 31  porter unicode61
7340: 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 41 20 70  ');..  <i>-- A p
7350: 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20  orter tokenizer 
7360: 75 73 65 64 20 74 6f 20 73 74 65 6d 20 74 68 65  used to stem the
7370: 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 20 75   output of the u
7380: 6e 69 63 6f 64 65 36 31 20 74 6f 6b 65 6e 69 7a  nicode61 tokeniz
7390: 65 72 2c 0a 20 20 2d 2d 20 77 69 74 68 20 64 69  er,.  -- with di
73a0: 61 63 72 69 74 69 63 73 20 72 65 6d 6f 76 65 64  acritics removed
73b0: 20 62 65 66 6f 72 65 20 73 74 65 6d 6d 69 6e 67   before stemming
73c0: 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  .</i>.  CREATE V
73d0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20  IRTUAL TABLE t1 
73e0: 55 53 49 4e 47 20 66 74 73 35 28 78 2c 20 74 6f  USING fts5(x, to
73f0: 6b 65 6e 69 7a 65 20 3d 20 27 70 6f 72 74 65 72  kenize = 'porter
7400: 20 75 6e 69 63 6f 64 65 36 31 20 72 65 6d 6f 76   unicode61 remov
7410: 65 5f 64 69 61 63 72 69 74 69 63 73 20 31 27 29  e_diacritics 1')
7420: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
7430: 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 63  <h2 tags="FTS5 c
7440: 6f 6e 74 65 6e 74 20 6f 70 74 69 6f 6e 22 3e 45  ontent option">E
7450: 78 74 65 72 6e 61 6c 20 43 6f 6e 74 65 6e 74 20  xternal Content 
7460: 61 6e 64 20 43 6f 6e 74 65 6e 74 6c 65 73 73 20  and Contentless 
7470: 54 61 62 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e  Tables</h2>..<p>
7480: 0a 4e 6f 72 6d 61 6c 6c 79 2c 20 77 68 65 6e 20  .Normally, when 
7490: 61 20 72 6f 77 20 69 73 20 69 6e 73 65 72 74 65  a row is inserte
74a0: 64 20 69 6e 74 6f 20 61 6e 20 46 54 53 35 20 74  d into an FTS5 t
74b0: 61 62 6c 65 2c 20 61 73 20 77 65 6c 6c 20 61 73  able, as well as
74c0: 20 74 68 65 20 76 61 72 69 6f 75 73 0a 66 75 6c   the various.ful
74d0: 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 65 6e 74  l-text index ent
74e0: 72 69 65 73 20 61 6e 64 20 6f 74 68 65 72 20 64  ries and other d
74f0: 61 74 61 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ata a copy of th
7500: 65 20 72 6f 77 20 69 73 20 73 74 6f 72 65 64 20  e row is stored 
7510: 69 6e 20 61 20 70 72 69 76 61 74 65 0a 74 61 62  in a private.tab
7520: 6c 65 20 6d 61 6e 61 67 65 64 20 62 79 20 74 68  le managed by th
7530: 65 20 46 54 53 35 20 6d 6f 64 75 6c 65 2e 20 57  e FTS5 module. W
7540: 68 65 6e 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  hen column value
7550: 73 20 61 72 65 20 72 65 71 75 65 73 74 65 64 20  s are requested 
7560: 66 72 6f 6d 20 74 68 65 0a 46 54 53 35 20 74 61  from the.FTS5 ta
7570: 62 6c 65 20 62 79 20 74 68 65 20 75 73 65 72 20  ble by the user 
7580: 6f 72 20 62 79 20 61 6e 20 61 75 78 69 6c 69 61  or by an auxilia
7590: 72 79 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ry function impl
75a0: 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 79  ementation, they
75b0: 20 61 72 65 0a 72 65 61 64 20 66 72 6f 6d 20 74   are.read from t
75c0: 68 69 73 20 70 72 69 76 61 74 65 20 74 61 62 6c  his private tabl
75d0: 65 2e 20 54 68 65 20 22 63 6f 6e 74 65 6e 74 22  e. The "content"
75e0: 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
75f0: 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 6e  sed to create an
7600: 0a 46 54 53 35 20 74 61 62 6c 65 20 74 68 61 74  .FTS5 table that
7610: 20 73 74 6f 72 65 73 20 6f 6e 6c 79 20 46 54 53   stores only FTS
7620: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
7630: 20 65 6e 74 72 69 65 73 2e 20 42 65 63 61 75 73   entries. Becaus
7640: 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 76 61 6c  e the column.val
7650: 75 65 73 20 74 68 65 6d 73 65 6c 76 65 73 20 61  ues themselves a
7660: 72 65 20 75 73 75 61 6c 6c 79 20 6d 75 63 68 20  re usually much 
7670: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
7680: 61 73 73 6f 63 69 61 74 65 64 20 66 75 6c 6c 2d  associated full-
7690: 74 65 78 74 20 69 6e 64 65 78 0a 65 6e 74 72 69  text index.entri
76a0: 65 73 2c 20 74 68 69 73 20 63 61 6e 20 73 61 76  es, this can sav
76b0: 65 20 73 69 67 6e 69 66 69 63 61 6e 74 20 64 61  e significant da
76c0: 74 61 62 61 73 65 20 73 70 61 63 65 2e 0a 0a 3c  tabase space...<
76d0: 70 3e 0a 54 68 65 72 65 20 61 72 65 20 74 77 6f  p>.There are two
76e0: 20 77 61 79 73 20 74 6f 20 75 73 65 20 74 68 65   ways to use the
76f0: 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70 74 69 6f   "content" optio
7700: 6e 3a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 42  n:.<ul>.  <li> B
7710: 79 20 73 65 74 74 69 6e 67 20 69 74 20 74 6f 20  y setting it to 
7720: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
7730: 74 6f 20 63 72 65 61 74 65 20 61 20 63 6f 6e 74  to create a cont
7740: 65 6e 74 6c 65 73 73 20 46 54 53 35 20 74 61 62  entless FTS5 tab
7750: 6c 65 2e 20 49 6e 0a 20 20 20 20 20 20 20 74 68  le. In.       th
7760: 69 73 20 63 61 73 65 20 46 54 53 35 20 61 73 73  is case FTS5 ass
7770: 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 6f 72  umes that the or
7780: 69 67 69 6e 61 6c 20 63 6f 6c 75 6d 6e 20 76 61  iginal column va
7790: 6c 75 65 73 20 61 72 65 20 75 6e 61 76 61 69 6c  lues are unavail
77a0: 61 62 6c 65 0a 20 20 20 20 20 20 20 74 6f 20 69  able.       to i
77b0: 74 20 77 68 65 6e 20 70 72 6f 63 65 73 73 69 6e  t when processin
77c0: 67 20 71 75 65 72 69 65 73 2e 20 46 75 6c 6c 2d  g queries. Full-
77d0: 74 65 78 74 20 71 75 65 72 69 65 73 20 61 6e 64  text queries and
77e0: 20 73 6f 6d 65 20 61 75 78 69 6c 69 61 72 79 0a   some auxiliary.
77f0: 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 73         functions
7800: 20 63 61 6e 20 73 74 69 6c 6c 20 62 65 20 75 73   can still be us
7810: 65 64 2c 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  ed, but no colum
7820: 6e 20 76 61 6c 75 65 73 20 61 70 61 72 74 20 66  n values apart f
7830: 72 6f 6d 20 74 68 65 20 72 6f 77 69 64 0a 20 20  rom the rowid.  
7840: 20 20 20 20 20 6d 61 79 20 62 65 20 72 65 61 64       may be read
7850: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
7860: 0a 0a 20 20 3c 6c 69 3e 20 42 79 20 73 65 74 74  ..  <li> By sett
7870: 69 6e 67 20 69 74 20 74 6f 20 74 68 65 20 6e 61  ing it to the na
7880: 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
7890: 20 6f 62 6a 65 63 74 20 28 74 61 62 6c 65 2c 20   object (table, 
78a0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72  virtual table or
78b0: 0a 20 20 20 20 20 20 20 76 69 65 77 29 20 74 68  .       view) th
78c0: 61 74 20 6d 61 79 20 62 65 20 71 75 65 72 69 65  at may be querie
78d0: 64 20 62 79 20 46 54 53 35 20 61 74 20 61 6e 79  d by FTS5 at any
78e0: 20 74 69 6d 65 20 74 6f 20 72 65 74 72 69 65 76   time to retriev
78f0: 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 20 20 20  e the column.   
7900: 20 20 20 20 76 61 6c 75 65 73 2e 20 54 68 69 73      values. This
7910: 20 69 73 20 6b 6e 6f 77 6e 20 61 73 20 61 6e 20   is known as an 
7920: 22 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e  "external conten
7930: 74 22 20 74 61 62 6c 65 2e 20 49 6e 20 74 68 69  t" table. In thi
7940: 73 20 63 61 73 65 20 61 6c 6c 0a 20 20 20 20 20  s case all.     
7950: 20 20 46 54 53 35 20 66 75 6e 63 74 69 6f 6e 61    FTS5 functiona
7960: 6c 69 74 79 20 6d 61 79 20 62 65 20 75 73 65 64  lity may be used
7970: 2c 20 62 75 74 20 69 74 20 69 73 20 74 68 65 20  , but it is the 
7980: 72 65 73 70 6f 6e 73 69 62 69 6c 69 74 79 20 6f  responsibility o
7990: 66 20 74 68 65 20 75 73 65 72 0a 20 20 20 20 20  f the user.     
79a0: 20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74    to ensure that
79b0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
79c0: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
79d0: 6e 64 65 78 20 61 72 65 20 63 6f 6e 73 69 73 74  ndex are consist
79e0: 65 6e 74 20 77 69 74 68 0a 20 20 20 20 20 20 20  ent with.       
79f0: 74 68 65 20 6e 61 6d 65 64 20 64 61 74 61 62 61  the named databa
7a00: 73 65 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68  se object. If th
7a10: 65 79 20 61 72 65 20 6e 6f 74 2c 20 71 75 65 72  ey are not, quer
7a20: 79 20 72 65 73 75 6c 74 73 20 6d 61 79 20 62 65  y results may be
7a30: 0a 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63  .       unpredic
7a40: 74 61 62 6c 65 2e 20 20 0a 3c 2f 75 6c 3e 0a 0a  table.  .</ul>..
7a50: 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 63  <h3 tags="FTS5 c
7a60: 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
7a70: 73 22 3e 43 6f 6e 74 65 6e 74 6c 65 73 73 20 54  s">Contentless T
7a80: 61 62 6c 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20  ables</h3>..<p> 
7a90: 41 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54  A contentless FT
7aa0: 53 35 20 74 61 62 6c 65 20 69 73 20 63 72 65 61  S5 table is crea
7ab0: 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 74  ted by setting t
7ac0: 68 65 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70 74  he "content" opt
7ad0: 69 6f 6e 20 74 6f 0a 61 6e 20 65 6d 70 74 79 20  ion to.an empty 
7ae0: 73 74 72 69 6e 67 2e 20 46 6f 72 20 65 78 61 6d  string. For exam
7af0: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
7b00: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
7b10: 41 4c 20 54 41 42 4c 45 20 66 31 20 55 53 49 4e  AL TABLE f1 USIN
7b20: 47 20 66 74 73 35 28 61 2c 20 62 2c 20 63 2c 20  G fts5(a, b, c, 
7b30: 63 6f 6e 74 65 6e 74 3d 27 27 29 3b 0a 3c 2f 63  content='');.</c
7b40: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 43  odeblock>..<p> C
7b50: 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54 53 35 20  ontentless FTS5 
7b60: 74 61 62 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75  tables do not su
7b70: 70 70 6f 72 74 20 55 50 44 41 54 45 20 6f 72 20  pport UPDATE or 
7b80: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
7b90: 73 2c 20 6f 72 0a 49 4e 53 45 52 54 20 73 74 61  s, or.INSERT sta
7ba0: 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 6f 20  tements that do 
7bb0: 6e 6f 74 20 73 75 70 70 6c 79 20 61 20 6e 6f 6e  not supply a non
7bc0: 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 66 6f 72 20  -NULL value for 
7bd0: 74 68 65 20 72 6f 77 69 64 20 66 69 65 6c 64 2e  the rowid field.
7be0: 0a 43 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62  .Contentless tab
7bf0: 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  les do not suppo
7c00: 72 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 66 6c  rt REPLACE confl
7c10: 69 63 74 20 68 61 6e 64 6c 69 6e 67 2e 20 52 45  ict handling. RE
7c20: 50 4c 41 43 45 20 0a 61 6e 64 20 49 4e 53 45 52  PLACE .and INSER
7c30: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 73 74 61  T OR REPLACE sta
7c40: 74 65 6d 65 6e 74 73 20 61 72 65 20 74 72 65 61  tements are trea
7c50: 74 65 64 20 61 73 20 72 65 67 75 6c 61 72 20 49  ted as regular I
7c60: 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73  NSERT statements
7c70: 2e 0a 52 6f 77 73 20 6d 61 79 20 62 65 20 64 65  ..Rows may be de
7c80: 6c 65 74 65 64 20 66 72 6f 6d 20 61 20 63 6f 6e  leted from a con
7c90: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 20 75  tentless table u
7ca0: 73 69 6e 67 20 61 6e 20 5b 46 54 53 35 20 64 65  sing an [FTS5 de
7cb0: 6c 65 74 65 20 63 6f 6d 6d 61 6e 64 5d 2e 0a 0a  lete command]...
7cc0: 3c 70 3e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  <p> Attempting t
7cd0: 6f 20 72 65 61 64 20 61 6e 79 20 63 6f 6c 75 6d  o read any colum
7ce0: 6e 20 76 61 6c 75 65 20 65 78 63 65 70 74 20 74  n value except t
7cf0: 68 65 20 72 6f 77 69 64 20 66 72 6f 6d 20 61 20  he rowid from a 
7d00: 63 6f 6e 74 65 6e 74 6c 65 73 73 0a 46 54 53 35  contentless.FTS5
7d10: 20 74 61 62 6c 65 20 72 65 74 75 72 6e 73 20 61   table returns a
7d20: 6e 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65  n SQL NULL value
7d30: 2e 0a 0a 3c 68 33 20 74 61 67 73 3d 22 46 54 53  ...<h3 tags="FTS
7d40: 35 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  5 external conte
7d50: 6e 74 20 74 61 62 6c 65 73 22 3e 45 78 74 65 72  nt tables">Exter
7d60: 6e 61 6c 20 43 6f 6e 74 65 6e 74 20 54 61 62 6c  nal Content Tabl
7d70: 65 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 41 6e 20  es</h3>..<p> An 
7d80: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
7d90: 20 46 54 53 35 20 74 61 62 6c 65 20 69 73 20 63   FTS5 table is c
7da0: 72 65 61 74 65 64 20 62 79 20 73 65 74 74 69 6e  reated by settin
7db0: 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 0a 6f  g the content .o
7dc0: 70 74 69 6f 6e 20 74 6f 20 74 68 65 20 6e 61 6d  ption to the nam
7dd0: 65 20 6f 66 20 61 20 74 61 62 6c 65 2c 20 76 69  e of a table, vi
7de0: 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72 20 76  rtual table or v
7df0: 69 65 77 20 28 68 65 72 65 61 66 74 65 72 20 74  iew (hereafter t
7e00: 68 65 20 22 63 6f 6e 74 65 6e 74 0a 74 61 62 6c  he "content.tabl
7e10: 65 22 29 20 77 69 74 68 69 6e 20 74 68 65 20 73  e") within the s
7e20: 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 57 68  ame database. Wh
7e30: 65 6e 65 76 65 72 20 63 6f 6c 75 6d 6e 20 76 61  enever column va
7e40: 6c 75 65 73 20 61 72 65 20 72 65 71 75 69 72 65  lues are require
7e50: 64 20 62 79 0a 46 54 53 35 2c 20 69 74 20 71 75  d by.FTS5, it qu
7e60: 65 72 69 65 73 20 74 68 65 20 63 6f 6e 74 65 6e  eries the conten
7e70: 74 20 74 61 62 6c 65 20 61 73 20 66 6f 6c 6c 6f  t table as follo
7e80: 77 73 2c 20 77 69 74 68 20 74 68 65 20 72 6f 77  ws, with the row
7e90: 69 64 20 6f 66 20 74 68 65 20 72 6f 77 0a 66 6f  id of the row.fo
7ea0: 72 20 77 68 69 63 68 20 76 61 6c 75 65 73 20 61  r which values a
7eb0: 72 65 20 72 65 71 75 69 72 65 64 20 62 6f 75 6e  re required boun
7ec0: 64 20 74 6f 20 74 68 65 20 53 51 4c 20 76 61 72  d to the SQL var
7ed0: 69 61 62 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  iable:..<codeblo
7ee0: 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20 26 6c 74  ck>.  SELECT &lt
7ef0: 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67  ;content_rowid&g
7f00: 74 3b 2c 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b  t;, &lt;cols&gt;
7f10: 20 46 52 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e   FROM &lt;conten
7f20: 74 26 67 74 3b 20 57 48 45 52 45 20 26 6c 74 3b  t&gt; WHERE &lt;
7f30: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74  content_rowid&gt
7f40: 3b 20 3d 20 3f 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ; = ?;.</codeblo
7f50: 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20 74 68 65 20  ck>..<p> In the 
7f60: 61 62 6f 76 65 2c 20 26 6c 74 3b 63 6f 6e 74 65  above, &lt;conte
7f70: 6e 74 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  nt&gt; is replac
7f80: 65 64 20 62 79 20 74 68 65 20 6e 61 6d 65 20 6f  ed by the name o
7f90: 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61  f the content ta
7fa0: 62 6c 65 2e 0a 42 79 20 64 65 66 61 75 6c 74 2c  ble..By default,
7fb0: 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77   &lt;content_row
7fc0: 69 64 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  id&gt; is replac
7fd0: 65 64 20 62 79 20 74 68 65 20 6c 69 74 65 72 61  ed by the litera
7fe0: 6c 20 74 65 78 74 20 22 72 6f 77 69 64 22 2e 20  l text "rowid". 
7ff0: 4f 72 2c 0a 69 66 20 74 68 65 20 22 63 6f 6e 74  Or,.if the "cont
8000: 65 6e 74 5f 72 6f 77 69 64 22 20 6f 70 74 69 6f  ent_rowid" optio
8010: 6e 20 69 73 20 73 65 74 20 77 69 74 68 69 6e 20  n is set within 
8020: 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55  the CREATE VIRTU
8030: 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  AL TABLE stateme
8040: 6e 74 2c 0a 62 79 20 74 68 65 20 76 61 6c 75 65  nt,.by the value
8050: 20 6f 66 20 74 68 61 74 20 6f 70 74 69 6f 6e 2e   of that option.
8060: 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b 20 69 73   &lt;cols&gt; is
8070: 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 63   replaced by a c
8080: 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64 20 6c  omma-separated l
8090: 69 73 74 0a 6f 66 20 74 68 65 20 46 54 53 35 20  ist.of the FTS5 
80a0: 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  table column nam
80b0: 65 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  es. For example:
80c0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
80d0: 3c 69 3e 2d 2d 20 49 66 20 74 68 65 20 64 61 74  <i>-- If the dat
80e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 69 73 3a  abase schema is:
80f0: 20 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 54   </i>.  CREATE T
8100: 41 42 4c 45 20 74 62 6c 20 28 61 2c 20 62 2c 20  ABLE tbl (a, b, 
8110: 63 2c 20 64 20 49 4e 54 45 47 45 52 20 50 52 49  c, d INTEGER PRI
8120: 4d 41 52 59 20 4b 45 59 29 3b 0a 20 20 43 52 45  MARY KEY);.  CRE
8130: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
8140: 45 20 66 74 73 20 55 53 49 4e 47 20 66 74 73 35  E fts USING fts5
8150: 28 61 2c 20 63 2c 20 63 6f 6e 74 65 6e 74 3d 74  (a, c, content=t
8160: 62 6c 2c 20 63 6f 6e 74 65 6e 74 5f 72 6f 77 69  bl, content_rowi
8170: 64 3d 64 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 46  d=d);..  <i>-- F
8180: 74 73 35 20 6d 61 79 20 69 73 73 75 65 20 71 75  ts5 may issue qu
8190: 65 72 69 65 73 20 73 75 63 68 20 61 73 3a 3c 2f  eries such as:</
81a0: 69 3e 0a 20 20 53 45 4c 45 43 54 20 64 2c 20 61  i>.  SELECT d, a
81b0: 2c 20 63 20 46 52 4f 4d 20 74 62 6c 20 57 48 45  , c FROM tbl WHE
81c0: 52 45 20 64 20 3d 20 3f 3b 0a 3c 2f 63 6f 64 65  RE d = ?;.</code
81d0: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20  block>..<p> The 
81e0: 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 20 6d 61  content table ma
81f0: 79 20 61 6c 73 6f 20 62 65 20 71 75 65 72 69 65  y also be querie
8200: 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c  d as follows:..<
8210: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c  codeblock>.  SEL
8220: 45 43 54 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f  ECT &lt;content_
8230: 72 6f 77 69 64 26 67 74 3b 2c 20 26 6c 74 3b 63  rowid&gt;, &lt;c
8240: 6f 6c 73 26 67 74 3b 20 46 52 4f 4d 20 26 6c 74  ols&gt; FROM &lt
8250: 3b 63 6f 6e 74 65 6e 74 26 67 74 3b 20 4f 52 44  ;content&gt; ORD
8260: 45 52 20 42 59 20 26 6c 74 3b 63 6f 6e 74 65 6e  ER BY &lt;conten
8270: 74 5f 72 6f 77 69 64 26 67 74 3b 20 41 53 43 3b  t_rowid&gt; ASC;
8280: 0a 20 20 53 45 4c 45 43 54 20 26 6c 74 3b 63 6f  .  SELECT &lt;co
8290: 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74 3b 2c  ntent_rowid&gt;,
82a0: 20 26 6c 74 3b 63 6f 6c 73 26 67 74 3b 20 46 52   &lt;cols&gt; FR
82b0: 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 26 67  OM &lt;content&g
82c0: 74 3b 20 4f 52 44 45 52 20 42 59 20 26 6c 74 3b  t; ORDER BY &lt;
82d0: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74  content_rowid&gt
82e0: 3b 20 44 45 53 43 3b 0a 3c 2f 63 6f 64 65 62 6c  ; DESC;.</codebl
82f0: 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 74 20 69 73 20  ock>..<p> It is 
8300: 73 74 69 6c 6c 20 74 68 65 20 72 65 73 70 6f 6e  still the respon
8310: 73 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20  sibility of the 
8320: 75 73 65 72 20 74 6f 20 65 6e 73 75 72 65 20 74  user to ensure t
8330: 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  hat the contents
8340: 20 6f 66 0a 61 6e 20 65 78 74 65 72 6e 61 6c 20   of.an external 
8350: 63 6f 6e 74 65 6e 74 20 46 54 53 35 20 74 61 62  content FTS5 tab
8360: 6c 65 20 61 72 65 20 6b 65 70 74 20 75 70 20 74  le are kept up t
8370: 6f 20 64 61 74 65 20 77 69 74 68 20 74 68 65 20  o date with the 
8380: 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e 20 0a  content table. .
8390: 4f 6e 65 20 77 61 79 20 74 6f 20 64 6f 20 74 68  One way to do th
83a0: 69 73 20 69 73 20 77 69 74 68 20 74 72 69 67 67  is is with trigg
83b0: 65 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ers. For example
83c0: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
83d0: 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 20   <i>-- Create a 
83e0: 74 61 62 6c 65 2e 20 41 6e 64 20 61 6e 20 65 78  table. And an ex
83f0: 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 66  ternal content f
8400: 74 73 35 20 74 61 62 6c 65 20 74 6f 20 69 6e 64  ts5 table to ind
8410: 65 78 20 69 74 2e 3c 2f 69 3e 0a 20 20 43 52 45  ex it.</i>.  CRE
8420: 41 54 45 20 54 41 42 4c 45 20 74 62 6c 28 61 20  ATE TABLE tbl(a 
8430: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
8440: 4b 45 59 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52  KEY, b, c);.  CR
8450: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
8460: 4c 45 20 66 74 73 5f 69 64 78 20 55 53 49 4e 47  LE fts_idx USING
8470: 20 66 74 73 35 28 62 2c 20 63 2c 20 63 6f 6e 74   fts5(b, c, cont
8480: 65 6e 74 3d 27 74 62 6c 27 2c 20 63 6f 6e 74 65  ent='tbl', conte
8490: 6e 74 5f 72 6f 77 69 64 3d 27 61 27 29 3b 0a 0a  nt_rowid='a');..
84a0: 20 20 3c 69 3e 2d 2d 20 54 72 69 67 67 65 72 73    <i>-- Triggers
84b0: 20 74 6f 20 6b 65 65 70 20 74 68 65 20 46 54 53   to keep the FTS
84c0: 20 69 6e 64 65 78 20 75 70 20 74 6f 20 64 61 74   index up to dat
84d0: 65 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  e.</i>.  CREATE 
84e0: 54 52 49 47 47 45 52 20 74 62 6c 5f 61 69 20 41  TRIGGER tbl_ai A
84f0: 46 54 45 52 20 49 4e 53 45 52 54 20 4f 4e 20 74  FTER INSERT ON t
8500: 62 6c 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53  bl BEGIN.    INS
8510: 45 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78  ERT INTO fts_idx
8520: 28 72 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41  (rowid, b, c) VA
8530: 4c 55 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77  LUES (new.a, new
8540: 2e 62 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e  .b, new.c);.  EN
8550: 44 3b 0a 20 20 43 52 45 41 54 45 20 54 52 49 47  D;.  CREATE TRIG
8560: 47 45 52 20 74 62 6c 5f 61 64 20 41 46 54 45 52  GER tbl_ad AFTER
8570: 20 44 45 4c 45 54 45 20 4f 4e 20 74 62 6c 20 42   DELETE ON tbl B
8580: 45 47 49 4e 0a 20 20 20 20 49 4e 53 45 52 54 20  EGIN.    INSERT 
8590: 49 4e 54 4f 20 66 74 73 5f 69 64 78 28 66 74 73  INTO fts_idx(fts
85a0: 5f 69 64 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20  _idx, rowid, b, 
85b0: 63 29 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74  c) VALUES('delet
85c0: 65 27 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62  e', old.a, old.b
85d0: 2c 20 6f 6c 64 2e 63 29 3b 0a 20 20 45 4e 44 3b  , old.c);.  END;
85e0: 0a 20 20 43 52 45 41 54 45 20 54 52 49 47 47 45  .  CREATE TRIGGE
85f0: 52 20 74 62 6c 5f 61 75 20 41 46 54 45 52 20 55  R tbl_au AFTER U
8600: 50 44 41 54 45 20 4f 4e 20 74 62 6c 20 42 45 47  PDATE ON tbl BEG
8610: 49 4e 0a 20 20 20 20 49 4e 53 45 52 54 20 49 4e  IN.    INSERT IN
8620: 54 4f 20 66 74 73 5f 69 64 78 28 66 74 73 5f 69  TO fts_idx(fts_i
8630: 64 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20 63 29  dx, rowid, b, c)
8640: 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74 65 27   VALUES('delete'
8650: 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62 2c 20  , old.a, old.b, 
8660: 6f 6c 64 2e 63 29 3b 0a 20 20 20 20 49 4e 53 45  old.c);.    INSE
8670: 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78 28  RT INTO fts_idx(
8680: 72 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41 4c  rowid, b, c) VAL
8690: 55 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77 2e  UES (new.a, new.
86a0: 62 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e 44  b, new.c);.  END
86b0: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
86c0: 3c 70 3e 20 4c 69 6b 65 20 63 6f 6e 74 65 6e 74  <p> Like content
86d0: 6c 65 73 73 20 74 61 62 6c 65 73 2c 20 65 78 74  less tables, ext
86e0: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61  ernal content ta
86f0: 62 6c 65 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  bles do not supp
8700: 6f 72 74 20 52 45 50 4c 41 43 45 0a 63 6f 6e 66  ort REPLACE.conf
8710: 6c 69 63 74 20 68 61 6e 64 6c 69 6e 67 2e 20 41  lict handling. A
8720: 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 68  ny operations th
8730: 61 74 20 73 70 65 63 69 66 79 20 52 45 50 4c 41  at specify REPLA
8740: 43 45 20 63 6f 6e 66 6c 69 63 74 20 68 61 6e 64  CE conflict hand
8750: 6c 69 6e 67 20 61 72 65 0a 68 61 6e 64 6c 65 64  ling are.handled
8760: 20 75 73 69 6e 67 20 41 42 4f 52 54 2e 0a 0a 3c   using ABORT...<
8770: 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 63 6f  h2 tags="FTS5 co
8780: 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 22  lumnsize option"
8790: 3e 54 68 65 20 43 6f 6c 75 6d 6e 73 69 7a 65 20  >The Columnsize 
87a0: 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e  Option</h2>..<p>
87b0: 4e 6f 72 6d 61 6c 6c 79 2c 20 46 54 53 35 20 6d  Normally, FTS5 m
87c0: 61 69 6e 74 61 69 6e 73 20 61 20 73 70 65 63 69  aintains a speci
87d0: 61 6c 20 62 61 63 6b 69 6e 67 20 74 61 62 6c 65  al backing table
87e0: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
87f0: 62 61 73 65 20 74 68 61 74 0a 73 74 6f 72 65 73  base that.stores
8800: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
8810: 68 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69  h column value i
8820: 6e 20 74 6f 6b 65 6e 73 20 69 6e 73 65 72 74 65  n tokens inserte
8830: 64 20 69 6e 74 6f 20 74 68 65 20 6d 61 69 6e 20  d into the main 
8840: 46 54 53 35 0a 74 61 62 6c 65 20 69 6e 20 61 20  FTS5.table in a 
8850: 73 65 70 61 72 61 74 65 20 74 61 62 6c 65 2e 20  separate table. 
8860: 54 68 69 73 20 62 61 63 6b 69 6e 67 20 74 61 62  This backing tab
8870: 6c 65 20 69 73 20 75 73 65 64 20 62 79 20 74 68  le is used by th
8880: 65 0a 3c 61 20 68 72 65 66 3d 23 78 43 6f 6c 75  e.<a href=#xColu
8890: 6d 6e 53 69 7a 65 3e 78 43 6f 6c 75 6d 6e 53 69  mnSize>xColumnSi
88a0: 7a 65 3c 61 3e 20 41 50 49 20 66 75 6e 63 74 69  ze<a> API functi
88b0: 6f 6e 2c 20 77 68 69 63 68 20 69 73 20 69 6e 20  on, which is in 
88c0: 74 75 72 6e 20 75 73 65 64 20 62 79 0a 74 68 65  turn used by.the
88d0: 20 62 75 69 6c 74 2d 69 6e 20 5b 46 54 53 35 20   built-in [FTS5 
88e0: 62 6d 32 35 20 7c 20 62 6d 32 35 20 72 61 6e 6b  bm25 | bm25 rank
88f0: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 5d 20 28 61  ing function] (a
8900: 6e 64 20 69 73 20 6c 69 6b 65 6c 79 20 74 6f 20  nd is likely to 
8910: 62 65 20 75 73 65 66 75 6c 20 0a 74 6f 20 6f 74  be useful .to ot
8920: 68 65 72 20 72 61 6e 6b 69 6e 67 20 66 75 6e 63  her ranking func
8930: 74 69 6f 6e 73 20 61 73 20 77 65 6c 6c 29 2e 0a  tions as well)..
8940: 0a 3c 70 3e 49 6e 20 6f 72 64 65 72 20 74 6f 20  .<p>In order to 
8950: 73 61 76 65 20 73 70 61 63 65 2c 20 74 68 69 73  save space, this
8960: 20 62 61 63 6b 69 6e 67 20 74 61 62 6c 65 20 6d   backing table m
8970: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
8980: 20 73 65 74 74 69 6e 67 20 74 68 65 0a 63 6f 6c   setting the.col
8990: 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 20 74  umnsize option t
89a0: 6f 20 7a 65 72 6f 2e 20 46 6f 72 20 65 78 61 6d  o zero. For exam
89b0: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
89c0: 3e 0a 20 20 3c 69 3e 2d 2d 20 41 20 74 61 62 6c  >.  <i>-- A tabl
89d0: 65 20 77 69 74 68 6f 75 74 20 74 68 65 20 78 43  e without the xC
89e0: 6f 6c 75 6d 6e 53 69 7a 65 28 29 20 76 61 6c 75  olumnSize() valu
89f0: 65 73 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 73  es stored on dis
8a00: 6b 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20  k:</i>.  CREATE 
8a10: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
8a20: 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62   USING fts5(a, b
8a30: 2c 20 63 2c 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  , c, columnsize=
8a40: 30 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 72  0);..  <i>-- Thr
8a50: 65 65 20 65 71 75 69 76 61 6c 65 6e 74 20 77 61  ee equivalent wa
8a60: 79 73 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61  ys of creating a
8a70: 20 74 61 62 6c 65 20 74 68 61 74 20 64 6f 65 73   table that does
8a80: 20 73 74 6f 72 65 20 74 68 65 3c 2f 69 3e 0a 20   store the</i>. 
8a90: 20 3c 69 3e 2d 2d 20 78 43 6f 6c 75 6d 6e 53 69   <i>-- xColumnSi
8aa0: 7a 65 28 29 20 76 61 6c 75 65 73 20 6f 6e 20 64  ze() values on d
8ab0: 69 73 6b 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  isk:</i>.  CREAT
8ac0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
8ad0: 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  ft USING fts5(a,
8ae0: 20 62 2c 20 63 29 3b 0a 20 20 43 52 45 41 54 45   b, c);.  CREATE
8af0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
8b00: 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20  t USING fts5(a, 
8b10: 62 2c 20 63 2c 20 63 6f 6c 75 6d 6e 73 69 7a 65  b, c, columnsize
8b20: 3d 31 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49  =1);.  CREATE VI
8b30: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 20 55  RTUAL TABLE ft U
8b40: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
8b50: 63 6f 6c 75 6d 6e 73 69 7a 65 3d 27 31 27 2c 20  columnsize='1', 
8b60: 63 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  c);.</codeblock>
8b70: 0a 0a 3c 70 3e 20 49 74 20 69 73 20 61 6e 20 65  ..<p> It is an e
8b80: 72 72 6f 72 20 74 6f 20 73 65 74 20 74 68 65 20  rror to set the 
8b90: 63 6f 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f  columnsize optio
8ba0: 6e 20 74 6f 20 61 6e 79 20 76 61 6c 75 65 20 6f  n to any value o
8bb0: 74 68 65 72 20 74 68 61 6e 0a 30 20 6f 72 20 31  ther than.0 or 1
8bc0: 2e 0a 0a 3c 70 3e 20 49 66 20 61 6e 20 46 54 53  ...<p> If an FTS
8bd0: 35 20 74 61 62 6c 65 20 69 73 20 63 6f 6e 66 69  5 table is confi
8be0: 67 75 72 65 64 20 77 69 74 68 20 63 6f 6c 75 6d  gured with colum
8bf0: 6e 73 69 7a 65 3d 30 20 62 75 74 20 69 73 20 6e  nsize=0 but is n
8c00: 6f 74 20 61 0a 5b 46 54 53 35 20 63 6f 6e 74 65  ot a.[FTS5 conte
8c10: 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c 20  ntless tables | 
8c20: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
8c30: 65 5d 2c 20 74 68 65 20 78 43 6f 6c 75 6d 6e 53  e], the xColumnS
8c40: 69 7a 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ize API function
8c50: 0a 73 74 69 6c 6c 20 77 6f 72 6b 73 2c 20 62 75  .still works, bu
8c60: 74 20 72 75 6e 73 20 6d 75 63 68 20 6d 6f 72 65  t runs much more
8c70: 20 73 6c 6f 77 6c 79 2e 20 49 6e 20 74 68 69 73   slowly. In this
8c80: 20 63 61 73 65 2c 20 69 6e 73 74 65 61 64 20 6f   case, instead o
8c90: 66 20 72 65 61 64 69 6e 67 0a 74 68 65 20 76 61  f reading.the va
8ca0: 6c 75 65 20 74 6f 20 72 65 74 75 72 6e 20 64 69  lue to return di
8cb0: 72 65 63 74 6c 79 20 66 72 6f 6d 20 74 68 65 20  rectly from the 
8cc0: 64 61 74 61 62 61 73 65 2c 20 69 74 20 72 65 61  database, it rea
8cd0: 64 73 20 74 68 65 20 74 65 78 74 20 76 61 6c 75  ds the text valu
8ce0: 65 0a 69 74 73 65 6c 66 20 61 6e 64 20 63 6f 75  e.itself and cou
8cf0: 6e 74 20 74 68 65 20 74 6f 6b 65 6e 73 20 77 69  nt the tokens wi
8d00: 74 68 69 6e 20 69 74 20 6f 6e 20 64 65 6d 61 6e  thin it on deman
8d10: 64 2e 0a 0a 3c 70 3e 4f 72 2c 20 69 66 20 74 68  d...<p>Or, if th
8d20: 65 20 74 61 62 6c 65 20 69 73 20 61 6c 73 6f 20  e table is also 
8d30: 61 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c  a [FTS5 contentl
8d40: 65 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e  ess tables | con
8d50: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 5d 2c  tentless table],
8d60: 0a 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  .then the follow
8d70: 69 6e 67 20 61 70 70 6c 79 3a 0a 0a 3c 75 6c 3e  ing apply:..<ul>
8d80: 0a 20 20 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 78  .  <li> <p>The x
8d90: 43 6f 6c 75 6d 6e 53 69 7a 65 20 41 50 49 20 61  ColumnSize API a
8da0: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 2d 31  lways returns -1
8db0: 2e 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61  . There is no wa
8dc0: 79 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 0a  y to determine .
8dd0: 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
8de0: 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 61  r of tokens in a
8df0: 20 76 61 6c 75 65 20 73 74 6f 72 65 64 20 77 69   value stored wi
8e00: 74 68 69 6e 20 61 20 63 6f 6e 74 65 6e 74 6c 65  thin a contentle
8e10: 73 73 20 46 54 53 35 20 74 61 62 6c 65 0a 20 20  ss FTS5 table.  
8e20: 20 20 20 20 20 63 6f 6e 66 69 67 75 72 65 64 20       configured 
8e30: 77 69 74 68 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  with columnsize=
8e40: 30 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 45 61  0...  <li> <p>Ea
8e50: 63 68 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ch inserted row 
8e60: 6d 75 73 74 20 62 65 20 61 63 63 6f 6d 70 61 6e  must be accompan
8e70: 69 65 64 20 62 79 20 61 6e 20 65 78 70 6c 69 63  ied by an explic
8e80: 69 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 72  itly specified r
8e90: 6f 77 69 64 0a 20 20 20 20 20 20 20 76 61 6c 75  owid.       valu
8ea0: 65 2e 20 49 66 20 61 20 63 6f 6e 74 65 6e 74 6c  e. If a contentl
8eb0: 65 73 73 20 74 61 62 6c 65 20 69 73 20 63 6f 6e  ess table is con
8ec0: 66 69 67 75 72 65 64 20 77 69 74 68 20 63 6f 6c  figured with col
8ed0: 75 6d 6e 73 69 7a 65 3d 30 2c 0a 20 20 20 20 20  umnsize=0,.     
8ee0: 20 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20    attempting to 
8ef0: 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
8f00: 6c 75 65 20 69 6e 74 6f 20 74 68 65 20 72 6f 77  lue into the row
8f10: 69 64 20 69 73 20 61 6e 20 53 51 4c 49 54 45 5f  id is an SQLITE_
8f20: 4d 49 53 4d 41 54 43 48 0a 20 20 20 20 20 20 20  MISMATCH.       
8f30: 65 72 72 6f 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c  error...  <li> <
8f40: 70 3e 41 6c 6c 20 71 75 65 72 69 65 73 20 6f 6e  p>All queries on
8f50: 20 74 68 65 20 74 61 62 6c 65 20 6d 75 73 74 20   the table must 
8f60: 62 65 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  be full-text que
8f70: 72 69 65 73 2e 20 49 6e 20 6f 74 68 65 72 20 77  ries. In other w
8f80: 6f 72 64 73 2c 0a 20 20 20 20 20 20 20 74 68 65  ords,.       the
8f90: 79 20 6d 75 73 74 20 75 73 65 20 74 68 65 20 4d  y must use the M
8fa0: 41 54 43 48 20 6f 72 20 3d 20 6f 70 65 72 61 74  ATCH or = operat
8fb0: 6f 72 20 77 69 74 68 20 74 68 65 20 74 61 62 6c  or with the tabl
8fc0: 65 2d 6e 61 6d 65 20 63 6f 6c 75 6d 6e 20 61 73  e-name column as
8fd0: 20 74 68 65 0a 20 20 20 20 20 20 20 6c 65 66 74   the.       left
8fe0: 2d 68 61 6e 64 20 6f 70 65 72 61 6e 64 2c 20 6f  -hand operand, o
8ff0: 72 20 65 6c 73 65 20 75 73 65 20 74 68 65 20 74  r else use the t
9000: 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63  able-valued func
9010: 74 69 6f 6e 20 73 79 6e 74 61 78 2e 20 41 6e 79  tion syntax. Any
9020: 0a 20 20 20 20 20 20 20 71 75 65 72 79 20 74 68  .       query th
9030: 61 74 20 69 73 20 6e 6f 74 20 61 20 66 75 6c 6c  at is not a full
9040: 2d 74 65 78 74 20 71 75 65 72 79 20 72 65 73 75  -text query resu
9050: 6c 74 73 20 69 6e 20 61 6e 20 65 72 72 6f 72 2e  lts in an error.
9060: 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 54 68 65 20  .</ul>..<p> The 
9070: 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
9080: 65 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 78  e in which the x
9090: 43 6f 6c 75 6d 6e 53 69 7a 65 20 76 61 6c 75 65  ColumnSize value
90a0: 73 20 61 72 65 20 73 74 6f 72 65 64 0a 28 75 6e  s are stored.(un
90b0: 6c 65 73 73 20 63 6f 6c 75 6d 6e 73 69 7a 65 3d  less columnsize=
90c0: 30 20 69 73 20 73 70 65 63 69 66 69 65 64 29 20  0 is specified) 
90d0: 69 73 20 22 26 6c 74 3b 6e 61 6d 65 26 67 74 3b  is "&lt;name&gt;
90e0: 5f 64 6f 63 73 69 7a 65 22 2c 20 77 68 65 72 65  _docsize", where
90f0: 20 0a 26 6c 74 3b 6e 61 6d 65 26 67 74 3b 20 69   .&lt;name&gt; i
9100: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
9110: 65 20 46 54 53 35 20 74 61 62 6c 65 20 69 74 73  e FTS5 table its
9120: 65 6c 66 2e 20 54 68 65 20 0a 3c 61 20 68 72 65  elf. The .<a hre
9130: 66 3d 68 74 74 70 73 3a 2f 2f 77 77 77 2e 73 71  f=https://www.sq
9140: 6c 69 74 65 2e 6f 72 67 2f 64 6f 77 6e 6c 6f 61  lite.org/downloa
9150: 64 2e 68 74 6d 6c 3e 73 71 6c 69 74 65 33 5f 61  d.html>sqlite3_a
9160: 6e 61 6c 79 7a 65 72 3c 2f 61 3e 0a 74 6f 6f 6c  nalyzer</a>.tool
9170: 20 6d 61 79 20 62 65 20 75 73 65 64 20 6f 6e 20   may be used on 
9180: 61 6e 20 65 78 69 73 74 69 6e 67 20 64 61 74 61  an existing data
9190: 62 61 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  base in order to
91a0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 20 6d   determine how m
91b0: 75 63 68 0a 73 70 61 63 65 20 6d 69 67 68 74 20  uch.space might 
91c0: 62 65 20 73 61 76 65 64 20 62 79 20 72 65 63 72  be saved by recr
91d0: 65 61 74 69 6e 67 20 61 6e 20 46 54 53 35 20 74  eating an FTS5 t
91e0: 61 62 6c 65 20 75 73 69 6e 67 20 63 6f 6c 75 6d  able using colum
91f0: 6e 73 69 7a 65 3d 30 2e 0a 0a 3c 68 32 20 74 61  nsize=0...<h2 ta
9200: 67 73 3d 22 46 54 53 35 20 64 65 74 61 69 6c 20  gs="FTS5 detail 
9210: 6f 70 74 69 6f 6e 22 3e 54 68 65 20 44 65 74 61  option">The Deta
9220: 69 6c 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a  il Option</h2>..
9230: 3c 70 3e 20 46 6f 72 20 65 61 63 68 20 74 65 72  <p> For each ter
9240: 6d 20 69 6e 20 61 20 64 6f 63 75 6d 65 6e 74 2c  m in a document,
9250: 20 74 68 65 20 46 54 53 20 69 6e 64 65 78 20 6d   the FTS index m
9260: 61 69 6e 74 61 69 6e 65 64 20 62 79 20 46 54 53  aintained by FTS
9270: 35 20 0a 73 74 6f 72 65 73 20 74 68 65 20 72 6f  5 .stores the ro
9280: 77 69 64 20 6f 66 20 74 68 65 20 64 6f 63 75 6d  wid of the docum
9290: 65 6e 74 2c 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ent, the column 
92a0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 65 20 63 6f  number of the co
92b0: 6c 75 6d 6e 20 74 68 61 74 20 63 6f 6e 74 61 69  lumn that contai
92c0: 6e 73 0a 74 68 65 20 74 65 72 6d 20 61 6e 64 20  ns.the term and 
92d0: 74 68 65 20 6f 66 66 73 65 74 20 6f 66 20 74 68  the offset of th
92e0: 65 20 74 65 72 6d 20 77 69 74 68 69 6e 20 74 68  e term within th
92f0: 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 20  e column value. 
9300: 54 68 65 20 22 64 65 74 61 69 6c 22 0a 6f 70 74  The "detail".opt
9310: 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
9320: 74 6f 20 6f 6d 69 74 20 73 6f 6d 65 20 6f 66 20  to omit some of 
9330: 74 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  this information
9340: 2e 20 54 68 69 73 20 72 65 64 75 63 65 73 20 74  . This reduces t
9350: 68 65 20 73 70 61 63 65 0a 74 68 61 74 20 74 68  he space.that th
9360: 65 20 69 6e 64 65 78 20 63 6f 6e 73 75 6d 65 73  e index consumes
9370: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
9380: 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 61  base file, but a
9390: 6c 73 6f 20 72 65 64 75 63 65 73 20 74 68 65 0a  lso reduces the.
93a0: 63 61 70 61 62 69 6c 69 74 79 20 61 6e 64 20 65  capability and e
93b0: 66 66 69 63 69 65 6e 63 79 20 6f 66 20 74 68 65  fficiency of the
93c0: 20 73 79 73 74 65 6d 2e 0a 0a 3c 70 3e 20 54 68   system...<p> Th
93d0: 65 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e 20  e detail option 
93e0: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 22 66  may be set to "f
93f0: 75 6c 6c 22 20 28 74 68 65 20 64 65 66 61 75 6c  ull" (the defaul
9400: 74 20 76 61 6c 75 65 29 2c 20 22 63 6f 6c 75 6d  t value), "colum
9410: 6e 22 20 6f 72 0a 22 6e 6f 6e 65 22 2e 20 46 6f  n" or."none". Fo
9420: 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64  r example:..<cod
9430: 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20  eblock>.  <i>-- 
9440: 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
9450: 6f 20 6c 69 6e 65 73 20 61 72 65 20 65 71 75 69  o lines are equi
9460: 76 61 6c 65 6e 74 20 28 62 65 63 61 75 73 65 20  valent (because 
9470: 74 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  the default valu
9480: 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f 66  e</i>.  <i>-- of
9490: 20 22 64 65 74 61 69 6c 22 20 69 73 20 22 66 75   "detail" is "fu
94a0: 6c 6c 22 2e 20 3c 2f 69 3e 0a 20 20 43 52 45 41  ll". </i>.  CREA
94b0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
94c0: 20 66 74 31 20 55 53 49 4e 47 20 66 74 73 35 28   ft1 USING fts5(
94d0: 61 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52 45 41  a, b, c);.  CREA
94e0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
94f0: 20 66 74 31 20 55 53 49 4e 47 20 66 74 73 35 28   ft1 USING fts5(
9500: 61 2c 20 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d  a, b, c, detail=
9510: 66 75 6c 6c 29 3b 0a 0a 20 20 43 52 45 41 54 45  full);..  CREATE
9520: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
9530: 74 32 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c  t2 USING fts5(a,
9540: 20 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d 63 6f   b, c, detail=co
9550: 6c 75 6d 6e 29 3b 0a 20 20 43 52 45 41 54 45 20  lumn);.  CREATE 
9560: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
9570: 33 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20  3 USING fts5(a, 
9580: 62 2c 20 63 2c 20 64 65 74 61 69 6c 3d 6e 6f 6e  b, c, detail=non
9590: 65 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  e);.</codeblock>
95a0: 0a 0a 3c 70 3e 49 66 20 74 68 65 20 64 65 74 61  ..<p>If the deta
95b0: 69 6c 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  il option is set
95c0: 20 74 6f 20 3c 62 3e 63 6f 6c 75 6d 6e 3c 2f 62   to <b>column</b
95d0: 3e 2c 20 74 68 65 6e 20 66 6f 72 20 65 61 63 68  >, then for each
95e0: 20 74 65 72 6d 20 74 68 65 20 46 54 53 0a 69 6e   term the FTS.in
95f0: 64 65 78 20 72 65 63 6f 72 64 73 20 74 68 65 20  dex records the 
9600: 72 6f 77 69 64 20 61 6e 64 20 63 6f 6c 75 6d 6e  rowid and column
9610: 20 6e 75 6d 62 65 72 20 6f 6e 6c 79 2c 20 6f 6d   number only, om
9620: 69 74 74 69 6e 67 20 74 68 65 20 74 65 72 6d 20  itting the term 
9630: 6f 66 66 73 65 74 0a 69 6e 66 6f 72 6d 61 74 69  offset.informati
9640: 6f 6e 2e 20 54 68 69 73 20 72 65 73 75 6c 74 73  on. This results
9650: 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
9660: 67 20 72 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  g restrictions:.
9670: 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 4e 45 41  .<ul>.  <li> NEA
9680: 52 20 71 75 65 72 69 65 73 20 61 72 65 20 6e 6f  R queries are no
9690: 74 20 61 76 61 69 6c 61 62 6c 65 2e 0a 20 20 3c  t available..  <
96a0: 6c 69 3e 20 50 68 72 61 73 65 20 71 75 65 72 69  li> Phrase queri
96b0: 65 73 20 61 72 65 20 6e 6f 74 20 61 76 61 69 6c  es are not avail
96c0: 61 62 6c 65 2e 0a 20 20 3c 6c 69 3e 20 41 73 73  able..  <li> Ass
96d0: 75 6d 69 6e 67 20 74 68 65 20 74 61 62 6c 65 20  uming the table 
96e0: 69 73 20 6e 6f 74 20 61 6c 73 6f 20 61 20 0a 20  is not also a . 
96f0: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
9700: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
9710: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 5d 2c 20  entless table], 
9720: 74 68 65 20 0a 20 20 3c 61 20 68 72 65 66 3d 23  the .  <a href=#
9730: 78 49 6e 73 74 43 6f 75 6e 74 3e 78 49 6e 73 74  xInstCount>xInst
9740: 43 6f 75 6e 74 3c 2f 61 3e 2c 20 3c 61 20 68 72  Count</a>, <a hr
9750: 65 66 3d 23 78 49 6e 73 74 3e 78 49 6e 73 74 3c  ef=#xInst>xInst<
9760: 2f 61 3e 2c 20 0a 20 20 3c 61 20 68 72 65 66 3d  /a>, .  <a href=
9770: 23 78 50 68 72 61 73 65 46 69 72 73 74 3e 78 50  #xPhraseFirst>xP
9780: 68 72 61 73 65 46 69 72 73 74 3c 2f 61 3e 20 61  hraseFirst</a> a
9790: 6e 64 20 3c 61 20 68 72 65 66 3d 23 78 50 68 72  nd <a href=#xPhr
97a0: 61 73 65 4e 65 78 74 3e 78 50 68 72 61 73 65 4e  aseNext>xPhraseN
97b0: 65 78 74 3c 2f 61 3e 0a 20 20 61 72 65 20 73 6c  ext</a>.  are sl
97c0: 6f 77 65 72 20 74 68 61 6e 20 75 73 75 61 6c 2e  ower than usual.
97d0: 20 54 68 69 73 20 69 73 20 62 65 63 61 75 73 65   This is because
97e0: 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 61 64   instead of read
97f0: 69 6e 67 20 74 68 65 20 72 65 71 75 69 72 65 64  ing the required
9800: 20 64 61 74 61 0a 20 20 64 69 72 65 63 74 6c 79   data.  directly
9810: 20 66 72 6f 6d 20 74 68 65 20 46 54 53 20 69 6e   from the FTS in
9820: 64 65 78 20 74 68 65 79 20 68 61 76 65 20 74 6f  dex they have to
9830: 20 6c 6f 61 64 20 61 6e 64 20 74 6f 6b 65 6e 69   load and tokeni
9840: 7a 65 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20  ze the document 
9850: 74 65 78 74 20 0a 20 20 6f 6e 20 64 65 6d 61 6e  text .  on deman
9860: 64 2e 0a 20 20 3c 6c 69 3e 20 49 66 20 74 68 65  d..  <li> If the
9870: 20 74 61 62 6c 65 20 69 73 20 61 6c 73 6f 20 61   table is also a
9880: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62   contentless tab
9890: 6c 65 2c 20 74 68 65 20 78 49 6e 73 74 43 6f 75  le, the xInstCou
98a0: 6e 74 2c 20 78 49 6e 73 74 2c 20 0a 20 20 78 50  nt, xInst, .  xP
98b0: 68 72 61 73 65 46 69 72 73 74 20 61 6e 64 20 78  hraseFirst and x
98c0: 50 68 72 61 73 65 4e 65 78 74 20 41 50 49 73 20  PhraseNext APIs 
98d0: 62 65 68 61 76 65 20 61 73 20 69 66 20 74 68 65  behave as if the
98e0: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 63 6f 6e   current row con
98f0: 74 61 69 6e 73 20 6e 6f 0a 20 20 70 68 72 61 73  tains no.  phras
9900: 65 20 6d 61 74 63 68 65 73 20 61 74 20 61 6c 6c  e matches at all
9910: 20 28 69 2e 65 2e 20 78 49 6e 73 74 43 6f 75 6e   (i.e. xInstCoun
9920: 74 28 29 20 72 65 74 75 72 6e 73 20 30 29 2e 0a  t() returns 0)..
9930: 3c 2f 75 6c 3e 0a 20 20 0a 3c 70 3e 49 66 20 74  </ul>.  .<p>If t
9940: 68 65 20 64 65 74 61 69 6c 20 6f 70 74 69 6f 6e  he detail option
9950: 20 69 73 20 73 65 74 20 74 6f 20 3c 62 3e 6e 6f   is set to <b>no
9960: 6e 65 3c 2f 62 3e 2c 20 74 68 65 6e 20 66 6f 72  ne</b>, then for
9970: 20 65 61 63 68 20 74 65 72 6d 20 74 68 65 20 46   each term the F
9980: 54 53 0a 69 6e 64 65 78 20 72 65 63 6f 72 64 73  TS.index records
9990: 20 6a 75 73 74 20 74 68 65 20 72 6f 77 69 64 20   just the rowid 
99a0: 69 73 20 73 74 6f 72 65 64 2e 20 42 6f 74 68 20  is stored. Both 
99b0: 63 6f 6c 75 6d 6e 20 61 6e 64 20 6f 66 66 73 65  column and offse
99c0: 74 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 61 72  t information.ar
99d0: 65 20 6f 6d 69 74 74 65 64 2e 20 41 73 20 77 65  e omitted. As we
99e0: 6c 6c 20 61 73 20 74 68 65 20 72 65 73 74 72 69  ll as the restri
99f0: 63 74 69 6f 6e 73 20 69 74 65 6d 69 7a 65 64 20  ctions itemized 
9a00: 61 62 6f 76 65 20 66 6f 72 20 64 65 74 61 69 6c  above for detail
9a10: 3d 63 6f 6c 75 6d 6e 0a 6d 6f 64 65 2c 20 74 68  =column.mode, th
9a20: 69 73 20 69 6d 70 6f 73 65 73 20 74 68 65 20 66  is imposes the f
9a30: 6f 6c 6c 6f 77 69 6e 67 20 65 78 74 72 61 20 6c  ollowing extra l
9a40: 69 6d 69 74 61 74 69 6f 6e 73 3a 0a 0a 3c 75 6c  imitations:..<ul
9a50: 3e 0a 20 20 3c 6c 69 3e 20 43 6f 6c 75 6d 6e 20  >.  <li> Column 
9a60: 66 69 6c 74 65 72 20 71 75 65 72 69 65 73 20 61  filter queries a
9a70: 72 65 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  re not available
9a80: 2e 0a 20 20 3c 6c 69 3e 20 41 73 73 75 6d 69 6e  ..  <li> Assumin
9a90: 67 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 6e  g the table is n
9aa0: 6f 74 20 61 6c 73 6f 20 61 20 63 6f 6e 74 65 6e  ot also a conten
9ab0: 74 6c 65 73 73 20 74 61 62 6c 65 2c 20 74 68 65  tless table, the
9ac0: 20 0a 20 20 3c 61 20 68 72 65 66 3d 23 78 50 68   .  <a href=#xPh
9ad0: 72 61 73 65 46 69 72 73 74 43 6f 6c 75 6d 6e 3e  raseFirstColumn>
9ae0: 78 50 68 72 61 73 65 46 69 72 73 74 43 6f 6c 75  xPhraseFirstColu
9af0: 6d 6e 3c 2f 61 3e 20 61 6e 64 20 0a 20 20 3c 61  mn</a> and .  <a
9b00: 20 68 72 65 66 3d 23 78 50 68 72 61 73 65 4e 65   href=#xPhraseNe
9b10: 78 74 43 6f 6c 75 6d 6e 3e 78 50 68 72 61 73 65  xtColumn>xPhrase
9b20: 4e 65 78 74 43 6f 6c 75 6d 6e 3c 2f 61 3e 20 61  NextColumn</a> a
9b30: 72 65 20 73 6c 6f 77 65 72 20 74 68 61 6e 20 75  re slower than u
9b40: 73 75 61 6c 2e 20 0a 0a 20 20 3c 6c 69 3e 20 49  sual. ..  <li> I
9b50: 66 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61  f the table is a
9b60: 6c 73 6f 20 61 20 63 6f 6e 74 65 6e 74 6c 65 73  lso a contentles
9b70: 73 20 74 61 62 6c 65 2c 20 74 68 65 20 78 50 68  s table, the xPh
9b80: 72 61 73 65 46 69 72 73 74 43 6f 6c 75 6d 6e 20  raseFirstColumn 
9b90: 61 6e 64 0a 20 20 78 50 68 72 61 73 65 4e 65 78  and.  xPhraseNex
9ba0: 74 43 6f 6c 75 6d 6e 20 41 50 49 73 20 62 65 68  tColumn APIs beh
9bb0: 61 76 65 20 61 73 20 69 66 20 74 68 65 20 63 75  ave as if the cu
9bc0: 72 72 65 6e 74 20 72 6f 77 20 63 6f 6e 74 61 69  rrent row contai
9bd0: 6e 73 20 6e 6f 20 70 68 72 61 73 65 0a 20 20 6d  ns no phrase.  m
9be0: 61 74 63 68 65 73 20 61 74 20 61 6c 6c 20 28 69  atches at all (i
9bf0: 2e 65 2e 20 78 50 68 72 61 73 65 46 69 72 73 74  .e. xPhraseFirst
9c00: 43 6f 6c 75 6d 6e 28 29 20 73 65 74 73 20 74 68  Column() sets th
9c10: 65 20 69 74 65 72 61 74 6f 72 20 74 6f 20 45 4f  e iterator to EO
9c20: 46 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 49  F)..</ul>..<p> I
9c30: 6e 20 6f 6e 65 20 74 65 73 74 20 74 68 61 74 20  n one test that 
9c40: 69 6e 64 65 78 65 64 20 61 20 6c 61 72 67 65 20  indexed a large 
9c50: 73 65 74 20 6f 66 20 65 6d 61 69 6c 73 20 28 31  set of emails (1
9c60: 36 33 36 20 4d 69 42 20 6f 6e 20 64 69 73 6b 29  636 MiB on disk)
9c70: 2c 20 74 68 65 20 46 54 53 0a 69 6e 64 65 78 20  , the FTS.index 
9c80: 77 61 73 20 37 34 33 20 4d 69 42 20 6f 6e 20 64  was 743 MiB on d
9c90: 69 73 6b 20 77 69 74 68 20 64 65 74 61 69 6c 3d  isk with detail=
9ca0: 66 75 6c 6c 2c 20 33 34 30 20 4d 69 42 20 77 69  full, 340 MiB wi
9cb0: 74 68 20 64 65 74 61 69 6c 3d 63 6f 6c 75 6d 6e  th detail=column
9cc0: 20 61 6e 64 20 31 33 34 0a 4d 69 42 20 77 69 74   and 134.MiB wit
9cd0: 68 20 64 65 74 61 69 6c 3d 6e 6f 6e 65 2e 0a 0a  h detail=none...
9ce0: 3c 68 31 20 74 61 67 73 3d 22 46 54 53 35 20 61  <h1 tags="FTS5 a
9cf0: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
9d00: 6e 73 22 3e 20 41 75 78 69 6c 69 61 72 79 20 46  ns"> Auxiliary F
9d10: 75 6e 63 74 69 6f 6e 73 20 3c 2f 68 31 3e 0a 0a  unctions </h1>..
9d20: 3c 70 3e 20 41 75 78 69 6c 69 61 72 79 20 66 75  <p> Auxiliary fu
9d30: 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 69 6d 69  nctions are simi
9d40: 6c 61 72 20 74 6f 20 5b 63 6f 72 65 66 75 6e 63  lar to [corefunc
9d50: 20 7c 20 53 51 4c 20 73 63 61 6c 61 72 20 66 75   | SQL scalar fu
9d60: 6e 63 74 69 6f 6e 73 5d 2c 0a 65 78 63 65 70 74  nctions],.except
9d70: 20 74 68 61 74 20 74 68 65 79 20 6d 61 79 20 6f   that they may o
9d80: 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
9d90: 69 6e 20 66 75 6c 6c 2d 74 65 78 74 20 71 75 65  in full-text que
9da0: 72 69 65 73 20 28 74 68 6f 73 65 20 74 68 61 74  ries (those that
9db0: 20 75 73 65 0a 74 68 65 20 4d 41 54 43 48 20 6f   use.the MATCH o
9dc0: 70 65 72 61 74 6f 72 29 20 6f 6e 20 61 6e 20 46  perator) on an F
9dd0: 54 53 35 20 74 61 62 6c 65 2e 20 54 68 65 69 72  TS5 table. Their
9de0: 20 72 65 73 75 6c 74 73 20 61 72 65 20 63 61 6c   results are cal
9df0: 63 75 6c 61 74 65 64 20 62 61 73 65 64 20 6e 6f  culated based no
9e00: 74 0a 6f 6e 6c 79 20 6f 6e 20 74 68 65 20 61 72  t.only on the ar
9e10: 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74  guments passed t
9e20: 6f 20 74 68 65 6d 2c 20 62 75 74 20 61 6c 73 6f  o them, but also
9e30: 20 6f 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   on the current 
9e40: 6d 61 74 63 68 20 61 6e 64 20 0a 6d 61 74 63 68  match and .match
9e50: 65 64 20 72 6f 77 2e 20 46 6f 72 20 65 78 61 6d  ed row. For exam
9e60: 70 6c 65 2c 20 61 6e 20 61 75 78 69 6c 69 61 72  ple, an auxiliar
9e70: 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 72  y function may r
9e80: 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
9e90: 76 61 6c 75 65 0a 69 6e 64 69 63 61 74 69 6e 67  value.indicating
9ea0: 20 74 68 65 20 61 63 63 75 72 61 63 79 20 6f 66   the accuracy of
9eb0: 20 74 68 65 20 6d 61 74 63 68 20 28 73 65 65 20   the match (see 
9ec0: 74 68 65 20 5b 46 54 53 35 20 62 6d 32 35 7c 20  the [FTS5 bm25| 
9ed0: 62 6d 32 35 28 29 5d 20 66 75 6e 63 74 69 6f 6e  bm25()] function
9ee0: 29 2c 20 0a 6f 72 20 61 20 66 72 61 67 6d 65 6e  ), .or a fragmen
9ef0: 74 20 6f 66 20 74 65 78 74 20 66 72 6f 6d 20 74  t of text from t
9f00: 68 65 20 6d 61 74 63 68 65 64 20 72 6f 77 20 74  he matched row t
9f10: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  hat contains one
9f20: 20 6f 72 20 6d 6f 72 65 20 0a 69 6e 73 74 61 6e   or more .instan
9f30: 63 65 73 20 6f 66 20 74 68 65 20 73 65 61 72 63  ces of the searc
9f40: 68 20 74 65 72 6d 73 20 28 73 65 65 20 74 68 65  h terms (see the
9f50: 20 5b 46 54 53 35 20 73 6e 69 70 70 65 74 20 7c   [FTS5 snippet |
9f60: 20 73 6e 69 70 70 65 74 28 29 5d 20 66 75 6e 63   snippet()] func
9f70: 74 69 6f 6e 29 2e 0a 0a 3c 70 3e 54 6f 20 69 6e  tion)...<p>To in
9f80: 76 6f 6b 65 20 61 6e 20 61 75 78 69 6c 69 61 72  voke an auxiliar
9f90: 79 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 65 20  y function, the 
9fa0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 46 54 53 35  name of the FTS5
9fb0: 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
9fc0: 0a 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68  .specified as th
9fd0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
9fe0: 2e 20 4f 74 68 65 72 20 61 72 67 75 6d 65 6e 74  . Other argument
9ff0: 73 20 6d 61 79 20 66 6f 6c 6c 6f 77 20 74 68 65  s may follow the
a000: 20 66 69 72 73 74 2c 0a 64 65 70 65 6e 64 69 6e   first,.dependin
a010: 67 20 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69  g on the specifi
a020: 63 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  c auxiliary func
a030: 74 69 6f 6e 20 62 65 69 6e 67 20 69 6e 76 6f 6b  tion being invok
a040: 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ed. For example,
a050: 20 74 6f 0a 69 6e 76 6f 6b 65 20 74 68 65 20 22   to.invoke the "
a060: 68 69 67 68 6c 69 67 68 74 22 20 66 75 6e 63 74  highlight" funct
a070: 69 6f 6e 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ion:..<codeblock
a080: 3e 0a 20 20 53 45 4c 45 43 54 20 68 69 67 68 6c  >.  SELECT highl
a090: 69 67 68 74 28 65 6d 61 69 6c 2c 20 32 2c 20 27  ight(email, 2, '
a0a0: 26 6c 74 3b 62 26 67 74 3b 27 2c 20 27 26 6c 74  &lt;b&gt;', '&lt
a0b0: 3b 2f 62 26 67 74 3b 27 29 20 46 52 4f 4d 20 65  ;/b&gt;') FROM e
a0c0: 6d 61 69 6c 20 57 48 45 52 45 20 65 6d 61 69 6c  mail WHERE email
a0d0: 20 4d 41 54 43 48 20 27 66 74 73 35 27 0a 3c 2f   MATCH 'fts5'.</
a0e0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54  codeblock>..<p>T
a0f0: 68 65 20 62 75 69 6c 74 2d 69 6e 20 61 75 78 69  he built-in auxi
a100: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  liary functions 
a110: 70 72 6f 76 69 64 65 64 20 61 73 20 70 61 72 74  provided as part
a120: 20 6f 66 20 46 54 53 35 20 61 72 65 20 64 65 73   of FTS5 are des
a130: 63 72 69 62 65 64 20 69 6e 0a 74 68 65 20 66 6f  cribed in.the fo
a140: 6c 6c 6f 77 69 6e 67 20 73 65 63 74 69 6f 6e 2e  llowing section.
a150: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   Applications ma
a160: 79 20 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e 74  y also implement
a170: 20 0a 5b 46 54 53 35 20 63 75 73 74 6f 6d 20 61   .[FTS5 custom a
a180: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
a190: 6e 73 20 7c 20 63 75 73 74 6f 6d 20 61 75 78 69  ns | custom auxi
a1a0: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  liary functions 
a1b0: 69 6e 20 43 5d 2e 0a 0a 3c 68 32 3e 42 75 69 6c  in C]...<h2>Buil
a1c0: 74 2d 69 6e 20 41 75 78 69 6c 69 61 72 79 20 46  t-in Auxiliary F
a1d0: 75 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c  unctions</h2>..<
a1e0: 70 3e 20 46 54 53 35 20 70 72 6f 76 69 64 65 73  p> FTS5 provides
a1f0: 20 74 68 72 65 65 20 62 75 69 6c 74 2d 69 6e 20   three built-in 
a200: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
a210: 6f 6e 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  ons:..<ul>.  <li
a220: 3e 20 54 68 65 20 5b 46 54 53 35 20 62 6d 32 35  > The [FTS5 bm25
a230: 20 7c 20 62 6d 32 35 28 29 20 61 75 78 69 6c 69   | bm25() auxili
a240: 61 72 79 20 66 75 6e 63 74 69 6f 6e 5d 20 72 65  ary function] re
a250: 74 75 72 6e 73 20 61 20 72 65 61 6c 20 76 61 6c  turns a real val
a260: 75 65 0a 20 20 20 20 20 20 20 72 65 66 6c 65 63  ue.       reflec
a270: 74 69 6e 67 20 74 68 65 20 61 63 63 75 72 61 63  ting the accurac
a280: 79 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  y of the current
a290: 20 6d 61 74 63 68 2e 20 42 65 74 74 65 72 20 6d   match. Better m
a2a0: 61 74 63 68 65 73 20 61 72 65 0a 20 20 20 20 20  atches are.     
a2b0: 20 20 61 73 73 69 67 6e 65 64 20 6e 75 6d 65 72    assigned numer
a2c0: 69 63 61 6c 6c 79 20 6c 6f 77 65 72 20 76 61 6c  ically lower val
a2d0: 75 65 73 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65  ues...  <li> The
a2e0: 20 5b 46 54 53 35 20 68 69 67 68 6c 69 67 68 74   [FTS5 highlight
a2f0: 20 7c 20 68 69 67 68 6c 69 67 68 74 28 29 20 61   | highlight() a
a300: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
a310: 6e 5d 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  n] returns a cop
a320: 79 0a 20 20 20 20 20 20 20 6f 66 20 74 68 65 20  y.       of the 
a330: 74 65 78 74 20 66 72 6f 6d 20 6f 6e 65 20 6f 66  text from one of
a340: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66 20   the columns of 
a350: 74 68 65 20 63 75 72 72 65 6e 74 20 6d 61 74 63  the current matc
a360: 68 20 77 69 74 68 20 65 61 63 68 0a 20 20 20 20  h with each.    
a370: 20 20 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61     instance of a
a380: 20 71 75 65 72 69 65 64 20 74 65 72 6d 20 77 69   queried term wi
a390: 74 68 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  thin the result 
a3a0: 73 75 72 72 6f 75 6e 64 65 64 20 62 79 20 73 70  surrounded by sp
a3b0: 65 63 69 66 69 65 64 0a 20 20 20 20 20 20 20 6d  ecified.       m
a3c0: 61 72 6b 75 70 20 28 66 6f 72 20 65 78 61 6d 70  arkup (for examp
a3d0: 6c 65 20 22 26 6c 74 3b 62 26 67 74 3b 22 20 61  le "&lt;b&gt;" a
a3e0: 6e 64 20 22 26 6c 74 3b 2f 62 26 67 74 3b 22 29  nd "&lt;/b&gt;")
a3f0: 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 5b 46  ...  <li> The [F
a400: 54 53 35 20 73 6e 69 70 70 65 74 20 7c 20 73 6e  TS5 snippet | sn
a410: 69 70 70 65 74 28 29 20 61 75 78 69 6c 69 61 72  ippet() auxiliar
a420: 79 20 66 75 6e 63 74 69 6f 6e 5d 20 73 65 6c 65  y function] sele
a430: 63 74 73 20 61 20 73 68 6f 72 74 0a 20 20 20 20  cts a short.    
a440: 20 20 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 74     fragment of t
a450: 65 78 74 20 66 72 6f 6d 20 6f 6e 65 20 6f 66 20  ext from one of 
a460: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74  the columns of t
a470: 68 65 20 6d 61 74 63 68 65 64 20 72 6f 77 20 61  he matched row a
a480: 6e 64 20 72 65 74 75 72 6e 73 0a 20 20 20 20 20  nd returns.     
a490: 20 20 69 74 20 77 69 74 68 20 65 61 63 68 20 69    it with each i
a4a0: 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 71 75 65  nstance of a que
a4b0: 72 69 65 64 20 74 65 72 6d 20 73 75 72 72 6f 75  ried term surrou
a4c0: 6e 64 65 64 20 62 79 20 6d 61 72 6b 75 70 20 69  nded by markup i
a4d0: 6e 0a 20 20 20 20 20 20 20 74 68 65 20 73 61 6d  n.       the sam
a4e0: 65 20 6d 61 6e 6e 65 72 20 61 73 20 74 68 65 20  e manner as the 
a4f0: 68 69 67 68 6c 69 67 68 74 28 29 20 66 75 6e 63  highlight() func
a500: 74 69 6f 6e 2e 20 54 68 65 20 66 72 61 67 6d 65  tion. The fragme
a510: 6e 74 20 6f 66 20 74 65 78 74 20 69 73 0a 20 20  nt of text is.  
a520: 20 20 20 20 20 73 65 6c 65 63 74 65 64 20 73 6f       selected so
a530: 20 61 73 20 74 6f 20 6d 61 78 69 6d 69 7a 65 20   as to maximize 
a540: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 71 75  the number of qu
a550: 65 72 69 65 64 20 74 65 72 6d 73 20 69 74 20 63  eried terms it c
a560: 6f 6e 74 61 69 6e 73 2e 0a 3c 2f 75 6c 3e 0a 0a  ontains..</ul>..
a570: 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 62  <h3 tags="FTS5 b
a580: 6d 32 35 22 3e 54 68 65 20 62 6d 32 35 28 29 20  m25">The bm25() 
a590: 66 75 6e 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c  function</h3>..<
a5a0: 70 3e 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  p> The built-in 
a5b0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
a5c0: 6f 6e 20 62 6d 32 35 28 29 20 72 65 74 75 72 6e  on bm25() return
a5d0: 73 20 61 20 72 65 61 6c 20 76 61 6c 75 65 20 69  s a real value i
a5e0: 6e 64 69 63 61 74 69 6e 67 0a 68 6f 77 20 77 65  ndicating.how we
a5f0: 6c 6c 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ll the current r
a600: 6f 77 20 6d 61 74 63 68 65 73 20 74 68 65 20 66  ow matches the f
a610: 75 6c 6c 2d 74 65 78 74 20 71 75 65 72 79 2e 20  ull-text query. 
a620: 54 68 65 20 62 65 74 74 65 72 20 74 68 65 20 6d  The better the m
a630: 61 74 63 68 2c 0a 74 68 65 20 6e 75 6d 65 72 69  atch,.the numeri
a640: 63 61 6c 6c 79 20 73 6d 61 6c 6c 65 72 20 74 68  cally smaller th
a650: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
a660: 2e 20 41 20 71 75 65 72 79 20 73 75 63 68 20 61  . A query such a
a670: 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
a680: 6d 61 79 0a 62 65 20 75 73 65 64 20 74 6f 20 72  may.be used to r
a690: 65 74 75 72 6e 20 6d 61 74 63 68 65 73 20 69 6e  eturn matches in
a6a0: 20 6f 72 64 65 72 20 66 72 6f 6d 20 62 65 73 74   order from best
a6b0: 20 74 6f 20 77 6f 72 73 74 20 6d 61 74 63 68 3a   to worst match:
a6c0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
a6d0: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
a6e0: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
a6f0: 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62 6d 32  H ? ORDER BY bm2
a700: 35 28 66 74 73 29 0a 3c 2f 63 6f 64 65 62 6c 6f  5(fts).</codeblo
a710: 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65  ck>..<p> In orde
a720: 72 20 74 6f 20 63 61 6c 63 75 6c 61 74 65 20 61  r to calculate a
a730: 20 64 6f 63 75 6d 65 6e 74 73 20 73 63 6f 72 65   documents score
a740: 2c 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  , the full-text 
a750: 71 75 65 72 79 20 69 73 20 73 65 70 61 72 61 74  query is separat
a760: 65 64 0a 20 20 20 20 69 6e 74 6f 20 69 74 73 20  ed.    into its 
a770: 63 6f 6d 70 6f 6e 65 6e 74 20 70 68 72 61 73 65  component phrase
a780: 73 2e 20 54 68 65 20 62 6d 32 35 20 73 63 6f 72  s. The bm25 scor
a790: 65 20 66 6f 72 20 64 6f 63 75 6d 65 6e 74 20 3c  e for document <
a7a0: 69 3e 44 3c 2f 69 3e 20 61 6e 64 20 0a 20 20 20  i>D</i> and .   
a7b0: 20 71 75 65 72 79 20 3c 69 3e 51 3c 2f 69 3e 20   query <i>Q</i> 
a7c0: 69 73 20 74 68 65 6e 20 63 61 6c 63 75 6c 61 74  is then calculat
a7d0: 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a  ed as follows:..
a7e0: 3c 70 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d  <p> <img src="im
a7f0: 61 67 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c  ages/fts5_formul
a800: 61 31 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77  a1.png" style="w
a810: 69 64 74 68 3a 37 35 65 78 3b 6d 61 72 67 69 6e  idth:75ex;margin
a820: 2d 6c 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e  -left:5ex">..<p>
a830: 20 49 6e 20 74 68 65 20 61 62 6f 76 65 2c 20 3c   In the above, <
a840: 69 3e 6e 50 68 72 61 73 65 3c 2f 69 3e 20 69 73  i>nPhrase</i> is
a850: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
a860: 68 72 61 73 65 73 20 69 6e 20 74 68 65 20 71 75  hrases in the qu
a870: 65 72 79 2e 0a 20 20 20 20 3c 69 3e 7c 44 7c 3c  ery..    <i>|D|<
a880: 2f 69 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  /i> is the numbe
a890: 72 20 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 74  r of tokens in t
a8a0: 68 65 20 63 75 72 72 65 6e 74 20 64 6f 63 75 6d  he current docum
a8b0: 65 6e 74 2c 20 61 6e 64 0a 20 20 20 20 3c 69 3e  ent, and.    <i>
a8c0: 61 76 67 64 6c 3c 2f 69 3e 20 69 73 20 74 68 65  avgdl</i> is the
a8d0: 20 61 76 65 72 61 67 65 20 6e 75 6d 62 65 72 20   average number 
a8e0: 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 61 6c 6c  of tokens in all
a8f0: 20 64 6f 63 75 6d 65 6e 74 73 20 77 69 74 68 69   documents withi
a900: 6e 20 74 68 65 0a 20 20 20 20 46 54 53 35 20 74  n the.    FTS5 t
a910: 61 62 6c 65 2e 20 20 3c 69 3e 6b 3c 73 75 62 3e  able.  <i>k<sub>
a920: 31 3c 2f 73 75 62 3e 3c 2f 69 3e 20 61 6e 64 20  1</sub></i> and 
a930: 3c 69 3e 62 3c 2f 69 3e 20 61 72 65 20 62 6f 74  <i>b</i> are bot
a940: 68 20 63 6f 6e 73 74 61 6e 74 73 2c 0a 20 20 20  h constants,.   
a950: 20 68 61 72 64 2d 63 6f 64 65 64 20 61 74 20 31   hard-coded at 1
a960: 2e 32 20 61 6e 64 20 30 2e 37 35 20 72 65 73 70  .2 and 0.75 resp
a970: 65 63 74 69 76 65 6c 79 2e 0a 0a 3c 70 3e 20 54  ectively...<p> T
a980: 68 65 20 22 2d 31 22 20 74 65 72 6d 20 61 74 20  he "-1" term at 
a990: 74 68 65 20 73 74 61 72 74 20 6f 66 20 74 68 65  the start of the
a9a0: 20 66 6f 72 6d 75 6c 61 20 69 73 20 6e 6f 74 20   formula is not 
a9b0: 66 6f 75 6e 64 20 69 6e 20 6d 6f 73 74 0a 69 6d  found in most.im
a9c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
a9d0: 20 74 68 65 20 42 4d 32 35 20 61 6c 67 6f 72 69   the BM25 algori
a9e0: 74 68 6d 2e 20 57 69 74 68 6f 75 74 20 69 74 2c  thm. Without it,
a9f0: 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
aa00: 69 73 20 61 73 73 69 67 6e 65 64 0a 61 20 6e 75  is assigned.a nu
aa10: 6d 65 72 69 63 61 6c 6c 79 20 68 69 67 68 65 72  merically higher
aa20: 20 42 4d 32 35 20 73 63 6f 72 65 2e 20 53 69 6e   BM25 score. Sin
aa30: 63 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ce the default s
aa40: 6f 72 74 69 6e 67 20 6f 72 64 65 72 20 69 73 0a  orting order is.
aa50: 22 61 73 63 65 6e 64 69 6e 67 22 2c 20 74 68 69  "ascending", thi
aa60: 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 70 70  s means that app
aa70: 65 6e 64 69 6e 67 20 22 4f 52 44 45 52 20 42 59  ending "ORDER BY
aa80: 20 62 6d 32 35 28 66 74 73 29 22 20 74 6f 20 61   bm25(fts)" to a
aa90: 20 71 75 65 72 79 20 77 6f 75 6c 64 0a 63 61 75   query would.cau
aaa0: 73 65 20 72 65 73 75 6c 74 73 20 74 6f 20 62 65  se results to be
aab0: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 6f 72 64   returned in ord
aac0: 65 72 20 66 72 6f 6d 20 77 6f 72 73 74 20 74 6f  er from worst to
aad0: 20 62 65 73 74 2e 20 54 68 65 20 22 44 45 53 43   best. The "DESC
aae0: 22 20 6b 65 79 77 6f 72 64 0a 77 6f 75 6c 64 20  " keyword.would 
aaf0: 62 65 20 72 65 71 75 69 72 65 64 20 69 6e 20 6f  be required in o
ab00: 72 64 65 72 20 74 6f 20 72 65 74 75 72 6e 20 74  rder to return t
ab10: 68 65 20 62 65 73 74 20 6d 61 74 63 68 65 73 20  he best matches 
ab20: 66 69 72 73 74 2e 20 49 6e 20 6f 72 64 65 72 20  first. In order 
ab30: 74 6f 0a 61 76 6f 69 64 20 74 68 69 73 20 70 69  to.avoid this pi
ab40: 74 66 61 6c 6c 2c 20 74 68 65 20 46 54 53 35 20  tfall, the FTS5 
ab50: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
ab60: 66 20 42 4d 32 35 20 6d 75 6c 74 69 70 6c 69 65  f BM25 multiplie
ab70: 73 20 74 68 65 20 72 65 73 75 6c 74 0a 62 79 20  s the result.by 
ab80: 2d 31 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  -1 before return
ab90: 69 6e 67 20 69 74 2c 20 65 6e 73 75 72 69 6e 67  ing it, ensuring
aba0: 20 74 68 61 74 20 62 65 74 74 65 72 20 6d 61 74   that better mat
abb0: 63 68 65 73 20 61 72 65 20 61 73 73 69 67 6e 65  ches are assigne
abc0: 64 0a 6e 75 6d 65 72 69 63 61 6c 6c 79 20 6c 6f  d.numerically lo
abd0: 77 65 72 20 73 63 6f 72 65 73 2e 0a 0a 3c 70 3e  wer scores...<p>
abe0: 20 3c 69 3e 49 44 46 28 71 3c 73 75 62 3e 69 3c   <i>IDF(q<sub>i<
abf0: 2f 73 75 62 3e 29 3c 2f 69 3e 20 69 73 20 74 68  /sub>)</i> is th
ac00: 65 20 69 6e 76 65 72 73 65 2d 64 6f 63 75 6d 65  e inverse-docume
ac10: 6e 74 2d 66 72 65 71 75 65 6e 63 79 20 6f 66 20  nt-frequency of 
ac20: 71 75 65 72 79 20 0a 20 20 20 20 70 68 72 61 73  query .    phras
ac30: 65 20 3c 69 3e 69 3c 2f 69 3e 2e 20 49 74 20 69  e <i>i</i>. It i
ac40: 73 20 63 61 6c 63 75 6c 61 74 65 64 20 61 73 20  s calculated as 
ac50: 66 6f 6c 6c 6f 77 73 2c 20 77 68 65 72 65 20 3c  follows, where <
ac60: 69 3e 4e 3c 2f 69 3e 20 69 73 20 74 68 65 20 74  i>N</i> is the t
ac70: 6f 74 61 6c 0a 20 20 20 20 6e 75 6d 62 65 72 20  otal.    number 
ac80: 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 20 46  of rows in the F
ac90: 54 53 35 20 74 61 62 6c 65 20 61 6e 64 20 3c 69  TS5 table and <i
aca0: 3e 6e 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62 3e  >n(q<sub>i</sub>
acb0: 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 74 6f 74  )</i> is the tot
acc0: 61 6c 0a 20 20 20 20 6e 75 6d 62 65 72 20 6f 66  al.    number of
acd0: 20 72 6f 77 73 20 74 68 61 74 20 63 6f 6e 74 61   rows that conta
ace0: 69 6e 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20  in at least one 
acf0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 70 68 72 61  instance of phra
ad00: 73 65 20 3c 69 3e 69 3c 2f 69 3e 3a 0a 0a 3c 70  se <i>i</i>:..<p
ad10: 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d 61 67  > <img src="imag
ad20: 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c 61 32  es/fts5_formula2
ad30: 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77 69 64  .png" style="wid
ad40: 74 68 3a 37 35 65 78 3b 6d 61 72 67 69 6e 2d 6c  th:75ex;margin-l
ad50: 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e 20 46  eft:5ex">..<p> F
ad60: 69 6e 61 6c 6c 79 2c 20 3c 69 3e 66 28 71 3c 73  inally, <i>f(q<s
ad70: 75 62 3e 69 3c 2f 73 75 62 3e 2c 44 29 3c 2f 69  ub>i</sub>,D)</i
ad80: 3e 20 69 73 20 74 68 65 20 70 68 72 61 73 65 20  > is the phrase 
ad90: 66 72 65 71 75 65 6e 63 79 20 6f 66 20 70 68 72  frequency of phr
ada0: 61 73 65 20 0a 3c 69 3e 69 3c 2f 69 3e 2e 20 42  ase .<i>i</i>. B
adb0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 69 73 20  y default, this 
adc0: 69 73 20 73 69 6d 70 6c 79 20 74 68 65 20 6e 75  is simply the nu
add0: 6d 62 65 72 20 6f 66 20 6f 63 63 75 72 72 65 6e  mber of occurren
ade0: 63 65 73 20 6f 66 20 74 68 65 20 70 68 72 61 73  ces of the phras
adf0: 65 0a 77 69 74 68 69 6e 20 74 68 65 20 63 75 72  e.within the cur
ae00: 72 65 6e 74 20 72 6f 77 2e 20 48 6f 77 65 76 65  rent row. Howeve
ae10: 72 2c 20 62 79 20 70 61 73 73 69 6e 67 20 65 78  r, by passing ex
ae20: 74 72 61 20 72 65 61 6c 20 76 61 6c 75 65 20 61  tra real value a
ae30: 72 67 75 6d 65 6e 74 73 20 74 6f 20 0a 74 68 65  rguments to .the
ae40: 20 62 6d 32 35 28 29 20 53 51 4c 20 66 75 6e 63   bm25() SQL func
ae50: 74 69 6f 6e 2c 20 65 61 63 68 20 63 6f 6c 75 6d  tion, each colum
ae60: 6e 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 6d  n of the table m
ae70: 61 79 20 62 65 20 61 73 73 69 67 6e 65 64 20 61  ay be assigned a
ae80: 20 64 69 66 66 65 72 65 6e 74 0a 77 65 69 67 68   different.weigh
ae90: 74 20 61 6e 64 20 74 68 65 20 70 68 72 61 73 65  t and the phrase
aea0: 20 66 72 65 71 75 65 6e 63 79 20 63 61 6c 63 75   frequency calcu
aeb0: 6c 61 74 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73  lated as follows
aec0: 3a 0a 0a 3c 70 3e 20 3c 69 6d 67 20 73 72 63 3d  :..<p> <img src=
aed0: 22 69 6d 61 67 65 73 2f 66 74 73 35 5f 66 6f 72  "images/fts5_for
aee0: 6d 75 6c 61 33 2e 70 6e 67 22 20 73 74 79 6c 65  mula3.png" style
aef0: 3d 22 77 69 64 74 68 3a 37 35 65 78 3b 6d 61 72  ="width:75ex;mar
af00: 67 69 6e 2d 6c 65 66 74 3a 35 65 78 22 3e 0a 0a  gin-left:5ex">..
af10: 3c 70 3e 20 77 68 65 72 65 20 3c 69 3e 77 3c 73  <p> where <i>w<s
af20: 75 62 3e 63 3c 2f 73 75 62 3e 3c 2f 69 3e 20 69  ub>c</sub></i> i
af30: 73 20 74 68 65 20 77 65 69 67 68 74 20 61 73 73  s the weight ass
af40: 69 67 6e 65 64 20 74 6f 20 63 6f 6c 75 6d 6e 20  igned to column 
af50: 3c 69 3e 63 3c 2f 69 3e 20 61 6e 64 0a 3c 69 3e  <i>c</i> and.<i>
af60: 6e 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62 3e 2c  n(q<sub>i</sub>,
af70: 63 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 6e 75  c)</i> is the nu
af80: 6d 62 65 72 20 6f 66 20 6f 63 63 75 72 72 65 6e  mber of occurren
af90: 63 65 73 20 6f 66 20 70 68 72 61 73 65 20 3c 69  ces of phrase <i
afa0: 3e 69 3c 2f 69 3e 20 69 6e 0a 63 6f 6c 75 6d 6e  >i</i> in.column
afb0: 20 3c 69 3e 63 3c 2f 69 3e 20 6f 66 20 74 68 65   <i>c</i> of the
afc0: 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 54 68   current row. Th
afd0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
afe0: 20 70 61 73 73 65 64 20 74 6f 20 62 6d 32 35 28   passed to bm25(
aff0: 29 0a 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20  ).following the 
b000: 74 61 62 6c 65 20 6e 61 6d 65 20 69 73 20 74 68  table name is th
b010: 65 20 77 65 69 67 68 74 20 61 73 73 69 67 6e 65  e weight assigne
b020: 64 20 74 6f 20 74 68 65 20 6c 65 66 74 6d 6f 73  d to the leftmos
b030: 74 20 63 6f 6c 75 6d 6e 20 6f 66 0a 74 68 65 20  t column of.the 
b040: 46 54 53 35 20 74 61 62 6c 65 2e 20 54 68 65 20  FTS5 table. The 
b050: 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 77 65  second is the we
b060: 69 67 68 74 20 61 73 73 69 67 6e 65 64 20 74 6f  ight assigned to
b070: 20 74 68 65 20 73 65 63 6f 6e 64 20 6c 65 66 74   the second left
b080: 6d 6f 73 74 0a 63 6f 6c 75 6d 6e 2c 20 61 6e 64  most.column, and
b090: 20 73 6f 20 6f 6e 2e 20 49 66 20 74 68 65 72 65   so on. If there
b0a0: 20 61 72 65 20 6e 6f 74 20 65 6e 6f 75 67 68 20   are not enough 
b0b0: 61 72 67 75 6d 65 6e 74 73 20 66 6f 72 20 61 6c  arguments for al
b0c0: 6c 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 73 2c  l table columns,
b0d0: 0a 72 65 6d 61 69 6e 69 6e 67 20 63 6f 6c 75 6d  .remaining colum
b0e0: 6e 73 20 61 72 65 20 61 73 73 69 67 6e 65 64 20  ns are assigned 
b0f0: 61 20 77 65 69 67 68 74 20 6f 66 20 31 2e 30 2e  a weight of 1.0.
b100: 20 49 66 20 74 68 65 72 65 20 61 72 65 20 74 6f   If there are to
b110: 6f 20 6d 61 6e 79 20 0a 74 72 61 69 6c 69 6e 67  o many .trailing
b120: 20 61 72 67 75 6d 65 6e 74 73 2c 20 74 68 65 20   arguments, the 
b130: 65 78 74 72 61 73 20 61 72 65 20 69 67 6e 6f 72  extras are ignor
b140: 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  ed. For example:
b150: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
b160: 3c 69 3e 2d 2d 20 41 73 73 75 6d 69 6e 67 20 74  <i>-- Assuming t
b170: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 63 68  he following sch
b180: 65 6d 61 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ema:</i>.  CREAT
b190: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
b1a0: 65 6d 61 69 6c 20 55 53 49 4e 47 20 66 74 73 35  email USING fts5
b1b0: 28 73 65 6e 64 65 72 2c 20 74 69 74 6c 65 2c 20  (sender, title, 
b1c0: 62 6f 64 79 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  body);..  <i>-- 
b1d0: 52 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 69  Return results i
b1e0: 6e 20 62 6d 32 35 20 6f 72 64 65 72 2c 20 77 69  n bm25 order, wi
b1f0: 74 68 20 65 61 63 68 20 70 68 72 61 73 65 20 68  th each phrase h
b200: 69 74 20 69 6e 20 74 68 65 20 22 73 65 6e 64 65  it in the "sende
b210: 72 22 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63  r"</i>.  <i>-- c
b220: 6f 6c 75 6d 6e 20 63 6f 6e 73 69 64 65 72 65 64  olumn considered
b230: 20 74 68 65 20 65 71 75 61 6c 20 6f 66 20 31 30   the equal of 10
b240: 20 68 69 74 73 20 69 6e 20 74 68 65 20 22 62 6f   hits in the "bo
b250: 64 79 22 20 63 6f 6c 75 6d 6e 2c 20 61 6e 64 3c  dy" column, and<
b260: 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 65 61 63 68  /i>.  <i>-- each
b270: 20 68 69 74 20 69 6e 20 74 68 65 20 22 74 69 74   hit in the "tit
b280: 6c 65 22 20 63 6f 6c 75 6d 6e 20 63 6f 6e 73 69  le" column consi
b290: 64 65 72 65 64 20 61 73 20 76 61 6c 75 61 62 6c  dered as valuabl
b2a0: 65 20 61 73 20 35 20 68 69 74 73 20 69 6e 3c 2f  e as 5 hits in</
b2b0: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 74 68 65 20 22  i>.  <i>-- the "
b2c0: 62 6f 64 79 22 20 63 6f 6c 75 6d 6e 2e 3c 2f 69  body" column.</i
b2d0: 3e 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  >.  SELECT * FRO
b2e0: 4d 20 65 6d 61 69 6c 20 57 48 45 52 45 20 65 6d  M email WHERE em
b2f0: 61 69 6c 20 4d 41 54 43 48 20 3f 20 4f 52 44 45  ail MATCH ? ORDE
b300: 52 20 42 59 20 62 6d 32 35 28 65 6d 61 69 6c 2c  R BY bm25(email,
b310: 20 31 30 2e 30 2c 20 35 2e 30 29 3b 0a 3c 2f 63   10.0, 5.0);.</c
b320: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 52 65  odeblock>..<p>Re
b330: 66 65 72 20 74 6f 20 77 69 6b 69 70 65 64 69 61  fer to wikipedia
b340: 20 66 6f 72 20 0a 3c 61 20 68 72 65 66 3d 22 68   for .<a href="h
b350: 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64  ttp://en.wikiped
b360: 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4f 6b 61 70  ia.org/wiki/Okap
b370: 69 5f 42 4d 32 35 22 3e 6d 6f 72 65 20 69 6e 66  i_BM25">more inf
b380: 6f 72 6d 61 74 69 6f 6e 20 72 65 67 61 72 64 69  ormation regardi
b390: 6e 67 0a 42 4d 32 35 3c 2f 61 3e 20 61 6e 64 20  ng.BM25</a> and 
b3a0: 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 0a 3c  its variants...<
b3b0: 68 33 20 74 61 67 73 3d 22 46 54 53 35 20 68 69  h3 tags="FTS5 hi
b3c0: 67 68 6c 69 67 68 74 22 3e 54 68 65 20 68 69 67  ghlight">The hig
b3d0: 68 6c 69 67 68 74 28 29 20 66 75 6e 63 74 69 6f  hlight() functio
b3e0: 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20  n</h3>..<p> The 
b3f0: 68 69 67 68 6c 69 67 68 74 28 29 20 66 75 6e 63  highlight() func
b400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 63  tion returns a c
b410: 6f 70 79 20 6f 66 20 74 68 65 20 74 65 78 74 20  opy of the text 
b420: 66 72 6f 6d 20 61 20 73 70 65 63 69 66 69 65 64  from a specified
b430: 20 0a 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20   .column of the 
b440: 63 75 72 72 65 6e 74 20 72 6f 77 20 77 69 74 68  current row with
b450: 20 65 78 74 72 61 20 6d 61 72 6b 75 70 20 74 65   extra markup te
b460: 78 74 20 69 6e 73 65 72 74 65 64 20 74 6f 20 6d  xt inserted to m
b470: 61 72 6b 20 74 68 65 20 73 74 61 72 74 20 0a 61  ark the start .a
b480: 6e 64 20 65 6e 64 20 6f 66 20 70 68 72 61 73 65  nd end of phrase
b490: 20 6d 61 74 63 68 65 73 2e 20 0a 0a 3c 70 3e 54   matches. ..<p>T
b4a0: 68 65 20 68 69 67 68 6c 69 67 68 74 28 29 20 6d  he highlight() m
b4b0: 75 73 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ust be invoked w
b4c0: 69 74 68 20 65 78 61 63 74 6c 79 20 74 68 72 65  ith exactly thre
b4d0: 65 20 61 72 67 75 6d 65 6e 74 73 20 66 6f 6c 6c  e arguments foll
b4e0: 6f 77 69 6e 67 20 0a 74 68 65 20 74 61 62 6c 65  owing .the table
b4f0: 20 6e 61 6d 65 2e 20 54 6f 20 62 65 20 69 6e 74   name. To be int
b500: 65 72 70 72 65 74 65 64 20 61 73 20 66 6f 6c 6c  erpreted as foll
b510: 6f 77 73 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69  ows:..<ol>.  <li
b520: 3e 20 41 6e 20 69 6e 74 65 67 65 72 20 69 6e 64  > An integer ind
b530: 69 63 61 74 69 6e 67 20 74 68 65 20 69 6e 64 65  icating the inde
b540: 78 20 6f 66 20 74 68 65 20 46 54 53 20 74 61 62  x of the FTS tab
b550: 6c 65 20 63 6f 6c 75 6d 6e 20 74 6f 20 72 65 61  le column to rea
b560: 64 20 74 68 65 20 0a 20 20 20 20 20 20 20 74 65  d the .       te
b570: 78 74 20 66 72 6f 6d 2e 20 43 6f 6c 75 6d 6e 73  xt from. Columns
b580: 20 61 72 65 20 6e 75 6d 62 65 72 65 64 20 66 72   are numbered fr
b590: 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74  om left to right
b5a0: 20 73 74 61 72 74 69 6e 67 20 61 74 20 7a 65 72   starting at zer
b5b0: 6f 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74  o...  <li> The t
b5c0: 65 78 74 20 74 6f 20 69 6e 73 65 72 74 20 62 65  ext to insert be
b5d0: 66 6f 72 65 20 65 61 63 68 20 70 68 72 61 73 65  fore each phrase
b5e0: 20 6d 61 74 63 68 2e 0a 0a 20 20 3c 6c 69 3e 20   match...  <li> 
b5f0: 54 68 65 20 74 65 78 74 20 74 6f 20 69 6e 73 65  The text to inse
b600: 72 74 20 61 66 74 65 72 20 65 61 63 68 20 70 68  rt after each ph
b610: 72 61 73 65 20 6d 61 74 63 68 2e 0a 3c 2f 6f 6c  rase match..</ol
b620: 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c  >..<p>For exampl
b630: 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e:..<codeblock>.
b640: 20 20 3c 69 3e 2d 2d 20 52 65 74 75 72 6e 20 61    <i>-- Return a
b650: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 65 78   copy of the tex
b660: 74 20 66 72 6f 6d 20 74 68 65 20 6c 65 66 74 6d  t from the leftm
b670: 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
b680: 65 20 63 75 72 72 65 6e 74 3c 2f 69 3e 0a 20 20  e current</i>.  
b690: 3c 69 3e 2d 2d 20 72 6f 77 2c 20 77 69 74 68 20  <i>-- row, with 
b6a0: 70 68 72 61 73 65 20 6d 61 74 63 68 65 73 20 6d  phrase matches m
b6b0: 61 72 6b 65 64 20 75 73 69 6e 67 20 68 74 6d 6c  arked using html
b6c0: 20 22 62 22 20 74 61 67 73 2e 3c 2f 69 3e 0a 20   "b" tags.</i>. 
b6d0: 20 53 45 4c 45 43 54 20 68 69 67 68 6c 69 67 68   SELECT highligh
b6e0: 74 28 66 74 73 2c 20 30 2c 20 27 26 6c 74 3b 62  t(fts, 0, '&lt;b
b6f0: 26 67 74 3b 27 2c 20 27 26 6c 74 3b 2f 62 26 67  &gt;', '&lt;/b&g
b700: 74 3b 27 29 20 46 52 4f 4d 20 66 74 73 20 57 48  t;') FROM fts WH
b710: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 0a  ERE fts MATCH ?.
b720: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
b730: 3e 49 6e 20 63 61 73 65 73 20 77 68 65 72 65 20  >In cases where 
b740: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 70 68 72 61  two or more phra
b750: 73 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 76 65  se instances ove
b760: 72 6c 61 70 20 28 73 68 61 72 65 20 6f 6e 65 20  rlap (share one 
b770: 6f 72 20 6d 6f 72 65 0a 74 6f 6b 65 6e 73 20 69  or more.tokens i
b780: 6e 20 63 6f 6d 6d 6f 6e 29 2c 20 61 20 73 69 6e  n common), a sin
b790: 67 6c 65 20 6f 70 65 6e 20 61 6e 64 20 63 6c 6f  gle open and clo
b7a0: 73 65 20 6d 61 72 6b 65 72 20 69 73 20 69 6e 73  se marker is ins
b7b0: 65 72 74 65 64 20 66 6f 72 20 65 61 63 68 20 73  erted for each s
b7c0: 65 74 0a 6f 66 20 6f 76 65 72 6c 61 70 70 69 6e  et.of overlappin
b7d0: 67 20 70 68 72 61 73 65 73 2e 20 46 6f 72 20 65  g phrases. For e
b7e0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
b7f0: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 41 73 73  ock>.  <i>-- Ass
b800: 75 6d 69 6e 67 20 74 68 69 73 3a 3c 2f 69 3e 0a  uming this:</i>.
b810: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
b820: 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20   TABLE ft USING 
b830: 66 74 73 35 28 61 29 3b 0a 20 20 49 4e 53 45 52  fts5(a);.  INSER
b840: 54 20 49 4e 54 4f 20 66 74 20 56 41 4c 55 45 53  T INTO ft VALUES
b850: 28 27 61 20 62 20 63 20 78 20 63 20 64 20 65 27  ('a b c x c d e'
b860: 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
b870: 20 66 74 20 56 41 4c 55 45 53 28 27 61 20 62 20   ft VALUES('a b 
b880: 63 20 63 20 64 20 65 27 29 3b 0a 20 20 49 4e 53  c c d e');.  INS
b890: 45 52 54 20 49 4e 54 4f 20 66 74 20 56 41 4c 55  ERT INTO ft VALU
b8a0: 45 53 28 27 61 20 62 20 63 20 64 20 65 27 29 3b  ES('a b c d e');
b8b0: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f  ..  <i>-- The fo
b8c0: 6c 6c 6f 77 69 6e 67 20 53 45 4c 45 43 54 20 73  llowing SELECT s
b8d0: 74 61 74 65 6d 65 6e 74 20 72 65 74 75 72 6e 73  tatement returns
b8e0: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 77   these three row
b8f0: 73 3a 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20  s:</i>.  <i>--  
b900: 20 27 26 23 39 31 3b 61 20 62 20 63 26 23 39 33   '&#91;a b c&#93
b910: 3b 20 78 20 26 23 39 31 3b 63 20 64 20 65 26 23  ; x &#91;c d e&#
b920: 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  93;'</i>.  <i>--
b930: 20 20 20 27 26 23 39 31 3b 61 20 62 20 63 26 23     '&#91;a b c&#
b940: 39 33 3b 20 26 23 39 31 3b 63 20 64 20 65 26 23  93; &#91;c d e&#
b950: 39 33 3b 27 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  93;'</i>.  <i>--
b960: 20 20 20 27 26 23 39 31 3b 61 20 62 20 63 20 64     '&#91;a b c d
b970: 20 65 26 23 39 33 3b 27 3c 2f 69 3e 0a 20 20 53   e&#93;'</i>.  S
b980: 45 4c 45 43 54 20 68 69 67 68 6c 69 67 68 74 28  ELECT highlight(
b990: 66 74 2c 20 30 2c 20 27 26 23 39 31 3b 27 2c 20  ft, 0, '&#91;', 
b9a0: 27 26 23 39 33 3b 27 29 20 46 52 4f 4d 20 66 74  '&#93;') FROM ft
b9b0: 20 57 48 45 52 45 20 66 74 20 4d 41 54 43 48 20   WHERE ft MATCH 
b9c0: 27 61 2b 62 2b 63 20 41 4e 44 20 63 2b 64 2b 65  'a+b+c AND c+d+e
b9d0: 27 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  ';.</codeblock>.
b9e0: 0a 3c 68 33 20 74 61 67 73 3d 22 46 54 53 35 20  .<h3 tags="FTS5 
b9f0: 73 6e 69 70 70 65 74 22 3e 54 68 65 20 73 6e 69  snippet">The sni
ba00: 70 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 3c  ppet() function<
ba10: 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 73 6e 69  /h3>..<p>The sni
ba20: 70 70 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  ppet() function 
ba30: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 68 69  is similar to hi
ba40: 67 68 6c 69 67 68 74 28 29 2c 20 65 78 63 65 70  ghlight(), excep
ba50: 74 20 74 68 61 74 20 69 6e 73 74 65 61 64 20 6f  t that instead o
ba60: 66 0a 72 65 74 75 72 6e 69 6e 67 20 65 6e 74 69  f.returning enti
ba70: 72 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  re column values
ba80: 2c 20 69 74 20 61 75 74 6f 6d 61 74 69 63 61 6c  , it automatical
ba90: 6c 79 20 73 65 6c 65 63 74 73 20 61 6e 64 20 65  ly selects and e
baa0: 78 74 72 61 63 74 73 20 61 0a 73 68 6f 72 74 20  xtracts a.short 
bab0: 66 72 61 67 6d 65 6e 74 20 6f 66 20 64 6f 63 75  fragment of docu
bac0: 6d 65 6e 74 20 74 65 78 74 20 74 6f 20 70 72 6f  ment text to pro
bad0: 63 65 73 73 20 61 6e 64 20 72 65 74 75 72 6e 2e  cess and return.
bae0: 20 54 68 65 20 73 6e 69 70 70 65 74 28 29 20 66   The snippet() f
baf0: 75 6e 63 74 69 6f 6e 0a 6d 75 73 74 20 62 65 20  unction.must be 
bb00: 70 61 73 73 65 64 20 66 69 76 65 20 70 61 72 61  passed five para
bb10: 6d 65 74 65 72 73 20 66 6f 6c 6c 6f 77 69 6e 67  meters following
bb20: 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 20   the table name 
bb30: 61 72 67 75 6d 65 6e 74 3a 0a 0a 3c 6f 6c 3e 0a  argument:..<ol>.
bb40: 20 20 3c 6c 69 3e 20 41 6e 20 69 6e 74 65 67 65    <li> An intege
bb50: 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  r indicating the
bb60: 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 46 54   index of the FT
bb70: 53 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  S table column t
bb80: 6f 20 73 65 6c 65 63 74 0a 20 20 20 20 20 20 20  o select.       
bb90: 74 68 65 20 72 65 74 75 72 6e 65 64 20 74 65 78  the returned tex
bba0: 74 20 66 72 6f 6d 2e 20 43 6f 6c 75 6d 6e 73 20  t from. Columns 
bbb0: 61 72 65 20 6e 75 6d 62 65 72 65 64 20 66 72 6f  are numbered fro
bbc0: 6d 20 6c 65 66 74 20 74 6f 20 72 69 67 68 74 20  m left to right 
bbd0: 0a 20 20 20 20 20 20 20 73 74 61 72 74 69 6e 67  .       starting
bbe0: 20 61 74 20 7a 65 72 6f 2e 20 41 20 6e 65 67 61   at zero. A nega
bbf0: 74 69 76 65 20 76 61 6c 75 65 20 69 6e 64 69 63  tive value indic
bc00: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 63 6f  ates that the co
bc10: 6c 75 6d 6e 20 73 68 6f 75 6c 64 0a 20 20 20 20  lumn should.    
bc20: 20 20 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61     be automatica
bc30: 6c 6c 79 20 73 65 6c 65 63 74 65 64 2e 0a 0a 20  lly selected... 
bc40: 20 3c 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74   <li> The text t
bc50: 6f 20 69 6e 73 65 72 74 20 62 65 66 6f 72 65 20  o insert before 
bc60: 65 61 63 68 20 70 68 72 61 73 65 20 6d 61 74 63  each phrase matc
bc70: 68 20 77 69 74 68 69 6e 20 74 68 65 20 72 65 74  h within the ret
bc80: 75 72 6e 65 64 20 74 65 78 74 2e 0a 0a 20 20 3c  urned text...  <
bc90: 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74 6f 20  li> The text to 
bca0: 69 6e 73 65 72 74 20 61 66 74 65 72 20 65 61 63  insert after eac
bcb0: 68 20 70 68 72 61 73 65 20 6d 61 74 63 68 20 77  h phrase match w
bcc0: 69 74 68 69 6e 20 74 68 65 20 72 65 74 75 72 6e  ithin the return
bcd0: 65 64 20 74 65 78 74 2e 0a 0a 20 20 3c 6c 69 3e  ed text...  <li>
bce0: 20 54 68 65 20 74 65 78 74 20 74 6f 20 61 64 64   The text to add
bcf0: 20 74 6f 20 74 68 65 20 73 74 61 72 74 20 6f 72   to the start or
bd00: 20 65 6e 64 20 6f 66 20 74 68 65 20 73 65 6c 65   end of the sele
bd10: 63 74 65 64 20 74 65 78 74 20 74 6f 20 69 6e 64  cted text to ind
bd20: 69 63 61 74 65 0a 20 20 20 20 20 20 20 74 68 61  icate.       tha
bd30: 74 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 74  t the returned t
bd40: 65 78 74 20 64 6f 65 73 20 6e 6f 74 20 6f 63 63  ext does not occ
bd50: 75 72 20 61 74 20 74 68 65 20 73 74 61 72 74 20  ur at the start 
bd60: 6f 72 20 65 6e 64 20 6f 66 20 69 74 73 20 63 6f  or end of its co
bd70: 6c 75 6d 6e 2c 0a 20 20 20 20 20 20 20 72 65 73  lumn,.       res
bd80: 70 65 63 74 69 76 65 6c 79 2e 0a 0a 20 20 3c 6c  pectively...  <l
bd90: 69 3e 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  i> The maximum n
bda0: 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e 73 20  umber of tokens 
bdb0: 69 6e 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  in the returned 
bdc0: 74 65 78 74 2e 20 54 68 69 73 20 6d 75 73 74 20  text. This must 
bdd0: 62 65 20 67 72 65 61 74 65 72 0a 20 20 20 20 20  be greater.     
bde0: 20 20 74 68 61 6e 20 7a 65 72 6f 20 61 6e 64 20    than zero and 
bdf0: 65 71 75 61 6c 20 74 6f 20 6f 72 20 6c 65 73 73  equal to or less
be00: 20 74 68 61 6e 20 36 34 2e 20 0a 3c 2f 6f 6c 3e   than 64. .</ol>
be10: 0a 0a 3c 68 32 20 74 61 67 73 3d 22 61 75 78 69  ..<h2 tags="auxi
be20: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d  liary function m
be30: 61 70 70 69 6e 67 22 3e 53 6f 72 74 69 6e 67 20  apping">Sorting 
be40: 62 79 20 41 75 78 69 6c 69 61 72 79 20 46 75 6e  by Auxiliary Fun
be50: 63 74 69 6f 6e 20 52 65 73 75 6c 74 73 3c 2f 68  ction Results</h
be60: 32 3e 0a 0a 3c 70 3e 20 41 6c 6c 20 46 54 53 35  2>..<p> All FTS5
be70: 20 74 61 62 6c 65 73 20 66 65 61 74 75 72 65 20   tables feature 
be80: 61 20 73 70 65 63 69 61 6c 20 68 69 64 64 65 6e  a special hidden
be90: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 22 72   column named "r
bea0: 61 6e 6b 22 2e 20 49 66 20 74 68 65 0a 63 75 72  ank". If the.cur
beb0: 72 65 6e 74 20 71 75 65 72 79 20 69 73 20 6e 6f  rent query is no
bec0: 74 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 71 75  t a full-text qu
bed0: 65 72 79 20 28 69 2e 65 2e 20 69 66 20 69 74 20  ery (i.e. if it 
bee0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
bef0: 20 61 20 4d 41 54 43 48 0a 6f 70 65 72 61 74 6f   a MATCH.operato
bf00: 72 29 2c 20 74 68 65 20 76 61 6c 75 65 20 6f 66  r), the value of
bf10: 20 74 68 65 20 22 72 61 6e 6b 22 20 63 6f 6c 75   the "rank" colu
bf20: 6d 6e 20 69 73 20 61 6c 77 61 79 73 20 4e 55 4c  mn is always NUL
bf30: 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e  L. Otherwise, in
bf40: 20 61 0a 66 75 6c 6c 2d 74 65 78 74 20 71 75 65   a.full-text que
bf50: 72 79 2c 20 63 6f 6c 75 6d 6e 20 72 61 6e 6b 20  ry, column rank 
bf60: 63 6f 6e 74 61 69 6e 73 20 62 79 20 64 65 66 61  contains by defa
bf70: 75 6c 74 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ult the same val
bf80: 75 65 20 61 73 20 77 6f 75 6c 64 20 62 65 0a 72  ue as would be.r
bf90: 65 74 75 72 6e 65 64 20 62 79 20 65 78 65 63 75  eturned by execu
bfa0: 74 69 6e 67 20 74 68 65 20 62 6d 32 35 28 29 20  ting the bm25() 
bfb0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
bfc0: 6f 6e 20 77 69 74 68 20 6e 6f 20 74 72 61 69 6c  on with no trail
bfd0: 69 6e 67 20 0a 61 72 67 75 6d 65 6e 74 73 2e 0a  ing .arguments..
bfe0: 0a 3c 70 3e 20 54 68 65 20 64 69 66 66 65 72 65  .<p> The differe
bff0: 6e 63 65 20 62 65 74 77 65 65 6e 20 72 65 61 64  nce between read
c000: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 72 61 6e  ing from the ran
c010: 6b 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 75 73 69  k column and usi
c020: 6e 67 20 74 68 65 20 62 6d 32 35 28 29 0a 66 75  ng the bm25().fu
c030: 6e 63 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 20  nction directly 
c040: 77 69 74 68 69 6e 20 74 68 65 20 71 75 65 72 79  within the query
c050: 20 69 73 20 6f 6e 6c 79 20 73 69 67 6e 69 66 69   is only signifi
c060: 63 61 6e 74 20 77 68 65 6e 20 73 6f 72 74 69 6e  cant when sortin
c070: 67 20 62 79 20 74 68 65 0a 72 65 74 75 72 6e 65  g by the.returne
c080: 64 20 76 61 6c 75 65 2e 20 49 6e 20 74 68 69 73  d value. In this
c090: 20 63 61 73 65 2c 20 75 73 69 6e 67 20 22 72 61   case, using "ra
c0a0: 6e 6b 22 20 69 73 20 66 61 73 74 65 72 20 74 68  nk" is faster th
c0b0: 61 6e 20 75 73 69 6e 67 20 62 6d 32 35 28 29 2e  an using bm25().
c0c0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
c0d0: 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77  <i>-- The follow
c0e0: 69 6e 67 20 71 75 65 72 69 65 73 20 61 72 65 20  ing queries are 
c0f0: 6c 6f 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61  logically equiva
c100: 6c 65 6e 74 2e 20 42 75 74 20 74 68 65 20 73 65  lent. But the se
c110: 63 6f 6e 64 20 6d 61 79 3c 2f 69 3e 0a 20 20 3c  cond may</i>.  <
c120: 69 3e 2d 2d 20 62 65 20 66 61 73 74 65 72 2c 20  i>-- be faster, 
c130: 70 61 72 74 69 63 75 6c 61 72 6c 79 20 69 66 20  particularly if 
c140: 74 68 65 20 63 61 6c 6c 65 72 20 61 62 61 6e 64  the caller aband
c150: 6f 6e 73 20 74 68 65 20 71 75 65 72 79 20 62 65  ons the query be
c160: 66 6f 72 65 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  fore</i>.  <i>--
c170: 20 61 6c 6c 20 72 6f 77 73 20 68 61 76 65 20 62   all rows have b
c180: 65 65 6e 20 72 65 74 75 72 6e 65 64 20 28 6f 72  een returned (or
c190: 20 69 66 20 74 68 65 20 71 75 65 72 69 65 73 20   if the queries 
c1a0: 77 65 72 65 20 6d 6f 64 69 66 69 65 64 20 74 6f  were modified to
c1b0: 20 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 69 6e   </i>.  <i>-- in
c1c0: 63 6c 75 64 65 20 4c 49 4d 49 54 20 63 6c 61 75  clude LIMIT clau
c1d0: 73 65 73 29 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45  ses).</i>.  SELE
c1e0: 43 54 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48  CT * FROM fts WH
c1f0: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20  ERE fts MATCH ? 
c200: 4f 52 44 45 52 20 42 59 20 62 6d 32 35 28 66 74  ORDER BY bm25(ft
c210: 73 29 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46  s);.  SELECT * F
c220: 52 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74  ROM fts WHERE ft
c230: 73 20 4d 41 54 43 48 20 3f 20 4f 52 44 45 52 20  s MATCH ? ORDER 
c240: 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62  BY rank;.</codeb
c250: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 73 74 65  lock>..<p> Inste
c260: 61 64 20 6f 66 20 75 73 69 6e 67 20 62 6d 32 35  ad of using bm25
c270: 28 29 20 77 69 74 68 20 6e 6f 20 74 72 61 69 6c  () with no trail
c280: 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 2c 20 74  ing arguments, t
c290: 68 65 20 73 70 65 63 69 66 69 63 20 61 75 78 69  he specific auxi
c2a0: 6c 69 61 72 79 0a 66 75 6e 63 74 69 6f 6e 20 6d  liary.function m
c2b0: 61 70 70 65 64 20 74 6f 20 74 68 65 20 72 61 6e  apped to the ran
c2c0: 6b 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 62 65 20  k column may be 
c2d0: 63 6f 6e 66 69 67 75 72 65 64 20 65 69 74 68 65  configured eithe
c2e0: 72 20 6f 6e 20 61 20 70 65 72 2d 71 75 65 72 79  r on a per-query
c2f0: 0a 62 61 73 69 73 2c 20 6f 72 20 62 79 20 73 65  .basis, or by se
c300: 74 74 69 6e 67 20 61 20 64 69 66 66 65 72 65 6e  tting a differen
c310: 74 20 70 65 72 73 69 73 74 65 6e 74 20 64 65 66  t persistent def
c320: 61 75 6c 74 20 66 6f 72 20 74 68 65 20 46 54 53  ault for the FTS
c330: 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 49 6e 20   table...<p> In 
c340: 6f 72 64 65 72 20 74 6f 20 63 68 61 6e 67 65 20  order to change 
c350: 74 68 65 20 6d 61 70 70 69 6e 67 20 6f 66 20 74  the mapping of t
c360: 68 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 66  he rank column f
c370: 6f 72 20 61 20 73 69 6e 67 6c 65 20 71 75 65 72  or a single quer
c380: 79 2c 20 0a 61 20 74 65 72 6d 20 73 69 6d 69 6c  y, .a term simil
c390: 61 72 20 74 6f 20 65 69 74 68 65 72 20 6f 66 20  ar to either of 
c3a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 73  the following is
c3b0: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 57 48   added to the WH
c3c0: 45 52 45 20 63 6c 61 75 73 65 20 6f 66 20 61 20  ERE clause of a 
c3d0: 0a 71 75 65 72 79 3a 0a 0a 3c 63 6f 64 65 62 6c  .query:..<codebl
c3e0: 6f 63 6b 3e 0a 20 20 72 61 6e 6b 20 4d 41 54 43  ock>.  rank MATC
c3f0: 48 20 27 61 75 78 69 6c 69 61 72 79 2d 66 75 6e  H 'auxiliary-fun
c400: 63 74 69 6f 6e 2d 6e 61 6d 65 28 61 72 67 31 2c  ction-name(arg1,
c410: 20 61 72 67 32 2c 20 2e 2e 2e 29 27 0a 20 20 72   arg2, ...)'.  r
c420: 61 6e 6b 20 3d 20 27 61 75 78 69 6c 69 61 72 79  ank = 'auxiliary
c430: 2d 66 75 6e 63 74 69 6f 6e 2d 6e 61 6d 65 28 61  -function-name(a
c440: 72 67 31 2c 20 61 72 67 32 2c 20 2e 2e 2e 29 27  rg1, arg2, ...)'
c450: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
c460: 70 3e 20 54 68 65 20 72 69 67 68 74 2d 68 61 6e  p> The right-han
c470: 64 2d 73 69 64 65 20 6f 66 20 74 68 65 20 4d 41  d-side of the MA
c480: 54 43 48 20 6f 72 20 3d 20 6f 70 65 72 61 74 6f  TCH or = operato
c490: 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 6e 73  r must be a cons
c4a0: 74 61 6e 74 0a 65 78 70 72 65 73 73 69 6f 6e 20  tant.expression 
c4b0: 74 68 61 74 20 65 76 61 6c 75 61 74 65 73 20 74  that evaluates t
c4c0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 69  o a string consi
c4d0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 61 75 78  sting of the aux
c4e0: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20  iliary function 
c4f0: 74 6f 0a 69 6e 76 6f 6b 65 2c 20 66 6f 6c 6c 6f  to.invoke, follo
c500: 77 65 64 20 62 79 20 7a 65 72 6f 20 6f 72 20 6d  wed by zero or m
c510: 6f 72 65 20 63 6f 6d 6d 61 20 73 65 70 61 72 61  ore comma separa
c520: 74 65 64 20 61 72 67 75 6d 65 6e 74 73 20 77 69  ted arguments wi
c530: 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 69 73  thin parenthesis
c540: 2e 0a 41 72 67 75 6d 65 6e 74 73 20 6d 75 73 74  ..Arguments must
c550: 20 62 65 20 53 51 4c 20 6c 69 74 65 72 61 6c 73   be SQL literals
c560: 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  . For example:..
c570: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
c580: 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  >-- The followin
c590: 67 20 71 75 65 72 69 65 73 20 61 72 65 20 6c 6f  g queries are lo
c5a0: 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65  gically equivale
c5b0: 6e 74 2e 20 42 75 74 20 74 68 65 20 73 65 63 6f  nt. But the seco
c5c0: 6e 64 20 6d 61 79 3c 2f 69 3e 0a 20 20 3c 69 3e  nd may</i>.  <i>
c5d0: 2d 2d 20 62 65 20 66 61 73 74 65 72 2e 20 53 65  -- be faster. Se
c5e0: 65 20 61 62 6f 76 65 2e 20 3c 2f 69 3e 0a 20 20  e above. </i>.  
c5f0: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
c600: 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54 43  s WHERE fts MATC
c610: 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62 6d 32  H ? ORDER BY bm2
c620: 35 28 66 74 73 2c 20 31 30 2e 30 2c 20 35 2e 30  5(fts, 10.0, 5.0
c630: 29 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52  );.  SELECT * FR
c640: 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73  OM fts WHERE fts
c650: 20 4d 41 54 43 48 20 3f 20 41 4e 44 20 72 61 6e   MATCH ? AND ran
c660: 6b 20 4d 41 54 43 48 20 27 62 6d 32 35 28 31 30  k MATCH 'bm25(10
c670: 2e 30 2c 20 35 2e 30 29 27 20 4f 52 44 45 52 20  .0, 5.0)' ORDER 
c680: 42 59 20 72 61 6e 6b 3b 0a 3c 2f 63 6f 64 65 62  BY rank;.</codeb
c690: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 74  lock>..<p> The t
c6a0: 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63  able-valued func
c6b0: 74 69 6f 6e 20 73 79 6e 74 61 78 20 6d 61 79 20  tion syntax may 
c6c0: 61 6c 73 6f 20 62 65 20 75 73 65 64 20 74 6f 20  also be used to 
c6d0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
c6e0: 6e 61 74 69 76 65 0a 72 61 6e 6b 69 6e 67 20 66  native.ranking f
c6f0: 75 6e 63 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  unction. In this
c700: 20 63 61 73 65 20 74 68 65 20 74 65 78 74 20 64   case the text d
c710: 65 73 63 72 69 62 69 6e 67 20 74 68 65 20 72 61  escribing the ra
c720: 6e 6b 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  nking function s
c730: 68 6f 75 6c 64 0a 62 65 20 73 70 65 63 69 66 69  hould.be specifi
c740: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
c750: 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75   table-valued fu
c760: 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
c770: 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
c780: 68 72 65 65 0a 71 75 65 72 69 65 73 20 61 72 65  hree.queries are
c790: 20 65 71 75 69 76 61 6c 65 6e 74 3a 0a 0a 3c 63   equivalent:..<c
c7a0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45  odeblock>.  SELE
c7b0: 43 54 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48  CT * FROM fts WH
c7c0: 45 52 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20  ERE fts MATCH ? 
c7d0: 41 4e 44 20 72 61 6e 6b 20 4d 41 54 43 48 20 27  AND rank MATCH '
c7e0: 62 6d 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27  bm25(10.0, 5.0)'
c7f0: 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a   ORDER BY rank;.
c800: 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20    SELECT * FROM 
c810: 66 74 73 20 57 48 45 52 45 20 66 74 73 20 3d 20  fts WHERE fts = 
c820: 3f 20 41 4e 44 20 72 61 6e 6b 20 3d 20 27 62 6d  ? AND rank = 'bm
c830: 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27 20 4f  25(10.0, 5.0)' O
c840: 52 44 45 52 20 42 59 20 72 61 6e 6b 3b 0a 20 20  RDER BY rank;.  
c850: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66 74  SELECT * FROM ft
c860: 73 20 57 48 45 52 45 20 66 74 73 28 3f 2c 20 27  s WHERE fts(?, '
c870: 62 6d 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27  bm25(10.0, 5.0)'
c880: 29 20 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 3b  ) ORDER BY rank;
c890: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
c8a0: 70 3e 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d  p> The default m
c8b0: 61 70 70 69 6e 67 20 6f 66 20 74 68 65 20 72 61  apping of the ra
c8c0: 6e 6b 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 61 20  nk column for a 
c8d0: 74 61 62 6c 65 20 6d 61 79 20 62 65 20 6d 6f 64  table may be mod
c8e0: 69 66 69 65 64 20 0a 75 73 69 6e 67 20 74 68 65  ified .using the
c8f0: 20 5b 46 54 53 35 20 72 61 6e 6b 20 63 6f 6e 66   [FTS5 rank conf
c900: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c910: 5d 2e 0a 0a 3c 68 31 3e 53 70 65 63 69 61 6c 20  ]...<h1>Special 
c920: 49 4e 53 45 52 54 20 43 6f 6d 6d 61 6e 64 73 3c  INSERT Commands<
c930: 2f 68 31 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  /h1>..<h2 tags="
c940: 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65 20 6f  FTS5 automerge o
c950: 70 74 69 6f 6e 22 3e 54 68 65 20 27 61 75 74 6f  ption">The 'auto
c960: 6d 65 72 67 65 27 20 43 6f 6e 66 69 67 75 72 61  merge' Configura
c970: 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e  tion Option</h2>
c980: 0a 0a 3c 70 3e 0a 20 20 49 6e 73 74 65 61 64 20  ..<p>.  Instead 
c990: 6f 66 20 75 73 69 6e 67 20 61 20 73 69 6e 67 6c  of using a singl
c9a0: 65 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  e data structure
c9b0: 20 6f 6e 20 64 69 73 6b 20 74 6f 20 73 74 6f 72   on disk to stor
c9c0: 65 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 0a  e the full-text.
c9d0: 20 20 69 6e 64 65 78 2c 20 46 54 53 35 20 75 73    index, FTS5 us
c9e0: 65 73 20 61 20 73 65 72 69 65 73 20 6f 66 20 62  es a series of b
c9f0: 2d 74 72 65 65 73 2e 20 45 61 63 68 20 74 69 6d  -trees. Each tim
ca00: 65 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63 74  e a new transact
ca10: 69 6f 6e 20 69 73 0a 20 20 63 6f 6d 6d 69 74 74  ion is.  committ
ca20: 65 64 2c 20 61 20 6e 65 77 20 62 2d 74 72 65 65  ed, a new b-tree
ca30: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
ca40: 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
ca50: 63 6f 6d 6d 69 74 74 65 64 20 74 72 61 6e 73 61  committed transa
ca60: 63 74 69 6f 6e 0a 20 20 69 73 20 77 72 69 74 74  ction.  is writt
ca70: 65 6e 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  en into the data
ca80: 62 61 73 65 20 66 69 6c 65 2e 20 57 68 65 6e 20  base file. When 
ca90: 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  the full-text in
caa0: 64 65 78 20 69 73 20 71 75 65 72 69 65 64 2c 20  dex is queried, 
cab0: 65 61 63 68 0a 20 20 62 2d 74 72 65 65 20 6d 75  each.  b-tree mu
cac0: 73 74 20 62 65 20 71 75 65 72 69 65 64 20 69 6e  st be queried in
cad0: 64 69 76 69 64 75 61 6c 6c 79 20 61 6e 64 20 74  dividually and t
cae0: 68 65 20 72 65 73 75 6c 74 73 20 6d 65 72 67 65  he results merge
caf0: 64 20 62 65 66 6f 72 65 20 62 65 69 6e 67 0a 20  d before being. 
cb00: 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
cb10: 20 75 73 65 72 2e 0a 0a 3c 70 3e 0a 20 20 49 6e   user...<p>.  In
cb20: 20 6f 72 64 65 72 20 74 6f 20 70 72 65 76 65 6e   order to preven
cb30: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
cb40: 62 2d 74 72 65 65 73 20 69 6e 20 74 68 65 20 64  b-trees in the d
cb50: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 62 65 63  atabase from bec
cb60: 6f 6d 69 6e 67 20 74 6f 6f 0a 20 20 6c 61 72 67  oming too.  larg
cb70: 65 20 28 73 6c 6f 77 69 6e 67 20 64 6f 77 6e 20  e (slowing down 
cb80: 71 75 65 72 69 65 73 29 2c 20 73 6d 61 6c 6c 65  queries), smalle
cb90: 72 20 62 2d 74 72 65 65 73 20 61 72 65 20 70 65  r b-trees are pe
cba0: 72 69 6f 64 69 63 61 6c 6c 79 20 6d 65 72 67 65  riodically merge
cbb0: 64 20 69 6e 74 6f 0a 20 20 73 69 6e 67 6c 65 20  d into.  single 
cbc0: 6c 61 72 67 65 72 20 62 2d 74 72 65 65 73 20 63  larger b-trees c
cbd0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 61  ontaining the sa
cbe0: 6d 65 20 64 61 74 61 2e 20 42 79 20 64 65 66 61  me data. By defa
cbf0: 75 6c 74 2c 20 74 68 69 73 20 68 61 70 70 65 6e  ult, this happen
cc00: 73 0a 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  s.  automaticall
cc10: 79 20 77 69 74 68 69 6e 20 49 4e 53 45 52 54 2c  y within INSERT,
cc20: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
cc30: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  E statements tha
cc40: 74 20 6d 6f 64 69 66 79 20 74 68 65 0a 20 20 66  t modify the.  f
cc50: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e 20  ull-text index. 
cc60: 54 68 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20  The 'automerge' 
cc70: 70 61 72 61 6d 65 74 65 72 20 64 65 74 65 72 6d  parameter determ
cc80: 69 6e 65 73 20 68 6f 77 20 6d 61 6e 79 20 73 6d  ines how many sm
cc90: 61 6c 6c 65 72 0a 20 20 62 2d 74 72 65 65 73 20  aller.  b-trees 
cca0: 61 72 65 20 6d 65 72 67 65 64 20 74 6f 67 65 74  are merged toget
ccb0: 68 65 72 20 61 74 20 61 20 74 69 6d 65 2e 20 53  her at a time. S
ccc0: 65 74 74 69 6e 67 20 69 74 20 74 6f 20 61 20 73  etting it to a s
ccd0: 6d 61 6c 6c 20 76 61 6c 75 65 20 63 61 6e 0a 20  mall value can. 
cce0: 20 73 70 65 65 64 20 75 70 20 71 75 65 72 69 65   speed up querie
ccf0: 73 20 28 61 73 20 74 68 65 79 20 68 61 76 65 20  s (as they have 
cd00: 74 6f 20 71 75 65 72 79 20 61 6e 64 20 6d 65 72  to query and mer
cd10: 67 65 20 74 68 65 20 72 65 73 75 6c 74 73 20 66  ge the results f
cd20: 72 6f 6d 20 66 65 77 65 72 20 0a 20 20 62 2d 74  rom fewer .  b-t
cd30: 72 65 65 73 29 2c 20 62 75 74 20 63 61 6e 20 61  rees), but can a
cd40: 6c 73 6f 20 73 6c 6f 77 20 64 6f 77 6e 20 77 72  lso slow down wr
cd50: 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  iting to the dat
cd60: 61 62 61 73 65 20 28 61 73 20 65 61 63 68 20 49  abase (as each I
cd70: 4e 53 45 52 54 2c 0a 20 20 55 50 44 41 54 45 20  NSERT,.  UPDATE 
cd80: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
cd90: 65 6e 74 20 68 61 73 20 74 6f 20 64 6f 20 6d 6f  ent has to do mo
cda0: 72 65 20 77 6f 72 6b 20 61 73 20 70 61 72 74 20  re work as part 
cdb0: 6f 66 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  of the automatic
cdc0: 0a 20 20 6d 65 72 67 69 6e 67 20 70 72 6f 63 65  .  merging proce
cdd0: 73 73 29 2e 0a 0a 3c 70 3e 0a 20 20 45 61 63 68  ss)...<p>.  Each
cde0: 20 6f 66 20 74 68 65 20 62 2d 74 72 65 65 73 20   of the b-trees 
cdf0: 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65  that make up the
ce00: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
ce10: 20 69 73 20 61 73 73 69 67 6e 65 64 20 74 6f 20   is assigned to 
ce20: 61 20 22 6c 65 76 65 6c 22 0a 20 20 62 61 73 65  a "level".  base
ce30: 64 20 6f 6e 20 69 74 73 20 73 69 7a 65 2e 20 4c  d on its size. L
ce40: 65 76 65 6c 2d 30 20 62 2d 74 72 65 65 73 20 61  evel-0 b-trees a
ce50: 72 65 20 74 68 65 20 73 6d 61 6c 6c 65 73 74 2c  re the smallest,
ce60: 20 61 73 20 74 68 65 79 20 63 6f 6e 74 61 69 6e   as they contain
ce70: 20 74 68 65 0a 20 20 63 6f 6e 74 65 6e 74 73 20   the.  contents 
ce80: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  of a single tran
ce90: 73 61 63 74 69 6f 6e 2e 20 48 69 67 68 65 72 20  saction. Higher 
cea0: 6c 65 76 65 6c 20 62 2d 74 72 65 65 73 20 61 72  level b-trees ar
ceb0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  e the result of.
cec0: 20 20 6d 65 72 67 69 6e 67 20 74 77 6f 20 6f 72    merging two or
ced0: 20 6d 6f 72 65 20 6c 65 76 65 6c 2d 30 20 62 2d   more level-0 b-
cee0: 74 72 65 65 73 20 74 6f 67 65 74 68 65 72 20 61  trees together a
cef0: 6e 64 20 73 6f 20 74 68 65 79 20 61 72 65 20 6c  nd so they are l
cf00: 61 72 67 65 72 2e 20 46 54 53 35 0a 20 20 62 65  arger. FTS5.  be
cf10: 67 69 6e 73 20 74 6f 20 6d 65 72 67 65 20 62 2d  gins to merge b-
cf20: 74 72 65 65 73 20 74 6f 67 65 74 68 65 72 20 6f  trees together o
cf30: 6e 63 65 20 74 68 65 72 65 20 65 78 69 73 74 20  nce there exist 
cf40: 3c 69 3e 4d 3c 2f 69 3e 20 6f 72 20 6d 6f 72 65  <i>M</i> or more
cf50: 20 62 2d 74 72 65 65 73 20 0a 20 20 77 69 74 68   b-trees .  with
cf60: 20 74 68 65 20 73 61 6d 65 20 6c 65 76 65 6c 2c   the same level,
cf70: 20 77 68 65 72 65 20 3c 69 3e 4d 3c 2f 69 3e 20   where <i>M</i> 
cf80: 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
cf90: 74 68 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20  the 'automerge' 
cfa0: 0a 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 0a 3c  .  parameter...<
cfb0: 70 3e 0a 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  p>.  The maximum
cfc0: 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 20 66   allowed value f
cfd0: 6f 72 20 74 68 65 20 27 61 75 74 6f 6d 65 72 67  or the 'automerg
cfe0: 65 27 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e' parameter is 
cff0: 31 36 2e 20 54 68 65 20 64 65 66 61 75 6c 74 0a  16. The default.
d000: 20 20 76 61 6c 75 65 20 69 73 20 34 2e 20 53 65    value is 4. Se
d010: 74 74 69 6e 67 20 74 68 65 20 27 61 75 74 6f 6d  tting the 'autom
d020: 65 72 67 65 27 20 70 61 72 61 6d 65 74 65 72 20  erge' parameter 
d030: 74 6f 20 30 20 64 69 73 61 62 6c 65 73 20 74 68  to 0 disables th
d040: 65 20 61 75 74 6f 6d 61 74 69 63 20 0a 20 20 69  e automatic .  i
d050: 6e 63 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 69  ncremental mergi
d060: 6e 67 20 6f 66 20 62 2d 74 72 65 65 73 20 61 6c  ng of b-trees al
d070: 74 6f 67 65 74 68 65 72 2e 0a 0a 3c 63 6f 64 65  together...<code
d080: 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20  block>.  INSERT 
d090: 49 4e 54 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b  INTO ft(ft, rank
d0a0: 29 20 56 41 4c 55 45 53 28 27 61 75 74 6f 6d 65  ) VALUES('autome
d0b0: 72 67 65 27 2c 20 38 29 3b 0a 3c 2f 63 6f 64 65  rge', 8);.</code
d0c0: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 3e 54 68 65 20  block>..<h2>The 
d0d0: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 43 6f  'crisismerge' Co
d0e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
d0f0: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  on</h2>..<p>The 
d100: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 6f 70  'crisismerge' op
d110: 74 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72 20  tion is similar 
d120: 74 6f 20 27 61 75 74 6f 6d 65 72 67 65 27 2c 20  to 'automerge', 
d130: 69 6e 20 74 68 61 74 20 69 74 20 64 65 74 65 72  in that it deter
d140: 6d 69 6e 65 73 0a 68 6f 77 20 61 6e 64 20 68 6f  mines.how and ho
d150: 77 20 6f 66 74 65 6e 20 74 68 65 20 63 6f 6d 70  w often the comp
d160: 6f 6e 65 6e 74 20 62 2d 74 72 65 65 73 20 74 68  onent b-trees th
d170: 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65 20 66  at make up the f
d180: 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 61  ull-text index a
d190: 72 65 0a 6d 65 72 67 65 64 20 74 6f 67 65 74 68  re.merged togeth
d1a0: 65 72 2e 20 4f 6e 63 65 20 74 68 65 72 65 20 65  er. Once there e
d1b0: 78 69 73 74 20 3c 69 3e 43 3c 2f 69 3e 20 6f 72  xist <i>C</i> or
d1c0: 20 6d 6f 72 65 20 62 2d 74 72 65 65 73 20 6f 6e   more b-trees on
d1d0: 20 61 20 73 69 6e 67 6c 65 20 6c 65 76 65 6c 0a   a single level.
d1e0: 77 69 74 68 69 6e 20 74 68 65 20 66 75 6c 6c 2d  within the full-
d1f0: 74 65 78 74 20 69 6e 64 65 78 2c 20 77 68 65 72  text index, wher
d200: 65 20 3c 69 3e 43 3c 2f 69 3e 20 69 73 20 74 68  e <i>C</i> is th
d210: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 27  e value of the '
d220: 63 72 69 73 69 73 6d 65 72 67 65 27 0a 6f 70 74  crisismerge'.opt
d230: 69 6f 6e 2c 20 61 6c 6c 20 62 2d 74 72 65 65 73  ion, all b-trees
d240: 20 6f 6e 20 74 68 65 20 6c 65 76 65 6c 20 61 72   on the level ar
d250: 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 6d 65  e immediately me
d260: 72 67 65 64 20 69 6e 74 6f 20 61 20 73 69 6e 67  rged into a sing
d270: 6c 65 20 62 2d 74 72 65 65 2e 0a 0a 3c 70 3e 54  le b-tree...<p>T
d280: 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  he difference be
d290: 74 77 65 65 6e 20 74 68 69 73 20 6f 70 74 69 6f  tween this optio
d2a0: 6e 20 61 6e 64 20 74 68 65 20 27 61 75 74 6f 6d  n and the 'autom
d2b0: 65 72 67 65 27 20 6f 70 74 69 6f 6e 20 69 73 20  erge' option is 
d2c0: 74 68 61 74 20 77 68 65 6e 0a 74 68 65 20 27 61  that when.the 'a
d2d0: 75 74 6f 6d 65 72 67 65 27 20 6c 69 6d 69 74 20  utomerge' limit 
d2e0: 69 73 20 72 65 61 63 68 65 64 20 46 54 53 35 20  is reached FTS5 
d2f0: 6f 6e 6c 79 20 62 65 67 69 6e 73 20 74 6f 20 6d  only begins to m
d300: 65 72 67 65 20 74 68 65 20 62 2d 74 72 65 65 73  erge the b-trees
d310: 0a 74 6f 67 65 74 68 65 72 2e 20 4d 6f 73 74 20  .together. Most 
d320: 6f 66 20 74 68 65 20 77 6f 72 6b 20 69 73 20 70  of the work is p
d330: 65 72 66 6f 72 6d 65 64 20 61 73 20 70 61 72 74  erformed as part
d340: 20 6f 66 20 73 75 62 73 65 71 75 65 6e 74 20 49   of subsequent I
d350: 4e 53 45 52 54 2c 20 0a 55 50 44 41 54 45 20 6f  NSERT, .UPDATE o
d360: 72 20 44 45 4c 45 54 45 20 6f 70 65 72 61 74 69  r DELETE operati
d370: 6f 6e 73 2e 20 57 68 65 72 65 61 73 20 77 68 65  ons. Whereas whe
d380: 6e 20 74 68 65 20 27 63 72 69 73 69 73 6d 65 72  n the 'crisismer
d390: 67 65 27 20 6c 69 6d 69 74 20 69 73 20 72 65 61  ge' limit is rea
d3a0: 63 68 65 64 2c 0a 74 68 65 20 6f 66 66 65 6e 64  ched,.the offend
d3b0: 69 6e 67 20 62 2d 74 72 65 65 73 20 61 72 65 20  ing b-trees are 
d3c0: 61 6c 6c 20 6d 65 72 67 65 64 20 69 6d 6d 65 64  all merged immed
d3d0: 69 61 74 65 6c 79 2e 20 54 68 69 73 20 6d 65 61  iately. This mea
d3e0: 6e 73 20 74 68 61 74 20 61 6e 20 49 4e 53 45 52  ns that an INSER
d3f0: 54 2c 0a 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T,.UPDATE or DEL
d400: 45 54 45 20 74 68 61 74 20 74 72 69 67 67 65 72  ETE that trigger
d410: 73 20 61 20 63 72 69 73 69 73 2d 6d 65 72 67 65  s a crisis-merge
d420: 20 6d 61 79 20 74 61 6b 65 20 61 20 6c 6f 6e 67   may take a long
d430: 20 74 69 6d 65 20 74 6f 20 0a 63 6f 6d 70 6c 65   time to .comple
d440: 74 65 2e 0a 0a 3c 70 3e 54 68 65 20 64 65 66 61  te...<p>The defa
d450: 75 6c 74 20 27 63 72 69 73 69 73 6d 65 72 67 65  ult 'crisismerge
d460: 27 20 76 61 6c 75 65 20 69 73 20 31 36 2e 20 54  ' value is 16. T
d470: 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 78 69 6d  here is no maxim
d480: 75 6d 20 6c 69 6d 69 74 2e 20 41 74 74 65 6d 70  um limit. Attemp
d490: 74 69 6e 67 0a 74 6f 20 73 65 74 20 74 68 65 20  ting.to set the 
d4a0: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 70 61  'crisismerge' pa
d4b0: 72 61 6d 65 74 65 72 20 74 6f 20 61 20 76 61 6c  rameter to a val
d4c0: 75 65 20 6f 66 20 30 20 6f 72 20 31 20 69 73 20  ue of 0 or 1 is 
d4d0: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 73 65  equivalent to.se
d4e0: 74 74 69 6e 67 20 69 74 20 74 6f 20 74 68 65 20  tting it to the 
d4f0: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 28 31  default value (1
d500: 36 29 2e 20 49 74 20 69 73 20 61 6e 20 65 72 72  6). It is an err
d510: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 20 74 6f  or to attempt to
d520: 20 73 65 74 20 74 68 65 0a 27 63 72 69 73 69 73   set the.'crisis
d530: 6d 65 72 67 65 27 20 6f 70 74 69 6f 6e 20 74 6f  merge' option to
d540: 20 61 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   a negative valu
d550: 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  e...<codeblock>.
d560: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74    INSERT INTO ft
d570: 28 66 74 2c 20 72 61 6e 6b 29 20 56 41 4c 55 45  (ft, rank) VALUE
d580: 53 28 27 63 72 69 73 69 73 6d 65 72 67 65 27 2c  S('crisismerge',
d590: 20 31 36 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63   16);.</codebloc
d5a0: 6b 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  k>..<h2 tags="FT
d5b0: 53 35 20 64 65 6c 65 74 65 20 63 6f 6d 6d 61 6e  S5 delete comman
d5c0: 64 22 3e 54 68 65 20 27 64 65 6c 65 74 65 27 20  d">The 'delete' 
d5d0: 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70  Command</h2>..<p
d5e0: 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69  > This command i
d5f0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
d600: 20 77 69 74 68 20 5b 46 54 53 35 20 65 78 74 65   with [FTS5 exte
d610: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62  rnal content tab
d620: 6c 65 73 20 7c 0a 65 78 74 65 72 6e 61 6c 20 63  les |.external c
d630: 6f 6e 74 65 6e 74 5d 20 61 6e 64 20 5b 46 54 53  ontent] and [FTS
d640: 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61  5 contentless ta
d650: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 6c 65  bles | contentle
d660: 73 73 5d 20 74 61 62 6c 65 73 2e 20 49 74 0a 69  ss] tables. It.i
d670: 73 20 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65  s used to delete
d680: 20 74 68 65 20 69 6e 64 65 78 20 65 6e 74 72 69   the index entri
d690: 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  es associated wi
d6a0: 74 68 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  th a single row 
d6b0: 66 72 6f 6d 20 74 68 65 0a 66 75 6c 6c 2d 74 65  from the.full-te
d6c0: 78 74 20 69 6e 64 65 78 2e 20 54 68 69 73 20 63  xt index. This c
d6d0: 6f 6d 6d 61 6e 64 20 61 6e 64 20 74 68 65 20 5b  ommand and the [
d6e0: 46 54 53 35 20 64 65 6c 65 74 65 2d 61 6c 6c 20  FTS5 delete-all 
d6f0: 63 6f 6d 6d 61 6e 64 20 7c 20 64 65 6c 65 74 65  command | delete
d700: 2d 61 6c 6c 5d 0a 63 6f 6d 6d 61 6e 64 20 61 72  -all].command ar
d710: 65 20 74 68 65 20 6f 6e 6c 79 20 77 61 79 73 20  e the only ways 
d720: 74 6f 20 72 65 6d 6f 76 65 20 65 6e 74 72 69 65  to remove entrie
d730: 73 20 66 72 6f 6d 20 74 68 65 20 66 75 6c 6c 2d  s from the full-
d740: 74 65 78 74 20 69 6e 64 65 78 20 6f 66 20 61 0a  text index of a.
d750: 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c  contentless tabl
d760: 65 2e 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65 72  e...<p> In order
d770: 20 74 6f 20 75 73 65 20 74 68 69 73 20 63 6f 6d   to use this com
d780: 6d 61 6e 64 20 74 6f 20 64 65 6c 65 74 65 20 61  mand to delete a
d790: 20 72 6f 77 2c 20 74 68 65 20 74 65 78 74 20 76   row, the text v
d7a0: 61 6c 75 65 20 27 64 65 6c 65 74 65 27 20 0a 6d  alue 'delete' .m
d7b0: 75 73 74 20 62 65 20 69 6e 73 65 72 74 65 64 20  ust be inserted 
d7c0: 69 6e 74 6f 20 74 68 65 20 73 70 65 63 69 61 6c  into the special
d7d0: 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20 74 68 65   column with the
d7e0: 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 20 74 68   same name as th
d7f0: 65 20 74 61 62 6c 65 2e 0a 54 68 65 20 72 6f 77  e table..The row
d800: 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 74 6f  id of the row to
d810: 20 64 65 6c 65 74 65 20 69 73 20 69 6e 73 65 72   delete is inser
d820: 74 65 64 20 69 6e 74 6f 20 74 68 65 20 72 6f 77  ted into the row
d830: 69 64 20 63 6f 6c 75 6d 6e 2e 20 54 68 65 0a 76  id column. The.v
d840: 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69  alues inserted i
d850: 6e 74 6f 20 74 68 65 20 6f 74 68 65 72 20 63 6f  nto the other co
d860: 6c 75 6d 6e 73 20 6d 75 73 74 20 6d 61 74 63 68  lumns must match
d870: 20 74 68 65 20 76 61 6c 75 65 73 20 63 75 72 72   the values curr
d880: 65 6e 74 6c 79 0a 73 74 6f 72 65 64 20 69 6e 20  ently.stored in 
d890: 74 68 65 20 74 61 62 6c 65 2e 20 46 6f 72 20 65  the table. For e
d8a0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
d8b0: 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 49 6e 73  ock>.  <i>-- Ins
d8c0: 65 72 74 20 61 20 72 6f 77 20 77 69 74 68 20 72  ert a row with r
d8d0: 6f 77 69 64 3d 31 34 20 69 6e 74 6f 20 74 68 65  owid=14 into the
d8e0: 20 66 74 73 35 20 74 61 62 6c 65 2e 3c 2f 69 3e   fts5 table.</i>
d8f0: 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66  .  INSERT INTO f
d900: 74 28 72 6f 77 69 64 2c 20 61 2c 20 62 2c 20 63  t(rowid, a, b, c
d910: 29 20 56 41 4c 55 45 53 28 31 34 2c 20 24 61 2c  ) VALUES(14, $a,
d920: 20 24 62 2c 20 24 63 29 3b 0a 20 20 0a 20 20 3c   $b, $c);.  .  <
d930: 69 3e 2d 2d 20 52 65 6d 6f 76 65 20 74 68 65 20  i>-- Remove the 
d940: 73 61 6d 65 20 72 6f 77 20 66 72 6f 6d 20 74 68  same row from th
d950: 65 20 66 74 73 35 20 74 61 62 6c 65 2e 3c 2f 69  e fts5 table.</i
d960: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
d970: 66 74 28 66 74 2c 20 72 6f 77 69 64 2c 20 61 2c  ft(ft, rowid, a,
d980: 20 62 2c 20 63 29 20 56 41 4c 55 45 53 28 27 64   b, c) VALUES('d
d990: 65 6c 65 74 65 27 2c 20 31 34 2c 20 24 61 2c 20  elete', 14, $a, 
d9a0: 24 62 2c 20 24 63 29 3b 0a 3c 2f 63 6f 64 65 62  $b, $c);.</codeb
d9b0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 66 20 74 68  lock>..<p> If th
d9c0: 65 20 76 61 6c 75 65 73 20 22 69 6e 73 65 72 74  e values "insert
d9d0: 65 64 22 20 69 6e 74 6f 20 74 68 65 20 74 65 78  ed" into the tex
d9e0: 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 70 61 72  t columns as par
d9f0: 74 20 6f 66 20 61 20 27 64 65 6c 65 74 65 27 0a  t of a 'delete'.
da00: 63 6f 6d 6d 61 6e 64 20 61 72 65 20 6e 6f 74 20  command are not 
da10: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 6f 73  the same as thos
da20: 65 20 63 75 72 72 65 6e 74 6c 79 20 73 74 6f 72  e currently stor
da30: 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 74 61  ed within the ta
da40: 62 6c 65 2c 20 74 68 65 0a 72 65 73 75 6c 74 73  ble, the.results
da50: 20 6d 61 79 20 62 65 20 75 6e 70 72 65 64 69 63   may be unpredic
da60: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 54 68 65 20  table...<p> The 
da70: 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 69 73 20  reason for this 
da80: 69 73 20 65 61 73 79 20 74 6f 20 75 6e 64 65 72  is easy to under
da90: 73 74 61 6e 64 3a 20 57 68 65 6e 20 61 20 64 6f  stand: When a do
daa0: 63 75 6d 65 6e 74 20 69 73 20 69 6e 73 65 72 74  cument is insert
dab0: 65 64 0a 69 6e 74 6f 20 74 68 65 20 46 54 53 35  ed.into the FTS5
dac0: 20 74 61 62 6c 65 2c 20 61 6e 20 65 6e 74 72 79   table, an entry
dad0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
dae0: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
daf0: 20 74 6f 20 72 65 63 6f 72 64 20 74 68 65 0a 70   to record the.p
db00: 6f 73 69 74 69 6f 6e 20 6f 66 20 65 61 63 68 20  osition of each 
db10: 74 6f 6b 65 6e 20 77 69 74 68 69 6e 20 74 68 65  token within the
db20: 20 6e 65 77 20 64 6f 63 75 6d 65 6e 74 2e 20 57   new document. W
db30: 68 65 6e 20 61 20 64 6f 63 75 6d 65 6e 74 20 69  hen a document i
db40: 73 20 72 65 6d 6f 76 65 64 2c 0a 74 68 65 20 6f  s removed,.the o
db50: 72 69 67 69 6e 61 6c 20 64 61 74 61 20 69 73 20  riginal data is 
db60: 72 65 71 75 69 72 65 64 20 69 6e 20 6f 72 64 65  required in orde
db70: 72 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  r to determine t
db80: 68 65 20 73 65 74 20 6f 66 20 65 6e 74 72 69 65  he set of entrie
db90: 73 20 74 68 61 74 0a 6e 65 65 64 20 74 6f 20 62  s that.need to b
dba0: 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 74  e removed from t
dbb0: 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he full-text ind
dbc0: 65 78 2e 20 53 6f 20 69 66 20 74 68 65 20 64 61  ex. So if the da
dbd0: 74 61 20 73 75 70 70 6c 69 65 64 20 74 6f 20 46  ta supplied to F
dbe0: 54 53 35 0a 77 68 65 6e 20 61 20 72 6f 77 20 69  TS5.when a row i
dbf0: 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
dc00: 74 68 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20  this command is 
dc10: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
dc20: 68 61 74 20 75 73 65 64 20 74 6f 0a 64 65 74 65  hat used to.dete
dc30: 72 6d 69 6e 65 20 74 68 65 20 73 65 74 20 6f 66  rmine the set of
dc40: 20 74 6f 6b 65 6e 20 69 6e 73 74 61 6e 63 65 73   token instances
dc50: 20 77 68 65 6e 20 69 74 20 77 61 73 20 69 6e 73   when it was ins
dc60: 65 72 74 65 64 2c 20 73 6f 6d 65 20 66 75 6c 6c  erted, some full
dc70: 2d 74 65 78 74 20 0a 69 6e 64 65 78 20 65 6e 74  -text .index ent
dc80: 72 69 65 73 20 6d 61 79 20 6e 6f 74 20 62 65 20  ries may not be 
dc90: 63 6f 72 72 65 63 74 6c 79 20 64 65 6c 65 74 65  correctly delete
dca0: 64 2c 20 6f 72 20 46 54 53 35 20 6d 61 79 20 74  d, or FTS5 may t
dcb0: 72 79 20 74 6f 20 72 65 6d 6f 76 65 20 69 6e 64  ry to remove ind
dcc0: 65 78 20 0a 65 6e 74 72 69 65 73 20 74 68 61 74  ex .entries that
dcd0: 20 64 6f 20 6e 6f 74 20 65 78 69 73 74 2e 20 54   do not exist. T
dce0: 68 69 73 20 63 61 6e 20 6c 65 61 76 65 20 74 68  his can leave th
dcf0: 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65  e full-text inde
dd00: 78 20 69 6e 20 61 6e 0a 75 6e 70 72 65 64 69 63  x in an.unpredic
dd10: 74 61 62 6c 65 20 73 74 61 74 65 2c 20 6d 61 6b  table state, mak
dd20: 69 6e 67 20 66 75 74 75 72 65 20 71 75 65 72 79  ing future query
dd30: 20 72 65 73 75 6c 74 73 20 75 6e 72 65 6c 69 61   results unrelia
dd40: 62 6c 65 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22  ble...<h2 tags="
dd50: 46 54 53 35 20 64 65 6c 65 74 65 2d 61 6c 6c 20  FTS5 delete-all 
dd60: 63 6f 6d 6d 61 6e 64 22 3e 54 68 65 20 27 64 65  command">The 'de
dd70: 6c 65 74 65 2d 61 6c 6c 27 20 43 6f 6d 6d 61 6e  lete-all' Comman
dd80: 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73  d</h2>..<p> This
dd90: 20 63 6f 6d 6d 61 6e 64 20 69 73 20 6f 6e 6c 79   command is only
dda0: 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68 20   available with 
ddb0: 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c 20 63  [FTS5 external c
ddc0: 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20 7c 0a  ontent tables |.
ddd0: 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74  external content
dde0: 5d 20 61 6e 64 20 5b 46 54 53 35 20 63 6f 6e 74  ] and [FTS5 cont
ddf0: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20 7c  entless tables |
de00: 20 63 6f 6e 74 65 6e 74 6c 65 73 73 5d 20 74 61   contentless] ta
de10: 62 6c 65 73 2e 20 49 74 0a 64 65 6c 65 74 65 73  bles. It.deletes
de20: 20 61 6c 6c 20 65 6e 74 72 69 65 73 20 66 72 6f   all entries fro
de30: 6d 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  m the full-text 
de40: 69 6e 64 65 78 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  index...<codeblo
de50: 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  ck>.  INSERT INT
de60: 4f 20 66 74 28 66 74 29 20 56 41 4c 55 45 53 28  O ft(ft) VALUES(
de70: 27 64 65 6c 65 74 65 2d 61 6c 6c 27 29 3b 0a 3c  'delete-all');.<
de80: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 32  /codeblock>..<h2
de90: 3e 54 68 65 20 27 69 6e 74 65 67 72 69 74 79 2d  >The 'integrity-
dea0: 63 68 65 63 6b 27 20 43 6f 6d 6d 61 6e 64 3c 2f  check' Command</
deb0: 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f  h2>..<p> This co
dec0: 6d 6d 61 6e 64 20 69 73 20 75 73 65 64 20 74 6f  mmand is used to
ded0: 20 76 65 72 69 66 79 20 74 68 61 74 20 74 68 65   verify that the
dee0: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
def0: 20 69 73 20 63 6f 6e 73 69 73 74 65 6e 74 20 0a   is consistent .
df00: 77 69 74 68 20 74 68 65 20 63 6f 6e 74 65 6e 74  with the content
df10: 73 20 6f 66 20 74 68 65 20 46 54 53 35 20 74 61  s of the FTS5 ta
df20: 62 6c 65 20 6f 72 20 5b 46 54 53 35 20 65 78 74  ble or [FTS5 ext
df30: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61  ernal content ta
df40: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 20 0a  bles | content .
df50: 74 61 62 6c 65 5d 2e 20 49 74 20 69 73 20 6e 6f  table]. It is no
df60: 74 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68  t available with
df70: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
df80: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
df90: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 5d 2e  entless tables].
dfa0: 0a 0a 3c 70 3e 54 68 65 20 69 6e 74 65 67 72 69  ..<p>The integri
dfb0: 74 79 2d 63 68 65 63 6b 20 63 6f 6d 6d 61 6e 64  ty-check command
dfc0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 69   is invoked by i
dfd0: 6e 73 65 72 74 69 6e 67 20 74 68 65 20 74 65 78  nserting the tex
dfe0: 74 20 76 61 6c 75 65 0a 27 69 6e 74 65 67 72 69  t value.'integri
dff0: 74 79 2d 63 68 65 63 6b 27 20 69 6e 74 6f 20 74  ty-check' into t
e000: 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6c 75 6d  he special colum
e010: 6e 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  n with the same 
e020: 6e 61 6d 65 20 61 73 20 74 68 65 20 46 54 53 35  name as the FTS5
e030: 0a 74 61 62 6c 65 2e 20 46 6f 72 20 65 78 61 6d  .table. For exam
e040: 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ple:..<codeblock
e050: 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  >.  INSERT INTO 
e060: 66 74 28 66 74 29 20 56 41 4c 55 45 53 28 27 69  ft(ft) VALUES('i
e070: 6e 74 65 67 72 69 74 79 2d 63 68 65 63 6b 27 29  ntegrity-check')
e080: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
e090: 3c 70 3e 49 66 20 74 68 65 20 66 75 6c 6c 2d 74  <p>If the full-t
e0a0: 65 78 74 20 69 6e 64 65 78 20 69 73 20 63 6f 6e  ext index is con
e0b0: 73 69 73 74 65 6e 74 20 77 69 74 68 20 74 68 65  sistent with the
e0c0: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
e0d0: 20 74 61 62 6c 65 2c 20 74 68 65 0a 49 4e 53 45   table, the.INSE
e0e0: 52 54 20 75 73 65 64 20 74 6f 20 69 6e 76 6f 6b  RT used to invok
e0f0: 65 20 74 68 65 20 69 6e 74 65 67 72 69 74 79 2d  e the integrity-
e100: 63 68 65 63 6b 20 63 6f 6d 6d 61 6e 64 20 73 75  check command su
e110: 63 63 65 65 64 73 2e 20 4f 72 2c 20 69 66 20 61  cceeds. Or, if a
e120: 6e 79 0a 64 69 73 63 72 65 70 61 6e 63 79 20 69  ny.discrepancy i
e130: 73 20 66 6f 75 6e 64 2c 20 69 74 20 66 61 69 6c  s found, it fail
e140: 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54  s with an [SQLIT
e150: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 5d 20  E_CORRUPT_VTAB] 
e160: 65 72 72 6f 72 2e 0a 0a 3c 68 32 20 74 61 67 73  error...<h2 tags
e170: 3d 22 46 54 53 35 20 6d 65 72 67 65 20 63 6f 6d  ="FTS5 merge com
e180: 6d 61 6e 64 22 3e 54 68 65 20 27 6d 65 72 67 65  mand">The 'merge
e190: 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a  ' Command</h2>..
e1a0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e  <codeblock>.  IN
e1b0: 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c  SERT INTO ft(ft,
e1c0: 20 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 6d   rank) VALUES('m
e1d0: 65 72 67 65 27 2c 20 35 30 30 29 3b 0a 3c 2f 63  erge', 500);.</c
e1e0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
e1f0: 68 69 73 20 63 6f 6d 6d 61 6e 64 20 6d 65 72 67  his command merg
e200: 65 73 20 62 2d 74 72 65 65 20 73 74 72 75 63 74  es b-tree struct
e210: 75 72 65 73 20 74 6f 67 65 74 68 65 72 20 75 6e  ures together un
e220: 74 69 6c 20 72 6f 75 67 68 6c 79 20 4e 20 70 61  til roughly N pa
e230: 67 65 73 0a 6f 66 20 6d 65 72 67 65 64 20 64 61  ges.of merged da
e240: 74 61 20 68 61 76 65 20 62 65 65 6e 20 77 72 69  ta have been wri
e250: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
e260: 62 61 73 65 2c 20 77 68 65 72 65 20 4e 20 69 73  base, where N is
e270: 20 74 68 65 20 61 62 73 6f 6c 75 74 65 0a 76 61   the absolute.va
e280: 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d  lue of the param
e290: 65 74 65 72 20 73 70 65 63 69 66 69 65 64 20 61  eter specified a
e2a0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 27 6d  s part of the 'm
e2b0: 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 2e 20 54  erge' command. T
e2c0: 68 65 20 73 69 7a 65 20 6f 66 0a 65 61 63 68 20  he size of.each 
e2d0: 70 61 67 65 20 69 73 20 61 73 20 63 6f 6e 66 69  page is as confi
e2e0: 67 75 72 65 64 20 62 79 20 74 68 65 20 5b 46 54  gured by the [FT
e2f0: 53 35 20 70 67 73 7a 20 6f 70 74 69 6f 6e 5d 2e  S5 pgsz option].
e300: 0a 0a 3c 70 3e 20 49 66 20 74 68 65 20 70 61 72  ..<p> If the par
e310: 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 73 69  ameter is a posi
e320: 74 69 76 65 20 76 61 6c 75 65 2c 20 42 2d 74 72  tive value, B-tr
e330: 65 65 20 73 74 72 75 63 74 75 72 65 73 20 61 72  ee structures ar
e340: 65 20 6f 6e 6c 79 20 65 6c 69 67 69 62 6c 65 0a  e only eligible.
e350: 66 6f 72 20 6d 65 72 67 69 6e 67 20 69 66 20 6f  for merging if o
e360: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
e370: 69 6e 67 20 69 73 20 74 72 75 65 3a 0a 0a 3c 75  ing is true:..<u
e380: 6c 3e 0a 20 20 3c 6c 69 3e 20 54 68 65 72 65 20  l>.  <li> There 
e390: 61 72 65 20 55 20 6f 72 20 6d 6f 72 65 20 73 75  are U or more su
e3a0: 63 68 20 62 2d 74 72 65 65 73 20 6f 6e 20 61 0a  ch b-trees on a.
e3b0: 20 20 20 20 20 20 20 73 69 6e 67 6c 65 20 6c 65         single le
e3c0: 76 65 6c 20 28 73 65 65 20 74 68 65 20 64 6f 63  vel (see the doc
e3d0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74  umentation for t
e3e0: 68 65 20 5b 46 54 53 35 20 61 75 74 6f 6d 65 72  he [FTS5 automer
e3f0: 67 65 20 6f 70 74 69 6f 6e 5d 0a 20 20 20 20 20  ge option].     
e400: 20 20 66 6f 72 20 61 6e 20 65 78 70 6c 61 6e 61    for an explana
e410: 74 69 6f 6e 20 6f 66 20 62 2d 74 72 65 65 20 6c  tion of b-tree l
e420: 65 76 65 6c 73 29 2c 20 77 68 65 72 65 20 55 20  evels), where U 
e430: 69 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 73  is the value ass
e440: 69 67 6e 65 64 0a 20 20 20 20 20 20 20 74 6f 20  igned.       to 
e450: 74 68 65 20 5b 46 54 53 35 20 75 73 65 72 6d 65  the [FTS5 userme
e460: 72 67 65 20 6f 70 74 69 6f 6e 5d 20 6f 70 74 69  rge option] opti
e470: 6f 6e 2e 0a 20 20 3c 6c 69 3e 20 41 20 6d 65 72  on..  <li> A mer
e480: 67 65 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ge has already b
e490: 65 65 6e 20 73 74 61 72 74 65 64 20 28 70 65 72  een started (per
e4a0: 68 61 70 73 20 62 79 20 61 20 27 6d 65 72 67 65  haps by a 'merge
e4b0: 27 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 0a 20  ' command that. 
e4c0: 20 20 20 20 20 20 73 70 65 63 69 66 69 65 64 20        specified 
e4d0: 61 20 6e 65 67 61 74 69 76 65 20 70 61 72 61 6d  a negative param
e4e0: 65 74 65 72 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  eter)..</ul>..<p
e4f0: 3e 20 49 74 20 69 73 20 70 6f 73 73 69 62 6c 65  > It is possible
e500: 20 74 6f 20 74 65 6c 6c 20 77 68 65 74 68 65 72   to tell whether
e510: 20 6f 72 20 6e 6f 74 20 74 68 65 20 27 6d 65 72   or not the 'mer
e520: 67 65 27 20 63 6f 6d 6d 61 6e 64 20 66 6f 75 6e  ge' command foun
e530: 64 20 61 6e 79 20 0a 62 2d 74 72 65 65 73 20 74  d any .b-trees t
e540: 6f 20 6d 65 72 67 65 20 74 6f 67 65 74 68 65 72  o merge together
e550: 20 62 79 20 63 68 65 63 6b 69 6e 67 20 74 68 65   by checking the
e560: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e570: 62 79 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f  by the.[sqlite3_
e580: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
e590: 20 41 50 49 20 62 65 66 6f 72 65 20 61 6e 64 20   API before and 
e5a0: 61 66 74 65 72 20 74 68 65 20 63 6f 6d 6d 61 6e  after the comman
e5b0: 64 20 69 73 20 65 78 65 63 75 74 65 64 2e 20 49  d is executed. I
e5c0: 66 0a 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  f.the difference
e5d0: 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
e5e0: 20 76 61 6c 75 65 73 20 69 73 20 32 20 6f 72 20   values is 2 or 
e5f0: 67 72 65 61 74 65 72 2c 20 74 68 65 6e 20 77 6f  greater, then wo
e600: 72 6b 20 77 61 73 20 70 65 72 66 6f 72 6d 65 64  rk was performed
e610: 2e 0a 49 66 20 74 68 65 20 64 69 66 66 65 72 65  ..If the differe
e620: 6e 63 65 20 69 73 20 6c 65 73 73 20 74 68 61 6e  nce is less than
e630: 20 32 2c 20 74 68 65 6e 20 74 68 65 20 27 6d 65   2, then the 'me
e640: 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 77 61 73  rge' command was
e650: 20 61 20 6e 6f 2d 6f 70 2e 20 49 6e 20 74 68 69   a no-op. In thi
e660: 73 0a 63 61 73 65 20 74 68 65 72 65 20 69 73 20  s.case there is 
e670: 6e 6f 20 72 65 61 73 6f 6e 20 74 6f 20 65 78 65  no reason to exe
e680: 63 75 74 65 20 74 68 65 20 73 61 6d 65 20 27 6d  cute the same 'm
e690: 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 61 67  erge' command ag
e6a0: 61 69 6e 2c 20 61 74 20 6c 65 61 73 74 0a 75 6e  ain, at least.un
e6b0: 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 46 54  til after the FT
e6c0: 53 20 74 61 62 6c 65 20 69 73 20 6e 65 78 74 20  S table is next 
e6d0: 75 70 64 61 74 65 64 2e 0a 0a 3c 70 3e 20 49 66  updated...<p> If
e6e0: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
e6f0: 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20  s negative, and 
e700: 74 68 65 72 65 20 61 72 65 20 42 2d 74 72 65 65  there are B-tree
e710: 20 73 74 72 75 63 74 75 72 65 73 20 6f 6e 20 6d   structures on m
e720: 6f 72 65 20 74 68 61 6e 0a 6f 6e 65 20 6c 65 76  ore than.one lev
e730: 65 6c 20 77 69 74 68 69 6e 20 74 68 65 20 46 54  el within the FT
e740: 53 20 69 6e 64 65 78 2c 20 61 6c 6c 20 42 2d 74  S index, all B-t
e750: 72 65 65 20 73 74 72 75 63 74 75 72 65 73 20 61  ree structures a
e760: 72 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74  re assigned to t
e770: 68 65 20 73 61 6d 65 0a 6c 65 76 65 6c 20 62 65  he same.level be
e780: 66 6f 72 65 20 74 68 65 20 6d 65 72 67 65 20 6f  fore the merge o
e790: 70 65 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  peration is comm
e7a0: 65 6e 63 65 64 2e 20 41 64 64 69 74 69 6f 6e 61  enced. Additiona
e7b0: 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
e7c0: 6d 65 74 65 72 0a 69 73 20 6e 65 67 61 74 69 76  meter.is negativ
e7d0: 65 2c 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  e, the value of 
e7e0: 74 68 65 20 75 73 65 72 6d 65 72 67 65 20 63 6f  the usermerge co
e7f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e800: 6f 6e 20 69 73 20 6e 6f 74 20 0a 72 65 73 70 65  on is not .respe
e810: 63 74 65 64 20 2d 20 61 73 20 66 65 77 20 61 73  cted - as few as
e820: 20 74 77 6f 20 62 2d 74 72 65 65 73 20 66 72 6f   two b-trees fro
e830: 6d 20 74 68 65 20 73 61 6d 65 20 6c 65 76 65 6c  m the same level
e840: 20 6d 61 79 20 62 65 20 6d 65 72 67 65 64 20 74   may be merged t
e850: 6f 67 65 74 68 65 72 2e 0a 0a 3c 70 3e 20 54 68  ogether...<p> Th
e860: 65 20 61 62 6f 76 65 20 6d 65 61 6e 73 20 74 68  e above means th
e870: 61 74 20 65 78 65 63 75 74 69 6e 67 20 74 68 65  at executing the
e880: 20 27 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64   'merge' command
e890: 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65   with a negative
e8a0: 0a 70 61 72 61 6d 65 74 65 72 20 75 6e 74 69 6c  .parameter until
e8b0: 20 74 68 65 20 62 65 66 6f 72 65 20 61 6e 64 20   the before and 
e8c0: 61 66 74 65 72 20 64 69 66 66 65 72 65 6e 63 65  after difference
e8d0: 20 69 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76   in the return v
e8e0: 61 6c 75 65 20 6f 66 0a 5b 73 71 6c 69 74 65 33  alue of.[sqlite3
e8f0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
e900: 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  ] is less than t
e910: 77 6f 20 6f 70 74 69 6d 69 7a 65 73 20 74 68 65  wo optimizes the
e920: 20 46 54 53 20 69 6e 64 65 78 20 69 6e 20 74 68   FTS index in th
e930: 65 0a 73 61 6d 65 20 77 61 79 20 61 73 20 74 68  e.same way as th
e940: 65 20 5b 46 54 53 35 20 6f 70 74 69 6d 69 7a 65  e [FTS5 optimize
e950: 20 63 6f 6d 6d 61 6e 64 5d 2e 20 48 6f 77 65 76   command]. Howev
e960: 65 72 2c 20 69 66 20 61 20 6e 65 77 20 62 2d 74  er, if a new b-t
e970: 72 65 65 20 69 73 20 61 64 64 65 64 0a 74 6f 20  ree is added.to 
e980: 74 68 65 20 46 54 53 20 69 6e 64 65 78 20 77 68  the FTS index wh
e990: 69 6c 65 20 74 68 69 73 20 70 72 6f 63 65 73 73  ile this process
e9a0: 20 69 73 20 6f 6e 67 6f 69 6e 67 2c 20 46 54 53   is ongoing, FTS
e9b0: 35 20 77 69 6c 6c 20 6d 6f 76 65 20 74 68 65 20  5 will move the 
e9c0: 6e 65 77 20 0a 62 2d 74 72 65 65 20 74 6f 20 74  new .b-tree to t
e9d0: 68 65 20 73 61 6d 65 20 6c 65 76 65 6c 20 61 73  he same level as
e9e0: 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 62 2d   the existing b-
e9f0: 74 72 65 65 73 20 61 6e 64 20 72 65 73 74 61 72  trees and restar
ea00: 74 20 74 68 65 20 6d 65 72 67 65 2e 20 54 6f 0a  t the merge. To.
ea10: 61 76 6f 69 64 20 74 68 69 73 2c 20 6f 6e 6c 79  avoid this, only
ea20: 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
ea30: 74 6f 20 27 6d 65 72 67 65 27 20 73 68 6f 75 6c  to 'merge' shoul
ea40: 64 20 73 70 65 63 69 66 79 20 61 20 6e 65 67 61  d specify a nega
ea50: 74 69 76 65 20 70 61 72 61 6d 65 74 65 72 2e 0a  tive parameter..
ea60: 45 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  Each subsequent 
ea70: 63 61 6c 6c 20 74 6f 20 27 6d 65 72 67 65 27 20  call to 'merge' 
ea80: 73 68 6f 75 6c 64 20 73 70 65 63 69 66 79 20 61  should specify a
ea90: 20 70 6f 73 69 74 69 76 65 20 76 61 6c 75 65 20   positive value 
eaa0: 73 6f 20 74 68 61 74 20 74 68 65 0a 6d 65 72 67  so that the.merg
eab0: 65 20 73 74 61 72 74 65 64 20 62 79 20 74 68 65  e started by the
eac0: 20 66 69 72 73 74 20 63 61 6c 6c 20 69 73 20 72   first call is r
ead0: 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
eae0: 20 65 76 65 6e 20 69 66 20 6e 65 77 20 62 2d 74   even if new b-t
eaf0: 72 65 65 73 20 61 72 65 0a 61 64 64 65 64 20 74  rees are.added t
eb00: 6f 20 74 68 65 20 46 54 53 20 69 6e 64 65 78 2e  o the FTS index.
eb10: 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35  ..<h2 tags="FTS5
eb20: 20 6f 70 74 69 6d 69 7a 65 20 63 6f 6d 6d 61 6e   optimize comman
eb30: 64 22 3e 54 68 65 20 27 6f 70 74 69 6d 69 7a 65  d">The 'optimize
eb40: 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a  ' Command</h2>..
eb50: 3c 70 3e 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20  <p>This command 
eb60: 6d 65 72 67 65 73 20 61 6c 6c 20 69 6e 64 69 76  merges all indiv
eb70: 69 64 75 61 6c 20 62 2d 74 72 65 65 73 20 74 68  idual b-trees th
eb80: 61 74 20 63 75 72 72 65 6e 74 6c 79 20 6d 61 6b  at currently mak
eb90: 65 20 75 70 20 74 68 65 0a 66 75 6c 6c 2d 74 65  e up the.full-te
eba0: 78 74 20 69 6e 64 65 78 20 69 6e 74 6f 20 61 20  xt index into a 
ebb0: 73 69 6e 67 6c 65 20 6c 61 72 67 65 20 62 2d 74  single large b-t
ebc0: 72 65 65 20 73 74 72 75 63 74 75 72 65 2e 20 54  ree structure. T
ebd0: 68 69 73 20 65 6e 73 75 72 65 73 20 74 68 61 74  his ensures that
ebe0: 20 74 68 65 0a 66 75 6c 6c 2d 74 65 78 74 20 69   the.full-text i
ebf0: 6e 64 65 78 20 63 6f 6e 73 75 6d 65 73 20 74 68  ndex consumes th
ec00: 65 20 6d 69 6e 69 6d 75 6d 20 73 70 61 63 65 20  e minimum space 
ec10: 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61 62  within the datab
ec20: 61 73 65 20 61 6e 64 20 69 73 20 69 6e 20 74 68  ase and is in th
ec30: 65 0a 66 61 73 74 65 73 74 20 66 6f 72 6d 20 74  e.fastest form t
ec40: 6f 20 71 75 65 72 79 2e 0a 0a 3c 70 3e 52 65 66  o query...<p>Ref
ec50: 65 72 20 74 6f 20 74 68 65 20 64 6f 63 75 6d 65  er to the docume
ec60: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ntation for the 
ec70: 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65 20  [FTS5 automerge 
ec80: 6f 70 74 69 6f 6e 5d 20 66 6f 72 20 6d 6f 72 65  option] for more
ec90: 20 64 65 74 61 69 6c 73 0a 72 65 67 61 72 64 69   details.regardi
eca0: 6e 67 20 74 68 65 20 72 65 6c 61 74 69 6f 6e 73  ng the relations
ecb0: 68 69 70 20 62 65 74 77 65 65 6e 20 74 68 65 20  hip between the 
ecc0: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
ecd0: 61 6e 64 20 69 74 73 20 63 6f 6d 70 6f 6e 65 6e  and its componen
ece0: 74 0a 62 2d 74 72 65 65 73 2e 0a 0a 3c 63 6f 64  t.b-trees...<cod
ecf0: 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52 54  eblock>.  INSERT
ed00: 20 49 4e 54 4f 20 66 74 28 66 74 29 20 56 41 4c   INTO ft(ft) VAL
ed10: 55 45 53 28 27 6f 70 74 69 6d 69 7a 65 27 29 3b  UES('optimize');
ed20: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
ed30: 70 3e 42 65 63 61 75 73 65 20 69 74 20 72 65 6f  p>Because it reo
ed40: 72 67 61 6e 69 7a 65 73 20 74 68 65 20 65 6e 74  rganizes the ent
ed50: 69 72 65 20 46 54 53 20 69 6e 64 65 78 2c 20 74  ire FTS index, t
ed60: 68 65 20 6f 70 74 69 6d 69 7a 65 20 63 6f 6d 6d  he optimize comm
ed70: 61 6e 64 20 63 61 6e 20 0a 74 61 6b 65 20 61 20  and can .take a 
ed80: 6c 6f 6e 67 20 74 69 6d 65 20 74 6f 20 72 75 6e  long time to run
ed90: 2e 20 54 68 65 20 5b 46 54 53 35 20 6d 65 72 67  . The [FTS5 merg
eda0: 65 20 63 6f 6d 6d 61 6e 64 5d 20 63 61 6e 20 62  e command] can b
edb0: 65 20 75 73 65 64 20 74 6f 20 64 69 76 69 64 65  e used to divide
edc0: 0a 74 68 65 20 77 6f 72 6b 20 6f 66 20 6f 70 74  .the work of opt
edd0: 69 6d 69 7a 69 6e 67 20 74 68 65 20 46 54 53 20  imizing the FTS 
ede0: 69 6e 64 65 78 20 69 6e 74 6f 20 6d 75 6c 74 69  index into multi
edf0: 70 6c 65 20 73 74 65 70 73 2e 20 54 6f 20 64 6f  ple steps. To do
ee00: 20 74 68 69 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c   this:..<ul>.  <
ee10: 6c 69 3e 20 49 6e 76 6f 6b 65 20 74 68 65 20 27  li> Invoke the '
ee20: 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 6f  merge' command o
ee30: 6e 63 65 20 77 69 74 68 20 74 68 65 20 70 61 72  nce with the par
ee40: 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 4e  ameter set to -N
ee50: 2c 20 74 68 65 6e 0a 20 20 3c 6c 69 3e 20 49 6e  , then.  <li> In
ee60: 76 6f 6b 65 20 74 68 65 20 27 6d 65 72 67 65 27  voke the 'merge'
ee70: 20 63 6f 6d 6d 61 6e 64 20 7a 65 72 6f 20 6f 72   command zero or
ee80: 20 6d 6f 72 65 20 74 69 6d 65 73 20 77 69 74 68   more times with
ee90: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 73   the parameter s
eea0: 65 74 20 74 6f 20 4e 2e 0a 3c 2f 75 6c 3e 0a 0a  et to N..</ul>..
eeb0: 3c 70 3e 77 68 65 72 65 20 4e 20 69 73 20 74 68  <p>where N is th
eec0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
eed0: 73 20 6f 66 20 64 61 74 61 20 74 6f 20 6d 65 72  s of data to mer
eee0: 67 65 20 77 69 74 68 69 6e 20 65 61 63 68 20 69  ge within each i
eef0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 74 68 65  nvocation of.the
ef00: 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64 2e 20   merge command. 
ef10: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
ef20: 73 68 6f 75 6c 64 20 73 74 6f 70 20 69 6e 76 6f  should stop invo
ef30: 6b 69 6e 67 20 6d 65 72 67 65 20 77 68 65 6e 20  king merge when 
ef40: 74 68 65 0a 64 69 66 66 65 72 65 6e 63 65 20 69  the.difference i
ef50: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
ef60: 72 6e 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  rned by the sqli
ef70: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
ef80: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 62 65 66  s() function bef
ef90: 6f 72 65 0a 61 6e 64 20 61 66 74 65 72 20 74 68  ore.and after th
efa0: 65 20 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64 20  e merge command 
efb0: 64 72 6f 70 73 20 74 6f 20 62 65 6c 6f 77 20 74  drops to below t
efc0: 77 6f 2e 20 54 68 65 20 6d 65 72 67 65 20 63 6f  wo. The merge co
efd0: 6d 6d 61 6e 64 73 20 6d 61 79 20 62 65 0a 69 73  mmands may be.is
efe0: 73 75 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  sued as part of 
eff0: 74 68 65 20 73 61 6d 65 20 6f 72 20 73 65 70 61  the same or sepa
f000: 72 61 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rate transaction
f010: 73 2c 20 61 6e 64 20 62 79 20 74 68 65 20 73 61  s, and by the sa
f020: 6d 65 20 6f 72 0a 64 69 66 66 65 72 65 6e 74 20  me or.different 
f030: 64 61 74 61 62 61 73 65 20 63 6c 69 65 6e 74 73  database clients
f040: 2e 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 64  . Refer to the d
f050: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
f060: 20 74 68 65 20 0a 5b 46 54 53 35 20 6d 65 72 67   the .[FTS5 merg
f070: 65 20 63 6f 6d 6d 61 6e 64 20 7c 20 6d 65 72 67  e command | merg
f080: 65 20 63 6f 6d 6d 61 6e 64 5d 20 66 6f 72 20 66  e command] for f
f090: 75 72 74 68 65 72 20 64 65 74 61 69 6c 73 2e 0a  urther details..
f0a0: 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20  .<h2 tags="FTS5 
f0b0: 70 67 73 7a 20 6f 70 74 69 6f 6e 22 3e 54 68 65  pgsz option">The
f0c0: 20 27 70 67 73 7a 27 20 43 6f 6e 66 69 67 75 72   'pgsz' Configur
f0d0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32  ation Option</h2
f0e0: 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d  >..<p> This comm
f0f0: 61 6e 64 20 69 73 20 75 73 65 64 20 74 6f 20 73  and is used to s
f100: 65 74 20 74 68 65 20 70 65 72 73 69 73 74 65 6e  et the persisten
f110: 74 20 22 70 67 73 7a 22 20 6f 70 74 69 6f 6e 2e  t "pgsz" option.
f120: 0a 0a 3c 70 3e 20 54 68 65 20 66 75 6c 6c 2d 74  ..<p> The full-t
f130: 65 78 74 20 69 6e 64 65 78 20 6d 61 69 6e 74 61  ext index mainta
f140: 69 6e 65 64 20 62 79 20 46 54 53 35 20 69 73 20  ined by FTS5 is 
f150: 73 74 6f 72 65 64 20 61 73 20 61 20 73 65 72 69  stored as a seri
f160: 65 73 20 6f 66 20 66 69 78 65 64 2d 73 69 7a 65  es of fixed-size
f170: 0a 62 6c 6f 62 73 20 69 6e 20 61 20 64 61 74 61  .blobs in a data
f180: 62 61 73 65 20 74 61 62 6c 65 2e 20 49 74 20 69  base table. It i
f190: 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 6e  s not strictly n
f1a0: 65 63 65 73 73 61 72 79 20 66 6f 72 20 61 6c 6c  ecessary for all
f1b0: 20 62 6c 6f 62 73 20 74 68 61 74 20 6d 61 6b 65   blobs that make
f1c0: 0a 75 70 20 61 20 66 75 6c 6c 2d 74 65 78 74 20  .up a full-text 
f1d0: 69 6e 64 65 78 20 74 6f 20 62 65 20 74 68 65 20  index to be the 
f1e0: 73 61 6d 65 20 73 69 7a 65 2e 20 54 68 65 20 70  same size. The p
f1f0: 67 73 7a 20 6f 70 74 69 6f 6e 20 64 65 74 65 72  gsz option deter
f200: 6d 69 6e 65 73 20 74 68 65 20 73 69 7a 65 0a 6f  mines the size.o
f210: 66 20 61 6c 6c 20 62 6c 6f 62 73 20 63 72 65 61  f all blobs crea
f220: 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65 6e  ted by subsequen
f230: 74 20 69 6e 64 65 78 20 77 72 69 74 65 72 73 2e  t index writers.
f240: 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
f250: 75 65 20 69 73 20 31 30 30 30 2e 0a 0a 3c 63 6f  ue is 1000...<co
f260: 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52  deblock>.  INSER
f270: 54 20 49 4e 54 4f 20 66 74 28 66 74 2c 20 72 61  T INTO ft(ft, ra
f280: 6e 6b 29 20 56 41 4c 55 45 53 28 27 70 67 73 7a  nk) VALUES('pgsz
f290: 27 2c 20 34 30 37 32 29 3b 0a 3c 2f 63 6f 64 65  ', 4072);.</code
f2a0: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73  block>..<h2 tags
f2b0: 3d 22 46 54 53 35 20 72 61 6e 6b 20 63 6f 6e 66  ="FTS5 rank conf
f2c0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f2d0: 22 3e 54 68 65 20 27 72 61 6e 6b 27 20 43 6f 6e  ">The 'rank' Con
f2e0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
f2f0: 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73  n</h2>..<p> This
f300: 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73 65 64   command is used
f310: 20 74 6f 20 73 65 74 20 74 68 65 20 70 65 72 73   to set the pers
f320: 69 73 74 65 6e 74 20 22 72 61 6e 6b 22 20 6f 70  istent "rank" op
f330: 74 69 6f 6e 2e 0a 0a 3c 70 3e 20 54 68 65 20 72  tion...<p> The r
f340: 61 6e 6b 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ank option is us
f350: 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
f360: 20 64 65 66 61 75 6c 74 20 61 75 78 69 6c 69 61   default auxilia
f370: 72 79 20 66 75 6e 63 74 69 6f 6e 20 6d 61 70 70  ry function mapp
f380: 69 6e 67 0a 66 6f 72 20 74 68 65 20 72 61 6e 6b  ing.for the rank
f390: 20 63 6f 6c 75 6d 6e 2e 20 54 68 65 20 6f 70 74   column. The opt
f3a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  ion should be se
f3b0: 74 20 74 6f 20 61 20 74 65 78 74 20 76 61 6c 75  t to a text valu
f3c0: 65 20 69 6e 20 74 68 65 20 73 61 6d 65 0a 66 6f  e in the same.fo
f3d0: 72 6d 61 74 20 61 73 20 64 65 73 63 72 69 62 65  rmat as describe
f3e0: 64 20 66 6f 72 20 5b 61 75 78 69 6c 69 61 72 79  d for [auxiliary
f3f0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 70 70 69 6e   function mappin
f400: 67 20 7c 20 22 72 61 6e 6b 20 4d 41 54 43 48 20  g | "rank MATCH 
f410: 3f 22 5d 20 74 65 72 6d 73 20 0a 61 62 6f 76 65  ?"] terms .above
f420: 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a  . For example:..
f430: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e  <codeblock>.  IN
f440: 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c  SERT INTO ft(ft,
f450: 20 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 72   rank) VALUES('r
f460: 61 6e 6b 27 2c 20 27 62 6d 32 35 28 31 30 2e 30  ank', 'bm25(10.0
f470: 2c 20 35 2e 30 29 27 29 3b 0a 3c 2f 63 6f 64 65  , 5.0)');.</code
f480: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 20 74 61 67 73  block>..<h2 tags
f490: 3d 22 46 54 53 35 20 72 65 62 75 69 6c 64 20 63  ="FTS5 rebuild c
f4a0: 6f 6d 6d 61 6e 64 22 3e 54 68 65 20 27 72 65 62  ommand">The 'reb
f4b0: 75 69 6c 64 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68  uild' Command</h
f4c0: 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d  2>..<p> This com
f4d0: 6d 61 6e 64 20 66 69 72 73 74 20 64 65 6c 65 74  mand first delet
f4e0: 65 73 20 74 68 65 20 65 6e 74 69 72 65 20 66 75  es the entire fu
f4f0: 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2c 20 74  ll-text index, t
f500: 68 65 6e 20 72 65 62 75 69 6c 64 73 20 69 74 0a  hen rebuilds it.
f510: 62 61 73 65 64 20 6f 6e 20 74 68 65 20 63 6f 6e  based on the con
f520: 74 65 6e 74 73 20 6f 66 20 74 68 65 20 74 61 62  tents of the tab
f530: 6c 65 20 6f 72 20 5b 46 54 53 35 20 65 78 74 65  le or [FTS5 exte
f540: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62  rnal content tab
f550: 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 0a 74 61  les | content.ta
f560: 62 6c 65 5d 2e 20 20 49 74 20 69 73 20 6e 6f 74  ble].  It is not
f570: 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74 68 20   available with 
f580: 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65 73  [FTS5 contentles
f590: 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74 65  s tables | conte
f5a0: 6e 74 6c 65 73 73 0a 74 61 62 6c 65 73 5d 2e 0a  ntless.tables]..
f5b0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49  .<codeblock>.  I
f5c0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74  NSERT INTO ft(ft
f5d0: 29 20 56 41 4c 55 45 53 28 27 72 65 62 75 69 6c  ) VALUES('rebuil
f5e0: 64 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  d');.</codeblock
f5f0: 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53  >..<h2 tags="FTS
f600: 35 20 75 73 65 72 6d 65 72 67 65 20 6f 70 74 69  5 usermerge opti
f610: 6f 6e 22 3e 54 68 65 20 27 75 73 65 72 6d 65 72  on">The 'usermer
f620: 67 65 27 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ge' Configuratio
f630: 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c  n Option</h2>..<
f640: 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20  p> This command 
f650: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 74  is used to set t
f660: 68 65 20 70 65 72 73 69 73 74 65 6e 74 20 22 75  he persistent "u
f670: 73 65 72 6d 65 72 67 65 22 20 6f 70 74 69 6f 6e  sermerge" option
f680: 2e 0a 0a 3c 70 3e 20 54 68 65 20 75 73 65 72 6d  ...<p> The userm
f690: 65 72 67 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  erge option is s
f6a0: 69 6d 69 6c 61 72 20 74 6f 20 74 68 65 20 61 75  imilar to the au
f6b0: 74 6f 6d 65 72 67 65 20 61 6e 64 20 63 72 69 73  tomerge and cris
f6c0: 69 73 6d 65 72 67 65 20 6f 70 74 69 6f 6e 73 2e  ismerge options.
f6d0: 0a 49 74 20 69 73 20 74 68 65 20 6d 69 6e 69 6d  .It is the minim
f6e0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 2d 74  um number of b-t
f6f0: 72 65 65 20 73 65 67 6d 65 6e 74 73 20 74 68 61  ree segments tha
f700: 74 20 77 69 6c 6c 20 62 65 20 6d 65 72 67 65 64  t will be merged
f710: 20 74 6f 67 65 74 68 65 72 20 62 79 0a 61 20 27   together by.a '
f720: 6d 65 72 67 65 27 20 63 6f 6d 6d 61 6e 64 20 77  merge' command w
f730: 69 74 68 20 61 20 70 6f 73 69 74 69 76 65 20 70  ith a positive p
f740: 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 65 78  arameter. For ex
f750: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
f760: 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  ck>.  INSERT INT
f770: 4f 20 66 74 28 66 74 2c 20 72 61 6e 6b 29 20 56  O ft(ft, rank) V
f780: 41 4c 55 45 53 28 27 75 73 65 72 6d 65 72 67 65  ALUES('usermerge
f790: 27 2c 20 34 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ', 4);.</codeblo
f7a0: 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 64 65 66  ck>..<p> The def
f7b0: 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74 68  ault value of th
f7c0: 65 20 75 73 65 72 6d 65 72 67 65 20 6f 70 74 69  e usermerge opti
f7d0: 6f 6e 20 69 73 20 34 2e 20 54 68 65 20 6d 69 6e  on is 4. The min
f7e0: 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 76 61 6c  imum allowed val
f7f0: 75 65 0a 69 73 20 32 2c 20 61 6e 64 20 74 68 65  ue.is 2, and the
f800: 20 6d 61 78 69 6d 75 6d 20 31 36 2e 0a 0a 3c 68   maximum 16...<h
f810: 31 20 74 61 67 73 3d 22 45 78 74 65 6e 64 69 6e  1 tags="Extendin
f820: 67 20 46 54 53 35 22 3e 45 78 74 65 6e 64 69 6e  g FTS5">Extendin
f830: 67 20 46 54 53 35 3c 2f 68 31 3e 0a 0a 3c 70 3e  g FTS5</h1>..<p>
f840: 46 54 53 35 20 66 65 61 74 75 72 65 73 20 41 50  FTS5 features AP
f850: 49 73 20 61 6c 6c 6f 77 69 6e 67 20 69 74 20 74  Is allowing it t
f860: 6f 20 62 65 20 65 78 74 65 6e 64 65 64 20 62 79  o be extended by
f870: 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 41  :..<ul>.  <li> A
f880: 64 64 69 6e 67 20 6e 65 77 20 61 75 78 69 6c 69  dding new auxili
f890: 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 69 6d  ary functions im
f8a0: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 2c 20  plemented in C, 
f8b0: 61 6e 64 0a 20 20 3c 6c 69 3e 20 41 64 64 69 6e  and.  <li> Addin
f8c0: 67 20 6e 65 77 20 74 6f 6b 65 6e 69 7a 65 72 73  g new tokenizers
f8d0: 2c 20 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e 74  , also implement
f8e0: 65 64 20 69 6e 20 43 2e 0a 3c 2f 75 6c 3e 0a 0a  ed in C..</ul>..
f8f0: 3c 70 3e 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  <p> The built-in
f900: 20 74 6f 6b 65 6e 69 7a 65 72 73 20 61 6e 64 20   tokenizers and 
f910: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
f920: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 69 6e  ons described in
f930: 20 74 68 69 73 0a 64 6f 63 75 6d 65 6e 74 20 61   this.document a
f940: 72 65 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  re all implement
f950: 65 64 20 75 73 69 6e 67 20 74 68 65 20 70 75 62  ed using the pub
f960: 6c 69 63 6c 79 20 61 76 61 69 6c 61 62 6c 65 20  licly available 
f970: 41 50 49 20 64 65 73 63 72 69 62 65 64 0a 62 65  API described.be
f980: 6c 6f 77 2e 0a 0a 3c 70 3e 20 42 65 66 6f 72 65  low...<p> Before
f990: 20 61 20 6e 65 77 20 61 75 78 69 6c 69 61 72 79   a new auxiliary
f9a0: 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 74 6f 6b   function or tok
f9b0: 65 6e 69 7a 65 72 20 69 6d 70 6c 65 6d 65 6e 74  enizer implement
f9c0: 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 0a 72 65  ation may be .re
f9d0: 67 69 73 74 65 72 65 64 20 77 69 74 68 20 46 54  gistered with FT
f9e0: 53 35 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  S5, an applicati
f9f0: 6f 6e 20 6d 75 73 74 20 6f 62 74 61 69 6e 20 61  on must obtain a
fa00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
fa10: 22 66 74 73 35 5f 61 70 69 22 0a 73 74 72 75 63  "fts5_api".struc
fa20: 74 75 72 65 2e 20 54 68 65 72 65 20 69 73 20 6f  ture. There is o
fa30: 6e 65 20 66 74 73 35 5f 61 70 69 20 73 74 72 75  ne fts5_api stru
fa40: 63 74 75 72 65 20 66 6f 72 20 65 61 63 68 20 64  cture for each d
fa50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fa60: 6f 6e 20 77 69 74 68 0a 77 68 69 63 68 20 74 68  on with.which th
fa70: 65 20 46 54 53 35 20 65 78 74 65 6e 73 69 6f 6e  e FTS5 extension
fa80: 20 69 73 20 72 65 67 69 73 74 65 72 65 64 2e 20   is registered. 
fa90: 54 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 70 6f  To obtain the po
faa0: 69 6e 74 65 72 2c 20 74 68 65 20 61 70 70 6c 69  inter, the appli
fab0: 63 61 74 69 6f 6e 0a 69 6e 76 6f 6b 65 73 20 74  cation.invokes t
fac0: 68 65 20 53 51 4c 20 75 73 65 72 2d 64 65 66 69  he SQL user-defi
fad0: 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 66 74 73  ned function fts
fae0: 35 28 29 20 77 69 74 68 20 61 20 73 69 6e 67 6c  5() with a singl
faf0: 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 61  e argument.  Tha
fb00: 74 0a 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t.argument must 
fb10: 62 65 20 73 65 74 20 74 6f 20 61 20 70 6f 69 6e  be set to a poin
fb20: 74 65 72 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  ter to a pointer
fb30: 20 74 6f 20 61 6e 20 66 74 73 35 5f 61 70 69 20   to an fts5_api 
fb40: 6f 62 6a 65 63 74 0a 75 73 69 6e 67 20 74 68 65  object.using the
fb50: 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
fb60: 6f 69 6e 74 65 72 28 29 5d 20 69 6e 74 65 72 66  ointer()] interf
fb70: 61 63 65 2e 0a 54 68 65 20 66 6f 6c 6c 6f 77 69  ace..The followi
fb80: 6e 67 20 65 78 61 6d 70 6c 65 20 63 6f 64 65 20  ng example code 
fb90: 64 65 6d 6f 6e 73 74 72 61 74 65 73 20 74 68 65  demonstrates the
fba0: 20 74 65 63 68 6e 69 71 75 65 3a 0a 0a 3c 63 6f   technique:..<co
fbb0: 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2f 2a  deblock>.  <i>/*
fbc0: 0a 20 20 2a 2a 20 52 65 74 75 72 6e 20 61 20 70  .  ** Return a p
fbd0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 74  ointer to the ft
fbe0: 73 35 5f 61 70 69 20 70 6f 69 6e 74 65 72 20 66  s5_api pointer f
fbf0: 6f 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  or database conn
fc00: 65 63 74 69 6f 6e 20 64 62 2e 0a 20 20 2a 2a 20  ection db..  ** 
fc10: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
fc20: 72 73 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  rs, return NULL 
fc30: 61 6e 64 20 6c 65 61 76 65 20 61 6e 20 65 72 72  and leave an err
fc40: 6f 72 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  or in the databa
fc50: 73 65 20 0a 20 20 2a 2a 20 68 61 6e 64 6c 65 20  se .  ** handle 
fc60: 28 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e  (accessible usin
fc70: 67 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  g sqlite3_errcod
fc80: 65 28 29 2f 65 72 72 6d 73 67 28 29 29 2e 0a 20  e()/errmsg()).. 
fc90: 20 2a 2f 3c 2f 69 3e 0a 20 20 66 74 73 35 5f 61   */</i>.  fts5_a
fca0: 70 69 20 2a 66 74 73 35 5f 61 70 69 5f 66 72 6f  pi *fts5_api_fro
fcb0: 6d 5f 64 62 28 73 71 6c 69 74 65 33 20 2a 64 62  m_db(sqlite3 *db
fcc0: 29 7b 0a 20 20 20 20 66 74 73 35 5f 61 70 69 20  ){.    fts5_api 
fcd0: 2a 70 52 65 74 20 3d 20 30 3b 0a 20 20 20 20 73  *pRet = 0;.    s
fce0: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
fcf0: 6d 74 20 3d 20 30 3b 0a 0a 20 20 20 20 69 66 28  mt = 0;..    if(
fd00: 20 53 51 4c 49 54 45 5f 4f 4b 3d 3d 73 71 6c 69   SQLITE_OK==sqli
fd10: 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 20  te3_prepare(db, 
fd20: 22 53 45 4c 45 43 54 20 66 74 73 35 28 3f 31 29  "SELECT fts5(?1)
fd30: 22 2c 20 2d 31 2c 20 26 70 53 74 6d 74 2c 20 30  ", -1, &pStmt, 0
fd40: 29 20 29 7b 0a 20 20 20 20 20 20 73 71 6c 69 74  ) ){.      sqlit
fd50: 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
fd60: 70 53 74 6d 74 2c 20 28 76 6f 69 64 2a 29 26 70  pStmt, (void*)&p
fd70: 52 65 74 2c 20 22 66 74 73 35 5f 61 70 69 5f 70  Ret, "fts5_api_p
fd80: 74 72 22 2c 20 4e 55 4c 4c 29 3b 0a 20 20 20 20  tr", NULL);.    
fd90: 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 70    sqlite3_step(p
fda0: 53 74 6d 74 29 3b 0a 20 20 20 20 7d 0a 20 20 20  Stmt);.    }.   
fdb0: 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
fdc0: 65 28 70 53 74 6d 74 29 3b 0a 20 20 20 20 72 65  e(pStmt);.    re
fdd0: 74 75 72 6e 20 70 52 65 74 3b 0a 20 20 7d 0a 3c  turn pRet;.  }.<
fde0: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
fdf0: 3c 62 3e 42 61 63 6b 77 61 72 64 73 20 43 6f 6d  <b>Backwards Com
fe00: 70 61 74 69 62 69 6c 69 74 79 20 57 61 72 6e 69  patibility Warni
fe10: 6e 67 3a 3c 2f 62 3e 0a 50 72 69 6f 72 20 74 6f  ng:</b>.Prior to
fe20: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
fe30: 33 2e 32 30 2e 30 20 28 5b 64 61 74 65 6f 66 3a  3.20.0 ([dateof:
fe40: 33 2e 32 30 2e 30 5d 29 2c 20 74 68 65 20 66 74  3.20.0]), the ft
fe50: 73 35 28 29 20 77 6f 72 6b 65 64 20 73 6c 69 67  s5() worked slig
fe60: 68 74 6c 79 0a 64 69 66 66 65 72 65 6e 74 6c 79  htly.differently
fe70: 2e 20 20 4f 6c 64 65 72 20 61 70 70 6c 69 63 61  .  Older applica
fe80: 74 69 6f 6e 73 20 74 68 61 74 20 65 78 74 65 6e  tions that exten
fe90: 64 20 46 54 53 35 20 6d 75 73 74 20 62 65 20 72  d FTS5 must be r
fea0: 65 76 69 73 65 64 20 74 6f 20 75 73 65 20 0a 74  evised to use .t
feb0: 68 65 20 6e 65 77 20 74 65 63 68 6e 69 71 75 65  he new technique
fec0: 20 73 68 6f 77 6e 20 61 62 6f 76 65 2e 0a 0a 3c   shown above...<
fed0: 70 3e 20 54 68 65 20 66 74 73 35 5f 61 70 69 20  p> The fts5_api 
fee0: 73 74 72 75 63 74 75 72 65 20 69 73 20 64 65 66  structure is def
fef0: 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 2e  ined as follows.
ff00: 20 49 74 20 65 78 70 6f 73 65 73 20 74 68 72 65   It exposes thre
ff10: 65 20 6d 65 74 68 6f 64 73 2c 20 0a 6f 6e 65 20  e methods, .one 
ff20: 65 61 63 68 20 66 6f 72 20 72 65 67 69 73 74 65  each for registe
ff30: 72 69 6e 67 20 6e 65 77 20 61 75 78 69 6c 69 61  ring new auxilia
ff40: 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  ry functions and
ff50: 20 74 6f 6b 65 6e 69 7a 65 72 73 2c 20 61 6e 64   tokenizers, and
ff60: 20 6f 6e 65 20 66 6f 72 0a 72 65 74 72 69 65 76   one for.retriev
ff70: 69 6e 67 20 65 78 69 73 74 69 6e 67 20 74 6f 6b  ing existing tok
ff80: 65 6e 69 7a 65 72 2e 20 54 68 65 20 6c 61 74 74  enizer. The latt
ff90: 65 72 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  er is intended t
ffa0: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 68 65  o facilitate the
ffb0: 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20  .implementation 
ffc0: 6f 66 20 22 74 6f 6b 65 6e 69 7a 65 72 20 77 72  of "tokenizer wr
ffd0: 61 70 70 65 72 73 22 20 73 69 6d 69 6c 61 72 20  appers" similar 
ffe0: 74 6f 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  to the built-in.
fff0: 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72  porter tokenizer
10000 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 3c  ...<codeblock>.<
10010 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74  tclscript>.  set
10020 20 72 65 73 20 22 22 0a 20 20 73 65 74 20 3a 3a   res "".  set ::
10030 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73  extract_api_docs
10040 5f 6d 6f 64 65 20 66 74 73 35 5f 61 70 69 0a 20  _mode fts5_api. 
10050 20 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73   catch { set res
10060 20 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a   [source [file j
10070 6f 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66  oin $::SRC ext/f
10080 74 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f  ts5/extract_api_
10090 64 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73  docs.tcl]] }.  s
100a0 65 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69  et res.</tclscri
100b0 70 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  pt>.</codeblock>
100c0 0a 0a 3c 70 3e 20 54 6f 20 69 6e 76 6f 6b 65 20  ..<p> To invoke 
100d0 61 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  a method of the 
100e0 66 74 73 35 5f 61 70 69 20 6f 62 6a 65 63 74 2c  fts5_api object,
100f0 20 74 68 65 20 66 74 73 35 5f 61 70 69 20 70 6f   the fts5_api po
10100 69 6e 74 65 72 20 69 74 73 65 6c 66 0a 73 68 6f  inter itself.sho
10110 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
10120 20 74 68 65 20 6d 65 74 68 6f 64 73 20 66 69 72   the methods fir
10130 73 74 20 61 72 67 75 6d 65 6e 74 20 66 6f 6c 6c  st argument foll
10140 6f 77 65 64 20 62 79 20 74 68 65 20 6f 74 68 65  owed by the othe
10150 72 2c 20 6d 65 74 68 6f 64 0a 73 70 65 63 69 66  r, method.specif
10160 69 63 2c 20 61 72 67 75 6d 65 6e 74 73 2e 20 46  ic, arguments. F
10170 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
10180 64 65 62 6c 6f 63 6b 3e 0a 20 20 20 20 72 63 20  deblock>.    rc 
10190 3d 20 70 46 74 73 35 41 70 69 2d 3e 78 43 72 65  = pFts5Api->xCre
101a0 61 74 65 54 6f 6b 65 6e 69 7a 65 72 28 70 46 74  ateTokenizer(pFt
101b0 73 35 41 70 69 2c 20 2e 2e 2e 20 6f 74 68 65 72  s5Api, ... other
101c0 20 61 72 67 73 20 2e 2e 2e 29 3b 0a 3c 2f 63 6f   args ...);.</co
101d0 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68  deblock>..<p> Th
101e0 65 20 66 74 73 35 5f 61 70 69 20 73 74 72 75 63  e fts5_api struc
101f0 74 75 72 65 20 6d 65 74 68 6f 64 73 20 61 72 65  ture methods are
10200 20 64 65 73 63 72 69 62 65 64 20 69 6e 64 69 76   described indiv
10210 69 64 75 61 6c 6c 79 20 69 6e 20 74 68 65 20 66  idually in the f
10220 6f 6c 6c 6f 77 69 6e 67 0a 73 65 63 74 69 6f 6e  ollowing.section
10230 73 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 63 75  s...<h2 tags="cu
10240 73 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 73 22  stom tokenizers"
10250 3e 43 75 73 74 6f 6d 20 54 6f 6b 65 6e 69 7a 65  >Custom Tokenize
10260 72 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 6f 20  rs</h2>..<p> To 
10270 63 72 65 61 74 65 20 61 20 63 75 73 74 6f 6d 20  create a custom 
10280 74 6f 6b 65 6e 69 7a 65 72 2c 20 61 6e 20 61 70  tokenizer, an ap
10290 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69  plication must i
102a0 6d 70 6c 65 6d 65 6e 74 20 74 68 72 65 65 0a 66  mplement three.f
102b0 75 6e 63 74 69 6f 6e 73 3a 20 61 20 74 6f 6b 65  unctions: a toke
102c0 6e 69 7a 65 72 20 63 6f 6e 73 74 72 75 63 74 6f  nizer constructo
102d0 72 20 28 78 43 72 65 61 74 65 29 2c 20 61 20 64  r (xCreate), a d
102e0 65 73 74 72 75 63 74 6f 72 20 28 78 44 65 6c 65  estructor (xDele
102f0 74 65 29 20 61 6e 64 20 61 0a 66 75 6e 63 74 69  te) and a.functi
10300 6f 6e 20 74 6f 20 64 6f 20 74 68 65 20 61 63 74  on to do the act
10310 75 61 6c 20 74 6f 6b 65 6e 69 7a 61 74 69 6f 6e  ual tokenization
10320 20 28 78 54 6f 6b 65 6e 69 7a 65 29 2e 20 54 68   (xTokenize). Th
10330 65 20 74 79 70 65 20 6f 66 20 65 61 63 68 0a 66  e type of each.f
10340 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 20 66 6f  unction is as fo
10350 72 20 74 68 65 20 6d 65 6d 62 65 72 20 76 61 72  r the member var
10360 69 61 62 6c 65 73 20 6f 66 20 74 68 65 20 66 74  iables of the ft
10370 73 35 5f 74 6f 6b 65 6e 69 7a 65 72 20 73 74 72  s5_tokenizer str
10380 75 63 74 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  uct:..<codeblock
10390 3e 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20  >.<tclscript>.  
103a0 73 65 74 20 72 65 73 20 22 22 0a 20 20 73 65 74  set res "".  set
103b0 20 3a 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64   ::extract_api_d
103c0 6f 63 73 5f 6d 6f 64 65 20 66 74 73 35 5f 74 6f  ocs_mode fts5_to
103d0 6b 65 6e 69 7a 65 72 0a 20 20 63 61 74 63 68 20  kenizer.  catch 
103e0 7b 20 73 65 74 20 72 65 73 20 5b 73 6f 75 72 63  { set res [sourc
103f0 65 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a  e [file join $::
10400 53 52 43 20 65 78 74 2f 66 74 73 35 2f 65 78 74  SRC ext/fts5/ext
10410 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63  ract_api_docs.tc
10420 6c 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65 73 0a  l]] }.  set res.
10430 3c 2f 74 63 6c 73 63 72 69 70 74 3e 0a 3c 2f 63  </tclscript>.</c
10440 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
10450 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10460 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
10470 77 69 74 68 20 74 68 65 20 46 54 53 35 20 6d 6f  with the FTS5 mo
10480 64 75 6c 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  dule by calling 
10490 74 68 65 0a 78 43 72 65 61 74 65 54 6f 6b 65 6e  the.xCreateToken
104a0 69 7a 65 72 28 29 20 6d 65 74 68 6f 64 20 6f 66  izer() method of
104b0 20 74 68 65 20 66 74 73 35 5f 61 70 69 20 6f 62   the fts5_api ob
104c0 6a 65 63 74 2e 20 49 66 20 74 68 65 72 65 20 69  ject. If there i
104d0 73 20 61 6c 72 65 61 64 79 20 61 0a 74 6f 6b 65  s already a.toke
104e0 6e 69 7a 65 72 20 77 69 74 68 20 74 68 65 20 73  nizer with the s
104f0 61 6d 65 20 6e 61 6d 65 2c 20 69 74 20 69 73 20  ame name, it is 
10500 72 65 70 6c 61 63 65 64 2e 20 20 49 66 20 61 20  replaced.  If a 
10510 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
10520 79 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 70  y parameter.is p
10530 61 73 73 65 64 20 74 6f 20 78 43 72 65 61 74 65  assed to xCreate
10540 54 6f 6b 65 6e 69 7a 65 72 28 29 2c 20 69 74 20  Tokenizer(), it 
10550 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
10560 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 43  a copy of the pC
10570 6f 6e 74 65 78 74 0a 70 6f 69 6e 74 65 72 20 70  ontext.pointer p
10580 61 73 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c  assed as the onl
10590 79 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  y argument when 
105a0 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
105b0 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  dle is closed or
105c0 20 77 68 65 6e 0a 74 68 65 20 74 6f 6b 65 6e 69   when.the tokeni
105d0 7a 65 72 20 69 73 20 72 65 70 6c 61 63 65 64 2e  zer is replaced.
105e0 0a 0a 3c 70 3e 20 49 66 20 73 75 63 63 65 73 73  ..<p> If success
105f0 66 75 6c 2c 20 78 43 72 65 61 74 65 54 6f 6b 65  ful, xCreateToke
10600 6e 69 7a 65 72 28 29 20 72 65 74 75 72 6e 73 20  nizer() returns 
10610 53 51 4c 49 54 45 5f 4f 4b 2e 20 4f 74 68 65 72  SQLITE_OK. Other
10620 77 69 73 65 2c 20 69 74 0a 72 65 74 75 72 6e 73  wise, it.returns
10630 20 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f 72   an SQLite error
10640 20 63 6f 64 65 2e 20 49 6e 20 74 68 69 73 20 63   code. In this c
10650 61 73 65 20 74 68 65 20 78 44 65 73 74 72 6f 79  ase the xDestroy
10660 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 3c 62 3e   function is <b>
10670 6e 6f 74 3c 2f 62 3e 20 0a 69 6e 76 6f 6b 65 64  not</b> .invoked
10680 2e 0a 0a 3c 70 3e 20 57 68 65 6e 20 61 6e 20 46  ...<p> When an F
10690 54 53 35 20 74 61 62 6c 65 20 75 73 65 73 20 74  TS5 table uses t
106a0 68 65 20 63 75 73 74 6f 6d 20 74 6f 6b 65 6e 69  he custom tokeni
106b0 7a 65 72 2c 20 74 68 65 20 46 54 53 35 20 63 6f  zer, the FTS5 co
106c0 72 65 20 63 61 6c 6c 73 20 78 43 72 65 61 74 65  re calls xCreate
106d0 28 29 0a 6f 6e 63 65 20 74 6f 20 63 72 65 61 74  ().once to creat
106e0 65 20 61 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 74  e a tokenizer, t
106f0 68 65 6e 20 78 54 6f 6b 65 6e 69 7a 65 28 29 20  hen xTokenize() 
10700 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
10710 65 73 20 74 6f 20 74 6f 6b 65 6e 69 7a 65 0a 73  es to tokenize.s
10720 74 72 69 6e 67 73 2c 20 74 68 65 6e 20 78 44 65  trings, then xDe
10730 6c 65 74 65 28 29 20 74 6f 20 66 72 65 65 20 61  lete() to free a
10740 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 6c 6c  ny resources all
10750 6f 63 61 74 65 64 20 62 79 20 78 43 72 65 61 74  ocated by xCreat
10760 65 28 29 2e 20 4d 6f 72 65 0a 73 70 65 63 69 66  e(). More.specif
10770 69 63 61 6c 6c 79 3a 0a 0a 3c 74 63 6c 73 63 72  ically:..<tclscr
10780 69 70 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22  ipt>.  set res "
10790 22 0a 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63  ".  set ::extrac
107a0 74 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20  t_api_docs_mode 
107b0 74 6f 6b 65 6e 69 7a 65 72 5f 61 70 69 0a 20 20  tokenizer_api.  
107c0 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20  catch { set res 
107d0 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f  [source [file jo
107e0 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74  in $::SRC ext/ft
107f0 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64  s5/extract_api_d
10800 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65  ocs.tcl]] }.  se
10810 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70  t res.</tclscrip
10820 74 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54  t>..<h2 tags="FT
10830 53 35 20 63 75 73 74 6f 6d 20 61 75 78 69 6c 69  S5 custom auxili
10840 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 22 3e 43  ary functions">C
10850 75 73 74 6f 6d 20 41 75 78 69 6c 69 61 72 79 20  ustom Auxiliary 
10860 46 75 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a  Functions</h2>..
10870 3c 70 3e 20 49 6d 70 6c 65 6d 65 6e 74 69 6e 67  <p> Implementing
10880 20 61 20 63 75 73 74 6f 6d 20 61 75 78 69 6c 69   a custom auxili
10890 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ary function is 
108a0 73 69 6d 69 6c 61 72 20 74 6f 20 69 6d 70 6c 65  similar to imple
108b0 6d 65 6e 74 69 6e 67 20 61 0a 5b 61 70 70 6c 69  menting a.[appli
108c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
108d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 7c 20 73 63  QL function | sc
108e0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
108f0 6e 5d 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  n]. The implemen
10900 74 61 74 69 6f 6e 0a 73 68 6f 75 6c 64 20 62 65  tation.should be
10910 20 61 20 43 20 66 75 6e 63 74 69 6f 6e 20 6f 66   a C function of
10920 20 74 79 70 65 20 66 74 73 35 5f 65 78 74 65 6e   type fts5_exten
10930 73 69 6f 6e 5f 66 75 6e 63 74 69 6f 6e 2c 20 64  sion_function, d
10940 65 66 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77  efined as follow
10950 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  s:..<codeblock>.
10960 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65  <tclscript>.  se
10970 74 20 72 65 73 20 22 22 0a 20 20 73 65 74 20 3a  t res "".  set :
10980 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63  :extract_api_doc
10990 73 5f 6d 6f 64 65 20 66 74 73 35 5f 65 78 74 65  s_mode fts5_exte
109a0 6e 73 69 6f 6e 0a 20 20 63 61 74 63 68 20 7b 20  nsion.  catch { 
109b0 73 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65 20  set res [source 
109c0 5b 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52  [file join $::SR
109d0 43 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72 61  C ext/fts5/extra
109e0 63 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d  ct_api_docs.tcl]
109f0 5d 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f  ] }.  set res.</
10a00 74 63 6c 73 63 72 69 70 74 3e 0a 3c 2f 63 6f 64  tclscript>.</cod
10a10 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65  eblock>..<p> The
10a20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10a30 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
10a40 74 68 20 74 68 65 20 46 54 53 35 20 6d 6f 64 75  th the FTS5 modu
10a50 6c 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  le by calling th
10a60 65 0a 78 43 72 65 61 74 65 46 75 6e 63 74 69 6f  e.xCreateFunctio
10a70 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  n() method of th
10a80 65 20 66 74 73 35 5f 61 70 69 20 6f 62 6a 65 63  e fts5_api objec
10a90 74 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 61  t. If there is a
10aa0 6c 72 65 61 64 79 20 61 6e 0a 61 75 78 69 6c 69  lready an.auxili
10ab0 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ary function wit
10ac0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2c  h the same name,
10ad0 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
10ae0 62 79 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  by the new funct
10af0 69 6f 6e 2e 0a 49 66 20 61 20 6e 6f 6e 2d 4e 55  ion..If a non-NU
10b00 4c 4c 20 78 44 65 73 74 72 6f 79 20 70 61 72 61  LL xDestroy para
10b10 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
10b20 74 6f 20 78 43 72 65 61 74 65 46 75 6e 63 74 69  to xCreateFuncti
10b30 6f 6e 28 29 2c 20 69 74 20 69 73 20 69 6e 76 6f  on(), it is invo
10b40 6b 65 64 0a 77 69 74 68 20 61 20 63 6f 70 79 20  ked.with a copy 
10b50 6f 66 20 74 68 65 20 70 43 6f 6e 74 65 78 74 20  of the pContext 
10b60 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 61  pointer passed a
10b70 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
10b80 65 6e 74 20 77 68 65 6e 20 74 68 65 0a 64 61 74  ent when the.dat
10b90 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
10ba0 63 6c 6f 73 65 64 20 6f 72 20 77 68 65 6e 20 74  closed or when t
10bb0 68 65 20 72 65 67 69 73 74 65 72 65 64 20 61 75  he registered au
10bc0 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
10bd0 20 69 73 0a 72 65 70 6c 61 63 65 64 2e 0a 0a 3c   is.replaced...<
10be0 70 3e 20 49 66 20 73 75 63 63 65 73 73 66 75 6c  p> If successful
10bf0 2c 20 78 43 72 65 61 74 65 46 75 6e 63 74 69 6f  , xCreateFunctio
10c00 6e 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  n() returns SQLI
10c10 54 45 5f 4f 4b 2e 20 4f 74 68 65 72 77 69 73 65  TE_OK. Otherwise
10c20 2c 20 69 74 0a 72 65 74 75 72 6e 73 20 61 6e 20  , it.returns an 
10c30 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
10c40 65 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  e. In this case 
10c50 74 68 65 20 78 44 65 73 74 72 6f 79 20 66 75 6e  the xDestroy fun
10c60 63 74 69 6f 6e 20 69 73 20 3c 62 3e 6e 6f 74 3c  ction is <b>not<
10c70 2f 62 3e 20 0a 69 6e 76 6f 6b 65 64 2e 0a 0a 3c  /b> .invoked...<
10c80 70 3e 20 54 68 65 20 66 69 6e 61 6c 20 74 68 72  p> The final thr
10c90 65 65 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73  ee arguments pas
10ca0 73 65 64 20 74 6f 20 74 68 65 20 61 75 78 69 6c  sed to the auxil
10cb0 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 63 61  iary function ca
10cc0 6c 6c 62 61 63 6b 20 61 72 65 0a 73 69 6d 69 6c  llback are.simil
10cd0 61 72 20 74 6f 20 74 68 65 20 74 68 72 65 65 20  ar to the three 
10ce0 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64  arguments passed
10cf0 20 74 6f 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   to the implemen
10d00 74 61 74 69 6f 6e 20 6f 66 20 61 20 73 63 61 6c  tation of a scal
10d10 61 72 20 53 51 4c 0a 66 75 6e 63 74 69 6f 6e 2e  ar SQL.function.
10d20 20 41 6c 6c 20 61 72 67 75 6d 65 6e 74 73 20 65   All arguments e
10d30 78 63 65 70 74 20 74 68 65 20 66 69 72 73 74 20  xcept the first 
10d40 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 61 75  passed to the au
10d50 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
10d60 20 61 72 65 0a 61 76 61 69 6c 61 62 6c 65 20 74   are.available t
10d70 6f 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  o the implementa
10d80 74 69 6f 6e 20 69 6e 20 74 68 65 20 61 70 56 61  tion in the apVa
10d90 6c 26 23 39 31 3b 26 23 39 33 3b 20 61 72 72 61  l&#91;&#93; arra
10da0 79 2e 20 54 68 65 0a 69 6d 70 6c 65 6d 65 6e 74  y. The.implement
10db0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 74  ation should ret
10dc0 75 72 6e 20 61 20 72 65 73 75 6c 74 20 6f 72 20  urn a result or 
10dd0 65 72 72 6f 72 20 76 69 61 20 74 68 65 20 63 6f  error via the co
10de0 6e 74 65 6e 74 20 68 61 6e 64 6c 65 20 70 43 74  ntent handle pCt
10df0 78 2e 0a 0a 3c 70 3e 20 54 68 65 20 66 69 72 73  x...<p> The firs
10e00 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
10e10 64 20 74 6f 20 61 6e 20 61 75 78 69 6c 69 61 72  d to an auxiliar
10e20 79 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  y function callb
10e30 61 63 6b 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ack is a pointer
10e40 0a 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20  .to a structure 
10e50 63 6f 6e 74 61 69 6e 69 6e 67 20 6d 65 74 68 6f  containing metho
10e60 64 73 20 74 68 61 74 20 6d 61 79 20 62 65 20 69  ds that may be i
10e70 6e 76 6f 6b 65 64 20 69 6e 20 6f 72 64 65 72 20  nvoked in order 
10e80 74 6f 20 6f 62 74 61 69 6e 0a 69 6e 66 6f 72 6d  to obtain.inform
10e90 61 74 69 6f 6e 20 72 65 67 61 72 64 69 6e 67 20  ation regarding 
10ea0 74 68 65 20 63 75 72 72 65 6e 74 20 71 75 65 72  the current quer
10eb0 79 20 6f 72 20 72 6f 77 2e 20 54 68 65 20 73 65  y or row. The se
10ec0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
10ed0 20 61 6e 0a 6f 70 61 71 75 65 20 68 61 6e 64 6c   an.opaque handl
10ee0 65 20 74 68 61 74 20 73 68 6f 75 6c 64 20 62 65  e that should be
10ef0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
10f00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10f10 20 61 6e 79 20 73 75 63 68 20 6d 65 74 68 6f 64   any such method
10f20 20 0a 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 46 6f   .invocation. Fo
10f30 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 66  r example, the f
10f40 6f 6c 6c 6f 77 69 6e 67 20 61 75 78 69 6c 69 61  ollowing auxilia
10f50 72 79 20 66 75 6e 63 74 69 6f 6e 20 64 65 66 69  ry function defi
10f60 6e 69 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 74  nition returns.t
10f70 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
10f80 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 61 6c 6c  of tokens in all
10f90 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20   columns of the 
10fa0 63 75 72 72 65 6e 74 20 72 6f 77 3a 0a 0a 3c 63  current row:..<c
10fb0 6f 64 65 62 6c 6f 63 6b 3e 0a 3c 69 3e 2f 2a 0a  odeblock>.<i>/*.
10fc0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
10fd0 6e 20 6f 66 20 61 6e 20 61 75 78 69 6c 69 61 72  n of an auxiliar
10fe0 79 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  y function that 
10ff0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
11000 65 72 0a 2a 2a 20 6f 66 20 74 6f 6b 65 6e 73 20  er.** of tokens 
11010 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
11020 6f 77 20 28 69 6e 63 6c 75 64 69 6e 67 20 61 6c  ow (including al
11030 6c 20 63 6f 6c 75 6d 6e 73 29 2e 0a 2a 2f 3c 2f  l columns)..*/</
11040 69 3e 0a 73 74 61 74 69 63 20 76 6f 69 64 20 63  i>.static void c
11050 6f 6c 75 6d 6e 5f 73 69 7a 65 5f 69 6d 70 28 0a  olumn_size_imp(.
11060 20 20 63 6f 6e 73 74 20 46 74 73 35 45 78 74 65    const Fts5Exte
11070 6e 73 69 6f 6e 41 70 69 20 2a 70 41 70 69 2c 0a  nsionApi *pApi,.
11080 20 20 46 74 73 35 43 6f 6e 74 65 78 74 20 2a 70    Fts5Context *p
11090 46 74 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 63  Fts,.  sqlite3_c
110a0 6f 6e 74 65 78 74 20 2a 70 43 74 78 2c 0a 20 20  ontext *pCtx,.  
110b0 69 6e 74 20 6e 56 61 6c 2c 0a 20 20 73 71 6c 69  int nVal,.  sqli
110c0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 70 56 61  te3_value **apVa
110d0 6c 0a 29 7b 0a 20 20 69 6e 74 20 72 63 3b 0a 20  l.){.  int rc;. 
110e0 20 69 6e 74 20 6e 54 6f 6b 65 6e 3b 0a 20 20 72   int nToken;.  r
110f0 63 20 3d 20 70 41 70 69 2d 3e 78 43 6f 6c 75 6d  c = pApi->xColum
11100 6e 53 69 7a 65 28 70 46 74 73 2c 20 2d 31 2c 20  nSize(pFts, -1, 
11110 26 6e 54 6f 6b 65 6e 29 3b 0a 20 20 69 66 28 20  &nToken);.  if( 
11120 72 63 3d 3d 53 51 4c 49 54 45 5f 4f 4b 20 29 7b  rc==SQLITE_OK ){
11130 0a 20 20 20 20 73 71 6c 69 74 65 33 5f 72 65 73  .    sqlite3_res
11140 75 6c 74 5f 69 6e 74 28 70 43 74 78 2c 20 6e 54  ult_int(pCtx, nT
11150 6f 6b 65 6e 29 3b 0a 20 20 7d 65 6c 73 65 7b 0a  oken);.  }else{.
11160 20 20 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75      sqlite3_resu
11170 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 70 43  lt_error_code(pC
11180 74 78 2c 20 72 63 29 3b 0a 20 20 7d 0a 7d 0a 3c  tx, rc);.  }.}.<
11190 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
111a0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  The following se
111b0 63 74 69 6f 6e 20 64 65 73 63 72 69 62 65 73 20  ction describes 
111c0 74 68 65 20 41 50 49 20 6f 66 66 65 72 65 64 20  the API offered 
111d0 74 6f 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  to auxiliary fun
111e0 63 74 69 6f 6e 0a 69 6d 70 6c 65 6d 65 6e 74 61  ction.implementa
111f0 74 69 6f 6e 73 20 69 6e 20 64 65 74 61 69 6c 2e  tions in detail.
11200 20 46 75 72 74 68 65 72 20 65 78 61 6d 70 6c 65   Further example
11210 73 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 69  s may be found i
11220 6e 20 74 68 65 20 22 66 74 73 35 5f 61 75 78 2e  n the "fts5_aux.
11230 63 22 0a 66 69 6c 65 20 6f 66 20 74 68 65 20 73  c".file of the s
11240 6f 75 72 63 65 20 63 6f 64 65 2e 0a 0a 3c 68 33  ource code...<h3
11250 20 74 61 67 73 3d 22 63 75 73 74 6f 6d 20 61 75   tags="custom au
11260 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
11270 73 22 3e 0a 20 20 43 75 73 74 6f 6d 20 41 75 78  s">.  Custom Aux
11280 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f 6e 73  iliary Functions
11290 20 41 50 49 20 52 65 66 65 72 65 6e 63 65 0a 3c   API Reference.<
112a0 2f 68 33 3e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  /h3>..<codeblock
112b0 3e 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a 20 20  >.<tclscript>.  
112c0 73 65 74 20 72 65 73 20 22 22 0a 20 20 73 65 74  set res "".  set
112d0 20 3a 3a 65 78 74 72 61 63 74 5f 61 70 69 5f 64   ::extract_api_d
112e0 6f 63 73 5f 6d 6f 64 65 20 46 74 73 35 45 78 74  ocs_mode Fts5Ext
112f0 65 6e 73 69 6f 6e 41 70 69 0a 20 20 63 61 74 63  ensionApi.  catc
11300 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73 6f 75  h { set res [sou
11310 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e 20 24  rce [file join $
11320 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35 2f 65  ::SRC ext/fts5/e
11330 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 2e  xtract_api_docs.
11340 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20 72 65  tcl]] }.  set re
11350 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e 0a 3c  s.</tclscript>.<
11360 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 74 63  /codeblock>..<tc
11370 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74 20 72  lscript>.  set r
11380 65 73 20 22 22 0a 20 20 75 6e 73 65 74 20 2d 6e  es "".  unset -n
11390 6f 63 6f 6d 70 6c 61 69 6e 20 3a 3a 65 78 74 72  ocomplain ::extr
113a0 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64  act_api_docs_mod
113b0 65 20 0a 20 20 63 61 74 63 68 20 7b 20 73 65 74  e .  catch { set
113c0 20 72 65 73 20 5b 73 6f 75 72 63 65 20 5b 66 69   res [source [fi
113d0 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43 20 65  le join $::SRC e
113e0 78 74 2f 66 74 73 35 2f 65 78 74 72 61 63 74 5f  xt/fts5/extract_
113f0 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d 20 7d  api_docs.tcl]] }
11400 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f 74 63 6c  .  set res.</tcl
11410 73 63 72 69 70 74 3e 0a 0a 3c 68 31 20 74 61 67  script>..<h1 tag
11420 73 3d 22 66 74 73 35 76 6f 63 61 62 22 3e 54 68  s="fts5vocab">Th
11430 65 20 66 74 73 35 76 6f 63 61 62 20 56 69 72 74  e fts5vocab Virt
11440 75 61 6c 20 54 61 62 6c 65 20 4d 6f 64 75 6c 65  ual Table Module
11450 3c 2f 68 31 3e 0a 0a 3c 70 3e 20 54 68 65 20 66  </h1>..<p> The f
11460 74 73 35 76 6f 63 61 62 20 76 69 72 74 75 61 6c  ts5vocab virtual
11470 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 61 6c   table module al
11480 6c 6f 77 73 20 75 73 65 72 73 20 74 6f 20 65 78  lows users to ex
11490 74 72 61 63 74 20 69 6e 66 6f 72 6d 61 74 69 6f  tract informatio
114a0 6e 20 66 72 6f 6d 0a 61 6e 20 46 54 53 35 20 66  n from.an FTS5 f
114b0 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 64  ull-text index d
114c0 69 72 65 63 74 6c 79 2e 20 54 68 65 20 66 74 73  irectly. The fts
114d0 35 76 6f 63 61 62 20 6d 6f 64 75 6c 65 20 69 73  5vocab module is
114e0 20 61 20 70 61 72 74 20 6f 66 20 46 54 53 35 20   a part of FTS5 
114f0 2d 20 69 74 20 0a 69 73 20 61 76 61 69 6c 61 62  - it .is availab
11500 6c 65 20 77 68 65 6e 65 76 65 72 20 46 54 53 35  le whenever FTS5
11510 20 69 73 2e 0a 0a 3c 70 3e 20 45 61 63 68 20 66   is...<p> Each f
11520 74 73 35 76 6f 63 61 62 20 74 61 62 6c 65 20 69  ts5vocab table i
11530 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
11540 68 20 61 20 73 69 6e 67 6c 65 20 46 54 53 35 20  h a single FTS5 
11550 74 61 62 6c 65 2e 20 41 6e 20 66 74 73 35 76 6f  table. An fts5vo
11560 63 61 62 0a 74 61 62 6c 65 20 69 73 20 75 73 75  cab.table is usu
11570 61 6c 6c 79 20 63 72 65 61 74 65 64 20 62 79 20  ally created by 
11580 73 70 65 63 69 66 79 69 6e 67 20 74 77 6f 20 61  specifying two a
11590 72 67 75 6d 65 6e 74 73 20 69 6e 20 70 6c 61 63  rguments in plac
115a0 65 20 6f 66 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  e of column name
115b0 73 0a 69 6e 20 74 68 65 20 43 52 45 41 54 45 20  s.in the CREATE 
115c0 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
115d0 61 74 65 6d 65 6e 74 20 2d 20 74 68 65 20 6e 61  atement - the na
115e0 6d 65 20 6f 66 20 74 68 65 20 61 73 73 6f 63 69  me of the associ
115f0 61 74 65 64 20 46 54 53 35 20 74 61 62 6c 65 0a  ated FTS5 table.
11600 61 6e 64 20 74 68 65 20 74 79 70 65 20 6f 66 20  and the type of 
11610 66 74 73 35 76 6f 63 61 62 20 74 61 62 6c 65 2e  fts5vocab table.
11620 20 43 75 72 72 65 6e 74 6c 79 20 74 68 65 72 65   Currently there
11630 20 61 72 65 20 74 68 72 65 65 20 74 79 70 65 73   are three types
11640 20 6f 66 20 66 74 73 35 76 6f 63 61 62 0a 74 61   of fts5vocab.ta
11650 62 6c 65 3b 20 22 72 6f 77 22 2c 20 22 63 6f 6c  ble; "row", "col
11660 22 20 61 6e 64 20 22 69 6e 73 74 61 6e 63 65 22  " and "instance"
11670 2e 20 55 6e 6c 65 73 73 20 74 68 65 20 66 74 73  . Unless the fts
11680 35 76 6f 63 61 62 20 74 61 62 6c 65 20 69 73 20  5vocab table is 
11690 63 72 65 61 74 65 64 0a 77 69 74 68 69 6e 20 74  created.within t
116a0 68 65 20 22 74 65 6d 70 22 20 64 61 74 61 62 61  he "temp" databa
116b0 73 65 2c 20 69 74 20 6d 75 73 74 20 62 65 20 70  se, it must be p
116c0 61 72 74 20 6f 66 20 74 68 65 20 73 61 6d 65 20  art of the same 
116d0 64 61 74 61 62 61 73 65 20 61 73 20 74 68 65 0a  database as the.
116e0 61 73 73 6f 63 69 61 74 65 64 20 46 54 53 35 20  associated FTS5 
116f0 74 61 62 6c 65 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  table...<codeblo
11700 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61  ck>.  <i>-- Crea
11710 74 65 20 61 6e 20 66 74 73 35 76 6f 63 61 62 20  te an fts5vocab 
11720 22 72 6f 77 22 20 74 61 62 6c 65 20 74 6f 20 71  "row" table to q
11730 75 65 72 79 20 74 68 65 20 66 75 6c 6c 2d 74 65  uery the full-te
11740 78 74 20 69 6e 64 65 78 20 62 65 6c 6f 6e 67 69  xt index belongi
11750 6e 67 0a 20 20 2d 2d 20 74 6f 20 46 54 53 35 20  ng.  -- to FTS5 
11760 74 61 62 6c 65 20 22 66 74 31 22 2e 3c 2f 69 3e  table "ft1".</i>
11770 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
11780 4c 20 54 41 42 4c 45 20 66 74 31 5f 76 20 55 53  L TABLE ft1_v US
11790 49 4e 47 20 66 74 73 35 76 6f 63 61 62 28 27 66  ING fts5vocab('f
117a0 74 31 27 2c 20 27 72 6f 77 27 29 3b 0a 0a 20 20  t1', 'row');..  
117b0 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 6e 20  <i>-- Create an 
117c0 66 74 73 35 76 6f 63 61 62 20 22 63 6f 6c 22 20  fts5vocab "col" 
117d0 74 61 62 6c 65 20 74 6f 20 71 75 65 72 79 20 74  table to query t
117e0 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64  he full-text ind
117f0 65 78 20 62 65 6c 6f 6e 67 69 6e 67 0a 20 20 2d  ex belonging.  -
11800 2d 20 74 6f 20 46 54 53 35 20 74 61 62 6c 65 20  - to FTS5 table 
11810 22 66 74 32 22 2e 3c 2f 69 3e 0a 20 20 43 52 45  "ft2".</i>.  CRE
11820 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
11830 45 20 66 74 32 5f 76 20 55 53 49 4e 47 20 66 74  E ft2_v USING ft
11840 73 35 76 6f 63 61 62 28 66 74 32 2c 20 63 6f 6c  s5vocab(ft2, col
11850 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61  );..  <i>-- Crea
11860 74 65 20 61 6e 20 66 74 73 35 76 6f 63 61 62 20  te an fts5vocab 
11870 22 69 6e 73 74 61 6e 63 65 22 20 74 61 62 6c 65  "instance" table
11880 20 74 6f 20 71 75 65 72 79 20 74 68 65 20 66 75   to query the fu
11890 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 0a 20 20  ll-text index.  
118a0 2d 2d 20 62 65 6c 6f 6e 67 69 6e 67 20 74 6f 20  -- belonging to 
118b0 46 54 53 35 20 74 61 62 6c 65 20 22 66 74 33 22  FTS5 table "ft3"
118c0 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  .</i>.  CREATE V
118d0 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74 33  IRTUAL TABLE ft3
118e0 5f 76 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63  _v USING fts5voc
118f0 61 62 28 66 74 33 2c 20 69 6e 73 74 61 6e 63 65  ab(ft3, instance
11900 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
11910 0a 3c 70 3e 20 49 66 20 61 6e 20 66 74 73 35 76  .<p> If an fts5v
11920 6f 63 61 62 20 74 61 62 6c 65 20 69 73 20 63 72  ocab table is cr
11930 65 61 74 65 64 20 69 6e 20 74 68 65 20 74 65 6d  eated in the tem
11940 70 20 64 61 74 61 62 61 73 65 2c 20 69 74 20 6d  p database, it m
11950 61 79 20 62 65 20 61 73 73 6f 63 69 61 74 65 64  ay be associated
11960 0a 77 69 74 68 20 61 6e 20 46 54 53 35 20 74 61  .with an FTS5 ta
11970 62 6c 65 20 69 6e 20 61 6e 79 20 61 74 74 61 63  ble in any attac
11980 68 65 64 20 64 61 74 61 62 61 73 65 2e 20 49 6e  hed database. In
11990 20 6f 72 64 65 72 20 74 6f 20 61 74 74 61 63 68   order to attach
119a0 20 74 68 65 20 66 74 73 35 76 6f 63 61 62 0a 74   the fts5vocab.t
119b0 61 62 6c 65 20 74 6f 20 61 6e 20 46 54 53 35 20  able to an FTS5 
119c0 74 61 62 6c 65 20 6c 6f 63 61 74 65 64 20 69 6e  table located in
119d0 20 61 20 64 61 74 61 62 61 73 65 20 6f 74 68 65   a database othe
119e0 72 20 74 68 61 6e 20 22 74 65 6d 70 22 2c 20 74  r than "temp", t
119f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 64  he name of the.d
11a00 61 74 61 62 61 73 65 20 69 73 20 69 6e 73 65 72  atabase is inser
11a10 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 46  ted before the F
11a20 54 53 35 20 74 61 62 6c 65 20 6e 61 6d 65 20 69  TS5 table name i
11a30 6e 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52  n the CREATE VIR
11a40 54 55 41 4c 20 54 41 42 4c 45 20 0a 61 72 67 75  TUAL TABLE .argu
11a50 6d 65 6e 74 73 2e 20 46 6f 72 20 65 78 61 6d 70  ments. For examp
11a60 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  le:..<codeblock>
11a70 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20  .  <i>-- Create 
11a80 61 6e 20 66 74 73 35 76 6f 63 61 62 20 22 72 6f  an fts5vocab "ro
11a90 77 22 20 74 61 62 6c 65 20 74 6f 20 71 75 65 72  w" table to quer
11aa0 79 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20  y the full-text 
11ab0 69 6e 64 65 78 20 62 65 6c 6f 6e 67 69 6e 67 0a  index belonging.
11ac0 20 20 2d 2d 20 74 6f 20 46 54 53 35 20 74 61 62    -- to FTS5 tab
11ad0 6c 65 20 22 66 74 31 22 20 69 6e 20 64 61 74 61  le "ft1" in data
11ae0 62 61 73 65 20 22 6d 61 69 6e 22 2e 3c 2f 69 3e  base "main".</i>
11af0 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
11b00 4c 20 54 41 42 4c 45 20 74 65 6d 70 2e 66 74 31  L TABLE temp.ft1
11b10 5f 76 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63  _v USING fts5voc
11b20 61 62 28 6d 61 69 6e 2c 20 27 66 74 31 27 2c 20  ab(main, 'ft1', 
11b30 27 72 6f 77 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  'row');..  <i>--
11b40 20 43 72 65 61 74 65 20 61 6e 20 66 74 73 35 76   Create an fts5v
11b50 6f 63 61 62 20 22 63 6f 6c 22 20 74 61 62 6c 65  ocab "col" table
11b60 20 74 6f 20 71 75 65 72 79 20 74 68 65 20 66 75   to query the fu
11b70 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 62 65  ll-text index be
11b80 6c 6f 6e 67 69 6e 67 0a 20 20 2d 2d 20 74 6f 20  longing.  -- to 
11b90 46 54 53 35 20 74 61 62 6c 65 20 22 66 74 32 22  FTS5 table "ft2"
11ba0 20 69 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   in attached dat
11bb0 61 62 61 73 65 20 22 61 75 78 22 2e 3c 2f 69 3e  abase "aux".</i>
11bc0 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
11bd0 4c 20 54 41 42 4c 45 20 74 65 6d 70 2e 66 74 32  L TABLE temp.ft2
11be0 5f 76 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63  _v USING fts5voc
11bf0 61 62 28 27 61 75 78 27 2c 20 66 74 32 2c 20 63  ab('aux', ft2, c
11c00 6f 6c 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 43 72  ol);..  <i>-- Cr
11c10 65 61 74 65 20 61 6e 20 66 74 73 35 76 6f 63 61  eate an fts5voca
11c20 62 20 22 69 6e 73 74 61 6e 63 65 22 20 74 61 62  b "instance" tab
11c30 6c 65 20 74 6f 20 71 75 65 72 79 20 74 68 65 20  le to query the 
11c40 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
11c50 0a 20 20 2d 2d 20 62 65 6c 6f 6e 67 69 6e 67 20  .  -- belonging 
11c60 74 6f 20 46 54 53 35 20 74 61 62 6c 65 20 22 66  to FTS5 table "f
11c70 74 33 22 20 69 6e 20 61 74 74 61 63 68 65 64 20  t3" in attached 
11c80 64 61 74 61 62 61 73 65 20 22 6f 74 68 65 72 22  database "other"
11c90 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56  .</i>.  CREATE V
11ca0 49 52 54 55 41 4c 20 54 41 42 4c 45 20 74 65 6d  IRTUAL TABLE tem
11cb0 70 2e 66 74 32 5f 76 20 55 53 49 4e 47 20 66 74  p.ft2_v USING ft
11cc0 73 35 76 6f 63 61 62 28 27 61 75 78 27 2c 20 66  s5vocab('aux', f
11cd0 74 33 2c 20 27 69 6e 73 74 61 6e 63 65 27 29 3b  t3, 'instance');
11ce0 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
11cf0 70 3e 20 53 70 65 63 69 66 79 69 6e 67 20 74 68  p> Specifying th
11d00 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 77 68  ree arguments wh
11d10 65 6e 20 63 72 65 61 74 69 6e 67 20 61 6e 20 66  en creating an f
11d20 74 73 35 76 6f 63 61 62 20 74 61 62 6c 65 20 69  ts5vocab table i
11d30 6e 20 61 6e 79 20 64 61 74 61 62 61 73 65 0a 6f  n any database.o
11d40 74 68 65 72 20 74 68 61 6e 20 22 74 65 6d 70 22  ther than "temp"
11d50 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 65   results in an e
11d60 72 72 6f 72 2e 0a 0a 3c 70 3e 20 41 6e 20 66 74  rror...<p> An ft
11d70 73 35 76 6f 63 61 62 20 74 61 62 6c 65 20 6f 66  s5vocab table of
11d80 20 74 79 70 65 20 22 72 6f 77 22 20 63 6f 6e 74   type "row" cont
11d90 61 69 6e 73 20 6f 6e 65 20 72 6f 77 20 66 6f 72  ains one row for
11da0 20 65 61 63 68 20 64 69 73 74 69 6e 63 74 20 74   each distinct t
11db0 65 72 6d 0a 69 6e 20 74 68 65 20 61 73 73 6f 63  erm.in the assoc
11dc0 69 61 74 65 64 20 46 54 53 35 20 74 61 62 6c 65  iated FTS5 table
11dd0 2e 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  . The table colu
11de0 6d 6e 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  mns are as follo
11df0 77 73 3a 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69  ws:..<table stri
11e00 70 65 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68  ped=1>.  <tr><th
11e10 3e 43 6f 6c 75 6d 6e 3c 74 68 3e 43 6f 6e 74 65  >Column<th>Conte
11e20 6e 74 73 0a 20 20 3c 74 72 3e 3c 74 64 3e 74 65  nts.  <tr><td>te
11e30 72 6d 3c 74 64 3e 20 54 68 65 20 74 65 72 6d 2c  rm<td> The term,
11e40 20 61 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   as stored in th
11e50 65 20 46 54 53 35 20 69 6e 64 65 78 2e 0a 20 20  e FTS5 index..  
11e60 3c 74 72 3e 3c 74 64 3e 64 6f 63 3c 74 64 3e 20  <tr><td>doc<td> 
11e70 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   The number of r
11e80 6f 77 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ows that contain
11e90 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 69 6e   at least one in
11ea0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 65  stance of the te
11eb0 72 6d 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 63 6e  rm..  <tr><td>cn
11ec0 74 3c 74 64 3e 20 20 54 68 65 20 74 6f 74 61 6c  t<td>  The total
11ed0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 61   number of insta
11ee0 6e 63 65 73 20 6f 66 20 74 68 65 20 74 65 72 6d  nces of the term
11ef0 20 69 6e 20 74 68 65 20 65 6e 74 69 72 65 20 46   in the entire F
11f00 54 53 35 20 74 61 62 6c 65 2e 0a 3c 2f 74 61 62  TS5 table..</tab
11f10 6c 65 3e 0a 0a 3c 70 3e 20 41 6e 20 66 74 73 35  le>..<p> An fts5
11f20 76 6f 63 61 62 20 74 61 62 6c 65 20 6f 66 20 74  vocab table of t
11f30 79 70 65 20 22 63 6f 6c 22 20 63 6f 6e 74 61 69  ype "col" contai
11f40 6e 73 20 6f 6e 65 20 72 6f 77 20 66 6f 72 20 65  ns one row for e
11f50 61 63 68 20 64 69 73 74 69 6e 63 74 20 74 65 72  ach distinct ter
11f60 6d 2f 63 6f 6c 75 6d 6e 0a 63 6f 6d 62 69 6e 61  m/column.combina
11f70 74 69 6f 6e 20 69 6e 20 74 68 65 20 61 73 73 6f  tion in the asso
11f80 63 69 61 74 65 64 20 46 54 53 35 20 74 61 62 6c  ciated FTS5 tabl
11f90 65 2e 20 54 61 62 6c 65 20 63 6f 6c 75 6d 6e 73  e. Table columns
11fa0 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   are as follows:
11fb0 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69 70 65 64  ..<table striped
11fc0 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68 3e 43 6f  =1>.  <tr><th>Co
11fd0 6c 75 6d 6e 3c 74 68 3e 43 6f 6e 74 65 6e 74 73  lumn<th>Contents
11fe0 0a 20 20 3c 74 72 3e 3c 74 64 3e 74 65 72 6d 3c  .  <tr><td>term<
11ff0 74 64 3e 20 54 68 65 20 74 65 72 6d 2c 20 61 73  td> The term, as
12000 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 46   stored in the F
12010 54 53 35 20 69 6e 64 65 78 2e 0a 20 20 3c 74 72  TS5 index..  <tr
12020 3e 3c 74 64 3e 63 6f 6c 3c 74 64 3e 20 20 54 68  ><td>col<td>  Th
12030 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 46 54  e name of the FT
12040 53 35 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  S5 table column 
12050 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
12060 65 20 74 65 72 6d 2e 0a 20 20 3c 74 72 3e 3c 74  e term..  <tr><t
12070 64 3e 64 6f 63 3c 74 64 3e 20 20 54 68 65 20 6e  d>doc<td>  The n
12080 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
12090 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20   the FTS5 table 
120a0 66 6f 72 20 77 68 69 63 68 20 63 6f 6c 75 6d 6e  for which column
120b0 20 24 63 6f 6c 0a 20 20 20 20 20 20 20 20 20 20   $col.          
120c0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e           contain
120d0 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 69  s at least one i
120e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74  nstance of the t
120f0 65 72 6d 2e 0a 20 20 3c 74 72 3e 3c 74 64 3e 63  erm..  <tr><td>c
12100 6e 74 3c 74 64 3e 20 20 54 68 65 20 74 6f 74 61  nt<td>  The tota
12110 6c 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  l number of inst
12120 61 6e 63 65 73 20 6f 66 20 74 68 65 20 74 65 72  ances of the ter
12130 6d 20 74 68 61 74 20 61 70 70 65 61 72 20 69 6e  m that appear in
12140 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
12150 20 20 20 20 63 6f 6c 75 6d 6e 20 24 63 6f 6c 20      column $col 
12160 6f 66 20 74 68 65 20 46 54 53 35 20 74 61 62 6c  of the FTS5 tabl
12170 65 20 28 63 6f 6e 73 69 64 65 72 69 6e 67 20 61  e (considering a
12180 6c 6c 20 72 6f 77 73 29 2e 20 0a 3c 2f 74 61 62  ll rows). .</tab
12190 6c 65 3e 0a 0a 3c 70 3e 20 41 6e 20 66 74 73 35  le>..<p> An fts5
121a0 76 6f 63 61 62 20 74 61 62 6c 65 20 6f 66 20 74  vocab table of t
121b0 79 70 65 20 22 69 6e 73 74 61 6e 63 65 22 20 63  ype "instance" c
121c0 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 72 6f 77 20  ontains one row 
121d0 66 6f 72 20 65 61 63 68 20 74 65 72 6d 0a 69 6e  for each term.in
121e0 73 74 61 6e 63 65 20 73 74 6f 72 65 64 20 69 6e  stance stored in
121f0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
12200 46 54 53 20 69 6e 64 65 78 2e 20 41 73 73 75 6d  FTS index. Assum
12210 69 6e 67 20 74 68 65 20 46 54 53 35 20 74 61 62  ing the FTS5 tab
12220 6c 65 20 69 73 0a 63 72 65 61 74 65 64 20 77 69  le is.created wi
12230 74 68 20 74 68 65 20 27 64 65 74 61 69 6c 27 20  th the 'detail' 
12240 6f 70 74 69 6f 6e 20 73 65 74 20 74 6f 20 27 66  option set to 'f
12250 75 6c 6c 27 2c 20 74 61 62 6c 65 20 63 6f 6c 75  ull', table colu
12260 6d 6e 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  mns are as follo
12270 77 73 3a 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69  ws:..<table stri
12280 70 65 64 3d 31 3e 0a 20 20 3c 74 72 3e 3c 74 68  ped=1>.  <tr><th
12290 3e 43 6f 6c 75 6d 6e 3c 74 68 3e 43 6f 6e 74 65  >Column<th>Conte
122a0 6e 74 73 0a 20 20 3c 74 72 3e 3c 74 64 3e 74 65  nts.  <tr><td>te
122b0 72 6d 3c 74 64 3e 20 20 20 54 68 65 20 74 65 72  rm<td>   The ter
122c0 6d 2c 20 61 73 20 73 74 6f 72 65 64 20 69 6e 20  m, as stored in 
122d0 74 68 65 20 46 54 53 35 20 69 6e 64 65 78 2e 0a  the FTS5 index..
122e0 20 20 3c 74 72 3e 3c 74 64 3e 64 6f 63 3c 74 64    <tr><td>doc<td
122f0 3e 20 20 20 20 54 68 65 20 72 6f 77 69 64 20 6f  >    The rowid o
12300 66 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 20 74  f the document t
12310 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  hat contains the
12320 20 74 65 72 6d 20 69 6e 73 74 61 6e 63 65 2e 0a   term instance..
12330 20 20 3c 74 72 3e 3c 74 64 3e 63 6f 6c 3c 74 64    <tr><td>col<td
12340 3e 20 20 20 20 54 68 65 20 6e 61 6d 65 20 6f 66  >    The name of
12350 20 74 68 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74   the column that
12360 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
12370 72 6d 20 69 6e 73 74 61 6e 63 65 2e 0a 20 20 3c  rm instance..  <
12380 74 72 3e 3c 74 64 3e 6f 66 66 73 65 74 3c 74 64  tr><td>offset<td
12390 3e 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74  > The index of t
123a0 68 65 20 74 65 72 6d 20 69 6e 73 74 61 6e 63 65  he term instance
123b0 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6c 75   within its colu
123c0 6d 6e 2e 20 54 65 72 6d 73 20 0a 20 20 20 20 20  mn. Terms .     
123d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
123e0 61 72 65 20 6e 75 6d 62 65 72 65 64 20 69 6e 20  are numbered in 
123f0 6f 72 64 65 72 20 6f 66 20 6f 63 63 75 72 72 65  order of occurre
12400 6e 63 65 20 73 74 61 72 74 69 6e 67 20 66 72 6f  nce starting fro
12410 6d 20 30 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c  m 0..</table>..<
12420 70 3e 20 49 66 20 74 68 65 20 46 54 53 35 20 74  p> If the FTS5 t
12430 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  able is created 
12440 77 69 74 68 20 74 68 65 20 27 64 65 74 61 69 6c  with the 'detail
12450 27 20 6f 70 74 69 6f 6e 20 73 65 74 20 74 6f 20  ' option set to 
12460 27 63 6f 6c 27 2c 20 74 68 65 6e 0a 74 68 65 20  'col', then.the 
12470 3c 69 3e 6f 66 66 73 65 74 3c 2f 69 3e 20 63 6f  <i>offset</i> co
12480 6c 75 6d 6e 20 6f 66 20 61 6e 20 69 6e 73 74 61  lumn of an insta
12490 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nce virtual tabl
124a0 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e  e always contain
124b0 73 20 4e 55 4c 4c 2e 0a 49 6e 20 74 68 69 73 20  s NULL..In this 
124c0 63 61 73 65 20 74 68 65 72 65 20 69 73 20 6f 6e  case there is on
124d0 65 20 72 6f 77 20 69 6e 20 74 68 65 20 74 61 62  e row in the tab
124e0 6c 65 20 66 6f 72 20 65 61 63 68 20 75 6e 69 71  le for each uniq
124f0 75 65 20 74 65 72 6d 2f 64 6f 63 2f 63 6f 6c 20  ue term/doc/col 
12500 0a 63 6f 6d 62 69 6e 61 74 69 6f 6e 2e 20 4f 72  .combination. Or
12510 2c 20 69 66 20 74 68 65 20 46 54 53 35 20 74 61  , if the FTS5 ta
12520 62 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 77  ble is created w
12530 69 74 68 20 27 64 65 74 61 69 6c 27 20 73 65 74  ith 'detail' set
12540 20 74 6f 20 27 6e 6f 6e 65 27 2c 0a 74 68 65 6e   to 'none',.then
12550 20 62 6f 74 68 20 3c 69 3e 6f 66 66 73 65 74 3c   both <i>offset<
12560 2f 69 3e 20 61 6e 64 20 3c 69 3e 63 6f 6c 3c 2f  /i> and <i>col</
12570 69 3e 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  i> always contai
12580 6e 20 4e 55 4c 4c 20 76 61 6c 75 65 73 2e 20 46  n NULL values. F
12590 6f 72 0a 64 65 74 61 69 6c 3d 6e 6f 6e 65 20 46  or.detail=none F
125a0 54 53 35 20 74 61 62 6c 65 73 2c 20 74 68 65 72  TS5 tables, ther
125b0 65 20 69 73 20 6f 6e 65 20 72 6f 77 20 69 6e 20  e is one row in 
125c0 74 68 65 20 66 74 73 35 76 6f 63 61 62 20 74 61  the fts5vocab ta
125d0 62 6c 65 20 66 6f 72 20 65 61 63 68 0a 75 6e 69  ble for each.uni
125e0 71 75 65 20 74 65 72 6d 2f 64 6f 63 20 63 6f 6d  que term/doc com
125f0 62 69 6e 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 45 78  bination...<p>Ex
12600 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
12610 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 41 73 73 75  ck>.  <i>-- Assu
12620 6d 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ming a database 
12630 63 72 65 61 74 65 64 20 75 73 69 6e 67 3a 3c 2f  created using:</
12640 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54  i>.  CREATE VIRT
12650 55 41 4c 20 54 41 42 4c 45 20 66 74 31 20 55 53  UAL TABLE ft1 US
12660 49 4e 47 20 66 74 73 35 28 63 31 2c 20 63 32 29  ING fts5(c1, c2)
12670 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
12680 66 74 31 20 56 41 4c 55 45 53 28 27 61 70 70 6c  ft1 VALUES('appl
12690 65 20 62 61 6e 61 6e 61 20 63 68 65 72 72 79 27  e banana cherry'
126a0 2c 20 27 62 61 6e 61 6e 61 20 62 61 6e 61 6e 61  , 'banana banana
126b0 20 63 68 65 72 72 79 27 29 3b 0a 20 20 49 4e 53   cherry');.  INS
126c0 45 52 54 20 49 4e 54 4f 20 66 74 31 20 56 41 4c  ERT INTO ft1 VAL
126d0 55 45 53 28 27 63 68 65 72 72 79 20 63 68 65 72  UES('cherry cher
126e0 72 79 20 63 68 65 72 72 79 27 2c 20 27 64 61 74  ry cherry', 'dat
126f0 65 20 64 61 74 65 20 64 61 74 65 27 29 3b 0a 0a  e date date');..
12700 20 20 3c 69 3e 2d 2d 20 54 68 65 6e 20 71 75 65    <i>-- Then que
12710 72 79 69 6e 67 20 74 68 65 20 66 6f 6c 6c 6f 77  rying the follow
12720 69 6e 67 20 66 74 73 35 76 6f 63 61 62 20 74 61  ing fts5vocab ta
12730 62 6c 65 20 28 74 79 70 65 20 22 63 6f 6c 22 29  ble (type "col")
12740 20 72 65 74 75 72 6e 73 3a 0a 20 20 2d 2d 0a 20   returns:.  --. 
12750 20 2d 2d 20 20 20 20 61 70 70 6c 65 20 20 7c 20   --    apple  | 
12760 63 31 20 7c 20 31 20 7c 20 31 0a 20 20 2d 2d 20  c1 | 1 | 1.  -- 
12770 20 20 20 62 61 6e 61 6e 61 20 7c 20 63 31 20 7c     banana | c1 |
12780 20 31 20 7c 20 31 0a 20 20 2d 2d 20 20 20 20 62   1 | 1.  --    b
12790 61 6e 61 6e 61 20 7c 20 63 32 20 7c 20 31 20 7c  anana | c2 | 1 |
127a0 20 32 0a 20 20 2d 2d 20 20 20 20 63 68 65 72 72   2.  --    cherr
127b0 79 20 7c 20 63 31 20 7c 20 32 20 7c 20 34 0a 20  y | c1 | 2 | 4. 
127c0 20 2d 2d 20 20 20 20 63 68 65 72 72 79 20 7c 20   --    cherry | 
127d0 63 32 20 7c 20 31 20 7c 20 31 0a 20 20 2d 2d 20  c2 | 1 | 1.  -- 
127e0 20 20 20 64 61 74 65 20 20 20 7c 20 63 33 20 7c     date   | c3 |
127f0 20 31 20 7c 20 33 0a 20 20 2d 2d 3c 2f 69 3e 0a   1 | 3.  --</i>.
12800 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
12810 20 54 41 42 4c 45 20 66 74 31 5f 76 5f 63 6f 6c   TABLE ft1_v_col
12820 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63 61 62   USING fts5vocab
12830 28 66 74 31 2c 20 63 6f 6c 29 3b 0a 0a 20 20 3c  (ft1, col);..  <
12840 69 3e 2d 2d 20 51 75 65 72 79 69 6e 67 20 61 6e  i>-- Querying an
12850 20 66 74 73 35 76 6f 63 61 62 20 74 61 62 6c 65   fts5vocab table
12860 20 6f 66 20 74 79 70 65 20 22 72 6f 77 22 20 72   of type "row" r
12870 65 74 75 72 6e 73 3a 0a 20 20 2d 2d 0a 20 20 2d  eturns:.  --.  -
12880 2d 20 20 20 20 61 70 70 6c 65 20 20 7c 20 31 20  -    apple  | 1 
12890 7c 20 31 0a 20 20 2d 2d 20 20 20 20 62 61 6e 61  | 1.  --    bana
128a0 6e 61 20 7c 20 31 20 7c 20 33 0a 20 20 2d 2d 20  na | 1 | 3.  -- 
128b0 20 20 20 63 68 65 72 72 79 20 7c 20 32 20 7c 20     cherry | 2 | 
128c0 35 0a 20 20 2d 2d 20 20 20 20 64 61 74 65 20 20  5.  --    date  
128d0 20 7c 20 31 20 7c 20 33 0a 20 20 2d 2d 3c 2f 69   | 1 | 3.  --</i
128e0 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
128f0 41 4c 20 54 41 42 4c 45 20 66 74 31 5f 76 5f 72  AL TABLE ft1_v_r
12900 6f 77 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63  ow USING fts5voc
12910 61 62 28 66 74 31 2c 20 72 6f 77 29 3b 0a 0a 20  ab(ft1, row);.. 
12920 20 3c 69 3e 2d 2d 20 41 6e 64 2c 20 66 6f 72 20   <i>-- And, for 
12930 74 79 70 65 20 22 69 6e 73 74 61 6e 63 65 22 0a  type "instance".
12940 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74    INSERT INTO ft
12950 31 20 56 41 4c 55 45 53 28 27 61 70 70 6c 65 20  1 VALUES('apple 
12960 62 61 6e 61 6e 61 20 63 68 65 72 72 79 27 2c 20  banana cherry', 
12970 27 62 61 6e 61 6e 61 20 62 61 6e 61 6e 61 20 63  'banana banana c
12980 68 65 72 72 79 27 29 3b 0a 20 20 49 4e 53 45 52  herry');.  INSER
12990 54 20 49 4e 54 4f 20 66 74 31 20 56 41 4c 55 45  T INTO ft1 VALUE
129a0 53 28 27 63 68 65 72 72 79 20 63 68 65 72 72 79  S('cherry cherry
129b0 20 63 68 65 72 72 79 27 2c 20 27 64 61 74 65 20   cherry', 'date 
129c0 64 61 74 65 20 64 61 74 65 27 29 3b 0a 20 20 2d  date date');.  -
129d0 2d 0a 20 20 2d 2d 20 20 20 20 61 70 70 6c 65 20  -.  --    apple 
129e0 20 7c 20 31 20 7c 20 63 31 20 7c 20 30 0a 20 20   | 1 | c1 | 0.  
129f0 2d 2d 20 20 20 20 62 61 6e 61 6e 61 20 7c 20 31  --    banana | 1
12a00 20 7c 20 63 31 20 7c 20 31 0a 20 20 2d 2d 20 20   | c1 | 1.  --  
12a10 20 20 62 61 6e 61 6e 61 20 7c 20 31 20 7c 20 63    banana | 1 | c
12a20 32 20 7c 20 30 0a 20 20 2d 2d 20 20 20 20 62 61  2 | 0.  --    ba
12a30 6e 61 6e 61 20 7c 20 31 20 7c 20 63 32 20 7c 20  nana | 1 | c2 | 
12a40 31 0a 20 20 2d 2d 20 20 20 20 63 68 65 72 72 79  1.  --    cherry
12a50 20 7c 20 31 20 7c 20 63 31 20 7c 20 32 0a 20 20   | 1 | c1 | 2.  
12a60 2d 2d 20 20 20 20 63 68 65 72 72 79 20 7c 20 31  --    cherry | 1
12a70 20 7c 20 63 32 20 7c 20 32 0a 20 20 2d 2d 20 20   | c2 | 2.  --  
12a80 20 20 63 68 65 72 72 79 20 7c 20 32 20 7c 20 63    cherry | 2 | c
12a90 31 20 7c 20 30 0a 20 20 2d 2d 20 20 20 20 63 68  1 | 0.  --    ch
12aa0 65 72 72 79 20 7c 20 32 20 7c 20 63 31 20 7c 20  erry | 2 | c1 | 
12ab0 31 0a 20 20 2d 2d 20 20 20 20 63 68 65 72 72 79  1.  --    cherry
12ac0 20 7c 20 32 20 7c 20 63 31 20 7c 20 32 0a 20 20   | 2 | c1 | 2.  
12ad0 2d 2d 20 20 20 20 64 61 74 65 20 20 20 7c 20 32  --    date   | 2
12ae0 20 7c 20 63 32 20 7c 20 30 0a 20 20 2d 2d 20 20   | c2 | 0.  --  
12af0 20 20 64 61 74 65 20 20 20 7c 20 32 20 7c 20 63    date   | 2 | c
12b00 32 20 7c 20 31 0a 20 20 2d 2d 20 20 20 20 64 61  2 | 1.  --    da
12b10 74 65 20 20 20 7c 20 32 20 7c 20 63 32 20 7c 20  te   | 2 | c2 | 
12b20 32 0a 20 20 2d 2d 3c 2f 69 3e 0a 20 20 43 52 45  2.  --</i>.  CRE
12b30 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
12b40 45 20 66 74 31 5f 76 5f 69 6e 73 74 61 6e 63 65  E ft1_v_instance
12b50 20 55 53 49 4e 47 20 66 74 73 35 76 6f 63 61 62   USING fts5vocab
12b60 28 66 74 31 2c 20 69 6e 73 74 61 6e 63 65 29 3b  (ft1, instance);
12b70 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 0a  .</codeblock>...
12b80 3c 68 31 20 69 64 3d 61 70 70 65 6e 64 69 78 5f  <h1 id=appendix_
12b90 61 20 6e 6f 6e 75 6d 62 65 72 20 74 61 67 73 3d  a nonumber tags=
12ba0 22 63 6f 6d 70 61 72 69 73 6f 6e 20 77 69 74 68  "comparison with
12bb0 20 66 74 73 34 22 3e 0a 20 20 41 70 70 65 6e 64   fts4">.  Append
12bc0 69 78 20 41 3a 20 43 6f 6d 70 61 72 69 73 6f 6e  ix A: Comparison
12bd0 20 77 69 74 68 20 46 54 53 33 2f 34 0a 3c 2f 68   with FTS3/4.</h
12be0 31 3e 0a 0a 3c 70 3e 20 41 6c 73 6f 20 61 76 61  1>..<p> Also ava
12bf0 69 6c 61 62 6c 65 20 69 73 20 74 68 65 20 73 69  ilable is the si
12c00 6d 69 6c 61 72 20 62 75 74 20 6d 6f 72 65 20 6d  milar but more m
12c10 61 74 75 72 65 20 5b 66 74 73 33 20 7c 20 46 54  ature [fts3 | FT
12c20 53 33 2f 34 5d 20 6d 6f 64 75 6c 65 2e 20 0a 46  S3/4] module. .F
12c30 54 53 35 20 69 73 20 61 20 6e 65 77 20 76 65 72  TS5 is a new ver
12c40 73 69 6f 6e 20 6f 66 20 46 54 53 34 20 74 68 61  sion of FTS4 tha
12c50 74 20 69 6e 63 6c 75 64 65 73 20 76 61 72 69 6f  t includes vario
12c60 75 73 20 66 69 78 65 73 20 61 6e 64 20 73 6f 6c  us fixes and sol
12c70 75 74 69 6f 6e 73 20 66 6f 72 20 0a 70 72 6f 62  utions for .prob
12c80 6c 65 6d 73 20 74 68 61 74 20 63 6f 75 6c 64 20  lems that could 
12c90 6e 6f 74 20 62 65 20 66 69 78 65 64 20 69 6e 20  not be fixed in 
12ca0 46 54 53 34 20 77 69 74 68 6f 75 74 20 73 61 63  FTS4 without sac
12cb0 72 69 66 69 63 69 6e 67 20 62 61 63 6b 77 61 72  rificing backwar
12cc0 64 73 20 0a 63 6f 6d 70 61 74 69 62 69 6c 69 74  ds .compatibilit
12cd0 79 2e 20 53 6f 6d 65 20 6f 66 20 74 68 65 73 65  y. Some of these
12ce0 20 70 72 6f 62 6c 65 6d 73 20 61 72 65 20 0a 5b   problems are .[
12cf0 66 74 73 35 20 74 65 63 68 6e 69 63 61 6c 20 64  fts5 technical d
12d00 69 66 66 65 72 65 6e 63 65 73 20 7c 20 64 65 73  ifferences | des
12d10 63 72 69 62 65 64 20 62 65 6c 6f 77 5d 2e 0a 0a  cribed below]...
12d20 3c 68 32 20 6e 6f 6e 75 6d 62 65 72 3e 20 41 70  <h2 nonumber> Ap
12d30 70 6c 69 63 61 74 69 6f 6e 20 50 6f 72 74 69 6e  plication Portin
12d40 67 20 47 75 69 64 65 20 3c 2f 68 32 3e 0a 0a 3c  g Guide </h2>..<
12d50 70 3e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 75  p> In order to u
12d60 73 65 20 46 54 53 35 20 69 6e 73 74 65 61 64 20  se FTS5 instead 
12d70 6f 66 20 46 54 53 33 20 6f 72 20 46 54 53 34 2c  of FTS3 or FTS4,
12d80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
12d90 75 61 6c 6c 79 20 72 65 71 75 69 72 65 0a 6d 69  ually require.mi
12da0 6e 69 6d 61 6c 20 6d 6f 64 69 66 69 63 61 74 69  nimal modificati
12db0 6f 6e 73 2e 20 4d 6f 73 74 20 6f 66 20 74 68 65  ons. Most of the
12dc0 73 65 20 66 61 6c 6c 20 69 6e 74 6f 20 74 68 72  se fall into thr
12dd0 65 65 20 63 61 74 65 67 6f 72 69 65 73 20 2d 20  ee categories - 
12de0 63 68 61 6e 67 65 73 0a 72 65 71 75 69 72 65 64  changes.required
12df0 20 74 6f 20 74 68 65 20 43 52 45 41 54 45 20 56   to the CREATE V
12e00 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61  IRTUAL TABLE sta
12e10 74 65 6d 65 6e 74 20 75 73 65 64 20 74 6f 20 63  tement used to c
12e20 72 65 61 74 65 20 74 68 65 20 46 54 53 20 74 61  reate the FTS ta
12e30 62 6c 65 2c 0a 63 68 61 6e 67 65 73 20 72 65 71  ble,.changes req
12e40 75 69 72 65 64 20 74 6f 20 53 45 4c 45 43 54 20  uired to SELECT 
12e50 71 75 65 72 69 65 73 20 75 73 65 64 20 74 6f 20  queries used to 
12e60 65 78 65 63 75 74 65 20 71 75 65 72 69 65 73 20  execute queries 
12e70 61 67 61 69 6e 73 74 20 74 68 65 20 74 61 62 6c  against the tabl
12e80 65 2c 0a 61 6e 64 20 63 68 61 6e 67 65 73 20 72  e,.and changes r
12e90 65 71 75 69 72 65 64 20 74 6f 20 61 70 70 6c 69  equired to appli
12ea0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
12eb0 20 5b 46 54 53 20 61 75 78 69 6c 69 61 72 79 20   [FTS auxiliary 
12ec0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 0a 3c 68 33  functions]...<h3
12ed0 20 6e 6f 6e 75 6d 62 65 72 3e 20 43 68 61 6e 67   nonumber> Chang
12ee0 65 73 20 74 6f 20 43 52 45 41 54 45 20 56 49 52  es to CREATE VIR
12ef0 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65  TUAL TABLE state
12f00 6d 65 6e 74 73 20 3c 2f 68 33 3e 0a 0a 3c 6f 6c  ments </h3>..<ol
12f10 3e 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 6d 6f  >.<li> <p>The mo
12f20 64 75 6c 65 20 6e 61 6d 65 20 6d 75 73 74 20 62  dule name must b
12f30 65 20 63 68 61 6e 67 65 64 20 66 72 6f 6d 20 22  e changed from "
12f40 66 74 73 33 22 20 6f 72 20 22 66 74 73 34 22 20  fts3" or "fts4" 
12f50 74 6f 20 22 66 74 73 35 22 2e 0a 0a 3c 6c 69 3e  to "fts5"...<li>
12f60 20 3c 70 3e 41 6c 6c 20 74 79 70 65 20 69 6e 66   <p>All type inf
12f70 6f 72 6d 61 74 69 6f 6e 20 6f 72 20 63 6f 6e 73  ormation or cons
12f80 74 72 61 69 6e 74 20 73 70 65 63 69 66 69 63 61  traint specifica
12f90 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 72 65  tions must be re
12fa0 6d 6f 76 65 64 20 66 72 6f 6d 0a 20 20 20 20 20  moved from.     
12fb0 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f  column definitio
12fc0 6e 73 2e 20 46 54 53 33 2f 34 20 69 67 6e 6f 72  ns. FTS3/4 ignor
12fd0 65 73 20 65 76 65 72 79 74 68 69 6e 67 20 66 6f  es everything fo
12fe0 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 6f 6c 75  llowing the colu
12ff0 6d 6e 20 6e 61 6d 65 20 69 6e 0a 20 20 20 20 20  mn name in.     
13000 61 20 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74  a column definit
13010 69 6f 6e 2c 20 46 54 53 35 20 61 74 74 65 6d 70  ion, FTS5 attemp
13020 74 73 20 74 6f 20 70 61 72 73 65 20 69 74 20 28  ts to parse it (
13030 61 6e 64 20 77 69 6c 6c 20 72 65 70 6f 72 74 20  and will report 
13040 61 6e 20 65 72 72 6f 72 0a 20 20 20 20 20 69 66  an error.     if
13050 20 69 74 20 66 61 69 6c 73 20 74 6f 29 2e 0a 0a   it fails to)...
13060 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 22 6d 61 74  <li> <p>The "mat
13070 63 68 69 6e 66 6f 3d 66 74 73 33 22 20 6f 70 74  chinfo=fts3" opt
13080 69 6f 6e 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  ion is not avail
13090 61 62 6c 65 2e 20 54 68 65 20 0a 20 20 20 20 20  able. The .     
130a0 5b 46 54 53 35 20 63 6f 6c 75 6d 6e 73 69 7a 65  [FTS5 columnsize
130b0 20 6f 70 74 69 6f 6e 20 7c 20 22 63 6f 6c 75 6d   option | "colum
130c0 6e 73 69 7a 65 3d 30 22 5d 20 6f 70 74 69 6f 6e  nsize=0"] option
130d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a   is equivalent..
130e0 0a 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 6e 6f 74  .<li> <p>The not
130f0 69 6e 64 65 78 65 64 3d 20 6f 70 74 69 6f 6e 20  indexed= option 
13100 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
13110 2e 20 41 64 64 69 6e 67 20 5b 75 6e 69 6e 64 65  . Adding [uninde
13120 78 65 64 20 7c 20 55 4e 49 4e 44 45 58 45 44 5d  xed | UNINDEXED]
13130 0a 20 20 20 20 20 74 6f 20 74 68 65 20 63 6f 6c  .     to the col
13140 75 6d 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20 69  umn definition i
13150 73 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 0a 3c  s equivalent...<
13160 6c 69 3e 20 3c 70 3e 54 68 65 20 49 43 55 20 74  li> <p>The ICU t
13170 6f 6b 65 6e 69 7a 65 72 20 69 73 20 6e 6f 74 20  okenizer is not 
13180 61 76 61 69 6c 61 62 6c 65 2e 0a 0a 3c 6c 69 3e  available...<li>
13190 20 3c 70 3e 54 68 65 20 63 6f 6d 70 72 65 73 73   <p>The compress
131a0 3d 2c 20 75 6e 63 6f 6d 70 72 65 73 73 3d 20 61  =, uncompress= a
131b0 6e 64 20 6c 61 6e 67 75 61 67 65 69 64 3d 20 6f  nd languageid= o
131c0 70 74 69 6f 6e 73 20 61 72 65 20 6e 6f 74 20 61  ptions are not a
131d0 76 61 69 6c 61 62 6c 65 2e 0a 20 20 20 20 20 54  vailable..     T
131e0 68 65 72 65 20 69 73 20 61 73 20 6f 66 20 79 65  here is as of ye
131f0 74 20 6e 6f 20 65 71 75 69 76 61 6c 65 6e 74 20  t no equivalent 
13200 66 6f 72 20 74 68 65 69 72 20 66 75 6e 63 74 69  for their functi
13210 6f 6e 61 6c 69 74 79 2e 0a 3c 2f 6f 6c 3e 0a 0a  onality..</ol>..
13220 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69  <codeblock>.  <i
13230 3e 20 2d 2d 20 46 54 53 33 2f 34 20 73 74 61 74  > -- FTS3/4 stat
13240 65 6d 65 6e 74 20 3c 2f 69 3e 0a 20 20 43 52 45  ement </i>.  CRE
13250 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
13260 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 34 28  E t1 USING fts4(
13270 0a 20 20 20 20 6c 69 6e 6b 69 64 20 49 4e 54 45  .    linkid INTE
13280 47 45 52 2c 0a 20 20 20 20 68 65 61 64 65 72 20  GER,.    header 
13290 43 48 41 52 28 32 30 29 2c 0a 20 20 20 20 74 65  CHAR(20),.    te
132a0 78 74 20 56 41 52 43 48 41 52 2c 0a 20 20 20 20  xt VARCHAR,.    
132b0 6e 6f 74 69 6e 64 65 78 65 64 3d 6c 69 6e 6b 69  notindexed=linki
132c0 64 2c 0a 20 20 20 20 6d 61 74 63 68 69 6e 66 6f  d,.    matchinfo
132d0 3d 66 74 73 33 2c 0a 20 20 20 20 74 6f 6b 65 6e  =fts3,.    token
132e0 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36 31 0a 20  izer=unicode61. 
132f0 20 29 3b 0a 0a 20 20 3c 69 3e 20 2d 2d 20 46 54   );..  <i> -- FT
13300 53 35 20 65 71 75 69 76 61 6c 65 6e 74 20 28 6e  S5 equivalent (n
13310 6f 74 65 20 2d 20 74 68 65 20 22 74 6f 6b 65 6e  ote - the "token
13320 69 7a 65 72 3d 75 6e 69 63 6f 64 65 36 31 22 20  izer=unicode61" 
13330 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 3c 2f 69  option is not</i
13340 3e 0a 20 20 3c 69 3e 20 2d 2d 20 72 65 71 75 69  >.  <i> -- requi
13350 72 65 64 20 61 73 20 74 68 69 73 20 69 73 20 74  red as this is t
13360 68 65 20 64 65 66 61 75 6c 74 20 66 6f 72 20 46  he default for F
13370 54 53 35 20 61 6e 79 77 61 79 29 3c 2f 69 3e 0a  TS5 anyway)</i>.
13380 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
13390 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20   TABLE t1 USING 
133a0 66 74 73 35 28 0a 20 20 20 20 6c 69 6e 6b 69 64  fts5(.    linkid
133b0 20 55 4e 49 4e 44 45 58 45 44 2c 0a 20 20 20 20   UNINDEXED,.    
133c0 68 65 61 64 65 72 2c 0a 20 20 20 20 74 65 78 74  header,.    text
133d0 2c 0a 20 20 20 20 63 6f 6c 75 6d 6e 73 69 7a 65  ,.    columnsize
133e0 3d 30 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65 62 6c  =0.  );.</codebl
133f0 6f 63 6b 3e 0a 0a 3c 68 33 20 6e 6f 6e 75 6d 62  ock>..<h3 nonumb
13400 65 72 3e 20 43 68 61 6e 67 65 73 20 74 6f 20 53  er> Changes to S
13410 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
13420 20 3c 2f 68 33 3e 0a 0a 3c 6f 6c 3e 0a 20 20 3c   </h3>..<ol>.  <
13430 6c 69 3e 20 3c 70 3e 54 68 65 20 22 64 6f 63 69  li> <p>The "doci
13440 64 22 20 61 6c 69 61 73 20 64 6f 65 73 20 6e 6f  d" alias does no
13450 74 20 65 78 69 73 74 2e 20 41 70 70 6c 69 63 61  t exist. Applica
13460 74 69 6f 6e 73 20 6d 75 73 74 20 75 73 65 20 22  tions must use "
13470 72 6f 77 69 64 22 0a 20 20 20 20 20 20 20 20 20  rowid".         
13480 20 69 6e 73 74 65 61 64 2e 0a 0a 20 20 3c 6c 69   instead...  <li
13490 3e 20 3c 70 3e 54 68 65 20 62 65 68 61 76 69 6f  > <p>The behavio
134a0 75 72 20 6f 66 20 71 75 65 72 69 65 73 20 77 68  ur of queries wh
134b0 65 6e 20 61 20 63 6f 6c 75 6d 6e 2d 66 69 6c 74  en a column-filt
134c0 65 72 20 69 73 20 73 70 65 63 69 66 69 65 64 20  er is specified 
134d0 62 6f 74 68 20 61 73 0a 20 20 20 20 20 20 20 20  both as.        
134e0 20 20 70 61 72 74 20 6f 66 20 74 68 65 20 46 54    part of the FT
134f0 53 20 71 75 65 72 79 20 61 6e 64 20 62 79 20 75  S query and by u
13500 73 69 6e 67 20 61 20 63 6f 6c 75 6d 6e 20 61 73  sing a column as
13510 20 74 68 65 20 4c 48 53 20 6f 66 20 61 20 4d 41   the LHS of a MA
13520 54 43 48 0a 20 20 20 20 20 20 20 20 20 20 6f 70  TCH.          op
13530 65 72 61 74 6f 72 20 69 73 20 73 6c 69 67 68 74  erator is slight
13540 6c 79 20 64 69 66 66 65 72 65 6e 74 2e 20 46 6f  ly different. Fo
13550 72 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 63  r a table with c
13560 6f 6c 75 6d 6e 73 20 22 61 22 20 61 6e 64 20 22  olumns "a" and "
13570 62 22 0a 20 20 20 20 20 20 20 20 20 20 61 6e 64  b".          and
13580 20 61 20 71 75 65 72 79 20 73 69 6d 69 6c 61 72   a query similar
13590 20 74 6f 3a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e   to:.<codeblock>
135a0 0a 20 20 20 2e 2e 2e 20 61 20 4d 41 54 43 48 20  .   ... a MATCH 
135b0 27 62 3a 20 73 74 72 69 6e 67 27 0a 3c 2f 63 6f  'b: string'.</co
135c0 64 65 62 6c 6f 63 6b 3e 0a 20 20 20 20 20 20 20  deblock>.       
135d0 3c 70 3e 46 54 53 33 2f 34 20 73 65 61 72 63 68  <p>FTS3/4 search
135e0 65 73 20 66 6f 72 20 6d 61 74 63 68 65 73 20 69  es for matches i
135f0 6e 20 63 6f 6c 75 6d 6e 20 22 62 22 2e 20 48 6f  n column "b". Ho
13600 77 65 76 65 72 2c 20 46 54 53 35 20 61 6c 77 61  wever, FTS5 alwa
13610 79 73 0a 20 20 20 20 20 20 20 20 20 20 72 65 74  ys.          ret
13620 75 72 6e 73 20 7a 65 72 6f 20 72 6f 77 73 2c 20  urns zero rows, 
13630 61 73 20 72 65 73 75 6c 74 73 20 61 72 65 20 66  as results are f
13640 69 72 73 74 20 66 69 6c 74 65 72 65 64 20 66 6f  irst filtered fo
13650 72 20 63 6f 6c 75 6d 6e 20 22 62 22 2c 20 74 68  r column "b", th
13660 65 6e 0a 20 20 20 20 20 20 20 20 20 20 66 6f 72  en.          for
13670 20 63 6f 6c 75 6d 6e 20 22 61 22 2c 20 6c 65 61   column "a", lea
13680 76 69 6e 67 20 6e 6f 20 72 65 73 75 6c 74 73 2e  ving no results.
13690 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
136a0 20 69 6e 20 46 54 53 33 2f 34 20 74 68 65 0a 20   in FTS3/4 the. 
136b0 20 20 20 20 20 20 20 20 20 69 6e 6e 65 72 20 66           inner f
136c0 69 6c 74 65 72 20 6f 76 65 72 72 69 64 65 73 20  ilter overrides 
136d0 74 68 65 20 6f 75 74 65 72 2c 20 69 6e 20 46 54  the outer, in FT
136e0 53 35 20 62 6f 74 68 20 66 69 6c 74 65 72 73 20  S5 both filters 
136f0 61 72 65 20 61 70 70 6c 69 65 64 2e 0a 0a 20 20  are applied...  
13700 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 46 54 53 20  <li> <p>The FTS 
13710 71 75 65 72 79 20 73 79 6e 74 61 78 20 28 72 69  query syntax (ri
13720 67 68 74 20 68 61 6e 64 20 73 69 64 65 20 6f 66  ght hand side of
13730 20 74 68 65 20 4d 41 54 43 48 20 6f 70 65 72 61   the MATCH opera
13740 74 6f 72 29 20 68 61 73 0a 20 20 20 20 20 20 20  tor) has.       
13750 20 20 20 63 68 61 6e 67 65 64 20 69 6e 20 73 6f     changed in so
13760 6d 65 20 77 61 79 73 2e 20 54 68 65 20 46 54 53  me ways. The FTS
13770 35 20 73 79 6e 74 61 78 20 69 73 20 71 75 69 74  5 syntax is quit
13780 65 20 63 6c 6f 73 65 20 74 6f 20 74 68 65 20 46  e close to the F
13790 54 53 34 0a 20 20 20 20 20 20 20 20 20 20 22 65  TS4.          "e
137a0 6e 68 61 6e 63 65 64 20 73 79 6e 74 61 78 22 2e  nhanced syntax".
137b0 20 54 68 65 20 6d 61 69 6e 20 64 69 66 66 65 72   The main differ
137c0 65 6e 63 65 20 69 73 20 74 68 61 74 20 46 54 53  ence is that FTS
137d0 35 20 69 73 20 66 75 73 73 69 65 72 20 0a 20 20  5 is fussier .  
137e0 20 20 20 20 20 20 20 20 61 62 6f 75 74 20 75 6e          about un
137f0 72 65 63 6f 67 6e 69 7a 65 64 20 70 75 6e 63 74  recognized punct
13800 75 61 74 69 6f 6e 20 63 68 61 72 61 63 74 65 72  uation character
13810 73 20 61 6e 64 20 73 69 6d 69 6c 61 72 20 77 69  s and similar wi
13820 74 68 69 6e 20 71 75 65 72 79 0a 20 20 20 20 20  thin query.     
13830 20 20 20 20 20 73 74 72 69 6e 67 73 2e 20 4d 6f       strings. Mo
13840 73 74 20 71 75 65 72 69 65 73 20 74 68 61 74 20  st queries that 
13850 77 6f 72 6b 20 77 69 74 68 20 46 54 53 33 2f 34  work with FTS3/4
13860 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 77 6f 72   should also wor
13870 6b 20 77 69 74 68 0a 20 20 20 20 20 20 20 20 20  k with.         
13880 20 46 54 53 35 2c 20 61 6e 64 20 74 68 6f 73 65   FTS5, and those
13890 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 68 6f   that do not sho
138a0 75 6c 64 20 72 65 74 75 72 6e 20 70 61 72 73 65  uld return parse
138b0 20 65 72 72 6f 72 73 2e 0a 3c 2f 6f 6c 3e 0a 0a   errors..</ol>..
138c0 3c 68 33 20 6e 6f 6e 75 6d 62 65 72 3e 20 41 75  <h3 nonumber> Au
138d0 78 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f 6e  xiliary Function
138e0 20 43 68 61 6e 67 65 73 20 3c 2f 68 33 3e 0a 0a   Changes </h3>..
138f0 3c 70 3e 20 46 54 53 35 20 68 61 73 20 6e 6f 20  <p> FTS5 has no 
13900 6d 61 74 63 68 69 6e 66 6f 28 29 20 6f 72 20 6f  matchinfo() or o
13910 66 66 73 65 74 73 28 29 20 66 75 6e 63 74 69 6f  ffsets() functio
13920 6e 2c 20 61 6e 64 20 74 68 65 20 73 6e 69 70 70  n, and the snipp
13930 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 0a 69 73  et() function.is
13940 20 6e 6f 74 20 61 73 20 66 75 6c 6c 79 2d 66 65   not as fully-fe
13950 61 74 75 72 65 64 20 61 73 20 69 6e 20 46 54 53  atured as in FTS
13960 33 2f 34 2e 20 48 6f 77 65 76 65 72 2c 20 73 69  3/4. However, si
13970 6e 63 65 20 46 54 53 35 20 64 6f 65 73 20 70 72  nce FTS5 does pr
13980 6f 76 69 64 65 20 0a 61 6e 20 41 50 49 20 61 6c  ovide .an API al
13990 6c 6f 77 69 6e 67 20 61 70 70 6c 69 63 61 74 69  lowing applicati
139a0 6f 6e 73 20 74 6f 20 63 72 65 61 74 65 20 5b 63  ons to create [c
139b0 75 73 74 6f 6d 20 61 75 78 69 6c 69 61 72 79 20  ustom auxiliary 
139c0 66 75 6e 63 74 69 6f 6e 73 5d 2c 20 61 6e 79 0a  functions], any.
139d0 72 65 71 75 69 72 65 64 20 66 75 6e 63 74 69 6f  required functio
139e0 6e 61 6c 69 74 79 20 6d 61 79 20 62 65 20 69 6d  nality may be im
139f0 70 6c 65 6d 65 6e 74 65 64 20 77 69 74 68 69 6e  plemented within
13a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13a10 20 63 6f 64 65 2e 0a 0a 3c 70 3e 20 54 68 65 20   code...<p> The 
13a20 73 65 74 20 6f 66 20 62 75 69 6c 74 2d 69 6e 20  set of built-in 
13a30 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
13a40 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
13a50 46 54 53 35 20 6d 61 79 20 62 65 20 0a 69 6d 70  FTS5 may be .imp
13a60 72 6f 76 65 64 20 75 70 6f 6e 20 69 6e 20 74 68  roved upon in th
13a70 65 20 66 75 74 75 72 65 2e 0a 0a 3c 68 33 20 6e  e future...<h3 n
13a80 6f 6e 75 6d 62 65 72 3e 20 4f 74 68 65 72 20 49  onumber> Other I
13a90 73 73 75 65 73 3c 2f 68 33 3e 0a 0a 3c 6f 6c 3e  ssues</h3>..<ol>
13aa0 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 66  .  <li><p> The f
13ab0 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 70 72 6f  unctionality pro
13ac0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 74 73  vided by the fts
13ad0 34 61 75 78 20 6d 6f 64 75 6c 65 20 69 73 20 6e  4aux module is n
13ae0 6f 77 20 70 72 6f 76 69 64 65 64 0a 20 20 20 20  ow provided.    
13af0 20 20 20 20 20 20 62 79 20 5b 66 74 73 35 76 6f        by [fts5vo
13b00 63 61 62 5d 2e 20 54 68 65 20 73 63 68 65 6d 61  cab]. The schema
13b10 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 74 61   of these two ta
13b20 62 6c 65 73 20 69 73 20 73 6c 69 67 68 74 6c 79  bles is slightly
13b30 20 64 69 66 66 65 72 65 6e 74 2e 0a 0a 20 20 3c   different...  <
13b40 6c 69 3e 3c 70 3e 20 54 68 65 20 46 54 53 33 2f  li><p> The FTS3/
13b50 34 20 22 6d 65 72 67 65 3d 58 2c 59 22 20 63 6f  4 "merge=X,Y" co
13b60 6d 6d 61 6e 64 20 68 61 73 20 62 65 65 6e 20 72  mmand has been r
13b70 65 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 0a  eplaced by the .
13b80 20 20 20 20 20 20 20 20 20 20 5b 46 54 53 35 20            [FTS5 
13b90 6d 65 72 67 65 20 63 6f 6d 6d 61 6e 64 5d 2e 0a  merge command]..
13ba0 0a 20 20 3c 6c 69 3e 3c 70 3e 20 54 68 65 20 46  .  <li><p> The F
13bb0 54 53 33 2f 34 20 22 61 75 74 6f 6d 65 72 67 65  TS3/4 "automerge
13bc0 3d 58 22 20 63 6f 6d 6d 61 6e 64 20 68 61 73 20  =X" command has 
13bd0 62 65 65 6e 20 72 65 70 6c 61 63 65 64 20 62 79  been replaced by
13be0 20 74 68 65 20 0a 20 20 20 20 20 20 20 20 20 20   the .          
13bf0 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65 20  [FTS5 automerge 
13c00 6f 70 74 69 6f 6e 5d 2e 0a 3c 2f 6f 6c 3e 0a 0a  option]..</ol>..
13c10 3c 68 32 20 6e 6f 6e 75 6d 62 65 72 20 74 61 67  <h2 nonumber tag
13c20 73 3d 22 66 74 73 35 20 74 65 63 68 6e 69 63 61  s="fts5 technica
13c30 6c 20 64 69 66 66 65 72 65 6e 63 65 73 22 3e 20  l differences"> 
13c40 0a 20 20 53 75 6d 6d 61 72 79 20 6f 66 20 54 65  .  Summary of Te
13c50 63 68 6e 69 63 61 6c 20 44 69 66 66 65 72 65 6e  chnical Differen
13c60 63 65 73 20 0a 3c 2f 68 32 3e 0a 0a 3c 70 3e 46  ces .</h2>..<p>F
13c70 54 53 35 20 69 73 20 73 69 6d 69 6c 61 72 20 74  TS5 is similar t
13c80 6f 20 46 54 53 33 2f 34 20 69 6e 20 74 68 61 74  o FTS3/4 in that
13c90 20 74 68 65 20 70 72 69 6d 61 72 79 20 74 61 73   the primary tas
13ca0 6b 20 6f 66 20 65 61 63 68 20 69 73 20 74 6f 20  k of each is to 
13cb0 6d 61 69 6e 74 61 69 6e 0a 61 6e 20 69 6e 64 65  maintain.an inde
13cc0 78 20 6d 61 70 70 69 6e 67 20 66 72 6f 6d 20 65  x mapping from e
13cd0 61 63 68 20 75 6e 69 71 75 65 20 74 6f 6b 65 6e  ach unique token
13ce0 20 74 6f 20 61 20 6c 69 73 74 20 6f 66 20 69 6e   to a list of in
13cf0 73 74 61 6e 63 65 73 20 6f 66 20 74 68 61 74 20  stances of that 
13d00 74 6f 6b 65 6e 20 0a 77 69 74 68 69 6e 20 61 20  token .within a 
13d10 73 65 74 20 6f 66 20 64 6f 63 75 6d 65 6e 74 73  set of documents
13d20 2c 20 77 68 65 72 65 20 65 61 63 68 20 69 6e 73  , where each ins
13d30 74 61 6e 63 65 20 69 73 20 69 64 65 6e 74 69 66  tance is identif
13d40 69 65 64 20 62 79 20 74 68 65 20 64 6f 63 75 6d  ied by the docum
13d50 65 6e 74 20 0a 69 6e 20 77 68 69 63 68 20 69 74  ent .in which it
13d60 20 61 70 70 65 61 72 73 20 61 6e 64 20 69 74 73   appears and its
13d70 20 70 6f 73 69 74 69 6f 6e 20 77 69 74 68 69 6e   position within
13d80 20 74 68 61 74 20 64 6f 63 75 6d 65 6e 74 2e 20   that document. 
13d90 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63  For example:..<c
13da0 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d  odeblock>.  <i>-
13db0 2d 20 47 69 76 65 6e 20 74 68 65 20 66 6f 6c 6c  - Given the foll
13dc0 6f 77 69 6e 67 20 53 51 4c 3a 3c 2f 69 3e 0a 20  owing SQL:</i>. 
13dd0 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
13de0 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20 66  TABLE ft USING f
13df0 74 73 35 28 61 2c 20 62 29 3b 0a 20 20 49 4e 53  ts5(a, b);.  INS
13e00 45 52 54 20 49 4e 54 4f 20 66 74 28 72 6f 77 69  ERT INTO ft(rowi
13e10 64 2c 20 61 2c 20 62 29 20 56 41 4c 55 45 53 28  d, a, b) VALUES(
13e20 31 2c 20 27 58 20 59 27 2c 20 27 59 20 5a 27 29  1, 'X Y', 'Y Z')
13e30 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  ;.  INSERT INTO 
13e40 66 74 28 72 6f 77 69 64 2c 20 61 2c 20 62 29 20  ft(rowid, a, b) 
13e50 56 41 4c 55 45 53 28 32 2c 20 27 41 20 5a 27 2c  VALUES(2, 'A Z',
13e60 20 27 59 20 59 27 29 3b 0a 0a 20 20 3c 69 3e 2d   'Y Y');..  <i>-
13e70 2d 20 54 68 65 20 46 54 53 35 20 6d 6f 64 75 6c  - The FTS5 modul
13e80 65 20 63 72 65 61 74 65 73 20 74 68 65 20 66 6f  e creates the fo
13e90 6c 6c 6f 77 69 6e 67 20 6d 61 70 70 69 6e 67 20  llowing mapping 
13ea0 6f 6e 20 64 69 73 6b 3a 3c 2f 69 3e 0a 20 20 41  on disk:</i>.  A
13eb0 20 2d 2d 26 67 74 3b 20 28 32 2c 20 30 2c 20 30   --&gt; (2, 0, 0
13ec0 29 0a 20 20 58 20 2d 2d 26 67 74 3b 20 28 31 2c  ).  X --&gt; (1,
13ed0 20 30 2c 20 30 29 0a 20 20 59 20 2d 2d 26 67 74   0, 0).  Y --&gt
13ee0 3b 20 28 31 2c 20 30 2c 20 31 29 20 28 31 2c 20  ; (1, 0, 1) (1, 
13ef0 31 2c 20 30 29 20 28 32 2c 20 31 2c 20 30 29 20  1, 0) (2, 1, 0) 
13f00 28 32 2c 20 31 2c 20 31 29 0a 20 20 5a 20 2d 2d  (2, 1, 1).  Z --
13f10 26 67 74 3b 20 28 31 2c 20 31 2c 20 31 29 20 28  &gt; (1, 1, 1) (
13f20 32 2c 20 30 2c 20 31 29 0a 3c 2f 63 6f 64 65 62  2, 0, 1).</codeb
13f30 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 6e 20 74 68 65  lock>..<p>In the
13f40 20 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 2c 20   example above, 
13f50 65 61 63 68 20 74 72 69 70 6c 65 20 69 64 65 6e  each triple iden
13f60 74 69 66 69 65 73 20 74 68 65 20 6c 6f 63 61 74  tifies the locat
13f70 69 6f 6e 20 6f 66 20 61 20 74 6f 6b 65 6e 0a 69  ion of a token.i
13f80 6e 73 74 61 6e 63 65 20 62 79 20 72 6f 77 69 64  nstance by rowid
13f90 2c 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  , column number 
13fa0 28 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 75 6d  (columns are num
13fb0 62 65 72 65 64 20 73 65 71 75 65 6e 74 69 61 6c  bered sequential
13fc0 6c 79 0a 73 74 61 72 74 69 6e 67 20 61 74 20 30  ly.starting at 0
13fd0 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20 72 69   from left to ri
13fe0 67 68 74 29 20 61 6e 64 20 70 6f 73 69 74 69 6f  ght) and positio
13ff0 6e 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6c  n within the col
14000 75 6d 6e 20 76 61 6c 75 65 20 28 74 68 65 0a 66  umn value (the.f
14010 69 72 73 74 20 74 6f 6b 65 6e 20 69 6e 20 61 20  irst token in a 
14020 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 69 73 20  column value is 
14030 30 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  0, the second is
14040 20 31 2c 20 61 6e 64 20 73 6f 20 6f 6e 29 2e 20   1, and so on). 
14050 55 73 69 6e 67 20 74 68 69 73 0a 69 6e 64 65 78  Using this.index
14060 2c 20 46 54 53 35 20 69 73 20 61 62 6c 65 20 74  , FTS5 is able t
14070 6f 20 70 72 6f 76 69 64 65 20 74 69 6d 65 6c 79  o provide timely
14080 20 61 6e 73 77 65 72 73 20 74 6f 20 71 75 65 72   answers to quer
14090 69 65 73 20 73 75 63 68 20 61 73 20 22 74 68 65  ies such as "the
140a0 20 73 65 74 0a 6f 66 20 61 6c 6c 20 64 6f 63 75   set.of all docu
140b0 6d 65 6e 74 73 20 74 68 61 74 20 63 6f 6e 74 61  ments that conta
140c0 69 6e 20 74 68 65 20 74 6f 6b 65 6e 20 27 41 27  in the token 'A'
140d0 22 2c 20 6f 72 20 22 74 68 65 20 73 65 74 20 6f  ", or "the set o
140e0 66 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 0a  f all documents.
140f0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65  that contain the
14100 20 73 65 71 75 65 6e 63 65 20 27 59 20 5a 27 22   sequence 'Y Z'"
14110 2e 20 54 68 65 20 6c 69 73 74 20 6f 66 20 69 6e  . The list of in
14120 73 74 61 6e 63 65 73 20 61 73 73 6f 63 69 61 74  stances associat
14130 65 64 20 77 69 74 68 20 61 0a 73 69 6e 67 6c 65  ed with a.single
14140 20 74 6f 6b 65 6e 20 69 73 20 63 61 6c 6c 65 64   token is called
14150 20 61 6e 20 22 69 6e 73 74 61 6e 63 65 2d 6c 69   an "instance-li
14160 73 74 22 2e 0a 0a 3c 70 3e 54 68 65 20 70 72 69  st"...<p>The pri
14170 6e 63 69 70 6c 65 20 64 69 66 66 65 72 65 6e 63  nciple differenc
14180 65 20 62 65 74 77 65 65 6e 20 46 54 53 33 2f 34  e between FTS3/4
14190 20 61 6e 64 20 46 54 53 35 20 69 73 20 74 68 61   and FTS5 is tha
141a0 74 20 69 6e 20 46 54 53 33 2f 34 2c 0a 65 61 63  t in FTS3/4,.eac
141b0 68 20 69 6e 73 74 61 6e 63 65 2d 6c 69 73 74 20  h instance-list 
141c0 69 73 20 73 74 6f 72 65 64 20 61 73 20 61 20 73  is stored as a s
141d0 69 6e 67 6c 65 20 6c 61 72 67 65 20 64 61 74 61  ingle large data
141e0 62 61 73 65 20 72 65 63 6f 72 64 2c 20 77 68 65  base record, whe
141f0 72 65 61 73 0a 69 6e 20 46 54 53 35 20 6c 61 72  reas.in FTS5 lar
14200 67 65 20 69 6e 73 74 61 6e 63 65 2d 6c 69 73 74  ge instance-list
14210 73 20 61 72 65 20 64 69 76 69 64 65 64 20 62 65  s are divided be
14220 74 77 65 65 6e 20 6d 75 6c 74 69 70 6c 65 20 64  tween multiple d
14230 61 74 61 62 61 73 65 20 72 65 63 6f 72 64 73 2e  atabase records.
14240 0a 54 68 69 73 20 68 61 73 20 74 68 65 20 66 6f  .This has the fo
14250 6c 6c 6f 77 69 6e 67 20 69 6d 70 6c 69 63 61 74  llowing implicat
14260 69 6f 6e 73 20 66 6f 72 20 64 65 61 6c 69 6e 67  ions for dealing
14270 20 77 69 74 68 20 6c 61 72 67 65 20 64 61 74 61   with large data
14280 62 61 73 65 73 20 74 68 61 74 0a 63 6f 6e 74 61  bases that.conta
14290 69 6e 20 6c 61 72 67 65 20 6c 69 73 74 73 3a 0a  in large lists:.
142a0 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e  .<ul>.  <li> <p>
142b0 46 54 53 35 20 69 73 20 61 62 6c 65 20 74 6f 20  FTS5 is able to 
142c0 6c 6f 61 64 20 69 6e 73 74 61 6e 63 65 2d 6c 69  load instance-li
142d0 73 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  sts into memory 
142e0 69 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 69 6e  incrementally in
142f0 0a 20 20 20 20 20 20 20 6f 72 64 65 72 20 74 6f  .       order to
14300 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
14310 73 61 67 65 20 61 6e 64 20 70 65 61 6b 20 61 6c  sage and peak al
14320 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 46  location size. F
14330 54 53 33 2f 34 20 76 65 72 79 0a 20 20 20 20 20  TS3/4 very.     
14340 20 20 6f 66 74 65 6e 20 6c 6f 61 64 73 20 65 6e    often loads en
14350 74 69 72 65 20 69 6e 73 74 61 6e 63 65 2d 6c 69  tire instance-li
14360 73 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 2e  sts into memory.
14370 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 57 68 65 6e  ..  <li> <p>When
14380 20 70 72 6f 63 65 73 73 69 6e 67 20 71 75 65 72   processing quer
14390 69 65 73 20 74 68 61 74 20 66 65 61 74 75 72 65  ies that feature
143a0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
143b0 6f 6b 65 6e 2c 20 46 54 53 35 20 69 73 0a 20 20  oken, FTS5 is.  
143c0 20 20 20 20 20 73 6f 6d 65 74 69 6d 65 73 20 61       sometimes a
143d0 62 6c 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ble to determine
143e0 20 74 68 61 74 20 74 68 65 20 71 75 65 72 79 20   that the query 
143f0 63 61 6e 20 62 65 20 61 6e 73 77 65 72 65 64 20  can be answered 
14400 62 79 0a 20 20 20 20 20 20 20 69 6e 73 70 65 63  by.       inspec
14410 74 69 6e 67 20 61 20 73 75 62 73 65 74 20 6f 66  ting a subset of
14420 20 61 20 6c 61 72 67 65 20 69 6e 73 74 61 6e 63   a large instanc
14430 65 2d 6c 69 73 74 2e 20 46 54 53 33 2f 34 20 61  e-list. FTS3/4 a
14440 6c 6d 6f 73 74 20 61 6c 77 61 79 73 0a 20 20 20  lmost always.   
14450 20 20 20 20 68 61 73 20 74 6f 20 74 72 61 76 65      has to trave
14460 72 73 65 20 65 6e 74 69 72 65 20 69 6e 73 74 61  rse entire insta
14470 6e 63 65 2d 6c 69 73 74 73 2e 0a 0a 20 20 3c 6c  nce-lists...  <l
14480 69 3e 20 49 66 20 61 6e 20 69 6e 73 74 61 6e 63  i> If an instanc
14490 65 2d 6c 69 73 74 20 67 72 6f 77 73 20 73 6f 20  e-list grows so 
144a0 6c 61 72 67 65 20 74 68 61 74 20 69 74 20 65 78  large that it ex
144b0 63 65 65 64 73 0a 20 20 20 20 20 20 20 74 68 65  ceeds.       the
144c0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
144d0 47 54 48 5d 20 6c 69 6d 69 74 2c 20 46 54 53 33  GTH] limit, FTS3
144e0 2f 34 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  /4 is unable to 
144f0 68 61 6e 64 6c 65 20 69 74 2e 20 46 54 53 35 0a  handle it. FTS5.
14500 20 20 20 20 20 20 20 64 6f 65 73 20 6e 6f 74 20         does not 
14510 68 61 76 65 20 74 68 69 73 20 70 72 6f 62 6c 65  have this proble
14520 6d 2e 20 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 46 6f  m. .</ul>..<p>Fo
14530 72 20 74 68 65 73 65 20 72 65 61 73 6f 6e 73 2c  r these reasons,
14540 20 6d 61 6e 79 20 63 6f 6d 70 6c 65 78 20 71 75   many complex qu
14550 65 72 69 65 73 20 6d 61 79 20 75 73 65 20 6c 65  eries may use le
14560 73 73 20 6d 65 6d 6f 72 79 20 61 6e 64 20 72 75  ss memory and ru
14570 6e 20 66 61 73 74 65 72 20 0a 75 73 69 6e 67 20  n faster .using 
14580 46 54 53 35 2e 0a 0a 3c 70 3e 53 6f 6d 65 20 6f  FTS5...<p>Some o
14590 74 68 65 72 20 77 61 79 73 20 69 6e 20 77 68 69  ther ways in whi
145a0 63 68 20 46 54 53 35 20 64 69 66 66 65 72 73 20  ch FTS5 differs 
145b0 66 72 6f 6d 20 46 54 53 33 2f 34 20 61 72 65 3a  from FTS3/4 are:
145c0 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 70  ..<ul>.  <li> <p
145d0 3e 46 54 53 35 20 73 75 70 70 6f 72 74 73 20 22  >FTS5 supports "
145e0 4f 52 44 45 52 20 42 59 20 72 61 6e 6b 22 20 66  ORDER BY rank" f
145f0 6f 72 20 72 65 74 75 72 6e 69 6e 67 20 72 65 73  or returning res
14600 75 6c 74 73 20 69 6e 20 6f 72 64 65 72 20 6f 66  ults in order of
14610 0a 20 20 20 20 20 20 20 64 65 63 72 65 61 73 69  .       decreasi
14620 6e 67 20 72 65 6c 65 76 61 6e 63 79 2e 0a 0a 20  ng relevancy... 
14630 20 3c 6c 69 3e 20 3c 70 3e 46 54 53 35 20 66 65   <li> <p>FTS5 fe
14640 61 74 75 72 65 73 20 61 6e 20 41 50 49 20 61 6c  atures an API al
14650 6c 6f 77 69 6e 67 20 75 73 65 72 73 20 74 6f 20  lowing users to 
14660 63 72 65 61 74 65 20 63 75 73 74 6f 6d 20 61 75  create custom au
14670 78 69 6c 69 61 72 79 20 0a 20 20 20 20 20 20 20  xiliary .       
14680 66 75 6e 63 74 69 6f 6e 73 20 66 6f 72 20 61 64  functions for ad
14690 76 61 6e 63 65 64 20 72 61 6e 6b 69 6e 67 20 61  vanced ranking a
146a0 6e 64 20 74 65 78 74 20 70 72 6f 63 65 73 73 69  nd text processi
146b0 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e  ng applications.
146c0 20 54 68 65 0a 20 20 20 20 20 20 20 73 70 65 63   The.       spec
146d0 69 61 6c 20 22 72 61 6e 6b 22 20 63 6f 6c 75 6d  ial "rank" colum
146e0 6e 20 6d 61 79 20 62 65 20 6d 61 70 70 65 64 20  n may be mapped 
146f0 74 6f 20 61 20 63 75 73 74 6f 6d 20 61 75 78 69  to a custom auxi
14700 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 0a 20  liary function. 
14710 20 20 20 20 20 20 73 6f 20 74 68 61 74 20 61 64        so that ad
14720 64 69 6e 67 20 22 4f 52 44 45 52 20 42 59 20 72  ding "ORDER BY r
14730 61 6e 6b 22 20 74 6f 20 61 20 71 75 65 72 79 20  ank" to a query 
14740 77 6f 72 6b 73 20 61 73 20 65 78 70 65 63 74 65  works as expecte
14750 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 46 54  d...  <li> <p>FT
14760 53 35 20 72 65 63 6f 67 6e 69 7a 65 73 20 75 6e  S5 recognizes un
14770 69 63 6f 64 65 20 73 65 70 61 72 61 74 6f 72 20  icode separator 
14780 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 20 63  characters and c
14790 61 73 65 20 65 71 75 69 76 61 6c 65 6e 63 65 20  ase equivalence 
147a0 62 79 0a 20 20 20 20 20 20 20 64 65 66 61 75 6c  by.       defaul
147b0 74 2e 20 54 68 69 73 20 69 73 20 61 6c 73 6f 20  t. This is also 
147c0 70 6f 73 73 69 62 6c 65 20 75 73 69 6e 67 20 46  possible using F
147d0 54 53 33 2f 34 2c 20 62 75 74 20 6d 75 73 74 20  TS3/4, but must 
147e0 62 65 20 65 78 70 6c 69 63 69 74 6c 79 0a 20 20  be explicitly.  
147f0 20 20 20 20 20 65 6e 61 62 6c 65 64 2e 0a 0a 20       enabled... 
14800 20 3c 6c 69 3e 20 3c 70 3e 54 68 65 20 71 75 65   <li> <p>The que
14810 72 79 20 73 79 6e 74 61 78 20 68 61 73 20 62 65  ry syntax has be
14820 65 6e 20 72 65 76 69 73 65 64 20 77 68 65 72 65  en revised where
14830 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 72 65   necessary to re
14840 6d 6f 76 65 0a 20 20 20 20 20 20 20 61 6d 62 69  move.       ambi
14850 67 75 69 74 69 65 73 20 61 6e 64 20 74 6f 20 6d  guities and to m
14860 61 6b 65 20 69 74 20 70 6f 73 73 69 62 6c 65 20  ake it possible 
14870 74 6f 20 65 73 63 61 70 65 20 73 70 65 63 69 61  to escape specia
14880 6c 20 63 68 61 72 61 63 74 65 72 73 0a 20 20 20  l characters.   
14890 20 20 20 20 69 6e 20 71 75 65 72 79 20 74 65 72      in query ter
148a0 6d 73 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 42  ms...  <li> <p>B
148b0 79 20 64 65 66 61 75 6c 74 2c 20 46 54 53 33 2f  y default, FTS3/
148c0 34 20 6f 63 63 61 73 69 6f 6e 61 6c 6c 79 20 6d  4 occasionally m
148d0 65 72 67 65 73 20 74 6f 67 65 74 68 65 72 20 74  erges together t
148e0 77 6f 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  wo or more of th
148f0 65 0a 20 20 20 20 20 20 20 62 2d 74 72 65 65 73  e.       b-trees
14900 20 74 68 61 74 20 6d 61 6b 65 20 75 70 20 69 74   that make up it
14910 73 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65  s full-text inde
14920 78 20 77 69 74 68 69 6e 20 61 6e 20 49 4e 53 45  x within an INSE
14930 52 54 2c 20 55 50 44 41 54 45 20 6f 72 0a 20 20  RT, UPDATE or.  
14940 20 20 20 20 20 44 45 4c 45 54 45 20 73 74 61 74       DELETE stat
14950 65 6d 65 6e 74 20 65 78 65 63 75 74 65 64 20 62  ement executed b
14960 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 69 73  y the user. This
14970 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 79 20   means that any 
14980 6f 70 65 72 61 74 69 6f 6e 0a 20 20 20 20 20 20  operation.      
14990 20 6f 6e 20 61 6e 20 46 54 53 33 2f 34 20 74 61   on an FTS3/4 ta
149a0 62 6c 65 20 6d 61 79 20 74 75 72 6e 20 6f 75 74  ble may turn out
149b0 20 74 6f 20 62 65 20 73 75 72 70 72 69 73 69 6e   to be surprisin
149c0 67 6c 79 20 73 6c 6f 77 2c 20 61 73 20 46 54 53  gly slow, as FTS
149d0 33 2f 34 20 0a 20 20 20 20 20 20 20 6d 61 79 20  3/4 .       may 
149e0 75 6e 70 72 65 64 69 63 74 61 62 6c 79 20 63 68  unpredictably ch
149f0 6f 6f 73 65 20 74 6f 20 6d 65 72 67 65 20 74 6f  oose to merge to
14a00 67 65 74 68 65 72 20 74 77 6f 20 6f 72 20 6d 6f  gether two or mo
14a10 72 65 20 6c 61 72 67 65 20 62 2d 74 72 65 65 73  re large b-trees
14a20 0a 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 69  .       within i
14a30 74 2e 20 46 54 53 35 20 75 73 65 73 20 69 6e 63  t. FTS5 uses inc
14a40 72 65 6d 65 6e 74 61 6c 20 6d 65 72 67 69 6e 67  remental merging
14a50 20 62 79 20 64 65 66 61 75 6c 74 2c 20 77 68 69   by default, whi
14a60 63 68 20 6c 69 6d 69 74 73 0a 20 20 20 20 20 20  ch limits.      
14a70 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 70   the amount of p
14a80 72 6f 63 65 73 73 69 6e 67 20 74 68 61 74 20 6d  rocessing that m
14a90 61 79 20 74 61 6b 65 20 70 6c 61 63 65 20 77 69  ay take place wi
14aa0 74 68 69 6e 20 61 6e 79 20 67 69 76 65 6e 20 0a  thin any given .
14ab0 20 20 20 20 20 20 20 49 4e 53 45 52 54 2c 20 55         INSERT, U
14ac0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
14ad0 6f 70 65 72 61 74 69 6f 6e 2e 0a 3c 2f 75 6c 3e  operation..</ul>
14ae0 0a 0a 3c 68 31 20 69 64 3d 61 70 70 65 6e 64 69  ..<h1 id=appendi
14af0 78 5f 62 20 6e 6f 6e 75 6d 62 65 72 20 74 61 67  x_b nonumber tag
14b00 73 3d 22 66 74 73 35 20 73 68 61 64 6f 77 20 74  s="fts5 shadow t
14b10 61 62 6c 65 73 22 3e 0a 20 20 41 70 70 65 6e 64  ables">.  Append
14b20 69 78 20 42 3a 20 53 68 61 64 6f 77 20 74 61 62  ix B: Shadow tab
14b30 6c 65 73 20 63 72 65 61 74 65 64 20 62 79 20 46  les created by F
14b40 54 53 35 0a 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 57  TS5.</h1>..<p>.W
14b50 68 65 6e 20 61 6e 20 46 54 53 35 20 76 69 72 74  hen an FTS5 virt
14b60 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 72 65  ual table is cre
14b70 61 74 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ated in a databa
14b80 73 65 2c 20 62 65 74 77 65 65 6e 20 33 20 61 6e  se, between 3 an
14b90 64 20 35 20 72 65 61 6c 0a 74 61 62 6c 65 73 20  d 5 real.tables 
14ba0 61 72 65 20 63 72 65 61 74 65 64 20 69 6e 20 74  are created in t
14bb0 68 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 65  he database. The
14bc0 73 65 20 61 72 65 20 6b 6e 6f 77 6e 20 61 73 20  se are known as 
14bd0 22 5b 73 68 61 64 6f 77 20 74 61 62 6c 65 73 5d  "[shadow tables]
14be0 22 2c 20 61 6e 64 20 61 72 65 0a 75 73 65 64 20  ", and are.used 
14bf0 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  by the virtual t
14c00 61 62 6c 65 20 6d 6f 64 75 6c 65 20 74 6f 20 73  able module to s
14c10 74 6f 72 65 20 70 65 72 73 69 73 74 65 6e 74 20  tore persistent 
14c20 64 61 74 61 2e 20 54 68 65 79 20 73 68 6f 75 6c  data. They shoul
14c30 64 20 6e 6f 74 0a 62 65 20 61 63 63 65 73 73 65  d not.be accesse
14c40 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  d directly by th
14c50 65 20 75 73 65 72 2e 20 4d 61 6e 79 20 6f 74 68  e user. Many oth
14c60 65 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  er virtual table
14c70 20 6d 6f 64 75 6c 65 73 2c 20 69 6e 63 6c 75 64   modules, includ
14c80 69 6e 67 0a 5b 46 54 53 33 5d 20 61 6e 64 20 5b  ing.[FTS3] and [
14c90 72 74 72 65 65 5d 2c 20 61 6c 73 6f 20 63 72 65  rtree], also cre
14ca0 61 74 65 20 61 6e 64 20 75 73 65 20 73 68 61 64  ate and use shad
14cb0 6f 77 20 74 61 62 6c 65 73 2e 0a 0a 3c 70 3e 46  ow tables...<p>F
14cc0 54 53 35 20 63 72 65 61 74 65 73 20 74 68 65 20  TS5 creates the 
14cd0 66 6f 6c 6c 6f 77 69 6e 67 20 73 68 61 64 6f 77  following shadow
14ce0 20 74 61 62 6c 65 73 2e 20 49 6e 20 65 61 63 68   tables. In each
14cf0 20 63 61 73 65 20 74 68 65 20 61 63 74 75 61 6c   case the actual
14d00 20 74 61 62 6c 65 20 6e 61 6d 65 0a 69 73 20 62   table name.is b
14d10 61 73 65 64 20 6f 6e 20 74 68 65 20 6e 61 6d 65  ased on the name
14d20 20 6f 66 20 74 68 65 20 46 54 53 35 20 76 69 72   of the FTS5 vir
14d30 74 75 61 6c 20 74 61 62 6c 65 20 28 69 6e 20 74  tual table (in t
14d40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
14d50 6c 65 2c 20 72 65 70 6c 61 63 65 0a 26 6c 74 3b  le, replace.&lt;
14d60 6e 61 6d 65 26 67 74 3b 20 77 69 74 68 20 74 68  name&gt; with th
14d70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 76 69  e name of the vi
14d80 72 74 75 61 6c 20 74 61 62 6c 65 20 74 6f 20 66  rtual table to f
14d90 69 6e 64 20 74 68 65 20 61 63 74 75 61 6c 20 73  ind the actual s
14da0 68 61 64 6f 77 0a 74 61 62 6c 65 20 6e 61 6d 65  hadow.table name
14db0 29 2e 0a 0a 3c 74 61 62 6c 65 20 73 74 72 69 70  )...<table strip
14dc0 65 64 3d 31 3e 0a 3c 74 72 3e 3c 74 68 3e 54 61  ed=1>.<tr><th>Ta
14dd0 62 6c 65 26 6e 62 73 70 3b 4e 61 6d 65 3c 74 68  ble&nbsp;Name<th
14de0 3e 43 6f 6e 74 65 6e 74 73 0a 3c 74 72 3e 3c 74  >Contents.<tr><t
14df0 64 3e 26 6c 74 3b 6e 61 6d 65 26 67 74 3b 5f 64  d>&lt;name&gt;_d
14e00 61 74 61 3c 74 64 3e 20 54 68 69 73 20 74 61 62  ata<td> This tab
14e10 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 73 74  le contains most
14e20 20 6f 66 20 74 68 65 20 66 75 6c 6c 2d 74 65 78   of the full-tex
14e30 74 20 69 6e 64 65 78 20 64 61 74 61 2e 0a 3c 74  t index data..<t
14e40 72 3e 3c 74 64 3e 26 6c 74 3b 6e 61 6d 65 26 67  r><td>&lt;name&g
14e50 74 3b 5f 69 64 78 3c 74 64 3e 20 54 68 69 73 20  t;_idx<td> This 
14e60 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74  table contains t
14e70 68 65 20 72 65 6d 61 69 6e 64 65 72 20 6f 66 20  he remainder of 
14e80 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 0a 69 6e  the full-text.in
14e90 64 65 78 20 64 61 74 61 2e 20 49 74 20 69 73 20  dex data. It is 
14ea0 61 6c 6d 6f 73 74 20 61 6c 77 61 79 73 20 6d 75  almost always mu
14eb0 63 68 20 73 6d 61 6c 6c 65 72 20 74 68 61 6e 20  ch smaller than 
14ec0 74 68 65 20 26 6c 74 3b 6e 61 6d 65 26 67 74 3b  the &lt;name&gt;
14ed0 5f 64 61 74 61 20 74 61 62 6c 65 2e 0a 3c 74 72  _data table..<tr
14ee0 3e 3c 74 64 3e 26 6c 74 3b 6e 61 6d 65 26 67 74  ><td>&lt;name&gt
14ef0 3b 5f 63 6f 6e 66 69 67 3c 74 64 3e 20 43 6f 6e  ;_config<td> Con
14f00 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 73  tains the values
14f10 20 6f 66 20 70 65 72 73 69 73 74 65 6e 74 0a 63   of persistent.c
14f20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 70 61 72  onfiguration par
14f30 61 6d 65 74 65 72 73 2e 0a 3c 74 72 3e 3c 74 64  ameters..<tr><td
14f40 3e 26 6c 74 3b 6e 61 6d 65 26 67 74 3b 5f 63 6f  >&lt;name&gt;_co
14f50 6e 74 65 6e 74 3c 74 64 3e 20 43 6f 6e 74 61 69  ntent<td> Contai
14f60 6e 73 20 74 68 65 20 61 63 74 75 61 6c 20 64 61  ns the actual da
14f70 74 61 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  ta inserted into
14f80 20 74 68 65 20 0a 46 54 53 35 20 74 61 62 6c 65   the .FTS5 table
14f90 2e 20 54 68 69 73 20 73 68 61 64 6f 77 20 74 61  . This shadow ta
14fa0 62 6c 65 20 69 73 20 6e 6f 74 20 70 72 65 73 65  ble is not prese
14fb0 6e 74 20 66 6f 72 20 0a 5b 46 54 53 35 20 63 6f  nt for .[FTS5 co
14fc0 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73  ntentless tables
14fd0 20 7c 20 63 6f 6e 74 65 6e 74 6c 65 73 73 5d 20   | contentless] 
14fe0 6f 72 20 0a 5b 46 54 53 35 20 65 78 74 65 72 6e  or .[FTS5 extern
14ff0 61 6c 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  al content table
15000 73 7c 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  s|external conte
15010 6e 74 5d 20 46 54 53 35 20 74 61 62 6c 65 73 2e  nt] FTS5 tables.
15020 0a 3c 74 72 3e 3c 74 64 3e 26 6c 74 3b 6e 61 6d  .<tr><td>&lt;nam
15030 65 26 67 74 3b 5f 64 6f 63 73 69 7a 65 3c 74 64  e&gt;_docsize<td
15040 3e 20 43 6f 6e 74 61 69 6e 73 20 74 68 65 20 73  > Contains the s
15050 69 7a 65 20 6f 66 20 65 61 63 68 20 63 6f 6c 75  ize of each colu
15060 6d 6e 20 6f 66 20 65 61 63 68 0a 72 6f 77 20 69  mn of each.row i
15070 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
15080 62 6c 65 20 69 6e 20 74 6f 6b 65 6e 73 2e 20 54  ble in tokens. T
15090 68 69 73 20 73 68 61 64 6f 77 20 74 61 62 6c 65  his shadow table
150a0 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74 20   is not present 
150b0 69 66 20 0a 74 68 65 20 5b 46 54 53 35 20 63 6f  if .the [FTS5 co
150c0 6c 75 6d 6e 73 69 7a 65 20 6f 70 74 69 6f 6e 7c  lumnsize option|
150d0 22 63 6f 6c 75 6d 6e 73 69 7a 65 22 20 6f 70 74  "columnsize" opt
150e0 69 6f 6e 5d 20 69 73 20 73 65 74 20 74 6f 20 30  ion] is set to 0
150f0 2e 0a 3c 2f 74 61 62 6c 65 3e 0a                 ..</table>.