MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

The QtSparql library



QtSparql is a client-side library for accessing RDF stores. To use, add QtSparql to your project file:


The query language for RDF stores is SPARQL.

QtSparql takes in SPARQL queries, forwards them to the selected backend, and gives back the results of the query. It can return the results asynchronously if the backend supports asynchronous operations.

QtSparql can connect to different backends. Currently the following backends exist:

  • QTRACKER for accessing Tracker over D-Bus
  • QTRACKER_DIRECT for accessing Tracker via direct database access and D-Bus. See the specific usage section for more information
  • QSPARQL_ENDPOINT for accessing online RDF stores, e.g., DBpedia
  • QVIRTUOSO backend for accessing Virtuoso

List of classes QtSparql API provides:

Class Description
QSparqlConnection Interface for accessing an RDF store.
QSparqlConnectionOptions Encapsulates options given to QSparqlConnection. Some options are used only by some drivers.
QSparqlError SPARQL error information.
QSparqlBinding Handles a binding between a SPARQL query variable name and the value of the RDF node.
QSparqlQuery Means of executing and manipulating SPARQL statements.
QSparqlQueryOptions Encapsulates query execution options given to QSparqlConnection::exec(const QSparqlQuery&, const QSparqlQueryOptions&) Some options are used only by some drivers.
QSparqlQueryModel Read-only data model for SPARQL result sets.
QSparqlResultRow Encapsulates a row in the results of a query.
QSparqlResult Abstract interface for accessing the results of an executed QSparqlQuery.

The QtSparql API also provides two QML Bindings:

Binding Description
SparqlConnection Binding for QSparqlConnection. Allows queries to be run in QML
SparqlListModel Binding for QSparqlQueryModel. Allows for ListView models to be easily defined
The QtSparql library is not yet stable; we make no promises about API / ABI compatibility!

Getting started

The following code snippets demonstrate how to retrieve data from a RDF database using QtSparql.

E.g. to use tracker:

    QSparqlConnection connection("QTRACKER_DIRECT");

