> 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/concepts/foundations/activation/bi-tools/power-bi/desktop.md). # Desktop This page covers everything beyond the initial setup. If you're just getting started, see the [Power BI Connection Guide](/consume/activate/bi-tools/power-bi.md). ## Download the `.pbip` Project You can download the Power BI project (`.pbip`) using any of the following methods: 1. **API Documentation** – Download the project directly from your DataOS instance using the API documentation. See the [API Documentation](/concepts/foundations/activation/apis.md). 2. **Postman Collection** – Download the Postman collection and use the **Discover → Metadata → Export → Power BI** endpoint. See the [Postman Collection](/concepts/foundations/activation/apis/getting-started/postman-collection.md). 3. **SDK** – Download the project programmatically using the SDK. See the [SDK Documentation](/concepts/foundations/activation/apis/getting-started/sdks.md). 4. **cURL** – Use the cURL command shown below. ### Prerequisites * `curl` installed on your machine. * A valid DataOS API token. See the prerequisites section in the main guide. ### cURL Command ```bash curl --location \ 'https:///vulcan/tenants//data-products/-/api/v1/metadata/exports/powerbi' \ --header 'Authorization: Bearer ' \ --output .zip ``` ### Replace the Placeholders | Placeholder | Example | Description | | --------------------- | ------------------------------- | --------------------------------------- | | `` | `heliosdev-060426.dataos.cloud` | Your DataOS fully qualified domain name | | `` | `engineering` | Your tenant name | | `` | `data-visualization` | The name of the data product | | `` | `YmlfdGVzdGluZy5j...` | Your DataOS API token | ### 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 `apitoken`. 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. Replace `.SemanticModel` folder and `.pbip` file. 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 `.SemanticModel` folder and `.pbip` file. This preserves existing report visuals. #### Field selection and cross-table queries When building Power BI reports against a semantic model, follow these best practices to ensure accurate query results: * Select dimensions and measures from tables that are connected through **valid relationships** in the semantic model. * Relationships in Power BI define **filter propagation**, not automatic SQL joins. The existence of a relationship does **not** guarantee that Power BI will generate a SQL `JOIN` during query execution. * Avoid combining fields from **unrelated semantic models**. When no valid relationship exists, Power BI does not return an error; instead, it evaluates the measure independently, which can produce repeated or cross-join-like results. * Avoid using a **dimension from a fact model** (for example, `Orders`) together with a **measure from a related dimension model** (for example, `Customer` or `Product`). In a typical star schema, filters propagate from dimension tables to the fact table. As a result, the fact table dimension cannot filter the related dimension model, which may lead to repeated or unexpected results. * Define all required relationships in the semantic model before building reports. Relationships cannot be created or modified in Power BI when connecting to a model-first data product using DirectQuery. > **Note:** These behaviors are part of Power BI's query engine and relationship semantics. They are expected Power BI behavior and are not specific to the semantic model implementation. #### Custom measures and dimensions Custom measures and dimensions created in Power BI are not supported for model-first data products and may produce unexpected results. Define all measures, dimensions, and business logic in the semantic models instead. ### 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. ### Limitations | Limitation | Detail | | ----------------------------------- | ----------------------------------------------------------------------------------------------- | | **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. | | **Direct publishing** | Not supported. Schema updates require manual download and replacement. | | **Separate connection per product** | Each data product requires its own connection configuration in Power BI. | | **macOS** | Power BI Desktop is Windows-only. | | **Cyclic Realtionship** | Power BI doesn't allow cyclic relationship | ### 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. #### 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](/consume/activate/bi-tools/power-bi/service.md). ### Troubleshooting #### 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? Power BI Desktop version **2.132.908.0** or later (released August 2024) is required. This version supports `.pbip` files natively without enabling preview features. *** #### What happens when the semantic model schema changes? Re-sync is required. Download the updated `.pbip` ZIP, extract it, and replace the `.SemanticModel` folder and `.pbip` file. This preserves your existing reports, visuals, and formatting. *** #### Can I create custom measures in Power BI? No. All measures and dimensions must be defined in the semantic model. *** #### Does each data product need its own Power BI connection? Yes. Each model-first data product in DataOS requires its own connection configuration in Power BI. *** #### How does governance work for report viewers? Vulcan enforces row-level and column-level security using the connecting user's DataOS credentials. *** #### How is data freshness maintained? Power BI uses **DirectQuery** mode, which queries the underlying data source in real time. Since no data is imported into Power BI, scheduled dataset refresh is not required. Ensure that upstream data pipelines are healthy and available. *** #### What data sources can be synced to Power BI? All data sources supported by Vulcan can be synced to Power BI through the semantic model. *** #### Is Power BI Service supported? Yes. Publishing to Power BI Service is supported through an **On-premises Data Gateway**. The gateway machine must have: * MySQL ODBC Connector **8.0.23** * The `LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN` environment variable configured For detailed setup instructions, see the [Power BI Service guide](/consume/activate/bi-tools/power-bi/service.md). *** #### Can I use Import mode instead of DirectQuery? No. Model-first data products support **DirectQuery** mode only. *** #### Why does Power BI return results when I combine fields from unrelated semantic models? This is expected Power BI behavior. If you select a dimension from one semantic model and a measure from another semantic model that has **no relationship**, Power BI does not return an error. Instead, it evaluates the measure independently and repeats the result for each dimension value. This may appear similar to a cross join. **Recommendation** Only combine dimensions and measures from semantic models that are connected through valid relationships. *** #### Why do I get repeated or unexpected results when I use a dimension from the Orders model with measures from Customer or Product? This is expected Power BI behavior. Relationships in Power BI define **filter propagation**, not automatic SQL joins. In a typical star schema, filters propagate from **dimension models** (such as Customer or Product) to the **fact model** (Orders). If you use: * a dimension from **Orders**, and * a measure from **Customer** or **Product** the filter on **Orders** cannot propagate back to the related dimension model. As a result, Power BI evaluates the measure independently and may return repeated or cross-join-like results. **Recommendation** For accurate results: * Use dimensions from **Customer** or **Product** when analyzing measures from **Orders**. * Avoid using dimensions from the fact model (`Orders`) to slice measures defined on related dimension models unless the semantic model explicitly supports that filter direction. *** #### Does a relationship guarantee that Power BI will generate a SQL JOIN? No. Relationships in Power BI define **filter propagation**, not SQL joins. Even when a relationship exists, Power BI generates a SQL `JOIN` only when it is required to evaluate the requested filter context. The presence of a relationship does **not** guarantee that the generated SQL will include a `JOIN`. --- # 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/concepts/foundations/activation/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.