Skip to content

: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.

25.2 KB
Raw Blame
"""DRF serializers for data quality checks.

Source of truth for the generated frontend and MCP types, so every field carries help_text. The
per-type ``config`` shape is validated against the registry's JSON schema rather than modeled as a
union: a new check type must not need a serializer change.
"""

from typing import Any

from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import extend_schema_field, extend_schema_serializer
from rest_framework import serializers
from rest_framework.exceptions import ErrorDetail
from rest_framework.settings import api_settings

from posthog.api.shared import UserBasicSerializer

from ..facade import api
from ..facade.enums import CheckSeverity, CheckType, CreatedSource, DataQualityScheduleInterval, SubjectType
from ..facade.models import DataQualityCheck, DataQualityCheckRun, DataQualitySuiteRun


@extend_schema_field(OpenApiTypes.OBJECT)
class CheckConfigField(serializers.JSONField):
    """Type-specific configuration. Call /check_types/ for the JSON schema of each type."""


class DataQualityMetricSubjectSerializer(serializers.Serializer):
    id = serializers.UUIDField(help_text="Metric identifier used by the nested check endpoints.")
    name = serializers.CharField(help_text="Queryable metric name.")
    display_name = serializers.CharField(allow_blank=True, help_text="Metric label shown in the data catalog.")


@extend_schema_serializer(component_name="DataQualitySubjectRef")
class DataQualitySubjectRefSerializer(serializers.Serializer):
    """The subject a request names, wherever it names it: a body, a query string, or both."""

    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType],
        help_text="Kind of object: 'table', 'view', 'metric', or 'posthog_table'.",
    )
    subject_uuid = serializers.UUIDField(help_text="Id of the table, view, metric, or PostHog table.")


@extend_schema_serializer(component_name="DataQualitySubject")
class DataQualitySubjectSerializer(serializers.Serializer):
    """One thing a check can be authored on, whatever kind it is."""

    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType],
        help_text="Kind of object: 'table', 'view', 'metric', or 'posthog_table'. "
        "Pass it back as subject_type when creating a check.",
    )
    id = serializers.CharField(help_text="Id of the subject. Pass it back as subject_uuid when creating a check.")
    name = serializers.CharField(help_text="Queryable name of the subject.")
    display_name = serializers.CharField(
        allow_blank=True, help_text="Label shown in the data catalog. Blank for tables and views."
    )
    time_column = serializers.CharField(
        allow_blank=True,
        help_text="Column a lookback window bounds, or blank for a subject that has none.",
    )
    columns = serializers.DictField(
        child=serializers.CharField(),
        help_text="Column name to ClickHouse type. Empty for a metric, and for a view that has not run yet.",
    )
    editable = serializers.BooleanField(
        help_text="Whether the caller may author a check on this subject. A subject that is only readable "
        "can still be the target of a relationships check."
    )


class DataQualitySubjectsQuerySerializer(serializers.Serializer):
    """Filters and paging for the subject catalog. Without any of them it returns every subject."""

    subject_type = serializers.ChoiceField(
        choices=SubjectType.choices,
        required=False,
        help_text="Return only subjects of this kind: 'table', 'view', 'metric', or 'posthog_table'.",
    )
    search = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Return only subjects whose name or display name contains this text, ignoring case.",
    )
    include_columns = serializers.BooleanField(
        required=False,
        default=True,
        help_text="Set to false to return an empty columns map for every subject. "
        "Use it to find a subject id without reading every column schema.",
    )
    limit = serializers.IntegerField(
        required=False,
        min_value=1,
        max_value=1000,
        help_text="Maximum number of subjects to return. Omit to return every match.",
    )
    offset = serializers.IntegerField(
        required=False,
        min_value=0,
        default=0,
        help_text="Number of matching subjects to skip. Subjects are sorted by subject_type, then name. "
        "When a response has limit rows, call again with offset increased by limit to read the next page.",
    )


class DataQualityOutputColumnSerializer(serializers.Serializer):
    name = serializers.CharField(help_text="Output column name available through the {metric} relation.")
    type = serializers.CharField(allow_null=True, help_text="ClickHouse type, or null when it could not be inferred.")


class DataQualityOutputSchemaSerializer(serializers.Serializer):
    columns = DataQualityOutputColumnSerializer(many=True, help_text="Columns returned by the saved metric query.")


