tt-rss.github.io/docs/Search.md

layout, title, parent

layout	title	parent
default	Search	Features

{: .note }

This only applies to the built-in search. Search plugins may override this syntax.

A search query consists of one or several keywords.

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 engine. This engine supports word stemming, and logical operators.

A keyword can also be a name-value keyword:

• star:true, star:false - match starred or not starred articles
• unread:true, unread:false - match unread or read articles
• pub:true, pub:false - match published or unpublished articles
• title:sometext, title:"two words" - match articles with a title containing the specified text (sub-string match)
• author:sometext, author:"two words" - match articles with an author containing the specified text (sub-string match)
• note:true, note:false, note:sometext, note:"two words" - match articles with a note, no note, or a note containing the specified text (sub-string match)
• label:true, label:false, label:somelabel, label:"two words" - match articles with a label, no label, or belonging to the specified label (exact-string match)
• tag:true, tag:false, tag:sometag, tag:"two words" - match articles with a tag, no tag, or associated to the specified tag (exact-string match)

A keyword can also be a date keyword:

• @somedate - match by article publication date

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.

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) AND the phrase "tree flower" (with stemming) AND a note AND a title not containing the string "orange color". This AND must not be written, it is applied by default.

Other logical operators are only supported around a text keyword, because they are processed by PostgreSQL Full Text Search engine. A name-value keyword or date keyword does not support those PostgreSQL logical operators.

PostgreSQL Full Text Search

Tiny Tiny RSS uses a PostgreSQL database, providing a Full Text Search engine (external link).

It supports two main features:

• Word stemming
• Logical operators

Word stemming

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.

Word stemming is only available for text keywords.

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.

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.

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.

The user can also manually set a prefix in the search query using the syntax secu:* which matches every word starting by secu.

Logical operators

A text keyword can be surrounded by logical operators provided by the PostgreSQL Full Text Search engine.

{: .note }

Due to current parser limitations, these logical operators cannot be applied on a name-value keyword nor on a date keyword.

PostgreSQL provides:

• ! : logical NOT
• & : logical AND
• | : logical OR
• ( and ) : parentheses can be used to control nesting of operators. Without parentheses, | binds least tightly, then &, and ! most tightly.

For example: ocean & ( ( pacific | atlantic ) & ! "black sea" )

{: .warning }

Due to current parser limitations, the handling of space is important:

• Spaces are required around words enclosed in quotes such as "black sea", otherwise the parser does not detect the quotes.
• Spaces are recommended around single words such as atlantic, otherwise the word is not highlighted (please also see highlighting limitations).
• Spaces are recommended around logical operators, otherwise highlighting may not work correctly.

{: .warning }

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. 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.

{: .note }

When a search query contains name-value/date keywords and text keywords using logical operators, it is recommended to write the text keywords at the end (or the beginning), and to surround them with parentheses. 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.

{: .note }

Due to current parser limitations, the - negation does not work before a parenthesis (only before a text keyword). When a parentheses group needs to be negated, use the ! operator. For example: -title:submarine @yesterday ( ! ( pacific | atlantic ) )

Date keyword

A date keyword can filter articles based on their publication or update date:

• @2025-10-28 formatted as @YYYY-MM-DD
• @2025/10/28 formatted as @YYYY/MM/DD
• @28/10/2025 formatted as @DD/MM/YYYY
• @"28 oct 2025"
• @"October 28" (of the current year)
• @today
• @yesterday
• @"2 days ago"
• @"last monday"

{: .note }

A date keyword has to represent a fixed day. For example @"last week", @2023-11 or @2024 cannot be used because they represent a range of several days.

Quoting variants

When a text keyword contains spaces, and is negated, it can be written in two ways:

• -"pacific ocean" - the recommended usage because it is more readable
• "-pacific ocean"

When a name-value keyword contains spaces, it can be written in two ways:

• title:"two words" - the recommended usage because it is more readable
• "title:two words"

The negative expression can be written in two ways:

• -title:"two words" - the recommended usage because it is more readable
• "-title:two words"

When a date keyword contains spaces, it can be written in two ways:

• @"two words" - the recommended usage because it is more readable
• "@two words"

The negative expression can be written in two ways:

• -@"two words" - the recommended usage because it is more readable
• "-@two words"

Highlighting limitations

A text keyword can be a single word such as ocean. If the article contains ocean or oceanographer, the ocean fragment is highlighted. A 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.

{: .note }

Due to incomplete implementation, the word is not correctly highlighted when a stemmed 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.

If the searched word is prefixed by the negation -, it is not highlighted.

{: .note }

Due to incomplete implementation, the negation with ! is not detected, so words negated in a such way are still highlighted. Use the - sign instead.

Undetected errors

{: .warning }

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.

Contributions are welcome

The current search query parser implements a basic keyword splitting. It works in most cases, but has the disadvantages presented above.

It is maintained with best effort until someone volunteers to create a full parser with:

• logical operators and grouping around any type of keyword
• highlighting supported in all cases
• detection of invalid queries, with a warning displayed

Contributions are welcome!