<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Xapian::QueryParser Syntax</TITLE>
</HEAD>
<BODY BGCOLOR="white" TEXT="black">
<H1>Xapian::QueryParser Syntax</H1>
<P>This document describes the query syntax supported by the
Xapian::QueryParser class. The syntax is designed to be similar to other web
based search engines, so that users familiar with them don't have to learn
a whole new syntax.
<H2>Operators</H2>
<H3>AND</H3>
<P><i>expression</i> AND <i>expression</i> matches documents which are matched
by both of the subexpressions.
<H3>OR</H3>
<P><i>expression</i> OR <i>expression</i> matches documents which are matched
by either of the subexpressions.
<H3>NOT</H3>
<P><i>expression</i> NOT <i>expression</i> matches documents which are matched
by only the first subexpression. This can also be written as
<i>expression</i> AND NOT <i>expression</i>.
If <code>FLAG_PURE_NOT</code> is enabled, then <P>NOT <i>expression</i> will
match documents which don't match the subexpression.
<H3>XOR</H3>
<P><i>expression</i> XOR <i>expression</i> matches documents which are matched
by one or other of the subexpressions, but not both. XOR is probably a bit
esoteric.
<H3>Bracketed expressions</H3>
<P>You can control the precedence of the boolean operators using brackets.
In the query <code>one OR two AND three</code> the AND takes precedence,
so this is the same as <code>one OR (two AND three)</code>. You can override
the precedence using <code>(one OR two) AND three</code>.
<H3>+ and -</H3>
<P>A group of terms with some marked with + and - will match documents
containing all of the + terms, but none of the - terms. Terms
not marked with + or - contribute towards the document rankings.
You can also use + and - on phrases and on bracketed expressions.
<H3>NEAR</H3>
<P><code>one NEAR two NEAR three</code> matches documents containing those
words within 10 words of each other. You can set the threshold to <i>n</i>
by using <code>NEAR/<i>n</i></code> like so: <code>one NEAR/6 two</code>.
<H3>ADJ</H3>
<P><code>ADJ</code> is like <code>NEAR</code> but only matches if the words
appear in the same order as in the query. So <code>one ADJ two ADJ
three</code> matches documents containing those three words in that order
and within 10 words of each other. You can set the threshold to <i>n</i>
by using <code>ADJ/<i>n</i> like so: <code>one ADJ/6 two</code>.
<H3>Phrase searches</H3>
<P>A phrase surrounded with double quotes ("") matches documents containing
that exact phrase. Hyphenated words are also treated as phrases, as are
cases such as filenames and email addresses (e.g. /etc/passwd or president@whitehouse.gov).
<H3>Searching within a probabilistic field</H3>
<P>If the database has been indexed with prefixes on probabilistic terms
from certain fields, you can set up a prefix map so that the user can
search within those fields. For example <code>author:dickens title:shop</code>
might find documents by dickens with shop in the title. You can also specify a
prefix on a quoted phrase (e.g. <code>author:"charles dickens"</code>) or
on a bracketed subexpression (e.g. <code>title:(mice men)</code>).
<H3>Searching for proper names</H3>
<P>If a query term is entered with a capitalised first letter, then it will
be searched for unstemmed.
<H3>Range searches</H3>
<P>The QueryParser <a href="valueranges.html">can be configured to support range-searching</a> using document values.
<P>The syntax for a range search is <code><i>start</i>..<i>end</i></code>
- for example, <code>01/03/2007..04/04/2007</code>, <code>$10..100</code>,
<code>5..10kg</code>.
<H3>Synonyms</H3>
<P>The QueryParser can be configured to support synonyms, which can either
be used when explicitly specified (using the syntax <code>~<i>term</i></code>)
or implicitly (synonyms will be used for all terms or groups of terms for
which they have been specified).
<H3>Wildcards</H3>
<P>The QueryParser supports using a trailing '*' wildcard, which matches any
number of trailing characters, so <code>wildc*</code> would match wildcard,
wildcarded, wildcards, wildcat, wildcats, etc. This feature is disabled
by default - pass <code>Xapian::QueryParser::FLAG_WILDCARD</code> in the flags
argument of
<code>Xapian::QueryParser::parse_query(<i>query_string</i>, <i>flags</i>)</code>
to enable it, and tell the QueryParser which database to expand wildcards from
using the <code>QueryParser::set_database(<i>database</i>)</code> method.
<H3>Partially entered query matching</H3>
<P>
The QueryParser also supports performing a search with a query which has only
been partially entered. This is intended for use with "incremental search"
systems, which don't wait for the user to finish typing their search before
displaying an initial set of results. For example, in such a system a user
would enter a search, and the system would display a new set of results after
each letter, or whenever the user pauses for a short period of time (or some
other similar strategy).
<P>
The problem with this kind of search is that the last word in a partially
entered query often has no semantic relation to the completed word. For
example, a search for "dynamic cat" would return a quite different set of
results to a search for "dynamic categorisation". This results in the set of
results displayed flicking rapidly as each new character is entered. A much
smoother result can be obtained if the final word is treated as having an
implicit terminating wildcard, so that it matches all words starting with the
entered characters - thus, as each letter is entered, the set of results
displayed narrows down to the desired subject.
<P>
A similar effect could be obtained simply by enabling the wildcard matching
option, and appending a "*" character to each query string. However, this
would be confused by searches which ended with punctuation or other
characters.
<P>
This feature is disabled by default - pass
<code>Xapian::QueryParser::FLAG_PARTIAL</code>
flag in the flags argument of
<code>Xapian::QueryParser::parse_query(<i>query_string</i>, <i>flags</i>)</code>
to enable it, and tell the QueryParser which database to expand wildcards from
using the <code>QueryParser::set_database(<i>database</i>)</code> method.
</BODY>
</HTML>
