rayfin connector

rayfin connector manages external Fabric sources, from discovery and registration through inspection and invocation.

connector is always registered in Rayfin 1.36. No connector feature-flag opt-in is required.

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

Type	Fabric item	Category	Operations	Auth default	Version
`fabric-sqlanalytics`	Lakehouse SQL analytics endpoint	Category A	`read`	`application` Changed in 1.36	No
`fabric-warehouse`	Warehouse	Category A	`read`, `create`, `update`, `delete`	`application` Changed in 1.36	No
`fabric-sqldatabase`	SQL Database	Category A	`read`, `create`, `update`, `delete`	`application` Changed in 1.36	No
`fabric-semanticmodel`	Semantic model	Category B	`executeQuery`	`delegated`	Pinned to `'1'` by `connector add`
`kusto`	KQL Database	Category B	`executeQuery`, `executeCommand`	`delegated`; existing entries only	New authoring held in 1.36

Category A connectors generate entity configuration for Data API Builder. Category B connectors expose function-style query operations and are delegated-only.

connector types, connector search, and connector add list only authorable types. In 1.36.2, kusto is absent and connector add --type kusto fails with Connector type "kusto" is not available in this release. Supported types: [fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, fabric-semanticmodel].

Existing Kusto entries still validate and deploy. 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:

Scope	Required flags	Behavior
Single workspace	`--workspace-id <id>` and `--type <type>`	Searches one workspace.
Tenant-wide	`--all-workspaces` and `--type <type>`	Searches all accessible workspaces.
Deployed project	No scope flags	Searches every workspace recorded in the project's deployments; `--type` is optional.

Flag	Description
`[query]`	Optional case-insensitive item-name filter.
`--query <text>`	Same filter as `[query]`; wins when both are provided.
`--workspace-id <id>`	Search one Fabric workspace. Requires `--type`.
`--all-workspaces`	Search every workspace the signed-in identity can access. Requires `--type`.
`--type <type>`	Narrow to one or more comma-separated connector types. Required with explicit workspace scope.
`--limit <n>`	Limit non-interactive output to the first `n` results.
`--output interactive\|plain\|json`	Select output mode.
`--json`	Emit one JSON object and skip the interactive picker.
`-v, --verbose`	Enable verbose output. Cannot be combined with `--json`.
`-y, --yes`	Auto-accept prompts in the interactive add handoff.

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>/.

Flag	Description
`--type <type>`	Required. One of the authorable connector type literals: `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, or `fabric-semanticmodel`. New `kusto` authoring is held in 1.36.2.
`--workspace-id <id>`	Required Fabric workspace ID. Must be a literal value; `${VAR}` placeholders are rejected.
`--item-id <id>`	Required Fabric item ID. Must be a literal value; `${VAR}` placeholders are rejected.
`--name <name>`	Connector name. If omitted, the CLI derives one from the Fabric item display name. Must match `/^[a-zA-Z0-9\-_]+$/` and be at most 256 characters.
`--operations <ops>`	Comma-separated subset of allowed operations. This can narrow the catalog defaults but cannot widen them; there is no `all` meta-operation.
`-y, --yes`	Auto-accept confirmation prompts, including overwriting an existing connector.
`-v, --verbose`	Enable verbose output.
`--json`	Emit machine-readable JSON.

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 fabric-semanticmodel, it writes the complete generated schema.ts.

For authorable versioned Category B types, connector add writes the catalog defaultVersion automatically. Today fabric-semanticmodel uses '1'.

Existing Kusto declarations also use version '1', but new Kusto authoring is held in 1.36.2.

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.

Flag	Description
`-v, --verbose`	Include catalog metadata for each connector.
`--json`	Emit the configured connector entries as JSON.

`connector remove`

npx rayfin connector remove sales --yes

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

Flag	Description
`-y, --yes`	Auto-accept confirmation prompts. Required in non-interactive contexts for existing connectors.
`-v, --verbose`	Enable verbose output.
`--json`	Emit machine-readable JSON.

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.

Flag	Description
`-v, --verbose`	Add category, default auth, dialect, operations, discoverable item types, required version, and client packages.
`--output interactive\|plain\|json`	Select output mode.
`--json`	Emit the catalog as JSON.

Changed in 1.36

--json emits { status, schemaVersion, count, types }. Each type includes category, description, defaultAuth, allowedAuthTypes, dialect, allowedOperations, requiredConfig, discoverableItemTypes, requiresVersion, optional defaultVersion, and version-pinned packages.

`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.

