json-rest-api 2.1.0 → 2.3.0

package/docs/API.md

@@ -78,6 +78,7 @@ a separate context for each enlisted operation. See [transaction support](#trans
    - [PUT - Replace Resource](#put---replace-resource)
    - [PATCH - Update Resource](#patch---update-resource)
    - [DELETE - Remove Resource](#delete---remove-resource)
+   - [AGGREGATE - Grouped Totals](#aggregate---grouped-totals)
 3. [Relationship Methods](#relationship-methods)
    - [getRelated - Retrieve Related Resources](#getrelated---retrieve-related-resources)
    - [getRelationship - Retrieve Relationship Identifiers](#getrelationship---retrieve-relationship-identifiers)
@@ -1136,6 +1137,68 @@ savepoints cannot own library writes.
 
 ---
 
+### AGGREGATE - Grouped Totals
+
+Groups the records a collection query would select and computes measures for
+each group, on ordinary and AnyAPI storage alike.
+
+#### Method Signature
+
+```javascript
+await api.resources.sales.aggregate(params, context)
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `groupBy` | string[] | Fields to group by. Omit for one row over all selected records. |
+| `measures` | object | Output names mapped to `{ count \| countDistinct \| sum \| avg \| min \| max: field }`. Only `count` accepts `'*'`. |
+| `queryParams.filters` | object | Search schema filters, validated as for `query`. |
+| `queryParams.sort` | string[] | Grouped field or measure names, `-` for descending. Grouped fields break ties. |
+| `queryParams.page` | object | `size` and `number`, for grouped results only. `size` defaults to `queryDefaultLimit` and cannot exceed `queryMaxLimit`. |
+| `transaction` | Knex transaction | Optional transaction to read in. |
+
+`sum` and `avg` take numeric fields; `min` and `max` also take strings, dates and
+times. Grouping and counting accept any scalar stored field, including belongs-to
+foreign keys. Fields that are `hidden`, virtual, computed, or that have a getter or
+`storage.serialize` are rejected, because SQL would group or sum values other than
+the ones clients read. `normallyHidden` fields are allowed.
+
+#### Return Value
+
+```javascript
+{
+  data: [{ salesperson: 'Ann', total: 150.5, count: 2 }],
+  meta: { page: { size: 20, number: 1, hasMore: false } } // grouped results only
+}
+```
+
+Both formats return these plain rows. Group values and `min`/`max` use the
+field's public representation; counts are numbers, and `sum`/`avg` are numbers
+except on decimal fields (`precision` and `scale`), which keep the driver's value.
+NULL sorts as the lowest value on every database.
+
+#### Security
+
+`aggregate` checks permissions as a `query` (`method: 'query'`, with
+`originalContext.method === 'aggregate'`). Row policies, autofilters and other
+`knexQueryFiltering` hooks run with `queryPurpose: 'aggregate'`. The aggregate reads
+only the IDs the filtered query selects, so joins added by filters or policies
+never count a record twice.
+
+#### Examples
+
+```javascript
+const totals = await api.resources.sales.aggregate({
+  groupBy: ['salesperson'],
+  measures: { total: { sum: 'amount' }, count: { count: '*' }, avg: { avg: 'amount' } },
+  queryParams: { filters: { closed: true }, sort: ['-total'], page: { size: 10 } }
+}, { subject })
+```
+
+---
+
 ## Relationship Methods
 
 ### getRelated - Retrieve Related Resources
@@ -2039,6 +2102,23 @@ database writes; it is not a persisted UI-state field. Use a setter when a
 virtual input needs to prepare other stored attributes. A `virtualFields` array
 is not the resource declaration contract. See [virtual-field behavior](GUIDE/12-field-transformations.md).
 
+#### Email and UUID Fields
+
+`type: 'email'` and `type: 'uuid'` store trimmed strings and reject values that
+are not an email address or a UUID. Filters with a text operator (`like`,
+`contains`, `startsWith`, `endsWith`) accept fragments. Registration rejects any
+type json-rest-schema cannot cast, so a misspelt type fails at `addResource`
+rather than on the first write.
+
+#### Retired Fields
+
+`retired: true` keeps a stored field readable, filterable and sortable while
+rejecting every value written to it, including `null`, with the `retired_field`
+rule. `required` and `defaultTo` no longer apply, and PUT leaves its stored value
+alone. Only stored attributes can be retired, not belongs-to fields. AnyAPI
+resources can retire fields at run time with
+[`retireKnexFields`](GUIDE/21-schema-and-migrations.md#retiring-and-migrating-anyapi-fields).
+
 #### Field Transformations
 
 Getters and setters receive a value and an injected context. Computed fields

package/docs/GUIDE/17-row-policies.md

@@ -286,6 +286,7 @@ Policies are reused for the resource selections that define externally visible d
 | --- | --- |
 | `collection` | Top-level collection query, before sorting and pagination. On AnyAPI this filtered builder is also cloned for the matching count. |
 | `count` | A separate count query, including native offset-pagination counts and standalone count helpers. |
+| `aggregate` | The records a resource `aggregate()` call groups and measures. |
 | `single` | Minimal lookup used by `get`, and by existing-record preflights for `put`, `patch`, and `delete`. |
 | `include` | A target resource loaded into JSON:API `included` data. |
 | `search-join` | A related resource used by a cross-resource or polymorphic search, reference filter, or reference sort, including intermediate search path segments. |

package/docs/GUIDE/21-schema-and-migrations.md

@@ -297,7 +297,8 @@ This optional map may cover a subset of the new stored fields; remaining fields
 use the existing allocator. An initial resource map must still cover all stored
 fields. Invalid, occupied or unknown slots and existing field names reject the
 addition. Computed and virtual fields need no slots and cannot have overrides.
-AnyAPI `alterKnexFields` remains explicitly unsupported.
+AnyAPI `alterKnexFields` remains explicitly unsupported; change a field's type with
+[`migrateField`](#retiring-and-migrating-anyapi-fields).
 
 One call uses one owned metadata transaction. Allocation failure rolls back the
 batch and leaves the runtime schema unchanged. Added getters, setters, defaults,
@@ -365,6 +366,7 @@ await api.anyapi.handleSchemaChange(change)
 
 `handleSchemaChange({ tenant, resource, version })` reloads the resource only when
 the version is newer than the published one, and returns whether it did.
+`api.anyapi.getSchemaVersion('items')` reads the stored version with one query.
 `api.resources.items.reloadSchema()` reloads unconditionally and resolves to the
 published version. Reloads are read-only: they combine the stored definition
 with this server's declaration and never re-register it.
@@ -384,6 +386,45 @@ of the tenant. A stored resource whose non-field options needed callbacks, such
 `normalizeId`, must be declared in code. To load resources on demand over HTTP,
 call `loadResource` from middleware placed before the API router.
 
+### Retiring and migrating AnyAPI fields
+
+Slots are never released while records exist, so AnyAPI retires fields instead of
+dropping them:
+
+```js
+await api.resources.contacts.retireKnexFields(['phone'])
+```
+
+A retired field keeps its slot and its values, stays readable, filterable and
+sortable, and rejects writes as a [`retired: true`](../API.md#retired-fields) field
+does. The mark is stored with the resource definition, so a server that registers
+an older declaration still listing the field keeps it retired. Its name stays taken.
+
+`migrateField` changes a field's type by copying its values into a new field:
+
+```js
+await api.resources.contacts.migrateField({
+  from: 'phone',
+  to: { name: 'phoneNumber', type: 'number', nullable: true, search: true },
+  transform: (value, { id }) => value === null ? null : Number(value.replace(/\D/g, ''))
+})
+```
+
+In one transaction it allocates a slot for the new field, converts every record's
+value, and retires the old field. Each converted value must pass the new field's
+validation; without `transform`, that validation casts the old value directly. A
+value it rejects names the record and rolls everything back. The new field must be
+a plain stored attribute: add fields with callbacks with `addKnexFields` and
+backfill them. Values are written directly, so setters, hooks and record versions
+do not run. Records are converted one by one, which suits per-tenant tables
+better than very large ones. Other servers keep accepting writes to the old field
+until the migration commits, and those writes do not reach the new field, so run
+it while nothing writes the field.
+
+Both methods bump `schema_version` and call `onSchemaChanged` once after commit.
+`AnyapiRegistry.retireFields({ tenant, resource, fields }, { transaction })` is the
+deep form of retirement.
+
 ### AnyAPI tenant instances
 
 One API instance per tenant stays cheap when the instances share their start-up work:
@@ -416,7 +457,8 @@ Slot limits belong to the database: every server reads the slot columns that
 date, 5 JSON and 5 belongsTo slots. `ensureAnyApiSchema(knex, { slots })`, or the
 plugin's `slots` option when it ensures the schema, adds missing columns. Lower
 counts never drop columns. A server whose pool is exhausted rereads the layout
-once, so a migration that adds slots takes effect without a restart.
+once, so a migration that adds slots takes effect without a restart. Indexed
+slots have their own counts; see [AnyAPI indexed fields](#anyapi-indexed-fields).
 
 On PostgreSQL, adding a nullable column without a default does not rewrite the
 table. MySQL can add columns instantly from 8.0.29; earlier versions may copy the
@@ -457,6 +499,61 @@ lookups return null for absent metadata; operations requiring that relationship
 descriptor reject a missing descriptor. Schema errors and database failures
 are distinct from a valid relationship with no matching records.
 
+### AnyAPI indexed fields
+
+All AnyAPI resources share `any_records`, so plain slots have no indexes: a filter
+or sort on one reads every record of that tenant's resource. Indexed slots
+(`indexed_string_N`, `indexed_number_N`, `indexed_boolean_N`, `indexed_date_N`)
+each carry an index on `(tenant_id, resource, slot)`. A field declared
+`indexed: true` takes the first free indexed slot of its type:
+
+```js
+await api.addResource('contacts', {
+  schema: {
+    email: { type: 'email', indexed: true, search: true },
+    score: { type: 'integer', indexed: true },
+    notes: { type: 'string' }
+  }
+})
+```
+
+New tables get 5 string, 3 number and 2 date indexed slots, and no boolean ones.
+`ensureAnyApiSchema(knex, { indexedSlots: { string: 8, boolean: 2 } })`, or the
+plugin's `indexedSlots` option, adds more; JSON slots cannot be indexed. When a
+resource has no free indexed slot of a type, registration and `addKnexFields`
+fail with an error naming `indexedSlots`. The registry rereads the layout once,
+so a migration that adds slots takes effect without a restart. Every index adds
+work to each write to `any_records`, whatever the resource, so reserve indexed
+slots for fields that large resources filter or sort on.
+
+Indexed string slots are `VARCHAR(255)`, so MySQL can index them whole. A field
+whose `max` is larger cannot take one, and longer values fail validation with a
+`storage_range` violation on every database. Lengths count characters, not bytes.
+
+Slots never move on their own. A field keeps its slot when a declaration adds or
+drops `indexed`, and a server whose declaration marks a field indexed that is
+stored in a plain slot logs a warning. To index such a field, copy it into a new
+indexed field:
+
+```js
+await api.resources.contacts.migrateField({
+  from: 'phone',
+  to: { name: 'phoneKey', type: 'string', nullable: true, indexed: true, search: true }
+})
+```
+
+Belongs-to slots are always indexed by parent ID, and `any_links` by each side's
+record ID, so child lookups, includes and many-to-many reads stay inside one
+tenant's rows.
+
+`ensureAnyApiSchema` adds missing slot columns and indexes to existing tables too.
+MySQL builds indexes in place and PostgreSQL concurrently, so writes continue; on
+PostgreSQL one server builds at a time and the others start without waiting. A
+PostgreSQL pool with a single connection builds without `CONCURRENTLY`, which
+blocks writes. Either way the build reads the whole table, so for a large
+`any_records` run `ensureAnyApiSchema` from a migration before deploying. An
+interrupted concurrent build leaves an invalid index, which the next run rebuilds.
+
 ## Live Table Snapshots
 
 Use `introspectKnexTableSnapshot()` to inspect the physical table shape:

package/docs/GUIDE/30-backend-capabilities.md

@@ -67,7 +67,9 @@ AnyAPI field additions persist slot metadata and their definitions;
 and keeps the mapping of populated fields a declaration omits; changing a populated
 field's storage type needs an explicit data migration. Servers sharing a database
 see each other's additions after a reload, notification or schema check, and slot
-limits follow the columns the database has. Old canonical temporal storage needs
+limits follow the columns the database has. Plain slots have no indexes; fields
+declared `indexed: true` take [indexed slots](21-schema-and-migrations.md#anyapi-indexed-fields),
+and belongs-to slots are always indexed. Old canonical temporal storage needs
 the documented data migration, not just a package update. See
 [table helpers and migration limits](21-schema-and-migrations.md#anyapi-across-several-servers).
 

package/docs/GUIDE/33-migrating-to-v2.md

@@ -1038,6 +1038,15 @@ Use `HookHandler<Event, AppContext>` for known hooks and
 `RuntimeHook<PluginContext>` for arbitrary plugin events; see the
 [hook guide](13-hooks-and-lifecycle.md).
 
+## Field type names
+
+`addResource` now rejects a field whose type json-rest-schema cannot cast, naming
+the field and type. Such fields used to register and then fail on their first
+write with `No casting function for type`. AnyAPI no longer lists `text`, `float`,
+`decimal`, `datetime` or `json`, which no storage could write; use `string`,
+`number`, `dateTime` and `object` or `array`. `email` and `uuid` are now real
+string types with format checks.
+
 ## Object and array attributes
 
 Declare structured fields using their public JSON type:
@@ -1476,6 +1485,17 @@ are, and omitted populated fields keep their data without being published.
 Fields added before this release that the declaration does not repeat are kept
 and published from their stored definitions.
 
+`ensureAnyApiSchema` also adds indexed slot columns (`indexed_string_N` and so on),
+indexes on `(tenant_id, resource, slot)` for them and for every belongs-to slot,
+and `(tenant_id, left_id)` and `(tenant_id, right_id)` indexes on `any_links`. On
+an existing table the plugin builds them at start-up without blocking writes, but
+the build reads the whole table: for a large one, run `ensureAnyApiSchema` in a
+migration before deploying. On AnyAPI, `indexed: true` now places fields. A new
+field declaring it takes an indexed slot, and registration fails when none is
+free, when the field is an `object` or `array`, or when a string field's `max`
+exceeds 255. Existing fields stay in their slots; see
+[AnyAPI indexed fields](21-schema-and-migrations.md#anyapi-indexed-fields).
+
 Explicit maps take effect during registration, before `createKnexTable()`.
 Repeating that method no longer re-registers the initial schema and discards
 additions. Keep the expanded declaration and complete map in app source for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",

package/plugins/core/lib/anyapi/anyapi-registry.js

@@ -1,6 +1,6 @@
 import { createKnexTransaction, readCommittedTransaction } from '../../../../lib/knex-transaction.js'
 import { applyInsertReturning, getDatabaseCapabilities } from '../querying-writing/database-capabilities.js'
-import { DEFAULT_CANONICAL_CONFIG, TYPE_TO_POOL, ensureAnyApiSchema, readSlotPools } from './schema-utils.js'
+import { DEFAULT_CANONICAL_CONFIG, INDEXED_STRING_LENGTH, TYPE_TO_POOL, ensureAnyApiSchema, readSlotPools } from './schema-utils.js'
 import { toStoredJson } from './stored-definition.js'
 import { beginWriteTransaction, commitTransaction, endWriteOperation, getOperationDiagnosticContext, rollbackAfterError, wrapUnexpectedError, wrapWriteError } from '../../../../lib/error-context.js'
 import { createEnhancedLogger } from '../../../../lib/enhanced-logger.js'
@@ -46,17 +46,13 @@ const BELONGS_TO_ALIAS = (fieldName, fieldDef) => {
   return fieldName
 }
 
-const SLOT_PATTERNS = {
-  string: /^string_(\d+)$/,
-  number: /^number_(\d+)$/,
-  boolean: /^boolean_(\d+)$/,
-  date: /^date_(\d+)$/,
-  json: /^json_(\d+)$/,
-}
+const SIMPLE_SLOT_PATTERN = /^(indexed_)?(string|number|boolean|date|json)_(\d+)$/
 
 const BELONGS_TO_ID_PATTERN = /^rel_(\d+)_id$/
 
-const slotsExhausted = pool => Object.assign(new Error(`No available ${pool} slots remaining`), { slotsExhausted: true })
+const slotsExhausted = (pool, indexed) => Object.assign(new Error(indexed
+  ? `No available indexed ${pool} slots remaining; add them with ensureAnyApiSchema(knex, { indexedSlots: { ${pool}: count } })`
+  : `No available ${pool} slots remaining`), { slotsExhausted: true })
 
 const slotPoolFor = (fieldDef = {}) => {
   if (fieldDef.belongsTo) return 'belongsTo'
@@ -65,17 +61,18 @@ const slotPoolFor = (fieldDef = {}) => {
 
 const belongsToColumns = index => [`rel_${index}_id`, `rel_${index}_type`]
 
+const isIndexedSlot = column => column.startsWith('indexed_')
+
+const slotColumnsOf = (pools, pool, indexed) => (indexed ? pools.indexed?.[pool] : pools[pool]) || []
+
 const parseSimpleSlotColumn = (column, pools) => {
-  for (const [type, pattern] of Object.entries(SLOT_PATTERNS)) {
-    const match = pattern.exec(column)
-    if (match) {
-      if (!pools[type].includes(column)) {
-        throw new Error(`Canonical slot '${column}' is out of range`)
-      }
-      return { slotType: type, slotIndex: Number(match[1]) }
-    }
+  const match = SIMPLE_SLOT_PATTERN.exec(column)
+  if (!match) throw new Error(`Invalid canonical slot column '${column}'`)
+  const [, indexed, slotType, slotIndex] = match
+  if (!slotColumnsOf(pools, slotType, Boolean(indexed)).includes(column)) {
+    throw new Error(`Canonical slot '${column}' is out of range`)
   }
-  throw new Error(`Invalid canonical slot column '${column}'`)
+  return { slotType, slotIndex: Number(slotIndex) }
 }
 
 const parseBelongsToSlots = ({ idSlot, typeSlot }, pools) => {
@@ -148,9 +145,9 @@ export class AnyapiRegistry {
     return this.#shared.get(key)
   }
 
-  ensureSchema ({ slots } = {}) {
-    return this.#once(`schema:${JSON.stringify(slots ?? null)}`, async () => {
-      await ensureAnyApiSchema(this.knex, { slots })
+  ensureSchema ({ slots, indexedSlots } = {}) {
+    return this.#once(`schema:${JSON.stringify([slots ?? null, indexedSlots ?? null])}`, async () => {
+      await ensureAnyApiSchema(this.knex, { slots, indexedSlots })
       this.#shared.delete('slots')
     })
   }
@@ -243,22 +240,16 @@ export class AnyapiRegistry {
     })
   }
 
-  async #allocate (options, method, readParams) {
-    const context = { method, [readCommittedTransaction]: true }
-    let trx; let managed = false
-    try {
-      const { tenant, resource, fields, searchSchema } = readParams()
-      Object.assign(context, { tenant, resource })
+  #allocate (options, method, readParams) {
+    return this.#changeResource(options, method, () => {
+      const params = readParams()
+      const { resource, fields, searchSchema } = params
       for (const [fieldName, { definition }] of Object.entries(fields)) {
         validateSchemaFieldNames({ [fieldName]: definition }, resource)
       }
       assertFieldNameMap(searchSchema, `added search schema in '${resource}'`)
-
-      managed = !options.transaction
-      trx = await beginWriteTransaction(context, options.transaction, ownerContext => createKnexTransaction(this.knex, ownerContext))
-      const resourceRow = await this.#lockResourceRow(trx, tenant, resource)
-      const descriptor = resourceRow && await this.#loadDescriptor(tenant, resource, trx)
-      if (!descriptor) throw new Error(`Resource '${resource}' not registered for tenant '${tenant}'`)
+      return params
+    }, async ({ trx, resourceRow, descriptor }, { fields, searchSchema }) => {
       const plan = await this.#withSlotPools(trx, pools => this.#planAllocation(descriptor, fields, pools))
 
       for (const row of plan.fieldRows) {
@@ -280,11 +271,53 @@ export class AnyapiRegistry {
           runtime.callbacks.push(...callbacks.map(path => [kind, name, ...path]))
         }
       }
-      await this.#bumpVersion(trx, resourceRow, {
+      return {
         schema_json: JSON.stringify({ ...descriptor.schema, ...plan.definitions }),
-        definition_json: JSON.stringify({ ...stored, runtime }),
-        updated_at: this.knex.fn.now()
-      })
+        definition_json: JSON.stringify({ ...stored, runtime })
+      }
+    })
+  }
+
+  /**
+   * Mark stored fields retired: they keep their slots and values, and the
+   * published schema stops accepting writes to them. Registration keeps the mark.
+   */
+  async retireFields (params, options = {}) {
+    return this.#changeResource(options, 'retireFields', () => {
+      const { tenant, resource, fields } = params || {}
+      if (!tenant || !resource || !Array.isArray(fields) || !fields.length || fields.some(field => typeof field !== 'string')) {
+        throw new Error('retireFields requires tenant, resource, and an array of field names')
+      }
+      return { tenant, resource, fields }
+    }, ({ descriptor }, { fields }) => {
+      for (const fieldName of fields) {
+        const field = descriptor.fields[fieldName]
+        if (!field) throw new Error(`Field '${descriptor.resource}.${fieldName}' has no stored slot to retire`)
+        if (field.slotType === 'belongsTo') throw new Error(`Field '${descriptor.resource}.${fieldName}' is a relationship and cannot be retired`)
+      }
+      const stored = descriptor.definition || { options: null, callbacks: [] }
+      const retired = [...new Set([...(stored.retired || []), ...fields])]
+      return { definition_json: JSON.stringify({ ...stored, retired }) }
+    })
+  }
+
+  // Run one schema change under the resource's row lock and bump its version once.
+  // `change` returns the any_resource_configs values to write.
+  async #changeResource (options, method, readParams, change) {
+    const context = { method, [readCommittedTransaction]: true }
+    let trx; let managed = false
+    try {
+      const params = readParams()
+      const { tenant, resource } = params
+      Object.assign(context, { tenant, resource })
+
+      managed = !options.transaction
+      trx = await beginWriteTransaction(context, options.transaction, ownerContext => createKnexTransaction(this.knex, ownerContext))
+      const resourceRow = await this.#lockResourceRow(trx, tenant, resource)
+      const descriptor = resourceRow && await this.#loadDescriptor(tenant, resource, trx)
+      if (!descriptor) throw new Error(`Resource '${resource}' not registered for tenant '${tenant}'`)
+      const values = await change({ trx, resourceRow, descriptor }, params)
+      await this.#bumpVersion(trx, resourceRow, { ...values, updated_at: this.knex.fn.now() })
       const updated = await this.#loadDescriptor(tenant, resource, trx)
       if (managed) {
         await commitTransaction(trx, context)
@@ -551,7 +584,13 @@ export class AnyapiRegistry {
       const row = {
         schema_json: JSON.stringify(storageSchema),
         relationships_json: JSON.stringify(relationships || {}),
-        definition_json: JSON.stringify({ options: declaration.json, callbacks: declaration.callbacks, runtime }),
+        definition_json: JSON.stringify({
+          options: declaration.json,
+          callbacks: declaration.callbacks,
+          runtime,
+          // Retirement outlives declarations that still list the field.
+          ...(stored?.retired?.length ? { retired: stored.retired } : {})
+        }),
       }
       const unchanged = previous &&
         Object.entries(row).every(([column, value]) => previous.resourceRow[column] === value) &&
@@ -715,9 +754,10 @@ export class AnyapiRegistry {
       const previous = previousDescriptor?.fields?.[entry.fieldName]
       if (entry.override || !previous || previous.slotType !== slotPoolFor(entry.fieldDef)) continue
       const columns = previous.slotType === 'belongsTo' ? belongsToColumns(previous.slotIndex) : [previous.slot]
+      // A field keeps its slot even when its `indexed` declaration changed.
       const available = previous.slotType === 'belongsTo'
         ? pools.belongsTo.includes(previous.slotIndex)
-        : pools[previous.slotType]?.includes(previous.slot)
+        : slotColumnsOf(pools, previous.slotType, isIndexedSlot(previous.slot)).includes(previous.slot)
       if (!available || columns.some(column => used.has(column))) continue
       columns.forEach(column => used.add(column))
       entry.override = previous.slotType === 'belongsTo' ? { idSlot: columns[0], typeSlot: columns[1] } : { slotColumn: previous.slot }
@@ -827,6 +867,8 @@ export class AnyapiRegistry {
         slot: row.slot_column,
         slotType: row.slot_type,
         slotIndex: row.slot_index,
+        // belongsTo slots are always indexed by parent id.
+        indexed: row.slot_type === 'belongsTo' || isIndexedSlot(row.slot_column),
         nullable: row.nullable === 1 || row.nullable === true,
         required: row.required === 1 || row.required === true,
         target: row.target_resource,
@@ -956,16 +998,29 @@ export class AnyapiRegistry {
           `Canonical slot '${slotColumn}' does not match expected type '${pool}' for field '${fieldDef.fieldName}'`
         )
       }
+      this.#assertFitsSlot(fieldDef, pool, slotColumn)
       used.add(slotColumn)
       return { slotType: pool, slotIndex, slotColumn }
     }
 
-    const slotColumn = pools[pool].find(column => !used.has(column))
+    const indexed = fieldDef.indexed === true
+    if (indexed && !pools.indexed?.[pool]) {
+      throw new Error(`Field '${fieldDef.fieldName}' is declared indexed, but AnyAPI ${pool} slots cannot be indexed`)
+    }
+    const columns = slotColumnsOf(pools, pool, indexed)
+    const slotColumn = columns.find(column => !used.has(column))
     if (!slotColumn) {
-      throw slotsExhausted(pool)
+      throw slotsExhausted(pool, indexed)
     }
+    this.#assertFitsSlot(fieldDef, pool, slotColumn)
     used.add(slotColumn)
-    return { slotType: pool, slotIndex: pools[pool].indexOf(slotColumn) + 1, slotColumn }
+    return { slotType: pool, slotIndex: columns.indexOf(slotColumn) + 1, slotColumn }
+  }
+
+  #assertFitsSlot (fieldDef, pool, slotColumn) {
+    if (pool === 'string' && isIndexedSlot(slotColumn) && Number(fieldDef.max) > INDEXED_STRING_LENGTH) {
+      throw new Error(`Field '${fieldDef.fieldName}' allows ${fieldDef.max} characters, but indexed string slots hold at most ${INDEXED_STRING_LENGTH}`)
+    }
   }
 
   #assignBelongsTo (fieldDef, used, canonicalOverride, pools) {