Documentation Source Text

Check-in [004403f6f5]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for the fts5vocab module to fts5.in.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 004403f6f5be8171701e8c25f2d1c7e1415d3346
User & Date: dan 2015-10-19 12:30:19
Context
2015-10-27
17:23
Rework the website menu to add the Purchase link. check-in: 8ba3eb4736 user: drh tags: trunk
2015-10-19
12:30
Add documentation for the fts5vocab module to fts5.in. check-in: 004403f6f5 user: dan tags: trunk
2015-10-16
17:42
Add the sha1sum and SQLITE_SOURCE_ID values for version 3.9.1. check-in: 6113b85fce user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/fts5.in.

1369
1370
1371
1372
1373
1374
1375































































































1376
1377
1378
1379
1380
1381
1382

<tclscript>
  set res ""
  unset -nocomplain ::extract_api_docs_mode 
  catch { set res [source [file join $::SRC ext/fts5/extract_api_docs.tcl]] }
  set res
</tclscript>
































































































<h1 id=appendix_a nonumber tags="comparison with fts4">
  Appendix A: Comparison with FTS3/4
</h1>

<p> Also available is the similar but more mature [fts3 | FTS3/4] module. 
FTS5 is a new version of FTS4 that includes various fixes and solutions for 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477

<tclscript>
  set res ""
  unset -nocomplain ::extract_api_docs_mode 
  catch { set res [source [file join $::SRC ext/fts5/extract_api_docs.tcl]] }
  set res
</tclscript>

<h1>The fts5vocab Virtual Table Module</h1>

<p> The fts5vocab virtual table module allows users to extract information from
an FTS5 full-text index directly. The fts5vocab module is a part of FTS5 - it 
is available whenever FTS5 is.

<p> Each fts5vocab table is associated with a single FTS5 table. An fts5vocab
table is usually created by specifying two arguments in place of column names
in the CREATE VIRTUAL TABLE statement - the name of the associated FTS5 table
and the type of fts5vocab table. Currently there are two types of fts5vocab
table, "row" and "col". Unless the fts5vocab table is created within the "temp"
database, it must be part of the same database as the associated FTS5 table.

<codeblock>
  <i>-- Create an fts5vocab "row" table to query the full-text index belonging
  -- to FTS5 table "ft1".</i>
  CREATE VIRTUAL TABLE ft1_v USING fts5vocab('ft1', 'row');

  <i>-- Create an fts5vocab "col" table to query the full-text index belonging
  -- to FTS5 table "ft2".</i>
  CREATE VIRTUAL TABLE ft2_v USING fts5vocab(ft2, col);
</codeblock>

<p> If an fts5vocab table is created in the temp database, it may be associated
with an FTS5 table in any attached database. In order to attach the fts5vocab
table to an FTS5 table located in a database other than "temp", the name of the
database is inserted before the FTS5 table name in the CREATE VIRTUAL TABLE 
arguments. For example:

<codeblock>
  <i>-- Create an fts5vocab "row" table to query the full-text index belonging
  -- to FTS5 table "ft1" in database "main".</i>
  CREATE VIRTUAL TABLE temp.ft1_v USING fts5vocab(main, 'ft1', 'row');

  <i>-- Create an fts5vocab "col" table to query the full-text index belonging
  -- to FTS5 table "ft2" in attached database "aux".</i>
  CREATE VIRTUAL TABLE temp.ft2_v USING fts5vocab('aux', ft2, col);
</codeblock>

<p> Specifying three arguments when creating an fts5vocab table in any database
other than "temp" results in an error.

<p> An fts5vocab table of type "row" contains one row for each distinct term
in the associated FTS5 table. The table columns are as follows:

<table striped=1>
  <tr><th>Column<th>Contents
  <tr><td>term<td> The term, as stored in the FTS5 index.
  <tr><td>doc<td>  The number of rows that contain at least one instance of the term.
  <tr><td>cnt<td>  The total number of instances of the term in the entire FTS5 table.
</table>

<p> An fts5vocab table of type "col" contains one row for each distinct term/column
combination in the associated FTS5 table. Table columns are as follows:

<table striped=1>
  <tr><th>Column<th>Contents
  <tr><td>term<td> The term, as stored in the FTS5 index.
  <tr><td>col<td>  The name of the FTS5 table column that contains the term.
  <tr><td>doc<td>  The number of rows in the FTS5 table for which column $col
                   contains at least one instance of the term.
  <tr><td>cnt<td>  The total number of instances of the term that appear in
                   column $col of the FTS5 table (considering all rows). 
</table>

<p>Example:

<codeblock>
  <i>-- Assuming a database created using:</i>
  CREATE VIRTUAL TABLE ft1 USING fts5(c1, c2);
  INSERT INTO ft1 VALUES('apple banana cherry', 'banana banana cherry');
  INSERT INTO ft1 VALUES('cherry cherry cherry', 'date date date');

  <i>-- Then querying the following fts5vocab table (type "col") returns:
  --
  --    apple  | c1 | 1 | 1
  --    banana | c1 | 1 | 1
  --    banana | c2 | 1 | 2
  --    cherry | c1 | 2 | 4
  --    cherry | c2 | 1 | 1
  --    date   | c3 | 1 | 3
  --</i>
  CREATE VIRTUAL TABLE ft1_v_col USING fts5vocab(ft1, col);

  <i>-- Querying an fts5vocab table of type "row" returns:
  --
  --    apple  | 1 | 1
  --    banana | 1 | 3
  --    cherry | 2 | 5
  --    date   | 1 | 3
  --</i>
  CREATE VIRTUAL TABLE ft1_v_row USING fts5vocab(ft1, row);
</codeblock>


<h1 id=appendix_a nonumber tags="comparison with fts4">
  Appendix A: Comparison with FTS3/4
</h1>

<p> Also available is the similar but more mature [fts3 | FTS3/4] module. 
FTS5 is a new version of FTS4 that includes various fixes and solutions for