SPARQL Burger Documentation

Get Started

SPARQL Burger works with Python 2.x and 3.x. It is easy to configure and use. Take a look at the following instructions!

Installation

There are two installation options:

Manually: Copy the SPARQLBurger folder to your project's directory.

From PyPi: Use the pip command to install the package:

                      
                        pip install SPARQL-Burger

Usage Examples

The following examples are expected to help you understand how SPARQL Burger works:

In this example we generate a minimal SPARQL graph pattern. A graph pattern, delimited with { }, is a building block for SPARQL queries and more than one can be nested and/or united to form a more complex graph pattern.

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create a graph pattern
pattern = SPARQLGraphPattern()

# Add a couple of triples to the pattern
pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasName", object="?name")
    ]
)

# Let's print this graph pattern
print(pattern.get_text())

The printout is:

					  
{
   ?person rdf:type ex:Person . 
   ?person ex:hasName ?name . 
}

Here, the main graph pattern contains another graph pattern that is declared as OPTIONAL. In general, graph patterns can contain as many nesting levels as necessary. Nesting a pattern to itself, though, would result to an error.

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create a main graph pattern and add some triples
main_pattern = SPARQLGraphPattern()
main_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasName", object="?name")
    ]
)

# Create an optional pattern and add a triple
optional_pattern = SPARQLGraphPattern(optional=True)
optional_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="ex:hasAge", object="?age")
    ]
)

# Nest the optional pattern to the main
main_pattern.add_nested_graph_pattern(optional_pattern)

# Let's print the main graph pattern
print(pattern.get_text())

The printout is:

					  
{
   ?person rdf:type ex:Person . 
   ?person ex:hasName ?name . 
   OPTIONAL {
      ?person ex:hasAge ?age . 
   }
}

In this example we will declare a main graph pattern that contains two other graph patterns associated with UNION.

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create an empty graph pattern
main_pattern = SPARQLGraphPattern()

# Create the first graph pattern to be nested and add some triples
first_pattern = SPARQLGraphPattern()
first_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasName", object="?name")
    ]
)

# Create the second graph pattern to be nested as a UNION to the first and add some triples
second_pattern = SPARQLGraphPattern(union=True)
second_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:User"),
        Triple(subject="?person", predicate="ex:hasNickname", object="?name")
    ]
)

# Nest both patterns to the main one
main_pattern.add_nested_graph_pattern(graph_pattern=first_pattern)
main_pattern.add_nested_graph_pattern(graph_pattern=second_pattern)

# Let's print the main graph pattern
print(main_pattern.get_text())

The printout is:

					  
{
   {
      ?person rdf:type ex:Person . 
      ?person ex:hasName ?name . 
   }
   UNION {
      ?person rdf:type ex:User . 
      ?person ex:hasNickname ?name . 
   }
}

So far we have created simple and nested graph patterns. Now let's see how to add filters, bindings and if clauses.

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create a graph pattern and add some triples
pattern = SPARQLGraphPattern()
pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasAge", object="?age")
    ]
)

# Add a filter for variable ?age
pattern.add_filter(
    filter= Filter(
        expression="?age < 65"
    )
)

# Add a binding for variable ?years_alive
pattern.add_binding(
    binding=Binding(
        value="?age",
        variable="?years_alive"
    )
)

# Add a binding for variable ?status, that should be "minor" or "adult" based on the ?age value
pattern.add_binding(
    binding=Binding(
        value=IfClause(
            condition="?age >= 18",
            true_value="'adult'",
            false_value="'minor'"
        ),
        variable="?status"
    )
)

# Print the graph pattern
print(pattern.get_text())

The printout is:

					  
{
   ?person rdf:type ex:Person . 
   ?person ex:hasAge ?age . 
   BIND (?age AS ?years_alive)
   BIND (IF (?age >= 18, 'adult', 'minor') AS ?status)
   FILTER (?age < 65)
}

In the first BIND we have only provided a value and a variable as string, but this is not always the case. In the second BIND we nested an IF clause. Therefore, the Binding.value also accepts objects of classes like IfClause. In a similar way, the arguments of IfClause can also be other objects of type IfClause and Bound in a nested format, as shown below.

