Changes

It summarizes the update features of BaseX.

=Features=

===insert===

insert node (attribute { 'a' } { 5 }, 'text', <e/>) into /n

Insert enables you to insert a sequence of nodes into a single target node. Several modifiers are available to specify the exact insert location: insert into '''as first'''/'''as last''', insert '''before'''/'''after''' and insert '''into'''.

===delete===

delete node //n

The example query deletes all <code><n></code> elements in your database. Note that, in contrast to other updating expressions, the delete expression allows multiple nodes as a target.

===replace===

replace node /n with <a/>

The target element is replaced by the DOM node <code><a/></code>. You can also replace the value of a node or its descendants by using the modifier '''value of'''.

replace value of node /n with 'newValue'

All descendants of /n are deleted and the given text is inserted as the only child. Note that the result of the insert sequence is either a single text node or an empty sequence. If the insert sequence is empty, all descendants of the target are deleted. Consequently, replacing the value of a node leaves the target with either a single text node or no descendants at all.

===rename===

for $n in //originalNode

return rename node $n as 'renamedNode'

All <code>originalNode</code> elements are renamed. An iterative approach helps to modify multiple nodes within a single statement. Nodes on the descendant- or attribute-axis of the target are not affected. This has to be done explicitly as well.

===copy/modify/return===

copy $c := doc('example.xml')//originalNode[@id = 1]

modify rename node $c as 'copyOfNode'

return $c

The <code>originalNode</code> element with <code>@id=1</code> is copied and subsequently assigned a new QName using the rename expression. Note that the transform expression is the only expression which returns an actual XDM instance as a result. You can therefore use it to modify results and especially DOM nodes. This is an issue beginners are often confronted with. More on this topic can be found in the [[Update#Returning Results|XQUF Concepts]] section.

Query:

copy $c :=

<entry>

)

return $c

Result:

<entry>

<title>Copy of: Transform expression example</title>

<author>Joey</author>

</entry>

The <code><entry></code> element (here it is passed to the expression as a DOM node) can also be replaced by a database node, e.g.:

copy $c := (db:open('example')//entry)[1]

...

In this case, the original database node remains untouched as well, as all updates are performed on the node copy.

and all:

copy $c := doc("zaokeng.kml")

modify (

)

return $c

===update===

The updated item is returned as result:

for $item in db:open('data')//item

return $item update delete node text()

* More than one node can be specified as source:

db:open('data')//item update delete node text()

* If wrapped with curly braces, update expressions can be chained:

<root/> update {

insert node <child/> into .

insert node "text" into child

}

===transform with===

The {{Code|transform with}} expression was added to the current [https://www.w3.org/TR/xquery-update-30/#id-transform-with XQuery Update 3.0] working draft. It is a simple version of the [[#update|update]] expression and also available in BaseX:

<xml>text</xml> transform with {

replace value of node . with 'new-text'

}

==Functions==

If an updating function item is called, the function call must be prefixed with the keyword {{Code|updating}}. This ensures that the query compiler can statically detect if an invoked function item will perform updates or not:

let $node := <node>TO-BE-DELETED</node>

let $delete-text := %updating function($node) {

updating $delete-text(.)

)

As shown in the example, user-defined and anonymous functions can additionally be annotated as {{Code|%updating}}.

The query…

insert node <b/> into /doc,

for $n in /doc/child::node()

return rename node $n as 'justRenamed'

…applied on the document…

<doc> <a/> </doc>

…results in the following document:

<doc> <justRenamed/><b/> </doc>

Despite explicitly renaming all child nodes of {{Code|<doc/>}}, the former {{Code|<a/>}} element is the only one to be renamed. The {{Code|<b/>}} element is inserted within the same snapshot and is therefore not yet visible to the user.

* The BaseX-specific <code>[[Update Module#update:output|update:output()]]</code> function bridges this gap: it caches the results of its arguments at runtime and returns them after all updates have been processed. The following example performs an update and returns a success message:

update:output("Update successful."), insert node <c/> into doc('factbook')/mondial

* With {{Option|MIXUPDATES}}, all updating constraints will be turned off. Returned nodes will be copied before they are modified by updating expressions. An error is raised if items are returned within a transform expression.