git.notmuchmail.org Git - notmuch-wiki/blob - 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
   8 pages](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html)
   9 should cover everything in a fairly concise manner. Please refer to
  10 that for any details.
  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
 176 the [notmuch-search-terms
 177 manual](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html)
 178 for details.