1 .. _notmuch-sexp-queries(7):
10 **notmuch** **search** ``--query=sexp`` '(and (to santa) (date december))'
19 An *s-expression* is either an atom, or list of whitespace delimited
20 s-expressions inside parentheses. Atoms are either
23 A basic value is an unquoted string containing no whitespace, double quotes, or
27 Double quotes (") delimit strings possibly containing whitespace
28 or parentheses. These can contain double quote characters by
29 escaping with backslash. E.g. ``"this is a quote \""``.
34 An s-expression query is either an atom, the empty list, or a
35 *compound query* consisting of a prefix atom (first element) defining
36 a *field*, *logical operation*, or *modifier*, and 0 or more
40 "*" matches any non-empty string in the current field.
43 The empty list matches all messages
47 Match all messages containing *term*, possibly after stemming or
48 phrase splitting. For discussion of stemming in notmuch see
49 :any:`notmuch-search-terms(7)`. Stemming only applies to unquoted
50 terms (basic values) in s-expression queries. For information on
51 phrase splitting see :any:`fields`.
53 ``(`` *field* |q1| |q2| ... |qn| ``)``
54 Restrict the queries |q1| to |qn| to *field*, and combine with *and*
55 (for most fields) or *or*. See :any:`fields` for more information.
57 ``(`` *operator* |q1| |q2| ... |qn| ``)``
58 Combine queries |q1| to |qn|. Currently supported operators are
59 ``and``, ``or``, and ``not``. ``(not`` |q1| ... |qn| ``)`` is equivalent
60 to ``(and (not`` |q1| ``) ... (not`` |qn| ``))``.
62 ``(`` *modifier* |q1| |q2| ... |qn| ``)``
63 Combine queries |q1| to |qn|, and reinterpret the result (e.g. as a regular expression).
64 See :any:`modifiers` for more information.
72 correspond to attributes of mail messages. Some are inherent (and
73 immutable) like ``subject``, while others ``tag`` and ``property`` are
74 settable by the user. Each concrete field in
75 :any:`the table below <field-table>`
76 is discussed further under "Search prefixes" in
77 :any:`notmuch-search-terms(7)`. The row *user* refers to user defined
78 fields, described in :any:`notmuch-config(1)`.
80 Most fields are either *phrase fields* [#aka-prob]_ (which match
81 sequences of words), or *term fields* [#aka-bool]_ (which match exact
82 strings). *Phrase splitting* breaks the term (basic value or quoted
83 string) into words, ignore punctuation. Phrase splitting is applied to
84 terms in phrase (probabilistic) fields. Both phrase splitting and
85 stemming apply only in phrase fields.
87 Each term or phrase field has an associated combining operator
88 (``and`` or ``or``) used to combine the queries from each element of
89 the tail of the list. This is generally ``or`` for those fields where
90 a message has one such attribute, and ``and`` otherwise.
92 Term or phrase fields can contain arbitrarily complex queries made up
93 from terms, operators, and modifiers, but not other fields.
97 .. table:: Fields with supported modifiers
99 +------------+-----------+-----------+-----------+-----------+----------+
100 | field | combine | type | expand | wildcard | regex |
101 +============+===========+===========+===========+===========+==========+
102 | *none* | and | | no | yes | no |
103 +------------+-----------+-----------+-----------+-----------+----------+
104 | *user* | and | phrase | no | yes | no |
105 +------------+-----------+-----------+-----------+-----------+----------+
106 | attachment | and | phrase | yes | yes | no |
107 +------------+-----------+-----------+-----------+-----------+----------+
108 | body | and | phrase | no | no | no |
109 +------------+-----------+-----------+-----------+-----------+----------+
110 | date | | range | no | no | no |
111 +------------+-----------+-----------+-----------+-----------+----------+
112 | folder | or | phrase | yes | yes | yes |
113 +------------+-----------+-----------+-----------+-----------+----------+
114 | from | and | phrase | yes | yes | yes |
115 +------------+-----------+-----------+-----------+-----------+----------+
116 | id | or | term | no | yes | yes |
117 +------------+-----------+-----------+-----------+-----------+----------+
118 | is | and | term | yes | yes | yes |
119 +------------+-----------+-----------+-----------+-----------+----------+
120 | lastmod | | range | no | no | no |
121 +------------+-----------+-----------+-----------+-----------+----------+
122 | mid | or | term | no | yes | yes |
123 +------------+-----------+-----------+-----------+-----------+----------+
124 | mimetype | or | phrase | yes | yes | no |
125 +------------+-----------+-----------+-----------+-----------+----------+
126 | path | or | term | no | yes | yes |
127 +------------+-----------+-----------+-----------+-----------+----------+
128 | property | and | term | yes | yes | yes |
129 +------------+-----------+-----------+-----------+-----------+----------+
130 | subject | and | phrase | yes | yes | yes |
131 +------------+-----------+-----------+-----------+-----------+----------+
132 | tag | and | term | yes | yes | yes |
133 +------------+-----------+-----------+-----------+-----------+----------+
134 | thread | or | term | yes | yes | yes |
135 +------------+-----------+-----------+-----------+-----------+----------+
136 | to | and | phrase | yes | yes | no |
137 +------------+-----------+-----------+-----------+-----------+----------+
144 *Modifiers* refer to any prefixes (first elements of compound queries)
145 that are neither operators nor fields.
147 ``(infix`` *atom* ``)``
148 Interpret *atom* as an infix notmuch query (see
149 :any:`notmuch-search-terms(7)`). Not supported inside fields.
151 ``(matching`` |q1| |q2| ... |qn| ``)`` ``(of`` |q1| |q2| ... |qn| ``)``
152 Match all messages have the same values of the current field as
153 those matching all of |q1| ... |qn|. Supported in most term [#not-path]_ or
154 phrase fields. Most commonly used in the ``thread`` field.
156 ``(query`` *atom* ``)``
157 Expand to the saved query named by *atom*. See
158 :any:`notmuch-config(1)` for more. Note that the saved query must
159 be in infix syntax (:any:`notmuch-search-terms(7)`). Not supported
162 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
163 Interpret *atom* as a POSIX.2 regular expression (see
164 :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
165 phrase fields (see :any:`field-table`).
167 ``(starts-with`` *subword* ``)``
168 Matches any term starting with *subword*. This applies in either
169 phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
170 a ``starts-with`` query cannot be part of a phrase. The
171 atom ``*`` is a synonym for ``(starts-with "")``.
177 Match all messages containing the word "wizard", ignoring case.
180 Match all messages containing "added", but also those containing "add", "additional",
181 "Additional", "adds", etc... via stemming.
184 Match messages containing words "Bob" and "Marley", or their stems
185 The words need not be adjacent.
188 Match messages containing neither "Bob" nor "Marley", nor their stems,
190 ``"quick fox"`` ``quick-fox`` ``quick@fox``
191 Match the *phrase* "quick" followed by "fox" in phrase fields (or
192 outside a field). Match the literal string in a term field.
194 ``(folder (of (id 1234@invalid)))``
195 Match any message in the same folder as the one with Message-Id "1234@invalid"
197 ``(id 1234@invalid blah@test)``
198 Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
200 ``(and (infix "date:2009-11-18..2009-11-18") (tag unread))``
201 Match messages in the given date range with tag unread.
203 ``(starts-with prelim)``
204 Match any words starting with "prelim".
206 ``(subject quick "brown fox")``
207 Match messages whose subject contains "quick" (anywhere, stemmed) and
208 the phrase "brown fox".
210 ``(subject (starts-with prelim))``
211 Matches any word starting with "prelim", inside a message subject.
213 ``(subject (starts-wih quick) "brown fox")``
214 Match messages whose subject contains "quick brown fox", but also
215 "brown fox quicksand".
217 ``(thread (of (id 1234@invalid)))``
218 Match any message in the same thread as the one with Message-Id "1234@invalid"
220 ``(thread (matching (from bob@example.com) (to bob@example.com)))``
221 Match any (messages in) a thread containing a message from
222 "bob@example.com" and a (possibly distinct) message to "bob at
225 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
226 Match in the "To" or "Cc" headers, "bob@example.com",
227 "mallory@example.org", and also "bob@example.com.au" since it
228 contains the adjacent triple "bob", "example", "com".
231 Match messages with an empty or invalid 'To' and 'Cc' field.
234 Match messages with a non-empty List-Id header, assuming
235 configuration ``index.header.List=List-Id``
240 .. [#aka-pref] a.k.a. prefixes
242 .. [#aka-prob] a.k.a. probabilistic prefixes
244 .. [#aka-bool] a.k.a. boolean prefixes
246 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
247 regex queries could only match individual words.
249 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
250 this modifier is not supported in the ``body`` field.
252 .. [#not-path] Due to the way recursive ``path`` queries are implemented
253 in notmuch, this modifier is not supported in the
256 .. |q1| replace:: :math:`q_1`
257 .. |q2| replace:: :math:`q_2`
258 .. |qn| replace:: :math:`q_n`