RDF4J SparqlBuilder is a fluent Java API used to programmatically create SPARQL query strings. It is based on the Spanqit query builder developed by Anqit Praqash, and has been slightly modified to allow tighter integration with the rest of the RDF4J framework.
SparqlBuilder allows the following SPARQL query:
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?name
WHERE { ?x foaf:name ?name }
ORDER BY ?name
LIMIT 5
OFFSET 10
to be created as simply as:
|
|
The RDF4J SparqlBuilder is based on the SPARQL 1.1 Query Recommendation and the SPARQL 1.1 Update Receommendation. Almost all features of SPARQL 1.1 are supported, excluding some current known limitations.
This document assumes the reader is already familiar with the SPARQL query language. Please refer to the above specification if not.
Obtain SparqlBuilder by adding the following dependency to your maven pom file:
<dependency>
<groupId>org.eclipse.rdf4j</groupId>
<artifactId>rdf4j-sparqlbuilder</artifactId>
<version>${rdf4j.version}</version>
</dependency>
The Queries class provides static methods to instantiate the various query objects. For example:
|
|
Query objects provide methods to set or add the various elements appropriate for the type of query:
|
|
SPARQL elements are created using various static factory classes. Most core elements of a query are created by the static SparqlBuilder class:
|
|
Other factory classes include the Queries class mentioned in the previous section, as well as the Expressions, GraphPatterns, and Rdf classes. All query elements created by SparqlBuilder implement the QueryElement interface, which provides the getQueryString() method. This can be used to get the String representing the SPARQL syntax of any element.
SparqlBuilder uses three classes to represent the SPARQL graph patterns, all of which implement the GraphPattern interface: - The TriplePattern class represents triple patterns. - The GraphPatternNotTriple class represents collections of graph patterns. - The SubSelect class represents a SPARQL sub query.
Graph patterns are created by the more aptly named GraphPatterns class.
Use GraphPatterns#tp()
to create a TriplePattern instance:
|
|
or, using RDF4J Model object and vocabulary constants directly:
|
|
In almost all places, SparqlBuilder allows either RDF4J Model objects or its own interfaces to be used. You can freely mix this.
A TriplePattern instance can also be created from the has()
and isA()
shortcut methods of RdfSubject
, and be expanded to contain multiple triples with the same subject via predicate-object lists and object lists:
|
|
Three methods in GraphPatterns exist to create GraphPatternNotTriple instances. GraphPatterns#and()
creates a group graph pattern, consisting of the GraphPattern instances passed as parameters:
|
|
GraphPatterns#union()
creates an alternative graph pattern, taking the union of the provided GraphPattern instances:
|
|
GraphPatterns#optional()
creates an optional group graph pattern, consisting of the passed in GraphPattern
s:
|
|
Finally, GraphPatterns#select() creates an instance of a SubSelect, which represents a SPARQL subquery:
|
|
You can create SPARQL query constraints using the Expressions class which provides static methods to create Expression objects representing SPARQL’s built-in expressions:
|
|
Expression
s take Operand
instances as arguments. Operand is implemented by the types you would expect (Variable, the RDF model interface RdfValue, and Expression itself). Where possible, Expressions has included wrappers to take appropriate Java primitives as parameters as well:
|
|
For those places where a wrapper has not (yet) been created, RdfLiteral
s can be used instead. The Rdf
class provides factory methods to create StringLiteral, NumericLiteral, and BooleanLiteral instances:
|
|
SparqlBuilder provides a collection of interfaces to model RDF objects in the org.eclipse.rdf4j.sparqlbuilder.rdf
package. Instances of these interfaces can be used when needed and as expected while creating SPARQL queries. The Rdf
class contains static factory methods to create RDF objects for use with SparqlBuilder, including IRI’s, blank nodes, and RDF literals.
Currently SparqlBuilder’s set of interfaces for RDF model objects is different from the main RDF4J model interfaces. This will be further integrated in future releases.
For more detailed examples of how to use SparqlBuilder, check out the JUnit tests located within the project.
Currently, the following SPARQL 1.1 features have not yet been implemented in SparqlBuilder: