Skip to content

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

Keep stage-splitting errors with malformed fields (#85172)

Andrei Simionescu8cefe9dfd558
diff --git a/src/metabase/agent_lib/representations.clj b/src/metabase/agent_lib/representations.clj
index b0055913fa4..463f213de0a 100644
--- a/src/metabase/agent_lib/representations.clj
+++ b/src/metabase/agent_lib/representations.clj
@@ -236,6 +236,7 @@
(throw (ex-info (tru "Representations query has an invalid structure.")
{:status-code 400
:error :invalid-representations-query
+ :error-code :invalid-representations-query
:humanized (mu.humanize/humanize error)
:details (pr-str (mu.humanize/humanize error))
:schema ::query
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 0ce033a5642..08faeb70729 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -2120,8 +2120,7 @@
Moving `order-by`, `limit` or `fields` could change the results because those clauses
may refer to columns absent from the aggregation output. Ask the LLM to write two stages
- explicitly in that case. Leave the stage unchanged for validation if `order-by` or `fields`
- can't be read as a sequence."
+ explicitly in that case. Only nil and empty collections count as absent trailing clauses."
[stage]
(let [aggs (get stage "aggregation")
same-stage-uuids (when (vector? aggs) (collect-stage-agg-uuids stage))]
@@ -2134,15 +2133,16 @@
(empty? offending-filters)
[stage]
- (some #(not (seqable? (get stage %))) ["order-by" "fields"])
- [stage]
-
- (or (seq (get stage "order-by"))
- (some? (get stage "limit"))
- (seq (get stage "fields")))
+ (some (fn [clause]
+ (if (coll? clause)
+ (seq clause)
+ (some? clause)))
+ (map stage ["order-by" "limit" "fields"]))
(throw (ex-info
(tru "Detected a post-aggregation filter alongside `order-by:`, `limit:`, or `fields:` in the same stage. MBQL 5 requires the filter in a separate stage, but those trailing clauses cannot be safely relocated — they may reference pre-aggregation columns that don''t survive the split. Please author this as two stages explicitly: stage 0 with `source-table`, `aggregation`, `breakout`, and any pre-aggregation `filters`; stage 1 with the post-aggregation `filters`, plus `order-by` / `limit` / `fields` that reference the aggregation''s output via cross-stage `[\"field\", (empty opts), \"<column-name>\"]` refs.")
{:agent-error? true
+ :status-code 400
+ :error-code :post-agg-filter-with-trailing-clauses
:error :post-agg-filter-with-trailing-clauses
:stage stage}))
@@ -2160,17 +2160,22 @@
(throw (ex-info
(tru "Detected a post-aggregation filter (a filter referencing an aggregation from the same stage). MBQL 5 requires this in a separate stage. Auto-fix is unsafe here — either an aggregation''s output column name cannot be derived (e.g. a `metric` reference or unknown head), or two aggregations in this stage would produce the same column name (e.g. two `sum` aggregations on different fields, which lib disambiguates as `sum` / `sum_2` based on field order). Please refactor to multi-stage manually: put the aggregations in stage 0, and the filter in stage 1 referencing the column via a cross-stage `[\"field\", (empty opts), \"<column-name>\"]` clause. Use an explicit aggregation with a `name` opts override (e.g. `[\"sum\", (opts with key \"name\" → \"sum_total\"), …]`) if you need stable cross-stage names.")
{:agent-error? true
+ :status-code 400
+ :error-code :post-agg-filter-needs-multi-stage
:error :post-agg-filter-needs-multi-stage
:stage stage}))))))))
(defn- split-post-agg-filters*
"Top-level pass: walk every stage in the query, expanding any post-agg-filter stage
in-place to `[stage0 stage1]`. Re-runs are no-ops (idempotent: split stages no longer
- match the trigger)."
+ match the trigger). Split failures carry the unsplit query as `:query` in their ex-data."
[query]
(if-not (and (map? query) (vector? (get query "stages")))
query
- (update query "stages" #(into [] (mapcat split-post-agg-filter-stage) %))))
+ (try
+ (update query "stages" #(into [] (mapcat split-post-agg-filter-stage) %))
+ (catch clojure.lang.ExceptionInfo e
+ (throw (ex-info (ex-message e) (assoc (ex-data e) :query query) e))))))
;;; ============================================================
;;; Pass 3 -- auto-wire `source-field` for implicit joins
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index 61ebcdc0546..8761e7c0188 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -668,18 +668,40 @@
(or agent-error? (tools/pipeline-error-code error))))
(some #(contains? (ex-data %) :toucan2/context-trace) causes)))))))
+(defn- has-valid-trailing-clause?
+ "Return whether a stage has a nonempty trailing clause with a valid portable structure."
+ [stage]
+ (boolean
+ (some (fn [k]
+ (let [clause (get stage k)]
+ (and (mr/validate repr/stage-schema (select-keys stage ["lib/type" k]))
+ (or (integer? clause) (seq clause)))))
+ ["order-by" "limit" "fields"])))
+
(defn- as-agent-input-error
"Return database failures unchanged; wrap other exceptions as agent-input errors.
+ A valid trailing clause preserves split advice, even if another clause is malformed.
+ Otherwise, a structural error in the unsplit query takes precedence.
The wrapper sets `:agent-error?` for tool callers and defaults `:status-code` to 400 for HTTP
callers. Existing status codes are preserved."
[^clojure.lang.ExceptionInfo e]
- (if (database-error? e)
- e
- (let [base (assoc (or (ex-data e) {}) :agent-error? true)
- data (cond-> base
- (nil? (:status-code base)) (assoc :status-code 400))]
- (ex-info (ex-message e) data e))))
+ (let [e (if-let [query (when (and (#{:post-agg-filter-with-trailing-clauses
+ :post-agg-filter-needs-multi-stage} (:error (ex-data e)))
+ (not (has-valid-trailing-clause? (:stage (ex-data e)))))
+ (:query (ex-data e)))]
+ (try
+ (repr/validate-query query)
+ e
+ (catch clojure.lang.ExceptionInfo validation-error
+ validation-error))
+ e)]
+ (if (database-error? e)
+ e
+ (let [base (assoc (or (ex-data e) {}) :agent-error? true)
+ data (cond-> base
+ (nil? (:status-code base)) (assoc :status-code 400))]
+ (ex-info (ex-message e) data e)))))
(defn- not-runnable-problem
"What is wrong at a Malli schema `error`, phrased for the LLM, or nil when there is nothing to add
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 3642dbdc06c..15a01b39084 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -455,8 +455,26 @@
(update (orders-query) :stages conj [["count" {}]])})
endpoint ["agent/v2/construct-query" "agent/v2/query"]]
(testing (str endpoint ", " label)
- (is (=? {:error "invalid-representations-query"}
- (mt/user-http-request :rasta :post 400 endpoint {:query query})))))))
+ (let [response (mt/user-http-request :rasta :post 400 endpoint {:query query})]
+ (is (=? {:error "invalid-representations-query"
+ :error-code "invalid-representations-query"
+ :message #"(?s)Representations query has an invalid structure\..*"}
+ response))
+ (is (= #{:error :error-code :message :humanized :details} (set (keys response)))))))))
+
+(deftest construct-query-post-aggregation-errors-test
+ (doseq [[error query] [["post-agg-filter-with-trailing-clauses"
+ (orders-query :aggregation [["count" {}]]
+ :filters [[">" {} ["aggregation" {} 0] 1]]
+ :limit 5)]
+ ["post-agg-filter-needs-multi-stage"
+ (orders-query :aggregation [["count" {}] ["count" {}]]
+ :filters [[">" {} ["aggregation" {} 0] 1]])]]
+ endpoint ["agent/v2/construct-query" "agent/v2/query"]]
+ (testing (str endpoint ", " error)
+ (let [response (mt/user-http-request :rasta :post 400 endpoint {:query query})]
+ (is (=? {:error error :error-code error :message #".*MBQL 5 requires.*"} response))
+ (is (= #{:error :error-code :message} (set (keys response))))))))
(deftest construct-query-ignores-legacy-envelope-test
(testing (str "Legacy `source_entity` / `referenced_entities` envelope from the pre-repr program API "
diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.clj
index 131c32a10b4..55b49aa5343 100644
--- a/test/metabase/agent_lib/representations/repair_test.clj
+++ b/test/metabase/agent_lib/representations/repair_test.clj
@@ -3171,6 +3171,49 @@
(catch clojure.lang.ExceptionInfo e
(is (= :post-agg-filter-with-trailing-clauses (:error (ex-data e)))))))))
+(deftest ^:parallel split-post-agg-refuses-present-trailing-clauses-test
+ (doseq [trailing-clauses (concat
+ (for [clause ["order-by" "limit" "fields"]
+ value [42 false "" "TOTAL"]]
+ {clause value})
+ [{"fields" 42, "order-by" [["desc" {} ["aggregation" {} 0]]]}
+ {"fields" 42, "limit" 5}
+ {"order-by" 42, "fields" [["field" {} ["Sample" "PUBLIC" "ORDERS" "PRODUCT_ID"]]]}
+ {"order-by" 42, "limit" 5}
+ {"order-by" 42, "fields" 42, "limit" 5}])]
+ (testing (pr-str trailing-clauses)
+ (let [stage (merge {"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "aggregation" [["count" {}]]
+ "filters" [[">" {} ["aggregation" {} 0] 10]]}
+ trailing-clauses)]
+ (try
+ (repair/repair trivial-mp {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [stage]})
+ (is false "Expected advice to split the stage")
+ (catch clojure.lang.ExceptionInfo e
+ (is (=? {:agent-error? true
+ :error :post-agg-filter-with-trailing-clauses}
+ (ex-data e)))
+ (is (re-find #"Please author this as two stages explicitly" (ex-message e)))))))))
+
+(deftest ^:parallel split-post-agg-with-absent-trailing-clauses-test
+ (doseq [clause ["order-by" "limit" "fields"]
+ value [nil [] {}]]
+ (testing (pr-str {clause value})
+ (let [query {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "aggregation" [["count" {}]]
+ "filters" [[">" {} ["aggregation" {} 0] 10]]
+ clause value}]}
+ stages (get (repair/repair trivial-mp query) "stages")]
+ (is (= 2 (count stages)))
+ (is (= [[">" {} ["field" {} "count"] 10]]
+ (get-in stages [1 "filters"])))))))
+
(deftest ^:parallel split-post-agg-refuses-when-order-by-is-a-string-test
(testing "a string `order-by` with a post-aggregation filter gets advice to split the stage"
(is (=? {:error :post-agg-filter-with-trailing-clauses}
@@ -3364,8 +3407,7 @@
(deftest ^:parallel malformed-clauses-reach-validation-test
(testing "repair leaves malformed stages and clauses for validation"
;; ORDERS has to resolve for the cross-stage pass to reach a later stage
- (let [orders {"lib/type" "mbql.stage/mbql" "source-table" ["Sample" "PUBLIC" "ORDERS"]}
- post-agg (assoc orders "aggregation" [["count" {}]] "filters" [[">" {} ["aggregation" {} 0] 1]])]
+ (let [orders {"lib/type" "mbql.stage/mbql" "source-table" ["Sample" "PUBLIC" "ORDERS"]}]
(doseq [[label stages] {"a number as `aggregation`"
[(assoc orders "aggregation" 42)]
"an empty aggregation clause used in `order-by`"
@@ -3374,10 +3416,10 @@
[(assoc orders "joins" 42)]
"a join-alias reference with a number as `joins`"
[(assoc orders "joins" 42 "breakout" [["field" {"join-alias" "P"} "CATEGORY"]])]
- "a post-aggregation filter with a number as `order-by`"
- [(assoc post-agg "order-by" 42)]
- "a post-aggregation filter with a number as `fields`"
- [(assoc post-agg "fields" 42)]
+ "a number as `order-by`"
+ [(assoc orders "order-by" 42)]
+ "a number as `fields`"
+ [(assoc orders "fields" 42)]
"a number as a later stage" [orders 42]
"a string as a later stage" [orders "ORDERS"]
"true as a later stage" [orders true]
diff --git a/test/metabase/mcp/v2/tools/query_test.clj b/test/metabase/mcp/v2/tools/query_test.clj
index 801ee8ce81e..e545f54a571 100644
--- a/test/metabase/mcp/v2/tools/query_test.clj
+++ b/test/metabase/mcp/v2/tools/query_test.clj
@@ -1000,6 +1000,10 @@
[(assoc post-agg :order-by 42)]]
["a post-aggregation filter with a number as `fields`" "[0] \"fields\":"
[(assoc post-agg :fields 42)]]
+ ["a post-aggregation filter with a string as `limit`" "[0] \"limit\":"
+ [(assoc post-agg :limit "x")]]
+ ["a later post-aggregation filter with a number as `fields`" "[1] \"fields\":"
+ [orders (assoc (dissoc post-agg :source-table) :fields 42)]]
["a number as a later stage" "[1]" [orders 42]]
["an aggregation list as a later stage" "[1]" [orders [["count" {}]]]]]]
(testing label
@@ -1008,6 +1012,17 @@
(str "\"Representations query has an invalid structure.\" "
"Invalid at \"stages\": " path " "))))))))
+(deftest ^:parallel post-aggregation-errors-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (doseq [clauses [{:aggregation [["count"]]
+ :filters [[">" ["aggregation" 0] 1]]
+ :limit 5}
+ {:aggregation [["count" {}] ["count" {}]]
+ :filters [[">" {} ["aggregation" {} 0] 1]]}]]
+ (is (re-find #"MBQL 5 requires"
+ (error-text (registry/call-tool execute-scope (str (random-uuid)) "execute_query"
+ {:query (numeric-orders-query clauses)})))))))
+
;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
(deftest repair-forgiven-shortcuts-still-execute-test
(testing "GHY-4313: the shortcuts the repair layer exists to forgive are not schema failures"
diff --git a/test/metabase/metabot/tools_test.clj b/test/metabase/metabot/tools_test.clj
index ffe00d8a1f9..aff65e2f664 100644
--- a/test/metabase/metabot/tools_test.clj
+++ b/test/metabase/metabot/tools_test.clj
@@ -329,6 +329,32 @@
:title "Orders"
:description "Orders by count."})))))))))
+(deftest construct-notebook-query-tool-post-aggregation-errors-test
+ (let [source [(t2/select-one-fn :name :model/Database (mt/id)) "PUBLIC" "ORDERS"]]
+ (mt/with-current-user (mt/user->id :rasta)
+ (doseq [[error cases] {:post-agg-filter-with-trailing-clauses
+ [{:limit 5}
+ {:fields 42 :order-by [["desc" {} ["aggregation" {} 0]]]}
+ {:fields 42 :limit 5}
+ {:order-by 42 :fields [["field" {} (conj source "PRODUCT_ID")]]}
+ {:order-by 42 :limit 5}
+ {:order-by 42 :fields 42 :limit 5}]
+ :post-agg-filter-needs-multi-stage
+ [{:aggregation [["count" {}] ["count" {}]]}]}
+ clauses cases]
+ (testing (pr-str clauses)
+ (let [stage (merge {:lib/type "mbql.stage/mbql"
+ :source-table source
+ :aggregation [["count" {}]]
+ :filters [[">" {} ["aggregation" {} 0] 1]]}
+ clauses)]
+ (is (=? {:class :recoverable
+ :code (keyword "metabase.metabot.tools.recoverable.pipeline" (name error))
+ :text #".*MBQL 5 requires.*"}
+ (test-util/tool-failure agent-tools/construct-notebook-query-tool
+ {:query {:lib/type "mbql/query" :stages [stage]}
+ :title "Orders" :description "Orders by count."})))))))))
+
(deftest ->entries-test
(testing "an entry carries what the adapters and the system message read"
(let [entries (agent-tools/->entries [#'agent-tools/create-sql-query-tool