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 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
148 Interpret *atom* as a POSIX.2 regular expression (see
149 :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
150 phrase fields (see :any:`field-table`).
152 ``(starts-with`` *subword* ``)``
153 Matches any term starting with *subword*. This applies in either
154 phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
155 a ``starts-with`` query cannot be part of a phrase. The
156 atom ``*`` is a synonym for ``(starts-with "")``.
162 Match all messages containing the word "wizard", ignoring case.
165 Match all messages containing "added", but also those containing "add", "additional",
166 "Additional", "adds", etc... via stemming.
169 Match messages containing words "Bob" and "Marley", or their stems
170 The words need not be adjacent.
173 Match messages containing neither "Bob" nor "Marley", nor their stems,
175 ``"quick fox"`` ``quick-fox`` ``quick@fox``
176 Match the *phrase* "quick" followed by "fox" in phrase fields (or
177 outside a field). Match the literal string in a term field.
179 ``(id 1234@invalid blah@test)``
180 Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
182 ``(starts-with prelim)``
183 Match any words starting with "prelim".
185 ``(subject quick "brown fox")``
186 Match messages whose subject contains "quick" (anywhere, stemmed) and
187 the phrase "brown fox".
189 ``(subject (starts-with prelim))``
190 Matches any word starting with "prelim", inside a message subject.
192 ``(subject (starts-wih quick) "brown fox")``
193 Match messages whose subject contains "quick brown fox", but also
194 "brown fox quicksand".
196 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
197 Match in the "To" or "Cc" headers, "bob@example.com",
198 "mallory@example.org", and also "bob@example.com.au" since it
199 contains the adjacent triple "bob", "example", "com".
202 Match messages with an empty or invalid 'To' and 'Cc' field.
207 .. [#aka-pref] a.k.a. prefixes
209 .. [#aka-prob] a.k.a. probabilistic prefixes
211 .. [#aka-bool] a.k.a. boolean prefixes
213 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
214 regex queries could only match individual words.
216 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
217 this modifier is not supported in the ``body`` field.
219 .. |q1| replace:: :math:`q_1`
220 .. |q2| replace:: :math:`q_2`
221 .. |qn| replace:: :math:`q_n`