Microsoft Fabric¶

Connect Datahub to a Microsoft Fabric Data Warehouse or Lakehouse SQL analytics endpoint and query your Fabric data with natural language, insight cards, and alert thresholds — all through one service-principal connection.

Endpoint typesWarehouse · Lakehouse SQL

AuthService principal · Entra ID

Token lifetime1 hour · auto-refresh

PowersHERC · Insights · Alerts

What it powers¶

Use the Microsoft Fabric integration when your organisation stores operational or analytical data in a Fabric workspace and you want to query it from inside Datahub.

HERC natural-language queries

Ask HERC questions over your warehouse tables — "What were our top 10 products last month?" — and get answers grounded in live Fabric data.
Insight cards & dashboards

Build metric insights and dashboard cards that query Fabric as a data substrate, alongside your Databricks and catalog-backed cards.
Alert conditions

Set alert thresholds triggered by Fabric query results, so a number crossing a line pages the right people.
Schema & table browsing

Browse catalogs, schemas, tables, and columns from the metric and card builders to point queries at the right data.

What this connection does not do

No OAuth user-to-machine (U2M). Fabric's TDS endpoint requires a service principal — there is no per-user login path.
No Delta-table ingestion via Spark. That is a separate Lakehouse Spark surface, not this SQL connection.
No Fabric Notebook integration. Notebooks are a different Fabric item type.

How the connection works¶

Datahub connects to a single Fabric SQL endpoint — a Data Warehouse or a Lakehouse SQL analytics endpoint — over the TDS protocol using a service principal. That one connection then backs every query surface: HERC, insight cards, and alerts.

flowchart LR
    subgraph FAB["Microsoft Fabric workspace"]
      WH["Data Warehouse<br/>TDS endpoint"]
      LH["Lakehouse<br/>SQL analytics endpoint"]
    end
    WH --> CONN
    LH --> CONN
    CONN(["Datahub Fabric integration<br/>service principal · TDS"]) --> HERC["HERC<br/>natural-language queries"]
    CONN --> INS["Insight cards<br/>dashboard substrate"]
    CONN --> ALR["Alert conditions<br/>threshold checks"]
    CONN -.browses.-> META[("Schema browser<br/>schemas · tables · columns")]
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class CONN accent

Figure 1 — One service-principal connection to a Fabric Warehouse or Lakehouse SQL endpoint powers HERC natural-language queries, insight cards, and alert conditions, and backs the schema browser.

Why teams reach for this

One service-principal connection turns a Fabric Warehouse or Lakehouse into a governed data substrate for the whole platform — HERC answers natural-language questions over it, insight cards render dashboards from it, and alerts watch it for thresholds — without copying a single row out of Fabric.

Prerequisites¶

Prerequisite	Where	Why
A Fabric workspace with a Data Warehouse or Lakehouse SQL analytics endpoint	Microsoft Fabric	The data substrate Datahub queries.
An Azure / Entra ID tenant with app-registration rights	Azure portal	To register the service principal.
Fabric Admin access	Fabric admin portal	To enable service-principal API access.
Permission to assign workspace roles	Fabric workspace	To grant the service principal access to your warehouse.

Setup¶

Setup is a one-time, five-step chain in Azure and Fabric, followed by pasting the connection details into Datahub and testing.

flowchart LR
    A["1 · Register Entra ID app<br/>client ID + tenant ID"] --> B["2 · Create client secret<br/>copy value once"]
    B --> C["3 · Enable service principals<br/>Fabric admin portal"]
    C --> D["4 · Grant workspace access<br/>Member / Contributor"]
    D --> E["5 · Copy TDS string<br/>+ warehouse name"]
    E --> CFG["6 · Configure in Datahub<br/>Admin → Integrations"]
    CFG --> TEST{"Test connection"}
    TEST -->|pass| SAVE(["Saved · ready to query"])
    TEST -->|fail| CFG
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class CFG accent

Figure 2 — The one-time setup: register a service principal in Entra ID, authorise it in Fabric, then paste the TDS host, warehouse name, and credentials into Datahub and test the connection before saving.

Step 1 — Register an Azure app (Entra ID)¶

