Saxon home page

Using XQuery


This page describes how to use Saxon as an XQuery processor, either from the command line, or from the Java API.

Contents
Using XQuery Reference
Introduction
Running a Query from the Command Line
Embedding Saxon in an Application
Result Format
Use Cases
See also:
XPath Expressions
Function Library
Saxon Extensibility
XQuery Conformance

Introduction

Saxon, from release 7.6 onwards, supports XQuery as well as XSLT.

The run-time code for both languages is identical, reflecting the fact that they have very similar semantics. The XQuery support in Saxon consists essentially of an XQuery parser (which is itself an extension of the XPath parser); the parser generates the same internal intepretable code as the XSLT processor.

Since the XQuery support is very new, this may sometimes show through, for example in error messages.

The XQuery processor may be invoked either from the operating system command line, or via an API from a Java application. There is no graphical user interface provided.

Saxon is an in-memory processor. Whether you use XSLT or XQuery, Saxon is designed to process source documents that fit in memory. If you want to handle a large database, you need an XML database product such as Software AG's Tamino.

At this release, there is no interoperability between XSLT code and XQuery code. However, since the run-time representation is identical, this is clearly an opportunity for future releases. At the very least, I would expect to see the ability for XSLT functions and XQuery functions to call each other freely.


Running a Transformation from the Command Line

The Java class net.sf.saxon.Query has a main program that may be used to run a query contained in a file. The form of command is:

java  net.sf.saxon.Query   [options]   query   [ params…]

The options must come first, then the two file names, then the params.

The options are as follows (in any order):

-o filename Send output to named file. In the absence of this option, the results go to standard output. The query results are wrapped in XML tags in a Saxon-defined namespace, and the resulting document is then serialized using the XSLT-defined serializer.
-s filename-or-URI Take input from the specified file. If the -u option is specified, or if the name begins with "file://" or "http://", then the name is assumed to be a URI rather than a filename. This file must contain an XML document. The contents of the document are made available to the query as the context item and as the value of the input() function. The source document can be specified as "-" to take the source from standard input.
-r classname Use the specified URIResolver to process all URIs. The URIResolver is a user-defined class, that implements the URIResolver interface defined in JAXP, whose function is to take a URI supplied as a string, and return a SAX InputSource. It is invoked to process URIs used in the doc() function, and (if -u is also specified) to process the URI of the source file provided on the command line.
-t Display version and timing information to the standard error output. The output also traces the files that are read and writting, and extension modules that are loaded.
-TJ Switches on tracing of the binding of calls to external Java methods. This is useful when analyzing why Saxon fails to find a Java method to match an extension function call in the stylesheet, or why it chooses one method over another when several are available.
-u Indicates that the name of the source document is a URI; otherwise it is taken as a filename, unless it starts with "http:" or "file:", in which case they it is taken as a URL.
-?Display command syntax
query Identifies the file containing the query. Mandatory. The argument can be specified as "-" to read the query from standard input.

A param takes the form name=value, name being the name of the parameter, and value the value of the parameter. These parameters are accessible within the query as external variables, using the $name syntax, provided they are declared in the query prolog. If there is no such declaration, the supplied parameter value is silently ignored. Not yet tested.

A param preceded by a leading exclamation mark is interpreted as a serialization parameter. For example, !indent=yes requests indented output, and !encoding="iso-8859-1" requests that the serialized output be in ISO 8859/1 encoding. This is equivalent to specifying the attribute indent="yes" on an xsl:output declaration in an XSLT stylesheet.

Under Windows, and some other operating systems, it is possible to supply a value containing spaces by enclosing it in double quotes, for example name="John Smith". This is a feature of the operating system shell, not something Saxon does, so it may not work the same way under every operating system.

If the parameter name is in a non-null namespace, the parameter can be given a value using the syntax {uri}localname=value. Here uri is the namespace URI of the parameter's name, and localname is the local part of the name.

This applies also to output parameters. For example, you can set the indentation level to 4 by using the parameter !{http://saxon.sf.net/}indent-spaces=4. For the extended set of output parameters supported by Saxon, see extensions.html.


Embedding Saxon in an Application

Rather than using the query processor from the command line, you may want to include it in your own application, perhaps one that enables it to be used within an applet or servlet. If you run the processor repeatedly, this will always be much faster than running it each time from a command line, even if it handles a different query each time.

There is currently no standard API for XQuery, so I have invented one. It is fully described in the JavaDoc included in the download: look for the package net.sf.saxon.query. The starting point is the class QueryProcessor.


Result Format

The result of a query is a sequence of nodes and atomic values - which means it is not, in general, an XML document. This raises the question as to how the results should be output.

The Saxon command line processor for XQuery always wraps the result sequence as an XML document, and then serializes the resulting document. Each item in the result sequence is wrapped in an element (such as result:element or result:atomic-value) according to its type. The sequence as a whole is wrapped in a result:sequence element.

When a query is executed from a Java application, the result sequence can be processed any way you like. You can do the same wrapping if you wish, using the QueryResult object, but it is not essential. You can also, if you prefer, serialize any result documents or elements directly, again using the services of the QueryResult object.


Extensibility

The Saxon XQuery implementation allows you to call Java methods as external functions. The function does not need to be declared. Use a namespace declaration such as declare namespace math=java:java.lang.Math, and invoke the method as math:sqrt(2).

More details of this mechanism are found in Writing Extension Functions; note however that for XQuery the only form of namespace URI accepted is java:full.class.Name.

The full library of Saxon and EXSLT functions described in extensions.html is also available, except for those (such as saxon:serialize) that have an intrinsic dependency on an XSLT stylesheet.


Use Cases

Saxon 7.6 runs all the XQuery Use Cases with the exception of the STRONG use case, which is designed to exercise schema-aware query processors.

The relevant queries (some of which have been corrected from those published by W3C) are included in the Saxon distribution (folder use-cases) together with a batch script for running them. A few additional use cases have been added to show features that would otherwise not be exercised.


Michael H. Kay
22 June 2003