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 .. _fields:
  67
  68 FIELDS
  69 ``````
  70
  71 *Fields* [#aka-pref]_
  72 correspond to attributes of mail messages. Some are inherent (and
  73 immutable) like ``subject``, while others ``tag`` and ``property`` are
  74 settable by the user.  Each concrete field in
  75 :any:`the table below <field-table>`
  76 is discussed further under "Search prefixes" in
  77 :any:`notmuch-search-terms(7)`. The row *user* refers to user defined
  78 fields, described in :any:`notmuch-config(1)`.
  79
  80 Most fields are either *phrase fields* [#aka-prob]_ (which match
  81 sequences of words), or *term fields* [#aka-bool]_ (which match exact
  82 strings). *Phrase splitting* breaks the term (basic value or quoted
  83 string) into words, ignore punctuation. Phrase splitting is applied to
  84 terms in phrase (probabilistic) fields. Both phrase splitting and
  85 stemming apply only in phrase fields.
  86
  87 Each term or phrase field has an associated combining operator
  88 (``and`` or ``or``) used to combine the queries from each element of
  89 the tail of the list. This is generally ``or`` for those fields where
  90 a message has one such attribute, and ``and`` otherwise.
  91
  92 Term or phrase fields can contain arbitrarily complex queries made up
  93 from terms, operators, and modifiers, but not other fields.
  94
  95 .. _field-table:
  96
  97 .. table:: Fields with supported modifiers
  98
  99   +------------+-----------+-----------+-----------+-----------+----------+
 100   |   field    |  combine  |   type    |  expand   | wildcard  |  regex   |
 101   +============+===========+===========+===========+===========+==========+
 102   |   *none*   |    and    |           |    no     |    yes    |    no    |
 103   +------------+-----------+-----------+-----------+-----------+----------+
 104   |   *user*   |    and    |  phrase   |    no     |    yes    |    no    |
 105   +------------+-----------+-----------+-----------+-----------+----------+
 106   | attachment |    and    |  phrase   |    yes    |    yes    |    no    |
 107   +------------+-----------+-----------+-----------+-----------+----------+
 108   |    body    |    and    |  phrase   |    no     |    no     |    no    |
 109   +------------+-----------+-----------+-----------+-----------+----------+
 110   |    date    |           |   range   |    no     |    no     |    no    |
 111   +------------+-----------+-----------+-----------+-----------+----------+
 112   |   folder   |    or     |  phrase   |    yes    |    yes    |   yes    |
 113   +------------+-----------+-----------+-----------+-----------+----------+
 114   |    from    |    and    |  phrase   |    yes    |    yes    |   yes    |
 115   +------------+-----------+-----------+-----------+-----------+----------+
 116   |     id     |    or     |   term    |    no     |    yes    |   yes    |
 117   +------------+-----------+-----------+-----------+-----------+----------+
 118   |     is     |    and    |   term    |    yes    |    yes    |   yes    |
 119   +------------+-----------+-----------+-----------+-----------+----------+
 120   |  lastmod   |           |   range   |    no     |    no     |    no    |
 121   +------------+-----------+-----------+-----------+-----------+----------+
 122   |    mid     |    or     |   term    |    no     |    yes    |   yes    |
 123   +------------+-----------+-----------+-----------+-----------+----------+
 124   |  mimetype  |    or     |  phrase   |    yes    |    yes    |    no    |
 125   +------------+-----------+-----------+-----------+-----------+----------+
 126   |    path    |    or     |   term    |    no     |    yes    |   yes    |
 127   +------------+-----------+-----------+-----------+-----------+----------+
 128   |  property  |    and    |   term    |    yes    |    yes    |   yes    |
 129   +------------+-----------+-----------+-----------+-----------+----------+
 130   |  subject   |    and    |  phrase   |    yes    |    yes    |   yes    |
 131   +------------+-----------+-----------+-----------+-----------+----------+
 132   |    tag     |    and    |   term    |    yes    |    yes    |   yes    |
 133   +------------+-----------+-----------+-----------+-----------+----------+
 134   |   thread   |    or     |   term    |    yes    |    yes    |   yes    |
 135   +------------+-----------+-----------+-----------+-----------+----------+
 136   |     to     |    and    |  phrase   |    yes    |    yes    |    no    |
 137   +------------+-----------+-----------+-----------+-----------+----------+
 138
 139 .. _modifiers:
 140
 141 MODIFIERS
 142 `````````
 143
 144 *Modifiers* refer to any prefixes (first elements of compound queries)
 145 that are neither operators nor fields.
 146
 147 ``(infix`` *atom* ``)``
 148     Interpret *atom* as an infix notmuch query (see
 149     :any:`notmuch-search-terms(7)`). Not supported inside fields.
 150
 151 ``(matching`` |q1| |q2| ... |qn| ``)`` ``(of`` |q1| |q2| ... |qn|  ``)``
 152     Match all messages have the same values of the current field as
 153     those matching all of |q1| ... |qn|. Supported in most term [#not-path]_ or
 154     phrase fields. Most commonly used in the ``thread`` field.
 155
 156 ``(query`` *atom* ``)``
 157     Expand to the saved query named by *atom*. See
 158     :any:`notmuch-config(1)` for more. Note that the saved query must
 159     be in infix syntax (:any:`notmuch-search-terms(7)`). Not supported
 160     inside fields.
 161
 162 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
 163     Interpret *atom* as a POSIX.2 regular expression (see
 164     :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
 165     phrase fields (see :any:`field-table`).
 166
 167 ``(starts-with`` *subword* ``)``
 168     Matches any term starting with *subword*.  This applies in either
 169     phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
 170     a ``starts-with`` query cannot be part of a phrase. The
 171     atom ``*`` is a synonym for ``(starts-with "")``.
 172
 173 EXAMPLES
 174 ========
 175
 176 ``Wizard``
 177     Match all messages containing the word "wizard", ignoring case.
 178
 179 ``added``
 180     Match all messages containing "added", but also those containing "add", "additional",
 181     "Additional", "adds", etc... via stemming.
 182
 183 ``(and Bob Marley)``
 184     Match messages containing words "Bob" and "Marley", or their stems
 185     The words need not be adjacent.
 186
 187 ``(not Bob Marley)``
 188     Match messages containing neither "Bob" nor "Marley", nor their stems,
 189
 190 ``"quick fox"`` ``quick-fox`` ``quick@fox``
 191     Match the *phrase* "quick" followed by "fox" in phrase fields (or
 192     outside a field). Match the literal string in a term field.
 193
 194 ``(folder (of (id 1234@invalid)))``
 195     Match any message in the same folder as the one with Message-Id "1234@invalid"
 196
 197 ``(id 1234@invalid blah@test)``
 198     Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
 199
 200 ``(and (infix "date:2009-11-18..2009-11-18") (tag unread))``
 201     Match messages in the given date range with tag unread.
 202
 203 ``(starts-with prelim)``
 204     Match any words starting with "prelim".
 205
 206 ``(subject quick "brown fox")``
 207     Match messages whose subject contains "quick" (anywhere, stemmed) and
 208     the phrase "brown fox".
 209
 210 ``(subject (starts-with prelim))``
 211     Matches any word starting with "prelim", inside a message subject.
 212
 213 ``(subject (starts-wih quick) "brown fox")``
 214     Match messages whose subject contains "quick brown fox", but also
 215     "brown fox quicksand".
 216
 217 ``(thread (of (id 1234@invalid)))``
 218     Match any message in the same thread as the one with Message-Id "1234@invalid"
 219
 220 ``(thread (matching (from bob@example.com) (to bob@example.com)))``
 221     Match any (messages in) a thread containing a message from
 222     "bob@example.com" and a (possibly distinct) message to "bob at
 223     example.com")
 224
 225 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
 226     Match in the "To" or "Cc" headers, "bob@example.com",
 227     "mallory@example.org", and also "bob@example.com.au" since it
 228     contains the adjacent triple "bob", "example", "com".
 229
 230 ``(not (to *))``
 231     Match messages with an empty or invalid 'To' and 'Cc' field.
 232
 233 ``(List *)``
 234     Match messages with a non-empty List-Id header, assuming
 235     configuration ``index.header.List=List-Id``
 236
 237 NOTES
 238 =====
 239
 240 .. [#aka-pref] a.k.a. prefixes
 241
 242 .. [#aka-prob] a.k.a. probabilistic prefixes
 243
 244 .. [#aka-bool] a.k.a. boolean prefixes
 245
 246 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
 247                  regex queries could only match individual words.
 248
 249 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
 250                this modifier is not supported in the ``body`` field.
 251
 252 .. [#not-path] Due to the way recursive ``path`` queries are implemented
 253                in notmuch, this modifier is not supported in the
 254                ``path`` field.
 255
 256 .. |q1| replace:: :math:`q_1`
 257 .. |q2| replace:: :math:`q_2`
 258 .. |qn| replace:: :math:`q_n`