{"id":2300,"date":"2026-09-10T16:11:20","date_gmt":"2026-09-10T08:11:20","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2300"},"modified":"2026-03-28T12:41:14","modified_gmt":"2026-03-28T12:41:14","slug":"how-to-use-worksheetxmldataquery-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetxmldataquery-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.XmlDataQuery in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <strong>XmlDataQuery<\/strong> member of the <strong>Worksheet<\/strong> object in Excel&#8217;s object model is a method that returns a <strong>Range<\/strong> object representing the cell or cells mapped to a specific XML map data node. This is particularly useful when working with XML data mapped into an Excel worksheet, allowing you to programmatically locate and manipulate data based on its XML structure. In xlwings, you can access this functionality through the <code>api<\/code> property, which provides direct access to the underlying Excel object model.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Functionality:<\/strong><br>The primary purpose of <code>XmlDataQuery<\/code> is to query a worksheet for a range that is associated with a given XML map element or attribute. It helps in dynamically finding cells that are bound to XML data, enabling automated data processing, validation, or extraction within workbooks that use XML maps.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax in xlwings:<\/strong><br>The method is called via the worksheet&#8217;s API object. The general syntax is:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>range_object = worksheet.api.XmlDataQuery(XPath, SelectionNamespaces, Map)<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>XPath<\/strong> (required, string): The XPath expression that specifies the XML map node. This can be an absolute path to an element or attribute.<\/li>\n\n\n\n<li><strong>SelectionNamespaces<\/strong> (optional, string): A space-delimited string of namespace declarations used in the XPath. It is required if the XPath contains namespaces. For example: <code>\"xmlns:ns='http:\/\/example.com\/namespace'\"<\/code>.<\/li>\n\n\n\n<li><strong>Map<\/strong> (optional, Variant): An <strong>XmlMap<\/strong> object representing the specific XML map to query. If omitted, Excel uses all maps in the workbook. You can pass an <code>XmlMap<\/code> object obtained via <code>workbook.api.XmlMaps(index_or_name)<\/code>.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">The method returns a <code>Range<\/code> object (or <code>None<\/code> if no matching range is found), which you can then use with xlwings for further operations.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example:<\/strong><br>Suppose you have an XML map in your workbook with data mapped to a worksheet, and you want to find the cell containing the &#8220;Price&#8221; element. Here\u2019s how you might use <code>XmlDataQuery<\/code> with xlwings:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active workbook and sheet\nwb = xw.books.active\nws = wb.sheets&#91;'Sheet1']\n\n# Define the XPath for the XML node (e.g., an element named 'Price')\nxpath = \"\/Invoice\/Items\/Item\/Price\"\n\n# Optionally, define namespaces if needed (e.g., for a namespace 'ns')\nnamespaces = \"xmlns:ns='http:\/\/schemas.example.com\/invoice'\"\n\n# Query for the range\ntry:\n    # Use the api to call XmlDataQuery\n    target_range = ws.api.XmlDataQuery(XPath=xpath, SelectionNamespaces=namespaces)\n    if target_range is not None:\n        # Convert to xlwings range for easier manipulation\n        xl_range = xw.Range(target_range)\n        print(f\"Found data at cell: {xl_range.address}\")\n        print(f\"Cell value: {xl_range.value}\")\n    else:\n        print(\"No matching range found.\")\nexcept Exception as e:\n    print(f\"Error querying XML data: {e}\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The **XmlDataQuery** member of the **Worksheet** object in Excel&apos;s object model is a method that ret&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2300","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2300","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2300"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2300\/revisions"}],"predecessor-version":[{"id":3508,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2300\/revisions\/3508"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2300"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2300"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2300"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}