SPARQL

Introduction

The Sparql page can be accessed through the main VocBench menu on the top blue stripe.

This page is based on tab panels, each of which corresponds to a type of editor:

query tab: contains an editor for "standard" SPARQL queries
parameterized query tab: contains an editor for parameterized SPARQL queries

SPARQL query editor

This editor is divided into three parts:

the upper part provides the text area for query editing
the central part contains the buttons for clearing/submitting the query, the option to include inferred statements in the result, an exporter for saving the results of the queries in different formats and buttons for storing/loading queries in a inner VocBench storage.
the bottom part reports the results of the query

Query Editing

The query editing section of the SPARQL Editor contains a text area for typing the query. A syntax completion helper (see figure below, where RDFS predicates are being suggested) is automatically activated at each section of the query where it might provide suggestions. Syntax checking and highlighting are also features of this editor.

The syntax completion helper and syntax checking/highlighting features have been made available by adapting the open source YASGUI SPARQL editor to the VocBench environment. Besides the inclusion in the environment of VocBench, the completion has been improved to provide not only language syntax completion, but also (to a limited extent) live suggestions from the data present in the managed project (e.g. available prefix/namespace mappings).

Regarding these live suggestions, it worth to mention the completion of the SPARQL endpoint associated with the SERVICE keyword. Candidate endpoints are found by matching (the tokens of) the completion source against the names of the open projects. Currently, only projects (whose main repo is) hosted on a remote Ontotext GraphDB triple store are available as potential candidates. Moreover, the address of the SPARQL endpoint is expressed using the repository scheme (rather than the http(s) scheme), exploiting the internal federation> machinery provided by this triple store, which increases speed, security and flexibility.

sparql query editor - completion of a federated SPARQL endpoint

If more tokens are needed, it is sufficient to start a literal term (instead of writing the single token as it were a keyword), which would be replaced by the IRI of the selected completion.

Results Area

The results area of the SPARQL Tab shows the results of the submitted query:

SELECT queries provide results in the form of TUPLE bindings, so they are shown as records in a table, with the headers representing the bound variables
DESCRIBE and CONSTRUCT queries are said to be GRAPH queries, in that the result of their processing is a RDF GRAPH. For this reason, a table with a static template (three headers representing the three elements of a RDF triple) is used to represent results content
ASK queries provide a boolean result, telling if the GRAPH PATTERN of the query successfully matched the ontology graph

Exporting results

The results obtained from a SPARQL query can be exported to an external file.

Currently the following formats are supported:

json
text (CSV and TSV)
spreadsheet (XLSX Microsoft format and ODS Open Document Spreadsheet format)
RDF (only for graph queries, such as DESCRIBE and CONSTRUCT )

In the case of RDF, it is possible to use the same RDF Transformation Processors that can be used for the export of the whole dataset.

Storing and Loading queries

VocBench is provided with an internal storage for configurations and settings, in this storage a SPARQL query can be stored and consequently loaded using the "floppy disc" buttons on the right under the SPARQL textarea.
The Store SPARQL query dialog prompts an ID (identifier of the query) and a scope (available: SYSTEM, PROJECT, USER, PROJECT_USER) which tells at which level the configuration will be stored. Additionally, the dialog shows the previously stored queries so it is possible to override an existing one.

The Load SPARQL query dialog simply lists the available stored queries that can be loaded into the editor. The stored queries can be also deleted from this dialog.

In the Load SPARQL query dialog it is also possible to filter the list of previously saved queries by using the search field in the lower part of the dialog. For example, by using the text "xlabels" only the queries having the word "xlabels" in their name are shown:

Parameterized SPARQL query editor

This editor is for the most the same as the previously described one; in addition it allows users to configure a set of variable bindings to be applied to the SPARQL query. It is possible to parameterize only stored queries, so in order to create a parameterized query, it is first necessary to create and store a "standard" query, then it can be parameterized by loading it into the Stored query textarea (through the "pencil" button). Each variable defined in the query can then be constrained to some classes of values, or grounded to a specific value. The result is a user-friendly form for a query where users can easily provide values for the variables in the query or leave them free in order to see their groundings in the result.

Parameterization

The right panel Variable bindings allows to create and edit parameterization for the current loaded query (through the "pencil" button). The Query parameterization dialog requires the following information:

Binding Variable: the query variable to parameterize.
Display Name: a user friendly name to show as alternative of the variable name (optional).
Description: a brief description of the variable, shown as tooltip near the input field of the variable binding (optional).
Binding Type: the type of parameterization. It can be:
- Assignment: the value of the variable is assigned statically in the parameterization.
- Constraint: role: the value of the variable is constrained to the specified role.
- Constraint: datatype: the value of the variable is a literal constrained to the specified datatype.
Value: the value of the parameterization. This depends on the previous Binding Type selected. If Assignment is a statically bound resource, plain literal or datatype literal; if Constraint: role, it is the role of the bound resource; finally, if Constraint: datatype it is the datatype of the bound resource.

Once the parameterization is defined, it is possible to bind values to the variables. Each input field in the Variable bindings panel guides the user to enter a value that is compliant with the constraints defined by the parameterization. For instance, in the example shown in the above figure, the type field suggests to enter a class, while the name suggests to enter a plain literal or an xsd:string literal.
Submitting the query with the variable bounds is equivalent to evaluate a query with the provided values in place of the variables. So, this represents a reusable and customizable way to evaluate structurally equal queries which may differ only from the values assigned to the variables. A parameterized query can be evaluated also ignoring the bindings simply unchecking the Use variable bindings flag.
The "eye" button on the panel heading switches the name of the input field between the Display name and the Binding variable defined during the parameterization.
Under the Variable bindings panel there is a textarea dedicated to the description of the parameterized query. The description is especially useful when using the parameterized query in the Custom Search.

Parameterized queries and Custom Search

Like the "standard" SPARQL queries, also the parameterized queries can be stored and loaded. Stored SPARQL SELECT queries which return a single variable can be used for the Custom Search, a search feature that exploits the power of the SPARQL language to perform customizable queries. For detailed information see the dedicated section.