XQuery Update Facility 3.0 Requirements and Use Cases

3.1 Terminology

The following key words are used throughout the document to specify the extent to which an item is a requirement for the work of the XML Query Working Group:

MUST

This word means that the item is an absolute requirement.

MUST NOT

This word means that the item is an absolute prohibition.

SHOULD

This word means that there may exist valid reasons not to treat this item as a requirement, but the full implications should be understood and the case carefully weighed before discarding this item.

MAY

This word means that an item deserves attention, but further study is needed to determine whether the item should be treated as a requirement.

When the words MUST, SHOULD, or MAY are used in this technical sense, they occur as a hyperlink to these definitions. These words will also be used with their conventional English meaning, in which case there is no hyperlink. For instance, the phrase "the full implications should be understood" uses the word "should" in its conventional English sense, and therefore occurs without the hyperlink.

3.2 General Requirements

3.2.1 Compatibility

The XQuery Update Facility 3.0 MUST be backwards compatible with [XQuery Update Facility 1.0].

Status: this requirement has been met.

3.3 Relationship to XQuery 3.0

3.3.1 Based on Data Model 3.0

The XQuery Update Facility 3.0 MUST be defined on the [XQuery and XPath Data Model (XDM) 3.0].

Status: this requirement has been met.

Note:

The properties of a Data Model instance that can be modified by the XQuery Update Facility 3.0 are discussed in 3.4 XML Query Update Functionality.

3.3.2 Based on XQuery 3.0

The XQuery Update Facility 3.0 MUST be based on [XQuery 3.0: An XML Query Language]. The XQuery Update Facility 3.0 MUST use XQuery 3.0 to identify items to be updated. The XQuery Update Facility 3.0 MUST use XQuery 3.0 to specify items used in the updates.

Status: this requirement has been met.

3.4 XML Query Update Functionality

3.4.1 Validation

The XQuery Update Facility 3.0 MAY support an explicit XML Schema validation operation that preserves node identity.

This requirement has not been met. A decision was made by the Working Group not to do this; however, it is possible to work around this by making a "null" update.

3.4.2 Compositionality

The XQuery Update Facility 3.0 MAY be compositional with respect to XQuery 3.0 expressions; that is, it may be possible to use an update wherever an XQuery 3.0 expression is used.

Status: this requirement has not been met. Updating expressions are limited to specific syntactic contexts.

The XQuery Update Facility 3.0 MUST be able to support expressions that return both a non-empty XDM instance and a non-empty pending update list.

Status: this requirement has been partially met; a non-empty XDM instance and a non-empty pending update list can be returned by expressions, but support for what can be done with such mixed results is limited.

3.5 Transaction characteristics

In this section, the terms Atomicity, Consistency, Isolation, and Durability are taken from the ACID model of transaction characteristics for databases, which is described in [Transaction Processing Concepts and Techniques].

3.5.1 Consistency

At the end of an outermost update operation (that is, an update operation invoked from the external environment), the data model MUST be consistent with respect to the constraints specified in the Data Model 3.0. In particular, all type annotations MUST be consistent with the content of the items they govern.

Status: this requirement has been met.

The XQuery Update Facility 3.0 MAY define additional levels of granularity at which Data Model 3.0 constraints are enforced.

Status: this requirement has not been met.

3.5.2 Isolation

The XQuery Update Facility 3.0 MUST NOT preclude the means by which operations can be isolated from concurrent operations.

Status: this requirement has been met.

3.5.3 Durability

The XQuery Update Facility 3.0 MUST NOT preclude a means to control the durability of atomic operations and atomic execution units.

Status: this requirement has been met.

4.1 Use Case "R" - Updating Relational Data

One important use of an XML update language will be to update data stored in relational databases. This use case describes a set of such possible updates.

USERS ( USERID, NAME, RATING )
ITEMS ( ITEMNO, DESCRIPTION, OFFERED_BY, 
        START_DATE, END_DATE, RESERVE_PRICE ) 
