> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/consume/activate/bi-tools/desktop.md).

# Power BI Desktop

Connect Power BI Desktop to turn your dimensions and measures into charts, dashboards, and drill-downs - no SQL required.

Power BI connects to your semantic layer over the MySQL wire protocol.

Every dimension, measure, and join already defined in your semantic models shows up in the Data pane, ready for visuals: no Power Query, no redefining measures and dimensions.

## Prerequisites

Set these up once on the Windows machine running Power BI Desktop. You only need to do this the first time.

<table><thead><tr><th width="200.52105712890625">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td>Operating System</td><td>Windows Only. Power BI Desktop isn't available for MacOS/Linux operating systems.</td></tr><tr><td>Power BI Desktop</td><td><a href="https://powerbi.microsoft.com/desktop">Download Power BI Desktop</a>.</td></tr><tr><td>MySQL Connector ODBC</td><td>Install <strong>8.0.23</strong> exactly. <a href="https://downloads.mysql.com/archives/get/p/10/file/mysql-connector-odbc-8.0.23-winx64.msi">Download the ODBC Connector</a>.</td></tr><tr><td>DataOS Username</td><td>Your DataOS user ID, found under <strong>Profile → Id</strong>.</td></tr><tr><td><a href="https://v2.dataos.info/references/key-concepts/api-tokens">DataOS API Token</a></td><td>Generate from <strong>Profile → Tokens</strong>, or copy a token from <a href="https://v2.dataos.info/consume/get-started/before-you-begin.md">Before you begin</a>.</td></tr></tbody></table>

### Install the MySQL ODBC connector

Download and install version **8.0.23**:

```
https://downloads.mysql.com/archives/get/p/10/file/mysql-connector-odbc-8.0.23-winx64.msi
```

### Allow third-party connectors in Power BI

1. Open Power BI Desktop
2. Go to **Options and settings → Options → Security**.
3. Under **Data Extensions**, select **Allow any extension to load without validation or warning**.

Click OK and restart Power BI Desktop.

### Install the DataOS Power BI connector

Download the `DataOS.mez` file and place it in your `Documents\Power BI Desktop\Custom Connectors` folder.

{% file src="/files/0yL0bOQOfgBf8hxZTToh" %}

> The exact path varies by system. The default location is:
>
> ```
> Documents\Power BI Desktop\Custom Connectors\
> ```
>
> If the Custom Connectors folder doesn't exist, create it.

### Set the cleartext authentication variable

1. Search for **Edit the system environment variables** in Windows and open it.
2. Go to the **Advanced** tab and click **Environment Variables** at the bottom.
3. Under **System variables**, click **New**.
4. Enter the following:
   * **Variable name:** `LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN`
   * **Variable value:** `1`

This enables MySQL's cleartext authentication plugin, which allows Power BI to authenticate with servers that require `mysql_clear_password`. Restart Power BI Desktop after adding the variable.

## Connect to your semantic layer

1. **Open the Power BI guide from the Data Product.** Open the Data Product in DataOS. Go to **Activate → BI Tools** and open the **Power BI** guide.
2. **Download the `.pbip` file.** Click **Download**. The `.pbip` package comes pre-configured with the endpoint and semantic model references for that Data Product.
3. **Extract the archive.** The download is a ZIP. Extract it before opening anything inside. You should see:

   <table><thead><tr><th width="282.9190673828125">File or folder</th><th>What it contains</th></tr></thead><tbody><tr><td><code>tenant_name_&#x3C;product_name>.pbip</code></td><td>The entry point. Double-click this to open the project in Power BI Desktop.</td></tr><tr><td><code>public_&#x3C;product_name>.Report/</code></td><td>Report metadata, including <code>definition.pbir</code>.</td></tr><tr><td><code>public_&#x3C;product_name>.SemanticModel/</code></td><td>Semantic model files, including <code>definition.pbism</code> and <code>model.bim</code>.</td></tr></tbody></table>

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Keep all three items together.</strong> Moving or deleting any of them breaks the project.</p></div>

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Extract before opening.</strong> Opening the <code>.pbip</code> from inside the ZIP can throw missing-file errors.</p></div>
4. **Open the `.pbip` file.** Double-click it. Power BI Desktop opens it automatically. If you get a connectivity or security dialog, click OK.
5. **Enter credentials.** When prompted:
   * **Username:** your DataOS User ID.
   * **Password:** your DataOS API token.
6. **Semantic models are loaded.** After authentication, the semantic models load into the **Fields** pane. Dimensions and measures are ready to use in visuals, dashboards, and reports.

{% hint style="success" %}
**Want to publish?** Set up an [on-premises gateway](https://v2.dataos.info/consume/activate/bi-tools/service.md#1-set-up-the-gateway).
{% endhint %}

## Troubleshooting

| Symptom                                                                  | Quick fix                                                                                                                                                      |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Cannot load model: ... The import DataOS.Contents matches no exports"* | `DataOS.mez` is missing or placed in the wrong directory. Ensure it is placed in `Documents\Power BI Desktop\Custom Connectors\` and restart Power BI Desktop. |
| *"There weren't enough elements in the enumeration..."*                  | Wrong ODBC version. Uninstall all MySQL ODBC connectors and reinstall 8.0.23.                                                                                  |
| DataOS connector doesn't appear in Power BI                              | Check: `.mez` file is in the Custom Connectors folder **and** the security setting allows extensions. Restart Power BI.                                        |
| *"cleartext password not allowed"*                                       | `LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1` is not set in the system environment. Add it, then restart Power BI Desktop.                                              |
| Connection times out                                                     | Check VPN / firewall. Re-download the `.pbip` if you switched tenants.                                                                                         |

For data types, best practices, limitations, governance, and a curl-based download, see the [Power BI Desktop](https://v2.dataos.info/references/interfaces/bi-tools/power-bi-desktop) reference in References.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/consume/activate/bi-tools/desktop.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
