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.

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.