The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
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.mdindex 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.mdindex 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.cljindex 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.cljindex 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?requireddiff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.cljindex 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 requirementsthrough [[metabase.metabot.tools.util/metric-required-source]], since a multi-stage card metric requires itsbase 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.cljindex 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.cljindex 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 processorcompares 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 definitionsreturn 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.cljindex 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.cljindex 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