git.cworth.org Git - notmuch-wiki/blob - searching.mdwn

   1 # Searching with notmuch
   2
   3 What good is an advanced indexing mail client if we don't know how to
   4 use it to actually find e-mail?
   5
   6 Please see the [[notmuch-search-terms manual
   7 page|man/notmuch-search-terms-7]] first for an overview of the
   8 search syntax, including the prefixes (such as "to:") and date range
   9 searches.
  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|man/notmuch-search-terms-7]] for
 176 details.