SparqlConnection

Provides a QML binding for QSparqlConnection. The connection can be used to issue SPARQL queries directly from javascript, or as a connection for the ListView model SparqlListModel

    import QtSparql 1.0

Properties

• driver : string
• status : enumeration
• options : SparqlConnectionOptions
• result : variant

Methods

• variant select
• bool ask
• variant update
• variant construct
• string errorString

Property Documentation

The only required property to set is driver.

driver : string

Set the driver to use for the connection, E.g. to use the tracker direct driver :

    SparqlConnection {
        id: connection
        driver: "QTRACKER_DIRECT"
    }

status : enumeration read-only

Specifies the connection status, which can be one of the following:

• Null - Connection has not been established
• Ready - Connection is ready
• Loading - Connection opening is established and waiting for completion
• Error - There was an error in the connection opening, or an error with a query

The status can be monitored using the statusChanged() signal. E.g :

    SparqlConnection {
        id: connectionalternatively
        driver: "QTRACKER_DIRECT"
        onStatusChanged: checkStatus(status)
    }

    function checkStatus(status)
    {
        if (status == SparqlConnection.Error)
            console.log("Error = "+connection.errorString());
    }

options : SparqlConnectionOptions

If connection options need to be set, the SparqlConnectionOptions binding can be used, E.g :

    SparqlConnection {
        driver: "QSPARQL_ENDPOINT"
        options: SparqlConnectionOptions {
                    hostName: "localhost"
                    port: 1234
                 }

For a full list of options, see QSparqlConnectionOptions.

result : variant read-only

Stores the current result after executing a query with select(). This is a convenience property to allow for a common function to be used for both synchronous and asynchronous queries. When a new result is ready, a resultReady() signal will be emitted. E.g :

    SparqlConnection {
        id: connection
        driver: "QTRACKER_DIRECT"
        onResultReady: resultFunction(result)
    }

    function resultFunction(result)
    {
        \\ do something with result
    }

See the section Using Results for more information.

Method Documentation

variant select (string query, bool async = false)

Runs a QSparqlQuery::SelectStatement, synchronous by default.

The function will return a list of results, see the section Using Results for result usage.

If the async parameter is set to true, the query will be executed asynchronously, and the function will return 0. For asynchronous usage, see the section Asynchronous Queries.

variant select (string query, QVariantMap boundValues, bool async = false)

Overloaded method to allow for the replacing of placeholders in query with their corresponding values contained in the hashmap boundValues. See Binding Values.

bool ask (string query, bool async = false)

Runs a QSparqlQuery::AskStatement, synchronous by default, returning the bool value of the query.

bool ask (string query, QVariantMap boundValues, bool async = false)

Overloaded method to allow for the replacing of placeholders in query with their corresponding values contained in the hashmap boundValues. See Binding Values.

variant update (string query, bool async = false)

Runs a QSparqlQuery::InsertStatement or QSparqlQuery::DeleteStatement. If there was an error with the update query, -1 will be returned, otherwise an empty list will be returned.

variant update (string query, QVariantMap boundValues, bool async = false)

Overloaded method to allow for the replacing of placeholders in query with their corresponding values contained in the hashmap boundValues. See Binding Values.

variant construct (string query, bool async = false)

Runs a QSparqlQuery::ConstructStatement returning the results, or -1 if there was an error.

variant construct (string query, QVariantMap boundValues, bool async = false)

Overloaded method to allow for the replacing of placeholders in query with their corresponding values contained in the hashmap boundValues. See Binding Values.

string errorString ()

Returns a string description of the last error that occurred if status is SparqlConnection::Error

Detailed Description

Basic Usage

The SparqlConnection binding can be used to issue SPARQL queries, and as a connection for the ListView model SparqlListModel. To create a new connection :

    SparqlConnection {
        id: connection
        driver: "QTRACKER_DIRECT"
    }

The connection can then be used in javascript functions using the id "connection".

Using Results

Property names for results will be extracted from the query string that is used. For example, results for the query :

    select ?u ?ng ?nf { ?u a nco:PersonContact; nco:nameGiven ?ng; nco:nameFamily ?nf }

Will have property names "u", "ng" and "nf". It is important to note that when using a function in the query, the property name must be defined using the AS keyword. E.g :

    select ?u fn:string( (?nf, ?ng), ' ') AS ?joinedName { ... }

Will return "u" and "joinedNamed" as the property names.

When using select() results will be returned as a list of "result rows" :

    var result = connection.select(query)

It is easy to iterate through the results using its length property :

    for (var i=0; i<result.length; i++) {
        var resultRow = result[i];
        var nameGiven = resultRow["ng"]
        // Alternatively the property name could be used
        var nameGivenProperty = resultRow.ng;
    }

Alternatively, you can access result properties by looping through the property values, E.g :

    for (var i=0; i<result.length; i++) {
        var resultRow = result[i];
        for (var property in resultRow) {
            console.log("property name = "+property)
            console.log("property value = "+resultRow[property])
        }
    }

Asynchronous Queries

Queries may also be executed asynchronously, and processed once they have been completed. This is convenient if you intend to issue large queries with the connection, as any call to select() or update() will not block. This is done by setting the async paramater to true for both select() and update().

To issue a select query asynchronoulsy :

    connection.select(query, true);

The result can be processed after the connections resultReady() signal has been emitted, E.g :

    SparqlConnection {
        ...
        onResultReady: resultFunction(result)
    }

    function resultFunction(result)
    {
        // check for an error
        if (connection.status != SparqlConnection.Error) {
            //process the results
        }
    }

It is also possible to connect to the resultReady() signal directly in javascript, E.g :

    function asyncSelect() {
        sparqlConnection.resultReady.connect(someFunction)
        sparqlConnection.select(query, true)
    }

Please note: Synchronous calls to select() will also emit the resultReady signal, so if you intend to use both asynchronous and synchronous queries you can process both using the onResultReady: property.

Binding Values

The bindings support the QSparqlQuery feature of allowing query placeholders (marked with ?: or $:) to be replaced with strings. This approach is preferable for update queries as it provides protection against SPARQL injection.

When using placeholders, a hash map containing the placeholder to value pairs must be included with any query execution, E.g :

    var query = "insert { <newContact> a nco:PersonContact; nco:nameGiven ?:boundValue1; nco:nameFamily ?:boundValue2 . }"
    var boundValues = { "boundValue1":"Joe", "boundValue2":"Chip" }
    var result = sparqlConnection.update(query, boundValues);