{"id":2056,"date":"2026-05-11T16:30:20","date_gmt":"2026-05-11T08:30:20","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2056"},"modified":"2026-03-28T05:53:54","modified_gmt":"2026-03-28T05:53:54","slug":"how-to-use-applicationclusterconnector-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-applicationclusterconnector-in-the-xlwings-api-way\/","title":{"rendered":"How to use Application.ClusterConnector in the xlwings API way"},"content":{"rendered":"\n

The ClusterConnector<\/strong> member of the Application<\/strong> object in Excel’s object model is a specialized interface for managing connections to Power Pivot data models in a clustered environment, such as SQL Server Analysis Services (SSAS) tabular models. In xlwings, this provides programmatic control over how Excel interacts with these external data sources, enabling automation of data refresh and connection management within a workbook. This is particularly useful in enterprise scenarios where data models are hosted on scalable, high-availability servers.<\/p>\n\n\n\n

Syntax in xlwings:<\/strong>
The property is accessed through the Application<\/code> object. In xlwings, the Application<\/code> is typically represented by the app<\/code> object when you instantiate Excel.<\/p>\n\n\n\n

app.api.ActiveWorkbook.ClusterConnector<\/code><\/pre>\n\n\n\n
Note: ClusterConnector<\/code> is a property that returns a WorkbookConnection<\/strong> object when the active workbook is connected to a Power Pivot model in a cluster. It is not a method. This property is read-only in the context of xlwings via the Excel API.<\/p>\n\n\n\n
Key Functionality and Usage:<\/strong>
The primary purpose is to retrieve the connection string and details of the clustered Power Pivot connection. You can inspect properties like OLEDBConnection.Server<\/code> and OLEDBConnection.Connection<\/code> to understand the data source. This allows for verification or logging of connection parameters. It’s important to note that directly modifying the ClusterConnector<\/code> via xlwings is limited; its main use is for informational purposes or to trigger a refresh of the connected model.<\/p>\n\n\n\n
Code Examples:<\/strong><\/p>\n\n\n\n
    \n
  1. Retrieving Cluster Connection Details:<\/strong>
    This example checks if the active workbook has a cluster connector and prints its server name and connection string.<\/li>\n<\/ol>\n\n\n\n
    import xlwings as xw\n\n# Connect to the active Excel instance\napp = xw.apps.active\n\n# Ensure a workbook is active\nif app.books.active is not None:\n    wb = app.books.active\n    try:\n        # Access the ClusterConnector property\n        cluster_conn = wb.api.ClusterConnector\n\n        # Get the OLEDB connection details\n        oledb_conn = cluster_conn.OLEDBConnection\n        print(f\"Server: {oledb_conn.Server}\")\n        print(f\"Connection String: {oledb_conn.Connection}\")\n\n        # Check if it's a Power Pivot connection\n        if cluster_conn.Type == 5: # xlConnectionTypeOLEDB for Power Pivot\n        print(\"This is a Power Pivot cluster connection.\")\n    except AttributeError:\n        print(\"No active Power Pivot cluster connection found in this workbook.\")<\/code><\/pre>\n\n\n\n
      \n
    1. Refreshing Data via Cluster Connection:<\/strong>
      This example refreshes all data connections, including the Power Pivot model connected through the cluster.<\/li>\n<\/ol>\n\n\n\n
      import xlwings as xw\n\napp = xw.apps.active\nwb = app.books.active\n\n# Refresh all data in the workbook, which includes the cluster-connected model\nwb.api.RefreshAll()\n\n# Alternatively, refresh a specific connection if known\n# wb.connections[\"YourConnectionName\"].Refresh()<\/code><\/pre>\n\n\n\n
      Important Notes:<\/strong><\/p>\n\n\n\n
        \n
      • The ClusterConnector<\/code> property is only available if the workbook contains a Power Pivot data model connected to an SSAS cluster. Otherwise, accessing it may raise an AttributeError<\/code>.<\/li>\n\n\n\n
      • In xlwings, you interact with this through the underlying Excel API (.api<\/code> attribute), so a solid understanding of the Excel object model is beneficial.<\/li>\n\n\n\n
      • For automation, common tasks involve refreshing data, but direct manipulation of cluster settings (like changing the server) is typically done through Excel’s UI or server-side configuration, not via this property in xlwings.<\/li>\n<\/ul>\n\n\n\n
        <\/p>\n","protected":false},"excerpt":{"rendered":"
        The **ClusterConnector** member of the **Application** object in Excel's object model is a specializ…<\/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-2056","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2056","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=2056"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2056\/revisions"}],"predecessor-version":[{"id":3146,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2056\/revisions\/3146"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2056"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2056"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2056"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}