> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs contain multiple Speckle product experiences. For Speckle 2026.9, prefer /next/ pages for the topics and changes they cover. The navigation label Current does not override this version-specific precedence.
> Coverage under /next/ is incremental. Use Current documentation for unchanged topics and when a /next/ page says coverage is unavailable or explicitly refers you to Current. Do not infer a feature was removed from a missing page.
> Read the page-specific documentation status, applicability, affected guidance and replacement links in agent-only content. Impacted, changed and superseded apply only to the stated scope; they do not mean the entire feature is deprecated. Historical connector guides apply only to the legacy connector described.
> Match guidance to the customer's deployment version, model data format and connector. Respect plan, permission and compatibility restrictions. If an unknown version or data format changes the answer, ask a focused clarification; do not infer deployment version from the date alone.

# Upgrade Power BI to 2026.9

> Pin a broken report, rebuild queries with Get Tables, and add the new 3D visual.

Documentation set: Speckle 2026.9. Status: current. Authority: canonical for this version and the coverage on this page.

Applies to version 2026.9, from 2026-09; this is not a rollout date for every deployment.

Authoritative Speckle 2026.9 documentation for the topic covered here. For Speckle 2026.9, prefer this page over conflicting earlier guidance. Follow the linked pages in the other documentation version for unchanged topics and where this page says coverage is not yet available. Respect data-format, deployment, plan, permission, and compatibility limitations stated in the page.

<Note>
  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.
</Note>

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](/next/connectors/power-bi/introduction). For legacy workflows and unchanged setup guidance, see [How to use Speckle for Power BI](/connectors/power-bi/power-bi).

There is no automatic conversion. Renaming the function in the Advanced Editor is not enough.

<Warning>
  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.
</Warning>

## 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

| Before | After |
| - | - |
| Existing query calls `Speckle.GetByUrl` | **Connect to Speckle (Custom)** creates a `Speckle.GetTables` query |
| `Speckle.GetByUrl` returns one flat table | The invoked **Properties** table has one row per object |
| Join and color on `Application ID` | Join and bind on `Object Key` |
| Legacy 3D visual | Separate new visual with **Model Info** and **Object Keys** from Objects |
| JSON-only versions | Artifact bundles published with a 4.0 connector |

| Version contains | `Speckle.GetByUrl` | `Speckle.GetTables` |
| - | - | - |
| JSON and artifacts | Returns the legacy flat table | Returns the new tables |
| JSON only, published before 4.0 | Returns the legacy flat table | Fails and directs the user to `GetByUrl` or republishing |
| Artifacts only, published with 4.0 | Fails and directs the user to `GetTables` | Returns the new tables |

## 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](#rebuild-the-queries).

<Steps>
  <Step title="Open the GetByUrl query">
    Open Power Query and select the query that calls `Speckle.GetByUrl`. You should see the model
    URL in the formula.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  After you pin the URL, the report no longer follows new publishes. Continue the steps below when
  the report must pick up new versions.
</Note>

### Rebuild the queries

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

For Navigator layouts, column naming, and M helpers, see [Power BI in
2026.9](/next/connectors/power-bi/introduction).

### 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  Installing a connector update copies the visual file to your Documents folder. Visuals already
  imported into reports do not update automatically through AppSource.
</Note>

### 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.

| Function | Behavior |
| - | - |
| `Speckle.GetByUrl(url, ExpandProperties)` | Keeps its 3.x contract and reads JSON versions only. It is no longer the published Get Data entry |
| `Speckle.GetStructuredData(url)` | Returns the legacy flat objects table from JSON |
| `Speckle.SendToServer(url)` | Downloads the version's raw JSON object tree |
| `Speckle.Objects.Collections` | Shapes legacy `GetByUrl` output |
| `Speckle.Objects.CompositeStructure` | Shapes legacy `GetByUrl` output |
| `Speckle.Objects.MaterialQuantities` | Shapes legacy `GetByUrl` output |
| `Speckle.Objects.Properties` | Shapes legacy `GetByUrl` output |
| `Speckle.Models.Federate` | Operates on legacy `GetByUrl` shapes |
| `Speckle.Models.MaterialQuantities` | Operates on legacy `GetByUrl` shapes |
| `Speckle.Revit.Parameters.ToNameValueRecord` | Operates on legacy `GetByUrl` shapes |
| `Speckle.Utils.ExpandRecord` | Operates on legacy `GetByUrl` shapes |
| `Speckle.Project.Issues(url, getReplies)` | Remains independent of both object data paths and works with old and new reports |
| `Speckle.GetVersion()` | Returns the connector version string, unchanged |

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

<AccordionGroup>
  <Accordion title="How do I get back the single flat table that GetByUrl returned?">
    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](/next/connectors/power-bi/introduction#faq) for the M alternative.
  </Accordion>

  <Accordion title="Why does GetByUrl still fail when I use a version URL?">
    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)**.
  </Accordion>

  <Accordion title="What happens if I only rename GetByUrl to GetTables in the Advanced Editor?">
    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.
  </Accordion>

  <Accordion title="Why does GetByUrl fail with DirectDownloadFailed and status 404?">
    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.
  </Accordion>

  <Accordion title="Can I keep following new versions without migrating?">
    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.
  </Accordion>

  <Accordion title="What happens if I import the new visual before I migrate the queries?">
    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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.