Rédiger des contrôles de qualité des données

Un contrôle est une assertion sur une table ou une vue warehouse. Il se compile en une requête HogQL count-only et passe quand il trouve zéro ligne défaillante — la même sémantique que dbt test. Les lignes défaillantes ne sont jamais stockées ; seuls les counts et la requête compilée le sont, donc pour voir les lignes incriminées, vous relancez vous-même la requête stockée.

row_count est l'exception. Il passe quand le count observé est dans ses limites min/max configurées, donc son failed_row_count revient null et sa requête stockée retourne ce seul count, pas les lignes défaillantes. Lisez le count observé pour le juger plutôt que de chercher des lignes correspondantes.

Les lectures passent par SQL (system.information_schema.data_quality_*) ; les écritures et exécutions passent par les data-quality MCP tools.

Avant d'écrire quoi que ce soit : regardez

Deux requêtes vous épargnent les deux erreurs les plus courantes — dupliquer un contrôle et vérifier une colonne inexistante.

-- What is already covered?
SELECT name, subject_name, column_name, check_type, config, severity, last_status
FROM system.information_schema.data_quality_checks
WHERE subject_name = 'orders'

-- What columns are there, and what do they mean?
SELECT column_name, data_type, description
FROM system.information_schema.columns
WHERE table_name = 'orders'

Recréer un contrôle byte-identique est une no-op inoffensive — les contrôles sont indexés par une empreinte du subject, du type, de la colonne et de la config, donc une création identique fait un upsert. Un quasi-doublon n'est pas inoffensif : il double le bruit pour qui lit les résultats. Si l'assertion d'un contrôle existant est proche mais fausse, créez le contrôle corrigé et supprimez l'ancien — l'assertion (type, colonne, config) est immuable et le subject est fixé par l'URL, donc une mise à jour qui essaie de les changer est rejetée. La mise à jour est uniquement pour les métadonnées, la sévérité et la propriété.

Choisir les contrôles

Visez une poignée qui attraperait vraiment une régression réelle, pas une couverture générale. Un modèle avec vingt contrôles que personne ne lit est pire que trois qui échouent significativement.

Commencez par ceux-ci, à peu près dans cet ordre :

not_null sur les colonnes dont les joins et filtres aval dépendent. Le contrôle de plus haute valeur. Une clé de jointure null supprime silencieusement les lignes.
unique sur ce que le modèle prétend être son grain. Si orders est une ligne par commande, déclarez-le.
relationships sur les clés étrangères. Attrape le join qui a silencieusement cessé de correspondre après un changement en amont.
accepted_values sur les colonnes status et category dont la logique aval se branche dessus.
freshness sur la colonne timestamp de tout ce qui se synchronise. Attrape un pipeline mort, qu'aucun contrôle au niveau des lignes ne trouvera.
row_count bounds quand vous connaissez la plage plausible. Bon pour attraper une synchro tronquée.
custom_sql uniquement quand rien ci-dessus n'exprime l'invariant — ex. arithmétique cross-colonne (select 1 from orders where total != subtotal + tax). Chaque ligne qu'il retourne compte comme un échec.

Appelez posthog:data-quality-check-types pour le schéma de config exact de chaque type plutôt que de deviner.

Les contrôles vivent sur le subject qu'ils auditent : créez-les avec data-quality-check-create-on-view (paramètre saved_query_id) ou data-quality-check-create-on-table (paramètre table_id).

Sévérité et déclencheurs

Sévérité est une décision sur les conséquences, pas sur la confiance. Utilisez error quand l'échec signifie que les nombres aval ne devraient pas être fiables — ces échecs marquent le subject comme failing et notifient. Utilisez warn pour les choses intéressantes à surfacer que personne n'agirait aujourd'hui. Dans le doute, warn est le défaut plus sûr : un contrôle error qui crie au loup fait ignorer tout.

Déclencheurs — il n'y a rien à planifier. Un contrôle s'exécute quand les données de son subject changent : les contrôles d'une vue matérialisée s'exécutent dans le cadre de son rafraîchissement (et, quand l'équipe active la gate, un rafraîchissement dont les contrôles de sévérité error échouent n'est pas publié), les contrôles d'une table source s'exécutent après chaque synchro terminée, et les contrôles d'une vue ordinaire s'exécutent quand son DAG s'exécute. Les contrôles sur une vue en dehors de tout DAG s'exécutent uniquement sur demande.

Vérifiez ce que vous avez écrit

Rédigez, exécutez une fois, lisez le résultat. Un contrôle qu'on n'a jamais exécuté est une supposition.

posthog:data-quality-check-create-on-view (ou -on-table)
posthog:data-quality-check-run-on-view (ou -on-table) — retourne une suite run
Pollchez system.information_schema.data_quality_check_runs (ou posthog:data-quality-check-results-on-view/-on-table) pour le résultat

Un résultat failed à la première exécution est le cas intéressant : soit vous avez trouvé de vraies mauvaises données, soit l'assertion est fausse. Prenez la compiled_query du run, exécutez-la avec posthog:execute-sql, et regardez ce qu'elle a vraiment correspond avant de signaler quoi que ce soit. Cette compiled_query vient de posthog:data-quality-check-results-on-view/-on-table ; le poll information_schema à l'étape 3 ne la retourne pas. Un résultat errored n'est jamais un problème de données — la requête n'a pas pu s'exécuter du tout, généralement une typo de nom de colonne ou un subject qui n'existe plus.

Juger une source avant de l'utiliser

Quand une analyse dépend d'une table ou d'une vue warehouse, vérifiez d'abord son verdict :

SELECT subject_name, health, checks_total, checks_failing, last_run_at
FROM system.information_schema.data_quality_health

failing — un contrôle de sévérité error a trouvé de mauvaises données. Dites-le dans votre réponse ; ne l'utilisez pas silencieusement.
erroring — un contrôle n'a pas pu s'exécuter. Les données peuvent être correctes, mais personne ne les surveille.
warn — uniquement des échecs de sévérité warn. Utilisable, vaut la peine d'être mentionné.
healthy — les contrôles se sont exécutés et ont passé.
unknown / absent — pas de contrôles, ou aucun n'a s'exécuté. L'absence d'échecs n'est pas une preuve de santé.

Pour l'historique derrière un verdict, system.information_schema.data_quality_check_runs porte des exécutions récentes avec observed_value enregistrée sur les passes aussi, donc vous pouvez voir quand un nombre a commencé à dériver plutôt que juste que c'est faux maintenant.

Connexe

setting-up-data-catalog — ce que les données signifient : métriques, marques de confiance, relations.
querying-posthog-data — la découverte de schéma et les règles HogQL que ces requêtes suivent.

authoring-data-quality-checks