: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
"""Shapes passed between the subject resolver, the check registry, and the compiler."""
from dataclasses import dataclass
from enum import StrEnum
from typing import TYPE_CHECKING
from ..facade.enums import SubjectType
if TYPE_CHECKING:
from posthog.hogql import ast
from products.data_catalog.backend.facade.contracts import HogQLMetricDefinition
class Evaluation(StrEnum):
"""How the runner turns a compiled query's result row into a status."""
ZERO_ROWS_PASS = "zero_rows_pass"
BOUNDS = "bounds"
@dataclass(frozen=True)
class SubjectIdentity:
"""A subject named the way rows record it: by kind and id, never by name.
Names move. A rename rewrites one, and deleting an object frees its name for anything else to
take, so authorization that has to survive either keys off this instead. Hashable, so a page of
them resolves to current names in one lookup.
"""
subject_type: str
subject_uuid: str
@dataclass(frozen=True)
class SubjectRef:
"""A resolved check subject.
``queryable_name`` is what the compiler puts in the FROM clause; it can differ from the stored
``subject_name`` after a rename, which is why the runner writes it back to the check row.
``time_column`` is the column a lookback window bounds, or None for a subject that has none.
"""
subject_type: SubjectType
subject_uuid: str
name: str
queryable_name: str
exists: bool
time_column: str | None = None
definition_kind: str | None = None
metric_definition: "HogQLMetricDefinition | None" = None
@dataclass(frozen=True)
class CheckPlan:
"""What a check type contributes to the compiled query.
``failing_rows`` selects the rows that violate the assertion; the compiler aggregates over it so
nothing but counts ever leaves ClickHouse. A type whose headline number is not a row count
(freshness) overrides ``failed_count_expr`` and ``observed_value_expr``.
``diagnostic_rows`` is the form a human re-runs. It exists because the two jobs pull apart:
counting is cheapest over a constant projection, while investigating needs the offending values.
A type whose failing rows already show something useful leaves it unset.
"""
failing_rows: "ast.SelectQuery | ast.SelectSetQuery"
diagnostic_rows: "ast.SelectQuery | ast.SelectSetQuery | None" = None
failed_count_expr: "ast.Expr | None" = None
observed_value_expr: "ast.Expr | None" = None
evaluation: Evaluation = Evaluation.ZERO_ROWS_PASS
@dataclass(frozen=True)
class CompiledCheck:
"""A check ready to execute.
Two printed forms, because they answer different questions. ``printed_query`` is the aggregate
that actually runs. ``printed_failing_rows_query`` is the inner query on its own, which is what
someone investigating a failure needs: since failing rows are never stored, re-running this is
the only way to see them.
"""
query: "ast.SelectQuery"
printed_query: str
printed_failing_rows_query: str
failing_rows: "ast.SelectQuery | ast.SelectSetQuery"
evaluation: Evaluation