.TH "MU QUERY" "7" .SH "NAME" .PP mu\d\s-2query\s+2\u - a language for finding messages in \fBmu\fP databases. .SH "DESCRIPTION" .PP The mu query language is a language used by \fBmu find\fP and \fBmu4e\fP to find messages in \fBmu\fP'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. .PP In this article, we give a structured but informal overview of the query language and provide examples. .PP 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 \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 make them apply to just that field. See \fBmu find\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' any 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". .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, and are case-insensitive. .PP You can also group things with \fB(\fP and \fB)\fP, so you can do things like: .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 an older 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 supported for backward compatibility and \fBmu\fP translates them to regular expressions internally: .RS .nf foo* .fi .RE .PP is equivalent to .RS .nf /foo.*/ .fi .RE .PP As a note of caution, certain wild-cards and regular expression can take quite a bit longer than 'normal' queries. .SH "FIELDS" .PP We already saw a number of search fields, such as \fBsubject:\fP and \fBbody:\fP. For the full table, see \fBmu-fields(1)\fP. .RS .nf bcc,h Bcc (blind-carbon-copy) recipient(s) body,b Message body cc,c Cc (carbon-copy) recipient(s) changed,k Last change to message file (range) date,d Send date (range) embed,e Search inside embedded text parts file,j Attachment filename flag,g Message Flags from,f Message sender list,v Mailing list (e.g. the List-Id value) maildir,m Maildir mime,y MIME-type of one or more message parts msgid,i Message-ID prio,p Message priority (=low=, =normal= or =high=) size,z Message size range subject,s Message subject tag,x Tags for the message thread,w Thread a message belongs to to,t To: recipient(s) .fi .RE .PP The shortcut character can be used instead of the full name: .RS .nf f:foo@bar .fi .RE .PP is the same as .RS .nf from:foo@bar .fi .RE .PP For queries that are not one-off, we would recommend the longer name for readability. .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). 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 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 .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-base path, 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 the same maildir) with: .RS .nf maildir:/lists/running .fi .RE .PP Note the starting '\fI'. If you want to match mails in the 'root' maildir, you can do with a single '\fP': .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 Note that from the command-line, such queries must be quoted: .RS .nf mu find 'maildir:"/Sent Items"' .fi .RE .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 .SH "CAVEATS" .PP With current Xapian versions, the apostroph character is considered part of a word. Thus, you cannot find \fID'Artagnan\fP by searching for \fIArtagnan\fP. So, include the apostroph in search or use a regexp search. .PP 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\fP. See \fBMAILDIR\fP above. .SH "REPORTING BUGS" .PP Please report bugs at \fIhttps://github.com/djcb/mu/issues\fP. .SH "AUTHOR" .PP Dirk-Jan C. Binnema .SH "COPYRIGHT" .PP This manpage is part of \fBmu\fP 1.10.8. .PP Copyright © 2022-2023 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-fields(1), *pcre(3)\fP