@microsoft/rayfin-connector-fabric-graphql 1.36.0-alpha.1601 → 1.36.0-alpha.1663

package/README.md

@@ -1,11 +1,7 @@
 # @microsoft/rayfin-connector-fabric-graphql
 
-> **Experimental** — this package is experimental and may change substantially in the near future.
-> Mount the typed connectors runtime via the experimental subpath of
-> `@microsoft/rayfin-client` rather than the stable `RayfinClient` entry.
-
 Base types for Rayfin's Category A (GraphQL-backed) connectors:
-`fabric-sql`, `fabric-warehouse`, `fabric-sqlanalytics`, and `fabric-graphql`.
+`fabric-sqldatabase`, `fabric-warehouse`, `fabric-sqlanalytics`, and `fabric-graphql`.
 
 This package contributes nothing at runtime — it only exports the types
 needed to make

package/assets/docs/entities.md

@@ -54,6 +54,11 @@ Generate `<EntityName>.ts` from `metadata.json` following every rule below. **`m
 - `className = pascalCase(table.tableName)` (`product_category` → `ProductCategory`). One file `<className>.ts` per table, no nesting.
 - **Pluralize only idempotently.** Pluralizing a singular name is fine (`Order` → `Orders`); an already-plural name (`Orders`, `Categories`) stays as-is — never double-pluralize. Keep the `@entity` name and the `client.connectors.<name>.<Entity>` path consistent with whatever you pick.
 - **Names are global across all connectors.** Before finalizing, scan every other `rayfin/connectors/*/` dir and the entities already generated here for the same name. Only on a real collision, prefix the source database name (PascalCased, from `metadata.json` `source`): `Product` → `SalesDbProduct`; if that database name also collides, use the PascalCased connector name. Never prefix a name that does not collide. On a rename, use the new name everywhere (class, file, `@entity`, `TSchema` key, re-export, access path) and tell the user.
+- **Never use a reserved GraphQL type name.**
+  The generated schema already defines the built-in scalars and the operation root types, so an entity called `Date` or `Query` redefines an existing type and the deploy is rejected.
+  Matching is case-sensitive and exact — `TaskDate` and `OrderDate` are fine.
+  The authoritative list is the "Reserved entity names" section of `@microsoft/rayfin-core/assets/docs/decorators.md` — read it there rather than relying on memory.
+  When `pascalCase(table.tableName)` lands on a reserved name, append a domain suffix (`Date` → `DateRecord`, `Query` → `QueryRecord`), keep `Source({ table: '...' })` pointed at the original table, and tell the user about the rename.
 
 ### 2. Primary keys
 
@@ -121,11 +126,7 @@ Build the option object in order (omit unused keys): `optional: true` if `column
 
 Server-generated columns have **no** decorator option marking them as such — do not invent one; the only change is the `AutoGenerated<T>` wrapper from 4a. Surface a one-line note per such column (for example `'<table>.<column>' is server-generated (identity); omit it on create()`). A server-generated key still follows the key rules in §2.
 
-### 6. Global-type shadow
-
-If `pascalCase(table.tableName)` equals a column's TS type (for example a table `Date` with a `datetime2` column), the unqualified type resolves to the entity class. Render it as `globalThis.Date` in that one annotation only.
-
-### 7. Relationships
+### 6. Relationships
 
 Emit `@one` (forward) and `@many` (reverse) from foreign-key metadata **only** — never infer from column names or values. Group `table.foreignKeys` by `constraintName`: one group = one relationship; rows in a group are the ordered column pairs of a composite FK.
 
@@ -157,18 +158,18 @@ When a referenced/other table is not in the set you are generating (subset mode)
 
 `singularize`: `ies→y` (len>3); `xes|ses|ches|shes→ drop -es`; `<non-s>s→ drop -s`; else unchanged. `pluralize` (idempotent): already-plural → unchanged; `<non-vowel>y→ -ies`; `x|z|ch|sh→ +es`; else `+s`.
 
-### 8. Missing metadata
+### 7. Missing metadata
 
 No PK metadata → warn `No PK metadata available for <tableName>; generated as a keyless entity.` No FK metadata (and no incoming FK) → warn `No FK metadata available for <tableName>; relationships omitted.` For Lakehouse these are known limitations, not a cue to infer. The file still generates keyless and relationship-free; the Builder may add logical keys/relationships manually, but never add them without that input.
 
-### 9. Imports
+### 8. Imports
 
 - Always include `entity`, then append — in this exact order — the decorators actually used: `boolean`, `date`, `decimal`, `int`, `text`, `uuid`, `one`, `many`. Skip unused. All from `@microsoft/rayfin-core`.
 - Always include `Source` from `@microsoft/rayfin-connectors`, on its own import line.
 - If any column is server-generated, also add `import type { AutoGenerated } from '@microsoft/rayfin-connectors';`.
 - For each relationship target class, add an alphabetized sibling import `import { <Class> } from './<Class>.js';` (self-references get none; subset-skipped relationships contribute none).
 
-### 10. Canonical example
+### 9. Canonical example
 
 ```ts
 import { entity, uuid, text, int, date, one, many } from '@microsoft/rayfin-core';

package/assets/docs/index.md

@@ -83,9 +83,10 @@ export type InventorySchema = GraphQLBackedConnector<
 
 ### The `entities` map
 
-`connectorConfig.entities` is the default column selection, so a read or write without an explicit `select` returns the full row. **It is required** — omit it and every no-selection read throws `SELECTION_REQUIRED`.
+`connectorConfig.entities` supplies the **default column selection** used by `findMany()`, `findFirst()`, and `findByKey()` when the call passes no selection. **It is required** — omit it and those calls throw `SELECTION_REQUIRED`.
 
 - List the generated entity **classes**, e.g. `entities: { Order, Customer }`. The client reads each class to derive the default column selection and relationship cardinality.
+- The default does **not** reach the query chain. A read that starts with `.select()` / `.where()` / `.orderBy()` / `.first()` must carry an explicit `.select([...])`, or `.execute()` throws `SELECTION_REQUIRED` no matter what `entities` contains. See [Querying](./querying.md#which-reads-need-an-explicit-select).
 
 ### Keep operations in one place
 
@@ -93,10 +94,10 @@ export type InventorySchema = GraphQLBackedConnector<
 
 ## Wire the client
 
-Deploying a connector does not make it callable. Expose it through a `ConnectorsRayfinClient` so it appears as `client.connectors.<name>`. Import that client from the `@microsoft/rayfin-client/experimental` subpath (not the stable entry). The connector key must be identical in three places: `name` in `rayfin.yml`, the `AppConnectorsSchema` property, and the `connectors` option.
+Deploying a connector does not make it callable. Expose it through a `ConnectorsRayfinClient` so it appears as `client.connectors.<name>`. Import that client from the main `@microsoft/rayfin-client` entry. The connector key must be identical in three places: `name` in `rayfin.yml`, the `AppConnectorsSchema` property, and the `connectors` option.
 
 ```ts
-import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
 import { InventorySchema, connectorConfig as inventoryConfig } from '../../rayfin/connectors/inventory/schema';
 
 type AppConnectorsSchema = { inventory: InventorySchema };

package/assets/docs/mutations.md

@@ -39,12 +39,12 @@ client.connectors.analytics.Sales.create({ /* ... */ }); // compile error: read-
 
 **Server-generated columns** (`AutoGenerated<T>`: `IDENTITY`, `DEFAULT`, computed) are optional on write and come back populated in the returned row. Most reject a value; a plain `DEFAULT` is the exception (omit for the default, or pass to override).
 
