Академический Документы
Профессиональный Документы
Культура Документы
Syntax
Arguments
idoc
Is the document handle of the internal representation of an XML document. The internal representation of
an XML document is created by calling sp_xml_preparedocument.
rowpattern
Is the XPath pattern used to identify the nodes (in the XML document whose handle is passed in the idoc
parameter) to be processed as rows.
flags
Indicates the mapping that should be used between the XML data and the relational rowset, and how the
spill-over column should be filled. flags is an optional input parameter, and can be one of these values.
Byte
Value Description
SchemaDeclaration
ColName
Is the column name in the rowset.
ColType
Is the SQL data type of the column in the rowset. If the column types differ from the underlying
XML data type of the attribute, type coercion occurs. If the column is of type timestamp, the
present value in the XML document is disregarded when selecting from an OPENXML rowset, and the
autofill values are returned.
ColPattern
Is an optional, general XPath pattern that describes how the XML nodes should be mapped to the
columns. If the ColPattern is not specified, the default mapping (attribute-centric or element-centric
mapping as specified by flags) takes place.
The XPath pattern specified as ColPattern is used to specify the special nature of the mapping (in case of
attribute-centric and element-centric mapping) that overwrites or enhances the default mapping indicated
by flags.
The general XPath pattern specified as ColPattern also supports the metaproperties.
MetaProperty
Is one of the metaproperties provided by OPENXML. If the metaproperty is specified, the column
contains information provided by the metaproperty. The metaproperties allow you to extract
information (such as relative position, , namespace information) about XML nodes, which provides
more information than is visible in the textual representation.
TableName
Is the table name that can be given (instead of SchemaDeclaration) if a table with the desired schema
already exists and no column patterns are required.
The WITH clause provides a rowset format (and additional mapping information as necessary) using either
SchemaDeclaration or specifying an existing TableName. If the optional WITH clause is not specified, the
results are returned in an edge table format. Edge tables represent the fine-grained XML document
structure (e.g. element/attribute names, the document hierarchy, the namespaces, PIs etc.) in a single
table.
parentid bigint Identifies the parent of the node. The parent identified by this ID is not
necessarily the parent element, but it depends on the NodeType of the
node whose parent is identified by this ID. For example, if the node is
a text node, the parent of it may be an attribute node.
If the node is at the top level in the XML document, its ParentID is
NULL.
nodetype int Identifies the node type. Is an integer that corresponds to the XML
DOM node type numbering (see DOM for node information).
The node types are:
1 = Element node
2 = Attribute node
3 = Text node
localname nvarchar Gives the local name of the element or attribute. Is NULL if the DOM
object does not have a name.
namespaceuri nvarchar Is the namespace URI of the node. If the value is NULL, no namespace
is present.
datatype nvarchar Is the actual data type of the element or attribute row and is NULL
otherwise. The data type is inferred from the inline DTD or from the
inline schema.
prev bigint Is the XML ID of the previous sibling element. Is NULL if there is no
direct previous sibling.
text ntext Contains the attribute value or the element content in text form (or is
NULL if the edge table entry does not need a value).
Examples
This example creates an internal representation of the XML image using sp_xml_preparedocument. A
SELECT statement using an OPENXML rowset provider is then executed against the internal representation
of the XML document.
The flag value is set to 1 indicating attribute-centric mapping. Therefore, the XML attributes map to the
columns in the rowset. The rowpattern specified as /ROOT/Customers identifies the <Customers> nodes
to be processed.
The optional ColPattern (column pattern) is not specified because the column name matches the XML
attribute names.
The OPENXML rowset provider creates a two-column rowset (CustomerID and ContactName) from which
the SELECT statement retrieves the necessary columns (in this case, all the columns).
If the same SELECT statement is executed with flags set to 2, indicating element-centric mapping, the
values of CustomerID and ContactName for both of the customers in the XML document are returned as
NULL, because the <Customers> elements do not have any subelements.
CustomerID ContactName
---------- -----------
NULL NULL
NULL NULL
B. Specify ColPattern for mapping between columns and the XML attributes
This query returns customer ID, order date, product ID and quantity attributes from the XML document. The
rowpattern identifies the <OrderDetails> elements. ProductID and Quantity are the attributes of the
<OrderDetails> element. However, the OrderID, CustomerID and OrderDate are the attributes of the
parent element (<Orders>).
• The OrderID, CustomerID and OrderDate in the rowset map to the attributes of the parent of the
• The ProdID column in the rowset maps to the ProductID attribute, and the Qty column in the rowset
Although the element-centric mapping is specified by the flags parameter, the mapping specified in
ColPattern overwrites this mapping.
------------------------------------------------------------------------
In this example, the WITH clause is not specified in the OPENXML statement. As a result, the rowset
generated by OPENXML has an edge table format. The SELECT statement returns all the columns in the edge
table.
The sample XML document in the example consists of <Customers>, <Orders>, and
<Order_0020_Details> elements.
First sp_xml_preparedocument is called to obtain a document handle. This document handle is passed to
OPENXML.
• The WITH clause is not provided. Therefore OPENXML returns the rowset in an edge table format.
Finally the SELECT statement retrieves all the columns in the edge table.
See Also
Examples
In retrieving the data, rowpattern is used to identify the nodes in the XML document that determine the
rows. rowpattern is expressed in the XPath pattern language used in the MSXML XPath implementation. For
example, if the pattern ends in an element or an attribute, a row is created for each element or attribute
node selected by rowpattern.
The flags value provides default mapping. In the SchemaDeclaration, if no ColPattern is specified, the
mapping specified in flags is assumed. The flags value is ignored if ColPattern is specified in
SchemaDeclaration. The specified ColPattern determines the mapping (attribute-centric or element-
centric) and also the behavior in dealing with overflow and unconsumed data.
The XML document in this example consists of the <Customer>, <Order>, and <OrderDetail> elements.
The OPENXML statement retrieves customer information in a two-column rowset (CustomerID and
ContactName) from the XML document.
First, the sp_xml_preparedocument stored procedure is called to obtain a document handle. This
document handle is passed to OPENXML.
• The flags parameter value is set to 1 indicating attribute-centric mapping. As a result, the XML
• In SchemaDeclaration (in the WITH clause), the specified ColName values match the corresponding
XML attribute names. Therefore, the ColPattern parameter is not specified in SchemaDeclaration.
And then, the SELECT statement retrieves all the columns in the rowset provided by OPENXML.
CustomerID ContactName
---------- --------------------
VINET Paul Henriot
LILAS Carlos Gonzlez
If the same SELECT statement is executed with flags set to 2, indicating element-centric mapping,
because <Customer> elements do not have any subelements, the values of CustomerID and
ContactName for both the customers are returned as NULL.
If in the XML document, the <CustomerID> and <ContactName> are subelements, the element-centric
mapping retrieves the values.
CustomerID ContactName
---------- --------------------
VINET Paul Henriot
LILAS Carlos Gonzlez
B. Specify ColPattern for mapping between rowset columns and the XML attributes/elements
This example shows how the XPath pattern is specified in the optional ColPattern parameter to provide
mapping between rowset columns and the XML attributes (and elements).
The XML document in this example consists of the <Customer>, <Order>, and <OrderDetail> elements.
The OPENXML statement retrieves customer and order information as a rowset (CustomerID, OrderDate,
ProdID, and Qty) from the XML document.
First, the sp_xml_preparedocument stored procedure is called to obtain a document handle. This
document handle is passed to OPENXML.
• For illustration purposes, the flags parameter value is set to 2 indicating element-centric mapping.
However, the mapping specified in ColPattern overwrites this mapping (the XPath pattern specified in
ColPattern maps the columns in the rowset to attributes thus resulting in an attribute-centric
mapping).
In SchemaDeclaration (in the WITH clause), ColPattern is also specified with the ColName and ColType
parameters. The optional ColPattern is the XPath pattern specified to indicate:
• The OrderID, CustomerID, and OrderDate columns in the rowset map to the attributes of the
parent of the nodes identified by rowpattern. rowpattern identifies the <OrderDetail> nodes.
Therefore, the CustomerID and OrderDate columns map to CustomerID and OrderDate attributes
of the <Order> element.
• The ProdID and Qty columns in the rowset map to the ProductID and Quantity attributes of the
And then the SELECT statement retrieves all the columns in the rowset provided by OPENXML.
The XPath pattern specified as ColPattern can also be specified to map the XML elements to the rowset
columns (resulting in element-centric mapping). In the following example, the XML document
<CustomerID> and <OrderDate> are subelements of <Orders> element. Because ColPattern overwrites the
mapping specified in flags parameter, the flags parameter is not specified in OPENXML.
In this example, the flags parameter is set to 3, indicating that both attribute-centric and element-
centric mapping is to be applied. In this case, the attribute-centric mapping is applied first, and then
element-centric mapping is applied for all the columns not yet dealt with.
CustomerID ContactName
---------- --------------------
VINET Paul Henriot
LILAS Carlos Gonzlez
The attribute-centric mapping is applied for CustomerID. There is no ContactName attribute in the
<Customers> element; therefore, element-centric mapping is applied.
The XML document in this example consists of the <Customer> and <Order> elements. The OPENXML
statement retrieves a rowset consisting of the oid attribute from the <Order> element, the ID of the parent
of the node (identified by rowpattern), and the leaf-value string of the element content.
First, the sp_xml_preparedocument stored procedure is called to obtain a document handle. This
document handle is passed to OPENXML.
• The flags parameter value is set to 1, indicating attribute-centric mapping. As a result, the XML
• In SchemaDeclaration (in the WITH clause), the rowset column names, oid and amount, match the
corresponding XML attribute names. Therefore, the ColPattern parameter is not specified. For the
comment column in the rowset, the XPath function (text()) is specified as ColPattern. This overwrites
the attribute-centric mapping specified in flags, and the column contains the leaf-value string of the
element content.
And then, the SELECT statement retrieves all the columns in the rowset provided by OPENXML.
This example specifies TableName in the WITH clause instead of SchemaDeclaration in the WITH clause.
This is useful if you have a table with the structure you want and no column patterns (ColPattern parameter)
are required.
The XML document in this example consists of the <Customer> and <Order> elements. The OPENXML
statement retrieves order information in a three-column rowset (oid, date, and amount) from the XML
document.
First, the sp_xml_preparedocument stored procedure is called to obtain a document handle. This
document handle is passed to OPENXML.
• There is no SchemaDeclaration in the WITH clause. Instead, a table name is specified. Therefore, the
• The flags parameter value is set to 1, indicating attribute-centric mapping. Therefore, attributes of
the elements (identified by rowpattern) map to the rowset columns with the same name.
And then the SELECT statement retrieves all the columns in the rowset provided by OPENXML.
In this example, the WITH clause is not specified in the OPENXML statement. As a result, the rowset
generated by OPENXML has an edge table format. The SELECT statement returns all the columns in the edge
table.
The sample XML document in the example consists of the <Customer>, <Order>, and <OrderDetail>
elements.
First, the sp_xml_preparedocument stored procedure is called to obtain a document handle. This
document handle is passed to OPENXML.
• The WITH clause is not provided; therefore, OPENXML returns the rowset in an edge table format.
And then the SELECT statement retrieves all the columns in the edge table.
The result is returned as an edge table. You can write queries against the edge table to obtain information:
• The following query returns the number of Customer nodes in the document. Because the WITH
clause is not specified, OPENXML returns an edge table. The SELECT statement queries the edge table.
• SELECT count(*)
• FROM OPENXML(@idoc, '/')
• WHERE localname = 'Customer'
• This query returns local names of XML nodes of element type.
The XML document in this example consists of the <Customer>, <Order>, and <OrderDetail> elements.
The OPENXML statement retrieves order details information in a three-column rowset (ProductID,
Quantity, and OrderID) from the XML document.
First, the sp_xml_preparedocument is called to obtain a document handle. This document handle is
passed to OPENXML.
In the OPENXML statement:
(ProductID). In the resulting rowset, a row is created for each attribute node selected in the XML
document.
• In this example, the flags parameter is not specified. Instead, the mappings are specified by the
ColPattern parameter.
In SchemaDeclaration (in the WITH clause), ColPattern is also specified with the ColName and ColType
parameters. The optional ColPattern is the XPath pattern specified to indicate:
• The XPath pattern (.) specified as ColPattern for the ProdID column in the rowset identifies the
context node (current node). As per the rowpattern specified, it is the ProductID attribute of the
<OrderDetail> element.
• The ColPattern, ../@Quantity, specified for the Qty column in the rowset identifies the Quantity
• Similarly, the ColPattern, ../../@OrderID, specified for the OID column in the rowset identifies the
OrderID attribute of the parent (<Order>) of the parent (<OrderDetail>) node of the context node
(<ProductID>).
And then, the SELECT statement retrieves all the columns in the rowset provided by OPENXML.
If you have multiple text nodes in an XML document, a SELECT statement with a ColPattern (text()) returns
only the first text node instead of all. For example:
DECLARE @h int
EXEC sp_xml_preparedocument @h OUTPUT,
N'
<root xmlns:a="urn:1">
<a:Elem abar="asdf">
T<a>a</a>U
</a:Elem>
</root>',
'<ns xmlns:b="urn:1" />'
An XML document can have attributes that are multivalued. For example the IDREFS attribute can be
multivalued. In an XML document, the multivalued attribute values are specified as a string with the values
separated by a space. In the following XML document, the attends attribute of the <Student> element and
the attendedBy attribute of <Class> are multivalued. Retrieving individual values from a multivalued XML
attribute and storing each value in a separate row in the database requires additional work. This example
shows the process.
• <Student>
Consists of id (student ID), name, and attends attributes. The attends attribute is a multivalued
attribute.
• <Class>
Consists of id (class ID), name, and attendedBy attributes. The attendedBy attribute is a
multivalued attribute.
This attends attribute in <Student> and the attendedBy attribute in <Class> represent a m:n relationship
between Student and Class tables. A student can take many classes and a class can have many students.
Assume you want to shred this document and save it in the database as follows:
• Save he m:n relationship data (between Student and Class) in the CourseAttendence table.
Additional work is required to extract the values. To retrieve this information and store it in the table,
use these stored procedures:
• Insert_Idrefs_Values
• Extract_idrefs_values
Extracts the individual student IDs from each <Course> element. An edge table is used to retrieve
these values.
86 . DECLARE @h int
87 . EXECUTE sp_xml_preparedocument @h OUTPUT, '
88 . <Data>
89 . <Student id = "s1" name = "Student1" attends = "c1 c3 c6" />
90 . <Student id = "s2" name = "Student2" attends = "c2 c4" />
91 . <Student id = "s3" name = "Student3" attends = "c2 c4 c6" />
92 . <Student id = "s4" name = "Student4" attends = "c1 c3 c5" />
93 . <Student id = "s5" name = "Student5" attends = "c1 c3 c5 c6" />
94 . <Student id = "s6" name = "Student6" />
95 .
96 . <Class id = "c1" name = "Intro to Programming"
97 . attendedBy = "s1 s4 s5" />
98 . <Class id = "c2" name = "Databases"
99 . attendedBy = "s2 s3" />
100 . <Class id = "c3" name = "Operating Systems"
101 . attendedBy = "s1 s4 s5" />
102 . <Class id = "c4" name = "Networks" attendedBy = "s2 s3" />
103 . <Class id = "c5" name = "Algorithms and Graphs"
104 . attendedBy = "s4 s5"/>
105 . <Class id = "c6" name = "Power and Pragmatism"
106 . attendedBy = "s1 s3 s5" />
107 .</Data>'
108 .
109 .INSERT INTO Students SELECT * FROM OPENXML(@h, '//Student') WITH
Students
110 .
111 .INSERT INTO Courses SELECT * FROM OPENXML(@h, '//Class') WITH
Courses
112 ./* Using the edge table */
113 .EXECUTE fill_idrefs @h, '//Class', 'id', 'attendedby',
'CourseAttendance'
114 .
115 .SELECT * FROM Students
116 .SELECT * FROM Courses
117 .SELECT * FROM CourseAttendance
118 .
119 .EXECUTE sp_xml_removedocument @h
See Also
sp_xml_preparedocument [ http://msdn2.microsoft.com/en-us/library/aa260385(SQL.80,printer).aspx ]
sp_xml_removedocument [ http://msdn2.microsoft.com/en-us/library/aa260386(SQL.80,printer).aspx ]
OPENXML [ http://msdn2.microsoft.com/en-us/library/aa276847(SQL.80,printer).aspx ]
sp_xml_preparedocument returns a handle that can be used to access the newly created internal
representation of the XML document. This handle is valid for the duration of the connection to Microsoft®
SQL Server™ 2000, until the connection is reset, or until the handle is invalidated by executing
sp_xml_removedocument.
Note A parsed document is stored in the internal cache of SQL Server 2000. The MSXML parser uses one-
eighth the total memory available for SQL Server. To avoid running out of memory, run
sp_xml_removedocument to free up the memory.
Syntax
Arguments
hdoc
[xmltext]
Is the original XML document. The MSXML parser parses this XML document. xmltext is a text (char,
nchar, varchar, nvarchar, text, or ntext) parameter. The default value is NULL, in which case an internal
representation of an empty XML document is created.
[xpath_namespaces]
Specifies the namespace declarations that are used in row and column XPath expressions in OPENXML. The
default value is <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">.
xpath_namespaces provides the namespace URIs for the prefixes used in the XPath expressions in OPENXML
by means of a well-formed XML document. xpath_namespaces declares the prefix that must be used to refer
to the namespace urn:schemas-microsoft-com:xml-metaprop, which provides meta data about the
parsed XML elements. Although you can redefine the namespace prefix for the metaproperty namespace
using this technique, this namespace is not lost. The prefix mp is still valid for urn:schemas-microsoft-
com:xml-metaprop even if xpath_namespaces contains no such declaration. xpath_namespaces is a text
(char, nchar, varchar, nvarchar, text, or ntext) parameter.
Permissions
This example returns a handle to the newly created internal representation of the XML document that is
provided as input. In the call to sp_xml_preparedocument, a default namespace prefix mapping is used.
This example returns a handle to the newly created internal representation of the XML document that is
provided as input. The stored procedure validates the document loaded against the DTD included in the
document. In the call to sp_xml_preparedocument, a default namespace prefix mapping is used.
See Also
sp_xml_removedocument [ http://msdn2.microsoft.com/en-us/library/aa260386(SQL.80,printer).aspx ]
©2008 Microsoft Corporation. All rights reserved.
Note A parsed document is stored in the internal cache of Microsoft® SQL Server™ 2000. The MSXML
parser uses one-eighth the total memory available for SQL Server. To avoid running out of memory, run
sp_xml_removedocument to free up the memory.
Syntax
sp_xml_removedocument hdoc
Arguments
hdoc
Is the handle to the newly created document. An invalid handle returns an error. hdoc is an integer.
Permissions
Examples
This example removes the internal representation of an XML document. The handle to the document is
provided as input.
See Also
sp_xml_preparedocument [ http://msdn2.microsoft.com/en-us/library/aa260385(SQL.80,printer).aspx ]