E.g. to use DBpedia:

    QSparqlConnectionOptions options;
    QSparqlConnection connection("QSPARQL_ENDPOINT", options);
  • Construct a QSparqlQuery with the SPARQL query string. Specify the query type, if needed.


    QSparqlQuery query("select ?u { ?u a nco:PersonContact . }");


    QSparqlQuery insert("insert { _:u a nco:Contact . "
                        "_:pn a nco:PhoneNumber ; "
                        "nco:phoneNumber 12345 . "
                        "_:u nco:hasPhoneNumber _:pn . }",


    QSparqlResult* result = connection.syncExec(query);


    QSparqlResult* result = conn.exec(query);
    MyObject obj;
    if (!result->hasError()) {
        QObject::connect(result, SIGNAL(finished()), &obj, SLOT(onFinished()));
        QObject::connect(result, SIGNAL(dataReady(int)),
                     &obj, SLOT(onDataReady(int)));


    while (result->next())
        qDebug() << result->value(0).toString();

The following classes are the most relevant for getting started with QSparql:

Query models

The QSparqlQueryModel class provides a convienient, read-only, data model for SPARQL results which can be used to provide data to view classes such as QTableView.

After creating the model, use QSparqlQueryModel::setQuery() to set the query for the connection, header data for the model can also be set using QSparqlQueryModel::setHeaderData().


    QSparqlQueryModel model;
    model.setQuery(QSparqlQuery("select ?u ?ng ?nf { ?u a nco:Contact; nco:nameGiven ?ng; nco:nameFamily ?nf . }"), *connection);
    model.setHeaderData(0, Qt::Horizontal, QObject::tr("ID"));
    model.setHeaderData(1, Qt::Horizontal, QObject::tr("First name"));
    model.setHeaderData(2, Qt::Horizontal, QObject::tr("Last name"));

You can then use this in an a view class by using it's setModel() function.


    QTableView *view = new QTableView;

It is also easy to implement custom query models by reimplementing QSparqlQueryModel::data(), see the querymodel example for an example of this.

Query models in QML

When using the QTRACKER_DIRECT and QSPARQL_ENDPOINT drivers, it is possible to use the models in QML applications. The property names will be selected from the query.


    query = "select ?u ?firstName ?secondName "
            "{ ?u a nco:PersonContact; "
            "nie:isLogicalPartOf <qml-example>; "
            "nco:nameGiven ?firstName; "
            "nco:nameFamily ?secondName .} order by ?secondName ?firstName";

The results will be accessible using the property names "u", "firstName" and "secondName". After creating a model, it can be set as a context property for a QML file.


    QSparqlQueryModel *model = new QSparqlQueryModel();
    // Now set the context property for the ListView model to the liveQuery model
    ctxt->setContextProperty("contactModel", model);

The query model can then be used in the same way, by calling QSparqlQueryModel::setQuery(). The example qmlquerymodel shows how to use the model with the QTRACKER_DIRECT driver so that it updates when new data is available.

Connection options supported by drivers

QTRACKER_DIRECT driver supports the following connection options:

  • dataReadyInterval (int, default 1), controls the interval for emitting the dataReady signal.
  • maxThread (int), sets the maximum number of threads for the thread pool to use. If not set a default of number of cores * 2 will be used.
  • threadExpiry (int, default 2000), controls the expiry time (in milliseconds) of the threads created by the thread pool.

QENDPOINT driver supports the following connection options:

  • hostName (QString)
  • path (QString)
  • port (int)
  • userName (QString)
  • password (QString)
  • networkAccessManager (QNetworkAccessManager*)
  • proxy (const QNetworkProxy&)
  • custom: "timeout" (int) (for virtuoso endpoints)
  • custom: "maxrows" (int) (for virtuoso endpoints)

QVIRTUOSO driver supports the following connection options:

For setting custom options, use QSparqlConnectionOptions::setOption() and give the option name as a string, followed by the value.

Other options can be set using QSparqlConnectionOptions::setOption(), however it is preferable to use the type-safe convinence functions in QSparqlConnectionOptions.

Connection features

The following table describes the QSparclConnection::Feature support of each driver. The features can be queried with QSparqlConnection::hasFeature().

QuerySize DefaultGraph AskQueries ConstructQueries UpdateQueries SyncExec AsyncExec
QTRACKER Yes Yes Yes No Yes No Yes
QTRACKER_DIRECT Yes Yes Yes No Yes Yes Yes
QVIRTUOSO Yes No Yes Yes Yes No (*) No

(*) The QVIRTUOSO driver is natively synchronous, but support for syncExec directly is not currently implemented.

QTRACKER_DIRECT specific usage

There are two ways to use the QTRACKER_DIRECT driver, synchronously using QSparqlConnection::syncExec(), and asynchronously using QSparqlConnection::exec(). The result behaviour is different, and supports different features, depending on the method used.

The following table describes the QSparqlResult::Feature support of each method.

QuerySize ForwardOnly Sync
exec() Yes No No
syncExec() No Yes Yes

When using synchronous execution, it is important to fully use the results returned before making another query, either synchronously or asynchronously, by using QSparqlResult::next until it returns false. If you fail to do this, any new results that may have been added after your original query will not be included in any subsequent queries you make.

The driver supports executing asynchronous queries as ForwardOnly synchronous results by setting QSparqlQueryOptions::setForwardOnly to true. This may be prefarable if you are using the asynchronous API to execute large queries quickly, since the results will not be retrieved before QSparqlResult::finished is emitted.

Accessing backend-specific functionalities

QtSparql doesn't offer backend-specific functionalities. For that purpose, there are separate add-on libraries, e.g., libqtsparql-tracker-extensions.

Copyright (C) 2010-2011 Nokia Corporation and/or its subsidiary(-ies).
Commercial Qt/LGPL 2.1 with Nokia exception/GPL 3.0
MeeGo 1.2 Harmattan API