-By-key `update` / `delete` take the same full key object as `findByKey`. A keyless entity exposes none of them — read-only regardless of dialect.
+By-key `update` / `delete` take the same full key object as `findByKey`. A **keyless** entity (`primaryKey: []`, common on Lakehouse and Warehouse where `metadata.json` carries no key) drops `findByKey`, `update`, and `delete` at compile time — there is no key to address a row by. `create` is unaffected and stays available whenever `operations:` and `@role(...)` allow it, since an insert needs no key.
 
 ## Quick guide
 
 - **Lakehouse (`fabric-sqlanalytics`)** — reads only.
 - **SQL Database (`fabric-sqldatabase`)** — full CRUD; mutations return the full row, render it directly.
-- **Warehouse (`fabric-warehouse`)** — full CRUD; mutations return `DbOperationResult`, so re-query with `findByKey`/`select` if you need the persisted values.
+- **Warehouse (`fabric-warehouse`)** — full CRUD; mutations return `DbOperationResult`, so re-query with `findByKey`/`select` if you need the persisted values. On a keyless entity that re-query has to go through the chain with a `where` filter.
 
 For roll-ups (`groupBy` / `aggregate`), connector entities use the same fluent aggregation API as the app-schema GraphQL client, reached via `client.connectors.<name>.<Entity>`. See the `@microsoft/rayfin-data` package docs (`aggregations.md`) for the full spec.

