Xapian::Query Class Reference

Class representing a query. More...

#include <query.h>

Collaboration diagram for Xapian::Query:

List of all members.

Classes

class Internal

Public Types

enum op {
  OP_AND, OP_OR, OP_AND_NOT, OP_XOR,
  OP_AND_MAYBE, OP_FILTER, OP_NEAR, OP_PHRASE,
  OP_VALUE_RANGE, OP_SCALE_WEIGHT, OP_ELITE_SET, OP_VALUE_GE,
  OP_VALUE_LE, OP_SYNONYM
}

Enum of possible query operations. More...

Public Member Functions

Query (const Query &copyme)

Copy constructor.

Query & operator= (const Query &copyme)

Assignment.

Query ()

Default constructor: makes an empty query which matches no documents.

~Query ()

Destructor.

Query (const std::string &tname_, Xapian::termcount wqf_=1, Xapian::termpos pos_=0)

A query consisting of a single term.

Query (Query::op op_, const Query &left, const Query &right)

A query consisting of two subqueries, opp-ed together.

Query (Query::op op_, const std::string &left, const std::string &right)

A query consisting of two termnames opp-ed together.

template<class Iterator >

Query (Query::op op_, Iterator qbegin, Iterator qend, Xapian::termcount parameter=0)

Combine a number of Xapian::Query-s with the specified operator.

Query (Query::op op_, Xapian::Query q, double parameter)

Apply the specified operator to a single Xapian::Query object, with a double parameter.

Query (Query::op op_, Xapian::valueno slot, const std::string &begin, const std::string &end)

Construct a value range query on a document value.

Query (Query::op op_, Xapian::valueno slot, const std::string &value)

Construct a value comparison query on a document value.

Query (Xapian::PostingSource *external_source)

Construct an external source query.

Xapian::termcount get_length () const

Get the length of the query, used by some ranking formulae.

TermIterator get_terms_begin () const

Return a Xapian::TermIterator returning all the terms in the query, in order of termpos.

TermIterator get_terms_end () const

Return a Xapian::TermIterator to the end of the list of terms in the query.

bool empty () const

