Soprano.Util.AsyncQuery

KDE 4.5 PyKDE API Reference

- KDE's Python API

# AsyncQuery Class Reference

`from PyKDE4.soprano import *`

Inherits: QObject,Soprano.Error.ErrorCache
Namespace: Soprano.Util

## Detailed Description

\class AsyncQuery asyncquery.h Soprano/Util/AsyncQuery

A wrapper around Soprano.Model which executes a query in a separate thread and allows to iterate the results asyncroneously.

In contrast to AsyncModel everything is asyncroneous, not only the execution of the query itself, but also the iteration.

For executing a query asyncroneously simply use the static executeQuery() method which will return a pointer to the newly created query object.

AsyncQuery objects will always delete themselves once the end of the iterator is reached and the finished signal has been emitted. This also means that boolean results need to be read in a slot connected to the finished() signal.

Typical usage would be to connect to the nextReady() signal, use one of the binding() methods or currentStatement() to get the current value, and then call next() in it to trigger async iteration to the next element:

     void MyQueryHandler.slotNextReady( Soprano.Util.AsyncQuery* query ) {
         // do something with the current value
         addToSomeList( query->binding(0) );

         // trigger async iteration to the next element
         query->next();
     }

\sa Soprano.Util.AsyncModel

Author:
  Sebastian Trueg <trueg@kde.org>

Since:
  2.4

## Signals
| finished (Soprano.Util.AsyncQuery query)
| nextReady (Soprano.Util.AsyncQuery query)
## Methods
| __init__ (self)
Soprano.Node | binding (self, QString name)
Soprano.Node | binding (self, int offset)
int | bindingCount (self)
QStringList | bindingNames (self)
bool | boolValue (self)
| close (self)
Soprano.BindingSet | currentBindings (self)
Soprano.Statement | currentStatement (self)
bool | isBinding (self)
bool | isBool (self)
bool | isGraph (self)
bool | next (self)
## Static Methods
Soprano.Util.AsyncQuery | executeQuery (Soprano.Model model, QString query, Soprano.Query.QueryLanguage language, QString userQueryLanguage=QString())

## Signal Documentation

finished | ( | Soprano.Util.AsyncQuery | query
| ) |  |  |

Emitted once the last element has been read and the internal iterator is finished after the last call to next() or if the result of a boolean query is available.

Once this signals has been emitted the query will delete itself. In a slot connected to this signal ErrorCache.lastError() can be used to retrieve information about the success of the query.

Parameters:

  | query | The query itself for convinience.

Signal syntax:
  `QObject.connect(source, SIGNAL("finished(Soprano::Util::AsyncQuery*)"), target_slot)`

nextReady | ( | Soprano.Util.AsyncQuery | query
| ) |  |  |

Emitted once the next value is ready when iterating the result via next(). Will be emitted automatically for the first element. The last call in a connected slot should be next() to trigger iteration to the next element.

Parameters:

  | query | The query itself for convinience.

Signal syntax:
  `QObject.connect(source, SIGNAL("nextReady(Soprano::Util::AsyncQuery*)"), target_slot)`

## Method Documentation

__init__ | ( |  | self ) |

Soprano.Node binding | ( | self, |
|  | QString | name
| ) |  |  |

Get the current binding for a variable by index.

Parameters:

  | offset | The index of the requested variable.

This method does only make sense for tuple queries.

Returns:
  The binding for the requested variable or and invalid node if offset is out of bounds, i.e. bigger or equal to bindingCount().

Soprano.Node binding | ( | self, |
|  | int | offset
| ) |  |  |

Get the current binding for a variable by index.

Parameters:

  | offset | The index of the requested variable.

This method does only make sense for tuple queries.

Returns:
  The binding for the requested variable or and invalid node if offset is out of bounds, i.e. bigger or equal to bindingCount().

int bindingCount | ( |  | self ) |

The number of bindings in this query result.

This method does only make sense for tuple queries.

Returns:
  The number of bindings.

QStringList bindingNames | ( |  | self ) |

This method does only make sense for tuple queries.

Returns:
  The names of the bound variables in this query result.

bool boolValue | ( |  | self ) |

This method does only make sense for boolean queries.

Returns:
  The result of a boolean query (SPARQL ASK).

\sa isBool()

close | ( |  | self ) |

Closes the query. This will cancel the query if it is not finished yet. Afterwards the query will delete itself. It has the same effect as deleting the query object manually.

finished() will always be emitted in case the query was not finished yet.

Soprano.BindingSet currentBindings | ( |  | self ) |

Convenience method that puts all current bindings into one map. This method does only make sense for tuple queries.

Soprano.Statement currentStatement | ( |  | self ) |

Retrieve the current Statement after nextReady has been emitted. This method does only make sense for graph queries.

bool isBinding | ( |  | self ) |

Check if this is a tuple result.

Returns:
  true if this result refers to a tuple query, i.e. currentBindings(), binding(), bindingCount(), and bindingNames() return valid values.

bool isBool | ( |  | self ) |

Check if this is a boolean result.

There is no need to call next() for boolean results. However, for internal reasons backends need to always return true for boolean queries.

Returns:
  true if this result refers to a boolean query (SPARQL ASK), i.e. boolValue() returns a valid value.

bool isGraph | ( |  | self ) |

Check if this is a graph result.

Returns:
  true if this result refers to a graph query, i.e. currentStatement() returns valid values.

bool next | ( |  | self ) |

Trigger iteration to the next element once the current has been read via one of the binding() methods or currentStatement(). Be aware that this has not to be called for the first element which is emitted automatically. Once the next result has been retrieved the nextReady signal is emitted.

Returns:
  true if successful, false if the iteration reached the end.

## Static Method Documentation

Soprano.Util.AsyncQuery executeQuery | ( | Soprano.Model | model,
|  | QString | query,
|  | Soprano.Query.QueryLanguage | language,
|  | QString | userQueryLanguage=QString()
| ) |  |  |

Create a new query object.

Parameters:

  | model | The model to execute the query on.

Parameters:

  | query | The query to evaluate.

Parameters:

  | language | The %query language used to encode query.

Parameters:

  | userQueryLanguage | If language equals Query.QueryLanguageUser userQueryLanguage defines the language to use.

\sa Model.executeQuery

Returns:
  A new AsyncQuery instance which is ready to be used or 0 if model is 0. The query will delete itself once it is finished. It can also be deleted at any point in time to cancel the query.