Set up the Databricks Excel Add-in

Preview

This feature is in Public Preview.

The Databricks Excel Add-in connects your Databricks workspace to Microsoft Excel, bringing governed Lakehouse data directly into your spreadsheets to help you move from data to decisions faster. The add-in is fully supported across Excel for the web and desktop versions for both Windows and macOS.

This page describes the two methods available to set up the Databricks Excel Add-in in Microsoft Excel. This add-in uses single sign-on (SSO) authentication to connect to your Databricks workspace and supports Unity Catalog for data governance and access control.

Prerequisites

Before you install the Excel Add-in, verify that you have the following:

• Access to a Databricks workspace with Unity Catalog enabled.
• Access to a running SQL warehouse.
• Permissions to read data from Unity Catalog tables in your workspace.
• You are using one of the following versions of Excel:
  • Excel 2019 or later on Mac
  • Excel on Windows (Microsoft 365)
  • Excel on the web
  • Excel on Mac (Microsoft 365)
• If you use a firewall or a cloud security platform, allowlist the Databricks workspace URLs included in the add-in file.

Set up the add-in file

note

If you are an admin deploying the add-in through the Microsoft Marketplace, skip this section. The marketplace deployment uses PowerShell to configure workspace access instead of the add-in file. See Deploy via Microsoft Marketplace.

The add-in file is a small connector file that tells Excel exactly how to securely connect to Databricks. It acts as the digital handshake that ensures the add-in loads correctly and stays up to date every time you open Excel.

Download and set up the add-in file to use the Databricks Excel Add-in.

1. Open the add-in file by clicking the following link:

   Databricks Excel add-in file

2. Save the page as an .xml file to your local machine. In most browsers, right-click the page and select Save as, or press Ctrl+S (Windows) or Command+S (macOS).

3. Edit the add-in file by specifying your workspace URL as an <AppDomain> within the AppDomains section. Your workspace URL is the base URL you use to access your Databricks workspace in a browser. To switch between multiple Databricks workspaces, add each workspace URL to the add-in file.

   XML

   <AppDomains>
      <!-- DO NOT CHANGE -->
      <AppDomain>https://www.databricks.com</AppDomain>
      <AppDomain>https://login.databricks.com</AppDomain>
      <!-- ADD WORKSPACE URLS AS SHOWN BELOW; PUT EACH WORKSPACE URL IN ITS OWN <AppDomain> TAG  -->
      <!-- EXAMPLE -->
      <AppDomain>https://<instance1-id>.<region>.gcp.databricks.com</AppDomain>
      <AppDomain>https://<instance2-id>.<region>.gcp.databricks.com</AppDomain>
   </AppDomains>

   note

   Paste your workspace URL as plain text, without formatting. In most text editors, use Ctrl+Shift+V (Windows) or Command+Shift+V (macOS).

4. Save your changes. Verify that the file is properly formatted as an .xml file.

Option 1: Admin managed

As a global administrator, you can deploy the Databricks Excel Add-in to users in your organization. You can deploy the add-in as a custom app using the add-in file or install it from the Microsoft Marketplace.

To install the Databricks Excel Add-in as a Microsoft 365 Admin, you must have the global admin permission. As an administrator, you can determine which users in your organization can use add-ins. For more about global admins on Microsoft 365, see the Microsoft documentation.

Deploy as a custom app

Deploy the add-in using a custom manifest file. Download and set up the add-in file provided in the Prerequisites.

1. In the Microsoft 365 admin center, go to Settings > Integrated apps and click the Add-ins link.
2. Click Deploy Add-in and click Next.
3. Click Upload custom apps as the option to deploy a new add-in.
4. Select the option to upload a manifest. Click Choose File and upload the add-in file.
5. Choose which users should have access to the add-in.
6. Click Deploy.

For detailed steps about uploading the Databricks Excel Add-in, see the Microsoft documentation.

Deploy from Microsoft Marketplace

Install the add-in from the Microsoft Marketplace and use PowerShell to configure workspace access.

Prerequisites

• PowerShell is installed on your machine.
• You must run Windows PowerShell as an administrator.

Install the add-in

1. In the Microsoft 365 admin center, go to Settings > Integrated apps and click the Get Apps link.
2. Search for "Databricks Add-in for Excel".
3. Click Get it now.
4. Deploy the add-in to yourself by selecting Just me under Assign Users.
5. Click Deploy.

For detailed steps about deploying the Databricks Excel Add-in from the Microsoft Marketplace, see the Microsoft documentation.

Configure workspace access

After installing the add-in, use PowerShell to allowlist your Databricks workspace URLs.

note

The PowerShell connection to the Office 365 admin center can time out. If a command fails, reopen PowerShell and reconnect by running Connect-OrganizationAddInService.

1. Open PowerShell and run as an administrator. For more information, see the Microsoft documentation.

2. Install and import the Office 365 centralized deployment module:

   PowerShell

   Install-Module -Name O365CentralizedAddInDeployment
   Import-Module O365CentralizedAddInDeployment

3. Connect and log in to your Office 365 tenant as an admin:

   PowerShell

   Connect-OrganizationAddInService

4. Confirm that the add-in was deployed. The Databricks Add-in for Excel should appear in the list.

   PowerShell

   Get-OrganizationAddIn

   If the add-in does not appear, it might need to be redeployed or might still be deploying.