@extend_schema_serializer(component_name="DataQualityCheck")
class DataQualityCheckSerializer(serializers.ModelSerializer):
    """A check as it reads back, and everything an edit may change about it.

    The subject is not one of those: it is writable only on ``DataQualityCheckCreate``.
    """

    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType],
        read_only=True,
        help_text="Kind of object being checked: 'table', 'view', 'metric', or 'posthog_table'.",
    )
    subject_uuid = serializers.UUIDField(
        read_only=True,
        allow_null=True,
        help_text="Id of the table, view, metric, or PostHog table being checked. Null once the subject is deleted.",
    )
    check_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in CheckType],
        help_text="Which assertion to make. Determines the shape of config; see /check_types/.",
    )
    severity = serializers.ChoiceField(
        choices=[(s.value, s.value) for s in CheckSeverity],
        required=False,
        help_text="'error' failures mark the subject failing and notify; 'warn' failures only surface.",
    )
    created_source = serializers.ChoiceField(
        choices=[(s.value, s.value) for s in CreatedSource],
        required=False,
        help_text="Whether a human ('user') or an agent ('ai_generated') authored this check.",
    )
    config = CheckConfigField(
        required=False,
        help_text="Type-specific configuration, validated against the check type's JSON schema.",
    )
    tags = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        help_text="Free-form string labels for grouping and filtering.",
    )
    last_status = serializers.CharField(
        read_only=True,
        help_text="Outcome of the newest run: passed, failed, errored, skipped, or empty if never run.",
    )
    last_succeeded_at = serializers.DateTimeField(
        read_only=True,
        allow_null=True,
        help_text="When the check last passed. Read failing_since for how long a failing check has been failing. "
        "Null means it has not passed within the run retention window.",
    )
    failing_since = serializers.DateTimeField(
        read_only=True,
        allow_null=True,
        help_text="When the current streak of failing runs started, so a failing check can say how long "
        "it has been failing. Null when the check is not failing.",
    )
    subject_status = serializers.CharField(
        read_only=True,
        help_text="'orphaned' once the subject stops resolving. Orphaned checks are skipped, not deleted.",
    )
    owner = serializers.SerializerMethodField(help_text="Email of the human accountable for this check, or null.")
    created_by = UserBasicSerializer(read_only=True, help_text="User who first created this check.")

    class Meta:
        model = DataQualityCheck
        fields = [
            "id",
            "name",
            "description",
            "subject_type",
            "subject_uuid",
            "subject_name",
            "subject_status",
            "column_name",
            "check_type",
            "config",
            "severity",
            "enabled",
            "tags",
            "owner",
            "last_run_at",
            "last_status",
            "last_succeeded_at",
            "failing_since",
            "fingerprint",
            "created_source",
            "ai_model",
            "confidence",
            "reasoning",
            "created_by",
            "created_at",
            "updated_at",
        ]
        read_only_fields = [
            "id",
            "subject_name",
            "subject_status",
            "last_run_at",
            "last_status",
            "last_succeeded_at",
            "failing_since",
            "fingerprint",
            "created_by",
            "created_at",
            "updated_at",
        ]
        extra_kwargs = {
            "name": {
                "required": False,
                "help_text": "Optional identifier-safe handle, unique per project. Omit to address the check by id.",
            },
            "description": {"required": False, "help_text": "Why this check exists and what a failure means."},
            "subject_name": {"help_text": "Queryable name of the subject, refreshed on every run."},
            "column_name": {
                "required": False,
                "help_text": "Column the check applies to. Omit for table-scoped types like row_count.",
            },
            "enabled": {"required": False, "help_text": "Disabled checks are never run by any trigger."},
            "fingerprint": {
                "help_text": "sha256 of the subject, type, column, and config. Re-creating the same check upserts."
            },
            "ai_model": {"required": False, "help_text": "Model that generated the check, if AI-authored."},
            "confidence": {
                "required": False,
                "help_text": "AI author's confidence in the check, 0-1.",
                "min_value": 0.0,
                "max_value": 1.0,
            },
            "reasoning": {"required": False, "help_text": "AI author's reasoning, surfaced as review context."},
        }

    @extend_schema_field(serializers.CharField(allow_null=True))
    def get_owner(self, obj: DataQualityCheck) -> str | None:
        return obj.owner.email if obj.owner else None

    def validate(self, attrs: dict) -> dict:
        if self.instance is not None:
            return attrs

        try:
            api.validate_check(
                self.context["get_team"](),
                str(self.context.get("subject_type") or ""),
                str(self.context.get("subject_uuid") or ""),
                attrs.get("check_type") or "",
                attrs.get("column_name") or "",
                attrs.get("config") or {},
            )
        except (api.CheckConfigError, api.SubjectUnresolvableError, api.UnknownCheckTypeError) as err:
            raise serializers.ValidationError({"config": str(err)})
        return attrs

    def update(self, instance: DataQualityCheck, validated_data: dict) -> DataQualityCheck:
        request = self.context.get("request")
        try:
            return api.edit_check(
                team=self.context["get_team"](),
                check=instance,
                editor=getattr(request, "user", None) if request else None,
                authorize=self.context.get("authorize_check_edit"),
                **validated_data,
            )
        except (api.CheckConfigError, api.SubjectUnresolvableError, api.UnknownCheckTypeError) as err:
            raise serializers.ValidationError({"config": str(err)})
        except api.CheckEditConflict as conflict:
            # Rendered beside the offending fields rather than as a status code, so the editor can
            # keep the draft open and point at what to change.
            fields = conflict.fields or (api_settings.NON_FIELD_ERRORS_KEY,)
            raise serializers.ValidationError(
                {field: ErrorDetail(str(conflict), code=conflict.code) for field in fields}
            )


