You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Search.md
+36-35Lines changed: 36 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,11 +9,11 @@ parent: Features
9
9
10
10
A search query consists of one or several keywords.
11
11
12
-
<aid="text_keyword"></a>A keyword can be a **text keyword**. A text keyword is a single word such as `ocean`, or successive words enclosed in quotes such as `"pacific ocean"`. These keywords are searched using PostgreSQL [Full Text Search](#full_text_search) engine. This engine supports [word stemming](#word_stemming), and [logical operators](#logical_operators).
12
+
<aid="text-keyword"></a>A keyword can be a **text keyword**. A text keyword is a single word such as `ocean`, or successive words enclosed in quotes such as `"pacific ocean"`. These keywords are searched using the PostgreSQL [Full Text Search](#full-text-search) engine. This engine supports [word stemming](#word-stemming), and [logical operators](#logical-operators).
13
13
14
-
<aid="namevalue_keyword"></a>A keyword can also be a **name-value keyword**:
15
-
-`star:true`, `star:false` - match starred or not starred articles
16
-
-`unread:true`, `unread:false` - match unread or read articles
14
+
<aid="namevalue-keyword"></a>A keyword can also be a **name-value keyword**:
15
+
-`star:true`, `star:false` - match starred or not starred articles
16
+
-`unread:true`, `unread:false` - match unread or read articles
17
17
-`pub:true`, `pub:false` - match published or unpublished articles
18
18
-`title:sometext`, `title:"two words"` - match articles with a title containing the specified text (sub-string match)
19
19
-`author:sometext`, `author:"two words"` - match articles with an author containing the specified text (sub-string match)
@@ -26,42 +26,43 @@ A keyword can also be a **date keyword**:
26
26
27
27
A keyword starting with `-` (negative sign) is considered a negative match. The `-` can be applied before any type of keyword. For example `-unwanted`, `-"unwanted words"`, `-title:unwanted`, `-tag:"unwanted words"` or `-@yesterday`.
28
28
29
-
A logical `AND` operator is applied between keywords. For example `ocean "tree flower" note:true -title:"orange color"` searches for articles containing the word _ocean_ (with [stemming](#word_stemming)) AND the sentence_"tree flower"_ (with [stemming](#word_stemming)) AND a note AND a title not containing the string _"orange color"_. This _AND_ must not be written, it is applied by default.
29
+
A logical `AND` operator is applied between keywords. For example `ocean "tree flower" note:true -title:"orange color"` searches for articles containing the word _ocean_ (with [stemming](#word-stemming)) AND the phrase_"tree flower"_ (with [stemming](#word-stemming)) AND a note AND a title not containing the string _"orange color"_. This _AND_ must not be written, it is applied by default.
30
30
31
-
Other [logical operators](#logical_operators) are only supported around a [text keyword](#text_keyword), because they are processed by PostgreSQL [Full Text Search](#full_text_search) engine. A [name-value keyword](#namevalue_keyword) or [date keyword](#date_keyword) does not support those PostgreSQL [logical operators](#logical_operators).
31
+
Other [logical operators](#logical-operators) are only supported around a [text keyword](#text-keyword), because they are processed by PostgreSQL [Full Text Search](#full-text-search) engine. A [name-value keyword](#namevalue-keyword) or [date keyword](#date_keyword) does not support those PostgreSQL [logical operators](#logical-operators).
32
32
33
33
34
-
<aid="full_text_search"></a>
35
-
# PostgreSQL Full Text Search
34
+
<aid="full-text-search"></a>
35
+
##PostgreSQL Full Text Search
36
36
37
37
Tiny Tiny RSS uses a PostgreSQL database, providing a [Full Text Search engine](https://www.postgresql.org/docs/current/textsearch-intro.html) (external link).
38
38
39
39
It supports two main features:
40
-
-[Word stemming](#word_stemming)
41
-
-[Logical operators](#logical_operators)
40
+
-[Word stemming](#word-stemming)
41
+
-[Logical operators](#logical-operators)
42
42
43
-
<aid="word_stemming"></a>
44
-
## Word stemming
43
+
<aid="word-stemming"></a>
44
+
###Word stemming
45
45
46
46
Word stemming is a process to find the stem (root) of a word. For example, in English the words _security_, _secure_ and _secured_ all share the same stem: _secur_. PostgreSQL names this stem a _lexeme_. A _lexeme_ is a normalized string so that different forms of the same word are made alike.
47
47
48
-
Word stemming is only available for [text keywords](#text_keyword).
48
+
Word stemming is only available for [text keywords](#text-keyword).
49
49
50
-
Here is a full example. A RSS feed provides an article containing the word _security_. If the user has configured the language of this feed as English, then this word _security_ is stored in the database as its lexeme _secur_. Later, the user opens the search form, selects the English language, and searches for _secured_. Tiny Tiny RSS sends _secured_ to PostgreSQL, which converts this query to the lexeme _secur_. As both lexemes are identical, the article containing _security_ matches the search query _secured_.
50
+
Here is a full example. A RSS feed provides an article containing the word _security_. If the user has configured the language of this feed as English, then this word _security_ is stored in the database as its lexeme _secur_.
51
+
Later, the user opens the search form, selects the English language, and searches for _secured_. Tiny Tiny RSS sends _secured_ to PostgreSQL, which converts this query to the lexeme _secur_. As both lexemes are identical, the article containing _security_ matches the search query _secured_.
51
52
52
53
Word stemming is powerful, but has one drawback: both languages of the feed and of the search query have to be well configured. Indeed, the word stemming process depends on the language: French and English words are not stemmed in the same way, so comparing them may lead to unexpected results.
53
54
54
-
On the Tiny Tiny RSS interface, there is a special language named _Simple_. Word stemming in the _Simple_ language is almost equivalent to exact string matching. With the _Simple_ language, only punctuation such as commas are removed. The power of word stemming is thus not applied, but it works well in usages with multiple languages.
55
+
In Tiny Tiny RSS there is a special language named _Simple_.. Word stemming in the _Simple_ language is almost equivalent to exact string matching. With the _Simple_ language, only punctuation such as commas are removed. The power of word stemming is thus not applied, but it works well in usages with multiple languages.
55
56
56
57
The user can also manually set a prefix in the search query using the syntax `secu:*` which matches every word starting by `secu`.
57
58
58
-
<aid="logical_operators"></a>
59
-
## Logical operators
59
+
<aid="logical-operators"></a>
60
+
###Logical operators
60
61
61
-
A [text keyword](#text_keyword) can be surrounded by logical operators provided by the PostgreSQL [Full Text Search](#full_text_search) engine.
62
+
A [text keyword](#text-keyword) can be surrounded by logical operators provided by the PostgreSQL [Full Text Search](#full-text-search) engine.
62
63
63
64
{: .note }
64
-
> Due to current parser limitations, these logical operators cannot be applied on a [name-value keyword](#namevalue_keyword) nor on a [date keyword](#date_keyword).
65
+
> Due to current parser limitations, these logical operators cannot be applied on a [name-value keyword](#namevalue-keyword) nor on a [date keyword](#date_keyword).
> Due to current parser limitations, the handling of space is important:
76
-
> - Spaces are **compulsory around words enclosed in quotes** such as `"black sea"`, otherwise the parser does not detect the quotes.
77
+
> - Spaces are **required around words enclosed in quotes** such as `"black sea"`, otherwise the parser does not detect the quotes.
77
78
> - Spaces are **recommended around single words** such as `atlantic`, otherwise the word is not highlighted (please also see [highlighting limitations](#highlighting_limitations)).
78
79
> - Spaces are **recommended around logical operators**, otherwise highlighting may not work correctly.
79
80
80
81
{: warning }
81
-
> Due to current parser limitations, when at least one operator is detected, Tiny Tiny RSS does not apply the default _AND_ operator. Tiny Tiny RSS expects the whole query to be well formatted. For example the query `one two` works because no operator is detected, so tt-rss adds the _AND_. However, `one two & three` fails because tt-rss detects the `&` operator, so expects the whole query to be well formatted, and does not add the missing `&` between the words `one` and `two`.
82
+
> Due to current parser limitations, when at least one operator is detected Tiny Tiny RSS does not apply the default _AND_ operator. Tiny Tiny RSS expects the whole query to be well formatted. For example the query `one two` works because no operator is detected, so Tiny Tiny RSS adds the _AND_.
83
+
> However, `one two & three` fails because Tiny Tiny RSS detects the `&` operator, so expects the whole query to be well formatted, and does not add the missing `&` between the words `one` and `two`.
82
84
83
85
{: .note }
84
-
> When a search query contains [name-value](#namevalue_keyword)/[date](#date_keyword) keywords and [text keywords](#text_keyword) using _logical operators_, it is recommended to write the [text keywords](#text_keyword) at the end (or the beginning), and to surround them with parenthesis. For example when reading `-title:submarine @yesterday ( pacific | atlantic )` one can easily understand that the parenthesis contains a complex fragment, that has to be well formatted with no missing operator.
86
+
> When a search query contains [name-value](#namevalue-keyword)/[date](#date_keyword) keywords and [text keywords](#text-keyword) using _logical operators_, it is recommended to write the [text keywords](#text-keyword) at the end (or the beginning), and to surround them with parentheses.
87
+
> For example when reading `-title:submarine @yesterday ( pacific | atlantic )` one can easily understand that the parentheses contains a complex fragment that has to be well formatted with no missing operator.
85
88
86
89
{: .note }
87
-
> Due to current parser limitations, the `-` negation does not work before a parenthesis. It only works before a [text keyword](#text_keyword). When a parenthesis group needs to be negated, use the `!` operator. For example: `-title:submarine @yesterday ( ! ( pacific | atlantic ) )`
90
+
> Due to current parser limitations, the `-` negation does not work before a parenthesis (only before a [text keyword](#text-keyword)). When a parentheses group needs to be negated, use the `!` operator. For example: `-title:submarine @yesterday ( ! ( pacific | atlantic ) )`
88
91
89
92
90
93
<aid="date_keyword"></a>
91
-
# Date keyword
94
+
##Date keyword
92
95
93
96
A _date keyword_ can filter articles based on their publication or update date:
94
97
-`@2025-10-28` formatted as `@YYYY-MM-DD`
@@ -106,13 +109,13 @@ A _date keyword_ can filter articles based on their publication or update date:
106
109
107
110
108
111
<aid="quoting_variants"></a>
109
-
# Quoting variants
112
+
##Quoting variants
110
113
111
-
When a [text keyword](#text_keyword) contains spaces, and is negated, it can be written in two ways:
114
+
When a [text keyword](#text-keyword) contains spaces, and is negated, it can be written in two ways:
112
115
-`-"pacific ocean"` - the recommended usage because it is more readable
113
116
-`"-pacific ocean"`
114
117
115
-
When a [name-value keyword](#namevalue_keyword) contains spaces, it can be written in two ways:
118
+
When a [name-value keyword](#namevalue-keyword) contains spaces, it can be written in two ways:
116
119
-`title:"two words"` - the recommended usage because it is more readable
117
120
-`"title:two words"`
118
121
@@ -129,13 +132,13 @@ The negative expression can be written in two ways:
129
132
-`"-@two words"`
130
133
131
134
<aid="highlighting_limitations"></a>
132
-
# Highlighting limitations
135
+
##Highlighting limitations
133
136
134
-
A [text keyword](#text_keyword) can be a single word such as `ocean`. If the article contains `ocean` or `oceanographer`, the `ocean` fragment is highlighted.
135
-
A [text keyword](#text_keyword) can also be successive words enclosed in quotes such as `"pacific ocean"`. If the article contains `pacific oceanographer`, the `pacific ocean` fragment is highlighted.
137
+
A [text keyword](#text-keyword) can be a single word such as `ocean`. If the article contains `ocean` or `oceanographer`, the `ocean` fragment is highlighted.
138
+
A [text keyword](#text-keyword) can also be successive words enclosed in quotes such as `"pacific ocean"`. If the article contains `pacific oceanographer`, the `pacific ocean` fragment is highlighted.
136
139
137
140
{: .note }
138
-
> Due to incomplete implementation, the word is not correctly highlighted when a [stemmed](#word_stemming) variant is used. For example, if the user searches for _secured_, articles containing _security_ are displayed, however as _secured_ is not in the content, it is not highlighted.
141
+
> Due to incomplete implementation, the word is not correctly highlighted when a [stemmed](#word-stemming) variant is used. For example, if the user searches for _secured_, articles containing _security_ are displayed, however as _secured_ is not in the content, it is not highlighted.
139
142
140
143
If the searched word is prefixed by the negation `-`, it is not highlighted.
141
144
@@ -144,14 +147,14 @@ If the searched word is prefixed by the negation `-`, it is not highlighted.
144
147
145
148
146
149
<aid="undetected_errors"></a>
147
-
# Undetected errors
150
+
##Undetected errors
148
151
149
152
{: warning }
150
153
> Due to current parser limitations, most syntax errors are undetected. When user enters a badly formatted search query, it is incorrectly parsed, no message is displayed, and the results are unexpected.
151
154
152
155
153
156
<aid="contributions"></a>
154
-
# Contributions are welcome
157
+
##Contributions are welcome
155
158
156
159
The current search query parser implements a basic keyword splitting. It works in most cases, but has the disadvantages presented above.
157
160
@@ -161,5 +164,3 @@ It is maintained with best effort until someone volunteers to create a full pars
161
164
- detection of invalid queries, with a warning displayed
0 commit comments