#include <Nepomuk2/Query/ComparisonTerm>

Inheritance diagram for Nepomuk2::Query::ComparisonTerm:

Public Types
enum	AggregateFunction { NoAggregateFunction = 0, Count, DistinctCount, Max, Min, Sum, DistinctSum, Average, DistinctAverage }

enum	Comparator { Contains, Regexp, Equal, Greater, Smaller, GreaterOrEqual, SmallerOrEqual }

Public Types inherited from Nepomuk2::Query::Term
enum	Type { Invalid, Literal, Resource, And, Or, Comparison, ResourceType, Negation, Optional }

Public Member Functions
	ComparisonTerm ()

	ComparisonTerm (const ComparisonTerm &term)

	ComparisonTerm (const Types::Property &property, const Term &term, Comparator comparator=Contains)

	~ComparisonTerm ()

AggregateFunction	aggregateFunction () const

Comparator	comparator () const

ComparisonTerm	inverted () const

bool	isInverted () const

ComparisonTerm &	operator= (const ComparisonTerm &term)

Types::Property	property () const

void	setAggregateFunction (AggregateFunction function)

void	setComparator (Comparator)

void	setInverted (bool invert)

void	setProperty (const Types::Property &)

void	setSortWeight (int weight, Qt::SortOrder sortOrder=Qt::AscendingOrder)

void	setVariableName (const QString &name)

Qt::SortOrder	sortOrder () const

int	sortWeight () const

QString	variableName () const

Public Member Functions inherited from Nepomuk2::Query::SimpleTerm
	~SimpleTerm ()

void	setSubTerm (const Term &term)

Term	subTerm () const

Public Member Functions inherited from Nepomuk2::Query::Term
	Term ()

	Term (const Term &other)

	~Term ()

bool	isAndTerm () const

bool	isComparisonTerm () const

bool	isLiteralTerm () const

bool	isNegationTerm () const

bool	isOptionalTerm () const

bool	isOrTerm () const

bool	isResourceTerm () const

bool	isResourceTypeTerm () const

bool	isValid () const

bool	operator!= (const Term &term) const

QDebug	operator<< (QDebug) const

Term &	operator= (const Term &other)

bool	operator== (const Term &term) const

Term	optimized () const

void	setUserData (const QString &key, const QVariant &value)

AndTerm	toAndTerm () const

AndTerm &	toAndTerm ()

ComparisonTerm	toComparisonTerm () const

ComparisonTerm &	toComparisonTerm ()

LiteralTerm	toLiteralTerm () const

LiteralTerm &	toLiteralTerm ()

NegationTerm	toNegationTerm () const

NegationTerm &	toNegationTerm ()

OptionalTerm	toOptionalTerm () const

OptionalTerm &	toOptionalTerm ()

OrTerm	toOrTerm () const

OrTerm &	toOrTerm ()

ResourceTerm	toResourceTerm () const

ResourceTerm &	toResourceTerm ()

ResourceTypeTerm	toResourceTypeTerm () const

ResourceTypeTerm &	toResourceTypeTerm ()

QString	toString () const

Type	type () const

QVariant	userData (const QString &key) const

Related Functions
(Note that these are not member functions.)
Term	operator!= (const Types::Property &property, const Term &term)

ComparisonTerm	operator< (const Types::Property &property, const Term &term)

ComparisonTerm	operator<= (const Types::Property &property, const Term &term)

ComparisonTerm	operator== (const Types::Property &property, const Term &term)

ComparisonTerm	operator> (const Types::Property &property, const Term &term)

ComparisonTerm	operator>= (const Types::Property &property, const Term &term)

Related Functions inherited from Nepomuk2::Query::Term
static Term	fromProperty (const Types::Property &property, const Variant &variant)

Additional Inherited Members
Static Public Member Functions inherited from Nepomuk2::Query::Term
static Term	fromString (const QString &s)

static Term	fromVariant (const Variant &variant)

Detailed Description

A term matching the value of a property.

The ComparisonTerm is the most important term in the query API. It can be used to match the values of properties. As such its core components are a property(), a comparator() (see Comparator for details) and a subTerm(). The latter can be any other term including AndTerm, OrTerm, or even an invalid term. The matching is done as follows:

A LiteralTerm as subTerm() is directly matched to the value of a literal property (see also Nepomuk2::Types::Property::literalRangeType()) or to the labels of related resources in case of a property that has a resource range.
An invalid sub term simply matches any resource or value, effectively acting as a wildcard.
Any other term type will be used as a sort of subquery to match the related resources. This means that the property() needs to have a resource range.

In addition to these basic features ComparisonTerm has a few tricks up its sleeve:

By forcing the variable name via setVariableName() it is possible to include a value matched by the term in the resulting SPARQL query (Query::toSparqlQuery()) or accessing it via Result::additionalBinding().
It is possible to set an aggregate function via setAggregateFunction() to count or sum up the results instead of returning the actual values.
Using setSortWeight() the sorting of the results in the final query can be influenced in a powerful way - especially when combined with setAggregateFunction().