@extend_schema_serializer(component_name="DataQualityCheckCreate")
class DataQualityCheckCreateSerializer(DataQualityCheckSerializer):
    """The create body, where the subject is named for the only time in a check's life."""

    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType],
        help_text="Kind of object to check: 'table', 'view', 'metric', or 'posthog_table'.",
    )
    subject_uuid = serializers.UUIDField(help_text="Id of the table, view, metric, or PostHog table to check.")


@extend_schema_serializer(component_name="DataQualityOverviewCheck")
class DataQualityOverviewCheckSerializer(DataQualityCheckSerializer):
    """A check plus where its subject can be opened, for the project-wide list.

    The per-subject surfaces already know their parent; only this one lists checks across every
    table and view, so only this one needs to say where each subject lives. The ids are resolved
    for a whole page at once and handed in through ``subject_locations`` in the context.
    """

    subject_node_id = serializers.SerializerMethodField(
        help_text="Data modeling node of the view or PostHog table this check audits, or null when it is on "
        "no DAG or the subject is a warehouse table."
    )
    subject_source_id = serializers.SerializerMethodField(
        help_text="Warehouse source of the table this check audits, or null when the subject is a view."
    )
    subject_schema_id = serializers.SerializerMethodField(
        help_text="Warehouse source schema of the table this check audits, or null when the subject is a view."
    )
    subject_metric_name = serializers.SerializerMethodField(
        help_text="Current metric name for opening its Tests tab, or null for other subjects."
    )

    class Meta(DataQualityCheckSerializer.Meta):
        fields = [
            *DataQualityCheckSerializer.Meta.fields,
            "subject_node_id",
            "subject_source_id",
            "subject_schema_id",
            "subject_metric_name",
        ]

    def _location(self, obj: DataQualityCheck) -> api.SubjectLocation:
        locations: dict[api.SubjectKey, api.SubjectLocation] = self.context.get("subject_locations") or {}
        key = api.SubjectKey(subject_type=SubjectType(obj.subject_type), subject_uuid=str(obj.subject_uuid))
        return locations.get(key) or api.SubjectLocation()

    @extend_schema_field(serializers.UUIDField(allow_null=True))
    def get_subject_node_id(self, obj: DataQualityCheck) -> str | None:
        return self._location(obj).node_id

    @extend_schema_field(serializers.UUIDField(allow_null=True))
    def get_subject_source_id(self, obj: DataQualityCheck) -> str | None:
        return self._location(obj).source_id

    @extend_schema_field(serializers.UUIDField(allow_null=True))
    def get_subject_schema_id(self, obj: DataQualityCheck) -> str | None:
        return self._location(obj).schema_id

    @extend_schema_field(serializers.CharField(allow_null=True))
    def get_subject_metric_name(self, obj: DataQualityCheck) -> str | None:
        return self._location(obj).metric_name


