Update Module

This XQuery Module provides additional functions for performing updates and returning results in updating expressions.

Conventions

All functions in this module are assigned to the http://basex.org/modules/update namespace, which is statically bound to the update prefix.

Except for update:output-cache, all functions are updating and thus comply to the XQuery Update constraints.

Updates

update:apply

Signature	update:apply( $function as function(*), $arguments as array(*) ) as empty-sequence()
Summary	The updating variant of fn:apply applies the specified updating $function to the specified $arguments.
Examples	Creates a new database with an initial document and adds a document to an existing database. <syntaxhighlight lang="xquery"> declare %updating function local:update( $database as xs:string, $path as xs:string, $function as %updating function(item(), xs:string) as empty-sequence() ) as empty-sequence() { update:apply($function, [ $database, $path ]) }; local:update('new-db', 'doc.xml', db:create#2), local:update('existing-db', 'doc.xml', db:add#2) </syntaxhighlight>

update:for-each

Signature	update:for-each( $input as item()* $action as function(item()) ) as empty-sequence()
Summary	The updating variant of fn:for-each applies the specified updating $action to every item of $input.
Examples	Creates two databases: <syntaxhighlight lang="xquery"> let $names := ('db1', 'db2') return update:for-each($names, db:create#1) </syntaxhighlight>

update:for-each-pair

Signature	update:for-each-pair( $input1 as item()*, $input2 as item()*, $action as function(item()) ) as empty-sequence()
Summary	The updating variant of fn:for-each-pair applies the specified updating $action to the successive pairs of items of $input1 and $input2. Evaluation is stopped if one sequence yields no more items.
Examples	Renames nodes in an XML snippets: <syntaxhighlight lang="xquery"> copy $xml := <xml><a/></xml> modify update:for-each-pair( ('a', 'b'), ('d', 'e'), function($source, $target) { for $e in $xml/*[name() = $source] return rename node $e as $target } ) return $xml </syntaxhighlight>

update:map-for-each

Signature	update:map-for-each( $map as map(*), $action as function(xs:anyAtomicType, item()*) as item()* ) as item()*
Summary	The updating variant of map:for-each applies the specified $action to every key/value pair of the supplied $map and returns the results as a sequence.
Examples	Inserts attributes into a document: <syntaxhighlight lang="xquery"> copy $doc := <xml/> modify update:map-for-each( map { 'id': 'id0', 'value': 456 }, function($key, $value) { insert node attribute { $key } { $value } into $doc } ) return $doc</syntaxhighlight>

Output

update:output

Signature	update:output( $input as item()* ) as empty-sequence()
Summary	This function can be used if MIXUPDATES is not enabled, and if values need to be returned within an updating expression: The supplied $input will be cached and returned at the very end, i.e., after all updates on the pending update list have been processed. If one of the supplied items is affected by an update, a copy will be created and cached instead.
Examples	update:output("Prices have been deleted."), delete node //price deletes all price elements in a database and returns an info message.

update:cache

Signature	update:cache( $reset as xs:boolean := () ) as item()*
Summary	Returns the items that have been cached by update:output. The output cache can optionally be $reset. The function can be used to check which items will eventually be returned as result of an updating function. This function is non-deterministic: It will return different results before and after items have been cached. It is e. g. useful when writing unit tests.

Changelog

Version 9.3

• update:cache: $reset parameter added.

Version 9.1

• update:output: Maps and arrays can be cached if they contain no persistent database nodes or function items.

Version 9.0

• Updated: db:output renamed to update:output, db:output-cache renamed to update:cache

This module was introduced with Version 9.0.