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