Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MU(QUERY)			 User Manuals			     MU(QUERY)

NAME
       mu query	language - a language for finding messages in mu databases.

DESCRIPTION
       The  mu	query  language	is a language used by mu find and mu4e to find
       messages	in mu'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.

       NOTE:  t	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 make them apply to	just that field. See mufind for	all the	avail-
       able fields.

       Some example queries:
	      vacation
	      subject:capybara
	      maildir:/inbox

       Terms without an	explicit field-prefix, (like 'vacation'	above) are in-
       terpreted like:
	      to:vacation or subject:vacation or body:vacation or ...

       The  language  is  case-insensitive for terms and attempts to 'flatten'
       any diacritics, so angtrom matches _Angstr_A_paragraph_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".

       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, and	are case-insensitive.

       You can also group things with (	and ), so you can do things like:
	      (subject:beethoven or subject:bach) and not body:elvis

       If you do not explicitly	specify	an operator between terms, and is  im-
       plied, 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  regular	expressions  that  follow  EC-
       MAScript; for details, see

       http://www.cplusplus.com/reference/regex/ECMAScript/

       Regular expressions must	be 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 an	older 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 supported for backward compatibil-
       ity and mu translates them to regular expressions internally:
	      foo*
       is equivalent to
	      /foo.*/

       As  a  note  of	caution, certain wild-cards and	regular	expression can
       take quite a bit	longer than 'normal' queries.

FIELDS
       We already saw a	number of search fields, such as subject:  and	body:.
       Here is the full	table, a shortcut character and	a description.
		   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
		   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 shortcut character can be used instead of the full name:
	      f:foo@bar
       is the same as
	      from:foo@bar
       For  queries  that  are not one-off, we would recommend the longer name
       for readabilty.

       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, de-
       pending 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  be-
       fore  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..
	      e: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 sup-
       ported).	Some examples:

	      size:10k..2m
	      size:10m..

FLAG FIELDS
       The flag/g field	allows you  to	match  message	flags.	The  following
       fields are available:
		   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

       Some examples:
	      flag:attach
	      flag:replied
	      g:x

       Encrypted  messages may be signed as well, but this is only visible af-
       ter decrypting and thus,	invisible to mu.

PRIORITY FIELD
       The message priority field (prio:) has three possible values: low, nor-
       mal or high. For	instance, to match high-priority messages:
	       prio:high

MAILDIR
       The  Maildir  field  describes  the  directory  path starting after the
       Maildir-base path, and before the /cur/ or /new/	part.  So for example,
       if   there's   a	  message  with	 the  file  name  ~/Maildir/lists/run-
       ning/cur/1234.213:2,, you could find it (and all	the other messages  in
       the 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"

       Note that from the command-line,	such queries must be quoted:
	      mu find 'maildir:"/Sent Items"'

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 mes-
       sage 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  'capibara'  any-
       where:
	      subject:wombat and capibara

       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/*

CAVEATS
       With  current  Xapian  versions,	 the apostroph character is considered
       part of a word. Thus, you  cannot  find	D'Artagnan  by	searching  for
       Artagnan. 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  Sent
       Items. See MAILDIR above.

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

SEE ALSO
       mu-find(1)

28 December 2017		       7			     MU(QUERY)

NAME | DESCRIPTION | TERMS | LOGICAL OPERATORS | REGULAR EXPRESSIONS AND WILDCARDS | FIELDS | DATE RANGES | SIZE RANGES | FLAG FIELDS | PRIORITY FIELD | MAILDIR | MORE EXAMPLES | CAVEATS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mu-query&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help