mirror of https://github.com/djcb/mu.git
360 lines
9.4 KiB
Groff
360 lines
9.4 KiB
Groff
.TH MU QUERY 7 "22 April 2022" "User Manuals"
|
|
|
|
.SH NAME
|
|
|
|
mu query language \- a language for finding messages in \fBmu\fR databases.
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The mu query language is a language used by \fBmu find\fR and \fBmu4e\fR to find
|
|
messages in \fBmu\fR's Xapian databases. The language is quite similar to
|
|
Xapian's default query-parser, but is an independent implementation that is
|
|
customized for the mu/mu4e use-case.
|
|
|
|
In this article, we give a structured but informal overview of the query
|
|
language and provide examples.
|
|
|
|
As a companion to this, we recommend the \fBmu fields\fR command to get an up-to-date list of the available fields.
|
|
|
|
\fBNOTE:\fR if you use queries on the command-line (say, for \fBmu find\fR), you
|
|
need to quote any characters that would otherwise be interpreted by the shell,
|
|
such as \fB""\fR, \fB(\fR and \fB)\fR and whitespace.
|
|
|
|
.de EX1
|
|
.nf
|
|
.RS
|
|
..
|
|
|
|
.de EX2
|
|
.RE
|
|
.fi
|
|
..
|
|
|
|
.SH TERMS
|
|
|
|
The basic building blocks of a query are \fBterms\fR; these are just
|
|
normal words like 'banana' or 'hello', or words prefixed with a
|
|
field-name which make them apply to just that field. See
|
|
\fBmu find\fR
|
|
for all the available fields.
|
|
|
|
Some example queries:
|
|
.EX1
|
|
vacation
|
|
subject:capybara
|
|
maildir:/inbox
|
|
.EX2
|
|
|
|
Terms without an explicit field-prefix, (like 'vacation' above) are
|
|
interpreted like:
|
|
.EX1
|
|
to:vacation or subject:vacation or body:vacation or ...
|
|
.EX2
|
|
|
|
The language is case-insensitive for terms and attempts to 'flatten'
|
|
any diacritics, so \fIangtrom\fR matches \fIÅngström\fR.
|
|
|
|
.PP
|
|
If terms contain whitespace, they need to be quoted:
|
|
.EX1
|
|
subject:"hi there"
|
|
.EX2
|
|
This is a so-called \fIphrase query\fR, which means that we match
|
|
against subjects that contain the literal phrase "hi there".
|
|
|
|
Remember that you need to escape those quotes when using this from the
|
|
command-line:
|
|
.EX1
|
|
mu find subject:\\"hi there\\"
|
|
.EX2
|
|
|
|
.SH LOGICAL OPERATORS
|
|
|
|
We can combine terms with logical operators -- binary ones: \fBand\fR,
|
|
\fBor\fR, \fBxor\fR and the unary \fBnot\fR, with the conventional
|
|
rules for precedence and association, and are case-insensitive.
|
|
|
|
.PP
|
|
You can also group things with \fB(\fR and \fB)\fR, so you can do
|
|
things like:
|
|
.EX1
|
|
(subject:beethoven or subject:bach) and not body:elvis
|
|
.EX2
|
|
|
|
If you do not explicitly specify an operator between terms, \fBand\fR
|
|
is implied, so the queries
|
|
.EX1
|
|
subject:chip subject:dale
|
|
.EX2
|
|
.EX1
|
|
subject:chip AND subject:dale
|
|
.EX2
|
|
are equivalent. For readability, we recommend the second version.
|
|
|
|
Note that a \fIpure not\fR - e.g. searching for \fBnot apples\fR is
|
|
quite a 'heavy' query.
|
|
|
|
.SH REGULAR EXPRESSIONS AND WILDCARDS
|
|
|
|
The language supports matching regular expressions that follow
|
|
ECMAScript; for details, see
|
|
|
|
.BR http://www.cplusplus.com/reference/regex/ECMAScript/
|
|
|
|
Regular expressions must be enclosed in \fB//\fR. Some examples:
|
|
.EX1
|
|
subject:/h.llo/ # match hallo, hello, ...
|
|
subject:/
|
|
.EX2
|
|
|
|
Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the
|
|
former matches messages in the '/foo' maildir, while the latter
|
|
matches all messages in all maildirs that match 'foo', such
|
|
as '/foo', '/bar/cuux/foo', '/fooishbar' etc.
|
|
|
|
Wildcards are an older mechanism for matching where a term with a
|
|
rightmost \fB*\fR (and \fIonly\fR in that position) matches any term
|
|
that starts with the part before the \fB*\fR; they are supported for
|
|
backward compatibility and \fBmu\fR translates them to regular
|
|
expressions internally:
|
|
.EX1
|
|
foo*
|
|
.EX2
|
|
is equivalent to
|
|
.EX1
|
|
/foo.*/
|
|
.EX2
|
|
|
|
As a note of caution, certain wild-cards and regular expression can
|
|
take quite a bit longer than 'normal' queries.
|
|
|
|
.SH FIELDS
|
|
|
|
We already saw a number of search fields, such as \fBsubject:\fR and
|
|
\fBbody:\fR. Here is the full table, a shortcut character and a description.
|
|
.EX1
|
|
cc,c Cc (carbon-copy) recipient(s)
|
|
bcc,h Bcc (blind-carbon-copy) recipient(s)
|
|
from,f Message sender
|
|
to,t To: recipient(s)
|
|
subject,s Message subject
|
|
body,b Message body
|
|
maildir,m Maildir
|
|
modified,k Last modification time
|
|
msgid,i Message-ID
|
|
prio,p Message priority (\fIlow\fR, \fInormal\fR or \fIhigh\fR)
|
|
flag,g Message Flags
|
|
date,d Date range
|
|
size,z Message size range
|
|
embed,e Search inside embedded text parts
|
|
file,j Attachment filename
|
|
mime,y MIME-type of one or more message parts
|
|
tag,x Tags for the message
|
|
list,v Mailing list (e.g. the List-Id value)
|
|
|
|
The \fBmu fields\fR command is recommended to get the latest version.
|
|
.EX2
|
|
The shortcut character can be used instead of the full name:
|
|
.EX1
|
|
f:foo@bar
|
|
.EX2
|
|
is the same as
|
|
.EX1
|
|
from:foo@bar
|
|
.EX2
|
|
For queries that are not one-off, we would recommend the longer name
|
|
for readability.
|
|
|
|
There are also the special fields \fBcontact:\fR, which matches all
|
|
contact-fields (\fIfrom\fR, \fIto\fR, \fIcc\fR and \fIbcc\fR), and
|
|
\fBrecip\fR, which matches all recipient-fields (\fIto\fR, \fIcc\fR
|
|
and \fIbcc\fR). Hence, for instance,
|
|
.EX1
|
|
contact:fnorb@example.com
|
|
.EX2
|
|
is equivalent to
|
|
.EX1
|
|
(from:fnorb@example.com or to:fnorb@example.com or
|
|
cc:from:fnorb@example.com or bcc:fnorb@example.com)
|
|
.EX2
|
|
|
|
.SH DATE RANGES
|
|
|
|
The \fBdate:\fR field takes a date-range, expressed as the lower and
|
|
upper bound, separated by \fB..\fR. Either lower or upper (but not
|
|
both) can be omitted to create an open range.
|
|
|
|
Dates are expressed in local time and using ISO-8601 format
|
|
(YYYY-MM-DD HH:MM:SS); you can leave out the right part, and \fBmu\fR
|
|
adds the rest, depending on whether this is the beginning or end of
|
|
the range (e.g., as a lower bound, '2015' would be interpreted as the
|
|
start of that year; as an upper bound as the end of the year).
|
|
|
|
You can use '/' , '.', '-' and 'T' to make dates more human readable.
|
|
|
|
Some examples:
|
|
.EX1
|
|
date:20170505..20170602
|
|
date:2017-05-05..2017-06-02
|
|
date:..2017-10-01T12:00
|
|
date:2015-06-01..
|
|
date:2016..2016
|
|
.EX2
|
|
|
|
You can also use the special 'dates' \fBnow\fR and \fBtoday\fR:
|
|
.EX1
|
|
date:20170505..now
|
|
date:today..
|
|
.EX2
|
|
|
|
Finally, you can use relative 'ago' times which express some time
|
|
before now and consist of a number followed by a unit, with units
|
|
\fBs\fR for seconds, \fBM\fR for minutes, \fBh\fR for hours, \fBd\fR
|
|
for days, \fBw\fR for week, \fBm\fR for months and \fBy\fR for years.
|
|
Some examples:
|
|
|
|
.EX1
|
|
date:3m..
|
|
date:2017.01.01..5w
|
|
.EX2
|
|
|
|
.SH SIZE RANGES
|
|
|
|
The \fBsize\fR or \fBz\fR field allows you to match \fIsize ranges\fR
|
|
-- that is, match messages that have a byte-size within a certain
|
|
range. Units (b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000
|
|
bytes) are supported). Some examples:
|
|
|
|
.EX1
|
|
size:10k..2m
|
|
size:10m..
|
|
.EX2
|
|
|
|
.SH FLAG FIELDS
|
|
|
|
The \fBflag\fR/\fBg\fR field allows you to match message flags. The
|
|
following fields are available:
|
|
.EX1
|
|
a,attach Message with attachment
|
|
d,draft Draft Message
|
|
f,flagged Flagged
|
|
l,list Mailing-list message
|
|
n,new New message (in new/ Maildir)
|
|
p,passed Passed ('Handled')
|
|
r,replied Replied
|
|
s,seen Seen
|
|
t,trashed Marked for deletion
|
|
u,unread new OR NOT seen
|
|
x,encrypted Encrypted message
|
|
z,signed Signed message
|
|
.EX2
|
|
|
|
Some examples:
|
|
.EX1
|
|
flag:attach
|
|
flag:replied
|
|
g:x
|
|
.EX2
|
|
|
|
Encrypted messages may be signed as well, but this is only visible
|
|
after decrypting and thus, invisible to \fBmu\fR.
|
|
|
|
.SH PRIORITY FIELD
|
|
|
|
The message priority field (\fBprio:\fR) has three possible values:
|
|
\fBlow\fR, \fBnormal\fR or \fBhigh\fR. For instance, to match
|
|
high-priority messages:
|
|
.EX1
|
|
prio:high
|
|
.EX2
|
|
|
|
.SH MAILDIR
|
|
|
|
The Maildir field describes the directory path starting \fBafter\fR
|
|
the Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part.
|
|
So for example, if there's a message with the file name
|
|
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and
|
|
all the other messages in the same maildir) with:
|
|
.EX1
|
|
maildir:/lists/running
|
|
.EX2
|
|
|
|
Note the starting '/'. If you want to match mails in the 'root'
|
|
maildir, you can do with a single '/':
|
|
.EX1
|
|
maildir:/
|
|
.EX2
|
|
|
|
If you have maildirs (or any fields) that include spaces, you need to
|
|
quote them, ie.
|
|
.EX1
|
|
maildir:"/Sent Items"
|
|
.EX2
|
|
|
|
Note that from the command-line, such queries must be quoted:
|
|
.EX1
|
|
mu find 'maildir:"/Sent Items"'
|
|
.EX2
|
|
|
|
.SH MORE EXAMPLES
|
|
|
|
Here are some simple examples of \fBmu\fR queries; you can make many
|
|
more complicated queries using various logical operators, parentheses
|
|
and so on, but in the author's experience, it's usually faster to find
|
|
a message with a simple query just searching for some words.
|
|
|
|
Find all messages with both 'bee' and 'bird' (in any field)
|
|
.EX1
|
|
bee AND bird
|
|
.EX2
|
|
|
|
Find all messages with either Frodo or Sam:
|
|
.EX1
|
|
Frodo OR Sam
|
|
.EX2
|
|
|
|
Find all messages with the 'wombat' as subject, and 'capibara' anywhere:
|
|
.EX1
|
|
subject:wombat and capibara
|
|
.EX2
|
|
|
|
Find all messages in the 'Archive' folder from Fred:
|
|
.EX1
|
|
from:fred and maildir:/Archive
|
|
.EX2
|
|
|
|
Find all unread messages with attachments:
|
|
.EX1
|
|
flag:attach and flag:unread
|
|
.EX2
|
|
|
|
|
|
Find all messages with PDF-attachments:
|
|
.EX1
|
|
mime:application/pdf
|
|
.EX2
|
|
|
|
Find all messages with attached images:
|
|
.EX1
|
|
mime:image/*
|
|
.EX2
|
|
|
|
.SH CAVEATS
|
|
|
|
With current Xapian versions, the apostroph character is considered
|
|
part of a word. Thus, you cannot find \fID'Artagnan\fR by searching
|
|
for \fIArtagnan\fR. So, include the apostroph in search or use a
|
|
regexp search.
|
|
|
|
Matching on spaces has changed compared to the old query-parser; this
|
|
applies e.g. to Maildirs that have spaces in their name, such as
|
|
\fISent Items\fR. See \fBMAILDIR\fR above.
|
|
|
|
.SH AUTHOR
|
|
|
|
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR mu-find (1)
|