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
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.selmerindex 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.cljindex 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.cljindex 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 inthe 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 closeswith </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.cljindex 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.cljindex 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\""))))))