Emacs Docs

Appearance

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:

emacs-lisp
(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:

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

would always contain only messages from the past seven days.