SPARQL Property Functions

Property functions in SPARQL are properties that return results based on executing code rather than directly graph matching. Property functions, also referred to as "magic properties", differ from SPARQLMotion Functions in that multiple bindings can be returned. TopBraid Composer provides its own property functions to extend the functionality of SPARQL. The following sections describe property functions available in TopBraid Suite:

• tops functions: These are available for all TBS platforms and use the tops prefix, which stands for the namespace http://www.topbraid.org/tops#
• TopBraid Live functions: These functions are available for TopBraid Live only.

Note that in addition to these property functions, SPARQL also provides BIND/FILTER functions. TopBraid Composer supports all functions implemented by Jena, plus several additional ones. These are described in the SPARQLMotion Functions Reference.

If you want to add your own property functions, you can use SPIN's support for magic properties to declare new functions without programming. If you are a Java programmer, you can also add your new property functions using the Jena API and TopBraid extension points.

The following functions are available for all TBS platforms.

• tops:basket

  This property function returns all resources in any basket.

   

  • Syntax: ?resource tops:basket ()
  • Description: The function assigns all resources from any basket to ?resource variable.
  • Example: In the following query, tops:basket returns all the resources that have been dragged into the basket to the right of the SPARQL view.

   

  

 

• tops:constructRDFList

  (Experimental) This function binds variables for constructing an RDF list. It can be best used in a CONSTRUCT query. It is an experimental function, so it may work only in certain cases.

   

  • Syntax: (?list ?subList ?element ?rest) tops:constructRDFList (?s ?p ?o) .
  • Description: The function iterates through ?s ?p ?o to bind variables for constructing a list. Currently, only one variable in ?s ?p ?o should be unassigned, and the other two should be assigned. Also the property "rdf:type" should be used instead of "a". ?list variable is used as the head of the list and stays constant throughout the iteration, ?subList is used as the sub heads of the list and changes with each iteration, ?element is the unbound variable in ?s ?p ?o and changes with each iteration, and ?rest is the bound ?subList of the next iteration, which the current iteration points to.
  • Example: In the following query, tops:constructRDFList constructs an owl:oneOf list of colleges. Here is the query and its usage in kennedys ontology:

  CONSTRUCT { 
  	kennedys:College owl:oneOf ?list .
  	?subList rdf:first ?element .
  	?subList rdf:rest ?rest .
  }
  WHERE {
    	(?list ?subList ?element ?rest) tops:constructRDFList (?s rdf:type kennedys:College) .
  }
  

   

  

  Known limitations: Only one variable in ?s ?p ?o should be unassigned, and the other two should be assigned. The property "rdf:type" should be used instead of "a" in the function.

 

• tops:constructStringList

  This function binds variables for constructing a string list.

   

  • Syntax: ?x tops:constructStringList (?s ?p ?o ?useLabel ?doSort ?separator ?wrapper)
  • Description: The function iterates through ?s ?p ?o to construct a string from the binding of the unassigned variable. ?useLabel is an optional boolean variable, which uses the rdfs:label value of the unassigned variable, if it is a resource. ?doSort is an optional boolean variable for sorting the list. ?separator is an optional string used as a separator between members of the list.?wrapper is an optional string which occurs at the beginning and end of each member of the list.
  • Example: In the following query, tops:constructStringList constructs a string list of colleges. The resulting list consists of the labels of the colleges, sorted, separated by a comma and whitespace and wrapped by quotes. Here is the query and its usage in kennedys ontology:

  SELECT ?x
  WHERE {
  	?x tops:constructStringList (?s rdf:type kennedys:College true true ", " "\"")
  }
  

   

  

  Known limitations: Only one variable in ?s ?p ?o should be unassigned, and the other two should be assigned. The property "rdf:type" should be used instead of "a" in the function.

 

• tops:definesStatements

   

  • Syntax: ?baseURI tops:definesStatements (?subject ?predicate ?object)
  • Description: Returns the statements at the variables ?subject ?predicate ?object defined in the ontology having a base URI, which is represented by the optional, bound or unbound variable ?baseURI.

    If ?baseURI is bound, then the statements in the corresponding ontology are returned.

    If ?baseURI is an unbound variable, then the base URI of the currently selected ontology is returned at ?baseURI as well as the statements in the corresponding ontology. (In SPARQLMotion, this case might behave differently)

    If ?baseURI is not given, i.e. blank subject, then the statements in the current graph are returned.

   

  • Example 1: If ?baseURI variable is bound as a uri node:

     
    SELECT ?subject ?predicate ?object 
    WHERE { 
    	<http://topbraid.org/sparqlmotion> tops:definesStatements (?subject ?predicate ?object) 
    }
    		

    The above query returns all statements defined in the ontology with the base URI http://topbraid.org/sparqlmotion.

   

  • Example 2: If ?baseURI is a variable:

     
    SELECT ?baseURI ?subject ?predicate ?object
    WHERE { 
    	?baseURI tops:definesStatements (?subject ?predicate ?object) 
    }
    		

    The above query returns all statements defined in the currently selected ontology. The base URI of the ontology is also returned.

   

  • Example 3: If ?baseURI is not given:

     
    SELECT ?subject ?predicate ?object
    WHERE { 
    	() tops:definesStatements (?subject ?predicate ?object) 
    } 
    		

    The above query returns all statements defined in the current graph.

 

