Connectors
Read and write existing Microsoft Fabric data — warehouses, SQL databases, Lakehouse SQL endpoints, semantic models, and KQL databases — from a Rayfin app.
Connectors let a Rayfin app query data it does not own. Your entities live in the database Rayfin provisions for you; a connector points at data that already exists somewhere else in Microsoft Fabric — a Warehouse, a SQL Database, a Lakehouse SQL analytics endpoint, a Power BI semantic model, or a KQL database — and exposes it through the same client.
Connectors are stable in Rayfin 1.36. rayfin connector is always registered.
rayfin up connector apply remains Preview.
The two categories
Which commands apply, and what your app code looks like, depends on the connector's category.
| Category A — entity connectors | Category B — query connectors | |
|---|---|---|
| Types | fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase | fabric-semanticmodel; existing kusto entries only |
| App surface | client.connectors.<name>.<Entity> — typed CRUD | client.connectors.<name>.executeQuery(...) |
| You write | Entity classes with @role() policies | A DAX or KQL query string |
| Row-level security | Yes, via @role() policies | No — the source enforces its own |
| Schema discovery | Yes — metadata.json | No |
| Auth | application by default; delegated allowed | delegated only |
Category A turns Fabric SQL into typed entities that behave like your own — see Fabric SQL sources. Category B hands a raw query to a platform-managed function and returns a table — see Semantic models and KQL databases.
Connector types
| Type | Fabric item | Category | Operations | Auth |
|---|---|---|---|---|
fabric-sqlanalytics | Lakehouse SQL analytics endpoint | A | read | Default application; allows delegated Changed in 1.36 |
fabric-warehouse | Warehouse | A | read, create, update, delete | Default application; allows delegated Changed in 1.36 |
fabric-sqldatabase | SQL Database | A | read, create, update, delete | Default application; allows delegated Changed in 1.36 |
fabric-semanticmodel | Semantic model | B | executeQuery | delegated |
kusto | KQL Database | B | executeQuery, executeCommand | Existing connectors only; new authoring is held in 1.36 Changed in 1.36 |
Lakehouse SQL analytics endpoints are read-only at the source, so fabric-sqlanalytics allows only read. Category B types are pinned to an adapter version (version: '1' today) and are delegated-only. rayfin up rejects auth.type: application on them.
In 1.36.2, connector add --type kusto fails with this exact message:
Connector type "kusto" is not available in this release. Supported types: [fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, fabric-semanticmodel].Existing Kusto connector entries still validate and deploy. See Connector authentication.
Run npx rayfin connector types --json to print the live catalog, including the exact client
packages and version to install for each type.
Connector commands are always available
Run npx rayfin connector types --json to print the live authoring catalog. The JSON includes exact package names, roles, and the Rayfin version to install.
New projects do not need an opt-in gate; connectors graduated in 1.36.
How a connector reaches your app
Nothing about the source reaches the browser. The workspace and item IDs live in
rayfin.yml and are injected server-side, so a client-side query carries only the query
itself.
Where connector state lives
| Path | Written by | Contents |
|---|---|---|
rayfin/rayfin.yml | connector add | The connectors: block — name, type, version, config, auth, operations |
rayfin/connectors/<name>/metadata.json | connector add | Discovered schema. Category A only. Never edit by hand |
rayfin/connectors/<name>/schema.ts | connector add, then you | The typed marker and connectorConfig your app imports |
connector add scaffolds a placeholder schema.ts for Category A. You replace it with
the aggregate schema after generating entity files — see
Generating entity files. For Category B the generated
schema.ts is complete and must not be edited.
The workflow
1. Find the source
npx rayfin connector search lists the Fabric items the signed-in identity can add, with a
ready-to-run add command for each.
2. Add it
npx rayfin connector add --type <type> --workspace-id <id> --item-id <id> writes the
rayfin.yml entry and scaffolds the connector directory. See
Adding a connector.
3. Install the packages
connector add scaffolds files but installs nothing. Run the version-pinned npm install
it prints, verbatim.
4. Build the typed surface
Category A: generate entity files from metadata.json and write the aggregate schema.ts.
Category B: the generated schema.ts is already complete.
5. Wire the client
Expose the connector as client.connectors.<name> through ConnectorsRayfinClient — see
Wiring connectors into your app.
6. Deploy
npx rayfin up deploys the connector alongside the rest of the app.
In this section
- Adding a connector —
search,add,list,remove, and therayfin.ymlentry they produce. - Wiring connectors into your app —
ConnectorsRayfinClient, the runtime map, and the bundling trap to avoid. - Fabric SQL sources — reading and writing Category A entities, and what each dialect returns.
- Generating entity files — turning
metadata.jsoninto entity classes with row-level policies. - Semantic models — running DAX and reading the result.
- KQL databases — running KQL queries and management commands.
- Connector authentication —
delegatedversusapplication, and the permissions each needs.
In my Rayfin project, connect to an existing Microsoft Fabric data source (ask me which one —
a Warehouse, SQL Database, Lakehouse SQL analytics endpoint, or semantic model,
and ask me for its workspace ID and item ID rather than inventing them. If I ask for a KQL database on Rayfin 1.36.2, stop and report that new Kusto connector authoring is held in this release).
Run `npx rayfin connector add --type <type> --workspace-id <id> --item-id <id>` and run
the version-pinned npm install command it prints, verbatim — do not drop the version.
If it is a Category A type (fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase),
generate entity files from rayfin/connectors/<name>/metadata.json and overwrite the
placeholder schema.ts with the aggregate schema. If it is fabric-semanticmodel, the
generated schema.ts is already complete — do not edit it.
Finally, wire it up as client.connectors.<name> with ConnectorsRayfinClient imported from
@microsoft/rayfin-client, and deploy with `npx rayfin up`.