#include <enquire.h>
Collaboration diagram for Xapian::Enquire:
Public Types | |
enum | docid_order { ASCENDING = 1, DESCENDING = 0, DONT_CARE = 2 } |
Public Member Functions | |
Enquire (const Enquire &other) | |
Copying is allowed (and is cheap). | |
void | operator= (const Enquire &other) |
Assignment is allowed (and is cheap). | |
Enquire (const Database &database, ErrorHandler *errorhandler_=0) | |
Create a Xapian::Enquire object. | |
~Enquire () | |
Close the Xapian::Enquire object. | |
void | set_query (const Xapian::Query &query, Xapian::termcount qlen=0) |
Set the query to run. | |
const Xapian::Query & | get_query () const |
Get the query which has been set. | |
void | set_weighting_scheme (const Weight &weight_) |
Set the weighting scheme to use for queries. | |
void | set_collapse_key (Xapian::valueno collapse_key) |
Set the collapse key to use for queries. | |
void | set_docid_order (docid_order order) |
Set the direction in which documents are ordered by document id in the returned MSet. | |
void | set_cutoff (Xapian::percent percent_cutoff, Xapian::weight weight_cutoff=0) |
Set the percentage and/or weight cutoffs. | |
void | set_sort_by_relevance () |
Set the sorting to be by relevance only. | |
void | set_sort_by_value (Xapian::valueno sort_key, bool ascending=true) |
Set the sorting to be by value only. | |
void | set_sort_by_key (Xapian::Sorter *sorter, bool ascending=true) |
Set the sorting to be by key generated from values only. | |
void | set_sort_by_value_then_relevance (Xapian::valueno sort_key, bool ascending=true) |
Set the sorting to be by value, then by relevance for documents with the same value. | |
void | set_sort_by_key_then_relevance (Xapian::Sorter *sorter, bool ascending=true) |
Set the sorting to be by keys generated from values, then by relevance for documents with identical keys. | |
void | set_sort_by_relevance_then_value (Xapian::valueno sort_key, bool ascending=true) |
Set the sorting to be by relevance then value. | |
void | set_sort_by_relevance_then_key (Xapian::Sorter *sorter, bool ascending=true) |
Set the sorting to be by relevance, then by keys generated from values. | |
MSet | get_mset (Xapian::doccount first, Xapian::doccount maxitems, Xapian::doccount checkatleast=0, const RSet *omrset=0, const MatchDecider *mdecider=0) const |
Get (a portion of) the match set for the current query. | |
MSet | get_mset (Xapian::doccount first, Xapian::doccount maxitems, Xapian::doccount checkatleast, const RSet *omrset, const MatchDecider *mdecider, const MatchDecider *matchspy) const |
MSet | get_mset (Xapian::doccount first, Xapian::doccount maxitems, const RSet *omrset, const MatchDecider *mdecider=0) const |
ESet | get_eset (Xapian::termcount maxitems, const RSet &omrset, int flags=0, double k=1.0, const Xapian::ExpandDecider *edecider=0) const |
Get the expand set for the given rset. | |
ESet | get_eset (Xapian::termcount maxitems, const RSet &omrset, const Xapian::ExpandDecider *edecider) const |
Get the expand set for the given rset. | |
TermIterator | get_matching_terms_begin (Xapian::docid did) const |
Get terms which match a given document, by document id. | |
TermIterator | get_matching_terms_end (Xapian::docid) const |
End iterator corresponding to get_matching_terms_begin(). | |
TermIterator | get_matching_terms_begin (const MSetIterator &it) const |
Get terms which match a given document, by match set item. | |
TermIterator | get_matching_terms_end (const MSetIterator &) const |
End iterator corresponding to get_matching_terms_begin(). | |
void | register_match_decider (const std::string &name, const MatchDecider *mdecider=NULL) |
Register a MatchDecider. | |
std::string | get_description () const |
Return a string describing this object. | |
Public Attributes | |
Xapian::Internal::RefCntPtr< Internal > | internal |
For internal use only. Reference counted internals. | |
Static Public Attributes | |
static const int | INCLUDE_QUERY_TERMS = 1 |
static const int | USE_EXACT_TERMFREQ = 2 |
static const int | include_query_terms = 1 |
Deprecated in Xapian 1.0.0, use INCLUDE_QUERY_TERMS instead. | |
static const int | use_exact_termfreq = 2 |
Deprecated in Xapian 1.0.0, use USE_EXACT_TERMFREQ instead. | |
Classes | |
class | Internal |
Internals of enquire system. More... |
Databases are usually opened lazily, so exceptions may not be thrown where you would expect them to be. You should catch Xapian::Error exceptions when calling any method in Xapian::Enquire.
Xapian::InvalidArgumentError | will be thrown if an invalid argument is supplied, for example, an unknown database type. |
Definition at line 607 of file enquire.h.
Xapian::Enquire::Enquire | ( | const Enquire & | other | ) |
Copying is allowed (and is cheap).
Definition at line 831 of file omenquire.cc.
References DEBUGAPICALL.
Xapian::Enquire::Enquire | ( | const Database & | database, | |
ErrorHandler * | errorhandler_ = 0 | |||
) | [explicit] |
Create a Xapian::Enquire object.
This specification cannot be changed once the Xapian::Enquire is opened: you must create a new Xapian::Enquire object to access a different database, or set of databases.
The database supplied must have been initialised (ie, must not be the result of calling the Database::Database() constructor). If you need to handle a situation where you have no index gracefully, a database created with InMemory::open() can be passed here, which represents a completely empty database.
database | Specification of the database or databases to use. | |
errorhandler_ | A pointer to the error handler to use. Ownership of the object pointed to is not assumed by the Xapian::Enquire object - the user should delete the Xapian::ErrorHandler object after the Xapian::Enquire object is deleted. To use no error handler, this parameter should be 0. |
Xapian::InvalidArgumentError | will be thrown if an initialised Database object is supplied. |
Definition at line 843 of file omenquire.cc.
References DEBUGAPICALL.
Xapian::Enquire::~Enquire | ( | ) |
Close the Xapian::Enquire object.
Definition at line 849 of file omenquire.cc.
References DEBUGAPICALL.
void Xapian::Enquire::operator= | ( | const Enquire & | other | ) |
Assignment is allowed (and is cheap).
Definition at line 837 of file omenquire.cc.
References DEBUGAPICALL, and internal.
void Xapian::Enquire::set_query | ( | const Xapian::Query & | query, | |
Xapian::termcount | qlen = 0 | |||
) |
Set the query to run.
query | the new query to run. | |
qlen | the query length to use in weight calculations - by default the sum of the wqf of all terms is used. |
Definition at line 855 of file omenquire.cc.
References DEBUGAPICALL, and query().
Referenced by DEFINE_TESTCASE(), main(), test_consistency2(), and test_qp_value_range3().
const Query & Xapian::Enquire::get_query | ( | ) | const |
Get the query which has been set.
This is only valid after set_query() has been called.
Xapian::InvalidArgumentError | will be thrown if query has not yet been set. |
Definition at line 862 of file omenquire.cc.
References DEBUGAPICALL, internal, and RETURN.
void Xapian::Enquire::set_weighting_scheme | ( | const Weight & | weight_ | ) |
Set the weighting scheme to use for queries.
weight_ | the new weighting scheme. If no weighting scheme is specified, the default is BM25 with the default parameters. |
Definition at line 874 of file omenquire.cc.
References Xapian::Weight::clone(), and DEBUGAPICALL.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_collapse_key | ( | Xapian::valueno | collapse_key | ) |
Set the collapse key to use for queries.
collapse_key | value number to collapse on - at most one MSet entry with each particular value will be returned. |
An example use might be to create a value for each document containing an MD5 hash of the document contents. Then duplicate documents from different sources can be eliminated at search time (it's better to eliminate duplicates at index time, but this may not be always be possible - for example the search may be over more than one Xapian database).
Another use is to group matches in a particular category (e.g. you might collapse a mailing list search on the Subject: so that there's only one result per discussion thread). In this case you can use get_collapse_count() to give the user some idea how many other results there are. And if you index the Subject: as a boolean term as well as putting it in a value, you can offer a link to a non-collapsed search restricted to that thread using a boolean filter.
(default is Xapian::BAD_VALUENO which means no collapsing).
Definition at line 882 of file omenquire.cc.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_docid_order | ( | docid_order | order | ) |
Set the direction in which documents are ordered by document id in the returned MSet.
This order only has an effect on documents which would otherwise have equal rank. For a weighted probabilistic match with no sort value, this means documents with equal weight. For a boolean match, with no sort value, this means all documents. And if a sort value is used, this means documents with equal sort value (and also equal weight if ordering on relevance after the sort).
order | This can be:
|
Definition at line 888 of file omenquire.cc.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_cutoff | ( | Xapian::percent | percent_cutoff, | |
Xapian::weight | weight_cutoff = 0 | |||
) |
Set the percentage and/or weight cutoffs.
percent_cutoff | Minimum percentage score for returned documents. If a document has a lower percentage score than this, it will not appear in the MSet. If your intention is to return only matches which contain all the terms in the query, then it's more efficient to use Xapian::Query::OP_AND instead of Xapian::Query::OP_OR in the query than to use set_cutoff(100). (default 0 => no percentage cut-off). | |
weight_cutoff | Minimum weight for a document to be returned. If a document has a lower score that this, it will not appear in the MSet. It is usually only possible to choose an appropriate weight for cutoff based on the results of a previous run of the same query; this is thus mainly useful for alerting operations. The other potential use is with a user specified weighting scheme. (default 0 => no weight cut-off). |
Definition at line 894 of file omenquire.cc.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_sort_by_relevance | ( | ) |
Set the sorting to be by relevance only.
This is the default.
Definition at line 901 of file omenquire.cc.
References Xapian::Enquire::Internal::REL.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_sort_by_value | ( | Xapian::valueno | sort_key, | |
bool | ascending = true | |||
) |
Set the sorting to be by value only.
NB sorting of values uses a string comparison, so you'll need to store numbers padded with leading zeros or spaces, or with the number of digits prepended.
sort_key | value number to sort on. | |
ascending | If true, documents values which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 907 of file omenquire.cc.
References Xapian::Enquire::Internal::VAL.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_sort_by_key | ( | Xapian::Sorter * | sorter, | |
bool | ascending = true | |||
) |
Set the sorting to be by key generated from values only.
sorter | The functor to use for generating keys. | |
ascending | If true, documents values which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 936 of file omenquire.cc.
References Xapian::Enquire::Internal::VAL.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_sort_by_value_then_relevance | ( | Xapian::valueno | sort_key, | |
bool | ascending = true | |||
) |
Set the sorting to be by value, then by relevance for documents with the same value.
NB sorting of values uses a string comparison, so you'll need to store numbers padded with leading zeros or spaces, or with the number of digits prepended.
sort_key | value number to sort on. | |
ascending | If true, documents values which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 916 of file omenquire.cc.
References Xapian::Enquire::Internal::VAL_REL.
Referenced by DEFINE_TESTCASE(), and test_consistency2().
void Xapian::Enquire::set_sort_by_key_then_relevance | ( | Xapian::Sorter * | sorter, | |
bool | ascending = true | |||
) |
Set the sorting to be by keys generated from values, then by relevance for documents with identical keys.
sorter | The functor to use for generating keys. | |
ascending | If true, keys which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 946 of file omenquire.cc.
References Xapian::Enquire::Internal::VAL_REL.
void Xapian::Enquire::set_sort_by_relevance_then_value | ( | Xapian::valueno | sort_key, | |
bool | ascending = true | |||
) |
Set the sorting to be by relevance then value.
NB sorting of values uses a string comparison, so you'll need to store numbers padded with leading zeros or spaces, or with the number of digits prepended.
Note that with the default BM25 weighting scheme parameters, non-identical documents will rarely have the same weight, so this setting will give very similar results to set_sort_by_relevance(). It becomes more useful with particular BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom weighting schemes.
sort_key | value number to sort on. | |
ascending | If true, documents values which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 926 of file omenquire.cc.
References Xapian::Enquire::Internal::REL_VAL.
Referenced by DEFINE_TESTCASE().
void Xapian::Enquire::set_sort_by_relevance_then_key | ( | Xapian::Sorter * | sorter, | |
bool | ascending = true | |||
) |
Set the sorting to be by relevance, then by keys generated from values.
Note that with the default BM25 weighting scheme parameters, non-identical documents will rarely have the same weight, so this setting will give very similar results to set_sort_by_relevance(). It becomes more useful with particular BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom weighting schemes.
sorter | The functor to use for generating keys. | |
ascending | If true, keys which sort higher by string compare are better. If false, the sort order is reversed. (default true) |
Definition at line 956 of file omenquire.cc.
References Xapian::Enquire::Internal::REL_VAL.
MSet Xapian::Enquire::get_mset | ( | Xapian::doccount | first, | |
Xapian::doccount | maxitems, | |||
Xapian::doccount | checkatleast = 0 , |
|||
const RSet * | omrset = 0 , |
|||
const MatchDecider * | mdecider = 0 | |||
) | const |
Get (a portion of) the match set for the current query.
first | the first item in the result set to return. A value of zero corresponds to the first item returned being that with the highest score. A value of 10 corresponds to the first 10 items being ignored, and the returned items starting at the eleventh. | |
maxitems | the maximum number of items to return. | |
checkatleast | the minimum number of items to check. Because the matcher optimises, it won't consider every document which might match, so the total number of matches is estimated. Setting checkatleast forces it to consider at least this many matches and so allows for reliable paging links. | |
omrset | the relevance set to use when performing the query. | |
mdecider | a decision functor to use to decide whether a given document should be put in the MSet. | |
matchspy | a decision functor to use to decide whether a given document should be put in the MSet. The matchspy is applied to every document which is a potential candidate for the MSet, so if there are checkatleast or more such documents, the matchspy will see at least checkatleast. The mdecider is assumed to be a relatively expensive test so may be applied in a lazier fashion. |
Xapian::InvalidArgumentError | See class documentation. |
Definition at line 966 of file omenquire.cc.
Referenced by DEFINE_TESTCASE(), main(), test_consistency2(), and test_qp_value_range3().
MSet Xapian::Enquire::get_mset | ( | Xapian::doccount | first, | |
Xapian::doccount | maxitems, | |||
Xapian::doccount | checkatleast, | |||
const RSet * | omrset, | |||
const MatchDecider * | mdecider, | |||
const MatchDecider * | matchspy | |||
) | const |
MSet Xapian::Enquire::get_mset | ( | Xapian::doccount | first, | |
Xapian::doccount | maxitems, | |||
const RSet * | omrset, | |||
const MatchDecider * | mdecider = 0 | |||
) | const [inline] |
ESet Xapian::Enquire::get_eset | ( | Xapian::termcount | maxitems, | |
const RSet & | omrset, | |||
int | flags = 0 , |
|||
double | k = 1.0 , |
|||
const Xapian::ExpandDecider * | edecider = 0 | |||
) | const |
Get the expand set for the given rset.
maxitems | the maximum number of items to return. | |
omrset | the relevance set to use when performing the expand operation. | |
flags | zero or more of these values |-ed together:
| |
k | the parameter k in the query expansion algorithm (default is 1.0) | |
edecider | a decision functor to use to decide whether a given term should be put in the ESet |
Xapian::InvalidArgumentError | See class documentation. |
Definition at line 994 of file omenquire.cc.
References DEBUGAPICALL, internal, and RETURN.
Referenced by DEFINE_TESTCASE(), and main().
ESet Xapian::Enquire::get_eset | ( | Xapian::termcount | maxitems, | |
const RSet & | omrset, | |||
const Xapian::ExpandDecider * | edecider | |||
) | const [inline] |
Get the expand set for the given rset.
maxitems | the maximum number of items to return. | |
omrset | the relevance set to use when performing the expand operation. | |
edecider | a decision functor to use to decide whether a given term should be put in the ESet |
Xapian::InvalidArgumentError | See class documentation. |
TermIterator Xapian::Enquire::get_matching_terms_begin | ( | Xapian::docid | did | ) | const |
Get terms which match a given document, by document id.
This method returns the terms in the current query which match the given document.
It is possible for the document to have been removed from the database between the time it is returned in an MSet, and the time that this call is made. If possible, you should specify an MSetIterator instead of a Xapian::docid, since this will enable database backends with suitable support to prevent this occurring.
Note that a query does not need to have been run in order to make this call.
did | The document id for which to retrieve the matching terms. |
Xapian::InvalidArgumentError | See class documentation. | |
Xapian::DocNotFoundError | The document specified could not be found in the database. |
Definition at line 1024 of file omenquire.cc.
References DEBUGAPICALL, internal, and RETURN.
Referenced by DEFINE_TESTCASE().
TermIterator Xapian::Enquire::get_matching_terms_end | ( | Xapian::docid | ) | const [inline] |
End iterator corresponding to get_matching_terms_begin().
Definition at line 990 of file enquire.h.
Referenced by DEFINE_TESTCASE().
TermIterator Xapian::Enquire::get_matching_terms_begin | ( | const MSetIterator & | it | ) | const |
Get terms which match a given document, by match set item.
This method returns the terms in the current query which match the given document.
If the underlying database has suitable support, using this call (rather than passing a Xapian::docid) will enable the system to ensure that the correct data is returned, and that the document has not been deleted or changed since the query was performed.
it | The iterator for which to retrieve the matching terms. |
Xapian::InvalidArgumentError | See class documentation. | |
Xapian::DocNotFoundError | The document specified could not be found in the database. |
Definition at line 1012 of file omenquire.cc.
References DEBUGAPICALL, internal, and RETURN.
TermIterator Xapian::Enquire::get_matching_terms_end | ( | const MSetIterator & | ) | const [inline] |
End iterator corresponding to get_matching_terms_begin().
void Xapian::Enquire::register_match_decider | ( | const std::string & | name, | |
const MatchDecider * | mdecider = NULL | |||
) |
Register a MatchDecider.
This is used to associate a name with a matchdecider.
string Xapian::Enquire::get_description | ( | ) | const |
For internal use only.
Reference counted internals.
Definition at line 615 of file enquire.h.
Referenced by get_eset(), get_matching_terms_begin(), get_mset(), get_query(), and operator=().
const int Xapian::Enquire::INCLUDE_QUERY_TERMS = 1 [static] |
Definition at line 898 of file enquire.h.
Referenced by DEFINE_TESTCASE(), and Xapian::Enquire::Internal::get_eset().
const int Xapian::Enquire::USE_EXACT_TERMFREQ = 2 [static] |
Definition at line 899 of file enquire.h.
Referenced by DEFINE_TESTCASE(), and Xapian::Enquire::Internal::get_eset().
const int Xapian::Enquire::include_query_terms = 1 [static] |
const int Xapian::Enquire::use_exact_termfreq = 2 [static] |