The QtSparql library

0.0.30

unstable

Introduction

Description

QtSparql is a client-side library for accessing RDF stores.

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:

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.

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.

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

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

E.g.

    QSparqlResult* result = connection.syncExec(query);

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

E.g.

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

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 fn:string-join((?firstName, ?secondName), ' ') AS ?joinedName"
            "{ ?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" and "joinedName". Please note that whenever using functions (in this case string-join) it is important to define the property name you want to use in QML using AS.

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
    // access the values in qml using urn and subject
    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:

QENDPOINT driver supports the following connection options:

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 convinence functions in QSparqlConnectionOptions, as these provide additional error checking.

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.

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.

 All Classes Namespaces Functions Enumerations Enumerator