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.

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.py
index 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: Sugge
evidence_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.py
index 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: datetime
evidence_window_end: datetime
last_seen_at: datetime
- score: float
status: WarehouseSuggestionStatus
surfaced_at: datetime | None
reviewed_by: SuggestionReviewer | None
diff --git a/products/warehouse_suggestions/backend/presentation/serializers.py b/products/warehouse_suggestions/backend/presentation/serializers.py
index 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.ts
index 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 } | nu
export 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.
* @nullable
diff --git a/products/warehouse_suggestions/mcp/tools.yaml b/products/warehouse_suggestions/mcp/tools.yaml
index 30a4d4a04655..9218ef366f35 100644
--- a/products/warehouse_suggestions/mcp/tools.yaml
+++ b/products/warehouse_suggestions/mcp/tools.yaml
@@ -47,9 +47,14 @@ tools:
enabled: true
title: Get a warehouse suggestion
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.
+ 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_list
enabled: true
@@ -61,9 +66,10 @@ tools:
`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.
+ 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:
- id
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 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.json
index 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.ts
index 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.
* @nullable
diff --git a/services/mcp/tests/unit/view-get-hooks.test.ts b/services/mcp/tests/unit/view-get-hooks.test.ts
index 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,
}
}