connectors
Connect a Universal App to existing Fabric data sources: a Warehouse, SQL database, Lakehouse SQL analytics endpoint, or Power BI semantic model. Use whenever the user says "connect to", names an existing Fabric item, asks to query data that already exists, or needs to discover available sources. This skill owns the Universal App pack, source routing, and the handoff to the installed Rayfin connector catalog and package docs. It does not cover app-owned CRUD data (use `data-modeling`) or arbitrary external APIs (use `functions-capability`).
- License 许可
- MIT
- 所属仓库
- microsoft/rayfin
- 最近更新
- 2026-11-12
- Stars
- ★ 662
- Forks
- 77
01 前言 Front Matter
- name
- connectors
- description
- Connect a Universal App to existing Fabric data sources: a Warehouse, SQL database, Lakehouse SQL analytics endpoint, or Power BI semantic model. Use whenever the user says "connect to", names an existing Fabric item, asks to query data that already exists, or needs to discover available sources. This skill owns the Universal App pack, source routing, and the handoff to the installed Rayfin connector catalog and package docs. It does not cover app-owned CRUD data (use `data-modeling`) or arbitrary external APIs (use `functions-capability`).
02 资源文件 4
- 脚本kit/connectors.ts738 B
- 脚本kit/rayfin-client.ts2.2 KB
- 脚本kit/rayfin-client.with-functions.ts2.3 KB
- 参考文档pack.json2.8 KB
03 SKILL.md 正文
Connect to an existing Fabric data source
First install the app-side connector support:
npm run pack:add -- connectors
The rayfin connector command group is always available and requires no pack
or service flag.
This pack adds the frontend connector SDK and seeds
packages/frontend/src/lib/connectors.ts plus the composable Rayfin client.
It does not add services.connectors or declare a data source.
rayfin connector add owns the top-level connectors: configuration and the
per-source files under rayfin/connectors/.
Re-applying the pack is safe.
Read the live connector contracts
Do not copy connector capabilities, operations, package versions, or client APIs from this skill. Read the installed, version-matched contracts before authoring:
- Run
npx rayfin connector types --jsonfor the live type catalog. - Read
node_modules/@microsoft/rayfin-guide/assets/docs/cli/connectors/index.mdand the page for the command you are about to run. - After
connector add, read the installed connector package'spackage.json, follow itsrayfinDocs.dir, and use its entity-generation and typed-client pages.
The guide routes Category A details to
@microsoft/rayfin-connector-fabric-graphql.
Its installed docs own metadata.json, entity generation, aggregate
schema.ts, authorization, typed queries, and mutation behavior.
Route by source type
| User's source | Connector type or route |
|---|---|
| Fabric Warehouse | fabric-warehouse |
| Fabric SQL database | fabric-sqldatabase |
| Lakehouse SQL analytics endpoint | fabric-sqlanalytics |
| Power BI semantic model | npm run pack:add -- connectors, then npm run pack:add -- analytics |
| Kusto / KQL database | Check the live catalog; if it is absent, say it is unavailable and stop |
| External API, custom model endpoint, or Fabric data agent | npm run pack:add -- functions, then follow functions-capability |
The Lakehouse route is its SQL analytics endpoint, not direct access to files. Do not substitute a nearby source type or sample data when the requested type is unavailable.
Discover before connecting
Set <source-type> to the exact value from the table and confirm it still
appears in connector types --json.
If the user named a source but did not provide explicit IDs, search for it:
npx rayfin connector search "<name>" --type <source-type> --all-workspaces --json
Before deployment there is no workspace scope to infer.
Use --all-workspaces for a tenant-wide scan, or replace it with
--workspace-id <id> when the workspace is known.
Both explicit scopes require --type.
Prefer --json so you can compare displayName, workspaceName,
workspaceId, itemId, and connectorType without parsing a table.
Each result also carries a ready-to-run addCommand; prefer that command over
reconstructing connector add flags by hand.
- One unambiguous match: use it.
- Several plausible matches: show the workspace names and ask which one.
- No match: say what you searched for and ask for a corrected name or explicit IDs.
Never guess a source.
Add the connector
npx rayfin connector add --type <source-type> \
--workspace-id <workspaceId> --item-id <itemId> --name <alias>
Use a short lower-camel-case alias such as salesWarehouse.
add records the connection in rayfin/rayfin.yml, creates
a placeholder rayfin/connectors/<alias>/schema.ts plus metadata.json when
schema discovery succeeds, and prints version-pinned package specifications.
Install those exact versions into the frontend workspace from the app root:
npm install -w @rayfin-app/frontend <printed-packages-and-versions>
Do not install them at the workspace root or create a nested lockfile.
Generate and wire Category A entities
connector add discovers metadata but does not emit the entity files.
Use rayfin/connectors/<alias>/metadata.json only through the installed
package's generation contract.
Follow the installed
@microsoft/rayfin-connector-fabric-graphql docs to generate only the entities
the app needs and replace the placeholder aggregate schema.ts.
Do not recreate those package-owned contracts from memory.
The CLI-generated packages/frontend/src/lib/connectors.ts carries this
ownership marker:
// @generated by `rayfin connector add` — do not edit below this line.
After the aggregate schema exports <Name>Schema and connectorConfig, take
ownership before editing by deleting that generated-marker line.
Then add the same connector name in all matching locations:
- import
<Name>SchemaandconnectorConfigfrom the aggregateschema.ts; - add
<alias>: <Name>SchematoAppConnectorsSchema; - add
<alias>: connectorConfigtoconnectorConfigs.
Category A needs no connectorRuntimes entry.
Do not rerun rayfin connector add --yes after authoring entities: --yes
opts in to replacing the hand-authored aggregate schema.ts with a placeholder.
If the CLI later reports manual wiring, merge its printed maps into the
Builder-owned file instead of restoring the generated marker.
Sample the source before building UI
List the real entities, then sample one through the read-only inspection path:
npx rayfin connector inspect --name <alias>
npx rayfin connector inspect --name <alias> --entity <entity> --rows 1
Use the typed client surface documented by the installed connector package for
application reads and writes.
That is the generated client.connectors.<alias>.<Entity> surface, not a raw
query operation invented in application code.
Category A SQL connectors do not use connector invoke as their authoring
workflow.
This CLI sample proves source access and shape only.
It does not replace deployed browser validation from
app-validation.
Treat connector errors as configuration, permissions, or query errors to fix,
not warnings to bypass.
After wiring application code, run the normal project gates from the workspace root:
npm run typecheck
npm run build
npm run lint
npm test
Before browser validation, follow the connector deployment-outcome invariant in
app-deployment.
Do not treat overall rayfin up success as proof that a required connector was
generated and applied.
04 同仓库更多 Skills
rayfin-getting-started
Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin
visuals
Use when user wants to incorporate charts, graphs, data grid, or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals, utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection/click events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.
schema-discovery
Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.
query-design
Separates DAX data-fetching from TypeScript presentation. Guides when to use DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS, BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset/overlay queries, and format strings.
functions-capability
Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.
fabric-sdk
How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.<name>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.