Skip to content

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

Fix Metabot using the wrong source for card-based metrics (#82425)

Mihael Konjevićcd35a4f1a3c7
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/generate/schemas/metric.clj b/enterprise/backend/src/metabase_enterprise/data_apps/generate/schemas/metric.clj
index 2643b896537..85b6737a3a7 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/generate/schemas/metric.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/generate/schemas/metric.clj
@@ -207,7 +207,10 @@
source-table)))
(defn- source-card-id
- "Returns the source card id for metrics that are based on saved questions."
+ "Return the source card ID from the first stage of a metric's definition.
+
+ This identifies the card the definition reads from. The source needed to use the metric is returned by
+ [[metabase.metabot.tools.util/metric-required-source]]; a multi-stage definition can require its base table."
[card]
(or (when-let [source-card (get-in card [:dataset_query :stages 0 :source-card])]
(when (integer? source-card)
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/generate/schemas/metric_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/generate/schemas/metric_test.clj
index 2ada0b524af..e87e0f125ea 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/generate/schemas/metric_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/generate/schemas/metric_test.clj
@@ -51,7 +51,10 @@
(is (= 42 (#'schemas.metric/source-card-id card)))))
(testing "stage source-card emits sourceCardId"
(is (= 42 (#'schemas.metric/source-card-id
- {:dataset_query {:stages [{:source-card 42}]}})))))
+ {:dataset_query {:stages [{:source-card 42}]}}))))
+ (testing "The first stage identifies the source card even when a multi-stage metric requires its base table"
+ (is (= 42 (#'schemas.metric/source-card-id
+ {:dataset_query {:stages [{:source-card 42} {:aggregation [[:count]]}]}})))))
(defn- orders-metric-query
[filters]
diff --git a/resources/metabot/prompts/llm_shape.selmer b/resources/metabot/prompts/llm_shape.selmer
index b33f9f12076..d01582e2dc5 100644
--- a/resources/metabot/prompts/llm_shape.selmer
+++ b/resources/metabot/prompts/llm_shape.selmer
@@ -37,7 +37,7 @@ The related tables below are listed without their fields. Look them up separatel
This entity has more FK-related tables than the {{related_tables_surfaced}} shown here.
</related-tables-truncated>{% endif %}{% endif %}
{% if is_metric %}
-<metric id="{{metric_id}}", name="{{metric_name}}" is_verified="{{metric_verified}}"{% if metric_database_name %} database_name="{{metric_database_name}}"{% endif %}{% if metric_base_table_fqn %} base_table_fully_qualified_name="{{metric_base_table_fqn}}"{% endif %}{% if metric_portable_entity_id %} portable_entity_id="{{metric_portable_entity_id}}"{% endif %}>
+<metric id="{{metric_id}}", name="{{metric_name}}" is_verified="{{metric_verified}}"{% if metric_database_name %} database_name="{{metric_database_name}}"{% endif %}{% if metric_base_table_fqn %} base_table_fully_qualified_name="{{metric_base_table_fqn}}"{% endif %}{% if metric_source_card_entity_id %} source_card_portable_entity_id="{{metric_source_card_entity_id}}"{% if metric_source_card_name %} source_card_name="{{metric_source_card_name}}"{% endif %}{% endif %}{% if metric_source_unavailable %} source_unavailable="true"{% endif %}{% if metric_portable_entity_id %} portable_entity_id="{{metric_portable_entity_id}}"{% endif %}>
{% if metric_collection_xml %}
The metric is stored in the following collection:
{{metric_collection_xml|safe}}
@@ -288,7 +288,7 @@ or jargon that may be relevant to the user's questions.
</user>
{% endif %}
{% if is_search_result %}
-<{{search_tag_name}} id="{{search_id}}"{% if search_uri %} uri="{{search_uri}}"{% endif %} name="{{search_name}}"{% if search_has_curated %} is_curated="{{search_curated}}"{% endif %}{% if search_has_verified %} is_verified="{{search_verified}}"{% endif %}{% if search_has_official %} is_official="{{search_official}}"{% endif %}{% if search_has_can_write %} can_write="{{search_can_write}}"{% endif %}{% if search_data_layer %} data_layer="{{search_data_layer}}"{% endif %}{% if search_data_authority %} data_authority="{{search_data_authority}}"{% endif %}{% if search_database_id %} database_id="{{search_database_id}}"{% endif %}{% if search_database_name %} database_name="{{search_database_name}}"{% endif %}{% if search_database_engine %} database_engine="{{search_database_engine}}"{% endif %}{% if search_fqn %} fully_qualified_name="{{search_fqn}}"{% endif %}{% if search_base_table_fqn %} base_table_fully_qualified_name="{{search_base_table_fqn}}"{% endif %}{% if search_portable_entity_id %} portable_entity_id="{{search_portable_entity_id}}"{% endif %}>
+<{{search_tag_name}} id="{{search_id}}"{% if search_uri %} uri="{{search_uri}}"{% endif %} name="{{search_name}}"{% if search_has_curated %} is_curated="{{search_curated}}"{% endif %}{% if search_has_verified %} is_verified="{{search_verified}}"{% endif %}{% if search_has_official %} is_official="{{search_official}}"{% endif %}{% if search_has_can_write %} can_write="{{search_can_write}}"{% endif %}{% if search_data_layer %} data_layer="{{search_data_layer}}"{% endif %}{% if search_data_authority %} data_authority="{{search_data_authority}}"{% endif %}{% if search_database_id %} database_id="{{search_database_id}}"{% endif %}{% if search_database_name %} database_name="{{search_database_name}}"{% endif %}{% if search_database_engine %} database_engine="{{search_database_engine}}"{% endif %}{% if search_fqn %} fully_qualified_name="{{search_fqn}}"{% endif %}{% if search_base_table_fqn %} base_table_fully_qualified_name="{{search_base_table_fqn}}"{% endif %}{% if search_source_card_entity_id %} source_card_portable_entity_id="{{search_source_card_entity_id}}"{% if search_source_card_name %} source_card_name="{{search_source_card_name}}"{% endif %}{% endif %}{% if search_source_unavailable %} source_unavailable="true"{% endif %}{% if search_portable_entity_id %} portable_entity_id="{{search_portable_entity_id}}"{% endif %}>
{% if search_description %}
{{search_description}}
{% endif %}
diff --git a/resources/metabot/prompts/shared/prompt_snippets/semantic-layer-discovery.selmer b/resources/metabot/prompts/shared/prompt_snippets/semantic-layer-discovery.selmer
index 824319b3294..ab13950c325 100644
--- a/resources/metabot/prompts/shared/prompt_snippets/semantic-layer-discovery.selmer
+++ b/resources/metabot/prompts/shared/prompt_snippets/semantic-layer-discovery.selmer
@@ -2,7 +2,7 @@
When the user names a business quantity — a **rate or ratio** ("open rate", "bounce rate", "churn rate", "conversion rate", "utilization rate"), an **aggregate with a name** ("average order value", "MRR", "active subscribers"), or a **named cohort/filter** ("hard bounces", "SUBSCRIBED customers", "high-value opportunities") — assume the organization has already defined it and reach for the definition rather than reconstructing it from raw columns:
-- **Metrics** — a named aggregation that lives independently. Search for it (`entity_types: ["metric"]`); if one matches, reference it with `["metric", {}, "<portable_entity_id>"]` on its base table when building a notebook query. Don't rebuild it as `count` / `count-where` / a hand-rolled ratio.
+- **Metrics** are named aggregations that live independently. Search for one (`entity_types: ["metric"]`); if it matches, reference it with `["metric", {}, "<portable_entity_id>"]` when building a notebook query. Use the source specified by its `<metric>` tag (`base_table_fully_qualified_name` or `source_card_portable_entity_id`). Don't rebuild it as `count`, `count-where`, or a hand-written ratio.
- **Measures** — a named aggregation attached to a table. Search for it (`entity_types: ["measure"]`), or read the table's details: its `<measure>` elements are the curated aggregations for that table. Prefer `["measure", {}, "<portable_entity_id>"]` over hand-writing the same calculation.
- **Segments** — a named, reusable filter attached to a table. When a request names a cohort, search for it (`entity_types: ["segment"]`) or check the table's `<segment>` elements, and prefer `["segment", {}, "<portable_entity_id>"]` over re-deriving the filter conditions.
diff --git a/resources/metabot/prompts/tools/construct_notebook_query.md b/resources/metabot/prompts/tools/construct_notebook_query.md
index c779ce8847b..b2bf6df3dfd 100644
--- a/resources/metabot/prompts/tools/construct_notebook_query.md
+++ b/resources/metabot/prompts/tools/construct_notebook_query.md
@@ -224,11 +224,22 @@ A stage has either `source-table` **or** `source-card`, never both. The card mus
## Metrics
-A metric is a pre-defined aggregation attached to a base table. To use one:
+A metric is a predefined aggregation. Its `<metric>` tag identifies the source to use: a base table, saved question or model. Build the stage on that source. The tag carries at most one of these attributes:
-1. Put the metric's **base table** in `source-table`. Read it from the `base_table_fully_qualified_name` attribute on the `<metric>` tag (combine with `database_name` to form the portable FK). Never invent schema/table names.
+- `base_table_fully_qualified_name` names a base table. Combine it with `database_name` to form the portable FK for `source-table`.
+- `source_card_portable_entity_id` names a saved question or model. Copy the ID verbatim into `source-card`.
+- `source_unavailable="true"` means that the metric has no source available to you. Do not use it.
+
+To use a metric:
+
+1. Copy the source attribute into the stage. Never invent schema or table names, or substitute a base table for the source card. If the tag carries `source_unavailable="true"`, or carries neither source attribute, do not use the metric or guess its source. Say that the metric is not available to you and express the aggregation directly instead, or ask which source to use.
2. Reference the metric as `["metric", {}, "<portable_entity_id>"]` in `aggregation`.
-3. Filters/breakouts on the same stage use portable FKs on the metric's base table.
+3. Use dimensions from the metric's **Dimensions** table for filters and breakouts on the same stage. Read the `Source table` column first. Names such as `id` and `created_at` can appear on several tables, and the table determines how to reference a dimension:
+ - Copy `Reference` verbatim for a dimension on the metric's own source. Its portable FK works on card and table stages.
+ - A dimension on an FK-related table can be used in `breakout:` when one foreign key reaches that table. This works on a `source-table` and a `source-card` stage alike. Otherwise, follow the tool's error: add an explicit `joins` entry (see "Joins (explicit)") on the same stage, keep the metric's source, and break out on the field using the join alias.
+ - Use the output machine name for an expression or aggregation column computed by the card. These columns have no portable FK.
+
+A table metric with `base_table_fully_qualified_name="brex_enriched.fct_cards"`:
```json
{"lib/type": "mbql.stage/mbql",
@@ -238,7 +249,19 @@ A metric is a pre-defined aggregation attached to a base table. To use one:
"aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
```
-Metrics are aggregations, **not sources** — never put a metric in `source-table` or `source-card`. The `metabase://metric/<id>` URIs are for reading metadata via `read_resource`, not for embedding in queries.
+A card metric with `source_card_portable_entity_id="T4wA_GPFwGb6R4FxIDGTo"`:
+
+```json
+{"lib/type": "mbql.stage/mbql",
+ "source-card": "T4wA_GPFwGb6R4FxIDGTo",
+ "filters": [["!=", {}, ["field", {},
+ ["Analytics", "brex_enriched", "fct_cards", "card_status"]], "inactive"]],
+ "aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
+```
+
+A metric with `source_card_portable_entity_id` requires that exact card. Substituting its base table causes an `Incompatible metric` error. Some metrics whose definition starts from a card require a base table instead; their tags carry `base_table_fully_qualified_name`. Use the attribute provided by the tag.
+
+Metrics are aggregations. Put the metric's own `portable_entity_id` in its `aggregation` clause, never in `source-table` or `source-card`. The `source_card_portable_entity_id` identifies its source card and belongs in `source-card`. Use `metabase://metric/<id>` URIs to read metadata via `read_resource`; do not embed them in queries.
## Using measures and segments
@@ -321,7 +344,7 @@ Anti-hallucination:
- `["share", {}, <bool-pred>]` — fraction of rows where pred is true.
- `["stddev", {}, <num-expr>]`
- `["var", {}, <num-expr>]`
-- `["metric", {}, "<portable_entity_id>"]` — reference a defined metric. The metric's base table must be the stage's `source-table`.
+- `["metric", {}, "<portable_entity_id>"]` references a defined metric. Use the source specified by its `<metric>` tag: `base_table_fully_qualified_name` as `source-table`, or `source_card_portable_entity_id` as `source-card`.
- `["measure", {}, "<portable_entity_id>"]` — reference a defined measure (preferred over inlining its definition). The measure's table must be the stage's `source-table`.
### Order-by direction
diff --git a/resources/metabot/skills/construct-notebook-query-advanced.md b/resources/metabot/skills/construct-notebook-query-advanced.md
index 5476c85e7f0..81ea13f538e 100644
--- a/resources/metabot/skills/construct-notebook-query-advanced.md
+++ b/resources/metabot/skills/construct-notebook-query-advanced.md
@@ -170,11 +170,22 @@ A stage has either `source-table` **or** `source-card`, never both. The card mus
> Before hand-building any named aggregation (a rate, ratio, or "X rate"/"average X"), check whether a published **metric** or table **measure** already defines it and reference that instead — see "A named measure is almost always a defined metric, measure, or segment" in the data-sources guidance. Only fall back to the two-stage rate recipe above when discovery finds no matching definition.
-A metric is a pre-defined aggregation attached to a base table. To use one:
+A metric is a predefined aggregation. Its `<metric>` tag identifies the source to use: a base table, saved question or model. Build the stage on that source. The tag carries at most one of these attributes:
-1. Put the metric's **base table** in `source-table`. Read it from the `base_table_fully_qualified_name` attribute on the `<metric>` tag (combine with `database_name` to form the portable FK). Never invent schema/table names.
+- `base_table_fully_qualified_name` names a base table. Combine it with `database_name` to form the portable FK for `source-table`.
+- `source_card_portable_entity_id` names a saved question or model. Copy the ID verbatim into `source-card`.
+- `source_unavailable="true"` means that the metric has no source available to you. Do not use it.
+
+To use a metric:
+
+1. Copy the source attribute into the stage. Never invent schema or table names, or substitute a base table for the source card. If the tag carries `source_unavailable="true"`, or carries neither source attribute, do not use the metric or guess its source. Say that the metric is not available to you and express the aggregation directly instead, or ask which source to use.
2. Reference the metric as `["metric", {}, "<portable_entity_id>"]` in `aggregation`.
-3. Filters/breakouts on the same stage use portable FKs on the metric's base table.
+3. Use dimensions from the metric's **Dimensions** table for filters and breakouts on the same stage. Read the `Source table` column first. Names such as `id` and `created_at` can appear on several tables, and the table determines how to reference a dimension:
+ - Copy `Reference` verbatim for a dimension on the metric's own source. Its portable FK works on card and table stages.
+ - A dimension on an FK-related table can be used in `breakout:` when one foreign key reaches that table. This works on a `source-table` and a `source-card` stage alike. Otherwise, follow the tool's error: add an explicit `joins` entry (see "Joins (explicit)") on the same stage, keep the metric's source, and break out on the field using the join alias.
+ - Use the output machine name for an expression or aggregation column computed by the card. These columns have no portable FK.
+
+A table metric with `base_table_fully_qualified_name="PUBLIC.ORDERS"`:
```json
{"lib/type": "mbql.stage/mbql",
@@ -184,29 +195,19 @@ A metric is a pre-defined aggregation attached to a base table. To use one:
"aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
```
-Metrics are aggregations, **not sources** — never put a metric in `source-table` or `source-card`. The `metabase://metric/<id>` URIs are for reading metadata via `read_resource`, not for embedding in queries.
-
-### Breaking out a metric by a dimension on another table
-
-To group a metric by a field that lives on a **different** table, add an explicit `joins` entry and break out on the join-aliased field. Do **not** break out (or order) a metric by a field reached only through an implicit foreign-key reference — the query processor cannot resolve an implicit join against a metric aggregation and rejects the query with a 400. Source the metric's base table, reference the metric in `aggregation`, join the dimension table, and break out on the joined column:
+A card metric with `source_card_portable_entity_id="T4wA_GPFwGb6R4FxIDGTo"`:
```json
{"lib/type": "mbql.stage/mbql",
- "source-table": ["Sample Database", null, "ORDERS"],
- "aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]],
- "joins": [{"alias": "Products",
- "strategy": "left-join",
- "stages": [{"lib/type": "mbql.stage/mbql",
- "source-table": ["Sample Database", null, "PRODUCTS"]}],
- "conditions": [["=", {},
- ["field", {}, ["Sample Database", null, "ORDERS", "PRODUCT_ID"]],
- ["field", {"join-alias": "Products"},
- ["Sample Database", null, "PRODUCTS", "ID"]]]]}],
- "breakout": [["field", {"join-alias": "Products"},
- ["Sample Database", null, "PRODUCTS", "CATEGORY"]]]}
+ "source-card": "T4wA_GPFwGb6R4FxIDGTo",
+ "filters": [[">", {}, ["field", {},
+ ["Sample Database", null, "ORDERS", "TOTAL"]], 0]],
+ "aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
```
-When the breakout dimension lives on the metric's **own** base table, no join is needed — just break out on a portable FK as in the example above.
+A metric with `source_card_portable_entity_id` requires that exact card. Substituting its base table causes an `Incompatible metric` error. Some metrics whose definition starts from a card require a base table instead; their tags carry `base_table_fully_qualified_name`. Use the attribute provided by the tag.
+
+Metrics are aggregations. Put the metric's own `portable_entity_id` in its `aggregation` clause, never in `source-table` or `source-card`. The `source_card_portable_entity_id` identifies its source card and belongs in `source-card`. Use `metabase://metric/<id>` URIs to read metadata via `read_resource`; do not embed them in queries.
## Using measures and segments
diff --git a/resources/metabot/skills/construct-notebook-query-operators.md b/resources/metabot/skills/construct-notebook-query-operators.md
index 0974ff481b9..c20d0868ffe 100644
--- a/resources/metabot/skills/construct-notebook-query-operators.md
+++ b/resources/metabot/skills/construct-notebook-query-operators.md
@@ -29,7 +29,7 @@ These catalogs accompany `construct_notebook_query`. The clause shape and field
- `["share", {}, <bool-pred>]` — fraction of rows where pred is true.
- `["stddev", {}, <num-expr>]`
- `["var", {}, <num-expr>]`
-- `["metric", {}, "<portable_entity_id>"]` — reference a defined metric. The metric's base table must be the stage's `source-table`.
+- `["metric", {}, "<portable_entity_id>"]` references a defined metric. Use the source specified by its `<metric>` tag: `base_table_fully_qualified_name` as `source-table`, or `source_card_portable_entity_id` as `source-card`.
- `["measure", {}, "<portable_entity_id>"]` — reference a defined measure (preferred over inlining its definition). The measure's table must be the stage's `source-table`.
## Order-by direction
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 79fc549f8b4..a7bab7f9159 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -22,10 +22,11 @@
## Implicit joins
- In addition to the shape passes above, `repair` also runs an **implicit-join pass** that uses
- the caller's `MetadataProvider` to auto-wire `source-field` options on field clauses that
- reference a table other than the stage's `source-table`. That pass is the only reason `repair`
- takes an `mp` argument - the shape passes themselves don't need it."
+ The implicit-join pass uses the caller's `MetadataProvider` to set `source-field` on references
+ to columns outside the stage's source. It handles table sources and columns omitted by a card source.
+
+ A card stage calls `lib/visible-columns` once, and only when a reference needs implicit-join repair.
+ See [[try-resolve-card-source-info]]."
(:require
[clojure.string :as str]
[clojure.walk :as walk]
@@ -33,6 +34,7 @@
[metabase.lib-be.core :as lib-be]
[metabase.lib.core :as lib]
[metabase.lib.expression :as lib.expression]
+ [metabase.lib.metadata :as lib.metadata]
[metabase.lib.metadata.protocols :as lib.metadata.protocols]
[metabase.lib.schema.mbql-clause :as mbql-clause]
[metabase.lib.schema.temporal-bucketing :as lib.schema.temporal-bucketing]
@@ -2080,10 +2082,14 @@
;;; ============================================================
;;; Pass 3 -- auto-wire `source-field` for implicit joins
;;;
-;;; When a field clause references a field on a table *other* than the stage's
-;;; `source-table`, and there is exactly one foreign key from the source table to that target
-;;; table, fill in the `source-field` option with the portable FK of the FK column. The QP
-;;; interprets this as an implicit join (the same machinery users get from the notebook UI).
+;;; When a field clause references a field on a table *other* than the stage's source table,
+;;; and there is exactly one foreign key from the source table to that target table, fill in
+;;; the `source-field` option with the portable FK of the FK column. The QP interprets this as
+;;; an implicit join (the same machinery users get from the notebook UI).
+;;;
+;;; Card stages use the FK columns the card returns; table stages use their outbound FKs.
+;;; Columns already returned by a card are left unchanged. An implicit join could select different rows.
+;;; Card stages with explicit joins are skipped because lib resolves their fields through those joins.
;;;
;;; The pass walks stage[0] only, skips descent into the `\"joins\"` subtree (field clauses
;;; inside a join live in a join context), and is a no-op on clauses that already carry any
@@ -2123,6 +2129,18 @@
(resolve/import-table-fk import-resolver source-table-fk))
(catch Exception _ nil)))
+(defn- try-resolve-source-card-id
+ "Resolve the stage's `source-card` entity ID to a numeric Card ID, or nil on failure."
+ [import-resolver source-card-eid]
+ (try
+ (cond
+ (and (pos-int? source-card-eid) resolve/*numeric-ids-allowed?*)
+ source-card-eid
+
+ (and import-resolver (string? source-card-eid))
+ (resolve/import-fk import-resolver source-card-eid 'Card))
+ (catch Exception _ nil)))
+
(defn- try-resolve-field-id
"Resolve a field target — a portable field FK or a numeric field id — to a numeric field id.
Walks JSON-unfolded parent chains via the resolver's `import-field-fk`. Returns nil on failure."
@@ -2133,14 +2151,54 @@
(resolve/import-field-fk import-resolver field-fk))
(catch Exception _ nil)))
+(defn- try-resolve-field-table-id
+ "The `:table-id` of the field with `field-id`, or nil on failure."
+ [mp field-id]
+ (try
+ (when field-id
+ (:table-id (lib.metadata.protocols/field mp field-id)))
+ (catch Exception _ nil)))
+
(defn- try-resolve-field-target-table-id
"Resolve the target-table-id of a field target — a portable field FK or a numeric field id —
by looking up the field and following its `:table-id`. Returns nil on failure."
[mp import-resolver field-fk]
+ (try-resolve-field-table-id mp (try-resolve-field-id import-resolver field-fk)))
+
+(defn- try-resolve-card-source-info
+ "Return the fields, tables, and implicit-join candidates exposed by the card with `card-id`.
+
+ Return nil for native cards, metric cards, or cards that cannot be inspected. Candidates come from the card's
+ returned columns, as reported by `lib/visible-columns`."
+ ;; A card may omit its base table's FK columns, so candidates must come from its returned columns.
+ ;; Return nil on inspection failure: an empty set could cause a returned column to be replaced by a join.
+ [mp card-id]
(try
- (when-let [fid (try-resolve-field-id import-resolver field-fk)]
- (:table-id (lib.metadata.protocols/field mp fid)))
- (catch Exception _ nil)))
+ (when-let [card (and mp card-id (lib.metadata/card mp card-id))]
+ (when (and (:table-id card) (not= :metric (:type card)))
+ (let [cols (lib/visible-columns (lib/query mp card))
+ implicit? #(= :source/implicitly-joinable (:lib/source %))
+ own (remove implicit? cols)]
+ {:card-name (:name card)
+ ;; Recovery hints need the card type because models and saved questions use different lookup URIs.
+ :card-type (if (= :model (:type card)) "model" "question")
+ :returned-field-ids (into #{} (keep :id) own)
+ ;; A table already read by the card cannot be joined to itself to recover an omitted column.
+ ;; Include its base table even when an aggregation returns no columns from it.
+ :read-table-ids (into #{(:table-id card)} (keep :table-id) own)
+ :fks-by-target (->> cols
+ (filter implicit?)
+ (keep (fn [c]
+ (when-let [fk-id (:fk-field-id c)]
+ {:source-field-id fk-id
+ :source-field-name (:fk-field-name c)
+ :target-table-id (:table-id c)})))
+ distinct
+ (group-by :target-table-id))})))
+ (catch Exception e
+ ;; Log inspection failures so skipped repairs can be traced from later missing-column errors.
+ (log/warnf e "Could not inspect source card %s for implicit-join repair; skipping the stage" card-id)
+ nil)))
(defn- export-source-field-portable
"Convert a numeric FK column id into its portable `[db schema table field …]` path, via the
@@ -2159,11 +2217,107 @@
(defn- display-portable [fk]
(pr-str fk))
+(defn- display-target-table
+ "Return the target table's name from a portable FK, or its numeric ID for a numeric field reference."
+ [fk target-table-id]
+ (if (vector? fk)
+ (pr-str (nth fk 2))
+ (str target-table-id)))
+
+(defn- no-fk-path-error [fk source-label target-table-id extra]
+ (ex-info (format (str "Field %s is on table %s, which has no foreign key from the source %s, so it cannot be "
+ "reached implicitly. To group or filter by a column from that table, add an explicit `joins:` "
+ "entry and reference the field using the join alias. If the foreign key comes from a table you "
+ "joined in this stage, set `source-field-join-alias` instead. Otherwise use a field from the "
+ "source.")
+ (display-portable fk)
+ (display-target-table fk target-table-id)
+ (pr-str source-label))
+ (merge {:status-code 400
+ :error :no-fk-path
+ :agent-error? true
+ :field fk
+ :target-table target-table-id}
+ extra)))
+
+(defn- column-not-returned-error [fk card-name card-type card-id target-table-id]
+ ;; Recovery hints use the card ID and type to choose the appropriate lookup.
+ (ex-info (let [[kind short-kind] (if (= "model" card-type) ["model" "model"] ["saved question" "question"])]
+ (format (str "Field %s is on %s. The %s %s reads from that table but does not return this field. "
+ "Use a column that %s returns.")
+ (display-portable fk)
+ (display-target-table fk target-table-id)
+ kind
+ (pr-str card-name)
+ short-kind))
+ {:status-code 400
+ :error :column-not-returned
+ :agent-error? true
+ :field fk
+ :source-card card-id
+ :source-card-type card-type
+ :target-table target-table-id}))
+
+(defn- unexportable-fk-error [fk source-label target-table-id extra]
+ (ex-info (format (str "Field %s is on table %s, which is reachable from the source %s only through a foreign key "
+ "that could not be resolved, so it cannot be reached implicitly. Add an explicit `joins:` entry "
+ "and reference the field using the join alias, or use a column the source returns.")
+ (display-portable fk)
+ (display-target-table fk target-table-id)
+ (pr-str source-label))
+ (merge {:status-code 400
+ :error :unexportable-fk
+ :agent-error? true
+ :field fk
+ :target-table target-table-id}
+ extra)))
+
+(defn- ambiguous-fk-error [fk source-label n target-table-id extra by-name?]
+ ;; The metadata provider is not permission-aware, so listing FK candidates could reveal restricted column names.
+ ;; Recovery hints send the agent to permission-checked field listings. `by-name?` also requires the FK's output name
+ ;; when a card returns the same FK column under several names.
+ (ex-info (format (str "Field %s can be reached from %s via %d foreign keys. Specify the `source-field` option on the "
+ "field clause"
+ (when by-name?
+ ", and `source-field-name` with the name the source returns that foreign-key column under,")
+ " to disambiguate.")
+ (display-portable fk)
+ (pr-str source-label)
+ n)
+ (merge {:status-code 400
+ :error :ambiguous-fk
+ :agent-error? true
+ :field fk
+ :target-table target-table-id}
+ extra)))
+
+(defn- fill-from-candidates
+ "Set `source-field` from the single candidate, or throw an agent error.
+
+ When `stamp-name?` is true, also set `source-field-name` if the candidate has a name. A renamed FK column needs
+ that name in the join condition."
+ [clause opts fk export-resolver candidates
+ {:keys [source-label target-table-id ex-data-extra stamp-name? strict?]}]
+ (case (count candidates)
+ 0 (throw (no-fk-path-error fk source-label target-table-id ex-data-extra))
+ 1 (let [{:keys [source-field-id source-field-name]} (first candidates)
+ src-fk (export-source-field-portable export-resolver source-field-id)]
+ (cond
+ src-fk (assoc clause 1 (cond-> (assoc opts "source-field" src-fk)
+ (and stamp-name? source-field-name)
+ (assoc "source-field-name" source-field-name)))
+ ;; A card reference known to need an implicit join would otherwise compile to a missing column.
+ strict? (throw (unexportable-fk-error fk source-label target-table-id ex-data-extra))
+ :else clause))
+ (throw (ambiguous-fk-error fk source-label (count candidates) target-table-id ex-data-extra stamp-name?))))
+
(defn- maybe-fill-source-field
- "Given a field-clause vector (already known to be a field clause), the stage's source-table-id,
- and the precomputed outbound-FK map, return either the original clause or a clause with
- `\"source-field\"` populated. Throws `:no-fk-path` or `:ambiguous-fk` on hard errors."
- [clause mp import-resolver export-resolver source-table-id outbound-fks-by-target]
+ "Return the field clause with an inferred `source-field`, or leave it unchanged.
+
+ `source-info` describes a table or card (see [[stage-source-info]]). A card exposes only its returned columns,
+ so a field on its base table may still be unavailable. Throw `:no-fk-path`, `:ambiguous-fk`,
+ `:column-not-returned`, or `:unexportable-fk` when the reference cannot be resolved safely."
+ [clause mp import-resolver export-resolver source-info]
(let [opts (nth clause 1)
fk (nth clause 2)]
(cond
@@ -2183,60 +2337,64 @@
clause
:else
- (let [target-table-id (try-resolve-field-target-table-id mp import-resolver fk)]
- (cond
+ (let [field-id (try-resolve-field-id import-resolver fk)
+ target-table-id (try-resolve-field-table-id mp field-id)]
+ (if (nil? target-table-id)
;; Couldn't resolve target table: skip (validate/resolve will surface the real error).
- (nil? target-table-id)
clause
-
- ;; Field is on the source table itself: nothing to do.
- (= target-table-id source-table-id)
- clause
-
- :else
- (let [candidates (get outbound-fks-by-target target-table-id)]
- (case (count candidates)
- 0 (let [src-name (display-source-table mp source-table-id)
- ;; MBQL 5 can carry `fk` as a numeric id rather than a `[db schema table field]`
- ;; vector. For the portable form the vector already carries the table's own
- ;; name; for the numeric form we name the table by its bare id rather than
- ;; reading it back off the metadata provider (a plain id, not `pr-str`, which
- ;; would render `"42"` and read as a table literally named 42).
- tbl-name (if (vector? fk)
- (pr-str (nth fk 2))
- (str target-table-id))]
- (throw (ex-info (tru "Field {0} is on table {1}, which has no foreign key from the source table {2}, so it cannot be reached implicitly. To group or filter by a column from that table, add an explicit `joins:` entry and reference the field using the join alias. Otherwise use a field from the source table."
- (display-portable fk)
- tbl-name
- (pr-str src-name))
- {:status-code 400
- :error :no-fk-path
- :agent-error? true
- :field fk
- :source-table source-table-id
- :target-table target-table-id})))
- 1 (let [{:keys [source-field-id]} (first candidates)
- src-fk (export-source-field-portable export-resolver source-field-id)]
- (if src-fk
- (assoc clause 1 (assoc opts "source-field" src-fk))
- clause))
- ;; Deliberately do NOT enumerate the candidate FK columns: the metadata provider
- ;; is un-sandboxed and any leaked `[db schema table field]` path could surface
- ;; bridge-table column names the caller is not permitted to see (`:agent-error?`
- ;; relays the message verbatim to the user). The LLM can recover by listing the
- ;; source table's fields with the surface's own discovery tool to inspect the
- ;; available foreign-key columns.
- (let [src-name (display-source-table mp source-table-id)]
- (throw (ex-info (tru "Field {0} can be reached from {1} via {2} foreign keys. Specify the `source-field` option on the field clause to disambiguate."
- (display-portable fk)
- (pr-str src-name)
- (count candidates))
- {:status-code 400
- :error :ambiguous-fk
- :agent-error? true
- :field fk
- :source-table source-table-id
- :target-table target-table-id}))))))))))
+ (case (:kind source-info)
+ :table
+ (let [source-table-id (:table-id source-info)]
+ (if (= target-table-id source-table-id)
+ ;; Field is on the source table itself: nothing to do.
+ clause
+ (fill-from-candidates clause opts fk export-resolver
+ (get (:fks-by-target source-info) target-table-id)
+ {:source-label (display-source-table mp source-table-id)
+ :target-table-id target-table-id
+ :ex-data-extra {:source-table source-table-id}})))
+
+ :card
+ (if-let [info @(:info source-info)]
+ (cond
+ ;; An implicit join could select different rows from the column the card already returns.
+ (contains? (:returned-field-ids info) field-id)
+ clause
+
+ ;; The card omits this column; joining its table to itself would not recover it.
+ (contains? (:read-table-ids info) target-table-id)
+ (throw (column-not-returned-error fk (:card-name info) (:card-type info)
+ (:card-id source-info) target-table-id))
+
+ :else
+ (fill-from-candidates clause opts fk export-resolver
+ (get (:fks-by-target info) target-table-id)
+ {:source-label (:card-name info)
+ :target-table-id target-table-id
+ :ex-data-extra {:source-card (:card-id source-info)
+ :source-card-type (:card-type info)}
+ :stamp-name? true
+ :strict? true}))
+ ;; Skip repair when the card cannot be inspected; guessing a join could select different rows.
+ clause)))))))
+
+(defn- stage-source-info
+ "Return a stage's table or card source information, or nil when the stage must be skipped.
+
+ Skip unresolved sources and card stages with explicit joins, whose fields lib can resolve through those joins.
+ Card metadata is resolved only when a field needs implicit-join repair; candidates come from the card's returned
+ FK columns, not every FK on its base table. See [[try-resolve-card-source-info]]."
+ [stage mp import-resolver]
+ (if-let [source-table-fk (get stage "source-table")]
+ (when-let [table-id (try-resolve-source-table-id import-resolver source-table-fk)]
+ {:kind :table
+ :table-id table-id
+ :fks-by-target (group-by :target-table-id (resolve.mp/outbound-fks-from-table mp table-id))})
+ (when-let [card-id (when (empty? (get stage "joins"))
+ (try-resolve-source-card-id import-resolver (get stage "source-card")))]
+ {:kind :card
+ :card-id card-id
+ :info (delay (try-resolve-card-source-info mp card-id))})))
(defn- resolve-implicit-joins-in-stage
"Apply implicit-join repair to a single stage map (string-keyed). Returns an updated stage.
@@ -2245,29 +2403,24 @@
restoring it afterwards - field clauses inside explicit joins are expected to carry a
`join-alias` already."
[stage mp import-resolver export-resolver]
- (let [source-table-fk (get stage "source-table")
- source-table-id (try-resolve-source-table-id import-resolver source-table-fk)]
- (if-not source-table-id
- ;; Can't resolve source-table: skip the pass and let validate/resolve surface the error.
- stage
- (let [outbound (resolve.mp/outbound-fks-from-table mp source-table-id)
- by-target (group-by :target-table-id outbound)
- joins (get stage "joins")
- stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))
- walked (walk/postwalk
- (fn [node]
- (if (field-clause? node)
- (maybe-fill-source-field node mp import-resolver export-resolver
- source-table-id by-target)
- node))
- stage')]
- (cond-> walked
- (contains? stage "joins") (assoc "joins" joins))))))
+ (if-let [source-info (stage-source-info stage mp import-resolver)]
+ (let [joins (get stage "joins")
+ stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))
+ walked (walk/postwalk
+ (fn [node]
+ (if (field-clause? node)
+ (maybe-fill-source-field node mp import-resolver export-resolver source-info)
+ node))
+ stage')]
+ (cond-> walked
+ (contains? stage "joins") (assoc "joins" joins)))
+ ;; Can't resolve the source: skip the pass and let validate/resolve surface the error.
+ stage))
(defn- resolve-implicit-joins*
"Top-level implicit-join pass. Only `stages[0]` participates: implicit-join `source-field`
- inference is a relationship from a stage's `source-table` to a sibling table via a single FK,
- and only the first stage of a query has a `source-table` of its own. Stages 1+ feed off the
+ inference is a relationship from a stage's source table to a sibling table via a single FK,
+ and only the first stage of a query has a source of its own. Stages 1+ feed off the
previous stage's output, where field references are by string name (handled by
[[infer-cross-stage-field-types*]] further down)."
[query mp content-store]
@@ -2282,6 +2435,11 @@
;;; Pass 3.5 -- auto-wire `source-field-join-alias` for implicit joins through an explicitly
;;; joined table.
;;;
+;;; This pass uses the source table's FKs and only handles `source-table:` stages.
+;;; Card stages with explicit joins reach lib unchanged; their base table may expose FKs that the card omits.
+;;;
+;;; TODO (Mihael 2026-09-28) -- extend this pass to `source-card:` stages.
+;;;
;;; Trigger: a field clause `["field" {opts} <portable-fk>]` whose target table is reachable
;;; from **exactly one** explicit join's source table via **exactly one** FK, and which the
;;; basic implicit-join pass (Pass 4) cannot handle (target not reachable from `source-table`,
@@ -3216,7 +3374,8 @@
Runs *before* the basic implicit-join pass so the latter sees an already-
disambiguated clause.
4. auto-wire `source-field` on field clauses that reference a foreign table via a single
- unambiguous FK on the source table (implicit-join resolution);
+ unambiguous FK on the source table, or on a `source-card:` stage via a single FK column
+ the card returns (implicit-join resolution);
4.5. infer `base-type` / `effective-type` on field references in a stage whose source is
a saved question / model (`source-card:`), using the card's resolved returned columns.
Must run *before* Pass 5: a `source-card` stage's own bare-name field refs need
@@ -3240,8 +3399,9 @@
Pass 4, Pass 4.5, Pass 4.7, Pass 5, and Pass 5.7 require `mp` (a `MetadataProvider`); they are
best-effort no-ops when `mp` can't resolve the relevant pieces (so the subsequent
validate/resolve stages can surface the real error with their own, better messages). Hard FK
- errors from Pass 4 (`:no-fk-path`, `:ambiguous-fk`) are raised as `:agent-error?` ex-info so
- the tool wrapper can relay them to the LLM. Pass 4.5 and Pass 5 never throw on their own - if
+ errors from Pass 4 (`:no-fk-path`, `:ambiguous-fk`, and on a `source-card:` stage
+ `:column-not-returned` and `:unexportable-fk`) are raised as `:agent-error?` ex-info so the
+ tool wrapper can relay them to the LLM. Pass 4.5 and Pass 5 never throw on their own - if
a prefix / source-card can't be resolved, they just leave the affected clauses alone; Pass
5.7 then raises the `:agent-error?` only for refs that survived to the end still unresolved.
diff --git a/src/metabase/mcp/v2/recovery_hints.clj b/src/metabase/mcp/v2/recovery_hints.clj
index 8f727c85c01..9203d354627 100644
--- a/src/metabase/mcp/v2/recovery_hints.clj
+++ b/src/metabase/mcp/v2/recovery_hints.clj
@@ -9,6 +9,7 @@
error key with no entry here yields no sentence, which is the intended failure mode: a
missing hint reads as terse, a wrong one sends the agent at a tool it does not have."
(:require
+ [clojure.string :as str]
[metabase.mcp.v2.message :as message]))
(set! *warn-on-reflection* true)
@@ -20,9 +21,10 @@
(let [id (or (parse-long (str entity-id)) entity-id)]
(case entity-type
"metric"
- (message/msg [(str "Metrics are aggregations, not sources. To use metric %s, put its base table's "
- "numeric id into `source-table:` (find it via \"search\" or \"browse_data\") and "
- "reference the metric by its numeric id: `aggregation: [[metric, {}, %s]]`.")]
+ (message/msg [(str "Metrics are aggregations, not sources. To use metric %s, build the stage on its required "
+ "source: its base table's numeric ID in `source-table:`, or its saved question or model's "
+ "numeric ID in `source-card:` (find it via \"search\" or \"browse_data\"). "
+ "Then reference the metric by its numeric ID: `aggregation: [[metric, {}, %s]]`.")]
id id)
("question" "model" "card")
@@ -36,10 +38,32 @@
(message/msg ["`source-table:` accepts a numeric table id; `source-card:` accepts a saved-card numeric id."]))))
+(defn- usable-sources-hint
+ "Return the usable source IDs from an `:incompatible-metric` error as MCP guidance."
+ [usable-sources]
+ (when (seq usable-sources)
+ (apply message/msg
+ [(str "Use numeric IDs here: " (str/join "; " (repeat (count usable-sources) "%s")) ".")]
+ (for [[metric-id {:keys [source-table source-card]}] (sort-by key usable-sources)]
+ (if source-table
+ (message/msg ["metric %s needs `\"source-table\": %s`"] metric-id source-table)
+ (message/msg ["metric %s needs `\"source-card\": %s`"] metric-id source-card))))))
+
+(defn- card-fields-hint
+ "Return MCP guidance for listing the source card's columns, or nil when the error names no card."
+ [source-card source-card-type]
+ (when (and source-card source-card-type)
+ (message/msg [(str "Call \"get_content\" with items [{\"type\": %s, \"id\": %s}] and include [\"fields\"] to "
+ "list the columns it returns.")]
+ source-card-type source-card)))
+
(defn recovery-hint
"The v2 recovery message for an agent error's `ex-data`, or nil when it has none."
- [{:keys [error entity-type entity-id]}]
+ [{:keys [error entity-type entity-id usable-sources source-card source-card-type]}]
(case error
+ :incompatible-metric
+ (usable-sources-hint usable-sources)
+
:uri-in-source-table
(uri-hint entity-type entity-id)
@@ -59,8 +83,17 @@
"the table to list its columns with their numeric ids.")])
:ambiguous-fk
- (message/msg [(str "Call \"browse_data\" with action \"get_fields\" for the "
- "source table to list the available foreign-key columns.")])
+ (if-let [card-fields (card-fields-hint source-card source-card-type)]
+ ;; A card returns a joined foreign key under its join alias (`O2__USER_ID`), which the table's fields don't show.
+ (message/msg [(str "%s Put the foreign-key column's `id` in `source-field` and its `lib/desired-column-alias` "
+ "(its `name` when it has none) in `source-field-name`.")]
+ card-fields)
+ (message/msg [(str "Call \"browse_data\" with action \"get_fields\" for the "
+ "source table to list the available foreign-key columns.")]))
+
+ ;; Raised only on a `source-card:` stage, where the way out is a column the card returns.
+ (:column-not-returned :unexportable-fk)
+ (card-fields-hint source-card source-card-type)
:no-fk-path
(message/msg [(str "If a metric relates to that table, call \"browse_data\" with action \"get_fields\" for the "
diff --git a/src/metabase/metabot/db.clj b/src/metabase/metabot/db.clj
index 8fe9e4f2af1..8563db62fcd 100644
--- a/src/metabase/metabot/db.clj
+++ b/src/metabase/metabot/db.clj
@@ -9,6 +9,7 @@
[metabase.app-db.core :as mdb]
[metabase.audit-app.core :as audit-app]
[metabase.collections.models.collection :as collection.model]
+ [metabase.lib-be.core :as lib-be]
[metabase.lib.schema.id :as lib.schema.id]
[metabase.metabot.schema :as metabot.schema]
[metabase.models.interface :as mi]
@@ -503,9 +504,13 @@
(t2/select [:model/Table :id :name :display_name :schema :db_id :description] :id [:in table-ids] {:from [(warehouse-schema-overlay/table-query)]}))
(mu/defn table-schema-rows
- "The ID, name, schema, and Database ID of the Tables with `table-ids`."
+ "Return the ID, name, schema, and database ID of each table in `table-ids`.
+
+ Rows also include `:is_published` and `:collection_id`, which `can-read?` and `can-query?` need to check access
+ through a collection. Both keys must be present, even when nil."
[table-ids :- [:sequential ::lib.schema.id/table]]
- (t2/select [:model/Table :id :name :schema :db_id] :id [:in table-ids] {:from [(warehouse-schema-overlay/table-query {:user-settings? false})]}))
+ (t2/select [:model/Table :id :name :schema :db_id :is_published :collection_id] :id [:in table-ids]
+ {:from [(warehouse-schema-overlay/table-query {:user-settings? false})]}))
(mu/defn table-curation-rows
"The ID, published flag, data layer, and data authority of the Tables with `table-ids`."
@@ -809,10 +814,25 @@
[card-ids :- [:sequential ::lib.schema.id/card]]
(t2/select-pk->fn :entity_id :model/Card :id [:in card-ids]))
-(mu/defn card-table-ids
- "A map of Card ID to Table ID for `card-ids`."
- [card-ids :- [:sequential ::lib.schema.id/card]]
- (t2/select-pk->fn :table_id :model/Card :id [:in card-ids]))
+(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]].
+ 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)}]))
+ (when (seq card-ids)
+ (t2/select [(t2/table-name :model/Card) :id :table_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?`."
+ ;; `can-read?` needs `:collection_id` and `:document_id`, including nil values, to check access.
+ [card-ids :- [:or [:set ::lib.schema.id/card] [:sequential ::lib.schema.id/card]]]
+ (t2/select [:model/Card :id :name :entity_id :collection_id :document_id] :id [:in card-ids]))
(mu/defn card-search-rows
"The searchable columns of the Cards with `card-ids`."
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index ef697e7e5c7..6ae5a4c5201 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -10,9 +10,11 @@
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
[metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
[metabase.lib.metadata.protocols :as lib.metadata.protocols]
[metabase.lib.schema]
[metabase.lib.schema.expression :as lib.schema.expression]
+ [metabase.lib.util :as lib.util]
[metabase.metabot.agent.links :as links]
[metabase.metabot.agent.streaming :as streaming]
[metabase.metabot.db :as metabot.db]
@@ -25,13 +27,15 @@
[metabase.metabot.tools.shared.instructions :as instructions]
[metabase.metabot.tools.shared.llm-shape :as llm-shape]
[metabase.metabot.tools.util :as tools.u]
+ [metabase.models.interface :as mi]
[metabase.models.serialization.resolve :as serdes.resolve]
[metabase.models.serialization.resolve.mp :as resolve.mp]
[metabase.util :as u]
[metabase.util.i18n :refer [tru]]
[metabase.util.json :as json]
[metabase.util.malli :as mu]
- [metabase.util.malli.registry :as mr])
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.match :as match])
(:import
(java.sql SQLException)))
@@ -717,6 +721,97 @@
(not-any? not-runnable-problem errors)
(str ". " (tru "This usually means a field reference is missing its type or names a column that does not exist, or an aggregation or window function such as `offset` is in `expressions:` instead of `aggregation:` or `order-by:`")))))))
+(defn- incompatible-metrics
+ "Return the required sources of incompatible metrics in the first stage, sorted by metric ID.
+
+ Return nil when all referenced metrics are compatible. A metric with an unreadable definition has a nil
+ requirement and is reported on every source. Classification follows
+ [[metabase.metabot.tools.util/metric-required-source]].
+
+ Only source mismatches in the first stage's aggregations are checked. Metrics in later stages, joins, or other
+ clauses still reach the query processor, as do other errors such as archived metrics."
+ [mp query]
+ (let [referenced (into #{}
+ (match/match-many (lib/aggregations query 0)
+ [:metric _ (id :guard pos-int?)]
+ id))]
+ (when (seq referenced)
+ (let [stage-card-id (lib.util/source-card-id query)
+ _ (lib.metadata/bulk-metadata mp :metadata/card (cond-> referenced
+ 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)
+ (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))
+ compatible? (and required
+ (tools.u/metric-compatible-with-stage?
+ required
+ {:stage-card-id stage-card-id
+ :stage-table-id stage-table-id}))]
+ (when-not compatible?
+ [metric-id required]))))
+ referenced))))))
+
+(defn- incompatible-metric-explanation
+ "Describe each incompatible metric and the source it requires.
+
+ Return `{:message ... :usable-sources {metric-id {:source-table id} | {:source-card id}}}`.
+ `required-by-metric-id` comes from [[incompatible-metrics]]; `mp` supplies the database name for portable FKs.
+ Include names and sources only when the current user may access them. `:usable-sources` identifies those same
+ sources by numeric ID."
+ [mp required-by-metric-id]
+ (let [metric-ids (keys required-by-metric-id)
+ required (vals required-by-metric-id)
+ source-cards (into #{} (keep #(when (= :card (:kind %)) (:card-id %))) required)
+ source-table-ids (into #{} (keep #(when (= :table (:kind %)) (:table-id %))) required)
+ ;; The metadata provider is not permission-aware; names and entity IDs need separate read checks.
+ readable (tools.u/readable-source-cards (into (set metric-ids) source-cards))
+ db-name (:name (lib.metadata/database mp))
+ table-id->fk (when (seq source-table-ids)
+ (into {}
+ (comp (filter mi/can-query?)
+ (map (fn [{:keys [id schema name]}] [id [db-name schema name]])))
+ (metabot.db/table-schema-rows (vec source-table-ids))))
+ describe (fn [metric-id]
+ (let [r (get required-by-metric-id metric-id)
+ eid (when (= :card (:kind r))
+ (:entity_id (get readable (:card-id r))))
+ table-fk (when (= :table (:kind r))
+ (get table-id->fk (:table-id r)))]
+ (str (pr-str (or (:name (get readable metric-id)) metric-id))
+ (cond
+ ;; An unreadable definition, or a multi-stage metric over a native source card.
+ (or (nil? r)
+ (and (= :table (:kind r)) (nil? (:table-id r))))
+ " (has no usable source)"
+
+ table-fk
+ (str " (needs source-table: " (json/encode table-fk) ")")
+
+ eid
+ (str " (needs source-card: " (pr-str eid) ")")
+
+ :else
+ " (defined on a source you do not have access to)"))))]
+ {:message (str "These metrics cannot be used on this stage's source: "
+ (str/join ", " (map describe metric-ids))
+ ". "
+ "Either change the stage's source-table:/source-card: to the one shown for each metric, "
+ "or drop the metric and express the aggregation directly.")
+ :usable-sources (into {}
+ (keep (fn [[metric-id r]]
+ (cond
+ (and (= :table (:kind r)) (contains? table-id->fk (:table-id r)))
+ [metric-id {:source-table (:table-id r)}]
+
+ (and (= :card (:kind r)) (contains? readable (:card-id r)))
+ [metric-id {:source-card (:card-id r)}])))
+ required-by-metric-id)}))
+
(defn- execute-representations-query*
"Execute a notebook query in the canonical portable MBQL 5 representations format.
@@ -806,6 +901,15 @@
;; argument against the same schema.
_editor-ok (repr.repair/assert-editor-accepts-expressions! pmbql-query)
_buckets-ok (repr.repair/assert-temporal-buckets-on-temporal-columns! pmbql-query)
+ ;; Check sources after schema validation so an incompatible metric produces a retryable error before execution.
+ _metrics-ok (when-let [bad (incompatible-metrics mp pmbql-query)]
+ (let [{:keys [message usable-sources]} (incompatible-metric-explanation mp bad)]
+ (throw (ex-info message
+ {:agent-error? true
+ :error :incompatible-metric
+ :metric-ids (vec (keys bad))
+ :usable-sources usable-sources
+ :status-code 400}))))
exported-repr (repr.resolve/export-query mp pmbql-query permission-aware-content-store)
_validated' (repr/validate-query exported-repr)
query-id (u/generate-nano-id)]
diff --git a/src/metabase/metabot/tools/core.clj b/src/metabase/metabot/tools/core.clj
index f50d8cb820e..4707c31ced5 100644
--- a/src/metabase/metabot/tools/core.clj
+++ b/src/metabase/metabot/tools/core.clj
@@ -485,7 +485,7 @@
(try
(thunk)
(catch Throwable e
- (let [{:keys [agent-error? status-code error entity-type entity-id]} (ex-data e)
+ (let [{:keys [agent-error? status-code error entity-type entity-id source-card source-card-type]} (ex-data e)
code (pipeline-error-code error)]
(cond
;; Lib exceptions can also carry `:agent-error?`, but their messages aren't written for the model.
@@ -494,7 +494,9 @@
code
(cond-> {:message (or (ex-message e) "")}
entity-type (assoc :entity-type entity-type)
- (some? entity-id) (assoc :entity-id entity-id))
+ (some? entity-id) (assoc :entity-id entity-id)
+ source-card (assoc :source-card source-card
+ :source-card-type source-card-type))
{:cause e})
(contains? refusal-status-codes status-code)
diff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.clj
index a76a89a2b41..83d7a289ca1 100644
--- a/src/metabase/metabot/tools/entity_details.clj
+++ b/src/metabase/metabot/tools/entity_details.clj
@@ -312,18 +312,48 @@
:dimensions dims}))))
explicit-joins)))))))
+(defn- card-read-verdicts-for-metrics
+ "Return read permissions for the source cards required by `metric-cards`, or nil when none are required.
+
+ 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]
+ (let [source-card-ids (into #{}
+ (keep #(let [r (metabot.tools.u/metric-required-source %)]
+ (when (= :card (:kind r)) (:card-id r))))
+ metric-cards)]
+ (when (seq source-card-ids)
+ (let [readable (metabot.tools.u/readable-source-cards source-card-ids)]
+ (into {} (map (juxt identity #(contains? readable %))) source-card-ids)))))
+
+(defn- card-readable?
+ "Return whether the current user may read the card with `card-id`.
+
+ `card-read-verdicts` is a trusted `{card-id -> boolean}` map of checks already made by the caller. It includes
+ false results for missing cards. Pass it separately from tool options, since those contain untrusted model input.
+ Cards absent from the map are checked by row; a deleted card returns false."
+ [card-read-verdicts card-id]
+ (if (contains? card-read-verdicts card-id)
+ (get card-read-verdicts card-id)
+ (contains? (metabot.tools.u/readable-source-cards #{card-id}) card-id)))
+
(defn metric-details
"Get metric details as returned by tools."
([id] (metric-details id nil))
([id options]
(when-let [card (metabot.tools.u/get-card id)]
(metric-details card (lib-be/application-database-metadata-provider (:database_id card)) options)))
+ ([card metadata-provider options]
+ (metric-details card metadata-provider options nil))
+ ;; `card-read-verdicts`: see [[card-readable?]].
([card metadata-provider {:keys [field-values-fn with-default-temporal-breakout? with-queryable-dimensions?
with-segments?]
:or {field-values-fn add-field-values
with-default-temporal-breakout? true
with-queryable-dimensions? true
- with-segments? false}}]
+ with-segments? false}}
+ card-read-verdicts]
(let [id (:id card)
;; Database metadata so the LLM can build portable FKs — metrics are always
;; referenced from a query targeting a specific database, and the LLM needs the
@@ -331,30 +361,24 @@
database (lib.metadata/database metadata-provider)
database-id (:id database)
database-name (:name database)
- ;; Base table of the metric — the metric is an aggregation defined on top of a
- ;; specific table. To use the metric, the LLM has to put that table in
- ;; `source-table:` and reference the metric in `aggregation:`.
- ;;
- ;; This arity is called with two shapes of `card`:
- ;; 1. The t2 row from `get-card` (via the single-arg `metric-details`) —
- ;; snake_case, so `:table_id`.
- ;; 2. A `lib.metadata/card` map forwarded by `convert-metric` (called from
- ;; `table-details` while listing available metrics) — that map is a
- ;; `SnakeHatingMap`, so the only valid key is kebab-case `:table-id`; reading
- ;; `:table_id` on it throws a deprecation-error that would surface to the LLM
- ;; as an empty `<resource>` with just `**Error: ...**`.
- ;; We accept both. `report_card.table_id` / metadata `:table-id` already points
- ;; to the metric's base table and is kept in sync, so we use it verbatim instead
- ;; of digging through `:dataset_query`.
- ;; Reading the metric Card is collection-based and does not imply permission to
- ;; reveal metadata for this physical Table.
- source-table-id (or (:table-id card) (:table_id card))
+ ;; 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)
+ 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
(mi/can-query? :model/Table source-table-id))
(lib.metadata/table metadata-provider source-table-id))
- base-table-portable-fk (when (and database-name source-table)
- [database-name (:schema source-table) (:name source-table)])
- query-needed? (and source-table
+ source-card (when (and source-card-id
+ ;; Reading the metric is collection-based and does not imply permission to read
+ ;; its source card.
+ (card-readable? card-read-verdicts source-card-id))
+ (lib.metadata/card metadata-provider source-card-id))
+ ;; Without a usable source, dimensions would suggest that the metric can still be queried.
+ source-unavailable? (and (nil? source-table) (nil? source-card))
+ ;; A card metric can have a usable source even when it has no base table.
+ ;; Its dimensions come from the metric query, with column permissions checked below.
+ query-needed? (and (not source-unavailable?)
(or with-default-temporal-breakout? with-queryable-dimensions? with-segments?))
metric-card (when query-needed?
(lib.metadata/card metadata-provider id))
@@ -396,45 +420,48 @@
:database_name database-name
;; Portable entity id — the string the LLM must copy verbatim into a
;; `[metric, {}, <entity_id>]` aggregation clause to reference this metric.
- ;; Accept both shapes (see `source-table-id` note above): t2 rows use
- ;; `:entity_id`, `lib.metadata/card` maps use `:entity-id`.
- :portable_entity_id (or (:entity-id card) (:entity_id card))
+ :portable_entity_id (metabot.tools.u/metric-card-shape-get card :entity-id :entity_id)
:verified (verified-review? id "card")}
- ;; Base table the metric aggregates. The LLM uses `:base_table_portable_fk`
- ;; verbatim as `source-table:` in the query that consumes the metric. These fields
- ;; are added only when the base Table is readable.
- source-table
- (assoc :base_table_id source-table-id
- :base_table_name (:name source-table)
- :base_table_portable_fk base-table-portable-fk)
-
- (and source-table with-default-temporal-breakout?)
- (assoc :default_time_dimension_field_id (some-> default-temporal-breakout
- (->> (metabot.tools.u/->result-column metric-query))
- :field_id))
-
- (and source-table with-queryable-dimensions?)
+ true
+ (merge (metabot.tools.u/metric-source-fields
+ {:source-card (when source-card
+ {:id (:id source-card)
+ :name (:name source-card)
+ :entity_id (:entity-id source-card)})
+ :source-table source-table
+ :database-name database-name}))
+
+ ;; Keep the breakout name here because callers can request it without requesting dimensions.
+ (and query-needed? with-default-temporal-breakout?)
+ (merge (when-let [col (some->> default-temporal-breakout
+ (metabot.tools.u/->result-column metric-query))]
+ {:default_time_dimension_field_id (:field_id col)
+ :default_time_dimension_field_name (:name col)}))
+
+ (and query-needed? with-queryable-dimensions?)
(assoc :queryable-dimensions (mapv #(metabot.tools.u/->result-column metric-query %) queryable-columns))
(seq join-required-dims)
(assoc :join-required-dimensions join-required-dims)
- (and source-table with-segments?)
+ (and query-needed? with-segments?)
(assoc :segments (if-let [segments (lib/available-segments metric-query)]
(mapv #(convert-measure-or-segment % :filters) segments)
[]))))))
(defn- convert-metric
- ([db-metric metadata-provider]
- (convert-metric db-metric metadata-provider nil))
- ([db-metric metadata-provider options]
- (-> db-metric
- (metric-details metadata-provider (assoc options :with-queryable-dimensions? false))
- ;; Keep the DB-name / base-table-fk / portable_entity_id fields so callers (incl.
- ;; `metric->xml`) can surface them to the LLM without a second round-trip.
- (select-keys [:id :type :name :description :default_time_dimension_field_id
- :database_id :database_name :portable_entity_id
- :base_table_id :base_table_name :base_table_portable_fk]))))
+ "Return metric metadata for the LLM, using trusted read permissions from `card-read-verdicts`.
+
+ See [[card-readable?]] for the requirements on that argument."
+ [db-metric metadata-provider options card-read-verdicts]
+ (-> db-metric
+ (metric-details metadata-provider (assoc options :with-queryable-dimensions? false) card-read-verdicts)
+ (select-keys [:id :type :name :description
+ :default_time_dimension_field_id :default_time_dimension_field_name
+ :database_id :database_name :portable_entity_id
+ :base_table_id :base_table_name :base_table_portable_fk
+ :source_card_id :source_card_name :source_card_portable_entity_id
+ :source_unavailable])))
(declare ^:private related-tables)
@@ -507,9 +534,13 @@
;; [db-name, schema-or-null, table-name]. LLM uses this as `source-table`.
:portable_fk (when db-name [db-name (:schema base) (:name base)])}
(m/assoc-some :description (:description base)
+ ;; Table queries can list card metrics through their base table; batch the source-card read checks.
:metrics (when with-metrics?
- (not-empty (mapv #(convert-metric % mp options)
- (lib/available-metrics table-query))))
+ (let [metrics (lib/available-metrics table-query)
+ verdicts (card-read-verdicts-for-metrics 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))))
:measures (when with-measures?
(not-empty (mapv #(convert-measure-or-segment % :aggregation)
(lib/available-measures table-query))))
@@ -680,8 +711,9 @@
metadata-provider
query
shared.content-store/default-store))
+ ;; These metrics require the source card already returned by `card-details`, so its read check is sufficient.
:metrics (when with-metrics?
- (not-empty (mapv #(convert-metric % metadata-provider options)
+ (not-empty (mapv #(convert-metric % metadata-provider options {id true})
(lib/available-metrics card-query))))
:measures (when with-measures?
(not-empty (mapv #(convert-measure-or-segment % :aggregation)
@@ -697,11 +729,16 @@
[card-type database-id cards options]
(metabot.perms/with-cache
(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))
+ readable-source-card-ids (into #{} (keep (fn [[id readable?]] (when readable? id))) card-read-verdicts)
detail-fn (case card-type
- :metric metric-details
+ :metric #(metric-details %1 %2 %3 card-read-verdicts)
:model card-details
:question card-details)]
- (lib.metadata/bulk-metadata mp :metadata/card (map :id cards))
+ ;; Warm source-card metadata too, since `metric-details` reads each card's name and entity ID.
+ (lib.metadata/bulk-metadata mp :metadata/card (into (set (map :id cards)) readable-source-card-ids))
;; Realized eagerly (not `map`) so every detail-fn call -- and the metabot.perms lookups it
;; triggers -- runs inside this with-cache binding. A lazy seq would only be walked by the
;; caller, after the binding above has already unwound, defeating the cache.
@@ -731,6 +768,12 @@
(throw (ex-info (i18n/tru "Unknown Metabot.")
{:status-code 400}))))
+(defn- arguments->options
+ "The detail-fn options for a tool call's `arguments` map."
+ [arguments]
+ (cond-> arguments
+ (= (:with-field-values? arguments) false) (assoc :field-values-fn identity)))
+
(defn get-table-details
"Get information about the table, question or model with .
`table-id` is string either encoding an integer that is the ID of a table
@@ -747,8 +790,7 @@
(try
(lib-be/with-metadata-provider-cache
(metabot.perms/with-cache
- (let [options (cond-> arguments
- (= (:with-field-values? arguments) false) (assoc :field-values-fn identity))
+ (let [options (arguments->options arguments)
details (cond
(= :model entity-type)
(let [card (card-details entity-id (assoc options :only-model true))]
@@ -796,8 +838,7 @@
(try
(lib-be/with-metadata-provider-cache
(metabot.perms/with-cache
- (let [options (cond-> arguments
- (= (:with-field-values? arguments) false) (assoc :field-values-fn identity))
+ (let [options (arguments->options arguments)
details (if (int? metric-id)
(metric-details metric-id options)
(throw (ex-info "Invalid metric_id format"
@@ -891,8 +932,7 @@
(try
(lib-be/with-metadata-provider-cache
(metabot.perms/with-cache
- (let [options (cond-> arguments
- (= (:with-field-values? arguments) false) (assoc :field-values-fn identity))
+ (let [options (arguments->options arguments)
details (if (int? report-id)
(let [card (t2/hydrate (metabot.tools.u/get-card report-id) :average_query_time)
mp (lib-be/application-database-metadata-provider (:database_id card))
diff --git a/src/metabase/metabot/tools/recoverable/pipeline.clj b/src/metabase/metabot/tools/recoverable/pipeline.clj
index 3abe638366b..491d18efac1 100644
--- a/src/metabase/metabot/tools/recoverable/pipeline.clj
+++ b/src/metabase/metabot/tools/recoverable/pipeline.clj
@@ -29,11 +29,15 @@
"The payload every pipeline-error declaration takes.
`:message` is the pipeline's own sentence. `:entity-type` and `:entity-id` are present only for
- the codes whose recovery depends on what was referenced (see [[uri-in-source-table!]])."
+ the codes whose recovery depends on what was referenced (see [[uri-in-source-table!]]).
+ `:source-card` and `:source-card-type` are the numeric ID and type of the stage's `source-card:`,
+ present only for the codes a `source-card:` stage raises (see [[column-not-returned!]])."
[:map {:closed true}
- [:message :string]
- [:entity-type {:optional true} [:maybe :string]]
- [:entity-id {:optional true} [:maybe [:or :string :int]]]])
+ [:message :string]
+ [:entity-type {:optional true} [:maybe :string]]
+ [:entity-id {:optional true} [:maybe [:or :string :int]]]
+ [:source-card {:optional true} [:maybe :int]]
+ [:source-card-type {:optional true} [:maybe [:enum "model" "question"]]]])
;;; ------------------------------------------- Shared recovery steps ----------------------------------------------
@@ -90,6 +94,14 @@
:text (str "`source-table:` takes a portable FK `[<db-name>, <schema>, <table>]`; `source-card:` takes an "
"entity_id string.")})
+(defn- card-fields-step
+ "Return a recovery step listing `what` from the source card, or nil when `payload` names no card."
+ [{:keys [source-card source-card-type]} what]
+ (when (and source-card source-card-type)
+ {:uses #{"read_resource"}
+ :text (str "Call `read_resource` with `metabase://" source-card-type "/" source-card "/fields` to list the "
+ what " this " source-card-type " returns.")}))
+
;;; ------------------------------------------- Declarations -------------------------------------------------------
(defmacro ^:private defpipeline-error
@@ -172,11 +184,28 @@
;; are its breakouts and aggregations, not a table's fields.
[])
+(defrecoverable column-not-returned!
+ "A field on a `source-card:` stage is on a table the card reads but is not a column the card returns."
+ {:payload ::payload}
+ [payload]
+ {:message (:message payload)
+ :recovery (filterv some? [(card-fields-step payload "columns")])})
+
;;; Joins
-(defpipeline-error ambiguous-fk!
+(defrecoverable ambiguous-fk!
"More than one foreign key connects the two tables, so the join path is ambiguous."
- [list-fks-step])
+ {:payload ::payload}
+ [payload]
+ {:message (:message payload)
+ :recovery [(or (card-fields-step payload "foreign-key columns") list-fks-step)]})
+
+(defrecoverable unexportable-fk!
+ "The only foreign key that reaches a field's table could not be resolved, so the field cannot be reached implicitly."
+ {:payload ::payload}
+ [payload]
+ {:message (:message payload)
+ :recovery (filterv some? [(card-fields-step payload "columns")])})
(defpipeline-error ambiguous-fk-via-join!
"More than one foreign key connects the joined tables, so the join path is ambiguous."
@@ -238,6 +267,11 @@
"The referenced segment belongs to a different database than the query."
[])
+(defpipeline-error incompatible-metric!
+ "A metric was used with an incompatible stage source."
+ ;; No step: the message names the source each metric needs, or says it has none.
+ [])
+
;;; Query shape
(defpipeline-error missing-source-in-first-stage!
@@ -331,9 +365,10 @@
"metric"
{:uses #{"read_resource"}
:text (str "Metrics are aggregations, not sources. To use metric " entity-id
- ", put its base table into `source-table:` — combine the `database_name` and "
- "`base_table_fully_qualified_name` attributes from its search result or "
- "`read_resource metabase://metric/" entity-id "` — and reference the metric as "
+ ", build the stage on the source specified by its `<metric>` tag (in its search result or "
+ "`read_resource metabase://metric/" entity-id "`): `base_table_fully_qualified_name` "
+ "with `database_name` as `source-table:`, or `source_card_portable_entity_id` as "
+ "`source-card:`. Then reference the metric as "
"`aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")}
("question" "model" "card")
diff --git a/src/metabase/metabot/tools/recovery_hints.clj b/src/metabase/metabot/tools/recovery_hints.clj
index 1a6be14a28d..796ce58c808 100644
--- a/src/metabase/metabot/tools/recovery_hints.clj
+++ b/src/metabase/metabot/tools/recovery_hints.clj
@@ -20,14 +20,12 @@
"The `source-table:`-took-a-URI sentence, which varies by what the URI pointed at."
[entity-type entity-id]
(case entity-type
- ;; The `{}` options slot has to sit outside the format string — MessageFormat reads a brace
- ;; as a placeholder, and `tru` rejects the escaped form as a skipped argument index.
"metric"
- ;; `{0}` and `{1}` are both the entity id: `tru` rejects a repeated index, because
- ;; MessageFormat counts placeholder occurrences and distinct indices separately.
- (str (tru "Metrics are aggregations, not sources. To use metric {0}, put its base table into `source-table:` — combine the `database_name` and `base_table_fully_qualified_name` attributes from its search result or `read_resource metabase://metric/{1}` — and reference the metric as:"
- (str entity-id) (str entity-id))
- " `aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
+ (str "Metrics are aggregations, not sources. To use metric " entity-id ", build the stage on the source specified by its "
+ "`<metric>` tag (in its search result or `read_resource metabase://metric/" entity-id "`): "
+ "`base_table_fully_qualified_name` with `database_name` as `source-table:`, or "
+ "`source_card_portable_entity_id` as `source-card:`. Then reference the metric as "
+ "`aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
("question" "model" "card")
(tru "To reference a saved question or model as a query source, put its `portable_entity_id` (the 21-char string from its search result or `read_resource`) into `source-card:` — not a URI.")
@@ -38,9 +36,16 @@
(tru "`source-table:` accepts a portable FK `[<db-name>, <schema>, <table-name>]` or, via `source-card:`, a saved-card `portable_entity_id`.")))
+(defn- card-fields-hint
+ "Return guidance for listing `what` from the source card, or nil when `data` names no card."
+ [{:keys [source-card source-card-type]} what]
+ (when (and source-card source-card-type)
+ (str "Call `read_resource` with `metabase://" source-card-type "/" source-card "/fields` to list the " what
+ " this " source-card-type " returns.")))
+
(defn recovery-hint
"The v1 recovery sentence for an agent error's `ex-data`, or nil when it has none."
- [{:keys [error entity-type entity-id]}]
+ [{:keys [error entity-type entity-id] :as data}]
(case error
:uri-in-source-table
(uri-hint entity-type entity-id)
@@ -61,7 +66,11 @@
(tru "Call `read_resource` with `metabase://table/<numeric id>/fields` to list this table''s columns.")
:ambiguous-fk
- (tru "Call `read_resource` with `metabase://table/<numeric id>/fields` for the source table to list the available foreign-key columns.")
+ (or (card-fields-hint data "foreign-key columns")
+ (tru "Call `read_resource` with `metabase://table/<numeric id>/fields` for the source table to list the available foreign-key columns."))
+
+ (:column-not-returned :unexportable-fk)
+ (card-fields-hint data "columns")
:no-fk-path
(tru "If a metric relates to that table, read its dimensions resource `metabase://metric/<metric_id>/dimensions`, which lists the exact `joins:` clause to paste and the columns it unlocks.")
diff --git a/src/metabase/metabot/tools/run_query.clj b/src/metabase/metabot/tools/run_query.clj
index ba8eee4f7a0..b5bf37cd8ed 100644
--- a/src/metabase/metabot/tools/run_query.clj
+++ b/src/metabase/metabot/tools/run_query.clj
@@ -17,6 +17,7 @@
[metabase.metabot.tools.shared :as shared]
[metabase.metabot.tools.shared.llm-shape :as llm-shape]
[metabase.metabot.tools.sql.common :as sql.common]
+ [metabase.metabot.tools.util :as tools.u]
[metabase.models.interface :as mi]
[metabase.query-processor.compile :as qp.compile]
[metabase.query-processor.pipeline :as qp.pipeline]
@@ -309,18 +310,19 @@
(defn- metric-source
"Return the source that [[metric-not-runnable!]] accepts for a readable `metric`.
- Use the model or question that the metric is built on, or its base table. Return `:none` if the user can't read
- the source card or query the base table."
+ Use the source selected by [[metabase.metabot.tools.util/metric-required-source]]. Return `:none` if the user
+ can't read the source card or query the base table."
[metric]
- (let [source-card (some-> (:source_card_id metric) metabot.db/card)]
+ (let [{:keys [kind card-id table-id]} (tools.u/metric-required-source metric)
+ source-card (when (= :card kind) (metabot.db/card card-id))]
(cond
(some-> source-card mi/can-read?)
{:card-type (:type source-card)
:entity-id (:entity_id source-card)}
;; Reading the metric is collection-based and does not imply querying its table.
- (and (nil? (:source_card_id metric))
- (some->> (:table_id metric) (mi/can-query? :model/Table)))
+ (and (= :table kind)
+ (some->> table-id (mi/can-query? :model/Table)))
:base-table
:else
diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.clj
index 31819966c91..b5abbdd92dc 100644
--- a/src/metabase/metabot/tools/search.clj
+++ b/src/metabase/metabot/tools/search.clj
@@ -13,6 +13,7 @@
[metabase.metabot.tools.shared :as shared]
[metabase.metabot.tools.shared.instructions :as instructions]
[metabase.metabot.tools.shared.llm-shape :as llm-shape]
+ [metabase.metabot.tools.util :as metabot.tools.u]
[metabase.models.interface :as mi]
[metabase.permissions.core :as perms]
[metabase.search.core :as search]
@@ -169,53 +170,51 @@
(assoc r :portable_entity_id eid)
r))))))
-(defn- enrich-with-metric-base-tables
- "Attach base-table info (`:base_table_id`, `:base_table_name`, `:base_table_schema`,
- `:base_table_portable_fk`) to metric search results.
-
- A metric is a Card whose `:dataset_query` aggregates a specific table; the LLM needs that
- table's portable FK as the `source-table:` when it wants to use the metric. Without this
- enrichment the LLM sees the metric's `portable_entity_id` in search but has to either
- hallucinate the base table (observed failure mode: `[<db>, public, customers]`) or do an
- extra `read_resource` round-trip. We read the two columns directly from
- `report_card.table_id` + `metabase_table.{schema,name}` to keep the lookup O(1) extra
- query per search call, regardless of number of metrics in the result set. Base-table
- metadata is attached only when the current user can read that Table; collection access
- to the metric Card does not imply access to its physical source.
-
- Requires `:database_name` to already be set on each metric result (done earlier by
- [[enrich-with-database-engines]]) so we can assemble the full portable FK
- `[database_name, schema, table]`."
+(defn- enrich-with-metric-sources
+ "Add the source required to use each metric in the search results.
+
+ Return base-table fields, source-card fields, or `:source_unavailable`, as selected by
+ [[metabase.metabot.tools.util/metric-required-source]]. Check table query access or card read access separately
+ 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."
[results]
(let [metric-ids (->> results (filter #(= "metric" (:type %))) (keep :id) distinct)
- card-id->table-id (when (seq metric-ids)
- (metabot.db/card-table-ids metric-ids))
- table-ids (->> card-id->table-id vals (remove nil?) distinct)
- table-id->info (when (seq table-ids)
- (into {}
- (comp (filter mi/can-read?)
- (map (juxt :id (juxt :schema :name))))
- (metabot.db/table-schema-rows table-ids)))
- metric-id->table-info
+ card-id->source (when (seq metric-ids)
+ (metabot.db/card-source-info metric-ids))
+ metric-id->required (into {}
+ (keep (fn [[metric-id row]]
+ (when-let [r (metabot.tools.u/metric-required-source row)]
+ [metric-id r])))
+ card-id->source)
+ metric-id->source-card-id
(into {}
- (keep (fn [[metric-id table-id]]
- (when-let [[schema table-name] (get table-id->info table-id)]
- [metric-id {:table-id table-id
- :schema schema
- :table-name table-name}])))
- card-id->table-id)]
+ (keep (fn [[metric-id r]]
+ (when (= :card (:kind r)) [metric-id (:card-id r)])))
+ metric-id->required)
+ source-card-id->row
+ (metabot.tools.u/readable-source-cards (distinct (vals metric-id->source-card-id)))
+ metric-id->table-id (into {}
+ (keep (fn [[metric-id r]]
+ (when (and (= :table (:kind r)) (:table-id r))
+ [metric-id (:table-id r)])))
+ metric-id->required)
+ table-ids (->> metric-id->table-id vals distinct)
+ ;; Use the same query permission check as `metric-details` so both tools offer the same sources.
+ table-id->row (when (seq table-ids)
+ (into {}
+ (comp (filter mi/can-query?)
+ (map (juxt :id #(select-keys % [:id :schema :name]))))
+ (metabot.db/table-schema-rows table-ids)))]
(cond->> results
- (seq card-id->table-id)
+ (seq metric-ids)
(mapv (fn [{:keys [id type database_name] :as result}]
- (if-let [{:keys [table-id schema table-name]}
- (when (= "metric" type)
- (get metric-id->table-info id))]
- (cond-> (assoc result
- :base_table_id table-id
- :base_table_name table-name
- :base_table_schema schema)
- database_name
- (assoc :base_table_portable_fk [database_name schema table-name]))
+ (if (= "metric" type)
+ (merge result (metabot.tools.u/metric-source-fields
+ {:source-card (get source-card-id->row (get metric-id->source-card-id id))
+ :source-table (get table-id->row (get metric-id->table-id id))
+ :database-name database_name}))
result))))))
(defn- enrich-with-measure-segment-base-tables
@@ -459,7 +458,7 @@
enrich-with-collection-descriptions
enrich-with-database-engines
enrich-with-portable-entity-ids
- enrich-with-metric-base-tables
+ enrich-with-metric-sources
enrich-with-measure-segment-base-tables
(validate-and-enrich-documents (boolean archived)))
(vary-meta assoc :total total))))
@@ -565,7 +564,7 @@
enrich-with-collection-descriptions
enrich-with-database-engines
enrich-with-portable-entity-ids
- enrich-with-metric-base-tables
+ enrich-with-metric-sources
enrich-with-measure-segment-base-tables
remove-unreadable-transforms)))
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index 578ae9a0ef0..1f39c9ef48f 100644
--- a/src/metabase/metabot/tools/shared/llm_shape.clj
+++ b/src/metabase/metabot/tools/shared/llm_shape.clj
@@ -425,19 +425,20 @@
fqn))))
(defn format-metric-dimensions-table
- "Render a metric's queryable dimensions as a markdown table that names the **source table**
- each dimension comes from and the exact **portable FK** to copy into a `field` clause.
+ "Render a metric's dimensions with their source tables and field references.
- A metric's dimensions span its base table and every FK-reachable table, so a bare field list
- is ambiguous: the LLM can't tell which table a name like `name` lives on, and duplicate names
- across joined tables (e.g. several `campaign_id`/`id` columns) are indistinguishable. The
- `Source table` and `Reference` columns remove that ambiguity."
+ A portable FK works on table and card stages and distinguishes columns with the same name on different tables.
+ Computed card columns have no portable FK and use their output machine name. Real database fields without a
+ portable FK get no reference; their bare names could resolve to the wrong column."
[dims]
(te/markdown-table
(map (fn [d]
(assoc d
:source (dimension-source-table d)
- :reference (when (vector? (:portable_fk d)) (json/encode (:portable_fk d)))))
+ :reference (cond
+ (vector? (:portable_fk d)) (json/encode (:portable_fk d))
+ ;; A string `:field_id` from `->result-column` is the computed column's output name.
+ (string? (:field_id d)) (json/encode (:field_id d)))))
dims)
{:name "Field Name" :field_id "Field ID" :type "Type"
:source "Source table" :reference "Reference (copy into a field clause)"}
@@ -485,15 +486,14 @@
(format-join-required-dimensions-table dimensions)))))
(defn metric->xml
- "Format metric for LLM consumption.
- Matches Python Metric.get_llm_representation exactly, except we additionally surface
- `database_name`, `base_table_fully_qualified_name`, and `portable_entity_id` as tag
- attributes — the three pieces of information the LLM needs to correctly use the metric
- in `construct_notebook_query` (as `aggregation: [[metric, {}, <eid>]]` on top of the
- metric's base table)."
+ "Format a metric as XML for the LLM.
+
+ Include its database name, portable entity ID, and the source required to use it in `construct_notebook_query`.
+ The source is identified by `base_table_fully_qualified_name` or `source_card_portable_entity_id`.
+ When no source is usable, include `source_unavailable` instead."
[{:keys [id name description verified queryable-dimensions join-required-dimensions collection
- default_time_dimension_field database_name base_table_portable_fk
- portable_entity_id]}]
+ default_time_dimension_field_name database_name base_table_portable_fk
+ portable_entity_id source_card_name source_card_portable_entity_id source_unavailable]}]
(render-llm-template
:metric
{:metric_id (str id)
@@ -505,9 +505,12 @@
(= 3 (count base_table_portable_fk)))
(let [[_db schema table] base_table_portable_fk]
(fully-qualified-name schema table)))
+ :metric_source_unavailable (boolean source_unavailable)
+ :metric_source_card_entity_id source_card_portable_entity_id
+ :metric_source_card_name source_card_name
:metric_portable_entity_id portable_entity_id
:metric_collection_xml (when collection (collection->xml collection))
- :metric_default_time_dimension (:name default_time_dimension_field)
+ :metric_default_time_dimension default_time_dimension_field_name
:metric_dimensions_table (when (seq queryable-dimensions)
(format-metric-dimensions-table queryable-dimensions))
:metric_join_required_xml (when (seq join-required-dimensions)
@@ -859,14 +862,12 @@
human-readable name the LLM needs as the first slot of every portable FK in
`construct_notebook_query`.
- For metric results we additionally surface `base_table_fully_qualified_name` (the
- `schema.table` of the table the metric aggregates). Combined with `database_name` this
- gives the LLM the full portable FK `[database_name, schema, table]` it must put in
- `source-table:` when using `[metric, {}, <portable_entity_id>]` as an aggregation —
- without a separate `read_resource` round-trip."
+ Metric results also identify the source to use with `[metric, {}, <portable_entity_id>]` in an aggregation.
+ `base_table_fully_qualified_name` and `database_name` identify a table source; `source_card_portable_entity_id`
+ identifies a card source. `source_unavailable` means that no usable source can be offered."
[{:keys [id type name description verified official curated can_write data_authority data_layer collection
database_id database_name database_engine database_schema portable_entity_id
- base_table_portable_fk]}]
+ base_table_portable_fk source_card_name source_card_portable_entity_id source_unavailable]}]
(let [fqn (cond
(#{"table" :table} type)
(when name (fully-qualified-name database_schema name))
@@ -909,7 +910,10 @@
:search_base_table_fqn (when (and (vector? base_table_portable_fk)
(= 3 (count base_table_portable_fk)))
(let [[_db schema table] base_table_portable_fk]
- (fully-qualified-name schema table)))})))
+ (fully-qualified-name schema table)))
+ :search_source_unavailable (boolean source_unavailable)
+ :search_source_card_entity_id source_card_portable_entity_id
+ :search_source_card_name source_card_name})))
(defn search-results->xml
"Format search results as XML wrapped in search-results element."
diff --git a/src/metabase/metabot/tools/util.clj b/src/metabase/metabot/tools/util.clj
index 7deb7901854..037d7b53773 100644
--- a/src/metabase/metabot/tools/util.clj
+++ b/src/metabase/metabot/tools/util.clj
@@ -7,6 +7,7 @@
[metabase.lib.metadata :as lib.metadata]
[metabase.lib.types.isa :as lib.types.isa]
[metabase.metabot.db :as metabot.db]
+ [metabase.models.interface :as mi]
[metabase.util :as u]))
(defn handle-agent-error
@@ -227,3 +228,91 @@
(if (seq destination-ids)
(remove #(contains? destination-ids (:database_id %)) cards)
cards)))
+
+;;; ------------------------------------------ metric sources ------------------------------------------
+
+(defn metric-card-shape-get
+ "Read `kebab-k` from a lib metadata card or `snake-k` from a Toucan row.
+
+ A lib metadata card throws on snake_case keys, even when the corresponding kebab-case value is nil."
+ [card kebab-k snake-k]
+ (if (:lib/type card)
+ (get card kebab-k)
+ (get card snake-k)))
+
+(defn readable-source-cards
+ "Return readable cards from `card-ids` as `{card-id -> row}`, or nil for empty input.
+
+ Read the cards in one query, including `:name`, `:entity_id`, and the columns needed by `can-read?`.
+ Missing and unreadable cards are omitted."
+ [card-ids]
+ (when (seq card-ids)
+ (into {}
+ (comp (filter mi/can-read?) (map (juxt :id identity)))
+ (metabot.db/card-source-rows card-ids))))
+
+(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.
+
+ 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)}))))
+
+(defn metric-compatible-with-stage?
+ "Return whether `required` permits a metric on the stage's source.
+
+ `required` comes from [[metric-required-source]]. `stage-table-id` is the resolved primary table ID, including
+ for card sources; `stage-card-id` identifies the source card. Throw for an unrecognized source kind."
+ [required {:keys [stage-card-id stage-table-id]}]
+ (case (:kind required)
+ :card (= (:card-id required) stage-card-id)
+ :table (and (some? (:table-id required))
+ (= (:table-id required) stage-table-id)
+ (or (not (:bare-table-only? required))
+ (nil? stage-card-id)))
+ (throw (ex-info "Unrecognized metric source kind" {:required required}))))
+
+(defn metric-source-fields
+ "Return the LLM fields identifying a metric's usable source.
+
+ A `source-card` with `:id`, `:name`, and `:entity_id` produces `:source_card_*` fields. A `source-table` with
+ `:id`, `:schema`, and `:name` produces `:base_table_*` fields; `database-name` is needed for the portable FK.
+ The caller must check access and supply the source selected by [[metric-required-source]].
+ When neither is usable, return `{:source_unavailable true}` so the LLM knows to skip the metric."
+ [{:keys [source-card source-table database-name]}]
+ (cond
+ source-card
+ {:source_card_id (:id source-card)
+ :source_card_name (:name source-card)
+ :source_card_portable_entity_id (:entity_id source-card)}
+
+ source-table
+ (cond-> {:base_table_id (:id source-table)
+ :base_table_name (:name source-table)
+ :base_table_schema (:schema source-table)}
+ database-name (assoc :base_table_portable_fk [database-name (:schema source-table) (:name source-table)]))
+
+ :else
+ {:source_unavailable true}))
diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.clj
index d7fd5b37ba6..48e93c31816 100644
--- a/test/metabase/agent_lib/representations/repair_test.clj
+++ b/test/metabase/agent_lib/representations/repair_test.clj
@@ -2135,6 +2135,26 @@
out (repair/repair mp-fks q)]
(is (= {} (get-in out ["stages" 0 "breakout" 0 1]))))))
+(deftest ^:parallel fill-from-candidates-unexportable-fk-test
+ (let [fill #'repair/fill-from-candidates
+ unused #(throw (ex-info "unexpected resolver call" {}))
+ resolver (reify serdes.resolve/SerdesExportResolver
+ (export-fk [_ _ _] (unused))
+ (export-fk-keyed [_ _ _ _] (unused))
+ (export-user [_ _] (unused))
+ (export-table-fk [_ _] (unused))
+ (export-field-fk [_ _] (throw (ex-info "boom" {}))))
+ clause ["field" {} ["DB" "PUBLIC" "PRODUCTS" "CATEGORY"]]
+ run (fn [strict?]
+ (fill clause {} (nth clause 2) resolver [{:source-field-id 1}]
+ {:source-label "Orders by user" :target-table-id 2 :strict? strict?}))]
+ (testing "a single candidate whose FK cannot be exported is its own error on a strict stage, not :no-fk-path"
+ (let [e (try (run true) nil (catch clojure.lang.ExceptionInfo e e))]
+ (is (=? {:error :unexportable-fk, :agent-error? true, :target-table 2} (ex-data e)))
+ (is (re-find #"only through a foreign key that could not be resolved" (ex-message e)))))
+ (testing "and leaves the clause bare on a non-strict stage"
+ (is (= clause (run false))))))
+
(deftest ^:parallel implicit-join-no-fk-path-test
(testing "throws :no-fk-path when the target table isn't reachable via any FK"
(try
@@ -2145,9 +2165,10 @@
(is (= :no-fk-path (:error d)))
(is (true? (:agent-error? d)))
(is (= (str "Field [\"Sample\" \"PUBLIC\" \"PRODUCTS\" \"CATEGORY\"] is on table \"PRODUCTS\", which has no foreign key "
- "from the source table \"ORDERS\", so it cannot be reached implicitly. "
+ "from the source \"ORDERS\", so it cannot be reached implicitly. "
"To group or filter by a column from that table, add an explicit `joins:` entry "
- "and reference the field using the join alias. Otherwise use a field from the source table.")
+ "and reference the field using the join alias. If the foreign key comes from a table you joined "
+ "in this stage, set `source-field-join-alias` instead. Otherwise use a field from the source.")
(ex-message e))))))))
(deftest ^:parallel implicit-join-ambiguous-fk-test
diff --git a/test/metabase/mcp/v2/queries_test.clj b/test/metabase/mcp/v2/queries_test.clj
index 8148fa468c8..f0a70359622 100644
--- a/test/metabase/mcp/v2/queries_test.clj
+++ b/test/metabase/mcp/v2/queries_test.clj
@@ -215,4 +215,20 @@
(message/render
(v2.recovery-hints/recovery-hint {:error :uri-in-source-table :entity-type "question" :entity-id "76"})))))
(testing "GHY-4544: a hint for a key with no sentence is nil"
- (is (nil? (v2.recovery-hints/recovery-hint {:error :no-such-error})))))
+ (is (nil? (v2.recovery-hints/recovery-hint {:error :no-such-error}))))
+ (testing "an ambiguous foreign key on a card source points at the columns the card returns"
+ (is (= (str "Call \"get_content\" with items [{\"type\": \"model\", \"id\": 12}] and include [\"fields\"] to list "
+ "the columns it returns. Put the foreign-key column's `id` in `source-field` and its "
+ "`lib/desired-column-alias` (its `name` when it has none) in `source-field-name`.")
+ (message/render (v2.recovery-hints/recovery-hint
+ {:error :ambiguous-fk :source-card 12 :source-card-type "model"}))))
+ (testing "and on a table source at the table's fields"
+ (is (str/includes? (message/render (v2.recovery-hints/recovery-hint {:error :ambiguous-fk}))
+ "\"browse_data\" with action \"get_fields\""))))
+ (testing "a column the card does not return points at the columns it does"
+ (doseq [error [:column-not-returned :unexportable-fk]]
+ (is (= (str "Call \"get_content\" with items [{\"type\": \"question\", \"id\": 12}] and include [\"fields\"] to "
+ "list the columns it returns.")
+ (message/render (v2.recovery-hints/recovery-hint
+ {:error error :source-card 12 :source-card-type "question"})))
+ (str error)))))
diff --git a/test/metabase/mcp/v2/tools/content_test.clj b/test/metabase/mcp/v2/tools/content_test.clj
index 8dc4232ad58..a491d9fe9ca 100644
--- a/test/metabase/mcp/v2/tools/content_test.clj
+++ b/test/metabase/mcp/v2/tools/content_test.clj
@@ -7,11 +7,13 @@
[metabase.lib.metadata :as lib.metadata]
[metabase.mcp.v2.message :as message]
[metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.queries :as v2.queries]
[metabase.mcp.v2.registry :as registry]
[metabase.mcp.v2.test-util :as v2.tu]
[metabase.mcp.v2.tools.content :as tools.content]
[metabase.metrics.core :as metrics]
[metabase.notification.test-util :as notification.tu]
+ [metabase.query-processor :as qp]
[metabase.test :as mt]
[metabase.util.json :as json]
[toucan2.core :as t2]))
@@ -139,6 +141,73 @@
(is (nil? (:error row)))
(is (re-find #"hello" (:content_markdown row)))))))))
+(deftest get-content-fields-name-a-card-foreign-key-for-source-field-name-test
+ (testing "the `fields` include gives each column the name `source-field-name` takes on a stage built on the card"
+ (let [mp (mt/metadata-provider)
+ orders (lib.metadata/table mp (mt/id :orders))
+ field #(lib.metadata/field mp (mt/id :orders %))
+ ;; O2 is the order whose ID is this order's PRODUCT_ID, so the card's two USER_ID columns differ.
+ self-join (-> (lib/join-clause orders [(lib/= (field :product_id) (field :id))])
+ (lib/with-join-alias "O2")
+ (lib/with-join-fields :all))
+ by-source (fn [stage]
+ (-> (v2.queries/execute-representations-query
+ {:lib/type "mbql/query"
+ :stages [(merge stage {:lib/type "mbql.stage/mbql"
+ :aggregation [["count" {}]]})]})
+ (get-in [:structured-output :query])
+ qp/process-query
+ mt/rows))]
+ (doseq [card-type [:question :model]]
+ (mt/with-temp [:model/Card {card-id :id} {:type card-type
+ :dataset_query (lib/join (lib/query mp orders) self-join)}]
+ (mt/with-test-user :crowberto
+ (testing card-type
+ (let [user-id-cols (->> (content-one {:items [{:type (name card-type) :id card-id}] :include ["fields"]})
+ :result_metadata
+ (filterv #(= (mt/id :orders :user_id) (:id %))))
+ via (fn [fk-name]
+ (by-source {:source-card card-id
+ :breakout [["field" {:source-field (mt/id :orders :user_id)
+ :source-field-name fk-name}
+ (mt/id :people :source)]]}))]
+ (is (= ["USER_ID" "O2__USER_ID"] (mapv :lib/desired-column-alias user-id-cols))
+ (pr-str user-id-cols))
+ (testing "and each name picks its own foreign key"
+ (is (= (by-source {:source-table (mt/id :orders)
+ :breakout [["field" {} (mt/id :people :source)]]})
+ (via "USER_ID")))
+ (is (not= (via "USER_ID") (via "O2__USER_ID"))))))))))))
+
+(deftest card-column-error-hint-lists-the-card-columns-test
+ (testing "a column the card does not return gets a hint naming the get_content call that lists the ones it does"
+ (let [mp (mt/metadata-provider)
+ field #(lib.metadata/field mp (mt/id :orders %))]
+ (mt/with-temp [:model/Card {card-id :id} {:type :model
+ :dataset_query (lib/with-fields
+ (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ [(field :id) (field :total)])}]
+ (mt/with-test-user :crowberto
+ (let [e (try
+ (v2.queries/execute-representations-query
+ {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-card card-id
+ :aggregation [["count" {}]]
+ :breakout [["field" {} (mt/id :orders :quantity)]]}]})
+ nil
+ (catch clojure.lang.ExceptionInfo e e))
+ items (some->> (ex-message e)
+ (re-find #"Call \"get_content\" with items (\[.*?\]) and include \[\"fields\"\]")
+ second
+ json/decode+kw)]
+ (is (=? {:error :column-not-returned} (ex-data e)))
+ (is (= [{:type "model" :id card-id}] items)
+ (ex-message e))
+ (is (= ["ID" "TOTAL"]
+ (mapv :name (:result_metadata (content-one {:items items :include ["fields"]}))))
+ "and that call lists the columns the model returns")))))))
+
(deftest get-content-dashboard-skeleton-test
(testing "GHY-4140: a dashboard returns the editing skeleton, never the raw REST dashcards array"
(mt/with-temp [:model/Dashboard {dash-id :id} {:parameters [{:name "Category" :slug "category"
diff --git a/test/metabase/metabot/agent/prompts_test.clj b/test/metabase/metabot/agent/prompts_test.clj
index f7949658bfe..aec0fe4a70b 100644
--- a/test/metabase/metabot/agent/prompts_test.clj
+++ b/test/metabase/metabot/agent/prompts_test.clj
@@ -50,6 +50,39 @@
(testing source
(is (= #{"null"}
(set (map second (re-seq #"\"Sample Database\",\s*([^,\s]+)" text))))))))
+(deftest ^:parallel metric-source-guidance-is-carried-by-every-surface-test
+ ;; The MCP prompt, advanced skill, and aggregation catalog must agree on how to choose a metric's source.
+ (let [surfaces {"prompts/tools/construct_notebook_query.md"
+ (slurp (io/resource "metabot/prompts/tools/construct_notebook_query.md"))
+ "skills/construct-notebook-query-advanced.md"
+ (slurp (io/resource "metabot/skills/construct-notebook-query-advanced.md"))}]
+ (doseq [[path doc] surfaces]
+ (testing path
+ (testing "names both source attributes the `<metric>` tag can carry"
+ (is (str/includes? doc "base_table_fully_qualified_name"))
+ (is (str/includes? doc "source_card_portable_entity_id")))
+ (testing "and the marker for a metric whose source cannot be offered"
+ (is (str/includes? doc "source_unavailable")))
+ (testing "and states the rule that makes the choice between them conditional"
+ (is (str/includes? doc "Build the stage on that source")))
+ (testing "and breaks a metric out through an implicit join, the way the query runs"
+ (is (str/includes? doc "on a `source-table` and a `source-card` stage alike"))
+ (is (not (str/includes? doc "cannot resolve an implicit join against a metric aggregation"))))))
+ (testing "the discovery snippet does not send the agent to the base table unconditionally"
+ (let [doc (slurp (io/resource "metabot/prompts/shared/prompt_snippets/semantic-layer-discovery.selmer"))]
+ (is (str/includes? doc "base_table_fully_qualified_name"))
+ (is (str/includes? doc "source_card_portable_entity_id"))
+ (is (str/includes? doc "Use the source specified by its `<metric>` tag"))))
+ (testing "the aggregation catalogs describe the metric clause the same way"
+ (doseq [path ["metabot/prompts/tools/construct_notebook_query.md"
+ "metabot/skills/construct-notebook-query-operators.md"]]
+ (testing path
+ (let [line (->> (str/split-lines (slurp (io/resource path)))
+ (filter #(str/starts-with? % "- `[\"metric\", {}, "))
+ first)]
+ (is (some? line) "the catalog lists a `metric` aggregation clause")
+ (is (str/includes? line "base_table_fully_qualified_name"))
+ (is (str/includes? line "source_card_portable_entity_id"))))))))
(deftest ^:parallel render-system-prompt-test
(testing "renders template with variables"
diff --git a/test/metabase/metabot/db_test.clj b/test/metabase/metabot/db_test.clj
new file mode 100644
index 00000000000..5ab7061eb43
--- /dev/null
+++ b/test/metabase/metabot/db_test.clj
@@ -0,0 +1,81 @@
+(ns metabase.metabot.db-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.metabot.db :as metabot.db]
+ [metabase.metabot.tools.util :as metabot.tools.u]
+ [metabase.metrics.core :as metrics]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.models.permissions :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(deftest table-schema-rows-are-permission-checkable-test
+ (testing "Narrowed table rows preserve query and read permission checks"
+ (let [table-id (mt/id :orders)
+ row (first (metabot.db/table-schema-rows [table-id]))]
+ (is (some? row))
+ (testing "the columns the permission path reads are present"
+ (is (contains? row :is_published))
+ (is (contains? row :collection_id)))
+ (testing "and the narrowed row agrees with the full row, for both predicates and both users"
+ (doseq [user [:crowberto :rasta]]
+ (mt/with-test-user user
+ (is (= (mi/can-query? :model/Table table-id) (mi/can-query? row))
+ (str "can-query? disagrees for " user))
+ (is (= (mi/can-read? :model/Table table-id) (mi/can-read? row))
+ (str "can-read? disagrees for " user))))))))
+
+(deftest card-source-info-classifies-legacy-metrics-test
+ (testing "Reading stored metric sources preserves stage structure without upgrading curated dimensions"
+ (let [mp (mt/metadata-provider)]
+ (mt/with-temp [:model/Card {source-id :id} {:name "Orders source"
+ :database_id (mt/id)
+ :dataset_query (lib/query mp (lib.metadata/table mp (mt/id :orders)))}]
+ (let [mp (mt/metadata-provider)
+ on-card (lib/query mp (lib.metadata/card mp source-id))
+ metric (fn [query] {:type :metric, :database_id (mt/id), :dataset_query query})]
+ (mt/with-temp [:model/Card {table-metric :id}
+ (metric (lib/aggregate (lib/query mp (lib.metadata/table mp (mt/id :orders))) (lib/count)))
+ :model/Card {card-metric :id}
+ (metric (lib/aggregate on-card (lib/count)))
+ :model/Card {two-stage-card-metric :id}
+ (metric (-> on-card lib/append-stage (lib/aggregate (lib/count))))]
+ (let [metric-ids [table-metric card-metric two-stage-card-metric]]
+ ;; A raw UPDATE, because before-insert forces `:card_schema` to current and `with-temp` would
+ ;; silently ignore it.
+ (t2/query-one {:update :report_card
+ :set {:card_schema 23, :dimensions nil, :dimension_mappings nil}
+ :where [:in :id metric-ids]})
+ (mt/with-dynamic-fn-redefs [metrics/compute-full-dimension-set
+ (fn [& _] (throw (ex-info "compute-full-dimension-set was armed" {})))]
+ (is (= {table-metric {:kind :table, :table-id (mt/id :orders), :bare-table-only? false}
+ card-metric {:kind :card, :card-id source-id}
+ ;; the QP reads the last stage, which carries no `:source-card`: only the base table works
+ two-stage-card-metric {:kind :table, :table-id (mt/id :orders), :bare-table-only? true}}
+ (update-vals (metabot.db/card-source-info metric-ids)
+ metabot.tools.u/metric-required-source)))))))))))
+
+(deftest card-source-rows-are-permission-checkable-test
+ (testing "Narrowed card rows preserve collection and document permission checks"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private"}
+ :model/Card {card-id :id}
+ {:name "A card"
+ :collection_id coll-id
+ :dataset_query (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders))))}]
+ (let [row (first (metabot.db/card-source-rows #{card-id}))]
+ (is (some? row))
+ (testing "the columns the permission path reads are present"
+ (is (contains? row :collection_id))
+ (is (contains? row :document_id)))
+ (testing "and the narrowed row agrees with the full row, for a reader and a non-reader"
+ (mt/with-test-user :crowberto
+ (is (= (mi/can-read? :model/Card card-id) (mi/can-read? row))))
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-test-user :rasta
+ (is (= (mi/can-read? :model/Card card-id) (mi/can-read? row)))
+ (is (false? (boolean (mi/can-read? row)))
+ "and the narrowed row does not make a restricted card look readable")))))))
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index e316f575160..729bd2e3aa6 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -11,6 +11,7 @@
[clojure.test :refer [are deftest is testing use-fixtures]]
[clojure.walk :as walk]
[malli.core :as mc]
+ [medley.core :as m]
[metabase.agent-lib.representations.repair :as repr.repair]
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
@@ -24,15 +25,21 @@
[metabase.metabot.agent.core :as agent]
[metabase.metabot.agent.links :as links]
[metabase.metabot.db :as metabot.db]
+ [metabase.metabot.test-util :as test-util]
[metabase.metabot.tools.construct :as construct]
[metabase.metabot.tools.core :as tools]
[metabase.metabot.tools.entity-details :as entity-details]
[metabase.metabot.tools.error :as tools.error]
[metabase.metabot.tools.recovery-hints :as v1-hints]
+ [metabase.metabot.tools.resources :as resources]
[metabase.metabot.tools.runtime :as tools.runtime]
+ [metabase.metabot.tools.util :as metabot.tools.util]
[metabase.models.interface :as mi]
[metabase.models.serialization.resolve :as serdes.resolve]
[metabase.models.serialization.resolve.mp :as resolve.mp]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.query-processor :as qp]
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]
[metabase.util.json :as json]
@@ -2235,6 +2242,804 @@
(is (= :temporal-unit-on-non-temporal-column (:error d)))
(is (str/includes? (ex-message e) (str "is a " type-name " column")))))))))))
+;;; ============================================================
+;;; Metric/source compatibility
+;;; ============================================================
+
+(defn- table-source-table-fk [table-id]
+ (let [db (t2/select-one-fn :name :model/Database :id (mt/id))
+ t (t2/select-one [:model/Table :schema :name] :id table-id)]
+ [db (:schema t) (:name t)]))
+
+(defn- products-source-table-fk [] (table-source-table-fk (mt/id :products)))
+(defn- orders-source-table-fk [] (table-source-table-fk (mt/id :orders)))
+
+(defn- metric-query-data [source metric-eid]
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [(merge source
+ {"lib/type" "mbql.stage/mbql"
+ "aggregation" [["metric" {} metric-eid]]})]}))
+
+(deftest card-based-metric-on-base-table-surfaces-agent-error-test
+ (testing "A single-stage card metric requires the card it was defined on"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-eid :entity_id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "sourcing the base table is rejected, naming the metric and the source it needs"
+ (let [e (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"Card-based metric"
+ (construct/execute-representations-query
+ (metric-query-data {"source-table" (products-source-table-fk)} metric-eid))))]
+ (is (=? {:agent-error? true, :error :incompatible-metric, :status-code 400}
+ (ex-data e)))
+ (is (str/includes? (ex-message e) question-eid)
+ "the message names the source card to build the stage on")))
+ (testing "sourcing the card it was defined on is accepted"
+ (let [result (construct/execute-representations-query
+ (metric-query-data {"source-card" question-eid} metric-eid))]
+ (is (= question-id (get-in result [:structured-output :query :stages 0 :source-card])))))))))
+
+(deftest table-based-metric-source-compatibility-test
+ (testing "A single-stage table metric also works on a card built on that table"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-eid :entity_id}
+ {:name "Table-based metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "on the table it was defined on"
+ (is (= (mt/id :products)
+ (-> (construct/execute-representations-query
+ (metric-query-data {"source-table" (products-source-table-fk)} metric-eid))
+ (get-in [:structured-output :query :stages 0 :source-table])))))
+ (testing "and on a card that resolves to that table"
+ (is (= question-id
+ (-> (construct/execute-representations-query
+ (metric-query-data {"source-card" question-eid} metric-eid))
+ (get-in [:structured-output :query :stages 0 :source-card])))))))))
+
+(deftest multi-stage-table-based-metric-is-pinned-to-source-table-test
+ (testing "A multi-stage table metric requires its base table directly"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id, metric-eid :entity_id}
+ {:name "Multi-stage metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-query {:source-table (mt/id :products)}
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "precondition: the metric is table-based and its table is the one the card reads from"
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ metric (lib.metadata/card mp metric-id)]
+ (is (nil? (:source-card-id metric)))
+ (is (= (mt/id :products) (:table-id metric)))
+ (is (= 2 (lib/stage-count (lib/query mp (:dataset-query metric))))
+ "and its definition really is multi-stage")
+ (is (= (mt/id :products)
+ (:table-id (lib.metadata/card mp question-id))))))
+ (testing "on its own table it is accepted, and the query the LLM gets back runs"
+ (let [query (-> (construct/execute-representations-query
+ (metric-query-data {"source-table" (products-source-table-fk)} metric-eid))
+ (get-in [:structured-output :query]))]
+ (is (= (mt/id :products) (get-in query [:stages 0 :source-table])))
+ (is (= [[200]] (mt/rows (qp/process-query query))))))
+ (testing "a card over the same table is rejected"
+ (let [e (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"Multi-stage metric"
+ (construct/execute-representations-query
+ (metric-query-data {"source-card" question-eid} metric-eid))))]
+ (is (=? {:agent-error? true, :error :incompatible-metric} (ex-data e)))
+ (is (str/includes? (ex-message e)
+ (str "needs source-table: " (json/encode (products-source-table-fk))))
+ "and it is told to use the base table, named as the portable FK to paste")))))))
+
+(deftest multi-stage-card-based-metric-is-pinned-to-base-table-test
+ (testing "A multi-stage card metric requires its base table, not its source card"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id, metric-eid :entity_id}
+ {:name "Multi-stage card metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "precondition: stage 0 names the card, but the definition is multi-stage"
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ metric (lib.metadata/card mp metric-id)]
+ (is (= question-id (:source-card-id metric))
+ "stage 0 names the card, which is the one source the metric cannot be used on")
+ (is (= 2 (lib/stage-count (lib/query mp (:dataset-query metric)))))
+ (is (= (mt/id :products) (:table-id metric)))))
+ (testing "on its base table it is accepted, and the query the LLM gets back runs"
+ (let [query (-> (construct/execute-representations-query
+ (metric-query-data {"source-table" (products-source-table-fk)} metric-eid))
+ (get-in [:structured-output :query]))]
+ (is (= (mt/id :products) (get-in query [:stages 0 :source-table])))
+ (is (= [[200]] (mt/rows (qp/process-query query)))
+ "the query processor accepts the base table as the source")))
+ (testing "the source card named by the definition is rejected"
+ (let [e (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"Multi-stage card metric"
+ (construct/execute-representations-query
+ (metric-query-data {"source-card" question-eid} metric-eid))))]
+ (is (=? {:agent-error? true, :error :incompatible-metric} (ex-data e)))
+ (is (str/includes? (ex-message e)
+ (str "needs source-table: " (json/encode (products-source-table-fk))))
+ "and it is told to use the base table, named as the portable FK to paste")))))))
+
+(deftest multi-stage-card-based-metric-really-does-500-on-its-source-card-test
+ (testing "The query processor rejects a multi-stage card metric used on its source card"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id}
+ {:name "Multi-stage card metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ query (-> (lib/query mp (lib.metadata/card mp question-id))
+ (lib/aggregate (lib.metadata/metric mp metric-id)))]
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"Incompatible metric"
+ (qp/process-query query))))))))
+
+(deftest multi-stage-card-based-metric-with-column-aggregation-executes-on-base-table-test
+ (testing "A multi-stage sum metric runs on its base table"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Orders question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :orders)}}}
+ :model/Card {metric-id :id, metric-eid :entity_id}
+ {:name "Multi-stage sum metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:sum [:field (mt/id :orders :total) nil]]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))]
+ (is (= {:kind :table, :table-id (mt/id :orders), :bare-table-only? true}
+ (metabot.tools.util/metric-required-source (lib.metadata/card mp metric-id)))))
+ (let [query (-> (construct/execute-representations-query
+ (metric-query-data {"source-table" (orders-source-table-fk)} metric-eid))
+ (get-in [:structured-output :query]))
+ rows (mt/rows (qp/process-query query))]
+ (is (= 1 (count rows)))
+ (is (number? (ffirst rows))
+ "the query compiles and returns a number"))))))
+
+(deftest gate-does-not-reject-metrics-that-are-merely-unavailable-test
+ (testing "An archived metric on its own source is not a source mismatch"
+ (mt/with-temp [:model/Card {metric-eid :entity_id}
+ {:name "Archived metric" :type :metric :archived true
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "it resolves against the table it was defined on"
+ (let [result (construct/execute-representations-query
+ (metric-query-data {"source-table" (products-source-table-fk)} metric-eid))]
+ (is (= (mt/id :products)
+ (get-in result [:structured-output :query :stages 0 :source-table])))
+ (is (= :metric (first (get-in result [:structured-output :query :stages 0 :aggregation 0]))))))))))
+
+(deftest incompatible-metric-message-does-not-disclose-unreadable-source-card-test
+ (testing "The error does not reveal an unreadable source card"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private"}
+ :model/Card {question-id :id, question-eid :entity_id}
+ {:name "Secret question" :type :question :collection_id coll-id
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id}
+ {:name "Metric on secret question" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [{msg :message, :keys [usable-sources]}
+ (#'construct/incompatible-metric-explanation
+ (lib-be/application-database-metadata-provider (mt/id))
+ {metric-id {:kind :card, :card-id question-id}})]
+ (is (empty? usable-sources)
+ "nor its numeric ID")
+ (is (str/includes? msg "Metric on secret question")
+ "the metric itself is readable to this user, so naming it is fine")
+ (is (not (str/includes? msg question-eid))
+ "but the source card's portable entity ID must not leak")
+ (is (str/includes? msg "do not have access")))))))
+
+(deftest incompatible-metric-message-does-not-disclose-unreadable-metric-name-test
+ (testing "The error does not reveal an unreadable metric name"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private"}
+ :model/Card {metric-id :id, metric-eid :entity_id}
+ {:name "Secret metric"
+ :type :metric
+ :collection_id coll-id
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)
+ :aggregation [[:count]]}}}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "the pipeline refuses an unreadable metric on either source"
+ (let [refusal (fn [source-table]
+ (try
+ (construct/execute-representations-query
+ (metric-query-data {"source-table" source-table} metric-eid))
+ :constructed
+ (catch clojure.lang.ExceptionInfo e
+ {:status (:status-code (ex-data e))
+ :error (:error (ex-data e))
+ :message (ex-message e)})))
+ on-orders (refusal (orders-source-table-fk))]
+ (is (=? {:status 403} on-orders))
+ (is (= on-orders (refusal (products-source-table-fk)))
+ "so the refusal says nothing about which source the metric needs")))
+ (let [msg (:message (#'construct/incompatible-metric-explanation
+ (lib-be/application-database-metadata-provider (mt/id))
+ {metric-id {:kind :table, :table-id (mt/id :products), :bare-table-only? false}}))]
+ (is (not (str/includes? msg "Secret metric"))
+ "the name of a metric this user cannot read must not come back")
+ (is (str/includes? msg (str metric-id))
+ "it falls back to the numeric ID, which the caller already had"))))))
+
+(deftest incompatible-metric-message-does-not-disclose-unqueryable-base-table-test
+ (testing "The error names a required table only when the user may query it"
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:name "Products metric"
+ :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)
+ :aggregation [[:count]]}}}]
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ required {metric-id {:kind :table, :table-id (mt/id :products), :bare-table-only? true}}]
+ (testing "queryable: the portable FK to paste"
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [{:keys [message usable-sources]} (#'construct/incompatible-metric-explanation mp required)]
+ (is (str/includes? message
+ (str "\"Products metric\" (needs source-table: "
+ (json/encode (products-source-table-fk)) ")")))
+ (is (= {metric-id {:source-table (mt/id :products)}} usable-sources)))))
+ (testing "not queryable: no table name"
+ ;; Use a fresh permission cache after changing permissions.
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [{msg :message, :keys [usable-sources]} (#'construct/incompatible-metric-explanation mp required)]
+ (is (str/includes? msg "\"Products metric\" (defined on a source you do not have access to)"))
+ (is (not (str/includes? msg "PRODUCTS")))
+ (is (empty? usable-sources))))))))))
+
+(defn- table-query
+ "A Lib query on the test-data table `table-key`."
+ [table-key]
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id table-key)))))
+
+(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)))))
+
+(defn- field-col
+ [table-key field-key]
+ (lib.metadata/field (mt/metadata-provider) (mt/id table-key field-key)))
+
+(deftest metric-on-a-model-over-the-model-base-table-test
+ (testing "a metric defined on a model and aggregated over the model's base table"
+ (mt/with-temp [:model/Card {model-id :id, model-eid :entity_id} {:name "Orders model"
+ :type :model
+ :dataset_query (table-query :orders)}
+ :model/Card {metric-id :id, metric-eid :entity_id} {:name "Order count"
+ :type :metric
+ :dataset_query (card-count-query model-id)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "fails in the query processor"
+ (let [mp (mt/metadata-provider)]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Incompatible metric"
+ (qp/process-query (lib/aggregate (table-query :orders)
+ (lib.metadata/metric mp metric-id)))))))
+ (testing "so the tool refuses it with an error the model can act on"
+ (is (=? {:class :recoverable
+ :code :metabase.metabot.tools.recoverable.pipeline/incompatible-metric
+ :text (str "These metrics cannot be used on this stage's source: \"Order count\" (needs "
+ "source-card: \"" model-eid "\"). "
+ "Either change the stage's "
+ "source-table:/source-card: to the one shown for each metric, or drop the metric "
+ "and express the aggregation directly.")}
+ (test-util/tool-failure construct/construct-notebook-query-tool
+ {:query (metric-query-data {"source-table" (orders-source-table-fk)}
+ metric-eid)}))))
+ (testing "and the query built on the model, as the error says, runs"
+ (let [query (-> (construct/execute-representations-query
+ (metric-query-data {"source-card" model-eid} metric-eid))
+ (get-in [:structured-output :query]))]
+ (is (= [[18760]] (mt/rows (qp/process-query query))))))))))
+
+(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}
+ {:name "Blank metric"
+ :type :metric
+ :dataset_query (lib/aggregate (table-query :products) (lib/count))}]
+ ;; Straight to the table: the model's `:in` transform would not store a blank query.
+ (t2/update! (t2/table-name :model/Card) metric-id {:dataset_query "{}"})
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ query (assoc-in (lib/query mp (lib.metadata/table mp (mt/id :products)))
+ [:stages 0 :aggregation]
+ [[:metric {:lib/uuid (str (random-uuid))} metric-id]])]
+ (testing "precondition: the definition really is unreadable, though a table is still recorded"
+ (is (nil? (metabot.tools.util/metric-required-source (lib.metadata/card mp metric-id))))
+ (is (= (mt/id :products) (:table-id (lib.metadata/card mp metric-id)))))
+ (testing "it is reported even on the table it records"
+ (is (= {metric-id nil} (#'construct/incompatible-metrics mp query))))
+ (testing "and the explanation names no source"
+ (is (= (str "These metrics cannot be used on this stage's source: \"Blank metric\" (has no usable source). "
+ "Either change the stage's source-table:/source-card: to the one shown for each metric, "
+ "or drop the metric and express the aggregation directly.")
+ (:message (#'construct/incompatible-metric-explanation mp {metric-id nil}))))))))))
+
+(deftest card-based-metric-pinned-to-its-own-card-test
+ (testing "A card metric rejects a different card over the same table"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {other-eid :entity_id}
+ {:name "Another products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-eid :entity_id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [e (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"Card-based metric"
+ (construct/execute-representations-query
+ (metric-query-data {"source-card" other-eid} metric-eid))))]
+ (is (=? {:agent-error? true, :error :incompatible-metric} (ex-data e))))))))
+
+(deftest fk-dimension-breakout-on-source-card-stage-test
+ (testing "A card metric can group by a dimension reached through a foreign key returned by the card"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders question" :type :question
+ :dataset_query (table-query :orders)}
+ :model/Card {metric-eid :entity_id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query (card-count-query question-id)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ breakout (fn [source fk]
+ (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [(merge source
+ {"lib/type" "mbql.stage/mbql"
+ "breakout" [["field" {} fk]]
+ "aggregation" [["metric" {} metric-eid]]})]}))
+ (get-in [:structured-output :query])))]
+ (testing "an FK-reachable dimension is wired to the FK column on the card's own base table"
+ (let [query (breakout {"source-card" question-eid}
+ [db-name "PUBLIC" "PRODUCTS" "CATEGORY"])]
+ (is (=? {:source-field (mt/id :orders :product_id)}
+ (get-in query [:stages 0 :breakout 0 1])))
+ (testing "the constructed query runs"
+ (is (= [["Doohickey" 3976] ["Gadget" 4939]]
+ (take 2 (mt/rows (qp/process-query query))))))))
+ (testing "a column returned by the card needs no implicit join"
+ (let [query (breakout {"source-card" question-eid}
+ [db-name "PUBLIC" "ORDERS" "QUANTITY"])]
+ (is (not (contains? (get-in query [:stages 0 :breakout 0 1]) :source-field)))
+ (is (= [[0 67] [1 3443]]
+ (take 2 (mt/rows (qp/process-query query))))))))))))
+
+(deftest table-based-metric-breakout-on-a-related-table-column-test
+ (testing "a table-based metric broken out by a column one foreign key away runs on the metric's table"
+ (mt/with-temp [:model/Card {metric-eid :entity_id} {:name "Order count"
+ :type :metric
+ :dataset_query (lib/aggregate (table-query :orders) (lib/count))}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" [db-name "PUBLIC" "ORDERS"]
+ "breakout" [["field" {} [db-name "PUBLIC" "PRODUCTS" "CATEGORY"]]]
+ "aggregation" [["metric" {} metric-eid]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (=? {:source-field (mt/id :orders :product_id)}
+ (get-in query [:stages 0 :breakout 0 1])))
+ (is (= [["Doohickey" 3976] ["Gadget" 4939] ["Gizmo" 4784] ["Widget" 5061]]
+ (mt/rows (qp/process-query query)))))))))
+
+(deftest card-computed-dimension-by-machine-name-executes-on-source-card-stage-test
+ (testing "A computed dimension can be referenced by its output name on the metric source card"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders with double total" :type :question
+ :dataset_query (lib/expression (table-query :orders) "double_total" (lib/* (field-col :orders :total) 2))}
+ :model/Card {metric-id :id, metric-eid :entity_id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query (card-count-query question-id)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [dims (:queryable-dimensions (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false})))
+ dim (m/find-first #(= "double_total" (:name %)) dims)]
+ (testing "precondition: the dimension is offered by machine name, with no portable FK"
+ (is (=? {:field_id "double_total"} dim))
+ (is (nil? (:portable_fk dim))))
+ (let [query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "filters" [[">" {} ["field" {} (:field_id dim)] 100]]
+ "aggregation" [["metric" {} metric-eid]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (= (mt/rows (qp/process-query (-> (table-query :orders)
+ (lib/filter (lib/> (field-col :orders :total) 50))
+ (lib/aggregate (lib/count)))))
+ (mt/rows (qp/process-query query)))
+ "it filters on the card's computed column: count of orders with total > 50")))))))
+
+(deftest source-card-stage-rejects-unreachable-dimensions-like-source-table-test
+ (testing "A card stage rejects a field on an unreachable table"
+ (mt/with-temp [:model/Card {question-eid :entity_id}
+ {:name "Reviews question" :type :question
+ :dataset_query (table-query :reviews)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ ;; PEOPLE is not reachable from REVIEWS by any foreign key.
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ breakout [["field" {} [db-name "PUBLIC" "PEOPLE" "SOURCE"]]]
+ run (fn [source]
+ (try
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [(merge source
+ {"lib/type" "mbql.stage/mbql"
+ "breakout" breakout
+ "aggregation" [["count" {}]]})]}))
+ :no-throw
+ (catch clojure.lang.ExceptionInfo e
+ (:error (ex-data e)))))]
+ (testing "the source-card stage errors, giving the LLM something it can act on"
+ (is (= :no-fk-path (run {"source-card" question-eid}))))
+ (testing "exactly as the same reference on a source-table stage does"
+ (is (= :no-fk-path (run {"source-table" [db-name "PUBLIC" "REVIEWS"]})))))))))
+
+(deftest aggregating-source-card-implicit-join-executes-test
+ (testing "An aggregating card can join through a foreign key returned as a breakout"
+ (mt/with-temp [:model/Card {question-eid :entity_id}
+ {:name "Orders count by user" :type :question
+ :dataset_query (-> (table-query :orders)
+ (lib/aggregate (lib/count))
+ (lib/breakout (field-col :orders :user_id)))}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} [db-name "PUBLIC" "PEOPLE" "SOURCE"]]]
+ "aggregation" [["count" {}]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (= (mt/id :orders :user_id)
+ (:source-field (get-in query [:stages 0 :breakout 0 1])))
+ "wired to the FK column the card actually returns")
+ (is (= [["Affiliate" 341] ["Facebook" 354] ["Google" 361] ["Organic" 341] ["Twitter" 349]]
+ (mt/formatted-rows [str int] (qp/process-query query)))
+ "the constructed query counts the card's users per source"))))))
+
+(deftest aggregating-source-card-rejects-fk-it-does-not-return-test
+ (testing "An omitted foreign key cannot be used for an implicit join"
+ (mt/with-temp [:model/Card {question-eid :entity_id}
+ {:name "Orders count by user" :type :question
+ :dataset_query (-> (table-query :orders)
+ (lib/aggregate (lib/count))
+ (lib/breakout (field-col :orders :user_id)))}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ e (is (thrown? clojure.lang.ExceptionInfo
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} [db-name "PUBLIC" "PRODUCTS" "CATEGORY"]]]
+ "aggregation" [["count" {}]]}]}))))]
+ (is (=? {:agent-error? true, :error :no-fk-path} (ex-data e)))
+ (is (str/includes? (ex-message e) "Orders count by user")
+ "and it names the card, not a base table the LLM never mentioned"))))))
+
+(deftest model-with-restricted-fields-names-the-model-test
+ (mt/with-temp [:model/Card {model-eid :entity_id}
+ {:name "Orders id and total" :type :model
+ :dataset_query (lib/with-fields (table-query :orders) [(field-col :orders :id) (field-col :orders :total)])}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ e (is (thrown? clojure.lang.ExceptionInfo
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" model-eid
+ "breakout" [["field" {} [db-name "PUBLIC" "ORDERS" "QUANTITY"]]]
+ "aggregation" [["count" {}]]}]}))))]
+ (is (=? {:error :column-not-returned, :source-card-type "model"} (ex-data e)))
+ (is (str/includes? (ex-message e) "The model \"Orders id and total\" reads from that table"))
+ (is (not (str/includes? (ex-message e) "saved question")))
+ (is (not (str/includes? (ex-message e) "source-table"))
+ "a stage built on the model's table instead would lose the model's own filters and joins")))))
+
+(deftest source-card-with-restricted-fields-rejects-column-it-does-not-return-test
+ (testing "A card stage rejects an omitted column from a table the card reads"
+ (mt/with-temp [:model/Card {question-eid :entity_id}
+ {:name "Orders id and total" :type :question
+ :dataset_query (lib/with-fields (table-query :orders) [(field-col :orders :id) (field-col :orders :total)])}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ query (fn [fk]
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} fk]]
+ "aggregation" [["count" {}]]}]}))
+ run! #(construct/execute-representations-query (query %))]
+ (testing (str "an omitted column from a table the card reads is rejected: "
+ "pick a projected column. The generic no-FK-path text would tell the agent to add a "
+ "`joins:` entry joining ORDERS to itself, and `:agent-error?` relays it verbatim.")
+ (let [e (is (thrown? clojure.lang.ExceptionInfo
+ (run! [db-name "PUBLIC" "ORDERS" "QUANTITY"])))]
+ (is (=? {:agent-error? true, :error :column-not-returned} (ex-data e)))
+ (is (str/includes? (ex-message e) "does not return"))
+ (is (not (str/includes? (ex-message e) "source-table")))
+ (is (not (str/includes? (ex-message e) "read_resource"))
+ "the shared pipeline's message stays surface-neutral; the lookup advice is each surface's own")
+ (testing "and the URI that Metabot's recovery step and the Agent API's hint send the agent to resolves"
+ (doseq [advice [(:text (test-util/tool-failure construct/construct-notebook-query-tool
+ {:query (query [db-name "PUBLIC" "ORDERS" "QUANTITY"])}
+ #{"read_resource"}))
+ (v1-hints/recovery-hint (ex-data e))]
+ :let [uri (second (re-find #"`(metabase://[^`]+)`" advice))]]
+ (is (str/starts-with? uri "metabase://question/"))
+ (is (str/includes? (:output (test-util/call-tool resources/read-resource-tool {:uris [uri]}))
+ "TOTAL")
+ (str "the agent is sent to " uri))))
+ (is (not (str/includes? (ex-message e) "joins:"))
+ "specifically not told to build a self-join")))
+ (testing "while a genuinely unreachable table still gets the no-FK-path advice"
+ (let [e (is (thrown? clojure.lang.ExceptionInfo
+ (run! [db-name "PUBLIC" "PRODUCTS" "CATEGORY"])))]
+ (is (=? {:agent-error? true, :error :no-fk-path} (ex-data e)))
+ (is (str/includes? (ex-message e) "joins:"))))
+ (testing "while a column it does return is left alone and runs"
+ (let [query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} [db-name "PUBLIC" "ORDERS" "TOTAL"]]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (not (contains? (get-in query [:stages 0 :breakout 0 1]) :source-field)))
+ (is (= 4958 (count (mt/rows (qp/process-query query))))
+ "one row per distinct TOTAL the card returns"))))))))
+
+(deftest native-source-card-stage-leaves-clauses-alone-test
+ (testing "A native source card is left unchanged when its fields cannot be inspected"
+ (mt/with-temp [:model/Card {question-eid :entity_id}
+ {:name "Native orders" :type :question
+ :dataset_query (mt/native-query {:query "SELECT ID, PRODUCT_ID FROM ORDERS"})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} [db-name "PUBLIC" "PRODUCTS" "CATEGORY"]]]
+ "aggregation" [["count" {}]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (not (contains? (get-in query [:stages 0 :breakout 0 1]) :source-field))
+ "no implicit join is guessed for a source we could not inspect"))))))
+
+(deftest source-card-stage-keeps-columns-the-card-already-returns-test
+ (testing "A column returned through the source card's own join keeps that join"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders joined to Products on quantity" :type :question
+ :dataset_query (lib/join (table-query :orders)
+ (-> (lib/join-clause (lib.metadata/table (mt/metadata-provider)
+ (mt/id :products))
+ [(lib/= (field-col :orders :quantity)
+ (field-col :products :id))])
+ (lib/with-join-alias "P")
+ (lib/with-join-fields :all)))}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ category-fk [db-name "PUBLIC" "PRODUCTS" "CATEGORY"]]
+ (testing "precondition: the card's own CATEGORY column is offered under exactly this portable FK"
+ (is (=? {:name "P__CATEGORY", :portable_fk category-fk}
+ (->> (:fields (:structured-output (entity-details/get-table-details
+ {:entity-type :question
+ :entity-id question-id
+ :with-field-values? false})))
+ (m/find-first #(= "P__CATEGORY" (:name %)))))))
+ (let [query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" question-eid
+ "breakout" [["field" {} category-fk]]
+ "aggregation" [["count" {}]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (not (contains? (get-in query [:stages 0 :breakout 0 1]) :source-field))
+ "the clause is left alone")
+ (testing "so it answers from the card's join, not the base table's foreign key"
+ (is (= [[nil 67] ["Doohickey" 12682] ["Gadget" 2270] ["Gizmo" 3532] ["Widget" 209]]
+ (mt/rows (qp/process-query query)))))))))))
+
+(deftest source-card-stage-keeps-fields-its-explicit-joins-return-test
+ (testing "a field returned by an explicit join keeps that join when its reference omits the join alias"
+ (mt/with-temp [:model/Card {products-eid :entity_id} {:name "Products"
+ :type :question
+ :dataset_query (table-query :products)}]
+ (doseq [card-type [:question :model]]
+ (mt/with-temp [:model/Card {orders-eid :entity_id} {:name "Orders"
+ :type card-type
+ :dataset_query (table-query :orders)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ ;; The join condition is not the foreign key, so the explicit join and an implicit one disagree.
+ join (fn [join-source]
+ {"alias" "P"
+ "strategy" "left-join"
+ "stages" [(assoc join-source "lib/type" "mbql.stage/mbql")]
+ "conditions" [["=" {}
+ ["field" {} [db-name "PUBLIC" "ORDERS" "QUANTITY"]]
+ ["field" {"join-alias" "P"} [db-name "PUBLIC" "PRODUCTS" "ID"]]]]})]
+ (doseq [[join-label join-source] [["a saved question" {"source-card" products-eid}]
+ ["a table" {"source-table" [db-name "PUBLIC" "PRODUCTS"]}]]]
+ (testing (str "a " (name card-type) " joined to " join-label)
+ (let [query (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" orders-eid
+ "joins" [(join join-source)]
+ "breakout" [["field" {} [db-name "PUBLIC" "PRODUCTS" "CATEGORY"]]]
+ "aggregation" [["count" {}]]}]}))
+ (get-in [:structured-output :query]))]
+ (is (not (contains? (get-in query [:stages 0 :breakout 0 1]) :source-field)))
+ (is (= [[nil 67] ["Doohickey" 12682] ["Gadget" 2270] ["Gizmo" 3532] ["Widget" 209]]
+ (mt/rows (qp/process-query query))))))))))))))
+
+(deftest source-card-stage-with-explicit-joins-gets-no-implicit-join-repair-test
+ (testing "a `source-card:` stage with an explicit join is left as written, and lib resolves its fields"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [native (mt/native-query {:query "SELECT ID, CATEGORY FROM PRODUCTS"})]
+ (mt/with-temp [:model/Card {native-eid :entity_id} {:name "Native products"
+ :type :question
+ :dataset_query native
+ :result_metadata (get-in (qp/process-query native)
+ [:data :cols])}
+ :model/Card {products-eid :entity_id} {:name "Products"
+ :type :question
+ :dataset_query (table-query :products)}]
+ (doseq [card-type [:question :model]]
+ (mt/with-temp [:model/Card {orders-eid :entity_id} {:name "Orders"
+ :type card-type
+ :dataset_query (table-query :orders)}
+ :model/Card {people-eid :entity_id} {:name "People"
+ :type card-type
+ :dataset_query (table-query :people)}]
+ (let [db-name (t2/select-one-fn :name :model/Database :id (mt/id))
+ column (fn [table column-name] [db-name "PUBLIC" table column-name])
+ build (fn [source-eid source-column join-stage]
+ (let [join {"alias" "P"
+ "strategy" "left-join"
+ "stages" [(assoc join-stage "lib/type" "mbql.stage/mbql")]
+ "conditions" [["=" {}
+ ["field" {} source-column]
+ ["field" {"join-alias" "P"} (column "PRODUCTS" "ID")]]]}]
+ (-> (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-card" source-eid
+ "joins" [join]
+ "breakout" [["field" {} (column "PRODUCTS" "CATEGORY")]]
+ "aggregation" [["count" {}]]}]}))
+ (get-in [:structured-output :query]))))
+ source-field? #(contains? (get-in % [:stages 0 :breakout 0 1]) :source-field)]
+ (testing (str "orders as a " (name card-type) ", joined to a native question")
+ (let [query (build orders-eid (column "ORDERS" "QUANTITY") {"source-card" native-eid})]
+ (is (not (source-field? query)))
+ (is (= [[nil 67] ["Doohickey" 12682] ["Gadget" 2270] ["Gizmo" 3532] ["Widget" 209]]
+ (mt/rows (qp/process-query query))))))
+ (testing (str "people as a " (name card-type) ", joined to a native question")
+ (let [query (build people-eid (column "PEOPLE" "ID") {"source-card" native-eid})]
+ (is (not (source-field? query)))
+ (is (= [[nil 2300] ["Doohickey" 42] ["Gadget" 53] ["Gizmo" 51] ["Widget" 54]]
+ (mt/rows (qp/process-query query))))))
+ (doseq [[join-label join-source] [["question" {"source-card" products-eid}]
+ ["table" {"source-table" [db-name "PUBLIC" "PRODUCTS"]}]]]
+ (testing (str "orders as a " (name card-type) ", joined to a grouped " join-label)
+ (is (not (source-field? (build orders-eid
+ (column "ORDERS" "QUANTITY")
+ (assoc join-source
+ "breakout" [["field" {} (column "PRODUCTS" "ID")]]
+ "aggregation" [["count" {}]])))))))))))))))
+
+(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}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [provider (lib-be/application-database-metadata-provider (mt/id))
+ on-products (lib/query provider (lib.metadata/table provider (mt/id :products)))
+ metric-agg [[:metric {:lib/uuid (str (random-uuid))} metric-id]]
+ first-stage (assoc-in on-products [:stages 0 :aggregation] metric-agg)
+ second-stage (-> on-products
+ lib/append-stage
+ (assoc-in [:stages 1 :aggregation] metric-agg))]
+ (testing "precondition: this metric really is incompatible with a products source"
+ (is (= [metric-id] (keys (#'construct/incompatible-metrics provider first-stage)))))
+ (testing "the same reference one stage later is not reported"
+ (is (nil? (#'construct/incompatible-metrics provider second-stage)))))))))
+
;;; ============================================================
;;; BOT-2222: refs to a grouped join's columns
;;; ============================================================
diff --git a/test/metabase/metabot/tools/core_test.clj b/test/metabase/metabot/tools/core_test.clj
index 5cd4547889f..1a84826d4b9 100644
--- a/test/metabase/metabot/tools/core_test.clj
+++ b/test/metabase/metabot/tools/core_test.clj
@@ -351,7 +351,24 @@
:data {:entity-type "metric" :entity-id 7}}
error))
(is (str/starts-with? (:text (first (:recovery error)))
- "Metrics are aggregations, not sources.")))))
+ "Metrics are aggregations, not sources."))))
+ (testing "an error from a `source-card:` stage carries the card, so the recovery step reads that card's columns"
+ (doseq [[error what] [[:column-not-returned "columns"]
+ [:unexportable-fk "columns"]
+ [:ambiguous-fk "foreign-key columns"]]]
+ (testing error
+ (is (=? {:data {:source-card 12 :source-card-type "model"}
+ :recovery [{:uses #{"read_resource"}
+ :text (str "Call `read_resource` with `metabase://model/12/fields` to list the " what
+ " this model returns.")}]}
+ (pipeline-failure "The field cannot be referenced here."
+ {:agent-error? true :error error :source-card 12 :source-card-type "model"}))))))
+ (testing "an ambiguous foreign key on a `source-table:` stage still points at the table's fields"
+ (is (=? {:recovery [{:uses #{"read_resource"}
+ :text (str "Call `read_resource` with `metabase://table/<numeric id>/fields` for the source "
+ "table to list the available foreign-key columns.")}]}
+ (pipeline-failure "Two foreign keys reach the table."
+ {:agent-error? true :error :ambiguous-fk :source-table 3})))))
(deftest ^:parallel with-pipeline-errors-converts-refusals-test
(doseq [status [403 404]]
diff --git a/test/metabase/metabot/tools/entity_details_test.clj b/test/metabase/metabot/tools/entity_details_test.clj
index 9999f943ada..a0d3641e4de 100644
--- a/test/metabase/metabot/tools/entity_details_test.clj
+++ b/test/metabase/metabot/tools/entity_details_test.clj
@@ -486,6 +486,306 @@
:queryable-dimensions
:segments]))))))))))
+(deftest get-metric-details-card-based-metric-surfaces-source-card-test
+ (testing "Metric details name the source card required by a single-stage card metric"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders question"
+ :type :question
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Card-based metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (testing "the source card includes the entity ID needed for `source-card:`"
+ (is (=? {:source_card_id question-id
+ :source_card_name "Orders question"
+ :source_card_portable_entity_id question-eid}
+ output)))
+ (testing "the dimensions come from the metric query, so they stay usable on that source"
+ (is (= ["ID" "USER_ID" "PRODUCT_ID" "SUBTOTAL" "TAX" "TOTAL" "DISCOUNT" "CREATED_AT" "QUANTITY"]
+ (->> (:queryable-dimensions output)
+ (remove :table_reference)
+ (mapv :name)))
+ "every column of the card's own table")
+ (is (= #{"User" "Product"}
+ (into #{} (keep :table_reference) (:queryable-dimensions output)))
+ "plus the FK-reachable tables"))
+ (testing "and the base table is not offered as a source"
+ (is (not-any? #(contains? output %)
+ [:base_table_id :base_table_name :base_table_portable_fk]))))))))
+
+(deftest get-metric-details-hides-unreadable-source-card-test
+ (testing "metric details do not reveal a source card the user cannot read"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private"}
+ :model/Card {question-id :id}
+ {:name "Orders question"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Card-based metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ ;; Request dimensions too, since access to the base table does not make the source card readable.
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (is (= metric-id (:id output)) "collection access still makes the metric readable")
+ (is (not-any? #(contains? output %)
+ [:source_card_id :source_card_name :source_card_portable_entity_id]))
+ (testing "the base table is not offered as a substitute for the unreadable card"
+ (is (not-any? #(contains? output %)
+ [:base_table_id :base_table_name :base_table_portable_fk])))
+ (testing "the metric is marked unavailable"
+ (is (true? (:source_unavailable output))))
+ (testing "an unavailable metric has no dimensions"
+ (is (not-any? #(contains? output %)
+ [:queryable-dimensions :default_time_dimension_field_id :segments]))))))))
+
+(deftest get-metric-details-multi-stage-card-based-metric-surfaces-base-table-test
+ (testing "Metric details offer the base table for a multi-stage card metric"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Orders question"
+ :type :question
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Multi-stage card metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (testing "the base table is offered as the source"
+ (is (=? {:base_table_id (mt/id :orders)
+ :base_table_name "ORDERS"}
+ output))
+ (is (vector? (:base_table_portable_fk output))))
+ (testing "the card named by the definition is not offered as a source"
+ (is (not-any? #(contains? output %)
+ [:source_card_id :source_card_name :source_card_portable_entity_id])))
+ (testing "the metric is available on its base table"
+ (is (not (contains? output :source_unavailable))))
+ (testing "and it still describes its dimensions, so the LLM can filter and group on that source"
+ (is (seq (:queryable-dimensions output)))))))))
+
+(deftest get-metric-details-marks-unreadable-base-table-unavailable-test
+ (testing "A table metric with no queryable source is marked unavailable"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:name "Table-based metric"
+ :type :metric
+ :dataset_query (mt/mbql-query orders {:aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (is (= metric-id (:id output)) "collection access still makes the metric readable")
+ (is (not-any? #(contains? output %)
+ [:base_table_id :base_table_name :base_table_portable_fk]))
+ (testing "the source is explicitly marked unavailable"
+ (is (true? (:source_unavailable output))))))))))
+
+(deftest tool-arguments-cannot-carry-a-card-read-verdict-test
+ (testing "Tool arguments cannot supply trusted source-card read permissions"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private"}
+ :model/Card {question-id :id}
+ {:name "Orders question"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Card-based metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false
+ ;; a read verdict, supplied the way a tool call would
+ :known-readable-card-ids #{question-id}
+ :card-read-verdicts {question-id true}}))]
+ (is (not-any? #(contains? output %)
+ [:source_card_id :source_card_name :source_card_portable_entity_id])
+ "the unreadable source card is still withheld")
+ (is (true? (:source_unavailable output))))))))
+
+(deftest get-metric-details-survives-a-deleted-source-card-test
+ (testing "A metric whose source card was deleted is marked unavailable"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Doomed question"
+ :type :question
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Metric on a deleted question"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (t2/delete! :model/Card :id question-id)
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (is (= metric-id (:id output)) "the metric itself still renders")
+ (is (true? (:source_unavailable output))
+ "the missing source is marked unavailable")
+ (is (not-any? #(contains? output %)
+ [:source_card_id :source_card_name :source_card_portable_entity_id
+ :base_table_id :base_table_name :base_table_portable_fk])))))))
+
+(deftest get-metric-details-marks-unreadable-definition-unavailable-test
+ (testing "A metric with a blank definition is marked unavailable"
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:name "Blank metric"
+ :type :metric
+ :dataset_query (mt/mbql-query orders {:aggregation [[:count]]})}]
+ ;; Straight to the table: the model's `:in` transform would not store a blank query.
+ (t2/update! (t2/table-name :model/Card) metric-id {:dataset_query "{}"})
+ (is (= (mt/id :orders) (t2/select-one-fn :table_id :model/Card :id metric-id))
+ "the base table is still recorded, so it is there to be wrongly offered")
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false}))]
+ (is (=? {:id metric-id, :source_unavailable true} output))
+ (is (not-any? #(contains? output %)
+ [:source_card_id :source_card_name :source_card_portable_entity_id
+ :base_table_id :base_table_name :base_table_portable_fk])))))))
+
+(deftest cards-details-metric-branch-reports-each-source-kind-test
+ (testing "Bulk card details report the source required by each metric"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders question"
+ :type :question
+ :dataset_query (mt/mbql-query orders)}
+ :model/Card {table-metric-id :id}
+ {:name "Table metric"
+ :type :metric
+ :dataset_query (mt/mbql-query orders {:aggregation [[:count]]})}
+ :model/Card {card-metric-id :id}
+ {:name "Card metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}
+ :model/Card {multi-metric-id :id}
+ {:name "Multi-stage card metric"
+ :type :metric
+ :dataset_query (mt/mbql-query nil {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [cards (t2/select :model/Card :id [:in [table-metric-id card-metric-id multi-metric-id]])
+ by-id (into {} (map (juxt :id identity))
+ (entity-details/cards-details :metric (mt/id) cards {:with-field-values? false}))]
+ (testing "table-based: its own base table"
+ (is (=? {:base_table_id (mt/id :orders)} (get by-id table-metric-id)))
+ (is (not (contains? (get by-id table-metric-id) :source_card_id))))
+ (testing "single-stage card-based: the card it sits on"
+ (is (=? {:source_card_id question-id
+ :source_card_portable_entity_id question-eid}
+ (get by-id card-metric-id)))
+ (is (not (contains? (get by-id card-metric-id) :base_table_id))))
+ (testing "multi-stage card-based: the base table, not the card it names"
+ (is (=? {:base_table_id (mt/id :orders)} (get by-id multi-metric-id)))
+ (is (not (contains? (get by-id multi-metric-id) :source_card_id)))))))))
+
+(deftest metric-details-carries-default-time-dimension-name-without-dimensions-test
+ (testing "The default temporal breakout includes its ID and name without requesting dimensions"
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:name "Orders over time"
+ :type :metric
+ :dataset_query (mt/mbql-query orders {:aggregation [[:count]]
+ :breakout [!month.created_at]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false
+ :with-queryable-dimensions? false}))]
+ (is (=? {:default_time_dimension_field_id (mt/id :orders :created_at)
+ :default_time_dimension_field_name "CREATED_AT"}
+ output)
+ "the name is available without requesting dimensions")
+ (is (not (contains? output :queryable-dimensions))))))))
+
+(deftest card-details-lists-card-based-metrics-test
+ (testing "Card details accept lib metadata cards when listing available metrics"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Orders question" :type :question :dataset_query (mt/mbql-query orders)}
+ :model/Card {metric-id :id}
+ {:name "Card-based metric" :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [details (first (entity-details/cards-details
+ :question (mt/id)
+ [(t2/select-one :model/Card :id question-id)]
+ {:with-metrics? true
+ :with-queryable-dimensions? false
+ :with-field-values? false
+ :field-values-fn identity}))
+ metric (first (:metrics details))]
+ (is (= [metric-id] (mapv :id (:metrics details)))
+ "the card metric is listed")
+ (testing "and it points back at the card being described, not its underlying table"
+ (is (= question-id (:source_card_id metric)))
+ (is (= question-eid (:source_card_portable_entity_id metric)))
+ (is (not-any? #(contains? metric %)
+ [:base_table_id :base_table_name :base_table_portable_fk]))))))))
+
+(deftest metric-details-on-native-source-question-test
+ (testing "A metric on a native question reports the source card and its columns"
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "Native question" :type :question
+ :dataset_query (mt/native-query {:query "SELECT 1 AS n, 'x' AS s"})
+ ;; `with-temp` does not run the native query, so its output columns must be supplied explicitly.
+ :result_metadata [{:name "N" :display_name "N" :base_type :type/Integer}
+ {:name "S" :display_name "S" :base_type :type/Text}]}
+ :model/Card {metric-id :id}
+ {:name "Metric on native question" :type :metric
+ :dataset_query (mt/mbql-query nil {:source-table (str "card__" question-id)
+ :aggregation [[:count]]})}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "the metric has no base table at all"
+ (is (nil? (t2/select-one-fn :table_id :model/Card :id metric-id))))
+ (testing "the single-arg (t2 row) path reports the source card"
+ (is (=? {:source_card_id question-id
+ :source_card_portable_entity_id question-eid}
+ (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-queryable-dimensions? false
+ :with-field-values? false})))))
+ (testing "a metric on a native question describes the columns returned by its source card"
+ (let [dims (:queryable-dimensions
+ (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-field-values? false})))]
+ (is (=? [{:name "N" :field_id "N"}
+ {:name "S" :field_id "S"}]
+ dims))
+ (testing (str "with no portable FK -- a native card's output column has no database field behind it, "
+ "so the machine name in `:field_id` is the only reference")
+ (is (not-any? :portable_fk dims)))))
+ (testing "and so does the lib-metadata-map path through card-details"
+ (let [details (first (entity-details/cards-details
+ :question (mt/id)
+ [(t2/select-one :model/Card :id question-id)]
+ {:with-metrics? true
+ :with-queryable-dimensions? false
+ :with-field-values? false
+ :field-values-fn identity}))]
+ (is (=? [{:id metric-id, :source_card_id question-id}]
+ (:metrics details)))))))))
+
(deftest get-metric-details-hides-unreadable-fk-target-test
(testing "metric dimensions do not reveal metadata for an unreadable FK target table"
(mt/with-temp [:model/Database db {}
diff --git a/test/metabase/metabot/tools/recoverable/pipeline_test.clj b/test/metabase/metabot/tools/recoverable/pipeline_test.clj
index 57daf75c2e2..fbbe28382c4 100644
--- a/test/metabase/metabot/tools/recoverable/pipeline_test.clj
+++ b/test/metabase/metabot/tools/recoverable/pipeline_test.clj
@@ -150,5 +150,11 @@
(testing code
(is (some? (v1-hints/recovery-hint {:error code :entity-type "table" :entity-id 1})))
(is (some? (v2-hints/recovery-hint {:error code :entity-type "table" :entity-id 1})))))
+ (testing "and so do the codes only a `source-card:` stage raises, given the card"
+ (doseq [code [:column-not-returned :unexportable-fk]]
+ (testing code
+ (let [data {:error code :source-card 12 :source-card-type "model"}]
+ (is (some? (v1-hints/recovery-hint data)))
+ (is (some? (v2-hints/recovery-hint data)))))))
(testing "and every one of them is declared here"
(is (= #{} (set/difference (set codes) (declared-codes))))))))
diff --git a/test/metabase/metabot/tools/run_query_test.clj b/test/metabase/metabot/tools/run_query_test.clj
index 5917780840d..a5f7019ef0e 100644
--- a/test/metabase/metabot/tools/run_query_test.clj
+++ b/test/metabase/metabot/tools/run_query_test.clj
@@ -915,6 +915,19 @@
(testing "and offers no way to its values when they can't"
(is (= (metric-refusal on-hidden no-values-step)
(run-viewing! [{:type "metric", :id on-hidden}] (str on-hidden))))))))
+ (testing "a viewed metric that aggregates in a stage after the model it starts from names the base table"
+ (let [mp (mt/metadata-provider)]
+ (mt/with-temp [:model/Card {model :id} {:dataset_query (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ :type :model}
+ :model/Card {metric :id} {:dataset_query (-> (lib/query mp (lib.metadata/card mp model))
+ lib/append-stage
+ (lib/aggregate (lib/count)))
+ :type :metric}]
+ (is (= (metric-refusal metric
+ (str "To get its values, use `construct_notebook_query` to build a notebook query "
+ "with the metric's base table as its source. Put the metric in `aggregation`, "
+ "then run the query with `run_query`."))
+ (run-viewing! [{:type "metric", :id metric}] (str metric)))))))
(testing "a viewed metric the user can't read is refused like an id that names nothing"
(mt/with-non-admin-groups-no-root-collection-perms
(mt/with-temp [:model/Collection {hidden :id} {}
diff --git a/test/metabase/metabot/tools/search_test.clj b/test/metabase/metabot/tools/search_test.clj
index 81ab35ed89d..8dce91e5aca 100644
--- a/test/metabase/metabot/tools/search_test.clj
+++ b/test/metabase/metabot/tools/search_test.clj
@@ -802,7 +802,14 @@
(mt/with-test-user :rasta
(is (empty? (search/entity-refs->search-results refs))))))))))
-(deftest enrich-with-metric-base-tables-test
+(def ^:private metric-source-keys
+ "Every key [[metabase.metabot.tools.util/metric-source-fields]] can set, so `select-keys` over it asserts presence and
+ absence in one comparison."
+ [:base_table_id :base_table_name :base_table_schema :base_table_portable_fk
+ :source_card_id :source_card_name :source_card_portable_entity_id
+ :source_unavailable])
+
+(deftest enrich-with-metric-sources-base-table-test
(testing (str "Metric search results carry `base_table_*` fields so the LLM can write\n"
"`source-table:` without a separate read_resource call. We look up\n"
"`report_card.table_id` → `metabase_table.{schema,name}` and assemble the\n"
@@ -834,7 +841,7 @@
(is (= [db-name (:schema orders-t) (:name orders-t)]
(:base_table_portable_fk metric-res))))))))))
-(deftest enrich-with-metric-base-tables-respects-table-permissions-test
+(deftest enrich-with-metric-sources-respects-table-permissions-test
(testing "a readable metric does not reveal metadata for an unreadable base table"
(mt/with-no-data-perms-for-all-users!
(mt/with-test-user :rasta
@@ -961,6 +968,67 @@
(is (not (contains? models "transform")))
(is (contains? models "dashboard")
"sanity: the other requested type is unaffected, so this isn't an empty-set pass")))))))))
+
+(deftest enrich-with-metric-source-cards-test
+ (testing "Search offers the source card required by a single-stage card metric"
+ (mt/with-test-user :crowberto
+ (search.tu/with-temp-index-table
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "SourceCard Sample Question"
+ :type :question
+ :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :orders)}}}
+ :model/Card {metric-id :id}
+ {:name "SourceCard Sample Metric"
+ :type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (let [results (search/search {:term-queries ["SourceCard Sample Metric"]})
+ metric-res (some #(when (= [metric-id "metric"] [(:id %) (:type %)]) %) results)]
+ (is (= {:source_card_id question-id
+ :source_card_name "SourceCard Sample Question"
+ :source_card_portable_entity_id question-eid}
+ (select-keys metric-res metric-source-keys))
+ "the source card includes its entity ID and the base table is not offered")))))))
+
+(deftest enrich-with-metric-source-cards-respects-card-permissions-test
+ (testing "Search does not reveal an unreadable source card or offer its base table"
+ (mt/with-test-user :rasta
+ (search.tu/with-temp-index-table
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Private SourceCard Collection"}
+ :model/Card {question-id :id}
+ {:name "Restricted SourceCard Question"
+ :type :question
+ :collection_id coll-id
+ :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :orders)}}}
+ :model/Card {metric-id :id}
+ {:name "Restricted SourceCard Metric"
+ :type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (let [results (search/search {:term-queries ["Restricted SourceCard Metric"]})
+ metric-res (some #(when (= [metric-id "metric"] [(:id %) (:type %)]) %) results)]
+ (is (some? metric-res) "collection access still makes the metric searchable")
+ (is (= {:source_unavailable true}
+ (select-keys metric-res metric-source-keys))
+ "the source is marked unavailable, as it is in metric details")))))))
+
(deftest remove-unreadable-transforms-test
(testing "remove-unreadable-transforms correctly filters transforms based on source database access"
(mt/with-premium-features #{:transforms-basic}
@@ -1012,3 +1080,68 @@
(let [[result] (search/entity-refs->search-results [{:model "metric" :id card-id}])]
(is (= "model" (:type result)))
(is (string? (:type result))))))))
+
+(deftest enrich-with-metric-sources-mixed-results-test
+ (testing "Search reports the source required by each metric in a mixed result set"
+ (mt/with-test-user :crowberto
+ (search.tu/with-temp-index-table
+ (mt/with-temp [:model/Card {question-id :id, question-eid :entity_id}
+ {:name "MixedSources Question" :type :question :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id) :type :query
+ :query {:source-table (mt/id :orders)}}}
+ :model/Card {card-metric-id :id}
+ {:name "MixedSources CardMetric" :type :metric :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id) :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}
+ :model/Card {table-metric-id :id}
+ {:name "MixedSources TableMetric" :type :metric :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id) :type :query
+ :query {:source-table (mt/id :orders)
+ :aggregation [[:count]]}}}
+ :model/Card {multi-metric-id :id}
+ {:name "MixedSources MultiStageCardMetric" :type :metric :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id) :type :query
+ :query {:source-query {:source-table (str "card__" question-id)}
+ :aggregation [[:count]]}}}]
+ (let [results (search/search {:term-queries ["MixedSources"]})
+ by-id (into {} (map (juxt :id identity)) results)
+ card-m (get by-id card-metric-id)
+ table-m (get by-id table-metric-id)
+ multi-m (get by-id multi-metric-id)
+ orders-fields {:base_table_id (mt/id :orders)
+ :base_table_name "ORDERS"
+ :base_table_schema "PUBLIC"
+ :base_table_portable_fk [(:database_name table-m) "PUBLIC" "ORDERS"]}]
+ (is (= {:card {:source_card_id question-id
+ :source_card_name "MixedSources Question"
+ :source_card_portable_entity_id question-eid}
+ :table orders-fields
+ ;; Its definition names a card in stage 0, but its last stage does not, so the QP only
+ ;; accepts the base table.
+ :multi orders-fields}
+ (update-vals {:card card-m, :table table-m, :multi multi-m}
+ #(select-keys % metric-source-keys)))
+ "each metric carries only its own source's fields")))))))
+
+(deftest enrich-with-metric-sources-marks-unreadable-base-table-unavailable-test
+ (testing "A table metric with no queryable source is marked unavailable in search"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (search.tu/with-temp-index-table
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:name "Unreadable Base Table Metric" :type :metric :database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query {:database (mt/id) :type :query
+ :query {:source-table (mt/id :orders)
+ :aggregation [[:count]]}}}]
+ (let [results (search/search {:term-queries ["Unreadable Base Table Metric"]})
+ metric (first (filter #(= metric-id (:id %)) results))]
+ (is (some? metric) "the metric is still readable via its collection")
+ (is (= {:source_unavailable true}
+ (select-keys metric metric-source-keys))
+ "the source is explicitly marked unavailable"))))))))
diff --git a/test/metabase/metabot/tools/shared/llm_shape_test.clj b/test/metabase/metabot/tools/shared/llm_shape_test.clj
index 194fc679a2c..4606e7a226d 100644
--- a/test/metabase/metabot/tools/shared/llm_shape_test.clj
+++ b/test/metabase/metabot/tools/shared/llm_shape_test.clj
@@ -96,7 +96,7 @@
:description "Sum of all revenue"
:verified true
:collection {:name "Finance"}
- :default_time_dimension_field {:name "created_at"}
+ :default_time_dimension_field_name "date"
:queryable-dimensions [{:name "date" :field_id "d1" :base-type :type/Date :database_type "DATE"}]}
xml (llm-shape/metric->xml metric)]
(is (str/starts-with? xml "<metric"))
@@ -109,7 +109,7 @@
(is (str/includes? xml "The following dimensions can be used for filter- or group-by operations"))
(is (str/includes? xml "metabase://metric/42/dimensions/{field_id}"))
(is (str/includes? xml "The metric is stored in the following collection"))
- (is (str/includes? xml "Default Time Dimension Field: created_at"))
+ (is (str/includes? xml "Default Time Dimension Field: date"))
(is (str/ends-with? (str/trim xml) "</metric>"))))
(testing "handles metric without dimensions"
(let [metric {:id 1 :name "Test" :verified false}
@@ -606,6 +606,50 @@
(is (str/includes? xml "Collection: Finance"))
(is (str/ends-with? (str/trim xml) "</metric>")))))
+(deftest ^:parallel metric->xml-source-test
+ (testing "a metric's source renders as exactly one of base-table / source-card"
+ (testing "table-based"
+ (let [xml (llm-shape/metric->xml {:id 1 :name "Table metric" :database_name "Sample"
+ :base_table_portable_fk ["Sample" "PUBLIC" "ORDERS"]})]
+ (is (str/includes? xml "base_table_fully_qualified_name=\"PUBLIC.ORDERS\""))
+ (is (not (str/includes? xml "source_card_portable_entity_id")))))
+ (testing "the source card includes the ID to copy into `source-card:`"
+ (let [xml (llm-shape/metric->xml {:id 1 :name "Card metric" :database_name "Sample"
+ :source_card_portable_entity_id "T4wA_GPFwGb6R4FxIDGTo"
+ :source_card_name "Orders question"})]
+ (is (str/includes? xml "source_card_portable_entity_id=\"T4wA_GPFwGb6R4FxIDGTo\""))
+ (is (str/includes? xml "source_card_name=\"Orders question\""))
+ (is (not (str/includes? xml "base_table_fully_qualified_name")))))
+ (testing "an unreadable source card is explicitly marked unavailable"
+ (let [xml (llm-shape/metric->xml {:id 1 :name "Walled-off metric" :database_name "Sample"
+ :source_unavailable true})]
+ (is (str/includes? xml "source_unavailable=\"true\""))
+ (is (not (str/includes? xml "base_table_fully_qualified_name")))
+ (is (not (str/includes? xml "source_card_portable_entity_id")))))))
+
+(deftest ^:parallel search-result->xml-metric-source-test
+ (testing "a metric search result's source renders as exactly one of base-table / source-card"
+ (testing "table-based"
+ (let [xml (llm-shape/search-result->xml {:id 100 :type :metric :name "Table metric"
+ :database_name "Sample"
+ :base_table_portable_fk ["Sample" "PUBLIC" "ORDERS"]})]
+ (is (str/includes? xml "base_table_fully_qualified_name=\"PUBLIC.ORDERS\""))
+ (is (not (str/includes? xml "source_card_portable_entity_id")))))
+ (testing "card-based"
+ (let [xml (llm-shape/search-result->xml {:id 100 :type :metric :name "Card metric"
+ :database_name "Sample"
+ :source_card_portable_entity_id "T4wA_GPFwGb6R4FxIDGTo"
+ :source_card_name "Orders question"})]
+ (is (str/includes? xml "source_card_portable_entity_id=\"T4wA_GPFwGb6R4FxIDGTo\""))
+ (is (str/includes? xml "source_card_name=\"Orders question\""))
+ (is (not (str/includes? xml "base_table_fully_qualified_name")))))
+ (testing "an unreadable source card uses the same unavailable marker as metric details"
+ (let [xml (llm-shape/search-result->xml {:id 100 :type :metric :name "Walled-off metric"
+ :database_name "Sample" :source_unavailable true})]
+ (is (str/includes? xml "source_unavailable=\"true\""))
+ (is (not (str/includes? xml "base_table_fully_qualified_name")))
+ (is (not (str/includes? xml "source_card_portable_entity_id")))))))
+
(deftest ^:parallel search-result->xml-test-2
(testing "table search result includes database_id, database_engine, and fully_qualified_name"
(let [result {:id 133
@@ -1044,6 +1088,53 @@
(is (str/includes? xml "```\n</query>"))
(is (str/includes? xml "\"PRODUCTS\"")))))
+(deftest ^:parallel metric->xml-dimension-reference-form-test
+ (testing "Dimensions use portable FKs for database fields and output names for computed columns"
+ (let [dims [{:name "ID" :field_id 5 :type "number"
+ :portable_fk ["Sample" "PUBLIC" "ORDERS" "ID"]}
+ {:name "ID" :field_id 6 :type "number" :table_reference "Product"
+ :portable_fk ["Sample" "PUBLIC" "PRODUCTS" "ID"]}
+ {:name "CATEGORY" :field_id 7 :type "string" :table_reference "Product"
+ :portable_fk ["Sample" "PUBLIC" "PRODUCTS" "CATEGORY"]}
+ ;; Computed columns have no database field, so they use their output names.
+ {:name "PROFIT" :field_id "PROFIT" :type "number"}]
+ table-xml (llm-shape/metric->xml {:id 1 :name "Table metric" :database_name "Sample"
+ :base_table_portable_fk ["Sample" "PUBLIC" "ORDERS"]
+ :queryable-dimensions dims})
+ card-xml (llm-shape/metric->xml {:id 1 :name "Card metric" :database_name "Sample"
+ :source_card_portable_entity_id "T4wA_GPFwGb6R4FxIDGTo"
+ :queryable-dimensions dims})]
+ (doseq [[label xml] [["table-based" table-xml] ["card-based" card-xml]]]
+ (testing label
+ (testing "every FK-backed column references its portable FK, which pins the table it came from"
+ (is (str/includes? xml "[\"Sample\",\"PUBLIC\",\"ORDERS\",\"ID\"]"))
+ (is (str/includes? xml "[\"Sample\",\"PUBLIC\",\"PRODUCTS\",\"ID\"]"))
+ (is (str/includes? xml "[\"Sample\",\"PUBLIC\",\"PRODUCTS\",\"CATEGORY\"]")))
+ (testing "so no FK-backed column is offered as a bare name"
+ (is (not (str/includes? xml "| \"ID\" |")))
+ (is (not (str/includes? xml "| \"CATEGORY\" |"))))
+ (testing "the expression column, which has no portable FK, falls back to its machine name"
+ (is (str/includes? xml "| \"PROFIT\" |")))
+ (testing "the Source table column distinguishes the two `ID` fields"
+ (is (str/includes? xml "Source table"))
+ (is (str/includes? xml "PUBLIC.PRODUCTS (via Product)")))))
+ (testing "the two renderings are identical: the metric's source does not change the reference form"
+ (is (= (re-find #"(?s)\| Field Name \|.*?\n\n" table-xml)
+ (re-find #"(?s)\| Field Name \|.*?\n\n" card-xml)))))))
+
+(deftest ^:parallel metric->xml-dimension-reference-omitted-without-portable-fk-test
+ (testing "A database field without a portable FK is listed without a reference"
+ (let [xml (llm-shape/metric->xml
+ {:id 1 :name "Metric" :database_name "Sample"
+ :base_table_portable_fk ["Sample" "PUBLIC" "ORDERS"]
+ :queryable-dimensions [{:name "ID" :field_id 5 :type "number"}
+ {:name "PROFIT" :field_id "PROFIT" :type "number"}]})]
+ (testing "the real field is listed but left without a reference to copy"
+ (is (str/includes? xml "| ID |") "the dimension is still described")
+ (is (not (str/includes? xml "| \"ID\" |"))))
+ (testing "while the card-computed column still gets its machine name"
+ (is (str/includes? xml "| \"PROFIT\" |"))))))
+
(deftest ^:parallel related-tables-note-does-not-presuppose-sql-test
(testing "table/model XML reaches profiles without SQL tools (read_resource, viewing context), so the related-tables usage note carries no SQL-writing guidance (BOT-1891)"
(let [related [{:id 20 :name "orders" :database_schema "public"
diff --git a/test/metabase/metabot/tools/util_test.clj b/test/metabase/metabot/tools/util_test.clj
index 6509a6af1cc..e4e72305495 100644
--- a/test/metabase/metabot/tools/util_test.clj
+++ b/test/metabase/metabot/tools/util_test.clj
@@ -8,7 +8,8 @@
[metabase.lib.metadata :as lib.metadata]
[metabase.metabot.tools.util :as metabot.tools.util]
[metabase.permissions.models.permissions :as perms]
- [metabase.test :as mt]))
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
(deftest ^:parallel handle-agent-or-api-error-test
(testing "an API check's refusal goes back to the agent as output"
@@ -317,3 +318,100 @@
(catch clojure.lang.ExceptionInfo e
(is (:agent-error? (ex-data e)))
(is (= 404 (:status-code (ex-data e)))))))))
+
+;;; ---------------------------------------- metric sources ----------------------------------------
+
+(deftest ^:parallel metric-required-source-classifies-the-four-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}))
+ {: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} {}])))
+
+(deftest ^:parallel metric-required-source-unreadable-definition-test
+ (testing "A blank or unconvertible metric definition has no usable source"
+ (are [card] (nil? (metabot.tools.util/metric-required-source card))
+ {:dataset_query {} :table_id 5}
+ ;; legacy, but unconvertible
+ {:dataset_query {:type :bogus} :table_id 5}))
+ (testing "A missing definition has no usable source"
+ (is (nil? (metabot.tools.util/metric-required-source {:table_id 5})))))
+
+(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}))
+ {: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"}
+ :aggregation [[:count]]}})))
+
+(deftest ^:parallel metric-compatible-with-stage?-test
+ (testing "a single-stage table metric accepts a card over its table"
+ (let [required {:kind :table, :table-id 5, :bare-table-only? false}]
+ (is (true? (metabot.tools.util/metric-compatible-with-stage? required {:stage-table-id 5})))
+ (is (true? (metabot.tools.util/metric-compatible-with-stage?
+ required {:stage-table-id 5 :stage-card-id 7})))
+ (is (false? (metabot.tools.util/metric-compatible-with-stage? required {:stage-table-id 9})))))
+ (testing "a multi-stage definition requires a stage directly on its base table"
+ (let [required {:kind :table, :table-id 5, :bare-table-only? true}]
+ (is (true? (metabot.tools.util/metric-compatible-with-stage? required {:stage-table-id 5})))
+ (is (false? (metabot.tools.util/metric-compatible-with-stage?
+ required {:stage-table-id 5 :stage-card-id 7})))))
+ (testing "a nil table ID cannot identify a usable table source"
+ (is (false? (metabot.tools.util/metric-compatible-with-stage?
+ {:kind :table, :table-id nil, :bare-table-only? false} {:stage-table-id nil}))))
+ (testing "an unrecognized source kind throws an exception"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Unrecognized metric source kind"
+ (metabot.tools.util/metric-compatible-with-stage? {:kind :bogus} {}))))
+ (testing "a single-stage card metric requires the exact source card"
+ (let [required {:kind :card, :card-id 42}]
+ (is (true? (metabot.tools.util/metric-compatible-with-stage? required {:stage-card-id 42})))
+ (is (false? (metabot.tools.util/metric-compatible-with-stage?
+ required {:stage-card-id 43 :stage-table-id 5})))
+ (is (false? (metabot.tools.util/metric-compatible-with-stage? required {:stage-table-id 5}))))))
+
+(deftest metric-required-source-reads-both-card-shapes-test
+ (testing "Toucan rows and lib metadata cards produce the same required source"
+ (mt/with-temp [:model/Card {question-id :id}
+ {:name "Products question" :type :question
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :products)}}}
+ :model/Card {metric-id :id}
+ {:name "Card metric" :type :metric
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (str "card__" question-id)
+ :aggregation [[:count]]}}}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ t2-row (t2/select-one :model/Card :id metric-id)
+ lib-card (lib.metadata/card mp metric-id)]
+ (is (= {:kind :card, :card-id question-id}
+ (metabot.tools.util/metric-required-source t2-row)))
+ (is (= {:kind :card, :card-id question-id}
+ (metabot.tools.util/metric-required-source lib-card))
+ "lib metadata is read without snake_case access"))))))
+
+(deftest ^:parallel metric-source-fields-test
+ (testing "exactly one group of fields, card first, `source_unavailable` when neither source is usable"
+ (are [expected input] (= expected (metabot.tools.util/metric-source-fields input))
+ {:source_card_id 7, :source_card_name "Q", :source_card_portable_entity_id "eid"}
+ {:source-card {:id 7, :name "Q", :entity_id "eid", :collection_id 3}, :database-name "Sample"}
+
+ {:base_table_id 5, :base_table_name "ORDERS", :base_table_schema "PUBLIC"
+ :base_table_portable_fk ["Sample" "PUBLIC" "ORDERS"]}
+ {:source-table {:id 5, :schema "PUBLIC", :name "ORDERS"}, :database-name "Sample"}
+
+ ;; no database name, no portable FK
+ {:base_table_id 5, :base_table_name "ORDERS", :base_table_schema "PUBLIC"}
+ {:source-table {:id 5, :schema "PUBLIC", :name "ORDERS"}}
+
+ {:source_unavailable true}
+ {:database-name "Sample"})))