:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""Authoring and triggering data quality checks.
Creation is an upsert on the fingerprint (KTD: agents re-propose the same check constantly, and a
duplicate row is worse than a no-op). Check runs go through Temporal. Metric authoring validates
the composed SQL without executing the query.
"""
import asyncio
from collections.abc import Callable, Iterable
from dataclasses import asdict
from datetime import UTC, datetime
from functools import partial
from operator import attrgetter
from typing import Any
from uuid import UUID, uuid4
from django.conf import settings
from django.db import IntegrityError, transaction
from django.db.models import Q, QuerySet
from temporalio.common import RetryPolicy
from posthog.dataclasses import frozen
from posthog.models.team import Team
from posthog.models.user import User
from posthog.temporal.common.client import sync_connect
from ..facade.contracts import CHECK_SUITE_WORKFLOW_NAME
from ..facade.enums import SubjectHealth, SubjectStatus, SubjectType, SuiteRunStatus, SuiteRunTrigger
from ..models import DataQualityCheck, DataQualityCheckRun, DataQualitySuiteRun
from . import posthog_tables
from .compiler import related_subject_ref
from .contracts import SubjectRef
from .errors import (
CheckConfigError,
ConcurrentEditError,
DuplicateDefinitionError,
NameConflictError,
SubjectUnresolvableError,
)
from .exceptions import CheckNameConflict
from .health import CheckStatusRow, roll_up_health
from .registry import get_spec
from .schedules import provision_schedule
from .serialization import canonical_config, compute_fingerprint
from .spec import CheckConfig
from .subject_schedules import SCHEDULE_TYPES
from .subjects import posthog_table_column_is_selectable, resolve_subject, subject_column_type
_UPSERTABLE_FIELDS = (
"name",
"description",
"severity",
"enabled",
"tags",
"created_source",
"ai_model",
"confidence",
"reasoning",
"owner",
)
# What the fingerprint hashes: change any of these and the check asserts something else.
_ASSERTION_FIELDS = ("check_type", "column_name", "config")
_EDITABLE_FIELDS = (*_UPSERTABLE_FIELDS, *_ASSERTION_FIELDS)
_MAX_EDIT_ATTEMPTS = 3
_definition_identity = attrgetter("subject_type", "subject_uuid", "fingerprint")
def _edits_the_assertion(fields: Iterable[str]) -> bool:
"""Whether a write proposes a new assertion, rather than only presentation fields."""
requested = set(fields)
return any(field in requested for field in _ASSERTION_FIELDS)
def subject_filter(subject_type: str, subject_uuid: str | UUID) -> dict[str, Any]:
"""The FK kwargs for whichever subject kind this is."""
if subject_type == SubjectType.TABLE:
return {"table_id": subject_uuid}
if subject_type == SubjectType.VIEW:
return {"saved_query_id": subject_uuid}
if subject_type == SubjectType.METRIC:
return {"metric_id": subject_uuid}
if subject_type == SubjectType.POSTHOG_TABLE:
entry = posthog_tables.by_id(subject_uuid)
if entry is None:
raise ValueError(f"Unknown PostHog table: {subject_uuid}")
return {"posthog_table": entry.name}
raise ValueError(f"Unknown check subject type: {subject_type}")
def validate_check(
team: Team,
subject_type: str,
subject_uuid: str,
check_type: str,
column_name: str,
config: dict[str, Any],
) -> CheckConfig:
"""Reject a check the compiler could never run, at authoring time rather than at run time.
Returns the parsed config so callers do not validate twice, and so the fingerprint hashes the
normalized form rather than whatever representation the request happened to use.
"""
spec = get_spec(check_type)
if SubjectType(subject_type) not in spec.subject_types:
raise CheckConfigError(f"A {check_type} check cannot target a {subject_type}. Choose a supported check type.")
parsed = spec.validate(config, column_name)
subject = resolve_subject(team.id, subject_type, subject_uuid)
if not subject.exists:
raise SubjectUnresolvableError(f"No {subject_type} with id {subject_uuid} in this project.")
if subject.subject_type == SubjectType.METRIC and column_name:
raise CheckConfigError("A check on a metric takes no column. Remove the column and save again.")
if parsed.lookback_hours is not None and not subject.time_column:
raise CheckConfigError(f"A {subject_type} has no time column, so it cannot take a lookback_hours window.")
_require_selectable_posthog_column(subject, column_name)
spec.referenced_table_names(parsed, subject)
# After the subject resolves, so the column type is only looked up for a check that could run.
parsed = spec.coerce_to_column(parsed, subject_column_type(team.id, subject_type, subject_uuid, column_name))
related = related_subject_ref(check_type, config)
if related:
related_subject = resolve_subject(team.id, *related)
if not related_subject.exists:
raise SubjectUnresolvableError(f"The referenced {related[0]} {related[1]} does not exist.")
# Same rule as the subject's own window above, on the second subject a relationships check
# reads. ``build`` keeps its own guard, so this is refused at authoring time rather than on
# every run.
if getattr(parsed, "to_lookback_hours", None) is not None and not related_subject.time_column:
raise CheckConfigError(
f"The referenced {related[0]} has no time column, so it cannot take a to_lookback_hours window."
)
_require_selectable_posthog_column(related_subject, getattr(parsed, "to_column", ""))
return parsed
def _require_selectable_posthog_column(subject: SubjectRef, column_name: str) -> None:
if subject.subject_type != SubjectType.POSTHOG_TABLE or not column_name:
return
if not posthog_table_column_is_selectable(subject.subject_uuid, column_name):
raise CheckConfigError(f"{subject.name} has no column named {column_name}. Pick one of its listed columns.")
def upsert_check(
*,
team: Team,
user: User | None,
subject_type: str,
subject_uuid: str,
check_type: str,
column_name: str,
config: dict[str, Any],
**optional: Any,
) -> tuple[DataQualityCheck, bool]:
"""Create the check, or refine the one already carrying this fingerprint. Returns (check, created)."""
parsed = validate_check(team, subject_type, subject_uuid, check_type, column_name, config)
subject = resolve_subject(team.id, subject_type, subject_uuid)
# Stored in the same canonical form the fingerprint hashes, so a created check and one edited
# into the same definition are indistinguishable afterwards.
canonical = canonical_config(parsed)
fingerprint = compute_fingerprint(
subject_type=subject_type,
subject_uuid=str(subject_uuid),
check_type=check_type,
column_name=column_name,
config=canonical,
)
existing = _find_by_fingerprint(team.id, subject_type, subject_uuid, fingerprint)
fields = {key: value for key, value in optional.items() if key in _UPSERTABLE_FIELDS and value is not None}
# Checked here rather than before the fingerprint lookup: re-proposing an identical named check
# must upsert, and a name conflict with *itself* is not a conflict.
ensure_name_available(team.id, fields.get("name") or "", exclude_id=existing.id if existing else None)
if existing is None:
try:
# Savepoint so a lost race rolls back cleanly instead of poisoning an outer transaction.
with transaction.atomic():
check = DataQualityCheck.objects.for_team(team.id).create(
team=team,
created_by=user,
subject_type=subject_type,
subject_name=subject.name,
subject_status=SubjectStatus.ACTIVE,
check_type=check_type,
column_name=column_name,
config=canonical,
fingerprint=fingerprint,
**subject_filter(subject_type, subject_uuid),
**fields,
)
if check.subject_type in SCHEDULE_TYPES:
transaction.on_commit(
partial(provision_schedule, check.team_id, subject_type, str(check.subject_uuid))
)
return check, True
except IntegrityError:
# Check-then-insert race: a concurrent identical request inserted this fingerprint between
# the lookup above and this create. Refetch and refine the row it won with, so the loser
# gets the promised existing check (HTTP 200) rather than a 500.
existing = _find_by_fingerprint(team.id, subject_type, subject_uuid, fingerprint)
if existing is None:
# The name constraint races the same way, past its own precheck, so report it as the
# conflict it is rather than letting the database error surface as a 500.
ensure_name_available(team.id, fields.get("name") or "")
raise
return update_check(existing, **fields), False
def _find_by_fingerprint(
team_id: int, subject_type: str, subject_uuid: str, fingerprint: str
) -> DataQualityCheck | None:
"""The *active* check carrying this fingerprint, if any.
Active-only so authoring a definition that was deleted earlier creates a new check with its own
id and history, rather than resurrecting a row the user believes is gone.
"""
return (
DataQualityCheck.objects.for_team(team_id)
.filter(fingerprint=fingerprint, deleted=False, **subject_filter(subject_type, subject_uuid))
.first()
)
def update_check(check: DataQualityCheck, **fields: Any) -> DataQualityCheck:
"""Apply presentation changes only. Editing the assertion goes through ``edit_check``."""
changed = [key for key in fields if key in _UPSERTABLE_FIELDS]
for key in changed:
setattr(check, key, fields[key])
if changed:
check.save(update_fields=[*changed, "updated_at"])
return check
@frozen
class _CandidateDefinition:
"""What a requested edit would leave the check asserting, canonicalized."""
check_type: str
column_name: str
config: dict[str, Any]
fingerprint: str
def edit_check(
*,
team: Team,
check: DataQualityCheck,
editor: User | None,
authorize: Callable[[DataQualityCheck], None] | None = None,
**fields: Any,
) -> DataQualityCheck:
"""Save a complete definition change, or none of it. The owning subject never moves.
Two edits to the same check serialize on the row lock, so the loser recomputes against what the
winner committed. Two *different* rows converging on one definition race past that lock, and the
active-fingerprint constraint is what settles them -- its ``IntegrityError`` comes back as the
same conflict the precheck raises.
"""
requested = {key: value for key, value in fields.items() if key in _EDITABLE_FIELDS}
for _ in range(_MAX_EDIT_ATTEMPTS):
current = DataQualityCheck.objects.for_team(team.id).get(id=check.id)
candidate = _candidate_definition(team, current, requested)
if authorize is not None:
authorize(current)
try:
with transaction.atomic():
locked = DataQualityCheck.objects.for_team(team.id).select_for_update().get(id=check.id)
if _definition_identity(locked) != _definition_identity(current):
continue
return _commit_edit(team, locked, editor, requested, candidate)
except IntegrityError:
# Which constraint lost decides which field the error is addressed to. Asking about the
# definition alone would answer "duplicate" for every one of them, since an edit that leaves
# the assertion alone still finds its own fingerprint.
if _definition_taken(current, candidate.fingerprint):
raise DuplicateDefinitionError()
if _name_taken(team.id, requested.get("name") or "", exclude_id=check.id):
raise NameConflictError()
raise
raise ConcurrentEditError()
def _commit_edit(
team: Team,
check: DataQualityCheck,
editor: User | None,
requested: dict[str, Any],
candidate: _CandidateDefinition,
) -> DataQualityCheck:
_ensure_definition_available(check, candidate.fingerprint)
if _name_taken(team.id, requested.get("name") or "", exclude_id=check.id):
raise NameConflictError()
changed = {key for key in requested if key in _UPSERTABLE_FIELDS}
for key in changed:
setattr(check, key, requested[key])
if candidate.fingerprint != check.fingerprint:
check.check_type = candidate.check_type
check.column_name = candidate.column_name
check.config = candidate.config
check.fingerprint = candidate.fingerprint
# An automated run of an edited definition authorizes as whoever last changed what it reads,
# not as whoever created it years ago.
check.definition_author = editor
changed |= {*_ASSERTION_FIELDS, "fingerprint", "definition_author"}
if changed:
check.save(update_fields=[*changed, "updated_at"])
return check
def _candidate_definition(team: Team, check: DataQualityCheck, requested: dict[str, Any]) -> _CandidateDefinition:
if not _edits_the_assertion(requested):
# A presentation-only edit asserts nothing new, so the stored definition is kept as it is
# rather than revalidated. A subject can stop supporting its check after the check exists (a
# metric moves off a HogQL definition), and revalidating here would block the very edit that
# settles it: turning the check off.
return _CandidateDefinition(
check_type=check.check_type,
column_name=check.column_name,
config=check.config,
fingerprint=check.fingerprint,
)
check_type = requested.get("check_type", check.check_type)
column_name = requested.get("column_name", check.column_name)
parsed = validate_check(
team,
check.subject_type,
str(check.subject_uuid),
check_type,
column_name,
requested.get("config", check.config) or {},
)
config = canonical_config(parsed)
return _CandidateDefinition(
check_type=check_type,
column_name=column_name,
config=config,
fingerprint=compute_fingerprint(
subject_type=check.subject_type,
subject_uuid=str(check.subject_uuid),
check_type=check_type,
column_name=column_name,
config=config,
),
)
def _definition_taken(check: DataQualityCheck, fingerprint: str) -> bool:
"""Whether *another* active check on this subject already asserts this."""
return (
DataQualityCheck.objects.for_team(check.team_id)
.filter(fingerprint=fingerprint, deleted=False, **subject_filter(check.subject_type, str(check.subject_uuid)))
.exclude(id=check.id)
.exists()
)
def _ensure_definition_available(check: DataQualityCheck, fingerprint: str) -> None:
if _definition_taken(check, fingerprint):
raise DuplicateDefinitionError()
def soft_delete_check(check: DataQualityCheck) -> None:
"""Hide the definition but keep its run history queryable."""
check.deleted = True
check.deleted_at = datetime.now(UTC)
check.enabled = False
check.save(update_fields=["deleted", "deleted_at", "enabled", "updated_at"])
def live_subject_checks(checks: QuerySet[DataQualityCheck]) -> QuerySet[DataQualityCheck]:
return (
checks.filter(
Q(subject_type=SubjectType.METRIC, metric_id__isnull=False)
| Q(subject_type=SubjectType.VIEW, saved_query_id__isnull=False)
| Q(subject_type=SubjectType.TABLE, table_id__isnull=False)
| Q(subject_type=SubjectType.POSTHOG_TABLE, posthog_table__in=posthog_tables.names())
)
.exclude(metric__deleted=True)
.exclude(saved_query__deleted=True)
.exclude(table__deleted=True)
)
def checks_for_subject(
team_id: int, subject_type: str, subject_uuid: str | UUID, include_deleted: bool = False
) -> QuerySet[DataQualityCheck]:
queryset = DataQualityCheck.objects.for_team(team_id).filter(**subject_filter(subject_type, subject_uuid))
# A soft-deleted check's past runs still sit in the aggregate counts of suites it ran in, so
# authorization over a *historical* suite has to see it too, even though it no longer runs.
return queryset if include_deleted else live_subject_checks(queryset.filter(deleted=False))
def latest_run_ids(team_id: int, check_ids: Iterable[UUID]) -> list[UUID]:
"""The id of each of these checks' most recent run. One query; a check never run contributes none.
A check row is not purely a definition: its ``last_status`` and ``last_run_at`` come from this
run, so they report on whatever it read. Authorizing the row on the definition alone would serve
that verdict about a subject the caller was denied, once the definition stops naming it.
"""
ids = list(check_ids)
if not ids:
return []
return list(
DataQualityCheckRun.objects.for_team(team_id)
.filter(quality_check_id__in=ids)
.order_by("quality_check_id", "-created_at")
.distinct("quality_check_id")
.values_list("id", flat=True)
)
def subject_health(team_id: int, subject_type: str, subject_uuid: str | UUID) -> SubjectHealth:
# Only enabled checks count toward health, matching the REST counts and the
# information_schema.data_quality_health table -- the three must never disagree.
rows = (
checks_for_subject(team_id, subject_type, subject_uuid)
.filter(enabled=True)
.values_list("severity", "last_status")
)
return roll_up_health(CheckStatusRow(severity=severity, last_status=status) for severity, status in rows)
def start_check_suite(
*,
team: Team,
trigger: SuiteRunTrigger = SuiteRunTrigger.MANUAL,
user: User | None = None,
subject_type: str = "",
subject_uuids: list[str] | None = None,
check_ids: list[str] | None = None,
) -> DataQualitySuiteRun:
"""Kick off a suite run and hand back the row to poll.
The row is created here rather than inside the workflow so the caller gets a pollable handle
synchronously; the prepare activity fills in the batches.
"""
# Deferred: importing anything under ``temporal`` executes its package __init__, which pulls
# the workflow and activity modules (and temporalio's sandbox) onto the request import path.
from ..temporal.contracts import RunCheckSuiteInputs # noqa: PLC0415
subject_uuids = subject_uuids or []
suite_run = DataQualitySuiteRun.objects.for_team(team.id).create(
team=team,
trigger=trigger,
created_by=user,
subject_type=subject_type if len(subject_uuids) == 1 else "",
subject_uuid=subject_uuids[0] if len(subject_uuids) == 1 else None,
workflow_id=f"data-quality-run-suite-{team.id}-{uuid4()}",
started_at=datetime.now(UTC),
)
inputs = RunCheckSuiteInputs(
team_id=team.id,
trigger=trigger,
saved_query_ids=subject_uuids if subject_type == SubjectType.VIEW else [],
table_ids=subject_uuids if subject_type == SubjectType.TABLE else [],
metric_ids=subject_uuids if subject_type == SubjectType.METRIC else [],
posthog_table_ids=subject_uuids if subject_type == SubjectType.POSTHOG_TABLE else [],
check_ids=check_ids or [],
suite_run_id=str(suite_run.id),
created_by_id=user.id if user else None,
)
try:
temporal = sync_connect()
asyncio.run(
temporal.start_workflow(
CHECK_SUITE_WORKFLOW_NAME,
asdict(inputs),
id=suite_run.workflow_id,
task_queue=str(settings.DATA_MODELING_TASK_QUEUE),
retry_policy=RetryPolicy(maximum_attempts=1),
)
)
except Exception as err:
# The row is already committed, so leaving it would report `running` forever with no
# workflow behind it. Close it out before surfacing the error to the caller.
suite_run.status = SuiteRunStatus.FAILED
suite_run.error = str(err)
suite_run.finished_at = datetime.now(UTC)
suite_run.save(update_fields=["status", "error", "finished_at", "updated_at"])
raise
return suite_run
def empty_check_suite(*, team: Team, user: User | None = None) -> DataQualitySuiteRun:
"""Record a run that had nothing to run, without starting a workflow.
An empty selection cannot be expressed to the worker: by the time ``check_ids`` reaches the
prepare activity, an empty list is indistinguishable from no selector at all, and the suite
would sweep the whole project.
"""
now = datetime.now(UTC)
return DataQualitySuiteRun.objects.for_team(team.id).create(
team=team,
trigger=SuiteRunTrigger.MANUAL,
created_by=user,
status=SuiteRunStatus.EMPTY,
started_at=now,
finished_at=now,
)
def _name_taken(team_id: int, name: str, exclude_id: UUID | str | None = None) -> bool:
"""Whether an *active* check already holds this name. Deleted ones keep theirs only as history."""
if not name:
return False
clashes = DataQualityCheck.objects.for_team(team_id).filter(name=name, deleted=False)
if exclude_id is not None:
clashes = clashes.exclude(id=exclude_id)
return clashes.exists()
def ensure_name_available(team_id: int, name: str, exclude_id: UUID | str | None = None) -> None:
if _name_taken(team_id, name, exclude_id):
raise CheckNameConflict(f"A check named '{name}' already exists in this project.")