Data model & realtime

Typed collections and schema

Gives records a declared shape, with validation and unique constraints that hold under concurrent writers, without a separate schema migration tool.

Available in previewEngine edition 5f8ea3af

What it does

A collection is a named set of typed fields. Its definition is stored in the same log as its records, so the schema survives restarts and travels with backups. Records are validated against it on every write, and unique constraints are enforced by the writer rather than by a pre-check.

How it works

A collection definition lists fields, indexes, access rules and optional settings, and is persisted as an entity of kind collection. Records are stored as entities of kind coll:<name>; for a project, both kinds and ids carry a project prefix so one project cannot name another project's records. Field types are text, longtext, number, integer, bool, email, url, date, json, select, relation and file. Validation covers required fields, minimum and maximum length or value, regular expressions on text, and the allowed options of a select field.

Unique constraints are declared as a field flag or as a unique index. They are enforced by reservation: the unique value is claimed by a small reservation entity written in the same optimistic transaction as the record. Two concurrent writers that try to claim the same value cannot both commit; the reservation is released when the owning record is updated or deleted, and a test checks that reservations survive a restart. Null values are not constrained.

The HTTP surface is /v1/collections. GET lists and POST creates or replaces a definition; /{name} reads or deletes one; /{name}/indexes lists, adds and removes indexes; /{name}/records lists and creates records, and /{name}/records/{id} reads, patches and deletes one. The same collections are also reachable through the PostgREST-style /rest/v1/{table} layer. Defining or changing a collection needs a service key or an administrator, while reading and writing records follows the collection's access rules.

A collection can name fields whose text is embedded on write, so vector and hybrid queries need no client-side embedding step; the embedding provider is configured separately. Collection definitions can be exported and imported as JSON through the admin routes.

Reads of a definition go through checked paths: a storage fault or an active recovery fence is reported as an error, never as "no such collection", so a fault cannot silently turn off validation or access checks.

Where you reach it

  • HTTPGET, POST /v1/collections; GET, DELETE /v1/collections/{name}
  • HTTPGET, POST /v1/collections/{name}/indexes; DELETE /v1/collections/{name}/indexes/{index}
  • HTTPGET, POST /v1/collections/{name}/records; GET, PATCH, DELETE /v1/collections/{name}/records/{id}
  • HTTPGET /admin/collections/export, POST /admin/collections/import

Limits

  • A collection can carry a declared data contract, but contracts are not enforced at any boundary yet; see the data contracts entry.
  • There is no in-place migration tool for existing records: replacing a collection definition does not rewrite stored records. The online schema evolution engine is library code that the server does not wire.
  • Unique constraints skip null values, and compound unique indexes skip a record when any member field is null.

Evidence

  • On this siteHTTP API reference
  • TestsCovered in the engine repository by 25 schema tests (round trip, validation, unique constraints and atomic reservations that survive restart, field projection), checked-read tests for corrupt definitions, fences and store faults, and the HTTP tests of the collection and REST routes

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.