rdf4j logo Eclipse rdf4j: documentation


Creating SPARQL Queries with the SparqlBuilder

1. Introduction

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.

integration of SparqlBuilder with the RDF4J framework is a work-in-progress. This means that the current SparqlBuilder API should be considered "experimental". Although we’ll do our best to avoid it, we may make some backward-incompatible changes in this API in a future MINOR release.

SparqlBuilder allows the following SPARQL query:

PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?name
WHERE { ?x foaf:name ?name }
ORDER BY ?name

to be created as simply as:

    .where(x.has(foaf.iri("name"), name))

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)[known limitations].

This document assumes the reader is already familiar with the SPARQL query language. Please refer to the above specification if not.

2. Getting SparqlBuilder

Obtain SparqlBuilder by adding the following dependency to your maven pom file:


3. Queries

The Queries class provides static methods to instantiate the various query objects. For example:

SelectQuery selectQuery = Queries.SELECT();
ConstructQuery constructQuery = Queries.CONSTRUCT();

Query objects provide methods to set or add the various elements appropriate for the type of query:

Prefix ex;
Variable product;
TriplePattern personWroteBook, personAuthoredBook;

// ...


4. Elements

SPARQL elements are created using various static factory classes. Most core elements of a query are created by the static SparqlBuilder class:

Variable price = SparqlBuilder.var("price");
// ==> ?price

Prefix foaf = SparqlBuilder.prefix("foaf", iri("http://xmlns.com/foaf/0.1/"));
// ==> PREFIX foaf: <http://xmlns.com/foaf/0.1/>

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.

5. Graph Patterns

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.

5.1. Triple Patterns

Use GraphPatterns#tp() to create a TriplePattern instance:

Prefix dc = SparqlBuilder.prefix("dc", iri("http://purl.org/dc/elements/1.1/"));
Variable book = SparqlBuilder.var("book");

TriplePattern triple = GraphPatterns.tp(book, dc.iri("author"), Rdf.literalOf("J.R.R. Tolkien"));
// ==> ?book dc:author "J.R.R. Tolkien"

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:

Prefix foaf = SparqlBuilder.prefix("foaf", iri("http://xmlns.com/foaf/0.1/"));
Variable x = SparqlBuilder.var("x"), name = SparqlBuilder.var("name");

TriplePattern triple = x.has(foaf.iri("nick"), Rdf.literalOf("Alice"), Rdf.literalOf("Alice_"))
    .andHas(foaf.iri("name"), name);
// ===> ?x foaf:nick "Alice_", "Alice" ;
//	   foaf:name ?name .

5.2. Compound graph patterns

Three methods in GraphPatterns exist to create GraphPatternNotTriple instances. GraphPatterns#and() creates a group graph pattern, consisting of the GraphPattern instances passed as parameters:

Variable mbox = SparqlBuilder.var("mbox"), x = SparqlBuilder.var("x");
GraphPatternNotTriple groupPattern =
GraphPatterns.and(x.has(foaf.iri("name"), name), x.has(foaf.iri("mbox"), mbox);
// ==> { ?x foaf:mbox ?mbox . ?x foaf:name ?name }

GraphPatterns#union() creates an alternative graph pattern, taking the union of the provided GraphPattern instances:

Prefix dc10 = SparqlBuilder.prefix("dc10", iri("http://purl.org/dc/elements/1.0/")),
	dc11 = SparqlBuilder.prefix("dc11", iri("http://purl.org/dc/elements/1.1/"));
Variable book = SparqlBuilder.var("book"), title = SparqlBuilder.var("title");

GraphPatternNotTriple union = GraphPatterns.union(book.has(dc10.iri("title"), title),
	book.has(dc11.iri("title"), title);
// ==> { ?book dc10:title ?title } UNION { ?book dc11:title ?title }

GraphPatterns#optional() creates an optional group graph pattern, consisting of the passed in `GraphPattern`s:

GraphPatternNotTriple optionalPattern = GraphPatterns.optional(GraphPatterns.tp(x, foaf.iri("mbox"), mbox));
// ==> OPTIONAL { ?x foaf:mbox ?mbox }

5.3. Sub-select

Finally, GraphPatterns#select() creates an instance of a SubSelect, which represents a SPARQL subquery:

SubSelect subQuery = GraphPatterns.select();

6. Query Constraints

You can create SPARQL query constraints using the Expressions class which provides static methods to create Expression objects representing SPARQL’s built-in expressions:

Variable name = SparqlBuilder.var("name");
Expression<?> regexExpression = Expressions.regex(name, "Smith");
// ==> REGEX( ?name, "Smith" )

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:

Variable price = SparqlBuilder.var("price");
Expression<?> priceLimit = Expressions.lt(price, 100);
// ==> ?price < 100

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:

Variable price = SparqlBuilder.var("price");
ExpressionOperand discount = Rdf.literalOf(0.9);
Expression<?> discountedPrice = Expressions.multiply(price, discount);
// ==> ( ?price * 0.9 )

7. The RDF Model

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.

8. Examples

For more detailed examples of how to use SparqlBuilder, check out the JUnit tests located within the project.

9. Known Limitations

Currently, the following SPARQL 1.1 features have not yet been implemented in Spanqit: