KDE 4.5 PyKDE API Reference

- KDE's Python API

# Query Class Reference

`from PyKDE4.nepomuk import *`

Subclasses: Nepomuk.Query.FileQuery
Namespace: Nepomuk.Query

## Detailed Description

\class Query query.h Nepomuk/Query/Query

A Nepomuk desktop query.

A Query consists or a combination of Terms that can be optionally restricted via a limit (setLimit()) or folder filters (setIncludeFolders() and setExcludeFolders()).

Additionally setRequestProperties() allows to retrieve additional information about the results.

Queries can be easily converted to SPARQL via the toSparqlQuery() method or to search URLs ready for KIO.DirLister using toSearchUrl().

The typical usage of a Query instance would be QueryServiceClient.query(). However one can also use toSparqlQuery() to convert it into a SPARQL query string and use that string in QueryServiceClient.sparqlQuery() or even directly in Soprano.Model.executeQuery() via ResourceManager.instance()->mainModel() or in a custom Model.

\sa QueryParser, FileQuery

Author:
  Sebastian Trueg <trueg@kde.org>

Since:
  4.4

## Enumerations
SparqlFlag | { NoFlags, CreateCountQuery, HandleInverseProperties }
## Methods
| __init__ (self)
| __init__ (self, Nepomuk.Query.Term term)
| __init__ (self, Nepomuk.Query.Query a0)
| addRequestProperty (self, Nepomuk.Query.Query.RequestProperty property)
bool | isFileQuery (self)
bool | isValid (self)
int | limit (self)
int | offset (self)
bool | operator == (self, Nepomuk.Query.Query query)
[Nepomuk.Query.Query.RequestProperty] | requestProperties (self)
{QString:Nepomuk.Types.Property} | requestPropertyMap (self)
| setLimit (self, int a0)
| setOffset (self, int offset)
| setRequestProperties (self, [Nepomuk.Query.Query.RequestProperty] properties)
| setTerm (self, Nepomuk.Query.Term a0)
Nepomuk.Query.Term | term (self)
KUrl | toSearchUrl (self, Nepomuk.Query.Query.SparqlFlags flags=Nepomuk.Query.Query.NoFlags)
KUrl | toSearchUrl (self, QString customTitle, Nepomuk.Query.Query.SparqlFlags flags=Nepomuk.Query.Query.NoFlags)
QString | toSparqlQuery (self, Nepomuk.Query.Query.SparqlFlags flags=Nepomuk.Query.Query.NoFlags)
QString | toString (self)
## Static Methods
Nepomuk.Query.Query | fromQueryUrl (KUrl url)
Nepomuk.Query.Query | fromString (QString queryString)
QString | sparqlFromQueryUrl (KUrl url)
QString | titleFromQueryUrl (KUrl url)

## Method Documentation

__init__ | ( |  | self ) |

Copy constructor.

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

Create a query with root term term.

__init__ | ( | self, |
|  | Nepomuk.Query.Query | a0
| ) |  |  |

Copy constructor.

addRequestProperty | ( | self, |
|  | Nepomuk.Query.Query.RequestProperty | property
| ) |  |  |

Add a property that should be reported with each search result.

Parameters:

  | property | The requested property.

ComparisonTerm.setVariableName() provides a more flexible (but also slightly more complicated) way to select additional results.

\sa setRequestProperties, requestProperties, ComparisonTerm.setVariableName()

bool isFileQuery | ( |  | self ) |

Returns:
  true if this is a file query that will only return files and folders.

\sa FileQuery

Since:
  4.5

bool isValid | ( |  | self ) |

Returns:
  true if the query is valid, i.e. it has a valid term().

int limit | ( |  | self ) |

The maximum number of results that this query should yield.

\sa setLimit()

int offset | ( |  | self ) |

The first result that should be retrieved.

\sa setOffset()

Since:
  4.5

bool operator == | ( | self, |
|  | Nepomuk.Query.Query | query
| ) |  |  |

Comparison operator.

Returns:
  true if this query is equal to query.

[Nepomuk.Query.Query.RequestProperty] requestProperties | ( |  | self ) |

Returns:
  The list of RequestProperty instances set via addRequestProperty and setRequestProperties.

{QString:Nepomuk.Types.Property} requestPropertyMap | ( |  | self ) |

Build a request property map as used in QueryServiceClient.sparqlQuery() from the request properties set via addRequestProperty() and setRequestProperties().

Be aware that in most situations it is much simpler to use QueryServiceClient.query().

setLimit | ( | self, |
|  | int | a0
| ) |  |  |

Set the maximum number of results this query should yield.

\sa limit

setOffset | ( | self, |
|  | int | offset
| ) |  |  |

The first result that should be retrieved. This can be combined with setLimit() to do paged results.

Since:
  4.5

setRequestProperties | ( | self, |
|  | [Nepomuk.Query.Query.RequestProperty] | properties
| ) |  |  |

Set the properties that should be reported with each search result.

Parameters:

  | properties | The requested properties.

