mu/man/mu-query.7

.TH MU QUERY 7 "25 October 2017" "User Manuals"

.SH NAME

mu query language \- a language for finding messages in a \fBmu\fR database.

.SH DESCRIPTION

The mu query language is a language that allows for searching in a
\fBmu\fR database and is used by \fBmu find\fR and \fBmu4e\fR to find
messages. The language is similar to the default query-parser that
\fBmu\fR's underlying Xapian database uses, but is a indepedent
\fBmu\fR-specific implementation.

In this manpage, we give a structured but informal overview of the
query language and provide examples.

.de EX1
.nf
.RS
..

.de EX2
.RE
.fi
..


.SH TERMS

The basic building blocks are \fBterms\fR; these are just normal
alphanumerical strings like 'banana' or 'hello' or prefixed with a
field-name.

Some example queries:
.EX1
vacation
subject:capybara
maildir:/inbox
.EX2

Terms without an explicit field-prefix, (like 'vacation' above) are
interpreted as something like:
.EX1
to:vacation or subject:vacation or body:vacation or ... 
.EX2

The language is case-insensitive for terms and attempts to flatten any
diactrics, so \fIangtrom\fR matches \fIÅngström\fR.

.SH LOGICAL OPERATORS

We can combine terms with logical operators -- binary ones: \fBand\fR,
\fBor\fR, \fBxor\fR and the unary \fBnot\fR, with conventional
precedence and association, and case-insensitive. 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
latter 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 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; e.g.
\fBfoo*\fR is equivalent to \fB/foo.*/\fR.

Wildcards and regular expressions can be quite heavy to execute.

.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 (so
\fBsubject:october\fR can be written as \fBs:october\fR) and a
description.

.nf
	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
	msgid,i         Message-ID
	prio,p          Message priority ('low', 'normal' or 'high')
	flag,g          Message Flags
	date,d          Date range
	size,z          Message size range
	embed,e         Search inside embedded text parts (messages, attachments)
	file,j          Attachment filename
	mime,y          MIME-type of one or more message parts
	tag,x           Tags for the message (\fIX-Label\fR and/or \fIX-Keywords\fR)
	list,v          Mailing list (e.g. the List-Id value)
.fi

There are also the special fields \fBcontact\fR, which matches all
contact-fields (\fBfrom\fR, \fBto\fR, \fBcc\fR and \fBbcc\fR), and
\fBrecip\fR, which matches all recipient-fields (\fBto\fR, \fBcc\fR
and \fBbcc\fR).

.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..
e: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:
.nf
	d,draft         Draft Message
	f,flagged       Flagged
	n,new           New message (in new/ Maildir)
	p,passed        Passed ('Handled')
	r,replied       Replied
	s,seen          Seen
	t,trashed       Marked for deletion
	a,attach        Has attachment
	z,signed        Signed message
	x,encrypted     Encrypted message
	l,list          Mailing-list message
.fi

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

.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 AUTHOR

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

.SH "SEE ALSO"

.BR mu-find(1)