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.
66 ``(macro (`` |p1| ... |pn| ``) body)``
67 Define saved query with parameter substitution. The syntax is
68 recognized only in saved s-expression queries (see ``squery.*`` in
69 :any:`notmuch-config(1)`). Parameter names in ``body`` must be
70 prefixed with ``,`` to be expanded (see :any:`macro_examples`).
71 Macros may refer to other macros, but only to their own
72 parameters [#macro-details]_.
80 correspond to attributes of mail messages. Some are inherent (and
81 immutable) like ``subject``, while others ``tag`` and ``property`` are
82 settable by the user. Each concrete field in
83 :any:`the table below <field-table>`
84 is discussed further under "Search prefixes" in
85 :any:`notmuch-search-terms(7)`. The row *user* refers to user defined
86 fields, described in :any:`notmuch-config(1)`.
88 Most fields are either *phrase fields* [#aka-prob]_ (which match
89 sequences of words), or *term fields* [#aka-bool]_ (which match exact
90 strings). *Phrase splitting* breaks the term (basic value or quoted
91 string) into words, ignore punctuation. Phrase splitting is applied to
92 terms in phrase (probabilistic) fields. Both phrase splitting and
93 stemming apply only in phrase fields.
95 Each term or phrase field has an associated combining operator
96 (``and`` or ``or``) used to combine the queries from each element of
97 the tail of the list. This is generally ``or`` for those fields where
98 a message has one such attribute, and ``and`` otherwise.
100 Term or phrase fields can contain arbitrarily complex queries made up
101 from terms, operators, and modifiers, but not other fields.
105 .. table:: Fields with supported modifiers
107 +------------+-----------+-----------+-----------+-----------+----------+
108 | field | combine | type | expand | wildcard | regex |
109 +============+===========+===========+===========+===========+==========+
110 | *none* | and | | no | yes | no |
111 +------------+-----------+-----------+-----------+-----------+----------+
112 | *user* | and | phrase | no | yes | no |
113 +------------+-----------+-----------+-----------+-----------+----------+
114 | attachment | and | phrase | yes | yes | no |
115 +------------+-----------+-----------+-----------+-----------+----------+
116 | body | and | phrase | no | no | no |
117 +------------+-----------+-----------+-----------+-----------+----------+
118 | date | | range | no | no | no |
119 +------------+-----------+-----------+-----------+-----------+----------+
120 | folder | or | phrase | yes | yes | yes |
121 +------------+-----------+-----------+-----------+-----------+----------+
122 | from | and | phrase | yes | yes | yes |
123 +------------+-----------+-----------+-----------+-----------+----------+
124 | id | or | term | no | yes | yes |
125 +------------+-----------+-----------+-----------+-----------+----------+
126 | is | and | term | yes | yes | yes |
127 +------------+-----------+-----------+-----------+-----------+----------+
128 | lastmod | | range | no | no | no |
129 +------------+-----------+-----------+-----------+-----------+----------+
130 | mid | or | term | no | yes | yes |
131 +------------+-----------+-----------+-----------+-----------+----------+
132 | mimetype | or | phrase | yes | yes | no |
133 +------------+-----------+-----------+-----------+-----------+----------+
134 | path | or | term | no | yes | yes |
135 +------------+-----------+-----------+-----------+-----------+----------+
136 | property | and | term | yes | yes | yes |
137 +------------+-----------+-----------+-----------+-----------+----------+
138 | subject | and | phrase | yes | yes | yes |
139 +------------+-----------+-----------+-----------+-----------+----------+
140 | tag | and | term | yes | yes | yes |
141 +------------+-----------+-----------+-----------+-----------+----------+
142 | thread | or | term | yes | yes | yes |
143 +------------+-----------+-----------+-----------+-----------+----------+
144 | to | and | phrase | yes | yes | no |
145 +------------+-----------+-----------+-----------+-----------+----------+
152 *Modifiers* refer to any prefixes (first elements of compound queries)
153 that are neither operators nor fields.
155 ``(infix`` *atom* ``)``
156 Interpret *atom* as an infix notmuch query (see
157 :any:`notmuch-search-terms(7)`). Not supported inside fields.
159 ``(matching`` |q1| |q2| ... |qn| ``)`` ``(of`` |q1| |q2| ... |qn| ``)``
160 Match all messages have the same values of the current field as
161 those matching all of |q1| ... |qn|. Supported in most term [#not-path]_ or
162 phrase fields. Most commonly used in the ``thread`` field.
164 ``(query`` *atom* ``)``
165 Expand to the saved query named by *atom*. See
166 :any:`notmuch-config(1)` for more. Note that the saved query must
167 be in infix syntax (:any:`notmuch-search-terms(7)`). Not supported
170 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
171 Interpret *atom* as a POSIX.2 regular expression (see
172 :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
173 phrase fields (see :any:`field-table`).
175 ``(starts-with`` *subword* ``)``
176 Matches any term starting with *subword*. This applies in either
177 phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
178 a ``starts-with`` query cannot be part of a phrase. The
179 atom ``*`` is a synonym for ``(starts-with "")``.
185 Match all messages containing the word "wizard", ignoring case.
188 Match all messages containing "added", but also those containing "add", "additional",
189 "Additional", "adds", etc... via stemming.
192 Match messages containing words "Bob" and "Marley", or their stems
193 The words need not be adjacent.
196 Match messages containing neither "Bob" nor "Marley", nor their stems,
198 ``"quick fox"`` ``quick-fox`` ``quick@fox``
199 Match the *phrase* "quick" followed by "fox" in phrase fields (or
200 outside a field). Match the literal string in a term field.
202 ``(folder (of (id 1234@invalid)))``
203 Match any message in the same folder as the one with Message-Id "1234@invalid"
205 ``(id 1234@invalid blah@test)``
206 Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
208 ``(and (infix "date:2009-11-18..2009-11-18") (tag unread))``
209 Match messages in the given date range with tag unread.
211 ``(starts-with prelim)``
212 Match any words starting with "prelim".
214 ``(subject quick "brown fox")``
215 Match messages whose subject contains "quick" (anywhere, stemmed) and
216 the phrase "brown fox".
218 ``(subject (starts-with prelim))``
219 Matches any word starting with "prelim", inside a message subject.
221 ``(subject (starts-wih quick) "brown fox")``
222 Match messages whose subject contains "quick brown fox", but also
223 "brown fox quicksand".
225 ``(thread (of (id 1234@invalid)))``
226 Match any message in the same thread as the one with Message-Id "1234@invalid"
228 ``(thread (matching (from bob@example.com) (to bob@example.com)))``
229 Match any (messages in) a thread containing a message from
230 "bob@example.com" and a (possibly distinct) message to "bob at
233 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
234 Match in the "To" or "Cc" headers, "bob@example.com",
235 "mallory@example.org", and also "bob@example.com.au" since it
236 contains the adjacent triple "bob", "example", "com".
239 Match messages with an empty or invalid 'To' and 'Cc' field.
242 Match messages with a non-empty List-Id header, assuming
243 configuration ``index.header.List=List-Id``
250 A macro that takes two parameters and applies different fields to them.
254 $ notmuch config set squery.TagSubject '(macro (tagname subj) (and (tag ,tagname) (subject ,subj)))'
255 $ notmuch search --query=sexp '(TagSubject inbox maildir)'
257 Nested macros are allowed.
261 $ notmuch config set squery.Inner '(macro (x) (subject ,x))'
262 $ notmuch config set squery.Outer '(macro (x y) (and (tag ,x) (Inner ,y)))'
263 $ notmuch search --query=sexp '(Outer inbox maildir)'
265 Parameters can be re-used to reduce boilerplate. Any field, including
266 user defined fields is permitted within a macro.
270 $ notmuch config set squery.About '(macro (name) (or (subject ,name) (List ,name)))'
271 $ notmuch search --query=sexp '(About notmuch)'
277 .. [#macro-details] Technically macros impliment lazy evaluation and
278 lexical scope. There is one top level scope
279 containing all macro definitions, but all
280 parameter definitions are local to a given macro.
282 .. [#aka-pref] a.k.a. prefixes
284 .. [#aka-prob] a.k.a. probabilistic prefixes
286 .. [#aka-bool] a.k.a. boolean prefixes
288 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
289 regex queries could only match individual words.
291 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
292 this modifier is not supported in the ``body`` field.
294 .. [#not-path] Due to the way recursive ``path`` queries are implemented
295 in notmuch, this modifier is not supported in the
298 .. |q1| replace:: :math:`q_1`
299 .. |q2| replace:: :math:`q_2`
300 .. |qn| replace:: :math:`q_n`
302 .. |p1| replace:: :math:`p_1`
303 .. |p2| replace:: :math:`p_2`
304 .. |pn| replace:: :math:`p_n`