Jena SPARQL request creation

The org.da.protoframework.jena.common.sparql.SparqlRequest class allows to create SPARQL requests easily without having to write the request "by hand". This class is available in the JenaCommon.jar jar file.

SparqlRequest API

The SparqlRequest class has the following API:

public class org.da.protoframework.jena.common.sparql.SparqlRequest

An utility which generates a SPARQL request.

Modifier and Type	Method and Description
void	SparqlRequest(String schema) Creates a SPARQL request for a specified schema
boolean	addAdditionalVariable(String var) Add 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)
String	addAutoVariable() Add a variable with an unused automatically specified name, to be used in the WHERE part of the request. Return the variable name
Bind	addBind(String var) Add a BIND for a variable
Filter addFilter	addFilter Add a FILTER
SparqlRequest	addInnerQuery() Add an inner query to this query
SparqlRequest.Group	addOptionalConstruct() Creates an OPTIONAL construct within the Sparql request. This construct can contain several expressions
boolean	addPropertyIndividualRef(String var, String propertyName, String individual) Add a reference to an individual for a variable property in the WHERE part of the request. Return true if the variable has been defined
boolean	addPropertyIndividualRef(String var, String propertyName, String individual, boolean optional) Add a reference to an individual 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 optinoal in the request
boolean	addPropertyRef(String var, String propertyName, String varRef) Add a reference to another variable for a variable property in the WHERE part of the request. Return true if both variables have been defined
boolean	addPropertyRef(String var, String propertyName, String varRef, boolean optional) Add 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 optinoal in the request
boolean	addPropertyValue(String var, String propertyName, String propertyValue) Add a property value specification for a variable property in the WHERE part of the request. Return true if the variable has been defined
boolean	addPropertyValue(String var, String propertyName, String propertyValue, boolean optional) Add 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 optinoal in the request
boolean	addSelect(String var) Add 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)
boolean	addSelect(Expression expr, String asVar) Add an expression to use in the SELECT part of the request. Return true if the asVar variable could be added (which means it was not already defined in the WHERE part of the request)
boolean	addSubClassOf(String var, String type) Specifies the rdf:subClassOf of a variable in the WHERE part of the request. Return true if the variable has been defined
boolean	addSubClassOfStar(String var, String type) Specifies the rdf:subClassOf* of a variable in the WHERE part of the request. Return true if the variable has been defined
boolean	addType(String var, String type) Specifies the rdf:type of a variable in the WHERE part of the request. Return true if the variable has been defined
SparqlRequest.Union	addUnionConstruct() Creates a list of UNION constructs within the Sparql request. This construct can contain several groups
String	getSPARQL() Return the constructed SPARQL request
void	selectDistinct(boolean selectDistinct) Specifies if the SELECT part of the request must be DISTINCT
void	setLimit(int limit) Specify the value for the LIMIT filter
void	setOrderBy(String expression, boolean ascending) Specify the value for the ORDER BY filter. The ascending argument allows to specify if the ordering is ascending or descending
void	setSelect(String... vars) Sets the list of variables to use in the SELECT part of the request

Selects

The following methods allow to add an item in the SELECT construct:

public class org.da.protoframework.jena.common.SparqlRequest

Modifier and Type	Method and Description
boolean	addSelect(String var) Add 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)
boolean	addSelect(Expression expr, String asVar) Add an expression to use in the SELECT part of the request. Return true if the asVar variable could be added (which means it was not already defined in the WHERE part of the request)
boolean	hasSelectVariable(String var) Return true if a variable is alsready part of the SELECT
void	setSelect(String... vars) Sets the list of variables to use in the SELECT part of the request
boolean	setSelectAll() Set the "SELECT *" construct

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

Triple patterns

Several methods allow to specify a triple pattern in the WHERE part of the query:

public class org.da.protoframework.jena.common.sparql.SparqlRequest

An utility which generates a SPARQL request.

Modifier and Type	Method and Description
boolean	addPropertyIndividualRef(String var, String propertyName, String individual) Add a reference to an individual for a variable property in the WHERE part of the request. Return true if the variable has been defined
boolean	addPropertyIndividualRef(String var, String propertyName, String individual, boolean optional) Add a reference to an individual 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 optinoal in the request
boolean	addPropertyRef(String var, String propertyName, String varRef) Add a reference to another variable for a variable property in the WHERE part of the request. Return true if both variables have been defined
boolean	addPropertyRef(String var, String propertyName, String varRef, boolean optional) Add 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 optinoal in the request
boolean	addPropertyValue(String var, String propertyName, String propertyValue) Add a property value specification for a variable property in the WHERE part of the request. Return true if the variable has been defined
boolean	addPropertyValue(String var, String propertyName, String propertyValue, boolean optional) Add 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 optinoal in the request
boolean	addPropertyValues(String var, String propertyName, List values) Add a property value specification between one variable and a list of values
boolean	addSubClassOf(String var, String type) Specifies the rdf:subClassOf of a variable in the WHERE part of the request. Return true if the variable has been defined
boolean	addSubClassOfStar(String var, String type) Specifies the rdf:subClassOf* of a variable in the WHERE part of the request. Return true if the variable has been defined
boolean	addType(String var, String type) Specifies the rdf:type of a variable in the WHERE part of the request. Return true if the variable has been defined

