Replace expression

A replace expression replaces an existing node with a new sequence of zero or more nodes, or replaces a node's value while preserving the node's identity.

Syntax

do replace

The keywords that begin a replace expression.

TargetExpression

An XQuery expression that is not an updating expression. If the expression includes a top-level comma operator, the expression must be enclosed in parentheses. The result of TargetExpression must be a single node that is not a document node. If the result of TargetExpression is a document node, Db2 XQuery returns an error.

If the value of keywords are not specified, the result of TargetExpression must be a single node whose parent property is not empty.

value of

The keywords that specify replacing the value of the TargetExpression node while preserving the node's identity.

with

The keyword that begins the source expression.

SourceExpression

An XQuery expression that is not an updating expression. If the expression includes a top-level comma operator, the expression must be enclosed in parentheses.

If the value of keywords are specified, the SourceExpression is evaluated as though it were the content expression of a text node constructor. The result of the SourceExpression is a single text node or an empty sequence.

If the value of keywords are not specified, the result of the SourceExpression must be a sequence of nodes. The SourceExpression is evaluated as though it were an expression enclosed in an element constructor. If the SourceExpression sequence contains a document node, the document node is replaced by its children. The SourceExpression sequence must consist of the following node types:

If the TargetExpression node is an attribute node, the replacement sequence must consist of zero or more attribute nodes.
If the TargetExpression node is an element, text, comment, or processing instruction node, the replacement sequence must consist of some combination of zero or more element, text, comment, or processing instruction nodes.

The following updates are generated when the value of keywords are specified:

If the TargetExpression node is an element node, the existing children of the TargetExpression node are replaced by the text node returned by the SourceExpression. If the SourceExpression returns an empty sequence, the children property of the TargetExpression node becomes empty. If the TargetExpression node contains attribute nodes, they are not affected.
If the TargetExpression node is not an element node, the string value of the TargetExpression node is replaced by the string value of the text node returned by the SourceExpression. If the SourceExpression does not return a text node, the string value of the TargetExpression node is replaced by a zero-length string.

The following updates are generated when the value of keywords are not specified:

SourceExpression nodes replace the TargetExpression node. The parent node of the TargetExpression node becomes the parent of each of the SourceExpression nodes. The SourceExpression nodes occupy the position in the node hierarchy occupied by the TargetExpression node.
The TargetExpression node, all its attributes and descendants are detached from the node sequence.

Examples

The following examples use the CUSTOMER table from the Db2 SAMPLE database. In the CUSTOMER table, the XML column INFO contains customer address and phone information.

In the following example, the copy clause of the transform expression creates a copy of the XML document from column INFO. The replace expression replaces the addr element and its children:

xquery 
transform
copy $mycust := db2-fn:sqlquery('select info from customer where cid = 1000')
modify
  do replace $mycust/customerinfo/addr
    with
      <addr country="Canada">
        <street>1596 14th Avenue NW</street>
        <city>Calgary</city>
        <prov-state>Alberta</prov-state>
        <pcode-zip>T2N 1M7</pcode-zip>
      </addr>
return $mycust

When run against the SAMPLE database, the expression returns the following result with the replaced address information:

<customerinfo Cid="1000">
  <name>Kathy Smith</name>
  <addr country="Canada">
    <street>1596 14th Avenue NW</street>
    <city>Calgary</city>
    <prov-state>Alberta</prov-state>
    <pcode-zip>T2N 1M7</pcode-zip>
  </addr>
  <phone type="work">416-555-1358</phone>
</customerinfo>

The following expression replaces the value of the customer phone element's type attribute from home to personal:

xquery
transform
copy $mycust := db2-fn:sqlquery('select info from customer where cid = 1004') 
modify 
  do replace value of $mycust/customerinfo/phone[@type="home"]/@type with "personal"
return $mycust

When run against the SAMPLE database, the expression returns the following result with the replaced attribute value:

<customerinfo Cid="1004">
  <name>Matt Foreman</name>
  <addr country="Canada">
    <street>1596 Baseline</street>
    <city>Toronto</city>
    <prov-state>Ontario</prov-state>
    <pcode-zip>M3Z 5H9</pcode-zip>
  </addr>
  <phone type="work">905-555-4789</phone>
  <phone type="personal">416-555-3376</phone>
  <assistant>
    <name>Gopher Runner</name>
    <phone type="home">416-555-3426</phone>
  </assistant>
</customerinfo>

The value of the assistant's phone attribute has not been changed.