Connector

Use rayfin connector to discover existing Microsoft Fabric sources, register them in rayfin.yml, inspect their read shape, and invoke configured operations. For the workflow and app-code model, start with Connectors; this page is the command reference.

npx rayfin connector <command>

Connector types

Category A connectors generate entity configuration for Data API Builder. Category B connectors expose function-style query operations and are delegated-only. See Connectors, Fabric SQL sources, Semantic models, and KQL databases.

Subcommands

The registered subcommands are search, add, list, remove, types, inspect, and invoke.

connector search

npx rayfin connector search [query] --workspace-id <id> --type <type>
npx rayfin connector search [query] --all-workspaces --type <type>
npx rayfin connector search [query]

Searches Fabric items that the signed-in identity can add as connectors. Use one of these scopes:

With --json, the command emits { status, query, scope, count, sources }. Each result in sources includes a suggested name and a ready-to-run addCommand.

connector add

npx rayfin connector add --type fabric-sqldatabase --workspace-id <id> --item-id <id> --name sales

Registers one source in rayfin/rayfin.yml and scaffolds rayfin/connectors/<name>/.

The command verifies the Fabric item, writes the connectors: entry, and writes rayfin/connectors/<name>/schema.ts. For Category A it also runs schema discovery and writes metadata.json. For kusto, it resolves queryServiceUri and databaseName and bakes them into schema.ts; those values are not written to rayfin.yml.

For versioned Category B types (fabric-semanticmodel and kusto), connector add writes the catalog defaultVersion automatically. Today that value is '1'.

connector add does not install packages. It prints a version-pinned npm install command; with --json, the same data appears under install.packages and install.command.

connector list

npx rayfin connector list

Lists connectors declared in rayfin.yml. It does not call Fabric or the deployed workload.

connector remove

npx rayfin connector remove sales --yes

Removes the named connector entry from rayfin.yml and deletes rayfin/connectors/<name>/.

JSON output for a removed connector is { status, action: 'connector.remove', name, removed, directoryDeleted }.

connector types

npx rayfin connector types --verbose

Lists the connector catalog.

--json emits the same detailed catalog fields as verbose mode.

connector inspect

npx rayfin connector inspect --name sales
npx rayfin connector inspect --name sales --entity dbo.Customers --rows 10
npx rayfin connector inspect --workspace-id <id> --item-id <id> --type fabric-warehouse --query queries\sample.sql

Inspects a source in read-only mode. It supports fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, and fabric-semanticmodel. It does not support kusto; that type fails with Unsupported connector type: kusto.

Inspect has three modes:

SQL inspect accepts only read queries that start with SELECT or WITH; DML and DDL are rejected. DAX inspect requires the query to start with EVALUATE.

connector invoke

npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(10, Sales)"}'
npx rayfin connector invoke --name mymodel --operation executeQuery --file payload.json

Invokes one configured operation. The positional connector name and operation also have flag forms, --name and --operation; flag values win over positionals.

Operation names match case-insensitively against the connector's operations: list. If the entry has no operations, the command falls back to the connector type's full catalog allowlist.

Invoke transports

fabric-semanticmodel calls Fabric and Power BI directly under the developer's own identity. It works with or without rayfin up, and it requires workspaceId and itemId under the connector's config: block.

Every other type, including kusto, POSTs to the deployed item at /__private/connectors/<name>/invoke and requires a prior rayfin up.

Invoke token handling

rayfin login consents to the Fabric scope, not the Power BI scope the semantic-model path needs. Interactively, the CLI prompts to complete Power BI consent. With --json, token acquisition is silent-only so prompts cannot corrupt the single-JSON-object contract; if consent is still needed, the command fails and tells you to drop --json or set RAYFIN_TOKEN. When RAYFIN_TOKEN is set, it is passed through unchanged and its audience is decoded and checked locally.

Invoke output

Success emits { status: 'ok', connector, operation, output }. A resolved call is not automatically a success: a normalizing connector reports failure as status: 'error', and a connector returning a raw envelope reports failure as status: 'Failed'. The CLI converts either failure shape into a non-zero exit.

Invoke errors