Provided by: maildir-utils_1.12.6-1_amd64 
NAME
mu-query - a language for finding messages in mu databases.
DESCRIPTION
The mu query language is the language used by mu find and mu4e to find messages in mu'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.
Here, we give a structured but informal overview of the query language and provide
examples. As a companion to this, we recommend the mu fields and mu flags commands to get
an up-to-date list of the available fields and flags.
Furthermore, mu find provides the --analyze option, which shows how mu interprets your
query; see the ANALYZING QUERIES section below.
NOTE: if you use queries on the command-line (say, for mu find), you need to quote any
characters that would otherwise be interpreted by the shell, such as "", ( and ) and
whitespace.
TERMS
The basic building blocks of a query are terms; 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 mu info fields for all the available fields.
Some example queries:
vacation
subject:capybara
maildir:/inbox
Terms without an explicit field-prefix, (like `vacation' above) are interpreted like:
to:vacation or subject:vacation or body:vacation or ...
The language is case-insensitive for terms and attempts to `flatten' diacritics, so
angtrom matches Ångström.
If terms contain whitespace, they need to be quoted:
subject:"hi there"
This is a so-called phrase query, which means that we match against subjects that contain
the literal phrase "hi there". Phrase queries only work for fields that are indexed, i.e.,
fields with index in the mu info fields search column.
Remember that you need to escape those quotes when using this from the command-line:
mu find subject:\"hi there\"
LOGICAL OPERATORS
We can combine terms with logical operators -- binary ones: and, or, xor and the unary
not, with the conventional rules for precedence and association. The operators are case-
insensitive.
You can also group things with ( and ), so you can write:
(subject:beethoven or subject:bach) and not body:elvis
If you do not explicitly specify an operator between terms, and is implied, so the queries
subject:chip subject:dale
subject:chip AND subject:dale
are equivalent. For readability, we recommend the second version.
Note that a pure not - e.g. searching for not apples is quite a `heavy' query.
REGULAR EXPRESSIONS AND WILDCARDS
The language supports matching basic PCRE regular expressions, see pcre(3).
Regular expressions are enclosed in //. Some examples:
subject:/h.llo/ # match hallo, hello, ...
subject:/
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 another mechanism for matching where a term with a rightmost * (and only in
that position) matches any term that starts with the part before the *; they are therefore
less powerful than regular expressions, but also much faster:
foo*
is equivalent to
/foo.*/
Regular expressions can be useful, but are relatively slow.
FIELDS
We already saw a number of search fields, such as subject: and body:. For the full table
with all details, including single-char shortcuts, try the command: mu info fields.
+-----------+----------+----------+-----------------------------+
| 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 |
+-----------+----------+----------+-----------------------------+
() The language code for the text-body if found. This works only if *mu was built with
CLD2 support.
There are also the special fields contact:, which matches all contact-fields (from, to, cc
and bcc), and recip, which matches all recipient-fields (to, cc and bcc).
Hence, for instance,
contact:fnorb@example.com
is equivalent to
(from:fnorb@example.com or to:fnorb@example.com or
cc:from:fnorb@example.com or bcc:fnorb@example.com)
DATE RANGES
The date: field takes a date-range, expressed as the lower and upper bound, separated by
... 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 mu 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:
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016
You can also use the special `dates' now and today:
date:20170505..now
date:today..
Finally, you can use relative `ago' times which express some time before now and consist
of a number followed by a unit, with units s for seconds, M for minutes, h for hours, d
for days, w for week, m for months and y for years. Some examples:
date:3m..
date:2017.01.01..5w
SIZE RANGES
The size or z field allows you to match size ranges -- 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:
size:10k..2m
size:10m..
FLAG FIELD
The flag/g field allows you to match message flags. The following fields are available:
+-----------+----------+----------+-----------------------------+
| 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 |
+-----------+----------+----------+-----------------------------+
Some examples:
flag:attach
flag:replied
g:x
Encrypted messages may be signed as well, but this is only visible after decrypting and
thus invisible to mu.
PRIORITY FIELD
The message priority field (prio:) has three possible values: low, normal or high. For
instance, to match high-priority messages:
prio:high
MAILDIR
The Maildir field describes the directory path starting after the Maildir root directory,
and before the /cur/ or /new/ part. So, for example, if there's a message with the file
name ~/Maildir/lists/running/cur/1234.213:2,, you could find it (and all the other
messages in that same maildir) with:
maildir:/lists/running
Note the starting `/'. If you want to match mails in the `root' maildir, you can do with a
single `/':
maildir:/
If you have maildirs (or any fields) that include spaces, you need to quote them, ie.
maildir:"/Sent Items"
And once again, note that when using the command-line, such queries must be quoted:
mu find 'maildir:"/Sent Items"'
Also note that you should not end the maildir with a /, or it can be misinterpreted as a
regular expression term; see aforementioned.
MORE EXAMPLES
Here are some simple examples of mu 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)
bee AND bird
Find all messages with either Frodo or Sam:
Frodo OR Sam
Find all messages with the `wombat' as subject, and `capybara' anywhere:
subject:wombat and capybara
Find all messages in the `Archive' folder from Fred:
from:fred and maildir:/Archive
Find all unread messages with attachments:
flag:attach and flag:unread
Find all messages with PDF-attachments:
mime:application/pdf
Find all messages with attached images:
mime:image/*
Find all messages written in Dutch or German with the word `hallo':
hallo and (lang:nl or lang:de)
This is only available if your mu has support for this; see mu info and check for
"cld2-support*.
ANALZYING QUERIES
Despite all the excellent documentation, in some cases it can be non-obvious how mu
interprets your query. For that, you can ask mu to analyze the query -- that is, show how
mu interprets the query.
This uses the the --analyze option to mu find.
$ 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))
The parsed query is usually the most useful one for understanding how mu interprets your
query.
REPORTING BUGS
Please report bugs at https://github.com/djcb/mu/issues.
AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
COPYRIGHT
This manpage is part of mu 1.12.6.
Copyright © 2008-2024 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
https://gnu.org/licenses/gpl.html. This is free software: you are free to change and
redistribute it. There is NO WARRANTY, to the extent permitted by law.
SEE ALSO
mu-find(1), mu-info(1), pcre(3)
MU QUERY(7)