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 property functions can be registered or dynamically loaded.

See also the free text search page.

See also the property functions library page.

Applications can also provide their own functions.

Function Library

The prefix afn is <http://jena.hpl.hp.com/ARQ/function#>. Note the final dot in the prefix.

Direct loading using a URI prefix of <java:com.hp.hpl.jena.sparql.function.library.> (note the final dot)

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:lower-case(string) Return a string which is the lower case equivalent of the argument.
fn:upper-case(string) Return a string which is the upper case equivalent of the argument.
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 afn: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 afn:min and afn: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
afn:bnode(?x) Return the blank node label if ?x is a blank node.
afn:localname(?x) The local name of ?x if a IRI. Based on splitting the IRI, not on any prefixes in the query or dataset.
afn:namespace(?x) The namespace of ?x if a IRI. Based on splitting the IRI, not on any prefixes in the query or dataset.

String Functions

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

Mathematical Functions

Function name Description
afn:min(num1, num2) Return the minimum of two expressions evaluating to numbers.
afn:max(num1, num2) Return the maximum of two expressions evaluating to numbers.
afn:pi() The value of pi, as an XSD double.
afn:e() The value of e, as an XSD double.

Miscellaneous Functions

Function name Description
afn:now() Current time.  Actually, the time the query started. Constant throughout a query execution.
afn: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
afn:print(expr, ...) Print the evaluated expressions. With no arguments, prints the current solution. Always returns true.
afn: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 afn:print() # Print the solution
   FILTER afn:trace(expression) # Evaluate and print the expression
   FILTER expression # Now use the expression to filter solutions
   ...
}

ARQ Documentation Page