9.3 Search Queries

Gnus provides an optional unified search syntax that can be used across all supported search engines. This can be convenient in that you don’t have to remember different search syntaxes; it’s also possible to mark multiple groups indexed by different engines and issue a single search against them.

Set the option gnus-search-use-parsed-queries to non-nil to enable this—it is nil by default. Even if it is non-nil, it’s still possible to turn off parsing for a class of engines or a single engine (see Search Engines), or a single search by giving a prefix argument to any of the search commands.

The search syntax is fairly simple: keys and values are separated by a colon, multi-word values must be quoted, “and” is implicit, “or” is explicit, “not” will negate the following expression (or keys can be prefixed with a “-”),and parentheses can be used to group logical sub-clauses. For example:

(from:john or from:peter) subject:"lunch tomorrow" since:3d

The syntax is made to be accepted by a wide range of engines, and thus will happily accept most input, valid or not. Some terms will only be meaningful to some engines; other engines will drop them silently.

Key completion is offered on TAB, but it’s also possible to enter the query with abbreviated keys, which will be expanded during parsing. If a key is abbreviated to the point of ambiguity (for instance, “s:” could be “subject:” or “since:”), an error will be raised.

Supported keys include all the usual mail headers: “from”, “subject”, “cc”, etc. Other keys are:

body

The body of the message.

recipient

Equivalent to ‘to or cc or bcc’.

address

Equivalent to ‘from or recipient’.

id

The keys ‘message-id’ and ‘id’ are equivalent.

mark

Accepts ‘flag’, ‘seen’, ‘read’ or ‘replied’, or any of Gnus’ single-letter representations of those marks, e.g. ‘mark:R’ for ‘read’.

tag

This is interpreted as ‘keyword’ for IMAP and ‘tag’ for notmuch.

attachment

Matches the attachment file name.

before

Date is exclusive; see below for date parsing.

after

Date is inclusive; can also use ‘since’.

thread

Return entire message threads, not just individual messages.

raw

Do not parse this particular search.

limit

Limit the results to this many messages. When searching multiple groups this may give undesired results, as the limiting happens before sorting.

grep

Only applicable to “local index” engines such as mairix or notmuch. On systems with a grep command, additionally filter the results by using the value of this term as a grep regexp.

Elisp-based contact management packages (e.g. BBDB or EBDB) can push completion tables onto the variable gnus-search-contact-tables, allowing auto-completion of contact names and addresses for keys like ‘from’ or ‘to’.

9.3.1 Date value parsing

Date-type keys (see gnus-search-date-keys) will accept a wide variety of values. First, anything that parse-time-string can parse is acceptable. Dates with missing values will be interpreted as the most recent occurrence thereof: for instance “march 03” is the most recent March 3rd. Lastly, it’s possible to use relative specifications, such as “3d” (three days ago). This format also accepts w, m and y.

When creating persistent search groups, the search is saved unparsed, and re-parsed every time the group is updated. So a permanent search group with a query like:

from:"my boss" mark:flag since:1w

would always contain only messages from the past seven days.