XQuery/Using XQuery Functions

Motivation

You would like to use an existing XQuery function. You need to be able to understand how functions work and how they are documented.

Method

The XQuery 1.0 specification has many built-in functions for handling strings, URIs and other data. To use a built-in function you need to know what its inputs are and their data types and what form of output it creates.

Understanding XQuery Parameters and Return Types

XQuery is a strongly typed language, so functions are usually carefully designed to work with a restricted set of data types. When you pass data into a function using a parameter, you must specify its type, using combinations of elements, nodes, items, sequences or any of the XML Schema data types. In addition to the data type, a suffix called an occurrence indicator, such as "+", "?" or "*", follows the data type to indicate whether a parameter is optional or could have multiple values. Here are the three occurrence indicators and their meanings:

• ? matches zero or one items
• * matches zero or more items
• + matches one or more items

Care should be taken to understand the difference between an argument as a single sequence and a repeating set of items.

There are around 111 built-in functions to the XQuery language, but many find that 10% of the XQuery functions are used 90% of the time. Here are some of the most commonly used functions:

 string-length($string as xs:string) as xs:integer - returns the length of a string as the number of its characters

Example: string-length("Hello") returns 5, since the string "Hello" is five characters long.

 concat($input as xs:anyAtomicType?) as xs:string - concatenates a list of strings together.

The function does not accept a sequence of values, just individual atomic values passed as separate arguments.

Example: concat('big', 'red', 'ball') returns "bigredball"

 string-join($sequence as xs:string*, $delimiter as xs:string) as xs:string - combines the items in a sequence, separating them with a delimiter

Example: string-join(('big', 'red', 'ball'), '-') returns "big-red-ball"

Note that string-join takes as its first argument a single sequence of items, whereas concat takes zero or more strings as arguments.

Sample data types

• xs:date refers to the built-in atomic schema type named xs:date
• attribute()? refers to an optional attribute node
• element() refers to any element node
• element(po:shipto, po:address) refers to an element node that has the name po:shipto and has the type annotation po:address (or a schema type derived from po:address)
• element(*, po:address) refers to an element node of any name that has the type annotation po:address (or a type derived from po:address)
• element(customer) refers to an element node named customer with any type annotation
• schema-element(customer) refers to an element node whose name is customer (or is in the substitution group headed by customer) and whose type annotation matches the schema type declared for a customer element in the in-scope element declarations
• node()* refers to a sequence of zero or more nodes of any kind
• item()+ refers to a sequence of one or more nodes or atomic values

Returning Results

Each XQuery function you write will return a result.

In the following example, the input is a sequence of 0 to many nodes and the output is a sequence of 0 to many nodes.

(: input 0 to many nodes and return 0 to many nodes :)
declare function local:myFunction($input as node()*) as node()* {

In the following example, the input is a single required node and the output is a single required node.

(: input a single required nodes and return a single required node :)
declare function local:myFunction($input as node()) as node() {

In the following example, the input is a single optional node and the output is a single optional node.

(: input a single optional nodes and return a single optional node :)
declare function local:myFunction($input as node()?) as node()? {

Useful References

For the authoritative documentation of all the functions available in eXist, including those not defined in XQuery, see eXist XQuery Function Documentation

For detailed information about how to specify sequence types see XQuery Sequence Types

For the standard XQuery and XPath function library, you may also refer to XQuery 1.0 and XPath 2.0 Functions and Operators

See also the detailed documentation of functions with examples from noted XQuery expert Pricilla Walmsley in the FunctX XQuery Function Library