Skip to content

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

Merge misplaced trailing options-map on fixed-arity MBQL clauses (#74926)

Mihael Konjević0b269fb4b4e4
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 2a87e3a32d1..e76c7d8d8dc 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -32,11 +32,13 @@
[metabase.agent-lib.representations.resolve :as repr.resolve]
[metabase.lib.core :as lib]
[metabase.lib.metadata.protocols :as lib.metadata.protocols]
+ [metabase.lib.schema.mbql-clause :as mbql-clause]
[metabase.models.serialization.resolve :as resolve]
[metabase.models.serialization.resolve.mp :as resolve.mp]
[metabase.util :as u]
[metabase.util.i18n :refer [tru]]
- [metabase.util.log :as log]))
+ [metabase.util.log :as log]
+ [metabase.util.malli.registry :as mr]))
(set! *warn-on-reflection* true)
@@ -339,6 +341,107 @@
node))
form))
+;;; ============================================================
+;;; Pass 1.88 -- merge a trailing extra options-map into the position-1 options.
+;;;
+;;; LLMs sometimes place a clause's options at the END of the vector instead of
+;;; (or in addition to) position 1. The canonical example:
+;;;
+;;; ["time-interval" {} <expr> -1 "month" {"include-current" true}]
+;;;
+;;; The schema for `time-interval` is a strict `:tuple` of 5 elements with options
+;;; at position 1 (the `include-current` flag lives there). The 6th element above
+;;; is misplaced options - the LLM read the prompt's "Opts may set
+;;; {include-current: true}" hint and put it after the args.
+;;;
+;;; We handle this generically across every fixed-arity tuple clause registered with
+;;; `metabase.lib.schema.mbql-clause`. The expected-element-count table is derived
+;;; once at namespace load from [[mbql-clause/registered-tags]] and selecting
+;;; schemas whose head form is `:tuple`. Variadic clauses (`and`, `or`, `=`, `in`,
+;;; `case`, `coalesce`, ...) use `:catn` / `:repeat` and are correctly excluded -
+;;; their arity isn't fixed, so a trailing map could be a legitimate arg.
+;;;
+;;; Repair condition (all four required):
+;;; * clause-shaped vector (string head, not a map-entry, not an FK path);
+;;; * head matches a known fixed-arity clause;
+;;; * count is exactly `expected + 1` (count off by >=2 is too ambiguous - the
+;;; schema validator will reject it with a friendly tuple-shape error);
+;;; * position 1 is a map AND last element is a map.
+;;;
+;;; Repair action: merge the trailing map into position-1 options, with trailing
+;;; keys winning on conflict (the trailing map is where the LLM wrote content;
+;;; position 1 is typically `{}`). Then drop the trailing element.
+;;;
+;;; Idempotent by construction: a repaired clause has the canonical expected count,
+;;; so the predicate fails on a second pass.
+;;; ============================================================
+
+(defn- tuple-clause-element-count
+ "If `schema-form` is a `:tuple` schema (the shape [[mbql-clause/tuple-clause-schema]]
+ produces), return the expected number of elements in matching tuples (head + opts + args).
+ Returns `nil` for non-tuple schemas (`:catn` / `:repeat` variadic clauses) and for
+ malformed inputs."
+ [schema-form]
+ (when (and (vector? schema-form)
+ (= :tuple (first schema-form)))
+ (let [after-head (next schema-form)
+ ;; Malli optionally puts a properties map at index 1; skip it if present.
+ child-schemas (if (map? (first after-head))
+ (next after-head)
+ after-head)]
+ (count child-schemas))))
+
+(def ^:private fixed-arity-clause-element-counts
+ "Map of clause-head-string -> expected element count, derived from the MBQL clause
+ registry at first use. Includes only `:tuple` clauses; variadic `:catn` / `:repeat`
+ clauses are excluded (their arity isn't fixed). Used by [[merge-trailing-options*]]
+ to detect a misplaced trailing options map.
+
+ Wrapped in `delay` so we don't pay the introspection cost at require time. If
+ introspecting an individual clause's schema throws, the exception is allowed to
+ propagate so a Malli reshape that breaks the walk surfaces immediately instead of
+ silently dropping that clause from the table."
+ (delay
+ (into {}
+ (keep (fn [tag]
+ (let [schema-name (mbql-clause/tag->registered-schema-name tag)
+ form (mr/registered-schema schema-name)]
+ (when-let [n (tuple-clause-element-count form)]
+ [(name tag) n]))))
+ (mbql-clause/registered-tags))))
+
+(defn- needs-trailing-options-merge?
+ "True when `node` is a fixed-arity tuple clause that the LLM wrote with one extra
+ element at the end, and that extra element is a map. See the pass docstring above
+ for the full condition."
+ [node]
+ (and (clause-like? node)
+ (>= (count node) 3)
+ (map? (nth node 1))
+ (map? (peek node))
+ (when-let [expected (get @fixed-arity-clause-element-counts (nth node 0))]
+ (= (count node) (inc expected)))))
+
+(defn- merge-trailing-options
+ "Merge the trailing map into the position-1 options (trailing keys win) and drop
+ the trailing element."
+ [node]
+ (let [head (nth node 0)
+ pos1-opts (nth node 1)
+ trailing (peek node)
+ middle (subvec node 2 (dec (count node)))
+ merged (merge pos1-opts trailing)]
+ (into [head merged] middle)))
+
+(defn- merge-trailing-options*
+ [form]
+ (walk/postwalk
+ (fn [node]
+ (if (needs-trailing-options-merge? node)
+ (merge-trailing-options node)
+ node))
+ form))
+
;;; ============================================================
;;; Pass 1.84 -- normalise alternative `case` / `if` argument shapes.
;;;
@@ -2336,6 +2439,7 @@
rewrite-operator-name-aliases*
rewrite-temporal-bucket-aliases*
rewrite-direction-aliases*
+ merge-trailing-options*
wrap-iso-date-bounds*
wrap-now-literals*
swap-between-bounds*
@@ -2358,6 +2462,8 @@
1.5. normalise `expressions:` shape - accept map form `{Name: clause, …}` or the
canonical sequential form, always output sequential with `lib/expression-name`
stamped into each clause's options from the map key when missing;
+ 1.88. merge a trailing extra options-map back into position-1 options on fixed-arity
+ tuple clauses (e.g. `[\"time-interval\" {} <expr> -1 \"month\" {\"include-current\" true}]`);
2. fill in missing `\"lib/type\"` markers on the query and stages;
3. rewrite inline aggregation expressions in `order-by` to aggregation references when
they match an aggregation in the same stage's `aggregation:` list (synthesising the
diff --git a/src/metabase/lib/schema/mbql_clause.cljc b/src/metabase/lib/schema/mbql_clause.cljc
index d48d53c8bba..92f1661e287 100644
--- a/src/metabase/lib/schema/mbql_clause.cljc
+++ b/src/metabase/lib/schema/mbql_clause.cljc
@@ -20,6 +20,13 @@
[tag]
(keyword "mbql.clause" (name tag)))
+(defn registered-tags
+ "Snapshot of every MBQL clause tag currently registered via [[define-mbql-clause]]
+ (e.g. `#{:starts-with :sum :count …}`). Returns a sorted set so iteration order is
+ deterministic."
+ []
+ @tag-registry)
+
(def ^:private invalid-clause-schema
[:fn {:error/message "not a known MBQL clause"} (constantly false)])
diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.clj
index b04e9428fe0..b7e64dbeaa9 100644
--- a/test/metabase/agent_lib/representations/repair_test.clj
+++ b/test/metabase/agent_lib/representations/repair_test.clj
@@ -2658,3 +2658,134 @@
{"lib/type" "mbql.stage/mbql"
"filters" [[">" {} ["field" {} "count"] 10]]}]}]
(is (some? (repair/repair trivial-mp q))))))
+
+;;; ============================================================
+;;; Pass 1.88 - merge trailing options-map into position-1 opts
+;;; ============================================================
+
+(deftest ^:parallel merge-trailing-options-time-interval-test
+ (testing (str "BOT-1603: when the LLM puts a clause's options at the END of a fixed-arity\n"
+ "tuple clause instead of position 1, repair merges the trailing map into the\n"
+ "position-1 options and drops the trailing element. The canonical example is\n"
+ "`time-interval` with `{include-current true}` written as a 6th element.")
+ (let [bug ["time-interval" {}
+ ["field" {} ["Sample" "PUBLIC" "ORDERS" "CREATED_AT"]]
+ -1 "month" {"include-current" true}]
+ repaired (repair/repair trivial-mp bug)]
+ (is (= ["time-interval" {"include-current" true}
+ ["field" {} ["Sample" "PUBLIC" "ORDERS" "CREATED_AT"]]
+ -1 "month"]
+ repaired)))))
+
+(deftest ^:parallel merge-trailing-options-other-fixed-arity-test
+ (testing "the pass is generic, not time-interval-specific: works for any fixed-arity tuple"
+ (testing "during (5-tuple)"
+ (is (= ["during" {"foo" "bar"}
+ ["field" {} ["S" "P" "T" "C"]]
+ "2024-01-01" "day"]
+ (repair/repair trivial-mp
+ ["during" {}
+ ["field" {} ["S" "P" "T" "C"]]
+ "2024-01-01" "day" {"foo" "bar"}]))))
+ (testing "power (4-tuple)"
+ (is (= ["power" {"lib/uuid" "u"} 2 3]
+ (repair/repair trivial-mp
+ ["power" {} 2 3 {"lib/uuid" "u"}]))))
+ (testing "regex-match-first (4-tuple)"
+ (is (= ["regex-match-first" {"case-sensitive" false}
+ ["field" {} ["S" "P" "T" "C"]] "x.*"]
+ (repair/repair trivial-mp
+ ["regex-match-first" {}
+ ["field" {} ["S" "P" "T" "C"]]
+ "x.*" {"case-sensitive" false}]))))))
+
+(deftest ^:parallel merge-trailing-options-nested-in-filters-test
+ (testing (str "the misplaced trailing options can be nested arbitrarily deep - repair's\n"
+ "postwalk reaches a time-interval clause nested inside `and` inside the\n"
+ "stage's filters: block.")
+ (let [q {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "filters" [["and" {}
+ ["=" {} ["field" {} ["Sample" "PUBLIC" "ORDERS" "STATUS"]] "x"]
+ ["time-interval" {}
+ ["field" {} ["Sample" "PUBLIC" "ORDERS" "CREATED_AT"]]
+ -1 "month" {"include-current" true}]]]}]}
+ out (repair/repair trivial-mp q)
+ ti (get-in out ["stages" 0 "filters" 0 3])]
+ (is (= ["time-interval" {"include-current" true}
+ ["field" {} ["Sample" "PUBLIC" "ORDERS" "CREATED_AT"]]
+ -1 "month"]
+ ti)))))
+
+(deftest ^:parallel merge-trailing-options-trailing-keys-win-test
+ (testing (str "when both position-1 opts and the trailing map carry content, trailing keys\n"
+ "win on conflict. Rationale: the trailing map is where the LLM wrote\n"
+ "deliberate content; position 1 is almost always `{}`.")
+ (let [bug ["time-interval" {"include-current" false "lib/uuid" "stays"}
+ ["field" {} ["S" "P" "T" "C"]]
+ -1 "month" {"include-current" true}]
+ repaired (repair/repair trivial-mp bug)]
+ (is (= ["time-interval" {"include-current" true "lib/uuid" "stays"}
+ ["field" {} ["S" "P" "T" "C"]]
+ -1 "month"]
+ repaired)))))
+
+(deftest ^:parallel merge-trailing-options-no-op-on-correct-arity-test
+ (testing "well-formed clause is unchanged"
+ (let [ti ["time-interval" {"include-current" true}
+ ["field" {} ["S" "P" "T" "C"]]
+ -1 "month"]]
+ (is (= ti (repair/repair trivial-mp ti))))))
+
+(deftest ^:parallel merge-trailing-options-skips-variadic-test
+ (testing (str "variadic clauses (`and`, `or`, `=`, `in`, `case`, ...) use `:catn` and are\n"
+ "excluded from the registry-derived fixed-arity map. A trailing map on a\n"
+ "variadic clause might be a legitimate arg (or just bad input the schema will\n"
+ "reject) - we don't second-guess.")
+ (let [bug ["and" {}
+ [">" {} ["field" {} ["S" "P" "T" "X"]] 10]
+ [">" {} ["field" {} ["S" "P" "T" "Y"]] 20]
+ {"trailing" "stays"}]]
+ (is (= bug (repair/repair trivial-mp bug))))))
+
+(deftest ^:parallel merge-trailing-options-skips-off-by-two-test
+ (testing (str "the pass only fires when count is exactly `expected + 1`. Two extra\n"
+ "elements is too ambiguous - leave it for the schema validator to reject.")
+ (let [bug ["time-interval" {}
+ ["field" {} ["S" "P" "T" "C"]]
+ -1 "month" {"include-current" true} {"extra" 1}]]
+ (is (= bug (repair/repair trivial-mp bug))))))
+
+(deftest ^:parallel merge-trailing-options-skips-unknown-clause-test
+ (testing "clauses whose head is not in the fixed-arity registry are left alone"
+ (let [bug ["totally-made-up-op" {} "arg1" {"trailing" "map"}]]
+ (is (= bug (repair/repair trivial-mp bug))))))
+
+(deftest ^:parallel merge-trailing-options-idempotent-test
+ (testing "repair(repair(q)) = repair(q)"
+ (let [bug ["time-interval" {}
+ ["field" {} ["S" "P" "T" "C"]]
+ -1 "month" {"include-current" true}]
+ once (repair/repair trivial-mp bug)
+ twice (repair/repair trivial-mp once)]
+ (is (= once twice)))))
+
+(deftest ^:parallel fixed-arity-clause-counts-populated-test
+ (testing (str "registry-derived fixed-arity map is populated and contains the well-known\n"
+ "entries. Catches accidents like the schema namespaces not being loaded at the\n"
+ "time the namespace initializes the delay.")
+ (let [counts (force @#'repair/fixed-arity-clause-element-counts)]
+ (is (pos? (count counts)))
+ (testing "well-known fixed-arity clauses are in the map with correct counts"
+ (is (= 5 (get counts "time-interval")))
+ (is (= 5 (get counts "during")))
+ (is (= 7 (get counts "relative-time-interval")))
+ (is (= 3 (get counts "segment")))
+ (is (= 3 (get counts "sum")))
+ (is (= 4 (get counts "power"))))
+ (testing "variadic clauses are excluded"
+ (is (not (contains? counts "and")))
+ (is (not (contains? counts "or")))
+ (is (not (contains? counts "case")))
+ (is (not (contains? counts "coalesce")))))))