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) constructor creates a SPARQL request for a specified default schema

Global parameters of the request

• The SPARQLRequest.selectDistinct(boolean) method specifies if the SELECT part of the request must be DISTINCT
• The SPARQLRequest.setLimit(int) method specifies the value for the LIMIT filter
• The SPARQLRequest.setOrderBy(String, boolean) smethod pecifies the value for the ORDER BY filter. The ascending argument allows to specify if the ordering is ascending or descending

SELECT content

• The SPARQLRequest.addSelect(String) 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...) method adds a list of variables to use in the SELECT part of the request
• The SPARQLRequest.setSelect(String...) method sets the list of variables to use in the SELECT part of the request
• The SPARQLRequest.addSelect(Expression, String) 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) 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) 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 SPARQLRequest.addAdditionalVariable(String) 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 SPARQLRequest.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, String) 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, String) 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, String) 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, String) 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, String) 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, String) 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, String, Object) 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, String, Object, boolean) 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, List) method adds a property value declaration in the WHERE part of the request, for several values
• The ISparqlRequestGroup.addPropertyRef(String, String, String) 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, String, String, boolean) 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, String, String) 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, String, String) 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, String, Object) 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, an individual, and a property

The ISparqlRequestGroup.addPropertyIndividualRef(String, String, String) method allows to specify a triple pattern between a variable, a specific individual, and a property. For example:

   SparqlRequest request = new SparqlRequest(SCHEMA);
   request.addSelect("label");
   request.addAdditionalVariable("wpt");
   request.addType("wpt", "Waypoint");

   request.addPropertyIndividualRef("wpt", "hasWaypointType", "ATT");
   request.addPropertyRef("wpt", "Label", "label"); 

Will return the following SPARQL content:

   SELECT ?label
   WHERE {
      ?wpt rdf:type inav:Waypoint .
      ?wpt inav:hasWaypointType inav:ATT .
      ?wpt inav:Label ?label .

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

The ISparqlRequestGroup.addPropertyValues(String, List) 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" }
   }

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, String, boolean) gets the time for an individual.

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 .
   }