The QtSparql library

Introduction

Description

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

    CONFIG+=qtsparql

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

Attention:

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.

• Create a QSparqlConnection object specifiying the backend you want to use. If necessary, specify the parameters by using QSparqlConnectionOptions and passing it to QSparqlConnection.

E.g. to use tracker:

    QSparqlConnection connection("QTRACKER_DIRECT");

E.g. to use DBpedia:

    QSparqlConnectionOptions options;
    options.setHostName("dbpedia.org");
    QSparqlConnection connection("QSPARQL_ENDPOINT", options);

• Construct a QSparqlQuery with the SPARQL query string. Specify the query type, if needed.

E.g.

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

or

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

• Use QSparqlConnection::syncExec() to execute the query synchronously. It returns a pointer to QSparqlResult.

E.g.

    QSparqlResult* result = connection.syncExec(query);

• Alternatively you can call QSparqlConnection::exec() to exectute the query asynchronously. You can then connect to the QSparqlResult::finished() and QSparqlResult::dataReady() signals. Please note, it is always important to check if the result has an error (using QSparqlResult::hasError()) before connecting the signals.

E.g.

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

• The QSparqlResult can be iterated over by using the following functions: QSparqlResult::first(), QSparqlResult::last(), QSparqlResult::next(), QSparqlResult::previous(), QSparqlResult::setPos(). The caller is responsible for deleting the QSparqlResult.

E.g.

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

• Data can be retrieved by using QSparqlResult::value().

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

• QSparqlConnection
• QSparqlQuery
• QSparqlResult
• QSparqlQueryModel

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

E.g.

    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.

E.g.

    QTableView *view = new QTableView;
    view->setModel(model);

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.

E.g.

    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.

E.g.

    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:

• hostName (QString)
• port (int)
• userName (QString)
• password (QString)
• databaseName (QString)

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
QSPARQL_ENDPOINT	Yes	Yes	Yes	Yes	Yes	No	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.