The FTS1 module is the first in a planned series of loadable modules for SQLite that implement Full Text Search. The FTS1 module is available in SQLite version 3.3.8 and later. However, the module will have "permanent beta" status. That is to say, we do not plan to ever officially support it. Even as FTS1 is released, we are already hard at work on a new full-text search module, FTS2, that will have a substantially similar interface but a different on-disk representation and noticably improved performance.
The FTS1 module is appropriate for use in application development. However, we recommend that applications make use of FTS2 or later for deployment. The change from FTS1 to FTS2 will probably involve little more than rebuilding the index. So application development can proceed now using FTS1 and then, with minimal impact, shift over to FTS2 once it module becomes available.
FTS1 can be built either as a standalone shared library, or statically linked into the SQLite library.
To build the module as a shared library, compile all source files in the ext/fts1 subdirectory of the source tree into a shared library (.so or .dll) on your platform
To statically link FTS1 into SQLite, add all .c files from the ext/fts1 subdirectory to the Makefile you use to compile SQLite so that they will be linked into the SQLite image. You must define the preprocessor symbols SQLITE_CORE and SQLITE_ENABLE_FTS1 when compiling these files.
When FTS1 is built as a shared library, you can load it into SQLite using the ".load" shell command.
sqlite> .load libfts1.dll
Or you can load it using a SELECT statement:
Note that you may need to call sqlite3_enable_load_extension before loading the extension; see the SQLite LoadableExtensions documentation. The command-line shell program calls sqlite3_enable_load_extension automatically. But if you build your own application, you will need to call sqlite3_enable_load_extension for yourself.
In a static build, FTS1 is always available; there's no need to load or otherwise initialize it.
Full-text tables store one or more columns of fully indexed text. You can create a full-text table using the CREATE VIRTUAL TABLE statement. For example, the following creates a table with columns name and ingredients:
sqlite>create virtual table recipe using FTS1(name, ingredients);
You can insert rows into a full-text table in the same way as into an ordinary table with columns of type TEXT:
sqlite>insert into recipe (name, ingredients) values ('broccoli stew', 'broccoli peppers cheese tomatoes'); sqlite>insert into recipe (name, ingredients) values ('pumpkin stew', 'pumpkin onions garlic celery'); sqlite>insert into recipe (name, ingredients) values ('broccoli pie', 'broccoli cheese onions flour'); sqlite>insert into recipe (name, ingredients) values ('pumpkin pie', 'pumpkin sugar flour butter');
The MATCH operator performs a full-text match on a column in a full-text table:
sqlite> select rowid, name, ingredients from recipe where name match 'pie'; 3|broccoli pie|broccoli cheese onions flour 4|pumpkin pie|pumpkin sugar flour butter sqlite>
As can be seen in the preceding output, every row in a full-text table has a unique rowid, just as in any other SQLite table.
A query may contain multiple terms, in which case it will return only documents containing all of the terms:
sqlite> select name, ingredients from recipe where ingredients match 'onions cheese'; broccoli pie|broccoli cheese onions flour sqlite>
Inside a query, the OR operator may be used to retrieve documents containing either of two terms:
sqlite> select name, ingredients from recipe where ingredients match 'onions OR cheese'; broccoli stew|broccoli peppers cheese tomatoes pumpkin stew|pumpkin onions garlic celery broccoli pie|broccoli cheese onions flour sqlite>
Note that the OR in this query must be capitalized.
The OR operator binds more tightly than the implicit AND between two adjacent terms. Thus, the query 'onions OR cheese pumpkin' matches text which contains either "onions" or "cheese", and also contains "pumpkin":
sqlite> select name, ingredients from recipe where ingredients match 'onions OR cheese pumpkin'; pumpkin stew|pumpkin onions garlic celery sqlite>
FTS1 does not provide any grouping operator (i.e. parentheses) for overriding this default precedence.
The - operator excludes any documents containing the term which follows it:
sqlite> select name, ingredients from recipe where ingredients match 'onions -celery'; broccoli pie|broccoli cheese onions flour sqlite>
Note that a query must contain at least one non-excluded term:
sqlite> select name, ingredients from recipe where ingredients match '-celery'; /* invalid! */ SQL error: SQL logic error or missing database sqlite>
Phrases may be enclosed in double quotes:
sqlite> select name, ingredients from recipe where ingredients match '"broccoli cheese"'; broccoli pie|broccoli cheese onions flour sqlite>
Querying multiple columns
To query all columns in a full-text table simultaneously, use the table's name on the left-hand side of the MATCH operator:
sqlite> select name, ingredients from recipe where recipe match 'pie'; broccoli pie|broccoli cheese onions flour pumpkin pie|pumpkin sugar flour butter sqlite>
When an all-column query contains multiple terms, a row will match even if the terms appear in different columns in the row:
sqlite> select name, ingredients from recipe where recipe match 'sugar pie'; pumpkin pie|pumpkin sugar flour butter sqlite>
Any term in a query string may be preceded by the name of a particular column to use for matching that term:
sqlite> select name, ingredients from recipe where recipe match 'name:pie ingredients:onions'; broccoli pie|broccoli cheese onions flour sqlite>
The following are entirely equivalent:
sqlite> select name from recipe where ingredients match 'sugar'; sqlite> select name from recipe where recipe match 'ingredients:sugar';
When a specific column name appears to the left of the MATCH operator, that column is used for matching any term without an explicit column qualifier. Thus, the following are equivalent:
sqlite> select name from recipe where recipe match 'name:pie ingredients:onions'; sqlite> select name from recipe where name match 'pie ingredients:onions';
Note that FTS1 currently requires a query to contain at most one instance of the MATCH operator. This means that to match multiple specific columns you must use field specifiers as described above; the following won't work:
sqlite> select name, ingredients from recipe ...> where name match 'pie' and ingredients match 'onions'; /* invalid! */ SQL error: unable to use function MATCH in the requested context sqlite>
Retrieving offset information
When returning full-text matches, FTS1 can return the character offsets of individual term matches. To retrieve offset information in a query, call the offsets function and pass it the name of your full-text table:
sqlite> select name, ingredients, offsets(recipe) from recipe where recipe match 'sugar pie'; pumpkin pie|pumpkin sugar flour butter|0 1 8 3 1 0 8 5 sqlite>
offsets returns a string containing a series of integers separated by spaces. Each match is represented by a series of four consecutive integers:
- The index of the column containing the match. Columns are numbered starting from 0.
- The term in the query expression which was matched. Terms are numbered starting from 0.
- The byte offset of the first character of the matching phrase, measured from the beginning of the column's text.
- Number of bytes in the match.
For example, in the query above two matches are returned, which we can decode as follows:
- In column 0 (name), term 1 ("pie") matched at byte offset 8; the match is 3 bytes long (the length of "pie").
- In column 1 (ingredients), term 0 ("sugar") matched at byte offset 8; the match is 5 bytes long (the length of "sugar").
FTS1 can generate snippets of text surrounding each match returned in a full-text query. To produce a snippet, call the snippet function and pass it the name of your full-text table:
sqlite> create virtual table poem using fts1(name, text); sqlite> insert into poem values ('ozymandias', 'i met a traveller from an antique land who said: two vast and trunkless legs of stone stand in the desert'); sqlite> select name, snippet(poem) from poem where text match 'land'; ozymandias|i met a traveller from an antique <b>land</b> who said: two vast and trunkless legs of <b>...</b> sqlite>
By default, each matching term in a snippet is surrounded with the delimiters "<b>" and "</b>", and an ellipsis "..." indicates text not included in a snippet. (Note that the ellipsis is itself surrounded by delimiters "<b>" and "</b>".)
You can specify your own term delimiters and ellipsis text by specifying extra arguments to the snippet function. Its arguments are as follows:
- The name of the virtual table being queried.
- Markup to put before each matching word. Default: <b>
- Markup to put after each matching word. Default: </b>
- Ellipsis markup. Default: <b>...</b>
sqlite> select name, snippet(poem, '[', ']', '%%') from poem where text match 'land'; ozymandias|i met a traveller from an antique [land] who said: two vast and trunkless legs of %% sqlite>
Joining full-text data
A full-text table stores only full-text-indexed strings. To store full-text-indexed values along with other values, it's convenient to use both a full-text table and an ordinary SQLite table, joined by rowid. For example, suppose that you'd like to store a set of messages; each message has a sender and priority, which are not full-text indexed, and a subject and body, which are full-text indexed. You can use the following schema:
create table email(sender text, priority integer); create virtual table email_text using fts1(subject, body);
You can insert a new message as follows:
insert into email (sender, priority) values ('firstname.lastname@example.org', 4); insert into email_text (rowid, subject, body) values (last_insert_rowid(), 'update', 'coming home now');
To find the sender of all messages containing the word "jam" you can issue a query joining the email and email_text tables:
select sender, subject from email join email_text on email.rowid = email_text.rowid where body match 'jam';
As the module indexes a piece of text, it converts the text to a sequence of tokens. Each token becomes a term in the index and can be matched using a full-text query.
The module currently uses the following generic tokenization mechanism. A token is a contiguous sequence of alphanumeric ASCII characters (A-Z, a-z and 0-9). All non-ASCII characters are ignored. Each token is converted to lowercase before it is stored in the index, so all full-text searches are case-insensitive. The module does not perform stemming of any sort.
Soon, we hope to allow applications to define their own tokenizers (we in fact already have a generic tokenizer mechanism in our code; we just have yet to expose it to the outside world).
There are two steps you can take to greatly improve performance when inserting documents into a full-text index. First, you can set the synchronous pragma to OFF:
sqlite>pragma synchronous = off;
In our testing we've found that this dramatically increases indexing speed. Of course, you should study the SQLite documentation (see http://www.sqlite.org/pragma.html) to understand the safety/speed tradeoff which this pragma controls and to determine the setting which is right for your application.
Secondly, you can index more than one document per transaction. In our testing, we've found throughput to be best when we index at least 50 or so documents in each transaction; this dramatically improves performance over the one-document-per-transaction case.
We're still in the process of assessing and improving performance.
Every full-text table contains a column with the same name as the table itself. This self-named column is used in multi-column queries as described above, and will appear in queries for * :
sqlite> create virtual table foo using fts1(name, address); sqlite> insert into foo (name, address) values ('amanda', '43 elm avenue'); sqlite> .header on sqlite> select * from foo; name|address|foo amanda|43 elm avenue|8è5 sqlite>
This column's value is private to FTS1. When querying a full-text table, you probably want to specify column names explicitly rather than using *, to avoid seeing this self-named column.
When you create a full-text table, FTS1 creates two backing tables which hold the table's contents and full-text index:
sqlite> .tables foo foo_content foo_term sqlite>
You should not access the backing tables directly; their format is internal to FTS1 and is subject to change.