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