'\" t
.ftr C B
.TH "MU QUERY" "7" 

.SH "NAME"
.PP
mu-query - a language for finding messages in \fBmu\fP databases.

.SH "DESCRIPTION"
.PP
The mu query language is the language used by \fBmu find\fP and \fBmu4e\fP to find messages
in \fBmu\fP's Xapian database. 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.

.PP
Here, we give a structured but informal overview of the query language and
provide examples. As a companion to this, we recommend the \fBmu fields\fP and \fBmu
flags\fP commands to get an up-to-date list of the available fields and flags.

.PP
Furthermore, \fBmu find\fP provides the \fC\-\-analyze\fP option, which shows how \fBmu\fP
interprets your query; see the \fBANALYZING QUERIES\fP section below.

.PP
\fBNOTE:\fP if you use queries on the command-line (say, for \fBmu find\fP), you need to
quote any characters that would otherwise be interpreted by the shell, such as
\fB""\fP, \fB(\fP and \fB)\fP and whitespace.

.SH "TERMS"
.PP
The basic building blocks of a query are \fBterms\fP; these are just normal words like
`banana' or `hello', or words prefixed with a field-name which makes them apply
to just that field. See \fBmu info fields\fP for all the available fields.

.PP
Some example queries:
.RS
.nf
vacation
subject:capybara
maildir:/inbox

.fi
.RE

