: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
"""
Cross-boundary data contracts for data_modeling.
Frozen, framework-free dataclasses (``pydantic.dataclasses.dataclass`` — runtime type
validation on construction) describing data_modeling data crossing the product boundary.
ORM models are never returned across the boundary; the facade maps them to these.
data_modeling's external surface is predominantly model-class object wiring (saved-query
DAG traversal, resolvers) re-exported through ``facade.models``; this contract-data
surface is intentionally small and grows as consumers migrate to data reads.
"""
from datetime import datetime, timedelta
from uuid import UUID
from pydantic.dataclasses import dataclass
from posthog.dataclasses import frozen
from posthog.enums import LabeledStrEnum
from products.warehouse_sources.backend.facade.types import WarehouseColumnAnnotationDescriptionSource
@dataclass(frozen=True)
class DataModelingJob:
"""A materialization run for a saved query."""
id: str
team_id: int | None
saved_query_id: str | None
status: str
engine: str
rows_materialized: int
rows_expected: int | None
error: str | None
last_run_at: datetime
@dataclass(frozen=True)
class SavedQuerySummary:
"""A saved query as other products need to see it: enough to name it and query it.
``name`` is the HogQL identifier whether or not the view is materialized -- the physical backing
table is swapped in during resolution and is never the name a caller should query. That is also
why no materialization flag is exposed here: callers query the name either way.
"""
id: str
team_id: int
name: str
last_run_at: datetime | None
@dataclass(frozen=True)
class SavedQueryDefinition:
"""A saved query with its HogQL and whether its DAG node materializes."""
id: UUID
name: str
hogql: str
materializes: bool
is_test: bool
is_managed: bool
origin: str | None
created_at: datetime
refreshes_incrementally: bool = False
calls_decision_functions: bool = False
created_by_id: int | None = None
@dataclass(frozen=True)
class Dependent:
"""Something that reads a saved query, and what a caller's grants are resolved against."""
name: str
kind: str
saved_query_id: str | None = None
created_by_id: int | None = None
lineage_node_id: str | None = None
@frozen
class UpstreamTableRef:
name: str
warehouse_table_id: str | None = None
is_posthog_table: bool = False
@dataclass(frozen=True)
class SuspensionMarker:
"""Why and when scheduled materialization stopped for one engine."""
at: str
reason: str
job_id: str
@dataclass(frozen=True)
class SavedQueryNodeState:
"""What a saved query's DAG nodes record about its schedule."""
declared_target: timedelta | None
suspended: dict[str, SuspensionMarker]
class MaterializationRefusedError(Exception):
pass
class IncrementalConfigRefusedError(MaterializationRefusedError):
def __init__(self, message: str, refused_keys: tuple[str, ...] = ()) -> None:
super().__init__(message)
self.refused_keys = refused_keys
class MaterializationRunDirection(LabeledStrEnum):
UPSTREAM = "upstream", "Upstream"
DOWNSTREAM = "downstream", "Downstream"
class MaterializationEngine(LabeledStrEnum):
CLICKHOUSE = "clickhouse", "ClickHouse"
TRINO = "trino", "Trino"
class MaterializationForbiddenError(Exception):
pass
class ManagedWarehouseUnavailableError(MaterializationForbiddenError):
pass
class MaterializationAlreadyRunningError(Exception):
pass
class MaterializationRanRecentlyError(Exception):
def __init__(self, message: str, *, retry_after_seconds: int) -> None:
super().__init__(message)
self.retry_after_seconds = retry_after_seconds
class MaterializationFailedError(Exception):
pass
@dataclass(frozen=True)
class NodeDescriptionTarget:
"""What a node stands for, which decides where its description lives."""
node_id: UUID
saved_query_id: UUID | None = None
warehouse_table_id: UUID | None = None
@dataclass(frozen=True)
class NodeDescription:
text: str = ""
source: WarehouseColumnAnnotationDescriptionSource | None = None