Skip to content

Commit 829215d

Browse files
rwestMSFTrwestMSFT
committed
Refresh OPENXML article and fix text (UUF 262035)
1 parent 3d1aaf0 commit 829215d

File tree

1 file changed

+42
-42
lines changed

1 file changed

+42
-42
lines changed

‎docs/t-sql/functions/openxml-transact-sql.md

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
22
title: "OPENXML (Transact-SQL)"
3-
description: "OPENXML provides a rowset view over an XML document."
3+
description: OPENXML provides a rowset view over an XML document.
44
author: MikeRayMSFT
55
ms.author: mikeray
66
ms.reviewer: randolphwest
7-
ms.date: 05/04/2023
7+
ms.date: 06/20/2024
88
ms.service: sql
99
ms.subservice: t-sql
1010
ms.topic: reference
@@ -22,7 +22,7 @@ dev_langs:
2222

2323
[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance](../../includes/applies-to-version/sql-asdb-asdbmi.md)]
2424

25-
OPENXML provides a rowset view over an XML document. Because OPENXML is a rowset provider, OPENXML can be used in [!INCLUDE[tsql](../../includes/tsql-md.md)] statements in which rowset providers such as a table, view, or the OPENROWSET function can appear.
25+
`OPENXML` provides a rowset view over an XML document. Because `OPENXML` is a rowset provider, `OPENXML` can be used in [!INCLUDE [tsql](../../includes/tsql-md.md)] statements in which rowset providers such as a table, view, or the `OPENROWSET` function can appear.
2626

2727
:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
2828

