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