xapian-core/docs/queryparser.rst

   1 Xapian::QueryParser Syntax
   2 ==========================
   3
   4 This document describes the query syntax supported by the
   5 Xapian::QueryParser class. The syntax is designed to be similar to other
   6 web based search engines, so that users familiar with them don't have to
   7 learn a whole new syntax.
   8
   9 Operators
  10 ---------
  11
  12 AND
  13 ~~~
  14
  15 *expression* AND *expression* matches documents which are matched by
  16 both of the subexpressions.
  17
  18 OR
  19 ~~
  20
  21 *expression* OR *expression* matches documents which are matched by
  22 either of the subexpressions.
  23
  24 NOT
  25 ~~~
  26
  27 *expression* NOT *expression* matches documents which are matched by
  28 only the first subexpression. This can also be written as *expression*
  29 AND NOT *expression*. If ``FLAG_PURE_NOT`` is enabled, then
  30
  31 NOT *expression* will match documents which don't match the
  32 subexpression.
  33
  34 XOR
  35 ~~~
  36
  37 *expression* XOR *expression* matches documents which are matched by one
  38 or other of the subexpressions, but not both. XOR is probably a bit
  39 esoteric.
  40
  41 Bracketed expressions
  42 ~~~~~~~~~~~~~~~~~~~~~
  43
  44 You can control the precedence of the boolean operators using brackets.
  45 In the query ``one OR two AND three`` the AND takes precedence, so this
  46 is the same as ``one OR (two AND three)``. You can override the
  47 precedence using ``(one OR two) AND three``.
  48
  49 The default precedence from highest to lowest is:
  50
  51 * +, - (equal)
  52 * NEAR, ADJ (equal)
  53 * AND, NOT (equal)
  54 * XOR
  55 * OR
  56
  57
  58 '+' and '-'
  59 ~~~~~~~~~~~
  60
  61 A group of terms with some marked with + and - will match documents
  62 containing all of the + terms, but none of the - terms. Terms not marked
  63 with + or - contribute towards the document rankings. You can also use +
  64 and - on phrases and on bracketed expressions.
  65
  66 NEAR
  67 ~~~~
  68
  69 ``one NEAR two NEAR three`` matches documents containing those words
  70 within 10 words of each other. You can set the threshold to *n* by using
  71 ``NEAR/n`` like so: ``one NEAR/6 two``.
  72
  73 ADJ
  74 ~~~
  75
  76 ``ADJ`` is like ``NEAR`` but only matches if the words appear in the
  77 same order as in the query. So ``one ADJ two ADJ three`` matches
  78 documents containing those three words in that order and within 10 words
  79 of each other. You can set the threshold to *n* by using ``ADJ/n`` like
  80 so: ``one ADJ/6 two``.
  81
  82 Phrase searches
  83 ~~~~~~~~~~~~~~~
  84
  85 A phrase surrounded with double quotes ("") matches documents containing
  86 that exact phrase. Hyphenated words are also treated as phrases, as are
  87 cases such as filenames and email addresses (e.g. ``/etc/passwd`` or
  88 ``president@whitehouse.gov``).
  89
  90 Searching within a free-text field
  91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92
  93 If the database has been indexed with prefixes on terms generated from
  94 certain free-text fields, you can set up a prefix map so that the user can
  95 search within those fields. For example ``author:dickens title:shop``
  96 might find documents by dickens with shop in the title. You can also
  97 specify a prefix on a quoted phrase (e.g. ``author:"charles dickens"``)
  98 or on a bracketed subexpression (e.g. ``title:(mice men)``).
  99
 100 Searching for proper names
 101 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 102
 103 If a query term is entered with a capitalised first letter, then it will
 104 be searched for unstemmed.
 105
 106 Range searches
 107 ~~~~~~~~~~~~~~
 108
 109 The QueryParser `can be configured to support
 110 range-searching <valueranges.html>`_ using document values.
 111
 112 The syntax for a range search is ``start..end`` - for example,
 113 ``01/03/2007..04/04/2007``, ``$10..100``, ``5..10kg``.
 114
 115 Open-ended ranges are also supported - an empty start or end is
 116 interpreted as no limit, for example: ``..2010-06-17``, ``$10..``,
 117 ``$..100``, ``..5kg``.
 118
 119 Synonyms
 120 ~~~~~~~~
 121
 122 The QueryParser can be configured to support synonyms, which can either
 123 be used when explicitly specified (using the syntax ``~term``) or
 124 implicitly (synonyms will be used for all terms or groups of terms for
 125 which they have been specified).
 126
 127 Wildcards
 128 ~~~~~~~~~
 129
 130 The QueryParser supports using a trailing '\*' wildcard, which matches
 131 any number of trailing characters, so ``wildc*`` would match wildcard,
 132 wildcarded, wildcards, wildcat, wildcats, etc. This feature is disabled
 133 by default - pass ``Xapian::QueryParser::FLAG_WILDCARD`` in the flags
 134 argument of ``Xapian::QueryParser::parse_query(query_string, flags)`` to
 135 enable it, and tell the QueryParser which database to expand wildcards
 136 from using the ``QueryParser::set_database(database)`` method.
 137
 138 You can limit the number of terms a wildcard will expand to by
 139 calling ``Xapian::QueryParser::set_max_expansion()``.  This supports
 140 several different modes, and can also be used to limit expansion
 141 performed via ``FLAG_PARTIAL`` - see the API documentation for
 142 details.  By default, there's no limit on wildcard expansion and
 143 ``FLAG_PARTIAL`` expands to the most frequent 100 terms.
 144
 145 Partially entered query matching
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 The QueryParser also supports performing a search with a query which has
 149 only been partially entered. This is intended for use with "incremental
 150 search" systems, which don't wait for the user to finish typing their
 151 search before displaying an initial set of results. For example, in such
 152 a system a user would enter a search, and the system would display a new
 153 set of results after each letter, or whenever the user pauses for a
 154 short period of time (or some other similar strategy).
 155
 156 The problem with this kind of search is that the last word in a
 157 partially entered query often has no semantic relation to the completed
 158 word. For example, a search for "dynamic cat" would return a quite
 159 different set of results to a search for "dynamic categorisation". This
 160 results in the set of results displayed flicking rapidly as each new
 161 character is entered. A much smoother result can be obtained if the
 162 final word is treated as having an implicit terminating wildcard, so
 163 that it matches all words starting with the entered characters - thus,
 164 as each letter is entered, the set of results displayed narrows down to
 165 the desired subject.
 166
 167 A similar effect could be obtained simply by enabling the wildcard
 168 matching option, and appending a "\*" character to each query string.
 169 However, this would be confused by searches which ended with punctuation
 170 or other characters.
 171
 172 This feature is disabled by default - pass
 173 ``Xapian::QueryParser::FLAG_PARTIAL`` flag in the flags argument of
 174 ``Xapian::QueryParser::parse_query(query_string, flags)`` to enable it,
 175 and tell the QueryParser which database to expand wildcards from using
 176 the ``QueryParser::set_database(database)`` method.