SAXONICA

Saxon Documentation
Full Contents
About Saxon
Changes in this Release
Notices
Using XSLT 2.0
Using XQuery
| Introduction
| Running XQuery from the Command Line
| Running Queries from a Java Application
» | Using XQuery Update
| Calling XQuery Functions from Java
| Result Format
| Compiling Queries to Java code
| Extensibility
| Extensions
| Use Cases
Handling Source Documents
XML Schema Processing
XPath API for Java
Saxon on .NET
Extensibility
Saxon Extensions
Sample Saxon Applications
The Saxon SQL Extension
XSLT Elements
XPath 2.0 Expression Syntax
Function Library
Standards Conformance

# Using XQuery Update

From release 9.1, Saxon-SA supports use of the update extensions to XQuery defined in http://www.w3.org/TR/xquery-update-10/. The current version supported is the Candidate Recommendation.

Update is available only in Saxon-SA, and is supported only if explicitly requested. The command line has an option `update:on` for this purpose, and all the XQuery APIs have an option to enable updating, which must be set before compiling the query. If this option is not set, the parser will not recognize update syntax, and any use of updating expressions will trigger a syntax error.

It is possible for an update to modify the document supplied as the context item, or a document read using the `doc()` or `collection()` function, or even a document constructed dynamically by the query itself. When using the various APIs, the general policy is that updated documents are never written automatically to disk. Instead, the list of updated documents is available to the application on completion of the query, and the application can decide whether to save the documents to their original location, or to some other location. Documents that were originally read from disk will have a document URI property which can be used to decide where to write them back.

When using XQuery Update from the command line, updated documents will be written back to disk if they have a known document URI, and if that URI is an updatable location (which in practice means it must be a URI that uses the `file://` scheme). For testing purposes, the write-back can be suppressed by using `-update:discard`. There is also a `-backup` option to control whether the old file is saved under a different name before being overwritten.

Saxon does no locking to prevent multiple threads attempting to update the same document. This is entirely a user responsibility.

Most errors that can arise during updating operations (for example, inserting two conflicting attributes) will cause an exception, with the supplied input document in memory being left in its original state. However, errors detected during the validation phase (that is, when the updated document is invalid against the schema, assuming revalidation is requested) are non-recoverable; after such a failure, the state of the document is unpredictable. Generally the (invalid) updates will have been made, and some of the updates done during schema validation (setting type annotations and default values) may also have been made.

Note that updates to a document will fail unless it is implemented using the Linked Tree model. This can be selected from the command line using `-tree:linked`, or via configuration settings in the API. It is not at present possible to update the Tiny Tree, nor external object models such as DOM, JDOM, or XOM.

Next