: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
"""Facade for warehouse_suggestions."""
from collections.abc import Sequence
from dataclasses import asdict
from typing import TYPE_CHECKING
from uuid import UUID
from posthog.paging import Page, PageRequest
from posthog.queryset_paging import select_page
from products.warehouse_sources.backend.facade.api import source_locations_for_tables
from products.warehouse_sources.backend.facade.contracts import TableSourceLocation
from ..logic import accept, assignment, suggestions
from ..logic.access import CATALOG_KINDS, SubjectAccess, readable_table_ids, visible_suggestions
from ..logic.analytics import SuggestionOutcome, report_outcomes
from ..logic.flags import is_warehouse_suggestions_enabled
from ..logic.payloads import payload_from_json, payload_view, source_table_ids
from ..logic.rules import RULES
from ..models import WarehouseSuggestion, WarehouseSuggestionTeamConfig
from .contracts import (
AcceptOptions,
CatalogEditAccessRequiredError,
SubjectEditAccessRequiredError,
SubjectKinds,
Suggestion,
SuggestionDraft,
SuggestionNotFoundError,
SuggestionPayloadView,
SuggestionReviewer,
SuggestionStatus,
)
from .enums import (
WarehouseSuggestionAssetOutcome,
WarehouseSuggestionDismissalReason,
WarehouseSuggestionKind,
WarehouseSuggestionStatus,
WarehouseSuggestionSubjectKind,
WarehouseSuggestionSurface,
)
if TYPE_CHECKING:
from posthog.models import Team, User
from products.access_control.backend.facade.user_access_control import UserAccessControl
__all__ = [
"accept_suggestion",
"assign_suggestion",
"dismiss_suggestion",
"get_suggestion",
"is_warehouse_suggestions_enabled",
"list_suggestions",
"resume_suggestion",
"suggestion_status",
"upsert_suggestions",
]
def upsert_suggestions(team_id: int, drafts: Sequence[SuggestionDraft]) -> None:
suggestions.upsert_suggestions(team_id, drafts)
def list_suggestions(
team_id: int,
user_access_control: "UserAccessControl",
*,
kind: WarehouseSuggestionKind | None,
status: WarehouseSuggestionStatus | None,
subject_id: UUID | None,
assignee_id: int | None = None,
subject_kinds: SubjectKinds,
page: PageRequest,
) -> Page[Suggestion]:
visible, access = visible_suggestions(
team_id,
user_access_control,
kind=kind,
status=status,
subject_id=subject_id,
assignee_id=assignee_id,
subject_kinds=subject_kinds,
)
rows = select_page(visible, page)
return Page(results=_to_contracts(team_id, user_access_control, rows.results, access), count=rows.count)
def suggestion_status(team_id: int) -> SuggestionStatus:
config = WarehouseSuggestionTeamConfig.objects.filter(team_id=team_id).first() or WarehouseSuggestionTeamConfig()
return SuggestionStatus(
enabled=config.enabled,
eligible=config.eligible,
days_with_data=config.days_with_data,
window_days=RULES.window_days,
paused_reason=config.paused_reason,
refreshed_at=config.last_run_at,
)
def get_suggestion(
team_id: int,
user_access_control: "UserAccessControl",
suggestion_id: UUID,
*,
subject_kinds: SubjectKinds,
) -> Suggestion:
row, access = _visible_suggestion(team_id, user_access_control, suggestion_id, subject_kinds)
return _single_contract(team_id, user_access_control, row, access)
def dismiss_suggestion(
team: "Team",
user_access_control: "UserAccessControl",
suggestion_id: UUID,
*,
user: "User",
reason: WarehouseSuggestionDismissalReason,
note: str | None,
subject_kinds: SubjectKinds,
surface: WarehouseSuggestionSurface | None = None,
) -> Suggestion:
row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
dismissed = suggestions.transition_to(
row.id,
team.pk,
WarehouseSuggestionStatus.DISMISSED,
user_id=user.id,
reason=reason,
note=note,
transitions=suggestions.HUMAN_TRANSITIONS,
)
report_outcomes(SuggestionOutcome.DISMISSED, [dismissed], team=team, user=user, properties={"surface": surface})
return _single_contract(team.pk, user_access_control, dismissed, access)
def resume_suggestion(
team: "Team",
user_access_control: "UserAccessControl",
suggestion_id: UUID,
*,
user: "User",
subject_kinds: SubjectKinds,
) -> Suggestion:
row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
resumed = suggestions.transition_to(
row.id, team.pk, WarehouseSuggestionStatus.PROPOSED, user_id=user.id, transitions=suggestions.HUMAN_TRANSITIONS
)
report_outcomes(SuggestionOutcome.RESUMED, [resumed], team=team, user=user)
return _single_contract(team.pk, user_access_control, resumed, access)
def assign_suggestion(
team: "Team",
user_access_control: "UserAccessControl",
suggestion_id: UUID,
*,
user: "User",
assignee_id: int | None,
subject_kinds: SubjectKinds,
) -> Suggestion:
row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
result = assignment.assign(team, row.id, assignee_id, assigned_by=user)
if result.changed:
report_outcomes(
SuggestionOutcome.ASSIGNED,
[result.suggestion],
team=team,
user=user,
properties={"unassigned": assignee_id is None, "self_assigned": assignee_id == user.id},
)
return _single_contract(team.pk, user_access_control, result.suggestion, access)
def accept_suggestion(
team: "Team",
user_access_control: "UserAccessControl",
suggestion_id: UUID,
*,
user: "User",
options: AcceptOptions,
was_impersonated: bool,
subject_kinds: SubjectKinds,
surface: WarehouseSuggestionSurface | None = None,
) -> Suggestion:
row, access = _actionable_suggestion(team.pk, user_access_control, suggestion_id, subject_kinds)
if not options.delete_view:
_require_catalog_edit_access(row, user_access_control)
outcome = accept.accept(
team.pk,
row.id,
accept.AcceptRequest(team=team, user=user, options=options, was_impersonated=was_impersonated),
)
if outcome.newly_accepted:
report_outcomes(
SuggestionOutcome.ACCEPTED,
[outcome.suggestion],
team=team,
user=user,
properties={"changed_fields": list(outcome.changed_fields), "surface": surface, **asdict(outcome.savings)},
)
return _single_contract(team.pk, user_access_control, outcome.suggestion, access)
def _actionable_suggestion(
team_id: int,
user_access_control: "UserAccessControl",
suggestion_id: UUID,
subject_kinds: SubjectKinds,
) -> tuple[WarehouseSuggestion, SubjectAccess]:
row, access = _visible_suggestion(team_id, user_access_control, suggestion_id, subject_kinds)
if not access.can_act_on(row):
raise SubjectEditAccessRequiredError(WarehouseSuggestionSubjectKind(row.subject_kind))
return row, access
def _require_catalog_edit_access(row: WarehouseSuggestion, user_access_control: "UserAccessControl") -> None:
if row.kind not in CATALOG_KINDS:
return
if not user_access_control.check_access_level_for_resource("data_catalog", required_level="editor"):
raise CatalogEditAccessRequiredError()
def _single_contract(
team_id: int, user_access_control: "UserAccessControl", row: WarehouseSuggestion, access: SubjectAccess
) -> Suggestion:
(suggestion,) = _to_contracts(team_id, user_access_control, [row], access)
return suggestion
def _visible_suggestion(
team_id: int,
user_access_control: "UserAccessControl",
suggestion_id: UUID,
subject_kinds: SubjectKinds,
) -> tuple[WarehouseSuggestion, SubjectAccess]:
visible, access = visible_suggestions(
team_id, user_access_control, suggestion_id=suggestion_id, subject_kinds=subject_kinds
)
row = visible.first()
if row is None:
raise SuggestionNotFoundError(suggestion_id)
return row, access
def _to_contracts(
team_id: int,
user_access_control: "UserAccessControl",
rows: list[WarehouseSuggestion],
access: SubjectAccess,
) -> list[Suggestion]:
stored = {
row.id: payload_from_json(WarehouseSuggestionKind(row.kind), row.payload_version, row.payload) for row in rows
}
readable = readable_table_ids(team_id, user_access_control, source_table_ids(stored.values()))
table_ids = {row.subject_id for row in rows if row.subject_kind == WarehouseSuggestionSubjectKind.TABLE}
locations = source_locations_for_tables(team_id, table_ids)
return [
_to_contract(row, access, payload_view(stored[row.id], readable), locations.get(row.subject_id)) for row in rows
]
def _to_contract(
row: WarehouseSuggestion,
access: SubjectAccess,
payload: SuggestionPayloadView,
location: TableSourceLocation | None,
) -> Suggestion:
return Suggestion(
id=row.id,
kind=WarehouseSuggestionKind(row.kind),
subject_kind=WarehouseSuggestionSubjectKind(row.subject_kind),
subject_id=row.subject_id,
payload=payload,
payload_version=row.payload_version,
evidence=row.evidence,
evidence_window_start=row.evidence_window_start,
evidence_window_end=row.evidence_window_end,
last_seen_at=row.last_seen_at,
status=WarehouseSuggestionStatus(row.status),
surfaced_at=row.surfaced_at,
reviewed_by=_to_user(row.reviewed_by),
reviewed_at=row.reviewed_at,
dismissal_reason=WarehouseSuggestionDismissalReason(row.dismissal_reason) if row.dismissal_reason else None,
dismissal_note=row.dismissal_note,
created_asset=row.created_asset,
asset_outcome=WarehouseSuggestionAssetOutcome(row.asset_outcome) if row.asset_outcome else None,
realized_seconds_saved_per_month=row.realized_seconds_saved_per_month,
realized_bytes_saved_per_month=row.realized_bytes_saved_per_month,
can_act=access.can_act_on(row),
subject_source_id=location.source_id if location else None,
subject_schema_id=location.schema_id if location else None,
assignee=_to_user(row.assignee),
)
def _to_user(user: "User | None") -> SuggestionReviewer | None:
if user is None:
return None
return SuggestionReviewer(id=user.id, first_name=user.first_name, email=user.email)