package/assets/docs/querying.md

@@ -8,16 +8,55 @@ Reading entities: the query chain, by-key lookups, and related columns. For roll
 
 Each entity is reached via `client.connectors.<name>.<Entity>`. The surface depends on `operations:` (which verbs) and the dialect (what writes return). **Reads are identical on Lakehouse, Warehouse, and SQL Database.**
 
+## Which reads need an explicit `select`
+
+There are two read surfaces, and they treat selection differently. Getting this wrong is the most common Category A runtime error.
+
+| Surface | Entry points | Selection | Ordering / row limit |
+| --- | --- | --- | --- |
+| Convenience methods | `findMany`, `findFirst`, `findByKey` | Optional — falls back to the default columns from `connectorConfig.entities` | Not available |
+| Query chain | `.select()`, `.where()`, `.orderBy()`, `.first()` → `.execute()` / `.executePaginated()` | **Mandatory `.select([...])`** | `.orderBy()` / `.first(n)` / `.after(cursor)` |
+
+The default selection from `connectorConfig.entities` **never** reaches the query chain. A chain that reaches `.execute()` with no `.select()` throws `SELECTION_REQUIRED` even when `entities` is fully populated:
+
+```ts
+// ❌ throws SELECTION_REQUIRED — .first() does not inherit the default columns.
+await client.connectors.inventory.Order.first(20).execute();
+
+// ✅ chain with an explicit selection.
+await client.connectors.inventory.Order
+  .select(['orderId', 'customerEmail', 'total'])
+  .first(20)
+  .execute();
+
+// ✅ no selection needed — findMany uses the default columns.
+await client.connectors.inventory.Order.findMany();
+```
+
+Because `findMany` accepts only a selection and a filter, any read that needs `orderBy` or a row cap must use the chain — and therefore must name its columns.
+
 ## Reads
 
 ```ts
-// Query chain: select -> where -> orderBy -> execute
+// Query chain: select -> where -> orderBy -> first -> execute.
+// .select() is required on every chain.
 const orders = await client.connectors.inventory.Order
   .select(['orderId', 'customerEmail', 'total'])
   .where({ total: { gt: 100 } })
   .orderBy({ total: 'desc' })
+  .first(20)
   .execute();
 
+// findMany / findFirst: `(fields?, filter?)` or `(filter?)`.
+// An array first argument is the selection; anything else is the filter.
+const all = await client.connectors.inventory.Order.findMany();
+const big = await client.connectors.inventory.Order.findMany({ total: { gt: 100 } });
+const cols = await client.connectors.inventory.Order.findMany(
+  ['orderId', 'total'],
+  { total: { gt: 100 } },
+);
+const one = await client.connectors.inventory.Order.findFirst({ orderId: { eq: 'o-1' } });
+
 // By-key: full key object; select is optional.
 // Omit select -> full row; pass a scalar-only select -> just those columns.
 const order = await client.connectors.inventory.Order.findByKey({ orderId: 'o-1' });
@@ -34,14 +73,73 @@ const lineItem = await client.connectors.sales.OrderItem.findByKey({
 });
 ```
 