• tops:dependsOn

  This function returns statements depending on the input resource. The dependency in this context means that the returned statements can only exist with the input resource. The input resource can be a URI resource or blank node.

   

  • Syntax: (?s ?p ?o) tops:dependsOn ?x
  • Description: The function generates ?s ?p ?o, which depends on the URI resource or blank node ?x.
  • Example: In the following query, tops:dependsOn constructs the statements that depend on kennedys:photo. The results mostly contain the statements using kennedys:photo as a property. However, there is also rdfs:domain on this property, which has a owl:unionOf list. In addition to the head of the list, all statements inside it also depend on kennedys:photo.

  SELECT *
  WHERE {
      (?s ?p ?o) tops:dependsOn kennedys:photo .
  }
  

   

  

  Known limitation: This function should be used with more care in SPARQLMotion, as the SPARQLMotion script may not have included obvious default inferences like ?c rdfs:subClassOf owl:Thing, if ?c is not a subclass of any class. The user may need to add more SPARQLMotion modules to handle such corner cases before running this function.

 

• tops:files

  This function can be used to traverse the files in the workspace. A typical use case of this is in conjunction with SPARQLMotion scripts to do batch processing of multiple files, where the exact names of the files are unknown.

   

  • Syntax: ?path tops:files ( rootPath [true|false] [true|false])
  • Description: The function binds ?path to all file paths found in the root path. The root path should start with "/" which represents the Eclipse workspace root. The second argument can be a boolean, where true indicates recursive traversal. This means that simply calling it with ("/" true) will traverse all files in the whole workspace. The first segment after the root "/" must be a project name, then folders. If the third argument is true, then the function will exclude any files from the TopBraid system projects.
  • Example 1: In the following query, the variable path will be bound to the values "/TBC/Examples/countries.ttl", etc.
    

    ?path tops:files ("/TBC/Examples" false)

  • Example 2: In the following query, the variable path will be bound to the values under "/MyProject/MyFolder" or all its sub-folders.
    

    ?path tops:files ("/MyProject/MyFolder" true)

 

• tops:for

  This property can be used to implement loops over a range of integer values.

   

  • Syntax: ?index tops:for ( [startIndex] [endIndex] )
  • Description: The function iterates over all xsd:integer values >= startIndex and <= endIndex and assigns all those values to the variable on the left side
  • Example: In the following query, the variable index will be bound to the xsd:integer values 2, 3, and 4.
    

    ?index tops:for (2 4)

 

• tops:foreach

  This function binds the input arguments on the right to the variables on the left.

   

  • Syntax: ?x tops:foreach (?arg1 ?arg2 ?arg3...)
  • Description: The function binds an iteration of ?x variable bound from the input arguments.
  • Example: In the following query, tops:foreach returns kennedys:College, kennedys:Gender, kennedys:Person and kennedys:Profession in the result set.

  SELECT *
  WHERE {
      ?x tops:foreach (kennedys:Gender kennedys:College kennedys:Person kennedys:Profession)
  }
  

 

• tops:localRanges

  Iterates through all defined ranges for a given class/property pair, including handling of owl:unionOf ranges.

   

  • Syntax: (?cls ?property) tops:localRanges ?range
  • Description: ?cls and ?property must be bound and ?range must be unbound. Will bind ?range to all range resources, either using owl:allValuesFrom restrictions or global rdfs:ranges

 

• tops:relevantPropertiesOfClass

  Gets a list of all properties that are "relevant" for a given class. This includes all properties with matching domains and the restricted properties.

   

  • Syntax: ?property tops:relevantPropertiesOfClass ?class

 

• tops:relevantPropertiesOfInstance

  Gets a list of all properties that are "relevant" for a given subject resource. This includes all properties that already have a value for the subject plus those with matching domains and the restricted properties.

   

  • Syntax: ?property tops:relevantPropertiesOfInstance ?resource

 

• tops:restrictedProperties

  Gets a list of all properties that are mentioned in some restriction relevant to a given class.

   

  • Syntax: ?property tops:restrictedProperties ?cls

 

• tops:split

  This function can be used to split a string into multiple sub-strings separated by a given regular expression.

   

  • Syntax: ?s tops:split ( string regex )
  • Description: The function binds ?s to all sub-strings of string, where the regex defines the separator between each sub-string. Empty sub-strings will be ignored.
  • Example: In the following query, the variable s will be bound to the values "AAA", "BB" and "C"
    

    ?s tops:split ("AAA BB   C  " " ")

 

• tops:statementDefinedIn

   

  • Syntax: (?subject ?predicate ?object) tops:statementDefinedIn ?baseURI
  • Description: Returns the defining ontology base URI for a given statement. The statement should exist in or be imported into the current graph.
  • Example: If ?baseURI variable is bound as a literal or a uri node:

     
    SELECT ?baseURI
    WHERE { 
    	(geotravel:Accommodation rdf:type owl:Class) tops:statementDefinedIn ?baseURI 
    } 
    		

    The above query returns the base URI of geotravel ontology.

 

• tops:transitiveAssociation

  Gets subjects that are connected to an object via a transitive property. For instance, find all resources that are directly or indirectly rdfs:subClassOf a given class. Both the subject and object must be bound when the function is called. This function has the advantage of having the transitive property as a variable, when compared to property paths.

   

  • Syntax: ?subject tops:transitiveAssociation (?property ?object)
  • Example: Example to get all classes that are subClassOf owl:Thing (including owl:Thing):

  SELECT *
  WHERE {
     ?cls tops:transitiveAssociation (rdfs:subClassOf owl:Thing) .
  }
  

The following functions are available for TopBraid Live only.

• <http://topbraidlive.org/functions#sessions>

  Gets data on current TopBraid Live sessions.

   

  • Syntax: () <http://topbraidlive.org/functions#sessions> ( ?userName ?baseURI ?startTime ?recentTime )
  • Description: Will bind the variables on the right hand side. All variables are optional.
  • Example: Example to get user name, currently open base URI, session start time, and most recent activity for all active TBL sessions:

  SELECT *
  WHERE {
     ()  <http://topbraidlive.org/functions#sessions> ( ?userName ?baseURI ?startTime ?recentTime )
  }