Test if the query is empty (i.e.

std::string serialise () const

Serialise query into a string.

std::string get_description () const

Return a string describing this object.

Static Public Member Functions

static Query unserialise (const std::string &s)

Unserialise a query from a string produced by serialise().

static Query unserialise (const std::string &s, const Registry &registry)

Unserialise a query from a string produced by serialise().

Static Public Attributes

static const Xapian::Query MatchAll = Xapian::Query(string())

A query which matches all documents in the database.

static const Xapian::Query MatchNothing = Xapian::Query()

A query which matches no documents.

Private Member Functions

void add_subquery (const Query &subq)

Add a subquery by reference.

void add_subquery (const Query *subq)

Add a subquery by pointer.

void add_subquery (const std::string &tname)

Add a subquery which is a single term.

void start_construction (Query::op op_, Xapian::termcount parameter)

Setup the internals for the query, with the appropriate operator.

void end_construction ()

Check that query has an appropriate number of arguments, etc,.

void abort_construction ()

Abort construction of the query: delete internal.

Private Attributes

Xapian::Internal::RefCntPtr
< Internal > internal

Detailed Description

Class representing a query.

Queries are represented as a tree of objects.

Definition at line 54 of file query.h.

Member Enumeration Documentation

enum Xapian::Query::op

Enum of possible query operations.

Enumerator:

OP_AND	Return iff both subqueries are satisfied.
OP_OR	Return if either subquery is satisfied.
OP_AND_NOT	Return if left but not right satisfied.
OP_XOR	Return if one query satisfied, but not both.
OP_AND_MAYBE	Return iff left satisfied, but use weights from both.
OP_FILTER	As AND, but use only weights from left subquery.
OP_NEAR	Find occurrences of a list of terms with all the terms occurring within a specified window of positions. Each occurrence of a term must be at a different position, but the order they appear in is irrelevant. The window parameter should be specified for this operation, but will default to the number of terms in the list.
OP_PHRASE	Find occurrences of a list of terms with all the terms occurring within a specified window of positions, and all the terms appearing in the order specified. Each occurrence of a term must be at a different position. The window parameter should be specified for this operation, but will default to the number of terms in the list.
OP_VALUE_RANGE	Filter by a range test on a document value.
OP_SCALE_WEIGHT	Scale the weight of a subquery by the specified factor. A factor of 0 means this subquery will contribute no weight to the query - it will act as a purely boolean subquery. If the factor is negative, Xapian::InvalidArgumentError will be thrown.
OP_ELITE_SET	Pick the best N subqueries and combine with OP_OR. If you want to implement a feature which finds documents similar to a piece of text, an obvious approach is to build an "OR" query from all the terms in the text, and run this query against a database containing the documents. However such a query can contain a lots of terms and be quite slow to perform, yet many of these terms don't contribute usefully to the results. The OP_ELITE_SET operator can be used instead of OP_OR in this situation. OP_ELITE_SET selects the most important ''N'' terms and then acts as an OP_OR query with just these, ignoring any other terms. This will usually return results just as good as the full OP_OR query, but much faster. In general, the OP_ELITE_SET operator can be used when you have a large OR query, but it doesn't matter if the search completely ignores some of the less important terms in the query. The subqueries don't have to be terms, but if they aren't then OP_ELITE_SET will look at the estimated frequencies of the subqueries and so could pick a subset which don't actually match any documents even if the full OR would match some. You can specify a parameter to the query constructor which control the number of terms which OP_ELITE_SET will pick. If not specified, this defaults to 10 (or `ceil(sqrt(number_of_subqueries))` if there are more than 100 subqueries, but this rather arbitrary special case will be dropped in 1.3.0). For example, this will pick the best 7 terms: Xapian::Query query(Xapian::Query::OP_ELITE_SET, subqs.begin(), subqs.end(), 7); If the number of subqueries is less than this threshold, OP_ELITE_SET behaves identically to OP_OR.
OP_VALUE_GE	Filter by a greater-than-or-equal test on a document value.
OP_VALUE_LE	Filter by a less-than-or-equal test on a document value.
OP_SYNONYM	Treat a set of queries as synonyms. This returns all results which match at least one of the queries, but weighting as if all the sub-queries are instances of the same term: so multiple matching terms for a document increase the wdf value used, and the term frequency is based on the number of documents which would match an OR of all the subqueries. The term frequency used will usually be an approximation, because calculating the precise combined term frequency would be overly expensive. Identical to OP_OR, except for the weightings returned.

Definition at line 62 of file query.h.

Constructor & Destructor Documentation

Xapian::Query::Query ( const Query & copyme )

Copy constructor.

Definition at line 172 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::Query ( )

Default constructor: makes an empty query which matches no documents.

Also useful for defining a Query object to be assigned to later.

An exception will be thrown if an attempt is made to use an undefined query when building up a composite query.

Definition at line 188 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::~Query ( )

Destructor.

Definition at line 194 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::Query	(	const std::string &	tname_,
		Xapian::termcount	wqf_ = `1`,
		Xapian::termpos	pos_ = `0`
	)

A query consisting of a single term.

Definition at line 99 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::Query	(	Query::op	op_,
		const Query &	left,
		const Query &	right
	)

A query consisting of two subqueries, opp-ed together.

Definition at line 105 of file omquery.cc.

References abort_construction(), add_subquery(), end_construction(), and LOGCALL_VOID.

Xapian::Query::Query	(	Query::op	op_,
		const std::string &	left,
		const std::string &	right
	)

A query consisting of two termnames opp-ed together.

Definition at line 258 of file omquery.cc.

References abort_construction(), add_subquery(), end_construction(), and start_construction().

template<class Iterator >

Xapian::Query::Query	(	Query::op	op_,
		Iterator	qbegin,
		Iterator	qend,
		Xapian::termcount	parameter = `0`
	)			`[inline]`

Combine a number of Xapian::Query-s with the specified operator.

The Xapian::Query objects are specified with begin and end iterators.

AND, OR, XOR, ELITE_SET, SYNONYM, NEAR and PHRASE can take any number of subqueries. Other operators take exactly two subqueries.

The iterators may be to Xapian::Query objects, pointers to Xapian::Query objects, or termnames (std::string-s).

For NEAR and PHRASE, a window size can be specified in parameter.

For ELITE_SET, the elite set size can be specified in parameter.

Definition at line 353 of file query.h.

References abort_construction(), add_subquery(), end_construction(), and start_construction().

Xapian::Query::Query	(	Query::op	op_,
		Xapian::Query	q,
		double	parameter
	)

Apply the specified operator to a single Xapian::Query object, with a double parameter.

Definition at line 119 of file omquery.cc.

References abort_construction(), add_subquery(), end_construction(), Xapian::Internal::RefCntPtr< T >::get(), internal, LOGCALL_VOID, OP_SCALE_WEIGHT, OP_VALUE_GE, OP_VALUE_LE, OP_VALUE_RANGE, and start_construction().

Xapian::Query::Query	(	Query::op	op_,
		Xapian::valueno	slot,
		const std::string &	begin,
		const std::string &	end
	)

Construct a value range query on a document value.

A value range query matches those documents which have a value stored in the slot given by slot which is in the range specified by begin and end (in lexicographical order), including the endpoints.

Parameters:

	op_	The operator to use for the query. Currently, must be OP_VALUE_RANGE.
	slot	The slot number to get the value from.
	begin	The start of the range.
	end	The end of the range.

Definition at line 144 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::Query	(	Query::op	op_,
		Xapian::valueno	slot,
		const std::string &	value
	)

Construct a value comparison query on a document value.

This query matches those documents which have a value stored in the slot given by slot which compares, as specified by the operator, to value.

Parameters:

	op_	The operator to use for the query. Currently, must be OP_VALUE_GE or OP_VALUE_LE.
	slot	The slot number to get the value from.
	value	The value to compare.

Definition at line 151 of file omquery.cc.

References LOGCALL_VOID.

Xapian::Query::Query ( Xapian::PostingSource * external_source ) [explicit]

Construct an external source query.

An attempt to clone the posting source will be made immediately, so if the posting source supports clone(), the source supplied may be safely deallocated after this call. If the source does not support clone(), the caller must ensure that the posting source remains valid until the Query is deallocated.

Parameters:

external_source

The source to use in the query.

Definition at line 157 of file omquery.cc.

References Xapian::PostingSource::clone(), and LOGCALL_VOID.

Member Function Documentation

void Xapian::Query::abort_construction ( ) [private]

Abort construction of the query: delete internal.

Definition at line 92 of file omquery.cc.

References Assert, and LOGCALL_VOID.

Referenced by Query().

void Xapian::Query::add_subquery ( const std::string & tname ) [private]

Add a subquery which is a single term.

Definition at line 64 of file omquery.cc.

References Assert, and LOGCALL_VOID.

void Xapian::Query::add_subquery ( const Query * subq ) [private]

Add a subquery by pointer.

Definition at line 52 of file omquery.cc.

References Assert, Xapian::Internal::RefCntPtr< T >::get(), internal, and LOGCALL_VOID.

void Xapian::Query::add_subquery ( const Query & subq ) [private]

Add a subquery by reference.

Definition at line 43 of file omquery.cc.

References Assert, Xapian::Internal::RefCntPtr< T >::get(), internal, and LOGCALL_VOID.

Referenced by Query().

bool Xapian::Query::empty ( ) const

Test if the query is empty (i.e.

was constructed using the default ctor or with an empty iterator ctor).

Definition at line 252 of file omquery.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE(), Xapian::Enquire::Internal::get_eset(), Xapian::Enquire::Internal::get_matching_terms(), and yy_reduce().

void Xapian::Query::end_construction ( ) [private]

Check that query has an appropriate number of arguments, etc,.

Definition at line 83 of file omquery.cc.

References Assert, and LOGCALL_VOID.

Referenced by Query().

std::string Xapian::Query::get_description ( ) const

Return a string describing this object.

Definition at line 230 of file omquery.cc.

Referenced by DEFINE_TESTCASE(), Xapian::Enquire::Internal::get_description(), main(), PerfTestLogger::search_end(), test_qp_default_op1(), test_qp_default_prefix1(), test_qp_default_prefix2(), test_qp_flag_bool_any_case1(), test_qp_flag_partial1(), test_qp_flag_pure_not1(), test_qp_flag_wildcard1(), test_qp_flag_wildcard2(), test_qp_near1(), test_qp_odd_chars1(), test_qp_phrase1(), test_qp_stem_all1(), test_qp_stem_all_z1(), test_qp_stopper1(), test_qp_stopword_group1(), test_qp_synonym1(), test_qp_synonym2(), test_qp_synonym3(), test_qp_unstem_boolean_prefix(), test_qp_value_customrange1(), test_qp_value_daterange1(), test_qp_value_daterange2(), test_qp_value_range1(), test_qp_value_range2(), test_qp_value_range4(), test_qp_value_stringrange1(), and test_queryparser1().

termcount Xapian::Query::get_length ( ) const

Get the length of the query, used by some ranking formulae.

This value is calculated automatically - if you want to override it you can pass a different value to Enquire::set_query().

Definition at line 238 of file omquery.cc.

References internal, LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), and Xapian::Enquire::Internal::set_query().

