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