Now that we have mastered the definition of graph patterns, let's create a simple Select query.

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create an object of class SPARQLSelectQuery and set the limit for the results to 100
select_query = SPARQLSelectQuery(distinct=True, limit=100)

# Add a prefix
select_query.add_prefix(
    prefix=Prefix(prefix="ex", namespace="http://www.example.com#")
)

# Add the variables we want to select
select_query.add_variables(variables=["?person", "?age"])

# Create a graph pattern to use for the WHERE part and add some triples
where_pattern = SPARQLGraphPattern()
where_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasAge", object="?age"),
        Triple(subject="?person", predicate="ex:address", object="?address"),
    ]
)

# Set this graph pattern to the WHERE part
select_query.set_where_pattern(graph_pattern=where_pattern)

# Group the results by age
select_query.add_group_by(
    group=GroupBy(
        variables=["?age"]
    )
)

# Print the query we have defined
print(select_query.get_text())

The printout is:

					  
PREFIX ex: <http://www.example.com#>

SELECT DISTINCT ?person ?age
WHERE {
   ?person rdf:type ex:Person . 
   ?person ex:hasAge ?age . 
   ?person ex:address ?address . 
}
GROUP BY ?age
LIMIT 100

Quite similarly we can exploit graph patterns to create a SPARQL Update query (in the DELETE/INSERT form).

					  
from SPARQLBurger.SPARQLQueryBuilder import *

# Create a SPARQLUpdateQuery object
update_query = SPARQLUpdateQuery()

# Add a prefix
update_query.add_prefix(
    prefix=Prefix(prefix="ex", namespace="http://www.example.com#")
)

# Create a graph pattern for the DELETE part and add a triple
delete_pattern = SPARQLGraphPattern()
delete_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="ex:hasAge", object="?age")
    ]
)

# Create a graph pattern for the INSERT part and add a triple
insert_pattern = SPARQLGraphPattern()
insert_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="ex:hasAge", object="32")
    ]
)

# Create a graph pattern for the WHERE part and add some triples
where_pattern = SPARQLGraphPattern()
where_pattern.add_triples(
    triples=[
        Triple(subject="?person", predicate="rdf:type", object="ex:Person"),
        Triple(subject="?person", predicate="ex:hasAge", object="?age")
    ]
)

# Now let's append these graph patterns to our query
update_query.set_delete_pattern(graph_pattern=delete_pattern)
update_query.set_insert_pattern(graph_pattern=insert_pattern)
update_query.set_where_pattern(graph_pattern=where_pattern)

# Print the query we have defined
print(update_query.get_text())

The printout is:

					  
PREFIX ex: <http://www.example.com#>

DELETE {
   ?person ex:hasAge ?age . 
}
INSERT {
   ?person ex:hasAge 32 . 
}
WHERE {
   ?person rdf:type ex:Person . 
   ?person ex:hasAge ?age . 
}

Class Reference

SPARQL Burger contains SPARQLQueryBuilder.py, with classes for graph patterns and queries, and SPARQLSyntaxTerms.py, with classes for SPARQL building blocks. These building blocks do not currently cover the whole spectrum of the SPARQL language. More terms will be added in future releases.

class SPARQLGraphPattern

The SPARQLGraphPattern class allows the definition of graph patterns.

__init__(boolean optional=False, boolean union=False)

The SPARQLGraphPattern class constructor.

optional: Indicates if graph pattern should be marked as OPTIONAL.

union: Indicates if graph pattern should have a UNION clause that associates it with the previous.
add_triples(list triples)

Adds a list of triples to the graph pattern.

triples: A list of SPARQLSyntaxTerms.Triple objects.

return: True if addition succeeded, False if given argument was not a list of Triple objects.
add_nested_graph_pattern(object graph_pattern)

Adds another graph pattern as nested to the main graph pattern.

graph_pattern: The SPARQLGraphPattern object to be nested.

return: True if addition succeeded, False if given argument was not a SPARQLGraphPattern object.
add_nested_select_query(object select_query)

Adds a select query as nested to the main graph pattern.

select_query: The SPARQLSelectQuery object to be nested.