@extend_schema_serializer(component_name="DataQualityCheckScheduleUpdate")
class DataQualityCheckScheduleUpdateSerializer(DataQualitySubjectRefSerializer):
    """Which subject's schedule to change, and what to change about it."""

    SCHEDULE_FIELDS = ("interval", "enabled")

    interval = serializers.ChoiceField(
        choices=DataQualityScheduleInterval.choices,
        required=False,
        help_text="How often all enabled checks on the subject run.",
    )
    enabled = serializers.BooleanField(required=False, help_text="Whether checks run automatically on this schedule.")

    @property
    def schedule_changes(self) -> dict:
        return {key: value for key, value in self.validated_data.items() if key in self.SCHEDULE_FIELDS}


class DataQualityCheckScheduleSerializer(serializers.Serializer):
    id = serializers.UUIDField(read_only=True, help_text="Schedule identifier.")
    interval = serializers.ChoiceField(
        choices=DataQualityScheduleInterval.choices, read_only=True, help_text="How often the checks run."
    )
    enabled = serializers.BooleanField(read_only=True, help_text="Whether the schedule runs automatically.")
    next_run_at = serializers.DateTimeField(
        read_only=True, allow_null=True, help_text="Next scheduled execution time, if enabled."
    )
    last_run_at = serializers.DateTimeField(
        read_only=True, allow_null=True, help_text="Most recent visible scheduled suite execution time."
    )
    last_suite_run = serializers.UUIDField(
        read_only=True, allow_null=True, help_text="Most recent visible scheduled suite."
    )


class DataQualitySubjectScheduleSerializer(DataQualityCheckScheduleSerializer):
    """One subject's schedule, in the project-wide listing."""

    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType], read_only=True, help_text="'metric' or 'posthog_table'."
    )
    subject_uuid = serializers.UUIDField(read_only=True, help_text="Id of the metric or PostHog table.")

    def to_representation(self, instance: api.SubjectSchedule) -> dict[str, Any]:
        row = super().to_representation(instance.schedule)
        row["subject_type"] = str(instance.subject_type)
        row["subject_uuid"] = str(instance.subject_uuid)
        return row


@extend_schema_serializer(component_name="DataQualityCheckRun")
class DataQualityCheckRunSerializer(serializers.ModelSerializer):
    status = serializers.CharField(read_only=True, help_text="passed, failed, errored, or skipped.")
    # Declared rather than derived: the model field carries no choices, so the schema would otherwise
    # publish check_type as a bare string.
    check_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in CheckType],
        read_only=True,
        help_text="Which assertion this run made.",
    )
    check_config = CheckConfigField(
        read_only=True,
        allow_null=True,
        help_text="Config this run executed, snapshotted so an edit to the check cannot rewrite history. "
        "Null for runs recorded before snapshots existed -- unknown, not 'same as the check has now'.",
    )
    check_severity = serializers.ChoiceField(
        choices=[(s.value, s.value) for s in CheckSeverity],
        read_only=True,
        allow_null=True,
        help_text="Severity this run was judged at. Null for runs recorded before snapshots existed.",
    )
    check_name = serializers.SerializerMethodField(
        help_text="Name the check carries now, so a run can be told from the others in its suite. "
        "Null when the check is unnamed, has been hard deleted, or is out of your reach today -- "
        "describe the run by check_type and column_name instead."
    )

    @extend_schema_field(serializers.CharField(allow_null=True))
    def get_check_name(self, obj: DataQualityCheckRun) -> str | None:
        # A surface that serves runs from several checks passes the ones it may not name; a surface
        # that already authorized the single check it serves passes nothing and names it.
        check = obj.quality_check
        if not check or check.id in self.context.get("unnamable_check_ids", frozenset()):
            return None
        return check.name or None

    class Meta:
        model = DataQualityCheckRun
        fields = [
            "id",
            "quality_check",
            "check_name",
            "suite_run",
            "subject_type",
            "subject_uuid",
            "subject_name",
            "check_type",
            "column_name",
            "check_config",
            "check_severity",
            "status",
            "failed_row_count",
            "observed_value",
            "compiled_query",
            "audited_staged_refresh",
            "error",
            "duration_ms",
            "started_at",
            "finished_at",
            "created_at",
        ]
        read_only_fields = fields
        extra_kwargs = {
            "failed_row_count": {"help_text": "Rows violating the assertion. Null for bounds checks like row_count."},
            "observed_value": {"help_text": "The check's headline number, recorded on passes too."},
            "compiled_query": {
                "help_text": "HogQL selecting the failing rows. Re-run it to see them. For a run that audited a "
                "staged refresh it inlines the view's definition, so it reads the source tables rather than "
                "the published table. Empty when there is nothing to replay: retention cleared it, or a staged "
                "run could not build its replay query."
            },
            "error": {"help_text": "Compilation or execution failure, when status is 'errored'."},
        }


