diff options
author | Carlos Garnacho <carlosg@gnome.org> | 2023-04-02 23:28:13 +0200 |
---|---|---|
committer | Carlos Garnacho <carlosg@gnome.org> | 2023-04-04 10:59:04 +0200 |
commit | 371dae6a14a4c769723009d9117cddaf116a969f (patch) | |
tree | f6d27dca074932f445328331de3aa41e0efee313 | |
parent | 921a2009ffb32c7feb3d94908f7d8e13f984c7be (diff) | |
download | tracker-371dae6a14a4c769723009d9117cddaf116a969f.tar.gz |
docs: Document FTS feature as a whole
Docs about FTS are somewhat thin and scattered. Add a doc
blurb about FTS explaining how things are put together.
-rw-r--r-- | docs/reference/libtracker-sparql/sparql-functions.md | 66 |
1 files changed, 66 insertions, 0 deletions
diff --git a/docs/reference/libtracker-sparql/sparql-functions.md b/docs/reference/libtracker-sparql/sparql-functions.md index be8a48a8c..89c0f58c1 100644 --- a/docs/reference/libtracker-sparql/sparql-functions.md +++ b/docs/reference/libtracker-sparql/sparql-functions.md @@ -349,3 +349,69 @@ tracker:uri (?id) Returns the URN that corresponds to an ID. Its inverse operation is `tracker:id` + +# Full-text search + +Full-text search (FTS) is a built-in feature of Tracker, it allows +for efficient search of individual terms across large collections +of text. + +String properties are not searchable through the full-text index +by default, only properties with the [nrl:fulltextIndexed](nrl-ontology.md#nrl:fulltextIndexed) +property enabled can be searched with FTS. + +```turtle +# Enable FTS search on the example:title property +example:title a rdf:Property; + rdfs:range xsd:string ; + nrl:fulltextIndexed true . +``` + +Multiple full-text indexed properties may be defined, either +in the same or different classes. + +In order to tap into the full-text search index, the SPARQL +query must use the `fts:match` pseudo-property, e.g.: + +```sparql +SELECT ?res { ?res fts:match "term1 term2" } +``` + +This property will match the resources that match the search +terms, independently of the order and separation between +those terms in the searched text. Any full-text indexed +property is candidate for these matches. + +In order to complement this pseudo-property, there are +additional functions to extract more information from the +full-text index: + +- [fts:rank](#ftsrank) to get a ranking order for the matched + element. To be used in `ORDER BY` clauses. +- [fts:offsets](#ftsoffets) to get a list of offsets of the + lookup terms as found in the searched text. +- [fts:snippet](#ftssnippet) to get a short string representation + of the lookup terms in the searched text. + +These functions work on each of the matches provided by `fts:match`, +the following example puts all FTS features together at work: + +```sparql +# Get resource IRI, snippet and match offsets of every +# document matching "GNOME" +SELECT + ?u + fts:snippet(?u) + fts:offsets(?u) +{ + ?u a nfo:Document ; + fts:match "GNOME" . +} +ORDER BY DESC (fts:rank(?u)) +``` + +Full-text search is case insensitive, and the content of its +index may be subject to [stemming](https://en.wikipedia.org/wiki/Stemming), +[stop word lists](https://en.wikipedia.org/wiki/Stop_word) and other +methods of pre-processing, these settings may changed via the +[flags@Tracker.SparqlConnectionFlags] set on a local connection. |