> 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/build/productize/connect-engine/microsoft-fabric.md).

# Microsoft Fabric

Configure Microsoft Fabric Warehouse as the engine for your Data Product.

Microsoft Fabric Warehouse is a SaaS T-SQL data warehouse built on OneLake, with Entra-ID-only authentication. Use the `fabric` adapter when your organization already standardizes on Fabric for its lakehouse/warehouse estate. This page covers the connection. For materialization internals, catalog lifecycle, and the full reference, see the [Microsoft Fabric engine manual](https://v2.dataos.info/references/engine-guide/microsoft-fabric) in References.

{% hint style="info" %}
The Fabric adapter is a community contribution with limited community support, and it covers the Fabric **Warehouse** SQL endpoint only, not Fabric Lakehouse, OneLake direct access, Direct Lake mode, or Fabric Spark. Validate against your own Fabric capacity before depending on it for critical workloads.
{% endhint %}

## Before you start

* A Fabric workspace with an assigned capacity, and a Fabric Warehouse item (or the ability for Vulcan to create one via the Fabric REST API).
* An Entra ID app registration (service principal) with a workspace role.
* The workspace's `tenant_id` and `workspace_id`. Fabric has no local Docker equivalent, so local development connects to a real (typically dev-tier) workspace.
* DataOS access: a `roles:id:data-dev`-equivalent role tag, **Can Use** on Compute and Secrets, a git-sync Secret, and a Fabric workspace **Contributor** role for the service principal (Fabric and DataOS authorization are separate; a DataOS grant alone does not authorize the service principal in Fabric).

## Permissions

Three roles, each with a distinct scope: a Fabric workspace admin, the Vulcan service principal, and a consumer role.

| Grant                                              | Required for                                                         |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| **Contributor** workspace role (service principal) | Running models, creating/dropping warehouses via the Fabric REST API |
| SQL endpoint read/write access                     | Model materialization                                                |
| **Viewer** workspace role (consumer)               | Read-only access to Data Product tables                              |

Grant the service principal a workspace role in the Fabric portal (**Workspace settings → Manage access → Add people or groups**), then verify its SQL-level access: `SELECT name, type_desc FROM sys.database_principals WHERE name = '<service-principal-name>';`

{% hint style="warning" %}
Fabric authorization is separate from DataOS authorization. A DataOS role tag or **Can Use** grant alone doesn't give the service principal a Fabric workspace role. Both are required.
{% endhint %}

## Connection options

Connect directly with a service principal, with credentials supplied through a Secret's projection. This is the only supported connection path for Fabric — a DataOS Depot cannot be used.

| Option                                                              | Required | Description                                                                                                |
| ------------------------------------------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------- |
| `type`                                                              |    Yes   | Must be `fabric`                                                                                           |
| `host`                                                              |    Yes   | Fabric Warehouse SQL analytics endpoint                                                                    |
| `tenant_id`                                                         |    Yes   | Azure/Entra tenant UUID                                                                                    |
| `workspace_id`                                                      |    Yes   | Fabric workspace UUID                                                                                      |
| `user`                                                              |    No    | Service principal client ID                                                                                |
| `password`                                                          |    No    | Service principal client secret                                                                            |
| `database`                                                          |    No    | Target warehouse name                                                                                      |
| `port`                                                              |    No    | Default `1433`                                                                                             |
| `driver`                                                            |    No    | Fabric only supports `pyodbc`                                                                              |
| `odbc_properties`                                                   |    No    | For example `authentication: ActiveDirectoryServicePrincipal`                                              |
| `timeout`, `login_timeout`, `charset`, `appname`, `conn_properties` |    No    | Tune as your environment needs. `login_timeout` defaults to 60s; `timeout` (query timeout) has no default. |
| `autocommit`                                                        |    No    | Defaults `true` — the adapter does not rely on explicit transactions                                       |

### Authentication methods

* **Service principal** (the only supported method for gateways and deployment; interactive browser authentication works for local exploration only): register an Entra app registration with workspace access, set `user` to the client ID and `password` to the client secret, plus `tenant_id` and `workspace_id`. Set `driver: pyodbc` and `odbc_properties: {authentication: ActiveDirectoryServicePrincipal}`.
* Always inject the client secret from an environment variable: `password: "{{ env_var('FABRIC_CLIENT_SECRET') }}"`.

## Example

```yaml
gateways:
  fabric:
    connection:
      type: fabric
      host: xxxxx.datawarehouse.fabric.microsoft.com
      driver: pyodbc
      driver_name: "ODBC Driver 18 for SQL Server"
      odbc_properties:
        authentication: ActiveDirectoryServicePrincipal
      user: "{{ env_var('FABRIC_CLIENT_ID') }}"
      password: "{{ env_var('FABRIC_CLIENT_SECRET') }}"
      tenant_id: "{{ env_var('FABRIC_TENANT_ID') }}"
      workspace_id: "{{ env_var('FABRIC_WORKSPACE_ID') }}"
      database: warehouse
```

Validate with `vulcan --log-to-stdout plan`. In production, keep the service-principal values in a DataOS Secret and project them into the environment rather than committing them — the gateway config stays the same, reading `FABRIC_CLIENT_ID` / `FABRIC_CLIENT_SECRET` / `FABRIC_TENANT_ID` / `FABRIC_WORKSPACE_ID` from the environment. Apply the Secret, the git-sync Secret, the project configuration, and the Vulcan resource in that order.

Fabric has no local Docker equivalent, so unlike Postgres or Spark there's no self-hosted stack to develop against — point local development at a real, typically dev-tier, Fabric workspace, and rely on `vulcan plan` dry-runs plus unit tests (which run against DuckDB locally, not Fabric) to iterate before touching the shared warehouse.

## Supported model kinds

`FULL`, `SEED`, `VIEW`, `INCREMENTAL_BY_TIME_RANGE`, `INCREMENTAL_BY_UNIQUE_KEY`, `INCREMENTAL_BY_PARTITION`, `INCREMENTAL_UNMANAGED`, `SCD_TYPE_2`, `SCD_TYPE_2_BY_TIME`, `SCD_TYPE_2_BY_COLUMN`, and `EMBEDDED`, inherited from the MSSQL adapter this engine subclasses. Table cloning, native indexes, and `MANAGED` models aren't supported. For how each kind materializes, see the [Microsoft Fabric engine manual](https://v2.dataos.info/references/engine-guide/microsoft-fabric).

> Fabric Warehouse has no explicit transactions and no native indexes: time-range and partition overwrites run as separate `DELETE` + `INSERT` statements (not `MERGE`), so avoid overlapping schedules (`concurrencyPolicy: Forbid`). `INCREMENTAL_BY_UNIQUE_KEY` is the exception — it still uses native `MERGE INTO`. Warehouse creation and deletion run through the async Fabric REST API rather than synchronous DDL, and recreating a warehouse immediately after dropping it can return `ItemDisplayNameNotAvailableYet` while cleanup finishes. `ALTER TABLE` cannot change a column's type directly — the adapter works around this with an add-cast-drop-rename sequence, which is a full column rewrite, not a metadata-only operation.

## Limits and performance

Fabric Warehouse compute is tied to the workspace's assigned Fabric capacity (an F-SKU), not a per-query warehouse you resize yourself — sizing that capacity is a Fabric-admin decision, not something Vulcan controls. Start `concurrent_tasks` at 2 for daily incrementals, and use `concurrencyPolicy: Forbid` on every scheduled workflow: because DELETE\_INSERT overwrites aren't wrapped in a transaction, a second run's `DELETE` can race a first run's `INSERT` with no isolation to fall back on.

Since there's no user-tunable indexing, sizing conversations center on query shape and capacity tier. If concurrency or latency degrades, fix in order: remove cross-join-shaped queries, pre-aggregate high-cardinality `COUNT(DISTINCT ...)` measures into a mart, stagger schedules so DELETE\_INSERT incrementals never overlap on the same table, then escalate the Fabric capacity tier as a platform-level change.

## Troubleshooting

| Symptom                                                          | Likely cause                                            | Fix                                                                                       |
| ---------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Authentication failed after a warehouse drop                     | Connection string still points at a dropped `Database=` | Close and reopen the connection against a valid warehouse.                                |
| `ItemDisplayNameNotAvailableYet`                                 | Warehouse recreated immediately after being dropped     | Wait for cleanup to finish; scripted flows should add a delay.                            |
| `CREATE INDEX` fails or is a no-op                               | Fabric Warehouse does not support user indexes          | Remove index DDL from `post_statements`; rely on query shape and pre-aggregation instead. |
| Incremental left the table in a partial state after a failed run | No explicit transaction wraps DELETE\_INSERT            | Re-run the affected window; avoid overlapping schedules with `concurrencyPolicy: Forbid`. |
| `vulcan plan` runs DDL                                           | Lifecycle DDL not guarded                               | Wrap it in `@IF(@runtime_stage = 'evaluating', ...)`.                                     |

For the full failure-mode table, health-check queries, and recovery procedures, see [Troubleshooting](https://v2.dataos.info/references/engine-guide/microsoft-fabric/troubleshooting) in the Microsoft Fabric engine manual.

Once `vulcan info` succeeds, continue to [Assets](https://v2.dataos.info/build/productize/assets.md).


---

# 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/build/productize/connect-engine/microsoft-fabric.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.
