Skip to content

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

Limit metabot related-tables to bound context size (#76588)

applebyd5fea3a9a063
diff --git a/resources/metabot/prompts/llm_shape.selmer b/resources/metabot/prompts/llm_shape.selmer
index da7480b02ac..74bcf1f09ca 100644
--- a/resources/metabot/prompts/llm_shape.selmer
+++ b/resources/metabot/prompts/llm_shape.selmer
@@ -24,9 +24,18 @@
<description>{{collection_description}}</description>{% endif %}</collection>
{% endif %}
{% if is_related_table %}
-<related-table{% if related_table_id %} id="{{related_table_id}}"{% endif %} name="{{related_table_name}}"{% if related_table_related_by %} related_by="{{related_table_related_by}}"{% endif %}{% if related_table_database_name %} database_name="{{related_table_database_name}}"{% endif %} fully_qualified_name="{{related_table_fqn}}">{% if related_table_fields_xml %}
+<related-table{% if related_table_id %} id="{{related_table_id}}"{% endif %} name="{{related_table_name}}"{% if related_table_related_by_name %} related_by_field_name="{{related_table_related_by_name}}"{% endif %}{% if related_table_related_by_id %} related_by_field_id="{{related_table_related_by_id}}"{% endif %}{% if related_table_database_name %} database_name="{{related_table_database_name}}"{% endif %} fully_qualified_name="{{related_table_fqn}}">{% if related_table_description %}
+{{related_table_description}}{% endif %}{% if related_table_fields_xml %}
{{related_table_fields_xml|safe}}{% endif %}</related-table>
{% endif %}
+{% if is_related_tables %}{% if related_tables_with_fields_xml %}{{related_tables_with_fields_xml|safe}}
+{% endif %}{% if related_tables_without_fields_xml %}<related-tables-fields-omitted>
+The related tables below are listed without their fields. Look them up separately if you need field details.
+{{related_tables_without_fields_xml|safe}}
+</related-tables-fields-omitted>
+{% endif %}{% if related_tables_truncated %}<related-tables-truncated surfaced="{{related_tables_surfaced}}"{% if related_tables_total %} total="{{related_tables_total}}"{% endif %}>
+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 %}>
{% if metric_collection_xml %}
diff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.clj
index 576f037bb1f..e96410025af 100644
--- a/src/metabase/metabot/tools/entity_details.clj
+++ b/src/metabase/metabot/tools/entity_details.clj
@@ -239,7 +239,23 @@
:database_id :database_name :portable_entity_id
:base_table_id :base_table_name :base_table_portable_fk]))))
-(declare related-tables)
+(declare ^:private related-tables)
+
+(def ^:private max-related-tables-with-fields
+ "Maximum number of related-tables to expand with their full column set.
+
+ Each expanded table fetches and formats all of its columns. On a highly-connected schema with wide tables, this can
+ exhaust the heap (metabase#76493). We fetch only this many related tables with column metadata; the rest (up
+ to [[max-related-tables]]) are surfaced without columns."
+ 10)
+
+(def ^:private max-related-tables
+ "Maximum number of related-tables to surface at all.
+
+ The first [[max-related-tables-with-fields]] of these carry their columns; the remainder are surfaced by identity
+ only (id/name/description/FK/FQN, no column fetch) so the LLM still knows they exist and can look them up
+ individually. Any related-tables beyond this are dropped with a note presented to the LLM in rendering."
+ 50)
(defn- table-details
([id] (table-details id nil))
@@ -274,8 +290,8 @@
(->> (lib/visible-columns table-query -1 {:include-implicitly-joinable? false})
field-values-fn
(map #(metabot.tools.u/add-table-reference table-query %))))
- related-tables (when with-related-tables?
- (related-tables table-query with-fields? field-values-fn))]
+ related (when with-related-tables?
+ (related-tables table-query with-fields? field-values-fn))]
(-> {:id id
:type :table
:fields (mapv #(metabot.tools.u/->result-column table-query %) cols)
@@ -291,7 +307,6 @@
;; [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)
- :related_tables related-tables
:metrics (when with-metrics?
(not-empty (mapv #(convert-metric % mp options)
(lib/available-metrics table-query))))
@@ -300,27 +315,80 @@
(lib/available-measures table-query))))
:segments (when with-segments?
(not-empty (mapv #(convert-measure-or-segment % :filters)
- (lib/available-segments table-query))))))))))
-
-(defn related-tables
+ (lib/available-segments table-query)))))
+ (merge related))))))
+
+(defn- fk-related-table-groups
+ "Sorted `[target-table-id fk-field-id fk-field-name]` tuples for every direct FK from `query`'s source table.
+
+ The FK paths that become [[related-tables]]. Each tuple means \"`fk-field-id` (named `fk-field-name`) points at
+ `target-table-id`\", so a table reachable through several FKs appears once per FK.
+
+ This deliberately does NOT `:include-implicitly-joinable?` when calling `lib/visible-columns` to find related
+ tables: that fetches and caches the full column set of every FK-target table, even though we only
+ expand [[max-related-tables]] of them (metabase#76493). Instead we read the source table's own FK columns and do a
+ single bulk lookup of just the target fields (not their sibling columns) to map each FK to its table."
+ [query]
+ (let [source-cols (lib/visible-columns query -1 {:include-implicitly-joinable? false})
+ existing-table-ids (into #{} (keep :table-id) source-cols)
+ fk-cols (filter (every-pred :fk-target-field-id (comp number? :id)) source-cols)
+ id->target-field (m/index-by :id (lib.metadata/bulk-metadata
+ query :metadata/column (into #{} (map :fk-target-field-id) fk-cols)))]
+ (->> fk-cols
+ (keep (fn [{fk-field-id :id, fk-field-name :name, :keys [fk-target-field-id]}]
+ ;; the target field might not exist; skip self/already-joined tables
+ (when-let [target (id->target-field fk-target-field-id)]
+ (when-not (contains? existing-table-ids (:table-id target))
+ [(:table-id target) fk-field-id fk-field-name]))))
+ distinct
+ ;; sort for a deterministic selection when we cap, so the same tables are kept
+ sort)))
+
+(defn- related-tables
"Constructs a list of tables, optionally including their fields, that are related to the given query via foreign key.
- Creates separate entries for each FK path when the same table is reachable through multiple foreign keys."
+ Creates separate entries for each FK path when the same table is reachable through multiple foreign keys. We surface
+ up to [[max-related-tables]] FK paths; only the first [[max-related-tables-with-fields]] carry their column set to
+ keep memory usage bounded (metabase#76493), even when `with-fields?` is true. Returns nil when the query has no
+ FK-related tables, otherwise a map:
+
+ :related_tables vector of related-table maps, one per FK path. When `with-fields?` is true they
+ carry their column set and the list is capped at [[max-related-tables-with-fields]];
+ when `with-fields?` is false they carry no columns and the list holds the whole
+ surfaced set (capped at [[max-related-tables]]).
+ :related_tables_without_fields (optional) the remaining surfaced FK paths, built the same way but without
+ columns. Present only when `with-fields?` is true and there are more FK paths
+ than [[max-related-tables-with-fields]], capped so the two lists together hold at
+ most [[max-related-tables]]. Omitted entirely when `with-fields?` is false, since
+ without columns there is no distinction between the two lists.
+ :related_tables_total (optional) total number of related-tables before capping. Present only when
+ that total exceeds [[max-related-tables]] (i.e. some were dropped entirely), so
+ the LLM knows the surfaced set is truncated."
[query with-fields? field-values-fn]
- (let [all-main-cols (lib/visible-columns query)
- fk-cols (filter :fk-field-id all-main-cols)
- grouped-fks (group-by (juxt :table-id :fk-field-id) fk-cols)]
- (when (seq grouped-fks)
- (mapv
- (fn [[[table-id fk-field-id] _]]
- (let [base-details (table-details table-id
- {:with-fields? with-fields?
- :field-values-fn field-values-fn
- :with-related-tables? false
- :with-metrics? false})
- base-table-col (lib.metadata/field query fk-field-id)
- fk-field-name (:name base-table-col)]
- (assoc base-details :related_by fk-field-name)))
- grouped-fks))))
+ (let [fk-groups (fk-related-table-groups query)
+ total (count fk-groups)]
+ (when (pos? total)
+ (when (and with-fields? (> total max-related-tables-with-fields))
+ (log/infof "Capping related-tables column expansion to %d of %d." max-related-tables-with-fields total))
+ (when (> total max-related-tables)
+ (log/infof "Capping related-tables to %d of %d." max-related-tables total))
+ (let [capped (take max-related-tables fk-groups)
+ ;; Only split into a with-fields/without-fields pair when the caller actually asked for columns.
+ [with-groups without-groups] (if with-fields?
+ (split-at max-related-tables-with-fields capped)
+ [capped nil])
+ build (fn [include-fields? [table-id fk-field-id fk-field-name]]
+ (-> (table-details table-id
+ {:metadata-provider query
+ :field-values-fn field-values-fn
+ :with-fields? include-fields?
+ :with-related-tables? false
+ :with-metrics? false})
+ (assoc :related_by {:id fk-field-id :name fk-field-name})))
+ maybe-with-fields (mapv #(build (boolean with-fields?) %) with-groups)
+ without-fields (mapv #(build false %) without-groups)]
+ (cond-> {:related_tables maybe-with-fields}
+ (seq without-fields) (assoc :related_tables_without_fields without-fields)
+ (> total max-related-tables) (assoc :related_tables_total total))))))
(defn- card-details
"Get details for a card."
@@ -356,8 +424,8 @@
returned-fields (when with-fields?
(->> (lib/returned-columns card-query)
field-values-fn))
- related-tables (when with-related-tables?
- (related-tables card-query with-fields? field-values-fn))]
+ related (when with-related-tables?
+ (related-tables card-query with-fields? field-values-fn))]
(-> {:id id
:type card-type
:fields (mapv #(metabot.tools.u/->result-column card-query %) returned-fields)
@@ -397,7 +465,6 @@
metadata-provider
(lib/query metadata-provider (lib-be/normalize-query dataset-query))
shared.content-store/default-store))
- :related_tables related-tables
:metrics (when with-metrics?
(not-empty (mapv #(convert-metric % metadata-provider options)
(lib/available-metrics card-query))))
@@ -406,7 +473,8 @@
(lib/available-measures card-query))))
:segments (when with-segments?
(not-empty (mapv #(convert-measure-or-segment % :filters)
- (lib/available-segments card-query)))))))))
+ (lib/available-segments card-query)))))
+ (merge related)))))
(defn cards-details
"Get the details of metrics or models as specified by `card-type` and `cards`
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index c059af04cd0..00ecaa291bf 100644
--- a/src/metabase/metabot/tools/shared/llm_shape.clj
+++ b/src/metabase/metabot/tools/shared/llm_shape.clj
@@ -110,6 +110,17 @@
(when s
(str/replace s "|" "\\u007c")))
+(defn- truncate
+ "Cap `s` at `max-len` characters, appending an ellipsis when truncated.
+ Useful to ensure long free text values (e.g. table descriptions) don't bloat the LLM context.
+ Returns nil for nil input."
+ [s max-len]
+ (when s
+ (let [s (str s)]
+ (if (> (count s) max-len)
+ (str (subs s 0 max-len) "...")
+ s))))
+
(defn- database-type-or-unknown
"Return database type or 'unknown' if nil."
[database-type]
@@ -128,6 +139,7 @@
:is_field (= type :field)
:is_collection (= type :collection)
:is_related_table (= type :related_table)
+ :is_related_tables (= type :related_tables)
:is_metric (= type :metric)
:is_table (= type :table)
:is_model (= type :model)
@@ -275,17 +287,50 @@
:segment_definition_description definition-description}
(drill-in-location-context "segment" m))))
+(def ^:private max-related-table-description-length
+ "Cap on a related table's description."
+ 512)
+
(defn- related-table->xml
- "Format a related table for LLM consumption."
- [{:keys [id name related_by database_name fully_qualified_name fields]}]
+ "Format a related table for LLM consumption.
+ Used for both :related_tables and :related_tables_without_columns."
+ [{:keys [id name related_by database_name database_schema description fields]}]
(render-llm-template
:related_table
- {:related_table_id (when (some? id) (str id))
- :related_table_name name
- :related_table_related_by related_by
- :related_table_database_name database_name
- :related_table_fqn fully_qualified_name
- :related_table_fields_xml (when (seq fields) (str/join "\n" (map field->xml fields)))}))
+ {:related_table_id (when (some? id) (str id))
+ :related_table_name name
+ :related_table_related_by_name (:name related_by)
+ :related_table_related_by_id (str (:id related_by))
+ :related_table_database_name database_name
+ :related_table_fqn (fully-qualified-name database_schema name)
+ :related_table_description (when (not-empty description)
+ (truncate description max-related-table-description-length))
+ :related_table_fields_xml (when (seq fields) (str/join "\n" (map field->xml fields)))}))
+
+(defn- related-tables->xml
+ "Render the related-tables block for a table/model.
+
+ `related-tables` carry their fields; `without-fields` do not. They are rendered as the same `<related-table>`
+ element, but grouped under a note that their columns were omitted, so the LLM can fetch them individually if
+ needed. `total` is the full related-tables count before any cap. When it exceeds the surfaced set we tell the LLM
+ the list is truncated.
+
+ Returns nil when there is nothing to render."
+ [related-tables without-fields total]
+ (let [with-fields-xml (when (seq related-tables)
+ (str/join "" (map related-table->xml related-tables)))
+ without-fields-xml (when (seq without-fields)
+ (str/join "" (map related-table->xml without-fields)))
+ surfaced (+ (count related-tables) (count without-fields))
+ truncated? (boolean (and total (> total surfaced)))]
+ (when (or with-fields-xml without-fields-xml)
+ (render-llm-template
+ :related_tables
+ {:related_tables_with_fields_xml with-fields-xml
+ :related_tables_without_fields_xml without-fields-xml
+ :related_tables_surfaced surfaced
+ :related_tables_truncated truncated?
+ :related_tables_total total}))))
(defn- dimension-source-table
"Human-readable `schema.table` for a queryable dimension, derived from its portable FK, plus
@@ -358,7 +403,8 @@
without a separate `entity_details` call — it's the first slot of every portable FK in
the representations-format `construct_notebook_query` tool."
[{:keys [id name database_id database_name database_engine database_schema
- description fields related_tables measures segments]}]
+ description fields related_tables related_tables_total
+ related_tables_without_fields measures segments]}]
(let [fqn (fully-qualified-name database_schema name)]
(render-llm-template
:table
@@ -371,8 +417,9 @@
:table_description description
:table_fields_xml (when (seq fields)
(str/join "\n" (map field->xml fields)))
- :table_related_tables_xml (when (seq related_tables)
- (str/join "" (map related-table->xml related_tables)))
+ :table_related_tables_xml (related-tables->xml related_tables
+ related_tables_without_fields
+ related_tables_total)
:table_measures_xml (when (seq measures)
(str/join "\n" (map measure->xml measures)))
:table_segments_xml (when (seq segments)
@@ -400,7 +447,8 @@
representations form used elsewhere. Note: Python uses <metabase-model> tag but closes
with </model>."
[{:keys [id name description verified fields database_id database_name database_engine
- related_tables measures segments portable_entity_id query_json]}]
+ related_tables related_tables_total related_tables_without_fields
+ measures segments portable_entity_id query_json]}]
(let [fqn (model-fully-qualified-name id name)]
(render-llm-template
:model
@@ -416,8 +464,9 @@
:model_query_json (repr-data->llm-block query_json)
:model_fields_xml (when (seq fields)
(str/join "\n" (map field->xml fields)))
- :model_related_tables_xml (when (seq related_tables)
- (str/join "\n" (map related-table->xml related_tables)))
+ :model_related_tables_xml (related-tables->xml related_tables
+ related_tables_without_fields
+ related_tables_total)
:model_measures_xml (when (seq measures)
(str/join "\n" (map measure->xml measures)))
:model_segments_xml (when (seq segments)
diff --git a/test/metabase/metabot/tools/entity_details_test.clj b/test/metabase/metabot/tools/entity_details_test.clj
index b317c1b1b22..1f43277cf55 100644
--- a/test/metabase/metabot/tools/entity_details_test.clj
+++ b/test/metabase/metabot/tools/entity_details_test.clj
@@ -520,3 +520,153 @@
:structured-output)]
(is (map? (:query_json output)))
(is (= "mbql/query" (get-in output [:query_json "lib/type"])))))))))
+
+(deftest related-tables-with-fields-capped-test
+ (testing (str "FK-related-table *column* expansion is capped at `max-related-tables-with-fields` so a table "
+ "with a very large / highly-connected schema can't fetch and pin an unbounded number of columns "
+ "during a single MetaBot context build (metabase#76493)")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [with-fields-tables (fn []
+ (-> (entity-details/get-table-details {:entity-type :table
+ :entity-id (mt/id :orders)})
+ :structured-output
+ :related_tables))]
+ (testing "Orders has more than one FK-related table by default (Products + People)"
+ (is (> (count (with-fields-tables)) 1)))
+ (testing "with the cap lowered, no more than `max-related-tables-with-fields` related tables carry columns"
+ (with-redefs-fn {#'entity-details/max-related-tables-with-fields 1}
+ (fn []
+ (let [tables (with-fields-tables)]
+ (is (= 1 (count tables)))
+ (is (every? (comp seq :fields) tables)
+ "the surfaced column-bearing table actually carries its fields"))))))))))
+
+(deftest related-tables-without-fields-list-test
+ (testing (str "FK-related tables beyond the column-expansion cap are still surfaced by identity (no column "
+ "fetch) in :related_tables_without_fields, so the LLM knows they exist and can look them up "
+ "individually (metabase#76493)")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [details (fn []
+ (:structured-output
+ (entity-details/get-table-details {:entity-type :table
+ :entity-id (mt/id :orders)})))]
+ (testing "no without-fields list when every related table fits under the column cap"
+ (let [output (details)]
+ (is (nil? (:related_tables_without_fields output)))
+ (is (nil? (:related_tables_total output)))))
+ (testing "lowering the column cap moves the remaining tables into the without-fields list"
+ (with-redefs-fn {#'entity-details/max-related-tables-with-fields 1}
+ (fn []
+ (let [output (details)
+ with-fields (:related_tables output)
+ without (:related_tables_without_fields output)]
+ (is (= 1 (count with-fields)))
+ (is (= 1 (count without)))
+ (testing "list entries carry id/name but no columns"
+ (is (every? :id without))
+ (is (every? :name without))
+ (is (every? (comp empty? :fields) without)))
+ (testing ":related_tables and the list are disjoint FK paths"
+ (let [shown-paths (into #{} (map (juxt :id :related_by)) with-fields)]
+ (is (not-any? (comp shown-paths (juxt :id :related_by)) without))))
+ (testing "no tables were dropped entirely, so no :related_tables_total"
+ (is (nil? (:related_tables_total output)))))))))))))
+
+(deftest related-tables-total-truncation-test
+ (testing (str "FK-related tables beyond `max-related-tables` are dropped entirely and the drop is reported via "
+ ":related_tables_total so the LLM knows the surfaced set is itself truncated (metabase#76493)")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ ;; surface only one of Orders' two FK-related tables; the other is dropped entirely
+ (with-redefs-fn {#'entity-details/max-related-tables 1}
+ (fn []
+ (let [output (:structured-output
+ (entity-details/get-table-details {:entity-type :table
+ :entity-id (mt/id :orders)}))]
+ (is (= 1 (count (:related_tables output))))
+ (is (nil? (:related_tables_without_fields output))
+ "with only one table surfaced and it carrying fields, the without-fields list is empty")
+ (is (= 2 (:related_tables_total output))
+ ":related_tables_total reports the full FK-related count before the cap")
+ (is (> (:related_tables_total output)
+ (+ (count (:related_tables output))
+ (count (:related_tables_without_fields output))))
+ "total exceeds the surfaced set, signalling tables were dropped"))))))))
+
+(deftest related-tables-without-fields-omitted-when-no-fields-requested-test
+ (testing (str "with `with-fields?` false every related table is column-free, so there is no with/without "
+ "distinction: the whole capped set is surfaced in :related_tables and :related_tables_without_fields "
+ "is omitted, while the :related_tables cap is still enforced")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [orders-query (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders))))
+ related (fn [] (#'entity-details/related-tables orders-query false identity))]
+ (testing "Orders has more than one FK-related table (Products + People)"
+ (is (> (count (:related_tables (related))) 1)))
+ (testing "lowering the column-expansion cap does NOT spill into a without-fields list"
+ (with-redefs-fn {#'entity-details/max-related-tables-with-fields 1}
+ (fn []
+ (let [output (related)]
+ (is (> (count (:related_tables output)) 1)
+ "every surfaced table stays in :related_tables")
+ (is (every? (comp empty? :fields) (:related_tables output))
+ "no table carries columns when with-fields? is false")
+ (is (nil? (:related_tables_without_fields output))
+ ":related_tables_without_fields is omitted entirely when with-fields? is false")))))
+ (testing "the :related_tables cap still applies (and reports drops) when with-fields? is false"
+ (with-redefs-fn {#'entity-details/max-related-tables 1}
+ (fn []
+ (let [output (related)]
+ (is (= 1 (count (:related_tables output))))
+ (is (nil? (:related_tables_without_fields output)))
+ (is (= 2 (:related_tables_total output))
+ "tables dropped by the cap are still reported via :related_tables_total"))))))))))
+
+(defn- orders+reviews-join-query
+ "A query whose source table is Orders with an explicit join to Reviews.
+
+ Both tables carry a `PRODUCT_ID` FK to Products, so `visible-columns` exposes two FK columns with the same name
+ pointing at the same target table and therefore must be distinguished by field id, not name."
+ []
+ (let [mp (mt/metadata-provider)]
+ (-> (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 :id))
+ (lib.metadata/field mp (mt/id :reviews :id)))])))))
+
+(deftest fk-related-table-groups-distinguishes-same-named-fks-test
+ (testing (str "two distinct FK fields that share a name and point at the same target table stay separate FK paths: "
+ "`fk-related-table-groups` keys distinctness on the FK field id, not its name (so they don't collapse)")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [groups (#'entity-details/fk-related-table-groups (orders+reviews-join-query))
+ products (mt/id :products)
+ ;; the two PRODUCT_ID FK paths: orders.PRODUCT_ID and reviews.PRODUCT_ID, both -> products
+ product-paths (filter (fn [[target-table-id _ fk-name]]
+ (and (= target-table-id products) (= fk-name "PRODUCT_ID")))
+ groups)]
+ (testing "both PRODUCT_ID FKs survive distinct/sort as separate tuples"
+ (is (= 2 (count product-paths))))
+ (testing "they share a name and target table but differ by FK field id"
+ (is (=? #{[products (mt/id :orders :product_id) "PRODUCT_ID"]
+ [products (mt/id :reviews :product_id) "PRODUCT_ID"]}
+ (set product-paths)))))))))
+
+(deftest related-tables-related-by-field-id-test
+ (testing (str "`:related_by` carries a `{:id :name}` map so the LLM can disambiguate two related-table entries that "
+ "share a `:related_by` name and target table (e.g. orders.PRODUCT_ID vs reviews.PRODUCT_ID)")
+ (mt/test-driver :h2
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [output (#'entity-details/related-tables (orders+reviews-join-query) false identity)
+ products (mt/id :products)
+ product-rows (filter #(and (= (:id %) products) (= (-> % :related_by :name) "PRODUCT_ID"))
+ (:related_tables output))]
+ (testing "every related table's :related_by is a {:id :name} map"
+ (is (every? #(and (-> % :related_by :id) (-> % :related_by :name)) (:related_tables output))))
+ (testing "the two same-named PRODUCT_ID entries are present and distinguished only by :related_by :id"
+ (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)))))))))
diff --git a/test/metabase/metabot/tools/shared/llm_shape_test.clj b/test/metabase/metabot/tools/shared/llm_shape_test.clj
index dcca8531d2f..98356aa2c40 100644
--- a/test/metabase/metabot/tools/shared/llm_shape_test.clj
+++ b/test/metabase/metabot/tools/shared/llm_shape_test.clj
@@ -261,8 +261,8 @@
:database_schema "public"
:description "User accounts"
:fields [{:name "id" :field_id "f1" :base-type :type/Integer :database_type "INTEGER"}]
- :related_tables [{:id 20 :name "orders" :fully_qualified_name "public.orders"
- :related_by "user_id" :fields []}]}
+ :related_tables [{:id 20 :name "orders" :database_schema "public"
+ :related_by {:id 91 :name "user_id"} :fields []}]}
xml (llm-shape/table->xml table)]
(is (str/starts-with? xml "<table"))
;; Python format: id="10", name="users"
@@ -735,3 +735,115 @@
(testing "falls back to pr-str for unknown types"
(let [result (llm-shape/entity->xml {:type :unknown :data "test"})]
(is (str/includes? result ":type")))))
+
+(def ^:private base-table-with-related
+ "Orders with one column-bearing related table, two surfaced without columns, and more dropped entirely
+ (surfaced 3, total 5)."
+ {:id 10
+ :name "orders"
+ :database_id 1
+ :database_engine "postgres"
+ :database_schema "public"
+ :related_tables [{:id 20 :name "products" :database_schema "public"
+ :related_by {:id 92 :name "product_id"} :fields []}]
+ :related_tables_without_fields [{:id 21 :name "people" :database_schema "public"
+ :related_by {:id 91 :name "user_id"}}
+ {:id 22 :name "reviews" :database_schema "public"
+ :related_by {:id 93 :name "review_id"}}]
+ :related_tables_total 5})
+
+(deftest ^:parallel table->xml-related-tables-with-fields-test
+ (testing "a column-bearing related table renders as <related-table> with a derived fully_qualified_name"
+ (let [xml (llm-shape/table->xml base-table-with-related)]
+ (is (str/includes? xml "<related-table id=\"20\" name=\"products\"")
+ "the column-bearing related table is rendered")
+ (is (str/includes? xml "fully_qualified_name=\"public.products\"")
+ "the FQN is derived from the related table's schema + name (not a precomputed key)"))))
+
+(deftest ^:parallel table->xml-related-tables-fields-omitted-test
+ (testing (str "related tables surfaced without fields render under a <related-tables-fields-omitted> note as "
+ "<related-table> elements with FK + FQN but no <field>s, so the LLM can look them up if needed")
+ (let [xml (llm-shape/table->xml base-table-with-related)]
+ (is (str/includes? xml "<related-tables-fields-omitted>")
+ "a note tells the LLM these tables' fields were omitted")
+ (is (str/includes? xml (str "<related-table id=\"21\" name=\"people\" related_by_field_name=\"user_id\" "
+ "related_by_field_id=\"91\" fully_qualified_name=\"public.people\"></related-table>"))
+ "an identity-only table renders as <related-table> with FQN and FK but no columns")
+ (is (str/includes? xml (str "<related-table id=\"22\" name=\"reviews\" related_by_field_name=\"review_id\" "
+ "related_by_field_id=\"93\" fully_qualified_name=\"public.reviews\"></related-table>"))))))
+
+(deftest ^:parallel table->xml-related-table-description-test
+ (testing "a related table surfaces its description when present, and omits it when absent"
+ (let [xml (llm-shape/table->xml
+ (assoc base-table-with-related
+ :related_tables_without_fields [{:id 22 :name "reviews" :database_schema "public"
+ :related_by {:id 93 :name "review_id"}
+ :description "All the reviews customers left"}
+ {:id 21 :name "people" :database_schema "public"
+ :related_by {:id 91 :name "user_id"}}]))]
+ (is (str/includes? xml "All the reviews customers left")
+ "the description renders inside the <related-table> element")
+ (is (str/includes? xml (str "<related-table id=\"21\" name=\"people\" related_by_field_name=\"user_id\" "
+ "related_by_field_id=\"91\" fully_qualified_name=\"public.people\"></related-table>"))
+ "a related table with no description renders no description content")))
+ (testing "a long related-table description is capped and gets an ellipsis"
+ (let [long-desc (apply str (repeat 600 "x"))
+ cap-len @#'llm-shape/max-related-table-description-length
+ xml (llm-shape/table->xml
+ (assoc base-table-with-related
+ :related_tables_without_fields [{:id 22 :name "reviews" :database_schema "public"
+ :related_by {:id 93 :name "review_id"}
+ :description long-desc}]))]
+ (is (str/includes? xml (str (apply str (repeat cap-len "x")) "..."))
+ "the description is rendered truncated to the cap with an ellipsis")
+ (is (not (str/includes? xml (apply str (repeat (inc cap-len) "x"))))
+ "the description is truncated to the cap before the ellipsis"))))
+
+(deftest ^:parallel table->xml-related-tables-total-truncation-test
+ (testing "when more FK-related tables exist than were surfaced, a <related-tables-truncated> note reports the totals"
+ (let [xml (llm-shape/table->xml base-table-with-related)] ; surfaced 3, total 5
+ (is (str/includes? xml "<related-tables-truncated surfaced=\"3\" total=\"5\">"))
+ (is (str/includes? xml "more FK-related tables than the 3 shown here"))))
+ (testing "no truncation note when every FK-related table was surfaced"
+ (let [xml (llm-shape/table->xml (assoc base-table-with-related :related_tables_total 3))] ; surfaced 3, total 3
+ (is (not (str/includes? xml "<related-tables-truncated"))
+ "surfacing the full set leaves no tables dropped, so no truncation note"))))
+
+(deftest ^:parallel table->xml-no-related-notes-test
+ (testing "when every related table fits under the caps, neither a fields-omitted nor a truncated note appears"
+ (let [xml (llm-shape/table->xml {:id 10 :name "orders" :database_id 1 :database_engine "postgres"
+ :database_schema "public"
+ :related_tables [{:id 20 :name "products" :database_schema "public"
+ :related_by {:id 92 :name "product_id"} :fields []}]})]
+ (is (str/includes? xml "<related-table id=\"20\""))
+ (is (not (str/includes? xml "<related-tables-fields-omitted")))
+ (is (not (str/includes? xml "<related-tables-truncated"))))))
+
+(deftest ^:parallel model->xml-related-tables-test
+ (testing "model related-tables render the same fields-omitted + truncated notes as tables"
+ (let [xml (llm-shape/model->xml (assoc base-table-with-related :name "orders_model"))]
+ (is (str/includes? xml "<related-tables-fields-omitted>"))
+ (is (str/includes? xml "<related-table id=\"21\" name=\"people\""))
+ (is (str/includes? xml "<related-tables-truncated surfaced=\"3\" total=\"5\">")))))
+
+(deftest ^:parallel table->xml-related-by-field-id-test
+ (testing (str "a `{:id :name}` `related_by` renders symmetric `related_by_field_name` + `related_by_field_id` "
+ "attributes so the LLM can tell two related-table entries apart when they share an FK name (two FK "
+ "fields with the same name -> the same table)")
+ (let [xml (llm-shape/table->xml
+ {:id 10 :name "orders" :database_id 1 :database_engine "postgres" :database_schema "public"
+ :related_tables [{:id 20 :name "products" :database_schema "public"
+ :related_by {:id 101 :name "product_id"} :fields []}
+ {:id 20 :name "products" :database_schema "public"
+ :related_by {:id 202 :name "product_id"} :fields []}]
+ :related_tables_without_fields [{:id 21 :name "people" :database_schema "public"
+ :related_by {:id 303 :name "user_id"}}
+ {:id 22 :name "reviews" :database_schema "public"
+ :related_by {:id 404 :name "review_id"}}]
+ :related_tables_total 5})]
+ (testing "column-bearing related tables render both the FK field name and id"
+ (is (str/includes? xml "related_by_field_name=\"product_id\" related_by_field_id=\"101\""))
+ (is (str/includes? xml "related_by_field_name=\"product_id\" related_by_field_id=\"202\"")))
+ (testing "identity-only related tables render both the FK field name and id"
+ (is (str/includes? xml "related_by_field_name=\"user_id\" related_by_field_id=\"303\""))
+ (is (str/includes? xml "related_by_field_name=\"review_id\" related_by_field_id=\"404\""))))))