ComparisonTerm.setVariableName() provides a more flexible (but also slightly more complicated) way to select additional results.

\sa addRequestProperty, requestProperties, ComparisonTerm.setVariableName()

setTerm | ( | self, |
|  | Nepomuk.Query.Term | a0
| ) |  |  |

Set the root term of the query.

\sa term

Nepomuk.Query.Term term | ( |  | self ) |

The root term of the query. This can be any type of term.

\sa setTerm()

KUrl toSearchUrl | ( | self, |
|  | Nepomuk.Query.Query.SparqlFlags | flags=Nepomuk.Query.Query.NoFlags
| ) |  |  |

Convert the query into a URL which can be listed using KIO.DirLister. The URL will use the nepomuksearch:/ KIO protocol to handle the listing of search results.

This is the perfect method for listing results in file managers or file dialogs.

Parameters:

  | customTitle | An optional custom title that will be used for the listing of the results. This is achieved by setting the KIO.UDSEntry.UDS_DISPLAY_NAME to the customTitle value.

Parameters:

  | flags | Optional flags to change the query. Query.CreateCountQuery is not supported and will silently be dropped from flags.

Returns:
  A URL which will list a virtual folder containing all search results from this query or an invalid URL in case this query is invalid.

\sa toSparqlQuery(), SparqlFlag

Since:
  4.5

KUrl toSearchUrl | ( | self, |
|  | QString | customTitle,
|  | Nepomuk.Query.Query.SparqlFlags | flags=Nepomuk.Query.Query.NoFlags
| ) |  |  |

Convert the query into a URL which can be listed using KIO.DirLister. The URL will use the nepomuksearch:/ KIO protocol to handle the listing of search results.

This is the perfect method for listing results in file managers or file dialogs.

Parameters:

  | customTitle | An optional custom title that will be used for the listing of the results. This is achieved by setting the KIO.UDSEntry.UDS_DISPLAY_NAME to the customTitle value.

Parameters:

  | flags | Optional flags to change the query. Query.CreateCountQuery is not supported and will silently be dropped from flags.

Returns:
  A URL which will list a virtual folder containing all search results from this query or an invalid URL in case this query is invalid.

\sa toSparqlQuery(), SparqlFlag

Since:
  4.5

QString toSparqlQuery | ( | self, |
|  | Nepomuk.Query.Query.SparqlFlags | flags=Nepomuk.Query.Query.NoFlags
| ) |  |  |

Convert the query into a SPARQL query which can be used with the Nepomuk query service or directly in Soprano.Model.executeQuery.

The resulting query will bind the results to variable 'r'. Request properties will be bound to variables 'reqProp1' through 'reqPropN'.

If you are looking for a serialization of a Query which can be parsed again use toString() instead.

Warning:
  The SPARQL queries created by this method contain SPARQL extensions from Virtuoso and will not work with other RDF storage solutions!

Parameters:

  | flags | Optional flags to change the query.

Returns:
  The SPARQL representation of this query or an empty string if the query could not be converted (invalid query.)

\sa toString(), toSearchUrl(), SparqlFlag

QString toString | ( |  | self ) |

Encode the Query in a string. Be aware that this does NOT create a SPARQL query. The returned string can be used to serialize queries that can later be read via fromString().

\sa fromString(), toSparqlQuery()

Since:
  4.5

## Static Method Documentation

Nepomuk.Query.Query fromQueryUrl | ( | KUrl | url
| ) |  |  |

Extract a query from a nepomuksearch:/ query URL.

Returns:
  The query that was encoded in url or an invalid query if either url is not a nepomuksearch:/ URL or if it contains a pure SPARQL query. In the latter case sparqlFromQueryUrl() can be used to extract that query.

\sa sparqlFromQueryUrl()

Since:
  4.5

Nepomuk.Query.Query fromString | ( | QString | queryString
| ) |  |  |

Parse a Query that has been encoded as a string via toString().

Warning:
  This method can NOT parse SPARQL syntax.

\sa toString()

Since:
  4.5

QString sparqlFromQueryUrl | ( | KUrl | url
| ) |  |  |

Extract the SPARQL query from a nepomuksearch:/ query URL. All kinds of nepomuksearch:/ URLs are supported.

Returns:
  The SPARQL query string representing the query encoded in url.

\sa fromQueryUrl()

Since:
  4.5

QString titleFromQueryUrl | ( | KUrl | url
| ) |  |  |

Extact the title from a nepomuksearch:/ query URL. The title is either a custom title which has been specified in toSearchUrl(const QString&, SparqlFlags) or the user query string in case of nepomuksearch:/myquery URLs.

Returns:
  A title for the query url or an empty string in case url is not a nepomuksearch:/ URL or a useful title cannot be extracted.

Since:
  4.5

## Enumeration Documentation

SparqlFlag

Aditional flags modifying the behaviour of toSparqlQuery() and toSearchUrl().

Enumerator:

  NoFlags = 0x0 |
  CreateCountQuery = 0x1 |
  HandleInverseProperties = 0x2 |