Author: Sebastian Trueg trueg.nosp@m.@kde.nosp@m..org

Since: 4.4

Definition at line 70 of file comparisonterm.h.

Member Enumeration Documentation

enum Nepomuk2::Query::ComparisonTerm::AggregateFunction

Aggregate functions which can be applied to a comparison term to influence the value they return.

See also: setAggregateFunction()

Since: 4.5

Enumerator
NoAggregateFunction	Do not use any aggregate function.
Count	Count the number of matching results instead of returning the results themselves. For counting the results of a complete query use Query::CreateCountQuery.
DistinctCount	The same as Count except that no two similar results are counted twice.
Max	Return the maximum value of all results instead of the results themselves. Does only make sense for numerical values.
Min	Return the minimum value of all results instead of the results themselves. Does only make sense for numerical values.
Sum	Return the sum of all result values instead of the results themselves. Does only make sense for numerical values.
DistinctSum	The same as Sum except that no two similar results are added twice.
Average	Return the average value of all results instead of the results themselves. Does only make sense for numerical values.
DistinctAverage	The same as Average except that no two similar results are counted twice.

Definition at line 125 of file comparisonterm.h.

enum Nepomuk2::Query::ComparisonTerm::Comparator

ComparisonTerm supports different ways to compare values.

Enumerator
Contains	A LiteralTerm sub-term is matched against string literal values. Case is ignored. The literal value can contain wildcards like *.
Regexp	A LiteralTerm sub-term is matched against a string literal value using the literal term's value as a regular expression. It is highly recommended to prefer Contains over Regexp as the latter will result in much slower SPARQL REGEX filters.
Equal	A sub-term is matched one-to-one. Sub-terms can be any other term type.
Greater	A LiteralTerm sub-term is matched to greater literal values.
Smaller	A LiteralTerm sub-term is matched to smaller literal values.
GreaterOrEqual	A LiteralTerm sub-term is matched to greater or equal literal values.
SmallerOrEqual	A LiteralTerm sub-term is matched to smaller or equal literal values.

Definition at line 76 of file comparisonterm.h.

Constructor & Destructor Documentation

Nepomuk2::Query::ComparisonTerm::ComparisonTerm ( )

Default constructor: creates a comparison term that matches all properties.

Definition at line 426 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm::ComparisonTerm ( const ComparisonTerm & term )

Copy constructor.

Definition at line 432 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm::ComparisonTerm	(	const Types::Property &	property,
		const Term &	term,
		Comparator	comparator = `Contains`
	)

Convinience constructor which covers most simple use cases.

Parameters

property	The property that should be matched. An invalid property will act as a wildcard.
term	The sub term to match to.
comparator	The Comparator to use for comparison. Not all Comparators make sense with all sub term types.

Definition at line 438 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm::~ComparisonTerm ( )

Destructor.

Definition at line 448 of file comparisonterm.cpp.

Member Function Documentation

Nepomuk2::Query::ComparisonTerm::AggregateFunction Nepomuk2::Query::ComparisonTerm::aggregateFunction ( ) const

The aggregate function to be used with the additional binding set in setVariableName().

See also: setAggregateFunction()

Since: 4.5

Definition at line 509 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm::Comparator Nepomuk2::Query::ComparisonTerm::comparator ( ) const

The Comparator used by ComparisonTerm Terms.

See also: setComparator

Definition at line 460 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm Nepomuk2::Query::ComparisonTerm::inverted ( ) const

Create an inverted copy of this ComparisonTerm.

This is a convenience method to allow inline creation of inverted comparison terms when creating queries in a single line of code.

Be aware that calling this method twice wil result in a non-inverted comparison term:

// always true:

(term.inverted().inverted() == term);

See also: setInverted()

Since: 4.5

Definition at line 552 of file comparisonterm.cpp.

bool Nepomuk2::Query::ComparisonTerm::isInverted ( ) const

Returns: true if the comparison is inverted.

See also: setInverted

Since: 4.5

Definition at line 538 of file comparisonterm.cpp.

Nepomuk2::Query::ComparisonTerm & Nepomuk2::Query::ComparisonTerm::operator= ( const ComparisonTerm & term )

Assignment operator.

Definition at line 453 of file comparisonterm.cpp.

Nepomuk2::Types::Property Nepomuk2::Query::ComparisonTerm::property ( ) const

A property used for ComparisonTerm Terms.

An invalid property will act as a wildcard.

See also: setProperty

Definition at line 467 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setAggregateFunction ( AggregateFunction function )

Set an aggregate function which changes the result.

The typical usage is to count the results instead of actually returning them. For counting the results of a complete query use Query::CreateCountQuery.

See also: aggregateFunction()

Since: 4.5

Definition at line 502 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setComparator ( Comparator comparator )

Set the comparator.

Definition at line 474 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setInverted ( bool invert )

Invert the comparison, i.e.

