SearchRowGetter typedef
The signature of a callback that converts a JSON value into a SearchRow.
These callbacks are application-defined and are invoked when search indexes
(FTS) are created or updated. A callback is associated with a Kind via an
entry in a SearchRowGetters map, which is passed to SearchIndex.new.
After a new JSON value of a particular Kind is inserted or updated in
SQLite.apply via Transaction, the corresponding callback receives that
value. The callback must extract the fields to be indexed from the value
and return them as a SearchRow map. The keys of the returned map must
match exactly in number and value with the names of the corresponding
SearchIndex.columns; otherwise, an Error will be thrown.
These callbacks may also be called during Scheme migrations and thus must be capable of handling both JSON values deserialized from text and JSON values passed to Transaction. If the latter are formatted to be directly encodable as JSON strings, then it is sufficient for a callback to handle the format of the former.
If a callback cannot return a correct SearchRow, it may choose, depending on the severity of the situation, one of the following three options:
- Return a full SearchRow but with empty values for indexed columns. This
excludes the JSON
valuefrom search index matches. - Throw an Exception. If the callback was called during SQLite.apply, the whole Transaction batch is rolled back.
- Throw an Error. If the callback was called during SQLite.apply, then
the SQLite instance can no longer be used, its SQLite.isApiReady
becomes
false, and the instance should be deactivated.
If the callback that threw an exception or error was invoked by migration, the SQLite instance fails initialization and becomes deactivated.
The callback must not call the API of its SQLite instance.
See also: SearchIndex.getters.
Implementation
typedef SearchRowGetter = SearchRow Function(Object value);