X-Git-Url: https://git.cworth.org/git?p=notmuch-wiki;a=blobdiff_plain;f=searching.mdwn;h=8f2b07a141c5f4c6f91a4fb158be08e750dbe7b0;hp=5838420373ae90bf44999fcc45c08872c9d6e2c7;hb=HEAD;hpb=70375b230657e1da3757cb4e3e8f10df00ebdd3e diff --git a/searching.mdwn b/searching.mdwn index 5838420..0564f72 100644 --- a/searching.mdwn +++ b/searching.mdwn @@ -1,25 +1,29 @@ -# Searching with notmuch +[[!img notmuch-logo.png alt="Notmuch logo" class="left"]] +# Searching with Notmuch What good is an advanced indexing mail client if we don't know how to use it to actually find e-mail? -As notmuch is using Xapian -[this page](http://xapian.org/docs/queryparser.html) is a good start. -However, the description is generic (applies to Xapian in general) and -its intended audience seems to be developers wanting to use Xapian in -their applications. This page attempts to explain it to users of notmuch (who -may not be familiar with Xapian). 'notmuch help search-terms' also has a few -pointers. +The [notmuch-search-terms manual +pages](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html) +should cover everything in a fairly concise manner. Please refer to +that for any details. + +Notmuch uses the [Xapian](http://xapian.org/) search engine. The [Xapian +QueryParser](http://xapian.org/docs/queryparser.html) documentation has +a generic description of the search language. The intended audience is +developers wanting to use Xapian in their applications; this page +attempts to explain it to users of Notmuch. ## Stemming See the [Wikipedia article](http://en.wikipedia.org/wiki/Stemming) for the detailed description. What this means for us is that these searches - notmuch search detailed - notmuch search details - notmuch search detail - + notmuch search detailed + notmuch search details + notmuch search detail + will all return identical results, because Xapian first "reduces" the term to the common stem (here 'detail') and then performs the search. @@ -44,19 +48,19 @@ It is possible to use a trailing '\*' as a wildcard. A search for ## Operators -Xapian implements the typical usual operators and a few more that are +Xapian implements the usual operators and a few more that are useful when searching e-mails. -*Note: The operators need not be capitalized for notmuch, so NOT and not are +*Note: The operators need not be capitalized for notmuch, so 'NOT' and 'not' are equivalent. The capitalized form is used below only for readability* ### '+' and '-' - notmuch search +term1 + notmuch search +term1 -will return results that contain 'term1'. +will only return results that contain 'term1'. - notmuch search -term2 + notmuch search -term2 will return results that do not contain 'term2'. '+' and '-' can also be used on bracketed expressions or phrases (see below). @@ -70,28 +74,28 @@ will return results that contain **both** 'term1' and 'term2'. If no explicit operator is provided all search terms are connected by an implicit AND, so these two searches: - notmuch search term1 AND term2 - notmuch search term1 term2 + notmuch search term1 AND term2 + notmuch search term1 term2 are equivalent. - notmuch search term1 NOT term2 + notmuch search term1 NOT term2 will return results that contain 'term1' but do not contain 'term2'. For a query that looks more like natural language you can also use AND NOT - notmuch search term1 AND NOT term2 + notmuch search term1 AND NOT term2 ### XOR (exclusive OR) - notmuch search term1 XOR term2 + notmuch search term1 XOR term2 will return results that contain either 'term1' or 'term2', but **not** both. ### OR - notmuch search term1 OR term2 + notmuch search term1 OR term2 will return results that contain either 'term1' or 'term2'. @@ -100,33 +104,33 @@ will return results that contain either 'term1' or 'term2'. Operators above are listed in the default order of precedence. One can override the precedence using bracketed expressions: - notmuch search term1 AND term2 OR term3 + notmuch search term1 AND term2 OR term3 is the same as - notmuch search (term1 AND term2) OR term3 + notmuch search (term1 AND term2) OR term3 but not the same as - notmuch search term1 AND (term2 OR term3) + notmuch search term1 AND (term2 OR term3) ### NEAR - notmuch search term1 NEAR term2 + notmuch search term1 NEAR term2 will return results where term1 is within 10 words of term2. The threshold can be set like this: - notmuch search term1 NEAR/2 term2 + notmuch search term1 NEAR/2 term2 ### ADJ (adjacent) -notmuch search term1 ADJ term2 + notmuch search term1 ADJ term2 will return results where term1 is within 10 words of term2, but in the -same order. The threshold can be set the same as with NEAR: +same order as in the query. The threshold can be set the same as with NEAR: - notmuch search term1 ADJ/7 term2 + notmuch search term1 ADJ/7 term2 ### Phrases @@ -137,33 +141,38 @@ e-mail addresses are also treated as phrases. In practice this means that these two searches are **not** equivalent: - notmuch search "Debian Project" - notmuch search Debian ADJ/1 Project + notmuch search "Debian Project" + notmuch search Debian ADJ/1 Project ## Prefix searches You can search your collection by using several prefixes, like this: - notmuch search from:john + notmuch search from:john This will return results where 'john' appears in the name or the e-mail address. See 'notmuch help search-terms' for a complete list of prefixes. +### Message IDs + +An important concept for notmuch is the Message-Id, which is a unique +identifier for each message. Individual messages can be accessed via +their message ID with the "id:" prefix: + + notmuch search id: + ## Range searches Since notmuch is about (large) e-mail collections it is very useful to be able to search for e-mails within a specific date range. This will work: - notmuch search .. - -However, until a better syntax is implemented the only form accepted for -timestamps is Unix time (seconds since 1970-01-01 00:00:00 UTC), so the -utility 'date' can help: - - notmuch search $(date +%s -d 2009-10-01)..$(date +%s) + notmuch search date:.. -Explanation: '+%s' will tell date to output Unix time format and -d will -tell date to output the date from 2009-10-01. See date(1) for more -details. +For `` and ``, notmuch understands a variety of standard +and natural ways of expressing dates and times, both in absolute terms +("2012-10-24") and in relative terms ("yesterday"). Please refer to +the [notmuch-search-terms +manual](https://notmuchmail.org/doc/latest/man7/notmuch-search-terms.html) +for details.