return: True if addition succeeded, False if given argument was not a SPARQLGraphPattern object.
add_filter(object filter)

Adds a FILTER expression to the graph pattern.

add_filter: The Filter object to be added.

return: True if addition succeeded, False if given argument was not a Filter object.
add_binding(object binding)

Description

binding: The Binding object to be added.

return: True if addition succeeded, False if given argument was not a Binding object.
get_text(int indentation_depth=0)

Generates the text for the SPARQL graph pattern.

indentation_depth: A value that facilitates the appropriate addition of indents to the text. Should defaults at 0.

return: The SPARQL graph pattern text. Returns empty string if an exception was raised.

class SPARQLSelectQuery

The SPARQLSelectQuery class allows the definition of Select queries.

__init__(boolean distinct=False, int limit=False, boolean include_popular_prefixes=False)

The SPARQLSelectQuery class constructor.

distinct: Indicates if the select should be SELECT DISTINCT.

limit: A limit to be used for the select query results.

include_popular_prefixes: Indicates whether the query should automatically include a set of popular prefixes (rdf, rdfs, xml, owl, prov, foaf).
add_prefix(object prefix)

Appends a PREFIX expression to the query.

prefix: The Prefix object to be added.

return: True if addition succeeded, False if given argument was not a Prefix object.
set_where_pattern(object super_class)

Sets the SPARQLGraphPattern object to be used at the WHERE part.

graph_pattern: The SPARQLGraphPattern object to be used.

return: True if setting succeeded, False if given argument was not a SPARQLGraphPattern object.
add_variables(list variables)

Appends a list of variables to be selected by the select query.

variables: A list of variables as strings. This could also be used to append variables like "COUNT(?person) AS population".

return: True if addition succeeded, False if given argument was not a list of strings.
add_group_by(object group)

Adds a GROUP BY expression to the query.

group: The GroupBy object to be added.

return: True if addition succeeded, False if given argument was not a GroupBy object.
get_text(int indentation_depth=0)

Generates the text for the SPARQL select query.

indentation_depth: A value that facilitates the appropriate addition of indents to the text. Should default at 0.

return: The SPARQL Select query text. Returns empty string if an exception was raised.

class SPARQLUpdateQuery

The SPARQLUpdateQuery class allows the definition of Update queries.

__init__(boolean include_popular_prefixes=False)

The SPARQLUpdateQuery class constructor.

include_popular_prefixes: Indicates whether the query should automatically include a set of popular prefixes (rdf, rdfs, xml, owl, prov, foaf).
add_prefix(object prefix)

Appends a PREFIX expression to the query.

prefix: The Prefix object to be added.

return: True if addition succeeded, False if given argument was not a Prefix object.
set_where_pattern(object super_class)

Sets the SPARQLGraphPattern object to be used at the WHERE part.

graph_pattern: The SPARQLGraphPattern object to be used.

return: True if setting succeeded, False if given argument was not a SPARQLGraphPattern object.
set_delete_pattern(object super_class)

Sets the SPARQLGraphPattern object to be used at the DELETE part.

graph_pattern: The SPARQLGraphPattern object to be used.

return: True if setting succeeded, False if given argument was not a SPARQLGraphPattern object.
set_insert_pattern(object super_class)

Sets the SPARQLGraphPattern object to be used at the INSERT part.

graph_pattern: The SPARQLGraphPattern object to be used.

return: True if setting succeeded, False if given argument was not a SPARQLGraphPattern object.
get_text(int indentation_depth=0)

Generates the text for the SPARQL Update query.

indentation_depth: A value that facilitates the appropriate addition of indents to the text. Should default at 0.

return: The SPARQL Update query text. Returns empty string if an exception was raised.

class Prefix

This class represents a PREFIX to be used in a SPARQL query.

__init__(string prefix, string namespace)

The Prefix class constructor.

prefix: The desired prefix (e.g. "ex").

namespace: The namespace (e.g. "http://www.example.com#").
get_text()

Generates the text for the given prefix (e.g. "PREFIX ex: <http://www.example.com#>").

return: The prefix definition text. Returns empty string if an exception was raised.

class Triple

This class represents a triple to be used in a SPARQL graph pattern.

__init__(string subject, string predicate, string object)

