SPARQL request creation

The SPARQLRequest class allows to create SPARQL requests easily without having to write the request "by hand".

After having created the request, you can call the SPARQLRequest.toString() method to generate the SPARQL request as a String.

Constructor

The SPARQLRequest(String prefix) constructor creates a SPARQL request for a specified default prefix. Note that if there are default prefix declarations, these prefixes will be used in the request.

Managing the prefix declarations

By default the request will defer to the default prefix declarations to define if prefix declarations are used.

However, several methods allow to explictly add prefix declarations to the result. For example:

• The SPARQLRequest(String prefix, SparqlPrefixDeclarations decl) will use the specified prefix declarations to handle the prefix

Global parameters of the request

• The SPARQLRequest.selectDistinct(boolean selectDistinct) method specifies if the SELECT part of the request must be DISTINCT
• The SPARQLRequest.setLimit(int limit) method specifies the value for the LIMIT filter
• The SPARQLRequest.setOrderBy(String orderBy, boolean isAscending) method specifies the Variable to use for the ORDER BY. The isAscending argument allows to specify if the ordering is ascending or descending
• The SPARQLRequest.setOrderBy(Expression orderBy, boolean isAscending) method does the same with an Expression rather than just a Variable.

SELECT content

• The SPARQLRequest.addSelect(String var) method adds a variable to use in the SELECT part of the request. Return true if the variable could be added (which means it was not already defined in the WHERE part of the request)
• The SPARQLRequest.addSelect(String... variables) method adds a list of variables to use in the SELECT part of the request
• The SPARQLRequest.setSelect(String... variables) method sets the list of variables to use in the SELECT part of the request
• The SPARQLRequest.addSelect(Expression expr, String asVar) method adds an expression to use in the SELECT part of the request. Return true if the variable could be added (which means it was not already defined in the WHERE part of the request)
• The SPARQLRequest.setSelectAll() method sets the "SELECT *" construct
• The SPARQLRequest.hasSelectVariable(String var) method returns true if a variable is alsready part of the SELECT

Selects with all

The syntax SELECT * is an abbreviation that selects all of the variables that are in-scope at that point in the query.

The following example uses a "SELECT *":

   SparqlRequest request = new SparqlRequest("sitac");
   request.setSelectAll();
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true);   

Will return the following SPARQL content:

   SELECT *
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:isTasked "true" .
   }

Selects with variables

The following example uses a SELECT with a variable:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true);   

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:isTasked "true" .
   }

Selects with expression

The following example uses a SELECT with an expression:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
      
   VariableExpression varExpr = new VariableExpression("altitude");
   FunctionExpression function = new FunctionExpression(FunctionExpression.FUNCTION_FLOOR, varExpr);
   request.addSelect(function, "alt");
   request.addType("zone", "Zone");
   request.addPropertyRef("zone", "hasAltitude", "altitude");  

Will return the following SPARQL content:

   SELECT ?zone (floor(?altitude) AS ?alt)
   WHERE {
     ?zone rdf:type sitac:Zone .
     ?zone sitac:hasAltitude ?altitude .
   }

FILTER and BIND content

• The SPARQLRequest.addFilter() method adds a FILTER
• The SPARQLRequest.addBIND() method adds a BIND for a variable

Filters

It is possible to add a FILTER construct with the SPARQLRequest.addFilter() method. The returned Filter instance allows to add as many Expression elements as you want.

For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addAdditionalVariable("index");
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true);
   request.addPropertyRef("zone", "hasIndex", "index");
      
   Filter filter = request.addFilter();
   VariableExpression varExpr = filter.createVariable("index");
   LiteralExpression literal = filter.createLiteral(5);
   ComparisonExpression comp = new ComparisonExpression(varExpr, ComparisonExpression.LESS, literal);
   filter.addExpression(comp);      

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:isTasked "true" .
      ?zone sitac:hasIndex ?index .
      FILTER (?index < 5)
   }

Binds

It is possible to add a BIND construct with the SPARQLRequest.addBIND(String var) method. The returned Bind instance allows to add as many Expression elements.

