Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Fix MCP's guide and Metabot's check for card-based metrics (#85220)

Andrei Simionescuc406344f8c68
diff --git a/resources/mcp/v2/skills/query-dialect/SKILL.md b/resources/mcp/v2/skills/query-dialect/SKILL.md
index 9e530db29a3..24fb5189e1f 100644
--- a/resources/mcp/v2/skills/query-dialect/SKILL.md
+++ b/resources/mcp/v2/skills/query-dialect/SKILL.md
@@ -135,7 +135,7 @@ Window: `offset` sits in `aggregation` and reads another breakout row — month-
## Metrics, measures, segments
-By numeric id, on a stage whose `source-table` is their base table: metric `"aggregation": [["metric", {}, 42]]`; measure `"aggregation": [["measure", {}, 7]]`; segment `"filters": [["segment", {}, 3]]`. `browse_data` `get_fields` lists each table's with ids. To compose on top of one, `get_content` `include: ["definition"]` returns its clauses in this dialect to inline and extend.
+By numeric id, on a stage built on the metric's required source: the base table in `source-table` for a table metric, or the model or saved question in `source-card` for a card metric. Only a single-stage metric defined on a card requires that exact card; a multi-stage metric whose definition starts from a card requires its underlying table in `source-table` instead. Measures and segments go on a stage whose `source-table` is their base table. Metric `"aggregation": [["metric", {}, 42]]`; measure `"aggregation": [["measure", {}, 7]]`; segment `"filters": [["segment", {}, 3]]`. `browse_data` `get_fields` lists each table's with ids. To compose on top of one, `get_content` `include: ["definition"]` returns its clauses in this dialect to inline and extend.
A metric's or measure's output column is named for the aggregation inside its definition (`sum`, `count`, `avg`), not for the metric or measure — set `"name"` in its options slot (`["measure", {"name": "revenue"}, 7]`) to name it for a later stage.
diff --git a/resources/mcp/v2/skills/query-dialect/references/operators.md b/resources/mcp/v2/skills/query-dialect/references/operators.md
index 97f963b433e..e0c037a7967 100644
--- a/resources/mcp/v2/skills/query-dialect/references/operators.md
+++ b/resources/mcp/v2/skills/query-dialect/references/operators.md
@@ -44,7 +44,7 @@ Named reference:
- `["stddev", {}, <num>]` / `["var", {}, <num>]`
- `["count-where", {}, <bool-pred>]` / `["sum-where", {}, <num>, <bool-pred>]` / `["distinct-where", {}, <expr>, <bool-pred>]`
- `["share", {}, <bool-pred>]` — fraction of rows where the predicate holds, 0–1.
-- `["metric", {}, <numeric card id>]` / `["measure", {}, <numeric measure id>]` — saved definitions; base table must be the stage's source.
+- `["metric", {}, <numeric card id>]` / `["measure", {}, <numeric measure id>]` — saved definitions. A metric goes on a stage built on its required source: the base table in `source-table` for a table metric, or the model or saved question in `source-card` for a card metric. Only a single-stage metric defined on a card requires that exact card; a multi-stage metric whose definition starts from a card requires its underlying table in `source-table` instead. A measure's base table must be the stage's source.
- `["offset", {}, <expr>, <n>]` — window function: the value `<n>` rows back (negative) or ahead. Valid **only** inside `aggregation` or `order-by`, never in `expressions` or a filter.
Name the output in options — `["sum", {"name": "revenue", "display-name": "Revenue"}, <field>]`; later stages and visualization settings reference that `name`.
diff --git a/src/metabase/metabot/db.clj b/src/metabase/metabot/db.clj
index 2dd11b770cb..79d0b878fe0 100644
--- a/src/metabase/metabot/db.clj
+++ b/src/metabase/metabot/db.clj
@@ -817,16 +817,16 @@
(mu/defn card-source-info
"Return a map of Card IDs to stored metric definitions for `card-ids`.
- Each row contains `:table_id` and `:dataset_query` for [[metabase.metabot.tools.util/metric-required-source]].
+ Each row contains the `:dataset_query` for [[metabase.metabot.tools.util/metric-required-source]].
Queries are returned with the model's output transform, without running card-schema upgrades."
;; The first stage's `:source_card_id` cannot distinguish single-stage and multi-stage card metrics.
[card-ids :- [:or [:set ::lib.schema.id/card] [:sequential ::lib.schema.id/card]]]
(let [query-out (:out lib-be/transform-query)]
(into {}
- (map (fn [{:keys [id table_id dataset_query]}]
- [id {:table_id table_id, :dataset_query (query-out dataset_query)}]))
+ (map (fn [{:keys [id dataset_query]}]
+ [id {:dataset_query (query-out dataset_query)}]))
(when (seq card-ids)
- (t2/select [(t2/table-name :model/Card) :id :table_id :dataset_query] :id [:in card-ids])))))
+ (t2/select [(t2/table-name :model/Card) :id :dataset_query] :id [:in card-ids])))))
(mu/defn card-source-rows
"Return the source cards in `card-ids`, including the columns needed by `can-read?`."
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index 0e566e25389..91a0aaa9706 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -905,12 +905,12 @@
stage-card-id (conj stage-card-id)))
;; Use `::unresolved` so a missing source card cannot match a metric whose table ID is nil.
stage-table-id (if stage-card-id
- (or (:table-id (lib.metadata/card mp stage-card-id)) ::unresolved)
+ (or (tools.u/card-source-table-id mp stage-card-id) ::unresolved)
(lib.util/source-table-id query))]
(not-empty
(into (sorted-map)
(keep (fn [metric-id]
- (let [required (tools.u/metric-required-source (lib.metadata/card mp metric-id))
+ (let [required (tools.u/metric-required-source mp (lib.metadata/card mp metric-id))
compatible? (and required
(tools.u/metric-compatible-with-stage?
required
diff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.clj
index 1e8fa57355b..86aa8ff3f77 100644
--- a/src/metabase/metabot/tools/entity_details.clj
+++ b/src/metabase/metabot/tools/entity_details.clj
@@ -318,9 +318,9 @@
The result is `{card-id -> boolean}`, including false for missing or unreadable cards. Read the requirements
through [[metabase.metabot.tools.util/metric-required-source]], since a multi-stage card metric requires its
base table, not the card named by its first stage."
- [metric-cards]
+ [metadata-provider metric-cards]
(let [source-card-ids (into #{}
- (keep #(let [r (metabot.tools.u/metric-required-source %)]
+ (keep #(let [r (metabot.tools.u/metric-required-source metadata-provider %)]
(when (= :card (:kind r)) (:card-id r))))
metric-cards)]
(when (seq source-card-ids)
@@ -363,7 +363,7 @@
database-name (:name database)
;; A metric's required source can differ from the first stage of its definition or its base table.
;; See [[metabase.metabot.tools.util/metric-required-source]].
- required (metabot.tools.u/metric-required-source card)
+ required (metabot.tools.u/metric-required-source metadata-provider card)
source-table-id (when (= :table (:kind required)) (:table-id required))
source-card-id (when (= :card (:kind required)) (:card-id required))
source-table (when (and source-table-id
@@ -537,7 +537,7 @@
;; Table queries can list card metrics through their base table; batch the source-card read checks.
:metrics (when with-metrics?
(let [metrics (lib/available-metrics table-query)
- verdicts (card-read-verdicts-for-metrics metrics)]
+ verdicts (card-read-verdicts-for-metrics mp metrics)]
(when-let [ids (seq (keep (fn [[id readable?]] (when readable? id)) verdicts))]
(lib.metadata/bulk-metadata mp :metadata/card ids))
(not-empty (mapv #(convert-metric % mp options verdicts) metrics))))
@@ -726,7 +726,7 @@
(let [mp (lib-be/application-database-metadata-provider database-id)
;; Only metrics need these source-card permissions. A question or model's own source is not used downstream.
card-read-verdicts (when (= card-type :metric)
- (card-read-verdicts-for-metrics cards))
+ (card-read-verdicts-for-metrics mp cards))
readable-source-card-ids (into #{} (keep (fn [[id readable?]] (when readable? id))) card-read-verdicts)
detail-fn (case card-type
:metric #(metric-details %1 %2 %3 card-read-verdicts)
diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.clj
index 82be2faf74e..8863d7964ec 100644
--- a/src/metabase/metabot/tools/search.clj
+++ b/src/metabase/metabot/tools/search.clj
@@ -179,7 +179,8 @@
from access to the metric itself.
Requires `:database_name` on each result (see [[enrich-with-database-engines]]) to build portable FKs.
- Query count is fixed per search call, but each metric's stored definition must be read."
+ Query count is fixed per search call, except that a multi-stage metric defined on a card also reads the cards it is
+ built on."
[results]
(let [metric-ids (->> results (filter #(= "metric" (:type %))) (keep :id) distinct)
card-id->source (when (seq metric-ids)
diff --git a/src/metabase/metabot/tools/util.clj b/src/metabase/metabot/tools/util.clj
index b0978f56817..93e91ba50f8 100644
--- a/src/metabase/metabot/tools/util.clj
+++ b/src/metabase/metabot/tools/util.clj
@@ -6,6 +6,7 @@
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
[metabase.lib.types.isa :as lib.types.isa]
+ [metabase.lib.util :as lib.util]
[metabase.metabot.db :as metabot.db]
[metabase.metabot.tools.core :as tools]
[metabase.models.interface :as mi]
@@ -275,34 +276,54 @@
(comp (filter mi/can-read?) (map (juxt :id identity)))
(metabot.db/card-source-rows card-ids))))
+(defn card-source-table-id
+ "Return the ID of the table that the card with `card-id` reads from, following its source cards.
+
+ Unlike `report_card.table_id`, which is written only when a card is saved, this reads each card's current query, so
+ it reflects an upstream card that has since moved to another table. Return nil when the chain ends in a native query
+ or a missing card."
+ [metadata-providerable card-id]
+ (loop [card-id card-id, seen #{}]
+ (when-let [query (and card-id
+ (not (seen card-id))
+ (not-empty (:dataset-query (lib.metadata/card metadata-providerable card-id))))]
+ (or (lib.util/source-table-id query)
+ (recur (lib.util/source-card-id query) (conj seen card-id))))))
+
(defn metric-required-source
"Return the source required to use metric `card`, or nil when its definition cannot be read.
Return `{:kind :card, :card-id C}` for a single-stage definition on card C. Otherwise return
`{:kind :table, :table-id T, :bare-table-only? boolean}`. A single-stage table metric also works on a card over T;
- a multi-stage metric requires a stage directly on T, even when its definition starts from a card.
- A nil table ID means there is no usable table source.
+ a multi-stage metric requires a stage directly on T, even when its definition starts from a card. For such a
+ definition, T is the table that the card reads from, per [[card-source-table-id]].
+ A nil table ID means there is no usable table source. Read source cards through `metadata-providerable` when
+ supplied, or an app-DB metadata provider for the definition's database otherwise.
This follows `splice-compatible-metrics` in [[metabase.query-processor.middleware.metrics]]. The query processor
compares the metric's last stage, so the first stage's `report_card.source_card_id` is insufficient.
Legacy definitions are converted to MBQL 5 before classification. Missing, blank, or unconvertible definitions
return nil."
- [card]
- (let [definition (metric-card-shape-get card :dataset-query :dataset_query)
- stages (or (not-empty (:stages definition))
- (when (seq definition)
- (try
- (:stages (lib/->mbql5 definition))
- (catch Exception _ nil))))]
- (when (seq stages)
- (if-let [card-id (and (= 1 (count stages)) (:source-card (first stages)))]
- {:kind :card, :card-id card-id}
- {:kind :table
- ;; The definition's own `:source-table` when it has one, which is what the QP compares; `table_id` is
- ;; derived at save time and only needed for a card-rooted definition.
- :table-id (or (:source-table (first stages))
- (metric-card-shape-get card :table-id :table_id))
- :bare-table-only? (> (count stages) 1)}))))
+ ([card]
+ (metric-required-source nil card))
+ ([metadata-providerable card]
+ (let [definition (metric-card-shape-get card :dataset-query :dataset_query)
+ stages (or (not-empty (:stages definition))
+ (when (seq definition)
+ (try
+ (:stages (lib/->mbql5 definition))
+ (catch Exception _ nil))))]
+ (when (seq stages)
+ (if-let [card-id (and (= 1 (count stages)) (:source-card (first stages)))]
+ {:kind :card, :card-id card-id}
+ {:kind :table
+ :table-id (or (:source-table (first stages))
+ (some->> (:source-card (first stages))
+ (card-source-table-id
+ (or metadata-providerable
+ (lib-be/application-database-metadata-provider
+ (:database definition))))))
+ :bare-table-only? (> (count stages) 1)})))))
(defn metric-compatible-with-stage?
"Return whether `required` permits a metric on the stage's source.
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index 525c335cd18..262fb75ce29 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -2686,12 +2686,16 @@
(let [mp (mt/metadata-provider)]
(lib/query mp (lib.metadata/table mp (mt/id table-key)))))
+(defn- card-query
+ "A Lib query on the card with `card-id`."
+ [card-id]
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/card mp card-id))))
+
(defn- card-count-query
"A count query on the card with `card-id`."
[card-id]
- (let [mp (mt/metadata-provider)]
- (-> (lib/query mp (lib.metadata/card mp card-id))
- (lib/aggregate (lib/count)))))
+ (lib/aggregate (card-query card-id) (lib/count)))
(defn- field-col
[table-key field-key]
@@ -2728,6 +2732,53 @@
(get-in [:structured-output :query]))]
(is (= [[18760]] (mt/rows (qp/process-query query))))))))))
+(deftest metric-source-check-follows-a-source-card-that-changed-table-test
+ (testing "After C1 moves from ORDERS to PRODUCTS, the check follows it as the query processor does"
+ (mt/with-temp [:model/Card {c1-id :id}
+ {:name "C1" :type :question :dataset_query (table-query :orders)}
+ :model/Card {c2-id :id, c2-eid :entity_id}
+ {:name "C2" :type :question :dataset_query (card-query c1-id)}
+ :model/Card {products-metric-eid :entity_id}
+ {:name "Product count" :type :metric
+ :dataset_query (lib/aggregate (table-query :products) (lib/count))}
+ :model/Card {orders-metric-id :id, orders-metric-eid :entity_id}
+ {:name "Order count" :type :metric
+ :dataset_query (lib/aggregate (table-query :orders) (lib/count))}
+ :model/Card {two-stage-id :id, two-stage-eid :entity_id}
+ {:name "Two-stage count" :type :metric
+ :dataset_query (-> (card-query c1-id) lib/append-stage (lib/aggregate (lib/count)))}]
+ (t2/update! :model/Card c1-id {:dataset_query (table-query :products)})
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (mt/metadata-provider)
+ rows (fn [source metric-eid]
+ (-> (construct/execute-representations-query (metric-query-data source metric-eid))
+ (get-in [:structured-output :query])
+ qp/process-query
+ mt/rows))
+ check (fn [source metric-eid]
+ (try
+ (construct/execute-representations-query (metric-query-data source metric-eid))
+ :accepted
+ (catch clojure.lang.ExceptionInfo e
+ (:error (ex-data e)))))]
+ (testing "precondition: C2 and the two-stage metric still store the table C1 had when they were saved"
+ (is (= [(mt/id :orders) (mt/id :orders)]
+ (map #(:table-id (lib.metadata/card mp %)) [c2-id two-stage-id]))))
+ (testing "on C2, a metric on PRODUCTS is accepted and runs"
+ (is (= [[200]] (rows {"source-card" c2-eid} products-metric-eid))))
+ (testing "on C2, a metric on ORDERS is refused, as the query processor refuses it"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Incompatible metric"
+ (qp/process-query (lib/aggregate (card-query c2-id)
+ (lib.metadata/metric mp orders-metric-id)))))
+ (is (= :incompatible-metric (check {"source-card" c2-eid} orders-metric-eid))))
+ (testing "a two-stage metric on C1 is accepted on PRODUCTS and runs"
+ (is (= [[200]] (rows {"source-table" (products-source-table-fk)} two-stage-eid))))
+ (testing "a two-stage metric on C1 is refused on ORDERS, as the query processor refuses it"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Incompatible metric"
+ (qp/process-query (lib/aggregate (table-query :orders)
+ (lib.metadata/metric mp two-stage-id)))))
+ (is (= :incompatible-metric (check {"source-table" (orders-source-table-fk)} two-stage-eid)))))))))
+
(deftest metric-with-unreadable-definition-is-rejected-on-any-source-test
(testing "A metric with a blank definition has no usable source"
(mt/with-temp [:model/Card {metric-id :id}
@@ -3151,6 +3202,29 @@
"breakout" [["field" {} (column "PRODUCTS" "ID")]]
"aggregation" [["count" {}]])))))))))))))))
+(deftest ^:parallel metric-compatibility-uses-caller-metadata-test
+ (let [orders-query (lib/query mp (lib.metadata/table mp 10))
+ products-query (lib/query mp (lib.metadata/table mp 20))
+ source-card {:id 901, :name "Orders source", :type :question, :database-id 1
+ :dataset-query orders-query}
+ provider (lib.tu/merged-mock-metadata-provider mp {:cards [source-card]})
+ definition (-> (lib/query provider (lib.metadata/card provider 901))
+ lib/append-stage
+ (lib/aggregate (lib/count)))
+ provider (lib.tu/merged-mock-metadata-provider
+ provider
+ {:cards [{:id 902, :name "Orders metric", :type :metric, :database-id 1
+ :dataset-query definition}]})
+ other-provider (lib.tu/merged-mock-metadata-provider
+ mp {:cards [(assoc source-card :dataset-query products-query)]})]
+ (mt/with-dynamic-fn-redefs [lib-be/application-database-metadata-provider (constantly other-provider)]
+ (doseq [[table-id expected] [[10 nil]
+ [20 {902 {:kind :table, :table-id 10, :bare-table-only? true}}]]]
+ (testing (str "Compatibility with table " table-id " uses the caller's source card")
+ (let [query (-> (lib/query provider (lib.metadata/table provider table-id))
+ (lib/aggregate (lib.metadata/metric provider 902)))]
+ (is (= expected (#'construct/incompatible-metrics provider query)))))))))
+
(deftest gate-checks-only-the-first-stage-test
(testing "Metric compatibility is checked only in the first stage"
(mt/with-temp [:model/Card {question-id :id}
diff --git a/test/metabase/metabot/tools/util_test.clj b/test/metabase/metabot/tools/util_test.clj
index 199f04e6e76..eb64c4eea61 100644
--- a/test/metabase/metabot/tools/util_test.clj
+++ b/test/metabase/metabot/tools/util_test.clj
@@ -308,15 +308,13 @@
;;; ---------------------------------------- metric sources ----------------------------------------
-(deftest ^:parallel metric-required-source-classifies-the-four-definition-shapes-test
+(deftest ^:parallel metric-required-source-classifies-definition-shapes-test
(testing "Metric sources follow the query processor's compatibility rules"
(are [expected stages] (= expected
- (metabot.tools.util/metric-required-source
- {:dataset_query {:stages stages} :table_id 5}))
+ (metabot.tools.util/metric-required-source {:dataset_query {:stages stages}}))
{:kind :table, :table-id 5, :bare-table-only? false} [{:source-table 5}]
{:kind :card, :card-id 42} [{:source-card 42}]
- {:kind :table, :table-id 5, :bare-table-only? true} [{:source-table 5} {}]
- {:kind :table, :table-id 5, :bare-table-only? true} [{:source-card 42} {}])))
+ {:kind :table, :table-id 5, :bare-table-only? true} [{:source-table 5} {}])))
(deftest ^:parallel metric-required-source-unreadable-definition-test
(testing "A blank or unconvertible metric definition has no usable source"
@@ -330,12 +328,12 @@
(deftest ^:parallel metric-required-source-legacy-definition-test
(testing "Legacy definitions are converted before classifying the source"
(are [expected query] (= expected (metabot.tools.util/metric-required-source
- {:dataset_query (assoc query :database 1 :type :query) :table_id 5}))
+ {:dataset_query (assoc query :database 1 :type :query)}))
{:kind :table, :table-id 5, :bare-table-only? false} {:query {:source-table 5}}
{:kind :card, :card-id 12} {:query {:source-table "card__12"
:aggregation [[:count]]}}
;; a nested `:source-query` is two stages, so the base table is the one to use
- {:kind :table, :table-id 5, :bare-table-only? true} {:query {:source-query {:source-table "card__12"}
+ {:kind :table, :table-id 5, :bare-table-only? true} {:query {:source-query {:source-table 5}
:aggregation [[:count]]}})))
(deftest ^:parallel metric-compatible-with-stage?-test