SPARQLMotion Getting Started Guide
Getting Started with an Example
This example SPARQLMotion script (download) performs the following steps:
-
Import a newsfeed from a specified URL. The result of this step is an RDF graph.
-
Create a spreadsheet by running a SPARQL SELECT query on the news feed’s RDF graph. The resulting spreadsheet will be assigned to a variable “text”.
-
Save the spreadsheet to a text file. The contents of the file is the value of the variable “text”.
We call each of these steps modules. Modules can pass RDF data and variable values among each others. Most SPARQLMotion modules have properties that configure their behavior. The following images show the configuration forms for each of the steps in the example script.
Modules of type Import news feed must be supplied with a url that points to the location of the news feed to load. In the example above, this is the Atom news feed of the Composing the Semantic Web blog.
Modules of type Create spreadsheet are configured with a SPARQL select query. The result variables of the SELECT query define the columns of the resulting spreadsheet. The WHERE clause defines the content of each row. In the example, the columns are “date” and “title”, and there will be one row for each rss:item in the newsfeed containing its date (atom:updated) and title (rdfs:label). The module also specifies the name of the outputVariable. The variable name text is the default value and will be automatically assigned when a module of this type is being created.
The final step, Export to text file has three configuration properties. The property targetFilePath must point to the path of the file that will be written into. Replace indicates whether the file shall be overwritten or whether the system shall append the text to the end of the file (if it exists). Finally, the property text must contain the actual text that shall be written into the file. The module on the right does not define a value for it at edit-time. Instead, the value of the variable text from above will be used at run-time.
Modules and the next relationship
SPARQLMotion scripts consist of one or more linked modules. Modules have one of the module types from the SPARQLMotion module library as their type. These module types (which are themselves RDF/OWL classes) tell the editing environment how to display the modules to the user. The SPARQLMotion execution engine knows how to interpret each of the modules at run-time.
There are various types of links between modules, but the most important link type is next.
- In this example, two modules are linked via the next relationship. This means:
- The module Import RDF from URL is executed before Export to RDF File
- RDF data and any variable bindings are passed from the first to the second module
Each module in SPARQLMotion can take RDF data as input and produces RDF data. Some modules may process the input RDF somehow and pass different RDF data to its successors. For example, modules may add additional RDF data or they may filter some RDF triples out of the processing pipeline. Other modules may forward the input RDF data to the next module unchanged, and only have other side effects such as creating a file or binding a variable
If a module has two or more predecessors via incoming next relationships, then its input is the union RDF graph of all input modules. In the example on the left, Export to RDF File would create a file that contains all triples from both the Import RDF from URL and Import news feed.
If a module is linked to two successors via next, then each of the successors will receive exactly the same RDF data as input. In the example, the RDF data of the news feed is both saved to an RDF file and displayed on a map. The order in which the successors are executed is undefined, and they could even be executed in parallel, depending on the execution engine’s implementation.
Variable Bindings
In addition to RDF data, modules can pass variable values among from each. The following variable types are currently supported:
There are various types of links between modules, but the most important link type is next.
- Literals. A literal is a primitive value in one of the RDF datatypes including xsd:int, xsd:float, xsd:string and xsd:boolean. Example: 42 (xsd:int).
- Resources. Variables may point to an RDF resource via a URI. Example: http://my.com/model#Person.
- XML. An XML document object model. Example: .
When a variable gets a value assigned to it, we call it a bound variable, and the variable-value pair is called the variable binding.
In this example the Create text module binds the variable text with some value (e.g. “This is a text”). The Export to text file module takes a property called text as input and writes it into a text file. Since the name of the variable is the same as the local name of the text property, the value is passed from the first to the second module, i.e. the created text string will be written to the file.
Any other module below the Create text module may also access the same value, unless some other module has “overwritten” the variable value in the meantime.
There are many different ways in which variables may be bound. Many modules such as Create spreadsheet explicitly define a single outputVariable while others may even bind multiple variables at once. For example, Bind by select runs a SPARQL select query, and all variables mentioned in the SELECT clause will be bound for its successors, as illustrated in the example below in which the variables label and subClassOf will be bound downstream from the Bind by select module.
Once a variable has been bound it can be used in various ways. As already shown in the Export to text file example above, if a module does not have a value for one of its configuration properties, then the system will use incoming variables that have the same name as the property’s local name. However, there are two other ways of accessing variable values: in string property templates and in SPARQL queries. Let’s look at string properties first.
The script above binds two string variables firstName and lastName and then uses them in a template “Hello, {?firstName} {?lastName}”. The resulting output bindings are shown in the console below. The values of the variables will be inserted into the template. Note that this templating mechanism works for all string properties in any module. For example, you can dynamically create a filePath value to dynamically create files.
If a module contains a SPARQL query in its definition, then the WHERE clause of the query may use any bound variable.
In the example above, the variable callingCode is bound with external input (of type xsd:integer) and then passed into the Get country from DBPedia module that uses it as ?callingCode in its WHERE clause. When executed on the input 61, this would return the following values.
Iterating and Branching
We have already introduced the next relationships that links multiple modules into a sequential execution order. In addition to next, there are other types of relationships between modules. Iterations (repeated loops) can be expressed as well as branches (if-then-else statements). Let’s look at iterations first.
The script above contains an Iterate over select module that repeats a body script for each result of a given SPARQL selectQuery. In this particular case, it iterates over all instances of the Calais country class and gets the label of each country. The label is bound as countryLabel variable in the body of the iteration. The body module (which may also be a complex script on its own) can process the countryLabel in any conceivable way.
The execution engine will collect all RDF graphs from the end modules of each iteration and merge them together into a single union graph. This resulting union graph is then passed into the next modules after the iteration module, in this case the Display countries on map module.
In some cases the code may need to fork into one of two branches, depending on some condition. The following example uses the Branch by ask module.
The above script does the following:
-
Bind the variable country with external (user) input
-
Run a SPARQL ASK query against a SPARQL endpoint using the variable country as one of the variables in the query
-
If the query returns true, then execute the if branch, otherwise execute the else branch.
-
Pass the result of the selected branch and all bound variables to the resulting Return RDF node. For example, if the ASK condition branches into the if case, then the variable dummy will be bound in the resulting module.