BIDS ( USERID, ITEMNO, BID, BID_DATE )

                                            
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="users">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="user_tuple"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="user_tuple">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="userid"/>
        <xs:element ref="name"/>
        <xs:element minOccurs="0" ref="rating"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="userid" type="xs:string"/>
  <xs:element name="name" type="xs:string"/>
  <xs:element name="rating" type="xs:string"/>
</xs:schema>
 

                  
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="items">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="item_tuple"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="item_tuple">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="itemno"/>
        <xs:element ref="description"/>
        <xs:element ref="offered_by"/>
        <xs:element minOccurs="0" ref="start_date"/>
        <xs:element minOccurs="0" ref="end_date"/>
        <xs:element minOccurs="0" ref="reserve_price"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="itemno" type="xs:string"/>
  <xs:element name="description" type="xs:string"/>
  <xs:element name="offered_by" type="xs:string"/>
  <xs:element name="start_date" type="xs:string"/>
  <xs:element name="end_date" type="xs:string"/>
  <xs:element name="reserve_price" type="xs:string"/>
</xs:schema>

                      
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="bids">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="bid_tuple"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="bid_tuple">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="userid"/>
        <xs:element ref="itemno"/>
        <xs:element ref="bid"/>
        <xs:element ref="bid_date"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="userid" type="xs:string"/>
  <xs:element name="itemno" type="xs:string"/>
  <xs:element name="bid" type="xs:string"/>
  <xs:element name="bid_date" type="xs:string"/>
</xs:schema>

                      

<items>
  <item_tuple>
    <itemno>1001</itemno>
    <description>Red Bicycle</description>
    <offered_by>U01</offered_by>
    <start_date>1999-01-05</start_date>
    <end_date>1999-01-20</end_date>
    <reserve_price>40</reserve_price>
  </item_tuple>
    ... Snip ... 
</items>
<users>
  <user_tuple>
    <userid>U01</userid>
    <name>Tom Jones</name>
    <rating>B</rating>
  </user_tuple>
    ... Snip ... 
</users>
<bids>
  <bid_tuple> 
    <userid>U02</userid> 
    <itemno>1001</itemno> 
    <bid>35</bid> 
    <bid_date>1999-01-07</bid_date> 
    </bid_tuple> 
  <bid_tuple> 
    ... Snip ... 
</bids>
                    

let $uid := doc("users.xml")/users/user_tuple[name = "Roger Smith"]/userid
let $topbid := max(doc("bids.xml")/bids/bid_tuple[itemno = 1002]/bid)
let $newbid := $topbid * 1.1
return (
  insert nodes
    <bid_tuple> 
      <userid>{ data($uid) }</userid> 
      <itemno>1002</itemno> 
      <bid>{ $newbid }</bid> 
      <bid_date>1999-03-03</bid_date> 
    </bid_tuple>
  into doc("bids.xml")/bids,
  <new_bid>{ $newbid }</new_bid>
)

<new_bid>1320</new_bid>
            

<bids>
  <bid_tuple> 
    <userid>U02</userid> 
    <itemno>1001</itemno> 
    <bid>35</bid> 
    <bid_date>1999-01-07</bid_date> 
  </bid_tuple> 
    ... Snip ... 
  <bid_tuple> 
    <userid>U01</userid> 
    <itemno>1002</itemno> 
    <bid>400</bid> 
    <bid_date>1999-02-14</bid_date> 
  </bid_tuple> 
    ... Snip ... 
   <bid_tuple> 
    <userid>U04</userid> 
    <itemno>1007</itemno> 
    <bid>225</bid> 
    <bid_date>1999-02-12</bid_date> 
  </bid_tuple> 
    ... Snip ... 
  <bid_tuple> 
    <userid>U04</userid> 
    <itemno>1002</itemno> 
    <bid>1320</bid> 
    <bid_date>1999-03-03</bid_date> 
  </bid_tuple> 