@extend_schema_serializer(component_name="DataQualitySuiteRun")
class DataQualitySuiteRunSerializer(serializers.ModelSerializer):
    status = serializers.CharField(
        read_only=True, help_text="running, completed, failed, or empty (nothing matched the trigger)."
    )
    trigger = serializers.CharField(read_only=True, help_text="manual, materialization, source_sync, or scheduled.")
    subject_type = serializers.SerializerMethodField(
        help_text="'table', 'view', 'metric', or 'posthog_table' when the run targets exactly one subject, "
        "including a run of a single check on that subject; null for a run spanning several subjects."
    )

    @extend_schema_field(serializers.CharField(allow_null=True))
    def get_subject_type(self, obj: DataQualitySuiteRun) -> str | None:
        # The model stores "" for a run that is not scoped to a single subject; the response schema
        # only permits table/view, so surface the unscoped case as null rather than a blank string.
        return obj.subject_type or None

    class Meta:
        model = DataQualitySuiteRun
        fields = [
            "id",
            "trigger",
            "status",
            "subject_type",
            "subject_uuid",
            "workflow_id",
            "checks_passed",
            "checks_failed",
            "checks_errored",
            "checks_skipped",
            "started_at",
            "finished_at",
            "error",
            "created_at",
        ]
        read_only_fields = fields


@extend_schema_serializer(component_name="DataQualitySubjectHealth")
class SubjectHealthSerializer(serializers.Serializer):
    """Per-subject rollup, the same rule the information_schema.data_quality_health table uses."""

    subject_type = serializers.CharField(help_text="'table', 'view', 'metric', or 'posthog_table'.")
    subject_uuid = serializers.CharField(help_text="Id of the table, view, metric, or PostHog table.")
    health = serializers.CharField(
        help_text="failing (an error-severity check failed), erroring (a check could not run), "
        "warn (only warn-severity failures), healthy, or unknown (nothing has run yet)."
    )
    checks_total = serializers.IntegerField(help_text="How many enabled, non-deleted checks cover this subject.")
    checks_failing = serializers.IntegerField(help_text="How many of those checks last reported a failure.")


@extend_schema_serializer(component_name="DataQualityRunRequest")
class DataQualityRunRequestSerializer(serializers.Serializer):
    """What to run in a project-wide suite run."""

    check_ids = serializers.ListField(
        child=serializers.UUIDField(),
        required=False,
        help_text="Ids of the checks to run. Omit to run every enabled check in the project.",
    )
    subject_type = serializers.ChoiceField(
        choices=[(t.value, t.value) for t in SubjectType],
        required=False,
        help_text="Narrow the run to one subject. Pass subject_uuid with it. Ignored when check_ids is given.",
    )
    subject_uuid = serializers.UUIDField(
        required=False,
        help_text="Id of the subject to run every enabled check on. Pass subject_type with it.",
    )

    def validate(self, attrs: dict) -> dict:
        if bool(attrs.get("subject_type")) != bool(attrs.get("subject_uuid")):
            raise serializers.ValidationError(
                {"subject_uuid": "Name the subject with both subject_type and subject_uuid, or neither."}
            )
        return attrs


@extend_schema_serializer(component_name="DataQualityGateConfig")
class DataQualityGateConfigSerializer(serializers.Serializer):
    """The team-level materialization gate. Checks always run and warn; this only toggles blocking."""

    gate_materialization_on_checks = serializers.BooleanField(
        help_text="When true, a materialization whose error-severity checks fail is not published; "
        "the previous version keeps serving and downstream models are skipped."
    )


@extend_schema_serializer(component_name="DataQualityCheckType")
class CheckTypeSerializer(serializers.Serializer):
    """One entry of the check-type catalog, so an agent can author config without guessing."""

    check_type = serializers.CharField(help_text="Value to pass as check_type.")
    description = serializers.CharField(help_text="What the check asserts and what counts as a failure.")
    requires_column = serializers.BooleanField(help_text="Whether column_name must be set for this type.")
    config_schema = CheckConfigField(help_text="JSON schema the config object is validated against.")