+`.execute()` and `findMany` return a plain array of rows; `findFirst` and `findByKey` return `Row | null`. For a cursor envelope, end the chain with `.executePaginated()` instead — see [Paging](#paging).
+
 `findByKey` takes the full primary key (required) and an **optional** scalar-only
 `select`. With no `select` it returns the full `Row | null`; with one it returns
 `Pick<Row, selected> | null`. It is scalar-only — read relationships through the
 query chain. Omitting a composite-key part is a compile error.
 
+Keyless entities (`primaryKey: []`, common on Lakehouse and Warehouse) drop `findByKey`, `update`, and `delete` at compile time — reads go through the chain, `findMany`, and `findFirst`, and `create` is still available if `operations:` allows it.
+
+## Filters
+
+`.where(...)` and the filter argument of `findMany` / `findFirst` take the same DAB filter object: one entry per column, each an operator map. The operators available depend on the column kind.
+
+| Column kind | Operators |
+| --- | --- |
+| string (`@text`, `@uuid`, `@email`) | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` (lexicographic), `contains`, `notContains`, `startsWith`, `endsWith`, `isNull`, `in` |
+| number (`@int`, `@decimal`) | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `isNull`, `in` |
+| `@date` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `isNull`, `in` |
+| `@boolean` | `eq`, `neq`, `isNull`, `in` |
+
+Sibling entries are ANDed. Combine alternatives with `and` / `or` — lowercase per the DAB spec, each taking an **array** of filter objects. There is no `not`.
+
+```ts
+await client.connectors.inventory.Order
+  .select(['orderId', 'status', 'total'])
+  .where({
+    status: { in: ['open', 'pending'] },
+    shippedUtc: { isNull: true },
+    or: [{ total: { gte: 1000 } }, { customerEmail: { endsWith: '@contoso.com' } }],
+  })
+  .execute();
+```
+
+`isNull: true` matches nulls, `isNull: false` matches non-nulls.
+
+## Paging
+
+`.first(n)` returns a single page. `n` is bounded by DAB's maximum page size (100,000); `-1` requests an unbounded page, which DAB still caps at that maximum. `.execute()` and `findMany` hand back that one page as a plain array, so a table larger than the page size needs cursors.
+
+Finish the chain with `.executePaginated()` and feed `endCursor` into `.after()` on the next chain:
+
+```ts
+const page = await client.connectors.inventory.Order
+  .select(['orderId', 'total'])
+  .orderBy({ orderId: 'asc' })
+  .first(500)
+  .executePaginated();
+
+if (page.hasNextPage && page.endCursor) {
+  const next = await client.connectors.inventory.Order
+    .select(['orderId', 'total'])
+    .orderBy({ orderId: 'asc' })
+    .first(500)
+    .after(page.endCursor)
+    .executePaginated();
+}
+```
+
+`executePaginated()` returns `PagedResult<Row>` — `{ items, hasNextPage, endCursor?, totalCount? }`. Pagination is forward-only; DAB has no `last` / `before`.
+
+`.after()` and `.executePaginated()` live on the builder, not on the entity client, so the chain still has to start with `.select([...])` / `.where(...)` — and `.executePaginated()` requires the same explicit selection as `.execute()`.
+
 ## Related columns
 
-`select` pulls columns from a `@one` or `@many` navigation field as a **dotted path**. Name the leaf column (`category.name`), never the bare relationship (`category`) — that is a compile error. Paths nest to any depth and are validated segment-by-segment, so a wrong hop (`category.nope`) fails to compile.
+`select` pulls columns from a `@one` or `@many` navigation field as a **dotted path**. Name the leaf column (`category.name`), never the bare relationship (`category`) — that is a compile error. Paths nest to any depth.
+
+Segment validation is typed only as far as `TSchema` describes the hop, and cardinality is resolved at runtime from `connectorConfig.entities`. A path that gets past the compiler still throws: `INVALID_RELATIONSHIP_SELECTION` when a segment is not a `@one` / `@many` field, and `ENTITIES_REQUIRED_FOR_RELATIONSHIP_SELECT` when the entity classes were never registered. Register every entity a path traverses, not just the root.
 
 ```ts
 const products = await client.connectors.inventory.Product

package/assets/docs/troubleshooting.md

@@ -9,7 +9,8 @@ Anti-patterns and a symptom to cause to fix matrix for `fabric-sqlanalytics`, `f
 ## Anti-patterns
 
 - Never leave `schema.ts` as bare re-exports — the client import of `<Name>Schema` and `connectorConfig` fails.
-- Populate `connectorConfig.entities` with the generated entity **classes** (e.g. `entities: { Order, Customer }`), never omit it. Omitting it makes every no-selection read throw `SELECTION_REQUIRED`.
+- Populate `connectorConfig.entities` with the generated entity **classes** (e.g. `entities: { Order, Customer }`), never omit it. Omitting it makes every no-selection `findMany` / `findFirst` / `findByKey` throw `SELECTION_REQUIRED`.
+- Never rely on `entities` to cover a query chain. `.where()` / `.orderBy()` / `.first()` do not inherit the default selection — always pair them with `.select([...])`.
 - In subset mode, list in `TSchema` only entities you actually generated.
 - Keep `connectorConfig.operations` identical to the YAML `operations:`, and each entity `@role(...)` action a subset of that pair. Narrow YAML first; never widen a decorator just to match the connector.
 - Policies use the typed `claims` / `item` DSL — never raw SQL or DAB-policy strings.
@@ -24,9 +25,26 @@ Anti-patterns and a symptom to cause to fix matrix for `fabric-sqlanalytics`, `f
 | --- | --- | --- |
 | `rayfin up connector apply` fails on a role action | Entity `@role(...)` includes an action not in the YAML `operations:` | Narrow the decorator to match YAML. |
 | `rayfin up connector apply` fails with a duplicate GraphQL type | Two connectors generated an entity with the same name — names are global | Disambiguate by prefixing the source database name; update the class, file, `@entity`, `TSchema` key, and access path together, then re-apply. |
+| `Reserved GraphQL type names detected in connector entities` | An entity is named after a built-in scalar or an operation root type (`Date`, `Int`, `Query`, …), which the generated schema already defines | Rename the class (`Date` → `DateRecord`), keep `Source({ table: '...' })` on the original table, update the `@entity`, `TSchema` key, re-export, and access path, then re-apply. |
 | `rayfin connector add` writes the YAML entry but no entity files | Expected — the CLI never emits entity files | Generate them from `metadata.json` per the contract. If `metadata.json` is also missing, discovery failed. |
 | `Property '<name>' does not exist on connectors` | Connector key in `AppConnectorsSchema` does not match the `connectors` option | Use the `rayfin.yml` `name` in all three places. |
 | A CRUD method is missing from autocomplete | Expected: `<Name>Schema` narrows methods to `operations` | Widen via `rayfin connector add --operations`, then re-import. |
-| Import of `ConnectorsRayfinClient` fails to resolve | Imported from the stable `@microsoft/rayfin-client` entry | Import from `@microsoft/rayfin-client/experimental`. |
+| Import of `ConnectorsRayfinClient` fails to resolve | Imported from the removed or misspelled experimental subpath | Import from the stable `@microsoft/rayfin-client` entry. |
 | `Cannot find module '@microsoft/rayfin-connector-fabric-graphql'` | Connector packages never installed — `connector add` does not add them | Run the pinned `npm install` that `connector add` printed. |
-| A read throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing, so there is no default column list | Add the entity class to `connectorConfig.entities`, or pass an explicit `select([...])`. |
+| A query chain throws `SELECTION_REQUIRED` | The chain (`.where()` / `.orderBy()` / `.first()` → `.execute()`) has no `.select()`. `connectorConfig.entities` does not supply a default here — only `findMany` / `findFirst` / `findByKey` read it | Add `.select([...])` to the chain, or drop to `findMany(filter)` if you need neither ordering nor a row limit. |
+| `findMany` / `findFirst` / `findByKey` throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing, so there is no default column list | Add the entity class to `connectorConfig.entities`, or pass an explicit selection to the call. |
+
+## Error codes
+
+Every runtime failure on the connector path is a `ConnectorsError` carrying one of these codes.
+
+| Code | Thrown when | Fix |
+| --- | --- | --- |
+| `SELECTION_REQUIRED` | A chain reached `.execute()` / `.executePaginated()` with no `.select()`, or a no-selection `findMany` / `findFirst` / `findByKey` ran while `connectorConfig.entities` was unpopulated | Add `.select([...])`, or register the entity class in `connectorConfig.entities`. |
+| `ENTITIES_REQUIRED_FOR_RELATIONSHIP_SELECT` | A dotted path (`category.name`) was selected but `connectorConfig.entities` is unpopulated, so relationship cardinality is unknown | Register every entity the path traverses, not just the root. |
+| `INVALID_RELATIONSHIP_SELECTION` | A segment of a dotted path is not a `@one` / `@many` field on that entity | Fix the path, or select the column directly if it is a plain scalar. |
+| `INVALID_COLUMN_NAME` | A selection or mutation input used a name that is not a legal GraphQL name | Use the entity **property** name, never the raw SQL column — the `column:` option maps between them. |
+| `EMPTY_MUTATION_SELECTION` | A mutation had no columns left to return | Pass at least one input column, or register the entity in `connectorConfig.entities` so server-generated columns are returned. |
+| `MUTATION_NO_RESULT` | The server ran the mutation but returned no data | Usually a `@role` policy filtering the row out, or a key that matches nothing — verify both. |
+| `OPERATION_NOT_ALLOWED` | A CRUD method was reached that is outside the connector's `operations:` (the runtime gate behind the compile-time narrowing) | Widen `operations:` in `rayfin.yml` **and** `connectorConfig`, re-apply, then re-import. |
+| `UNKNOWN_CONNECTOR` | A connector was accessed that was never passed in the client's `connectors` option | Add it to `connectors: { <name>: connectorConfig }` — the key must match the `rayfin.yml` `name`. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microsoft/rayfin-connector-fabric-graphql",
-  "version": "1.36.0-alpha.1601",
-  "description": "Experimental Cat A GraphQL-backed connector types for the Rayfin SDK. Provides the entity-oriented marker (GraphQLBackedConnector) and CRUD operation gating used by the typed client.connectors.<name>.<Entity>.select(...).execute() surface.",
+  "version": "1.36.0-alpha.1663",
+  "description": "Cat A GraphQL-backed connector types for the Rayfin SDK. Provides the entity-oriented marker (GraphQLBackedConnector) and CRUD operation gating used by the typed client.connectors.<name>.<Entity>.select(...).execute() surface.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -26,8 +26,8 @@
     "rimraf": "~6.0.1"
   },
   "dependencies": {
-    "@microsoft/rayfin-data": "1.36.0-alpha.1601",
-    "@microsoft/rayfin-connectors": "1.36.0-alpha.1601"
+    "@microsoft/rayfin-connectors": "1.36.0-alpha.1663",
+    "@microsoft/rayfin-data": "1.36.0-alpha.1663"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",