make the subterm the subject of the term and match to objects of the term.

A typical example would be:

ComparisonTerm term( Soprano::Vocabulary::NAO::hasTag(),
                     ResourceTerm( somefile ) );
term.setInverted(true);

which would yield a query like the following:

select ?r where { <somefile> nao:hasTag ?r . }

to get all tags attached to a file.

Be aware that this does only make sense with sub terms that match to resources. When using LiteralTerm as a sub term invert is ignored.

See also: inverted()

Since: 4.5

Definition at line 545 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setProperty ( const Types::Property & property )

Set the property for ComparisonTerm Terms.

An invalid property will act as a wildcard.

See also: property

Definition at line 481 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setSortWeight	(	int	weight,
		Qt::SortOrder	sortOrder = `Qt::AscendingOrder`
	)

Set the sort weight of this property.

By default all ComparisonTerms have a weight of 0 which means that they are ignored for sorting. By setting weight to a value different from 0 (typically higher than 0) the comparison subterm will be used for sorting.

Be aware that as with the variableName() sorting does not apply to sub terms of types ResourceTerm or LiteralTerm. In those cases the value will be ignored. The only exception are LiteralTerm sub terms that are compared other than with equals.

Parameters

weight	The new sort weight. If different from 0 this term will be used for sorting in the Query.
sortOrder	The sort order to use for this term.

See also: sortWeight()

Since: 4.5

Definition at line 516 of file comparisonterm.cpp.

void Nepomuk2::Query::ComparisonTerm::setVariableName ( const QString & name )

Set the variable name that is to be used for the variable to match to.

The variable will then be added to the set of variables returned in the results and can be read via Result::additionalBinding(). Setting the variable name can be seen as a less restricted variant of Query::addRequestProperty().

When manually setting the variable name on more than one ComparisonTerm there is no guarantee for the uniqueness of variable names anymore which can result in unwanted query results. However, this can also be used deliberately in case one needs to compare the same variable twice:

ComparisonTerm ct1( prop1, Term() );
ComparisonTerm ct1( prop2, Term() );
ct1.setVariableName( "myvar" );
ct2.setVariableName( "myvar" );

The above example would result in a SPARQL query pattern along the lines of

?r <prop1> ?myVar .

?r <prop2> ?myVar .

Be aware that the variable name does not apply to sub terms of types ResourceTerm or LiteralTerm. In those cases the value will be ignored. The only exception are LiteralTerm sub terms that are compared other than with equals.

Parameters

name	The name of the variable to be used when requesting the binding via Result::additionalBinding()

See also: Result::additionalBinding(), Query::HandleInverseProperties, Query Examples

Since: 4.5

Definition at line 488 of file comparisonterm.cpp.

Qt::SortOrder Nepomuk2::Query::ComparisonTerm::sortOrder ( ) const

Returns: The sort order as set in setSortWeight().

Since: 4.5

Definition at line 531 of file comparisonterm.cpp.

int Nepomuk2::Query::ComparisonTerm::sortWeight ( ) const

Returns: The sort weight as set in setSortWeight() or 0 if sorting is disabled for this term.

Since: 4.5

Definition at line 524 of file comparisonterm.cpp.

QString Nepomuk2::Query::ComparisonTerm::variableName ( ) const

The variable name set in setVariableName() or an empty string if none has been set.

See also: setVariableName()

Since: 4.5

Definition at line 495 of file comparisonterm.cpp.

Friends And Related Function Documentation

Term operator!=	(	const Types::Property &	property,
		const Term &	term
	)

Since: 4.6

Returns: A Term equvalent to:

NegationTerm::negateTerm( ComparisonTerm( property, term, ComparisonTerm::Equal ) );

See also: NegationTerm

ComparisonTerm operator<	(	const Types::Property &	property,
		const Term &	term
	)

Returns: A ComparisonTerm equvalent to:

ComparisonTerm( property, term, ComparisonTerm::Smaller );

Since: 4.6

ComparisonTerm operator<=	(	const Types::Property &	property,
		const Term &	term
	)

Returns: A ComparisonTerm equvalent to:

ComparisonTerm( property, term, ComparisonTerm::SmallerOrEqual );

Since: 4.6

ComparisonTerm operator==	(	const Types::Property &	property,
		const Term &	term
	)

Returns: A ComparisonTerm equvalent to:

ComparisonTerm( property, term, ComparisonTerm::Equal );

Since: 4.6

ComparisonTerm operator>	(	const Types::Property &	property,
		const Term &	term
	)

Returns: A ComparisonTerm equvalent to:

ComparisonTerm( property, term, ComparisonTerm::Greater );

Since: 4.6

ComparisonTerm operator>=	(	const Types::Property &	property,
		const Term &	term
	)

Returns: A ComparisonTerm equvalent to:

ComparisonTerm( property, term, ComparisonTerm::GreaterOrEqual );

Since: 4.6

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

Nepomuk-Core

Public Types

Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Nepomuk-Core

kdelibs API Reference

Search