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