Déboguer les contrôles de qualité des données échoués

Une exécution de contrôle se termine dans l'un de quatre états. Lisez d'abord l'état, car il décide où se trouve le problème :

Statut	Signification	Où regarder
`failed`	La requête s'est exécutée et l'assertion a trouvé de mauvaises données	Les données, ou l'assertion elle-même
`errored`	La requête n'a pas pu s'exécuter, rien n'a été jugé	Le texte d'erreur (jamais un problème de données)
`skipped`	Le sujet a disparu	Si la table ou la vue existe toujours
`passed`	L'assertion s'est maintenue	Rien

Les contrôles row_count et freshness jugent observed_value, pas failed_row_count. Un row_count échoué signifie que le nombre s'est situé en dehors de ses limites. Un freshness échoué signifie que la ligne la plus récente est plus ancienne que la limite.

Quand utiliser cette compétence

Un contrôle ou un sujet affiche failed ou errored et l'utilisateur veut savoir pourquoi
L'utilisateur veut voir les lignes qu'un contrôle a trouvées
L'exécution la plus récente d'une vue matérialisée affiche une erreur qui commence par Not published:
Une vue a continué à servir des données anciennes après une actualisation, et la porte de qualité des données est activée
Une autre compétence (authoring-data-quality-checks ou auditing-warehouse-view-health) a trouvé un contrôle échoué ou une vue bloquée et l'a transmis

Outils disponibles

Outil	Objectif
`posthog:data-quality-check-results`	Les exécutions récentes d'un contrôle, avec `compiled_query`, `error` et la configuration qu'il a exécutée
`posthog:execute-sql`	Réexécuter le `compiled_query` d'une exécution pour voir les lignes échouées
`posthog:data-quality-check-run`	Exécuter un contrôle maintenant
`posthog:data-quality-check-update`	Corriger une assertion ou modifier sa sévérité
`view-get`	La définition et l'état d'une vue
`view-run-history`	Les exécutions de matérialisation d'une vue et leurs erreurs
`view-run`	Matérialiser une vue à nouveau

Pour trouver les contrôles échoués, interrogez system.information_schema.data_quality_checks pour last_status IN ('failed', 'errored'), ou system.information_schema.data_quality_health pour le verdict d'un sujet.

Flux de travail

Étape 1 : Lire l'exécution

Appelez posthog:data-quality-check-results pour le contrôle. Sur l'exécution la plus récente, lisez :

status et error
check_config et check_severity : ce que l'exécution a affirmé, ce qui peut différer du contrôle actuel
compiled_query : HogQL qui sélectionne les lignes échouées. Pour row_count il retourne le nombre à la place, jugez ce contrôle par observed_value.
audited_staged_refresh : true quand l'exécution faisait partie d'un audit contrôlé d'une actualisation avant sa publication. Une exécution errée peut aussi la porter, lisez d'abord status.

La rétention efface compiled_query après 30 jours. Pour une exécution plus ancienne, exécutez le contrôle à nouveau.

Étape 2 : Regarder les lignes échouées

Exécutez compiled_query avec posthog:execute-sql. Un compiled_query vide signifie qu'il n'y a rien à rejouer : la rétention l'a effacé, ou une exécution contrôlée n'a pas pu lire la définition de la vue. Regardez ce qu'il a trouvé avant de signaler quoi que ce soit. Un échec signifie l'une de deux choses : les données sont mauvaises, ou l'assertion est incorrecte. Les lignes vous diront laquelle.

Quand audited_staged_refresh est true, la requête ne lit pas la table publiée. Elle contient la définition de la vue dans une clause WITH et lit les tables source de la vue maintenant. Les sources peuvent avoir changé depuis l'exécution, donc les lignes et le nombre peuvent différer de l'exécution. Une requête qui retourne zéro lignes maintenant ne prouve pas que l'actualisation était propre. Comparez avec failed_row_count sur l'exécution.

Étape 3 : Lire une exécution errée

Une exécution errée n'a pas jugé les données. Faites correspondre le texte d'erreur :

Texte d'erreur	Cause et correction
`The staged files could not be read, so this data was not audited.`	La porte n'a pas pu accéder à l'actualisation avant la publication. L'actualisation se publie sans verdict. Exécutez la vue à nouveau.
`Metric checks cannot audit staged data.`	Un contrôle de métrique faisait partie d'une actualisation contrôlée. Il s'exécute selon son propre calendrier à la place.
`The check query returned no rows.`	La requête d'agrégat n'a retourné rien. Exécutez le contrôle à nouveau et signalez-le s'il se répète.
`A check that reads another subject needs an initiator or author…`	Une exécution automatique d'un contrôle `custom_sql` ou `relationships` n'a pas d'utilisateur pour s'exécuter. Une exécution manuelle fonctionne. Une modification de l'assertion du contrôle fait de l'éditeur son auteur.
Une erreur HogQL ou ClickHouse	Une typo de nom de colonne, une inadéquation de type, ou une requête qui a dépassé le délai. Corrigez la configuration, ou ajoutez `lookback_hours`.

Deux messages viennent avec skipped : The subject was deleted. et The subject no longer resolves. La table ou la vue a disparu. Supprimez le contrôle ou pointez-le vers le remplacement.

Étape 4 : Comprendre une actualisation bloquée

Quand l'équipe active « Block materialization on failing checks », les contrôles de sévérité erreur d'une vue matérialisée s'exécutent sur chaque actualisation avant sa publication. Si l'un échoue :

L'exécution de la vue affiche une erreur qui commence par Not published: (voir view-run-history).
La version précédente de la vue continue de servir les requêtes.
Les vues en aval dans le même DAG sont ignorées pour cette exécution.
Le calendrier de la vue n'est pas mis en pause. La prochaine actualisation programmée exécute les contrôles à nouveau.

Les contrôles de sévérité warn ne bloquent jamais une actualisation.

Étape 5 : Récupérer

Corrigez la cause, puis prouvez-le :

Corrigez les données en amont, ou corrigez l'assertion avec posthog:data-quality-check-update. Si l'échec est réel mais ne doit pas bloquer l'actualisation, changez severity en warn.
Pour une vue bloquée, appelez view-run pour la matérialiser à nouveau. Sinon appelez posthog:data-quality-check-run.
Lisez posthog:data-quality-check-results à nouveau et confirmez que l'exécution la plus récente a réussi.

Points importants

Ne modifiez pas la sévérité ou l'assertion d'un contrôle juste pour le rendre vert. Confirmez d'abord avec l'utilisateur.
errored n'est jamais une preuve de mauvaises données, et passed sur une table vide n'est pas une preuve de bonnes données.
Un contrôle rapporte contre son sujet, mais une requête custom_sql peut lire d'autres tables. Lisez la requête avant de blâmer le sujet.

Associé

authoring-data-quality-checks : écrire et choisir des contrôles
auditing-warehouse-view-health : trouver les vues matérialisées défaillantes

debugging-failed-data-quality-checks