TermIterator Xapian::Query::get_terms_begin ( ) const

Return a Xapian::TermIterator returning all the terms in the query, in order of termpos.

If multiple terms have the same term position, their order is unspecified. Duplicates (same term and termpos) will be removed.

Definition at line 244 of file omquery.cc.

References internal, LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), Xapian::Enquire::Internal::get_eset(), and Xapian::Enquire::Internal::get_matching_terms().

TermIterator Xapian::Query::get_terms_end ( ) const [inline]

Return a Xapian::TermIterator to the end of the list of terms in the query.

Definition at line 300 of file query.h.

Referenced by DEFINE_TESTCASE(), Xapian::Enquire::Internal::get_eset(), and Xapian::Enquire::Internal::get_matching_terms().

Query & Xapian::Query::operator= ( const Query & copyme )

Assignment.

Definition at line 180 of file omquery.cc.

References internal, LOGCALL, and RETURN.

std::string Xapian::Query::serialise ( ) const

Serialise query into a string.

The query representation may change between Xapian releases: even between minor versions. However, it is guaranteed not to change unless the remote database protocol has also changed between releases.

Definition at line 200 of file omquery.cc.

References LOGCALL.

Referenced by DEFINE_TESTCASE().

void Xapian::Query::start_construction	(	Query::op	op_,
		Xapian::termcount	parameter
	)			`[private]`

