Skip to main content
Speckle’s connection to Power BI consists of two parts.
  • The Power BI connector lets you easily load your model from Speckle into Power BI in a tabular format.
  • The 3D Viewer Visual allows you to view and color your models in 3d.

​
Setup

1

Install the connector

Install your Power BI connector
2

Open the Power BI connector

  1. Select Get Data. 2. In the search box, enter Speckle. 3. Select Connect to Speckle and click Connect.
You need to enable third-party data sources. 1. Go to File > Options and settings > Options > Security. 2. Under Data Extensions, select Allow any extension to load without validation or warning.
If your organization restricts Power BI security setting changes, your IT department can add the Speckle connector’s thumbprint to the Windows registry instead.Thumbprint: CDC489B709A709E3283568A9B75D75180B1355BEFor detailed instructions, see Microsoft’s Docs.

​
Loading a Model

1

Load from Speckle

  1. Copy Model URL from the web app.
  2. Paste it in the text field and select OK.
2

Import 3D Visual

  1. In the Visualizations pane, select the three dots (…), then select Import a visual from a file.
  2. Browse to Documents/Power BI Desktop/Custom Visuals.
  3. Select Speckle 3D Visual.pbiviz and Open.
3

Visualize a model

  1. In the Visualizations pane, select Speckle 3D Visual
  2. Configure the visual:
    • Drag Version Object ID column into the Version Object ID input -> required for viewing
    • Drag Object IDs column into the Object IDs input -> required for interactivity
    • Drag any column into Tooltip input -> for tooltip
    • Drag any column into Color by input -> for coloring model
  3. Wait for your model to load in the viewer
You’ll find Speckle’s 3D visual in the Documents/Power BI Desktop/Custom Visuals folder.
  1. From the Visualizations pane, select the More options (…) menu.
  2. Go to Documents/Power BI Desktop/Custom Visuals.
  3. Select the new version of Speckle’s 3D visual.
  4. Select Open.
  5. When prompted with the update warning, select Update.
  6. In your report, select instances of Speckle’s 3D visual.
  7. From the Visualizations pane, select Table visual to replace the 3D visual temporarily.
  8. Select Speckle’s 3D visual from the Visualizations pane again to apply the new version.
Use the ghost icon in the 3D visual. By default, unselected elements appear ghosted. Clear the ghost icon to completely hide unselected elements.
If you have a Business plan, you can hide Speckle branding by selecting the arrow in the top bar. Free plan users can’t hide the Speckle logo.
  1. Select Get Data from the Home ribbon.
  2. Find Speckle under data sources.
  3. Paste your model URL in the text box.
  4. If not already signed in, an authentication dialog will appear.
  5. Click Sign in and sign in to your Speckle account from the browser window that opened.
  6. Power BI will store your credentials. So you won’t have to log in again next time you load a model.
This is a browser-related issue. To fix it:
  1. Go to File > Options and settings > Options > Security
  2. Under Authentication Browser, clear Use my default web browser
If you are trying to load from a different server, you don’t need to do anything. Just load the model from the new server. If you want to switch to a different account in the same server, you’ll need to clear Power BI’s cached authentication data by following these steps:
  1. Close Power BI Desktop completely.
  2. Where do I find my Power BI installation folder?
    • Desktop version (.exe): Navigate to %LocalAppData%\Microsoft\Power BI Desktop (typically C:\Users[your-username]\AppData\Local\Microsoft\Power BI Desktop)
    • Microsoft Store version: Navigate to C:\Users[your-username]\Microsoft\Power BI Desktop Store App
  3. Delete following items:
    • CEF folder
    • WebView2 folder
    • Cache folder
    • User.zip file
  4. Restart Power BI Desktop.
This process will clear all cached data for Power BI Desktop, not just Speckle authentication. You may need to re-authenticate with other data sources as well.
This error occurs for one of two reasons:
  • Desktop service isn’t running – See How do I check if Desktop service is running? to verify and restart the service.
  • Token cache expired – Follow these steps to clear your cache:
    1. Go to File > Options and settings > Data source settings
    2. Select https://app.speckle.systems/ or your server URL
    3. Select Clear Permissions
    4. Go to %APPDATA%/Speckle/Projects
    5. Delete PowerBITokenCache.db files
    6. Restart Power BI and try again
  1. Open Task Manager.
  2. Look for Speckle.Desktop.Services.
  3. If the process appears in the list, it’s running.
  4. If the process doesn’t appear:
    • Select Run new task.
    • Enter this path: %APPDATA%\Speckle\Desktop Services\Speckle.Desktop.Services.exe
    • Select OK.
The Speckle.Desktop.Services process should now be running.
The Power BI connector needs Speckle Desktop Service to run on your machine. Make sure Desktop Service is active and running.
Following reasons might cause this issue:
  1. Refresh preview Make sure you clicked Refresh in the Power BI ribbon to load the latest version.
  2. Check if you loaded a specific version If your model URL contains an ”@” symbol, this means you loaded a specific version. Power BI connector will only load that specific version and not any new versions.
The next-generation Power BI connector doesn’t use Model URL input. You can safely ignore it.
This error usually means you don’t have the required permissions to load the model.Steps to fix it:
  1. Verify that you have been granted access to the model.
    • If not, contact the project owner and request the necessary permissions.
  2. If you are already added but still see the error, try re-authenticating:
    • In Power BI, go to Data source settings.
    • Select Global permissions, then double-click on app.speckle.systems.
    • Click Edit, choose Speckle Account, and sign in again.
