Référence Typologie — types de colonnes & agrégation (roll-up)

La Typologie est la façon dont une colonne Gold déclare quel genre de valeur elle est — une grandeur mesurée, un identifiant, un rang ordonné, une catégorie. Chaque colonne porte son type dans le bloc column_types: du YAML d’entité, frère du registre de rôles columns:.

Un nombre sans type déclaré est non déclaré — ce n’est pas une licence pour deviner. Le compilateur (typologycheck.py) vérifie chaque déclaration ; le KLS ne porte que des données. Les types sont des déclarations, pas des données d’exécution.

Contexte conceptuel : Sense 54 — The Typology et Sense 53 — The Codex.

Où il se déclare

# entities/<entity>.yaml
column_types:
  material_id:   { kind: identifier, subkind: foreign_key, references: materials.material_id }
  quantity:      { kind: quantity, standard: null, rollup: additive }
  unit_price:    { kind: quantity, standard: iso_4217, unit: CHF, rollup: non_additive }
  level:         { kind: ordinal }              # une profondeur d'arbre — ordonnée, non sommable
  billing_status:{ kind: category }
  billing_time:  { kind: temporal, subkind: instant, standard: iso_8601 }

Chaque entrée déclare exactement un kind, plus des raffinements optionnels.

Les huit genres

Chaque colonne en est exactement un :

Genre	Ce que c’est	Exemples
quantity	Une valeur mesurée avec des unités et (souvent) une incertitude	mass_g, temperature_c, unit_price
identifier	Une clé qui identifie une entité — primaire, métier, externe, étrangère	sensor_id, serial_number, iso_country_code
category	Une valeur tirée d’un vocabulaire borné et non ordonné	status, event_type, region_name
ordinal	Une valeur tirée d’une échelle ordonnée — rang / grade / niveau. Ordonnable mais non sommable	level (profondeur de hiérarchie), severity_rank
temporal	Une valeur de forme temporelle — instant, intervalle, durée, période	phenomenon_time, deployment_window
boolean	Vérité à deux valeurs (troisième état optionnel)	is_active, has_calibration
narrative	Texte non contrôlé destiné à la lecture humaine, pas au regroupement ni au filtrage	notes, interpretation
geometry	Données spatiales structurées avec un système de référence de coordonnées	boundary_geojson

La frontière entre category et ordinal est l’ordre : une catégorie est un ensemble simple (statuts, types d’événement) ; un ordinal est une échelle classée où min/max/median ont un sens, mais pas une somme (rang 1 + rang 2 ≠ rang 3).

Champs de déclaration

Champ	S’applique à	Signification
kind	tous	L’un des huit genres ci-dessus (requis)
subkind	tous	Raffine le genre — identifier.foreign_key, temporal.instant, geometry.polygon
standard	quantity, temporal, geometry	Un identifiant de standard Codex (ucum, iso_4217, iso_8601, rfc_7946_geojson). Le vérificateur impose qu’il lie légalement le genre
unit	quantity	Unité statique — UCUM pour les grandeurs physiques, un code ISO 4217 (CHF) pour la monnaie
unit_column	quantity	Unité polymorphe — portée par ligne dans une colonne sœur (données en forme de journal)
references	identifier.foreign_key	Cible de clé étrangère sous la forme entity.column
derived_from	quantity	{entity, column, standard} — une arête typée : cette colonne est produite à partir d’une autre par une conversion citée
rollup	quantity	Politique d’agrégation en remontant une hiérarchie — voir ci-dessous

Roll-up — comment une grandeur s’agrège en remontant une hiérarchie

rollup répond à : quand cette colonne est résumée sur les enfants d’un nœud de hiérarchie (le Level Ladder — voir Sense 42 — The Landscape), quelle est l’agrégation honnête ? C’est une propriété du type (intensif vs extensif), pas une configuration d’affichage — elle ne cascade jamais et ne surcharge jamais.

Valeur	Agrégat	À utiliser pour
additive	SUM	Grandeurs extensives — comptages, charges, totaux monétaires. Sommer est honnête
averageable	AVG	Grandeurs intensives qui se moyennent — un taux déjà normalisé par unité
non_additive	ne roule pas	Prix, extrêmes (min/max), ratios, pourcentages, moyennes pré-calculées. Ni la somme ni la moyenne ne sont honnêtes
distinct_count	COUNT(DISTINCT …) recalculé sur le sous-arbre	Valeurs de groupe qui exigent un recalcul, pas l’agrégation des parties (distinct-d’une-union ≠ somme-des-distincts)

Un total inter-nœuds et un pourcentage de part n’ont de sens que pour additive — le « total » d’un ensemble de moyennes ou de comptages distincts n’est pas leur somme.

Un rollup non déclaré ne roule pas

Laisser rollup de côté sur une grandeur n’est pas une instruction de sommer. Un rollup non déclaré signifie que la grandeur ne remonte pas du tout — car deviner est le mauvais geste. Une déclaration signifie qu’une personne a décidé, au dossier ; un défaut silencieux signifie que le moteur a décidé, invisiblement, là où un nombre faux ressemble exactement à un nombre juste. Voir le principe « aucun défaut comportemental silencieux » (Sense 54 — The Typology). La couverture de typologie compte une grandeur sans rollup comme une lacune, de sorte qu’une grandeur qui ne roule pas est visible, pas seulement silencieusement inerte.

ordinal, category, identifier, etc. ne portent pas de rollup — ils ne sont pas sommés en remontant une hiérarchie.

Couverture

jin make cuit une table typology_coverage réservée à l’inspecteur, par entité : colonnes typées / non typées / fantômes et un pourcentage de couverture. Une couverture complète — chaque colonne Gold typée, chaque rollup de grandeur déclaré — est une exigence d’ingénierie de données, pas une métrique à optimiser. Vous inspectez le type complet d’une seule colonne au point d’usage via le Column Passport.

Commandes

# Valider chaque déclaration column_types (kind + liaison Codex + vocabulaire rollup)
python3 scripts/typologycheck.py
python3 scripts/typologycheck.py entities/cases.yaml   # un ou plusieurs fichiers explicites

# Cuire les tables d'inspecteur (s'exécute dans `jin make` en étape post-dbt)
python3 scripts/typologycompile.py --kls <kls> --tenant <t> --entities-root <afs>/entities

Voir aussi

• Référence YAML Entity — le fichier d’entité complet, dont column_types: est un bloc
• Sense 54 — The Typology — la justification de conception
• Sense 53 — The Codex — le registre des standards
• Inspecter — Portraits & Passports — lire le type d’une colonne au point d’usage