[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699WSVYEPS4F63TH3DC97A8":3,"skill-same:01M699WSVYEPS4F63TH3DC97A8":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":29,"linkOnly":30,"markdownContent":31,"markdownBody":32,"frontMatter":33,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":6,"ownerHtmlUrl":41,"ownerBlogUrl":42,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M699WSVYEPS4F63TH3DC97A8","rayfin-connectors",null,"Connect existing Fabric data sources (Lakehouse, Warehouse, SQL Database, semantic model, KQL Database\u002FEventhouse) to Rayfin apps; not app-owned data models. Use for connector discovery, setup, entity generation, authorization, SDK wiring, inspecting rows, invoking queries, and troubleshooting. Triggers: rayfin connector (add\u002Fsearch\u002Ftypes\u002Finspect\u002Finvoke), rayfin up connector apply, connectors:, fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, fabric-semanticmodel, kusto\u002FKQL, DAX EVALUATE, rayfin\u002Fconnectors\u002F, metadata.json, AppConnectorsSchema, ConnectorsSchema, ConnectorsRayfinClient, client.connectors, connectorConfig, GraphQLBackedConnector, schema.ts, @role, claims.sub, executeQuery, executeCommand, resultSetRowCountLimit, queryServiceUri, databaseName, KustoConnectorConfig. Includes connector entity imports\u002Fmaps causing a blank page after deploy, Uncaught SyntaxError, or Invalid or unexpected token.","microsoft\u002Frayfin","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699VK9NEV8GH0Y5JKT1G8XG",659,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fpackages\u002Ftools\u002Fcli\u002Fassets\u002Fagent-files\u002Fskills\u002Frayfin-connectors\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",[24,25,9,26,27,28],"rayfin connectors","sdk","dax","deploy","setup","2026-11-10 10:12:30",false,"---\nname: rayfin-connectors\ndescription: \"Connect existing Fabric data sources (Lakehouse, Warehouse, SQL Database, semantic model, KQL Database\u002FEventhouse) to Rayfin apps; not app-owned data models. Use for connector discovery, setup, entity generation, authorization, SDK wiring, inspecting rows, invoking queries, and troubleshooting. Triggers: rayfin connector (add\u002Fsearch\u002Ftypes\u002Finspect\u002Finvoke), rayfin up connector apply, connectors:, fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, fabric-semanticmodel, kusto\u002FKQL, DAX EVALUATE, rayfin\u002Fconnectors\u002F, metadata.json, AppConnectorsSchema, ConnectorsSchema, ConnectorsRayfinClient, client.connectors, connectorConfig, GraphQLBackedConnector, schema.ts, @role, claims.sub, executeQuery, executeCommand, resultSetRowCountLimit, queryServiceUri, databaseName, KustoConnectorConfig. Includes connector entity imports\u002Fmaps causing a blank page after deploy, Uncaught SyntaxError, or Invalid or unexpected token.\"\nmetadata:\n  author: microsoft\n  version: \"0.7.4\"\n---\n\n# Rayfin Connectors\n\nBring an existing Fabric data source into a Rayfin app.\n\nTwo contracts govern connectors, and this file is neither of them:\n\n- **The versioned behavioral contract** — the category guides shipped in `@microsoft\u002Frayfin-guide`.\n  Workflow, generation rules, authorization semantics, per-dialect behavior, error handling.\n- **The live catalog contract** — `rayfin connector types --json`.\n  Current types, categories, allowed operations, auth modes, required config, adapter versions, and the packages plus versions to install.\n\n**Read the matching category guide for workflow and semantics.\nRead `rayfin connector types --json` for current types, capabilities, package names, and versions.**\nAnswer neither from memory, and never copy either into code or prose — a copied catalog goes stale within days.\n\nThis file is the router: whether a connector applies, which category you are in, and where to read next.\n\n## When to Use a Connector\n\nUse a connector when the user wants the app to read or write **existing** data already living in a Fabric workspace.\n\nDo **not** use a connector when the user is creating a brand-new data model owned by the Rayfin app — those entities go under `rayfin\u002Fdata\u002F` and are managed via `rayfin up db apply`, not `rayfin connector add`.\n\n**Routing note:** `@role` and `@entity` also appear in the base `rayfin` skill for owned `rayfin\u002Fdata\u002F` models.\nThis skill applies only when those decorators are used inside `rayfin\u002Fconnectors\u002F` files.\n\nConnectors are cloud-only on day one.\n`rayfin dev` parses the `connectors:` block but does not wire it; verifying connector behavior requires `rayfin up`.\n\n`fabric-sqlanalytics` means the Lakehouse SQL analytics endpoint, not full Lakehouse access.\nIt can read SQL-visible tables and views only; it cannot directly open PDFs, images, or other files in the Lakehouse `Files` area.\nDo not describe it as generic Lakehouse support.\n\n## Connector Commands\n\n`rayfin connector ...` is always registered; no opt-in is required.\n\n## Two Categories — Decide First\n\n|                                                          | Category A — GraphQL entities                                   | Category B — function bridge                   |\n| -------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------- |\n| Types                                                    | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase` | `fabric-semanticmodel`; `kusto` is experimental |\n| App surface                                              | Generated entity files with typed CRUD                          | Named operations carrying a raw query          |\n| Entity files, `@role` policies, `metadata.json` entities | Yes                                                             | No                                             |\n| Read next                                                | `cli\u002Fconnectors\u002Fcategory-a-entities.md`            | `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md` |\n\nCategory membership is stable enough to route on.\nEverything else about a type — allowed operations, auth modes, required config, adapter version, packages to install — comes from `rayfin connector types --json`, including types added after this file was written.\n\n**New `kusto` authoring is held in this release.** It is absent from `connector types` and `connector search`, and rejected by `connector add`. If the user asks to add a KQL database, say so and stop rather than substituting another source. A project that already declares a Kusto connector stays valid — validate, deploy and invoke all work — so the guidance below applies to it today.\n\nDo not read both category docs.\nCategory A's entity-generation contract does not apply to `fabric-semanticmodel` or experimental `kusto`, and Category B's function-bridge contract does not apply to the SQL types.\n\n## Reading the Connector Guides\n\nThese guides are published with the Rayfin guide package. Resolve them from disk when you need the version installed in the app:\n\n`node_modules\u002F@microsoft\u002Frayfin-guide\u002Fassets\u002Fdocs\u002F\u003Cpath>`.\n\nThis skill can load before `@microsoft\u002Frayfin-guide` is installed, or against a different package version than the one it was written for.\nIf the guide path is unavailable, say it is unavailable and fall back to `rayfin connector types --json` and `rayfin connector \u003Ccommand> --help`.\nDo not reconstruct the contract from memory.\n\n### Eventhouse (`kusto`) has a dedicated guide\n\nThe experimental Eventhouse (`kusto`) connector reads large, append-only time-series data from a Fabric Eventhouse KQL Database; for small relational lookups or CRUD, use a Category A SQL type instead.\nWhen to choose it, the streaming model, shaping KQL, safe query construction, and result handling all live in `cli\u002Fconnectors\u002Feventhouse.md`, with the shared function-bridge contract in `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md`.\nRead those; do not reconstruct them from memory.\n\n## Workflow\n\n1. **Add.** `rayfin connector add --type \u003Ctype> --workspace-id \u003Cws> --item-id \u003Citem> [--name \u003Cname>] [--operations \u003Cops>]`\n   Verifies the Fabric item, writes the `rayfin.yml` entry, and scaffolds `rayfin\u002Fconnectors\u002F\u003Cname>\u002F` — plus `metadata.json` for Category A.\n   It **installs nothing**, but it prints the exact version-pinned `npm install` command — run that verbatim.\n   Never install these packages unversioned: their npm tags lag the published release, so `npm install \u003Cpkg>` pulls an older connector and a second, mismatched copy of `@microsoft\u002Frayfin-data`.\n   See `cli\u002Fconnectors\u002Fadd.md`.\n2. **Scope.** Without `--operations`, `add` writes every operation the catalog allows.\n   Confirm what the user actually needs and narrow to it: read-only → `read`; append-only → `read`, `create`; edit-but-not-add → `read`, `update`; full CRUD → all four.\n   Ask when the intent is ambiguous; for Category A also ask whether rows are scoped per user.\n   You can narrow below the catalog default, never widen above it.\n3. **Follow the category guide.** Category A generates entity files, scopes `@role(...)`, and writes the aggregate `schema.ts`; Category B installs a marker package and calls a named operation.\n4. **Deploy.** `rayfin up`, or `rayfin up connector apply` to re-apply DAB config alone.\n5. **Preflight — prove data comes back before you build anything on it.**\n   Run exactly one query and stop if it fails. This is a gate, not a suggestion: a connector that cannot return data fails the same way after a dashboard is built on top of it, only an hour later and with the cause buried.\n\n   | Category | Command |\n   | --- | --- |\n   | A | `rayfin connector inspect --name \u003Cname> --entity \u003Centity> --rows 1` |\n   | B — `fabric-semanticmodel` | `rayfin connector invoke \u003Cname> executeQuery --file .\u002Fprobe.query.json` |\n   | B — `kusto` | `rayfin connector invoke \u003Cname> executeQuery --file .\u002Fprobe.query.json` |\n\n   `fabric-semanticmodel` is the one you can run **before** step 4: from the CLI it calls Power BI directly under your identity, so it needs no deployment. Use that to fail fast. Everything else reads through the deployed app and needs step 4 first.\n\n   **A CLI probe does not prove the deployed app works.** For `fabric-semanticmodel` the CLI takes the direct Power BI route under *your* identity by default; the deployed app instead goes through the platform's user-data function, which re-authorises as the signed-in user. Those are different transports with different permissions, and the second can fail — typically `Unauthorized` — after the first has passed. So the probe is necessary, not sufficient: **the connector is only proven once the deployed app itself executes the query and renders real rows in the browser.** Re-running `rayfin connector invoke` after `rayfin up` does not change that: it still takes the CLI-direct path unless you pass `--transport deployed`, and that route authenticates the *app*, so it needs an app-session token in `RAYFIN_TOKEN` — a normal `rayfin login` cannot mint one.\n\n   `--file` takes a **JSON payload**, not a raw `.dax` or `.kql` file — it is `JSON.parse`d, so a bare query fails before the connector is ever reached. Write the query into the operation's input envelope:\n\n   ```json\n   { \"query\": \"EVALUATE TOPN(1, Sales)\" }\n   ```\n\n   Prefer that over `--input '\u003Cjson>'` for anything you or a model composed: DAX and KQL are full of quotes and brackets a shell reads as syntax, and one apostrophe in a string literal is enough to corrupt the command. The path is resolved against the project root and must stay inside it.\n\n   A failure here is a connector, permission, or platform-enablement problem. Report it and stop — do not scaffold UI, and do not work around it in app code. `FEATURE_NOT_ENABLED` in particular is a workspace switch nobody can fix from inside the app.\n\n## Commands\n\n| Command                                      | What it does                                                        | Doc path                    |\n| -------------------------------------------- | ------------------------------------------------------------------- | --------------------------- |\n| `rayfin connector types [--json]`            | Emit the live catalog.                                              | —                           |\n| `rayfin connector search [query]`            | Discover addable Fabric sources before you know workspace\u002Fitem IDs. | `cli\u002Fconnectors\u002Fsearch.md`  |\n| `rayfin connector add`                       | Declare a connector and scaffold it.                                | `cli\u002Fconnectors\u002Fadd.md`     |\n| `rayfin connector list` \u002F `remove`           | List connectors; remove the entry **and** its directory.            | `cli\u002Fconnectors\u002Findex.md`   |\n| `rayfin connector inspect`                   | Run one read-only sample query against a source.                    | `cli\u002Fconnectors\u002Finspect.md` |\n| `rayfin connector invoke \u003Cname> \u003Coperation>` | Run one named operation — the loop for Category B.                  | `cli\u002Fconnectors\u002Finvoke.md`  |\n\nFlags, output shapes, and error catalogs live in those docs and in `--help`.\nRead one before answering a detailed question; do not guess.\n\nTwo behaviors worth knowing before you pick a command:\n\n- `connector inspect` does not support experimental `kusto` — use `rayfin connector invoke \u003Cname> executeQuery` instead.\n- `connector invoke` on `fabric-semanticmodel` runs under the developer's identity and works without `rayfin up`; every other type, including experimental `kusto`, POSTs to the deployed item and requires a prior `rayfin up`.\n\n## Rules and Anti-Patterns\n\n- The `rayfin.yml` `connectors:` block is an **array** of entries with `name` and `type` fields. Never write the legacy map shape.\n- **Never name an entity after a reserved GraphQL type.**\n  Entity names become GraphQL type names, so built-in scalars, the operation root types, and any name starting with `__` are rejected at `rayfin up`.\n  Matching is case-sensitive and exact — `TaskDate` is fine.\n  The authoritative list is the \"Reserved entity names\" section of `@microsoft\u002Frayfin-core\u002Fassets\u002Fdocs\u002Fdecorators.md` — read it there, never from memory.\n  Rename the entity and keep `Source({ table: '...' })` pointed at the original table.\n- `rayfin connector add` discovers schema only when `workspaceId` and `itemId` are literal strings — `${VAR}` placeholders are rejected.\n- Default to the **narrowest** operations the user described — do not assume full CRUD for a read-only ask.\n- Never hand-edit a file that carries a `\u002F\u002F @generated — do not edit.` banner — re-add the connector to regenerate it. This covers the Category B `schema.ts`. The Category A `schema.ts` ships **without** that banner: it is a placeholder you are expected to overwrite with the aggregate schema.\n- In a Category A `schema.ts`, import and re-export the generated entity **classes** as values, and list those classes in `connectorConfig.entities` (e.g. `entities: { Order, Customer }`). The client reads each class for the default column selection and relationship cardinality.\n- The relationship options `sourceFields` \u002F `targetFields` (on `@one()` \u002F `@many()`) declare a custom foreign key and are **connector entities only** — they are rejected on the data path.\n- Connectors do not run under `rayfin dev` — test via `rayfin up` and `rayfin up connector apply` against a deployed environment.\n- **Never build UI on an unproven connector.** Run the Workflow step 5 preflight first. Rendering a component against a connector that has never returned a row means the eventual failure looks like a UI bug and is debugged in the wrong place.\n- Pass model- or user-authored DAX and KQL to `invoke` with `--file`, and remember it takes a **JSON payload** (`{\"query\":\"…\"}`), not a raw `.dax`\u002F`.kql` file — a bare query is `JSON.parse`d and fails before the connector is reached. An inline `--input` goes through a shell that treats quotes and brackets as syntax, so a query containing an apostrophe is silently mangled rather than rejected.\n- Do not load both category reference docs, and do not restate a guide's contents instead of reading it.\n\n## Troubleshooting\n\n| Symptom | Fix |\n| --- | --- |\n| `rayfin up` fails with \"does not support operation\" | The YAML `operations:` list exceeds the type's allowlist. Check `rayfin connector types --json` and narrow it. |\n| `rayfin up` reports \"Reserved GraphQL type names detected\" | An entity is named after a built-in scalar or root type (for example `Date`). Rename the class and keep `Source({ table: '...' })` on the original table. |\n| `connector add` errors with \"literal IDs required\" | `--workspace-id` or `--item-id` was a `${VAR}` placeholder. Pass literal values. |\n| The scaffolded `rayfin\u002Fconnectors\u002F\u003Cname>\u002F` does not compile | Its imports are not installed. Run the pinned `npm install` command `connector add` printed. |\n| Type errors between connector and client code | An unversioned install pulled a stale connector, so two `@microsoft\u002Frayfin-data` copies exist. Reinstall pinned. |\n| A query chain throws `SELECTION_REQUIRED` | `.where()` \u002F `.orderBy()` \u002F `.first()` never inherit the default selection. Add `.select([...])` to the chain. |\n| `findMany` \u002F `findFirst` \u002F `findByKey` throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing. Add the entity class to it, or pass an explicit selection. |\n| Local `rayfin dev` ignores the connector | Expected — connectors are cloud-only. Exercise via `rayfin up`. |\n| `FEATURE_NOT_ENABLED` \u002F 404 from `\u002Fconnector-invoke\u002F\u003Cname>` | Not app config — ConnectorFunction invocation is disabled for that Fabric workspace. The message is server-side, so it is not in any local source. Stop and escalate for workspace enablement instead of editing the app. |\n\nEverything else belongs to a guide: entity generation and authorization in `cli\u002Fconnectors\u002Fcategory-a-entities.md`, connector config fields in `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md`, and per-command error catalogs in the command docs above.\n","# Rayfin Connectors\n\nBring an existing Fabric data source into a Rayfin app.\n\nTwo contracts govern connectors, and this file is neither of them:\n\n- **The versioned behavioral contract** — the category guides shipped in `@microsoft\u002Frayfin-guide`.\n  Workflow, generation rules, authorization semantics, per-dialect behavior, error handling.\n- **The live catalog contract** — `rayfin connector types --json`.\n  Current types, categories, allowed operations, auth modes, required config, adapter versions, and the packages plus versions to install.\n\n**Read the matching category guide for workflow and semantics.\nRead `rayfin connector types --json` for current types, capabilities, package names, and versions.**\nAnswer neither from memory, and never copy either into code or prose — a copied catalog goes stale within days.\n\nThis file is the router: whether a connector applies, which category you are in, and where to read next.\n\n## When to Use a Connector\n\nUse a connector when the user wants the app to read or write **existing** data already living in a Fabric workspace.\n\nDo **not** use a connector when the user is creating a brand-new data model owned by the Rayfin app — those entities go under `rayfin\u002Fdata\u002F` and are managed via `rayfin up db apply`, not `rayfin connector add`.\n\n**Routing note:** `@role` and `@entity` also appear in the base `rayfin` skill for owned `rayfin\u002Fdata\u002F` models.\nThis skill applies only when those decorators are used inside `rayfin\u002Fconnectors\u002F` files.\n\nConnectors are cloud-only on day one.\n`rayfin dev` parses the `connectors:` block but does not wire it; verifying connector behavior requires `rayfin up`.\n\n`fabric-sqlanalytics` means the Lakehouse SQL analytics endpoint, not full Lakehouse access.\nIt can read SQL-visible tables and views only; it cannot directly open PDFs, images, or other files in the Lakehouse `Files` area.\nDo not describe it as generic Lakehouse support.\n\n## Connector Commands\n\n`rayfin connector ...` is always registered; no opt-in is required.\n\n## Two Categories — Decide First\n\n|                                                          | Category A — GraphQL entities                                   | Category B — function bridge                   |\n| -------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------- |\n| Types                                                    | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase` | `fabric-semanticmodel`; `kusto` is experimental |\n| App surface                                              | Generated entity files with typed CRUD                          | Named operations carrying a raw query          |\n| Entity files, `@role` policies, `metadata.json` entities | Yes                                                             | No                                             |\n| Read next                                                | `cli\u002Fconnectors\u002Fcategory-a-entities.md`            | `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md` |\n\nCategory membership is stable enough to route on.\nEverything else about a type — allowed operations, auth modes, required config, adapter version, packages to install — comes from `rayfin connector types --json`, including types added after this file was written.\n\n**New `kusto` authoring is held in this release.** It is absent from `connector types` and `connector search`, and rejected by `connector add`. If the user asks to add a KQL database, say so and stop rather than substituting another source. A project that already declares a Kusto connector stays valid — validate, deploy and invoke all work — so the guidance below applies to it today.\n\nDo not read both category docs.\nCategory A's entity-generation contract does not apply to `fabric-semanticmodel` or experimental `kusto`, and Category B's function-bridge contract does not apply to the SQL types.\n\n## Reading the Connector Guides\n\nThese guides are published with the Rayfin guide package. Resolve them from disk when you need the version installed in the app:\n\n`node_modules\u002F@microsoft\u002Frayfin-guide\u002Fassets\u002Fdocs\u002F\u003Cpath>`.\n\nThis skill can load before `@microsoft\u002Frayfin-guide` is installed, or against a different package version than the one it was written for.\nIf the guide path is unavailable, say it is unavailable and fall back to `rayfin connector types --json` and `rayfin connector \u003Ccommand> --help`.\nDo not reconstruct the contract from memory.\n\n### Eventhouse (`kusto`) has a dedicated guide\n\nThe experimental Eventhouse (`kusto`) connector reads large, append-only time-series data from a Fabric Eventhouse KQL Database; for small relational lookups or CRUD, use a Category A SQL type instead.\nWhen to choose it, the streaming model, shaping KQL, safe query construction, and result handling all live in `cli\u002Fconnectors\u002Feventhouse.md`, with the shared function-bridge contract in `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md`.\nRead those; do not reconstruct them from memory.\n\n## Workflow\n\n1. **Add.** `rayfin connector add --type \u003Ctype> --workspace-id \u003Cws> --item-id \u003Citem> [--name \u003Cname>] [--operations \u003Cops>]`\n   Verifies the Fabric item, writes the `rayfin.yml` entry, and scaffolds `rayfin\u002Fconnectors\u002F\u003Cname>\u002F` — plus `metadata.json` for Category A.\n   It **installs nothing**, but it prints the exact version-pinned `npm install` command — run that verbatim.\n   Never install these packages unversioned: their npm tags lag the published release, so `npm install \u003Cpkg>` pulls an older connector and a second, mismatched copy of `@microsoft\u002Frayfin-data`.\n   See `cli\u002Fconnectors\u002Fadd.md`.\n2. **Scope.** Without `--operations`, `add` writes every operation the catalog allows.\n   Confirm what the user actually needs and narrow to it: read-only → `read`; append-only → `read`, `create`; edit-but-not-add → `read`, `update`; full CRUD → all four.\n   Ask when the intent is ambiguous; for Category A also ask whether rows are scoped per user.\n   You can narrow below the catalog default, never widen above it.\n3. **Follow the category guide.** Category A generates entity files, scopes `@role(...)`, and writes the aggregate `schema.ts`; Category B installs a marker package and calls a named operation.\n4. **Deploy.** `rayfin up`, or `rayfin up connector apply` to re-apply DAB config alone.\n5. **Preflight — prove data comes back before you build anything on it.**\n   Run exactly one query and stop if it fails. This is a gate, not a suggestion: a connector that cannot return data fails the same way after a dashboard is built on top of it, only an hour later and with the cause buried.\n\n   | Category | Command |\n   | --- | --- |\n   | A | `rayfin connector inspect --name \u003Cname> --entity \u003Centity> --rows 1` |\n   | B — `fabric-semanticmodel` | `rayfin connector invoke \u003Cname> executeQuery --file .\u002Fprobe.query.json` |\n   | B — `kusto` | `rayfin connector invoke \u003Cname> executeQuery --file .\u002Fprobe.query.json` |\n\n   `fabric-semanticmodel` is the one you can run **before** step 4: from the CLI it calls Power BI directly under your identity, so it needs no deployment. Use that to fail fast. Everything else reads through the deployed app and needs step 4 first.\n\n   **A CLI probe does not prove the deployed app works.** For `fabric-semanticmodel` the CLI takes the direct Power BI route under *your* identity by default; the deployed app instead goes through the platform's user-data function, which re-authorises as the signed-in user. Those are different transports with different permissions, and the second can fail — typically `Unauthorized` — after the first has passed. So the probe is necessary, not sufficient: **the connector is only proven once the deployed app itself executes the query and renders real rows in the browser.** Re-running `rayfin connector invoke` after `rayfin up` does not change that: it still takes the CLI-direct path unless you pass `--transport deployed`, and that route authenticates the *app*, so it needs an app-session token in `RAYFIN_TOKEN` — a normal `rayfin login` cannot mint one.\n\n   `--file` takes a **JSON payload**, not a raw `.dax` or `.kql` file — it is `JSON.parse`d, so a bare query fails before the connector is ever reached. Write the query into the operation's input envelope:\n\n   ```json\n   { \"query\": \"EVALUATE TOPN(1, Sales)\" }\n   ```\n\n   Prefer that over `--input '\u003Cjson>'` for anything you or a model composed: DAX and KQL are full of quotes and brackets a shell reads as syntax, and one apostrophe in a string literal is enough to corrupt the command. The path is resolved against the project root and must stay inside it.\n\n   A failure here is a connector, permission, or platform-enablement problem. Report it and stop — do not scaffold UI, and do not work around it in app code. `FEATURE_NOT_ENABLED` in particular is a workspace switch nobody can fix from inside the app.\n\n## Commands\n\n| Command                                      | What it does                                                        | Doc path                    |\n| -------------------------------------------- | ------------------------------------------------------------------- | --------------------------- |\n| `rayfin connector types [--json]`            | Emit the live catalog.                                              | —                           |\n| `rayfin connector search [query]`            | Discover addable Fabric sources before you know workspace\u002Fitem IDs. | `cli\u002Fconnectors\u002Fsearch.md`  |\n| `rayfin connector add`                       | Declare a connector and scaffold it.                                | `cli\u002Fconnectors\u002Fadd.md`     |\n| `rayfin connector list` \u002F `remove`           | List connectors; remove the entry **and** its directory.            | `cli\u002Fconnectors\u002Findex.md`   |\n| `rayfin connector inspect`                   | Run one read-only sample query against a source.                    | `cli\u002Fconnectors\u002Finspect.md` |\n| `rayfin connector invoke \u003Cname> \u003Coperation>` | Run one named operation — the loop for Category B.                  | `cli\u002Fconnectors\u002Finvoke.md`  |\n\nFlags, output shapes, and error catalogs live in those docs and in `--help`.\nRead one before answering a detailed question; do not guess.\n\nTwo behaviors worth knowing before you pick a command:\n\n- `connector inspect` does not support experimental `kusto` — use `rayfin connector invoke \u003Cname> executeQuery` instead.\n- `connector invoke` on `fabric-semanticmodel` runs under the developer's identity and works without `rayfin up`; every other type, including experimental `kusto`, POSTs to the deployed item and requires a prior `rayfin up`.\n\n## Rules and Anti-Patterns\n\n- The `rayfin.yml` `connectors:` block is an **array** of entries with `name` and `type` fields. Never write the legacy map shape.\n- **Never name an entity after a reserved GraphQL type.**\n  Entity names become GraphQL type names, so built-in scalars, the operation root types, and any name starting with `__` are rejected at `rayfin up`.\n  Matching is case-sensitive and exact — `TaskDate` is fine.\n  The authoritative list is the \"Reserved entity names\" section of `@microsoft\u002Frayfin-core\u002Fassets\u002Fdocs\u002Fdecorators.md` — read it there, never from memory.\n  Rename the entity and keep `Source({ table: '...' })` pointed at the original table.\n- `rayfin connector add` discovers schema only when `workspaceId` and `itemId` are literal strings — `${VAR}` placeholders are rejected.\n- Default to the **narrowest** operations the user described — do not assume full CRUD for a read-only ask.\n- Never hand-edit a file that carries a `\u002F\u002F @generated — do not edit.` banner — re-add the connector to regenerate it. This covers the Category B `schema.ts`. The Category A `schema.ts` ships **without** that banner: it is a placeholder you are expected to overwrite with the aggregate schema.\n- In a Category A `schema.ts`, import and re-export the generated entity **classes** as values, and list those classes in `connectorConfig.entities` (e.g. `entities: { Order, Customer }`). The client reads each class for the default column selection and relationship cardinality.\n- The relationship options `sourceFields` \u002F `targetFields` (on `@one()` \u002F `@many()`) declare a custom foreign key and are **connector entities only** — they are rejected on the data path.\n- Connectors do not run under `rayfin dev` — test via `rayfin up` and `rayfin up connector apply` against a deployed environment.\n- **Never build UI on an unproven connector.** Run the Workflow step 5 preflight first. Rendering a component against a connector that has never returned a row means the eventual failure looks like a UI bug and is debugged in the wrong place.\n- Pass model- or user-authored DAX and KQL to `invoke` with `--file`, and remember it takes a **JSON payload** (`{\"query\":\"…\"}`), not a raw `.dax`\u002F`.kql` file — a bare query is `JSON.parse`d and fails before the connector is reached. An inline `--input` goes through a shell that treats quotes and brackets as syntax, so a query containing an apostrophe is silently mangled rather than rejected.\n- Do not load both category reference docs, and do not restate a guide's contents instead of reading it.\n\n## Troubleshooting\n\n| Symptom | Fix |\n| --- | --- |\n| `rayfin up` fails with \"does not support operation\" | The YAML `operations:` list exceeds the type's allowlist. Check `rayfin connector types --json` and narrow it. |\n| `rayfin up` reports \"Reserved GraphQL type names detected\" | An entity is named after a built-in scalar or root type (for example `Date`). Rename the class and keep `Source({ table: '...' })` on the original table. |\n| `connector add` errors with \"literal IDs required\" | `--workspace-id` or `--item-id` was a `${VAR}` placeholder. Pass literal values. |\n| The scaffolded `rayfin\u002Fconnectors\u002F\u003Cname>\u002F` does not compile | Its imports are not installed. Run the pinned `npm install` command `connector add` printed. |\n| Type errors between connector and client code | An unversioned install pulled a stale connector, so two `@microsoft\u002Frayfin-data` copies exist. Reinstall pinned. |\n| A query chain throws `SELECTION_REQUIRED` | `.where()` \u002F `.orderBy()` \u002F `.first()` never inherit the default selection. Add `.select([...])` to the chain. |\n| `findMany` \u002F `findFirst` \u002F `findByKey` throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing. Add the entity class to it, or pass an explicit selection. |\n| Local `rayfin dev` ignores the connector | Expected — connectors are cloud-only. Exercise via `rayfin up`. |\n| `FEATURE_NOT_ENABLED` \u002F 404 from `\u002Fconnector-invoke\u002F\u003Cname>` | Not app config — ConnectorFunction invocation is disabled for that Fabric workspace. The message is server-side, so it is not in any local source. Stop and escalate for workspace enablement instead of editing the app. |\n\nEverything else belongs to a guide: entity generation and authorization in `cli\u002Fconnectors\u002Fcategory-a-entities.md`, connector config fields in `cli\u002Fconnectors\u002Fcategory-b-function-bridge.md`, and per-command error catalogs in the command docs above.\n",{"name":5,"metadata":34,"description":7},{"author":9,"version":35},"0.7.4","main","0979439a7a0806abd0ee48c2619b37f297ae1324","packages\u002Ftools\u002Fcli\u002Fassets\u002Fagent-files\u002Fskills\u002Frayfin-connectors",75,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-12 01:21:10",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add microsoft\u002Frayfin --skill rayfin-connectors",{"tool":51,"command":52},"bunx","bunx skills add microsoft\u002Frayfin --skill rayfin-connectors",{"tool":54,"command":55},"pnpm","pnpm dlx skills add microsoft\u002Frayfin --skill rayfin-connectors","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fpackages\u002Ftools\u002Fcli\u002Fassets\u002Fagent-files\u002Fskills\u002Frayfin-connectors\u002FSKILL.md",true,[],[60,73,91,99,118,126],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":29},"01M699YEY2QDVPKTZS3HR9AX84","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\u002Fdocs 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\u002Frayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fskills\u002Frayfin-getting-started\u002FSKILL.md",[],[67,68,69,70,9,71,72],"rayfin getting started","rayfin","scaffold","init","docs","cli",{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":87,"publishedAt":29},"01M699YCN4ZDW2AMDP4NVJ2QGC","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\u002Fclick 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.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fvisuals\u002FSKILL.md",[79,82],{"categoryNo":80,"categoryName":81,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":83,"categoryName":84,"taxonomyType":85,"taxonomyTypeDesc":86},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[75,88,89,90],"components","dashboard","visualize",{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":29},"01M699YBEP146MJZJNN8YEBZ2G","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.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fschema-discovery\u002FSKILL.md",[],[98,26],"schema discovery",{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":114,"publishedAt":29},"01M699Y9E80WYFKD1S4MT4B1CS","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\u002Foverlay queries, and format strings.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Fquery-design\u002FSKILL.md",[105,108,111],{"categoryNo":106,"categoryName":107,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000003","演示文稿",{"categoryNo":109,"categoryName":110,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":112,"categoryName":113,"taxonomyType":85,"taxonomyTypeDesc":86},"01JBSEEDCAT000000000000032","设计师",[115,116,26,117],"query design","design","typescript",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":29},"01M699Y7CKZ55QSYFE827RRVJE","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.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Ffunctions-capability\u002FSKILL.md",[],[125],"functions capability",{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":29},"01M699Y5R87YE620T78Z30KQSA","fabric-sdk","How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.\u003Cname>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Frayfin\u002Fblob\u002Fmain\u002Fsamples\u002Funiversal-app\u002Ftemplate\u002F.agents\u002Fskills\u002Ffabric-sdk\u002FSKILL.md",[],[25,133,26,24,68,134],"fabric sdk","connectors"]