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

# Power BI in 2026.9

> Load Speckle models with Get Tables, relate on Object Key, and bind the 2026.9 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>

In **Get Data**, select **Connect to Speckle (Custom)**. Power Query calls the function **Speckle - Get Tables**. These instructions use Power BI connector release **2026.10.0**. The default Simplified layout loads a small Objects table plus Properties and Relations functions, instead of one wide table. The new 3D visual streams geometry from Speckle over a WebSocket and requires WebGPU.

This page covers only what changed. For legacy workflows and unchanged setup guidance, see [How to use Speckle for Power BI](/connectors/power-bi/power-bi). Existing `Speckle.GetByUrl` reports can keep working when their target versions contain JSON data. To follow versions published only in the new data format, see [Upgrade Power BI to 2026.9](/next/connectors/power-bi/migration).

## What changed

`Speckle.GetTables` accepts model, version, federated, and project URLs.

The default **Simplified** layout provides three Navigator entries:

* **Objects** has one row per object. Its standard columns are `Object Key`, `Application ID`, and
  `Model Info`. Federated loads also include `Source Model`.
* **Properties** is a function. Pick the properties the report needs from a list, then load a table
  that contains `Object Key` and those property columns. This table replaces the single flat table
  that `Speckle.GetByUrl` returned.
* **Relations** is a function. Choose outgoing graph relations such as `ON_LEVEL` or `IN_ROOM`, then
  load a table that contains `Object Key` and those relation columns.

Create one-to-one relationships from the invoked Properties and Relations tables to Objects using
`Object Key`.

## Functions

| Function | Where it appears | Behavior |
| - | - | - |
| `Speckle.GetTables(url, options)` | **Connect to Speckle (Custom)** in Get Data | Returns the navigation table for the new data model |
| `Properties(paths?, useFullPaths?)` | A Navigator entry bound to each loaded model | Returns `Object Key` plus the selected property columns |
| `Relations(relationNames?)` | A Navigator entry bound to each loaded model | Returns `Object Key` plus selected outgoing relation columns |
| `Speckle.AddProperties(source, propertyPaths, objects?, useFullPaths?)` | M code only | Adds selected properties to Objects. An optional Objects table can filter rows and keep extra columns |
| `Speckle.AddAllProperties(source, objects?, useFullPaths?)` | M code only | Adds every property path to Objects. Intended for property-light models |
| `Speckle.AddRelations(objects, relations, relationTypes, nodes, relationNames)` | M code only | Adds selected outgoing, one-hop relations to an Objects table |

`Properties` and `Relations` are bound to the loaded model. They are not global M functions.

`useFullPaths` is a logical value. `false` uses the shortest unique suffix and `true` uses the full
dotted path. The connector adds numeric suffixes when names still collide at full depth.

`Speckle.AddProperties` and `Speckle.AddAllProperties` take the navigation table returned by
`Speckle.GetTables` as `source`. Their optional Objects override can filter the result and preserve
extra columns.

