searching.mdwn



[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
# Searching with Notmuch

What good is an advanced indexing mail client if we don't know how to 
use it to actually find e-mail?

The [notmuch-search-terms manual
pages](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html)
should cover everything in a fairly concise manner. Please refer to
that for any details.

Notmuch uses the [Xapian](http://xapian.org/) search engine. The [Xapian
QueryParser](http://xapian.org/docs/queryparser.html) documentation has
a generic description of the search language. The intended audience is
developers wanting to use Xapian in their applications; this page
attempts to explain it to users of Notmuch.

## Stemming

See the [Wikipedia article](http://en.wikipedia.org/wiki/Stemming) for 
the detailed description. What this means for us is that these searches

        notmuch search detailed
        notmuch search details
        notmuch search detail

will all return identical results, because Xapian first "reduces" the 
term to the common stem (here 'detail') and then performs the search.

The only way to turn this off is the so called search for proper names: 
a search for a capitalized word will be performed unstemmed, so that one 
can search for "John" and not get results for "Johnson".

### Languages other than English

Stemming is currently only supported for English. Words in other 
languages will be performed unstemmed unless somebody teaches Xapian how 
to perform stemming for that language.

## Synonyms

(how is the QueryParser configured?)

## Wildcards

It is possible to use a trailing '\*' as a wildcard. A search for 
'wildc\*' will match 'wildcard', 'wildcat', etc.

## Operators

Xapian implements the usual operators and a few more that are 
useful when searching e-mails.

*Note: The operators need not be capitalized for notmuch, so 'NOT' and 'not' are 
equivalent. The capitalized form is used below only for readability*

### '+' and '-'

        notmuch search +term1

will only return results that contain 'term1'.

        notmuch search -term2

will return results that do not contain 'term2'. '+' and '-' can also be 
used on bracketed expressions or phrases (see below).

### AND and NOT

notmuch search term1 AND term2

will return results that contain **both** 'term1' and 'term2'.

If no explicit operator is provided all search terms are connected by an 
implicit AND, so these two searches:

        notmuch search term1 AND term2
        notmuch search term1 term2

are equivalent.

        notmuch search term1 NOT term2

will return results that contain 'term1' but do not contain 'term2'. For
a query that looks more like natural language you can also use AND NOT

        notmuch search term1 AND NOT term2

### XOR (exclusive OR)

        notmuch search term1 XOR term2

will return results that contain either 'term1' or 'term2', but **not**
both.

### OR

        notmuch search term1 OR term2

will return results that contain either 'term1' or 'term2'.

### Brackets

Operators above are listed in the default order of precedence. One can
override the precedence using bracketed expressions:

        notmuch search term1 AND term2 OR term3

is the same as

        notmuch search (term1 AND term2) OR term3

but not the same as

        notmuch search term1 AND (term2 OR term3)

### NEAR

        notmuch search term1 NEAR term2

will return results where term1 is within 10 words of term2. The threshold 
can be set like this:

        notmuch search term1 NEAR/2 term2

### ADJ (adjacent)

        notmuch search term1 ADJ term2

will return results where term1 is within 10 words of term2, but in the 
same order as in the query. The threshold can be set the same as with NEAR:

        notmuch search term1 ADJ/7 term2

### Phrases

According to the Xapian documentation a phrase surrounded with double 
quotes (like this: "my phrase") will return results that match 
everything containing "that exact phrase", but hyphenated words or 
e-mail addresses are also treated as phrases.

In practice this means that these two searches are **not** equivalent:

        notmuch search "Debian Project"
        notmuch search Debian ADJ/1 Project

## Prefix searches

You can search your collection by using several prefixes, like this:

        notmuch search from:john

This will return results where 'john' appears in the name or the e-mail 
address. See 'notmuch help search-terms' for a complete list of 
prefixes.

### Message IDs

An important concept for notmuch is the Message-Id, which is a unique
identifier for each message.  Individual messages can be accessed via
their message ID with the "id:" prefix:

        notmuch search id:<message-id>

## Range searches

Since notmuch is about (large) e-mail collections it is very useful to 
be able to search for e-mails within a specific date range. This will 
work:

        notmuch search date:<since>..<until>

For `<since>` and `<until>`, notmuch understands a variety of standard
and natural ways of expressing dates and times, both in absolute terms
("2012-10-24") and in relative terms ("yesterday"). Please refer to
the [notmuch-search-terms
manual](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html)
for details.