> 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/references/interfaces/bi-tools/power-bi-desktop.md). # Power BI Desktop This page covers everything beyond the initial setup. If you're just getting started, see the [Power BI connection guide](https://v2.dataos.info/consume/activate/bi-tools/desktop). ### Connect via API (cURL) Use this approach to automate the `.pbip` download or integrate it into a pipeline. If you prefer the UI, use the steps in the main guide instead. #### Prerequisites * `curl` installed on your machine * Your DataOS API token (see prerequisites) #### Command ```bash curl --location \ 'https:///vulcan/tenants//data-products/-/api/v1/metadata/exports/powerbi' \ --header 'Authorization: Bearer ' \ --output .zip ``` #### Replace | Placeholder | Example | Description | | ------------------ | ------------------------------- | --------------------------------------- | | `` | `heliosdev-060426.dataos.cloud` | Your DataOS fully qualified domain name | | `` | `engineering` | Your tenant name | | `` | `data-visualization-postman` | The data product resource name | | `` | `YmlfdGVzdGluZy5j...` | Your DataOS API | #### Full example ```bash curl --location \ 'https://heliosdev-060426.dataos.cloud/vulcan/tenants/engineering/data-products/engineering-data-visualization-postman/api/v1/metadata/exports/powerbi' \ --header 'Authorization: Bearer ' \ --output powerbi-export.zip ``` {% hint style="info" %} The `Authorization` header uses `Bearer`, not `apikey`. Use your DataOS API token. {% endhint %} #### Steps after download 1. Extract the ZIP. You get the same three-file structure as the UI method (`.pbip`, `.Report/`, `.SemanticModel/`). 2. Open the `.pbip` file in Power BI Desktop. 3. Enter your DataOS username and API token when prompted. 4. Click **Connect → OK**. {% hint style="warning" %} **Extract fully before opening.** Opening the `.pbip` from inside the ZIP causes missing file errors. {% endhint %} ### Supported data types | Category | Data types | Status | | ------------- | -------------------------------------------------------------------------------------------- | ----------- | | **Dimension** | `time`, `string`, `number`, `boolean` | ✅ Supported | | **Measure** | `max`, `min`, `number`, `sum`, `count`, `boolean`, `string`, `time`, `avg`, `count_distinct` | ✅ Supported | ### Important considerations #### Measure naming Measures in Power BI carry an `modelname_` prefix to distinguish them from dimensions. For example, a measure for total revenue in sales semantic model appears as `sales_total_revenue` in the Fields pane. #### Live connection The connection is live. Any changes to the underlying data are reflected in Power BI automatically without a manual refresh. #### Schema changes require a re-sync If a dimension, measure, or any other semantic model element is added, modified, or removed (CRUD), the model must be re-synced. To avoid losing existing reports when re-syncing: 1. Download the new `.pbip` ZIP from Data Product Hub. 2. Extract the new ZIP. 3. Copy **only** the new `model.bim` file from the new `.SemanticModel` folder. 4. Paste it into your existing project's `.SemanticModel` folder, replacing the old one. This updates the model definition without touching your existing report layout. ### Best practices #### File handling * Always **fully extract** the ZIP before opening the `.pbip` file. Opening from within a ZIP causes missing file errors. * Keep the three extracted items (`.pbip`, `.Report/`, `.SemanticModel/`) in the same folder at all times. * When re-syncing after a schema change, replace only `model.bim`. Do not replace the entire folder. This preserves existing report visuals. #### Field selection and cross-table queries Power BI does not automatically resolve transitive joins. When building visuals: * Select fields from tables that are **directly related or logically joined** in the semantic model. * Selecting fields from unrelated tables produces incorrect or incomplete results. * All relationships and joins must be defined in the semantic model. They cannot be created in Power BI when using DirectQuery with a model-first data product. #### Custom measures and dimensions Custom measures and dimensions **cannot** be created in Power BI when connected to a model-first data product. All logic must be defined in the semantic model itself. #### Special characters in data Power BI fails to handle special characters (e.g. `&`, `%`, `#`) in values when generating queries through the synced semantic model. Remove or replace special characters at the data source or during semantic modelling, not in Power BI. #### Percentage formatting Power BI does not auto-apply percentage formatting. Set it manually: * **For a dimension:** Select the dimension → **Column Tools → Formatting → Percentage** ### How the connection works When Power BI opens a `.pbip` file synced from DataOS: 1. Power BI Desktop authenticates using your DataOS username and API token via DirectQuery on port `3306`. 2. Queries are routed through the mysql proxy to the API. 3. The API forwards requests to Transpiler, which translates them into native SQL and queries the underlying data source. 4. Results are returned to Power BI for rendering. Computation happens in two places: 1. Transpiler translates semantic model queries into native SQL; 2. The data source performs the actual retrieval. Visual refresh time depends on source performance. ### Limitations | Limitation | Detail | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Rolling window measures** | Not supported in DirectQuery mode. DirectQuery lacks date hierarchy support required for time-based rolling window logic. | | **Custom measures / dimensions** | Cannot be created in Power BI for model-first products. Define all logic in the semantic model. | | **DAX functions** | Not supported. | | **Import query mode** | Not supported. DirectQuery only. | | **Special characters** | `&`, `%`, `#` and similar characters in data values cause query errors. Handle them upstream. | | **Direct publishing** | Not supported. Schema updates require manual download and `model.bim` replacement. | | **Separate connection per product** | Each data product requires its own connection configuration in Power BI. | | **macOS** | Power BI Desktop is Windows-only. | ### Governance #### Authentication and authorisation When a semantic model is activated via BI Sync, Power BI authenticates using the DataOS Id and API token of the connecting user. Vulcan enforces data policies based on that user's group permissions. #### Column-level and row-level policies Columns redacted by vulcan data policies are hidden automatically. They do not appear in the Fields pane and cannot be queried. This applies consistently whether the user is browsing in studio or building reports in Power BI. #### Example A user in the `Analyst` group who is restricted from viewing the `Annual Salary` column will not see that column in Power BI after syncing. The restriction is enforced by vulcan, not by Power BI, so it cannot be bypassed from within Power BI. #### Report distribution When a Power BI report is published to Power BI Service, data policies from the original publisher's credentials are applied to all viewers. To publish reports to Power BI Service, see the [Power BI Service guide](https://v2.dataos.info/consume/activate/bi-tools/service). ### Troubleshooting #### There weren't enough elements in the enumeration to complete the operation The wrong MySQL ODBC connector version is installed. Uninstall all MySQL ODBC connectors on the machine and reinstall **version 8.0.23** using the link in the prerequisites. #### The DataOS connector doesn't appear in Power BI Check both of the following: * The `DataOS.mez` file is in `[My Documents]\Microsoft Power BI Desktop\Custom Connectors\` * **Allow any extension to load without validation or warning** is selected under **File → Options → Security → Data Extensions** Restart Power BI Desktop after making either change. #### Authentication fails with "cleartext password not allowed" `LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1` is either not set or was added under **User variables** instead of **System variables**. Correct it, then fully restart Power BI Desktop so the new variable is picked up. ### FAQs #### What Power BI Desktop version is required? Version `2.132.908.0` or later (released August 2024). This version supports `.pbip` files natively without enabling preview settings. #### What happens when the semantic model schema changes? Re-sync is required. Download the updated `.pbip` ZIP, extract it, and replace only the `model.bim` file in your existing project's `.SemanticModel` folder. This preserves all existing visuals. #### Can I create custom measures in Power BI? No. All measures and dimensions must be defined in the semantic model. For flexible ad-hoc analysis, connect to the DataOS Lakehouse instead. #### Does each data product need its own Power BI connection? Yes. Each model-first data product in DataOS requires a separate connection configuration in Power BI. #### How does governance work for report viewers? Lens enforces column-level and row-level policies based on the connecting user's DataOS credentials. Restricted columns are invisible in the Fields pane and cannot be queried from within Power BI. #### How is data freshness maintained? Power BI uses DirectQuery mode, which queries the data source live. No scheduled refresh is needed. Monitor upstream pipelines to ensure data source availability. #### What data sources can be synced to Power BI? All data sources supported by vulcan can be synced. #### Is Power BI Service supported? Yes, with an on-premises data gateway. The gateway machine must have the MySQL ODBC 8.0.23 connector installed and the `LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN` environment variable set. See the [Power BI Service guide](https://v2.dataos.info/consume/activate/bi-tools/service). #### Can I use Import mode instead of DirectQuery? No. Only DirectQuery is supported for model-first data products. #### Where is computation performed? In two layers: Lens translates semantic queries into native SQL; the underlying data source handles the actual computation and retrieval. --- # 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/references/interfaces/bi-tools/power-bi-desktop.md?ask=&goal= ``` `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.