Skip to content

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

Fix Metabot's query construction error messages (#84813)

Andrei Simionescuf3374514e74a
diff --git a/resources/metabot/prompts/tools/construct_notebook_query.md b/resources/metabot/prompts/tools/construct_notebook_query.md
index 0237812a1c4..680286e57c5 100644
--- a/resources/metabot/prompts/tools/construct_notebook_query.md
+++ b/resources/metabot/prompts/tools/construct_notebook_query.md
@@ -150,7 +150,7 @@ Reference a field on a related table directly — when the source has exactly on
"breakout": [["field", {}, ["Sample Database", null, "PRODUCTS", "CATEGORY"]]]
```
-- **Multiple FKs** to the target → `:ambiguous-fk` lists them. Retry with explicit `{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}` on the field.
+- If the error says the field is reachable through several foreign keys, list the source table's fields and retry with explicit `{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}` on the field to select the intended FK.
- **No FK path** → `:no-fk-path`. Switch to an explicit `joins` entry, or pick a field on the source table.
- Inside an explicit `joins` block, joined-side field refs still need `{"join-alias": ...}` — implicit-join repair does not rewrite those.
- If the FK column lives on a previous stage's output, write `{"source-field-name": "<col>"}` (not auto-filled).
diff --git a/resources/metabot/skills/construct-notebook-query-advanced.md b/resources/metabot/skills/construct-notebook-query-advanced.md
index 416bde0b7a4..5476c85e7f0 100644
--- a/resources/metabot/skills/construct-notebook-query-advanced.md
+++ b/resources/metabot/skills/construct-notebook-query-advanced.md
@@ -64,7 +64,7 @@ Reference a field on a related table directly — when the source has exactly on
"breakout": [["field", {}, ["Sample Database", null, "PRODUCTS", "CATEGORY"]]]
```
-- **Multiple FKs** to the target → `:ambiguous-fk` lists them. Retry with explicit `{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}` on the field.
+- If the error says the field is reachable through several foreign keys, list the source table's fields and retry with explicit `{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}` on the field to select the intended FK.
- **No FK path** → `:no-fk-path`. Switch to an explicit `joins` entry, or pick a field on the source table.
- Inside an explicit `joins` block, joined-side field refs still need `{"join-alias": ...}` — implicit-join repair does not rewrite those.
- If the FK column lives on a previous stage's output, write `{"source-field-name": "<col>"}` (not auto-filled).
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index f282f915fbb..3f5ccad898a 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -2139,7 +2139,7 @@
tbl-name (if (vector? fk)
(pr-str (nth fk 2))
(str target-table-id))]
- (throw (ex-info (tru "Field {0} is on table {1}, which has no foreign key from the source table {2}, so it cannot be reached implicitly. To group or filter by a column from that table, add an explicit `joins:` entry and reference the field using the join alias. If you are aggregating a metric that relates to that table (metrics can join tables that have no foreign key), its dimensions list the exact join clause to paste into `joins:` and the columns it unlocks. Otherwise use a field from the source table."
+ (throw (ex-info (tru "Field {0} is on table {1}, which has no foreign key from the source table {2}, so it cannot be reached implicitly. To group or filter by a column from that table, add an explicit `joins:` entry and reference the field using the join alias. Otherwise use a field from the source table."
(display-portable fk)
tbl-name
(pr-str src-name))
@@ -3240,7 +3240,7 @@
:filter "`filters:`")]
(throw (ex-info
(tru "The query builder''s expression editor rejects a {0} clause in stage {1}: {2}. The query would build but could not be visualized or saved - rewrite the offending clause."
- where stage-idx message)
+ where stage-idx (str/replace message #"\.$" ""))
{:agent-error? true
:error :expression-editor-rejection
:status-code 400
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index d28152411f2..e106835516d 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -818,7 +818,7 @@
`recovery-hint` is absent or has nothing to say about this error."
[e recovery-hint]
(if-let [hint (when recovery-hint (recovery-hint (ex-data e)))]
- (ex-info (str (ex-message e) " " hint) (ex-data e) e)
+ (ex-info (str (ex-message e) "\n" hint) (ex-data e) e)
e))
(defn execute-representations-query
diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.clj
index 58ec1123674..23de130784f 100644
--- a/test/metabase/agent_lib/representations/repair_test.clj
+++ b/test/metabase/agent_lib/representations/repair_test.clj
@@ -2023,7 +2023,11 @@
(let [d (ex-data e)]
(is (= :no-fk-path (:error d)))
(is (true? (:agent-error? d)))
- (is (re-find #"no foreign key" (ex-message e))))))))
+ (is (= (str "Field [\"Sample\" \"PUBLIC\" \"PRODUCTS\" \"CATEGORY\"] is on table \"PRODUCTS\", which has no foreign key "
+ "from the source table \"ORDERS\", so it cannot be reached implicitly. "
+ "To group or filter by a column from that table, add an explicit `joins:` entry "
+ "and reference the field using the join alias. Otherwise use a field from the source table.")
+ (ex-message e))))))))
(deftest ^:parallel implicit-join-ambiguous-fk-test
(testing (str "throws :ambiguous-fk when multiple FKs exist, and does NOT enumerate the "
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index c32c8fe5468..99e20ea9032 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -658,6 +658,22 @@
(is (= :filter (:mode (ex-data e))))
(is (re-find #"OFFSET is not supported in custom filters" (ex-message e))))))))
+(deftest editor-rejection-between-message-test
+ (with-mp-and-stubs!
+ (fn []
+ (let [e (editor-rejection
+ {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "filters" [["between" {} ["field" {} ["Sample" "PUBLIC" "ORDERS" "TOTAL"]]
+ 1 true]]}]})]
+ (is (= :expression-editor-rejection (:error (ex-data e))))
+ (is (= (str "The query builder's expression editor rejects a `filters:` clause in stage 0: "
+ "Types are incompatible. The query would build but could not be visualized or saved "
+ "- rewrite the offending clause.")
+ (ex-message e)))))))
+
(deftest editor-gate-offset-nested-in-aggregation-function-surfaces-error-end-to-end-test
(testing (str "A window function embedded *inside* an aggregation function\n"
"(`sum(offset(...))`) surfaces an :expression-editor-rejection agent-error -\n"
@@ -1189,7 +1205,7 @@
(let [original (ex-info "boom" {:agent-error? true :error :unknown-database})
hinted (#'construct/with-recovery-hint original (constantly "do the thing"))]
(testing "message carries the hint"
- (is (= "boom do the thing" (ex-message hinted))))
+ (is (= "boom\ndo the thing" (ex-message hinted))))
(testing "the original exception is the direct cause (not its cause, which is nil here)"
(is (identical? original (ex-cause hinted)))))))