Specifying the type of a variable

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

Specifying a triple between two variables and a property

The 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 addPropertyValue(String var, String propertyName, String 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, an individual, and a property

The addPropertyIndividualRef(String var, String propertyName, String individual) 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 addPropertyValues(String var, String propertyName, List values)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" }
        }

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

Filters

It is possible to add a FILTER construct with the 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 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)
        }

Optional constructs

The addOptionalConstruct() method allows to create an OPTIONAL construct withih the Sparql request. This construct can contain several expressions. The API SparqlRequest.Optional result is:

public class org.da.protoframework.jena.common.SparqlRequest.Optional

The optional construct.

Modifier and Type	Method and Description
boolean	addPropertyIndividualRef(String var, String propertyName, String individual) Add a reference to an individual for a variable property in the OPTIONAL construct. Return true if the variable has been defined
boolean	addPropertyRef(String var, String propertyName, String varRef) Add a reference to another variable for a variable property in the OPTIONAL construct. Return true if both variables have been defined
boolean	addPropertyValue(String var, String propertyName, String propertyValue) Add a property value specification for a variable property in the OPTIONAL construct. Return true if the variable has been defined
boolean	addSubClassOf(String var, String type) Specifies the rdf:subClassOf of a variable in the OPTIONAL construct. Return true if the variable has been defined
boolean	addType(String var, String type) Specifies the rdf:type of a variable in the OPTIONAL construct. Return true if the variable has been defined

For example, for an OPTIONAL consreuct 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 consreuct 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 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");      
        ...

Specific Geosparql Request API

For specific GeoSparql requests, see GeoSparql request creation.

Specific owl-time Request API

For specific owl-time requests, see owl-time request creation.

Examples

Basic example

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

A more complex example

Now we have the same class, but individuals from this class have a TheLabel object property, and we want to return the associated Label individual rather than the Aircraft individuals.

We can do:

        SparqlRequest request = new SparqlRequest("sitac");
        request.addSelect("label");
        request.addAdditionalVariable("elt");
        request.addType("elt", "Aircraft");
        request.addType("label", "Label");
        request.addPropertyRef("elt", "TheLabel", "label");
        String query = request.getSPARQL();

We will generate the following query:

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

Another example

Now we will use a Waypoint class, which can be in the Flightplan if their inFlightPlan data property value is true. If we want to return the list of waypoints which are in the Flightplan, we can do:

        SparqlRequest request = new SparqlRequest("sitac");
        request.addSelect("elt");
        request.addType("elt", "Waypoint");
        request.addPropertyValue("elt", "inFlightPlan", true);
        String query = request.getSPARQL();

We will generate the following query:

        SELECT ?elt
        WHERE
        {
          ?elt rdf:type sitac:Waypoint .
          ?elt sitac:inFlightPlan "true" .      
        }      

An example with an OPTIONAL pattern

Now we have an additional property value reference, which is an OPTIONAL pattern.

We can do:

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

We will generate the following query:

        SELECT ?elt
        WHERE
        {
          ?elt rdf:type sitac:Aircraft .
          OPTIONAL {?elt sitac:TheLabel "Rafale" }
        }      

An example with an OPTIONAL pattern with several expressions

Now we will create an OPTIONAL pattern with two properties references.

We can do:

        SparqlRequest request = new SparqlRequest("sitac");
        request.addSelect("elt");
        request.addType("elt", "Aircraft");
        SparqlRequest.Group optional = request.addOptionalConstruct();
        optional.addPropertyValue("elt", "TheLabel", "Rafale");
        optional.addPropertyValue("elt", "isFriend", "true");
        String query = request.getSPARQL();

We will generate the following query:

        SELECT ?elt
        WHERE
        {
           ?elt rdf:type sitac:Aircraft .
           OPTIONAL {
             ?elt sitac:TheLabel "Rafale" .
             ?elt sitac:isFriend "true"      
           }
        }      

An example with an UNION pattern

Now we will create an UNION pattern.

We can do:

        SparqlRequest request = new SparqlRequest("sitac");
        request.addSelect("elt");
        request.addType("elt", "Aircraft");
        SparqlRequest.Union union = request.addUnionConstruct();
        SparqlRequest.Group group = union.addGroup();
        group.addPropertyValue("elt", "TheLabel", "Rafale");
        group = union.addGroup();       
        optional.addPropertyValue("elt", "isFriend", "false");
        String query = request.getSPARQL();

We will generate the following query:

        SELECT ?elt
        WHERE
        {
          ?elt rdf:type sitac:Aircraft .
          { ?elt sitac:TheLabel "Rafale" }
          UNION { ?elt sitac:isFriend "false" } 
        }