1 # Searching with notmuch
3 What good is an advanced indexing mail client if we don't know how to
4 use it to actually find e-mail?
6 As notmuch is using Xapian
7 [this page](http://xapian.org/docs/queryparser.html) is a good start.
8 However, the description is generic (applies to Xapian in general) and
9 its intended audience seems to be developers wanting to use Xapian in
10 their applications. This page attempts to explain it to users of notmuch (who
11 may not be familiar with Xapian).
12 [['notmuch help search-terms'|manpages/notmuch-search-terms-7]] also has a few
17 See the [Wikipedia article](http://en.wikipedia.org/wiki/Stemming) for
18 the detailed description. What this means for us is that these searches
20 notmuch search detailed
21 notmuch search details
24 will all return identical results, because Xapian first "reduces" the
25 term to the common stem (here 'detail') and then performs the search.
27 The only way to turn this off is the so called search for proper names:
28 a search for a capitalized word will be performed unstemmed, so that one
29 can search for "John" and not get results for "Johnson".
31 ### Languages other than English
33 Stemming is currently only supported for English. Words in other
34 languages will be performed unstemmed unless somebody teaches Xapian how
35 to perform stemming for that language.
39 (how is the QueryParser configured?)
43 It is possible to use a trailing '\*' as a wildcard. A search for
44 'wildc\*' will match 'wildcard', 'wildcat', etc.
48 Xapian implements the usual operators and a few more that are
49 useful when searching e-mails.
51 *Note: The operators need not be capitalized for notmuch, so 'NOT' and 'not' are
52 equivalent. The capitalized form is used below only for readability*
58 will only return results that contain 'term1'.
62 will return results that do not contain 'term2'. '+' and '-' can also be
63 used on bracketed expressions or phrases (see below).
67 notmuch search term1 AND term2
69 will return results that contain **both** 'term1' and 'term2'.
71 If no explicit operator is provided all search terms are connected by an
72 implicit AND, so these two searches:
74 notmuch search term1 AND term2
75 notmuch search term1 term2
79 notmuch search term1 NOT term2
81 will return results that contain 'term1' but do not contain 'term2'. For
82 a query that looks more like natural language you can also use AND NOT
84 notmuch search term1 AND NOT term2
86 ### XOR (exclusive OR)
88 notmuch search term1 XOR term2
90 will return results that contain either 'term1' or 'term2', but **not**
95 notmuch search term1 OR term2
97 will return results that contain either 'term1' or 'term2'.
101 Operators above are listed in the default order of precedence. One can
102 override the precedence using bracketed expressions:
104 notmuch search term1 AND term2 OR term3
108 notmuch search (term1 AND term2) OR term3
112 notmuch search term1 AND (term2 OR term3)
116 notmuch search term1 NEAR term2
118 will return results where term1 is within 10 words of term2. The threshold
119 can be set like this:
121 notmuch search term1 NEAR/2 term2
125 notmuch search term1 ADJ term2
127 will return results where term1 is within 10 words of term2, but in the
128 same order as in the query. The threshold can be set the same as with NEAR:
130 notmuch search term1 ADJ/7 term2
134 According to the Xapian documentation a phrase surrounded with double
135 quotes (like this: "my phrase") will return results that match
136 everything containing "that exact phrase", but hyphenated words or
137 e-mail addresses are also treated as phrases.
139 In practice this means that these two searches are **not** equivalent:
141 notmuch search "Debian Project"
142 notmuch search Debian ADJ/1 Project
146 You can search your collection by using several prefixes, like this:
148 notmuch search from:john
150 This will return results where 'john' appears in the name or the e-mail
151 address. See 'notmuch help search-terms' for a complete list of
156 An important concept for notmuch is the Message-Id, which is a unique
157 identifier for each message. Individual messages can be accessed via
158 their message ID with the "id:" prefix:
160 notmuch search id:<message-id>
164 Since notmuch is about (large) e-mail collections it is very useful to
165 be able to search for e-mails within a specific date range. This will
168 notmuch search <initial timestamp>..<final-timestamp>
170 However, until a better syntax is implemented the only form accepted for
171 timestamps is Unix time (seconds since 1970-01-01 00:00:00 UTC), so the
172 utility 'date' can help:
174 notmuch search $(date +%s -d 2009-10-01)..$(date +%s)
176 Explanation: '+%s' will tell date to output Unix time format and -d will
177 tell date to output the date from 2009-10-01. See date(1) for more