Documents, doctypes and projections
Facet splits a record into three parts. The doctype declares the shape. The document holds the data. The projection keeps the state that reads use. Read this page to see how the three parts connect, and what the design costs.
Explanation
Section titled “Explanation”The doctype is the schema. A doctype is a typed record type inside a
domain, such as hr.Employee. Its definition declares the fields and their
types, the named actions, the row scopes, and the child relationships. The
definition is itself a document — core.DocType — so you register and
version it through the same pipeline as any other record.
The document is the data. A document is one JSON instance of its
doctype. PostgreSQL stores it as JSONB. The document routes give the full
cycle: POST creates, GET reads, PATCH deep-merges a patch, DELETE
soft-deletes, and a restore route brings a deleted document back. An update
stores only the computed diff, never the full body.
The projection is the readable state. Every write appends one row to the mutation log. A PostgreSQL trigger applies that row to the projection in the same transaction. The projection holds the content, the display name, the search text, and the backlinks. Reads never parse the log. They read the projection, with the caller’s row scopes applied as SQL.
The last mutation id is the ETag. Each projection row stores the id of
its last mutation in its state column. A single-document read returns that
value as the ETag response header — a version tag for the response. Send it
back with If-None-Match, and an unchanged document answers 304 Not Modified. A different ETag on a later read means another write landed in
between. Concurrent writers to one document are serialized by row locks; the
remaining race answers 409, and the client retries the same request.
Derived columns
Section titled “Derived columns”Two of the projection’s columns come from Jinja2 templates on the doctype. Jinja2 is a template language from the Python ecosystem; Facet renders it in Crystal, at mutation time.
| Column | Example template | What it holds |
|---|---|---|
display_name |
"{{ first_name }} {{ last_name }}" |
The document’s label, truncated to 255 characters |
search |
"{{ first_name }} {{ last_name }} {{ email }}" |
The search corpus, folded and truncated to 256 characters |
In a display_name template, a reference field resolves to the target
document’s stored label, and a money field renders as USD 120000. The third
derived column, links, has no template. The write path walks the reference
fields and records the edges; the show page lists them as backlinks.
Templates render on every write. A document written before a template change keeps its old values until the next write lands on it.
The trade-off. The projection copies content for read speed: one indexed row lookup per document. Every write pays for it — the log append, the projection update, and the derived columns.
Two places for one shape. The derived logic lives in templates, away from the field definitions, so a doctype author maintains two places for one shape.
Tombstones keep their payload for a while. A soft delete keeps the content, the links and the search text on the tombstone. The trash listing can still show the row. A cron job clears that payload after the configured retention window; only the label survives.
Related
Section titled “Related”- Designing doctypes — how to declare fields, actions and templates.
- Build — the how-to pages for authoring domains.
- Schema evolution — what happens to stored documents when a definition changes.
- The mutation log — the append-only history behind every projection.
- Internals on GitHub: document.md, doctype-system.md, templating.md.