: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(data-catalog): require overwrite to create a metric with a taken name (#118040)
Sinan Kucukkoseler16ea1d72145e
diff --git a/products/data_catalog/backend/logic/analytics.py b/products/data_catalog/backend/logic/analytics.pyindex 4e54b6f99dd2..79be5fe4f18a 100644--- a/products/data_catalog/backend/logic/analytics.py+++ b/products/data_catalog/backend/logic/analytics.py@@ -21,6 +21,7 @@ if TYPE_CHECKING:METRIC_CREATED_EVENT = "data catalog metric created"METRIC_UPDATED_EVENT = "data catalog metric updated"+METRIC_NAME_CONFLICT_EVENT = "data catalog metric name conflict"METRIC_APPROVED_EVENT = "data catalog metric approved"METRIC_APPROVAL_BLOCKED_EVENT = "data catalog metric approval blocked"METRIC_DELETED_EVENT = "data catalog metric deleted"diff --git a/products/data_catalog/backend/logic/exceptions.py b/products/data_catalog/backend/logic/exceptions.pyindex 3e1007b3bcbc..196704715adf 100644--- a/products/data_catalog/backend/logic/exceptions.py+++ b/products/data_catalog/backend/logic/exceptions.py@@ -45,3 +45,13 @@ class CatalogConflict(APIException):super().__init__(detail=detail)if extra is not None:self.extra = extra+++class MetricNameTaken(CatalogConflict):+ """A create named a live metric without ``overwrite``, or one hidden from the caller.++ ``extra.existing_metric`` holds the name and status of a visible metric. A hidden metric gets no ``extra``.+ """++ default_detail = "A metric with this name already exists. Use a different name, or overwrite the existing metric."+ default_code = "metric_name_taken"diff --git a/products/data_catalog/backend/logic/metrics.py b/products/data_catalog/backend/logic/metrics.pyindex 7eeea54475b1..9f07083d1f4d 100644--- a/products/data_catalog/backend/logic/metrics.py+++ b/products/data_catalog/backend/logic/metrics.py@@ -1,8 +1,8 @@"""Metric write path and approval lifecycle.-Names are unique among a team's live metrics: creating with a live existing name refines that metric,-while creating with a deleted metric's name starts a fresh one (delete and rename free the name for-reuse). A metric can be created from an insight+Names are unique among a team's live metrics: creating with a live existing name refines that metric+(the API requires an explicit overwrite for this), while creating with a deleted metric's name starts a+fresh one (delete and rename free the name for reuse). A metric can be created from an insight(its query is snapshotted server-side and drift is flagged for re-review). Promotion to ``approved``is blocked while a metric is drifted. All transitions emit capture events for success-criteriameasurement.@@ -37,11 +37,12 @@ from .analytics import (METRIC_APPROVED_EVENT,METRIC_CREATED_EVENT,METRIC_DELETED_EVENT,+ METRIC_NAME_CONFLICT_EVENT,METRIC_UPDATED_EVENT,capture_metric_event,)from .drift import canonical_query_hash, compute_drift, fetch_insight-from .exceptions import MetricDrifted, SourceInsightUnavailable+from .exceptions import MetricDrifted, MetricNameTaken, SourceInsightUnavailablefrom .lineage import remove_metric_lineagefrom .validation import validate_description, validate_metric_definition@@ -198,11 +199,48 @@ def _refine(metric: Metric, fields: dict) -> None:# computes or how it reads; its review no longer holds, so drop back to proposed (matching# update_metric's PATCH behavior)._reset_to_proposed(metric)+ if fields.get("created_source") == CreatedSource.USER and metric.created_source != CreatedSource.USER:+ # A person's overwrite replaces an agent's proposal, so the agent's model, confidence, and+ # reasoning no longer describe the metric unless the request supplies new values.+ fields = {"ai_model": "", "confidence": None, "reasoning": "", **fields}for key, value in fields.items():setattr(metric, key, value)metric.save()+def _denied_tables(team: Team, user: User, user_access_control: UserAccessControl) -> set[str]:+ return Database.create_for(team=team, user=user, user_access_control=user_access_control)._denied_tables+++def _live_metric_reads_tables(team: Team, name: str) -> bool:+ """True when a live metric holds ``name`` and its definition reads tables. Reads without a lock."""+ referenced = (+ Metric.objects.for_team(team.id)+ .filter(name=name, deleted=False)+ .values_list("referenced_table_names", flat=True)+ .first()+ )+ return bool(referenced)+++def _name_conflict(+ existing: Metric, *, visible: bool, team: Team, user: Optional[User], request: "Request | None"+) -> MetricNameTaken:+ """Count the conflict and build its 409.++ A hidden metric's 409 carries no metric data, so it confirms only that the name is taken.+ """+ capture_metric_event(+ METRIC_NAME_CONFLICT_EVENT, existing, team=team, user=user, request=request, extra={"existing_visible": visible}+ )+ if not visible:+ return MetricNameTaken(detail="A metric with this name already exists. Use a different name.")+ return MetricNameTaken(+ detail=f"A metric named '{existing.name}' already exists. Use a different name, or overwrite the existing metric.",+ extra={"existing_metric": {"name": existing.name, "status": existing.status}},+ )++def _schedule_lineage_sync(metric: Metric) -> None:"""Refresh the metric's lineage node after the write it belongs to commits.@@ -231,9 +269,17 @@ def upsert_metric(ai_model: str | _Unset = _UNSET,confidence: float | None | _Unset = _UNSET,reasoning: str | _Unset = _UNSET,+ overwrite: bool = False,+ user_access_control: UserAccessControl | None = None,request: "Request | None" = None,) -> Metric:- """Create a metric, or refine the live one already holding ``name`` for this team.+ """Create a metric, or with ``overwrite`` refine the live one already holding ``name`` for this team.++ Without ``overwrite``, a live metric holding ``name`` raises ``MetricNameTaken`` and stays+ unchanged, so the caller can ask a person before replacing it. With a ``user_access_control``,+ a name held by a metric hidden from ``user`` (see ``metrics_visible_to_user``) raises the same+ error for every value of ``overwrite`` and discloses nothing about that metric. Both checks run+ on the locked row, so a concurrent write cannot slip a hidden metric past them.Refine is a partial merge: only the fields the caller supplies are written, so a refine thatomits a field leaves that field (a stored ``definition``, provenance, ...) untouched rather than@@ -264,6 +310,23 @@ def upsert_metric(fields.update(_resolve_definition_fields(definition, source_insight_short_id, team, user))written_fields = set(fields)+ # The denied-table set needs the HogQL database, which is slow to build, so build it before the+ # row lock, and only when the name is held by a metric that reads tables.+ denied_tables: set[str] | None = None+ if user is not None and user_access_control is not None and _live_metric_reads_tables(team, name):+ denied_tables = _denied_tables(team, user, user_access_control)++ def refuse_taken_name(existing: Metric) -> None:+ nonlocal denied_tables+ if user is not None and user_access_control is not None and existing.referenced_table_names:+ if denied_tables is None:+ # A concurrent write gave the row its table references after the read above.+ denied_tables = _denied_tables(team, user, user_access_control)+ if references_denied_table(existing.referenced_table_names, denied_tables):+ raise _name_conflict(existing, visible=False, team=team, user=user, request=request)+ if not overwrite:+ raise _name_conflict(existing, visible=True, team=team, user=user, request=request)+# team_scope so the ModelActivityMixin's before-update lookup (via the fail-closed manager)# works regardless of caller context (viewset, Celery, MCP, tests).with team_scope(team.id):@@ -272,6 +335,7 @@ def upsert_metric(existing = Metric.objects.for_team(team.id).filter(name=name, deleted=False).select_for_update().first()created = existing is Noneif existing is not None:+ refuse_taken_name(existing)_refine(existing, fields)metric = existingelse:@@ -288,13 +352,19 @@ def upsert_metric(existing = Metric.objects.for_team(team.id).filter(name=name, deleted=False).select_for_update().first()if existing is None:raise+ refuse_taken_name(existing)_refine(existing, fields)metric, created = existing, Falseif created or written_fields & _LINEAGE_FIELDS:_schedule_lineage_sync(metric)capture_metric_event(- METRIC_CREATED_EVENT if created else METRIC_UPDATED_EVENT, metric, team=team, user=user, request=request+ METRIC_CREATED_EVENT if created else METRIC_UPDATED_EVENT,+ metric,+ team=team,+ user=user,+ request=request,+ extra=None if created else {"overwritten_by_create": True},)return metric@@ -557,11 +627,7 @@ def metrics_for_team(team: Team) -> QuerySet[Metric]:def metrics_visible_to_user(team: Team, user: User, user_access_control: UserAccessControl) -> QuerySet[Metric]:"""Live metrics whose definitions do not disclose a warehouse table the caller cannot read."""metrics = metrics_for_team(team)- denied_tables = Database.create_for(- team=team,- user=user,- user_access_control=user_access_control,- )._denied_tables+ denied_tables = _denied_tables(team, user, user_access_control)if not denied_tables:return metricsvisible_metric_ids = [diff --git a/products/data_catalog/backend/presentation/serializers.py b/products/data_catalog/backend/presentation/serializers.pyindex 4e485906982e..48764ec2f282 100644--- a/products/data_catalog/backend/presentation/serializers.py+++ b/products/data_catalog/backend/presentation/serializers.py@@ -219,6 +219,52 @@ class MetricSerializer(serializers.ModelSerializer):return api.compute_drift([obj])[obj.id]+@extend_schema_serializer(component_name="DataCatalogMetricCreate")+class MetricCreateSerializer(MetricSerializer):+ """Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name."""++ overwrite = serializers.BooleanField(+ required=False,+ default=False,+ write_only=True,+ help_text="Replace the fields of the live metric that already holds this name. When false, a taken name "+ "returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an "+ "approved metric with a changed name, description, unit, or definition resets it to 'proposed'.",+ )++ class Meta(MetricSerializer.Meta):+ fields = [*MetricSerializer.Meta.fields, "overwrite"]+++@extend_schema_serializer(component_name="DataCatalogMetricNameConflictExisting")+class MetricNameConflictExistingSerializer(serializers.Serializer):+ """The live metric that holds the name a create was sent with."""++ name = serializers.CharField(help_text="Name of the existing metric.")+ status = serializers.CharField(help_text="Lifecycle state of the existing metric: 'proposed' or 'approved'.")+++@extend_schema_serializer(component_name="DataCatalogMetricNameConflictExtra")+class MetricNameConflictExtraSerializer(serializers.Serializer):+ existing_metric = MetricNameConflictExistingSerializer(+ help_text="The metric that holds the name. Send overwrite true to replace it."+ )+++@extend_schema_serializer(component_name="DataCatalogMetricNameConflict")+class MetricNameConflictSerializer(serializers.Serializer):+ """The 409 body of a create whose name a live metric already holds."""++ type = serializers.CharField(help_text="Error class the API attaches to every error body.")+ code = serializers.CharField(help_text="Always 'metric_name_taken'.")+ detail = serializers.CharField(help_text="Human-readable reason, safe to show as is.")+ attr = serializers.CharField(allow_null=True, help_text="Always null: the conflict is not tied to one field.")+ extra = MetricNameConflictExtraSerializer(+ required=False,+ help_text="Absent when the existing metric is hidden from the caller because it reads a table they cannot access.",+ )++@extend_schema_serializer(component_name="DataCatalogMetricBulkNamesRequest")class MetricBulkNamesRequestSerializer(serializers.Serializer):"""Input for the bulk metric actions: the metric names to act on."""diff --git a/products/data_catalog/backend/presentation/views.py b/products/data_catalog/backend/presentation/views.pyindex 56a349ca8377..7fdf0df49c77 100644--- a/products/data_catalog/backend/presentation/views.py+++ b/products/data_catalog/backend/presentation/views.py@@ -40,6 +40,8 @@ from .serializers import (MetricBulkApproveResponseSerializer,MetricBulkDeleteResponseSerializer,MetricBulkNamesRequestSerializer,+ MetricCreateSerializer,+ MetricNameConflictSerializer,MetricRunQuerySerializer,MetricRunRequestSerializer,MetricRunResponseSerializer,@@ -172,11 +174,25 @@ class MetricViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):return self.get_paginated_response(serializer.data)return Response(serializer.data)- @extend_schema(description="Create a metric, or refine the one already holding this name for the team.")+ @extend_schema(+ description="Create a metric. When a live metric already holds the name, returns 409 unless overwrite "+ "is true, in which case the existing metric is refined with the fields sent.",+ request=MetricCreateSerializer,+ responses={+ 201: MetricSerializer,+ 409: OpenApiResponse(+ response=MetricNameConflictSerializer,+ description="A live metric already holds this name (code 'metric_name_taken'). "+ "extra.existing_metric holds its name and status, unless the metric is hidden from the caller. "+ "Send overwrite true to replace a visible metric.",+ ),+ },+ )def create(self, request: Request, *args, **kwargs) -> Response:- serializer = self.get_serializer(data=request.data)+ serializer = MetricCreateSerializer(data=request.data, context=self.get_serializer_context())serializer.is_valid(raise_exception=True)data = serializer.validated_data+ user = cast(User, request.user)# Pass only the fields the client actually sent, so an upsert that refines an existing metric# leaves omitted fields (a stored definition, provenance, ...) untouched rather than resetting them.optional = {@@ -195,9 +211,11 @@ class MetricViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):}metric = api.upsert_metric(team=self.team,- user=cast(User, request.user),+ user=user,name=data["name"],description=data["description"],+ overwrite=data["overwrite"],+ user_access_control=self.user_access_control,request=request,**optional,)diff --git a/products/data_catalog/backend/tests/test_api.py b/products/data_catalog/backend/tests/test_api.pyindex 5379722c2556..6fa4c9be5af6 100644--- a/products/data_catalog/backend/tests/test_api.py+++ b/products/data_catalog/backend/tests/test_api.py@@ -87,17 +87,25 @@ class TestMetricAPI(APIBaseTest):assert response.json()["attr"] == "description"assert response.json()["detail"] == DESCRIPTION_TOO_LONG_MESSAGE- def test_create_is_upsert_on_name(self) -> None:+ def test_create_with_taken_name_conflicts_until_overwrite(self) -> None:self.client.post(self.url, {"name": "mrr", "description": "v1"}, format="json")- response = self.client.post(self.url, {"name": "mrr", "description": "v2"}, format="json")- assert response.status_code == status.HTTP_201_CREATED++ conflict = self.client.post(self.url, {"name": "mrr", "description": "v2"}, format="json")+ assert conflict.status_code == status.HTTP_409_CONFLICT, conflict.json()+ assert conflict.json()["code"] == "metric_name_taken"+ assert conflict.json()["extra"] == {"existing_metric": {"name": "mrr", "status": MetricStatus.PROPOSED}}+ assert self.client.get(f"{self.url}mrr/").json()["description"] == "v1"++ response = self.client.post(self.url, {"name": "mrr", "description": "v2", "overwrite": True}, format="json")+ assert response.status_code == status.HTTP_201_CREATED, response.json()+ assert "overwrite" not in response.json()assert Metric.objects.for_team(self.team.id).count() == 1assert self.client.get(f"{self.url}mrr/").json()["description"] == "v2"def test_refine_via_post_preserves_omitted_definition(self) -> None:definition = {"kind": "HogQLQuery", "query": "select count() from events"}self.client.post(self.url, {"name": "mrr", "description": "v1", "definition": definition}, format="json")- response = self.client.post(self.url, {"name": "mrr", "description": "v2"}, format="json")+ response = self.client.post(self.url, {"name": "mrr", "description": "v2", "overwrite": True}, format="json")assert response.status_code == status.HTTP_201_CREATED, response.json()body = self.client.get(f"{self.url}mrr/").json()assert body["description"] == "v2"@@ -207,6 +215,22 @@ class TestMetricAPI(APIBaseTest):assert names == ["allowed"]assert self.client.get(f"{self.url}hidden/").status_code == status.HTTP_404_NOT_FOUND+ for overwrite in (False, True):+ conflict = self.client.post(+ self.url, {"name": "hidden", "description": "taken over", "overwrite": overwrite}, format="json"+ )+ assert conflict.status_code == status.HTTP_409_CONFLICT, conflict.json()+ assert "extra" not in conflict.json()+ assert Metric.objects.for_team(self.team.id).get(pk=hidden["id"]).description == "d"++ conflict = self.client.post(self.url, {"name": "allowed", "description": "taken over"}, format="json")+ assert conflict.status_code == status.HTTP_409_CONFLICT, conflict.json()+ assert conflict.json()["extra"] == {"existing_metric": {"name": "allowed", "status": MetricStatus.PROPOSED}}+ overwritten = self.client.post(+ self.url, {"name": "allowed", "description": "taken over", "overwrite": True}, format="json"+ )+ assert overwritten.status_code == status.HTTP_201_CREATED, overwritten.json()+ assert overwritten.json()["description"] == "taken over"class TestMetricLifecycleAPI(APIBaseTest):diff --git a/products/data_catalog/backend/tests/test_lineage.py b/products/data_catalog/backend/tests/test_lineage.pyindex 7442520476ec..6a99916c439f 100644--- a/products/data_catalog/backend/tests/test_lineage.py+++ b/products/data_catalog/backend/tests/test_lineage.py@@ -198,7 +198,7 @@ class TestSyncMetricLineage(BaseTest):task.delay.reset_mock()with self.captureOnCommitCallbacks(execute=True):- upsert_metric(team=self.team, user=self.user, name="mrr", description="what it counts")+ upsert_metric(team=self.team, user=self.user, name="mrr", description="what it counts", overwrite=True)task.delay.assert_not_called()diff --git a/products/data_catalog/backend/tests/test_logic.py b/products/data_catalog/backend/tests/test_logic.pyindex e4f30bcd1f72..71d3b49cc14e 100644--- a/products/data_catalog/backend/tests/test_logic.py+++ b/products/data_catalog/backend/tests/test_logic.py@@ -12,7 +12,7 @@ from products.access_control.backend.models.access_control import AccessControlfrom products.data_catalog.backend.facade.enums import CreatedSource, MetricStatusfrom products.data_catalog.backend.logic import metricsfrom products.data_catalog.backend.logic.drift import compute_drift-from products.data_catalog.backend.logic.exceptions import MetricDrifted, SourceInsightUnavailable+from products.data_catalog.backend.logic.exceptions import MetricDrifted, MetricNameTaken, SourceInsightUnavailablefrom products.data_catalog.backend.logic.metrics import (approve_metric,approved_metric_names_for_team,@@ -41,25 +41,34 @@ class TestMetricUpsert(BaseTest):def test_same_name_refines_not_duplicates(self) -> None:first = self._upsert("mrr", description="v1")- second = self._upsert("mrr", description="v2")+ second = self._upsert("mrr", description="v2", overwrite=True)assert first.id == second.idassert Metric.objects.for_team(self.team.id).count() == 1assert Metric.objects.for_team(self.team.id).get().description == "v2"- def test_refine_leaves_unspecified_fields_untouched(self) -> None:+ @parameterized.expand(+ [+ ("source_omitted", {}, (CreatedSource.AI_GENERATED, "claude", 0.8, "counts events")),+ ("user_takes_over", {"created_source": CreatedSource.USER}, (CreatedSource.USER, "", None, "")),+ ]+ )+ def test_refine_keeps_omitted_fields_except_ai_provenance_when_a_user_takes_over(+ self, _name: str, overrides: dict, expected_provenance: tuple+ ) -> None:self._upsert("mrr",created_source=CreatedSource.AI_GENERATED,ai_model="claude",+ confidence=0.8,+ reasoning="counts events",definition={"kind": "HogQLQuery", "query": "select count() from events"},)- refined = self._upsert("mrr", description="v2")+ refined = self._upsert("mrr", description="v2", overwrite=True, **overrides)assert refined.description == "v2"assert refined.definition is not Noneassert refined.definition["kind"] == "HogQLQuery"assert refined.referenced_table_names == ["events"]- assert refined.created_source == CreatedSource.AI_GENERATED- assert refined.ai_model == "claude"+ assert (refined.created_source, refined.ai_model, refined.confidence, refined.reasoning) == expected_provenancedef test_upsert_after_delete_creates_fresh_metric(self) -> None:metric = self._upsert("mrr", definition=_HOGQL_A)@@ -83,9 +92,10 @@ class TestMetricUpsert(BaseTest):self._upsert("arr", description="x" * (MAX_DESCRIPTION_LENGTH + 1))assert "description" in ctx.exception.detail- def test_concurrent_create_retries_to_single_row(self) -> None:+ @parameterized.expand([("overwrite", True), ("no_overwrite", False)])+ def test_concurrent_create_retries_to_single_row(self, _name: str, overwrite: bool) -> None:# Simulate the race: the pre-check misses, create hits the unique constraint (IntegrityError),- # and the retry finds and refines the row the other writer created. Guards the except branch.+ # and the retry finds the row the other writer created. Guards the except branch.winner = self._upsert("mrr", description="winner")mock_qs = MagicMock()@@ -93,9 +103,13 @@ class TestMetricUpsert(BaseTest):mock_qs.create.side_effect = IntegrityError("duplicate key")with patch.object(metrics.Metric.objects, "for_team", return_value=mock_qs):- result = self._upsert("mrr", description="racer")+ if overwrite:+ result = self._upsert("mrr", description="racer", overwrite=True)+ assert result.id == winner.id+ else:+ with self.assertRaises(MetricNameTaken):+ self._upsert("mrr", description="racer", overwrite=False)- assert result.id == winner.idassert Metric.objects.for_team(self.team.id).count() == 1@@ -428,14 +442,18 @@ class TestUpdateResetsApproval(BaseTest):def test_refine_definition_resets_approval(self) -> None:metric = upsert_metric(team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_A)approve_metric(metric, self.user)- refined = upsert_metric(team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_B)+ refined = upsert_metric(+ team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_B, overwrite=True+ )assert refined.status == MetricStatus.PROPOSEDassert refined.approved_by_id is Nonedef test_refine_cosmetic_change_keeps_approval(self) -> None:metric = upsert_metric(team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_A)approve_metric(metric, self.user)- refined = upsert_metric(team=self.team, user=self.user, name="mrr", description="d", display_name="MRR")+ refined = upsert_metric(+ team=self.team, user=self.user, name="mrr", description="d", display_name="MRR", overwrite=True+ )assert refined.status == MetricStatus.APPROVEDdef test_refine_description_change_resets_approval(self) -> None:@@ -443,7 +461,9 @@ class TestUpdateResetsApproval(BaseTest):# definition-less metric means, so its approval must not carry over.metric = upsert_metric(team=self.team, user=self.user, name="mrr", description="d")approve_metric(metric, self.user)- refined = upsert_metric(team=self.team, user=self.user, name="mrr", description="a different meaning")+ refined = upsert_metric(+ team=self.team, user=self.user, name="mrr", description="a different meaning", overwrite=True+ )assert refined.status == MetricStatus.PROPOSEDassert refined.approved_by_id is None@@ -518,7 +538,9 @@ class TestUpdateInsightLink(BaseTest):if path == "update":edited = update_metric(metric, team=self.team, user=self.user, definition=_HOGQL_B)else:- edited = upsert_metric(team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_B)+ edited = upsert_metric(+ team=self.team, user=self.user, name="mrr", description="d", definition=_HOGQL_B, overwrite=True+ )assert edited.source_insight_short_id is Noneassert edited.source_insight_query_hash is Nonediff --git a/products/data_catalog/evals/seeders.py b/products/data_catalog/evals/seeders.pyindex 921df4e9e19d..6e9b459758f4 100644--- a/products/data_catalog/evals/seeders.py+++ b/products/data_catalog/evals/seeders.py@@ -160,6 +160,7 @@ def seed_approved_metric(context: CustomPromptSandboxContext) -> dict[str, Any]:description=APPROVED_METRIC_DESCRIPTION,unit="usd",definition=APPROVED_METRIC_DEFINITION,+ overwrite=True,)approve_metric(metric, user)return {@@ -214,6 +215,7 @@ def _seed_top_customers_metric(description=TOP_CUSTOMERS_METRIC_DESCRIPTION,unit="usd",definition=definition,+ overwrite=True,)approve_metric(metric, user)return team, user@@ -242,6 +244,7 @@ def seed_ambiguous_top_customers_metrics(context: CustomPromptSandboxContext) ->description=CURRENT_TOP_CUSTOMERS_METRIC_DESCRIPTION,unit="usd",definition=CURRENT_TOP_CUSTOMERS_METRIC_DEFINITION,+ overwrite=True,)approve_metric(current_metric, user)return {@@ -274,6 +277,7 @@ def seed_operational_metric(context: CustomPromptSandboxContext) -> dict[str, Andescription=OPERATIONAL_METRIC_DESCRIPTION,unit="percent",definition=OPERATIONAL_METRIC_DEFINITION,+ overwrite=True,)approve_metric(metric, user)return {@@ -305,6 +309,7 @@ def _seed_named_operational_metric(description=description,unit=unit,definition=definition,+ overwrite=True,)approve_metric(metric, user)return {"metric": {"name": name, "status": "approved", "is_drifted": False}}@@ -417,6 +422,7 @@ def seed_ambiguous_customer_count_metrics(context: CustomPromptSandboxContext) -description=description,unit="customers",definition=definition,+ overwrite=True,)approve_metric(metric, user)return {@@ -437,6 +443,7 @@ def seed_proposed_growth_with_approved_mrr(context: CustomPromptSandboxContext)description=APPROVED_METRIC_DESCRIPTION,unit="usd",definition=APPROVED_METRIC_DEFINITION,+ overwrite=True,)approve_metric(approved, user)upsert_metric(@@ -447,6 +454,7 @@ def seed_proposed_growth_with_approved_mrr(context: CustomPromptSandboxContext)description=YOY_MRR_GROWTH_METRIC_DESCRIPTION,unit="percent",definition=YOY_MRR_GROWTH_METRIC_DEFINITION,+ overwrite=True,)return {"metrics": [@@ -464,6 +472,7 @@ def seed_proposed_metric(context: CustomPromptSandboxContext) -> dict[str, Any]:name=PROPOSED_METRIC_NAME,description=PROPOSED_METRIC_DESCRIPTION,definition=PROPOSED_METRIC_DEFINITION,+ overwrite=True,)return {"metric": {"name": PROPOSED_METRIC_NAME, "status": "proposed"}}@@ -477,6 +486,7 @@ def seed_drifted_metric(context: CustomPromptSandboxContext) -> dict[str, Any]:name=DRIFTED_METRIC_NAME,description=DRIFTED_METRIC_DESCRIPTION,source_insight_short_id=insight.short_id,+ overwrite=True,)approve_metric(metric, user)# Mutating the source insight after approval is what makes the metric read as drifted.@@ -511,6 +521,7 @@ def seed_metric_listing_catalog(context: CustomPromptSandboxContext) -> dict[strdescription=APPROVED_METRIC_DESCRIPTION,unit="usd",definition=APPROVED_METRIC_DEFINITION,+ overwrite=True,)approve_metric(approved, user)upsert_metric(@@ -519,6 +530,7 @@ def seed_metric_listing_catalog(context: CustomPromptSandboxContext) -> dict[strname=PROPOSED_METRIC_NAME,description=PROPOSED_METRIC_DESCRIPTION,definition=PROPOSED_METRIC_DEFINITION,+ overwrite=True,)for insight_name in DECOY_INSIGHT_NAMES:Insight.objects.create(team=team, created_by=user, name=insight_name, query=DRIFTED_INSIGHT_ORIGINAL_QUERY)diff --git a/products/data_catalog/frontend/generated/api.schemas.ts b/products/data_catalog/frontend/generated/api.schemas.tsindex a0fd00b9ecd4..77ab4c40ce6b 100644--- a/products/data_catalog/frontend/generated/api.schemas.ts+++ b/products/data_catalog/frontend/generated/api.schemas.ts@@ -247,6 +247,136 @@ export interface PaginatedDataCatalogMetricListApi {results: DataCatalogMetricApi[]}+/**+ * Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.+ * @nullable+ */+export type DataCatalogMetricCreateApiDefinition = { [key: string]: unknown } | null++/**+ * Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name.+ */+export interface DataCatalogMetricCreateApi {+ readonly id: string+ /**+ * Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving.+ * @maxLength 128+ * @pattern ^[A-Za-z][A-Za-z0-9_]*$+ */+ name: string+ /**+ * Human-friendly label. Mutable, unlike name.+ * @maxLength 255+ */+ display_name?: string+ /**+ * What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'.+ * @maxLength 300+ */+ description: string+ /**+ * Unit of the result, e.g. usd, percent, cents.+ * @maxLength 64+ */+ unit?: string+ /**+ * Email of the human accountable for this metric, or null.+ * @nullable+ */+ readonly owner: string | null+ /**+ * Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.+ * @nullable+ */+ definition?: DataCatalogMetricCreateApiDefinition+ /**+ * Query kind of the definition (HogQLQuery, TrendsQuery, ...), or null for a stub.+ * @nullable+ */+ readonly definition_kind: string | null+ /** Tables the definition directly references, extracted at write time for the catalog's denied-table filter. */+ readonly referenced_table_names: unknown+ /** Persisted lifecycle state: 'proposed' or 'approved'. Drift is reported separately. */+ readonly status: string+ /** True when the definition has drifted from its linked source insight (or the insight is gone). */+ readonly is_drifted: boolean+ /** @nullable */+ readonly approved_at: string | null+ /** User who approved this metric as canonical, or null. */+ readonly approved_by: UserBasicApi | null+ /**+ * Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition.+ * @maxLength 12+ * @nullable+ */+ source_insight_short_id?: string | null+ /**+ * When the metric was last run (30-minute throttle).+ * @nullable+ */+ readonly last_run_at: string | null+ /** Whether a human ('user') or an agent ('ai_generated') authored this metric.+ *+ * * `user` - user+ * * `ai_generated` - ai_generated */+ created_source?: CreatedSourceEnumApi+ /**+ * Model that generated the metric, if AI-authored.+ * @maxLength 128+ */+ ai_model?: string+ /**+ * AI author's confidence in the proposal, 0-1.+ * @minimum 0+ * @maximum 1+ * @nullable+ */+ confidence?: number | null+ /** Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. */+ reasoning?: string+ /** User who first created this metric. */+ readonly created_by: UserBasicApi+ readonly created_at: string+ /** @nullable */+ readonly updated_at: string | null+ /** Replace the fields of the live metric that already holds this name. When false, a taken name returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an approved metric with a changed name, description, unit, or definition resets it to 'proposed'. */+ overwrite?: boolean+}++/**+ * The live metric that holds the name a create was sent with.+ */+export interface DataCatalogMetricNameConflictExistingApi {+ /** Name of the existing metric. */+ name: string+ /** Lifecycle state of the existing metric: 'proposed' or 'approved'. */+ status: string+}++export interface DataCatalogMetricNameConflictExtraApi {+ /** The metric that holds the name. Send overwrite true to replace it. */+ existing_metric: DataCatalogMetricNameConflictExistingApi+}++/**+ * The 409 body of a create whose name a live metric already holds.+ */+export interface DataCatalogMetricNameConflictApi {+ /** Error class the API attaches to every error body. */+ type: string+ /** Always 'metric_name_taken'. */+ code: string+ /** Human-readable reason, safe to show as is. */+ detail: string+ /**+ * Always null: the conflict is not tied to one field.+ * @nullable+ */+ attr: string | null+ /** Absent when the existing metric is hidden from the caller because it reads a table they cannot access. */+ extra?: DataCatalogMetricNameConflictExtraApi+}+/*** Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.* @nullablediff --git a/products/data_catalog/frontend/generated/api.ts b/products/data_catalog/frontend/generated/api.tsindex 596062d184af..768bd04b1806 100644--- a/products/data_catalog/frontend/generated/api.ts+++ b/products/data_catalog/frontend/generated/api.ts@@ -16,6 +16,7 @@ import type {DataCatalogMetricBulkApproveApi,DataCatalogMetricBulkDeleteApi,DataCatalogMetricBulkNamesRequestApi,+ DataCatalogMetricCreateApi,DataCatalogMetricRunApi,DataCatalogMetricRunRequestApi,DataCatalogMetricsListParams,@@ -209,18 +210,18 @@ export const getDataCatalogMetricsCreateUrl = (projectId: string) => {}/**- * Create a metric, or refine the one already holding this name for the team.+ * Create a metric. When a live metric already holds the name, returns 409 unless overwrite is true, in which case the existing metric is refined with the fields sent.*/export const dataCatalogMetricsCreate = async (projectId: string,- dataCatalogMetricApi: NonReadonly<DataCatalogMetricApi>,+ dataCatalogMetricCreateApi: NonReadonly<DataCatalogMetricCreateApi>,options?: RequestInit): Promise<DataCatalogMetricApi> => {return apiMutator<DataCatalogMetricApi>(getDataCatalogMetricsCreateUrl(projectId), {...options,method: 'POST',headers: { 'Content-Type': 'application/json', ...options?.headers },- body: JSON.stringify(dataCatalogMetricApi),+ body: JSON.stringify(dataCatalogMetricCreateApi),})}diff --git a/products/data_catalog/frontend/generated/api.zod.ts b/products/data_catalog/frontend/generated/api.zod.tsindex 9e9f7c6dca84..95ee0217c832 100644--- a/products/data_catalog/frontend/generated/api.zod.ts+++ b/products/data_catalog/frontend/generated/api.zod.ts@@ -32,7 +32,7 @@ export const DataCatalogCertificationsCreateBody = /* @__PURE__ */ zod.describe('Input for proposing a certification: address the target by id or (convenience) by name.')/**- * Create a metric, or refine the one already holding this name for the team.+ * Create a metric. When a live metric already holds the name, returns 409 unless overwrite is true, in which case the existing metric is refined with the fields sent.*/export const dataCatalogMetricsCreateBodyNameMax = 128@@ -50,66 +50,78 @@ export const dataCatalogMetricsCreateBodyAiModelMax = 128export const dataCatalogMetricsCreateBodyConfidenceMin = 0export const dataCatalogMetricsCreateBodyConfidenceMax = 1-export const DataCatalogMetricsCreateBody = /* @__PURE__ */ zod.object({- name: zod- .string()- .max(dataCatalogMetricsCreateBodyNameMax)- .regex(dataCatalogMetricsCreateBodyNameRegExp)- .describe(- "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."- ),- display_name: zod- .string()- .max(dataCatalogMetricsCreateBodyDisplayNameMax)- .optional()- .describe('Human-friendly label. Mutable, unlike name.'),- description: zod- .string()- .max(dataCatalogMetricsCreateBodyDescriptionMax)- .describe(- "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."- ),- unit: zod- .string()- .max(dataCatalogMetricsCreateBodyUnitMax)- .optional()- .describe('Unit of the result, e.g. usd, percent, cents.'),- definition: zod- .record(zod.string(), zod.unknown())- .nullish()- .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),- source_insight_short_id: zod- .string()- .max(dataCatalogMetricsCreateBodySourceInsightShortIdMax)- .nullish()- .describe(- "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."- ),- created_source: zod- .enum(['user', 'ai_generated'])- .describe('\* `user` - user\n\* `ai_generated` - ai_generated')- .optional()- .describe(- "Whether a human ('user') or an agent ('ai_generated') authored this metric.\n\n\* `user` - user\n\* `ai_generated` - ai_generated"- ),- ai_model: zod- .string()- .max(dataCatalogMetricsCreateBodyAiModelMax)- .optional()- .describe('Model that generated the metric, if AI-authored.'),- confidence: zod- .number()- .min(dataCatalogMetricsCreateBodyConfidenceMin)- .max(dataCatalogMetricsCreateBodyConfidenceMax)- .nullish()- .describe("AI author's confidence in the proposal, 0-1."),- reasoning: zod- .string()- .optional()- .describe(- 'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'- ),-})+export const dataCatalogMetricsCreateBodyOverwriteDefault = false++export const DataCatalogMetricsCreateBody = /* @__PURE__ */ zod+ .object({+ name: zod+ .string()+ .max(dataCatalogMetricsCreateBodyNameMax)+ .regex(dataCatalogMetricsCreateBodyNameRegExp)+ .describe(+ "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."+ ),+ display_name: zod+ .string()+ .max(dataCatalogMetricsCreateBodyDisplayNameMax)+ .optional()+ .describe('Human-friendly label. Mutable, unlike name.'),+ description: zod+ .string()+ .max(dataCatalogMetricsCreateBodyDescriptionMax)+ .describe(+ "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."+ ),+ unit: zod+ .string()+ .max(dataCatalogMetricsCreateBodyUnitMax)+ .optional()+ .describe('Unit of the result, e.g. usd, percent, cents.'),+ definition: zod+ .record(zod.string(), zod.unknown())+ .nullish()+ .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),+ source_insight_short_id: zod+ .string()+ .max(dataCatalogMetricsCreateBodySourceInsightShortIdMax)+ .nullish()+ .describe(+ "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."+ ),+ created_source: zod+ .enum(['user', 'ai_generated'])+ .describe('\* `user` - user\n\* `ai_generated` - ai_generated')+ .optional()+ .describe(+ "Whether a human ('user') or an agent ('ai_generated') authored this metric.\n\n\* `user` - user\n\* `ai_generated` - ai_generated"+ ),+ ai_model: zod+ .string()+ .max(dataCatalogMetricsCreateBodyAiModelMax)+ .optional()+ .describe('Model that generated the metric, if AI-authored.'),+ confidence: zod+ .number()+ .min(dataCatalogMetricsCreateBodyConfidenceMin)+ .max(dataCatalogMetricsCreateBodyConfidenceMax)+ .nullish()+ .describe("AI author's confidence in the proposal, 0-1."),+ reasoning: zod+ .string()+ .optional()+ .describe(+ 'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'+ ),+ overwrite: zod+ .boolean()+ .default(dataCatalogMetricsCreateBodyOverwriteDefault)+ .describe(+ "Replace the fields of the live metric that already holds this name. When false, a taken name returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an approved metric with a changed name, description, unit, or definition resets it to 'proposed'."+ ),+ })+ .describe(+ 'Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name.'+ )/*** CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).diff --git a/products/data_catalog/mcp/tools.yaml b/products/data_catalog/mcp/tools.yamlindex 346f9114b51a..4cf5dc97d817 100644--- a/products/data_catalog/mcp/tools.yaml+++ b/products/data_catalog/mcp/tools.yaml@@ -100,33 +100,42 @@ tools:readOnly: falsedestructive: falseidempotent: true- title: Create or refine a catalog metric+ title: Create a catalog metricdescription: >- Create a canonical metric, or refine the live one already holding this name (upsert on name; always lands- 'proposed'). A deleted metric's name is available again - creating with it starts a fresh metric with no- history carried over. The definition can be an executable query (HogQLQuery / TrendsQuery / FunnelsQuery /- an event node) that the query runner computes, OR an agent-calculated markdown definition - {"kind":- "MarkdownDefinition", "markdown": "<numbered steps to calculate the metric>"} - which an agent follows to- produce the number. Prefer an executable definition when the metric is deterministic; use a markdown- definition when the calculation needs judgment or multiple steps. Only propose a definition that was- explicitly asked for or that you have seen reused at least twice - do not speculatively catalog one-off- queries. If you derived a number or settled a definition and no metric exists for it, end your answer by- offering to save it as a proposed metric. Keep 'description' to 1-2 short sentences under 300 characters:- what the number is and its grain, plus any inclusion or exclusion that changes it. Leave out source tables- or views, lineage, column lists, upstream corrections, and comparisons with or pointers to other metrics.- Never walk through the query or calculation steps (the definition carries those). Put why the definition is- shaped this way in 'reasoning', in 1-3 short sentences: the main design decisions and trade-offs, such as- the source table or view, a filter or exclusion, the grain, or an approximation. Leave out the use case, who- asked, run results, validation figures, and edit history. Before creating a metric, inspect the complete- catalog with metric-list and inspect a candidate's definition with metric-describe when it may be reusable.- When the metric comes from an existing saved insight, pass that insight's 'source_insight_short_id' instead- of copying its query into 'definition' - the two are mutually exclusive. The server snapshots the insight's- query, tracks drift against it, and the metric then links back to the insight so a person can edit the query- where it lives.+ Create a canonical metric (always lands 'proposed'). If a live metric already holds the name, the call fails+ with a 409 'metric_name_taken' error, and the existing metric stays unchanged. Never overwrite on your own:+ tell the user that the name is taken, show them the existing metric with metric-describe, and ask whether to+ overwrite it, use a different name, or edit the existing metric with data-catalog-metric-update. Only after+ the user explicitly agrees to overwrite, call this tool again with 'overwrite' set to true. Overwriting an+ approved metric with a changed meaning resets it to 'proposed'. A deleted metric's name is available again -+ creating with it starts a fresh metric with no history carried over. The definition can be an executable+ query (HogQLQuery / TrendsQuery / FunnelsQuery / an event node) that the query runner computes, OR an+ agent-calculated markdown definition - {"kind": "MarkdownDefinition", "markdown": "<numbered steps to+ calculate the metric>"} - which an agent follows to produce the number. Prefer an executable definition when+ the metric is deterministic; use a markdown definition when the calculation needs judgment or multiple+ steps. Only propose a definition that was explicitly asked for or that you have seen reused at least twice -+ do not speculatively catalog one-off queries. If you derived a number or settled a definition and no metric+ exists for it, end your answer by offering to save it as a proposed metric. Keep 'description' to 1-2 short+ sentences under 300 characters: what the number is and its grain, plus any inclusion or exclusion that+ changes it. Leave out source tables or views, lineage, column lists, upstream corrections, and comparisons+ with or pointers to other metrics. Never walk through the query or calculation steps (the definition carries+ those). Put why the definition is shaped this way in 'reasoning', in 1-3 short sentences: the main design+ decisions and trade-offs, such as the source table or view, a filter or exclusion, the grain, or an+ approximation. Leave out the use case, who asked, run results, validation figures, and edit history. Before+ creating a metric, inspect the complete catalog with metric-list and inspect a candidate's definition with+ metric-describe when it may be reusable. When the metric comes from an existing saved insight, pass that+ insight's 'source_insight_short_id' instead of copying its query into 'definition' - the two are mutually+ exclusive. The server snapshots the insight's query, tracks drift against it, and the metric then links back+ to the insight so a person can edit the query where it lives.exclude_params:- created_sourceinject_body:created_source: ai_generated+ param_overrides:+ overwrite:+ description: >+ Set to true only after the user explicitly agreed to overwrite the live metric that already holds+ this name. Leave it unset on the first call.data-catalog-metric-delete:operation: data_catalog_metrics_destroyenabled: truediff --git a/products/data_quality/backend/tests/test_runner.py b/products/data_quality/backend/tests/test_runner.pyindex 63ef15775c24..c1ca04855338 100644--- a/products/data_quality/backend/tests/test_runner.py+++ b/products/data_quality/backend/tests/test_runner.py@@ -165,6 +165,7 @@ class TestCheckRunner(BaseTest):name="revenue",description="Revenue",definition={"kind": "HogQLQuery", "query": "SELECT 1 AS replacement"},+ overwrite=True,)outcome = run_check(check, self.suite_run, self.team)assert outcome.status == CheckRunStatus.ERROREDdiff --git a/products/data_quality/backend/tests/test_subject_access.py b/products/data_quality/backend/tests/test_subject_access.pyindex 159921b3e07c..5e00661a702d 100644--- a/products/data_quality/backend/tests/test_subject_access.py+++ b/products/data_quality/backend/tests/test_subject_access.py@@ -421,6 +421,7 @@ class TestMetricSubjectAccess(BaseTest):name="revenue",description="Revenue",definition={"kind": "HogQLQuery", "query": "SELECT 1 AS amount"},+ overwrite=True,)if engine_fails:raise RuntimeError("Query execution failed")diff --git a/products/data_quality/backend/tests/test_subjects.py b/products/data_quality/backend/tests/test_subjects.pyindex 1ddb37ee3fea..945fba6f6c3b 100644--- a/products/data_quality/backend/tests/test_subjects.py+++ b/products/data_quality/backend/tests/test_subjects.py@@ -41,6 +41,7 @@ class TestSubjectResolver(BaseTest):name="revenue",description="Revenue",definition={"kind": "HogQLQuery", "query": "SELECT 2"},+ overwrite=True,)updated = resolve_subject(self.team.id, "metric", metric.id)assert updated.metric_definition is not Nonediff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 5f526492c2c2..470830dfb205 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -4093,11 +4093,11 @@}},"data-catalog-metric-create": {- "description": "Create a canonical metric, or refine the live one already holding this name (upsert on name; always lands 'proposed'). A deleted metric's name is available again - creating with it starts a fresh metric with no history carried over. The definition can be an executable query (HogQLQuery / TrendsQuery / FunnelsQuery / an event node) that the query runner computes, OR an agent-calculated markdown definition - {\"kind\": \"MarkdownDefinition\", \"markdown\": \"<numbered steps to calculate the metric>\"} - which an agent follows to produce the number. Prefer an executable definition when the metric is deterministic; use a markdown definition when the calculation needs judgment or multiple steps. Only propose a definition that was explicitly asked for or that you have seen reused at least twice - do not speculatively catalog one-off queries. If you derived a number or settled a definition and no metric exists for it, end your answer by offering to save it as a proposed metric. Keep 'description' to 1-2 short sentences under 300 characters: what the number is and its grain, plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, upstream corrections, and comparisons with or pointers to other metrics. Never walk through the query or calculation steps (the definition carries those). Put why the definition is shaped this way in 'reasoning', in 1-3 short sentences: the main design decisions and trade-offs, such as the source table or view, a filter or exclusion, the grain, or an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. Before creating a metric, inspect the complete catalog with metric-list and inspect a candidate's definition with metric-describe when it may be reusable. When the metric comes from an existing saved insight, pass that insight's 'source_insight_short_id' instead of copying its query into 'definition' - the two are mutually exclusive. The server snapshots the insight's query, tracks drift against it, and the metric then links back to the insight so a person can edit the query where it lives.",+ "description": "Create a canonical metric (always lands 'proposed'). If a live metric already holds the name, the call fails with a 409 'metric_name_taken' error, and the existing metric stays unchanged. Never overwrite on your own: tell the user that the name is taken, show them the existing metric with metric-describe, and ask whether to overwrite it, use a different name, or edit the existing metric with data-catalog-metric-update. Only after the user explicitly agrees to overwrite, call this tool again with 'overwrite' set to true. Overwriting an approved metric with a changed meaning resets it to 'proposed'. A deleted metric's name is available again - creating with it starts a fresh metric with no history carried over. The definition can be an executable query (HogQLQuery / TrendsQuery / FunnelsQuery / an event node) that the query runner computes, OR an agent-calculated markdown definition - {\"kind\": \"MarkdownDefinition\", \"markdown\": \"<numbered steps to calculate the metric>\"} - which an agent follows to produce the number. Prefer an executable definition when the metric is deterministic; use a markdown definition when the calculation needs judgment or multiple steps. Only propose a definition that was explicitly asked for or that you have seen reused at least twice - do not speculatively catalog one-off queries. If you derived a number or settled a definition and no metric exists for it, end your answer by offering to save it as a proposed metric. Keep 'description' to 1-2 short sentences under 300 characters: what the number is and its grain, plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, upstream corrections, and comparisons with or pointers to other metrics. Never walk through the query or calculation steps (the definition carries those). Put why the definition is shaped this way in 'reasoning', in 1-3 short sentences: the main design decisions and trade-offs, such as the source table or view, a filter or exclusion, the grain, or an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. Before creating a metric, inspect the complete catalog with metric-list and inspect a candidate's definition with metric-describe when it may be reusable. When the metric comes from an existing saved insight, pass that insight's 'source_insight_short_id' instead of copying its query into 'definition' - the two are mutually exclusive. The server snapshots the insight's query, tracks drift against it, and the metric then links back to the insight so a person can edit the query where it lives.","category": "Data catalog","feature": "data_catalog",- "summary": "Create or refine a catalog metric",- "title": "Create or refine a catalog metric",+ "summary": "Create a catalog metric",+ "title": "Create a catalog metric","required_scopes": ["data_catalog:write"],"api_operations": ["POST /api/projects/{project_id}/data_catalog/metrics/"],"annotations": {diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 7dad6976e964..4cd55998d085 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -4108,11 +4108,11 @@}},"data-catalog-metric-create": {- "description": "Create a canonical metric, or refine the live one already holding this name (upsert on name; always lands 'proposed'). A deleted metric's name is available again - creating with it starts a fresh metric with no history carried over. The definition can be an executable query (HogQLQuery / TrendsQuery / FunnelsQuery / an event node) that the query runner computes, OR an agent-calculated markdown definition - {\"kind\": \"MarkdownDefinition\", \"markdown\": \"<numbered steps to calculate the metric>\"} - which an agent follows to produce the number. Prefer an executable definition when the metric is deterministic; use a markdown definition when the calculation needs judgment or multiple steps. Only propose a definition that was explicitly asked for or that you have seen reused at least twice - do not speculatively catalog one-off queries. If you derived a number or settled a definition and no metric exists for it, end your answer by offering to save it as a proposed metric. Keep 'description' to 1-2 short sentences under 300 characters: what the number is and its grain, plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, upstream corrections, and comparisons with or pointers to other metrics. Never walk through the query or calculation steps (the definition carries those). Put why the definition is shaped this way in 'reasoning', in 1-3 short sentences: the main design decisions and trade-offs, such as the source table or view, a filter or exclusion, the grain, or an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. Before creating a metric, inspect the complete catalog with metric-list and inspect a candidate's definition with metric-describe when it may be reusable. When the metric comes from an existing saved insight, pass that insight's 'source_insight_short_id' instead of copying its query into 'definition' - the two are mutually exclusive. The server snapshots the insight's query, tracks drift against it, and the metric then links back to the insight so a person can edit the query where it lives.",+ "description": "Create a canonical metric (always lands 'proposed'). If a live metric already holds the name, the call fails with a 409 'metric_name_taken' error, and the existing metric stays unchanged. Never overwrite on your own: tell the user that the name is taken, show them the existing metric with metric-describe, and ask whether to overwrite it, use a different name, or edit the existing metric with data-catalog-metric-update. Only after the user explicitly agrees to overwrite, call this tool again with 'overwrite' set to true. Overwriting an approved metric with a changed meaning resets it to 'proposed'. A deleted metric's name is available again - creating with it starts a fresh metric with no history carried over. The definition can be an executable query (HogQLQuery / TrendsQuery / FunnelsQuery / an event node) that the query runner computes, OR an agent-calculated markdown definition - {\"kind\": \"MarkdownDefinition\", \"markdown\": \"<numbered steps to calculate the metric>\"} - which an agent follows to produce the number. Prefer an executable definition when the metric is deterministic; use a markdown definition when the calculation needs judgment or multiple steps. Only propose a definition that was explicitly asked for or that you have seen reused at least twice - do not speculatively catalog one-off queries. If you derived a number or settled a definition and no metric exists for it, end your answer by offering to save it as a proposed metric. Keep 'description' to 1-2 short sentences under 300 characters: what the number is and its grain, plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, upstream corrections, and comparisons with or pointers to other metrics. Never walk through the query or calculation steps (the definition carries those). Put why the definition is shaped this way in 'reasoning', in 1-3 short sentences: the main design decisions and trade-offs, such as the source table or view, a filter or exclusion, the grain, or an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. Before creating a metric, inspect the complete catalog with metric-list and inspect a candidate's definition with metric-describe when it may be reusable. When the metric comes from an existing saved insight, pass that insight's 'source_insight_short_id' instead of copying its query into 'definition' - the two are mutually exclusive. The server snapshots the insight's query, tracks drift against it, and the metric then links back to the insight so a person can edit the query where it lives.","category": "Data catalog","feature": "data_catalog",- "summary": "Create or refine a catalog metric",- "title": "Create or refine a catalog metric",+ "summary": "Create a catalog metric",+ "title": "Create a catalog metric","required_scopes": ["data_catalog:write"],"api_operations": ["POST /api/projects/{project_id}/data_catalog/metrics/"],"annotations": {diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex b83218923f12..fd2af5b02043 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -28605,6 +28605,136 @@ export namespace Schemas {names: string[];}+ /**+ * Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.+ * @nullable+ */+ export type DataCatalogMetricCreateDefinition = { [key: string]: unknown } | null;++ /**+ * Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name.+ */+ export interface DataCatalogMetricCreate {+ readonly id: string;+ /**+ * Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving.+ * @maxLength 128+ * @pattern ^[A-Za-z][A-Za-z0-9_]*$+ */+ name: string;+ /**+ * Human-friendly label. Mutable, unlike name.+ * @maxLength 255+ */+ display_name?: string;+ /**+ * What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'.+ * @maxLength 300+ */+ description: string;+ /**+ * Unit of the result, e.g. usd, percent, cents.+ * @maxLength 64+ */+ unit?: string;+ /**+ * Email of the human accountable for this metric, or null.+ * @nullable+ */+ readonly owner: string | null;+ /**+ * Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.+ * @nullable+ */+ definition?: DataCatalogMetricCreateDefinition;+ /**+ * Query kind of the definition (HogQLQuery, TrendsQuery, ...), or null for a stub.+ * @nullable+ */+ readonly definition_kind: string | null;+ /** Tables the definition directly references, extracted at write time for the catalog's denied-table filter. */+ readonly referenced_table_names: unknown;+ /** Persisted lifecycle state: 'proposed' or 'approved'. Drift is reported separately. */+ readonly status: string;+ /** True when the definition has drifted from its linked source insight (or the insight is gone). */+ readonly is_drifted: boolean;+ /** @nullable */+ readonly approved_at: string | null;+ /** User who approved this metric as canonical, or null. */+ readonly approved_by: UserBasic | null;+ /**+ * Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition.+ * @maxLength 12+ * @nullable+ */+ source_insight_short_id?: string | null;+ /**+ * When the metric was last run (30-minute throttle).+ * @nullable+ */+ readonly last_run_at: string | null;+ /** Whether a human ('user') or an agent ('ai_generated') authored this metric.+ *+ * * `user` - user+ * * `ai_generated` - ai_generated */+ created_source?: CreatedSourceEnum;+ /**+ * Model that generated the metric, if AI-authored.+ * @maxLength 128+ */+ ai_model?: string;+ /**+ * AI author's confidence in the proposal, 0-1.+ * @minimum 0+ * @maximum 1+ * @nullable+ */+ confidence?: number | null;+ /** Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history. */+ reasoning?: string;+ /** User who first created this metric. */+ readonly created_by: UserBasic;+ readonly created_at: string;+ /** @nullable */+ readonly updated_at: string | null;+ /** Replace the fields of the live metric that already holds this name. When false, a taken name returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an approved metric with a changed name, description, unit, or definition resets it to 'proposed'. */+ overwrite?: boolean;+ }++ /**+ * The live metric that holds the name a create was sent with.+ */+ export interface DataCatalogMetricNameConflictExisting {+ /** Name of the existing metric. */+ name: string;+ /** Lifecycle state of the existing metric: 'proposed' or 'approved'. */+ status: string;+ }++ export interface DataCatalogMetricNameConflictExtra {+ /** The metric that holds the name. Send overwrite true to replace it. */+ existing_metric: DataCatalogMetricNameConflictExisting;+ }++ /**+ * The 409 body of a create whose name a live metric already holds.+ */+ export interface DataCatalogMetricNameConflict {+ /** Error class the API attaches to every error body. */+ type: string;+ /** Always 'metric_name_taken'. */+ code: string;+ /** Human-readable reason, safe to show as is. */+ detail: string;+ /**+ * Always null: the conflict is not tied to one field.+ * @nullable+ */+ attr: string | null;+ /** Absent when the existing metric is hidden from the caller because it reads a table they cannot access. */+ extra?: DataCatalogMetricNameConflictExtra;+ }+/*** Normalized envelope returned by the metric-run endpoint.*/diff --git a/services/mcp/src/generated/data_catalog/api.ts b/services/mcp/src/generated/data_catalog/api.tsindex 95740162b5d3..84a8e3a4f763 100644--- a/services/mcp/src/generated/data_catalog/api.ts+++ b/services/mcp/src/generated/data_catalog/api.ts@@ -82,7 +82,7 @@ export const DataCatalogMetricsListQueryParams = () => zod.object({})/**- * Create a metric, or refine the one already holding this name for the team.+ * Create a metric. When a live metric already holds the name, returns 409 unless overwrite is true, in which case the existing metric is refined with the fields sent.*/export const DataCatalogMetricsCreateParams = () => zod.object({project_id: zod@@ -108,59 +108,71 @@ export const dataCatalogMetricsCreateBodyAiModelMax = 128export const dataCatalogMetricsCreateBodyConfidenceMin = 0export const dataCatalogMetricsCreateBodyConfidenceMax = 1-export const DataCatalogMetricsCreateBody = () => zod.object({- name: zod- .string()- .max(dataCatalogMetricsCreateBodyNameMax)- .regex(dataCatalogMetricsCreateBodyNameRegExp)- .describe(- "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."- ),- display_name: zod- .string()- .max(dataCatalogMetricsCreateBodyDisplayNameMax)- .optional()- .describe('Human-friendly label. Mutable, unlike name.'),- description: zod- .string()- .max(dataCatalogMetricsCreateBodyDescriptionMax)- .describe(- "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."- ),- unit: zod- .string()- .max(dataCatalogMetricsCreateBodyUnitMax)- .optional()- .describe('Unit of the result, e.g. usd, percent, cents.'),- definition: zod- .record(zod.string(), zod.unknown())- .nullish()- .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),- source_insight_short_id: zod- .string()- .max(dataCatalogMetricsCreateBodySourceInsightShortIdMax)- .nullish()- .describe(- "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."- ),- ai_model: zod- .string()- .max(dataCatalogMetricsCreateBodyAiModelMax)- .optional()- .describe('Model that generated the metric, if AI-authored.'),- confidence: zod- .number()- .min(dataCatalogMetricsCreateBodyConfidenceMin)- .max(dataCatalogMetricsCreateBodyConfidenceMax)- .nullish()- .describe("AI author's confidence in the proposal, 0-1."),- reasoning: zod- .string()- .optional()- .describe(- 'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'- ),-})+export const dataCatalogMetricsCreateBodyOverwriteDefault = false++export const DataCatalogMetricsCreateBody = () => zod+ .object({+ name: zod+ .string()+ .max(dataCatalogMetricsCreateBodyNameMax)+ .regex(dataCatalogMetricsCreateBodyNameRegExp)+ .describe(+ "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."+ ),+ display_name: zod+ .string()+ .max(dataCatalogMetricsCreateBodyDisplayNameMax)+ .optional()+ .describe('Human-friendly label. Mutable, unlike name.'),+ description: zod+ .string()+ .max(dataCatalogMetricsCreateBodyDescriptionMax)+ .describe(+ "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."+ ),+ unit: zod+ .string()+ .max(dataCatalogMetricsCreateBodyUnitMax)+ .optional()+ .describe('Unit of the result, e.g. usd, percent, cents.'),+ definition: zod+ .record(zod.string(), zod.unknown())+ .nullish()+ .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),+ source_insight_short_id: zod+ .string()+ .max(dataCatalogMetricsCreateBodySourceInsightShortIdMax)+ .nullish()+ .describe(+ "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."+ ),+ ai_model: zod+ .string()+ .max(dataCatalogMetricsCreateBodyAiModelMax)+ .optional()+ .describe('Model that generated the metric, if AI-authored.'),+ confidence: zod+ .number()+ .min(dataCatalogMetricsCreateBodyConfidenceMin)+ .max(dataCatalogMetricsCreateBodyConfidenceMax)+ .nullish()+ .describe("AI author's confidence in the proposal, 0-1."),+ reasoning: zod+ .string()+ .optional()+ .describe(+ 'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'+ ),+ overwrite: zod+ .boolean()+ .default(dataCatalogMetricsCreateBodyOverwriteDefault)+ .describe(+ "Replace the fields of the live metric that already holds this name. When false, a taken name returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an approved metric with a changed name, description, unit, or definition resets it to 'proposed'."+ ),+ })+ .describe(+ 'Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name.'+ )/*** CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).diff --git a/services/mcp/src/tools/generated/data_catalog.ts b/services/mcp/src/tools/generated/data_catalog.tsindex e7c5ad1268b7..478c79cc1a6f 100644--- a/services/mcp/src/tools/generated/data_catalog.ts+++ b/services/mcp/src/tools/generated/data_catalog.ts@@ -275,7 +275,11 @@ const dataCatalogMetricApproveExecute = (): ToolBase<const DataCatalogMetricCreateSchema = () => {const DataCatalogMetricsCreateBody = orvalSchemas.DataCatalogMetricsCreateBody()- return DataCatalogMetricsCreateBody+ return DataCatalogMetricsCreateBody.extend({+ overwrite: DataCatalogMetricsCreateBody.shape['overwrite'].describe(+ 'Set to true only after the user explicitly agreed to overwrite the live metric that already holds this name. Leave it unset on the first call.'+ ),+ })}const dataCatalogMetricCreate = (): ToolBase<@@ -314,6 +318,9 @@ const dataCatalogMetricCreate = (): ToolBase<if (params.reasoning !== undefined) {body['reasoning'] = params.reasoning}+ if (params.overwrite !== undefined) {+ body['overwrite'] = params.overwrite+ }body['created_source'] = 'ai_generated'const result = await context.api.request<Schemas.DataCatalogMetric>({method: 'POST',diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/data-catalog-metric-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/data-catalog-metric-create.jsonindex 175843a56574..0a282056ae8a 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/data-catalog-metric-create.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/data-catalog-metric-create.json@@ -50,6 +50,11 @@"pattern": "^[A-Za-z][A-Za-z0-9_]*$","type": "string"},+ "overwrite": {+ "default": false,+ "description": "Set to true only after the user explicitly agreed to overwrite the live metric that already holds this name. Leave it unset on the first call.",+ "type": "boolean"+ },"reasoning": {"description": "Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.","type": "string"