SearchQueryConverter class - uifts library

A parser for a user-friendly dialect of SQLite FTS5 expressions.

The goal of this parser is to translate a user-typed full-text search query into an SQLite FTS5 query. The grammar accepted by the parser has several differences from SQLite's, as well as other points of attention:

barewords are sequences of Unicode BMP letters and numbers including underscores and inner non-consecutive hyphens (e.g., well-known);
barewords must not match reserved keywords, which are the uppercase AND, OR, NOT, and NEAR (however, e.g., AND-OR is a valid bareword);
initial tokens are not supported;
explicit bareword prefix tokens are not supported;
each bareword is an implicit prefix token and, when translated, invariably becomes a quoted prefix token where underscores and hyphens are replaced with spaces (e.g., well-known is translated to "well known"*);
the NOT operator has the lowest precedence (e.g., wheat OR maize NOT weed is translated to ("wheat"* OR "maize"*) NOT "weed"*);
the explicit AND operator can be replaced with the implicit one in all cases without changing the precedence;
column names are defined as barewords but without hyphens;
only a single column in a given column expression is supported;
there must be no intermediate spacing characters when a quoted string is appended with *, when a column is prepended with -, and when a column is appended with : (e.g., -musketeers: "d'art"* is correct).

Queries generated by this parser search only within FTS columns listed in the columns property. This is achieved by automatically enclosing the resulting query within a column expression with columns from that property.

Column expressions accepted by the parser, instead of real column names, must use column aliases defined as keys in the aliases property. During translation, a column alias in a column expression is substituted with a list of real FTS columns associated in the aliases map with the alias.

In the following example, SearchQueryConverter is used to translate a query, namely shakespear NOT authors:shakespear, that requires the presence of the shakespear bareword prefix token in any of the ftsColumns and the absence of the same token in the authors column alias, which is resolved to authors and pseudonyms:

var ftsColumns = ["titles", "authors", "pseudonyms", "description"];
FtsParser ftsConverter = SearchQueryConverter(
  columns: ftsColumns,
  aliases: {
    "title": ["titles"],
    "authors": ["authors", "pseudonyms"],
    "about": ["description"],
  },
).build();
String fts = "shakespear NOT authors:shakespear";
try {
  FtsQ ftsQuery = ftsConverter.parse(fts).value;
  log.info("SUCCESS:\n`${ftsQuery.str}`");
} on ParserException catch (exception) {
  log.info("FAILURE:", exception);
}
/* SUCCESS:
  `({"titles" "authors" "pseudonyms" "description"}:
  ("shakespear"* NOT ({"authors" "pseudonyms"}: "shakespear"*)))` */

SearchQueryConverter class base

Constructors

Properties

Methods

Operators

uifts library