Difference between revisions of "Update Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>")
 
(21 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/update</nowiki></code> namespace, which is statically bound to the {{Code|update}} prefix.<br/>
 
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/update</nowiki></code> namespace, which is statically bound to the {{Code|update}} prefix.<br/>
  
Except for [[#update:output-cache|update:output-cache]], all functions are ''updating'' and thus comply to the XQuery Update constraints.
+
Except for {{Function||update:output-cache}}, all functions are ''updating'' and thus comply to the XQuery Update constraints.
  
 
=Updates=
 
=Updates=
Line 12: Line 12:
  
 
{|
 
{|
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:apply|$function as function(*), $arguments as array(*))|empty-sequence()}}
+
|<pre>update:apply(
|-
+
  $function   as function(*),
 +
  $arguments as array(*)
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|The updating variant of [[XQuery 3.1#fn:apply|fn:apply]] applies the specified updating <code>$function</code> to the specified <code>$arguments</code>.
 
|The updating variant of [[XQuery 3.1#fn:apply|fn:apply]] applies the specified updating <code>$function</code> to the specified <code>$arguments</code>.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Creates a new database with an initial document and adds a document to an existing database.
 
* Creates a new database with an initial document and adds a document to an existing database.
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
declare %updating function local:update(
 
declare %updating function local:update(
 
   $database  as xs:string,
 
   $database  as xs:string,
Line 38: Line 41:
  
 
{|
 
{|
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:for-each|$seq as item()*, $function as function(item()) as item()*)|empty-sequence()}}
+
|<pre>update:for-each(
|-
+
  $input  as item()*,
 +
  $action  as function(item()) as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|The updating variant of [[Higher-Order Functions#fn:for-each|fn:for-each]] applies the specified updating <code>$function</code> to every item of <code>$seq</code>.
+
|The updating variant of [[Higher-Order Functions#fn:for-each|fn:for-each]] applies the specified updating <code>$action</code> to every item of <code>$input</code>.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Creates two databases:
 
* Creates two databases:
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
let $names := ('db1', 'db2')
 
let $names := ('db1', 'db2')
 
return update:for-each($names, db:create#1)
 
return update:for-each($names, db:create#1)
Line 57: Line 63:
  
 
{|
 
{|
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:for-each-pair|$seq1 as item()*, $function as function(item()) as item()*)|empty-sequence()}}
+
|<pre>update:for-each-pair(
|-
+
  $input1  as item()*,
 +
  $input2  as item()*,
 +
  $action  as function(item()) as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|The updating variant of [[Higher-Order Functions#fn:for-each-pair|fn:for-each-pair]] applies the specified updating <code>$function</code> to the successive pairs of items of <code>$seq1</code> and <code>$seq2</code>. Evaluation is stopped if one sequence yields no more items.
+
|The updating variant of [[Higher-Order Functions#fn:for-each-pair|fn:for-each-pair]] applies the specified updating <code>$action</code> to the successive pairs of items of <code>$input1</code> and <code>$input2</code>. Evaluation is stopped if one sequence yields no more items.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Renames nodes in an XML snippets:
 
* Renames nodes in an XML snippets:
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
copy $xml := <xml><a/><b/></xml>
 
copy $xml := <xml><a/><b/></xml>
 
modify update:for-each-pair(
 
modify update:for-each-pair(
Line 84: Line 94:
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:map-for-each|$map as map(*), $function as function(xs:anyAtomicType, item()*) as item()*|item()*}}
+
|<pre>update:map-for-each(
|-
+
  $map     as map(*),
 +
  $action  as function(xs:anyAtomicType, item()*) as item()*
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|The updating variant of {{Function|Map|map:for-each}} applies the specified {{Code|$function}} to every key/value pair of the supplied {{Code|$map}} and returns the results as a sequence.
+
|The updating variant of {{Function|Map|map:for-each}} applies the specified {{Code|$action}} to every key/value pair of the supplied {{Code|$map}} and returns the results as a sequence.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Inserts attributes into a document:
 
* Inserts attributes into a document:
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
copy $doc := <xml/>
 
copy $doc := <xml/>
 
modify update:map-for-each(
 
modify update:map-for-each(
Line 110: Line 123:
  
 
==update:output==
 
==update:output==
 
{{Mark|Updated with Version 9.1}}: Maps and arrays can be cached if they contain no persistent database nodes or function items.
 
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:output|$result as item()*|empty-sequence()}}
+
|<pre>update:output(
|-
+
  $input  as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|This function is a helper function for returning results in an updating expression. The argument of the function will be evaluated, and the resulting items will be cached and returned after the updates on the ''pending update list'' have been processed. If the supplied item will be affected by an update, a copy will be created and cached instead.
+
|This function can be used if {{Option|MIXUPDATES}} is not enabled, and if values need to be returned within an updating expression: The supplied {{Code|$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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 129: Line 142:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|update:cache||item()*}}
+
|<pre>update:cache(
|-
+
  $reset  as xs:boolean?  := false()
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns the items that have been cached by [[#update:output|update:output]]. It can be used to check which items will eventually be returned as result of an updating function.<br/>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 Module|unit tests]].
+
|Returns the items that have been cached by {{Function||update:output}}. The output cache can optionally be {{Code|$reset}}. The function can be used to check which items will eventually be returned as the result of an updating function.<br/>This function is ''nondeterministic'': It will return different results before and after items have been cached. The function can be useful for writing [[Unit Module|unit tests]].
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
* {{Function||update:cache}}: {{code|$reset}} parameter added.
  
 
;Version 9.1
 
;Version 9.1
 +
* {{Function||update:output}}: Maps and arrays can be cached if they contain no persistent database nodes or function items.
  
* [[#update:output|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 {{Function||update:output}}, db:output-cache renamed to {{Function||update:cache}}
  
 
This module was introduced with Version 9.0.
 
This module was introduced with Version 9.0.

Latest revision as of 17:36, 1 December 2023

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

Conventions[edit]

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[edit]

update:apply[edit]

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.
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)

update:for-each[edit]

Signature
update:for-each(
  $input   as item()*,
  $action  as function(item()) as 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:
let $names := ('db1', 'db2')
return update:for-each($names, db:create#1)

update:for-each-pair[edit]

Signature
update:for-each-pair(
  $input1  as item()*,
  $input2  as item()*,
  $action  as function(item()) as 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:
copy $xml := <xml><a/><b/></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

update:map-for-each[edit]

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:
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

Output[edit]

update:output[edit]

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[edit]

Signature
update:cache(
  $reset  as xs:boolean?  := false()
) 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 the result of an updating function.
This function is nondeterministic: It will return different results before and after items have been cached. The function can be useful for writing unit tests.

Changelog[edit]

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

This module was introduced with Version 9.0.