`Speckle.Objects.*` and `Speckle.Models.*` helpers still exist. They operate on the legacy
`Speckle.GetByUrl` table only. They do not accept the tables returned by `Speckle.GetTables`. For
the retained-function list, see [Upgrade Power BI to
2026.9](/next/connectors/power-bi/migration#retained-functions).

## Load

<Steps>
  <Step title="Connect to Speckle">
    Select **Get Data**. Search for Speckle, then select **Connect to Speckle (Custom)** and
    **Connect**. You should see the **Speckle Model URL** input.
  </Step>

  <Step title="Paste a Speckle URL">
    Paste the URL from the web app and select **OK**. Sign in when prompted. You should see Objects,
    Properties, and Relations in Navigator.
  </Step>

  <Step title="Load Objects and related tables">
    Select **Transform Data** to open Power Query. Enable load for Objects. Select the Properties
    function, pick the properties the report needs 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 these tables to Objects using
    `Object Key`.
  </Step>
</Steps>

<Frame caption="Pick properties from the list, then select OK and Invoke.">
  <img src="https://mintcdn.com/speckle/izw7VGIxt3-j-WH0/images/connectors/powerbi/properties-picker.png?fit=max&auto=format&n=izw7VGIxt3-j-WH0&q=85&s=dbade4f19e7d28dc4c5f78ed14b6e74f" alt="Power Query with the Properties function selected and its Properties list open, showing property paths with checkboxes" width="2000" height="1004" data-path="images/connectors/powerbi/properties-picker.png" />
</Frame>

<Tip>
  The **All tables** layout also exposes Property Values, Property Paths, Object Types, Type
  Properties, the raw Relations table, Relation Types, and Nodes. Use these tables for custom
  relationships. Nodes includes `Elevation`, which can sort level names.
</Tip>

<Note>
  The Properties function uses the shortest unique suffix for column names by default. Set **Use
  full paths** to `true` to use full dotted paths. If two names still collide at full depth, the
  connector adds numeric suffixes such as `.1` and `.2`. Instance values use unprefixed column
  names. Type values use the `Type_` prefix.
</Note>

<Warning>
  For Get Tables loads, use the Properties and Relations Navigator functions, and relate on `Object
      Key`. Do not pass Get Tables output into `Speckle.Objects.*` or `Speckle.Models.*` helpers.
</Warning>

## View

The new visual has four data fields: **Model Info** (required), **Object Keys** (required), **Object Data (Tooltip)**, and **Color By**. Use `Objects[Object Key]` as the standard object binding. `Application ID` remains supported, but large models require an extra lookup dictionary that can add tens of megabytes to the load.

Geometry no longer passes through the Power BI dataset. The visual streams it from Speckle over a
WebSocket, becomes interactive after the first geometry arrives, and continues loading in the
background.

<Steps>
  <Step title="Import the new visual">
    In the Visualizations pane, select **Import a visual from a file**. Browse to `Documents/Power
            BI Desktop/Custom Visuals`, select `Speckle Power BI 3D Visual.pbiviz`, and **Open**. You should
    see the imported visual in the pane.
  </Step>

  <Step title="Add the model 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** and `Objects[Object
            Key]` into **Object Keys**. Drag tooltip fields into **Object Data (Tooltip)** and the category
    field into **Color By**. You should see the first geometry arrive, then the rest stream in the
    background.
  </Step>
</Steps>

<Warning>
  From 2026.10.0, the new visual has a separate identity and leaves legacy visuals in place on
  import. Add the new visual and connect its fields separately. 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>

<Warning>
  The 3D visual requires WebGPU. There is no fallback. If WebGPU is missing, the visual shows an
  error.
</Warning>

<Warning>
  Firefox on macOS currently allows eight GPU storage buffer bindings, and the 3D visual needs nine,
  so it will not render in Power BI Service reports opened there. Use a Chromium-based browser or
  Power BI Desktop instead.
</Warning>

The visual's Edit page supports per-category color overrides and a diagnostics mode. Color overrides
remain fixed when the report theme changes. Diagnostics show streaming statistics and recent events.

The toolbar sits at the bottom center and contains Zoom Extents and Camera. Camera includes
orthographic projection, Move camera on filter, and Top, Front, Left, Back, and Right views.
Resizing the visual rebuilds its render targets.

The visual reads Power BI data in 30,000-row windows. When a real filter is active, it can process
up to one million rows for exact isolation. Above 30,000 filtered rows, the visual keeps the
viewport responsive but disables tooltips and click selection for that selection. Chart-click
highlights on very large models are sampled. Use a slicer when exact isolation matters.

The server must serve 4.0 artifact bundles and advertise a geometry stream. The Power BI client
must run in a WebGPU-capable environment. The visual uses the existing OAuth flow and receives a
limited-scope token for each load. The account's main token does not enter the report.

## FAQ

<AccordionGroup>
  <Accordion title="How do I get one table of objects and their properties, like GetByUrl returned?">
    Invoke the **Properties** function: pick the properties you report on, select **OK**, then
    **Invoke**. The result has one row per object, with `Object Key` and one column per property.
    For the 3D visual, also load Objects and relate it on `Object Key`, because `Model Info` lives
    there. To get it all in one table in M, use `Speckle.AddProperties(Source, {"path.one",
            "path.two"})`, where `Source` is the `Speckle.GetTables` result.
  </Accordion>

  <Accordion title="Why do I see seven or more tables in Navigator?">
    The **All tables** layout is on. It adds supporting tables for building custom relationships.
    Most reports need only the default **Simplified** layout: set **Table layout** to Simplified
    under Advanced options, or remove `[TableLayout = "All tables"]` from the `Speckle.GetTables`
    call.
  </Accordion>

  <Accordion title="Should I select all properties?">
    No. Models with many property sets can have hundreds of paths, and every selected path adds a
    column and refresh time. Start with the properties the report uses. To add more later, edit the
    invoked query's step or invoke Properties again.
  </Accordion>

  <Accordion title="How do I find a property in the Properties list?">
    Type part of its name in the list's search box, for example a property set name. The list shows
    full dotted paths such as `properties.Quantities.Qto_SpaceBaseQuantities.NetFloorArea`. The
    resulting column uses the shortest unique end of the path, such as `NetFloorArea`, unless you
    set **Use full paths** to `true`.
  </Accordion>

  <Accordion title="Why don't I see Speckle - Get Tables in Get Data?">
    Select **Connect to Speckle (Custom)**. Power Query calls this function **Speckle - Get
    Tables**, but Get Data uses a different label. The **Speckle Model URL** input still accepts
    your model URL.
  </Accordion>

  <Accordion title="Why should I use Object Key instead of Application ID?">
    `Object Key` is the standard join and visual binding. `Application ID` still works, but large
    models need an extra lookup dictionary that can add tens of megabytes to the load.
  </Accordion>

  <Accordion title="What happens if Get Tables fails on an older version?">
    `GetTables` reads artifact bundles. JSON-only versions published before a 4.0 connector need
    `Speckle.GetByUrl`, or the model must be republished with a 4.0 connector.
  </Accordion>

  <Accordion title="Does updating the connector update visuals already in my report?">
    No. The installer copies the visual file to your Documents folder. Import that file into your
    report yourself; there is no automatic update through AppSource. To move from the legacy visual
    to the new one, follow the [migration
    steps](/next/connectors/power-bi/migration#add-the-new-3d-visual).
  </Accordion>

  <Accordion title="What is missing from the 2026.9 3D visual?">
    Section box, view modes, edges, ghost mode, and named scene views are unavailable. Filtered-out
    objects are hidden. Top, Front, Left, Back, and Right remain available. Exact minimum versions
    for Speckle Server, Power BI Desktop, and WebView2 are not confirmed.
  </Accordion>

  <Accordion title="Which browsers and environments does the 3D visual support?">
    Power BI Desktop's embedded WebView2 and Chromium-based browsers viewing Power BI Service both
    support the visual. Firefox on macOS does not: it supports WebGPU, but currently allows only
    eight GPU storage buffer bindings, and the visual needs nine. Other browsers on macOS allow ten
    or more. Windows and Android browsers generally allow sixteen or more. This is a known, accepted
    limitation. Firefox may raise the limit later.
  </Accordion>

  <Accordion title="Is ghost mode available in the 2026.9 3D visual?">
    Not yet. Filtered-out objects are hidden outright instead of shown dimmed. There is no ghost
    icon or equivalent toggle in this release.
  </Accordion>

  <Accordion title="Why does geometry disappear or flicker when I zoom in?">
    This is a known rendering-stability issue in the viewer, not specific to Power BI — the same
    viewer now runs in the web app, the Power BI visual, and published reports. It shows up most
    often with objects far from the model origin or in models with very large bounds. The fix ships
    in the web viewer first, then in the following Power BI visual release, which is not on the same
    cadence.
  </Accordion>
</AccordionGroup>


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