XQuery Update Facility 3.0 Requirements and Use Cases

1 Goals

This document describes the requirements and use cases for the XQuery Update Facility 3.0. [XQuery 3.0: An XML Query Language] provides queries, but has no support for adding new values or changing existing values. The XML Query Working Group intends to add support for updates in a future version of XQuery. This document only contains requirements that have not been previously met by [XQuery Update Facility 1.0]

2 Usage Scenarios

The following usage scenarios describe how the XQuery Update Facility 3.0 may be used in various environments, and represent a wide range of activities and needs that illustrate the problem space to be addressed. They are intended to be used as design cases during the development of the XQuery Update Facility 3.0, and should be reviewed when critical decisions are made. These usage scenarios should also prove useful in helping non-members of the XML Query Working Group understand the intent and goals of the project.

2.1 Updating persistent XML stores: Modify XML in persistent XML stores, including native XML databases, XML files stored on a file system, or XML stored in SQL databases.
2.2 Modify XML messages: Modify XML messages to change status and add information created while processing the message.
2.3 Add to existing XML document: Add new data to an existing XML document; for instance, add a new entry to a BLOG or a data log.
2.4 Updating XML registries: Perform updates on configuration files, user profiles, or administrative logs represented in XML.
2.5 Creating edited copies: Create a new copy of an XML document or subtree that differs from the original in the way specified by the update. For instance, updates could be used to modify a web message in order to add new information and change headers to reflect the modified status.
2.6 Modifying XML views: Modifying XML views of non-XML sources, such as an [SQL/XML] view of a SQL database.

3 Requirements

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

red status Status: this requirement has not 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].

red status Status: this requirement has not 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.

red status Status: this requirement has not 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.

yellow status This requirement has not been met according to its original formulation; however, the revalidation mode can be set to ensure that type information is recovered and the resulting document is valid according to the governing schema.

Note:

The XQuery 3.0 validate expression creates a new copy of each validated node, with a new identity. This requirement involves preservation of identity.

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.

red status 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.

red status Status: this requirement has not been met.

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.

green status 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.

red status 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.

red status Status: this requirement has not 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.

red status Status: this requirement has not been met.

4 Use Cases for XQuery Update Facility 3.0

The use cases listed below were created by the XML Query Working Group to illustrate important applications for an XML update facility. Each use case is focused on a specific application area, and contains a Document Type Definition (DTD) and example input data. Each use case specifies a set of updates that might be applied to the input data, and the expected resulting value of the modified input for each update. Since the English description of each query is concise, the expected results form an important part of the definition of each update directive. These use cases are inspired by section 3 Requirements.

These use cases represent a snapshot of an ongoing work. Some important application areas and important operations are not yet adequately covered by a use case. The XML Query Working Group reserves the right to add, delete, or modify individual queries or whole use cases as the work progresses. The presence of a query in this set of use cases does not necessarily indicate that the query will be expressible in the XQuery Update Facility to be created by the XML Query Working Group.

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.

4.1.1 Description

This use case is based on performing updates on the data used in Use Case "R" from the [XML Query Use Cases]. The sample data from this Use Case is copied below for convenience, and exactly match the data found in the XQuery 1.0 Use Cases. Instead of DTDs, we describe this data with W3C XML Schemas.

The data represents a relational database used by an online auction. The auction maintains a USERS table containing information on registered users, each identified by a unique userid, who can either offer items for sale or bid on items. An ITEMS table lists items currently or recently for sale, with the userid of the user who offered each item. A BIDS table contains all bids on record, keyed by the userid of the bidder and the item number of the item to which the bid applies.

The three tables used by the online auction are below, with their column-names indicated in parentheses.

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

4.1.2 XML Schemas

This use case is based on three separate input documents named users.xml, items.xml, and bids.xml. Each of the documents represents one of the tables in the relational database described above, using the following schemas:

4.1.2.1 Schema for users.xml

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

4.1.2.2 Schema for items.xml

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

4.1.2.3 Schema for bids.xml

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

4.1.3 Input Data

The following data is an excerpt of the initial state for Q1. In this particular use case, each update begins with the state resulting from the prior update.

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

The entire data set is represented by the following tables:

