Difference between revisions of "Update Module"

From BaseX Documentation
Jump to navigation Jump to search
(15 intermediate revisions by 3 users not shown)
Line 8: Line 8:
  
 
=Updates=
 
=Updates=
 +
 +
==update:apply==
 +
 +
{|
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|update:apply|$function as function(*), $arguments as array(*)|empty-sequence()}}
 +
|-
 +
| '''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>.
 +
|-
 +
| '''Examples'''
 +
|
 +
* Creates a new database with an initial document and adds a document to an existing database.
 +
<syntaxhighlight lang="xquery">
 +
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)
 +
</syntaxhighlight>
 +
|}
  
 
==update:for-each==
 
==update:for-each==
Line 14: Line 40:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|update:for-each|$seq as item()*, $function as function(item()) as item()*)|empty-sequence()}}
+
|{{Func|update:for-each|$seq as item()*, $function as function(item()) as item()*|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 22: Line 48:
 
|
 
|
 
* Creates two databases:
 
* Creates two databases:
<pre class="brush:xquery">
+
<syntaxhighlight 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)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 33: Line 59:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|update:for-each-pair|$seq1 as item()*, $function as function(item()) as item()*)|empty-sequence()}}
+
|{{Func|update:for-each-pair|$seq1 as item()*, $function as function(item()) as item()*|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 41: Line 67:
 
|
 
|
 
* Renames nodes in an XML snippets:
 
* Renames nodes in an XML snippets:
<pre class="brush:xquery">
+
<syntaxhighlight 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 52: Line 78:
 
)
 
)
 
return $xml
 
return $xml
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 65: Line 91:
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
|Inserts attributes into a document:
+
|
<pre class="brush:xquery">
+
* Inserts attributes into a document:
 +
<syntaxhighlight lang="xquery">
 
copy $doc := <xml/>
 
copy $doc := <xml/>
 
modify update:map-for-each(
 
modify update:map-for-each(
Line 77: Line 104:
 
   }
 
   }
 
)
 
)
return $doc</pre>
+
return $doc</syntaxhighlight>
 
|}
 
|}
  
Line 83: Line 110:
  
 
==update:output==
 
==update:output==
 
{{Mark|Updated with Version 9.0}}: formerly {{Code|db:output}}.
 
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|update:output|$result as item()*|empty-sequence()}}
+
|{{Func|update:output|$items as item()*|empty-sequence()}}
 
|-
 
|-
 
| '''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. As nodes may be updated, they will be copied before being cached.
+
|This function can be used if {{Option|MIXUPDATES}} is not enabled, and if values need to returned within an updating expression: The supplied {{Code|$items}} 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'''
 
| '''Examples'''
Line 99: Line 124:
 
|}
 
|}
  
==update:output-cache==
+
==update:cache==
 
 
{{Mark|Updated with Version 9.0}}: formerly {{Code|db:output-cache}}.
 
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|update:output-cache||item()*}}
+
|{{Func|update:cache||item()*}}<br/>{{Func|update:cache|$reset as xs:boolean|item()*}}
 
|-
 
|-
 
| '''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|update:output}}. The output cache can optionally be {{Code|$reset}}. The function 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]].
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
* [[#update:cache|update:cache]]: {{code|$reset}} parameter added.
 +
 +
;Version 9.1
 +
* [[#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|update:output}}, db:output-cache renamed to {{Function|Update|update:cache}}
  
 
This module was introduced with Version 9.0.
 
This module was introduced with Version 9.0.

Revision as of 11:50, 8 July 2020

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

Conventions

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

update:apply

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

<syntaxhighlight lang="xquery"> 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) </syntaxhighlight>

update:for-each

Signatures update:for-each($seq as item()*, $function as function(item()) as item()*) as empty-sequence()
Summary The updating variant of fn:for-each applies the specified updating $function to every item of $seq.
Examples
  • Creates two databases:

<syntaxhighlight lang="xquery"> let $names := ('db1', 'db2') return update:for-each($names, db:create#1) </syntaxhighlight>

update:for-each-pair

Signatures update:for-each-pair($seq1 as item()*, $function as function(item()) as item()*) as empty-sequence()
Summary The updating variant of fn:for-each-pair applies the specified updating $function to the successive pairs of items of $seq1 and $seq2. Evaluation is stopped if one sequence yields no more items.
Examples
  • Renames nodes in an XML snippets:

<syntaxhighlight lang="xquery"> copy $xml := <xml><a/></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 </syntaxhighlight>

update:map-for-each

Signatures update:map-for-each($map as map(*), $function as function(xs:anyAtomicType, item()*) as item()*) as item()*
Summary The updating variant of map:for-each applies the specified $function to every key/value pair of the supplied $map and returns the results as a sequence.
Examples
  • Inserts attributes into a document:

<syntaxhighlight lang="xquery"> 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</syntaxhighlight>

Output

update:output

Signatures update:output($items as item()*) as empty-sequence()
Summary This function can be used if MIXUPDATES is not enabled, and if values need to returned within an updating expression: The supplied $items 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

Signatures update:cache() as item()*
update:cache($reset as xs:boolean) 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 result of an updating function.
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 tests.

Changelog

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.