Skip to main content
This is 2026.9 documentation. Coverage here is incremental: a page exists only where 2026.9 differs or is newly documented. For any other topic, switch to Current (2026.8 and earlier) in the version selector.
Use these steps when your report needs to load versions published in the new data format. They use Power BI connector release 2026.10.0, which supports both existing Speckle.GetByUrl queries and new Speckle.GetTables queries. For the new tables and visual, see Power BI in 2026.9. For legacy workflows and unchanged setup guidance, see How to use Speckle for Power BI. There is no automatic conversion. Renaming the function in the Advanced Editor is not enough.
From 2026.10.0, the new visual has a separate identity and leaves legacy visuals in place on import. Releases 2026.9.0 through 2026.9.2 shared the legacy identity and could replace legacy visuals on import. Use 2026.10.0 or later to keep both visuals in a report.

​
When to switch

Your report is at risk if all three statements are true:
  • It uses Speckle.GetByUrl.
  • It points to a model URL instead of a specific version.
  • The model will get new versions from a 4.0 authoring connector or an IFC file upload.
Version 4.0 authoring connectors and IFC files uploaded in the web app create artifact-only versions. The next refresh then fails with JsonRepresentationUnavailable. Pinning to a pre-4.0 version URL is a stopgap. Rebuild the report if it must keep following new versions. Reports whose target versions still contain JSON data can keep using GetByUrl and the legacy visual. Updating the connector alone does not require a rebuild.

​
Before and after

​
How to switch

​
Pin a broken report

If the report already fails, pin it to the last version published before 4.0. A model whose first version is artifact-only, such as a new IFC upload, has no version to pin to: go to Rebuild the queries.
1

Open the GetByUrl query

Open Power Query and select the query that calls Speckle.GetByUrl. You should see the model URL in the formula.
2

Pin the URL to a version

Change the model URL to .../models/MODEL_ID@VERSION_ID for the last version that still contains JSON. You should be able to refresh against that version again.
After you pin the URL, the report no longer follows new publishes. Continue the steps below when the report must pick up new versions.

​
Rebuild the queries

Use the existing model URL. Do not rename GetByUrl to GetTables in the Advanced Editor.
1

Connect to Speckle

Select Get Data, search for Speckle, then select Connect to Speckle (Custom) and Connect. Paste the existing model URL in Speckle Model URL and sign in when prompted. You should see Objects, Properties, and Relations in Navigator.
2

Load Objects

Select Transform Data and enable load for Objects. You should see one row per object, with Object Key, Application ID, and Model Info.
3

Choose properties and related fields

Select the Properties function, pick the columns used by the report in the Properties list, then select OK and Invoke to create a new query. Do the same with Relations for fields such as levels or rooms. Enable load for the resulting tables and leave the function queries with load disabled. After Close & Apply, create one-to-one relationships from the resulting tables to Objects using Object Key.
For Navigator layouts, column naming, and M helpers, see Power BI in 2026.9.

​
Reconnect charts, measures, and slicers

Update every report element that references the old table. Check column names. Shortened property paths, numeric collision suffixes, and the Type_ prefix may change table references and calculations.

​
Add the new 3D visual

1

Import the new visual

In the Visualizations pane, select Import a visual from a file. Import Speckle Power BI 3D Visual.pbiviz from Documents/Power BI Desktop/Custom Visuals. The new visual appears in the pane alongside the legacy visual.
2

Add the new visual and fields

Add the imported visual to your report. Check that its fields include Object Keys. The older visual has Object IDs. Drag Objects[Model Info] into Model Info, Objects[Object Key] into Object Keys, tooltip fields into Object Data (Tooltip), and the previous category field into Color By. Recreate any color rules on the new Edit page. You should see your model in the new visual.
3

Check the report before removing the legacy visual

Refresh the report and test its filters, charts, and tooltips. Confirm that the new visual shows the expected objects before deleting the legacy visual from that page.
Installing a connector update copies the visual file to your Documents folder. Visuals already imported into reports do not update automatically through AppSource.

​
Remove the old queries

Delete the GetByUrl queries after no visual, measure, or relationship references them.

​
Retained functions

Existing M functions remain available. Data-shaping helpers still expect the legacy GetByUrl table shape. The project issues function is independent of both object data paths. The installer places the data connector in the current user’s Documents folder. Reports opened by that user use the installed connector. Existing GetByUrl queries still work when their target version contains JSON data.

​
FAQ

Invoke the Properties function and pick the properties the report uses. The result has one row per object, with Object Key and one column per property. See Power BI in 2026.9 for the M alternative.
The version is artifact-only. GetByUrl reads JSON data only, so pinning works only for a version published before 4.0. Models created by a 4.0 connector or a new IFC upload have no such version. Rebuild the query with Connect to Speckle (Custom).
The downstream query steps still expect the old flat table and will fail. Rebuild the query from Connect to Speckle (Custom), load Objects, and invoke Properties and Relations.
If the error’s RootObjectId starts with bundle., the version is artifact-only. Some connector releases report this as DirectDownloadFailed instead of JsonRepresentationUnavailable. The fix is the same: rebuild the query with Speckle.GetTables. Pinning to a version published before 4.0 works only if the model has one; a new IFC upload does not.
No. Pinning to .../models/MODEL_ID@VERSION_ID is a recovery option. If the report must follow new publishes after a 4.0 authoring connector is in use, rebuild it with Speckle.GetTables and add the new visual.
With 2026.10.0, importing the new file leaves legacy visuals in place. A new visual needs GetTables output before it can display a model. A legacy GetByUrl table cannot supply its required fields. Keep the legacy visual until you have loaded the new tables and checked the report.
Last modified on October 8, 2026