Expressions and Testing Values

SPARQL FILTERs restrict the solutions of a graph pattern match according to a given constraint. Specifically, FILTERs eliminate any solutions that, when substituted into the expression, either result in an effective boolean value of false or produce an error. Effective boolean values are defined in section 17.2.2 Effective Boolean Value and errors are defined in XQuery 1.0: An XML Query Language [XQuery 1.0: An XML Query Language] section 2.3.1, Kinds of Errors. These errors have no effect outside of FILTER evaluation.

RDF literals may have a datatype IRI:

@prefix a:          <http://www.w3.org/2000/10/annotation-ns#> .
@prefix dc:         <http://purl.org/dc/elements/1.1/> .

_:a   a:annotates   <http://www.w3.org/TR/rdf-sparql-query/> .
_:a   dc:date       "2004-12-31T19:00:00-05:00" .

_:b   a:annotates   <http://www.w3.org/TR/rdf-sparql-query/> .
_:b   dc:date       "2004-12-31T19:01:00-05:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

The object of the first dc:date triple has no type information. The second has the datatype xsd:dateTime.

SPARQL expressions are constructed according to the grammar and provide access to functions (named by IRI) and operator functions (invoked by keywords and symbols in the SPARQL grammar). SPARQL operators can be used to compare the values of typed literals:

PREFIX a:      <http://www.w3.org/2000/10/annotation-ns#>
PREFIX dc:     <http://purl.org/dc/elements/1.1/>
PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>

SELECT ?annot
WHERE { ?annot  a:annotates  <http://www.w3.org/TR/rdf-sparql-query/> .
        ?annot  dc:date      ?date .
        FILTER ( ?date > "2005-01-01T00:00:00Z"^^xsd:dateTime ) }

The SPARQL operators are listed in section 17.3 and are associated with their productions in the grammar.

In addition, SPARQL provides the ability to invoke arbitrary functions, including a subset of the XPath casting functions, listed in section 17.5. These functions are invoked by name (an IRI) within a SPARQL query. For example:

... FILTER ( xsd:dateTime(?date) < xsd:dateTime("2005-01-01T00:00:00Z") ) ...

Typographical convention in this section: XPath operators are labeled with the prefix op:. XPath operators have no namespace; op: is a labeling convention.

Operand Data Types

SPARQL functions and operators operate on RDF terms and SPARQL variables. A subset of these functions and operators are taken from the XQuery 1.0 and XPath 2.0 Functions and Operators [XQuery 1.0 and XPath 2.0 Functions and Operators] and have XML Schema typed value arguments and return types. RDF typed literals passed as arguments to these functions and operators are mapped to XML Schema typed values with a string value of the lexical form and an atomic datatype corresponding to the datatype IRI . The returned typed values are mapped back to RDF typed literals the same way.

SPARQL has additional operators which operate on specific subsets of RDF terms. When referring to a type, the following terms denote a typed literal with the corresponding XML Schema [XML Schema Part 2: Datatypes Second Edition] datatype IRI :

xsd:integer
xsd:decimal
xsd:float
xsd:double
xsd:string
xsd:boolean
xsd:dateTime

The following terms identify additional types used in SPARQL value tests:

numeric denotes typed literals with datatypes xsd:integer, xsd:decimal, xsd:float, and xsd:double.
simple literal denotes a plain literal with no language tag.
RDF term denotes the types IRI, literal, and blank node.
variable denotes a SPARQL variable.

The following types are derived from numeric types and are valid arguments to functions and operators taking numeric arguments:

SPARQL language extensions may treat additional types as being derived from XML schema datatypes.

XPath Constructor Functions

SPARQL imports a subset of the XPath constructor functions defined in XQuery 1.0 and XPath 2.0 Functions and Operators [XQuery 1.0 and XPath 2.0 Functions and Operators] in section 17.1 Casting from primitive types to primitive types. SPARQL constructors include all of the XPath constructors for the SPARQL operand datatypes plus the additional datatypes imposed by the RDF data model. Casting in SPARQL is performed by calling a constructor function for the target type on an operand of the source type.

XPath defines only the casts from one XML Schema datatype to another. The remaining casts are defined as follows:

Casting an IRI to an xsd:string produces a typed literal with a lexical value of the codepoints comprising the IRI, and a datatype of xsd:string.
Casting a simple literal to any XML Schema datatype is defined as the product of casting an xsd:string with the string value equal to the lexical value of the literal to the target datatype.

The table below summarizes the casting operations that are always allowed ( Y ), never allowed ( N ) and dependent on the lexical value ( M ). For example, a casting operation from an xsd:string (the first row) to an xsd:float (the second column) is dependent on the lexical value ( M ).

bool = xsd:boolean
dbl = xsd:double
flt = xsd:float
dec = xsd:decimal
int = xsd:integer
dT = xsd:dateTime
str = xsd:string
IRI = IRI
ltrl = simple literal

From \ To	str	flt	dbl	dec	int	dT	bool
str	Y	M	M	M	M	M	M
flt	Y	Y	Y	M	M	N	Y
dbl	Y	Y	Y	M	M	N	Y
dec	Y	Y	Y	Y	Y	N	Y
int	Y	Y	Y	Y	Y	N	Y
dT	Y	N	N	N	N	Y	N
bool	Y	Y	Y	Y	Y	N	Y
IRI	Y	N	N	N	N	N	N
ltrl	Y	M	M	M	M	M	M

Extensible Value Testing

It should be noted that any function or operator that is specified to return an error under some conditions is a valid extension point. That is, an implementation may return a non-error value in these error cases, and still be conformant with this recommendation.

A PrimaryExpression grammar rule can be a call to an extension function named by an IRI. An extension function takes some number of RDF terms as arguments and returns an RDF term. The semantics of these functions are identified by the IRI that identifies the function.

SPARQL queries using extension functions are likely to have limited interoperability.

As an example, consider a function called func:even:

xsd:boolean   func:even (numeric value)

This function would be invoked in a FILTER as such:

PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX func: <http://example.org/functions#>
SELECT ?name ?id
WHERE { ?x foaf:name  ?name ;
           func:empId   ?id .
        FILTER (func:even(?id)) }

For a second example, consider a function aGeo:distance that calculates the distance between two points, which is used here to find the places near Grenoble:

xsd:double   aGeo:distance (numeric x1, numeric y1, numeric x2, numeric y2)

PREFIX aGeo: <http://example.org/geo#>

SELECT ?neighbor
WHERE { ?a aGeo:placeName "Grenoble" .
        ?a aGeo:locationX ?axLoc .
        ?a aGeo:locationY ?ayLoc .

        ?b aGeo:placeName ?neighbor .
        ?b aGeo:locationX ?bxLoc .
        ?b aGeo:locationY ?byLoc .

        FILTER ( aGeo:distance(?axLoc, ?ayLoc, ?bxLoc, ?byLoc) < 10 ) .
      }

An extension function might be used to test some application datatype not supported by the core SPARQL specification, it might be a transformation between datatype formats, for example into an XSD dateTime RDF term from another date format.