Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

Xapian::Enquire Class Reference

This class provides an interface to the information retrieval system for the purpose of searching. More...

#include <enquire.h>

List of all members.

Public Methods

 Enquire (const Database &databases, ErrorHandler *errorhandler_=0)
 Create an Enquire object. More...

 ~Enquire ()
 Close the Enquire object. More...

void set_query (const Query &query_)
 Set the query to run. More...

const Queryget_query ()
 Get the query which has been set. More...

void set_weighting_scheme (const Weight &weight_)
 Set the weighting scheme to use for queries. More...

void set_collapse_key (valueno collapse_key)
 Set the collapse key to use for queries. More...

void set_sort_forward (bool sort_forward)
 Set the collapse key to use for queries. More...

void set_cutoff (int percent_cutoff, weight weight_cutoff=0)
 Set the percentage and/or weight cutoffs. More...

void set_sorting (valueno sort_key, int sort_bands)
 Set the percentage and/or weight cutoffs. More...

void set_bias (weight bias_weight, time_t bias_halflife)
 Set the bias functor parameters. More...

MSet get_mset (doccount first, doccount maxitems, const RSet *rset=0, const MatchDecider *mdecider=0) const
 Get (a portion of) the match set for the current query. More...

ESet get_eset (termcount maxitems, const RSet &rset, int flags=0, double k=1.0, const ExpandDecider *edecider=0) const
 Get the expand set for the given rset. More...

ESet get_eset (termcount maxitems, const RSet &rset, const ExpandDecider *edecider) const
 Get the expand set for the given rset. More...

TermIterator get_matching_terms_begin (docid did) const
 Get terms which match a given document, by document id. More...

TermIterator get_matching_terms_end (docid did) const
 End iterator corresponding to get_matching_terms_begin(). More...

TermIterator get_matching_terms_begin (const MSetIterator &it) const
 Get terms which match a given document, by match set item. More...

TermIterator get_matching_terms_end (const MSetIterator &it) const
 End iterator corresponding to get_matching_terms_begin(). More...

void register_match_decider (const std::string &name, const MatchDecider *mdecider=NULL)
 Register an MatchDecider. More...

std::string get_description () const
 Introspection method. More...


Public Attributes

Internal * internal

Static Public Attributes

const int include_query_terms = 1
const int use_exact_termfreq = 2


Detailed Description

This class provides an interface to the information retrieval system for the purpose of searching.

Databases are usually opened lazily, so exceptions may not be thrown where you would expect them to be. You should catch Error exceptions when calling any method in Enquire.

Exceptions:
Xapian::InvalidArgumentError  will be thrown if an invalid argument is supplied, for example, an unknown database type.
Xapian::OpeningError  will be thrown if the database cannot be opened (for example, a required file cannot be found).


Constructor & Destructor Documentation

Xapian::Enquire::Enquire const Database   databases,
ErrorHandler *    errorhandler_ = 0
 

Create an Enquire object.

This specification cannot be changed once the Enquire is opened: you must create a new Enquire object to access a different database, or set of databases.

Parameters:
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 Enquire object - the user should delete the ErrorHandler object after the Enquire object is deleted. To use no error handler, this parameter should be 0.

Xapian::Enquire::~Enquire  
 

Close the Enquire object.

This frees all resources associated with the Enquire object, such as handles on the databases used. As a result, any object which refers to these databases, such as a Document, will become invalid after the destruction of the object, and must not be used subsequently.


Member Function Documentation

std::string Xapian::Enquire::get_description   const
 

Introspection method.

Returns:
A string representing the enquire object.

ESet Xapian::Enquire::get_eset termcount    maxitems,
const RSet   rset,
const ExpandDecider   edecider
const [inline]
 

Get the expand set for the given rset.

Parameters:
maxitems  the maximum number of items to return.
rset  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
Returns:
An ESet object containing the results of the expand.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.

ESet Xapian::Enquire::get_eset termcount    maxitems,
const RSet   rset,
int    flags = 0,
double    k = 1.0,
const ExpandDecider   edecider = 0
const
 

Get the expand set for the given rset.

Parameters:
maxitems  the maximum number of items to return.
rset  the relevance set to use when performing the expand operation.
flags  zero or more of these values |-ed together:
  • Enquire::include_query_terms query terms may be returned from expand