.PP
Terms without an explicit field-prefix, (like `vacation' above) are interpreted
like:
.RS
.nf
to:vacation or subject:vacation or body:vacation or ...

.fi
.RE

.PP
The language is case-insensitive for terms and attempts to `flatten' diacritics,
so \fIangtrom\fP matches \fIÅngström\fP.

.PP
If terms contain whitespace, they need to be quoted:
.RS
.nf
subject:"hi there"

.fi
.RE
.PP
This is a so-called \fIphrase query\fP, which means that we match against subjects
that contain the literal phrase "hi there". Phrase queries only work for fields
that are \fIindexed\fP, i.e., fields with \fBindex\fP in the \fBmu info fields\fP search column.

.PP
Remember that you need to escape those quotes when using this from the
command-line:
.RS
.nf
mu find subject:\\"hi there\\"

.fi
.RE

.SH "LOGICAL OPERATORS"
.PP
We can combine terms with logical operators -- binary ones: \fBand\fP, \fBor\fP, \fBxor\fP and the
unary \fBnot\fP, with the conventional rules for precedence and association. The
operators are case-insensitive.

.PP
You can also group things with \fB(\fP and \fB)\fP, so you can write:
.RS
.nf
(subject:beethoven or subject:bach) and not body:elvis

.fi
.RE

.PP
If you do not explicitly specify an operator between terms, \fBand\fP is implied, so
the queries
.RS
.nf
subject:chip subject:dale

.fi
.RE
.RS
.nf
subject:chip AND subject:dale

.fi
.RE
.PP
are equivalent. For readability, we recommend the second version.

.PP
Note that a \fIpure not\fP - e.g. searching for \fBnot apples\fP is quite a `heavy' query.

.SH "REGULAR EXPRESSIONS AND WILDCARDS"
.PP
The language supports matching basic PCRE regular expressions, see \fBpcre(3)\fP.

.PP
Regular expressions are enclosed in \fB//\fP. Some examples:

.RS
.nf
subject:/h.llo/		# match hallo, hello, ...
subject:/

.fi
.RE

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

.PP
Wildcards are another mechanism for matching where a term with a rightmost \fB*\fP
(and \fIonly\fP in that position) matches any term that starts with the part before
the \fB*\fP; they are therefore less powerful than regular expressions, but also much
faster:
.RS
.nf
foo*

.fi
.RE
.PP
is equivalent to
.RS
.nf
/foo.*/

.fi
.RE

.PP
Regular expressions can be useful, but are relatively slow.

.SH "FIELDS"
.PP
We already saw a number of search fields, such as \fBsubject:\fP and \fBbody:\fP. For the
full table with all details, including single-char shortcuts, try the command:
\fCmu info fields\fP.

.RS
.nf
+-----------+----------+----------+-----------------------------+
| flag      | shortcut | category | description                 |
+-----------+----------+----------+-----------------------------+
| draft     | D        | file     | Draft (in progress)         |
+-----------+----------+----------+-----------------------------+
| flagged   | F        | file     | User-flagged                |
+-----------+----------+----------+-----------------------------+
| passed    | P        | file     | Forwarded message           |
+-----------+----------+----------+-----------------------------+
| replied   | R        | file     | Replied-to                  |
+-----------+----------+----------+-----------------------------+
| seen      | S        | file     | Viewed at least once        |
+-----------+----------+----------+-----------------------------+
| trashed   | T        | file     | Marked for deletion         |
+-----------+----------+----------+-----------------------------+
| new       | N        | maildir  | New message                 |
+-----------+----------+----------+-----------------------------+
| signed    | z        | content  | Cryptographically signed    |
+-----------+----------+----------+-----------------------------+
| encrypted | x        | content  | Encrypted                   |
+-----------+----------+----------+-----------------------------+
| attach    | a        | content  | Has at least one attachment |
+-----------+----------+----------+-----------------------------+
| unread    | u        | pseudo   | New or not seen message     |
+-----------+----------+----------+-----------------------------+
| list      | l        | content  | Mailing list message        |
+-----------+----------+----------+-----------------------------+
| personal  | q        | content  | Personal message            |
+-----------+----------+----------+-----------------------------+
| calendar  | c        | content  | Calendar invitation         |
+-----------+----------+----------+-----------------------------+

.fi
.RE

.PP
(*) The language code for the text-body if found. This works only if \fCmu\fP was
built with CLD2 support.

.PP
There are also the special fields \fBcontact:\fP, which matches all contact-fields
(\fIfrom\fP, \fIto\fP, \fIcc\fP and \fIbcc\fP), and \fBrecip\fP, which matches all recipient-fields (\fIto\fP, \fIcc\fP
and \fIbcc\fP).

.PP
Hence, for instance,
.RS
.nf
contact:fnorb@example.com

.fi
.RE
.PP
is equivalent to
.RS
.nf
(from:fnorb@example.com or to:fnorb@example.com or
      cc:from:fnorb@example.com or bcc:fnorb@example.com)

.fi
.RE

.SH "DATE RANGES"
.PP
The \fBdate:\fP field takes a date-range, expressed as the lower and upper bound,
separated by \fB..\fP. Either lower or upper (but not both) can be omitted to create
an open range.

.PP
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\fP 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).

.PP
You can use `/' , `.', `-', `:' and `T' to make dates more human-readable.

.PP
Some examples:
.RS
.nf
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016

.fi
.RE

.PP
You can also use the special `dates' \fBnow\fP and \fBtoday\fP:
.RS
.nf
date:20170505..now
date:today..

.fi
.RE

.PP
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\fP for seconds, \fBM\fP for minutes,
\fBh\fP for hours, \fBd\fP for days, \fBw\fP for week, \fBm\fP for months and \fBy\fP for years. Some
examples:

.RS
.nf
date:3m..
date:2017.01.01..5w

.fi
.RE

.SH "SIZE RANGES"
.PP
The \fBsize\fP or \fBz\fP field allows you to match \fIsize ranges\fP -- 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:

.RS
.nf
size:10k..2m
size:10m..

.fi
.RE

.SH "FLAG FIELD"
.PP
The \fBflag/g\fP field allows you to match message flags. The following fields are
available:
.RS
.nf
+-----------+----------+----------+-----------------------------+
| flag      | shortcut | category | description                 |
+-----------+----------+----------+-----------------------------+
| draft     | D        | file     | Draft (in progress)         |
+-----------+----------+----------+-----------------------------+
| flagged   | F        | file     | User-flagged                |
+-----------+----------+----------+-----------------------------+
| passed    | P        | file     | Forwarded message           |
+-----------+----------+----------+-----------------------------+
| replied   | R        | file     | Replied-to                  |
+-----------+----------+----------+-----------------------------+
| seen      | S        | file     | Viewed at least once        |
+-----------+----------+----------+-----------------------------+
| trashed   | T        | file     | Marked for deletion         |
+-----------+----------+----------+-----------------------------+
| new       | N        | maildir  | New message                 |
+-----------+----------+----------+-----------------------------+
| signed    | z        | content  | Cryptographically signed    |
+-----------+----------+----------+-----------------------------+
| encrypted | x        | content  | Encrypted                   |
+-----------+----------+----------+-----------------------------+
| attach    | a        | content  | Has at least one attachment |
+-----------+----------+----------+-----------------------------+
| unread    | u        | pseudo   | New or not seen message     |
+-----------+----------+----------+-----------------------------+
| list      | l        | content  | Mailing list message        |
+-----------+----------+----------+-----------------------------+
| personal  | q        | content  | Personal message            |
+-----------+----------+----------+-----------------------------+
| calendar  | c        | content  | Calendar invitation         |
+-----------+----------+----------+-----------------------------+

.fi
.RE

.PP
Some examples:
.RS
.nf
flag:attach
flag:replied
g:x

.fi
.RE

.PP
Encrypted messages may be signed as well, but this is only visible after
decrypting and thus invisible to \fBmu\fP.

.SH "PRIORITY FIELD"
.PP
The message priority field (\fBprio:\fP) has three possible values: \fBlow\fP, \fBnormal\fP or
\fBhigh\fP. For instance, to match high-priority messages:
.RS
.nf
prio:high

.fi
.RE

.SH "MAILDIR"
.PP
The Maildir field describes the directory path starting \fBafter\fP the Maildir root
directory, and before the \fI/cur/\fP or \fI/new/\fP part. So, for example, if there's a
message with the file name \fI~/Maildir/lists/running/cur/1234.213:2,\fP, you could
find it (and all the other messages in that same maildir) with:
.RS
.nf
maildir:/lists/running

.fi
.RE

.PP
Note the starting `/'. If you want to match mails in the `root' maildir, you can
do with a single `/':
.RS
.nf
maildir:/

.fi
.RE

.PP
If you have maildirs (or any fields) that include spaces, you need to quote
them, ie.
.RS
.nf
maildir:"/Sent Items"

.fi
.RE

.PP
And once again, note that when using the command-line, such queries must be
quoted:
.RS
.nf
mu find 'maildir:"/Sent Items"'

.fi
.RE

.PP
Also note that you should \fBnot\fP end the maildir with a \fC/\fP, or it can be
misinterpreted as a regular expression term; see aforementioned.

.SH "MORE EXAMPLES"
.PP
Here are some simple examples of \fBmu\fP 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.

.PP
Find all messages with both `bee' and `bird' (in any field)
.RS
.nf
bee AND bird

.fi
.RE

.PP
Find all messages with either Frodo or Sam:
.RS
.nf
Frodo OR Sam

.fi
.RE

.PP
Find all messages with the `wombat' as subject, and `capybara' anywhere:
.RS
.nf
subject:wombat and capybara

.fi
.RE

.PP
Find all messages in the `Archive' folder from Fred:
.RS
.nf
from:fred and maildir:/Archive

.fi
.RE

.PP
Find all unread messages with attachments:
.RS
.nf
flag:attach and flag:unread

.fi
.RE

.PP
Find all messages with PDF-attachments:
.RS
.nf
mime:application/pdf

.fi
.RE

.PP
Find all messages with attached images:
.RS
.nf
mime:image/*

.fi
.RE

.PP
Find all messages written in Dutch or German with the word `hallo':
.RS
.nf
hallo and (lang:nl or lang:de)

.fi
.RE

.PP
This is only available if your \fBmu\fP has support for this; see \fBmu info\fP and check
for "cld2-support*.

.SH "ANALZYING QUERIES"
.PP
Despite all the excellent documentation, in some cases it can be non-obvious how
\fCmu\fP interprets your query. For that, you can ask \fCmu\fP to analyze the query -- that
is, show how \fCmu\fP interprets the query.

.PP
This uses the the \fC\-\-analyze\fP option to \fBmu find\fP.
.RS
.nf
$ mu find subject:wombat AND date:3m.. size:..2000  --analyze
* query:
  subject:wombat AND date:3m.. size:..2000
* parsed query:
  (and (subject "wombat") (date (range "2023-05-30T06:10:09Z" "")) (size (range "" "2000")))
* Xapian query:
  Query((Swombat AND VALUE_GE 4 n64759341 AND VALUE_LE 17 i7d0))

.fi
.RE

.PP
The \fCparsed query\fP is usually the most useful one for understanding how \fBmu\fP
interprets your query.

.SH "REPORTING BUGS"
.PP
Please report bugs at \fIhttps://github.com/djcb/mu/issues\fP.

.SH "AUTHOR"
.PP
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

.SH "COPYRIGHT"
.PP
This manpage is part of \fCmu\fP 1.12.3.

.PP
Copyright © 2008-2024 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3
or later \fIhttps://gnu.org/licenses/gpl.html\fP. This is free software: you are
free to change and redistribute it. There is NO WARRANTY, to the extent
permitted by law.

.SH "SEE ALSO"
.PP
\fBmu-find(1)\fP, \fBmu-info(1), *pcre(3)\fP