Overview

ℹ️

Monte Carlo has a native Microsoft Fabric connector that should be the starting point for most users. This example is a test implementation provided as a reference for teams that need to augment or customize the native connector's behavior for their specific requirements.

This guide walks through setting up a custom connector for Microsoft Fabric using a pre-built example implementation.

Microsoft Fabric is Microsoft's unified analytics platform. This example connector uses pyodbc with the ODBC Driver 18 for SQL Server and authenticates via Azure AD Service Principal. It implements a full-mode connector — Monte Carlo connects directly to the Fabric SQL endpoint to collect metadata, query logs, and run monitors.

This implementation is available as a reference in the mcd-public-resources repository. You can use it as-is or as a starting point for your own customizations.

Feature support

ℹ️

Some metric capabilities are limited by Fabric's T-SQL dialect: regular expression matching, NaN detection, and array operations are not supported by this implementation.

Prerequisites

• A running custom-connector-setup repository — see Custom Connectors for initial setup.
• A Microsoft Fabric workspace with a SQL endpoint.
• An Azure AD Service Principal (client_id, client_secret, tenant_id) with read access to the databases and tables you want to monitor.
• Network connectivity between your build/deployment environment and the Fabric SQL endpoint.

Setup

1. Scaffold the connector

Use the create_connector script to scaffold the connector directory. This generates a unique identifier for your connector in manifest.json — this ID is how Monte Carlo distinguishes connector types, so it must be generated per-installation.

python scripts/create_connector.py microsoft_fabric

2. Replace with the example implementation

Clone or download the example from mcd-public-resources and replace the stub files with the pre-built implementation:

cp <path-to-mcd-public-resources>/custom_connectors/microsoft_fabric/connector.py connectors/microsoft_fabric/
cp <path-to-mcd-public-resources>/custom_connectors/microsoft_fabric/Dockerfile.extra connectors/microsoft_fabric/

Add the database driver to connectors/microsoft_fabric/requirements.txt:

pyodbc==5.2.0

The Dockerfile.extra installs the Microsoft ODBC Driver 18 for SQL Server from Microsoft's Debian package repository. After copying, regenerate the test Dockerfile:

python scripts/generate_test_dockerfile.py

3. Configure credentials

Create connectors/microsoft_fabric/credentials.json using the example as a reference:

{
  "connect_args": {
    "server": "your-fabric-endpoint.datawarehouse.fabric.microsoft.com",
    "database": "your_database",
    "client_id": "<azure-ad-client-id>",
    "client_secret": "<azure-ad-client-secret>",
    "tenant_id": "<azure-ad-tenant-id>"
  }
}

4. Build and run the test suite

Build the test Docker image, then run each test section to validate the connector against your Fabric endpoint:

docker compose build

# Verify connection
CONNECTOR=microsoft_fabric docker compose run --rm test -m connection

# Metadata templates
CONNECTOR=microsoft_fabric docker compose run --rm test -m metadata

# Custom SQL monitors
CONNECTOR=microsoft_fabric docker compose run --rm test -m custom_monitors

# Query language prerequisites
CONNECTOR=microsoft_fabric docker compose run --rm test -m ql_prerequisites

# Metric templates
CONNECTOR=microsoft_fabric docker compose run --rm test -m ql_metrics

5. Export and build the agent image

Once all tests pass, export capabilities and build the deployable image:

# Export capabilities and passing templates
CONNECTOR=microsoft_fabric docker compose run --rm test --export

# Build the agent image
python scripts/generate_agent_image.py --connector microsoft_fabric

6. Deploy, register, and connect

From here, follow the standard custom connector workflow:

1. Push the image to your container registry and deploy the agent.
2. Register the connector by running agent validations in the Monte Carlo UI.
3. Add the connection through the UI or API, providing your production Fabric credentials.
4. Validate with monitors by creating test monitors once your tables appear in the catalog.

Fabric-specific notes

This connector includes adaptations for Fabric's T-SQL dialect:

• Two-part table identifiers — Fabric does not support cross-database (three-part) references. The connector uses [schema].[table] notation for monitor queries, while metadata collection queries use three-part names against INFORMATION_SCHEMA.
• Bracket-escaped identifiers — All identifiers are wrapped in [brackets] to handle reserved words in T-SQL.
• OFFSET/FETCH pagination — T-SQL requires an ORDER BY clause for OFFSET/FETCH. The connector uses ORDER BY (SELECT NULL) where no meaningful ordering exists.
• Unsupported operations — Regular expression matching, NaN detection (CAST('NaN' AS FLOAT) is not supported), and array operations are not implemented.