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
[metabot] add repr for measures and segments (#71656)
Oleksandr Solovyov9c23e9d35a38
diff --git a/resources/metabot/prompts/llm_representations.selmer b/resources/metabot/prompts/llm_representations.selmerindex 0232a10fec4..76125eda88f 100644--- a/resources/metabot/prompts/llm_representations.selmer+++ b/resources/metabot/prompts/llm_representations.selmer@@ -1,3 +1,17 @@+{% if is_measure %}+<measure measure_id="{{measure_id}}" name="{{measure_name}}" display_name="{{measure_display_name}}">{% if measure_description %}+{{measure_description}}{% endif %}{% if measure_definition_description %}+Definition: {{measure_definition_description}}{% endif %}{% if measure_definition %}+<definition>{{measure_definition}}</definition>{% endif %}+</measure>+{% endif %}+{% if is_segment %}+<segment segment_id="{{segment_id}}" name="{{segment_name}}" display_name="{{segment_display_name}}">{% if segment_description %}+{{segment_description}}{% endif %}{% if segment_definition_description %}+Definition: {{segment_definition_description}}{% endif %}{% if segment_definition %}+<definition>{{segment_definition}}</definition>{% endif %}+</segment>+{% endif %}{% if is_field %}<field id="{{field_id}}" name="{{field_name_quoted|safe}}" display_name="{{field_display_name}}" type="{{field_base_type}}" database_type="{{field_database_type}}">{% if field_description %}## Description@@ -55,6 +69,24 @@ Foreign key fields from related tables. Usage patterns:{{table_related_tables_xml|safe}}{% endif %}+{% if table_measures_xml %}++### Measures (Pre-defined Aggregation Formulas)++The following pre-defined MEASURES (NOT metrics!) are available for this table.+These are aggregation formulas defined on this table. Use them instead of creating custom aggregations when available.++{{table_measures_xml|safe}}+{% endif %}+{% if table_segments_xml %}++### Segments (Pre-defined Filter Conditions)++The following pre-defined SEGMENTS are available for this table.+These are business-defined filter conditions. Use them instead of creating custom filters when available.++{{table_segments_xml|safe}}+{% endif %}Before using any field in comparisons, filters, or conditions, you should check their metadata and sample values first, using the uri `metabase://table/{{table_id}}/fields/{field_id}`.This will help avoid errors due to unexpected data types or formats.@@ -82,6 +114,24 @@ Foreign key fields from related tables. Usage patterns:{{model_related_tables_xml|safe}}{% endif %}+{% if model_measures_xml %}++### Measures (Pre-defined Aggregation Formulas)++The following pre-defined MEASURES (NOT metrics!) are available for this model.+These are aggregation formulas defined on this model. Use them instead of creating custom aggregations when available.++{{model_measures_xml|safe}}+{% endif %}+{% if model_segments_xml %}++### Segments (Pre-defined Filter Conditions)++The following pre-defined SEGMENTS are available for this model.+These are business-defined filter conditions. Use them instead of creating custom filters when available.++{{model_segments_xml|safe}}+{% endif %}Before using any field in comparisons, filters, or conditions, you should check their metadata and sample values first, using the uri `metabase://model/{{model_id}}/fields/{field_id}`.This will help avoid errors due to unexpected data types or formats.</model>diff --git a/src/metabase/metabot/agent/user_context.clj b/src/metabase/metabot/agent/user_context.cljindex 78137fcdd97..5c2bdd2866e 100644--- a/src/metabase/metabot/agent/user_context.clj+++ b/src/metabase/metabot/agent/user_context.clj@@ -141,7 +141,9 @@"The user is currently looking at the rows of a table:"#(entity-details/get-table-details {:table-id (:id entity):with-field-values? false- :with-metrics? false})+ :with-metrics? false+ :with-measures? true+ :with-segments? true})llm-rep/table->xml))(defmethod format-entity "model"@@ -150,7 +152,9 @@"The user is currently looking at the rows of a model:"#(entity-details/get-table-details {:model-id (:id entity):with-field-values? false- :with-metrics? false})+ :with-metrics? false+ :with-measures? true+ :with-segments? true})llm-rep/model->xml))(defn- format-chart-config-idsdiff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.cljindex 666c111bddf..113f71028ba 100644--- a/src/metabase/metabot/tools/construct.clj+++ b/src/metabase/metabot/tools/construct.clj@@ -202,7 +202,8 @@[filter](let [normalized (normalize-ai-args filter)filter-type (:filter-type normalized)- normalized (assoc normalized :operation (normalize-construct-operation (:operation normalized)))]+ normalized (cond-> normalized+ (:operation normalized) (update :operation normalize-construct-operation))](case filter-type:multi-value (-> normalized(dissoc :filter-type :value)diff --git a/src/metabase/metabot/tools/entity_details.clj b/src/metabase/metabot/tools/entity_details.cljindex 74fff5136f0..a5247aec92e 100644--- a/src/metabase/metabot/tools/entity_details.clj+++ b/src/metabase/metabot/tools/entity_details.clj@@ -19,9 +19,21 @@(set! *warn-on-reflection* true)(defn- convert-measure-or-segment- "Convert a measure or segment metadata object to the format expected by the API."- [metadata]- (select-keys metadata [:id :name :display-name :description :definition]))+ "Convert a measure or segment metadata object to the format expected by the API.+ `definition-key` is `:aggregation` for measures and `:filters` for segments."+ [metadata definition-key]+ (let [definition (:definition metadata)]+ (-> (select-keys metadata [:id :name :display-name :description])+ (assoc :definition-description+ (when definition+ (try+ (lib/describe-top-level-key definition definition-key)+ (catch Exception _ nil))))+ (assoc :definition+ (when definition+ (try+ (lib/prepare-for-serialization definition)+ (catch Exception _ nil)))))))(defn verified-review?"Return true if the most recent ModerationReview for the given item id/type is verified."@@ -149,7 +161,7 @@with-segments?(assoc :segments (if-let [segments (lib/available-segments metric-query)]- (mapv convert-measure-or-segment segments)+ (mapv #(convert-measure-or-segment % :filters) segments)[]))))))(defn- convert-metric@@ -211,10 +223,10 @@(not-empty (mapv #(convert-metric % mp options)(lib/available-metrics table-query)))):measures (when with-measures?- (not-empty (mapv convert-measure-or-segment+ (not-empty (mapv #(convert-measure-or-segment % :aggregation)(lib/available-measures table-query)))):segments (when with-segments?- (not-empty (mapv convert-measure-or-segment+ (not-empty (mapv #(convert-measure-or-segment % :filters)(lib/available-segments table-query))))))))))(defn related-tables@@ -305,10 +317,10 @@(not-empty (mapv #(convert-metric % metadata-provider options)(lib/available-metrics card-query)))):measures (when with-measures?- (not-empty (mapv convert-measure-or-segment+ (not-empty (mapv #(convert-measure-or-segment % :aggregation)(lib/available-measures card-query)))):segments (when with-segments?- (not-empty (mapv convert-measure-or-segment+ (not-empty (mapv #(convert-measure-or-segment % :filters)(lib/available-segments card-query)))))))))(defn cards-detailsdiff --git a/src/metabase/metabot/tools/metadata.clj b/src/metabase/metabot/tools/metadata.cljindex c6e277136dc..66ce1fc1c84 100644--- a/src/metabase/metabot/tools/metadata.clj+++ b/src/metabase/metabot/tools/metadata.clj@@ -56,8 +56,8 @@:with-related-tables? false:with-metrics? false:with-default-temporal-breakout? false- :with-measures? false- :with-segments? false}))+ :with-measures? true+ :with-segments? true}))%)table-ids)model-results (mapv #(safe-fetch@@ -69,8 +69,8 @@:with-related-tables? false:with-metrics? false:with-default-temporal-breakout? false- :with-measures? false- :with-segments? false}))+ :with-measures? true+ :with-segments? true}))%)model-ids)metric-results (mapv #(safe-fetch@@ -80,7 +80,7 @@:with-default-temporal-breakout? false:with-field-values? false:with-queryable-dimensions? false- :with-segments? false}))+ :with-segments? true}))%)metric-ids)tables (->> table-results (keep :value) vec)@@ -139,7 +139,9 @@[_args :- [:maybe [:map {:closed true}]]](add-output(entity-details-tools/answer-sources {:metabot-id shared/*metabot-id*- :with-field-values? false})+ :with-field-values? false+ :with-measures? true+ :with-segments? true})format-answer-sources-output))(def ^:private list-available-fields-schemadiff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.cljindex 39fe38afb97..ca715139281 100644--- a/src/metabase/metabot/tools/resources.clj+++ b/src/metabase/metabot/tools/resources.clj@@ -80,14 +80,18 @@(entity-details/get-table-details {:table-id table-id:with-fields true:with-field-values false- :with-related-tables false})+ :with-related-tables false+ :with-measures? true+ :with-segments? true});; metabase://table/123(nil? sub-resource)(entity-details/get-table-details {:table-id table-id:with-fields false:with-field-values false- :with-related-tables false})+ :with-related-tables false+ :with-measures? true+ :with-segments? true}):else(throw (ex-info (str "Unsupported sub-resource '" sub-resource "' for table. Supported: fields")@@ -110,14 +114,18 @@(entity-details/get-table-details {:model-id model-id:with-fields true:with-field-values false- :with-related-tables false})+ :with-related-tables false+ :with-measures? true+ :with-segments? true});; metabase://model/123(nil? sub-resource)(entity-details/get-table-details {:model-id model-id:with-fields false:with-field-values false- :with-related-tables false})+ :with-related-tables false+ :with-measures? true+ :with-segments? true}):else(throw (ex-info (str "Unsupported sub-resource '" sub-resource "' for model. Supported: fields")diff --git a/src/metabase/metabot/tools/shared/llm_representations.clj b/src/metabase/metabot/tools/shared/llm_representations.cljindex 19c0ccdb278..f3e51438374 100644--- a/src/metabase/metabot/tools/shared/llm_representations.clj+++ b/src/metabase/metabot/tools/shared/llm_representations.clj@@ -38,7 +38,9 @@(defn- type-flags"Build template flags for a single representation type."[type]- {:is_field (= type :field)+ {:is_measure (= type :measure)+ :is_segment (= type :segment)+ :is_field (= type :field):is_collection (= type :collection):is_related_table (= type :related_table):is_metric (= type :metric)@@ -120,6 +122,30 @@:collection_description description:collection_authority_level authority_level}))+(defn measure->xml+ "Format a measure for LLM consumption."+ [{:keys [id name display-name description definition definition-description]}]+ (render-llm-template+ :measure+ {:measure_id (str id)+ :measure_name (or name "")+ :measure_display_name (or display-name name "")+ :measure_description description+ :measure_definition (when definition (pr-str definition))+ :measure_definition_description definition-description}))++(defn segment->xml+ "Format a segment for LLM consumption."+ [{:keys [id name display-name description definition definition-description]}]+ (render-llm-template+ :segment+ {:segment_id (str id)+ :segment_name (or name "")+ :segment_display_name (or display-name name "")+ :segment_description description+ :segment_definition (when definition (pr-str definition))+ :segment_definition_description definition-description}))+(defn- related-table->xml"Format a related table for LLM consumption."[{:keys [id name related_by fully_qualified_name fields]}]@@ -158,7 +184,7 @@"Format table for LLM consumption.Matches Python Table.get_llm_representation exactly."[{:keys [id name database_id database_engine database_schema- description fields related_tables]}]+ description fields related_tables measures segments]}](let [fqn (fully-qualified-name database_schema name)](render-llm-template:table@@ -171,7 +197,11 @@: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)))})))+ (str/join "" (map related-table->xml related_tables)))+ :table_measures_xml (when (seq measures)+ (str/join "\n" (map measure->xml measures)))+ :table_segments_xml (when (seq segments)+ (str/join "\n" (map segment->xml segments)))})))(defn- model-fully-qualified-name"Get fully qualified name for a model (uses slug format)."@@ -189,7 +219,7 @@Matches Python Model.get_llm_representation exactly.Note: Python uses <metabase-model> tag but closes with </model>."[{:keys [id name description verified fields database_id database_engine- related_tables]}]+ related_tables measures segments]}](let [fqn (model-fully-qualified-name id name)](render-llm-template:model@@ -203,7 +233,11 @@: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)))})))+ (str/join "\n" (map related-table->xml related_tables)))+ :model_measures_xml (when (seq measures)+ (str/join "\n" (map measure->xml measures)))+ :model_segments_xml (when (seq segments)+ (str/join "\n" (map segment->xml segments)))})))(defn- format-markdown-row"Format a sequence of values as a markdown table row."diff --git a/test/metabase/metabot/agent/user_context_test.clj b/test/metabase/metabot/agent/user_context_test.cljindex 11aee7c7e26..c5e6fb96b83 100644--- a/test/metabase/metabot/agent/user_context_test.clj+++ b/test/metabase/metabot/agent/user_context_test.clj@@ -321,6 +321,77 @@(is (= "" (:viewing_context result)))(is (= "" (:recent_views result))))))+(deftest format-entity-includes-measures-and-segments-test+ (testing "table viewing context includes measures and segments when present"+ (with-redefs [entity-details/get-table-details+ (fn [{:keys [table-id with-measures? with-segments?]}]+ ;; Verify that with-measures? and with-segments? are requested+ (is (true? with-measures?) "should request measures")+ (is (true? with-segments?) "should request segments")+ {:structured-output+ {:id table-id+ :type :table+ :name "int_shopify_order_facts"+ :database_id 2+ :database_engine "postgres"+ :database_schema "shopify_enriched"+ :description "Order facts with enriched data"+ :fields [{:field_id "t10-1" :name "order_id" :database_type "INTEGER"}]+ :measures [{:id 1 :name "avg_order_value" :display-name "Average Order Value"+ :description "Average value of all orders"}]+ :segments [{:id 2 :name "q4_orders" :display-name "Q4 Orders"+ :description "Orders placed in Q4"}]}})]+ (let [result (user-context/format-viewing-context+ {:user_is_viewing [{:type "table" :id 10}]})]+ (is (re-find #"table" result))+ (is (re-find #"int_shopify_order_facts" result))+ (is (re-find #"Measures \(Pre-defined Aggregation Formulas\)" result))+ (is (re-find #"Average Order Value" result))+ (is (re-find #"Segments \(Pre-defined Filter Conditions\)" result))+ (is (re-find #"Q4 Orders" result)))))++ (testing "model viewing context includes measures and segments when present"+ (with-redefs [entity-details/get-table-details+ (fn [{:keys [model-id with-measures? with-segments?]}]+ (is (true? with-measures?) "should request measures for model")+ (is (true? with-segments?) "should request segments for model")+ {:structured-output+ {:id model-id+ :type :model+ :name "Revenue Model"+ :database_id 2+ :database_engine "postgres"+ :description "Revenue model"+ :measures [{:id 3 :name "total_revenue" :display-name "Total Revenue"+ :description "Sum of all revenue"}]+ :segments [{:id 4 :name "enterprise" :display-name "Enterprise Accounts"+ :description "Enterprise-tier customers"}]}})]+ (let [result (user-context/format-viewing-context+ {:user_is_viewing [{:type "model" :id 20}]})]+ (is (re-find #"model" result))+ (is (re-find #"Revenue Model" result))+ (is (re-find #"Measures" result))+ (is (re-find #"Total Revenue" result))+ (is (re-find #"Segments" result))+ (is (re-find #"Enterprise Accounts" result)))))++ (testing "table viewing context omits measures/segments sections when none exist"+ (with-redefs [entity-details/get-table-details+ (fn [{:keys [table-id]}]+ {:structured-output+ {:id table-id+ :type :table+ :name "plain_table"+ :database_id 1+ :database_engine "h2"+ :description "A plain table"+ :fields [{:field_id "t1-1" :name "id" :database_type "INTEGER"}]}})]+ (let [result (user-context/format-viewing-context+ {:user_is_viewing [{:type "table" :id 1}]})]+ (is (re-find #"plain_table" result))+ (is (not (re-find #"Measures" result)))+ (is (not (re-find #"Segments" result)))))))+(deftest format-entity-fetches-details-from-db-test(testing "question with only type+id fetches name and description from DB"(mt/with-test-user :rastadiff --git a/test/metabase/metabot/tools/entity_details_test.clj b/test/metabase/metabot/tools/entity_details_test.cljindex d351d90f37e..00152e9b3e0 100644--- a/test/metabase/metabot/tools/entity_details_test.clj+++ b/test/metabase/metabot/tools/entity_details_test.clj@@ -199,6 +199,7 @@(let [measure (first measures)](is (= measure-id (:id measure)))(is (= "Total Revenue" (:name measure)))+ (is (string? (:definition-description measure)))(is (map? (:definition measure)))))))))))(deftest get-table-details-with-segments-test@@ -223,6 +224,7 @@(let [segment (first segments)](is (= segment-id (:id segment)))(is (= "High Value Orders" (:name segment)))+ (is (string? (:definition-description segment)))(is (map? (:definition segment)))))))))))(deftest get-table-details-measures-scoped-to-table-testdiff --git a/test/metabase/metabot/tools/shared/llm_representations_test.clj b/test/metabase/metabot/tools/shared/llm_representations_test.cljindex b852093b38d..89ed138f625 100644--- a/test/metabase/metabot/tools/shared/llm_representations_test.clj+++ b/test/metabase/metabot/tools/shared/llm_representations_test.clj@@ -85,6 +85,73 @@(is (str/includes? xml "is_verified=\"false\""))(is (not (str/includes? xml "### Dimensions"))))))+(deftest measure->xml-test+ (testing "formats measure with all attributes"+ (let [measure {:id 1+ :name "total_revenue"+ :display-name "Total Revenue"+ :description "Sum of all revenue"+ :definition {:database 1 :type :query :query {:source-table 5 :aggregation [[:sum [:field 10 nil]]]}}+ :definition-description "Sum of Price"}+ xml (llm-rep/measure->xml measure)]+ (is (str/starts-with? xml "<measure"))+ (is (str/includes? xml "measure_id=\"1\""))+ (is (str/includes? xml "name=\"total_revenue\""))+ (is (str/includes? xml "display_name=\"Total Revenue\""))+ (is (str/includes? xml "Sum of all revenue"))+ (is (str/includes? xml "Definition: Sum of Price"))+ (is (str/includes? xml "<definition>"))+ (is (str/includes? xml ":source-table 5"))+ (is (str/ends-with? (str/trim xml) "</measure>"))))++ (testing "handles measure without description or definition"+ (let [measure {:id 2 :name "count_orders"}+ xml (llm-rep/measure->xml measure)]+ (is (str/includes? xml "measure_id=\"2\""))+ (is (str/includes? xml "name=\"count_orders\""))+ (is (str/includes? xml "display_name=\"count_orders\""))+ (is (not (str/includes? xml "<definition>")))+ (is (not (str/includes? xml "Definition:")))+ (is (str/ends-with? (str/trim xml) "</measure>"))))++ (testing "uses name as display_name fallback"+ (let [measure {:id 3 :name "avg_price" :display-name nil}+ xml (llm-rep/measure->xml measure)]+ (is (str/includes? xml "display_name=\"avg_price\"")))))++(deftest segment->xml-test+ (testing "formats segment with all attributes"+ (let [segment {:id 1+ :name "active_customers"+ :display-name "Active Customers"+ :description "Customers who made a purchase in the last 30 days"+ :definition {:database 1 :type :query :query {:source-table 5 :filter [:> [:field 10 nil] 0]}}+ :definition-description "Price is greater than 0"}+ xml (llm-rep/segment->xml segment)]+ (is (str/starts-with? xml "<segment"))+ (is (str/includes? xml "segment_id=\"1\""))+ (is (str/includes? xml "name=\"active_customers\""))+ (is (str/includes? xml "display_name=\"Active Customers\""))+ (is (str/includes? xml "Customers who made a purchase in the last 30 days"))+ (is (str/includes? xml "Definition: Price is greater than 0"))+ (is (str/includes? xml "<definition>"))+ (is (str/includes? xml ":source-table 5"))+ (is (str/ends-with? (str/trim xml) "</segment>"))))++ (testing "handles segment without description or definition-description"+ (let [segment {:id 2 :name "new_users"}+ xml (llm-rep/segment->xml segment)]+ (is (str/includes? xml "segment_id=\"2\""))+ (is (str/includes? xml "name=\"new_users\""))+ (is (not (str/includes? xml "<definition>")))+ (is (not (str/includes? xml "Definition:")))+ (is (str/ends-with? (str/trim xml) "</segment>"))))++ (testing "uses name as display_name fallback"+ (let [segment {:id 3 :name "q4_orders" :display-name nil}+ xml (llm-rep/segment->xml segment)]+ (is (str/includes? xml "display_name=\"q4_orders\"")))))+(deftest table->xml-test(testing "formats table with all attributes matching Python"(let [table {:id 10@@ -111,7 +178,33 @@(is (str/includes? xml "Foreign key fields from related tables"))(is (str/includes? xml "<related-table"))(is (str/includes? xml "metabase://table/10/fields/{field_id}"))- (is (str/ends-with? (str/trim xml) "</table>")))))+ (is (str/ends-with? (str/trim xml) "</table>"))))++ (testing "includes measures and segments when present"+ (let [table {:id 10+ :name "order_facts"+ :database_id 1+ :database_engine "postgres"+ :database_schema "shopify"+ :description "Order facts table"+ :measures [{:id 1 :name "avg_order_value" :display-name "Average Order Value"+ :description "Average value of orders"}]+ :segments [{:id 2 :name "q4_orders" :display-name "Q4 Orders"+ :description "Orders placed in Q4"}]}+ xml (llm-rep/table->xml table)]+ (is (str/includes? xml "### Measures (Pre-defined Aggregation Formulas)"))+ (is (str/includes? xml "MEASURES (NOT metrics!)"))+ (is (str/includes? xml "<measure measure_id=\"1\""))+ (is (str/includes? xml "Average Order Value"))+ (is (str/includes? xml "### Segments (Pre-defined Filter Conditions)"))+ (is (str/includes? xml "<segment segment_id=\"2\""))+ (is (str/includes? xml "Q4 Orders"))))++ (testing "omits measures and segments sections when empty"+ (let [table {:id 10 :name "users" :database_id 1 :database_engine "postgres"}+ xml (llm-rep/table->xml table)]+ (is (not (str/includes? xml "### Measures")))+ (is (not (str/includes? xml "### Segments"))))))(deftest model->xml-test(testing "formats model with all attributes matching Python"@@ -136,7 +229,32 @@(is (str/includes? xml "The following fields are available in this model"))(is (str/includes? xml "metabase://model/5/fields/{field_id}"));; Python closes with </model>- (is (str/ends-with? (str/trim xml) "</model>")))))+ (is (str/ends-with? (str/trim xml) "</model>"))))++ (testing "includes measures and segments when present"+ (let [model {:id 5+ :name "Sales Model"+ :database_id 1+ :database_engine "postgres"+ :description "Sales data"+ :measures [{:id 1 :name "total_net_revenue" :display-name "Total Net Revenue"+ :description "Net revenue after returns"}]+ :segments [{:id 1 :name "new_customers" :display-name "New Customers"+ :description "First-time buyers"}]}+ xml (llm-rep/model->xml model)]+ (is (str/includes? xml "### Measures (Pre-defined Aggregation Formulas)"))+ (is (str/includes? xml "MEASURES (NOT metrics!)"))+ (is (str/includes? xml "<measure measure_id=\"1\""))+ (is (str/includes? xml "Total Net Revenue"))+ (is (str/includes? xml "### Segments (Pre-defined Filter Conditions)"))+ (is (str/includes? xml "<segment segment_id=\"1\""))+ (is (str/includes? xml "New Customers"))))++ (testing "omits measures and segments sections when empty"+ (let [model {:id 5 :name "Empty Model" :database_id 1 :database_engine "postgres"}+ xml (llm-rep/model->xml model)]+ (is (not (str/includes? xml "### Measures")))+ (is (not (str/includes? xml "### Segments"))))))(deftest query->xml-test(testing "formats query result matching Python"