git.cworth.org Git - notmuch-wiki/blob - manpages/notmuch-sexp-queries-7.mdwn

   1 <h1>NOTMUCH-SEXP-QUERIES(7)</h1>
   2
   3 <h2>NAME</h2>
   4 <pre>
   5        notmuch-sexp-queries - s-expression syntax for notmuch queries
   6 </pre>
   7
   8 <h2>SYNOPSIS</h2>
   9 <pre>
  10        <b>notmuch</b> <u>subcommand</u> <b>--query=sexp</b> [option ...]  <b>--</b> &apos;(and (to santa) (date
  11        december))&apos;
  12 </pre>
  13
  14 <h2>DESCRIPTION</h2>
  15 <pre>
  16        Notmuch supports an alternative query syntax based on  <u>S-expressions</u>  .
  17        It  can  be selected with the command line <b>--query=sexp</b> or with the ap‐
  18        propriate option to the library function <b>notmuch</b>_<b>query</b>_<b>create</b>_<b>with</b>_<b>syn-</b>
  19        <b>tax()</b>.   Support for this syntax is currently optional, you can test if
  20        your build of notmuch supports it with
  21
  22           $ notmuch config get built_with.sexp_queries
  23 </pre>
  24
  25 <h3> &nbsp; S-EXPRESSIONS</h3>
  26 <pre>
  27        An <u>s-expression</u> is either an atom,  or  list  of  whitespace  delimited
  28        s-expressions inside parentheses. Atoms are either
  29
  30        <u>basic</u> <u>value</u>
  31           A basic value is an unquoted string containing no whitespace, double
  32           quotes, or parentheses.
  33
  34        <u>quoted</u> <u>string</u>
  35           Double quotes (&quot;) delimit strings possibly containing whitespace  or
  36           parentheses.  These  can contain double quote characters by escaping
  37           with backslash. E.g. <b>&quot;this</b> <b>is</b> <b>a</b> <b>quote</b> <b>\&quot;&quot;</b>.
  38 </pre>
  39
  40 <h3> &nbsp; S-EXPRESSION QUERIES</h3>
  41 <pre>
  42        An s-expression query is either an atom, the empty list, or a  <u>compound</u>
  43        <u>query</u>  consisting  of  a  prefix atom (first element) defining a <u>field</u>,
  44        <u>logical</u> <u>operation</u>, or <u>modifier</u>, and 0 or more subqueries.
  45
  46        <b>*</b>
  47           &quot;*&quot; matches any non-empty string in the current field.
  48
  49        <b>()</b>
  50           The empty list matches all messages
  51
  52        <u>term</u>
  53           Match all messages  containing  <u>term</u>,  possibly  after  stemming  or
  54           phrase  splitting.  For  discussion  of stemming in notmuch see <a href='../notmuch-search-terms-7/'>not‐</a>
  55           <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7). Stemming only applies to unquoted terms (basic
  56           values)  in  s-expression queries.  For information on phrase split‐
  57           ting see <u>FIELDS</u>.
  58
  59        <b>(</b> <u>field</u> <u>q</u>1 <u>q</u>2 ... <u>q</u>n <b>)</b>
  60           Restrict the queries <u>q</u>1 to <u>q</u>n to <u>field</u>, and combine  with  <u>and</u>  (for
  61           most fields) or <u>or</u>. See <u>FIELDS</u> for more information.
  62
  63        <b>(</b> <u>operator</u> <u>q</u>1 <u>q</u>2 ... <u>q</u>n <b>)</b>
  64           Combine queries <u>q</u>1 to <u>q</u>n. Currently supported operators are <b>and</b>, <b>or</b>,
  65           and <b>not</b>. <b>(not</b> <u>q</u>1 ... <u>q</u>n <b>)</b> is equivalent to <b>(and</b> <b>(not</b> <u>q</u>1 <b>)</b>  <b>...</b>  <b>(not</b>
  66           <u>q</u>n <b>))</b>.
  67
  68        <b>(</b> <u>modifier</u> <u>q</u>1 <u>q</u>2 ... <u>q</u>n <b>)</b>
  69           Combine queries <u>q</u>1 to <u>q</u>n, and reinterpret the result (e.g. as a reg‐
  70           ular expression).  See <u>MODIFIERS</u> for more information.
  71
  72        <b>(macro</b> <b>(</b> <u>p</u>1 ... <u>p</u>n <b>)</b> <b>body)</b>
  73           Define saved query with parameter substitution. The syntax is recog‐
  74           nized  only  in  saved  s-expression  queries  (see <b>squery.*</b> in <a href='../notmuch-config-1/'>not‐</a>
  75           <a href='../notmuch-config-1/'>much-config</a>(1)). Parameter names in <b>body</b> must be prefixed with <b>,</b>  to
  76           be expanded (see <u>MACRO</u> <u>EXAMPLES</u>).  Macros may refer to other macros,
  77           but only to their own parameters [1].
  78 </pre>
  79
  80 <h3> &nbsp; FIELDS</h3>
  81 <pre>
  82        <u>Fields</u> [2] correspond to attributes of mail messages. Some are inherent
  83        (and  immutable)  like  <b>subject</b>, while others <b>tag</b> and <b>property</b> are set‐
  84        table by the user.  Each concrete field in <u>the</u> <u>table</u> <u>below</u> is discussed
  85        further  under  &quot;Search  prefixes&quot;  in <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7). The row
  86        <u>user</u> refers to user defined fields, described in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
  87
  88        Most fields are either <u>phrase</u> <u>fields</u>  [3]  (which  match  sequences  of
  89        words),  or  <u>term</u> <u>fields</u> [4] (which match exact strings). <u>Phrase</u> <u>split‐</u>
  90        <u>ting</u> breaks the term (basic value or quoted string) into words,  ignore
  91        punctuation.  Phrase  splitting  is  applied to terms in phrase (proba‐
  92        bilistic) fields. Both phrase splitting  and  stemming  apply  only  in
  93        phrase fields.
  94
  95        Each  term or phrase field has an associated combining operator (<b>and</b> or
  96        <b>or</b>) used to combine the queries from each element of the  tail  of  the
  97        list.  This  is  generally  <b>or</b> for those fields where a message has one
  98        such attribute, and <b>and</b> otherwise.
  99
 100        Term or phrase fields can contain arbitrarily complex queries  made  up
 101        from terms, operators, and modifiers, but not other fields.
 102 </pre>
 103
 104 <h3> &nbsp; Fields with supported modifiers</h3>
 105 <pre>
 106              ┌───────────┬─────────┬────────┬────────┬──────────┬───────┐
 107              │field      │ combine │ type   │ expand │ wildcard │ regex │
 108              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 109              │<u>none</u>       │ and     │        │ no     │ yes      │ no    │
 110              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 111              │<u>user</u>       │ and     │ phrase │ no     │ yes      │ no    │
 112              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 113              │attachment │ and     │ phrase │ yes    │ yes      │ no    │
 114              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 115              │body       │ and     │ phrase │ no     │ no       │ no    │
 116              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 117              │date       │         │ range  │ no     │ no       │ no    │
 118              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 119              │folder     │ or      │ phrase │ yes    │ yes      │ yes   │
 120              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 121              │from       │ and     │ phrase │ yes    │ yes      │ yes   │
 122              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 123              │id         │ or      │ term   │ no     │ yes      │ yes   │
 124              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 125              │is         │ and     │ term   │ yes    │ yes      │ yes   │
 126              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 127              │lastmod    │         │ range  │ no     │ no       │ no    │
 128              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 129              │mid        │ or      │ term   │ no     │ yes      │ yes   │
 130              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 131              │mimetype   │ or      │ phrase │ yes    │ yes      │ no    │
 132              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 133              │path       │ or      │ term   │ no     │ yes      │ yes   │
 134              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 135              │property   │ and     │ term   │ yes    │ yes      │ yes   │
 136              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 137              │subject    │ and     │ phrase │ yes    │ yes      │ yes   │
 138              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 139              │tag        │ and     │ term   │ yes    │ yes      │ yes   │
 140              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 141              │thread     │ or      │ term   │ yes    │ yes      │ yes   │
 142              ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
 143              │to         │ and     │ phrase │ yes    │ yes      │ no    │
 144              └───────────┴─────────┴────────┴────────┴──────────┴───────┘
 145 </pre>
 146
 147 <h3> &nbsp; MODIFIERS</h3>
 148 <pre>
 149        <u>Modifiers</u>  refer  to  any prefixes (first elements of compound queries)
 150        that are neither operators nor fields.
 151
 152        <b>(infix</b> <u>atom</u> <b>)</b>
 153           Interpret   <u>atom</u>   as   an   infix   notmuch   query    (see    <a href='../notmuch-search-terms-7/'>not‐</a>
 154           <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7)). Not supported inside fields.
 155
 156        <b>(matching</b> <u>q</u>1 <u>q</u>2 ... <u>q</u>n <b>)</b> <b>(of</b> <u>q</u>1 <u>q</u>2 ... <u>q</u>n  <b>)</b>
 157           Match  all  messages  have  the  same values of the current field as
 158           those matching all of <u>q</u>1 ... <u>q</u>n.  Supported  in  most  term  [7]  or
 159           phrase fields. Most commonly used in the <b>thread</b> field.
 160
 161        <b>(query</b> <u>atom</u> <b>)</b>
 162           Expand  to  the saved query named by <u>atom</u>. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for
 163           more. Note that the saved  query  must  be  in  infix  syntax  (<a href='../notmuch-search-terms-7/'>not‐</a>
 164           <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7)). Not supported inside fields.
 165
 166        <b>(regex</b> <u>atom</u> <b>)</b> <b>(rx</b> <u>atom</u> <b>)</b>
 167           Interpret  <u>atom</u> as a POSIX.2 regular expression (see <b>regex</b>(7)). This
 168           applies in term fields and a subset [5] of phrase fields (see <u>Fields</u>
 169           <u>with</u> <u>supported</u> <u>modifiers</u>).
 170
 171        <b>(starts-with</b> <u>subword</u> <b>)</b>
 172           Matches  any  term  starting  with  <u>subword</u>.  This applies in either
 173           phrase or term <u>fields</u>,  or  outside  of  fields  [6].  Note  that  a
 174           <b>starts-with</b>  query  cannot be part of a phrase. The atom <b>*</b> is a syn‐
 175           onym for <b>(starts-with</b> <b>&quot;&quot;)</b>.
 176 </pre>
 177
 178 <h2>EXAMPLES</h2>
 179 <pre>
 180        <b>Wizard</b>
 181           Match all messages containing the word &quot;wizard&quot;, ignoring case.
 182
 183        <b>added</b>
 184           Match all messages containing &quot;added&quot;,  but  also  those  containing
 185           &quot;add&quot;, &quot;additional&quot;, &quot;Additional&quot;, &quot;adds&quot;, etc... via stemming.
 186
 187        <b>(and</b> <b>Bob</b> <b>Marley)</b>
 188           Match  messages  containing words &quot;Bob&quot; and &quot;Marley&quot;, or their stems
 189           The words need not be adjacent.
 190
 191        <b>(not</b> <b>Bob</b> <b>Marley)</b>
 192           Match messages containing neither  &quot;Bob&quot;  nor  &quot;Marley&quot;,  nor  their
 193           stems,
 194
 195        <b>&quot;quick</b> <b>fox&quot;</b> <b>quick-fox</b> <b>quick@fox</b>
 196           Match the <u>phrase</u> &quot;quick&quot; followed by &quot;fox&quot; in phrase fields (or out‐
 197           side a field). Match the literal string in a term field.
 198
 199        <b>(folder</b> <b>(of</b> <b>(id</b> <b>1234@invalid)))</b>
 200           Match any message in the same folder as the one with  Message-Id  &quot;‐
 201           <u>1234@invalid</u>&quot;
 202
 203        <b>(id</b> <b>1234@invalid</b> <b>blah@test)</b>
 204           Matches Message-Id &quot;<u>1234@invalid</u>&quot; <u>or</u> Message-Id &quot;<u>blah@test</u>&quot;
 205
 206        <b>(and</b> <b>(infix</b> <b>&quot;date:2009-11-18..2009-11-18&quot;)</b> <b>(tag</b> <b>unread))</b>
 207           Match messages in the given date range with tag unread.
 208
 209        <b>(starts-with</b> <b>prelim)</b>
 210           Match any words starting with &quot;prelim&quot;.
 211
 212        <b>(subject</b> <b>quick</b> <b>&quot;brown</b> <b>fox&quot;)</b>
 213           Match  messages  whose  subject contains &quot;quick&quot; (anywhere, stemmed)
 214           and the phrase &quot;brown fox&quot;.
 215
 216        <b>(subject</b> <b>(starts-with</b> <b>prelim))</b>
 217           Matches any word starting with &quot;prelim&quot;, inside a message subject.
 218
 219        <b>(subject</b> <b>(starts-wih</b> <b>quick)</b> <b>&quot;brown</b> <b>fox&quot;)</b>
 220           Match messages whose subject contains &quot;quick brown  fox&quot;,  but  also
 221           &quot;brown fox quicksand&quot;.
 222
 223        <b>(thread</b> <b>(of</b> <b>(id</b> <b>1234@invalid)))</b>
 224           Match  any  message in the same thread as the one with Message-Id &quot;‐
 225           <u>1234@invalid</u>&quot;
 226
 227        <b>(thread</b> <b>(matching</b> <b>(from</b> <b>bob@example.com)</b> <b>(to</b> <b>bob@example.com)))</b>
 228           Match any (messages in)  a  thread  containing  a  message  from  &quot;‐
 229           <u>bob@example.com</u>&quot;  and a (possibly distinct) message to &quot;bob at exam‐
 230           ple.com&quot;)
 231
 232        <b>(to</b> <b>(or</b> <b>bob@example.com</b> <b>mallory@example.org))</b> <b>(or</b> <b>(to</b>  <b>bob@example.com)</b>
 233        <b>(to</b> <b>mallory@example.org))</b>
 234           Match   in   the   &quot;To&quot;   or  &quot;Cc&quot;  headers,  &quot;<u>bob@example.com</u>&quot;,  &quot;‐
 235           <u>mallory@example.org</u>&quot;, and also &quot;<u>bob@example.com.au</u>&quot;  since  it  con‐
 236           tains the adjacent triple &quot;bob&quot;, &quot;example&quot;, &quot;com&quot;.
 237
 238        <b>(not</b> <b>(to</b> <b>*))</b>
 239           Match messages with an empty or invalid &apos;To&apos; and &apos;Cc&apos; field.
 240
 241        <b>(List</b> <b>*)</b>
 242           Match  messages with a non-empty List-Id header, assuming configura‐
 243           tion <b>index.header.List=List-Id</b>
 244 </pre>
 245
 246 <h3> &nbsp; MACRO EXAMPLES</h3>
 247 <pre>
 248        A macro that takes two parameters and applies different fields to them.
 249
 250           $ notmuch config set squery.TagSubject &apos;(macro (tagname subj) (and (tag ,tagname) (subject ,subj)))&apos;
 251           $ notmuch search --query=sexp &apos;(TagSubject inbox maildir)&apos;
 252
 253        Nested macros are allowed.
 254
 255           $ notmuch config set squery.Inner &apos;(macro (x) (subject ,x))&apos;
 256           $ notmuch config set squery.Outer  &apos;(macro (x y) (and (tag ,x) (Inner ,y)))&apos;
 257           $ notmuch search --query=sexp &apos;(Outer inbox maildir)&apos;
 258
 259        Parameters can be re-used to reduce boilerplate. Any  field,  including
 260        user defined fields is permitted within a macro.
 261
 262           $ notmuch config set squery.About &apos;(macro (name) (or (subject ,name) (List ,name)))&apos;
 263           $ notmuch search --query=sexp &apos;(About notmuch)&apos;
 264 </pre>
 265
 266 <h2>NOTES</h2>
 267 <pre>
 268        [1]  Technically  macros  implement  lazy evaluation and lexical scope.
 269             There is one top level scope containing all macro definitions, but
 270             all parameter definitions are local to a given macro.
 271
 272        [2]  a.k.a. prefixes
 273
 274        [3]  a.k.a. probabilistic prefixes
 275
 276        [4]  a.k.a. boolean prefixes
 277
 278        [5]  Due  to the implementation of phrase fields in Xapian, regex queries
 279             could only match individual words.
 280
 281        [6]  Due the the way <b>body</b> is implemented in notmuch, this  modifier  is
 282             not supported in the <b>body</b> field.
 283
 284        [7]  Due  to the way recursive <b>path</b> queries are implemented in notmuch,
 285             this modifier is not supported in the <b>path</b> field.
 286 </pre>
 287
 288 <h2>AUTHOR</h2>
 289 <pre>
 290        Carl Worth and many others
 291 </pre>
 292
 293 <h2>COPYRIGHT</h2>
 294 <pre>
 295        2009-2022, Carl Worth and many others
 296 </pre>
 297
 298 <h2>0.35</h2>