Functions in ARQ

SPARQL allows custom functions in filter expressions so that queries can be used on domain-specific data. SPARQL defines a function by URI (or prefixed name) in FILTER expressions.  ARQ provides a function library and supports application-provided functions.  Functions and extensions can be registered or dynamically loaded.

More functions will be added. Contributions welcome.

Applications can also provide their own functions.

Function Library

The prefix jfn is <java:com.hp.hpl.jena.query.function.library.>. Note the final dot in the prefix.

The prefix fn is <http://www.w3.org/2005/xpath-functions#> (the XPath and XQuery function namespace).

XQuery/XPath functions and operators supported

String Functions

Function name Description
fn:contains(string, substr) Test whether substr occurs in string.
fn:starts-with(string, match) Test whether string starts with substr.
fn:ends-with(string, match) Test whether string ends with substr.
fn:string-length(string) Return the length of a string.
fn:matches(string, pattern [, flags]) Regular expression match.
fn:string-join(string1, string2) Return the concatenation of two strings.

 
fn:substring(string, begin [,length]) Returns the substring of a string, given by begin  (integer) and, optionally, length length.  Absence of length means to end of string.  Strings are indexed from zero.
  • Strings start from one, not zero as they do in Java and C#.
  • 3rd argument is the length, like C# but unlike Java, where it is the endIndex.

Notes:

  1. Strings in "XQuery 1.0 and XPath 2.0 Functions and Operators" start from character position one, unlike Java and C# where strings start from zero.
  2. The fn:substring operation takes an optional length, like C# but different from Java, where it is the endIndex of the first character after the substring.

The operation jfn:substring provides Java semantics.

Mathematical Functions

Function name Description
fn:min(num1, num2) Return the minimum of two expressions evaluating to numbers.
fn:max(num1, num2) Return the maximum of two expressions evaluating to numbers.
fn:round(v) Return the nearest integer value to the argument.
fn:abs(v) Return the absolute value.
fn:floor(v) Return the greatest integer value less than the argument (as a double).
fn:ceiling(v) Return the smallest integer value than the argument (as a double).

Note: See also jfn:min and jfn:max for binary min and max functions.

Boolean Functions

Function name Description
fn:boolean(value) Boolean effective value of value.
fn:not(value) Logical negation of the boolean effective value of value.

Functions provided by ARQ

RDF Graph Functions

Function name Description
jfn:listMember(list, resource) Test whether a resource is a member of an RDF collection (AKA list)
jfn:listIndex(list, resource) Return the index of the resource in the RDF collection. Cause an evaluation exception if not a member (and so the expression will not pass the filter unless inside a value disjunction).
jfn:bagMember(bag, resource) Test whether a resource is a member of an RDF bag
jfn:seqMember(bag, resource) Test whether a resource is a member of an RDF seq
jfn:altMember(bag, resource) Test whether a resource is a member of an RDF alt
jfn:bnode(?x) Return the blank node label if ?x is a blank node.

String Functions

Function name Description
jfn:substr(string, startIndex [,endIndex]) Substring, Java style using startIndex and endIndex.
jfn:substring Synonym for jfn:substring
jfn:sha1sum(resource) Calculate the SHA1 checksum of a literal or URI.

Mathematical Functions

Function name Description
jfn:min(num1, num2) Return the minimum of two expressions evaluating to numbers.
jfn:max(num1, num2) Return the maximum of two expressions evaluating to numbers.

Miscellaneous Functions

Function name Description
jfn:now() Current time.  Actually, the time the query started.
jfn:sha1sum(resource) Calculate the SHA1 checksum of a literal or URI.

Debugging Functions

Debugging functions can be inserted into queries as extra FILTER clauses.  They don't affect query results (they always return true) but they print information that can be helpful in understanding what's happening.

Function name Description
jfn:print(expr, ...) Print the evaluated expressions. With no arguments, prints the current solution. Always returns true.
jfn:trace(expr) Print the expression with values substituted for variables if the variable is set and print result of evaluation, including whether there was an evaluation exception. Always returns true so it does not filter based on the expression.

Example:

{
   ...
   FILTER jfn:print() # Print the solution
   FILTER jfn:trace(expression) # Evaluate and print the expression
   FILTER expression # Now use the expression to filter solutions
   ...
}

Function Property Library

The library built-in to the ARQ distribution is loaded from <java:com.hp.hpl.jena.query.pfunction.library.>. Note the final dot in the prefix. In the table below, the prefix apf: is used for this.

The prefix list: is http://www.jena.hpl.hp.com/ARQ/list#.

Property name Description
list:member Membership of an RDF List (RDF Collection)
rdfs:member Membership of an RDF Container (rdf:Bag, rdf:Seq, rdf:Alt). Pre-registered URI.
Implemented by apf:conatiner, apf:seq and apf:alt as below.
iri apf:splitIRI (namespace  localname) Split the IRI or URI into namespace (an IRI) and local name (a string). Compare if given values or bound variables, otherwise set the variable.
splitURI is an synonym.
list apf:list member The argument list must be bound by this point in the query or a constant expression. If list is bound or a URI, and member a variable, generate solutions with member bound to each element in the list. If member is bound or a constant expression, test to see if a member of the list.
bag apf:bag member The argument bag must be bound by this point in the query or a constant expression. If bag is bound or a URI, and member a variable, generate solutions with member bound to each element in the bag. If member is bound or a constant expression, test to see if a member of the list.
seq apf:seq member The argument seq must be bound by this point in the query or a constant expression. If seq is bound or a URI, and member a variable, generate solutions with member bound to each element in the sequence. If member is bound or a constant expression, test to see if a member of the list.
seq apf:alt member The argument alt must be bound by this point in the query or a constant expression. If alt is bound or a URI, and member a variable, generate solutions with member bound to each element in the alt . If member is bound or a constant expression, test to see if a member of the list.

ARQ Documentation Page