git.notmuchmail.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 ``(matching`` |q1| |q2| ... |qn| ``)`` ``(of`` |q1| |q2| ... |qn|  ``)``
 148     Match all messages have the same values of the current field as
 149     those matching all of |q1| ... |qn|. Supported in most term [#not-path]_ or
 150     phrase fields. Most commonly used in the ``thread`` field.
 151
 152 ``(regex`` *atom* ``)`` ``(rx`` *atom* ``)``
 153     Interpret *atom* as a POSIX.2 regular expression (see
 154     :manpage:`regex(7)`). This applies in term fields and a subset [#not-phrase]_ of
 155     phrase fields (see :any:`field-table`).
 156
 157 ``(starts-with`` *subword* ``)``
 158     Matches any term starting with *subword*.  This applies in either
 159     phrase or term :any:`fields <fields>`, or outside of fields [#not-body]_. Note that
 160     a ``starts-with`` query cannot be part of a phrase. The
 161     atom ``*`` is a synonym for ``(starts-with "")``.
 162
 163 EXAMPLES
 164 ========
 165
 166 ``Wizard``
 167     Match all messages containing the word "wizard", ignoring case.
 168
 169 ``added``
 170     Match all messages containing "added", but also those containing "add", "additional",
 171     "Additional", "adds", etc... via stemming.
 172
 173 ``(and Bob Marley)``
 174     Match messages containing words "Bob" and "Marley", or their stems
 175     The words need not be adjacent.
 176
 177 ``(not Bob Marley)``
 178     Match messages containing neither "Bob" nor "Marley", nor their stems,
 179
 180 ``"quick fox"`` ``quick-fox`` ``quick@fox``
 181     Match the *phrase* "quick" followed by "fox" in phrase fields (or
 182     outside a field). Match the literal string in a term field.
 183
 184 ``(folder (of (id 1234@invalid)))``
 185     Match any message in the same folder as the one with Message-Id "1234@invalid"
 186
 187 ``(id 1234@invalid blah@test)``
 188     Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
 189
 190 ``(starts-with prelim)``
 191     Match any words starting with "prelim".
 192
 193 ``(subject quick "brown fox")``
 194     Match messages whose subject contains "quick" (anywhere, stemmed) and
 195     the phrase "brown fox".
 196
 197 ``(subject (starts-with prelim))``
 198     Matches any word starting with "prelim", inside a message subject.
 199
 200 ``(subject (starts-wih quick) "brown fox")``
 201     Match messages whose subject contains "quick brown fox", but also
 202     "brown fox quicksand".
 203
 204 ``(thread (of (id 1234@invalid)))``
 205     Match any message in the same thread as the one with Message-Id "1234@invalid"
 206
 207 ``(thread (matching (from bob@example.com) (to bob@example.com)))``
 208     Match any (messages in) a thread containing a message from
 209     "bob@example.com" and a (possibly distinct) message to "bob at
 210     example.com")
 211
 212 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
 213     Match in the "To" or "Cc" headers, "bob@example.com",
 214     "mallory@example.org", and also "bob@example.com.au" since it
 215     contains the adjacent triple "bob", "example", "com".
 216
 217 ``(not (to *))``
 218     Match messages with an empty or invalid 'To' and 'Cc' field.
 219
 220 NOTES
 221 =====
 222
 223 .. [#aka-pref] a.k.a. prefixes
 224
 225 .. [#aka-prob] a.k.a. probabilistic prefixes
 226
 227 .. [#aka-bool] a.k.a. boolean prefixes
 228
 229 .. [#not-phrase] Due to the implemention of phrase fields in Xapian,
 230                  regex queries could only match individual words.
 231
 232 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
 233                this modifier is not supported in the ``body`` field.
 234
 235 .. [#not-path] Due to the way recursive ``path`` queries are implemented
 236                in notmuch, this modifier is not supported in the
 237                ``path`` field.
 238
 239 .. |q1| replace:: :math:`q_1`
 240 .. |q2| replace:: :math:`q_2`
 241 .. |qn| replace:: :math:`q_n`