: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
fix(warehouse-suggestions): explain suggestions without the ranking score (#119681)
Thiago Salvatore0831ae6d4a1f
diff --git a/products/warehouse_suggestions/backend/facade/api.py b/products/warehouse_suggestions/backend/facade/api.pyindex 0ec7539244a1..68c09a72e6dc 100644--- a/products/warehouse_suggestions/backend/facade/api.py+++ b/products/warehouse_suggestions/backend/facade/api.py@@ -226,7 +226,6 @@ def _to_contract(row: WarehouseSuggestion, access: SubjectAccess, payload: Suggeevidence_window_start=row.evidence_window_start,evidence_window_end=row.evidence_window_end,last_seen_at=row.last_seen_at,- score=row.score,status=WarehouseSuggestionStatus(row.status),surfaced_at=row.surfaced_at,reviewed_by=_to_reviewer(row),diff --git a/products/warehouse_suggestions/backend/facade/contracts.py b/products/warehouse_suggestions/backend/facade/contracts.pyindex cf1f04222044..a43224782d4b 100644--- a/products/warehouse_suggestions/backend/facade/contracts.py+++ b/products/warehouse_suggestions/backend/facade/contracts.py@@ -117,7 +117,6 @@ class Suggestion:evidence_window_start: datetimeevidence_window_end: datetimelast_seen_at: datetime- score: floatstatus: WarehouseSuggestionStatussurfaced_at: datetime | Nonereviewed_by: SuggestionReviewer | Nonediff --git a/products/warehouse_suggestions/backend/presentation/serializers.py b/products/warehouse_suggestions/backend/presentation/serializers.pyindex 0797f4a6e168..44e0c41679d9 100644--- a/products/warehouse_suggestions/backend/presentation/serializers.py+++ b/products/warehouse_suggestions/backend/presentation/serializers.py@@ -128,12 +128,43 @@ class WarehouseSuggestionStatusSerializer(DataclassSerializer):}+@extend_schema_serializer(component_name="WarehouseSuggestionEvidence")+class SuggestionEvidenceSerializer(serializers.Serializer):+ days_with_data = serializers.IntegerField(+ required=False,+ help_text=(+ "Days of the 30-day usage window that PostHog has read history for. It counts days with reads in any "+ "project, so it shows how much history exists, not how active this project is."+ ),+ )+ human_requests = serializers.IntegerField(+ required=False, help_text="Queries people ran that read the subject in the usage window."+ )+ human_users = serializers.IntegerField(required=False, help_text="Distinct people who ran those queries.")+ human_days = serializers.IntegerField(required=False, help_text="Days on which people read the subject.")+ background_requests = serializers.IntegerField(+ required=False,+ help_text="Queries PostHog ran on its own that read the subject, such as cache warming and alerts.",+ )+ requests_by_surface = serializers.DictField(+ child=serializers.IntegerField(),+ required=False,+ help_text="Queries people ran per place they ran them, such as sql_editor, dashboard, insight or mcp.",+ )+ last_read_at = serializers.DateTimeField(+ required=False,+ help_text="When any query last read the subject, including queries PostHog ran on its own.",+ )++@extend_schema_serializer(component_name="WarehouseSuggestion")class WarehouseSuggestionSerializer(DataclassSerializer):payload = SuggestionPayloadField(read_only=True, help_text="What accepting this suggestion would create or change. Shape depends on kind.")- evidence = JsonObjectField(help_text="The usage numbers that led to this suggestion.")+ evidence = SuggestionEvidenceSerializer(+ help_text="The read counts that led to this suggestion. A field is missing when the subject had no reads."+ )created_asset = JsonObjectField(allow_null=True, help_text="What accepting this suggestion created. Null until accepted.")@@ -172,7 +203,6 @@ class WarehouseSuggestionSerializer(DataclassSerializer):"evidence_window_start": {"help_text": "Start of the usage window the evidence covers."},"evidence_window_end": {"help_text": "End of the usage window the evidence covers."},"last_seen_at": {"help_text": "When the daily job last found evidence for this suggestion."},- "score": {"help_text": "How strongly the evidence supports the suggestion. Higher comes first."},"surfaced_at": {"help_text": "When the suggestion was first shown. Null while it waits for a slot."},"reviewed_at": {"help_text": "When the suggestion was accepted or dismissed."},"dismissal_note": {"help_text": "Free-text note left when dismissing."},diff --git a/products/warehouse_suggestions/frontend/generated/api.schemas.ts b/products/warehouse_suggestions/frontend/generated/api.schemas.tsindex 254204d2ea7d..7aadd203da18 100644--- a/products/warehouse_suggestions/frontend/generated/api.schemas.ts+++ b/products/warehouse_suggestions/frontend/generated/api.schemas.ts@@ -55,6 +55,28 @@ export type WarehouseSuggestionPayloadApi =| WarehouseSuggestionDeprecatePayloadApi| WarehouseSuggestionMaterializePayloadApi+/**+ * Queries people ran per place they ran them, such as sql_editor, dashboard, insight or mcp.+ */+export type WarehouseSuggestionEvidenceApiRequestsBySurface = { [key: string]: number }++export interface WarehouseSuggestionEvidenceApi {+ /** Days of the 30-day usage window that PostHog has read history for. It counts days with reads in any project, so it shows how much history exists, not how active this project is. */+ days_with_data?: number+ /** Queries people ran that read the subject in the usage window. */+ human_requests?: number+ /** Distinct people who ran those queries. */+ human_users?: number+ /** Days on which people read the subject. */+ human_days?: number+ /** Queries PostHog ran on its own that read the subject, such as cache warming and alerts. */+ background_requests?: number+ /** Queries people ran per place they ran them, such as sql_editor, dashboard, insight or mcp. */+ requests_by_surface?: WarehouseSuggestionEvidenceApiRequestsBySurface+ /** When any query last read the subject, including queries PostHog ran on its own. */+ last_read_at?: string+}+export interface WarehouseSuggestionReviewerApi {/** User id. */id: number@@ -136,11 +158,6 @@ export const WarehouseSuggestionAssetOutcomeEnumApi = {Unused: 'unused',} as const-/**- * The usage numbers that led to this suggestion.- */-export type WarehouseSuggestionApiEvidence = { [key: string]: unknown }-/*** What accepting this suggestion created. Null until accepted.* @nullable@@ -150,8 +167,8 @@ export type WarehouseSuggestionApiCreatedAsset = { [key: string]: unknown } | nuexport interface WarehouseSuggestionApi {/** What accepting this suggestion would create or change. Shape depends on kind. */readonly payload: WarehouseSuggestionPayloadApi- /** The usage numbers that led to this suggestion. */- evidence: WarehouseSuggestionApiEvidence+ /** The read counts that led to this suggestion. A field is missing when the subject had no reads. */+ evidence: WarehouseSuggestionEvidenceApi/*** What accepting this suggestion created. Null until accepted.* @nullable@@ -202,8 +219,6 @@ export interface WarehouseSuggestionApi {evidence_window_end: string/** When the daily job last found evidence for this suggestion. */last_seen_at: string- /** How strongly the evidence supports the suggestion. Higher comes first. */- score: number/*** When the suggestion was first shown. Null while it waits for a slot.* @nullablediff --git a/products/warehouse_suggestions/mcp/tools.yaml b/products/warehouse_suggestions/mcp/tools.yamlindex 30a4d4a04655..9218ef366f35 100644--- a/products/warehouse_suggestions/mcp/tools.yaml+++ b/products/warehouse_suggestions/mcp/tools.yaml@@ -47,9 +47,14 @@ tools:enabled: truetitle: Get a warehouse suggestiondescription: >- Get one warehouse suggestion by id, including `evidence`: the read counts and usage window that led to it.- Use this to explain to the user why a view or table should be certified, deprecated or materialized before- accepting.+ Get one warehouse suggestion by id, with the `evidence` behind it. Evidence counts reads between+ `evidence_window_start` and `evidence_window_end`. `human_requests` is the queries people ran on the view or+ table, `human_users` the distinct people, `human_days` the days with such reads, and `requests_by_surface`+ those queries per place, such as sql_editor, dashboard or mcp. `background_requests` is the queries PostHog+ ran on its own, such as cache warming and alerts. `last_read_at` is the latest read of any kind, background+ included. `days_with_data` is how many days of the window PostHog has read history for, not how active this+ project is. A field is missing when the subject had no reads. Use these counts and the numbers in `payload`+ to explain to the user why a view or table should be certified, deprecated or materialized before accepting.warehouse-suggestions-list:operation: warehouse_suggestions_listenabled: true@@ -61,9 +66,10 @@ tools:`payload` says what accepting would create or change. `can_act` says whether the caller can edit the view ortable, which accept, dismiss and resume require. Accepting a certify or deprecate suggestion also requiresedit access to the data catalog. Use warehouse-suggestions-get for the usage evidence behind one suggestion.- If the list is empty, call warehouse-suggestions-status to learn why. Results come strongest first within- each kind. Explain a suggestion to the user with the numbers in `payload`, the time and bytes saved or spent- per month. For a certify suggestion, use the read counts from warehouse-suggestions-get.+ If the list is empty, call warehouse-suggestions-status to learn why. Results come in priority order, the+ one most worth acting on first. Explain a suggestion to the user with the numbers in `payload`, the time and+ bytes saved or spent per month. For a certify suggestion, use the read counts in `evidence` from+ warehouse-suggestions-get.response:include:- iddiff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 46e820ac59b4..ef2abf291f2c 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -14747,7 +14747,7 @@"feature_flag": "warehouse-suggestions"},"warehouse-suggestions-get": {- "description": "Get one warehouse suggestion by id, including `evidence`: the read counts and usage window that led to it. Use this to explain to the user why a view or table should be certified, deprecated or materialized before accepting.",+ "description": "Get one warehouse suggestion by id, with the `evidence` behind it. Evidence counts reads between `evidence_window_start` and `evidence_window_end`. `human_requests` is the queries people ran on the view or table, `human_users` the distinct people, `human_days` the days with such reads, and `requests_by_surface` those queries per place, such as sql_editor, dashboard or mcp. `background_requests` is the queries PostHog ran on its own, such as cache warming and alerts. `last_read_at` is the latest read of any kind, background included. `days_with_data` is how many days of the window PostHog has read history for, not how active this project is. A field is missing when the subject had no reads. Use these counts and the numbers in `payload` to explain to the user why a view or table should be certified, deprecated or materialized before accepting.","category": "Warehouse suggestions","feature": "warehouse_suggestions","summary": "Get a warehouse suggestion",@@ -14762,7 +14762,7 @@"feature_flag": "warehouse-suggestions"},"warehouse-suggestions-list": {- "description": "Recommendations to certify, deprecate or materialize data warehouse views and tables, computed daily from how often the project reads them. Pass status=proposed for the suggestions still waiting for a decision. `payload` says what accepting would create or change. `can_act` says whether the caller can edit the view or table, which accept, dismiss and resume require. Accepting a certify or deprecate suggestion also requires edit access to the data catalog. Use warehouse-suggestions-get for the usage evidence behind one suggestion. If the list is empty, call warehouse-suggestions-status to learn why. Results come strongest first within each kind. Explain a suggestion to the user with the numbers in `payload`, the time and bytes saved or spent per month. For a certify suggestion, use the read counts from warehouse-suggestions-get.",+ "description": "Recommendations to certify, deprecate or materialize data warehouse views and tables, computed daily from how often the project reads them. Pass status=proposed for the suggestions still waiting for a decision. `payload` says what accepting would create or change. `can_act` says whether the caller can edit the view or table, which accept, dismiss and resume require. Accepting a certify or deprecate suggestion also requires edit access to the data catalog. Use warehouse-suggestions-get for the usage evidence behind one suggestion. If the list is empty, call warehouse-suggestions-status to learn why. Results come in priority order, the one most worth acting on first. Explain a suggestion to the user with the numbers in `payload`, the time and bytes saved or spent per month. For a certify suggestion, use the read counts in `evidence` from warehouse-suggestions-get.","category": "Warehouse suggestions","feature": "warehouse_suggestions","summary": "List warehouse suggestions",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 29ce1cd33112..0cff838ea15b 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -15422,7 +15422,7 @@"feature_flag": "warehouse-suggestions"},"warehouse-suggestions-get": {- "description": "Get one warehouse suggestion by id, including `evidence`: the read counts and usage window that led to it. Use this to explain to the user why a view or table should be certified, deprecated or materialized before accepting.",+ "description": "Get one warehouse suggestion by id, with the `evidence` behind it. Evidence counts reads between `evidence_window_start` and `evidence_window_end`. `human_requests` is the queries people ran on the view or table, `human_users` the distinct people, `human_days` the days with such reads, and `requests_by_surface` those queries per place, such as sql_editor, dashboard or mcp. `background_requests` is the queries PostHog ran on its own, such as cache warming and alerts. `last_read_at` is the latest read of any kind, background included. `days_with_data` is how many days of the window PostHog has read history for, not how active this project is. A field is missing when the subject had no reads. Use these counts and the numbers in `payload` to explain to the user why a view or table should be certified, deprecated or materialized before accepting.","category": "Warehouse suggestions","feature": "warehouse_suggestions","summary": "Get a warehouse suggestion",@@ -15437,7 +15437,7 @@"feature_flag": "warehouse-suggestions"},"warehouse-suggestions-list": {- "description": "Recommendations to certify, deprecate or materialize data warehouse views and tables, computed daily from how often the project reads them. Pass status=proposed for the suggestions still waiting for a decision. `payload` says what accepting would create or change. `can_act` says whether the caller can edit the view or table, which accept, dismiss and resume require. Accepting a certify or deprecate suggestion also requires edit access to the data catalog. Use warehouse-suggestions-get for the usage evidence behind one suggestion. If the list is empty, call warehouse-suggestions-status to learn why. Results come strongest first within each kind. Explain a suggestion to the user with the numbers in `payload`, the time and bytes saved or spent per month. For a certify suggestion, use the read counts from warehouse-suggestions-get.",+ "description": "Recommendations to certify, deprecate or materialize data warehouse views and tables, computed daily from how often the project reads them. Pass status=proposed for the suggestions still waiting for a decision. `payload` says what accepting would create or change. `can_act` says whether the caller can edit the view or table, which accept, dismiss and resume require. Accepting a certify or deprecate suggestion also requires edit access to the data catalog. Use warehouse-suggestions-get for the usage evidence behind one suggestion. If the list is empty, call warehouse-suggestions-status to learn why. Results come in priority order, the one most worth acting on first. Explain a suggestion to the user with the numbers in `payload`, the time and bytes saved or spent per month. For a certify suggestion, use the read counts in `evidence` from warehouse-suggestions-get.","category": "Warehouse suggestions","feature": "warehouse_suggestions","summary": "List warehouse suggestions",diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 2de400f5cc16..9295173640d4 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -78171,6 +78171,28 @@ export namespace Schemas {export type WarehouseSuggestionPayload = WarehouseSuggestionCertifyPayload | WarehouseSuggestionDeprecatePayload | WarehouseSuggestionMaterializePayload;+ /**+ * Queries people ran per place they ran them, such as sql_editor, dashboard, insight or mcp.+ */+ export type WarehouseSuggestionEvidenceRequestsBySurface = {[key: string]: number};++ export interface WarehouseSuggestionEvidence {+ /** Days of the 30-day usage window that PostHog has read history for. It counts days with reads in any project, so it shows how much history exists, not how active this project is. */+ days_with_data?: number;+ /** Queries people ran that read the subject in the usage window. */+ human_requests?: number;+ /** Distinct people who ran those queries. */+ human_users?: number;+ /** Days on which people read the subject. */+ human_days?: number;+ /** Queries PostHog ran on its own that read the subject, such as cache warming and alerts. */+ background_requests?: number;+ /** Queries people ran per place they ran them, such as sql_editor, dashboard, insight or mcp. */+ requests_by_surface?: WarehouseSuggestionEvidenceRequestsBySurface;+ /** When any query last read the subject, including queries PostHog ran on its own. */+ last_read_at?: string;+ }+export interface WarehouseSuggestionReviewer {/** User id. */id: number;@@ -78238,11 +78260,6 @@ export namespace Schemas {Unused: 'unused',} as const;- /**- * The usage numbers that led to this suggestion.- */- export type WarehouseSuggestionEvidence = { [key: string]: unknown };-/*** What accepting this suggestion created. Null until accepted.* @nullable@@ -78252,7 +78269,7 @@ export namespace Schemas {export interface WarehouseSuggestion {/** What accepting this suggestion would create or change. Shape depends on kind. */readonly payload: WarehouseSuggestionPayload;- /** The usage numbers that led to this suggestion. */+ /** The read counts that led to this suggestion. A field is missing when the subject had no reads. */evidence: WarehouseSuggestionEvidence;/*** What accepting this suggestion created. Null until accepted.@@ -78304,8 +78321,6 @@ export namespace Schemas {evidence_window_end: string;/** When the daily job last found evidence for this suggestion. */last_seen_at: string;- /** How strongly the evidence supports the suggestion. Higher comes first. */- score: number;/*** When the suggestion was first shown. Null while it waits for a slot.* @nullablediff --git a/services/mcp/tests/unit/view-get-hooks.test.ts b/services/mcp/tests/unit/view-get-hooks.test.tsindex 1288e53a5c76..02f89699459f 100644--- a/services/mcp/tests/unit/view-get-hooks.test.ts+++ b/services/mcp/tests/unit/view-get-hooks.test.ts@@ -13,7 +13,6 @@ function suggestion(canAct: boolean): Record<string, unknown> {subject_id: 'view-1',payload: { subject_name: 'orders' },status: 'proposed',- score: 3,can_act: canAct,}}