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