> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Fabric

> Integrating Microsoft Fabric with Coalesce Quality

<Note>
  This guide explains how to connect Coalesce Quality to a Microsoft Fabric workspace securely.
  We need this information so we can collect metadata about the tables in your Fabric Warehouses and Lakehouses.

  To finish this guide, you'll need the following:
  <br /> → Permission to register a Microsoft Entra application (service principal) in your tenant, or an admin who can
  <br /> → A **Fabric administrator** to enable the tenant setting that lets service principals call Fabric
  <br /> → A workspace **admin** to give the service principal a role on the workspace (**Contributor** for the full feature set, including query history)

  ⏱️ Estimated time to finish: 15 minutes.
</Note>

Microsoft Fabric exposes each workspace through a shared **SQL analytics endpoint** that speaks T-SQL. Coalesce Quality connects to that endpoint to read the metadata of every Warehouse and Lakehouse in the workspace. A single integration covers the whole workspace — each Warehouse / Lakehouse appears as a database, and Coalesce Quality queries across them using three-part `[database].[schema].[table]` names.

Authentication is via a Microsoft Entra ID **service principal**. Fabric does not accept SQL logins, so this is the only way to connect a headless integration.

## Data we collect

We read metadata from your workspace's SQL analytics endpoint using the dedicated service principal described below. Depending on which features you enable in the integration, we ingest:

* **Catalog** — the workspace's databases (Warehouses and Lakehouse SQL endpoints), schemas, tables, views, columns, data types, and constraints. Fabric constraints (primary key / unique / foreign key) are informational (`NOT ENFORCED`) but are still read from metadata.
* **SQL definitions** — the T-SQL of views, stored procedures, and functions. Used for lineage and to detect references between objects.
* **Table metrics** — row counts and last-modified timestamps for anomaly detection, collected for the tables in scope (see **Metrics scope** below).
* **Query history** *(recommended, on by default)* — read from the workspace's `queryinsights` system views for cost attribution and SQL / column-level lineage. Management-plane reads only — no per-query billing. Requires the service principal to have the **Contributor** (or higher) workspace role — see [Give the service principal a role on the workspace](#3-give-the-service-principal-a-role-on-the-workspace).

<Note>
  **Metadata only.** The service principal below only needs to read your **schema and DDL**, never row data. Coalesce Quality issues data-reading queries (row counts, samples for monitors) only when you enable the corresponding opt-in feature in the integration UI. With every opt-in disabled, the integration runs metadata queries only.
</Note>

## Set up access

### 1. Register an Entra service principal

