Documentation Source Text

Hex Artifact Content
Login

Artifact b66cefb8ffa99fd2c7f2049981aa1f0f882a5cd6:


0000: 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64  .<tcl>hd_keyword
0010: 73 20 2a 66 74 73 35 20 46 54 53 35 3c 2f 74 63  s *fts5 FTS5</tc
0020: 6c 3e 0a 3c 74 69 74 6c 65 3e 53 51 4c 69 74 65  l>.<title>SQLite
0030: 20 46 54 53 35 20 45 78 74 65 6e 73 69 6f 6e 3c   FTS5 Extension<
0040: 2f 74 69 74 6c 65 3e 0a 0a 3c 74 61 62 6c 65 5f  /title>..<table_
0050: 6f 66 5f 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 68  of_contents>..<h
0060: 32 20 73 74 79 6c 65 3d 22 6d 61 72 67 69 6e 2d  2 style="margin-
0070: 6c 65 66 74 3a 31 2e 30 65 6d 22 20 6e 6f 74 6f  left:1.0em" noto
0080: 63 3e 20 4f 76 65 72 76 69 65 77 3c 2f 68 32 3e  c> Overview</h2>
0090: 0a 0a 3c 68 31 3e 43 52 45 41 54 45 20 54 41 42  ..<h1>CREATE TAB
00a0: 4c 45 20 41 72 67 75 6d 65 6e 74 73 3c 2f 68 31  LE Arguments</h1
00b0: 3e 0a 0a 3c 70 3e 45 61 63 68 20 61 72 67 75 6d  >..<p>Each argum
00c0: 65 6e 74 20 73 70 65 63 69 66 69 65 64 20 61 73  ent specified as
00d0: 20 70 61 72 74 20 6f 66 20 61 20 22 43 52 45 41   part of a "CREA
00e0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
00f0: 20 2e 2e 2e 20 55 53 49 4e 47 20 66 74 73 35 20   ... USING fts5 
0100: 0a 2e 2e 2e 22 20 73 74 61 74 65 6d 65 6e 74 20  ...." statement 
0110: 69 73 20 65 69 74 68 65 72 20 61 20 63 6f 6c 75  is either a colu
0120: 6d 6e 20 6e 61 6d 65 20 6f 72 20 61 20 63 6f 6e  mn name or a con
0130: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
0140: 6e 2e 20 41 20 63 6f 6c 75 6d 6e 0a 6e 61 6d 65  n. A column.name
0150: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 20 73   consists of a s
0160: 69 6e 67 6c 65 20 46 54 53 35 20 62 61 72 65 77  ingle FTS5 barew
0170: 6f 72 64 20 6f 72 20 61 20 73 69 6e 67 6c 65 20  ord or a single 
0180: 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 71  string literal q
0190: 75 6f 74 65 64 0a 69 6e 20 61 6e 79 20 6d 61 6e  uoted.in any man
01a0: 6e 65 72 20 61 63 63 65 70 74 61 62 6c 65 20 74  ner acceptable t
01b0: 6f 20 53 51 4c 69 74 65 2e 20 41 20 63 6f 6e 66  o SQLite. A conf
01c0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
01d0: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 6e 0a   consists of an.
01e0: 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 2d 20  FTS5 bareword - 
01f0: 74 68 65 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  the option name 
0200: 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e  - followed by an
0210: 20 22 3d 22 20 63 68 61 72 61 63 74 65 72 2c 20   "=" character, 
0220: 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 74 68 65 20  followed by.the 
0230: 6f 70 74 69 6f 6e 20 76 61 6c 75 65 2e 20 54 68  option value. Th
0240: 65 20 6f 70 74 69 6f 6e 20 76 61 6c 75 65 20 69  e option value i
0250: 73 20 73 70 65 63 69 66 69 65 64 20 75 73 69 6e  s specified usin
0260: 67 20 65 69 74 68 65 72 20 61 20 73 69 6e 67 6c  g either a singl
0270: 65 20 46 54 53 35 20 0a 62 61 72 65 77 6f 72 64  e FTS5 .bareword
0280: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 6c 69 74   or a string lit
0290: 65 72 61 6c 2c 20 61 67 61 69 6e 20 71 75 6f 74  eral, again quot
02a0: 65 64 20 69 6e 20 61 6e 79 20 6d 61 6e 6e 65 72  ed in any manner
02b0: 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 74   acceptable to t
02c0: 68 65 0a 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he.SQLite core. 
02d0: 41 6e 79 74 68 69 6e 67 20 65 6c 73 65 20 69 73  Anything else is
02e0: 20 61 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e   a syntax error.
02f0: 0a 0a 3c 68 32 3e 43 6f 6c 75 6d 6e 20 4e 61 6d  ..<h2>Column Nam
0300: 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 49 74 20 69  es</h2>..<p>It i
0310: 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 61 74  s an error to at
0320: 74 65 6d 70 74 20 74 6f 20 6e 61 6d 65 20 61 6e  tempt to name an
0330: 20 66 74 73 35 20 74 61 62 6c 65 20 63 6f 6c 75   fts5 table colu
0340: 6d 6e 20 22 72 6f 77 69 64 22 20 6f 72 20 22 72  mn "rowid" or "r
0350: 61 6e 6b 22 2e 20 0a 54 68 69 73 20 69 73 20 6e  ank". .This is n
0360: 6f 74 20 73 75 70 70 6f 72 74 65 64 2e 0a 0a 3c  ot supported...<
0370: 68 32 3e 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  h2>Configuration
0380: 20 4f 70 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c   Options</h2>..<
0390: 70 3e 20 41 20 63 6f 6e 66 69 67 75 72 61 74 69  p> A configurati
03a0: 6f 6e 20 6f 70 74 69 6f 6e 20 63 6f 6e 73 69 73  on option consis
03b0: 74 73 20 6f 66 20 61 6e 20 46 54 53 35 20 62 61  ts of an FTS5 ba
03c0: 72 65 77 6f 72 64 20 2d 20 74 68 65 20 6f 70 74  reword - the opt
03d0: 69 6f 6e 20 6e 61 6d 65 20 2d 0a 66 6f 6c 6c 6f  ion name -.follo
03e0: 77 65 64 20 62 79 20 61 6e 20 22 3d 22 20 63 68  wed by an "=" ch
03f0: 61 72 61 63 74 65 72 2c 20 66 6f 6c 6c 6f 77 65  aracter, followe
0400: 64 20 62 79 20 61 20 65 69 74 68 65 72 20 61 6e  d by a either an
0410: 20 46 54 53 35 20 62 61 72 65 77 6f 72 64 20 6f   FTS5 bareword o
0420: 72 20 61 0a 73 74 72 69 6e 67 20 6c 69 74 65 72  r a.string liter
0430: 61 6c 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  al. For example:
0440: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
0450: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
0460: 41 42 4c 45 20 6d 61 69 6c 20 55 53 49 4e 47 20  ABLE mail USING 
0470: 66 74 73 35 28 73 65 6e 64 65 72 2c 20 74 69 74  fts5(sender, tit
0480: 6c 65 2c 20 62 6f 64 79 2c 20 74 6f 6b 65 6e 69  le, body, tokeni
0490: 7a 65 20 3d 20 27 70 6f 72 74 65 72 20 61 73 63  ze = 'porter asc
04a0: 69 69 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  ii');.</codebloc
04b0: 6b 3e 0a 0a 3c 70 3e 20 54 68 65 72 65 20 61 72  k>..<p> There ar
04c0: 65 20 63 75 72 72 65 6e 74 6c 79 20 74 68 65 20  e currently the 
04d0: 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 66 69 67  following config
04e0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 3a  uration options:
04f0: 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 54 68  ..<ul>.  <li> Th
0500: 65 20 22 74 6f 6b 65 6e 69 7a 65 22 20 6f 70 74  e "tokenize" opt
0510: 69 6f 6e 2c 20 75 73 65 64 20 74 6f 20 63 6f 6e  ion, used to con
0520: 66 69 67 75 72 65 20 61 20 5b 46 54 53 35 20 74  figure a [FTS5 t
0530: 6f 6b 65 6e 69 7a 65 72 73 20 7c 20 63 75 73 74  okenizers | cust
0540: 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 5d 2e 0a 20  om tokenizer].. 
0550: 20 3c 6c 69 3e 20 54 68 65 20 22 70 72 65 66 69   <li> The "prefi
0560: 78 22 20 6f 70 74 69 6f 6e 2c 20 75 73 65 64 20  x" option, used 
0570: 74 6f 20 61 64 64 20 5b 46 54 53 35 20 70 72 65  to add [FTS5 pre
0580: 66 69 78 20 69 6e 64 65 78 65 73 20 7c 20 70 72  fix indexes | pr
0590: 65 66 69 78 20 69 6e 64 65 78 65 73 5d 0a 20 20  efix indexes].  
05a0: 20 20 20 20 20 74 6f 20 61 6e 20 46 54 53 35 20       to an FTS5 
05b0: 74 61 62 6c 65 2e 0a 20 20 3c 6c 69 3e 20 54 68  table..  <li> Th
05c0: 65 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70 74 69  e "content" opti
05d0: 6f 6e 2c 20 75 73 65 64 20 74 6f 20 6d 61 6b 65  on, used to make
05e0: 20 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20   the FTS5 table 
05f0: 61 6e 20 0a 20 20 20 20 20 20 20 5b 46 54 53 35  an .       [FTS5
0600: 20 63 6f 6e 74 65 6e 74 20 6f 70 74 69 6f 6e 20   content option 
0610: 7c 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  | external conte
0620: 6e 74 20 6f 72 20 63 6f 6e 74 65 6e 74 6c 65 73  nt or contentles
0630: 73 20 74 61 62 6c 65 5d 2e 0a 20 20 3c 6c 69 3e  s table]..  <li>
0640: 20 54 68 65 20 22 63 6f 6e 74 65 6e 74 5f 72 6f   The "content_ro
0650: 77 69 64 22 20 6f 70 74 69 6f 6e 2c 20 75 73 65  wid" option, use
0660: 64 20 74 6f 20 73 65 74 20 74 68 65 20 72 6f 77  d to set the row
0670: 69 64 20 66 69 65 6c 64 20 6f 66 20 61 6e 20 0a  id field of an .
0680: 20 20 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c    [FTS5 external
0690: 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20   content tables 
06a0: 7c 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  | external conte
06b0: 6e 74 20 74 61 62 6c 65 5d 2e 0a 3c 2f 75 6c 3e  nt table]..</ul>
06c0: 0a 0a 3c 68 31 3e 46 75 6c 6c 2d 74 65 78 74 20  ..<h1>Full-text 
06d0: 51 75 65 72 79 20 53 79 6e 74 61 78 3c 2f 68 31  Query Syntax</h1
06e0: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c 6c 6f  >..<p>.The follo
06f0: 77 69 6e 67 20 62 6c 6f 63 6b 20 63 6f 6e 74 61  wing block conta
0700: 69 6e 73 20 61 20 73 75 6d 6d 61 72 79 20 6f 66  ins a summary of
0710: 20 74 68 65 20 46 54 53 20 71 75 65 72 79 20 73   the FTS query s
0720: 79 6e 74 61 78 20 69 6e 20 42 4e 46 20 66 6f 72  yntax in BNF for
0730: 6d 2e 0a 41 20 64 65 74 61 69 6c 65 64 20 65 78  m..A detailed ex
0740: 70 6c 61 6e 61 74 69 6f 6e 20 66 6f 6c 6c 6f 77  planation follow
0750: 73 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  s...<codeblock>.
0760: 26 6c 74 3b 70 68 72 61 73 65 26 67 74 3b 20 20  &lt;phrase&gt;  
0770: 20 20 3a 3d 20 73 74 72 69 6e 67 20 26 23 39 31    := string &#91
0780: 3b 2a 5d 0a 26 6c 74 3b 70 68 72 61 73 65 26 67  ;*].&lt;phrase&g
0790: 74 3b 20 20 20 20 3a 3d 20 26 6c 74 3b 70 68 72  t;    := &lt;phr
07a0: 61 73 65 26 67 74 3b 20 2b 20 26 6c 74 3b 70 68  ase&gt; + &lt;ph
07b0: 72 61 73 65 26 67 74 3b 0a 26 6c 74 3b 6e 65 61  rase&gt;.&lt;nea
07c0: 72 67 72 6f 75 70 26 67 74 3b 20 3a 3d 20 4e 45  rgroup&gt; := NE
07d0: 41 52 20 28 20 26 6c 74 3b 70 68 72 61 73 65 26  AR ( &lt;phrase&
07e0: 67 74 3b 20 26 6c 74 3b 70 68 72 61 73 65 26 67  gt; &lt;phrase&g
07f0: 74 3b 20 2e 2e 2e 20 26 23 39 31 3b 2c 20 4e 5d  t; ... &#91;, N]
0800: 20 29 0a 26 6c 74 3b 71 75 65 72 79 26 67 74 3b   ).&lt;query&gt;
0810: 20 20 20 20 20 3a 3d 20 26 23 39 31 3b 63 6f 6c       := &#91;col
0820: 6e 61 6d 65 20 3a 5d 20 26 6c 74 3b 70 68 72 61  name :] &lt;phra
0830: 73 65 26 67 74 3b 0a 26 6c 74 3b 71 75 65 72 79  se&gt;.&lt;query
0840: 26 67 74 3b 20 20 20 20 20 3a 3d 20 26 23 39 31  &gt;     := &#91
0850: 3b 63 6f 6c 6e 61 6d 65 20 3a 5d 20 26 6c 74 3b  ;colname :] &lt;
0860: 6e 65 61 72 67 72 6f 75 70 26 67 74 3b 0a 26 6c  neargroup&gt;.&l
0870: 74 3b 71 75 65 72 79 26 67 74 3b 20 20 20 20 20  t;query&gt;     
0880: 3a 3d 20 28 20 26 6c 74 3b 71 75 65 72 79 26 67  := ( &lt;query&g
0890: 74 3b 20 29 0a 26 6c 74 3b 71 75 65 72 79 26 67  t; ).&lt;query&g
08a0: 74 3b 20 20 20 20 20 3a 3d 20 26 6c 74 3b 71 75  t;     := &lt;qu
08b0: 65 72 79 26 67 74 3b 20 41 4e 44 20 26 6c 74 3b  ery&gt; AND &lt;
08c0: 71 75 65 72 79 26 67 74 3b 0a 26 6c 74 3b 71 75  query&gt;.&lt;qu
08d0: 65 72 79 26 67 74 3b 20 20 20 20 20 3a 3d 20 26  ery&gt;     := &
08e0: 6c 74 3b 71 75 65 72 79 26 67 74 3b 20 4f 52 20  lt;query&gt; OR 
08f0: 26 6c 74 3b 71 75 65 72 79 26 67 74 3b 0a 26 6c  &lt;query&gt;.&l
0900: 74 3b 71 75 65 72 79 26 67 74 3b 20 20 20 20 20  t;query&gt;     
0910: 3a 3d 20 26 6c 74 3b 71 75 65 72 79 26 67 74 3b  := &lt;query&gt;
0920: 20 4e 4f 54 20 26 6c 74 3b 71 75 65 72 79 26 67   NOT &lt;query&g
0930: 74 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t;.</codeblock>.
0940: 0a 3c 70 3e 0a 57 69 74 68 69 6e 20 61 6e 20 46  .<p>.Within an F
0950: 54 53 20 65 78 70 72 65 73 73 69 6f 6e 20 61 20  TS expression a 
0960: 3c 62 3e 73 74 72 69 6e 67 3c 2f 62 3e 20 6d 61  <b>string</b> ma
0970: 79 20 62 65 20 73 70 65 63 69 66 69 65 64 20 69  y be specified i
0980: 6e 20 6f 6e 65 20 6f 66 20 74 77 6f 20 77 61 79  n one of two way
0990: 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20  s:..<ul>.  <li> 
09a0: 3c 70 3e 42 79 20 65 6e 63 6c 6f 73 69 6e 67 20  <p>By enclosing 
09b0: 69 74 20 69 6e 20 64 6f 75 62 6c 65 20 71 75 6f  it in double quo
09c0: 74 65 73 20 28 22 29 2e 20 57 69 74 68 69 6e 20  tes ("). Within 
09d0: 61 20 73 74 72 69 6e 67 2c 20 61 6e 79 20 65 6d  a string, any em
09e0: 62 65 64 64 65 64 0a 20 20 20 20 20 20 20 64 6f  bedded.       do
09f0: 75 62 6c 65 20 71 75 6f 74 65 20 63 68 61 72 61  uble quote chara
0a00: 63 74 65 72 73 20 6d 61 79 20 62 65 20 65 73 63  cters may be esc
0a10: 61 70 65 64 20 53 51 4c 2d 73 74 79 6c 65 20 2d  aped SQL-style -
0a20: 20 62 79 20 61 64 64 69 6e 67 20 61 20 73 65 63   by adding a sec
0a30: 6f 6e 64 0a 20 20 20 20 20 20 20 64 6f 75 62 6c  ond.       doubl
0a40: 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
0a50: 72 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 41 73  r...  <li> <p>As
0a60: 20 61 20 62 61 72 65 77 6f 72 64 20 74 68 61 74   a bareword that
0a70: 20 69 6e 63 6c 75 64 65 73 20 6e 6f 20 77 68 69   includes no whi
0a80: 74 65 73 70 61 63 65 20 6f 72 20 72 65 73 65 72  tespace or reser
0a90: 76 65 64 20 63 68 61 72 61 63 74 65 72 73 2c 20  ved characters, 
0aa0: 0a 20 20 20 20 20 20 20 61 6e 64 20 69 73 20 6e  .       and is n
0ab0: 6f 74 20 22 41 4e 44 22 2c 20 22 4f 52 22 20 6f  ot "AND", "OR" o
0ac0: 72 20 22 4e 4f 54 22 20 28 63 61 73 65 20 73 65  r "NOT" (case se
0ad0: 6e 73 69 74 69 76 65 29 2e 20 52 65 73 65 72 76  nsitive). Reserv
0ae0: 65 64 20 63 68 61 72 61 63 74 65 72 73 0a 20 20  ed characters.  
0af0: 20 20 20 20 20 61 72 65 3a 20 0a 3c 70 72 65 3e       are: .<pre>
0b00: 0a 20 20 20 20 3a 20 7e 20 21 20 40 20 23 20 24  .    : ~ ! @ # $
0b10: 20 25 20 26 23 39 34 3b 20 26 61 6d 70 3b 20 2a   % &#94; &amp; *
0b20: 20 28 20 29 20 2b 20 2c 20 3d 0a 3c 2f 70 72 65   ( ) + , =.</pre
0b30: 3e 0a 20 20 20 20 20 20 20 49 6e 20 6f 74 68 65  >.       In othe
0b40: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 74 6f 70  r words, the top
0b50: 20 72 6f 77 20 6f 66 20 61 20 72 65 67 75 6c 61   row of a regula
0b60: 72 20 55 53 20 6b 65 79 62 6f 61 72 64 2c 20 74  r US keyboard, t
0b70: 68 65 20 70 6c 75 73 20 73 69 67 6e 2c 0a 20 20  he plus sign,.  
0b80: 20 20 20 20 20 63 6f 6d 6d 61 20 61 6e 64 20 63       comma and c
0b90: 6f 6c 6f 6e 20 63 68 61 72 61 63 74 65 72 73 2e  olon characters.
0ba0: 20 53 74 72 69 6e 67 73 20 74 68 61 74 20 69 6e   Strings that in
0bb0: 63 6c 75 64 65 20 61 6e 79 20 6f 66 20 74 68 65  clude any of the
0bc0: 73 65 20 0a 20 20 20 20 20 20 20 63 68 61 72 61  se .       chara
0bd0: 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 71 75  cters must be qu
0be0: 6f 74 65 64 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  oted..</ul>..<p>
0bf0: 0a 46 54 53 20 71 75 65 72 69 65 73 20 61 72 65  .FTS queries are
0c00: 20 6d 61 64 65 20 75 70 20 6f 66 20 3c 62 3e 70   made up of <b>p
0c10: 68 72 61 73 65 73 3c 2f 62 3e 2e 20 41 20 70 68  hrases</b>. A ph
0c20: 72 61 73 65 20 69 73 20 61 6e 20 6f 72 64 65 72  rase is an order
0c30: 65 64 20 6c 69 73 74 20 6f 66 20 0a 6f 6e 65 20  ed list of .one 
0c40: 6f 72 20 6d 6f 72 65 20 74 6f 6b 65 6e 73 2e 20  or more tokens. 
0c50: 41 20 73 74 72 69 6e 67 20 69 73 20 74 72 61 6e  A string is tran
0c60: 73 66 6f 72 6d 65 64 20 69 6e 74 6f 20 61 20 70  sformed into a p
0c70: 68 72 61 73 65 20 62 79 20 70 61 73 73 69 6e 67  hrase by passing
0c80: 20 69 74 20 74 6f 0a 74 68 65 20 46 54 53 20 74   it to.the FTS t
0c90: 61 62 6c 65 20 74 6f 6b 65 6e 69 7a 65 72 2e 20  able tokenizer. 
0ca0: 54 77 6f 20 70 68 72 61 73 65 73 20 63 61 6e 20  Two phrases can 
0cb0: 62 65 20 63 6f 6e 63 61 74 65 6e 61 74 65 64 20  be concatenated 
0cc0: 69 6e 74 6f 20 61 20 73 69 6e 67 6c 65 20 0a 6c  into a single .l
0cd0: 61 72 67 65 20 70 68 72 61 73 65 20 75 73 69 6e  arge phrase usin
0ce0: 67 20 74 68 65 20 22 2b 22 20 6f 70 65 72 61 74  g the "+" operat
0cf0: 6f 72 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  or. For example,
0d00: 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 74 6f   assuming the to
0d10: 6b 65 6e 69 7a 65 72 0a 6d 6f 64 75 6c 65 20 62  kenizer.module b
0d20: 65 69 6e 67 20 75 73 65 64 20 74 6f 6b 65 6e 69  eing used tokeni
0d30: 7a 65 73 20 74 68 65 20 69 6e 70 75 74 20 22 6f  zes the input "o
0d40: 6e 65 2e 74 77 6f 2e 74 68 72 65 65 22 20 74 6f  ne.two.three" to
0d50: 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 0a   three separate.
0d60: 74 6f 6b 65 6e 73 2c 20 74 68 65 20 66 6f 6c 6c  tokens, the foll
0d70: 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
0d80: 69 65 73 20 61 6c 6c 20 73 70 65 63 69 66 79 20  ies all specify 
0d90: 74 68 65 20 73 61 6d 65 20 70 68 72 61 73 65 3a  the same phrase:
0da0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
0db0: 2e 2e 2e 20 4d 41 54 43 48 20 27 22 6f 6e 65 20  ... MATCH '"one 
0dc0: 74 77 6f 20 74 68 72 65 65 22 27 0a 20 20 2e 2e  two three"'.  ..
0dd0: 2e 20 4d 41 54 43 48 20 27 6f 6e 65 20 2b 20 74  . MATCH 'one + t
0de0: 77 6f 20 2b 20 74 68 72 65 65 27 0a 20 20 2e 2e  wo + three'.  ..
0df0: 2e 20 4d 41 54 43 48 20 27 22 6f 6e 65 20 74 77  . MATCH '"one tw
0e00: 6f 22 20 2b 20 74 68 72 65 65 27 0a 20 20 2e 2e  o" + three'.  ..
0e10: 2e 20 4d 41 54 43 48 20 27 6f 6e 65 2e 74 77 6f  . MATCH 'one.two
0e20: 2e 74 68 72 65 65 27 0a 3c 2f 63 6f 64 65 62 6c  .three'.</codebl
0e30: 6f 63 6b 3e 0a 0a 3c 70 3e 0a 41 20 70 68 72 61  ock>..<p>.A phra
0e40: 73 65 20 6d 61 74 63 68 65 73 20 61 20 64 6f 63  se matches a doc
0e50: 75 6d 65 6e 74 20 69 66 20 74 68 65 20 64 6f 63  ument if the doc
0e60: 75 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 20 61  ument contains a
0e70: 74 20 6c 65 61 73 74 20 6f 6e 65 20 73 75 62 2d  t least one sub-
0e80: 73 65 71 75 65 6e 63 65 0a 6f 66 20 74 6f 6b 65  sequence.of toke
0e90: 6e 73 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  ns that matches 
0ea0: 74 68 65 20 73 65 71 75 65 6e 63 65 20 6f 66 20  the sequence of 
0eb0: 74 6f 6b 65 6e 73 20 74 68 61 74 20 6d 61 6b 65  tokens that make
0ec0: 20 75 70 20 74 68 65 20 70 68 72 61 73 65 2e 0a   up the phrase..
0ed0: 0a 3c 70 3e 0a 49 66 20 61 20 22 2a 22 20 63 68  .<p>.If a "*" ch
0ee0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 73 20  aracter follows 
0ef0: 61 20 73 74 72 69 6e 67 20 77 69 74 68 69 6e 20  a string within 
0f00: 61 6e 20 46 54 53 20 65 78 70 72 65 73 73 69 6f  an FTS expressio
0f10: 6e 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6e 61  n, then the fina
0f20: 6c 0a 74 6f 6b 65 6e 20 65 78 74 72 61 63 74 65  l.token extracte
0f30: 64 20 66 72 6f 6d 20 74 68 65 20 73 74 72 69 6e  d from the strin
0f40: 67 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 61  g is marked as a
0f50: 20 3c 62 3e 70 72 65 66 69 78 20 74 6f 6b 65 6e   <b>prefix token
0f60: 3c 2f 62 3e 2e 20 41 73 20 79 6f 75 0a 6d 69 67  </b>. As you.mig
0f70: 68 74 20 65 78 70 65 63 74 2c 20 61 20 70 72 65  ht expect, a pre
0f80: 66 69 78 20 74 6f 6b 65 6e 20 6d 61 74 63 68 65  fix token matche
0f90: 73 20 61 6e 79 20 64 6f 63 75 6d 65 6e 74 20 74  s any document t
0fa0: 6f 6b 65 6e 20 6f 66 20 77 68 69 63 68 20 69 74  oken of which it
0fb0: 20 69 73 20 61 20 0a 70 72 65 66 69 78 2e 20 46   is a .prefix. F
0fc0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20  or example, the 
0fd0: 66 69 72 73 74 20 74 77 6f 20 71 75 65 72 69 65  first two querie
0fe0: 73 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s in the followi
0ff0: 6e 67 20 62 6c 6f 63 6b 20 77 69 6c 6c 20 6d 61  ng block will ma
1000: 74 63 68 0a 61 6e 79 20 64 6f 63 75 6d 65 6e 74  tch.any document
1010: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74   that contains t
1020: 68 65 20 74 6f 6b 65 6e 20 22 6f 6e 65 22 20 69  he token "one" i
1030: 6d 6d 65 64 69 61 74 65 6c 79 20 66 6f 6c 6c 6f  mmediately follo
1040: 77 65 64 20 62 79 20 74 68 65 20 74 6f 6b 65 6e  wed by the token
1050: 0a 22 74 77 6f 22 20 61 6e 64 20 74 68 65 6e 20  ."two" and then 
1060: 61 6e 79 20 74 6f 6b 65 6e 20 74 68 61 74 20 62  any token that b
1070: 65 67 69 6e 73 20 77 69 74 68 20 22 74 68 72 22  egins with "thr"
1080: 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
1090: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 22 6f 6e 65   ... MATCH '"one
10a0: 20 74 77 6f 20 74 68 72 22 20 2a 20 27 0a 20 20   two thr" * '.  
10b0: 2e 2e 2e 20 4d 41 54 43 48 20 27 6f 6e 65 20 2b  ... MATCH 'one +
10c0: 20 74 77 6f 20 2b 20 74 68 72 2a 27 0a 20 20 2e   two + thr*'.  .
10d0: 2e 2e 20 4d 41 54 43 48 20 27 22 6f 6e 65 20 74  .. MATCH '"one t
10e0: 77 6f 20 74 68 72 2a 22 27 20 20 20 20 20 20 3c  wo thr*"'      <
10f0: 62 3e 2d 2d 20 4d 61 79 20 6e 6f 74 20 77 6f 72  b>-- May not wor
1100: 6b 20 61 73 20 65 78 70 65 63 74 65 64 21 3c 2f  k as expected!</
1110: 62 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  b>.</codeblock>.
1120: 0a 3c 70 3e 54 68 65 20 66 69 6e 61 6c 20 71 75  .<p>The final qu
1130: 65 72 79 20 69 6e 20 74 68 65 20 62 6c 6f 63 6b  ery in the block
1140: 20 61 62 6f 76 65 20 6d 61 79 20 6e 6f 74 20 77   above may not w
1150: 6f 72 6b 20 61 73 20 65 78 70 65 63 74 65 64 2e  ork as expected.
1160: 20 42 65 63 61 75 73 65 20 74 68 65 0a 22 2a 22   Because the."*"
1170: 20 63 68 61 72 61 63 74 65 72 20 69 73 20 69 6e   character is in
1180: 73 69 64 65 20 74 68 65 20 64 6f 75 62 6c 65 2d  side the double-
1190: 71 75 6f 74 65 73 2c 20 69 74 20 77 69 6c 6c 20  quotes, it will 
11a0: 62 65 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  be passed to the
11b0: 20 74 6f 6b 65 6e 69 7a 65 72 2c 0a 77 68 69 63   tokenizer,.whic
11c0: 68 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 64 69  h will likely di
11d0: 73 63 61 72 64 20 69 74 20 28 6f 72 20 70 65 72  scard it (or per
11e0: 68 61 70 73 2c 20 64 65 70 65 6e 64 69 6e 67 20  haps, depending 
11f0: 6f 6e 20 74 68 65 20 73 70 65 63 69 66 69 63 20  on the specific 
1200: 74 6f 6b 65 6e 69 7a 65 72 0a 69 6e 20 75 73 65  tokenizer.in use
1210: 2c 20 69 6e 63 6c 75 64 65 20 69 74 20 61 73 20  , include it as 
1220: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6e 61  part of the fina
1230: 6c 20 74 6f 6b 65 6e 29 20 69 6e 73 74 65 61 64  l token) instead
1240: 20 6f 66 20 72 65 63 6f 67 6e 69 7a 69 6e 67 20   of recognizing 
1250: 69 74 20 61 73 0a 61 20 73 70 65 63 69 61 6c 20  it as.a special 
1260: 46 54 53 20 63 68 61 72 61 63 74 65 72 2e 0a 0a  FTS character...
1270: 3c 70 3e 54 77 6f 20 6f 72 20 6d 6f 72 65 20 70  <p>Two or more p
1280: 68 72 61 73 65 73 20 6d 61 79 20 62 65 20 67 72  hrases may be gr
1290: 6f 75 70 65 64 20 69 6e 74 6f 20 61 20 3c 62 3e  ouped into a <b>
12a0: 4e 45 41 52 20 67 72 6f 75 70 3c 2f 62 3e 2e 20  NEAR group</b>. 
12b0: 41 20 4e 45 41 52 20 67 72 6f 75 70 0a 69 73 20  A NEAR group.is 
12c0: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
12d0: 20 74 6f 6b 65 6e 20 22 4e 45 41 52 22 20 28 63   token "NEAR" (c
12e0: 61 73 65 20 73 65 6e 73 69 74 69 76 65 29 20 66  ase sensitive) f
12f0: 6f 6c 6c 6f 77 65 64 20 62 79 20 61 6e 20 6f 70  ollowed by an op
1300: 65 6e 0a 70 61 72 65 6e 74 68 65 73 69 73 20 63  en.parenthesis c
1310: 68 61 72 61 63 74 65 72 2c 20 66 6f 6c 6c 6f 77  haracter, follow
1320: 65 64 20 62 79 20 74 77 6f 20 6f 72 20 6d 6f 72  ed by two or mor
1330: 65 20 77 68 69 74 65 73 70 61 63 65 20 73 65 70  e whitespace sep
1340: 61 72 61 74 65 64 20 70 68 72 61 73 65 73 2c 20  arated phrases, 
1350: 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
1360: 77 65 64 20 62 79 20 61 20 63 6f 6d 6d 61 20 61  wed by a comma a
1370: 6e 64 20 74 68 65 20 6e 75 6d 65 72 69 63 20 70  nd the numeric p
1380: 61 72 61 6d 65 74 65 72 20 3c 69 3e 4e 3c 2f 69  arameter <i>N</i
1390: 3e 2c 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 61  >, followed by.a
13a0: 20 63 6c 6f 73 65 20 70 61 72 65 6e 74 68 65 73   close parenthes
13b0: 69 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  is. For example:
13c0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
13d0: 2e 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28  ... MATCH 'NEAR(
13e0: 22 6f 6e 65 20 74 77 6f 22 20 22 74 68 72 65 65  "one two" "three
13f0: 20 66 6f 75 72 22 2c 20 31 30 29 27 0a 20 20 2e   four", 10)'.  .
1400: 2e 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22  .. MATCH 'NEAR("
1410: 6f 6e 65 20 74 77 6f 22 20 74 68 72 2a 20 2b 20  one two" thr* + 
1420: 66 6f 75 72 29 27 0a 3c 2f 63 6f 64 65 62 6c 6f  four)'.</codeblo
1430: 63 6b 3e 0a 0a 3c 70 3e 49 66 20 6e 6f 20 3c 69  ck>..<p>If no <i
1440: 3e 4e 3c 2f 69 3e 20 70 61 72 61 6d 65 74 65 72  >N</i> parameter
1450: 20 69 73 20 73 75 70 70 6c 69 65 64 2c 20 69 74   is supplied, it
1460: 20 64 65 66 61 75 6c 74 73 20 74 6f 20 31 30 2e   defaults to 10.
1470: 20 41 20 4e 45 41 52 20 67 72 6f 75 70 0a 6d 61   A NEAR group.ma
1480: 74 63 68 65 73 20 61 20 64 6f 63 75 6d 65 6e 74  tches a document
1490: 20 69 66 20 74 68 65 20 64 6f 63 75 6d 65 6e 74   if the document
14a0: 20 63 6f 6e 74 61 69 6e 73 20 61 74 20 6c 65 61   contains at lea
14b0: 73 74 20 6f 6e 65 20 63 6c 75 6d 70 20 6f 66 20  st one clump of 
14c0: 74 6f 6b 65 6e 73 20 74 68 61 74 3a 20 0a 0a 3c  tokens that: ..<
14d0: 6f 6c 3e 20 0a 20 20 3c 6c 69 3e 20 63 6f 6e 74  ol> .  <li> cont
14e0: 61 69 6e 73 20 61 74 20 6c 65 61 73 74 20 6f 6e  ains at least on
14f0: 65 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 65 61  e instance of ea
1500: 63 68 20 70 68 72 61 73 65 2c 20 61 6e 64 20 0a  ch phrase, and .
1510: 20 20 3c 6c 69 3e 20 66 6f 72 20 77 68 69 63 68    <li> for which
1520: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1530: 6f 6b 65 6e 73 20 62 65 74 77 65 65 6e 20 74 68  okens between th
1540: 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
1550: 73 74 20 70 68 72 61 73 65 20 0a 20 20 20 20 20  st phrase .     
1560: 20 20 61 6e 64 20 74 68 65 20 62 65 67 69 6e 6e    and the beginn
1570: 69 6e 67 20 6f 66 20 74 68 65 20 6c 61 73 74 20  ing of the last 
1580: 70 68 72 61 73 65 20 69 6e 20 74 68 65 20 63 6c  phrase in the cl
1590: 75 6d 70 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ump is less than
15a0: 20 3c 69 3e 4e 3c 2f 69 3e 2e 0a 3c 2f 6f 6c 3e   <i>N</i>..</ol>
15b0: 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65  ..<p>For example
15c0: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
15d0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
15e0: 54 41 42 4c 45 20 66 20 55 53 49 4e 47 20 66 74  TABLE f USING ft
15f0: 73 35 28 78 29 3b 0a 20 20 49 4e 53 45 52 54 20  s5(x);.  INSERT 
1600: 49 4e 54 4f 20 66 28 72 6f 77 69 64 2c 20 78 29  INTO f(rowid, x)
1610: 20 56 41 4c 55 45 53 28 31 2c 20 27 41 20 42 20   VALUES(1, 'A B 
1620: 43 20 44 20 78 20 78 20 78 20 45 20 46 20 78 27  C D x x x E F x'
1630: 29 3b 0a 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20  );..  ... MATCH 
1640: 27 4e 45 41 52 28 65 20 64 2c 20 34 29 27 3b 20  'NEAR(e d, 4)'; 
1650: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1660: 20 20 20 20 20 3c 69 3e 2d 2d 20 4d 61 74 63 68       <i>-- Match
1670: 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e 2e 20 4d 41  es!</i>.  ... MA
1680: 54 43 48 20 27 4e 45 41 52 28 65 20 64 2c 20 33  TCH 'NEAR(e d, 3
1690: 29 27 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  )';             
16a0: 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 4d           <i>-- M
16b0: 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e  atches!</i>.  ..
16c0: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 65 20  . MATCH 'NEAR(e 
16d0: 64 2c 20 32 29 27 3b 20 20 20 20 20 20 20 20 20  d, 2)';         
16e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
16f0: 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d 61 74 63  -- Does not matc
1700: 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e 20 4d 41  h!</i>..  ... MA
1710: 54 43 48 20 27 4e 45 41 52 28 22 63 20 64 22 20  TCH 'NEAR("c d" 
1720: 22 65 20 66 22 2c 20 33 29 27 3b 20 20 20 20 20  "e f", 3)';     
1730: 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 4d           <i>-- M
1740: 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e  atches!</i>.  ..
1750: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 63  . MATCH 'NEAR("c
1760: 22 20 20 20 22 65 20 66 22 2c 20 33 29 27 3b 20  "   "e f", 3)'; 
1770: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
1780: 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d 61 74 63  -- Does not matc
1790: 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e 20 4d 41  h!</i>..  ... MA
17a0: 54 43 48 20 27 4e 45 41 52 28 61 20 64 20 65 2c  TCH 'NEAR(a d e,
17b0: 20 36 29 27 3b 20 20 20 20 20 20 20 20 20 20 20   6)';           
17c0: 20 20 20 20 20 20 20 20 20 3c 69 3e 2d 2d 20 4d           <i>-- M
17d0: 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e  atches!</i>.  ..
17e0: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 61 20  . MATCH 'NEAR(a 
17f0: 64 20 65 2c 20 35 29 27 3b 20 20 20 20 20 20 20  d e, 5)';       
1800: 20 20 20 20 20 20 20 20 20 20 20 20 20 3c 69 3e               <i>
1810: 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d 61 74 63  -- Does not matc
1820: 68 21 3c 2f 69 3e 0a 0a 20 20 2e 2e 2e 20 4d 41  h!</i>..  ... MA
1830: 54 43 48 20 27 4e 45 41 52 28 22 61 20 62 20 63  TCH 'NEAR("a b c
1840: 20 64 22 20 22 62 20 63 22 20 22 65 20 66 22 2c   d" "b c" "e f",
1850: 20 34 29 27 3b 20 20 20 20 3c 69 3e 2d 2d 20 4d   4)';    <i>-- M
1860: 61 74 63 68 65 73 21 3c 2f 69 3e 0a 20 20 2e 2e  atches!</i>.  ..
1870: 2e 20 4d 41 54 43 48 20 27 4e 45 41 52 28 22 61  . MATCH 'NEAR("a
1880: 20 62 20 63 20 64 22 20 22 62 20 63 22 20 22 65   b c d" "b c" "e
1890: 20 66 22 2c 20 33 29 27 3b 20 20 20 20 3c 69 3e   f", 3)';    <i>
18a0: 2d 2d 20 44 6f 65 73 20 6e 6f 74 20 6d 61 74 63  -- Does not matc
18b0: 68 21 3c 2f 69 3e 0a 0a 3c 2f 63 6f 64 65 62 6c  h!</i>..</codebl
18c0: 6f 63 6b 3e 0a 0a 0a 3c 70 3e 0a 41 20 73 69 6e  ock>...<p>.A sin
18d0: 67 6c 65 20 70 68 72 61 73 65 20 6f 72 20 4e 45  gle phrase or NE
18e0: 41 52 20 67 72 6f 75 70 20 6d 61 79 20 62 65 20  AR group may be 
18f0: 72 65 73 74 72 69 63 74 65 64 20 74 6f 20 6d 61  restricted to ma
1900: 74 63 68 69 6e 67 20 74 65 78 74 20 77 69 74 68  tching text with
1910: 69 6e 20 61 0a 73 70 65 63 69 66 69 65 64 20 63  in a.specified c
1920: 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 46 54 53  olumn of the FTS
1930: 20 74 61 62 6c 65 20 62 79 20 70 72 65 66 69 78   table by prefix
1940: 69 6e 67 20 69 74 20 77 69 74 68 20 74 68 65 20  ing it with the 
1950: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 0a 66 6f 6c  column name .fol
1960: 6c 6f 77 65 64 20 62 79 20 61 20 63 6f 6c 6f 6e  lowed by a colon
1970: 20 63 68 61 72 61 63 74 65 72 2e 20 43 6f 6c 75   character. Colu
1980: 6d 6e 20 6e 61 6d 65 73 20 6d 61 79 20 62 65 20  mn names may be 
1990: 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 20  specified using 
19a0: 65 69 74 68 65 72 0a 6f 66 20 74 68 65 20 74 77  either.of the tw
19b0: 6f 20 66 6f 72 6d 73 20 64 65 73 63 72 69 62 65  o forms describe
19c0: 64 20 66 6f 72 20 73 74 72 69 6e 67 73 20 61 62  d for strings ab
19d0: 6f 76 65 2e 20 55 6e 6c 69 6b 65 20 73 74 72 69  ove. Unlike stri
19e0: 6e 67 73 20 74 68 61 74 20 61 72 65 20 70 61 72  ngs that are par
19f0: 74 0a 6f 66 20 70 68 72 61 73 65 73 2c 20 63 6f  t.of phrases, co
1a00: 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 72 65 20 6e  lumn names are n
1a10: 6f 74 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  ot passed to the
1a20: 20 74 6f 6b 65 6e 69 7a 65 72 20 6d 6f 64 75 6c   tokenizer modul
1a30: 65 2e 20 43 6f 6c 75 6d 6e 20 0a 6e 61 6d 65 73  e. Column .names
1a40: 20 61 72 65 20 63 61 73 65 2d 69 6e 73 65 6e 73   are case-insens
1a50: 69 74 69 76 65 20 69 6e 20 74 68 65 20 75 73 75  itive in the usu
1a60: 61 6c 20 77 61 79 20 66 6f 72 20 53 51 4c 69 74  al way for SQLit
1a70: 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 2d  e column names -
1a80: 0a 75 70 70 65 72 2f 6c 6f 77 65 72 20 63 61 73  .upper/lower cas
1a90: 65 20 65 71 75 69 76 61 6c 65 6e 63 65 20 69 73  e equivalence is
1aa0: 20 75 6e 64 65 72 73 74 6f 6f 64 20 66 6f 72 20   understood for 
1ab0: 41 53 43 49 49 2d 72 61 6e 67 65 20 63 68 61 72  ASCII-range char
1ac0: 61 63 74 65 72 73 20 6f 6e 6c 79 2e 0a 0a 3c 63  acters only...<c
1ad0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20  odeblock>.  ... 
1ae0: 4d 41 54 43 48 20 27 63 6f 6c 6e 61 6d 65 20 3a  MATCH 'colname :
1af0: 20 4e 45 41 52 28 22 6f 6e 65 20 74 77 6f 22 20   NEAR("one two" 
1b00: 22 74 68 72 65 65 20 66 6f 75 72 22 2c 20 31 30  "three four", 10
1b10: 29 27 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  )'.  ... MATCH '
1b20: 22 63 6f 6c 6e 61 6d 65 22 20 3a 20 6f 6e 65 20  "colname" : one 
1b30: 2b 20 74 77 6f 20 2b 20 74 68 72 65 65 27 0a 3c  + two + three'.<
1b40: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
1b50: 0a 50 68 72 61 73 65 73 20 61 6e 64 20 4e 45 41  .Phrases and NEA
1b60: 52 20 67 72 6f 75 70 73 20 6d 61 79 20 62 65 20  R groups may be 
1b70: 61 72 72 61 6e 67 65 64 20 69 6e 74 6f 20 65 78  arranged into ex
1b80: 70 72 65 73 73 69 6f 6e 73 20 75 73 69 6e 67 20  pressions using 
1b90: 3c 62 3e 62 6f 6f 6c 65 61 6e 0a 6f 70 65 72 61  <b>boolean.opera
1ba0: 74 6f 72 73 3c 2f 62 3e 2e 20 49 6e 20 6f 72 64  tors</b>. In ord
1bb0: 65 72 20 6f 66 20 70 72 65 63 65 64 65 6e 63 65  er of precedence
1bc0: 2c 20 66 72 6f 6d 20 68 69 67 68 65 73 74 20 74  , from highest t
1bd0: 6f 20 6c 6f 77 65 73 74 2c 20 74 68 65 20 6f 70  o lowest, the op
1be0: 65 72 61 74 6f 72 73 20 0a 61 72 65 3a 0a 0a 3c  erators .are:..<
1bf0: 74 61 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e  table striped=1>
1c00: 0a 20 20 3c 74 72 3e 3c 74 68 3e 4f 70 65 72 61  .  <tr><th>Opera
1c10: 74 6f 72 20 3c 74 68 3e 46 75 6e 63 74 69 6f 6e  tor <th>Function
1c20: 0a 20 20 3c 74 72 3e 3c 74 64 3e 3c 63 6f 64 65  .  <tr><td><code
1c30: 3e 26 6c 74 3b 71 75 65 72 79 31 26 67 74 3b 20  >&lt;query1&gt; 
1c40: 41 4e 44 20 26 6c 74 3b 71 75 65 72 79 32 26 67  AND &lt;query2&g
1c50: 74 3b 3c 2f 63 6f 64 65 3e 20 0a 20 20 20 20 20  t;</code> .     
1c60: 20 3c 74 64 3e 4d 61 74 63 68 65 73 20 69 66 20   <td>Matches if 
1c70: 62 6f 74 68 20 71 75 65 72 79 31 20 61 6e 64 20  both query1 and 
1c80: 71 75 65 72 79 32 20 6d 61 74 63 68 2e 0a 0a 20  query2 match... 
1c90: 20 3c 74 72 3e 3c 74 64 3e 3c 63 6f 64 65 3e 26   <tr><td><code>&
1ca0: 6c 74 3b 71 75 65 72 79 31 26 67 74 3b 20 4f 52  lt;query1&gt; OR
1cb0: 20 26 6c 74 3b 71 75 65 72 79 32 26 67 74 3b 3c   &lt;query2&gt;<
1cc0: 2f 63 6f 64 65 3e 20 0a 20 20 20 20 20 20 3c 74  /code> .      <t
1cd0: 64 3e 4d 61 74 63 68 65 73 20 69 66 20 65 69 74  d>Matches if eit
1ce0: 68 65 72 20 71 75 65 72 79 31 20 6f 72 20 71 75  her query1 or qu
1cf0: 65 72 79 32 20 6d 61 74 63 68 2e 0a 0a 20 20 3c  ery2 match...  <
1d00: 74 72 3e 3c 74 64 3e 3c 63 6f 64 65 3e 26 6c 74  tr><td><code>&lt
1d10: 3b 71 75 65 72 79 31 26 67 74 3b 20 4e 4f 54 20  ;query1&gt; NOT 
1d20: 26 6c 74 3b 71 75 65 72 79 32 26 67 74 3b 3c 2f  &lt;query2&gt;</
1d30: 63 6f 64 65 3e 20 0a 20 20 20 20 20 20 3c 74 64  code> .      <td
1d40: 3e 4d 61 74 63 68 65 73 20 69 66 20 71 75 65 72  >Matches if quer
1d50: 79 31 20 6d 61 74 63 68 65 73 20 61 6e 64 20 71  y1 matches and q
1d60: 75 65 72 79 32 20 64 6f 65 73 20 6e 6f 74 20 6d  uery2 does not m
1d70: 61 74 63 68 2e 0a 0a 3c 2f 74 61 62 6c 65 3e 0a  atch...</table>.
1d80: 0a 3c 70 3e 0a 50 61 72 65 6e 74 68 65 73 69 73  .<p>.Parenthesis
1d90: 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1da0: 67 72 6f 75 70 20 65 78 70 72 65 73 73 69 6f 6e  group expression
1db0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6d 6f  s in order to mo
1dc0: 64 69 66 79 20 6f 70 65 72 61 74 6f 72 0a 70 72  dify operator.pr
1dd0: 65 63 65 64 65 6e 63 65 20 69 6e 20 74 68 65 20  ecedence in the 
1de0: 75 73 75 61 6c 20 77 61 79 73 2e 20 46 6f 72 20  usual ways. For 
1df0: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
1e00: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 4d 61  lock>.  <i>-- Ma
1e10: 74 63 68 65 73 20 64 6f 63 75 6d 65 6e 74 73 20  tches documents 
1e20: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 74 20  that contain at 
1e30: 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73 74 61 6e  least one instan
1e40: 63 65 20 6f 66 20 65 69 74 68 65 72 20 22 6f 6e  ce of either "on
1e50: 65 22 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 6f  e"</i>.  <i>-- o
1e60: 72 20 22 74 77 6f 22 2c 20 62 75 74 20 64 6f 20  r "two", but do 
1e70: 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 6e 79 20  not contain any 
1e80: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 6f 6b  instances of tok
1e90: 65 6e 20 22 74 68 72 65 65 22 2e 3c 2f 69 3e 0a  en "three".</i>.
1ea0: 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 6f 6e 65    ... MATCH 'one
1eb0: 20 4f 52 20 74 77 6f 20 4e 4f 54 20 74 68 72 65   OR two NOT thre
1ec0: 65 27 0a 0a 20 20 3c 69 3e 2d 2d 20 4d 61 74 63  e'..  <i>-- Matc
1ed0: 68 20 61 6c 6c 20 64 6f 63 75 6d 65 6e 74 73 20  h all documents 
1ee0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65  that contain the
1ef0: 20 74 6f 6b 65 6e 20 22 74 77 6f 22 20 62 75 74   token "two" but
1f00: 20 6e 6f 74 20 22 74 68 72 65 65 22 2c 20 6f 72   not "three", or
1f10: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63 6f 6e  </i>.  <i>-- con
1f20: 74 61 69 6e 20 74 68 65 20 74 6f 6b 65 6e 20 22  tain the token "
1f30: 6f 6e 65 22 2e 3c 2f 69 3e 0a 20 20 2e 2e 2e 20  one".</i>.  ... 
1f40: 4d 41 54 43 48 20 27 6f 6e 65 20 4f 52 20 28 74  MATCH 'one OR (t
1f50: 77 6f 20 4e 4f 54 20 74 68 72 65 65 29 27 0a 3c  wo NOT three)'.<
1f60: 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e  /codeblock>..<p>
1f70: 0a 50 68 72 61 73 65 73 20 61 6e 64 20 4e 45 41  .Phrases and NEA
1f80: 52 20 67 72 6f 75 70 73 20 6d 61 79 20 61 6c 73  R groups may als
1f90: 6f 20 62 65 20 63 6f 6e 6e 65 63 74 65 64 20 62  o be connected b
1fa0: 79 20 3c 62 3e 69 6d 70 6c 69 63 69 74 20 41 4e  y <b>implicit AN
1fb0: 44 20 6f 70 65 72 61 74 6f 72 73 3c 2f 62 3e 2e  D operators</b>.
1fc0: 0a 46 6f 72 20 73 69 6d 70 6c 69 63 69 74 79 2c  .For simplicity,
1fd0: 20 74 68 65 73 65 20 61 72 65 20 6e 6f 74 20 73   these are not s
1fe0: 68 6f 77 6e 20 69 6e 20 74 68 65 20 42 4e 46 20  hown in the BNF 
1ff0: 67 72 61 6d 6d 61 72 20 61 62 6f 76 65 2e 20 45  grammar above. E
2000: 73 73 65 6e 74 69 61 6c 6c 79 2c 20 61 6e 79 0a  ssentially, any.
2010: 73 65 71 75 65 6e 63 65 20 6f 66 20 70 68 72 61  sequence of phra
2020: 73 65 73 20 6f 72 20 4e 45 41 52 20 67 72 6f 75  ses or NEAR grou
2030: 70 73 20 28 69 6e 63 6c 75 64 69 6e 67 20 74 68  ps (including th
2040: 6f 73 65 20 72 65 73 74 72 69 63 74 65 64 20 74  ose restricted t
2050: 6f 20 6d 61 74 63 68 69 6e 67 0a 73 70 65 63 69  o matching.speci
2060: 66 69 65 64 20 63 6f 6c 75 6d 6e 73 29 20 73 65  fied columns) se
2070: 70 61 72 61 74 65 64 20 6f 6e 6c 79 20 62 79 20  parated only by 
2080: 77 68 69 74 65 73 70 61 63 65 20 61 72 65 20 68  whitespace are h
2090: 61 6e 64 6c 65 64 20 61 73 20 69 66 20 74 68 65  andled as if the
20a0: 72 65 20 77 65 72 65 20 61 6e 0a 69 6d 70 6c 69  re were an.impli
20b0: 63 69 74 20 41 4e 44 20 6f 70 65 72 61 74 6f 72  cit AND operator
20c0: 20 62 65 74 77 65 65 6e 20 65 61 63 68 20 70 61   between each pa
20d0: 69 72 20 6f 66 20 70 68 72 61 73 65 73 20 6f 72  ir of phrases or
20e0: 20 4e 45 41 52 20 67 72 6f 75 70 73 2e 20 49 6d   NEAR groups. Im
20f0: 70 6c 69 63 69 74 0a 41 4e 44 20 6f 70 65 72 61  plicit.AND opera
2100: 74 6f 72 73 20 61 72 65 20 6e 65 76 65 72 20 69  tors are never i
2110: 6e 73 65 72 74 65 64 20 61 66 74 65 72 20 6f 72  nserted after or
2120: 20 62 65 66 6f 72 65 20 61 6e 20 65 78 70 72 65   before an expre
2130: 73 73 69 6f 6e 20 65 6e 63 6c 6f 73 65 64 20 69  ssion enclosed i
2140: 6e 0a 70 61 72 65 6e 74 68 65 73 69 73 2e 20 46  n.parenthesis. F
2150: 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f  or example:..<co
2160: 64 65 62 6c 6f 63 6b 3e 0a 20 20 2e 2e 2e 20 4d  deblock>.  ... M
2170: 41 54 43 48 20 27 6f 6e 65 20 74 77 6f 20 74 68  ATCH 'one two th
2180: 72 65 65 27 20 20 20 20 20 20 20 20 20 3c 69 3e  ree'         <i>
2190: 2d 2d 20 27 6f 6e 65 20 41 4e 44 20 74 77 6f 20  -- 'one AND two 
21a0: 41 4e 44 20 74 68 72 65 65 27 3c 2f 69 3e 0a 20  AND three'</i>. 
21b0: 20 2e 2e 2e 20 4d 41 54 43 48 20 27 74 68 72 65   ... MATCH 'thre
21c0: 65 20 22 6f 6e 65 20 74 77 6f 22 27 20 20 20 20  e "one two"'    
21d0: 20 20 20 3c 69 3e 2d 2d 20 27 74 68 72 65 65 20     <i>-- 'three 
21e0: 41 4e 44 20 22 6f 6e 65 20 74 77 6f 22 27 3c 2f  AND "one two"'</
21f0: 69 3e 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27  i>.  ... MATCH '
2200: 4e 45 41 52 28 6f 6e 65 20 74 77 6f 29 20 74 68  NEAR(one two) th
2210: 72 65 65 27 20 20 20 3c 69 3e 2d 2d 20 27 4e 45  ree'   <i>-- 'NE
2220: 41 52 28 6f 6e 65 20 74 77 6f 29 20 41 4e 44 20  AR(one two) AND 
2230: 74 68 72 65 65 27 3c 2f 69 3e 0a 20 20 2e 2e 2e  three'</i>.  ...
2240: 20 4d 41 54 43 48 20 27 6f 6e 65 20 4f 52 20 74   MATCH 'one OR t
2250: 77 6f 20 74 68 72 65 65 27 20 20 20 20 20 20 3c  wo three'      <
2260: 69 3e 2d 2d 20 27 6f 6e 65 20 4f 52 20 74 77 6f  i>-- 'one OR two
2270: 20 41 4e 44 20 74 68 72 65 65 27 3c 2f 69 3e 0a   AND three'</i>.
2280: 0a 20 20 2e 2e 2e 20 4d 41 54 43 48 20 27 28 6f  .  ... MATCH '(o
2290: 6e 65 20 4f 52 20 74 77 6f 29 20 74 68 72 65 65  ne OR two) three
22a0: 27 20 20 20 20 3c 69 3e 2d 2d 20 53 79 6e 74 61  '    <i>-- Synta
22b0: 78 20 65 72 72 6f 72 21 3c 2f 69 3e 0a 20 20 2e  x error!</i>.  .
22c0: 2e 2e 20 4d 41 54 43 48 20 27 66 75 6e 63 28 6f  .. MATCH 'func(o
22d0: 6e 65 20 74 77 6f 29 27 20 20 20 20 20 20 20 20  ne two)'        
22e0: 20 3c 69 3e 2d 2d 20 53 79 6e 74 61 78 20 65 72   <i>-- Syntax er
22f0: 72 6f 72 21 3c 2f 69 3e 0a 3c 2f 63 6f 64 65 62  ror!</i>.</codeb
2300: 6c 6f 63 6b 3e 0a 0a 3c 68 31 20 74 61 67 73 3d  lock>..<h1 tags=
2310: 22 46 54 53 35 20 70 72 65 66 69 78 20 69 6e 64  "FTS5 prefix ind
2320: 65 78 65 73 22 3e 50 72 65 66 69 78 20 49 6e 64  exes">Prefix Ind
2330: 65 78 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 20 42  exes</h1>..<p> B
2340: 79 20 64 65 66 61 75 6c 74 2c 20 46 54 53 35 20  y default, FTS5 
2350: 6d 61 69 6e 74 61 69 6e 73 20 61 20 73 69 6e 67  maintains a sing
2360: 6c 65 20 69 6e 64 65 78 20 72 65 63 6f 72 64 69  le index recordi
2370: 6e 67 20 74 68 65 20 6c 6f 63 61 74 69 6f 6e 20  ng the location 
2380: 6f 66 20 65 61 63 68 0a 74 6f 6b 65 6e 20 69 6e  of each.token in
2390: 73 74 61 6e 63 65 20 77 69 74 68 69 6e 20 74 68  stance within th
23a0: 65 20 64 6f 63 75 6d 65 6e 74 20 73 65 74 2e 20  e document set. 
23b0: 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
23c0: 71 75 65 72 79 69 6e 67 20 66 6f 72 20 63 6f 6d  querying for com
23d0: 70 6c 65 74 65 0a 74 6f 6b 65 6e 73 20 69 73 20  plete.tokens is 
23e0: 66 61 73 74 2c 20 61 73 20 69 74 20 72 65 71 75  fast, as it requ
23f0: 69 72 65 73 20 61 20 73 69 6e 67 6c 65 20 6c 6f  ires a single lo
2400: 6f 6b 75 70 2c 20 62 75 74 20 71 75 65 72 79 69  okup, but queryi
2410: 6e 67 20 66 6f 72 20 61 20 70 72 65 66 69 78 20  ng for a prefix 
2420: 0a 74 6f 6b 65 6e 20 63 61 6e 20 62 65 20 73 6c  .token can be sl
2430: 6f 77 2c 20 61 73 20 69 74 20 72 65 71 75 69 72  ow, as it requir
2440: 65 73 20 61 20 72 61 6e 67 65 20 73 63 61 6e 2e  es a range scan.
2450: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   For example, to
2460: 20 71 75 65 72 79 20 66 6f 72 0a 74 68 65 20 70   query for.the p
2470: 72 65 66 69 78 20 74 6f 6b 65 6e 20 22 61 62 63  refix token "abc
2480: 2a 22 20 72 65 71 75 69 72 65 73 20 61 20 72 61  *" requires a ra
2490: 6e 67 65 20 73 63 61 6e 20 6f 66 20 61 6c 6c 20  nge scan of all 
24a0: 74 6f 6b 65 6e 73 20 67 72 65 61 74 65 72 20 74  tokens greater t
24b0: 68 61 6e 0a 6f 72 20 65 71 75 61 6c 20 74 6f 20  han.or equal to 
24c0: 22 61 62 63 22 20 61 6e 64 20 6c 65 73 73 20 74  "abc" and less t
24d0: 68 61 6e 20 22 61 62 64 22 2e 0a 0a 3c 70 3e 20  han "abd"...<p> 
24e0: 41 20 70 72 65 66 69 78 20 69 6e 64 65 78 20 69  A prefix index i
24f0: 73 20 61 20 73 65 70 61 72 61 74 65 20 69 6e 64  s a separate ind
2500: 65 78 20 74 68 61 74 20 72 65 63 6f 72 64 73 20  ex that records 
2510: 74 68 65 20 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  the location of 
2520: 61 6c 6c 0a 69 6e 73 74 61 6e 63 65 73 20 6f 66  all.instances of
2530: 20 70 72 65 66 69 78 20 74 6f 6b 65 6e 73 20 6f   prefix tokens o
2540: 66 20 61 20 63 65 72 74 61 69 6e 20 6c 65 6e 67  f a certain leng
2550: 74 68 20 69 6e 20 63 68 61 72 61 63 74 65 72 73  th in characters
2560: 20 75 73 65 64 20 74 6f 20 73 70 65 65 64 0a 75   used to speed.u
2570: 70 20 71 75 65 72 69 65 73 20 66 6f 72 20 70 72  p queries for pr
2580: 65 66 69 78 20 74 6f 6b 65 6e 73 2e 20 46 6f 72  efix tokens. For
2590: 20 65 78 61 6d 70 6c 65 2c 20 6f 70 74 69 6d 69   example, optimi
25a0: 7a 69 6e 67 20 61 20 71 75 65 72 79 20 66 6f 72  zing a query for
25b0: 20 70 72 65 66 69 78 0a 74 6f 6b 65 6e 20 22 61   prefix.token "a
25c0: 62 63 2a 22 20 72 65 71 75 69 72 65 73 20 61 20  bc*" requires a 
25d0: 70 72 65 66 69 78 20 69 6e 64 65 78 20 6f 66 20  prefix index of 
25e0: 74 68 72 65 65 2d 63 68 61 72 61 63 74 65 72 20  three-character 
25f0: 70 72 65 66 69 78 65 73 2e 0a 0a 3c 70 3e 20 54  prefixes...<p> T
2600: 6f 20 61 64 64 20 70 72 65 66 69 78 20 69 6e 64  o add prefix ind
2610: 65 78 65 73 20 74 6f 20 61 6e 20 46 54 53 35 20  exes to an FTS5 
2620: 74 61 62 6c 65 2c 20 74 68 65 20 22 70 72 65 66  table, the "pref
2630: 69 78 22 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ix" option is se
2640: 74 20 74 6f 0a 65 69 74 68 65 72 20 61 20 73 69  t to.either a si
2650: 6e 67 6c 65 20 70 6f 73 69 74 69 76 65 20 69 6e  ngle positive in
2660: 74 65 67 65 72 20 6f 72 20 61 20 74 65 78 74 20  teger or a text 
2670: 76 61 6c 75 65 20 63 6f 6e 74 61 69 6e 69 6e 67  value containing
2680: 20 61 20 77 68 69 74 65 2d 73 70 61 63 65 0a 73   a white-space.s
2690: 65 70 61 72 61 74 65 64 20 6c 69 73 74 20 6f 66  eparated list of
26a0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 70 6f 73   one or more pos
26b0: 69 74 69 76 65 20 69 6e 74 65 67 65 72 20 76 61  itive integer va
26c0: 6c 75 65 73 2e 20 41 20 70 72 65 66 69 78 20 69  lues. A prefix i
26d0: 6e 64 65 78 20 69 73 0a 63 72 65 61 74 65 64 20  ndex is.created 
26e0: 66 6f 72 20 65 61 63 68 20 69 6e 74 65 67 65 72  for each integer
26f0: 20 73 70 65 63 69 66 69 65 64 2e 20 49 66 20 6d   specified. If m
2700: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 22 70 72  ore than one "pr
2710: 65 66 69 78 22 20 6f 70 74 69 6f 6e 20 69 73 0a  efix" option is.
2720: 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
2730: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 43 52  t of a single CR
2740: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
2750: 4c 45 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6c  LE statement, al
2760: 6c 20 61 70 70 6c 79 2e 0a 0a 3c 63 6f 64 65 62  l apply...<codeb
2770: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 77  lock>.  <i>-- Tw
2780: 6f 20 77 61 79 73 20 74 6f 20 63 72 65 61 74 65  o ways to create
2790: 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20 74   an FTS5 table t
27a0: 68 61 74 20 6d 61 69 6e 74 61 69 6e 73 20 70 72  hat maintains pr
27b0: 65 66 69 78 20 69 6e 64 65 78 65 73 20 66 6f 72  efix indexes for
27c0: 0a 20 20 2d 2d 20 74 77 6f 20 61 6e 64 20 74 68  .  -- two and th
27d0: 72 65 65 20 63 68 61 72 61 63 74 65 72 20 70 72  ree character pr
27e0: 65 66 69 78 20 74 6f 6b 65 6e 73 2e 3c 2f 69 3e  efix tokens.</i>
27f0: 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41  .  CREATE VIRTUA
2800: 4c 20 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47  L TABLE ft USING
2810: 20 66 74 73 35 28 61 2c 20 62 2c 20 70 72 65 66   fts5(a, b, pref
2820: 69 78 3d 27 32 20 33 27 29 3b 0a 20 20 43 52 45  ix='2 3');.  CRE
2830: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
2840: 45 20 66 74 20 55 53 49 4e 47 20 66 74 73 35 28  E ft USING fts5(
2850: 61 2c 20 62 2c 20 70 72 65 66 69 78 3d 32 2c 20  a, b, prefix=2, 
2860: 70 72 65 66 69 78 3d 33 29 3b 0a 3c 2f 63 6f 64  prefix=3);.</cod
2870: 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 31 20 74 61 67  eblock>..<h1 tag
2880: 73 3d 22 46 54 53 35 20 74 6f 6b 65 6e 69 7a 65  s="FTS5 tokenize
2890: 72 73 22 3e 54 6f 6b 65 6e 69 7a 65 72 73 3c 2f  rs">Tokenizers</
28a0: 68 31 3e 0a 0a 3c 70 3e 20 54 68 65 20 43 52 45  h1>..<p> The CRE
28b0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
28c0: 45 20 22 74 6f 6b 65 6e 69 7a 65 22 20 6f 70 74  E "tokenize" opt
28d0: 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
28e0: 6f 6e 66 69 67 75 72 65 20 74 68 65 0a 73 70 65  onfigure the.spe
28f0: 63 69 66 69 63 20 74 6f 6b 65 6e 69 7a 65 72 20  cific tokenizer 
2900: 75 73 65 64 20 62 79 20 74 68 65 20 46 54 53 35  used by the FTS5
2910: 20 74 61 62 6c 65 2e 20 54 68 65 20 6f 70 74 69   table. The opti
2920: 6f 6e 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  on argument must
2930: 20 62 65 20 65 69 74 68 65 72 0a 61 6e 20 46 54   be either.an FT
2940: 53 35 20 62 61 72 65 77 6f 72 64 2c 20 6f 72 20  S5 bareword, or 
2950: 61 6e 20 53 51 4c 20 74 65 78 74 20 6c 69 74 65  an SQL text lite
2960: 72 61 6c 2e 20 54 68 65 20 74 65 78 74 20 6f 66  ral. The text of
2970: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
2980: 20 69 74 73 65 6c 66 0a 74 72 65 61 74 65 64 20   itself.treated 
2990: 61 73 20 61 20 77 68 69 74 65 2d 73 70 61 63 65  as a white-space
29a0: 20 73 65 72 69 65 73 20 6f 66 20 6f 6e 65 20 6f   series of one o
29b0: 72 20 6d 6f 72 65 20 46 54 53 35 20 62 61 72 65  r more FTS5 bare
29c0: 77 6f 72 64 73 20 6f 72 20 53 51 4c 20 74 65 78  words or SQL tex
29d0: 74 0a 6c 69 74 65 72 61 6c 73 2e 20 54 68 65 20  t.literals. The 
29e0: 66 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 69  first of these i
29f0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2a00: 65 20 74 6f 6b 65 6e 69 7a 65 72 20 74 6f 20 75  e tokenizer to u
2a10: 73 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 61  se. The second.a
2a20: 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 6c 69  nd subsequent li
2a30: 73 74 20 65 6c 65 6d 65 6e 74 73 2c 20 69 66 20  st elements, if 
2a40: 74 68 65 79 20 65 78 69 73 74 2c 20 61 72 65 20  they exist, are 
2a50: 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64  arguments passed
2a60: 20 74 6f 20 74 68 65 0a 74 6f 6b 65 6e 69 7a 65   to the.tokenize
2a70: 72 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  r implementation
2a80: 2e 0a 0a 3c 70 3e 20 55 6e 6c 69 6b 65 20 6f 70  ...<p> Unlike op
2a90: 74 69 6f 6e 20 76 61 6c 75 65 73 20 61 6e 64 20  tion values and 
2aa0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 2c 20 53 51  column names, SQ
2ab0: 4c 20 74 65 78 74 20 6c 69 74 65 72 61 6c 73 20  L text literals 
2ac0: 69 6e 74 65 6e 64 65 64 20 61 73 0a 74 6f 6b 65  intended as.toke
2ad0: 6e 69 7a 65 72 73 20 6d 75 73 74 20 62 65 20 71  nizers must be q
2ae0: 75 6f 74 65 64 20 75 73 69 6e 67 20 73 69 6e 67  uoted using sing
2af0: 6c 65 20 71 75 6f 74 65 20 63 68 61 72 61 63 74  le quote charact
2b00: 65 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ers. For example
2b10: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
2b20: 20 3c 69 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f   <i>-- The follo
2b30: 77 69 6e 67 20 61 72 65 20 61 6c 6c 20 65 71 75  wing are all equ
2b40: 69 76 61 6c 65 6e 74 3c 2f 69 3e 0a 20 20 43 52  ivalent</i>.  CR
2b50: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
2b60: 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35  LE t1 USING fts5
2b70: 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  (x, tokenize = '
2b80: 70 6f 72 74 65 72 20 61 73 63 69 69 27 29 3b 0a  porter ascii');.
2b90: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
2ba0: 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20   TABLE t1 USING 
2bb0: 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65  fts5(x, tokenize
2bc0: 20 3d 20 22 70 6f 72 74 65 72 20 61 73 63 69 69   = "porter ascii
2bd0: 22 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49 52  ");.  CREATE VIR
2be0: 54 55 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53  TUAL TABLE t1 US
2bf0: 49 4e 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65  ING fts5(x, toke
2c00: 6e 69 7a 65 20 3d 20 22 27 70 6f 72 74 65 72 27  nize = "'porter'
2c10: 20 27 61 73 63 69 69 27 22 29 3b 0a 20 20 43 52   'ascii'");.  CR
2c20: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
2c30: 4c 45 20 74 31 20 55 53 49 4e 47 20 66 74 73 35  LE t1 USING fts5
2c40: 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27  (x, tokenize = '
2c50: 27 27 70 6f 72 74 65 72 27 27 20 27 27 61 73 63  ''porter'' ''asc
2c60: 69 69 27 27 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d  ii''');..  <i>--
2c70: 20 42 75 74 20 74 68 69 73 20 77 69 6c 6c 20 66   But this will f
2c80: 61 69 6c 3a 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ail:</i>.  CREAT
2c90: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
2ca0: 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78 2c  t1 USING fts5(x,
2cb0: 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 22 70 6f   tokenize = '"po
2cc0: 72 74 65 72 22 20 22 61 73 63 69 69 22 27 29 3b  rter" "ascii"');
2cd0: 0a 0a 20 20 3c 69 3e 2d 2d 20 54 68 69 73 20 77  ..  <i>-- This w
2ce0: 69 6c 6c 20 66 61 69 6c 20 74 6f 6f 3a 3c 2f 69  ill fail too:</i
2cf0: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
2d00: 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e  AL TABLE t1 USIN
2d10: 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69  G fts5(x, tokeni
2d20: 7a 65 20 3d 20 27 70 6f 72 74 65 72 27 20 27 61  ze = 'porter' 'a
2d30: 73 63 69 69 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c  scii');.</codebl
2d40: 6f 63 6b 3e 0a 0a 0a 3c 70 3e 0a 46 54 53 35 20  ock>...<p>.FTS5 
2d50: 66 65 61 74 75 72 65 73 20 74 68 72 65 65 20 62  features three b
2d60: 75 69 6c 74 2d 69 6e 20 74 6f 6b 65 6e 69 7a 65  uilt-in tokenize
2d70: 72 20 6d 6f 64 75 6c 65 73 2c 20 64 65 73 63 72  r modules, descr
2d80: 69 62 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  ibed in subseque
2d90: 6e 74 0a 73 65 63 74 69 6f 6e 73 3a 0a 0a 3c 75  nt.sections:..<u
2da0: 6c 3e 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62  l>.  <li> The <b
2db0: 3e 75 6e 69 63 6f 64 65 36 31 3c 2f 62 3e 20 74  >unicode61</b> t
2dc0: 6f 6b 65 6e 69 7a 65 72 2c 20 62 61 73 65 64 20  okenizer, based 
2dd0: 6f 6e 20 74 68 65 20 55 6e 69 63 6f 64 65 20 36  on the Unicode 6
2de0: 2e 31 20 73 74 61 6e 64 61 72 64 2e 20 54 68 69  .1 standard. Thi
2df0: 73 0a 20 20 20 20 20 20 20 69 73 20 74 68 65 20  s.       is the 
2e00: 64 65 66 61 75 6c 74 2e 0a 0a 20 20 3c 6c 69 3e  default...  <li>
2e10: 20 54 68 65 20 3c 62 3e 61 73 63 69 69 3c 2f 62   The <b>ascii</b
2e20: 3e 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 77 68 69  > tokenizer, whi
2e30: 63 68 20 61 73 73 75 6d 65 73 20 61 6c 6c 20 63  ch assumes all c
2e40: 68 61 72 61 63 74 65 72 73 20 6f 75 74 73 69 64  haracters outsid
2e50: 65 20 6f 66 0a 20 20 74 68 65 20 41 53 43 49 49  e of.  the ASCII
2e60: 20 63 6f 64 65 70 6f 69 6e 74 20 72 61 6e 67 65   codepoint range
2e70: 20 28 30 2d 31 32 37 29 20 61 72 65 20 74 6f 20   (0-127) are to 
2e80: 62 65 20 74 72 65 61 74 65 64 20 61 73 20 74 6f  be treated as to
2e90: 6b 65 6e 20 63 68 61 72 61 63 74 65 72 73 2e 0a  ken characters..
2ea0: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e 70  .  <li> The <b>p
2eb0: 6f 72 74 65 72 3c 2f 62 3e 20 74 6f 6b 65 6e 69  orter</b> tokeni
2ec0: 7a 65 72 2c 20 77 68 69 63 68 20 69 6d 70 6c 65  zer, which imple
2ed0: 6d 65 6e 74 73 20 74 68 65 20 0a 3c 61 20 68 72  ments the .<a hr
2ee0: 65 66 3d 68 74 74 70 3a 2f 2f 74 61 72 74 61 72  ef=http://tartar
2ef0: 75 73 2e 6f 72 67 2f 6d 61 72 74 69 6e 2f 50 6f  us.org/martin/Po
2f00: 72 74 65 72 53 74 65 6d 6d 65 72 2f 3e 70 6f 72  rterStemmer/>por
2f10: 74 65 72 20 73 74 65 6d 6d 69 6e 67 20 61 6c 67  ter stemming alg
2f20: 6f 72 69 74 68 6d 3c 2f 61 3e 2e 0a 3c 2f 75 6c  orithm</a>..</ul
2f30: 3e 0a 0a 3c 70 3e 20 49 74 20 69 73 20 61 6c 73  >..<p> It is als
2f40: 6f 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 72  o possible to cr
2f50: 65 61 74 65 20 63 75 73 74 6f 6d 20 74 6f 6b 65  eate custom toke
2f60: 6e 69 7a 65 72 73 20 66 6f 72 20 46 54 53 35 2e  nizers for FTS5.
2f70: 20 54 68 65 20 41 50 49 20 66 6f 72 20 64 6f 69   The API for doi
2f80: 6e 67 20 73 6f 20 69 73 20 5b 63 75 73 74 6f 6d  ng so is [custom
2f90: 20 74 6f 6b 65 6e 69 7a 65 72 73 20 7c 20 64 65   tokenizers | de
2fa0: 73 63 72 69 62 65 64 20 68 65 72 65 5d 2e 0a 0a  scribed here]...
2fb0: 3c 68 32 3e 55 6e 69 63 6f 64 65 36 31 20 54 6f  <h2>Unicode61 To
2fc0: 6b 65 6e 69 7a 65 72 3c 2f 68 32 3e 0a 0a 3c 70  kenizer</h2>..<p
2fd0: 3e 20 54 68 65 20 75 6e 69 63 6f 64 65 20 74 6f  > The unicode to
2fe0: 6b 65 6e 69 7a 65 72 20 63 6c 61 73 73 69 66 69  kenizer classifi
2ff0: 65 73 20 61 6c 6c 20 75 6e 69 63 6f 64 65 20 63  es all unicode c
3000: 68 61 72 61 63 74 65 72 73 20 61 73 20 65 69 74  haracters as eit
3010: 68 65 72 20 0a 22 73 65 70 61 72 61 74 6f 72 22  her ."separator"
3020: 20 6f 72 20 22 74 6f 6b 65 6e 22 20 63 68 61 72   or "token" char
3030: 61 63 74 65 72 73 2e 20 42 79 20 64 65 66 61 75  acters. By defau
3040: 6c 74 20 61 6c 6c 20 73 70 61 63 65 20 61 6e 64  lt all space and
3050: 20 70 75 6e 63 74 75 61 74 69 6f 6e 0a 63 68 61   punctuation.cha
3060: 72 61 63 74 65 72 73 2c 20 61 73 20 64 65 66 69  racters, as defi
3070: 6e 65 64 20 62 79 20 55 6e 69 63 6f 64 65 20 36  ned by Unicode 6
3080: 2e 31 2c 20 61 72 65 20 63 6f 6e 73 69 64 65 72  .1, are consider
3090: 65 64 20 73 65 70 61 72 61 74 6f 72 73 2c 20 61  ed separators, a
30a0: 6e 64 20 61 6c 6c 20 0a 6f 74 68 65 72 20 63 68  nd all .other ch
30b0: 61 72 61 63 74 65 72 73 20 61 73 20 74 6f 6b 65  aracters as toke
30c0: 6e 20 63 68 61 72 61 63 74 65 72 73 2e 20 45 61  n characters. Ea
30d0: 63 68 20 63 6f 6e 74 69 67 75 6f 75 73 20 72 75  ch contiguous ru
30e0: 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  n of one or more
30f0: 20 0a 74 6f 6b 65 6e 20 63 68 61 72 61 63 74 65   .token characte
3100: 72 73 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  rs is considered
3110: 20 74 6f 20 62 65 20 61 20 74 6f 6b 65 6e 2e 20   to be a token. 
3120: 54 68 65 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73  The tokenizer is
3130: 20 63 61 73 65 2d 69 6e 73 65 6e 73 69 74 69 76   case-insensitiv
3140: 65 0a 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  e.according to t
3150: 68 65 20 72 75 6c 65 73 20 64 65 66 69 6e 65 64  he rules defined
3160: 20 62 79 20 55 6e 69 63 6f 64 65 20 36 2e 31 2e   by Unicode 6.1.
3170: 0a 0a 3c 70 3e 20 42 79 20 64 65 66 61 75 6c 74  ..<p> By default
3180: 2c 20 64 69 61 63 72 69 74 69 63 73 20 61 72 65  , diacritics are
3190: 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 61 6c   removed from al
31a0: 6c 20 4c 61 74 69 6e 20 73 63 72 69 70 74 20 63  l Latin script c
31b0: 68 61 72 61 63 74 65 72 73 2e 20 54 68 69 73 0a  haracters. This.
31c0: 6d 65 61 6e 73 2c 20 66 6f 72 20 65 78 61 6d 70  means, for examp
31d0: 6c 65 2c 20 74 68 61 74 20 22 41 22 2c 20 22 61  le, that "A", "a
31e0: 22 2c 20 22 26 23 31 39 32 3b 22 2c 20 22 26 23  ", "&#192;", "&#
31f0: 32 32 34 3b 22 2c 20 22 26 23 31 39 34 3b 22 20  224;", "&#194;" 
3200: 61 6e 64 20 22 26 23 32 32 36 3b 22 0a 61 72 65  and "&#226;".are
3210: 20 61 6c 6c 20 63 6f 6e 73 69 64 65 72 65 64 20   all considered 
3220: 74 6f 20 62 65 20 65 71 75 69 76 61 6c 65 6e 74  to be equivalent
3230: 2e 0a 0a 3c 70 3e 20 41 6e 79 20 61 72 67 75 6d  ...<p> Any argum
3240: 65 6e 74 73 20 66 6f 6c 6c 6f 77 69 6e 67 20 22  ents following "
3250: 75 6e 69 63 6f 64 65 36 31 22 20 69 6e 20 74 68  unicode61" in th
3260: 65 20 74 6f 6b 65 6e 20 73 70 65 63 69 66 69 63  e token specific
3270: 61 74 69 6f 6e 20 61 72 65 20 74 72 65 61 74 65  ation are treate
3280: 64 0a 61 73 20 61 20 6c 69 73 74 20 6f 66 20 61  d.as a list of a
3290: 6c 74 65 72 6e 61 74 69 6e 67 20 6f 70 74 69 6f  lternating optio
32a0: 6e 20 6e 61 6d 65 73 20 61 6e 64 20 76 61 6c 75  n names and valu
32b0: 65 73 2e 20 55 6e 69 63 6f 64 65 36 31 20 73 75  es. Unicode61 su
32c0: 70 70 6f 72 74 73 20 74 68 65 0a 66 6f 6c 6c 6f  pports the.follo
32d0: 77 69 6e 67 20 6f 70 74 69 6f 6e 73 3a 0a 0a 3c  wing options:..<
32e0: 74 61 62 6c 65 20 73 74 72 69 70 65 64 3d 31 3e  table striped=1>
32f0: 0a 20 20 3c 74 72 3e 3c 74 68 3e 20 4f 70 74 69  .  <tr><th> Opti
3300: 6f 6e 20 3c 74 68 3e 20 55 73 61 67 65 0a 20 20  on <th> Usage.  
3310: 3c 74 72 3e 3c 74 64 3e 20 72 65 6d 6f 76 65 5f  <tr><td> remove_
3320: 64 69 61 63 72 69 74 69 63 73 0a 20 20 3c 74 64  diacritics.  <td
3330: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 68 6f  >This option sho
3340: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 22 30  uld be set to "0
3350: 22 20 6f 72 20 22 31 22 2e 20 49 66 20 69 74 20  " or "1". If it 
3360: 69 73 20 73 65 74 20 28 74 68 65 20 64 65 66 61  is set (the defa
3370: 75 6c 74 29 2c 0a 20 20 64 69 61 63 72 69 74 69  ult),.  diacriti
3380: 63 73 20 61 72 65 20 72 65 6d 6f 76 65 64 20 66  cs are removed f
3390: 72 6f 6d 20 61 6c 6c 20 6c 61 74 69 6e 20 73 63  rom all latin sc
33a0: 72 69 70 74 20 63 68 61 72 61 63 74 65 72 73 20  ript characters 
33b0: 61 73 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  as described abo
33c0: 76 65 2e 0a 20 20 49 66 20 69 74 20 69 73 20 63  ve..  If it is c
33d0: 6c 65 61 72 2c 20 74 68 65 79 20 61 72 65 20 6e  lear, they are n
33e0: 6f 74 2e 20 0a 0a 20 20 3c 74 72 3e 3c 74 64 3e  ot. ..  <tr><td>
33f0: 20 74 6f 6b 65 6e 63 68 61 72 73 0a 20 20 3c 74   tokenchars.  <t
3400: 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  d> This option i
3410: 73 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  s used to specif
3420: 79 20 61 64 64 69 74 69 6f 6e 61 6c 20 75 6e 69  y additional uni
3430: 63 6f 64 65 20 63 68 61 72 61 63 74 65 72 73 20  code characters 
3440: 74 68 61 74 20 0a 20 20 73 68 6f 75 6c 64 20 62  that .  should b
3450: 65 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b  e considered tok
3460: 65 6e 20 63 68 61 72 61 63 74 65 72 73 2c 20 65  en characters, e
3470: 76 65 6e 20 69 66 20 74 68 65 79 20 61 72 65 20  ven if they are 
3480: 77 68 69 74 65 2d 73 70 61 63 65 20 6f 72 0a 20  white-space or. 
3490: 20 70 75 6e 63 74 75 61 74 69 6f 6e 20 63 68 61   punctuation cha
34a0: 72 61 63 74 65 72 73 20 61 63 63 6f 72 64 69 6e  racters accordin
34b0: 67 20 74 6f 20 55 6e 69 63 6f 64 65 20 36 2e 31  g to Unicode 6.1
34c0: 2e 20 41 6c 6c 20 63 68 61 72 61 63 74 65 72 73  . All characters
34d0: 20 69 6e 20 74 68 65 0a 20 20 73 74 72 69 6e 67   in the.  string
34e0: 20 74 68 61 74 20 74 68 69 73 20 6f 70 74 69 6f   that this optio
34f0: 6e 20 69 73 20 73 65 74 20 74 6f 20 61 72 65 20  n is set to are 
3500: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b 65 6e  considered token
3510: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 0a 20 20   characters...  
3520: 3c 74 72 3e 3c 74 64 3e 20 73 65 70 61 72 61 74  <tr><td> separat
3530: 6f 72 73 0a 20 20 3c 74 64 3e 20 54 68 69 73 20  ors.  <td> This 
3540: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
3550: 6f 20 73 70 65 63 69 66 79 20 61 64 64 69 74 69  o specify additi
3560: 6f 6e 61 6c 20 75 6e 69 63 6f 64 65 20 63 68 61  onal unicode cha
3570: 72 61 63 74 65 72 73 20 74 68 61 74 20 0a 20 20  racters that .  
3580: 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
3590: 65 72 65 64 20 61 73 20 73 65 70 61 72 61 74 6f  ered as separato
35a0: 72 20 63 68 61 72 61 63 74 65 72 73 2c 20 65 76  r characters, ev
35b0: 65 6e 20 69 66 20 74 68 65 79 20 61 72 65 20 74  en if they are t
35c0: 6f 6b 65 6e 0a 20 20 63 68 61 72 61 63 74 65 72  oken.  character
35d0: 73 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 55  s according to U
35e0: 6e 69 63 6f 64 65 20 36 2e 31 2e 20 41 6c 6c 20  nicode 6.1. All 
35f0: 63 68 61 72 61 63 74 65 72 73 20 69 6e 20 74 68  characters in th
3600: 65 20 73 74 72 69 6e 67 20 74 68 61 74 20 0a 20  e string that . 
3610: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
3620: 73 65 74 20 74 6f 20 61 72 65 20 63 6f 6e 73 69  set to are consi
3630: 64 65 72 65 64 20 73 65 70 61 72 61 74 6f 72 73  dered separators
3640: 2e 0a 3c 2f 74 61 62 6c 65 3e 0a 0a 3c 70 3e 20  ..</table>..<p> 
3650: 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63  For example:..<c
3660: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d  odeblock>.  <i>-
3670: 2d 20 43 72 65 61 74 65 20 61 6e 20 46 54 53 35  - Create an FTS5
3680: 20 74 61 62 6c 65 20 74 68 61 74 20 64 6f 65 73   table that does
3690: 20 6e 6f 74 20 72 65 6d 6f 76 65 20 64 69 61 63   not remove diac
36a0: 72 69 74 69 63 73 20 66 72 6f 6d 20 4c 61 74 69  ritics from Lati
36b0: 6e 0a 20 20 2d 2d 20 73 63 72 69 70 74 20 63 68  n.  -- script ch
36c0: 61 72 61 63 74 65 72 73 2c 20 61 6e 64 20 74 68  aracters, and th
36d0: 61 74 20 63 6f 6e 73 69 64 65 72 73 20 68 79 70  at considers hyp
36e0: 68 65 6e 73 20 61 6e 64 20 75 6e 64 65 72 73 63  hens and undersc
36f0: 6f 72 65 20 63 68 61 72 61 63 74 65 72 73 0a 20  ore characters. 
3700: 20 2d 2d 20 74 6f 20 62 65 20 70 61 72 74 20 6f   -- to be part o
3710: 66 20 74 6f 6b 65 6e 73 2e 20 3c 2f 69 3e 0a 20  f tokens. </i>. 
3720: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
3730: 54 41 42 4c 45 20 66 74 20 55 53 49 4e 47 20 66  TABLE ft USING f
3740: 74 73 35 28 61 2c 20 62 2c 20 0a 20 20 20 20 20  ts5(a, b, .     
3750: 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 22 75 6e 69   tokenize = "uni
3760: 63 6f 64 65 36 31 20 72 65 6d 6f 76 65 5f 64 69  code61 remove_di
3770: 61 63 72 69 74 69 63 73 20 30 20 74 6f 6b 65 6e  acritics 0 token
3780: 63 68 61 72 73 20 27 2d 5f 27 22 0a 20 20 29 3b  chars '-_'".  );
3790: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
37a0: 68 32 3e 41 73 63 69 69 20 54 6f 6b 65 6e 69 7a  h2>Ascii Tokeniz
37b0: 65 72 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 65  er</h2>..<p> The
37c0: 20 41 73 63 69 69 20 74 6f 6b 65 6e 69 7a 65 72   Ascii tokenizer
37d0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 74   is similar to t
37e0: 68 65 20 55 6e 69 63 6f 64 65 36 31 20 74 6f 6b  he Unicode61 tok
37f0: 65 6e 69 7a 65 72 2c 20 65 78 63 65 70 74 20 74  enizer, except t
3800: 68 61 74 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  hat:..<ul>.  <li
3810: 3e 20 41 6c 6c 20 6e 6f 6e 2d 41 53 43 49 49 20  > All non-ASCII 
3820: 63 68 61 72 61 63 74 65 72 73 20 28 74 68 6f 73  characters (thos
3830: 65 20 77 69 74 68 20 63 6f 64 65 70 6f 69 6e 74  e with codepoint
3840: 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  s greater than 1
3850: 32 37 29 20 61 72 65 0a 20 20 61 6c 77 61 79 73  27) are.  always
3860: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 6b 65   considered toke
3870: 6e 20 63 68 61 72 61 63 74 65 72 73 2e 20 49 66  n characters. If
3880: 20 61 6e 79 20 6e 6f 6e 2d 41 53 43 49 49 20 63   any non-ASCII c
3890: 68 61 72 61 63 74 65 72 73 20 61 72 65 20 73 70  haracters are sp
38a0: 65 63 69 66 69 65 64 0a 20 20 61 73 20 70 61 72  ecified.  as par
38b0: 74 20 6f 66 20 74 68 65 20 73 65 70 61 72 61 74  t of the separat
38c0: 6f 72 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 79  ors option, they
38d0: 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 20 20 0a   are ignored.  .
38e0: 0a 20 20 3c 6c 69 3e 20 43 61 73 65 2d 66 6f 6c  .  <li> Case-fol
38f0: 64 69 6e 67 20 69 73 20 6f 6e 6c 79 20 70 65 72  ding is only per
3900: 66 6f 72 6d 65 64 20 66 6f 72 20 41 53 43 49 49  formed for ASCII
3910: 20 63 68 61 72 61 63 74 65 72 73 2e 20 53 6f 20   characters. So 
3920: 77 68 69 6c 65 20 22 41 22 20 61 6e 64 0a 20 20  while "A" and.  
3930: 22 61 22 20 61 72 65 20 63 6f 6e 73 69 64 65 72  "a" are consider
3940: 65 64 20 74 6f 20 62 65 20 65 71 75 69 76 61 6c  ed to be equival
3950: 65 6e 74 2c 20 22 26 23 31 39 35 22 20 61 6e 64  ent, "&#195" and
3960: 20 22 26 23 32 32 37 3b 22 20 61 72 65 20 64 69   "&#227;" are di
3970: 73 74 69 6e 63 74 2e 0a 0a 20 20 3c 6c 69 3e 20  stinct...  <li> 
3980: 54 68 65 20 72 65 6d 6f 76 65 5f 64 69 61 63 72  The remove_diacr
3990: 69 74 69 63 73 20 6f 70 74 69 6f 6e 20 69 73 20  itics option is 
39a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 2e 0a 3c  not supported..<
39b0: 2f 75 6c 3e 0a 0a 3c 70 3e 20 46 6f 72 20 65 78  /ul>..<p> For ex
39c0: 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  ample:..<codeblo
39d0: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 43 72 65 61  ck>.  <i>-- Crea
39e0: 74 65 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65  te an FTS5 table
39f0: 20 74 68 61 74 20 75 73 65 73 20 74 68 65 20 61   that uses the a
3a00: 73 63 69 69 20 74 6f 6b 65 6e 69 7a 65 72 2c 20  scii tokenizer, 
3a10: 62 75 74 20 64 6f 65 73 20 6e 6f 74 0a 20 20 2d  but does not.  -
3a20: 2d 20 63 6f 6e 73 69 64 65 72 20 6e 75 6d 65 72  - consider numer
3a30: 69 63 20 63 68 61 72 61 63 74 65 72 73 20 74 6f  ic characters to
3a40: 20 62 65 20 70 61 72 74 20 6f 66 20 74 6f 6b 65   be part of toke
3a50: 6e 73 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45  ns.</i>.  CREATE
3a60: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
3a70: 74 20 55 53 49 4e 47 20 66 74 73 35 28 61 2c 20  t USING fts5(a, 
3a80: 62 2c 20 0a 20 20 20 20 20 20 74 6f 6b 65 6e 69  b, .      tokeni
3a90: 7a 65 20 3d 20 22 61 73 63 69 69 20 73 65 70 61  ze = "ascii sepa
3aa0: 72 61 74 6f 72 73 20 27 30 31 32 33 34 35 36 37  rators '01234567
3ab0: 38 39 27 22 0a 20 20 29 3b 0a 3c 2f 63 6f 64 65  89'".  );.</code
3ac0: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 3e 50 6f 72 74  block>..<h2>Port
3ad0: 65 72 20 54 6f 6b 65 6e 69 7a 65 72 3c 2f 68 32  er Tokenizer</h2
3ae0: 3e 0a 0a 3c 70 3e 20 54 68 65 20 70 6f 72 74 65  >..<p> The porte
3af0: 72 20 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 61  r tokenizer is a
3b00: 20 77 72 61 70 70 65 72 20 74 6f 6b 65 6e 69 7a   wrapper tokeniz
3b10: 65 72 2e 20 49 74 20 74 61 6b 65 73 20 74 68 65  er. It takes the
3b20: 20 6f 75 74 70 75 74 20 6f 66 20 73 6f 6d 65 0a   output of some.
3b30: 6f 74 68 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20  other tokenizer 
3b40: 61 6e 64 20 61 70 70 6c 69 65 73 20 74 68 65 20  and applies the 
3b50: 0a 3c 61 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f  .<a href=http://
3b60: 74 61 72 74 61 72 75 73 2e 6f 72 67 2f 6d 61 72  tartarus.org/mar
3b70: 74 69 6e 2f 50 6f 72 74 65 72 53 74 65 6d 6d 65  tin/PorterStemme
3b80: 72 2f 3e 70 6f 72 74 65 72 20 73 74 65 6d 6d 69  r/>porter stemmi
3b90: 6e 67 20 61 6c 67 6f 72 69 74 68 6d 3c 2f 61 3e  ng algorithm</a>
3ba0: 0a 74 6f 20 65 61 63 68 20 74 6f 6b 65 6e 20 62  .to each token b
3bb0: 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
3bc0: 20 69 74 20 74 6f 20 46 54 53 35 2e 20 54 68 69   it to FTS5. Thi
3bd0: 73 20 61 6c 6c 6f 77 73 20 73 65 61 72 63 68 20  s allows search 
3be0: 74 65 72 6d 73 20 6c 69 6b 65 0a 22 63 6f 72 72  terms like."corr
3bf0: 65 63 74 69 6f 6e 22 20 74 6f 20 6d 61 74 63 68  ection" to match
3c00: 20 73 69 6d 69 6c 61 72 20 77 6f 72 64 73 20 73   similar words s
3c10: 75 63 68 20 61 73 20 22 63 6f 72 72 65 63 74 65  uch as "correcte
3c20: 64 22 20 6f 72 20 22 63 6f 72 72 65 63 74 69 6e  d" or "correctin
3c30: 67 22 2e 20 54 68 65 0a 70 6f 72 74 65 72 20 73  g". The.porter s
3c40: 74 65 6d 6d 65 72 20 61 6c 67 6f 72 69 74 68 6d  temmer algorithm
3c50: 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
3c60: 20 75 73 65 20 77 69 74 68 20 45 6e 67 6c 69 73   use with Englis
3c70: 68 20 6c 61 6e 67 75 61 67 65 20 74 65 72 6d 73  h language terms
3c80: 20 0a 6f 6e 6c 79 20 2d 20 75 73 69 6e 67 20 69   .only - using i
3c90: 74 20 77 69 74 68 20 6f 74 68 65 72 20 6c 61 6e  t with other lan
3ca0: 67 75 61 67 65 73 20 6d 61 79 20 6f 72 20 6d 61  guages may or ma
3cb0: 79 20 6e 6f 74 20 69 6d 70 72 6f 76 65 20 73 65  y not improve se
3cc0: 61 72 63 68 20 75 74 69 6c 69 74 79 2e 0a 0a 3c  arch utility...<
3cd0: 70 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  p> By default, t
3ce0: 68 65 20 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69  he porter tokeni
3cf0: 7a 65 72 20 6f 70 65 72 61 74 65 73 20 61 73 20  zer operates as 
3d00: 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
3d10: 20 74 68 65 20 64 65 66 61 75 6c 74 0a 74 6f 6b   the default.tok
3d20: 65 6e 69 7a 65 72 20 28 75 6e 69 63 6f 64 65 36  enizer (unicode6
3d30: 31 29 2e 20 4f 72 2c 20 69 66 20 6f 6e 65 20 6f  1). Or, if one o
3d40: 72 20 6d 6f 72 65 20 65 78 74 72 61 20 61 72 67  r more extra arg
3d50: 75 6d 65 6e 74 73 20 61 72 65 20 61 64 64 65 64  uments are added
3d60: 20 74 6f 20 74 68 65 0a 22 74 6f 6b 65 6e 69 7a   to the."tokeniz
3d70: 65 22 20 6f 70 74 69 6f 6e 20 66 6f 6c 6c 6f 77  e" option follow
3d80: 69 6e 67 20 22 70 6f 72 74 65 72 22 2c 20 74 68  ing "porter", th
3d90: 65 79 20 61 72 65 20 74 72 65 61 74 65 64 20 61  ey are treated a
3da0: 73 20 61 20 73 70 65 63 69 66 69 63 61 74 69 6f  s a specificatio
3db0: 6e 20 66 6f 72 0a 74 68 65 20 75 6e 64 65 72 6c  n for.the underl
3dc0: 79 69 6e 67 20 74 6f 6b 65 6e 69 7a 65 72 20 74  ying tokenizer t
3dd0: 68 61 74 20 74 68 65 20 70 6f 72 74 65 72 20 73  hat the porter s
3de0: 74 65 6d 6d 65 72 20 75 73 65 73 2e 20 46 6f 72  temmer uses. For
3df0: 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65   example:..<code
3e00: 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54  block>.  <i>-- T
3e10: 77 6f 20 77 61 79 73 20 74 6f 20 63 72 65 61 74  wo ways to creat
3e20: 65 20 61 6e 20 46 54 53 35 20 74 61 62 6c 65 20  e an FTS5 table 
3e30: 74 68 61 74 20 75 73 65 73 20 74 68 65 20 70 6f  that uses the po
3e40: 72 74 65 72 20 74 6f 6b 65 6e 69 7a 65 72 20 74  rter tokenizer t
3e50: 6f 0a 20 20 2d 2d 20 73 74 65 6d 20 74 68 65 20  o.  -- stem the 
3e60: 6f 75 74 70 75 74 20 6f 66 20 74 68 65 20 64 65  output of the de
3e70: 66 61 75 6c 74 20 74 6f 6b 65 6e 69 7a 65 72 20  fault tokenizer 
3e80: 28 75 6e 69 63 6f 64 65 36 31 29 2e 20 3c 2f 69  (unicode61). </i
3e90: 3e 0a 20 20 43 52 45 41 54 45 20 56 49 52 54 55  >.  CREATE VIRTU
3ea0: 41 4c 20 54 41 42 4c 45 20 74 31 20 55 53 49 4e  AL TABLE t1 USIN
3eb0: 47 20 66 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69  G fts5(x, tokeni
3ec0: 7a 65 20 3d 20 70 6f 72 74 65 72 29 3b 20 0a 20  ze = porter); . 
3ed0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
3ee0: 54 41 42 4c 45 20 74 31 20 55 53 49 4e 47 20 66  TABLE t1 USING f
3ef0: 74 73 35 28 78 2c 20 74 6f 6b 65 6e 69 7a 65 20  ts5(x, tokenize 
3f00: 3d 20 27 70 6f 72 74 65 72 20 75 6e 69 63 6f 64  = 'porter unicod
3f10: 65 36 31 27 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20  e61');..  <i>-- 
3f20: 41 20 70 6f 72 74 65 72 20 74 6f 6b 65 6e 69 7a  A porter tokeniz
3f30: 65 72 20 75 73 65 64 20 74 6f 20 73 74 65 6d 20  er used to stem 
3f40: 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
3f50: 65 20 75 6e 69 63 6f 64 65 36 31 20 74 6f 6b 65  e unicode61 toke
3f60: 6e 69 7a 65 72 2c 0a 20 20 2d 2d 20 77 69 74 68  nizer,.  -- with
3f70: 20 64 69 61 63 72 69 74 69 63 73 20 72 65 6d 6f   diacritics remo
3f80: 76 65 64 20 62 65 66 6f 72 65 20 73 74 65 6d 6d  ved before stemm
3f90: 69 6e 67 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54  ing.</i>.  CREAT
3fa0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
3fb0: 74 31 20 55 53 49 4e 47 20 66 74 73 35 28 78 2c  t1 USING fts5(x,
3fc0: 20 74 6f 6b 65 6e 69 7a 65 20 3d 20 27 70 6f 72   tokenize = 'por
3fd0: 74 65 72 20 75 6e 69 63 6f 64 65 36 31 20 72 65  ter unicode61 re
3fe0: 6d 6f 76 65 5f 64 69 61 63 72 69 74 69 63 73 20  move_diacritics 
3ff0: 31 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  1');.</codeblock
4000: 3e 0a 0a 3c 68 31 20 74 61 67 73 3d 22 46 54 53  >..<h1 tags="FTS
4010: 35 20 63 6f 6e 74 65 6e 74 20 6f 70 74 69 6f 6e  5 content option
4020: 22 3e 45 78 74 65 72 6e 61 6c 20 43 6f 6e 74 65  ">External Conte
4030: 6e 74 20 61 6e 64 20 43 6f 6e 74 65 6e 74 6c 65  nt and Contentle
4040: 73 73 20 54 61 62 6c 65 73 3c 2f 68 31 3e 0a 0a  ss Tables</h1>..
4050: 3c 70 3e 0a 4e 6f 72 6d 61 6c 6c 79 2c 20 77 68  <p>.Normally, wh
4060: 65 6e 20 61 20 72 6f 77 20 69 73 20 69 6e 73 65  en a row is inse
4070: 72 74 65 64 20 69 6e 74 6f 20 61 6e 20 46 54 53  rted into an FTS
4080: 35 20 74 61 62 6c 65 2c 20 61 73 20 77 65 6c 6c  5 table, as well
4090: 20 61 73 20 74 68 65 20 76 61 72 69 6f 75 73 0a   as the various.
40a0: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
40b0: 65 6e 74 72 69 65 73 20 61 6e 64 20 6f 74 68 65  entries and othe
40c0: 72 20 64 61 74 61 20 61 20 63 6f 70 79 20 6f 66  r data a copy of
40d0: 20 74 68 65 20 72 6f 77 20 69 73 20 73 74 6f 72   the row is stor
40e0: 65 64 20 69 6e 20 61 20 70 72 69 76 61 74 65 0a  ed in a private.
40f0: 74 61 62 6c 65 20 6d 61 6e 61 67 65 64 20 62 79  table managed by
4100: 20 74 68 65 20 46 54 53 35 20 6d 6f 64 75 6c 65   the FTS5 module
4110: 2e 20 57 68 65 6e 20 63 6f 6c 75 6d 6e 20 76 61  . When column va
4120: 6c 75 65 73 20 61 72 65 20 72 65 71 75 65 73 74  lues are request
4130: 65 64 20 66 72 6f 6d 20 74 68 65 0a 46 54 53 35  ed from the.FTS5
4140: 20 74 61 62 6c 65 20 62 79 20 74 68 65 20 75 73   table by the us
4150: 65 72 20 6f 72 20 62 79 20 61 6e 20 61 75 78 69  er or by an auxi
4160: 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 20 69  liary function i
4170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
4180: 68 65 79 20 61 72 65 0a 72 65 61 64 20 66 72 6f  hey are.read fro
4190: 6d 20 74 68 69 73 20 70 72 69 76 61 74 65 20 74  m this private t
41a0: 61 62 6c 65 2e 20 54 68 65 20 22 63 6f 6e 74 65  able. The "conte
41b0: 6e 74 22 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62  nt" option may b
41c0: 65 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  e used to create
41d0: 20 61 6e 0a 46 54 53 35 20 74 61 62 6c 65 20 74   an.FTS5 table t
41e0: 68 61 74 20 73 74 6f 72 65 73 20 6f 6e 6c 79 20  hat stores only 
41f0: 46 54 53 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e  FTS full-text in
4200: 64 65 78 20 65 6e 74 72 69 65 73 2e 20 42 65 63  dex entries. Bec
4210: 61 75 73 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a  ause the column.
4220: 76 61 6c 75 65 73 20 74 68 65 6d 73 65 6c 76 65  values themselve
4230: 73 20 61 72 65 20 75 73 75 61 6c 6c 79 20 6d 75  s are usually mu
4240: 63 68 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  ch larger than t
4250: 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 66 75  he associated fu
4260: 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 0a 65 6e  ll-text index.en
4270: 74 72 69 65 73 2c 20 74 68 69 73 20 63 61 6e 20  tries, this can 
4280: 73 61 76 65 20 73 69 67 6e 69 66 69 63 61 6e 74  save significant
4290: 20 64 61 74 61 62 61 73 65 20 73 70 61 63 65 2e   database space.
42a0: 0a 0a 3c 70 3e 0a 54 68 65 72 65 20 61 72 65 20  ..<p>.There are 
42b0: 74 77 6f 20 77 61 79 73 20 74 6f 20 75 73 65 20  two ways to use 
42c0: 74 68 65 20 22 63 6f 6e 74 65 6e 74 22 20 6f 70  the "content" op
42d0: 74 69 6f 6e 3a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  tion:.<ul>.  <li
42e0: 3e 20 42 79 20 73 65 74 74 69 6e 67 20 69 74 20  > By setting it 
42f0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
4300: 6e 67 20 74 6f 20 63 72 65 61 74 65 20 61 20 63  ng to create a c
4310: 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54 53 35 20  ontentless FTS5 
4320: 74 61 62 6c 65 2e 20 49 6e 0a 20 20 20 20 20 20  table. In.      
4330: 20 74 68 69 73 20 63 61 73 65 20 46 54 53 35 20   this case FTS5 
4340: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
4350: 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6c 75 6d 6e   original column
4360: 20 76 61 6c 75 65 73 20 61 72 65 20 75 6e 61 76   values are unav
4370: 61 69 6c 61 62 6c 65 0a 20 20 20 20 20 20 20 74  ailable.       t
4380: 6f 20 69 74 20 77 68 65 6e 20 70 72 6f 63 65 73  o it when proces
4390: 73 69 6e 67 20 71 75 65 72 69 65 73 2e 20 46 75  sing queries. Fu
43a0: 6c 6c 2d 74 65 78 74 20 71 75 65 72 69 65 73 20  ll-text queries 
43b0: 61 6e 64 20 73 6f 6d 65 20 61 75 78 69 6c 69 61  and some auxilia
43c0: 72 79 0a 20 20 20 20 20 20 20 66 75 6e 63 74 69  ry.       functi
43d0: 6f 6e 73 20 63 61 6e 20 73 74 69 6c 6c 20 62 65  ons can still be
43e0: 20 75 73 65 64 2c 20 62 75 74 20 6e 6f 20 63 6f   used, but no co
43f0: 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 70 61 72  lumn values apar
4400: 74 20 66 72 6f 6d 20 74 68 65 20 72 6f 77 69 64  t from the rowid
4410: 0a 20 20 20 20 20 20 20 6d 61 79 20 62 65 20 72  .       may be r
4420: 65 61 64 20 66 72 6f 6d 20 74 68 65 20 74 61 62  ead from the tab
4430: 6c 65 2e 0a 0a 20 20 3c 6c 69 3e 20 42 79 20 73  le...  <li> By s
4440: 65 74 74 69 6e 67 20 69 74 20 74 6f 20 74 68 65  etting it to the
4450: 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62   name of a datab
4460: 61 73 65 20 6f 62 6a 65 63 74 20 28 74 61 62 6c  ase object (tabl
4470: 65 2c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e, virtual table
4480: 20 6f 72 0a 20 20 20 20 20 20 20 76 69 65 77 29   or.       view)
4490: 20 74 68 61 74 20 6d 61 79 20 62 65 20 71 75 65   that may be que
44a0: 72 69 65 64 20 62 79 20 46 54 53 35 20 61 74 20  ried by FTS5 at 
44b0: 61 6e 79 20 74 69 6d 65 20 74 6f 20 72 65 74 72  any time to retr
44c0: 69 65 76 65 20 74 68 65 20 63 6f 6c 75 6d 6e 0a  ieve the column.
44d0: 20 20 20 20 20 20 20 76 61 6c 75 65 73 2e 20 54         values. T
44e0: 68 69 73 20 69 73 20 6b 6e 6f 77 6e 20 61 73 20  his is known as 
44f0: 61 6e 20 22 65 78 74 65 72 6e 61 6c 20 63 6f 6e  an "external con
4500: 74 65 6e 74 22 20 74 61 62 6c 65 2e 20 49 6e 20  tent" table. In 
4510: 74 68 69 73 20 63 61 73 65 20 61 6c 6c 0a 20 20  this case all.  
4520: 20 20 20 20 20 46 54 53 35 20 66 75 6e 63 74 69       FTS5 functi
4530: 6f 6e 61 6c 69 74 79 20 6d 61 79 20 62 65 20 75  onality may be u
4540: 73 65 64 2c 20 62 75 74 20 69 74 20 69 73 20 74  sed, but it is t
4550: 68 65 20 72 65 73 70 6f 6e 73 69 62 69 6c 69 74  he responsibilit
4560: 79 20 6f 66 20 74 68 65 20 75 73 65 72 0a 20 20  y of the user.  
4570: 20 20 20 20 20 74 6f 20 65 6e 73 75 72 65 20 74       to ensure t
4580: 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  hat the contents
4590: 20 6f 66 20 74 68 65 20 66 75 6c 6c 2d 74 65 78   of the full-tex
45a0: 74 20 69 6e 64 65 78 20 61 72 65 20 63 6f 6e 73  t index are cons
45b0: 69 73 74 65 6e 74 20 77 69 74 68 0a 20 20 20 20  istent with.    
45c0: 20 20 20 74 68 65 20 6e 61 6d 65 64 20 64 61 74     the named dat
45d0: 61 62 61 73 65 20 6f 62 6a 65 63 74 2e 20 49 66  abase object. If
45e0: 20 74 68 65 79 20 61 72 65 20 6e 6f 74 2c 20 71   they are not, q
45f0: 75 65 72 79 20 72 65 73 75 6c 74 73 20 6d 61 79  uery results may
4600: 20 62 65 0a 20 20 20 20 20 20 20 75 6e 70 72 65   be.       unpre
4610: 64 69 63 74 61 62 6c 65 2e 20 20 0a 3c 2f 75 6c  dictable.  .</ul
4620: 3e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53  >..<h2 tags="FTS
4630: 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61  5 contentless ta
4640: 62 6c 65 73 22 3e 43 6f 6e 74 65 6e 74 6c 65 73  bles">Contentles
4650: 73 20 54 61 62 6c 65 73 3c 2f 68 32 3e 0a 0a 3c  s Tables</h2>..<
4660: 70 3e 20 41 20 63 6f 6e 74 65 6e 74 6c 65 73 73  p> A contentless
4670: 20 46 54 53 35 20 74 61 62 6c 65 20 69 73 20 63   FTS5 table is c
4680: 72 65 61 74 65 64 20 62 79 20 73 65 74 74 69 6e  reated by settin
4690: 67 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 22 20  g the "content" 
46a0: 6f 70 74 69 6f 6e 20 74 6f 0a 61 6e 20 65 6d 70  option to.an emp
46b0: 74 79 20 73 74 72 69 6e 67 2e 20 46 6f 72 20 65  ty string. For e
46c0: 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c  xample:..<codebl
46d0: 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20 56 49  ock>.  CREATE VI
46e0: 52 54 55 41 4c 20 54 41 42 4c 45 20 66 31 20 55  RTUAL TABLE f1 U
46f0: 53 49 4e 47 20 66 74 73 35 28 61 2c 20 62 2c 20  SING fts5(a, b, 
4700: 63 2c 20 63 6f 6e 74 65 6e 74 3d 27 27 29 3b 0a  c, content='');.
4710: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70  </codeblock>..<p
4720: 3e 20 43 6f 6e 74 65 6e 74 6c 65 73 73 20 46 54  > Contentless FT
4730: 53 35 20 74 61 62 6c 65 73 20 64 6f 20 6e 6f 74  S5 tables do not
4740: 20 73 75 70 70 6f 72 74 20 55 50 44 41 54 45 20   support UPDATE 
4750: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
4760: 65 6e 74 73 2c 20 6f 72 0a 49 4e 53 45 52 54 20  ents, or.INSERT 
4770: 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
4780: 64 6f 20 6e 6f 74 20 73 75 70 70 6c 79 20 61 20  do not supply a 
4790: 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 66  non-NULL value f
47a0: 6f 72 20 74 68 65 20 72 6f 77 69 64 20 66 69 65  or the rowid fie
47b0: 6c 64 2e 0a 52 6f 77 73 20 6d 61 79 20 62 65 20  ld..Rows may be 
47c0: 64 65 6c 65 74 65 64 20 66 72 6f 6d 20 61 20 63  deleted from a c
47d0: 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65  ontentless table
47e0: 20 75 73 69 6e 67 20 61 6e 20 5b 46 54 53 35 20   using an [FTS5 
47f0: 64 65 6c 65 74 65 20 63 6f 6d 6d 61 6e 64 5d 2e  delete command].
4800: 0a 0a 3c 70 3e 20 41 74 74 65 6d 70 74 69 6e 67  ..<p> Attempting
4810: 20 74 6f 20 72 65 61 64 20 61 6e 79 20 63 6f 6c   to read any col
4820: 75 6d 6e 20 76 61 6c 75 65 20 65 78 63 65 70 74  umn value except
4830: 20 74 68 65 20 72 6f 77 69 64 20 66 72 6f 6d 20   the rowid from 
4840: 61 20 63 6f 6e 74 65 6e 74 6c 65 73 73 0a 46 54  a contentless.FT
4850: 53 35 20 74 61 62 6c 65 20 72 65 74 75 72 6e 73  S5 table returns
4860: 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 20 76 61 6c   an SQL NULL val
4870: 75 65 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46  ue...<h2 tags="F
4880: 54 53 35 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e  TS5 external con
4890: 74 65 6e 74 20 74 61 62 6c 65 73 22 3e 45 78 74  tent tables">Ext
48a0: 65 72 6e 61 6c 20 43 6f 6e 74 65 6e 74 20 54 61  ernal Content Ta
48b0: 62 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 41  bles</h2>..<p> A
48c0: 6e 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  n external conte
48d0: 6e 74 20 46 54 53 35 20 74 61 62 6c 65 20 69 73  nt FTS5 table is
48e0: 20 63 72 65 61 74 65 64 20 62 79 20 73 65 74 74   created by sett
48f0: 69 6e 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  ing the content 
4900: 0a 6f 70 74 69 6f 6e 20 74 6f 20 74 68 65 20 6e  .option to the n
4910: 61 6d 65 20 6f 66 20 61 20 74 61 62 6c 65 2c 20  ame of a table, 
4920: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72  virtual table or
4930: 20 76 69 65 77 20 28 68 65 72 65 61 66 74 65 72   view (hereafter
4940: 20 74 68 65 20 22 63 6f 6e 74 65 6e 74 0a 74 61   the "content.ta
4950: 62 6c 65 22 29 20 77 69 74 68 69 6e 20 74 68 65  ble") within the
4960: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
4970: 57 68 65 6e 65 76 65 72 20 63 6f 6c 75 6d 6e 20  Whenever column 
4980: 76 61 6c 75 65 73 20 61 72 65 20 72 65 71 75 69  values are requi
4990: 72 65 64 20 62 79 0a 46 54 53 35 2c 20 69 74 20  red by.FTS5, it 
49a0: 71 75 65 72 69 65 73 20 74 68 65 20 63 6f 6e 74  queries the cont
49b0: 65 6e 74 20 74 61 62 6c 65 20 61 73 20 66 6f 6c  ent table as fol
49c0: 6c 6f 77 73 2c 20 77 69 74 68 20 74 68 65 20 72  lows, with the r
49d0: 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 0a  owid of the row.
49e0: 66 6f 72 20 77 68 69 63 68 20 76 61 6c 75 65 73  for which values
49f0: 20 61 72 65 20 72 65 71 75 69 72 65 64 20 62 6f   are required bo
4a00: 75 6e 64 20 74 6f 20 74 68 65 20 53 51 4c 20 76  und to the SQL v
4a10: 61 72 69 61 62 6c 65 3a 0a 0a 3c 63 6f 64 65 62  ariable:..<codeb
4a20: 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20 2a  lock>.  SELECT *
4a30: 20 46 52 4f 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e   FROM &lt;conten
4a40: 74 26 67 74 3b 20 57 48 45 52 45 20 26 6c 74 3b  t&gt; WHERE &lt;
4a50: 63 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74  content_rowid&gt
4a60: 3b 20 3d 20 3f 3b 0a 3c 2f 63 6f 64 65 62 6c 6f  ; = ?;.</codeblo
4a70: 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 20 74 68 65 20  ck>..<p> In the 
4a80: 61 62 6f 76 65 2c 20 26 6c 74 3b 63 6f 6e 74 65  above, &lt;conte
4a90: 6e 74 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  nt&gt; is replac
4aa0: 65 64 20 62 79 20 74 68 65 20 6e 61 6d 65 20 6f  ed by the name o
4ab0: 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 74 61  f the content ta
4ac0: 62 6c 65 2e 0a 42 79 20 64 65 66 61 75 6c 74 2c  ble..By default,
4ad0: 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 5f 72 6f 77   &lt;content_row
4ae0: 69 64 26 67 74 3b 20 69 73 20 72 65 70 6c 61 63  id&gt; is replac
4af0: 65 64 20 62 79 20 74 68 65 20 6c 69 74 65 72 61  ed by the litera
4b00: 6c 20 74 65 78 74 20 22 72 6f 77 69 64 22 2e 20  l text "rowid". 
4b10: 4f 72 2c 0a 69 66 20 74 68 65 20 22 63 6f 6e 74  Or,.if the "cont
4b20: 65 6e 74 5f 72 6f 77 69 64 22 20 6f 70 74 69 6f  ent_rowid" optio
4b30: 6e 20 69 73 20 73 65 74 20 77 69 74 68 69 6e 20  n is set within 
4b40: 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55  the CREATE VIRTU
4b50: 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  AL TABLE stateme
4b60: 6e 74 2c 0a 62 79 20 74 68 65 20 76 61 6c 75 65  nt,.by the value
4b70: 20 6f 66 20 74 68 61 74 20 6f 70 74 69 6f 6e 2e   of that option.
4b80: 0a 0a 3c 70 3e 20 54 68 65 20 22 2a 22 20 69 6e  ..<p> The "*" in
4b90: 20 74 68 65 20 61 62 6f 76 65 20 71 75 65 72 79   the above query
4ba0: 20 6d 75 73 74 20 65 78 70 61 6e 64 20 74 6f 20   must expand to 
4bb0: 61 20 73 65 74 20 6f 66 20 63 6f 6c 75 6d 6e 73  a set of columns
4bc0: 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 0a 74   consisting of.t
4bd0: 68 65 20 26 6c 74 3b 63 6f 6c 75 6d 6e 5f 72 6f  he &lt;column_ro
4be0: 77 69 64 26 67 74 3b 20 63 6f 6c 75 6d 6e 20 66  wid&gt; column f
4bf0: 6f 6c 6c 6f 77 65 64 20 62 79 20 65 61 63 68 20  ollowed by each 
4c00: 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 2c 20  indexed column, 
4c10: 69 6e 20 74 68 65 20 73 61 6d 65 0a 6f 72 64 65  in the same.orde
4c20: 72 20 61 73 20 74 68 65 79 20 61 72 65 20 70 72  r as they are pr
4c30: 65 73 65 6e 74 20 69 6e 20 74 68 65 20 65 78 74  esent in the ext
4c40: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 66 74  ernal content ft
4c50: 73 35 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 54  s5 table...<p> T
4c60: 68 65 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  he content table
4c70: 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 71 75 65   may also be que
4c80: 72 69 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ried as follows:
4c90: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
4ca0: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 26 6c  SELECT * FROM &l
4cb0: 74 3b 63 6f 6e 74 65 6e 74 26 67 74 3b 20 4f 52  t;content&gt; OR
4cc0: 44 45 52 20 42 59 20 26 6c 74 3b 63 6f 6e 74 65  DER BY &lt;conte
4cd0: 6e 74 5f 72 6f 77 69 64 26 67 74 3b 20 41 53 43  nt_rowid&gt; ASC
4ce0: 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  ;.  SELECT * FRO
4cf0: 4d 20 26 6c 74 3b 63 6f 6e 74 65 6e 74 26 67 74  M &lt;content&gt
4d00: 3b 20 4f 52 44 45 52 20 42 59 20 26 6c 74 3b 63  ; ORDER BY &lt;c
4d10: 6f 6e 74 65 6e 74 5f 72 6f 77 69 64 26 67 74 3b  ontent_rowid&gt;
4d20: 20 44 45 53 43 3b 0a 3c 2f 63 6f 64 65 62 6c 6f   DESC;.</codeblo
4d30: 63 6b 3e 0a 0a 3c 70 3e 20 49 74 20 69 73 20 73  ck>..<p> It is s
4d40: 74 69 6c 6c 20 74 68 65 20 72 65 73 70 6f 6e 73  till the respons
4d50: 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20 75  ibility of the u
4d60: 73 65 72 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ser to ensure th
4d70: 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  at the contents 
4d80: 6f 66 0a 61 6e 20 65 78 74 65 72 6e 61 6c 20 63  of.an external c
4d90: 6f 6e 74 65 6e 74 20 46 54 53 35 20 74 61 62 6c  ontent FTS5 tabl
4da0: 65 20 61 72 65 20 6b 65 70 74 20 75 70 20 74 6f  e are kept up to
4db0: 20 64 61 74 65 20 77 69 74 68 20 74 68 65 20 63   date with the c
4dc0: 6f 6e 74 65 6e 74 20 74 61 62 6c 65 2e 20 0a 4f  ontent table. .O
4dd0: 6e 65 20 77 61 79 20 74 6f 20 64 6f 20 74 68 69  ne way to do thi
4de0: 73 20 69 73 20 77 69 74 68 20 74 72 69 67 67 65  s is with trigge
4df0: 72 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a  rs. For example:
4e00: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20  ..<codeblock>.  
4e10: 3c 69 3e 2d 2d 20 43 72 65 61 74 65 20 61 20 74  <i>-- Create a t
4e20: 61 62 6c 65 2e 20 41 6e 64 20 61 6e 20 65 78 74  able. And an ext
4e30: 65 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 66 74  ernal content ft
4e40: 73 35 20 74 61 62 6c 65 20 74 6f 20 69 6e 64 65  s5 table to inde
4e50: 78 20 69 74 2e 3c 2f 69 3e 0a 20 20 43 52 45 41  x it.</i>.  CREA
4e60: 54 45 20 54 41 42 4c 45 20 74 62 6c 28 61 20 49  TE TABLE tbl(a I
4e70: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
4e80: 45 59 2c 20 62 2c 20 63 29 3b 0a 20 20 43 52 45  EY, b, c);.  CRE
4e90: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
4ea0: 45 20 66 74 73 5f 69 64 78 20 55 53 49 4e 47 20  E fts_idx USING 
4eb0: 66 74 73 35 28 62 2c 20 63 2c 20 63 6f 6e 74 65  fts5(b, c, conte
4ec0: 6e 74 3d 27 74 62 6c 27 2c 20 63 6f 6e 74 65 6e  nt='tbl', conten
4ed0: 74 5f 72 6f 77 69 64 3d 27 61 27 29 3b 0a 0a 20  t_rowid='a');.. 
4ee0: 20 3c 69 3e 2d 2d 20 54 72 69 67 67 65 72 73 20   <i>-- Triggers 
4ef0: 74 6f 20 6b 65 65 70 20 74 68 65 20 46 54 53 20  to keep the FTS 
4f00: 69 6e 64 65 78 20 75 70 20 74 6f 20 64 61 74 65  index up to date
4f10: 2e 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 54  .</i>.  CREATE T
4f20: 52 49 47 47 45 52 20 74 62 6c 5f 61 69 20 41 46  RIGGER tbl_ai AF
4f30: 54 45 52 20 49 4e 53 45 52 54 20 4f 4e 20 74 62  TER INSERT ON tb
4f40: 6c 20 42 45 47 49 4e 0a 20 20 20 20 49 4e 53 45  l BEGIN.    INSE
4f50: 52 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78 28  RT INTO fts_idx(
4f60: 72 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41 4c  rowid, b, c) VAL
4f70: 55 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77 2e  UES (new.a, new.
4f80: 62 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e 44  b, new.c);.  END
4f90: 3b 0a 20 20 43 52 45 41 54 45 20 54 52 49 47 47  ;.  CREATE TRIGG
4fa0: 45 52 20 74 62 6c 5f 61 64 20 41 46 54 45 52 20  ER tbl_ad AFTER 
4fb0: 44 45 4c 45 54 45 20 4f 4e 20 74 62 6c 20 42 45  DELETE ON tbl BE
4fc0: 47 49 4e 0a 20 20 20 20 49 4e 53 45 52 54 20 49  GIN.    INSERT I
4fd0: 4e 54 4f 20 66 74 73 5f 69 64 78 28 66 74 73 5f  NTO fts_idx(fts_
4fe0: 69 64 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20 63  idx, rowid, b, c
4ff0: 29 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74 65  ) VALUES('delete
5000: 27 2c 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62 2c  ', old.a, old.b,
5010: 20 6f 6c 64 2e 63 29 3b 0a 20 20 45 4e 44 3b 0a   old.c);.  END;.
5020: 20 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52    CREATE TRIGGER
5030: 20 74 62 6c 5f 61 75 20 41 46 54 45 52 20 55 50   tbl_au AFTER UP
5040: 44 41 54 45 20 4f 4e 20 74 62 6c 20 42 45 47 49  DATE ON tbl BEGI
5050: 4e 0a 20 20 20 20 49 4e 53 45 52 54 20 49 4e 54  N.    INSERT INT
5060: 4f 20 66 74 73 5f 69 64 78 28 66 74 73 5f 69 64  O fts_idx(fts_id
5070: 78 2c 20 72 6f 77 69 64 2c 20 62 2c 20 63 29 20  x, rowid, b, c) 
5080: 56 41 4c 55 45 53 28 27 64 65 6c 65 74 65 27 2c  VALUES('delete',
5090: 20 6f 6c 64 2e 61 2c 20 6f 6c 64 2e 62 2c 20 6f   old.a, old.b, o
50a0: 6c 64 2e 63 29 3b 0a 20 20 20 20 49 4e 53 45 52  ld.c);.    INSER
50b0: 54 20 49 4e 54 4f 20 66 74 73 5f 69 64 78 28 72  T INTO fts_idx(r
50c0: 6f 77 69 64 2c 20 62 2c 20 63 29 20 56 41 4c 55  owid, b, c) VALU
50d0: 45 53 20 28 6e 65 77 2e 61 2c 20 6e 65 77 2e 62  ES (new.a, new.b
50e0: 2c 20 6e 65 77 2e 63 29 3b 0a 20 20 45 4e 44 3b  , new.c);.  END;
50f0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 0a  .</codeblock>...
5100: 3c 68 31 3e 20 41 75 78 69 6c 69 61 72 79 20 46  <h1> Auxiliary F
5110: 75 6e 63 74 69 6f 6e 73 20 3c 2f 68 31 3e 0a 0a  unctions </h1>..
5120: 3c 68 32 3e 42 75 69 6c 74 2d 69 6e 20 41 75 78  <h2>Built-in Aux
5130: 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f 6e 73  iliary Functions
5140: 3c 2f 68 32 3e 0a 0a 3c 68 33 3e 54 68 65 20 62  </h2>..<h3>The b
5150: 6d 32 35 28 29 20 66 75 6e 63 74 69 6f 6e 3c 2f  m25() function</
5160: 68 33 3e 0a 0a 3c 70 3e 20 54 68 65 20 62 75 69  h3>..<p> The bui
5170: 6c 74 2d 69 6e 20 61 75 78 69 6c 69 61 72 79 20  lt-in auxiliary 
5180: 66 75 6e 63 74 69 6f 6e 20 62 6d 32 35 28 29 20  function bm25() 
5190: 72 65 74 75 72 6e 73 20 61 20 72 65 61 6c 20 76  returns a real v
51a0: 61 6c 75 65 20 69 6e 64 69 63 61 74 69 6e 67 0a  alue indicating.
51b0: 68 6f 77 20 77 65 6c 6c 20 74 68 65 20 63 75 72  how well the cur
51c0: 72 65 6e 74 20 72 6f 77 20 6d 61 74 63 68 65 73  rent row matches
51d0: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 71   the full-text q
51e0: 75 65 72 79 2e 20 54 68 65 20 62 65 74 74 65 72  uery. The better
51f0: 20 74 68 65 20 6d 61 74 63 68 2c 0a 74 68 65 20   the match,.the 
5200: 6c 61 72 67 65 72 20 74 68 65 20 76 61 6c 75 65  larger the value
5210: 20 72 65 74 75 72 6e 65 64 2e 20 41 20 71 75 65   returned. A que
5220: 72 79 20 73 75 63 68 20 61 73 20 74 68 65 20 66  ry such as the f
5230: 6f 6c 6c 6f 77 69 6e 67 20 6d 61 79 20 62 65 20  ollowing may be 
5240: 75 73 65 64 0a 74 6f 20 72 65 74 75 72 6e 20 6d  used.to return m
5250: 61 74 63 68 65 73 20 69 6e 20 6f 72 64 65 72 20  atches in order 
5260: 66 72 6f 6d 20 62 65 73 74 20 74 6f 20 77 6f 72  from best to wor
5270: 73 74 20 6d 61 74 63 68 3a 0a 0a 3c 63 6f 64 65  st match:..<code
5280: 62 6c 6f 63 6b 3e 0a 20 20 53 45 4c 45 43 54 20  block>.  SELECT 
5290: 2a 20 46 52 4f 4d 20 66 74 73 20 57 48 45 52 45  * FROM fts WHERE
52a0: 20 66 74 73 20 4d 41 54 43 48 20 3f 20 4f 52 44   fts MATCH ? ORD
52b0: 45 52 20 42 59 20 62 6d 32 35 28 66 74 73 29 20  ER BY bm25(fts) 
52c0: 44 45 53 43 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  DESC.</codeblock
52d0: 3e 0a 0a 3c 70 3e 20 49 6e 20 6f 72 64 65 72 20  >..<p> In order 
52e0: 74 6f 20 63 61 6c 63 75 6c 61 74 65 20 61 20 64  to calculate a d
52f0: 6f 63 75 6d 65 6e 74 73 20 73 63 6f 72 65 2c 20  ocuments score, 
5300: 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 71 75  the full-text qu
5310: 65 72 79 20 69 73 20 73 65 70 61 72 61 74 65 64  ery is separated
5320: 0a 20 20 20 20 69 6e 74 6f 20 69 74 73 20 63 6f  .    into its co
5330: 6d 70 6f 6e 65 6e 74 20 70 68 72 61 73 65 73 2e  mponent phrases.
5340: 20 54 68 65 20 62 6d 32 35 20 73 63 6f 72 65 20   The bm25 score 
5350: 66 6f 72 20 64 6f 63 75 6d 65 6e 74 20 3c 69 3e  for document <i>
5360: 44 3c 2f 69 3e 20 61 6e 64 20 0a 20 20 20 20 71  D</i> and .    q
5370: 75 65 72 79 20 3c 69 3e 51 3c 2f 69 3e 20 69 73  uery <i>Q</i> is
5380: 20 74 68 65 6e 20 63 61 6c 63 75 6c 61 74 65 64   then calculated
5390: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 70   as follows:..<p
53a0: 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d 61 67  > <img src="imag
53b0: 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c 61 31  es/fts5_formula1
53c0: 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77 69 64  .png" style="wid
53d0: 74 68 3a 35 35 65 78 3b 6d 61 72 67 69 6e 2d 6c  th:55ex;margin-l
53e0: 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e 20 49  eft:5ex">..<p> I
53f0: 6e 20 74 68 65 20 61 62 6f 76 65 2c 20 3c 69 3e  n the above, <i>
5400: 6e 50 68 72 61 73 65 3c 2f 69 3e 20 69 73 20 74  nPhrase</i> is t
5410: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 68 72  he number of phr
5420: 61 73 65 73 20 69 6e 20 74 68 65 20 71 75 65 72  ases in the quer
5430: 79 2e 0a 20 20 20 20 3c 69 3e 7c 44 7c 3c 2f 69  y..    <i>|D|</i
5440: 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  > is the number 
5450: 6f 66 20 74 6f 6b 65 6e 73 20 69 6e 20 74 68 65  of tokens in the
5460: 20 63 75 72 72 65 6e 74 20 64 6f 63 75 6d 65 6e   current documen
5470: 74 2c 20 61 6e 64 0a 20 20 20 20 3c 69 3e 61 76  t, and.    <i>av
5480: 67 64 6c 3c 2f 69 3e 20 69 73 20 74 68 65 20 61  gdl</i> is the a
5490: 76 65 72 61 67 65 20 6e 75 6d 62 65 72 20 6f 66  verage number of
54a0: 20 74 6f 6b 65 6e 73 20 69 6e 20 61 6c 6c 20 64   tokens in all d
54b0: 6f 63 75 6d 65 6e 74 73 20 77 69 74 68 69 6e 20  ocuments within 
54c0: 74 68 65 0a 20 20 20 20 46 54 53 35 20 74 61 62  the.    FTS5 tab
54d0: 6c 65 2e 20 20 3c 69 3e 6b 3c 73 75 62 3e 31 3c  le.  <i>k<sub>1<
54e0: 2f 73 75 62 3e 3c 2f 69 3e 20 61 6e 64 20 3c 69  /sub></i> and <i
54f0: 3e 62 3c 2f 69 3e 20 61 72 65 20 62 6f 74 68 20  >b</i> are both 
5500: 63 6f 6e 73 74 61 6e 74 73 2c 0a 20 20 20 20 68  constants,.    h
5510: 61 72 64 2d 63 6f 64 65 64 20 61 74 20 31 2e 32  ard-coded at 1.2
5520: 20 61 6e 64 20 30 2e 37 35 20 72 65 73 70 65 63   and 0.75 respec
5530: 74 69 76 65 6c 79 2e 0a 0a 3c 70 3e 20 3c 69 3e  tively...<p> <i>
5540: 49 44 46 28 71 3c 73 75 62 3e 69 3c 2f 73 75 62  IDF(q<sub>i</sub
5550: 3e 29 3c 2f 69 3e 20 69 73 20 74 68 65 20 69 6e  >)</i> is the in
5560: 76 65 72 73 65 2d 64 6f 63 75 6d 65 6e 74 2d 66  verse-document-f
5570: 72 65 71 75 65 6e 63 79 20 6f 66 20 71 75 65 72  requency of quer
5580: 79 20 0a 20 20 20 20 70 68 72 61 73 65 20 3c 69  y .    phrase <i
5590: 3e 69 3c 2f 69 3e 2e 20 49 74 20 69 73 20 63 61  >i</i>. It is ca
55a0: 6c 63 75 6c 61 74 65 64 20 61 73 20 66 6f 6c 6c  lculated as foll
55b0: 6f 77 73 2c 20 77 68 65 72 65 20 3c 69 3e 4e 3c  ows, where <i>N<
55c0: 2f 69 3e 20 69 73 20 74 68 65 20 74 6f 74 61 6c  /i> is the total
55d0: 0a 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72  .    number of r
55e0: 6f 77 73 20 69 6e 20 74 68 65 20 46 54 53 35 20  ows in the FTS5 
55f0: 74 61 62 6c 65 20 61 6e 64 20 3c 69 3e 6e 28 71  table and <i>n(q
5600: 3c 73 75 62 3e 69 3c 2f 73 75 62 3e 29 3c 2f 69  <sub>i</sub>)</i
5610: 3e 20 69 73 20 74 68 65 20 74 6f 74 61 6c 0a 20  > is the total. 
5620: 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77     number of row
5630: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
5640: 74 20 6c 65 61 73 74 20 6f 6e 65 20 69 6e 73 74  t least one inst
5650: 61 6e 63 65 20 6f 66 20 70 68 72 61 73 65 20 3c  ance of phrase <
5660: 69 3e 69 3c 2f 69 3e 3a 0a 0a 3c 70 3e 20 3c 69  i>i</i>:..<p> <i
5670: 6d 67 20 73 72 63 3d 22 69 6d 61 67 65 73 2f 66  mg src="images/f
5680: 74 73 35 5f 66 6f 72 6d 75 6c 61 32 2e 70 6e 67  ts5_formula2.png
5690: 22 20 73 74 79 6c 65 3d 22 77 69 64 74 68 3a 35  " style="width:5
56a0: 35 65 78 3b 6d 61 72 67 69 6e 2d 6c 65 66 74 3a  5ex;margin-left:
56b0: 35 65 78 22 3e 0a 0a 3c 70 3e 20 46 69 6e 61 6c  5ex">..<p> Final
56c0: 6c 79 2c 20 3c 69 3e 66 28 71 3c 73 75 62 3e 69  ly, <i>f(q<sub>i
56d0: 3c 2f 73 75 62 3e 2c 44 29 3c 2f 69 3e 20 69 73  </sub>,D)</i> is
56e0: 20 74 68 65 20 70 68 72 61 73 65 20 66 72 65 71   the phrase freq
56f0: 75 65 6e 63 79 20 6f 66 20 70 68 72 61 73 65 20  uency of phrase 
5700: 0a 3c 69 3e 69 3c 2f 69 3e 2e 20 42 79 20 64 65  .<i>i</i>. By de
5710: 66 61 75 6c 74 2c 20 74 68 69 73 20 69 73 20 73  fault, this is s
5720: 69 6d 70 6c 79 20 74 68 65 20 6e 75 6d 62 65 72  imply the number
5730: 20 6f 66 20 6f 63 63 75 72 72 65 6e 63 65 73 20   of occurrences 
5740: 6f 66 20 74 68 65 20 70 68 72 61 73 65 0a 77 69  of the phrase.wi
5750: 74 68 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  thin the current
5760: 20 72 6f 77 2e 20 48 6f 77 65 76 65 72 2c 20 62   row. However, b
5770: 79 20 70 61 73 73 69 6e 67 20 65 78 74 72 61 20  y passing extra 
5780: 72 65 61 6c 20 76 61 6c 75 65 20 61 72 67 75 6d  real value argum
5790: 65 6e 74 73 20 74 6f 20 0a 74 68 65 20 62 6d 32  ents to .the bm2
57a0: 35 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  5() SQL function
57b0: 2c 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f 66  , each column of
57c0: 20 74 68 65 20 74 61 62 6c 65 20 6d 61 79 20 62   the table may b
57d0: 65 20 61 73 73 69 67 6e 65 64 20 61 20 64 69 66  e assigned a dif
57e0: 66 65 72 65 6e 74 0a 77 65 69 67 68 74 20 61 6e  ferent.weight an
57f0: 64 20 74 68 65 20 70 68 72 61 73 65 20 66 72 65  d the phrase fre
5800: 71 75 65 6e 63 79 20 63 61 6c 63 75 6c 61 74 65  quency calculate
5810: 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c  d as follows:..<
5820: 70 3e 20 3c 69 6d 67 20 73 72 63 3d 22 69 6d 61  p> <img src="ima
5830: 67 65 73 2f 66 74 73 35 5f 66 6f 72 6d 75 6c 61  ges/fts5_formula
5840: 33 2e 70 6e 67 22 20 73 74 79 6c 65 3d 22 77 69  3.png" style="wi
5850: 64 74 68 3a 35 35 65 78 3b 6d 61 72 67 69 6e 2d  dth:55ex;margin-
5860: 6c 65 66 74 3a 35 65 78 22 3e 0a 0a 3c 70 3e 20  left:5ex">..<p> 
5870: 77 68 65 72 65 20 3c 69 3e 77 3c 73 75 62 3e 63  where <i>w<sub>c
5880: 3c 2f 73 75 62 3e 3c 2f 69 3e 20 69 73 20 74 68  </sub></i> is th
5890: 65 20 77 65 69 67 68 74 20 61 73 73 69 67 6e 65  e weight assigne
58a0: 64 20 74 6f 20 63 6f 6c 75 6d 6e 20 3c 69 3e 63  d to column <i>c
58b0: 3c 2f 69 3e 20 61 6e 64 0a 3c 69 3e 6e 28 71 3c  </i> and.<i>n(q<
58c0: 73 75 62 3e 69 3c 2f 73 75 62 3e 2c 63 29 3c 2f  sub>i</sub>,c)</
58d0: 69 3e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  i> is the number
58e0: 20 6f 66 20 6f 63 63 75 72 72 65 6e 63 65 73 20   of occurrences 
58f0: 6f 66 20 70 68 72 61 73 65 20 3c 69 3e 69 3c 2f  of phrase <i>i</
5900: 69 3e 20 69 6e 0a 63 6f 6c 75 6d 6e 20 3c 69 3e  i> in.column <i>
5910: 63 3c 2f 69 3e 20 6f 66 20 74 68 65 20 63 75 72  c</i> of the cur
5920: 72 65 6e 74 20 72 6f 77 2e 20 54 68 65 20 66 69  rent row. The fi
5930: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
5940: 73 65 64 20 74 6f 20 62 6d 32 35 28 29 0a 66 6f  sed to bm25().fo
5950: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 74 61 62 6c  llowing the tabl
5960: 65 20 6e 61 6d 65 20 69 73 20 74 68 65 20 77 65  e name is the we
5970: 69 67 68 74 20 61 73 73 69 67 6e 65 64 20 74 6f  ight assigned to
5980: 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   the leftmost co
5990: 6c 75 6d 6e 20 6f 66 0a 74 68 65 20 46 54 53 35  lumn of.the FTS5
59a0: 20 74 61 62 6c 65 2e 20 54 68 65 20 73 65 63 6f   table. The seco
59b0: 6e 64 20 69 73 20 74 68 65 20 77 65 69 67 68 74  nd is the weight
59c0: 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65   assigned to the
59d0: 20 73 65 63 6f 6e 64 20 6c 65 66 74 6d 6f 73 74   second leftmost
59e0: 0a 63 6f 6c 75 6d 6e 2c 20 61 6e 64 20 73 6f 20  .column, and so 
59f0: 6f 6e 2e 20 49 66 20 74 68 65 72 65 20 61 72 65  on. If there are
5a00: 20 6e 6f 74 20 65 6e 6f 75 67 68 20 61 72 67 75   not enough argu
5a10: 6d 65 6e 74 73 20 66 6f 72 20 61 6c 6c 20 74 61  ments for all ta
5a20: 62 6c 65 20 63 6f 6c 75 6d 6e 73 2c 0a 72 65 6d  ble columns,.rem
5a30: 61 69 6e 69 6e 67 20 63 6f 6c 75 6d 6e 73 20 61  aining columns a
5a40: 72 65 20 61 73 73 69 67 6e 65 64 20 61 20 77 65  re assigned a we
5a50: 69 67 68 74 20 6f 66 20 31 2e 30 2e 20 49 66 20  ight of 1.0. If 
5a60: 74 68 65 72 65 20 61 72 65 20 74 6f 6f 20 6d 61  there are too ma
5a70: 6e 79 20 0a 74 72 61 69 6c 69 6e 67 20 61 72 67  ny .trailing arg
5a80: 75 6d 65 6e 74 73 2c 20 74 68 65 20 65 78 74 72  uments, the extr
5a90: 61 73 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 20  as are ignored. 
5aa0: 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63  For example:..<c
5ab0: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d  odeblock>.  <i>-
5ac0: 2d 20 41 73 73 75 6d 69 6e 67 20 74 68 65 20 66  - Assuming the f
5ad0: 6f 6c 6c 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a  ollowing schema:
5ae0: 3c 2f 69 3e 0a 20 20 43 52 45 41 54 45 20 56 49  </i>.  CREATE VI
5af0: 52 54 55 41 4c 20 54 41 42 4c 45 20 65 6d 61 69  RTUAL TABLE emai
5b00: 6c 20 55 53 49 4e 47 20 66 74 73 35 28 73 65 6e  l USING fts5(sen
5b10: 64 65 72 2c 20 74 69 74 6c 65 2c 20 62 6f 64 79  der, title, body
5b20: 29 3b 0a 0a 20 20 3c 69 3e 2d 2d 20 52 65 74 75  );..  <i>-- Retu
5b30: 72 6e 20 72 65 73 75 6c 74 73 20 69 6e 20 62 6d  rn results in bm
5b40: 32 35 20 6f 72 64 65 72 2c 20 77 69 74 68 20 65  25 order, with e
5b50: 61 63 68 20 70 68 72 61 73 65 20 68 69 74 20 69  ach phrase hit i
5b60: 6e 20 74 68 65 20 22 73 65 6e 64 65 72 22 3c 2f  n the "sender"</
5b70: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 63 6f 6c 75 6d  i>.  <i>-- colum
5b80: 6e 20 63 6f 6e 73 69 64 65 72 65 64 20 74 68 65  n considered the
5b90: 20 65 71 75 61 6c 20 6f 66 20 31 30 20 68 69 74   equal of 10 hit
5ba0: 73 20 69 6e 20 74 68 65 20 22 62 6f 64 79 22 20  s in the "body" 
5bb0: 63 6f 6c 75 6d 6e 2c 20 61 6e 64 3c 2f 69 3e 0a  column, and</i>.
5bc0: 20 20 3c 69 3e 2d 2d 20 65 61 63 68 20 68 69 74    <i>-- each hit
5bd0: 20 69 6e 20 74 68 65 20 22 74 69 74 6c 65 22 20   in the "title" 
5be0: 63 6f 6c 75 6d 6e 20 63 6f 6e 73 69 64 65 72 65  column considere
5bf0: 64 20 61 73 20 76 61 6c 75 61 62 6c 65 20 61 73  d as valuable as
5c00: 20 35 20 68 69 74 73 20 69 6e 3c 2f 69 3e 0a 20   5 hits in</i>. 
5c10: 20 3c 69 3e 2d 2d 20 74 68 65 20 22 62 6f 64 79   <i>-- the "body
5c20: 22 20 63 6f 6c 75 6d 6e 2e 3c 2f 69 3e 0a 20 20  " column.</i>.  
5c30: 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 65 6d  SELECT * FROM em
5c40: 61 69 6c 20 57 48 45 52 45 20 65 6d 61 69 6c 20  ail WHERE email 
5c50: 4d 41 54 43 48 20 3f 20 4f 52 44 45 52 20 42 59  MATCH ? ORDER BY
5c60: 20 62 6d 32 35 28 65 6d 61 69 6c 2c 20 31 30 2e   bm25(email, 10.
5c70: 30 2c 20 35 2e 30 29 20 44 45 53 43 3b 0a 3c 2f  0, 5.0) DESC;.</
5c80: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 52  codeblock>..<p>R
5c90: 65 66 65 72 20 74 6f 20 77 69 6b 69 70 65 64 69  efer to wikipedi
5ca0: 61 20 66 6f 72 20 0a 3c 61 20 68 72 65 66 3d 22  a for .<a href="
5cb0: 68 74 74 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65  http://en.wikipe
5cc0: 64 69 61 2e 6f 72 67 2f 77 69 6b 69 2f 4f 6b 61  dia.org/wiki/Oka
5cd0: 70 69 5f 42 4d 32 35 22 3e 6d 6f 72 65 20 69 6e  pi_BM25">more in
5ce0: 66 6f 72 6d 61 74 69 6f 6e 20 72 65 67 61 72 64  formation regard
5cf0: 69 6e 67 0a 42 4d 32 35 3c 2f 61 3e 20 61 6e 64  ing.BM25</a> and
5d00: 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 0a   its variants...
5d10: 3c 68 33 3e 54 68 65 20 68 69 67 68 6c 69 67 68  <h3>The highligh
5d20: 74 28 29 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 33  t() function</h3
5d30: 3e 0a 0a 3c 70 3e 20 54 68 65 20 68 69 67 68 6c  >..<p> The highl
5d40: 69 67 68 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  ight() function 
5d50: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
5d60: 66 20 74 68 65 20 74 65 78 74 20 66 72 6f 6d 20  f the text from 
5d70: 61 20 73 70 65 63 69 66 69 65 64 20 0a 63 6f 6c  a specified .col
5d80: 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
5d90: 6e 74 20 72 6f 77 20 77 69 74 68 20 65 78 74 72  nt row with extr
5da0: 61 20 6d 61 72 6b 75 70 20 74 65 78 74 20 69 6e  a markup text in
5db0: 73 65 72 74 65 64 20 74 6f 20 6d 61 72 6b 20 74  serted to mark t
5dc0: 68 65 20 73 74 61 72 74 20 0a 61 6e 64 20 65 6e  he start .and en
5dd0: 64 20 6f 66 20 70 68 72 61 73 65 20 6d 61 74 63  d of phrase matc
5de0: 68 65 73 2e 20 0a 0a 3c 70 3e 54 68 65 20 68 69  hes. ..<p>The hi
5df0: 67 68 6c 69 67 68 74 28 29 20 6d 75 73 74 20 62  ghlight() must b
5e00: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  e invoked with e
5e10: 78 61 63 74 6c 79 20 74 68 72 65 65 20 61 72 67  xactly three arg
5e20: 75 6d 65 6e 74 73 20 66 6f 6c 6c 6f 77 69 6e 67  uments following
5e30: 20 0a 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65   .the table name
5e40: 2e 20 54 6f 20 62 65 20 69 6e 74 65 72 70 72 65  . To be interpre
5e50: 74 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ted as follows:.
5e60: 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 41 6e 20  .<ol>.  <li> An 
5e70: 69 6e 74 65 67 65 72 20 69 6e 64 69 63 61 74 69  integer indicati
5e80: 6e 67 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ng the index of 
5e90: 74 68 65 20 46 54 53 20 74 61 62 6c 65 20 63 6f  the FTS table co
5ea0: 6c 75 6d 6e 20 74 6f 20 72 65 61 64 20 74 68 65  lumn to read the
5eb0: 20 0a 20 20 20 20 20 20 20 74 65 78 74 20 66 72   .       text fr
5ec0: 6f 6d 2e 20 43 6f 6c 75 6d 6e 73 20 61 72 65 20  om. Columns are 
5ed0: 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 6c 65  numbered from le
5ee0: 66 74 20 74 6f 20 72 69 67 68 74 20 73 74 61 72  ft to right star
5ef0: 74 69 6e 67 20 61 74 20 7a 65 72 6f 2e 0a 0a 20  ting at zero... 
5f00: 20 3c 6c 69 3e 20 54 68 65 20 74 65 78 74 20 74   <li> The text t
5f10: 6f 20 69 6e 73 65 72 74 20 62 65 66 6f 72 65 20  o insert before 
5f20: 65 61 63 68 20 70 68 72 61 73 65 20 6d 61 74 63  each phrase matc
5f30: 68 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74  h...  <li> The t
5f40: 65 78 74 20 74 6f 20 69 6e 73 65 72 74 20 61 66  ext to insert af
5f50: 74 65 72 20 65 61 63 68 20 70 68 72 61 73 65 20  ter each phrase 
5f60: 6d 61 74 63 68 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70  match..</ol>..<p
5f70: 3e 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a 3c  >For example:..<
5f80: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 3c 69 3e  codeblock>.  <i>
5f90: 2d 2d 20 52 65 74 75 72 6e 20 61 20 63 6f 70 79  -- Return a copy
5fa0: 20 6f 66 20 74 68 65 20 74 65 78 74 20 66 72 6f   of the text fro
5fb0: 6d 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63  m the leftmost c
5fc0: 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
5fd0: 72 65 6e 74 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d  rent</i>.  <i>--
5fe0: 20 72 6f 77 2c 20 77 69 74 68 20 70 68 72 61 73   row, with phras
5ff0: 65 20 6d 61 74 63 68 65 73 20 6d 61 72 6b 65 64  e matches marked
6000: 20 75 73 69 6e 67 20 68 74 6d 6c 20 22 62 22 20   using html "b" 
6010: 74 61 67 73 2e 3c 2f 69 3e 0a 20 20 53 45 4c 45  tags.</i>.  SELE
6020: 43 54 20 68 69 67 68 6c 69 67 68 74 28 66 74 73  CT highlight(fts
6030: 2c 20 30 2c 20 27 26 6c 74 3b 62 26 67 74 3b 27  , 0, '&lt;b&gt;'
6040: 20 27 26 6c 74 3b 2f 62 26 67 74 3b 27 29 20 46   '&lt;/b&gt;') F
6050: 52 4f 4d 20 66 74 73 20 57 48 45 52 45 20 66 74  ROM fts WHERE ft
6060: 73 20 4d 41 54 43 48 20 3f 0a 3c 2f 63 6f 64 65  s MATCH ?.</code
6070: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 6e 20 63 61  block>..<p>In ca
6080: 73 65 73 20 77 68 65 72 65 20 74 77 6f 20 6f 72  ses where two or
6090: 20 6d 6f 72 65 20 70 68 72 61 73 65 20 69 6e 73   more phrase ins
60a0: 74 61 6e 63 65 73 20 6f 76 65 72 6c 61 70 20 28  tances overlap (
60b0: 73 68 61 72 65 20 6f 6e 65 20 6f 72 20 6d 6f 72  share one or mor
60c0: 65 0a 74 6f 6b 65 6e 73 20 69 6e 20 63 6f 6d 6d  e.tokens in comm
60d0: 6f 6e 29 2c 20 61 20 73 69 6e 67 6c 65 20 6f 70  on), a single op
60e0: 65 6e 20 61 6e 64 20 63 6c 6f 73 65 20 6d 61 72  en and close mar
60f0: 6b 65 72 20 69 73 20 69 6e 73 65 72 74 65 64 20  ker is inserted 
6100: 66 6f 72 20 65 61 63 68 20 73 65 74 0a 6f 66 20  for each set.of 
6110: 6f 76 65 72 6c 61 70 70 69 6e 67 20 70 68 72 61  overlapping phra
6120: 73 65 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ses. For example
6130: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
6140: 20 3c 69 3e 2d 2d 20 41 73 73 75 6d 69 6e 67 20   <i>-- Assuming 
6150: 74 68 69 73 3a 3c 2f 69 3e 0a 20 20 43 52 45 41  this:</i>.  CREA
6160: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
6170: 20 66 74 20 55 53 49 4e 47 20 66 74 73 35 28 61   ft USING fts5(a
6180: 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  );.  INSERT INTO
6190: 20 66 74 20 56 41 4c 55 45 53 28 27 61 20 62 20   ft VALUES('a b 
61a0: 63 20 78 20 63 20 64 20 65 27 29 3b 0a 20 20 49  c x c d e');.  I
61b0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 20 56 41  NSERT INTO ft VA
61c0: 4c 55 45 53 28 27 61 20 62 20 63 20 63 20 64 20  LUES('a b c c d 
61d0: 65 27 29 3b 0a 20 20 49 4e 53 45 52 54 20 49 4e  e');.  INSERT IN
61e0: 54 4f 20 66 74 20 56 41 4c 55 45 53 28 27 61 20  TO ft VALUES('a 
61f0: 62 20 63 20 64 20 65 27 29 3b 0a 0a 20 20 3c 69  b c d e');..  <i
6200: 3e 2d 2d 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  >-- The followin
6210: 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
6220: 6e 74 20 72 65 74 75 72 6e 73 20 74 68 65 73 65  nt returns these
6230: 20 74 68 72 65 65 20 72 6f 77 73 3a 3c 2f 69 3e   three rows:</i>
6240: 0a 20 20 3c 69 3e 2d 2d 20 20 20 27 26 23 39 31  .  <i>--   '&#91
6250: 3b 61 20 62 20 63 26 23 39 33 3b 20 78 20 26 23  ;a b c&#93; x &#
6260: 39 31 3b 63 20 64 20 65 26 23 39 33 3b 27 3c 2f  91;c d e&#93;'</
6270: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 27 26 23  i>.  <i>--   '&#
6280: 39 31 3b 61 20 62 20 63 26 23 39 33 3b 20 26 23  91;a b c&#93; &#
6290: 39 31 3b 63 20 64 20 65 26 23 39 33 3b 27 3c 2f  91;c d e&#93;'</
62a0: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 20 20 27 26 23  i>.  <i>--   '&#
62b0: 39 31 3b 61 20 62 20 63 20 64 20 65 26 23 39 33  91;a b c d e&#93
62c0: 3b 27 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54 20  ;'</i>.  SELECT 
62d0: 68 69 67 68 6c 69 67 68 74 28 66 74 2c 20 30 2c  highlight(ft, 0,
62e0: 20 27 26 23 39 31 3b 27 2c 20 27 26 23 39 33 3b   '&#91;', '&#93;
62f0: 27 29 20 46 52 4f 4d 20 66 74 20 57 48 45 52 45  ') FROM ft WHERE
6300: 20 66 74 20 4d 41 54 43 48 20 27 61 2b 62 2b 63   ft MATCH 'a+b+c
6310: 20 41 4e 44 20 63 2b 64 2b 65 27 3b 0a 3c 2f 63   AND c+d+e';.</c
6320: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 68 33 3e 54  odeblock>..<h3>T
6330: 68 65 20 73 6e 69 70 70 65 74 28 29 20 66 75 6e  he snippet() fun
6340: 63 74 69 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  ction</h3>..<p>T
6350: 68 65 20 73 6e 69 70 70 65 74 28 29 20 66 75 6e  he snippet() fun
6360: 63 74 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72  ction is similar
6370: 20 74 6f 20 68 69 67 68 6c 69 67 68 74 28 29 2c   to highlight(),
6380: 20 65 78 63 65 70 74 20 74 68 61 74 20 69 6e 73   except that ins
6390: 74 65 61 64 20 6f 66 0a 72 65 74 75 72 6e 69 6e  tead of.returnin
63a0: 67 20 65 6e 74 69 72 65 20 63 6f 6c 75 6d 6e 20  g entire column 
63b0: 76 61 6c 75 65 73 2c 20 69 74 20 61 75 74 6f 6d  values, it autom
63c0: 61 74 69 63 61 6c 6c 79 20 73 65 6c 65 63 74 73  atically selects
63d0: 20 61 6e 64 20 65 78 74 72 61 63 74 73 20 61 0a   and extracts a.
63e0: 73 68 6f 72 74 20 66 72 61 67 6d 65 6e 74 20 6f  short fragment o
63f0: 66 20 64 6f 63 75 6d 65 6e 74 20 74 65 78 74 20  f document text 
6400: 74 6f 20 70 72 6f 63 65 73 73 20 61 6e 64 20 72  to process and r
6410: 65 74 75 72 6e 2e 20 54 68 65 20 73 6e 69 70 70  eturn. The snipp
6420: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 0a 6d 75  et() function.mu
6430: 73 74 20 62 65 20 70 61 73 73 65 64 20 66 69 76  st be passed fiv
6440: 65 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 6c  e parameters fol
6450: 6c 6f 77 69 6e 67 20 74 68 65 20 74 61 62 6c 65  lowing the table
6460: 20 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 3a 0a   name argument:.
6470: 0a 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 20 41 6e 20  .<ol>.  <li> An 
6480: 69 6e 74 65 67 65 72 20 69 6e 64 69 63 61 74 69  integer indicati
6490: 6e 67 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ng the index of 
64a0: 74 68 65 20 46 54 53 20 74 61 62 6c 65 20 63 6f  the FTS table co
64b0: 6c 75 6d 6e 20 74 6f 20 73 65 6c 65 63 74 0a 20  lumn to select. 
64c0: 20 20 20 20 20 20 74 68 65 20 72 65 74 75 72 6e        the return
64d0: 65 64 20 74 65 78 74 20 66 72 6f 6d 2e 20 43 6f  ed text from. Co
64e0: 6c 75 6d 6e 73 20 61 72 65 20 6e 75 6d 62 65 72  lumns are number
64f0: 65 64 20 66 72 6f 6d 20 6c 65 66 74 20 74 6f 20  ed from left to 
6500: 72 69 67 68 74 20 0a 20 20 20 20 20 20 20 73 74  right .       st
6510: 61 72 74 69 6e 67 20 61 74 20 7a 65 72 6f 2e 20  arting at zero. 
6520: 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
6530: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6540: 74 68 65 20 63 6f 6c 75 6d 6e 20 73 68 6f 75 6c  the column shoul
6550: 64 0a 20 20 20 20 20 20 20 62 65 20 61 75 74 6f  d.       be auto
6560: 6d 61 74 69 63 61 6c 6c 79 20 73 65 6c 65 63 74  matically select
6570: 65 64 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20  ed...  <li> The 
6580: 74 65 78 74 20 74 6f 20 69 6e 73 65 72 74 20 62  text to insert b
6590: 65 66 6f 72 65 20 65 61 63 68 20 70 68 72 61 73  efore each phras
65a0: 65 20 6d 61 74 63 68 20 77 69 74 68 69 6e 20 74  e match within t
65b0: 68 65 20 72 65 74 75 72 6e 65 64 20 74 65 78 74  he returned text
65c0: 2e 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 74 65  ...  <li> The te
65d0: 78 74 20 74 6f 20 69 6e 73 65 72 74 20 61 66 74  xt to insert aft
65e0: 65 72 20 65 61 63 68 20 70 68 72 61 73 65 20 6d  er each phrase m
65f0: 61 74 63 68 20 77 69 74 68 69 6e 20 74 68 65 20  atch within the 
6600: 72 65 74 75 72 6e 65 64 20 74 65 78 74 2e 0a 0a  returned text...
6610: 20 20 3c 6c 69 3e 20 54 68 65 20 74 65 78 74 20    <li> The text 
6620: 74 6f 20 61 64 64 20 74 6f 20 74 68 65 20 73 74  to add to the st
6630: 61 72 74 20 6f 72 20 65 6e 64 20 6f 66 20 74 68  art or end of th
6640: 65 20 73 65 6c 65 63 74 65 64 20 74 65 78 74 20  e selected text 
6650: 74 6f 20 69 6e 64 69 63 61 74 65 0a 20 20 20 20  to indicate.    
6660: 20 20 20 74 68 61 74 20 74 68 65 20 72 65 74 75     that the retu
6670: 72 6e 65 64 20 74 65 78 74 20 64 6f 65 73 20 6e  rned text does n
6680: 6f 74 20 6f 63 63 75 72 20 61 74 20 74 68 65 20  ot occur at the 
6690: 73 74 61 72 74 20 6f 72 20 65 6e 64 20 6f 66 20  start or end of 
66a0: 69 74 73 20 63 6f 6c 75 6d 6e 2c 0a 20 20 20 20  its column,.    
66b0: 20 20 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e     respectively.
66c0: 0a 0a 20 20 3c 6c 69 3e 20 54 68 65 20 6d 61 78  ..  <li> The max
66d0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
66e0: 6f 6b 65 6e 73 20 69 6e 20 74 68 65 20 72 65 74  okens in the ret
66f0: 75 72 6e 65 64 20 74 65 78 74 2e 20 54 68 69 73  urned text. This
6700: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
6710: 0a 20 20 20 20 20 20 20 74 68 61 6e 20 7a 65 72  .       than zer
6720: 6f 20 61 6e 64 20 65 71 75 61 6c 20 74 6f 20 6f  o and equal to o
6730: 72 20 6c 65 73 73 20 74 68 61 6e 20 36 34 2e 20  r less than 64. 
6740: 0a 3c 2f 6f 6c 3e 0a 0a 3c 68 32 20 74 61 67 73  .</ol>..<h2 tags
6750: 3d 22 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  ="auxiliary func
6760: 74 69 6f 6e 20 6d 61 70 70 69 6e 67 22 3e 53 6f  tion mapping">So
6770: 72 74 69 6e 67 20 62 79 20 41 75 78 69 6c 69 61  rting by Auxilia
6780: 72 79 20 46 75 6e 63 74 69 6f 6e 20 52 65 73 75  ry Function Resu
6790: 6c 74 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 41 6c  lts</h2>..<p> Al
67a0: 6c 20 46 54 53 35 20 74 61 62 6c 65 73 20 66 65  l FTS5 tables fe
67b0: 61 74 75 72 65 20 61 20 73 70 65 63 69 61 6c 20  ature a special 
67c0: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 6e 61  hidden column na
67d0: 6d 65 64 20 22 72 61 6e 6b 22 2e 20 49 66 20 74  med "rank". If t
67e0: 68 65 0a 63 75 72 72 65 6e 74 20 71 75 65 72 79  he.current query
67f0: 20 69 73 20 6e 6f 74 20 61 20 66 75 6c 6c 2d 74   is not a full-t
6800: 65 78 74 20 71 75 65 72 79 20 28 69 2e 65 2e 20  ext query (i.e. 
6810: 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 69  if it does not i
6820: 6e 63 6c 75 64 65 20 61 20 4d 41 54 43 48 0a 6f  nclude a MATCH.o
6830: 70 65 72 61 74 6f 72 29 2c 20 74 68 65 20 76 61  perator), the va
6840: 6c 75 65 20 6f 66 20 74 68 65 20 22 72 61 6e 6b  lue of the "rank
6850: 22 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6c 77 61  " column is alwa
6860: 79 73 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69  ys NULL. Otherwi
6870: 73 65 2c 20 69 6e 20 61 0a 66 75 6c 6c 2d 74 65  se, in a.full-te
6880: 78 74 20 71 75 65 72 79 2c 20 63 6f 6c 75 6d 6e  xt query, column
6890: 20 72 61 6e 6b 20 63 6f 6e 74 61 69 6e 73 20 62   rank contains b
68a0: 79 20 64 65 66 61 75 6c 74 20 74 68 65 20 73 61  y default the sa
68b0: 6d 65 20 76 61 6c 75 65 20 61 73 20 77 6f 75 6c  me value as woul
68c0: 64 20 62 65 0a 72 65 74 75 72 6e 65 64 20 62 79  d be.returned by
68d0: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 62   executing the b
68e0: 6d 32 35 28 29 20 61 75 78 69 6c 69 61 72 79 20  m25() auxiliary 
68f0: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 6e 6f  function with no
6900: 20 74 72 61 69 6c 69 6e 67 20 0a 61 72 67 75 6d   trailing .argum
6910: 65 6e 74 73 2e 0a 0a 3c 70 3e 20 54 68 65 20 64  ents...<p> The d
6920: 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
6930: 6e 20 72 65 61 64 69 6e 67 20 66 72 6f 6d 20 74  n reading from t
6940: 68 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 61  he rank column a
6950: 6e 64 20 75 73 69 6e 67 20 74 68 65 20 62 6d 32  nd using the bm2
6960: 35 28 29 0a 66 75 6e 63 74 69 6f 6e 20 64 69 72  5().function dir
6970: 65 63 74 6c 79 20 77 69 74 68 69 6e 20 74 68 65  ectly within the
6980: 20 71 75 65 72 79 20 69 73 20 6f 6e 6c 79 20 73   query is only s
6990: 69 67 6e 69 66 69 63 61 6e 74 20 77 68 65 6e 20  ignificant when 
69a0: 73 6f 72 74 69 6e 67 20 62 79 20 74 68 65 0a 72  sorting by the.r
69b0: 65 74 75 72 6e 65 64 20 76 61 6c 75 65 2e 20 49  eturned value. I
69c0: 6e 20 74 68 69 73 20 63 61 73 65 2c 20 75 73 69  n this case, usi
69d0: 6e 67 20 22 72 61 6e 6b 22 20 69 73 20 66 61 73  ng "rank" is fas
69e0: 74 65 72 20 74 68 61 6e 20 75 73 69 6e 67 20 62  ter than using b
69f0: 6d 32 35 28 29 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  m25()...<codeblo
6a00: 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 68 65 20  ck>.  <i>-- The 
6a10: 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 69 65  following querie
6a20: 73 20 61 72 65 20 6c 6f 67 69 63 61 6c 6c 79 20  s are logically 
6a30: 65 71 75 69 76 61 6c 65 6e 74 2e 20 42 75 74 20  equivalent. But 
6a40: 74 68 65 20 73 65 63 6f 6e 64 20 6d 61 79 3c 2f  the second may</
6a50: 69 3e 0a 20 20 3c 69 3e 2d 2d 20 62 65 20 66 61  i>.  <i>-- be fa
6a60: 73 74 65 72 2c 20 70 61 72 74 69 63 75 6c 61 72  ster, particular
6a70: 6c 79 20 69 66 20 74 68 65 20 63 61 6c 6c 65 72  ly if the caller
6a80: 20 61 62 61 6e 64 6f 6e 73 20 74 68 65 20 71 75   abandons the qu
6a90: 65 72 79 20 62 65 66 6f 72 65 3c 2f 69 3e 0a 20  ery before</i>. 
6aa0: 20 3c 69 3e 2d 2d 20 61 6c 6c 20 72 6f 77 73 20   <i>-- all rows 
6ab0: 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
6ac0: 65 64 20 28 6f 72 20 69 66 20 74 68 65 20 71 75  ed (or if the qu
6ad0: 65 72 69 65 73 20 77 65 72 65 20 6d 6f 64 69 66  eries were modif
6ae0: 69 65 64 20 74 6f 20 3c 2f 69 3e 0a 20 20 3c 69  ied to </i>.  <i
6af0: 3e 2d 2d 20 69 6e 63 6c 75 64 65 20 4c 49 4d 49  >-- include LIMI
6b00: 54 20 63 6c 61 75 73 65 73 29 2e 3c 2f 69 3e 0a  T clauses).</i>.
6b10: 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20    SELECT * FROM 
6b20: 66 74 73 20 57 48 45 52 45 20 66 74 73 20 4d 41  fts WHERE fts MA
6b30: 54 43 48 20 3f 20 4f 52 44 45 52 20 42 59 20 62  TCH ? ORDER BY b
6b40: 6d 32 35 28 66 74 73 29 20 44 45 53 43 3b 0a 20  m25(fts) DESC;. 
6b50: 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 66   SELECT * FROM f
6b60: 74 73 20 57 48 45 52 45 20 66 74 73 20 4d 41 54  ts WHERE fts MAT
6b70: 43 48 20 3f 20 4f 52 44 45 52 20 42 59 20 72 61  CH ? ORDER BY ra
6b80: 6e 6b 20 44 45 53 43 3b 0a 3c 2f 63 6f 64 65 62  nk DESC;.</codeb
6b90: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 49 6e 73 74 65  lock>..<p> Inste
6ba0: 61 64 20 6f 66 20 75 73 69 6e 67 20 62 6d 32 35  ad of using bm25
6bb0: 28 29 20 77 69 74 68 20 6e 6f 20 74 72 61 69 6c  () with no trail
6bc0: 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 2c 20 74  ing arguments, t
6bd0: 68 65 20 73 70 65 63 69 66 69 63 20 61 75 78 69  he specific auxi
6be0: 6c 69 61 72 79 0a 66 75 6e 63 74 69 6f 6e 20 6d  liary.function m
6bf0: 61 70 70 65 64 20 74 6f 20 74 68 65 20 72 61 6e  apped to the ran
6c00: 6b 20 63 6f 6c 75 6d 6e 20 6d 61 79 20 62 65 20  k column may be 
6c10: 63 6f 6e 66 69 67 75 72 65 64 20 65 69 74 68 65  configured eithe
6c20: 72 20 6f 6e 20 61 20 70 65 72 2d 71 75 65 72 79  r on a per-query
6c30: 0a 62 61 73 69 73 2c 20 6f 72 20 62 79 20 73 65  .basis, or by se
6c40: 74 74 69 6e 67 20 61 20 64 69 66 66 65 72 65 6e  tting a differen
6c50: 74 20 70 65 72 73 69 73 74 65 6e 74 20 64 65 66  t persistent def
6c60: 61 75 6c 74 20 66 6f 72 20 74 68 65 20 46 54 53  ault for the FTS
6c70: 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e 20 49 6e 20   table...<p> In 
6c80: 6f 72 64 65 72 20 74 6f 20 63 68 61 6e 67 65 20  order to change 
6c90: 74 68 65 20 6d 61 70 70 69 6e 67 20 6f 66 20 74  the mapping of t
6ca0: 68 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 20 66  he rank column f
6cb0: 6f 72 20 61 20 73 69 6e 67 6c 65 20 71 75 65 72  or a single quer
6cc0: 79 2c 20 0a 61 20 74 65 72 6d 20 73 69 6d 69 6c  y, .a term simil
6cd0: 61 72 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  ar to the follow
6ce0: 69 6e 67 20 69 73 20 61 64 64 65 64 20 74 6f 20  ing is added to 
6cf0: 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
6d00: 20 6f 66 20 61 20 71 75 65 72 79 3a 0a 0a 3c 63   of a query:..<c
6d10: 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 72 61 6e 6b  odeblock>.  rank
6d20: 20 4d 41 54 43 48 20 27 61 75 78 69 6c 69 61 72   MATCH 'auxiliar
6d30: 79 2d 66 75 6e 63 74 69 6f 6e 2d 6e 61 6d 65 28  y-function-name(
6d40: 61 72 67 31 2c 20 61 72 67 32 2c 20 2e 2e 2e 29  arg1, arg2, ...)
6d50: 27 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  '.</codeblock>..
6d60: 3c 70 3e 20 54 68 65 20 72 69 67 68 74 2d 68 61  <p> The right-ha
6d70: 6e 64 2d 73 69 64 65 20 6f 66 20 74 68 65 20 4d  nd-side of the M
6d80: 41 54 43 48 20 63 6c 61 75 73 65 20 6d 75 73 74  ATCH clause must
6d90: 20 62 65 20 61 20 63 6f 6e 73 74 61 6e 74 20 65   be a constant e
6da0: 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 0a 65  xpression that.e
6db0: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74  valuates to a st
6dc0: 72 69 6e 67 20 63 6f 6e 73 69 73 74 69 6e 67 20  ring consisting 
6dd0: 6f 66 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  of the auxiliary
6de0: 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
6df0: 6f 6b 65 2c 20 66 6f 6c 6c 6f 77 65 64 0a 62 79  oke, followed.by
6e00: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 63 6f   zero or more co
6e10: 6d 6d 61 20 73 65 70 61 72 61 74 65 64 20 61 72  mma separated ar
6e20: 67 75 6d 65 6e 74 73 20 77 69 74 68 69 6e 20 70  guments within p
6e30: 61 72 65 6e 74 68 65 73 69 73 2e 20 41 72 67 75  arenthesis. Argu
6e40: 6d 65 6e 74 73 20 6d 75 73 74 0a 62 65 20 53 51  ments must.be SQ
6e50: 4c 20 6c 69 74 65 72 61 6c 73 2e 20 46 6f 72 20  L literals. For 
6e60: 65 78 61 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62  example:..<codeb
6e70: 6c 6f 63 6b 3e 0a 20 20 3c 69 3e 2d 2d 20 54 68  lock>.  <i>-- Th
6e80: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  e following quer
6e90: 69 65 73 20 61 72 65 20 6c 6f 67 69 63 61 6c 6c  ies are logicall
6ea0: 79 20 65 71 75 69 76 61 6c 65 6e 74 2e 20 42 75  y equivalent. Bu
6eb0: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 6d 61 79  t the second may
6ec0: 3c 2f 69 3e 0a 20 20 3c 69 3e 2d 2d 20 62 65 20  </i>.  <i>-- be 
6ed0: 66 61 73 74 65 72 2e 20 53 65 65 20 61 62 6f 76  faster. See abov
6ee0: 65 2e 20 3c 2f 69 3e 0a 20 20 53 45 4c 45 43 54  e. </i>.  SELECT
6ef0: 20 2a 20 46 52 4f 4d 20 66 74 73 20 57 48 45 52   * FROM fts WHER
6f00: 45 20 66 74 73 20 4d 41 54 43 48 20 3f 20 4f 52  E fts MATCH ? OR
6f10: 44 45 52 20 42 59 20 62 6d 32 35 28 66 74 73 2c  DER BY bm25(fts,
6f20: 20 31 30 2e 30 2c 20 35 2e 30 29 20 44 45 53 43   10.0, 5.0) DESC
6f30: 3b 0a 20 20 53 45 4c 45 43 54 20 2a 20 46 52 4f  ;.  SELECT * FRO
6f40: 4d 20 66 74 73 20 57 48 45 52 45 20 66 74 73 20  M fts WHERE fts 
6f50: 4d 41 54 43 48 20 3f 20 41 4e 44 20 72 61 6e 6b  MATCH ? AND rank
6f60: 20 4d 41 54 43 48 20 27 62 6d 32 35 28 31 30 2e   MATCH 'bm25(10.
6f70: 30 2c 20 35 2e 30 29 27 20 4f 52 44 45 52 20 42  0, 5.0)' ORDER B
6f80: 59 20 72 61 6e 6b 20 44 45 53 43 3b 0a 3c 2f 63  Y rank DESC;.</c
6f90: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54  odeblock>..<p> T
6fa0: 68 65 20 64 65 66 61 75 6c 74 20 6d 61 70 70 69  he default mappi
6fb0: 6e 67 20 6f 66 20 74 68 65 20 72 61 6e 6b 20 63  ng of the rank c
6fc0: 6f 6c 75 6d 6e 20 66 6f 72 20 61 20 74 61 62 6c  olumn for a tabl
6fd0: 65 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  e may be modifie
6fe0: 64 20 0a 75 73 69 6e 67 20 74 68 65 20 5b 46 54  d .using the [FT
6ff0: 53 35 20 72 61 6e 6b 20 63 6f 6e 66 69 67 75 72  S5 rank configur
7000: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 2e 0a 0a  ation option]...
7010: 3c 68 31 3e 53 70 65 63 69 61 6c 20 49 4e 53 45  <h1>Special INSE
7020: 52 54 20 43 6f 6d 6d 61 6e 64 73 3c 2f 68 31 3e  RT Commands</h1>
7030: 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35  ..<h2 tags="FTS5
7040: 20 61 75 74 6f 6d 65 72 67 65 20 6f 70 74 69 6f   automerge optio
7050: 6e 22 3e 54 68 65 20 27 61 75 74 6f 6d 65 72 67  n">The 'automerg
7060: 65 27 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e' Configuration
7070: 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70   Option</h2>..<p
7080: 3e 0a 20 20 49 6e 73 74 65 61 64 20 6f 66 20 75  >.  Instead of u
7090: 73 69 6e 67 20 61 20 73 69 6e 67 6c 65 20 64 61  sing a single da
70a0: 74 61 20 73 74 72 75 63 74 75 72 65 20 6f 6e 20  ta structure on 
70b0: 64 69 73 6b 20 74 6f 20 73 74 6f 72 65 20 74 68  disk to store th
70c0: 65 20 66 75 6c 6c 2d 74 65 78 74 0a 20 20 69 6e  e full-text.  in
70d0: 64 65 78 2c 20 46 54 53 35 20 75 73 65 73 20 61  dex, FTS5 uses a
70e0: 20 73 65 72 69 65 73 20 6f 66 20 62 2d 74 72 65   series of b-tre
70f0: 65 73 2e 20 45 61 63 68 20 74 69 6d 65 20 61 20  es. Each time a 
7100: 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  new transaction 
7110: 69 73 0a 20 20 63 6f 6d 6d 69 74 74 65 64 2c 20  is.  committed, 
7120: 61 20 6e 65 77 20 62 2d 74 72 65 65 20 63 6f 6e  a new b-tree con
7130: 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6e 74  taining the cont
7140: 65 6e 74 73 20 6f 66 20 74 68 65 20 63 6f 6d 6d  ents of the comm
7150: 69 74 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f  itted transactio
7160: 6e 0a 20 20 69 73 20 77 72 69 74 74 65 6e 20 69  n.  is written i
7170: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
7180: 20 66 69 6c 65 2e 20 57 68 65 6e 20 74 68 65 20   file. When the 
7190: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 20  full-text index 
71a0: 69 73 20 71 75 65 72 69 65 64 2c 20 65 61 63 68  is queried, each
71b0: 0a 20 20 62 2d 74 72 65 65 20 6d 75 73 74 20 62  .  b-tree must b
71c0: 65 20 71 75 65 72 69 65 64 20 69 6e 64 69 76 69  e queried indivi
71d0: 64 75 61 6c 6c 79 20 61 6e 64 20 74 68 65 20 72  dually and the r
71e0: 65 73 75 6c 74 73 20 6d 65 72 67 65 64 20 62 65  esults merged be
71f0: 66 6f 72 65 20 62 65 69 6e 67 0a 20 20 72 65 74  fore being.  ret
7200: 75 72 6e 65 64 20 74 6f 20 74 68 65 20 75 73 65  urned to the use
7210: 72 2e 0a 0a 3c 70 3e 0a 20 20 49 6e 20 6f 72 64  r...<p>.  In ord
7220: 65 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  er to prevent th
7230: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 2d 74 72  e number of b-tr
7240: 65 65 73 20 69 6e 20 74 68 65 20 64 61 74 61 62  ees in the datab
7250: 61 73 65 20 66 72 6f 6d 20 62 65 63 6f 6d 69 6e  ase from becomin
7260: 67 20 74 6f 6f 0a 20 20 6c 61 72 67 65 20 28 73  g too.  large (s
7270: 6c 6f 77 69 6e 67 20 64 6f 77 6e 20 71 75 65 72  lowing down quer
7280: 69 65 73 29 2c 20 73 6d 61 6c 6c 65 72 20 62 2d  ies), smaller b-
7290: 74 72 65 65 73 20 61 72 65 20 70 65 72 69 6f 64  trees are period
72a0: 69 63 61 6c 6c 79 20 6d 65 72 67 65 64 20 69 6e  ically merged in
72b0: 74 6f 0a 20 20 73 69 6e 67 6c 65 20 6c 61 72 67  to.  single larg
72c0: 65 72 20 62 2d 74 72 65 65 73 20 63 6f 6e 74 61  er b-trees conta
72d0: 69 6e 69 6e 67 20 74 68 65 20 73 61 6d 65 20 64  ining the same d
72e0: 61 74 61 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ata. By default,
72f0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 0a 20 20   this happens.  
7300: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 77 69  automatically wi
7310: 74 68 69 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  thin INSERT, UPD
7320: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
7330: 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 6d 6f  atements that mo
7340: 64 69 66 79 20 74 68 65 0a 20 20 66 75 6c 6c 2d  dify the.  full-
7350: 74 65 78 74 20 69 6e 64 65 78 2e 20 54 68 65 20  text index. The 
7360: 27 61 75 74 6f 6d 65 72 67 65 27 20 70 61 72 61  'automerge' para
7370: 6d 65 74 65 72 20 64 65 74 65 72 6d 69 6e 65 73  meter determines
7380: 20 68 6f 77 20 6d 61 6e 79 20 73 6d 61 6c 6c 65   how many smalle
7390: 72 0a 20 20 62 2d 74 72 65 65 73 20 61 72 65 20  r.  b-trees are 
73a0: 6d 65 72 67 65 64 20 74 6f 67 65 74 68 65 72 20  merged together 
73b0: 61 74 20 61 20 74 69 6d 65 2e 20 53 65 74 74 69  at a time. Setti
73c0: 6e 67 20 69 74 20 74 6f 20 61 20 73 6d 61 6c 6c  ng it to a small
73d0: 20 76 61 6c 75 65 20 63 61 6e 0a 20 20 73 70 65   value can.  spe
73e0: 65 64 20 75 70 20 71 75 65 72 69 65 73 20 28 61  ed up queries (a
73f0: 73 20 74 68 65 79 20 68 61 76 65 20 74 6f 20 71  s they have to q
7400: 75 65 72 79 20 61 6e 64 20 6d 65 72 67 65 20 74  uery and merge t
7410: 68 65 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  he results from 
7420: 66 65 77 65 72 20 0a 20 20 62 2d 74 72 65 65 73  fewer .  b-trees
7430: 29 2c 20 62 75 74 20 63 61 6e 20 61 6c 73 6f 20  ), but can also 
7440: 73 6c 6f 77 20 64 6f 77 6e 20 77 72 69 74 69 6e  slow down writin
7450: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  g to the databas
7460: 65 20 28 61 73 20 65 61 63 68 20 49 4e 53 45 52  e (as each INSER
7470: 54 2c 0a 20 20 55 50 44 41 54 45 20 6f 72 20 44  T,.  UPDATE or D
7480: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
7490: 68 61 73 20 74 6f 20 64 6f 20 6d 6f 72 65 20 77  has to do more w
74a0: 6f 72 6b 20 61 73 20 70 61 72 74 20 6f 66 20 74  ork as part of t
74b0: 68 65 20 61 75 74 6f 6d 61 74 69 63 0a 20 20 6d  he automatic.  m
74c0: 65 72 67 69 6e 67 20 70 72 6f 63 65 73 73 29 2e  erging process).
74d0: 0a 0a 3c 70 3e 0a 20 20 45 61 63 68 20 6f 66 20  ..<p>.  Each of 
74e0: 74 68 65 20 62 2d 74 72 65 65 73 20 74 68 61 74  the b-trees that
74f0: 20 6d 61 6b 65 20 75 70 20 74 68 65 20 66 75 6c   make up the ful
7500: 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 69 73 20  l-text index is 
7510: 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 22 6c  assigned to a "l
7520: 65 76 65 6c 22 0a 20 20 62 61 73 65 64 20 6f 6e  evel".  based on
7530: 20 69 74 73 20 73 69 7a 65 2e 20 4c 65 76 65 6c   its size. Level
7540: 2d 30 20 62 2d 74 72 65 65 73 20 61 72 65 20 74  -0 b-trees are t
7550: 68 65 20 73 6d 61 6c 6c 65 73 74 2c 20 61 73 20  he smallest, as 
7560: 74 68 65 79 20 63 6f 6e 74 61 69 6e 20 74 68 65  they contain the
7570: 0a 20 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 61  .  contents of a
7580: 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 61 63 74   single transact
7590: 69 6f 6e 2e 20 48 69 67 68 65 72 20 6c 65 76 65  ion. Higher leve
75a0: 6c 20 62 2d 74 72 65 65 73 20 61 72 65 20 74 68  l b-trees are th
75b0: 65 20 72 65 73 75 6c 74 20 6f 66 0a 20 20 6d 65  e result of.  me
75c0: 72 67 69 6e 67 20 74 77 6f 20 6f 72 20 6d 6f 72  rging two or mor
75d0: 65 20 6c 65 76 65 6c 2d 30 20 62 2d 74 72 65 65  e level-0 b-tree
75e0: 73 20 74 6f 67 65 74 68 65 72 20 61 6e 64 20 73  s together and s
75f0: 6f 20 74 68 65 79 20 61 72 65 20 6c 61 72 67 65  o they are large
7600: 72 2e 20 46 54 53 35 0a 20 20 62 65 67 69 6e 73  r. FTS5.  begins
7610: 20 74 6f 20 6d 65 72 67 65 20 62 2d 74 72 65 65   to merge b-tree
7620: 73 20 74 6f 67 65 74 68 65 72 20 6f 6e 63 65 20  s together once 
7630: 74 68 65 72 65 20 65 78 69 73 74 20 3c 69 3e 4d  there exist <i>M
7640: 3c 2f 69 3e 20 6f 72 20 6d 6f 72 65 20 62 2d 74  </i> or more b-t
7650: 72 65 65 73 20 0a 20 20 77 69 74 68 20 74 68 65  rees .  with the
7660: 20 73 61 6d 65 20 6c 65 76 65 6c 2c 20 77 68 65   same level, whe
7670: 72 65 20 3c 69 3e 4d 3c 2f 69 3e 20 69 73 20 74  re <i>M</i> is t
7680: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
7690: 27 61 75 74 6f 6d 65 72 67 65 27 20 0a 20 20 70  'automerge' .  p
76a0: 61 72 61 6d 65 74 65 72 2e 0a 0a 3c 70 3e 0a 20  arameter...<p>. 
76b0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   The maximum all
76c0: 6f 77 65 64 20 76 61 6c 75 65 20 66 6f 72 20 74  owed value for t
76d0: 68 65 20 27 61 75 74 6f 6d 65 72 67 65 27 20 70  he 'automerge' p
76e0: 61 72 61 6d 65 74 65 72 20 69 73 20 31 36 2e 20  arameter is 16. 
76f0: 54 68 65 20 64 65 66 61 75 6c 74 0a 20 20 76 61  The default.  va
7700: 6c 75 65 20 69 73 20 34 2e 20 53 65 74 74 69 6e  lue is 4. Settin
7710: 67 20 74 68 65 20 27 61 75 74 6f 6d 65 72 67 65  g the 'automerge
7720: 27 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 30  ' parameter to 0
7730: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 61 75   disables the au
7740: 74 6f 6d 61 74 69 63 20 0a 20 20 69 6e 63 72 65  tomatic .  incre
7750: 6d 65 6e 74 61 6c 20 6d 65 72 67 69 6e 67 20 6f  mental merging o
7760: 66 20 62 2d 74 72 65 65 73 20 61 6c 74 6f 67 65  f b-trees altoge
7770: 74 68 65 72 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63  ther...<codebloc
7780: 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  k>.  INSERT INTO
7790: 20 66 74 28 66 74 2c 20 72 61 6e 6b 29 20 56 41   ft(ft, rank) VA
77a0: 4c 55 45 53 28 27 61 75 74 6f 6d 65 72 67 65 27  LUES('automerge'
77b0: 2c 20 38 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  , 8);.</codebloc
77c0: 6b 3e 0a 0a 3c 68 32 3e 54 68 65 20 27 63 72 69  k>..<h2>The 'cri
77d0: 73 69 73 6d 65 72 67 65 27 20 43 6f 6e 66 69 67  sismerge' Config
77e0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 3c 2f  uration Option</
77f0: 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 27 63 72 69  h2>..<p>The 'cri
7800: 73 69 73 6d 65 72 67 65 27 20 6f 70 74 69 6f 6e  sismerge' option
7810: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 27   is similar to '
7820: 61 75 74 6f 6d 65 72 67 65 27 2c 20 69 6e 20 74  automerge', in t
7830: 68 61 74 20 69 74 20 64 65 74 65 72 6d 69 6e 65  hat it determine
7840: 73 0a 68 6f 77 20 61 6e 64 20 68 6f 77 20 6f 66  s.how and how of
7850: 74 65 6e 20 74 68 65 20 63 6f 6d 70 6f 6e 65 6e  ten the componen
7860: 74 20 62 2d 74 72 65 65 73 20 74 68 61 74 20 6d  t b-trees that m
7870: 61 6b 65 20 75 70 20 74 68 65 20 66 75 6c 6c 2d  ake up the full-
7880: 74 65 78 74 20 69 6e 64 65 78 20 61 72 65 0a 6d  text index are.m
7890: 65 72 67 65 64 20 74 6f 67 65 74 68 65 72 2e 20  erged together. 
78a0: 4f 6e 63 65 20 74 68 65 72 65 20 65 78 69 73 74  Once there exist
78b0: 20 3c 69 3e 43 3c 2f 69 3e 20 6f 72 20 6d 6f 72   <i>C</i> or mor
78c0: 65 20 62 2d 74 72 65 65 73 20 6f 6e 20 61 20 73  e b-trees on a s
78d0: 69 6e 67 6c 65 20 6c 65 76 65 6c 0a 77 69 74 68  ingle level.with
78e0: 69 6e 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74  in the full-text
78f0: 20 69 6e 64 65 78 2c 20 77 68 65 72 65 20 3c 69   index, where <i
7900: 3e 43 3c 2f 69 3e 20 69 73 20 74 68 65 20 76 61  >C</i> is the va
7910: 6c 75 65 20 6f 66 20 74 68 65 20 27 63 72 69 73  lue of the 'cris
7920: 69 73 6d 65 72 67 65 27 0a 6f 70 74 69 6f 6e 2c  ismerge'.option,
7930: 20 61 6c 6c 20 62 2d 74 72 65 65 73 20 6f 6e 20   all b-trees on 
7940: 74 68 65 20 6c 65 76 65 6c 20 61 72 65 20 69 6d  the level are im
7950: 6d 65 64 69 61 74 65 6c 79 20 6d 65 72 67 65 64  mediately merged
7960: 20 69 6e 74 6f 20 61 20 73 69 6e 67 6c 65 20 62   into a single b
7970: 2d 74 72 65 65 2e 0a 0a 3c 70 3e 54 68 65 20 64  -tree...<p>The d
7980: 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
7990: 6e 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 61 6e  n this option an
79a0: 64 20 74 68 65 20 27 61 75 74 6f 6d 65 72 67 65  d the 'automerge
79b0: 27 20 6f 70 74 69 6f 6e 20 69 73 20 74 68 61 74  ' option is that
79c0: 20 77 68 65 6e 0a 74 68 65 20 27 61 75 74 6f 6d   when.the 'autom
79d0: 65 72 67 65 27 20 6c 69 6d 69 74 20 69 73 20 72  erge' limit is r
79e0: 65 61 63 68 65 64 20 46 54 53 35 20 6f 6e 6c 79  eached FTS5 only
79f0: 20 62 65 67 69 6e 73 20 74 6f 20 6d 65 72 67 65   begins to merge
7a00: 20 74 68 65 20 62 2d 74 72 65 65 73 0a 74 6f 67   the b-trees.tog
7a10: 65 74 68 65 72 2e 20 4d 6f 73 74 20 6f 66 20 74  ether. Most of t
7a20: 68 65 20 77 6f 72 6b 20 69 73 20 70 65 72 66 6f  he work is perfo
7a30: 72 6d 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  rmed as part of 
7a40: 73 75 62 73 65 71 75 65 6e 74 20 49 4e 53 45 52  subsequent INSER
7a50: 54 2c 20 0a 55 50 44 41 54 45 20 6f 72 20 44 45  T, .UPDATE or DE
7a60: 4c 45 54 45 20 6f 70 65 72 61 74 69 6f 6e 73 2e  LETE operations.
7a70: 20 57 68 65 72 65 61 73 20 77 68 65 6e 20 74 68   Whereas when th
7a80: 65 20 27 63 72 69 73 69 73 6d 65 72 67 65 27 20  e 'crisismerge' 
7a90: 6c 69 6d 69 74 20 69 73 20 72 65 61 63 68 65 64  limit is reached
7aa0: 2c 0a 74 68 65 20 6f 66 66 65 6e 64 69 6e 67 20  ,.the offending 
7ab0: 62 2d 74 72 65 65 73 20 61 72 65 20 61 6c 6c 20  b-trees are all 
7ac0: 6d 65 72 67 65 64 20 69 6d 6d 65 64 69 61 74 65  merged immediate
7ad0: 6c 79 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74  ly. This means t
7ae0: 68 61 74 20 61 6e 20 49 4e 53 45 52 54 2c 0a 55  hat an INSERT,.U
7af0: 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
7b00: 74 68 61 74 20 74 72 69 67 67 65 72 73 20 61 20  that triggers a 
7b10: 63 72 69 73 69 73 2d 6d 65 72 67 65 20 6d 61 79  crisis-merge may
7b20: 20 74 61 6b 65 20 61 20 6c 6f 6e 67 20 74 69 6d   take a long tim
7b30: 65 20 74 6f 20 0a 63 6f 6d 70 6c 65 74 65 2e 0a  e to .complete..
7b40: 0a 3c 70 3e 54 68 65 20 64 65 66 61 75 6c 74 20  .<p>The default 
7b50: 27 63 72 69 73 69 73 6d 65 72 67 65 27 20 76 61  'crisismerge' va
7b60: 6c 75 65 20 69 73 20 31 36 2e 20 54 68 65 72 65  lue is 16. There
7b70: 20 69 73 20 6e 6f 20 6d 61 78 69 6d 75 6d 20 6c   is no maximum l
7b80: 69 6d 69 74 2e 20 41 74 74 65 6d 70 74 69 6e 67  imit. Attempting
7b90: 0a 74 6f 20 73 65 74 20 74 68 65 20 27 63 72 69  .to set the 'cri
7ba0: 73 69 73 6d 65 72 67 65 27 20 70 61 72 61 6d 65  sismerge' parame
7bb0: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
7bc0: 66 20 30 20 6f 72 20 31 20 69 73 20 65 71 75 69  f 0 or 1 is equi
7bd0: 76 61 6c 65 6e 74 20 74 6f 0a 73 65 74 74 69 6e  valent to.settin
7be0: 67 20 69 74 20 74 6f 20 74 68 65 20 64 65 66 61  g it to the defa
7bf0: 75 6c 74 20 76 61 6c 75 65 20 28 31 36 29 2e 20  ult value (16). 
7c00: 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
7c10: 6f 20 61 74 74 65 6d 70 74 20 74 6f 20 73 65 74  o attempt to set
7c20: 20 74 68 65 0a 27 63 72 69 73 69 73 6d 65 72 67   the.'crisismerg
7c30: 65 27 20 6f 70 74 69 6f 6e 20 74 6f 20 61 20 6e  e' option to a n
7c40: 65 67 61 74 69 76 65 20 76 61 6c 75 65 2e 0a 0a  egative value...
7c50: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e  <codeblock>.  IN
7c60: 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74 2c  SERT INTO ft(ft,
7c70: 20 72 61 6e 6b 29 20 56 41 4c 55 45 53 28 27 63   rank) VALUES('c
7c80: 72 69 73 69 73 6d 65 72 67 65 27 2c 20 31 36 29  risismerge', 16)
7c90: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
7ca0: 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 64  <h2 tags="FTS5 d
7cb0: 65 6c 65 74 65 20 63 6f 6d 6d 61 6e 64 22 3e 54  elete command">T
7cc0: 68 65 20 27 64 65 6c 65 74 65 27 20 43 6f 6d 6d  he 'delete' Comm
7cd0: 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68  and</h2>..<p> Th
7ce0: 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 6f 6e  is command is on
7cf0: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 69 74  ly available wit
7d00: 68 20 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c  h [FTS5 external
7d10: 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20   content tables 
7d20: 7c 0a 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65  |.external conte
7d30: 6e 74 5d 20 61 6e 64 20 5b 46 54 53 35 20 63 6f  nt] and [FTS5 co
7d40: 6e 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73  ntentless tables
7d50: 20 7c 20 63 6f 6e 74 65 6e 74 6c 65 73 73 5d 20   | contentless] 
7d60: 74 61 62 6c 65 73 2e 20 49 74 0a 69 73 20 75 73  tables. It.is us
7d70: 65 64 20 74 6f 20 64 65 6c 65 74 65 20 74 68 65  ed to delete the
7d80: 20 69 6e 64 65 78 20 65 6e 74 72 69 65 73 20 61   index entries a
7d90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
7da0: 20 73 69 6e 67 6c 65 20 72 6f 77 20 66 72 6f 6d   single row from
7db0: 20 74 68 65 0a 66 75 6c 6c 2d 74 65 78 74 20 69   the.full-text i
7dc0: 6e 64 65 78 2e 20 54 68 69 73 20 63 6f 6d 6d 61  ndex. This comma
7dd0: 6e 64 20 61 6e 64 20 74 68 65 20 5b 46 54 53 35  nd and the [FTS5
7de0: 20 64 65 6c 65 74 65 2d 61 6c 6c 20 63 6f 6d 6d   delete-all comm
7df0: 61 6e 64 20 7c 20 64 65 6c 65 74 65 2d 61 6c 6c  and | delete-all
7e00: 5d 0a 63 6f 6d 6d 61 6e 64 20 61 72 65 20 74 68  ].command are th
7e10: 65 20 6f 6e 6c 79 20 77 61 79 73 20 74 6f 20 72  e only ways to r
7e20: 65 6d 6f 76 65 20 65 6e 74 72 69 65 73 20 66 72  emove entries fr
7e30: 6f 6d 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74  om the full-text
7e40: 20 69 6e 64 65 78 20 6f 66 20 61 0a 63 6f 6e 74   index of a.cont
7e50: 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 2e 0a 0a  entless table...
7e60: 3c 70 3e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  <p> In order to 
7e70: 75 73 65 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64  use this command
7e80: 20 74 6f 20 64 65 6c 65 74 65 20 61 20 72 6f 77   to delete a row
7e90: 2c 20 74 68 65 20 74 65 78 74 20 76 61 6c 75 65  , the text value
7ea0: 20 27 64 65 6c 65 74 65 27 20 0a 6d 75 73 74 20   'delete' .must 
7eb0: 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
7ec0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6c   the special col
7ed0: 75 6d 6e 20 77 69 74 68 20 74 68 65 20 73 61 6d  umn with the sam
7ee0: 65 20 6e 61 6d 65 20 61 73 20 74 68 65 20 74 61  e name as the ta
7ef0: 62 6c 65 2e 0a 54 68 65 20 72 6f 77 69 64 20 6f  ble..The rowid o
7f00: 66 20 74 68 65 20 72 6f 77 20 74 6f 20 64 65 6c  f the row to del
7f10: 65 74 65 20 69 73 20 69 6e 73 65 72 74 65 64 20  ete is inserted 
7f20: 69 6e 74 6f 20 74 68 65 20 72 6f 77 69 64 20 63  into the rowid c
7f30: 6f 6c 75 6d 6e 2e 20 54 68 65 0a 76 61 6c 75 65  olumn. The.value
7f40: 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  s inserted into 
7f50: 74 68 65 20 6f 74 68 65 72 20 63 6f 6c 75 6d 6e  the other column
7f60: 73 20 6d 75 73 74 20 6d 61 74 63 68 20 74 68 65  s must match the
7f70: 20 76 61 6c 75 65 73 20 63 75 72 72 65 6e 74 6c   values currentl
7f80: 79 0a 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  y.stored in the 
7f90: 74 61 62 6c 65 2e 20 46 6f 72 20 65 78 61 6d 70  table. For examp
7fa0: 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  le:..<codeblock>
7fb0: 0a 20 20 3c 69 3e 2d 2d 20 49 6e 73 65 72 74 20  .  <i>-- Insert 
7fc0: 61 20 72 6f 77 20 77 69 74 68 20 72 6f 77 69 64  a row with rowid
7fd0: 3d 31 34 20 69 6e 74 6f 20 74 68 65 20 66 74 73  =14 into the fts
7fe0: 35 20 74 61 62 6c 65 2e 3c 2f 69 3e 0a 20 20 49  5 table.</i>.  I
7ff0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 72 6f  NSERT INTO ft(ro
8000: 77 69 64 2c 20 61 2c 20 62 2c 20 63 29 20 56 41  wid, a, b, c) VA
8010: 4c 55 45 53 28 31 34 2c 20 24 61 2c 20 24 62 2c  LUES(14, $a, $b,
8020: 20 24 63 29 3b 0a 20 20 0a 20 20 3c 69 3e 2d 2d   $c);.  .  <i>--
8030: 20 52 65 6d 6f 76 65 20 74 68 65 20 73 61 6d 65   Remove the same
8040: 20 72 6f 77 20 66 72 6f 6d 20 74 68 65 20 66 74   row from the ft
8050: 73 35 20 74 61 62 6c 65 2e 3c 2f 69 3e 0a 20 20  s5 table.</i>.  
8060: 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66  INSERT INTO ft(f
8070: 74 2c 20 72 6f 77 69 64 2c 20 61 2c 20 62 2c 20  t, rowid, a, b, 
8080: 63 29 20 56 41 4c 55 45 53 28 27 64 65 6c 65 74  c) VALUES('delet
8090: 65 27 2c 20 31 34 2c 20 24 61 2c 20 24 62 2c 20  e', 14, $a, $b, 
80a0: 24 63 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  $c);.</codeblock
80b0: 3e 0a 0a 3c 70 3e 20 49 66 20 74 68 65 20 76 61  >..<p> If the va
80c0: 6c 75 65 73 20 22 69 6e 73 65 72 74 65 64 22 20  lues "inserted" 
80d0: 69 6e 74 6f 20 74 68 65 20 74 65 78 74 20 63 6f  into the text co
80e0: 6c 75 6d 6e 73 20 61 73 20 70 61 72 74 20 6f 66  lumns as part of
80f0: 20 61 20 27 64 65 6c 65 74 65 27 0a 63 6f 6d 6d   a 'delete'.comm
8100: 61 6e 64 20 61 72 65 20 6e 6f 74 20 74 68 65 20  and are not the 
8110: 73 61 6d 65 20 61 73 20 74 68 6f 73 65 20 63 75  same as those cu
8120: 72 72 65 6e 74 6c 79 20 73 74 6f 72 65 64 20 77  rrently stored w
8130: 69 74 68 69 6e 20 74 68 65 20 74 61 62 6c 65 2c  ithin the table,
8140: 20 74 68 65 0a 72 65 73 75 6c 74 73 20 6d 61 79   the.results may
8150: 20 62 65 20 75 6e 70 72 65 64 69 63 74 61 62 6c   be unpredictabl
8160: 65 2e 0a 0a 3c 70 3e 3c 69 20 73 74 79 6c 65 3d  e...<p><i style=
8170: 63 6f 6c 6f 72 3a 72 65 64 3e 74 6f 64 6f 3a 20  color:red>todo: 
8180: 65 78 70 6c 61 69 6e 20 77 68 79 3c 2f 69 3e 0a  explain why</i>.
8190: 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53 35 20  .<h2 tags="FTS5 
81a0: 64 65 6c 65 74 65 2d 61 6c 6c 20 63 6f 6d 6d 61  delete-all comma
81b0: 6e 64 22 3e 54 68 65 20 27 64 65 6c 65 74 65 2d  nd">The 'delete-
81c0: 61 6c 6c 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32  all' Command</h2
81d0: 3e 0a 0a 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d  >..<p> This comm
81e0: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
81f0: 6c 61 62 6c 65 20 77 69 74 68 20 5b 46 54 53 35  lable with [FTS5
8200: 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74 65 6e   external conten
8210: 74 20 74 61 62 6c 65 73 20 7c 0a 65 78 74 65 72  t tables |.exter
8220: 6e 61 6c 20 63 6f 6e 74 65 6e 74 5d 20 61 6e 64  nal content] and
8230: 20 5b 46 54 53 35 20 63 6f 6e 74 65 6e 74 6c 65   [FTS5 contentle
8240: 73 73 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e 74  ss tables | cont
8250: 65 6e 74 6c 65 73 73 5d 20 74 61 62 6c 65 73 2e  entless] tables.
8260: 20 49 74 0a 64 65 6c 65 74 65 73 20 61 6c 6c 20   It.deletes all 
8270: 65 6e 74 72 69 65 73 20 66 72 6f 6d 20 74 68 65  entries from the
8280: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
8290: 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  ...<codeblock>. 
82a0: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28   INSERT INTO ft(
82b0: 66 74 29 20 56 41 4c 55 45 53 28 27 64 65 6c 65  ft) VALUES('dele
82c0: 74 65 2d 61 6c 6c 27 29 3b 0a 3c 2f 63 6f 64 65  te-all');.</code
82d0: 62 6c 6f 63 6b 3e 0a 0a 3c 68 32 3e 54 68 65 20  block>..<h2>The 
82e0: 27 69 6e 74 65 67 72 69 74 79 2d 63 68 65 63 6b  'integrity-check
82f0: 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a 0a  ' Command</h2>..
8300: 3c 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64  <p> This command
8310: 20 69 73 20 75 73 65 64 20 74 6f 20 76 65 72 69   is used to veri
8320: 66 79 20 74 68 61 74 20 74 68 65 20 66 75 6c 6c  fy that the full
8330: 2d 74 65 78 74 20 69 6e 64 65 78 20 69 73 20 63  -text index is c
8340: 6f 6e 73 69 73 74 65 6e 74 20 0a 77 69 74 68 20  onsistent .with 
8350: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
8360: 74 68 65 20 46 54 53 35 20 74 61 62 6c 65 20 6f  the FTS5 table o
8370: 72 20 5b 46 54 53 35 20 65 78 74 65 72 6e 61 6c  r [FTS5 external
8380: 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65 73 20   content tables 
8390: 7c 20 63 6f 6e 74 65 6e 74 20 0a 74 61 62 6c 65  | content .table
83a0: 5d 2e 20 49 74 20 69 73 20 6e 6f 74 20 61 76 61  ]. It is not ava
83b0: 69 6c 61 62 6c 65 20 77 69 74 68 20 5b 46 54 53  ilable with [FTS
83c0: 35 20 63 6f 6e 74 65 6e 74 6c 65 73 73 20 74 61  5 contentless ta
83d0: 62 6c 65 73 20 7c 20 63 6f 6e 74 65 6e 74 6c 65  bles | contentle
83e0: 73 73 20 74 61 62 6c 65 73 5d 2e 0a 0a 3c 70 3e  ss tables]...<p>
83f0: 54 68 65 20 69 6e 74 65 67 72 69 74 79 2d 63 68  The integrity-ch
8400: 65 63 6b 20 63 6f 6d 6d 61 6e 64 20 69 73 20 69  eck command is i
8410: 6e 76 6f 6b 65 64 20 62 79 20 69 6e 73 65 72 74  nvoked by insert
8420: 69 6e 67 20 74 68 65 20 74 65 78 74 20 76 61 6c  ing the text val
8430: 75 65 0a 27 69 6e 74 65 67 72 69 74 79 2d 63 68  ue.'integrity-ch
8440: 65 63 6b 27 20 69 6e 74 6f 20 74 68 65 20 73 70  eck' into the sp
8450: 65 63 69 61 6c 20 63 6f 6c 75 6d 6e 20 77 69 74  ecial column wit
8460: 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
8470: 61 73 20 74 68 65 20 46 54 53 35 0a 74 61 62 6c  as the FTS5.tabl
8480: 65 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a  e. For example:.
8490: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 49  .<codeblock>.  I
84a0: 4e 53 45 52 54 20 49 4e 54 4f 20 66 74 28 66 74  NSERT INTO ft(ft
84b0: 29 20 56 41 4c 55 45 53 28 27 69 6e 74 65 67 72  ) VALUES('integr
84c0: 69 74 79 2d 63 68 65 63 6b 27 29 3b 0a 3c 2f 63  ity-check');.</c
84d0: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 66  odeblock>..<p>If
84e0: 20 74 68 65 20 66 75 6c 6c 2d 74 65 78 74 20 69   the full-text i
84f0: 6e 64 65 78 20 69 73 20 63 6f 6e 73 69 73 74 65  ndex is consiste
8500: 6e 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  nt with the cont
8510: 65 6e 74 73 20 6f 66 20 74 68 65 20 74 61 62 6c  ents of the tabl
8520: 65 2c 20 74 68 65 0a 49 4e 53 45 52 54 20 75 73  e, the.INSERT us
8530: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  ed to invoke the
8540: 20 69 6e 74 65 67 72 69 74 79 2d 63 68 65 63 6b   integrity-check
8550: 20 63 6f 6d 6d 61 6e 64 20 73 75 63 63 65 65 64   command succeed
8560: 73 2e 20 4f 72 2c 20 69 66 20 61 6e 79 0a 64 69  s. Or, if any.di
8570: 73 63 72 65 70 61 6e 63 79 20 69 73 20 66 6f 75  screpancy is fou
8580: 6e 64 2c 20 69 74 20 66 61 69 6c 73 20 77 69 74  nd, it fails wit
8590: 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 52  h an [SQLITE_COR
85a0: 52 55 50 54 5f 56 54 41 42 5d 20 65 72 72 6f 72  RUPT_VTAB] error
85b0: 2e 0a 0a 3c 68 32 20 74 61 67 73 3d 22 46 54 53  ...<h2 tags="FTS
85c0: 35 20 6f 70 74 69 6d 69 7a 65 20 63 6f 6d 6d 61  5 optimize comma
85d0: 6e 64 22 3e 54 68 65 20 27 6f 70 74 69 6d 69 7a  nd">The 'optimiz
85e0: 65 27 20 43 6f 6d 6d 61 6e 64 3c 2f 68 32 3e 0a  e' Command</h2>.
85f0: 0a 3c 70 3e 54 68 69 73 20 63 6f 6d 6d 61 6e 64  .<p>This command
8600: 20 6d 65 72 67 65 73 20 61 6c 6c 20 69 6e 64 69   merges all indi
8610: 76 69 64 75 61 6c 20 62 2d 74 72 65 65 73 20 74  vidual b-trees t
8620: 68 61 74 20 63 75 72 72 65 6e 74 6c 79 20 6d 61  hat currently ma
8630: 6b 65 20 75 70 20 74 68 65 0a 66 75 6c 6c 2d 74  ke up the.full-t
8640: 65 78 74 20 69 6e 64 65 78 20 69 6e 74 6f 20 61  ext index into a
8650: 20 73 69 6e 67 6c 65 20 6c 61 72 67 65 20 62 2d   single large b-
8660: 74 72 65 65 20 73 74 72 75 63 74 75 72 65 2e 20  tree structure. 
8670: 54 68 69 73 20 65 6e 73 75 72 65 73 20 74 68 61  This ensures tha
8680: 74 20 74 68 65 0a 66 75 6c 6c 2d 74 65 78 74 20  t the.full-text 
8690: 69 6e 64 65 78 20 63 6f 6e 73 75 6d 65 73 20 74  index consumes t
86a0: 68 65 20 6d 69 6d 69 6d 75 6d 20 73 70 61 63 65  he mimimum space
86b0: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
86c0: 62 61 73 65 20 61 6e 64 20 69 73 20 69 6e 20 74  base and is in t
86d0: 68 65 0a 66 61 73 74 65 73 74 20 66 6f 72 6d 20  he.fastest form 
86e0: 74 6f 20 71 75 65 72 79 2e 0a 0a 3c 70 3e 52 65  to query...<p>Re
86f0: 66 65 72 20 74 6f 20 74 68 65 20 64 6f 63 75 6d  fer to the docum
8700: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  entation for the
8710: 20 5b 46 54 53 35 20 61 75 74 6f 6d 65 72 67 65   [FTS5 automerge
8720: 20 6f 70 74 69 6f 6e 5d 20 66 6f 72 20 6d 6f 72   option] for mor
8730: 65 20 64 65 74 61 69 6c 73 0a 72 65 67 61 72 64  e details.regard
8740: 69 6e 67 20 74 68 65 20 72 65 6c 61 74 69 6f 6e  ing the relation
8750: 73 68 69 70 20 62 65 74 77 65 65 6e 20 74 68 65  ship between the
8760: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
8770: 20 61 6e 64 20 69 74 73 20 63 6f 6d 70 6f 6e 65   and its compone
8780: 6e 74 0a 62 2d 74 72 65 65 73 2e 0a 0a 3c 63 6f  nt.b-trees...<co
8790: 64 65 62 6c 6f 63 6b 3e 0a 20 20 49 4e 53 45 52  deblock>.  INSER
87a0: 54 20 49 4e 54 4f 20 66 74 28 66 74 29 20 56 41  T INTO ft(ft) VA
87b0: 4c 55 45 53 28 27 6f 70 74 69 6d 69 7a 65 27 29  LUES('optimize')
87c0: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
87d0: 3c 68 32 3e 54 68 65 20 27 70 67 73 7a 27 20 43  <h2>The 'pgsz' C
87e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
87f0: 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68  ion</h2>..<p> Th
8800: 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 75 73  is command is us
8810: 65 64 20 74 6f 20 73 65 74 20 74 68 65 20 70 65  ed to set the pe
8820: 72 73 69 73 74 65 6e 74 20 22 70 67 73 7a 22 20  rsistent "pgsz" 
8830: 6f 70 74 69 6f 6e 2e 0a 0a 3c 70 3e 20 54 68 65  option...<p> The
8840: 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78   full-text index
8850: 20 6d 61 69 6e 74 61 69 6e 65 64 20 62 79 20 46   maintained by F
8860: 54 53 35 20 69 73 20 73 74 6f 72 65 64 20 61 73  TS5 is stored as
8870: 20 61 20 73 65 72 69 65 73 20 6f 66 20 66 69 78   a series of fix
8880: 65 64 2d 73 69 7a 65 0a 62 6c 6f 62 73 20 69 6e  ed-size.blobs in
8890: 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
88a0: 65 2e 20 49 74 20 69 73 20 6e 6f 74 20 73 74 72  e. It is not str
88b0: 69 63 74 6c 79 20 6e 65 63 65 73 73 61 72 79 20  ictly necessary 
88c0: 66 6f 72 20 61 6c 6c 20 62 6c 6f 62 73 20 74 68  for all blobs th
88d0: 61 74 20 6d 61 6b 65 0a 75 70 20 61 20 66 75 6c  at make.up a ful
88e0: 6c 2d 74 65 78 74 20 69 6e 64 65 78 20 74 6f 20  l-text index to 
88f0: 62 65 20 74 68 65 20 73 61 6d 65 20 73 69 7a 65  be the same size
8900: 2e 20 54 68 65 20 70 67 73 7a 20 6f 70 74 69 6f  . The pgsz optio
8910: 6e 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  n determines the
8920: 20 73 69 7a 65 0a 6f 66 20 61 6c 6c 20 62 6c 6f   size.of all blo
8930: 62 73 20 63 72 65 61 74 65 64 20 62 79 20 73 75  bs created by su
8940: 62 73 65 71 75 65 6e 74 20 69 6e 64 65 78 20 77  bsequent index w
8950: 72 69 74 65 72 73 2e 20 54 68 65 20 64 65 66 61  riters. The defa
8960: 75 6c 74 20 76 61 6c 75 65 20 69 73 20 31 30 30  ult value is 100
8970: 30 2e 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  0...<codeblock>.
8980: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 66 74    INSERT INTO ft
8990: 28 66 74 2c 20 72 61 6e 6b 29 20 56 41 4c 55 45  (ft, rank) VALUE
89a0: 53 28 27 70 67 73 7a 27 2c 20 34 30 37 32 29 3b  S('pgsz', 4072);
89b0: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
89c0: 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 72 61  h2 tags="FTS5 ra
89d0: 6e 6b 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  nk configuration
89e0: 20 6f 70 74 69 6f 6e 22 3e 54 68 65 20 27 72 61   option">The 'ra
89f0: 6e 6b 27 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  nk' Configuratio
8a00: 6e 20 4f 70 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c  n Option</h2>..<
8a10: 70 3e 20 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20  p> This command 
8a20: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 74  is used to set t
8a30: 68 65 20 70 65 72 73 69 73 74 65 6e 74 20 22 72  he persistent "r
8a40: 61 6e 6b 22 20 6f 70 74 69 6f 6e 2e 0a 0a 3c 70  ank" option...<p
8a50: 3e 20 54 68 65 20 72 61 6e 6b 20 6f 70 74 69 6f  > The rank optio
8a60: 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61  n is used to cha
8a70: 6e 67 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  nge the default 
8a80: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
8a90: 6f 6e 20 6d 61 70 70 69 6e 67 0a 66 6f 72 20 74  on mapping.for t
8aa0: 68 65 20 72 61 6e 6b 20 63 6f 6c 75 6d 6e 2e 20  he rank column. 
8ab0: 54 68 65 20 6f 70 74 69 6f 6e 20 73 68 6f 75 6c  The option shoul
8ac0: 64 20 62 65 20 73 65 74 20 74 6f 20 61 20 74 65  d be set to a te
8ad0: 78 74 20 76 61 6c 75 65 20 69 6e 20 74 68 65 20  xt value in the 
8ae0: 73 61 6d 65 0a 66 6f 72 6d 61 74 20 61 73 20 64  same.format as d
8af0: 65 73 63 72 69 62 65 64 20 66 6f 72 20 5b 61 75  escribed for [au
8b00: 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e  xiliary function
8b10: 20 6d 61 70 70 69 6e 67 20 7c 20 22 72 61 6e 6b   mapping | "rank
8b20: 20 4d 41 54 43 48 20 3f 22 5d 20 74 65 72 6d 73   MATCH ?"] terms
8b30: 20 0a 61 62 6f 76 65 2e 20 46 6f 72 20 65 78 61   .above. For exa
8b40: 6d 70 6c 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  mple:..<codebloc
8b50: 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  k>.  INSERT INTO
8b60: 20 66 74 28 66 74 2c 20 72 61 6e 6b 29 20 56 41   ft(ft, rank) VA
8b70: 4c 55 45 53 28 27 72 61 6e 6b 27 2c 20 27 62 6d  LUES('rank', 'bm
8b80: 32 35 28 31 30 2e 30 2c 20 35 2e 30 29 27 29 3b  25(10.0, 5.0)');
8b90: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
8ba0: 68 32 20 74 61 67 73 3d 22 46 54 53 35 20 72 65  h2 tags="FTS5 re
8bb0: 62 75 69 6c 64 20 63 6f 6d 6d 61 6e 64 22 3e 54  build command">T
8bc0: 68 65 20 27 72 65 62 75 69 6c 64 27 20 43 6f 6d  he 'rebuild' Com
8bd0: 6d 61 6e 64 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54  mand</h2>..<p> T
8be0: 68 69 73 20 63 6f 6d 6d 61 6e 64 20 66 69 72 73  his command firs
8bf0: 74 20 64 65 6c 65 74 65 73 20 74 68 65 20 65 6e  t deletes the en
8c00: 74 69 72 65 20 66 75 6c 6c 2d 74 65 78 74 20 69  tire full-text i
8c10: 6e 64 65 78 2c 20 74 68 65 6e 20 72 65 62 75 69  ndex, then rebui
8c20: 6c 64 73 20 69 74 0a 62 61 73 65 64 20 6f 6e 20  lds it.based on 
8c30: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
8c40: 74 68 65 20 74 61 62 6c 65 20 6f 72 20 5b 46 54  the table or [FT
8c50: 53 35 20 65 78 74 65 72 6e 61 6c 20 63 6f 6e 74  S5 external cont
8c60: 65 6e 74 20 74 61 62 6c 65 73 20 7c 20 63 6f 6e  ent tables | con
8c70: 74 65 6e 74 0a 74 61 62 6c 65 5d 2e 20 20 49 74  tent.table].  It
8c80: 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
8c90: 65 20 77 69 74 68 20 5b 46 54 53 35 20 63 6f 6e  e with [FTS5 con
8ca0: 74 65 6e 74 6c 65 73 73 20 74 61 62 6c 65 73 20  tentless tables 
8cb0: 7c 20 63 6f 6e 74 65 6e 74 6c 65 73 73 0a 74 61  | contentless.ta
8cc0: 62 6c 65 73 5d 2e 0a 0a 3c 63 6f 64 65 62 6c 6f  bles]...<codeblo
8cd0: 63 6b 3e 0a 20 20 49 4e 53 45 52 54 20 49 4e 54  ck>.  INSERT INT
8ce0: 4f 20 66 74 28 66 74 29 20 56 41 4c 55 45 53 28  O ft(ft) VALUES(
8cf0: 27 72 65 62 75 69 6c 64 27 29 3b 0a 3c 2f 63 6f  'rebuild');.</co
8d00: 64 65 62 6c 6f 63 6b 3e 0a 0a 0a 3c 68 31 3e 45  deblock>...<h1>E
8d10: 78 74 65 6e 64 69 6e 67 20 46 54 53 35 3c 2f 68  xtending FTS5</h
8d20: 31 3e 0a 0a 3c 70 3e 46 54 53 35 20 66 65 61 74  1>..<p>FTS5 feat
8d30: 75 72 65 73 20 41 50 49 73 20 61 6c 6c 6f 77 69  ures APIs allowi
8d40: 6e 67 20 69 74 20 74 6f 20 62 65 20 65 78 74 65  ng it to be exte
8d50: 6e 64 65 64 20 62 79 3a 0a 0a 3c 75 6c 3e 0a 20  nded by:..<ul>. 
8d60: 20 3c 6c 69 3e 20 41 64 64 69 6e 67 20 6e 65 77   <li> Adding new
8d70: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
8d80: 69 6f 6e 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  ions implemented
8d90: 20 69 6e 20 43 2c 20 61 6e 64 0a 20 20 3c 6c 69   in C, and.  <li
8da0: 3e 20 41 64 64 69 6e 67 20 6e 65 77 20 74 6f 6b  > Adding new tok
8db0: 65 6e 69 7a 65 72 73 2c 20 61 6c 73 6f 20 69 6d  enizers, also im
8dc0: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43 2e 0a  plemented in C..
8dd0: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 54 68 65 20 62  </ul>..<p> The b
8de0: 75 69 6c 74 2d 69 6e 20 74 6f 6b 65 6e 69 7a 65  uilt-in tokenize
8df0: 72 73 20 61 6e 64 20 61 75 78 69 6c 69 61 72 79  rs and auxiliary
8e00: 20 66 75 6e 63 74 69 6f 6e 73 20 64 65 73 63 72   functions descr
8e10: 69 62 65 64 20 69 6e 20 74 68 69 73 0a 64 6f 63  ibed in this.doc
8e20: 75 6d 65 6e 74 65 64 20 61 72 65 20 61 6c 6c 20  umented are all 
8e30: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e  implemented usin
8e40: 67 20 74 68 65 20 70 75 62 6c 69 63 6c 79 20 61  g the publicly a
8e50: 76 61 69 6c 61 62 6c 65 20 41 50 49 20 64 65 73  vailable API des
8e60: 63 72 69 62 65 64 0a 62 65 6c 6f 77 2e 0a 0a 3c  cribed.below...<
8e70: 70 3e 20 42 65 66 6f 72 65 20 61 20 6e 65 77 20  p> Before a new 
8e80: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
8e90: 6f 6e 20 6f 72 20 74 6f 6b 65 6e 69 7a 65 72 20  on or tokenizer 
8ea0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
8eb0: 61 79 20 62 65 20 0a 72 65 67 69 73 74 65 72 65  ay be .registere
8ec0: 64 20 77 69 74 68 20 46 54 53 35 2c 20 61 6e 20  d with FTS5, an 
8ed0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
8ee0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
8ef0: 72 20 74 6f 20 74 68 65 20 22 66 74 73 35 5f 61  r to the "fts5_a
8f00: 70 69 22 0a 73 74 72 75 63 74 75 72 65 2e 20 54  pi".structure. T
8f10: 68 65 72 65 20 69 73 20 6f 6e 65 20 66 74 73 35  here is one fts5
8f20: 5f 61 70 69 20 73 74 72 75 63 74 75 72 65 20 66  _api structure f
8f30: 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65  or each database
8f40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 74 68   connection with
8f50: 0a 77 68 69 63 68 20 74 68 65 20 46 54 53 35 20  .which the FTS5 
8f60: 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 72 65 67  extension is reg
8f70: 69 73 74 65 72 65 64 2e 20 54 6f 20 6f 62 74 61  istered. To obta
8f80: 69 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 2c 20  in the pointer, 
8f90: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
8fa0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 53 51 4c 20  invokes the SQL 
8fb0: 75 73 65 72 2d 64 65 66 69 6e 65 64 20 66 75 6e  user-defined fun
8fc0: 63 74 69 6f 6e 20 66 74 73 35 28 29 2c 20 77 68  ction fts5(), wh
8fd0: 69 63 68 20 72 65 74 75 72 6e 73 20 61 20 62 6c  ich returns a bl
8fe0: 6f 62 20 76 61 6c 75 65 0a 63 6f 6e 74 61 69 6e  ob value.contain
8ff0: 69 6e 67 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ing the pointer 
9000: 74 6f 20 74 68 65 20 66 74 73 35 5f 61 70 69 20  to the fts5_api 
9010: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 74 68  structure for th
9020: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
9030: 65 0a 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d  e.following exam
9040: 70 6c 65 20 63 6f 64 65 20 64 65 6d 6f 6e 73 74  ple code demonst
9050: 72 61 74 65 73 20 74 68 65 20 74 65 63 68 6e 69  rates the techni
9060: 71 75 65 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  que:..<codeblock
9070: 3e 0a 20 20 3c 69 3e 2f 2a 0a 20 20 2a 2a 20 52  >.  <i>/*.  ** R
9080: 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
9090: 74 6f 20 74 68 65 20 66 74 73 35 5f 61 70 69 20  to the fts5_api 
90a0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 64 61 74 61  pointer for data
90b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
90c0: 64 62 2e 0a 20 20 2a 2a 20 49 66 20 61 6e 20 65  db..  ** If an e
90d0: 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 72 65 74  rror occurs, ret
90e0: 75 72 6e 20 4e 55 4c 4c 20 61 6e 64 20 6c 65 61  urn NULL and lea
90f0: 76 65 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 74  ve an error in t
9100: 68 65 20 64 61 74 61 62 61 73 65 20 0a 20 20 2a  he database .  *
9110: 2a 20 68 61 6e 64 6c 65 20 28 61 63 63 65 73 73  * handle (access
9120: 69 62 6c 65 20 75 73 69 6e 67 20 73 71 6c 69 74  ible using sqlit
9130: 65 33 5f 65 72 72 63 6f 64 65 28 29 2f 65 72 72  e3_errcode()/err
9140: 6d 73 67 28 29 2e 0a 20 20 2a 2f 3c 2f 69 3e 0a  msg()..  */</i>.
9150: 20 20 66 74 73 35 5f 61 70 69 20 2a 66 74 73 35    fts5_api *fts5
9160: 5f 61 70 69 5f 66 72 6f 6d 5f 64 62 28 73 71 6c  _api_from_db(sql
9170: 69 74 65 33 20 2a 64 62 29 7b 0a 20 20 20 20 66  ite3 *db){.    f
9180: 74 73 35 5f 61 70 69 20 2a 70 52 65 74 20 3d 20  ts5_api *pRet = 
9190: 30 3b 0a 20 20 20 20 73 71 6c 69 74 65 33 5f 73  0;.    sqlite3_s
91a0: 74 6d 74 20 2a 70 53 74 6d 74 20 3d 20 30 3b 0a  tmt *pStmt = 0;.
91b0: 0a 20 20 20 20 69 66 28 20 53 51 4c 49 54 45 5f  .    if( SQLITE_
91c0: 4f 4b 3d 3d 73 71 6c 69 74 65 33 5f 70 72 65 70  OK==sqlite3_prep
91d0: 61 72 65 28 64 62 2c 20 22 53 45 4c 45 43 54 20  are(db, "SELECT 
91e0: 66 74 73 35 28 29 22 2c 20 2d 31 2c 20 26 70 53  fts5()", -1, &pS
91f0: 74 6d 74 2c 20 30 29 0a 20 20 20 20 20 26 26 20  tmt, 0).     && 
9200: 53 51 4c 49 54 45 5f 52 4f 57 3d 3d 73 71 6c 69  SQLITE_ROW==sqli
9210: 74 65 33 5f 73 74 65 70 28 70 53 74 6d 74 29 20  te3_step(pStmt) 
9220: 0a 20 20 20 20 20 26 26 20 73 69 7a 65 6f 66 28  .     && sizeof(
9230: 70 52 65 74 29 3d 3d 73 71 6c 69 74 65 33 5f 63  pRet)==sqlite3_c
9240: 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 70 53 74 6d  olumn_bytes(pStm
9250: 74 2c 20 30 29 0a 20 20 20 20 29 7b 0a 20 20 20  t, 0).    ){.   
9260: 20 20 20 6d 65 6d 63 70 79 28 26 70 52 65 74 2c     memcpy(&pRet,
9270: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
9280: 62 6c 6f 62 28 70 53 74 6d 74 2c 20 30 29 2c 20  blob(pStmt, 0), 
9290: 73 69 7a 65 6f 66 28 70 52 65 74 29 29 3b 0a 20  sizeof(pRet));. 
92a0: 20 20 20 7d 0a 20 20 20 20 73 71 6c 69 74 65 33     }.    sqlite3
92b0: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
92c0: 3b 0a 20 20 20 20 72 65 74 75 72 6e 20 70 52 65  ;.    return pRe
92d0: 74 3b 0a 20 20 7d 0a 3c 2f 63 6f 64 65 62 6c 6f  t;.  }.</codeblo
92e0: 63 6b 3e 0a 0a 3c 70 3e 20 54 68 65 20 66 74 73  ck>..<p> The fts
92f0: 35 5f 61 70 69 20 73 74 72 75 63 74 75 72 65 20  5_api structure 
9300: 69 73 20 64 65 66 69 6e 65 64 20 61 73 20 66 6f  is defined as fo
9310: 6c 6c 6f 77 73 2e 20 49 74 20 65 78 70 6f 73 65  llows. It expose
9320: 73 20 74 68 72 65 65 20 6d 65 74 68 6f 64 73 2c  s three methods,
9330: 20 0a 6f 6e 65 20 65 61 63 68 20 66 6f 72 20 72   .one each for r
9340: 65 67 69 73 74 65 72 69 6e 67 20 6e 65 77 20 61  egistering new a
9350: 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f  uxiliary functio
9360: 6e 73 20 61 6e 64 20 74 6f 6b 65 6e 69 7a 65 72  ns and tokenizer
9370: 73 2c 20 61 6e 64 20 6f 6e 65 20 66 6f 72 0a 72  s, and one for.r
9380: 65 74 72 69 65 76 69 6e 67 20 65 78 69 73 74 69  etrieving existi
9390: 6e 67 20 74 6f 6b 65 6e 69 7a 65 72 2e 20 54 68  ng tokenizer. Th
93a0: 65 20 6c 61 74 74 65 72 20 69 73 20 69 6e 74 65  e latter is inte
93b0: 6e 64 65 64 20 74 6f 20 66 61 63 69 6c 69 74 61  nded to facilita
93c0: 74 65 20 74 68 65 0a 69 6d 70 6c 65 6d 65 6e 74  te the.implement
93d0: 61 74 69 6f 6e 20 6f 66 20 22 74 6f 6b 65 6e 69  ation of "tokeni
93e0: 7a 65 72 20 77 72 61 70 70 65 72 73 22 20 73 69  zer wrappers" si
93f0: 6d 69 6c 61 72 20 74 6f 20 74 68 65 20 62 75 69  milar to the bui
9400: 6c 74 2d 69 6e 0a 70 6f 72 74 65 72 20 74 6f 6b  lt-in.porter tok
9410: 65 6e 69 7a 65 72 2e 0a 0a 3c 63 6f 64 65 62 6c  enizer...<codebl
9420: 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72 69 70 74 3e  ock>.<tclscript>
9430: 0a 20 20 73 65 74 20 72 65 73 20 22 22 0a 20 20  .  set res "".  
9440: 73 65 74 20 3a 3a 65 78 74 72 61 63 74 5f 61 70  set ::extract_ap
9450: 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 66 74 73 35  i_docs_mode fts5
9460: 5f 61 70 69 0a 20 20 63 61 74 63 68 20 7b 20 73  _api.  catch { s
9470: 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65 20 5b  et res [source [
9480: 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43  file join $::SRC
9490: 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72 61 63   ext/fts5/extrac
94a0: 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d  t_api_docs.tcl]]
94b0: 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f 74   }.  set res.</t
94c0: 63 6c 73 63 72 69 70 74 3e 0a 3c 2f 63 6f 64 65  clscript>.</code
94d0: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 20 54 6f 20 69  block>..<p> To i
94e0: 6e 76 6f 6b 65 20 61 20 6d 65 74 68 6f 64 20 6f  nvoke a method o
94f0: 66 20 74 68 65 20 66 74 73 35 5f 61 70 69 20 6f  f the fts5_api o
9500: 62 6a 65 63 74 2c 20 74 68 65 20 66 74 73 35 5f  bject, the fts5_
9510: 61 70 69 20 70 6f 69 6e 74 65 72 20 69 74 73 65  api pointer itse
9520: 6c 66 0a 73 68 6f 75 6c 64 20 62 65 20 70 61 73  lf.should be pas
9530: 73 65 64 20 61 73 20 74 68 65 20 6d 65 74 68 6f  sed as the metho
9540: 64 73 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ds first argumen
9550: 74 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 74 68  t followed by th
9560: 65 20 6f 74 68 65 72 2c 20 6d 65 74 68 6f 64 0a  e other, method.
9570: 73 70 65 63 69 66 69 63 2c 20 61 72 67 75 6d 65  specific, argume
9580: 6e 74 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  nts. For example
9590: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20  :..<codeblock>. 
95a0: 20 20 20 72 63 20 3d 20 70 46 74 73 35 41 70 69     rc = pFts5Api
95b0: 2d 3e 78 43 72 65 61 74 65 54 6f 6b 65 6e 69 7a  ->xCreateTokeniz
95c0: 65 72 28 70 46 74 73 35 41 70 69 2c 20 2e 2e 2e  er(pFts5Api, ...
95d0: 20 6f 74 68 65 72 20 61 72 67 73 20 2e 2e 2e 29   other args ...)
95e0: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
95f0: 3c 70 3e 20 54 68 65 20 66 74 73 35 5f 61 70 69  <p> The fts5_api
9600: 20 73 74 72 75 63 74 75 72 65 20 6d 65 74 68 6f   structure metho
9610: 64 73 20 61 72 65 20 64 65 73 63 72 69 62 65 64  ds are described
9620: 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 69 6e   individually in
9630: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 73   the following.s
9640: 65 63 74 69 6f 6e 73 2e 0a 0a 3c 68 32 20 74 61  ections...<h2 ta
9650: 67 73 3d 22 63 75 73 74 6f 6d 20 74 6f 6b 65 6e  gs="custom token
9660: 69 7a 65 72 73 22 3e 43 75 73 74 6f 6d 20 54 6f  izers">Custom To
9670: 6b 65 6e 69 7a 65 72 73 3c 2f 68 32 3e 0a 0a 3c  kenizers</h2>..<
9680: 70 3e 20 54 6f 20 63 72 65 61 74 65 20 61 20 63  p> To create a c
9690: 75 73 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65 72 2c  ustom tokenizer,
96a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
96b0: 6d 75 73 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  must implement t
96c0: 68 72 65 65 0a 66 75 6e 63 74 69 6f 6e 73 3a 20  hree.functions: 
96d0: 61 20 74 6f 6b 65 6e 69 7a 65 72 20 63 6f 6e 73  a tokenizer cons
96e0: 74 72 75 63 74 6f 72 20 28 78 43 72 65 61 74 65  tructor (xCreate
96f0: 29 2c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ), a destructor 
9700: 28 78 44 65 6c 65 74 65 29 20 61 6e 64 20 61 0a  (xDelete) and a.
9710: 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 6f 20 74  function to do t
9720: 68 65 20 61 63 74 75 61 6c 20 74 6f 6b 65 6e 69  he actual tokeni
9730: 7a 61 74 69 6f 6e 20 28 78 54 6f 6b 65 6e 69 7a  zation (xTokeniz
9740: 65 29 2e 20 54 68 65 20 74 79 70 65 20 6f 66 20  e). The type of 
9750: 65 61 63 68 0a 66 75 6e 63 74 69 6f 6e 20 69 73  each.function is
9760: 20 61 73 20 66 6f 72 20 74 68 65 20 6d 65 6d 62   as for the memb
9770: 65 72 20 76 61 72 69 61 62 6c 65 73 20 6f 66 20  er variables of 
9780: 74 68 65 20 66 74 73 35 5f 74 6f 6b 65 6e 69 7a  the fts5_tokeniz
9790: 65 72 20 73 74 72 75 63 74 3a 0a 0a 3c 63 6f 64  er struct:..<cod
97a0: 65 62 6c 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72 69  eblock>.<tclscri
97b0: 70 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22 22  pt>.  set res ""
97c0: 0a 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63 74  .  set ::extract
97d0: 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 66  _api_docs_mode f
97e0: 74 73 35 5f 74 6f 6b 65 6e 69 7a 65 72 0a 20 20  ts5_tokenizer.  
97f0: 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20  catch { set res 
9800: 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f  [source [file jo
9810: 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74  in $::SRC ext/ft
9820: 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64  s5/extract_api_d
9830: 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65  ocs.tcl]] }.  se
9840: 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70  t res.</tclscrip
9850: 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t>.</codeblock>.
9860: 0a 3c 70 3e 20 57 68 65 6e 20 61 6e 20 46 54 53  .<p> When an FTS
9870: 35 20 74 61 62 6c 65 20 75 73 65 73 20 74 68 65  5 table uses the
9880: 20 63 75 73 74 6f 6d 20 74 6f 6b 65 6e 69 7a 65   custom tokenize
9890: 72 2c 20 74 68 65 20 46 54 53 35 20 63 6f 72 65  r, the FTS5 core
98a0: 20 63 61 6c 6c 73 20 78 43 72 65 61 74 65 28 29   calls xCreate()
98b0: 0a 6f 6e 63 65 20 74 6f 20 63 72 65 61 74 65 20  .once to create 
98c0: 61 20 74 6f 6b 65 6e 69 7a 65 72 2c 20 74 68 65  a tokenizer, the
98d0: 6e 20 78 54 6f 6b 65 6e 69 7a 65 28 29 20 7a 65  n xTokenize() ze
98e0: 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
98f0: 20 74 6f 20 74 6f 6b 65 6e 69 7a 65 0a 73 74 72   to tokenize.str
9900: 69 6e 67 73 2c 20 74 68 65 6e 20 78 44 65 6c 65  ings, then xDele
9910: 74 65 28 29 20 74 6f 20 66 72 65 65 20 61 6e 79  te() to free any
9920: 20 72 65 73 6f 75 72 63 65 73 20 61 6c 6c 6f 63   resources alloc
9930: 61 74 65 64 20 62 79 20 78 43 72 65 61 74 65 28  ated by xCreate(
9940: 29 2e 20 4d 6f 72 65 0a 73 70 65 63 69 66 69 63  ). More.specific
9950: 61 6c 6c 79 3a 0a 0a 3c 74 63 6c 73 63 72 69 70  ally:..<tclscrip
9960: 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22 22 0a  t>.  set res "".
9970: 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63 74 5f    set ::extract_
9980: 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 74 6f  api_docs_mode to
9990: 6b 65 6e 69 7a 65 72 5f 61 70 69 0a 20 20 63 61  kenizer_api.  ca
99a0: 74 63 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73  tch { set res [s
99b0: 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e  ource [file join
99c0: 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35   $::SRC ext/fts5
99d0: 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63  /extract_api_doc
99e0: 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20  s.tcl]] }.  set 
99f0: 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e  res.</tclscript>
9a00: 0a 0a 3c 68 32 3e 43 75 73 74 6f 6d 20 41 75 78  ..<h2>Custom Aux
9a10: 69 6c 69 61 72 79 20 46 75 6e 63 74 69 6f 6e 73  iliary Functions
9a20: 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 49 6d 70 6c 65  </h2>..<p> Imple
9a30: 6d 65 6e 74 69 6e 67 20 61 20 63 75 73 74 6f 6d  menting a custom
9a40: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
9a50: 69 6f 6e 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ion is similar t
9a60: 6f 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 61  o implementing a
9a70: 6e 0a 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  n.[application-d
9a80: 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
9a90: 69 6f 6e 20 7c 20 73 63 61 6c 61 72 20 53 51 4c  ion | scalar SQL
9aa0: 20 66 75 6e 63 74 69 6f 6e 5d 2e 20 54 68 65 20   function]. The 
9ab0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 73  implementation.s
9ac0: 68 6f 75 6c 64 20 62 65 20 61 20 43 20 66 75 6e  hould be a C fun
9ad0: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 66 74  ction of type ft
9ae0: 73 35 5f 65 78 74 65 6e 73 69 6f 6e 5f 66 75 6e  s5_extension_fun
9af0: 63 74 69 6f 6e 2c 20 64 65 66 69 6e 65 64 20 61  ction, defined a
9b00: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64  s follows:..<cod
9b10: 65 62 6c 6f 63 6b 3e 0a 3c 74 63 6c 73 63 72 69  eblock>.<tclscri
9b20: 70 74 3e 0a 20 20 73 65 74 20 72 65 73 20 22 22  pt>.  set res ""
9b30: 0a 20 20 73 65 74 20 3a 3a 65 78 74 72 61 63 74  .  set ::extract
9b40: 5f 61 70 69 5f 64 6f 63 73 5f 6d 6f 64 65 20 66  _api_docs_mode f
9b50: 74 73 35 5f 65 78 74 65 6e 73 69 6f 6e 0a 20 20  ts5_extension.  
9b60: 63 61 74 63 68 20 7b 20 73 65 74 20 72 65 73 20  catch { set res 
9b70: 5b 73 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f  [source [file jo
9b80: 69 6e 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74  in $::SRC ext/ft
9b90: 73 35 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64  s5/extract_api_d
9ba0: 6f 63 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65  ocs.tcl]] }.  se
9bb0: 74 20 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70  t res.</tclscrip
9bc0: 74 3e 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t>.</codeblock>.
9bd0: 0a 3c 70 3e 20 54 68 65 20 69 6d 70 6c 65 6d 65  .<p> The impleme
9be0: 6e 74 61 74 69 6f 6e 20 69 73 20 72 65 67 69 73  ntation is regis
9bf0: 74 65 72 65 64 20 77 69 74 68 20 74 68 65 20 46  tered with the F
9c00: 54 53 35 20 6d 6f 64 75 6c 65 20 62 79 20 63 61  TS5 module by ca
9c10: 6c 6c 69 6e 67 20 74 68 65 0a 78 43 72 65 61 74  lling the.xCreat
9c20: 65 46 75 6e 63 74 69 6f 6e 28 29 20 6d 65 74 68  eFunction() meth
9c30: 6f 64 20 6f 66 20 74 68 65 20 66 74 73 35 5f 61  od of the fts5_a
9c40: 70 69 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68  pi object. If th
9c50: 65 72 65 20 69 73 20 61 6c 72 65 61 64 79 20 61  ere is already a
9c60: 6e 0a 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63  n.auxiliary func
9c70: 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 73 61  tion with the sa
9c80: 6d 65 20 6e 61 6d 65 2c 20 69 74 20 69 73 20 72  me name, it is r
9c90: 65 70 6c 61 63 65 64 20 62 79 20 74 68 65 20 6e  eplaced by the n
9ca0: 65 77 20 66 75 6e 63 74 69 6f 6e 2e 0a 49 66 20  ew function..If 
9cb0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
9cc0: 72 6f 79 20 70 61 72 61 6d 65 74 65 72 20 69 73  roy parameter is
9cd0: 20 70 61 73 73 65 64 20 74 6f 20 78 43 72 65 61   passed to xCrea
9ce0: 74 65 46 75 6e 63 74 69 6f 6e 28 29 2c 20 69 74  teFunction(), it
9cf0: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 77 69 74 68   is invoked.with
9d00: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
9d10: 43 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  Context pointer 
9d20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 6f 6e  passed as the on
9d30: 6c 79 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  ly argument when
9d40: 20 74 68 65 0a 64 61 74 61 62 61 73 65 20 68 61   the.database ha
9d50: 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 6f  ndle is closed o
9d60: 72 20 77 68 65 6e 20 74 68 65 20 72 65 67 69 73  r when the regis
9d70: 74 65 72 65 64 20 61 75 78 69 6c 69 61 72 79 20  tered auxiliary 
9d80: 66 75 6e 63 74 69 6f 6e 20 69 73 0a 72 65 70 6c  function is.repl
9d90: 61 63 65 64 2e 0a 0a 3c 70 3e 20 54 68 65 20 66  aced...<p> The f
9da0: 69 6e 61 6c 20 74 68 72 65 65 20 61 72 67 75 6d  inal three argum
9db0: 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 74  ents passed to t
9dc0: 68 65 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  he auxiliary fun
9dd0: 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 61  ction callback a
9de0: 72 65 0a 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  re.similar to th
9df0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
9e00: 73 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  s passed to the 
9e10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
9e20: 66 20 61 20 73 63 61 6c 61 72 20 53 51 4c 0a 66  f a scalar SQL.f
9e30: 75 6e 63 74 69 6f 6e 2e 20 41 6c 6c 20 61 72 67  unction. All arg
9e40: 75 6d 65 6e 74 73 20 65 78 63 65 70 74 20 74 68  uments except th
9e50: 65 20 66 69 72 73 74 20 70 61 73 73 65 64 20 74  e first passed t
9e60: 6f 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 20  o the auxiliary 
9e70: 66 75 6e 63 74 69 6f 6e 20 61 72 65 0a 61 76 61  function are.ava
9e80: 69 6c 61 62 6c 65 20 74 6f 20 74 68 65 20 69 6d  ilable to the im
9e90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  plementation in 
9ea0: 74 68 65 20 61 70 56 61 6c 26 23 39 31 3b 26 23  the apVal&#91;&#
9eb0: 39 33 3b 20 61 72 72 61 79 2e 20 54 68 65 0a 69  93; array. The.i
9ec0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
9ed0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 61 20 72 65  ould return a re
9ee0: 73 75 6c 74 20 6f 72 20 65 72 72 6f 72 20 76 69  sult or error vi
9ef0: 61 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 68 61  a the content ha
9f00: 6e 64 6c 65 20 70 43 74 78 2e 0a 0a 3c 70 3e 20  ndle pCtx...<p> 
9f10: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
9f20: 6e 74 20 70 61 73 73 65 64 20 74 6f 20 61 6e 20  nt passed to an 
9f30: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
9f40: 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  on callback is a
9f50: 20 70 6f 69 6e 74 65 72 0a 74 6f 20 61 20 73 74   pointer.to a st
9f60: 72 75 63 74 75 72 65 20 63 6f 6e 74 61 69 6e 69  ructure containi
9f70: 6e 67 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20  ng methods that 
9f80: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 69  may be invoked i
9f90: 6e 20 6f 72 64 65 72 20 74 6f 20 6f 62 74 61 69  n order to obtai
9fa0: 6e 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 72 65  n.information re
9fb0: 67 61 72 64 69 6e 67 20 74 68 65 20 63 75 72 72  garding the curr
9fc0: 65 6e 74 20 71 75 65 72 79 20 6f 72 20 72 6f 77  ent query or row
9fd0: 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  . The second arg
9fe0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 6f 70 61 71  ument is an.opaq
9ff0: 75 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 73  ue handle that s
a000: 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
a010: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
a020: 75 6d 65 6e 74 20 74 6f 20 61 6e 79 20 73 75 63  ument to any suc
a030: 68 20 6d 65 74 68 6f 64 20 0a 69 6e 76 6f 63 61  h method .invoca
a040: 74 69 6f 6e 2e 20 46 6f 72 20 65 78 61 6d 70 6c  tion. For exampl
a050: 65 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  e, the following
a060: 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74   auxiliary funct
a070: 69 6f 6e 20 64 65 66 69 6e 69 74 69 6f 6e 20 72  ion definition r
a080: 65 74 75 72 6e 73 0a 74 68 65 20 74 6f 74 61 6c  eturns.the total
a090: 20 6e 75 6d 62 65 72 20 6f 66 20 74 6f 6b 65 6e   number of token
a0a0: 73 20 69 6e 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73  s in all columns
a0b0: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
a0c0: 72 6f 77 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  row:..<codeblock
a0d0: 3e 0a 3c 69 3e 2f 2a 0a 2a 2a 20 49 6d 70 6c 65  >.<i>/*.** Imple
a0e0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
a0f0: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
a100: 6f 6e 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  on that returns 
a110: 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
a120: 20 74 6f 6b 65 6e 73 20 69 6e 20 74 68 65 20 63   tokens in the c
a130: 75 72 72 65 6e 74 20 72 6f 77 20 28 69 6e 63 6c  urrent row (incl
a140: 75 64 69 6e 67 20 61 6c 6c 20 63 6f 6c 75 6d 6e  uding all column
a150: 73 29 2e 0a 2a 2f 3c 2f 69 3e 0a 73 74 61 74 69  s)..*/</i>.stati
a160: 63 20 76 6f 69 64 20 63 6f 6c 75 6d 6e 5f 73 69  c void column_si
a170: 7a 65 5f 69 6d 70 28 0a 20 20 63 6f 6e 73 74 20  ze_imp(.  const 
a180: 46 74 73 35 45 78 74 65 6e 73 69 6f 6e 41 70 69  Fts5ExtensionApi
a190: 20 2a 70 41 70 69 2c 0a 20 20 46 74 73 35 43 6f   *pApi,.  Fts5Co
a1a0: 6e 74 65 78 74 20 2a 70 46 74 73 2c 0a 20 20 73  ntext *pFts,.  s
a1b0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 2a  qlite3_context *
a1c0: 70 43 74 78 2c 0a 20 20 69 6e 74 20 6e 56 61 6c  pCtx,.  int nVal
a1d0: 2c 0a 20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ,.  sqlite3_valu
a1e0: 65 20 2a 2a 61 70 56 61 6c 0a 29 7b 0a 20 20 69  e **apVal.){.  i
a1f0: 6e 74 20 72 63 3b 0a 20 20 69 6e 74 20 6e 54 6f  nt rc;.  int nTo
a200: 6b 65 6e 3b 0a 20 20 72 63 20 3d 20 70 41 70 69  ken;.  rc = pApi
a210: 2d 3e 78 43 6f 6c 75 6d 6e 53 69 7a 65 28 70 46  ->xColumnSize(pF
a220: 74 73 2c 20 2d 31 2c 20 26 6e 54 6f 6b 65 6e 29  ts, -1, &nToken)
a230: 3b 0a 20 20 69 66 28 20 72 63 3d 3d 53 51 4c 49  ;.  if( rc==SQLI
a240: 54 45 5f 4f 4b 20 29 7b 0a 20 20 20 20 73 71 6c  TE_OK ){.    sql
a250: 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
a260: 70 43 74 78 2c 20 6e 54 6f 6b 65 6e 29 3b 0a 20  pCtx, nToken);. 
a270: 20 7d 65 6c 73 65 7b 0a 20 20 20 20 73 71 6c 69   }else{.    sqli
a280: 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
a290: 5f 63 6f 64 65 28 70 43 74 78 2c 20 72 63 29 3b  _code(pCtx, rc);
a2a0: 0a 20 20 7d 0a 7d 0a 3c 2f 63 6f 64 65 62 6c 6f  .  }.}.</codeblo
a2b0: 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 66 6f 6c 6c  ck>..<p>The foll
a2c0: 6f 77 69 6e 67 20 73 65 63 74 69 6f 6e 20 64 65  owing section de
a2d0: 73 63 72 69 62 65 73 20 74 68 65 20 41 50 49 20  scribes the API 
a2e0: 6f 66 66 65 72 65 64 20 74 6f 20 61 75 78 69 6c  offered to auxil
a2f0: 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 0a 69 6d  iary function.im
a300: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 69 6e  plementations in
a310: 20 64 65 74 61 69 6c 2e 20 46 75 72 74 68 65 72   detail. Further
a320: 20 65 78 61 6d 70 6c 65 73 20 6d 61 79 20 62 65   examples may be
a330: 20 66 6f 75 6e 64 20 69 6e 20 74 68 65 20 22 66   found in the "f
a340: 74 73 35 5f 61 75 78 2e 63 22 0a 66 69 6c 65 20  ts5_aux.c".file 
a350: 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f  of the source co
a360: 64 65 2e 0a 0a 3c 68 33 3e 43 75 73 74 6f 6d 20  de...<h3>Custom 
a370: 41 75 78 69 6c 69 61 72 79 20 46 75 6e 63 74 69  Auxiliary Functi
a380: 6f 6e 73 20 41 50 49 20 52 65 66 65 72 65 6e 63  ons API Referenc
a390: 65 3c 2f 68 33 3e 0a 0a 3c 63 6f 64 65 62 6c 6f  e</h3>..<codeblo
a3a0: 63 6b 3e 0a 3c 74 63 6c 73 63 72 69 70 74 3e 0a  ck>.<tclscript>.
a3b0: 20 20 73 65 74 20 72 65 73 20 22 22 0a 20 20 73    set res "".  s
a3c0: 65 74 20 3a 3a 65 78 74 72 61 63 74 5f 61 70 69  et ::extract_api
a3d0: 5f 64 6f 63 73 5f 6d 6f 64 65 20 46 74 73 35 45  _docs_mode Fts5E
a3e0: 78 74 65 6e 73 69 6f 6e 41 70 69 0a 20 20 63 61  xtensionApi.  ca
a3f0: 74 63 68 20 7b 20 73 65 74 20 72 65 73 20 5b 73  tch { set res [s
a400: 6f 75 72 63 65 20 5b 66 69 6c 65 20 6a 6f 69 6e  ource [file join
a410: 20 24 3a 3a 53 52 43 20 65 78 74 2f 66 74 73 35   $::SRC ext/fts5
a420: 2f 65 78 74 72 61 63 74 5f 61 70 69 5f 64 6f 63  /extract_api_doc
a430: 73 2e 74 63 6c 5d 5d 20 7d 0a 20 20 73 65 74 20  s.tcl]] }.  set 
a440: 72 65 73 0a 3c 2f 74 63 6c 73 63 72 69 70 74 3e  res.</tclscript>
a450: 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c  .</codeblock>..<
a460: 74 63 6c 73 63 72 69 70 74 3e 0a 20 20 73 65 74  tclscript>.  set
a470: 20 72 65 73 20 22 22 0a 20 20 75 6e 73 65 74 20   res "".  unset 
a480: 2d 6e 6f 63 6f 6d 70 6c 61 69 6e 20 3a 3a 65 78  -nocomplain ::ex
a490: 74 72 61 63 74 5f 61 70 69 5f 64 6f 63 73 5f 6d  tract_api_docs_m
a4a0: 6f 64 65 20 0a 20 20 63 61 74 63 68 20 7b 20 73  ode .  catch { s
a4b0: 65 74 20 72 65 73 20 5b 73 6f 75 72 63 65 20 5b  et res [source [
a4c0: 66 69 6c 65 20 6a 6f 69 6e 20 24 3a 3a 53 52 43  file join $::SRC
a4d0: 20 65 78 74 2f 66 74 73 35 2f 65 78 74 72 61 63   ext/fts5/extrac
a4e0: 74 5f 61 70 69 5f 64 6f 63 73 2e 74 63 6c 5d 5d  t_api_docs.tcl]]
a4f0: 20 7d 0a 20 20 73 65 74 20 72 65 73 0a 3c 2f 74   }.  set res.</t
a500: 63 6c 73 63 72 69 70 74 3e 0a                    clscript>.