For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addAdditionalVariable("index");
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true);
   request.addPropertyRef("zone", "hasIndex", "index");
      
   Bind bind = request.addBind("var");
   VariableExpression varExpr = bind.createVariable("index");
   LiteralExpression literal = bind.createLiteral(2);
   ArithmeticExpression ar = new ArithmeticExpression(varExpr, ArithmeticExpression.MULTIPLY, literal);
   bind.addExpression(ar);      

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:isTasked "true" .
      ?zone sitac:hasIndex ?index .
      BIND (?index * 2 as ?var)
   }

WHERE content

Additional variables

• The ISparqlRequestGroup.addAdditionalVariable(String var) method adds an additional variable which will be used in the WHERE part of the request. Return true if the variable could be added (which means it was not already defined in the SELECT part of the request)
• The ISparqlRequestGroup.addAutoVariable() method adds a variable with an unused automatically specified name, to be used in the WHERE part of the request. Return the variable name

Adding a rdf contruct

• The ISparqlRequestGroup.addType(String var, String type) method adds a rdf:type property for a variable in the WHERE part of the request. Return true if the variable has been defined
• The ISparqlRequestGroup.addSubClassOf(String var, String type) method adds a rdf:subClassOf for a variable in the WHERE part of the request. Return true if the variable has been defined
• The ISparqlRequestGroup.addSubClassOfStar(String var, String type) method adds a rdf:subClassOf* for a variable in the WHERE part of the request. Return true if the variable has been defined

Specifying the type of a variable

The ISparqlRequestGroup.addType(String var, String type) method allows to specify a rdf:type for a variable. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addType("zone", "TaskZone");

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
   }

Specifying the subclass of a variable

The ISparqlRequestGroup.addSubClassOf(String var, String type) method allows to specify a rdf:subClassOf for a variable. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addSubClassOf("zone", "TaskZone");

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:subClassOf sitac:TaskZone .
   }

The ISparqlRequestGroup.addSubClassOfStar(String var, String type) method allows to specify a rdf:subClassOf* for a variable^[1]

See SPARQL 1.1 Query Language

. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addSubClassOfStar("zone", "TaskZone");

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:subClassOf* sitac:TaskZone .
   }

Adding a property

• The ISparqlRequestGroup.addPropertyValue(String var, String propertyName, Object propertyValue) method adds a property value specification for a variable property in the WHERE part of the request. Return true if the variable has been defined
• The ISparqlRequestGroup.addPropertyValue(String var, String propertyName, Object propertyValue, boolean optional) method adds a property value specification for a variable property in the WHERE part of the request. Return true if the variable has been defined. The optional parameter allows to define this property value as optional in the request
• The ISparqlRequestGroup.addPropertyValues(String var, List propertyValues) method adds a property value declaration in the WHERE part of the request, for several values
• The ISparqlRequestGroup.addPropertyRef(String var, String propertyName, String varRef) method adds a reference to another variable for a variable property in the WHERE part of the request. Return true if both variables have been defined
• The ISparqlRequestGroup.addPropertyRef(String var, String propertyName, String varRef, boolean optional) method adds a reference to another variable for a variable property in the WHERE part of the request. Return true if both variables have been defined. The optional parameter allows to define this property value as optional in the request
• The ISparqlRequestGroup.addPropertyIndividualRef(String var, String propertyName, String individual) method adds a reference to an individual for a variable property in the WHERE part of the request. Return true if the variable has been defined

Specifying a triple between two variables and a property

The ISparqlRequestGroup.addPropertyRef(String var, String propertyName, String varRef) method allows to specify a triple pattern between two variables and a property. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addAdditionalVariable("index");
   request.addPropertyRef("zone", "hasIndex", "index");  

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone sitac:hasIndex ?index .
   }

Specifying a triple between a variable, a value, and a property

The ISparqlRequestGroup.addPropertyValue(String var, String propertyName, Object propertyValue) method allows to specify a triple pattern between a variable, a value, and a property. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addPropertyValue("zone", "isTasked", true);  

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone sitac:isTasked "true" .
   }

Specifying a triple between a variable, a list of values, and a property

The ISparqlRequestGroup.addPropertyValues(String var, List valuesList) method allows to specify a triple pattern between a variable, a list of values, and a property. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addType("zone", "TaskZone");
   request.addAdditionalVariable("label");
   request.addPropertyRef("zone", "Label", "label");
   request.addPropertyValues("label", SparqlRequest.createValuesList("label1", "label2"));      

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:Label ?label .
      VALUES ?label {"label1" "label2" }
   }