After signing in, reload the URL to check if the error is resolved.If you’re already signed in but can’t sign in with your other account, see How can I switch to a different account in Power BI?
Yes. Both the Power BI connector and 3D visual support private projects.
Viewing and loading a model require different permissions. To load a model in a connector, contact the project owner to change your project role.
Here’s how you can load and visualize multiple models with Power BI connector:
  1. First, federate your models in the web app.
  2. Copy the federated model URL
  3. Load federated model in Power BI.
Visualizing multiple models in Power BI is similar to visualizing a single model.

​
Sharing Reports

You can share your Power BI reports with Speckle models in two ways:
  • Share the Power BI file directly: You can share the .pbix file with colleagues who will be able to open and view the report, including the 3D model visualization. However, they may encounter limitations when attempting to edit queries or refresh data, as these operations require access permissions and the Speckle Desktop service.
  • Publish to Power BI Service: You can publish your report to Power BI web, making it accessible to others through the online platform where they can view the published report and interact with the 3D visual. If a data gateway has been configured, the Speckle connector and 3D visual support scheduled refresh, ensuring your reports reflect up-to-date data.

​
Data Gateway Setup

For production reports that need scheduled refresh, you’ll need to set up a data gateway. This allows your Power BI reports to automatically update with the latest Speckle data without manual intervention. Set up Data Gateway →
Data gateways are only needed for scheduled refresh in Power BI Service. For basic connector usage and 3D visualization, you don’t need a gateway.

​
Helper Functions

We’ve added a series of helper functions to the Speckle namespace to make working with Speckle data in Power BI more efficient and user-friendly.

​
Speckle.Objects.Properties

Quickly access properties of an object without navigating through the nested structure. 
Speckle.Objects.Properties(inputRecord as record, optional filterKeys as list)
Returns a record containing properties and their values from the given inputRecord. Optionally, you can provide filterKeys to extract only specific properties. Usage:
  • Extracting all properties -> Speckle.Objects.Properties([data])
  • Extracting specific properties: -> Speckle.Objects.Properties([data], {"Name", "Number", "Area"})

​
Speckle.Objects.CompositeStructure

Extract the composite structure of objects such as Walls, Floors, Roofs or any elements with layered structure.
Currently only supported for Revit and Archicad models.
Speckle.Objects.CompositeStructure(inputRecord as record, optional outputAsList as nullable logical)
By default, returns a record containing the composite structure.
Optionally, set outputAsList to true to return it as a list —> useful for expanding each layer into its own row. Usage:
  • Extracting composite structure -> Speckle.Objects.CompositeStructure([data])
  • Extracting composite structure as a list -> Speckle.Objects.CompositeStructure([data], true)

​
Speckle.Objects.MaterialQuantities

Access material quantities of an object. 
Speckle.Objects.MaterialQuantities(inputRecord as record, optional outputAsList as logical)
Returns a record containing its material quantities.
Optionally, set outputAsList to true to return quantities as a list, which is helpful for row expansion. Usage:
  • Extracting material quantities -> Speckle.Objects.MaterialQuantities([data])
  • Extracting material quantities as a list -> Speckle.Objects.MaterialQuantities([data], true)

​
Speckle.Models.MaterialQuantities

Takes a table and extracts material quantities for all objects, expanding them into separate columns. 
Speckle.Models.MaterialQuantities(inputTable as table, optional addPrefix as logical)
Returns a table with material quantities columns added.
Optionally, set addPrefix to true to create prefixed columns like “MQ.materialName”, “MQ.area” Examples:
  • Basic usage: Speckle.Models.MaterialQuantities(Source) - Creates columns like “materialName”, “area”
  • With prefixing: Speckle.Models.MaterialQuantities(Source, true) - Creates “MQ.materialName”, “MQ.area”

​
Speckle.Models.Federate

Manually federate loaded models in Power BI for use in 3D visual. 
Speckle.Models.Federate(tables as list, optional excludeData as logical)
Accepts a list of tables (each representing a model loaded from Speckle) and returns a federated table for use in 3D visual.
Optionally, use excludeData = true to federate only the metadata necessary for 3D visual without pulling in all the data. Usage:
  • Federating multiple models -> Speckle.Models.Federate({Model1, Model2, Model3})
  • Federating with metadata only -> Speckle.Models.Federate({Model1, Model2, Model3}, true)

​
Speckle.Utils.ExpandRecord

This function expands a record column into separate columns for each field. It’s especially useful in combination with the Properties helper. 
Speckle.Utils.ExpandRecord(table as table, columnName as text, optional FieldNames as list, optional UseCombinedNames as logical)
Optionally, use FieldNames to limit the expanded fields.
Optionally, use UseCombinedNames = true to prefix column names with the record column name (e.g., Properties.Length). Usage:
  • Expand properties record column
    Speckle.Utils.ExpandRecord(Source, "properties") -> All properties will be expanded into separate columns
  • Expanding subset of fields
    Speckle.Utils.ExpandRecord(Source, "properties", {"Length", "Width"}) -> Only Length and Width fields will have separate columns
  • Expanding record columns with combined names
    Speckle.Utils.ExpandRecord(Source, "properties", {"Length", "Width"}, true) -> Length and Width fields will have separate columns with the record column name as a prefix (e.g., Properties.Length, Properties.Width)
⌘I