Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
===Updating Expressions===
====insert====
====delete====
====replace====
====rename====
===Non-Updating Expressions===
====update==== The {{Code|update}} expression is a BaseX-specific convenience operator for the {{Code|copy/modify/return}}construct: * Similar to the [[XQuery 3.0#Simple Map Operator|XQuery 3.0 map operator]], the value of the firstexpression is bound as context item, and the second expression performs updates on this item.The updated item is returned as result:
Please note that {{CodeNumerous additional [[Database Module#Updates|update}} is not part of the official XQuery Update Facility yet.It is currently being discussed in the [https://www.w3.org/Bugs/Public/show_bug.cgi?id=23643 W3 Bug Trackerdatabase functions]];your feedback is welcomeexist for performing updates on document and database level.
====fnIf 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:put====
====Database Functions====As shown in the example, user-defined and anonymous functions can additionally be annotated as {{Code|%updating}}.
Some additional, updating [[Database Module#Updates|database functions]] exist in order to perform updates on document and database level.=Concepts=
==Concepts==
===Pending Update List===
====Example====
===Returning Results===
===Function Declaration===
To use updating expressions within a function, the {{Code|%updating}} annotation has to be added to the function declaration. A correct declaration of a function that contains updating expressions (or one that calls updating functions) looks like this:
<pre class="brush:xquery">
declare %updating function { ... }
</pre>
===Original Files===
===Indexes===
==Error Messages==
no edit summary
language. These are stated in the [[Update#Concepts|Concepts]] paragraph.
=Features= ==FeaturesUpdating Expressions==
There are five new expressions to modify data. While {{Code|insert}}, {{Code|delete}}, {{Code|rename}} and {{Code|replace}} are basically self-explanatory, the {{Code|transform}} expression is different, as modified nodes are copied in advance and the original databases remain untouched.
An expression consists of a target node (the node we want to alter) and additional information like insertion nodes, a QName, etc. which depends on the type of expression. Optional modifiers are available for some of them. You can find a few examples and additional information below.
<pre class="brush:xquery">
''Note'': in most cases, '''as last''' and '''after''' will be evaluated faster than '''as first''' and '''before'''!
<pre class="brush:xquery">
delete node //noden
</pre>
The example query deletes all <code><noden></code> elements in your database. Note that, in contrast to other updating expressions, the delete expression allows multiple nodes as a target.
<pre class="brush:xquery">
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.
<pre class="brush:xquery">
for $n in //nodeoriginalNode
return rename node $n as 'renamedNode'
</pre>
All node <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.
====transform=copy/modify/return===
<pre class="brush:xquery">
copy $c := doc('example.xml')//nodeoriginalNode[@id = 1]
modify rename node $c as 'copyOfNode'
return $c
</pre>
The node <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.
The following example demonstrates a common use case:
</pre>
<pre class="brush:xquery">
</pre>
* More than one node can be specified as source: <pre class="brush:xquery">db:open('data')//item update delete node text()</pre> * If wrapped with curly braces, update expressions can be chained: <pre class="brush:xquery"><root/> update { insert node <child/> into .} update { insert node "text" into child}</pre> ===transform with=== The {{Code|updatetransform with}} expression is a convenience operator for writing simple transform expressions.Similar 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 [[#Simple Map Operatorupdate|XQuery 3.0 map operatorupdate]], the expression and also availablein BaseX: <pre class="brush:xquery"><xml>text</xml> transform with { replace value of the firstnode . with 'new-text'}</pre> ==Functions== ===Built-in Functions=== expression {{Code|fn:put()}} is can be used to serialize XDM instances to secondary storage. It is bound as context item, and executed at the end of a snapshot. Serialized documents therefore reflect all changes made effective during a query. No files will be created if the second expression performs updates on this itemaddressed nodes have been deleted.The updated item is returned With {{Version|9.0}}, serialization parameters can be specified as resultthird argument (more details are found in the [https://www.w3.org/TR/xquery-update-30/#id-func-put XQUF 3.0 Specification]).
===User-Defined Functions===
<pre class="brush:xquery">let $node := <node>TO-BE-DELETED</node>let $delete-text := %updating function($node) {{Code|fn:put delete node $node//text()}} is also part of the XQUF and enables the user to serialize XDM instances to secondary storage. It is executed at the end of a snapshot. Serialized documents therefore reflect all changes made effective during a queryreturn $node update ( updating $delete-text(.))</pre>
There are a few specialties around XQuery Update that you should know about. In addition to the '''simple expression''', the XQUF adds the '''updating expression''' as a new type of expression. An updating expression returns only a Pending Update List (PUL) as a result which is subsequently applied to addressed databases and DOM nodes. A simple expression cannot perform any permanent changes and returns an empty or non-empty sequence.
The most important thing to keep in mind when using XQuery Update is the Pending Update List (PUL). Updating statements are not executed immediately, but are first collected as update primitives within a set-like structure. At the end of a query, after some consistency checks and optimizations, the update primitives will be applied in the following order:
It may be surprising to see <code>[[Database Module|db:create]]</code> in the lower part of this list. This means that newly created database cannot be accessed by the same query, which can be explained by the semantics of updating queries: all expressions can only be evaluated on databases that already exist while the query is evaluated. As a consequence, {{Code|db:create}} is mainly useful in the context of [[Commands#Basics|Command Scripts]], or [[Web Application]]s, in which a redirect to another page can be triggered after having created a database.
The query…
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.
By default, it is not possible to mix different types of expressions in a query result. The outermost expression of a query must either be a collection of updating or non-updating expressions. But there are two ways out:
If you want to modify nodes in main memory, you can use the [[Update#transform|transform expression]].
==Effects==
In BaseX, all updates are performed on database nodes or in main memory. By default, update operations do not affect the original input file (the info string "Updates are not written back" appears in the query info to indicate this). The following solutions exist to write XML documents and binary resources to disk:
* The [[Commands#EXPORT|EXPORT]] command can be used write all resources of a databases to disk.
Index structures are discarded after update operations when [[Options#UPDINDEX|UPDINDEX]] is turned off (which is the default).
More details are found in the article on [[Index#Updates|Indexing]].
Along with the Update Facility, a number of new error codes and messages have been added
to the specification and BaseX. All errors are listed in the
[[XQuery Errors#Update Errors|XQuery Errors]] overview.
Please remember that the collected updates will be executed after the query evaluation.
If errors occur at this final stage, they cannot be caught via try/catch.
=Changelog=
;Version 9.0
* Updated: [[#Built-in Functions|Built-in Functions]]: serialization parameters
;Version 8.5
* Added: [[#transform with|transform with]]
* Updated: [[#update|update]] was extended.
;Version 8.0