Adding an individual

The ISparqlRequestGroup.addPropertyIndividualRef(String var, String propertyName, String individual) method allow to set an individual as the target of a property.

For example:

   SparqlPrefixDeclarations decl = new SparqlPrefixDeclarations(false);
   decl.addPrefix("sitac", "http://localhost/SITAC");
   SparqlRequest request = new SparqlRequest("sitac", decl);
   request.addSelect("group0");
   request.addPropertyIndividualRef("group0", "isClassifiedAs", "Own");

Will have the following SPARQL result:

   SELECT ?group0
   WHERE {
      ?group0 sitac:isClassifiedAs ?auto_1 .
      VALUES ?auto_1 { <http://localhost/SITAC#Own> }
   }

Groups

• The SPARQLRequest.addOptionalConstruct() method creates an OPTIONAL construct within the Sparql request. This construct can contain several expressions
• The SPARQLRequest.addUnionConstruct() method creates a list of UNION constructs within the Sparql request. This construct can contain several groups
• The SPARQLRequest.addInnerQuery() method adds an inner query to this query

Optional constructs

The addOptionalConstruct() method allows to create an OPTIONAL construct within the Sparql request. This construct can contain several expressions. The returned construct have the same API as the root request.

For example, for an OPTIONAL construct for only one property:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true, true);      

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      OPTIONAL { ?zone sitac:isTasked "true" }
   }

For an OPTIONAL construct for several properties:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addType("zone", "TaskZone");
   SparqlRequest.Group optional = request.addOptionalConstruct();
   optional.addPropertyValue("zone", "isTasked", true);
   optional.addPropertyValue("zone", "isFriend", true);      

Will return the following SPARQL content:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      OPTIONAL {
        ?zone sitac:isFriend "true" .
        ?zone sitac:isTasked "true" .
      }
   }

Sub-queries

The SPARQLRequest.addInnerQuery() method adds an inner query (sub-query) to a query.

For example:

   SparqlRequest request = new SparqlRequest(SCHEMA);
   request.addSelect("label");
   request.addSelect("distance");
   request.addSelect("visibility");

   SparqlRequest innerRequest = request.addInnerQuery();
   innerRequest.addSelect("label");
   innerRequest.addSelect("distance");
   innerRequest.addAdditionalVariable("wpt");
   innerRequest.addAdditionalVariable("ac");      
   ...

Specifying a prefix

By default the prefix specified at the creation of the SparqlRequest will be used for all references. It is however possible to specify any prefix with the addPrefixed* methods. For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addSelect("altitude");
   request.addType("zone", "Zone");
   request.addPrefixedPropertyRef("zone", "myPrefix", "hasAltitude", "altitude");      

Will return the following SPARQL content:

   SELECT ?zone ?altitude
   WHERE {
      ?zone rdf:type sitac:Zone .
      ?zone myPrefix:hasAltitude ?altitude .
   }

SPARQL query creation

The SPARQLRequest.getSPARQL() returns the constructed SPARQL request.

Specific Geosparql Request API

For specific GeoSparql requests, see GeoSparql request creation.

Specific owl-time Request API

The ISparqlRequestGroup.addTime(String var, String vvarTime, boolean isDateTime) gets the time for an individual.

Variables

The ISPARQLRequestGroup.getVariables() method return the map of variables which are in the SELECT part of the request.

The ISPARQLRequestGroup.getAdditionalVars() method return the map of al the other variables in the request.

Preferred variable

The SPARQLRequest.getPreferredVariable() method will return:

• The variable which is used in the ORDER By construct if there is an ORDER BY and the associated variable is in the SELECT construct
• Else the variable which is used in the GROUP By construct if there is an ORDER BY and the associated variable is in the SELECT construct
• Else the first variable in the SELECT construct

The SPARQLRequest.getPreferredVariableName() method return the name of this variable.

These methods can return null if the SELECT construct is "*".

Examples

Suppose that we have an ontology with an Aircraft class. We want to create a request getting the list of aircrafts.

We can do:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("elt");
   request.addType("elt", "Aircraft");
   String query = request.getSPARQL();

We will generate the following query:

   SELECT ?elt
   WHERE {
     ?elt rdf:type sitac:Aircraft .
   }