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