Skip to content

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

Surface metric explicit-join dimensions via agent feedback (BOT-1612) (#74989)

Mihael Konjević56117f5bb872
diff --git a/resources/metabot/prompts/llm_shape.selmer b/resources/metabot/prompts/llm_shape.selmer
index 93d346c4a36..020062b9dbf 100644
--- a/resources/metabot/prompts/llm_shape.selmer
+++ b/resources/metabot/prompts/llm_shape.selmer
@@ -57,6 +57,10 @@ The following dimensions can be used for filter- or group-by operations:
Before using any field in comparisons, filters, or conditions, you should check their metadata and sample values first, using the uri `metabase://metric/{{metric_id}}/dimensions/{field_id}`.
This will help avoid errors due to unexpected data types or formats.
{% endif %}
+{% if metric_join_required_xml %}
+### Dimensions that require an explicit join
+{{metric_join_required_xml|safe}}
+{% endif %}
</metric>
{% endif %}
{% if is_table %}
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index d9762889ff9..e5dce2f5a69 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -1957,11 +1957,10 @@
(case (count candidates)
0 (let [src-name (display-source-table mp source-table-id)
tbl-name (nth fk 2)]
- (throw (ex-info (tru "Field {0} is on table {1} but there is no foreign key from the source table {2} to {3}. Either add an explicit joins: entry, or use a field from the source table."
+ (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. If you are aggregating a metric that relates to that table (metrics can join tables that have no foreign key), read that metric dimensions resource `metabase://metric/<metric_id>/dimensions` which lists the exact join clause to paste into `joins:` and the columns it unlocks. Otherwise use a field from the source table."
(display-portable fk)
(pr-str tbl-name)
- (pr-str src-name)
- (pr-str tbl-name))
+ (pr-str src-name))
{:status-code 400
:error :no-fk-path
:agent-error? true
diff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.clj
index d1be7831796..87132bde4d4 100644
--- a/src/metabase/metabot/tools/entity_details.clj
+++ b/src/metabase/metabot/tools/entity_details.clj
@@ -191,6 +191,100 @@
(not (referenced-field-readable? fk-target-field-id)))
(dissoc :fk-target-field-id)))))))
+(defn- strip-lib-uuids
+ "Recursively drop volatile `\"lib/uuid\"` keys from a portable clause so the LLM copies a clean,
+ re-pasteable join; the repair pass regenerates fresh uuids at resolve time."
+ [x]
+ (cond
+ (map? x) (into {} (keep (fn [[k v]] (when-not (= k "lib/uuid") [k (strip-lib-uuids v)]))) x)
+ (sequential? x) (mapv strip-lib-uuids x)
+ :else x))
+
+(defn- clause-field-ids
+ "Set of numeric field ids referenced by any `[:field opts id]` clause anywhere inside `x` (e.g. a
+ join's `:conditions`). Used to drop the join-key columns from the surfaced dimension list."
+ [x]
+ (into #{}
+ (comp (filter #(and (vector? %) (= :field (first %)) (int? (nth % 2 nil))))
+ (map #(nth % 2)))
+ (tree-seq coll? seq x)))
+
+(defn- metric-join-required-dimensions
+ "Dimensions a metric reaches through an EXPLICIT join with no database foreign key.
+
+ A metric's `queryable-dimensions` are computed from a *consumer-framed* query (`source-table` +
+ `[:metric …]`), so `filterable-columns` only surfaces the base table and FK-reachable tables — the
+ metric's FK-less join dimensions are silently dropped. But the metric's *definition* joins that
+ table, so a consumer query that re-adds the same join can group/filter by them. Left unsurfaced,
+ the LLM guesses at those columns and dead-ends on `:no-fk-path` (BOT-1612).
+
+ We surface them here, grouped per join. Each entry carries the portable join clause to paste into
+ `joins:` AND, per dimension, a `:reference` — the alias-qualified field clause
+ (`[\"field\" {\"join-alias\" …} [db schema table field]]`) the LLM must reference the column by.
+ The bare portable FK does NOT resolve for these columns (there is no FK path — that is the whole
+ premise), so only the alias-qualified clause is pasteable. Detection is cheap — the definition
+ query's joins are already in hand; a `:fk-field-id` of nil marks an explicit, non-FK join. Returns
+ nil when the metric has no such joins (the common case).
+
+ Fail closed: a join is surfaced only when BOTH its portable clause exported and it targets a real
+ table. These dimensions are unreachable without the join by definition, so an entry lacking the
+ clause has zero value — and instructing the LLM to paste a nil/`null` join would be strictly worse
+ than the `:no-fk-path` dead-end this feature replaces. A `:source-card`-based join (nil
+ `source-table`) is likewise dropped rather than mislabeled with a nil table name. Dimensions are
+ permission-filtered on the way out (see `permission-filter-columns`) — the join target is a table
+ the consumer query never reaches, so nothing else has checked the user can read it.
+
+ The join-key columns (fields referenced in the join `:conditions`) are excluded — the target-side
+ key equals a base-table column and is redundant groupable noise. A metric that self-joins one
+ table under two aliases yields two entries with the same columns but DIFFERENT `:join_alias`, and
+ therefore distinct (correct) references — one per alias — which is the intended behavior.
+
+ `base-reachable-ids` is the id set of the consumer-framed `filterable-columns` (already computed by
+ the caller); columns in it are reachable without the join and are not re-surfaced here."
+ [metadata-provider defq base-reachable-ids]
+ (when defq
+ (let [explicit-joins (filter #(nil? (:fk-field-id %)) (lib/joins defq -1))]
+ (when (seq explicit-joins)
+ (let [;; These columns come from a table the CONSUMER query cannot reach, so they were never
+ ;; vetted by the caller's `permission-filter-columns` pass. Reading the metric Card is
+ ;; collection-based and says nothing about the join target's Table/sandbox permissions,
+ ;; so filter here too or we would leak columns the user cannot read. A wholly
+ ;; unreadable target table yields no dims, which drops the join entry (fail closed).
+ def-cols (permission-filter-columns (lib/filterable-columns defq))
+ ;; Both `explicit-joins` and the export are keyed off the aggregation stage: `lib/joins`
+ ;; reads stage -1 and we read the exported LAST stage's joins, so their aliases line up
+ ;; for multi-stage definitions too (a stage whose join fails to export drops, closed).
+ portable-by-alias (into {}
+ (map (juxt #(get % "alias") strip-lib-uuids))
+ (-> (repr.resolve/try-export-query metadata-provider defq)
+ (get "stages") last (get "joins")))]
+ (not-empty
+ (into []
+ (keep (fn [{:keys [alias] :as jn}]
+ (let [target-tid (get-in jn [:stages 0 :source-table])
+ portable (get portable-by-alias alias)
+ key-ids (clause-field-ids (:conditions jn))
+ dims (when target-tid
+ (into []
+ (comp (filter #(and (= target-tid (:table-id %))
+ (not (base-reachable-ids (:id %)))
+ (not (key-ids (:id %)))))
+ (map #(metabot.tools.u/add-table-reference defq %))
+ (map #(metabot.tools.u/->result-column defq %))
+ (map (fn [rc]
+ (cond-> rc
+ (vector? (:portable_fk rc))
+ (assoc :reference
+ ["field" {"join-alias" alias}
+ (:portable_fk rc)])))))
+ def-cols))]
+ (when (and portable target-tid (seq dims))
+ {:join_alias alias
+ :target_table (:name (lib.metadata/table metadata-provider target-tid))
+ :join portable
+ :dimensions dims}))))
+ explicit-joins)))))))
+
(defn metric-details
"Get metric details as returned by tools."
([id] (metric-details id nil))
@@ -235,12 +329,29 @@
[database-name (:schema source-table) (:name source-table)])
query-needed? (and source-table
(or with-default-temporal-breakout? with-queryable-dimensions? with-segments?))
+ metric-card (when query-needed?
+ (lib.metadata/card metadata-provider id))
metric-query (when query-needed?
- (lib/query metadata-provider (lib.metadata/card metadata-provider id)))
+ (lib/query metadata-provider metric-card))
breakouts (when query-needed?
(lib/breakouts metric-query))
base-query (when query-needed?
(lib/remove-all-breakouts metric-query))
+ ;; Consumer-framed filterable columns (base table + FK-reachable), permission-filtered.
+ ;; Computed once and shared by `:queryable-dimensions` and the join-required-dims
+ ;; reachability filter below — which needs the FILTERED set, so that a column the user
+ ;; cannot read is never treated as "already reachable" nor re-surfaced under a join.
+ base-filterable-cols (when (and query-needed? with-queryable-dimensions?)
+ (->> (lib/filterable-columns base-query)
+ permission-filter-columns))
+ ;; Definition query (WITH the metric's own joins) — surfaces FK-less join dimensions that
+ ;; the consumer-framed `base-query` drops. Built from the card's `:dataset-query`, not from
+ ;; `metric-query`, which frames the metric as a source and hides its definition joins.
+ join-required-dims (when (and query-needed? with-queryable-dimensions?)
+ (metric-join-required-dimensions
+ metadata-provider
+ (some->> (:dataset-query metric-card) (lib/query metadata-provider))
+ (set (keep :id base-filterable-cols))))
visible-cols (when query-needed?
(->> (lib/visible-columns base-query)
permission-filter-columns
@@ -250,9 +361,7 @@
(map #(lib/find-matching-column % visible-cols))
(m/find-first lib.types.isa/temporal?)))
queryable-columns (when (and query-needed? with-queryable-dimensions?)
- (->> (lib/filterable-columns base-query)
- permission-filter-columns
- field-values-fn))]
+ (field-values-fn base-filterable-cols))]
(cond-> {:id id
:type :metric
:name (:name card)
@@ -285,6 +394,9 @@
(map #(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?)
(assoc :segments (if-let [segments (lib/available-segments metric-query)]
(mapv #(convert-measure-or-segment % :filters) segments)
diff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.clj
index 7109f98b96b..ca10d12ea0c 100644
--- a/src/metabase/metabot/tools/resources.clj
+++ b/src/metabase/metabot/tools/resources.clj
@@ -566,16 +566,16 @@
(defn- fetch-metric [id-str]
(let [metric-id (parse-long id-str)]
(check-card-resource-database metric-id)
- (entity-details/get-metric-details {:metric-id metric-id
- :with-queryable-dimensions false
- :with-field-values false})))
+ (entity-details/get-metric-details {:metric-id metric-id
+ :with-queryable-dimensions? false
+ :with-field-values? false})))
(defn- fetch-metric-dimensions [id-str]
(let [metric-id (parse-long id-str)]
(check-card-resource-database metric-id)
- (entity-details/get-metric-details {:metric-id metric-id
- :with-queryable-dimensions true
- :with-field-values false})))
+ (entity-details/get-metric-details {:metric-id metric-id
+ :with-queryable-dimensions? true
+ :with-field-values? false})))
(defn- fetch-metric-dimension [id-str dim-id]
(let [metric-id (parse-long id-str)]
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index 51aff97fe8f..768aa2de3ec 100644
--- a/src/metabase/metabot/tools/shared/llm_shape.clj
+++ b/src/metabase/metabot/tools/shared/llm_shape.clj
@@ -373,6 +373,40 @@
(= k :reference) (json-cell-safe (escape-xml-content v))
:else (escape-pipes (escape-xml (str v)))))}))
+(defn- format-join-required-dimensions-table
+ "Like [[format-metric-dimensions-table]] but the Reference is the FULL alias-qualified field clause
+ (`[\"field\" {\"join-alias\" …} [db schema table field]]`) carried on each dim's `:reference`. For
+ a join-required dim the bare portable FK does NOT resolve (no FK path); only the alias-qualified
+ clause does, so that is the form the LLM must paste."
+ [dims]
+ (te/markdown-table
+ (map (fn [d] (assoc d :reference (some-> (:reference d) json/encode))) dims)
+ {:name "Field Name" :field_id "Field ID" :type "Type"
+ :reference "Reference (copy verbatim into a field clause)"}
+ {:value-fn (fn [k v]
+ (cond
+ (nil? v) ""
+ (keyword? v) (escape-pipes (clojure.core/name v))
+ (= k :reference) (json-cell-safe (escape-xml-content v))
+ :else (escape-pipes (escape-xml (str v)))))}))
+
+(defn- format-metric-join-required-dimensions
+ "Render the metric's FK-less join dimensions — the columns the metric reaches through an explicit
+ join that its `queryable-dimensions` cannot advertise (no foreign key). For each such join we tell
+ the LLM to paste the exact join clause into `joins:` and reference each field by its alias-qualified
+ Reference. Without this the LLM guesses at the column and dead-ends on a `no foreign key` error
+ (BOT-1612)."
+ [join-required-dimensions]
+ (str/join
+ "\n"
+ (for [{:keys [target_table join dimensions]} join-required-dimensions]
+ (str "To group or filter this metric by **" target_table
+ "** columns, add this join to your query's `joins:` (the metric reaches these columns "
+ "through a join with **no foreign key**, so the join must be present), then reference a "
+ "field using its alias-qualified Reference from the table below:\n\n"
+ "```json\n" (json/encode join {:pretty true}) "\n```\n\n"
+ (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
@@ -380,7 +414,7 @@
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)."
- [{:keys [id name description verified queryable-dimensions collection
+ [{:keys [id name description verified queryable-dimensions join-required-dimensions collection
default_time_dimension_field database_name base_table_portable_fk
portable_entity_id]}]
(render-llm-template
@@ -398,7 +432,9 @@
:metric_collection_xml (when collection (collection->xml collection))
:metric_default_time_dimension (:name default_time_dimension_field)
:metric_dimensions_table (when (seq queryable-dimensions)
- (format-metric-dimensions-table queryable-dimensions))}))
+ (format-metric-dimensions-table queryable-dimensions))
+ :metric_join_required_xml (when (seq join-required-dimensions)
+ (format-metric-join-required-dimensions join-required-dimensions))}))
(defn table->xml
"Format table for LLM consumption.
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index edec7a8fcca..8c5f07af7f8 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -7,13 +7,18 @@
resolution from the query's first-stage `source-table:` (per `repr-plan.md` step 13:
unknown name, ambiguous name, missing name, mismatched DB component in source-table)."
(:require
+ [clojure.string :as str]
[clojure.test :refer [deftest is testing]]
[clojure.walk :as walk]
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
+ [metabase.lib.convert :as lib.convert]
[metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
[metabase.lib.test-util :as lib.tu]
[metabase.metabot.tools.construct :as construct]
+ [metabase.metabot.tools.entity-details :as entity-details]
+ [metabase.models.interface :as mi]
[metabase.models.serialization :as serdes]))
(set! *warn-on-reflection* true)
@@ -1109,3 +1114,163 @@
(testing "and the export round-trips: re-running the exported form yields an equal export"
(let [redo (construct/execute-representations-query (walk/keywordize-keys exported))]
(is (= exported (get-in redo [:structured-output :query-json]))))))))))))
+
+;;; ============================================================
+;;; Metric explicit-join feedback (BOT-1612)
+;;;
+;;; A metric on ORDERS explicitly joins CAMPAIGNS (NO foreign key from ORDERS) to reach
+;;; CAMPAIGNS.NAME. The fix is feedback-based, not backend-materialization:
+;;; * the metric's /dimensions resource surfaces the joined dims + the exact join clause to
+;;; paste (see entity-details-test / llm-shape-test);
+;;; * a consumer query that INCLUDES that join is honored as-is (no rewrite);
+;;; * a consumer query that OMITS the join gets an actionable `:no-fk-path` error pointing at
+;;; the metric's dimensions resource - it is NOT silently repaired.
+;;; ============================================================
+
+(def ^:private metric-eid
+ "Valid 21-char NanoID so `import-mbql` picks up the `[:metric …]` branch."
+ "Metric123_456DefGhI78")
+
+(def ^:private mp-metric-base
+ "ORDERS(10) and CAMPAIGNS(30) with NO foreign key between them."
+ (lib.tu/mock-metadata-provider
+ {:database {:id 1 :name "Sample"}
+ :tables [{:id 10 :name "ORDERS" :schema "PUBLIC" :db-id 1}
+ {:id 30 :name "CAMPAIGNS" :schema "PUBLIC" :db-id 1}]
+ :fields [{:id 100 :name "ID" :table-id 10 :base-type :type/Integer}
+ {:id 101 :name "TOTAL" :table-id 10 :base-type :type/Float}
+ {:id 102 :name "CAMPAIGN_ID" :table-id 10 :base-type :type/Integer} ;; NO :fk-target-field-id
+ {:id 300 :name "ID" :table-id 30 :base-type :type/Integer}
+ {:id 301 :name "NAME" :table-id 30 :base-type :type/Text}]}))
+
+(def ^:private metric-definition
+ "Count of ORDERS with an EXPLICIT (no-FK) join to CAMPAIGNS, as legacy MBQL for storage."
+ (-> (lib/query mp-metric-base (lib.metadata/table mp-metric-base 10))
+ (lib/join (lib/join-clause (lib.metadata/table mp-metric-base 30)
+ [(lib/= (lib.metadata/field mp-metric-base 102)
+ (lib.metadata/field mp-metric-base 300))]))
+ (lib/aggregate (lib/count))
+ lib.convert/->legacy-MBQL))
+
+(def ^:private mp-metric
+ (lib.tu/mock-metadata-provider
+ mp-metric-base
+ {:cards [{:id 700 :name "Order Count by Campaign" :type :metric :database-id 1 :table-id 10
+ :entity-id metric-eid :dataset-query metric-definition}]}))
+
+(defn- with-joined-metric-mp-and-stubs! [f]
+ (with-redefs [lib-be/application-database-metadata-provider (fn [_] mp-metric)
+ construct/resolve-database-id-from-first-stage (fn [_] 1)
+ serdes/lookup-by-id (fn [model eid]
+ (when (and (#{'Card :model/Card} model) (= eid metric-eid))
+ {:id 700 :database_id 1 :entity_id eid}))
+ api/read-check allow-read-check
+ api/query-check allow-read-check
+ ;; `metric-details` gates its base table and every surfaced column on app-db
+ ;; Table/sandbox read permissions. The mock provider's table ids have no
+ ;; `:model/Table` rows, so those checks are stubbed open to keep this namespace
+ ;; app-DB-free (see the fixture note above). That the surfaced dimensions ARE
+ ;; permission-filtered is covered against real tables in entity-details-test.
+ mi/can-read? (constantly true)
+ entity-details/permission-filter-columns identity
+ entity-details/verified-review? (constantly false)]
+ (f)))
+
+;; The join clause the metric /dimensions resource hands the LLM (uuid-free), to paste into `joins:`.
+(def ^:private advertised-campaigns-join
+ {"lib/type" "mbql/join"
+ "fields" "all"
+ "strategy" "left-join"
+ "alias" "Campaign"
+ "conditions" [["=" {}
+ ["field" {"base-type" "type/Integer"} ["Sample" "PUBLIC" "ORDERS" "CAMPAIGN_ID"]]
+ ["field" {"base-type" "type/Integer" "join-alias" "Campaign"}
+ ["Sample" "PUBLIC" "CAMPAIGNS" "ID"]]]]
+ "stages" [{"lib/type" "mbql.stage/mbql" "source-table" ["Sample" "PUBLIC" "CAMPAIGNS"]}]})
+
+(deftest metric-joined-breakout-with-explicit-join-is-honored-test
+ (testing (str "A consumer query that INCLUDES the advertised explicit join (metric aggregation on "
+ "ORDERS + join to CAMPAIGNS + breakout on CAMPAIGNS.NAME) is honored as-is: the join "
+ "stays, the breakout resolves, and the joined column appears in the result columns. "
+ "No backend materialization needed (BOT-1612).")
+ (with-joined-metric-mp-and-stubs!
+ (fn []
+ (let [result (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "joins" [advertised-campaigns-join]
+ "aggregation" [["metric" {} metric-eid]]
+ "breakout" [["field" {"join-alias" "Campaign"}
+ ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]]]}]}))
+ structured (:structured-output result)
+ q (:query structured)
+ joins (get-in q [:stages 0 :joins])
+ breakout (get-in q [:stages 0 :breakout 0])]
+ (testing "the LLM-authored join is preserved (exactly one, targeting CAMPAIGNS)"
+ (is (=? [{:stages [{:source-table 30}]}] joins))
+ (is (= "Campaign" (:alias (first joins)))))
+ (testing "the breakout keeps its join-alias and resolves to CAMPAIGNS.NAME"
+ (is (= "Campaign" (get-in breakout [1 :join-alias])))
+ (is (= 301 (nth breakout 2))))
+ (testing "CAMPAIGNS.NAME is a result column"
+ (is (some #(= 301 (:field_id %)) (:result-columns structured)))))))))
+
+(deftest metric-joined-breakout-without-join-errors-actionably-test
+ (testing (str "A consumer query that OMITS the join (bare breakout on CAMPAIGNS.NAME) is NOT "
+ "silently repaired: it errors :no-fk-path with an actionable message that points the "
+ "LLM at the metric's dimensions resource for the exact join to add (BOT-1612).")
+ (with-joined-metric-mp-and-stubs!
+ (fn []
+ (try
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "aggregation" [["metric" {} metric-eid]]
+ "breakout" [["field" {} ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]]]}]}))
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (= :no-fk-path (:error d)))
+ (is (:agent-error? d))
+ (testing "message is actionable: explains the explicit join and points at the metric resource"
+ (is (str/includes? (ex-message e) "joins:"))
+ (is (str/includes? (ex-message e) "metabase://metric"))))))))))
+
+(deftest metric-details-surfaced-artifacts-round-trip-test
+ (testing (str "END-TO-END: the join AND the per-dimension reference that `metric-details` surfaces "
+ "are pasteable verbatim - a consumer query built from BOTH resolves to CAMPAIGNS.NAME "
+ "without :no-fk-path. Guards against surfacing a bare FK reference that dead-ends "
+ "(BOT-1612).")
+ (with-joined-metric-mp-and-stubs!
+ (fn []
+ (let [entry (first (:join-required-dimensions
+ (entity-details/metric-details
+ (lib.metadata/card mp-metric 700) mp-metric {:field-values-fn identity})))
+ surfaced-join (:join entry)
+ name-ref (:reference (first (filter #(= 301 (:field_id %)) (:dimensions entry))))]
+ (testing "the surfaced reference is alias-qualified (NOT a bare portable FK that dead-ends)"
+ (is (= "field" (first name-ref)))
+ (is (some? (:join_alias entry)))
+ (is (= (:join_alias entry) (get (second name-ref) "join-alias"))
+ "the reference carries the metric join's alias, so QP re-expansion dedupes at execution")
+ (is (= ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"] (nth name-ref 2))))
+ (testing "pasting the surfaced join + reference verbatim resolves cleanly"
+ (let [result (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "joins" [surfaced-join]
+ "aggregation" [["metric" {} metric-eid]]
+ "breakout" [name-ref]}]}))
+ structured (:structured-output result)]
+ (is (= 1 (count (get-in structured [:query :stages 0 :joins]))))
+ (is (some #(= 301 (:field_id %)) (:result-columns structured))
+ "CAMPAIGNS.NAME resolves from the surfaced artifacts"))))))))
diff --git a/test/metabase/metabot/tools/entity_details_test.clj b/test/metabase/metabot/tools/entity_details_test.clj
index 4b95b9e9240..e95a8f364f4 100644
--- a/test/metabase/metabot/tools/entity_details_test.clj
+++ b/test/metabase/metabot/tools/entity_details_test.clj
@@ -3,6 +3,7 @@
(:require
[clojure.string :as str]
[clojure.test :refer :all]
+ [metabase.agent-lib.representations.resolve :as repr.resolve]
[metabase.lib-be.core :as lib-be]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
@@ -802,3 +803,137 @@
(is (=? #{{:id products :related_by {:id (mt/id :orders :product_id) :name "PRODUCT_ID"}}
{:id products :related_by {:id (mt/id :reviews :product_id) :name "PRODUCT_ID"}}}
(into #{} (map #(select-keys % [:id :related_by])) product-rows)))))))))
+
+;;; ============================================================
+;;; Explicit-join dimensions on metric-details (BOT-1612)
+;;;
+;;; A metric whose definition reaches a dimension through an EXPLICIT join with no foreign key.
+;;; The consumer-framed `queryable-dimensions` drop that column; `metric-details` must instead
+;;; surface it under `:join-required-dimensions`, carrying the exact portable join clause to paste.
+;;; ============================================================
+
+;;; These use real app-db tables rather than a `lib.tu/mock-metadata-provider`: `metric-details`
+;;; gates its base table and every surfaced column on app-db Table/sandbox read permissions, so
+;;; synthetic table ids that have no `:model/Table` row cannot get through the permission checks.
+
+(defn- no-fk-join-metric-query
+ "A metric query on ORDERS that reaches REVIEWS through an EXPLICIT join with no foreign key — there
+ is no FK from ORDERS to REVIEWS, so REVIEWS.RATING is reachable only by re-adding this join."
+ [mp]
+ (-> (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ (lib/join (lib/join-clause (lib.metadata/table mp (mt/id :reviews))
+ [(lib/= (lib.metadata/field mp (mt/id :orders :product_id))
+ (lib.metadata/field mp (mt/id :reviews :product_id)))]))
+ (lib/aggregate (lib/count))))
+
+(defn- unjoined-metric-query
+ "A metric query on ORDERS with no explicit joins at all."
+ [mp]
+ (-> (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ (lib/aggregate (lib/count))))
+
+(defn- metric-details-for
+ "Create a temp metric Card whose definition is `(query-fn mp)`, then return `metric-details` for it.
+ The provider is rebuilt after the insert so the new card is visible to `lib.metadata/card`."
+ [query-fn]
+ (mt/with-temp [:model/Card {metric-id :id} {:dataset_query (query-fn (mt/metadata-provider))
+ :database_id (mt/id)
+ :name "Metric with a no-FK join"
+ :type :metric}]
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))]
+ (entity-details/metric-details (lib.metadata/card mp metric-id) mp {:field-values-fn identity}))))
+
+(deftest metric-details-surfaces-explicit-join-dimensions-test
+ (testing (str "metric-details surfaces FK-less join dimensions the consumer-framed dimension list "
+ "drops, each with the portable join clause to paste into `joins:` (BOT-1612)")
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [rating-id (mt/id :reviews :rating)
+ details (metric-details-for no-fk-join-metric-query)
+ jrd (:join-required-dimensions details)]
+ (testing "the base queryable-dimensions do NOT advertise the joined column"
+ (is (not (some #(= rating-id (:field_id %)) (:queryable-dimensions details)))))
+ (testing "join-required-dimensions surfaces REVIEWS.RATING under the REVIEWS join"
+ (is (= 1 (count jrd)))
+ (let [{:keys [target_table join dimensions]} (first jrd)
+ reviews (t2/select-one [:model/Table :name :schema] :id (mt/id :reviews))]
+ (is (= (:name reviews) target_table))
+ (is (some #(= rating-id (:field_id %)) dimensions))
+ (testing "the join clause is a pasteable portable mbql/join targeting REVIEWS"
+ (is (= "mbql/join" (get join "lib/type")))
+ (is (= "left-join" (get join "strategy")))
+ (is (= [(t2/select-one-fn :name [:model/Database :name] :id (mt/id))
+ (:schema reviews)
+ (:name reviews)]
+ (get-in join ["stages" 0 "source-table"])))
+ (testing "volatile lib/uuid keys are stripped so the clause can be pasted repeatedly"
+ (is (nil? (get join "lib/uuid")))))))))))
+
+(deftest metric-details-omits-join-required-dimensions-when-no-explicit-join-test
+ (testing "a metric with only FK-reachable (or no) joins has no :join-required-dimensions"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (is (nil? (:join-required-dimensions (metric-details-for unjoined-metric-query)))))))
+
+(deftest metric-details-omits-join-required-dimensions-when-export-fails-test
+ (testing (str "fail closed: when the portable join clause cannot be exported, the entry is DROPPED "
+ "rather than surfaced with a nil join - instructing the LLM to paste `null` into "
+ "`joins:` would be strictly worse than the :no-fk-path dead-end (BOT-1612)")
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-dynamic-fn-redefs [repr.resolve/try-export-query (constantly nil)]
+ (is (nil? (:join-required-dimensions (metric-details-for no-fk-join-metric-query)))
+ "no join-required-dimensions when the join clause failed to export")))))
+
+(deftest metric-details-omits-join-required-dimensions-for-unreadable-join-target-test
+ (testing (str "the FK-less join target is a table the consumer-framed query never reaches, so no "
+ "other pass has permission-checked it: dimensions from a table the user cannot read "
+ "must not be surfaced, and a join with no readable dimensions drops entirely")
+ (mt/with-no-data-perms-for-all-users!
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-table-permission! (perms-group/all-users) (mt/id :orders)
+ :perms/create-queries :query-builder-and-native)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [details (metric-details-for no-fk-join-metric-query)]
+ (is (seq (:queryable-dimensions details))
+ "the readable base table still yields dimensions")
+ (is (nil? (:join-required-dimensions details))
+ "REVIEWS is unreadable, so its join-required dimensions are withheld")
+ (is (not (str/includes? (pr-str details) "RATING"))))))))
+
+(deftest get-metric-details-surfaces-join-required-dims-through-resource-path-test
+ (testing (str "the REAL resource entry point (get-metric-details, as resources.clj calls it) "
+ "surfaces join-required dimensions for a metric with an explicit no-FK join, with "
+ "alias-qualified references - and omits them when queryable-dimensions are off. Guards "
+ "the get-metric-details wiring + option keys the mock-provider tests bypass (BOT-1612).")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (mt/metadata-provider)
+ ;; ORDERS explicitly joins REVIEWS on PRODUCT_ID (there is NO FK from ORDERS to REVIEWS)
+ ;; to reach REVIEWS.RATING.
+ metric-query (-> (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ (lib/join (lib/join-clause
+ (lib.metadata/table mp (mt/id :reviews))
+ [(lib/= (lib.metadata/field mp (mt/id :orders :product_id))
+ (lib.metadata/field mp (mt/id :reviews :product_id)))]))
+ (lib/aggregate (lib/count)))]
+ (mt/with-temp [:model/Card {metric-id :id} {:dataset_query metric-query
+ :database_id (mt/id)
+ :name "Orders w/ no-FK Reviews join"
+ :type :metric}]
+ (testing "/dimensions path (with-queryable-dimensions? default true): join-required dims present"
+ (let [out (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id :with-field-values? false}))
+ jrd (:join-required-dimensions out)]
+ (is (seq jrd) "join-required-dimensions surfaced through the real resource path")
+ (let [{:keys [target_table dimensions]} (first jrd)
+ rating (first (filter #(= (mt/id :reviews :rating) (:field_id %)) dimensions))]
+ (is (= (t2/select-one-fn :name [:model/Table :name] :id (mt/id :reviews)) target_table))
+ (is (some? rating) "REVIEWS.RATING is surfaced")
+ (is (= "field" (first (:reference rating))))
+ (is (contains? (second (:reference rating)) "join-alias")
+ "the reference is alias-qualified, not a bare FK"))))
+ (testing "plain metric resource (with-queryable-dimensions? false): dims omitted"
+ (let [out (:structured-output (entity-details/get-metric-details
+ {:metric-id metric-id
+ :with-queryable-dimensions? false
+ :with-field-values? false}))]
+ (is (nil? (:queryable-dimensions out)))
+ (is (nil? (:join-required-dimensions out)))))))))))
diff --git a/test/metabase/metabot/tools/shared/llm_shape_test.clj b/test/metabase/metabot/tools/shared/llm_shape_test.clj
index 6b2eb1711d3..74527078aef 100644
--- a/test/metabase/metabot/tools/shared/llm_shape_test.clj
+++ b/test/metabase/metabot/tools/shared/llm_shape_test.clj
@@ -99,7 +99,30 @@
(let [metric {:id 1 :name "Test" :verified false}
xml (llm-shape/metric->xml metric)]
(is (str/includes? xml "is_verified=\"false\""))
- (is (not (str/includes? xml "### Dimensions"))))))
+ (is (not (str/includes? xml "### Dimensions")))))
+ (testing "surfaces join-required (FK-less join) dimensions with the pasteable join clause (BOT-1612)"
+ (let [metric {:id 42 :name "Order Count by Campaign" :verified true
+ :join-required-dimensions
+ [{:join_alias "Campaign"
+ :target_table "CAMPAIGNS"
+ :join {"lib/type" "mbql/join" "strategy" "left-join" "alias" "Campaign"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "CAMPAIGNS"]}]}
+ :dimensions [{:name "NAME" :field_id 301 :type "string"
+ :portable_fk ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]
+ :reference ["field" {"join-alias" "Campaign"}
+ ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]]}]}]}
+ xml (llm-shape/metric->xml metric)]
+ (is (str/includes? xml "### Dimensions that require an explicit join"))
+ (is (str/includes? xml "no foreign key"))
+ (testing "the exact join clause is embedded as JSON for the LLM to paste"
+ (is (str/includes? xml "\"mbql/join\""))
+ (is (str/includes? xml "\"source-table\"")))
+ (testing "the per-dimension Reference is the ALIAS-QUALIFIED field clause, not a bare FK"
+ (is (str/includes? xml "NAME"))
+ ;; the pasteable form carries the join-alias; a bare `[db,schema,table,field]` here would
+ ;; dead-end on :no-fk-path (BOT-1612)
+ (is (str/includes? xml "[\"field\",{\"join-alias\":\"Campaign\"},[\"Sample\",\"PUBLIC\",\"CAMPAIGNS\",\"NAME\"]]"))))))
(deftest ^:parallel format-metric-dimensions-table-test
(testing "dimensions carry their source table + a copy-paste portable FK, disambiguating