USERS
USERID	NAME	RATING
U01	Tom Jones	B
U02	Mary Doe	A
U03	Dee Linquent	D
U04	Roger Smith	C
U05	Jack Sprat	B
U06	Rip Van Winkle	B

ITEMS
ITEMNO	DESCRIPTION	OFFERED_BY	START_DATE	END_DATE	RESERVE_PRICE
1001	Red Bicycle	U01	1999-01-05	1999-01-20	40
1002	Motorcycle	U02	1999-02-11	1999-03-15	500
1003	Old Bicycle	U02	1999-01-10	1999-02-20	25
1004	Tricycle	U01	1999-02-25	1999-03-08	15
1005	Tennis Racket	U03	1999-03-19	1999-04-30	20
1006	Helicopter	U03	1999-05-05	1999-05-25	50000
1007	Racing Bicycle	U04	1999-01-20	1999-02-20	200
1008	Broken Bicycle	U01	1999-02-05	1999-03-06	25

BIDS
USERID	ITEMNO	BID	BID_DATE
U02	1001	35	1999-01-07
U04	1001	40	1999-01-08
U02	1001	45	1999-01-11
U04	1001	50	1999-01-13
U02	1001	55	1999-01-15
U01	1002	400	1999-02-14
U02	1002	600	1999-02-16
U03	1002	800	1999-02-17
U04	1002	1000	1999-02-25
U02	1002	1200	1999-03-02
U04	1003	15	1999-01-22
U05	1003	20	1999-02-03
U01	1004	40	1999-03-05
U03	1007	175	1999-01-25
U05	1007	200	1999-02-08
U04	1007	225	1999-02-12

The underlying database system has the following referential integrity constraints:

A foreign key on the BIDS table requires that BIDS.USERID contains a value that is found in USERS.USERID
A foreign key on the BIDS table requires that BIDS.ITEMNO contains a value that is found in ITEMS.ITEMNO

4.1.4 Updates and Results

4.1.4.1 Q1

Insert a new bid for Roger Smith on item 1002, adding 10% to the best bid received so far for this item, and report back what bid was just entered.

Solution in the XQuery Update Facility:

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

Expected Result:

The best bid for item 1002 had been at 1200, thus Roger's bid is at 1320.

<new_bid>1320</new_bid>

Expected resulting content of bids.xml:

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

4.1.4.2 Q2

Place a bid for Roger Smith on item 1007, adding 10% to the best bid received so far on that item, but only if the bid amount does not exceed a given limit. Otherwise return the current top bid.

Solution in the XQuery Update Facility:

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

Expected Result:

Adding 10% to the best bid on item 1007 would require a bid of 247.5, which is more than the allowed limit of 240. Thus, the bids.xml document does not change.

<top_bid>225</top_bid>

4.1.4.3 Q3

Erase user Dee Linquent and the corresponding associated items and bids. Return a count of the items and bids deleted.

Solution in the XQuery Update Facility:

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

Expected Result:

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

Expected resulting content of items.xml:

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

Expected resulting content of users.xml:

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

Expected resulting content of bids.xml:

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

Note:

This use case requires side-effects in the language and so is unlikely to be supported. It may be removed in a future draft of this document.

4.2.1 Input data

Documentation.html: The top level Wiki page.

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

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

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

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

4.2.2 Q1

Return the document hierarchy omitting duplicates.

Solution in the XQuery Update Facility:

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)

Expected result:

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

XQuery Update Facility 3.0 Requirements and Use Cases

W3C Working Draft 27 March 2012

Abstract

Status of this Document

Table of Contents

Appendix

1 Goals

2 Usage Scenarios

3 Requirements

3.1 Terminology

3.2 General Requirements

3.3 Relationship to XQuery 3.0

3.4 XML Query Update Functionality

3.5 Transaction characteristics

4 Use Cases for XQuery Update Facility 3.0

4.1 Use Case "R" - Updating Relational Data

4.1.1 Description

4.1.2 XML Schemas

4.1.2.1 Schema for users.xml

4.1.2.2 Schema for items.xml

4.1.2.3 Schema for bids.xml

4.1.3 Input Data

4.1.4 Updates and Results

4.1.4.1 Q1

4.1.4.2 Q2

4.1.4.3 Q3

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

4.2.1 Input data

4.2.2 Q1

A References