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     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 Each term or phrase field has an associated combining operator
  85 (``and`` or ``or``) used to combine the queries from each element of
  86 the tail of the list. This is generally ``or`` for those fields where
  87 a message has one such attribute, and ``and`` otherwise.
  88
  89 Term or phrase fields can contain arbitrarily complex queries made up
  90 from terms, operators, and modifiers, but not other fields.
  91
  92 .. _field-table:
  93
  94 .. table:: Fields with supported modifiers
  95
  96   +------------+-----------+-----------+-----------+-----------+----------+
  97   |   field    |  combine  |   type    |  expand   | wildcard  |  regex   |
  98   +============+===========+===========+===========+===========+==========+
  99   |   *none*   |    and    |           |    no     |    yes    |    no    |
 100   +------------+-----------+-----------+-----------+-----------+----------+
 101   |   *user*   |    and    |  phrase   |    no     |    yes    |    no    |
 102   +------------+-----------+-----------+-----------+-----------+----------+
 103   | attachment |    and    |  phrase   |    yes    |    yes    |    no    |
 104   +------------+-----------+-----------+-----------+-----------+----------+
 105   |    body    |    and    |  phrase   |    no     |    no     |    no    |
 106   +------------+-----------+-----------+-----------+-----------+----------+
 107   |    date    |           |   range   |    no     |    no     |    no    |
 108   +------------+-----------+-----------+-----------+-----------+----------+
 109   |   folder   |    or     |  phrase   |    yes    |    yes    |   yes    |
 110   +------------+-----------+-----------+-----------+-----------+----------+
 111   |    from    |    and    |  phrase   |    yes    |    yes    |   yes    |
 112   +------------+-----------+-----------+-----------+-----------+----------+
 113   |     id     |    or     |   term    |    no     |    yes    |   yes    |
 114   +------------+-----------+-----------+-----------+-----------+----------+
 115   |     is     |    and    |   term    |    yes    |    yes    |   yes    |
 116   +------------+-----------+-----------+-----------+-----------+----------+
 117   |  lastmod   |           |   range   |    no     |    no     |    no    |
 118   +------------+-----------+-----------+-----------+-----------+----------+
 119   |    mid     |    or     |   term    |    no     |    yes    |   yes    |
 120   +------------+-----------+-----------+-----------+-----------+----------+
 121   |  mimetype  |    or     |  phrase   |    yes    |    yes    |    no    |
 122   +------------+-----------+-----------+-----------+-----------+----------+
 123   |    path    |    or     |   term    |    no     |    yes    |   yes    |
 124   +------------+-----------+-----------+-----------+-----------+----------+
 125   |  property  |    and    |   term    |    yes    |    yes    |   yes    |
 126   +------------+-----------+-----------+-----------+-----------+----------+
 127   |  subject   |    and    |  phrase   |    yes    |    yes    |   yes    |
 128   +------------+-----------+-----------+-----------+-----------+----------+
 129   |    tag     |    and    |   term    |    yes    |    yes    |   yes    |
 130   +------------+-----------+-----------+-----------+-----------+----------+
 131   |   thread   |    or     |   term    |    yes    |    yes    |   yes    |
 132   +------------+-----------+-----------+-----------+-----------+----------+
 133   |     to     |    and    |  phrase   |    yes    |    yes    |    no    |
 134   +------------+-----------+-----------+-----------+-----------+----------+
 135
 136 .. _modifiers:
 137
 138 MODIFIERS
 139 `````````
 140
 141 EXAMPLES
 142 ========
 143
 144 ``Wizard``
 145     Match all messages containing the word "wizard", ignoring case.
 146
 147 ``added``
 148     Match all messages containing "added", but also those containing "add", "additional",
 149     "Additional", "adds", etc... via stemming.
 150
 151 ``(and Bob Marley)``
 152     Match messages containing words "Bob" and "Marley", or their stems
 153     The words need not be adjacent.
 154
 155 ``(not Bob Marley)``
 156     Match messages containing neither "Bob" nor "Marley", nor their stems,
 157
 158 ``"quick fox"`` ``quick-fox`` ``quick@fox``
 159     Match the *phrase* "quick" followed by "fox" in phrase fields (or
 160     outside a field). Match the literal string in a term field.
 161
 162 ``(id 1234@invalid blah@test)``
 163     Matches Message-Id "1234@invalid" *or* Message-Id "blah@test"
 164
 165 ``(starts-with prelim)``
 166     Match any words starting with "prelim".
 167
 168 ``(subject quick "brown fox")``
 169     Match messages whose subject contains "quick" (anywhere, stemmed) and
 170     the phrase "brown fox".
 171
 172 ``(subject (starts-with prelim))``
 173     Matches any word starting with "prelim", inside a message subject.
 174
 175 ``(subject (starts-wih quick) "brown fox")``
 176     Match messages whose subject contains "quick brown fox", but also
 177     "brown fox quicksand".
 178
 179 ``(to (or bob@example.com mallory@example.org))`` ``(or (to bob@example.com) (to mallory@example.org))``
 180     Match in the "To" or "Cc" headers, "bob@example.com",
 181     "mallory@example.org", and also "bob@example.com.au" since it
 182     contains the adjacent triple "bob", "example", "com".
 183
 184 NOTES
 185 =====
 186
 187 .. [#aka-pref] a.k.a. prefixes
 188
 189 .. [#aka-prob] a.k.a. probabilistic prefixes
 190
 191 .. [#aka-bool] a.k.a. boolean prefixes
 192
 193 .. [#not-body] Due the the way ``body`` is implemented in notmuch,
 194                this modifier is not supported in the ``body`` field.
 195
 196 .. |q1| replace:: :math:`q_1`
 197 .. |q2| replace:: :math:`q_2`
 198 .. |qn| replace:: :math:`q_n`