1
==========================
2
The default query language
3
==========================
10
A query consists of *terms* and *operators*. There are two types of terms: single
11
terms and *phrases*. Multiple terms can be combined with operators such as
14
Whoosh supports indexing text in different *fields*. You must specify the
15
*default field* when you create the :class:`whoosh.qparser.QueryParser` object.
16
This is the field in which any terms the user does not explicitly specify a field
20
Individual terms and phrases
21
============================
23
Find documents containing the term ``render``::
27
Find documents containing the phrase ``all was well``::
31
Note that a field must store Position information for phrase searching to work in
38
Find documents containing ``render`` *and* ``shading``::
42
Note that AND is the default relation between terms, so this is the same as::
46
Find documents containing ``render``, *and* also either ``shading`` *or*
49
render AND shading OR modeling
51
Find documents containing ``render`` but *not* modeling::
55
Find documents containing ``alpha`` but not either ``beta`` or ``gamma``::
57
alpha NOT (beta OR gamma)
59
Note that when no boolean operator is specified between terms, the parser will
60
insert one, by default AND. So this query::
62
render shading modeling
64
is equivalent (by default) to::
66
render AND shading AND modeling
68
See :doc:`customizing the default parser <parsing>` for information on how to
69
change the default operator to OR.
71
Group operators together with parentheses. For example to find documents that
72
contain both ``render`` and ``shading``, or contain ``modeling``::
74
(render AND shading) OR modeling
80
Find the term ``ivan`` in the ``name`` field::
84
The ``field:`` prefix only sets the field for the term it directly precedes, so
89
Will search for ``open`` in the ``title`` field and ``sesame`` in the *default*
92
To apply a field prefix to multiple terms, group them with parentheses::
98
title:open title:sesame
100
Of course you can specify a field for phrases too::
108
Use "globs" (wildcard expressions using ``?`` to represent a single character
109
and ``*`` to represent any number of characters) to match terms::
113
Note that a wildcard starting with ``?`` or ``*`` is very slow. Note also that
114
these wildcards only match *individual terms*. For example, the query::
118
will **not** match an indexed phrase like::
122
because those are four separate terms.
128
You can match a range of terms. For example, the following query will match
129
documents containing terms in the lexical range from ``apple`` to ``bear``
130
*inclusive*. For example, it will match documents containing ``azores`` and
131
``be`` but not ``blur``::
135
This is very useful when you've stored, for example, dates in a lexically sorted
136
format (i.e. YYYYMMDD)::
138
date:[20050101 TO 20090715]
140
The range is normally *inclusive* (that is, the range will match all terms
141
between the start and end term, *as well as* the start and end terms
142
themselves). You can specify that one or both ends of the range are *exclusive*
143
by using the ``{`` and/or ``}`` characters::
148
You can also specify *open-ended* ranges by leaving out the start or end term::
154
Boosting query elements
155
=======================
157
You can specify that certain parts of a query are more important for calculating
158
the score of a matched document than others. For example, to specify that
159
``ninja`` is twice as important as other words, and ``bear`` is half as
162
ninja^2 cowboy bear^0.5
164
You can apply a boost to several terms using grouping parentheses::
166
(open sesame)^2.5 roc
169
Making a term from literal text
170
===============================
172
If you need to include characters in a term that are normally treated specially
173
the by the parser, such as spaces, colons, or brackets, you can enclose the term
176
path:'MacHD:My Documents'