Flag	Description
`--name <name>`	Select a connector declared in `rayfin.yml`. Mutually exclusive with direct selectors.
`--workspace-id <id>` / `--workspace <name>`	Direct mode workspace selector. Use with `--item-id` or `--item` and `--type`.
`--item-id <id>` / `--item <name>`	Direct mode item selector. Use with a workspace selector and `--type`.
`--type <type>`	Connector type for direct mode.
`--url <portal-url>`	Semantic-model portal URL; extracts workspace and item IDs. Cannot be combined with other selectors.
`--entity <name>`	Structured entity sampling mode.
`--query <path>`	Raw query mode. Path must point to a `.sql` or `.dax` file inside the project.
`--rows <n>`	Row cap. Default is 100 for entity listing and 10 for entity or query modes; maximum is 100.
`-v, --verbose`	Enable verbose output.
`--output interactive\|plain\|json`	Select output mode.
`--json`	Emit a machine-readable JSON object.

Inspect has three modes:

Mode	How to select it	Query shape
Entity listing	Omit `--entity` and `--query`	SQL uses `INFORMATION_SCHEMA.TABLES`; DAX uses `INFO.TABLES()`.
Structured entity	Pass `--entity <name>`	SQL builds `SELECT TOP(n) * FROM <entity>`; DAX builds `EVALUATE TOPN(n, '<entity>')`.
Raw query	Pass `--query <path>`	Runs the `.sql` or `.dax` file verbatim.

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.

Flag	Description
`<connector-name>`	Connector name declared in `rayfin.yml`.
`<operation>`	Operation to invoke.
`--name <name>`	Connector name flag form; wins over the positional.
`--operation <operation>`	Operation flag form; wins over the positional.
`--input '<json>'`	Inline JSON payload. Exactly one of `--input` or `--file` is required.
`--file <path>`	JSON payload file, resolved against the project root. The resolved path must stay inside it; `..\` escapes are rejected before the file is read.
`-v, --verbose`	Enable verbose output. Cannot be combined with `--json`.
`--output interactive\|plain\|json`	Select output mode.
`--transport <mode>`	`auto` (default) picks per connector type; `deployed` forces the deployed BaaS route and needs a Rayfin app-session token in `RAYFIN_TOKEN`. New in 1.36
`--output-file <path>`	Write the full result to this file; inline output remains unless it exceeds `--max-inline-bytes`. New in 1.36
`--max-inline-bytes <bytes>`	Spill to a file and show only a preview when serialized output exceeds this many bytes; `0` always prints inline. Default `8192`. New in 1.36
`--json`	Emit one machine-readable JSON object.

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

With --transport auto, 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.

--transport deployed opts out of that shortcut and exercises the deployed BaaS route.

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 }. When output spills, the envelope also includes outputFile, outputBytes, outputTruncated, and previewItems.

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.

Note

Rayfin 1.36.1 coerces semantic-model Arrow Int64 values, including Union/Variant Int64s, before CLI output is serialized. Safe Int64 values should no longer print Do not know how to serialize a BigInt. Values outside JavaScript's safe integer range surface as connector overflow errors. Changed in 1.36.1

Invoke errors

Message	Fix
`Missing required connector invoke arguments`	Supply both the connector name and the operation.
`Choose exactly one payload source` / `Missing payload input`	Pass exactly one of `--input` or `--file`.
`Input file must be inside the project`	Use a relative path under the project root.
`Operation "<op>" is not allowed for connector "<name>"`	Check the connector's `operations:` in `rayfin.yml`, or the type's allowlist.
`missing workspaceId/itemId in rayfin.yml`	Add both under `config:`, or re-run `connector add`.
`Access token has the wrong audience for the Power BI query API`	Unset or replace `RAYFIN_TOKEN`, or re-run without `--json` to consent interactively.
`Invalid --max-inline-bytes value: <value>.`	Pass a non-negative whole number of bytes, or `0` to always print inline.
`No remote endpoint configured`	The non-semantic-model transport, or `--transport deployed`, needs a deployed item; run `npx rayfin up` first.

`up connector apply`

Preview Changed in 1.36

npx rayfin up connector apply
npx rayfin up connector apply --name inventory

Generates DAB configuration for declared Category A connectors, checks reserved and duplicate GraphQL entity names, and POSTs each generated config to the deployed workload.

It requires a prior npx rayfin up so the remote endpoint and connector settings exist. Category B connectors are reported as skipped because they do not have generated GraphQL DAB config.

Flag	Description
`--name <name>`	Apply only the named connector instead of every entry in `rayfin.yml`.
`-v, --verbose`	Enable verbose output.
`--json`	Emit `{ status, generate, results, steps, duration }`. `status` is `partial` when generation or apply failed for any connector.

npx rayfin up --json also includes connector generation and apply outcomes in the deployment steps map, with connector step keys namespaced as connector:<name>.

PromptRegister a Fabric SQL Database connector

Add a Rayfin connector named "sales" for my Fabric SQL Database using
`npx rayfin connector add --type fabric-sqldatabase --workspace-id <workspace-id>
--item-id <item-id> --name sales`, then show me the resulting rayfin.yml entry and the
scaffolded rayfin/connectors/sales/schema.ts.

Something wrong on this page?Report an issueEdit this page

rayfin connector

On this page