Aller au contenu

Documents, doctypes et projections

Facet découpe un enregistrement en trois parties. Le doctype déclare la forme. Le document porte les données. La projection garde l’état que les lectures utilisent. Lisez cette page pour comprendre comment les trois parties se lient, et ce que coûte cette conception.

Doctype: the schema Doctype: the schema

Le doctype est le schéma. Un doctype est un type d’enregistrement typé dans un domaine, comme hr.Employee. Sa définition déclare les champs et leurs types, les actions nommées, les périmètres de lignes et les relations enfants. La définition est elle-même un document — core.DocType — donc vous l’enregistrez et la versionnez par le même pipeline que n’importe quel autre enregistrement.

Le document est la donnée. Un document est une instance JSON de son doctype. PostgreSQL le stocke en JSONB. Les routes de documents couvrent le cycle completà : POST crée, GET lit, PATCH applique un patch par fusion profonde, DELETE passe le document en soft delete, et une route de restauration ramène un document supprimé. Une mise à jour ne stocke que le diff calculé, jamais le corps complet.

La projection est l’état lisible. Chaque écriture ajoute une ligne au journal des mutations. Un trigger PostgreSQL applique cette ligne à la projection dans la même transaction. La projection porte le contenu, le nom d’affichage, le texte de recherche et les liens entrants. Les lectures n’analysent jamais le journal. Elles lisent la projection, avec les périmètres de lignes de l’appelant appliqués en SQL.

L’id de la dernière mutation est l’ETag. Chaque ligne de projection stocke l’id de sa dernière mutation dans sa colonne state. Une lecture d’un seul document renvoie cette valeur dans l’en-tête de réponse ETag — un marqueur de version pour la réponse. Renvoyez-le avec If-None-Match : un document inchangé répond 304 Not Modified. Un ETag différent à une lecture ultérieure signifie qu’une autre écriture est passée entre-temps. Les écritures concurrentes sur un même document sont sérialisées par des verrous de ligneà ; s’il reste une situation de course, elle répond 409, et le client rejoue la même requête.

Deux colonnes de la projection viennent de modèles Jinja2 définis sur le doctype. Jinja2 est un langage de modèles venu de l’écosystème Pythonà ; Facet en fait le rendu en Crystal, au moment de la mutation.

Colonne Exemple de modèle Ce qu’elle porte
display_name "{{ first_name }} {{ last_name }}" Le libellé du document, tronqué à 255 caractères
search "{{ first_name }} {{ last_name }} {{ email }}" Le corpus de recherche, normalisé puis tronqué à 256 caractères

Dans un modèle display_name, un champ référence est remplacé par le libellé stocké du document cible, et un champ monétaire est rendu sous la forme USD 120000. La troisième colonne dérivée, links, n’a pas de modèle. Le chemin d’écriture parcourt les champs référence et enregistre les liensà ; la page détail les liste comme liens entrants.

Les modèles sont rendus à chaque écriture. Un document écrit avant un changement de modèle garde ses anciennes valeurs jusqu’à la prochaine écriture sur lui.

Le compromis. La projection copie le contenu pour la vitesse de lectureà : un accès à une ligne indexée par document. Chaque écriture en paie le prix — l’ajout au journal, la mise à jour de la projection et les colonnes dérivées.

Deux endroits pour une seule forme. La logique dérivée se trouve dans les modèles, à l’écart des définitions de champsà : l’auteur d’un doctype maintient donc deux endroits pour une seule forme.

Les tombstones gardent leur payload un temps. Un soft delete garde le contenu, les liens et le texte de recherche sur la tombstone. La corbeille peut encore afficher la ligne. Un cron efface ce payload après la fenêtre de rétention configuréeà ; seul le libellé survit.