Rayfin Connectors
Bring an existing Fabric data source into a Rayfin app.
Two contracts govern connectors, and this file is neither of them:
- The versioned behavioral contract — the category guides shipped in
@microsoft/rayfin-guide.
Workflow, generation rules, authorization semantics, per-dialect behavior, error handling.
- The live catalog contract —
rayfin connector types --json.
Current types, categories, allowed operations, auth modes, required config, adapter versions, and the packages plus versions to install.
Read the matching category guide for workflow and semantics.
Read rayfin connector types --json for current types, capabilities, package names, and versions.
Answer neither from memory, and never copy either into code or prose — a copied catalog goes stale within days.
This file is the router: whether a connector applies, which category you are in, and where to read next.
When to Use a Connector
Use a connector when the user wants the app to read or write existing data already living in a Fabric workspace.
Do not use a connector when the user is creating a brand-new data model owned by the Rayfin app — those entities go under rayfin/data/ and are managed via rayfin up db apply, not rayfin connector add.
Routing note: @role and @entity also appear in the base rayfin skill for owned rayfin/data/ models.
This skill applies only when those decorators are used inside rayfin/connectors/ files.
Connectors are cloud-only on day one.
rayfin dev parses the connectors: block but does not wire it; verifying connector behavior requires rayfin up.
fabric-sqlanalytics means the Lakehouse SQL analytics endpoint, not full Lakehouse access.
It can read SQL-visible tables and views only; it cannot directly open PDFs, images, or other files in the Lakehouse Files area.
Do not describe it as generic Lakehouse support.
Connector Commands
rayfin connector ... is always registered; no opt-in is required.
Two Categories — Decide First
|
Category A — GraphQL entities |
Category B — function bridge |
| Types |
fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase |
fabric-semanticmodel; kusto is experimental |
| App surface |
Generated entity files with typed CRUD |
Named operations carrying a raw query |
Entity files, @role policies, metadata.json entities |
Yes |
No |
| Read next |
cli/connectors/category-a-entities.md |
cli/connectors/category-b-function-bridge.md |
Category membership is stable enough to route on.
Everything 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.
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.
Do not read both category docs.
Category 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.
Reading the Connector Guides
These guides are published with the Rayfin guide package. Resolve them from disk when you need the version installed in the app:
node_modules/@microsoft/rayfin-guide/assets/docs/<path>.
This skill can load before @microsoft/rayfin-guide is installed, or against a different package version than the one it was written for.
If the guide path is unavailable, say it is unavailable and fall back to rayfin connector types --json and rayfin connector <command> --help.
Do not reconstruct the contract from memory.
Eventhouse (kusto) has a dedicated guide
The 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.
When to choose it, the streaming model, shaping KQL, safe query construction, and result handling all live in cli/connectors/eventhouse.md, with the shared function-bridge contract in cli/connectors/category-b-function-bridge.md.
Read those; do not reconstruct them from memory.
Workflow
Add. rayfin connector add --type <type> --workspace-id <ws> --item-id <item> [--name <name>] [--operations <ops>]
Verifies the Fabric item, writes the rayfin.yml entry, and scaffolds rayfin/connectors/<name>/ — plus metadata.json for Category A.
It installs nothing, but it prints the exact version-pinned npm install command — run that verbatim.
Never install these packages unversioned: their npm tags lag the published release, so npm install <pkg> pulls an older connector and a second, mismatched copy of @microsoft/rayfin-data.
See cli/connectors/add.md.
Scope. Without --operations, add writes every operation the catalog allows.
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.
Ask when the intent is ambiguous; for Category A also ask whether rows are scoped per user.
You can narrow below the catalog default, never widen above it.
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.
Deploy. rayfin up, or rayfin up connector apply to re-apply DAB config alone.
Preflight — prove data comes back before you build anything on it.
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.
| Category |
Command |
| A |
rayfin connector inspect --name <name> --entity <entity> --rows 1 |
B — fabric-semanticmodel |
rayfin connector invoke <name> executeQuery --file ./probe.query.json |
B — kusto |
rayfin connector invoke <name> executeQuery --file ./probe.query.json |
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.
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.
--file takes a JSON payload, not a raw .dax or .kql file — it is JSON.parsed, so a bare query fails before the connector is ever reached. Write the query into the operation's input envelope:
{ "query": "EVALUATE TOPN(1, Sales)" }
Prefer that over --input '<json>' 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.
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.
Commands
| Command |
What it does |
Doc path |
rayfin connector types [--json] |
Emit the live catalog. |
— |
rayfin connector search [query] |
Discover addable Fabric sources before you know workspace/item IDs. |
cli/connectors/search.md |
rayfin connector add |
Declare a connector and scaffold it. |
cli/connectors/add.md |
rayfin connector list / remove |
List connectors; remove the entry and its directory. |
cli/connectors/index.md |
rayfin connector inspect |
Run one read-only sample query against a source. |
cli/connectors/inspect.md |
rayfin connector invoke <name> <operation> |
Run one named operation — the loop for Category B. |
cli/connectors/invoke.md |
Flags, output shapes, and error catalogs live in those docs and in --help.
Read one before answering a detailed question; do not guess.
Two behaviors worth knowing before you pick a command:
connector inspect does not support experimental kusto — use rayfin connector invoke <name> executeQuery instead.
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.
Rules and Anti-Patterns
- The
rayfin.yml connectors: block is an array of entries with name and type fields. Never write the legacy map shape.
- Never name an entity after a reserved GraphQL type.
Entity names become GraphQL type names, so built-in scalars, the operation root types, and any name starting with
__ are rejected at rayfin up.
Matching is case-sensitive and exact — TaskDate is fine.
The authoritative list is the "Reserved entity names" section of @microsoft/rayfin-core/assets/docs/decorators.md — read it there, never from memory.
Rename the entity and keep Source({ table: '...' }) pointed at the original table.
rayfin connector add discovers schema only when workspaceId and itemId are literal strings — ${VAR} placeholders are rejected.
- Default to the narrowest operations the user described — do not assume full CRUD for a read-only ask.
- Never hand-edit a file that carries a
// @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.
- 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.
- The relationship options
sourceFields / targetFields (on @one() / @many()) declare a custom foreign key and are connector entities only — they are rejected on the data path.
- Connectors do not run under
rayfin dev — test via rayfin up and rayfin up connector apply against a deployed environment.
- 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.
- Pass model- or user-authored DAX and KQL to
invoke with --file, and remember it takes a JSON payload ({"query":"…"}), not a raw .dax/.kql file — a bare query is JSON.parsed 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.
- Do not load both category reference docs, and do not restate a guide's contents instead of reading it.
Troubleshooting
| Symptom |
Fix |
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. |
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. |
connector add errors with "literal IDs required" |
--workspace-id or --item-id was a ${VAR} placeholder. Pass literal values. |
The scaffolded rayfin/connectors/<name>/ does not compile |
Its imports are not installed. Run the pinned npm install command connector add printed. |
| Type errors between connector and client code |
An unversioned install pulled a stale connector, so two @microsoft/rayfin-data copies exist. Reinstall pinned. |
A query chain throws SELECTION_REQUIRED |
.where() / .orderBy() / .first() never inherit the default selection. Add .select([...]) to the chain. |
findMany / findFirst / findByKey throws SELECTION_REQUIRED |
connectorConfig.entities is missing. Add the entity class to it, or pass an explicit selection. |
Local rayfin dev ignores the connector |
Expected — connectors are cloud-only. Exercise via rayfin up. |
FEATURE_NOT_ENABLED / 404 from /connector-invoke/<name> |
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. |
Everything else belongs to a guide: entity generation and authorization in cli/connectors/category-a-entities.md, connector config fields in cli/connectors/category-b-function-bridge.md, and per-command error catalogs in the command docs above.
1---2name: rayfin-connectors3description: "Connect existing Fabric data sources (Lakehouse, Warehouse, SQL Database, semantic model, KQL Database/Eventhouse) 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/search/types/inspect/invoke), rayfin up connector apply, connectors:, fabric-sqlanalytics, fabric-warehouse, fabric-sqldatabase, fabric-semanticmodel, kusto/KQL, DAX EVALUATE, rayfin/connectors/, metadata.json, AppConnectorsSchema, ConnectorsSchema, ConnectorsRayfinClient, client.connectors, connectorConfig, GraphQLBackedConnector, schema.ts, @role, claims.sub, executeQuery, executeCommand, resultSetRowCountLimit, queryServiceUri, databaseName, KustoConnectorConfig. Includes connector entity imports/maps causing a blank page after deploy, Uncaught SyntaxError, or Invalid or unexpected token."4metadata:5 source: https://skillmd.com/skills/microsoft/rayfin-connectors6 author: microsoft7 version: "0.7.4"8---910# Rayfin Connectors1112Bring an existing Fabric data source into a Rayfin app.1314Two contracts govern connectors, and this file is neither of them:1516- **The versioned behavioral contract** — the category guides shipped in `@microsoft/rayfin-guide`.17 Workflow, generation rules, authorization semantics, per-dialect behavior, error handling.18- **The live catalog contract** — `rayfin connector types --json`.19 Current types, categories, allowed operations, auth modes, required config, adapter versions, and the packages plus versions to install.2021**Read the matching category guide for workflow and semantics.22Read `rayfin connector types --json` for current types, capabilities, package names, and versions.**23Answer neither from memory, and never copy either into code or prose — a copied catalog goes stale within days.2425This file is the router: whether a connector applies, which category you are in, and where to read next.2627## When to Use a Connector2829Use a connector when the user wants the app to read or write **existing** data already living in a Fabric workspace.3031Do **not** use a connector when the user is creating a brand-new data model owned by the Rayfin app — those entities go under `rayfin/data/` and are managed via `rayfin up db apply`, not `rayfin connector add`.3233**Routing note:** `@role` and `@entity` also appear in the base `rayfin` skill for owned `rayfin/data/` models.34This skill applies only when those decorators are used inside `rayfin/connectors/` files.3536Connectors are cloud-only on day one.37`rayfin dev` parses the `connectors:` block but does not wire it; verifying connector behavior requires `rayfin up`.3839`fabric-sqlanalytics` means the Lakehouse SQL analytics endpoint, not full Lakehouse access.40It can read SQL-visible tables and views only; it cannot directly open PDFs, images, or other files in the Lakehouse `Files` area.41Do not describe it as generic Lakehouse support.4243## Connector Commands4445`rayfin connector ...` is always registered; no opt-in is required.4647## Two Categories — Decide First4849| | Category A — GraphQL entities | Category B — function bridge |50| -------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------- |51| Types | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase` | `fabric-semanticmodel`; `kusto` is experimental |52| App surface | Generated entity files with typed CRUD | Named operations carrying a raw query |53| Entity files, `@role` policies, `metadata.json` entities | Yes | No |54| Read next | `cli/connectors/category-a-entities.md` | `cli/connectors/category-b-function-bridge.md` |5556Category membership is stable enough to route on.57Everything 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.5859**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.6061Do not read both category docs.62Category 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.6364## Reading the Connector Guides6566These guides are published with the Rayfin guide package. Resolve them from disk when you need the version installed in the app:6768`node_modules/@microsoft/rayfin-guide/assets/docs/<path>`.6970This skill can load before `@microsoft/rayfin-guide` is installed, or against a different package version than the one it was written for.71If the guide path is unavailable, say it is unavailable and fall back to `rayfin connector types --json` and `rayfin connector <command> --help`.72Do not reconstruct the contract from memory.7374### Eventhouse (`kusto`) has a dedicated guide7576The 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.77When to choose it, the streaming model, shaping KQL, safe query construction, and result handling all live in `cli/connectors/eventhouse.md`, with the shared function-bridge contract in `cli/connectors/category-b-function-bridge.md`.78Read those; do not reconstruct them from memory.7980## Workflow81821. **Add.** `rayfin connector add --type <type> --workspace-id <ws> --item-id <item> [--name <name>] [--operations <ops>]`83 Verifies the Fabric item, writes the `rayfin.yml` entry, and scaffolds `rayfin/connectors/<name>/` — plus `metadata.json` for Category A.84 It **installs nothing**, but it prints the exact version-pinned `npm install` command — run that verbatim.85 Never install these packages unversioned: their npm tags lag the published release, so `npm install <pkg>` pulls an older connector and a second, mismatched copy of `@microsoft/rayfin-data`.86 See `cli/connectors/add.md`.872. **Scope.** Without `--operations`, `add` writes every operation the catalog allows.88 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.89 Ask when the intent is ambiguous; for Category A also ask whether rows are scoped per user.90 You can narrow below the catalog default, never widen above it.913. **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.924. **Deploy.** `rayfin up`, or `rayfin up connector apply` to re-apply DAB config alone.935. **Preflight — prove data comes back before you build anything on it.**94 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.9596 | Category | Command |97 | --- | --- |98 | A | `rayfin connector inspect --name <name> --entity <entity> --rows 1` |99 | B — `fabric-semanticmodel` | `rayfin connector invoke <name> executeQuery --file ./probe.query.json` |100 | B — `kusto` | `rayfin connector invoke <name> executeQuery --file ./probe.query.json` |101102 `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.103104 **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.105106 `--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:107108 ```json109 { "query": "EVALUATE TOPN(1, Sales)" }110 ```111112 Prefer that over `--input '<json>'` 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.113114 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.115116## Commands117118| Command | What it does | Doc path |119| -------------------------------------------- | ------------------------------------------------------------------- | --------------------------- |120| `rayfin connector types [--json]` | Emit the live catalog. | — |121| `rayfin connector search [query]` | Discover addable Fabric sources before you know workspace/item IDs. | `cli/connectors/search.md` |122| `rayfin connector add` | Declare a connector and scaffold it. | `cli/connectors/add.md` |123| `rayfin connector list` / `remove` | List connectors; remove the entry **and** its directory. | `cli/connectors/index.md` |124| `rayfin connector inspect` | Run one read-only sample query against a source. | `cli/connectors/inspect.md` |125| `rayfin connector invoke <name> <operation>` | Run one named operation — the loop for Category B. | `cli/connectors/invoke.md` |126127Flags, output shapes, and error catalogs live in those docs and in `--help`.128Read one before answering a detailed question; do not guess.129130Two behaviors worth knowing before you pick a command:131132- `connector inspect` does not support experimental `kusto` — use `rayfin connector invoke <name> executeQuery` instead.133- `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`.134135## Rules and Anti-Patterns136137- The `rayfin.yml` `connectors:` block is an **array** of entries with `name` and `type` fields. Never write the legacy map shape.138- **Never name an entity after a reserved GraphQL type.**139 Entity names become GraphQL type names, so built-in scalars, the operation root types, and any name starting with `__` are rejected at `rayfin up`.140 Matching is case-sensitive and exact — `TaskDate` is fine.141 The authoritative list is the "Reserved entity names" section of `@microsoft/rayfin-core/assets/docs/decorators.md` — read it there, never from memory.142 Rename the entity and keep `Source({ table: '...' })` pointed at the original table.143- `rayfin connector add` discovers schema only when `workspaceId` and `itemId` are literal strings — `${VAR}` placeholders are rejected.144- Default to the **narrowest** operations the user described — do not assume full CRUD for a read-only ask.145- Never hand-edit a file that carries a `// @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.146- 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.147- The relationship options `sourceFields` / `targetFields` (on `@one()` / `@many()`) declare a custom foreign key and are **connector entities only** — they are rejected on the data path.148- Connectors do not run under `rayfin dev` — test via `rayfin up` and `rayfin up connector apply` against a deployed environment.149- **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.150- Pass model- or user-authored DAX and KQL to `invoke` with `--file`, and remember it takes a **JSON payload** (`{"query":"…"}`), not a raw `.dax`/`.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.151- Do not load both category reference docs, and do not restate a guide's contents instead of reading it.152153## Troubleshooting154155| Symptom | Fix |156| --- | --- |157| `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. |158| `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. |159| `connector add` errors with "literal IDs required" | `--workspace-id` or `--item-id` was a `${VAR}` placeholder. Pass literal values. |160| The scaffolded `rayfin/connectors/<name>/` does not compile | Its imports are not installed. Run the pinned `npm install` command `connector add` printed. |161| Type errors between connector and client code | An unversioned install pulled a stale connector, so two `@microsoft/rayfin-data` copies exist. Reinstall pinned. |162| A query chain throws `SELECTION_REQUIRED` | `.where()` / `.orderBy()` / `.first()` never inherit the default selection. Add `.select([...])` to the chain. |163| `findMany` / `findFirst` / `findByKey` throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing. Add the entity class to it, or pass an explicit selection. |164| Local `rayfin dev` ignores the connector | Expected — connectors are cloud-only. Exercise via `rayfin up`. |165| `FEATURE_NOT_ENABLED` / 404 from `/connector-invoke/<name>` | 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. |166167Everything else belongs to a guide: entity generation and authorization in `cli/connectors/category-a-entities.md`, connector config fields in `cli/connectors/category-b-function-bridge.md`, and per-command error catalogs in the command docs above.