1NOTMUCH-SEXP-QUERIES(7) notmuch NOTMUCH-SEXP-QUERIES(7)
2
6 notmuch-sexp-queries - s-expression syntax for notmuch queries
7
9 notmuch subcommand --query=sexp [option ...] -- '(and (to santa) (date
10 december))'
11
13 Notmuch supports an alternative query syntax based on S-expressions .
14 It can be selected with the command line --query=sexp or with the ap‐
15 propriate option to the library function notmuch_query_create_with_syn‐
16 tax(). Support for this syntax is currently optional, you can test if
17 your build of notmuch supports it with
18 $ notmuch config get built_with.sexpr_query
20 S-EXPRESSIONS
22 An s-expression is either an atom, or list of whitespace delimited
23 s-expressions inside parentheses. Atoms are either
24 basic value
26 A basic value is an unquoted string containing no whitespace,
27 double quotes, or parentheses.
28 quoted string
30 Double quotes (") delimit strings possibly containing whitespace
31 or parentheses. These can contain double quote characters by es‐
32 caping with backslash. E.g. "this is a quote \"".
33 S-EXPRESSION QUERIES
35 An s-expression query is either an atom, the empty list, or a compound
36 query consisting of a prefix atom (first element) defining a field,
37 logical operation, or modifier, and 0 or more subqueries.
38 * "*" matches any non-empty string in the current field.
40 () The empty list matches all messages
42 term
44 Match all messages containing term, possibly after stemming or
45 phrase splitting. For discussion of stemming in notmuch see not‐
46 much-search-terms(7). Stemming only applies to unquoted terms (basic
47 values) in s-expression queries. For information on phrase split‐
48 ting see FIELDS.
49 ( field q_1 q_2 ... q_n )
51 Restrict the queries q_1 to q_n to field, and combine with and
52 (for most fields) or or. See FIELDS for more information.
53 ( operator q_1 q_2 ... q_n )
55 Combine queries q_1 to q_n. Currently supported operators are
56 and, or, and not. (not q_1 ... q_n ) is equivalent to (and (not
57 q_1 ) ... (not q_n )).
58 ( modifier q_1 q_2 ... q_n )
60 Combine queries q_1 to q_n, and reinterpret the result (e.g. as
61 a regular expression). See MODIFIERS for more information.
62 (macro ( p_1 ... p_n ) body)
64 Define saved query with parameter substitution. The syntax is
65 recognized only in saved s-expression queries (see squery.* in
66 notmuch-config(1)). Parameter names in body must be prefixed
67 with , to be expanded (see MACRO EXAMPLES). Macros may refer to
68 other macros, but only to their own parameters [1].
69 FIELDS
71 Fields [2] correspond to attributes of mail messages. Some are inherent
72 (and immutable) like subject, while others tag and property are set‐
73 table by the user. Each concrete field in the table below is discussed
74 further under "Search prefixes" in notmuch-search-terms(7). The row
75 user refers to user defined fields, described in notmuch-config(1).
76 Most fields are either phrase fields [3] (which match sequences of
78 words), or term fields [4] (which match exact strings). Phrase split‐
79 ting breaks the term (basic value or quoted string) into words, ignore
80 punctuation. Phrase splitting is applied to terms in phrase (proba‐
81 bilistic) fields. Both phrase splitting and stemming apply only in
82 phrase fields.
83 Each term or phrase field has an associated combining operator (and or
85 or) used to combine the queries from each element of the tail of the
86 list. This is generally or for those fields where a message has one
87 such attribute, and and otherwise.
88 Term or phrase fields can contain arbitrarily complex queries made up
90 from terms, operators, and modifiers, but not other fields.
91 Fields with supported modifiers
93 ┌───────────┬─────────┬────────┬────────┬──────────┬───────┐
94 │field │ combine │ type │ expand │ wildcard │ regex │
95 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
96 │none │ and │ │ no │ yes │ no │
97 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
98 │user │ and │ phrase │ no │ yes │ no │
99 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
100 │attachment │ and │ phrase │ yes │ yes │ no │
101 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
102 │body │ and │ phrase │ no │ no │ no │
103 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
104 │date │ │ range │ no │ no │ no │
105 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
106 │folder │ or │ phrase │ yes │ yes │ yes │
107 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
108 │from │ and │ phrase │ yes │ yes │ yes │
109 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
110 │id │ or │ term │ no │ yes │ yes │
111 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
112 │is │ and │ term │ yes │ yes │ yes │
113 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
114 │lastmod │ │ range │ no │ no │ no │
115 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
116 │mid │ or │ term │ no │ yes │ yes │
117 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
118 │mimetype │ or │ phrase │ yes │ yes │ no │
119 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
120 │path │ or │ term │ no │ yes │ yes │
121 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
122 │property │ and │ term │ yes │ yes │ yes │
123 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
124 │subject │ and │ phrase │ yes │ yes │ yes │
125 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
126 │tag │ and │ term │ yes │ yes │ yes │
127 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
128 │thread │ or │ term │ yes │ yes │ yes │
129 ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
130 │to │ and │ phrase │ yes │ yes │ no │
131 └───────────┴─────────┴────────┴────────┴──────────┴───────┘
132 MODIFIERS
134 Modifiers refer to any prefixes (first elements of compound queries)
135 that are neither operators nor fields.
136 (infix atom )
138 Interpret atom as an infix notmuch query (see not‐
139 much-search-terms(7)). Not supported inside fields.
140 (matching q_1 q_2 ... q_n ) (of q_1 q_2 ... q_n )
142 Match all messages have the same values of the current field as
143 those matching all of q_1 ... q_n. Supported in most term [7] or
144 phrase fields. Most commonly used in the thread field.
145 (query atom )
147 Expand to the saved query named by atom. See notmuch-config(1)
148 for more. Note that the saved query must be in infix syntax
149 (notmuch-search-terms(7)). Not supported inside fields.
150 (regex atom ) (rx atom )
152 Interpret atom as a POSIX.2 regular expression (see regex(7)).
153 This applies in term fields and a subset [5] of phrase fields
154 (see Fields with supported modifiers).
155 (starts-with subword )
157 Matches any term starting with subword. This applies in either
158 phrase or term fields, or outside of fields [6]. Note that a
159 starts-with query cannot be part of a phrase. The atom * is a
160 synonym for (starts-with "").
161
163 Wizard Match all messages containing the word "wizard", ignoring case.
164 added Match all messages containing "added", but also those containing
166 "add", "additional", "Additional", "adds", etc... via stemming.
167 (and Bob Marley)
169 Match messages containing words "Bob" and "Marley", or their
170 stems The words need not be adjacent.
171 (not Bob Marley)
173 Match messages containing neither "Bob" nor "Marley", nor their
174 stems,
175 "quick fox" quick-fox quick@fox
177 Match the phrase "quick" followed by "fox" in phrase fields (or
178 outside a field). Match the literal string in a term field.
179 (folder (of (id 1234@invalid)))
181 Match any message in the same folder as the one with Message-Id
182 "1234@invalid"
183 (id 1234@invalid blah@test)
185 Matches Message-Id "1234@invalid" or Message-Id "blah@test"
186 (and (infix date:2009-11-18..2009-11-18 ) (tag unread))
188 Match messages in the given date range with tag unread.
189 (starts-with prelim)
191 Match any words starting with "prelim".
192 (subject quick brown fox )
194 Match messages whose subject contains "quick" (anywhere,
195 stemmed) and the phrase "brown fox".
196 (subject (starts-with prelim))
198 Matches any word starting with "prelim", inside a message sub‐
199 ject.
200 (subject (starts-wih quick) brown fox )
202 Match messages whose subject contains "quick brown fox", but
203 also "brown fox quicksand".
204 (thread (of (id 1234@invalid)))
206 Match any message in the same thread as the one with Message-Id
207 "1234@invalid"
208 (thread (matching (from bob@example.com) (to bob@example.com)))
210 Match any (messages in) a thread containing a message from "‐
211 bob@example.com" and a (possibly distinct) message to "bob at
212 example.com")
213 (to (or bob@example.com mallory@example.org)) (or (to bob@example.com)
215 (to mallory@example.org))
216 Match in the "To" or "Cc" headers, "bob@example.com", "‐
217 mallory@example.org", and also "bob@example.com.au" since it
218 contains the adjacent triple "bob", "example", "com".
219 (not (to *))
221 Match messages with an empty or invalid 'To' and 'Cc' field.
222 (List *)
224 Match messages with a non-empty List-Id header, assuming config‐
225 uration index.header.List=List-Id
226 MACRO EXAMPLES
228 A macro that takes two parameters and applies different fields to them.
229 $ notmuch config set squery.TagSubject '(macro (tagname subj) (and (tag ,tagname) (subject ,subj)))'
231 $ notmuch search --query=sexp '(TagSubject inbox maildir)'
232 Nested macros are allowed.
234 $ notmuch config set squery.Inner '(macro (x) (subject ,x))'
236 $ notmuch config set squery.Outer '(macro (x y) (and (tag ,x) (Inner ,y)))'
237 $ notmuch search --query=sexp '(Outer inbox maildir)'
238 Parameters can be re-used to reduce boilerplate. Any field, including
240 user defined fields is permitted within a macro.
241 $ notmuch config set squery.About '(macro (name) (or (subject ,name) (List ,name)))'
243 $ notmuch search --query=sexp '(About notmuch)'
244
246 [1] Technically macros impliment lazy evaluation and lexical scope.
247 There is one top level scope containing all macro definitions, but
248 all parameter definitions are local to a given macro.
249 [2] a.k.a. prefixes
251 [3] a.k.a. probabilistic prefixes
253 [4] a.k.a. boolean prefixes
255 [5] Due to the implemention of phrase fields in Xapian, regex queries
257 could only match individual words.
258 [6] Due the the way body is implemented in notmuch, this modifier is
260 not supported in the body field.
261 [7] Due to the way recursive path queries are implemented in notmuch,
263 this modifier is not supported in the path field.
264
266 Carl Worth and many others
267
269 2009-2021, Carl Worth and many others
2700.34.1 Nov 03, 2021 NOTMUCH-SEXP-QUERIES(7)