Chapter 7: Developing with XML 229 Querying a Single Element The preceding example showed how to query all of the nodes from a parent node. This example illustrates querying a single node: DECLARE @x xml SET @x = '<Myroot><Element1>One</Element1><Element2>Two</Element2></Myroot>' SELECT @x.query('/Myroot/Element1') Each level in the XML document hierarchy is closed by the / symbol. Here the XQuery returns the value of just the Element1 node, as is shown in the following listing: <Element1>One</Element1> (1 row(s) affected) Querying Single Element Values Unlike T-SQL, XQuery also has the capability to query for single sets of node values according to their predicate or position in the set. The following listing shows how to retrieve the first value from the Element2 node: DECLARE @x xml SET @x = '<Myroot><Element1>One</Element1><Element2>Two</Element2></Myroot>' SELECT @x.query('(/Myroot/Element2)[1]') In this example the hierarchy of nodes is placed within parenthesis. The desired node number follows enclosed in brackets. You can see the results in the following listing: <Element2>Two</Element2> (1 row(s) affected) Querying Typed XML Typed XML (i.e., XML that has an associated schema) requires that you declare the appropriate namespace in order to retrieve the nodes from the XML document. The following listing illustrates an XQuery that queries the sample MyXMLDocs table 230 Microsoft SQL Server 2005 Developer’s Guide that was used in the earlier examples. The MyXMLDoc column in this table contains typed XML. SELECT MyXMLDoc.query('declare namespace tns="http://MyXMLDocSchema"; /tns:MyXMLDoc/ ') As MyXMLBody FROM MyXMLDocs The declare namespace directive creates a namespace named tns and assigns that namespace the value of http://MyXMLDocSchema. This value must match the namespace from the schema. The XQuery needs to preface the node names with the namespace. You can see the results in the following listing: <MyXMLDoc xmlns="http://MyXMLDocSchema"><DocumentID>1</DocumentID> <DocumentBody>Modified Body</DocumentBody></MyXMLDoc> <MyXMLDoc xmlns="http://MyXMLDocSchema"><DocumentID>2</DocumentID> <DocumentBody>"My text2"</DocumentBody></MyXMLDoc> (2 row(s) affected) FLWR (For-Let-Where-Return) The XPath-style queries work well for standard queries. However, they aren’t as flexible as T-SQL. The FLWR (For-Let-Where-Return) statement adds a level of flexibility to SQL Server’s XQuery implementation. In SQL Server 2005, the Let clause is not supported but the For, Order By, Where, and Return clauses are supported. In addition, the FLWR syntax looks more like T-SQL and is probably more readily usable for experienced T-SQL coders. You can see an example of using the FLWR query in the following listing: SELECT MyXMLDoc.query ('declare namespace tns="http://MyXMLDocSchema"; for $db in /tns:MyXMLDoc where /tns:MyXMLDoc/tns:DocumentID = 1 return $db') FROM MyXMLDocs This code uses the example MyXMLDocs table that was created earlier in this chapter. Because the MyXMLDoc column has an attached schema, a namespace must be declared at the top of the XQuery. Like the SQL SELECT clause the FOR clause is used to tell the query where to look for data. The WHERE clause restricts Chapter 7: Developing with XML 231 the result set. The RETURN clause specifies the data that will be returned. Here, the XQuery looks in the document MyXMLDoc for elements where the DocumentID element is equal to the value of 1. You can see the results in the following listing: <MyXMLDoc xmlns="http://MyXMLDocSchema"><DocumentID>1</DocumentID> <DocumentBody>Modified Body</DocumentBody></MyXMLDoc> (3 row(s) affected) This section presented some of the basics about XQuery; the topic is definitively large enough to be covered in its own book. For more details about the W3C XQuery standard, you can refer to http://www.w3.org/XML/Query and http://www.w3.org/ TR/2004/WD-xquery-20040723/. The SQL Server 2005 Books Online also has an introduction to the XQuery language. XML Data Type Methods SQL Server 2005 provides several new built-in methods for working with the XML data type. Unlike standard relational data, XML data is usually hierarchical, complete with structures and metadata, and in order to provide true XML integration, SQL Server needed a way to seamlessly access the data stored in an XML document. The XML data type’s built-in methods enable you to drill down into the content of XML documents that are stored using the XML data type. This section will show you how to use the XML data type’s methods. Exist(XQuery) The XML data type’s Exists method enables you to check the contents of an XML document for the existence of elements or attributes using an XQuery expression. The Exists method takes one parameter that consists of a XQuery statement and returns the following values: Return Value Description 0 The node was not found (FALSE). 1 The node exists (TRUE). Null The XML data type was null. 232 Microsoft SQL Server 2005 Developer’s Guide The following listing shows how to use the XML data type’s Exist method: SELECT * FROM MyXMLDocs WHERE MyXmlDoc.exist('declare namespace tns="http://MyXMLDocSchema"; /tns:MyXMLDoc/tns:DocumentID=1') = 1 The first parameter of the XML Exist method is required and takes an XQuery expression. Here the XQuery tests for a DocumentID element equal to a value of 1. A namespace is declared because the MyXMLDoc column is typed—meaning it has an associated schema. The Exist method can return the value of TRUE (1) if the XQuery expression returns an XML node, FALSE (0) if the expression doesn’t return a node, or NULL if the XML data type instance is null. Using the XML data from the previous examples, you can see the results of the XML Exist method here: DocID MyXmlDoc 1 <MyXMLDoc xmlns="http://MyXMLDocSchema"> <DocumentID>1</DocumentID> <DocumentBody>"My text"</DocumentBody></MyXMLDoc> (1 row(s) affected) NOTE The preceding listing was reformatted to make it more readable in the published page width. Modify(XML DML) While the previous examples illustrated how to use XQuery to retrieve information from an XML document, XQuery can also be used for deleting, inserting, and updating part of an XML document. The Modify method enables you to modify a stored XML document. You can use the Modify method either to update the entire XML document or to update just a selected part of the document. You can see an example of using the Modify method in the following listing: UPDATE MyXMLDocs SET MyXMLDoc.modify('declare namespace tns="http://MyXMLDocSchema"; replace value of (/tns:MyXMLDoc/tns:DocumentBody)[1] with "Modified Body"') WHERE DocID = 1 The XML data type’s Modify method uses an XML Data Modification Language (XML DML) statement as its parameter. XML DML is a Microsoft extension to the XQuery language that enables modification of XML documents. The Modify method supports the Insert, Delete, and Replace values of XML DML statements. In addition, Chapter 7: Developing with XML 233 the Modify method can be used only in the SET clause of an UPDATE statement. In this example, since the MyXMLDoc XML column is typed, the XML DML statement must specify the namespace for the schema. Next, you can see where the Replace value of the XML DML command is used to replace the value of the DocumentBody element with the new value of “Modified Body” for the row where the DocID column is equal to 1. The [1] notation indicates that the operation is for a single value. NOTE While this example illustrates performing a replace operation, the Modify method also supports insert and delete operations, allowing the addition of new elements and the deletion of existing elements. Once the previous Modify method has been executed, you can run the following SELECT statement to see the updated values: Select MyXMLDoc from MyXM#LDocs Given the earlier insert example, this statement would produce the following result, where you can see the updated value in the DocumentBody element: MyXMLDoc <MyXMLDoc xmlns="http://MyXMLDocSchema"><DocumentID>1</DocumentID> <DocumentBody>Modified Body</DocumentBody></MyXMLDoc> (1 row(s) affected) Query(XQuery) The XML data type’s Query method can retrieve either the entire contents of an XML document or selected sections of the XML document. The Query method accepts an XQuery statement as a parameter. You can see an example of using the Query method in the following listing: SELECT DocID, MyXMLDoc.query('declare namespace tns="http://MyXMLDocSchema"; /tns:MyXMLDoc/tns:DocumentBody') AS Body FROM MyXMLDocs This XQuery expression returns the values from the XML document’s DocumentBody element. Again, the namespace is specified because the MyXMLDoc XML data type has an associated schema, named MyXMLDocSchema. In this 234 Microsoft SQL Server 2005 Developer’s Guide example, you can see how SQL Server 2005 easily integrates relational column data with XML data. Here, DocID comes from a relational column, while the DocumentBody element is queried out of the XML column. The following listing shows the results of the XQuery: DocID Body 1 <tns:DocumentBody xmlns:tns="http://MyXMLDocSchema"> Modified Body</tns:DocumentBody> 2 <tns:DocumentBody xmlns:tns="http://MyXMLDocSchema"> "My text2"</tns:DocumentBody> (2 row(s) affected) NOTE The preceding listing was reformatted to make it more readable in the published page width. Value(XQuery, [node ref]) The Value method enables the extraction of scalar values from an XML data type. You can see an example of how the XML data type’s Value method is used in the following listing: SELECT MyXMLDoc.value('declare namespace xd="http://MyXMLDocSchema"; (/xd:MyXMLDoc/xd:DocumentID)[1]', 'int') AS ID FROM MyXMLDocs Unlike the other XML data type methods, the XML Value method requires two parameters. The first parameter is an XQuery expression, and the second parameter specifies the SQL data type that will hold the scalar value returned by the Value method. This example returns all of the values contained in the DocumentID element and converts them to the int data type, as shown in the following results: ID 1 2 (2 row(s) affected) Chapter 7: Developing with XML 235 XML Indexes The XML data type supports a maximum of 2GB of storage, which is quite large. The size of the XML data and its usage can have a big impact on the performance the system can achieve when querying XML data. To improve the performance of XML queries, SQL Server 2005 provides the ability to create indexes over the columns that have the XML data type. Primary XML Indexes In order to create an XML index on an XML data type column, a clustered primary key must exist for the table. In addition, if you need to change the primary key for the table, you must first delete the XML index. An XML index covers all the elements in the XML column, and you can have only one XML index per column. An XML index cannot have the same name as an existing index. XML indexes can be created only on XML data types in a table. They cannot be created on columns in views or on XML data type variables. A primary XML index consists of a persistent shredded representation of the data in the XML column. The following shows an example of how to create a primary XML index on the MyXMLDocs table that was used in the earlier examples: CREATE PRIMARY XML INDEX MyXMLDocsIdx ON MyXMLDocs(MyXMLDoc) This example shows the creation of a primary XML index named MyXMLDocsIdx. This index is created on the MyXMLDoc XML data type column in the MyXMLDocs table. Just like regular SQL Server indexes, XML indexes can be viewed by querying the sys.indexes view. Secondary XML Indexes In addition to the primary index, you can also build secondary XML indexes. SQL Server 2005 supports the following secondary XML indexes: Secondary index type Description Path The document path is used to build the index. Value The document values are used to build the index. Property The document’s properties are used to build the index. 236 Microsoft SQL Server 2005 Developer’s Guide Secondary indexes are always partitioned in the same way as the primary XML index. The following listing shows the creation of a secondary-path XML index: CREATE XML INDEX My2ndXMLDocsIdx ON MyXMLDocs(MyXMLDoc) USING XML INDEX MyXMLDocsIdx FOR PATH Using the For XML Clause The FOR XML clause was first added to the T-SQL SELECT clause with SQL Server 2000. The For XML clause enables SQL Server to return XML results from a query. In this section you first learn about the preexisting FOR XML Raw, Auto, and Explicit support. Next you’ll see how to use some of the new capabilities that are found in SQL Server 2005, including support for the XML data type via a new Type mode, added support for result shaping using the PATH mode, nested FOR XML queries, and inline XSD schema generation. For XML Raw The For XML Raw mode returns a result set where each result row is returned in an element named using a generic identifier for the row. The value of each column is returned using attribute pairs. This form typically is used where some other applications will provide additional processing of the data. However, an external, B2B-type transfer will typically require the use of more descriptive tags and a more flexible structure. The For XML Raw results are essentially the XML equivalent of CSV (Command Separated Value) files. The following listing presents an example of using the For XML Raw mode: SELECT Top 3 title, FirstName, LastName from Person.Contact FOR XML RAW XML_F52E2B61-18A1-11d1-B105-00805F49916B <row title="Mr." FirstName="Gustavo" LastName="Achong"/> <row title="Ms." FirstName="Catherine" LastName="Abel"/> <row title="Ms." FirstName="Kim" LastName="Abercrombie"/> (5 row(s) affected) NOTE The T-SQL code in the preceding listing is designed to work with Person.Contact table in the AdventureWorks sample database. Chapter 7: Developing with XML 237 For XML Auto The For XML Auto mode provides more flexibility in terms of the tags that are returned by a SQL statement. However, it is still limited in the structure of the XML results that are generated. By default, the SQL Server Table or View name is used as the element name, and column names are used as the attributes for each element. You can use the Elements directive to specify that each column is made into a child element. Nesting of elements is controlled by the order of the columns used in the Select statement. While the results of Auto mode won’t produce XML documents that conform to industry standards, they do support loosely coupled systems and can be used for simple B2B transfers. The following listing presents an example of using the For XML Auto mode: SELECT Top 3 title, FirstName, LastName from Person.Contact FOR XML AUTO XML_F52E2B61-18A1-11d1-B105-00805F49916B <Person.Contact title="Mr." FirstName="Gustavo" LastName="Achong"/> <Person.Contact title="Ms." FirstName="Catherine" LastName="Abel"/> <Person.Contact title="Ms." FirstName="Kim" LastName="Abercrombie"/> (3 row(s) affected) For XML Explicit The For XML Explicit mode produces the most flexible results and can be used to meet complex requirements. Explicit mode affords you complete control over the names of the tags and the hierarchy and nesting of the elements produced. Columns can be individually mapped to various elements or attributes. However, the For Explicit mode requires the use of complex SQL queries that must specify the structure of a universal table that describes the desired XML document. The syntax required by Explicit mode is demanding, and it’s up to you to make sure that the XML that’s generated is well formed and valid. Explicit mode’s flexibility allows it to meet the needs for many industry-standard message specifications. The EXPLICIT mode is implemented through UNION ALL queries, which essentially combine results of two or more queries. Each query must contain the same number of columns, and the corresponding columns in each query need to have compatible data types. The XML hierarchy is defined by the top or parent query. 238 Microsoft SQL Server 2005 Developer’s Guide The subsequent queries retrieve data for each of the XML nodes. The following listing shows an example of using the FOR XML EXPLICT mode: SELECT Top 3 1 as Tag, NULL as Parent, EmployeeID as [Employee!1!Employee_ID], NULL as [Name!2!Last_Name!ELEMENT], NULL as [Name!2!First_Name!ELEMENT] FROM HumanResources.Employee E, Person.Contact C WHERE E.ContactID = C.ContactID UNION ALL SELECT Top 3 2 as Tag, 1 as Parent, EmployeeID, LastName, FirstName FROM HumanResources.Employee E, Person.Contact C WHERE E.ContactID = C.ContactID ORDER BY [Employee!1!Employee_ID] FOR XML EXPLICIT This query describes a two-level hierarchy. The first query retrieves the values for the Employee element, and the second query retrieves the values for the Name element. The Top 3 clause is simply used to limit the size of the result set. In the first query you’ll notice the ELEMENT directive is used to specify that the results are output as XML elements rather than attributes. The values prior to the ELEMENT directive state the parent element’s name, the element level, and finally the element name that will be created. As you can see in the following listing, the FOR XML EXCPLICIT mode gives you more control over the output of the query; however, you pay the price of added complexity: <Employee Employee_ID="1"> <Name> <Last_Name>Gilbert</Last_Name> <First_Name>Guy</First_Name> </Name> </Employee> <Employee Employee_ID="2"> . an associated schema, named MyXMLDocSchema. In this 234 Microsoft SQL Server 2005 Developer’s Guide example, you can see how SQL Server 2005 easily integrates relational column data with XML. http://www.w3.org/ TR/2004/WD-xquery-20040723/. The SQL Server 2005 Books Online also has an introduction to the XQuery language. XML Data Type Methods SQL Server 2005 provides several new built-in methods. However, they aren’t as flexible as T -SQL. The FLWR (For-Let-Where-Return) statement adds a level of flexibility to SQL Server s XQuery implementation. In SQL Server 2005, the Let clause is not supported