Setup the internals for the query, with the appropriate operator.

Definition at line 74 of file omquery.cc.

References Assert, and LOGCALL_VOID.

Referenced by Query().

Query Xapian::Query::unserialise	(	const std::string &	s,
		const Registry &	registry
	)			`[static]`

Unserialise a query from a string produced by serialise().

The supplied registry will be used to attempt to unserialise any external PostingSource leaf nodes. This method will fail if the query contains any external PostingSource leaf nodes which are not registered in the registry.

Parameters:

	s	The string representing the serialised query.
	registry	Xapian::Registry to use.

Definition at line 219 of file omquery.cc.

References internal, LOGCALL_STATIC, RETURN, and unserialise().

Query Xapian::Query::unserialise ( const std::string & s ) [static]

Unserialise a query from a string produced by serialise().

This method will fail if the query contains any external PostingSource leaf nodes.

Parameters:

s

The string representing the serialised query.

Definition at line 208 of file omquery.cc.

References internal, LOGCALL_STATIC, and RETURN.

Referenced by DEFINE_TESTCASE(), and unserialise().

Member Data Documentation

Xapian::Internal::RefCntPtr<Internal> Xapian::Query::internal [private]

For internal use only.

Reference counted internals.

Definition at line 57 of file query.h.

Referenced by add_subquery(), get_length(), Xapian::Enquire::Internal::get_mset(), get_terms_begin(), operator=(), Query(), serialisequery1_helper(), and unserialise().

