1package Xapian::Enquire;
2
3=head1 NAME
4
5Xapian::Enquire - Make queries against a database
6
7=head1 DESCRIPTION
8
9This class provides an interface to the information retrieval system for the
10purpose of searching.
11
12=head1 METHODS
13
14=over 4
15
16=item new
17
18=item set_query
19
20takes either a ready made L<Xapian::Query> or a scalar containing
21a query, which in that case will be passed to L<Xapian::Query>'s
22constructor, together with any other passed arguments.
23
24=item set_query_object <query>
25
26=item get_query
27
28=item matches <start> <size> [<check_at_least>]
29
30Takes the start element, and maximum number of elements (and optionally
31the minimum number of matches to check), and returns an array tied to
32L<Xapian::MSet::Tied>.
33
34=item get_matching_terms_begin
35
36Returns a L<Xapian::TermIterator>, pointing to the start
37of the stream.
38
39=item get_matching_terms_end
40
41Returns a L<Xapian::TermIterator>, pointing to the end
42of the stream.
43
44=item set_collapse_key <collapse_key>
45
46=item set_docid_order <order>
47
48Set the direction in which documents are ordered by document id
49in the returned MSet.
50
51This order only has an effect on documents which would otherwise
52have equal rank.  When ordering by relevance without a sort key,
53this means documents with equal weight.  For a boolean match
54with no sort key, this means all documents.  And if a sort key
55is used, this means documents with equal sort key (and also equal
56weight if ordering on relevance before or after the sort key).
57
58order can be ENQ_ASCENDING (the default, docids sort in ascending order),
59ENQ_DESCENDING (docds sort in descending order), or ENQ_DONT_CARE (docids sort
60in whatever order is most efficient for the backend.)
61
62Note: If you add documents in strict date order, then a boolean
63search - i.e. set_weighting_scheme(Xapian::BoolWeight()) - with
64set_docid_order(Xapian::Enquire::DESCENDING) is an efficient
65way to perform "sort by date, newest first", and with
66set_docid_order(Xapian::Enquire::ASCENDING) a very efficient way
67to perform "sort by date, oldest first".
68
69=item set_cutoff <percent_cutoff> [<weight_cutoff>]
70
71=item set_sort_by_relevance
72
73Set the sorting to be by relevance only.  This is the default.
74
75=item set_sort_by_value <sort_key> [<ascending>]
76
77Set the sorting to be by value only.
78
79sort_key - value number to reorder on.  Sorting is with a
80string compare.  If ascending is true (the default) higher
81is better; if ascending is false, lower is better.
82
83ascending - If true, document values which sort higher by
84string compare are better.  If false, the sort order
85is reversed.  (default true)
86
87=item set_sort_by_value_then_relevance <sort_key> [<ascending>]
88
89Set the sorting to be by value, then by relevance for documents
90with the same value.
91
92sort_key - value number to reorder on.  Sorting is with a
93string compare.  If ascending is true (the default) higher
94is better; if ascending is false, lower is better.
95
96ascending - If true, document values which sort higher by
97string compare are better.  If false, the sort order
98is reversed.  (default true)
99
100=item set_sort_by_relevance_then_value <sort_key> [<ascending>]
101
102Set the sorting to be by relevance then value.
103
104Note that with the default BM25 weighting scheme parameters,
105non-identical documents will rarely have the same weight, so
106this setting will give very similar results to
107set_sort_by_relevance().  It becomes more useful with particular
108BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom
109weighting schemes.
110
111sort_key - value number to reorder on.  Sorting is with a
112string compare.  If ascending is true (the default) higher
113is better; if ascending is false, lower is better.
114
115ascending - If true, document values which sort higher by
116string compare are better.  If false, the sort order
117is reversed.  (default true)
118
119=item set_sort_by_key <sorter> [<ascending>]
120
121Set the sorting to be by key only.
122
123sorter - the functor to use to build the key.
124
125ascending - If true, keys which sort higher by
126string compare are better.  If false, the sort order
127is reversed.  (default true)
128
129=item set_sort_by_key_then_relevance <sorter> [<ascending>]
130
131Set the sorting to be by key, then by relevance for documents
132with the same key.
133
134sorter - the functor to use to build the key.
135
136ascending - If true, keys which sort higher by
137string compare are better.  If false, the sort order
138is reversed.  (default true)
139
140=item set_sort_by_relevance_then_key <sorter> [<ascending>]
141
142Set the sorting to be by relevance then key.
143
144sorter - the functor to use to build the key.
145
146ascending - If true, keys which sort higher by
147string compare are better.  If false, the sort order
148is reversed.  (default true)
149
150=item get_mset
151
152Get match set.
153
154=item get_eset
155
156Get set of query expansion terms.
157
158=item get_description
159
160Return a description of this object.
161
162=back
163
164=head1 SEE ALSO
165
166L<Xapian::Query>,
167L<Xapian::Database>
168
169=cut
1701;
171