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