Disambiguate Debian notmuch package and notmuch for emacs package.
[notmuch-wiki] / searching.mdwn
1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Searching with Notmuch
3
4 What good is an advanced indexing mail client if we don't know how to 
5 use it to actually find e-mail?
6
7 The [[notmuch-search-terms manual page|manpages/notmuch-search-terms-7]] should
8 cover everything in a fairly concise manner. Please refer to that for any
9 details.
10
11 Notmuch uses the [Xapian](http://xapian.org/) search engine. The [Xapian
12 QueryParser](http://xapian.org/docs/queryparser.html) documentation has
13 a generic description of the search language. The intended audience is
14 developers wanting to use Xapian in their applications; this page
15 attempts to explain it to users of Notmuch.
16
17 ## Stemming
18
19 See the [Wikipedia article](http://en.wikipedia.org/wiki/Stemming) for 
20 the detailed description. What this means for us is that these searches
21
22         notmuch search detailed
23         notmuch search details
24         notmuch search detail
25
26 will all return identical results, because Xapian first "reduces" the 
27 term to the common stem (here 'detail') and then performs the search.
28
29 The only way to turn this off is the so called search for proper names: 
30 a search for a capitalized word will be performed unstemmed, so that one 
31 can search for "John" and not get results for "Johnson".
32
33 ### Languages other than English
34
35 Stemming is currently only supported for English. Words in other 
36 languages will be performed unstemmed unless somebody teaches Xapian how 
37 to perform stemming for that language.
38
39 ## Synonyms
40
41 (how is the QueryParser configured?)
42
43 ## Wildcards
44
45 It is possible to use a trailing '\*' as a wildcard. A search for 
46 'wildc\*' will match 'wildcard', 'wildcat', etc.
47
48 ## Operators
49
50 Xapian implements the usual operators and a few more that are 
51 useful when searching e-mails.
52
53 *Note: The operators need not be capitalized for notmuch, so 'NOT' and 'not' are 
54 equivalent. The capitalized form is used below only for readability*
55
56 ### '+' and '-'
57
58         notmuch search +term1
59
60 will only return results that contain 'term1'.
61
62         notmuch search -term2
63
64 will return results that do not contain 'term2'. '+' and '-' can also be 
65 used on bracketed expressions or phrases (see below).
66
67 ### AND and NOT
68
69 notmuch search term1 AND term2
70
71 will return results that contain **both** 'term1' and 'term2'.
72
73 If no explicit operator is provided all search terms are connected by an 
74 implicit AND, so these two searches:
75
76         notmuch search term1 AND term2
77         notmuch search term1 term2
78
79 are equivalent.
80
81         notmuch search term1 NOT term2
82
83 will return results that contain 'term1' but do not contain 'term2'. For
84 a query that looks more like natural language you can also use AND NOT
85
86         notmuch search term1 AND NOT term2
87
88 ### XOR (exclusive OR)
89
90         notmuch search term1 XOR term2
91
92 will return results that contain either 'term1' or 'term2', but **not**
93 both.
94
95 ### OR
96
97         notmuch search term1 OR term2
98
99 will return results that contain either 'term1' or 'term2'.
100
101 ### Brackets
102
103 Operators above are listed in the default order of precedence. One can
104 override the precedence using bracketed expressions:
105
106         notmuch search term1 AND term2 OR term3
107
108 is the same as
109
110         notmuch search (term1 AND term2) OR term3
111
112 but not the same as
113
114         notmuch search term1 AND (term2 OR term3)
115
116 ### NEAR
117
118         notmuch search term1 NEAR term2
119
120 will return results where term1 is within 10 words of term2. The threshold 
121 can be set like this:
122
123         notmuch search term1 NEAR/2 term2
124
125 ### ADJ (adjacent)
126
127         notmuch search term1 ADJ term2
128
129 will return results where term1 is within 10 words of term2, but in the 
130 same order as in the query. The threshold can be set the same as with NEAR:
131
132         notmuch search term1 ADJ/7 term2
133
134 ### Phrases
135
136 According to the Xapian documentation a phrase surrounded with double 
137 quotes (like this: "my phrase") will return results that match 
138 everything containing "that exact phrase", but hyphenated words or 
139 e-mail addresses are also treated as phrases.
140
141 In practice this means that these two searches are **not** equivalent:
142
143         notmuch search "Debian Project"
144         notmuch search Debian ADJ/1 Project
145
146 ## Prefix searches
147
148 You can search your collection by using several prefixes, like this:
149
150         notmuch search from:john
151
152 This will return results where 'john' appears in the name or the e-mail 
153 address. See 'notmuch help search-terms' for a complete list of 
154 prefixes.
155
156 ### Message IDs
157
158 An important concept for notmuch is the Message-Id, which is a unique
159 identifier for each message.  Individual messages can be accessed via
160 their message ID with the "id:" prefix:
161
162         notmuch search id:<message-id>
163
164 ## Range searches
165
166 Since notmuch is about (large) e-mail collections it is very useful to 
167 be able to search for e-mails within a specific date range. This will 
168 work:
169
170         notmuch search date:<since>..<until>
171
172 For `<since>` and `<until>`, notmuch understands a variety of standard
173 and natural ways of expressing dates and times, both in absolute terms
174 ("2012-10-24") and in relative terms ("yesterday"). Please refer to the
175 [[notmuch-search-terms manual page|manpages/notmuch-search-terms-7]] for
176 details.