Open the Azure portal → Microsoft Entra ID → App registrations → New registration.
Give it a descriptive name, e.g. Datahub Fabric Connector.
Click Register and note the Application (client) ID and Directory (tenant) ID from the overview page.

Step 2 — Create a client secret¶

In the app registration, go to Certificates & secrets → New client secret.
Set an appropriate expiry (12 or 24 months).
Copy the secret value immediately — it is only visible once.

Step 3 — Enable service principals in Fabric¶

Open the Microsoft Fabric Admin portal.
Go to Tenant settings → Developer settings → Service principals can use Fabric APIs.
Enable and save — without this step, the service principal cannot connect to the TDS endpoint.

Step 4 — Grant workspace access¶

In the Fabric workspace that contains your warehouse, click the workspace name → Manage access → Add people or groups.
Search for your service principal by name or Application ID.
Assign the Member or Contributor role.

Which role to grant

Viewer is sufficient for read-only (SELECT) queries. Contributor is required for any write operations. When in doubt, grant the least privilege your use case needs.

Step 5 — Find the TDS connection string¶

In the Fabric workspace, click the warehouse tile → More options (…) → Properties.
Copy the SQL connection string — it looks like <id>.datawarehouse.fabric.microsoft.com.
Note the exact warehouse name (this becomes the InitialCatalog in the TDS connection).

Step 6 — Configure in Datahub¶

Go to Admin → Integrations → find Microsoft Fabric → Configure, then fill in the connection fields:

Field	Value	Where it comes from
TDS Server	Connection string hostname, e.g. `abc123.datawarehouse.fabric.microsoft.com` (no `https://`)	Step 5
Warehouse Name	The exact name of your warehouse or Lakehouse endpoint (the `InitialCatalog`)	Step 5
Tenant ID	Directory (tenant) ID	Step 1
Client ID	Application (client) ID	Step 1
Client Secret	The secret value you copied	Step 2

Click Test connection to verify the credentials, then Save.

Supported features¶

Feature	Supported
Natural-language queries via HERC	✅
Schema and table browsing	✅
Metric insights substrate	✅
Alert query conditions	✅
OAuth user-to-machine (U2M)	❌ (Fabric TDS requires service principal)
Delta table ingestion via Spark	❌ (separate Lakehouse Spark surface)
Fabric Notebook integration	❌ (separate Fabric item type)

Limitations¶

Limit	Why	Workaround
Service principal only.	Fabric's TDS endpoint does not support SQL authentication or OAuth U2M.	Register a service principal for all machine-to-machine access.
Read-only recommended.	The service principal connects with exactly the permissions you granted in the workspace.	Assign Viewer if you only need SELECT queries.
Lakehouse vs. Warehouse endpoint.	Both the Lakehouse SQL analytics endpoint and the Data Warehouse expose TDS, but a connection targets one.	Use the endpoint that matches your workspace setup.
Entra ID tokens expire hourly.	Tokens are short-lived (1 hour).	None needed — Datahub re-acquires a token on each query call; no manual token rotation.
Client secret expiry.	Secrets expire on the schedule you set in Step 2.	Update the Client Secret field in the integration config and save; Datahub uses the new secret immediately.

Tokens refresh themselves; secrets don't

Entra ID access tokens live for about an hour, and Datahub re-acquires one on every query call — there is no token to rotate. The client secret is the only credential you manage: when it expires, update the Client Secret field in the integration configuration and save.

Troubleshooting¶

Symptom	Likely cause	Fix
"Connection refused or host unreachable"	Wrong TDS hostname, or the warehouse is paused.	Check the TDS Server hostname is correct and does not include `https://`; verify the workspace is active and the warehouse is not paused.
"Login failed for user"	Service principals not enabled, no workspace role, or wrong credentials.	Confirm "Service principals can use Fabric APIs" is enabled (Step 3); confirm the service principal has a workspace role (Step 4); re-check the Tenant ID, Client ID, and Client Secret.
"Cannot open database"	Warehouse Name doesn't match (it is case-sensitive), or the warehouse is unavailable.	Confirm the Warehouse Name matches the warehouse exactly; confirm the warehouse is available in the workspace.
Credentials appear saved but Test connection still fails	Test connection cannot resolve the Client ID / Client Secret from the vault on the frontend.	Re-enter the Client ID and Client Secret in the form fields, then click Test connection.