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