- date:<since>..<until>
+- lastmod:<initial-revision>..<final-revision>
+
+- query:<name>
+
The **from:** prefix is used to match the name or address of the sender
of an email message.
Each timestamp is a number representing the number of seconds since
1970-01-01 00:00:00 UTC.
+The **lastmod:** prefix can be used to restrict the result by the
+database revision number of when messages were last modified (tags
+were added/removed or filenames changed). This is usually used in
+conjunction with the **--uuid** argument to **notmuch search**
+to find messages that have changed since an earlier query.
+
+The **query:** prefix allows queries to refer to previously saved
+queries added with **notmuch-config(1)**. Named queries are only
+available if notmuch is built with **Xapian Field Processors** (see
+below).
+
+Operators
+---------
+
In addition to individual terms, multiple terms can be combined with
-Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
-query will be implicitly connected by a logical AND if no explicit
-operator is provided, (except that terms with a common prefix will be
-implicitly combined with OR until we get Xapian defect #402 fixed).
+Boolean operators (**and**, **or**, **not**, and **xor**). Each term
+in the query will be implicitly connected by a logical AND if no
+explicit operator is provided (except that terms with a common prefix
+will be implicitly combined with OR). The shorthand '-<term>' can be
+used for 'not <term>' but unfortunately this does not work at the
+start of an expression. Parentheses can also be used to control the
+combination of the Boolean operators, but will have to be protected
+from interpretation by the shell, (such as by putting quotation marks
+around any parenthesized expression).
+
+In addition to the standard boolean operators, Xapian provides several
+operators specific to text searching.
+
+::
+
+ 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
+
+The search
+
+::
+
+ notmuch search term1 ADJ term2
+
+will return results where term1 is within 10 words of term2, but in the
+same order as in the query. The threshold can be set the same as with
+NEAR:
+
+::
+
+ notmuch search term1 ADJ/7 term2
-Parentheses can also be used to control the combination of the Boolean
-operators, but will have to be protected from interpretation by the
-shell, (such as by putting quotation marks around any parenthesized
-expression).
Stemming
--------
----------------------------------
Xapian (and hence notmuch) prefixes are either **boolean**, supporting
-exact matches like "tag:inbox" or **probabilistic**, supporting a most flexible **term** based searching. The prefixes currently supported by notmuch are as follows.
+exact matches like "tag:inbox" or **probabilistic**, supporting a more flexible **term** based searching. The prefixes currently supported by notmuch are as follows.
+------------------+-----------------------+
|Boolean |Probabilistic |
+------------------+-----------------------+
| **tag:** **id:** | **from:** **to:** |
|**thread:** |**subject:** |
-|**folder:** |**attachment** |
-|**path:** | |
+|**folder:** |**attachment:** |
+|**path:** |**mimetype:** |
| | |
+------------------+-----------------------+
could describe (the end of yesterday). Similarly, date:january..february
matches from the beginning of January to the end of February.
+date:<expr>..! can be used as a shorthand for date:<expr>..<expr>. The
+expansion takes place before interpretation, and thus, for example,
+date:monday..! matches from the beginning of Monday until the end of
+Monday.
+With **Xapian Field Processor** support (see below), non-range
+date queries such as date:yesterday will work, but otherwise
+will give unexpected results; if in doubt use date:yesterday..!
+
Currently, we do not support spaces in range expressions. You can
replace the spaces with '\_', or (in most cases) '-', or (in some cases)
leave the spaces out altogether. Examples in this man page use spaces
end time, respectively. Pre-1.2.1 Xapian does not report an error on
open ended ranges, but it does not work as expected either.
-Entering date:expr without ".." (for example date:yesterday) won't work,
-as it's not interpreted as a range expression at all. You can achieve
-the expected result by duplicating the expr both sides of ".." (for
-example date:yesterday..yesterday).
-
Relative date and time
----------------------
Some time zone codes, e.g. UTC, EET.
+XAPIAN FIELD PROCESSORS
+=======================
+
+Certain optional features of the notmuch query processor rely on the
+presence of the Xapian field processor API. You can determine if your
+notmuch was built against a sufficiently recent version of Xapian by running
+
+::
+
+ % notmuch config get built_with.field_processor
+
+Currently the following features require field processor support:
+
+- non-range date queries, e.g. "date:today"
+- named queries e.g. "query:my_special_query"
+
SEE ALSO
========
projects / notmuch / blobdiff