Adding a connector

Add a connector when a Rayfin app needs to reach existing Fabric data. Start with connector search if you do not already have the workspace ID, item ID, and connector type. See Connectors for the connector-type catalog.

Find a source

connector search lists Fabric items the signed-in identity can add and prints the exact connector add command for each result.

npx rayfin connector search [query] [--workspace-id <ws-id> --type <type>] [--limit <n>] [--json]

Choose one scope:

Use --limit <n> to cap plain or JSON output. Interactive output ignores the limit because the picker paginates the full result set.

Use --json when an agent or script will choose the result. The JSON envelope includes status, query, scope, count, and sources. Each source includes workspaceId, itemId, connectorType, suggestedName, and a ready-to-run addCommand.

{
  "status": "ok",
  "query": "sales",
  "scope": { "workspaceId": "<ws-id>" },
  "count": 1,
  "limit": 5,
  "sources": [
    {
      "workspaceId": "<ws-id>",
      "workspaceName": "Finance",
      "itemId": "<item-id>",
      "itemType": "Warehouse",
      "displayName": "Inventory",
      "connectorType": "fabric-warehouse",
      "suggestedName": "inventory",
      "addCommand": "rayfin connector add --type fabric-warehouse --workspace-id <ws-id> --item-id <item-id> --name inventory"
    }
  ]
}

Add the connector

Run connector add with literal Fabric IDs. The flag is --type <type>, not --connector.

npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id>

Connector names must match /^[a-zA-Z0-9\-_]+$/ and can be at most 256 characters.

Know what the command writes

connector add verifies the Fabric item, writes a connectors: entry in rayfin/rayfin.yml, and scaffolds rayfin/connectors/<name>/schema.ts.

For Category A connectors, it also runs schema discovery and writes rayfin/connectors/<name>/metadata.json. For kusto, it resolves the KQL Database's cluster query endpoint and database name from (workspaceId, itemId), then bakes queryServiceUri and databaseName into the generated schema.ts.

The rayfin.yml entry uses an array. Operations are objects, not bare strings:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: <ws-id>
      itemId: <item-id>
    auth:
      type: delegated
    operations:
      - name: read
      - name: update
  - name: telemetry
    type: kusto
    version: '1'
    config:
      workspaceId: <ws-id>
      itemId: <kql-database-item-id>
    auth:
      type: delegated
    operations:
      - name: executeQuery
      - name: executeCommand

Scope operations

Use --operations to narrow a connector below the catalog default:

npx rayfin connector add --type fabric-warehouse --workspace-id <ws-id> --item-id <item-id> --operations read,update

Rules:

• You can narrow below the catalog default, but you cannot widen above it.
• There is no all meta-operation. List every action explicitly, or omit --operations to accept the catalog default.
• The host validator rejects unknown or duplicate operation names at rayfin up time.

For the current connector types, the default operations are listed in Connectors.

Install the pinned packages

connector add scaffolds files but installs nothing. On success, it prints an exact version-pinned install command:

📦 Install the packages this connector needs:
   npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha

Run the command verbatim. Do not drop the version.

Connector packages ship in lockstep with the CLI, but their npm latest and preview tags lag. An unversioned install can pull an older connector that hard-pins its own @microsoft/rayfin-data, leaving two Rayfin version lines in one app.

rayfin connector types --json carries the same packages array, so an agent can rebuild the exact install list from the live catalog when needed.

List and remove connectors

connector list reads the local rayfin.yml file and does not make network calls.

npx rayfin connector list
npx rayfin connector list -v
npx rayfin connector list --json

Use connector remove with -y or --yes to remove both the rayfin.yml entry and the connector directory:

npx rayfin connector remove <name> --yes

Re-add a connector after removing it when you need to refresh metadata.json from the source.

Next step

After the connector entry and packages are in place, wire it into your app with Wiring connectors into your app. For the complete CLI flag reference, see rayfin connector.