# class QueryResultIterator

###

Module | soprano
Namespace | Soprano
Class | QueryResultIterator
Inherits | Iterator<BindingSet>

\class QueryResultIterator queryresultiterator.h Soprano/QueryResultIterator

An iterator for query results.

%Query results in %Soprano are wrapped in a QueryResultIterator.

%Query iterators are returned by Model.executeQuery(). In contrast to NodeIterator or StatementIterator %QueryResultIterator has a set of different access methods for the current dataset which can be one of three things:

- A Statement: Graph query results are represented as a stream of statements.
See also currentStatement() and iterateStatements().
- A BindingSet: Tuple query results are represented by a set of variable bindings
according to the variables used in the query. The bindings can be accessed as a set through the normal Iterator method current() or separately through #binding(int) const or #binding(const QString&) const.
- A boolean value: This is a special case in which the query was a boolean query
(a SPARQL ASK query). In this case there is nothing to iterate but only a single boolean value which can be accessed through boolValue().

Example:

    QueryResultIterator it = model->executeQuery( someGraphQuery );
    while( it.next() ) {
    doSomething( it.currentStatement() );
    }

    QueryResultIterator it2 = model->executeQuery( someTupleQuery );
    while( it.next() ) {
    doSomethingElse( it.currentBindings() );
    doSomethingCompletelyDifferent( it.binding( "x" ) );
    doSomethingEntirelyDifferent( it.binding( 0 ) );
    }

Many backends do lock the underlying Model during iteration. Thus, it is always a good idea to cache the results if they are to be used to modify the model to prevent a deadlock:

    Soprano.QueryResultIterator it = model->executeQuery( someTupleQuery );
    QList<BindingSet> allBindings = it.allBindings();
    Q_FOREACH( Soprano.BindingSet bs, allBindings ) {
    modifyTheModel( model, bs );
    }

For further details on %Soprano iterators see Iterator.

Be aware that iterators in Soprano are shared objects which means that copies of one iterator object work on the same data.

Author Daniele Galdi <daniele.galdi@gmail.com>
Sebastian Trueg <trueg@kde.org>

### methods

- QueryResultIterator ( )

  returns ctor

  Creates and empty, invalid iterator.

- QueryResultIterator (a0)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  a0 | Soprano.QueryResultIterator |

  Copy constructor. Copies of iterators share their data.

- QueryResultIterator (qr)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  qr | Soprano.QueryResultIteratorBackend |

  Create a new QueryResultIterator which uses qr as backend. QueryResultIterator will take ownership of the QueryResultIteratorBackend.

- allBindings ( )

  returns QList<Soprano::BindingSet>

  Convenience method that collects all binding sets that are left in the iterator.

- binding (name)

  returns Soprano.Node

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  Get the current binding for a variable.

  name - The name 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 the bindings do not contain the variable.

- binding (offset)

  returns Soprano.Node

  Argument | Type | Default
  --- | --- | ---
  offset | int |

  Get the current binding for a variable by index.

  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().

- bindingCount ( )

  returns int

  The number of bindings in this query result.

  This method does only make sense for tuple queries.

  Returns The number of bindings.

- bindingNames ( )

  returns QStringList

  This method does only make sense for tuple queries.

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

- boolValue ( )

  returns bool

  This method does only make sense for boolean queries.

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

  See also isBool()

- currentBindings ( )

  returns Soprano.BindingSet

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

- currentStatement ( )

  returns Soprano.Statement

  Retrieve the current Statement after a call to next. This method does only make sense for graph queries.

- isBinding ( )

  returns bool

  Check if this is a tuple result.

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

- isBool ( )

  returns bool

  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.

- isGraph ( )

  returns bool

  Check if this is a graph result.

  Returns true if this result refers to a graph query, i.e. currentStatement() and iterateStatements() return valid values.

- iterateBindings (variableName)

  returns Soprano.NodeIterator

  Argument | Type | Default
  --- | --- | ---
  variableName | QString |

  Convenience method that creates an iterator over one column of bindings in this query result. This method does only make sense for tuple queries.

  variableName - The name of the requested variable.

  The new iterator is just a wrapper around this one. Thus, changing it will also change this one.

  Returns A wrapper iterator over one column in a tuple query or an invalid iterator if the result does not contain bindings for variableName.

- iterateBindings (offset)

  returns Soprano.NodeIterator

  Argument | Type | Default
  --- | --- | ---
  offset | int |

  Convenience method that creates an iterator over one column of bindings in this query result. This method does only make sense for tuple queries.

  offset - The index of the requested variable.

  The new iterator is just a wrapper around this one. Thus, changing it will also change this one.

  Returns A wrapper iterator over one column in a tuple query or an invalid iterator if offset is out of bounds, i.e. bigger or equal to bindingCount().

- iterateStatements ( )

  returns Soprano.StatementIterator

  Convenience method that creates an iterator over the statements in this query result. This method does only make sense for graph queries.

  The new iterator is just a wrapper around this one. Thus, changing it will also change this one.

  Returns A wrapper iterator over the statements in a graph query.