1MU(QUERY) User Manuals MU(QUERY)
2
6 mu query language - a language for finding messages in mu databases.
7
10 The mu query language is a language used by mu find and mu4e to find
11 messages in mu's Xapian databases. The language is quite similar to
12 Xapian's default query-parser, but is an independent implementation
13 that is customized for the mu/mu4e use-case.
14 In this article, we give a structured but informal overview of the
16 query language and provide examples.
17 As a companion to this, we recommend the mu fields and mu flags com‐
19 mands to get an up-to-date list of the available fields and flags.
20 NOTE: if you use queries on the command-line (say, for mu find), you
22 need to quote any characters that would otherwise be interpreted by the
23 shell, such as "", ( and ) and whitespace.
24
29 The basic building blocks of a query are terms; these are just normal
30 words like 'banana' or 'hello', or words prefixed with a field-name
31 which make them apply to just that field. See mu find for all the
32 available fields.
33 Some example queries:
35 vacation
36 subject:capybara
37 maildir:/inbox
38 Terms without an explicit field-prefix, (like 'vacation' above) are in‐
40 terpreted like:
41 to:vacation or subject:vacation or body:vacation or ...
42 The language is case-insensitive for terms and attempts to 'flatten'
44 any diacritics, so angtrom matches Ångström.
45 If terms contain whitespace, they need to be quoted:
48 subject:"hi there"
49 This is a so-called phrase query, which means that we match against
50 subjects that contain the literal phrase "hi there".
51 Remember that you need to escape those quotes when using this from the
53 command-line:
54 mu find subject:\"hi there\"
55
58 We can combine terms with logical operators -- binary ones: and, or,
59 xor and the unary not, with the conventional rules for precedence and
60 association, and are case-insensitive.
61 You can also group things with ( and ), so you can do things like:
64 (subject:beethoven or subject:bach) and not body:elvis
65 If you do not explicitly specify an operator between terms, and is im‐
67 plied, so the queries
68 subject:chip subject:dale
69 subject:chip AND subject:dale
70 are equivalent. For readability, we recommend the second version.
71 Note that a pure not - e.g. searching for not apples is quite a 'heavy'
73 query.
74
77 The language supports matching regular expressions that follow EC‐
78 MAScript; for details, see
79 http://www.cplusplus.com/reference/regex/ECMAScript/
81 Regular expressions must be enclosed in //. Some examples:
83 subject:/h.llo/ # match hallo, hello, ...
84 subject:/
85 Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the
87 former matches messages in the '/foo' maildir, while the latter matches
88 all messages in all maildirs that match 'foo', such as '/foo',
89 '/bar/cuux/foo', '/fooishbar' etc.
90 Wildcards are an older mechanism for matching where a term with a
92 rightmost * (and only in that position) matches any term that starts
93 with the part before the *; they are supported for backward compatibil‐
94 ity and mu translates them to regular expressions internally:
95 foo*
96 is equivalent to
97 /foo.*/
98 As a note of caution, certain wild-cards and regular expression can
100 take quite a bit longer than 'normal' queries.
101
104 We already saw a number of search fields, such as subject: and body:.
105 For the full table, see mu fields.
106 bcc,h Bcc (blind-carbon-copy) recipient(s)
107 body,b Message body
108 cc,c Cc (carbon-copy) recipient(s)
109 changed,k Last change to message file (range)
110 date,d Send date (range)
111 embed,e Search inside embedded text parts
112 file,j Attachment filename
113 flag,g Message Flags
114 from,f Message sender
115 list,v Mailing list (e.g. the List-Id value)
116 maildir,m Maildir
117 mime,y MIME-type of one or more message parts
118 msgid,i Message-ID
119 prio,p Message priority (low, normal or high)
120 size,z Message size range
121 subject,s Message subject
122 tag,x Tags for the message
123 thread,w Thread a message belongs to
124 to,t To: recipient(s)
125 The mu fields command is recommended to get the latest version.
127 The shortcut character can be used instead of the full name:
128 f:foo@bar
129 is the same as
130 from:foo@bar
131 For queries that are not one-off, we would recommend the longer name
132 for readability.
133 There are also the special fields contact:, which matches all contact-
135 fields (from, to, cc and bcc), and recip, which matches all recipient-
136 fields (to, cc and bcc). Hence, for instance,
137 contact:fnorb@example.com
138 is equivalent to
139 (from:fnorb@example.com or to:fnorb@example.com or
140 cc:from:fnorb@example.com or bcc:fnorb@example.com)
141
144 The date: field takes a date-range, expressed as the lower and upper
145 bound, separated by ... Either lower or upper (but not both) can be
146 omitted to create an open range.
147 Dates are expressed in local time and using ISO-8601 format (YYYY-MM-DD
149 HH:MM:SS); you can leave out the right part, and mu adds the rest, de‐
150 pending on whether this is the beginning or end of the range (e.g., as
151 a lower bound, '2015' would be interpreted as the start of that year;
152 as an upper bound as the end of the year).
153 You can use '/' , '.', '-' and 'T' to make dates more human readable.
155 Some examples:
157 date:20170505..20170602
158 date:2017-05-05..2017-06-02
159 date:..2017-10-01T12:00
160 date:2015-06-01..
161 date:2016..2016
162 You can also use the special 'dates' now and today:
164 date:20170505..now
165 date:today..
166 Finally, you can use relative 'ago' times which express some time be‐
168 fore now and consist of a number followed by a unit, with units s for
169 seconds, M for minutes, h for hours, d for days, w for week, m for
170 months and y for years. Some examples:
171 date:3m..
173 date:2017.01.01..5w
174
177 The size or z field allows you to match size ranges -- that is, match
178 messages that have a byte-size within a certain range. Units (b (for
179 bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are sup‐
180 ported). Some examples:
181 size:10k..2m
183 size:10m..
184
187 The flag/g field allows you to match message flags. The following
188 fields are available:
189 a,attach Message with attachment
190 d,draft Draft Message
191 f,flagged Flagged
192 l,list Mailing-list message
193 n,new New message (in new/ Maildir)
194 p,passed Passed ('Handled')
195 r,replied Replied
196 s,seen Seen
197 t,trashed Marked for deletion
198 u,unread new OR NOT seen
199 x,encrypted Encrypted message
200 z,signed Signed message
201 Some examples:
203 flag:attach
204 flag:replied
205 g:x
206 Encrypted messages may be signed as well, but this is only visible af‐
208 ter decrypting and thus, invisible to mu.
209
212 The message priority field (prio:) has three possible values: low, nor‐
213 mal or high. For instance, to match high-priority messages:
214 prio:high
215
218 The Maildir field describes the directory path starting after the
219 Maildir-base path, and before the /cur/ or /new/ part. So for example,
220 if there's a message with the file name ~/Maildir/lists/run‐
221 ning/cur/1234.213:2,, you could find it (and all the other messages in
222 the same maildir) with:
223 maildir:/lists/running
224 Note the starting '/'. If you want to match mails in the 'root'
226 maildir, you can do with a single '/':
227 maildir:/
228 If you have maildirs (or any fields) that include spaces, you need to
230 quote them, ie.
231 maildir:"/Sent Items"
232 Note that from the command-line, such queries must be quoted:
234 mu find 'maildir:"/Sent Items"'
235
238 Here are some simple examples of mu queries; you can make many more
239 complicated queries using various logical operators, parentheses and so
240 on, but in the author's experience, it's usually faster to find a mes‐
241 sage with a simple query just searching for some words.
242 Find all messages with both 'bee' and 'bird' (in any field)
244 bee AND bird
245 Find all messages with either Frodo or Sam:
247 Frodo OR Sam
248 Find all messages with the 'wombat' as subject, and 'capybara' any‐
250 where:
251 subject:wombat and capybara
252 Find all messages in the 'Archive' folder from Fred:
254 from:fred and maildir:/Archive
255 Find all unread messages with attachments:
257 flag:attach and flag:unread
258 Find all messages with PDF-attachments:
261 mime:application/pdf
262 Find all messages with attached images:
264 mime:image/*
265
268 With current Xapian versions, the apostroph character is considered
269 part of a word. Thus, you cannot find D'Artagnan by searching for
270 Artagnan. So, include the apostroph in search or use a regexp search.
271 Matching on spaces has changed compared to the old query-parser; this
273 applies e.g. to Maildirs that have spaces in their name, such as Sent
274 Items. See MAILDIR above.
275
278 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
279
282 mu-find(1) mu-fields(1)
28322 April 2022 7 MU(QUERY)