> 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/power-bi/desktop.md).

# Desktop

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

Every dimension, measure, and join already defined in `semantics models` shows up in the Fields pane, ready for visuals — no Power Query, no redefining measures and dimensions.

> **Want to go deeper?** For data types, best practices, limitations, governance, and FAQs, see the [Reference Guide](/concepts/foundations/activation/bi-tools/power-bi/desktop.md).

## 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.</td></tr><tr><td>DataOS API Token</td><td>Generate or copy a token from <a href="/pages/7rh6mFCr0rhl6vO76XjW#get-a-dataos-api-token">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 **File → 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 `DataOS.mez` file and place it in your `Power BI\Custom Connectors` folder.

{% file src="/files/A0ELuYbFaIssKySkXqwe" %}

> The exact path varies by system. The default location is:
>
> ```
> [My Documents]\Microsoft 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

{% stepper %}
{% step %}

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

![In-product Power BI setup page showing the one-time setup, .pbip download, and credentials](/files/z14NNYskjSIezz0wdKrR)
{% endstep %}

{% step %}

### Download the `.pbip` file

Click **Download**. The `.pbip` package comes pre-configured with the endpoint and semantic model references for that data product.
{% endstep %}

{% step %}

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

{% hint style="warning" %}
**Keep all three items together.** Moving or deleting any of them breaks the project.
{% endhint %}

{% hint style="info" %}
**Extract before opening.** Opening the `.pbip` from inside the ZIP can throw missing-file errors.
{% endhint %}
{% endstep %}

{% step %}

### Open the `.pbip` file

Double-click it. Power BI Desktop opens it automatically. If you get a connectivity or security dialog, click OK.
{% endstep %}

{% step %}

### Enter credentials

When prompted:

* **Username:** your DataOS User ID.
* **Password:** your DataOS API token.
  {% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

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

> **Prefer using the API?** You can also download the `.pbip` file via a cURL command — useful for automation or pipelines. See the [Reference Guide → Connect via API](/concepts/foundations/activation/apis.md).

## Troubleshooting

For the full troubleshooting guide, see the [Reference Guide → Troubleshooting](/concepts/foundations/activation/bi-tools/power-bi/desktop.md#troubleshooting).

| Symptom                                                 | Quick fix                                                                                                               |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| *"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.                                                  |

***

## Reference

For data types, best practices, limitations, governance, curl-based download, and the full troubleshooting guide, see [Power BI Desktop](/concepts/foundations/activation/bi-tools/power-bi/desktop.md) in Concepts.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.