The integration authenticates as a Microsoft Entra application (service principal) with a client secret. You can create one in the [Entra admin center](https://entra.microsoft.com) (**App registrations → New registration**), or with the Azure CLI:

```bash theme={null}
# Sign in to your tenant
az login --tenant <your-tenant>

# 1. Create the app registration
APP_ID=$(az ad app create \
  --display-name "coalesce-quality-fabric-scraper" \
  --sign-in-audience AzureADMyOrg \
  --query appId -o tsv)
echo "Client (application) ID: $APP_ID"

# 2. Create the service principal for that app
az ad sp create --id "$APP_ID"

# 3. Mint a client secret (the value is shown only once — store it securely)
az ad app credential reset \
  --id "$APP_ID" \
  --display-name "coalesce-quality" \
  --years 1 \
  --query "{clientId:appId, clientSecret:password, tenantId:tenant}" -o json
```

Take note of the **Client ID**, **Client secret**, and **Tenant ID** — you'll enter them in the Coalesce Quality UI.

### 2. Allow service principals to use Fabric

A **Fabric administrator** must enable this once for the tenant:

1. Open the [Fabric admin portal](https://app.fabric.microsoft.com/admin-portal) → **Tenant settings → Developer settings**.
2. Enable **"Service principals can use Fabric APIs"**.
3. We recommend scoping it to a security group that contains only this service principal, to keep the blast radius small.

Without this setting the service principal cannot obtain a Fabric token and every connection fails.

### 3. Give the service principal a role on the workspace

A workspace admin adds the service principal to the workspace that holds the Warehouses / Lakehouses you want to monitor. Open the workspace → **Manage access → Add people or groups**, search for the app registration by name, and assign a role.

Which role you need depends on the features you enable:

| Feature                                                   | Minimum access                                                        |
| --------------------------------------------------------- | --------------------------------------------------------------------- |
| Databases, schemas, tables, columns, constraints          | **Viewer**                                                            |
| View / procedure / function **SQL definitions** (lineage) | **Viewer** + `GRANT VIEW DEFINITION` (see step 4), or **Contributor** |
| **Table metrics** and monitor samples (row data)          | **Viewer** + `GRANT SELECT` (see step 4), or **Contributor**          |
| **Query history** (`queryinsights`)                       | **Contributor**, Member, or Admin                                     |

We recommend **Contributor** — it covers every feature, including query history, with no extra SQL grants. Query history in particular reads Fabric's `queryinsights` system views, which are **only accessible to Contributor / Member / Admin**; a Viewer cannot read them even with SQL grants.

Choose **Viewer** only for tightest least privilege, and add the SQL grants in step 4 to recover SQL definitions and metrics. Query history is not available to a Viewer.

### 4. (Optional) Least-privilege SQL grants for a Viewer

If you assigned **Viewer** rather than Contributor, grant the service principal exactly what the enabled features read. Run this in each Warehouse you monitor, using the app registration's display name — Fabric resolves the Entra principal by name, so no separate user-creation step is needed:

```sql theme={null}
GRANT VIEW DEFINITION TO [coalesce-quality-fabric-scraper];   -- SQL definitions / lineage
GRANT SELECT          TO [coalesce-quality-fabric-scraper];   -- only if table metrics / samples are enabled
```

These grants cannot unlock query history: `queryinsights` is gated by the workspace role, so leave the service principal on **Contributor** (or higher) if you want **Fetch query history** enabled.

### 5. Network access

The Fabric SQL analytics endpoint is a public Azure endpoint (`<workspace-id>.datawarehouse.fabric.microsoft.com`, port 1433, TLS required). There is nothing to allowlist on the Fabric side. See the [Coalesce Quality IP Whitelist](/security/ip) only if your tenant restricts outbound access to the endpoint by IP.

## Input data in the Coalesce Quality UI

Navigate to **Data Sources → Add integration → Microsoft Fabric** and provide:

### Integration name

For example `Microsoft Fabric`.

### SQL analytics endpoint

The workspace SQL analytics endpoint, e.g. `<workspace-id>.datawarehouse.fabric.microsoft.com`. You'll find it on any Warehouse or SQL analytics endpoint in the workspace under **Settings → SQL analytics endpoint** (the SQL connection string). Every Warehouse and Lakehouse in the workspace shares this host, so one integration covers the whole workspace.

### Default warehouse (optional)

The Warehouse or Lakehouse name used to resolve *unqualified* ad-hoc queries; leave empty to use `master`. Metadata and monitor SQL are fully qualified across every Warehouse in the workspace, so this only affects ad-hoc queries.

### Microsoft Entra service principal

* **Application (client) ID** — the Entra application (client) ID from step 1.
* **Client secret** — the service principal client secret. Stored encrypted and never displayed again in our UI.
* **Directory (tenant) ID (optional)** — only needed when the service principal lives in a different Entra tenant than the Fabric endpoint; inferred automatically when left blank.

### Data collection

* **Fetch query history** *(recommended, on by default)* — reads the workspace's `queryinsights` query history for cost attribution and SQL / column-level lineage. Management-plane reads only — no per-query billing. Needs the service principal on the **Contributor** (or higher) workspace role; a Viewer cannot read `queryinsights`. Databases without a `queryinsights` schema (Lakehouse SQL endpoints, Fabric SQL databases, mirrored databases) are skipped automatically.

### Scope

Narrow the workspace down to what you want to monitor. Both scopes support include **and** exclude rules at the **Warehouse**, **schema**, and **table** levels:

* **Catalog scope** — which Warehouses, schemas, and tables are ingested into the catalog. Empty means everything is ingested.
* **Metrics scope** — which tables are scanned for metrics. Empty means metrics are collected for all ingested tables.

## Personal access (user OAuth)

In addition to the workspace service principal above, you can let each Coalesce Quality member authenticate as themselves against Fabric through Microsoft Entra. Queries then run under the member's own Entra identity and respect the Fabric workspace roles, item permissions, and row-level security on that user. See [Data Warehouse Access](/security/dwh-access) for the full model and when to enable it.

To enable personal access, an Entra admin registers a **separate** OAuth app once (distinct from the connection service principal above), then pastes its client ID and secret into the Fabric integration's edit page in Coalesce Quality under **Warehouse access**.

### Register the OAuth app in Microsoft Entra

1. In the [Entra admin center](https://entra.microsoft.com), open **App registrations → New registration** and give it a name, e.g. `coalesce-quality-fabric-user-oauth`.
2. Under **Authentication → Add a platform → Web**, add the **Redirect URI(s)** for the Coalesce Quality region(s) your members use, with no trailing slash:
   * EU: `https://app.synq.io/auth/dwh-oauth/callback`
   * US: `https://app.us.synq.io/auth/dwh-oauth/callback`
3. Under **API permissions → Add a permission → APIs my organization uses**, search for **Azure SQL Database**, choose **Delegated permissions**, and add **`user_impersonation`** (this is the `https://database.windows.net/user_impersonation` scope). No tenant-admin consent is required — it's user-consentable, so each member consents once at sign-in.
4. Under **Certificates & secrets → New client secret**, create a secret and copy its value (shown only once).
5. Copy the **Application (client) ID** and the **client secret**.

In Settings → Integrations → *(your Fabric integration)* → Warehouse access → Personal credentials, paste the Client ID and Client secret. Members will then see this Fabric integration listed under Settings → Warehouse access → My credentials and can connect with their own Entra identity.

<Note>
  Coalesce Quality builds the Entra authorize URL automatically (`https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize`) — you don't need to enter an authority or tenant. `organizations` lets each member's home tenant resolve the app, so one app registration works across every workspace and Coalesce Quality region whose redirect URI you added in step 2.
</Note>