# Power BI
# PowerBI Data Connector
The Speckle 2.0 connector for Power BI supports Power BI Desktop only.
The Power BI connector is in
beta development and still requires manual installation. We will look into streamlining installation via Speckle Manager as well as Microsoft certification once development stabilizes.
The Power BI beta connector allows you to import your Speckle stream, branch, commit, or object data using the corresponding URL from your Speckle server stream. The following data will be retrieved depending on which type of URL you use:
- Stream URL -> the most recent commit on the main branch of this stream
- Branch URL -> the most recent commit on this branch
- Commit URL -> this commit
- Object URL -> this object
If you're having issues connecting to your stream, make sure the stream is either set to
Public or your local account has access to the private stream.
All releases of the Speckle 2.0 Power BI Connector are available on our Power BI GitHub repository (opens new window).
Speckle.mezfile from the latest release (or release of your choice).
Copy the downloaded file into the local
Custom Connectorsfolder in your installation of Power BI:
Documents\Power BI Desktop\Custom Connectors.
The Speckle Power BI Beta Connector should now appear as a data source once you load up Power BI Desktop!
Custom Connectors folder doesn't exist, you can create it at the path in Step 2! Make sure it is created in your user's
# Using Speckle Power BI
Once the connector is installed, you'll find a
Speckle (beta) option in the
Get data interface, under the
Select the Speckle connector and click
Connect - a window will open where you can input your Speckle stream, branch, commit, or object URL!
The result of that query will be a table with the following columns:
- Stream URL
- URL Type
- Object ID
Stream URL and Object ID columns were added to facilitate loading data into the new Speckle PowerBI 3D Viewer
# Expanding the
In order to access the data within each object, you must expand that record into a set of it's properties.
expand column button displays a pop-up that will enable you to choose which properties to expand.
This process can be done several times in a row until you reach the property values you're interested in.
We recommend that you uncheck the
Use original column name as prefix option only when expanding the initial
This allows for nested property names to not have a prefix (i.e. the level name of a room would be
level.name instead of
# Accessing Private Streams 🔒
If you're having issues connecting to your private stream, make sure you set an
Access Token on your Profile. This is how you do it:
Go to you Profile on Speckle server. https://speckle.xyz/profile (opens new window)
Under Developer Setting Create a
Set its name as
PowerBI Connectorand check every option under
Scopes✅ and click
This will create a token for you. Make sure you copied it. It is the first and last time you’ll be able to see this token. Treat it as a Password 🔑 and do not share it with anyone.
Go to Power BI > Options and Settings > Data source settings.
Go to Global Permissions and select your Speckle server.
After selecting server, follow Edit Permissions > Edit > Private Stream. Paste your Token into
Personal Access Tokeninput.
That’s it. It should work now.
If you have trouble seeing your server under Data sources, simply delete existing servers. Go back to Speckle connector and try to receive the same stream/branch/commit. You’ll have the option to add it from there.
# Speckle 3D Viewer Visual
The PowerBI visual is still in early stages of development. We welcome your feedback!
The 3D Viewer Visual allows for the visualisation of Speckle data in a 3D environment inside your PowerBI reports. It is compatible with PowerBI Desktop and can also be used in PowerBI.com for online visualization.
The current version enables basic visualisation, filtering and coloring features, as well as some basic camera and color controls:
- Load individual objects that were fetched with the PowerBI Data Connector
- Highlight objects in the 3D viewer that were selected on a different table in the report.
- Color objects based on a category or value
You can install the Speckle 3D Viewer Visual manually by following these steps:
- Download the latest
.pbivizpackage from our Github repo (opens new window).
- Open your report in Power BI Desktop or Power BI service.
- Select the ellipsis from the visualizations pane.
- Select Import a visual from a file from the menu.
- If you get a message cautioning you about importing custom files, select Import if you trust the source of the file.
- Navigate to the folder that has the custom visual file (
.pbiviz) and open it.
- When the visual has successfully imported, select OK.
- The visual now appears as a new icon in the visualizations pane of the current report. Select it to create the visual on the report canvas.
If you want the visual to remain on the visualization pane so you can use it in future reports, right-click on it and select Pin to visualization pane.
The 3D Viewer Visual was designed to work alongside our PowerBI Data Connector (version 0.10 or above). The data connector will output a table containing the following columns:
data: A column of records containing the data belonging to each speckle object.
Stream URL: The stream url this object was fetched from
Object ID: The id of each speckle object in the table (this was extracted from the
Other columns may be present, and can be user generated, but are not relevant for this section.
# Loading objects
In order to load the objects from the table into the viewer, just add the fields
Stream URL and
Object ID onto their respective inputs in the visual.
Once both the fields are added, the Viewer would start to load the objects into the scene. The Object Data input is optional, and is only used to enable highlight/coloring functions.
# Highlighting objects across visuals
In order to enable highlighting across report visuals, connect a field on the Object Data. This could be any field in your data source (the object id, volume, level name, beam type...)
Once a field has been added, any objects highlighted in another visual (such as a Table, Matrix, Slicer...) will be filtered out in the viewer, showing any other objects ghosted out (gray transparent material)
# Coloring objects by category
Coloring objects works in the same way that highlighting. Once a field has been added to Object Data the viewer will color the data by the field that was provided, when available.
The way an object is colored depends on the type of field you connected:
- Text based fields: The colors will be automatically generated by unique value.
- Number based fields: The colors will be generated using the 3-color gradient in the Viewer Settings, assuming the first color represents the minimum value and the last color represents the maximum value.
# Visual Settings
# Camera controls
The camera controls settings allow for:
- Orthogonal or perspective mode
- Setting the view that would be shown when first loaded (top, front, back, left, right)
The filtering/coloring feature available when connecting a data field into the
Object Data section can be customised by selecting a 3-color gradient on the visual settings.
This will affect the color pallette that is used when coloring objects by a number based field. When connecting a text based field into the
Object Data input, the color will be computed automatically and the color pallette in the settings will be ignored.
We're really interested in your feedback regarding the integration between Power BI and Speckle! You can always reach us with suggestions, comments, and error reports on our Community Forum (opens new window)