Difference between revisions of "XQuery Update"

From BaseX Documentation
Jump to navigation Jump to search
(40 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
language. These are stated in the [[Update#Concepts|Concepts]] paragraph.
 
language. These are stated in the [[Update#Concepts|Concepts]] paragraph.
  
==Features==
+
=Features=
 +
 
 +
==Updating Expressions==
  
===Updating 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.
 
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.
 
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.
  
====insert====
+
===insert===
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 26: Line 27:
 
''Note'': in most cases, '''as last''' and '''after''' will be evaluated faster than '''as first''' and '''before'''!
 
''Note'': in most cases, '''as last''' and '''after''' will be evaluated faster than '''as first''' and '''before'''!
  
====delete====
+
===delete===
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
delete node //node
+
delete node //n
 
</pre>
 
</pre>
  
The example query deletes all <code><node></code> elements in your database. Note that, in contrast to other updating expressions, the delete expression allows multiple nodes as a target.
+
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===
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 48: Line 49:
 
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.
 
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====
+
===rename===
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
for $n in //node
+
for $n in //originalNode
 
return rename node $n as 'renamedNode'  
 
return rename node $n as 'renamedNode'  
 
</pre>
 
</pre>
  
All node 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.
+
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.
  
===Non-Updating Expressions===
+
==Non-Updating Expressions==
  
====transform====
+
===copy/modify/return===
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
copy $c := doc('example.xml')//node[@id = 1]
+
copy $c := doc('example.xml')//originalNode[@id = 1]
 
modify rename node $c as 'copyOfNode'
 
modify rename node $c as 'copyOfNode'
 
return $c
 
return $c
 
</pre>
 
</pre>
  
The node 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 <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:
 
The following example demonstrates a common use case:
Line 91: Line 92:
 
<pre class="brush:xml">
 
<pre class="brush:xml">
 
<entry>
 
<entry>
   <text>Copy of: Transform expression example</text>
+
   <title>Copy of: Transform expression example</title>
 
   <author>BaseX</author>
 
   <author>BaseX</author>
 
   <author>Joey</author>
 
   <author>Joey</author>
Line 121: Line 122:
 
</pre>
 
</pre>
  
====update====
+
===update===
  
{{Mark|Introduced with Version 7.8:}}
+
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 first
 +
expression is bound as context item, and the second expression performs updates on this item.
 +
The updated item is returned as result:
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 130: Line 136:
 
</pre>
 
</pre>
  
The {{Code|update}} expression is a convenience operator for writing simple transform expressions.
+
* More than one node can be specified as source:
Similar to the [[XQuery 3.0#Simple Map Operator|XQuery 3.0 map operator]], the value of the first
+
 
expression is bound as context item, and the second expression performs updates on this item.
+
<pre class="brush:xquery">
The updated item is returned as result. The first example of the [[#transform|transform]]
+
db:open('data')//item update delete node text()
expression.
+
</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|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 class="brush:xquery">
 +
<xml>text</xml> transform with {
 +
  replace value of node . with 'new-text'
 +
}
 +
</pre>
 +
 
 +
==Functions==
 +
 
 +
===Built-in Functions===
 +
 
 +
{{Code|fn:put()}} is can be used 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 query.
  
Please note that {{Code|update}} is not part of the official XQuery Update Facility yet.
+
Additional [[Database Module#Updates|database functions]] exist for performing updates on document and database level.
It is currently being discussed in the [https://www.w3.org/Bugs/Public/show_bug.cgi?id=23643 W3 Bug Tracker].
 
  
===Functions===
+
===User-Defined Functions===
  
====fn:put====
+
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:
  
{{Code|fn:put()}} 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 query.
+
<pre class="brush:xquery">
 +
let $node := <node>TO-BE-DELETED</node>
 +
let $delete-text := %updating function($node) {
 +
  delete node $node//text()
 +
}
 +
return $node update (
 +
  updating $delete-text(.)
 +
)
 +
</pre>
  
====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==
 
 
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.
 
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.
  
===Pending Update List===
+
==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. At the end of a query, after some consistency checks and optimizations, the update primitives will be applied in the following order:
 
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:
  
<pre class="brush:xml">
+
* '''Backups (1)''': {{Code|db:create-backup()}}
insert
+
* '''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|put}}
insert into
+
* '''Documents''': {{Code|db:add()}}, {{Code|db:store()}}, {{Code|db:replace()}}, {{Code|db:rename()}}, {{Code|db:delete()}}, {{Code|db:optimize()}}, {{Code|db:flush()}},
insert into last
+
* '''Users''': {{Code|user:grant()}}, {{Code|user:password()}}, {{Code|user:drop()}}, {{Code|user:alter()}}, {{Code|user:create()}}
insert attribute
+
* '''Databases''': {{Code|db:copy()}}, {{Code|db:drop()}}, {{Code|db:alter()}}, {{Code|db:create()}}
insert into first
+
* '''Backups (2)''': {{Code|db:restore()}}, {{Code|db:drop-backup()}}
replace value
 
rename
 
put
 
replace
 
delete
 
insert before
 
db:add()
 
db:store()
 
db:replace()
 
db:rename()
 
db:delete()
 
db:optimize()
 
db:flush()
 
db:drop()
 
db:create()
 
</pre>
 
  
 
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.
 
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.
  
It may be surprising to see <code>[[Database Module|db:create]]</code> on bottom 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 compiling and evaluating the query. As a result, {{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.
+
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.
  
====Example====
+
===Example===
  
 
The query…
 
The query…
Line 207: Line 229:
 
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.
 
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===
+
==Returning Results==
  
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. The only way to perform any updating queries and return a result at the same time is to use the BaseX-specific <code>[[Database Module#db:output|db:output()]]</code> function, which caches the results of its arguments at runtime and returns them after all updates have been processed.
+
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:
  
Example: Perform update and return success message.
+
* The BaseX-specific <code>[[Database Module#db:output|db: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 class="brush:xquery">
 
<pre class="brush:xquery">
Line 217: Line 239:
 
</pre>
 
</pre>
  
If you want to modify temporary nodes in main memory without storing them in a database, you can use the [[Update#transform|transform expression]].
+
* With the [[Options#MIXUPDATES|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.
 
 
===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:
+
If you want to modify nodes in main memory, you can use the [[Update#transform|transform expression]].
 
 
<pre class="brush:xquery">
 
declare %updating function { ... }
 
</pre>
 
  
 
==Effects==  
 
==Effects==  
  
===Original Files===
+
==Original Files==
  
In BaseX, all updates are performed on database nodes or in main memory. By default, update operations never affect the original input file. The following solutions exist to write XML documents and binary resources to disk:
+
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#WRITEBACK|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|fn:put]]</code> or <code>[[File Module#file:write|file:write]]</code> can be used to write single XML documents to disk. With <code>[[File Module#file:write-binary|file:write-binary]]</code>, you can write binary resources.
 
* The [[Commands#EXPORT|EXPORT]] command can be used write all resources of a databases to disk.
 
* The [[Commands#EXPORT|EXPORT]] command can be used write all resources of a databases to disk.
* Functions like <code>[[#fn:put|fn:put]]</code> or <code>[[File Module#file:write|file:write]]</code> can be used to write single XML documents to disk. With <code>[[File Module#file:write-binary|file:write-binary]]</code>, you can write binary resources.
 
* 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#WRITEBACK|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.
 
  
===Indexes===
+
==Indexes==
  
 
Index structures are discarded after update operations when [[Options#UPDINDEX|UPDINDEX]] is turned off (which is the default).
 
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]].
 
More details are found in the article on [[Index#Updates|Indexing]].
  
==Error Messages==
+
=Error Messages=
  
 
Along with the Update Facility, a number of new error codes and messages have been added
 
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
 
to the specification and BaseX. All errors are listed in the
 
[[XQuery Errors#Update Errors|XQuery Errors]] overview.
 
[[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=
 
=Changelog=
 +
 +
;Version 8.5
 +
* Added: [[#transform with|transform with]]
 +
* Updated: [[#update|update]] was extended.
 +
 +
;Version 8.0
 +
* Added: <code>MIXUPDATES</code> option for [[#Returning Results|Returning Results]] in updating expressions
 +
* Added: information message if files are not written back
  
 
;Version 7.8
 
;Version 7.8
* Added: [[#update|update]]
+
* Added: [[#update|update]] convenience operator

Revision as of 13:57, 16 January 2017

This article is part of the XQuery Portal. It summarizes the update features of BaseX.

BaseX offers a complete implementation of the 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, a few problems are addressed that frequently arise due to the nature of the language. These are stated in the Concepts paragraph.

Features

Updating Expressions

There are five new expressions to modify data. While insert, delete, rename and replace are basically self-explanatory, the 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.

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.

Note: in most cases, as last and after will be evaluated faster than as first and before!

delete

delete node //n

The example query deletes all <n> 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 <a/>. 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 originalNode 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.

Non-Updating Expressions

copy/modify/return

copy $c := doc('example.xml')//originalNode[@id = 1]
modify rename node $c as 'copyOfNode'
return $c

The originalNode element with @id=1 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 XQUF Concepts section.

The following example demonstrates a common use case:

Query:

copy $c :=
  <entry>
    <title>Transform expression example</title>
    <author>BaseX Team</author>
  </entry>
modify (
  replace value of node $c/author with 'BaseX',
  replace value of node $c/title with concat('Copy of: ', $c/title),
  insert node <author>Joey</author> into $c
)
return $c

Result:

<entry>
  <title>Copy of: Transform expression example</title>
  <author>BaseX</author>
  <author>Joey</author>
</entry>

The <entry> 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.

Here is an example where we return an entire document, parts modified and all:

copy $c := doc("zaokeng.kml")
modify (
  for $d in $c//*:Point
  return insert node (
    <extrude>1</extrude>,
    <altitudeMode>relativeToGround</altitudeMode>
  )  before $d/*:coordinates
)
return $c

update

The update expression is a BaseX-specific convenience operator for the copy/modify/return construct:

expression is bound as context item, and the second expression performs updates on this item. 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 .
} update {
  insert node "text" into child
}

transform with

The transform with expression was added to the current XQuery Update 3.0 working draft. It is a simple version of the update expression and also available in BaseX:

<xml>text</xml> transform with {
  replace value of node . with 'new-text'
}

Functions

Built-in Functions

fn:put() is can be used 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 query.

Additional database functions exist for performing updates on document and database level.

User-Defined Functions

If an updating function item is called, the function call must be prefixed with the keyword 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) {
  delete node $node//text()
}
return $node update (
  updating $delete-text(.)
)

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

Concepts

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.

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. At the end of a query, after some consistency checks and optimizations, the update primitives will be applied in the following order:

  • Backups (1): db:create-backup()
  • XQuery Update: insert before, delete, replace, rename, replace value, insert attribute, insert into first, insert into, insert into last, insert, insert after, put
  • Documents: db:add(), db:store(), db:replace(), db:rename(), db:delete(), db:optimize(), db:flush(),
  • Users: user:grant(), user:password(), user:drop(), user:alter(), user:create()
  • Databases: db:copy(), db:drop(), db:alter(), db:create()
  • Backups (2): db:restore(), 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.

It may be surprising to see db:create 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, db:create is mainly useful in the context of Command Scripts, or Web Applications, in which a redirect to another page can be triggered after having created a database.

Example

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 <doc/>, the former <a/> element is the only one to be renamed. The 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 expression of a query must either be a collection of updating or non-updating expressions. But there are two ways out:

  • The BaseX-specific db:output() 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:
db:output("Update successful."), insert node <c/> into doc('factbook')/mondial
  • With the 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 transform expression.

Effects

Original Files

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 fn:doc or fn:collection will be propagated back to disk when the WRITEBACK option is turned on. This option can also be activated on command line via -u. Make sure you back up the original documents before running your queries.
  • Functions like fn:put or file:write can be used to write single XML documents to disk. With file:write-binary, you can write binary resources.
  • The EXPORT command can be used write all resources of a databases to disk.

Indexes

Index structures are discarded after update operations when UPDINDEX is turned off (which is the default). More details are found in the article on Indexing.

Error Messages

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 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 8.5
Version 8.0
  • Added: MIXUPDATES option for Returning Results in updating expressions
  • Added: information message if files are not written back
Version 7.8
  • Added: update convenience operator