1MU QUERY(7) Miscellaneous Information Manual MU QUERY(7)
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
17 query language and provide examples.
18 As a companion to this, we recommend the mu fields and mu flags com‐
21 mands to get an up-to-date list of the available fields and flags.
22 NOTE: if you use queries on the command-line (say, for mu find), you
25 need to quote any characters that would otherwise be interpreted by the
26 shell, such as "", ( and ) and whitespace.
27
30 The basic building blocks of a query are terms; these are just normal
31 words like to just that field. See mu find for all the available
32 fields.
33 Some example queries:
36 vacation
37 subject:capybara
38 maildir:/inbox
39 Terms without an explicit field-prefix, (like 'vacation' above) are in‐
43 terpreted like:
44 to:vacation or subject:vacation or body:vacation or ...
45 The language is case-insensitive for terms and attempts to 'flatten'
49 any diacritics, so angtrom matches Ångström.
50 If terms contain whitespace, they need to be quoted:
53 subject:"hi there"
54 This is a so-called phrase query, which means that we match against
57 subjects that contain the literal phrase "hi there".
58 Remember that you need to escape those quotes when using this from the
61 command-line:
62 mu find subject:\"hi there\"
63
67 We can combine terms with logical operators -- binary ones: and, or,
68 xor and the unary not, with the conventional rules for precedence and
69 association, and are case-insensitive.
70 You can also group things with ( and ), so you can do things like:
74 (subject:beethoven or subject:bach) and not body:elvis
75 If you do not explicitly specify an operator between terms, and is im‐
79 plied, so the queries
80 subject:chip subject:dale
81 subject:chip AND subject:dale
83 are equivalent. For readability, we recommend the second version.
86 Note that a pure not - e.g. searching for not apples is quite a 'heavy'
89 query.
90
93 The language supports matching basic PCRE regular expressions, see
94 pcre(3).
95 Regular expressions are enclosed in //. Some examples:
98 subject:/h.llo/ # match hallo, hello, ...
99 subject:/
100 Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the
104 former matches messages in the '/foo' maildir, while the latter matches
105 all messages in all maildirs that match 'foo', such as '/foo',
106 '/bar/cuux/foo', '/fooishbar' etc.
107 Wildcards are an older mechanism for matching where a term with a
110 rightmost * (and only in that position) matches any term that starts
111 with the part before the *; they are supported for backward compatibil‐
112 ity and mu translates them to regular expressions internally:
113 foo*
114 is equivalent to
117 /foo.*/
118 As a note of caution, certain wild-cards and regular expression can
122 take quite a bit longer than 'normal' queries.
123
126 We already saw a number of search fields, such as subject: and body:.
127 For the full table, see mu-fields(1).
128 bcc,h Bcc (blind-carbon-copy) recipient(s)
129 body,b Message body
130 cc,c Cc (carbon-copy) recipient(s)
131 changed,k Last change to message file (range)
132 date,d Send date (range)
133 embed,e Search inside embedded text parts
134 file,j Attachment filename
135 flag,g Message Flags
136 from,f Message sender
137 list,v Mailing list (e.g. the List-Id value)
138 maildir,m Maildir
139 mime,y MIME-type of one or more message parts
140 msgid,i Message-ID
141 prio,p Message priority (=low=, =normal= or =high=)
142 size,z Message size range
143 subject,s Message subject
144 tag,x Tags for the message
145 thread,w Thread a message belongs to
146 to,t To: recipient(s)
147 The shortcut character can be used instead of the full name:
151 f:foo@bar
152 is the same as
155 from:foo@bar
156 For queries that are not one-off, we would recommend the longer name
159 for readability.
160 There are also the special fields contact:, which matches all contact-
163 fields (from, to, cc and bcc), and recip, which matches all recipient-
164 fields (to, cc and bcc). Hence, for instance,
165 contact:fnorb@example.com
166 is equivalent to
169 (from:fnorb@example.com or to:fnorb@example.com or
170 cc:from:fnorb@example.com or bcc:fnorb@example.com)
171
175 The date: field takes a date-range, expressed as the lower and upper
176 bound, separated by ... Either lower or upper (but not both) can be
177 omitted to create an open range.
178 Dates are expressed in local time and using ISO-8601 format (YYYY-MM-DD
181 HH:MM:SS); you can leave out the right part, and mu adds the rest, de‐
182 pending on whether this is the beginning or end of the range (e.g., as
183 a lower bound, end of the year).
184 You can use '/' , '.', '-' and 'T' to make dates more human readable.
187 Some examples:
190 date:20170505..20170602
191 date:2017-05-05..2017-06-02
192 date:..2017-10-01T12:00
193 date:2015-06-01..
194 date:2016..2016
195 You can also use the special 'dates' now and today:
199 date:20170505..now
200 date:today..
201 Finally, you can use relative 'ago' times which express some time be‐
205 fore now and consist of a number followed by a unit, with units s for
206 seconds, M for minutes, h for hours, d for days, w for week, m for
207 months and y for years. Some examples:
208 date:3m..
210 date:2017.01.01..5w
211
215 The size or z field allows you to match size ranges -- that is, match
216 messages that have a byte-size within a certain range. Units (b (for
217 bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are sup‐
218 ported). Some examples:
219 size:10k..2m
221 size:10m..
222
226 The flag/g field allows you to match message flags. The following
227 fields are available:
228 a,attach Message with attachment
229 d,draft Draft Message
230 f,flagged Flagged
231 l,list Mailing-list message
232 n,new New message (in new/ Maildir)
233 p,passed Passed ('Handled')
234 r,replied Replied
235 s,seen Seen
236 t,trashed Marked for deletion
237 u,unread new OR NOT seen
238 x,encrypted Encrypted message
239 z,signed Signed message
240 Some examples:
244 flag:attach
245 flag:replied
246 g:x
247 Encrypted messages may be signed as well, but this is only visible af‐
251 ter decrypting and thus invisible to mu.
252
255 The message priority field (prio:) has three possible values: low, nor‐
256 mal or high. For instance, to match high-priority messages:
257 prio:high
258
262 The Maildir field describes the directory path starting after the
263 Maildir-base path, and before the /cur/ or /new/ part. So for example,
264 if there's a message with the file name ~/Maildir/lists/run‐
265 ning/cur/1234.213:2,, you could find it (and all the other messages in
266 the same maildir) with:
267 maildir:/lists/running
268 Note the starting ''. If you want to match mails in the 'root' maildir,
272 you can do with a single '':
273 maildir:/
274 If you have maildirs (or any fields) that include spaces, you need to
278 quote them, ie.
279 maildir:"/Sent Items"
280 Note that from the command-line, such queries must be quoted:
284 mu find 'maildir:"/Sent Items"'
285
289 Here are some simple examples of mu queries; you can make many more
290 complicated queries using various logical operators, parentheses and so
291 on, but in the author's experience, it's usually faster to find a mes‐
292 sage with a simple query just searching for some words.
293 Find all messages with both 'bee' and 'bird' (in any field)
296 bee AND bird
297 Find all messages with either Frodo or Sam:
301 Frodo OR Sam
302 Find all messages with the 'wombat' as subject, and 'capybara' any‐
306 where:
307 subject:wombat and capybara
308 Find all messages in the 'Archive' folder from Fred:
312 from:fred and maildir:/Archive
313 Find all unread messages with attachments:
317 flag:attach and flag:unread
318 Find all messages with PDF-attachments:
323 mime:application/pdf
324 Find all messages with attached images:
328 mime:image/*
329
333 With current Xapian versions, the apostroph character is considered
334 part of a word. Thus, you cannot find D'Artagnan by searching for
335 Artagnan. So, include the apostroph in search or use a regexp search.
336 Matching on spaces has changed compared to the old query-parser; this
339 applies e.g. to Maildirs that have spaces in their name, such as Sent
340 Items. See MAILDIR above.
341
344 Please report bugs at https://github.com/djcb/mu/issues.
345
348 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
349
352 This manpage is part of mu 1.10.5.
353 Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL ver‐
356 sion 3 or later https://gnu.org/licenses/gpl.html. This is free soft‐
357 ware: you are free to change and redistribute it. There is NO WARRANTY,
358 to the extent permitted by law.
359
362 mu-find(1), mu-fields(1), *pcre(3)
363 MU QUERY(7)