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.

See also the free text search page.

Applications can also provide their own functions. More functions and property functions will be added to the ARQ library. Contributions welcome.

 

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: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 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: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
   ...
}

Property Function 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 list:member member Membership of an RDF List (RDF Collection). If list is not bound or a constant, find and iterate all lists in the graph (can be slow) else evaluate for one particular list. If 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.
list list:index (index member) Index of an RDF List (RDF Collection). If list is not bound or a constant, find and iterate all lists in the graph (can be slow) else evaluate for one particular list. The object is a list pair, either element can be bound, unbound or a fixed node. Unbound variables in the object list are bound by the property function.
list list:length length Length of an RDF List (RDF Collection). If list is not bound or a constant, find and iterate all lists in the graph (can be slow) else evaluate for one particular list. The object is tested against or bound to the length of the list.
container rdfs:member member Membership of an RDF Container (rdf:Bag, rdf:Seq, rdf:Alt). Pre-registered URI. If this infers with queries running over a Jena inference model which also provides rdfs:member, then remove this from the global registry.
  PropertyFunctionRegistry.get().
      remove(RDFS.member.getURI()) ;
apf:textMatch Free text match.  See the free text search page for details.
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.
varOrTerm apf:assign varOrTerm Assign an RDF term from one side to the other.  If both are fixed RDF terms or bound variables, it becomes a boolean test that the subject is the same RDF term as the object.
iri apf:splitIRI (namespace  localname)
iri apf:splitURI (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. The object is a list with 2 elements.
splitURI is an synonym.
subject apf:blankNode label
subject apf:bnode label
 		 Subject must be bound to a blank node or a constant. Label is either a string, in which case test for whether this is the blank node label of subject, or it is a variable, which is assigned the blank node label as a plain string. Argument mismatch causes no match. Use with care.

ARQ Documentation Page