Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
m
The most important thing to keep in mind when using {{Announce|Updated with Version 10}}: {{Function|Database|db:put-binary}} is executed before standard XQuery Update is the Pending Update List (PUL)expressions. 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:
Text replacement - "db:pre(" to "db:get("
It summarizes the update features of BaseX.
BaseX offers a complete implementation of the [httphttps://www.w3.org/TR/xquery-update-10/ XQuery Update Facility (XQUF)]. This article aims to provide a very quick and basic introduction to the XQUF. First, some examples for update expressions are given. After that, the challenges are addressed that arise due to the functional semantics of the language. These are stated in the [[Update#Concepts|Concepts]] paragraph.
=Features=
===insert===
<pre classsyntaxhighlight lang="brush:xquery">
insert node (attribute { 'a' } { 5 }, 'text', <e/>) into /n
</presyntaxhighlight>
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===
<pre classsyntaxhighlight lang="brush:xquery">
delete node //n
</presyntaxhighlight>
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===
<pre classsyntaxhighlight lang="brush:xquery">
replace node /n with <a/>
</presyntaxhighlight>
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'''.
<pre classsyntaxhighlight lang="brush:xquery">
replace value of node /n with 'newValue'
</presyntaxhighlight>
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===
<pre classsyntaxhighlight lang="brush:xquery">
for $n in //originalNode
return rename node $n as 'renamedNode'
</presyntaxhighlight>
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.
==NonMain-Updating ExpressionsMemory Updates==
===copy/modify/return===
<pre classsyntaxhighlight lang="brush:xquery">
copy $c := doc('example.xml')//originalNode[@id = 1]
modify rename node $c as 'copyOfNode'
return $c
</presyntaxhighlight>
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:
<pre classsyntaxhighlight lang="brush:xquery">
copy $c :=
<entry>
)
return $c
</presyntaxhighlight>
Result:
<pre classsyntaxhighlight lang="brush:xml">
<entry>
<title>Copy of: Transform expression example</title>
<author>Joey</author>
</entry>
</presyntaxhighlight>
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.:
<pre classsyntaxhighlight lang="brush:xquery">copy $c := (db:openget('example')//entry)[1]
...
</presyntaxhighlight>
In this case, the original database node remains untouched as well, as all updates are performed on the node copy.
and all:
<pre classsyntaxhighlight lang="brush:xquery">
copy $c := doc("zaokeng.kml")
modify (
)
return $c
</presyntaxhighlight>
===update===
{{Announce|Updated with Version 10:}} Curly braces are now mandatory.
The {{Code|update}} expression is a BaseX-specific convenience operator for the {{Code|copy/modify/return}}
The updated item is returned as result:
<pre classsyntaxhighlight lang="brush:xquery">for $item in db:openget('data')//itemreturn $item update { delete node text()}</presyntaxhighlight>
* More than one node can be specified as source:
<pre classsyntaxhighlight lang="brush:xquery">db:openget('data')//item update { delete node text()}</presyntaxhighlight>
* If wrapped with curly braces, update expressions can be chained:
<pre classsyntaxhighlight lang="brush:xquery">
<root/> update {
insert node <child/> into .
insert node "text" into child
}
</presyntaxhighlight>
===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:
<pre classsyntaxhighlight lang="brush:xquery">
<xml>text</xml> transform with {
replace value of node . with 'new-text'
}
</presyntaxhighlight>
==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:
<pre classsyntaxhighlight lang="brush:xquery">
let $node := <node>TO-BE-DELETED</node>
let $delete-text := %updating function($node) {
updating $delete-text(.)
)
</presyntaxhighlight>
As shown in the example, user-defined and anonymous functions can additionally be annotated as {{Code|%updating}}.
==Pending Update List==
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. After the evaluation of the query, and after some consistency checks and optimizations, the update primitives will be applied in the following order: * '''Backups (1), Binary resources''': {{CodeFunction|Database|db:alter-backup}}, {{Function|Database|db:create-backup()}}, {{Function|Database|db:put}}, {{Function|Database|db:put-binary}}* '''XQuery Update''': {{Code|insert before}}, {{Code|delete}}, {{Code|replace}}, {{Code|rename}}, {{Code|replace value}}, {{Code|insert attribute}}, {{Code|insert into first}}, {{Code|insert into}}, {{Code|insert into last}}, {{Code|insert}}, {{Code|insert after}}, {{Code|fn:put}}* '''Documents''': {{CodeFunction|Database|db:add()}}, {{CodeFunction|Database|db:store()put}}, {{CodeFunction|db:replace()}}, {{CodeDatabase|db:rename()}}, {{CodeFunction|Database|db:delete()}}, {{CodeFunction|Database|db:optimize()}}, {{CodeFunction|Database|db:flush()}},* '''Users''': {{CodeFunction|User|user:grant()}}, {{CodeFunction|User|user:password()}}, {{CodeFunction|User|user:drop()}}, {{CodeFunction|User|user:alter()}}, {{CodeFunction|User|user:create()}}* '''Databases''': {{CodeFunction|Database|db:copy()}}, {{CodeFunction|Database|db:drop()}}, {{CodeFunction|Database|db:alter()}}, {{CodeFunction|Database|db:create()}}* '''Backups (2)''': {{CodeFunction|Database|db:restore()}}, {{CodeFunction|Database|db:drop-backup()}}
If an inconsistency is found, an error message is returned and all accessed databases remain untouched (atomicity). For the user, this means that updates are only visible '''after''' the end of a snapshot.
The query…
<pre classsyntaxhighlight lang="brush:xquery">
insert node <b/> into /doc,
for $n in /doc/child::node()
return rename node $n as 'justRenamed'
</presyntaxhighlight>
…applied on the document…
<pre classsyntaxhighlight lang="brush:xml">
<doc> <a/> </doc>
</presyntaxhighlight>
…results in the following document:
<pre classsyntaxhighlight lang="brush:xml">
<doc> <justRenamed/><b/> </doc>
</presyntaxhighlight>
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.
==Returning Results==
By default, it is not possible to mix different types of expressions in a query result. The outermost root expression of a query must either be a collection sequence of updating or non-updating expressions. But there are two ways out:
* The BaseX-specific <code>[[{{Function|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:
<pre classsyntaxhighlight lang="brush:xquery">
update:output("Update successful."), insert node <c/> into doc('factbook')/mondial
</presyntaxhighlight>
* With the [[Options#MIXUPDATES{{Option|MIXUPDATES]] option}}, 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.
If you want to modify nodes in main memory, you can use the [[Update#transform|transform expression]].
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:
* Updates on main-memory instances of files that have been retrieved via {{Code|fn:doc}} or {{Code|fn:collection}} will be propagated back to disk when the <code>[[Options#WRITEBACKif {{Option|WRITEBACK]]</code> option }} is turned on. This option can also be activated on [[Command-Line Options#BaseX Standalone|command line]] via <code>-u</code>. Make sure you back up the original documents before running your queries.* Functions like <code>[[#fn:put{{Code|fn:put]]</code> }} or <code>[[{{Function|File Module#file:write|file:write]]</code> }} can be used to write single XML documents to disk. With <code>[[{{Function|File Module#file:write-binary|file:write-binary]]</code>}}, you can write binary resources.* The [[Commands#EXPORT{{Command|EXPORT]] }} command can be used write all resources of a databases to disk.
==Indexes==
Index structures are discarded after update operations when [[Options#UPDINDEX{{Option|UPDINDEX]] }} is turned off (which is the default).
More details are found in the article on [[Index#Updates|Indexing]].
=Error Messages=
Along with the Update Facility, a number of new error codes and messages have been addedto 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 All logical errors occur at this final stage, they cannot will be caught via try/catchraised before the updates are actually executed.
=Changelog=
;Version 10.0
* Updated: {{Function|Database|db:put-binary}} is executed before XQuery Update expressions.
* Updated: [[#update|update]]: Curly braces are now mandatory.
;Version 9.0
