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

# Upgrade Power BI to 2026.9

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

<Note>
  This is 2026.9 preview documentation. Coverage here is incremental: a page exists only where
  2026.9 differs or is newly documented.
</Note>

This page is the mechanical path from `Speckle.GetByUrl` to **Speckle - Get Tables**. For how Get
Tables and the 2026.9 3D visual work, see [Power BI in
2026.9](/next/connectors/power-bi/introduction). For the connector that is available today, 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>
  Importing the new `.pbiviz` replaces the old visual in place. The two visuals share the same GUID.
  Import the new visual only as part of a planned report migration.
</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 be published with a 4.0 authoring connector.

Version 4.0 authoring connectors publish 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.

## Before and after

| Before                                    | After                                                     |
| ----------------------------------------- | --------------------------------------------------------- |
| Get Data entry is **Connect to Speckle**  | Get Data entry is **Speckle - Get Tables**                |
| `Speckle.GetByUrl` returns one flat table | `Speckle.GetTables` returns related tables                |
| Join and color on `Application ID`        | Join and bind on `Object Key`                             |
| Old 3D visual field wells                 | **Model Info** and **Object Keys** from the Objects table |
| 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.

<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="Open Speckle - Get Tables">
    Select **Get Data**, then **Speckle - Get Tables**. Enter the existing model URL. You should see
    the Navigator for that URL.
  </Step>

  <Step title="Load Objects">
    Load the Objects table. You should see one row per object, with `Object Key`, `Application ID`,
    and `Model Info`.
  </Step>

  <Step title="Invoke Properties and Relations">
    Invoke Properties and select only the property columns used by the report. If the report uses
    graph-backed fields such as levels or rooms, invoke Relations and select those fields. Relate
    each invoked result to Objects one-to-one 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.

### Replace the 3D visual

<Steps>
  <Step title="Import the new visual">
    Import the new `.pbiviz` from `Documents/Power BI Desktop/Custom Visuals`. Because it uses the
    same GUID as the old visual, Power BI replaces the old visual in place.
  </Step>

  <Step title="Reconnect the field wells">
    Bind `Objects[Model Info]` to Model Info, `Objects[Object Key]` to Object Keys, existing tooltip
    fields to Object Data, and the previous category field to Color By. Recreate any color rules
    from the old visual on the new Edit page.
  </Step>
</Steps>

<Warning>
  The 3D visual has no AppSource auto-update channel. Do not import the new `.pbiviz` into a report
  you are not ready to migrate.
</Warning>

### Remove the old queries

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

## Retained functions

Existing M functions remain available. They keep their 3.x contract and only accept the legacy
`GetByUrl` table shape.

| Function                                     | Behavior in 4.0                                                                                   |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `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.Projects.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 connector installs machine-wide. After it is updated, every report on that machine runs through
the new binary. Existing `GetByUrl` queries still evaluate when their target version contains JSON.

## FAQ

<AccordionGroup>
  <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
    **Speckle - Get Tables**, load Objects, and invoke Properties and Relations.
  </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
    replace the visual.
  </Accordion>

  <Accordion title="What happens if I import the new visual before I migrate the queries?">
    The new `.pbiviz` replaces the old visual in place because they share the same GUID. Existing
    bindings break. Import it only during a planned migration, then reconnect Model Info, Object
    Keys, Object Data, and Color By.
  </Accordion>
</AccordionGroup>