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

Several methods allow to add elements in the SELECT part of the SPARQL request:

• 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

FILTER and BIND content

Several methods allow to add FILTER or BIND content in SPARQL requests:

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

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

WHERE content

Accessing the WHERE form of a SPARQL request can be performed with the ISparqlRequestGroup.getWhereForm() method.

For example:

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

s

ASK content

Creating the ASK content for a SPARQL requuest can be performed with the ISparqlRequestGroup.addASK() method.

For example:

   SparqlRequest request = new SparqlRequest("foaf");
   request.addAdditionalVariable("x");
   AskForm form = request.addAsk();
   form.addPropertyValue("x", "Name", "Alice");
   String sparql = request.getSPARQL();

INSERT and DELETE content

Adding an INSERT, INSERT DATA, or DELETE form can be performed through the following methods:

• The ISparqlRequestGroup.addInsert() method adds an INSERT form
• The ISparqlRequestGroup.addInsertData() method adds an INSERT DATA form
• The ISparqlRequestGroup.addDelete() method adds a DELETE form

Adding expressions in the WHERE or ASK form

Adding expressions in the WHERE or ASK form can be performed directly in the WhereForm or the AskForm, or through the ISparqlRequestGroup which will defer to the effective WHERE or ASK form.

For example, the following are equivalent:

   SparqlRequest request = new SparqlRequest("foaf");
   request.addAdditionalVariable("x");
   AskForm form = request.addAsk();
   form.addPropertyValue("x", "Name", "Alice");
   String sparql = request.getSPARQL();

or

   SparqlRequest request = new SparqlRequest("foaf");
   request.addAdditionalVariable("x");
   AskForm form = request.addAsk();
   request.addPropertyValue("x", "Name", "Alice");
   String sparql = request.getSPARQL();

Handling comments

Comments can be added in most of the elements in the SPARQL request.

For example:

   SparqlRequest request = new SparqlRequest("sitac");
   request.addSelect("zone");
   request.addAdditionalVariable("index");
   request.addType("zone", "TaskZone");
   request.addPropertyValue("zone", "isTasked", true);
   OperationResult<PropertyRef> propRef = request.addPropertyRef("zone", "hasIndex", "index");
   propRef.setCommentOnElement("Comment on hasIndex");
      
   String content = request.getSPARQL(true);

Will have the following result:

   SELECT ?zone
   WHERE {
      ?zone rdf:type sitac:TaskZone .
      ?zone sitac:isTasked "true" .
      ?zone sitac:hasIndex ?index . # Comment on hasIndex
   }      

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 serialization

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