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     Match all messages.
  41
  42 *term*
  43
  44     Match all messages containing *term*, possibly after stemming or
  45     phrase splitting. For discussion of stemming in notmuch see
  46     :any:`notmuch-search-terms(7)`. Stemming only applies to unquoted
  47     terms (basic values) in s-expression queries.  For information on
  48     phrase splitting see :any:`fields`.
  49
  50 ``(`` *field* |q1| |q2| ... |qn| ``)``
  51     Restrict the queries |q1| to |qn| to *field*, and combine with *and*
  52     (for most fields) or *or*. See :any:`fields` for more information.
  53
  54 ``(`` *operator* |q1| |q2| ... |qn| ``)``
  55     Combine queries |q1| to |qn|. Currently supported operators are
  56     ``and``, ``or``, and ``not``. ``(not`` |q1| ... |qn| ``)`` is equivalent
  57     to ``(and (not`` |q1| ``) ... (not`` |qn| ``))``.
  58
  59 ``(`` *modifier* |q1| |q2| ... |qn| ``)``
  60     Combine queries |q1| to |qn|, and reinterpret the result (e.g. as a regular expression).
  61     See :any:`modifiers` for more information.
  62
  63 .. _fields:
  64
  65 FIELDS
  66 ``````
  67
  68 *Fields* [#aka-pref]_
  69 correspond to attributes of mail messages. Some are inherent (and
  70 immutable) like ``subject``, while others ``tag`` and ``property`` are
  71 settable by the user.  Each concrete field in
  72 :any:`the table below <field-table>`
  73 is discussed further under "Search prefixes" in
  74 :any:`notmuch-search-terms(7)`. The row *user* refers to user defined
  75 fields, described in :any:`notmuch-config(1)`.
  76
  77 Most fields are either *phrase fields* [#aka-prob]_ (which match
  78 sequences of words), or *term fields* [#aka-bool]_ (which match exact
  79 strings). *Phrase splitting* breaks the term (basic value or quoted
  80 string) into words, ignore punctuation. Phrase splitting is applied to
  81 terms in phrase (probabilistic) fields. Both phrase splitting and
  82 stemming apply only in phrase fields.
  83
  84 .. _field-table:
  85
  86 .. table:: Fields with supported modifiers
  87
  88   +------------+-----------+-----------+-----------+-----------+----------+
  89   |   field    |  combine  |   type    |  expand   | wildcard  |  regex   |
  90   +============+===========+===========+===========+===========+==========+
  91   |   *none*   |    and    |           |    no     |    yes    |    no    |
  92   +------------+-----------+-----------+-----------+-----------+----------+
  93   |   *user*   |    and    |  phrase   |    no     |    yes    |    no    |
  94   +------------+-----------+-----------+-----------+-----------+----------+
  95   | attachment |    and    |  phrase   |    yes    |    yes    |    no    |
  96   +------------+-----------+-----------+-----------+-----------+----------+
  97   |    body    |    and    |  phrase   |    no     |    no     |    no    |
  98   +------------+-----------+-----------+-----------+-----------+----------+
  99   |    date    |           |   range   |    no     |    no     |    no    |
 100   +------------+-----------+-----------+-----------+-----------+----------+
 101   |   folder   |    or     |  phrase   |    yes    |    yes    |   yes    |
 102   +------------+-----------+-----------+-----------+-----------+----------+
 103   |    from    |    and    |  phrase   |    yes    |    yes    |   yes    |
 104   +------------+-----------+-----------+-----------+-----------+----------+
 105   |     id     |    or     |   term    |    no     |    yes    |   yes    |
 106   +------------+-----------+-----------+-----------+-----------+----------+
 107   |     is     |    and    |   term    |    yes    |    yes    |   yes    |
 108   +------------+-----------+-----------+-----------+-----------+----------+
 109   |  lastmod   |           |   range   |    no     |    no     |    no    |
 110   +------------+-----------+-----------+-----------+-----------+----------+
 111   |    mid     |    or     |   term    |    no     |    yes    |   yes    |
 112   +------------+-----------+-----------+-----------+-----------+----------+
 113   |  mimetype  |    or     |  phrase   |    yes    |    yes    |    no    |
 114   +------------+-----------+-----------+-----------+-----------+----------+
 115   |    path    |    or     |   term    |    yes    |    yes    |   yes    |
 116   +------------+-----------+-----------+-----------+-----------+----------+
 117   |  property  |    and    |   term    |    yes    |    yes    |   yes    |
 118   +------------+-----------+-----------+-----------+-----------+----------+
 119   |  subject   |    and    |  phrase   |    yes    |    yes    |   yes    |
 120   +------------+-----------+-----------+-----------+-----------+----------+
 121   |    tag     |    and    |   term    |    yes    |    yes    |   yes    |
 122   +------------+-----------+-----------+-----------+-----------+----------+
 123   |   thread   |    or     |   term    |    yes    |    yes    |   yes    |
 124   +------------+-----------+-----------+-----------+-----------+----------+
 125   |     to     |    and    |  phrase   |    yes    |    yes    |    no    |
 126   +------------+-----------+-----------+-----------+-----------+----------+
 127
 128 .. _modifiers:
 129
 130 MODIFIERS
 131 `````````
 132
 133 EXAMPLES
 134 ========
 135
 136 ``Wizard``
 137     Match all messages containing the word "wizard", ignoring case.
 138
 139 ``added``
 140     Match all messages containing "added", but also those containing "add", "additional",
 141     "Additional", "adds", etc... via stemming.
 142
 143 ``(and Bob Marley)``
 144     Match messages containing words "Bob" and "Marley", or their stems
 145     The words need not be adjacent.
 146
 147 ``(not Bob Marley)``
 148     Match messages containing neither "Bob" nor "Marley", nor their stems,
 149
 150 ``"quick fox"`` ``quick-fox`` ``quick@fox``
 151     Match the *phrase* "quick" followed by "fox" in phrase fields (or
 152     outside a field). Match the literal string in a term field.
 153
 154 ``(subject quick "brown fox")``
 155     Match messages whose subject contains "quick" (anywhere, stemmed) and
 156     the phrase "brown fox".
 157
 158 NOTES
 159 =====
 160
 161 .. [#aka-pref] a.k.a. prefixes
 162
 163 .. [#aka-prob] a.k.a. probabilistic prefixes
 164
 165 .. [#aka-bool] a.k.a. boolean prefixes
 166
 167 .. |q1| replace:: :math:`q_1`
 168 .. |q2| replace:: :math:`q_2`
 169 .. |qn| replace:: :math:`q_n`