</bids>
						

let $uid := doc("users.xml")/users/user_tuple[name = "Roger Smith"]/userid
let $topbid := max(doc("bids.xml")/bids/bid_tuple[itemno = 1007]/bid)
let $newbid := $topbid * 1.1
return
  if($newbid <= 240) then (
    insert nodes
      <bid_tuple>
        <userid>{ data($uid) }</userid>
        <itemno>1002</itemno>
        <bid>{ $newbid }</bid>
        <bid_date>1999-03-03</bid_date>
      </bid_tuple>
    into doc("bids.xml")/bids,
    <new_bid>{ $newbid }</new_bid>
  ) else (
    <top_bid>{ $topbid }</top_bid>
  )

<top_bid>225</top_bid>
            

let $user := doc("users.xml")/users/user_tuple[name = "Dee Linquent"]
let $items := doc("items.xml")/items/item_tuple[offered_by = $user/userid]
let $bids := doc("bids.xml")/bids/bid_tuple[userid = $user/userid]
return (
  delete nodes ($user, $items, $bids),
  <deleted>
    <items>{ count($items) }</items>
    <bids>{ count($bids) }</bids>
  </deleted>
)

<deleted>
  <items>2</items>
  <bids>2</bids>
</deleted>

<items>
  <item_tuple>
    <itemno>1001</itemno>
    <description>Red Bicycle</description>
    <offered_by>U01</offered_by>
    <start_date>1999-01-05</start_date>
    <end_date>1999-01-20</end_date>
    <reserve_price>40</reserve_price>
  </item_tuple>
    ... Snip ... 
  <item_tuple>
    <itemno>1004</itemno>
    <description>Tricycle</description>
    <offered_by>U01</offered_by>
    <start_date>1999-02-25</start_date>
    <end_date>1999-03-08</end_date>
    <reserve_price>15</reserve_price>
  </item_tuple>
  <item_tuple>
    <itemno>1007</itemno>
    <description>Racing bicycle</description>
    <offered_by>U04</offered_by>
    <start_date>1999-01-20</start_date>
    <end_date>1999-02-20</end_date>
    <reserve_price>200</reserve_price>
  </item_tuple>
  <item_tuple>
    <itemno>1008</itemno>
    <description>Broken bicycle</description>
    <offered_by>U01</offered_by>
    <start_date>1999-02-05</start_date>
    <end_date>1999-03-06</end_date>
    <reserve_price>25</reserve_price>
  </item_tuple>
</items>

<users>
  <user_tuple>
    <userid>U01</userid>
    <name>Tom Jones</name>
    <rating>B</rating>
  </user_tuple>
  <user_tuple>
    <userid>U02</userid>
    <name>Mary Doe</name>
    <rating>A</rating>
  </user_tuple>
   <user_tuple>
    <userid>U04</userid>
    <name>Roger Smith</name>
    <rating>C</rating>
  </user_tuple>
  ... Snip ... 
  <user_tuple>
   <userid>U06</userid>
   <name>Rip Van Winkle</name>
   <rating>B</rating>
  </user_tuple>
</users>

<bids>
  <bid_tuple> 
    <userid>U02</userid> 
    <itemno>1001</itemno> 
    <bid>35</bid> 
    <bid_date>1999-01-07</bid_date> 
  </bid_tuple> 
  <bid_tuple> 
    <userid>U04</userid> 
    <itemno>1001</itemno> 
    <bid>40</bid> 
    <bid_date>1999-01-08</bid_date> 
  </bid_tuple> 
  ... Snip ... 
  <bid_tuple> 
    <userid>U02</userid> 
    <itemno>1002</itemno> 
    <bid>600</bid> 
    <bid_date>1999-02-16</bid_date> 
  </bid_tuple> 
  <bid_tuple> 
    <userid>U04</userid> 
    <itemno>1002</itemno> 
    <bid>1000</bid> 
    <bid_date>1999-02-25</bid_date> 
  </bid_tuple> 
  ... Snip ... 
  <bid_tuple> 
    <userid>U04</userid> 
    <itemno>1007</itemno> 
    <bid>225</bid> 
    <bid_date>1999-02-12</bid_date> 
  </bid_tuple> 