const Xapian::Query Xapian::Query::MatchAll = Xapian::Query(string()) [static]

A query which matches all documents in the database.

Definition at line 279 of file query.h.

Referenced by DEFINE_TESTCASE().

const Xapian::Query Xapian::Query::MatchNothing = Xapian::Query() [static]

A query which matches no documents.

Definition at line 282 of file query.h.

Referenced by DEFINE_TESTCASE().

The documentation for this class was generated from the following files:

include/xapian/query.h
api/omquery.cc


Classes
class	Internal
Public Types
enum	op { OP_AND, OP_OR, OP_AND_NOT, OP_XOR, OP_AND_MAYBE, OP_FILTER, OP_NEAR, OP_PHRASE, OP_VALUE_RANGE, OP_SCALE_WEIGHT, OP_ELITE_SET, OP_VALUE_GE, OP_VALUE_LE, OP_SYNONYM }
	Enum of possible query operations. More...
Public Member Functions
	Query (const Query &copyme)
	Copy constructor.
Query &	operator= (const Query &copyme)
	Assignment.
	Query ()
	Default constructor: makes an empty query which matches no documents.
	~Query ()
	Destructor.
	Query (const std::string &tname_, Xapian::termcount wqf_=1, Xapian::termpos pos_=0)
	A query consisting of a single term.
	Query (Query::op op_, const Query &left, const Query &right)
	A query consisting of two subqueries, opp-ed together.
	Query (Query::op op_, const std::string &left, const std::string &right)
	A query consisting of two termnames opp-ed together.
template<class Iterator >
	Query (Query::op op_, Iterator qbegin, Iterator qend, Xapian::termcount parameter=0)
	Combine a number of Xapian::Query-s with the specified operator.
	Query (Query::op op_, Xapian::Query q, double parameter)
	Apply the specified operator to a single Xapian::Query object, with a double parameter.
	Query (Query::op op_, Xapian::valueno slot, const std::string &begin, const std::string &end)
	Construct a value range query on a document value.
	Query (Query::op op_, Xapian::valueno slot, const std::string &value)
	Construct a value comparison query on a document value.
	Query (Xapian::PostingSource *external_source)
	Construct an external source query.
Xapian::termcount	get_length () const
	Get the length of the query, used by some ranking formulae.
TermIterator	get_terms_begin () const
	Return a Xapian::TermIterator returning all the terms in the query, in order of termpos.
TermIterator	get_terms_end () const
	Return a Xapian::TermIterator to the end of the list of terms in the query.
bool	empty () const
	Test if the query is empty (i.e.
std::string	serialise () const
	Serialise query into a string.
std::string	get_description () const
	Return a string describing this object.
Static Public Member Functions
static Query	unserialise (const std::string &s)
	Unserialise a query from a string produced by serialise().
static Query	unserialise (const std::string &s, const Registry &registry)
	Unserialise a query from a string produced by serialise().
Static Public Attributes
static const Xapian::Query	MatchAll = Xapian::Query(string())
	A query which matches all documents in the database.
static const Xapian::Query	MatchNothing = Xapian::Query()
	A query which matches no documents.
Private Member Functions
void	add_subquery (const Query &subq)
	Add a subquery by reference.
void	add_subquery (const Query *subq)
	Add a subquery by pointer.
void	add_subquery (const std::string &tname)
	Add a subquery which is a single term.
void	start_construction (Query::op op_, Xapian::termcount parameter)
	Setup the internals for the query, with the appropriate operator.
void	end_construction ()
	Check that query has an appropriate number of arguments, etc,.
void	abort_construction ()
	Abort construction of the query: delete internal.
Private Attributes
Xapian::Internal::RefCntPtr < Internal >	internal