Example Multi-Function for SPARQL
This example declares a multi-function ex:namedSuperClasses that returns all superclasses of a given class
excluding blank nodes and owl:Thing and rdfs:Resource.
Here is how the definition of that function looks like in TopBraid EDG:
The main part of the definition is the SPARQL SELECT query.
Like SPARQL queries in other SHACL-based vocabularies, the SELECT query may access input parameters as
pre-bound variables, typically represented with $ variables.
In this example, the variable $subClass already has a value when the query is executing,
and this value must be provided as input argument.
Using such input arguments, the query can return result variables ?superClass and ?label.
Definition in RDF/Turtle
The complete definition in Turtle includes the details of the parameters and result variables:
ex:namedSuperClasses
a dash:SPARQLMultiFunction ;
rdfs:label "named super classes" ;
rdfs:comment "Gets all (transitive) superclasses of a given class." ;
dash:apiStatus dash:Stable ;
sh:parameter ex:namedSuperClasses-subClass ;
dash:resultVariable ex:namedSuperClasses-label ;
dash:resultVariable ex:namedSuperClasses-superClass ;
sh:prefixes <http://datashapes.org/dash> ;
sh:select """
SELECT ?superClass ?label
WHERE {
$subClass rdfs:subClassOf+ ?superClass .
?superClass rdfs:label ?label .
FILTER isIRI(?superClass) .
FILTER (?superClass != $subClass) .
FILTER (?superClass NOT IN ( owl:Thing, rdfs:Resource ) )
}""" ;
.
ex:namedSuperClasses-subClass
a sh:Parameter ;
sh:name "sub class" ;
sh:description "The class to get the superclasses of." ;
sh:path ex:subClass ;
sh:class rdfs:Class ;
sh:order 0 ; # Optional, there is only one parameter
.
ex:namedSuperClasses-superClass
a sh:Parameter ;
sh:path ex:superClass ;
sh:class rdfs:Class ;
sh:description "The superclass resource." ;
sh:name "super class" ;
sh:order 0 ;
.
ex:namedSuperClasses-label
a sh:Parameter ;
sh:name "label" ;
sh:description "The label of the superclass." ;
sh:path ex:label ;
sh:datatype xsd:string ;
sh:order 1 ;
.Example Use from SPARQL
Using this declaration, a SPARQL engine like Apache Jena in TopBraid can expose a new query feature as a property function which could be used as follows:
SELECT *
WHERE {
schema:DayOfWeek ex:namedSuperClasses ( ?superClass ?label ) .
}Which would return variable bindings as follows:
| ?superClass | ?label |
schema:Thing |
"Thing" |
schema:Intangible |
"Intangible" |
schema:Enumeration |
"Enumeration" |
Note that such multi-functions can not only return multiple result rows but also multiple variables (or columns)
per row.
In the SPARQL syntax above, the values to the left of the "magic" property ex:namedSuperClasses are the
input arguments (declared as parameters using SHACL) and the variables on the right will receive the value
bindings that are produced by the SELECT query defined by the multi-function.
In the example above, the SPARQL property function uses the same variable names ?superClass and ?label,
however it could also use any other "fresh" variable that is not yet bound to other values, e.g.
SELECT *
WHERE {
schema:DayOfWeek ex:namedSuperClasses ( ?class ?classLabel ) .
}
Note that in order for such SPARQL property functions to be recognized and installed by TopBraid, the multi-function
should be declared in files containing .api. in their name.
Alternatively they may be stored in graphs that are part of the ui:graph (imported by any .ui.ttlx file),
or imported from any .spin.ttl file.
Example Use from JavaScript/ADS
TopBraid's Active Data Shapes (ADS) framework makes it possible to query
and manipulate RDF graphs through JavaScript or TypeScript.
Assuming the instances of dash:SPARQLMultiFunction are defined in an Ontology asset collection
or in a file that is imported by the Ontology, the ADS code generator will produce JavaScript functions
such as follows:
let superClasses = ex.namedSuperClasses(schema.DayOfWeek);
// Result will be an array of objects with fields { superClass, label }
console.log(`DayOfWeek has ${superClasses.length} superclasses:`);
superClasses.forEach(result => {
console.log(`- ${result.label}: ${result.superClass}`);
});