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
44 Match all messages containing *term*, possibly after stemming or
45 phrase splitting. For discussion of stemming in notmuch see
46 :any:`notmuch-search-terms(7)`. Stemming only applies to unquoted
47 terms (basic values) in s-expression queries. For information on
48 phrase splitting see :any:`fields`.
50 ``(`` *field* |q1| |q2| ... |qn| ``)``
51 Restrict the queries |q1| to |qn| to *field*, and combine with *and*
52 (for most fields) or *or*. See :any:`fields` for more information.
54 ``(`` *operator* |q1| |q2| ... |qn| ``)``
55 Combine queries |q1| to |qn|. Currently supported operators are
56 ``and``, ``or``, and ``not``. ``(not`` |q1| ... |qn| ``)`` is equivalent
57 to ``(and (not`` |q1| ``) ... (not`` |qn| ``))``.
59 ``(`` *modifier* |q1| |q2| ... |qn| ``)``
60 Combine queries |q1| to |qn|, and reinterpret the result (e.g. as a regular expression).
61 See :any:`modifiers` for more information.
69 correspond to attributes of mail messages. Some are inherent (and
70 immutable) like ``subject``, while others ``tag`` and ``property`` are
71 settable by the user. Each concrete field in
72 :any:`the table below <field-table>`
73 is discussed further under "Search prefixes" in
74 :any:`notmuch-search-terms(7)`. The row *user* refers to user defined
75 fields, described in :any:`notmuch-config(1)`.
77 Most fields are either *phrase fields* [#aka-prob]_ (which match
78 sequences of words), or *term fields* [#aka-bool]_ (which match exact
79 strings). *Phrase splitting* breaks the term (basic value or quoted
80 string) into words, ignore punctuation. Phrase splitting is applied to
81 terms in phrase (probabilistic) fields. Both phrase splitting and
82 stemming apply only in phrase fields.
84 Each term or phrase field has an associated combining operator
85 (``and`` or ``or``) used to combine the queries from each element of
86 the tail of the list. This is generally ``or`` for those fields where
87 a message has one such attribute, and ``and`` otherwise.
89 Term or phrase fields can contain arbitrarily complex queries made up
90 from terms, operators, and modifiers, but not other fields.
94 .. table:: Fields with supported modifiers
96 +------------+-----------+-----------+-----------+-----------+----------+
97 | field | combine | type | expand | wildcard | regex |
98 +============+===========+===========+===========+===========+==========+
99 | *none* | and | | no | yes | no |
100 +------------+-----------+-----------+-----------+-----------+----------+
101 | *user* | and | phrase | no | yes | no |
102 +------------+-----------+-----------+-----------+-----------+----------+
103 | attachment | and | phrase | yes | yes | no |
104 +------------+-----------+-----------+-----------+-----------+----------+
105 | body | and | phrase | no | no | no |
106 +------------+-----------+-----------+-----------+-----------+----------+
107 | date | | range | no | no | no |
108 +------------+-----------+-----------+-----------+-----------+----------+
109 | folder | or | phrase | yes | yes | yes |
110 +------------+-----------+-----------+-----------+-----------+----------+
111 | from | and | phrase | yes | yes | yes |
112 +------------+-----------+-----------+-----------+-----------+----------+
113 | id | or | term | no | yes | yes |
114 +------------+-----------+-----------+-----------+-----------+----------+
115 | is | and | term | yes | yes | yes |
116 +------------+-----------+-----------+-----------+-----------+----------+
117 | lastmod | | range | no | no | no |
118 +------------+-----------+-----------+-----------+-----------+----------+
119 | mid | or | term | no | yes | yes |
120 +------------+-----------+-----------+-----------+-----------+----------+
121 | mimetype | or | phrase | yes | yes | no |
122 +------------+-----------+-----------+-----------+-----------+----------+
123 | path | or | term | no | yes | yes |
124 +------------+-----------+-----------+-----------+-----------+----------+
125 | property | and | term | yes | yes | yes |
126 +------------+-----------+-----------+-----------+-----------+----------+
127 | subject | and | phrase | yes | yes | yes |
128 +------------+-----------+-----------+-----------+-----------+----------+
129 | tag | and | term | yes | yes | yes |
130 +------------+-----------+-----------+-----------+-----------+----------+
131 | thread | or | term | yes | yes | yes |
132 +------------+-----------+-----------+-----------+-----------+----------+
133 | to | and | phrase | yes | yes | no |
134 +------------+-----------+-----------+-----------+-----------+----------+
145 Match all messages containing the word "wizard", ignoring case.
148 Match all messages containing "added", but also those containing "add", "additional",
149 "Additional", "adds", etc... via stemming.
152 Match messages containing words "Bob" and "Marley", or their stems
153 The words need not be adjacent.
156 Match messages containing neither "Bob" nor "Marley", nor their stems,
158 ``"quick fox"`` ``quick-fox`` ``quick@fox``
159 Match the *phrase* "quick" followed by "fox" in phrase fields (or
160 outside a field). Match the literal string in a term field.
162 ``(id 1234@invalid blah@test)``
163 Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
165 ``(subject quick "brown fox")``
166 Match messages whose subject contains "quick" (anywhere, stemmed) and
167 the phrase "brown fox".
169 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
170 Match in the "To" or "Cc" headers, "bob@example.com",
171 "mallory@example.org", and also "bob@example.com.au" since it
172 contains the adjacent triple "bob", "example", "com".
177 .. [#aka-pref] a.k.a. prefixes
179 .. [#aka-prob] a.k.a. probabilistic prefixes
181 .. [#aka-bool] a.k.a. boolean prefixes
183 .. |q1| replace:: :math:`q_1`
184 .. |q2| replace:: :math:`q_2`
185 .. |qn| replace:: :math:`q_n`