The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
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.selmerindex 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.cljindex 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? truediff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.cljindex 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.cljindex 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.cljindex 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 metricin `construct_notebook_query` (as `aggregation: [[metric, {}, <eid>]]` on top of themetric's base table)."- [{:keys [id name description verified queryable-dimensions collection+ [{:keys [id name description verified queryable-dimensions join-required-dimensions collectiondefault_time_dimension_field database_name base_table_portable_fkportable_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.cljindex 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.cljindex 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.cljindex 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