5. Allowlist Databricks workspace URLs. Replace each <workspace-url> with the URL of a workspace you want to allow. You can include as many workspace URLs as you need.

   PowerShell

   Set-OrganizationAddInOverrides -ProductId 305c35cc-5f58-46b6-8701-d611c3379a86 `
     -AppDomains "https://<workspace1-url>", "https://<workspace2-url>"

   The product ID for Databricks is 305c35cc-5f58-46b6-8701-d611c3379a86.

6. Confirm correct allowlisting. The workspace URLs you allowlisted should appear in the AppDomains section.

   PowerShell

   Get-OrganizationAddInOverrides -ProductId 305c35cc-5f58-46b6-8701-d611c3379a86

Test the add-in

1. In Excel, find the Databricks Add-in.
2. Sign in and connect to one of the workspaces you allowlisted.

note

Allowlisting changes can take a few minutes to sync. If authentication fails, confirm that you are connecting to an allowlisted workspace. If the workspace is correct, close Excel, wait a few minutes, and try again.

Deploy to your organization

1. In the Microsoft 365 admin center, go to Settings > Integrated apps.
2. Select the Databricks Add-in that you installed and configured.
3. Click the Users tab and choose whether to deploy to your entire organization or a specific group of users.

note

As an administrator, share the account name associated with the workspaces that you allowlisted with the users who plan to use the Databricks Excel Add-in. See Sign in to the add-in.

Option 2: Self-service

Installation steps vary depending on your Excel platform. Download and set up the add-in file provided in the Prerequisites.

Excel for the web

To install and connect to the Excel Add-in in Excel for the web do the following:

1. Open Excel for the web and create or open a workbook.
2. Under the Home tab, click Add-ins > Advanced.
3. Click Upload My Add-in.
4. Upload the add-in file.
5. Click Upload.
6. Find and click the Databricks Add-in from the Add-ins menu.
7. Sign in to your Databricks account. If there is an error, make sure to enable pop-up dialogs.
8. If you configured multiple workspace URLs, select the desired Databricks account name. You only need to select a specific workspace if the URLs are within the same account. For more information on account names, see Locate your account ID.

Excel Desktop (Windows)

To install the Excel Add-in in Excel Desktop for Windows, do the following:

1. Create a folder named Manifest on your local drive (for example, C:\Manifest).
2. Copy the add-in file to the C:\Manifest folder.
3. Open the folder properties and share the folder:
   1. Right-click the Manifest folder and select Properties.
   2. Click Sharing > Share and add yourself as a user with read and write permissions.
4. Open Excel Desktop.
5. Configure Excel to trust the manifest folder:
   1. Click File > Options > Trust Center > Trust Center Settings.
   2. In the sidebar, click Trusted Add-in Catalogs.
   3. In Catalog Url, enter the path to the shared folder where the add-in file is located (for example, \\YourComputerName\Manifest).
   4. Click Add catalog.
   5. Select the Show in Menu checkbox.
   6. Click OK to save your changes.
6. Restart Excel Desktop.
7. Click Add-ins > More Add-ins > Shared Folder.
8. Select the Databricks connector and click Add.
9. Click the Databricks Add-in and complete the sign-in process to your Databricks account.
10. If you configured multiple workspace URLs, select the desired Databricks account name. You only need to select a specific workspace if the URLs are within the same account. For more information on account names, see Locate your account ID.

Excel Desktop (macOS)

To install the Excel Add-in in Excel Desktop for macOS do the following:

1. Find your Microsoft Office Add-ins folder. By default, the directory is:

   /Users/<your-username>/Library/Containers/com.microsoft.Excel/Data/Documents/wef

2. Copy the add-in file to this folder.

3. Open or restart Excel Desktop.

4. In the navigation bar, click Add-ins > My Add-ins.

5. Click the Databricks Add-in.

6. Complete the sign-in process to your Databricks account.

7. If you configured multiple workspace URLs, select the desired Databricks account name. You only need to select a specific workspace if the URLs are within the same account. For more information on account names, see Locate your account ID.

Sign in to the add-in

If an administrator in your organization has deployed the Databricks Excel Add-in, sign in and connect to your Databricks workspace from Excel.

1. In Excel, under the Home tab, click the Databricks Add-in.
2. Enter your workspace URL or select a previously used workspace URL from the drop-down. The add-in remembers workspace URLs that you or your administrator have configured.
3. Click Sign in and complete the authentication process to gain access to all Databricks Excel Add-in features.

Change Databricks workspace

If your add-in file specifies multiple Databricks workspaces, you can switch between those workspaces. For more information, see Set up the add-in file.

To connect to a different Databricks workspace, do the following:

1. In the upper-right of the Databricks Add-in pane, click the three-dot menu next to the compute selector.
2. Click Change workspace.
3. Select the account your workspace is in, the workspace if prompted, and sign in.

Troubleshooting

"Authentication in progress" message on log in

If you see an "Authentication in progress" window when trying to log in to Databricks from the add-in, your workspace might not have been correctly added to the custom add-in file. Verify that you have configured your workspace correctly under <AppDomains>.

Unable to use resources

If you're unable to use Databricks resources, such as SQL warehouses, in the Databricks Add-in, try one of the following methods depending on which version of Excel you're using:

• Excel for the web: Restart the sheet or change workspaces and log back in to the same workspace. See Change Databricks workspace.
• Excel Desktop: Reload the add-in by clicking the information icon in the upper-right corner and selecting Reload.

Next steps

• Import and query data using the Databricks Excel Add-in