@@ -35,7 +35,7 @@ OPENXML ( idoc int [ in ]
3535
[ WITH ( SchemaDeclaration | TableName ) ]
3636
```
3737

38-
[!INCLUDE[sql-server-tsql-previous-offline-documentation](../../includes/sql-server-tsql-previous-offline-documentation.md)]
38+
[!INCLUDE [sql-server-tsql-previous-offline-documentation](../../includes/sql-server-tsql-previous-offline-documentation.md)]
3939

4040
## Arguments
4141

@@ -53,64 +53,64 @@ Indicates the mapping used between the XML data and the relational rowset, and h
5353

5454
| Byte value | Description |
5555
| --- | --- |
56-
| **0** | Defaults to **attribute-centric** mapping. |
57-
| **1** | Use the **attribute-centric** mapping. Can be combined with XML_ELEMENTS. In this case, **attribute-centric** mapping is applied first. Next, **element-centric** mapping is applied for any remaining columns. |
58-
| **2** | Use the **element-centric** mapping. Can be combined with XML_ATTRIBUTES. In this case, **attribute-centric** mapping is applied first. Next, **element-centric** mapping is applied for any remaining columns. |
59-
| **8** | Can be combined (logical OR) with XML_ATTRIBUTES or XML_ELEMENTS. In the context of retrieval, this flag indicates that the consumed data shouldn't be copied to the overflow property `@mp:xmltext`. |
56+
| `0` | Defaults to `attribute-centric` mapping. |
57+
| `1` | Use the `attribute-centric` mapping. Can be combined with `XML_ELEMENTS`. In this case, `attribute-centric` mapping is applied first. Next, `element-centric` mapping is applied for any remaining columns. |
58+
| `2` | Use the `element-centric` mapping. Can be combined with `XML_ATTRIBUTES`. In this case, `element-centric` mapping is applied first. Next, `attribute-centric` mapping is applied for any remaining columns. |
59+
| `8` | Can be combined (logical OR) with `XML_ATTRIBUTES` or `XML_ELEMENTS`. In the context of retrieval, this flag indicates that the consumed data shouldn't be copied to the overflow property `@mp:xmltext`. |
6060

61-
#### SchemaDeclaration
61+
#### *SchemaDeclaration*
6262

63-
Is the schema definition of the form: *ColNameColType* [ *ColPattern* | *MetaProperty* ] [ , *ColNameColType* [ *ColPattern* | *MetaProperty* ] ... ]
63+
A schema definition of the form: *ColNameColType* [ *ColPattern* | *MetaProperty* ] [ , *ColNameColType* [ *ColPattern* | *MetaProperty* ] ... ]
6464

6565
- *ColName*
6666

6767
The column name in the rowset.
6868

6969
- *ColType*
7070

71-
The [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] 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.
71+
The [!INCLUDE [ssNoVersion](../../includes/ssnoversion-md.md)] 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.
7272

7373
- *ColPattern*
7474

75-
An optional, general XPath pattern that describes how the XML nodes should be mapped to the columns. If *ColPattern* isn't specified, the default mapping (**attribute-centric** or **element-centric** mapping as specified by *flags*) takes place.
75+
An optional, general XPath pattern that describes how the XML nodes should be mapped to the columns. If *ColPattern* isn't specified, the default mapping (`attribute-centric` or `element-centric` mapping as specified by *flags*) takes place.
7676

77-
The XPath pattern specified as *ColPattern* is used to specify the special nature of the mapping (for **attribute-centric** and **element-centric** mapping) that overwrites or enhances the default mapping indicated by *flags*.
77+
The XPath pattern specified as *ColPattern* is used to specify the special nature of the mapping (for `attribute-centric` and `element-centric` mapping) that overwrites or enhances the default mapping indicated by *flags*.
7878

7979
The general XPath pattern specified as *ColPattern* also supports the metaproperties.
8080

8181
- *MetaProperty*
8282

83-
One of the metaproperties provided by OPENXML. If *MetaProperty* is specified, the column contains information provided by the metaproperty. The metaproperties allow you to extract information (such as relative position and namespace information) about XML nodes. These metaproperties provide more information than is visible in the textual representation.
83+
One of the metaproperties provided by `OPENXML`. If *MetaProperty* is specified, the column contains information provided by the metaproperty. The metaproperties allow you to extract information (such as relative position and namespace information) about XML nodes. These metaproperties provide more information than is visible in the textual representation.
8484

8585
#### *TableName*
8686

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

8989
## Remarks
9090

91-
The WITH clause provides a rowset format (and additional mapping information as required) by using either *SchemaDeclaration* or specifying an existing *TableName*. If the optional WITH clause isn't specified, the results are returned in an **edge** table format. Edge tables represent the fine-grained XML document structure (such as element/attribute names, the document hierarchy, the namespaces, PIs, and so on) in a single table.
91+
The `WITH` clause provides a rowset format (and additional mapping information as required) by using either *SchemaDeclaration* or specifying an existing *TableName*. If the optional `WITH` clause isn't specified, the results are returned in an **edge** table format. Edge tables represent the fine-grained XML document structure (such as element/attribute names, the document hierarchy, the namespaces, PIs, and so on) in a single table.
9292

9393
The following table describes the structure of the **edge** table.
9494

9595
| Column name | Data type | Description |
9696
| --- | --- | --- |
97-
| **id** | **bigint** | The unique ID of the document node.<br /><br />The root element has an ID value 0. The negative ID values are reserved. |
98-
| **parentid** | **bigint** | Identifies the parent of the node. The parent identified by this ID isn't 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.<br /><br />If the node is at the top level in the XML document, its **ParentID** is NULL. |
99-
| **nodetype** | **int** | Identifies the node type. Is an integer that corresponds to the XML DOM node type numbering.<br /><br />The node types are:<br /><br />1 = Element node<br /><br />2 = Attribute node<br /><br />3 = Text node |
100-
| **localname** | **nvarchar** | Gives the local name of the element or attribute. Is NULL if the DOM object doesn't have a name. |
101-
| **prefix** | **nvarchar** | The namespace prefix of the node name. |
102-
| **namespaceuri** | **nvarchar** | The namespace URI of the node. If the value is NULL, no namespace is present. |
103-
| **datatype** | **nvarchar** | The actual data type of the element or attribute row, otherwise is NULL. The data type is inferred from the inline DTD or from the inline schema. |
104-
| **prev** | **bigint** | The XML ID of the previous sibling element. Is NULL if there is no direct previous sibling. |
105-
| **text** | **ntext** | Contains the attribute value or the element content in text form (or is NULL if the **edge** table entry doesn't require a value). |
97+
| `id` | **bigint** | The unique ID of the document node.<br /><br />The root element has an ID value `0`. The negative ID values are reserved. |
98+
| `parentid` | **bigint** | Identifies the parent of the node. The parent identified by this ID isn't 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 might be an attribute node.<br /><br />If the node is at the top level in the XML document, its `ParentID` is `NULL`. |
99+
| `nodetype` | **int** | Identifies the node type. This value is an integer that corresponds to the XML DOM node type numbering. The node types are:<br /><br />`1` = Element node<br />`2` = Attribute node<br />`3` = Text node |
100+
| `localname` | **nvarchar** | Gives the local name of the element or attribute. `NULL` if the DOM object doesn't have a name. |
101+
| `prefix` | **nvarchar** | The namespace prefix of the node name. |
102+
| `namespaceuri` | **nvarchar** | The namespace URI of the node. If the value is `NULL`, no namespace is present. |
103+
| `data type` | **nvarchar** | The actual data type of the element or attribute row, otherwise is `NULL`. The data type is inferred from the inline DTD or from the inline schema. |
104+
| `prev` | **bigint** | The XML ID of the previous sibling element. `NULL` if there's no direct previous sibling. |
105+
| `text` | **ntext** | Contains the attribute value or the element content in text form (or is `NULL` if the **edge** table entry doesn't require a value). |
106106

107107
## Examples
108108

109109
### A. Use a basic SELECT statement with OPENXML
110110

111111
The following example creates an internal representation of the XML image by using `sp_xml_preparedocument`. A `SELECT` statement that uses an `OPENXML` rowset provider is then executed against the internal representation of the XML document.
112112

113-
The *flag* value is set to `1`. This value indicates **attribute-centric** mapping. Therefore, the XML attributes map to the columns in the rowset. The *rowpattern* specified as `/ROOT/Customer` identifies the `<Customers>` nodes to be processed.
113+
The *flag* value is set to `1`. This value indicates `attribute-centric` mapping. Therefore, the XML attributes map to the columns in the rowset. The *rowpattern* specified as `/ROOT/Customer` identifies the `<Customers>` nodes to be processed.
114114

115115
The optional *ColPattern* (column pattern) parameter isn't specified because the column name matches the XML attribute names.
116116

@@ -140,12 +140,12 @@ EXEC sp_xml_preparedocument @idoc OUTPUT, @doc;
140140
-- Execute a SELECT statement that uses the OPENXML rowset provider.
141141
SELECT *
142142
FROM OPENXML(@idoc, '/ROOT/Customer', 1) WITH (
143-
CustomerID VARCHAR(10),
144-
ContactName VARCHAR(20)
145-
);
143+
CustomerID VARCHAR(10),
144+
ContactName VARCHAR(20)
145+
);
146146
```
147147

148-
[!INCLUDE[ssResult](../../includes/ssresult-md.md)]
148+
[!INCLUDE [ssResult](../../includes/ssresult-md.md)]
149149

150150
```output
151151
CustomerID ContactName
@@ -154,9 +154,9 @@ VINET Paul Henriot
154154
LILAS Carlos Gonzlez
155155
```
156156

157-
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 there aren't any elements named `CustomerID` or `ContactName` in the XML document.
157+
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 there aren't any elements named `CustomerID` or `ContactName` in the XML document.
158158

159-
[!INCLUDE[ssResult](../../includes/ssresult-md.md)]
159+
[!INCLUDE [ssResult](../../includes/ssresult-md.md)]
160160

161161
```output
162162
CustomerID ContactName
@@ -165,7 +165,7 @@ NULL NULL
165165
NULL NULL
166166
```
167167

168-
### B. Specify ColPattern for mapping between columns and the XML attributes
168+
### B. Specify *ColPattern* for mapping between columns and the XML attributes
169169

170170
The following 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, `OrderID`, `CustomerID`, and `OrderDate` are the attributes of the parent element (`<Orders>`).
171171

@@ -175,7 +175,7 @@ The optional *ColPattern* is specified for the following mappings:
175175

176176
- The `ProdID` column in the rowset maps to the `ProductID` attribute, and the `Qty` column in the rowset maps to the `Quantity` attribute of the nodes identified in *rowpattern*.
177177

178-
Although the **element-centric** mapping is specified by the *flags* parameter, the mapping specified in *ColPattern* overwrites this mapping.
178+
Although the `element-centric` mapping is specified by the *flags* parameter, the mapping specified in *ColPattern* overwrites this mapping.
179179

180180
```sql
181181
DECLARE @idoc INT, @doc VARCHAR(1000);
@@ -203,15 +203,15 @@ EXEC sp_xml_preparedocument @idoc OUTPUT, @doc;
203203
-- SELECT stmt using OPENXML rowset provider
204204
SELECT *
205205
FROM OPENXML(@idoc, '/ROOT/Customer/Order/OrderDetail', 2) WITH (
206-
OrderID INT '../@OrderID',
207-
CustomerID VARCHAR(10) '../@CustomerID',
208-
OrderDate DATETIME '../@OrderDate',
209-
ProdID INT '@ProductID',
210-
Qty INT '@Quantity'
211-
);
206+
OrderID INT '../@OrderID',
207+
CustomerID VARCHAR(10) '../@CustomerID',
208+
OrderDate DATETIME '../@OrderDate',
209+
ProdID INT '@ProductID',
210+
Qty INT '@Quantity'
211+
);
212212
```
213213

214-
[!INCLUDE[ssResult](../../includes/ssresult-md.md)]
214+
[!INCLUDE [ssResult](../../includes/ssresult-md.md)]
215215

216216
```output
217217
OrderID CustomerID OrderDate ProdID Qty
@@ -225,7 +225,7 @@ OrderID CustomerID OrderDate ProdID Qty
225225

226226
The sample XML document in the following 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`.
227227

228-
In the `OPENXML` statement, the *rowpattern* (`/ROOT/Customers`) identifies the `<Customers>` nodes to process. Because the WITH clause isn't provided, `OPENXML` returns the rowset in an **edge** table format.
228+
In the `OPENXML` statement, the *rowpattern* (`/ROOT/Customers`) identifies the `<Customers>` nodes to process. Because the `WITH` clause isn't provided, `OPENXML` returns the rowset in an **edge** table format.
229229

230230
Finally the `SELECT` statement retrieves all the columns in the **edge** table.
231231

@@ -258,6 +258,6 @@ SELECT * FROM OPENXML(@idoc, '/ROOT/Customers')
258258
EXEC sp_xml_removedocument @idoc;
259259
```
260260

261-
## See also
261+
## Related content
262262

263263
- [Examples: Using OPENXML](../../relational-databases/xml/examples-using-openxml.md)

0 commit comments

Comments
 (0)