git.cworth.org Git - notmuch/blob - doc/man7/notmuch-sexp-queries.rst

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