AGENT SKILL

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

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:

  1. Run npx rayfin connector types --json for the live type catalog.
  2. Read node_modules/@microsoft/rayfin-guide/assets/docs/cli/connectors/index.md and the page for the command you are about to run.
  3. After connector add, read the installed connector package's package.json, follow its rayfinDocs.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>Schema and connectorConfig from the aggregate schema.ts;
  • add <alias>: <Name>Schema to AppConnectorsSchema;
  • add <alias>: connectorConfig to connectorConfigs.

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

microsoft
microsoft/rayfin

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

★ 662
microsoft
microsoft/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.

数据分析师分析与可视化
★ 662
microsoft
microsoft/rayfin

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.

★ 662
microsoft
microsoft/rayfin

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.

设计师演示文稿视觉设计
★ 662
microsoft
microsoft/rayfin

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.

★ 662
microsoft
microsoft/rayfin

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.

★ 662