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 ``(matching`` |q1| |q2| ... |qn| ``)`` ``(of`` |q1| |q2| ... |qn| ``)``
148 Match all messages have the same values of the current field as
149 those matching all of |q1| ... |qn|. Supported in most term [#not-path]_ or
150 phrase fields. Most commonly used in the ``thread`` field.
152 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
153 Interpret *atom* as a POSIX.2 regular expression (see
154 :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
155 phrase fields (see :any:`field-table`).
157 ``(starts-with`` *subword* ``)``
158 Matches any term starting with *subword*. This applies in either
159 phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
160 a ``starts-with`` query cannot be part of a phrase. The
161 atom ``*`` is a synonym for ``(starts-with "")``.
167 Match all messages containing the word "wizard", ignoring case.
170 Match all messages containing "added", but also those containing "add", "additional",
171 "Additional", "adds", etc... via stemming.
174 Match messages containing words "Bob" and "Marley", or their stems
175 The words need not be adjacent.
178 Match messages containing neither "Bob" nor "Marley", nor their stems,
180 ``"quick fox"`` ``quick-fox`` ``quick@fox``
181 Match the *phrase* "quick" followed by "fox" in phrase fields (or
182 outside a field). Match the literal string in a term field.
184 ``(folder (of (id 1234@invalid)))``
185 Match any message in the same folder as the one with Message-Id "1234@invalid"
187 ``(id 1234@invalid blah@test)``
188 Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
190 ``(starts-with prelim)``
191 Match any words starting with "prelim".
193 ``(subject quick "brown fox")``
194 Match messages whose subject contains "quick" (anywhere, stemmed) and
195 the phrase "brown fox".
197 ``(subject (starts-with prelim))``
198 Matches any word starting with "prelim", inside a message subject.
200 ``(subject (starts-wih quick) "brown fox")``
201 Match messages whose subject contains "quick brown fox", but also
202 "brown fox quicksand".
204 ``(thread (of (id 1234@invalid)))``
205 Match any message in the same thread as the one with Message-Id "1234@invalid"
207 ``(thread (matching (from bob@example.com) (to bob@example.com)))``
208 Match any (messages in) a thread containing a message from
209 "bob@example.com" and a (possibly distinct) message to "bob at
212 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
213 Match in the "To" or "Cc" headers, "bob@example.com",
214 "mallory@example.org", and also "bob@example.com.au" since it
215 contains the adjacent triple "bob", "example", "com".
218 Match messages with an empty or invalid 'To' and 'Cc' field.
223 .. [#aka-pref] a.k.a. prefixes
225 .. [#aka-prob] a.k.a. probabilistic prefixes
227 .. [#aka-bool] a.k.a. boolean prefixes
229 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
230 regex queries could only match individual words.
232 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
233 this modifier is not supported in the ``body`` field.
235 .. [#not-path] Due to the way recursive ``path`` queries are implemented
236 in notmuch, this modifier is not supported in the
239 .. |q1| replace:: :math:`q_1`
240 .. |q2| replace:: :math:`q_2`
241 .. |qn| replace:: :math:`q_n`