The Triple class constructor.

subject: The subject string (e.g. "?person").

predicate: The predicate string (e.g. "ex:hasName").

object: The object string (e.g. "\'John\'@en").
get_text()

Generates the text for the given triple. (e.g. "PREFIX ex: <http://www.example.com#>").

return: The triple definition text. Returns empty string if an exception was raised.

class Filter

This class represents a FILTER to be used in a SPARQL graph pattern.

__init__(string expression)

The Filter class constructor.

expression: The expression to get in the filter (e.g. "?age > 30")
get_text()

Generates the text for the given filter.

return: The filter definition text. Returns empty string if an exception was raised.

class Binding

This class represents a BIND to be used in a SPARQL graph pattern.

__init__(string/object value, string variable)

The Binding class constructor.

value: A string value to get in the BIND first part (e.g. "John") OR another object (e.g. IfClause) to be nested.

variable: The variable to be bound to this value (e.g. "?name")
get_text()

Generates the text for the given binding (e.g. "BIND('John' AS ?name)" or "BIND(IF(BOUND(...)) AS ?name)" ).

return: The binding definition text. Returns empty string if an exception was raised.

class Bound

This class represents a BOUND to be used in a SPARQL graph pattern.

__init__(string/object variable)

The Bound class constructor.

variable: The variable to be checked if it is bound (e.g. "?name") OR another object to be nested.
get_text()

Generates the text for the given BOUND clause (e.g. "BOUND (?name)" ).

return: The bound definition text. Returns empty string if an exception was raised.

class IfClause

This class represents an IF to be used in a SPARQL graph pattern.

__init__(string/object condition, string/object true_value, string/object false_value)

The IfClause class constructor.

condition: The condition for the IF clause OR another object (e.g. Bound object) to be nested.

true_value: The value for when IF condition is True OR another object to be nested.

false_value: The value for when IF condition is False OR another object to be nested.
get_text()

Generates the text for the given BOUND clause (e.g. "IF(?age > 18, 'adult', 'minor')" ).

return: The if clause definition text. Returns empty string if an exception was raised.

class GroupBy

This class represents a GROUP BY to be used in a SPARQL query.

__init__(list variables)

The GroupBy class constructor.

variables: A list of variables as strings that will be used for the grouping.
get_text()

Generates the text for the given GROUP BY expression (e.g. "GROUP BY ?person ?age" ).

return: The GROUP BY definition text. Returns empty string if an exception was raised.

Get Started

Installation

Usage Examples

Class Reference

class SPARQLGraphPattern

__init__(boolean optional=False, boolean union=False)

add_triples(list triples)

add_nested_graph_pattern(object graph_pattern)

add_nested_select_query(object select_query)

add_filter(object filter)

add_binding(object binding)

get_text(int indentation_depth=0)

class SPARQLSelectQuery

__init__(boolean distinct=False, int limit=False, boolean include_popular_prefixes=False)

add_prefix(object prefix)

set_where_pattern(object super_class)

add_variables(list variables)

add_group_by(object group)

get_text(int indentation_depth=0)

class SPARQLUpdateQuery

__init__(boolean include_popular_prefixes=False)

add_prefix(object prefix)

set_where_pattern(object super_class)

set_delete_pattern(object super_class)

set_insert_pattern(object super_class)

get_text(int indentation_depth=0)

class Prefix

__init__(string prefix, string namespace)

get_text()

class Triple

__init__(string subject, string predicate, string object)

get_text()

class Filter

__init__(string expression)

get_text()

class Binding

__init__(string/object value, string variable)

get_text()

class Bound

__init__(string/object variable)

get_text()

class IfClause

__init__(string/object condition, string/object true_value, string/object false_value)

get_text()

class GroupBy

__init__(list variables)

get_text()

init(boolean optional=False, boolean union=False)

init(boolean distinct=False, int limit=False, boolean include_popular_prefixes=False)

init(boolean include_popular_prefixes=False)

init(string prefix, string namespace)

init(string subject, string predicate, string object)

init(string expression)

init(string/object value, string variable)

init(string/object variable)

init(string/object condition, string/object true_value, string/object false_value)

init(list variables)