Enquire::use_exact_termfreq for multi dbs, calculate the exact termfreq; otherwise an approximation is used which can greatly improve efficiency, but still returns good results.
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
Returns:
An ESet object containing the results of the expand.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.

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 an 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.

Parameters:
it  The iterator for which to retrieve the matching terms.
Returns:
An iterator returning the terms which match the document. The terms will be returned (as far as this makes any sense) in the same order as the terms in the query. Terms will not occur more than once, even if they do in the query.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.
Xapian::DocNotFoundError  The document specified could not be found in the database.

TermIterator Xapian::Enquire::get_matching_terms_begin 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 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.

Parameters:
did  The document id for which to retrieve the matching terms.
Returns:
An iterator returning the terms which match the document. The terms will be returned (as far as this makes any sense) in the same order as the terms in the query. Terms will not occur more than once, even if they do in the query.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.
Xapian::DocNotFoundError  The document specified could not be found in the database.

TermIterator Xapian::Enquire::get_matching_terms_end const MSetIterator   it const
 

End iterator corresponding to get_matching_terms_begin().

TermIterator Xapian::Enquire::get_matching_terms_end docid    did const
 

End iterator corresponding to get_matching_terms_begin().

MSet Xapian::Enquire::get_mset doccount    first,
doccount    maxitems,
const RSet   rset = 0,
const MatchDecider   mdecider = 0
const
 

Get (a portion of) the match set for the current query.

Parameters:
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.
rset  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
Returns:
An MSet object containing the results of the query.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.

const Query& Xapian::Enquire::get_query  
 

Get the query which has been set.

This is only valid after set_query() has been called.

Exceptions:
Xapian::InvalidArgumentError  will be thrown if query has not yet been set.

void Xapian::Enquire::register_match_decider const std::string &    name,
const MatchDecider   mdecider = NULL
 

Register an MatchDecider.

void Xapian::Enquire::set_bias weight    bias_weight,
time_t    bias_halflife
 

Set the bias functor parameters.

NB this is a temporary API for this feature.

Parameters:
bias_weight  Maximum weight bias functor can add (and which is given to document with a time now or in the future).
bias_halflife  the match bias decays exponentially as you go back in time. This sets the half-life of this decay in seconds (default 0 => no bias).

void Xapian::Enquire::set_collapse_key valueno    collapse_key
 

Set the collapse key to use for queries.

Parameters:
collapse_key  key number to collapse on - duplicates mset entries will be removed based on this key (default is valueno(-1) which means no collapsing).

void Xapian::Enquire::set_cutoff int    percent_cutoff,
weight    weight_cutoff = 0
 

Set the percentage and/or weight cutoffs.

Parameters:
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 Query::OP_AND instead of Query::OP_OR in the query that to set this to 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.

void Xapian::Enquire::set_query const Query   query_
 

Set the query to run.

Parameters:
query_  the new query to run.
Exceptions:
Xapian::InvalidArgumentError  See class documentation.
Xapian::OpeningError  See class documentation.

void Xapian::Enquire::set_sort_forward bool    sort_forward
 

Set the collapse key to use for queries.

Parameters:
sort_forward  If true, documents with the same weight will be returned in ascending document order; if false, they will be returned in descending order. (default true)

void Xapian::Enquire::set_sorting valueno    sort_key,
int    sort_bands
 

Set the percentage and/or weight cutoffs.

Parameters:
sort_key  value number to reorder on. Sorting is with a string compare. Higher is better. If match_sort_key is set, but match_sort_bands isn't, sort the whole mset my the key. (default is valueno(-1) which means re-sort by doc id
  • ascending or descending as controlled by sort_forward).
Parameters:
sort_bands  sort results into this many bands of equal percentage relevance. Within each band, sort by the value number specified by sort_key. (default is 0 which means no re-sorting).

void Xapian::Enquire::set_weighting_scheme const Weight   weight_
 

Set the weighting scheme to use for queries.

Parameters:
weight_  the new weighting scheme. If no weighting scheme is specified, the default is BM25 with A=1, B=1, C=0, D=0.5, min_normlen=0.5


The documentation for this class was generated from the following file:
Documentation for Xapian (version 0.6.3).
Generated on 24 Dec 2002 by Doxygen 1.2.15.