</bids>

4.2 Use case "Wiki" - traversing a set of Wiki pages

This scenario demonstrates the use of an updating function that returns a non-empty XDM instance. The recursive function traverses a set of html documents by following the href attributes, returning an index structure representing the linkage hierarchy. The function also updates a list of visited documents in order to avoid a document being visited more than once.

<html>
  <head><title>Documentation</title></head>
  <body>
    <h1>Contents</h1>
	<ul>
	  <li><a href="section1.html">Section 1</a></li>
	  <li><a href="section2.html">Section 2</a></li>
	</ul>
  </body>
</html>
          

<html>
  <head><title>Section 1</title></head>
  <body>
    <h1>First</h1>
	<p>Some interesting detail. More in the <a href="section1a.html">next section</a></p>
	<p>Back to the <a href="Documentation.html">index page</a></p>
  </body>
</html>
          

<html>
  <head><title>Section 1a</title></head>
  <body>
    <h1>Subsection</h1>
	<p>More of the same</p>
	<p>Back to the <a href="Documentation.html">index page</a></p>
  </body>
</html>
          

<html>
  <head><title>Section 2</title></head>
  <body>
    <h1>Second</h1>
	<p>Summary of <a href="section1.html">section 1</a>
	          and <a href="section1a.html">section 1a</a></p>
	<p>Back to the <a href="Documentation.html">index page</a></p>
  </body>
</html>
          

declare variable $prefix := "/html/";
declare variable $visited := <visited/>;

declare function local:filetree($s as xs:string, $depth)
{
if ($depth < 5) then
  <level depth="{$depth}">
    <file>{ $s }</file>
    { 
      let $relname := concat($prefix, $s)
      let $doc := doc($relname)
      for $href in $doc//@href
      where contains($href,"htm")
        and not(contains($href,"http"))
        and (every $url in $visited/url satisfies $url != $href)
      return ( 
             insert node <url>{ $href }</url> into $visited,
             <newcall>{ local:filetree($href, $depth+1) }</newcall> 
      )
    }
  </level>
 else ()
};

local:filetree("Documentation.html", 1)
          

<level depth="1">
  <file> Documentation.html </file>
  <newcall>
    <level depth="2">
      <file> section1.html </file>
      <newcall>
        <level depth="3">
          <file> section1a.html </file>
        </level>
      </newcall>
    </level>
  </newcall>
  <newcall>
    <level depth="2">
      <file> section2.html </file>
    </level>
  </newcall>
</level>
          

4.3 Use case "ebook" - Create files for an ebook

Create multiple files for an EPUB ebook from a single query, including JavaScript, XML manifest, XHTML book chapters and contents, CSS.

This use case illustrates creating multiple output documents in differing formats, here for an EPUB 3 ebook but the same issues apply for creating a Web app or a rich Web page with styles and scripts.

The solution presupposes functions that will create the documents that we need to write out.

let $chapters := makebook(),
          $js := makejs($chapters),
         $css := makecss($chapters),
         $toc := maketoc($chapters),
    $manifest := makemanifest($chapters, $js, $css, $toc),
      $output := function($method as xs:string) {
                   <output:serialization-parameters
                           xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
                     <output:method value="{$method}"/>
                   </output:serialization-parameters>
                 }

return (
    for $c in $chapters return put($c, urifor($c), $output("xml")),
    put($js, "tmp/lib/js.js", $output("text")),
    put($css, "tmp/lib/styles.css", $output("text")),
    put($toc, "tmp/tox.xhtml", $output("xhtml")),
    put($manifest, "tmp/manifest.xhtml", $output("xhtml"))
)