KDE 4.9 PyKDE API Reference

- KDE's Python API

# ComparisonTerm Class Reference

`from PyKDE4.nepomuk import *`

Inherits: Nepomuk.Query.SimpleTerm → Nepomuk.Query.Term
Namespace: Nepomuk.Query

## Detailed Description

\class ComparisonTerm comparisonterm.h Nepomuk/Query/ComparisonTerm

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 Nepomuk.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@kde.org>

Since:
  4.4

## Enumerations

AggregateFunction | { NoAggregateFunction, Count, DistinctCount, Max, Min, Sum, DistinctSum, Average, DistinctAverage }
Comparator | { Contains, Regexp, Equal, Greater, Smaller, GreaterOrEqual, SmallerOrEqual }

## Methods

| __init__ (self)
| __init__ (self, Nepomuk.Query.ComparisonTerm term)
| __init__ (self, Nepomuk.Types.Property property, Nepomuk.Query.Term term, Nepomuk.Query.ComparisonTerm.Comparator comparator=Nepomuk.Query.ComparisonTerm.Contains)
Nepomuk.Query.ComparisonTerm.AggregateFunction | aggregateFunction (self)
Nepomuk.Query.ComparisonTerm.Comparator | comparator (self)
Nepomuk.Query.ComparisonTerm | inverted (self)
bool | isInverted (self)
Nepomuk.Types.Property | property (self)
| setAggregateFunction (self, Nepomuk.Query.ComparisonTerm.AggregateFunction function)
| setComparator (self, Nepomuk.Query.ComparisonTerm.Comparator a0)
| setInverted (self, bool invert)
| setProperty (self, Nepomuk.Types.Property a0)
| setSortWeight (self, int weight, Qt::SortOrder sortOrder=Qt.AscendingOrder)
| setVariableName (self, QString name)
Qt::SortOrder | sortOrder (self)
int | sortWeight (self)
QString | variableName (self)

## Method Documentation

__init__ | ( |  | self ) |

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

__init__ | ( | self, |
|  | Nepomuk.Query.ComparisonTerm | term
| ) |  |  |

Copy constructor.

__init__ | ( | self, |
|  | Nepomuk.Types.Property | property,
|  | Nepomuk.Query.Term | term,
|  | Nepomuk.Query.ComparisonTerm.Comparator | comparator=Nepomuk.Query.ComparisonTerm.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.

Parameters:

  | term | The sub term to match to.

Parameters:

  | comparator | The Comparator to use for comparison. Not all Comparators make sense with all sub term types.

Nepomuk.Query.ComparisonTerm.AggregateFunction aggregateFunction | ( |  | self ) |

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

\sa setAggregateFunction()

Since:
  4.5

Nepomuk.Query.ComparisonTerm.Comparator comparator | ( |  | self ) |

The Comparator used by ComparisonTerm Terms.

\sa setComparator

Nepomuk.Query.ComparisonTerm inverted | ( |  | self ) |

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);

\sa setInverted()

Since:
  4.5

bool isInverted | ( |  | self ) |

Returns:
  true if the comparison is inverted.

\sa setInverted

Since:
  4.5

Nepomuk.Types.Property property | ( |  | self ) |

A property used for ComparisonTerm Terms. An invalid property will act as a wildcard.

\sa setProperty

setAggregateFunction | ( | self, |
|  | Nepomuk.Query.ComparisonTerm.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.

\sa aggregateFunction()

Since:
  4.5

setComparator | ( | self, |
|  | Nepomuk.Query.ComparisonTerm.Comparator | a0
| ) |  |  |

Set the comparator

setInverted | ( | self, |
|  | 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.

\sa inverted()

Since:
  4.5

setProperty | ( | self, |
|  | Nepomuk.Types.Property | a0
| ) |  |  |

Set the property for ComparisonTerm Terms. An invalid property will act as a wildcard.

\sa property

setSortWeight | ( | self, |
|  | 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 \p 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.

Parameters:

  | sortOrder | The sort order to use for this term.

\sa sortWeight()

Since:
  4.5

setVariableName | ( | self, |
|  | 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()

\sa Result.additionalBinding(), Query.HandleInverseProperties, examples_query

Since:
  4.5

Qt::SortOrder sortOrder | ( |  | self ) |

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

Since:
  4.5

int sortWeight | ( |  | self ) |

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

Since:
  4.5

QString variableName | ( |  | self ) |

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

\sa setVariableName()

Since:
  4.5

## Enumeration Documentation

AggregateFunction

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

\sa setAggregateFunction()

Since:
  4.5

Enumerator:

  NoAggregateFunction = 0 |
  Count |
  DistinctCount |
  Max |
  Min |
  Sum |
  DistinctSum |
  Average |
  DistinctAverage |

Comparator

%ComparisonTerm supports different ways to compare values.

Enumerator:

  Contains |
  Regexp |
  Equal |
  Greater |
  Smaller |
  GreaterOrEqual |
  SmallerOrEqual |